commit f213ec89765936f8d36a71674c92a605834810fc
Author: wehub-resource-sync <resource-sync@wehub.local>
Date:   Mon Jul 13 12:24:33 2026 +0800

    chore: import upstream snapshot with attribution

diff --git a/.buildkite/README.md b/.buildkite/README.md
new file mode 100644
index 0000000..73ccfde
--- /dev/null
+++ b/.buildkite/README.md
@@ -0,0 +1,15 @@
+# Comprehensive Tests
+
+An end-to-end integration suite for LMCache & vLLM latest branch.
+
+## Layout
+
+- **Scripts**: `scripts/vllm-integration-tests.sh`
+- **Configs**: `configs/`
+- **Pipeline**: `pipelines/comprehensive-tests.yml`
+
+## Prepare
+
+1. Add your YAMLs to `configs/` (e.g. `local_cpu.yaml`, `local_disk.yaml`).
+
+2. Add the filenames to `cases/comprehensive-cases.txt`.
diff --git a/.buildkite/cases/comprehensive-cases.txt b/.buildkite/cases/comprehensive-cases.txt
new file mode 100644
index 0000000..8ca9964
--- /dev/null
+++ b/.buildkite/cases/comprehensive-cases.txt
@@ -0,0 +1,11 @@
+local_cpu.yaml
+local_cpu_mla.yaml
+local_disk.yaml
+pd.yaml
+multi_device.yaml
+async.yaml
+p2p.yaml
+layerwise.yaml
+local_cpu_with_v3.yaml
+local_disk_with_v3.yaml
+p2p_with_v3.yaml
\ No newline at end of file
diff --git a/.buildkite/cases/integration-cases.txt b/.buildkite/cases/integration-cases.txt
new file mode 100644
index 0000000..1cc79cb
--- /dev/null
+++ b/.buildkite/cases/integration-cases.txt
@@ -0,0 +1 @@
+dummy.yaml
diff --git a/.buildkite/configs/async.yaml b/.buildkite/configs/async.yaml
new file mode 100644
index 0000000..df244dd
--- /dev/null
+++ b/.buildkite/configs/async.yaml
@@ -0,0 +1,32 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+  sleep-time-after-warmup: 20
+  num-documents: 20
+  repeat-count: 1
+  hit-miss-ratio: 2:2
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=False"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=70"
+    - "LMCACHE_MAX_LOCAL_DISK_SIZE=70"
+    - "LMCACHE_LOCAL_DISK=\"file:///local/end-to-end-tests/local/\""
+    - "LMCACHE_ENABLE_ASYNC_LOADING=True"
+    - "LMCACHE_EXTRA_CONFIG={\"lookup_backoff_time\": 0.01, \"use_odirect\": True}"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=False"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.1-8B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/dummy.yaml b/.buildkite/configs/dummy.yaml
new file mode 100644
index 0000000..c266453
--- /dev/null
+++ b/.buildkite/configs/dummy.yaml
@@ -0,0 +1,22 @@
+workload: 
+  type: dummy
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=True"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--max-model-len"
+    - "1024"
+    - "--gpu-memory-utilization"
+    - "0.35"
+    - "--load-format"
+    - "dummy"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
\ No newline at end of file
diff --git a/.buildkite/configs/layerwise.yaml b/.buildkite/configs/layerwise.yaml
new file mode 100644
index 0000000..ed41144
--- /dev/null
+++ b/.buildkite/configs/layerwise.yaml
@@ -0,0 +1,26 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=True"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+    - "LMCACHE_USE_LAYERWISE=true"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+    - "--compilation-config" 
+    - "{\"cudagraph_mode\":\"PIECEWISE\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/lmcache_configs/local_cpu_mla.yaml b/.buildkite/configs/lmcache_configs/local_cpu_mla.yaml
new file mode 100644
index 0000000..8acd238
--- /dev/null
+++ b/.buildkite/configs/lmcache_configs/local_cpu_mla.yaml
@@ -0,0 +1,15 @@
+# LMCache Configuration File
+# This replaces the individual environment variables for cleaner configuration
+
+# Basic configurations
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 5
+
+internal_api_server_enabled: true
+internal_api_server_socket_path_prefix: "/tmp/lmcache_internal_api_server/socket"
+internal_api_server_include_index_list: [1]
+
+extra_config:
+  save_only_first_rank: true
+  first_rank_max_local_cpu_size: 5
diff --git a/.buildkite/configs/local_cpu.yaml b/.buildkite/configs/local_cpu.yaml
new file mode 100644
index 0000000..6727480
--- /dev/null
+++ b/.buildkite/configs/local_cpu.yaml
@@ -0,0 +1,23 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=True"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/local_cpu_mla.yaml b/.buildkite/configs/local_cpu_mla.yaml
new file mode 100644
index 0000000..a48f287
--- /dev/null
+++ b/.buildkite/configs/local_cpu_mla.yaml
@@ -0,0 +1,30 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+
+docker:
+  env:
+    - "LMCACHE_CONFIG_FILE=/etc/lmcache/local_cpu_mla.yaml"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  gpu_count: 2
+
+vllm:
+  model: "deepseek-ai/DeepSeek-V2-Lite-Chat"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - '{"kv_connector":"LMCacheConnectorV1Dynamic","kv_role":"kv_both","kv_connector_module_path":"lmcache.integration.vllm.lmcache_connector_v1","kv_connector_extra_config":{"discard_partial_chunks":false}}'
+    - "--tensor-parallel-size"
+    - "2"
+    - "--block-size"
+    - "64"
+    - "--kv-cache-dtype"
+    - "fp8_e4m3"
+    - "--quantization"
+    - "fp8"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/local_cpu_with_v3.yaml b/.buildkite/configs/local_cpu_with_v3.yaml
new file mode 100644
index 0000000..d5592ee
--- /dev/null
+++ b/.buildkite/configs/local_cpu_with_v3.yaml
@@ -0,0 +1,25 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+  expected-latency-gain: true
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=True"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+    - "LMCACHE_USE_GPU_CONNECTOR_V3=True"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/local_disk.yaml b/.buildkite/configs/local_disk.yaml
new file mode 100644
index 0000000..0e5162c
--- /dev/null
+++ b/.buildkite/configs/local_disk.yaml
@@ -0,0 +1,26 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+  sleep-time-after-warmup: 20
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=False"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=10"
+    - "LMCACHE_MAX_LOCAL_DISK_SIZE=10"
+    - "LMCACHE_LOCAL_DISK=\"file:///local/end-to-end-tests/local/\""
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/local_disk_with_v3.yaml b/.buildkite/configs/local_disk_with_v3.yaml
new file mode 100644
index 0000000..0bc380a
--- /dev/null
+++ b/.buildkite/configs/local_disk_with_v3.yaml
@@ -0,0 +1,27 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+  sleep-time-after-warmup: 20
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=False"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=10"
+    - "LMCACHE_MAX_LOCAL_DISK_SIZE=10"
+    - "LMCACHE_LOCAL_DISK=\"file:///local/end-to-end-tests/local/\""
+    - "LMCACHE_USE_GPU_CONNECTOR_V3=True"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/multi_device.yaml b/.buildkite/configs/multi_device.yaml
new file mode 100644
index 0000000..9bb5bf9
--- /dev/null
+++ b/.buildkite/configs/multi_device.yaml
@@ -0,0 +1,26 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 20
+
+docker:
+  env:
+    - "LMCACHE_CHUNK_SIZE=256"
+    - "LMCACHE_LOCAL_CPU=True"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+    - "LMCACHE_GDS_PATH=/tmp/"
+    - "LMCACHE_GDS_BUFFER_SIZE=4096"
+    - "LMCACHE_EXTRA_CONFIG={\"use_direct_io\": true}"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+
+vllm:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/configs/p2p.yaml b/.buildkite/configs/p2p.yaml
new file mode 100644
index 0000000..f66010f
--- /dev/null
+++ b/.buildkite/configs/p2p.yaml
@@ -0,0 +1,69 @@
+workload:
+  type: long_doc_qa
+  num-documents: 20
+  max-inflight-requests: 1
+  repeat-count: 1
+
+feature:
+  type: p2p
+
+docker1:
+  env:
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=60"
+    - "LMCACHE_ENABLE_ASYNC_LOADING=True"
+    - "LMCACHE_ENABLE_P2P=True"
+    - "LMCACHE_P2P_HOST=localhost"
+    - "LMCACHE_P2P_INIT_PORTS=8200"
+    - "LMCACHE_P2P_LOOKUP_PORTS=8201"
+    - "LMCACHE_TRANSFER_CHANNEL=nixl"
+    - "LMCACHE_ENABLE_CONTROLLER=True"
+    - "LMCACHE_LMCACHE_INSTANCE_ID=lmcache_instance_1"
+    - "LMCACHE_LMCACHE_WORKER_PORTS=8500"
+    - "LMCACHE_EXTRA_CONFIG={\"lookup_backoff_time\": 0.001}"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=False"
+    - "PYTHONHASHSEED=123"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  pull-port: 8300
+  reply-port: 8400
+
+docker2:
+  env:
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=60"
+    - "LMCACHE_ENABLE_ASYNC_LOADING=True"
+    - "LMCACHE_ENABLE_P2P=True"
+    - "LMCACHE_P2P_HOST=localhost"
+    - "LMCACHE_P2P_INIT_PORTS=8202"
+    - "LMCACHE_P2P_LOOKUP_PORTS=8203"
+    - "LMCACHE_TRANSFER_CHANNEL=nixl"
+    - "LMCACHE_ENABLE_CONTROLLER=True"
+    - "LMCACHE_LMCACHE_INSTANCE_ID=lmcache_instance_2"
+    - "LMCACHE_LMCACHE_WORKER_PORTS=8501"
+    - "LMCACHE_EXTRA_CONFIG={\"lookup_backoff_time\": 0.001}"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=False"
+    - "PYTHONHASHSEED=123"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  pull-port: 8300
+  reply-port: 8400
+
+vllm1:
+  model: "meta-llama/Llama-3.1-8B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+vllm2:
+  model: "meta-llama/Llama-3.1-8B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - warmup_round_time_per_prompt
diff --git a/.buildkite/configs/p2p_with_v3.yaml b/.buildkite/configs/p2p_with_v3.yaml
new file mode 100644
index 0000000..708e2ad
--- /dev/null
+++ b/.buildkite/configs/p2p_with_v3.yaml
@@ -0,0 +1,71 @@
+workload:
+  type: long_doc_qa
+  num-documents: 20
+  max-inflight-requests: 1
+  repeat-count: 1
+
+feature:
+  type: p2p
+
+docker1:
+  env:
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=60"
+    - "LMCACHE_ENABLE_ASYNC_LOADING=True"
+    - "LMCACHE_ENABLE_P2P=True"
+    - "LMCACHE_P2P_HOST=localhost"
+    - "LMCACHE_P2P_INIT_PORTS=8200"
+    - "LMCACHE_P2P_LOOKUP_PORTS=8201"
+    - "LMCACHE_TRANSFER_CHANNEL=nixl"
+    - "LMCACHE_ENABLE_CONTROLLER=True"
+    - "LMCACHE_LMCACHE_INSTANCE_ID=lmcache_instance_1"
+    - "LMCACHE_LMCACHE_WORKER_PORTS=8500"
+    - "LMCACHE_EXTRA_CONFIG={\"lookup_backoff_time\": 0.001}"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=False"
+    - "PYTHONHASHSEED=123"
+    - "LMCACHE_USE_GPU_CONNECTOR_V3=True"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  pull-port: 8300
+  reply-port: 8400
+
+docker2:
+  env:
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=60"
+    - "LMCACHE_ENABLE_ASYNC_LOADING=True"
+    - "LMCACHE_ENABLE_P2P=True"
+    - "LMCACHE_P2P_HOST=localhost"
+    - "LMCACHE_P2P_INIT_PORTS=8202"
+    - "LMCACHE_P2P_LOOKUP_PORTS=8203"
+    - "LMCACHE_TRANSFER_CHANNEL=nixl"
+    - "LMCACHE_ENABLE_CONTROLLER=True"
+    - "LMCACHE_LMCACHE_INSTANCE_ID=lmcache_instance_2"
+    - "LMCACHE_LMCACHE_WORKER_PORTS=8501"
+    - "LMCACHE_EXTRA_CONFIG={\"lookup_backoff_time\": 0.001}"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=False"
+    - "PYTHONHASHSEED=123"
+    - "LMCACHE_USE_GPU_CONNECTOR_V3=True"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  pull-port: 8300
+  reply-port: 8400
+
+vllm1:
+  model: "meta-llama/Llama-3.1-8B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+vllm2:
+  model: "meta-llama/Llama-3.1-8B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_both\"}"
+
+checking-fields:
+  - warmup_round_time_per_prompt
diff --git a/.buildkite/configs/pd.yaml b/.buildkite/configs/pd.yaml
new file mode 100644
index 0000000..31e2244
--- /dev/null
+++ b/.buildkite/configs/pd.yaml
@@ -0,0 +1,74 @@
+workload:
+  type: long_doc_qa
+  max-inflight-requests: 1
+  repeat-count: 1
+  completion: true
+  num-documents: 20
+  document-length: 16382
+
+feature:
+  type: pd
+
+docker-prefiller:
+  env:
+    # Force vLLM Model Runner V1: MRV2 (enabled by default for Llama/Mistral
+    # dense models in vLLM nightly, see vllm-project/vllm#43458) is incompatible
+    # with KV cache connectors and hangs the PD path. Remove once MRV2 supports
+    # connectors / auto-falls back to MRV1.
+    - "VLLM_USE_V2_MODEL_RUNNER=0"
+    - "LMCACHE_LOCAL_CPU=False"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+    - "LMCACHE_ENABLE_PD=True"
+    - "LMCACHE_TRANSFER_CHANNEL=nixl"
+    - "LMCACHE_PD_ROLE=sender"
+    - "LMCACHE_PD_PROXY_HOST=localhost"
+    - "LMCACHE_PD_BUFFER_SIZE=1073741824" # 1GB
+    - "LMCACHE_PD_BUFFER_DEVICE=cuda"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=True"
+    - "PYTHONHASHSEED=0"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  proxy-port: 7500
+
+docker-decoder:
+  env:
+    # Force vLLM Model Runner V1: MRV2 (enabled by default for Llama/Mistral
+    # dense models in vLLM nightly, see vllm-project/vllm#43458) is incompatible
+    # with KV cache connectors and hangs the PD path. Remove once MRV2 supports
+    # connectors / auto-falls back to MRV1.
+    - "VLLM_USE_V2_MODEL_RUNNER=0"
+    - "LMCACHE_LOCAL_CPU=False"
+    - "LMCACHE_MAX_LOCAL_CPU_SIZE=0"
+    - "LMCACHE_ENABLE_PD=True"
+    - "LMCACHE_TRANSFER_CHANNEL=nixl"
+    - "LMCACHE_PD_ROLE=receiver"
+    - "LMCACHE_PD_PEER_HOST=localhost"
+    - "LMCACHE_PD_BUFFER_SIZE=2147483648" # 2GB
+    - "LMCACHE_PD_BUFFER_DEVICE=cuda"
+    - "LMCACHE_SAVE_UNFULL_CHUNK=True"
+    - "PYTHONHASHSEED=0"
+    - "LMCACHE_INTERNAL_API_SERVER_ENABLED=True"
+    - "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/socket"
+  init-port: 7300
+  alloc-port: 7400
+
+vllm-prefiller:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_producer\",\"kv_connector_extra_config\": {\"discard_partial_chunks\": false, \"lmcache_rpc_port\": \"producer1\"}}"
+
+vllm-decoder:
+  model: "meta-llama/Llama-3.2-1B-Instruct"
+  args:
+    - "--load-format"
+    - "dummy"
+    - "--no-enable-prefix-caching"
+    - "--kv-transfer-config"
+    - "{\"kv_connector\":\"LMCacheConnectorV1\",\"kv_role\":\"kv_consumer\",\"kv_connector_extra_config\": {\"discard_partial_chunks\": false, \"lmcache_rpc_port\": \"consumer1\", \"skip_last_n_tokens\": 1}}"
+
+checking-fields:
+  - query_round_time_per_prompt
diff --git a/.buildkite/correctness/README.md b/.buildkite/correctness/README.md
new file mode 100644
index 0000000..dfa14ac
--- /dev/null
+++ b/.buildkite/correctness/README.md
@@ -0,0 +1,52 @@
+# Correctness Test
+
+This is a E2E testing suite for whether having a KV pass through LMCache from vllm (storing and loading) will degrade the accuracy of a transformer. 
+
+Unit tests do not suffice in going from request to response and passing through LMCache. We use offline serving
+for this testing suite because the API Server of vllm is assumed to be unproblematic. 
+
+## Setup 
+
+We use the [Measuring Massive Multitask Language Understanding](https://arxiv.org/abs/2009.03300) multiple choice dataset downloaded as a compressed tarball in `data.tar.xz`
+
+The following 3 options are viable:
+A. Disable prefix caching on vllm to only use lmcache
+B. Use lmcache centralized remote server
+C. Use lmcache p2p sharing
+
+We choose option A to keep the CI server lightweight (only 2x L4s needed). 
+
+We test one small model for each Attention Architecture. Currently dense/standard attention will use `meta-llama/Llama-3.1-8B-Instruct` and 
+MLA (multi-head latent attention) will use `deepseek-ai/DeepSeek-V2-Lite` with tensor parallel 2. We do not care about the objective accuracy on the MMLU benchmark but only on any differential that appears from using LMCache. 
+
+## CI Agent Pre Set-up
+
+To ensure the speed of the MMLU Correctness tests, please conduct the following set up on your runner beforehand (only need to do once and `setup.sh` will renew your environment afterwards). 
+
+1. Create a virtual environment at `~/correctness_venv`
+
+```bash
+pip install pandas
+```
+
+2. Please run the following commands (these will be run by `setup.sh` every time):
+```bash
+cd ~
+mkdir correctness_repositories
+cd correctness_repositories
+git clone https://github.com/LMCache/LMCache.git
+git clone https://github.com/vllm-project/vllm.git
+cd LMCache
+pip install -e .
+cd ../vllm
+pip install -e . 
+```
+
+Explanation: "pull" upstream code in this CI suite by pulling the latest upstream default branch
+and let the editable virtual environment update the latest code. This allows a little bit of pre-setup to greatly optimize every run afterwards. 
+
+## Directory Structure
+`single-mmlu-test.py`
+
+The MMLU question dataset will be sent to this single endpoint and accuracy will be evaluated (correct answers are included
+in the dataset). When LMCache is used, queries are sent twice. 
\ No newline at end of file
diff --git a/.buildkite/correctness/async_request.py b/.buildkite/correctness/async_request.py
new file mode 100755
index 0000000..e1bfa1c
--- /dev/null
+++ b/.buildkite/correctness/async_request.py
@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import asyncio
+import copy
+import json
+import logging
+import os
+import time
+import traceback
+
+# Third Party
+from tqdm import tqdm
+import aiohttp
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+
+async def make_request(session, payload: tuple, args):
+    endpoint = args.endpoint
+    output_file = args.output_file
+    obj_name, payload = payload
+    headers = {
+        "Authorization": f"Bearer {os.getenv('API_KEY', '')}",
+        "Content-Type": "application/json",
+    }
+    try:
+        async with session.post(
+            endpoint, json=payload, headers=headers, ssl=False
+        ) as response:
+            json_data = await response.json()
+            content = (
+                json_data.get("choices", [{}])[0].get("message", {}).get("content", "")
+            )
+            logger.info(content)
+            if json_data.get("id") is not None:
+                with open(output_file, "a") as f:
+                    f.write(f"{json_data.get('id')}:\n{content}\n")
+                if json_data.get("choices", [{}])[0].get("finish_reason", "") != "stop":
+                    with open(output_file.replace(".txt", "_length.txt"), "a") as f:
+                        f.write(f"{json_data.get('id')}:\n{content}\n")
+            return True, json_data
+    except Exception:
+        logger.error(f"Request failed (Object name: {obj_name})")
+        traceback.print_exc()
+        return False, None
+
+
+async def process_requests(payloads: dict, args):
+    semaphore = asyncio.Semaphore(args.max_concurrency)
+
+    async def sem_task(session, payload: tuple, args):
+        async with semaphore:
+            return await make_request(session, payload, args)
+
+    timeout = aiohttp.ClientTimeout(total=6000)
+    connector = aiohttp.TCPConnector(limit=0)
+    async with aiohttp.ClientSession(timeout=timeout, connector=connector) as session:
+        tasks = [sem_task(session, payload, args) for payload in payloads.items()]
+
+        generated_token = []
+        for coro in tqdm(
+            asyncio.as_completed(tasks), total=len(tasks), desc="Requests Progress"
+        ):
+            success, content = await coro
+            if success:
+                generated_token.append(
+                    content.get("usage", {}).get("completion_tokens", 0)
+                )
+            else:
+                logger.error(f"Error: {content}")
+        logger.info(f"Total generated tokens: {sum(generated_token)}")
+
+
+def request_concurrency(requests: dict, args):
+    same_req = args.same_req
+    rid = args.rid
+    counts = args.counts
+    model = args.model
+    payloads = dict()
+    if same_req:
+        for index, request in requests.items():
+            if index == rid:
+                request.update({"model": model})
+                request.update({"stream": False})
+                request.update({"temperature": 0})
+                request.update({"request_id": index})
+                payloads[index] = request
+                for i in range(counts):
+                    payloads[i] = copy.deepcopy(payloads[index])
+                    payloads[i]["request_id"] = str(i)
+                break
+
+    else:
+        for index, request in requests.items():
+            request.update({"model": model})
+            request.update({"stream": False})
+            request.update({"temperature": 0})
+            request["request_id"] = index
+            payloads[index] = request
+
+    start = time.time()
+    asyncio.run(process_requests(payloads, args))
+    end = time.time()
+    logger.info(f"Total time: {end - start:.2f} seconds")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Concurrent request tester")
+
+    parser.add_argument(
+        "--model", type=str, default="Qwen3/Qwen3-32B", help="Model name"
+    )
+    parser.add_argument(
+        "--endpoint",
+        type=str,
+        required=True,
+        help="API endpoint, e.g. http://host:port/v1/chat/completions",
+    )
+    parser.add_argument(
+        "--request-number",
+        type=int,
+        default=500,
+        help="Number of requests to read from dataset",
+    )
+    parser.add_argument(
+        "--max-concurrency", type=int, default=128, help="Max concurrency"
+    )
+    parser.add_argument(
+        "--dataset_file", type=str, default="data.json", help="Dataset json file"
+    )
+    parser.add_argument(
+        "--output-file",
+        type=str,
+        default="result_output.txt",
+        help="Output result file prefix",
+    )
+    parser.add_argument(
+        "--same-req",
+        action="store_true",
+        help="Send the same rid request multiple times",
+    )
+    parser.add_argument(
+        "--rid", type=str, default="", help="The rid to repeat if same_req=True"
+    )
+    parser.add_argument(
+        "--counts", type=int, default=100, help="How many times to send the same rid"
+    )
+
+    args = parser.parse_args()
+
+    # --- load dataset ---
+    with open(args.dataset_file, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    data = dict(list(data.items())[: args.request_number])
+
+    print(f"Loaded {len(data)} requests.")
+
+    # --- call your function ---
+    request_concurrency(data, args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.buildkite/correctness/compare_files.py b/.buildkite/correctness/compare_files.py
new file mode 100644
index 0000000..2c8635a
--- /dev/null
+++ b/.buildkite/correctness/compare_files.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import re
+
+
+def load_file(path):
+    data = {}
+    current_id = None
+    buffer = []
+
+    id_pattern = re.compile(r"chatcmpl-[a-zA-Z0-9\-_]+")
+
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line_strip = line.strip()
+            if id_pattern.search(line_strip):
+                if current_id is not None:
+                    data[current_id] = "\n".join(buffer).strip()
+                current_id = id_pattern.search(line_strip).group(0)
+                buffer = []
+            else:
+                buffer.append(line.rstrip())
+
+        if current_id is not None:
+            data[current_id] = "\n".join(buffer).strip()
+
+    return data
+
+
+def compare_files(file1, file2):
+    d1 = load_file(file1)
+    d2 = load_file(file2)
+
+    ids1 = set(d1.keys())
+    ids2 = set(d2.keys())
+
+    common = ids1 & ids2
+    only1 = ids1 - ids2
+    only2 = ids2 - ids1
+
+    same = []
+    diff = []
+
+    for cid in common:
+        if d1[cid] == d2[cid]:
+            same.append(cid)
+        else:
+            diff.append(cid)
+    print("====== Statistics ======")
+    print(f"Common IDs: {len(common)}")
+    print(f"Identical IDs: {len(same)}")
+    print(f"Different IDs: {len(diff)}")
+    print()
+    print("—— Identical IDs ——")
+    for cid in same:
+        print(cid)
+    print()
+    print("—— Different IDs ——")
+    for cid in diff:
+        print(cid)
+    print()
+    print("—— Only in File 1 ——")
+    for cid in only1:
+        print(cid)
+    print()
+    print("—— Only in File 2 ——")
+    for cid in only2:
+        print(cid)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Compare two result files.")
+    parser.add_argument("--file1", type=str, required=True, help="Path to first file.")
+    parser.add_argument("--file2", type=str, required=True, help="Path to second file.")
+
+    args = parser.parse_args()
+
+    file1 = args.file1
+    file2 = args.file2
+
+    compare_files(file1, file2)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.buildkite/correctness/mmlu-test.py b/.buildkite/correctness/mmlu-test.py
new file mode 100644
index 0000000..fb4e939
--- /dev/null
+++ b/.buildkite/correctness/mmlu-test.py
@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import json
+import os
+import time
+
+# Third Party
+from tqdm import tqdm
+from transformers import AutoTokenizer, set_seed
+
+# vLLM
+from vllm import LLM, SamplingParams
+from vllm.config import KVTransferConfig
+import numpy as np
+import pandas as pd
+
+# setting PYTHONHASHSEED derandomizes token chunking
+os.environ["PYTHONHASHSEED"] = "0"
+
+global tokenizer
+choices = ["A", "B", "C", "D"]
+
+
+# grab the idx'th row of the df and generate a prompt string
+# format of the MMLU csvs:
+# question,option_A,option_B,option_C,option_D,answer
+def prompt_string(df, idx, include_answer=True):
+    prompt = df.iloc[idx, 0]
+    k = df.shape[1] - 2  # number of columns - 2 (question and answer)
+    for i in range(k):
+        prompt += f"\n{choices[i]}. {df.iloc[idx, i + 1]}"
+    prompt += "\nAnswer:"
+    if include_answer:
+        prompt += f" {df.iloc[idx, k]}\n\n"
+    return prompt
+
+
+def evaluate(args, llm, subject, dev_df, test_df):
+    prompts, labels = [], []
+
+    shared_multi_shot_prefix = [
+        f'The following are multiple choice questions (with answers) \
+                    about {subject}. \
+                    You must respond with a single letter only. \
+                    Either "A", "B", "C", or "D". \
+                    Do not include any other text in your response. \n\n'
+    ]
+    shared_multi_shot_prefix_length = 0
+    for i in range(dev_df.shape[0]):
+        # the multi-shot examples should contain answers
+        shared_multi_shot_prefix.append(prompt_string(dev_df, i))
+
+        # Use plain list of token IDs, no torch tensors
+        token_ids = tokenizer(shared_multi_shot_prefix[-1], add_special_tokens=True)[
+            "input_ids"
+        ]
+        shared_multi_shot_prefix_length += len(token_ids)
+
+        if shared_multi_shot_prefix_length > 4000:
+            break
+
+    # all already have double newlines at the end
+    shared_multi_shot_prefix = "".join(shared_multi_shot_prefix)
+
+    for i in range(test_df.shape[0]):
+        # do NOT include the answer for the actual question
+        # we want the LLM to answer
+        query_prompt = prompt_string(test_df, i, include_answer=False)
+        prompt = f"{shared_multi_shot_prefix}\n\n{query_prompt}"
+        prompts.append(prompt)
+        label = test_df.iloc[i, test_df.shape[1] - 1]
+        labels.append(label)
+
+    # Create sampling params with deterministic settings
+    # (temperature=0, seed=42)
+    sampling_params = SamplingParams(
+        temperature=0,
+        max_tokens=2,
+        seed=42,
+        n=1,
+        stop=None,
+    )
+
+    # even though offline serving can batch all the prompts, we do them one at a time
+    # to keep the vllm scheduler deterministic
+    outputs = []
+    for prompt in prompts:
+        # if we use lmcache, we need to first populate the kv cache
+        if args.use_lmcache:
+            llm.generate(prompt, sampling_params)
+            time.sleep(0.5)
+        outputs.append(llm.generate(prompt, sampling_params))
+        time.sleep(0.5)
+
+    predictions = []
+    for output in outputs:
+        prediction = output.outputs[0].text
+        prediction_stripped = prediction.strip()
+        if prediction_stripped and prediction_stripped[0] in choices:
+            predictions.append(prediction_stripped[0])
+        else:
+            # Fallback: look for any A, B, C, D in the response
+            for char in prediction_stripped:
+                if char in ["A", "B", "C", "D"]:
+                    predictions.append(char)
+                    break
+            else:
+                predictions.append("A")  # Default fallback
+
+    accuracy = np.mean(np.array(predictions) == np.array(labels))
+    return accuracy
+
+
+def main(args):
+    global tokenizer
+    tokenizer = AutoTokenizer.from_pretrained(args.model)
+
+    ktc = None
+    if args.use_lmcache:
+        ktc = KVTransferConfig(
+            kv_connector="LMCacheConnectorV1",
+            kv_role="kv_both",
+        )
+    llm = LLM(
+        model=args.model,
+        max_model_len=8000,
+        gpu_memory_utilization=0.9,
+        kv_transfer_config=ktc,
+        tensor_parallel_size=2,
+        enable_prefix_caching=False,
+        enforce_eager=True,
+        trust_remote_code=True,
+    )
+
+    mmlu_files = os.listdir("data/test")
+    test_files = [f for f in mmlu_files if f.endswith("_test.csv")]
+    subjects = sorted([f.split("_test.csv")[0] for f in test_files])
+
+    accuracies = []
+    num_questions = []
+    output_dict = {}
+
+    for subject_raw in tqdm(
+        subjects[: args.number_of_subjects],
+        desc="Processing subjects",
+    ):
+        subject = " ".join(subject_raw.split("_"))
+        dev_df = pd.read_csv(
+            os.path.join("data/dev", subject_raw + "_dev.csv"),
+            header=None,
+        )
+        test_df = pd.read_csv(
+            os.path.join("data/test", subject_raw + "_test.csv"),
+            header=None,
+        )
+        accuracy = evaluate(args, llm, subject, dev_df, test_df)
+        accuracies.append(accuracy)
+        num_questions.append(len(test_df))
+        output_dict[subject_raw] = {
+            "accuracy": accuracy,
+            "num_questions": len(test_df),
+        }
+
+    total_accuracy = np.mean(accuracies)
+    total_num_questions = sum(num_questions)
+    output_dict["total"] = {
+        "accuracy": total_accuracy,
+        "num_questions": total_num_questions,
+    }
+
+    with open(args.result_file, "w") as f:
+        # output will be a jsonl file
+        for subject, value in output_dict.items():
+            f.write(json.dumps({subject: value}) + "\n")
+
+
+if __name__ == "__main__":
+    set_seed(42)  # some tokenizers may have randomness
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", type=str, required=True)
+    parser.add_argument("--number-of-subjects", type=int, default=25)
+    parser.add_argument("--use-lmcache", action="store_true", default=False)
+    args = parser.parse_args()
+    if args.use_lmcache:
+        args.result_file = args.model.split("/")[-1] + "-lmcache.jsonl"
+    else:
+        args.result_file = args.model.split("/")[-1] + "-baseline.jsonl"
+    main(args)
diff --git a/.buildkite/correctness/pipeline.correctness.yml b/.buildkite/correctness/pipeline.correctness.yml
new file mode 100644
index 0000000..24af1cb
--- /dev/null
+++ b/.buildkite/correctness/pipeline.correctness.yml
@@ -0,0 +1,16 @@
+steps:
+  - label: ":rocket: vLLM correctness"
+    key: "correctness"
+    timeout_in_minutes: 60
+    commands:
+      - |
+        set -euo pipefail
+
+        echo "[INFO] HOME: $HOME"
+        echo "[INFO] PWD: $PWD"
+
+        chmod +x .buildkite/scripts/vllm-correctness.sh
+        BUILD_ID="${BUILDKITE_BUILD_ID}" .buildkite/scripts/vllm-correctness.sh
+
+    artifact_paths:
+      - "build_${BUILDKITE_BUILD_ID}.log"
\ No newline at end of file
diff --git a/.buildkite/correctness/pipeline.mmlu.yml b/.buildkite/correctness/pipeline.mmlu.yml
new file mode 100644
index 0000000..392f296
--- /dev/null
+++ b/.buildkite/correctness/pipeline.mmlu.yml
@@ -0,0 +1,36 @@
+agents:
+  queue: "shaoting-gcp"
+
+steps:
+  - label: "Run MMLU KV Transfer Test"
+    command: |
+      set -euo pipefail
+      echo "Starting MMLU test"
+      echo "Running setup.sh"
+      bash setup.sh
+      
+      # buildkite agents start at the root of the Git checkout
+      cd .buildkite/correctness
+  
+      echo "Starting Dense KV Transfer Test with meta-llama/Llama-3.1-8B-Instruct"
+      # produces Llama-3.1-8B-Instruct-baseline.jsonl
+      python mmlu-test.py --model meta-llama/Llama-3.1-8B-Instruct --number-of-subjects 25
+      # produces Llama-3.1-8B-Instruct-lmcache.jsonl
+      python mmlu-test.py --model meta-llama/Llama-3.1-8B-Instruct --number-of-subjects 25 --use-lmcache
+  
+      echo "Starting MLA KV Transfer Test with deepseek-ai/DeepSeek-V2-Lite"
+      # produces DeepSeek-V2-Lite-baseline.jsonl
+      python mmlu-test.py --model deepseek-ai/DeepSeek-V2-Lite --number-of-subjects 25
+      # produces DeepSeek-V2-Lite-lmcache.jsonl
+      python mmlu-test.py --model deepseek-ai/DeepSeek-V2-Lite --number-of-subjects 25 --use-lmcache
+  
+      echo "Summarizing Results"
+      # the summarize-results.py will look for jsonl files with the same techniqiue as the mmlu-test.py script
+      # which is with args.model.split("/")[-1]
+      python summarize-results.py meta-llama/Llama-3.1-8B-Instruct deepseek-ai/DeepSeek-V2-Lite
+  
+      # this produces correctness-summary.txt
+      buildkite-agent artifact upload correctness-summary.txt
+
+    artifact_paths:
+      - correctness-summary.txt
diff --git a/.buildkite/correctness/setup.sh b/.buildkite/correctness/setup.sh
new file mode 100644
index 0000000..c328e98
--- /dev/null
+++ b/.buildkite/correctness/setup.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+
+# buildkite agents start at the root of the Git checkout
+
+cd .buildkite/correctness
+
+unxz data.tar.xz
+tar xf data.tar
+
+# see README.md for pre-configuring your CI runner
+source ~/correctness_venv/bin/activate
+cd ~/correctness_repositories/LMCache
+git pull origin dev
+cd ~/correctness_repositories/vllm
+git pull origin main
diff --git a/.buildkite/correctness/sharegpt2openai.py b/.buildkite/correctness/sharegpt2openai.py
new file mode 100644
index 0000000..90a498a
--- /dev/null
+++ b/.buildkite/correctness/sharegpt2openai.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import json
+
+VLLM_TEMPLATE = {
+    "model": "Qwen3/Qwen3-32B",
+    "frequency_penalty": 0.0,
+    "logit_bias": None,
+    "logprobs": False,
+    "top_logprobs": 0,
+    "max_tokens": 2048,
+    "max_completion_tokens": 2048,
+    "n": 1,
+    "presence_penalty": 0.0,
+    "response_format": None,
+    "seed": None,
+    "stop": [],
+    "stream": True,
+    "stream_options": None,
+    "temperature": 0.01,
+    "top_p": 1.0,
+    "tools": None,
+    "tool_choice": "none",
+    "reasoning_effort": None,
+    "include_reasoning": True,
+    "parallel_tool_calls": False,
+    "user": None,
+    "best_of": None,
+    "use_beam_search": False,
+    "top_k": -1,
+    "min_p": None,
+    "repetition_penalty": 1.0,
+    "length_penalty": 1.0,
+    "stop_token_ids": [],
+    "include_stop_str_in_output": False,
+    "ignore_eos": False,
+    "min_tokens": 0,
+    "skip_special_tokens": True,
+    "spaces_between_special_tokens": True,
+    "priority": 0,
+    "truncate_prompt_tokens": None,
+    "prompt_logprobs": None,
+    "allowed_token_ids": None,
+    "bad_words": [],
+    "order": "routine",
+    "lora_type": None,
+    "reasoning": False,
+    "echo": False,
+    "add_generation_prompt": True,
+    "continue_final_message": False,
+    "add_special_tokens": False,
+    "documents": None,
+    "chat_template": None,
+    "chat_template_kwargs": {"enable_thinking": False},
+    "mm_processor_kwargs": None,
+    "guided_json": None,
+    "guided_regex": None,
+    "guided_choice": None,
+    "guided_grammar": None,
+    "structural_tag": None,
+    "guided_decoding_backend": None,
+    "guided_whitespace_pattern": None,
+    "kv_transfer_params": None,
+    "vllm_xargs": None,
+}
+
+
+def convert_sharegpt_to_vllm(input_path, output_path):
+    with open(input_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    output = {}
+
+    for item in data:
+        conv = item["conversations"]
+
+        # # Delete the gpt's response at the end
+        if len(conv) > 0 and conv[-1]["from"] == "gpt":
+            conv = conv[:-1]
+
+        messages = []
+        for c in conv:
+            role = "user" if c["from"] == "human" else "assistant"
+            content = c["value"]
+            messages.append({"role": role, "content": content})
+
+        file_key = f"{item['id']}"
+
+        out_entry = VLLM_TEMPLATE.copy()
+        out_entry["messages"] = messages
+
+        output[file_key] = out_entry
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(output, f, ensure_ascii=False, indent=2)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert ShareGPT JSON dataset to vLLM format."
+    )
+    parser.add_argument(
+        "--input",
+        "-i",
+        type=str,
+        required=True,
+        help="Path to the input ShareGPT JSON file.",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        required=True,
+        help="Path to the output vLLM JSON file.",
+    )
+
+    args = parser.parse_args()
+
+    convert_sharegpt_to_vllm(args.input, args.output)
+    print(f"Converted {args.input} -> {args.output}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.buildkite/correctness/summarize-results.py b/.buildkite/correctness/summarize-results.py
new file mode 100644
index 0000000..46539e5
--- /dev/null
+++ b/.buildkite/correctness/summarize-results.py
@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict, List, Tuple
+import json
+import os
+import sys
+
+
+def load_jsonl_file(filepath: str) -> Dict[str, Dict[str, float]]:
+    """Load a JSONL file and return a dictionary of results."""
+    results: dict[str, dict[str, float]] = {}
+
+    if not os.path.exists(filepath):
+        print(f"Warning: File {filepath} not found")
+        return results
+
+    with open(filepath, "r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                try:
+                    data = json.loads(line)
+                    results.update(data)
+                except json.JSONDecodeError:
+                    print(f"Error parsing line in {filepath}: {line}")
+                    continue
+
+    return results
+
+
+def compare_results(
+    baseline_results: Dict, lmcache_results: Dict
+) -> Tuple[List[Tuple], float, float]:
+    """Compare baseline and lmcache results, return comparison data and totals."""
+    comparisons = []
+    baseline_total_correct = 0
+    baseline_total_questions = 0
+    lmcache_total_correct = 0
+    lmcache_total_questions = 0
+
+    # Get all subjects (excluding 'total' for now)
+    all_subjects = set(baseline_results.keys()) | set(lmcache_results.keys())
+    all_subjects.discard("total")  # Handle total separately
+
+    # Sort subjects alphabetically
+    for subject in sorted(all_subjects):
+        baseline_data = baseline_results.get(
+            subject, {"accuracy": 0.0, "num_questions": 0}
+        )
+        lmcache_data = lmcache_results.get(
+            subject, {"accuracy": 0.0, "num_questions": 0}
+        )
+
+        baseline_acc = baseline_data["accuracy"]
+        lmcache_acc = lmcache_data["accuracy"]
+        difference = lmcache_acc - baseline_acc
+
+        # Use the number of questions from whichever dataset has the subject
+        num_questions = max(
+            baseline_data["num_questions"], lmcache_data["num_questions"]
+        )
+
+        comparisons.append(
+            (subject, baseline_acc, lmcache_acc, difference, num_questions)
+        )
+
+        # Accumulate totals
+        baseline_total_correct += baseline_acc * num_questions
+        baseline_total_questions += num_questions
+        lmcache_total_correct += lmcache_acc * num_questions
+        lmcache_total_questions += num_questions
+
+    # Calculate overall accuracies
+    baseline_total_acc = (
+        baseline_total_correct / baseline_total_questions
+        if baseline_total_questions > 0
+        else 0
+    )
+    lmcache_total_acc = (
+        lmcache_total_correct / lmcache_total_questions
+        if lmcache_total_questions > 0
+        else 0
+    )
+
+    return comparisons, baseline_total_acc, lmcache_total_acc
+
+
+def format_model_report(
+    model_name: str,
+    model_short_name: str,
+    comparisons: List[Tuple],
+    baseline_total: float,
+    lmcache_total: float,
+) -> str:
+    """Format a single model's comparison report."""
+    report = []
+    report.append("=" * 80)
+    report.append(f"MODEL: {model_name}")
+    report.append("=" * 80)
+    report.append("")
+
+    # Header
+    report.append(
+        f"{'Subject':<35} \
+        {'Baseline':<12} \
+        {'LMCache':<12} \
+        {'Difference':<12} \
+        {'Questions':<10}"
+    )
+    report.append("-" * 80)
+
+    # Subject comparisons
+    for subject, baseline_acc, lmcache_acc, difference, num_questions in comparisons:
+        report.append(
+            f"{subject:<35} \
+            {baseline_acc:<12.4f} \
+            {lmcache_acc:<12.4f} \
+            {difference:<12.4f} \
+            {num_questions:<10}"
+        )
+
+    # Totals
+    total_difference = lmcache_total - baseline_total
+    report.append("-" * 80)
+    report.append(
+        f"{'TOTAL':<35} \
+        {baseline_total:<12.4f} \
+        {lmcache_total:<12.4f} \
+        {total_difference:<12.4f}"
+    )
+    report.append("")
+
+    # Summary
+    report.append("SUMMARY:")
+    report.append(f"  Baseline Total Accuracy: {baseline_total:.4f}")
+    report.append(f"  LMCache Total Accuracy:  {lmcache_total:.4f}")
+    report.append(f"  Net Accuracy Difference: {total_difference:.4f}")
+    if total_difference >= 0:
+        report.append(f"  Result: LMCache performs BETTER by {total_difference:.4f}")
+    else:
+        report.append(
+            f"  Result: LMCache performs WORSE by {abs(total_difference):.4f}"
+        )
+    report.append("")
+
+    return "\n".join(report)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python summarize-results.py <model1> <model2> ...")
+        print(
+            "Example: python summarize-results.py \
+                meta-llama/Llama-3.1-8B-Instruct \
+                deepseek-ai/DeepSeek-V2-Lite"
+        )
+        sys.exit(1)
+
+    model_names = sys.argv[1:]
+    all_reports = []
+
+    print(f"Processing {len(model_names)} models...")
+
+    for model_name in model_names:
+        print(f"Processing model: {model_name}")
+
+        # Extract short name using the same logic as mmlu-test.py
+        model_short_name = model_name.split("/")[-1]
+
+        # Define file paths
+        baseline_file = f"{model_short_name}-baseline.jsonl"
+        lmcache_file = f"{model_short_name}-lmcache.jsonl"
+
+        print(f"  Looking for files: {baseline_file}, {lmcache_file}")
+
+        # Load results
+        baseline_results = load_jsonl_file(baseline_file)
+        lmcache_results = load_jsonl_file(lmcache_file)
+
+        if not baseline_results and not lmcache_results:
+            print(f"  Warning: No data found for {model_name}")
+            continue
+
+        # Compare results
+        comparisons, baseline_total, lmcache_total = compare_results(
+            baseline_results, lmcache_results
+        )
+
+        # Generate report for this model
+        model_report = format_model_report(
+            model_name,
+            model_short_name,
+            comparisons,
+            baseline_total,
+            lmcache_total,
+        )
+        all_reports.append(model_report)
+
+        print(f"  Processed {len(comparisons)} subjects")
+
+    # Write combined report to file
+    output_file = "correctness-summary.txt"
+    with open(output_file, "w") as f:
+        f.write("MMLU Correctness Comparison Report\n")
+        f.write("=" * 80 + "\n")
+        f.write(f"Generated for {len(model_names)} models\n\n")
+
+        for report in all_reports:
+            f.write(report)
+            f.write("\n")
+
+    print(f"\nReport written to {output_file}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.buildkite/k3_harness/ARCHITECTURE.md b/.buildkite/k3_harness/ARCHITECTURE.md
new file mode 100644
index 0000000..73807f4
--- /dev/null
+++ b/.buildkite/k3_harness/ARCHITECTURE.md
@@ -0,0 +1,89 @@
+# K3s CI Harness Architecture
+
+This document outlines the main motivations, design decisions, and architecture of the K3s-based Buildkite CI Harness for LMCache.
+
+## Motivations
+
+1. **Ease of Setup**: Bring up a fully functional CI node on any raw Linux GPU machine with a single script (`setup-cluster.sh`), avoiding manual configuration of dependencies or persistent Buildkite agents.
+2. **Machine Agnostic**: Remove reliance on machine-specific scripts (e.g., custom `pick-free-gpu.sh` scripts). The CI runs identically on any machine with an NVIDIA GPU and Docker.
+3. **Clean Environments**: Eliminate state bleeding between test runs (no shared pip/uv caches or leftover files). Every job gets a pristine environment.
+4. **Automated Resource Management**: Leverage standard Kubernetes primitives for GPU allocation, volume mounting, and cleanup.
+
+## Core Design Decisions
+
+### 1. K3s + GPU Operator
+We use **K3s** as a lightweight, single-node Kubernetes cluster. The **NVIDIA GPU Operator** automatically configures the container runtime and exposes GPUs to K8s. This abstracts away the underlying hardware and handles GPU discovery automatically.
+
+### 2. Ephemeral Pod-Based Execution (`agent-stack-k8s`)
+Instead of running persistent `buildkite-agent` binaries, we use Buildkite's `agent-stack-k8s`. A controller pod polls the Buildkite queue and dynamically provisions an ephemeral K8s Pod to run each job. When the job finishes, the pod is destroyed.
+
+### 3. Declarative GPU Allocation & Parallelizability
+Each pipeline step explicitly requests the number of GPUs it needs in its Kubernetes pod specification:
+
+```yaml
+resources:
+  limits:
+    nvidia.com/gpu: "2"  # Requests 2 GPUs
+```
+
+Because Kubernetes handles atomic resource scheduling, **jobs automatically run in parallel on multi-GPU nodes**. If a node has 4 GPUs and three jobs arrive (requesting 1, 2, and 1 GPU respectively), K8s schedules them concurrently. If another job requests 2 GPUs, it waits in the queue until resources free up. This completely eliminates the need for manual GPU locking mechanisms.
+
+### 4. Local Base Image & Ephemeral Setup
+To avoid Docker registry dependencies, `setup-cluster.sh` automatically detects the host GPU's compute capability, builds the `lmcache/ci-base:latest` image locally, and imports it directly into K3s. Each job pod uses this base image and dynamically installs vLLM and LMCache (`setup-env.sh`) at runtime.
+
+### 5. Shared Host Volumes
+Large, read-heavy directories (like HuggingFace models and datasets) are mounted into pods via `hostPath` to speed up tests without duplicating downloads, while keeping the job environment itself stateless.
+
+---
+
+## Architecture Flow
+
+### Node Initialization (One-Time Setup)
+
+```text
+[ Raw Linux Host + NVIDIA GPU ]
+          |
+          | (run setup-cluster.sh)
+          v
++-----------------------------------------------------+
+|                     K3s Cluster                     |
+|                                                     |
+|  1. Install K3s                                     |
+|  2. Install Helm -> Deploy NVIDIA GPU Operator      |
+|  3. Build CI Base Image (lmcache/ci-base:latest)    |
+|  4. Import Base Image to K3s containerd             |
++-----------------------------------------------------+
+          |
+          | (run install-agent-stack.sh)
+          v
+[ agent-stack-k8s Controller Pod (Watches queue) ]
+```
+
+### CI Execution Flow
+
+```text
+Buildkite Web UI
+       |
+       | 1. Job pushed to 'k8s' queue
+       v
+agent-stack-k8s Controller (in K3s)
+       |
+       | 2. Reads job, creates ephemeral Pod requesting GPUs
+       v
++-------------------------------------------------------------+
+| Job Pod (e.g., limits: nvidia.com/gpu: "1")                 |
+|                                                             |
+|  - Mounts /data/huggingface from host                       |
+|  - Runs setup-env.sh (Installs vLLM, LMCache)               |
+|  - Executes test script (e.g., pytest)                      |
++-------------------------------------------------------------+
+       |
+       | 3. Test finishes (Pass/Fail)
+       v
+agent-stack-k8s Controller
+       |
+       | 4. Reports result to Buildkite
+       | 5. Destroys the Pod (wipes environment)
+       v
+Buildkite Web UI
+```
\ No newline at end of file
diff --git a/.buildkite/k3_harness/README.md b/.buildkite/k3_harness/README.md
new file mode 100644
index 0000000..9cf7fb2
--- /dev/null
+++ b/.buildkite/k3_harness/README.md
@@ -0,0 +1,143 @@
+# K3s CI Harness
+
+Single-node K3s + NVIDIA GPU Operator for running LMCache CI on any GPU machine.
+
+## Prerequisites
+
+- Linux host with NVIDIA GPU(s) and driver installed
+- Docker (for building the CI base image)
+- Root access
+- A GitHub token (PAT or fine-grained) with read/write access to the repo
+
+## Setup (one-time)
+
+```bash
+# 1. Install K3s + GPU Operator + build CI base image
+.buildkite/k3_harness/setup-cluster.sh
+
+# 2. Verify GPUs work in pods
+.buildkite/k3_harness/smoke-test.sh
+
+# 3. Connect to Buildkite (needs agent token + GitHub token for HTTPS checkout)
+.buildkite/k3_harness/install-agent-stack.sh <BUILDKITE_AGENT_TOKEN> <GITHUB_TOKEN>
+```
+
+`setup-cluster.sh` does everything: installs K3s, Helm, GPU Operator, builds the CI base image from `ci-base.Dockerfile`, imports it into K3s containerd locally, and creates host volume directories. Safe to re-run.
+
+## How Buildkite integration works
+
+This is different from the bare-metal agent setup where you install a Buildkite agent binary on your own machine, register it with a queue created on the Web UI, and manage it as a systemd service. With agent-stack-k8s, there are **no persistent agents on the machine**.
+
+Instead, agent-stack-k8s runs a controller pod in K8s that polls Buildkite for jobs matching the configured queue. When a job appears, it creates a K8s pod to run it. When the job finishes, the pod is deleted.
+
+**What you need from the Buildkite web UI**:
+
+1. **Create a queue** — Go to **Organization Settings → Default cluster → Queues → New Queue** and create a queue named `k8s` (or your chosen name). The queue needs no configuration — just a name. You do **not** register any agents on it.
+2. **Get an agent token** — From the cluster settings page, copy the agent token (or create a new one).
+3. **Get a GitHub token** — Create a PAT (or fine-grained token) with read/write access to the repo. This is used for HTTPS checkout and for pushing baselines to `benchmarks-main`.
+4. **Run `install-agent-stack.sh`** with the agent token and GitHub token. The script creates a K8s secret and installs agent-stack-k8s.
+
+To use a queue name other than `k8s`, set `BUILDKITE_QUEUE` when running install:
+```bash
+BUILDKITE_QUEUE=my-queue .buildkite/k3_harness/install-agent-stack.sh <AGENT_TOKEN> <GITHUB_TOKEN>
+```
+
+Pipeline steps target the queue with:
+```yaml
+agents:
+  queue: "k8s"   # must match the queue name
+```
+
+## Per-job environment
+
+Every CI job sources `setup-env.sh` to install vLLM + LMCache:
+
+```yaml
+command: |
+  source .buildkite/k3_harness/setup-env.sh
+  bash .buildkite/scripts/my-test.sh
+```
+
+This installs:
+1. **vLLM** from nightly wheel
+2. **LMCache** from PR source
+
+Each pod has its own ephemeral filesystem that is cleanly erased after being shut down — no shared pip/uv cache, no cross-pod contention.
+
+## Shared volumes
+
+Mounted into every pod via `hostPath`:
+
+| Host | Container | What |
+|------|-----------|------|
+| `/data/huggingface` | `/root/.cache/huggingface` | Model weights (read-heavy, write-once) |
+| `/data/datasets` | `/root/correctness` | Test datasets (read-only after download) |
+
+## GPU allocation
+
+Request GPUs per pipeline step:
+
+```yaml
+plugins:
+  - kubernetes:
+      podSpec:
+        containers:
+          - resources:
+              limits:
+                nvidia.com/gpu: "2"  # 1 or 2
+```
+
+K8s device plugin handles atomic allocation. No `pick-free-gpu.sh`.
+
+## CI base image
+
+`ci-base.Dockerfile` builds an image with CUDA + Python 3.12 + uv + build deps (no vLLM/LMCache). `setup-cluster.sh` builds it automatically, auto-detects your GPU's compute capability for `TORCH_CUDA_ARCH_LIST`, and imports it into K3s containerd — no registry needed.
+
+To rebuild after changing `requirements/*.txt`:
+```bash
+REBUILD_IMAGE=1 .buildkite/k3_harness/setup-cluster.sh
+```
+
+## Files
+
+```
+k3_harness/
+├── ci-base.Dockerfile      # CI base image definition
+├── setup-cluster.sh        # One-time: K3s + GPU Operator + base image
+├── install-agent-stack.sh  # One-time: Buildkite agent (needs token + GitHub token)
+├── values.yaml             # Reference Helm values (documentation only)
+├── setup-env.sh            # Per-job: install vLLM + LMCache (includes GPU health check)
+├── smoke-test.sh           # Verify: GPU pod runs in K3s
+├── gpu-monitor.sh          # Host-level: detect stale non-K8s GPU processes
+├── setup-gpu-monitor.sh    # Install gpu-monitor.sh as a cron job
+├── teardown.sh             # Remove everything (preserves /data/*)
+└── README.md
+```
+
+## GPU monitoring
+
+CI jobs automatically check GPU health at startup (via `check_gpu_health` in `setup-env.sh`). If a GPU assigned to a pod has less than 80% free memory — usually due to a stale host process — the job fails immediately with a clear message instead of wasting time on setup and then getting a cryptic CUDA OOM.
+
+For **host-level monitoring**, install the GPU monitor cron job:
+
+```bash
+# Install cron job that checks every 10 minutes for stale non-K8s GPU processes
+sudo bash .buildkite/k3_harness/setup-gpu-monitor.sh
+```
+
+This runs `gpu-monitor.sh` every 10 minutes. It distinguishes K8s pod processes (in `kubepods` cgroups) from stale host processes and logs warnings to `/var/log/gpu-monitor.log` with PID, command, GPU, memory usage, and process age.
+
+```bash
+# View monitor logs
+tail -f /var/log/gpu-monitor.log
+
+# Remove the cron job
+crontab -l 2>/dev/null | grep -v gpu-monitor.sh | crontab -
+```
+
+## Teardown
+
+```bash
+.buildkite/k3_harness/teardown.sh
+# Removes K3s, GPU Operator, agent-stack. Preserves /data/*
+```
diff --git a/.buildkite/k3_harness/ci-base.Dockerfile b/.buildkite/k3_harness/ci-base.Dockerfile
new file mode 100644
index 0000000..47f1ac5
--- /dev/null
+++ b/.buildkite/k3_harness/ci-base.Dockerfile
@@ -0,0 +1,40 @@
+# CI base image: CUDA + Python + uv + build deps.
+# No vLLM or LMCache — those are installed per-job by setup-env.sh.
+#
+# Built automatically by setup-cluster.sh and imported into K3s containerd.
+# Rebuild when requirements/*.txt changes.
+
+FROM nvidia/cuda:13.0.2-devel-ubuntu24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PATH="/opt/venv/bin:${PATH}"
+
+RUN echo 'tzdata tzdata/Areas select America' | debconf-set-selections \
+    && echo 'tzdata tzdata/Zones/America select Los_Angeles' | debconf-set-selections \
+    && apt-get update -y \
+    && apt-get install -y --no-install-recommends \
+        ccache software-properties-common git curl sudo jq lsof \
+        python3 python3-dev python3-venv python3-pip tzdata libxcb1-dev \
+        libcudart12 \
+    && ldconfig \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv ~/.local/bin/uv /usr/local/bin/ \
+    && mv ~/.local/bin/uvx /usr/local/bin/ \
+    && uv venv /opt/venv \
+    && . /opt/venv/bin/activate \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace
+
+# Pre-install requirements that rarely change
+COPY requirements/common.txt requirements/build.txt requirements/cuda.txt \
+     requirements/cuda13_core.txt requirements/nixl.txt /tmp/reqs/
+RUN . /opt/venv/bin/activate && \
+    uv pip install -r /tmp/reqs/cuda.txt && \
+    uv pip install -r /tmp/reqs/build.txt && \
+    rm -rf /tmp/reqs
+
+# Set at build time to match the CI machine's GPU.
+# Query with: nvidia-smi --query-gpu=compute_cap --format=csv,noheader
+ARG TORCH_CUDA_ARCH_LIST
+ENV TORCH_CUDA_ARCH_LIST=${TORCH_CUDA_ARCH_LIST}
diff --git a/.buildkite/k3_harness/gpu-monitor.sh b/.buildkite/k3_harness/gpu-monitor.sh
new file mode 100755
index 0000000..f4cd757
--- /dev/null
+++ b/.buildkite/k3_harness/gpu-monitor.sh
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Host-level GPU monitoring script.
+# Detects non-K8s processes holding GPU memory and logs warnings.
+#
+# Install as a cron job on the CI machine:
+#   sudo crontab -e
+#   */10 * * * * /path/to/gpu-monitor.sh >> /var/log/gpu-monitor.log 2>&1
+#
+# Or install with setup-gpu-monitor.sh for automatic setup.
+
+set -euo pipefail
+
+LOG_PREFIX="[gpu-monitor $(date '+%Y-%m-%d %H:%M:%S')]"
+K8S_PIDS_FILE=$(mktemp)
+trap 'rm -f "$K8S_PIDS_FILE"' EXIT
+
+if ! command -v nvidia-smi &>/dev/null; then
+    echo "$LOG_PREFIX ERROR: nvidia-smi not found"
+    exit 1
+fi
+
+# Collect all PIDs using GPU compute
+mapfile -t GPU_PIDS < <(
+    nvidia-smi --query-compute-apps=pid --format=csv,noheader,nounits 2>/dev/null \
+        | tr -d ' ' | sort -u | grep -v '^$'
+)
+
+if [[ ${#GPU_PIDS[@]} -eq 0 ]]; then
+    # No GPU processes -- all clean
+    exit 0
+fi
+
+# Collect K8s container PIDs (all processes running inside any K8s pod).
+# K3s uses containerd; enumerate all container cgroups.
+{
+    shopt -s nullglob
+    for cgroup_dir in /sys/fs/cgroup/*/kubepods* /sys/fs/cgroup/kubepods*; do
+        if [[ -d "$cgroup_dir" ]]; then
+            find "$cgroup_dir" -name "cgroup.procs" -exec cat {} \; 2>/dev/null
+        fi
+    done
+    shopt -u nullglob
+} | sort -u > "$K8S_PIDS_FILE" 2>/dev/null || true
+
+# Also check via crictl if available (more reliable)
+if command -v crictl &>/dev/null; then
+    for container_id in $(crictl ps -q 2>/dev/null); do
+        pid=$(crictl inspect --output go-template --template '{{.info.pid}}' "$container_id" 2>/dev/null || true)
+        if [[ -n "$pid" && "$pid" != "0" ]]; then
+            # Include the container PID and all its descendants
+            echo "$pid" >> "$K8S_PIDS_FILE"
+            pgrep -P "$pid" --ns "$pid" 2>/dev/null >> "$K8S_PIDS_FILE" || true
+        fi
+    done
+fi
+
+# Check each GPU process
+STALE_FOUND=false
+for pid in "${GPU_PIDS[@]}"; do
+    [[ -z "$pid" ]] && continue
+
+    # Is this PID a K8s process?
+    if grep -qw "$pid" "$K8S_PIDS_FILE" 2>/dev/null; then
+        continue
+    fi
+
+    # Check if this PID is inside any cgroup containing "kubepods"
+    if [[ -f "/proc/$pid/cgroup" ]] && grep -q "kubepods" "/proc/$pid/cgroup" 2>/dev/null; then
+        continue
+    fi
+
+    # This is a non-K8s process using a GPU
+    STALE_FOUND=true
+    local_cmdline=$(tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | head -c 200 || echo "<unknown>")
+
+    echo "$LOG_PREFIX STALE GPU PROCESS: PID=$pid cmd='$local_cmdline'"
+    nvidia-smi --query-compute-apps=pid,gpu_bus_id,used_memory --format=csv,noheader 2>/dev/null \
+        | grep "^${pid}," | while IFS=, read -r _ bus mem; do
+            echo "$LOG_PREFIX   GPU bus=$bus memory=$mem"
+        done
+
+    # Check process age
+    if [[ -f "/proc/$pid/stat" ]]; then
+        local_start=$(awk '{print $22}' "/proc/$pid/stat" 2>/dev/null || echo "0")
+        local_uptime=$(awk '{print int($1)}' /proc/uptime)
+        local_clk_tck=$(getconf CLK_TCK)
+        if [[ "$local_start" -gt 0 && "$local_clk_tck" -gt 0 ]]; then
+            local_age_secs=$(( local_uptime - local_start / local_clk_tck ))
+            local_age_hours=$(( local_age_secs / 3600 ))
+            echo "$LOG_PREFIX   Age: ~${local_age_hours}h (${local_age_secs}s)"
+        fi
+    fi
+done
+
+if [[ "$STALE_FOUND" == "true" ]]; then
+    echo "$LOG_PREFIX"
+    echo "$LOG_PREFIX === GPU SUMMARY ==="
+    nvidia-smi --query-gpu=index,memory.used,memory.total,memory.free --format=csv,noheader \
+        | while IFS=, read -r idx used total free; do
+            echo "$LOG_PREFIX   GPU $idx: used=$(echo $used | xargs), total=$(echo $total | xargs), free=$(echo $free | xargs)"
+        done
+    echo "$LOG_PREFIX WARNING: Stale non-K8s processes are holding GPU memory. CI tests may fail."
+    echo "$LOG_PREFIX To fix: kill the stale PIDs listed above."
+    exit 1
+fi
diff --git a/.buildkite/k3_harness/install-agent-stack.sh b/.buildkite/k3_harness/install-agent-stack.sh
new file mode 100755
index 0000000..dbdb949
--- /dev/null
+++ b/.buildkite/k3_harness/install-agent-stack.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Install Buildkite agent-stack-k8s with GitHub token for HTTPS repo access.
+#
+# Usage:
+#   install-agent-stack.sh <BUILDKITE_AGENT_TOKEN> <GITHUB_TOKEN>
+#
+# Arguments:
+#   BUILDKITE_AGENT_TOKEN  — from Buildkite cluster settings
+#   GITHUB_TOKEN           — GitHub PAT or fine-grained token with repo read/write
+#
+# The queue name defaults to "k8s". Override with BUILDKITE_QUEUE env var.
+set -euo pipefail
+
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+TOKEN="${1:?Usage: $0 <BUILDKITE_AGENT_TOKEN> <GITHUB_TOKEN>}"
+GH_TOKEN="${2:?Usage: $0 <BUILDKITE_AGENT_TOKEN> <GITHUB_TOKEN>}"
+QUEUE="${BUILDKITE_QUEUE:-k8s}"
+
+# Create (or update) the K8s secret with GitHub credentials.
+# Two keys:
+#   .git-credentials — used by agent-stack-k8s checkout container (HTTPS clone).
+#                      The leading dot matches the file git-credential-store expects.
+#   GITHUB_TOKEN     — injected into job containers for git push (e.g. baselines)
+kubectl create secret generic buildkite-git-creds \
+    --from-literal=.git-credentials="https://x-access-token:${GH_TOKEN}@github.com" \
+    --from-literal=GITHUB_TOKEN="${GH_TOKEN}" \
+    -n buildkite --dry-run=client -o yaml | kubectl apply -f -
+
+# Install or upgrade agent-stack-k8s
+# - default-checkout-params.gitCredentialsSecret: checkout container uses HTTPS
+#   instead of SSH. Expects a Secret with a `.git-credentials` key.
+# - GITHUB_TOKEN is injected per-step in pipeline.yml (not via global pod-spec-patch)
+helm upgrade --install agent-stack-k8s oci://ghcr.io/buildkite/helm/agent-stack-k8s \
+    --version 0.38.0 \
+    --namespace buildkite --create-namespace \
+    --set agentToken="${TOKEN}" \
+    --set config.queue="${QUEUE}" \
+    --set-json 'config.default-checkout-params={"gitCredentialsSecret":{"secretName":"buildkite-git-creds"}}' \
+    --wait --timeout 3m
+
+echo "agent-stack-k8s installed (queue=${QUEUE})"
+kubectl get pods -n buildkite
diff --git a/.buildkite/k3_harness/resolve-pinned-vllm.sh b/.buildkite/k3_harness/resolve-pinned-vllm.sh
new file mode 100644
index 0000000..b48289b
--- /dev/null
+++ b/.buildkite/k3_harness/resolve-pinned-vllm.sh
@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# Resolve the vLLM nightly version that this build should install.
+#
+# Resolution order (first non-empty wins):
+#   1. PINNED_VLLM_VERSION env var  -- explicit per-build override.
+#   2. latest_tested_vllm.txt fetched from
+#      https://raw.githubusercontent.com/LMCache/LMCache/buildkite_latest_tested_vllm/latest_tested_vllm.txt
+#      -- the most recent vLLM nightly that the canary build verified.
+#   3. Empty string -- caller falls back to "latest nightly".
+#
+# The pin file's first non-blank, non-comment line is the bare version
+# (kept this way so older `head -n1` consumers still work). Subsequent
+# key=value lines carry pre-resolved metadata so consumers can install
+# the wheel without making any extra API calls:
+#   short_sha=<short-commit-sha>
+#   full_sha=<40-char-commit-sha>
+#   archive_index_url=https://wheels.vllm.ai/<full-sha>/cu130
+#
+# Toggles:
+#   USE_PINNED_VLLM=false  -- skip step 2 (always probe the latest nightly).
+#                             Used by the canary build itself, since pinning
+#                             to its own previous result would defeat the
+#                             purpose of a freshness check.
+#
+# Usage:
+#   source .buildkite/k3_harness/resolve-pinned-vllm.sh
+#   echo "Resolved: ${PINNED_VLLM_VERSION:-<unpinned, using nightly>}"
+#   echo "Archive : ${PINNED_VLLM_ARCHIVE_INDEX_URL:-<none>}"
+#
+# After sourcing the following are set (possibly empty) and exported:
+#   PINNED_VLLM_VERSION         -- e.g. 0.23.1rc1.dev508+gc6dd32a81
+#   PINNED_VLLM_FULL_SHA        -- 40-char commit SHA, if recorded in pin
+#   PINNED_VLLM_ARCHIVE_INDEX_URL
+#                               -- permanent PEP 503 simple index, if recorded
+#
+# The script never fails the build: a missing/unreachable pin file just
+# falls through to the unpinned path, mirroring the previous behaviour.
+
+# Allow re-sourcing without "unbound variable" complaints under set -u.
+PINNED_VLLM_VERSION="${PINNED_VLLM_VERSION:-}"
+PINNED_VLLM_ARCHIVE_INDEX_URL="${PINNED_VLLM_ARCHIVE_INDEX_URL:-}"
+PINNED_VLLM_FULL_SHA="${PINNED_VLLM_FULL_SHA:-}"
+USE_PINNED_VLLM="${USE_PINNED_VLLM:-true}"
+
+# Override URL if you mirror the pin file elsewhere (e.g. an internal
+# raw-file proxy for offline CI).
+LMCACHE_VLLM_PIN_URL="${LMCACHE_VLLM_PIN_URL:-https://raw.githubusercontent.com/LMCache/LMCache/buildkite_latest_tested_vllm/latest_tested_vllm.txt}"
+
+if [[ -z "${PINNED_VLLM_VERSION}" && "${USE_PINNED_VLLM}" == "true" ]]; then
+    if command -v curl >/dev/null 2>&1; then
+        # 5s connect, 10s total -- pin lookup must never dominate setup time.
+        fetched="$(curl -fsSL --connect-timeout 5 --max-time 10 \
+            "${LMCACHE_VLLM_PIN_URL}" 2>/dev/null || true)"
+        # The pin file's first non-blank, non-comment line is the bare
+        # version (back-compat for older readers); subsequent key=value
+        # lines carry resolved metadata so consumers can skip the live
+        # GitHub API lookup. A single awk pass extracts everything.
+        # Empty / missing keys are tolerated -- we'll just fall back to
+        # resolving them on demand later in the pipeline.
+        eval "$(printf '%s\n' "${fetched}" | awk '
+            BEGIN { ver=""; idx=""; sha="" }
+            /^[[:space:]]*(#|$)/ { next }
+            ver == "" {
+                line=$0
+                sub(/[[:space:]]+$/, "", line)
+                ver=line
+                next
+            }
+            /^archive_index_url=/ {
+                v=$0; sub(/^archive_index_url=/, "", v); idx=v; next
+            }
+            /^full_sha=/ {
+                v=$0; sub(/^full_sha=/, "", v); sha=v; next
+            }
+            END {
+                printf("PINNED_VLLM_VERSION=%s\n", ver)
+                printf("PINNED_VLLM_ARCHIVE_INDEX_URL=%s\n", idx)
+                printf("PINNED_VLLM_FULL_SHA=%s\n", sha)
+            }
+        ')"
+    fi
+fi
+
+export PINNED_VLLM_VERSION
+export PINNED_VLLM_ARCHIVE_INDEX_URL
+export PINNED_VLLM_FULL_SHA
+
+if [[ -n "${PINNED_VLLM_VERSION}" ]]; then
+    echo "[resolve-pinned-vllm] Pinned vLLM version: ${PINNED_VLLM_VERSION}" >&2
+    if [[ -n "${PINNED_VLLM_ARCHIVE_INDEX_URL}" ]]; then
+        echo "[resolve-pinned-vllm] Archive index:" \
+             "${PINNED_VLLM_ARCHIVE_INDEX_URL}" >&2
+    fi
+else
+    echo "[resolve-pinned-vllm] No pinned vLLM; will install latest nightly" >&2
+fi
diff --git a/.buildkite/k3_harness/setup-blend-env.sh b/.buildkite/k3_harness/setup-blend-env.sh
new file mode 100755
index 0000000..df07689
--- /dev/null
+++ b/.buildkite/k3_harness/setup-blend-env.sh
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Per-job environment setup for CacheBlend-plugin compatibility tests.
+ 
+set -euo pipefail
+
+trap 'echo "ERROR: setup-blend-env.sh failed at line $LINENO (exit code $?)" >&2' ERR
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# 1. Full env: vLLM nightly + LMCache(PR) from source (+ c_ops for this GPU).
+#    setup-env.sh already runs the GPU health pre-check.
+source "${REPO_ROOT}/.buildkite/k3_harness/setup-env.sh"
+
+# setup-env.sh installed its own ERR trap; restore ours for accurate attribution.
+trap 'echo "ERROR: setup-blend-env.sh failed at line $LINENO (exit code $?)" >&2' ERR
+
+# 2. Plugin-harness dep not in the LMCache/vLLM dependency closure.
+echo "--- :python: Installing cacheblend-plugin harness deps"
+uv pip install httpx
+
+# 3. Pull the cacheblend-plugin. Coordinates come from the Buildkite pipeline
+#    env; CB_PLUGIN_REPO is required (set it in the pipeline env so the repo
+#    owner/name is not hardcoded here). REF/DIR have sensible fallbacks.
+CB_PLUGIN_REPO="${CB_PLUGIN_REPO:?CB_PLUGIN_REPO not set — set the plugin repo (owner/name) in the Buildkite pipeline env}"
+CB_PLUGIN_REF="${CB_PLUGIN_REF:-main}"
+CB_PLUGIN_DIR="${CB_PLUGIN_DIR:-/tmp/cb-plugin}"
+
+echo "--- :arrow_down: Pulling ${CB_PLUGIN_REPO}@${CB_PLUGIN_REF}"
+_cb_tok="${GH_TOKEN:-${GITHUB_TOKEN:-}}"
+echo "    GH_TOKEN present: $([ -n "${_cb_tok}" ] && echo yes || echo NO)"
+if [ -z "${_cb_tok}" ]; then
+    echo "ERROR: GH_TOKEN/GITHUB_TOKEN not set. ${CB_PLUGIN_REPO} is private — set a" >&2
+    echo "       fine-grained PAT (resource owner = the repo's org, Contents: read)" >&2
+    echo "       as GH_TOKEN in the Buildkite pipeline env." >&2
+    exit 1
+fi
+_cb_url="https://x-access-token:${_cb_tok}@github.com/${CB_PLUGIN_REPO}.git"
+# Isolate from the Buildkite agent's git config: its checkout credential is a
+# GitHub App token scoped to LMCache (injected via the GLOBAL git config —
+# insteadOf / extraheader / credential.helper) and 403s on the plugin repo.
+# Ignoring global+system config forces git to use ONLY our GH_TOKEN from the URL.
+_cb_git=(env GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null
+         git -c credential.helper=)
+rm -rf "${CB_PLUGIN_DIR}"
+# --branch handles a branch/tag; a commit SHA needs a full clone + checkout.
+if ! "${_cb_git[@]}" clone --depth 1 --branch "${CB_PLUGIN_REF}" "${_cb_url}" "${CB_PLUGIN_DIR}" 2>/dev/null; then
+    "${_cb_git[@]}" clone "${_cb_url}" "${CB_PLUGIN_DIR}"
+    git -C "${CB_PLUGIN_DIR}" checkout "${CB_PLUGIN_REF}"
+fi
+echo "    cacheblend-plugin @ $(git -C "${CB_PLUGIN_DIR}" rev-parse --short HEAD) (ref=${CB_PLUGIN_REF})"
+
+# 4. Install the plugin editable; --no-deps keeps the env's torch/vllm/lmcache,
+#    --no-build-isolation because the plugin is pure-Python (no compile step).
+echo "--- :python: Installing cacheblend-plugin (editable)"
+git config --global --add safe.directory "${CB_PLUGIN_DIR}" 2>/dev/null || true
+uv pip install -e "${CB_PLUGIN_DIR}" --no-deps --no-build-isolation
+
+# 5. Import/registration smoke so a broken install fails here, not 180s into a
+#    server-boot timeout inside the harness.
+python -c "import lmcache_cacheblend; print('cacheblend-plugin imported OK')"
+
+export CB_PLUGIN_DIR CB_PLUGIN_REF
+echo "--- :white_check_mark: CacheBlend env ready (plugin @ ${CB_PLUGIN_REF}, dir=${CB_PLUGIN_DIR})"
diff --git a/.buildkite/k3_harness/setup-cluster.sh b/.buildkite/k3_harness/setup-cluster.sh
new file mode 100755
index 0000000..969e20b
--- /dev/null
+++ b/.buildkite/k3_harness/setup-cluster.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Idempotent K3s + GPU Operator + CI base image setup.
+# Safe to re-run — skips components already installed.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+CI_BASE_IMAGE="lmcache/ci-base:latest"
+DATA_DIR="/data"
+
+# ── K3s ──────────────────────────────────────────────────────
+if command -v k3s &>/dev/null && systemctl is-active --quiet k3s; then
+    echo "✓ K3s already running"
+else
+    echo "→ Installing K3s..."
+    curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="server \
+        --disable=traefik \
+        --write-kubeconfig-mode=644" sh -
+    echo "✓ K3s installed"
+fi
+
+# Persist KUBECONFIG for interactive shells
+grep -q 'KUBECONFIG=/etc/rancher/k3s/k3s.yaml' ~/.bashrc 2>/dev/null || \
+    echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc
+
+kubectl get nodes
+echo ""
+
+# ── Helm ─────────────────────────────────────────────────────
+if ! command -v helm &>/dev/null; then
+    echo "→ Installing Helm..."
+    curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+fi
+echo "✓ Helm $(helm version --short)"
+
+# ── NVIDIA GPU Operator ──────────────────────────────────────
+if helm status gpu-operator -n gpu-operator &>/dev/null; then
+    echo "✓ GPU Operator already installed"
+else
+    echo "→ Installing GPU Operator..."
+    helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
+    helm repo update nvidia
+    helm install gpu-operator nvidia/gpu-operator \
+        --namespace gpu-operator --create-namespace \
+        --set driver.enabled=false \
+        --set toolkit.enabled=true \
+        --wait --timeout 5m
+    echo "✓ GPU Operator installed"
+fi
+
+echo "→ Waiting for device plugin..."
+kubectl wait --for=condition=ready pod \
+    -l app=nvidia-device-plugin-daemonset \
+    -n gpu-operator --timeout=120s
+
+GPU_COUNT=$(kubectl get node -o jsonpath='{.items[0].status.allocatable.nvidia\.com/gpu}')
+echo "✓ GPUs available: ${GPU_COUNT}"
+
+# ── CI base image ────────────────────────────────────────────
+# Auto-detect GPU compute capability for TORCH_CUDA_ARCH_LIST
+COMPUTE_CAP=$(nvidia-smi --query-gpu=compute_cap --format=csv,noheader | head -1)
+ARCH_LIST="${COMPUTE_CAP}+PTX"
+
+# Check if image already exists in K3s containerd
+if k3s ctr images check | grep -q "${CI_BASE_IMAGE}"; then
+    echo "✓ CI base image already imported (${CI_BASE_IMAGE})"
+    echo "  To rebuild: run with REBUILD_IMAGE=1"
+    if [[ "${REBUILD_IMAGE:-}" != "1" ]]; then
+        SKIP_IMAGE=1
+    fi
+fi
+
+if [[ "${SKIP_IMAGE:-}" != "1" ]]; then
+    echo "→ Building CI base image (TORCH_CUDA_ARCH_LIST=${ARCH_LIST})..."
+    docker build \
+        -f "${SCRIPT_DIR}/ci-base.Dockerfile" \
+        --build-arg TORCH_CUDA_ARCH_LIST="${ARCH_LIST}" \
+        -t "${CI_BASE_IMAGE}" \
+        "${REPO_ROOT}"
+
+    echo "→ Importing into K3s containerd..."
+    docker save "${CI_BASE_IMAGE}" | k3s ctr images import -
+    echo "✓ CI base image ready"
+fi
+
+# ── Shared host volumes ──────────────────────────────────────
+mkdir -p "${DATA_DIR}/huggingface" "${DATA_DIR}/datasets"
+echo "✓ Host volumes: ${DATA_DIR}/{huggingface,datasets}"
+
+echo ""
+echo "=== Cluster ready ==="
+echo "  K3s:          $(k3s --version | head -1)"
+echo "  GPU Operator: $(helm list -n gpu-operator -o json | python3 -c 'import sys,json;print(json.load(sys.stdin)[0]["app_version"])' 2>/dev/null || echo 'unknown')"
+echo "  GPUs:         ${GPU_COUNT}x $(nvidia-smi --query-gpu=name --format=csv,noheader | head -1)"
+echo "  Arch list:    ${ARCH_LIST}"
+echo "  Base image:   ${CI_BASE_IMAGE}"
+echo "  Data dir:     ${DATA_DIR}"
+echo ""
+echo "Next: run ./install-agent-stack.sh <BUILDKITE_AGENT_TOKEN>"
diff --git a/.buildkite/k3_harness/setup-env.sh b/.buildkite/k3_harness/setup-env.sh
new file mode 100755
index 0000000..a5c5642
--- /dev/null
+++ b/.buildkite/k3_harness/setup-env.sh
@@ -0,0 +1,298 @@
+#!/usr/bin/env bash
+# Per-job environment setup: installs vLLM nightly + LMCache from source.
+# Called at the start of every CI job.
+set -euo pipefail
+
+# Print the failing command and line number on any error.
+trap 'echo "ERROR: setup-env.sh failed at line $LINENO (exit code $?)" >&2' ERR
+
+# ── GPU health pre-check ────────────────────────────────────
+# Fail fast if GPUs are occupied by stale host processes.
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+check_gpu_health 80
+
+# Resolve which vLLM nightly to install. Sets PINNED_VLLM_VERSION (empty
+# string means "use latest nightly", any other value means
+# "install vllm==<that exact version>"). See script header for the full
+# resolution order and override knobs.
+source "${REPO_ROOT}/.buildkite/k3_harness/resolve-pinned-vllm.sh"
+
+echo "--- :broom: Pre-install bytecode/cache eviction"
+# The CI base image pre-installs packages from requirements/*.txt at image
+# build time. We've observed k3 jobs (integration + correctness) fail with
+#   ImportError: cannot import name 'GenerationConfig' from 'transformers'
+# after `uv pip install -U vllm ...` upgrades transformers, even though the
+# installed .py files clearly expose GenerationConfig (verified both 5.5.0
+# and 5.5.4). The same install recipe replayed in a fresh venv outside CI
+# always succeeds, so the failure is tied to base-image filesystem state
+# (stale __pycache__, partial upgrades via overlayfs, etc.). Evict all
+# bytecode caches and uv's download cache up front so later steps operate
+# on clean ground; this is cheap (few seconds) and idempotent.
+find /opt/venv/lib/python3.12/site-packages -type d -name __pycache__ \
+    -exec rm -rf {} + 2>/dev/null || true
+uv cache clean 2>/dev/null || true
+
+echo "--- :python: Installing vLLM nightly (pinned to cu130 index)"
+# The base image is nvidia/cuda:13.0.2-devel-ubuntu24.04 (system nvcc 13).
+# vLLM's generic nightly index (wheels.vllm.ai/nightly/vllm/) non-deterministically
+# resolves to either a cu128 or a cu130 torch wheel depending on which wheel
+# vLLM's nightly CI happened to publish that day. When the resolver picks a
+# cu128 torch, torch.utils.cpp_extension._check_cuda_version aborts the
+# LMCache editable install with:
+#   RuntimeError: The detected CUDA version (13.0) mismatches the version
+#   that was used to compile PyTorch (12.8).
+#
+# Pin to the cu130 sub-index so torch.version.cuda is always "13.0" and
+# matches the base image. This also lets us drop the HTML-scraping + apt
+# cuda-compiler alignment dance that lived here before.
+# (See https://docs.vllm.ai/ install tips → Nightly → CUDA 13.0.)
+#
+# --reinstall-package for transformers / tokenizers / huggingface-hub /
+# safetensors / vllm forces uv to uninstall-and-reinstall those packages
+# even when it thinks the existing install is up to date. That is the
+# minimum set to put the full `vllm serve` import chain on a freshly
+# extracted wheel, which bypasses whatever filesystem-level mismatch in
+# the base image was causing the GenerationConfig ImportError.
+#
+# When PINNED_VLLM_VERSION is non-empty (resolved by resolve-pinned-vllm.sh
+# from the `buildkite_latest_tested_vllm` branch), pin to that exact wheel
+# so every CI job matches the version most recently verified by the
+# canary build. Empty falls back to "latest nightly".
+#
+# vLLM's nightly index (wheels.vllm.ai/nightly/<cuda>/) only keeps the
+# *latest* wheel; older versions get rolled off within a day or two and
+# pinning them there fails with "no version of vllm==X". Historical
+# wheels are still served at wheels.vllm.ai/<full-commit-sha>/<cuda>/,
+# which is a PEP 503 simple index. The canary records that archive URL
+# directly in the pin file, so the common path needs zero extra API
+# calls. As a fallback (e.g. an old-format pin file written before the
+# canary started recording metadata, or a manual override via
+# PINNED_VLLM_VERSION), we still expand the short SHA via the public
+# GitHub commits API; GITHUB_TOKEN is honoured (5000 req/h) but optional.
+PINNED_VLLM_INDEX_ARGS=()
+if [[ -n "${PINNED_VLLM_VERSION:-}" ]]; then
+    VLLM_INSTALL_SPEC="vllm[runai,tensorizer,flashinfer]==${PINNED_VLLM_VERSION}"
+    echo "Installing vLLM pinned: ${VLLM_INSTALL_SPEC}"
+    archive_url="${PINNED_VLLM_ARCHIVE_INDEX_URL:-}"
+    if [[ -z "${archive_url}" ]]; then
+        # Old-format pin file or per-build override: resolve on demand.
+        short_sha="${PINNED_VLLM_VERSION##*+g}"
+        if [[ "${short_sha}" != "${PINNED_VLLM_VERSION}" \
+                && "${short_sha}" =~ ^[0-9a-f]+$ ]]; then
+            gh_auth_args=()
+            if [[ -n "${GITHUB_TOKEN:-}" ]]; then
+                gh_auth_args=(-H "Authorization: Bearer ${GITHUB_TOKEN}")
+            fi
+            full_sha=""
+            for attempt in 1 2 3; do
+                full_sha="$(curl -fsSL --connect-timeout 5 --max-time 10 \
+                    -H "Accept: application/vnd.github+json" \
+                    "${gh_auth_args[@]+"${gh_auth_args[@]}"}" \
+                    "https://api.github.com/repos/vllm-project/vllm/commits/${short_sha}" \
+                    2>/dev/null \
+                    | awk -F'"' '/"sha":/ {print $4; exit}')" || true
+                if [[ "${full_sha}" =~ ^[0-9a-f]{40}$ ]]; then
+                    break
+                fi
+                echo "[INFO] GitHub commit lookup attempt ${attempt} for" \
+                     "${short_sha} returned no SHA; retrying..." >&2
+                sleep 2
+            done
+            if [[ "${full_sha}" =~ ^[0-9a-f]{40}$ ]]; then
+                archive_url="https://wheels.vllm.ai/${full_sha}/cu130"
+            else
+                echo "[WARN] could not resolve full SHA for ${short_sha}; pip" \
+                     "may fail if the wheel has rolled off the nightly index" >&2
+            fi
+        fi
+    fi
+    if [[ -n "${archive_url}" ]]; then
+        echo "Adding commit-archived index: ${archive_url}"
+        PINNED_VLLM_INDEX_ARGS+=(--extra-index-url "${archive_url}")
+    fi
+else
+    VLLM_INSTALL_SPEC="vllm[runai,tensorizer,flashinfer]"
+    echo "Installing latest vLLM nightly (no pin)"
+fi
+uv pip install -U "${VLLM_INSTALL_SPEC}" --pre \
+    --reinstall-package transformers \
+    --reinstall-package tokenizers \
+    --reinstall-package huggingface-hub \
+    --reinstall-package safetensors \
+    --reinstall-package vllm \
+    "${PINNED_VLLM_INDEX_ARGS[@]+"${PINNED_VLLM_INDEX_ARGS[@]}"}" \
+    --extra-index-url https://wheels.vllm.ai/nightly/cu130 \
+    --extra-index-url https://download.pytorch.org/whl/cu130 \
+    --index-strategy unsafe-best-match
+
+# Pre-import transformers on the main thread via sitecustomize.py so
+# vllm's BG-thread preload can't race ahead of _LazyModule init.
+cat > /opt/venv/lib/python3.12/site-packages/sitecustomize.py <<'PY'
+try:
+    import transformers  # noqa: F401
+except Exception:
+    pass
+PY
+
+# Probe the vLLM CLI by invoking `vllm --help` as a subprocess. This is the
+# only probe that exercises the full import chain that `vllm serve` runs:
+# vllm.entrypoints.cli.main.main() triggers `import vllm.entrypoints.cli.
+# benchmark.main` *inside* the function body, which in turn loads
+# vllm.config.model -> vllm.transformers_utils.config -> `from transformers
+# import GenerationConfig, PretrainedConfig`. A plain `from vllm.entrypoints.
+# cli.main import main` only resolves the `main` symbol; it never executes
+# the function, so it silently passes even when the CLI is broken. Shared
+# between the pre-install auto-heal loop below and the post-install hard
+# probe at the end of this script.
+probe_vllm_cli() {
+    vllm --help 2>&1 >/dev/null
+}
+
+# vLLM nightlies periodically add eager imports of packages that aren't in
+# their declared deps (e.g. `pandas` from vllm/_aiter_ops.py). Auto-install
+# any ModuleNotFoundError modules so the job keeps going. Capped to avoid
+# infinite loops; every auto-install is logged so the drift is visible in
+# the build output. ImportError with a missing top-level name (e.g. a
+# transformers/vLLM API break) bails immediately since reinstalling the
+# package wouldn't recover.
+dump_transformers_state() {
+    # Called whenever a CLI probe fails with anything other than a clean
+    # ModuleNotFoundError. This failure mode has been reproducible only on
+    # the K3s pods, never on a fresh local venv with identical versions,
+    # so we need a direct view of the running pod's filesystem + Python
+    # state to make progress.
+    echo "=================== DIAGNOSTIC DUMP ===================" >&2
+    echo "--- uv pip list (relevant packages) ---" >&2
+    uv pip list 2>/dev/null | grep -iE "^(transformers|tokenizers|huggingface|safetensors|vllm|torch) " >&2 || true
+    local tf_dir=/opt/venv/lib/python3.12/site-packages/transformers
+    echo "--- transformers directory listing ---" >&2
+    ls -la "${tf_dir}/__init__.py" "${tf_dir}/__pycache__/__init__.cpython-312.pyc" 2>&1 >&2 || true
+    echo "--- dist-info METADATA version ---" >&2
+    grep -m1 "^Version:" /opt/venv/lib/python3.12/site-packages/transformers-*.dist-info/METADATA 2>/dev/null >&2 || true
+    echo "--- transformers/__init__.py: __version__ line ---" >&2
+    grep -n "^__version__" "${tf_dir}/__init__.py" 2>/dev/null >&2 || true
+    echo "--- transformers/__init__.py: 'generation' key in _import_structure ---" >&2
+    awk '/"generation":/,/\]/' "${tf_dir}/__init__.py" 2>/dev/null | head -20 >&2 || true
+    echo "--- Python sees: ---" >&2
+    python - <<'PY' >&2 2>&1 || true
+import sys, importlib
+print(f"sys.executable = {sys.executable}")
+print(f"sys.path = {sys.path}")
+try:
+    import transformers
+    print(f"transformers.__file__ = {transformers.__file__}")
+    print(f"transformers.__version__ = {transformers.__version__}")
+    print(f"type(transformers) = {type(transformers).__name__}")
+    print(f"'GenerationConfig' in dir(transformers) = {'GenerationConfig' in dir(transformers)}")
+    cs2m = getattr(transformers, "_class_to_module", None)
+    print(f"has _class_to_module = {cs2m is not None}")
+    if cs2m is not None:
+        print(f"GenerationConfig in _class_to_module = {'GenerationConfig' in cs2m}")
+        print(f"first 5 keys = {list(cs2m.keys())[:5]}")
+    import_struct = getattr(transformers, "_import_structure", None)
+    print(f"has _import_structure = {import_struct is not None}")
+    if import_struct is not None:
+        print(f"'generation' in _import_structure = {'generation' in import_struct}")
+        print(f"_import_structure['generation'] = {import_struct.get('generation')}")
+    try:
+        from transformers import GenerationConfig
+        print("DIRECT IMPORT of GenerationConfig WORKED")
+    except Exception as e:
+        print(f"DIRECT IMPORT failed: {type(e).__name__}: {e}")
+except Exception as e:
+    import traceback
+    traceback.print_exc()
+PY
+    echo "=================== END DIAGNOSTIC DUMP ===================" >&2
+}
+
+MAX_AUTO_INSTALL=5
+for i in $(seq 1 "$MAX_AUTO_INSTALL"); do
+    if err=$(probe_vllm_cli); then
+        break
+    fi
+    mod=$(printf '%s\n' "$err" | sed -n "s/.*No module named '\([^']*\)'.*/\1/p" | head -1)
+    if [[ -z "$mod" ]]; then
+        echo "vLLM import failed with a non-ModuleNotFoundError:" >&2
+        echo "$err" >&2
+        dump_transformers_state
+        exit 1
+    fi
+    if [[ "$i" == "$MAX_AUTO_INSTALL" ]]; then
+        echo "Hit $MAX_AUTO_INSTALL auto-install retries; last missing module: $mod" >&2
+        echo "$err" >&2
+        exit 1
+    fi
+    echo "Auto-installing missing vLLM runtime dep: $mod"
+    uv pip install "$mod"
+done
+
+echo "--- :mag: Verifying torch CUDA matches system nvcc"
+# Sanity check: fail fast with a clear message if the cu130 pin above
+# somehow didn't produce a cu13x torch. Previously this mismatch surfaced
+# deep inside ninja as a cryptic `cusparse.h: No such file or directory`;
+# catching it here makes the failure mode obvious.
+python - <<'PY'
+import subprocess, sys, torch
+tc = torch.version.cuda or ""
+try:
+    nv = subprocess.check_output(["nvcc", "--version"], text=True)
+    sys_major = next(
+        (line.split("release ")[1].split(",")[0].split(".")[0]
+         for line in nv.splitlines() if "release " in line),
+        "",
+    )
+except Exception:
+    sys_major = ""
+torch_major = tc.split(".")[0] if tc else ""
+print(f"torch.version.cuda={tc!r}; system nvcc major={sys_major!r}")
+if torch_major and sys_major and torch_major != sys_major:
+    sys.exit(
+        f"CUDA major mismatch: torch={torch_major} vs nvcc={sys_major}. "
+        "Check the vLLM nightly cu130 index pin in setup-env.sh."
+    )
+PY
+
+echo "--- :python: Installing LMCache from source"
+# Skip setuptools_scm git describe; the repo carries non-PEP-440 tags
+# (nightly, nightly-cu13) that crash the newer vcs_versioning backend.
+export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LMCACHE="${SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LMCACHE:-0.0.0+ci}"
+uv pip freeze | sort > /tmp/env-before-lmcache.txt
+uv pip install -e . --no-build-isolation
+uv pip freeze | sort > /tmp/env-after-lmcache.txt
+if ! diff -q /tmp/env-before-lmcache.txt /tmp/env-after-lmcache.txt >/dev/null; then
+    echo "--- :warning: Packages changed during LMCache install"
+    diff /tmp/env-before-lmcache.txt /tmp/env-after-lmcache.txt || true
+fi
+
+echo "--- :broom: Post-install bytecode eviction"
+# Belt-and-suspenders companion to the pre-install eviction above: clear
+# __pycache__ again after the LMCache editable install, which may have
+# triggered fresh imports (setuptools_scm, pyproject build backend) and
+# deposited new .pyc files that reference now-downgraded packages.
+find /opt/venv/lib/python3.12/site-packages -type d -name __pycache__ \
+    -exec rm -rf {} + 2>/dev/null || true
+
+echo "--- :mag: Post-install CLI chain probe"
+# The LMCache editable install can downgrade transitive deps to honor the
+# caps in requirements/common.txt. If that leaves the env in a state where
+# `vllm --help` cannot complete its import chain (vllm.entrypoints.cli.
+# main.main() -> vllm.entrypoints.cli.benchmark.main -> vllm.config ->
+# vllm.transformers_utils.config -> `from transformers import ...`), the
+# only other signal is a 180s `wait_for_server` timeout inside each test
+# harness. Re-probe the full chain here so broken envs fail fast with the
+# actual traceback instead of a generic timeout.
+if err=$(probe_vllm_cli); then
+    echo "vLLM CLI import chain OK post-install."
+else
+    echo "FATAL: vLLM CLI import chain broken after LMCache install." >&2
+    echo "--- Traceback ---" >&2
+    echo "$err" >&2
+    echo "--- Installed packages ---" >&2
+    uv pip freeze >&2 || true
+    exit 1
+fi
+
+echo "--- :white_check_mark: Environment ready"
+python -c "import vllm; import lmcache; print(f'vLLM={vllm.__version__}, LMCache installed from source with no build isolation')"
diff --git a/.buildkite/k3_harness/setup-gpu-monitor.sh b/.buildkite/k3_harness/setup-gpu-monitor.sh
new file mode 100755
index 0000000..7cdae33
--- /dev/null
+++ b/.buildkite/k3_harness/setup-gpu-monitor.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Install the GPU monitor as a cron job on the CI host machine.
+# Run this once during initial cluster setup.
+#
+# Usage: sudo bash setup-gpu-monitor.sh
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MONITOR_SCRIPT="${SCRIPT_DIR}/gpu-monitor.sh"
+LOG_FILE="/var/log/gpu-monitor.log"
+CRON_INTERVAL="*/10"  # Every 10 minutes
+
+if [[ ! -f "$MONITOR_SCRIPT" ]]; then
+    echo "ERROR: gpu-monitor.sh not found at $MONITOR_SCRIPT"
+    exit 1
+fi
+
+chmod +x "$MONITOR_SCRIPT"
+
+# Create log file with rotation
+touch "$LOG_FILE"
+
+# Set up logrotate
+cat > /etc/logrotate.d/gpu-monitor <<EOF
+${LOG_FILE} {
+    daily
+    rotate 7
+    compress
+    missingok
+    notifempty
+}
+EOF
+
+# Install cron job (idempotent: removes old entry first)
+CRON_CMD="${CRON_INTERVAL} * * * * ${MONITOR_SCRIPT} >> ${LOG_FILE} 2>&1"
+(crontab -l 2>/dev/null | grep -v "gpu-monitor.sh" || true; echo "$CRON_CMD") | crontab -
+
+echo "GPU monitor installed:"
+echo "  Script: $MONITOR_SCRIPT"
+echo "  Log:    $LOG_FILE"
+echo "  Cron:   $CRON_CMD"
+echo ""
+echo "View logs:    tail -f $LOG_FILE"
+echo "Remove cron:  crontab -l | grep -v gpu-monitor.sh | crontab -"
diff --git a/.buildkite/k3_harness/setup-lmcache-only-env.sh b/.buildkite/k3_harness/setup-lmcache-only-env.sh
new file mode 100755
index 0000000..1758ebf
--- /dev/null
+++ b/.buildkite/k3_harness/setup-lmcache-only-env.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Per-job environment setup for jobs that DON'T need vLLM (e.g. unit tests).
+# Installs LMCache from source on top of the ci-base image, which already
+# has torch + requirements/cuda.txt + build.txt baked in. Much faster than
+# setup-env.sh since it skips the vLLM nightly install entirely.
+set -euo pipefail
+
+trap 'echo "ERROR: setup-lmcache-only-env.sh failed at line $LINENO (exit code $?)" >&2' ERR
+
+# ── GPU health pre-check ────────────────────────────────────
+# Fail fast if GPUs are occupied by stale host processes.
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+check_gpu_health 80
+
+echo "--- :python: Installing LMCache from source (no vLLM)"
+# Skip setuptools_scm git describe; the repo carries non-PEP-440 tags
+# (nightly, nightly-cu13) that crash the newer vcs_versioning backend.
+export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LMCACHE="${SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LMCACHE:-0.0.0+ci}"
+uv pip install -e . --no-build-isolation
+
+echo "--- :white_check_mark: Environment ready (LMCache only, no vLLM)"
+python -c "import lmcache; print('LMCache installed from source')"
diff --git a/.buildkite/k3_harness/setup-sglang-env.sh b/.buildkite/k3_harness/setup-sglang-env.sh
new file mode 100755
index 0000000..a3cffcd
--- /dev/null
+++ b/.buildkite/k3_harness/setup-sglang-env.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Per-job env setup for the SGLang + LMCache MP integration tests.
+# Drop the fork install once https://github.com/sgl-project/sglang/pull/24089
+# lands.
+set -euo pipefail
+trap 'echo "ERROR: setup-sglang-env.sh failed at line $LINENO (exit code $?)" >&2' ERR
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+check_gpu_health 80
+
+echo "--- :wrench: System tools (rustup, protoc, libnuma1)"
+# rustup: sglang-grpc needs Rust 1.85+ (apt's rustc is too old).
+# protoc: sglang-grpc's prost-build shells out to it.
+# libnuma1: sgl_kernel's sm100 .so dynamically links to libnuma.so.1.
+if ! command -v rustc >/dev/null 2>&1; then
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- \
+        -y --default-toolchain stable --profile minimal --no-modify-path
+fi
+# shellcheck disable=SC1091
+. "${HOME}/.cargo/env"
+rustc --version
+
+APT_NEEDED=()
+command -v protoc >/dev/null 2>&1 || APT_NEEDED+=("protobuf-compiler")
+[[ -e /usr/lib/x86_64-linux-gnu/libnuma.so.1 || -e /lib/x86_64-linux-gnu/libnuma.so.1 ]] || APT_NEEDED+=("libnuma1")
+if [[ ${#APT_NEEDED[@]} -gt 0 ]]; then
+    apt-get update
+    apt-get install -y --no-install-recommends "${APT_NEEDED[@]}"
+fi
+protoc --version
+
+echo "--- :package: SGLang + LMCache install"
+SGLANG_URL="git+https://github.com/sgl-project/sglang.git@main#subdirectory=python"
+uv pip install "${SGLANG_URL}"
+export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LMCACHE="${SETUPTOOLS_SCM_PRETEND_VERSION_FOR_LMCACHE:-0.0.0+ci}"
+
+uv pip uninstall cupy-cuda12x 2>/dev/null || true
+uv pip install -e . --no-build-isolation
+
+python -c "import lmcache, sglang; print(f'sglang={sglang.__version__}; lmcache OK')"
+python -c "import cupy; print(f'cupy={cupy.__version__}')"
diff --git a/.buildkite/k3_harness/smoke-test.sh b/.buildkite/k3_harness/smoke-test.sh
new file mode 100755
index 0000000..7e7971d
--- /dev/null
+++ b/.buildkite/k3_harness/smoke-test.sh
@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Verify K3s + GPU Operator works: schedule a pod that runs nvidia-smi.
+set -euo pipefail
+
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+echo "=== Smoke Test ==="
+
+# 1. Check cluster
+echo "→ Cluster"
+kubectl get nodes -o wide
+echo ""
+
+# 2. Check GPU resources
+GPU_COUNT=$(kubectl get node -o jsonpath='{.items[0].status.allocatable.nvidia\.com/gpu}')
+echo "→ GPUs allocatable: ${GPU_COUNT}"
+if [[ "${GPU_COUNT}" -lt 1 ]]; then
+    echo "✗ No GPUs found on node"
+    exit 1
+fi
+
+# 3. Run GPU pod
+echo "→ Launching GPU test pod..."
+kubectl delete pod gpu-smoke-test --ignore-not-found --wait=false &>/dev/null
+
+cat <<'EOF' | kubectl apply -f -
+apiVersion: v1
+kind: Pod
+metadata:
+  name: gpu-smoke-test
+spec:
+  restartPolicy: Never
+  containers:
+    - name: test
+      image: nvidia/cuda:12.8.0-base-ubuntu24.04
+      command: ["nvidia-smi"]
+      resources:
+        limits:
+          nvidia.com/gpu: "1"
+EOF
+
+kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/gpu-smoke-test --timeout=120s
+echo ""
+echo "→ Pod logs:"
+kubectl logs gpu-smoke-test
+kubectl delete pod gpu-smoke-test
+
+echo ""
+echo "=== Smoke test passed ==="
diff --git a/.buildkite/k3_harness/teardown.sh b/.buildkite/k3_harness/teardown.sh
new file mode 100755
index 0000000..165b773
--- /dev/null
+++ b/.buildkite/k3_harness/teardown.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Tear down K3s stack. Removes: agent-stack-k8s, GPU Operator, K3s.
+# Host data volumes (/data/*) are NOT deleted.
+set -euo pipefail
+
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+
+echo "=== Teardown ==="
+
+# agent-stack-k8s
+if helm status agent-stack-k8s -n buildkite &>/dev/null; then
+    echo "→ Removing agent-stack-k8s..."
+    helm uninstall agent-stack-k8s -n buildkite --wait
+fi
+
+# GPU Operator
+if helm status gpu-operator -n gpu-operator &>/dev/null; then
+    echo "→ Removing GPU Operator..."
+    helm uninstall gpu-operator -n gpu-operator --wait
+    kubectl delete namespace gpu-operator --ignore-not-found
+fi
+
+# K3s
+if command -v k3s-uninstall.sh &>/dev/null; then
+    echo "→ Removing K3s..."
+    /usr/local/bin/k3s-uninstall.sh
+fi
+
+echo "✓ Teardown complete"
+echo "  Note: /data/{huggingface,datasets} preserved"
diff --git a/.buildkite/k3_harness/values.yaml b/.buildkite/k3_harness/values.yaml
new file mode 100644
index 0000000..04fa55e
--- /dev/null
+++ b/.buildkite/k3_harness/values.yaml
@@ -0,0 +1,25 @@
+# Reference Helm values for agent-stack-k8s.
+# install-agent-stack.sh sets these automatically.
+# This file is for documentation only.
+# Docs: https://github.com/buildkite/agent-stack-k8s
+
+agentToken: "<from install-agent-stack.sh>"
+
+config:
+  queue: "k8s"                              # override with BUILDKITE_QUEUE env var
+
+  # HTTPS checkout using GitHub token (replaces SSH key)
+  git-credentials-secret:
+    name: buildkite-git-creds               # created by install-agent-stack.sh
+    key: git-credentials                    # contains https://x-access-token:<token>@github.com
+
+  # Inject GITHUB_TOKEN into job containers for git push operations
+  pod-spec-patch:
+    containers:
+      - name: container-0
+        env:
+          - name: GITHUB_TOKEN
+            valueFrom:
+              secretKeyRef:
+                name: buildkite-git-creds
+                key: GITHUB_TOKEN
diff --git a/.buildkite/k3_tests/README.md b/.buildkite/k3_tests/README.md
new file mode 100644
index 0000000..dd7016b
--- /dev/null
+++ b/.buildkite/k3_tests/README.md
@@ -0,0 +1,154 @@
+# K8s Test Pipelines
+
+Each subdirectory under `k3_tests/` is a self-contained test with these files:
+
+| File | Purpose |
+|------|---------|
+| `run.sh` | Test script (sources `k3_harness/setup-env.sh`, then runs tests) |
+| `pipeline.yml` | K8s pod spec — GPU count, volumes, timeouts |
+| `buildkite-pipeline.yml` | What to paste into the Buildkite UI "Steps" editor (runs path filter, then uploads `pipeline.yml`) |
+| `BK_WEB_SETUP.md` | Full Buildkite UI setup instructions: env vars, trigger filters, recommendations |
+
+## Buildkite Web UI Setup
+
+### Prerequisites
+
+Before creating pipelines, make sure a queue named `k8s` exists in your Buildkite cluster. Go to **Organization Settings → Default cluster → Queues → New Queue** and create it. The queue needs no configuration and no agents — agent-stack-k8s creates ephemeral pod-based agents automatically when jobs arrive.
+
+### Per-pipeline setup
+
+For each test directory, create a pipeline in the Buildkite UI.
+Each directory has a `BK_WEB_SETUP.md` with the exact settings — env vars, GitHub trigger filters, and recommendations for that test. The short version:
+
+1. Go to your org → **New Pipeline**
+2. In the **Steps** editor, paste the contents of that test's `buildkite-pipeline.yml`:
+   ```yaml
+   agents:
+     queue: "k8s"
+
+   env:
+     HF_TOKEN: "<your HuggingFace token>"
+
+   steps:
+     - label: ":pipeline: Upload pipeline"
+       command: buildkite-agent pipeline upload .buildkite/k3_tests/<test-name>/pipeline.yml
+   ```
+   The `agents.queue` must match the queue you created above. This routes the upload step to agent-stack-k8s, which checks out the repo, runs the path filter, and (if the build isn't skipped) uploads the real `pipeline.yml`. Each subsequent step also targets the same queue.
+3. `HF_TOKEN` is needed for gated model access (e.g., Llama, Qwen). Set it in the `env` block as shown above, or under **Pipeline Settings → Environment Variables** in the UI — both work
+4. Under **GitHub Settings**, configure trigger filters per the test's `BK_WEB_SETUP.md`
+5. Save — jobs will run on the K8s queue automatically
+
+### Path-based skip (auto-pass on docs-only changes)
+
+The upload step in `buildkite-pipeline.yml` runs `common_scripts/upload-pipeline.sh`
+instead of `buildkite-agent pipeline upload` directly. The wrapper
+(`common_scripts/path-filter.sh`) inspects the changed files in the build and:
+
+- **Skips** the build (exits 0 without uploading `pipeline.yml` → build is
+  green with just the upload step) when *all* changed files match a "trivial"
+  pattern: `*.md`, `LICENSE*`, `NOTICE*`, `.gitignore`, `.gitattributes`,
+  `.editorconfig`, `.mailmap`, `CODEOWNERS`, or anything under `docs/` or
+  `.github/`. (`.github/` is trivial here because k3 tests run on Buildkite,
+  not GitHub Actions, so workflow / CODEOWNERS / template changes do not
+  affect them.)
+- **Force-runs** the build when any changed file lives under `.buildkite/` —
+  those PRs are usually fixing the k3 CI itself, so we want them tested on
+  the PR rather than after merge.
+- **Runs** the build whenever there is at least one non-trivial file by
+  uploading `pipeline.yml`, which contains the real test steps.
+
+Detection:
+- PR builds diff against `origin/${BUILDKITE_PULL_REQUEST_BASE_BRANCH}`
+  (default `main`) using the merge-base.
+- Push builds diff `HEAD~1..HEAD`.
+- Scheduled builds (`BUILDKITE_SOURCE=schedule`) are never skipped.
+- If the script can't determine the changed files (shallow clone with no
+  parent, missing base branch, etc.) it falls back to "do not skip".
+
+To bypass the skip and force a full run, add the **`force-ci`** label to the
+PR on GitHub. Buildkite picks up PR labels automatically; when the filter
+sees `force-ci` it runs the full pipeline regardless of which files changed.
+
+### Trigger strategy
+
+Not all tests should run on every push. The general pattern:
+
+| Test weight | When to trigger | Example filter condition |
+|-------------|----------------|------------------------|
+| Lightweight (1 GPU, <20 min) | Every push / every PR | *(no filter)* |
+| Heavy (multi-GPU, >30 min) | PR label or main branch only | `build.pull_request.labels includes "full" \|\| build.branch == 'dev'` |
+
+Set **"Rebuild on PR label change"** to `Yes` for label-triggered pipelines so adding a label to an existing PR kicks off the build.
+
+## Adding a New Test
+
+1. Create a directory: `.buildkite/k3_tests/<test-name>/`
+
+2. Write a `run.sh` that sources the shared environment setup:
+   ```bash
+   #!/usr/bin/env bash
+   set -euo pipefail
+   cd "$(cd "$(dirname "$0")/../../.." && pwd)"
+   source .buildkite/k3_harness/setup-env.sh
+   # ... your test commands ...
+   ```
+
+3. Write a `pipeline.yml`. Set the GPU limit to what your test needs:
+   ```yaml
+   steps:
+     - label: ":test_tube: My Test"
+       command: .buildkite/k3_tests/<test-name>/run.sh
+       timeout_in_minutes: 30
+       agents: { queue: "k8s" }
+       plugins:
+         - kubernetes:
+             podSpec:
+               containers:
+                 - name: container-0
+                   image: lmcache/ci-base:latest
+                   imagePullPolicy: Never  # local image, imported into K3s containerd
+                   resources:
+                     limits:
+                       nvidia.com/gpu: "1"
+                   volumeMounts:
+                     - { name: hf-cache, mountPath: /root/.cache/huggingface }
+               volumes:
+                 - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+   ```
+
+4. Write a `buildkite-pipeline.yml` (the snippet pasted into the Buildkite UI's Steps
+   editor). Use `common_scripts/upload-pipeline.sh` so the test gets path-based skip:
+   ```yaml
+   agents:
+     queue: "k8s"
+
+   steps:
+     - label: ":pipeline: Upload pipeline"
+       command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/<test-name>/pipeline.yml
+   ```
+
+5. Write a `BK_WEB_SETUP.md` documenting the Buildkite UI settings for this test (env vars, trigger filters, recommendations). Use an existing test's `BK_WEB_SETUP.md` as a template.
+
+6. `chmod +x` your `run.sh` and create the pipeline in the Buildkite UI.
+
+### Optional: datasets volume
+
+If your test needs pre-downloaded data (e.g., ShareGPT), add the datasets volume:
+```yaml
+volumeMounts:
+  - { name: datasets, mountPath: /root/correctness }
+volumes:
+  - { name: datasets, hostPath: { path: /data/datasets, type: DirectoryOrCreate } }
+```
+
+### Optional: Docker-in-Docker
+
+If your test runs Docker containers inside the pod:
+```yaml
+securityContext:
+  privileged: true
+volumeMounts:
+  - { name: docker-sock, mountPath: /var/run/docker.sock }
+volumes:
+  - { name: docker-sock, hostPath: { path: /var/run/docker.sock } }
+```
diff --git a/.buildkite/k3_tests/blend/buildkite-pipeline.yml b/.buildkite/k3_tests/blend/buildkite-pipeline.yml
new file mode 100644
index 0000000..327d74e
--- /dev/null
+++ b/.buildkite/k3_tests/blend/buildkite-pipeline.yml
@@ -0,0 +1,20 @@
+# Paste this into the Buildkite pipeline's "Steps" editor.
+# It uploads the real pipeline definition from the repo.
+#
+# Fill in HF_TOKEN (gated model access), GH_TOKEN (read access to the private
+# plugin repo), and CB_PLUGIN_REPO (owner/name of the plugin repo). CB_PLUGIN_REF
+# selects which plugin commit to test the PR against; CB_PLUGIN_DIR is the clone
+# destination in the pod.
+agents:
+  queue: "k8s"
+
+env:
+  HF_TOKEN: ""                   # HuggingFace token — gated model access (e.g. Llama)
+  GH_TOKEN: ""                   # GitHub token — read access to the private plugin repo
+  CB_PLUGIN_REPO: ""             # owner/name of the plugin repo (required; set here or in the UI)
+  CB_PLUGIN_REF: "main"          # plugin git ref to test the PR against
+  CB_PLUGIN_DIR: "/tmp/cb-plugin"  # clone destination in the pod
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/blend/pipeline.yml
diff --git a/.buildkite/k3_tests/blend/pipeline.yml b/.buildkite/k3_tests/blend/pipeline.yml
new file mode 100644
index 0000000..9665dd0
--- /dev/null
+++ b/.buildkite/k3_tests/blend/pipeline.yml
@@ -0,0 +1,34 @@
+# CacheBlend <-> LMCache compatibility test.
+#
+# Builds the PR's LMCache from source (compiling c_ops for the pod's GPU arch),
+# pulls the external cacheblend-plugin from GitHub, installs it editable, and
+# runs the plugin's vllm_compat_check (--skip-correctness): one blend server +
+# vLLM stack, five V3 contract checks ending in a non-prefix blend that must
+# engage. Catches LMCache changes that break the external plugin *before* merge
+# — the recurring rebase/version-skew class (RPC key renames, handler-signature
+# drift, KV-layout changes, etc.).
+#
+# Needs one GPU. Set HF_TOKEN (gated model) and GH_TOKEN (private plugin repo)
+# in the Buildkite UI — see BK_WEB_SETUP.md.
+
+steps:
+  - label: ":jigsaw: CacheBlend plugin compat (Llama-8B)"
+    command: .buildkite/k3_tests/blend/run.sh
+    timeout_in_minutes: 30
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never  # local image, imported into K3s containerd
+                resources:
+                  limits:
+                    nvidia.com/gpu: "1"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "cb_compat_logs/**/*"
diff --git a/.buildkite/k3_tests/blend/run.sh b/.buildkite/k3_tests/blend/run.sh
new file mode 100755
index 0000000..44626eb
--- /dev/null
+++ b/.buildkite/k3_tests/blend/run.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+ 
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+
+# ── Environment setup ────────────────────────────────────────
+source .buildkite/k3_harness/setup-blend-env.sh
+
+# ── Ensure all scripts are executable ────────────────────────
+chmod +x "${SCRIPT_DIR}"/scripts/*.sh
+
+# ── Run the actual test logic ────────────────────────────────
+exec bash "${SCRIPT_DIR}/scripts/run-compat.sh" "$@"
diff --git a/.buildkite/k3_tests/blend/scripts/run-compat.sh b/.buildkite/k3_tests/blend/scripts/run-compat.sh
new file mode 100755
index 0000000..2ec8799
--- /dev/null
+++ b/.buildkite/k3_tests/blend/scripts/run-compat.sh
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# CacheBlend <-> LMCache compatibility check.
+#
+ 
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+source .buildkite/k3_tests/common_scripts/helpers.sh
+
+# Fail fast if the GPUs are occupied by stale host processes.
+check_gpu_health 80
+
+: "${CB_PLUGIN_DIR:?CB_PLUGIN_DIR not set — source k3_harness/setup-blend-env.sh first}"
+
+MODEL="${CB_MODEL:-meta-llama/Llama-3.1-8B-Instruct}"
+MAX_LEN="${CB_MAX_MODEL_LEN:-16384}"
+LOG_DIR="${REPO_ROOT}/cb_compat_logs"      # workspace-relative so artifact_paths can collect it
+mkdir -p "${LOG_DIR}"
+
+# Resolve the venv that owns vllm/lmcache. In the CI pod this is the image's
+# /opt/venv (on PATH via setup-env.sh); CB_VENV overrides for local runs.
+if [ -n "${CB_VENV:-}" ]; then
+    VENV="${CB_VENV}"
+elif [ -n "${VIRTUAL_ENV:-}" ]; then
+    VENV="${VIRTUAL_ENV}"
+elif command -v vllm >/dev/null 2>&1; then
+    VENV="$(cd "$(dirname "$(command -v vllm)")/.." && pwd)"
+else
+    VENV="/opt/venv"
+fi
+
+echo "+++ :jigsaw: vllm_compat_check  model=${MODEL}  venv=${VENV}  plugin=${CB_PLUGIN_DIR}"
+python "${CB_PLUGIN_DIR}/.buildkite/harness/vllm_compat_check.py" \
+    --model "${MODEL}" \
+    --gpu-sync 0 \
+    --skip-correctness \
+    --venv "${VENV}" \
+    --max-model-len "${MAX_LEN}" \
+    --log-dir "${LOG_DIR}"
diff --git a/.buildkite/k3_tests/common_scripts/helpers.sh b/.buildkite/k3_tests/common_scripts/helpers.sh
new file mode 100755
index 0000000..770c424
--- /dev/null
+++ b/.buildkite/k3_tests/common_scripts/helpers.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Shared helper functions for K3s test scripts.
+# Source this file from every scripts/*.sh.
+
+# Track background PIDs for cleanup
+TRACKED_PIDS=()
+
+# Check that all visible GPUs have sufficient free memory.
+# Fails fast with a clear message if a host-level process is hogging GPU memory.
+# Usage: check_gpu_health [min_free_percent]
+#   min_free_percent: minimum percentage of GPU memory that must be free (default: 80)
+check_gpu_health() {
+    local min_free_pct="${1:-80}"
+    echo "--- :mag: GPU health check (require ${min_free_pct}% free memory)"
+
+    if ! command -v nvidia-smi &>/dev/null; then
+        echo "  nvidia-smi not found, skipping GPU health check"
+        return 0
+    fi
+
+    # Parse GPU info into a temp file to avoid subshell variable scoping issues
+    local gpu_info
+    gpu_info=$(nvidia-smi --query-gpu=index,memory.total,memory.used,memory.free --format=csv,noheader,nounits 2>/dev/null | sed 's/ //g')
+
+    if [[ -z "$gpu_info" ]]; then
+        echo "  No GPUs detected, skipping"
+        return 0
+    fi
+
+    local has_problem=false
+    while IFS=, read -r idx total used free; do
+
+        if [[ "$total" -eq 0 ]]; then
+            continue
+        fi
+
+        local free_pct=$((free * 100 / total))
+
+        if [[ "$free_pct" -lt "$min_free_pct" ]]; then
+            echo "  WARNING: GPU $idx has only ${free_pct}% free (${free} MiB free / ${total} MiB total, ${used} MiB used)"
+            # Show which processes are using this GPU
+            nvidia-smi --query-compute-apps=pid,gpu_uuid,used_memory --format=csv,noheader -i "$idx" 2>/dev/null | while IFS= read -r proc; do
+                echo "    Process: $proc"
+            done
+            has_problem=true
+        else
+            echo "  GPU $idx: OK (${free_pct}% free, ${free} MiB / ${total} MiB)"
+        fi
+    done <<< "$gpu_info"
+
+    if [[ "$has_problem" == "true" ]]; then
+        echo ""
+        echo "FATAL: One or more GPUs have insufficient free memory."
+        echo "This usually means a stale process on the host is consuming GPU memory."
+        echo "Check the host with: nvidia-smi"
+        echo "To fix: kill the offending host processes, then re-run the CI job."
+        return 1
+    fi
+
+    echo "  All GPUs healthy."
+    return 0
+}
+
+# Find an available TCP port starting from a given port number.
+# Usage: find_free_port [start_port]
+find_free_port() {
+    local port="${1:-8000}"
+    while [ "$port" -lt 65536 ]; do
+        if ! lsof -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1 &&
+           ! timeout 1 bash -c "</dev/tcp/127.0.0.1/${port}" 2>/dev/null; then
+            echo "$port"
+            return 0
+        fi
+        ((port++))
+    done
+    echo "ERROR: No available port found starting from ${1:-8000}" >&2
+    return 1
+}
+
+# Wait for a vLLM server to become ready by polling /v1/models.
+# Usage: wait_for_server <port> [timeout_secs] [log_file]
+# If log_file is provided, its tail is dumped to stderr on timeout so the
+# real failure (e.g. an ImportError during startup) is visible inline in the
+# job output instead of requiring a trip through build artifacts.
+wait_for_server() {
+    local port="$1"
+    local timeout="${2:-180}"
+    local log_file="${3:-}"
+    echo "Waiting for vLLM on port $port (timeout=${timeout}s)..."
+    for ((i = 0; i < timeout; i++)); do
+        if curl -sf "http://localhost:${port}/v1/models" >/dev/null 2>&1; then
+            echo "vLLM ready on port $port (${i}s)"
+            return 0
+        fi
+        sleep 1
+    done
+    echo "vLLM failed to start on port $port within ${timeout}s" >&2
+    if [[ -n "$log_file" && -f "$log_file" ]]; then
+        echo "--- :page_facing_up: Last 200 lines of ${log_file}" >&2
+        tail -n 200 "$log_file" >&2
+    fi
+    return 1
+}
+
+# Kill all tracked background PIDs and wait for them.
+# Call this in a trap handler.
+cleanup_pids() {
+    echo "--- Cleaning up background processes..."
+    for pid in "${TRACKED_PIDS[@]}"; do
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "  Killing PID $pid"
+            kill "$pid" 2>/dev/null || true
+            wait "$pid" 2>/dev/null || true
+        fi
+    done
+    TRACKED_PIDS=()
+    # Give GPU memory a moment to release
+    sleep 2
+}
diff --git a/.buildkite/k3_tests/common_scripts/path-filter.sh b/.buildkite/k3_tests/common_scripts/path-filter.sh
new file mode 100755
index 0000000..7b99f2b
--- /dev/null
+++ b/.buildkite/k3_tests/common_scripts/path-filter.sh
@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Path filter: decide whether a CI build can be skipped based on which files
+# changed since the base commit.
+#
+# Usage:
+#   source path-filter.sh
+#   if should_skip_ci; then
+#       # all changed files are trivial (docs, etc.)
+#   fi
+#
+# Rules:
+#   - If ANY changed file lives under .buildkite/, the build runs.
+#     (Those PRs are usually fixing the k3 CI itself, so we want to test on
+#     the PR instead of waiting for it to land on main.)
+#   - Otherwise, if EVERY changed file matches a "trivial" pattern (markdown,
+#     LICENSE, anything under docs/ or .github/, etc.), the build can be
+#     skipped. .github/ is trivial for k3 because k3 tests run on Buildkite,
+#     not GitHub Actions, so workflow/CODEOWNERS/template changes do not
+#     affect what the k3 tests do.
+#   - Anything else → build runs.
+#
+# Opt-out: add a "force-ci" label to the PR on GitHub. Buildkite exposes
+# PR labels via BUILDKITE_PULL_REQUEST_LABELS; if "force-ci" is present
+# the filter is bypassed and the full pipeline runs.
+#
+# Detection of "changed files":
+#   - PR builds  → diff against the merge-base with BUILDKITE_PULL_REQUEST_BASE_BRANCH.
+#   - Push builds → diff HEAD~1..HEAD.
+#   - Anything we can't figure out → fall back to "do not skip".
+
+set -uo pipefail
+
+# ── Pattern lists ─────────────────────────────────────────────
+# bash `case` patterns: `*` matches any string including `/`, so `docs/*`
+# matches `docs/foo/bar.png` as well as `docs/foo`.
+
+_path_filter_is_always_trigger() {
+    case "$1" in
+        .buildkite/*) return 0 ;;
+    esac
+    return 1
+}
+
+_path_filter_is_trivial() {
+    case "$1" in
+        *.md) return 0 ;;
+        LICENSE|LICENSE.*) return 0 ;;
+        NOTICE|NOTICE.*) return 0 ;;
+        .gitignore|.gitattributes|.editorconfig|.mailmap) return 0 ;;
+        CODEOWNERS) return 0 ;;
+        docs/*) return 0 ;;
+        .github/*) return 0 ;;
+    esac
+    return 1
+}
+
+# ── Changed-files detection ───────────────────────────────────
+
+_path_filter_get_changed_files() {
+    local base_branch base merge_base
+
+    # Ephemeral pods may not have GitHub's SSH host key yet.
+    # Accept new keys automatically so git-fetch doesn't hang on a prompt.
+    export GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=accept-new -o LogLevel=ERROR"
+
+    if [[ -n "${BUILDKITE_PULL_REQUEST:-}" && "${BUILDKITE_PULL_REQUEST:-}" != "false" ]]; then
+        base_branch="${BUILDKITE_PULL_REQUEST_BASE_BRANCH:-main}"
+        # Buildkite checks out shallow; fetch enough history to find the merge-base.
+        git fetch --no-tags --depth=200 origin "$base_branch" 2>/dev/null || \
+            git fetch --no-tags origin "$base_branch" 2>/dev/null || true
+
+        if base=$(git rev-parse --verify "origin/${base_branch}" 2>/dev/null); then
+            if merge_base=$(git merge-base HEAD "$base" 2>/dev/null); then
+                git diff --name-only "$merge_base" HEAD
+                return 0
+            fi
+            # No merge-base (history not deep enough): diff directly.
+            git diff --name-only "$base" HEAD
+            return 0
+        fi
+        echo "path-filter: could not resolve origin/${base_branch}" >&2
+        return 1
+    fi
+
+    # Push build (or unknown context): diff against the previous commit.
+    if git rev-parse --verify HEAD~1 >/dev/null 2>&1; then
+        git diff --name-only HEAD~1 HEAD
+        return 0
+    fi
+
+    echo "path-filter: no parent commit available" >&2
+    return 1
+}
+
+# ── Public entry point ────────────────────────────────────────
+
+# Returns 0 if the build can be safely skipped, non-zero otherwise.
+# Prints a classification of every changed file to stderr for the build log.
+should_skip_ci() {
+    # PR label opt-out: adding "force-ci" on GitHub forces a full run.
+    if [[ ",${BUILDKITE_PULL_REQUEST_LABELS:-}," == *",force-ci,"* ]]; then
+        echo "path-filter: PR has 'force-ci' label → not skipping" >&2
+        return 1
+    fi
+
+    # Never skip scheduled builds (e.g. nightly baselines with NEED_UPLOAD=true).
+    if [[ "${BUILDKITE_SOURCE:-}" == "schedule" ]]; then
+        echo "path-filter: scheduled build (BUILDKITE_SOURCE=schedule) → not skipping" >&2
+        return 1
+    fi
+
+    local changed_files
+    if ! changed_files=$(_path_filter_get_changed_files); then
+        echo "path-filter: could not determine changed files → not skipping" >&2
+        return 1
+    fi
+
+    if [[ -z "$changed_files" ]]; then
+        echo "path-filter: no changed files reported → not skipping (safer default)" >&2
+        return 1
+    fi
+
+    local has_always_trigger=0
+    local has_non_trivial=0
+    local trivial_count=0
+    local total=0
+
+    echo "path-filter: classifying changed files:" >&2
+    while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        total=$((total + 1))
+        if _path_filter_is_always_trigger "$f"; then
+            has_always_trigger=1
+            echo "  [force-trigger] $f" >&2
+        elif _path_filter_is_trivial "$f"; then
+            trivial_count=$((trivial_count + 1))
+            echo "  [trivial]       $f" >&2
+        else
+            has_non_trivial=1
+            echo "  [non-trivial]   $f" >&2
+        fi
+    done <<< "$changed_files"
+
+    echo "path-filter: ${total} files changed (${trivial_count} trivial)" >&2
+
+    if [[ "$has_always_trigger" -eq 1 ]]; then
+        echo "path-filter: at least one file under .buildkite/ → not skipping" >&2
+        return 1
+    fi
+
+    if [[ "$has_non_trivial" -eq 1 ]]; then
+        echo "path-filter: non-trivial files changed → not skipping" >&2
+        return 1
+    fi
+
+    echo "path-filter: all changed files are trivial → SKIP" >&2
+    return 0
+}
diff --git a/.buildkite/k3_tests/common_scripts/upload-pipeline.sh b/.buildkite/k3_tests/common_scripts/upload-pipeline.sh
new file mode 100755
index 0000000..361808e
--- /dev/null
+++ b/.buildkite/k3_tests/common_scripts/upload-pipeline.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Wraps `buildkite-agent pipeline upload` with a path-based skip check.
+#
+# Usage (called from each test's buildkite-pipeline.yml upload step):
+#   command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh \
+#       .buildkite/k3_tests/<test-name>/pipeline.yml
+#
+# If every changed file in this build is trivial (markdown, LICENSE, .github,
+# etc.) and none touch .buildkite/, this script:
+#   - Annotates the build with a "skipped" note
+#   - Exits 0 without uploading any further steps → the build is green
+# Otherwise it execs `buildkite-agent pipeline upload <pipeline.yml>`, adding
+# the real test steps to the build.
+#
+# Add a "force-ci" label to the PR on GitHub to bypass the check.
+
+set -euo pipefail
+
+PIPELINE_FILE="${1:?Usage: upload-pipeline.sh <path/to/pipeline.yml>}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# shellcheck source=path-filter.sh
+source "${SCRIPT_DIR}/path-filter.sh"
+
+if should_skip_ci; then
+    echo "+++ :fast_forward: Skipping CI — only trivial files changed"
+    if command -v buildkite-agent >/dev/null 2>&1; then
+        buildkite-agent annotate \
+            --style success \
+            --context "path-filter-skip" \
+            "Skipped: only trivial files (docs, license, etc.) changed. Add a \`force-ci\` label to the PR to force a full run." \
+            || true
+    fi
+    exit 0
+fi
+
+echo "--- :pipeline: Uploading ${PIPELINE_FILE}"
+exec buildkite-agent pipeline upload "${PIPELINE_FILE}"
diff --git a/.buildkite/k3_tests/comprehensive/BK_WEB_SETUP.md b/.buildkite/k3_tests/comprehensive/BK_WEB_SETUP.md
new file mode 100644
index 0000000..a37b8dd
--- /dev/null
+++ b/.buildkite/k3_tests/comprehensive/BK_WEB_SETUP.md
@@ -0,0 +1,27 @@
+# Buildkite Web UI Setup: Comprehensive Tests
+
+**Steps editor**: paste contents of `buildkite-pipeline.yml` (fill in `HF_TOKEN`).
+
+**GitHub trigger settings**:
+- Filter: `build.pull_request.labels includes "full" || build.branch == 'dev'`
+- Rebuild on PR label change: Yes
+- Skip queued / cancel running branch builds: Yes
+
+Heavy test (10 parallel GPU steps) — run on `"full"` label or dev push, not every PR.
+
+> Builds whose only changes are docs/`*.md`/`LICENSE`/`.github/**` auto-pass
+> via the [path filter](../README.md#path-based-skip-auto-pass-on-docs-only-changes).
+> Changes under `.buildkite/` always run. Add `force-ci` label to the PR to
+> bypass.
+
+## Nightly Scheduled Build (rolling baselines)
+
+Create a **Scheduled Build** on this same pipeline to upload performance baselines:
+
+- **Schedule**: daily (e.g. `0 2 * * *` — 2am UTC)
+- **Branch**: `dev`
+- **Extra Environment Variables**: `NEED_UPLOAD=true`
+
+Each config step writes a date-stamped baseline (`<feature>-YYYYMMDD.json`) as a Buildkite artifact. The finalize step (`scripts/upload-baselines.sh`) collects them all, prunes files older than 5 days, and pushes a single commit to the `benchmarks-main` branch.
+
+PR builds automatically compare against the rolling 5-day worst-case (max latency) baseline.
diff --git a/.buildkite/k3_tests/comprehensive/buildkite-pipeline.yml b/.buildkite/k3_tests/comprehensive/buildkite-pipeline.yml
new file mode 100644
index 0000000..559fa29
--- /dev/null
+++ b/.buildkite/k3_tests/comprehensive/buildkite-pipeline.yml
@@ -0,0 +1,11 @@
+# Paste this into the Buildkite pipeline's "Steps" editor.
+# It uploads the real pipeline definition from the repo.
+agents:
+  queue: "k8s"
+
+env:
+  HF_TOKEN: ""  # set your HuggingFace token here (needed for gated model access)
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/comprehensive/pipeline.yml
diff --git a/.buildkite/k3_tests/comprehensive/pipeline.yml b/.buildkite/k3_tests/comprehensive/pipeline.yml
new file mode 100644
index 0000000..8d80ca5
--- /dev/null
+++ b/.buildkite/k3_tests/comprehensive/pipeline.yml
@@ -0,0 +1,143 @@
+# Comprehensive integration tests — one step per config, run in parallel.
+# Each step gets its own K8s pod with the exact GPU count it needs.
+# 2-GPU group is listed first so these heavier jobs get scheduled before 1-GPU jobs.
+
+x-perf-retry: &perf-retry
+  automatic:
+    - exit_status: -1
+      limit: 2
+    - exit_status: 1
+      limit: 2
+
+steps:
+  - group: ":test_tube: Comprehensive (2-GPU)"
+    steps:
+      - label: ":test_tube: pd"
+        command: .buildkite/k3_tests/comprehensive/run.sh pd.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec: &pod-2gpu
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources: { limits: { "nvidia.com/gpu": "2" } }
+                    volumeMounts: &vol-mounts
+                      - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                      - { name: datasets, mountPath: /root/correctness }
+                volumes: &vols
+                  - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+                  - { name: datasets, hostPath: { path: /data/datasets, type: DirectoryOrCreate } }
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: p2p"
+        command: .buildkite/k3_tests/comprehensive/run.sh p2p.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-2gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: p2p_with_v3"
+        command: .buildkite/k3_tests/comprehensive/run.sh p2p_with_v3.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-2gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+  - group: ":test_tube: Comprehensive (1-GPU)"
+    steps:
+      - label: ":test_tube: local_cpu"
+        command: .buildkite/k3_tests/comprehensive/run.sh local_cpu.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec: &pod-1gpu
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources: { limits: { "nvidia.com/gpu": "1" } }
+                    volumeMounts: *vol-mounts
+                volumes: *vols
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: local_disk"
+        command: .buildkite/k3_tests/comprehensive/run.sh local_disk.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: async"
+        command: .buildkite/k3_tests/comprehensive/run.sh async.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: local_cpu_with_v3"
+        command: .buildkite/k3_tests/comprehensive/run.sh local_cpu_with_v3.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: local_disk_with_v3"
+        command: .buildkite/k3_tests/comprehensive/run.sh local_disk_with_v3.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: multi_device"
+        command: .buildkite/k3_tests/comprehensive/run.sh multi_device.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+      - label: ":test_tube: layerwise"
+        command: .buildkite/k3_tests/comprehensive/run.sh layerwise.yaml
+        timeout_in_minutes: 30
+        retry: *perf-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log", "benchmarks/long_doc_qa/*.json"]
+
+  # Nightly baseline upload: only runs when NEED_UPLOAD=true (scheduled build).
+  # Collects date-stamped baseline artifacts from all config steps,
+  # prunes files older than 5 days, and pushes a single commit to benchmarks-main.
+  - wait: ~
+    if: build.env("NEED_UPLOAD") == "true"
+
+  - label: ":arrow_up: Upload rolling baselines"
+    if: build.env("NEED_UPLOAD") == "true"
+    command: .buildkite/k3_tests/comprehensive/scripts/upload-baselines.sh
+    timeout_in_minutes: 5
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources: { limits: { cpu: "1", memory: "2Gi" } }
+                env:
+                  - name: GITHUB_TOKEN
+                    valueFrom:
+                      secretKeyRef:
+                        name: buildkite-git-creds
+                        key: GITHUB_TOKEN
diff --git a/.buildkite/k3_tests/comprehensive/run.sh b/.buildkite/k3_tests/comprehensive/run.sh
new file mode 100755
index 0000000..1b1186d
--- /dev/null
+++ b/.buildkite/k3_tests/comprehensive/run.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Comprehensive integration test entrypoint for K8s pods.
+# Usage: run.sh <config.yaml>
+# Thin wrapper: sets up environment, then delegates to scripts/.
+set -euo pipefail
+
+CFG_NAME="${1:?Usage: $0 <config.yaml>}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+
+# ── Environment setup ────────────────────────────────────────
+source .buildkite/k3_harness/setup-env.sh
+
+# Install test utilities (yq for YAML parsing, jq for JSON, openai/pandas/matplotlib for benchmarks)
+uv pip install yq jq openai pandas matplotlib 2>/dev/null || true
+
+# ── Ensure all scripts are executable ────────────────────────
+chmod +x "${SCRIPT_DIR}"/scripts/*.sh
+
+# ── Run the actual test logic ────────────────────────────────
+exec bash "${SCRIPT_DIR}/scripts/run-single-config.sh" "$CFG_NAME"
diff --git a/.buildkite/k3_tests/comprehensive/scripts/run-single-config.sh b/.buildkite/k3_tests/comprehensive/scripts/run-single-config.sh
new file mode 100755
index 0000000..43d6790
--- /dev/null
+++ b/.buildkite/k3_tests/comprehensive/scripts/run-single-config.sh
@@ -0,0 +1,531 @@
+#!/usr/bin/env bash
+# Comprehensive integration test: run a single config natively in a K8s pod.
+# Replaces the old Docker-based vllm-integration-tests.sh.
+#
+# Usage: run-single-config.sh <config.yaml>
+set -euo pipefail
+
+CFG_NAME="${1:?Usage: $0 <config.yaml>}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+source .buildkite/k3_tests/common_scripts/helpers.sh
+
+CONFIG_DIR="${REPO_ROOT}/.buildkite/configs"
+LOGFILE="${REPO_ROOT}/${CFG_NAME%.yaml}.log"
+BUILD_ID="${BUILDKITE_BUILD_ID:-local_$$}"
+NEED_UPLOAD="${NEED_UPLOAD:-false}"
+SERVER_WAIT_TIMEOUT="${SERVER_WAIT_TIMEOUT:-240}"
+
+# Tee all output so Buildkite can collect it as an artifact
+exec > >(tee -a "$LOGFILE") 2>&1
+
+# ── Validate config ──────────────────────────────────────────
+cfg_file="${CONFIG_DIR}/${CFG_NAME}"
+if [[ ! -f "$cfg_file" ]]; then
+    echo "Config not found: ${cfg_file}"
+    exit 1
+fi
+
+feature_type=$(yq -r '.feature.type // ""' "$cfg_file")
+echo -e "\033[1;33m===== Testing LMCache with ${CFG_NAME} (type=${feature_type:-standard}) =====\033[0m"
+
+# Prevent git from hanging on prompts
+export GIT_TERMINAL_PROMPT=0
+
+# PID tracking for cleanup
+PIDS=()
+on_exit() {
+    local rc=$?
+    echo "--- Cleaning up (exit code: $rc)..."
+    for p in "${PIDS[@]}"; do
+        kill "$p" 2>/dev/null || true
+        wait "$p" 2>/dev/null || true
+    done
+    # Copy vLLM server logs to repo root so Buildkite can collect them as artifacts
+    cp /tmp/build_${BUILD_ID}_${CFG_NAME%.yaml}*.log "${REPO_ROOT}/" 2>/dev/null || true
+    sleep 5
+}
+trap on_exit EXIT INT TERM
+
+###############
+# UTILITIES   #
+###############
+
+# Start a vLLM process natively (no Docker).
+# Reads env vars from a yq-extracted docker section and vllm args from a vllm section.
+start_single_server() {
+    local docker_section="$1"
+    local vllm_section="$2"
+    local port="$3"
+    local gpu="${4:-}"
+    local logfile="${5:-/tmp/build_${BUILD_ID}_${CFG_NAME%.yaml}.log}"
+
+    # Collect env vars from docker.env[]
+    local -a env_cmd=()
+    while IFS= read -r e; do
+        [[ -n "$e" ]] && env_cmd+=("$e")
+    done < <(yq -r '.env[]?' <<<"$docker_section")
+
+    # Standard env vars
+    env_cmd+=("VLLM_USE_FLASHINFER_SAMPLER=0")
+    [[ -n "${HF_TOKEN:-}" ]] && env_cmd+=("HF_TOKEN=${HF_TOKEN}")
+    [[ -n "$gpu" ]] && env_cmd+=("CUDA_VISIBLE_DEVICES=${gpu}")
+
+    # Override socket prefix so each server gets its own socket directory.
+    # In the old Docker setup, a volume mount mapped /tmp/lmcache_internal_api_server
+    # inside the container to /tmp/lmcache_internal_api_server/${port} on the host.
+    # Without Docker, we replicate this by setting the prefix to include the port.
+    mkdir -p "/tmp/lmcache_internal_api_server/${port}"
+    env_cmd+=("LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX=/tmp/lmcache_internal_api_server/${port}/socket")
+
+    # Parse vllm model and args
+    local vllm_model
+    vllm_model="$(yq -r '.model' <<<"$vllm_section")"
+    local -a vllm_cli_args=()
+    mapfile -t vllm_cli_args < <(yq -r '.args // [] | .[]' <<<"$vllm_section")
+
+    echo "Starting vLLM: model=$vllm_model port=$port gpu=${gpu:-all}"
+    env "${env_cmd[@]}" \
+        vllm serve "$vllm_model" "${vllm_cli_args[@]}" --port "$port" \
+        >"$logfile" 2>&1 &
+    local pid=$!
+    PIDS+=("$pid")
+    echo "  PID=$pid log=$logfile"
+
+    # Wait for readiness
+    if ! wait_for_server "$port" "$SERVER_WAIT_TIMEOUT"; then
+        echo "Server failed to start. Last 50 lines of log:"
+        tail -50 "$logfile" || true
+        return 1
+    fi
+}
+
+###############
+# LAUNCH      #
+###############
+
+PORT=$(find_free_port 8000)
+PORT1=""
+PORT2=""
+model=""
+
+if [[ "$feature_type" == "pd" ]]; then
+    # ── Prefiller-Decoder mode (2 GPUs) ─────────────────────
+    PORT1=$(find_free_port 8100)
+    PORT2=$(find_free_port $((PORT1 + 100)))
+
+    prefiller_docker="$(yq '.["docker-prefiller"]' "$cfg_file")"
+    prefiller_vllm="$(yq '.["vllm-prefiller"]' "$cfg_file")"
+    decoder_docker="$(yq '.["docker-decoder"]' "$cfg_file")"
+    decoder_vllm="$(yq '.["vllm-decoder"]' "$cfg_file")"
+    model="$(yq -r '.["vllm-prefiller"].model' "$cfg_file")"
+
+    # Extra PD env vars
+    proxy=$(yq -er '.["docker-prefiller"]["proxy-port"]' "$cfg_file" 2>/dev/null || echo "7500")
+    init=$(yq -er '.["docker-decoder"]["init-port"]' "$cfg_file" 2>/dev/null || echo "7300")
+    alloc=$(yq -er '.["docker-decoder"]["alloc-port"]' "$cfg_file" 2>/dev/null || echo "7400")
+
+    # Inject PD-specific env vars into docker sections
+    prefiller_docker=$(echo "$prefiller_docker" | yq -y --arg proxy "$proxy" '. + {"env": (.env + ["LMCACHE_PD_PROXY_PORT=" + $proxy])}')
+    decoder_docker=$(echo "$decoder_docker" | yq -y --arg init "$init" --arg alloc "$alloc" '. + {"env": (.env + ["LMCACHE_PD_PEER_INIT_PORT=" + $init, "LMCACHE_PD_PEER_ALLOC_PORT=" + $alloc])}')
+
+    echo "--- Starting prefiller on port $PORT1 (GPU 0)"
+    # Prefiller needs UCX_TLS for NIXL transport
+    prefiller_docker=$(echo "$prefiller_docker" | yq -y ". + {\"env\": (.env + [\"UCX_TLS=cuda_ipc,cuda_copy,tcp\"])}")
+    start_single_server "$prefiller_docker" "$prefiller_vllm" "$PORT1" "0" \
+        "${REPO_ROOT}/${CFG_NAME%.yaml}-prefiller.log"
+
+    echo "--- Starting decoder on port $PORT2 (GPU 1)"
+    decoder_docker=$(echo "$decoder_docker" | yq -y ". + {\"env\": (.env + [\"UCX_TLS=cuda_ipc,cuda_copy,tcp\"])}")
+    start_single_server "$decoder_docker" "$decoder_vllm" "$PORT2" "1" \
+        "${REPO_ROOT}/${CFG_NAME%.yaml}-decoder.log"
+
+    # Start disagg proxy
+    echo "--- Starting PD proxy on port $PORT"
+    python3 "${REPO_ROOT}/examples/disagg_prefill/disagg_proxy_server.py" \
+        --port "$PORT" \
+        --prefiller-port "$PORT1" \
+        --decoder-port "$PORT2" \
+        --decoder-init-port "$init" \
+        --decoder-alloc-port "$alloc" \
+        --proxy-port "$proxy" \
+        > "${REPO_ROOT}/${CFG_NAME%.yaml}-proxy.log" 2>&1 &
+    PIDS+=($!)
+    sleep 10
+
+elif [[ "$feature_type" == "p2p" ]]; then
+    # ── Peer-to-Peer mode (2 GPUs) ──────────────────────────
+    PORT1=$(find_free_port 8177)
+    PORT2=$(find_free_port $((PORT1 + 100)))
+
+    docker1="$(yq '.docker1' "$cfg_file")"
+    vllm1="$(yq '.vllm1' "$cfg_file")"
+    docker2="$(yq '.docker2' "$cfg_file")"
+    vllm2="$(yq '.vllm2' "$cfg_file")"
+    model="$(yq -r '.vllm1.model' "$cfg_file")"
+
+    # Controller ports
+    pull=$(yq -er '.docker1["pull-port"]' "$cfg_file" 2>/dev/null || echo "8300")
+    reply=$(yq -er '.docker1["reply-port"]' "$cfg_file" 2>/dev/null || echo "8400")
+
+    # Inject controller URLs
+    docker1=$(echo "$docker1" | yq -y --arg pull "$pull" --arg reply "$reply" '. + {"env": (.env + ["LMCACHE_CONTROLLER_PULL_URL=localhost:" + $pull, "LMCACHE_CONTROLLER_REPLY_URL=localhost:" + $reply, "UCX_TLS=tcp"])}')
+
+    pull2=$(yq -er '.docker2["pull-port"]' "$cfg_file" 2>/dev/null || echo "$pull")
+    reply2=$(yq -er '.docker2["reply-port"]' "$cfg_file" 2>/dev/null || echo "$reply")
+    docker2=$(echo "$docker2" | yq -y --arg pull2 "$pull2" --arg reply2 "$reply2" '. + {"env": (.env + ["LMCACHE_CONTROLLER_PULL_URL=localhost:" + $pull2, "LMCACHE_CONTROLLER_REPLY_URL=localhost:" + $reply2, "UCX_TLS=tcp"])}')
+
+    # Start controller
+    echo "--- Starting P2P controller on port $PORT"
+    PYTHONHASHSEED=123 lmcache_controller \
+        --host localhost \
+        --port "$PORT" \
+        --monitor-ports "{\"pull\": ${pull}, \"reply\": ${reply}}" \
+        > "/tmp/build_${BUILD_ID}_${CFG_NAME%.yaml}_controller.log" 2>&1 &
+    PIDS+=($!)
+    sleep 10
+
+    echo "--- Starting instance 1 on port $PORT1 (GPU 0)"
+    start_single_server "$docker1" "$vllm1" "$PORT1" "0" \
+        "/tmp/build_${BUILD_ID}_${CFG_NAME%.yaml}1.log"
+
+    echo "--- Starting instance 2 on port $PORT2 (GPU 1)"
+    start_single_server "$docker2" "$vllm2" "$PORT2" "1" \
+        "/tmp/build_${BUILD_ID}_${CFG_NAME%.yaml}2.log"
+
+else
+    # ── Single server mode (1 GPU) ──────────────────────────
+    docker_section="$(yq '.docker' "$cfg_file")"
+    vllm_section="$(yq '.vllm' "$cfg_file")"
+    model="$(yq -r '.vllm.model' "$cfg_file")"
+
+    echo "--- Starting single server on port $PORT"
+    start_single_server "$docker_section" "$vllm_section" "$PORT" "" \
+        "/tmp/build_${BUILD_ID}_${CFG_NAME%.yaml}.log"
+fi
+
+###############
+# WORKLOAD    #
+###############
+
+test_mode="$(yq -r '.workload.type' "$cfg_file")"
+
+if [[ "$test_mode" == "dummy" ]]; then
+    echo "--- Running dummy test (simple HTTP request)"
+    http_status_code=$(
+        curl --max-time 60 "http://localhost:${PORT}/v1/completions" \
+            -w "%{http_code}" -o response-file.txt \
+            -H "Content-Type: application/json" \
+            -d '{
+                "model": "'"$model"'",
+                "prompt": "<|begin_of_text|><|system|>\nYou are a helpful AI assistant.\n<|user|>\nWhat is the capital of France?\n<|assistant|>",
+                "max_tokens": 100,
+                "temperature": 0.7
+            }'
+    )
+    if [[ "$http_status_code" -ne 200 ]]; then
+        echo "FAIL: Dummy test HTTP status ${http_status_code}"
+        cat response-file.txt
+        exit 1
+    fi
+    echo "PASS: Dummy test succeeded"
+    cat response-file.txt
+
+elif [[ "$test_mode" == "long_doc_qa" ]]; then
+    echo "--- Running long_doc_qa workload"
+
+    # Build workload JSON (merge workload section with model, strip non-CLI fields)
+    # Fields like expected-latency-gain are used by the checking logic, not long_doc_qa.py.
+    # "completion" -> "completions" rename to match the argparse flag.
+    workload_yaml="$(yq --arg model "$model" '(.workload * {"model": $model}) | del(.type) | del(.["expected-latency-gain"]) | if .completion then .completions = .completion | del(.completion) else . end' "$cfg_file")"
+    cfg_json="$(yq '.' "$cfg_file")"
+
+    # Determine which checking fields are requested
+    check_warmup_round_time_per_prompt=$(
+        jq -e '(.["checking-fields"] // []) | index("warmup_round_time_per_prompt") != null' \
+            <<< "$cfg_json" >/dev/null && echo true || echo false
+    )
+    check_query_round_time_per_prompt=$(
+        jq -e '(.["checking-fields"] // []) | index("query_round_time_per_prompt") != null' \
+            <<< "$cfg_json" >/dev/null && echo true || echo false
+    )
+    check_query_ttft_per_prompt=$(
+        jq -e '(.["checking-fields"] // []) | index("warmup_ttft_per_prompt") != null' \
+            <<< "$cfg_json" >/dev/null && echo true || echo false
+    )
+
+    run_long_doc_qa_workload() {
+        local workload_config="$1"
+        local port="$2"
+        local check_warmup="${3:-false}"
+        local check_ttft="${4:-false}"
+        local check_round="${5:-false}"
+        local feat_type="${6:-dummy}"
+        local need_upload="${7:-false}"
+
+        echo "Running long_doc_qa on port $port"
+
+        # Build args array from JSON config
+        local -a workload_args=()
+        mapfile -d '' -t workload_args < <(
+        jq -j '
+            to_entries[]
+            | select(.value != null and (.value|tostring) != "")
+            | (
+                if (.value|type) == "boolean" then
+                if .value then ["--\(.key)", "\u0000"] else [] end
+                elif (.value|type) == "array" then
+                .value[]
+                | ["--\(.key)", "\u0000",
+                    (if (type=="string") then . else tostring end),
+                    "\u0000"]
+                else
+                ["--\(.key)", "\u0000",
+                (if ((.value|type)=="string") then .value else (.value|tostring) end),
+                "\u0000"]
+                end
+            )
+            | .[]
+        ' <<<"$workload_config"
+        )
+
+        local json
+        json=$(
+            python3 "${REPO_ROOT}/benchmarks/long_doc_qa/long_doc_qa.py" \
+                "${workload_args[@]}" \
+                --port="$port" \
+                --output="response.txt" \
+                --json-output \
+                2>>response.txt | tail -n 1
+        )
+        local query_ttft_per_prompt query_round_time_per_prompt warmup_round_time_per_prompt
+        query_ttft_per_prompt=$(echo "$json" | jq -r '.query_ttft_per_prompt')
+        query_round_time_per_prompt=$(echo "$json" | jq -r '.query_round_time_per_prompt')
+        warmup_round_time_per_prompt=$(echo "$json" | jq -r '.warmup_round_time_per_prompt')
+
+        if [[ "$need_upload" == "true" ]]; then
+            # Nightly: write date-stamped file and upload as Buildkite artifact.
+            # A finalize step (upload-baselines.sh) will collect all artifacts,
+            # prune old files, and make a single commit to benchmarks-main.
+            local datestamp
+            datestamp="$(date +%Y%m%d)"
+            local artifact_name="${feat_type}-${datestamp}.json"
+            local artifact_path="${REPO_ROOT}/benchmarks/long_doc_qa/${artifact_name}"
+
+            echo "$json"
+            mkdir -p "$(dirname "$artifact_path")"
+            printf '%s\n' "$json" > "$artifact_path"
+
+            echo "[INFO] Uploading baseline artifact: ${artifact_name}"
+            buildkite-agent artifact upload "$artifact_path" 2>/dev/null || {
+                echo "[WARN] buildkite-agent not available; wrote $artifact_path locally"
+            }
+            return 0
+        fi
+
+        # ── PR comparison: rolling 5-day worst-case baseline ──────
+        # Fetch all date-stamped baselines for this feature from benchmarks-main.
+        # Use max() of each metric (= worst/slowest) as the threshold baseline.
+        # This makes the gate more tolerant of nightly hardware noise.
+        timeout 30 git fetch origin benchmarks-main >/dev/null 2>&1 || true
+
+        # List all baseline files for this feature (date-stamped and legacy).
+        # Note: git ls-tree does NOT expand shell globs in pathspecs, so we
+        # list the directory and filter with grep instead.
+        local -a baseline_files=()
+        mapfile -t baseline_files < <(
+            git ls-tree --name-only origin/benchmarks-main -- \
+                benchmarks/long_doc_qa/ 2>/dev/null \
+            | grep -E "^benchmarks/long_doc_qa/${feat_type}(-[0-9]{8})?\.json$" \
+            || true
+        )
+
+        if [[ ${#baseline_files[@]} -eq 0 ]]; then
+            if [[ "$feat_type" != "dummy" ]]; then
+                echo "No baselines found for ${feat_type} -- skipping performance comparisons"
+                echo "Current metrics: TTFT=$query_ttft_per_prompt, Latency=$query_round_time_per_prompt, Warmup=$warmup_round_time_per_prompt"
+            fi
+            return 0
+        fi
+
+        echo "[INFO] Found ${#baseline_files[@]} baseline file(s) for ${feat_type}:"
+        printf "  %s\n" "${baseline_files[@]}"
+
+        # Compute rolling max (worst-case) across all baselines
+        local expected_query_ttft=0 expected_query_round=0 expected_warmup=0
+        for bf in "${baseline_files[@]}"; do
+            local bj
+            bj=$(git show "origin/benchmarks-main:${bf}" 2>/dev/null || echo "")
+            if [[ -z "$bj" ]] || ! echo "$bj" | jq -e . >/dev/null 2>&1; then
+                echo "  Skipping invalid baseline: $bf"
+                continue
+            fi
+            # Take max of each metric (higher time = worse perf = more permissive gate)
+            expected_query_ttft=$(awk "BEGIN { a=$expected_query_ttft; b=$(echo "$bj" | jq -r '.query_ttft_per_prompt // 0'); print (a>b?a:b) }")
+            expected_query_round=$(awk "BEGIN { a=$expected_query_round; b=$(echo "$bj" | jq -r '.query_round_time_per_prompt // 0'); print (a>b?a:b) }")
+            expected_warmup=$(awk "BEGIN { a=$expected_warmup; b=$(echo "$bj" | jq -r '.warmup_round_time_per_prompt // 0'); print (a>b?a:b) }")
+        done
+
+        echo "[INFO] Rolling worst-case baseline: TTFT=$expected_query_ttft, Latency=$expected_query_round, Warmup=$expected_warmup"
+
+        # Sanity check: if all baselines were invalid, skip comparison
+        if awk "BEGIN { exit ($expected_query_ttft == 0 && $expected_query_round == 0 && $expected_warmup == 0) ? 0 : 1 }"; then
+            echo "All baselines were invalid or empty -- skipping performance comparisons"
+            return 0
+        fi
+
+        # Adaptive threshold: with fewer baselines the worst-case max is less
+        # representative, so we allow more headroom.
+        #   5+ baselines → 1.2x (20% tolerance, full confidence)
+        #   4  baselines → 1.3x
+        #   3  baselines → 1.4x
+        #   2  baselines → 1.5x
+        #   1  baseline  → 1.6x (60% tolerance, low confidence)
+        local num_baselines=${#baseline_files[@]}
+        local threshold
+        threshold=$(awk -v n="$num_baselines" 'BEGIN {
+            gap = (5 - n); if (gap < 0) gap = 0
+            printf "%.1f", 1.2 + gap * 0.1
+        }')
+        local pct
+        pct=$(awk -v t="$threshold" 'BEGIN { printf "%d", (t - 1) * 100 }')
+        echo "[INFO] Baselines: ${num_baselines}/5 — using ${pct}% tolerance (threshold=${threshold}x)"
+
+        if [[ "$check_ttft" == "true" ]]; then
+            echo "Worst-case baseline query ttft per prompt: $expected_query_ttft"
+            echo "Actual query ttft per prompt: $query_ttft_per_prompt"
+            awk -v expected="$expected_query_ttft" -v actual="$query_ttft_per_prompt" -v t="$threshold" -v pct="$pct" 'BEGIN {
+                if (actual > expected * t) { printf "FAIL: Query ttft per prompt >%d%% worse than rolling baseline\n", pct; exit 1 }
+                else { print "PASS: Query ttft per prompt within threshold" }
+            }'
+        fi
+
+        if [[ "$check_round" == "true" ]]; then
+            echo "Worst-case baseline query round time per prompt: $expected_query_round"
+            echo "Actual query round time per prompt: $query_round_time_per_prompt"
+            awk -v expected="$expected_query_round" -v actual="$query_round_time_per_prompt" -v t="$threshold" -v pct="$pct" 'BEGIN {
+                if (actual > expected * t) { printf "FAIL: Query round time per prompt >%d%% worse than rolling baseline\n", pct; exit 1 }
+                else { print "PASS: Query round time per prompt within threshold" }
+            }'
+        fi
+
+        if [[ "$check_warmup" == "true" ]]; then
+            echo "Worst-case baseline warmup round time per prompt: $expected_warmup"
+            echo "Actual warmup round time per prompt: $warmup_round_time_per_prompt"
+            awk -v expected="$expected_warmup" -v actual="$warmup_round_time_per_prompt" -v t="$threshold" -v pct="$pct" 'BEGIN {
+                if (actual > expected * t) { printf "FAIL: Warmup round time per prompt >%d%% worse than rolling baseline\n", pct; exit 1 }
+                else { print "PASS: Warmup round time per prompt within threshold" }
+            }'
+        fi
+    }
+
+    if [[ "$feature_type" == "p2p" ]]; then
+        run_long_doc_qa_workload "$workload_yaml" "$PORT1"
+        run_long_doc_qa_workload "$workload_yaml" "$PORT2" \
+            "$check_warmup_round_time_per_prompt" "$check_query_ttft_per_prompt" \
+            "$check_query_round_time_per_prompt" "${CFG_NAME%.yaml}" "$NEED_UPLOAD"
+    else
+        run_long_doc_qa_workload "$workload_yaml" "$PORT" \
+            "$check_warmup_round_time_per_prompt" "$check_query_ttft_per_prompt" \
+            "$check_query_round_time_per_prompt" "${CFG_NAME%.yaml}" "$NEED_UPLOAD"
+    fi
+fi
+
+###############
+# MEMORY LEAK #
+###############
+
+check_memory_leak() {
+    local port="$1"
+    local socket_path="/tmp/lmcache_internal_api_server/${port}/socket_7000"
+
+    local use_hot
+    use_hot=$(curl -s --unix-socket "$socket_path" "http://localhost/conf" 2>/dev/null | jq -r '.local_cpu // false')
+    if [[ -z "$use_hot" || "$use_hot" == "null" ]]; then
+        use_hot="false"
+    fi
+
+    echo "Checking memory leak on socket_path $socket_path (use_hot=$use_hot)..."
+
+    local metrics
+    metrics=$(curl -s --unix-socket "$socket_path" "http://localhost/metrics" 2>/dev/null)
+    if [[ -z "$metrics" ]]; then
+        echo "ERROR: Failed to fetch metrics from $socket_path"
+        return 1
+    fi
+
+    local local_cpu_hot_cache_count active_memory_objs_count pinned_memory_objs_count pin_monitor_pinned_objects_count
+    local_cpu_hot_cache_count=$(echo "$metrics" | grep -E '^lmcache:local_cpu_hot_cache_count\b' | awk '{print $2}' | head -n 1)
+    active_memory_objs_count=$(echo "$metrics" | grep -E '^lmcache:active_memory_objs_count\b' | awk '{print $2}' | head -n 1)
+    pinned_memory_objs_count=$(echo "$metrics" | grep -E '^lmcache:pinned_memory_objs_count\b' | awk '{print $2}' | head -n 1)
+    pin_monitor_pinned_objects_count=$(echo "$metrics" | grep -E '^lmcache:pin_monitor_pinned_objects_count\b' | awk '{print $2}' | head -n 1)
+
+    local_cpu_hot_cache_count=$(printf "%.0f" "${local_cpu_hot_cache_count:-0}")
+    active_memory_objs_count=$(printf "%.0f" "${active_memory_objs_count:-0}")
+    pinned_memory_objs_count=$(printf "%.0f" "${pinned_memory_objs_count:-0}")
+    pin_monitor_pinned_objects_count=$(printf "%.0f" "${pin_monitor_pinned_objects_count:-0}")
+
+    echo "  local_cpu_hot_cache_count: $local_cpu_hot_cache_count"
+    echo "  active_memory_objs_count: $active_memory_objs_count"
+    echo "  pinned_memory_objs_count: $pinned_memory_objs_count"
+    echo "  pin_monitor_pinned_objects_count: $pin_monitor_pinned_objects_count"
+
+    local has_leak=false
+
+    if [[ "$pinned_memory_objs_count" -ne 0 ]]; then
+        echo "ERROR: Memory leak detected - pinned_memory_objs_count ($pinned_memory_objs_count) should be 0"
+        has_leak=true
+    fi
+
+    if [[ "$use_hot" == "false" || "$use_hot" == "False" ]]; then
+        if [[ "$local_cpu_hot_cache_count" -ne 0 ]]; then
+            echo "ERROR: Memory leak - local_cpu_hot_cache_count ($local_cpu_hot_cache_count) should be 0 when use_hot=false"
+            has_leak=true
+        fi
+        if [[ "$active_memory_objs_count" -ne 0 ]]; then
+            echo "ERROR: Memory leak - active_memory_objs_count ($active_memory_objs_count) should be 0 when use_hot=false"
+            has_leak=true
+        fi
+    else
+        if [[ "$active_memory_objs_count" -ne "$local_cpu_hot_cache_count" ]]; then
+            echo "ERROR: Memory leak - active_memory_objs_count ($active_memory_objs_count) should equal local_cpu_hot_cache_count ($local_cpu_hot_cache_count) when use_hot=true"
+            has_leak=true
+        fi
+    fi
+
+    if [[ "$has_leak" == "true" ]]; then
+        echo "$metrics"
+        return 1
+    fi
+
+    echo "  Memory leak check passed!"
+    return 0
+}
+
+# Wait for metrics to settle
+sleep 30
+echo "--- Checking for memory leaks..."
+
+if [[ "$feature_type" == "p2p" ]]; then
+    echo "Skipping memory leak check for p2p (known issue with pinned_memory_objs not clearing)."
+elif [[ "$feature_type" == "pd" ]]; then
+    if ! check_memory_leak "$PORT1"; then
+        echo "Memory leak check failed for instance 1 (port $PORT1)"
+        exit 1
+    fi
+    if ! check_memory_leak "$PORT2"; then
+        echo "Memory leak check failed for instance 2 (port $PORT2)"
+        exit 1
+    fi
+elif [[ "$CFG_NAME" == "multi_device.yaml" || "$CFG_NAME" == "layerwise.yaml" ]]; then
+    echo "Skipping memory leak check for $CFG_NAME case as it's a flaky test while run check_memory_leak check."
+else
+    if ! check_memory_leak "$PORT"; then
+        echo "Memory leak check failed for $CFG_NAME"
+        exit 1
+    fi
+fi
+
+echo "===== PASS: ${CFG_NAME} ====="
diff --git a/.buildkite/k3_tests/comprehensive/scripts/upload-baselines.sh b/.buildkite/k3_tests/comprehensive/scripts/upload-baselines.sh
new file mode 100755
index 0000000..1080145
--- /dev/null
+++ b/.buildkite/k3_tests/comprehensive/scripts/upload-baselines.sh
@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# Finalize nightly baseline upload.
+# Runs AFTER all comprehensive config steps complete (via `wait`).
+#
+# 1. Downloads all *-YYYYMMDD.json artifacts from this build
+# 2. Checks out benchmarks-main
+# 3. Copies new date-stamped files, prunes entries older than 5 days
+# 4. Makes a single commit and pushes to benchmarks-main
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+BASELINE_DIR="${REPO_ROOT}/benchmarks/long_doc_qa"
+KEEP_DAYS=5
+
+cd "${REPO_ROOT}"
+
+# Prevent git from hanging on prompts
+export GIT_TERMINAL_PROMPT=0
+
+###############
+# DOWNLOAD    #
+###############
+
+ARTIFACT_DIR="/tmp/baseline_artifacts"
+mkdir -p "$ARTIFACT_DIR"
+
+echo "--- Downloading baseline artifacts from this build"
+buildkite-agent artifact download "benchmarks/long_doc_qa/*-*.json" "$ARTIFACT_DIR" 2>/dev/null || {
+    echo "No baseline artifacts found. This is expected if no long_doc_qa configs ran."
+    exit 0
+}
+
+NEW_FILES=("$ARTIFACT_DIR"/benchmarks/long_doc_qa/*-*.json)
+if [[ ! -e "${NEW_FILES[0]}" ]]; then
+    echo "No date-stamped baseline files found in artifacts."
+    exit 0
+fi
+
+echo "Downloaded ${#NEW_FILES[@]} baseline file(s):"
+printf "  %s\n" "${NEW_FILES[@]}"
+
+###############
+# CHECKOUT    #
+###############
+
+# Work in a detached worktree to avoid touching the main checkout
+WORK_DIR="/tmp/baselines_push_$$"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+# Push baselines to a dedicated CI repo instead of the main LMCache repo.
+CI_REPO="LMCache/LMCache"
+CI_BRANCH="benchmarks-main"
+
+if [[ -n "${GITHUB_TOKEN:-}" ]]; then
+    CI_REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${CI_REPO}.git"
+else
+    echo "[WARN] GITHUB_TOKEN not set — push may fail without credentials"
+    CI_REPO_URL="https://github.com/${CI_REPO}.git"
+fi
+
+echo "--- Preparing ${CI_BRANCH} branch from ${CI_REPO}"
+git clone --depth=1 --branch "${CI_BRANCH}" "${CI_REPO_URL}" "$WORK_DIR" 2>/dev/null || {
+    # Branch doesn't exist yet — create an orphan
+    mkdir -p "$WORK_DIR"
+    git -C "$WORK_DIR" init
+    git -C "$WORK_DIR" remote add origin "${CI_REPO_URL}"
+    git -C "$WORK_DIR" checkout --orphan "${CI_BRANCH}"
+}
+
+###############
+# COPY + PRUNE#
+###############
+
+mkdir -p "$WORK_DIR/benchmarks/long_doc_qa"
+
+# Copy new files
+for f in "${NEW_FILES[@]}"; do
+    cp "$f" "$WORK_DIR/benchmarks/long_doc_qa/"
+done
+
+# Prune date-stamped files older than KEEP_DAYS
+echo "--- Pruning baselines older than ${KEEP_DAYS} days"
+CUTOFF_DATE="$(date -d "${KEEP_DAYS} days ago" +%Y%m%d 2>/dev/null || date -v-${KEEP_DAYS}d +%Y%m%d)"
+
+for f in "$WORK_DIR"/benchmarks/long_doc_qa/*-*.json; do
+    [[ ! -e "$f" ]] && continue
+    fname="$(basename "$f")"
+    # Extract YYYYMMDD from filename like "local_cpu-20260301.json"
+    file_date="${fname##*-}"
+    file_date="${file_date%.json}"
+    if [[ "$file_date" =~ ^[0-9]{8}$ ]] && [[ "$file_date" < "$CUTOFF_DATE" ]]; then
+        echo "  Removing old baseline: $fname"
+        rm "$f"
+    fi
+done
+
+# Also remove legacy single-point files (feature.json without date) since we now use rolling
+# Keep them if they exist for backward compat during transition, but don't create new ones.
+
+###############
+# COMMIT+PUSH #
+###############
+
+cd "$WORK_DIR"
+git add benchmarks/long_doc_qa/
+
+if git diff --cached --quiet 2>/dev/null; then
+    echo "No changes to commit."
+    exit 0
+fi
+
+TODAY="$(date +%Y-%m-%d)"
+git -c user.email="ci@lmcache.ai" -c user.name="LMCache CI" \
+    commit -m "Update rolling baselines: ${TODAY}" || true
+
+echo "--- Pushing to ${CI_REPO} ${CI_BRANCH}"
+# Try normal push first; fall back to force-push if history diverged
+if ! git push origin "HEAD:${CI_BRANCH}" 2>/dev/null; then
+    echo "[WARN] Normal push failed, force-pushing..."
+    git push origin "+HEAD:${CI_BRANCH}" 2>/dev/null || {
+        echo "[ERROR] Failed to push baselines to ${CI_REPO} ${CI_BRANCH}"
+        exit 1
+    }
+fi
+
+echo "--- Baselines uploaded successfully"
+git log --oneline -1
+ls -la benchmarks/long_doc_qa/
diff --git a/.buildkite/k3_tests/correctness/BK_WEB_SETUP.md b/.buildkite/k3_tests/correctness/BK_WEB_SETUP.md
new file mode 100644
index 0000000..77bbc2d
--- /dev/null
+++ b/.buildkite/k3_tests/correctness/BK_WEB_SETUP.md
@@ -0,0 +1,14 @@
+# Buildkite Web UI Setup: Correctness Tests
+
+**Steps editor**: paste contents of `buildkite-pipeline.yml` (fill in `HF_TOKEN`).
+
+**GitHub trigger settings**:
+- Filter: *(none — runs on every push/PR)*
+- Skip queued / cancel running branch builds: Yes
+
+Lightweight (1 GPU) — good candidate for a required GitHub status check.
+
+> Builds whose only changes are docs/`*.md`/`LICENSE`/`.github/**` auto-pass
+> via the [path filter](../README.md#path-based-skip-auto-pass-on-docs-only-changes).
+> Changes under `.buildkite/` always run. Add `force-ci` label to the PR to
+> bypass.
diff --git a/.buildkite/k3_tests/correctness/buildkite-pipeline.yml b/.buildkite/k3_tests/correctness/buildkite-pipeline.yml
new file mode 100644
index 0000000..ed9fb33
--- /dev/null
+++ b/.buildkite/k3_tests/correctness/buildkite-pipeline.yml
@@ -0,0 +1,11 @@
+# Paste this into the Buildkite pipeline's "Steps" editor.
+# It uploads the real pipeline definition from the repo.
+agents:
+  queue: "k8s"
+
+env:
+  HF_TOKEN: ""  # set your HuggingFace token here (needed for gated model access)
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/correctness/pipeline.yml
diff --git a/.buildkite/k3_tests/correctness/pipeline.yml b/.buildkite/k3_tests/correctness/pipeline.yml
new file mode 100644
index 0000000..935c377
--- /dev/null
+++ b/.buildkite/k3_tests/correctness/pipeline.yml
@@ -0,0 +1,27 @@
+# Correctness test — verifies LMCache produces identical output to base vLLM.
+# Runs: base vLLM → LMCache vLLM → man bash prefix test → ShareGPT diff.
+# Requires pre-downloaded model weights and ShareGPT dataset.
+
+steps:
+  - label: ":white_check_mark: Correctness"
+    command: .buildkite/k3_tests/correctness/run.sh
+    timeout_in_minutes: 30
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources:
+                  limits:
+                    nvidia.com/gpu: "1"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                  - { name: datasets, mountPath: /root/correctness }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+              - { name: datasets, hostPath: { path: /data/datasets, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "build_*.log"
diff --git a/.buildkite/k3_tests/correctness/run.sh b/.buildkite/k3_tests/correctness/run.sh
new file mode 100755
index 0000000..eed3b5a
--- /dev/null
+++ b/.buildkite/k3_tests/correctness/run.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Correctness test entrypoint for K8s pods.
+# Thin wrapper: sets up environment, then delegates to scripts/.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+
+# ── Environment setup ────────────────────────────────────────
+source .buildkite/k3_harness/setup-env.sh
+uv pip install aiohttp tqdm pandas huggingface_hub
+
+# ── Ensure all scripts are executable ────────────────────────
+chmod +x "${SCRIPT_DIR}"/scripts/*.sh
+
+# ── Run the actual test logic ────────────────────────────────
+# Retry up to 3 times. vLLM's `VLLM_BATCH_INVARIANT=1` guarantee
+# currently does not hold across process restarts in the vllm nightlies
+# we pin to (reproduced locally: two back-to-back vanilla vllm-only runs
+# produce ~55 different outputs out of 100). Phase 4's bitwise
+# comparison between the base-vllm run and the vllm+LMCache run is
+# bimodal (0 diff or ~50 diff) depending on which cuBLAS/kernel plans
+# the two separate processes happen to pick. Retrying lets a lucky
+# scheduling pass; a real LMCache regression will persistently fail.
+MAX_ATTEMPTS="${CORRECTNESS_MAX_ATTEMPTS:-3}"
+for attempt in $(seq 1 "${MAX_ATTEMPTS}"); do
+    echo "=== Correctness attempt ${attempt}/${MAX_ATTEMPTS} ==="
+    if bash "${SCRIPT_DIR}/scripts/run-correctness.sh"; then
+        exit 0
+    fi
+    echo "[INFO] Attempt ${attempt} failed."
+done
+echo "[FAIL] Correctness persistently failed after ${MAX_ATTEMPTS} attempts." >&2
+exit 1
diff --git a/.buildkite/k3_tests/correctness/scripts/run-correctness.sh b/.buildkite/k3_tests/correctness/scripts/run-correctness.sh
new file mode 100755
index 0000000..3f3d8c1
--- /dev/null
+++ b/.buildkite/k3_tests/correctness/scripts/run-correctness.sh
@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+# Self-contained correctness test for K8s pods.
+# Replaces the old vllm-correctness.sh which assumed a pre-existing venv
+# and pick-free-gpu.sh. Here everything runs natively in the pod.
+#
+# Tests that LMCache produces identical output to base vLLM.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+source .buildkite/k3_tests/common_scripts/helpers.sh
+
+###############
+# CONFIG      #
+###############
+
+BUILD_ID="${BUILDKITE_BUILD_ID:-local_$$}"
+MODEL="Qwen/Qwen2.5-14B-Instruct"
+WORK_LOG="/tmp/build_${BUILD_ID}_correctness.log"
+VLLM_LOG="/tmp/build_${BUILD_ID}_vllm.log"
+ARTIFACT="build_${BUILD_ID}.log"
+SERVER_WAIT_TIMEOUT=180
+CORRECTNESS_DIR=".buildkite/correctness"
+REQUEST_NUMBER=100
+MAX_CONCURRENCY=40
+
+# K8s assigns GPUs via device plugin
+export CUDA_VISIBLE_DEVICES="${CUDA_VISIBLE_DEVICES:-0}"
+
+###############
+# DATA SETUP  #
+###############
+
+SHAREGPT_PATH="/root/correctness/.ShareGPT_V3_unfiltered_cleaned_split.json"
+if [[ ! -f "$SHAREGPT_PATH" ]]; then
+    echo "[INFO] ShareGPT dataset not found, downloading..."
+    mkdir -p /root/correctness
+    wget -q \
+        "https://huggingface.co/datasets/anon8231489123/ShareGPT_Vicuna_unfiltered/resolve/main/ShareGPT_V3_unfiltered_cleaned_split.json" \
+        -O "$SHAREGPT_PATH"
+fi
+
+if [[ ! -s "$SHAREGPT_PATH" ]]; then
+    echo "[ERROR] ShareGPT dataset file is empty: $SHAREGPT_PATH"
+    exit 1
+fi
+
+###############
+# HELPERS     #
+###############
+
+VLLM_PID=""
+
+CI_CACHE_DIR="$PWD/.vllm_cache_${BUILD_ID}"
+mkdir -p "$CI_CACHE_DIR"
+export FLASHINFER_WORKSPACE_DIR="$CI_CACHE_DIR/flashinfer"
+
+collect_artifact() {
+    echo "[INFO] Collecting logs into ${ARTIFACT}"
+    cat "${WORK_LOG}" "${VLLM_LOG}" > "${ARTIFACT}" 2>/dev/null || true
+}
+
+stop_vllm() {
+    if [[ -n "${VLLM_PID:-}" ]]; then
+        echo "[INFO] Stopping vLLM process (PID: ${VLLM_PID})"
+        kill "${VLLM_PID}" >/dev/null 2>&1 || true
+        wait "${VLLM_PID}" 2>/dev/null || true
+        VLLM_PID=""
+        sleep 5
+    fi
+}
+
+trap 'rc=$?; stop_vllm; collect_artifact; exit $rc' EXIT INT TERM
+
+exec > >(tee -a "${WORK_LOG}") 2>&1
+
+echo "=== DIAGNOSTICS: GPU STATE before CI ==="
+nvidia-smi
+echo "[INFO] Using GPU(s): ${CUDA_VISIBLE_DEVICES}"
+
+echo "[INFO] Converting ShareGPT dataset to OpenAI format..."
+python "${CORRECTNESS_DIR}/sharegpt2openai.py" -i "$SHAREGPT_PATH" -o "./shareGPT_dataset.json"
+
+###############
+# PHASE 1     #
+###############
+# Base Server (Baseline) -- vLLM WITHOUT LMCache
+
+PORT=$(find_free_port 8000)
+echo "[INFO] Starting BASE vLLM server on port ${PORT}..."
+
+VLLM_SERVER_DEV_MODE=1 \
+VLLM_BATCH_INVARIANT=1 \
+vllm serve "${MODEL}" \
+    --port "${PORT}" \
+    --trust-remote-code \
+    --enforce-eager \
+    --attention-backend FLASH_ATTN \
+    --gpu-memory-utilization 0.8 \
+    >"${VLLM_LOG}" 2>&1 &
+VLLM_PID=$!
+
+echo "[INFO] Waiting for Base server readiness..."
+if ! wait_for_server "$PORT" "$SERVER_WAIT_TIMEOUT"; then
+    echo "[ERROR] Base vLLM failed to start"
+    exit 1
+fi
+
+echo "[TEST] Running ShareGPT Batch (Base)..."
+python "${CORRECTNESS_DIR}/async_request.py" \
+    --model "${MODEL}" \
+    --endpoint "http://localhost:${PORT}/v1/chat/completions" \
+    --output-file "sharegpt_base.txt" \
+    --dataset_file "./shareGPT_dataset.json" \
+    --request-number "${REQUEST_NUMBER}" \
+    --max-concurrency "${MAX_CONCURRENCY}"
+
+stop_vllm
+
+###############
+# PHASE 2     #
+###############
+# LMCache Server -- vLLM WITH LMCache
+
+echo "[INFO] Preparing LMCache config (cpu.yaml)..."
+cat <<EOF > cpu.yaml
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 50
+EOF
+
+PORT=$(find_free_port 8000)
+echo "[INFO] Starting LMCACHE vLLM server on port ${PORT}..."
+
+LMCACHE_CONFIG_FILE=cpu.yaml \
+VLLM_SERVER_DEV_MODE=1 \
+VLLM_BATCH_INVARIANT=1 \
+vllm serve "${MODEL}" \
+    --port "${PORT}" \
+    --trust-remote-code \
+    --enforce-eager \
+    --attention-backend FLASH_ATTN \
+    --gpu-memory-utilization 0.8 \
+    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}' \
+    >>"${VLLM_LOG}" 2>&1 &
+VLLM_PID=$!
+
+echo "[INFO] Waiting for LMCache server readiness..."
+if ! wait_for_server "$PORT" "$SERVER_WAIT_TIMEOUT"; then
+    echo "[ERROR] LMCache vLLM failed to start"
+    exit 1
+fi
+
+echo "[TEST] Running ShareGPT Batch (LMCache)..."
+python "${CORRECTNESS_DIR}/async_request.py" \
+    --model "${MODEL}" \
+    --endpoint "http://localhost:${PORT}/v1/chat/completions" \
+    --output-file "sharegpt_lmcache.txt" \
+    --dataset_file "./shareGPT_dataset.json" \
+    --request-number "${REQUEST_NUMBER}" \
+    --max-concurrency "${MAX_CONCURRENCY}"
+
+###############
+# PHASE 3     #
+###############
+# Man bash correctness test (on the LMCache server)
+
+echo "[TEST] Running technical man bash correctness test..."
+CONTEXT="$(man bash | sed 's/.\x08//g' | tr -s '[:space:]' ' ' | awk '{for(i=1;i<=NF;i++){printf "%s ",$i; if(++c==5000) exit}}')"
+HALF_CONTEXT="$(man bash | sed 's/.\x08//g' | tr -s '[:space:]' ' ' | awk '{for(i=1;i<=NF;i++){printf "%s ",$i; if(++c==2500) exit}}')"
+
+send_completion() {
+    curl -s "http://localhost:${PORT}/v1/chat/completions" \
+        -H "Content-Type: application/json" \
+        -d "$(jq -n --arg model "${MODEL}" --arg content "$1" '{model: $model, temperature: 0, max_tokens: 100, messages: [{role:"user",content:$content}]}')" |
+        jq -r '.choices[0].message.content'
+}
+
+echo "[STEP 1] Full context (LMCache)"
+OUT1="$(send_completion "${CONTEXT}")"
+
+echo "[STEP 2] Reset prefix cache"
+curl -s -X POST "http://localhost:${PORT}/reset_prefix_cache" >/dev/null
+
+echo "[STEP 3] Half context"
+send_completion "${HALF_CONTEXT}" >/dev/null
+
+echo "[STEP 4] Full context again"
+OUT2="$(send_completion "${CONTEXT}")"
+
+if [[ "${OUT1}" != "${OUT2}" ]]; then
+    echo "[FAIL] man bash output mismatch!"
+    exit 1
+fi
+
+###############
+# PHASE 4     #
+###############
+# ShareGPT File Comparison
+
+echo "[INFO] Comparing ShareGPT results..."
+COMPARE_OUT=$(python "${CORRECTNESS_DIR}/compare_files.py" --file1 "sharegpt_base.txt" --file2 "sharegpt_lmcache.txt")
+
+echo "--- COMPARISON RESULTS ---"
+echo "${COMPARE_OUT}"
+echo "--------------------------"
+
+DIFFERENT_COUNT=$(echo "${COMPARE_OUT}" | grep "^Different IDs:" | grep -oE '[0-9]+' | tail -1 || echo "0")
+ONLY_FILE1_COUNT=$(echo "${COMPARE_OUT}" | awk '/^—— Only in File 1 ——$/,/^—— Only in File 2 ——$/ {print}' | grep -cE "^chatcmpl-" || echo "0")
+ONLY_FILE2_COUNT=$(echo "${COMPARE_OUT}" | awk '/^—— Only in File 2 ——$/,/^$/ {print}' | grep -cE "^chatcmpl-" || echo "0")
+
+echo "[INFO] Analysis: Different=${DIFFERENT_COUNT}, Only in Base=${ONLY_FILE1_COUNT}, Only in LMCache=${ONLY_FILE2_COUNT}"
+
+if [[ "${DIFFERENT_COUNT}" -gt 0 ]] || [[ "${ONLY_FILE1_COUNT}" -gt 0 ]] || [[ "${ONLY_FILE2_COUNT}" -gt 0 ]]; then
+    echo "[FAIL] Inconsistency detected between Base and LMCache outputs."
+    exit 1
+fi
+
+echo "[PASS] All correctness tests passed -- identical output verified."
diff --git a/.buildkite/k3_tests/integration/BK_WEB_SETUP.md b/.buildkite/k3_tests/integration/BK_WEB_SETUP.md
new file mode 100644
index 0000000..8d2fcea
--- /dev/null
+++ b/.buildkite/k3_tests/integration/BK_WEB_SETUP.md
@@ -0,0 +1,14 @@
+# Buildkite Web UI Setup: Integration Tests
+
+**Steps editor**: paste contents of `buildkite-pipeline.yml` (fill in `HF_TOKEN`).
+
+**GitHub trigger settings**:
+- Filter: *(none — runs on every push/PR)*
+- Skip queued / cancel running branch builds: Yes
+
+Lightweight (1 GPU) — good candidate for a required GitHub status check.
+
+> Builds whose only changes are docs/`*.md`/`LICENSE`/`.github/**` auto-pass
+> via the [path filter](../README.md#path-based-skip-auto-pass-on-docs-only-changes).
+> Changes under `.buildkite/` always run. Add `force-ci` label to the PR to
+> bypass.
\ No newline at end of file
diff --git a/.buildkite/k3_tests/integration/buildkite-pipeline.yml b/.buildkite/k3_tests/integration/buildkite-pipeline.yml
new file mode 100644
index 0000000..ffed4f5
--- /dev/null
+++ b/.buildkite/k3_tests/integration/buildkite-pipeline.yml
@@ -0,0 +1,11 @@
+# Paste this into the Buildkite pipeline's "Steps" editor.
+# It uploads the real pipeline definition from the repo.
+agents:
+  queue: "k8s"
+
+env:
+  HF_TOKEN: ""  # set your HuggingFace token here (needed for gated model access)
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/integration/pipeline.yml
diff --git a/.buildkite/k3_tests/integration/pipeline.yml b/.buildkite/k3_tests/integration/pipeline.yml
new file mode 100644
index 0000000..9d6c114
--- /dev/null
+++ b/.buildkite/k3_tests/integration/pipeline.yml
@@ -0,0 +1,49 @@
+# Integration tests — starts vLLM with LMCache directly (no Docker),
+# tests CPU and disk backends via the OpenAI API.
+
+steps:
+  - label: ":test_tube: Integration — CPU backend"
+    command: .buildkite/k3_tests/integration/run.sh cpu
+    timeout_in_minutes: 20
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources:
+                  limits:
+                    nvidia.com/gpu: "1"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "*.csv"
+      - "*.pdf"
+      - "*.log"
+
+  - label: ":test_tube: Integration — Disk backend"
+    command: .buildkite/k3_tests/integration/run.sh disk
+    timeout_in_minutes: 20
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources:
+                  limits:
+                    nvidia.com/gpu: "1"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "*.csv"
+      - "*.pdf"
+      - "*.log"
diff --git a/.buildkite/k3_tests/integration/run.sh b/.buildkite/k3_tests/integration/run.sh
new file mode 100755
index 0000000..c2d23d6
--- /dev/null
+++ b/.buildkite/k3_tests/integration/run.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Integration test entrypoint for K8s pods.
+# Thin wrapper: sets up environment, then delegates to scripts/.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+
+# ── Environment setup ────────────────────────────────────────
+source .buildkite/k3_harness/setup-env.sh
+uv pip install aiohttp
+
+# ── Ensure all scripts are executable ────────────────────────
+chmod +x "${SCRIPT_DIR}"/scripts/*.sh
+
+# ── Run the actual test logic ────────────────────────────────
+exec bash "${SCRIPT_DIR}/scripts/run-integration.sh" "$@"
diff --git a/.buildkite/k3_tests/integration/scripts/run-integration.sh b/.buildkite/k3_tests/integration/scripts/run-integration.sh
new file mode 100755
index 0000000..3d805a2
--- /dev/null
+++ b/.buildkite/k3_tests/integration/scripts/run-integration.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Integration test logic: starts vLLM with LMCache (CPU and disk backends),
+# sends requests via the OpenAI API, and verifies responses.
+# Runs directly in the K8s pod -- no Docker.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+source .buildkite/k3_tests/common_scripts/helpers.sh
+
+TEST_NAME="${1:-all}"  # "cpu", "disk", or "all"
+
+MODEL="meta-llama/Llama-3.2-1B-Instruct"
+PORT=8000
+VLLM_PID=""
+
+cleanup() {
+    if [[ -n "$VLLM_PID" ]]; then
+        echo "--- Shutting down vLLM (PID=$VLLM_PID)"
+        kill "$VLLM_PID" 2>/dev/null || true
+        wait "$VLLM_PID" 2>/dev/null || true
+    fi
+}
+trap cleanup EXIT
+
+send_request() {
+    local port=$1 prompt=$2
+    curl -sf "http://localhost:${port}/v1/completions" \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"${MODEL}\",
+            \"prompt\": \"${prompt}\",
+            \"max_tokens\": 64,
+            \"temperature\": 0
+        }"
+}
+
+run_test() {
+    local test_name=$1
+    shift
+    local env_vars=("$@")
+
+    echo "--- :test_tube: ${test_name}"
+
+    # Start vLLM with LMCache
+    env "${env_vars[@]}" \
+        vllm serve "$MODEL" \
+            --port "$PORT" \
+            --load-format dummy \
+            --enforce-eager \
+            --no-enable-prefix-caching \
+            --gpu-memory-utilization 0.8 \
+            --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}' \
+            > "${test_name}-vllm.log" 2>&1 &
+    VLLM_PID=$!
+
+    wait_for_server "$PORT" 300 "${test_name}-vllm.log"
+
+    # Send requests -- same prompt twice to exercise the cache (second hit should be cached)
+    local prompt="The quick brown fox jumps over the lazy dog. Explain this sentence in detail."
+
+    echo "Sending request 1 (cold)..."
+    local resp1
+    resp1=$(send_request "$PORT" "$prompt")
+    echo "Response 1: $(echo "$resp1" | python3 -c 'import sys,json; r=json.load(sys.stdin); print(r["choices"][0]["text"][:100])' 2>/dev/null || echo "PARSE_ERROR")"
+
+    echo "Sending request 2 (should hit cache)..."
+    local resp2
+    resp2=$(send_request "$PORT" "$prompt")
+    echo "Response 2: $(echo "$resp2" | python3 -c 'import sys,json; r=json.load(sys.stdin); print(r["choices"][0]["text"][:100])' 2>/dev/null || echo "PARSE_ERROR")"
+
+    # Verify we got valid responses
+    for resp_name in resp1 resp2; do
+        local resp_val="${!resp_name}"
+        if ! echo "$resp_val" | python3 -c 'import sys,json; r=json.load(sys.stdin); assert r["choices"][0]["text"]' 2>/dev/null; then
+            echo "FAIL: ${test_name} -- invalid response in ${resp_name}"
+            echo "$resp_val"
+            kill "$VLLM_PID" 2>/dev/null; wait "$VLLM_PID" 2>/dev/null || true; VLLM_PID=""
+            return 1
+        fi
+    done
+
+    echo "PASS: ${test_name}"
+
+    # Shut down for next test
+    kill "$VLLM_PID" 2>/dev/null; wait "$VLLM_PID" 2>/dev/null || true; VLLM_PID=""
+    sleep 2
+}
+
+# ── Test 1: CPU backend ───────────────────────────────────────
+if [[ "$TEST_NAME" == "cpu" || "$TEST_NAME" == "all" ]]; then
+    run_test "local_cpu" \
+        "LMCACHE_CHUNK_SIZE=256" \
+        "LMCACHE_LOCAL_CPU=True" \
+        "LMCACHE_MAX_LOCAL_CPU_SIZE=5"
+fi
+
+# ── Test 2: Disk backend ─────────────────────────────────────
+if [[ "$TEST_NAME" == "disk" || "$TEST_NAME" == "all" ]]; then
+    DISK_DIR=$(mktemp -d)
+    trap "cleanup; rm -rf $DISK_DIR" EXIT
+
+    run_test "local_disk" \
+        "LMCACHE_CHUNK_SIZE=256" \
+        "LMCACHE_LOCAL_CPU=True" \
+        "LMCACHE_MAX_LOCAL_CPU_SIZE=5" \
+        "LMCACHE_LOCAL_DISK=file://${DISK_DIR}"
+fi
+
+echo "--- :white_check_mark: Integration tests passed (${TEST_NAME})"
diff --git a/.buildkite/k3_tests/multiprocess/BK_WEB_SETUP.md b/.buildkite/k3_tests/multiprocess/BK_WEB_SETUP.md
new file mode 100644
index 0000000..eb0244d
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/BK_WEB_SETUP.md
@@ -0,0 +1,15 @@
+# Buildkite Web UI Setup: Multiprocess Tests
+
+**Steps editor**: paste contents of `buildkite-pipeline.yml` (fill in `HF_TOKEN`).
+
+**GitHub trigger settings**:
+- Filter: `build.pull_request.labels includes "mp" || build.pull_request.labels includes "full" || build.branch == 'dev'`
+- Rebuild on PR label change: Yes
+- Skip queued / cancel running branch builds: Yes
+
+Heavy test (2 GPUs, Docker-in-Docker, ~45 min) — run on `"mp"`/`"full"` label or dev push, not every PR.
+
+> Builds whose only changes are docs/`*.md`/`LICENSE`/`.github/**` auto-pass
+> via the [path filter](../README.md#path-based-skip-auto-pass-on-docs-only-changes).
+> Changes under `.buildkite/` always run. Add `force-ci` label to the PR to
+> bypass.
diff --git a/.buildkite/k3_tests/multiprocess/buildkite-pipeline.yml b/.buildkite/k3_tests/multiprocess/buildkite-pipeline.yml
new file mode 100644
index 0000000..0178e84
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/buildkite-pipeline.yml
@@ -0,0 +1,11 @@
+# Paste this into the Buildkite pipeline's "Steps" editor.
+# It uploads the real pipeline definition from the repo.
+agents:
+  queue: "k8s"
+
+env:
+  HF_TOKEN: ""  # set your HuggingFace token here (needed for gated model access)
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/multiprocess/pipeline.yml
diff --git a/.buildkite/k3_tests/multiprocess/pipeline.yml b/.buildkite/k3_tests/multiprocess/pipeline.yml
new file mode 100644
index 0000000..bf9936b
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/pipeline.yml
@@ -0,0 +1,279 @@
+# Multiprocess tests — one step per test, run in parallel.
+# Each step gets its own K8s pod with the exact GPU count it needs.
+# Tests are grouped by GPU requirement; the 2-GPU group is listed first so
+# these heavier jobs get scheduled before 1-GPU jobs.
+#   2-GPU: LMCache+vLLM on GPU 0, baseline on GPU 1 (or TP=2 across both).
+#   1-GPU: LMCache+vLLM on GPU 0 only (no baseline server).
+
+# Retry policy for known-flaky long-running multiprocess steps.
+# Note: exit_status "*" matches 1-255 only; -1 (agent lost) needs a separate rule.
+x-flaky-retry: &flaky-retry
+  automatic:
+    - exit_status: -1
+      limit: 2
+    - exit_status: "*"
+      limit: 2
+
+steps:
+  - group: ":compression: Multiprocess (2-GPU)"
+    if: build.env("VERIFY_AND_PIN_VLLM") !~ /true/
+    steps:
+      - label: ":compression: vllm_bench"
+        command: .buildkite/k3_tests/multiprocess/run.sh vllm_bench
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec: &pod-2gpu
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources: { limits: { "nvidia.com/gpu": "2" } }
+                    volumeMounts: &vol-mounts
+                      - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                volumes: &vols
+                  - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: long_doc_qa"
+        command: .buildkite/k3_tests/multiprocess/run.sh long_doc_qa
+        timeout_in_minutes: 30
+        retry: *flaky-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-2gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: long_doc_qa_l2"
+        command: .buildkite/k3_tests/multiprocess/run.sh long_doc_qa_l2
+        timeout_in_minutes: 30
+        retry: *flaky-retry
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-2gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: deadlock"
+        command: .buildkite/k3_tests/multiprocess/run.sh deadlock
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-2gpu } }]
+        artifact_paths: ["*.log"]
+
+      # Two LMCache MP instances + two vLLM instances + one coordinator on a
+      # single 2-GPU pod (localhost). Verifies engine B serves a long prompt's
+      # KV from engine A over P2P.
+      - label: ":compression: p2p"
+        command: .buildkite/k3_tests/multiprocess/run.sh p2p
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-2gpu } }]
+        artifact_paths: ["*.log"]
+
+  - group: ":compression: Multiprocess (1-GPU)"
+    if: build.env("VERIFY_AND_PIN_VLLM") !~ /true/
+    steps:
+      - label: ":compression: lm_eval"
+        command: .buildkite/k3_tests/multiprocess/run.sh lm_eval
+        timeout_in_minutes: 30
+        retry: *flaky-retry
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec: &pod-1gpu
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources: { limits: { "nvidia.com/gpu": "1" } }
+                    volumeMounts: *vol-mounts
+                volumes: *vols
+        artifact_paths: ["*.log"]
+
+      # Engine-driven transfer mode correctness on GPU (SHM transport).
+      # Default CUDA dispatch is lmcache_driven (server-side IPC handle);
+      # this step forces engine_driven (worker-side gather/scatter via SHM)
+      # and verifies gsm8k outputs are still bit-exact across cache-population
+      # and cache-hit runs.
+      #
+      # To enable SHM transport:
+      #   - L1_USE_LAZY=false disables lazy allocation so L1 is backed by a
+      #     POSIX SHM segment that the worker can mmap.
+      #   - CPU_BUFFER_SIZE=20 caps L1 at 20GB (needs /dev/shm >= 20GB).
+      #   - dshm volume provides a 24Gi tmpfs mount at /dev/shm.
+      - label: ":compression: lm_eval_engine_driven"
+        command: .buildkite/k3_tests/multiprocess/run.sh lm_eval
+        timeout_in_minutes: 30
+        env:
+          LMCACHE_MP_TRANSFER_MODE: "engine_driven"
+          L1_USE_LAZY: "false"
+          CPU_BUFFER_SIZE: "80"
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec:
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources: { limits: { "nvidia.com/gpu": "1" } }
+                    volumeMounts:
+                      - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                      - { name: dshm, mountPath: /dev/shm }
+                volumes:
+                  - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+                  - { name: dshm, emptyDir: { medium: Memory, sizeLimit: 128Gi } }
+        artifact_paths: ["*.log"]
+
+      # HMA correctness check on google/gemma-4-31B-it (a hybrid model whose KV
+      # cache groups get different block sizes). Runs gsm8k, resets vLLM's prefix
+      # cache (LMCache preserved), reruns served by LMCache, and asserts the two
+      # runs' scores match. Single GPU, no baseline.
+      - label: ":compression: hma_lm_eval_gemma4"
+        command: .buildkite/k3_tests/multiprocess/run.sh hma_lm_eval_gemma4
+        timeout_in_minutes: 60
+        retry: *flaky-retry
+        env:
+          MODEL: "google/gemma-4-31B-it"
+          # Allow a small score difference between the two runs.
+          SCORE_TOLERANCE: "0.03"
+          ATTENTION_BACKEND: "auto"
+          GPU_MEMORY_UTILIZATION: "0.85"
+          # 31B load + CUDA-graph capture is slow; raise the readiness timeout
+          # above the 300s default.
+          MAX_WAIT_SECONDS: "600"
+          # Cap samples and enlarge the CPU pool so the retrieve run stays
+          # cache-served (31B's per-token KV is large).
+          LIMIT: "100"
+          CPU_BUFFER_SIZE: "200"
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: fault_tolerance"
+        command: .buildkite/k3_tests/multiprocess/run.sh fault_tolerance
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: restart_recovery"
+        command: .buildkite/k3_tests/multiprocess/run.sh restart_recovery
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: cache_stats"
+        command: .buildkite/k3_tests/multiprocess/run.sh cache_stats
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: http_api"
+        command: .buildkite/k3_tests/multiprocess/run.sh http_api
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins: [{ kubernetes: { podSpec: *pod-1gpu } }]
+        artifact_paths: ["*.log"]
+
+      - label: ":compression: gds_smoke_test"
+        command: .buildkite/k3_tests/multiprocess/run.sh gds_smoke_test
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec:
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources: { limits: { "nvidia.com/gpu": "1" } }
+                    volumeMounts:
+                      - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                      - { name: scratch, mountPath: /scratch }
+                      - { name: udev, mountPath: /run/udev, readOnly: true }
+                volumes:
+                  - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+                  - { name: scratch, hostPath: { path: /data/gds-scratch, type: DirectoryOrCreate } }
+                  - { name: udev, hostPath: { path: /run/udev, type: Directory } }
+        artifact_paths: ["*.log"]
+
+  - group: ":compression: Multiprocess (CPU-only)"
+    if: build.env("VERIFY_AND_PIN_VLLM") !~ /true/
+    steps:
+      # Note: LMCACHE_SHM_NAME uses `${VAR-default}` (not `:-`) in the
+      # runner script, so an empty string ("") is meaningful and differs
+      # from unset. `__default__` is the sentinel meaning "shm mode".
+      - label: ":compression: cpu_e2e_validation ({{matrix.mode}})"
+        # matrix.adjustments does not support `env:` in Buildkite. Instead
+        # we branch on {{matrix.mode}} inside the command to set the
+        # per-mode env before invoking the shared runner script.
+        command: |
+          case "{{matrix.mode}}" in
+            shm) ;;  # rely on script defaults (engine-driven + shm transport)
+            pickle) export LMCACHE_SHM_NAME="" ;;
+            server_copy) export LMCACHE_MP_TRANSFER_MODE="lmcache_driven" ;;
+          esac
+          bash .github/scripts/run-cpu-e2e-validation.sh
+        matrix:
+          setup:
+            mode:
+              - "shm"
+              - "pickle"
+              - "server_copy"
+        timeout_in_minutes: 30
+        agents: { queue: "k8s" }
+        plugins:
+          - kubernetes:
+              podSpec:
+                containers:
+                  - name: container-0
+                    image: lmcache/ci-base:latest
+                    imagePullPolicy: Never
+                    resources:
+                      requests:
+                        cpu: "8"
+                        memory: "256Gi"
+                      limits:
+                        cpu: "8"
+                        memory: "256Gi"
+                    volumeMounts:
+                      - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                      - { name: dshm, mountPath: /dev/shm }
+                volumes:
+                  - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+                  - { name: dshm, emptyDir: { medium: Memory, sizeLimit: 4Gi } }
+
+  # Canary path for VERIFY_AND_PIN_VLLM=true: skips every real test group
+  # above (each group's `if` evaluates to false) and instead runs a single
+  # vllm_bench step that proves the freshly-installed vLLM nightly works
+  # with LMCache. On success, the verified vllm wheel version is pushed to
+  # the `buildkite_latest_tested_vllm` branch so downstream builds can pin
+  # to a known-good nightly instead of resolving "latest" again.
+  - label: ":pushpin: Verify & pin vLLM nightly"
+    if: build.env("VERIFY_AND_PIN_VLLM") =~ /true/
+    command: |
+      .buildkite/k3_tests/multiprocess/run.sh vllm_bench
+      bash .buildkite/k3_tests/multiprocess/scripts/pin-tested-vllm.sh
+    timeout_in_minutes: 30
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources: { limits: { "nvidia.com/gpu": "2" } }
+                env:
+                  - name: GITHUB_TOKEN
+                    valueFrom:
+                      secretKeyRef:
+                        name: buildkite-git-creds
+                        key: GITHUB_TOKEN
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+    artifact_paths: ["*.log"]
diff --git a/.buildkite/k3_tests/multiprocess/run.sh b/.buildkite/k3_tests/multiprocess/run.sh
new file mode 100755
index 0000000..88df1cd
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/run.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Multiprocess test entrypoint for K8s pods.
+# Usage: run.sh <test_name>
+#   test_name: lm_eval | hma_lm_eval_gemma4 | vllm_bench | long_doc_qa
+#              | long_doc_qa_l2 | fault_tolerance | deadlock | restart_recovery
+#              | gds_smoke_test | p2p
+# Thin wrapper: sets up environment, then delegates to scripts/.
+# No Docker -- all processes run natively in the pod.
+set -euo pipefail
+
+TEST_NAME="${1:?Usage: $0 <test_name>  (lm_eval|hma_lm_eval_gemma4|vllm_bench|long_doc_qa|long_doc_qa_l2|fault_tolerance|deadlock|restart_recovery|cache_stats|http_api|p2p)}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+
+# ── Environment setup ────────────────────────────────────────
+source .buildkite/k3_harness/setup-env.sh
+
+# Install test extras (lm-eval for eval workload, openai/pandas/matplotlib for benchmarks)
+uv pip install 'lm-eval[api]' openai pandas matplotlib
+
+# ── Ensure all scripts are executable ────────────────────────
+chmod +x "${SCRIPT_DIR}"/scripts/*.sh
+
+# ── Run the actual test logic ────────────────────────────────
+exec bash "${SCRIPT_DIR}/scripts/run-single-test.sh" "$TEST_NAME"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/cleanup.sh b/.buildkite/k3_tests/multiprocess/scripts/cleanup.sh
new file mode 100755
index 0000000..2a61601
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/cleanup.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Cleanup background processes launched for multiprocessing tests.
+# This script should always be called, even on failure.
+
+BUILD_ID="${BUILD_ID:-local_$$}"
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+
+echo "=== Cleaning up background processes ==="
+
+if [[ -f "$PID_FILE" ]]; then
+    while IFS= read -r pid; do
+        if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+            echo "Killing PID $pid"
+            # Capture a snippet of the process log before killing
+            kill "$pid" 2>/dev/null || true
+            wait "$pid" 2>/dev/null || true
+            echo "PID $pid stopped"
+        fi
+    done < "$PID_FILE"
+    rm -f "$PID_FILE"
+else
+    echo "No PID file found at $PID_FILE"
+fi
+
+# Also kill any stray vllm/lmcache processes from this build
+# (safety net in case PIDs weren't recorded)
+for port in "${VLLM_PORT:-8000}" "${VLLM_BASELINE_PORT:-9000}" "${LMCACHE_PORT:-6555}"; do
+    fuser -k "${port}/tcp" 2>/dev/null || true
+done
+
+# Remove the GDS slab scratch dir (only set for gds_* tests). It lives on the
+# /scratch hostPath (host-local NVMe), so it persists past the pod and the
+# preallocated slab is large -- drop it now that the server is stopped.
+if [[ -n "${GDS_L1_PATH:-}" ]]; then
+    echo "Removing GDS slab dir: $GDS_L1_PATH"
+    rm -rf "${GDS_L1_PATH}" 2>/dev/null || true
+fi
+
+echo "=== Cleanup complete ==="
+
+# Copy server logs to the workspace so Buildkite can collect them as artifacts
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+cp /tmp/build_${BUILD_ID}_*.log "${REPO_ROOT}/" 2>/dev/null || true
+
+# Wait for GPU memory to be fully released
+echo "Waiting 5 seconds for GPU memory to be released..."
+sleep 5
diff --git a/.buildkite/k3_tests/multiprocess/scripts/launch-processes.sh b/.buildkite/k3_tests/multiprocess/scripts/launch-processes.sh
new file mode 100755
index 0000000..4e40052
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/launch-processes.sh
@@ -0,0 +1,199 @@
+#!/usr/bin/env bash
+# Launch LMCache MP server, vLLM with LMCache, and vLLM baseline
+# as native background processes (no Docker).
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration (inherited from run-mp-test.sh)
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+vllm_port="${VLLM_PORT:-8000}"
+vllm_baseline_port="${VLLM_BASELINE_PORT:-9000}"
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+
+# K8s assigns exactly 2 GPUs as devices 0 and 1 (overridable for local runs).
+GPU_FOR_VLLM="${GPU_FOR_VLLM:-0}"
+GPU_FOR_BASELINE="${GPU_FOR_BASELINE:-1}"
+echo "Using GPU $GPU_FOR_VLLM for vLLM with LMCache"
+echo "Using GPU $GPU_FOR_BASELINE for vLLM baseline"
+
+# Check GPU memory and set gpu-memory-utilization for very large GPUs.
+# Without this, vLLM allocates so much KV cache that APC covers all prefixes
+# and LMCache's cache path is never exercised, making the test pass vacuously.
+GPU_MEMORY_UTIL_ARG=""
+GPU_MEMORY_MB=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits -i "${GPU_FOR_VLLM}" | tr -d ' ')
+GPU_MEMORY_GB=$((GPU_MEMORY_MB / 1024))
+echo "Detected GPU memory: ${GPU_MEMORY_GB}GB (${GPU_MEMORY_MB}MB)"
+
+if [ -n "${GPU_MEMORY_UTILIZATION:-}" ]; then
+    # Explicit override (e.g. large models like gemma-4-31B whose ~63GB of
+    # weights alone exceed the default 0.5 fraction and would fail to load).
+    echo "Using configured --gpu-memory-utilization ${GPU_MEMORY_UTILIZATION}"
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization ${GPU_MEMORY_UTILIZATION}"
+elif [ "$GPU_MEMORY_GB" -gt 90 ]; then
+    echo "GPU memory > 90GB, adding --gpu-memory-utilization 0.5"
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization 0.5"
+fi
+
+# Attention backend for both vLLM servers. Defaults to FLASH_ATTN (what the
+# batch-invariant lm_eval needs). Models with heterogeneous head dimensions
+# (e.g. gemma-4) must NOT pin FLASH_ATTN -- set ATTENTION_BACKEND=auto so vLLM
+# selects the backend itself (gemma-4 auto-forces TRITON_ATTN).
+ATTENTION_BACKEND="${ATTENTION_BACKEND:-FLASH_ATTN}"
+ATTENTION_BACKEND_ARG=""
+if [ -n "$ATTENTION_BACKEND" ] && [ "$ATTENTION_BACKEND" != "auto" ]; then
+    ATTENTION_BACKEND_ARG="--attention-backend $ATTENTION_BACKEND"
+fi
+
+# Optionally run vLLM in eager mode (skip CUDA graph capture) for both servers.
+# Off by default: verified to break the bit-exact run1 == run2 check in the
+# determinism tests (lm_eval) -- eager changes the kernel path enough to diverge
+# across the cold/warm batch difference even under VLLM_BATCH_INVARIANT. Enable
+# (ENFORCE_EAGER=1) only for large models whose CUDA-graph capture would
+# otherwise time out at launch (those tests use a tolerance, not bit-exactness).
+ENFORCE_EAGER_ARG=""
+if [ "${ENFORCE_EAGER:-0}" = "1" ] || [ "${ENFORCE_EAGER:-0}" = "true" ]; then
+    ENFORCE_EAGER_ARG="--enforce-eager"
+fi
+
+# Pin max model length for both servers; defaults to "auto" (vLLM derives the
+# largest length that fits KV memory). Verified not to affect the bit-exact
+# determinism tests. Override via MAX_MODEL_LEN if a model needs a fixed length.
+MAX_MODEL_LEN="${MAX_MODEL_LEN:-auto}"
+MAX_MODEL_LEN_ARG="--max-model-len ${MAX_MODEL_LEN}"
+
+# LMCache server chunk size in tokens. Empty -> server default.
+CHUNK_SIZE_ARG=""
+if [ -n "${CHUNK_SIZE:-}" ]; then
+    CHUNK_SIZE_ARG="--chunk-size ${CHUNK_SIZE}"
+fi
+
+# vLLM batch-invariant mode. On by default; GDN/Mamba backends do not support it.
+BATCH_INVARIANT="${BATCH_INVARIANT:-1}"
+
+# Mamba KV cache mode + prefix caching, set only for hybrid Mamba models.
+MAMBA_ARGS=""
+if [ -n "${MAMBA_CACHE_MODE:-}" ]; then
+    MAMBA_ARGS="--mamba-cache-mode ${MAMBA_CACHE_MODE} --enable-prefix-caching"
+fi
+
+# Max tokens per scheduler step. Empty -> vLLM default.
+MAX_NUM_BATCHED_TOKENS_ARG=""
+if [ -n "${MAX_NUM_BATCHED_TOKENS:-}" ]; then
+    MAX_NUM_BATCHED_TOKENS_ARG="--max-num-batched-tokens ${MAX_NUM_BATCHED_TOKENS}"
+fi
+
+# L1 lazy allocation mode. Default is lazy (--l1-use-lazy). Set L1_USE_LAZY=false
+# to disable lazy allocation, which enables POSIX SHM-backed L1 pool for the
+# engine_driven SHM transfer path. When lazy is enabled (default), the SHM pool
+# is disabled and engine_driven falls back to pickle transport.
+L1_LAZY_ARG=""
+if [ "${L1_USE_LAZY:-true}" = "false" ]; then
+    L1_LAZY_ARG="--no-l1-use-lazy"
+    echo "L1 lazy allocation disabled (SHM transport enabled)"
+fi
+
+# Store PIDs in a file so cleanup.sh can find them
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+> "$PID_FILE"
+
+# ── 1. LMCache Multiprocess Server ──────────────────────────
+echo "=== Launching LMCache MP server ==="
+echo "Port: $LMCACHE_PORT"
+
+# Optional GDS L1 slab tier (gds_* tests). When GDS_L1_PATH is set, the L1
+# medium becomes an NVMe slab accessed via cuFile DMA instead of pinned DRAM;
+# --l1-size-gb then sizes the slab. The path must be on a GDS-capable
+# filesystem (local NVMe), provided by the /scratch hostPath mount.
+GDS_L1_ARG=""
+if [ -n "${GDS_L1_PATH:-}" ]; then
+    echo "GDS L1 tier enabled; slab directory: $GDS_L1_PATH"
+    GDS_L1_ARG="--gds-l1-path ${GDS_L1_PATH}"
+fi
+
+CUDA_VISIBLE_DEVICES="${GPU_FOR_VLLM}" \
+lmcache server \
+    --l1-size-gb "$CPU_BUFFER_SIZE" \
+    --eviction-policy LRU \
+    --max-workers "$MAX_WORKERS" \
+    $CHUNK_SIZE_ARG \
+    --port "$LMCACHE_PORT" \
+    ${GDS_L1_ARG} \
+    ${L1_LAZY_ARG} \
+    > "/tmp/build_${BUILD_ID}_lmcache.log" 2>&1 &
+
+LMCACHE_PID=$!
+echo "$LMCACHE_PID" >> "$PID_FILE"
+echo "LMCache MP server started (PID=$LMCACHE_PID)"
+
+# Wait for LMCache to initialize
+echo "Waiting for LMCache to initialize..."
+sleep 10
+
+# Unset VLLM_PORT so vLLM's internal get_open_port() picks a random
+# ephemeral port for torch.distributed instead of trying serving_port+1.
+# Without this, both instances fight over the same internal port.
+unset VLLM_PORT
+
+# ── 2. vLLM with LMCache ────────────────────────────────────
+echo "=== Launching vLLM with LMCache ==="
+echo "Model: $MODEL"
+echo "Port: $vllm_port"
+
+CUDA_VISIBLE_DEVICES="${GPU_FOR_VLLM}" \
+VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+VLLM_SERVER_DEV_MODE=1 \
+VLLM_BATCH_INVARIANT=${BATCH_INVARIANT} \
+PYTHONHASHSEED=0 \
+vllm serve "$MODEL" \
+    --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $LMCACHE_PORT, \"lmcache.mp.mq_timeout\": 10}}" \
+    $ATTENTION_BACKEND_ARG \
+    --port "$vllm_port" \
+    --no-async-scheduling \
+    $MAX_MODEL_LEN_ARG \
+    $ENFORCE_EAGER_ARG \
+    $GPU_MEMORY_UTIL_ARG \
+    $MAMBA_ARGS \
+    $MAX_NUM_BATCHED_TOKENS_ARG \
+    > "/tmp/build_${BUILD_ID}_vllm.log" 2>&1 &
+
+VLLM_PID=$!
+echo "$VLLM_PID" >> "$PID_FILE"
+echo "vLLM with LMCache started (PID=$VLLM_PID)"
+
+# ── 3. vLLM Baseline (without LMCache) ──────────────────────
+# Only launched for tests that compare against a baseline (2-GPU pods).
+# Single-GPU tests set LAUNCH_BASELINE=false and skip this entirely.
+if [[ "${LAUNCH_BASELINE:-true}" == "true" ]]; then
+    echo "=== Launching vLLM baseline ==="
+    echo "Port: $vllm_baseline_port"
+
+    CUDA_VISIBLE_DEVICES="${GPU_FOR_BASELINE}" \
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    VLLM_SERVER_DEV_MODE=1 \
+    VLLM_BATCH_INVARIANT=1 \
+    PYTHONHASHSEED=0 \
+    vllm serve "$MODEL" \
+        $ATTENTION_BACKEND_ARG \
+        --port "$vllm_baseline_port" \
+        --no-async-scheduling \
+        $MAX_MODEL_LEN_ARG \
+        $ENFORCE_EAGER_ARG \
+        $GPU_MEMORY_UTIL_ARG \
+        > "/tmp/build_${BUILD_ID}_vllm_baseline.log" 2>&1 &
+
+    VLLM_BASELINE_PID=$!
+    echo "$VLLM_BASELINE_PID" >> "$PID_FILE"
+    echo "vLLM baseline started (PID=$VLLM_BASELINE_PID)"
+else
+    echo "=== Skipping vLLM baseline (LAUNCH_BASELINE=false, 1-GPU test) ==="
+fi
+
+echo "=== All processes launched ==="
+echo "PIDs: LMCache=$LMCACHE_PID, vLLM=$VLLM_PID, Baseline=${VLLM_BASELINE_PID:-skipped}"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/pin-tested-vllm.sh b/.buildkite/k3_tests/multiprocess/scripts/pin-tested-vllm.sh
new file mode 100644
index 0000000..9a5c3c8
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/pin-tested-vllm.sh
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# Pin the currently-installed vLLM nightly to the
+# `buildkite_latest_tested_vllm` branch.
+#
+# Runs ONLY when the canary vllm_bench step has succeeded and
+# VERIFY_AND_PIN_VLLM=true. Records the just-verified vllm wheel version so
+# downstream builds can install the same version deterministically instead
+# of resolving "latest nightly" again.
+#
+# Two files are maintained on the dedicated branch:
+#   tested_vllm_versions.csv  -- JSON Lines, append-only history. Each line
+#                                is one self-contained record.
+#   latest_tested_vllm.txt    -- Plain text, single line: the most recent
+#                                verified version. Overwritten every run.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+cd "${REPO_ROOT}"
+
+export GIT_TERMINAL_PROMPT=0
+
+# ── Resolve the version that's actually installed in this pod ───────────
+VLLM_VERSION="$(python -c 'import vllm; print(vllm.__version__)')"
+if [[ -z "${VLLM_VERSION}" ]]; then
+    echo "[ERROR] could not read vllm.__version__ from the live env" >&2
+    exit 1
+fi
+echo "Verified vLLM version: ${VLLM_VERSION}"
+
+# ── Resolve commit SHAs so consumers don't need to call any external API ─
+# The PEP 440 local version after `+g` is the short commit SHA, e.g.
+# 0.23.1rc1.dev508+gc6dd32a81 -> c6dd32a81. Expand it to the full 40-char
+# SHA via the public GitHub commits API; we already have GITHUB_TOKEN in
+# the env (5000 req/h). The full SHA gives us the permanent
+# wheels.vllm.ai/<full-sha>/<cuda>/ archive URL, which keeps working even
+# after the rolling nightly index has dropped the wheel.
+VLLM_SHORT_SHA="${VLLM_VERSION##*+g}"
+if [[ "${VLLM_SHORT_SHA}" == "${VLLM_VERSION}" \
+        || ! "${VLLM_SHORT_SHA}" =~ ^[0-9a-f]+$ ]]; then
+    VLLM_SHORT_SHA=""
+fi
+
+VLLM_FULL_SHA=""
+if [[ -n "${VLLM_SHORT_SHA}" ]]; then
+    gh_auth_args=()
+    if [[ -n "${GITHUB_TOKEN:-}" ]]; then
+        gh_auth_args=(-H "Authorization: Bearer ${GITHUB_TOKEN}")
+    fi
+    for attempt in 1 2 3; do
+        VLLM_FULL_SHA="$(curl -fsSL --connect-timeout 5 --max-time 10 \
+            -H "Accept: application/vnd.github+json" \
+            "${gh_auth_args[@]+"${gh_auth_args[@]}"}" \
+            "https://api.github.com/repos/vllm-project/vllm/commits/${VLLM_SHORT_SHA}" \
+            2>/dev/null \
+            | jq -r '.sha // empty')" || true
+        if [[ "${VLLM_FULL_SHA}" =~ ^[0-9a-f]{40}$ ]]; then
+            break
+        fi
+        VLLM_FULL_SHA=""
+        echo "[INFO] GitHub commit lookup attempt ${attempt} for" \
+             "${VLLM_SHORT_SHA} returned no SHA; retrying..." >&2
+        sleep 2
+    done
+fi
+
+if [[ -n "${VLLM_FULL_SHA}" ]]; then
+    VLLM_ARCHIVE_INDEX="https://wheels.vllm.ai/${VLLM_FULL_SHA}/cu130"
+    echo "Resolved full SHA: ${VLLM_FULL_SHA}"
+    echo "Archive index:     ${VLLM_ARCHIVE_INDEX}"
+else
+    VLLM_ARCHIVE_INDEX=""
+    echo "[WARN] could not resolve full SHA for short SHA" \
+         "'${VLLM_SHORT_SHA:-<none>}'; archive_index_url will be empty" \
+         "and consumers will fall back to live API lookup" >&2
+fi
+
+CI_REPO="LMCache/LMCache"
+CI_BRANCH="buildkite_latest_tested_vllm"
+
+if [[ -n "${GITHUB_TOKEN:-}" ]]; then
+    CI_REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/${CI_REPO}.git"
+else
+    echo "[WARN] GITHUB_TOKEN not set — push will likely fail" >&2
+    CI_REPO_URL="https://github.com/${CI_REPO}.git"
+fi
+
+WORK_DIR="/tmp/pin_vllm_$$"
+trap 'rm -rf "${WORK_DIR}"' EXIT
+
+echo "--- Preparing ${CI_BRANCH} branch from ${CI_REPO}"
+if ! git clone --depth=1 --branch "${CI_BRANCH}" "${CI_REPO_URL}" \
+        "${WORK_DIR}" 2>/dev/null; then
+    # Branch does not exist yet -- create an orphan with no parent history.
+    rm -rf "${WORK_DIR}"
+    mkdir -p "${WORK_DIR}"
+    git -C "${WORK_DIR}" init -q
+    git -C "${WORK_DIR}" remote add origin "${CI_REPO_URL}"
+    git -C "${WORK_DIR}" checkout --orphan "${CI_BRANCH}"
+    # Drop anything that the orphan checkout might have staged from HEAD.
+    git -C "${WORK_DIR}" rm -rf --cached . >/dev/null 2>&1 || true
+    find "${WORK_DIR}" -mindepth 1 -maxdepth 1 ! -name ".git" \
+        -exec rm -rf {} +
+fi
+
+# ── Update files ────────────────────────────────────────────────────────
+HISTORY_FILE="${WORK_DIR}/tested_vllm_versions.csv"
+LATEST_FILE="${WORK_DIR}/latest_tested_vllm.txt"
+
+TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+BUILD_URL="${BUILDKITE_BUILD_URL:-}"
+BUILD_NUMBER="${BUILDKITE_BUILD_NUMBER:-}"
+COMMIT_SHA="${BUILDKITE_COMMIT:-}"
+
+# Append-only history (JSON Lines). Built via python so quoting is safe.
+# Use a quoted heredoc (<<'PY') to disable Bash expansion inside the script,
+# and pass variables via the environment to avoid syntax errors from special
+# characters in values like BUILD_URL.
+TIMESTAMP="${TIMESTAMP}" \
+VLLM_VERSION="${VLLM_VERSION}" \
+VLLM_SHORT_SHA="${VLLM_SHORT_SHA}" \
+VLLM_FULL_SHA="${VLLM_FULL_SHA}" \
+VLLM_ARCHIVE_INDEX="${VLLM_ARCHIVE_INDEX}" \
+BUILD_NUMBER="${BUILD_NUMBER}" \
+BUILD_URL="${BUILD_URL}" \
+COMMIT_SHA="${COMMIT_SHA}" \
+python - "$HISTORY_FILE" <<'PY'
+import json, os, sys
+path = sys.argv[1]
+record = {
+    "timestamp": os.environ.get("TIMESTAMP", ""),
+    "vllm_version": os.environ.get("VLLM_VERSION", ""),
+    "vllm_short_sha": os.environ.get("VLLM_SHORT_SHA", ""),
+    "vllm_full_sha": os.environ.get("VLLM_FULL_SHA", ""),
+    "archive_index_url": os.environ.get("VLLM_ARCHIVE_INDEX", ""),
+    "build_number": os.environ.get("BUILD_NUMBER", ""),
+    "build_url": os.environ.get("BUILD_URL", ""),
+    "commit": os.environ.get("COMMIT_SHA", ""),
+}
+with open(path, "a", encoding="utf-8") as f:
+    f.write(json.dumps(record) + "\n")
+PY
+
+# Latest pointer. The first line is the bare version so older consumers
+# that just `head -n1` keep working; the trailing key=value lines let new
+# consumers skip the live GitHub API lookup entirely.
+{
+    printf '%s\n' "${VLLM_VERSION}"
+    printf 'short_sha=%s\n' "${VLLM_SHORT_SHA}"
+    printf 'full_sha=%s\n' "${VLLM_FULL_SHA}"
+    printf 'archive_index_url=%s\n' "${VLLM_ARCHIVE_INDEX}"
+} > "${LATEST_FILE}"
+
+# ── Commit + push ───────────────────────────────────────────────────────
+cd "${WORK_DIR}"
+git add tested_vllm_versions.csv latest_tested_vllm.txt
+
+if git diff --cached --quiet 2>/dev/null; then
+    echo "No changes to commit (version unchanged?)."
+    exit 0
+fi
+
+git -c user.email="ci@lmcache.ai" -c user.name="LMCache CI" \
+    commit -m "Pin verified vLLM nightly: ${VLLM_VERSION}"
+
+echo "--- Pushing to ${CI_REPO} ${CI_BRANCH}"
+if ! git push origin "HEAD:${CI_BRANCH}" 2>/dev/null; then
+    echo "[WARN] Normal push failed, force-pushing..." >&2
+    git push origin "+HEAD:${CI_BRANCH}" 2>/dev/null || {
+        echo "[ERROR] Failed to push to ${CI_REPO} ${CI_BRANCH}" >&2
+        exit 1
+    }
+fi
+
+echo "--- Pinned vLLM ${VLLM_VERSION} successfully"
+git log --oneline -1
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-cache-stats.sh b/.buildkite/k3_tests/multiprocess/scripts/run-cache-stats.sh
new file mode 100755
index 0000000..5129767
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-cache-stats.sh
@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# Test that kv_transfer_params / cached_token_stats flows end-to-end
+# through the OpenAI-compatible API when LMCache MP mode is active.
+#
+# Flow:
+#   1. Send a long prompt (cold — populates LMCache, no cache hit)
+#   2. Send the same prompt again (warm — should hit LMCache)
+#   3. Verify the response contains cached_token_stats with expected values
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration (inherited from run-single-test.sh)
+VLLM_PORT="${VLLM_PORT:-8000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+STATS_DIR="$RESULTS_DIR/cache_stats"
+mkdir -p "$STATS_DIR"
+
+echo "=== Cache Stats Reporting Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port: $VLLM_PORT"
+echo "Results dir: $STATS_DIR"
+echo ""
+
+# Build a prompt long enough to span multiple LMCache chunks (default
+# chunk_size=256 tokens). Repeating a sentence gives us ~600+ tokens.
+LONG_CONTENT="Explain the history of computer science in great detail. $(printf 'The Turing machine is a fundamental concept in theoretical computer science that defines an abstract machine capable of manipulating symbols on a strip of tape according to a table of rules. %.0s' {1..20})"
+
+send_request() {
+    local label="$1"
+    local output_file="$2"
+
+    echo "--- Sending request: $label ---"
+    local http_code
+    http_code=$(curl -s -o "$output_file" -w "%{http_code}" \
+        -X POST "http://localhost:${VLLM_PORT}/v1/chat/completions" \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"${MODEL}\",
+            \"messages\": [{\"role\": \"user\", \"content\": $(python3 -c "import json; print(json.dumps('$LONG_CONTENT'))")}],
+            \"max_tokens\": 1,
+            \"kv_transfer_params\": {\"cached_token_stats\": true}
+        }")
+
+    if [ "$http_code" -ne 200 ]; then
+        echo "FAIL: $label returned HTTP $http_code"
+        cat "$output_file"
+        return 1
+    fi
+    echo "$label: HTTP 200 OK"
+}
+
+validate_stats_present() {
+    local label="$1"
+    local response_file="$2"
+
+    python3 -c "
+import json, sys
+
+with open('$response_file') as f:
+    data = json.load(f)
+
+kv_params = data.get('kv_transfer_params')
+if kv_params is None:
+    print('FAIL: $label — kv_transfer_params is missing from response')
+    sys.exit(1)
+
+stats = kv_params.get('cached_token_stats')
+if stats is None:
+    print('FAIL: $label — cached_token_stats is missing from kv_transfer_params')
+    print(f'  kv_transfer_params = {kv_params}')
+    sys.exit(1)
+
+required_keys = [
+    'num_vllm_cached_tokens',
+    'num_lmcache_cached_tokens',
+    'num_lmcache_extra_cached_tokens',
+]
+missing = [k for k in required_keys if k not in stats]
+if missing:
+    print(f'FAIL: $label — missing keys in cached_token_stats: {missing}')
+    print(f'  cached_token_stats = {stats}')
+    sys.exit(1)
+
+for k in required_keys:
+    v = stats[k]
+    if not isinstance(v, int) or v < 0:
+        print(f'FAIL: $label — {k} should be a non-negative integer, got {v!r}')
+        sys.exit(1)
+
+print(f'PASS: $label — cached_token_stats present with all required keys')
+print(f'  num_vllm_cached_tokens:          {stats[\"num_vllm_cached_tokens\"]}')
+print(f'  num_lmcache_cached_tokens:       {stats[\"num_lmcache_cached_tokens\"]}')
+print(f'  num_lmcache_extra_cached_tokens: {stats[\"num_lmcache_extra_cached_tokens\"]}')
+"
+}
+
+validate_warm_hit() {
+    local cold_file="$1"
+    local warm_file="$2"
+
+    python3 -c "
+import json, sys
+
+with open('$cold_file') as f:
+    cold = json.load(f)
+with open('$warm_file') as f:
+    warm = json.load(f)
+
+cold_stats = cold['kv_transfer_params']['cached_token_stats']
+warm_stats = warm['kv_transfer_params']['cached_token_stats']
+
+cold_lmcache = cold_stats['num_lmcache_cached_tokens']
+warm_lmcache = warm_stats['num_lmcache_cached_tokens']
+
+print(f'Cold request — num_lmcache_cached_tokens: {cold_lmcache}')
+print(f'Warm request — num_lmcache_cached_tokens: {warm_lmcache}')
+
+if warm_lmcache <= cold_lmcache:
+    print(f'FAIL: warm request should have more LMCache hits than cold request')
+    print(f'  cold={cold_lmcache}, warm={warm_lmcache}')
+    sys.exit(1)
+
+if warm_lmcache == 0:
+    print('FAIL: warm request has 0 LMCache cached tokens (cache not populated?)')
+    sys.exit(1)
+
+print(f'PASS: warm request has more LMCache hits ({warm_lmcache} > {cold_lmcache})')
+"
+}
+
+# ── Step 1: Cold request (populates LMCache) ──────────────────
+echo "============================================"
+echo "=== Step 1: Cold request ==="
+echo "============================================"
+if ! send_request "Cold" "$STATS_DIR/cold_response.json"; then
+    exit 1
+fi
+if ! validate_stats_present "Cold" "$STATS_DIR/cold_response.json"; then
+    exit 1
+fi
+echo ""
+
+# Small delay to let the store operation complete in LMCache
+sleep 2
+
+# ── Step 2: Warm request (same prompt, should hit cache) ──────
+echo "============================================"
+echo "=== Step 2: Warm request ==="
+echo "============================================"
+if ! send_request "Warm" "$STATS_DIR/warm_response.json"; then
+    exit 1
+fi
+if ! validate_stats_present "Warm" "$STATS_DIR/warm_response.json"; then
+    exit 1
+fi
+echo ""
+
+# ── Step 3: Validate cache hit improvement ────────────────────
+echo "============================================"
+echo "=== Step 3: Validate cache hit ==="
+echo "============================================"
+if ! validate_warm_hit "$STATS_DIR/cold_response.json" "$STATS_DIR/warm_response.json"; then
+    exit 1
+fi
+echo ""
+
+# ── Step 4: Verify opt-in behavior ────────────────────────────
+# Request WITHOUT kv_transfer_params should NOT have stats in response.
+echo "============================================"
+echo "=== Step 4: Verify opt-in (no stats without opt-in) ==="
+echo "============================================"
+
+echo "--- Sending request without kv_transfer_params ---"
+http_code=$(curl -s -o "$STATS_DIR/no_opt_in_response.json" -w "%{http_code}" \
+    -X POST "http://localhost:${VLLM_PORT}/v1/chat/completions" \
+    -H "Content-Type: application/json" \
+    -d "{
+        \"model\": \"${MODEL}\",
+        \"messages\": [{\"role\": \"user\", \"content\": \"Hello, how are you?\"}],
+        \"max_tokens\": 1
+    }")
+
+if [ "$http_code" -ne 200 ]; then
+    echo "FAIL: no-opt-in request returned HTTP $http_code"
+    exit 1
+fi
+
+python3 -c "
+import json, sys
+
+with open('$STATS_DIR/no_opt_in_response.json') as f:
+    data = json.load(f)
+
+kv_params = data.get('kv_transfer_params')
+if kv_params is not None:
+    print(f'FAIL: kv_transfer_params should be absent without opt-in, got {kv_params}')
+    sys.exit(1)
+
+print('PASS: kv_transfer_params correctly absent when not opted in')
+"
+echo ""
+
+# ── Summary ───────────────────────────────────────────────────
+echo "============================================"
+echo "=== Cache Stats Reporting Test PASSED ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-deadlock.sh b/.buildkite/k3_tests/multiprocess/scripts/run-deadlock.sh
new file mode 100644
index 0000000..77a84e2
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-deadlock.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Self-contained deadlock regression test.
+#
+# Launches DeepSeek-V2-Lite-Chat with TP=2 (both GPUs) + LMCache server,
+# sends 50 requests with ~30K token prefixes, and verifies they all
+# complete within 3 minutes.  A CUDA-driver/GIL deadlock would cause
+# requests to hang indefinitely, failing the timeout.
+#
+# This test is self-contained: it handles its own server lifecycle
+# instead of using the standard launch-processes.sh / wait-for-servers.sh.
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# ── Configuration ───────────────────────────────────────────
+MODEL="deepseek-ai/DeepSeek-V2-Lite-Chat"
+LMCACHE_PORT="${LMCACHE_PORT:-15554}"
+VLLM_PORT="${VLLM_PORT:-8000}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+TIMEOUT_SECONDS=180   # 3 minutes
+
+# ── Install py-spy for deadlock diagnosis ──────────────────
+echo "=== Installing py-spy ==="
+uv pip install py-spy
+PY_SPY="$(which py-spy)"
+echo "py-spy installed at: $PY_SPY"
+
+PYSPY_LOG="/tmp/build_${BUILD_ID}_pyspy.log"
+
+# ── Helper: dump stacks of server processes via py-spy ─────
+dump_stacks() {
+    echo "" | tee -a "$PYSPY_LOG"
+    echo "=== py-spy stack dump (native + Python) ===" | tee -a "$PYSPY_LOG"
+
+    if kill -0 "$LMCACHE_PID" 2>/dev/null; then
+        echo "" | tee -a "$PYSPY_LOG"
+        echo "--- LMCache server (PID=$LMCACHE_PID) ---" | tee -a "$PYSPY_LOG"
+        sudo "$PY_SPY" dump --pid "$LMCACHE_PID" --native 2>&1 | tee -a "$PYSPY_LOG" || true
+    fi
+
+    # Copy to repo root so cleanup.sh collects it as a Buildkite artifact
+    cp "$PYSPY_LOG" "${REPO_ROOT}/build_${BUILD_ID}_pyspy.log" 2>/dev/null || true
+}
+
+# ── 1. Launch LMCache server ───────────────────────────────
+echo "=== Launching LMCache server ==="
+echo "Port: $LMCACHE_PORT"
+
+lmcache server \
+    --host localhost \
+    --port "$LMCACHE_PORT" \
+    --chunk-size 256 \
+    --l1-size-gb 50 \
+    --eviction-policy LRU \
+    --max-workers 2 \
+    > "/tmp/build_${BUILD_ID}_lmcache.log" 2>&1 &
+
+LMCACHE_PID=$!
+echo "$LMCACHE_PID" >> "$PID_FILE"
+echo "LMCache server started (PID=$LMCACHE_PID)"
+sleep 10
+
+# ── 2. Launch vLLM with DeepSeek TP=2 ─────────────────────
+echo "=== Launching vLLM (DeepSeek TP=2) ==="
+echo "Model: $MODEL"
+echo "Port: $VLLM_PORT"
+
+# Save VLLM_PORT before unsetting — vLLM's internal get_open_port()
+# would otherwise collide with the serving port for torch.distributed.
+SAVED_VLLM_PORT="$VLLM_PORT"
+unset VLLM_PORT
+
+FLASHINFER_DISABLE_VERSION_CHECK=1 \
+VLLM_SERVER_DEV_MODE=1 \
+vllm serve "$MODEL" \
+    --tensor-parallel-size 2 \
+    --distributed-executor-backend mp \
+    --block-size 64 \
+    --trust-remote-code \
+    --load-format dummy \
+    --enable-prefix-caching \
+    --enable-chunked-prefill \
+    --gpu-memory-utilization 0.8 \
+    --max-model-len 65536 \
+    --hf-overrides '{"max_position_embeddings":65536}' \
+    --max-num-seqs 32 \
+    --max-num-batched-tokens 16000 \
+    --scheduling-policy fcfs \
+    --port "$SAVED_VLLM_PORT" \
+    --enforce-eager \
+    --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $LMCACHE_PORT, \"lmcache.mp.mq_timeout\": 60}}" \
+    > "/tmp/build_${BUILD_ID}_vllm.log" 2>&1 &
+
+VLLM_PID=$!
+echo "$VLLM_PID" >> "$PID_FILE"
+echo "vLLM started (PID=$VLLM_PID)"
+
+VLLM_PORT="$SAVED_VLLM_PORT"
+
+# ── 3. Wait for vLLM to be ready ──────────────────────────
+echo "=== Waiting for vLLM to be ready ==="
+if ! wait_for_server "$VLLM_PORT" 600; then
+    echo "vLLM failed to start. Last 100 lines of log:"
+    tail -100 "/tmp/build_${BUILD_ID}_vllm.log" 2>/dev/null || true
+    exit 1
+fi
+
+# ── 4. Run benchmark with timeout ─────────────────────────
+echo "=== Running lmcache bench engine (random-prefill, 50 reqs, ~30K tokens) ==="
+echo "Timeout: ${TIMEOUT_SECONDS}s"
+
+if ! timeout "$TIMEOUT_SECONDS" lmcache bench engine \
+        --engine-url "http://localhost:${VLLM_PORT}" \
+        --workload random-prefill \
+        --tokens-per-gb-kvcache 6000 \
+        --rp-request-length 30000 \
+        --rp-num-requests 50 \
+        --no-interactive \
+        --no-csv \
+        -q; then
+    echo "FAIL: Benchmark failed or timed out (possible deadlock)"
+    echo ""
+    echo "=== LMCache log (last 50 lines) ==="
+    tail -50 "/tmp/build_${BUILD_ID}_lmcache.log" 2>/dev/null || true
+    echo ""
+    echo "=== vLLM log (last 50 lines) ==="
+    tail -50 "/tmp/build_${BUILD_ID}_vllm.log" 2>/dev/null || true
+    exit 1
+fi
+
+echo ""
+echo "=== Benchmark completed within ${TIMEOUT_SECONDS}s ==="
+echo "PASS: No deadlock detected"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-fault-tolerance.sh b/.buildkite/k3_tests/multiprocess/scripts/run-fault-tolerance.sh
new file mode 100755
index 0000000..2bbfbae
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-fault-tolerance.sh
@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# Test LMCache fault tolerance: verify vLLM requests complete after
+# the LMCache MP server is killed mid-flight.
+#
+# Flow:
+#   1. Run a warmup bench (measures baseline timing)
+#   2. Run bench again, killing LMCache server mid-flight
+#   3. Run bench fully without LMCache server
+#   4. Verify all prompts completed in every phase
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration (inherited from run-mp-test.sh)
+VLLM_PORT="${VLLM_PORT:-8000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+
+# Bench parameters
+NUM_PROMPTS="${NUM_PROMPTS:-50}"
+RANDOM_INPUT_LEN="${RANDOM_INPUT_LEN:-10000}"
+RANDOM_OUTPUT_LEN="${RANDOM_OUTPUT_LEN:-1}"
+RANDOM_SEED="${RANDOM_SEED:-42}"
+
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+
+# Output directory
+FT_DIR="$RESULTS_DIR/fault_tolerance"
+mkdir -p "$FT_DIR"
+
+echo "=== Fault Tolerance Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port: $VLLM_PORT"
+echo "LMCache Port: $LMCACHE_PORT"
+echo "Bench: $NUM_PROMPTS prompts, input_len=$RANDOM_INPUT_LEN, output_len=$RANDOM_OUTPUT_LEN"
+echo "Results dir: $FT_DIR"
+echo ""
+
+# ── Step 0: Restart LMCache + vLLM with fresh state ─────────
+# Previous steps may have left processes in an unknown state.
+# Restart both so vLLM registers its GPU context with the new server.
+echo "============================================"
+echo "=== Restarting LMCache + vLLM ==="
+echo "============================================"
+
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+GPU_DEVICE="${GPU_FOR_VLLM:-0}"
+
+# Kill existing LMCache + vLLM (keep baseline on line 3)
+if [ -f "$PID_FILE" ]; then
+    OLD_LMCACHE_PID=$(sed -n '1p' "$PID_FILE")
+    OLD_VLLM_PID=$(sed -n '2p' "$PID_FILE")
+    for pid in $OLD_LMCACHE_PID $OLD_VLLM_PID; do
+        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+            echo "Killing PID $pid"
+            kill "$pid" 2>/dev/null || true
+            wait "$pid" 2>/dev/null || true
+        fi
+    done
+    sleep 2
+fi
+
+# Launch LMCache with L1 config
+CUDA_VISIBLE_DEVICES="${GPU_DEVICE}" \
+lmcache server \
+    --l1-size-gb "$CPU_BUFFER_SIZE" \
+    --eviction-policy LRU \
+    --max-workers "$MAX_WORKERS" \
+    --port "$LMCACHE_PORT" \
+    > "/tmp/build_${BUILD_ID}_lmcache_ft.log" 2>&1 &
+
+NEW_LMCACHE_PID=$!
+echo "LMCache server started (PID=$NEW_LMCACHE_PID)"
+sleep 10
+
+# Launch vLLM with LMCache
+GPU_MEMORY_UTIL_ARG=""
+GPU_MEMORY_MB=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits -i "${GPU_DEVICE}" | tr -d ' ')
+GPU_MEMORY_GB=$((GPU_MEMORY_MB / 1024))
+if [ "$GPU_MEMORY_GB" -gt 90 ]; then
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization 0.5"
+fi
+
+env -u VLLM_PORT \
+    CUDA_VISIBLE_DEVICES="${GPU_DEVICE}" \
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    VLLM_SERVER_DEV_MODE=1 \
+    VLLM_BATCH_INVARIANT=1 \
+    PYTHONHASHSEED=0 \
+vllm serve "$MODEL" \
+    --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $LMCACHE_PORT, \"lmcache.mp.mq_timeout\": 10}}" \
+    --attention-backend FLASH_ATTN \
+    --port "$VLLM_PORT" \
+    --no-async-scheduling \
+    $GPU_MEMORY_UTIL_ARG \
+    > "/tmp/build_${BUILD_ID}_vllm_ft.log" 2>&1 &
+
+NEW_VLLM_PID=$!
+echo "vLLM started (PID=$NEW_VLLM_PID)"
+
+# Update PID file
+if [ -f "$PID_FILE" ]; then
+    sed -i "1s/.*/$NEW_LMCACHE_PID/" "$PID_FILE"
+    sed -i "2s/.*/$NEW_VLLM_PID/" "$PID_FILE"
+else
+    echo "$NEW_LMCACHE_PID" > "$PID_FILE"
+    echo "$NEW_VLLM_PID" >> "$PID_FILE"
+fi
+
+if ! wait_for_server "$VLLM_PORT" 300; then
+    echo "vLLM failed to start"
+    tail -50 "/tmp/build_${BUILD_ID}_lmcache_ft.log" || true
+    tail -50 "/tmp/build_${BUILD_ID}_vllm_ft.log" || true
+    exit 1
+fi
+echo ""
+
+# ── Helpers ──────────────────────────────────────────────────
+
+run_bench() {
+    local description="$1"
+    local result_file="$2"
+
+    echo ""
+    echo "--- $description ---"
+
+    vllm bench serve \
+        --seed "$RANDOM_SEED" \
+        --port "$VLLM_PORT" \
+        --model "$MODEL" \
+        --dataset-name random \
+        --random-input-len "$RANDOM_INPUT_LEN" \
+        --random-output-len "$RANDOM_OUTPUT_LEN" \
+        --num-prompts "$NUM_PROMPTS" \
+        --ignore-eos \
+        --backend openai-chat \
+        --endpoint /v1/chat/completions \
+        --result-dir "$FT_DIR" \
+        --result-filename "$result_file" \
+        --save-result
+
+    local completed
+    completed=$(python3 -c "
+import json
+with open('$FT_DIR/$result_file') as f:
+    data = json.load(f)
+print(data.get('completed', 0))
+")
+
+    echo "$description: $completed / $NUM_PROMPTS completed"
+
+    if [ "$completed" -ne "$NUM_PROMPTS" ]; then
+        echo "FAIL: Expected $NUM_PROMPTS completed, got $completed"
+        return 1
+    fi
+
+    echo "PASS: All $NUM_PROMPTS prompts completed"
+    return 0
+}
+
+get_lmcache_pid() {
+    local pid_file="/tmp/lmcache_mp_pids_${BUILD_ID}"
+    if [[ -f "$pid_file" ]]; then
+        head -1 "$pid_file"
+    fi
+}
+
+# ── Step 1: Warmup bench ─────────────────────────────────────
+echo "============================================"
+echo "=== Fault Tolerance Step 1: Warmup bench ==="
+echo "============================================"
+
+if ! run_bench "Warmup (with LMCache)" "ft_warmup.json"; then
+    echo "FAIL: Warmup bench failed"
+    exit 1
+fi
+
+# Extract duration to calibrate kill timing
+WARMUP_DURATION=$(python3 -c "import json; print(json.load(open('$FT_DIR/ft_warmup.json'))['duration'])")
+KILL_DELAY=$(python3 -c "print(max(3, int($WARMUP_DURATION * 0.4)))")
+echo "Warmup took ${WARMUP_DURATION}s. Will kill LMCache after ${KILL_DELAY}s in next run."
+
+# ── Step 2: Bench with mid-flight LMCache kill ───────────────
+echo ""
+echo "============================================"
+echo "=== Fault Tolerance Step 2: Mid-flight kill ==="
+echo "============================================"
+
+LMCACHE_PID=$(get_lmcache_pid)
+if [ -z "$LMCACHE_PID" ] || ! kill -0 "$LMCACHE_PID" 2>/dev/null; then
+    echo "FAIL: LMCache server not running (PID=$LMCACHE_PID)"
+    exit 1
+fi
+
+echo "LMCache server PID: $LMCACHE_PID"
+echo "Will kill after ${KILL_DELAY}s into bench."
+
+# Start bench in background
+run_bench "Mid-flight kill" "ft_midflight.json" &
+BENCH_PID=$!
+
+# Wait, then kill LMCache
+sleep "$KILL_DELAY"
+echo "Killing LMCache server (PID: $LMCACHE_PID)..."
+kill "$LMCACHE_PID" 2>/dev/null
+wait "$LMCACHE_PID" 2>/dev/null || true
+echo "LMCache server killed at +${KILL_DELAY}s."
+
+# Wait for bench to finish
+echo "Waiting for bench to complete..."
+if ! wait "$BENCH_PID"; then
+    echo "FAIL: Bench did not complete after mid-flight LMCache kill."
+    echo "--- vLLM log (last 50 lines) ---"
+    tail -50 "/tmp/build_${BUILD_ID}_vllm.log" 2>/dev/null || true
+    exit 1
+fi
+
+# ── Step 3: Bench fully without LMCache server ───────────────
+echo ""
+echo "============================================"
+echo "=== Fault Tolerance Step 3: Without LMCache ==="
+echo "============================================"
+
+if ! run_bench "Without LMCache" "ft_without_lmcache.json"; then
+    echo "FAIL: Bench failed without LMCache server."
+    echo "--- vLLM log (last 50 lines) ---"
+    tail -50 "/tmp/build_${BUILD_ID}_vllm.log" 2>/dev/null || true
+    exit 1
+fi
+
+# ── Summary ──────────────────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Fault Tolerance Test PASSED ==="
+echo "============================================"
+
+warmup_completed=$(python3 -c "import json; print(json.load(open('$FT_DIR/ft_warmup.json'))['completed'])")
+warmup_duration=$(python3 -c "import json; print(f\"{json.load(open('$FT_DIR/ft_warmup.json'))['duration']:.1f}\")")
+midflight_completed=$(python3 -c "import json; print(json.load(open('$FT_DIR/ft_midflight.json'))['completed'])")
+midflight_duration=$(python3 -c "import json; print(f\"{json.load(open('$FT_DIR/ft_midflight.json'))['duration']:.1f}\")")
+without_completed=$(python3 -c "import json; print(json.load(open('$FT_DIR/ft_without_lmcache.json'))['completed'])")
+without_duration=$(python3 -c "import json; print(f\"{json.load(open('$FT_DIR/ft_without_lmcache.json'))['duration']:.1f}\")")
+
+echo "  Warmup (with LMCache):  $warmup_completed/$NUM_PROMPTS in ${warmup_duration}s"
+echo "  Mid-flight kill:        $midflight_completed/$NUM_PROMPTS in ${midflight_duration}s (killed at +${KILL_DELAY}s)"
+echo "  Without LMCache:        $without_completed/$NUM_PROMPTS in ${without_duration}s"
+echo ""
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-gds-smoke.sh b/.buildkite/k3_tests/multiprocess/scripts/run-gds-smoke.sh
new file mode 100755
index 0000000..c33e5c6
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-gds-smoke.sh
@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# GDS L1 smoke test. Sends a few completions (cold) to store KV to the slab,
+# resets vLLM's prefix cache, then re-sends them (warm) to read the KV back from
+# LMCache/GDS. Passes if every request returns HTTP 200, a real LMCache retrieve
+# happened, and the warm (GDS-retrieved) outputs match the cold (recomputed)
+# ones -- i.e. the GDS store/retrieve path works and is correct.
+#
+# Expects the GDS-enabled LMCache server + vLLM to already be running, with
+# VLLM_SERVER_DEV_MODE=1 (for /reset_prefix_cache).
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+VLLM_PORT="${VLLM_PORT:-8000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+LMCACHE_LOG="/tmp/build_${BUILD_ID}_lmcache.log"
+N_PROMPTS="${GDS_SMOKE_PROMPTS:-4}"
+OUT_DIR="$(mktemp -d)"
+trap 'rm -rf "$OUT_DIR"' EXIT
+
+# A long-ish prompt so each request stores at least one LMCache chunk.
+build_prompt() {  # $1 = unique id
+    local filler="The key-value cache stores attention keys and values across transformer layers. "
+    local body="" i
+    for i in $(seq 1 80); do body="${body}${filler}"; done
+    printf 'Document %s. %s' "$1" "$body"
+}
+
+# Send N_PROMPTS completions; capture each generated text to
+# $OUT_DIR/<label>_<i>.txt and require every request to return HTTP 200.
+send_batch() {  # $1 = phase label (cold|warm)
+    local label="$1" ok=0 i prompt payload resp http body
+    for i in $(seq 1 "$N_PROMPTS"); do
+        prompt="$(build_prompt "$i")"
+        payload=$(python3 -c 'import json,sys; print(json.dumps({"model":sys.argv[1],"prompt":sys.argv[2],"max_tokens":16,"temperature":0}))' "$MODEL" "$prompt")
+        resp=$(curl -s -w $'\n%{http_code}' \
+            "http://127.0.0.1:${VLLM_PORT}/v1/completions" \
+            -H "Content-Type: application/json" -d "$payload")
+        http="${resp##*$'\n'}"
+        body="${resp%$'\n'*}"
+        printf '%s' "$body" \
+            | python3 -c 'import json,sys; print(json.load(sys.stdin)["choices"][0]["text"])' \
+            > "${OUT_DIR}/${label}_${i}.txt" 2>/dev/null \
+            || echo "<no-output>" > "${OUT_DIR}/${label}_${i}.txt"
+        echo "  [$label] req $i -> HTTP $http"
+        [ "$http" = "200" ] && ok=$((ok + 1))
+    done
+    [ "$ok" -eq "$N_PROMPTS" ] || { echo "[$label] only $ok/$N_PROMPTS returned HTTP 200"; return 1; }
+}
+
+# Count completed LMCache retrieves recorded in the server log (0 if no log yet).
+count_retrieves() {
+    [ -f "$LMCACHE_LOG" ] || { echo 0; return; }
+    grep -c "Retrieved" "$LMCACHE_LOG" 2>/dev/null || true
+}
+
+echo "============================================"
+echo "=== GDS smoke: phase 1 (cold -> store KV to the GDS slab) ==="
+echo "============================================"
+send_batch cold
+echo "Waiting for async stores to drain to the LMCache server..."
+sleep 3
+retrieves_before=$(count_retrieves)
+
+echo "============================================"
+echo "=== Reset vLLM prefix cache (force warm requests through LMCache/GDS) ==="
+echo "============================================"
+reset_code=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+    "http://127.0.0.1:${VLLM_PORT}/reset_prefix_cache")
+if [ "$reset_code" != "200" ]; then
+    echo "reset_prefix_cache failed (HTTP $reset_code); is VLLM_SERVER_DEV_MODE=1?"
+    exit 1
+fi
+sleep 2
+
+echo "============================================"
+echo "=== GDS smoke: phase 2 (warm -> retrieve KV from the GDS slab) ==="
+echo "============================================"
+send_batch warm
+retrieves_after=$(count_retrieves)
+
+# 1. A real GDS retrieve must have happened (else warm recomputed / hit the APC).
+echo ""
+echo "LMCache retrieves logged: before=${retrieves_before} after=${retrieves_after}"
+if [ "$retrieves_after" -le "$retrieves_before" ]; then
+    echo "GDS smoke FAILED: no LMCache retrieve recorded -- the GDS read path was"
+    echo "not exercised (warm requests recomputed or hit vLLM's prefix cache)."
+    exit 1
+fi
+
+# 2. The KV retrieved from the GDS slab must produce the same output as the
+#    cold recompute (deterministic decoding -> byte-identical completions).
+echo "=== Verifying warm (GDS-retrieved) outputs match cold (recomputed) ==="
+mismatch=0
+for i in $(seq 1 "$N_PROMPTS"); do
+    if diff -q "${OUT_DIR}/cold_${i}.txt" "${OUT_DIR}/warm_${i}.txt" >/dev/null 2>&1; then
+        echo "  prompt $i: match"
+    else
+        echo "  prompt $i: MISMATCH"
+        mismatch=$((mismatch + 1))
+    fi
+done
+if [ "$mismatch" -ne 0 ]; then
+    echo "GDS smoke FAILED: ${mismatch}/${N_PROMPTS} warm outputs differ from cold"
+    echo "-- the KV retrieved from the GDS slab is incorrect."
+    exit 1
+fi
+
+echo "=== GDS smoke test passed: GDS store + retrieve path works and is correct ==="
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-hma-lm-eval.sh b/.buildkite/k3_tests/multiprocess/scripts/run-hma-lm-eval.sh
new file mode 100755
index 0000000..89dcfaa
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-hma-lm-eval.sh
@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# HMA (hybrid memory allocator) correctness test using a real hybrid model.
+#
+# Models (selected by run-single-test.sh):
+#   - google/gemma-4-31B-it: sliding-window + full-attention hybrid whose full
+#     layers have a larger head_dim, so vLLM gives the KV cache groups
+#     different block sizes -- exercising per-group HMA store/retrieve.
+#   - Qwen/Qwen3.5-0.8B: Mamba/GDN + full-attention hybrid, exercising the
+#     registration-time cache re-views (kv_cache_group_edits.py).
+#
+# Flow (single GPU, no baseline server):
+#   1. vLLM run: lm_eval (gsm8k) against vLLM+LMCache, populating LMCache.
+#   2. Reset vLLM's *local* prefix cache (APC) only, leaving LMCache intact, via
+#      the dev-mode endpoint POST /reset_prefix_cache (reset_external defaults to
+#      false, so the LMCache-managed cache is preserved).
+#   3. LMCache retrieve run: re-run lm_eval; vLLM's APC misses, so the prefix KV
+#      is served by LMCache.
+#   4. Assert the two runs' gsm8k scores match -- a broken LMCache would skew the
+#      retrieved KV and make them diverge.
+#   5. Assert LMCache actually served retrieves in the retrieve run (non-vacuous).
+#
+# The reset endpoint requires VLLM_SERVER_DEV_MODE=1 (set by launch-processes.sh).
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+MODEL="${MODEL:-google/gemma-4-31B-it}"
+NUM_CONCURRENT="${NUM_CONCURRENT:-50}"
+# 31B has a large per-token KV footprint; cap the sample count so the working
+# set fits the CPU pool (a too-large set thrashes and the retrieve run misses).
+LIMIT="${LIMIT:-100}"
+# Max abs difference allowed between the two runs' gsm8k scores; 0 requires an
+# exact match. For non-bit-exact backends, raise LIMIT to shrink run-to-run
+# drift (~1/sqrt(LIMIT)) rather than loosening this.
+SCORE_TOLERANCE="${SCORE_TOLERANCE:-0}"
+# Seconds to let async LMCache stores drain before the retrieve run.
+STORE_DRAIN_SECONDS="${STORE_DRAIN_SECONDS:-20}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+# LMCache MP server log, scanned to confirm the retrieve run hit LMCache.
+LMCACHE_LOG="${LMCACHE_LOG:-/tmp/build_${BUILD_ID}_lmcache.log}"
+
+HMA_DIR="$RESULTS_DIR/hma_lm_eval"
+VLLM_RUN_DIR="$HMA_DIR/vllm_run"
+RETRIEVE_RUN_DIR="$HMA_DIR/retrieve_run"
+
+echo "=== HMA lm_eval correctness test ==="
+echo "Model: $MODEL"
+echo "vLLM (LMCache) port: $VLLM_PORT"
+echo "Concurrent requests: $NUM_CONCURRENT"
+echo "Limit: $LIMIT"
+echo "Score tolerance: $SCORE_TOLERANCE"
+echo "Results dir: $HMA_DIR"
+echo ""
+
+mkdir -p "$VLLM_RUN_DIR" "$RETRIEVE_RUN_DIR"
+
+# Run one lm_eval gsm8k pass against a vLLM OpenAI-compatible server.
+#
+# Globals (read):
+#   MODEL          - HuggingFace model id, echoed to lm_eval's model_args.
+#   NUM_CONCURRENT - number of in-flight requests lm_eval issues.
+#   LIMIT          - number of gsm8k samples to evaluate.
+# Arguments:
+#   $1 port       - TCP port of the vLLM /v1/completions endpoint to evaluate.
+#   $2 output_dir - directory lm_eval writes results_*.json / samples_*.jsonl to.
+#   $3 run_name   - human-readable label used only in progress log lines.
+# Outputs:
+#   Writes lm_eval result and per-sample files under output_dir; prints progress
+#   to stdout.
+# Returns:
+#   lm_eval's exit status (non-zero if the evaluation run fails). Propagated to
+#   the caller via ``set -e``.
+run_lm_eval() {
+    local port="$1"
+    local output_dir="$2"
+    local run_name="$3"
+
+    echo "=== Running lm_eval ($run_name) on port $port ==="
+    lm_eval --model local-completions --tasks gsm8k \
+        --model_args "model=${MODEL},base_url=http://127.0.0.1:${port}/v1/completions,num_concurrent=${NUM_CONCURRENT},max_retries=3,tokenized_requests=False" \
+        --limit "$LIMIT" \
+        --seed 0 \
+        -s --output_path "$output_dir" \
+        --gen_kwargs '{"temperature": 0.0}'
+    echo "$run_name completed"
+    echo ""
+}
+
+# Reset a vLLM server's local prefix cache (APC) while preserving LMCache.
+#
+# POSTs to the dev-mode /reset_prefix_cache endpoint without reset_external
+# (which defaults to false), so only vLLM's GPU-side automatic prefix cache is
+# cleared and the LMCache-managed cache is left intact.
+# Arguments:
+#   $1 port - TCP port of the vLLM server whose local APC should be reset.
+# Outputs:
+#   Progress / failure detail to stdout.
+# Returns:
+#   0 if the server acknowledged with HTTP 200; 1 otherwise (e.g. the endpoint
+#   is absent because VLLM_SERVER_DEV_MODE was not set when launching vLLM).
+reset_vllm_prefix_cache() {
+    local port="$1"
+    echo "=== Resetting vLLM local prefix cache on port $port (LMCache preserved) ==="
+    # reset_external defaults to false -> only vLLM's APC is cleared.
+    local code
+    code=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
+        "http://127.0.0.1:${port}/reset_prefix_cache")
+    if [ "$code" != "200" ]; then
+        echo "Failed to reset prefix cache (HTTP $code). Is VLLM_SERVER_DEV_MODE=1?"
+        return 1
+    fi
+    echo "vLLM prefix cache reset."
+    echo ""
+}
+
+# Count completed LMCache retrieves recorded in the server log so far.
+#
+# Used to prove run 2 was actually served by LMCache (the delta around run 2
+# must be > 0), so the correctness comparison cannot pass vacuously by silently
+# recomputing.
+# Globals (read):
+#   LMCACHE_LOG - path to the LMCache MP server log file.
+# Arguments:
+#   none.
+# Outputs:
+#   The integer count of "Retrieved" log lines to stdout (0 if the log file does
+#   not exist yet).
+count_retrieves() {
+    # NB: ``grep -c`` prints 0 *and* exits 1 on no match, so guard the file
+    # existence and use ``|| true`` (not ``|| echo 0``) to avoid emitting "0\n0".
+    [ -f "$LMCACHE_LOG" ] || { echo 0; return; }
+    grep -c "Retrieved" "$LMCACHE_LOG" 2>/dev/null || true
+}
+
+# ── 1. vLLM run: compute from scratch, populating LMCache ───
+run_lm_eval "$VLLM_PORT" "$VLLM_RUN_DIR" "vLLM run"
+
+# Let async stores drain to the LMCache server before invalidating the APC.
+echo "Waiting ${STORE_DRAIN_SECONDS}s for LMCache stores to drain..."
+sleep "$STORE_DRAIN_SECONDS"
+
+retrieves_before=$(count_retrieves)
+
+# ── 2. Invalidate vLLM's local prefix cache (keep LMCache) ──
+reset_vllm_prefix_cache "$VLLM_PORT"
+
+# ── 3. Retrieve run: vLLM APC misses -> LMCache serves the KV ─
+run_lm_eval "$VLLM_PORT" "$RETRIEVE_RUN_DIR" "LMCache retrieve run"
+
+retrieves_after=$(count_retrieves)
+
+# ── 4. Compare scores and verify LMCache was actually used ──
+echo "============================================"
+echo "=== Verifying HMA store/retrieve correctness ==="
+echo "============================================"
+echo "LMCache retrieves logged: before=${retrieves_before}, after=${retrieves_after}"
+
+python3 - "$VLLM_RUN_DIR" "$RETRIEVE_RUN_DIR" \
+    "$SCORE_TOLERANCE" "$retrieves_before" "$retrieves_after" <<'PYEOF'
+import glob
+import json
+import os
+import sys
+
+vllm_run_dir, retrieve_run_dir, tol_s, before_s, after_s = sys.argv[1:6]
+tol = float(tol_s)
+retrieves_before = int(before_s)
+retrieves_after = int(after_s)
+
+
+def gsm8k_score_and_stderr(results_dir: str) -> tuple[float, float]:
+    """Return the gsm8k (exact_match, stderr) from an lm_eval results directory.
+
+    Prefers the strict-match variant; falls back to any non-stderr
+    ``exact_match`` metric key (paired with its ``exact_match_stderr`` twin).
+
+    Args:
+        results_dir: Directory passed to ``lm_eval --output_path``. Searched
+            recursively for the newest ``results_*.json`` (lm_eval nests it
+            under a per-model subdirectory and stamps the filename with a
+            timestamp).
+
+    Returns:
+        ``(score, stderr)``: the gsm8k ``exact_match`` accuracy in
+        ``[0.0, 1.0]`` and its reported sampling stderr (0.0 if absent).
+
+    Raises:
+        SystemExit: If no ``results_*.json`` exists under ``results_dir`` or the
+            newest one contains no ``exact_match`` metric for the gsm8k task.
+    """
+    files = glob.glob(os.path.join(results_dir, "**", "results_*.json"), recursive=True)
+    if not files:
+        raise SystemExit(f"No results_*.json under {results_dir}")
+    latest = max(files, key=os.path.getmtime)
+    with open(latest) as f:
+        data = json.load(f)
+    metrics = data["results"]["gsm8k"]
+    preferred = "exact_match,strict-match"
+    if preferred in metrics:
+        stderr = float(metrics.get("exact_match_stderr,strict-match", 0.0))
+        return float(metrics[preferred]), stderr
+    for key, value in metrics.items():
+        if key.startswith("exact_match,") and "stderr" not in key:
+            variant = key.split(",", 1)[1]
+            stderr = float(metrics.get(f"exact_match_stderr,{variant}", 0.0))
+            return float(value), stderr
+    raise SystemExit(f"No exact_match metric in {latest}: {sorted(metrics)}")
+
+
+s_vllm, e_vllm = gsm8k_score_and_stderr(vllm_run_dir)
+s_retrieve, e_retrieve = gsm8k_score_and_stderr(retrieve_run_dir)
+
+print(f"  vLLM run             gsm8k exact_match = {s_vllm:.4f} +/- {e_vllm:.4f}")
+print(f"  LMCache retrieve run gsm8k exact_match = {s_retrieve:.4f} +/- {e_retrieve:.4f}")
+print(f"  tolerance = {tol}")
+
+failures = []
+# The two runs must match -- a broken LMCache would skew the retrieved KV.
+if abs(s_vllm - s_retrieve) > tol:
+    failures.append(
+        f"score drift between runs: |{s_vllm:.4f} - {s_retrieve:.4f}| = "
+        f"{abs(s_vllm - s_retrieve):.4f} > {tol}"
+    )
+# Non-vacuous: the retrieve run must have been served by LMCache, not recompute.
+if retrieves_after <= retrieves_before:
+    failures.append(
+        "LMCache served no retrieves during the retrieve run "
+        f"(before={retrieves_before}, after={retrieves_after})"
+    )
+
+if failures:
+    print("\nFAILED:")
+    for f in failures:
+        print(f"  - {f}")
+    sys.exit(1)
+
+print(
+    f"\nPASS: vLLM and LMCache-retrieve gsm8k scores match (tol={tol}); "
+    f"LMCache served {retrieves_after - retrieves_before} retrieves."
+)
+PYEOF
+
+echo ""
+echo "============================================"
+echo "=== HMA lm_eval correctness test passed ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-http-api.sh b/.buildkite/k3_tests/multiprocess/scripts/run-http-api.sh
new file mode 100755
index 0000000..2f47c1c
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-http-api.sh
@@ -0,0 +1,446 @@
+#!/usr/bin/env bash
+# End-to-end test for LMCache HTTP API endpoints and CLI commands.
+#
+# Part 1 — HTTP API endpoints:
+#   Systematically exercises every HTTP endpoint on the LMCache
+#   multiprocess HTTP server (port 8080) with a live engine + vLLM.
+#
+# Part 2 — CLI commands:
+#   Tests `lmcache describe` and `lmcache kvcache clear`
+#   against the running server.
+#
+# Requires: LMCache MP server + vLLM launched by launch-processes.sh.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration (inherited from run-single-test.sh)
+VLLM_PORT="${VLLM_PORT:-8000}"
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-8080}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+HTTP_DIR="$RESULTS_DIR/http_api"
+mkdir -p "$HTTP_DIR"
+
+BASE_URL="http://localhost:${LMCACHE_HTTP_PORT}"
+
+echo "=== HTTP API & CLI Test ==="
+echo "Model: $MODEL"
+echo "vLLM port: $VLLM_PORT"
+echo "LMCache HTTP: $BASE_URL"
+echo "Results dir: $HTTP_DIR"
+echo ""
+
+# ── Counters ────────────────────────────────────────────────
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# ── Helpers ─────────────────────────────────────────────────
+
+pass() {
+    local label="$1"
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_PASSED=$((TESTS_PASSED + 1))
+    echo "PASS: $label"
+}
+
+fail() {
+    local label="$1"
+    shift
+    TESTS_RUN=$((TESTS_RUN + 1))
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+    echo "FAIL: $label — $*"
+}
+
+check_http() {
+    local label="$1"
+    local method="$2"
+    local path="$3"
+    local output="$4"
+    local expected_code="${5:-200}"
+    local body="${6:-}"
+
+    local curl_args=(-s -o "$output" -w "%{http_code}")
+    case "$method" in
+        GET)  curl_args+=("${BASE_URL}${path}") ;;
+        POST)
+            curl_args+=(-X POST -H "Content-Type: application/json")
+            [ -n "$body" ] && curl_args+=(-d "$body")
+            curl_args+=("${BASE_URL}${path}")
+            ;;
+        PUT)
+            curl_args+=(-X PUT -H "Content-Type: application/json")
+            [ -n "$body" ] && curl_args+=(-d "$body")
+            curl_args+=("${BASE_URL}${path}")
+            ;;
+        DELETE)
+            curl_args+=(-X DELETE "${BASE_URL}${path}")
+            ;;
+    esac
+
+    local http_code
+    http_code=$(curl "${curl_args[@]}")
+
+    if [ "$http_code" -ne "$expected_code" ]; then
+        fail "$label" "expected HTTP $expected_code, got $http_code"
+        echo "  Response body:"
+        cat "$output" 2>/dev/null || true
+        echo ""
+        return 1
+    fi
+    pass "$label (HTTP $http_code)"
+    return 0
+}
+
+assert_json_key() {
+    local label="$1"
+    local file="$2"
+    local key="$3"
+    local expected_value="${4:-}"
+
+    python3 -c "
+import json, sys
+with open('$file') as f:
+    data = json.load(f)
+keys = '$key'.split('.')
+cur = data
+for k in keys:
+    if not isinstance(cur, dict) or k not in cur:
+        print('FAIL: $label — key \"$key\" not found')
+        sys.exit(1)
+    cur = cur[k]
+if '$expected_value' and str(cur) != '$expected_value':
+    print('FAIL: $label — expected \"$expected_value\", got ' + repr(cur))
+    sys.exit(1)
+" || {
+        fail "$label" "JSON key assertion failed for key '$key'"
+        return 1
+    }
+    pass "$label (key '$key')"
+}
+
+assert_contains() {
+    local label="$1"
+    local file="$2"
+    local pattern="$3"
+
+    if grep -q "$pattern" "$file" 2>/dev/null; then
+        pass "$label (contains '$pattern')"
+    else
+        fail "$label" "output does not contain '$pattern'"
+        return 1
+    fi
+}
+
+# ================================================================
+#  PART 1: HTTP API ENDPOINT TESTS
+# ================================================================
+
+echo ""
+echo "========================================================"
+echo "=== Part 1: HTTP API Endpoint Tests ==="
+echo "========================================================"
+
+# ── Step 0: Warm up cache via vLLM ─────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 0: Warm up cache ==="
+echo "============================================"
+
+warmup_code=$(curl -s -o "$HTTP_DIR/warmup.json" -w "%{http_code}" \
+    -X POST "http://localhost:${VLLM_PORT}/v1/chat/completions" \
+    -H "Content-Type: application/json" \
+    -d "{
+        \"model\": \"${MODEL}\",
+        \"messages\": [{\"role\": \"user\", \"content\": \"Explain the concept of caching in computer science.\"}],
+        \"max_tokens\": 1
+    }")
+
+if [ "$warmup_code" -ne 200 ]; then
+    echo "FATAL: warmup request failed with HTTP $warmup_code"
+    cat "$HTTP_DIR/warmup.json" 2>/dev/null || true
+    exit 1
+fi
+echo "Warmup request successful (HTTP 200)"
+sleep 2
+
+# ── Step 1: Root + Healthcheck ─────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 1: Root + Healthcheck ==="
+echo "============================================"
+
+check_http "GET /" GET "/" "$HTTP_DIR/root.json" 200
+assert_json_key "GET / — status" "$HTTP_DIR/root.json" "status" "ok"
+assert_json_key "GET / — service" "$HTTP_DIR/root.json" "service" "LMCache HTTP API"
+
+check_http "GET /healthcheck" GET "/healthcheck" "$HTTP_DIR/healthcheck.json" 200
+assert_json_key "GET /healthcheck — status" "$HTTP_DIR/healthcheck.json" "status" "healthy"
+
+# ── Step 2: Configuration ──────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 2: Configuration (/config) ==="
+echo "============================================"
+
+check_http "GET /config" GET "/config" "$HTTP_DIR/config.json" 200
+
+python3 -c "
+import json, sys
+with open('$HTTP_DIR/config.json') as f:
+    data = json.load(f)
+required = ['mp', 'storage_manager', 'observability', 'http']
+missing = [k for k in required if k not in data]
+if missing:
+    print(f'FAIL: /config missing keys: {missing}')
+    sys.exit(1)
+print('All config sections present: ' + ', '.join(required))
+" && pass "GET /config — required keys present" \
+  || fail "GET /config — required keys present" "missing config sections"
+
+# ── Step 3: Status ─────────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 3: Status (/status) ==="
+echo "============================================"
+
+check_http "GET /status" GET "/status" "$HTTP_DIR/status.json" 200
+
+python3 -c "
+import json, sys
+with open('$HTTP_DIR/status.json') as f:
+    data = json.load(f)
+if not isinstance(data, dict):
+    print('FAIL: /status did not return a JSON dict')
+    sys.exit(1)
+print('Status response is a valid dict with ' + str(len(data)) + ' keys')
+" && pass "GET /status — valid JSON dict" \
+  || fail "GET /status — valid JSON dict" "response is not a dict"
+
+# ── Step 4: Metrics ────────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 4: Metrics (/metrics) ==="
+echo "============================================"
+
+check_http "GET /metrics" GET "/metrics" "$HTTP_DIR/metrics.txt" 200
+assert_contains "GET /metrics — has lmcache metrics" "$HTTP_DIR/metrics.txt" "lmcache_"
+assert_contains "GET /metrics — Prometheus format" "$HTTP_DIR/metrics.txt" "# "
+
+# ── Step 5: Environment ────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 5: Environment (/env) ==="
+echo "============================================"
+
+check_http "GET /env" GET "/env" "$HTTP_DIR/env.json" 200
+
+python3 -c "
+import json, sys
+with open('$HTTP_DIR/env.json') as f:
+    data = json.load(f)
+if not isinstance(data, dict):
+    print('FAIL: /env did not return a JSON dict')
+    sys.exit(1)
+if 'PATH' not in data:
+    print('FAIL: /env missing PATH key')
+    sys.exit(1)
+print('/env returned ' + str(len(data)) + ' environment variables')
+" && pass "GET /env — valid JSON with PATH" \
+  || fail "GET /env — valid JSON with PATH" "validation failed"
+
+# ── Step 6: Log Level ──────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 6: Log Level (/loglevel) ==="
+echo "============================================"
+
+check_http "GET /loglevel (list)" GET "/loglevel" "$HTTP_DIR/loglevel_list.txt" 200
+assert_contains "GET /loglevel — header" "$HTTP_DIR/loglevel_list.txt" "Loggers and Levels"
+
+check_http "GET /loglevel (set DEBUG)" GET "/loglevel?logger_name=lmcache&level=DEBUG" "$HTTP_DIR/loglevel_set.txt" 200
+assert_contains "GET /loglevel (set DEBUG) — confirmation" "$HTTP_DIR/loglevel_set.txt" "Set lmcache level to DEBUG"
+
+check_http "GET /loglevel (invalid level)" GET "/loglevel?logger_name=lmcache&level=INVALID_LEVEL" "$HTTP_DIR/loglevel_bad.txt" 400
+
+# ── Step 7: Threads ────────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 7: Threads ==="
+echo "============================================"
+
+check_http "GET /threads" GET "/threads" "$HTTP_DIR/threads.txt" 200
+assert_contains "GET /threads — header" "$HTTP_DIR/threads.txt" "Thread Summary"
+
+check_http "GET /periodic-threads" GET "/periodic-threads" "$HTTP_DIR/periodic_threads.json" 200
+
+python3 -c "
+import json, sys
+with open('$HTTP_DIR/periodic_threads.json') as f:
+    data = json.load(f)
+if 'summary' not in data or 'threads' not in data:
+    print('FAIL: /periodic-threads missing summary or threads key')
+    sys.exit(1)
+if 'total_count' not in data['summary']:
+    print('FAIL: /periodic-threads summary missing total_count')
+    sys.exit(1)
+print('/periodic-threads: ' + str(data['summary']['total_count']) + ' threads registered')
+" && pass "GET /periodic-threads — structure" \
+  || fail "GET /periodic-threads — structure" "validation failed"
+
+check_http "GET /periodic-threads-health" GET "/periodic-threads-health" "$HTTP_DIR/periodic_health.json" 200
+assert_json_key "GET /periodic-threads-health — healthy key" "$HTTP_DIR/periodic_health.json" "healthy"
+
+# ── Step 8: Clear Cache ────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 8: Clear Cache (/cache/clear) ==="
+echo "============================================"
+
+check_http "POST /cache/clear" POST "/cache/clear" "$HTTP_DIR/clear_cache.json" 200
+assert_json_key "POST /cache/clear — status" "$HTTP_DIR/clear_cache.json" "status" "ok"
+
+# ── Step 9: Quota CRUD ─────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 9: Quota CRUD ==="
+echo "============================================"
+
+QUOTA_SALT="test_salt_${BUILD_ID}"
+
+# 9a: Create quota
+check_http "PUT /quota/${QUOTA_SALT}" PUT "/quota/${QUOTA_SALT}" "$HTTP_DIR/quota_put.json" 200 '{"limit_gb": 1.0}'
+assert_json_key "PUT quota — status" "$HTTP_DIR/quota_put.json" "status" "ok"
+
+# 9b: Read quota
+check_http "GET /quota/${QUOTA_SALT}" GET "/quota/${QUOTA_SALT}" "$HTTP_DIR/quota_get.json" 200
+
+python3 -c "
+import json, sys
+with open('$HTTP_DIR/quota_get.json') as f:
+    data = json.load(f)
+if not data.get('exists'):
+    print('FAIL: quota should exist after PUT')
+    sys.exit(1)
+limit = data.get('limit_gb', 0)
+if abs(limit - 1.0) > 0.01:
+    print(f'FAIL: expected limit_gb ~1.0, got {limit}')
+    sys.exit(1)
+print(f'Quota exists with limit_gb={limit}')
+" && pass "GET /quota — exists with correct limit" \
+  || fail "GET /quota — exists with correct limit" "validation failed"
+
+# 9c: List quotas
+check_http "GET /quota (list)" GET "/quota" "$HTTP_DIR/quota_list.json" 200
+assert_json_key "GET /quota (list) — users key" "$HTTP_DIR/quota_list.json" "users"
+
+# 9d: Delete quota
+check_http "DELETE /quota/${QUOTA_SALT}" DELETE "/quota/${QUOTA_SALT}" "$HTTP_DIR/quota_delete.json" 200
+assert_json_key "DELETE quota — status" "$HTTP_DIR/quota_delete.json" "status" "removed"
+
+# 9e: Verify deletion
+check_http "GET /quota/${QUOTA_SALT} (after delete)" GET "/quota/${QUOTA_SALT}" "$HTTP_DIR/quota_gone.json" 200
+
+python3 -c "
+import json, sys
+with open('$HTTP_DIR/quota_gone.json') as f:
+    data = json.load(f)
+if data.get('exists'):
+    print('FAIL: quota should not exist after DELETE')
+    sys.exit(1)
+print('Quota correctly gone after DELETE')
+" && pass "GET /quota after DELETE — not exists" \
+  || fail "GET /quota after DELETE — not exists" "quota still exists"
+
+# 9f: Delete non-existent
+check_http "DELETE /quota/nonexistent_salt" DELETE "/quota/nonexistent_salt" "$HTTP_DIR/quota_notfound.json" 200
+assert_json_key "DELETE nonexistent — status" "$HTTP_DIR/quota_notfound.json" "status" "not_found"
+
+# 9g: Error — negative limit
+check_http "PUT /quota (negative limit)" PUT "/quota/err_salt" "$HTTP_DIR/quota_neg.json" 400 '{"limit_gb": -1.0}'
+
+# 9h: Error — missing key
+check_http "PUT /quota (missing limit_gb)" PUT "/quota/err_salt" "$HTTP_DIR/quota_badkey.json" 400 '{"bad_key": 1}'
+
+# ── Step 10: Version ───────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 10: Version ==="
+echo "============================================"
+
+check_http "GET /version" GET "/version" "$HTTP_DIR/version.txt" 200
+check_http "GET /lmc_version" GET "/lmc_version" "$HTTP_DIR/lmc_version.txt" 200
+check_http "GET /commit_id" GET "/commit_id" "$HTTP_DIR/commit_id.txt" 200
+
+# ================================================================
+#  PART 2: CLI COMMAND TESTS
+# ================================================================
+
+echo ""
+echo "========================================================"
+echo "=== Part 2: CLI Command Tests ==="
+echo "========================================================"
+
+# ── Step 11: lmcache describe kvcache ──────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 11: lmcache describe kvcache ==="
+echo "============================================"
+
+if lmcache describe kvcache --url "${BASE_URL}" > "$HTTP_DIR/describe.txt" 2>&1; then
+    pass "lmcache describe kvcache — exit code 0"
+else
+    fail "lmcache describe kvcache — exit code 0" "command returned non-zero"
+    echo "  Output:"
+    cat "$HTTP_DIR/describe.txt" 2>/dev/null || true
+fi
+
+assert_contains "describe — Health section" "$HTTP_DIR/describe.txt" "Health"
+assert_contains "describe — L1 capacity section" "$HTTP_DIR/describe.txt" "L1 capacity"
+
+# ── Step 12: lmcache kvcache clear ─────────────────────────
+echo ""
+echo "============================================"
+echo "=== Step 12: lmcache kvcache clear ==="
+echo "============================================"
+
+if lmcache kvcache clear --url "${BASE_URL}" > "$HTTP_DIR/kvcache_clear.txt" 2>&1; then
+    pass "lmcache kvcache clear — exit code 0"
+else
+    fail "lmcache kvcache clear — exit code 0" "command returned non-zero"
+    echo "  Output:"
+    cat "$HTTP_DIR/kvcache_clear.txt" 2>/dev/null || true
+fi
+
+assert_contains "kvcache clear — OK" "$HTTP_DIR/kvcache_clear.txt" "OK"
+
+# ================================================================
+#  SUMMARY
+# ================================================================
+
+echo ""
+echo "========================================================"
+echo "=== Summary ==="
+echo "========================================================"
+echo "Tests run:    $TESTS_RUN"
+echo "Tests passed: $TESTS_PASSED"
+echo "Tests failed: $TESTS_FAILED"
+echo ""
+
+if [ "$TESTS_FAILED" -gt 0 ]; then
+    echo "============================================"
+    echo "=== HTTP API & CLI Test FAILED ==="
+    echo "============================================"
+    exit 1
+fi
+
+echo "============================================"
+echo "=== HTTP API & CLI Test PASSED ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-lm-eval.sh b/.buildkite/k3_tests/multiprocess/scripts/run-lm-eval.sh
new file mode 100755
index 0000000..cfe23d5
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-lm-eval.sh
@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Run lm_eval workload test against vLLM server.
+# Sends the same requests twice to test LMCache caching behavior.
+# Adapted from the old Docker-based run-lm-eval.sh -- no venv setup needed
+# (setup-env.sh + extras already installed by run.sh).
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+NUM_CONCURRENT="${NUM_CONCURRENT:-50}"
+LIMIT="${LIMIT:-300}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+# Output directories
+LM_EVAL_DIR="$RESULTS_DIR/lm_eval"
+FIRST_RUN_DIR="$LM_EVAL_DIR/first_run"
+SECOND_RUN_DIR="$LM_EVAL_DIR/second_run"
+
+echo "=== LM-Eval Workload Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port: $VLLM_PORT"
+echo "Concurrent requests: $NUM_CONCURRENT"
+echo "Limit: $LIMIT"
+echo "Results dir: $LM_EVAL_DIR"
+echo ""
+
+mkdir -p "$FIRST_RUN_DIR" "$SECOND_RUN_DIR"
+
+run_lm_eval() {
+    local run_name="$1"
+    local output_dir="$2"
+
+    echo "=== Running lm_eval ($run_name) ==="
+    lm_eval --model local-completions --tasks gsm8k \
+        --model_args "model=${MODEL},base_url=http://127.0.0.1:${VLLM_PORT}/v1/completions,num_concurrent=${NUM_CONCURRENT},max_retries=3,tokenized_requests=False" \
+        --limit "$LIMIT" \
+        --seed 0 \
+        -s --output_path "$output_dir" \
+        --gen_kwargs '{"temperature": 0.0}'
+
+    echo "$run_name completed"
+    echo ""
+}
+
+verify_samples_match() {
+    local first_dir="$1"
+    local second_dir="$2"
+
+    echo "=== Verifying samples files match ==="
+
+    first_samples=$(find "$first_dir" -name "samples_gsm8k_*.jsonl" -type f 2>/dev/null | head -1)
+    second_samples=$(find "$second_dir" -name "samples_gsm8k_*.jsonl" -type f 2>/dev/null | head -1)
+
+    if [ -z "$first_samples" ]; then
+        echo "Could not find samples_gsm8k_*.jsonl in first run directory: $first_dir"
+        find "$first_dir" -type f -name "*.jsonl" || true
+        return 1
+    fi
+
+    if [ -z "$second_samples" ]; then
+        echo "Could not find samples_gsm8k_*.jsonl in second run directory: $second_dir"
+        find "$second_dir" -type f -name "*.jsonl" || true
+        return 1
+    fi
+
+    echo "First run samples: $first_samples"
+    echo "Second run samples: $second_samples"
+
+    first_sorted=$(mktemp)
+    second_sorted=$(mktemp)
+
+    sort "$first_samples" > "$first_sorted"
+    sort "$second_samples" > "$second_sorted"
+
+    if diff -q "$first_sorted" "$second_sorted" > /dev/null 2>&1; then
+        echo "Samples files are identical!"
+        rm -f "$first_sorted" "$second_sorted"
+        return 0
+    else
+        echo "Samples files differ!"
+        echo ""
+        echo "=== Diff (first 50 lines) ==="
+        diff "$first_sorted" "$second_sorted" | head -50 || true
+        rm -f "$first_sorted" "$second_sorted"
+        return 1
+    fi
+}
+
+# First run -- populates cache
+echo "============================================"
+echo "=== First lm_eval run (cache population) ==="
+echo "============================================"
+run_lm_eval "first_run" "$FIRST_RUN_DIR"
+
+# Second run -- should use cached results
+echo "============================================"
+echo "=== Second lm_eval run (cache hit) ==="
+echo "============================================"
+run_lm_eval "second_run" "$SECOND_RUN_DIR"
+
+# Verify consistency
+echo "============================================"
+echo "=== Verifying output consistency ==="
+echo "============================================"
+if ! verify_samples_match "$FIRST_RUN_DIR" "$SECOND_RUN_DIR"; then
+    echo "Verification failed: samples files do not match"
+    exit 1
+fi
+
+echo "============================================"
+echo "=== LM-Eval workload test completed ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-long-doc-qa-l2.sh b/.buildkite/k3_tests/multiprocess/scripts/run-long-doc-qa-l2.sh
new file mode 100755
index 0000000..2b60560
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-long-doc-qa-l2.sh
@@ -0,0 +1,575 @@
+#!/usr/bin/env bash
+# Run long_doc_qa for L2 skip_l1 mode with mock L2 adapter.
+#
+# This script:
+#   1. Kills the existing LMCache MP server
+#   2. Relaunches it with L2 config (skip_l1 + mock L2 at 2 GB/s)
+#   3. Waits for vLLM to reconnect
+#   4. Runs long_doc_qa against baseline (vLLM only) and L2-enabled vLLM
+#   5. Verifies L2 query is faster than baseline and warmup overhead is bounded
+#
+# Expects the following env vars from run-mp-test.sh:
+#   VLLM_PORT, VLLM_BASELINE_PORT, MODEL, BUILD_ID, RESULTS_DIR, LMCACHE_DIR,
+#   LMCACHE_PORT, CPU_BUFFER_SIZE, MAX_WORKERS, GPU_FOR_VLLM (optional)
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+LMCACHE_DIR="${LMCACHE_DIR:-$REPO_ROOT}"
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+
+DOCUMENT_LENGTH="${DOCUMENT_LENGTH:-10000}"
+NUM_DOCUMENTS="${NUM_DOCUMENTS:-30}"
+OUTPUT_LEN="${OUTPUT_LEN:-200}"
+REPEAT_COUNT="${REPEAT_COUNT:-2}"
+REPEAT_MODE="${REPEAT_MODE:-tile}"
+SHUFFLE_SEED="${SHUFFLE_SEED:-0}"
+MAX_INFLIGHT_REQUESTS="${MAX_INFLIGHT_REQUESTS:-5}"
+
+# Mock L2 config
+L2_MAX_SIZE_GB="${L2_MAX_SIZE_GB:-80}"
+L2_BANDWIDTH_GB="${L2_BANDWIDTH_GB:-4}"
+
+# L2 performance thresholds
+# Recent CI runs show ~1.51-1.67x query speedup, ~1.77-2.02x TTFT speedup,
+# and ~0.87-0.99x warmup overhead. Tighten from the previous pass-anything
+# thresholds (1.0x/1.0x/2.0x) while leaving headroom for variance.
+MIN_L2_SPEEDUP="${MIN_L2_SPEEDUP:-1.3}"
+MIN_L2_TTFT_SPEEDUP="${MIN_L2_TTFT_SPEEDUP:-1.5}"
+MAX_WARMUP_OVERHEAD="${MAX_WARMUP_OVERHEAD:-1.2}"
+
+L2_RESULTS_DIR="$RESULTS_DIR/long_doc_qa_l2"
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+# /metrics is now served by the LMCache FastAPI HTTP server (port 8080
+# by default) — the legacy ``--prometheus-port`` standalone server was
+# disabled for the ``lmcache server`` entrypoint by #3164.  Defined here
+# (not just in Step 4) so the relaunch and the curl scrape agree.
+METRICS_HTTP_PORT="${METRICS_HTTP_PORT:-8080}"
+
+echo "=== Long Doc QA L2 Performance Test ==="
+echo "Model: $MODEL"
+echo "L2 adapter: mock (${L2_MAX_SIZE_GB}GB, ${L2_BANDWIDTH_GB}GB/s)"
+echo "Store policy: skip_l1 | Eviction: noop"
+echo "Thresholds: speedup>=${MIN_L2_SPEEDUP}x, TTFT speedup>=${MIN_L2_TTFT_SPEEDUP}x, overhead<=${MAX_WARMUP_OVERHEAD}x"
+echo "Results: $L2_RESULTS_DIR"
+echo ""
+
+mkdir -p "$L2_RESULTS_DIR"
+
+# ---------------------------------------------------------------------------
+# Step 1: Kill existing LMCache + vLLM, relaunch both with L2 config
+# ---------------------------------------------------------------------------
+
+echo "--- Stopping existing LMCache MP server and vLLM ---"
+# PID file layout: line1=LMCache, line2=vLLM w/ LMCache, line3=vLLM baseline.
+# These processes were launched by an earlier script (launch-processes.sh)
+# and are not children of this shell, so ``wait $pid`` is a no-op here.
+# We instead poll until each PID actually exits, then poll until the
+# Prometheus port is free, otherwise the LMCache relaunch below would
+# fail to bind /metrics and the metrics check would fail spuriously.
+if [ -f "$PID_FILE" ]; then
+    LMCACHE_PID=$(sed -n '1p' "$PID_FILE")
+    VLLM_PID=$(sed -n '2p' "$PID_FILE")
+    for pid in $LMCACHE_PID $VLLM_PID; do
+        if [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then
+            echo "Killing PID $pid"
+            kill "$pid" 2>/dev/null || true
+            for _ in $(seq 1 60); do
+                kill -0 "$pid" 2>/dev/null || break
+                sleep 0.5
+            done
+            # Last resort: SIGKILL if SIGTERM didn't take after 30s.
+            if kill -0 "$pid" 2>/dev/null; then
+                echo "PID $pid still alive after SIGTERM; sending SIGKILL"
+                kill -9 "$pid" 2>/dev/null || true
+            fi
+        fi
+    done
+    # Poll until the Prometheus port is fully released so the new server
+    # below can bind it cleanly.
+    for _ in $(seq 1 30); do
+        if ! (ss -ltn 2>/dev/null || netstat -ltn 2>/dev/null) \
+                | awk '{print $4}' | grep -qE ":${METRICS_HTTP_PORT}$"; then
+            break
+        fi
+        sleep 0.5
+    done
+fi
+
+echo "--- Launching LMCache MP server with L2 config ---"
+L2_ADAPTER_JSON="{\"type\":\"mock\",\"max_size_gb\":${L2_MAX_SIZE_GB},\"mock_bandwidth_gb\":${L2_BANDWIDTH_GB}}"
+
+# Determine GPU to use
+GPU_DEVICE="${GPU_FOR_VLLM:-0}"
+
+CUDA_VISIBLE_DEVICES="${GPU_DEVICE}" \
+lmcache server \
+    --l1-size-gb "$CPU_BUFFER_SIZE" \
+    --eviction-policy noop \
+    --l2-store-policy skip_l1 \
+    --l2-prefetch-policy default \
+    --l2-adapter "$L2_ADAPTER_JSON" \
+    --max-workers "$MAX_WORKERS" \
+    --metrics-sample-rate 1.0 \
+    --http-port "$METRICS_HTTP_PORT" \
+    --port "$LMCACHE_PORT" \
+    > "/tmp/build_${BUILD_ID}_lmcache_l2.log" 2>&1 &
+
+NEW_LMCACHE_PID=$!
+echo "LMCache L2 server started (PID=$NEW_LMCACHE_PID)"
+
+echo "Waiting for LMCache L2 to initialize..."
+sleep 10
+
+echo "--- Launching vLLM with LMCache ---"
+# Compute GPU memory utilization for large GPUs
+GPU_MEMORY_UTIL_ARG=""
+GPU_MEMORY_MB=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits -i "${GPU_DEVICE}" | tr -d ' ')
+GPU_MEMORY_GB=$((GPU_MEMORY_MB / 1024))
+if [ "$GPU_MEMORY_GB" -gt 90 ]; then
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization 0.5"
+fi
+
+# Unset VLLM_PORT in child env so vLLM's torch.distributed picks a free port
+env -u VLLM_PORT \
+    CUDA_VISIBLE_DEVICES="${GPU_DEVICE}" \
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    VLLM_SERVER_DEV_MODE=1 \
+    VLLM_BATCH_INVARIANT=1 \
+    PYTHONHASHSEED=0 \
+vllm serve "$MODEL" \
+    --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $LMCACHE_PORT, \"lmcache.mp.mq_timeout\": 10}}" \
+    --attention-backend FLASH_ATTN \
+    --port "$VLLM_PORT" \
+    --no-async-scheduling \
+    $GPU_MEMORY_UTIL_ARG \
+    > "/tmp/build_${BUILD_ID}_vllm_l2.log" 2>&1 &
+
+NEW_VLLM_PID=$!
+echo "vLLM started (PID=$NEW_VLLM_PID)"
+
+# Update PID file (replace lines 1 and 2, keep baseline on line 3)
+if [ -f "$PID_FILE" ]; then
+    sed -i "1s/.*/$NEW_LMCACHE_PID/" "$PID_FILE"
+    sed -i "2s/.*/$NEW_VLLM_PID/" "$PID_FILE"
+else
+    echo "$NEW_LMCACHE_PID" > "$PID_FILE"
+    echo "$NEW_VLLM_PID" >> "$PID_FILE"
+fi
+
+# Wait for vLLM to be ready (needs time to load model)
+echo "--- Waiting for vLLM to be ready ---"
+if ! wait_for_server "$VLLM_PORT" 300; then
+    echo "vLLM failed to start after restart"
+    echo "LMCache L2 log (last 50 lines):"
+    tail -50 "/tmp/build_${BUILD_ID}_lmcache_l2.log" || true
+    echo "vLLM log (last 50 lines):"
+    tail -50 "/tmp/build_${BUILD_ID}_vllm_l2.log" || true
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+run_long_doc_qa() {
+    local port="$1"
+    local result_file="$2"
+    local description="$3"
+
+    echo "--- Running long_doc_qa ($description) on port $port ---"
+    local output_file="$L2_RESULTS_DIR/${description}_output.txt"
+
+    python3 "$LMCACHE_DIR/benchmarks/long_doc_qa/long_doc_qa.py" \
+        --port "$port" \
+        --model "$MODEL" \
+        --document-length "$DOCUMENT_LENGTH" \
+        --num-documents "$NUM_DOCUMENTS" \
+        --output-len "$OUTPUT_LEN" \
+        --repeat-count "$REPEAT_COUNT" \
+        --repeat-mode "$REPEAT_MODE" \
+        --shuffle-seed "$SHUFFLE_SEED" \
+        --max-inflight-requests "$MAX_INFLIGHT_REQUESTS" \
+        --output "$output_file" \
+        --json-output \
+        2>>"$output_file" | tee "$result_file"
+
+    echo "Completed: $description"
+    echo ""
+}
+
+extract_json_field() {
+    local json_file="$1"
+    local field="$2"
+    tail -n 1 "$json_file" | python3 -c "
+import json, sys
+try:
+    data = json.loads(sys.stdin.read())
+    v = data.get('$field')
+    print(v if v is not None else 'null')
+except Exception:
+    print('null')
+"
+}
+
+# ---------------------------------------------------------------------------
+# Step 2: Run benchmarks
+# ---------------------------------------------------------------------------
+
+# Phase 1: Baseline -- reuse results from step 5 (same port, same params)
+STEP5_BASELINE="$RESULTS_DIR/long_doc_qa/baseline_result.json"
+if [ -f "$STEP5_BASELINE" ]; then
+    echo "============================================"
+    echo "=== Phase 1: Reusing baseline from step 5 ==="
+    echo "============================================"
+    cp "$STEP5_BASELINE" "$L2_RESULTS_DIR/baseline_result.json"
+    echo "Copied baseline results from $STEP5_BASELINE"
+    echo ""
+else
+    echo "============================================"
+    echo "=== Phase 1: Baseline vLLM (no LMCache) ==="
+    echo "============================================"
+    run_long_doc_qa "$VLLM_BASELINE_PORT" "$L2_RESULTS_DIR/baseline_result.json" "baseline"
+fi
+
+# Phase 2+3: L2 warmup + query (repeat_count=2, tile mode)
+#   Round 1 (warmup): prompts -> L1 write buffer -> L2 store -> L1 delete
+#   Round 2 (query):  prompts -> L1 miss -> L2 prefetch -> L1 load -> serve
+echo "============================================"
+echo "=== Phase 2+3: vLLM + LMCache L2 ==="
+echo "============================================"
+run_long_doc_qa "$VLLM_PORT" "$L2_RESULTS_DIR/l2_result.json" "l2"
+
+# ---------------------------------------------------------------------------
+# Step 3: Verify thresholds
+# ---------------------------------------------------------------------------
+
+echo "============================================"
+echo "=== Verifying L2 Performance ==="
+echo "============================================"
+
+baseline_query_ttft=$(extract_json_field "$L2_RESULTS_DIR/baseline_result.json" "query_ttft_per_prompt")
+baseline_query_round_time=$(extract_json_field "$L2_RESULTS_DIR/baseline_result.json" "query_round_time_per_prompt")
+baseline_warmup_round_time=$(extract_json_field "$L2_RESULTS_DIR/baseline_result.json" "warmup_round_time_per_prompt")
+
+l2_query_ttft=$(extract_json_field "$L2_RESULTS_DIR/l2_result.json" "query_ttft_per_prompt")
+l2_query_round_time=$(extract_json_field "$L2_RESULTS_DIR/l2_result.json" "query_round_time_per_prompt")
+l2_warmup_round_time=$(extract_json_field "$L2_RESULTS_DIR/l2_result.json" "warmup_round_time_per_prompt")
+
+python3 << EOF
+import sys
+
+def sf(val):
+    try: return float(val)
+    except: return None
+
+bqt  = sf("$baseline_query_ttft")
+bqrt = sf("$baseline_query_round_time")
+bwrt = sf("$baseline_warmup_round_time")
+lqt  = sf("$l2_query_ttft")
+lqrt = sf("$l2_query_round_time")
+lwrt = sf("$l2_warmup_round_time")
+
+min_spd  = float("$MIN_L2_SPEEDUP")
+min_ttft = float("$MIN_L2_TTFT_SPEEDUP")
+max_oh   = float("$MAX_WARMUP_OVERHEAD")
+
+failed = False
+
+print("=" * 60)
+print("L2 Performance Summary")
+print("=" * 60)
+print(f"{'Metric':<35} {'Baseline':>12} {'L2':>12}")
+print("-" * 60)
+for name, bv, lv in [
+    ("query_ttft_per_prompt (s)", bqt, lqt),
+    ("query_round_time_per_prompt (s)", bqrt, lqrt),
+    ("warmup_round_time_per_prompt (s)", bwrt, lwrt),
+]:
+    bs = f"{bv:.4f}" if bv else "N/A"
+    ls = f"{lv:.4f}" if lv else "N/A"
+    print(f"{name:<35} {bs:>12} {ls:>12}")
+
+print()
+print("=" * 60)
+print("Threshold Verification")
+print("=" * 60)
+
+# 1. L2 query round-time speedup
+if lqrt and bqrt and lqrt > 0:
+    s = bqrt / lqrt
+    ok = s >= min_spd
+    print(f"[{'PASS' if ok else 'FAIL'}] L2 query speedup: {s:.2f}x (need >= {min_spd}x)")
+    if not ok: failed = True
+else:
+    print("[FAIL] Cannot compute L2 query speedup"); failed = True
+
+# 2. L2 TTFT speedup
+if lqt and bqt and lqt > 0:
+    s = bqt / lqt
+    ok = s >= min_ttft
+    print(f"[{'PASS' if ok else 'FAIL'}] L2 TTFT speedup: {s:.2f}x (need >= {min_ttft}x)")
+    if not ok: failed = True
+else:
+    print("[FAIL] Cannot compute L2 TTFT speedup"); failed = True
+
+# 3. Warmup overhead
+if lwrt and bwrt and bwrt > 0:
+    o = lwrt / bwrt
+    ok = o <= max_oh
+    print(f"[{'PASS' if ok else 'FAIL'}] Warmup overhead: {o:.2f}x (need <= {max_oh}x)")
+    if not ok: failed = True
+else:
+    print("[FAIL] Cannot compute warmup overhead"); failed = True
+
+print()
+if failed:
+    print("[FAIL] L2 performance verification FAILED")
+    sys.exit(1)
+else:
+    print("[PASS] All L2 performance thresholds passed")
+EOF
+
+# ---------------------------------------------------------------------------
+# Step 4: Verify L2 data flow via Prometheus metrics
+# ---------------------------------------------------------------------------
+
+echo "============================================"
+echo "=== Verifying L2 Data Flow (Metrics) ==="
+echo "============================================"
+
+L2_METRICS_FILE="$L2_RESULTS_DIR/prometheus_metrics.txt"
+# Retry briefly: when LMCache is relaunched on the same port as the
+# previous instance, the Prometheus socket can take a moment to come
+# back up, and a single-shot curl loses the metrics check silently.
+> "$L2_METRICS_FILE"
+for i in 1 2 3 4 5; do
+    if curl -sf "http://localhost:${METRICS_HTTP_PORT}/metrics" \
+            > "$L2_METRICS_FILE" 2>/dev/null && [ -s "$L2_METRICS_FILE" ]; then
+        break
+    fi
+    sleep 2
+done
+
+if [ ! -s "$L2_METRICS_FILE" ]; then
+    echo "FAIL: could not fetch /metrics from LMCache HTTP server (port $METRICS_HTTP_PORT)."
+    echo "       /metrics being unreachable means we cannot verify the L2"
+    echo "       data flow or the observability surface; failing the test"
+    echo "       rather than silently skipping."
+    echo ""
+    echo "--- LMCache L2 server log (last 50 lines) ---"
+    tail -50 "/tmp/build_${BUILD_ID}_lmcache_l2.log" 2>&1 || true
+    echo ""
+    echo "--- Listening sockets on port ${METRICS_HTTP_PORT} ---"
+    (ss -ltnp 2>/dev/null || netstat -ltnp 2>/dev/null || true) \
+        | awk -v p=":${METRICS_HTTP_PORT}" '$0 ~ p'
+    exit 1
+fi
+
+python3 -c "
+import sys
+
+with open('$L2_METRICS_FILE') as f:
+    metrics_text = f.read()
+
+def get_counter(name):
+    for line in metrics_text.splitlines():
+        if line.startswith(name + ' ') or line.startswith(name + '{'):
+            return float(line.rsplit(' ', 1)[-1])
+    return 0.0
+
+# L1 metrics
+l1_write_keys = get_counter('lmcache_mp_l1_write_chunks_total')
+
+# L2 metrics
+store_keys = get_counter('lmcache_mp_l2_store_submitted_objects_chunks_total')
+store_succeeded = get_counter('lmcache_mp_l2_store_completed_objects_chunks_total')
+prefetch_lookups = get_counter('lmcache_mp_l2_prefetch_lookup_requests_total')
+prefetch_hits = get_counter('lmcache_mp_l2_prefetch_hit_chunks_total')
+prefetch_loaded = get_counter('lmcache_mp_l2_prefetch_load_completed_chunks_total')
+
+print('=' * 60)
+print('Data Flow Metrics')
+print('=' * 60)
+print(f'  L1 write keys:               {l1_write_keys:.0f}')
+print(f'  L2 store keys submitted:     {store_keys:.0f}')
+print(f'  L2 store keys succeeded:     {store_succeeded:.0f}')
+print(f'  L2 prefetch lookups:         {prefetch_lookups:.0f}')
+print(f'  L2 prefetch prefix hits:     {prefetch_hits:.0f}')
+print(f'  L2 prefetch keys loaded:     {prefetch_loaded:.0f}')
+print()
+
+failed = False
+
+def check(cond, pass_msg, fail_msg):
+    global failed
+    if cond:
+        print(f'[PASS] {pass_msg}')
+    else:
+        print(f'[FAIL] {fail_msg}')
+        failed = True
+
+# 1. L1 store activity (warmup writes KV to L1 before L2 store)
+check(l1_write_keys > 0,
+      f'L1 store: {l1_write_keys:.0f} keys written',
+      'No keys written to L1 (expected > 0 from warmup)')
+
+# 2. L2 store submitted and completed
+check(store_keys > 0,
+      f'L2 store: {store_keys:.0f} keys submitted',
+      'No keys submitted to L2 store')
+check(store_succeeded > 0,
+      f'L2 store: {store_succeeded:.0f} keys succeeded',
+      'No keys successfully stored to L2')
+
+# 3. L2 prefetch submitted and completed (query round: L1 cold, L2 has data)
+check(prefetch_lookups > 0,
+      f'L2 prefetch: {prefetch_lookups:.0f} lookup requests',
+      'No prefetch lookups (expected > 0 from query round)')
+check(prefetch_hits > 0,
+      f'L2 prefetch: {prefetch_hits:.0f} prefix hits',
+      'No prefix hits from L2 lookup')
+check(prefetch_loaded > 0,
+      f'L2 prefetch: {prefetch_loaded:.0f} keys loaded',
+      'No keys loaded from L2')
+
+print()
+if failed:
+    print('[FAIL] Data flow verification FAILED')
+    sys.exit(1)
+else:
+    print('[PASS] All data flow checks passed')
+"
+
+# ---------------------------------------------------------------------------
+# Step 5: Verify the rest of the MP observability surface
+# ---------------------------------------------------------------------------
+# The data-flow block above is L2-focused.  This block goes wider — it
+# asserts that every metric we publish from MP mode actually advances
+# during the run.  ``--metrics-sample-rate 1.0`` was set on the relaunch
+# above so the histograms record on every event (the default 0.01 would
+# leave them empty in this short workload and flake the assertions).
+
+echo ""
+echo "============================================"
+echo "=== Verifying full MP observability surface ==="
+echo "============================================"
+
+python3 - "$L2_METRICS_FILE" <<'PYEOF'
+import re
+import sys
+
+with open(sys.argv[1]) as f:
+    text = f.read()
+
+
+def counter_total(name: str) -> float:
+    """Sum a counter across all label combinations."""
+    total = 0.0
+    pat = re.compile(rf"^{re.escape(name)}(\{{[^}}]*\}})?\s+([0-9eE+\-.]+)\s*$", re.M)
+    for _, value in pat.findall(text):
+        try:
+            total += float(value)
+        except ValueError:
+            pass
+    return total
+
+
+def histogram_count(base_name: str) -> float:
+    """Sum the ``_count`` series across all label combinations.
+
+    Non-zero means the histogram observed at least one sample.
+
+    The OTel→Prometheus bridge appends the OTel ``unit`` to the metric
+    name (e.g. unit ``GB/s`` → ``GB_per_second``), so the actual series
+    looks like ``<base>_GB_per_second_count``.  Match that as a suffix
+    so this works whether or not the unit is present.
+    """
+    pat = re.compile(
+        rf"^{re.escape(base_name)}(?:_[A-Za-z_]+)?_count(?:\{{[^}}]*\}})?\s+"
+        rf"([0-9eE+\-.]+)\s*$",
+        re.M,
+    )
+    return sum(float(v) for v in pat.findall(text))
+
+
+def has_label(base_name: str, label: str) -> bool:
+    """Check that at least one sample of `base_name` carries the named label.
+
+    Tolerates the OTel unit suffix that Prometheus appends to histograms.
+    """
+    pat = re.compile(
+        rf"^{re.escape(base_name)}(?:_[A-Za-z_]+)?(?:_count|_sum|_bucket)?"
+        rf"\{{[^}}]*\b{re.escape(label)}=",
+        re.M,
+    )
+    return bool(pat.search(text))
+
+
+# (kind, metric_name, optional_label_to_assert_present_or_None)
+checks = [
+    # ── Newer counters (with label dimensions) ─────────────────────
+    ("counter", "lmcache_mp_l2_store_completed_requests_total", "l2_name"),
+    ("counter", "lmcache_mp_l2_load_completed_requests_total", "l2_name"),
+    ("counter", "lmcache_mp_lookup_requested_tokens_total", "model_name"),
+    ("counter", "lmcache_mp_lookup_hit_tokens_total", "model_name"),
+    ("counter", "lmcache_mp_num_chunks_loaded_total", "worker_id"),
+    # ── Histograms.  The OTel→Prometheus bridge appends the OTel
+    # ``unit`` to the series name, so a histogram declared with
+    # ``unit="GB/s"`` actually reports as
+    # ``<name>_GB_per_second_count`` / ``..._sum`` / ``..._bucket``.
+    # Match by base name and let the helper tolerate the unit suffix.
+    ("hist", "lmcache_mp_l0_l1_store_throughput", None),
+    ("hist", "lmcache_mp_l0_l1_load_throughput", None),
+    ("hist", "lmcache_mp_l2_store_throughput", "l2_name"),
+    ("hist", "lmcache_mp_l2_load_throughput", "l2_name"),
+]
+
+failed = False
+for kind, name, label in checks:
+    if kind == "counter":
+        value = counter_total(name)
+        ok = value > 0
+        detail = f"total={value:.0f}"
+    else:
+        value = histogram_count(name)
+        ok = value > 0
+        detail = f"_count={value:.0f}"
+
+    status = "PASS" if ok else "FAIL"
+    print(f"[{status}] {name}: {detail}")
+    if not ok:
+        failed = True
+        continue
+
+    if label is not None:
+        if has_label(name, label):
+            print(f"       └─ label '{label}' present")
+        else:
+            print(f"[FAIL] {name}: expected label '{label}' is missing")
+            failed = True
+
+print()
+if failed:
+    print("[FAIL] Observability metric verification FAILED")
+    print("       (some metric did not advance, or its label dimension is missing)")
+    sys.exit(1)
+print("[PASS] All observability metrics populated.")
+PYEOF
+
+echo "============================================"
+echo "=== L2 Long Doc QA test completed ==="
+echo "============================================"
+echo "Results: $L2_RESULTS_DIR"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-long-doc-qa.sh b/.buildkite/k3_tests/multiprocess/scripts/run-long-doc-qa.sh
new file mode 100755
index 0000000..c85efc6
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-long-doc-qa.sh
@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# Run long_doc_qa workload test against both vLLM servers.
+# Compares performance between LMCache-enabled and baseline vLLM.
+# Adapted from the old Docker-based run-long-doc-qa.sh.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+LMCACHE_DIR="${LMCACHE_DIR:-$REPO_ROOT}"
+
+DOCUMENT_LENGTH="${DOCUMENT_LENGTH:-10000}"
+NUM_DOCUMENTS="${NUM_DOCUMENTS:-30}"
+OUTPUT_LEN="${OUTPUT_LEN:-200}"
+REPEAT_COUNT="${REPEAT_COUNT:-2}"
+REPEAT_MODE="${REPEAT_MODE:-tile}"
+SHUFFLE_SEED="${SHUFFLE_SEED:-0}"
+MAX_INFLIGHT_REQUESTS="${MAX_INFLIGHT_REQUESTS:-5}"
+
+# Relative performance thresholds (compared against baseline run in same job)
+# Negative values mean LMCache must be *faster* than baseline by at least that %.
+# Recent CI runs show ~77-84% TTFT improvement and ~27-40% round-time improvement,
+# so requiring 60% and 15% respectively leaves comfortable headroom.
+MAX_TTFT_SLOWDOWN_PCT="${MAX_TTFT_SLOWDOWN_PCT:--60}"
+MAX_ROUND_TIME_SLOWDOWN_PCT="${MAX_ROUND_TIME_SLOWDOWN_PCT:--15}"
+
+# Output directory
+LONG_DOC_QA_DIR="$RESULTS_DIR/long_doc_qa"
+
+echo "=== Long Doc QA Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port (with LMCache): $VLLM_PORT"
+echo "vLLM Baseline Port (without LMCache): $VLLM_BASELINE_PORT"
+echo "Document length: $DOCUMENT_LENGTH"
+echo "Number of documents: $NUM_DOCUMENTS"
+echo "Output length: $OUTPUT_LEN"
+echo "Results dir: $LONG_DOC_QA_DIR"
+echo ""
+echo "Performance thresholds (relative to baseline, negative = must be faster):"
+echo "  Max TTFT slowdown: ${MAX_TTFT_SLOWDOWN_PCT}% (LMCache must be >= $(echo "$MAX_TTFT_SLOWDOWN_PCT" | tr -d '-')% faster)"
+echo "  Max round time slowdown: ${MAX_ROUND_TIME_SLOWDOWN_PCT}% (LMCache must be >= $(echo "$MAX_ROUND_TIME_SLOWDOWN_PCT" | tr -d '-')% faster)"
+echo ""
+
+mkdir -p "$LONG_DOC_QA_DIR"
+
+run_long_doc_qa() {
+    local port="$1"
+    local result_file="$2"
+    local description="$3"
+
+    echo "=== Running long_doc_qa ($description) ==="
+    local output_file="$LONG_DOC_QA_DIR/${description}_output.txt"
+
+    python3 "$LMCACHE_DIR/benchmarks/long_doc_qa/long_doc_qa.py" \
+        --port "$port" \
+        --model "$MODEL" \
+        --document-length "$DOCUMENT_LENGTH" \
+        --num-documents "$NUM_DOCUMENTS" \
+        --output-len "$OUTPUT_LEN" \
+        --repeat-count "$REPEAT_COUNT" \
+        --repeat-mode "$REPEAT_MODE" \
+        --shuffle-seed "$SHUFFLE_SEED" \
+        --max-inflight-requests "$MAX_INFLIGHT_REQUESTS" \
+        --output "$output_file" \
+        --json-output \
+        2>>"$output_file" | tee "$result_file"
+
+    echo "$description benchmark completed"
+    echo ""
+}
+
+extract_json_field() {
+    local json_file="$1"
+    local field="$2"
+    local json_line
+    json_line=$(tail -n 1 "$json_file")
+    python3 -c "
+import json, sys
+try:
+    data = json.loads('''$json_line''')
+    value = data.get('$field', 'null')
+    print(value if value is not None else 'null')
+except json.JSONDecodeError:
+    print('null')
+"
+}
+
+compare_results() {
+    local lmcache_result="$LONG_DOC_QA_DIR/lmcache_result.json"
+    local baseline_result="$LONG_DOC_QA_DIR/baseline_result.json"
+
+    echo "=== Comparing benchmark results ==="
+
+    if [ ! -f "$lmcache_result" ] || [ ! -f "$baseline_result" ]; then
+        echo "Result files not found"
+        return 1
+    fi
+
+    lmcache_query_ttft=$(extract_json_field "$lmcache_result" "query_ttft_per_prompt")
+    lmcache_query_round_time=$(extract_json_field "$lmcache_result" "query_round_time_per_prompt")
+    lmcache_warmup_round_time=$(extract_json_field "$lmcache_result" "warmup_round_time_per_prompt")
+
+    baseline_query_ttft=$(extract_json_field "$baseline_result" "query_ttft_per_prompt")
+    baseline_query_round_time=$(extract_json_field "$baseline_result" "query_round_time_per_prompt")
+    baseline_warmup_round_time=$(extract_json_field "$baseline_result" "warmup_round_time_per_prompt")
+
+    echo ""
+    echo "============================================"
+    echo "=== Performance Summary ==="
+    echo "============================================"
+
+    python3 << EOF
+import sys
+
+def safe_float(val):
+    try:
+        return float(val)
+    except (ValueError, TypeError):
+        return None
+
+def format_comparison(name, lmcache_val, baseline_val):
+    lmcache = safe_float(lmcache_val)
+    baseline = safe_float(baseline_val)
+    if lmcache is None or baseline is None:
+        return f"{name}: Unable to compare (invalid values)"
+    if baseline > 0:
+        diff_pct = ((lmcache - baseline) / baseline) * 100
+        diff_str = f"{abs(diff_pct):.2f}% {'faster' if diff_pct < 0 else 'slower'}"
+    else:
+        diff_str = "N/A"
+    return f"{name}:\n  Baseline:  {baseline:.4f}s\n  LMCache:   {lmcache:.4f}s\n  Diff:      {diff_str}"
+
+print(format_comparison("query_ttft_per_prompt", "$lmcache_query_ttft", "$baseline_query_ttft"))
+print()
+print(format_comparison("query_round_time_per_prompt", "$lmcache_query_round_time", "$baseline_query_round_time"))
+print()
+print(format_comparison("warmup_round_time_per_prompt", "$lmcache_warmup_round_time", "$baseline_warmup_round_time"))
+print()
+
+# Summary table
+print(f"{'Metric':<35} {'Baseline':>12} {'LMCache':>12} {'Diff':>10}")
+print("-" * 70)
+metrics = [
+    ("query_ttft_per_prompt", "$baseline_query_ttft", "$lmcache_query_ttft"),
+    ("query_round_time_per_prompt", "$baseline_query_round_time", "$lmcache_query_round_time"),
+    ("warmup_round_time_per_prompt", "$baseline_warmup_round_time", "$lmcache_warmup_round_time"),
+]
+for name, bval, lval in metrics:
+    b = safe_float(bval)
+    l = safe_float(lval)
+    if b is not None and l is not None:
+        diff_pct = ((l - b) / b) * 100 if b > 0 else 0
+        print(f"{name:<35} {b:>12.4f} {l:>12.4f} {diff_pct:>+9.1f}%")
+    else:
+        print(f"{name:<35} {'N/A':>12} {'N/A':>12} {'N/A':>10}")
+print()
+EOF
+
+    return 0
+}
+
+verify_thresholds() {
+    local lmcache_result="$LONG_DOC_QA_DIR/lmcache_result.json"
+    local baseline_result="$LONG_DOC_QA_DIR/baseline_result.json"
+
+    echo "=== Verifying LMCache performance vs baseline ==="
+    echo "Max allowed TTFT slowdown: ${MAX_TTFT_SLOWDOWN_PCT}%"
+    echo "Max allowed query round time slowdown: ${MAX_ROUND_TIME_SLOWDOWN_PCT}%"
+    echo ""
+
+    lmcache_query_ttft=$(extract_json_field "$lmcache_result" "query_ttft_per_prompt")
+    lmcache_query_round_time=$(extract_json_field "$lmcache_result" "query_round_time_per_prompt")
+    baseline_query_ttft=$(extract_json_field "$baseline_result" "query_ttft_per_prompt")
+    baseline_query_round_time=$(extract_json_field "$baseline_result" "query_round_time_per_prompt")
+
+    python3 << EOF
+import sys
+
+def safe_float(val):
+    try:
+        return float(val)
+    except (ValueError, TypeError):
+        return None
+
+def check_metric(name, lmcache_val, baseline_val, max_slowdown_pct):
+    lmc = safe_float(lmcache_val)
+    base = safe_float(baseline_val)
+    if lmc is None or base is None or base <= 0:
+        print(f"{name}: unable to compare (lmcache={lmcache_val}, baseline={baseline_val}) -- FAIL")
+        return False
+    pct = ((lmc - base) / base) * 100
+    label = f"{abs(pct):.1f}% faster" if pct < 0 else f"{pct:.1f}% slower"
+    if max_slowdown_pct < 0:
+        threshold_label = f"need >= {abs(max_slowdown_pct):.0f}% faster"
+    else:
+        threshold_label = f"max {max_slowdown_pct}% slower"
+    if pct <= max_slowdown_pct:
+        print(f"{name}: {lmc:.4f}s vs baseline {base:.4f}s ({label}, {threshold_label}) -- PASS")
+        return True
+    else:
+        print(f"{name}: {lmc:.4f}s vs baseline {base:.4f}s ({label}, {threshold_label}) -- FAIL")
+        return False
+
+failed = False
+if not check_metric("query_ttft_per_prompt",
+                     "$lmcache_query_ttft", "$baseline_query_ttft",
+                     float("$MAX_TTFT_SLOWDOWN_PCT")):
+    failed = True
+if not check_metric("query_round_time_per_prompt",
+                     "$lmcache_query_round_time", "$baseline_query_round_time",
+                     float("$MAX_ROUND_TIME_SLOWDOWN_PCT")):
+    failed = True
+
+if failed:
+    print("\nThreshold verification FAILED")
+    sys.exit(1)
+else:
+    print("\nAll thresholds passed")
+    sys.exit(0)
+EOF
+}
+
+# Run benchmark against baseline
+echo "============================================"
+echo "=== Benchmark: Baseline vLLM (without LMCache) ==="
+echo "============================================"
+run_long_doc_qa "$VLLM_BASELINE_PORT" "$LONG_DOC_QA_DIR/baseline_result.json" "baseline"
+
+# Run benchmark against vLLM with LMCache
+echo "============================================"
+echo "=== Benchmark: vLLM with LMCache ==="
+echo "============================================"
+run_long_doc_qa "$VLLM_PORT" "$LONG_DOC_QA_DIR/lmcache_result.json" "lmcache"
+
+# Compare
+echo "============================================"
+echo "=== Comparing Results ==="
+echo "============================================"
+if ! compare_results; then
+    echo "Comparison failed"
+    exit 1
+fi
+
+# Verify thresholds
+echo "============================================"
+echo "=== Verifying Performance Thresholds ==="
+echo "============================================"
+if ! verify_thresholds; then
+    echo "Threshold verification failed"
+    exit 1
+fi
+
+echo "============================================"
+echo "=== Long Doc QA test completed ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-mp-test.sh b/.buildkite/k3_tests/multiprocess/scripts/run-mp-test.sh
new file mode 100755
index 0000000..fec0826
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-mp-test.sh
@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Main orchestrator for multiprocessing tests (native, no Docker).
+# Launches LMCache MP server + vLLM with LMCache + vLLM baseline,
+# then runs workloads (lm_eval, vllm bench, long_doc_qa).
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+source .buildkite/k3_tests/common_scripts/helpers.sh
+
+# ── Configuration ────────────────────────────────────────────
+export LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+export VLLM_PORT="${VLLM_PORT:-8000}"
+export VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+export MAX_WAIT_SECONDS="${MAX_WAIT_SECONDS:-300}"
+export BUILD_ID="${BUILDKITE_BUILD_ID:-local_$$}"
+export MODEL="${MODEL:-Qwen/Qwen3-14B}"
+export CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+export MAX_WORKERS="${MAX_WORKERS:-4}"
+export LMCACHE_DIR="$REPO_ROOT"
+export RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+mkdir -p "$RESULTS_DIR"
+
+TEST_RESULT=0
+
+# Cleanup: always kill background processes on exit
+trap '"${SCRIPT_DIR}/cleanup.sh"' EXIT
+
+echo "============================================"
+echo "=== LMCache Multiprocessing Test ==="
+echo "============================================"
+echo "Build ID: $BUILD_ID"
+echo "Model: $MODEL"
+echo "LMCache port: $LMCACHE_PORT"
+echo "vLLM port: $VLLM_PORT"
+echo "vLLM baseline port: $VLLM_BASELINE_PORT"
+echo "Results dir: $RESULTS_DIR"
+echo ""
+
+# Step 1: Launch native processes (replaces Docker containers)
+echo "============================================"
+echo "=== Step 1: Launching native processes ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/launch-processes.sh"; then
+    echo "Failed to launch processes"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 2: Wait for vLLM to be ready
+echo "============================================"
+echo "=== Step 2: Waiting for vLLM to be ready ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/wait-for-servers.sh"; then
+    echo "vLLM failed to become ready"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 3: Run lm_eval workload test
+echo "============================================"
+echo "=== Step 3: Running lm_eval workload ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/run-lm-eval.sh"; then
+    echo "lm_eval workload test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 4: Run vllm bench serve test
+echo "============================================"
+echo "=== Step 4: Running vllm bench serve ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/run-vllm-bench.sh"; then
+    echo "vllm bench serve test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 5: Run long doc QA test
+echo "============================================"
+echo "=== Step 5: Running long doc QA ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/run-long-doc-qa.sh"; then
+    echo "long doc QA test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 6: L2 long doc QA test (restarts LMCache with L2 config)
+echo "============================================"
+echo "=== Step 6: Running long doc QA (L2) ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/run-long-doc-qa-l2.sh"; then
+    echo "long doc QA L2 test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 7: Fault tolerance test (kills LMCache server -- must be last)
+echo "============================================"
+echo "=== Step 7: Running fault tolerance test ==="
+echo "============================================"
+if ! "${SCRIPT_DIR}/run-fault-tolerance.sh"; then
+    echo "fault tolerance test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+echo "============================================"
+echo "=== All tests passed! ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-p2p.sh b/.buildkite/k3_tests/multiprocess/scripts/run-p2p.sh
new file mode 100644
index 0000000..3ff88f4
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-p2p.sh
@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# P2P end-to-end test: two LMCache MP instances + two vLLM instances + one
+# coordinator, all in a single 2-GPU pod over localhost.
+#
+# Topology:
+#   coordinator           : http://127.0.0.1:12300
+#   lmcache A (GPU 0)      : zmq 6555, http 7555, p2p-advertise 127.0.0.1:8555
+#   lmcache B (GPU 1)      : zmq 6556, http 7556, p2p-advertise 127.0.0.1:8556
+#   vLLM A    (GPU 0)      : port 8000, connector -> lmcache A (mp.port 6555)
+#   vLLM B    (GPU 1)      : port 8001, connector -> lmcache B (mp.port 6556)
+#
+# Flow:
+#   1. Both lmcache servers register with the coordinator and discover each
+#      other; each creates a P2P L2 adapter for its peer.
+#   2. Send a long prompt to vLLM A (cold) -> stored in lmcache A's L1.
+#   3. Send the same prompt to vLLM B. B's L1 is empty and its only L2 adapter
+#      is the P2P adapter pointing at A, so any LMCache hit on B must have been
+#      fetched from A over P2P.
+#   4. Assert B's num_lmcache_cached_tokens > 0.
+#
+# Self-contained: launches every process itself and records PIDs in the shared
+# PID file so cleanup.sh tears them down on exit.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+MAX_WAIT_SECONDS="${MAX_WAIT_SECONDS:-300}"
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+
+# Ports (localhost, single pod).
+COORDINATOR_PORT="${COORDINATOR_PORT:-12300}"
+COORDINATOR_URL="http://127.0.0.1:${COORDINATOR_PORT}"
+LMCACHE_A_PORT=6555; LMCACHE_A_HTTP=7555; LMCACHE_A_P2P="127.0.0.1:8555"
+LMCACHE_B_PORT=6556; LMCACHE_B_HTTP=7556; LMCACHE_B_P2P="127.0.0.1:8556"
+VLLM_A_PORT=8000
+VLLM_B_PORT=8001
+
+# Tell cleanup.sh which ports to free (PID-file kill covers the rest).
+export VLLM_PORT="$VLLM_A_PORT"
+export VLLM_BASELINE_PORT="$VLLM_B_PORT"
+export LMCACHE_PORT="$LMCACHE_A_PORT"
+
+# GPUs: K8s assigns devices 0 and 1.
+GPU_A="${GPU_FOR_A:-0}"
+GPU_B="${GPU_FOR_B:-1}"
+
+P2P_DIR="$RESULTS_DIR/p2p"
+mkdir -p "$P2P_DIR"
+
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+> "$PID_FILE"
+
+# vLLM GPU-memory fraction: clamp on very large GPUs so APC does not cover the
+# whole prefix and hide the LMCache path (mirrors launch-processes.sh).
+GPU_MEMORY_UTIL_ARG=""
+GPU_MEMORY_MB=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits -i "${GPU_A}" | tr -d ' ')
+GPU_MEMORY_GB=$((GPU_MEMORY_MB / 1024))
+echo "Detected GPU memory: ${GPU_MEMORY_GB}GB"
+if [ -n "${GPU_MEMORY_UTILIZATION:-}" ]; then
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization ${GPU_MEMORY_UTILIZATION}"
+elif [ "$GPU_MEMORY_GB" -gt 90 ]; then
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization 0.5"
+fi
+
+CONNECTOR_CONFIG() {
+    # $1 = lmcache mp port
+    echo "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $1, \"lmcache.mp.mq_timeout\": 10}}"
+}
+
+launch_lmcache() {
+    # $1=gpu $2=zmq_port $3=http_port $4=p2p_advertise $5=instance_id $6=logname
+    CUDA_VISIBLE_DEVICES="$1" \
+    lmcache server \
+        --l1-size-gb "$CPU_BUFFER_SIZE" \
+        --eviction-policy LRU \
+        --max-workers "$MAX_WORKERS" \
+        --port "$2" \
+        --http-port "$3" \
+        --host 127.0.0.1 \
+        --instance-id "$5" \
+        --coordinator-url "$COORDINATOR_URL" \
+        --coordinator-advertise-ip 127.0.0.1 \
+        --p2p-advertise-url "$4" \
+        > "/tmp/build_${BUILD_ID}_${6}.log" 2>&1 &
+    local pid=$!
+    echo "$pid" >> "$PID_FILE"
+    echo "$pid"
+}
+
+launch_vllm() {
+    # $1=gpu $2=serving_port $3=lmcache_mp_port $4=logname
+    # Unset VLLM_PORT so vLLM's get_open_port() picks a random internal port
+    # for torch.distributed instead of colliding on serving_port+1.
+    env -u VLLM_PORT \
+    CUDA_VISIBLE_DEVICES="$1" \
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    VLLM_SERVER_DEV_MODE=1 \
+    VLLM_BATCH_INVARIANT=1 \
+    PYTHONHASHSEED=0 \
+    vllm serve "$MODEL" \
+        --kv-transfer-config "$(CONNECTOR_CONFIG "$3")" \
+        --attention-backend FLASH_ATTN \
+        --port "$2" \
+        --no-async-scheduling \
+        --max-model-len auto \
+        $GPU_MEMORY_UTIL_ARG \
+        > "/tmp/build_${BUILD_ID}_${4}.log" 2>&1 &
+    local pid=$!
+    echo "$pid" >> "$PID_FILE"
+    echo "$pid"
+}
+
+# ── Step 1: coordinator ──────────────────────────────────────
+echo "=== Launching coordinator on ${COORDINATOR_URL} ==="
+lmcache coordinator --host 0.0.0.0 --port "$COORDINATOR_PORT" \
+    > "/tmp/build_${BUILD_ID}_coordinator.log" 2>&1 &
+echo "$!" >> "$PID_FILE"
+echo "Waiting for coordinator health..."
+for _ in $(seq 1 30); do
+    if curl -sf "${COORDINATOR_URL}/healthz" > /dev/null 2>&1; then break; fi
+    sleep 1
+done
+
+# ── Step 2: two LMCache MP servers ───────────────────────────
+echo "=== Launching LMCache servers ==="
+launch_lmcache "$GPU_A" "$LMCACHE_A_PORT" "$LMCACHE_A_HTTP" "$LMCACHE_A_P2P" \
+    "p2p-a-${BUILD_ID}" "lmcache_a" > /dev/null
+launch_lmcache "$GPU_B" "$LMCACHE_B_PORT" "$LMCACHE_B_HTTP" "$LMCACHE_B_P2P" \
+    "p2p-b-${BUILD_ID}" "lmcache_b" > /dev/null
+echo "Waiting for LMCache servers to initialize..."
+sleep 10
+
+# ── Step 3: wait for P2P discovery (A must see B as a peer) ──
+echo "=== Waiting for P2P peer discovery ==="
+discovered=false
+for _ in $(seq 1 "$MAX_WAIT_SECONDS"); do
+    peers=$(curl -sf "http://127.0.0.1:${LMCACHE_A_HTTP}/status" 2>/dev/null \
+        | python3 -c "import json,sys; print(json.load(sys.stdin).get('p2p_peer_count', 0))" \
+        2>/dev/null || echo 0)
+    if [ "${peers:-0}" -ge 1 ]; then
+        echo "lmcache A discovered ${peers} P2P peer(s)."
+        discovered=true
+        break
+    fi
+    sleep 2
+done
+if [ "$discovered" != "true" ]; then
+    echo "FAIL: lmcache A did not discover its P2P peer in time"
+    echo "--- lmcache A log (tail) ---"; tail -50 "/tmp/build_${BUILD_ID}_lmcache_a.log" || true
+    echo "--- lmcache B log (tail) ---"; tail -50 "/tmp/build_${BUILD_ID}_lmcache_b.log" || true
+    echo "--- coordinator instances ---"; curl -s "${COORDINATOR_URL}/instances" || true
+    exit 1
+fi
+
+# ── Step 4: two vLLM servers ─────────────────────────────────
+echo "=== Launching vLLM servers ==="
+launch_vllm "$GPU_A" "$VLLM_A_PORT" "$LMCACHE_A_PORT" "vllm_a" > /dev/null
+launch_vllm "$GPU_B" "$VLLM_B_PORT" "$LMCACHE_B_PORT" "vllm_b" > /dev/null
+
+wait_for_vllm() {
+    local port="$1" name="$2" logfile="$3"
+    echo "Waiting for $name on port $port..."
+    local deadline=$(( $(date +%s) + MAX_WAIT_SECONDS ))
+    while [ "$(date +%s)" -lt "$deadline" ]; do
+        if curl -sf "http://localhost:${port}/health" > /dev/null 2>&1 \
+           || curl -sf "http://localhost:${port}/v1/models" > /dev/null 2>&1; then
+            echo "$name is ready."
+            return 0
+        fi
+        sleep 5
+    done
+    echo "FAIL: $name did not become ready in ${MAX_WAIT_SECONDS}s"
+    tail -100 "$logfile" 2>/dev/null || true
+    return 1
+}
+wait_for_vllm "$VLLM_A_PORT" "vLLM A" "/tmp/build_${BUILD_ID}_vllm_a.log"
+wait_for_vllm "$VLLM_B_PORT" "vLLM B" "/tmp/build_${BUILD_ID}_vllm_b.log"
+
+# ── Step 5: long prompt to A (cold), then B (P2P hit) ────────
+LONG_CONTENT="Explain the history of computer science in great detail. $(printf 'The Turing machine is a fundamental concept in theoretical computer science that defines an abstract machine capable of manipulating symbols on a strip of tape according to a table of rules. %.0s' {1..20})"
+
+send_request() {
+    # $1=port $2=label $3=output_file
+    local http_code
+    http_code=$(curl -s -o "$3" -w "%{http_code}" \
+        -X POST "http://localhost:${1}/v1/chat/completions" \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"${MODEL}\",
+            \"messages\": [{\"role\": \"user\", \"content\": $(python3 -c "import json;print(json.dumps('$LONG_CONTENT'))")}],
+            \"max_tokens\": 1,
+            \"kv_transfer_params\": {\"cached_token_stats\": true}
+        }")
+    if [ "$http_code" -ne 200 ]; then
+        echo "FAIL: $2 returned HTTP $http_code"; cat "$3"; return 1
+    fi
+    echo "$2: HTTP 200 OK"
+}
+
+echo "=== Step 5a: cold request to vLLM A (populates lmcache A) ==="
+send_request "$VLLM_A_PORT" "engine-A-cold" "$P2P_DIR/a_cold.json"
+
+# Let A's store complete and become lockable before B looks it up over P2P.
+sleep 8
+
+echo "=== Step 5b: same request to vLLM B (should hit A over P2P) ==="
+send_request "$VLLM_B_PORT" "engine-B-p2p" "$P2P_DIR/b_p2p.json"
+
+# ── Step 6: assert B got a P2P cache hit ─────────────────────
+echo "=== Step 6: verify P2P cache hit on engine B ==="
+python3 -c "
+import json, sys
+
+with open('$P2P_DIR/b_p2p.json') as f:
+    data = json.load(f)
+
+stats = (data.get('kv_transfer_params') or {}).get('cached_token_stats')
+if stats is None:
+    print('FAIL: cached_token_stats missing from engine B response')
+    print(data)
+    sys.exit(1)
+
+lmcache_hits = stats['num_lmcache_cached_tokens']
+vllm_hits = stats['num_vllm_cached_tokens']
+print(f'engine B num_vllm_cached_tokens:    {vllm_hits}')
+print(f'engine B num_lmcache_cached_tokens: {lmcache_hits}')
+
+# B never saw this prompt and its only L2 adapter is the P2P adapter to A, so a
+# positive LMCache hit can only have come from A over P2P.
+if lmcache_hits <= 0:
+    print('FAIL: engine B had no LMCache hits; P2P fetch did not happen')
+    sys.exit(1)
+
+print(f'PASS: engine B served {lmcache_hits} tokens from peer A over P2P')
+"
+
+echo "============================================"
+echo "=== P2P test PASSED ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-restart-recovery.sh b/.buildkite/k3_tests/multiprocess/scripts/run-restart-recovery.sh
new file mode 100755
index 0000000..c1ed229
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-restart-recovery.sh
@@ -0,0 +1,287 @@
+#!/usr/bin/env bash
+# Test LMCache server restart recovery: vLLM workers should re-register
+# their KV caches with the new LMCache server (driven by the heartbeat
+# thread's recover callback) and resume successful stores.
+#
+# Flow:
+#   1. Run a `lmcache bench engine --workload random-prefill` round.
+#   2. Snapshot lmcache_mp_l1_write_chunks_total via /metrics.
+#   3. Kill the LMCache server, relaunch on the same port.
+#   4. Wait for the new server to be ready and for the worker to
+#      re-register (poll /status until cache_context_meta is non-empty).
+#   5. Run the same bench round again.
+#   6. Snapshot the metric again.
+#   7. Assert run2 > 0 and run2 >= 0.8 * run1.
+#
+# The metric counter is reset to 0 by the new server process, so
+# run2 is the absolute count for the post-restart benchmark only.
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# ── Configuration (inherited from run-single-test.sh) ─────────
+VLLM_PORT="${VLLM_PORT:-8000}"
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-8080}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+
+# Bench parameters — small enough for CI but big enough to register
+# a non-trivial l1_write_keys count per round.
+NUM_REQUESTS="${RR_NUM_REQUESTS:-100}"
+REQUEST_LEN="${RR_REQUEST_LEN:-5000}"
+KV_CACHE_VOLUME="${RR_KV_CACHE_VOLUME:-5}"
+
+# Recovery timing
+RECOVER_TIMEOUT="${RR_RECOVER_TIMEOUT:-150}"
+
+# Output
+OUT_DIR="$RESULTS_DIR/restart_recovery"
+mkdir -p "$OUT_DIR"
+
+PID_FILE="/tmp/lmcache_mp_pids_${BUILD_ID}"
+
+echo "=== Restart Recovery Test ==="
+echo "Model: $MODEL"
+echo "vLLM URL: http://localhost:${VLLM_PORT}"
+echo "LMCache HTTP URL: http://localhost:${LMCACHE_HTTP_PORT}"
+echo "Bench: ${NUM_REQUESTS} requests x ${REQUEST_LEN} tokens"
+echo "Recovery timeout: ${RECOVER_TIMEOUT}s"
+echo ""
+
+# ── Helpers ──────────────────────────────────────────────────
+
+run_bench_round() {
+    local label="$1"
+    local seed=$2
+    local out_subdir="$OUT_DIR/$label"
+    mkdir -p "$out_subdir"
+    echo "--- bench round: $label ---"
+
+    if ! lmcache bench engine \
+        --engine-url "http://localhost:${VLLM_PORT}" \
+        --lmcache-url "http://localhost:${LMCACHE_HTTP_PORT}" \
+        --workload random-prefill \
+        --rp-num-requests "$NUM_REQUESTS" \
+        --rp-request-length "$REQUEST_LEN" \
+        --kv-cache-volume "$KV_CACHE_VOLUME" \
+        --no-interactive \
+        --no-csv \
+        --json \
+        --quiet \
+        --seed $seed \
+        --output-dir "$out_subdir" \
+        2>&1 | tee "$out_subdir/bench.log"; then
+        echo "FAIL: bench round '$label' returned non-zero (failed requests)"
+        return 1
+    fi
+
+    # Quick sanity from JSON summary
+    if [ -f "$out_subdir/bench_summary.json" ]; then
+        local successful failed
+        successful=$(python3 -c "import json; print(json.load(open('$out_subdir/bench_summary.json')).get('successful_requests', 0))")
+        failed=$(python3 -c "import json; print(json.load(open('$out_subdir/bench_summary.json')).get('failed_requests', 0))")
+        echo "$label: successful=$successful failed=$failed"
+        if [ "$failed" -ne 0 ]; then
+            echo "FAIL: $failed requests failed in '$label'"
+            return 1
+        fi
+    fi
+    return 0
+}
+
+scrape_l1_write_keys() {
+    # Print the latest lmcache_mp_l1_write_chunks_total value (single sample,
+    # unlabeled) from the LMCache HTTP server's /metrics endpoint.
+    python3 - <<EOF
+import sys, urllib.request
+url = "http://localhost:${LMCACHE_HTTP_PORT}/metrics"
+try:
+    body = urllib.request.urlopen(url, timeout=10).read().decode()
+except Exception as e:
+    print(f"ERROR fetching {url}: {e}", file=sys.stderr)
+    sys.exit(1)
+total = None
+for line in body.splitlines():
+    if line.startswith("#"):
+        continue
+    if not line.startswith("lmcache_mp_l1_write_chunks_total"):
+        continue
+    parts = line.rsplit(" ", 1)
+    if len(parts) != 2:
+        continue
+    try:
+        val = float(parts[1])
+    except ValueError:
+        continue
+    total = (total or 0.0) + val
+if total is None:
+    print(f"ERROR: lmcache_mp_l1_write_chunks_total not found at {url}", file=sys.stderr)
+    sys.exit(1)
+print(int(total))
+EOF
+}
+
+wait_for_lmcache_http() {
+    local deadline=$(( $(date +%s) + 60 ))
+    while [ "$(date +%s)" -lt "$deadline" ]; do
+        if curl -sf "http://localhost:${LMCACHE_HTTP_PORT}/healthcheck" > /dev/null 2>&1; then
+            echo "LMCache HTTP healthy"
+            return 0
+        fi
+        sleep 2
+    done
+    echo "FAIL: LMCache HTTP did not come back within 60s"
+    return 1
+}
+
+wait_for_worker_reregister() {
+    # Poll /status until cache_context_meta has at least one entry,
+    # which proves the vLLM worker re-registered with the new server.
+    local deadline=$(( $(date +%s) + RECOVER_TIMEOUT ))
+    while [ "$(date +%s)" -lt "$deadline" ]; do
+        local count
+        count=$(python3 - <<EOF 2>/dev/null
+import json, urllib.request
+try:
+    body = urllib.request.urlopen("http://localhost:${LMCACHE_HTTP_PORT}/status", timeout=5).read()
+    data = json.loads(body)
+    print(len(data.get("cache_context_meta", {})))
+except Exception:
+    print(0)
+EOF
+)
+        if [ "$count" -gt 0 ]; then
+            echo "Worker re-registered (cache_context_meta entries: $count)"
+            return 0
+        fi
+        sleep 2
+    done
+    echo "FAIL: worker did not re-register within ${RECOVER_TIMEOUT}s"
+    return 1
+}
+
+restart_lmcache() {
+    local old_pid
+    old_pid=$(sed -n '1p' "$PID_FILE" 2>/dev/null || true)
+    if [ -z "$old_pid" ]; then
+        echo "FAIL: no LMCache PID in $PID_FILE"
+        return 1
+    fi
+    echo "Killing LMCache PID $old_pid..."
+    if kill -0 "$old_pid" 2>/dev/null; then
+        kill "$old_pid" 2>/dev/null || true
+        wait "$old_pid" 2>/dev/null || true
+    fi
+    sleep 60
+
+    echo "Relaunching LMCache on port ${LMCACHE_PORT} / HTTP ${LMCACHE_HTTP_PORT}..."
+    lmcache server \
+        --l1-size-gb "$CPU_BUFFER_SIZE" \
+        --eviction-policy LRU \
+        --max-workers "$MAX_WORKERS" \
+        --port "$LMCACHE_PORT" \
+        --http-port "$LMCACHE_HTTP_PORT" \
+        > "/tmp/build_${BUILD_ID}_lmcache_restart.log" 2>&1 &
+
+    local new_pid=$!
+    echo "$new_pid" > /tmp/.new_lmcache_pid
+    # Replace line 1 of the PID file so cleanup.sh kills the new process.
+    sed -i "1s/.*/$new_pid/" "$PID_FILE"
+    echo "LMCache restarted (PID=$new_pid)"
+    return 0
+}
+
+# ── Step 1: Bench round 1 ────────────────────────────────────
+echo "============================================"
+echo "=== Round 1: bench against original server ==="
+echo "============================================"
+if ! run_bench_round "round1" "41"; then
+    echo "FAIL: round 1 bench failed"
+    exit 1
+fi
+
+ROUND1_WRITES=$(scrape_l1_write_keys) || {
+    echo "FAIL: could not scrape /metrics after round 1"
+    exit 1
+}
+echo "Round 1 lmcache_mp_l1_write_chunks_total = $ROUND1_WRITES"
+
+if [ "$ROUND1_WRITES" -le 0 ]; then
+    echo "FAIL: round 1 produced no L1 writes; benchmark setup is broken"
+    exit 1
+fi
+
+# ── Step 2: Kill + relaunch LMCache ──────────────────────────
+echo ""
+echo "============================================"
+echo "=== Restarting LMCache server ==="
+echo "============================================"
+if ! restart_lmcache; then
+    exit 1
+fi
+
+if ! wait_for_lmcache_http; then
+    echo "--- new lmcache log (last 80 lines) ---"
+    tail -80 "/tmp/build_${BUILD_ID}_lmcache_restart.log" 2>/dev/null || true
+    exit 1
+fi
+
+if ! wait_for_worker_reregister; then
+    echo "--- new lmcache log (last 80 lines) ---"
+    tail -80 "/tmp/build_${BUILD_ID}_lmcache_restart.log" 2>/dev/null || true
+    echo "--- vllm log (last 80 lines) ---"
+    tail -80 "/tmp/build_${BUILD_ID}_vllm.log" 2>/dev/null || true
+    exit 1
+fi
+
+# ── Step 3: Bench round 2 ────────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Round 2: bench against restarted server ==="
+echo "============================================"
+if ! run_bench_round "round2" "42"; then
+    echo "FAIL: round 2 bench failed"
+    echo "--- vllm log (last 80 lines) ---"
+    tail -80 "/tmp/build_${BUILD_ID}_vllm.log" 2>/dev/null || true
+    exit 1
+fi
+
+ROUND2_WRITES=$(scrape_l1_write_keys) || {
+    echo "FAIL: could not scrape /metrics after round 2"
+    exit 1
+}
+echo "Round 2 lmcache_mp_l1_write_chunks_total = $ROUND2_WRITES"
+
+# ── Step 4: Compare metrics ──────────────────────────────────
+echo ""
+echo "============================================"
+echo "=== Verification ==="
+echo "============================================"
+echo "Round 1 writes: $ROUND1_WRITES"
+echo "Round 2 writes: $ROUND2_WRITES"
+
+if [ "$ROUND2_WRITES" -le 0 ]; then
+    echo "FAIL: round 2 produced no L1 writes — re-registration likely failed"
+    exit 1
+fi
+
+# Floor-divide: round2 >= 0.8 * round1  <=>  round2 * 10 >= round1 * 8
+if [ $((ROUND2_WRITES * 10)) -lt $((ROUND1_WRITES * 8)) ]; then
+    pct=$(python3 -c "print(f'{$ROUND2_WRITES / $ROUND1_WRITES * 100:.1f}')")
+    echo "FAIL: round 2 only ${pct}% of round 1 writes (threshold: 80%)"
+    exit 1
+fi
+
+pct=$(python3 -c "print(f'{$ROUND2_WRITES / $ROUND1_WRITES * 100:.1f}')")
+echo "PASS: round 2 = ${pct}% of round 1 (>= 80%)"
+echo ""
+echo "============================================"
+echo "=== Restart Recovery Test PASSED ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-single-test.sh b/.buildkite/k3_tests/multiprocess/scripts/run-single-test.sh
new file mode 100755
index 0000000..fb72976
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-single-test.sh
@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+# Orchestrator for a single multiprocessing test (native, no Docker).
+# Usage: run-single-test.sh <test_name>
+#   test_name: lm_eval | hma_lm_eval_gemma4 | vllm_bench | long_doc_qa
+#              | long_doc_qa_l2 | fault_tolerance | deadlock | restart_recovery
+#              | gds_smoke_test
+#
+# Each invocation is self-contained: launches servers, runs one test, cleans up.
+# This mirrors the comprehensive tests' run-single-config.sh pattern.
+set -o pipefail
+
+TEST_NAME="${1:?Usage: $0 <test_name>}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+source .buildkite/k3_tests/common_scripts/helpers.sh
+
+# ── Configuration ────────────────────────────────────────────
+export LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+export VLLM_PORT="${VLLM_PORT:-8000}"
+export VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+export MAX_WAIT_SECONDS="${MAX_WAIT_SECONDS:-300}"
+export BUILD_ID="${BUILDKITE_BUILD_ID:-local_$$}"
+
+# gds_smoke_test enables the GDS L1 NVMe-slab tier
+GDS_SCRATCH="${GDS_SCRATCH:-/scratch}"
+if [ "$TEST_NAME" = "gds_smoke_test" ]; then
+    export GDS_L1_PATH="${GDS_SCRATCH}/lmcache-gds-${BUILD_ID}-${TEST_NAME}"
+    echo "GDS L1 tier enabled (slab dir: $GDS_L1_PATH)"
+fi
+
+# Per-test default model (overridable via the MODEL env var). The HMA test needs
+# a hybrid model whose KV cache groups have different block sizes, so the
+# connector exercises the per-group hybrid-memory-allocator path.
+if [ "$TEST_NAME" = "hma_lm_eval_gemma4" ]; then
+    # gemma-4-31B-it is public (no gating, so no HF token check) and has
+    # heterogeneous head dims (head_dim 256 / global_head_dim 512), so vLLM
+    # gives its KV cache groups different block sizes -- this is what exercises
+    # LMCache's per-group block-size handling. It forces TRITON_ATTN, so the
+    # pipeline sets ATTENTION_BACKEND=auto; its ~63GB of weights also need a
+    # higher GPU_MEMORY_UTILIZATION than the default (all set in pipeline.yml).
+    export MODEL="${MODEL:-google/gemma-4-31B-it}"
+elif [ "$TEST_NAME" = "hma_lm_eval_qwen3_5" ]; then
+    # Qwen3.5-0.8B is a Mamba/GDN + full-attention hybrid (caches re-viewed at
+    # registration; see lmcache/integration/vllm/kv_cache_group_edits.py).
+    export MODEL="${MODEL:-Qwen/Qwen3.5-0.8B}"
+    export ATTENTION_BACKEND="${ATTENTION_BACKEND:-auto}"
+    # LMCache chunk size must be a multiple of the unified vLLM block size (544).
+    export CHUNK_SIZE="${CHUNK_SIZE:-544}"
+    # GDN supports only the 'align' Mamba cache mode.
+    export MAMBA_CACHE_MODE="${MAMBA_CACHE_MODE:-align}"
+    # 'align' snapshots the Mamba state only at scheduler-step boundaries; cap
+    # the step at the chunk size for one reusable snapshot per chunk.
+    export MAX_NUM_BATCHED_TOKENS="${MAX_NUM_BATCHED_TOKENS:-544}"
+    # GDN has no batch-invariant mode, so runs are not bit-exact; compare within
+    # a score tolerance and use enough samples to shrink run-to-run drift
+    # (~1/sqrt(LIMIT)) well inside it.
+    export BATCH_INVARIANT="${BATCH_INVARIANT:-0}"
+    export SCORE_TOLERANCE="${SCORE_TOLERANCE:-0.05}"
+    export LIMIT="${LIMIT:-300}"
+else
+    export MODEL="${MODEL:-Qwen/Qwen3-14B}"
+fi
+export CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+export MAX_WORKERS="${MAX_WORKERS:-4}"
+export LMCACHE_DIR="$REPO_ROOT"
+export RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+mkdir -p "$RESULTS_DIR"
+
+# Cleanup: always kill background processes on exit
+trap '"${SCRIPT_DIR}/cleanup.sh"' EXIT
+
+echo "============================================"
+echo "=== LMCache Multiprocessing Test: ${TEST_NAME} ==="
+echo "============================================"
+echo "Build ID: $BUILD_ID"
+echo "Model: $MODEL"
+echo "LMCache port: $LMCACHE_PORT"
+echo "vLLM port: $VLLM_PORT"
+echo "vLLM baseline port: $VLLM_BASELINE_PORT"
+echo "Results dir: $RESULTS_DIR"
+echo ""
+
+# Tests that handle their own server lifecycle (different GPU/model config)
+SELF_CONTAINED_TESTS=" deadlock p2p "
+
+# Tests that compare against a baseline vLLM (no LMCache) on a second GPU.
+# Only these need the baseline server (and thus a 2-GPU pod); everything
+# else runs on GPU 0 alone, so launch-processes.sh skips the baseline.
+BASELINE_TESTS=" vllm_bench long_doc_qa long_doc_qa_l2 "
+if [[ "$BASELINE_TESTS" == *" $TEST_NAME "* ]]; then
+    export LAUNCH_BASELINE=true
+else
+    export LAUNCH_BASELINE=false
+fi
+
+if [[ "$SELF_CONTAINED_TESTS" != *" $TEST_NAME "* ]]; then
+    # ── Step 1: Launch native processes ──────────────────────────
+    echo "============================================"
+    echo "=== Launching native processes ==="
+    echo "============================================"
+    if ! "${SCRIPT_DIR}/launch-processes.sh"; then
+        echo "Failed to launch processes"
+        exit 1
+    fi
+    echo ""
+
+    # ── Step 2: Wait for vLLM to be ready ───────────────────────
+    echo "============================================"
+    echo "=== Waiting for vLLM to be ready ==="
+    echo "============================================"
+    if ! "${SCRIPT_DIR}/wait-for-servers.sh"; then
+        echo "vLLM failed to become ready"
+        exit 1
+    fi
+    echo ""
+fi
+
+# ── Step 3: Run the requested test ──────────────────────────
+echo "============================================"
+echo "=== Running test: ${TEST_NAME} ==="
+echo "============================================"
+
+case "$TEST_NAME" in
+    lm_eval)
+        exec_script="${SCRIPT_DIR}/run-lm-eval.sh"
+        ;;
+    hma_lm_eval_gemma4)
+        exec_script="${SCRIPT_DIR}/run-hma-lm-eval.sh"
+        ;;
+    hma_lm_eval_qwen3_5)
+        exec_script="${SCRIPT_DIR}/run-hma-lm-eval.sh"
+        ;;
+    vllm_bench)
+        exec_script="${SCRIPT_DIR}/run-vllm-bench.sh"
+        ;;
+    long_doc_qa)
+        exec_script="${SCRIPT_DIR}/run-long-doc-qa.sh"
+        ;;
+    long_doc_qa_l2)
+        exec_script="${SCRIPT_DIR}/run-long-doc-qa-l2.sh"
+        ;;
+    fault_tolerance)
+        exec_script="${SCRIPT_DIR}/run-fault-tolerance.sh"
+        ;;
+    deadlock)
+        exec_script="${SCRIPT_DIR}/run-deadlock.sh"
+        ;;
+    restart_recovery)
+        exec_script="${SCRIPT_DIR}/run-restart-recovery.sh"
+        ;;
+    cache_stats)
+        exec_script="${SCRIPT_DIR}/run-cache-stats.sh"
+        ;;
+    p2p)
+        exec_script="${SCRIPT_DIR}/run-p2p.sh"
+        ;;
+    http_api)
+        exec_script="${SCRIPT_DIR}/run-http-api.sh"
+        ;;
+    gds_smoke_test)
+        exec_script="${SCRIPT_DIR}/run-gds-smoke.sh"
+        ;;
+    *)
+        echo "Unknown test: $TEST_NAME"
+        echo "Valid tests: lm_eval, hma_lm_eval_gemma4, vllm_bench, long_doc_qa, long_doc_qa_l2, fault_tolerance, deadlock, restart_recovery, cache_stats, http_api, gds_smoke_test, p2p"
+        exit 1
+        ;;
+esac
+
+if ! "$exec_script"; then
+    echo "${TEST_NAME} test failed"
+    exit 1
+fi
+
+echo ""
+echo "============================================"
+echo "=== Test ${TEST_NAME} passed! ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/run-vllm-bench.sh b/.buildkite/k3_tests/multiprocess/scripts/run-vllm-bench.sh
new file mode 100755
index 0000000..5beea48
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/run-vllm-bench.sh
@@ -0,0 +1,276 @@
+#!/usr/bin/env bash
+# Run vllm bench serve test against both vLLM servers.
+# Compares performance between LMCache-enabled and baseline vLLM.
+# Adapted from the old Docker-based run-vllm-bench.sh.
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+NUM_PROMPTS="${NUM_PROMPTS:-50}"
+RANDOM_INPUT_LEN="${RANDOM_INPUT_LEN:-10000}"
+RANDOM_OUTPUT_LEN="${RANDOM_OUTPUT_LEN:-1}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+# Expected values
+EXPECTED_TOTAL_INPUT_TOKENS=$((NUM_PROMPTS * RANDOM_INPUT_LEN))
+EXPECTED_COMPLETED=$NUM_PROMPTS
+MAX_SLOWDOWN_PERCENT=5
+
+# Reproducible seed
+RANDOM_SEED="${RANDOM_SEED:-$(date +%s)}"
+
+# Output directory
+VLLM_BENCH_DIR="$RESULTS_DIR/vllm_bench"
+
+echo "=== vLLM Bench Serve Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port (with LMCache): $VLLM_PORT"
+echo "vLLM Baseline Port (without LMCache): $VLLM_BASELINE_PORT"
+echo "Number of prompts: $NUM_PROMPTS"
+echo "Random input length: $RANDOM_INPUT_LEN"
+echo "Random output length: $RANDOM_OUTPUT_LEN"
+echo "Results dir: $VLLM_BENCH_DIR"
+echo ""
+
+mkdir -p "$VLLM_BENCH_DIR"
+
+run_vllm_bench() {
+    local port="$1"
+    local result_filename="$2"
+    local description="$3"
+    local seed="$4"
+
+    echo "=== Running vllm bench serve ($description) ==="
+    echo "Port: $port, Seed: $seed"
+
+    vllm bench serve \
+        --seed "$seed" \
+        --port "$port" \
+        --model "$MODEL" \
+        --dataset-name random \
+        --random-input-len "$RANDOM_INPUT_LEN" \
+        --random-output-len "$RANDOM_OUTPUT_LEN" \
+        --num-prompts "$NUM_PROMPTS" \
+        --ignore-eos \
+        --backend openai-chat \
+        --endpoint /v1/chat/completions \
+        --result-dir "$VLLM_BENCH_DIR" \
+        --result-filename "$result_filename" \
+        --save-result
+
+    echo "$description benchmark completed"
+    echo ""
+}
+
+extract_json_field() {
+    local json_file="$1"
+    local field="$2"
+    python3 -c "
+import json
+with open('$json_file', 'r') as f:
+    data = json.load(f)
+print(data.get('$field', 'null'))
+"
+}
+
+verify_results() {
+    local lmcache_result="$VLLM_BENCH_DIR/lmcache.json"
+    local baseline_result="$VLLM_BENCH_DIR/baseline.json"
+
+    echo "=== Verifying benchmark results ==="
+
+    if [ ! -f "$lmcache_result" ]; then
+        echo "LMCache result file not found: $lmcache_result"
+        return 1
+    fi
+    if [ ! -f "$baseline_result" ]; then
+        echo "Baseline result file not found: $baseline_result"
+        return 1
+    fi
+
+    # Extract values
+    lmcache_total_input_tokens=$(extract_json_field "$lmcache_result" "total_input_tokens")
+    lmcache_completed=$(extract_json_field "$lmcache_result" "completed")
+    lmcache_throughput=$(extract_json_field "$lmcache_result" "total_token_throughput")
+
+    baseline_total_input_tokens=$(extract_json_field "$baseline_result" "total_input_tokens")
+    baseline_completed=$(extract_json_field "$baseline_result" "completed")
+    baseline_throughput=$(extract_json_field "$baseline_result" "total_token_throughput")
+
+    echo "=== LMCache Results ==="
+    echo "  total_input_tokens: $lmcache_total_input_tokens"
+    echo "  completed: $lmcache_completed"
+    echo "  total_token_throughput: $lmcache_throughput"
+    echo ""
+    echo "=== Baseline Results ==="
+    echo "  total_input_tokens: $baseline_total_input_tokens"
+    echo "  completed: $baseline_completed"
+    echo "  total_token_throughput: $baseline_throughput"
+    echo ""
+
+    local failed=0
+
+    echo "=== Verification ==="
+
+    # vLLM's random dataset decodes and re-encodes token sequences, which can
+    # drift slightly from the requested length (see RandomDataset in
+    # vllm/benchmarks/datasets.py). Allow 1% tolerance.
+    local token_tolerance=$((EXPECTED_TOTAL_INPUT_TOKENS / 100))
+
+    check_input_tokens() {
+        local label="$1"
+        local actual="$2"
+        local diff=$((actual - EXPECTED_TOTAL_INPUT_TOKENS))
+        local abs_diff=${diff#-}
+        if [ "$abs_diff" -le "$token_tolerance" ] 2>/dev/null; then
+            echo "$label total_input_tokens: $actual (expected: $EXPECTED_TOTAL_INPUT_TOKENS ±$token_tolerance) PASS"
+        else
+            echo "$label total_input_tokens: $actual (expected: $EXPECTED_TOTAL_INPUT_TOKENS ±$token_tolerance) FAIL"
+            failed=1
+        fi
+    }
+
+    check_input_tokens "LMCache" "$lmcache_total_input_tokens"
+    check_input_tokens "Baseline" "$baseline_total_input_tokens"
+
+    if [ "$lmcache_completed" -eq "$EXPECTED_COMPLETED" ] 2>/dev/null; then
+        echo "LMCache completed: $lmcache_completed (expected: $EXPECTED_COMPLETED) PASS"
+    else
+        echo "LMCache completed: $lmcache_completed (expected: $EXPECTED_COMPLETED) FAIL"
+        failed=1
+    fi
+
+    if [ "$baseline_completed" -eq "$EXPECTED_COMPLETED" ] 2>/dev/null; then
+        echo "Baseline completed: $baseline_completed (expected: $EXPECTED_COMPLETED) PASS"
+    else
+        echo "Baseline completed: $baseline_completed (expected: $EXPECTED_COMPLETED) FAIL"
+        failed=1
+    fi
+
+    # Throughput comparison
+    throughput_check=$(python3 -c "
+lmcache_tp = $lmcache_throughput
+baseline_tp = $baseline_throughput
+max_slowdown = $MAX_SLOWDOWN_PERCENT
+min_acceptable = baseline_tp * (1 - max_slowdown / 100.0)
+if baseline_tp > 0:
+    slowdown_pct = ((baseline_tp - lmcache_tp) / baseline_tp) * 100
+else:
+    slowdown_pct = 0
+if lmcache_tp >= min_acceptable:
+    print(f'PASS|{slowdown_pct:.2f}')
+else:
+    print(f'FAIL|{slowdown_pct:.2f}')
+")
+
+    throughput_status=$(echo "$throughput_check" | cut -d'|' -f1)
+    slowdown_pct=$(echo "$throughput_check" | cut -d'|' -f2)
+
+    if [ "$throughput_status" = "PASS" ]; then
+        echo "Throughput: LMCache is ${slowdown_pct}% slower (max allowed: ${MAX_SLOWDOWN_PERCENT}%) PASS"
+    else
+        echo "Throughput: LMCache is ${slowdown_pct}% slower (max allowed: ${MAX_SLOWDOWN_PERCENT}%) FAIL"
+        failed=1
+    fi
+
+    # Sanity check: on a random (no-reuse) workload, LMCache should NOT be
+    # significantly faster than baseline. If it is, the benchmark setup is
+    # asymmetric and the results are unreliable as a regression test.
+    local max_speedup_pct=10
+    speedup_check=$(python3 -c "
+lmcache_tp = $lmcache_throughput
+baseline_tp = $baseline_throughput
+if baseline_tp > 0:
+    speedup_pct = ((lmcache_tp - baseline_tp) / baseline_tp) * 100
+else:
+    speedup_pct = 0
+if speedup_pct > $max_speedup_pct:
+    print(f'WARN|{speedup_pct:.2f}')
+else:
+    print(f'OK|{speedup_pct:.2f}')
+")
+
+    local speedup_status speedup_pct
+    speedup_status=$(echo "$speedup_check" | cut -d'|' -f1)
+    speedup_pct=$(echo "$speedup_check" | cut -d'|' -f2)
+
+    if [ "$speedup_status" = "WARN" ]; then
+        echo "WARNING: LMCache is ${speedup_pct}% faster than baseline on random workload (max expected: ${max_speedup_pct}%)"
+        echo "This suggests a measurement asymmetry, not a real cache benefit."
+        failed=1
+    else
+        echo "Speedup sanity check: LMCache is ${speedup_pct}% faster (max expected: ${max_speedup_pct}%) OK"
+    fi
+
+    echo ""
+    return "$failed"
+}
+
+warmup_server() {
+    local port="$1"
+    local description="$2"
+    local num_warmup="${3:-3}"
+
+    echo "=== Warming up $description (port $port) ==="
+    # Send a few chat completion requests to warm up the tokenizer,
+    # chat template (Jinja2), and engine pipeline. Without this, the
+    # first-ever batch of requests incurs ~25s of cold-start overhead
+    # (BPE compilation, template compilation, etc.) which skews the
+    # benchmark since lm-eval (Step 3) only warms the LMCache server.
+    for i in $(seq 1 "$num_warmup"); do
+        curl -s -X POST "http://localhost:${port}/v1/chat/completions" \
+            -H "Content-Type: application/json" \
+            -d "{
+                \"model\": \"${MODEL}\",
+                \"messages\": [{\"role\": \"user\", \"content\": \"Warmup request ${i}. The quick brown fox jumps over the lazy dog.\"}],
+                \"max_tokens\": 1
+            }" > /dev/null 2>&1
+    done
+    echo "$description warmup complete"
+}
+
+echo "Using random seed: $RANDOM_SEED"
+echo ""
+
+# Warm up both servers so tokenizer/template compilation does not
+# skew the benchmark. See THROUGHPUT_FIX_PROPOSAL.md for details.
+echo "============================================"
+echo "=== Warming up both servers ==="
+echo "============================================"
+warmup_server "$VLLM_PORT" "vLLM with LMCache"
+warmup_server "$VLLM_BASELINE_PORT" "vLLM baseline"
+echo ""
+
+# Baseline first
+echo "============================================"
+echo "=== Benchmark: Baseline vLLM (without LMCache) ==="
+echo "============================================"
+run_vllm_bench "$VLLM_BASELINE_PORT" "baseline.json" "Baseline vLLM" "$RANDOM_SEED"
+
+# LMCache
+echo "============================================"
+echo "=== Benchmark: vLLM with LMCache ==="
+echo "============================================"
+run_vllm_bench "$VLLM_PORT" "lmcache.json" "vLLM with LMCache" "$RANDOM_SEED"
+
+# Verify
+echo "============================================"
+echo "=== Verifying benchmark results ==="
+echo "============================================"
+if ! verify_results; then
+    echo "Verification failed"
+    exit 1
+fi
+
+echo "============================================"
+echo "=== vLLM Bench test completed ==="
+echo "============================================"
diff --git a/.buildkite/k3_tests/multiprocess/scripts/wait-for-servers.sh b/.buildkite/k3_tests/multiprocess/scripts/wait-for-servers.sh
new file mode 100755
index 0000000..429e13e
--- /dev/null
+++ b/.buildkite/k3_tests/multiprocess/scripts/wait-for-servers.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Wait for vLLM servers to be ready (native processes, no Docker).
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
+
+source "${REPO_ROOT}/.buildkite/k3_tests/common_scripts/helpers.sh"
+
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MAX_WAIT_SECONDS="${MAX_WAIT_SECONDS:-600}"
+BUILD_ID="${BUILD_ID:-local_$$}"
+
+# Wait for a vLLM server with health check
+wait_for_vllm_server() {
+    local port="$1"
+    local description="$2"
+    local logfile="$3"
+
+    echo "=== Waiting for $description to be ready ==="
+    echo "Port: $port, Max wait: ${MAX_WAIT_SECONDS}s"
+
+    local start_time end_time
+    start_time=$(date +%s)
+    end_time=$((start_time + MAX_WAIT_SECONDS))
+
+    while true; do
+        local current_time elapsed
+        current_time=$(date +%s)
+        elapsed=$((current_time - start_time))
+
+        if [ "$current_time" -ge "$end_time" ]; then
+            echo "Timeout: $description did not become ready within ${MAX_WAIT_SECONDS}s"
+            echo ""
+            echo "=== $description log (last 100 lines) ==="
+            tail -100 "$logfile" 2>/dev/null || true
+            return 1
+        fi
+
+        if curl -sf "http://localhost:${port}/health" > /dev/null 2>&1; then
+            echo "$description is ready! (took ${elapsed}s)"
+            return 0
+        fi
+
+        if curl -sf "http://localhost:${port}/v1/models" > /dev/null 2>&1; then
+            echo "$description is ready! (took ${elapsed}s)"
+            return 0
+        fi
+
+        echo "Waiting for $description... (${elapsed}s elapsed)"
+        sleep 5
+    done
+}
+
+# Wait for both servers (they start simultaneously)
+if ! wait_for_vllm_server "$VLLM_PORT" "vLLM with LMCache" \
+        "/tmp/build_${BUILD_ID}_vllm.log"; then
+    exit 1
+fi
+
+# The baseline server only exists for 2-GPU tests; 1-GPU tests set
+# LAUNCH_BASELINE=false in launch-processes.sh and never start it.
+if [[ "${LAUNCH_BASELINE:-true}" == "true" ]]; then
+    if ! wait_for_vllm_server "$VLLM_BASELINE_PORT" "vLLM baseline (without LMCache)" \
+            "/tmp/build_${BUILD_ID}_vllm_baseline.log"; then
+        exit 1
+    fi
+fi
+
+echo ""
+echo "=== All vLLM servers are ready ==="
diff --git a/.buildkite/k3_tests/sglang/BK_WEB_SETUP.md b/.buildkite/k3_tests/sglang/BK_WEB_SETUP.md
new file mode 100644
index 0000000..26fc9fe
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/BK_WEB_SETUP.md
@@ -0,0 +1,16 @@
+# Buildkite Web UI Setup: SGLang + LMCache MP
+
+**Steps editor**: paste contents of `buildkite-pipeline.yml` (fill in `HF_TOKEN`).
+
+**GitHub trigger settings**:
+- Filter (the SGLang MP adapter's real dependency surface spans most of `lmcache/`):
+  - `lmcache/**`
+  - `.buildkite/k3_tests/sglang/**`
+- Skip queued / cancel running branch builds: Yes
+
+Two GPU jobs (correctness + performance), ~5 min each — lightweight enough for a required PR status check on changes that touch the MP integration.
+
+> Builds whose only changes are docs/`*.md`/`LICENSE`/`.github/**` auto-pass
+> via the [path filter](../README.md#path-based-skip-auto-pass-on-docs-only-changes).
+> Changes under `.buildkite/` always run. Add the `force-ci` label to a PR to
+> bypass.
diff --git a/.buildkite/k3_tests/sglang/buildkite-pipeline.yml b/.buildkite/k3_tests/sglang/buildkite-pipeline.yml
new file mode 100644
index 0000000..06aff4b
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/buildkite-pipeline.yml
@@ -0,0 +1,12 @@
+# Paste this into the Buildkite pipeline's "Steps" editor for the
+# SGLang + LMCache MP integration test. Uploads the real pipeline
+# definition from the repo.
+agents:
+  queue: "k8s"
+
+env:
+  HF_TOKEN: ""  # set your HuggingFace token here (needed for gated model access)
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/sglang/pipeline.yml
diff --git a/.buildkite/k3_tests/sglang/pipeline.yml b/.buildkite/k3_tests/sglang/pipeline.yml
new file mode 100644
index 0000000..c965db2
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/pipeline.yml
@@ -0,0 +1,54 @@
+# SGLang + LMCache MP integration tests.
+# 1) Correctness: LMCache does not change output, and is actually exercised.
+# 2) Performance: LMCache makes TTFT smaller.
+
+steps:
+  - label: ":test_tube: SGLang+LMCache — Correctness"
+    command: .buildkite/k3_tests/sglang/run.sh correctness
+    timeout_in_minutes: 15
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources:
+                  limits:
+                    nvidia.com/gpu: "1"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "*.log"
+      - "*.json"
+
+  - label: ":zap: SGLang+LMCache — Performance"
+    command: .buildkite/k3_tests/sglang/run.sh perf
+    timeout_in_minutes: 15
+    retry:
+      automatic:
+        - exit_status: -1
+          limit: 2
+        - exit_status: 1
+          limit: 2
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                resources:
+                  limits:
+                    nvidia.com/gpu: "1"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "*.log"
+      - "*.json"
diff --git a/.buildkite/k3_tests/sglang/run.sh b/.buildkite/k3_tests/sglang/run.sh
new file mode 100755
index 0000000..d656872
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/run.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# SGLang + LMCache MP integration test entrypoint for K8s pods.
+# Sources the SGLang-specific env setup, then dispatches to scripts/.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+cd "${REPO_ROOT}"
+
+source .buildkite/k3_harness/setup-sglang-env.sh
+
+chmod +x "${SCRIPT_DIR}"/scripts/*.sh
+
+case "${1:-}" in
+    correctness)
+        exec bash "${SCRIPT_DIR}/scripts/run-correctness.sh"
+        ;;
+    perf)
+        exec bash "${SCRIPT_DIR}/scripts/run-perf.sh"
+        ;;
+    *)
+        echo "Usage: $0 {correctness|perf}" >&2
+        exit 2
+        ;;
+esac
diff --git a/.buildkite/k3_tests/sglang/scripts/common.sh b/.buildkite/k3_tests/sglang/scripts/common.sh
new file mode 100755
index 0000000..734fa1d
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/scripts/common.sh
@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# Shared helpers for SGLang + LMCache MP CI tests.
+
+MODEL="${MODEL:-Qwen/Qwen2.5-7B-Instruct}"
+DAEMON_PORT="${DAEMON_PORT:-6200}"
+DAEMON_HTTP_PORT="${DAEMON_HTTP_PORT:-7200}"
+LMC_CONFIG_FILE="${LMC_CONFIG_FILE:-/tmp/lmcache_mp_ci.yaml}"
+
+DAEMON_PID=""
+SGLANG_PID=""
+
+cleanup_all() {
+    if [[ -n "${SGLANG_PID}" ]]; then
+        kill -9 "${SGLANG_PID}" 2>/dev/null || true
+        pkill -9 -P "${SGLANG_PID}" 2>/dev/null || true
+        pkill -9 -f "sglang::scheduler" 2>/dev/null || true
+        wait "${SGLANG_PID}" 2>/dev/null || true
+        SGLANG_PID=""
+    fi
+    if [[ -n "${DAEMON_PID}" ]]; then
+        kill -9 "${DAEMON_PID}" 2>/dev/null || true
+        wait "${DAEMON_PID}" 2>/dev/null || true
+        DAEMON_PID=""
+    fi
+    sleep 2
+}
+
+launch_daemon() {
+    local log_file="$1"
+    cat > "${LMC_CONFIG_FILE}" <<EOF
+mp_host: 127.0.0.1
+mp_port: ${DAEMON_PORT}
+EOF
+    lmcache server \
+        --host 127.0.0.1 --port "${DAEMON_PORT}" --http-port "${DAEMON_HTTP_PORT}" \
+        --chunk-size 256 --l1-size-gb 20 --eviction-policy LRU \
+        > "${log_file}" 2>&1 &
+    DAEMON_PID=$!
+    for ((i = 0; i < 60; i++)); do
+        if grep -q "ZMQ cache server is running" "${log_file}" 2>/dev/null; then
+            echo "  daemon ready (${i}s, log=${log_file})"
+            return 0
+        fi
+        sleep 1
+    done
+    echo "FAIL: daemon did not start within 60s" >&2
+    tail -n 200 "${log_file}" >&2
+    return 1
+}
+
+# Launch SGLang. $1=port, $2=log file, $3="lmcache" or "no-lmcache".
+launch_sglang() {
+    local port="$1" log_file="$2" mode="$3"
+    local lmcache_args=()
+    if [[ "${mode}" == "lmcache" ]]; then
+        lmcache_args=(--enable-lmcache --lmcache-config-file "${LMC_CONFIG_FILE}")
+    fi
+    python -m sglang.launch_server \
+        --model-path "${MODEL}" \
+        --host 127.0.0.1 --port "${port}" \
+        "${lmcache_args[@]}" \
+        > "${log_file}" 2>&1 &
+    SGLANG_PID=$!
+    wait_sglang_ready "${port}" "${log_file}"
+}
+
+wait_sglang_ready() {
+    local port="$1" log_file="$2" timeout="${3:-240}"
+    for ((i = 0; i < timeout; i++)); do
+        if curl -sf "http://127.0.0.1:${port}/health" >/dev/null 2>&1; then
+            echo "  sglang ready on port ${port} (${i}s, mode=${mode:-?}, log=${log_file})"
+            return 0
+        fi
+        if grep -q "SIGQUIT received\|FATAL\|RuntimeError" "${log_file}" 2>/dev/null; then
+            echo "FAIL: SGLang crashed during startup" >&2
+            tail -n 200 "${log_file}" >&2
+            return 1
+        fi
+        sleep 1
+    done
+    echo "FAIL: SGLang did not become ready on port ${port} within ${timeout}s" >&2
+    tail -n 200 "${log_file}" >&2
+    return 1
+}
+
+# Non-streaming chat completion. Args: port, prompt, max_tokens.
+chat_completion() {
+    local port="$1" prompt="$2" max_tokens="${3:-64}"
+    curl -sf "http://127.0.0.1:${port}/v1/chat/completions" \
+        -H "Content-Type: application/json" \
+        -d "$(python3 -c "
+import json, sys
+print(json.dumps({
+    'model': '${MODEL}',
+    'messages': [{'role': 'user', 'content': sys.argv[1]}],
+    'max_tokens': int(sys.argv[2]),
+    'temperature': 0.0,
+    'stream': False,
+}))" "${prompt}" "${max_tokens}")" \
+        | python3 -c "
+import json, sys
+resp = json.load(sys.stdin)
+print(resp['choices'][0]['message']['content'], end='')
+"
+}
+
+# Sum LMCache L1 chunk reads from the daemon's /metrics; 0 if unreachable.
+count_retrievals() {
+    local val
+    val=$( { curl -sf --max-time 3 "http://127.0.0.1:${DAEMON_HTTP_PORT}/metrics" 2>/dev/null || true; } \
+        | awk '/^lmcache_mp_l1_read_chunks_total[ {]/ { sum += $NF } END { printf "%d", sum + 0 }')
+    echo "${val:-0}"
+}
+
+# Two distinct ~2500-token prompts for run-correctness.sh.
+generate_prompt() {
+    local variant="${1:-a}"
+    python3 -c "
+import sys
+sentences = {
+    'a': 'The quick brown fox jumps over the lazy dog while a curious cat watches from the windowsill on a quiet afternoon in early autumn. ',
+    'b': 'An old man walks slowly along a foggy riverside path at dawn carrying a fishing rod and dreaming of his grandchildren far away. ',
+}
+print(sentences[sys.argv[1]] * 80 + 'Summarize the scene above in one short sentence.')
+" "${variant}"
+}
+
+# Run lmcache bench engine + long-doc-qa; echo mean TTFT in seconds. Pool > HBM forces LMCache hits on each doc's 2nd query.
+run_long_doc_qa_ttft() {
+    local port="$1"
+    local outdir
+    outdir="$(mktemp -d -t lmc-bench-XXXXXX)"
+    lmcache bench engine \
+        --engine-url "http://127.0.0.1:${port}" \
+        --model "${MODEL}" \
+        --workload long-doc-qa \
+        --ldqa-document-length 10000 \
+        --ldqa-query-per-document 2 \
+        --ldqa-shuffle-policy tile \
+        --tokens-per-gb-kvcache 17500 --kv-cache-volume 15 \
+        --json --no-csv --no-interactive --quiet \
+        --output-dir "${outdir}" > "perf-bench-${port}.log" 2>&1
+    python3 -c "
+import json
+print(json.load(open('${outdir}/bench_summary.json'))['results']['mean_ttft_ms'] / 1000)
+"
+}
diff --git a/.buildkite/k3_tests/sglang/scripts/run-correctness.sh b/.buildkite/k3_tests/sglang/scripts/run-correctness.sh
new file mode 100755
index 0000000..4a6bd2e
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/scripts/run-correctness.sh
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Correctness: LMCache must not change the output, and must be exercised. A → B → flush_cache → A on the LMCache server: A populates LMCache, B is a separate request, /flush_cache clears SGLang's radix (but not LMCache), so the second A is a radix miss / LMCache hit. The cache-hit output is diffed against a no-LMCache reference run. Servers are launched sequentially (kill between phases) so two SGLang processes don't fight for GPU memory.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+
+DAEMON_LOG="correctness-daemon.log"
+LMC_SGL_LOG="correctness-sgl-lmc.log"
+NO_SGL_LOG="correctness-sgl-no.log"
+PORT_LMC=30200
+PORT_NO=30201
+
+trap cleanup_all EXIT
+
+echo "--- :rocket: Start daemon"
+launch_daemon "${DAEMON_LOG}"
+
+PROMPT_A="$(generate_prompt a)"
+PROMPT_B="$(generate_prompt b)"
+
+echo "--- :test_tube: Launch SGLang+LMCache; drive A → B → flush_cache → A"
+launch_sglang "${PORT_LMC}" "${LMC_SGL_LOG}" "lmcache"
+chat_completion "${PORT_LMC}" "${PROMPT_A}" 64 > /tmp/lmc_run1_A.txt
+chat_completion "${PORT_LMC}" "${PROMPT_B}" 64 > /tmp/lmc_run2_B.txt
+curl -sf -X POST "http://127.0.0.1:${PORT_LMC}/flush_cache" >/dev/null
+RETRIEVALS_BEFORE=$(count_retrievals)
+chat_completion "${PORT_LMC}" "${PROMPT_A}" 64 > /tmp/lmc_out.txt
+RETRIEVALS_AFTER=$(count_retrievals)
+RETRIEVAL_DELTA=$((RETRIEVALS_AFTER - RETRIEVALS_BEFORE))
+echo "  daemon retrieval delta on the cache-hit call: ${RETRIEVAL_DELTA}"
+
+echo "--- :recycle: Kill LMCache SGLang, relaunch without LMCache"
+kill -9 "${SGLANG_PID}" 2>/dev/null || true
+pkill -9 -f "sglang::scheduler" 2>/dev/null || true
+wait "${SGLANG_PID}" 2>/dev/null || true
+SGLANG_PID=""
+sleep 3
+launch_sglang "${PORT_NO}" "${NO_SGL_LOG}" "no-lmcache"
+
+echo "--- :mag: Reference call on the no-LMCache server"
+chat_completion "${PORT_NO}" "${PROMPT_A}" 64 > /tmp/no_out.txt
+
+echo "+++ :scales: Verdict"
+if [[ "${RETRIEVAL_DELTA}" -lt 1 ]]; then
+    echo "FAIL: LMCache was not exercised (retrieval delta ${RETRIEVAL_DELTA} < 1)" >&2
+    tail -n 60 "${DAEMON_LOG}" >&2
+    exit 1
+fi
+if ! diff -u /tmp/no_out.txt /tmp/lmc_out.txt; then
+    echo "FAIL: LMCache changed the output" >&2
+    exit 1
+fi
+echo "PASS — outputs match AND LMCache served ${RETRIEVAL_DELTA} retrieval(s) on the cache-hit call."
diff --git a/.buildkite/k3_tests/sglang/scripts/run-perf.sh b/.buildkite/k3_tests/sglang/scripts/run-perf.sh
new file mode 100755
index 0000000..dd1c27d
--- /dev/null
+++ b/.buildkite/k3_tests/sglang/scripts/run-perf.sh
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Performance: query-round TTFT with LMCache must be lower than without.
+# Phase A: launch SGLang + LMCache → bench → record TTFT and verify
+# the daemon log shows RETRIEVE traffic. Phase B: relaunch SGLang
+# without LMCache → same bench → record TTFT.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "${SCRIPT_DIR}/common.sh"
+trap cleanup_all EXIT
+
+DAEMON_LOG="perf-daemon.log"
+LMC_LOG="perf-sgl-lmc.log"
+NO_LOG="perf-sgl-no.log"
+PORT_LMC=30200
+PORT_NO=30201
+
+echo "--- :rocket: Phase A — start daemon + LMCache-enabled SGLang"
+launch_daemon "${DAEMON_LOG}"
+launch_sglang "${PORT_LMC}" "${LMC_LOG}" "lmcache"
+
+echo "--- :stopwatch: Phase A — bench, record mean TTFT"
+RETRIEVALS_BEFORE=$(count_retrievals)
+TTFT_LMC=$(run_long_doc_qa_ttft "${PORT_LMC}")
+RETRIEVALS_AFTER=$(count_retrievals)
+RETRIEVAL_DELTA=$((RETRIEVALS_AFTER - RETRIEVALS_BEFORE))
+echo "  ttft_with_lmcache = ${TTFT_LMC}s, retrieval delta = ${RETRIEVAL_DELTA}"
+
+echo "--- :recycle: Phase B — relaunch SGLang without LMCache"
+kill -9 "${SGLANG_PID}" 2>/dev/null || true
+pkill -9 -f "sglang::scheduler" 2>/dev/null || true
+wait "${SGLANG_PID}" 2>/dev/null || true
+SGLANG_PID=""
+sleep 3
+launch_sglang "${PORT_NO}" "${NO_LOG}" "no-lmcache"
+
+echo "--- :stopwatch: Phase B — bench, record mean TTFT"
+TTFT_NO=$(run_long_doc_qa_ttft "${PORT_NO}")
+echo "  ttft_without_lmcache = ${TTFT_NO}s"
+
+echo "+++ :scales: Verdict"
+echo "  ttft_with_lmcache    = ${TTFT_LMC}s"
+echo "  ttft_without_lmcache = ${TTFT_NO}s"
+echo "  retrieval delta      = ${RETRIEVAL_DELTA}"
+
+if [[ "${RETRIEVAL_DELTA}" -lt 1 ]]; then
+    echo "FAIL: LMCache was not exercised (retrieval delta ${RETRIEVAL_DELTA} < 1)" >&2
+    tail -n 60 "${DAEMON_LOG}" >&2
+    exit 1
+fi
+if ! python3 -c "import sys; sys.exit(0 if ${TTFT_LMC} < ${TTFT_NO} else 1)"; then
+    echo "FAIL: LMCache did not improve query-round TTFT (${TTFT_LMC}s >= ${TTFT_NO}s)" >&2
+    exit 1
+fi
+echo "PASS — ttft_with_lmcache (${TTFT_LMC}s) < ttft_without_lmcache (${TTFT_NO}s); ${RETRIEVAL_DELTA} retrieval(s)."
diff --git a/.buildkite/k3_tests/unit/buildkite-pipeline.yml b/.buildkite/k3_tests/unit/buildkite-pipeline.yml
new file mode 100644
index 0000000..830b8a0
--- /dev/null
+++ b/.buildkite/k3_tests/unit/buildkite-pipeline.yml
@@ -0,0 +1,13 @@
+# Paste this into the Buildkite pipeline's "Steps" editor.
+# It uploads the real pipeline definition from the repo.
+agents:
+  queue: "k3-h200-local"
+
+env:
+  # Optional: unit tests run without it. Setting it unlocks one extra test
+  # (test_segment_token_database) that's gated on HF credentials.
+  HF_TOKEN: ""
+
+steps:
+  - label: ":pipeline: Upload pipeline"
+    command: bash .buildkite/k3_tests/common_scripts/upload-pipeline.sh .buildkite/k3_tests/unit/pipeline.yml
diff --git a/.buildkite/k3_tests/unit/pipeline.yml b/.buildkite/k3_tests/unit/pipeline.yml
new file mode 100644
index 0000000..cd1cad2
--- /dev/null
+++ b/.buildkite/k3_tests/unit/pipeline.yml
@@ -0,0 +1,44 @@
+# Unit tests — runs pytest with coverage against LMCache source.
+# No vLLM required; uses setup-lmcache-only-env.sh for a lighter install.
+
+steps:
+  - label: ":test_tube: Unit Tests"
+    command: .buildkite/k3_tests/unit/run.sh
+    timeout_in_minutes: 60
+    agents: { queue: "k8s" }
+    plugins:
+      - kubernetes:
+          podSpec:
+            containers:
+              - name: container-0
+                image: lmcache/ci-base:latest
+                imagePullPolicy: Never
+                env:
+                  - { name: CUDA_LAUNCH_BLOCKING, value: "1" }
+                resources:
+                  requests:
+                    cpu: "32"
+                    memory: "96Gi"
+                  limits:
+                    nvidia.com/gpu: "1"
+                    cpu: "64"
+                    memory: "200Gi"
+                volumeMounts:
+                  - { name: hf-cache, mountPath: /root/.cache/huggingface }
+                  # K8s defaults /dev/shm to 64 MiB, which causes SIGBUS in
+                  # tests/v1/shm_allocator (allocates 5 GiB via SharedMemory).
+                  # Mount a 16 GiB tmpfs to give shm tests headroom.
+                  - { name: dshm, mountPath: /dev/shm }
+                  # GDS-capable scratch dir on the host's local NVMe. Direct
+                  # hostPath (no subPath) — K8s' subPath bind-mount breaks
+                  # cuFile's fs-type detection. run.sh creates a per-build
+                  # subdir here and exposes it via LMCACHE_TEST_TMPDIR.
+                  - { name: scratch, mountPath: /scratch }
+            volumes:
+              - { name: hf-cache, hostPath: { path: /data/huggingface, type: DirectoryOrCreate } }
+              - { name: dshm, emptyDir: { medium: Memory, sizeLimit: 16Gi } }
+              - { name: scratch, hostPath: { path: /data/gds-scratch, type: DirectoryOrCreate } }
+    artifact_paths:
+      - "durations/test.html"
+      - "coverage-test.xml"
+      - "coverage-test/**/*"
diff --git a/.buildkite/k3_tests/unit/run.sh b/.buildkite/k3_tests/unit/run.sh
new file mode 100755
index 0000000..052ed59
--- /dev/null
+++ b/.buildkite/k3_tests/unit/run.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Unit test entrypoint for K8s pods.
+# Installs LMCache (no vLLM) + test deps, then runs pytest with coverage.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+cd "${REPO_ROOT}"
+
+# ── Per-build scratch dir ────────────────────────────────────
+# /scratch is a shared hostPath mount (see pipeline.yml) backed by ext4/xfs
+# on local NVMe — the only place GDS (cuFile) works in this pod (overlayfs
+# /tmp fails with CU_FILE_IO_NOT_SUPPORTED). Give this build its own
+# subdirectory so concurrent pods don't collide, and clean it up on exit.
+# Direct subdir rather than K8s subPathExpr since the latter's bind mount
+# breaks cuFile's fs-type detection.
+#
+# LMCACHE_TEST_TMPDIR is consumed by the handful of test files that need
+# GDS-capable scratch (test_gds_backend, test_cache_engine, the xpu
+# benchmarks). Leaving TMPDIR unset means /tmp stays pod-internal overlay
+# for pip/uv/build caches — those don't need direct I/O.
+BUILD_TAG="${BUILDKITE_BUILD_ID:-manual-$$}"
+export LMCACHE_TEST_TMPDIR="/scratch/bk-${BUILD_TAG}"
+mkdir -p "${LMCACHE_TEST_TMPDIR}"
+trap 'rm -rf "${LMCACHE_TEST_TMPDIR}" 2>/dev/null || true' EXIT
+
+# ── Environment setup ────────────────────────────────────────
+source .buildkite/k3_harness/setup-lmcache-only-env.sh
+uv pip install -r requirements/test.txt
+
+# ── Run unit tests with coverage ─────────────────────────────
+LMCACHE_TRACK_USAGE="false" \
+pytest --maxfail=1 --cov=lmcache \
+    --cov-report term --cov-report=html:coverage-test \
+    --cov-report=xml:coverage-test.xml --html=durations/test.html \
+    --ignore=tests/disagg --ignore=tests/v1/test_pos_kernels.py \
+    --ignore=tests/skipped \
+    --ignore=tests/v1/storage_backend/test_eic.py
+
+cat << EOF | buildkite-agent annotate --style "info"
+  Read the <a href="artifact://coverage-test/index.html">uploaded coverage report</a>
+EOF
diff --git a/.buildkite/operator/integration/pipeline.yaml b/.buildkite/operator/integration/pipeline.yaml
new file mode 100644
index 0000000..f8ef73a
--- /dev/null
+++ b/.buildkite/operator/integration/pipeline.yaml
@@ -0,0 +1,28 @@
+steps:
+  - label: "Detect operator changes"
+    key: "operator_detect_changes"
+    command: |
+      set -eu
+
+      BASE_REF="origin/dev"
+
+      if ! git fetch --quiet origin dev 2>/dev/null; then
+        echo "WARN: could not fetch $$BASE_REF; running tests defensively."
+        buildkite-agent pipeline upload .buildkite/operator/integration/tests.yaml
+        exit 0
+      fi
+
+      if ! CHANGED=$(git diff --name-only "$$BASE_REF...HEAD" -- operator/ .buildkite/operator/ 2>/dev/null); then
+        echo "WARN: git diff failed; running tests defensively."
+        buildkite-agent pipeline upload .buildkite/operator/integration/tests.yaml
+        exit 0
+      fi
+
+      if [ -z "$$CHANGED" ]; then
+        echo "No operator or operator-pipeline changes vs $$BASE_REF; skipping integration tests."
+        exit 0
+      fi
+
+      echo "Operator changes detected:"
+      echo "$$CHANGED"
+      buildkite-agent pipeline upload .buildkite/operator/integration/tests.yaml
diff --git a/.buildkite/operator/integration/tests.yaml b/.buildkite/operator/integration/tests.yaml
new file mode 100644
index 0000000..a96681c
--- /dev/null
+++ b/.buildkite/operator/integration/tests.yaml
@@ -0,0 +1,38 @@
+# The CacheBlend integration spec (cacheblend_integration_smoke_test.go) pulls a
+# PRIVATE payload image. Set these as pipeline secrets in the Buildkite UI (same
+# mechanism as HF_TOKEN); they propagate through `make test-e2e-gpu-kind` ->
+# `go test` -> the spec via os.Getenv. Do NOT hardcode the token here.
+#   CACHEBLEND_REGISTRY_USER   docker registry username (e.g. Docker Hub user)
+#   CACHEBLEND_REGISTRY_TOKEN  docker registry read-only PAT
+#   CACHEBLEND_REGISTRY_SERVER optional, default https://index.docker.io/v1/
+# When USER/TOKEN are unset the spec Skips, so this build stays green without them.
+env:
+  GPU_KIND_CLUSTER: "operator-test-e2e-gpu-${BUILDKITE_BUILD_NUMBER}"
+
+steps:
+  - label: "Operator Integration: test-e2e-gpu-kind"
+    key: "operator_test_e2e_gpu_kind"
+    timeout_in_minutes: 90
+    command: |
+      echo $$PWD # for debugging
+
+      cd operator
+      make test-e2e-gpu-kind
+
+  - label: "Cleanup Kind cluster"
+    key: "operator_cleanup_kind"
+    depends_on: "operator_test_e2e_gpu_kind"
+    allow_dependency_failure: true
+    timeout_in_minutes: 10
+    command: |
+      cd operator
+      make cleanup-test-e2e-gpu-kind
+
+  - label: "Cleanup workspace"
+    depends_on: "operator_cleanup_kind"
+    allow_dependency_failure: true
+    command: |
+      export TARGET="$$PWD"
+      echo "Deleting current workspace $$TARGET"
+      cd /
+      rm -rf "$$TARGET" || true
diff --git a/.buildkite/pipeline.yml b/.buildkite/pipeline.yml
new file mode 100644
index 0000000..505df83
--- /dev/null
+++ b/.buildkite/pipeline.yml
@@ -0,0 +1,60 @@
+env:
+  PATH: "$HOME/.local/bin:$PATH"
+
+steps:
+  - label: "Unit Tests"
+    key: "unit_tests"
+    timeout_in_minutes: 60
+    command: |
+      echo $PWD # for debugging
+
+      uv venv --python 3.12 .venv-$BUILDKITE_BUILD_ID
+      source .venv-$BUILDKITE_BUILD_ID/bin/activate
+      uv pip install --upgrade pip setuptools wheel
+
+      if command -v nvidia-smi >/dev/null 2>&1; then
+        source .buildkite/scripts/pick-free-gpu.sh 18000
+        export CUDA_LAUNCH_BLOCKING=1
+        # Pin torch to a version compatible with the CI machine's CUDA 12.x driver
+        uv pip install "torch>=2.6.0,<2.11.0"
+      else
+        source .buildkite/scripts/pick-free-gpu-amd.sh 18000
+        export AMD_SERIALIZE_KERNEL=1
+        export PYTORCH_ROCM_ARCH="gfx942"
+        export TORCH_DONT_CHECK_COMPILER_ABI=1
+        export CXX=hipcc
+        export BUILD_WITH_HIP=1
+        uv pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.0
+        uv pip install -r requirements/rocm_core.txt
+      fi
+
+      uv pip install -r requirements/common.txt
+      uv pip install -r requirements/test.txt
+      uv pip install -e . --no-build-isolation
+      uv pip freeze
+
+      LMCACHE_TRACK_USAGE="false" \
+      pytest --maxfail=1 --cov=lmcache \
+        --cov-report term --cov-report=html:coverage-test \
+        --cov-report=xml:coverage-test.xml --html=durations/test.html \
+        --ignore=tests/disagg --ignore=tests/v1/test_pos_kernels.py \
+        --ignore=tests/v1/test_nixl_batched_contains.py \
+        --ignore=tests/v1/test_device_id_race.py \
+        --ignore=tests/v1/test_nixl_multipath.py \
+        --ignore=tests/skipped \
+        --ignore=tests/v1/storage_backend/test_eic.py
+
+
+      cat << EOF | buildkite-agent annotate --style "info"
+        Read the <a href="artifact://coverage-test/index.html">uploaded coverage report</a>
+      EOF
+
+      export TARGET="$PWD"
+      echo "Deleting current workspace $TARGET"
+      cd /
+      sudo rm -rf "$TARGET"
+
+    artifact_paths:
+      - "durations/test.html"
+      - "coverage-test.xml"
+      - "coverage-test/**/*"      
diff --git a/.buildkite/pipelines/clean.yml b/.buildkite/pipelines/clean.yml
new file mode 100644
index 0000000..3208df9
--- /dev/null
+++ b/.buildkite/pipelines/clean.yml
@@ -0,0 +1,6 @@
+steps:  
+  - label: ":wastebasket: Kill all"
+    key: "clean"
+    command: |
+      bash .buildkite/scripts/clean.sh
+      sudo rm -rf /var/cache/buildkite/*.lock
\ No newline at end of file
diff --git a/.buildkite/pipelines/comprehensive-tests.yml b/.buildkite/pipelines/comprehensive-tests.yml
new file mode 100644
index 0000000..6249baf
--- /dev/null
+++ b/.buildkite/pipelines/comprehensive-tests.yml
@@ -0,0 +1,31 @@
+env:
+  DOCKER_BUILDKIT: 1
+
+steps:
+  - label: ":compression: Comprehensive Tests"
+    key: "test"
+    timeout_in_minutes: 60
+    commands:
+      - .buildkite/scripts/should-run-comprehensive.sh || exit 0 # Skip comprehensive tests for safe-path-only PRs.
+      - chmod +x .buildkite/scripts/vllm-integration-tests.sh
+      - |
+        # Ensure artifact is created even if test crashes
+        create_artifact() {
+          if ls /tmp/build_${BUILDKITE_BUILD_ID}_*.log 1>/dev/null 2>&1; then
+            cat /tmp/build_${BUILDKITE_BUILD_ID}_*.log > build_${BUILDKITE_BUILD_ID}.log 2>/dev/null || true
+          else
+            echo "No log files found for build ${BUILDKITE_BUILD_ID}" > build_${BUILDKITE_BUILD_ID}.log
+          fi
+        }
+        trap 'test_exit_code=$?; create_artifact; exit $test_exit_code' EXIT INT TERM
+        BUILD_ID=${BUILDKITE_BUILD_ID} .buildkite/scripts/vllm-integration-tests.sh --hf-token=$HF_TOKEN --server-wait-timeout=240 --configs=.buildkite/cases/comprehensive-cases.txt
+        test_exit_code=$?
+        create_artifact
+        exit $test_exit_code
+
+        export TARGET="$PWD"
+        echo "Deleting current workspace $TARGET"
+        cd /
+        sudo rm -rf "$TARGET"
+    artifact_paths:
+      - "build_${BUILDKITE_BUILD_ID}.log"
diff --git a/.buildkite/pipelines/end-to-end-tests.yml b/.buildkite/pipelines/end-to-end-tests.yml
new file mode 100644
index 0000000..31bb1be
--- /dev/null
+++ b/.buildkite/pipelines/end-to-end-tests.yml
@@ -0,0 +1,50 @@
+steps:
+  - label: ":pip: E2E Tests"
+    key: "e2e"
+    command: |
+      echo $PWD # for debugging
+
+      uv venv --python 3.12 .venv-$BUILDKITE_BUILD_ID
+      source .venv-$BUILDKITE_BUILD_ID/bin/activate
+
+      uv pip install --upgrade pip setuptools wheel 
+      uv pip install -r requirements/common.txt
+      uv pip install -r requirements/test.txt
+      uv pip install -e . --no-build-isolation
+      uv pip install matplotlib
+      uv pip install pandas
+      uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
+      uv pip freeze
+
+
+      source .buildkite/scripts/pick-free-gpu.sh 18000
+
+      bash .buildkite/scripts/end-to-end-test.sh
+    artifact_paths:
+      - "test_local_cpu_experimental.csv"
+      - "test_local_cpu_experimental.pdf"
+      - "test_local_disk_experimental.csv"
+      - "test_local_disk_experimental.pdf"
+      - "lmcache-cpu-stdout.log"
+      - "lmcache-cpu-stderr.log"
+      - "vllm-cpu-stdout.log"
+      - "vllm-cpu-stderr.log"
+      - "lmcache-disk-stdout.log"
+      - "lmcache-disk-stderr.log"
+      - "vllm-disk-stdout.log"
+      - "vllm-disk-stderr.log"
+
+  - label: ":wastebasket: Kill all"
+    key: "clean"
+    depends_on: "e2e"
+    allow_dependency_failure: true
+    command: bash .buildkite/scripts/bare-machine-cleanup.sh
+
+  - label: "Clean up"
+    depends_on:
+        - "clean"
+    command: |
+      export TARGET="$PWD"
+      echo "Deleting current workspace $TARGET"
+      cd /
+      sudo rm -rf "$TARGET"
diff --git a/.buildkite/pipelines/multiprocessing-test.yml b/.buildkite/pipelines/multiprocessing-test.yml
new file mode 100644
index 0000000..5d26e46
--- /dev/null
+++ b/.buildkite/pipelines/multiprocessing-test.yml
@@ -0,0 +1,11 @@
+env:
+  DOCKER_BUILDKIT: 1
+
+steps:
+  - label: ":compression: Multiprocessing tests"
+    key: "test"
+    timeout_in_minutes: 60
+    commands:
+      - .buildkite/scripts/should-run-comprehensive.sh || exit 0 # Reuse the trigger condition for comprehensive tests
+      - chmod +x .buildkite/scripts/multiprocessing-test/*.sh
+      - BUILD_ID=${BUILDKITE_BUILD_ID} .buildkite/scripts/multiprocessing-test/run-mp-test.sh
diff --git a/.buildkite/scripts/bare-machine-cleanup.sh b/.buildkite/scripts/bare-machine-cleanup.sh
new file mode 100644
index 0000000..a366797
--- /dev/null
+++ b/.buildkite/scripts/bare-machine-cleanup.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -eu
+
+# Utility: kill and cleanup a PID stored in Buildkite meta‑data
+cleanup_meta_pid() {
+  local key="$1"
+  local label="$2"
+
+  # Try to fetch the PID from meta‑data; if the key doesn't exist, `get` will exit non‑zero
+  if pid=$(buildkite-agent meta-data get "$key" 2>/dev/null); then
+    if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+      echo "🧹 Killing ${label} process ${pid}"
+      kill "$pid" || true
+      wait "$pid" 2>/dev/null || true
+    else
+      echo "No running ${label} process with PID ${pid}"
+    fi
+  fi
+}
+
+# Clean up the bare‑machine CPU test
+cleanup_meta_pid "cpu-CID"  "bare‑machine CPU test"
+
+# Clean up the bare‑machine disk test
+cleanup_meta_pid "disk-CID" "bare‑machine disk test"
diff --git a/.buildkite/scripts/clean.sh b/.buildkite/scripts/clean.sh
new file mode 100644
index 0000000..8ef2d96
--- /dev/null
+++ b/.buildkite/scripts/clean.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Read each PID (one-per-line) into an array
+mapfile -t pids < <(
+  nvidia-smi \
+    --query-compute-apps=pid \
+    --format=csv,noheader,nounits
+)
+
+if (( ${#pids[@]} == 0 )); then
+  echo "✔ No GPU processes found."
+else
+  echo "The following GPU processes will be terminated:"
+  printf '→ %s\n' "${pids[@]}"
+
+  for pid in "${pids[@]}"; do
+    if kill -0 "$pid" &>/dev/null; then
+      echo "→ Killing PID $pid"
+      kill -9 "$pid"
+    else
+      echo "⚠ PID $pid does not exist or has already exited"
+    fi
+  done
+fi
+
+docker system prune -af --volumes
+docker builder prune -af
+rm -rf ~/.cache/huggingface
+
+echo "Done."
diff --git a/.buildkite/scripts/end-to-end-test.sh b/.buildkite/scripts/end-to-end-test.sh
new file mode 100644
index 0000000..e976bf1
--- /dev/null
+++ b/.buildkite/scripts/end-to-end-test.sh
@@ -0,0 +1,90 @@
+#!/bin/bash
+
+orig_dir="$(pwd)"
+cd "$LM_CACHE_TEST_DIR"
+
+start_port=8000
+max_port=9000
+
+find_free_port() {
+  local port=$1
+  while [ $port -le $max_port ]; do
+    if ! netstat -tuln 2>/dev/null | grep -q ":$port "; then
+      >&2 echo "Port $port is available."
+      printf "%s" "$port"
+      return 0
+    fi
+
+    >&2 echo "Port $port is in use. Killing process(es)..."
+    local pids
+    pids=$(lsof -t -i tcp:$port)
+    if [ -n "$pids" ]; then
+      >&2 echo "→ Killing PID(s): $pids"
+      kill $pids
+      sleep 1
+      if ! netstat -tuln 2>/dev/null | grep -q ":$port "; then
+        >&2 echo "→ Port $port freed after killing processes."
+        printf "%s" "$port"
+        return 0
+      else
+        >&2 echo "→ Port $port still in use after kill. Continuing search..."
+      fi
+    else
+      >&2 echo "→ No PIDs found listening on $port. Continuing search..."
+    fi
+
+    port=$((port + 1))
+  done
+  return 1
+}
+
+# Find port1
+port1=$(find_free_port $start_port) || {
+  echo "❌ Could not find any free port between $start_port and $max_port."
+  exit 1
+}
+
+# Find port2, starting just after port1
+port2=$(find_free_port $((port1 + 1))) || {
+  echo "❌ Could not find a second free port between $((port1+1)) and $max_port."
+  exit 1
+}
+
+echo
+echo "🎉 Selected ports: port1=$port1, port2=$port2"
+
+set -x
+
+LMCACHE_TRACK_USAGE="false" python3 main.py tests/tests.py \
+  -f test_local_cpu_experimental \
+  -o outputs/ \
+  -p "$port1" "$port2" &
+CID=$!
+buildkite-agent meta-data set "cpu-CID" "$CID"
+wait $CID
+
+mv /tmp/buildkite-agent-"$port1"-stdout.log "$orig_dir"/lmcache-cpu-stdout.log
+mv /tmp/buildkite-agent-"$port1"-stderr.log "$orig_dir"/lmcache-cpu-stderr.log
+mv /tmp/buildkite-agent-"$port2"-stdout.log "$orig_dir"/vllm-cpu-stdout.log
+mv /tmp/buildkite-agent-"$port2"-stderr.log "$orig_dir"/vllm-cpu-stderr.log
+
+LMCACHE_TRACK_USAGE="false" python3 main.py tests/tests.py \
+  -f test_local_disk_experimental \
+  -o outputs/ \
+  -p "$port1" "$port2" &
+CID=$!
+buildkite-agent meta-data set "disk-CID" "$CID"
+wait $CID
+
+mv /tmp/buildkite-agent-"$port1"-stdout.log "$orig_dir"/lmcache-disk-stdout.log
+mv /tmp/buildkite-agent-"$port1"-stderr.log "$orig_dir"/lmcache-disk-stderr.log
+mv /tmp/buildkite-agent-"$port2"-stdout.log "$orig_dir"/vllm-disk-stdout.log
+mv /tmp/buildkite-agent-"$port2"-stderr.log "$orig_dir"/vllm-disk-stderr.log
+
+python3 outputs/drawing_wrapper.py ./
+if compgen -G outputs/*.{csv,pdf} > /dev/null; then
+    mv outputs/*.{csv,pdf} "$orig_dir"/
+else
+    echo "Error: no CSV or PDF files found in outputs/" >&2
+    exit 1
+fi
diff --git a/.buildkite/scripts/gpu_zombie_killer.sh b/.buildkite/scripts/gpu_zombie_killer.sh
new file mode 100644
index 0000000..4c2689b
--- /dev/null
+++ b/.buildkite/scripts/gpu_zombie_killer.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+
+# Helper daemon to run on your CI machine to kill GPU processes that are running for too long
+# Copy somewhere
+# chmod +x gpu_zombie_killer.sh
+# nohup sudo ./gpu_zombie_killer.sh > /dev/null 2>&1 &
+
+# Check logs:
+# cat /var/log/gpu_zombie_killer.log
+
+# Kill it:
+# sudo kill -9 $(cat /tmp/gpu_zombie_killer.pid)
+
+PIDFILE="/tmp/gpu_zombie_killer.pid"
+LOGFILE="/var/log/gpu_zombie_killer.log"
+MAX_SECONDS=$((60 * 60))   # 1 hour
+SLEEP_INTERVAL=60          # check every 60s
+
+# Track date for log rotation
+LAST_DATE=$(date +%F)
+
+# Save PID for tracking
+echo $$ > "$PIDFILE"
+echo "[GPU ZOMBIE KILLER] Started with PID $$ at $(date)" >> "$LOGFILE"
+
+# Clean up on termination
+trap 'echo "[GPU ZOMBIE KILLER] Stopping at $(date)" >> "$LOGFILE"; rm -f "$PIDFILE"; exit 0' SIGINT SIGTERM
+
+while true; do
+  now=$(date +%s)
+
+  # Rotate logs if date changed
+  current_date=$(date +%F)
+  if [ "$current_date" != "$LAST_DATE" ]; then
+    echo "[GPU ZOMBIE KILLER] Clearing logs at midnight ($current_date)" > "$LOGFILE"
+    LAST_DATE="$current_date"
+  fi
+
+  nvidia-smi --query-compute-apps=pid --format=csv,noheader,nounits \
+  | awk '{print $1}' \
+  | while read -r pid; do
+      [ -d "/proc/$pid" ] || continue
+      start_ticks=$(awk '{print $22}' /proc/$pid/stat)
+      hertz=$(getconf CLK_TCK)
+      boot_time=$(awk '/btime/ {print $2}' /proc/stat)
+      start_time=$((boot_time + start_ticks / hertz))
+      now=$(date +%s)
+      runtime=$((now - start_time))
+
+      if (( runtime > MAX_SECONDS )); then
+        echo "[GPU ZOMBIE KILLER] Killing PID $pid (runtime ${runtime}s) at $(date)" >> "$LOGFILE"
+        kill -9 "$pid"
+      fi
+    done
+
+  sleep "$SLEEP_INTERVAL"
+done
diff --git a/.buildkite/scripts/multi-round-qa.sh b/.buildkite/scripts/multi-round-qa.sh
new file mode 100644
index 0000000..92bc561
--- /dev/null
+++ b/.buildkite/scripts/multi-round-qa.sh
@@ -0,0 +1,45 @@
+#!/bin/bash
+
+set -x
+
+# Install lmcache
+pip install -e .
+
+# Pull the latest lmcache-vllm
+cd ../lmcache-vllm
+git pull
+
+# Install requirements for benchmark scripts
+cd ../benchmark
+pip install -r ./benchmarks/multi_round_qa/requirements.txt
+
+set +x
+
+# Start the server
+LMCACHE_TRACK_USAGE="false" lmcache_vllm serve mistralai/Mistral-7B-Instruct-v0.2 --disable-log-requests > lmcache_vllm.log 2>&1 &
+echo "Waiting for service to start..."
+timeout=90  # Timeout duration in seconds
+elapsed=0   # Track elapsed time
+until grep -q "Uvicorn running on" lmcache_vllm.log; do
+  if [ $elapsed -ge $timeout ]; then
+    echo "Timeout reached: Service did not start within $timeout seconds."
+    exit 1
+  fi
+  sleep 10
+  elapsed=$((elapsed + 10))
+  echo "Waiting... ($elapsed seconds elapsed)"
+done
+echo "Service started successfully."
+
+# Run benchmark scripts
+python3 benchmarks/multi-round-qa.py \
+    --num-users 10 \
+    --num-rounds 5 \
+    --qps 0.5 \
+    --shared-system-prompt 1000 \
+    --user-history-prompt 2000 \
+    --answer-len 100 \
+    --model mistralai/Mistral-7B-Instruct-v0.2 \
+    --base-url http://localhost:8000/v1 \
+    --time 300
+    
diff --git a/.buildkite/scripts/multiprocessing-test/README.md b/.buildkite/scripts/multiprocessing-test/README.md
new file mode 100644
index 0000000..c4a9483
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/README.md
@@ -0,0 +1,339 @@
+# LMCache Multiprocessing Tests
+
+This directory contains end-to-end integration tests for LMCache's multiprocessing functionality. These tests validate that LMCache correctly caches KV tensors and provides performance benefits when integrated with vLLM.
+
+## Overview
+
+The test suite runs two vLLM servers in parallel:
+1. **vLLM with LMCache** - Connected to an LMCache multiprocessing server for KV caching
+2. **vLLM baseline** - Standard vLLM without LMCache (for performance comparison)
+
+Tests send workloads to both servers and verify:
+- Correctness: LMCache produces identical outputs to baseline
+- Performance: LMCache meets latency/throughput thresholds
+- Caching behavior: Repeated requests benefit from cached KV tensors
+
+## Quick Start
+
+Run all tests:
+
+```bash
+./run-mp-test.sh
+```
+
+This will:
+1. Build the Docker image
+2. Launch LMCache and vLLM containers
+3. Run all benchmark tests
+4. Clean up containers (even on failure)
+
+## Script Structure
+
+```
+multiprocessing-test/
+├── run-mp-test.sh           # Main orchestrator - runs everything
+├── common.sh                # Shared utilities (setup_venv, RESULTS_DIR)
+│
+├── build-mp-docker-image.sh # Builds lmcache/vllm-openai:test image
+├── launch-containers.sh     # Starts LMCache + vLLM containers
+├── wait-for-vllm.sh         # Waits for vLLM health endpoints
+├── cleanup.sh               # Stops and removes containers
+│
+├── run-lm-eval.sh           # Test: lm_eval workload (correctness)
+├── run-vllm-bench.sh        # Test: vllm bench serve (throughput)
+├── run-long-doc-qa.sh       # Test: Long document QA (latency)
+│
+└── README.md                # This file
+```
+
+### Script Descriptions
+
+| Script | Purpose |
+|--------|---------|
+| `run-mp-test.sh` | Main entry point. Orchestrates the entire test pipeline and ensures cleanup runs on exit. |
+| `common.sh` | Shared utilities sourced by test scripts. Provides `setup_venv()` function and common variables (`RESULTS_DIR`, `BUILD_ID`, `VENV_DIR`). |
+| `build-mp-docker-image.sh` | Builds the `lmcache/vllm-openai:test` Docker image from the repository's Dockerfile. |
+| `launch-containers.sh` | Launches three containers: LMCache server, vLLM with LMCache, and baseline vLLM. |
+| `wait-for-vllm.sh` | Polls health endpoints until both vLLM servers are ready. |
+| `cleanup.sh` | Stops and removes all test containers. Captures logs before cleanup for debugging. |
+| `run-lm-eval.sh` | Runs GSM8K evaluation twice to verify caching produces identical outputs. |
+| `run-vllm-bench.sh` | Benchmarks throughput using `vllm bench serve` and compares LMCache vs baseline. |
+| `run-long-doc-qa.sh` | Tests long-context caching with document QA workload and verifies latency thresholds. |
+
+## Test Descriptions
+
+### 1. LM-Eval Workload (`run-lm-eval.sh`)
+
+**Purpose:** Verify that LMCache produces deterministic, correct outputs.
+
+**How it works:**
+1. Runs `lm_eval` with GSM8K task against vLLM+LMCache (first run populates cache)
+2. Runs the same evaluation again (second run uses cached KV tensors)
+3. Compares output samples from both runs
+
+**Pass criteria:** Sample outputs from both runs must be identical.
+
+### 2. vLLM Bench Serve (`run-vllm-bench.sh`)
+
+**Purpose:** Verify LMCache doesn't significantly degrade throughput.
+
+**How it works:**
+1. Runs `vllm bench serve` with random prompts against baseline vLLM
+2. Runs the same benchmark against vLLM+LMCache
+3. Compares throughput metrics
+
+**Pass criteria:**
+- All prompts complete successfully
+- LMCache throughput is within 5% of baseline
+
+### 3. Long Document QA (`run-long-doc-qa.sh`)
+
+**Purpose:** Verify LMCache provides latency benefits for long-context workloads.
+
+**How it works:**
+1. Runs long document QA benchmark against baseline vLLM
+2. Runs the same benchmark against vLLM+LMCache
+3. Compares TTFT (Time To First Token) and round-trip latency
+
+**Pass criteria:**
+- `query_ttft_per_prompt` ≤ 0.22s (loading 10K tokens)
+- `query_round_time_per_prompt` ≤ 0.58s
+
+## Expected Outputs
+
+All test results are saved to a shared directory:
+
+```
+/tmp/lmcache_ci_results_${BUILD_ID}/
+├── lm_eval/
+│   ├── first_run/
+│   │   └── samples_gsm8k_*.jsonl
+│   └── second_run/
+│       └── samples_gsm8k_*.jsonl
+├── long_doc_qa/
+│   ├── lmcache_result.json
+│   ├── baseline_result.json
+│   ├── lmcache_output.txt
+│   └── baseline_output.txt
+└── vllm_bench/
+    ├── lmcache.json
+    └── baseline.json
+```
+
+### Sample Output Files
+
+**vllm_bench/lmcache.json:** (some fields are excluded)
+```json
+{
+  "total_input_tokens": 500000,
+  "completed": 50,
+  "total_token_throughput": 12345.67
+}
+```
+
+**long_doc_qa/lmcache_result.json:** (some fields are excluded)
+```json
+{
+  "query_ttft_per_prompt": 0.15,
+  "query_round_time_per_prompt": 0.45,
+  "warmup_round_time_per_prompt": 2.1
+}
+```
+
+## Configuration
+
+All scripts support configuration via environment variables:
+
+### Common Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BUILD_ID` | `local_<timestamp>` | Unique identifier for this test run |
+| `RESULTS_DIR` | `/tmp/lmcache_ci_results_${BUILD_ID}` | Directory for all test outputs |
+| `VENV_DIR` | `<workspace>/.venv` | Python virtual environment path |
+| `MODEL` | `Qwen/Qwen3-14B` | Model to use for testing |
+| `VLLM_PORT` | `8000` | Port for vLLM with LMCache |
+| `VLLM_BASELINE_PORT` | `9000` | Port for baseline vLLM |
+| `LMCACHE_PORT` | `6555` | Port for LMCache server |
+| `MAX_WAIT_SECONDS` | `300` | Timeout for vLLM startup |
+
+### Test-Specific Variables
+
+**run-lm-eval.sh:**
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NUM_CONCURRENT` | `50` | Concurrent requests |
+| `LIMIT` | `300` | Number of samples |
+
+**run-vllm-bench.sh:**
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NUM_PROMPTS` | `50` | Number of prompts |
+| `RANDOM_INPUT_LEN` | `10000` | Input token length |
+| `RANDOM_OUTPUT_LEN` | `1` | Output token length |
+| `RANDOM_SEED` | `<timestamp>` | Seed for reproducibility |
+
+**run-long-doc-qa.sh:**
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DOCUMENT_LENGTH` | `10000` | Document length in tokens |
+| `NUM_DOCUMENTS` | `30` | Number of documents |
+| `OUTPUT_LEN` | `200` | Output length |
+| `MAX_LMCACHE_TTFT` | `0.22` | Max allowed TTFT (seconds) |
+| `MAX_LMCACHE_QUERY_ROUND_TIME` | `0.58` | Max allowed round time (seconds) |
+
+## Adding a New Test
+
+To add a new test to the suite:
+
+### 1. Create Your Test Script
+
+Create a new script (e.g., `run-my-test.sh`) following this template:
+
+```bash
+#!/bin/bash
+# Brief description of your test
+
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source common utilities
+source "$SCRIPT_DIR/common.sh"
+
+# Configuration (use environment variables with defaults)
+MY_PARAM="${MY_PARAM:-default_value}"
+
+# Output directory (subdirectory of shared RESULTS_DIR)
+MY_TEST_DIR="$RESULTS_DIR/my_test"
+
+echo "=== My Test ==="
+echo "Results dir: $MY_TEST_DIR"
+
+# Create results directory
+mkdir -p "$MY_TEST_DIR"
+
+# Your test functions here
+run_my_test() {
+    # Implementation
+    echo "Running test..."
+}
+
+verify_results() {
+    # Verification logic
+    # Return 0 on success, 1 on failure
+    return 0
+}
+
+# Main execution
+main() {
+    # Setup venv with required packages
+    setup_venv package1 package2
+    
+    # Run test
+    run_my_test
+    
+    # Verify results
+    if ! verify_results; then
+        echo "❌ Test failed"
+        exit 1
+    fi
+    
+    echo "✅ Test passed"
+}
+
+main "$@"
+```
+
+### 2. Add to Orchestrator
+
+Edit `run-mp-test.sh` to include your test:
+
+```bash
+# Step N: Run your test
+echo "============================================"
+echo "=== Step N: Running my test ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/run-my-test.sh"; then
+    echo "❌ my test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+```
+
+### 3. Guidelines
+
+- **Use `common.sh`**: Source it to get `setup_venv()`, `RESULTS_DIR`, `BUILD_ID`, etc.
+- **Use subdirectories**: Store outputs in `$RESULTS_DIR/your_test_name/`
+- **Exit codes**: Return 0 on success, non-zero on failure
+- **Logging**: Use clear status indicators (✅, ❌) and descriptive messages
+- **Cleanup**: Don't leave temporary files outside `RESULTS_DIR`
+- **Configuration**: Use environment variables with sensible defaults
+- **Comparison tests**: When comparing LMCache vs baseline, run baseline first to avoid any warm-up effects benefiting LMCache unfairly
+
+### 4. Test Your Script
+
+Run your script in isolation first:
+
+```bash
+# Start containers manually
+./launch-containers.sh
+./wait-for-vllm.sh
+
+# Run your test
+./run-my-test.sh
+
+# Cleanup
+./cleanup.sh
+```
+
+Then run the full suite:
+
+```bash
+./run-mp-test.sh
+```
+
+## Troubleshooting
+
+### Container logs
+
+If tests fail, check container logs:
+
+```bash
+docker logs lmcache-mp-test-<pid>
+docker logs vllm-mp-test-<pid>
+docker logs vllm-baseline-test-<pid>
+```
+
+The cleanup script automatically captures the last 50 lines of logs before removing containers.
+
+### Common issues
+
+1. **vLLM timeout**: Increase `MAX_WAIT_SECONDS` or check GPU availability
+2. **Out of memory**: Reduce model size or adjust `--gpu-memory-utilization`
+3. **Port conflicts**: Change `VLLM_PORT`, `VLLM_BASELINE_PORT`, or `LMCACHE_PORT`
+4. **Model not found**: Ensure HuggingFace cache is mounted correctly
+
+### Running individual tests
+
+You can run tests individually after containers are up:
+
+```bash
+# Start infrastructure
+./build-mp-docker-image.sh
+./launch-containers.sh
+./wait-for-vllm.sh
+
+# Run specific test
+./run-lm-eval.sh
+# or
+./run-vllm-bench.sh
+# or
+./run-long-doc-qa.sh
+
+# Cleanup when done
+./cleanup.sh
+```
+
diff --git a/.buildkite/scripts/multiprocessing-test/build-mp-docker-image.sh b/.buildkite/scripts/multiprocessing-test/build-mp-docker-image.sh
new file mode 100755
index 0000000..15a557b
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/build-mp-docker-image.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+# Build the LMCache + vLLM docker image for multiprocessing tests
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+echo "=== Building LMCache + vLLM image ==="
+
+cd "$REPO_ROOT/docker"
+
+# Build the vLLM + LMCache image (used for both lmcache server and vllm process)
+docker build \
+    --progress=plain \
+    --build-arg CUDA_VERSION=12.8 \
+    --build-arg UBUNTU_VERSION=24.04 \
+    --build-arg VLLM_VERSION=nightly \
+    --target image-build \
+    --file Dockerfile \
+    --tag lmcache/vllm-openai:test \
+    ../
+
+echo "=== Docker image built successfully ==="
+docker images | grep "lmcache/vllm-openai" | head -5
diff --git a/.buildkite/scripts/multiprocessing-test/cleanup.sh b/.buildkite/scripts/multiprocessing-test/cleanup.sh
new file mode 100755
index 0000000..ffa268b
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/cleanup.sh
@@ -0,0 +1,52 @@
+#!/bin/bash
+# Cleanup containers launched for multiprocessing tests
+# This script should always be called, even on failure
+
+LMCACHE_CONTAINER_NAME="${LMCACHE_CONTAINER_NAME:-lmcache-mp-test}"
+VLLM_CONTAINER_NAME="${VLLM_CONTAINER_NAME:-vllm-mp-test}"
+VLLM_BASELINE_CONTAINER_NAME="${VLLM_BASELINE_CONTAINER_NAME:-vllm-baseline-test}"
+
+echo "=== Cleaning up containers ==="
+
+# Function to stop and remove a container
+cleanup_container() {
+    local container_name="$1"
+    
+    if docker ps -a --format '{{.Names}}' | grep -q "^${container_name}$"; then
+        echo "Stopping and removing container: $container_name"
+        
+        # Try to get logs before cleanup (for debugging)
+        echo "--- Container logs for $container_name ---"
+        docker logs --tail 50 "$container_name" 2>&1 || true
+        echo "--- End of logs ---"
+        
+        # Stop container (with timeout)
+        docker stop --timeout 10 "$container_name" 2>/dev/null || true
+        
+        # Remove container
+        docker rm -f "$container_name" 2>/dev/null || true
+        
+        echo "Container $container_name cleaned up"
+    else
+        echo "Container $container_name not found (already cleaned up or never started)"
+    fi
+}
+
+# Cleanup all containers
+cleanup_container "$VLLM_BASELINE_CONTAINER_NAME"
+cleanup_container "$VLLM_CONTAINER_NAME"
+cleanup_container "$LMCACHE_CONTAINER_NAME"
+
+echo "=== Cleanup complete ==="
+
+# Wait for GPU memory to be fully released
+echo "Waiting 5 seconds for GPU memory to be released..."
+sleep 5
+
+# List any remaining test containers (for debugging)
+remaining=$(docker ps -a --format '{{.Names}}' | grep -E "(lmcache|vllm).*-(mp|baseline)-test" || true)
+if [ -n "$remaining" ]; then
+    echo "Warning: Some test containers may still exist:"
+    echo "$remaining"
+fi
+
diff --git a/.buildkite/scripts/multiprocessing-test/common.sh b/.buildkite/scripts/multiprocessing-test/common.sh
new file mode 100644
index 0000000..5bd5fd2
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/common.sh
@@ -0,0 +1,59 @@
+#!/bin/bash
+# Common utilities for multiprocessing tests
+# Source this file to use shared functions and variables
+
+# Get the directory where this script is located
+COMMON_SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKSPACE_DIR="$(cd "$COMMON_SCRIPT_DIR/../../../.." && pwd)"
+LMCACHE_DIR="$(cd "$COMMON_SCRIPT_DIR/../../.." && pwd)"
+
+# Common configuration
+BUILD_ID="${BUILD_ID:-local_$(date +%Y%m%d_%H%M%S)}"
+VENV_DIR="${VENV_DIR:-$WORKSPACE_DIR/.venv}"
+RESULTS_DIR="${RESULTS_DIR:-/tmp/lmcache_ci_results_${BUILD_ID}}"
+
+# Setup virtual environment
+# Usage: setup_venv [packages...]
+# Example: setup_venv openai pandas matplotlib
+setup_venv() {
+    local packages=("$@")
+    
+    echo "=== Setting up virtual environment ==="
+    
+    if [ -d "$VENV_DIR" ] && [ -f "$VENV_DIR/bin/activate" ]; then
+        echo "Virtual environment already exists at $VENV_DIR"
+    else
+        echo "Creating virtual environment with uv..."
+        
+        # Check if uv is available
+        if ! command -v uv &> /dev/null; then
+            echo "uv not found, installing..."
+            curl -LsSf https://astral.sh/uv/install.sh | sh
+            export PATH="$HOME/.local/bin:$PATH"
+        fi
+        
+        # Create venv with uv
+        uv venv "$VENV_DIR"
+        echo "Virtual environment created"
+    fi
+    
+    # Activate virtual environment
+    source "$VENV_DIR/bin/activate"
+    echo "Virtual environment activated"
+    
+    # Install dependencies if provided
+    if [ ${#packages[@]} -gt 0 ]; then
+        echo "Installing dependencies: ${packages[*]}"
+        uv pip install "${packages[@]}" --quiet
+        echo "Dependencies installed"
+    fi
+    
+    echo ""
+}
+
+# Ensure results directory exists
+ensure_results_dir() {
+    mkdir -p "$RESULTS_DIR"
+    echo "Results directory: $RESULTS_DIR"
+}
+
diff --git a/.buildkite/scripts/multiprocessing-test/launch-containers.sh b/.buildkite/scripts/multiprocessing-test/launch-containers.sh
new file mode 100755
index 0000000..edde8f3
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/launch-containers.sh
@@ -0,0 +1,126 @@
+#!/bin/bash
+# Launch LMCache and vLLM containers for multiprocessing tests
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Container names (exported so cleanup script can use them)
+export LMCACHE_CONTAINER_NAME="${LMCACHE_CONTAINER_NAME:-lmcache-mp-test}"
+export VLLM_CONTAINER_NAME="${VLLM_CONTAINER_NAME:-vllm-mp-test}"
+export VLLM_BASELINE_CONTAINER_NAME="${VLLM_BASELINE_CONTAINER_NAME:-vllm-baseline-test}"
+
+# Configuration
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-6556}"
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+
+# Pick 2 free GPUs dynamically for the test
+echo "=== Selecting free GPUs for testing ==="
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+source "$REPO_ROOT/.buildkite/scripts/pick-free-gpu.sh" 70000 2
+if [ -z "$CUDA_VISIBLE_DEVICES" ]; then
+    echo "❌ Failed to select 2 free GPUs"
+    exit 1
+fi
+
+# Parse the selected GPUs into an array
+IFS=',' read -ra SELECTED_GPUS <<< "$CUDA_VISIBLE_DEVICES"
+if [ ${#SELECTED_GPUS[@]} -ne 2 ]; then
+    echo "❌ Expected 2 GPUs, but got ${#SELECTED_GPUS[@]}: ${CUDA_VISIBLE_DEVICES}"
+    exit 1
+fi
+
+GPU_FOR_VLLM="${SELECTED_GPUS[0]}"
+GPU_FOR_BASELINE="${SELECTED_GPUS[1]}"
+echo "Selected GPU ${GPU_FOR_VLLM} for vLLM with LMCache"
+echo "Selected GPU ${GPU_FOR_BASELINE} for vLLM baseline"
+
+# Check GPU memory and set gpu-memory-utilization if > 100GB
+GPU_MEMORY_UTIL_ARG=""
+GPU_MEMORY_MB=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits -i "${GPU_FOR_VLLM}" | tr -d ' ')
+GPU_MEMORY_GB=$((GPU_MEMORY_MB / 1024))
+echo "Detected GPU memory: ${GPU_MEMORY_GB}GB (${GPU_MEMORY_MB}MB)"
+
+if [ "$GPU_MEMORY_GB" -gt 90 ]; then
+    echo "GPU memory > 100GB, adding --gpu-memory-utilization 0.5"
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization 0.5"
+fi
+
+echo "=== Launching LMCache container ==="
+echo "Container name: $LMCACHE_CONTAINER_NAME"
+echo "Port: $LMCACHE_PORT"
+
+docker run -d \
+    --name "$LMCACHE_CONTAINER_NAME" \
+    --runtime nvidia \
+    --gpus "device=${GPU_FOR_VLLM}" \
+    --network host \
+    --ipc host \
+    --entrypoint /opt/venv/bin/python3 \
+    lmcache/vllm-openai:test \
+    -m lmcache.v1.multiprocess.http_server \
+    --l1-size-gb "$CPU_BUFFER_SIZE" \
+    --eviction-policy LRU \
+    --max-workers "$MAX_WORKERS" \
+    --port "$LMCACHE_PORT" \
+    --http-port "$LMCACHE_HTTP_PORT"
+
+echo "LMCache container started"
+
+# Wait a bit for LMCache to initialize
+echo "Waiting for LMCache to initialize..."
+sleep 10
+
+echo "=== Launching vLLM container ==="
+echo "Container name: $VLLM_CONTAINER_NAME"
+echo "Model: $MODEL"
+
+docker run -d \
+    --name "$VLLM_CONTAINER_NAME" \
+    --runtime nvidia \
+    --gpus "device=${GPU_FOR_VLLM}" \
+    --volume ~/.cache/huggingface:/root/.cache/huggingface \
+    --network host \
+    --ipc host \
+    --env VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    --env VLLM_BATCH_INVARIANT=1 \
+    --env PYTHONHASHSEED=0 \
+    lmcache/vllm-openai:test \
+    "$MODEL" \
+    --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $LMCACHE_PORT, \"lmcache.mp.mq_timeout\": 10}}" \
+    --attention-backend FLASH_ATTN \
+    --port "$VLLM_PORT" \
+    $GPU_MEMORY_UTIL_ARG
+
+echo "vLLM container started"
+
+echo "=== Launching vLLM baseline container (without LMCache) ==="
+echo "Container name: $VLLM_BASELINE_CONTAINER_NAME"
+echo "Port: $VLLM_BASELINE_PORT"
+
+docker run -d \
+    --name "$VLLM_BASELINE_CONTAINER_NAME" \
+    --runtime nvidia \
+    --gpus "device=${GPU_FOR_BASELINE}" \
+    --volume ~/.cache/huggingface:/root/.cache/huggingface \
+    --network host \
+    --ipc host \
+    --env VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    --env VLLM_BATCH_INVARIANT=1 \
+    --env PYTHONHASHSEED=0 \
+    lmcache/vllm-openai:test \
+    "$MODEL" \
+    --port "$VLLM_BASELINE_PORT" \
+    --attention-backend FLASH_ATTN \
+    $GPU_MEMORY_UTIL_ARG
+
+echo "vLLM baseline container started"
+
+echo "=== Containers launched ==="
+docker ps --filter "name=$LMCACHE_CONTAINER_NAME" --filter "name=$VLLM_CONTAINER_NAME" --filter "name=$VLLM_BASELINE_CONTAINER_NAME"
+
diff --git a/.buildkite/scripts/multiprocessing-test/run-fault-tolerance.sh b/.buildkite/scripts/multiprocessing-test/run-fault-tolerance.sh
new file mode 100755
index 0000000..9fdaeef
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/run-fault-tolerance.sh
@@ -0,0 +1,152 @@
+#!/bin/bash
+# Test fault tolerance: verify vLLM requests complete after LMCache server dies.
+#
+# Flow:
+#   1. Warmup bench (calibrate timing)
+#   2. Start bench in background, kill LMCache container mid-flight
+#   3. Verify all prompts completed
+#   4. Quick curl health check (vLLM still alive)
+#
+# NOTE: This test is destructive — it kills the LMCache container.
+# Run it as the LAST test step.
+
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Configuration (reuse exported vars from run-mp-test.sh)
+VLLM_PORT="${VLLM_PORT:-8000}"
+LMCACHE_CONTAINER_NAME="${LMCACHE_CONTAINER_NAME:-lmcache-mp-test}"
+VLLM_CONTAINER_NAME="${VLLM_CONTAINER_NAME:-vllm-mp-test}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+NUM_PROMPTS="${NUM_PROMPTS:-50}"
+RANDOM_INPUT_LEN="${RANDOM_INPUT_LEN:-10000}"
+RANDOM_OUTPUT_LEN="${RANDOM_OUTPUT_LEN:-1}"
+RANDOM_SEED="${RANDOM_SEED:-42}"
+
+# Output directory
+FT_RESULTS_DIR="$RESULTS_DIR/fault_tolerance"
+mkdir -p "$FT_RESULTS_DIR"
+
+echo "=== Fault Tolerance Test ==="
+echo "vLLM port: $VLLM_PORT"
+echo "LMCache container: $LMCACHE_CONTAINER_NAME"
+echo "Bench: $NUM_PROMPTS prompts, input_len=$RANDOM_INPUT_LEN"
+echo ""
+
+# Helper: run vllm bench serve
+run_bench() {
+    local description="$1"
+    local result_file="$2"
+
+    echo "--- $description ---"
+    vllm bench serve \
+        --seed "$RANDOM_SEED" \
+        --port "$VLLM_PORT" \
+        --model "$MODEL" \
+        --dataset-name random \
+        --random-input-len "$RANDOM_INPUT_LEN" \
+        --random-output-len "$RANDOM_OUTPUT_LEN" \
+        --num-prompts "$NUM_PROMPTS" \
+        --ignore-eos \
+        --backend openai-chat \
+        --endpoint /v1/chat/completions \
+        --result-dir "$FT_RESULTS_DIR" \
+        --result-filename "$result_file" \
+        --save-result
+
+    local completed
+    completed=$(python3 -c "
+import json
+with open('$FT_RESULTS_DIR/$result_file') as f:
+    data = json.load(f)
+print(data.get('completed', 0))
+")
+
+    echo "$description: $completed / $NUM_PROMPTS completed"
+    if [ "$completed" -ne "$NUM_PROMPTS" ]; then
+        echo "ERROR: Expected $NUM_PROMPTS completed, got $completed"
+        return 1
+    fi
+    echo "All $NUM_PROMPTS prompts completed"
+}
+
+main() {
+    setup_venv vllm openai
+
+    # Step 1: Warmup bench (measure timing for kill calibration)
+    echo "============================================"
+    echo "=== Step 1: Warmup bench ==="
+    echo "============================================"
+    if ! run_bench "Warmup (with LMCache)" "bench_warmup.json"; then
+        echo "Warmup bench failed"
+        exit 1
+    fi
+
+    WARMUP_DURATION=$(python3 -c "import json; print(json.load(open('$FT_RESULTS_DIR/bench_warmup.json'))['duration'])")
+    KILL_DELAY=$(python3 -c "print(max(3, int($WARMUP_DURATION * 0.4)))")
+    echo "Warmup took ${WARMUP_DURATION}s. Will kill LMCache after ${KILL_DELAY}s."
+    echo ""
+
+    # Step 2: Bench with mid-flight LMCache kill
+    echo "============================================"
+    echo "=== Step 2: Bench with mid-flight LMCache kill ==="
+    echo "============================================"
+
+    run_bench "Mid-flight kill" "bench_midflight.json" &
+    BENCH_PID=$!
+
+    echo "Waiting ${KILL_DELAY}s before killing LMCache container..."
+    sleep "$KILL_DELAY"
+
+    echo "Killing LMCache container: $LMCACHE_CONTAINER_NAME"
+    docker kill "$LMCACHE_CONTAINER_NAME" 2>/dev/null || true
+    docker rm -f "$LMCACHE_CONTAINER_NAME" 2>/dev/null || true
+    echo "LMCache container killed."
+
+    echo "Waiting for bench to complete..."
+    if ! wait "$BENCH_PID"; then
+        echo "Bench did not complete after mid-flight LMCache kill"
+        echo "--- vLLM container logs ---"
+        docker logs --tail 50 "$VLLM_CONTAINER_NAME" 2>&1 || true
+        exit 1
+    fi
+    echo ""
+
+    # Step 3: Quick curl health check
+    echo "============================================"
+    echo "=== Step 3: Quick curl health check ==="
+    echo "============================================"
+    for i in 1 2 3; do
+        if ! curl -sf --max-time 120 \
+            "http://localhost:${VLLM_PORT}/v1/completions" \
+            -H "Content-Type: application/json" \
+            -d "{
+                \"model\": \"$MODEL\",
+                \"prompt\": \"Question: What is $i + $i?\\nAnswer:\",
+                \"max_tokens\": 32,
+                \"temperature\": 0
+            }" > /dev/null 2>&1; then
+            echo "Request $i failed - vLLM became unresponsive"
+            exit 1
+        fi
+        echo "  Request $i: OK"
+    done
+    echo "vLLM still responsive"
+    echo ""
+
+    # Summary
+    warmup_dur=$(python3 -c "import json; print(f\"{json.load(open('$FT_RESULTS_DIR/bench_warmup.json'))['duration']:.1f}\")")
+    midflight_dur=$(python3 -c "import json; print(f\"{json.load(open('$FT_RESULTS_DIR/bench_midflight.json'))['duration']:.1f}\")")
+
+    echo "============================================"
+    echo "=== Fault Tolerance Test PASSED ==="
+    echo "============================================"
+    echo "  Warmup:            $NUM_PROMPTS/$NUM_PROMPTS in ${warmup_dur}s"
+    echo "  Mid-flight kill:   $NUM_PROMPTS/$NUM_PROMPTS in ${midflight_dur}s (killed at +${KILL_DELAY}s)"
+    echo "  Results: $FT_RESULTS_DIR/"
+}
+
+main "$@"
diff --git a/.buildkite/scripts/multiprocessing-test/run-lm-eval.sh b/.buildkite/scripts/multiprocessing-test/run-lm-eval.sh
new file mode 100755
index 0000000..2bce6ac
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/run-lm-eval.sh
@@ -0,0 +1,140 @@
+#!/bin/bash
+# Run lm_eval workload test against vLLM server
+# This script sends the same requests twice to test LMCache caching behavior
+
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source common utilities
+source "$SCRIPT_DIR/common.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+NUM_CONCURRENT="${NUM_CONCURRENT:-50}"
+LIMIT="${LIMIT:-300}"
+
+# Output directories for first and second runs (subdirectories of shared RESULTS_DIR)
+LM_EVAL_DIR="$RESULTS_DIR/lm_eval"
+FIRST_RUN_DIR="$LM_EVAL_DIR/first_run"
+SECOND_RUN_DIR="$LM_EVAL_DIR/second_run"
+
+echo "=== LM-Eval Workload Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port: $VLLM_PORT"
+echo "Concurrent requests: $NUM_CONCURRENT"
+echo "Limit: $LIMIT"
+echo "Virtual env: $VENV_DIR"
+echo "Build ID: $BUILD_ID"
+echo "Results dir: $LM_EVAL_DIR"
+echo ""
+
+# Create results directories
+mkdir -p "$FIRST_RUN_DIR"
+mkdir -p "$SECOND_RUN_DIR"
+
+# Run lm_eval
+run_lm_eval() {
+    local run_name="$1"
+    local output_dir="$2"
+    
+    echo "=== Running lm_eval ($run_name) ==="
+    echo "Output directory: $output_dir"
+    
+    lm_eval --model local-completions --tasks gsm8k \
+        --model_args "model=${MODEL},base_url=http://127.0.0.1:${VLLM_PORT}/v1/completions,num_concurrent=${NUM_CONCURRENT},max_retries=3,tokenized_requests=False" \
+        --limit "$LIMIT" \
+        --seed 0 \
+        -s --output_path "$output_dir" \
+        --gen_kwargs '{"temperature": 0.0}'
+    
+    echo "✅ $run_name completed"
+    echo ""
+}
+
+# Verify that the samples files from two runs are identical
+verify_samples_match() {
+    local first_dir="$1"
+    local second_dir="$2"
+    
+    echo "=== Verifying samples files match ==="
+    
+    # Find samples_gsm8k_*.jsonl files in both directories
+    # lm_eval creates output in: output_path/model_name/samples_task_timestamp.jsonl
+    first_samples=$(find "$first_dir" -name "samples_gsm8k_*.jsonl" -type f 2>/dev/null | head -1)
+    second_samples=$(find "$second_dir" -name "samples_gsm8k_*.jsonl" -type f 2>/dev/null | head -1)
+    
+    if [ -z "$first_samples" ]; then
+        echo "❌ Could not find samples_gsm8k_*.jsonl in first run directory: $first_dir"
+        find "$first_dir" -type f -name "*.jsonl" || true
+        return 1
+    fi
+    
+    if [ -z "$second_samples" ]; then
+        echo "❌ Could not find samples_gsm8k_*.jsonl in second run directory: $second_dir"
+        find "$second_dir" -type f -name "*.jsonl" || true
+        return 1
+    fi
+    
+    echo "First run samples: $first_samples"
+    echo "Second run samples: $second_samples"
+    
+    # Sort both files by a consistent key and compare content
+    # JSONL files may have lines in different order, so we sort them before comparing
+    first_sorted=$(mktemp)
+    second_sorted=$(mktemp)
+    
+    # Sort by the JSON content (each line is a JSON object)
+    sort "$first_samples" > "$first_sorted"
+    sort "$second_samples" > "$second_sorted"
+    
+    if diff -q "$first_sorted" "$second_sorted" > /dev/null 2>&1; then
+        echo "✅ Samples files are identical!"
+        rm -f "$first_sorted" "$second_sorted"
+        return 0
+    else
+        echo "❌ Samples files differ!"
+        echo ""
+        echo "=== Diff (first 50 lines) ==="
+        diff "$first_sorted" "$second_sorted" | head -50 || true
+        rm -f "$first_sorted" "$second_sorted"
+        return 1
+    fi
+}
+
+# Main execution
+main() {
+    setup_venv 'lm-eval[api]' openai pandas
+    
+    # First run - populates cache
+    echo "============================================"
+    echo "=== First lm_eval run (cache population) ==="
+    echo "============================================"
+    run_lm_eval "first_run" "$FIRST_RUN_DIR"
+    
+    # Second run - should use cached results
+    echo "============================================"
+    echo "=== Second lm_eval run (cache hit) ==="
+    echo "============================================"
+    run_lm_eval "second_run" "$SECOND_RUN_DIR"
+    
+    # Verify that the samples from both runs are identical
+    echo "============================================"
+    echo "=== Verifying output consistency ==="
+    echo "============================================"
+    if ! verify_samples_match "$FIRST_RUN_DIR" "$SECOND_RUN_DIR"; then
+        echo "❌ Verification failed: samples files do not match"
+        exit 1
+    fi
+    
+    echo "============================================"
+    echo "=== ✅ LM-Eval workload test completed ==="
+    echo "============================================"
+    echo "Results saved to: $LM_EVAL_DIR"
+    echo "  - First run: $FIRST_RUN_DIR"
+    echo "  - Second run: $SECOND_RUN_DIR"
+}
+
+main "$@"
diff --git a/.buildkite/scripts/multiprocessing-test/run-long-doc-qa.sh b/.buildkite/scripts/multiprocessing-test/run-long-doc-qa.sh
new file mode 100755
index 0000000..ec1df51
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/run-long-doc-qa.sh
@@ -0,0 +1,345 @@
+#!/bin/bash
+# Run long_doc_qa workload test against both vLLM servers
+# Compares performance between LMCache-enabled and baseline vLLM
+
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source common utilities
+source "$SCRIPT_DIR/common.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+
+DOCUMENT_LENGTH="${DOCUMENT_LENGTH:-10000}"
+NUM_DOCUMENTS="${NUM_DOCUMENTS:-30}"
+OUTPUT_LEN="${OUTPUT_LEN:-200}"
+
+REPEAT_COUNT="${REPEAT_COUNT:-2}"
+REPEAT_MODE="${REPEAT_MODE:-tile}"
+SHUFFLE_SEED="${SHUFFLE_SEED:-0}"
+MAX_INFLIGHT_REQUESTS="${MAX_INFLIGHT_REQUESTS:-5}"
+
+# Performance thresholds for LMCache (test fails if exceeded)
+# 0.22s for loading 10K tokens of Qwen3-14B
+# 0.50s for query round time of Qwen3-14B
+MAX_LMCACHE_TTFT="${MAX_LMCACHE_TTFT:-0.22}"
+MAX_LMCACHE_QUERY_ROUND_TIME="${MAX_LMCACHE_QUERY_ROUND_TIME:-0.50}"
+
+# Output directory (subdirectory of shared RESULTS_DIR)
+LONG_DOC_QA_DIR="$RESULTS_DIR/long_doc_qa"
+
+echo "=== Long Doc QA Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port (with LMCache): $VLLM_PORT"
+echo "vLLM Baseline Port (without LMCache): $VLLM_BASELINE_PORT"
+echo "Document length: $DOCUMENT_LENGTH"
+echo "Number of documents: $NUM_DOCUMENTS"
+echo "Output length: $OUTPUT_LEN"
+echo "Repeat count: $REPEAT_COUNT"
+echo "Repeat mode: $REPEAT_MODE"
+echo "Shuffle seed: $SHUFFLE_SEED"
+echo "Max inflight requests: $MAX_INFLIGHT_REQUESTS"
+echo "Virtual env: $VENV_DIR"
+echo "Build ID: $BUILD_ID"
+echo "Results dir: $LONG_DOC_QA_DIR"
+echo ""
+echo "Performance thresholds (LMCache):"
+echo "  Max TTFT: ${MAX_LMCACHE_TTFT}s"
+echo "  Max query round time: ${MAX_LMCACHE_QUERY_ROUND_TIME}s"
+echo ""
+
+# Create results directory
+mkdir -p "$LONG_DOC_QA_DIR"
+
+# Run long_doc_qa benchmark
+run_long_doc_qa() {
+    local port="$1"
+    local result_file="$2"
+    local description="$3"
+    
+    echo "=== Running long_doc_qa ($description) ==="
+    echo "Port: $port"
+    echo "Result file: $result_file"
+    
+    local output_file="$LONG_DOC_QA_DIR/${description}_output.txt"
+    
+    # Run long_doc_qa.py and capture JSON output
+    python3 "$LMCACHE_DIR/benchmarks/long_doc_qa/long_doc_qa.py" \
+        --port "$port" \
+        --model "$MODEL" \
+        --document-length "$DOCUMENT_LENGTH" \
+        --num-documents "$NUM_DOCUMENTS" \
+        --output-len "$OUTPUT_LEN" \
+        --repeat-count "$REPEAT_COUNT" \
+        --repeat-mode "$REPEAT_MODE" \
+        --shuffle-seed "$SHUFFLE_SEED" \
+        --max-inflight-requests "$MAX_INFLIGHT_REQUESTS" \
+        --output "$output_file" \
+        --json-output \
+        2>>"$output_file" | tee "$result_file"
+    
+    echo "✅ $description benchmark completed"
+    echo ""
+}
+
+# Extract a field from JSON file (last line)
+extract_json_field() {
+    local json_file="$1"
+    local field="$2"
+    
+    # Get the last line which should be the JSON output
+    local json_line
+    json_line=$(tail -n 1 "$json_file")
+    
+    python3 -c "
+import json
+import sys
+try:
+    data = json.loads('$json_line')
+    value = data.get('$field', 'null')
+    print(value if value is not None else 'null')
+except json.JSONDecodeError:
+    print('null')
+"
+}
+
+# Compare and summarize results
+compare_results() {
+    local lmcache_result="$LONG_DOC_QA_DIR/lmcache_result.json"
+    local baseline_result="$LONG_DOC_QA_DIR/baseline_result.json"
+    
+    echo "=== Comparing benchmark results ==="
+    
+    # Check if result files exist
+    if [ ! -f "$lmcache_result" ]; then
+        echo "❌ LMCache result file not found: $lmcache_result"
+        return 1
+    fi
+    
+    if [ ! -f "$baseline_result" ]; then
+        echo "❌ Baseline result file not found: $baseline_result"
+        return 1
+    fi
+    
+    # Extract values from LMCache result
+    lmcache_query_ttft=$(extract_json_field "$lmcache_result" "query_ttft_per_prompt")
+    lmcache_query_round_time=$(extract_json_field "$lmcache_result" "query_round_time_per_prompt")
+    lmcache_warmup_round_time=$(extract_json_field "$lmcache_result" "warmup_round_time_per_prompt")
+    
+    # Extract values from baseline result
+    baseline_query_ttft=$(extract_json_field "$baseline_result" "query_ttft_per_prompt")
+    baseline_query_round_time=$(extract_json_field "$baseline_result" "query_round_time_per_prompt")
+    baseline_warmup_round_time=$(extract_json_field "$baseline_result" "warmup_round_time_per_prompt")
+    
+    echo ""
+    echo "============================================"
+    echo "=== Performance Summary ==="
+    echo "============================================"
+    echo ""
+    
+    # Calculate and display comparison
+    python3 << EOF
+import sys
+
+def safe_float(val):
+    try:
+        return float(val)
+    except (ValueError, TypeError):
+        return None
+
+failed = False
+
+def format_comparison(name, lmcache_val, baseline_val):
+    global failed
+    lmcache = safe_float(lmcache_val)
+    baseline = safe_float(baseline_val)
+
+    if lmcache is None or baseline is None:
+        return f"{name}: Unable to compare (invalid values)"
+
+    if baseline > 0:
+        diff_pct = ((lmcache - baseline) / baseline) * 100
+        if diff_pct < 0:
+            status = "✅ FASTER"
+            diff_str = f"{abs(diff_pct):.2f}% faster"
+        elif diff_pct > 10:
+            status = "❌ SLOWER"
+            diff_str = f"{diff_pct:.2f}% slower"
+            failed = True
+        else:
+            status = "✅ OK"
+            diff_str = f"{diff_pct:.2f}% slower"
+    else:
+        status = "⚠️"
+        diff_str = "N/A"
+
+    return f"{name}:\n  Baseline:  {baseline:.4f}s\n  LMCache:   {lmcache:.4f}s\n  Diff:      {diff_str} {status}"
+
+print("=" * 50)
+print("Query TTFT per Prompt (Time to First Token)")
+print("=" * 50)
+print(format_comparison("query_ttft_per_prompt", "$lmcache_query_ttft", "$baseline_query_ttft"))
+print()
+
+print("=" * 50)
+print("Query Round Time per Prompt (End-to-End Latency)")
+print("=" * 50)
+print(format_comparison("query_round_time_per_prompt", "$lmcache_query_round_time", "$baseline_query_round_time"))
+print()
+
+print("=" * 50)
+print("Warmup Round Time per Prompt")
+print("=" * 50)
+print(format_comparison("warmup_round_time_per_prompt", "$lmcache_warmup_round_time", "$baseline_warmup_round_time"))
+print()
+
+# Summary table
+print("=" * 50)
+print("Summary Table")
+print("=" * 50)
+print(f"{'Metric':<35} {'Baseline':>12} {'LMCache':>12} {'Diff':>10}")
+print("-" * 70)
+
+metrics = [
+    ("query_ttft_per_prompt", "$baseline_query_ttft", "$lmcache_query_ttft"),
+    ("query_round_time_per_prompt", "$baseline_query_round_time", "$lmcache_query_round_time"),
+    ("warmup_round_time_per_prompt", "$baseline_warmup_round_time", "$lmcache_warmup_round_time"),
+]
+
+for name, baseline_val, lmcache_val in metrics:
+    baseline = safe_float(baseline_val)
+    lmcache = safe_float(lmcache_val)
+
+    if baseline is not None and lmcache is not None:
+        if baseline > 0:
+            diff_pct = ((lmcache - baseline) / baseline) * 100
+            diff_str = f"{diff_pct:+.1f}%"
+        else:
+            diff_str = "N/A"
+        print(f"{name:<35} {baseline:>12.4f} {lmcache:>12.4f} {diff_str:>10}")
+    else:
+        print(f"{name:<35} {'N/A':>12} {'N/A':>12} {'N/A':>10}")
+
+print()
+
+if failed:
+    print("❌ LMCache is significantly slower (>10%) than baseline on one or more metrics")
+    sys.exit(1)
+else:
+    print("✅ LMCache performance is within acceptable range")
+    sys.exit(0)
+EOF
+}
+
+# Verify LMCache performance meets thresholds
+verify_thresholds() {
+    local lmcache_result="$LONG_DOC_QA_DIR/lmcache_result.json"
+    
+    echo "=== Verifying LMCache performance thresholds ==="
+    echo "Max allowed TTFT: ${MAX_LMCACHE_TTFT}s"
+    echo "Max allowed query round time: ${MAX_LMCACHE_QUERY_ROUND_TIME}s"
+    echo ""
+    
+    # Extract LMCache values
+    lmcache_query_ttft=$(extract_json_field "$lmcache_result" "query_ttft_per_prompt")
+    lmcache_query_round_time=$(extract_json_field "$lmcache_result" "query_round_time_per_prompt")
+    
+    # Verify thresholds using Python
+    python3 << EOF
+import sys
+
+def safe_float(val):
+    try:
+        return float(val)
+    except (ValueError, TypeError):
+        return None
+
+ttft = safe_float("$lmcache_query_ttft")
+query_round_time = safe_float("$lmcache_query_round_time")
+max_ttft = float("$MAX_LMCACHE_TTFT")
+max_query_round_time = float("$MAX_LMCACHE_QUERY_ROUND_TIME")
+
+failed = False
+
+print("=" * 50)
+print("Threshold Verification")
+print("=" * 50)
+
+# Check TTFT
+if ttft is None:
+    print("❌ query_ttft_per_prompt: Unable to parse value")
+    failed = True
+elif ttft <= max_ttft:
+    print(f"✅ query_ttft_per_prompt: {ttft:.4f}s <= {max_ttft}s (PASS)")
+else:
+    print(f"❌ query_ttft_per_prompt: {ttft:.4f}s > {max_ttft}s (FAIL)")
+    failed = True
+
+# Check query round time
+if query_round_time is None:
+    print("❌ query_round_time_per_prompt: Unable to parse value")
+    failed = True
+elif query_round_time <= max_query_round_time:
+    print(f"✅ query_round_time_per_prompt: {query_round_time:.4f}s <= {max_query_round_time}s (PASS)")
+else:
+    print(f"❌ query_round_time_per_prompt: {query_round_time:.4f}s > {max_query_round_time}s (FAIL)")
+    failed = True
+
+print()
+
+if failed:
+    print("❌ Threshold verification FAILED")
+    sys.exit(1)
+else:
+    print("✅ All thresholds passed")
+    sys.exit(0)
+EOF
+}
+
+# Main execution
+main() {
+    setup_venv openai pandas matplotlib
+    
+    # Run benchmark against baseline vLLM (without LMCache)
+    echo "============================================"
+    echo "=== Benchmark: Baseline vLLM (without LMCache) ==="
+    echo "============================================"
+    run_long_doc_qa "$VLLM_BASELINE_PORT" "$LONG_DOC_QA_DIR/baseline_result.json" "baseline"
+    
+    # Run benchmark against vLLM with LMCache
+    echo "============================================"
+    echo "=== Benchmark: vLLM with LMCache ==="
+    echo "============================================"
+    run_long_doc_qa "$VLLM_PORT" "$LONG_DOC_QA_DIR/lmcache_result.json" "lmcache"
+    
+    # Compare and summarize results
+    echo "============================================"
+    echo "=== Comparing Results ==="
+    echo "============================================"
+    if ! compare_results; then
+        echo "❌ Comparison failed"
+        exit 1
+    fi
+    
+    # Verify LMCache performance meets thresholds (soft-fail: warn but don't exit)
+    echo "============================================"
+    echo "=== Verifying Performance Thresholds ==="
+    echo "============================================"
+    if ! verify_thresholds; then
+        echo "⚠️ Threshold verification failed (soft-fail, not blocking)"
+    fi
+    
+    echo "============================================"
+    echo "=== ✅ Long Doc QA test completed ==="
+    echo "============================================"
+    echo "Results saved to: $LONG_DOC_QA_DIR"
+    echo "  - LMCache: $LONG_DOC_QA_DIR/lmcache_result.json"
+    echo "  - Baseline: $LONG_DOC_QA_DIR/baseline_result.json"
+}
+
+main "$@"
diff --git a/.buildkite/scripts/multiprocessing-test/run-mp-test.sh b/.buildkite/scripts/multiprocessing-test/run-mp-test.sh
new file mode 100755
index 0000000..6149365
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/run-mp-test.sh
@@ -0,0 +1,128 @@
+#!/bin/bash
+# Main orchestrator script for multiprocessing tests
+# This script ensures cleanup always runs, even on failure
+
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Export container names and configuration for all scripts
+export LMCACHE_CONTAINER_NAME="lmcache-mp-test-$$"
+export VLLM_CONTAINER_NAME="vllm-mp-test-$$"
+export VLLM_BASELINE_CONTAINER_NAME="vllm-baseline-test-$$"
+export LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+export VLLM_PORT="${VLLM_PORT:-8000}"
+export VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+export MAX_WAIT_SECONDS="${MAX_WAIT_SECONDS:-300}"
+export BUILD_ID="${BUILD_ID:-local_$$}"
+
+# Track the overall test result
+TEST_RESULT=0
+
+# Cleanup function - always runs on exit
+cleanup() {
+    echo ""
+    echo "============================================"
+    echo "=== Running cleanup (exit code: $TEST_RESULT) ==="
+    echo "============================================"
+    "$SCRIPT_DIR/cleanup.sh"
+}
+
+# Register cleanup to run on exit (covers normal exit, errors, and signals)
+trap cleanup EXIT
+
+echo "============================================"
+echo "=== LMCache Multiprocessing Test ==="
+echo "============================================"
+echo "Build ID: $BUILD_ID"
+echo "LMCache container: $LMCACHE_CONTAINER_NAME"
+echo "vLLM container: $VLLM_CONTAINER_NAME"
+echo "vLLM baseline container: $VLLM_BASELINE_CONTAINER_NAME"
+echo "LMCache port: $LMCACHE_PORT"
+echo "vLLM port: $VLLM_PORT"
+echo "vLLM baseline port: $VLLM_BASELINE_PORT"
+echo ""
+
+# Step 1: Build docker images
+echo "============================================"
+echo "=== Step 1: Building Docker images ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/build-mp-docker-image.sh"; then
+    echo "❌ Failed to build docker images"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 2: Launch containers
+echo "============================================"
+echo "=== Step 2: Launching containers ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/launch-containers.sh"; then
+    echo "❌ Failed to launch containers"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 3: Wait for vLLM to be ready
+echo "============================================"
+echo "=== Step 3: Waiting for vLLM to be ready ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/wait-for-vllm.sh"; then
+    echo "❌ vLLM failed to become ready"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 4: Run lm_eval workload test
+echo "============================================"
+echo "=== Step 4: Running lm_eval workload ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/run-lm-eval.sh"; then
+    echo "❌ lm_eval workload test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 5: Run vllm bench serve test
+echo "============================================"
+echo "=== Step 5: Running vllm bench serve ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/run-vllm-bench.sh"; then
+    echo "❌ vllm bench serve test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 6: Run long doc QA test
+echo "============================================"
+echo "=== Step 6: Running long doc QA ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/run-long-doc-qa.sh"; then
+    echo "❌ long doc QA test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+# Step 7: Run fault tolerance test (destructive — kills LMCache container)
+echo "============================================"
+echo "=== Step 7: Running fault tolerance test ==="
+echo "============================================"
+if ! "$SCRIPT_DIR/run-fault-tolerance.sh"; then
+    echo "❌ fault tolerance test failed"
+    TEST_RESULT=1
+    exit 1
+fi
+echo ""
+
+echo "============================================"
+echo "=== ✅ All tests passed! ==="
+echo "============================================"
+
+# Step 8: Cleanup runs automatically via trap
+
diff --git a/.buildkite/scripts/multiprocessing-test/run-vllm-bench.sh b/.buildkite/scripts/multiprocessing-test/run-vllm-bench.sh
new file mode 100755
index 0000000..8e1e201
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/run-vllm-bench.sh
@@ -0,0 +1,253 @@
+#!/bin/bash
+# Run vllm bench serve test against both vLLM servers
+# Compares performance between LMCache-enabled and baseline vLLM
+
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source common utilities
+source "$SCRIPT_DIR/common.sh"
+
+# Configuration
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+NUM_PROMPTS="${NUM_PROMPTS:-50}"
+RANDOM_INPUT_LEN="${RANDOM_INPUT_LEN:-10000}"
+RANDOM_OUTPUT_LEN="${RANDOM_OUTPUT_LEN:-1}"
+
+# Expected values
+EXPECTED_TOTAL_INPUT_TOKENS=$((NUM_PROMPTS * RANDOM_INPUT_LEN))
+EXPECTED_COMPLETED=$NUM_PROMPTS
+MAX_SLOWDOWN_PERCENT=5
+
+# Generate a random seed once for reproducibility across both benchmarks
+RANDOM_SEED="${RANDOM_SEED:-$(date +%s)}"
+
+# Output directory (subdirectory of shared RESULTS_DIR)
+VLLM_BENCH_DIR="$RESULTS_DIR/vllm_bench"
+
+echo "=== vLLM Bench Serve Test ==="
+echo "Model: $MODEL"
+echo "vLLM Port (with LMCache): $VLLM_PORT"
+echo "vLLM Baseline Port (without LMCache): $VLLM_BASELINE_PORT"
+echo "Number of prompts: $NUM_PROMPTS"
+echo "Random input length: $RANDOM_INPUT_LEN"
+echo "Random output length: $RANDOM_OUTPUT_LEN"
+echo "Virtual env: $VENV_DIR"
+echo "Build ID: $BUILD_ID"
+echo "Results dir: $VLLM_BENCH_DIR"
+echo ""
+
+# Create results directory
+mkdir -p "$VLLM_BENCH_DIR"
+
+# Run vllm bench serve
+run_vllm_bench() {
+    local port="$1"
+    local result_filename="$2"
+    local description="$3"
+    local seed="$4"
+    
+    echo "=== Running vllm bench serve ($description) ==="
+    echo "Port: $port"
+    echo "Seed: $seed"
+    echo "Result file: $VLLM_BENCH_DIR/$result_filename"
+    
+    vllm bench serve \
+        --seed "$seed" \
+        --port "$port" \
+        --model "$MODEL" \
+        --dataset-name random \
+        --random-input-len "$RANDOM_INPUT_LEN" \
+        --random-output-len "$RANDOM_OUTPUT_LEN" \
+        --num-prompts "$NUM_PROMPTS" \
+        --ignore-eos \
+        --backend openai-chat \
+        --endpoint /v1/chat/completions \
+        --result-dir "$VLLM_BENCH_DIR" \
+        --result-filename "$result_filename" \
+        --save-result
+    
+    echo "✅ $description benchmark completed"
+    echo ""
+}
+
+# Extract a numeric field from JSON file
+extract_json_field() {
+    local json_file="$1"
+    local field="$2"
+    
+    python3 -c "
+import json
+with open('$json_file', 'r') as f:
+    data = json.load(f)
+print(data.get('$field', 'null'))
+"
+}
+
+# Verify benchmark results
+verify_results() {
+    local lmcache_result="$VLLM_BENCH_DIR/lmcache.json"
+    local baseline_result="$VLLM_BENCH_DIR/baseline.json"
+    
+    echo "=== Verifying benchmark results ==="
+    
+    # Check if result files exist
+    if [ ! -f "$lmcache_result" ]; then
+        echo "❌ LMCache result file not found: $lmcache_result"
+        return 1
+    fi
+    
+    if [ ! -f "$baseline_result" ]; then
+        echo "❌ Baseline result file not found: $baseline_result"
+        return 1
+    fi
+    
+    echo "LMCache result: $lmcache_result"
+    echo "Baseline result: $baseline_result"
+    echo ""
+    
+    # Extract values from LMCache result
+    lmcache_total_input_tokens=$(extract_json_field "$lmcache_result" "total_input_tokens")
+    lmcache_completed=$(extract_json_field "$lmcache_result" "completed")
+    lmcache_throughput=$(extract_json_field "$lmcache_result" "total_token_throughput")
+    
+    # Extract values from baseline result
+    baseline_total_input_tokens=$(extract_json_field "$baseline_result" "total_input_tokens")
+    baseline_completed=$(extract_json_field "$baseline_result" "completed")
+    baseline_throughput=$(extract_json_field "$baseline_result" "total_token_throughput")
+    
+    echo "=== LMCache Results ==="
+    echo "  total_input_tokens: $lmcache_total_input_tokens"
+    echo "  completed: $lmcache_completed"
+    echo "  total_token_throughput: $lmcache_throughput"
+    echo ""
+    
+    echo "=== Baseline Results ==="
+    echo "  total_input_tokens: $baseline_total_input_tokens"
+    echo "  completed: $baseline_completed"
+    echo "  total_token_throughput: $baseline_throughput"
+    echo ""
+    
+    # Verification
+    local failed=0
+    
+    echo "=== Verification ==="
+    
+    # vLLM's random dataset decodes and re-encodes token sequences, which can
+    # drift slightly from the requested length (see RandomDataset in
+    # vllm/benchmarks/datasets.py). Allow 1% tolerance.
+    local token_tolerance=$((EXPECTED_TOTAL_INPUT_TOKENS / 100))
+
+    check_input_tokens() {
+        local label="$1"
+        local actual="$2"
+        local diff=$((actual - EXPECTED_TOTAL_INPUT_TOKENS))
+        local abs_diff=${diff#-}
+        if [ "$abs_diff" -le "$token_tolerance" ] 2>/dev/null; then
+            echo "✅ $label total_input_tokens: $actual (expected: $EXPECTED_TOTAL_INPUT_TOKENS ±$token_tolerance)"
+        else
+            echo "❌ $label total_input_tokens: $actual (expected: $EXPECTED_TOTAL_INPUT_TOKENS ±$token_tolerance)"
+            failed=1
+        fi
+    }
+
+    check_input_tokens "LMCache" "$lmcache_total_input_tokens"
+    check_input_tokens "Baseline" "$baseline_total_input_tokens"
+    
+    # Check completed for LMCache
+    if [ "$lmcache_completed" -eq "$EXPECTED_COMPLETED" ] 2>/dev/null; then
+        echo "✅ LMCache completed: $lmcache_completed (expected: $EXPECTED_COMPLETED)"
+    else
+        echo "❌ LMCache completed: $lmcache_completed (expected: $EXPECTED_COMPLETED)"
+        failed=1
+    fi
+    
+    # Check completed for baseline
+    if [ "$baseline_completed" -eq "$EXPECTED_COMPLETED" ] 2>/dev/null; then
+        echo "✅ Baseline completed: $baseline_completed (expected: $EXPECTED_COMPLETED)"
+    else
+        echo "❌ Baseline completed: $baseline_completed (expected: $EXPECTED_COMPLETED)"
+        failed=1
+    fi
+    
+    # Check throughput comparison (LMCache should not be more than 10% slower)
+    throughput_check=$(python3 -c "
+lmcache_tp = $lmcache_throughput
+baseline_tp = $baseline_throughput
+max_slowdown = $MAX_SLOWDOWN_PERCENT
+
+# Calculate the minimum acceptable throughput (90% of baseline)
+min_acceptable = baseline_tp * (1 - max_slowdown / 100.0)
+
+# Calculate actual slowdown percentage
+if baseline_tp > 0:
+    slowdown_pct = ((baseline_tp - lmcache_tp) / baseline_tp) * 100
+else:
+    slowdown_pct = 0
+
+if lmcache_tp >= min_acceptable:
+    print(f'PASS|{slowdown_pct:.2f}')
+else:
+    print(f'FAIL|{slowdown_pct:.2f}')
+")
+    
+    throughput_status=$(echo "$throughput_check" | cut -d'|' -f1)
+    slowdown_pct=$(echo "$throughput_check" | cut -d'|' -f2)
+    
+    if [ "$throughput_status" = "PASS" ]; then
+        echo "✅ Throughput comparison: LMCache is ${slowdown_pct}% slower (max allowed: ${MAX_SLOWDOWN_PERCENT}%)"
+    else
+        echo "❌ Throughput comparison: LMCache is ${slowdown_pct}% slower (max allowed: ${MAX_SLOWDOWN_PERCENT}%)"
+        failed=1
+    fi
+    
+    echo ""
+    
+    if [ "$failed" -eq 1 ]; then
+        return 1
+    fi
+    
+    return 0
+}
+
+# Main execution
+main() {
+    setup_venv vllm openai
+    
+    echo "Using random seed: $RANDOM_SEED"
+    echo ""
+    
+    # Run benchmark against baseline vLLM (without LMCache)
+    echo "============================================"
+    echo "=== Benchmark: Baseline vLLM (without LMCache) ==="
+    echo "============================================"
+    run_vllm_bench "$VLLM_BASELINE_PORT" "baseline.json" "Baseline vLLM" "$RANDOM_SEED"
+    
+    # Run benchmark against vLLM with LMCache
+    echo "============================================"
+    echo "=== Benchmark: vLLM with LMCache ==="
+    echo "============================================"
+    run_vllm_bench "$VLLM_PORT" "lmcache.json" "vLLM with LMCache" "$RANDOM_SEED"
+    
+    # Verify results
+    echo "============================================"
+    echo "=== Verifying benchmark results ==="
+    echo "============================================"
+    if ! verify_results; then
+        echo "❌ Verification failed"
+        exit 1
+    fi
+    
+    echo "============================================"
+    echo "=== ✅ vLLM Bench test completed ==="
+    echo "============================================"
+    echo "Results saved to: $VLLM_BENCH_DIR"
+    echo "  - LMCache: $VLLM_BENCH_DIR/lmcache.json"
+    echo "  - Baseline: $VLLM_BENCH_DIR/baseline.json"
+}
+
+main "$@"
diff --git a/.buildkite/scripts/multiprocessing-test/test-launch.sh b/.buildkite/scripts/multiprocessing-test/test-launch.sh
new file mode 100755
index 0000000..4313054
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/test-launch.sh
@@ -0,0 +1,106 @@
+#!/bin/bash
+# Launch LMCache and vLLM containers for multiprocessing tests
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Container names (exported so cleanup script can use them)
+export LMCACHE_CONTAINER_NAME="${LMCACHE_CONTAINER_NAME:-lmcache-mp-test}"
+export VLLM_CONTAINER_NAME="${VLLM_CONTAINER_NAME:-vllm-mp-test}"
+export VLLM_BASELINE_CONTAINER_NAME="${VLLM_BASELINE_CONTAINER_NAME:-vllm-baseline-test}"
+
+# Configuration
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+
+CPU_BUFFER_SIZE="${CPU_BUFFER_SIZE:-80}"
+MAX_WORKERS="${MAX_WORKERS:-4}"
+MODEL="${MODEL:-Qwen/Qwen3-14B}"
+
+# Check GPU memory and set gpu-memory-utilization if > 100GB
+GPU_MEMORY_UTIL_ARG=""
+GPU_MEMORY_MB=$(nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits | head -n 1 | tr -d ' ')
+GPU_MEMORY_GB=$((GPU_MEMORY_MB / 1024))
+echo "Detected GPU memory: ${GPU_MEMORY_GB}GB (${GPU_MEMORY_MB}MB)"
+
+if [ "$GPU_MEMORY_GB" -gt 90 ]; then
+    echo "GPU memory > 100GB, adding --gpu-memory-utilization 0.5"
+    GPU_MEMORY_UTIL_ARG="--gpu-memory-utilization 0.5"
+fi
+
+echo "=== Launching LMCache container ==="
+echo "Container name: $LMCACHE_CONTAINER_NAME"
+echo "Port: $LMCACHE_PORT"
+
+docker run -d \
+    --name "$LMCACHE_CONTAINER_NAME" \
+    --runtime nvidia \
+    --gpus all \
+    --network host \
+    --ipc host \
+    --entrypoint /opt/venv/bin/python3 \
+    lmcache/vllm-openai:test \
+    -m lmcache.v1.multiprocess.server \
+    --cpu-buffer-size "$CPU_BUFFER_SIZE" \
+    --max-workers "$MAX_WORKERS" \
+    --port "$LMCACHE_PORT"
+
+echo "LMCache container started"
+
+# Wait a bit for LMCache to initialize
+echo "Waiting for LMCache to initialize..."
+sleep 10
+
+echo "=== Launching vLLM container ==="
+echo "Container name: $VLLM_CONTAINER_NAME"
+echo "Model: $MODEL"
+
+docker run -d \
+    --name "$VLLM_CONTAINER_NAME" \
+    --runtime nvidia \
+    --gpus all \
+    --volume /data1/yihua-model:/root/.cache/huggingface \
+    --network host \
+    --ipc host \
+    --env CUDA_VISIBLE_DEVICES=0 \
+    --env VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    --env VLLM_ATTENTION_BACKEND=FLASH_ATTN \
+    --env VLLM_BATCH_INVARIANT=1 \
+    --env PYTHONHASHSEED=0 \
+    lmcache/vllm-openai:test \
+    "$MODEL" \
+    --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_load_failure_policy\": \"recompute\", \"kv_connector_extra_config\": {\"lmcache.mp.port\": $LMCACHE_PORT, \"lmcache.mp.mq_timeout\": 10}}" \
+    --port "$VLLM_PORT" \
+    --no-async-scheduling \
+    $GPU_MEMORY_UTIL_ARG
+
+echo "vLLM container started"
+
+echo "=== Launching vLLM baseline container (without LMCache) ==="
+echo "Container name: $VLLM_BASELINE_CONTAINER_NAME"
+echo "Port: $VLLM_BASELINE_PORT"
+
+docker run -d \
+    --name "$VLLM_BASELINE_CONTAINER_NAME" \
+    --runtime nvidia \
+    --gpus all \
+    --volume /data1/yihua-model:/root/.cache/huggingface \
+    --network host \
+    --ipc host \
+    --env CUDA_VISIBLE_DEVICES=1 \
+    --env VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    --env VLLM_ATTENTION_BACKEND=FLASH_ATTN \
+    --env VLLM_BATCH_INVARIANT=1 \
+    --env PYTHONHASHSEED=0 \
+    lmcache/vllm-openai:test \
+    "$MODEL" \
+    --port "$VLLM_BASELINE_PORT" \
+    --no-async-scheduling \
+    $GPU_MEMORY_UTIL_ARG
+
+echo "vLLM baseline container started"
+
+echo "=== Containers launched ==="
+docker ps --filter "name=$LMCACHE_CONTAINER_NAME" --filter "name=$VLLM_CONTAINER_NAME" --filter "name=$VLLM_BASELINE_CONTAINER_NAME"
+
diff --git a/.buildkite/scripts/multiprocessing-test/wait-for-vllm.sh b/.buildkite/scripts/multiprocessing-test/wait-for-vllm.sh
new file mode 100755
index 0000000..0c8f5de
--- /dev/null
+++ b/.buildkite/scripts/multiprocessing-test/wait-for-vllm.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+# Wait for vLLM servers to be ready
+set -e
+
+VLLM_PORT="${VLLM_PORT:-8000}"
+VLLM_BASELINE_PORT="${VLLM_BASELINE_PORT:-9000}"
+MAX_WAIT_SECONDS="${MAX_WAIT_SECONDS:-600}"
+VLLM_CONTAINER_NAME="${VLLM_CONTAINER_NAME:-vllm-mp-test}"
+VLLM_BASELINE_CONTAINER_NAME="${VLLM_BASELINE_CONTAINER_NAME:-vllm-baseline-test}"
+
+# Function to wait for a single vLLM server
+wait_for_vllm_server() {
+    local port="$1"
+    local container_name="$2"
+    local description="$3"
+    
+    echo "=== Waiting for $description to be ready ==="
+    echo "Port: $port"
+    echo "Container: $container_name"
+    echo "Max wait time: ${MAX_WAIT_SECONDS}s"
+    
+    start_time=$(date +%s)
+    end_time=$((start_time + MAX_WAIT_SECONDS))
+    
+    while true; do
+        current_time=$(date +%s)
+        elapsed=$((current_time - start_time))
+        
+        if [ "$current_time" -ge "$end_time" ]; then
+            echo "❌ Timeout: $description did not become ready within ${MAX_WAIT_SECONDS} seconds"
+            echo ""
+            echo "=== $description container logs ==="
+            docker logs --tail 100 "$container_name" 2>&1 || true
+            return 1
+        fi
+        
+        # Check if container is still running
+        if ! docker ps --format '{{.Names}}' | grep -q "^${container_name}$"; then
+            echo "❌ $description container is not running"
+            echo ""
+            echo "=== $description container logs ==="
+            docker logs "$container_name" 2>&1 || true
+            return 1
+        fi
+        
+        # Check if vLLM health endpoint is responding
+        if curl -sf "http://localhost:${port}/health" > /dev/null 2>&1; then
+            echo "✅ $description is ready! (took ${elapsed}s)"
+            return 0
+        fi
+        
+        # Also try the models endpoint as a fallback
+        if curl -sf "http://localhost:${port}/v1/models" > /dev/null 2>&1; then
+            echo "✅ $description is ready! (took ${elapsed}s)"
+            return 0
+        fi
+        
+        echo "Waiting for $description... (${elapsed}s elapsed)"
+        sleep 5
+    done
+}
+
+# Wait for vLLM with LMCache
+if ! wait_for_vllm_server "$VLLM_PORT" "$VLLM_CONTAINER_NAME" "vLLM (with LMCache)"; then
+    exit 1
+fi
+
+echo ""
+
+# Wait for vLLM baseline (without LMCache)
+if ! wait_for_vllm_server "$VLLM_BASELINE_PORT" "$VLLM_BASELINE_CONTAINER_NAME" "vLLM baseline (without LMCache)"; then
+    exit 1
+fi
+
+echo ""
+echo "=== All vLLM servers are ready ==="
+
diff --git a/.buildkite/scripts/pick-free-gpu-amd.sh b/.buildkite/scripts/pick-free-gpu-amd.sh
new file mode 100644
index 0000000..60759f8
--- /dev/null
+++ b/.buildkite/scripts/pick-free-gpu-amd.sh
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Usage: source pick-free-gpu-amd.sh <MIN_FREE_MEM_MB> <GPU_COUNT>
+# Select AMD GPUs (ROCm) by free VRAM (computed from Total-Used) and low util.
+
+MIN_FREE_MEM="${1:-10000}"      # MiB (default 10 GiB)
+REQUESTED_GPU_COUNT="${2:-1}"   # number of GPUs to select
+MAX_UTIL="${MAX_UTIL:-20}"      # (%)
+GPU_LIMIT="${GPU_LIMIT:-8}"     # only consider GPU index < GPU_LIMIT (default 8 for your node)
+TIMEOUT_SECONDS="${TIMEOUT_SECONDS:-3600}"
+INTERVAL="${INTERVAL:-10}"
+
+start_time=$(date +%s)
+
+if ! command -v rocm-smi >/dev/null 2>&1; then
+  echo "❌ rocm-smi not found. Are you on an AMD/ROCm machine?"
+  return 1 2>/dev/null || exit 1
+fi
+
+# Return candidates as lines: "free_mib,util,idx"
+get_candidates() {
+  rocm-smi --showmeminfo vram --showuse 2>/dev/null | awk \
+    -v min_mem="$MIN_FREE_MEM" \
+    -v max_util="$MAX_UTIL" \
+    -v gpu_limit="$GPU_LIMIT" '
+    function mib_from_bytes(b) { return int(b / (1024*1024)) }
+
+    # Util lines: "GPU[3] : GPU use (%): 0"
+    /GPU\[[0-9]+\][[:space:]]*:[[:space:]]*GPU use[[:space:]]*\(%\):/ {
+      if (match($0, /GPU\[([0-9]+)\]/, m)) idx=m[1]; else next
+      if (idx+0 >= gpu_limit) next
+      if (match($0, /GPU use[[:space:]]*\(%\):[[:space:]]*([0-9]+)/, u)) util=u[1]; else next
+      gpu_util[idx]=util+0
+      next
+    }
+
+    # Total bytes: "GPU[3] : VRAM Total Memory (B): 206141652992"
+    /GPU\[[0-9]+\][[:space:]]*:[[:space:]]*VRAM Total Memory \(B\):/ {
+      if (match($0, /GPU\[([0-9]+)\]/, m)) idx=m[1]; else next
+      if (idx+0 >= gpu_limit) next
+      if (match($0, /VRAM Total Memory \(B\):[[:space:]]*([0-9]+)/, t)) total=t[1]; else next
+      vram_total[idx]=total+0
+      next
+    }
+
+    # Used bytes: "GPU[3] : VRAM Total Used Memory (B): 303304704"
+    /GPU\[[0-9]+\][[:space:]]*:[[:space:]]*VRAM Total Used Memory \(B\):/ {
+      if (match($0, /GPU\[([0-9]+)\]/, m)) idx=m[1]; else next
+      if (idx+0 >= gpu_limit) next
+      if (match($0, /VRAM Total Used Memory \(B\):[[:space:]]*([0-9]+)/, t)) used=t[1]; else next
+      vram_used[idx]=used+0
+      next
+    }
+
+    END {
+      for (i=0; i<gpu_limit; i++) {
+        if ((i in vram_total) && (i in vram_used) && (i in gpu_util)) {
+          free_bytes = vram_total[i] - vram_used[i]
+          free_mib = mib_from_bytes(free_bytes)
+          util = gpu_util[i] + 0
+          if (free_mib >= min_mem && util <= max_util) {
+            print free_mib "," util "," i
+          }
+        }
+      }
+    }'
+}
+
+while true; do
+  now=$(date +%s)
+  elapsed=$((now - start_time))
+
+  if (( elapsed >= TIMEOUT_SECONDS )); then
+    echo "❌ Timeout: No suitable GPU found within ${TIMEOUT_SECONDS}s (min_free=${MIN_FREE_MEM}MiB, max_util=${MAX_UTIL}%, gpu_limit=${GPU_LIMIT})"
+    return 1 2>/dev/null || exit 1
+  fi
+
+  mapfile -t candidates < <(get_candidates)
+
+  if [ "${#candidates[@]}" -gt 0 ]; then
+    # Sort by free_mib desc, util asc, idx asc
+    mapfile -t top_gpus < <(
+      printf "%s\n" "${candidates[@]}" \
+        | sort -t',' -k1,1nr -k2,2n -k3,3n \
+        | head -n"${REQUESTED_GPU_COUNT}" \
+        | awk -F',' '{print $3}'
+    )
+
+    if [ "${#top_gpus[@]}" -eq 1 ]; then
+      export HIP_VISIBLE_DEVICES="${top_gpus[0]}"
+      export CUDA_VISIBLE_DEVICES="${top_gpus[0]}"  # compatibility for some frameworks/scripts
+      echo "✅ Selected GPU #${top_gpus[0]} (HIP_VISIBLE_DEVICES=${top_gpus[0]})"
+    else
+      chosen_gpus=$(IFS=','; echo "${top_gpus[*]}")
+      export HIP_VISIBLE_DEVICES="${chosen_gpus}"
+      export CUDA_VISIBLE_DEVICES="${chosen_gpus}"
+      gpu_list=$(printf "#%s," "${top_gpus[@]}")
+      echo "✅ Selected GPUs ${gpu_list%,} (HIP_VISIBLE_DEVICES=${chosen_gpus})"
+    fi
+    break
+  fi
+
+  # Not found yet; print one-line status so it doesn't look "hung"
+  echo "⏳ No suitable GPU yet (elapsed=${elapsed}s). Waiting... (min_free=${MIN_FREE_MEM}MiB, max_util=${MAX_UTIL}%, gpu_limit=${GPU_LIMIT})"
+  sleep "${INTERVAL}"
+done
diff --git a/.buildkite/scripts/pick-free-gpu.sh b/.buildkite/scripts/pick-free-gpu.sh
new file mode 100644
index 0000000..4f4e179
--- /dev/null
+++ b/.buildkite/scripts/pick-free-gpu.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+# Usage: source pick-free-gpu.sh <MIN_FREE_MEM_MB> <GPU_COUNT>
+# Selects the specified number of best available GPUs
+MIN_FREE_MEM="${1:-10000}"    # in MiB (default: 10 GB)
+REQUESTED_GPU_COUNT="${2:-1}" # number of GPUs to select (default: 1)
+MAX_UTIL=20                   # hardcoded utilization threshold (%)
+GPU_LIMIT=8                   # reserves GPU 0-7 for CI/Build
+# 60 minutes
+TIMEOUT_SECONDS=3600
+INTERVAL=10
+
+start_time=$(date +%s)
+
+while true; do
+  now=$(date +%s)
+  elapsed=$((now - start_time))
+
+  if (( elapsed >= TIMEOUT_SECONDS )); then
+    echo "❌ Timeout: No suitable GPU found within ${TIMEOUT_SECONDS}s"
+    return 1
+  fi
+
+  mapfile -t candidates < <(
+    nvidia-smi --query-gpu=memory.free,utilization.gpu,index \
+      --format=csv,noheader,nounits \
+    | awk -F',' -v min_mem="$MIN_FREE_MEM" -v max_util="$MAX_UTIL" -v gpu_limit="$GPU_LIMIT" '{
+        mem = $1; util = $2; idx = $3;
+        gsub(/^[ \t]+|[ \t]+$/, "", mem);
+        gsub(/^[ \t]+|[ \t]+$/, "", util);
+        gsub(/^[ \t]+|[ \t]+$/, "", idx);
+        if (mem >= min_mem && util <= max_util && idx < gpu_limit) {
+          print mem "," util "," idx;
+        }
+      }'
+  )
+
+  if [ "${#candidates[@]}" -gt 0 ]; then
+    # select the top N GPUs with the maximum free memory
+    mapfile -t top_gpus < <(
+      printf "%s\n" "${candidates[@]}" \
+        | sort -t',' -k1,1 -nr \
+        | head -n"${REQUESTED_GPU_COUNT}" \
+        | awk -F',' '{print $3}'
+    )
+    
+    # Validate we found the requested number of GPUs
+    if [ "${#top_gpus[@]}" -lt "$REQUESTED_GPU_COUNT" ]; then
+      echo "⚠️  Warning: Requested $REQUESTED_GPU_COUNT GPUs but only found ${#top_gpus[@]} available. Waiting..."
+      sleep $INTERVAL
+      continue
+    fi
+    
+    if [ "${#top_gpus[@]}" -eq 1 ]; then
+      # Only one GPU found/requested
+      export CUDA_VISIBLE_DEVICES="${top_gpus[0]}"
+      echo "✅ Selected GPU #${top_gpus[0]} (CUDA_VISIBLE_DEVICES=${top_gpus[0]})"
+    else
+      # Multiple GPUs found/requested
+      chosen_gpus=$(IFS=','; echo "${top_gpus[*]}")
+      export CUDA_VISIBLE_DEVICES="${chosen_gpus}"
+      gpu_list=$(printf "#%s," "${top_gpus[@]}")
+      echo "✅ Selected GPUs ${gpu_list%,} (CUDA_VISIBLE_DEVICES=${chosen_gpus})"
+    fi
+    break
+  fi
+
+  sleep $INTERVAL
+done
diff --git a/.buildkite/scripts/should-run-comprehensive.sh b/.buildkite/scripts/should-run-comprehensive.sh
new file mode 100755
index 0000000..3d8e720
--- /dev/null
+++ b/.buildkite/scripts/should-run-comprehensive.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Decide whether comprehensive tests should run for this build.
+# Exit code semantics:
+#   0 -> run comprehensive tests
+#   1 -> skip comprehensive tests (safe paths only)
+
+# If this isn't a PR build, always run comprehensive tests.
+if [[ "${BUILDKITE_PULL_REQUEST:-false}" == "false" ]]; then
+  exit 0
+fi
+
+# Determine base ref to diff against.
+BASE_BRANCH="${BUILDKITE_PULL_REQUEST_BASE_BRANCH:-dev}"
+BASE_REF="origin/${BASE_BRANCH}"
+
+# Ensure the base ref exists; log a warning on fetch failure.
+if ! git fetch origin "${BASE_BRANCH}" >/dev/null 2>&1; then
+  echo "Warning: failed to fetch origin/${BASE_BRANCH}, falling back to local ref for diff." >&2
+fi
+
+# Compute changed files between the base and current HEAD.
+# If this fails, we will fall back to running the tests (CHANGED_FILES will be empty).
+CHANGED_FILES=$(git diff --name-only "${BASE_REF}...HEAD" 2>/dev/null || echo "")
+
+# If we cannot determine changes, be conservative and run tests.
+if [[ -z "${CHANGED_FILES}" ]]; then
+  exit 0
+fi
+
+# Track which safe-path categories were touched.
+safe_categories=()
+
+add_safe_category() {
+  local cat="$1"
+  for existing in "${safe_categories[@]}"; do
+    if [[ "$existing" == "$cat" ]]; then
+      return
+    fi
+  done
+  safe_categories+=("$cat")
+}
+
+# If any changed file is NOT in a safe path, we must run tests.
+while IFS= read -r f; do
+  case "$f" in
+    docs/*)
+      add_safe_category "docs/"
+      ;;
+    *.md|*.rst)
+      add_safe_category "*.md/*.rst"
+      ;;
+    tests/*)
+      add_safe_category "tests/"
+      ;;
+    tools/*)
+      add_safe_category "tools/"
+      ;;
+    lmcache/tools/*)
+      add_safe_category "lmcache/tools/"
+      ;;
+    examples/*)
+      add_safe_category "examples/"
+      ;;
+    asset/*)
+      add_safe_category "asset/"
+      ;;
+    *)
+      # Non-safe file touched -> run comprehensive tests.
+      exit 0
+      ;;
+  esac
+done <<< "${CHANGED_FILES}"
+
+# If we reach here, all changes are in safe paths, so safe_categories is not empty.
+# Join the array of categories for a clean log message.
+joined_cats=$(IFS=', '; echo "${safe_categories[*]}")
+echo "${joined_cats} change detected; skipping comprehensive tests."
+
+exit 1
diff --git a/.buildkite/scripts/vllm-correctness.sh b/.buildkite/scripts/vllm-correctness.sh
new file mode 100644
index 0000000..00d54c0
--- /dev/null
+++ b/.buildkite/scripts/vllm-correctness.sh
@@ -0,0 +1,273 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# This script requires some pre-configuration on the CI machine: 
+# 1. already has a virtual environment activated
+# 2. the model weights already exists on the CI machine
+# 3. the sharegpt dataset already exists on the CI machine
+
+# This script runs two tests: 
+# 1. a single request test for APC + LMCache hybrid KV Cache Retrieval
+# 2. a batch test for high concurrency / preemption to see if LMCache handles this case correctly
+#######################################
+# Required input
+#######################################
+: "${BUILD_ID:?BUILD_ID must be set}"
+
+#######################################
+# Configuration
+#######################################
+MODEL="Qwen/Qwen2.5-14B-Instruct"
+WORK_LOG="/tmp/build_${BUILD_ID}_correctness.log"
+VLLM_LOG="/tmp/build_${BUILD_ID}_vllm.log"
+ARTIFACT="build_${BUILD_ID}.log"
+SERVER_WAIT_TIMEOUT=180
+CORRECTNESS_DIR=".buildkite/correctness"
+REQUEST_NUMBER=100
+MAX_CONCURRENCY=40
+
+#######################################
+# Prerequisite for this script: 
+# Requires manual configuration on CI machines
+#######################################
+
+# 1. uv environment already exists
+
+# persist uv’s cache somewhere stable:
+export UV_CACHE_DIR="$HOME/.cache/uv"
+
+# we will try to reuse as much uv cache as possible across jobs
+# while pulling latest changes from vllm, LMCache, and other wheel dependencies
+source "$HOME/correctness/.venv/bin/activate"
+
+# update dependencies (nightly vllm and LMCache from the PR)
+# --refresh-package tells uv to revalidate cached data for that dependency.
+# --reinstall would reinstall all dependencies
+uv pip install -U vllm \
+  --extra-index-url https://wheels.vllm.ai/nightly \
+  --refresh-package vllm
+
+# override previous lmcache from previous jobs
+# the source installation is from this PR
+uv pip install -e . --reinstall-package lmcache --no-build-isolation
+
+# additional dependencies (please update manually if needed)
+# these packages are pretty stable so should not need to
+uv pip install aiohttp tqdm pandas huggingface_hub
+
+# 3. the sharegpt dataset already exists on the CI machine
+# wget -q \
+#   https://huggingface.co/datasets/anon8231489123/ShareGPT_Vicuna_unfiltered/resolve/main/ShareGPT_V3_unfiltered_cleaned_split.json \
+#   -O "$HOME/.ShareGPT_V3_unfiltered_cleaned_split.json"
+
+# ShareGPT dataset must already exist on the CI machine
+SHAREGPT_PATH="$HOME/correctness/.ShareGPT_V3_unfiltered_cleaned_split.json"
+
+echo "[INFO] Verifying ShareGPT dataset exists on the CI machine..."
+
+if [[ ! -f "$SHAREGPT_PATH" ]]; then
+    echo "[ERROR] ShareGPT dataset not found at: $SHAREGPT_PATH"
+    echo "[FIX] Pre-download it on the CI machine, e.g.:"
+    echo "      wget -q https://huggingface.co/datasets/anon8231489123/ShareGPT_Vicuna_unfiltered/resolve/main/ShareGPT_V3_unfiltered_cleaned_split.json -O '$SHAREGPT_PATH'"
+    exit 1
+fi
+
+if [[ ! -s "$SHAREGPT_PATH" ]]; then
+    echo "[ERROR] ShareGPT dataset file is empty: $SHAREGPT_PATH"
+    exit 1
+fi
+
+
+# 1. Setup local writable sandbox
+CI_CACHE_DIR="$PWD/.vllm_cache_${BUILD_ID}"
+mkdir -p "$CI_CACHE_DIR"
+
+# not sure if this is needed on H100 (it was on L40s)
+export FLASHINFER_WORKSPACE_DIR="$CI_CACHE_DIR/flashinfer"
+
+#######################################
+# Helpers
+#######################################
+collect_artifact() {
+    echo "[INFO] Collecting logs into ${ARTIFACT}"
+    cat "${WORK_LOG}" "${VLLM_LOG}" > "${ARTIFACT}" 2>/dev/null || true
+}
+
+stop_vllm() {
+    if [[ -n "${VLLM_PID:-}" ]]; then
+        echo "[INFO] Stopping vLLM process (PID: ${VLLM_PID})"
+        kill "${VLLM_PID}" >/dev/null 2>&1 || true
+        wait "${VLLM_PID}" 2>/dev/null || true
+        VLLM_PID=""
+        sleep 5
+    fi
+}
+
+find_free_port() {
+    for p in $(seq 8000 9000); do
+        if ! lsof -iTCP:"$p" -sTCP:LISTEN >/dev/null 2>&1; then
+            echo "$p"; return
+        fi
+    done
+    exit 1
+}
+
+trap 'rc=$?; stop_vllm; collect_artifact; exit $rc' EXIT INT TERM
+
+exec > >(tee -a "${WORK_LOG}") 2>&1
+
+echo "=== DIAGNOSTICS: GPU STATE before CI ==="
+nvidia-smi
+
+echo "[INFO] Selecting free GPU for this build..."
+source .buildkite/scripts/pick-free-gpu.sh 90000 1
+echo "[INFO] Using GPU(s): ${CUDA_VISIBLE_DEVICES}"
+
+echo "[INFO] Converting ShareGPT dataset to OpenAI format..."
+python "${CORRECTNESS_DIR}/sharegpt2openai.py" -i "$SHAREGPT_PATH" -o "./shareGPT_dataset.json"
+
+#######################################
+# Phase 1: Base Server (Baseline)
+#######################################
+PORT=$(find_free_port)
+echo "[INFO] Starting BASE vLLM server on port ${PORT}..."
+
+VLLM_SERVER_DEV_MODE=1 \
+VLLM_BATCH_INVARIANT=1 \
+vllm serve "${MODEL}" \
+    --port "${PORT}" \
+    --trust-remote-code \
+    --enforce-eager \
+    --attention-backend FLASH_ATTN \
+    --gpu-memory-utilization 0.8 \
+    >"${VLLM_LOG}" 2>&1 &
+VLLM_PID=$!
+
+echo "[INFO] Waiting for Base server readiness..."
+READY=false
+START_TIME=$(date +%s)
+while [ $(($(date +%s) - START_TIME)) -lt $SERVER_WAIT_TIMEOUT ]; do
+    if curl -s "http://localhost:${PORT}/v1/models" | grep -q "${MODEL//\//\\/}"; then
+        READY=true; break
+    fi
+    sleep 5
+done
+
+if [ "$READY" = false ]; then
+    echo "[ERROR] Base vLLM failed to start"; exit 1
+fi
+
+echo "[TEST] Running ShareGPT Batch (Base)..."
+python "${CORRECTNESS_DIR}/async_request.py" \
+    --model "${MODEL}" \
+    --endpoint "http://localhost:${PORT}/v1/chat/completions" \
+    --output-file "sharegpt_base.txt" \
+    --dataset_file "./shareGPT_dataset.json" \
+    --request-number "${REQUEST_NUMBER}" \
+    --max-concurrency "${MAX_CONCURRENCY}"
+
+stop_vllm
+
+#######################################
+# Phase 2: LMCache Server (Comparison)
+#######################################
+echo "[INFO] Preparing LMCache config (cpu.yaml)..."
+cat <<EOF > cpu.yaml
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 50
+EOF
+
+PORT=$(find_free_port)
+echo "[INFO] Starting LMCACHE vLLM server on port ${PORT}..."
+
+LMCACHE_CONFIG_FILE=cpu.yaml \
+VLLM_SERVER_DEV_MODE=1 \
+VLLM_BATCH_INVARIANT=1 \
+vllm serve "${MODEL}" \
+    --port "${PORT}" \
+    --trust-remote-code \
+    --enforce-eager \
+    --attention-backend FLASH_ATTN \
+    --gpu-memory-utilization 0.8 \
+    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}' \
+    >>"${VLLM_LOG}" 2>&1 &
+VLLM_PID=$!
+
+echo "[INFO] Waiting for LMCache server readiness..."
+READY=false
+START_TIME=$(date +%s)
+while [ $(($(date +%s) - START_TIME)) -lt $SERVER_WAIT_TIMEOUT ]; do
+    if curl -s "http://localhost:${PORT}/v1/models" | grep -q "${MODEL//\//\\/}"; then
+        READY=true; break
+    fi
+    sleep 5
+done
+
+if [ "$READY" = false ]; then
+    echo "[ERROR] LMCache vLLM failed to start"; exit 1
+fi
+
+echo "[TEST] Running ShareGPT Batch (LMCache)..."
+python "${CORRECTNESS_DIR}/async_request.py" \
+    --model "${MODEL}" \
+    --endpoint "http://localhost:${PORT}/v1/chat/completions" \
+    --output-file "sharegpt_lmcache.txt" \
+    --dataset_file "./shareGPT_dataset.json" \
+    --request-number "${REQUEST_NUMBER}" \
+    --max-concurrency "${MAX_CONCURRENCY}"
+
+#######################################
+# Phase 3: Final man bash Correctness (On LMCache Server)
+#######################################
+echo "[TEST] Running technical man bash correctness test..."
+CONTEXT="$(man bash | col -b | tr -s '[:space:]' ' ' | awk '{for(i=1;i<=NF;i++){printf "%s ",$i; if(++c==5000) exit}}')"
+HALF_CONTEXT="$(man bash | col -b | tr -s '[:space:]' ' ' | awk '{for(i=1;i<=NF;i++){printf "%s ",$i; if(++c==2500) exit}}')"
+
+send_completion() {
+    curl -s "http://localhost:${PORT}/v1/chat/completions" \
+        -H "Content-Type: application/json" \
+        -d "$(jq -n --arg model "${MODEL}" --arg content "$1" '{model: $model, temperature: 0, max_tokens: 100, messages: [{role:"user",content:$content}]}')" |
+        jq -r '.choices[0].message.content'
+}
+
+echo "[STEP 1] Full context (LMCache)"
+OUT1="$(send_completion "${CONTEXT}")"
+
+echo "[STEP 2] Reset prefix cache"
+curl -s -X POST "http://localhost:${PORT}/reset_prefix_cache" >/dev/null
+
+echo "[STEP 3] Half context"
+send_completion "${HALF_CONTEXT}" >/dev/null
+
+echo "[STEP 4] Full context again"
+OUT2="$(send_completion "${CONTEXT}")"
+
+if [[ "${OUT1}" != "${OUT2}" ]]; then
+    echo "[FAIL] man bash output mismatch!"
+    exit 1
+fi
+
+#######################################
+# Phase 4: ShareGPT File Comparison
+#######################################
+echo "[INFO] Comparing ShareGPT results..."
+COMPARE_OUT=$(python "${CORRECTNESS_DIR}/compare_files.py" --file1 "sharegpt_base.txt" --file2 "sharegpt_lmcache.txt")
+
+echo "--- COMPARISON RESULTS ---"
+echo "${COMPARE_OUT}"
+echo "--------------------------"
+
+# Extract counts from the statistics output
+DIFFERENT_COUNT=$(echo "${COMPARE_OUT}" | grep "^Different IDs:" | grep -oE '[0-9]+' || echo "0")
+ONLY_FILE1_COUNT=$(echo "${COMPARE_OUT}" | awk '/^—— Only in File 1 ——$/,/^—— Only in File 2 ——$/ {print}' | grep -E "^chatcmpl-" | wc -l || echo "0")
+ONLY_FILE2_COUNT=$(echo "${COMPARE_OUT}" | awk '/^—— Only in File 2 ——$/,/^$/ {print}' | grep -E "^chatcmpl-" | wc -l || echo "0")
+
+echo "[INFO] Analysis: Different=${DIFFERENT_COUNT}, Only in Base=${ONLY_FILE1_COUNT}, Only in LMCache=${ONLY_FILE2_COUNT}"
+
+if [[ "${DIFFERENT_COUNT}" -gt 0 ]] || [[ "${ONLY_FILE1_COUNT}" -gt 0 ]] || [[ "${ONLY_FILE2_COUNT}" -gt 0 ]]; then
+    echo "[FAIL] Inconsistency detected between Base and LMCache outputs."
+    exit 1
+fi
+
+echo "[PASS] All correctness tests passed identical output verified."
\ No newline at end of file
diff --git a/.buildkite/scripts/vllm-integration-tests.sh b/.buildkite/scripts/vllm-integration-tests.sh
new file mode 100755
index 0000000..940b267
--- /dev/null
+++ b/.buildkite/scripts/vllm-integration-tests.sh
@@ -0,0 +1,876 @@
+#!/usr/bin/bash
+#
+# This test script runs integration tests for the LMCache integration with vLLM.
+# A lmcache/vllm-openai container image is built by this script from the LMCache code base
+# the script is running from and the latest nightly build of vLLM. It is therefore using the
+# latest of both code bases to build the image which it then performs tests on.
+#
+# It’s laid out as follows:
+# - UTILITIES:  utility functions
+# - TESTS:      test functions
+# - SETUP:      environment setup steps
+# - MAIN:       test execution steps
+#
+# It requires the following to be installed to run:
+# - curl
+# - docker engine (daemon running)
+# - NVIDIA Container Toolkit:
+#   https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
+#
+# Note: The script should be run from the LMCache code base root.
+# Note: L4 CI runners cannot use Flash Infer
+
+set -e
+trap 'cleanup $?' EXIT INT TERM
+
+CID=
+PREFILLER_CID=
+DECODER_CID=
+CID1=
+CID2=
+HF_TOKEN=
+SERVER_WAIT_TIMEOUT=180
+PORT=
+PORT1=
+PORT2=
+
+#############
+# UTILITIES #
+#############
+
+cleanup() {
+    local code="${1:-0}"
+
+    echo "→ Cleaning up Docker containers and ports..." >&2
+
+    # Clean up container IDs if defined
+    for cid_var in CID PREFILLER_CID DECODER_CID CID1 CID2; do
+        local cid="${!cid_var:-}"
+        if [[ -n "$cid" ]]; then
+            echo "  - Killing and removing container: $cid" >&2
+            docker kill "$cid" >&2 || true
+            docker rm "$cid" >&2 || true
+            printf -v "$cid_var" ''
+        fi
+    done
+
+    # Clean up ports if defined
+    for port_var in PORT PORT1 PORT2; do
+        local port="${!port_var:-}"
+        if [[ -n "$port" ]]; then
+            echo "  - Killing and removing port: $port" >&2
+            fuser -k "${port}/tcp" >&2 || true
+            if [[ "$port_var" != "PORT" ]]; then
+                printf -v "$port_var" ''
+            fi
+        fi
+    done
+    
+    # Wait for GPU memory to be fully released
+    echo "  - Waiting 5 seconds for GPU memory to be released..." >&2
+    sleep 5
+}
+
+find_available_port() {
+    local start_port=${1:-8000}
+    local port=$start_port
+
+    while [ $port -lt 65536 ]; do
+        # Check if port is available using netstat
+        if ! netstat -tuln 2>/dev/null | grep -q ":${port} "; then
+            # Double-check by trying to bind to the port with nc
+            if timeout 1 bash -c "</dev/tcp/127.0.0.1/${port}" 2>/dev/null; then
+                # Port is in use, try next one
+                ((port++))
+                continue
+            else
+                # Port is available
+                echo $port
+                return 0
+            fi
+        fi
+        ((port++))
+    done
+
+    echo "ERROR: No available ports found starting from $start_port" >&2
+    return 1
+}
+
+build_lmcache_vllmopenai_image() {
+    cp example_build.sh test-build.sh
+    chmod 755 test-build.sh
+    ./test-build.sh
+}
+
+wait_for_openai_api_server() {
+    local port="$1"
+    local model="$2"
+    local cid="$3"
+
+    if ! timeout "$SERVER_WAIT_TIMEOUT" bash -c "
+        echo \"Curl /v1/models endpoint\"
+        until curl -s 127.0.0.1:${port}/v1/models \
+                | grep -Fq \"\\\"id\\\":\\\"${model}\\\"\"; do
+            sleep 30
+        done
+        echo \"Model ${model} is available on ${port}\"
+    "; then
+        echo "OpenAI API server did not start"
+        docker logs $cid
+        return 1
+    fi
+}
+
+run_lmcache_vllmopenai_container() {
+    local docker="$1"
+    local vllm="$2"
+    local cfg_name="$3"
+    LOGFILE="/tmp/build_${BUILD_ID}_${cfg_name}.log"
+
+    # Ensure host directory exists for socket mapping
+    mkdir -p "/tmp/lmcache_internal_api_server/${PORT}"
+
+    # Pick the GPUs based on config
+    gpu_count=$(yq -r '.docker.gpu_count // 1' "$cfg_file")
+    source "$ORIG_DIR/.buildkite/scripts/pick-free-gpu.sh" 40000 "$gpu_count"
+    if [ -z "$CUDA_VISIBLE_DEVICES" ]; then
+        echo "❌ Failed to select $gpu_count GPU(s)"
+        exit 1
+    fi
+    best_gpu="${CUDA_VISIBLE_DEVICES}"
+
+    # docker args
+    docker_args=(
+        --runtime nvidia
+        --network host
+        --volume ~/.cache/huggingface:/root/.cache/huggingface
+        --volume "${CONFIG_DIR}/lmcache_configs:/etc/lmcache:ro"
+        --volume /tmp/lmcache_internal_api_server/${PORT}:/tmp/lmcache_internal_api_server
+        --env VLLM_USE_FLASHINFER_SAMPLER=0
+        --env HF_TOKEN="$HF_TOKEN"
+    )
+    
+    # Handle GPU assignment based on count
+    if [ "$gpu_count" -gt 1 ]; then
+        # Multi-GPU: expose all and use CUDA_VISIBLE_DEVICES to restrict
+        docker_args+=(--gpus all)
+        docker_args+=(--env "CUDA_VISIBLE_DEVICES=${best_gpu}")
+    else
+        # Single GPU: use device isolation
+        docker_args+=(--gpus "device=${best_gpu}")
+    fi
+    while IFS= read -r e; do
+        [[ -n $e ]] && docker_args+=(--env "$e")
+    done < <(yq -r '.env[]?' <<<"$docker")
+
+    # vllm args
+    vllm_model="$(yq -r '.model' <<<"$vllm")"
+    mapfile -t vllm_cli_args < <(yq -r '.args // [] | .[]' <<<"$vllm")
+    cmd_args=(
+        lmcache/vllm-openai:build-latest
+        "$vllm_model"
+    )
+    cmd_args+=("${vllm_cli_args[@]}")
+    cmd_args+=("--port" "$PORT")
+
+    # Start docker
+    CID=$(
+        docker run -d \
+            "${docker_args[@]}" \
+            "${cmd_args[@]}"
+    )
+
+    wait_for_openai_api_server "$PORT" "$vllm_model" "$CID"
+
+    # Logging
+    touch "$LOGFILE"
+    docker logs -f "$CID" >>"$LOGFILE" 2>&1 &
+    LOG_PID=$!
+}
+
+run_pd_lmcache() {
+    local prefiller_docker="$1"
+    local prefiller_vllm="$2"
+    local decoder_docker="$3"
+    local decoder_vllm="$4"
+    local cfg_name="$5"
+    PREFILLER_LOGFILE="/tmp/build_${BUILD_ID}_${cfg_name}_prefiller.log"
+    DECODER_LOGFILE="/tmp/build_${BUILD_ID}_${cfg_name}_decoder.log"
+
+    # Pick 2 free GPUs for prefiller and decoder
+    source "$ORIG_DIR/.buildkite/scripts/pick-free-gpu.sh" 40000 2
+    if [ -z "$CUDA_VISIBLE_DEVICES" ]; then
+        echo "❌ Failed to select 2 free GPUs"
+        exit 1
+    fi
+    IFS=',' read -ra SELECTED_GPUS <<< "$CUDA_VISIBLE_DEVICES"
+    if [ ${#SELECTED_GPUS[@]} -ne 2 ]; then
+        echo "❌ Expected 2 GPUs, but got ${#SELECTED_GPUS[@]}: ${CUDA_VISIBLE_DEVICES}"
+        exit 1
+    fi
+    GPU_PREFILLER="${SELECTED_GPUS[0]}"
+    GPU_DECODER="${SELECTED_GPUS[1]}"
+    echo "Selected GPU ${GPU_PREFILLER} for prefiller, GPU ${GPU_DECODER} for decoder"
+
+    # Ensure host directory exists for socket mapping
+    mkdir -p "/tmp/lmcache_internal_api_server/${PORT1}"
+    mkdir -p "/tmp/lmcache_internal_api_server/${PORT2}"
+
+    ########## Prefiller ##########
+    # docker args
+    prefiller_docker_args=(
+        --runtime nvidia
+        --network host
+        --gpus "device=${GPU_PREFILLER}"
+        --volume ~/.cache/huggingface:/root/.cache/huggingface
+        --volume /tmp/lmcache_internal_api_server/${PORT1}:/tmp/lmcache_internal_api_server
+        --env VLLM_USE_FLASHINFER_SAMPLER=0
+        --env HF_TOKEN="$HF_TOKEN"
+        --env UCX_TLS=cuda_ipc,cuda_copy,tcp
+        --ipc host
+        --shm-size 4G
+    )
+    while IFS= read -r e; do
+        [[ -n $e ]] && prefiller_docker_args+=(--env "$e")
+    done < <(yq -r '.env[]?' <<<"$prefiller_docker")
+    proxy=$(yq -er '."proxy-port"' <<<"$prefiller_docker" 2>/dev/null)
+    prefiller_docker_args+=(--env "LMCACHE_PD_PROXY_PORT=$proxy")
+
+    # vllm args
+    prefiller_vllm_model="$(yq -r '.model' <<<"$prefiller_vllm")"
+    mapfile -t prefiller_vllm_cli_args < <(yq -r '.args // [] | .[]' <<<"$prefiller_vllm")
+    prefiller_cmd_args=(
+        lmcache/vllm-openai:build-latest
+        "$prefiller_vllm_model"
+    )
+    prefiller_cmd_args+=("${prefiller_vllm_cli_args[@]}")
+    prefiller_cmd_args+=("--port" "$PORT1")
+
+    # Start docker
+    PREFILLER_CID=$(
+        docker run -d \
+            "${prefiller_docker_args[@]}" \
+            "${prefiller_cmd_args[@]}"
+    )
+
+    # Health check
+    wait_for_openai_api_server "$PORT1" "$prefiller_vllm_model" "$PREFILLER_CID"
+
+    # Logging
+    touch "$PREFILLER_LOGFILE"
+    docker logs -f "$PREFILLER_CID" >>"$PREFILLER_LOGFILE" 2>&1 &
+
+    ########## Decoder ##########
+    # docker args
+    decoder_docker_args=(
+        --runtime nvidia
+        --network host
+        --gpus "device=${GPU_DECODER}"
+        --volume ~/.cache/huggingface:/root/.cache/huggingface
+        --volume /tmp/lmcache_internal_api_server/${PORT2}:/tmp/lmcache_internal_api_server
+        --env VLLM_USE_FLASHINFER_SAMPLER=0
+        --env HF_TOKEN="$HF_TOKEN"
+        --env UCX_TLS=cuda_ipc,cuda_copy,tcp
+        --ipc host
+        --shm-size 4G
+    )
+    while IFS= read -r e; do
+        [[ -n $e ]] && decoder_docker_args+=(--env "$e")
+    done < <(yq -r '.env[]?' <<<"$decoder_docker")
+    init=$(yq -er '."init-port"' <<<"$decoder_docker" 2>/dev/null)
+    decoder_docker_args+=(--env "LMCACHE_PD_PEER_INIT_PORT=$init")
+    alloc=$(yq -er '."alloc-port"' <<<"$decoder_docker" 2>/dev/null)
+    decoder_docker_args+=(--env "LMCACHE_PD_PEER_ALLOC_PORT=$alloc")
+
+    # vllm args
+    decoder_vllm_model="$(yq -r '.model' <<<"$decoder_vllm")"
+    mapfile -t decoder_vllm_cli_args < <(yq -r '.args // [] | .[]' <<<"$decoder_vllm")
+    decoder_cmd_args=(
+        lmcache/vllm-openai:build-latest
+        "$decoder_vllm_model"
+    )
+    decoder_cmd_args+=("${decoder_vllm_cli_args[@]}")
+    decoder_cmd_args+=("--port" "$PORT2")
+
+    # Start docker
+    DECODER_CID=$(
+        docker run -d \
+            "${decoder_docker_args[@]}" \
+            "${decoder_cmd_args[@]}"
+    )
+
+    # Health check
+    wait_for_openai_api_server "$PORT2" "$decoder_vllm_model" "$DECODER_CID"
+
+    # Logging
+    touch "$DECODER_LOGFILE"
+    docker logs -f "$DECODER_CID" >>"$DECODER_LOGFILE" 2>&1 &
+
+    ########## Proxy ##########
+    if [ ! -d ".venv" ]; then
+        UV_PYTHON=python3 uv -q venv
+    fi
+    source .venv/bin/activate
+    uv pip install -r "$ORIG_DIR/requirements/build.txt" > /dev/null 2>&1
+    uv pip install torch==2.7.1 httpx fastapi uvicorn requests > /dev/null 2>&1
+    uv pip install -e "$ORIG_DIR" --no-build-isolation > /dev/null 2>&1
+    # Start proxy
+    python3 "$ORIG_DIR/examples/disagg_prefill/disagg_proxy_server.py" \
+        --port "$PORT" \
+        --prefiller-port "$PORT1" \
+        --decoder-port "$PORT2" \
+        --decoder-init-port "$init" \
+        --decoder-alloc-port "$alloc" \
+        --proxy-port "$proxy" \
+        > "/tmp/build_${BUILD_ID}_${cfg_name}_proxy.log" 2>&1 &
+    sleep 10
+}
+
+run_p2p_lmcache() {
+    local docker1="$1"
+    local vllm1="$2"
+    local docker2="$3"
+    local vllm2="$4"
+    local cfg_name="$5"
+    LOGFILE1="/tmp/build_${BUILD_ID}_${cfg_name}1.log"
+    LOGFILE2="/tmp/build_${BUILD_ID}_${cfg_name}2.log"
+
+    # Pick 2 free GPUs for instance 1 and instance 2
+    source "$ORIG_DIR/.buildkite/scripts/pick-free-gpu.sh" 40000 2
+    if [ -z "$CUDA_VISIBLE_DEVICES" ]; then
+        echo "❌ Failed to select 2 free GPUs"
+        exit 1
+    fi
+    IFS=',' read -ra SELECTED_GPUS <<< "$CUDA_VISIBLE_DEVICES"
+    if [ ${#SELECTED_GPUS[@]} -ne 2 ]; then
+        echo "❌ Expected 2 GPUs, but got ${#SELECTED_GPUS[@]}: ${CUDA_VISIBLE_DEVICES}"
+        exit 1
+    fi
+    GPU_INSTANCE1="${SELECTED_GPUS[0]}"
+    GPU_INSTANCE2="${SELECTED_GPUS[1]}"
+    echo "Selected GPU ${GPU_INSTANCE1} for instance 1, GPU ${GPU_INSTANCE2} for instance 2"
+
+    # Ensure host directory exists for socket mapping
+    mkdir -p "/tmp/lmcache_internal_api_server/${PORT1}"
+    mkdir -p "/tmp/lmcache_internal_api_server/${PORT2}"
+
+    ########## Instance 1 ##########
+    # docker args
+    docker1_args=(
+        --runtime nvidia
+        --network host
+        --gpus "device=${GPU_INSTANCE1}"
+        --volume ~/.cache/huggingface:/root/.cache/huggingface
+        --volume /tmp/lmcache_internal_api_server/${PORT1}:/tmp/lmcache_internal_api_server
+        --env VLLM_USE_FLASHINFER_SAMPLER=0
+        --env HF_TOKEN="$HF_TOKEN"
+        --env UCX_TLS=tcp
+        --ipc host
+        --shm-size 4G
+    )
+    while IFS= read -r e; do
+        [[ -n $e ]] && docker1_args+=(--env "$e")
+    done < <(yq -r '.env[]?' <<<"$docker1")
+    pull=$(yq -er '."pull-port"' <<<"$docker1" 2>/dev/null)
+    docker1_args+=(--env "LMCACHE_CONTROLLER_PULL_URL=localhost:$pull")
+    reply=$(yq -er '."reply-port"' <<<"$docker1" 2>/dev/null)
+    docker1_args+=(--env "LMCACHE_CONTROLLER_REPLY_URL=localhost:$reply")
+
+    # vllm args
+    vllm1_model="$(yq -r '.model' <<<"$vllm1")"
+    mapfile -t vllm1_cli_args < <(yq -r '.args // [] | .[]' <<<"$vllm1")
+    cmd_args1=(
+        lmcache/vllm-openai:build-latest
+        "$vllm1_model"
+    )
+    cmd_args1+=("${vllm1_cli_args[@]}")
+    cmd_args1+=("--port" "$PORT1")
+
+    ##### Controller part start #####
+    if [ ! -d ".venv" ]; then
+        UV_PYTHON=python3 uv -q venv
+    fi
+    source .venv/bin/activate
+    uv pip install -r "$ORIG_DIR/requirements/build.txt" > /dev/null 2>&1
+    uv pip install torch==2.7.1 httpx fastapi uvicorn > /dev/null 2>&1
+    uv pip install -e "$ORIG_DIR" --no-build-isolation > /dev/null 2>&1
+    # Start controller
+    PYTHONHASHSEED=123 lmcache_controller \
+        --host localhost \
+        --port "$PORT" \
+        --monitor-ports "{\"pull\": ${pull}, \"reply\": ${reply}}" \
+        > "/tmp/build_${BUILD_ID}_${cfg_name}_controller.log" 2>&1 &
+    sleep 10
+    ##### Controller part end #####
+
+    # Start docker
+    CID1=$(
+        docker run -d \
+            "${docker1_args[@]}" \
+            "${cmd_args1[@]}"
+    )
+
+    # Health check
+    wait_for_openai_api_server "$PORT1" "$vllm1_model" "$CID1"
+
+    # Logging
+    touch "$LOGFILE1"
+    docker logs -f "$CID1" >>"$LOGFILE1" 2>&1 &
+
+    ########## Instance 2 ##########
+    # docker args
+    docker2_args=(
+        --runtime nvidia
+        --network host
+        --gpus "device=${GPU_INSTANCE2}"
+        --volume ~/.cache/huggingface:/root/.cache/huggingface
+        --volume /tmp/lmcache_internal_api_server/${PORT2}:/tmp/lmcache_internal_api_server
+        --env VLLM_USE_FLASHINFER_SAMPLER=0
+        --env HF_TOKEN="$HF_TOKEN"
+        --env UCX_TLS=tcp
+        --ipc host
+        --shm-size 4G
+    )
+    while IFS= read -r e; do
+        [[ -n $e ]] && docker2_args+=(--env "$e")
+    done < <(yq -r '.env[]?' <<<"$docker2")
+    pull=$(yq -er '."pull-port"' <<<"$docker2" 2>/dev/null)
+    docker2_args+=(--env "LMCACHE_CONTROLLER_PULL_URL=localhost:$pull")
+    reply=$(yq -er '."reply-port"' <<<"$docker2" 2>/dev/null)
+    docker2_args+=(--env "LMCACHE_CONTROLLER_REPLY_URL=localhost:$reply")
+
+    # vllm args
+    vllm2_model="$(yq -r '.model' <<<"$vllm2")"
+    mapfile -t vllm2_cli_args < <(yq -r '.args // [] | .[]' <<<"$vllm2")
+    cmd_args2=(
+        lmcache/vllm-openai:build-latest
+        "$vllm2_model"
+    )
+    cmd_args2+=("${vllm2_cli_args[@]}")
+    cmd_args2+=("--port" "$PORT2")
+
+    # Start docker
+    CID2=$(
+        docker run -d \
+            "${docker2_args[@]}" \
+            "${cmd_args2[@]}"
+    )
+
+    # Health check
+    wait_for_openai_api_server "$PORT2" "$vllm2_model" "$CID2"
+
+    # Logging
+    touch "$LOGFILE2"
+    docker logs -f "$CID2" >>"$LOGFILE2" 2>&1 &
+}
+
+usage() {
+    echo "Usage: $0 [OPTIONS]"
+    echo " "
+    echo "Options:"
+    echo "  --hf-token|-hft              HuggingFace access token for downloading model(s)"
+    echo "  --server-wait-timeout|-swt   Wait time in seconds for vLLM OpenAI server to start"
+    echo "  --help|-h                    Print usage"
+    echo "  --configs|-c                 Path to a file containing one config filename per line (required)"
+    echo "  --tests|-t                   Test mode"
+}
+
+#########
+# TESTS #
+#########
+
+check_memory_leak() {
+    local port="$1"
+
+    # Socket path on host: /tmp/lmcache_internal_api_server/{port}/socket_7000
+    local socket_path="/tmp/lmcache_internal_api_server/${port}/socket_7000"
+
+    # Get use_hot from /conf endpoint
+    local use_hot
+    use_hot=$(curl -s --unix-socket "$socket_path" "http://localhost/conf" 2>/dev/null | jq -r '.local_cpu // false')
+    if [ -z "$use_hot" ] || [ "$use_hot" = "null" ]; then
+        use_hot="false"
+    fi
+
+    echo "→ Checking memory leak on socket_path $socket_path (use_hot=$use_hot)..."
+
+    # Fetch metrics from the prometheus endpoint via unix socket
+    local metrics
+    metrics=$(curl -s --unix-socket "$socket_path" "http://localhost/metrics" 2>/dev/null)
+    if [ -z "$metrics" ]; then
+        echo "ERROR: Failed to fetch metrics from socket_path $socket_path"
+        return 1
+    fi
+
+    # Extract metric values
+    local local_cpu_hot_cache_count
+    local active_memory_objs_count
+    local pinned_memory_objs_count
+    local pin_monitor_pinned_objects_count
+
+    local_cpu_hot_cache_count=$(echo "$metrics" | grep -E '^lmcache:local_cpu_hot_cache_count\b' | awk '{print $2}' | head -n 1)
+    active_memory_objs_count=$(echo "$metrics" | grep -E '^lmcache:active_memory_objs_count\b' | awk '{print $2}' | head -n 1)
+    pinned_memory_objs_count=$(echo "$metrics" | grep -E '^lmcache:pinned_memory_objs_count\b' | awk '{print $2}' | head -n 1)
+    pin_monitor_pinned_objects_count=$(echo "$metrics" | grep -E '^lmcache:pin_monitor_pinned_objects_count\b' | awk '{print $2}' | head -n 1)
+
+    # Default to 0 if not found
+    local_cpu_hot_cache_count=${local_cpu_hot_cache_count:-0}
+    active_memory_objs_count=${active_memory_objs_count:-0}
+    pinned_memory_objs_count=${pinned_memory_objs_count:-0}
+    pin_monitor_pinned_objects_count=${pin_monitor_pinned_objects_count:-0}
+
+    # Convert to integer (remove decimal part if any)
+    local_cpu_hot_cache_count=$(printf "%.0f" "$local_cpu_hot_cache_count")
+    active_memory_objs_count=$(printf "%.0f" "$active_memory_objs_count")
+    pinned_memory_objs_count=$(printf "%.0f" "$pinned_memory_objs_count")
+    pin_monitor_pinned_objects_count=$(printf "%.0f" "$pin_monitor_pinned_objects_count")
+
+    echo "  local_cpu_hot_cache_count: $local_cpu_hot_cache_count"
+    echo "  active_memory_objs_count: $active_memory_objs_count"
+    echo "  pinned_memory_objs_count: $pinned_memory_objs_count"
+    echo "  pin_monitor_pinned_objects_count: $pin_monitor_pinned_objects_count"
+
+    local has_leak=false
+
+    # Check pinned_memory_objs_count must be 0
+    if [ "$pinned_memory_objs_count" -ne 0 ]; then
+        echo "ERROR: Memory leak detected - pinned_memory_objs_count ($pinned_memory_objs_count) should be 0"
+        has_leak=true
+    fi
+
+    # Check based on use_hot setting
+    if [ "$use_hot" = "false" ] || [ "$use_hot" = "False" ]; then
+        # use_hot is False: both local_cpu_hot_cache_count and active_memory_objs_count should be 0
+        if [ "$local_cpu_hot_cache_count" -ne 0 ]; then
+            echo "ERROR: Memory leak detected - local_cpu_hot_cache_count ($local_cpu_hot_cache_count) should be 0 when use_hot=false"
+            has_leak=true
+        fi
+        if [ "$active_memory_objs_count" -ne 0 ]; then
+            echo "ERROR: Memory leak detected - active_memory_objs_count ($active_memory_objs_count) should be 0 when use_hot=false"
+            has_leak=true
+        fi
+    else
+        # use_hot is True: active_memory_objs_count should equal local_cpu_hot_cache_count
+        if [ "$active_memory_objs_count" -ne "$local_cpu_hot_cache_count" ]; then
+            echo "ERROR: Memory leak detected - active_memory_objs_count ($active_memory_objs_count) should equal local_cpu_hot_cache_count ($local_cpu_hot_cache_count) when use_hot=true"
+            has_leak=true
+        fi
+    fi
+
+    if [ "$has_leak" = true ]; then
+        echo "$metrics"
+        return 1
+    fi
+
+    echo "  Memory leak check passed!"
+    return 0
+}
+
+test_vllmopenai_server_with_lmcache_integrated() {
+    local model="$1"
+
+    http_status_code=$(
+        curl --max-time 60 http://localhost:${PORT}/v1/completions \
+            -w "%{http_code}" -o response-file.txt \
+            -H "Content-Type: application/json" \
+            -d '{
+                "model": "'"$model"'",
+                "prompt": "<|begin_of_text|><|system|>\nYou are a helpful AI assistant.\n<|user|>\nWhat is the capital of France?\n<|assistant|>",
+                "max_tokens": 100,
+                "temperature": 0.7
+            }'
+    )
+
+    if [ "$http_status_code" -ne 200 ]; then
+        echo "Model prompt request from OpenAI API server failed, HTTP status code: ${http_status_code}."
+        cat response-file.txt
+        docker logs -n 20 $CID
+        return 1
+    else
+        echo "Model prompt request from OpenAI API server succeeded"
+        cat response-file.txt
+    fi
+}
+
+run_long_doc_qa() {
+    local workload_config="$1"
+    local port="$2"
+    local check_warmup_round_time_per_prompt="${3:-"false"}"
+    local check_query_ttft_per_prompt="${4:-"false"}"
+    local check_query_round_time_per_prompt="${5:-"false"}"
+    local feature_type="${6:-"dummy"}"
+    local need_upload="${7:-"false"}"
+
+    echo "→ Running long_doc_qa with customed workload config:"
+    printf '%s\n' "$workload_config"
+
+    local workload_args=()
+    mapfile -d '' -t workload_args < <(
+    jq -j '
+        to_entries[]
+        | select(.value != null and (.value|tostring) != "")
+        | (
+            if (.value|type) == "boolean" then
+            if .value then ["--\(.key)", "\u0000"] else [] end
+            elif (.value|type) == "array" then
+            .value[]
+            | ["--\(.key)", "\u0000",
+                (if (type=="string") then . else tostring end),
+                "\u0000"]
+            else
+            ["--\(.key)", "\u0000",
+            (if ((.value|type)=="string") then .value else (.value|tostring) end),
+            "\u0000"]
+            end
+        )
+        | .[]
+    ' <<<"$workload_config"
+    )
+
+    if [ ! -d ".venv" ]; then
+        UV_PYTHON=python3 uv -q venv
+    fi
+    source .venv/bin/activate
+    uv -q pip install openai pandas matplotlib
+    json=$(
+        python3 "$ORIG_DIR/benchmarks/long_doc_qa/long_doc_qa.py" \
+            "${workload_args[@]}" \
+            --port="$port" \
+            --output="response.txt" \
+            --json-output \
+            2>>response.txt | tail -n 1
+    )
+    query_ttft_per_prompt=$(echo "$json" | jq -r '.query_ttft_per_prompt')
+    query_round_time_per_prompt=$(echo "$json" | jq -r '.query_round_time_per_prompt')
+    warmup_round_time_per_prompt=$(echo "$json" | jq -r '.warmup_round_time_per_prompt')
+
+    if [ "$need_upload" = "true" ]; then
+        local baseline_path="$ORIG_DIR/benchmarks/long_doc_qa/$feature_type.json"
+        echo "$json"
+        printf '%s\n' "$json" > "$baseline_path"
+
+        git config user.email "$USER_EMAIL"
+        git config user.name "$USER_NAME"
+        git add "$baseline_path"
+        git commit -m "Update long_doc_qa baseline: $feature_type.json" || true
+        if ! git remote get-url internal >/dev/null 2>&1; then
+            git remote add internal git@github.com:LMCache/LMCache.git
+        fi
+        git push internal +HEAD:benchmarks-main >/dev/null 2>&1
+        return 0
+    fi
+
+    # Fetch branch
+    git fetch origin benchmarks-main >/dev/null 2>&1 || true
+
+    # Load baseline from branch
+    baseline_json=$(git show origin/benchmarks-main:benchmarks/long_doc_qa/$feature_type.json 2>/dev/null || echo "")
+
+    # Check if baseline exists, skip comparisons if not
+    if [[ -z "$baseline_json" ]] || ! echo "$baseline_json" | jq -e . >/dev/null 2>&1; then
+        if [[ "$feature_type" != "dummy" ]]; then
+            echo "⚠️  No baseline found for $feature_type.json - skipping performance comparisons"
+            echo "   This is expected for newly added configs. Baseline will be generated on next nightly run."
+            echo "   Current metrics: TTFT=$query_ttft_per_prompt, Latency=$query_round_time_per_prompt, Warmup=$warmup_round_time_per_prompt"
+        fi
+        return 0
+    fi
+
+    # Extract baseline numbers
+    expected_query_ttft_per_prompt=$(echo "$baseline_json" | jq -r '.query_ttft_per_prompt')
+    expected_query_round_time_per_prompt=$(echo "$baseline_json" | jq -r '.query_round_time_per_prompt')
+    expected_warmup_round_time_per_prompt=$(echo "$baseline_json" | jq -r '.warmup_round_time_per_prompt')
+
+    if [ "$check_query_ttft_per_prompt" = "true" ]; then
+        echo "Expected query ttft per prompt: $expected_query_ttft_per_prompt"
+        echo "Actual query ttft per prompt: $query_ttft_per_prompt"
+        awk -v expected="$expected_query_ttft_per_prompt" -v actual="$query_ttft_per_prompt" 'BEGIN {
+            if (actual > expected * 1.2) {
+                print "Query ttft per prompt requirement not met (>20% overhead)"
+                exit 1
+            } else {
+                print "Query ttft per prompt requirement met"
+            }
+        }'
+    fi
+
+    if [ "$check_query_round_time_per_prompt" = "true" ]; then
+        echo "Expected query round time per prompt: $expected_query_round_time_per_prompt"
+        echo "Actual query round time per prompt: $query_round_time_per_prompt"
+        awk -v expected="$expected_query_round_time_per_prompt" -v actual="$query_round_time_per_prompt" 'BEGIN {
+            if (actual > expected * 1.2) {
+                print "Query round time per prompt requirement not met (>20% overhead)"
+                exit 1
+            } else {
+                print "Query round time per prompt requirement met"
+            }
+        }'
+    fi
+
+    if [ "$check_warmup_round_time_per_prompt" = "true" ]; then
+        echo "Expected warmup round time per prompt: $expected_warmup_round_time_per_prompt"
+        echo "Actual warmup round time per prompt: $warmup_round_time_per_prompt"
+        awk -v expected="$expected_warmup_round_time_per_prompt" -v actual="$warmup_round_time_per_prompt" 'BEGIN {
+            if (actual > expected * 1.2) {
+                print "Warmup round time per prompt requirement not met (>20% overhead)"
+                exit 1
+            } else {
+                print "Warmup round time per prompt requirement met"
+            }
+        }'
+    fi
+}
+
+#########
+# SETUP #
+#########
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+    --configs* | -c*)
+        if [[ "$1" != *=* ]]; then shift; fi
+        configs_arg="${1#*=}"
+        ;;
+    --hf-token* | -hft*)
+        if [[ "$1" != *=* ]]; then shift; fi
+        HF_TOKEN="${1#*=}"
+        ;;
+    --server-wait-timeout* | -swt*)
+        if [[ "$1" != *=* ]]; then shift; fi
+        SERVER_WAIT_TIMEOUT="${1#*=}"
+        if ! [[ "$SERVER_WAIT_TIMEOUT" =~ ^[0-9]+$ ]]; then
+            echo "server-wait-timeout is wait time in seconds - integer only"
+            exit 1
+        fi
+        ;;
+    --help | -h)
+        usage
+        exit 0
+        ;;
+    *)
+        printf >&2 "Error: Invalid argument\n"
+        usage
+        exit 1
+        ;;
+    esac
+    shift
+done
+
+ORIG_DIR="$PWD"
+CONFIG_DIR="${ORIG_DIR}/.buildkite/configs"
+
+# Read the configs argument (always a file with one config per line)
+if [[ ! -f "$configs_arg" ]]; then
+    echo "Error: --configs file not found: $configs_arg" >&2
+    exit 1
+fi
+mapfile -t CONFIG_NAMES < <(
+    sed 's/[[:space:]]\+$//' "$configs_arg"
+)
+
+# Find an available port starting from 8000
+PORT=$(find_available_port 8000)
+if [ $? -ne 0 ]; then
+    echo "Failed to find an available port"
+    exit 1
+fi
+echo "Using port $PORT to send or receive requests."
+
+# Need to run from docker directory
+cd docker/
+
+# Create the container image
+build_lmcache_vllmopenai_image
+
+########
+# MAIN #
+########
+
+for cfg_name in "${CONFIG_NAMES[@]}"; do
+    echo -e "\033[1;33m===== Testing LMCache with ${cfg_name} =====\033[0m"
+    cfg_file="${CONFIG_DIR}/${cfg_name}"
+
+    # Start engine
+    feature_type=$(yq -r '.feature.type // ""' "$cfg_file")
+    if [[ "$feature_type" == "pd" ]]; then
+        PORT1=$(find_available_port 8100)
+        prefiller_docker_args="$(yq '.["docker-prefiller"]' "$cfg_file")"
+        prefiller_vllm_args="$(yq '.["vllm-prefiller"]' "$cfg_file")"
+        PORT2=$(find_available_port 8200)
+        decoder_docker_args="$(yq '.["docker-decoder"]' "$cfg_file")"
+        decoder_vllm_args="$(yq '.["vllm-decoder"]' "$cfg_file")"
+        run_pd_lmcache "$prefiller_docker_args" "$prefiller_vllm_args" "$decoder_docker_args" "$decoder_vllm_args" "$cfg_name" 
+        model="$(yq -r '.["vllm-prefiller"].model' "$cfg_file")"
+    elif [[ "$feature_type" == "p2p" ]]; then
+        PORT1=$(find_available_port 8177)
+        docker1_args="$(yq '.["docker1"]' "$cfg_file")"
+        vllm1_args="$(yq '.["vllm1"]' "$cfg_file")"
+        PORT2=$(find_available_port 8277)
+        docker2_args="$(yq '.["docker2"]' "$cfg_file")"
+        vllm2_args="$(yq '.["vllm2"]' "$cfg_file")"
+        run_p2p_lmcache "$docker1_args" "$vllm1_args" "$docker2_args" "$vllm2_args" "$cfg_name" 
+        model="$(yq -r '.["vllm1"].model' "$cfg_file")"
+    elif [[ -z "$feature_type" ]]; then
+        docker_args="$(yq '.docker' "$cfg_file")"
+        vllm_args="$(yq '.vllm' "$cfg_file")"
+        run_lmcache_vllmopenai_container "$docker_args" "$vllm_args" "$cfg_name"
+        model="$(yq -r '.vllm.model' "$cfg_file")"
+    fi
+    
+    # Send request
+    test_mode="$(yq -r '.workload.type' "$cfg_file")"
+    if [ "$test_mode" = "dummy" ]; then
+        test_vllmopenai_server_with_lmcache_integrated "$model"
+    elif [ "$test_mode" = "long_doc_qa" ]; then
+        workload_yaml="$(yq "(.workload * {\"model\": \"$model\"}) | del(.type)" "$cfg_file")"
+        cfg_json="$(yq '.' "$cfg_file")"
+        check_warmup_round_time_per_prompt=$(
+            jq -e '(.["checking-fields"] // []) | index("warmup_round_time_per_prompt") != null' \
+                <<< "$cfg_json" >/dev/null && echo true || echo false
+        )
+        check_query_round_time_per_prompt=$(
+            jq -e '(.["checking-fields"] // []) | index("query_round_time_per_prompt") != null' \
+                <<< "$cfg_json" >/dev/null && echo true || echo false
+        )
+        check_query_ttft_per_prompt=$(
+            jq -e '(.["checking-fields"] // []) | index("warmup_ttft_per_prompt") != null' \
+                <<< "$cfg_json" >/dev/null && echo true || echo false
+        )
+        if [[ "$feature_type" == "p2p" ]]; then
+            run_long_doc_qa "$workload_yaml" "$PORT1"
+            run_long_doc_qa "$workload_yaml" "$PORT2" "$check_warmup_round_time_per_prompt" "$check_query_ttft_per_prompt" "$check_query_round_time_per_prompt" "${cfg_name%.yaml}" "$NEED_UPLOAD"
+        else
+            run_long_doc_qa "$workload_yaml" "$PORT" "$check_warmup_round_time_per_prompt" "$check_query_ttft_per_prompt" "$check_query_round_time_per_prompt" "${cfg_name%.yaml}" "$NEED_UPLOAD"
+        fi
+    fi
+
+    # Check memory leak after test
+    sleep 15
+    echo "→ Checking for memory leaks..."
+    if [[ "$feature_type" == "pd" ]]; then
+        # Check both prefiller and decoder instances
+        if ! check_memory_leak "$PORT1"; then
+            echo "Memory leak check failed for prefiller (port $PORT1)"
+            exit 1
+        fi
+        if ! check_memory_leak "$PORT2"; then
+            echo "Memory leak check failed for decoder (port $PORT2)"
+            exit 1
+        fi
+    elif [[ "$feature_type" == "p2p" ]]; then
+        # TODO: p2p check_memory_leak has a known bug, skip for now
+        echo "⚠️  Skipping memory leak check for p2p case: check_memory_leak has a known bug that is being fixed."
+    elif [[ "$cfg_name" == "multi_device.yaml" || "$cfg_name" == "layerwise.yaml" ]]; then
+        echo "⚠️  Skipping memory leak check for $cfg_name case as it's a flaky test while run check_memory_leak check."
+    else
+        # Single instance
+        if ! check_memory_leak "$PORT"; then
+            echo "Memory leak check failed for $cfg_name"
+            exit 1
+        fi
+    fi
+
+    cleanup 0
+done
+
+exit 0
diff --git a/.buildkite/vllm-integration-tests.yml b/.buildkite/vllm-integration-tests.yml
new file mode 100644
index 0000000..b52ea28
--- /dev/null
+++ b/.buildkite/vllm-integration-tests.yml
@@ -0,0 +1,30 @@
+env:
+  DOCKER_BUILDKIT: 1
+
+steps:
+  - label: ":rocket: vLLM Integration Tests"
+    key: "test"
+    timeout_in_minutes: 60
+    commands:
+      - chmod +x .buildkite/scripts/vllm-integration-tests.sh
+      - |
+        # Ensure artifact is created even if test crashes
+        create_artifact() {
+          if ls /tmp/build_${BUILDKITE_BUILD_ID}_*.log 1>/dev/null 2>&1; then
+            cat /tmp/build_${BUILDKITE_BUILD_ID}_*.log > build_${BUILDKITE_BUILD_ID}.log 2>/dev/null || true
+          else
+            echo "No log files found for build ${BUILDKITE_BUILD_ID}" > build_${BUILDKITE_BUILD_ID}.log
+          fi
+        }
+        trap 'test_exit_code=$?; create_artifact; exit $test_exit_code' EXIT INT TERM
+        BUILD_ID=${BUILDKITE_BUILD_ID} .buildkite/scripts/vllm-integration-tests.sh --hf-token=$HF_TOKEN --server-wait-timeout=240 --configs=.buildkite/cases/integration-cases.txt
+        test_exit_code=$?
+        create_artifact
+        exit $test_exit_code
+        export TARGET="$PWD"
+        echo "Deleting current workspace $TARGET"
+        cd /
+        sudo rm -rf "$TARGET"
+
+    artifact_paths:
+      - "build_${BUILDKITE_BUILD_ID}.log"
diff --git a/.clang-format b/.clang-format
new file mode 100644
index 0000000..bcbfcf0
--- /dev/null
+++ b/.clang-format
@@ -0,0 +1,27 @@
+BasedOnStyle: Google
+UseTab: Never
+IndentWidth: 2
+ColumnLimit: 80
+
+# Force pointers to the type for C++.
+DerivePointerAlignment: false
+PointerAlignment: Left
+
+# Reordering #include statements can (and currently will) introduce errors
+SortIncludes: false
+
+# Style choices
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+IndentPPDirectives: BeforeHash
+
+IncludeCategories:
+  - Regex:           '^<'
+    Priority:        4
+  - Regex:           '^"(llvm|llvm-c|clang|clang-c|mlir|mlir-c)/'
+    Priority:        3
+  - Regex:           '^"(qoda|\.\.)/'
+    Priority:        2
+  - Regex:           '.*'
+    Priority:        1
+
diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md
new file mode 100644
index 0000000..145343b
--- /dev/null
+++ b/.claude/skills/create-pr/SKILL.md
@@ -0,0 +1,106 @@
+---
+name: create-pr
+description: Create a GitHub pull request from the current branch to the upstream repo, using the repo's PR template
+allowed-tools: Bash, Read, Glob, Grep, Agent, mcp__github__create_pull_request
+argument-hint: "[base_branch] [--draft] [--title 'PR title']"
+---
+
+# Create Pull Request
+
+Create a GitHub pull request from the current branch to the upstream repository.
+
+## Arguments
+
+`$ARGUMENTS` may contain:
+- First positional arg: base branch to merge into (default: auto-detect from upstream's default branch)
+- `--draft`: create as a draft PR
+- `--title 'PR title'`: override the PR title (default: auto-generated from changes)
+
+## Steps
+
+### 1. Gather context
+
+Run these in parallel:
+
+```bash
+# Check remotes — identify the fork remote and the upstream remote
+git remote -v
+
+# Current branch and tracking info
+git branch -vv --contains HEAD
+
+# Untracked/unstaged changes (warn user if dirty)
+git status -s
+
+# Default branch of the upstream repo
+gh api repos/<UPSTREAM_OWNER>/<UPSTREAM_REPO> --jq '.default_branch'
+```
+
+Determine:
+- **Fork remote**: the remote pointing to the user's fork (usually `local` or `origin` if the user's fork)
+- **Upstream remote**: the remote pointing to the upstream repo (look for the canonical org/repo)
+- **Fork owner**: extracted from the fork remote URL (e.g., `alice` from `git@github.com:alice/LMCache.git`)
+- **Upstream owner/repo**: extracted from the upstream remote URL
+- **Base branch**: from `$ARGUMENTS` or the upstream repo's default branch
+
+### 2. Check the branch is pushed
+
+Verify the current branch is pushed to the fork remote. If not, warn the user and stop — do NOT push without explicit permission.
+
+### 3. Find and read the PR template
+
+```
+Glob pattern: .github/PULL_REQUEST_TEMPLATE.md
+Glob pattern: .github/PULL_REQUEST_TEMPLATE/**/*.md
+Glob pattern: .github/pull_request_template.md
+```
+
+Read the template to understand required sections.
+
+### 4. Analyze changes
+
+```bash
+# Commits on this branch vs the base
+git log --oneline <upstream_remote>/<base_branch>..HEAD
+
+# Diff stat for summary
+git diff <upstream_remote>/<base_branch>..HEAD --stat
+```
+
+If there are many commits, also read the full diff to understand the changes:
+```bash
+git diff <upstream_remote>/<base_branch>..HEAD
+```
+
+### 5. Draft the PR
+
+- **Title**: Use `--title` from arguments if provided. Otherwise, generate a concise title (under 70 chars) summarizing the change.
+- **Body**: Fill in the PR template sections based on the changes. Focus on:
+  - **Why** the change is needed (motivation, problem being solved)
+  - **User-facing changes** (new CLI args, changed behavior, breaking changes)
+  - Do NOT enumerate per-file changes — reviewers can read the diff
+  - Keep it concise and informative
+
+Show the drafted title and body to the user and ask for confirmation before creating the PR.
+
+### 6. Create the PR
+
+Use the `mcp__github__create_pull_request` tool:
+- `owner`: upstream repo owner
+- `repo`: upstream repo name
+- `head`: `<fork_owner>:<branch_name>`
+- `base`: the base branch
+- `title`: the PR title
+- `body`: the PR body
+- `draft`: true if `--draft` was specified
+
+### 7. Report
+
+Print the PR URL so the user can review it.
+
+## Important Notes
+
+- Never push code or create commits — this skill only creates the PR from already-pushed branches.
+- Always show the PR title and body to the user for confirmation before creating.
+- If the working tree is dirty, warn the user that uncommitted changes won't be included.
+- Respect the PR template structure — fill in all sections, use checkboxes where the template has them.
diff --git a/.claude/skills/hybrid-benchmarking/SKILL.md b/.claude/skills/hybrid-benchmarking/SKILL.md
new file mode 100644
index 0000000..c324a5c
--- /dev/null
+++ b/.claude/skills/hybrid-benchmarking/SKILL.md
@@ -0,0 +1,176 @@
+---
+name: hybrid-benchmarking
+description: Benchmark a hybrid-attention model across the LMCache performance ladder (vLLM no-hybrid-allocator → hybrid allocator + prefix caching → hybrid allocator + LMCache) and produce a decode-throughput / TTFT / cache-hit-rate comparison. Use when asked to benchmark, demo, or quantify the value of LMCache caching for a hybrid model.
+allowed-tools: Bash, Read, Grep, Glob, Write
+argument-hint: "<hf-model-id> [--gpus N] [--tp N] [--output-dir DIR]"
+---
+
+# Hybrid-Model Benchmarking — the LMCache performance ladder
+
+Given a hybrid-attention model + hardware, calibrate a `long-doc-qa` workload, run the vLLM
+config ladder, and write `report.md` (launch commands + decode-throughput / TTFT / TPOT /
+hit-rate table + a rationale for every tuned number). Validated on `google/gemma-4-31B-it`
+(sliding-window), `Qwen/Qwen3.6-27B` (Mamba/GDN), and `deepseek-ai/DeepSeek-V4-Flash`
+(sparse-MLA + fp8).
+
+> **Run fully autonomously.** Log each decision and keep going through all runs and the
+> report — do **not** pause for approval/calibration confirmation. Only stop on a hard
+> blocker (model not given, gated weights missing). The user interrupts if something's off.
+
+## Inputs
+
+`$ARGUMENTS`: positional model id (required, e.g. `Qwen/Qwen3.6-27B`); `--gpus N` / `--tp N`
+(default: detect via `nvidia-smi -L`, tp = gpus); `--output-dir DIR` (default
+`./hybrid-bench-<slug>/`). On a shared box, pick free GPUs / non-default ports and never kill
+processes you didn't start.
+
+## The ladder
+
+Same `long-doc-qa` workload, four vLLM configs — each isolates one variable:
+
+| Run | config | what it shows |
+|--|--|--|
+| **A** | allocator off, prefix caching off | baseline: smallest batch → lowest decode tput, worst TTFT |
+| **B** | allocator on, prefix caching off | isolates allocator: packs ~8× more tokens → much higher decode tput |
+| **C** | + `--enable-prefix-caching` (no LMCache) | GPU prefix cache ~0 % hit under batch saturation → ≈ Run B |
+| **D** | + `LMCacheMPConnector` + `lmcache server` | CPU pool serves prefixes → ~100 % hit → lowest TTFT, highest decode tput |
+
+Two counterintuitive facts: **(1)** for sliding-window hybrids the allocator gives the
+*larger* batch (sliding layers keep only a window-sized KV slice → ~`num_layers /
+num_full_layers`× more tokens, ≈8× for Gemma-4), so Run A (all layers full) is the
+*smallest*/slowest. **(2)** Run C's GPU prefix cache is ~0 % hit because the active batch's KV
+(`batch × (doc+output)`) fills the whole pool — no blocks left to *retain* prefixes. That
+saturation gap is exactly what LMCache's CPU pool fills.
+
+> **Mandatory-allocator models → 3 runs (A ≡ B).** Mamba/GDN (Qwen3.5/3.6, Qwen3-Next) and
+> DeepSeek-V4 sparse-MLA have no allocator-off baseline — `--disable-hybrid-kv-cache-manager`
+> is rejected (Mamba) or fails at runtime (DeepSeek: CuTe sparse-attn needs C128/block_size=8).
+> Drop Run A; the story is the cache (C→D). The full 4-run structure applies only to
+> sliding-window hybrids (Gemma 3/4, gpt-oss).
+
+## Make the criteria visible
+
+Default `long-doc-qa` is prefill-bound, which *hides* the decode gap. **Always** pass
+`--ignore-eos --ldqa-max-output-length <N>` (≈2048 at L=24 000) → decode-bound *and* deterministic
+(identical total output tokens/run, so decode-throughput numbers are reproducible). Size the
+working set to **overflow the GPU pool but fit the LMCache pool with margin** (step 3).
+
+## Procedure
+
+**0 — Versions + env.** Record for the report (benchmarks are meaningless without them):
+`vllm --version` (→ commit); LMCache `git rev-parse --short HEAD` + `git status --short` (note
+any local patch, e.g. the `--ignore-eos` / `--ldqa-max-output-length` bench patch → record "base
+commit + with `<patch>`"). Export `HF_HOME` if weights live off-default — for **every** command
+(env doesn't persist across tool calls). Read the model's `docs/source/recipes/*.rst` for
+validated flags + quirks (else `docs/source/mp/hybrid_models.rst`, and warn it's unvalidated).
+Confirm weights are present.
+
+**1 — Classify → decide Run A.**
+
+| Family | Examples | Run A |
+|--|--|--|
+| Sliding-window + full | Gemma 3/4, gpt-oss | `--disable-hybrid-kv-cache-manager --no-enable-prefix-caching` |
+| Mamba / GDN | Qwen3.5/3.6, Qwen3-Next | allocator mandatory → no Run A; caching is non-bit-exact (GDN) |
+| Sparse-MLA + fp8 | DeepSeek-V4 | allocator mandatory (CuTe needs C128/block_size=8) → no Run A |
+| Dense | Llama, Mistral | not a hybrid; allocator distinction is moot |
+
+Classify via the recipe, else HF `config.json` `architectures`/`layer_types`.
+
+**2 — Probe pools.** Launch with `--max-model-len auto` (**never pin small** — it shrinks the
+sliding-window pool ~5×). From the startup log record GPU pool tokens for hybrid (`P_B`) and
+hybrid-off (`P_A`); their ratio is the allocator gain. For LMCache, once the server+connector
+engine is up read `cache_size_per_token` from `/status` → `tokens_per_gb = 1024³ / it`; pass it
+via `--tokens-per-gb-kvcache` so `num_documents` is identical across runs. (Real on-pool storage
+≈ 1.4× this — size against that, not the raw number.)
+
+**3 — Calibrate.** Util < 0.9; lower it so GPU memory is the binding constraint (0.50 on H200;
+**0.35 for fp8 DeepSeek** — fp8 makes the GPU pool huge). Pick `L` (≤ `P_A`, a sane hybrid batch
+`P_B/(L+output)`, a meaningful prefix). `num_documents = floor(kv_cache_volume_gb × tokens_per_gb
+/ L)` chosen so it **overflows GPU** (`num_docs × L > P_B`) and **fits LMCache with margin**
+(real storage ≈ 1.4×(tokens / tokens_per_gb) ≤ ~0.6 × `l1_size_gb`, watermark 0.95). `l1_size_gb`
+≤ host RAM and /dev/shm. Set `--ldqa-max-output-length` so decode dominates (≈2048 @ L=24 000). Log
+the operating point and proceed.
+
+**4 — Freeze one shared config.**
+```bash
+lmcache bench engine --engine-url http://localhost:8000 --workload long-doc-qa \
+    --model <model> --tokens-per-gb-kvcache <N> --kv-cache-volume <GB> \
+    --ldqa-document-length <L> --ldqa-query-per-document 1 \
+    --ldqa-num-inflight-requests <≥ hybrid batch> --ldqa-max-output-length <out> --ignore-eos \
+    --no-interactive --export-config "$OUT/shared.json"
+```
+Replay every run with `--config "$OUT/shared.json"` (so `num_documents` is byte-identical, even in A/B with no server).
+
+**5 — Run.** Start `lmcache server` **first** so its pinned pool pre-expands (lazy ~80 GiB/min) before D:
+```bash
+lmcache server --port 5560 --http-port 8090 --prometheus-port 9099 \
+    --l1-size-gb <GB> --eviction-policy LRU --eviction-trigger-watermark 0.95 [--chunk-size N]
+```
+Each run: launch engine → poll `curl -sf :8000/health` → snapshot metrics (step 6) → bench → teardown. `<base>` = recipe flags (`--tensor-parallel-size`, `--trust-remote-code`, …).
+```bash
+# Run-flags appended to <base>:
+#   A  --disable-hybrid-kv-cache-manager --no-enable-prefix-caching   (skip for mandatory-allocator families)
+#   B  --no-enable-prefix-caching
+#   C  --enable-prefix-caching
+#   D  C + --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.port":5560,"lmcache.mp.mq_timeout":900}}'
+vllm serve <model> <base> --gpu-memory-utilization <U> --max-model-len auto --port 8000 <run-flags>
+lmcache bench engine --engine-url http://localhost:8000 --config "$OUT/shared.json" \
+    --no-interactive --json --output-dir "$OUT/run-<A|B|C|D>"
+```
+**Run D at steady state:** bench **twice** — run #1 primes, run #2 measures; report run #2's delta. First confirm the pool is pinned (`/status memory_total_bytes ≈ l1`) and the engine registered (`cache_context_meta` non-empty).
+**Teardown by PID, not pattern:** `pkill -f "vllm serve …"` self-matches (exit 144) and orphans EngineCore/Workers that keep holding GPU memory. Kill the main PID + worker PIDs from `nvidia-smi --query-compute-apps`; kill `lmcache server` cleanly; verify GPUs return to ~0 MiB.
+
+**6 — Metrics.** Bench JSON `results`: `mean_ttft_ms`, `p90/p99_ttft_ms`, `output_throughput`
+(decode), `input_throughput` (prefill), `mean_decode_speed` (TPOT = 1000/it),
+`total_output_tokens`. **Hit rate from vLLM `:8000/metrics`** (LMCache Prometheus is often
+disabled in MP builds): `prefix_cache_*` (GPU-local), `external_prefix_cache_*` (LMCache).
+Snapshot before/after each bench; for D report the measure-run delta and prefer the
+`external_prefix_cache_*` token counters.
+
+**7 — Report `$OUT/report.md`.** Header: versions, hardware, TP. **(a)** exact launch commands
+(server + runs + bench; note D's prime+measure double-run). **(b)** table: decode tput,
+mean/p90/p99 TTFT, TPOT, prefill tput, hit rate, wall-clock, GPU pool tokens, effective batch.
+**(c)** rationale + findings, validating the criteria explicitly: A→B decode jumps (≈8× batch);
+B→C ≈ no change (0 % hit, saturated); C→D TTFT collapses + decode rises (hit ~100 %).
+
+## Family turnkey configs
+
+**Mamba/GDN** (Qwen3.5/3.6, …): every run uses `--mamba-cache-mode align
+--max-num-batched-tokens 2N-1`, where N is the unified block size (vLLM logs `Setting attention
+block size to N tokens`; also set server `--chunk-size N`). **Use 2N-1, not N** — at exactly N a
+decoding request consumes the per-step budget, so a new request's block-aligned prefill rounds
+to 0 tokens → serial execution (Running:1, ~7× slower; verified by single-variable A/B). Also
+`--max-num-seqs ≤ #Mamba cache blocks` vLLM reports, or CUDA-graph capture fails.
+
+**DeepSeek-V4 sparse-MLA + fp8**: `export CUDA_HOME=/usr/local/cuda-<ver>
+PATH=$CUDA_HOME/bin:$PATH` (sparse-attn JIT fails on the default toolchain) for **every** launch;
+flags `--kv-cache-dtype fp8_ds_mla --trust-remote-code --tokenizer-mode deepseek_v4
+--enable-expert-parallel`. **Util ≈0.35** (at 0.80 the fp8 GPU pool swallows the whole working
+set → nothing for LMCache to serve); large `--l1-size-gb` (full per-token state ~62 KB,
+`tokens_per_gb ≈ 16 800`).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|--|--|
+| B decode ≈ A (not ≫) | run is prefill-bound — add `--ignore-eos`, raise `--ldqa-max-output-length` |
+| D hit ≪ 100 % | working set hit the watermark mid-fill — pre-pin before D; raise `--l1-size-gb`; shrink working set (real ≈1.4× est.) |
+| D aborts "register_kv_caches within 300s" | big pinned pool → set `lmcache.mp.mq_timeout` ≥ 900 |
+| reg hangs "Wrapping N KV tensors for IPC" | server/connector transfer-mode mismatch — use default (auto) on both |
+| pool ~5× too small | `--max-model-len` pinned — use `auto` |
+| `exit 144` / leaked GPU after kill | `pkill` self-matched / orphaned workers — kill by PID (main + `nvidia-smi` workers) |
+| "CUDA compiler … headers are incompatible" (DeepSeek) | set `CUDA_HOME` matching torch's CUDA, every launch |
+| "CuTe DSL … only supports C128 block_size=8" | tried to disable the allocator on DeepSeek — don't; it's mandatory (3 runs) |
+| fp8: D ~100 % but no saturation / nothing to serve | GPU pool fits the whole working set — lower util (≈0.35) |
+
+## Flag cheat-sheet
+
+- Allocator off: `--disable-hybrid-kv-cache-manager` (sliding-window/dense only).
+- Prefix caching: `--no-enable-prefix-caching` / `--enable-prefix-caching`.
+- Deterministic decode-bound: `--ignore-eos --ldqa-max-output-length <N>`.
+- Pools: `--max-model-len auto`; `lmcache server --l1-size-gb <GB> --eviction-trigger-watermark 0.95` (start early to pre-pin).
+- LMCache wiring: `--kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.port":5560,"lmcache.mp.mq_timeout":900}}'`.
+- Mamba/GDN: `--mamba-cache-mode align --max-num-batched-tokens 2N-1`, server `--chunk-size N`.
+- DeepSeek sparse-MLA: `CUDA_HOME` set; `--kv-cache-dtype fp8_ds_mla --tokenizer-mode deepseek_v4 --enable-expert-parallel`; util ≈0.35.
+- Hit rate: vLLM `:8000/metrics` (`prefix_cache_*` GPU-local, `external_prefix_cache_*` LMCache).
+- Teardown: by PID; verify GPUs ~0 MiB.
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
new file mode 100644
index 0000000..c1b4858
--- /dev/null
+++ b/.claude/skills/pr-review/SKILL.md
@@ -0,0 +1,205 @@
+---
+name: pr-review
+description: Review a GitHub pull request against the LMCache coding standards
+allowed-tools: Bash, Read, Grep, Glob, Agent, mcp__github__pull_request_read, mcp__github__list_pull_requests, mcp__github__search_pull_requests, mcp__github__add_reply_to_pull_request_comment
+argument-hint: "<PR number or URL>"
+---
+
+# PR Review: LMCache Code Quality Standard
+
+Review a pull request against the LMCache coding standards defined in `docs/coding_standards.md`.
+
+## Inputs
+
+`$ARGUMENTS` is a PR number (e.g., `3032`) or a GitHub PR URL.
+
+## Review Process
+
+### Step 0 -- Load the standards
+
+Read `docs/coding_standards.md` at the repo root. This is the authoritative reference for
+all quality checks. Also read `AGENTS.md` for the quick-reference checklist.
+
+### Step 1 -- Understand the PR
+
+1. Fetch the PR metadata (`get`) to understand the title, description, author, and base branch.
+2. Fetch the diff (`get_diff`) to see exactly what changed.
+3. Fetch the list of changed files (`get_files`) for a structural overview.
+4. Read any design docs referenced in the PR description. `docs/design/` mirrors
+   the `lmcache/` package tree, so for each changed module `lmcache/<path>/`
+   check `docs/design/<path>/` for relevant docs.
+5. For each **changed public symbol** (function, method, class, field), note its fully qualified name. You will use these in Step 4 to find callers.
+
+### Step 2 -- Design Doc Compliance
+
+If a relevant design doc exists (check `docs/design/<path>/` for each changed
+module `lmcache/<path>/`; `docs/design/` mirrors the `lmcache/` package tree):
+
+- Check that the implementation conforms to documented contracts, invariants, and assumptions.
+- Present compliance as a table:
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| ... | pass/fail | ... |
+
+If no design doc is relevant, state that and skip this section.
+
+### Step 3 -- Coding Quality Review
+
+Review the diff against these standards (from `docs/coding_standards.md`):
+
+**Typing (Section 2)**:
+- All new/modified functions have type hints for arguments and return values.
+- No use of `Any` or bare generic containers (`list`, `dict`, `tuple`).
+- No `assert` used for runtime validation -- must use `if/raise ValueError`.
+
+**Docstrings (Section 3)**:
+- All new/modified public functions have complete docstrings (summary, args, returns, raises, notes).
+- Docstrings match actual current behavior (not planned future behavior).
+- Modified functions have updated docstrings.
+
+**Function and Interface Design (Section 4)**:
+- Function names are self-explanatory.
+- No ambiguous return values (e.g., `None` meaning two different things).
+- No boolean parameters where an enum or function split would be clearer.
+- Dict/container parameters have documented schemas.
+- Caller assumptions documented in docstrings.
+- Class interfaces are minimal (no unnecessary public methods).
+- No cross-class private member access.
+
+**New Functionality (Section 5)**:
+- Design doc present for non-trivial features.
+- Tests cover new features (error-severity if missing).
+- Tests verify public interface, not implementation details.
+- Tests do not access private members.
+
+**Modifications (Section 6)**:
+- Docstrings updated for changed functions.
+- User/design docs updated if behavior changes.
+- Checked for reusable existing code.
+
+**Code Organization (Section 7)**:
+- License header present on new Python files.
+- Import ordering correct (Standard / Third Party / First Party / Local).
+- All imports at file top (no lazy imports).
+- `import torch` before native C extensions.
+- Uses `init_logger(__name__)` from `lmcache.logging`, not bare `logging.getLogger()`.
+- Operational logs at DEBUG level (not INFO).
+- Log levels appropriate (no WARNING for expected concurrent conditions).
+- Module-level helpers at top; private methods at end of class.
+
+**Resource Management (Section 7.5-7.6)**:
+- Error paths release locks, free pool entries, close file descriptors.
+- No unbounded collection growth (sets/dicts cleaned up when resources freed).
+- No unnecessary memory copies in hot paths.
+- CUDA/GPU resources properly managed.
+
+### Step 4 -- Caller Impact Analysis (Section 6.2)
+
+This step is what distinguishes a real review from a diff-reader. For each changed
+public symbol identified in Step 1, verify the change is safe for **every unchanged caller**.
+
+**Triggers -- run this step whenever the PR:**
+- Adds, removes, renames, or reorders parameters of a public function/method
+- Changes parameter types, defaults, or accepted domains (e.g., adds `None` to accepted values, narrows a type)
+- Changes return types or the meaning of sentinel returns (e.g., what `None` means)
+- Adds, removes, or changes raised exceptions
+- Changes side effects, ordering, blocking behavior, or thread-safety guarantees
+- Modifies a method on a base class or protocol (subclasses are callers)
+- Changes an invariant of a class field accessed by public API
+
+**How to find callers:**
+
+1. Use `Grep` with the symbol name across the repo (do not filter to only changed files).
+   Include `tests/`, `benchmarks/`, `lmcache/integration/`, and `docs/` in the search.
+2. For common function names that may have many false matches, use `Grep` with
+   `-A 2 -B 2` to see context, or use the `Agent` (Explore) tool with a focused
+   prompt (e.g., "find all callers of `L1Manager.is_key_evictable` and summarize
+   what they do with the return value").
+3. For base-class/protocol changes, also grep for subclasses
+   (`class \w+\(<BaseName>`).
+
+**For each caller, check:**
+- Is the new signature compatible with this call site? (Keyword arg renames are especially dangerous.)
+- Does the caller still handle the new return type / new exceptions correctly?
+- Does the caller pass the output to something else whose contract would now be violated?
+- If the change is backwards-compatible at the signature level, is it also backwards-compatible at the **semantic** level (e.g., does a now-optional param change default behavior)?
+
+**Flag as error severity:**
+- Any unchanged caller that is now broken and not updated in the PR.
+- Any protocol/base-class change where at least one implementer is not updated.
+
+**Flag as warning severity:**
+- Callers whose assumptions are weakened by the change and whose correctness is not obviously preserved.
+
+Report findings as part of the issues list, with the path:line of the affected caller and a one-line explanation of the impact.
+
+### Step 5 -- Thread Safety (Section 8)
+
+- Shared state protected by locks.
+- Lock granularity appropriate.
+- Concurrent access from multiple controller threads is safe.
+- Even debug/test-only methods hold locks when accessing shared state.
+
+### Step 6 -- Test Coverage (Section 5.2)
+
+- New features have tests (error-severity if missing).
+- Bug fixes have regression tests (error-severity if missing).
+- Tests verify public API and docstring contract.
+- Tests do not access private members or test private functions directly.
+- Note what is tested and what is missing (especially failure paths and concurrent access).
+
+### Step 7 -- PR Structure (Section 1.1)
+
+- Is the PR appropriately scoped? If too many changed files, suggest how to break it down.
+
+## Output Format
+
+### Summary
+One paragraph describing what the PR does.
+
+### Design Doc Compliance
+Table (if applicable) or "No relevant design doc."
+
+### Issues
+
+Group issues by severity, following the calibration from `docs/coding_standards.md` Section 9.2:
+
+**error** (must fix before merge):
+- Missing SPDX header, missing type hints, missing docstrings on public functions,
+  new feature with zero tests, bug fix with no regression test, cross-class private
+  member access, poor architectural decision, ambiguous return values, `assert` for
+  runtime validation, docstring that misrepresents behavior.
+
+**warning** (should fix):
+- Docstring could be more detailed, tests that test implementation details, naming
+  could be clearer, code could be more modular, missing `strict=True` on `zip` of
+  parallel lists, log level too high for operational messages.
+
+**info** (suggestion, non-blocking):
+- Optional naming improvement, minor refactor for readability, style preference.
+
+For each issue, include:
+- File path and line number(s)
+- What the issue is and why it matters
+- Suggested fix (if straightforward)
+
+### Summary Table
+
+| Severity | Count | Key Items |
+|----------|-------|-----------|
+| error    | N     | ... |
+| warning  | N     | ... |
+| info     | N     | ... |
+
+## Reviewer Rules
+
+- The review is scoped to the diff, with **one exception**: unchanged callers of
+  changed symbols (Step 4). Flag a caller in unchanged code only when the PR's
+  changes demonstrably affect it; do not review unrelated issues in those files.
+- Do NOT praise the code. Only report issues or confirm the PR is clean.
+- Do NOT pad findings. If the PR is clean, say "PR is clean" and list what was checked.
+- Be precise about file paths and line numbers.
+- If unsure whether something is an issue, treat it as `info`, not `error`.
+- Do NOT leave trivial or nitpick comments that linters would catch.
+- Focus on design decisions, architectural soundness, correctness, caller impact, thread safety, code cleanliness, modularity, and maintainability.
diff --git a/.claude/skills/pre-pr-check/SKILL.md b/.claude/skills/pre-pr-check/SKILL.md
new file mode 100644
index 0000000..4e5ffef
--- /dev/null
+++ b/.claude/skills/pre-pr-check/SKILL.md
@@ -0,0 +1,256 @@
+---
+name: pre-pr-check
+description: Check local changes against the LMCache coding standards and fix issues before creating a PR
+allowed-tools: Bash, Read, Edit, Write, Grep, Glob, Agent
+argument-hint: "[--scope uncommitted|branch|staged] [--fix|--check-only]"
+---
+
+# Pre-PR Check: LMCache Coding Standard Compliance
+
+Check the developer's local changes against the coding standards defined in
+`docs/coding_standards.md` and modify the code to fix compliance issues, so the
+PR is clean before it is opened.
+
+This skill is meant to be run **before** `/create-pr`.
+
+## Arguments
+
+- `--scope` (default: `branch`)
+  - `uncommitted` -- check only unstaged + staged changes vs HEAD
+  - `staged` -- check only staged changes
+  - `branch` -- check all commits on the current branch not yet in `dev` (the
+    full PR diff). This is the default since that matches what a reviewer sees.
+- `--fix` (default) -- automatically fix issues that can be fixed mechanically
+- `--check-only` -- only report issues, do not modify files
+
+## Workflow
+
+### Step 0 -- Load the standard
+
+Read `docs/coding_standards.md` at the repo root. This is the authoritative reference.
+
+### Step 1 -- Detect the scope of changes
+
+Run `git status --short` and `git branch --show-current` to orient yourself.
+
+Then, based on `--scope`, compute the diff:
+
+| Scope | Command |
+|-------|---------|
+| `uncommitted` | `git diff HEAD` |
+| `staged` | `git diff --cached` |
+| `branch` (default) | `git diff dev...HEAD` |
+
+Also list changed files:
+
+| Scope | Command |
+|-------|---------|
+| `uncommitted` | `git diff --name-only HEAD` |
+| `staged` | `git diff --cached --name-only` |
+| `branch` | `git diff --name-only dev...HEAD` |
+
+If there are no changes in the selected scope, report that and stop.
+
+### Step 2 -- Read the changed files
+
+For each changed file, read the current content (not just the diff) so you can
+make accurate edits. Focus on:
+- `.py` files -- full coding-standard review
+- `.md`, `.rst` -- documentation review (brief)
+- `.cpp`, `.cu`, `.rs` -- light review (style only; clang-format / cargo fmt handle most of it)
+
+For each changed file, also identify the **changed public symbols** (functions,
+methods, classes, fields whose signature, return type, raised exceptions, or
+behavior contract changed). You will use these in Step 4 to find and inspect callers.
+
+For large changes, delegate to the Explore agent to summarize per-file
+responsibilities before reviewing.
+
+### Step 3 -- Run the checks
+
+For each changed Python file, check the following (from `docs/coding_standards.md`):
+
+#### A. Mechanical issues (fix automatically unless `--check-only`)
+
+These are straightforward to fix:
+
+1. **License header** (Section 1.3): Missing `# SPDX-License-Identifier: Apache-2.0` on line 1 of new Python files.
+2. **`assert` used for runtime validation** (Section 2.2): Replace with `if <not cond>: raise ValueError(<clear msg>)`.
+3. **`Optional` usage** (Section 2.1): Where a value is always initialized, remove the `Optional` wrapper and initialize directly. Where None is genuinely possible, rewrite as `X | None`.
+4. **Bare generics** (Section 2.1): Replace bare `list`, `dict`, `tuple`, `set` in annotations with parameterized forms (`list[T]`, `dict[K, V]`).
+5. **Lazy imports** (Section 7.2): Move imports to the top of the file, under the correct section heading. Preserve `torch`-before-native-C-extension ordering.
+6. **Bare `logging.getLogger(__name__)`** (Section 7.4): Replace with `init_logger(__name__)` from `lmcache.logging`.
+7. **Operational logs at `INFO` level** (Section 7.4): If a log is about store/retrieve/task progress, change `logger.info(...)` to `logger.debug(...)`.
+8. **Inappropriate `WARNING`** (Section 7.4): For log messages about benign concurrent conditions (e.g., "key not found, this should not happen" in a code path documented as not holding the global lock), downgrade to `debug` and fix the misleading message.
+
+#### B. Docstring issues (fix when content is clear; ask when content is unclear)
+
+9. **Missing docstrings** on public/modified functions (Section 3.1-3.2):
+   - If the function is simple and its purpose is obvious from the code, draft a full docstring (summary, args, returns, raises).
+   - If behavior is non-obvious, draft a docstring with clear sections but add a `TODO: confirm` note where you are uncertain, and flag it in the report.
+10. **Docstring accuracy** (Section 3.3): If you added a parameter but the docstring still describes the old signature, update it. If a parameter is currently a no-op (accepted but ignored), the docstring must say so explicitly.
+11. **Missing type hints** on function args or return values (Section 2.1): Add them based on the function's body.
+
+#### C. Design issues (flag; do NOT silently refactor)
+
+These are judgment calls and should be reported, not auto-fixed:
+
+12. **Cross-class private member access** (Section 4.4): Accessing `other._private` outside the defining class.
+13. **Ambiguous return values** (Section 4.3): Function returns `None` for multiple distinct meanings.
+14. **Boolean parameters on public APIs** (Section 4.3).
+15. **New features without tests** (Section 5.2).
+16. **Bug fixes without regression tests** (Section 5.2).
+17. **Unbounded collection growth** (Section 7.6): A set/dict that is appended to without cleanup.
+18. **Error paths that leave state inconsistent** (Section 7.5): Exceptions that skip lock release, FD close, or pool free.
+19. **Missing design doc** for non-trivial new features (Section 5.1).
+20. **PR scope too large** (Section 1.1): If the diff touches many unrelated modules, suggest how to split.
+21. **Lock protocol violations** (Section 8): Debug methods not holding `self._lock`; shared state accessed without synchronization.
+
+### Step 4 -- Apply fixes
+
+For category A and B issues (unless `--check-only`):
+- Use `Edit` to make precise, minimal changes.
+- Preserve existing comments and code style.
+- After fixes, re-read the file to confirm the edit applied cleanly.
+
+For category C issues: do NOT auto-fix. Report them for the developer to address.
+
+### Step 5 -- Caller Impact Analysis (Section 6.2 of the standard)
+
+Even when the diff itself looks clean, a change can silently break unchanged
+callers. Before declaring the changes ready for PR, verify the global view for
+each changed public symbol identified in Step 2.
+
+**Triggers -- run this step if the diff does any of:**
+- Adds, removes, renames, or reorders parameters of a public function/method
+- Changes parameter types, defaults, or accepted domains (e.g., adds `None` to accepted values, narrows a type)
+- Changes the return type or the meaning of sentinel returns (e.g., what `None` means)
+- Adds, removes, or changes raised exceptions
+- Changes side effects, ordering, blocking behavior, or thread-safety guarantees
+- Modifies a method on a base class or protocol (subclasses are callers)
+- Changes an invariant of a class field accessed by public API
+
+If none of the above applies, skip this step.
+
+**How to run it:**
+
+1. For each changed public symbol, `Grep` its name across the whole repo
+   (production code, `tests/`, `benchmarks/`, `lmcache/integration/`, `docs/`).
+   Do not limit to files in the diff.
+2. For commonly-named symbols with many false matches, use `Grep -A 2 -B 2`
+   for context, or delegate to the `Agent` (Explore) tool with a focused prompt
+   (e.g., "find all callers of `LMCacheMPWorkerAdapter.submit_store_request`
+   and summarize the arguments each caller passes").
+3. For base-class / protocol changes, also grep for subclasses
+   (`class \w+\(<BaseName>`).
+
+**For each caller, decide:**
+
+- **Broken and must be fixed in this PR** (category A-like, fix it):
+  - Removed / renamed parameter that the caller passes by keyword
+  - Reordered positional parameters the caller relies on
+  - Return type change that the caller destructures (e.g., tuple shape change)
+  - Newly raised exception the caller doesn't handle, when the caller is on the normal success path
+
+  For these, update the caller in the same pass as the main change. Apply the
+  edit using `Edit`, then re-read to confirm. If the caller is in an unrelated
+  module and the fix is non-trivial, flag it for manual review instead.
+
+- **Behaviorally risky** (category C-like, flag for the developer):
+  - Signature is still compatible but semantics changed (e.g., a return value
+    that used to always be non-empty can now be empty)
+  - Caller passes through to another function whose contract may now be violated
+  - Base-class change where a subclass may need updating even though the
+    signature is backwards-compatible
+
+  Do NOT silently edit these -- the developer needs to confirm the intent. Flag
+  them in the output with `path:line` of the caller and a one-line explanation.
+
+- **Safe** (no action):
+  - Backwards-compatible signature extension the caller does not use
+  - Change in an internal detail not observable at the call site
+
+Track the caller-impact findings under the existing output sections:
+- Auto-fixed callers go under "Auto-fixed issues" with a new category "Caller updates"
+- Flagged risky callers go under "Manual review required" with severity
+  `error` if the caller is clearly broken and `warning` otherwise
+
+### Step 6 -- Final verification
+
+Run these checks and report the outcome. Do NOT auto-run them; print the command the developer should run (respecting the user's preference to run these themselves):
+
+```bash
+pre-commit run --all-files
+pytest -xvs tests/v1/distributed/        # if distributed/ changed
+pytest -xvs tests/v1/mp_observability/   # if mp_observability/ changed
+```
+
+## Output Format
+
+### Summary
+- Scope: `<uncommitted|staged|branch>`
+- Files changed: `<N>`
+- Issues found: `<total>` (auto-fixed: `<N>`, manual: `<N>`)
+
+### Auto-fixed issues
+Grouped by category, with file:line references. E.g.:
+
+**Typing (3 fixes)**
+- `lmcache/v1/foo.py:42` -- replaced `Optional[int]` with `int | None`
+- `lmcache/v1/foo.py:87` -- added type hint for `limit: int` and return type `-> list[str]`
+- `lmcache/v1/bar.py:120` -- replaced `dict` with `dict[str, int]`
+
+**Runtime validation (1 fix)**
+- `lmcache/v1/config.py:548` -- replaced `assert config.url is not None` with `if config.url is None: raise ValueError("url is required")`
+
+**Docstrings (2 fixes)**
+- `lmcache/v1/baz.py:15` -- added full docstring for public method `submit_request`
+- `lmcache/v1/baz.py:60` -- updated docstring for `lookup` to reflect new `cache_salt` parameter
+
+### Manual review required (needs developer judgment)
+
+Grouped by severity:
+
+**error** (must fix before PR):
+- `lmcache/v1/foo.py:230` -- new feature `BatchProcessor.process_async` has no tests in `tests/v1/`. Add unit tests that exercise the public `process_async` API.
+- `lmcache/v1/bar.py:15` -- `BarAdapter.do_thing` accesses `self._cache._internal_map` directly; use a public accessor or expose a method on `Cache`.
+
+**warning** (should fix):
+- `lmcache/v1/baz.py:42` -- `register(name: str, force: bool)` uses a boolean parameter. Consider splitting into `register(name)` and `register_overwrite(name)`, or using an enum `RegisterMode`.
+
+**info** (suggestion):
+- `lmcache/v1/baz.py:78` -- filter parameter is named `filter`; consider `key_eligible_filter` for clarity.
+
+### Commands to run next
+
+```bash
+pre-commit run --all-files
+# then run relevant test suites
+```
+
+### Summary table
+
+| Category | Auto-fixed | Manual | Total |
+|----------|-----------|--------|-------|
+| Typing | 3 | 0 | 3 |
+| Runtime validation | 1 | 0 | 1 |
+| Docstrings | 2 | 0 | 2 |
+| Design | 0 | 2 | 2 |
+| Tests | 0 | 1 | 1 |
+| **Total** | **6** | **3** | **9** |
+
+## Rules
+
+- Only touch files in the selected scope, **except** when Step 5 identifies an
+  unchanged caller that is clearly broken by a signature change in this PR. In
+  that case, update the caller in the same pass. Do not otherwise "improve"
+  unchanged files.
+- Never add error handling, fallbacks, or validation that the task does not require.
+- Never introduce new abstractions, helpers, or dependencies in fixes.
+- When a fix requires judgment (e.g., "what should this docstring say?" or "is
+  this caller's assumption still valid?"), prefer to flag it for manual review
+  rather than guess.
+- Never run `git add`, `git commit`, or `git push`. The developer handles git operations themselves.
+- Never run `pre-commit` or the test suite automatically; print the command for the developer to run.
+- If the scope is `branch` and the branch has no upstream or is far behind `dev`, warn the developer but proceed.
+- If `docs/coding_standards.md` is missing, stop and ask the developer to check it out or pull the latest `dev`.
diff --git a/.cursor/BUGBOT.md b/.cursor/BUGBOT.md
new file mode 100644
index 0000000..19d38c7
--- /dev/null
+++ b/.cursor/BUGBOT.md
@@ -0,0 +1,74 @@
+# LMCache Code Review Style Guide
+
+This is the style guide for the LMCache project — a KV cache management engine
+for LLM serving (vLLM/SGLang integration, GPU/CPU/disk/S3 storage tiers, CUDA
+kernels, Rust raw-block I/O).
+
+## Review philosophy
+
+Do NOT care about security-related issues or small trivial matters. ONLY focus
+on design decisions, architectural soundness, technical debt, code cleanliness,
+modularity, and future maintainability and readability.
+
+## Project conventions
+
+Read these files for project standards:
+- `AGENTS.md` — coding conventions, testing practices, review checklist
+- `CONTRIBUTING.md` — contribution guidelines
+
+## What to check
+
+### Convention Compliance & Documentation
+
+- All new/modified `.py` files have `# SPDX-License-Identifier: Apache-2.0` as line 1
+- All new functions have type hints (arguments + return values)
+- All new public functions have docstrings (what, args, return, exceptions)
+- Docstrings match the function's actual behavior
+- No private member access (`_`-prefixed attributes) across class boundaries
+- Import order: Standard / Third Party / First Party / Local (with section heading comments)
+- Code passes ruff rules: E (pycodestyle), F (pyflakes), B (bugbear), SLF (self/private access)
+- Formatting consistent with ruff (line-length 88) and isort (black profile, from_first=true)
+- User-facing changes reflected in `docs/source/` if applicable
+- Breaking changes explicitly called out
+- New docs placed in correct subdirectory and linked from a toctree
+- Design documents updated or added for non-trivial new features or architectural changes
+
+### Testing
+
+- New features include corresponding tests
+- Bug fixes include regression tests
+- Tests verify public interface and docstring contract, not implementation details
+- No tests for private methods
+- Test files are in the correct location under `tests/` matching the source structure
+
+### Architecture & Design
+
+- Changes consistent with existing codebase patterns
+- New abstractions justified (not premature)
+- Public APIs minimal and well-defined — no exposed internals
+- Module-level helpers at top of file; private methods at end of class
+- SLF discipline followed (no cross-class private member access), especially in
+  `lmcache/v1/multiprocess/` and `lmcache/v1/distributed/` where CI enforces it
+
+## Severity calibration
+
+- **error** — MUST fix before merge. Examples: missing SPDX header, missing type
+  hints on public function, missing docstring on public function, missing or
+  inaccurate documentation for user-facing changes, new feature with zero tests,
+  poor architectural decision, cross-class private member access in enforced
+  directories, premature abstraction, tightly coupled modules.
+- **warning** — SHOULD fix. Examples: docstring could be more detailed, tests
+  that test implementation details, code could be more modular, naming could
+  be clearer for maintainability.
+- **info** — suggestion only, non-blocking. Examples: could improve naming,
+  optional refactor for readability, minor style preference.
+
+## Rules for the reviewer
+
+- Do NOT report issues in unchanged code — only review lines in the diff.
+- Do NOT praise the code. Only report issues.
+- Do NOT pad findings. If the PR is clean, say so and move on.
+- Be precise about file paths and line numbers.
+- If you are unsure whether something is an issue, treat it as info, not error.
+- Do NOT leave trivial or nitpick comments. If it doesn't affect correctness,
+  maintainability, or readability in a meaningful way, don't comment on it.
diff --git a/.gemini/styleguide.md b/.gemini/styleguide.md
new file mode 100644
index 0000000..c364ed9
--- /dev/null
+++ b/.gemini/styleguide.md
@@ -0,0 +1,75 @@
+# LMCache Code Review Style Guide
+
+This is the style guide for the LMCache project — a KV cache management engine
+for LLM serving (vLLM/SGLang integration, GPU/CPU/disk/S3 storage tiers, CUDA
+kernels, Rust raw-block I/O).
+
+## Review philosophy
+
+Do NOT care about security-related issues or small trivial matters. ONLY focus
+on design decisions, architectural soundness, technical debt, code cleanliness,
+modularity, and future maintainability and readability.
+
+## Project conventions
+
+Read these files for project standards:
+- `docs/coding_standards.md` — **authoritative** coding quality and review standard
+- `AGENTS.md` — coding conventions, testing practices, review checklist
+- `CONTRIBUTING.md` — contribution guidelines
+
+## What to check
+
+### Convention Compliance & Documentation
+
+- All new/modified `.py` files have `# SPDX-License-Identifier: Apache-2.0` as line 1
+- All new functions have type hints (arguments + return values)
+- All new public functions have docstrings (what, args, return, exceptions)
+- Docstrings match the function's actual behavior
+- No private member access (`_`-prefixed attributes) across class boundaries
+- Import order: Standard / Third Party / First Party / Local (with section heading comments)
+- Code passes ruff rules: E (pycodestyle), F (pyflakes), B (bugbear), SLF (self/private access)
+- Formatting consistent with ruff (line-length 88) and isort (black profile, from_first=true)
+- User-facing changes reflected in `docs/source/` if applicable
+- Breaking changes explicitly called out
+- New docs placed in correct subdirectory and linked from a toctree
+- Design documents updated or added for non-trivial new features or architectural changes
+
+### Testing
+
+- New features include corresponding tests
+- Bug fixes include regression tests
+- Tests verify public interface and docstring contract, not implementation details
+- No tests for private methods
+- Test files are in the correct location under `tests/` matching the source structure
+
+### Architecture & Design
+
+- Changes consistent with existing codebase patterns
+- New abstractions justified (not premature)
+- Public APIs minimal and well-defined — no exposed internals
+- Module-level helpers at top of file; private methods at end of class
+- SLF discipline followed (no cross-class private member access), especially in
+  `lmcache/v1/multiprocess/` and `lmcache/v1/distributed/` where CI enforces it
+
+## Severity calibration
+
+- **error** — MUST fix before merge. Examples: missing SPDX header, missing type
+  hints on public function, missing docstring on public function, missing or
+  inaccurate documentation for user-facing changes, new feature with zero tests,
+  poor architectural decision, cross-class private member access in enforced
+  directories, premature abstraction, tightly coupled modules.
+- **warning** — SHOULD fix. Examples: docstring could be more detailed, tests
+  that test implementation details, code could be more modular, naming could
+  be clearer for maintainability.
+- **info** — suggestion only, non-blocking. Examples: could improve naming,
+  optional refactor for readability, minor style preference.
+
+## Rules for the reviewer
+
+- Do NOT report issues in unchanged code — only review lines in the diff.
+- Do NOT praise the code. Only report issues.
+- Do NOT pad findings. If the PR is clean, say so and move on.
+- Be precise about file paths and line numbers.
+- If you are unsure whether something is an issue, treat it as info, not error.
+- Do NOT leave trivial or nitpick comments. If it doesn't affect correctness,
+  maintainability, or readability in a meaningful way, don't comment on it.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 0000000..ca34922
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,109 @@
+# LMCache CODEOWNERS
+
+# Core engine
+/lmcache/v1/cache_engine.py            @ApostaC @YaoJiayi @sammshen
+/lmcache/v1/cache_controller/          @maobaolong @YaoJiayi @chunxiaozheng
+/lmcache/v1/offload_server/            @maobaolong @YaoJiayi
+
+# Memory management
+/lmcache/v1/memory_management.py       @sammshen @deng451e @chunxiaozheng @DongDongJu @ApostaC
+
+# Multiprocess
+/lmcache/v1/multiprocess/              @ApostaC @OasisGit @hlin99
+/lmcache/v1/multiprocess/protocols/observability.py  @royyhuang @ApostaC
+/lmcache/v1/multiprocess/http_server.py              @royyhuang @ApostaC @OasisGit
+/lmcache/v1/mp_observability/            @yoo-kumaneko @royyhuang @ApostaC @OasisGit @sammshen
+
+# Distributed / L2
+/lmcache/v1/distributed/               @ApostaC @maobaolong @chunxiaozheng
+/lmcache/v1/distributed/eviction.py                              @YaoJiayi @hlin99
+/lmcache/v1/distributed/eviction_policy/                         @YaoJiayi @hlin99
+/lmcache/v1/distributed/storage_controllers/eviction_controller.py @YaoJiayi @hlin99
+/lmcache/v1/distributed/l2_adapters/mooncake_store_l2_adapter.py  @maobaolong
+/lmcache/v1/distributed/l2_adapters/resp_l2_adapter.py           @sammshen
+
+# GPU connector
+/lmcache/v1/gpu_connector/             @sammshen @ApostaC @hlin99
+
+# Platform
+/lmcache/v1/platform/                  @maobaolong @hlin99
+
+# Lookup client
+/lmcache/v1/lookup_client/             @maobaolong @YaoJiayi @sammshen
+/lmcache/v1/lookup_client/mooncake_lookup_client.py  @maobaolong
+
+# Storage backends
+/lmcache/v1/storage_backend/           @maobaolong @sammshen @chunxiaozheng @DongDongJu
+/lmcache/v1/storage_backend/connector/base_connector.py        @sammshen @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/instrumented_connector.py @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/s3_connector.py          @sammshen @YaoJiayi
+/lmcache/v1/storage_backend/connector/s3_adapter.py            @sammshen @YaoJiayi
+/lmcache/v1/storage_backend/connector/mooncakestore_connector.py @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/mooncakestore_adapter.py  @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/fs_connector.py          @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/fs_adapter.py            @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/audit_connector.py       @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/audit_adapter.py         @maobaolong @chunxiaozheng
+/lmcache/v1/storage_backend/connector/redis_connector.py      @sammshen @hlin99
+/lmcache/v1/storage_backend/connector/redis_adapter.py        @sammshen @hlin99
+/lmcache/v1/storage_backend/connector/lm_connector.py         @sammshen @hlin99
+/lmcache/v1/storage_backend/connector/lm_adapter.py           @sammshen @hlin99
+
+# Integration
+/lmcache/integration/vllm/             @sammshen @maobaolong @YaoJiayi @deng451e @hlin99
+/lmcache/integration/sglang/           @OasisGit @DongDongJu @sammshen @Shaoting-Feng
+/lmcache/integration/tensorrt_llm/     @sammshen
+
+# Non-CUDA equivalents
+/lmcache/non_cuda_equivalents.py       @hlin99 @hickeyma
+
+# C extensions
+/csrc/                                 @ApostaC @YaoJiayi @sammshen
+/csrc/storage_backends/                @sammshen @hlin99
+
+# Native connector L2 adapters
+/lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py  @sammshen @hlin99
+/lmcache/v1/distributed/l2_adapters/native_plugin_l2_adapter.py     @sammshen @hlin99
+/lmcache/v1/distributed/l2_adapters/fs_native_l2_adapter.py         @sammshen @hlin99
+
+# Offline analysis tools
+/lmcache/tools/                        @yoo-kumaneko
+
+# Tests
+/tests/                                @hickeyma @sammshen @ApostaC @deng451e
+
+# CLI
+/lmcache/cli/                          @KuntaiDu @deng451e @royyhuang @ApostaC @sammshen
+
+# Documentation
+/docs/source/mp/                       @ApostaC @YaoJiayi @KuntaiDu @royyhuang
+/docs/source/kv_cache/                 @sammshen @ApostaC
+/docs/source/kv_cache_optimizations/   @ApostaC @YaoJiayi
+/docs/source/getting_started/          @sammshen @deng451e
+/docs/source/developer_guide/          @sammshen @deng451e
+/docs/source/production/               @maobaolong @chunxiaozheng
+/docs/source/production/kv_cache_events.rst  @hickeyma
+/docs/                                 @sammshen @ApostaC @deng451e
+
+# Examples
+/examples/                             @sammshen @deng451e
+
+# CI / Infrastructure
+/.github/                              @hickeyma @sammshen @ApostaC @deng451e
+/.buildkite/                           @sammshen @ApostaC @deng451e @hickeyma
+
+# Operator
+/operator/                             @royyhuang
+
+# Rust
+/rust/                                 @DongDongJu
+
+# CXL / Maru / DAX
+/lmcache/v1/storage_backend/maru_backend.py            @DongDongJu
+/lmcache/v1/storage_backend/plugins/dax_backend.py     @DongDongJu
+/docs/source/kv_cache/storage_backends/maru.rst        @DongDongJu
+/docs/source/kv_cache/storage_backends/dax.rst         @DongDongJu
+
+# Packaging
+pyproject.toml                         @sammshen @ApostaC @deng451e @hickeyma
+setup.py                               @sammshen @ApostaC @deng451e @hickeyma
diff --git a/.github/ISSUE_TEMPLATE/blank_issue.md b/.github/ISSUE_TEMPLATE/blank_issue.md
new file mode 100644
index 0000000..ec9dd7c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/blank_issue.md
@@ -0,0 +1,30 @@
+---
+name: Blank issue
+about: Create a new issue from scratch
+title: ''
+labels: ''
+assignees: ''
+---
+**Label**
+Please label your issue so that it can easily be easily categorized under [LMCache Onboarding](https://github.com/LMCache/LMCache/issues/1882)
+
+**Summary**
+A concise overview of the issue you want to raise.
+
+**Details**
+Provide all relevant details here — context, reasoning, and any background information.
+
+**Steps / Reproduction (if applicable)**
+If this relates to a reproducible issue or process, list the steps here:
+1. Step one
+2. Step two
+3. Step three
+
+**Expected Outcome / Goal**
+Describe the desired resolution or end state.
+
+**Actual Outcome (if applicable)**
+Describe the current behavior or state, if different from what’s expected.
+
+**Additional Context**
+Include any other context, references, or screenshots that would be useful.
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..1acfc34
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+**Label**
+Please label your issue with "bug" and any other relevant labels so that it can easily be easily categorized under [LMCache Onboarding](https://github.com/LMCache/LMCache/issues/1882)
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..d5c5ea0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+**Label**
+Please label your issue with "new feature" and any other relevant labels so that it can easily be easily categorized under [LMCache Onboarding](https://github.com/LMCache/LMCache/issues/1882)
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..2d1b52e
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,12 @@
+<!--  Thanks for your contribution to LMCache!  Here are some tips for you:
+1. Make sure to read the Contributing Guide before submitting your PR: https://github.com/LMCache/LMCache/blob/dev/CONTRIBUTING.md
+2. If this PR closes another issue, add 'Fixes #<issue number>' somewhere in the PR summary. GitHub will automatically close that issue when this PR gets merged. Alternatively, adding 'Refs #<issue number>' will not close the issue, but help provide the reviewer more context.-->
+
+**What this PR does / why we need it**:
+
+**Special notes for your reviewers**:
+
+**If applicable**:
+
+- [ ] this PR contains user facing changes - docs added
+- [ ] this PR contains unit tests
diff --git a/.github/actions/free-disk-space/action.yml b/.github/actions/free-disk-space/action.yml
new file mode 100644
index 0000000..d0783ca
--- /dev/null
+++ b/.github/actions/free-disk-space/action.yml
@@ -0,0 +1,29 @@
+name: 'Free Disk Space'
+description: 'Frees disk space on the runner safely'
+runs:
+  using: "composite"
+  steps:
+    - name: Print disk space before cleanup
+      run: df -h
+      shell: bash
+
+    - name: Free Disk Space Linux
+      if: runner.os == 'Linux'
+      run: |
+        # 1. Remove massive toolsets first (fastest gain)
+        sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /usr/local/share/powershell /usr/share/swift /usr/local/.ghcup /usr/lib/jvm /usr/local/lib/node_modules || true
+        
+        # 2. Clean Docker images
+        sudo docker image prune -af >/dev/null 2>&1 || true
+
+        # 3. Clean APT (Skip aptitude, use standard apt-get)
+        # We wrap this in a block to ensure the script continues even if apt is locked
+        sudo apt-get update >/dev/null 2>&1 || true
+        sudo apt-get purge -y mysql-client mysql-server google-cloud-sdk azure-cli >/dev/null 2>&1 || true
+        sudo apt-get autoremove -y >/dev/null 2>&1 || true
+        sudo apt-get clean >/dev/null 2>&1 || true
+      shell: bash
+
+    - name: Print disk space after cleanup
+      run: df -h
+      shell: bash
\ No newline at end of file
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..4f0877a
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels: ["dependencies"]
+    open-pull-requests-limit: 5
+    reviewers: ["ApostaC", "YaoJiayi", "hickeyma"]
+    allow:
+      - dependency-type: "all"
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-patch"]
+      - dependency-name: "torch"
+      - dependency-name: "torchvision"
+      - dependency-name: "xformers"
+    groups:
+      minor-update:
+        applies-to: version-updates
+        update-types: ["minor"]
diff --git a/.github/scripts/cpu_device_test.sh b/.github/scripts/cpu_device_test.sh
new file mode 100644
index 0000000..bdf3daf
--- /dev/null
+++ b/.github/scripts/cpu_device_test.sh
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# CPU device test: runs both server bench and vLLM e2e tests
+# in the same environment to avoid repeated vLLM installation.
+#
+# Usage: cpu_device_test.sh [mode]
+#   mode: server_bench, vllm_e2e, or all (default)
+#
+# Environment variables:
+#   LMCACHE_BENCH_TRANSFER_MODE  engine_driven|lmcache_driven
+#                                (default: engine_driven)
+#   LMCACHE_E2E_TRANSPORT_MODE   engine_driven|lmcache_driven|shm|pickle
+#                                (default: engine_driven)
+#   LMCACHE_E2E_DATA_MODE        shm|pickle (default: shm)
+#   LMCACHE_HTTP_PORT_BENCH      HTTP port for bench (default: 18080)
+#   LMCACHE_ZMQ_PORT_BENCH       ZMQ port for bench (default: 15555)
+#   LMCACHE_HTTP_PORT_E2E        HTTP port for e2e (default: 18081)
+#   LMCACHE_ZMQ_PORT_E2E         ZMQ port for e2e (default: 15557)
+#   VLLM_PORT_E2E                HTTP port for vLLM (default: 18000)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OS="$(uname -s)"
+TEST_MODE="${1:-all}"
+
+echo "==> CPU device test (OS: ${OS}, Mode: ${TEST_MODE})"
+echo "    Python: $(python3 --version 2>&1 || true)"
+
+# Configuration
+BENCH_TRANSFER_MODE="${LMCACHE_BENCH_TRANSFER_MODE:-engine_driven}"
+E2E_TRANSPORT_MODE="${LMCACHE_E2E_TRANSPORT_MODE:-engine_driven}"
+E2E_DATA_MODE="${LMCACHE_E2E_DATA_MODE:-shm}"
+HTTP_PORT_BENCH="${LMCACHE_HTTP_PORT_BENCH:-18080}"
+ZMQ_PORT_BENCH="${LMCACHE_ZMQ_PORT_BENCH:-15555}"
+HTTP_PORT_E2E="${LMCACHE_HTTP_PORT_E2E:-18081}"
+ZMQ_PORT_E2E="${LMCACHE_ZMQ_PORT_E2E:-15557}"
+VLLM_PORT_E2E="${VLLM_PORT_E2E:-18000}"
+
+# Validate modes
+case "${BENCH_TRANSFER_MODE}" in
+  lmcache_driven|engine_driven) ;;
+  *)
+    echo "!! Unknown LMCACHE_BENCH_TRANSFER_MODE='${BENCH_TRANSFER_MODE}'"
+    exit 1
+    ;;
+esac
+
+# Map user-facing LMCACHE_E2E_TRANSPORT_MODE to internal representation.
+# shm/pickle are aliases for lmcache_driven mode with sub-mode selection.
+case "${E2E_TRANSPORT_MODE}" in
+  lmcache_driven|engine_driven)
+    MAPPED_TRANSPORT_MODE="${E2E_TRANSPORT_MODE}"
+    MAPPED_DATA_MODE="${E2E_DATA_MODE}"
+    ;;
+  shm)
+    MAPPED_TRANSPORT_MODE="engine_driven"
+    MAPPED_DATA_MODE="shm"
+    ;;
+  pickle)
+    MAPPED_TRANSPORT_MODE="engine_driven"
+    MAPPED_DATA_MODE="pickle"
+    ;;
+  *)
+    echo "!! Unknown LMCACHE_E2E_TRANSPORT_MODE='${E2E_TRANSPORT_MODE}'"
+    echo "   Valid values: engine_driven, lmcache_driven, shm, pickle"
+    exit 1
+    ;;
+esac
+
+echo "    Bench transfer mode: ${BENCH_TRANSFER_MODE}"
+echo "    E2E transport mode: ${E2E_TRANSPORT_MODE}"
+echo "    Ports: bench=${HTTP_PORT_BENCH}/${ZMQ_PORT_BENCH}, e2e=${HTTP_PORT_E2E}/${ZMQ_PORT_E2E}/${VLLM_PORT_E2E}"
+
+# Reap any LMCache/vLLM children started by this run on exit so the
+# next workflow step does not collide on default ZMQ/HTTP ports.
+cleanup_processes_safe() {
+    local rc=$?
+    set +e
+    # Kill child processes started by this shell first (e.g. lmcache server
+    # backgrounded by the shared validation script).
+    pkill -P $$ 2>/dev/null || true
+    sleep 1
+    pkill -9 -P $$ 2>/dev/null || true
+    return $rc
+}
+trap cleanup_processes_safe EXIT
+
+# Function to run server bench test
+run_server_bench() {
+    echo ""
+    echo "==> Running CPU server bench test"
+    
+    # Set environment for bench test
+    export LMCACHE_BENCH_TRANSFER_MODE="${BENCH_TRANSFER_MODE}"
+    export LMCACHE_HTTP_PORT="${HTTP_PORT_BENCH}"
+    export LMCACHE_ZMQ_PORT="${ZMQ_PORT_BENCH}"
+    export LMCACHE_LOG_FILE="/tmp/cpu_device_bench_${BENCH_TRANSFER_MODE}_lmcache.log"
+    export BENCH_OUTPUT_LOG="/tmp/cpu_device_bench_${BENCH_TRANSFER_MODE}_output.log"
+    export LMCACHE_HEALTHCHECK_TIMEOUT="30"
+    export BENCH_NUM_REQUESTS="3"
+    export BENCH_NUM_TOKENS="512"
+    
+    # Run bench test
+    bash "${SCRIPT_DIR}/cpu_server_bench_test.sh"
+    
+    echo "==> CPU server bench test completed successfully"
+}
+
+# Function to run vLLM e2e test
+run_vllm_e2e() {
+    echo ""
+    echo "==> Running CPU vLLM e2e test"
+    
+    # Set environment for e2e test
+    export LMCACHE_TRANSPORT_MODE="${MAPPED_TRANSPORT_MODE}"
+    export LMCACHE_DATA_MODE="${MAPPED_DATA_MODE}"
+    export LMCACHE_HTTP_PORT="${HTTP_PORT_E2E}"
+    export LMCACHE_ZMQ_PORT="${ZMQ_PORT_E2E}"
+    export VLLM_PORT="${VLLM_PORT_E2E}"
+    export LMCACHE_LOG_FILE="/tmp/cpu_device_e2e_${E2E_TRANSPORT_MODE}_lmcache.log"
+    export VLLM_LOG_FILE="/tmp/cpu_device_e2e_${E2E_TRANSPORT_MODE}_vllm.log"
+    export LMCACHE_HEALTHCHECK_TIMEOUT="30"
+    export VLLM_READY_TIMEOUT="300"
+    
+    # Run e2e test
+    bash "${SCRIPT_DIR}/cpu_vllm_e2e_test.sh"
+    
+    echo "==> CPU vLLM e2e test completed successfully"
+}
+
+# Determine which tests to run
+case "${TEST_MODE}" in
+    "server_bench")
+        run_server_bench
+        ;;
+    "vllm_e2e")
+        run_vllm_e2e
+        ;;
+    "all")
+        run_server_bench
+        run_vllm_e2e
+        ;;
+    *)
+        echo "!! Unknown test mode: ${TEST_MODE}"
+        echo "    Supported modes: server_bench, vllm_e2e, all"
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "==> CPU device test passed for modes:"
+echo "    Test mode: ${TEST_MODE}"
+echo "    Server bench: ${BENCH_TRANSFER_MODE}"
+echo "    vLLM e2e: ${E2E_TRANSPORT_MODE}"
diff --git a/.github/scripts/cpu_server_bench_test.sh b/.github/scripts/cpu_server_bench_test.sh
new file mode 100644
index 0000000..89a8b74
--- /dev/null
+++ b/.github/scripts/cpu_server_bench_test.sh
@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# CPU server bench test: starts lmcache server, runs
+# ``lmcache bench server --mode cpu`` with the requested transfer mode,
+# then tears down.
+#
+# Transfer modes (LMCACHE_BENCH_TRANSFER_MODE):
+#   lmcache_driven - worker-side gather/scatter via POSIX SHM pool
+#   engine_driven  - server-side copy via POSIX SHM IPC (shm_open/mmap)
+#
+# Environment variables (all optional, defaults shown):
+#   LMCACHE_BENCH_TRANSFER_MODE  lmcache_driven|engine_driven
+#                                (default: engine_driven)
+#   LMCACHE_HTTP_PORT            HTTP port            (default: 18080)
+#   LMCACHE_ZMQ_PORT             ZMQ RPC port         (default: 15555)
+#   LMCACHE_LOG_FILE             server log path      (default: /tmp/...)
+#   LMCACHE_HEALTHCHECK_TIMEOUT  seconds              (default: 60)
+#   BENCH_NUM_REQUESTS           requests to run      (default: 3)
+#   BENCH_NUM_TOKENS             tokens per request   (default: 512)
+
+set -euo pipefail
+
+OS="$(uname -s)"
+echo "==> CPU server bench test (OS: ${OS})"
+echo "    Python: $(python3 --version 2>&1 || true)"
+
+TRANSFER_MODE="${LMCACHE_BENCH_TRANSFER_MODE:-engine_driven}"
+HTTP_PORT="${LMCACHE_HTTP_PORT:-18080}"
+ZMQ_PORT="${LMCACHE_ZMQ_PORT:-15555}"
+LOG_FILE="${LMCACHE_LOG_FILE:-/tmp/cpu_server_bench_lmcache.log}"
+HEALTHCHECK_TIMEOUT="${LMCACHE_HEALTHCHECK_TIMEOUT:-60}"
+BENCH_NUM_REQUESTS="${BENCH_NUM_REQUESTS:-3}"
+BENCH_NUM_TOKENS="${BENCH_NUM_TOKENS:-512}"
+
+case "${TRANSFER_MODE}" in
+  lmcache_driven|engine_driven) ;;
+  *)
+    echo "!! Unknown LMCACHE_BENCH_TRANSFER_MODE='${TRANSFER_MODE}'"
+    echo "   Valid values: lmcache_driven, engine_driven"
+    exit 1
+    ;;
+esac
+
+echo "    TRANSFER_MODE=${TRANSFER_MODE}"
+echo "    HTTP_PORT=${HTTP_PORT}  ZMQ_PORT=${ZMQ_PORT}"
+echo "    BENCH_NUM_REQUESTS=${BENCH_NUM_REQUESTS}"
+echo "    BENCH_NUM_TOKENS=${BENCH_NUM_TOKENS}"
+
+# ------------------------------------------------------------------ #
+# Start lmcache server
+# ------------------------------------------------------------------ #
+echo ""
+echo "==> Starting lmcache server (log: ${LOG_FILE})"
+rm -f "${LOG_FILE}"
+
+lmcache server \
+  --port "${ZMQ_PORT}" \
+  --http-port "${HTTP_PORT}" \
+  --l1-size-gb 1 \
+  --eviction-policy LRU \
+  >"${LOG_FILE}" 2>&1 &
+SERVER_PID=$!
+
+cleanup() {
+  echo "==> Cleanup: stopping lmcache server (pid=${SERVER_PID})"
+  if kill -0 "${SERVER_PID}" 2>/dev/null; then
+    kill "${SERVER_PID}" 2>/dev/null || true
+    for _ in $(seq 1 10); do
+      kill -0 "${SERVER_PID}" 2>/dev/null || break
+      sleep 1
+    done
+    kill -9 "${SERVER_PID}" 2>/dev/null || true
+  fi
+  echo "==> Last 50 lines of server log:"
+  tail -n 50 "${LOG_FILE}" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ------------------------------------------------------------------ #
+# Wait for healthcheck
+# ------------------------------------------------------------------ #
+echo "==> Waiting for healthcheck (timeout: ${HEALTHCHECK_TIMEOUT}s)"
+READY=0
+for i in $(seq 1 "${HEALTHCHECK_TIMEOUT}"); do
+  if ! kill -0 "${SERVER_PID}" 2>/dev/null; then
+    echo "!! lmcache server exited prematurely after ${i}s"
+    break
+  fi
+  if curl -fsS --max-time 2 \
+      "http://127.0.0.1:${HTTP_PORT}/healthcheck" >/dev/null 2>&1; then
+    READY=1
+    echo "    Server healthy after ${i}s"
+    break
+  fi
+  sleep 1
+done
+
+if [ "${READY}" != "1" ]; then
+  echo "!! lmcache server did not become healthy within ${HEALTHCHECK_TIMEOUT}s"
+  exit 1
+fi
+
+# ------------------------------------------------------------------ #
+# Run bench and validate results
+# ------------------------------------------------------------------ #
+echo ""
+echo "==> Running: lmcache bench server" \
+  "--mode cpu --transfer-mode ${TRANSFER_MODE}" \
+  "--num-tokens ${BENCH_NUM_TOKENS}" \
+  "--end ${BENCH_NUM_REQUESTS}"
+
+BENCH_LOG="${BENCH_OUTPUT_LOG:-/tmp/cpu_server_bench_output.log}"
+lmcache bench server \
+  --rpc-url "tcp://127.0.0.1:${ZMQ_PORT}" \
+  --url "http://127.0.0.1:${HTTP_PORT}" \
+  --mode cpu \
+  --transfer-mode "${TRANSFER_MODE}" \
+  --num-tokens "${BENCH_NUM_TOKENS}" \
+  --end "${BENCH_NUM_REQUESTS}" \
+  2>&1 | tee "${BENCH_LOG}"
+
+echo ""
+echo "==> Validating bench results"
+
+if grep -q "CHECKSUM MISMATCH" "${BENCH_LOG}"; then
+  echo "!! CHECKSUM MISMATCH detected — store/retrieve data corruption"
+  exit 1
+fi
+
+MATCH_COUNT="$(grep -c "CHECKSUM MATCH OK" "${BENCH_LOG}" || true)"
+if [ "${MATCH_COUNT}" -lt "${BENCH_NUM_REQUESTS}" ]; then
+  echo "!! CHECKSUM MATCH count (${MATCH_COUNT}) < expected (${BENCH_NUM_REQUESTS})"
+  exit 1
+fi
+echo "    CHECKSUM MATCH: ${MATCH_COUNT}/${BENCH_NUM_REQUESTS} request(s) verified OK"
+
+echo ""
+echo "==> CPU server bench (${TRANSFER_MODE}) passed."
diff --git a/.github/scripts/cpu_vllm_e2e_test.sh b/.github/scripts/cpu_vllm_e2e_test.sh
new file mode 100644
index 0000000..66dcbfd
--- /dev/null
+++ b/.github/scripts/cpu_vllm_e2e_test.sh
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Generic CPU vLLM e2e wrapper for both macOS and Ubuntu.
+# Assumes vLLM CPU build and facebook/opt-125m are already installed/
+# downloaded by the CI workflow steps before this script is invoked.
+#
+# Delegates all logic to the shared run-cpu-e2e-validation.sh with:
+#   SKIP_INSTALL=1              (install done by CI workflow steps)
+#
+# Transport mode is selected via LMCACHE_TRANSPORT_MODE:
+#   engine_driven -> LMCACHE_MP_TRANSFER_MODE=engine_driven (server-side copy)
+#   lmcache_driven -> LMCACHE_DATA_MODE selects shm (default) or pickle
+#
+# Environment variables (all optional, defaults shown):
+#   LMCACHE_TRANSPORT_MODE   Transport: engine_driven|lmcache_driven
+#                             (default: engine_driven)
+#   LMCACHE_DATA_MODE        Data transfer mode: shm|pickle (default: shm)
+#   LMCACHE_HTTP_PORT        HTTP port for LMCache server  (default: 8080)
+#   VLLM_PORT                HTTP port for vLLM server     (default: 8000)
+#   LMCACHE_L1_SIZE_GB       LMCache L1 cache size in GB   (default: 2)
+#   VLLM_READY_TIMEOUT       Seconds to wait for vLLM      (default: 300)
+#   LMCACHE_HEALTHCHECK_TIMEOUT  Seconds to wait for LMCache (default: 60)
+
+set -euo pipefail
+
+OS="$(uname -s)"
+echo "==> CPU vLLM e2e test (OS: ${OS})"
+echo "    Python: $(python3 --version 2>&1 || true)"
+echo "    uname:  $(uname -a)"
+if [ "${OS}" = "Darwin" ]; then
+    sw_vers 2>/dev/null || true
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+SHARED_SCRIPT="${REPO_ROOT}/.github/scripts/run-cpu-e2e-validation.sh"
+
+if [ ! -f "${SHARED_SCRIPT}" ]; then
+    echo "!! Shared script not found: ${SHARED_SCRIPT}"
+    exit 1
+fi
+
+LMCACHE_TRANSPORT_MODE="${LMCACHE_TRANSPORT_MODE:-engine_driven}"
+
+# When LMCACHE_TRANSPORT_MODE=engine_driven, LMCACHE_DATA_MODE selects the
+# specific data transfer mechanism: shm (default) or pickle.
+LMCACHE_DATA_MODE="${LMCACHE_DATA_MODE:-shm}"
+
+# Map LMCACHE_TRANSPORT_MODE to the vars expected by the shared script.
+case "${LMCACHE_TRANSPORT_MODE}" in
+  engine_driven)
+    case "${LMCACHE_DATA_MODE}" in
+      shm)
+        export LMCACHE_SHM_NAME="__default__"
+        ;;
+      pickle)
+        export LMCACHE_SHM_NAME=""
+        ;;
+    esac
+    export LMCACHE_MP_TRANSFER_MODE="engine_driven"
+    ;;
+  lmcache_driven)
+    export LMCACHE_MP_TRANSFER_MODE="lmcache_driven"
+    ;;
+  *)
+    echo "!! Unknown LMCACHE_TRANSPORT_MODE='${LMCACHE_TRANSPORT_MODE}'"
+    echo "   Valid values: engine_driven, lmcache_driven"
+    exit 1
+    ;;
+esac
+
+export SKIP_INSTALL="${SKIP_INSTALL:-1}"
+export LMCACHE_HEALTHCHECK_TIMEOUT="${LMCACHE_HEALTHCHECK_TIMEOUT:-60}"
+export VLLM_READY_TIMEOUT="${VLLM_READY_TIMEOUT:-300}"
+export LMCACHE_LOG_FILE="${LMCACHE_LOG_FILE:-/tmp/cpu_e2e_lmcache.log}"
+export VLLM_LOG_FILE="${VLLM_LOG_FILE:-/tmp/cpu_e2e_vllm.log}"
+
+echo "    LMCACHE_TRANSPORT_MODE=${LMCACHE_TRANSPORT_MODE}"
+echo "    LMCACHE_DATA_MODE=${LMCACHE_DATA_MODE}"
+echo "    SKIP_INSTALL=${SKIP_INSTALL}"
+echo "    Delegating to: ${SHARED_SCRIPT}"
+
+exec bash "${SHARED_SCRIPT}"
diff --git a/.github/scripts/download_model.sh b/.github/scripts/download_model.sh
new file mode 100644
index 0000000..edd96d5
--- /dev/null
+++ b/.github/scripts/download_model.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Download (or just verify the local cache of) a HuggingFace model
+# repo, with bounded retry + exponential backoff so flaky HF mirrors
+# don't fail the whole CI run.
+#
+# Usage:
+#   download_model.sh <repo_id> [<repo_id> ...]
+#   MODEL_ID=facebook/opt-125m download_model.sh
+#
+# Environment:
+#   MODEL_ID                  fallback when no positional args given
+#   HF_TOKEN                  optional HuggingFace token for authenticated
+#                             requests (avoids anonymous rate limits)
+#   HF_DOWNLOAD_MAX_RETRIES   default 5
+#   HF_DOWNLOAD_RETRY_DELAY   default 30 (seconds, doubled per retry)
+#   HF_DOWNLOAD_FAIL_ON_ERROR default 0  (1 -> exit non-zero on failure)
+
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  if [ -z "${MODEL_ID:-}" ]; then
+    echo "!! download_model.sh: no model id provided"
+    echo "   pass repo ids as args or set MODEL_ID=..."
+    exit 2
+  fi
+  set -- "${MODEL_ID}"
+fi
+
+MAX_RETRIES="${HF_DOWNLOAD_MAX_RETRIES:-5}"
+RETRY_DELAY="${HF_DOWNLOAD_RETRY_DELAY:-30}"
+FAIL_ON_ERROR="${HF_DOWNLOAD_FAIL_ON_ERROR:-0}"
+
+MAX_RETRIES="${MAX_RETRIES}" RETRY_DELAY="${RETRY_DELAY}" \
+FAIL_ON_ERROR="${FAIL_ON_ERROR}" HF_TOKEN="${HF_TOKEN:-}" \
+  python3 - "$@" <<'PY'
+import os
+import random
+import sys
+import time
+
+from huggingface_hub import snapshot_download
+
+max_retries = int(os.environ["MAX_RETRIES"])
+base_delay = int(os.environ["RETRY_DELAY"])
+fail_on_error = os.environ["FAIL_ON_ERROR"] == "1"
+hf_token = os.environ.get("HF_TOKEN") or None
+
+repos = sys.argv[1:]
+failures = []
+
+for repo in repos:
+    # Try local cache first to avoid unnecessary HF API calls
+    # (which can 429 on busy CI runners even when the model is cached).
+    try:
+        snapshot_download(repo, local_files_only=True, token=hf_token)
+        print(f"CACHED: {repo} (local, no network)")
+        continue
+    except Exception:
+        pass
+
+    delay = base_delay
+    ok = False
+    for attempt in range(max_retries):
+        try:
+            print(f"Attempt {attempt + 1}/{max_retries}: {repo}")
+            snapshot_download(repo, token=hf_token)
+            print(f"OK: {repo}")
+            ok = True
+            break
+        except Exception as exc:
+            print(f"Attempt {attempt + 1} failed for {repo}: {exc}")
+            if attempt < max_retries - 1:
+                # Add ±25% jitter to avoid thundering herd
+                jitter = delay * (0.75 + random.random() * 0.5)
+                print(
+                    "Waiting %.1fs before retry..." % jitter)
+                time.sleep(jitter)
+                delay *= 2
+    if not ok:
+        failures.append(repo)
+
+if failures:
+    print("All retry attempts failed for: %s" % ", ".join(failures))
+    sys.exit(1 if fail_on_error else 0)
+PY
diff --git a/.github/scripts/download_opt125m_github.sh b/.github/scripts/download_opt125m_github.sh
new file mode 100644
index 0000000..3091e18
--- /dev/null
+++ b/.github/scripts/download_opt125m_github.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Download facebook/opt-125m from the LMCache/opt-125m GitHub release
+# and place it into the HuggingFace hub cache structure so vLLM can
+# find it via ``facebook/opt-125m`` without any network call to HF.
+#
+# Environment:
+#   OPT125M_GH_RELEASE  release tag (default: v1.0)
+#   OPT125M_SNAPSHOT    HF snapshot hash (default: 27dcfa...)
+
+set -euo pipefail
+
+GH_RELEASE="${OPT125M_GH_RELEASE:-v1.0}"
+SNAPSHOT="${OPT125M_SNAPSHOT:-27dcfa74d334bc871f3234de431e71c6eeba5dd6}"
+
+HF_CACHE="${HF_HOME:-$HOME/.cache/huggingface}/hub"
+MODEL_DIR="${HF_CACHE}/models--facebook--opt-125m"
+SNAPSHOT_DIR="${MODEL_DIR}/snapshots/${SNAPSHOT}"
+
+if [ -f "${SNAPSHOT_DIR}/pytorch_model.bin" ]; then
+    echo "opt-125m already cached in ${SNAPSHOT_DIR}, skipping download"
+    exit 0
+fi
+
+echo "Downloading opt-125m from GitHub release ${GH_RELEASE}..."
+mkdir -p "${SNAPSHOT_DIR}"
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "${TMP_DIR}"' EXIT
+
+TARBALL="${TMP_DIR}/opt-125m.tar.gz"
+DOWNLOAD_URL="https://github.com/LMCache/opt-125m/releases/download/${GH_RELEASE}/opt-125m.tar.gz"
+
+for i in $(seq 1 5); do
+    if curl -fsSL --retry 3 -o "${TARBALL}" "${DOWNLOAD_URL}"; then
+        break
+    fi
+    if [ "${i}" -eq 5 ]; then
+        echo "!! Failed to download after 5 attempts: ${DOWNLOAD_URL}"
+        exit 1
+    fi
+    sleep $((10 * i))
+done
+
+# Extract directly – the tarball contains opt-125m/ at top level.
+EXTRACT_DIR="${TMP_DIR}/extract"
+mkdir -p "${EXTRACT_DIR}"
+tar -xzf "${TARBALL}" -C "${EXTRACT_DIR}"
+mv "${EXTRACT_DIR}"/opt-125m/* "${SNAPSHOT_DIR}/"
+
+# Create the refs/main pointer so snapshot_download(local_files_only=True)
+# can resolve the snapshot hash.
+mkdir -p "${MODEL_DIR}/refs"
+echo "${SNAPSHOT}" > "${MODEL_DIR}/refs/main"
+
+echo "opt-125m cached at ${SNAPSHOT_DIR}"
+ls -lah "${SNAPSHOT_DIR}/"
\ No newline at end of file
diff --git a/.github/scripts/install_lmcache_cpu.sh b/.github/scripts/install_lmcache_cpu.sh
new file mode 100644
index 0000000..bafa772
--- /dev/null
+++ b/.github/scripts/install_lmcache_cpu.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Install lmcache in editable, CPU-only mode (NO_GPU_EXT=1).
+# Assumes vLLM (and therefore torch) was already installed by
+# install_vllm_cpu.sh, so we use --no-deps to keep that pinned torch
+# in place.
+#
+# Usage:
+#   install_lmcache_cpu.sh           # plain pip
+#   PIP_BIN="uv pip" install_lmcache_cpu.sh
+
+set -euo pipefail
+
+PIP_BIN="${PIP_BIN:-pip}"
+
+export NO_GPU_EXT=1
+export SETUPTOOLS_SCM_PRETEND_VERSION="${SETUPTOOLS_SCM_PRETEND_VERSION:-0.0.0.dev0}"
+
+${PIP_BIN} install --upgrade pip
+${PIP_BIN} install -r requirements/build.txt
+${PIP_BIN} install -r requirements/common.txt
+${PIP_BIN} install -r requirements/cli.txt
+${PIP_BIN} install -e . --no-deps --no-build-isolation
+
+python -c "import lmcache, vllm; \
+print('lmcache:', lmcache.__version__, 'vllm:', vllm.__version__)"
diff --git a/.github/scripts/install_vllm_cpu.sh b/.github/scripts/install_vllm_cpu.sh
new file mode 100644
index 0000000..fd44a36
--- /dev/null
+++ b/.github/scripts/install_vllm_cpu.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Install the prebuilt CPU-only vLLM wheel (`vllm-cpu-nightly`) plus a
+# `vllm-<ver>+cpu.dist-info` alias.
+#
+# Why the alias: the wheel installs the `vllm/` package but registers
+# its dist metadata under `vllm-cpu-nightly`. vLLM's CLI / internal
+# callers do `importlib.metadata.version("vllm")` (distribution name,
+# not import name); without the alias that raises PackageNotFoundError
+# and `vllm serve` won't start. The `+cpu` local label is also needed
+# so `cpu_platform_plugin()` activates the CPU platform (it greps the
+# dist metadata for the substring "cpu"); our build strips `+cpu`
+# before PyPI upload because PyPI rejects local versions.
+#
+# Usage:
+#   install_vllm_cpu.sh           # use plain `pip`
+#   PIP_BIN="uv pip" install_vllm_cpu.sh
+#                                 # use `uv pip` and pass extra flags
+#                                 # via PIP_INSTALL_EXTRA_ARGS
+#
+# Idempotent: re-running just rewrites the alias.
+
+set -euo pipefail
+
+PIP_BIN="${PIP_BIN:-pip}"
+PIP_INSTALL_EXTRA_ARGS="${PIP_INSTALL_EXTRA_ARGS:-}"
+
+# `--extra-index-url` is required because the wheel pins torch==2.11.0
+# which only lives on the pytorch CPU index. Harmless on macOS.
+${PIP_BIN} install "numpy<2"
+# shellcheck disable=SC2086
+${PIP_BIN} install vllm-cpu-nightly \
+  --extra-index-url https://download.pytorch.org/whl/cpu \
+  ${PIP_INSTALL_EXTRA_ARGS}
+
+python - <<'PY'
+import importlib.metadata as md
+import pathlib
+import shutil
+
+dist = md.distribution("vllm-cpu-nightly")
+ver = dist.version
+fake_ver = f"{ver}+cpu"
+site_root = pathlib.Path(dist.locate_file(""))
+info_name = next(
+    p.parts[0] for p in (dist.files or [])
+    if p.parts and p.parts[0].endswith(".dist-info")
+)
+src = site_root / info_name
+dst = src.with_name(f"vllm-{fake_ver}.dist-info")
+if dst.exists():
+    shutil.rmtree(dst)
+shutil.copytree(src, dst)
+meta = dst / "METADATA"
+txt = meta.read_text()
+txt = txt.replace("Name: vllm-cpu-nightly", "Name: vllm", 1)
+txt = txt.replace(f"Version: {ver}", f"Version: {fake_ver}", 1)
+meta.write_text(txt)
+print(f"Aliased {src.name} -> {dst.name}")
+print("vllm version (via importlib.metadata):", md.version("vllm"))
+PY
+
+python -c "import vllm, torch; \
+print('vllm:', vllm.__version__, 'torch:', torch.__version__, \
+      'cuda:', torch.cuda.is_available())"
diff --git a/.github/scripts/run-cpu-e2e-validation.sh b/.github/scripts/run-cpu-e2e-validation.sh
new file mode 100755
index 0000000..94c64b6
--- /dev/null
+++ b/.github/scripts/run-cpu-e2e-validation.sh
@@ -0,0 +1,648 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "Build ID: ${BUILDKITE_BUILD_ID:-local}"
+echo "Python: $(python3 --version 2>&1 || true)"
+if command -v uv >/dev/null 2>&1; then
+  echo "uv: $(uv --version 2>&1 || true)"
+else
+  echo "uv: not installed"
+fi
+
+BUILD_ID="${BUILDKITE_BUILD_ID:-local_$$}"
+VENV_DIR=".venv-${BUILD_ID}"
+SHARED_SCRIPTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LMCACHE_LOG="${LMCACHE_LOG_FILE:-/tmp/build_${BUILD_ID}_lmcache_cpu_validation.log}"
+VLLM_LOG="${VLLM_LOG_FILE:-/tmp/build_${BUILD_ID}_vllm_cpu_validation.log}"
+LMCACHE_PID=""
+VLLM_PID=""
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-8080}"
+LMCACHE_ZMQ_PORT="${LMCACHE_ZMQ_PORT:-5555}"
+VLLM_PORT="${VLLM_PORT:-8000}"
+LMCACHE_L1_SIZE_GB="${LMCACHE_L1_SIZE_GB:-1}"
+LMCACHE_EVICTION_POLICY="${LMCACHE_EVICTION_POLICY:-LRU}"
+LMCACHE_CHUNK_SIZE="${LMCACHE_CHUNK_SIZE:-128}"
+VLLM_GPU_MEMORY_UTILIZATION="${VLLM_GPU_MEMORY_UTILIZATION:-0.1}"
+# CPU-only KV cache pool size in GiB. vLLM defaults to 4 GiB when unset;
+# 1 GiB is plenty for opt-125m e2e validation.
+VLLM_CPU_KVCACHE_SPACE="${VLLM_CPU_KVCACHE_SPACE:-1}"
+# Cap context length and concurrent sequences to shrink scheduler buffers.
+VLLM_MAX_MODEL_LEN="${VLLM_MAX_MODEL_LEN:-2048}"
+VLLM_MAX_NUM_SEQS="${VLLM_MAX_NUM_SEQS:-4}"
+LMCACHE_HEALTHCHECK_TIMEOUT="${LMCACHE_HEALTHCHECK_TIMEOUT:-30}"
+VLLM_READY_TIMEOUT="${VLLM_READY_TIMEOUT:-120}"
+# Transport mode selection:
+#   LMCACHE_MP_TRANSFER_MODE=engine_driven  -> engine-driven data path,
+#       sub-selected by LMCACHE_SHM_NAME:
+#       LMCACHE_SHM_NAME=""              -> pickle transport
+#       LMCACHE_SHM_NAME=__default__     -> shm transport (default)
+#   LMCACHE_MP_TRANSFER_MODE=lmcache_driven -> lmcache-driven IPC handle path
+LMCACHE_SHM_NAME="${LMCACHE_SHM_NAME-__default__}"
+LMCACHE_MP_TRANSFER_MODE="${LMCACHE_MP_TRANSFER_MODE:-engine_driven}"
+# Set SKIP_INSTALL=1 to skip Phase 1 (install) — useful when the caller
+# has already installed everything (e.g. macOS CI workflow steps).
+SKIP_INSTALL="${SKIP_INSTALL:-0}"
+
+# Directory to collect artifacts before workspace is deleted
+ARTIFACT_DIR="/tmp/build_${BUILD_ID}_artifacts"
+mkdir -p "${ARTIFACT_DIR}"
+
+upload_artifacts() {
+  # Copy logs to artifact dir (which survives workspace deletion)
+  cp -f "${LMCACHE_LOG}" "${ARTIFACT_DIR}/lmcache_cpu_validation.log" 2>/dev/null || true
+  cp -f "${VLLM_LOG}" "${ARTIFACT_DIR}/vllm_cpu_validation.log" 2>/dev/null || true
+
+  if [ -n "${BUILDKITE_BUILD_ID:-}" ] && command -v buildkite-agent >/dev/null 2>&1; then
+    buildkite-agent artifact upload "${ARTIFACT_DIR}/*.log" || true
+  fi
+}
+
+cleanup_workspace() {
+  if [ -n "${BUILDKITE_BUILD_ID:-}" ]; then
+    export TARGET="$PWD"
+    case "$TARGET" in
+      ""|"/"|"/usr"|"/var"|"/etc"|"/bin"|"/sbin"|"/opt"|"/home"|"/tmp")
+        echo "❌ Refusing to delete unsafe workspace path: ${TARGET:-<empty>}"
+        return 1
+        ;;
+    esac
+    if [ "$TARGET" = "$HOME" ]; then
+      echo "❌ Refusing to delete unsafe workspace path: ${TARGET:-<empty>}"
+      return 1
+    fi
+    if [ ! -d "$TARGET/.git" ] || [ ! -f "$TARGET/pyproject.toml" ]; then
+      echo "❌ Refusing to delete unexpected workspace path: $TARGET"
+      return 1
+    fi
+    echo "Deleting current workspace $TARGET"
+    cd /
+    if command -v sudo >/dev/null 2>&1; then
+      sudo rm -rf "$TARGET"
+    else
+      rm -rf "$TARGET"
+    fi
+  fi
+}
+
+print_failure_logs() {
+  echo "=== LMCache Server Log (${LMCACHE_LOG}) ==="
+  if [ -f "${LMCACHE_LOG}" ]; then
+    tail -n 200 "${LMCACHE_LOG}" || true
+  else
+    echo "Log not found"
+  fi
+  echo "=== vLLM Log (${VLLM_LOG}) ==="
+  if [ -f "${VLLM_LOG}" ]; then
+    tail -n 200 "${VLLM_LOG}" || true
+  else
+    echo "Log not found"
+  fi
+}
+
+cleanup_processes() {
+  set +e
+  if [ -n "${VLLM_PID}" ] && kill -0 "${VLLM_PID}" 2>/dev/null; then
+    echo "Stopping vLLM (PID=${VLLM_PID})"
+    kill "${VLLM_PID}" 2>/dev/null || true
+    wait "${VLLM_PID}" 2>/dev/null || true
+  fi
+  if [ -n "${LMCACHE_PID}" ] && kill -0 "${LMCACHE_PID}" 2>/dev/null; then
+    echo "Stopping LMCache server (PID=${LMCACHE_PID})"
+    kill "${LMCACHE_PID}" 2>/dev/null || true
+    wait "${LMCACHE_PID}" 2>/dev/null || true
+  fi
+  set -e
+}
+
+wait_for_endpoint_contains() {
+  local url="$1"
+  local timeout="$2"
+  local expected="$3"
+  local label="$4"
+  local response
+
+  for _ in $(seq 1 "${timeout}"); do
+    if response="$(curl -fsS "${url}" 2>/dev/null)"; then
+      if [ -z "${expected}" ] || echo "${response}" | grep -q "${expected}"; then
+        return 0
+      fi
+    fi
+    sleep 1
+  done
+
+  echo "❌ ${label} did not become ready within ${timeout}s"
+  return 1
+}
+
+# Scrape a Prometheus counter value from LMCache /metrics endpoint
+scrape_metric() {
+  local metric_name="$1"
+  python3 - <<EOF
+import sys, urllib.request
+url = "http://localhost:${LMCACHE_HTTP_PORT}/metrics"
+try:
+    body = urllib.request.urlopen(url, timeout=10).read().decode()
+except Exception as e:
+    print(f"ERROR fetching {url}: {e}", file=sys.stderr)
+    print("0")
+    sys.exit(0)
+total = 0.0
+for line in body.splitlines():
+    if line.startswith("#"):
+        continue
+    if not line.startswith("${metric_name}"):
+        continue
+    parts = line.rsplit(" ", 1)
+    if len(parts) != 2:
+        continue
+    try:
+        total += float(parts[1])
+    except ValueError:
+        continue
+print(int(total))
+EOF
+}
+
+# Poll a Prometheus counter until its value differs from `baseline`,
+# or until `timeout` seconds elapse. Returns 0 on change, 1 on timeout
+# (callers typically `|| true` it because not every probe expects a
+# change to actually happen).
+wait_for_metric_change() {
+  local metric_name="$1"
+  local baseline="$2"
+  local timeout="${3:-10}"
+  local current
+  for _ in $(seq 1 "${timeout}"); do
+    current="$(scrape_metric "${metric_name}")"
+    if [ "${current}" != "${baseline}" ]; then
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+# Send a completion request and print the text output
+send_completion() {
+  local prompt_file="$1"
+  local max_tokens="${2:-50}"
+  local body_file
+  body_file="$(mktemp)"
+  # Build the JSON body in a separate process to avoid nested-quote
+  # quoting nightmares with -d "$(python3 -c "...")". Pass the prompt
+  # file path and max_tokens via argv so the python snippet itself
+  # does not need any shell interpolation inside its string body.
+  PROMPT_FILE="${prompt_file}" MAX_TOKENS="${max_tokens}" \
+    python3 - >"${body_file}" <<'PYEOF'
+import json
+import os
+
+prompt = open(os.environ['PROMPT_FILE']).read()
+print(json.dumps({
+    'model': 'facebook/opt-125m',
+    'prompt': prompt,
+    'max_tokens': int(os.environ['MAX_TOKENS']),
+    'temperature': 0,
+}))
+PYEOF
+  local response
+  response="$(curl -fsS "http://localhost:${VLLM_PORT}/v1/completions" \
+    -H "Content-Type: application/json" \
+    --data-binary "@${body_file}")"
+  rm -f "${body_file}"
+  echo "${response}" | python3 -c "import json,sys; print(json.load(sys.stdin)['choices'][0]['text'])"
+}
+
+start_vllm() {
+  echo "Starting vLLM server..."
+  # Export so multiproc_executor worker children inherit these. Without
+  # VLLM_CPU_KVCACHE_SPACE, CPU backend falls back to
+  # `total_memory * gpu_memory_utilization`, which can request 100s of GiB
+  # on big hosts and OOM (see vllm/v1/worker/cpu_worker.py:determine_available_memory).
+  # VLLM_DEVICE is the modern env var (vLLM 0.8+); VLLM_TARGET_DEVICE is
+  # kept for backwards-compatibility with older vLLM CPU wheels.
+  export VLLM_DEVICE=cpu
+  export VLLM_TARGET_DEVICE=cpu
+  export VLLM_CPU_KVCACHE_SPACE="${VLLM_CPU_KVCACHE_SPACE}"
+  export LMCACHE_MP_TRANSFER_MODE="${LMCACHE_MP_TRANSFER_MODE}"
+  # Pin gloo / vLLM rendezvous to loopback. Otherwise vLLM's
+  # network_utils.get_ip() picks a LAN address (e.g. 192.168.x.x on the
+  # macOS GHA runner) and gloo's init_process_group sits there for ~16
+  # minutes doing slow socket bind/connect retries before the engine
+  # ever loads weights.
+  export VLLM_HOST_IP="${VLLM_HOST_IP:-127.0.0.1}"
+  if [ -z "${GLOO_SOCKET_IFNAME:-}" ]; then
+    case "$(uname -s)" in
+      Darwin) export GLOO_SOCKET_IFNAME=lo0 ;;
+      Linux)  export GLOO_SOCKET_IFNAME=lo ;;
+    esac
+  fi
+  local kv_cache_bytes
+  kv_cache_bytes="$(python3 -c "print(int(${VLLM_CPU_KVCACHE_SPACE} * 1024 * 1024 * 1024))")"
+  # Tell LMCacheMPConnector where the lmcache server actually listens.
+  # Without this it falls back to tcp://localhost:5555 and dies with
+  # "Cannot reach the LMCache MP server" whenever we run multiple e2e
+  # steps in parallel/sequence on different ZMQ ports.
+  local kv_transfer_config
+  kv_transfer_config="$(python3 -c "
+import json
+print(json.dumps({
+    'kv_connector': 'LMCacheMPConnector',
+    'kv_role': 'kv_both',
+    'kv_connector_module_path': 'lmcache.integration.vllm.lmcache_mp_connector',
+    'kv_connector_extra_config': {
+        'lmcache.mp.host': 'tcp://localhost',
+        'lmcache.mp.port': int('${LMCACHE_ZMQ_PORT}'),
+    },
+}))")"
+  vllm serve facebook/opt-125m \
+    --port "${VLLM_PORT}" \
+    --dtype bfloat16 \
+    --disable-hybrid-kv-cache-manager \
+    --no-enable-prefix-caching \
+    --gpu-memory-utilization "${VLLM_GPU_MEMORY_UTILIZATION}" \
+    --kv-cache-memory-bytes "${kv_cache_bytes}" \
+    --max-model-len "${VLLM_MAX_MODEL_LEN}" \
+    --max-num-seqs "${VLLM_MAX_NUM_SEQS}" \
+    --kv-transfer-config "${kv_transfer_config}" \
+    --enforce-eager \
+    >"${VLLM_LOG}" 2>&1 &
+  VLLM_PID=$!
+  echo "vLLM server started (PID=${VLLM_PID})"
+  sleep 1
+  if ! kill -0 "${VLLM_PID}" 2>/dev/null; then
+    echo "❌ vLLM server exited immediately after startup. See ${VLLM_LOG} for details"
+    return 1
+  fi
+  echo "Waiting for vLLM readiness at http://localhost:${VLLM_PORT}/v1/models (timeout: ${VLLM_READY_TIMEOUT}s)"
+  if ! wait_for_endpoint_contains "http://localhost:${VLLM_PORT}/v1/models" "${VLLM_READY_TIMEOUT}" "facebook/opt-125m" "vLLM server"; then
+    return 1
+  fi
+  echo "✅ vLLM server is ready"
+}
+
+stop_vllm() {
+  if [ -n "${VLLM_PID}" ] && kill -0 "${VLLM_PID}" 2>/dev/null; then
+    echo "Stopping vLLM (PID=${VLLM_PID})"
+    kill "${VLLM_PID}" 2>/dev/null || true
+    wait "${VLLM_PID}" 2>/dev/null || true
+    VLLM_PID=""
+  fi
+}
+
+on_error() {
+  local exit_code=$?
+  trap - ERR
+  echo "❌ CPU install validation failed (exit code: ${exit_code})"
+  set +e
+  print_failure_logs
+  cleanup_processes
+  upload_artifacts
+  cleanup_workspace || echo "❌ Workspace cleanup failed"
+  set -e
+  exit "$exit_code"
+}
+
+trap on_error ERR
+
+if [ "${SKIP_INSTALL}" = "1" ]; then
+  echo "=== CPU Install Validation (Phase 1) — SKIPPED (SKIP_INSTALL=1) ==="
+else
+  echo "=== CPU Install Validation (Phase 1) ==="
+  echo "Creating virtual environment with uv at ${VENV_DIR}"
+  uv venv --python 3.12 "${VENV_DIR}"
+  # shellcheck disable=SC1091
+  source "${VENV_DIR}/bin/activate"
+
+  uv pip install --upgrade pip setuptools wheel
+
+  # `--index-strategy unsafe-best-match` is required because uv's
+  # default `first-index` strategy locks each package to the first
+  # index that lists it; the pytorch CPU index ships an older mirror
+  # of `setuptools` that would block the version vllm-cpu-nightly
+  # pins.
+  uv pip uninstall -y vllm vllm-cpu-nightly 2>/dev/null || true
+  PIP_BIN="uv pip" \
+  PIP_INSTALL_EXTRA_ARGS="--index-strategy unsafe-best-match" \
+    bash "${SHARED_SCRIPTS_DIR}/install_vllm_cpu.sh"
+
+  PIP_BIN="uv pip" \
+    bash "${SHARED_SCRIPTS_DIR}/install_lmcache_cpu.sh"
+
+  echo "Freezing installed package versions"
+  uv pip freeze
+
+  echo "✅ CPU install validation passed"
+fi
+
+echo "=== CPU E2E Validation (Phase 2) ==="
+
+if [ "${SKIP_INSTALL}" = "1" ]; then
+  echo "[Phase 2 / Step 1] numpy<2 install — SKIPPED (SKIP_INSTALL=1)"
+else
+  echo "[Phase 2 / Step 1] Installing numpy<2 for scipy/vLLM compatibility"
+  uv pip install "numpy<2"
+  echo "✅ numpy<2 installed"
+fi
+
+echo "[Phase 2 / Step 2] Downloading facebook/opt-125m model (GitHub release)"
+bash "${SHARED_SCRIPTS_DIR}/download_opt125m_github.sh"
+echo "✅ Model download/check complete"
+
+echo "[Phase 2 / Step 3] Starting LMCache server"
+echo "LMCache log: ${LMCACHE_LOG}"
+# Build lmcache server args
+LMCACHE_ARGS=(
+  --port "${LMCACHE_ZMQ_PORT}"
+  --http-port "${LMCACHE_HTTP_PORT}"
+  --l1-size-gb "${LMCACHE_L1_SIZE_GB}"
+  --eviction-policy "${LMCACHE_EVICTION_POLICY}"
+  --chunk-size "${LMCACHE_CHUNK_SIZE}"
+)
+# `engine_driven` / `lmcache_driven` resolve to different worker-side
+# TransferContexts:
+#   engine_driven -> EngineDrivenTransferContext (worker gathers/scatters data)
+#     sub-mode: SHM (--shm-name __default__) or pickle (--shm-name "")
+#   lmcache_driven -> LMCacheDrivenTransferContext (server-side IPC handle)
+# Step 5.5 verifies which one the worker actually entered.
+if [ "${LMCACHE_MP_TRANSFER_MODE}" = "engine_driven" ]; then
+  if [ "${LMCACHE_SHM_NAME}" = "__default__" ]; then
+    echo "Transport mode: engine-driven/shm (shared memory)"
+    EXPECTED_TRANSPORT="shm"
+  else
+    echo "Transport mode: engine-driven/pickle (--shm-name '${LMCACHE_SHM_NAME}')"
+    LMCACHE_ARGS+=(--shm-name "${LMCACHE_SHM_NAME}")
+    EXPECTED_TRANSPORT="pickle"
+  fi
+elif [ "${LMCACHE_MP_TRANSFER_MODE}" = "lmcache_driven" ]; then
+  echo "Transport mode: lmcache-driven (IPC handle path)"
+  EXPECTED_TRANSPORT="lmcache_driven"
+else
+  echo "Transport mode: unknown '${LMCACHE_MP_TRANSFER_MODE}',"
+  echo "  falling back to LMCACHE_SHM_NAME-based detection"
+  if [ "${LMCACHE_SHM_NAME}" = "__default__" ]; then
+    echo "Transport mode: data/shm (shared memory, fallback)"
+    EXPECTED_TRANSPORT="shm"
+  else
+    echo "Transport mode: data/pickle (--shm-name '${LMCACHE_SHM_NAME}')"
+    LMCACHE_ARGS+=(--shm-name "${LMCACHE_SHM_NAME}")
+    EXPECTED_TRANSPORT="pickle"
+  fi
+fi
+
+lmcache server "${LMCACHE_ARGS[@]}" \
+  >"${LMCACHE_LOG}" 2>&1 &
+LMCACHE_PID=$!
+echo "LMCache server started (PID=${LMCACHE_PID})"
+sleep 1
+if ! kill -0 "${LMCACHE_PID}" 2>/dev/null; then
+  echo "❌ LMCache server exited immediately after startup. See ${LMCACHE_LOG} for details"
+  false
+fi
+
+echo "Waiting for LMCache healthcheck at http://localhost:${LMCACHE_HTTP_PORT}/healthcheck (timeout: ${LMCACHE_HEALTHCHECK_TIMEOUT}s)"
+if ! wait_for_endpoint_contains "http://localhost:${LMCACHE_HTTP_PORT}/healthcheck" "${LMCACHE_HEALTHCHECK_TIMEOUT}" "" "LMCache server"; then
+  false
+fi
+echo "✅ LMCache server is healthy"
+
+echo "[Phase 2 / Step 4] Installing system libs (Linux only) and starting vLLM server"
+if [ "$(uname -s)" = "Linux" ]; then
+  # System libs vLLM's CPU serve path dlopens at import time:
+  #   - libnuma1: needed by some vLLM CPU code paths.
+  #   - ffmpeg:   provides libavutil.so.{56..60} etc. that torchcodec
+  #               dlopens. Recent vLLM nightlies import torchcodec
+  #               unconditionally, so `vllm serve` aborts with
+  #               "libavutil.so.NN: cannot open shared object file"
+  #               without FFmpeg — even for text-only models.
+  # Prefer sudo if present (GitHub ubuntu runners need it). Install only
+  # what's missing and never let an apt hiccup fail the step.
+  MISSING_PKGS=()
+  if [ ! -e /usr/lib/x86_64-linux-gnu/libnuma.so.1 ] \
+     && [ ! -e /lib/x86_64-linux-gnu/libnuma.so.1 ]; then
+    MISSING_PKGS+=(libnuma1)
+  fi
+  # torchcodec supports FFmpeg 4-8; the distro's ffmpeg package provides a
+  # compatible libavutil. Detect via ldconfig so we match whichever
+  # soname (56..60) the runner already ships.
+  if ! ldconfig -p 2>/dev/null | grep -q 'libavutil\.so'; then
+    MISSING_PKGS+=(ffmpeg)
+  fi
+  if [ "${#MISSING_PKGS[@]}" -gt 0 ]; then
+    echo "Installing missing system packages: ${MISSING_PKGS[*]}"
+    if command -v sudo >/dev/null 2>&1; then
+      sudo apt-get update \
+        && sudo apt-get install -y --no-install-recommends "${MISSING_PKGS[@]}" \
+        || echo "⚠️  apt-get install (${MISSING_PKGS[*]}) via sudo failed; continuing"
+    else
+      apt-get update \
+        && apt-get install -y --no-install-recommends "${MISSING_PKGS[@]}" \
+        || echo "⚠️  apt-get install (${MISSING_PKGS[*]}) failed; continuing"
+    fi
+  else
+    echo "libnuma1 and FFmpeg runtime libs already present, skipping apt install"
+  fi
+fi
+# VLLM_DEVICE is the modern env var (vLLM 0.8+)
+export VLLM_DEVICE=cpu
+export VLLM_TARGET_DEVICE=cpu
+start_vllm
+
+echo "[Phase 2 / Step 5] Sending E2E test request"
+completion_response="$(curl -fsS "http://localhost:${VLLM_PORT}/v1/completions" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"facebook/opt-125m","prompt":"Hello","max_tokens":5}')"
+echo "Completion response: ${completion_response}"
+if ! echo "${completion_response}" | grep -q '"choices"'; then
+  echo "❌ E2E request response failed structural validation"
+  false
+fi
+if ! echo "${completion_response}" | grep -q "facebook/opt-125m"; then
+  echo "❌ E2E request response missing expected model"
+  false
+fi
+echo "✅ E2E request validation passed"
+
+# Verify transport mode (logged after vLLM connects to LMCache server)
+echo "[Phase 2 / Step 5.5] Verifying transport mode: expecting '${EXPECTED_TRANSPORT}'"
+# Worker logs `Creating transfer context (device_type=<dev>, mode=<m>)`
+# from worker_transfer.py:create_transfer_context, where <m> is the
+# resolved MPTransferMode after env-var lookup. This is the single source
+# of truth for which TransferContext the worker actually entered. Note:
+# the worker is a child of `vllm serve`, so its LMCache log lines land in
+# VLLM_LOG (vllm's stdout), not in LMCACHE_LOG (lmcache server's stdout).
+# The shm/pickle branches still grep LMCACHE_LOG because the strategy
+# line is emitted by the lmcache server itself.
+if [ "${EXPECTED_TRANSPORT}" = "lmcache_driven" ]; then
+  if ! grep -q "Creating transfer context.*mode=lmcache_driven" "${VLLM_LOG}" 2>/dev/null; then
+    echo "❌ Expected lmcache-driven worker context but 'mode=lmcache_driven' not found in vLLM log"
+    tail -50 "${VLLM_LOG}"
+    false
+  fi
+  echo "✅ Transport mode confirmed: lmcache-driven (IPC handle path)"
+elif [ "${EXPECTED_TRANSPORT}" = "engine_driven" ]; then
+  if ! grep -q "Creating transfer context.*mode=engine_driven" "${VLLM_LOG}" 2>/dev/null; then
+    echo "❌ Expected engine-driven worker context but 'mode=engine_driven' not found in vLLM log"
+    tail -50 "${VLLM_LOG}"
+    false
+  fi
+  echo "✅ Transport mode confirmed: engine-driven"
+elif [ "${EXPECTED_TRANSPORT}" = "shm" ]; then
+  if ! grep -q "Using shm non-GPU transfer strategy" "${LMCACHE_LOG}" 2>/dev/null; then
+    echo "❌ Expected shm transport but server strategy line not found in log"
+    tail -50 "${LMCACHE_LOG}"
+    false
+  fi
+  echo "✅ Transport mode confirmed: shm"
+elif [ "${EXPECTED_TRANSPORT}" = "pickle" ]; then
+  if ! grep -q "Using pickle non-GPU transfer strategy" "${LMCACHE_LOG}" 2>/dev/null; then
+    echo "❌ Expected pickle transport but server strategy line not found in log"
+    tail -50 "${LMCACHE_LOG}"
+    false
+  fi
+  echo "✅ Transport mode confirmed: pickle"
+fi
+
+echo "[Phase 2 / Step 6] Cleaning up Phase 2 vLLM"
+stop_vllm
+echo "✅ Phase 2 cleanup completed"
+
+echo "✅ CPU E2E validation passed"
+
+# ═══════════════════════════════════════════════════════════════════
+# Phase 3: Cache Hit Validation
+# ═══════════════════════════════════════════════════════════════════
+# Scenario:
+#   - LMCache server stays running the entire time
+#   - vLLM instance 1: request A → LMCache store; request A again → LMCache hit
+#   - vLLM restart (instance 2): request A → LMCache hit (cross-instance)
+#   - All three outputs must be identical (bit-exact with temperature=0)
+# ═══════════════════════════════════════════════════════════════════
+
+echo "=== Cache Hit Validation (Phase 3) ==="
+
+# Generate a fixed ~1000 token prompt
+PROMPT_FILE="/tmp/build_${BUILD_ID}_phase3_prompt.txt"
+python3 -c "
+# A diverse, non-repetitive story prompt (~1000 tokens for opt-125m).
+# The model will continue the narrative; correctness doesn't matter,
+# only that all three runs produce identical output (cache consistency).
+story = '''Once upon a time in a small coastal village, there lived an old lighthouse keeper named Thomas. Every evening, he climbed the one hundred and thirty-seven steps to the top of the lighthouse to light the great lamp. The sea was unpredictable in those parts. Ships from distant lands carried spices, silk, and stories of places Thomas had never seen. One stormy night in November, a merchant vessel called the Silver Heron appeared on the horizon, listing dangerously to starboard. Thomas watched through his brass telescope as the waves crashed against its hull. He knew that if the ship did not change course within the next ten minutes, it would strike the jagged rocks known locally as the Devil's Teeth. He grabbed the emergency flare gun from the wooden cabinet and fired three red flares into the sky. The captain of the Silver Heron saw the warning and ordered hard to port. The ship groaned as it turned, barely clearing the outermost rock by twenty meters. The next morning, the captain rowed ashore to thank Thomas personally. He brought a gift: a small wooden box containing a compass that always pointed not north, but toward home. Thomas kept it on his desk for the rest of his days. Years later, when Thomas retired, he passed the compass to his granddaughter Elena, who had inherited his love of the sea. Elena became a marine biologist studying the migration patterns of humpback whales along the Pacific coast. She traveled from Alaska to Mexico following the whale pods, documenting their songs and social behaviors. Her research revealed that whale families maintained bonds across thousands of miles, communicating through low-frequency calls that could travel entire ocean basins. One afternoon while diving near a coral reef off the coast of Baja California, Elena discovered something extraordinary beneath a rocky overhang:'''
+print(story, end='')
+" > "${PROMPT_FILE}"
+echo "Generated prompt file: ${PROMPT_FILE} ($(wc -c < "${PROMPT_FILE}") bytes)"
+
+# Reset metrics to have a clean baseline
+echo "[Phase 3 / Step 1] Resetting LMCache metrics"
+curl -fsS -X POST "http://localhost:${LMCACHE_HTTP_PORT}/metrics/reset" >/dev/null
+echo "✅ Metrics reset"
+
+# Start vLLM instance 1
+echo "[Phase 3 / Step 2] Starting vLLM (instance 1)"
+start_vllm
+
+# Request A (first time) → should trigger store
+echo "[Phase 3 / Step 3] Request A (first) — expecting LMCache store"
+L1_WRITE_BEFORE=$(scrape_metric "lmcache_mp_l1_write_chunks_total")
+OUTPUT_1=$(send_completion "${PROMPT_FILE}" 50)
+echo "Output 1: ${OUTPUT_1}"
+sleep 2  # allow async store to complete
+L1_WRITE_AFTER=$(scrape_metric "lmcache_mp_l1_write_chunks_total")
+STORE_DELTA=$((L1_WRITE_AFTER - L1_WRITE_BEFORE))
+echo "L1 write chunks delta: ${STORE_DELTA}"
+if [ "${STORE_DELTA}" -lt 1 ]; then
+  echo "❌ No L1 write activity after first request (expected store)"
+  false
+fi
+echo "✅ LMCache store verified (${STORE_DELTA} chunks written)"
+
+# Request A (second time, same vLLM instance) → should trigger read/hit
+echo "[Phase 3 / Step 4] Request A (second) — expecting LMCache hit"
+L1_READ_BEFORE=$(scrape_metric "lmcache_mp_l1_read_chunks_total")
+OUTPUT_2=$(send_completion "${PROMPT_FILE}" 50)
+echo "Output 2: ${OUTPUT_2}"
+sleep 2
+L1_READ_AFTER=$(scrape_metric "lmcache_mp_l1_read_chunks_total")
+READ_DELTA=$((L1_READ_AFTER - L1_READ_BEFORE))
+echo "L1 read chunks delta: ${READ_DELTA}"
+if [ "${READ_DELTA}" -lt 1 ]; then
+  echo "❌ No L1 read activity on second request (expected cache hit)"
+  false
+fi
+echo "✅ LMCache hit verified on same instance (${READ_DELTA} chunks read)"
+
+# Restart vLLM
+echo "[Phase 3 / Step 5] Restarting vLLM (instance 2)"
+stop_vllm
+sleep 2
+start_vllm
+
+# Request A (third time, new vLLM instance) → should trigger read/hit from LMCache
+echo "[Phase 3 / Step 6] Request A (third) — expecting LMCache hit after vLLM restart"
+L1_READ_BEFORE=$(scrape_metric "lmcache_mp_l1_read_chunks_total")
+OUTPUT_3=$(send_completion "${PROMPT_FILE}" 50)
+echo "Output 3: ${OUTPUT_3}"
+sleep 2
+L1_READ_AFTER=$(scrape_metric "lmcache_mp_l1_read_chunks_total")
+READ_DELTA=$((L1_READ_AFTER - L1_READ_BEFORE))
+echo "L1 read chunks delta: ${READ_DELTA}"
+if [ "${READ_DELTA}" -lt 1 ]; then
+  echo "❌ No L1 read activity after vLLM restart (expected cross-instance cache hit)"
+  false
+fi
+echo "✅ LMCache cross-instance hit verified (${READ_DELTA} chunks read)"
+
+# Verify all three outputs are identical
+echo "[Phase 3 / Step 7] Verifying output consistency"
+if [ "${OUTPUT_1}" != "${OUTPUT_2}" ]; then
+  echo "❌ Output mismatch between request 1 and request 2"
+  echo "  Output 1: ${OUTPUT_1}"
+  echo "  Output 2: ${OUTPUT_2}"
+  false
+fi
+if [ "${OUTPUT_1}" != "${OUTPUT_3}" ]; then
+  echo "❌ Output mismatch between request 1 and request 3 (after vLLM restart)"
+  echo "  Output 1: ${OUTPUT_1}"
+  echo "  Output 3: ${OUTPUT_3}"
+  false
+fi
+echo "✅ All three outputs are identical — cache does not alter inference results"
+
+# Negative test: a completely different prompt should NOT hit the cache
+echo "[Phase 3 / Step 8] Request B (different prompt) — expecting cache MISS"
+PROMPT_FILE_B="/tmp/build_${BUILD_ID}_phase3_prompt_b.txt"
+python3 -c "
+# A completely different prompt that shares no prefix with prompt A
+story_b = '''In the year 2147, humanity established its first permanent colony on Mars. The settlement, named Arcadia, housed three thousand researchers and engineers working to terraform the red planet. Chief botanist Dr. Yuki Tanaka spent her days in the greenhouse domes, cultivating genetically modified crops that could thrive in Martian soil. The atmospheric processors hummed day and night, slowly converting carbon dioxide into breathable oxygen. It was tedious work measured in decades, but the colonists were patient. Every morning, Dr. Tanaka checked her instruments and recorded the oxygen levels in her logbook. Today the readings showed'''
+print(story_b, end='')
+" > "${PROMPT_FILE_B}"
+L1_READ_BEFORE=$(scrape_metric "lmcache_mp_l1_read_chunks_total")
+OUTPUT_B=$(send_completion "${PROMPT_FILE_B}" 50)
+echo "Output B: ${OUTPUT_B}"
+wait_for_metric_change "lmcache_mp_l1_read_chunks_total" "${L1_READ_BEFORE}" 5 || true
+L1_READ_AFTER=$(scrape_metric "lmcache_mp_l1_read_chunks_total")
+READ_DELTA=$((L1_READ_AFTER - L1_READ_BEFORE))
+echo "L1 read chunks delta for new prompt: ${READ_DELTA}"
+if [ "${READ_DELTA}" -gt 0 ]; then
+  echo "❌ Unexpected cache hit on a completely different prompt — metrics may be unreliable"
+  false
+fi
+echo "✅ Cache miss confirmed for different prompt — metrics are trustworthy"
+
+echo "[Phase 3 / Step 9] Cleaning up"
+stop_vllm
+cleanup_processes
+echo "✅ Phase 3 cleanup completed"
+
+echo ""
+echo "=========================================="
+echo "✅ All phases passed (Phase 1 + 2 + 3)"
+echo "=========================================="
+
+# Make sure lmcache/vllm processes started in this run are reaped so
+# the next CI step does not collide on their default ZMQ/HTTP ports.
+cleanup_processes
+
+# Upload artifacts BEFORE deleting the workspace
+upload_artifacts
+cleanup_workspace
diff --git a/.github/workflows/actionlint.dockerfile b/.github/workflows/actionlint.dockerfile
new file mode 100644
index 0000000..d4df32d
--- /dev/null
+++ b/.github/workflows/actionlint.dockerfile
@@ -0,0 +1,3 @@
+# Since dependabot cannot update workflows using docker,
+# we use this indirection since dependabot can update this file.
+FROM rhysd/actionlint:1.7.7@sha256:887a259a5a534f3c4f36cb02dca341673c6089431057242cdc931e9f133147e9
diff --git a/.github/workflows/actionlint.yml b/.github/workflows/actionlint.yml
new file mode 100644
index 0000000..71f0548
--- /dev/null
+++ b/.github/workflows/actionlint.yml
@@ -0,0 +1,52 @@
+name: Lint GitHub Actions workflows
+on:
+  push:
+    branches:
+      - "dev"
+      - "release-**"
+    paths:
+      - '.github/actions/*.ya?ml'
+      - '.github/workflows/*.ya?ml'
+      - '.github/workflows/actionlint.*' # This workflow
+  pull_request:
+    branches:
+      - "dev"
+      - "release-**"
+    paths:
+      - '.github/actions/*.ya?ml'
+      - '.github/workflows/*.ya?ml'
+      - '.github/workflows/actionlint.*' # This workflow
+
+env:
+  LC_ALL: en_US.UTF-8
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Harden Runner"
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          disable-sudo-and-containers: false
+          egress-policy: audit
+
+      - name: "Checkout"
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+
+      - name: "Download actionlint"
+        run: |
+          docker build --tag actionlint - < .github/workflows/actionlint.dockerfile
+
+      - name: "Check workflow files"
+        run: |
+          echo "::add-matcher::.github/workflows/matchers/actionlint.json"
+          docker run --volume="${PWD}:/repo" --workdir=/repo actionlint -color
diff --git a/.github/workflows/aerospike_integration.yml b/.github/workflows/aerospike_integration.yml
new file mode 100644
index 0000000..fbe1d4e
--- /dev/null
+++ b/.github/workflows/aerospike_integration.yml
@@ -0,0 +1,142 @@
+# Optional Aerospike native L2 integration (BUILD_AEROSPIKE=1 + CE Docker).
+name: Aerospike integration
+
+on:
+  push:
+    branches:
+      - "dev"
+      - "release-**"
+    paths:
+      - "csrc/storage_backends/aerospike/**"
+      - "lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py"
+      - "lmcache/v1/storage_backend/native_clients/aerospike_client.py"
+      - "setup.py"
+      - "tests/aerospike_ce.conf.template"
+      - "tests/v1/distributed/test_aerospike_*"
+      - ".github/workflows/aerospike_integration.yml"
+  pull_request:
+    branches:
+      - "dev"
+      - "release-**"
+    paths:
+      - "csrc/storage_backends/aerospike/**"
+      - "lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py"
+      - "lmcache/v1/storage_backend/native_clients/aerospike_client.py"
+      - "setup.py"
+      - "tests/aerospike_ce.conf.template"
+      - "tests/v1/distributed/test_aerospike_*"
+      - ".github/workflows/aerospike_integration.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  AEROSPIKE_CLIENT_C_VERSION: "7.3.0"
+  AEROSPIKE_CLIENT_C_UBUNTU: "ubuntu22.04"
+  AEROSPIKE_CONTAINER_NAME: lmcache-aerospike-ci
+
+jobs:
+  aerospike-native-l2:
+    name: Aerospike native L2
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install Aerospike C client (prebuilt)
+        run: |
+          set -euo pipefail
+          DEPS="${GITHUB_WORKSPACE}/.deps"
+          INSTALL="${DEPS}/aerospike-install"
+          VERSION="${AEROSPIKE_CLIENT_C_VERSION}"
+          UBUNTU="${AEROSPIKE_CLIENT_C_UBUNTU}"
+          BASE="aerospike-client-c-libuv_${VERSION}_${UBUNTU}_x86_64"
+          URL="https://download.aerospike.com/artifacts/aerospike-client-c/${VERSION}/${BASE}.tgz"
+          mkdir -p "${DEPS}"
+          curl -fsSL -o "${DEPS}/${BASE}.tgz" "${URL}"
+          tar xzf "${DEPS}/${BASE}.tgz" -C "${DEPS}"
+          rm -rf "${INSTALL}"
+          mkdir -p "${INSTALL}"
+          dpkg-deb -x "${DEPS}/${BASE}/aerospike-client-c-libuv-devel_${VERSION}-${UBUNTU}_amd64.deb" "${INSTALL}"
+          dpkg-deb -x "${DEPS}/${BASE}/aerospike-client-c-libuv_${VERSION}-${UBUNTU}_amd64.deb" "${INSTALL}"
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq libyaml-0-2 libuv1-dev
+          (cd "${DEPS}" && apt download libyaml-dev && \
+            rm -rf libyaml-install && mkdir -p libyaml-install && \
+            dpkg-deb -x libyaml-dev_*.deb libyaml-install)
+          {
+            echo "AEROSPIKE_INCLUDE_DIR=${INSTALL}/usr/include"
+            echo "AEROSPIKE_LIBRARY_DIR=${INSTALL}/usr/lib"
+            echo "LD_LIBRARY_PATH=${INSTALL}/usr/lib:${DEPS}/libyaml-install/usr/lib/x86_64-linux-gnu"
+          } >> "${GITHUB_ENV}"
+
+      - name: Build LMCache with Aerospike extension
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip wheel
+          python -m pip install 'setuptools>=77.0.3,<81.0.0' 'pybind11>=2.12'
+          python -m pip install numpy
+          python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+          export BUILD_AEROSPIKE=1
+          export NO_GPU_EXT=1
+          python -m pip install -e . --no-build-isolation
+          python -m pip install 'aerospike>=14.0.0,<19.0.0' pytest
+          python -c "from lmcache.lmcache_aerospike import LMCacheAerospikeClient; print('OK:', LMCacheAerospikeClient)"
+
+      - name: Start Aerospike CE
+        id: aerospike
+        run: |
+          set -euo pipefail
+          HOST_PORT=$(python -c 'import socket; s=socket.socket(); s.bind(("", 0)); print(s.getsockname()[1]); s.close()')
+          CONF_DIR=$(mktemp -d)
+          sed "s/__ACCESS_PORT__/${HOST_PORT}/g" tests/aerospike_ce.conf.template > "${CONF_DIR}/aerospike.conf"
+          docker rm -f "${AEROSPIKE_CONTAINER_NAME}" 2>/dev/null || true
+          docker run -d \
+            --name "${AEROSPIKE_CONTAINER_NAME}" \
+            -p "${HOST_PORT}:3000" \
+            -v "${CONF_DIR}/aerospike.conf:/etc/aerospike/aerospike.template.conf:ro" \
+            aerospike/aerospike-server:latest
+          deadline=$((SECONDS + 90))
+          until docker exec "${AEROSPIKE_CONTAINER_NAME}" asinfo -v status 2>/dev/null | grep -qE 'ok|normal'; do
+            if (( SECONDS >= deadline )); then
+              docker logs "${AEROSPIKE_CONTAINER_NAME}" 2>&1 | tail -80
+              exit 1
+            fi
+            sleep 1
+          done
+          host_deadline=$((SECONDS + 90))
+          until python -c "
+          import aerospike
+          c = aerospike.client({'hosts': [('127.0.0.1', ${HOST_PORT})]})
+          c.connect()
+          info = c.info_random_node('namespace/lmcache')
+          c.close()
+          assert 'nsup-period=120' in info
+          "; do
+            if (( SECONDS >= host_deadline )); then
+              docker logs "${AEROSPIKE_CONTAINER_NAME}" 2>&1 | tail -80
+              exit 1
+            fi
+            sleep 1
+          done
+          {
+            echo "AEROSPIKE_TEST_HOST=127.0.0.1"
+            echo "AEROSPIKE_TEST_PORT=${HOST_PORT}"
+            echo "AEROSPIKE_TEST_NAMESPACE=lmcache"
+            echo "RUN_AEROSPIKE_INTEGRATION=1"
+          } >> "${GITHUB_ENV}"
+
+      - name: Integration tests
+        run: |
+          pytest tests/v1/distributed/test_aerospike_l2_integration.py -v --tb=short
+
+      - name: Stop Aerospike CE
+        if: always()
+        run: docker rm -f "${AEROSPIKE_CONTAINER_NAME}" 2>/dev/null || true
diff --git a/.github/workflows/automerge-labeler.yml b/.github/workflows/automerge-labeler.yml
new file mode 100644
index 0000000..d3b49a5
--- /dev/null
+++ b/.github/workflows/automerge-labeler.yml
@@ -0,0 +1,17 @@
+name: Label auto-merge PRs
+
+on:
+  pull_request_target:
+    types: [ auto_merge_enabled, auto_merge_disabled ]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  add_remove_labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ubuntudroid/automerge-labeler@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          label: 'full'
diff --git a/.github/workflows/build_cli_artifacts.yml b/.github/workflows/build_cli_artifacts.yml
new file mode 100644
index 0000000..42a0ab0
--- /dev/null
+++ b/.github/workflows/build_cli_artifacts.yml
@@ -0,0 +1,106 @@
+name: Build CLI Artifacts
+
+# Reusable workflow that builds the pure-Python lmcache-cli wheel (no CUDA).
+# Uploaded as the `release-cli-artifacts` GHA artifact.
+
+on:
+    workflow_call:
+    pull_request:
+        branches:
+            - dev
+            - "release-**"
+        paths:
+            - 'lmcache/cli/**.py'
+            - 'pyproject_cli.toml'
+            - 'requirements/cli.txt'
+            - '.github/workflows/build_cli_artifacts.yml'
+
+env:
+    LC_ALL: en_US.UTF-8
+
+defaults:
+    run:
+        shell: bash
+
+# Cancel older in-flight runs on the same PR / branch.
+concurrency:
+    group: build-cli-${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    build-cli-artifacts:
+        name: Build CLI artifacts
+        runs-on: ubuntu-latest
+        steps:
+            - name: "Harden Runner"
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Checkout code
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              with:
+                fetch-depth: 0
+
+            # Keep stable vX.Y.Z and rc/a/b pre-release tags; strip variant tags
+            # (v*-cu129, v*-alpha) that yield invalid PEP 440 versions (see #3123).
+            - name: Remove non-release tags (keep stable + rc/a/b pre-releases)
+              run: git tag -l | grep -vE '^v[0-9]+\.[0-9]+\.[0-9]+((rc|a|b)[0-9]+)?$' | xargs -r git tag -d
+
+            - name: Setup Python 3.13
+              uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+              with:
+                python-version: "3.13"
+
+            - name: Install build tooling
+              run: |
+                python -m pip install --upgrade pip
+                pip install build
+
+            - name: Clean up release artifacts
+              run: |
+                rm -rf dist/
+
+            - name: Build lmcache-cli wheel (pure Python, no native extensions)
+              run: |
+                cp pyproject_cli.toml pyproject.toml
+                NO_NATIVE_EXT=1 python -m build --wheel
+
+            - name: Smoke-test CLI wheel (no torch)
+              run: |
+                pip install dist/lmcache_cli-*.whl
+
+                # CLI wheel must be pure-Python: no compiled extension bundled.
+                if unzip -l dist/lmcache_cli-*.whl | grep -E '\.(so|pyd)$'; then
+                  echo "::error::CLI wheel contains compiled extensions; should be pure-Python"
+                  exit 1
+                fi
+
+                # Pure-Python surface must import without torch / native ops.
+                python -c "import lmcache"
+
+                # Native CUDA ops must be unreachable from the slim wheel.
+                if python -c "import lmcache.c_ops" 2>/dev/null; then
+                  echo "::error::CLI wheel can import lmcache.c_ops; native ops must be absent from the pure-Python wheel"
+                  exit 1
+                fi
+                echo "OK: lmcache.c_ops is not importable from the CLI wheel"
+
+                lmcache --help
+
+                # Slim-supported subcommands only (server is full-only).
+                for cmd in mock kvcache describe ping query bench tool trace; do
+                  echo "::group::lmcache $cmd --help"
+                  lmcache "$cmd" --help
+                  echo "::endgroup::"
+                done
+
+            - name: Upload CLI release artifacts to GHA
+              uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+              with:
+                name: release-cli-artifacts
+                path: dist/
diff --git a/.github/workflows/build_cpu_artifacts.yml b/.github/workflows/build_cpu_artifacts.yml
new file mode 100644
index 0000000..91152e7
--- /dev/null
+++ b/.github/workflows/build_cpu_artifacts.yml
@@ -0,0 +1,122 @@
+name: Build CPU Artifacts
+
+# Build LMCache with NO_GPU_EXT=1 (common C++ extensions only).
+# Gates the CPU-only build path against regression.
+
+on:
+    workflow_call:
+    pull_request:
+        branches:
+            - dev
+            - "release-**"
+        paths:
+            - 'setup.py'
+            - 'pyproject.toml'
+            - 'csrc/**'
+            - 'requirements/common.txt'
+            - 'requirements/build.txt'
+            - 'lmcache/__init__.py'
+            - '.github/workflows/build_cpu_artifacts.yml'
+
+env:
+    LC_ALL: en_US.UTF-8
+
+defaults:
+    run:
+        shell: bash
+
+# Cancel stale runs per ref.
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    build-cpu-artifacts:
+        name: Build CPU artifacts
+        runs-on: ubuntu-latest
+        steps:
+            - name: "Harden Runner"
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Checkout code
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              with:
+                fetch-depth: 0
+
+            - name: Remove non-release tags
+              run: git tag -l | grep -vE '^v[0-9]+\.[0-9]+\.[0-9]+$' | xargs -r git tag -d
+
+            - name: Setup Python 3.13
+              uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+              with:
+                python-version: "3.13"
+
+            - name: Install build tooling and CPU torch
+              run: |
+                python -m pip install --upgrade pip
+                pip install --index-url https://download.pytorch.org/whl/cpu torch
+                # Pre-install build deps for --no-isolation below.
+                pip install -r requirements/build.txt
+                pip install build
+
+            - name: Clean up release artifacts
+              run: |
+                rm -rf dist/
+
+            - name: Build CPU-only wheel (common C++ extensions, no GPU backend)
+              # --skip-dependency-check: the pre-installed CPU torch may not
+              # match pyproject.toml's exact build-system pin, but is ABI-
+              # compatible for compiling CppExtensions.
+              run: |
+                NO_GPU_EXT=1 python -m build --wheel --no-isolation \
+                  --skip-dependency-check
+
+            - name: Verify CPU wheel contents
+              run: |
+                set -e
+                # Required: common C++ extensions.
+                for mod in native_storage_ops lmcache_redis lmcache_fs; do
+                  if ! unzip -l dist/lmcache-*.whl | grep -qE "lmcache/${mod}\..*\.so"; then
+                    echo "::error::missing common C++ extension: ${mod}"
+                    exit 1
+                  fi
+                done
+                # Forbidden: GPU extensions.
+                for mod in c_ops xpu_ops; do
+                  if unzip -l dist/lmcache-*.whl | grep -qE "lmcache/${mod}\..*\.so"; then
+                    echo "::error::unexpected GPU extension in CPU wheel: ${mod}"
+                    exit 1
+                  fi
+                done
+
+            - name: Smoke-test CPU wheel
+              # Run from $RUNNER_TEMP so Python resolves `lmcache` from the
+              # installed wheel, not the checkout on CWD.
+              working-directory: ${{ runner.temp }}
+              run: |
+                set -e
+                pip install ${{ github.workspace }}/dist/lmcache-*.whl
+                python -c "
+                import lmcache
+                assert lmcache.torch_device_type == 'cpu', lmcache.torch_device_type
+                "
+                python -c "import lmcache.native_storage_ops"
+                python -c "import lmcache.lmcache_redis"
+                python -c "import lmcache.lmcache_fs"
+                # c_ops resolves to the python_ops_fallback shim on CPU.
+                python -c "
+                import sys, lmcache, lmcache.c_ops
+                assert sys.modules['lmcache.c_ops'].__name__ == 'lmcache.python_ops_fallback'
+                "
+
+            - name: Upload CPU release artifacts to GHA
+              uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+              with:
+                name: release-cpu-artifacts
+                path: dist/
diff --git a/.github/workflows/build_cu129_artifacts.yml b/.github/workflows/build_cu129_artifacts.yml
new file mode 100644
index 0000000..39da202
--- /dev/null
+++ b/.github/workflows/build_cu129_artifacts.yml
@@ -0,0 +1,105 @@
+name: Build cu129 Artifacts
+
+# Reusable workflow that builds the cu129 CUDA 12.9 wheel via cibuildwheel
+# against the pytorch manylinux cu12.9 base image.
+# Uploaded as the `release-cu129-artifacts` GHA artifact.
+# The cu12.9 wheel carries no local version suffix and is published to a
+# dedicated v{tag}-cu12 GitHub Release (not PyPI).
+
+on:
+    workflow_call:
+
+env:
+    LC_ALL: en_US.UTF-8
+
+defaults:
+    run:
+        shell: bash
+
+permissions:
+    contents: read
+
+jobs:
+    build-cu129-artifacts:
+        name: Build cu129 artifacts
+        runs-on: ubuntu-latest
+        steps:
+            - name: "Harden Runner"
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Checkout code
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              with:
+                fetch-depth: 0
+
+            # Keep stable vX.Y.Z and rc/a/b pre-release tags; strip variant tags
+            # (v*-cu129, v*-alpha) that yield invalid PEP 440 versions (see #3123).
+            - name: Remove non-release tags (keep stable + rc/a/b pre-releases)
+              run: git tag -l | grep -vE '^v[0-9]+\.[0-9]+\.[0-9]+((rc|a|b)[0-9]+)?$' | xargs -r git tag -d
+
+            - name: Login to DockerHub
+              # Skip when either the username var or the token secret is
+              # absent. Secrets are not inherited into reusable workflows
+              # without `secrets: inherit`, and fork PRs never get secrets,
+              # so the token can legitimately be empty on some runs.
+              if: vars.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != ''
+              env:
+                DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+              uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+              with:
+                username: ${{ vars.DOCKERHUB_USERNAME }}
+                password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+            - name: Free disk space
+              uses: ./.github/actions/free-disk-space
+
+            - name: Setup Python 3.13
+              uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+              with:
+                python-version: "3.13"
+
+            - name: Install build tooling
+              run: |
+                python -m pip install --upgrade pip
+                pip install build cibuildwheel
+
+            - name: Clean up release artifacts
+              run: |
+                rm -rf dist/
+
+            - name: Get base version for cu12.9 wheel
+              run: |
+                if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+                  BASE="${GITHUB_REF_NAME#v}"
+                else
+                  BASE=$(git tag --list 'v[0-9]*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 | sed 's/^v//' || echo "0.0.0.dev")
+                fi
+                echo "CU129_VERSION=${BASE}" >> "$GITHUB_ENV"
+
+            - name: Build cu12.9 CUDA wheels with cibuildwheel
+              env:
+                CIBW_MANYLINUX_X86_64_IMAGE: docker.io/pytorch/manylinux2_28-builder:cuda12.9
+                CIBW_ENVIRONMENT: 'TORCH_CUDA_ARCH_LIST="7.0;7.5;8.0;8.6;8.9;9.0;10.0;12.0" ENABLE_CXX11_ABI=1 LMCACHE_CUDA_MAJOR=12 SETUPTOOLS_SCM_PRETEND_VERSION=${{ env.CU129_VERSION }} PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cu129'
+                CIBW_REPAIR_WHEEL_COMMAND_LINUX: >-
+                  auditwheel repair
+                  --plat manylinux_2_28_x86_64
+                  --exclude libtorch.so
+                  --exclude libtorch_cuda.so
+                  --exclude libtorch_python.so
+                  --exclude libtorch_cpu.so
+                  --exclude libc10.so
+                  --exclude libc10_cuda.so
+                  --exclude libcudart.so.12
+                  -w {dest_dir} {wheel}
+                CIBW_TEST_COMMAND: "python -c 'import lmcache.c_ops'"
+              run: |
+                python -m cibuildwheel --output-dir dist
+
+            - name: Upload cu12.9 release artifacts to GHA
+              uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+              with:
+                name: release-cu129-artifacts
+                path: dist/
diff --git a/.github/workflows/build_doc.yml b/.github/workflows/build_doc.yml
new file mode 100644
index 0000000..90f4550
--- /dev/null
+++ b/.github/workflows/build_doc.yml
@@ -0,0 +1,106 @@
+name: Build and Deploy Online Documentation
+
+on:
+  # Trigger the workflow on push request,
+  # for the dev branch
+  push:
+    branches:
+      - 'dev'
+    paths:
+     - 'docs/**'
+     - 'lmcache/**'
+     - 'examples/**'
+     - '.github/workflows/build_doc.yml'
+jobs:
+  build-docs:
+    name: Build docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          # Full git history needed for sphinx-multiversion to detect all tags/branches
+          fetch-depth: 0
+          # Fetch all branches and tags
+          fetch-tags: true
+
+      - name: Setup Python 3.13
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: "3.13"
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements/docs.txt
+
+      - name: Build Versioned Sphinx Documentation
+        run: |
+          sphinx-multiversion docs/source output
+          SPHINX_LANGUAGE=zh_CN sphinx-multiversion docs/source output-zh
+        continue-on-error: false
+
+      - name: Setup root docs, .nojekyll, and Chinese docs
+        run: |
+          touch output/.nojekyll
+          # Copy dev docs to root (latest docs at root URL)
+          cp -r output/dev/* output/
+          # Remove dev directory to avoid duplication
+          rm -rf output/dev
+          # Copy Chinese dev docs to /zh_CN/ and versioned docs under /zh_CN/<version>/
+          mkdir -p output/zh_CN
+          cp -r output-zh/dev/* output/zh_CN/
+          rm -rf output-zh/dev
+          cp -r output-zh/. output/zh_CN/
+          rm -rf output-zh
+
+      - name: Upload doc artifacts to GHA
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: doc-artifacts
+          path: output/
+
+  deploy-docs:
+    name: Deploy docs online
+    runs-on: ubuntu-latest
+    needs: build-docs
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Fetch doc artifacts
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+            name: doc-artifacts
+            path: output
+
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          repository: LM-Cache-Website/lm-cache-website.github.io
+          token: ${{ secrets.LMCACHE_DOC }}
+          path: target-repo
+
+      - name: Copy Files to Target Repository
+        run: |
+          cp -r output/* target-repo/
+
+      - name: Commit and Push to Target Repository
+        run: |
+          cd target-repo
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions@github.com"
+          git add .
+          if ! git diff --cached --quiet; then
+            git commit -m "Deploy updated online docs"
+            git push https://x-access-token:${{ secrets.LMCACHE_DOC }}@github.com/LM-Cache-Website/lm-cache-website.github.io.git main --force
+          else
+            echo "No changes to commit."
+          fi
diff --git a/.github/workflows/build_main_artifacts.yml b/.github/workflows/build_main_artifacts.yml
new file mode 100644
index 0000000..e618b13
--- /dev/null
+++ b/.github/workflows/build_main_artifacts.yml
@@ -0,0 +1,82 @@
+name: Build Main Artifacts
+
+# Reusable workflow that builds the main release artifacts:
+# - source distribution (tar ball)
+# - CUDA wheel (built via cibuildwheel, latest torch)
+# Uploaded as the `release-artifacts` GHA artifact.
+
+on:
+    workflow_call:
+
+env:
+    LC_ALL: en_US.UTF-8
+
+defaults:
+    run:
+        shell: bash
+
+permissions:
+    contents: read
+
+jobs:
+    build-artifacts:
+        name: Build artifacts
+        runs-on: ubuntu-latest
+        steps:
+            - name: "Harden Runner"
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Checkout code
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              with:
+                # for setuptools-scm
+                fetch-depth: 0
+
+            # Keep stable vX.Y.Z and rc/a/b pre-release tags; strip variant tags
+            # (v*-cu129, v*-alpha) that yield invalid PEP 440 versions (see #3123).
+            - name: Remove non-release tags (keep stable + rc/a/b pre-releases)
+              run: git tag -l | grep -vE '^v[0-9]+\.[0-9]+\.[0-9]+((rc|a|b)[0-9]+)?$' | xargs -r git tag -d
+
+            - name: Pin release version from tag (setuptools-scm)
+              if: startsWith(github.ref, 'refs/tags/v')
+              run: echo "SETUPTOOLS_SCM_PRETEND_VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"
+
+            - name: Free disk space
+              uses: ./.github/actions/free-disk-space
+
+            - name: Setup Python 3.13
+              uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+              with:
+                python-version: "3.13"
+
+            - name: Install build tooling
+              run: |
+                python -m pip install --upgrade pip
+                pip install build cibuildwheel
+
+            - name: Clean up release artifacts
+              run: |
+                rm -rf dist/
+
+            - name: Build source distribution (no native extensions)
+              run: |
+                NO_NATIVE_EXT=1 python -m build --sdist
+
+            - name: Build CUDA wheels with cibuildwheel
+              # Configuration is set in pyproject.toml
+              # this will build lmcache with the latest version of torch
+              # building from source will be required if a serving engine uses
+              # an earlier non-ABI compatible version of torch
+              env:
+                CIBW_TEST_COMMAND: "python -c 'import lmcache.c_ops'"
+              run: |
+                python -m cibuildwheel --output-dir dist
+
+            - name: Upload release artifacts to GHA
+              uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+              with:
+                name: release-artifacts
+                path: dist/
diff --git a/.github/workflows/code_quality_checks.yml b/.github/workflows/code_quality_checks.yml
new file mode 100644
index 0000000..4d7d262
--- /dev/null
+++ b/.github/workflows/code_quality_checks.yml
@@ -0,0 +1,68 @@
+name: Code Quality
+
+on:
+  workflow_call:
+  pull_request:
+
+# Cancel older in-flight runs on the same PR / branch.
+concurrency:
+  group: code-quality-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      lmcache: ${{ github.event_name == 'release' || steps.filter.outputs.lmcache == 'true' }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        if: github.event_name == 'push'
+        with:
+          fetch-depth: 2
+
+      - uses: dorny/paths-filter@v3
+        if: github.event_name == 'push' || github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            lmcache:
+              - '**'
+              - '!operator/**'
+              - '!.github/workflows/operator_*.yml'
+
+  pre-commit:
+    needs: changes
+    if: needs.changes.outputs.lmcache == 'true'
+    name: Check code quality
+    runs-on: ubuntu-latest
+    steps:
+        - name: Harden Runner
+          uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+          with:
+            disable-sudo-and-containers: true
+            egress-policy: audit
+
+        - name: Checkout code
+          uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+          with:
+            # for setuptools-scm
+            fetch-depth: 0
+
+        - name: Setup Python 3.13
+          uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+          with:
+            python-version: "3.13"
+
+        - run: echo "::add-matcher::.github/workflows/matchers/mypy.json"
+
+        - name: Run code quality checks - lint, format, spell, & static checks
+          uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1
+          with:
+            extra_args: --all-files
+
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..ed56272
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,112 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "dev" ]
+  pull_request:
+    branches: [ "dev" ]
+  schedule:
+    - cron: '29 4 * * 0'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ubuntu-latest
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        # Disable C/CPP scan for now until GPU runner available for the repo
+        # - language: c-cpp
+        #  build-mode: autobuild
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: "Harden Runner"
+      uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+      with:
+        disable-sudo-and-containers: true
+        egress-policy: audit
+
+    - name: Checkout repository
+      uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      with:
+        # for setuptools-scm
+        fetch-depth: 0
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@f443b600d91635bebf5b0d9ebc620189c0d6fba5 # v4.30.8
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@f443b600d91635bebf5b0d9ebc620189c0d6fba5 # v4.30.8
+      with:
+        category: "/language:${{matrix.language}}"
diff --git a/.github/workflows/cpu_device.yml b/.github/workflows/cpu_device.yml
new file mode 100644
index 0000000..ab8c1a5
--- /dev/null
+++ b/.github/workflows/cpu_device.yml
@@ -0,0 +1,174 @@
+name: CPU Device Tests
+
+# CPU device tests: server bench + vLLM e2e. Both job types share a
+# single environment (built once per OS) to avoid re-installing vLLM.
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - "dev"
+      - "release-**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      lmcache: >-
+        ${{
+          github.event_name == 'workflow_dispatch' ||
+          github.event_name == 'workflow_call' ||
+          steps.filter.outputs.lmcache == 'true'
+        }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        if: github.event_name == 'push'
+        with:
+          fetch-depth: 2
+
+      - uses: dorny/paths-filter@v3
+        if: >-
+          github.event_name == 'push' ||
+          github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            lmcache:
+              - 'lmcache/**'
+              - 'pyproject.toml'
+              - 'setup.py'
+              - 'requirements/**.txt'
+              - '.github/workflows/cpu_device.yml'
+              - '.github/scripts/cpu_device_test.sh'
+              - '.github/scripts/cpu_server_bench_test.sh'
+              - '.github/scripts/cpu_vllm_e2e_test.sh'
+              - '.github/scripts/install_vllm_cpu.sh'
+              - '.github/scripts/install_lmcache_cpu.sh'
+              - '.github/scripts/download_model.sh'
+              - '.github/scripts/run-cpu-e2e-validation.sh'
+              - '!operator/**'
+
+  cpu-device-test:
+    needs: changes
+    if: needs.changes.outputs.lmcache == 'true'
+    name: CPU device (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 120
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-latest]
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 1
+
+      - name: Setup Python 3.12
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            requirements/*.txt
+
+      - name: Install FFmpeg (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          if ! command -v ffmpeg >/dev/null 2>&1; then
+            brew install ffmpeg
+          else
+            echo "ffmpeg already installed: $(ffmpeg -version | head -n1)"
+          fi
+
+      - name: Cache opt-125m model (GitHub release)
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: opt-125m-gh-v2
+
+      - name: Install vLLM CPU (prebuilt nightly from PyPI)
+        run: bash .github/scripts/install_vllm_cpu.sh
+
+      - name: Install lmcache (CPU-only, no vLLM)
+        run: bash .github/scripts/install_lmcache_cpu.sh
+
+      - name: Download facebook/opt-125m (GitHub release)
+        run: bash .github/scripts/download_opt125m_github.sh
+
+      - name: Server bench — LMCache-driven
+        run: |
+          LMCACHE_BENCH_TRANSFER_MODE=lmcache_driven \
+          LMCACHE_HTTP_PORT_BENCH=18080 \
+          LMCACHE_ZMQ_PORT_BENCH=15555 \
+            bash .github/scripts/cpu_device_test.sh server_bench
+
+      - name: Server bench — Engine-driven
+        run: |
+          LMCACHE_BENCH_TRANSFER_MODE=engine_driven \
+          LMCACHE_HTTP_PORT_BENCH=18081 \
+          LMCACHE_ZMQ_PORT_BENCH=15556 \
+            bash .github/scripts/cpu_device_test.sh server_bench
+
+      - name: vLLM e2e — Engine-driven (pickle)
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          LMCACHE_E2E_TRANSPORT_MODE=pickle \
+          LMCACHE_HTTP_PORT_E2E=18082 \
+          LMCACHE_ZMQ_PORT_E2E=15557 \
+          VLLM_PORT_E2E=18000 \
+            bash .github/scripts/cpu_device_test.sh vllm_e2e
+
+      # POSIX SHM transport is Linux-only.
+      - name: vLLM e2e — Engine-driven (shm)
+        if: runner.os == 'Linux'
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          LMCACHE_E2E_TRANSPORT_MODE=shm \
+          LMCACHE_HTTP_PORT_E2E=18083 \
+          LMCACHE_ZMQ_PORT_E2E=15558 \
+          VLLM_PORT_E2E=18001 \
+            bash .github/scripts/cpu_device_test.sh vllm_e2e
+
+      - name: vLLM e2e — Engine-driven
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          LMCACHE_E2E_TRANSPORT_MODE=engine_driven \
+          LMCACHE_HTTP_PORT_E2E=18084 \
+          LMCACHE_ZMQ_PORT_E2E=15559 \
+          VLLM_PORT_E2E=18002 \
+            bash .github/scripts/cpu_device_test.sh vllm_e2e
+
+      - name: Upload logs on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cpu-device-logs-${{ matrix.os }}
+          path: |
+            /tmp/cpu_device_*.log
+          if-no-files-found: ignore
diff --git a/.github/workflows/matchers/actionlint.json b/.github/workflows/matchers/actionlint.json
new file mode 100644
index 0000000..4613e16
--- /dev/null
+++ b/.github/workflows/matchers/actionlint.json
@@ -0,0 +1,17 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "actionlint",
+      "pattern": [
+        {
+          "regexp": "^(?:\\x1b\\[\\d+m)?(.+?)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*:(?:\\x1b\\[\\d+m)*(\\d+)(?:\\x1b\\[\\d+m)*: (?:\\x1b\\[\\d+m)*(.+?)(?:\\x1b\\[\\d+m)* \\[(.+?)\\]$",
+          "file": 1,
+          "line": 2,
+          "column": 3,
+          "message": 4,
+          "code": 5
+        }
+      ]
+    }
+  ]
+}
diff --git a/.github/workflows/matchers/mypy.json b/.github/workflows/matchers/mypy.json
new file mode 100644
index 0000000..f048fce
--- /dev/null
+++ b/.github/workflows/matchers/mypy.json
@@ -0,0 +1,16 @@
+{
+  "problemMatcher": [
+    {
+      "owner": "mypy",
+      "pattern": [
+        {
+          "regexp": "^(.+):(\\d+):\\s(error|warning):\\s(.+)$",
+          "file": 1,
+          "line": 2,
+          "severity": 3,
+          "message": 4
+        }
+      ]
+    }
+  ]
+}
diff --git a/.github/workflows/nightly_build.yml b/.github/workflows/nightly_build.yml
new file mode 100644
index 0000000..6160988
--- /dev/null
+++ b/.github/workflows/nightly_build.yml
@@ -0,0 +1,221 @@
+name: Build nightly container image of latest code
+
+on:
+  schedule:
+    - cron: '30 7 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  nightly-wheels:
+    name: Build and publish nightly wheels
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          disable-sudo-and-containers: false
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Remove non-release tags
+        run: git tag -l | grep -vE '^v[0-9]+\.[0-9]+\.[0-9]+$' | xargs -r git tag -d
+
+      - name: Free disk space
+        uses: ./.github/actions/free-disk-space
+
+      - name: Setup Python 3.13
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: "3.13"
+
+      - name: Login to DockerHub
+        if: vars.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install cibuildwheel
+
+
+      - name: Build cu13.0 nightly wheel
+        env:
+          CIBW_TEST_COMMAND: "python -c 'import lmcache.c_ops'"
+        run: |
+          python -m cibuildwheel --output-dir dist/cu130
+
+      - name: Publish cu13.0 wheels to rolling nightly release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          gh release delete nightly --yes --cleanup-tag --repo ${{ github.repository }} 2>/dev/null || true
+          gh release create nightly \
+            --repo ${{ github.repository }} \
+            --title "Nightly $(date +'%Y-%m-%d') · CUDA 13.0" \
+            --notes "Nightly CUDA 13.0 wheels built from \`dev\` on $(date +'%Y-%m-%d').
+
+          \`\`\`
+          uv pip install lmcache --pre \\
+            --extra-index-url https://download.pytorch.org/whl/cu130 \\
+            --find-links https://github.com/${{ github.repository }}/releases/expanded_assets/nightly \\
+            --index-strategy unsafe-best-match
+          \`\`\`" \
+            --prerelease \
+            dist/cu130/*.whl
+
+      - name: Build cu12.9 nightly wheel
+        env:
+          CIBW_MANYLINUX_X86_64_IMAGE: docker.io/pytorch/manylinux2_28-builder:cuda12.9
+          CIBW_ENVIRONMENT: 'TORCH_CUDA_ARCH_LIST="7.0;7.5;8.0;8.6;8.9;9.0;10.0" ENABLE_CXX11_ABI=1 LMCACHE_CUDA_MAJOR=12 PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cu129'
+          CIBW_REPAIR_WHEEL_COMMAND_LINUX: >-
+            auditwheel repair
+            --plat manylinux_2_28_x86_64
+            --exclude libtorch.so
+            --exclude libtorch_cuda.so
+            --exclude libtorch_python.so
+            --exclude libtorch_cpu.so
+            --exclude libc10.so
+            --exclude libc10_cuda.so
+            --exclude libcudart.so.12
+            -w {dest_dir} {wheel}
+          CIBW_TEST_COMMAND: "python -c 'import lmcache.c_ops'"
+        run: |
+          python -m cibuildwheel --output-dir dist/cu129
+
+      - name: Publish cu12.9 wheels to rolling nightly-cu129 release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          gh release delete nightly-cu129 --yes --cleanup-tag --repo ${{ github.repository }} 2>/dev/null || true
+          gh release create nightly-cu129 \
+            --repo ${{ github.repository }} \
+            --title "Nightly $(date +'%Y-%m-%d') · CUDA 12.9" \
+            --notes "Nightly CUDA 12.9 wheels built from \`dev\` on $(date +'%Y-%m-%d').
+
+          \`\`\`
+          uv pip install lmcache --pre \\
+            --extra-index-url https://download.pytorch.org/whl/cu129 \\
+            --find-links https://github.com/${{ github.repository }}/releases/expanded_assets/nightly-cu129 \\
+            --index-strategy unsafe-best-match
+          \`\`\`" \
+            --prerelease \
+            dist/cu129/*.whl
+
+  nightly-build:
+    name: Build image
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+            disable-sudo-and-containers: false
+            egress-policy: audit
+
+      - name: Login to DockerHub
+        if: vars.DOCKERHUB_USERNAME != ''
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          # for setuptools-scm
+          fetch-depth: 0
+
+      - name: Remove non-release tags
+        run: git tag -l | grep -vE '^v[0-9]+\.[0-9]+\.[0-9]+$' | xargs -r git tag -d
+
+      - name: Free disk space
+        uses: ./.github/actions/free-disk-space
+
+      - name: Setup Python 3.13
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: "3.13"
+
+      - name: Get the current date
+        run: |
+          echo "NOW=$(date +'%Y-%m-%d')" >> "$GITHUB_ENV"
+
+      - name: Build lmcache/vllm-openai container image (cu13 nightly)
+        run: |
+          docker system prune -f --all
+          docker builder prune -af
+          docker build \
+          --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.09-cuda13.0-devel-ubuntu24.04 \
+          --build-arg CUDA_VERSION=13.0 \
+          --build-arg torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX' \
+          --target image-build \
+          --tag lmcache/vllm-openai:latest-nightly --tag lmcache/vllm-openai:nightly-${{ env.NOW }} \
+          --file docker/Dockerfile .
+
+      - name: Push lmcache/vllm-openai container image to DockerHub
+        run: |
+          docker push lmcache/vllm-openai:latest-nightly
+          docker push lmcache/vllm-openai:nightly-${{ env.NOW }}
+
+      - name: Build lmcache/standalone container image (cu13 nightly)
+        run: |
+          docker system prune -f --all
+          docker builder prune -af
+          docker build \
+          --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.09-cuda13.0-devel-ubuntu24.04 \
+          --build-arg CUDA_VERSION=13.0 \
+          --build-arg torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX' \
+          --target lmcache-final \
+          --tag lmcache/standalone:nightly --tag lmcache/standalone:nightly-${{ env.NOW }} \
+          --file docker/Dockerfile.standalone .
+
+      - name: Push lmcache/standalone container image to DockerHub
+        run: |
+          docker push lmcache/standalone:nightly
+          docker push lmcache/standalone:nightly-${{ env.NOW }}
+
+      - name: Build lmcache/vllm-openai container image (cu12.9 nightly)
+        run: |
+          docker system prune -f --all
+          docker builder prune -af
+          docker build \
+          --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.05-cuda12.9-devel-ubuntu24.04 \
+          --build-arg CUDA_VERSION=12.9 --build-arg UBUNTU_VERSION=24.04 \
+          --target image-build \
+          --tag lmcache/vllm-openai:latest-nightly-cu129 --tag lmcache/vllm-openai:nightly-${{ env.NOW }}-cu129 \
+          --file docker/Dockerfile .
+
+      - name: Push lmcache/vllm-openai cu12.9 nightly image to DockerHub
+        run: |
+          docker push lmcache/vllm-openai:latest-nightly-cu129
+          docker push lmcache/vllm-openai:nightly-${{ env.NOW }}-cu129
+
+      - name: Build lmcache/standalone container image (cu12.9 nightly)
+        run: |
+          docker system prune -f --all
+          docker builder prune -af
+          docker build \
+          --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.05-cuda12.9-devel-ubuntu24.04 \
+          --build-arg CUDA_VERSION=12.9 --build-arg UBUNTU_VERSION=24.04 \
+          --target lmcache-final \
+          --tag lmcache/standalone:nightly-cu129 --tag lmcache/standalone:nightly-${{ env.NOW }}-cu129 \
+          --file docker/Dockerfile.standalone .
+
+      - name: Push lmcache/standalone cu12.9 nightly image to DockerHub
+        run: |
+          docker push lmcache/standalone:nightly-cu129
+          docker push lmcache/standalone:nightly-${{ env.NOW }}-cu129
diff --git a/.github/workflows/operator_ci.yml b/.github/workflows/operator_ci.yml
new file mode 100644
index 0000000..1b919c5
--- /dev/null
+++ b/.github/workflows/operator_ci.yml
@@ -0,0 +1,76 @@
+name: "Operator: CI"
+
+on:
+  push:
+    branches:
+      - dev
+      - "release-**"
+  pull_request:
+    branches:
+      - dev
+      - "release-**"
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+    working-directory: operator
+
+jobs:
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      operator: ${{ steps.filter.outputs.operator == 'true' }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        if: github.event_name == 'push'
+        with:
+          fetch-depth: 2
+
+      - uses: dorny/paths-filter@v3
+        if: github.event_name == 'push' || github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            operator:
+              - 'operator/**'
+              - '.github/workflows/operator_ci.yml'
+
+  ci:
+    needs: changes
+    if: needs.changes.outputs.operator == 'true'
+    name: Format, lint, and test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: operator/go.mod
+
+      - name: Check formatting
+        run: |
+          test -z "$(gofmt -l .)" || { gofmt -d .; exit 1; }
+
+      - name: Check linter configuration
+        run: make lint-config
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: |
+          go mod tidy
+          make test
diff --git a/.github/workflows/operator_nightly.yml b/.github/workflows/operator_nightly.yml
new file mode 100644
index 0000000..22490ea
--- /dev/null
+++ b/.github/workflows/operator_nightly.yml
@@ -0,0 +1,80 @@
+name: "Operator: Nightly"
+
+on:
+  schedule:
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+
+env:
+  IMAGE_NAME: lmcache/lmcache-operator
+
+permissions:
+  contents: write
+
+defaults:
+  run:
+    shell: bash
+    working-directory: operator
+
+jobs:
+  nightly:
+    name: Build, push, and release nightly
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Compute nightly tag
+        id: tag
+        run: |
+          DATE=$(date -u +%Y-%m-%d)
+          echo "TAG=nightly-${DATE}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          context: operator
+          platforms: linux/amd64
+          push: true
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ steps.tag.outputs.TAG }}
+            ${{ env.IMAGE_NAME }}:nightly
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: operator/go.mod
+
+      - name: Build installer manifest
+        run: make build-installer IMG=${{ env.IMAGE_NAME }}:${{ steps.tag.outputs.TAG }}
+
+      - name: Update nightly release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: operator-nightly-latest
+          name: "Operator Nightly Latest (${{ steps.tag.outputs.TAG }})"
+          prerelease: true
+          make_latest: false
+          body: |
+            Automated nightly operator build from `dev` branch.
+
+            **Image:** `${{ env.IMAGE_NAME }}:${{ steps.tag.outputs.TAG }}`
+
+            ```bash
+            kubectl apply -f https://github.com/${{ github.repository }}/releases/download/operator-nightly-latest/install.yaml
+            ```
+          files: operator/dist/install.yaml
diff --git a/.github/workflows/operator_release.yml b/.github/workflows/operator_release.yml
new file mode 100644
index 0000000..31880af
--- /dev/null
+++ b/.github/workflows/operator_release.yml
@@ -0,0 +1,100 @@
+name: "Operator: Release"
+
+on:
+  release:
+    types: [published]
+
+env:
+  IMAGE_NAME: lmcache/lmcache-operator
+
+permissions:
+  contents: write
+
+defaults:
+  run:
+    shell: bash
+    working-directory: operator
+
+jobs:
+  release:
+    name: Build, push, and release
+    # Filter out main lmcache `v*` releases — only fire for operator-prefixed tags.
+    if: startsWith(github.ref_name, 'operator-v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          # Strip "operator-" prefix from tag to get version (e.g. operator-v0.4.8rc1 -> v0.4.8rc1).
+          VERSION="${GITHUB_REF_NAME#operator-}"
+          echo "VERSION=${VERSION}" >> "$GITHUB_OUTPUT"
+          # Pre-releases (rc/alpha/beta) get the floating ":latest-rc" tag and must
+          # never move the stable ":latest" image tag or the "operator-latest" alias.
+          # Detect from the version string rather than the GitHub "pre-release" flag
+          # so behavior is robust whether or not that box is ticked in the UI.
+          if [[ "${VERSION}" =~ (rc|alpha|beta) ]]; then
+            echo "FLOATING_TAG=latest-rc" >> "$GITHUB_OUTPUT"
+            echo "IS_PRERELEASE=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "FLOATING_TAG=latest" >> "$GITHUB_OUTPUT"
+            echo "IS_PRERELEASE=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build and push image
+        uses: docker/build-push-action@v6
+        with:
+          context: operator
+          platforms: linux/amd64
+          push: true
+          tags: |
+            ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.VERSION }}
+            ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.FLOATING_TAG }}
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: operator/go.mod
+
+      - name: Build installer manifest
+        run: make build-installer IMG=${{ env.IMAGE_NAME }}:${{ steps.version.outputs.VERSION }}
+
+      - name: Attach installer to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: operator/dist/install.yaml
+
+      - name: Update latest release alias
+        # Skip for pre-releases: an rc/alpha/beta must not repoint the stable
+        # "operator-latest" alias (or its install.yaml) at a pre-release build.
+        if: steps.version.outputs.IS_PRERELEASE == 'false'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: operator-latest
+          name: "Operator Latest (${{ steps.version.outputs.VERSION }})"
+          make_latest: false
+          body: |
+            Points to the latest stable operator release: `${{ steps.version.outputs.VERSION }}`
+
+            **Image:** `${{ env.IMAGE_NAME }}:latest`
+
+            ```bash
+            kubectl apply -f https://github.com/${{ github.repository }}/releases/download/operator-latest/install.yaml
+            ```
+          files: operator/dist/install.yaml
diff --git a/.github/workflows/pr_full_build.yml b/.github/workflows/pr_full_build.yml
new file mode 100644
index 0000000..95cd208
--- /dev/null
+++ b/.github/workflows/pr_full_build.yml
@@ -0,0 +1,52 @@
+name: PR Full Build
+
+# Build all release artifacts (sdist + CUDA wheel, CLI wheel, cu129 wheel)
+# on PRs carrying the `full` label. The `full` label is added automatically
+# by automerge-labeler.yml when auto-merge is enabled on a code-change PR,
+# so this acts as a pre-merge sanity check that wheels still build.
+#
+# No tests, no code-quality checks, no publishing — those are covered by
+# test.yml / code_quality_checks.yml (per-PR) and publish.yml (on merge).
+
+on:
+    pull_request:
+        branches:
+            - dev
+            - "release-**"
+        types: [opened, synchronize, reopened, labeled]
+
+# Cancel older in-flight runs on the same PR. github.ref is
+# refs/pull/<N>/merge on pull_request events, so each PR gets its own group.
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    # Each build runs independently — a failure in one does not skip the
+    # others, matching publish.yml's isolation model.
+
+    build-main:
+        name: Build main
+        if: contains(github.event.pull_request.labels.*.name, 'full')
+        uses: ./.github/workflows/build_main_artifacts.yml
+
+    build-cli:
+        name: Build CLI
+        if: contains(github.event.pull_request.labels.*.name, 'full')
+        uses: ./.github/workflows/build_cli_artifacts.yml
+
+    build-cpu:
+        name: Build CPU
+        if: contains(github.event.pull_request.labels.*.name, 'full')
+        uses: ./.github/workflows/build_cpu_artifacts.yml
+
+    build-cu129:
+        name: Build cu129
+        if: contains(github.event.pull_request.labels.*.name, 'full')
+        uses: ./.github/workflows/build_cu129_artifacts.yml
+        # Fork PRs won't expose DOCKERHUB_TOKEN even with `inherit`; the login
+        # step in build_cu129_artifacts.yml guards on the token being non-empty.
+        secrets: inherit
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..b6dd078
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,531 @@
+name: Build and Publish to PyPI
+
+on:
+    # Trigger the workflow on push to the dev and any release branches,
+    # and on release tag pushes / GitHub release publication.
+    # Per-PR verification lives in test.yml, code_quality_checks.yml, and
+    # pr_full_build.yml — this workflow is the release pipeline.
+    push:
+        branches:
+            - dev
+            - "release-**"
+        tags:
+            - "v*"
+    release:
+        types:
+            - published
+
+env:
+    LC_ALL: en_US.UTF-8
+
+# Cancel superseded runs on the same ref, but never abort a tag/release publish.
+concurrency:
+    group: publish-${{ github.ref }}
+    cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') && github.event_name != 'release' }}
+
+defaults:
+    run:
+        shell: bash
+
+permissions:
+    contents: read
+    pull-requests: read
+
+jobs:
+    changes:
+        name: Detect changes
+        runs-on: ubuntu-latest
+        permissions:
+            pull-requests: read
+        outputs:
+            # Skip the whole pipeline for operator releases (tags like `operator-v*`).
+            # operator_release.yml handles those; this workflow is lmcache-only.
+            lmcache: ${{ !startsWith(github.ref_name, 'operator-') && (github.event_name == 'release' || startsWith(github.ref, 'refs/tags/') || steps.filter.outputs.lmcache == 'true') }}
+        steps:
+            - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              if: github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')
+              with:
+                fetch-depth: 2
+
+            - uses: dorny/paths-filter@v3
+              if: github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')
+              id: filter
+              with:
+                filters: |
+                    lmcache:
+                        - '**.py'
+                        - 'pyproject.toml'
+                        - 'pyproject_cli.toml'
+                        - 'requirements/**.txt'
+                        - 'docker/**'
+                        - '.github/workflows/test.yml'
+                        - '.github/workflows/code_quality_checks.yml'
+                        - '.github/workflows/publish.yml'
+                        - '.github/workflows/build_main_artifacts.yml'
+                        - '.github/workflows/build_cli_artifacts.yml'
+                        - '.github/workflows/build_cu129_artifacts.yml'
+                        - '!operator/**'
+
+    # Build each artifact group in its own reusable workflow so that a
+    # failure in one (e.g. cu129) does not block publishing of the others.
+
+    build-main:
+        needs: changes
+        if: needs.changes.outputs.lmcache == 'true'
+        name: Build main
+        uses: ./.github/workflows/build_main_artifacts.yml
+
+    build-cli:
+        needs: changes
+        if: needs.changes.outputs.lmcache == 'true'
+        name: Build CLI
+        uses: ./.github/workflows/build_cli_artifacts.yml
+
+    build-cu129:
+        needs: changes
+        if: needs.changes.outputs.lmcache == 'true'
+        name: Build cu129
+        uses: ./.github/workflows/build_cu129_artifacts.yml
+        # DockerHub creds needed for the cu12.9 manylinux image pull;
+        # reusable workflows do not auto-inherit secrets.
+        secrets: inherit
+
+    # Run tests and code quality checks before publishing
+    test:
+        needs: changes
+        if: needs.changes.outputs.lmcache == 'true'
+        name: Run tests
+        uses: ./.github/workflows/test.yml
+
+    code-quality:
+        needs: changes
+        if: needs.changes.outputs.lmcache == 'true'
+        name: Run code quality checks
+        uses: ./.github/workflows/code_quality_checks.yml
+
+    # Push to Test PyPI when:
+    # - a new GitHub release is published
+    # - a commit lands on dev (PR merged)
+    publish-test-pypi:
+        name: Publish packages to test.pypi.org
+        # Require upstream jobs to have succeeded so a cancelled/skipped build
+        # doesn't trigger a publish that fails on the missing artifact.
+        if: |
+            needs.build-main.result == 'success' &&
+            needs.test.result == 'success' &&
+            needs.code-quality.result == 'success' &&
+            needs.changes.outputs.lmcache == 'true' &&
+            github.repository_owner == 'LMCache' &&
+            github.event_name == 'push' && github.ref == 'refs/heads/dev'
+        permissions:
+            contents: read
+            # see https://docs.pypi.org/trusted-publishers/
+            id-token: write
+        runs-on: ubuntu-latest
+        needs: [changes, build-main, test, code-quality]
+
+        steps:
+            - name: Harden Runner
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Fetch release artifacts
+              uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+              with:
+                  name: release-artifacts
+                  path: dist
+
+            - name: Upload to Test PyPI
+              uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+              with:
+                  repository-url: https://test.pypi.org/legacy/
+                  verbose: true
+
+    publish-cli-test-pypi:
+        name: Publish lmcache-cli packages to test.pypi.org
+        if: |
+            needs.build-cli.result == 'success' &&
+            needs.test.result == 'success' &&
+            needs.code-quality.result == 'success' &&
+            needs.changes.outputs.lmcache == 'true' &&
+            github.repository_owner == 'LMCache' &&
+            github.event_name == 'push' && github.ref == 'refs/heads/dev'
+        permissions:
+            contents: read
+            id-token: write
+        runs-on: ubuntu-latest
+        needs: [changes, build-cli, test, code-quality]
+
+        steps:
+            - name: Harden Runner
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Fetch CLI release artifacts
+              uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+              with:
+                  name: release-cli-artifacts
+                  path: dist
+
+            - name: Upload lmcache-cli to Test PyPI
+              uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+              with:
+                  repository-url: https://test.pypi.org/legacy/
+                  verbose: true
+
+    # Push to PyPI (production) when:
+    # - a new GitHub release is created
+    publish-pypi:
+        name: Publish release to pypi.org
+        if: |
+            needs.build-main.result == 'success' &&
+            needs.test.result == 'success' &&
+            needs.code-quality.result == 'success' &&
+            needs.changes.outputs.lmcache == 'true' &&
+            github.repository_owner == 'LMCache' && github.event.action == 'published'
+        permissions:
+            # see https://docs.pypi.org/trusted-publishers/
+            id-token: write
+            # allow gh release upload
+            contents: write
+
+        runs-on: ubuntu-latest
+        needs: [changes, build-main, test, code-quality]
+
+        steps:
+            - name: Harden Runner
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                  disable-sudo-and-containers: false
+                  egress-policy: audit
+
+            - name: Fetch release artifacts
+              uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+              with:
+                  name: release-artifacts
+                  path: dist
+
+            - name: Upload release artifacts to GitHub release
+              env:
+                  GITHUB_TOKEN: ${{ github.token }}
+              run: >-
+                  gh release upload '${{ github.ref_name }}' dist/* --repo '${{ github.repository }}'
+
+            - name: Upload to PyPI
+              uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+              with:
+                verbose: true
+
+    publish-cli-pypi:
+        name: Publish lmcache-cli release to pypi.org
+        if: |
+            needs.build-cli.result == 'success' &&
+            needs.test.result == 'success' &&
+            needs.code-quality.result == 'success' &&
+            needs.changes.outputs.lmcache == 'true' &&
+            github.repository_owner == 'LMCache' && github.event.action == 'published'
+        permissions:
+            id-token: write
+            contents: write
+        runs-on: ubuntu-latest
+        needs: [changes, build-cli, test, code-quality]
+
+        steps:
+            - name: Harden Runner
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                  disable-sudo-and-containers: false
+                  egress-policy: audit
+
+            - name: Fetch CLI release artifacts
+              uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+              with:
+                  name: release-cli-artifacts
+                  path: dist
+
+            - name: Upload lmcache-cli release artifacts to GitHub release
+              env:
+                  GITHUB_TOKEN: ${{ github.token }}
+              run: >-
+                  gh release upload '${{ github.ref_name }}' dist/* --repo '${{ github.repository }}'
+
+            - name: Upload lmcache-cli to PyPI
+              uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+              with:
+                verbose: true
+
+    # Publish cu12.9 wheel to GitHub Release (not PyPI) when a release is published
+    publish-cu129-github-release:
+        name: Publish cu129 wheel to GitHub Release
+        if: |
+            needs.build-cu129.result == 'success' &&
+            needs.test.result == 'success' &&
+            needs.code-quality.result == 'success' &&
+            needs.changes.outputs.lmcache == 'true' &&
+            github.repository_owner == 'LMCache' && github.event.action == 'published'
+        permissions:
+            contents: write
+        runs-on: ubuntu-latest
+        needs: [changes, build-cu129, test, code-quality]
+
+        steps:
+            - name: Harden Runner
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                  disable-sudo-and-containers: false
+                  egress-policy: audit
+
+            - name: Fetch cu12.9 release artifacts
+              uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+              with:
+                  name: release-cu129-artifacts
+                  path: dist
+
+            - name: Publish cu12.9 wheel to dedicated GitHub Release
+              env:
+                  GITHUB_TOKEN: ${{ github.token }}
+              run: |
+                  gh release create "${{ github.ref_name }}-cu129" \
+                    --repo ${{ github.repository }} \
+                    --latest=false \
+                    --title "Release ${{ github.ref_name }} · CUDA 12.9" \
+                    --notes "CUDA 12.9 wheel for LMCache ${{ github.ref_name }}.
+
+                  \`\`\`
+                  VERSION=${{ github.ref_name }}
+                  uv pip install lmcache==${VERSION#v} \\
+                    --extra-index-url https://download.pytorch.org/whl/cu129 \\
+                    --find-links https://github.com/${{ github.repository }}/releases/expanded_assets/${VERSION}-cu129 \\
+                    --index-strategy unsafe-best-match
+                  \`\`\`" \
+                    dist/*.whl
+
+    # Build container image and push to DockerHub when:
+    # - a new stable GitHub release is created (non-RC)
+    publish-image:
+        name: Publish image to DockerHub
+        if: |
+            needs.publish-pypi.result == 'success' &&
+            !cancelled() &&
+            github.repository_owner == 'LMCache' && github.event.action == 'published' &&
+            !contains(github.ref_name, 'rc')
+
+        runs-on: ubuntu-latest
+        needs: [publish-pypi, publish-cu129-github-release]
+
+        steps:
+            - name: "Harden Runner"
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Login to DockerHub
+              uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+              with:
+                username: ${{ vars.DOCKERHUB_USERNAME }}
+                password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+            - name: Checkout code
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              with:
+                # for setuptools-scm
+                fetch-depth: 0
+
+            - name: Free disk space
+              uses: ./.github/actions/free-disk-space
+
+            - name: Resolve the release tag that triggered this run
+              run: |
+                echo "LATEST_TAG=${{ github.ref_name }}" >> "$GITHUB_ENV"
+
+            - name: Build lmcache/vllm-openai container image (cu13)
+              run: |
+                docker build \
+                --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.09-cuda13.0-devel-ubuntu24.04 \
+                --build-arg CUDA_VERSION=13.0 \
+                --build-arg LMCACHE_VERSION=${{ env.LATEST_TAG }} \
+                --build-arg torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX' \
+                --target image-release \
+                --tag lmcache/vllm-openai:latest --tag lmcache/vllm-openai:${{ env.LATEST_TAG }} \
+                --file docker/Dockerfile .
+
+            # `lmcache --help` exercises eager CLI subcommand discovery,
+            # so a missing runtime dep fails the build before the image ships.
+            - name: Smoke test lmcache/vllm-openai (cu13)
+              run: |
+                docker run --rm --entrypoint lmcache lmcache/vllm-openai:${{ env.LATEST_TAG }} --help
+
+            - name: Push lmcache/vllm-openai container image to DockerHub
+              run: |
+                docker push lmcache/vllm-openai:latest
+                docker push lmcache/vllm-openai:${{ env.LATEST_TAG }}
+
+            - name: Clean up Docker layers and cache
+              run: |
+                docker system prune -f --all
+                docker builder prune -af
+
+            - name: Build lmcache/vllm-openai:lightweight
+              run: |
+                docker build \
+                --tag lmcache/vllm-openai:lightweight --tag lmcache/vllm-openai:${{ env.LATEST_TAG }}-lightweight \
+                --file docker/Dockerfile.lightweight .
+
+            - name: Smoke test lmcache/vllm-openai:lightweight
+              run: |
+                docker run --rm --entrypoint lmcache lmcache/vllm-openai:${{ env.LATEST_TAG }}-lightweight --help
+
+            - name: Push lmcache/vllm-openai:lightweight image to DockerHub
+              run: |
+                docker push lmcache/vllm-openai:lightweight
+                docker push lmcache/vllm-openai:${{ env.LATEST_TAG }}-lightweight
+
+            - name: Clean up Docker layers and cache
+              run: |
+                docker system prune -f --all
+                docker builder prune -af
+
+            - name: Build lmcache/standalone container image (cu13)
+              run: |
+                docker build \
+                --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.09-cuda13.0-devel-ubuntu24.04 \
+                --build-arg CUDA_VERSION=13.0 \
+                --build-arg torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX' \
+                --target lmcache-final \
+                --tag lmcache/standalone:latest --tag lmcache/standalone:${{ env.LATEST_TAG }} \
+                --tag lmcache/standalone:latest-cu130 --tag lmcache/standalone:${{ env.LATEST_TAG }}-cu130 \
+                --file docker/Dockerfile.standalone .
+
+            - name: Smoke test lmcache/standalone (cu13)
+              run: |
+                docker run --rm --entrypoint lmcache lmcache/standalone:${{ env.LATEST_TAG }} --help
+
+            - name: Push lmcache/standalone container image to DockerHub
+              run: |
+                docker push lmcache/standalone:latest
+                docker push lmcache/standalone:${{ env.LATEST_TAG }}
+                docker push lmcache/standalone:latest-cu130
+                docker push lmcache/standalone:${{ env.LATEST_TAG }}-cu130
+
+            - name: Clean up Docker layers and cache
+              run: |
+                docker system prune -f --all
+                docker builder prune -af
+
+            - name: Build lmcache/vllm-openai container image (cu12.9)
+              if: needs.publish-cu129-github-release.result == 'success'
+              run: |
+                docker build \
+                --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.05-cuda12.9-devel-ubuntu24.04 \
+                --build-arg CUDA_VERSION=12.9 \
+                --build-arg LMCACHE_VERSION=${{ env.LATEST_TAG }} \
+                --target image-release-cu129 \
+                --tag lmcache/vllm-openai:latest-cu129 --tag lmcache/vllm-openai:${{ env.LATEST_TAG }}-cu129 \
+                --file docker/Dockerfile .
+
+            - name: Smoke test lmcache/vllm-openai (cu12.9)
+              if: needs.publish-cu129-github-release.result == 'success'
+              run: |
+                docker run --rm --entrypoint lmcache lmcache/vllm-openai:${{ env.LATEST_TAG }}-cu129 --help
+
+            - name: Push lmcache/vllm-openai cu129 container image to DockerHub
+              if: needs.publish-cu129-github-release.result == 'success'
+              run: |
+                docker push lmcache/vllm-openai:latest-cu129
+                docker push lmcache/vllm-openai:${{ env.LATEST_TAG }}-cu129
+
+            - name: Clean up Docker layers and cache
+              run: |
+                docker system prune -f --all
+                docker builder prune -af
+
+            - name: Build lmcache/standalone container image (cu12.9)
+              if: needs.publish-cu129-github-release.result == 'success'
+              run: |
+                docker build \
+                --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.05-cuda12.9-devel-ubuntu24.04 \
+                --build-arg CUDA_VERSION=12.9 \
+                --target lmcache-final \
+                --tag lmcache/standalone:latest-cu129 --tag lmcache/standalone:${{ env.LATEST_TAG }}-cu129 \
+                --file docker/Dockerfile.standalone .
+
+            - name: Smoke test lmcache/standalone (cu12.9)
+              if: needs.publish-cu129-github-release.result == 'success'
+              run: |
+                docker run --rm --entrypoint lmcache lmcache/standalone:${{ env.LATEST_TAG }}-cu129 --help
+
+            - name: Push lmcache/standalone cu129 container image to DockerHub
+              if: needs.publish-cu129-github-release.result == 'success'
+              run: |
+                docker push lmcache/standalone:latest-cu129
+                docker push lmcache/standalone:${{ env.LATEST_TAG }}-cu129
+
+    # Build RC container image and push to DockerHub when:
+    # - a new RC GitHub release is created (e.g. v0.4.8rc1)
+    # Only pushes lmcache/vllm-openai:<tag> — does not touch latest or other image variants.
+    publish-image-rc:
+        name: Publish RC image to DockerHub
+        if: |
+            needs.publish-pypi.result == 'success' &&
+            !cancelled() &&
+            github.repository_owner == 'LMCache' && github.event.action == 'published' &&
+            contains(github.ref_name, 'rc')
+
+        runs-on: ubuntu-latest
+        needs: [publish-pypi]
+
+        steps:
+            - name: "Harden Runner"
+              uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+              with:
+                disable-sudo-and-containers: false
+                egress-policy: audit
+
+            - name: Login to DockerHub
+              uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+              with:
+                username: ${{ vars.DOCKERHUB_USERNAME }}
+                password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+            - name: Checkout code
+              uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+              with:
+                fetch-depth: 0
+
+            - name: Free disk space
+              uses: ./.github/actions/free-disk-space
+
+            - name: Get the release tag
+              run: |
+                REF="${{ github.ref_name }}"
+                [[ "$REF" =~ ^v[0-9]+\.[0-9]+\.[0-9]+rc[0-9]+$ ]] && echo "LATEST_RC_TAG=$REF" >> "$GITHUB_ENV"
+
+            - name: Build lmcache/vllm-openai container image (cu13)
+              run: |
+                docker build \
+                --build-arg BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:25.09-cuda13.0-devel-ubuntu24.04 \
+                --build-arg CUDA_VERSION=13.0 \
+                --build-arg LMCACHE_VERSION=${{ env.LATEST_RC_TAG }} \
+                --build-arg torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX' \
+                --target image-release \
+                --tag lmcache/vllm-openai:${{ env.LATEST_RC_TAG }} \
+                --file docker/Dockerfile .
+
+            - name: Smoke test lmcache/vllm-openai (cu13)
+              run: |
+                docker run --rm --entrypoint lmcache lmcache/vllm-openai:${{ env.LATEST_RC_TAG }} --help
+
+            - name: Push lmcache/vllm-openai RC image to DockerHub
+              run: |
+                docker push lmcache/vllm-openai:${{ env.LATEST_RC_TAG }}
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
new file mode 100644
index 0000000..0c61cd5
--- /dev/null
+++ b/.github/workflows/scorecard.yml
@@ -0,0 +1,84 @@
+# This workflow uses actions that are not certified by GitHub. They are provided
+# by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '23 8 * * 6'
+  push:
+    branches: [ "dev" ]
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    # `publish_results: true` only works when run from the default branch. conditional can be removed if disabled.
+    if: github.event.repository.default_branch == github.ref_name || github.event_name == 'pull_request'
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+      # Uncomment the permissions below if installing in a private repository.
+      # contents: read
+      # actions: read
+
+    steps:
+      - name: "Harden Runner"
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          disable-sudo-and-containers: false
+          egress-policy: audit
+
+      - name: "Checkout code"
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
+          # - you want to enable the Branch-Protection check on a *public* repository, or
+          # - you are installing Scorecard on a *private* repository
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
+          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          # For private repositories:
+          #   - `publish_results` will always be set to `false`, regardless
+          #     of the value entered here.
+          publish_results: true
+
+          # (Optional) Uncomment file_mode if you have a .gitattributes with files marked export-ignore
+          # file_mode: git
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: results.sarif
diff --git a/.github/workflows/stale_bot.yml b/.github/workflows/stale_bot.yml
new file mode 100644
index 0000000..64e0ec3
--- /dev/null
+++ b/.github/workflows/stale_bot.yml
@@ -0,0 +1,51 @@
+name: 'Close stale issues and PRs'
+
+on:
+  schedule:
+    - cron: '30 1 * * *'
+
+env:
+  LC_ALL: en_US.UTF-8
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+
+jobs:
+  stale:
+    permissions:
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Harden Runner"
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          disable-sudo-and-containers: true
+          egress-policy: audit
+
+      - name: "Stale Action"
+        uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+        with:
+          stale-issue-label: 'stale'
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not had activity within 60 days.
+            It will be automatically closed if no further activity occurs within 30 days.
+          close-issue-message: >
+            This issue has been automatically closed due to inactivity.
+            Please feel free to reopen if you feel it is still relevant!
+          days-before-issue-stale: 60
+          days-before-issue-close: 30
+          stale-pr-label: 'stale'
+          stale-pr-message: >
+            This pull request has been automatically marked as stale because it has not had activity within 60 days.
+            It will be automatically closed if no further activity occurs within 30 days.
+          close-pr-message: >
+            This pull request has been automatically closed due to inactivity.
+            Please feel free to reopen if you intend to continue working on it!
+          days-before-pr-stale: 60
+          days-before-pr-close: 30
+          operations-per-run: 300
diff --git a/.github/workflows/sync_torch_version.yml b/.github/workflows/sync_torch_version.yml
new file mode 100644
index 0000000..0bcc182
--- /dev/null
+++ b/.github/workflows/sync_torch_version.yml
@@ -0,0 +1,147 @@
+name: Sync Torch Version
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 2 * * 1"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: sync-torch-version
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    name: Sync torch pin with vLLM
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out dev branch
+        uses: actions/checkout@v4
+        with:
+          ref: dev
+          token: ${{ github.token }}
+          fetch-depth: 0
+
+      - name: Sync torch version with vLLM
+        id: sync
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+
+          readonly UPSTREAM_URL="https://raw.githubusercontent.com/vllm-project/vllm/main/pyproject.toml"
+          readonly TARGET_FILE="pyproject.toml"
+
+          tmp_upstream="$(mktemp)"
+          tmp_output="$(mktemp)"
+
+          cleanup() {
+            rm -f "$tmp_upstream" "$tmp_output"
+          }
+          trap cleanup EXIT
+
+          echo "Fetching upstream pyproject.toml from vLLM..."
+          curl \
+            --fail \
+            --show-error \
+            --silent \
+            --location \
+            --retry 3 \
+            --retry-delay 2 \
+            --connect-timeout 10 \
+            "$UPSTREAM_URL" \
+            -o "$tmp_upstream"
+
+          extract_torch_version() {
+            local file="$1"
+            sed -nE 's/.*torch[[:space:]]*==[[:space:]]*([0-9]+(\.[0-9]+){1,2}).*/\1/p' "$file"
+          }
+
+          mapfile -t upstream_matches < <(extract_torch_version "$tmp_upstream")
+          mapfile -t current_matches < <(extract_torch_version "$TARGET_FILE")
+
+          if [[ "${#upstream_matches[@]}" -ne 1 ]]; then
+            echo "Expected exactly one torch pin in upstream file, found ${#upstream_matches[@]}"
+            printf 'Matches: %s\n' "${upstream_matches[@]:-<none>}"
+            exit 1
+          fi
+
+          if [[ "${#current_matches[@]}" -ne 1 ]]; then
+            echo "Expected exactly one torch pin in ${TARGET_FILE}, found ${#current_matches[@]}"
+            printf 'Matches: %s\n' "${current_matches[@]:-<none>}"
+            exit 1
+          fi
+
+          upstream="${upstream_matches[0]}"
+          current="${current_matches[0]}"
+
+          echo "Current torch version : $current"
+          echo "Upstream torch version: $upstream"
+
+          {
+            echo "current=$current"
+            echo "upstream=$upstream"
+          } >> "$GITHUB_OUTPUT"
+
+          if [[ "$upstream" == "$current" ]]; then
+            echo "Torch version already up to date."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          awk -v new_ver="$upstream" '
+            BEGIN { updated = 0 }
+            {
+              if ($0 ~ /torch[[:space:]]*==[[:space:]]*[0-9]+(\.[0-9]+){1,2}/) {
+                sub(/torch[[:space:]]*==[[:space:]]*[0-9]+(\.[0-9]+){1,2}/, "torch==" new_ver)
+                updated++
+              }
+              print
+            }
+            END {
+              if (updated != 1) {
+                printf("Expected to update exactly one torch pin, updated %d\n", updated) > "/dev/stderr"
+                exit 1
+              }
+            }
+          ' "$TARGET_FILE" > "$tmp_output"
+
+          mv "$tmp_output" "$TARGET_FILE"
+
+          if git diff --quiet -- "$TARGET_FILE"; then
+            echo "No file change detected after update."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Create pull request
+        if: steps.sync.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ github.token }}
+          branch: automation/sync-torch-version
+          base: dev
+          delete-branch: true
+          signoff: true
+          add-paths: |
+            pyproject.toml
+          commit-message: "[Build] sync torch version with vLLM (${{
+            steps.sync.outputs.upstream }})"
+          title: "[Build] sync torch version with vLLM (${{
+            steps.sync.outputs.upstream }})"
+          body: |
+            Auto-sync the pinned torch version in `pyproject.toml` with vLLM.
+
+            - Current: `${{ steps.sync.outputs.current }}`
+            - Upstream: `${{ steps.sync.outputs.upstream }}`
+
+            This PR was generated automatically by GitHub Actions.
+          labels: |
+            dependencies
+            automation
\ No newline at end of file
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..b2a2dc5
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,170 @@
+name: Test
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - "dev"
+      - "release-**"
+
+env:
+  LC_ALL: en_US.UTF-8
+  PYTHONHASHSEED: 0
+
+defaults:
+  run:
+    shell: bash
+
+# Cancel older in-flight runs on the same PR / branch.
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      lmcache: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'release' || steps.filter.outputs.lmcache == 'true' }}
+      raw_block: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'release' || steps.filter.outputs.raw_block == 'true' }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        if: github.event_name == 'push'
+        with:
+          fetch-depth: 2
+
+      - uses: dorny/paths-filter@v3
+        if: github.event_name == 'push' || github.event_name == 'pull_request'
+        id: filter
+        with:
+          filters: |
+            lmcache:
+              - '**.py'
+              - 'pyproject.toml'
+              - 'requirements/**.txt'
+              - '.github/workflows/test.yml'
+              - '!operator/**'
+            raw_block:
+              - 'rust/raw_block/**'
+              - 'lmcache/v1/storage_backend/raw_block/**'
+              - 'lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py'
+              - 'lmcache/v1/multiprocess/**'
+              - 'tests/v1/storage_backend/test_raw_block*.py'
+              - 'tests/v1/storage_backend/raw_block_test_utils.py'
+              - 'tests/v1/multiprocess/test_raw_block_l2_adapter.py'
+              - '.github/workflows/test.yml'
+
+  test:
+    needs: changes
+    if: needs.changes.outputs.lmcache == 'true'
+    name: "test: ${{ matrix.python }} on ${{ matrix.platform }}"
+    runs-on: "${{ matrix.platform }}"
+    strategy:
+      matrix:
+        python:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+        platform:
+          - "ubuntu-latest"
+
+    steps:
+      - name: "Harden Runner"
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          # https://github.com/actions/checkout/issues/249
+          fetch-depth: 0
+
+      - name: Free disk space
+        uses: ./.github/actions/free-disk-space
+  
+      - name: Setup Python ${{ matrix.python }}
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: |
+            **/pyproject.toml
+            **/requirements/*.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install vllm
+          python -m pip install -r requirements/test.txt
+          python -m pip install -r requirements/common.txt
+
+      - name: "Run non-CUDA unit tests"
+        run: |
+          pytest --ignore=tests/disagg \
+            --ignore=tests/v1/multiprocess/ \
+            --ignore=tests/v1/distributed/ \
+            --ignore=tests/v1/mp_observability/ \
+            --ignore=tests/skipped \
+            --ignore=tests/cli/commands/trace \
+            --ignore=tests/v1/storage_backend/test_eic.py \
+            --ignore=tests/v1/storage_backend/test_p2p_backend_with_controller.py
+
+  raw-block-tests:
+    needs: changes
+    if: needs.changes.outputs.raw_block == 'true'
+    name: raw-block temp-file tests
+    runs-on: ubuntu-latest
+    env:
+      LMCACHE_LOG_LEVEL: CRITICAL
+
+    steps:
+      - name: "Harden Runner"
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
+
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: |
+            **/pyproject.toml
+            **/requirements/*.txt
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install maturin
+          python -m pip install -r requirements/test.txt
+          python -m pip install -r requirements/common.txt
+
+      - name: Build raw-block Rust extension
+        run: |
+          python -m maturin build --release \
+            --manifest-path rust/raw_block/Cargo.toml \
+            --out .pytest-tmp/raw-block-dist
+          python -m pip install .pytest-tmp/raw-block-dist/*.whl
+
+      - name: Run raw-block tests
+        run: |
+          pytest -q --basetemp=.pytest-tmp/raw-block \
+            tests/v1/storage_backend/test_raw_block_device.py \
+            tests/v1/storage_backend/test_raw_block_core.py \
+            tests/v1/multiprocess/test_raw_block_l2_adapter.py
diff --git a/.github/workflows/translate_doc_zh.yml b/.github/workflows/translate_doc_zh.yml
new file mode 100644
index 0000000..22197c1
--- /dev/null
+++ b/.github/workflows/translate_doc_zh.yml
@@ -0,0 +1,109 @@
+name: Update Chinese Documentation Translations
+
+on:
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+    inputs:
+      max_entries:
+        description: "Maximum entries to translate in this run"
+        required: false
+        default: "50"
+
+concurrency:
+    group: update-chinese-docs
+    cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  translate-docs:
+    name: Update Chinese docs translations
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout code
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          ref: dev
+
+      - name: Setup Python 3.13
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: "3.13"
+
+      - name: Install Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements/docs.txt
+
+      - name: Reuse translations from open PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Reuse the automation branch only while its PR is open; a closed PR's
+          # branch is stale and would overwrite human edits merged to dev.
+          open_prs=$(gh pr list --repo "$GITHUB_REPOSITORY" \
+            --head automation/update-chinese-docs --state open \
+            --json number --jq 'length' || echo 0)
+          if [ "${open_prs:-0}" -gt 0 ] && \
+             git fetch origin automation/update-chinese-docs 2>/dev/null; then
+            echo "Open translation PR found; reusing its translations."
+            git checkout FETCH_HEAD -- docs/source/locale/zh_CN/LC_MESSAGES/ || true
+          else
+            echo "No open translation PR; using dev as the translation base."
+          fi
+
+      - name: Update gettext catalogs
+        run: |
+          sphinx-build -b gettext docs/source docs/build/gettext
+          sphinx-intl update -p docs/build/gettext -l zh_CN -d docs/source/locale -j 1
+
+      - name: Delete translations for renamed or removed docs
+        run: |
+          find docs/source/locale/zh_CN/LC_MESSAGES -name '*.po' | while read -r po; do
+            rel="${po#docs/source/locale/zh_CN/LC_MESSAGES/}"
+            if [ ! -f "docs/build/gettext/${rel%.po}.pot" ]; then
+              echo "deleting $po (no matching source doc)"
+              git rm -fq --ignore-unmatch "$po"
+            fi
+          done
+
+      - name: Translate missing Chinese entries
+        env:
+          TRANSLATION_API_BASE_URL: ${{ secrets.TRANSLATION_API_BASE_URL }}
+          TRANSLATION_API_KEY: ${{ secrets.TRANSLATION_API_KEY }}
+          TRANSLATION_MODEL: ${{ secrets.TRANSLATION_MODEL }}
+          TRANSLATION_MAX_ENTRIES: ${{ inputs.max_entries || '500' }}
+        run: |
+          python tools/translate_docs_zh.py
+
+      - name: Validate Chinese docs build
+        run: |
+          SPHINX_LANGUAGE=zh_CN sphinx-build -b html docs/source docs/build/html/zh_CN
+
+      - name: Open or update translation PR
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ github.token }}
+          branch: automation/update-chinese-docs
+          base: dev
+          delete-branch: true
+          signoff: true
+          add-paths: |
+            docs/source/locale/zh_CN/LC_MESSAGES
+          commit-message: "Update Chinese documentation translations"
+          title: "Update Chinese documentation translations"
+          body: |
+            Automated weekly update for Chinese documentation translations.
+
+            Generated by `.github/workflows/translate_doc_zh.yml`.
+          labels: |
+            documentation
+            automation
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..9c29768
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,153 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Optional native backend build artifacts (scripts/build_libaerospike.sh)
+.deps/
+.aerospike-ci.env
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+durations/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Vim temporary files
+.*.sw*
+
+# misc
+outdated/
+perf-test.py
+*.prof
+*.so
+.ycm_extra_conf.py
+
+# temp tests
+lmcache/experimental/tests
+
+# example
+/examples/example_local.yaml
+/examples/openai_chat_completion_client_local.py
+/lmcache/experimental/examples
+/examples/debug
+/examples/p2p/bash.sh
+
+# example output
+*/offline_inference_outputs.jsonl
+/examples/offline_inference/offline_inference_outputs.jsonl
+/examples/save_decode_cache/offline_inference_outputs.jsonl
+/examples/offline_inference/buggy_example.py
+/examples/test_example
+
+# benchmark results
+*.csv
+
+# disk cache
+/remote_disk
+/local_disk
+/tests/local_disk
+/tests/remote_disk
+*.pt
+
+# random scripts
+/misc_scripts
+
+# nvtx profile report
+*.nsys-rep
+*.sqlite
+
+# docs/build
+/docs/build/
+/docs/build.sh
+/docs/output/
+
+/try
+
+# reference kernels
+/csrc/temp.cu
+
+# PyCharm
+.idea/
+
+# VSCode
+.vscode/
+
+# Setuptools scm version
+/lmcache/_version.py
+
+# Generated hip files
+/csrc_hip
+/csrc/*.hip
+/csrc/*_hip.cuh
+/csrc/*_hip.cpp
+/csrc/*_hip.h
+
+# SYCL build artifacts
+/build_sycl/
+
+# Ignore all log files
+*.log
+
+# uv
+uv.lock
+
+# Coding agent instructions
+GEMINI.md
+COPILOT.md
+CURSOR.md
+AIDER.md
+
+# Operator build artifacts
+operator/bin/
+operator/dist/
+operator/cover.out
+operator/coverage.html
+operator/Dockerfile.cross
+*.spv
+
+# Compiled gettext catalogs (built from .po at HTML build time)
+docs/source/locale/**/*.mo
diff --git a/.isort.cfg b/.isort.cfg
new file mode 100644
index 0000000..630eff1
--- /dev/null
+++ b/.isort.cfg
@@ -0,0 +1,11 @@
+[settings]
+profile=black
+from_first=true
+import_heading_future=Future
+import_heading_stdlib=Standard
+import_heading_thirdparty=Third Party
+import_heading_firstparty=First Party
+import_heading_localfolder=Local
+known_firstparty=
+known_localfolder=tuning
+extend_skip=lmcache/_version.py
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..d2650da
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,133 @@
+exclude: 'lmcache/integration/vllm/lmcache_mp_connector_.*\.py'
+repos:
+- repo: local
+  hooks:
+  - id: check-spdx-header
+    name: Check SPDX headers
+    entry: python tools/check_spdx_header.py
+    language: python
+    types: [python]
+  - id: ban-direct-torch-device
+    name: Ban direct torch device usage
+    entry: >-
+      bash -c '
+      pattern=$(find lmcache/v1/platform -mindepth 1 -maxdepth 1 -type d \
+        -exec basename {} \; | grep -v "^__" | grep -v "^base$" | sort | paste -sd "|");
+      if [ -z "$pattern" ]; then
+        echo "WARNING: no platform dirs found, skipping check";
+        exit 0;
+      fi;
+      echo "Detected platforms: ${pattern//|/, }";
+      echo "Ban pattern: torch.($pattern)";
+      matches=$(grep -rHnE "torch\.($pattern)" "$@");
+      if [ -n "$matches" ]; then
+        echo "";
+        echo "========================================";
+        echo "  BANNED: Direct torch device API usage";
+        echo "  Use lmcache.v1.platform abstractions instead";
+        echo "========================================";
+        echo "";
+        echo "$matches";
+        exit 1;
+      fi' --
+    language: system
+    types: [python]
+    files: ^lmcache/
+    exclude: |
+      (?x)^(
+        lmcache/.*/gpu_connector/.*|
+        lmcache/v1/platform/.*
+      )$
+  - id: ban-cuda-host-register
+    name: Ban cudaHostRegister/Unregister outside platform
+    entry: >-
+      bash -c '
+      matches=$(grep -rHnE "\.cudaHost(Register|Unregister)" "$@");
+      if [ -n "$matches" ]; then
+        echo "";
+        echo "=======================================================================";
+        echo "  BANNED: .cudaHostRegister/Unregister usage found outside platform dir";
+        echo "  Fix 1: They are only allowed in the platform directory";
+        echo "  Fix 2: use current_device_spec.pin_memory/unpin_memory instead";
+        echo "=======================================================================";
+        echo "";
+        echo "$matches";
+        exit 1;
+      fi' --
+    language: system
+    types: [python]
+    files: ^lmcache/
+    exclude: |
+      (?x)^(
+        lmcache/.*/gpu_connector/.*|
+        lmcache/v1/platform/.*
+      )$
+  - id: ban-raw-timeout-error
+    name: Ban raw raise of builtin TimeoutError
+    entry: >-
+      bash -c '
+      matches=$(grep -rHnE "raise[[:space:]]+(asyncio\.)?TimeoutError\b" "$@");
+      if [ -n "$matches" ]; then
+        echo "";
+        echo "========================================";
+        echo "  BANNED: raw raise of builtin TimeoutError";
+        echo "  Fix: raise LMCacheTimeoutError from";
+        echo "       lmcache.v1.mp_observability.errors so the timeout";
+        echo "       is reported to MP observability (OTel).";
+        echo "========================================";
+        echo "";
+        echo "$matches";
+        exit 1;
+      fi' --
+    language: system
+    types: [python]
+    files: ^lmcache/
+- repo: https://github.com/PyCQA/isort
+  rev: 6.0.1
+  hooks:
+  - id: isort
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.11.7
+  hooks:
+  - id: ruff
+    args: [--output-format, github, --fix]
+  - id: ruff-format
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.4.1
+  hooks:
+  - id: codespell
+    additional_dependencies: ['tomli']
+    args: ['--toml', 'pyproject.toml']
+- repo: https://github.com/pre-commit/mirrors-clang-format
+  rev: v20.1.3
+  hooks:
+  - id: clang-format
+    types_or: [c++, cuda]
+    args: [--style=file, --verbose]
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: 'v1.17.1'
+  hooks:
+  - id: mypy
+    language_version: python3.12 
+    args: [--config-file=pyproject.toml]
+    #args: [--ignore-missing-imports]
+    additional_dependencies:
+      - tokenize-rt==6.1.0 # For better dynamic analysis performance
+      - msgspec[mypy]
+      - types-requests
+      - types-PyYAML
+      - types-aiofiles
+- repo: local
+  hooks:
+  - id: rust-fmt
+    name: Rust Format Check
+    entry: bash -c 'cd rust/raw_block && cargo fmt --check'
+    language: system
+    types: [text]
+    files: ^rust/raw_block/.*\.rs$
+  - id: rust-clippy
+    name: Rust Clippy Check
+    entry: bash -c 'cd rust/raw_block && cargo clippy -- -D warnings'
+    language: system
+    types: [text]
+    files: ^rust/raw_block/.*\.rs$
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..aa239e5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,219 @@
+# AGENTS.md
+
+Guidelines for AI coding agents (Copilot, Cursor, Claude Code, etc.) working in this repository.
+
+## Project Overview
+
+LMCache is a KV cache management engine for LLM serving that reduces Time To First Token (TTFT) and increases throughput. It stores KV caches across multiple tiers (GPU, CPU, disk, S3) and integrates with vLLM and SGLang.
+
+## Repository
+
+The default branch is `dev`. Base all new branches and pull requests against `dev`.
+
+## Python Environment
+
+We recommend using [uv](https://docs.astral.sh/uv/) to manage Python environments and dependencies:
+
+```bash
+# Create and activate a virtual environment
+uv venv --python 3.12
+source .venv/bin/activate
+
+# Install dependencies
+uv pip install torch               # pre-requisite for CUDA extensions
+uv pip install -e . --no-build-isolation
+```
+
+## Build & Install
+
+```bash
+# Standard install with CUDA extensions (requires torch pre-installed)
+pip install -e . --no-build-isolation
+
+# Source-only (no native extensions)
+NO_NATIVE_EXT=1 pip install -e .
+
+# CPU-only (common C++ extensions, no GPU backend)
+NO_GPU_EXT=1 pip install -e . --no-build-isolation
+
+# HIP/ROCm build
+BUILD_WITH_HIP=1 pip install -e .
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run standard test suite (mirrors CI)
+pytest -xvs --ignore=tests/disagg \
+ --ignore=tests/v1/multiprocess/ \
+ --ignore=tests/v1/distributed/ \
+ --ignore=tests/skipped \
+ --ignore=tests/v1/storage_backend/test_eic.py
+
+# Run a single test file
+pytest -xvs tests/v1/test_cache_engine.py
+
+# Run a single test
+pytest -xvs tests/v1/test_cache_engine.py::test_function_name
+```
+
+Test dependencies: `uv pip install -r requirements/test.txt`
+
+Pytest marker: `@pytest.mark.no_shared_allocator` disables the shared-allocator monkeypatch for a test.
+
+### Testing Practices
+
+- Write tests against the **public interface and docstring contract**, not the implementation. Test as if you don't know the internals — verify that behavior matches what the docstring describes.
+- Avoid accessing private members in tests unless strongly needed.
+- All new features and bug fixes should include corresponding tests.
+- Ensure existing tests still pass before submitting changes.
+
+## Linting & Code Quality
+
+```bash
+# Run all checks (mirrors CI exactly)
+pre-commit run --all-files
+
+# Individual tools
+ruff check .              # Lint (E, F, B, SLF rules)
+ruff format .             # Format (line-length 88)
+isort .                   # Import sorting (black profile, from_first=true)
+mypy --config-file=pyproject.toml   # Type checking
+codespell --toml pyproject.toml     # Spell checking
+```
+
+C++/CUDA files use clang-format (Google style, 80-col). Rust code in `rust/` uses `cargo fmt` and `cargo clippy`.
+
+All Python files require an `# SPDX-License-Identifier: Apache-2.0` header as the first line.
+
+### Import Ordering
+
+Imports must follow this section-heading convention:
+
+```python
+# Standard
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+
+# Local
+from .utils import helper
+```
+
+### SLF (Private Member Access)
+
+SLF lint rules are currently enforced by CI only in `lmcache/v1/multiprocess/` and `lmcache/v1/distributed/`. However, **all new code should follow SLF discipline regardless of location** — never access private members (prefixed with `_`) of other classes. Treat this as a project-wide coding standard for any new or modified code.
+
+## Coding Conventions
+
+### Type Hints
+
+All functions and methods must have type hints for their arguments and return values.
+
+### Docstrings
+
+Every public function and method must have a clear docstring covering:
+- What the function does
+- Arguments (with types and descriptions)
+- Return values
+- Raised exceptions (if any)
+- Additional notes when behavior is non-obvious
+
+### Writing Documentation
+
+LMCache has three documentation surfaces:
+
+1. **User-facing docs** (`docs/source/`, reStructuredText, Sphinx-built). When adding
+   or modifying user docs, place them in the appropriate subdirectory under
+   `docs/source/` (e.g., `developer_guide/`, `getting_started/`, `kv_cache/`) and link
+   new pages from a `toctree` so they appear in the built site.
+2. **Design docs** (`docs/design/`, Markdown). **`docs/design/` mirrors the `lmcache/`
+   package tree** — a design doc for `lmcache/<path>/` lives at `docs/design/<path>/`.
+   For example, `lmcache/v1/distributed/l2_adapters/` → `docs/design/v1/distributed/l2_adapters/`.
+   When adding a design doc, place it at the path matching the module it describes;
+   when touching existing docs, find them at the mirrored location. See
+   `docs/design/README.md` for the full convention.
+3. **Module READMEs** (`README.md` next to code). Stay in place as user-entry-points;
+   they are symlinked from `docs/design/<path>/README.md`. Do not move them.
+
+When writing or updating documentation, follow these principles:
+
+- **Be concrete and concise.** State exactly what something does and why — avoid vague, hand-wavy descriptions. One precise sentence beats a paragraph of generalities.
+- **Include examples.** Show concrete code snippets, command invocations, or data formats so the reader can immediately see how things work in practice.
+- **Explain the _why_, not just the _what_.** Briefly state the design motivation or trade-off behind a decision so readers understand the reasoning.
+- **Use diagrams or short flows for complex interactions.** When multiple components interact (e.g., the multiprocess pipeline), a short step-by-step flow or ASCII diagram is far clearer than prose alone.
+- **Keep scope focused.** Each document should have a clear audience and purpose. Don't mix user-facing setup guides with internal architecture notes.
+
+#### Building and verifying docs
+
+Always verify that the Sphinx build passes after making documentation changes:
+
+```bash
+# Install doc dependencies (one-time)
+pip install -r requirements/docs.txt
+
+# Build (from the docs/ directory)
+cd docs
+make clean
+make html
+```
+
+The build must complete **without errors or warnings**. Review the generated HTML in `docs/build/html/` to confirm formatting, links, and examples render correctly. You can preview locally with:
+
+```bash
+python -m http.server -d build/html/
+```
+
+### Encapsulation
+
+Never access private members (prefixed with `_`) of other classes. Interact only through their public APIs.
+
+### Code Organization
+
+- **Module-level helper functions** go at the top of the file (after imports, before classes).
+- **Private/helper methods** within a class go at the end of the class, after all public methods.
+
+## Code Review Checklist
+
+When reviewing code (or self-checking before submitting), verify all of the following:
+
+### Correctness
+- [ ] The code does what it claims to do and matches the PR description.
+- [ ] Edge cases are handled (empty inputs, None values, boundary conditions).
+- [ ] No regressions to existing functionality — existing tests still pass.
+
+### Style & Standards
+- [ ] `pre-commit run --all-files` passes with no errors.
+- [ ] All new/modified functions have type hints for arguments and return values.
+- [ ] All new/modified public functions have complete docstrings.
+- [ ] License header (`# SPDX-License-Identifier: Apache-2.0`) is present on all Python files.
+- [ ] Import ordering follows the section-heading convention (Standard / Third Party / First Party / Local).
+
+### Encapsulation & Design
+- [ ] No direct access to private members (`_`-prefixed) of other classes.
+- [ ] New public APIs are minimal and well-defined — avoid exposing internals.
+- [ ] Module-level helpers are placed at the top; private methods at the end of the class.
+
+### Testing
+- [ ] New features and bug fixes include corresponding tests.
+- [ ] Tests target the public interface and docstring contract, not implementation details.
+- [ ] Tests pass locally: `pytest -xvs` with the standard ignore flags.
+
+### Documentation
+- [ ] New or updated documentation is concrete, concise, and includes examples.
+- [ ] Design decisions explain the _why_, not just the _what_.
+- [ ] Docs are placed in the correct subdirectory under `docs/source/` and linked from a `toctree`.
+- [ ] Sphinx build passes cleanly: `cd docs && make clean && make html` completes without errors or warnings.
+
+### Safety & Performance
+- [ ] No security vulnerabilities (injection, unsafe deserialization, etc.).
+- [ ] No unnecessary memory copies or allocations in hot paths.
+- [ ] Thread safety is maintained for shared data structures.
+- [ ] CUDA/GPU resources are properly managed (allocated, freed, synchronized).
+
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..01f2f2d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Code Quality Standards
+
+The authoritative reference for coding quality, review process, and PR expectations is
+**[docs/coding_standards.md](docs/coding_standards.md)**. Read it before writing or reviewing code.
+
+Key principles (see the full doc for details and rationale):
+
+- **Strong typing**: All functions have type hints. No `Any`, no bare generics. Avoid `Optional` -- initialize objects even if empty.
+- **Docstrings**: Every public function has a complete docstring (summary, args, returns, raises). Docstrings must match actual current behavior.
+- **Encapsulation**: Never access private members (`_`-prefixed) of other classes. Minimize public interfaces.
+- **Interface design**: No ambiguous return values. No boolean parameters (use enums or split functions). Document schemas for dict/container params.
+- **Testing**: New features and bug fixes require tests. Tests verify the public interface, not implementation details.
+- **No `assert` for validation**: Use `if/raise ValueError` for runtime checks.
+- **PR scope**: Keep PRs small and focused. Break large changes into multiple PRs.
+
+For the quick-reference checklist and build/test/lint commands, see **[AGENTS.md](AGENTS.md)**.
+
+## Design Docs
+
+Design docs live under **`docs/design/`**, which **mirrors the `lmcache/` package tree**.
+A design doc for code at `lmcache/<path>/` is located at `docs/design/<path>/`:
+
+- `lmcache/cli/commands/ping.py` → `docs/design/cli/commands/ping.md`
+- `lmcache/v1/distributed/l2_adapters/` → `docs/design/v1/distributed/l2_adapters/`
+- `lmcache/v1/mp_observability/` → `docs/design/v1/mp_observability/`
+
+When investigating a module, always check the mirrored `docs/design/<path>/` first for
+design rationale, contracts, and extension guides. When adding or updating a design
+doc, place it at the path matching the module it describes. See
+[docs/design/README.md](docs/design/README.md) for the full convention.
+
+Module `README.md` files stay co-located with code (symlinked from `docs/design/`); do
+not relocate them.
+
+## PR Review Instructions
+
+When asked to review a PR, use the `/pr-review` skill which implements the full review
+process from `docs/coding_standards.md` Section 9.
+
+The review covers:
+
+1. **Design doc compliance** -- check implementation against documented contracts (table format).
+2. **Coding quality** -- typing, docstrings, naming, interface design per Sections 2-4.
+3. **Correctness** -- logic bugs, error handling paths, resource management.
+4. **Thread safety** -- shared state, lock protocols, concurrent access patterns.
+5. **Test coverage** -- especially failure paths and concurrent access.
+6. **PR structure** -- is the scope appropriate, or should it be broken down?
+
+Issues are grouped by severity:
+- **error**: Must fix before merge (missing types/docstrings, no tests, architectural problems).
+- **warning**: Should fix (naming, modularity, test quality).
+- **info**: Suggestion only, non-blocking.
+
+See `docs/coding_standards.md` Section 9 for the full severity calibration and reviewer guidelines.
diff --git a/CMakeLists.txt b/CMakeLists.txt
new file mode 100644
index 0000000..ca2d359
--- /dev/null
+++ b/CMakeLists.txt
@@ -0,0 +1,2 @@
+cmake_minimum_required(VERSION 3.10)
+project(lmcache LANGUAGES CXX)
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..6f44946
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,128 @@
+# LMCache Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socioeconomic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+siddhant.r98@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..506a19b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,135 @@
+# Contributing 👍🎉
+
+First off, thank you for taking the time to contribute! 🎉👍  
+Check out the [online docs](https://docs.lmcache.ai/developer_guide/contributing.html) for a set of guidelines for contributing.
+
+A summary of LMCache's current direction can be found at: [[Onboarding] Welcoming contributors with good first issues!](https://github.com/LMCache/LMCache/issues/627)
+
+=======
+
+## Becoming an LMCache Committer
+
+To become a committer, you should:
+
+- Have **more than 5 important features** merged.
+- Have been **contributing for longer than 3 months**.
+- Be [**nominated by an existing committer**](MAINTAINERS.md).
+
+========
+
+## Basics of LMCache dev
+
+The default branch is `dev`. Base all new branches and pull requests against `dev`.
+
+## Python Environment
+
+We recommend using [uv](https://docs.astral.sh/uv/) to manage Python environments and dependencies:
+
+```bash
+# Create and activate a virtual environment
+uv venv --python 3.12
+source .venv/bin/activate
+
+# Install dependencies
+uv pip install vllm/sglang/other engines
+
+# Install LMCache. Requires nvcc. Use --no-build-isolation to ensure torch compatibility.
+uv pip install -e . --no-build-isolation
+
+# For ROCm build
+BUILD_WITH_HIP=1 pip install -e .
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run standard test suite (mirrors CI)
+pytest -xvs --ignore=tests/disagg \
+  --ignore=tests/v1/multiprocess/ \
+  --ignore=tests/v1/distributed/ \
+  --ignore=tests/skipped \
+  --ignore=tests/v1/storage_backend/test_eic.py
+
+# Run a single test file
+pytest -xvs tests/v1/test_cache_engine.py
+
+# Run a single test
+pytest -xvs tests/v1/test_cache_engine.py::test_function_name
+```
+
+Test dependencies: `uv pip install -r requirements/test.txt`
+
+Pytest marker: `@pytest.mark.no_shared_allocator` disables the shared-allocator monkeypatch for a test.
+
+### Testing Practices
+
+- Write tests against the **public interface and docstring contract**, not the implementation. Test as if you don't know the internals — verify that behavior matches what the docstring describes.
+- Avoid accessing private members in tests unless strongly needed.
+- All new features and bug fixes should include corresponding tests.
+- Ensure existing tests still pass before submitting changes.
+
+## Linting & Code Quality
+
+```bash
+# Run all checks (mirrors CI exactly)
+pre-commit run --all-files
+
+# Individual tools
+ruff check .              # Lint (E, F, B, SLF rules)
+ruff format .             # Format (line-length 88)
+isort .                   # Import sorting (black profile, from_first=true)
+mypy --config-file=pyproject.toml   # Type checking
+codespell --toml pyproject.toml     # Spell checking
+```
+
+C++/CUDA files use clang-format (Google style, 80-col). Rust code in `rust/` uses `cargo fmt` and `cargo clippy`.
+
+All Python files require an `# SPDX-License-Identifier: Apache-2.0` header as the first line.
+
+### Import Ordering
+
+Imports must follow this section-heading convention:
+
+```python
+# Standard
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+
+# Local
+from .utils import helper
+```
+
+### SLF (Private Member Access)
+
+SLF lint rules are currently enforced by CI only in `lmcache/v1/multiprocess/` and `lmcache/v1/distributed/`. However, **all new code should follow SLF discipline regardless of location** — never access private members (prefixed with `_`) of other classes. Treat this as a project-wide coding standard for any new or modified code.
+
+## Coding Conventions
+
+### Type Hints
+
+All functions and methods must have type hints for arguments and return values.
+
+### Docstrings
+
+Every public function and method must have a clear docstring covering:
+- What the function does
+- Arguments (with types and descriptions)
+- Return values
+- Raised exceptions (if any)
+- Additional notes when behavior is non-obvious
+
+### Encapsulation
+
+Never access private members (prefixed with `_`) of other classes. Interact only through their public API.
+
+### Code Organization
+
+- **Module-level helper functions** go at the top of the file (after imports, before classes).
+- **Private/helper methods** within a class go at the end of the class, after all public methods.
diff --git a/DCO b/DCO
new file mode 100644
index 0000000..49b8cb0
--- /dev/null
+++ b/DCO
@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..261eeb9
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
new file mode 100644
index 0000000..5ffe98f
--- /dev/null
+++ b/MAINTAINERS.md
@@ -0,0 +1,14 @@
+# Maintainers List
+
+Following is the current list of maintainers on this project
+
+- @apostacheng@gmail.com, Yihua Cheng, UChicago, Committer
+- @jiayi3@uchicago.edu, Jiayi Yao, UChicago, Committer
+- @kuntai@uchicago.edu, Kuntai Du, UChicago, Committer
+- @martin.hickey@ie.ibm.com, Martin Hickey, IBM, Committer
+- @HUAIZHEN001@e.ntu.edu.sg, Hunter Zhang, Bytedance, Committer
+- @307499405@qq.com, Baolong Mao, Tencent, Committer
+- @1179548172@qq.com, Chunxiao Zheng, Tencent, Committer
+- @shaotingf@uchicago.edu, Shaoting Feng, UChicago, Committer
+- @slshen@uchicago.edu, Samuel Shen, UChicago, Committer
+- @dongjoo.seo1@samsung.com, Dongjoo Seo, Samsung, Committer
diff --git a/MANIFEST.in b/MANIFEST.in
new file mode 100644
index 0000000..168e321
--- /dev/null
+++ b/MANIFEST.in
@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include requirements/common.txt
+include requirements/cuda.txt
+include requirements/cuda12_core.txt
+include requirements/cuda13_core.txt
+include requirements/nixl.txt
+
+recursive-include csrc *
+recursive-include lmcache/lmcache_frontend *
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9927f76
--- /dev/null
+++ b/README.md
@@ -0,0 +1,153 @@
+<div align="center">
+  <p align="center">
+    <img src="asset/logo.png" alt="lmcache logo" width="45%">
+  </p>
+  <h3 align="center">
+    A KV Cache Management Layer for Scalable LLM Inference
+  </h3>
+    <hr width="78%">
+
+  <h3 align="center">
+    <a href="https://blog.lmcache.ai/">Blog</a> |
+    <a href="https://docs.lmcache.ai/">Documentation</a> |
+    <a href="https://join.slack.com/t/lmcacheworkspace/shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA">Join Slack</a> |
+    <a href="https://docs.lmcache.ai/community/meetings.html">Community Meeting</a> |
+    <a href="https://github.com/LMCache/LMCache/issues/2923">Roadmap</a>
+  </h3>
+
+  [![GitHub Repo stars](https://img.shields.io/github/stars/LMCache/LMCache?style=flat&logo=github)](https://github.com/LMCache/LMCache/stargazers)
+  [![PyPI](https://img.shields.io/pypi/v/lmcache)](https://pypi.org/project/lmcache/)
+  [![PyPI - Downloads](https://img.shields.io/pypi/dm/lmcache)](https://pypi.org/project/lmcache/)
+  [![GitHub commit activity](https://img.shields.io/github/commit-activity/w/LMCache/LMCache)](https://github.com/LMCache/LMCache/graphs/commit-activity)
+  [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/LMCache/LMCache/)
+
+  ⭐ **If LMCache helps you serve LLMs faster and cheaper, [give us a star](https://github.com/LMCache/LMCache) — it helps more teams discover the project.**
+
+</div>
+
+## Updates
+- [2026/05] 🔥 Agentic workload benchmark on AMD MI300X ([blog](https://blog.lmcache.ai/en/2026/05/12/benchmarking-lmcache-for-multi-turn-agentic-workloads-on-amd-mi300x/)).
+- [2026/04] 🔥 LMCache's new multiprocess (MP) architecture release ([blog](https://blog.lmcache.ai/en/2026/04/03/lmcaches-new-architecture-boosts-moe-inference-performance-by-10x/)).
+- [2026/03] LMCache at GTC 2026 ([post](https://www.linkedin.com/posts/lmcache-lab_llm-opensource-nvidiagtc-activity-7442721875664826369-pMAu?utm_source=share&utm_medium=member_desktop&rcm=ACoAADkIIvQBTyG53kXXX70OZdE5rhpllYQqmIA)).
+- [2026/01] LMCache multi-node P2P CPU memory sharing, from experimental feature to production ([blog](https://blog.lmcache.ai/en/2026/01/21/p2p-1/)).
+
+<details>
+<summary>More</summary>
+
+- [2025/11] LMCache x CoreWeave accelerate efficient LLM inference for Cohere ([blog](https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/)).
+- [2025/10] LMCache joins the PyTorch Foundation and Tensormesh unveiled ([blog](https://blog.lmcache.ai/en/2025/10/31/tensormesh-unveiled-and-lmcache-joins-the-pytorch-foundation/), [PyTorch](https://pytorch.org/blog/lmcache-joins-pytorch-ecosystem/)).
+- [2025/09] NVIDIA Dynamo integrates LMCache, accelerating LLM inference ([blog](https://blog.lmcache.ai/en/2025/09/18/nvidia-dynamo-integrates-lmcache-accelerating-llm-inference/)).
+- [2025/08] 🎉 LMCache hits 5,000+ GitHub stars ([blog](https://blog.lmcache.ai/en/2025/08/28/%f0%9f%8e%89-lmcache-hits-5000-github-stars-thank-you-community/)).
+- [2025/08] LMCache supports gpt-oss (20B/120B) on day 1 ([blog](https://blog.lmcache.ai/en/2025/08/05/lmcache-supports-gpt-oss-20b-120b-on-day-1/)).
+- [2025/07] Get faster LLM inference and cheaper responses with LMCache and Redis ([Redis blog](https://redis.io/blog/get-faster-llm-inference-and-cheaper-responses-with-lmcache-and-redis/)).
+- [2025/07] LMCache extends its turbo-boost to multimodal models in vLLM V1 ([blog](https://blog.lmcache.ai/en/2025/07/03/lmcache-extends-its-turbo-boost-to-multimodal-models-in-vllm-v1/)).
+- [2025/06] LLM Production Stack goes cross-hardware: AMD, Arm and Ascend ([blog](https://blog.lmcache.ai/en/2025/06/20/llm-production-stack-goes-cross-hardware-ascend-arm-and-amd-support-incoming/)).
+
+</details>
+
+## About
+
+LMCache is a **KV cache management layer** for LLM inference. It turns KV cache from a temporary state into reusable *AI-native knowledge* that can be *stored* persistently, *reused* across multiple serving engines, *monitored* with an observability stack, and *transformed* for better generation quality. As a result, LMCache **reduces TTFT** (time-to-first-token) and **improves throughput**, especially for long-context agentic, multi-turn conversation, and knowledge-augmented workloads (e.g., RAG).
+
+LMCache is **vendor-neutral**. It can be used as a KV cache layer for a range of mainstream open-source serving engines, inference frameworks, hardware vendors, storage systems, and infrastructure providers. The vendor neutrality allows users to freely switch between serving engines and storage vendors, while reusing the stored KV caches.
+
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="asset/deployment_modes_dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="asset/deployment_modes_light.png">
+  <img alt="LMCache Deployment Modes" src="asset/deployment_modes_light.png">
+</picture>
+</p>
+
+### Key features
+
+- **Engine-independent deployment**: LMCache, as a standalone daemon process, manages KV cache independently from the inference engine process, so that KV cache will not be lost even if the inference engine crashes (i.e., no fate-sharing with engines).
+
+- **Persistent, tiered KV cache offloading and reuse**: Move KV caches out of GPU memory into a tiered storage hierarchy spanning CPU memory, local storage, and remote backends, enabling reuse across requests, sessions, and engine instances to reduce repeated prefill computation and improve TTFT.
+
+- **Production-level KV cache observability**: LMCache provides a rich set of KV cache observability metrics, including typical Kubernetes metrics (health monitoring, performance diagnostics), KV-cache-specific metrics (request-level and token-level prefix cache hits, lifecycle, request-level KV cache performance), management metrics (user-specific usage), and more.
+
+- **Pluggable storage and transport backends**: Easily integrate remote storage and KV transfer backends through a unified interface, enabling KV cache offloading and sharing across storage providers. Through this interface, LMCache supports storage backends including CPU RAM, local disk (SSD), Redis/Valkey, Mooncake, InfiniStore, S3-compatible object storage, NIXL, and GDS.
+
+- **Non-prefix KV reuse**: Extend KV reuse beyond prefix caching by reusing cached KV blocks at any position in the prompt. This leverages CacheBlend to selectively recompute tokens for quality recovery.
+
+- **PD disaggregation and KV transfer**: Support KV cache transfer from prefill workers to decode workers over NVLink, RDMA, or TCP through transport layers such as NIXL.
+
+- **Pluggable KV transformation**: A simple interface for researchers to write compression, token dropping, and custom serialization through a flexible SERDE interface.
+
+LMCache is becoming an integral layer in the LLM inference *ecosystem*, with *community*-driven integration with serving engines, inference frameworks, hardware vendors, storage systems, and infrastructure providers:
+
+<p align="center">
+  <img src="asset/ecosystem.png" alt="LMCache ecosystem">
+</p>
+
+## Getting Started
+
+To use LMCache, simply install `lmcache` from your package manager, e.g. pip:
+```bash
+pip install lmcache
+```
+
+For more setup options and examples, see:
+- [Installation](https://docs.lmcache.ai/getting_started/installation.html)
+- [Quickstart](https://docs.lmcache.ai/getting_started/quickstart.html)
+- [LMCache Recipes](https://docs.lmcache.ai/recipes/index.html)
+- [CLI Reference](https://docs.lmcache.ai/cli/index.html)
+- [Benchmarking Guide](https://docs.lmcache.ai/getting_started/benchmarking.html)
+- [Production Deployment](https://docs.lmcache.ai/mp/deployment.html)
+
+## Contributing
+We welcome and value contributions and collaborations. Join us in improving LMCache. Check out the [Contributing Guide](https://docs.lmcache.ai/developer_guide/contributing.html) or join our [Slack community](https://join.slack.com/t/lmcacheworkspace/shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA) to get started.
+
+## Adoption and Partnerships
+LMCache has a growing community of developers, researchers, industry adopters, and partners building the next generation of efficient LLM inference systems.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="asset/partner_dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="asset/partner_light.png">
+    <img alt="LMCache Adoption and Partnerships" src="asset/partner_light.png">
+  </picture>
+</p>
+
+As an independent open-source project, LMCache is becoming the de-facto standard for KV Cache management in LLM inference. Its continued development and community work are supported in part by [Tensormesh](https://www.tensormesh.ai/).
+
+## Citation
+
+LMCache builds on research in KV cache management, including cache reuse, offloading, compression, and serving optimization. If you use LMCache in your research, please cite the LMCache paper and related work.
+
+~~~bibtex
+@article{cheng2025lmcache,
+  title={LMCache: An Efficient KV Cache Layer for Enterprise-Scale LLM Inference},
+  author={Cheng, Yihua and Liu, Yuhan and Yao, Jiayi and An, Yuwei and Chen, Xiaokun and Feng, Shaoting and Huang, Yuyang and Shen, Samuel and Du, Kuntai and Jiang, Junchen},
+  journal={arXiv preprint arXiv:2510.09665},
+  year={2025}
+}
+~~~
+
+<details>
+<summary>Related papers</summary>
+
+~~~bibtex
+@inproceedings{liu2024cachegen,
+  title={Cachegen: Kv cache compression and streaming for fast large language model serving},
+  author={Liu, Yuhan and Li, Hanchen and Cheng, Yihua and Ray, Siddhant and Huang, Yuyang and Zhang, Qizheng and Du, Kuntai and Yao, Jiayi and Lu, Shan and Ananthanarayanan, Ganesh and others},
+  booktitle={Proceedings of the ACM SIGCOMM 2024 Conference},
+  pages={38--56},
+  year={2024}
+}
+
+@inproceedings{yao2025cacheblend,
+  title={Cacheblend: Fast large language model serving for rag with cached knowledge fusion},
+  author={Yao, Jiayi and Li, Hanchen and Liu, Yuhan and Ray, Siddhant and Cheng, Yihua and Zhang, Qizheng and Du, Kuntai and Lu, Shan and Jiang, Junchen},
+  booktitle={Proceedings of the twentieth European conference on computer systems},
+  pages={94--109},
+  year={2025}
+}
+~~~
+
+</details>
+
+## License
+
+The LMCache codebase is licensed under Apache License 2.0. See the [LICENSE](LICENSE) file for details.
diff --git a/README.wehub.md b/README.wehub.md
new file mode 100644
index 0000000..a6ad84b
--- /dev/null
+++ b/README.wehub.md
@@ -0,0 +1,7 @@
+# WeHub 来源说明
+
+- 原始项目：`LMCache/LMCache`
+- 原始仓库：https://github.com/LMCache/LMCache
+- 导入方式：上游默认分支的最新快照
+- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
+- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..5936080
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,9 @@
+# Security Policy
+
+## Supported Versions
+
+If you believe you have found a security vulnerability in LMCache, please let us know right away. We will investigate all vulnerability reports and do our best to quickly fix the problem.
+
+## Reporting a Vulnerability
+
+For now, please email details of the vulnerability to lmcacheteam@gmail.com. Please try to include some detailed examples, screenshots etc. or anything you feel which may help identify the problem fast.
diff --git a/asset/deployment_modes_dark.png b/asset/deployment_modes_dark.png
new file mode 100644
index 0000000..9ec05f2
Binary files /dev/null and b/asset/deployment_modes_dark.png differ
diff --git a/asset/deployment_modes_light.png b/asset/deployment_modes_light.png
new file mode 100644
index 0000000..127bd3d
Binary files /dev/null and b/asset/deployment_modes_light.png differ
diff --git a/asset/ecosystem.png b/asset/ecosystem.png
new file mode 100644
index 0000000..146ce57
Binary files /dev/null and b/asset/ecosystem.png differ
diff --git a/asset/logo.png b/asset/logo.png
new file mode 100644
index 0000000..dd4268e
Binary files /dev/null and b/asset/logo.png differ
diff --git a/asset/partner_dark.png b/asset/partner_dark.png
new file mode 100644
index 0000000..ccdb24c
Binary files /dev/null and b/asset/partner_dark.png differ
diff --git a/asset/partner_light.png b/asset/partner_light.png
new file mode 100644
index 0000000..3e7dc32
Binary files /dev/null and b/asset/partner_light.png differ
diff --git a/benchmarks/long_doc_qa/long_doc_qa.py b/benchmarks/long_doc_qa/long_doc_qa.py
new file mode 100644
index 0000000..e959c53
--- /dev/null
+++ b/benchmarks/long_doc_qa/long_doc_qa.py
@@ -0,0 +1,778 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# Adapted from
+# https://github.com/vllm-project/vllm/blob/main/benchmarks/benchmark_long_document_qa_throughput.py
+
+"""
+Commandline arguments:
+    --num-documents: The number of documents to sample prompts from.
+
+    --document-length: The length of each document in tokens.
+                       (Optional, default: 20000)
+
+    --output-len: The number of tokens to generate for each prompt.
+                  (Optional, default: 100)
+
+    --repeat-count: The number of times to repeat each prompt.
+                    (Optional, default: 2)
+
+    --repeat-mode: The mode to repeat prompts. The supported modes are:
+        - 'random': shuffle the prompts randomly. (Default)
+        - 'tile': the entire prompt list is repeated in sequence.
+        - 'interleave': each prompt is repeated consecutively before
+                        moving to the next element.
+
+    --shuffle-seed: Random seed when the repeat mode is "random".
+                    (Optional, default: 0)
+
+    --host: Host to query the vLLM server
+    --port: Port to query the vLLM server
+    --base-url: Base URL to query the LLM server (exclusive with --host/--port)
+
+    --model: Model name
+
+    --max-inflight-requests: Maximum number of in-flight requests. Default is 2
+
+    --sleep-time-after-warmup: Sleep time after warm up iteration.
+                              (Optional, default: 0.0 seconds)
+
+    --output: Filename to write all responses to. If omitted, writes to stdout.
+
+    --expected-ttft-gain: Expected minimum speed-up in time-to-first-token
+                         (warmup/query) as a factor, e.g. 4.3 for 4.3×. If
+                         actual gain is below this, exits.
+
+    --expected-latency-gain: Expected minimum speed-up in total round time
+                            (warmup/query) as a factor, e.g. 4.5 for 4.5×.
+                            If actual gain is below this, exits.
+
+    --expected-latency: Expected end to end latency for the first query round.
+    --completions: Use completions API instead of chat completions API
+
+    --visualize: Visualize the results
+
+    --eos-token-id: EOS token id. we bias against this token id so we always
+                   get the number of output tokens we specify
+
+    --hit-miss-ratio: In query round, control how many of the prompts
+    will miss the cache. For example, 3:1 means every fourth repeated prompt
+    will miss the cache. 2:2 means 2 hits and 2 misses.
+
+    --trim-fraction: Exclude the smallest X fraction and largest X fraction
+    and calculate mean of the rest. For example, 0.1 drops bottom 10% and top 10%.
+"""
+
+# Standard
+from dataclasses import dataclass
+import argparse
+import asyncio
+import os
+import random
+import sys
+import time
+
+# Third Party
+from openai import AsyncOpenAI
+import pandas as pd
+
+# Global output filename (set in __main__)
+OUTPUT_FILE = None
+completions_mode = False
+visualize = False
+eos_token_id = None
+
+
+@dataclass
+class RequestStats:
+    prompt_id: int
+    request_start: float
+    ttft: float
+    request_end: float
+    successful: bool
+
+
+def get_url_from_args(args):
+    """
+    Get the base URL from command line arguments.
+    Args:
+        args: Command line arguments.
+    Returns:
+        str: The base URL.
+    """
+    if args.base_url is not None:
+        return args.base_url
+    else:
+        host = args.host if args.host is not None else "localhost"
+        port = args.port if args.port is not None else 8000
+        return f"http://{host}:{port}/v1"
+
+
+def extract_reasoning_content(chunk):
+    """
+    Extract reasoning content from the response chunk.
+    Args:
+        chunk: The response chunk from OpenAI Chat Completions API.
+    Returns:
+        str | None: The reasoning content extracted from the chunk.
+            None means no reasoning content in this chunk.
+    """
+    delta = chunk.choices[0].delta
+    potential_reasoning_keys = [
+        "reasoning_content",
+        "reasoning",
+        "tool_calls",
+        "tool_call",
+        "tool_responses",
+    ]
+    for key in potential_reasoning_keys:
+        if hasattr(delta, key) and getattr(delta, key):
+            return getattr(delta, key)
+    return None
+
+
+def extract_normal_content(chunk):
+    """
+    Extract normal content from the response chunk.
+    Args:
+        chunk: The response chunk from OpenAI Chat Completions API.
+    Returns:
+        str | None: The normal content extracted from the chunk.
+            None means no normal content in this chunk.
+    """
+    delta = chunk.choices[0].delta
+    if hasattr(delta, "content") and delta.content:
+        return chunk.choices[0].delta.content
+    return None
+
+
+def has_content_completions(chunk):
+    """
+    Completions streaming emits text at choices[0].text.
+    """
+    return bool(chunk.choices) and (chunk.choices[0].text is not None)
+
+
+def has_content(chunk, completions_mode=False):
+    """
+    Check if the chunk has content in the choices.
+    Args:
+        chunk: The response chunk from OpenAI Chat Completions API.
+
+    Returns:
+        bool: True if content exists, False otherwise.
+    """
+    if completions_mode:
+        return has_content_completions(chunk)
+
+    return (
+        chunk.choices
+        and chunk.choices[0].delta
+        and (
+            extract_normal_content(chunk) is not None
+            or extract_reasoning_content(chunk) is not None
+        )
+    )
+
+
+def extract_content_completions(chunk):
+    """
+    Extract content from a Completions stream chunk.
+    """
+    return chunk.choices[0].text or ""
+
+
+def extract_content(chunk, completions_mode=False):
+    """
+    Extract content from the response chunk.
+    Args:
+        chunk: The response chunk from OpenAI Chat Completions API.
+    Returns:
+        str: The content extracted from the chunk.
+    """
+    if completions_mode:
+        return extract_content_completions(chunk)
+
+    if normal_content := extract_normal_content(chunk):
+        return normal_content
+    elif reasoning_content := extract_reasoning_content(chunk):
+        return reasoning_content
+    else:
+        return ""
+
+
+def write_resp(text: str):
+    """
+    Write text to the specified output file (if any), otherwise to stdout.
+    """
+    if OUTPUT_FILE:
+        with open(OUTPUT_FILE, "a") as resp_file:
+            resp_file.write(text)
+    else:
+        sys.stdout.write(text)
+
+
+async def process_single_prompt(
+    client, model, prompt, prompt_index, total_prompts, output_len, semaphore
+) -> RequestStats:
+    """
+    Process a single prompt with the given client and model.
+
+    Args:
+        client: The OpenAI client for making API calls.
+        model: The model name to use for generation.
+        prompt: The prompt string to be processed.
+        prompt_index: Index of the current prompt (0-based).
+        total_prompts: Total number of prompts being processed.
+        output_len: The maximum number of tokens to generate.
+        semaphore: Asyncio semaphore to limit concurrent requests.
+
+    Returns:
+        RequestStats: RequestStats object containing the request stats
+    """
+    async with semaphore:  # Acquire semaphore to limit concurrent requests
+        write_resp(f"\n--- Sending prompt {prompt_index + 1}/{total_prompts} ---\n")
+        # a request starts once it acquires the semaphore
+        start_time = time.time()
+        first_token_time = None
+
+        # add stop None so we always get the number of output tokens we specify
+        if completions_mode:
+            response = await client.completions.create(
+                model=model,
+                prompt=prompt,
+                stream=True,
+                max_tokens=output_len,
+                temperature=0.0,
+                stream_options={"include_usage": True},
+                logit_bias={str(eos_token_id): -100}
+                if eos_token_id is not None
+                else None,
+            )
+        else:
+            response = await client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                stream=True,
+                max_tokens=output_len,
+                temperature=0.0,
+                stream_options={"include_usage": True},
+                logit_bias={str(eos_token_id): -100}
+                if eos_token_id is not None
+                else None,
+            )
+
+        responses = []
+        # Collect the response chunks
+        async for chunk in response:
+            if not chunk.choices:
+                continue
+
+            # Handle content for chat completions
+            if has_content(chunk, completions_mode):
+                content = extract_content(chunk, completions_mode)
+                if first_token_time is None and content != "":
+                    first_token_time = time.time()
+                responses.append(content)
+
+        end_time = time.time()
+        final_response = "".join(responses)
+        write_resp(f"\nResponse of request {prompt_index}: {final_response}\n")
+
+        # TTFT < 0 means not successful
+        ttft = (first_token_time - start_time) if first_token_time is not None else -1
+        return RequestStats(
+            prompt_id=prompt_index,
+            request_start=start_time,
+            ttft=ttft,
+            request_end=end_time,
+            successful=ttft > 0,
+        )
+
+
+async def test_long_document_qa(
+    client, model, prompts=None, output_len=100, max_inflight_requests=10
+) -> list[RequestStats]:
+    """
+    Test long document QA with the given prompts and sampling parameters.
+    Process prompts concurrently with a limit on inflight requests.
+
+    Args:
+        client: The OpenAI client for making API calls.
+        model: The model name to use for generation.
+        prompts: A list of prompt strings to be processed by the LLM.
+        output_len: The maximum number of tokens to generate.
+        max_inflight_requests: Maximum number of concurrent requests.
+
+    Returns:
+        list: request_stats - a list of RequestStats objects
+    """
+    # Create semaphore to limit concurrent requests
+    semaphore = asyncio.Semaphore(max_inflight_requests)
+
+    # Create tasks for all prompts
+    tasks = [
+        process_single_prompt(
+            client=client,
+            model=model,
+            prompt=prompt,
+            prompt_index=i,
+            total_prompts=len(prompts),
+            output_len=output_len,
+            semaphore=semaphore,
+        )
+        for i, prompt in enumerate(prompts)
+    ]
+    # Execute all tasks concurrently and collect results
+    # The semaphore will control max concurrent requests
+    request_stats = await asyncio.gather(*tasks)
+
+    return request_stats
+
+
+def repeat_prompts(prompts, repeat_count, mode: str):
+    """
+    Repeat each prompt in the list for a specified number of times.
+    The order of prompts in the output list depends on the mode.
+
+    Args:
+        prompts: A list of prompts to be repeated.
+        repeat_count: The number of times each prompt is repeated.
+        mode: The mode of repetition. Supported modes are:
+            - 'random': Shuffle the prompts randomly after repetition.
+            - 'tile': Repeat the entire prompt list in sequence.
+              Example: [1, 2, 3] -> [1, 2, 3, 1, 2, 3].
+            - 'interleave': Repeat each prompt consecutively before moving to
+              the next. Example: [1, 2, 3] -> [1, 1, 2, 2, 3, 3].
+
+    Returns:
+        A list of repeated prompts in the specified order.
+
+    Raises:
+        ValueError: If an invalid mode is provided.
+    """
+    write_resp(f"Repeat mode:  {mode}\n")
+    if mode == "random":
+        repeated_prompts = prompts * repeat_count
+        random.shuffle(repeated_prompts)
+        return repeated_prompts
+    elif mode == "tile":
+        return prompts * repeat_count
+    elif mode == "interleave":
+        repeated_prompts = []
+        for prompt in prompts:
+            repeated_prompts.extend([prompt] * repeat_count)
+        return repeated_prompts
+    else:
+        raise ValueError(
+            f"Invalid mode: {mode}, only support 'random', 'tile', 'interleave'"
+        )
+
+
+def add_cache_misses(prompts, hit_miss_ratio):
+    """
+    Add cache misses to the prompts and return a boolean mask aligned with prompts.
+    """
+    if hit_miss_ratio is None:
+        return prompts, [False] * len(prompts)
+
+    hit, miss = map(int, hit_miss_ratio.split(":", 1))
+    period = hit + miss
+    miss_mask = [False] * len(prompts)
+
+    for i in range(len(prompts)):
+        # every (hit+miss) window: first `hit` are hits, rest are misses
+        if period and (i % period) >= hit:
+            miss_mask[i] = True
+            prompts[i] = f"{random.randint(-10_000_000, 10_000_000)} {prompts[i]}"
+
+    return prompts, miss_mask
+
+
+def relative_time(df, start_time):
+    """
+    Relative time to the start of the benchmark.
+    """
+    df["request_start"] = df["request_start"] - start_time
+    df["request_end"] = df["request_end"] - start_time
+    df["ttft_time"] = df["request_start"] + df["ttft"]
+
+
+def visualize_results(warmup_df, benchmark_df):
+    def plot_bars(df, title, filename):
+        plt.figure(figsize=(12, 6))
+
+        if "is_miss" in df.columns:
+            is_miss = df["is_miss"]
+        else:
+            is_miss = pd.Series(False, index=df.index)
+
+        hits = df[~is_miss]
+        misses = df[is_miss]
+
+        # Prefill: dark blue (hit), dark orange (miss)
+        if not hits.empty:
+            plt.barh(
+                hits["prompt_id"],
+                hits["ttft_time"] - hits["request_start"],
+                left=hits["request_start"],
+                color="darkblue",
+                label="Loading",  # prefill hits
+            )
+        if not misses.empty:
+            plt.barh(
+                misses["prompt_id"],
+                misses["ttft_time"] - misses["request_start"],
+                left=misses["request_start"],
+                color="darkorange",
+                label="Compute",  # prefill misses
+            )
+
+        # Decode: light blue (hit), light orange (miss)
+        if not hits.empty:
+            plt.barh(
+                hits["prompt_id"],
+                hits["request_end"] - hits["ttft_time"],
+                left=hits["ttft_time"],
+                color="skyblue",
+                label="Decoding after loading",
+            )
+        if not misses.empty:
+            plt.barh(
+                misses["prompt_id"],
+                misses["request_end"] - misses["ttft_time"],
+                left=misses["ttft_time"],
+                color="pink",
+                label="Decoding after compute",
+            )
+
+        plt.xlabel("Time (s)")
+        plt.ylabel("Prompt ID")
+        plt.legend()
+        plt.tight_layout()
+        plt.savefig(filename)
+        plt.close()
+
+    plot_bars(warmup_df, "Warmup Round", "warmup_round.png")
+    plot_bars(benchmark_df, "Query Round", "query_round.png")
+
+
+def trimmed_mean(series: pd.Series, trim_fraction: float) -> float:
+    """
+    Exclude the smallest trim_fraction and largest trim_fraction and take mean
+    of the rest. If trim_fraction <= 0, returns normal mean.
+    """
+    s = series.dropna()
+    if len(s) == 0:
+        return float("nan")
+    if trim_fraction <= 0:
+        return float(s.mean())
+
+    if not (0.0 <= trim_fraction < 0.5):
+        raise ValueError("--trim-fraction must be in [0, 0.5).")
+
+    s = s.sort_values()
+    n = len(s)
+    k = int(n * trim_fraction)
+    if n - 2 * k <= 0:
+        return float(s.mean())
+    return float(s.iloc[k : n - k].mean())
+
+
+async def main(args):
+    random.seed(args.shuffle_seed)
+
+    # Create the OpenAI client
+    # No timeout: some benchmarks can take 4-5 minutes per request
+    base_url = get_url_from_args(args)
+    print("Using base URL:", base_url)
+
+    api_key = os.getenv("OPENAI_API_KEY", "sk-dummy")
+
+    client = AsyncOpenAI(
+        base_url=base_url,
+        api_key=api_key,
+        timeout=None,
+    )
+    model = args.model
+    if model == "auto":
+        print("Auto-selecting model...", end=" ")
+        models = (await client.models.list(),)
+        model = models[0].data[0].id
+        print(f"selected model: {model}")
+
+    pre_warmup_prompts = [str(i) + "xx" + " ".join(["hi"] * 1000) for i in range(5)]
+
+    await test_long_document_qa(
+        client=client,
+        model=model,
+        prompts=pre_warmup_prompts,
+        output_len=args.output_len,
+        max_inflight_requests=args.max_inflight_requests,
+    )
+
+    # Prepare the prompts:
+    # we append the document id at the beginning to avoid any of the document
+    # being the prefix of other documents
+    warmup_prompts = [
+        str(i) + " " + " ".join(["hi"] * args.document_length)
+        for i in range(args.num_documents)
+    ]
+
+    prompts = repeat_prompts(warmup_prompts, args.repeat_count, mode=args.repeat_mode)
+    prompts, miss_mask = add_cache_misses(prompts, args.hit_miss_ratio)
+
+    write_resp("------warm up round------\n")
+    warmup_start_time = time.time()
+    warmup_request_stats = await test_long_document_qa(
+        client=client,
+        model=model,
+        prompts=warmup_prompts,
+        output_len=args.output_len,
+        max_inflight_requests=args.max_inflight_requests,
+    )
+    warmup_end_time = time.time()
+    write_resp("------query round------\n")
+
+    sleep_time_after_warmup = args.sleep_time_after_warmup
+    if sleep_time_after_warmup > 0:
+        write_resp(f"Sleeping for {sleep_time_after_warmup} seconds after warmup...\n")
+        time.sleep(sleep_time_after_warmup)
+
+    benchmark_start_time = time.time()
+    benchmark_request_stats = await test_long_document_qa(
+        client=client,
+        model=model,
+        prompts=prompts,
+        output_len=args.output_len,
+        max_inflight_requests=args.max_inflight_requests,
+    )
+    benchmark_end_time = time.time()
+
+    warmup_df = pd.DataFrame([stats.__dict__ for stats in warmup_request_stats])
+    relative_time(warmup_df, warmup_start_time)
+    warmup_df["is_miss"] = True
+    benchmark_df = pd.DataFrame([stats.__dict__ for stats in benchmark_request_stats])
+    benchmark_df["is_miss"] = miss_mask
+    relative_time(benchmark_df, benchmark_start_time)
+
+    warmup_df.to_csv("warmup_round.csv", index=False)
+    benchmark_df.to_csv("query_round.csv", index=False)
+
+    # Print results
+    warmup_mean_ttft = trimmed_mean(
+        warmup_df.query("successful == True")["ttft"], args.trim_fraction
+    )
+    query_mean_ttft = trimmed_mean(
+        benchmark_df.query("successful == True")["ttft"], args.trim_fraction
+    )
+    warmup_success_count = warmup_df.query("successful == True").shape[0]
+    query_success_count = benchmark_df.query("successful == True").shape[0]
+    CSI = "\x1b["
+    RESET = CSI + "0m"
+    print(f"Warmup round mean TTFT: {warmup_mean_ttft:.3f}s")
+    print(f"Warmup round time: {warmup_end_time - warmup_start_time:.3f}s")
+    print(f"Warmup round prompt count: {len(warmup_df)}")
+    print(f"Warmup round successful prompt count: {warmup_success_count}")
+    print(f"{CSI}36;1m\n=== BENCHMARK RESULTS ==={RESET}")
+    print(f"{CSI}32mQuery round mean TTFT: {query_mean_ttft:.3f}s{RESET}")
+    print(
+        f"{CSI}33mQuery round time: "
+        f"{benchmark_end_time - benchmark_start_time:.3f}s{RESET}"
+    )
+    print(f"{CSI}35mQuery round prompt count: {len(benchmark_df)}{RESET}")
+    print(f"{CSI}34mQuery round successful prompt count: {query_success_count}{RESET}")
+
+    if visualize:
+        visualize_results(warmup_df, benchmark_df)
+
+    if args.json_output:
+        query_duration = benchmark_end_time - benchmark_start_time
+        query_round_time_per_prompt = query_duration / len(benchmark_df)
+        warmup_duration = warmup_end_time - warmup_start_time
+        warmup_round_time_per_prompt = warmup_duration / len(warmup_df)
+        # Standard
+        import json
+
+        summary = {
+            "query_ttft_per_prompt": query_mean_ttft,
+            "query_round_time_per_prompt": query_round_time_per_prompt,
+            "warmup_round_time_per_prompt": warmup_round_time_per_prompt,
+        }
+        print(json.dumps(summary))
+
+
+def create_argument_parser():
+    parser = argparse.ArgumentParser(
+        description="Benchmark the performance with or "
+        "without automatic prefix caching."
+    )
+
+    parser.add_argument(
+        "--document-length",
+        type=int,
+        # Roughly the number of tokens for a system paper,
+        # excluding images
+        default=20000,
+        help="Length of each document in tokens.",
+    )
+
+    parser.add_argument(
+        "--num-documents",
+        type=int,
+        default=8,
+        help="Number of documents to generate for testing.",
+    )
+
+    parser.add_argument(
+        "--output-len",
+        type=int,
+        default=100,
+        help="Maximum number of tokens to generate for each prompt.",
+    )
+
+    parser.add_argument(
+        "--repeat-count",
+        type=int,
+        default=2,
+        help="Number of times to repeat each prompt",
+    )
+
+    parser.add_argument(
+        "--repeat-mode",
+        type=str,
+        default="random",
+        help="The mode to repeat prompts. The supported "
+        'modes are "random", "tile", and "interleave". '
+        "See repeat_prompts() in the source code for details.",
+    )
+
+    parser.add_argument(
+        "--shuffle-seed",
+        type=int,
+        default=0,
+        help='Random seed when the repeat mode is "random"',
+    )
+
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=None,
+        help="Host to query the vLLM server",
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="Port to query the vLLM server",
+    )
+
+    parser.add_argument(
+        "--base-url",
+        type=str,
+        default=None,
+        help="Base URL to query the LLM server",
+    )
+
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="auto",
+        help="Model name, can be set to 'auto' if the "
+        "endpoint support openai api /models",
+    )
+
+    parser.add_argument(
+        "--max-inflight-requests",
+        type=int,
+        default=2,
+        help="Maximum number of concurrent inflight requests",
+    )
+
+    parser.add_argument(
+        "--sleep-time-after-warmup",
+        type=float,
+        default=0.0,
+        help="Sleep time after warm up iteration",
+    )
+
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        help="Filename to write all responses to; if omitted, writes to stdout.",
+    )
+
+    parser.add_argument(
+        "--completions",
+        action="store_true",
+        help="Use completions API instead of chat completions API",
+    )
+
+    parser.add_argument(
+        "--visualize",
+        action="store_true",
+        help="Visualize the results",
+    )
+
+    parser.add_argument(
+        "--hit-miss-ratio",
+        type=str,
+        default=None,
+        help=(
+            "In query round, control how many of the prompts will miss the cache."
+            "For example, 3:1 means every fourth repeated prompt will be randomized "
+            "to force a cache miss. 2:2 means 2 hits and 2 misses"
+        ),
+    )
+
+    parser.add_argument(
+        "--eos-token-id",
+        type=int,
+        default=None,
+        help=(
+            "EOS token id. we bias against this token id so we always "
+            "get the number of output tokens we specify"
+        ),
+    )
+
+    parser.add_argument(
+        "--json-output",
+        action="store_true",
+        help="Print benchmark summary as a single JSON line to stdout.",
+    )
+
+    parser.add_argument(
+        "--trim-fraction",
+        type=float,
+        default=0.0,
+        help=(
+            "Exclude the smallest and largest fraction of successful samples "
+            "before averaging. Example: 0.1 drops bottom 10% and top 10%."
+        ),
+    )
+
+    return parser
+
+
+def validate_args(args):
+    # Verify port and base_url are exclusive
+    has_host_port = args.host is not None and args.port is not None
+    has_base_url = args.base_url is not None
+    if has_host_port and has_base_url:
+        raise ValueError("Cannot use --host/--port and --base-url together.")
+
+
+if __name__ == "__main__":
+    parser = create_argument_parser()
+    args = parser.parse_args()
+    validate_args(args)
+    completions_mode = args.completions
+    visualize = args.visualize
+    if visualize:
+        # Third Party
+        import matplotlib.pyplot as plt
+    if args.eos_token_id is not None:
+        eos_token_id = args.eos_token_id
+    OUTPUT_FILE = args.output
+    asyncio.run(main(args))
diff --git a/benchmarks/long_doc_qa/long_doc_qa_recommender.py b/benchmarks/long_doc_qa/long_doc_qa_recommender.py
new file mode 100644
index 0000000..568517a
--- /dev/null
+++ b/benchmarks/long_doc_qa/long_doc_qa_recommender.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import math
+import re
+import resource
+import subprocess
+
+# Third Party
+from huggingface_hub import HfApi
+import psutil
+import torch
+
+
+def determine_per_gpu_memory():
+    if not torch.cuda.is_available():
+        raise RuntimeError("CUDA is not available")
+    total_memory = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+    return total_memory
+
+
+def get_tensor_parallel_recommendation(model_name: str):
+    api = HfApi()
+    info = api.model_info(model_name)
+    total_bits = 0
+    for dtype, num_weights in info.safetensors.parameters.items():
+        m = re.search(r"\d+", dtype)
+        assert m is not None, "No bits information found from the HF API"
+        num_bits_in_dtype = int(m.group())
+        total_bits = num_bits_in_dtype * num_weights
+        break
+    if total_bits == 0:
+        raise RuntimeError("No parameters found in the model")
+
+    total_model_weights_gb = total_bits / 8 / (1024**3)
+    print(f"Model weights total gb: {total_model_weights_gb}")
+
+    per_gpu_memory = determine_per_gpu_memory()
+    # 0.9 is the default gpu usage for vllm
+    intermediate_buffer = 5
+    minimum_kv_cache_buffer = 5
+    usable_per_gpu_memory = (
+        per_gpu_memory * 0.9 - intermediate_buffer - minimum_kv_cache_buffer
+    )
+    print(f"Usable gpu memory for model weights per gpu: {usable_per_gpu_memory}")
+    initial_tp = math.ceil(total_model_weights_gb / usable_per_gpu_memory)
+    # round up to a power of 2
+    return 2 ** math.ceil(math.log2(initial_tp))
+
+
+def get_prefix_cache_token_size(model_name: str, tp: int):
+    cmd = [
+        "python",
+        "-c",
+        f"from vllm import LLM; "
+        f"LLM(model='{model_name}', tensor_parallel_size={tp}, load_format='dummy')",
+    ]
+    result = subprocess.run(
+        cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True
+    )
+
+    # look for "GPU KV cache size:"
+    # Example:
+    # (EngineCore_0 pid=3166091) INFO 09-07 20:45:57
+    # [kv_cache_utils.py:849] GPU KV cache size: 420,928 tokens
+    # watch out if vllm ever changes their output logs in the future
+    m = re.search(r"GPU KV cache size:\s*([\d,]+)\s*tokens\b", result.stdout, re.I)
+    assert m is not None, "No GPU KV cache size found"
+    tokens_in_prefix_cache = int(m.group(1).replace(",", ""))
+    m = re.search(
+        r"Available KV cache memory:\s*([\d,.]+)\s*GiB\b", result.stdout, re.I
+    )
+    assert m is not None, "No Available KV cache memory found"
+    per_gpu_kv_cache_gb = float(m.group(1))
+    return per_gpu_kv_cache_gb, tokens_in_prefix_cache
+
+
+def print_vllm_deployment_string(model_name: str, tp: int):
+    print("\n\n1. vLLM Deployment: \n-----------------\n")
+    print(
+        f"PYTHONHASHSEED=0 \\\n"
+        f"vllm serve {model_name} \\\n"
+        f"--tensor-parallel-size {tp} \\\n"
+        f"--load-format dummy"
+    )
+
+
+def print_lmcache_deployment_string(
+    model_name: str, tp: int, cpu_offload_GiB_per_gpu: float
+):
+    print("\n\n2. LMCache Deployment: \n--------------------\n")
+    print(
+        f"PYTHONHASHSEED=0 \\\n"
+        f"LMCACHE_MAX_LOCAL_CPU_SIZE={int(cpu_offload_GiB_per_gpu)} \\\n"
+        f"vllm serve {model_name} \\\n"
+        f"--tensor-parallel-size {tp} \\\n"
+        f"--load-format dummy \\\n"
+        f"--kv-transfer-config \\\n"
+        f'\'{{"kv_connector": "LMCacheConnectorV1", "kv_role": "kv_both"}}\''
+    )
+
+
+def print_long_doc_qa_workload_string(model_name: str, tokens_in_offload_cache: int):
+    document_length = 10000
+    output_length = 100
+    num_documents = int(tokens_in_offload_cache / (document_length + output_length)) - 2
+    print(
+        "\n\n"
+        "3. Multi-Round QA Workload Generation: \n"
+        "----------------------------------------\n"
+    )
+    print(
+        f"python benchmarks/long_doc_qa/long_doc_qa.py \\\n"
+        f"--model {model_name} \\\n"
+        f"--num-documents {num_documents} \\\n"
+        f"--document-length {document_length} \\\n"
+        f"--output-len {output_length} \\\n"
+        f"--repeat-count 1 \\\n"
+        f"--repeat-mode tile \\\n"
+        f"--max-inflight-requests 4"
+    )
+
+
+def get_cpu_offload_GiB_per_gpu(
+    per_gpu_kv_cache_GiB: float, GiB_1K_tokens_per_gpu: float, tp: int
+):
+    vm = psutil.virtual_memory()
+    available_pinnable_cpu_size_GiB = vm.available / 1024**3 / tp
+    # `import resource` should be added at the top of the file.
+    # The `resource` module is not available on Windows.
+    memlock_limit_bytes, _ = resource.getrlimit(resource.RLIMIT_MEMLOCK)
+    if memlock_limit_bytes != resource.RLIM_INFINITY:
+        print(f"OS restricts pinnable CPU size to {memlock_limit_bytes} bytes")
+        memlock_GiB = memlock_limit_bytes / (1024**3) / tp
+        available_pinnable_cpu_size_GiB = min(
+            available_pinnable_cpu_size_GiB, memlock_GiB
+        )
+    else:
+        print("You have unlimited pinnable CPU size")
+    # try to allocate space for 120000 additional tokens
+    DESIRED_ADDITIONAL_TOKENS_IN_OFFLOAD = 120_000
+    desired_offload_GiB = (
+        DESIRED_ADDITIONAL_TOKENS_IN_OFFLOAD / 1000 * GiB_1K_tokens_per_gpu
+        + per_gpu_kv_cache_GiB
+    )
+    offload_GiB_per_gpu = min(desired_offload_GiB, available_pinnable_cpu_size_GiB)
+    return offload_GiB_per_gpu
+
+
+def main(model_name: str):
+    tp = get_tensor_parallel_recommendation(model_name)
+    print(f"Tensor Parallel Recommendation: {tp}")
+    if torch.cuda.device_count() < tp:
+        print(
+            f"Warning: You have {torch.cuda.device_count()} GPUs, "
+            f"but {model_name} requires {tp} tensor parallelism to run on your hardware"
+        )
+        return
+    print("This will take a while...")
+    per_gpu_kv_cache_GiB, tokens_in_prefix_cache = get_prefix_cache_token_size(
+        model_name, tp
+    )
+    print(f"Tokens in prefix cache: {tokens_in_prefix_cache}")
+    print(f"Per GPU KV cache GiB: {per_gpu_kv_cache_GiB}")
+    GiB_1K_tokens_per_gpu = per_gpu_kv_cache_GiB / tokens_in_prefix_cache * 1000
+    print(f"GiB / 1K tokens per gpu: {GiB_1K_tokens_per_gpu}")
+    cpu_offload_GiB_per_gpu = get_cpu_offload_GiB_per_gpu(
+        per_gpu_kv_cache_GiB, GiB_1K_tokens_per_gpu, tp
+    )
+    if per_gpu_kv_cache_GiB >= cpu_offload_GiB_per_gpu:
+        print(
+            "Warning: Your system does not have enough available pinnable CPU RAM "
+            "to make use of KV Cache CPU offloading"
+        )
+        return
+    tokens_in_offload_cache = int(
+        cpu_offload_GiB_per_gpu * (1 / GiB_1K_tokens_per_gpu) * 1000
+    )
+    print(f"Total tokens storable: {tokens_in_offload_cache}")
+
+    print_vllm_deployment_string(model_name, tp)
+    print_lmcache_deployment_string(model_name, tp, cpu_offload_GiB_per_gpu)
+    print_long_doc_qa_workload_string(model_name, tokens_in_offload_cache)
+
+
+def build_argument_parser():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", type=str, default="Qwen/Qwen3-8B")
+    return parser
+
+
+if __name__ == "__main__":
+    parser = build_argument_parser()
+    args = parser.parse_args()
+    main(args.model)
diff --git a/benchmarks/microbenchmark/bitmap_ops_benchmark.py b/benchmarks/microbenchmark/bitmap_ops_benchmark.py
new file mode 100644
index 0000000..2a08978
--- /dev/null
+++ b/benchmarks/microbenchmark/bitmap_ops_benchmark.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Microbenchmark for the ranked fold (:func:`fold_unfold_ranked`).
+
+Compares the pure-Python reference against the native C++ implementation across
+request sizes, including a DeepSeek-scale hybrid case (1M tokens, 8 object
+groups mixing full attention and sliding window). Run with::
+
+    python benchmarks/microbenchmark/bitmap_ops_benchmark.py
+
+The native op scans the packed ``Bitmap`` buffer directly -- no Python per-bit
+loop and no ``Bitmap``<->tensor conversion -- so it stays sub-millisecond even
+at multi-million-key scale where the Python scan takes hundreds of ms.
+"""
+
+# Standard
+from collections.abc import Sequence
+import time
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.bitmap_ops import fold_unfold_ranked, highest_set_bit
+from lmcache.v1.distributed.bitmap_ops.fold import _fold_python, _unfold_python
+
+
+def _python_pipeline(found, num_chunks, num_ranks, group_windows):
+    """Pure-Python fold -> highest_set_bit -> unfold (no native ops)."""
+    servable = _fold_python(found, num_chunks, num_ranks, group_windows)
+    hit = highest_set_bit(servable) + 1  # -1 (no servable prefix) -> 0
+    return hit, _unfold_python(hit, num_chunks, num_ranks, group_windows)
+
+
+def _best_ms(fn, reps: int) -> float:
+    """Best wall-clock time of ``fn`` over ``reps`` runs, in milliseconds."""
+    best = float("inf")
+    for _ in range(reps):
+        start = time.perf_counter()
+        fn()
+        best = min(best, time.perf_counter() - start)
+    return best * 1e3
+
+
+def bench_case(
+    label: str,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+    present_fraction: float,
+    reps: int = 5,
+) -> None:
+    """Print Python vs native timings for one (size, fill) configuration."""
+    num_keys = len(group_windows) * num_chunks * num_ranks
+    if present_fraction >= 1.0:
+        found = Bitmap(num_keys, num_keys)
+    else:
+        found = Bitmap(num_keys, int(num_keys * present_fraction))
+
+    windows = list(group_windows)
+    py_ms = _best_ms(
+        lambda: _python_pipeline(found, num_chunks, num_ranks, windows),
+        reps,
+    )
+    native_ms = _best_ms(
+        lambda: fold_unfold_ranked(found, num_chunks, num_ranks, windows),
+        reps,
+    )
+    speedup = py_ms / native_ms if native_ms else float("inf")
+    print(
+        f"{label:<34}keys={num_keys:>9}  python={py_ms:>9.2f}ms  "
+        f"native={native_ms:>8.3f}ms  speedup={speedup:>7.1f}x"
+    )
+
+
+def main() -> None:
+    """Run the benchmark grid."""
+    # 8 groups, mix of full attention and sliding window (DeepSeek-like hybrid).
+    dpsk_windows = (-1, -1, -1, -1, 4, 4, 8, 1)
+
+    print("== DeepSeek 1M tokens @ chunk_size=256 (num_chunks=4096), all present ==")
+    bench_case("dpsk, world_size=1", 4096, 1, dpsk_windows, 1.0)
+    bench_case("dpsk, world_size=8", 4096, 8, dpsk_windows, 1.0)
+
+    print("\n== same, 50% prefix present (realistic) ==")
+    bench_case("dpsk, world_size=8", 4096, 8, dpsk_windows, 0.5)
+
+    print("\n== small request ==")
+    bench_case("4K tokens @256 (16 chunks)", 16, 8, dpsk_windows, 1.0)
+
+    print("\n== stress: chunk_size=16 -> 62500 chunks (4M keys) ==")
+    bench_case("stress, world_size=8", 62500, 8, dpsk_windows, 1.0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/microbenchmark/ttl_lock_benchmark.py b/benchmarks/microbenchmark/ttl_lock_benchmark.py
new file mode 100644
index 0000000..2257727
--- /dev/null
+++ b/benchmarks/microbenchmark/ttl_lock_benchmark.py
@@ -0,0 +1,541 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""
+Performance benchmark for TTLLock.
+
+This script tests the performance overhead of TTLLock under realistic conditions:
+- 100K different TTLLock objects
+- 10K+ lock/unlock operations per second
+- 4-8 threads accessing different locks concurrently
+
+Usage:
+    python benchmarks/ttl_lock_benchmark.py [--num-locks NUM] [--threads THREADS]
+                                            [--duration SECONDS] [--ops-per-batch OPS]
+"""
+
+# Standard
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Callable
+import argparse
+import random
+import statistics
+import threading
+import time
+
+# First Party
+from lmcache.native_storage_ops import TTLLock
+
+
+@dataclass
+class BenchmarkResult:
+    """Results from a benchmark run."""
+
+    name: str
+    num_threads: int
+    num_locks: int
+    duration_seconds: float
+    total_operations: int
+    operations_per_second: float
+    avg_latency_us: float
+    p50_latency_us: float
+    p95_latency_us: float
+    p99_latency_us: float
+    min_latency_us: float
+    max_latency_us: float
+
+    def __str__(self) -> str:
+        return (
+            f"\n{'=' * 60}\n"
+            f"Benchmark: {self.name}\n"
+            f"{'=' * 60}\n"
+            f"Configuration:\n"
+            f"  Threads:     {self.num_threads}\n"
+            f"  Lock objects: {self.num_locks:,}\n"
+            f"  Duration:    {self.duration_seconds:.2f}s\n"
+            f"\nThroughput:\n"
+            f"  Total ops:   {self.total_operations:,}\n"
+            f"  Ops/second:  {self.operations_per_second:,.0f}\n"
+            f"\nLatency (microseconds):\n"
+            f"  Average:     {self.avg_latency_us:.2f} us\n"
+            f"  P50:         {self.p50_latency_us:.2f} us\n"
+            f"  P95:         {self.p95_latency_us:.2f} us\n"
+            f"  P99:         {self.p99_latency_us:.2f} us\n"
+            f"  Min:         {self.min_latency_us:.2f} us\n"
+            f"  Max:         {self.max_latency_us:.2f} us\n"
+        )
+
+
+class TTLLockBenchmark:
+    """Benchmark suite for TTLLock performance testing."""
+
+    def __init__(
+        self,
+        num_locks: int = 100_000,
+        default_threads: int = 4,
+        default_duration: float = 5.0,
+    ):
+        self.num_locks = num_locks
+        self.default_threads = default_threads
+        self.default_duration = default_duration
+        self.locks: list[TTLLock] = []
+
+    def setup(self):
+        """Initialize the lock objects."""
+        print(f"Creating {self.num_locks:,} TTLLock objects...")
+        start = time.perf_counter()
+        self.locks = [TTLLock() for _ in range(self.num_locks)]
+        elapsed = time.perf_counter() - start
+        print(
+            f"Created {self.num_locks:,} locks in {elapsed:.3f}s "
+            f"({self.num_locks / elapsed:,.0f} locks/sec)"
+        )
+        print()
+
+    def _run_benchmark(
+        self,
+        name: str,
+        worker_fn: Callable[[int, list[float], threading.Event], None],
+        num_threads: int,
+        duration: float,
+    ) -> BenchmarkResult:
+        """Run a benchmark with the given worker function."""
+        stop_event = threading.Event()
+        latencies_per_thread: list[list[float]] = [[] for _ in range(num_threads)]
+        ops_count = [0] * num_threads
+
+        def timed_worker(thread_id: int):
+            local_latencies = latencies_per_thread[thread_id]
+            worker_fn(thread_id, local_latencies, stop_event)
+            ops_count[thread_id] = len(local_latencies)
+
+        # Start workers
+        threads = []
+        start_time = time.perf_counter()
+
+        for i in range(num_threads):
+            t = threading.Thread(target=timed_worker, args=(i,))
+            t.start()
+            threads.append(t)
+
+        # Let benchmark run for specified duration
+        time.sleep(duration)
+        stop_event.set()
+
+        # Wait for all threads to finish
+        for t in threads:
+            t.join()
+
+        end_time = time.perf_counter()
+        actual_duration = end_time - start_time
+
+        # Aggregate results
+        all_latencies = []
+        for lat_list in latencies_per_thread:
+            all_latencies.extend(lat_list)
+
+        total_ops = sum(ops_count)
+
+        if not all_latencies:
+            return BenchmarkResult(
+                name=name,
+                num_threads=num_threads,
+                num_locks=self.num_locks,
+                duration_seconds=actual_duration,
+                total_operations=0,
+                operations_per_second=0,
+                avg_latency_us=0,
+                p50_latency_us=0,
+                p95_latency_us=0,
+                p99_latency_us=0,
+                min_latency_us=0,
+                max_latency_us=0,
+            )
+
+        # Convert to microseconds
+        latencies_us = [lat * 1_000_000 for lat in all_latencies]
+        latencies_us.sort()
+
+        p50_idx = int(len(latencies_us) * 0.50)
+        p95_idx = int(len(latencies_us) * 0.95)
+        p99_idx = int(len(latencies_us) * 0.99)
+
+        return BenchmarkResult(
+            name=name,
+            num_threads=num_threads,
+            num_locks=self.num_locks,
+            duration_seconds=actual_duration,
+            total_operations=total_ops,
+            operations_per_second=total_ops / actual_duration,
+            avg_latency_us=statistics.mean(latencies_us),
+            p50_latency_us=latencies_us[p50_idx],
+            p95_latency_us=latencies_us[p95_idx],
+            p99_latency_us=latencies_us[min(p99_idx, len(latencies_us) - 1)],
+            min_latency_us=latencies_us[0],
+            max_latency_us=latencies_us[-1],
+        )
+
+    def benchmark_lock_only(
+        self, num_threads: int | None = None, duration: float | None = None
+    ) -> BenchmarkResult:
+        """Benchmark lock() operations only."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+        num_locks = self.num_locks
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            # Each thread accesses a different range of locks to reduce contention
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                lock_idx = rng.randint(0, num_locks - 1)
+                start = time.perf_counter()
+                self.locks[lock_idx].lock()
+                elapsed = time.perf_counter() - start
+                latencies.append(elapsed)
+
+        return self._run_benchmark("lock() only", worker, num_threads, duration)
+
+    def benchmark_unlock_only(
+        self, num_threads: int | None = None, duration: float | None = None
+    ) -> BenchmarkResult:
+        """Benchmark unlock() operations only."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+        num_locks = self.num_locks
+
+        # Pre-lock all locks
+        for lock in self.locks:
+            for _ in range(100):  # Lock each 100 times to have room for unlocks
+                lock.lock()
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                lock_idx = rng.randint(0, num_locks - 1)
+                start = time.perf_counter()
+                self.locks[lock_idx].unlock()
+                elapsed = time.perf_counter() - start
+                latencies.append(elapsed)
+
+        result = self._run_benchmark("unlock() only", worker, num_threads, duration)
+
+        # Reset locks for next benchmark
+        for lock in self.locks:
+            lock.reset()
+
+        return result
+
+    def benchmark_is_locked_only(
+        self, num_threads: int | None = None, duration: float | None = None
+    ) -> BenchmarkResult:
+        """Benchmark is_locked() operations only (read-only)."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+        num_locks = self.num_locks
+
+        # Pre-lock half the locks
+        for i, lock in enumerate(self.locks):
+            if i % 2 == 0:
+                lock.lock()
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                lock_idx = rng.randint(0, num_locks - 1)
+                start = time.perf_counter()
+                _ = self.locks[lock_idx].is_locked()
+                elapsed = time.perf_counter() - start
+                latencies.append(elapsed)
+
+        result = self._run_benchmark("is_locked() only", worker, num_threads, duration)
+
+        # Reset locks for next benchmark
+        for lock in self.locks:
+            lock.reset()
+
+        return result
+
+    def benchmark_lock_unlock_pair(
+        self, num_threads: int | None = None, duration: float | None = None
+    ) -> BenchmarkResult:
+        """Benchmark lock() + unlock() pairs (typical usage pattern)."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+        num_locks = self.num_locks
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                lock_idx = rng.randint(0, num_locks - 1)
+                start = time.perf_counter()
+                self.locks[lock_idx].lock()
+                self.locks[lock_idx].unlock()
+                elapsed = time.perf_counter() - start
+                latencies.append(elapsed)
+
+        return self._run_benchmark(
+            "lock() + unlock() pair", worker, num_threads, duration
+        )
+
+    def benchmark_mixed_operations(
+        self, num_threads: int | None = None, duration: float | None = None
+    ) -> BenchmarkResult:
+        """Benchmark mixed operations (realistic workload)."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+        num_locks = self.num_locks
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                lock_idx = rng.randint(0, num_locks - 1)
+                op = rng.randint(0, 9)
+
+                start = time.perf_counter()
+                if op < 4:  # 40% lock
+                    self.locks[lock_idx].lock()
+                elif op < 8:  # 40% unlock
+                    self.locks[lock_idx].unlock()
+                else:  # 20% is_locked
+                    _ = self.locks[lock_idx].is_locked()
+                elapsed = time.perf_counter() - start
+                latencies.append(elapsed)
+
+        return self._run_benchmark("mixed operations", worker, num_threads, duration)
+
+    def benchmark_high_contention(
+        self, num_threads: int | None = None, duration: float | None = None
+    ) -> BenchmarkResult:
+        """Benchmark with high contention (few locks, many threads)."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+
+        # Use only 100 locks for high contention
+        hot_locks = 100
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                lock_idx = rng.randint(0, hot_locks - 1)
+                start = time.perf_counter()
+                self.locks[lock_idx].lock()
+                self.locks[lock_idx].unlock()
+                elapsed = time.perf_counter() - start
+                latencies.append(elapsed)
+
+        result = self._run_benchmark(
+            f"high contention ({hot_locks} locks)", worker, num_threads, duration
+        )
+
+        # Reset the hot locks
+        for i in range(hot_locks):
+            self.locks[i].reset()
+
+        return result
+
+    def benchmark_batch_operations(
+        self,
+        num_threads: int | None = None,
+        duration: float | None = None,
+        batch_size: int = 100,
+    ) -> BenchmarkResult:
+        """Benchmark batch lock operations (lock multiple, then unlock multiple)."""
+        num_threads = num_threads or self.default_threads
+        duration = duration or self.default_duration
+        num_locks = self.num_locks
+
+        def worker(thread_id: int, latencies: list[float], stop: threading.Event):
+            rng = random.Random(thread_id)
+            while not stop.is_set():
+                # Pick a batch of random lock indices
+                indices = [rng.randint(0, num_locks - 1) for _ in range(batch_size)]
+
+                # Lock all
+                start = time.perf_counter()
+                for idx in indices:
+                    self.locks[idx].lock()
+                for idx in indices:
+                    self.locks[idx].unlock()
+                elapsed = time.perf_counter() - start
+
+                # Record per-operation latency
+                per_op_latency = elapsed / (batch_size * 2)
+                for _ in range(batch_size * 2):
+                    latencies.append(per_op_latency)
+
+        return self._run_benchmark(
+            f"batch operations (batch={batch_size})", worker, num_threads, duration
+        )
+
+    def run_all_benchmarks(
+        self, thread_counts: list[int] | None = None, duration: float | None = None
+    ) -> list[BenchmarkResult]:
+        """Run all benchmarks for specified thread counts."""
+        if thread_counts is None:
+            thread_counts = [1, 2, 4, 8]
+        if duration is None:
+            duration = self.default_duration
+
+        results = []
+
+        for num_threads in thread_counts:
+            print(f"\n{'#' * 60}")
+            print(f"# Running benchmarks with {num_threads} threads")
+            print(f"{'#' * 60}")
+
+            # Run each benchmark
+            benchmarks = [
+                ("lock_only", self.benchmark_lock_only),
+                ("unlock_only", self.benchmark_unlock_only),
+                ("is_locked_only", self.benchmark_is_locked_only),
+                ("lock_unlock_pair", self.benchmark_lock_unlock_pair),
+                ("mixed_operations", self.benchmark_mixed_operations),
+                ("high_contention", self.benchmark_high_contention),
+                ("batch_operations", self.benchmark_batch_operations),
+            ]
+
+            for name, benchmark_fn in benchmarks:
+                print(f"\nRunning: {name}...")
+                result = benchmark_fn(  # type: ignore
+                    num_threads=num_threads, duration=duration
+                )
+                results.append(result)
+                print(result)
+
+        return results
+
+
+def print_summary_table(results: list[BenchmarkResult]):
+    """Print a summary comparison table."""
+    print("\n" + "=" * 100)
+    print("SUMMARY TABLE")
+    print("=" * 100)
+
+    # Group by benchmark name
+    by_name: dict[str, list[BenchmarkResult]] = defaultdict(list)
+    for r in results:
+        by_name[r.name].append(r)
+
+    # Print header
+    thread_counts = sorted(set(r.num_threads for r in results))
+    header = f"{'Benchmark':<30}"
+    for t in thread_counts:
+        header += f" | {t} threads (ops/s)"
+    print(header)
+    print("-" * 100)
+
+    # Print each benchmark
+    for name in by_name:
+        row = f"{name:<30}"
+        results_by_threads = {r.num_threads: r for r in by_name[name]}
+        for t in thread_counts:
+            if t in results_by_threads:
+                ops = results_by_threads[t].operations_per_second
+                row += f" | {ops:>15,.0f}"
+            else:
+                row += f" | {'N/A':>15}"
+        print(row)
+
+    print("=" * 100)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Performance benchmark for TTLLock",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--num-locks",
+        type=int,
+        default=100_000,
+        help="Number of TTLLock objects to create",
+    )
+    parser.add_argument(
+        "--threads",
+        type=str,
+        default="1,2,4,8",
+        help="Comma-separated list of thread counts to test",
+    )
+    parser.add_argument(
+        "--duration",
+        type=float,
+        default=5.0,
+        help="Duration in seconds for each benchmark",
+    )
+    parser.add_argument(
+        "--quick",
+        action="store_true",
+        help="Run quick benchmarks (1 second each, fewer thread counts)",
+    )
+
+    args = parser.parse_args()
+
+    thread_counts = [int(t.strip()) for t in args.threads.split(",")]
+    duration = args.duration
+
+    if args.quick:
+        thread_counts = [4, 8]
+        duration = 1.0
+
+    print("=" * 60)
+    print("TTLLock Performance Benchmark")
+    print("=" * 60)
+    print(f"Number of locks: {args.num_locks:,}")
+    print(f"Thread counts:   {thread_counts}")
+    print(f"Duration:        {duration}s per benchmark")
+    print()
+
+    benchmark = TTLLockBenchmark(
+        num_locks=args.num_locks,
+        default_threads=thread_counts[0],
+        default_duration=duration,
+    )
+
+    benchmark.setup()
+    results = benchmark.run_all_benchmarks(
+        thread_counts=thread_counts, duration=duration
+    )
+
+    print_summary_table(results)
+
+    # Print key findings
+    print("\nKEY FINDINGS:")
+    print("-" * 60)
+
+    # Find best throughput
+    best = max(results, key=lambda r: r.operations_per_second)
+    print(
+        f"Best throughput: {best.operations_per_second:,.0f} ops/sec "
+        f"({best.name}, {best.num_threads} threads)"
+    )
+
+    # Find typical workload performance
+    mixed_results = [r for r in results if "mixed" in r.name]
+    if mixed_results:
+        for r in mixed_results:
+            print(
+                f"Mixed workload ({r.num_threads} threads): "
+                f"{r.operations_per_second:,.0f} ops/sec, "
+                f"avg latency: {r.avg_latency_us:.2f}us"
+            )
+
+    # Check if we can sustain 10K+ ops/sec with 4-8 threads
+    target_ops = 10_000
+    for t in [4, 8]:
+        mixed = [r for r in results if "mixed" in r.name and r.num_threads == t]
+        if mixed:
+            r = mixed[0]
+            if r.operations_per_second >= target_ops:
+                print(
+                    f"✓ {t} threads can sustain {target_ops:,}+ ops/sec "
+                    f"(achieved: {r.operations_per_second:,.0f})"
+                )
+            else:
+                print(
+                    f"✗ {t} threads cannot sustain {target_ops:,} ops/sec "
+                    f"(achieved: {r.operations_per_second:,.0f})"
+                )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/multi_doc_qa/README.md b/benchmarks/multi_doc_qa/README.md
new file mode 100644
index 0000000..4cbc1c5
--- /dev/null
+++ b/benchmarks/multi_doc_qa/README.md
@@ -0,0 +1,30 @@
+# Benchmarking CacheBlend with Muti-Doc QA
+
+## Overview
+The benchmark contains two request rounds. The first round (warmup round) sends each document as a single prompt. The second round randomly samples a certain number of preprocessed documents and concatenate them together for each request.
+
+## Run the benchmarking
+
+### Step 1: Start the serving engine
+
+**Baseline1: vLLM**
+```bash
+vllm serve mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000
+```
+
+**Baseline2: vLLM + vanilla LMCache**
+
+```bash
+LMCACHE_CONFIG_FILE=lmcache.yaml vllm serve mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+**vLLM + LMCache with blending**
+
+```bash
+LMCACHE_CONFIG_FILE=lmcache_blend.yaml vllm serve mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000 --no-enable-prefix-caching --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+### Step 2: Send the requests
+```bash
+python multi_doc_qa.py --num-total-documents 100 --document-length 3000 --output-len 1 --num-requests 100 --num-docs-per-request 5 --model mistralai/Mistral-7B-Instruct-v0.2 --port 8000 --max-inflight-requests 1 
+```
\ No newline at end of file
diff --git a/benchmarks/multi_doc_qa/lmcache.yaml b/benchmarks/multi_doc_qa/lmcache.yaml
new file mode 100644
index 0000000..5c7b30c
--- /dev/null
+++ b/benchmarks/multi_doc_qa/lmcache.yaml
@@ -0,0 +1 @@
+max_local_cpu_size: 60
\ No newline at end of file
diff --git a/benchmarks/multi_doc_qa/lmcache_blend.yaml b/benchmarks/multi_doc_qa/lmcache_blend.yaml
new file mode 100644
index 0000000..b22e496
--- /dev/null
+++ b/benchmarks/multi_doc_qa/lmcache_blend.yaml
@@ -0,0 +1,6 @@
+max_local_cpu_size: 60
+
+enable_blending: True
+blend_special_str: " # # "
+use_layerwise: True
+
diff --git a/benchmarks/multi_doc_qa/multi_doc_qa.py b/benchmarks/multi_doc_qa/multi_doc_qa.py
new file mode 100644
index 0000000..b1115db
--- /dev/null
+++ b/benchmarks/multi_doc_qa/multi_doc_qa.py
@@ -0,0 +1,495 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# Adapted from
+# https://github.com/vllm-project/vllm/blob/main/benchmarks/benchmark_long_document_qa_throughput.py
+
+"""
+Commandline arguments:
+    --num-total-documents: The number of documents to sample prompts from.
+
+    --document-length: The length of each document in tokens.
+                       (Optional, default: 20000)
+
+    --output-len: The number of tokens to generate for each prompt.
+                  (Optional, default: 100)
+
+    --num-requests: The number of requests to send.
+
+    --num-docs-per-request: The number of documents to use in each prompt.
+
+    --sampling-strategy: The sampling strategy to use. Currently only supports
+                         "random".
+
+    --random-seed: Random seed when the repeat mode is "random".
+                    (Optional, default: 0)
+
+    --blend-special-str: The special string to use for blending documents.
+                         (Optional, default: " # # ")
+
+    --port: Port to query the vLLM server
+
+    --model: Model name
+
+    --max-inflight-requests: Maximum number of in-flight requests. Default is 2
+
+    --sleep-time-after-warmup: Sleep time after warm up iteration.
+                              (Optional, default: 0.0 seconds)
+
+    --output: Filename to write all responses to. If omitted, writes to stdout.
+
+    --expected-ttft-gain: Expected minimum speed-up in time-to-first-token
+                         (warmup/query) as a factor, e.g. 4.3 for 4.3×. If
+                         actual gain is below this, exits.
+
+    --expected-latency-gain: Expected minimum speed-up in total round time
+                            (warmup/query) as a factor, e.g. 4.5 for 4.5×.
+                            If actual gain is below this, exits.
+"""
+
+# Standard
+import argparse
+import asyncio
+import random
+import sys
+import time
+
+# Third Party
+from openai import AsyncOpenAI
+from transformers import AutoTokenizer
+
+# Global output filename (set in __main__)
+OUTPUT_FILE = None
+
+
+def has_content(chunk):
+    """
+    Check if the chunk has content in the choices.
+    Args:
+        chunk: The response chunk from OpenAI API.
+
+    Returns:
+        bool: True if content exists, False otherwise.
+    """
+    return chunk.choices and chunk.choices[0].text
+
+
+def extract_content(chunk):
+    """
+    Extract content from the response chunk.
+    Args:
+        chunk: The response chunk from OpenAI API.
+    Returns:
+        str: The content extracted from the chunk.
+    """
+    if chunk.choices[0].text is not None:
+        return chunk.choices[0].text
+    else:
+        return ""
+
+
+def write_resp(text: str):
+    """
+    Write text to the specified output file (if any), otherwise to stdout.
+    """
+    if OUTPUT_FILE:
+        with open(OUTPUT_FILE, "a") as resp_file:
+            resp_file.write(text)
+    else:
+        sys.stdout.write(text)
+
+
+async def process_single_prompt(
+    client, model, prompt, prompt_index, total_prompts, output_len, semaphore
+):
+    """
+    Process a single prompt with the given client and model.
+
+    Args:
+        client: The OpenAI client for making API calls.
+        model: The model name to use for generation.
+        prompt: The prompt string to be processed.
+        prompt_index: Index of the current prompt (0-based).
+        total_prompts: Total number of prompts being processed.
+        output_len: The maximum number of tokens to generate.
+        semaphore: Asyncio semaphore to limit concurrent requests.
+
+    Returns:
+        float: Time-to-first-token measurement
+    """
+    async with semaphore:  # Acquire semaphore to limit concurrent requests
+        write_resp(f"\n--- Sending prompt {prompt_index + 1}/{total_prompts} ---\n")
+        start_time = time.time()
+        first_token_time = None
+        words = ""
+
+        response = await client.completions.create(
+            model=model,
+            prompt=prompt,
+            max_tokens=output_len,
+            temperature=0.0,
+            stream=True,
+            extra_body={"ignore_eos": True},
+        )
+
+        responses = []
+        # Collect the response chunks
+        async for chunk in response:
+            if not chunk.choices:
+                continue
+
+            # Handle content for chat completions
+            if has_content(chunk):
+                content = extract_content(chunk)
+                if first_token_time is None and content != "":
+                    first_token_time = time.time()
+                responses.append(content)
+                words += content
+
+        final_response = "".join(responses)
+        write_resp(f"\nResponse of request {prompt_index}: {final_response}\n")
+
+        if first_token_time is not None:
+            return first_token_time - start_time
+        else:
+            # If no content was generated, return a default value
+            return 0.0
+
+
+async def test_long_document_qa(
+    client, model, prompts=None, output_len=100, max_inflight_requests=10
+):
+    """
+    Test long document QA with the given prompts and sampling parameters.
+    Process prompts concurrently with a limit on inflight requests.
+
+    Args:
+        client: The OpenAI client for making API calls.
+        model: The model name to use for generation.
+        prompts: A list of prompt strings to be processed by the LLM.
+        output_len: The maximum number of tokens to generate.
+        max_inflight_requests: Maximum number of concurrent requests.
+
+    Returns:
+        list: ttfts - a list of time-to-first-token measurements
+    """
+    # Create semaphore to limit concurrent requests
+    semaphore = asyncio.Semaphore(max_inflight_requests)
+
+    # Create tasks for all prompts
+    tasks = []
+    for i, prompt in enumerate(prompts):
+        task = process_single_prompt(
+            client=client,
+            model=model,
+            prompt=prompt,
+            prompt_index=i,
+            total_prompts=len(prompts),
+            output_len=output_len,
+            semaphore=semaphore,
+        )
+        tasks.append(task)
+
+    # Execute all tasks concurrently and collect results
+    ttfts = await asyncio.gather(*tasks)
+
+    return ttfts
+
+
+def generate_warmup_prompt_ids(
+    doc_prompts, sys_prompts, query_prompts, blend_special_str, tokenizer, offset=1
+):
+    blend_special_ids = tokenizer.encode(blend_special_str)[offset:]
+    warmup_prompt_ids = []
+    for doc_prompt, sys_prompt, query_prompt in zip(
+        doc_prompts, sys_prompts, query_prompts, strict=False
+    ):
+        sys_prompt_ids = tokenizer.encode(sys_prompt)
+        doc_prompt_ids = tokenizer.encode(doc_prompt)[offset:]
+        query_prompt_ids = tokenizer.encode(query_prompt)[offset:]
+        warmup_prompt_ids.append(
+            sys_prompt_ids
+            + blend_special_ids
+            + doc_prompt_ids
+            + blend_special_ids
+            + query_prompt_ids
+        )
+    return warmup_prompt_ids
+
+
+def generate_prompt_ids(
+    doc_prompts: list[str],
+    sys_prompts: list[str],
+    query_prompts: list[str],
+    num_requests: int,
+    num_docs_per_request: int,
+    blend_special_str: str,
+    tokenizer,
+    offset: int = 1,
+):
+    blend_special_ids = tokenizer.encode(blend_special_str)[offset:]
+
+    prompt_ids = []
+
+    for i in range(num_requests):
+        temp_prompt_ids = []
+        sample_docs = random.sample(doc_prompts, num_docs_per_request)
+        sample_docs_ids = [tokenizer.encode(doc)[offset:] for doc in sample_docs]
+        sys_prompt_ids = tokenizer.encode(sys_prompts[i])
+        query_prompt_ids = tokenizer.encode(query_prompts[i])[offset:]
+        temp_prompt_ids += sys_prompt_ids
+        for doc_ids in sample_docs_ids:
+            temp_prompt_ids += blend_special_ids + doc_ids
+        temp_prompt_ids += blend_special_ids + query_prompt_ids
+
+        prompt_ids.append(temp_prompt_ids)
+
+    return prompt_ids
+
+
+async def main(args):
+    random.seed(args.random_seed)
+
+    # Create the OpenAI client
+    client = AsyncOpenAI(
+        base_url=f"http://localhost:{args.port}/v1", api_key="sk-dummy"
+    )
+    model = args.model
+    blend_special_str = args.blend_special_str
+    num_requests = args.num_requests
+    num_docs_per_request = args.num_docs_per_request
+    document_length = args.document_length
+    num_total_documents = args.num_total_documents
+
+    tokenizer = AutoTokenizer.from_pretrained(args.model)
+
+    doc_prompts = [
+        str(i) + " " + " ".join(["hi"] * document_length)
+        for i in range(num_total_documents)
+    ]
+    warmup_sys_prompts = ["You are a helpful assistant."] * num_total_documents
+    warmup_query_prompts = ["What's up? how are you recently?"] * num_total_documents
+
+    warmup_prompt_ids = generate_warmup_prompt_ids(
+        doc_prompts,
+        warmup_sys_prompts,
+        warmup_query_prompts,
+        blend_special_str,
+        tokenizer,
+        offset=1,
+    )
+
+    sys_prompts = ["You are a helpful assistant."] * num_requests
+    query_prompts = ["What's up? how are you recently?"] * num_requests
+
+    prompt_ids = generate_prompt_ids(
+        doc_prompts,
+        sys_prompts,
+        query_prompts,
+        num_requests,
+        num_docs_per_request,
+        blend_special_str,
+        tokenizer,
+        offset=1,
+    )
+
+    write_resp("------warm up round------\n")
+    warmup_start_time = time.time()
+    warmup_ttfts = await test_long_document_qa(
+        client=client,
+        model=model,
+        prompts=warmup_prompt_ids,
+        output_len=args.output_len,
+        max_inflight_requests=args.max_inflight_requests,
+    )
+    warmup_end_time = time.time()
+    write_resp("------query round------\n")
+
+    sleep_time_after_warmup = args.sleep_time_after_warmup
+    if sleep_time_after_warmup > 0:
+        write_resp(f"Sleeping for {sleep_time_after_warmup} seconds after warmup...\n")
+        time.sleep(sleep_time_after_warmup)
+
+    benchmark_start_time = time.time()
+    benchmark_ttfts = await test_long_document_qa(
+        client=client,
+        model=model,
+        prompts=prompt_ids,
+        output_len=args.output_len,
+        max_inflight_requests=args.max_inflight_requests,
+    )
+    benchmark_end_time = time.time()
+
+    # Print results
+    warmup_mean_ttft = sum(warmup_ttfts) / len(warmup_ttfts)
+    query_mean_ttft = sum(benchmark_ttfts) / len(benchmark_ttfts)
+    CSI = "\x1b["
+    RESET = CSI + "0m"
+    print(f"{CSI}36;1m\n=== BENCHMARK RESULTS ==={RESET}")
+    print(f"{CSI}32mWarmup round mean TTFT: {warmup_mean_ttft:.3f}s{RESET}")
+    print(
+        f"{CSI}33mWarmup round time: {warmup_end_time - warmup_start_time:.3f}s{RESET}"
+    )
+    print(f"{CSI}35mWarmup round prompt count: {len(warmup_ttfts)}{RESET}")
+    print(f"{CSI}32mQuery round mean TTFT: {query_mean_ttft:.3f}s{RESET}")
+    print(
+        f"{CSI}33mQuery round time: "
+        f"{benchmark_end_time - benchmark_start_time:.3f}s{RESET}"
+    )
+    print(f"{CSI}35mQuery round prompt count: {len(benchmark_ttfts)}{RESET}")
+
+    # Validate expected gains as multiplicative speed-ups
+    if args.expected_ttft_gain is not None:
+        actual_ttft_gain = (
+            warmup_mean_ttft / query_mean_ttft if query_mean_ttft > 0 else float("inf")
+        )
+        print(f"{CSI}34mActual TTFT gain: {actual_ttft_gain:.2f}×{RESET}")
+        if actual_ttft_gain < args.expected_ttft_gain:
+            sys.exit(
+                f"ERROR: TTFT gain {actual_ttft_gain:.2f}× < expected "
+                f"{args.expected_ttft_gain:.2f}×"
+            )
+
+    if args.expected_latency_gain is not None:
+        warmup_duration = warmup_end_time - warmup_start_time
+        query_duration = benchmark_end_time - benchmark_start_time
+
+        # compute per-prompt latency before comparing
+        warmup_per_prompt = warmup_duration / len(warmup_ttfts)
+        query_per_prompt = query_duration / len(benchmark_ttfts)
+        actual_latency_gain = (
+            warmup_per_prompt / query_per_prompt
+            if query_per_prompt > 0
+            else float("inf")
+        )
+        print(f"{CSI}34mActual latency gain: {actual_latency_gain:.2f}×{RESET}")
+        if actual_latency_gain < args.expected_latency_gain:
+            sys.exit(
+                f"ERROR: latency gain {actual_latency_gain:.2f}× < expected "
+                f"{args.expected_latency_gain:.2f}×"
+            )
+
+
+def create_argument_parser():
+    parser = argparse.ArgumentParser(
+        description="Benchmark the performance forMulti-Doc QA."
+    )
+
+    parser.add_argument(
+        "--document-length",
+        type=int,
+        # Roughly the number of tokens for a system paper,
+        # excluding images
+        default=3000,
+        help="Length of each document in tokens.",
+    )
+
+    parser.add_argument(
+        "--num-total-documents",
+        type=int,
+        default=100,
+        help="Number of documents to generate for testing.",
+    )
+
+    parser.add_argument(
+        "--output-len",
+        type=int,
+        default=10,
+        help="Maximum number of tokens to generate for each prompt.",
+    )
+
+    parser.add_argument(
+        "--num-requests",
+        type=int,
+        default=100,
+        help="Number of requests to send.",
+    )
+
+    parser.add_argument(
+        "--num-docs-per-request",
+        type=int,
+        default=5,
+        help="Number of requests to send.",
+    )
+
+    parser.add_argument(
+        "--sampling-strategy",
+        type=str,
+        default="random",
+        help="Random seed for sampling",
+    )
+
+    parser.add_argument(
+        "--random-seed",
+        type=int,
+        default=0,
+        help='Random seed when the repeat mode is "random"',
+    )
+
+    parser.add_argument(
+        "--blend-special-str",
+        type=str,
+        default=" # # ",
+        help="Special string to separate different documents.",
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port to query the vLLM server",
+    )
+
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="meta-llama/Llama-3.1-8B-Instruct",
+        help="Model name",
+    )
+
+    parser.add_argument(
+        "--max-inflight-requests",
+        type=int,
+        default=20,
+        help="Maximum number of concurrent inflight requests",
+    )
+
+    parser.add_argument(
+        "--sleep-time-after-warmup",
+        type=float,
+        default=0.0,
+        help="Sleep time after warm up iteration",
+    )
+
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        help="Filename to write all responses to; if omitted, writes to stdout.",
+    )
+    parser.add_argument(
+        "--expected-ttft-gain",
+        type=float,
+        default=None,
+        help=(
+            "Expected minimum speed-up in time-to-first-token (warmup/query) "
+            "as a factor, e.g. 4.3 for 4.3×. If actual gain is below this, exits."
+        ),
+    )
+    parser.add_argument(
+        "--expected-latency-gain",
+        type=float,
+        default=None,
+        help=(
+            "Expected minimum speed-up in total round time (warmup/query) "
+            "as a factor, e.g. 4.5 for 4.5×. If actual gain is below this, exits."
+        ),
+    )
+
+    return parser
+
+
+if __name__ == "__main__":
+    parser = create_argument_parser()
+    args = parser.parse_args()
+    OUTPUT_FILE = args.output
+    asyncio.run(main(args))
diff --git a/benchmarks/multi_doc_qa/shuffle_doc_qa.py b/benchmarks/multi_doc_qa/shuffle_doc_qa.py
new file mode 100644
index 0000000..38855d5
--- /dev/null
+++ b/benchmarks/multi_doc_qa/shuffle_doc_qa.py
@@ -0,0 +1,289 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Generate (num_documents - 1) chat requests: each request permutes all documents
+so no document appears in the same ordinal position as in the baseline order
+(identity). Uses the same message shape as two-request-demo.py.
+
+Inputs (CLI):
+  --num-documents: how many distinct documents
+  --document-length: approximate length of each document
+    (same construction as multi_doc_qa)
+  --output-len: max_tokens for generation
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import argparse
+import itertools
+import os
+import random
+import sys
+import time
+
+# Third Party
+from openai import OpenAI
+from transformers import AutoTokenizer
+
+SERVICE_PORT = os.environ.get("SERVICE_PORT", "10001")
+
+
+def ordinal_word(i: int) -> str:
+    """0 -> 'first', 1 -> 'second', ..."""
+    names = (
+        "first",
+        "second",
+        "third",
+        "fourth",
+        "fifth",
+        "sixth",
+        "seventh",
+        "eighth",
+        "ninth",
+        "tenth",
+    )
+    if i < len(names):
+        return names[i]
+    return f"{i + 1}th"
+
+
+def all_derangements(n: int) -> list[tuple[int, ...]]:
+    """Permutations p of range(n) with p[i] != i for all i (only for small n)."""
+    out: list[tuple[int, ...]] = []
+    for perm in itertools.permutations(range(n)):
+        if all(perm[i] != i for i in range(n)):
+            out.append(perm)
+    return out
+
+
+def random_derangement(n: int, rng: random.Random) -> tuple[int, ...]:
+    """Uniform random derangement via shuffle-and-reject (small n only)."""
+    for _ in range(500_000):
+        p = list(range(n))
+        rng.shuffle(p)
+        if all(p[i] != i for i in range(n)):
+            return tuple(p)
+    raise RuntimeError(f"failed to sample a derangement for n={n}")
+
+
+def pick_derangements(n: int, count: int, rng: random.Random) -> list[tuple[int, ...]]:
+    """Return `count` distinct derangements; raises if mathematically impossible."""
+    if count == 0:
+        return []
+    # For modest n, enumerate (correct feasibility check + reproducible shuffle).
+    if n <= 8:
+        all_d = all_derangements(n)
+        if len(all_d) < count:
+            raise ValueError(
+                f"need {count} distinct derangements for n={n}, "
+                f"but only {len(all_d)} exist"
+            )
+        rng.shuffle(all_d)
+        return all_d[:count]
+
+    # Large n: sample random derangements (full enumeration is intractable).
+    seen: set[tuple[int, ...]] = set()
+    for _ in range(count * 200_000):
+        if len(seen) >= count:
+            break
+        seen.add(random_derangement(n, rng))
+    if len(seen) < count:
+        raise RuntimeError(
+            f"could not collect {count} distinct derangements for n={n} "
+            f"(got {len(seen)}); try a different --random-seed"
+        )
+    return list(seen)[:count]
+
+
+def build_documents(num_documents: int, document_length: int) -> list[str]:
+    """Synthetic docs aligned with multi_doc_qa.py."""
+    return [
+        str(i) + " " + " ".join(["hi"] * document_length) for i in range(num_documents)
+    ]
+
+
+def build_messages(
+    documents: list[str],
+    perm: tuple[int, ...],
+) -> list[dict]:
+    """
+    Same structure as two-request-demo.py: system, then for each slot
+    (user label, user body), then final summarize user message.
+    `perm[k]` is which document index appears at ordinal position k.
+    """
+    n = len(documents)
+    if len(perm) != n:
+        raise ValueError("perm length must match number of documents")
+
+    messages: list[dict] = [
+        {"role": "system", "content": "You are a helpful assistant."},
+    ]
+    for slot in range(n):
+        messages.append(
+            {
+                "role": "user",
+                "content": f"Here is the {ordinal_word(slot)} document",
+            }
+        )
+        messages.append(
+            {
+                "role": "user",
+                "content": documents[perm[slot]],
+            }
+        )
+
+    if n == 1:
+        summary = "Please summarize the above document."
+    elif n == 2:
+        summary = "Please summarize the above two documents"
+    else:
+        summary = f"Please summarize the above {n} documents"
+    messages.append({"role": "user", "content": summary})
+    return messages
+
+
+def parse_chunk_output(choice) -> str | None:
+    if not hasattr(choice, "delta"):
+        return choice.text
+
+    choice_delta = choice.delta
+
+    if choice_delta is None:
+        return None
+
+    fields_to_scan = [
+        "content",
+        "function_call",
+        "refusal",
+        "role",
+        "tool_calls",
+        "reasoning",
+    ]
+    for field in fields_to_scan:
+        if hasattr(choice_delta, field) and getattr(choice_delta, field) is not None:
+            return getattr(choice_delta, field)
+    return None
+
+
+def query_and_measure_ttft(
+    client: OpenAI,
+    model: str,
+    messages: list[dict],
+    max_tokens: int,
+) -> float:
+    start = time.perf_counter()
+    ttft = None
+
+    chat_completion = client.chat.completions.create(
+        messages=messages,
+        model=model,
+        temperature=0,
+        stream=True,
+        max_tokens=max_tokens,
+    )
+
+    for chunk in chat_completion:
+        chunk_message = parse_chunk_output(chunk.choices[0])
+        if chunk_message is not None:
+            if ttft is None:
+                ttft = time.perf_counter()
+            print(chunk_message, end="", flush=True)
+
+    print("\n")
+    return ttft - start if ttft is not None else 0.0
+
+
+def build_warmup_messages() -> list:
+    return [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "Hi how are you"},
+    ]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Multi-doc QA with (n-1) deranged shuffles; "
+            "matches two-request-demo request shape."
+        ),
+    )
+    parser.add_argument(
+        "--num-documents",
+        type=int,
+        required=True,
+        help="Number of documents; emits (num_documents - 1) requests.",
+    )
+    parser.add_argument(
+        "--document-length",
+        type=int,
+        required=True,
+        help="Length field for each synthetic document (see multi_doc_qa).",
+    )
+    parser.add_argument(
+        "--output-len",
+        type=int,
+        required=True,
+        help="max_tokens for each completion.",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(SERVICE_PORT),
+        help="vLLM/OpenAI-compatible server port (default: SERVICE_PORT or 10001).",
+    )
+    parser.add_argument(
+        "--random-seed",
+        type=int,
+        default=0,
+        help="Seed for choosing which derangements when multiple exist.",
+    )
+    args = parser.parse_args()
+
+    n = args.num_documents
+    if n < 1:
+        print("num-documents must be >= 1", file=sys.stderr)
+        sys.exit(2)
+
+    num_requests = n - 1
+    if num_requests == 0:
+        print("num_documents is 1: nothing to send (n-1 == 0). Exiting.")
+        return
+
+    documents = build_documents(n, args.document_length)
+    rng = random.Random(args.random_seed)
+
+    try:
+        perms = pick_derangements(n, num_requests, rng)
+    except (ValueError, RuntimeError) as e:
+        print(e, file=sys.stderr)
+        sys.exit(1)
+
+    client = OpenAI(
+        api_key="dummy-key",
+        base_url=f"http://localhost:{args.port}/v1",
+    )
+
+    models = client.models.list()
+    model = models.data[0].id
+    AutoTokenizer.from_pretrained(model)  # validate model id like two-request-demo
+
+    print("Warming up server")
+    warmup_messages = build_warmup_messages()
+    query_and_measure_ttft(
+        client, model, warmup_messages, max_tokens=min(200, args.output_len)
+    )
+    print()
+    print("-------------------------------")
+
+    for i, perm in enumerate(perms):
+        print(f"\n--- Request {i + 1}/{num_requests} derangement {perm} ---\n")
+        messages = build_messages(documents, perm)
+        ttft = query_and_measure_ttft(
+            client, model, messages, max_tokens=args.output_len
+        )
+        print(f"\nTTFT: {ttft:.3f} seconds\n")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/multi_round_qa/README.md b/benchmarks/multi_round_qa/README.md
new file mode 100644
index 0000000..3786d59
--- /dev/null
+++ b/benchmarks/multi_round_qa/README.md
@@ -0,0 +1,127 @@
+# Benchmarking LLM Performance: Multi-Round QA Use Case
+
+## Overview
+
+This repository contains benchmarking tools for evaluating the performance of language models in various scenarios. The initial focus of this benchmark is on the multi-round QA (Question Answering) use case. The script `multi_round_qa.py` simulates multiple users interacting with a language model concurrently, allowing you to analyze the serving engine's throughput and latency.
+
+### Current Workloads
+
+- **Multi-Round QA Benchmark**: Simulates a realistic multi-user, multi-turn question-answering session to evaluate key metrics such as token throughput, latency, and average response times.
+
+
+## Setup
+
+1. Install the required dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Running the Multi-Round QA Benchmark
+
+To run the multi-round QA benchmark, use the following command:
+
+```bash
+python3 multi_round_qa.py \
+    --num-users 10 \
+    --num-rounds 5 \
+    --qps 0.5 \
+    --shared-system-prompt 1000 \
+    --user-history-prompt 2000 \
+    --answer-len 100 \
+    --model mistralai/Mistral-7B-Instruct-v0.2 \
+    --base-url http://localhost:8000/v1
+```
+
+Use ctrl-C to terminate the benchmark at any time, and the the script will write each request's detailed stats to `summary.csv`.
+
+
+*Note:* the above command requires there is a serving engine with the `mistralai/Mistral-7B-Instruct-v0.2` model served locally at `http://localhost:8000/v1`. Here's an example command to launch the serving engine:
+
+```bash
+vllm serve mistralai/Mistral-7B-Instruct-v0.2 --disable-log-requests
+```
+
+### Arguments
+
+#### Configuring the workload
+- `--num-users <int>`: The maximum number of concurrent users in the system.
+- `--num-rounds <int>`: The number of rounds per user.
+- `--qps <float>`: The overall queries per second (QPS) rate for the system.
+- `--shared-system-prompt <int>`: Length of the system prompt shared across all users (in tokens).
+- `--user-history-prompt <int>`: Length of the user-specific context (simulating existing chat history) (in tokens).
+- `--answer-len <int>`: Length of the answer expected (in tokens).
+- `--init-user-id <int>`: The initial user ID to start the benchmark (default = 0). This is useful when you want to resume the benchmark from a specific user ID or avoid serving engine caching the request from previous runs
+- `--request-with-user-id`: If this option is present, the script will include the user ID in the request header.
+- `--sharegpt`: If this option is present, the script will use ShareGPT workload instead of dummy context.
+
+*Note:* If you use ShareGPT dataset, the length of the answer expected (in tokens) will be determined by the min value of the dataset response and  `--answer-len`. You also need to follow the instructions in **ShareGPT Datasets** first.
+
+#### Configuring the serving engine connection
+- `--model <str>`: The model name (e.g., `mistralai/Mistral-7B-Instruct-v0.2`).
+- `--base-url <str>`: The URL endpoint for the language model server.
+
+#### Configuring the experiment (Optional)
+- `--output <str>`: The csv file to dump the detailed stats for each query (default = summary.csv)
+- `--log-interval <float>`: Time between each performance summary log in seconds (default = 30)
+- `--time <float>`: Total time to run the experiment (default = forever)
+- `--dry-run`: If this option is present, the script will not send requests to the endpoint (server). This option is useful when quickly verifying whether a script can properly process trace data.
+
+#### Processing previous outputs only (Optional)
+- `--process-summary <filename>`: if this option is present, the script will only process the existing output csv and print out the summary without running any experiment.
+
+### Example Use Case
+
+The above command starts a benchmark with 10 users engaging in 5 rounds of interaction, with an expected QPS of 0.5. It assumes there is already a serving engine (vLLM or lmcache\_vllm) with the `mistralai/Mistral-7B-Instruct-v0.2` model served locally at `http://localhost:8000/v1`.
+
+Upon completion, a summary of key performance metrics (e.g., QPS, average response time) is printed to the console and saved as `summary.csv`.
+
+## Understanding the Benchmark Script
+
+The `multi_round_qa.py` script works by:
+
+- Simulating multiple user sessions (`UserSessionManager`) which make requests (`UserSession`) to a specified language model concurrently.
+- Tracking key metrics such as token throughput, time to first token (TTFT), and generation times.
+- Printing a summary of the performance metrics periodically and writing the results to a CSV file at the end.
+
+## Benchmark Metrics
+
+- **Queries Per Second (QPS)**: The average number of queries processed by the model per second.
+- **Average Prompt Throughput**: Tokens generated in the prompt per second.
+- **Average Generation Throughput**: Tokens generated as part of the response per second.
+- **Average TTFT (Time to First Token)**: Average time taken for the model to generate the first token of a response.
+
+## ShareGPT Datasets
+
+1. Download and prepare the ShareGPT dataset 
+    You can easily download the ShareGPT dataset and perform the preparation step to remove invalid traces by running the script below.
+
+    ```bash
+    bash prepare_sharegpt_data.sh 1
+    ```
+
+    You can specify the proportion of data to process by providing a number between `0` and `1` as an argument to the script. In this example, `1` indicates processing 100% of the dataset. You can adjust this value as needed.
+
+    Once the script runs successfully, `ShareGPT_V3_unfiltered_cleaned_split.json` will be downloaded, and the prepared `ShareGPT.json` will be generated.
+
+    The `prepare_sharegpt_data.sh` script internally executes `data_preprocessing.py`, which provides the following options:
+
+    - `--parse`: proportion of data to process by providing a number between `0` and `1` (default = 1)
+    - `--model`: model name for tokenizer (default = `mistralai/Mistral-7B-Instruct-v0.2`)
+    - `--trace`: trace file name to process (default = `ShareGPT_V3_unfiltered_cleaned_split.json`)
+
+2. Run the benchmark
+    Example:
+
+    ```bash
+    python3 multi_round_qa.py \
+        --num-users 10 \
+        --num-rounds 5 \
+        --qps 0.3 \
+        --shared-system-prompt 1000 \
+        --user-history-prompt 2000 \
+        --answer-len 100 \
+        --model mistralai/Mistral-7B-Instruct-v0.2 \
+        --base-url http://localhost:8000/v1 \
+        --sharegpt
+    ```
+
diff --git a/benchmarks/multi_round_qa/data_preprocessing.py b/benchmarks/multi_round_qa/data_preprocessing.py
new file mode 100644
index 0000000..51209b3
--- /dev/null
+++ b/benchmarks/multi_round_qa/data_preprocessing.py
@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import json
+import os
+
+# Third Party
+from tqdm import tqdm
+from transformers import AutoTokenizer
+import numpy as np
+
+_tokenizer: AutoTokenizer | None = None
+
+
+def estimate_num_tokens(text: str) -> int:
+    global _tokenizer
+    if _tokenizer is None:
+        os.environ["TOKENIZERS_PARALLELISM"] = "false"
+        _tokenizer = AutoTokenizer.from_pretrained(args.model)
+    return len(_tokenizer.tokenize(text))
+
+
+def is_human(human):
+    return human in ["human", "user"]
+
+
+def is_gpt(gpt):
+    return gpt in ["gpt", "chatgpt", "bing", "bard"]
+
+
+def is_system(system):
+    return system in ["system"]
+
+
+def invalid_conversations(conversations):
+    # pair does not match
+    if len(conversations) < 2:
+        return True
+
+    # starting from gpt or systems
+    entry = conversations[0]
+    if is_gpt(entry["from"]) or is_system(entry["from"]):
+        return True
+
+    # ending with human
+    entry = conversations[-1]
+    if is_human(entry["from"]):
+        return True
+
+    prev_from = None
+    total_tokens = 0
+    for conv in conversations:
+        _from = conv["from"]
+        total_tokens += estimate_num_tokens(conv["value"])
+
+        # consecutive rounds (gpt followed by gpt, human followed by human, ..)
+        if prev_from == _from:
+            return True
+
+        # too long conversations
+        if total_tokens > (128 * 1024):
+            return True
+
+        # unknown from
+        if not is_human(_from) and not is_gpt(_from) and not is_system(_from):
+            return True
+
+        prev_from = _from
+
+    return False
+
+
+parser = argparse.ArgumentParser(description="Process data percentage.")
+parser.add_argument(
+    "--parse",
+    type=float,
+    default=1,
+    help="The percentage of data to process (0 to 1). Default is 1 (100%).",
+)
+parser.add_argument(
+    "--model",
+    type=str,
+    default="mistralai/Mistral-7B-Instruct-v0.2",
+    help="Model for tokenizer. Default is mistralai/Mistral-7B-Instruct-v0.2.",
+)
+parser.add_argument(
+    "--trace",
+    type=str,
+    default="ShareGPT_V3_unfiltered_cleaned_split.json",
+    help="Trace file. Default is ShareGPT_V3_unfiltered_cleaned_split.json",
+)
+
+args = parser.parse_args()
+
+print("Loading trace file..")
+with open(args.trace, "r", encoding="utf-8") as file:
+    data = json.load(file)
+
+num_of_ids = len(data)
+print(f"Number of IDs: {num_of_ids}")
+
+# exclude invalid data
+print("Veryfing trace..")
+data = [d for d in tqdm(data) if not invalid_conversations(d["conversations"])]
+excluded_ids = len(data)
+num_of_ids -= excluded_ids
+print(f"Excluded number of IDs: {excluded_ids}")
+
+data_to_process = int(num_of_ids * args.parse)
+data = data[:data_to_process]
+print(f"Data to process: {data_to_process}")
+
+for d in tqdm(data):
+    conversations = d["conversations"]
+    d["num_round"] = len(conversations)  # human is one round, gpt is another round
+    human_tokens = []
+    gpt_tokens = []
+    for conv in conversations:
+        num_tokens = estimate_num_tokens(conv["value"])
+
+        if is_human(conv["from"]):
+            human_tokens.append(num_tokens)
+        elif is_gpt(conv["from"]):
+            conv["num_tokens"] = num_tokens
+            gpt_tokens.append(num_tokens)
+        else:
+            print("Invalid _from_")
+
+    if len(human_tokens) == 0:
+        d["average_human_token"] = 0
+        d["max_human_token"] = 0
+    else:
+        d["average_human_token"] = float(np.mean(human_tokens))
+        d["max_human_token"] = float(np.max(human_tokens))
+    if len(gpt_tokens) == 0:
+        d["average_gpt_token"] = 0
+        d["max_gpt_token"] = 0
+    else:
+        d["average_gpt_token"] = float(np.mean(gpt_tokens))
+        d["max_gpt_token"] = float(np.max(gpt_tokens))
+
+with open("ShareGPT.json", "w", encoding="utf-8") as file:
+    json.dump(data, file, ensure_ascii=False, indent=2)
diff --git a/benchmarks/multi_round_qa/multi-round-qa.py b/benchmarks/multi_round_qa/multi-round-qa.py
new file mode 100644
index 0000000..0edbc76
--- /dev/null
+++ b/benchmarks/multi_round_qa/multi-round-qa.py
@@ -0,0 +1,764 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+import argparse
+import asyncio
+import json
+import logging
+import time
+
+# Third Party
+from utils import AsyncLoopWrapper, init_logger
+import openai
+import pandas as pd
+
+logger = init_logger(__name__, logging.INFO)
+
+
+@dataclass
+class WorkloadConfig:
+    # Max number of users in the system concurrently
+    num_users: int
+
+    # Length of shared system prompt
+    system_prompt_len: int
+
+    # Length of the user-specific data
+    user_info_len: int
+
+    # Length of the answer in one round
+    answer_len: int
+
+    # Number of rounds in the conversation
+    num_rounds: int
+
+    # Overall QPS
+    qps: int
+
+    # Model name
+    model: str
+
+    # Whether to include user id in request header
+    enable_user_id: bool
+
+    # Whether strictly cap active sessions at num_users
+    enforce_strict_concurrent_users: bool = False
+
+    # Whether to disable ramp up during the uphill stage
+    disable_ramp_up: bool = False
+
+
+@dataclass
+class UserConfig:
+    # User id
+    user_id: int
+
+    # System prompt length
+    system_prompt_len: int
+
+    # Length of the user-specific data
+    user_info_len: int
+
+    # Answer length
+    answer_len: int
+
+    # Gap between two requests
+    gap_between_requests: float
+
+    # Num rounds
+    num_rounds: int
+
+    # Whether to include user id in request header
+    enable_user_id: bool
+
+    @staticmethod
+    def new_user_config(user_id: int, workload_config: WorkloadConfig) -> "UserConfig":
+        return UserConfig(
+            user_id=user_id,
+            system_prompt_len=workload_config.system_prompt_len,
+            user_info_len=workload_config.user_info_len,
+            answer_len=workload_config.answer_len,
+            gap_between_requests=workload_config.num_users / workload_config.qps,
+            num_rounds=workload_config.num_rounds,
+            enable_user_id=workload_config.enable_user_id,
+        )
+
+
+class ChatHistory:
+    def __init__(
+        self,
+    ):
+        self.history = []
+
+    def on_user_query(self, query: str):
+        if len(self.history) == 0:
+            self.history.append({"role": "user", "content": query})
+        else:
+            assert self.history[-1]["role"] == "assistant", "Expect system response"
+            self.history.append({"role": "user", "content": query})
+
+    def on_system_response(self, response: str):
+        assert len(self.history) > 0, "Expect user query"
+        assert self.history[-1]["role"] == "user", "Expect user query"
+        self.history.append({"role": "assistant", "content": response})
+
+    def get_messages_for_openai(self):
+        return self.history
+
+    def __len__(self):
+        return len(self.history)
+
+
+@dataclass
+class Response:
+    body: str
+    ttft: float
+    generation_time: float
+    prompt_tokens: int
+    generation_tokens: int
+    launch_time: float
+    finish_time: float
+
+
+class RequestExecutor:
+    def __init__(self, base_url: str, api_key: str, model: str):
+        self.client = openai.AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self.model = model
+        self.loop = AsyncLoopWrapper.GetOrStartLoop()
+
+    async def _async_launch_request(self, messages, max_tokens, extra_headers=None):
+        start_time = time.time()
+        first_token_time = None
+        words = ""
+
+        response = await self.client.chat.completions.create(
+            messages=messages,
+            model=self.model,
+            temperature=0,
+            stream=True,
+            max_tokens=max_tokens,
+            stream_options={"include_usage": True},
+            extra_headers=extra_headers,
+        )
+
+        async for tok in response:
+            if not tok.choices:
+                continue
+            chunk_message = tok.choices[0].delta.content
+            if chunk_message is not None:
+                if first_token_time is None and chunk_message != "":
+                    first_token_time = time.time()
+                words += chunk_message
+        tokens_out = tok.usage.completion_tokens
+        tokens_prefill = tok.usage.prompt_tokens
+
+        if first_token_time is None:
+            first_token_time = time.time()
+
+        return Response(
+            body=words,
+            ttft=first_token_time - start_time,
+            generation_time=time.time() - first_token_time,
+            prompt_tokens=tokens_prefill,
+            generation_tokens=tokens_out,
+            launch_time=start_time,
+            finish_time=time.time(),
+        )
+
+    def launch_request(
+        self,
+        chat_history: ChatHistory,
+        max_tokens: int,
+        finish_callback,
+        extra_headers=None,
+    ):
+        """
+        finish_callback: Callable[[Response], None]
+        """
+        messages = chat_history.get_messages_for_openai()
+        real_callback = lambda x: finish_callback(x.result())
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_launch_request(messages, max_tokens, extra_headers),
+            self.loop,
+        )
+        future.add_done_callback(real_callback)
+
+
+class UserSession:
+    def __init__(self, user_config: UserConfig, use_sharegpt=False, sharegpt_data=None):
+        self.user_config = user_config
+        self.last_request_time: float | None = None
+        self.chat_history = ChatHistory()
+        self.question_id = 0
+        self.use_sharegpt = use_sharegpt
+        if self.use_sharegpt:
+            self.sharegpt_data = sharegpt_data
+            if self.sharegpt_data["num_round"] % 2 == 0:
+                self.start_with_gpt = False
+            else:
+                self.start_with_gpt = True
+
+        self.has_unfinished_request = False
+        self.last_unfinished_log = 0.0
+
+        self.prompt_lengths: list[int] = []
+        self.generation_lengths: list[int] = []
+        self.ttfts: list[float | None] = []
+        self.generation_times: list[float | None] = []
+        self.launch_times: list[float | None] = []
+        self.finish_times: list[float | None] = []
+
+        self.finished = False
+
+    def _update_result(self, response: Response):
+        self.prompt_lengths.append(response.prompt_tokens)
+        self.generation_lengths.append(response.generation_tokens)
+        self.ttfts.append(response.ttft)
+        self.generation_times.append(response.generation_time)
+        self.launch_times.append(response.launch_time)
+        self.finish_times.append(response.finish_time)
+
+    def _build_system_prompt(self):
+        def gen_dummy_text(length):
+            return " ".join(["hi"] * length)
+
+        dummy_text_sys = gen_dummy_text(self.user_config.system_prompt_len)
+        dummy_text_user = gen_dummy_text(self.user_config.user_info_len)
+        system_prompt = (
+            f"Hi, here's some system prompt: {dummy_text_sys}."
+            + f"For user {self.user_config.user_id}, "
+            + f"here are some other context: {dummy_text_user}."
+        )
+        return system_prompt
+
+    def _build_new_question(self):
+        self.question_id += 1
+        return (
+            f"Here's question #{self.question_id}: can you tell me "
+            + "a new long story with a happy ending?"
+        )
+
+    def _launch_new_request(self, timestamp: float, request_executor: RequestExecutor):
+        if self.use_sharegpt:
+            if self.start_with_gpt:
+                prompt = self.sharegpt_data["conversations"][2 * self.question_id + 1][
+                    "value"
+                ]
+            else:
+                prompt = self.sharegpt_data["conversations"][2 * self.question_id][
+                    "value"
+                ]
+            self.question_id += 1
+        else:
+            prompt = self._build_new_question()
+        if len(self.chat_history) == 0:
+            prompt = self._build_system_prompt() + prompt
+        self.chat_history.on_user_query(prompt)
+        logger.debug(
+            f"User {self.user_config.user_id} issues request {self.question_id}"
+        )
+        if self.use_sharegpt:
+            if self.start_with_gpt:
+                max_tokens = self.sharegpt_data["conversations"][2 * self.question_id][
+                    "num_tokens"
+                ]
+            else:
+                max_tokens = self.sharegpt_data["conversations"][
+                    2 * self.question_id - 1
+                ]["num_tokens"]
+            max_tokens = min(max_tokens, self.user_config.answer_len)
+        else:
+            max_tokens = self.user_config.answer_len
+        if request_executor is not None:
+            request_executor.launch_request(
+                self.chat_history,
+                max_tokens,
+                self._on_request_finished,
+                extra_headers={"x-user-id": str(self.user_config.user_id)},
+            )
+            self.has_unfinished_request = True
+        else:  # dry-run
+            self.chat_history.on_system_response("")
+            self.has_unfinished_request = False
+        self.last_request_time = timestamp
+
+    def _on_request_finished(self, response: Response):
+        self.chat_history.on_system_response(response.body)
+        self.has_unfinished_request = False
+        logger.debug(
+            f"User {self.user_config.user_id} finished one request. "
+            f"Prompt tokens: {response.prompt_tokens}, "
+            f"generation tokens: {response.generation_tokens}"
+        )
+        self._update_result(response)
+
+    def set_internal_state(self, offset: float, timestamp: float):
+        """Tell the session is the 'offset' seconds after the start"""
+        assert len(self.chat_history) == 0, (
+            "Internal state should be set before the first request"
+        )
+
+        num_passed_questions = int(offset / self.user_config.gap_between_requests) + 1
+
+        passed_time = (num_passed_questions - 1) * self.user_config.gap_between_requests
+
+        self.last_request_time = timestamp - offset + passed_time
+        self.question_id = num_passed_questions
+        logger.debug(
+            f"Set internal state for user {self.user_config.user_id}, "
+            f"question_id: {self.question_id}, "
+            f"last_request_time: {self.last_request_time}"
+        )
+
+    def step(self, timestamp: float, request_executor: RequestExecutor):
+        if (
+            self.question_id >= self.user_config.num_rounds
+            and not self.has_unfinished_request
+        ):
+            self.finished = True
+            return
+
+        if self.last_request_time is None:
+            self._launch_new_request(timestamp, request_executor)
+            return
+
+        if timestamp - self.last_request_time > self.user_config.gap_between_requests:
+            if self.has_unfinished_request:
+                if timestamp - self.last_unfinished_log > 10:
+                    logger.warning(
+                        f"User {self.user_config.user_id} has an unfinished "
+                        "request and unable to fit the QPS requirement."
+                    )
+                    self.last_unfinished_log = timestamp
+                return
+
+            self._launch_new_request(timestamp, request_executor)
+            return
+
+    def summary(self) -> pd.DataFrame:
+        df = pd.DataFrame()
+        df["prompt_tokens"] = self.prompt_lengths
+        df["generation_tokens"] = self.generation_lengths
+        df["ttft"] = self.ttfts
+        df["generation_time"] = self.generation_times
+        df["user_id"] = self.user_config.user_id
+        df["question_id"] = range(1, len(self.prompt_lengths) + 1)
+        df["launch_time"] = self.launch_times
+        df["finish_time"] = self.finish_times
+        return df
+
+
+class UserSessionManager:
+    def __init__(
+        self,
+        workload_config: WorkloadConfig,
+        init_user_id=0,
+        use_sharegpt=False,
+    ):
+        self.workload_config = workload_config
+        self.sessions: list[UserSession] = []
+
+        gap_between_requests_per_user = workload_config.num_users / workload_config.qps
+        session_alive_time = gap_between_requests_per_user * (
+            workload_config.num_rounds - 1
+        )
+        self.gap_between_users = session_alive_time / (workload_config.num_users + 0)
+        self.ramp_up_time = workload_config.num_users * self.gap_between_users
+
+        logger.info(
+            f"Gap between users: {self.gap_between_users} secs.\n"
+            f"Gap between user reqs: {gap_between_requests_per_user} secs.\n"
+            f"Expected length of user session: {session_alive_time} secs."
+        )
+
+        self.user_id = init_user_id
+        self.last_user_join = 0.0
+        self.session_summaries: list[pd.DataFrame] = []
+        self.start_time: float | None = None
+
+        self.need_ramp_up = not workload_config.disable_ramp_up
+
+        self.use_sharegpt = use_sharegpt
+        if self.use_sharegpt:
+            self._load_sharegpt_data()
+
+        self.enforce_strict_concurrent_users = (
+            workload_config.enforce_strict_concurrent_users
+        )
+
+    def _load_sharegpt_data(self):
+        with open("ShareGPT.json", "r", encoding="utf-8") as file:
+            self.sharegpt_data = json.load(file)
+        self.sharegpt_data = [
+            d
+            for d in self.sharegpt_data
+            if d["num_round"] > 2 * self.workload_config.num_rounds
+        ]
+        logger.info(f"There are {len(self.sharegpt_data)} users satisfying ")
+        assert len(self.sharegpt_data) >= self.workload_config.num_users, (
+            "Not enough data! Reduce --num-users or --num-rounds"
+        )
+
+    def _ramp_up(self, timestamp: float, ramp_up_time: float):
+        for i in range(self.workload_config.num_users):
+            new_session = self._create_user_session()
+            offset = ramp_up_time - i * self.gap_between_users
+            if offset < 0:
+                break
+            new_session.set_internal_state(offset, timestamp)
+        self.need_ramp_up = False
+
+    def _create_user_session(self):
+        self.user_id += 1
+        user_config = UserConfig.new_user_config(self.user_id, self.workload_config)
+        if self.use_sharegpt:
+            user_session = UserSession(
+                user_config, self.use_sharegpt, self.sharegpt_data[self.user_id]
+            )
+        else:
+            user_session = UserSession(user_config, self.use_sharegpt)
+        self.sessions.append(user_session)
+        return user_session
+
+    def _remove_finished_sessions(self):
+        sessions_to_remove = [s for s in self.sessions if s.finished]
+        if len(sessions_to_remove) > 0:
+            logger.info(
+                f"Removing {len(sessions_to_remove)} finished sessions, now "
+                f"active users: {len(self.sessions) - len(sessions_to_remove)}"
+            )
+            for session in sessions_to_remove:
+                self.session_summaries.append(session.summary())
+        self.sessions = [s for s in self.sessions if not s.finished]
+
+    def _can_join_user(self, timestamp: float) -> bool:
+        # No new user session if gap_between_users time interval not meets
+        if timestamp - self.last_user_join <= self.gap_between_users:
+            return False
+
+        # No user seession if active user count is less than configured
+        if (
+            self.enforce_strict_concurrent_users
+            and len(self.sessions) >= self.workload_config.num_users
+        ):
+            return False
+        return True
+
+    def step(self, timestamp: float, executor: RequestExecutor):
+        if self.need_ramp_up:
+            self._ramp_up(timestamp, self.ramp_up_time)
+
+        if self.start_time is None:
+            self.start_time = timestamp
+
+        # Check if can join new user session
+        if self._can_join_user(timestamp):
+            self._create_user_session()
+            self.last_user_join = timestamp
+            logger.info(
+                f"Joined a new user {self.user_id}, "
+                f"now active users: {len(self.sessions)}"
+            )
+
+        for session in self.sessions:
+            session.step(timestamp, executor)
+
+        self._remove_finished_sessions()
+
+    @staticmethod
+    def ProcessSummary(
+        df: pd.DataFrame,
+        start_time: Optional[float] = None,
+        end_time: Optional[float] = None,
+        pending_queries: int = 0,
+        config_qps: Optional[float] = None,
+    ):
+        if start_time and end_time:
+            launched_queries = len(
+                df.query(f"{start_time} <= launch_time <= {end_time}")
+            )
+            df = df.query(f"{start_time} <= finish_time <= {end_time}")
+        else:
+            launched_queries = len(df)
+
+        logger.debug(
+            f"Launched queries: {launched_queries}, "
+            f"pending queries: {pending_queries}, "
+            f"finished queries: {len(df)}"
+        )
+
+        if config_qps is None:
+            config_qps = 0.0
+
+        if start_time is None:
+            start_time = df["launch_time"].min()
+        if end_time is None:
+            end_time = df["finish_time"].max()
+        total_time = end_time - start_time
+
+        total_requests = launched_queries + pending_queries
+        actual_qps = total_requests / total_time
+
+        total_finished_requests = len(df)
+        finished_qps = total_finished_requests / total_time
+
+        total_prompt_tokens = df["prompt_tokens"].sum()
+        total_generation_tokens = df["generation_tokens"].sum()
+        average_prefill_speed = total_prompt_tokens / total_time
+        average_generation_speed = total_generation_tokens / total_time
+        average_generation_speed_per_request = (
+            df["generation_tokens"] / df["generation_time"]
+        ).mean()
+        average_ttft = df["ttft"].mean()
+        logger.info("Calculating performance summary")
+        print("\n")
+        print("==================== Performance summary ======================")
+        print(f"  \033[33mConfig QPS: \033[32m{config_qps:.4f} reqs/s\033[0m\n")
+        print(f"  \033[33mActual QPS: \033[32m{actual_qps:.4f} reqs/s\033[0m\n")
+
+        print(f"  \033[33mProcessing speed: \033[32m{finished_qps:.4f} reqs/s\033[0m\n")
+
+        print(f"  \033[33mRequests on-the-fly: {pending_queries}\033[0m\n")
+
+        print(
+            "  \033[33mInput tokens per second: "
+            f"\033[32m{average_prefill_speed:.4f} tokens/s\033[0m\n"
+        )
+
+        print(
+            "  \033[33mOutput tokens per second: "
+            f"\033[32m{average_generation_speed:.4f} tokens/s\033[0m\n"
+        )
+
+        print(
+            "  \033[33mAverage generation throughput (per request): "
+            f"\033[32m{average_generation_speed_per_request:.4f} "
+            "tokens/req/s\033[0m\n"
+        )
+
+        print(f"  \033[33mAverage TTFT: \033[32m{average_ttft:.4f}s\033[0m\n")
+
+        print(f"Time range: {start_time} - {end_time} ({total_time:.2f}s)")
+
+        print("===============================================================")
+        print("\n")
+        return df
+
+    def summary(self, start_time: float, end_time: float) -> pd.DataFrame:
+        if len(self.session_summaries) == 0 and len(self.sessions) == 0:
+            return pd.DataFrame()
+
+        df = pd.concat(
+            [s for s in self.session_summaries] + [s.summary() for s in self.sessions]
+        )
+        pending_queries = len([s for s in self.sessions if s.has_unfinished_request])
+        assert self.start_time is not None
+        start_time = max(self.start_time, start_time)
+        qps = self.workload_config.qps
+
+        df = UserSessionManager.ProcessSummary(
+            df, start_time, end_time, pending_queries, qps
+        )
+        return df
+
+
+def warmup_engine(executor):
+    logger.info("Warming up the engine")
+    for i in range(10):
+        chat_history = ChatHistory()
+        chat_history.on_user_query(
+            f"WARMUP: Hi, I'm user {i}. Here are some text: {'hi ' * 100}."
+        )
+        executor.launch_request(chat_history, 100, lambda x: None)
+
+    AsyncLoopWrapper.WaitLoop()
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Parse benchmark configurations.")
+
+    parser.add_argument(
+        "--num-users",
+        type=int,
+        required=True,
+        help="Max number of users in the system concurrently",
+    )
+    parser.add_argument(
+        "--shared-system-prompt",
+        type=int,
+        required=True,
+        help="Length of the shared system prompt (tokens)",
+    )
+    parser.add_argument(
+        "--user-history-prompt",
+        type=int,
+        required=True,
+        help="Length of the user-specific history prompt (tokens)",
+    )
+    parser.add_argument(
+        "--answer-len",
+        type=int,
+        required=True,
+        help="Length of the answer in one round",
+    )
+    parser.add_argument(
+        "--num-rounds",
+        type=int,
+        required=True,
+        help="Number of rounds in the conversation",
+    )
+    parser.add_argument("--qps", type=float, required=True, help="Overall QPS")
+    parser.add_argument("--model", type=str, required=True, help="Model name")
+    parser.add_argument(
+        "--base-url",
+        type=str,
+        required=True,
+        help="Base URL of the serving engine endpoint",
+    )
+    parser.add_argument(
+        "--time",
+        type=int,
+        required=False,
+        help="The time to run the simulation in seconds",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default="summary.csv",
+        help="The output file name (ended with csv or txt) for the summary csv and txt",
+    )
+    parser.add_argument(
+        "--init-user-id",
+        type=int,
+        default=0,
+        help="The initial user id to start with",
+    )
+    parser.add_argument(
+        "--request-with-user-id",
+        action="store_true",
+        help="Whether to enable user id in the request headers",
+    )
+    parser.add_argument(
+        "--log-interval",
+        type=int,
+        default=30,
+        help="The time between two summary loggings in seconds",
+    )
+
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Whether to enable verbose logging",
+    )
+    parser.add_argument(
+        "--sharegpt",
+        action="store_true",
+        help="Whether to use ShareGPT dataset",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Does not send requests to the endpoint (server)",
+    )
+    parser.add_argument(
+        "--enforce-strict-concurrent-users",
+        action="store_true",
+        help="Strictly enforce concurrent users count to match --num-users",
+    )
+    parser.add_argument(
+        "--disable-ramp-up",
+        action="store_true",
+        help="Disable the initial ramp-up phase, allowing users to join gradually",
+    )
+    args = parser.parse_args()
+    return args
+
+
+def parse_process_summary():
+    parser = argparse.ArgumentParser(
+        description="Parse benchmark configurations.", add_help=False
+    )
+
+    parser.add_argument("--process-summary", type=str, default=None)
+
+    args, _ = parser.parse_known_args()
+    return args
+
+
+def process_output(filename):
+    logger.warning(
+        f"Processing the existing summary file {filename}"
+        ", ignoring all the other arguments"
+    )
+    UserSessionManager.ProcessSummary(pd.read_csv(filename), pending_queries=0)
+
+
+def main():
+    args = parse_process_summary()
+    if args.process_summary:
+        process_output(args.process_summary)
+        return
+
+    args = parse_arguments()
+    if args.verbose:
+        global logger
+        logger = init_logger(__name__, logging.DEBUG)
+
+    step_interval = 0.1
+
+    executor = None
+    if not args.dry_run:
+        executor = RequestExecutor(
+            base_url=args.base_url, api_key="EMPTY", model=args.model
+        )
+
+        warmup_engine(executor)
+
+    workload_config = WorkloadConfig(
+        num_users=args.num_users,
+        system_prompt_len=args.shared_system_prompt,
+        user_info_len=args.user_history_prompt,
+        answer_len=args.answer_len,
+        num_rounds=args.num_rounds,
+        qps=args.qps,
+        model=args.model,
+        enable_user_id=args.request_with_user_id,
+        enforce_strict_concurrent_users=args.enforce_strict_concurrent_users,
+        disable_ramp_up=args.disable_ramp_up,
+    )
+
+    manager = UserSessionManager(
+        workload_config,
+        init_user_id=args.init_user_id,
+        use_sharegpt=args.sharegpt,
+    )
+
+    num_steps = 0
+    start_time = time.time()
+    last_summary_time = start_time
+    try:
+        while True:
+            num_steps += 1
+            manager.step(time.time(), executor)
+            time.sleep(step_interval)
+
+            if time.time() - last_summary_time > args.log_interval:
+                manager.summary(last_summary_time, time.time())
+                last_summary_time = time.time()
+
+            if args.time is not None and time.time() - start_time > args.time:
+                break
+
+    except KeyboardInterrupt:
+        logger.info("Interrupted, waiting for the final result")
+
+    AsyncLoopWrapper.StopLoop()
+
+    logger.info(f"Finished benchmarking, dumping summary to {args.output}")
+    summary = manager.summary(0, time.time())
+    summary.to_csv(args.output, index=False)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/multi_round_qa/prepare_sharegpt_data.sh b/benchmarks/multi_round_qa/prepare_sharegpt_data.sh
new file mode 100644
index 0000000..80d2baa
--- /dev/null
+++ b/benchmarks/multi_round_qa/prepare_sharegpt_data.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+
+wget https://huggingface.co/datasets/anon8231489123/ShareGPT_Vicuna_unfiltered/resolve/main/ShareGPT_V3_unfiltered_cleaned_split.json
+python3 data_preprocessing.py --parse $1
diff --git a/benchmarks/multi_round_qa/requirements.txt b/benchmarks/multi_round_qa/requirements.txt
new file mode 100644
index 0000000..60b3c8c
--- /dev/null
+++ b/benchmarks/multi_round_qa/requirements.txt
@@ -0,0 +1,3 @@
+tqdm
+pandas
+openai
diff --git a/benchmarks/multi_round_qa/utils.py b/benchmarks/multi_round_qa/utils.py
new file mode 100644
index 0000000..eea04cf
--- /dev/null
+++ b/benchmarks/multi_round_qa/utils.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from logging import Logger
+import asyncio
+import logging
+import threading
+
+
+def build_format(color):
+    reset = "\x1b[0m"
+    underline = "\x1b[3m"
+    return (
+        f"{color}[%(asctime)s] %(levelname)s:{reset} %(message)s "
+        + f"{underline}(%(filename)s:%(lineno)d:%(name)s){reset}"
+    )
+
+
+class CustomFormatter(logging.Formatter):
+    grey = "\x1b[1m"
+    green = "\x1b[32;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+
+    FORMATS = {
+        logging.DEBUG: build_format(grey),
+        logging.INFO: build_format(green),
+        logging.WARNING: build_format(yellow),
+        logging.ERROR: build_format(red),
+        logging.CRITICAL: build_format(bold_red),
+    }
+
+    def format(self, record):
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def init_logger(name: str, log_level=logging.DEBUG) -> Logger:
+    logger = logging.getLogger(name)
+
+    logger.handlers.clear()
+    logger.propagate = False
+
+    ch = logging.StreamHandler()
+    ch.setLevel(log_level)
+    ch.setFormatter(CustomFormatter())
+    logger.addHandler(ch)
+    logger.setLevel(logging.DEBUG)
+
+    return logger
+
+
+class AsyncLoopWrapper:
+    _loop: asyncio.AbstractEventLoop | None = None
+    _thread: threading.Thread | None = None
+    _logger = init_logger("AsyncLoopWrapper")
+
+    @classmethod
+    def WaitLoop(cls):
+        assert cls._loop is not None, "Loop is not started"
+
+        async def wait_for_tasks():
+            current_task = asyncio.current_task(cls._loop)
+            tasks = [
+                task
+                for task in asyncio.all_tasks(cls._loop)
+                if not task.done() and task is not current_task
+            ]
+            cls._logger.info(f"Waiting for {len(tasks)} tasks to finish")
+            if tasks:
+                await asyncio.gather(*tasks)
+
+        # Schedule the wait_for_tasks coroutine to be executed in the loop
+        future = asyncio.run_coroutine_threadsafe(wait_for_tasks(), cls._loop)
+        try:
+            # Wait for wait_for_tasks to complete
+            future.result()
+        except Exception as e:
+            cls._logger.error(f"Error while waiting for tasks: {e}")
+
+    @classmethod
+    def StartLoop(cls):
+        if cls._loop is not None:
+            cls._logger.warning("Loop is already started")
+            return
+
+        if cls._loop is None:
+            cls._loop = asyncio.new_event_loop()
+
+        def run_loop():
+            asyncio.set_event_loop(cls._loop)
+            cls._logger.debug("Starting the asyncio loop")
+            cls._loop.run_forever()
+
+        cls._thread = threading.Thread(target=run_loop)
+        cls._thread.start()
+
+    @classmethod
+    def StopLoop(cls):
+        assert cls._loop is not None, "Loop is not started"
+        assert cls._thread is not None, "Thread is not started"
+
+        def stop_loop():
+            cls._logger.debug("Stopping the loop!")
+            cls._loop.stop()
+
+        cls._logger.info("Waiting for remaining tasks to finish")
+        cls.WaitLoop()
+
+        cls._loop.call_soon_threadsafe(stop_loop)
+        cls._thread.join()
+
+    @classmethod
+    def GetLoop(cls) -> asyncio.AbstractEventLoop:
+        assert cls._loop is not None, "Loop is not started"
+        return cls._loop
+
+    @classmethod
+    def GetOrStartLoop(cls) -> asyncio.AbstractEventLoop:
+        if cls._loop is None:
+            cls.StartLoop()
+        assert cls._loop is not None, "Loop is not started"
+        return cls._loop
diff --git a/benchmarks/musa/README.md b/benchmarks/musa/README.md
new file mode 100644
index 0000000..edf2207
--- /dev/null
+++ b/benchmarks/musa/README.md
@@ -0,0 +1,18 @@
+# MUSA Benchmarks
+
+MUSA benchmarks compare the existing torch path with optional native
+`musa_aiter` acceleration for the in-process vLLM MUSA connector.
+
+Run on a Moore Threads MUSA host:
+
+```bash
+python -c "import torch, torch_musa; print(torch.musa.is_available(), torch.musa.device_count())"
+pytest -q tests/v1/test_musa_native.py tests/v1/test_musa_connector.py -rs
+python benchmarks/musa/bench_inprocess_transfer.py --memory-device musa --iters 20 --warmup-iters 5 --min-speedup 1.2
+```
+
+The benchmark passes when native mode is at least `1.2x` faster than the torch
+fallback for the default shape. Use `--memory-device musa` when measuring native
+acceleration because the optional `musa_aiter` path consumes contiguous MUSA
+tensors directly. For review, attach the full benchmark command, MUSA driver
+version, `torch_musa` version, model-like shape, and speedup.
diff --git a/benchmarks/musa/bench_inprocess_transfer.py b/benchmarks/musa/bench_inprocess_transfer.py
new file mode 100644
index 0000000..3d0581b
--- /dev/null
+++ b/benchmarks/musa/bench_inprocess_transfer.py
@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Benchmark Stage2 in-process vLLM MUSA connector transfers."""
+
+# Standard
+from dataclasses import dataclass
+from typing import Callable
+import argparse
+import os
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.musa_connectors import VLLMPagedMemMUSAConnectorV2
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.platform.musa.native_kv_transfer import ENV_MUSA_NATIVE_KV_TRANSFER
+
+
+@dataclass(frozen=True)
+class BenchmarkResult:
+    """One benchmark result."""
+
+    name: str
+    seconds_per_iter: float
+
+
+def compare_results(
+    torch_result: BenchmarkResult,
+    native_result: BenchmarkResult,
+    *,
+    min_speedup: float,
+) -> tuple[bool, str]:
+    """Compare native transfer against the torch fallback."""
+    speedup = torch_result.seconds_per_iter / native_result.seconds_per_iter
+    passed = speedup >= min_speedup
+    return (
+        passed,
+        "torch={:.6f}s native={:.6f}s speedup={:.3f}x required>={:.3f}x".format(
+            torch_result.seconds_per_iter,
+            native_result.seconds_per_iter,
+            speedup,
+            min_speedup,
+        ),
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--iters", type=int, default=20)
+    parser.add_argument("--warmup-iters", type=int, default=5)
+    parser.add_argument("--num-layers", type=int, default=2)
+    parser.add_argument("--num-blocks", type=int, default=512)
+    parser.add_argument("--block-size", type=int, default=16)
+    parser.add_argument("--num-heads", type=int, default=8)
+    parser.add_argument("--head-size", type=int, default=128)
+    parser.add_argument("--num-tokens", type=int, default=4096)
+    parser.add_argument(
+        "--memory-device",
+        choices=("cpu", "musa"),
+        default="cpu",
+        help="Device backing the LMCache contiguous benchmark buffer.",
+    )
+    parser.add_argument("--min-speedup", type=float, default=1.2)
+    return parser.parse_args()
+
+
+def main() -> int:
+    """Run torch fallback and native opt-in transfer benchmarks."""
+    args = parse_args()
+    _require_musa()
+    device = torch.device("musa:0")
+    total_slots = args.num_blocks * args.block_size
+    if args.num_tokens > total_slots:
+        raise ValueError("--num-tokens must be <= num_blocks * block_size")
+
+    source = _make_kvcaches(args, device)
+    destination = [torch.zeros_like(layer) for layer in source]
+    slot_mapping = torch.randperm(total_slots, device=device, dtype=torch.long)[
+        : args.num_tokens
+    ]
+    hidden_dim = args.num_heads * args.head_size
+    alloc_bytes = 2 * args.num_layers * args.num_tokens * hidden_dim * 2
+    allocator = _make_allocator(args.memory_device, alloc_bytes, device)
+    memobj = allocator.allocate(
+        torch.Size([2, args.num_layers, args.num_tokens, hidden_dim]),
+        torch.bfloat16,
+        MemoryFormat.KV_2LTD,
+    )
+    if memobj is None:
+        raise RuntimeError(
+            f"Failed to allocate {args.memory_device} LMCache benchmark buffer"
+        )
+    memory_tensor = memobj.tensor
+    if memory_tensor is None:
+        raise RuntimeError(
+            f"{args.memory_device} LMCache benchmark buffer has no tensor view"
+        )
+    print(
+        f"memory_device={args.memory_device} "
+        f"memory_tensor_device={memory_tensor.device}"
+    )
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(args),
+        use_gpu=False,
+        device=device,
+    )
+
+    old_env = os.environ.get(ENV_MUSA_NATIVE_KV_TRANSFER)
+    try:
+        torch_result = _run_one_mode(
+            args=args,
+            native_enabled=False,
+            conn=conn,
+            memobj=memobj,
+            source=source,
+            destination=destination,
+            slot_mapping=slot_mapping,
+        )
+        for layer in destination:
+            layer.zero_()
+        native_result = _run_one_mode(
+            args=args,
+            native_enabled=True,
+            conn=conn,
+            memobj=memobj,
+            source=source,
+            destination=destination,
+            slot_mapping=slot_mapping,
+        )
+        _assert_copied_slots_match(source, destination, slot_mapping, hidden_dim)
+        passed, summary = compare_results(
+            torch_result,
+            native_result,
+            min_speedup=args.min_speedup,
+        )
+        print(summary)
+        return 0 if passed else 1
+    finally:
+        memobj.ref_count_down()
+        allocator.close()
+        if old_env is None:
+            os.environ.pop(ENV_MUSA_NATIVE_KV_TRANSFER, None)
+        else:
+            os.environ[ENV_MUSA_NATIVE_KV_TRANSFER] = old_env
+
+
+def _require_musa() -> None:
+    """Fail clearly when the benchmark is run away from a MUSA host."""
+    if not hasattr(torch, "musa") or not torch.musa.is_available():  # type: ignore[attr-defined]
+        raise RuntimeError("torch.musa is not available; run on a MUSA host")
+
+
+def _make_allocator(
+    memory_device: str,
+    alloc_bytes: int,
+    device: torch.device,
+) -> MemoryAllocatorInterface:
+    """Create the LMCache benchmark buffer allocator."""
+    size = max(alloc_bytes * 2, 64 * 1024 * 1024)
+    if memory_device == "musa":
+        return GPUMemoryAllocator(size=size, device=device)
+    return PinMemoryAllocator(size=size)
+
+
+def _make_metadata(args: argparse.Namespace) -> LMCacheMetadata:
+    """Create metadata matching the synthetic benchmark KV cache."""
+    return LMCacheMetadata(
+        model_name="musa-stage2-bench",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            args.num_layers,
+            2,
+            args.num_tokens,
+            args.num_heads,
+            args.head_size,
+        ),
+    )
+
+
+def _make_kvcaches(
+    args: argparse.Namespace,
+    device: torch.device,
+) -> list[torch.Tensor]:
+    """Allocate synthetic non-MLA vLLM MUSA paged KV caches."""
+    return [
+        torch.randn(
+            2,
+            args.num_blocks,
+            args.block_size,
+            args.num_heads,
+            args.head_size,
+            dtype=torch.bfloat16,
+            device=device,
+        )
+        for _ in range(args.num_layers)
+    ]
+
+
+def _run_one_mode(
+    *,
+    args: argparse.Namespace,
+    native_enabled: bool,
+    conn: VLLMPagedMemMUSAConnectorV2,
+    memobj: MemoryObj,
+    source: list[torch.Tensor],
+    destination: list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+) -> BenchmarkResult:
+    """Run one benchmark mode."""
+    os.environ[ENV_MUSA_NATIVE_KV_TRANSFER] = "1" if native_enabled else "0"
+
+    def _transfer_once() -> None:
+        conn.from_gpu(
+            memobj,
+            start=0,
+            end=args.num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=source,
+        )
+        conn.to_gpu(
+            memobj,
+            start=0,
+            end=args.num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=destination,
+        )
+
+    return _time_call(
+        name="native" if native_enabled else "torch",
+        iters=args.iters,
+        warmup_iters=args.warmup_iters,
+        fn=_transfer_once,
+    )
+
+
+def _time_call(
+    name: str,
+    iters: int,
+    warmup_iters: int,
+    fn: Callable[[], None],
+) -> BenchmarkResult:
+    """Time a synchronized MUSA callable."""
+    for _ in range(warmup_iters):
+        fn()
+    torch.musa.synchronize()  # type: ignore[attr-defined]
+    start = time.perf_counter()
+    for _ in range(iters):
+        fn()
+    torch.musa.synchronize()  # type: ignore[attr-defined]
+    return BenchmarkResult(
+        name=name,
+        seconds_per_iter=(time.perf_counter() - start) / iters,
+    )
+
+
+def _assert_copied_slots_match(
+    source: list[torch.Tensor],
+    destination: list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+    hidden_dim: int,
+) -> None:
+    """Verify destination slots match source slots after connector round-trip."""
+    for src_layer, dst_layer in zip(source, destination, strict=True):
+        src_k = src_layer[0].reshape(-1, hidden_dim)
+        src_v = src_layer[1].reshape(-1, hidden_dim)
+        dst_k = dst_layer[0].reshape(-1, hidden_dim)
+        dst_v = dst_layer[1].reshape(-1, hidden_dim)
+        torch.testing.assert_close(dst_k[slot_mapping], src_k[slot_mapping])
+        torch.testing.assert_close(dst_v[slot_mapping], src_v[slot_mapping])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/benchmarks/rag/README.md b/benchmarks/rag/README.md
new file mode 100644
index 0000000..f7515a5
--- /dev/null
+++ b/benchmarks/rag/README.md
@@ -0,0 +1,111 @@
+# Benchmarking LLM Performance: RAG Use Case
+## Overview
+
+This repository contains benchmarking tools for evaluating the performance of language models in various scenarios. The initial focus of this benchmark is on the RAG (Retrieval-augmented generation) use case. The script `rag.py` simulates RAG workloads, allowing you to analyze the serving engine's throughput and latency.  
+
+### Current Workloads
+
+- **RAG Benchmark**: Simulates a real RAG dataset to evaluate key metrics such as token throughput, average time to first token, and average quality.
+
+## Setup
+
+1. Install the required dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+## Running the RAG Benchmark
+To run the RAG benchmark, use launch_lmcache.sh and launch_vllm.sh.  
+
+How to launch:  
+After starting the serving engine, run ./launch_lmcache.sh or ./launch_vllm.sh to benchmark LMcache or vllm.  
+
+For launch_lmcache.sh:  
+Remember to match KV_STORAGE_SIZE with max_local_cache_size in lmcache config yaml.  
+Remember to match KV_CHUNK_SIZE with chunk_size in lmcache config yaml.  
+
+For launch_vllm.sh:  
+Remember to change END_INDEX in launch_vllm.sh to the end_index printed by precompute.py in launch_lmcache.sh.  
+It should be 150 in the following line(the second number).  
+```
+"Precompute from 0 to 150 for model mistralai/Mistral-7B-Instruct-v0.2"
+```
+
+Use ctrl-C to terminate the benchmark at any time, and the the script will write each request's detailed stats to the output file.  
+
+
+*Note:* the above command requires there is a serving engine with the `mistralai/Mistral-7B-Instruct-v0.2` model served locally at `http://localhost:8000/v1`. Here's an example command to launch the serving engine:
+
+```bash
+vllm serve mistralai/Mistral-7B-Instruct-v0.2 --disable-log-requests
+```
+
+Here's an example command to launch the serving engine with LMCache+CacheBlend:  
+
+```bash
+LMCACHE_CONFIG_FILE=example_blending.yaml python3 -m lmcache_vllm.vllm.entrypoints.openai.api_server --model mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.7 --port 8000
+```
+
+### What does precompute.py do
+If no --end-index provided, it will check kv-storage-size and try to precompute the documents that can be held in this size.  
+Used for precomputing some KV cache into storage.  
+### Arguments
+#### Configure the workload
+- `--dataset <str>` The path to the dataset. The format is described in `Dataset format` section.  
+- `--start-index <int>` Start from which request in the dataset.
+- `--end-index <int>` End before which request in the dataset. If not set, or set to negative value and has precomputation, it will default to the value returned by precompute according to how many requests' KV cache can be held in the given size.  
+- `--shuffle` Random shuffle the dataset.  
+- `--system-prompt <str>` System prompt before the documents.
+- `--query-prompt <str>` Query prompt after the documents and before the question in dataset.
+- `--separator <str>` The text used to separate system prompt, documents and query prompt. If enabling blending, should match the blend_separator. If not, should be "".
+- `--prompt-build-method <str>` Should be QA or FEW_SHOT, indicating different tasks.
+- `--time <int>` The number of seconds as an upper bound for this benchmark. By default no limit.
+- `--step-interval <float>` The time interval benchmarking script steps for sending requests.
+- `--max-tokens <int>` Maximum number of output tokens for every request.
+- `--qps <float>` Query per second. The rate to send requests.
+#### Configuring the serving engine connection
+- `--model <str>` The model name used by the endpoint.
+- `--base-url <str>` The URL endpoint for the language model server.
+- `--api-key <str>` API key for the language model server.
+#### Configure precompute
+To benchmark CacheBlend, we need to precompute the KV cache of documents.  
+- `--tokenizer <str>` The tokenizer name. If not provided, by default the same as `--model`.
+- `--model-config <str>` The model config name. If not provided, by default the same as `--model`.
+- `--kv-storage-size <str>` The size used for KV cache. This will decide how many requests will be sent, because we only precompute KV cache within this limit. The same as max_local_cache_size in LMCache config yaml.
+- `--kv-chunk-size <int>` The same as chunk_size in LMCache config yaml.
+- `--kv-precision-bit <int>` KV cache precision bit. By default 16 for FP16. Should be a multiple of 8.
+#### Configure output
+- `--output <str>` The csv file to dump the detailed stats for each query (default = summary.csv)
+- `--verbose` Enable verbose logging.
+
+## Benchmark Metrics
+
+- **Throughput**: Request processed per second.  
+- **Average TTFT (Time to First Token)**: Average time taken for the model to generate the first token of a response.
+- **Average Quality**: Average quality score of generation content.  
+
+## Dataset format
+Should be a json file, which is a list of dicts.  
+Every item(dict) in the list is one request with the following content.  
+```
+ {
+        "ctxs": [
+            {
+                "title": "",
+                "text": "doc_1"
+            },
+            {
+                "title": "",
+                "text": "doc_2"
+            },
+            {
+                "title": "",
+                "text": "doc_3"
+            }
+        ],
+        "question": "xxx ?",
+        "answers": [
+            "yyy"
+        ]
+    }
+```
+An example is [CacheBlend musique_s.json](https://github.com/YaoJiayi/CacheBlend/blob/main/inputs/musique_s.json)
diff --git a/benchmarks/rag/launch_lmcache.sh b/benchmarks/rag/launch_lmcache.sh
new file mode 100644
index 0000000..d0cf5ff
--- /dev/null
+++ b/benchmarks/rag/launch_lmcache.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+MODEL_NAME="mistralai/Mistral-7B-Instruct-v0.2"
+DATASET_PATH=~/CacheBlend/inputs/musique_s.json
+PROMPT_BUILD_METHOD=QA
+KV_STORAGE_SIZE=30GB
+KV_CHUNK_SIZE=256
+QPS=3.5
+BASE_URL="http://localhost:8000/v1"
+DATASET_NAME=$(echo $DATASET_PATH | awk -F'/' '{print $NF}' | awk -F'.' '{print $1}')
+OUTPUT_FILE="$DATASET_NAME"_lmcache_qps_"$QPS".csv
+
+export LMCACHE_CONFIG_FILE="example_blending.yaml"
+
+log_str=$(python3 precompute.py --model "$MODEL_NAME"\
+    --dataset "$DATASET_PATH" \
+    --prompt-build-method $PROMPT_BUILD_METHOD \
+    --kv-storage-size $KV_STORAGE_SIZE --kv-chunk-size $KV_CHUNK_SIZE \
+    --base-url $BASE_URL)
+echo "$log_str"
+RETURNED_END_INDEX=$(echo "$log_str" | awk '{print $5}')
+# Assert non-empty.
+if [ -z "$RETURNED_END_INDEX" ]; then
+    echo "Precompute returns empty end index"
+    exit 1
+fi
+python3 rag.py --qps $QPS\
+ --model "$MODEL_NAME" --dataset "$DATASET_PATH" \
+ --end-index "$RETURNED_END_INDEX" --separator "[BLEND_SEP]"\
+  --prompt-build-method $PROMPT_BUILD_METHOD --base-url $BASE_URL \
+  --max-tokens 32 --output "$OUTPUT_FILE"
\ No newline at end of file
diff --git a/benchmarks/rag/launch_vllm.sh b/benchmarks/rag/launch_vllm.sh
new file mode 100644
index 0000000..3b174d0
--- /dev/null
+++ b/benchmarks/rag/launch_vllm.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+MODEL_NAME="mistralai/Mistral-7B-Instruct-v0.2"
+DATASET_PATH=~/CacheBlend/inputs/musique_s.json
+PROMPT_BUILD_METHOD=QA
+QPS=3.5
+END_INDEX=32
+BASE_URL="http://localhost:8000/v1"
+DATASET_NAME=$(echo $DATASET_PATH | awk -F'/' '{print $NF}' | awk -F'.' '{print $1}')
+OUTPUT_FILE="$DATASET_NAME"_vllm_qps_"$QPS".csv
+
+python3 rag.py --qps $QPS\
+ --model "$MODEL_NAME" --dataset "$DATASET_PATH" \
+ --end-index "$END_INDEX" --warmup \
+ --prompt-build-method $PROMPT_BUILD_METHOD --base-url $BASE_URL \
+ --max-tokens 32 --output "$OUTPUT_FILE"
\ No newline at end of file
diff --git a/benchmarks/rag/precompute.py b/benchmarks/rag/precompute.py
new file mode 100644
index 0000000..075e3bf
--- /dev/null
+++ b/benchmarks/rag/precompute.py
@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import Tuple
+import argparse
+
+# Third Party
+from lmcache_vllm.blend_adapter import OnlineKVPreCompute
+from transformers import AutoConfig, AutoTokenizer
+from utils import (
+    PromptBuildMethodType,
+    build_fewshot_prompt,
+    build_qa_prompt,
+    load_dataset,
+)
+
+
+@dataclass
+class PrecomputeConfig:
+    # Model name.
+    model: str
+    # Tokenizer name.
+    tokenizer: str
+    # Model config path.
+    model_config: str
+    # Dataset.
+    dataset: str
+    # Start index.
+    start_idx: int
+    # End index.
+    end_idx: int
+    # KV storage size.
+    kv_storage_size: int
+    # KV chunk size.
+    kv_chunk_size: int
+    # Prompt build method.
+    prompt_build_method: PromptBuildMethodType
+    # API key
+    api_key: str
+    # Base url
+    base_url: str
+    # KV cache precision.
+    kv_precision: int
+
+
+class KVSizeCalculator:
+    def __init__(
+        self,
+        num_key_value_heads: int,
+        head_dim: int,
+        num_layers: int,
+        precision: int,
+    ):
+        self.ratio = num_key_value_heads * head_dim * num_layers * precision * 2
+
+    def get_kv_size(self, token_cnt: int) -> int:
+        return token_cnt * self.ratio
+
+
+def precompute_all_kv(config: PrecomputeConfig) -> Tuple[int, int, str]:
+    tokenizer = AutoTokenizer.from_pretrained(config.tokenizer)
+    model_config = AutoConfig.from_pretrained(config.model_config)
+    kv_size_calculator = KVSizeCalculator(
+        model_config.num_key_value_heads,
+        model_config.head_dim,
+        model_config.num_hidden_layers,
+        config.kv_precision,
+    )
+    eval_dataset = load_dataset(config.dataset)
+    start_idx = config.start_idx
+    end_idx = config.end_idx
+    if end_idx >= 0:
+        assert end_idx <= len(eval_dataset), (
+            f"end_index {end_idx} > length of dataset {len(eval_dataset)}"
+        )
+    assert start_idx >= 0, f"start_idx {start_idx} < 0"
+    assert start_idx < len(eval_dataset), (
+        f"start_idx {start_idx} >= length of dataset {len(eval_dataset)}"
+    )
+    precompute_kv = OnlineKVPreCompute(config.api_key, config.base_url, tokenizer)
+    with_bos = precompute_kv._blend_add_special_in_precomp
+    current_size_taken = 0
+    size_upper_bound = config.kv_storage_size
+    assert size_upper_bound > 0, f"size_upper_bound {size_upper_bound} <= 0"
+    current_idx = start_idx
+    round_up_token_cnt = config.kv_chunk_size
+    assert round_up_token_cnt >= 1
+    while True:
+        if end_idx >= 0:
+            if current_idx >= end_idx:
+                break
+        else:
+            if current_size_taken >= size_upper_bound or current_idx >= len(
+                eval_dataset
+            ):
+                break
+        example = eval_dataset[current_idx]
+        doc_prompts = None
+        this_case_size = 0
+        if config.prompt_build_method == PromptBuildMethodType.QA:
+            doc_prompts, _ = build_qa_prompt(example, "")
+        elif config.prompt_build_method == PromptBuildMethodType.FEW_SHOT:
+            doc_prompts, _ = build_fewshot_prompt(example)
+        assert doc_prompts is not None
+        # NOTE: Do not need chat template here.
+        # It should only affect system prompt and query prompt.
+        token_cnt = 0
+        for doc_prompt in doc_prompts:
+            assert len(doc_prompt) > 0
+            input_comps = tokenizer(doc_prompt).input_ids
+            assert len(input_comps) > 0
+            temp_cnt = len(input_comps)
+            if not with_bos:
+                if input_comps[0] == tokenizer.bos_token_id:
+                    temp_cnt -= 1
+            # Add doc token count before round up.
+            temp_cnt = (
+                (temp_cnt + round_up_token_cnt - 1) // round_up_token_cnt
+            ) * round_up_token_cnt
+            token_cnt += temp_cnt
+        assert token_cnt > 0, f"token_cnt {token_cnt} <= 0"
+        this_case_size = kv_size_calculator.get_kv_size(token_cnt)
+        if current_size_taken + this_case_size > size_upper_bound:
+            break
+        for prompt in doc_prompts:
+            precompute_kv.precompute_kv(prompt)
+        current_idx += 1
+        current_size_taken += this_case_size
+
+    return start_idx, current_idx, precompute_kv.model
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Parse RAG precompute configurations.")
+    parser.add_argument("--model", type=str, required=True, help="Model name")
+    parser.add_argument("--tokenizer", type=str, default="", help="Tokenizer name")
+    parser.add_argument(
+        "--model-config", type=str, default="", help="Model config path"
+    )
+    parser.add_argument("--dataset", type=str, required=True, help="The dataset path")
+    parser.add_argument(
+        "--start-index", type=int, default=0, help="Start index of the workload"
+    )
+    parser.add_argument(
+        "--end-index", type=int, default=-1, help="End index of the workload"
+    )
+    parser.add_argument(
+        "--prompt-build-method",
+        type=str,
+        required=True,
+        help="Prompt build method",
+    )
+    parser.add_argument(
+        "--kv-storage-size", type=str, default="", help="KV storage size"
+    )
+    parser.add_argument(
+        "--kv-chunk-size", type=int, default=256, help="KV storage chunk size"
+    )
+    parser.add_argument(
+        "--kv-precision-bit",
+        type=int,
+        default=16,
+        help="KV cache precision bit",
+    )
+    parser.add_argument(
+        "--base-url",
+        type=str,
+        required=True,
+        help="Base URL of the serving engine endpoint",
+    )
+    parser.add_argument(
+        "--api-key",
+        type=str,
+        default="EMPTY",
+        help="API key of the serving engine endpoint",
+    )
+    args = parser.parse_args()
+    return args
+
+
+def parse_size(size: str) -> int:
+    if len(size) == 0:
+        return -1
+    else:
+        size = size.upper()
+        if size.endswith("KB"):
+            return int(size[:-2]) * 1024
+        elif size.endswith("MB"):
+            return int(size[:-2]) * 1024 * 1024
+        elif size.endswith("GB"):
+            return int(size[:-2]) * 1024 * 1024 * 1024
+        elif size.endswith("TB"):
+            return int(size[:-2]) * 1024 * 1024 * 1024 * 1024
+        elif size.endswith("B"):
+            return int(size[:-1])
+        else:
+            raise ValueError(f"Invalid size unit {size}")
+
+
+def parse_prompt_build_method(
+    prompt_build_method: str,
+) -> PromptBuildMethodType:
+    prompt_build_method = prompt_build_method.upper()
+    if prompt_build_method == "QA":
+        return PromptBuildMethodType.QA
+    elif prompt_build_method == "FEW_SHOT":
+        return PromptBuildMethodType.FEW_SHOT
+    else:
+        raise ValueError(f"Invalid prompt build method {prompt_build_method}")
+
+
+def run_precompute(args):
+    kv_storage_size = parse_size(args.kv_storage_size)
+    kv_chunk_size = args.kv_chunk_size
+    prompt_build_method = parse_prompt_build_method(args.prompt_build_method)
+    kv_precision_bit = args.kv_precision_bit
+    assert kv_precision_bit % 8 == 0, (
+        f"kv_precision_bit {kv_precision_bit} is not a multiple of 8"
+    )
+    kv_precision = kv_precision_bit // 8
+    config = PrecomputeConfig(
+        model=args.model,
+        tokenizer=args.tokenizer,
+        model_config=args.model_config,
+        dataset=args.dataset,
+        start_idx=args.start_index,
+        end_idx=args.end_index,
+        kv_storage_size=kv_storage_size,
+        kv_chunk_size=kv_chunk_size,
+        prompt_build_method=prompt_build_method,
+        api_key=args.api_key,
+        base_url=args.base_url,
+        kv_precision=kv_precision,
+    )
+    start_idx, end_idx, model_name = precompute_all_kv(config)
+    return start_idx, end_idx, model_name
+
+
+def main():
+    args = parse_arguments()
+    if len(args.tokenizer) == 0:
+        args.tokenizer = args.model
+    if len(args.model_config) == 0:
+        args.model_config = args.model
+    start_idx, end_idx, model_name = run_precompute(args)
+    print(f"Precompute from {start_idx} to {end_idx} for model {model_name}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/rag/rag.py b/benchmarks/rag/rag.py
new file mode 100644
index 0000000..ebc404f
--- /dev/null
+++ b/benchmarks/rag/rag.py
@@ -0,0 +1,433 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+import argparse
+import asyncio
+import logging
+import random
+import time
+
+# Third Party
+from transformers import AutoTokenizer
+from utils import (
+    AsyncLoopWrapper,
+    PromptBuildMethodType,
+    build_rag_prompt,
+    compute_f1,
+    compute_rl,
+    init_logger,
+    load_dataset,
+)
+import openai
+import pandas as pd
+
+logger = init_logger(__name__, logging.INFO)
+
+system_prompt_set = {
+    PromptBuildMethodType.QA: "You will be asked a question after reading several passages. "  # noqa: E501
+    "Please directly answer the question based on the given passages. "
+    "Do NOT repeat the question. "
+    "The answer should be within 5 words..\nPassages:\n",
+    PromptBuildMethodType.FEW_SHOT: "Summarize the dialogue into a few short sentences. "  # noqa: E501
+    "The following are some examples.\n\n",
+}
+query_prompt_set = {
+    PromptBuildMethodType.QA: "\n\nAnswer the question directly based on the given passages."  # noqa: E501
+    " Do NOT repeat the question. "
+    "The answer should be within 5 words. \nQuestion:",
+    PromptBuildMethodType.FEW_SHOT: "",
+}
+
+
+@dataclass
+class WorkloadConfig:
+    # Overall QPS
+    qps: float
+    # Model name
+    model: str
+    # Tokenizer name
+    tokenizer: str
+    # Dataset.
+    dataset: str
+    # Start index of the workload
+    start_index: int
+    # End index of the workload
+    end_index: int
+    # Random shuffle.
+    shuffle: bool
+    # System prompt.
+    system_prompt: str
+    # Separator.
+    separator: str
+    # Query prompt.
+    query_prompt: str
+    # Prompt build method.
+    prompt_build_method: PromptBuildMethodType
+    # Max tokens for each generation.
+    max_tokens: int
+
+
+@dataclass
+class Response:
+    request_id: int
+    body: str
+    ttft: float
+    generation_time: float
+    prompt_tokens: int
+    generation_tokens: int
+    launch_time: float
+    finish_time: float
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Parse RAG benchmark configurations.")
+    parser.add_argument("--qps", type=float, required=True, help="Overall QPS")
+    parser.add_argument("--model", type=str, required=True, help="Model name")
+    parser.add_argument("--tokenizer", type=str, default="", help="Tokenizer name")
+    parser.add_argument("--dataset", type=str, required=True, help="The dataset path")
+    parser.add_argument(
+        "--start-index", type=int, default=0, help="Start index of the workload"
+    )
+    parser.add_argument(
+        "--end-index", type=int, default=-1, help="End index of the workload"
+    )
+    parser.add_argument("--shuffle", action="store_true", help="Random shuffle")
+    parser.add_argument("--system-prompt", type=str, default="", help="System prompt")
+    parser.add_argument("--separator", type=str, default="", help="Separator")
+    parser.add_argument("--query-prompt", type=str, default="", help="Query prompt")
+    parser.add_argument(
+        "--prompt-build-method",
+        type=str,
+        required=True,
+        help="Prompt build method",
+    )
+    parser.add_argument(
+        "--base-url",
+        type=str,
+        required=True,
+        help="Base URL of the serving engine endpoint",
+    )
+    parser.add_argument(
+        "--api-key",
+        type=str,
+        default="EMPTY",
+        help="API key of the serving engine endpoint",
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default="summary.csv",
+        help="The output file name (ended with csv or txt) for the summary csv and txt",
+    )
+    parser.add_argument(
+        "--warmup", action="store_true", help="Whether to enable warmup"
+    )
+    parser.add_argument(
+        "--time",
+        type=int,
+        default=None,
+        help="The total running time in seconds",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Whether to enable verbose logging",
+    )
+    parser.add_argument(
+        "--max-tokens",
+        type=int,
+        default=32,
+        help="Max tokens for each generation",
+    )
+    parser.add_argument(
+        "--step-interval", type=float, default=0.02, help="Step interval"
+    )
+    args = parser.parse_args()
+    return args
+
+
+class RequestExecutor:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        prompt_build_method: PromptBuildMethodType,
+        model: str,
+    ):
+        self.client = openai.AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self.model = model
+        self.loop = AsyncLoopWrapper.GetOrStartLoop()
+        self.prompt_build_method = prompt_build_method
+
+    async def _async_launch_request(self, request_id, prompt, max_tokens):
+        start_time = time.time()
+        first_token_time = None
+        words = ""
+        response = None
+        if self.prompt_build_method == PromptBuildMethodType.QA:
+            messages = [{"role": "user", "content": prompt}]
+            response = await self.client.chat.completions.create(
+                messages=messages,
+                model=self.model,
+                temperature=0,
+                stream=True,
+                max_tokens=max_tokens,
+                stream_options={"include_usage": True},
+            )
+        elif self.prompt_build_method == PromptBuildMethodType.FEW_SHOT:
+            response = await self.client.completions.create(
+                prompt=prompt,
+                model=self.model,
+                temperature=0,
+                stream=True,
+                max_tokens=max_tokens,
+                stream_options={"include_usage": True},
+            )
+        else:
+            raise ValueError(f"Invalid prompt build method {self.prompt_build_method}")
+        async for tok in response:
+            if not tok.choices:
+                continue
+            chunk_message = tok.choices[0].delta.content
+            if chunk_message is not None:
+                if first_token_time is None and chunk_message != "":
+                    first_token_time = time.time()
+                words += chunk_message
+        tokens_out = tok.usage.completion_tokens
+        tokens_prefill = tok.usage.prompt_tokens
+        finish_time = time.time()
+        if first_token_time is None:
+            first_token_time = finish_time
+        return Response(
+            request_id=request_id,
+            body=words,
+            ttft=first_token_time - start_time,
+            generation_time=finish_time - first_token_time,
+            prompt_tokens=tokens_prefill,
+            generation_tokens=tokens_out,
+            launch_time=start_time,
+            finish_time=finish_time,
+        )
+
+    def launch_request(self, request_id: int, prompt, max_tokens, finish_callback):
+        """
+        finish_callback: Callable[[Response], None]
+        """
+        real_callback = lambda x: finish_callback(x.result())
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_launch_request(request_id, prompt, max_tokens),
+            self.loop,
+        )
+        future.add_done_callback(real_callback)
+
+
+def warmup_engine(executor: RequestExecutor):
+    logger.info("Warming up the engine")
+    for i in range(10):
+        prompt = f"WARMUP: Hi, I'm user {i}. Here are some text: {'hi ' * 100}."
+        executor.launch_request(-1, prompt, 100, lambda x: None)
+
+    AsyncLoopWrapper.WaitLoop()
+    logger.info("Warm up finished.")
+
+
+class RAGManager:
+    def __init__(self, workload_config: WorkloadConfig):
+        self.workload_config = workload_config
+        eval_dataset = load_dataset(workload_config.dataset)
+        start_index = workload_config.start_index
+        end_index = workload_config.end_index
+        if end_index < 0:
+            end_index = len(eval_dataset)
+        eval_dataset = eval_dataset[start_index:end_index]
+        if workload_config.shuffle:
+            random.shuffle(eval_dataset)
+        self._prompts = []
+        self._answers = []
+        self._build_method = workload_config.prompt_build_method
+        self._generated_text: list[str | None] = []
+        self._generation_time: list[float | None] = []
+        self._prefill_tok_cnt: list[int | None] = []
+        self._generation_tok_cnt: list[int | None] = []
+        self._ttft: list[float | None] = []
+        self._tpot: list[float | None] = []
+        for ex in eval_dataset:
+            prompt, _ = build_rag_prompt(
+                workload_config.system_prompt,
+                ex,
+                workload_config.query_prompt,
+                workload_config.separator,
+                workload_config.prompt_build_method,
+            )
+            self._prompts.append(prompt)
+            self._answers.append(ex["answers"])
+            self._generated_text.append(None)
+            self._generation_time.append(None)
+            self._prefill_tok_cnt.append(None)
+            self._generation_tok_cnt.append(None)
+            self._ttft.append(None)
+            self._tpot.append(None)
+        self._tokenizer = AutoTokenizer.from_pretrained(workload_config.tokenizer)
+        self._last_request_time = -1.0
+        self._last_request_index = 0
+        assert workload_config.qps > 0
+        self._gap = 1.0 / workload_config.qps
+        self._max_tokens = workload_config.max_tokens
+
+    def _update_result(self, response: Response):
+        self._generated_text[response.request_id] = response.body
+        self._ttft[response.request_id] = response.ttft
+        self._tpot[response.request_id] = (
+            response.generation_time / response.generation_tokens
+        )
+        self._generation_time[response.request_id] = response.generation_time
+        self._prefill_tok_cnt[response.request_id] = response.prompt_tokens
+        self._generation_tok_cnt[response.request_id] = response.generation_tokens
+
+    def step(self, timestamp: float, executor: RequestExecutor) -> bool:
+        if self._last_request_index >= len(self._prompts):
+            return False
+        if (
+            self._last_request_time < 0
+            or timestamp >= self._last_request_time + self._gap
+        ):
+            prompt = self._prompts[self._last_request_index]
+            request_id = self._last_request_index
+            self._last_request_time = timestamp
+            self._last_request_index += 1
+            executor.launch_request(
+                request_id, prompt, self._max_tokens, self._update_result
+            )
+        return True
+
+    def summary(self, start_time: float, end_time: float) -> pd.DataFrame:
+        cnt = len(self._ttft)
+        assert cnt > 0
+        avg_ttft = sum(ttft for ttft in self._ttft if ttft is not None) / cnt
+        avg_tpot = sum(tpot for tpot in self._tpot if tpot is not None) / cnt
+        # Create a dataframe
+        quality = []
+        for i in range(cnt):
+            if self._build_method == PromptBuildMethodType.QA:
+                quality.append(
+                    max(
+                        [
+                            compute_f1(self._generated_text[i], answer, self._tokenizer)
+                            for answer in self._answers[i]
+                        ]
+                    )
+                )
+            elif self._build_method == PromptBuildMethodType.FEW_SHOT:
+                quality.append(
+                    max(
+                        [
+                            compute_rl(self._generated_text[i], answer)
+                            for answer in self._answers[i]
+                        ]
+                    )
+                )
+            else:
+                raise ValueError(f"Invalid prompt build method {self._build_method}")
+        avg_quality = sum(quality) / cnt
+        df = pd.DataFrame(
+            {
+                "quality": quality,
+                "ttft": self._ttft,
+                "tpot": self._tpot,
+                "generation_time": self._generation_time,
+                "prefill_token_cnt": self._prefill_tok_cnt,
+                "generation_token_cnt": self._generation_tok_cnt,
+            }
+        )
+        total_time = end_time - start_time
+        thput = cnt / total_time
+        logger.info(
+            f"Summary: {cnt} requests, average_ttft={avg_ttft} (second)\n"
+            f" average_tpot={avg_tpot} (second)\n"
+            f"throughput={thput} (req/s)\n"
+            f"average_quality={avg_quality}\n"
+        )
+        return df
+
+
+def run_rag(args):
+    build_prompt_method_str = args.prompt_build_method.upper()
+    build_prompt_method = None
+    if build_prompt_method_str == "QA":
+        build_prompt_method = PromptBuildMethodType.QA
+    elif build_prompt_method_str == "FEW_SHOT":
+        build_prompt_method = PromptBuildMethodType.FEW_SHOT
+    else:
+        raise ValueError(f"Invalid prompt build method {build_prompt_method_str}")
+    workload_config = WorkloadConfig(
+        qps=args.qps,
+        model=args.model,
+        tokenizer=args.tokenizer,
+        dataset=args.dataset,
+        start_index=args.start_index,
+        end_index=args.end_index,
+        shuffle=args.shuffle,
+        system_prompt=args.system_prompt,
+        separator=args.separator,
+        query_prompt=args.query_prompt,
+        prompt_build_method=build_prompt_method,
+        max_tokens=args.max_tokens,
+    )
+    executor = RequestExecutor(
+        base_url=args.base_url,
+        api_key=args.api_key,
+        prompt_build_method=build_prompt_method,
+        model=args.model,
+    )
+    if args.warmup:
+        warmup_engine(executor)
+    manager = RAGManager(workload_config)
+    step_interval = args.step_interval
+    num_steps = 0
+    start_time = time.time()
+    try:
+        while True:
+            num_steps += 1
+            effective = manager.step(time.time(), executor)
+            if not effective:
+                break
+            time.sleep(step_interval)
+            if args.time is not None and time.time() - start_time > args.time:
+                break
+
+    except KeyboardInterrupt:
+        logger.info("Interrupted, waiting for the final result")
+
+    AsyncLoopWrapper.StopLoop()
+
+    logger.info(f"Finished benchmarking, dumping summary to {args.output}")
+    summary = manager.summary(start_time, time.time())
+    summary.to_csv(args.output, index=False)
+
+
+def main():
+    args = parse_arguments()
+    build_prompt_method_str = args.prompt_build_method.upper()
+    build_prompt_method = None
+    if build_prompt_method_str == "QA":
+        build_prompt_method = PromptBuildMethodType.QA
+    elif build_prompt_method_str == "FEW_SHOT":
+        build_prompt_method = PromptBuildMethodType.FEW_SHOT
+    else:
+        raise ValueError(f"Invalid prompt build method {build_prompt_method_str}")
+    if len(args.system_prompt) == 0:
+        args.system_prompt = system_prompt_set[build_prompt_method]
+    if len(args.query_prompt) == 0:
+        args.query_prompt = query_prompt_set[build_prompt_method]
+    if len(args.tokenizer) == 0:
+        args.tokenizer = args.model
+    args.system_prompt = args.system_prompt.encode().decode("unicode_escape")
+    args.query_prompt = args.query_prompt.encode().decode("unicode_escape")
+    if args.verbose:
+        global logger
+        logger = init_logger(__name__, logging.DEBUG)
+    run_rag(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/rag/requirements.txt b/benchmarks/rag/requirements.txt
new file mode 100644
index 0000000..d56d94d
--- /dev/null
+++ b/benchmarks/rag/requirements.txt
@@ -0,0 +1,4 @@
+tqdm
+pandas
+openai
+rouge_score
diff --git a/benchmarks/rag/utils.py b/benchmarks/rag/utils.py
new file mode 100644
index 0000000..cc4340c
--- /dev/null
+++ b/benchmarks/rag/utils.py
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from enum import Enum, auto
+from logging import Logger
+import asyncio
+import collections
+import json
+import logging
+import re
+import string
+import threading
+
+# Third Party
+from rouge_score import rouge_scorer
+
+
+def build_format(color):
+    reset = "\x1b[0m"
+    underline = "\x1b[3m"
+    return (
+        f"{color}[%(asctime)s] %(levelname)s:{reset} %(message)s "
+        + f"{underline}(%(filename)s:%(lineno)d:%(name)s){reset}"
+    )
+
+
+class CustomFormatter(logging.Formatter):
+    grey = "\x1b[1m"
+    green = "\x1b[32;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+
+    FORMATS = {
+        logging.DEBUG: build_format(grey),
+        logging.INFO: build_format(green),
+        logging.WARNING: build_format(yellow),
+        logging.ERROR: build_format(red),
+        logging.CRITICAL: build_format(bold_red),
+    }
+
+    def format(self, record):
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def init_logger(name: str, log_level=logging.DEBUG) -> Logger:
+    logger = logging.getLogger(name)
+
+    logger.handlers.clear()
+    logger.propagate = False
+
+    ch = logging.StreamHandler()
+    ch.setLevel(log_level)
+    ch.setFormatter(CustomFormatter())
+    logger.addHandler(ch)
+    logger.setLevel(logging.DEBUG)
+
+    return logger
+
+
+class AsyncLoopWrapper:
+    _loop: asyncio.AbstractEventLoop | None = None
+    _thread: threading.Thread | None = None
+    _logger = init_logger("AsyncLoopWrapper")
+
+    @classmethod
+    def WaitLoop(cls):
+        assert cls._loop is not None, "Loop is not started"
+
+        async def wait_for_tasks():
+            current_task = asyncio.current_task(cls._loop)
+            tasks = [
+                task
+                for task in asyncio.all_tasks(cls._loop)
+                if not task.done() and task is not current_task
+            ]
+            cls._logger.info(f"Waiting for {len(tasks)} tasks to finish")
+            if tasks:
+                await asyncio.gather(*tasks)
+
+        # Schedule the wait_for_tasks coroutine to be executed in the loop
+        future = asyncio.run_coroutine_threadsafe(wait_for_tasks(), cls._loop)
+        try:
+            # Wait for wait_for_tasks to complete
+            future.result()
+        except Exception as e:
+            cls._logger.error(f"Error while waiting for tasks: {e}")
+
+    @classmethod
+    def StartLoop(cls):
+        if cls._loop is not None:
+            cls._logger.warning("Loop is already started")
+            return
+
+        if cls._loop is None:
+            cls._loop = asyncio.new_event_loop()
+
+        def run_loop():
+            asyncio.set_event_loop(cls._loop)
+            cls._logger.debug("Starting the asyncio loop")
+            cls._loop.run_forever()
+
+        cls._thread = threading.Thread(target=run_loop)
+        cls._thread.start()
+
+    @classmethod
+    def StopLoop(cls):
+        assert cls._loop is not None, "Loop is not started"
+        assert cls._thread is not None, "Thread is not started"
+
+        def stop_loop():
+            cls._logger.debug("Stopping the loop!")
+            cls._loop.stop()
+
+        cls._logger.info("Waiting for remaining tasks to finish")
+        cls.WaitLoop()
+
+        cls._loop.call_soon_threadsafe(stop_loop)
+        cls._thread.join()
+
+    @classmethod
+    def GetLoop(cls) -> asyncio.AbstractEventLoop:
+        assert cls._loop is not None, "Loop is not started"
+        return cls._loop
+
+    @classmethod
+    def GetOrStartLoop(cls) -> asyncio.AbstractEventLoop:
+        if cls._loop is None:
+            cls.StartLoop()
+        assert cls._loop is not None, "Loop is not started"
+        return cls._loop
+
+
+class PromptBuildMethodType(Enum):
+    QA = auto()
+    FEW_SHOT = auto()
+
+
+def load_dataset(dataset_path):
+    print("Loading dataset:", dataset_path)
+    with open(dataset_path) as f:
+        return json.load(f)
+
+
+def normalize_question(question):
+    if not question.endswith("?"):
+        question = question + "?"
+
+    return question[0].lower() + question[1:]
+
+
+def parse_generation(s):
+    s = s.lstrip("\n").split("\n")[0]
+    if s.startswith("Yes") or s.startswith("yes"):
+        s = "Yes"
+    elif (s.split()[0]).startswith("No") or (s.split()[0]).startswith("no"):
+        s = "No"
+    return s
+
+
+def normalize_answer(s):
+    def remove_articles(text):
+        return re.sub(r"\b(a|an|the)\b", " ", text)
+
+    def white_space_fix(text):
+        return " ".join(text.split())
+
+    def remove_punc(text):
+        exclude = set(string.punctuation)
+        return "".join(ch for ch in text if ch not in exclude)
+
+    def lower(text):
+        return text.lower()
+
+    return white_space_fix(remove_articles(remove_punc(lower(s))))
+
+
+def build_qa_prompt(example, query_prompt):
+    q = normalize_question(example["question"])
+    doc_prompts = [f"{ctx['title']}\n\n{ctx['text']}\n\n" for ctx in example["ctxs"]]
+    q_prompt = f"{query_prompt}{q}\nAnswer:"
+    return doc_prompts, q_prompt
+
+
+def build_fewshot_prompt(example):
+    q = "\n\n" + example["question"]
+    doc_prompts = [f"{ctx['text']}" for ctx in example["ctxs"]]
+    q_prompt = f"{q}"
+    return doc_prompts, q_prompt
+
+
+def compute_f1(a_pred, a_gold, tokenizer):
+    a_pred = parse_generation(a_pred)
+    gold_toks = tokenizer.encode(normalize_answer(a_gold))[1:]
+    pred_toks = tokenizer.encode(normalize_answer(a_pred))[1:]
+    common = collections.Counter(gold_toks) & collections.Counter(pred_toks)
+    num_same = sum(common.values())
+    if len(gold_toks) == 0 or len(pred_toks) == 0:
+        # If either is no-answer, then F1 is 1 if they agree, 0 otherwise
+        return int(gold_toks == pred_toks)
+    if num_same == 0:
+        return 0
+    precision = 1.0 * num_same / len(pred_toks)
+    recall = 1.0 * num_same / len(gold_toks)
+    f1 = (2 * precision * recall) / (precision + recall)
+    return f1
+
+
+def compute_rl(pred, gold):
+    scorer = rouge_scorer.RougeScorer(["rougeL"], use_stemmer=True)
+    rougeL = scorer.score(gold, pred)["rougeL"].fmeasure
+    return rougeL
+
+
+def build_rag_prompt(
+    system_prompt,
+    example,
+    query_prompt,
+    separator: str,
+    prompt_build_method: PromptBuildMethodType,
+):
+    doc_prompts = None
+    q_prompt = None
+    if prompt_build_method == PromptBuildMethodType.FEW_SHOT:
+        doc_prompts, q_prompt = build_fewshot_prompt(example)
+    elif prompt_build_method == PromptBuildMethodType.QA:
+        doc_prompts, q_prompt = build_qa_prompt(example, query_prompt)
+    else:
+        raise ValueError(f"Invalid prompt build method {prompt_build_method}")
+    final_prompt = separator.join([system_prompt] + doc_prompts + [q_prompt])
+    return final_prompt, doc_prompts
diff --git a/benchmarks/storage_backend_io/README.md b/benchmarks/storage_backend_io/README.md
new file mode 100644
index 0000000..ca52b4d
--- /dev/null
+++ b/benchmarks/storage_backend_io/README.md
@@ -0,0 +1,226 @@
+# Storage Backend I/O Benchmark
+
+This microbenchmark compares multiple storage backends under high write/read concurrency:
+- **LocalDiskBackend** - Local disk with optional O_DIRECT
+- **RustRawBlockBackend** - Raw block device with optional O_DIRECT and io_uring
+- **Hf3fsBackend** - HF3FS remote storage
+- **FsBackend** - Filesystem connector backend
+- The **io_uring** backend can optionally use **io_uring_cmd** (NVMe passthrough) for direct device access.
+
+## What It Measures
+
+- Total time to submit and complete `num_ops` write (put) or read (get) operations
+- Effective ops/sec under concurrent submission
+- Optional data integrity verification for read benchmarks
+
+## Usage
+
+```bash
+# Local disk backend (write benchmark)
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 512 \
+  --concurrency 32 \
+  --backend local_disk \
+  --local-disk-dir /tmp/lmcache_local_disk_bench \
+  --max-local-disk-gb 2 \
+  --local-disk-odirect \
+  --output-json /tmp/storage_backend_io.json
+
+# Rust raw block backend with io_uring (write benchmark)
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 512 \
+  --concurrency 32 \
+  --backend rust_raw_block \
+  --raw-device /dev/nvme0n1 \
+  --raw-odirect \
+  --use-uring \
+  --output-json /tmp/storage_backend_io.json
+
+# Rust raw block backend (write + read benchmark with integrity check)
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 512 \
+  --concurrency 32 \
+  --backend rust_raw_block \
+  --write_bench False \
+  --raw-device /dev/nvme0n1 \
+  --verify-integrity \
+  --output-json /tmp/storage_backend_io.json
+
+# Rust raw block backend with io_uring_cmd (write benchmark)
+# Note: io_uring_cmd requires NVMe character device node (/dev/ngXnY)
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 1024 \
+  --concurrency 4 \
+  --backend rust_raw_block \
+  --raw-device /dev/ng0n1 \
+  --chunk-size 256 \
+  --alignment 4096 \
+  --use-uring \
+  --use-uring-cmd \
+  --output-json /tmp/rust_raw_block_uring_cmd.json
+
+# HF3FS backend (write benchmark)
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 512 \
+  --concurrency 32 \
+  --backend hf3fs_backend \
+  --remote-url "hf3fs:///3fs/stage/hello,/3fs/stage/world" \
+  --output-json /tmp/storage_backend_io.json
+
+# FS backend (write benchmark)
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 512 \
+  --concurrency 32 \
+  --backend fs_backend \
+  --remote-url "/tmp/fs_backend_test" \
+  --output-json /tmp/storage_backend_io.json
+```
+
+### Backend Options
+
+| Backend | Description |
+|---------|-------------|
+| `local_disk` | Local disk storage with optional O_DIRECT support |
+| `rust_raw_block` | Raw block device with O_DIRECT and optional io_uring |
+| `hf3fs_backend` | HF3FS remote storage backend |
+| `fs_backend` | Filesystem connector backend |
+| `both` | Run both local_disk and rust_raw_block backends |
+
+### Key Arguments
+
+- `--write_bench`: Set to `True` (default) for write-only benchmark, `False` for write+read benchmark
+- `--use-uring`: Enable io_uring for raw block backend (Linux 5.1+)
+- `--chunk-size`: Chunk size for the backend (default: 256)
+- `--verify_integrity`: Verify data integrity after reads (requires `--write_bench False`)
+- `--remote-url`: Remote storage URL for hf3fs/fs backends
+
+### Notes
+
+- If `--raw-device` is not provided, the benchmark creates `raw_block.bin` in the same `--local-disk-dir` so both backends use the same filesystem.
+- This is safe but **not** representative of true raw block performance.
+- If `--raw-device` points to a real block device (`/dev/...`), the benchmark does not call `truncate()` on that path.
+- `--raw-odirect` should only be used with a real block device that supports O_DIRECT.
+- When `--local-disk-odirect` is enabled, the benchmark allocates **page-aligned** buffers to avoid EINVAL from O_DIRECT.
+- Local disk backend uses its internal worker pool; completion is tracked via callbacks.
+- Rust raw block benchmark uses a unique manifest path per run to avoid stale-index reuse between runs.
+- For io_uring there is a limit on the number of fixed buffers that can be registered. For unprivileged users its 16384.
+- Buffer registration and de-registration is time consuming.
+- **io_uring_cmd** requires using the NVMe character device node (e.g., `/dev/ng0n1`) instead of the block device node (e.g., `/dev/nvme0n1`).
+- **io_uring_cmd** requires io_uring as the underlying I/O engine.
+
+## How To Compare On Real NVMe
+
+Use the same physical device for both tests:
+- local_disk on an ext4 mount
+- rust_raw_block on the raw block device (unmounted)
+
+Example parameters:
+- `num_ops=65536`
+- `concurrency=4`
+- `--local-disk-odirect`
+- `--raw-odirect`
+
+### 1) Run local_disk on ext4
+
+```bash
+# WARNING: mkfs will erase the target device.
+sudo mkfs.ext4 -F /dev/nvme1n1
+sudo mkdir -p /mnt/local_disk_mount
+sudo mount -t ext4 /dev/nvme1n1 /mnt/local_disk_mount
+sudo chown "$USER":"$USER" /mnt/local_disk_mount
+
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 65536 \
+  --concurrency 4 \
+  --backend local_disk \
+  --local-disk-dir /mnt/local_disk_mount/lmcache_local_disk_bench \
+  --max-local-disk-gb 120 \
+  --local-disk-odirect \
+  --output-json /tmp/local_disk_ext4.json
+```
+
+### 2) Run rust_raw_block on raw device
+
+```bash
+sudo umount /mnt/local_disk_mount
+
+python benchmarks/storage_backend_io/storage_backend_io_benchmark.py \
+  --num-ops 65536 \
+  --concurrency 4 \
+  --backend rust_raw_block \
+  --raw-device /dev/nvme1n1 \
+  --raw-odirect \
+  --output-json /tmp/rust_raw_block_raw.json
+```
+
+### 3) Compute comparison
+
+```bash
+python - <<'PY'
+import json
+
+with open("/tmp/local_disk_ext4.json") as f:
+    local = json.load(f)[0]["ops_per_sec"]
+with open("/tmp/rust_raw_block_raw.json") as f:
+    rust = json.load(f)[0]["ops_per_sec"]
+
+print(f"local_disk ops/sec: {local:.2f}")
+print(f"rust_raw_block ops/sec: {rust:.2f}")
+print(f"rust vs local: {(rust / local - 1.0) * 100.0:+.2f}%")
+PY
+```
+
+## Output
+
+The script prints a summary and optionally writes JSON results if `--output-json` is provided.
+
+### Write Benchmark Output
+
+```
+local_disk: ops=512 concurrency=32 elapsed=1.234s ops/sec=415.23
+```
+
+### Write + Read Benchmark Output
+
+```
+read_rust_raw_block: ops=512 concurrency=32 write_elapsed=1.234s write_ops/sec=415.23 read_elapsed=0.567s read_ops/sec=902.84 total_elapsed=1.801s
+  Integrity check: PASSED (errors=0)
+```
+
+### JSON Output Structure
+
+```json
+[
+  {
+    "backend": "local_disk",
+    "num_ops": 512,
+    "concurrency": 32,
+    "write_elapsed_sec": 1.234,
+    "write_ops_per_sec": 415.23,
+    "use_odirect": true
+  }
+]
+```
+
+For write+read benchmarks (`--write_bench False`):
+
+```json
+[
+  {
+    "backend": "rust_raw_block",
+    "num_ops": 512,
+    "concurrency": 32,
+    "write_elapsed_sec": 1.234,
+    "write_ops_per_sec": 415.23,
+    "read_elapsed_sec": 0.567,
+    "read_ops_per_sec": 902.84,
+    "total_elapsed_sec": 1.801,
+    "use_odirect": true,
+    "verify_integrity": true,
+    "integrity_errors": 0,
+    "integrity_passed": true,
+    "use_uring": false,
+    "use_uring_cmd": false
+  }
+]
+```
diff --git a/benchmarks/storage_backend_io/storage_backend_io_benchmark.py b/benchmarks/storage_backend_io/storage_backend_io_benchmark.py
new file mode 100644
index 0000000..5839a9a
--- /dev/null
+++ b/benchmarks/storage_backend_io/storage_backend_io_benchmark.py
@@ -0,0 +1,1257 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Samsung Electronics Co., Ltd.All Rights Reserved
+#
+# 2026/4/20 support benchmark write performance of hf3fs and fs backend
+#   Wenwen Chen <wenwen.chen@samsung.com>
+#   Ruyi Zhang <ruyi.zhang@samsung.com>
+
+"""Benchmark storage backends under high write/read concurrency.
+This module provides a framework for benchmarking different storage backends
+(LocalDiskBackend, RustRawBlockBackend, RemoteBackend, etc.) with consistent
+logic. Supports both write and read benchmarks with optional integrity verification.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from concurrent.futures import Future, ThreadPoolExecutor
+from typing import Any, Callable, Optional
+import argparse
+import asyncio
+import json
+import os
+import stat
+import tempfile
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.local_disk_backend import LocalDiskBackend
+from lmcache.v1.storage_backend.plugins.rust_raw_block_backend import (
+    RustRawBlockBackend,
+)
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+logger = init_logger(__name__)
+# Type aliases
+OnCompleteCallback = Callable[[CacheEngineKey], None]
+
+
+# ============================================================================
+# Constants
+# ============================================================================
+DEFAULT_CHUNK_SIZE = 256
+
+# 2nd dim should equal to chunk size
+DEFAULT_KV_SHAPE = (28, 2, 256, 8, 128)
+# DEFAULT_SHAPE_LIST = [2, 28, 256, 1024]
+DEFAULT_SHAPE_LIST = [2, 16, 256, 128]
+
+DEFAULT_TORCH_SHAPE = torch.Size(DEFAULT_SHAPE_LIST)
+DEFAULT_DTYPE = torch.bfloat16  # 2Bytes
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def _start_loop() -> tuple[asyncio.AbstractEventLoop, threading.Thread]:
+    """Start an async event loop in a background thread."""
+    loop = asyncio.new_event_loop()
+    t = threading.Thread(target=loop.run_forever, name="bench-loop", daemon=True)
+    t.start()
+    return loop, t
+
+
+def _stop_loop(loop: asyncio.AbstractEventLoop, t: threading.Thread) -> None:
+    """Stop the async event loop."""
+    loop.call_soon_threadsafe(loop.stop)
+    t.join(timeout=5)
+    loop.close()
+
+
+def _build_metadata(chunk_size: int) -> LMCacheMetadata:
+    """Build test metadata for benchmark."""
+    kv_shape = (
+        DEFAULT_KV_SHAPE[0],
+        DEFAULT_KV_SHAPE[1],
+        chunk_size,
+        DEFAULT_KV_SHAPE[3],
+        DEFAULT_KV_SHAPE[4],
+    )
+    logger.info(f"_build_metadata: chunk_size {chunk_size}, kv_shape {kv_shape}")
+    return LMCacheMetadata(
+        model_name="benchmark_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=DEFAULT_DTYPE,
+        kv_shape=kv_shape,
+        chunk_size=chunk_size,
+    )
+
+
+def _make_memory_objs(
+    num_ops: int,
+    use_aligned: bool,
+    alignment: int,
+    keepalive: list[torch.Tensor],
+    memory_allocator: Optional[MemoryAllocatorInterface] = None,
+    shapes: Optional[list[torch.Size]] = None,
+    start_idx: int = 0,
+) -> list:
+    """Create memory objects for benchmark."""
+    if memory_allocator is None:
+        memory_allocator = AdHocMemoryAllocator(device="cpu")
+    if shapes is None:
+        shapes = [DEFAULT_TORCH_SHAPE]
+    logger.info(f"_make_memory_objs, shapes: {shapes}")
+
+    objs = []
+    for i in range(num_ops):
+        if use_aligned:
+            num_bytes = shapes[0].numel() * DEFAULT_DTYPE.itemsize
+            base = torch.empty(
+                torch.Size([num_bytes + alignment]),
+                dtype=torch.uint8,
+                device="cpu",
+            )
+            offset = (-base.data_ptr()) % alignment
+            aligned = base[offset : offset + num_bytes]
+            keepalive.append(base)
+            obj = TensorMemoryObj(
+                raw_data=aligned,
+                metadata=MemoryObjMetadata(
+                    shape=shapes[0],
+                    dtype=DEFAULT_DTYPE,
+                    address=0,
+                    phy_size=0,
+                    ref_count=1,
+                    pin_count=0,
+                    fmt=MemoryFormat.KV_T2D,
+                    shapes=shapes,
+                    dtypes=[DEFAULT_DTYPE],
+                ),
+                parent_allocator=memory_allocator,
+            )
+        else:
+            allocated_obj = memory_allocator.allocate(
+                shapes,
+                [DEFAULT_DTYPE],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert allocated_obj is not None
+            obj = allocated_obj  # type: ignore[assignment]
+        assert obj.tensor is not None
+        obj.tensor.fill_(start_idx + i)
+        objs.append(obj)
+    return objs
+
+
+def _release_memory_objs(objs: list) -> None:
+    """Release memory objects."""
+    for obj in objs:
+        try:
+            obj.ref_count_down()
+        except Exception:
+            pass
+
+
+def _make_keys(num_ops: int) -> list[CacheEngineKey]:
+    """Create cache keys for benchmark."""
+    return [
+        CacheEngineKey("benchmark_model", 1, 0, i, DEFAULT_DTYPE)
+        for i in range(num_ops)
+    ]
+
+
+def _compute_required_buffer_gb(
+    metadata: LMCacheMetadata,
+    num_ops: int,
+    chunk_size: int,
+) -> float:
+    """Compute the required CPU buffer size in GB for the benchmark.
+
+    Calculates the total size of all chunks based on KV shape and dtype,
+    then converts to GB with a small floor margin.
+
+    Args:
+        metadata: The benchmark metadata containing KV shape and dtype info.
+        num_ops: Number of put/get operations.
+        chunk_size: The chunk size used by the backend.
+
+    Returns:
+        Required buffer size in GB (minimum 0.01 GB).
+    """
+    chunk_size_bytes = (
+        metadata.kv_shape[0]
+        * metadata.kv_shape[1]
+        * chunk_size
+        * metadata.kv_shape[3]
+        * metadata.kv_shape[4]
+        * metadata.kv_dtype.itemsize
+    )
+    return max(0.01, (num_ops * chunk_size_bytes) / (1024**3))
+
+
+# ============================================================================
+# Abstract Base Class for Storage Backends
+# ============================================================================
+class StorageBackendBenchmark(ABC):
+    """Abstract base class for storage backend benchmarks.
+
+    This class provides common benchmark logic and defines abstract methods
+    that each backend implementation must override.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        num_ops: int,
+        concurrency: int,
+        use_odirect: bool,
+        alignment: int,
+        write_bench: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+        use_uring: bool = False,
+    ):
+        op = "write_" if write_bench else "read_"
+        self._backend_name = op + name
+        self.num_ops = num_ops
+        self.concurrency = concurrency
+        self.use_odirect = use_odirect
+        self.alignment = alignment
+        self.write_bench = write_bench
+        self.chunk_size = chunk_size
+        self.verify_integrity = verify_integrity
+        self.use_uring = use_uring
+
+        # Runtime state
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._loop_thread: Optional[threading.Thread] = None
+        self._local_cpu: LocalCPUBackend
+        self._backend: StorageBackendInterface
+        self._keys: list[CacheEngineKey] = []
+        self._objs: list[TensorMemoryObj] = []
+        self._keepalive: list[torch.Tensor] = []
+        self._start_time: float
+        # completed ops
+        self._completed = 0
+        # lock for _completed
+        self._lock = threading.Lock()
+        self._done = threading.Event()
+        # Flag to skip cleanup in run() if already handled in _execute_benchmark()
+        self._skip_cleanup = False
+
+    @property
+    def backend_name(self) -> str:
+        return self._backend_name
+
+    @property
+    @abstractmethod
+    def extra_config_keys(self) -> dict:
+        """Return extra config keys specific to this backend."""
+        pass
+
+    @abstractmethod
+    def _create_backend(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ) -> StorageBackendInterface:
+        """Create and return the backend instance."""
+        pass
+
+    @abstractmethod
+    def _close_backend(self) -> None:
+        """Close the backend and perform cleanup."""
+        pass
+
+    def _submit_tasks(
+        self,
+        keys: list[CacheEngineKey],
+        objs: Optional[list] = None,
+    ) -> list[Any]:
+        """Submit tasks (put or get) based on the benchmark mode.
+
+        Args:
+            keys: List of cache keys.
+            objs: List of memory objects for put operations. If None, submit get tasks.
+
+        Returns:
+            List of pending operations (futures or empty list).
+        """
+        # Default implementation: submit put tasks
+        return self._submit_put_tasks(keys, objs if objs else [])
+
+    def _submit_put_tasks(
+        self,
+        keys: list[CacheEngineKey],
+        objs: list,
+    ) -> list[Any]:
+        """Submit put tasks using callback pattern."""
+        self._completed = 0
+        self._done.clear()
+
+        def on_complete(_key: CacheEngineKey) -> None:
+            with self._lock:
+                self._completed += 1
+                if self._completed >= self.num_ops:
+                    self._done.set()
+
+        def submit_slice(start: int, end: int) -> None:
+            self._backend.batched_submit_put_task(
+                keys[start:end],
+                objs[start:end],
+                on_complete_callback=on_complete,
+            )
+
+        slice_size = max(1, self.num_ops // self.concurrency)
+        slices = [
+            (i, min(i + slice_size, self.num_ops))
+            for i in range(0, self.num_ops, slice_size)
+        ]
+
+        with ThreadPoolExecutor(max_workers=self.concurrency) as ex:
+            for s in slices:
+                ex.submit(submit_slice, s[0], s[1])
+
+        # Return empty list since we use callback pattern
+        return []
+
+    def _wait_for_completion(self, pending_ops: list[Any]) -> None:
+        """Wait using Event pattern."""
+        # Keep a floor for normal runs but scale for large-op runs.
+        # This avoids premature timeout for long single-shot benchmarks.
+        timeout_sec = max(300.0, float(self.num_ops) / 100.0)
+        while not self._done.wait(timeout=1.0):
+            if self._completed >= self.num_ops:
+                break
+            if float(time.perf_counter() - self._start_time) >= timeout_sec:
+                raise TimeoutError(
+                    f"{self.backend_name} benchmark timed out: "
+                    f"completed={self._completed}, expected={self.num_ops}"
+                )
+
+    def _setup_device(self) -> None:
+        return None
+
+    def _cleanup_device(self) -> None:
+        return None
+
+    def _setup_config(self, base_config: LMCacheEngineConfig) -> LMCacheEngineConfig:
+        """Setup backend-specific configuration. Override if needed."""
+        return base_config
+
+    def run(self) -> dict:
+        """Run the benchmark and return results."""
+        # Setup
+        self._loop, self._loop_thread = _start_loop()
+        metadata = _build_metadata(self.chunk_size)
+        logger.info(f"Prepare config for {self.backend_name} ...")
+
+        rust_raw = "rust" in self.backend_name
+
+        required_buffer_gb = (
+            _compute_required_buffer_gb(metadata, self.num_ops, self.chunk_size)
+            if rust_raw
+            else 0.1
+        )
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=self.chunk_size,
+            local_cpu=True,
+            max_local_cpu_size=required_buffer_gb,
+            lmcache_instance_id=f"bench_{self.backend_name}",
+        )
+
+        # prepare the raw disk
+        self._setup_device()
+        config.extra_config = self.extra_config_keys
+        config = self._setup_config(config)
+
+        # Create local CPU backend (common to all backends)
+        if self.use_uring and rust_raw:
+            self._local_cpu = LocalCPUBackend(
+                config=config,
+                metadata=metadata,
+                dst_device="cpu",
+            )
+        else:
+            self._local_cpu = LocalCPUBackend(
+                config=config,
+                metadata=metadata,
+                dst_device="cpu",
+                memory_allocator=AdHocMemoryAllocator(device="cpu"),
+            )
+        logger.info(f"Creating {self.backend_name} ...")
+        # Create the specific backend
+        self._backend = self._create_backend(
+            config, metadata, self._loop, self._local_cpu
+        )
+
+        # Prepare test data
+        self._keys = _make_keys(self.num_ops)
+        shapes = metadata.get_shapes()
+        self._objs = _make_memory_objs(
+            self.num_ops,
+            self.use_odirect,
+            self.alignment,
+            self._keepalive,
+            memory_allocator=self._local_cpu.memory_allocator,
+            shapes=shapes,  # [torch.Size(shape)]
+        )
+
+        # Run benchmark
+        logger.info(f"Start benchmark with {self.backend_name} ...")
+        self._start_time = time.perf_counter()
+        result = self._execute_benchmark()
+        logger.info(f"End benchmark with {self.backend_name} ...")
+        # Cleanup (skip if already handled in _execute_benchmark)
+        if not self._skip_cleanup:
+            _release_memory_objs(self._objs)
+        self._close_backend()
+        logger.info(f"Closed {self.backend_name} ...")
+
+        self._cleanup_device()
+        _stop_loop(self._loop, self._loop_thread)
+        return result
+
+    def _get_slices(self) -> list[tuple[int, int]]:
+        """Get slices for parallel task submission."""
+        slice_size = max(1, self.num_ops // self.concurrency)
+        return [
+            (i, min(i + slice_size, self.num_ops))
+            for i in range(0, self.num_ops, slice_size)
+        ]
+
+    def _execute_write_phase(self) -> float:
+        """Execute the write phase and return elapsed time in seconds.
+
+        This is shared between single-phase (write-only) and two-phase
+        (write+read) benchmarks to avoid code duplication.
+        """
+        start = time.perf_counter()
+        pending_ops = self._submit_tasks(self._keys, self._objs) or []
+
+        if pending_ops or self._uses_futures_pattern():
+            self._wait_for_futures(pending_ops)
+        else:
+            self._wait_for_completion(pending_ops)
+
+        return time.perf_counter() - start
+
+    def _execute_benchmark(self) -> dict:
+        """Execute the benchmark with concurrent writes.
+
+        Supports two modes:
+        - write_bench=True: Single-phase write-only benchmark
+        - write_bench=False: Two-phase write+read benchmark (if supported by backend)
+        """
+        # Check if this is a two-phase benchmark (write + read)
+        if not self.write_bench:
+            return self._execute_two_phase_benchmark()
+
+        # Single-phase benchmark (write-only)
+        elapsed = self._execute_write_phase()
+
+        return {
+            "backend": self.backend_name,
+            "num_ops": self.num_ops,
+            "concurrency": self.concurrency,
+            "write_elapsed_sec": elapsed,
+            "write_ops_per_sec": self.num_ops / elapsed if elapsed > 0 else 0.0,
+            "use_odirect": self.use_odirect,
+        }
+
+    def _uses_futures_pattern(self) -> bool:
+        """Check if this backend uses futures pattern.
+
+        Override in subclass to indicate futures pattern usage.
+        """
+        return False
+
+    def _wait_for_futures(self, futures: list[Any]) -> None:
+        """Wait for all futures to complete."""
+        for fut in futures:
+            fut.result(timeout=120)
+
+    def _get_extra_result_fields(self) -> dict:
+        """Get extra fields to add to the benchmark result.
+
+        Override in subclass to add backend-specific fields.
+        """
+        return {}
+
+    def _execute_two_phase_benchmark(self) -> dict:
+        """Execute two-phase benchmark: write then read.
+
+        This method handles the write phase, release of write objects,
+        read phase, and optional integrity verification.
+        Subclasses should override _verify_integrity() if needed.
+        """
+        # Store original data for integrity verification
+        original_data: dict[CacheEngineKey, torch.Tensor] = {}
+        if self.verify_integrity:
+            for key, obj in zip(self._keys, self._objs, strict=False):
+                assert obj.tensor is not None
+                original_data[key] = obj.tensor.clone()
+
+        # Write phase
+        logger.info("Begin to test write performance")
+        write_elapsed = self._execute_write_phase()
+        logger.info("End of test write performance")
+        # Release write objects
+        _release_memory_objs(self._objs)
+        self._skip_cleanup = True
+
+        # Read phase
+        logger.info("Begin to test read performance")
+        read_start = time.perf_counter()
+        read_results = self._execute_read_phase()
+        read_elapsed = time.perf_counter() - read_start
+        logger.info("End of test read performance")
+
+        # Verify integrity
+        integrity_errors = 0
+        integrity_passed = False
+        if self.verify_integrity:
+            integrity_errors, integrity_passed = self._verify_integrity(
+                read_results, original_data
+            )
+            logger.info("End of verify integrity")
+
+        # Cleanup read objects
+        self._cleanup_read_results(read_results)
+
+        result = {
+            "backend": self.backend_name,
+            "num_ops": self.num_ops,
+            "concurrency": self.concurrency,
+            "write_elapsed_sec": write_elapsed,
+            "write_ops_per_sec": self.num_ops / write_elapsed
+            if write_elapsed > 0
+            else 0.0,
+            "read_elapsed_sec": read_elapsed,
+            "read_ops_per_sec": self.num_ops / read_elapsed
+            if read_elapsed > 0
+            else 0.0,
+            "total_elapsed_sec": write_elapsed + read_elapsed,
+            "use_odirect": self.use_odirect,
+            "verify_integrity": self.verify_integrity,
+            "integrity_errors": integrity_errors,
+            "integrity_passed": integrity_passed,
+        }
+        # Add extra fields from subclass
+        result.update(self._get_extra_result_fields())
+        return result
+
+    def _execute_read_phase(self) -> list[tuple[CacheEngineKey, Optional[MemoryObj]]]:
+        """Execute the read phase and return results.
+
+        Override in subclass to customize read behavior.
+        """
+        slices = self._get_slices()
+        read_results: list[tuple[CacheEngineKey, Optional[MemoryObj]]] = []
+        read_lock = threading.Lock()
+
+        def submit_read_slice(start: int, end: int) -> None:
+            batch_keys = self._keys[start:end]
+            loaded = self._backend.batched_get_blocking(batch_keys)
+            with read_lock:
+                read_results.extend(zip(batch_keys, loaded, strict=False))
+
+        with ThreadPoolExecutor(max_workers=self.concurrency) as ex:
+            for s in slices:
+                ex.submit(submit_read_slice, s[0], s[1])
+
+        return read_results
+
+    def _verify_integrity(
+        self,
+        read_results: list[tuple[CacheEngineKey, Optional[MemoryObj]]],
+        original_data: dict[CacheEngineKey, torch.Tensor],
+    ) -> tuple[int, bool]:
+        """Verify data integrity between original and read data.
+
+        Returns:
+            Tuple of (error_count, is_passed)
+        """
+        errors = 0
+        for key, read_obj in read_results:
+            if read_obj is None:
+                errors += 1
+                continue
+            assert read_obj.tensor is not None
+            if key not in original_data:
+                errors += 1
+                continue
+            if not torch.equal(read_obj.tensor, original_data[key]):
+                errors += 1
+        return errors, errors == 0
+
+    def _cleanup_read_results(
+        self,
+        read_results: list[tuple[CacheEngineKey, Optional[MemoryObj]]],
+    ) -> None:
+        """Cleanup read results by releasing memory objects."""
+        for _, read_obj in read_results:
+            if read_obj is not None:
+                try:
+                    read_obj.ref_count_down()
+                except Exception:
+                    pass
+
+
+# ============================================================================
+# LocalDiskBackend Implementation
+# ============================================================================
+class LocalDiskBackendBenchmark(StorageBackendBenchmark):
+    """Benchmark for LocalDiskBackend."""
+
+    def __init__(
+        self,
+        num_ops: int,
+        concurrency: int,
+        local_disk_dir: str,
+        max_disk_gb: float,
+        use_odirect: bool,
+        alignment: int,
+        write_bench: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+    ):
+        super().__init__(
+            "local_disk",
+            num_ops,
+            concurrency,
+            use_odirect,
+            alignment,
+            write_bench,
+            chunk_size,
+            verify_integrity,
+        )
+        self.local_disk_dir = local_disk_dir
+        self.max_disk_gb = max_disk_gb
+
+    @property
+    def extra_config_keys(self) -> dict:
+        return {"use_odirect": self.use_odirect}
+
+    def _setup_config(self, config: LMCacheEngineConfig) -> LMCacheEngineConfig:
+        config.local_disk = self.local_disk_dir
+        config.max_local_disk_size = self.max_disk_gb
+        return config
+
+    def _create_backend(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ) -> LocalDiskBackend:
+        return LocalDiskBackend(
+            config=config,
+            loop=loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            metadata=metadata,
+        )
+
+    def _close_backend(self) -> None:
+        self._backend.close()
+
+
+# ============================================================================
+# RustRawBlockBackend Implementation
+# ============================================================================
+class RustRawBlockBackendBenchmark(StorageBackendBenchmark):
+    """Benchmark for RustRawBlockBackend.
+
+    Supports both write and read benchmarks:
+    - write_bench=True: Perform write-only benchmark
+    - write_bench=False: Perform write+read benchmark with optional
+    - integrity verification
+    """
+
+    def __init__(
+        self,
+        num_ops: int,
+        concurrency: int,
+        raw_device: str,
+        raw_device_size_gb: float,
+        use_odirect: bool,
+        alignment: int,
+        cleanup_raw_device: bool,
+        write_bench: bool,
+        use_uring: bool,
+        use_uring_cmd: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+        max_data_transfer_size: int = 0,
+    ):
+        super().__init__(
+            "rust_raw_block",
+            num_ops,
+            concurrency,
+            use_odirect,
+            alignment,
+            write_bench,
+            chunk_size,
+            verify_integrity,
+            use_uring,
+        )
+        self.raw_device = raw_device
+        self.raw_device_size_gb = raw_device_size_gb
+        self.cleanup_raw_device = cleanup_raw_device
+        self._temp_dir: Optional[str] = None
+        self._manifest_path: Optional[str] = None
+        self.use_uring = use_uring
+        self.use_uring_cmd = use_uring_cmd
+        self.max_data_transfer_size = max_data_transfer_size
+        # Create manifest path
+        self._manifest_path = os.path.join(
+            tempfile.gettempdir(),
+            f"lmcache_rust_raw_block_bench_{os.getpid()}_{time.time_ns()}.manifest.json",
+        )
+
+    @property
+    def extra_config_keys(self) -> dict:
+        return {
+            "rust_raw_block.device_path": self.raw_device,
+            "rust_raw_block.block_align": self.alignment,
+            "rust_raw_block.header_bytes": self.alignment,
+            "rust_raw_block.use_odirect": self.use_odirect,
+            "rust_raw_block.manifest_path": self._manifest_path,
+            "rust_raw_block.manifest_write_interval": 0,
+            "rust_raw_block.use_uring": self.use_uring,
+            "rust_raw_block.use_uring_cmd": self.use_uring_cmd,
+            "rust_raw_block.max_data_transfer_size": self.max_data_transfer_size,
+        }
+
+    def _setup_device(self) -> None:
+        """Setup raw block device or temp file."""
+        is_block_device = False
+        is_char_device = False
+        self._temp_dir = None
+        prefix = "write" if self.write_bench else "read"
+        prefix = prefix + "raw_block_bench_"
+        if self.raw_device:
+            try:
+                st_mode = os.stat(self.raw_device).st_mode
+                is_block_device = stat.S_ISBLK(st_mode)
+                is_char_device = stat.S_ISCHR(st_mode)
+            except FileNotFoundError:
+                is_block_device = False
+                is_char_device = False
+
+        # Create temp file if no device specified
+        if not self.raw_device:
+            self._temp_dir = tempfile.mkdtemp(prefix)
+            self.raw_device = os.path.join(self._temp_dir, "raw_block.bin")
+
+        # Truncate if not a real block device or character device
+        if self.raw_device and not is_block_device and not is_char_device:
+            with open(self.raw_device, "wb") as f:
+                f.truncate(int(self.raw_device_size_gb * 1024**3))
+
+    def _create_backend(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ) -> RustRawBlockBackend:
+        return RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop,
+            dst_device="cpu",
+        )
+
+    def _uses_futures_pattern(self) -> bool:
+        """RustRawBlockBackend uses futures pattern."""
+        return True
+
+    def _submit_put_tasks(
+        self,
+        keys: list[CacheEngineKey],
+        objs: list,
+    ) -> list[Any]:
+        """Submit put tasks using futures pattern (for RustRawBlockBackend)."""
+        futures: list[Future] = []
+        fut_lock = threading.Lock()
+        slices = self._get_slices()
+
+        def submit_slice(start: int, end: int) -> None:
+            result = self._backend.batched_submit_put_task(
+                keys[start:end], objs[start:end]
+            )
+            if result is not None:
+                with fut_lock:
+                    futures.extend(result)
+
+        with ThreadPoolExecutor(max_workers=self.concurrency) as ex:
+            for s in slices:
+                ex.submit(submit_slice, s[0], s[1])
+
+        return futures
+
+    def _close_backend(self) -> None:
+        if self._manifest_path:
+            try:
+                os.remove(self._manifest_path)
+            except Exception:
+                pass
+        if self._backend:
+            self._backend.close()
+
+    def _get_extra_result_fields(self) -> dict:
+        """Get extra fields for RustRawBlockBackend benchmark results."""
+        return {
+            "use_uring": self.use_uring,
+            "use_uring_cmd": self.use_uring_cmd,
+        }
+
+    def _cleanup_device(self) -> None:
+        """Cleanup temp files."""
+        if self.cleanup_raw_device or self._temp_dir:
+            try:
+                os.remove(self.raw_device)
+            except Exception:
+                pass
+            if self._temp_dir:
+                try:
+                    os.rmdir(self._temp_dir)
+                except Exception:
+                    pass
+
+
+# ============================================================================
+# RemoteBackendBenchmark Implementation
+# ============================================================================
+class RemoteBackendBenchmark(StorageBackendBenchmark):
+    """Benchmark for RemoteBackend (e.g., S3, Redis)."""
+
+    def __init__(
+        self,
+        name: str,
+        num_ops: int,
+        concurrency: int,
+        remote_url: str,
+        use_odirect: bool,
+        alignment: int,
+        write_bench: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+    ):
+        super().__init__(
+            name,
+            num_ops,
+            concurrency,
+            use_odirect,
+            alignment,
+            write_bench,
+            chunk_size,
+            verify_integrity,
+        )
+        self.remote_url = remote_url
+
+    def _setup_config(self, config: LMCacheEngineConfig) -> LMCacheEngineConfig:
+        config.remote_url = self.remote_url
+        return config
+
+    def _create_backend(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ) -> RemoteBackend:
+        return RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+
+    def _close_backend(self):
+        if self._backend:
+            self._backend.close()
+
+
+# ============================================================================
+# Hf3fsBackendBenchmark Implementation
+# ============================================================================
+class Hf3fsBackendBenchmark(RemoteBackendBenchmark):
+    def __init__(
+        self,
+        num_ops: int,
+        concurrency: int,
+        remote_url: str,
+        use_odirect: bool,
+        alignment: int,
+        write_bench: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+    ):
+        super().__init__(
+            "hf3fs_backend",
+            num_ops,
+            concurrency,
+            remote_url,
+            use_odirect,
+            alignment,
+            write_bench,
+            chunk_size,
+            verify_integrity,
+        )
+
+    @property
+    def extra_config_keys(self) -> dict:
+        return {
+            "hf3fs_mount_point": "/3fs/stage",
+            "hf3fs_iov_size": 209715200,
+            "hf3fs_ior_entries": 256,
+            "hf3fs_io_depth": 0,
+            "hf3fs_numa_id": -1,
+            "hf3fs_io_thread_num": 8,
+        }
+
+
+# ============================================================================
+# FsBackendBenchmark Implementation
+# ============================================================================
+class FsBackendBenchmark(RemoteBackendBenchmark):
+    def __init__(
+        self,
+        num_ops: int,
+        concurrency: int,
+        remote_url: str,
+        use_odirect: bool,
+        alignment: int,
+        write_bench: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+    ):
+        super().__init__(
+            "fs_backend",
+            num_ops,
+            concurrency,
+            remote_url,
+            use_odirect,
+            alignment,
+            write_bench,
+            chunk_size,
+            verify_integrity,
+        )
+
+    @property
+    def extra_config_keys(self) -> dict:
+        return {
+            "save_chunk_meta": False,
+            "fs_connector_read_ahead_size": 0,
+            "fs_connector_use_odirect": False,
+            # "fs_connector_relative_tmp_dir": "tmp",
+        }
+
+
+# ============================================================================
+# BigtableBackendBenchmark Implementation
+# ============================================================================
+class BigtableBackendBenchmark(RemoteBackendBenchmark):
+    def __init__(
+        self,
+        num_ops: int,
+        concurrency: int,
+        remote_url: str,
+        use_odirect: bool,
+        alignment: int,
+        write_bench: bool,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        verify_integrity: bool = False,
+    ):
+        super().__init__(
+            "bigtable",
+            num_ops,
+            concurrency,
+            remote_url,
+            use_odirect,
+            alignment,
+            write_bench,
+            chunk_size,
+            verify_integrity,
+        )
+
+    @property
+    def extra_config_keys(self) -> dict:
+        return {}
+
+
+# Main Entry Point
+# ============================================================================
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Benchmark storage backends under high write/read concurrency."
+    )
+    parser.add_argument("--num-ops", type=int, default=256, help="Total put ops")
+    parser.add_argument(
+        "--concurrency", type=int, default=4, help="Number of submit threads"
+    )
+    parser.add_argument(
+        "--backend",
+        choices=[
+            "local_disk",
+            "rust_raw_block",
+            "both",
+            "hf3fs_backend",
+            "fs_backend",
+            "bigtable",
+        ],
+        default="both",
+        help=(
+            "Backend to benchmark."
+            "For both, it will benchmark local_disk and rust_raw_block"
+        ),
+    )
+    parser.add_argument(
+        "--write_bench",
+        type=str,
+        default="True",
+        help="Perform write benchmark (default: True). False for read benchmark.",
+    )
+    parser.add_argument(
+        "--use-uring",
+        action="store_true",
+        help="Enable io_uring for raw block backend",
+    )
+    parser.add_argument(
+        "--use-uring-cmd",
+        action="store_true",
+        help=(
+            "Enable io_uring_cmd for raw block backend. "
+            "This automatically enables --use-uring. "
+            "Must use nvme character device node (/dev/ngXnY)"
+        ),
+    )
+    parser.add_argument(
+        "--max-data-transfer-size",
+        type=int,
+        default=0,
+        help=(
+            "Maximum data transfer size for use_uring_cmd. "
+            " > 0: Split based on the specified limit. "
+            " <= 0: Split based on device reported max hardware sector size"
+        ),
+    )
+    parser.add_argument(
+        "--verify-integrity",
+        action="store_true",
+        help="Verify data integrity after reads (write_bench is False)",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=DEFAULT_CHUNK_SIZE,
+        help=f"Chunk size for the backend (default: {DEFAULT_CHUNK_SIZE})",
+    )
+    parser.add_argument(
+        "--local-disk-dir",
+        type=str,
+        default="/tmp/lmcache_local_disk_bench",
+    )
+
+    parser.add_argument("--max-local-disk-gb", type=float, default=2.0)
+    parser.add_argument(
+        "--local-disk-odirect",
+        action="store_true",
+        help="Enable O_DIRECT for local disk backend",
+    )
+    parser.add_argument(
+        "--raw-device",
+        type=str,
+        default="",
+        help="Raw block device path (if empty, uses a temp file)",
+    )
+    parser.add_argument("--raw-device-size-gb", type=float, default=1.0)
+    parser.add_argument(
+        "--raw-odirect",
+        action="store_true",
+        help="Enable O_DIRECT for raw block backend",
+    )
+    parser.add_argument("--alignment", type=int, default=4096)
+    parser.add_argument(
+        "--remote-url",
+        type=str,
+        default="hf3fs:///3fs/stage/hello,/3fs/stage/world",
+        help="The url for fs_backend or hf3fs_backend.",
+    )
+
+    parser.add_argument(
+        "--output-json",
+        type=str,
+        default="",
+        help="Output JSON file path or directory",
+    )
+
+    args = parser.parse_args()
+
+    # use_uring_cmd requires io_uring as io_engine
+    if args.use_uring_cmd:
+        args.use_uring = True
+
+    # write_bench defaults to True (write benchmark), set to False for read benchmark
+    write_bench = args.write_bench.lower() in ("true", "1", "yes", "y", "")
+
+    results = []
+    # Run LocalDiskBackend benchmark
+    if args.backend in ("local_disk", "both"):
+        localdisk_bench = LocalDiskBackendBenchmark(
+            num_ops=args.num_ops,
+            concurrency=args.concurrency,
+            local_disk_dir=args.local_disk_dir,
+            max_disk_gb=args.max_local_disk_gb,
+            use_odirect=args.local_disk_odirect,
+            alignment=args.alignment,
+            write_bench=write_bench,
+            chunk_size=args.chunk_size,
+            verify_integrity=args.verify_integrity,
+        )
+        result = localdisk_bench.run()
+        result["local_disk_dir"] = args.local_disk_dir
+        results.append(result)
+
+    # Run RustRawBlockBackend benchmark
+    if args.backend in ("rust_raw_block", "both"):
+        raw_device = args.raw_device
+        cleanup_raw_device = False
+        if not raw_device:
+            # Use same filesystem as local disk for fair comparison
+            raw_device = os.path.join(args.local_disk_dir, "raw_block.bin")
+            cleanup_raw_device = True
+
+        rustraw_bench = RustRawBlockBackendBenchmark(
+            num_ops=args.num_ops,
+            concurrency=args.concurrency,
+            raw_device=raw_device,
+            raw_device_size_gb=args.raw_device_size_gb,
+            use_odirect=args.raw_odirect,
+            alignment=args.alignment,
+            cleanup_raw_device=cleanup_raw_device,
+            write_bench=write_bench,
+            use_uring=args.use_uring,
+            use_uring_cmd=args.use_uring_cmd,
+            chunk_size=args.chunk_size,
+            verify_integrity=args.verify_integrity,
+            max_data_transfer_size=args.max_data_transfer_size,
+        )
+        result = rustraw_bench.run()
+        result["raw_device"] = raw_device
+        results.append(result)
+
+    # Run Hf3fsBackend benchmark
+    if args.backend in ("hf3fs_backend",):
+        hf3fs_bench = Hf3fsBackendBenchmark(
+            num_ops=args.num_ops,
+            concurrency=args.concurrency,
+            remote_url=args.remote_url,
+            use_odirect=False,
+            alignment=args.alignment,
+            write_bench=write_bench,
+            chunk_size=args.chunk_size,
+            verify_integrity=args.verify_integrity,
+        )
+        result = hf3fs_bench.run()
+        result["hf3fs_dir"] = args.remote_url
+        results.append(result)
+
+    # Run FsBackend benchmark
+    if args.backend in ("fs_backend",):
+        fs_bench = FsBackendBenchmark(
+            num_ops=args.num_ops,
+            concurrency=args.concurrency,
+            remote_url=args.remote_url,
+            use_odirect=False,
+            alignment=args.alignment,
+            write_bench=write_bench,
+            chunk_size=args.chunk_size,
+            verify_integrity=args.verify_integrity,
+        )
+        result = fs_bench.run()
+        result["fs_dir"] = args.remote_url
+        results.append(result)
+
+    # Run BigtableBackend benchmark
+    if args.backend in ("bigtable",):
+        bigtable_bench = BigtableBackendBenchmark(
+            num_ops=args.num_ops,
+            concurrency=args.concurrency,
+            remote_url=args.remote_url,
+            use_odirect=False,
+            alignment=args.alignment,
+            write_bench=write_bench,
+            chunk_size=args.chunk_size,
+            verify_integrity=args.verify_integrity,
+        )
+        result = bigtable_bench.run()
+        result["bigtable_table"] = args.remote_url
+        results.append(result)
+
+    # Print results
+    for result in results:
+        print(
+            f"{result['backend']}: ops={result['num_ops']} "
+            f"concurrency={result['concurrency']} "
+            f"write_elapsed={result['write_elapsed_sec']:.3f}s "
+            f"write_ops/sec={result['write_ops_per_sec']:.2f}"
+        )
+        if not write_bench:
+            print(
+                f"read_elapsed={result['read_elapsed_sec']:.3f}s "
+                f"read_ops/sec={result['read_ops_per_sec']:.2f} "
+                f"total_elapsed={result['total_elapsed_sec']:.3f}s"
+            )
+            if args.verify_integrity:
+                status = "PASSED" if result["integrity_passed"] else "FAILED"
+                print(
+                    f"  Integrity check: {status} (errors={result['integrity_errors']})"
+                )
+
+    # Write JSON output
+    if args.output_json:
+        output_path = args.output_json
+        if output_path.endswith(os.sep) or os.path.isdir(output_path):
+            ts = time.strftime("%Y%m%d_%H%M%S")
+            output_path = os.path.join(output_path, f"storage_backend_io_{ts}.json")
+        with open(output_path, "w") as f:
+            json.dump(results, f, indent=2)
+        logger.info(f"Wrote results to {output_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/ttft-estimator/llama-h100-example.png b/benchmarks/ttft-estimator/llama-h100-example.png
new file mode 100644
index 0000000..066d3f2
Binary files /dev/null and b/benchmarks/ttft-estimator/llama-h100-example.png differ
diff --git a/benchmarks/ttft-estimator/ttft-estimator.py b/benchmarks/ttft-estimator/ttft-estimator.py
new file mode 100644
index 0000000..dbc1224
--- /dev/null
+++ b/benchmarks/ttft-estimator/ttft-estimator.py
@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Startup: 
+- serving engine agnostic benchmark but example is with vllm, 
+  where we can increase the max model length more by restricting
+  the concurrency to 1 since this estimator will only send one request at a time
+- load-format dummy to make weight loading faster and we don't care about the
+  outputs only the prefill speed
+vllm serve meta-llama/Llama-3.1-8B-Instruct \
+    --max-model-len 130000 --port 8000 \
+    --load-format dummy \
+    --max-num-seqs 1
+
+Example Usage: 
+python ttft-estimator.py \
+    --model meta-llama/Llama-3.1-8B-Instruct \
+    --host localhost --port 8000\
+    --context-lengths 2000,5000,10000,20000,30000,50000,75000,100000,128000
+"""
+
+# Standard
+import argparse
+import time
+
+# Third Party
+from openai import OpenAI
+from transformers import AutoTokenizer
+import matplotlib.pyplot as plt
+import numpy as np
+
+args = None
+tokenizer = None
+# the number of tokens in 10,000 "hi"s
+hi_multiplier = None
+context_length_ttfts = []
+
+client = OpenAI(api_key="dummy-key", base_url="http://localhost:8000/v1")
+
+
+def query_and_measure_ttft(prompt):
+    start = time.perf_counter()
+    ttft = None
+
+    chat_completion = client.chat.completions.create(
+        messages=[{"role": "user", "content": prompt}],
+        model=args.model,
+        temperature=0.7,
+        stream=True,
+        max_completion_tokens=5,
+    )
+
+    for chunk in chat_completion:
+        chunk_message = chunk.choices[0].delta.content
+        if chunk_message is not None:
+            if ttft is None:
+                ttft = time.perf_counter()
+            print(chunk_message, end="", flush=True)
+
+    print("\n")
+    return ttft - start
+
+
+def main():
+    # first send a dummy request
+    # e.g. on vLLM the very first request sometimes has higher
+    # TTFT due to kernel JIT compilation
+    warm_up_prompt = "bye" * 50
+    query_and_measure_ttft(warm_up_prompt)
+    print("Warm up complete")
+
+    for i, context_length in enumerate(
+        map(int, (s.strip() for s in args.context_lengths.split(",")))
+    ):
+        number_of_his = context_length * hi_multiplier // 10_000
+        # break the prefix with the enumeration
+        prompt = f"{i}" + "hi" * number_of_his
+        ttft = query_and_measure_ttft(prompt)
+        print(f"Context length: {context_length}, TTFT: {ttft}")
+        context_length_ttfts.append((context_length, ttft))
+    draw_quadratic_interpolation()
+
+
+def set_hi_multiplier():
+    global hi_multiplier
+    prompt = "hi" * 10000
+    hi_multiplier = len(tokenizer.encode(prompt))
+    print(f'number tokens in 10,000 "hi\'s": {hi_multiplier}')
+
+
+def parse_args():
+    global tokenizer
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", type=str, required=True)
+    parser.add_argument("--host", type=str, required=False, default="localhost")
+    parser.add_argument("--port", type=str, required=False, default="8000")
+    parser.add_argument("--context-lengths", type=str, required=False, default="1024")
+    return parser.parse_args()
+
+
+def draw_quadratic_interpolation():
+    # Note: this interpolation is completely speculative and should NOT be trusted
+    # This is to visualize under the assumption that prefill is quadratic complexity
+    xs = [context_length for context_length, _ in context_length_ttfts]
+    ys = [ttft for _, ttft in context_length_ttfts]
+    # degree 2
+    coeffs = np.polyfit(xs, ys, 2)
+    print(
+        f"Interpolation is: Prefill Time = {coeffs[0]} * Context Length^2 +"
+        f"{coeffs[1]} * Context Length + {coeffs[2]}"
+    )
+    quadratic = np.poly1d(coeffs)
+
+    x_smooth = np.linspace(min(xs), max(xs), 200)
+    y_smooth = quadratic(x_smooth)
+
+    plt.scatter(xs, ys, color="red", label="Data Points")
+    plt.plot(x_smooth, y_smooth, color="pink", label="Quadratic Interpolation")
+    plt.legend()
+    plt.xlabel("Context Length")
+    plt.ylabel("TTFT (s)")
+    plt.title("Quadratic Prefill Estimation")
+    plt.savefig("prefill-estimation.png")
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    tokenizer = AutoTokenizer.from_pretrained(args.model)
+    set_hi_multiplier()
+    main()
diff --git a/csrc/ac_dec.cu b/csrc/ac_dec.cu
new file mode 100644
index 0000000..8c66019
--- /dev/null
+++ b/csrc/ac_dec.cu
@@ -0,0 +1,538 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <iostream>
+#include <cstdio>
+#include <cuda_runtime.h>
+#include "cachegen_kernels.cuh"
+
+#define MAX_LP 64
+#define MAX_THREAD_PER_BLOCK 128
+#define MAX_SHARED_MEMORY_PER_THREAD (0xc000 / MAX_THREAD_PER_BLOCK)
+#if MAX_SHARED_MEMORY_PER_THREAD - MAX_LP * 2 >= 256
+  #define MAX_TOKENS_PER_THREAD 256
+  #define OUTPUT_BUFFER_LENGTH_PER_THREAD 256
+#else
+  #define OUTPUT_BUFFER_LENGTH_PER_THREAD \
+    (MAX_SHARED_MEMORY_PER_THREAD - MAX_LP * 2)
+  #define MAX_TOKENS_PER_THREAD (OUTPUT_BUFFER_LENGTH_PER_THREAD)
+#endif
+#define PRECISION 16
+
+extern int get_block_size(int);
+
+template <typename T>
+__inline__ __device__ T big_to_small(T value) {
+  return value;
+}
+
+template <>
+__inline__ __device__ uint32_t big_to_small<uint32_t>(uint32_t value) {
+  return ((value & 0xFF000000U) >> 24) | ((value & 0x00FF0000U) >> 8) |
+         ((value & 0x0000FF00U) << 8) | ((value & 0x000000FFU) << 24);
+}
+
+template <>
+__inline__ __device__ uint8_t big_to_small<uint8_t>(uint8_t value) {
+  return value;
+}
+
+template <int BUFFER_BITS, typename BUFFER_TYPE>
+__inline__ __device__ void read_next_bit(uint32_t& value,
+                                         BUFFER_TYPE& byte_buffer,
+                                         int& bit_idx) {
+  value <<= 1;
+  value |= (byte_buffer >> (BUFFER_BITS - bit_idx)) & 1;
+  bit_idx += 1;
+}
+
+template <int BUFFER_BITS, typename BUFFER_TYPE>
+__inline__ __device__ void check_and_update_byte_buffer(
+    BUFFER_TYPE& byte_buffer, int& bit_idx, int& byte_buffer_offset,
+    uint8_t* bytestream) {
+  if (bit_idx == BUFFER_BITS + 1) {
+    bit_idx = 1;
+    byte_buffer_offset++;
+    byte_buffer = big_to_small<BUFFER_TYPE>(
+        ((BUFFER_TYPE*)bytestream)[byte_buffer_offset]);
+  }
+}
+
+template <int BLOCK_SIZE>
+__inline__ __device__ uint16_t binsearch(const uint16_t* cdf_shared,
+                                         uint16_t target, uint8_t max_sym,
+                                         const int tid) {
+  uint16_t left = 0;
+  uint16_t right = max_sym + 1;  // len(cdf) == max_sym + 2
+
+  while (left + 1 < right) {  // ?
+    const auto m = static_cast<uint16_t>((left + right) / 2);
+    const auto offset = m * BLOCK_SIZE + tid;
+    const auto v = cdf_shared[offset];
+    if (v < target) {
+      left = m;
+    } else if (v > target) {
+      right = m;
+    } else {
+      return m;
+    }
+  }
+  return left;
+}
+
+// BLOCK_SIZE SHOULD ALWAYS BE THE SAME AS blockDim.x
+template <int BLOCK_SIZE, typename CDF_ACC_T, typename BS_ACC_T,
+          typename LEN_ACC_T, typename OUT_ACC_T>
+__global__ void decode_with_accessor_kernel(CDF_ACC_T cdf, BS_ACC_T bytestreams,
+                                            LEN_ACC_T lengths, OUT_ACC_T output,
+                                            int32_t lp, int32_t ntokens) {
+  // The shared memory will be split to 3 parts:
+  // 1. The CDF tensor, with shape [MAX_LP, BLOCK_SIZE)] (only used [LP,
+  // BLOCK_SIZE] part)
+  // 2. The bytestream buffer, with shape [BLOCK_SIZE,
+  // OUTPUT_BUFFER_LENGTH_PER_THREAD] uint8s
+  // 3. The lengths buffer, with shape [BLOCK_SIZE] int32s
+  __shared__ __align__(4) uint16_t cdf_shared[MAX_LP][BLOCK_SIZE];
+  __shared__ __align__(4)
+      uint8_t bytestreams_shared[BLOCK_SIZE][OUTPUT_BUFFER_LENGTH_PER_THREAD];
+  int32_t* lengths_shared = (int32_t*)&cdf_shared[0][0];
+
+  const int layer_id = blockIdx.x;
+  const int global_channel_offset = blockIdx.y * BLOCK_SIZE;
+  const int local_channel_id = threadIdx.x;
+  const int global_channel_id = global_channel_offset + local_channel_id;
+  const int max_symbol = lp - 2;
+
+  // copy lengths[layer_id,
+  // global_channel_offset:global_channel_offset+BLOCK_SIZE] to shared memory
+  for (int i = threadIdx.x; i < BLOCK_SIZE; i += BLOCK_SIZE) {
+    lengths_shared[i] = lengths[layer_id][global_channel_offset + i];
+  }
+
+  __syncthreads();
+
+  // copy bytestreams[layer_id,
+  // global_channel_offset:global_channel_offset+BLOCK_SIZE, :] to shared
+  // memory, do this channel by channel
+  for (int i = 0; i < BLOCK_SIZE; i++) {
+    const int channel_id = global_channel_offset + i;
+    const int length = lengths_shared[i];  // shared memory broadcast
+    // TODO: optimized this by a packed-32bits read instead of 8bits read
+    for (int j = threadIdx.x; j < OUTPUT_BUFFER_LENGTH_PER_THREAD;
+         j += BLOCK_SIZE) {
+      const uint8_t value =
+          j < length ? bytestreams[layer_id][channel_id][j] : 0;
+      bytestreams_shared[i][j] = value;
+    }
+  }
+  __syncthreads();
+
+  // copy CDF[layer_id, global_channel_offset:global_channel_offset+BLOCK_SIZE,
+  // :] to shared memory
+  const int cdf_size = lp * BLOCK_SIZE;
+  for (int i = threadIdx.x; i < cdf_size; i += BLOCK_SIZE) {
+    const int cid = i / lp;
+    const int lid = i % lp;
+    cdf_shared[lid][cid] = cdf[layer_id][global_channel_offset + cid][lid];
+  }
+
+  __syncthreads();
+
+  // decode the bytestreams
+  uint32_t low = 0;
+  uint32_t high = 0xFFFFFFFFU;
+  uint32_t value = 0;
+  const uint32_t c_count = 0x10000U;
+  const int precision = 16;
+
+  uint8_t byte_buffer = 0;
+  int bit_idx = 1;  // next bit to read: (byte_buffer >> (8 - bit_idx)) & 1
+  int byte_buffer_offset =
+      sizeof(value) / sizeof(byte_buffer);  // where to read the next byte
+
+  // Get the initial value and byte buffer
+  value = big_to_small<uint32_t>(
+      ((uint32_t*)bytestreams_shared[local_channel_id])[0]);
+  // byte_buffer = ((uint32_t
+  // *)bytestreams_shared[local_channel_id])[byte_buffer_offset];
+  byte_buffer = bytestreams_shared[local_channel_id][byte_buffer_offset];
+
+  for (int i = 0; i < ntokens; ++i) {
+    const uint64_t span =
+        static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+    // always < 0x10000 ???
+    const uint16_t count =
+        ((static_cast<uint64_t>(value) - static_cast<uint64_t>(low) + 1) *
+             c_count -
+         1) /
+        span;
+
+    // TODO: implement the binsearch here!
+    auto sym_i = binsearch<BLOCK_SIZE>(&cdf_shared[0][0], count, max_symbol,
+                                       local_channel_id);
+
+    output[layer_id][i][global_channel_id] = sym_i;
+
+    if (i == ntokens - 1) {
+      break;
+    }
+
+    const uint32_t c_low = cdf_shared[sym_i][local_channel_id];
+    const uint32_t c_high = sym_i == max_symbol
+                                ? 0x10000U
+                                : cdf_shared[sym_i + 1][local_channel_id];
+
+    high = (low - 1) + ((span * static_cast<uint64_t>(c_high)) >> precision);
+    low = (low) + ((span * static_cast<uint64_t>(c_low)) >> precision);
+
+    while (true) {
+      if (low >= 0x80000000U || high < 0x80000000U) {
+        low <<= 1;
+        high <<= 1;
+        high |= 1;
+        read_next_bit<8>(value, byte_buffer, bit_idx);
+        check_and_update_byte_buffer<8, uint8_t>(
+            byte_buffer, bit_idx, byte_buffer_offset,
+            bytestreams_shared[local_channel_id]);
+      } else if (low >= 0x40000000U && high < 0xC0000000U) {
+        low <<= 1;
+        low &= 0x7FFFFFFFU;  // make MSB 0
+        high <<= 1;
+        high |= 0x80000001U;  // add 1 at the end, retain MSB = 1
+        value -= 0x40000000U;
+        read_next_bit<8>(value, byte_buffer, bit_idx);
+        check_and_update_byte_buffer<8, uint8_t>(
+            byte_buffer, bit_idx, byte_buffer_offset,
+            bytestreams_shared[local_channel_id]);
+      } else {
+        break;
+      }
+    }
+  }
+}
+
+// BLOCK_SIZE SHOULD ALWAYS BE THE SAME AS blockDim.x
+template <int BLOCK_SIZE, typename CDF_ACC_T, typename BS_ACC_T,
+          typename LEN_ACC_T, typename OUT_ACC_T>
+__global__ void decode_prefix_with_accessor_kernel(CDF_ACC_T cdf,
+                                                   BS_ACC_T bytestreams,
+                                                   LEN_ACC_T lengths_prefix,
+                                                   OUT_ACC_T output, int32_t lp,
+                                                   int32_t ntokens) {
+  // The shared memory will be split to 3 parts:
+  // 1. The CDF tensor, with shape [MAX_LP, BLOCK_SIZE)] (only used [LP,
+  // BLOCK_SIZE] part)
+  // 2. The bytestream buffer, with shape [BLOCK_SIZE,
+  // OUTPUT_BUFFER_LENGTH_PER_THREAD] uint8s
+  // 3. The lengths buffer, with shape [BLOCK_SIZE] int32s
+  __shared__ __align__(4) uint16_t cdf_shared[MAX_LP][BLOCK_SIZE];
+  __shared__ __align__(4)
+      uint8_t bytestreams_shared[BLOCK_SIZE][OUTPUT_BUFFER_LENGTH_PER_THREAD];
+  int32_t* sum_lengths_shared = (int32_t*)&cdf_shared[0][0];
+
+  const int layer_id = blockIdx.x;
+  const int global_channel_offset = blockIdx.y * BLOCK_SIZE;
+  const int local_channel_id = threadIdx.x;
+  const int global_channel_id = global_channel_offset + local_channel_id;
+  const int max_symbol = lp - 2;
+  const int nchannels = gridDim.y * BLOCK_SIZE;
+
+  // copy lengths[layer_id,
+  // global_channel_offset:global_channel_offset+BLOCK_SIZE] to shared memory
+  for (int i = threadIdx.x; i < BLOCK_SIZE + 1; i += BLOCK_SIZE) {
+    int gid = layer_id * nchannels + global_channel_offset + i - 1;
+    sum_lengths_shared[i] =
+        gid >= 0 ? lengths_prefix[gid / nchannels][gid % nchannels] : 0;
+  }
+
+  __syncthreads();
+
+  // copy bytestreams[layer_id,
+  // global_channel_offset:global_channel_offset+BLOCK_SIZE, :] to shared
+  // memory, do this channel by channel
+  for (int i = 0; i < BLOCK_SIZE; i++) {
+    [[maybe_unused]] const int channel_id = global_channel_offset + i;
+    const int start_offset = sum_lengths_shared[i];
+    const int end_offset = sum_lengths_shared[i + 1];
+    const int length = end_offset - start_offset;
+    // TODO: optimized this by a packed-32bits read instead of 8bits read
+    for (int j = threadIdx.x; j < OUTPUT_BUFFER_LENGTH_PER_THREAD;
+         j += BLOCK_SIZE) {
+      const uint8_t value = j < length ? bytestreams[start_offset + j] : 0;
+      bytestreams_shared[i][j] = value;
+    }
+  }
+  __syncthreads();
+
+  // copy CDF[layer_id, global_channel_offset:global_channel_offset+BLOCK_SIZE,
+  // :] to shared memory
+  const int cdf_size = lp * BLOCK_SIZE;
+  for (int i = threadIdx.x; i < cdf_size; i += BLOCK_SIZE) {
+    const int cid = i / lp;
+    const int lid = i % lp;
+    cdf_shared[lid][cid] = cdf[layer_id][global_channel_offset + cid][lid];
+  }
+
+  __syncthreads();
+
+  // decode the bytestreams
+  uint32_t low = 0;
+  uint32_t high = 0xFFFFFFFFU;
+  uint32_t value = 0;
+  const uint32_t c_count = 0x10000U;
+  const int precision = 16;
+
+  uint8_t byte_buffer = 0;
+  int bit_idx = 1;  // next bit to read: (byte_buffer >> (8 - bit_idx)) & 1
+  int byte_buffer_offset =
+      sizeof(value) / sizeof(byte_buffer);  // where to read the next byte
+
+  // Get the initial value and byte buffer
+  value = big_to_small<uint32_t>(
+      ((uint32_t*)bytestreams_shared[local_channel_id])[0]);
+  // byte_buffer = ((uint32_t
+  // *)bytestreams_shared[local_channel_id])[byte_buffer_offset];
+  byte_buffer = bytestreams_shared[local_channel_id][byte_buffer_offset];
+
+  for (int i = 0; i < ntokens; ++i) {
+    const uint64_t span =
+        static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+    // always < 0x10000 ???
+    const uint16_t count =
+        ((static_cast<uint64_t>(value) - static_cast<uint64_t>(low) + 1) *
+             c_count -
+         1) /
+        span;
+
+    // TODO: implement the binsearch here!
+    auto sym_i = binsearch<BLOCK_SIZE>(&cdf_shared[0][0], count, max_symbol,
+                                       local_channel_id);
+
+    output[layer_id][i][global_channel_id] = sym_i;
+
+    if (i == ntokens - 1) {
+      break;
+    }
+
+    const uint32_t c_low = cdf_shared[sym_i][local_channel_id];
+    const uint32_t c_high = sym_i == max_symbol
+                                ? 0x10000U
+                                : cdf_shared[sym_i + 1][local_channel_id];
+
+    high = (low - 1) + ((span * static_cast<uint64_t>(c_high)) >> precision);
+    low = (low) + ((span * static_cast<uint64_t>(c_low)) >> precision);
+
+    while (true) {
+      if (low >= 0x80000000U || high < 0x80000000U) {
+        low <<= 1;
+        high <<= 1;
+        high |= 1;
+        read_next_bit<8>(value, byte_buffer, bit_idx);
+        check_and_update_byte_buffer<8, uint8_t>(
+            byte_buffer, bit_idx, byte_buffer_offset,
+            bytestreams_shared[local_channel_id]);
+      } else if (low >= 0x40000000U && high < 0xC0000000U) {
+        low <<= 1;
+        low &= 0x7FFFFFFFU;  // make MSB 0
+        high <<= 1;
+        high |= 0x80000001U;  // add 1 at the end, retain MSB = 1
+        value -= 0x40000000U;
+        read_next_bit<8>(value, byte_buffer, bit_idx);
+        check_and_update_byte_buffer<8, uint8_t>(
+            byte_buffer, bit_idx, byte_buffer_offset,
+            bytestreams_shared[local_channel_id]);
+      } else {
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * @brief CUDA kernel to decode a compressed bytestream using the given CDF.
+ *
+ * @param cdf the int16 CDF tensor, with shape [nlayers, nchannels, LP], should
+ * be on GPU
+ * @param bytestreams The uint8 bytestreams tensor, with shape [nlayers,
+ * nchannels, OUTPUT_BUFFER_LENGTH_PER_THREAD], should be on GPU
+ * @param lengths The int32 lengths tensor, with shape [nlayers, nchannels],
+ * should be on GPU
+ * @param output The uint8 output tensor, with shape nlayers, ntokens,
+ * nchannels], should be on GPU.
+ */
+void decode_cuda_new(const at::Tensor& cdf, const at::Tensor& bytestreams,
+                     const at::Tensor& lengths, at::Tensor& output) {
+  TORCH_CHECK(cdf.is_cuda(), "CDF should be on GPU");
+  TORCH_CHECK(bytestreams.is_cuda(), "Bytestreams should be on GPU");
+  TORCH_CHECK(lengths.is_cuda(), "Lengths should be on GPU");
+  TORCH_CHECK(output.is_cuda(), "Output should be on GPU");
+
+  const auto cdf_shape = cdf.sizes();
+  const auto bs_shape = bytestreams.sizes();
+  const auto lengths_shape = lengths.sizes();
+  const auto output_shape = output.sizes();
+  TORCH_CHECK(cdf_shape[0] == bs_shape[0],
+              "CDF and bytestreams should have the same number of layers");
+  TORCH_CHECK(cdf_shape[1] == bs_shape[1],
+              "CDF and bytestreams should have the same number of channels");
+  TORCH_CHECK(cdf_shape[0] == lengths_shape[0],
+              "CDF and lengths should have the same number of layers");
+  TORCH_CHECK(cdf_shape[1] == lengths_shape[1],
+              "CDF and lengths should have the same number of channels");
+  TORCH_CHECK(cdf_shape[0] == output_shape[0],
+              "CDF and output should have the same number of layers");
+  TORCH_CHECK(cdf_shape[1] == output_shape[2],
+              "CDF and output should have the same number of channels");
+
+  const int nlayers = cdf_shape[0];
+  const int nchannels = cdf_shape[1];
+  const int ntokens = output_shape[1];
+  const int lp = cdf_shape[2];
+  const int block_size = get_block_size(nchannels);
+  TORCH_CHECK(ntokens <= MAX_TOKENS_PER_THREAD,
+              "Number of tokens should be less than or equal to",
+              MAX_TOKENS_PER_THREAD);
+  TORCH_CHECK(nchannels % block_size == 0,
+              "Number of channels should be divisible by block size");
+  TORCH_CHECK(lp <= MAX_LP, "CDF should have at most", MAX_LP, "Lps");
+
+  dim3 block_dim(block_size, 1, 1);
+  dim3 grid_dim(nlayers, nchannels / block_size, 1);
+
+  auto cdf_accessor =
+      cdf.packed_accessor32<int16_t, 3, torch::RestrictPtrTraits>();
+  auto bytestreams_accessor =
+      bytestreams.packed_accessor32<uint8_t, 3, torch::RestrictPtrTraits>();
+  auto lengths_accessor =
+      lengths.packed_accessor32<int32_t, 2, torch::RestrictPtrTraits>();
+  auto output_accessor =
+      output.packed_accessor32<uint8_t, 3, torch::RestrictPtrTraits>();
+
+#ifndef LAUNCH_DECODE_KERNEL
+  #define LAUNCH_DECODE_KERNEL(block_size)                                     \
+    decode_with_accessor_kernel<block_size><<<grid_dim, block_dim>>>(          \
+        cdf_accessor, bytestreams_accessor, lengths_accessor, output_accessor, \
+        lp, ntokens)
+#endif
+
+  switch (block_size) {
+    case 1:
+      LAUNCH_DECODE_KERNEL(1);
+      break;
+    case 2:
+      LAUNCH_DECODE_KERNEL(2);
+      break;
+    case 4:
+      LAUNCH_DECODE_KERNEL(4);
+      break;
+    case 8:
+      LAUNCH_DECODE_KERNEL(8);
+      break;
+    case 16:
+      LAUNCH_DECODE_KERNEL(16);
+      break;
+    case 32:
+      LAUNCH_DECODE_KERNEL(32);
+      break;
+    case 64:
+      LAUNCH_DECODE_KERNEL(64);
+      break;
+    case 128:
+      LAUNCH_DECODE_KERNEL(128);
+      break;
+    default:
+      throw std::runtime_error("Unsupported block size");
+  }
+}
+
+/**
+ * @brief CUDA kernel to decode a compressed bytestream using the given CDF.
+ *
+ * @param cdf the int16 CDF tensor, with shape [nlayers, nchannels, LP], should
+ * be on GPU
+ * @param bytestreams The 1-D uint8 bytestreams tensor containing [nlayers,
+ * nchannels] bytestreams, should be on GPU
+ * @param lengths_prefsum The int64 tensor containing the prefix sum of the
+ * lengths, with shape [nlayers, nchannels], should be on GPU
+ * @param output The uint8 output tensor, with shape nlayers, ntokens,
+ * nchannels], should be on GPU.
+ */
+void decode_cuda_prefsum(const at::Tensor& cdf, const at::Tensor& bytestreams,
+                         const at::Tensor& lengths_prefsum,
+                         at::Tensor& output) {
+  TORCH_CHECK(cdf.is_cuda(), "CDF should be on GPU");
+  TORCH_CHECK(bytestreams.is_cuda(), "Bytestreams should be on GPU");
+  TORCH_CHECK(lengths_prefsum.is_cuda(), "Lengths should be on GPU");
+  TORCH_CHECK(output.is_cuda(), "Output should be on GPU");
+
+  const auto cdf_shape = cdf.sizes();
+  const auto lengths_shape = lengths_prefsum.sizes();
+  const auto output_shape = output.sizes();
+  TORCH_CHECK(cdf_shape[0] == lengths_shape[0],
+              "CDF and lengths should have the same number of layers");
+  TORCH_CHECK(cdf_shape[1] == lengths_shape[1],
+              "CDF and lengths should have the same number of channels");
+  TORCH_CHECK(cdf_shape[0] == output_shape[0],
+              "CDF and output should have the same number of layers");
+  TORCH_CHECK(cdf_shape[1] == output_shape[2],
+              "CDF and output should have the same number of channels");
+
+  const int nlayers = cdf_shape[0];
+  const int nchannels = cdf_shape[1];
+  const int ntokens = output_shape[1];
+  const int lp = cdf_shape[2];
+  const int block_size = get_block_size(nchannels);
+  TORCH_CHECK(ntokens <= MAX_TOKENS_PER_THREAD,
+              "Number of tokens should be less than or equal to",
+              MAX_TOKENS_PER_THREAD);
+  TORCH_CHECK(nchannels % block_size == 0,
+              "Number of channels should be divisible by block size");
+  TORCH_CHECK(lp <= MAX_LP, "CDF should have at most", MAX_LP, "Lps");
+
+  dim3 block_dim(block_size, 1, 1);
+  dim3 grid_dim(nlayers, nchannels / block_size, 1);
+
+  auto cdf_accessor =
+      cdf.packed_accessor32<int16_t, 3, torch::RestrictPtrTraits>();
+  auto bytestreams_accessor =
+      bytestreams.packed_accessor32<uint8_t, 1, torch::RestrictPtrTraits>();
+  auto lengths_accessor =
+      lengths_prefsum.packed_accessor32<int64_t, 2, torch::RestrictPtrTraits>();
+  auto output_accessor =
+      output.packed_accessor32<uint8_t, 3, torch::RestrictPtrTraits>();
+
+#ifndef LAUNCH_DECODE_PREFIX_KERNEL
+  #define LAUNCH_DECODE_PREFIX_KERNEL(block_size)                              \
+    decode_prefix_with_accessor_kernel<block_size><<<grid_dim, block_dim>>>(   \
+        cdf_accessor, bytestreams_accessor, lengths_accessor, output_accessor, \
+        lp, ntokens)
+#endif
+
+  switch (block_size) {
+    case 1:
+      LAUNCH_DECODE_PREFIX_KERNEL(1);
+      break;
+    case 2:
+      LAUNCH_DECODE_PREFIX_KERNEL(2);
+      break;
+    case 4:
+      LAUNCH_DECODE_PREFIX_KERNEL(4);
+      break;
+    case 8:
+      LAUNCH_DECODE_PREFIX_KERNEL(8);
+      break;
+    case 16:
+      LAUNCH_DECODE_PREFIX_KERNEL(16);
+      break;
+    case 32:
+      LAUNCH_DECODE_PREFIX_KERNEL(32);
+      break;
+    case 64:
+      LAUNCH_DECODE_PREFIX_KERNEL(64);
+      break;
+    case 128:
+      LAUNCH_DECODE_PREFIX_KERNEL(128);
+      break;
+    default:
+      throw std::runtime_error("Unsupported block size");
+  }
+}
diff --git a/csrc/ac_enc.cu b/csrc/ac_enc.cu
new file mode 100644
index 0000000..def33c3
--- /dev/null
+++ b/csrc/ac_enc.cu
@@ -0,0 +1,477 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <iostream>
+#include <cstdio>
+#include <cuda_runtime.h>
+#include "cachegen_kernels.cuh"
+
+#define MAX_LP 48
+#define MAX_THREAD_PER_BLOCK 128
+#define MAX_SHARED_MEMORY_PER_THREAD (0xc000 / MAX_THREAD_PER_BLOCK)
+#if MAX_SHARED_MEMORY_PER_THREAD - MAX_LP * 2 > 256
+  #define MAX_TOKENS_PER_THREAD 256
+  #define OUTPUT_BUFFER_LENGTH_PER_THREAD 256
+#else
+  #define OUTPUT_BUFFER_LENGTH_PER_THREAD \
+    (MAX_SHARED_MEMORY_PER_THREAD - MAX_LP * 2)
+  #define MAX_TOKENS_PER_THREAD (OUTPUT_BUFFER_LENGTH_PER_THREAD)
+#endif
+#define PRECISION 16
+
+/**
+ * Spill the register to the shared memory
+ */
+__device__ __inline__ void spill_reg_to_shared(uint32_t output_reg,
+                                               int& output_reg_len,
+                                               uint8_t* output_shared,
+                                               int& output_shared_offset) {
+  output_reg <<= 32 - output_reg_len;
+  output_reg_len = 0;
+  // TODO: potential optimization: since it uses little endian, we can directly
+  // write the 4 bytes
+  output_shared[output_shared_offset] = output_reg >> 24;
+  output_shared[output_shared_offset + 1] = (output_reg >> 16) & 0xFF;
+  output_shared[output_shared_offset + 2] = (output_reg >> 8) & 0xFF;
+  output_shared[output_shared_offset + 3] = output_reg & 0xFF;
+  output_shared_offset += 4;
+  output_reg = 0;
+}
+
+/**
+ * Spill the register to the shared memory, when it is not a full 32 bits
+ */
+__device__ __inline__ void spill_partial_reg_to_shared(
+    uint32_t output_reg, int& output_reg_len, uint8_t* output_shared,
+    int& output_shared_offset) {
+  output_reg <<= 32 - output_reg_len;
+  while (output_reg_len > 0) {
+    output_reg_len -= 8;
+    output_shared[output_shared_offset] = output_reg >> 24;
+    output_shared_offset++;
+    output_reg <<= 8;
+  }
+}
+
+/**
+ * Write N bits of 0/1 to the output. Save the overflow bits to the shared
+ * memory
+ */
+__device__ __inline__ void add_bits_to_output(uint32_t bit, int num,
+                                              uint32_t& output_reg,
+                                              int& output_reg_len,
+                                              uint8_t* output_shared,
+                                              int& output_shared_offset) {
+  do {
+    const int remaining = min(num, 32 - output_reg_len);
+    output_reg <<= remaining;
+    output_reg |= (bit << remaining) - bit;
+    num -= remaining;
+    output_reg_len += remaining;
+    if (output_reg_len == 32) {
+      spill_reg_to_shared(output_reg, output_reg_len, output_shared,
+                          output_shared_offset);
+    }
+  } while (num > 0);
+}
+
+/**
+ * Append a bit to the output, and add the pending bits
+ */
+__device__ __inline__ void append_bit_and_pending(
+    uint32_t bit, uint64_t& pending_bits, uint32_t& output_reg,
+    int& output_reg_len, uint8_t* output_shared, int& output_shared_offset) {
+  add_bits_to_output(bit, 1, output_reg, output_reg_len, output_shared,
+                     output_shared_offset);
+  add_bits_to_output(1 - bit, pending_bits, output_reg, output_reg_len,
+                     output_shared, output_shared_offset);
+  pending_bits = 0;
+}
+
+__inline__ __device__ void warp_scan(volatile int* temp, int tid) {
+  int offset = 1;
+  int n = blockDim.x;
+  while (offset < n) {
+    if (tid >= offset) temp[tid] += temp[tid - offset];
+    offset *= 2;
+    __syncthreads();
+  }
+}
+
+// This is assuming each thread will process all the tokens in the same layer
+// and channel
+template <int BLOCK_SIZE>
+__global__ void encode_kernel(
+    const uint16_t* cdf,       // shape [nlayers, nchannels, Lp]
+    const uint8_t* input_sym,  // shape [nlayers, ntokens, nchannels]
+    uint8_t* output_buffer,    // shape [nlayers, nchannels,
+                               // OUTPUT_BUFFER_LENGTH_PER_THREAD]
+    int32_t* output_lengths,   // shape [nlayers, nchannels]
+    int32_t lp, int32_t ntokens, int32_t output_buffer_length_per_thread) {
+  // The shared memory will be split to 2 parts:
+  // 1. The CDF tensor, with shape [MAX_LP, BLOCK_SIZE)] (only used [LP,
+  // BLOCK_SIZE] part)
+  // 2. The output buffer, with shape [BLOCK_SIZE, MAX_SHARED_PER_THREAD -
+  // MAX_LP * 2] uint8s
+  __shared__ uint16_t cdf_shared[MAX_LP * BLOCK_SIZE];
+  __shared__ uint8_t
+      output_shared[BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD];
+
+  const int nchannels = gridDim.y * BLOCK_SIZE;
+
+  const int layer_id = blockIdx.x;
+  const int channel_id = blockIdx.y * BLOCK_SIZE + threadIdx.x;
+
+  // Copy the CDF[layer_id, channel_start:channel_end, :] to shared memory
+  const int cdf_offset = (blockIdx.y * BLOCK_SIZE) * lp;
+  const int cdf_size = BLOCK_SIZE * lp;
+  for (int i = threadIdx.x; i < cdf_size; i += blockDim.x) {
+    const int cid = i / lp;
+    const int lid = i % lp;
+    const int shared_offset = lid * BLOCK_SIZE + cid;
+    cdf_shared[shared_offset] = reinterpret_cast<uint16_t>(
+        cdf[layer_id * nchannels * lp + cdf_offset + i]);
+  }
+
+  __syncthreads();
+
+  // Do the actual encoding
+  uint32_t low = 0U;
+  uint32_t high = 0xFFFFFFFFU;
+  uint64_t pending_bits = 0;
+  const int max_symbol = lp - 2;
+
+  uint32_t output_reg = 0;
+  int output_reg_len = 0;
+  int output_shared_offset = threadIdx.x * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+
+  for (int i = 0; i < ntokens; i++) {
+    const uint8_t sym =
+        input_sym[layer_id * ntokens * nchannels + i * nchannels + channel_id];
+    const uint64_t span =
+        static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+
+    const uint32_t c_low = cdf_shared[sym * BLOCK_SIZE + threadIdx.x];
+    const uint32_t c_high =
+        sym == max_symbol ? 0x10000U
+                          : cdf_shared[(sym + 1) * BLOCK_SIZE + threadIdx.x];
+
+    high = (low - 1) + ((span * static_cast<uint64_t>(c_high)) >> precision);
+    low = (low) + ((span * static_cast<uint64_t>(c_low)) >> precision);
+
+    while (true) {
+      if (high < 0x80000000U) {
+        append_bit_and_pending(0, pending_bits, output_reg, output_reg_len,
+                               output_shared, output_shared_offset);
+        low <<= 1;
+        high <<= 1;
+        high |= 1;
+      } else if (low >= 0x80000000U) {
+        append_bit_and_pending(1, pending_bits, output_reg, output_reg_len,
+                               output_shared, output_shared_offset);
+        low <<= 1;
+        high <<= 1;
+        high |= 1;
+      } else if (low >= 0x40000000U && high < 0xC0000000U) {
+        pending_bits++;
+        low <<= 1;
+        low &= 0x7FFFFFFF;
+        high <<= 1;
+        high |= 0x80000001;
+      } else {
+        break;
+      }
+    }
+  }
+
+  pending_bits += 1;
+
+  if (low < 0x40000000U) {
+    append_bit_and_pending(0, pending_bits, output_reg, output_reg_len,
+                           output_shared, output_shared_offset);
+  } else {
+    append_bit_and_pending(1, pending_bits, output_reg, output_reg_len,
+                           output_shared, output_shared_offset);
+  }
+
+  spill_partial_reg_to_shared(output_reg, output_reg_len, output_shared,
+                              output_shared_offset);
+  output_lengths[layer_id * nchannels + channel_id] =
+      output_shared_offset - threadIdx.x * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+
+  __syncthreads();
+
+  // reuse cdf for the prefix sum
+  int* output_lengths_shared = reinterpret_cast<int*>(cdf_shared);
+  output_lengths_shared[threadIdx.x] =
+      output_shared_offset - threadIdx.x * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+  __syncthreads();
+
+  // Copy the output buffer to global memory
+  // then copy one "row" at a time, and make sure the write is coalesced
+  for (int i = 0; i < BLOCK_SIZE; i++) {
+    int length = output_lengths_shared[i];
+    int current_channel = blockIdx.y * BLOCK_SIZE + i;
+    for (int j = threadIdx.x; j < length; j += blockDim.x) {
+      int global_offset =
+          layer_id * nchannels * output_buffer_length_per_thread +
+          current_channel * output_buffer_length_per_thread + j;
+      int local_offset = i * OUTPUT_BUFFER_LENGTH_PER_THREAD + j;
+      output_buffer[global_offset] = output_shared[local_offset];
+    }
+  }
+}
+
+// This is assuming each thread will process all the tokens in the same layer
+// and channel
+template <int BLOCK_SIZE, typename CDF_ACC_T, typename SYM_ACC_T,
+          typename OUTPUT_ACC_T, typename LEN_ACC_T>
+__global__ void encode_with_accessor_kernel(
+    CDF_ACC_T cdf,               // shape [nlayers, nchannels, Lp]
+    SYM_ACC_T input_sym,         // shape [nlayers, ntokens, nchannels]
+    OUTPUT_ACC_T output_buffer,  // shape [nlayers, nchannels,
+                                 // OUTPUT_BUFFER_LENGTH_PER_THREAD]
+    LEN_ACC_T output_lengths,    // shape [nlayers, nchannels]
+    int32_t lp, int32_t ntokens) {
+  // The shared memory will be split to 2 parts:
+  // 1. The CDF tensor, with shape [MAX_LP, BLOCK_SIZE)] (only used [LP,
+  // BLOCK_SIZE] part)
+  // 2. The output buffer, with shape [BLOCK_SIZE, MAX_SHARED_PER_THREAD -
+  // MAX_LP * 2] uint8s
+  __shared__ uint16_t cdf_shared[MAX_LP * BLOCK_SIZE];
+  __shared__ uint8_t
+      output_shared[BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD];
+
+  const int layer_id = blockIdx.x;
+  const int channel_id = blockIdx.y * BLOCK_SIZE + threadIdx.x;
+
+  // Copy the CDF[layer_id, channel_start:channel_end, :] to shared memory
+  const int cdf_size = BLOCK_SIZE * lp;
+  for (int i = threadIdx.x; i < cdf_size; i += blockDim.x) {
+    const int cid = i / lp;
+    const int lid = i % lp;
+    const int shared_offset = lid * BLOCK_SIZE + cid;
+    const int16_t value = cdf[layer_id][cid + blockIdx.y * BLOCK_SIZE][lid];
+    cdf_shared[shared_offset] = static_cast<uint16_t>(value);
+  }
+
+  __syncthreads();
+
+  // Do the actual encoding
+  uint32_t low = 0U;
+  uint32_t high = 0xFFFFFFFFU;
+  uint64_t pending_bits = 0;
+  const int max_symbol = lp - 2;
+
+  uint32_t output_reg = 0;
+  int output_reg_len = 0;
+  int output_shared_offset = threadIdx.x * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+
+  for (int i = 0; i < ntokens; i++) {
+    const uint8_t sym =
+        input_sym[layer_id][i][channel_id];  //[layer_id * ntokens * nchannels +
+                                             // i * nchannels + channel_id];
+    const uint64_t span =
+        static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+
+    const uint32_t c_low = cdf_shared[sym * BLOCK_SIZE + threadIdx.x];
+    const uint32_t c_high =
+        sym == max_symbol ? 0x10000U
+                          : cdf_shared[(sym + 1) * BLOCK_SIZE + threadIdx.x];
+
+    high = (low - 1) + ((span * static_cast<uint64_t>(c_high)) >> precision);
+    low = (low) + ((span * static_cast<uint64_t>(c_low)) >> precision);
+
+    while (true) {
+      if (high < 0x80000000U) {
+        append_bit_and_pending(0, pending_bits, output_reg, output_reg_len,
+                               output_shared, output_shared_offset);
+        low <<= 1;
+        high <<= 1;
+        high |= 1;
+      } else if (low >= 0x80000000U) {
+        append_bit_and_pending(1, pending_bits, output_reg, output_reg_len,
+                               output_shared, output_shared_offset);
+        low <<= 1;
+        high <<= 1;
+        high |= 1;
+      } else if (low >= 0x40000000U && high < 0xC0000000U) {
+        pending_bits++;
+        low <<= 1;
+        low &= 0x7FFFFFFF;
+        high <<= 1;
+        high |= 0x80000001;
+      } else {
+        break;
+      }
+    }
+  }
+
+  pending_bits += 1;
+
+  if (low < 0x40000000U) {
+    append_bit_and_pending(0, pending_bits, output_reg, output_reg_len,
+                           output_shared, output_shared_offset);
+  } else {
+    append_bit_and_pending(1, pending_bits, output_reg, output_reg_len,
+                           output_shared, output_shared_offset);
+  }
+
+  spill_partial_reg_to_shared(output_reg, output_reg_len, output_shared,
+                              output_shared_offset);
+  output_lengths[layer_id][channel_id] =
+      output_shared_offset - threadIdx.x * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+
+  __syncthreads();
+
+  // reuse cdf for the prefix sum
+  int* output_lengths_shared = reinterpret_cast<int*>(cdf_shared);
+  output_lengths_shared[threadIdx.x] =
+      output_shared_offset - threadIdx.x * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+  __syncthreads();
+
+  // Copy the output buffer to global memory
+  // then copy one "row" at a time, and make sure the write is coalesced
+  for (int i = 0; i < BLOCK_SIZE; i++) {
+    int length = output_lengths_shared[i];
+    int current_channel = blockIdx.y * BLOCK_SIZE + i;
+    for (int j = threadIdx.x; j < length; j += blockDim.x) {
+      output_buffer[layer_id][current_channel][j] =
+          output_shared[i * OUTPUT_BUFFER_LENGTH_PER_THREAD + j];
+    }
+  }
+}
+
+int get_block_size(int nchannels) {
+  // find the biggest 2^n that can divide nchannels
+  int factor = (nchannels ^ (nchannels - 1)) + 1;
+  factor >>= 1;
+  if (factor > MAX_THREAD_PER_BLOCK) {
+    factor = MAX_THREAD_PER_BLOCK;
+  }
+  return factor;
+}
+
+/**
+ * Encodes the input symbols to a list of bytestreams
+ *
+ * Input:
+ *   cdf: the int16 CDF tensor, with shape [nlayers, nchannels, Lp], should be
+ * on GPU input_sym: the int8 symbols tensor, with shape [nlayers, ntokens,
+ * nchannels], should be on GPU output_buffer: the output buffer of int8, with
+ * shape [nlayers, nchannels, ntokens * 2] should be on GPU output_lengths: the
+ * output lengths of int32, with shape [nlayers, nchannels], should be on GPU
+ *
+ * Note:
+ *   The block and grid mapping is as follows:
+ *   - Each thread is responsible for 1 layer, 1 channel, all the tokens
+ *   - Each block is responsible for 1 layer, 256 channel # TODO: maybe make
+ * '256' configurable
+ *   - Each grid consists of (nlayers, nchannels / 256) blocks
+ *   Each block will copy all the CDFs and output buffers to shared memory
+ *   On Volta, ADA and Ampere, the shared memory per thread is ~1KB. The CDF
+ * will take Lp * 2 bytes (66 bytes), and the output buffer will take ntokens *
+ * 2 bytes. So ideally the ntokens should be less than 512.
+ */
+void encode_cuda_new(const at::Tensor& cdf, const at::Tensor& input_sym,
+                     at::Tensor& output_buffer, at::Tensor& output_lengths) {
+  // TODO: if the input tensor have too many tokens, the shared memory will not
+  // be enough to hold the output
+  //       The current boundary is around 256 tokens
+
+  /* Input validation */
+  TORCH_CHECK(cdf.is_cuda(), "CDF should be on GPU");
+  TORCH_CHECK(input_sym.is_cuda(), "Input symbols should be on GPU");
+  TORCH_CHECK(output_buffer.is_cuda(), "Output buffer should be on GPU");
+  TORCH_CHECK(output_lengths.is_cuda(), "Output lengths should be on GPU");
+
+  const auto cdf_shape = cdf.sizes();
+  const auto input_shape = input_sym.sizes();
+  const auto output_shape = output_buffer.sizes();
+  const auto output_lengths_shape = output_lengths.sizes();
+  TORCH_CHECK(cdf_shape[0] == input_shape[0],
+              "CDF and input should have the same number of layers");
+  TORCH_CHECK(cdf_shape[1] == input_shape[2],
+              "CDF and input should have the same number of layers");
+  TORCH_CHECK(output_shape[0] == cdf_shape[0],
+              "Output buffer should have the same number of layers as CDF");
+  TORCH_CHECK(output_shape[1] == cdf_shape[1],
+              "Output buffer should have the same number of channels as CDF");
+  TORCH_CHECK(output_lengths_shape[0] == cdf_shape[0],
+              "Output lengths should have the same number of layers as CDF");
+  TORCH_CHECK(output_lengths_shape[1] == cdf_shape[1],
+              "Output lengths should have the same number of channels as CDF");
+
+  /* set block and grid size */
+  const int nlayers = cdf_shape[0];
+  const int nchannels = cdf_shape[1];
+  const int ntokens = input_shape[1];
+  // const int output_buffer_length_per_thread = output_shape[2];
+  const int block_size = get_block_size(nchannels);
+  TORCH_CHECK(ntokens <= MAX_TOKENS_PER_THREAD,
+              "Number of tokens should be less than or equal to ",
+              MAX_TOKENS_PER_THREAD);
+  TORCH_CHECK(nchannels % block_size == 0,
+              "Number of channels should be divisible by block size");
+  TORCH_CHECK(cdf_shape[2] <= MAX_LP, "CDF length should be less than MAX_LP");
+
+  dim3 block_dim(block_size, 1, 1);
+  dim3 grid_dim(nlayers, nchannels / block_size, 1);
+
+  // TODO: potential optimization: use PackedAccessor32 to access the tensors,
+  // in case the tensor is not contiguous
+  auto cdf_accessor =
+      cdf.packed_accessor32<int16_t, 3, torch::RestrictPtrTraits>();
+  auto input_sym_accessor =
+      input_sym.packed_accessor32<int8_t, 3, torch::RestrictPtrTraits>();
+  auto output_buffer_accessor =
+      output_buffer.packed_accessor32<uint8_t, 3, torch::RestrictPtrTraits>();
+  auto output_lengths_accessor =
+      output_lengths.packed_accessor32<int32_t, 2, torch::RestrictPtrTraits>();
+
+  /* Call the kernel */
+#ifndef LAUNCH_ENCODE_KERNEL
+  #define LAUNCH_ENCODE_KERNEL(block_size)                            \
+    encode_with_accessor_kernel<block_size><<<grid_dim, block_dim>>>( \
+        cdf_accessor, input_sym_accessor, output_buffer_accessor,     \
+        output_lengths_accessor, cdf_shape[2], ntokens)
+//#define LAUNCH_ENCODE_KERNEL(block_size) \
+//    encode_kernel<block_size><<<grid_dim, block_dim>>>( \
+//        (const uint16_t *)cdf.data_ptr<int16_t>(), \
+//        (const uint8_t *)input_sym.data_ptr<int8_t>(), \
+//        output_buffer.data_ptr<uint8_t>(), \
+//        output_lengths.data_ptr<int32_t>(), \
+//        cdf_shape[2], \
+//        ntokens, \
+//        output_buffer_length_per_thread \
+//    )
+#endif
+
+  switch (block_size) {
+    case 1:
+      LAUNCH_ENCODE_KERNEL(1);
+      break;
+    case 2:
+      LAUNCH_ENCODE_KERNEL(2);
+      break;
+    case 4:
+      LAUNCH_ENCODE_KERNEL(4);
+      break;
+    case 8:
+      LAUNCH_ENCODE_KERNEL(8);
+      break;
+    case 16:
+      LAUNCH_ENCODE_KERNEL(16);
+      break;
+    case 32:
+      LAUNCH_ENCODE_KERNEL(32);
+      break;
+    case 64:
+      LAUNCH_ENCODE_KERNEL(64);
+      break;
+    case 128:
+      LAUNCH_ENCODE_KERNEL(128);
+      break;
+    default:
+      throw std::runtime_error("Unsupported block size");
+  }
+}
\ No newline at end of file
diff --git a/csrc/cachegen_kernels.cuh b/csrc/cachegen_kernels.cuh
new file mode 100644
index 0000000..d20e1d6
--- /dev/null
+++ b/csrc/cachegen_kernels.cuh
@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <ATen/ATen.h>
+#include <pybind11/pybind11.h>
+#include <stdint.h>
+#include <cuda.h>
+#include <cuda_runtime.h>
+#include <torch/torch.h>
+#include <cstring>
+#include <vector>
+#include <string>
+#include <iostream>
+
+#include <cmath>
+
+#include <torch/extension.h>
+
+#include <tuple>
+#include <fstream>
+#include <algorithm>
+#include <chrono>
+#include <numeric>
+#include <iterator>
+
+#include <bitset>
+
+const int precision = 16;
+const int N = 1;
+using cdf_t = uint16_t;
+const int PRECISION = 16;
+const int RENORMALIZATION_FACTOR = 2 << (PRECISION - 1);
+const int STRIDE = 1;
+
+void encode_cuda_new(const at::Tensor& cdf, const at::Tensor& input_sym,
+                     at::Tensor& output_buffer, at::Tensor& output_lengths);
+
+void decode_cuda_new(const at::Tensor& cdf, const at::Tensor& bytestreams,
+                     const at::Tensor& lengths, at::Tensor& output);
+
+void decode_cuda_prefsum(const at::Tensor& cdf, const at::Tensor& bytestreams,
+                         const at::Tensor& lengths, at::Tensor& output);
+
+const struct cdf_ptr get_cdf_ptr_cuda(const at::Tensor& cdf);
+
+at::Tensor calculate_cdf(const at::Tensor& input, const int max_bins);
\ No newline at end of file
diff --git a/csrc/cal_cdf.cu b/csrc/cal_cdf.cu
new file mode 100644
index 0000000..32c7326
--- /dev/null
+++ b/csrc/cal_cdf.cu
@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <iostream>
+#include <cstdio>
+#include <cuda_runtime.h>
+#include <torch/torch.h>
+#include <ATen/ATen.h>
+
+#define MAX_BINS_SUPPORTED 64
+
+extern int get_block_size(int);
+
+__inline__ __device__ uint16_t normalize_cdf_value(uint16_t cdf_value,
+                                                   uint16_t max_cdf_value,
+                                                   const int max_bins) {
+  uint32_t MAX_UINT16_VALUE = 0xFFFF - max_bins;
+  return (uint16_t)(MAX_UINT16_VALUE * (uint32_t)cdf_value / max_cdf_value);
+}
+
+// BLOCK_SIZE should be equal to blockDim.x, and blockDim.y should be equal to 1
+template <int BLOCK_SIZE, int MAXBINS, typename INPUT_ACC_T,
+          typename OUTPUT_ACC_T>
+__global__ void calculate_cdf_kernel(INPUT_ACC_T input, OUTPUT_ACC_T output,
+                                     const int max_bins, const int ntokens) {
+  __shared__ uint16_t hist[MAXBINS][BLOCK_SIZE];
+
+  const int channel_id = blockIdx.x * BLOCK_SIZE + threadIdx.x;
+  const int layer_id = blockIdx.y;
+
+  for (int i = 0; i <= max_bins; i++) {
+    hist[i][threadIdx.x] = 0;
+  }
+
+  __syncthreads();
+
+  for (int i = 0; i < ntokens; i++) {
+    uint8_t value = input[layer_id][i][channel_id];
+    hist[value + 1][threadIdx.x]++;
+  }
+
+  uint16_t local_sum = 0;
+  for (int i = 0; i < max_bins; i++) {
+    uint16_t value = hist[i + 1][threadIdx.x];
+    hist[i + 1][threadIdx.x] += local_sum;
+    local_sum += value;
+  }
+
+  for (int i = 0; i <= max_bins; i++) {
+    hist[i][threadIdx.x] =
+        normalize_cdf_value(hist[i][threadIdx.x], local_sum, max_bins) + i;
+  }
+
+  __syncthreads();
+  const int num_elements = BLOCK_SIZE * (max_bins + 1);
+  const int start_channel = blockIdx.x * BLOCK_SIZE;
+  for (int i = threadIdx.x; i < num_elements; i += BLOCK_SIZE) {
+    int bin_id = i % (max_bins + 1);
+    int cid = i / (max_bins + 1);
+    output[layer_id][start_channel + cid][bin_id] = hist[bin_id][cid];
+  }
+}
+
+/**
+ * @brief Calculate the cdf across tokens in the same (layer, channel) pair of
+ * the input tensor
+ *
+ * @param input The input uint8 GPU tensor with shape [nlayers, ntokens,
+ * nchannels]
+ * @param max_bins The maximum number of bins (i.e., Lp - 1)
+ * @return at::Tensor The normalized int16t cdf that can be used for torchac
+ * with shape [nlayers, nchannels, max_bins + 1]
+ */
+at::Tensor calculate_cdf(const at::Tensor& input, const int max_bins) {
+  TORCH_CHECK(input.is_cuda(), "Input must be a CUDA tensor");
+  TORCH_CHECK(max_bins < MAX_BINS_SUPPORTED, "Max bins must be less than ",
+              MAX_BINS_SUPPORTED);
+
+  const auto input_shape = input.sizes();
+  const int nlayers = input_shape[0];
+  const int ntokens = input_shape[1];
+  const int nchannels = input_shape[2];
+
+  auto output = torch::zeros({nlayers, nchannels, max_bins + 1},
+                             input.options().dtype(at::kShort));
+
+  auto input_accessor = input.packed_accessor64<int8_t, 3>();
+  auto output_accessor = output.packed_accessor64<int16_t, 3>();
+
+  int block_size = get_block_size(nchannels);
+  dim3 block_dim(block_size, 1, 1);
+  dim3 grid_dim(nchannels / block_size, nlayers, 1);
+
+#ifndef LAUNCH_CDF_KERNEL
+  #define LAUNCH_CDF_KERNEL(block_size)                                      \
+    calculate_cdf_kernel<block_size, MAX_BINS_SUPPORTED>                     \
+        <<<grid_dim, block_dim>>>(input_accessor, output_accessor, max_bins, \
+                                  ntokens)
+#endif
+  switch (block_size) {
+    case 1:
+      LAUNCH_CDF_KERNEL(1);
+      break;
+    case 2:
+      LAUNCH_CDF_KERNEL(2);
+      break;
+    case 4:
+      LAUNCH_CDF_KERNEL(4);
+      break;
+    case 8:
+      LAUNCH_CDF_KERNEL(8);
+      break;
+    case 16:
+      LAUNCH_CDF_KERNEL(16);
+      break;
+    case 32:
+      LAUNCH_CDF_KERNEL(32);
+      break;
+    case 64:
+      LAUNCH_CDF_KERNEL(64);
+      break;
+    case 128:
+      LAUNCH_CDF_KERNEL(128);
+      break;
+    default:
+      throw std::runtime_error("Unsupported block size");
+  }
+
+  return output;
+}
diff --git a/csrc/completion_recorder.cpp b/csrc/completion_recorder.cpp
new file mode 100644
index 0000000..9f70ecd
--- /dev/null
+++ b/csrc/completion_recorder.cpp
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "completion_recorder.h"
+
+#include <utility>
+
+CompletionRecorder& CompletionRecorder::instance() {
+  static CompletionRecorder recorder;
+  return recorder;
+}
+
+void CompletionRecorder::push(std::unique_ptr<PendingCompletion> completion) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  buffer_.push_back(std::move(completion));
+}
+
+std::vector<std::unique_ptr<PendingCompletion>> CompletionRecorder::drain() {
+  std::lock_guard<std::mutex> lock(mutex_);
+  std::vector<std::unique_ptr<PendingCompletion>> result;
+  result.swap(buffer_);
+  return result;
+}
+
+static void
+#ifndef USE_ROCM
+    CUDART_CB
+#endif
+    completion_host_callback(void* data) {
+  // Adopt the raw pointer back into a unique_ptr.
+  std::unique_ptr<PendingCompletion> completion(
+      static_cast<PendingCompletion*>(data));
+  CompletionRecorder::instance().push(std::move(completion));
+}
+
+void record_completion_on_stream(int64_t cuda_stream_ptr,
+                                 const std::string& kind, std::string payload) {
+  auto completion = std::make_unique<PendingCompletion>(
+      PendingCompletion{kind, std::move(payload)});
+  auto stream = reinterpret_cast<lmcache_completion_stream_t>(
+      static_cast<uintptr_t>(cuda_stream_ptr));
+  // Pass ownership through the driver as a raw pointer; the host callback
+  // re-adopts it. Reclaim if the launch itself fails.
+  PendingCompletion* raw = completion.release();
+  auto err = LMCACHE_COMPLETION_LAUNCH_HOST_FUNC(stream,
+                                                 completion_host_callback, raw);
+  if (err != 0) {
+    delete raw;
+  }
+}
+
+CompletionDrainResult drain_recorded_completions() {
+  auto completions = CompletionRecorder::instance().drain();
+  CompletionDrainResult result;
+  result.reserve(completions.size());
+  for (auto& c : completions) {
+    result.emplace_back(std::move(c->kind), std::move(c->payload));
+  }
+  return result;
+}
diff --git a/csrc/completion_recorder.h b/csrc/completion_recorder.h
new file mode 100644
index 0000000..b02aa55
--- /dev/null
+++ b/csrc/completion_recorder.h
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// CUDA/HIP host-callback buffer for stream-completion records.
+// Mirrors event_recorder.h but carries an opaque bytes payload instead
+// of timestamped metadata. The callback runs without the GIL; Python
+// drains the buffer and dispatches to a handler keyed by ``kind``.
+
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <utility>
+#include <vector>
+
+#ifdef USE_ROCM
+  #include <hip/hip_runtime.h>
+using lmcache_completion_stream_t = hipStream_t;
+  #define LMCACHE_COMPLETION_LAUNCH_HOST_FUNC hipLaunchHostFunc
+#else
+  #include <cuda_runtime.h>
+using lmcache_completion_stream_t = cudaStream_t;
+  #define LMCACHE_COMPLETION_LAUNCH_HOST_FUNC cudaLaunchHostFunc
+#endif
+
+struct PendingCompletion {
+  std::string kind;     // dispatch key, e.g. "finish_write"
+  std::string payload;  // opaque encoded bytes (e.g. msgpack)
+};
+
+class CompletionRecorder {
+ public:
+  static CompletionRecorder& instance();
+  // Takes ownership of the heap-allocated PendingCompletion.
+  void push(std::unique_ptr<PendingCompletion> completion);
+  std::vector<std::unique_ptr<PendingCompletion>> drain();
+
+ private:
+  CompletionRecorder() = default;
+  std::mutex mutex_;
+  std::vector<std::unique_ptr<PendingCompletion>> buffer_;
+};
+
+// Schedule a completion record. Called WITHOUT the GIL.
+void record_completion_on_stream(int64_t cuda_stream_ptr,
+                                 const std::string& kind, std::string payload);
+
+using CompletionDrainResult = std::vector<std::pair<std::string, std::string>>;
+
+CompletionDrainResult drain_recorded_completions();
diff --git a/csrc/cuda_compat.h b/csrc/cuda_compat.h
new file mode 100644
index 0000000..64fd7f9
--- /dev/null
+++ b/csrc/cuda_compat.h
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+ * Adapted from
+ * https://github.com/vllm-project/vllm/blob/main/csrc/cuda_compat.h
+ */
+
+#pragma once
+#ifndef USE_ROCM
+  #define LMCACHE_LDG(arg) __ldg(arg)
+#else
+  #define LMCACHE_LDG(arg) *(arg)
+#endif
\ No newline at end of file
diff --git a/csrc/dispatch_utils.h b/csrc/dispatch_utils.h
new file mode 100644
index 0000000..e0e03df
--- /dev/null
+++ b/csrc/dispatch_utils.h
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+ * Adapted from
+ * https://github.com/pytorch/pytorch/blob/v2.0.1/aten/src/ATen/Dispatch.h
+ * https://github.com/vllm-project/vllm/blob/main/csrc/dispatch_utils.h
+ */
+
+#pragma once
+
+#include <torch/all.h>
+
+#define LMC_DISPATCH_CASE_FLOATING_TYPES(...)          \
+  AT_DISPATCH_CASE(at::ScalarType::Float, __VA_ARGS__) \
+  AT_DISPATCH_CASE(at::ScalarType::Half, __VA_ARGS__)  \
+  AT_DISPATCH_CASE(at::ScalarType::BFloat16, __VA_ARGS__)
+
+#define LMC_DISPATCH_FLOATING_TYPES(TYPE, NAME, ...) \
+  AT_DISPATCH_SWITCH(TYPE, NAME, LMC_DISPATCH_CASE_FLOATING_TYPES(__VA_ARGS__))
+
+#define LMC_DISPATCH_CASE_FLOATING_AND_BYTE_TYPES(...)    \
+  AT_DISPATCH_CASE(at::ScalarType::Float, __VA_ARGS__)    \
+  AT_DISPATCH_CASE(at::ScalarType::Half, __VA_ARGS__)     \
+  AT_DISPATCH_CASE(at::ScalarType::BFloat16, __VA_ARGS__) \
+  AT_DISPATCH_CASE(at::ScalarType::Byte, __VA_ARGS__)
+
+#define LMC_DISPATCH_FLOATING_AND_BYTE_TYPES(TYPE, NAME, ...) \
+  AT_DISPATCH_SWITCH(TYPE, NAME,                              \
+                     LMC_DISPATCH_CASE_FLOATING_AND_BYTE_TYPES(__VA_ARGS__))
+
+#define LMC_DISPATCH_CASE_INTEGRAL_TYPES(...)          \
+  AT_DISPATCH_CASE(at::ScalarType::Byte, __VA_ARGS__)  \
+  AT_DISPATCH_CASE(at::ScalarType::Char, __VA_ARGS__)  \
+  AT_DISPATCH_CASE(at::ScalarType::Short, __VA_ARGS__) \
+  AT_DISPATCH_CASE(at::ScalarType::Int, __VA_ARGS__)   \
+  AT_DISPATCH_CASE(at::ScalarType::Long, __VA_ARGS__)
+
+#define LMC_DISPATCH_INTEGRAL_TYPES(TYPE, NAME, ...) \
+  AT_DISPATCH_SWITCH(TYPE, NAME, LMC_DISPATCH_CASE_INTEGRAL_TYPES(__VA_ARGS__))
\ No newline at end of file
diff --git a/csrc/engine_kv_format.h b/csrc/engine_kv_format.h
new file mode 100644
index 0000000..b42bcd5
--- /dev/null
+++ b/csrc/engine_kv_format.h
@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+// Physical KV-cache memory layout an engine hands to LMCache, plus the
+// classification predicates over it. Vendor-header-free, so every backend and
+// the Python facade (lmc_ops) share one definition. Detection (raw layout ->
+// format) lives in lmcache/v1/gpu_connector/kv_format.
+
+/*
+Symbol Reference:
+NL: number of layers
+NB: number of blocks/pages
+BS: block/page size
+NBBS: block/page buffer size = NB * BS
+NH: number of heads
+HS: head size
+TWO: 2
+ONE: 1
+
+_ means a dimension within the same tensor
+_X_ means a dimension across a list
+
+A_X_B_X_C_D_E means:
+kv_cache: List[List[torch.Tensor]]
+len(kv_cache) = A
+len(kv_cache[0]) = B
+kv_cache[0][0].shape = (C, D, E)
+*/
+enum class EngineKVFormat : int {
+  NB_NL_TWO_BS_NH_HS = 0,
+  /*
+  used by:
+  - vLLM CROSS_LAYER mode
+  */
+
+  NL_X_TWO_NB_BS_NH_HS = 1,
+  /*
+  used by:
+  - vLLM non-MLA flash attention
+  */
+
+  NL_X_NB_TWO_BS_NH_HS = 2,
+  /*
+  used by:
+  - vLLM non-MLA flash infer
+  */
+
+  NL_X_NB_BS_HS = 3,
+  /*
+  used by:
+  - vLLM MLA
+  */
+
+  TWO_X_NL_X_NBBS_NH_HS = 4,
+  /*
+  used by:
+  - SGLang MHA (flash attention and flash infer)
+  */
+
+  NL_X_NBBS_ONE_HS = 5,
+  /*
+  used by:
+  - SGLang MLA
+  */
+
+  NL_X_TWO_NB_NH_BS_HS = 6,
+  /*
+  used by:
+  - vLLM non-MLA flash attention (HND layout)
+  physical shape per layer: [2, num_blocks, num_heads, block_size, head_size]
+  */
+
+  NL_X_NB_TWO_NH_BS_HS = 7,
+  /*
+  used by:
+  - vLLM non-MLA flash infer (HND layout)
+  physical shape per layer: [num_blocks, 2, num_heads, block_size, head_size]
+  */
+
+  NB_NL_TWO_NH_BS_HS = 8,
+  /*
+  used by:
+  - TRT-LLM cross-layer (HND layout)
+  physical shape: [num_blocks, num_layers, 2, num_heads, block_size, head_size]
+  */
+
+  TWO_X_NL_X_NB_BS_NH_HS = 9,
+  /*
+  used by:
+  - SGLang MHA via the MP daemon path
+  physical shape per layer: [num_blocks, block_size, num_heads, head_size]
+  */
+
+  NL_X_NB_NH_BS_TWO_HS = 10,
+  /*
+  used by:
+  - vLLM non-MLA blocks-first attention with K/V fused into the trailing dim
+  physical shape per layer: [num_blocks, num_heads, block_size, 2, head_size]
+  (recovered by splitting the fused trailing [block_size, 2 * head_size]).
+  Currently only reached via the host gather/scatter path, not the device
+  transfer kernels.
+  */
+};
+
+// __host__ __device__ under CUDA/HIP so the kernels can call these; the guard
+// keeps the header vendor-runtime-free.
+#if defined(__CUDACC__) || defined(__HIPCC__)
+  #define LMC_KV_FORMAT_HD __host__ __device__
+#else
+  #define LMC_KV_FORMAT_HD
+#endif
+
+// Structural shape of the normalized kv_caches: exactly one is true per format.
+
+// All layers in one fused tensor.
+LMC_KV_FORMAT_HD constexpr bool is_cross_layer(EngineKVFormat f) {
+  return f == EngineKVFormat::NB_NL_TWO_BS_NH_HS ||
+         f == EngineKVFormat::NB_NL_TWO_NH_BS_HS;
+}
+
+// Keys and values in two separate top-level lists: [key_layers, value_layers].
+LMC_KV_FORMAT_HD constexpr bool is_kv_list(EngineKVFormat f) {
+  return f == EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS ||
+         f == EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS;
+}
+
+// One list entry per layer: kv_caches[layer_idx] is that layer's tensor.
+LMC_KV_FORMAT_HD constexpr bool is_layer_list(EngineKVFormat f) {
+  return f == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS ||
+         f == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS ||
+         f == EngineKVFormat::NL_X_NB_BS_HS ||
+         f == EngineKVFormat::NL_X_NBBS_ONE_HS ||
+         f == EngineKVFormat::NL_X_TWO_NB_NH_BS_HS ||
+         f == EngineKVFormat::NL_X_NB_TWO_NH_BS_HS ||
+         f == EngineKVFormat::NL_X_NB_NH_BS_TWO_HS;
+}
+
+// Multi-head Latent Attention: a single latent KV head (no separate K/V split).
+LMC_KV_FORMAT_HD constexpr bool is_mla(EngineKVFormat f) {
+  return f == EngineKVFormat::NL_X_NB_BS_HS ||   // vLLM MLA
+         f == EngineKVFormat::NL_X_NBBS_ONE_HS;  // SGLang MLA
+}
diff --git a/csrc/event_recorder.cpp b/csrc/event_recorder.cpp
new file mode 100644
index 0000000..b599a35
--- /dev/null
+++ b/csrc/event_recorder.cpp
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "event_recorder.h"
+
+#include <chrono>
+#include <utility>
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// Monotonic wall-clock reader.
+//
+// Why not just `system_clock::now()`?  `system_clock` maps to CLOCK_REALTIME,
+// which NTP / chrony can slew backward by tens of microseconds to stay synced
+// with upstream.  CUDA host callbacks fire at arbitrary wall moments, so two
+// consecutive callbacks (e.g. MP_STORE_START then MP_STORE_END on the same
+// stream) can straddle a backward slew and land with end_ts < start_ts.
+// Jaeger then renders span duration as unsigned 64-bit subtraction, producing
+// the characteristic ~213503982d span duration (= 2^64 microseconds).
+//
+// Fix: anchor once to the (system_clock, steady_clock) pair at first call.
+// Every subsequent timestamp is computed as
+//   epoch_sys + (steady_now - epoch_steady)
+// which is monotonic (steady_clock == CLOCK_MONOTONIC on Linux) while
+// remaining expressed in Unix-epoch seconds so downstream consumers don't
+// notice any change.
+static double wall_clock_time() {
+  static const auto epoch_sys = std::chrono::system_clock::now();
+  static const auto epoch_steady = std::chrono::steady_clock::now();
+  auto now_steady = std::chrono::steady_clock::now();
+  auto since_epoch = epoch_sys.time_since_epoch() + (now_steady - epoch_steady);
+  return std::chrono::duration<double>(since_epoch).count();
+}
+
+// ---------------------------------------------------------------------------
+// EventRecorder
+// ---------------------------------------------------------------------------
+
+EventRecorder& EventRecorder::instance() {
+  static EventRecorder recorder;
+  return recorder;
+}
+
+void EventRecorder::push(PendingEvent* event) {
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    buffer_.push_back(std::move(*event));
+  }
+  delete event;
+}
+
+std::vector<PendingEvent> EventRecorder::drain() {
+  std::lock_guard<std::mutex> lock(mutex_);
+  std::vector<PendingEvent> result;
+  result.swap(buffer_);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// CUDA host callback — runs on a CUDA driver thread, no GIL.
+// ---------------------------------------------------------------------------
+
+static void
+#ifndef USE_ROCM
+    CUDART_CB
+#endif
+    event_host_callback(void* data) {
+  auto* event = static_cast<PendingEvent*>(data);
+  event->timestamp = wall_clock_time();
+  EventRecorder::instance().push(event);
+}
+
+// ---------------------------------------------------------------------------
+// Free functions for pybind11
+// ---------------------------------------------------------------------------
+
+void record_event_on_stream(
+    int64_t cuda_stream_ptr, const std::string& event_type_name,
+    const std::string& session_id,
+    const std::unordered_map<std::string, std::string>& str_metadata,
+    const std::unordered_map<std::string, int64_t>& int_metadata) {
+  auto* event = new PendingEvent{
+      event_type_name, session_id, 0.0, str_metadata, int_metadata,
+  };
+
+  auto stream = reinterpret_cast<lmcache_stream_t>(
+      static_cast<uintptr_t>(cuda_stream_ptr));
+  LMCACHE_LAUNCH_HOST_FUNC(stream, event_host_callback, event);
+}
+
+DrainResult drain_recorded_events() {
+  auto events = EventRecorder::instance().drain();
+  DrainResult result;
+  result.reserve(events.size());
+  for (auto& e : events) {
+    result.emplace_back(std::move(e.event_type_name), std::move(e.session_id),
+                        e.timestamp, std::move(e.str_metadata),
+                        std::move(e.int_metadata));
+  }
+  return result;
+}
diff --git a/csrc/event_recorder.h b/csrc/event_recorder.h
new file mode 100644
index 0000000..be435b2
--- /dev/null
+++ b/csrc/event_recorder.h
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <tuple>
+#include <unordered_map>
+#include <vector>
+
+// CUDA / HIP runtime
+#ifdef USE_ROCM
+  #include <hip/hip_runtime.h>
+using lmcache_stream_t = hipStream_t;
+  #define LMCACHE_LAUNCH_HOST_FUNC hipLaunchHostFunc
+#else
+  #include <cuda_runtime.h>
+using lmcache_stream_t = cudaStream_t;
+  #define LMCACHE_LAUNCH_HOST_FUNC cudaLaunchHostFunc
+#endif
+
+// ---------------------------------------------------------------------------
+// PendingEvent — lightweight struct held in a lock-free-ish buffer.
+// All fields are pure C++ (no Python objects) so the CUDA host callback
+// can write the timestamp without touching the GIL.
+// ---------------------------------------------------------------------------
+
+struct PendingEvent {
+  std::string event_type_name;  // e.g. "mp.store.start"
+  std::string session_id;
+  double timestamp;  // wall-clock, set by host callback
+  std::unordered_map<std::string, std::string> str_metadata;
+  std::unordered_map<std::string, int64_t> int_metadata;
+};
+
+// ---------------------------------------------------------------------------
+// EventRecorder — global singleton that buffers events from CUDA callbacks.
+// ---------------------------------------------------------------------------
+
+class EventRecorder {
+ public:
+  static EventRecorder& instance();
+
+  // Called from the CUDA host callback (no GIL held).
+  // Takes ownership of *event, moves it into the buffer, then deletes it.
+  void push(PendingEvent* event);
+
+  // Called from Python (GIL held) to drain all buffered events.
+  std::vector<PendingEvent> drain();
+
+ private:
+  EventRecorder() = default;
+  std::mutex mutex_;
+  std::vector<PendingEvent> buffer_;
+};
+
+// ---------------------------------------------------------------------------
+// Free functions exposed via pybind11
+// ---------------------------------------------------------------------------
+
+// Schedule an event recording on a CUDA stream.  The host callback stamps
+// the wall-clock time and pushes to the global EventRecorder.
+// Called WITHOUT the GIL (py::call_guard<py::gil_scoped_release>).
+void record_event_on_stream(
+    int64_t cuda_stream_ptr, const std::string& event_type_name,
+    const std::string& session_id,
+    const std::unordered_map<std::string, std::string>& str_metadata,
+    const std::unordered_map<std::string, int64_t>& int_metadata);
+
+// Drain all buffered events.  Returns a list of tuples:
+//   (event_type_name, session_id, timestamp, str_metadata, int_metadata)
+using DrainResult =
+    std::vector<std::tuple<std::string, std::string, double,
+                           std::unordered_map<std::string, std::string>,
+                           std::unordered_map<std::string, int64_t>>>;
+
+DrainResult drain_recorded_events();
diff --git a/csrc/kv_transfer_types.h b/csrc/kv_transfer_types.h
new file mode 100644
index 0000000..c24bfa8
--- /dev/null
+++ b/csrc/kv_transfer_types.h
@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+// Backend-agnostic transfer descriptors, free of any vendor runtime headers so
+// every backend (CUDA, ROCm, MUSA, SYCL/XPU, ...) shares one definition.
+
+#include "engine_kv_format.h"  // EngineKVFormat + its classification predicates
+
+enum class TransferDirection : int {
+  H2D = 0,
+  D2H = 1,
+};
diff --git a/csrc/mem_alloc.cpp b/csrc/mem_alloc.cpp
new file mode 100644
index 0000000..9ac21c1
--- /dev/null
+++ b/csrc/mem_alloc.cpp
@@ -0,0 +1,235 @@
+#include <cuda_runtime.h>
+#include <stdexcept>
+#include <string>
+#include <cassert>
+#include <sys/mman.h>
+#include <sys/syscall.h>
+#include <linux/mman.h>
+#include <unistd.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <cstring>            // for strerror
+#include <linux/mempolicy.h>  // for MPOL_BIND, MPOL_MF_MOVE, MPOL_MF_STRICT
+#include "mem_alloc.h"
+
+static constexpr size_t HUGEPAGE_SIZE = 2UL * 1024 * 1024;  // MAP_HUGE_2MB
+
+static inline size_t _align_hugepage(size_t size) {
+  return (size + HUGEPAGE_SIZE - 1) & ~(HUGEPAGE_SIZE - 1);
+}
+
+static void* _mmap_anon(size_t size, bool hugepages) {
+  int flags = MAP_PRIVATE | MAP_ANONYMOUS;
+  if (hugepages) {
+    flags |= MAP_HUGETLB | MAP_HUGE_2MB;
+  }
+  void* ptr = mmap(nullptr, size, PROT_READ | PROT_WRITE, flags, -1, 0);
+  if (ptr == MAP_FAILED) {
+    throw std::runtime_error(std::string("mmap failed: ") + strerror(errno));
+  }
+  return ptr;
+}
+
+uintptr_t alloc_pinned_ptr(size_t size, unsigned int flags) {
+  void* ptr = nullptr;
+  cudaError_t err = cudaHostAlloc(&ptr, size, flags);
+  if (err != cudaSuccess) {
+    throw std::runtime_error("cudaHostAlloc failed: " + std::to_string(err));
+  }
+  return reinterpret_cast<uintptr_t>(ptr);
+}
+
+void free_pinned_ptr(uintptr_t ptr) {
+  cudaError_t err = cudaFreeHost(reinterpret_cast<void*>(ptr));
+  if (err != cudaSuccess) {
+    throw std::runtime_error("cudaFreeHost failed: " + std::to_string(err));
+  }
+}
+
+uintptr_t alloc_hugepage_pinned_ptr(size_t size, unsigned int flags) {
+  size = _align_hugepage(size);
+  void* ptr = _mmap_anon(size, true);
+
+  cudaError_t st = cudaHostRegister(ptr, size, flags);
+  if (st != cudaSuccess) {
+    munmap(ptr, size);
+    throw std::runtime_error(std::string("cudaHostRegister failed: ") +
+                             cudaGetErrorString(st));
+  }
+
+  return reinterpret_cast<uintptr_t>(ptr);
+}
+
+void free_hugepage_pinned_ptr(uintptr_t ptr, size_t size) {
+  size = _align_hugepage(size);
+  void* p = reinterpret_cast<void*>(ptr);
+
+  // Unpin first, then unmap.
+  cudaError_t st = cudaHostUnregister(p);
+  if (st != cudaSuccess) {
+    munmap(p, size);
+    throw std::runtime_error(std::string("cudaHostUnregister failed: ") +
+                             cudaGetErrorString(st));
+  }
+  if (munmap(p, size) != 0) {
+    throw std::runtime_error(std::string("munmap failed: ") + strerror(errno));
+  }
+}
+
+void batched_memcpy(const std::vector<uintptr_t>& src_ptrs,
+                    const std::vector<uintptr_t>& dst_ptrs,
+                    const std::vector<size_t>& sizes) {
+  if (src_ptrs.size() != dst_ptrs.size() || src_ptrs.size() != sizes.size()) {
+    throw std::invalid_argument(
+        "batched_memcpy expects equally sized src_ptrs, dst_ptrs, and sizes");
+  }
+
+  for (size_t i = 0; i < src_ptrs.size(); ++i) {
+    if (sizes[i] == 0) {
+      continue;
+    }
+    std::memmove(reinterpret_cast<void*>(dst_ptrs[i]),
+                 reinterpret_cast<const void*>(src_ptrs[i]), sizes[i]);
+  }
+}
+
+static void first_touch(void* p, size_t size, bool hugepages) {
+  const size_t ps =
+      hugepages ? HUGEPAGE_SIZE : static_cast<size_t>(sysconf(_SC_PAGESIZE));
+  for (size_t off = 0; off < size; off += ps) {
+    volatile char* c = static_cast<volatile char*>(p) + off;
+    *c = 0;
+  }
+}
+
+static inline int mbind_sys(void* addr, unsigned long len, int mode,
+                            const unsigned long* nodemask,
+                            unsigned long maxnode, unsigned int flags) {
+  long rc = syscall(SYS_mbind, addr, len, mode, nodemask, maxnode, flags);
+  return (rc == -1) ? -errno : 0;
+}
+
+static uintptr_t _alloc_numa_impl(size_t size, int node, bool hugepages) {
+  if (hugepages) {
+    assert(size % HUGEPAGE_SIZE == 0);
+  }
+
+  void* ptr = _mmap_anon(size, hugepages);
+
+  // Maximum of 64 numa nodes
+  unsigned long mask = 1UL << node;
+  long maxnode = 8 * sizeof(mask);
+  if (mbind_sys(ptr, size, MPOL_BIND, &mask, maxnode,
+                MPOL_MF_MOVE | MPOL_MF_STRICT) != 0) {
+    int err = errno;
+    munmap(ptr, size);
+    throw std::runtime_error(std::string("mbind failed: ") + strerror(err));
+  }
+
+  first_touch(ptr, size, hugepages);
+
+  return reinterpret_cast<uintptr_t>(ptr);
+}
+
+uintptr_t alloc_numa_ptr(size_t size, int node) {
+  return _alloc_numa_impl(size, node, false);
+}
+
+void free_numa_ptr(uintptr_t ptr, size_t size) {
+  void* p = reinterpret_cast<void*>(ptr);
+  if (munmap(p, size) != 0) {
+    throw std::runtime_error(std::string("munmap failed: ") + strerror(errno));
+  }
+}
+
+static uintptr_t _alloc_pinned_numa_impl(size_t size, int node,
+                                         bool hugepages) {
+  void* ptr = reinterpret_cast<void*>(_alloc_numa_impl(size, node, hugepages));
+
+  cudaError_t st = cudaHostRegister(ptr, size, 0);
+  if (st != cudaSuccess) {
+    munmap(ptr, size);
+    throw std::runtime_error(std::string("cudaHostRegister failed: ") +
+                             cudaGetErrorString(st));
+  }
+
+  return reinterpret_cast<uintptr_t>(ptr);
+}
+
+uintptr_t alloc_pinned_numa_ptr(size_t size, int node) {
+  return _alloc_pinned_numa_impl(size, node, false);
+}
+
+uintptr_t alloc_hugepage_pinned_numa_ptr(size_t size, int node) {
+  size = _align_hugepage(size);
+  return _alloc_pinned_numa_impl(size, node, true);
+}
+
+void free_pinned_numa_ptr(uintptr_t ptr, size_t size) {
+  void* p = reinterpret_cast<void*>(ptr);
+  // Unpin first, then unmap.
+  cudaError_t st = cudaHostUnregister(p);
+  if (st != cudaSuccess) {
+    munmap(p, size);
+    throw std::runtime_error(std::string("cudaHostUnregister failed: ") +
+                             cudaGetErrorString(st));
+  }
+  if (munmap(p, size) != 0) {
+    throw std::runtime_error(std::string("munmap failed: ") + strerror(errno));
+  }
+}
+
+void free_hugepage_pinned_numa_ptr(uintptr_t ptr, size_t size) {
+  size = _align_hugepage(size);
+  free_pinned_numa_ptr(ptr, size);
+}
+
+uintptr_t alloc_shm_pinned_ptr(size_t size, const std::string& shm_name) {
+  int fd = shm_open(shm_name.c_str(), O_CREAT | O_RDWR, 0600);
+  if (fd < 0)
+    throw std::runtime_error(std::string("shm_open failed: ") +
+                             strerror(errno));
+
+  if (ftruncate(fd, size) != 0) {
+    int err = errno;
+    close(fd);
+    shm_unlink(shm_name.c_str());
+    throw std::runtime_error(std::string("ftruncate failed: ") + strerror(err));
+  }
+
+  void* ptr = mmap(nullptr, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+  close(fd);
+  if (ptr == MAP_FAILED) {
+    shm_unlink(shm_name.c_str());
+    throw std::runtime_error(std::string("mmap failed: ") + strerror(errno));
+  }
+
+  first_touch(ptr, size, false);
+
+  cudaError_t st = cudaHostRegister(ptr, size, 0);
+  if (st != cudaSuccess) {
+    munmap(ptr, size);
+    shm_unlink(shm_name.c_str());
+    throw std::runtime_error(std::string("cudaHostRegister failed: ") +
+                             cudaGetErrorString(st));
+  }
+
+  return reinterpret_cast<uintptr_t>(ptr);
+}
+
+void free_shm_pinned_ptr(uintptr_t ptr, size_t size,
+                         const std::string& shm_name) {
+  void* p = reinterpret_cast<void*>(ptr);
+  cudaError_t st = cudaHostUnregister(p);
+  if (st != cudaSuccess) {
+    munmap(p, size);
+    shm_unlink(shm_name.c_str());
+    throw std::runtime_error(std::string("cudaHostUnregister failed: ") +
+                             cudaGetErrorString(st));
+  }
+  if (munmap(p, size) != 0) {
+    shm_unlink(shm_name.c_str());
+    throw std::runtime_error(std::string("munmap failed: ") + strerror(errno));
+  }
+  shm_unlink(shm_name.c_str());
+}
diff --git a/csrc/mem_alloc.h b/csrc/mem_alloc.h
new file mode 100644
index 0000000..58c83b7
--- /dev/null
+++ b/csrc/mem_alloc.h
@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+uintptr_t alloc_pinned_ptr(size_t size, unsigned int flags);
+uintptr_t alloc_numa_ptr(size_t size, int node);
+uintptr_t alloc_pinned_numa_ptr(size_t size, int node);
+uintptr_t alloc_shm_pinned_ptr(size_t size, const std::string& shm_name);
+void batched_memcpy(const std::vector<uintptr_t>& src_ptrs,
+                    const std::vector<uintptr_t>& dst_ptrs,
+                    const std::vector<size_t>& sizes);
+
+void free_pinned_ptr(uintptr_t ptr);
+void free_numa_ptr(uintptr_t ptr, size_t size);
+void free_pinned_numa_ptr(uintptr_t ptr, size_t size);
+void free_shm_pinned_ptr(uintptr_t ptr, size_t size,
+                         const std::string& shm_name);
+
+// Hugepage variants (MAP_HUGETLB). Not available for shm: /dev/shm usually
+// uses tmpfs, and tmpfs does not support MAP_HUGETLB.
+uintptr_t alloc_hugepage_pinned_ptr(size_t size, unsigned int flags);
+uintptr_t alloc_hugepage_pinned_numa_ptr(size_t size, int node);
+
+void free_hugepage_pinned_ptr(uintptr_t ptr, size_t size);
+void free_hugepage_pinned_numa_ptr(uintptr_t ptr, size_t size);
diff --git a/csrc/mem_kernels.cu b/csrc/mem_kernels.cu
new file mode 100644
index 0000000..a257573
--- /dev/null
+++ b/csrc/mem_kernels.cu
@@ -0,0 +1,1091 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <torch/all.h>
+#include <c10/cuda/CUDAGuard.h>
+#include "mem_kernels.cuh"
+#include <ATen/ATen.h>
+#include <ATen/cuda/CUDAContext.h>
+#include <algorithm>
+#ifdef USE_ROCM
+  #include <hip/hip_fp8.h>
+#else
+  #include <cuda_fp8.h>
+#endif
+
+#ifndef CHECK_CUDA_CALL
+  #define CHECK_CUDA_CALL(call)                                             \
+    do {                                                                    \
+      cudaError_t err = call;                                               \
+      if (err != cudaSuccess) {                                             \
+        fprintf(stderr, "CUDA error in file '%s' in line %i : %s.\n",       \
+                __FILE__, __LINE__, cudaGetErrorString(err));               \
+        throw std::runtime_error(                                           \
+            std::string("CUDA error in file '") + __FILE__ + "' in line " + \
+            std::to_string(__LINE__) + " : " + cudaGetErrorString(err));    \
+      }                                                                     \
+    } while (0)
+#endif
+
+namespace lmc {
+
+// inline helper to check HND layout (callable from device and host)
+__host__ __device__ __forceinline__ bool is_hnd(
+    const EngineKVFormat engine_kv_format) {
+  return engine_kv_format ==
+             EngineKVFormat::NL_X_TWO_NB_NH_BS_HS ||  // flash attn HND
+         engine_kv_format ==
+             EngineKVFormat::NL_X_NB_TWO_NH_BS_HS;  // flash infer HND
+}
+
+// All paged (non-MLA) formats rely on block_size for offset computation.
+inline void check_block_size(const EngineKVFormat engine_kv_format,
+                             const int block_size) {
+  TORCH_CHECK(is_mla(engine_kv_format) || block_size > 0,
+              "block_size is required (must be > 0) for EngineKVFormat ",
+              static_cast<int>(engine_kv_format));
+}
+
+// HND formats additionally need head_size to decompose scalar offsets.
+inline void check_head_size(const EngineKVFormat engine_kv_format,
+                            const int head_size) {
+  TORCH_CHECK(!is_hnd(engine_kv_format) || head_size > 0,
+              "head_size is required (must be > 0) for EngineKVFormat ",
+              static_cast<int>(engine_kv_format));
+}
+
+template <typename scalar_t>
+__global__ void load_and_reshape_flash_kernel(
+    scalar_t* __restrict__ key_value,  // [num_tokens, num_heads, head_size]
+    const scalar_t* __restrict__ key_cache,    // [num_blocks, block_size,
+                                               // num_heads, head_size]
+    const scalar_t* __restrict__ value_cache,  // [num_blocks, block_size,
+                                               // num_heads, head_size]
+    const int64_t* __restrict__ slot_mapping,  // [num_tokens]
+    const int block_stride_in_64bit, const int key_value_stride,
+    const int num_heads, const int head_size_in_64bit, const int block_size,
+    const int key_layer_offset, const int value_layer_offset) {
+  const int64_t token_idx = blockIdx.x;
+  const int64_t slot_idx = slot_mapping[token_idx];
+
+  if (slot_idx < 0) {
+    return;
+  }
+
+  const int64_t block_idx = slot_idx / block_size;
+  const int64_t block_offset = slot_idx % block_size;
+  const int n = num_heads * head_size_in_64bit;
+
+  for (int i = threadIdx.x; i < n; i += blockDim.x) {
+    const int64_t tgt_key_idx =
+        key_layer_offset + token_idx * key_value_stride + i;
+    const int64_t tgt_value_idx =
+        value_layer_offset + token_idx * key_value_stride + i;
+
+    const int head_idx = i / head_size_in_64bit;
+    const int head_offset = i % head_size_in_64bit;
+    const int64_t src_key_value_idx =
+        block_idx * block_stride_in_64bit +
+        block_offset * num_heads * head_size_in_64bit +
+        head_idx * head_size_in_64bit + head_offset;
+
+    scalar_t tgt_key = key_cache[src_key_value_idx];
+    scalar_t tgt_value = value_cache[src_key_value_idx];
+
+    key_value[tgt_key_idx] = tgt_key;
+    key_value[tgt_value_idx] = tgt_value;
+  }
+}
+
+template <typename scalar_t>
+__global__ void reshape_and_cache_back_flash_kernel(
+    const scalar_t* __restrict__ key_value,  // [num_tokens, num_heads,
+                                             // head_size]
+    scalar_t* __restrict__ key_cache,    // [num_blocks, block_size, num_heads,
+                                         // head_size]
+    scalar_t* __restrict__ value_cache,  // [num_blocks, block_size, num_heads,
+                                         // head_size]
+    const int64_t* __restrict__ slot_mapping,  // [num_tokens]
+    const int block_stride_in_64bit, const int key_value_stride,
+    const int num_heads, const int head_size_in_64bit, const int block_size,
+    const int key_layer_offset, const int value_layer_offset) {
+  const int64_t token_idx = blockIdx.x;
+  const int64_t slot_idx = slot_mapping[token_idx];
+
+  if (slot_idx < 0) {
+    return;
+  }
+
+  const int64_t block_idx = slot_idx / block_size;
+  const int64_t block_offset = slot_idx % block_size;
+  const int n = num_heads * head_size_in_64bit;
+
+  for (int i = threadIdx.x; i < n; i += blockDim.x) {
+    const int64_t tgt_key_idx =
+        key_layer_offset + token_idx * key_value_stride + i;
+    const int64_t tgt_value_idx =
+        value_layer_offset + token_idx * key_value_stride + i;
+
+    const int head_idx = i / head_size_in_64bit;
+    const int head_offset = i % head_size_in_64bit;
+    const int64_t src_key_value_idx =
+        block_idx * block_stride_in_64bit +
+        block_offset * num_heads * head_size_in_64bit +
+        head_idx * head_size_in_64bit + head_offset;
+
+    scalar_t tgt_key = key_value[tgt_key_idx];
+    scalar_t tgt_value = key_value[tgt_value_idx];
+
+    key_cache[src_key_value_idx] = tgt_key;
+    value_cache[src_key_value_idx] = tgt_value;
+  }
+}
+
+template <typename scalar_t, EngineKVFormat format>
+__global__ void single_layer_kv_transfer_kernel(
+    scalar_t* __restrict__ lmc_key_value_cache,
+    scalar_t* __restrict__ vllm_key_value_cache,
+    const int64_t* __restrict__ slot_mapping,  // [num_tokens]
+    const int vllm_block_key_stride_in_64bit, const int vllm_value_offset,
+    const int lmc_stride, const int lmc_value_offset, const int num_heads,
+    const int head_size_in_64bit, const int block_size,
+    const TransferDirection direction) {
+  constexpr bool USE_MLA = (format == EngineKVFormat::NL_X_NB_BS_HS);
+  constexpr bool HND_LAYOUT = (format == EngineKVFormat::NL_X_TWO_NB_NH_BS_HS ||
+                               format == EngineKVFormat::NL_X_NB_TWO_NH_BS_HS);
+
+  const int64_t token_idx = blockIdx.x;
+  const int64_t slot_idx = slot_mapping[token_idx];
+
+  if (slot_idx < 0) {
+    return;
+  }
+
+  const int64_t block_idx = slot_idx / block_size;
+  const int64_t block_offset = slot_idx % block_size;
+  const int n = num_heads * head_size_in_64bit;
+
+  for (int i = threadIdx.x; i < n; i += blockDim.x) {
+    const int64_t lmc_key_idx = token_idx * lmc_stride + i;
+
+    const int head_idx = i / head_size_in_64bit;
+    const int head_offset = i % head_size_in_64bit;
+
+    int64_t vllm_key_idx;
+    if constexpr (HND_LAYOUT) {
+      // HND layout: [..., num_heads, block_size, head_size]
+      vllm_key_idx = block_idx * vllm_block_key_stride_in_64bit +
+                     head_idx * block_size * head_size_in_64bit +
+                     block_offset * head_size_in_64bit + head_offset;
+    } else {
+      // NHD layout: [..., block_size, num_heads, head_size]
+      // (also correct for MLA where num_heads==1)
+      vllm_key_idx = block_idx * vllm_block_key_stride_in_64bit +
+                     block_offset * num_heads * head_size_in_64bit +
+                     head_idx * head_size_in_64bit + head_offset;
+    }
+
+    if (direction == TransferDirection::D2H) {
+      // GPU to LMCache
+      lmc_key_value_cache[lmc_key_idx] = vllm_key_value_cache[vllm_key_idx];
+      if constexpr (!USE_MLA) {
+        const int64_t lmc_value_idx = lmc_key_idx + lmc_value_offset;
+        const int64_t vllm_value_idx = vllm_key_idx + vllm_value_offset;
+        lmc_key_value_cache[lmc_value_idx] =
+            vllm_key_value_cache[vllm_value_idx];
+      }
+    } else {
+      // LMCache to GPU
+      vllm_key_value_cache[vllm_key_idx] = lmc_key_value_cache[lmc_key_idx];
+      if constexpr (!USE_MLA) {
+        const int64_t lmc_value_idx = lmc_key_idx + lmc_value_offset;
+        const int64_t vllm_value_idx = vllm_key_idx + vllm_value_offset;
+        vllm_key_value_cache[vllm_value_idx] =
+            lmc_key_value_cache[lmc_value_idx];
+      }
+    }
+  }
+}
+
+template <EngineKVFormat format>
+__device__ __forceinline__ int64_t page_buffer_offset(
+    const int k_or_v, const int token_idx, const int scalar_offset,
+    const int scalars_per_token, const int page_buffer_size,
+    const int block_size, const int head_size) {
+  /*
+  logical semantics of arguments (agnostic to physical format):
+  k_or_v:            0 for key, 1 for value
+  token_idx:         flat slot index from slot_mapping[] = block_id * block_size
+  + offset_in_block scalar_offset:     thread-loop index in [0,
+  scalars_per_token), flat offset within one token's data (NH*HS in xword units)
+  scalars_per_token: NH * HS in xword units — total data elements per token slot
+  page_buffer_size:  NB * BS — total token slots in the paged buffer
+  block_size:        BS — number of token slots per block
+  head_size:         HS in xword units — only used by HND formats to decompose
+  scalar_offset into (head_idx, head_offset)
+
+  The job of page_buffer_offset is to translate these logical arguments into a
+  physical address based on the EngineKVFormat.
+
+  NOTE(perf): For HND formats, threads within a warp access non-contiguous
+  addresses when crossing head boundaries (stride BS*HS between heads),
+  harming memory coalescing
+  TODO: A dedicated HND kernel could launch with
+  grid=(2, L, T*NH) thread=(HS,,) to keep warps within one head's contiguous
+  HS run
+  However, most models have head_size = 128 using bf16 or fp16 which is 256
+  bytes when divided by xwords (8 bytes) is exactly 32 xwords which fits one
+  warp Worst case if HS is smaller or quantization is smaller, we will have to
+  make two vectorized loads per warp that are BS * HS (the head stride) apart
+  */
+
+  // vllm cross layer
+  if constexpr (format == EngineKVFormat::NB_NL_TWO_BS_NH_HS) {
+    return k_or_v * page_buffer_size * scalars_per_token +
+           token_idx * scalars_per_token + scalar_offset;
+  }
+  // vllm flash attention (NHD)
+  else if constexpr (format == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS) {
+    return k_or_v * page_buffer_size * scalars_per_token +
+           token_idx * scalars_per_token + scalar_offset;
+  }
+  // vllm flash infer (NHD)
+  else if constexpr (format == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS) {
+    const int block_idx = token_idx / block_size;
+    const int block_offset = token_idx % block_size;
+    return block_idx * 2 * block_size * scalars_per_token +
+           k_or_v * block_size * scalars_per_token +
+           block_offset * scalars_per_token + scalar_offset;
+  }
+  // MLA formats: vLLM (NL_X_NB_BS_HS) and SGLang (NL_X_NBBS_ONE_HS)
+  else if constexpr (format == EngineKVFormat::NL_X_NB_BS_HS ||
+                     format == EngineKVFormat::NL_X_NBBS_ONE_HS) {
+    return token_idx * scalars_per_token + scalar_offset;
+  }
+  // vllm flash attention (HND) — physical: [2, NB, NH, BS, HS]
+  else if constexpr (format == EngineKVFormat::NL_X_TWO_NB_NH_BS_HS) {
+    const int block_idx = token_idx / block_size;
+    const int block_offset = token_idx % block_size;
+    const int head_idx = scalar_offset / head_size;
+    const int head_offset = scalar_offset % head_size;
+    const int num_heads = scalars_per_token / head_size;
+    return k_or_v * page_buffer_size * scalars_per_token +
+           block_idx * num_heads * block_size * head_size +
+           head_idx * block_size * head_size + block_offset * head_size +
+           head_offset;
+  }
+  // vllm flash infer (HND) — physical: [NB, 2, NH, BS, HS]
+  else if constexpr (format == EngineKVFormat::NL_X_NB_TWO_NH_BS_HS) {
+    const int block_idx = token_idx / block_size;
+    const int block_offset = token_idx % block_size;
+    const int head_idx = scalar_offset / head_size;
+    const int head_offset = scalar_offset % head_size;
+    const int num_heads = scalars_per_token / head_size;
+    return block_idx * 2 * num_heads * block_size * head_size +
+           k_or_v * num_heads * block_size * head_size +
+           head_idx * block_size * head_size + block_offset * head_size +
+           head_offset;
+  }
+}
+
+__device__ __forceinline__ int64_t page_buffer_offset_unilateral(
+    const int token_idx, const int scalar_offset, const int scalars_per_token) {
+  return token_idx * scalars_per_token + scalar_offset;
+}
+
+__device__ __forceinline__ int64_t
+key_value_offset(const int k_or_v, const int layer_idx, const int token_idx,
+                 const int scalar_offset, const int scalars_per_token,
+                 const int num_tokens, const int num_layers) {
+  return k_or_v * num_layers * num_tokens * scalars_per_token +
+         layer_idx * num_tokens * scalars_per_token +
+         token_idx * scalars_per_token + scalar_offset;
+}
+
+template <typename scalar_t>
+__global__ void single_layer_kv_transfer_sgl_kernel(
+    // scalar_t* __restrict__ lmc_key_cache,    // [num_tokens,
+    // num_heads*head_size] scalar_t* __restrict__ lmc_value_cache,  //
+    // [num_tokens, num_heads*head_size]
+    scalar_t* __restrict__ lmc_key_value_cache,  // [num_tokens, 2,
+                                                 // num_heads*head_size]
+                                                 // or
+                                                 // [2, num_tokens,
+                                                 // num_heads*head_size]
+    scalar_t* __restrict__ sgl_key_cache,        // [num_blocks, block_size,
+                                                 // num_heads, head_size]
+    scalar_t* __restrict__ sgl_value_cache,      // [num_blocks, block_size,
+                                                 // num_heads, head_size]
+    const int64_t* __restrict__ slot_mapping,    // [num_tokens]
+    const int block_stride_in_64bit, const int lmc_stride,
+    const int lmc_value_offset, const int num_heads,
+    const int head_size_in_64bit, const int block_size,
+    const TransferDirection direction) {
+  const int64_t token_idx = blockIdx.x;
+  const int64_t slot_idx = slot_mapping[token_idx];
+
+  if (slot_idx < 0) {
+    return;
+  }
+
+  const int64_t block_idx = slot_idx / block_size;
+  const int64_t block_offset = slot_idx % block_size;
+  const int n = num_heads * head_size_in_64bit;
+
+  for (int i = threadIdx.x; i < n; i += blockDim.x) {
+    const int64_t lmc_key_idx = token_idx * lmc_stride + i;
+    const int64_t lmc_value_idx = lmc_key_idx + lmc_value_offset;
+
+    const int head_idx = i / head_size_in_64bit;
+    const int head_offset = i % head_size_in_64bit;
+    const int64_t sgl_key_value_idx =
+        block_idx * block_stride_in_64bit +
+        block_offset * num_heads * head_size_in_64bit +
+        head_idx * head_size_in_64bit + head_offset;
+
+    if (direction == TransferDirection::D2H) {
+      lmc_key_value_cache[lmc_key_idx] = sgl_key_cache[sgl_key_value_idx];
+      lmc_key_value_cache[lmc_value_idx] = sgl_value_cache[sgl_key_value_idx];
+    } else {  // direction == TransferDirection::H2D
+      sgl_key_cache[sgl_key_value_idx] = lmc_key_value_cache[lmc_key_idx];
+      sgl_value_cache[sgl_key_value_idx] = lmc_key_value_cache[lmc_value_idx];
+    }
+  }
+}
+
+/**
+ * Quickly load KV cache between vLLM paged memory and offloading buffer
+ * slot_id = slot_mapping[block.x]
+ * key_value[block.z, block.y, block.x, thread.x] <=> ptrs[block.y][block.z,
+ * slot_id, thread.x]
+ */
+template <typename scalar_t, bool DIRECTION, EngineKVFormat format>
+__global__ void load_and_reshape_multi_layer_kernel(
+    scalar_t* __restrict__ key_value,           // [2, num_layer, num_tokens,
+                                                // scalars_per_token]
+    scalar_t** __restrict__ paged_buffer_ptrs,  // [num_layers] * [2,
+                                                // PAGE_BUFFER_SIZE,
+                                                // scalars_per_token]
+                                                // or
+                                                // [num_layers] * [num_blocks,
+                                                // 2, block_size,
+                                                // scalars_per_token]
+    const int64_t* __restrict__ slot_mapping,   // [num_tokens]
+    const int scalars_per_token, const int num_tokens, const int num_layers,
+    const int page_buffer_size, const int block_size, const int head_size,
+    const int skip_prefix_n_tokens) {
+  const int token_id = blockIdx.x;
+  const int layer_id = blockIdx.y;
+  const int k_or_v = blockIdx.z;
+  const int tid = threadIdx.x;
+  const int num_threads = blockDim.x;
+
+  const int kv_token_id = token_id + skip_prefix_n_tokens;
+  const int64_t slot_idx = slot_mapping[kv_token_id];
+  scalar_t* paged_buffer_ptr = paged_buffer_ptrs[layer_id];
+
+  if (slot_idx < 0) {
+    return;
+  }
+
+  /** Copy the data from page buffer to key_value **/
+  for (int i = tid; i < scalars_per_token; i += num_threads) {
+    const int64_t lmcache_offset =
+        key_value_offset(k_or_v, layer_id, kv_token_id, i, scalars_per_token,
+                         num_tokens, num_layers);
+
+    const int64_t vllm_offset =
+        page_buffer_offset<format>(k_or_v, slot_idx, i, scalars_per_token,
+                                   page_buffer_size, block_size, head_size);
+
+    if (DIRECTION)  // 1 is paged buffer to LMCache
+      key_value[lmcache_offset] = paged_buffer_ptr[vllm_offset];
+    else  // 0 is LMCache to paged buffer
+      paged_buffer_ptr[vllm_offset] = key_value[lmcache_offset];
+  }
+}
+
+/*
+ * handle sglang MHA offload between CPU and GPU
+ * DIRECTION = 1 (true) means paged buffer to LMCache (D2H)
+ * DIRECTION = 0 (false) means LMCache to paged buffer (H2D)
+ */
+template <typename scalar_t, bool DIRECTION>
+__global__ void load_and_reshape_multi_layer_kernel_unilateral(
+    scalar_t* __restrict__ key_value,           // [2, num_layer, num_tokens,
+                                                // scalars_per_token]
+    scalar_t** __restrict__ paged_buffer_ptrs,  // [num_layers *2] *
+                                                // [PAGE_BUFFER_SIZE,
+                                                // scalars_per_token]
+    const int64_t* __restrict__ slot_mapping,   // [num_tokens]
+    const int scalars_per_token, const int num_tokens, const int num_layers,
+    const int page_buffer_size) {
+  const int token_id = blockIdx.x;
+  const int layer_id = blockIdx.y;
+  const int k_or_v = blockIdx.z;
+  const int tid = threadIdx.x;
+  const int num_threads = blockDim.x;
+
+  const int64_t slot_idx = slot_mapping[token_id];
+  scalar_t* key_ptr = paged_buffer_ptrs[layer_id];
+  scalar_t* value_ptr = paged_buffer_ptrs[layer_id + num_layers];
+
+  if (slot_idx < 0) {
+    return;
+  }
+
+  /** Copy the data from page buffer to key_value **/
+  for (int i = tid; i < scalars_per_token; i += num_threads) {
+    const int64_t lmcache_offset =
+        key_value_offset(k_or_v, layer_id, token_id, i, scalars_per_token,
+                         num_tokens, num_layers);
+
+    const int64_t sgl_offset =
+        page_buffer_offset_unilateral(slot_idx, i, scalars_per_token);
+
+    if (k_or_v == 0) {
+      if (DIRECTION)  // 1 is paged buffer to LMCache
+        key_value[lmcache_offset] = key_ptr[sgl_offset];
+      else  // 0 is LMCache to paged buffer
+        key_ptr[sgl_offset] = key_value[lmcache_offset];
+    } else {
+      if (DIRECTION)  // 1 is paged buffer to LMCache
+        key_value[lmcache_offset] = value_ptr[sgl_offset];
+      else  // 0 is LMCache to paged buffer
+        value_ptr[sgl_offset] = key_value[lmcache_offset];
+    }
+  }
+}
+
+}  // namespace lmc
+
+template <typename T, typename TENSOR_TYPE>
+T* get_kernel_ptr(TENSOR_TYPE& tensor) {
+  // Get the kernel-accessible pointer of the given type T
+  // Returns NULL if the tensor is on CPU and non-pinned
+  torch::Device device = tensor.device();
+  if (device.is_cuda()) {
+    return static_cast<T*>(tensor.data_ptr());
+  } else if (device.is_cpu()) {
+    T* ptr;
+    auto st = cudaHostGetDevicePointer(
+        (void**)&ptr, static_cast<void*>(tensor.data_ptr()), 0);
+    TORCH_CHECK(st == cudaSuccess,
+                "Host tensor not registered/pinned (or bad ptr)");
+    return ptr;
+  } else {
+    TORCH_CHECK(false, "Invalid device. Device must be cuda or pinned cpu.");
+  }
+}
+
+/**
+ * Quickly offload KV cache from vLLM paged memory to the offloading buffer
+ * Processes all the layers at the same time
+ *
+ * Each layer in vLLM's KV buffer has a shape of
+ * [2, PAGE_BUFFER_SIZE, num_heads*head_size]
+ *
+ * Each thread block processes the copy for a token
+ * The grid size should be (num_tokens, num_layers, 2)
+ *
+ * Therefore:
+ *  - k/v -- block.z
+ *  - layer id -- block.y
+ *  - token id -- block.x
+ *  - offset within a token -- thread.x
+ *
+ * The function does:
+ * slot_id = slot_mapping[block.x]
+ * key_value[block.z, block.y, block.x, thread.x] = ptrs[block.y][block.z,
+ * slot_id, thread.x]
+ *
+ * Param:
+ *  - direction: H2D  means LMCache to PagedBuffer, D2H  means PagedBuffer to
+ * LMCache
+ */
+#define LAUNCH_KERNEL_WITH_FORMAT(T, DIRECTION, FORMAT)                      \
+  lmc::load_and_reshape_multi_layer_kernel<T, DIRECTION, FORMAT>             \
+      <<<grid, block, 0, stream>>>(key_value_ptr, page_buffer_ptrs,          \
+                                   slot_mapping_ptr, num_xwords, num_tokens, \
+                                   num_layers, page_buffer_size, block_size, \
+                                   head_size_xword, skip_prefix_n_tokens);   \
+  C10_CUDA_KERNEL_LAUNCH_CHECK();
+
+template <typename T>
+void multi_layer_kv_transfer_templated(
+    torch::Tensor&
+        key_value,  // key/value must be on gpu/pinned cpu.
+                    // [2, num_layer, num_tokens, num_heads*head_size] for
+                    // flash_attn.
+                    // [1, num_layer, num_tokens, aligned_head_size]
+                    // for MLA.
+    const torch::Tensor& key_value_ptrs,  // [num_layers]
+    const torch::Tensor& slot_mapping,    // [num_tokens],
+    const torch::Device& paged_memory_device, const int page_buffer_size,
+    const TransferDirection direction, const EngineKVFormat engine_kv_format,
+    const int block_size, const int head_size, const int skip_prefix_n_tokens) {
+  T* key_value_ptr = get_kernel_ptr<T, torch::Tensor>(key_value);
+  T** page_buffer_ptrs =
+      get_kernel_ptr<T*, const torch::Tensor>(key_value_ptrs);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int num_layers = key_value.size(1);
+  int num_tokens = key_value.size(2);
+  int num_transfer_tokens = num_tokens - skip_prefix_n_tokens;
+  int num_origin_elements = key_value.size(3);
+  int elements_per_xword = sizeof(T) / key_value.element_size();
+  int num_xwords = num_origin_elements / elements_per_xword;
+  // head_size is in element units
+  // convert to xword units
+  // to match scalars_per_token (num_xwords) which is also in xword units.
+  int head_size_xword = head_size > 0 ? head_size / elements_per_xword : 0;
+
+  lmc::check_block_size(engine_kv_format, block_size);
+  lmc::check_head_size(engine_kv_format, head_size_xword);
+
+  int k_or_v_size = ::is_mla(engine_kv_format) ? 1 : 2;
+
+  dim3 grid(num_transfer_tokens, num_layers, k_or_v_size);
+  dim3 block(std::min(num_xwords, 128));
+
+  const at::cuda::OptionalCUDAGuard device_guard(paged_memory_device);
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  if (direction == TransferDirection::H2D) {
+    switch (engine_kv_format) {
+      case EngineKVFormat::NB_NL_TWO_BS_NH_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false, EngineKVFormat::NB_NL_TWO_BS_NH_HS);
+        break;
+      case EngineKVFormat::NL_X_TWO_NB_BS_NH_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false,
+                                  EngineKVFormat::NL_X_TWO_NB_BS_NH_HS);
+        break;
+      case EngineKVFormat::NL_X_NB_TWO_BS_NH_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false,
+                                  EngineKVFormat::NL_X_NB_TWO_BS_NH_HS);
+        break;
+      case EngineKVFormat::NL_X_NB_BS_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false, EngineKVFormat::NL_X_NB_BS_HS);
+        break;
+      case EngineKVFormat::NL_X_NBBS_ONE_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false, EngineKVFormat::NL_X_NBBS_ONE_HS);
+        break;
+      case EngineKVFormat::NL_X_TWO_NB_NH_BS_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false,
+                                  EngineKVFormat::NL_X_TWO_NB_NH_BS_HS);
+        break;
+      case EngineKVFormat::NL_X_NB_TWO_NH_BS_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, false,
+                                  EngineKVFormat::NL_X_NB_TWO_NH_BS_HS);
+        break;
+      default:
+        throw std::runtime_error("Unsupported EngineKVFormat");
+    }
+  } else {
+    switch (engine_kv_format) {
+      case EngineKVFormat::NB_NL_TWO_BS_NH_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true, EngineKVFormat::NB_NL_TWO_BS_NH_HS);
+        break;
+      case EngineKVFormat::NL_X_TWO_NB_BS_NH_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true,
+                                  EngineKVFormat::NL_X_TWO_NB_BS_NH_HS);
+        break;
+      case EngineKVFormat::NL_X_NB_TWO_BS_NH_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true,
+                                  EngineKVFormat::NL_X_NB_TWO_BS_NH_HS);
+        break;
+      case EngineKVFormat::NL_X_NB_BS_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true, EngineKVFormat::NL_X_NB_BS_HS);
+        break;
+      case EngineKVFormat::NL_X_NBBS_ONE_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true, EngineKVFormat::NL_X_NBBS_ONE_HS);
+        break;
+      case EngineKVFormat::NL_X_TWO_NB_NH_BS_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true,
+                                  EngineKVFormat::NL_X_TWO_NB_NH_BS_HS);
+        break;
+      case EngineKVFormat::NL_X_NB_TWO_NH_BS_HS:
+        LAUNCH_KERNEL_WITH_FORMAT(T, true,
+                                  EngineKVFormat::NL_X_NB_TWO_NH_BS_HS);
+        break;
+      default:
+        throw std::runtime_error("Unsupported EngineKVFormat");
+    }
+  }
+}
+
+#undef LAUNCH_KERNEL_WITH_FORMAT
+
+/**
+ * @see multi_layer_kv_transfer_templated
+ */
+void multi_layer_kv_transfer(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format, const int block_size,
+    const int head_size, const int skip_prefix_n_tokens) {
+  int num_origin_elements = key_value.size(3);
+  int copy_size = num_origin_elements * key_value.element_size();
+#ifndef LAUNCH_MULTI_LAYER_KV_TRANSFER
+  #define LAUNCH_MULTI_LAYER_KV_TRANSFER(type)                          \
+    do {                                                                \
+      multi_layer_kv_transfer_templated<type>(                          \
+          key_value, key_value_ptrs, slot_mapping, paged_memory_device, \
+          page_buffer_size, direction, engine_kv_format, block_size,    \
+          head_size, skip_prefix_n_tokens);                             \
+    } while (0)
+#endif
+  if (copy_size % 8 == 0) {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int64_t);
+  } else if (copy_size % 4 == 0) {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int32_t);
+  } else if (copy_size % 2 == 0) {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int16_t);
+  } else {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int8_t);
+  }
+#undef LAUNCH_MULTI_LAYER_KV_TRANSFER
+}
+
+/**
+ * Quickly offload KV cache from SGLang paged memory to the offloading buffer
+ * Processes all the layers at the same time
+ *
+ * Each layer in SGLang's K/V buffer has a shape of
+ * [PAGE_BUFFER_SIZE, num_heads*head_size]
+ *
+ * Each thread block processes the copy for a token
+ * The grid size should be (num_tokens, num_layers, 2)
+ *
+ * Therefore:
+ *  - k/v -- block.z
+ *  - layer id -- block.y
+ *  - token id -- block.x
+ *  - offset within a token -- thread.x
+ *
+ * The function does:
+ * slot_id = slot_mapping[block.x]
+ * key_value[block.z, block.y, block.x, thread.x] = ptrs[block.y][block.z,
+ * slot_id, thread.x]
+ *
+ * Param:
+ *  - direction: H2D  means LMCache to PagedBuffer, D2H  means PagedBuffer to
+ * LMCache
+ */
+void multi_layer_kv_transfer_unilateral(
+    torch::Tensor&
+        key_value,  // [2, num_layer, num_tokens, num_heads*head_size] for
+                    // flash_attn [1, num_layer, num_tokens, aligned_head_size]
+                    // for MLA key/value must be on gpu/pinned cpu
+
+    const torch::Tensor& key_value_ptrs,  // [num_layers*2]
+    const torch::Tensor& slot_mapping,    // [num_tokens],
+    const torch::Device& paged_memory_device, const int page_buffer_size,
+    const TransferDirection direction, const EngineKVFormat engine_kv_format) {
+  const bool use_mla = ::is_mla(engine_kv_format);
+  // MLA case collapses back to multi_layer_kv_transfer
+  // (vLLM and SGLang indexing are compatible)
+  if (use_mla) {
+    return multi_layer_kv_transfer(key_value, key_value_ptrs, slot_mapping,
+                                   paged_memory_device, page_buffer_size,
+                                   direction, engine_kv_format);
+  }
+
+  int64_t* key_value_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_value);
+  int64_t** page_buffer_ptrs =
+      get_kernel_ptr<int64_t*, const torch::Tensor>(key_value_ptrs);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int num_layers = key_value.size(1);
+  int num_tokens = slot_mapping.size(0);
+  int num_origin_elements = key_value.size(3);
+  int elements_per_qword = 8 / key_value.element_size();
+  int num_qwords = num_origin_elements / elements_per_qword;
+
+  int k_or_v_size = 2;
+
+  dim3 grid(key_value.size(2), key_value.size(1), k_or_v_size);
+  dim3 block(std::min(num_qwords, 128));
+
+  const at::cuda::OptionalCUDAGuard device_guard(paged_memory_device);
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  if (direction == TransferDirection::H2D) {
+    lmc::load_and_reshape_multi_layer_kernel_unilateral<int64_t, false>
+        <<<grid, block, 0, stream>>>(key_value_ptr, page_buffer_ptrs,
+                                     slot_mapping_ptr, num_qwords, num_tokens,
+                                     num_layers, page_buffer_size);
+    C10_CUDA_KERNEL_LAUNCH_CHECK();
+  } else {
+    lmc::load_and_reshape_multi_layer_kernel_unilateral<int64_t, true>
+        <<<grid, block, 0, stream>>>(key_value_ptr, page_buffer_ptrs,
+                                     slot_mapping_ptr, num_qwords, num_tokens,
+                                     num_layers, page_buffer_size);
+    C10_CUDA_KERNEL_LAUNCH_CHECK();
+  }
+}
+
+void single_layer_kv_transfer(
+    // torch::Tensor& lmc_key_cache,  // [num_tokens, num_heads*head_size]
+    //  key/value must be on gpu/pinned cpu
+    // torch::Tensor& lmc_value_cache,  // [num_tokens, num_heads*head_size]
+
+    torch::Tensor& lmc_key_value_cache,  // [num_tokens, 2, num_heads*head_size]
+                                         // or
+                                         // [2, num_tokens, num_heads*head_size]
+                                         // or for MLA:
+                                         // [num_tokens, aligned_head_size]
+
+    // torch::Tensor&
+    //     vllm_key_cache,  // [num_blocks, block_size, num_heads, head_size]
+    // torch::Tensor&
+    //     vllm_value_cache,  // [num_blocks, block_size, num_heads, head_size]
+    //  key_cache/value_cache must be on gpu
+    torch::Tensor&
+        vllm_key_value_cache,  // NHD: [2, num_blocks, block_size, num_heads,
+                               //       head_size] for flash attention
+                               //      [num_blocks, 2, block_size, num_heads,
+                               //       head_size] for flash infer
+                               // HND: [2, num_blocks, num_heads, block_size,
+                               //       head_size] for flash attention
+                               //      [num_blocks, 2, num_heads, block_size,
+                               //       head_size] for flash infer
+                               // MLA: [num_blocks, block_size, head_size]
+
+    torch::Tensor& slot_mapping,  // [num_tokens]
+    const TransferDirection direction, const EngineKVFormat engine_kv_format,
+    const bool token_major  // true: lmc_key_value_cache is
+                            // [num_tokens, 2, num_heads*head_size]
+                            // false: lmc_key_value_cache is
+                            // [2, num_tokens, num_heads*head_size]
+) {
+  // int64_t* lmc_key_cache_ptr = get_kernel_ptr<int64_t,
+  // torch::Tensor>(lmc_key_cache); int64_t* lmc_value_cache_ptr =
+  // get_kernel_ptr<int64_t, torch::Tensor>(lmc_value_cache);
+  int64_t* lmc_key_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(lmc_key_value_cache);
+
+  int64_t* vllm_key_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(vllm_key_value_cache);
+  // int64_t* vllm_value_cache_ptr =
+  //     get_kernel_ptr<int64_t, torch::Tensor>(vllm_value_cache);
+
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / vllm_key_value_cache.element_size();
+
+  int num_tokens = slot_mapping.size(0);
+  int num_heads;
+  int head_size_in_64bit;
+  int block_size;
+
+  const bool use_mla = ::is_mla(engine_kv_format);
+  const bool hnd_layout = lmc::is_hnd(engine_kv_format);
+
+  if (use_mla) {
+    // MLA format: [num_blocks, block_size, head_size]
+    num_heads = 1;
+    block_size = vllm_key_value_cache.size(1);
+    head_size_in_64bit = vllm_key_value_cache.size(2) / elements_per_entry;
+  } else if (hnd_layout) {
+    // HND format: [..., num_heads, block_size, head_size]
+    num_heads = vllm_key_value_cache.size(2);
+    block_size = vllm_key_value_cache.size(3);
+    head_size_in_64bit = vllm_key_value_cache.size(4) / elements_per_entry;
+  } else {
+    // NHD format: [..., block_size, num_heads, head_size]
+    block_size = vllm_key_value_cache.size(2);
+    num_heads = vllm_key_value_cache.size(3);
+    head_size_in_64bit = vllm_key_value_cache.size(4) / elements_per_entry;
+  }
+
+  lmc::check_block_size(engine_kv_format, block_size);
+  lmc::check_head_size(engine_kv_format, head_size_in_64bit);
+
+  int lmc_stride;
+  int lmc_value_offset;
+  if (use_mla) {
+    // MLA format: [num_tokens, aligned_head_size]
+    lmc_stride = lmc_key_value_cache.stride(0) / elements_per_entry;
+    lmc_value_offset = 0;  // No separate K/V for MLA
+  } else if (token_major) {
+    lmc_stride = lmc_key_value_cache.stride(0) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(1) / elements_per_entry;
+  } else {
+    lmc_stride = lmc_key_value_cache.stride(1) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(0) / elements_per_entry;
+  }
+
+  int vllm_block_key_stride_in_64bit;
+  int vllm_value_offset;
+  if (use_mla) {
+    // MLA format: [num_blocks, block_size, head_size]
+    vllm_block_key_stride_in_64bit =
+        vllm_key_value_cache.stride(0) / elements_per_entry;
+    vllm_value_offset = 0;  // No separate K/V for MLA
+  } else if (engine_kv_format == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS ||
+             engine_kv_format == EngineKVFormat::NL_X_TWO_NB_NH_BS_HS) {
+    vllm_block_key_stride_in_64bit =
+        vllm_key_value_cache.stride(1) / elements_per_entry;
+    vllm_value_offset = vllm_key_value_cache.stride(0) / elements_per_entry;
+  } else {  // engine_kv_format == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS
+    vllm_block_key_stride_in_64bit =
+        vllm_key_value_cache.stride(0) / elements_per_entry;
+    vllm_value_offset = vllm_key_value_cache.stride(1) / elements_per_entry;
+  }
+
+  // int block_stride_in_64bit = vllm_key_cache.stride(0) / elements_per_entry;
+  // TORCH_CHECK(vllm_key_cache.stride(0) == vllm_value_cache.stride(0));
+
+  dim3 grid(num_tokens);
+  dim3 block(std::min(num_heads * head_size_in_64bit, 128));
+  const at::cuda::OptionalCUDAGuard device_guard(
+      device_of(vllm_key_value_cache));
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  // Dispatch to the appropriate template specialization based on EngineKVFormat
+#define LAUNCH_SINGLE_LAYER_KERNEL(FORMAT)                                     \
+  lmc::single_layer_kv_transfer_kernel<int64_t, FORMAT>                        \
+      <<<grid, block, 0, stream>>>(                                            \
+          lmc_key_value_cache_ptr, vllm_key_value_cache_ptr, slot_mapping_ptr, \
+          vllm_block_key_stride_in_64bit, vllm_value_offset, lmc_stride,       \
+          lmc_value_offset, num_heads, head_size_in_64bit, block_size,         \
+          direction);                                                          \
+  break;
+
+  switch (engine_kv_format) {
+    case EngineKVFormat::NL_X_NB_BS_HS:
+      LAUNCH_SINGLE_LAYER_KERNEL(EngineKVFormat::NL_X_NB_BS_HS)
+    case EngineKVFormat::NL_X_TWO_NB_BS_NH_HS:
+      LAUNCH_SINGLE_LAYER_KERNEL(EngineKVFormat::NL_X_TWO_NB_BS_NH_HS)
+    case EngineKVFormat::NL_X_NB_TWO_BS_NH_HS:
+      LAUNCH_SINGLE_LAYER_KERNEL(EngineKVFormat::NL_X_NB_TWO_BS_NH_HS)
+    case EngineKVFormat::NL_X_TWO_NB_NH_BS_HS:
+      LAUNCH_SINGLE_LAYER_KERNEL(EngineKVFormat::NL_X_TWO_NB_NH_BS_HS)
+    case EngineKVFormat::NL_X_NB_TWO_NH_BS_HS:
+      LAUNCH_SINGLE_LAYER_KERNEL(EngineKVFormat::NL_X_NB_TWO_NH_BS_HS)
+    default:
+      TORCH_CHECK(false,
+                  "Unsupported EngineKVFormat for single_layer_kv_transfer: ",
+                  static_cast<int>(engine_kv_format));
+  }
+#undef LAUNCH_SINGLE_LAYER_KERNEL
+}
+
+void load_and_reshape_flash(
+    torch::Tensor&
+        key_value,  // [2, num_layer, num_tokens, num_heads*head_size]
+                    // key/value must be on gpu/pinned cpu
+
+    torch::Tensor& key_cache,  // [num_blocks, block_size, num_heads, head_size]
+    torch::Tensor&
+        value_cache,  // [num_blocks, block_size, num_heads, head_size]
+                      // key_cache/value_cache must be on gpu
+    torch::Tensor& slot_mapping,  // [num_tokens],
+    const int layer_idx) {
+  int64_t* key_value_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_value);
+
+  int64_t* key_cache_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_cache);
+  int64_t* value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(value_cache);
+
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / key_cache.element_size();
+
+  int num_tokens = slot_mapping.size(0);
+  int num_heads = key_cache.size(2);
+  int head_size_in_64bit = key_cache.size(3) / elements_per_entry;
+
+  int block_size = key_cache.size(1);
+
+  int key_value_stride = key_value.stride(2) / elements_per_entry;
+
+  int num_layers = key_value.size(1);
+  int key_layer_offset = layer_idx * key_value.stride(1) / elements_per_entry;
+  int value_layer_offset =
+      (layer_idx + num_layers) * key_value.stride(1) / elements_per_entry;
+
+  int block_stride_in_64bit = key_cache.stride(0) / elements_per_entry;
+  TORCH_CHECK(key_cache.stride(0) == value_cache.stride(0));
+
+  dim3 grid(num_tokens);
+  dim3 block(std::min(num_heads * head_size_in_64bit, 128));
+  const at::cuda::OptionalCUDAGuard device_guard(device_of(key_cache));
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  lmc::load_and_reshape_flash_kernel<int64_t><<<grid, block, 0, stream>>>(
+      key_value_ptr, key_cache_ptr, value_cache_ptr, slot_mapping_ptr,
+      block_stride_in_64bit, key_value_stride, num_heads, head_size_in_64bit,
+      block_size, key_layer_offset, value_layer_offset);
+}
+
+void reshape_and_cache_back_flash(
+    torch::Tensor&
+        key_value,  // [2, num_layer, num_tokens, num_heads*head_size]
+                    // key/value must be on gpu/pinned cpu
+
+    torch::Tensor& key_cache,  // [num_blocks, block_size, num_heads, head_size]
+    torch::Tensor&
+        value_cache,  // [num_blocks, block_size, num_heads, head_size]
+                      // key_cache/value_cache must be on gpu
+    torch::Tensor& slot_mapping,  // [num_tokens]
+    const int layer_idx) {
+  int64_t* key_cache_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_cache);
+  int64_t* value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(value_cache);
+
+  int64_t* key_value_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_value);
+
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / key_cache.element_size();
+
+  int num_tokens = slot_mapping.size(0);
+  int num_heads = key_cache.size(2);
+  int head_size_in_64bit = key_cache.size(3) / elements_per_entry;
+
+  int block_size = key_cache.size(1);
+
+  int key_value_stride = key_value.stride(2) / elements_per_entry;
+
+  int num_layers = key_value.size(1);
+  int key_layer_offset = layer_idx * key_value.stride(1) / elements_per_entry;
+  int value_layer_offset =
+      (layer_idx + num_layers) * key_value.stride(1) / elements_per_entry;
+
+  int block_stride_in_64bit = key_cache.stride(0) / elements_per_entry;
+  TORCH_CHECK(key_cache.stride(0) == value_cache.stride(0));
+
+  dim3 grid(num_tokens);
+  dim3 block(std::min(num_heads * head_size_in_64bit, 128));
+  const at::cuda::OptionalCUDAGuard device_guard(device_of(key_cache));
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  lmc::reshape_and_cache_back_flash_kernel<int64_t><<<grid, block, 0, stream>>>(
+      key_value_ptr, key_cache_ptr, value_cache_ptr, slot_mapping_ptr,
+      block_stride_in_64bit, key_value_stride, num_heads, head_size_in_64bit,
+      block_size, key_layer_offset, value_layer_offset);
+}
+
+void single_layer_kv_transfer_sgl(
+    // torch::Tensor& lmc_key_cache,  // [num_tokens, num_heads*head_size]
+    //  key/value must be on gpu/pinned cpu
+    // torch::Tensor& lmc_value_cache,  // [num_tokens, num_heads*head_size]
+
+    torch::Tensor& lmc_key_value_cache,  // [num_tokens, 2, num_heads*head_size]
+                                         // or
+                                         // [2, num_tokens, num_heads*head_size]
+
+    torch::Tensor&
+        sgl_key_cache,  // [num_blocks, block_size, num_heads, head_size]
+    torch::Tensor&
+        sgl_value_cache,  // [num_blocks, block_size, num_heads, head_size]
+                          // key_cache/value_cache must be on gpu
+    torch::Tensor& slot_mapping,  // [num_tokens]
+    const TransferDirection direction,
+    const bool token_major  // true: lmc_key_value_cache is
+                            // [num_tokens, 2, num_heads*head_size]
+                            // false: lmc_key_value_cache is
+                            // [2, num_tokens, num_heads*head_size]
+) {
+  // int64_t* lmc_key_cache_ptr = get_kernel_ptr<int64_t,
+  // torch::Tensor>(lmc_key_cache); int64_t* lmc_value_cache_ptr =
+  // get_kernel_ptr<int64_t, torch::Tensor>(lmc_value_cache);
+  int64_t* lmc_key_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(lmc_key_value_cache);
+
+  int64_t* sgl_key_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(sgl_key_cache);
+  int64_t* sgl_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(sgl_value_cache);
+
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / sgl_key_cache.element_size();
+
+  int num_tokens = slot_mapping.size(0);
+  int num_heads = sgl_key_cache.size(2);
+  int head_size_in_64bit = sgl_key_cache.size(3) / elements_per_entry;
+
+  int block_size = sgl_key_cache.size(1);
+
+  int lmc_stride;
+  int lmc_value_offset;
+  if (token_major) {
+    lmc_stride = lmc_key_value_cache.stride(0) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(1) / elements_per_entry;
+  } else {
+    lmc_stride = lmc_key_value_cache.stride(1) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(0) / elements_per_entry;
+  }
+
+  int block_stride_in_64bit = sgl_key_cache.stride(0) / elements_per_entry;
+  TORCH_CHECK(sgl_key_cache.stride(0) == sgl_value_cache.stride(0));
+
+  dim3 grid(num_tokens);
+  dim3 block(std::min(num_heads * head_size_in_64bit, 128));
+  const at::cuda::OptionalCUDAGuard device_guard(device_of(sgl_key_cache));
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  lmc::single_layer_kv_transfer_sgl_kernel<int64_t><<<grid, block, 0, stream>>>(
+      lmc_key_value_cache_ptr, sgl_key_cache_ptr, sgl_value_cache_ptr,
+      slot_mapping_ptr, block_stride_in_64bit, lmc_stride, lmc_value_offset,
+      num_heads, head_size_in_64bit, block_size, direction);
+}
+
+/**
+ * Perform asynchronous memory copy between lmcache host buffer (memory obj)
+ * and a device buffer.
+ * The copy will be performed asynchronously on the current CUDA stream.
+ * They copy will be split into multiple smaller copies based on the host buffer
+ * offset and host buffer alignment requirements.
+ *
+ * @param dest Destination pointer (device or host)
+ * @param src Source pointer (device or host)
+ * @param nbytes Number of bytes to copy
+ * @param direction H2D or D2H
+ * @param host_buffer_offset the virtual offset in the lmcache memory allocator
+ * @param host_buffer_alignments the alignment (i.e., cudaHostRegister
+ * granularity) requirement of the host buffer. Must be power of two.
+ */
+void lmcache_memcpy_async(uintptr_t dest, uintptr_t src, size_t nbytes,
+                          TransferDirection direction,
+                          size_t host_buffer_offset,
+                          size_t host_buffer_alignments) {
+  // Check that host_buffer_alignments is power of two
+  TORCH_CHECK((host_buffer_alignments & (host_buffer_alignments - 1)) == 0,
+              "host_buffer_alignments must be power of two");
+
+  size_t offset = 0;
+  const size_t mask = host_buffer_alignments - 1;
+  cudaMemcpyKind kind = (direction == TransferDirection::H2D)
+                            ? cudaMemcpyHostToDevice
+                            : cudaMemcpyDeviceToHost;
+  cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  while (offset < nbytes) {
+    size_t current_src = src + offset;
+    size_t current_dest = dest + offset;
+
+    size_t aligned_area_end =
+        ((offset + host_buffer_offset) & ~mask) + host_buffer_alignments;
+    // Use std::min<size_t> so HIP's overload set cannot silently narrow
+    // these values to int and produce a garbage length past the 2 GB mark.
+    size_t real_end =
+        std::min<size_t>(host_buffer_offset + nbytes, aligned_area_end);
+    size_t max_nbytes = real_end - offset - host_buffer_offset;
+
+    CHECK_CUDA_CALL(cudaMemcpyAsync(reinterpret_cast<void*>(current_dest),
+                                    reinterpret_cast<const void*>(current_src),
+                                    max_nbytes, kind, stream));
+
+    offset += max_nbytes;
+  }
+}
diff --git a/csrc/mem_kernels.cuh b/csrc/mem_kernels.cuh
new file mode 100644
index 0000000..a2d76e8
--- /dev/null
+++ b/csrc/mem_kernels.cuh
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <ATen/cuda/CUDAContext.h>
+#include <c10/util/Exception.h>
+#include "kv_transfer_types.h"
+
+void multi_layer_kv_transfer(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format, const int block_size = 0,
+    const int head_size = 0, const int skip_prefix_n_tokens = 0);
+
+// collapses to multi_layer_kv_transfer for MLA
+void multi_layer_kv_transfer_unilateral(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format);
+
+void single_layer_kv_transfer(torch::Tensor& lmc_key_value_cache,
+                              torch::Tensor& vllm_key_value_cache,
+                              torch::Tensor& slot_mapping,
+                              const TransferDirection direction,
+                              const EngineKVFormat engine_kv_format,
+                              const bool token_major = false);
+
+void single_layer_kv_transfer_sgl(torch::Tensor& lmc_key_value_cache,
+                                  torch::Tensor& sgl_key_cache,
+                                  torch::Tensor& sgl_value_cache,
+                                  torch::Tensor& slot_mapping,
+                                  const TransferDirection direction,
+                                  const bool token_major = false);
+
+void lmcache_memcpy_async(uintptr_t dest, uintptr_t src, size_t nbytes,
+                          TransferDirection direction,
+                          size_t host_buffer_offset,
+                          size_t host_buffer_alignments);
+
+// deprecated / unused except in unit tests
+void load_and_reshape_flash(torch::Tensor& key_value, torch::Tensor& key_cache,
+                            torch::Tensor& value_cache,
+                            torch::Tensor& slot_mapping, const int layer_idx);
+
+// deprecated / unused except in unit tests
+void reshape_and_cache_back_flash(torch::Tensor& key_value,
+                                  torch::Tensor& key_cache,
+                                  torch::Tensor& value_cache,
+                                  torch::Tensor& slot_mapping,
+                                  const int layer_idx);
diff --git a/csrc/mp_mem_kernels.cu b/csrc/mp_mem_kernels.cu
new file mode 100644
index 0000000..ebe3d75
--- /dev/null
+++ b/csrc/mp_mem_kernels.cu
@@ -0,0 +1,472 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "mp_mem_kernels.cuh"
+
+namespace {
+
+/**
+ * Key logic in the kernel implementation:
+ * 1. Each thread block is for (BS, NH, HS) part (i.e., a single block in the
+ * paged buffer)
+ * 2. Within a thread block, each warp is for a single head. Number of warps
+ * in a thread block is equal to the number of heads (NH).
+ * 3. Within a thread block, we do the loop over the BS (i.e., number of tokens
+ * in the block) dimension.
+ * 4. The grid will take over (2, NB, NL) dimensions. No matter what the actual
+ * layout in memory is, we will calculate the global offset for the start of the
+ * block
+ * 5. For LMCache, we assume it is always using 2LTD layout, e.g.,
+ * [2, L, 256, NH * HS], where 256 means that 256 tokens
+ */
+
+/**
+ * Calculate the offset for the current block in the paged buffer
+ */
+template <typename ScalarType, EngineKVFormat format>
+__device__ inline size_t calculate_engine_global_offset(
+    const int k_or_v, const int engine_block_idx, const int layer_idx,
+    const PageBufferShapeDesc shape_desc) {
+  size_t scalars_per_block = shape_desc.scalars_per_block<ScalarType>();
+  if constexpr (format == EngineKVFormat::NB_NL_TWO_BS_NH_HS) {
+    // Cross-layer: single tensor [NB, NL, 2, BS, NH, HS]
+    return k_or_v * scalars_per_block +
+           layer_idx * shape_desc.kv_size * scalars_per_block +
+           engine_block_idx * shape_desc.kv_size * scalars_per_block *
+               shape_desc.nl;
+  } else if constexpr (format == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS) {
+    // Normal: L tensors [2, NB, BS, NH, HS]
+    return engine_block_idx * scalars_per_block +
+           k_or_v * shape_desc.nb * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::NL_X_TWO_NB_NH_BS_HS) {
+    // Normal HND: L tensors [2, NB, NH, BS, HS]
+    return engine_block_idx * scalars_per_block +
+           k_or_v * shape_desc.nb * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS) {
+    // Flash Infer: L tensors [NB, 2, BS, NH, HS]
+    return engine_block_idx * shape_desc.kv_size * scalars_per_block +
+           k_or_v * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::NL_X_NB_TWO_NH_BS_HS) {
+    // Flash Infer HND: L tensors [NB, 2, NH, BS, HS]
+    return engine_block_idx * shape_desc.kv_size * scalars_per_block +
+           k_or_v * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::NL_X_NB_BS_HS) {
+    // MLA: L tensors [NB, BS, HS]
+    return engine_block_idx * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS) {
+    // SGLang MHA (in-process): 2L tensors [NBBS, NH, HS]
+    return engine_block_idx * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS) {
+    // SGLang MHA (MP daemon): 2L tensors [NB, BS, NH, HS]
+    return engine_block_idx * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::NL_X_NBBS_ONE_HS) {
+    // SGLang MLA: L tensors [NBBS, 1, HS]
+    return engine_block_idx * scalars_per_block;
+  } else if constexpr (format == EngineKVFormat::NB_NL_TWO_NH_BS_HS) {
+    // TRT-LLM cross-layer HND: single tensor [NB, NL, 2, NH, BS, HS]
+    // same block-level strides as NB_NL_TWO_BS_NH_HS
+    return k_or_v * scalars_per_block +
+           layer_idx * shape_desc.kv_size * scalars_per_block +
+           engine_block_idx * shape_desc.kv_size * scalars_per_block *
+               shape_desc.nl;
+  }
+}
+
+/**
+ * Calculate the offset for the current token against the start
+ * of the block in the paged buffer.
+ */
+template <typename ScalarType, EngineKVFormat format>
+__device__ inline size_t calculate_engine_local_offset(
+    const int token_offset, const int head_idx,
+    const PageBufferShapeDesc shape_desc) {
+  size_t scalars_per_head = shape_desc.scalars_per_head<ScalarType>();
+  size_t scalars_per_token = shape_desc.scalars_per_token<ScalarType>();
+  if constexpr (format == EngineKVFormat::NB_NL_TWO_NH_BS_HS ||
+                format == EngineKVFormat::NL_X_TWO_NB_NH_BS_HS ||
+                format == EngineKVFormat::NL_X_NB_TWO_NH_BS_HS) {
+    // HND: [NH, BS, HS] — heads are outermost within a block
+    size_t scalars_per_head_block =
+        shape_desc.bs * scalars_per_head;  // BS * HS
+    return head_idx * scalars_per_head_block + token_offset * scalars_per_head;
+  } else {
+    // NHD: [BS, NH, HS] — tokens are outermost within a block
+    return head_idx * scalars_per_head + token_offset * scalars_per_token;
+  }
+}
+
+/**
+ * Calculate the global offset for the current `block` in the LMCache object.
+ * The `block` here is the memory region corresponding to a thread-block.
+ */
+template <typename ScalarType, EngineKVFormat format>
+__device__ inline size_t calculate_lmcache_global_offset(
+    const int k_or_v,
+    const int
+        token_offset_in_lmcache_object,  // 0~255 if LMCache chunk size is 256
+    const int layer_idx,
+    const int lmcache_chunk_size,  // e.g., 256
+    const PageBufferShapeDesc shape_desc) {
+  size_t scalars_per_token = shape_desc.scalars_per_token<ScalarType>();
+  // LMCache is using 2LTD all the times
+  return token_offset_in_lmcache_object * scalars_per_token +
+         layer_idx * lmcache_chunk_size * scalars_per_token +
+         k_or_v * shape_desc.nl * lmcache_chunk_size * scalars_per_token;
+}
+
+/**
+ * Calculate the local offset for the current token against the start of the
+ * block in the LMCache object.
+ */
+template <typename ScalarType, EngineKVFormat format>
+__device__ inline size_t calculate_lmcache_local_offset(
+    const int token_offset, const int head_idx,
+    const PageBufferShapeDesc shape_desc) {
+  size_t scalars_per_head = shape_desc.scalars_per_head<ScalarType>();
+  size_t scalars_per_token = shape_desc.scalars_per_token<ScalarType>();
+  return head_idx * scalars_per_head + token_offset * scalars_per_token;
+}
+
+__device__ inline uint4 ld_cs(const uint4* addr) {
+#ifdef __CUDA_ARCH__
+  uint4 val;
+  asm volatile("ld.global.cs.v4.u32 {%0, %1, %2, %3}, [%4];"
+               : "=r"(val.x), "=r"(val.y), "=r"(val.z), "=r"(val.w)
+               : "l"(addr));
+  return val;
+#else
+  return *addr;
+#endif
+}
+
+__device__ inline void st_cs(uint4* addr, uint4 val) {
+#ifdef __CUDA_ARCH__
+  asm volatile("st.global.cs.v4.u32 [%0], {%1, %2, %3, %4};"
+               :
+               : "l"(addr), "r"(val.x), "r"(val.y), "r"(val.z), "r"(val.w));
+#else
+  *addr = val;
+#endif
+}
+
+template <typename ScalarType>
+__device__ inline void warp_copy(ScalarType* __restrict__ dst,
+                                 const ScalarType* __restrict__ src,
+                                 size_t num_elements) {
+  int idx = threadIdx.x;
+  int stride = blockDim.x;
+  if constexpr (std::is_same_v<ScalarType, uint4>) {
+    for (size_t i = idx; i < num_elements; i += stride) {
+      st_cs(dst + i, ld_cs(src + i));
+    }
+  } else {
+    for (size_t i = idx; i < num_elements; i += stride) {
+      dst[i] = src[i];
+    }
+  }
+}
+
+template <typename ScalarType, bool lmcache_to_engine, EngineKVFormat format>
+__device__ void multi_layer_block_transfer_single_block(
+    ScalarType* __restrict__ lmcache_object,
+    ScalarType** __restrict__ paged_buffer_ptrs, const int engine_block_idx,
+    const int offset_in_lmcache_block, const PageBufferShapeDesc shape_desc,
+    const int lmcache_chunk_size  // e.g., 256, used to calculate global offset
+                                  // in LMCache object
+) {
+  const int head_idx = threadIdx.y;
+  const int k_or_v = blockIdx.x;
+  const int layer_idx = blockIdx.z;
+
+  const size_t engine_global_offset =
+      calculate_engine_global_offset<ScalarType, format>(
+          k_or_v, engine_block_idx, layer_idx, shape_desc);
+  const size_t lmcache_global_offset =
+      calculate_lmcache_global_offset<ScalarType, format>(
+          k_or_v, offset_in_lmcache_block, layer_idx, lmcache_chunk_size,
+          shape_desc);
+  ScalarType* paged_buffer_layer_ptr;
+  if constexpr (format == EngineKVFormat::NB_NL_TWO_BS_NH_HS ||
+                format == EngineKVFormat::NB_NL_TWO_NH_BS_HS) {
+    paged_buffer_layer_ptr = (ScalarType*)paged_buffer_ptrs[0];
+  } else if constexpr (format == EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS) {
+    // SGLang MHA (in-process): ptrs[0..NL-1] = K per layer, ptrs[NL..2NL-1] = V
+    // per layer
+    paged_buffer_layer_ptr =
+        (ScalarType*)paged_buffer_ptrs[k_or_v * shape_desc.nl + layer_idx];
+  } else if constexpr (format == EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS) {
+    // SGLang MHA (MP daemon): ptrs[0..NL-1] = K per layer, ptrs[NL..2NL-1] = V
+    // per layer
+    paged_buffer_layer_ptr =
+        (ScalarType*)paged_buffer_ptrs[k_or_v * shape_desc.nl + layer_idx];
+  } else {
+    paged_buffer_layer_ptr = (ScalarType*)paged_buffer_ptrs[layer_idx];
+  }
+
+  for (int token_offset = 0; token_offset < shape_desc.bs; ++token_offset) {
+    const size_t engine_local_offset =
+        calculate_engine_local_offset<ScalarType, format>(token_offset,
+                                                          head_idx, shape_desc);
+    const size_t lmcache_local_offset =
+        calculate_lmcache_local_offset<ScalarType, format>(
+            token_offset, head_idx, shape_desc);
+    ScalarType* engine_ptr =
+        paged_buffer_layer_ptr + engine_global_offset + engine_local_offset;
+    ScalarType* lmcache_ptr =
+        lmcache_object + lmcache_global_offset + lmcache_local_offset;
+    if constexpr (lmcache_to_engine) {
+      warp_copy<ScalarType>(engine_ptr, lmcache_ptr,
+                            shape_desc.scalars_per_head<ScalarType>());
+    } else {
+      warp_copy<ScalarType>(lmcache_ptr, engine_ptr,
+                            shape_desc.scalars_per_head<ScalarType>());
+    }
+  }
+}
+
+template <typename ScalarType, bool lmcache_to_engine, EngineKVFormat format>
+__global__ void multi_layer_block_transfer_kernel(
+    MemoryObj4<ScalarType> lmcache_objects,
+    ScalarType** __restrict__ paged_buffer_ptrs,
+    const int64_t* engine_block_ids,
+    const int num_blocks_per_object,  // e.g. 16 for lmcache chunk size =
+                                      // 256 and block size = 16
+    const PageBufferShapeDesc shape_desc,
+    const int lmcache_chunk_size,  // e.g., 256, used to calculate global offset
+                                   // in LMCache object
+    const int skip_prefix_n_blocks) {
+  // blockIdx.y spans all blocks across all objects (total_blocks).
+  // Derive which object and local block index from the flat index.
+  const int flat_block_idx = blockIdx.y;
+  if (flat_block_idx < skip_prefix_n_blocks) {
+    return;
+  }
+  const int obj_idx = flat_block_idx / num_blocks_per_object;
+  const int block_idx_in_object = flat_block_idx % num_blocks_per_object;
+
+  const int engine_block_idx = engine_block_ids[flat_block_idx];
+  multi_layer_block_transfer_single_block<ScalarType, lmcache_to_engine,
+                                          format>(
+      lmcache_objects.objects[obj_idx], paged_buffer_ptrs, engine_block_idx,
+      block_idx_in_object * shape_desc.bs,  // offset in LMCache object
+      shape_desc, lmcache_chunk_size);
+}
+
+#define LAUNCH_KERNEL(DIRECTION, FORMAT)                                 \
+  multi_layer_block_transfer_kernel<ScalarType, DIRECTION, FORMAT>       \
+      <<<grid, block, 0, stream>>>(lmcache_obj4, paged_buffer_ptrs,      \
+                                   block_ids_ptr, num_blocks_per_object, \
+                                   shape_desc, lmcache_chunk_size,       \
+                                   skip_prefix_n_blocks);                \
+  C10_CUDA_KERNEL_LAUNCH_CHECK();
+
+#define DISPATCH_FORMAT(DIRECTION)                                      \
+  switch (engine_kv_format) {                                           \
+    case EngineKVFormat::NB_NL_TWO_BS_NH_HS:                            \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NB_NL_TWO_BS_NH_HS);     \
+      break;                                                            \
+    case EngineKVFormat::NL_X_TWO_NB_BS_NH_HS:                          \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NL_X_TWO_NB_BS_NH_HS);   \
+      break;                                                            \
+    case EngineKVFormat::NL_X_TWO_NB_NH_BS_HS:                          \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NL_X_TWO_NB_NH_BS_HS);   \
+      break;                                                            \
+    case EngineKVFormat::NL_X_NB_TWO_BS_NH_HS:                          \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NL_X_NB_TWO_BS_NH_HS);   \
+      break;                                                            \
+    case EngineKVFormat::NL_X_NB_TWO_NH_BS_HS:                          \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NL_X_NB_TWO_NH_BS_HS);   \
+      break;                                                            \
+    case EngineKVFormat::NL_X_NB_BS_HS:                                 \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NL_X_NB_BS_HS);          \
+      break;                                                            \
+    case EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS:                         \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS);  \
+      break;                                                            \
+    case EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS:                        \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS); \
+      break;                                                            \
+    case EngineKVFormat::NL_X_NBBS_ONE_HS:                              \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NL_X_NBBS_ONE_HS);       \
+      break;                                                            \
+    case EngineKVFormat::NB_NL_TWO_NH_BS_HS:                            \
+      LAUNCH_KERNEL(DIRECTION, EngineKVFormat::NB_NL_TWO_NH_BS_HS);     \
+      break;                                                            \
+    default:                                                            \
+      TORCH_CHECK(false, "Unsupported EngineKVFormat: ",                \
+                  static_cast<int>(engine_kv_format));                  \
+  }
+
+template <typename ScalarType>
+void multi_layer_block_kv_transfer_templated(
+    const torch::Tensor& paged_buffer_ptrs_tensor,
+    std::vector<int64_t> lmcache_objects_ptrs, const torch::Tensor& block_ids,
+    const torch::Device& device, TransferDirection direction,
+    PageBufferShapeDesc shape_desc, int lmcache_chunk_size,
+    EngineKVFormat engine_kv_format, int skip_prefix_n_blocks) {
+  // --- Validation ---
+  int num_objects = static_cast<int>(lmcache_objects_ptrs.size());
+  TORCH_CHECK(num_objects >= 1 && num_objects <= 4,
+              "Expected 1-4 LMCache objects, got ", num_objects);
+
+  int total_blocks = block_ids.size(0);
+  TORCH_CHECK(total_blocks % num_objects == 0, "block_ids length (",
+              total_blocks, ") must be divisible by num_objects (", num_objects,
+              ")");
+  int num_blocks_per_object = total_blocks / num_objects;
+
+  TORCH_CHECK(num_blocks_per_object * shape_desc.bs == lmcache_chunk_size,
+              "blocks_per_object * block_size (",
+              num_blocks_per_object * shape_desc.bs,
+              ") must equal lmcache_chunk_size (", lmcache_chunk_size, ")");
+
+  // --- Build MemoryObj4 ---
+  MemoryObj4<ScalarType> lmcache_obj4;
+  lmcache_obj4.num_objects = num_objects;
+  for (int i = 0; i < 4; ++i) {
+    lmcache_obj4.objects[i] =
+        (i < num_objects)
+            ? reinterpret_cast<ScalarType*>(lmcache_objects_ptrs[i])
+            : nullptr;
+  }
+
+  // --- Build paged buffer pointer array ---
+  ScalarType** paged_buffer_ptrs =
+      reinterpret_cast<ScalarType**>(paged_buffer_ptrs_tensor.data_ptr());
+
+  const at::cuda::OptionalCUDAGuard device_guard(device);
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+
+  // --- block_ids is a GPU int64 tensor, read directly ---
+  const int64_t* block_ids_ptr = block_ids.data_ptr<int64_t>();
+
+  // --- Grid and block dimensions ---
+  int elements_per_head = shape_desc.hs * shape_desc.element_size /
+                          static_cast<int>(sizeof(ScalarType));
+  int thread_dim_x = std::min(elements_per_head, 32);
+  int thread_dim_y = shape_desc.nh;
+
+  dim3 block(thread_dim_x, thread_dim_y);
+  dim3 grid(shape_desc.kv_size, total_blocks, shape_desc.nl);
+
+  if (direction == TransferDirection::H2D) {
+    DISPATCH_FORMAT(true);
+  } else {
+    DISPATCH_FORMAT(false);
+  }
+}
+
+#undef DISPATCH_FORMAT
+#undef LAUNCH_KERNEL
+
+}  // namespace
+
+#define LAUNCH_TEMPLATED(type)                                             \
+  do {                                                                     \
+    multi_layer_block_kv_transfer_templated<type>(                         \
+        paged_buffer_ptrs_tensor, lmcache_objects_ptrs, block_ids, device, \
+        direction, shape_desc, lmcache_chunk_size, engine_kv_format,       \
+        skip_prefix_n_blocks);                                             \
+  } while (0)
+
+void multi_layer_block_kv_transfer(
+    const torch::Tensor& paged_buffer_ptrs_tensor,
+    std::vector<int64_t> lmcache_objects_ptrs, const torch::Tensor& block_ids,
+    const torch::Device& device, TransferDirection direction,
+    PageBufferShapeDesc shape_desc, int lmcache_chunk_size,
+    EngineKVFormat engine_kv_format, int skip_prefix_n_blocks) {
+  int head_bytes = shape_desc.hs * shape_desc.element_size;
+  TORCH_CHECK(head_bytes % sizeof(uint16_t) == 0, "head_size * element_size (",
+              head_bytes, ") must be divisible by 2 for vectorized access");
+
+  if (head_bytes % sizeof(uint4) == 0) {
+    LAUNCH_TEMPLATED(uint4);  // 16 bytes per copy
+  } else if (head_bytes % sizeof(uint32_t) == 0) {
+    LAUNCH_TEMPLATED(uint32_t);  // 4 bytes per copy
+  } else {
+    LAUNCH_TEMPLATED(uint16_t);  // 2 bytes per copy (minimum granularity)
+  }
+}
+
+#undef LAUNCH_TEMPLATED
+
+void execute_object_group_transfer(
+    TransferDirection direction, const torch::Device& device,
+    size_t host_buffer_alignment,
+    const std::vector<KernelGroupSpec>& kernel_group_specs,
+    const std::vector<BatchStep>& batch_steps) {
+  // Set the device guard once for the whole plan so every staging copy and
+  // kernel launch below is enqueued on this device's current stream, in order.
+  const at::cuda::OptionalCUDAGuard device_guard(device);
+  const bool is_h2d = (direction == TransferDirection::H2D);
+  const auto int64_opts = at::TensorOptions().dtype(at::kLong).device(device);
+
+  const auto do_staging = [&](const std::vector<StagingCopy>& staging) {
+    for (const auto& copy : staging) {
+      lmcache_memcpy_async(copy.dest, copy.src, copy.nbytes, direction,
+                           copy.host_offset, host_buffer_alignment);
+    }
+  };
+
+  for (const auto& step : batch_steps) {
+    // H2D stages CPU->GPU temp buffers before the kernel reads them; D2H stages
+    // GPU->CPU after the kernel writes them. The per-step ordering must be
+    // preserved because temp buffers are reused across steps.
+    if (is_h2d) {
+      do_staging(step.staging);
+    }
+    for (const auto& launch : step.launches) {
+      TORCH_CHECK(
+          launch.group_idx >= 0 &&
+              launch.group_idx < static_cast<int>(kernel_group_specs.size()),
+          "LaunchVar.group_idx out of range: ", launch.group_idx);
+      const KernelGroupSpec& group = kernel_group_specs[launch.group_idx];
+      TORCH_CHECK(launch.num_objects >= 1 &&
+                      launch.num_objects <=
+                          static_cast<int>(group.lmcache_objects_ptrs.size()),
+                  "LaunchVar.num_objects (", launch.num_objects,
+                  ") exceeds available temp buffers (",
+                  group.lmcache_objects_ptrs.size(), ")");
+      // Bounds-check the block_ids slice before the kernel dereferences it on
+      // device: an out-of-range offset/length would otherwise be a silent
+      // out-of-bounds device read (CUDA fault or garbage), not a clean error.
+      TORCH_CHECK(launch.block_ids_offset >= 0,
+                  "LaunchVar.block_ids_offset must be non-negative, got ",
+                  launch.block_ids_offset);
+      TORCH_CHECK(launch.total_blocks >= 0,
+                  "LaunchVar.total_blocks must be non-negative, got ",
+                  launch.total_blocks);
+      TORCH_CHECK(launch.block_ids_offset + launch.total_blocks <=
+                      group.block_ids_capacity,
+                  "LaunchVar block_ids slice [", launch.block_ids_offset, ", ",
+                  launch.block_ids_offset + launch.total_blocks,
+                  ") exceeds block_ids capacity ", group.block_ids_capacity);
+
+      // Wrap the plan's pre-resolved raw device addresses as non-owning tensor
+      // views so we can reuse the existing multi_layer_block_kv_transfer entry
+      // point without touching any of its code. The backing storage is owned by
+      // the caller's tensors (kept alive for the duration of this call); these
+      // views only carry the pointer/shape each launch needs. Downstream only
+      // reads paged_buffer_ptrs_tensor.data_ptr() and block_ids.{data_ptr,
+      // size(0)}.
+      const uintptr_t block_ids_addr =
+          group.block_ids_base +
+          static_cast<uintptr_t>(launch.block_ids_offset) * sizeof(int64_t);
+      const at::Tensor paged_buffer_ptrs_tensor = at::from_blob(
+          reinterpret_cast<void*>(group.paged_buffer_ptrs), {1}, int64_opts);
+      const at::Tensor block_ids = at::from_blob(
+          reinterpret_cast<void*>(block_ids_addr),
+          {static_cast<int64_t>(launch.total_blocks)}, int64_opts);
+      std::vector<int64_t> lmcache_objects_ptrs(
+          group.lmcache_objects_ptrs.begin(),
+          group.lmcache_objects_ptrs.begin() + launch.num_objects);
+
+      multi_layer_block_kv_transfer(
+          paged_buffer_ptrs_tensor, std::move(lmcache_objects_ptrs), block_ids,
+          device, direction, group.shape_desc, group.lmcache_chunk_size,
+          group.engine_kv_format, launch.skip_prefix_n_blocks);
+    }
+    if (!is_h2d) {
+      do_staging(step.staging);
+    }
+  }
+}
diff --git a/csrc/mp_mem_kernels.cuh b/csrc/mp_mem_kernels.cuh
new file mode 100644
index 0000000..7534001
--- /dev/null
+++ b/csrc/mp_mem_kernels.cuh
@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "mem_kernels.cuh"  // TransferDirection, EngineKVFormat
+
+#include <c10/cuda/CUDAGuard.h>
+#include <cstdint>
+#include <vector>
+
+struct PageBufferShapeDesc {
+  int kv_size;       // 1 or 2
+  int nl;            // num layers
+  int nb;            // num blocks
+  int bs;            // block size
+  int nh;            // num heads
+  int hs;            // head size
+  int element_size;  // bytes (1 or 2)
+  // Physical per-block stride in source-dtype element units, used by
+  // formats whose dim-0 is the block axis to step over padding bytes
+  // (e.g. DeepSeek V4 compressor / indexer caches sharing a vLLM KV
+  // pool with larger attn groups, whose rows are padded up to the
+  // pool's max row width). 0 means "unset — fall back to the
+  // format-specific tight stride".
+  //
+  // CONTRACT: pass ``tensor.stride(0)`` verbatim. PyTorch stride
+  // semantics already absorb every inner-dim extent (including
+  // ``kv_size``), so DO NOT pre-multiply by any inner dim.
+  //
+  // Honoured today only by NL_X_NB_BS_HS (per-layer [NB, BS, HS],
+  // MLA). NL_X_NB_TWO_BS_NH_HS is restricted to the tight form
+  // upstream and leaves this field at 0; all other formats either
+  // pack non-block info into dim-0 or do not support dim-0 padding,
+  // and ignore this field.
+  int block_stride_elems;
+
+  template <typename ScalarType>
+  __host__ __device__ inline size_t scalars_per_head() const {
+    return hs * element_size / sizeof(ScalarType);
+  }
+
+  template <typename ScalarType>
+  __host__ __device__ inline size_t scalars_per_token() const {
+    return nh * hs * element_size / sizeof(ScalarType);
+  }
+
+  // Per (K or V) block step along dim-0, expressed in ``ScalarType``
+  // element units (the kernel's working dtype, e.g. uint4 / uint32_t /
+  // uint16_t). Returns the tight ``bs * nh * hs`` by default, or the
+  // physical ``block_stride_elems`` when dim-0 carries padding (today
+  // only NL_X_NB_BS_HS, see ``block_stride_elems`` above). Every
+  // ``calculate_engine_global_offset`` branch uses this as the dim-0
+  // step, so honouring padding here propagates to all formats without
+  // per-branch changes.
+  template <typename ScalarType>
+  __host__ __device__ inline size_t scalars_per_block() const {
+    const size_t elems = block_stride_elems > 0
+                             ? static_cast<size_t>(block_stride_elems)
+                             : static_cast<size_t>(bs) * nh * hs;
+    return elems * element_size / sizeof(ScalarType);
+  }
+};
+
+template <typename ScalarType>
+struct MemoryObj4 {
+  ScalarType* objects[4];
+  int num_objects;  // 0 - 4
+};
+
+// ---------------------------------------------------------------------------
+// Object-group transfer plan.
+//
+// A whole object group's transfer (all staging copies + all kernel launches) is
+// described as a plan on the Python side, then executed in a single native call
+// (execute_object_group_transfer) that releases the GIL once for the entire
+// burst instead of once per copy/launch. See the design in
+// docs/design/v1/multiprocess/modules/ and lmcache_driven_transfer.py.
+// ---------------------------------------------------------------------------
+
+// One asynchronous host<->device copy. `host_offset` is the host-side virtual
+// offset in the lmcache allocator (source for H2D, destination for D2H).
+struct StagingCopy {
+  uintptr_t dest;
+  uintptr_t src;
+  size_t nbytes;
+  size_t host_offset;
+};
+
+// One kernel launch within a batch step. The batch-invariant arguments live in
+// the referenced KernelGroupSpec; only these vary per (batch, kernel group).
+struct LaunchVar {
+  int group_idx;             // index into the plan's kernel_group_specs
+  int64_t block_ids_offset;  // element offset into the group's block_ids_base
+  int total_blocks;          // number of block ids for this launch
+  int num_objects;           // chunks in this batch (1-4)
+  int skip_prefix_n_blocks;
+};
+
+// One batch: its staging copies and kernel launches. For H2D the staging runs
+// before the launches, for D2H after; the executor preserves this ordering.
+struct BatchStep {
+  std::vector<StagingCopy> staging;
+  std::vector<LaunchVar> launches;
+};
+
+// Per-kernel-group invariants, resolved once on the Python side.
+struct KernelGroupSpec {
+  uintptr_t paged_buffer_ptrs;                // device ptr-array base address
+  std::vector<int64_t> lmcache_objects_ptrs;  // temp GPU buffer ptr per slot
+  PageBufferShapeDesc shape_desc;
+  int lmcache_chunk_size;
+  EngineKVFormat engine_kv_format;
+  uintptr_t block_ids_base;  // device int64* base; sliced via block_ids_offset
+  int64_t block_ids_capacity;  // total int64 elements behind block_ids_base;
+                               // bounds-checks each slice in the executor
+};
+
+/**
+ * Execute one object group's transfer plan on the current CUDA stream.
+ *
+ * Enqueues every staging copy and kernel launch described by `batch_steps`
+ * within a single GIL release (configured at the pybind layer), eliminating the
+ * per-copy/per-launch GIL handoffs of the equivalent Python loop. The device
+ * guard and stream are set once for the whole plan.
+ *
+ * @param direction            H2D (retrieve) or D2H (store), applied to all ops
+ * @param device               CUDA device of the transfer
+ * @param host_buffer_alignment Host buffer alignment for staging copies
+ *                              (power of two)
+ * @param kernel_group_specs   Per-kernel-group invariants
+ * @param batch_steps          Ordered per-batch staging + launch work
+ */
+void execute_object_group_transfer(
+    TransferDirection direction, const torch::Device& device,
+    size_t host_buffer_alignment,
+    const std::vector<KernelGroupSpec>& kernel_group_specs,
+    const std::vector<BatchStep>& batch_steps);
+
+/**
+ * Block-level multi-layer KV transfer between vLLM paged buffers and
+ * LMCache contiguous memory objects.
+ *
+ * @param paged_buffer_ptrs_tensor  GPU int64 tensor of data pointers into
+ *                                  vLLM paged buffers (one per tensor)
+ * @param lmcache_objects_ptrs      Raw pointers to LMCache memory objects
+ * @param block_ids                 GPU int64 tensor of block indices in vLLM
+ *                                  paged buffer
+ * @param device                    CUDA device of vLLM tensors
+ * @param direction                 H2D (LMCache->vLLM) or D2H (vLLM->LMCache)
+ * @param shape_desc                Shape descriptor for the paged buffer
+ * @param lmcache_chunk_size        Tokens per LMCache memory object
+ * @param engine_kv_format             EngineKVFormat identifier
+ * @param skip_prefix_n_blocks      Number of blocks to skip at the beginning
+ */
+void multi_layer_block_kv_transfer(
+    const torch::Tensor& paged_buffer_ptrs_tensor,
+    std::vector<int64_t> lmcache_objects_ptrs, const torch::Tensor& block_ids,
+    const torch::Device& device, TransferDirection direction,
+    PageBufferShapeDesc shape_desc, int lmcache_chunk_size,
+    EngineKVFormat engine_kv_format, int skip_prefix_n_blocks);
diff --git a/csrc/pos_kernels.cu b/csrc/pos_kernels.cu
new file mode 100644
index 0000000..cfc00d2
--- /dev/null
+++ b/csrc/pos_kernels.cu
@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/*
+ * Adapted from
+ * https://github.com/vllm-project/vllm/blob/main/csrc/pos_encoding_kernels.cu
+ */
+
+#include <torch/all.h>
+#include <ATen/cuda/CUDAContext.h>
+#include <c10/cuda/CUDAGuard.h>
+
+#include "dispatch_utils.h"
+#include "cuda_compat.h"
+namespace lmc {
+
+template <typename scalar_t, bool IS_NEOX>
+inline __device__ void apply_token_rotary_embedding_fused(
+    scalar_t* __restrict__ arr, const scalar_t* __restrict__ old_cos_ptr,
+    const scalar_t* __restrict__ old_sin_ptr,
+    const scalar_t* __restrict__ new_cos_ptr,
+    const scalar_t* __restrict__ new_sin_ptr, int rot_offset, int embed_dim) {
+  int x_index, y_index;
+  scalar_t old_cos, old_sin;
+  scalar_t new_cos, new_sin;
+  if (IS_NEOX) {
+    // GPT-NeoX style rotary embedding.
+    x_index = rot_offset;
+    y_index = embed_dim + rot_offset;
+    old_cos = LMCACHE_LDG(old_cos_ptr + x_index);
+    old_sin = LMCACHE_LDG(old_sin_ptr + x_index);
+
+    new_cos = LMCACHE_LDG(new_cos_ptr + x_index);
+    new_sin = LMCACHE_LDG(new_sin_ptr + x_index);
+  } else {
+    // GPT-J style rotary embedding.
+    x_index = 2 * rot_offset;
+    y_index = 2 * rot_offset + 1;
+    old_cos = LMCACHE_LDG(old_cos_ptr + x_index / 2);
+    old_sin = LMCACHE_LDG(old_sin_ptr + x_index / 2);
+
+    new_cos = LMCACHE_LDG(new_cos_ptr + x_index / 2);
+    new_sin = LMCACHE_LDG(new_sin_ptr + x_index / 2);
+  }
+
+  const scalar_t x = arr[x_index];
+  const scalar_t y = arr[y_index];
+
+  const scalar_t x_reverse = x * old_cos + y * old_sin;
+  const scalar_t y_reverse = y * old_cos - x * old_sin;
+
+  arr[x_index] = x_reverse * new_cos - y_reverse * new_sin;
+  arr[y_index] = y_reverse * new_cos + x_reverse * new_sin;
+}
+
+template <typename scalar_t, bool IS_NEOX>
+inline __device__ void apply_rotary_embedding_fused(
+    scalar_t* __restrict__ key,  // [batch_size, seq_len, num_kv_heads,
+                                 // head_size] or [num_tokens, num_kv_heads,
+                                 // head_size]
+    const scalar_t* old_cache_ptr, const scalar_t* new_cache_ptr,
+    const int head_size, const int num_kv_heads, const int rot_dim,
+    const int token_idx, const int64_t key_stride) {
+  const int embed_dim = rot_dim / 2;
+  const scalar_t* old_cos_ptr = old_cache_ptr;
+  const scalar_t* old_sin_ptr = old_cache_ptr + embed_dim;
+
+  const scalar_t* new_cos_ptr = new_cache_ptr;
+  const scalar_t* new_sin_ptr = new_cache_ptr + embed_dim;
+
+  const int nk = num_kv_heads * embed_dim;
+  for (int i = threadIdx.x; i < nk; i += blockDim.x) {
+    const int head_idx = i / embed_dim;
+    const int64_t token_head = token_idx * key_stride + head_idx * head_size;
+    const int rot_offset = i % embed_dim;
+    apply_token_rotary_embedding_fused<scalar_t, IS_NEOX>(
+        key + token_head, old_cos_ptr, old_sin_ptr, new_cos_ptr, new_sin_ptr,
+        rot_offset, embed_dim);
+  }
+}
+
+template <typename scalar_t, bool IS_NEOX>
+__global__ void rotary_embedding_kernel_fused(
+    const int64_t* __restrict__ old_positions,  // [batch_size, seq_len] or
+                                                // [num_tokens]
+
+    const int64_t* __restrict__ new_positions,  // [batch_size, seq_len] or
+                                                // [num_tokens]
+
+    scalar_t* __restrict__ key,  // [batch_size, seq_len, num_kv_heads,
+                                 // head_size] or [num_tokens, num_kv_heads,
+                                 // head_size]
+    const scalar_t* __restrict__ cos_sin_cache,  // [max_position, 2, rot_dim //
+                                                 // 2]
+    const int rot_dim, const int64_t key_stride, const int num_kv_heads,
+    const int head_size) {
+  // Each thread block is responsible for one token.
+  const int token_idx = blockIdx.x;
+  int64_t old_pos = old_positions[token_idx];
+  int64_t new_pos = new_positions[token_idx];
+
+  const scalar_t* old_cache_ptr = cos_sin_cache + old_pos * rot_dim;
+  const scalar_t* new_cache_ptr = cos_sin_cache + new_pos * rot_dim;
+
+  apply_rotary_embedding_fused<scalar_t, IS_NEOX>(
+      key, old_cache_ptr, new_cache_ptr, head_size, num_kv_heads, rot_dim,
+      token_idx, key_stride);
+}
+
+}  // namespace lmc
+
+void rotary_embedding_k_fused(
+    const torch::Tensor&
+        old_positions,  // [batch_size, seq_len] or [num_tokens]
+    const torch::Tensor&
+        new_positions,   // [batch_size, seq_len] or [num_tokens]
+    torch::Tensor& key,  // [batch_size, seq_len, num_kv_heads * head_size] or
+                         // Jiayi: [num_tokens, num_kv_heads, head_size]
+    int64_t head_size,
+    const torch::Tensor& cos_sin_cache,  // [max_position, rot_dim]
+    bool is_neox) {
+  int64_t num_tokens = key.numel() / (key.size(-1) * key.size(-2));
+  int rot_dim = cos_sin_cache.size(1);
+  int num_kv_heads = key.size(-2);
+  int64_t key_stride = num_kv_heads * head_size;
+
+  dim3 grid(num_tokens);
+  dim3 block(std::min<int64_t>(num_kv_heads * rot_dim / 2, 512));
+  const at::cuda::OptionalCUDAGuard device_guard(device_of(key));
+  const cudaStream_t stream = at::cuda::getCurrentCUDAStream();
+  LMC_DISPATCH_FLOATING_TYPES(
+      key.scalar_type(), "rotary_embedding_k_fused", [&] {
+        if (is_neox) {
+          lmc::rotary_embedding_kernel_fused<scalar_t, true>
+              <<<grid, block, 0, stream>>>(
+                  old_positions.data_ptr<int64_t>(),
+                  new_positions.data_ptr<int64_t>(), key.data_ptr<scalar_t>(),
+                  cos_sin_cache.data_ptr<scalar_t>(), rot_dim, key_stride,
+                  num_kv_heads, head_size);
+        } else {
+          lmc::rotary_embedding_kernel_fused<scalar_t, false>
+              <<<grid, block, 0, stream>>>(
+                  old_positions.data_ptr<int64_t>(),
+                  new_positions.data_ptr<int64_t>(), key.data_ptr<scalar_t>(),
+                  cos_sin_cache.data_ptr<scalar_t>(), rot_dim, key_stride,
+                  num_kv_heads, head_size);
+        }
+      });
+}
diff --git a/csrc/pos_kernels.cuh b/csrc/pos_kernels.cuh
new file mode 100644
index 0000000..5429e11
--- /dev/null
+++ b/csrc/pos_kernels.cuh
@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <ATen/cuda/CUDAContext.h>
+#include <c10/util/Exception.h>
+
+void rotary_embedding_k_fused(const torch::Tensor& old_positions,
+                              const torch::Tensor& new_positions,
+                              torch::Tensor& key, int64_t head_size,
+                              const torch::Tensor& cos_sin_cache, bool is_neox);
\ No newline at end of file
diff --git a/csrc/pybind.cpp b/csrc/pybind.cpp
new file mode 100644
index 0000000..fc380c6
--- /dev/null
+++ b/csrc/pybind.cpp
@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include "mem_kernels.cuh"
+#include "mp_mem_kernels.cuh"
+#include "cachegen_kernels.cuh"
+#include "pos_kernels.cuh"
+#include "mem_alloc.h"
+#include "utils.h"
+#include "event_recorder.h"
+#include "completion_recorder.h"
+#include <torch/torch.h>
+#include <torch/extension.h>
+#include <iostream>
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(c_ops, m) {
+  py::enum_<TransferDirection>(m, "TransferDirection")
+      .value("H2D", TransferDirection::H2D)
+      .value("D2H", TransferDirection::D2H)
+      .export_values();
+  py::enum_<EngineKVFormat>(m, "EngineKVFormat")
+      .value("NB_NL_TWO_BS_NH_HS", EngineKVFormat::NB_NL_TWO_BS_NH_HS)
+      .value("NL_X_TWO_NB_BS_NH_HS", EngineKVFormat::NL_X_TWO_NB_BS_NH_HS)
+      .value("NL_X_NB_TWO_BS_NH_HS", EngineKVFormat::NL_X_NB_TWO_BS_NH_HS)
+      .value("NL_X_NB_BS_HS", EngineKVFormat::NL_X_NB_BS_HS)
+      .value("TWO_X_NL_X_NBBS_NH_HS", EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS)
+      .value("NL_X_NBBS_ONE_HS", EngineKVFormat::NL_X_NBBS_ONE_HS)
+      .value("NL_X_TWO_NB_NH_BS_HS", EngineKVFormat::NL_X_TWO_NB_NH_BS_HS)
+      .value("NL_X_NB_TWO_NH_BS_HS", EngineKVFormat::NL_X_NB_TWO_NH_BS_HS)
+      .value("NB_NL_TWO_NH_BS_HS", EngineKVFormat::NB_NL_TWO_NH_BS_HS)
+      .value("TWO_X_NL_X_NB_BS_NH_HS", EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS)
+      .value("NL_X_NB_NH_BS_TWO_HS", EngineKVFormat::NL_X_NB_NH_BS_TWO_HS)
+      .export_values();
+  // Format classification, shared with the device kernels (engine_kv_format.h).
+  m.def(
+      "is_cross_layer", [](EngineKVFormat f) { return is_cross_layer(f); },
+      py::arg("engine_kv_format"));
+  m.def(
+      "is_kv_list", [](EngineKVFormat f) { return is_kv_list(f); },
+      py::arg("engine_kv_format"));
+  m.def(
+      "is_layer_list", [](EngineKVFormat f) { return is_layer_list(f); },
+      py::arg("engine_kv_format"));
+  m.def(
+      "is_mla", [](EngineKVFormat f) { return is_mla(f); },
+      py::arg("engine_kv_format"));
+  m.def("multi_layer_kv_transfer", &multi_layer_kv_transfer,
+        py::arg("key_value"), py::arg("key_value_ptrs"),
+        py::arg("slot_mapping"), py::arg("paged_memory_device"),
+        py::arg("page_buffer_size"), py::arg("direction"),
+        py::arg("engine_kv_format"), py::arg("block_size") = 0,
+        py::arg("head_size") = 0, py::arg("skip_prefix_n_tokens") = 0,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("multi_layer_kv_transfer_unilateral",
+        &multi_layer_kv_transfer_unilateral);
+  m.def("single_layer_kv_transfer", &single_layer_kv_transfer,
+        py::arg("lmc_key_value_cache"), py::arg("vllm_key_value_cache"),
+        py::arg("slot_mapping"), py::arg("direction"),
+        py::arg("engine_kv_format"), py::arg("token_major") = false);
+  m.def("single_layer_kv_transfer_sgl", &single_layer_kv_transfer_sgl,
+        py::arg("lmc_key_value_cache"), py::arg("sgl_key_cache"),
+        py::arg("sgl_value_cache"), py::arg("slot_mapping"),
+        py::arg("direction"), py::arg("token_major") = false);
+  m.def("load_and_reshape_flash", &load_and_reshape_flash);
+  m.def("reshape_and_cache_back_flash", &reshape_and_cache_back_flash);
+  m.def("lmcache_memcpy_async", &lmcache_memcpy_async,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("encode_fast_new", &encode_cuda_new);
+  m.def("decode_fast_new", &decode_cuda_new);
+  m.def("decode_fast_prefsum", &decode_cuda_prefsum);
+  m.def("calculate_cdf", &calculate_cdf);
+  m.def("rotary_embedding_k_fused", &rotary_embedding_k_fused);
+  m.def("alloc_pinned_ptr", &alloc_pinned_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("free_pinned_ptr", &free_pinned_ptr);
+  m.def("alloc_hugepage_pinned_ptr", &alloc_hugepage_pinned_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("free_hugepage_pinned_ptr", &free_hugepage_pinned_ptr);
+  m.def("alloc_pinned_numa_ptr", &alloc_pinned_numa_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("free_pinned_numa_ptr", &free_pinned_numa_ptr);
+  m.def("alloc_hugepage_pinned_numa_ptr", &alloc_hugepage_pinned_numa_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("free_hugepage_pinned_numa_ptr", &free_hugepage_pinned_numa_ptr);
+  m.def("alloc_numa_ptr", &alloc_numa_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("free_numa_ptr", &free_numa_ptr);
+  m.def("alloc_shm_pinned_ptr", &alloc_shm_pinned_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("free_shm_pinned_ptr", &free_shm_pinned_ptr,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("batched_memcpy", &batched_memcpy, py::arg("src_ptrs"),
+        py::arg("dst_ptrs"), py::arg("sizes"),
+        py::call_guard<py::gil_scoped_release>());
+  m.def("get_gpu_pci_bus_id", &get_gpu_pci_bus_id);
+  m.def("multi_layer_block_kv_transfer", &multi_layer_block_kv_transfer,
+        py::arg("paged_buffer_ptrs_tensor"), py::arg("lmcache_objects_ptrs"),
+        py::arg("block_ids"), py::arg("device"), py::arg("direction"),
+        py::arg("shape_desc"), py::arg("lmcache_chunk_size"),
+        py::arg("engine_kv_format"), py::arg("skip_prefix_n_blocks"),
+        py::call_guard<py::gil_scoped_release>());
+  py::class_<PageBufferShapeDesc>(m, "PageBufferShapeDesc")
+      .def(py::init<>())
+      .def_readwrite("kv_size", &PageBufferShapeDesc::kv_size)
+      .def_readwrite("nl", &PageBufferShapeDesc::nl)
+      .def_readwrite("nb", &PageBufferShapeDesc::nb)
+      .def_readwrite("bs", &PageBufferShapeDesc::bs)
+      .def_readwrite("nh", &PageBufferShapeDesc::nh)
+      .def_readwrite("hs", &PageBufferShapeDesc::hs)
+      .def_readwrite("element_size", &PageBufferShapeDesc::element_size)
+      .def_readwrite("block_stride_elems",
+                     &PageBufferShapeDesc::block_stride_elems);
+  // Object-group transfer plan types (see mp_mem_kernels.cuh). Built on the
+  // Python side and consumed by execute_object_group_transfer.
+  py::class_<StagingCopy>(m, "StagingCopy")
+      .def(py::init([](uintptr_t dest, uintptr_t src, size_t nbytes,
+                       size_t host_offset) {
+             return StagingCopy{dest, src, nbytes, host_offset};
+           }),
+           py::arg("dest"), py::arg("src"), py::arg("nbytes"),
+           py::arg("host_offset"));
+  py::class_<LaunchVar>(m, "LaunchVar")
+      .def(
+          py::init([](int group_idx, int64_t block_ids_offset, int total_blocks,
+                      int num_objects, int skip_prefix_n_blocks) {
+            return LaunchVar{group_idx, block_ids_offset, total_blocks,
+                             num_objects, skip_prefix_n_blocks};
+          }),
+          py::arg("group_idx"), py::arg("block_ids_offset"),
+          py::arg("total_blocks"), py::arg("num_objects"),
+          py::arg("skip_prefix_n_blocks"));
+  py::class_<BatchStep>(m, "BatchStep")
+      .def(py::init([](std::vector<StagingCopy> staging,
+                       std::vector<LaunchVar> launches) {
+             return BatchStep{std::move(staging), std::move(launches)};
+           }),
+           py::arg("staging"), py::arg("launches"));
+  py::class_<KernelGroupSpec>(m, "KernelGroupSpec")
+      .def(py::init([](uintptr_t paged_buffer_ptrs,
+                       std::vector<int64_t> lmcache_objects_ptrs,
+                       PageBufferShapeDesc shape_desc, int lmcache_chunk_size,
+                       EngineKVFormat engine_kv_format,
+                       uintptr_t block_ids_base, int64_t block_ids_capacity) {
+             return KernelGroupSpec{
+                 paged_buffer_ptrs, std::move(lmcache_objects_ptrs),
+                 shape_desc,        lmcache_chunk_size,
+                 engine_kv_format,  block_ids_base,
+                 block_ids_capacity};
+           }),
+           py::arg("paged_buffer_ptrs"), py::arg("lmcache_objects_ptrs"),
+           py::arg("shape_desc"), py::arg("lmcache_chunk_size"),
+           py::arg("engine_kv_format"), py::arg("block_ids_base"),
+           py::arg("block_ids_capacity"));
+  m.def("execute_object_group_transfer", &execute_object_group_transfer,
+        py::arg("direction"), py::arg("device"),
+        py::arg("host_buffer_alignment"), py::arg("kernel_group_specs"),
+        py::arg("batch_steps"), py::call_guard<py::gil_scoped_release>());
+  m.def("record_event_on_stream", &record_event_on_stream,
+        py::arg("cuda_stream_ptr"), py::arg("event_type_name"),
+        py::arg("session_id"), py::arg("str_metadata"), py::arg("int_metadata"),
+        py::call_guard<py::gil_scoped_release>());
+  m.def("drain_recorded_events", &drain_recorded_events);
+  m.def("record_completion_on_stream", &record_completion_on_stream,
+        py::arg("cuda_stream_ptr"), py::arg("kind"), py::arg("payload"),
+        py::call_guard<py::gil_scoped_release>());
+  // Return each payload as py::bytes; pybind11 utf-8-decodes std::string
+  // by default, corrupting binary payloads (e.g. msgpack).
+  m.def("drain_recorded_completions", []() {
+    auto items = drain_recorded_completions();
+    py::list out;
+    for (auto& kv : items) {
+      out.append(py::make_tuple(py::str(kv.first), py::bytes(kv.second)));
+    }
+    return out;
+  });
+  // Backward-compat alias: GPUKVFormat -> EngineKVFormat
+  m.attr("GPUKVFormat") = m.attr("EngineKVFormat");
+}
diff --git a/csrc/storage_backends/README.md b/csrc/storage_backends/README.md
new file mode 100644
index 0000000..b070c32
--- /dev/null
+++ b/csrc/storage_backends/README.md
@@ -0,0 +1,311 @@
+# Native Storage Backends
+
+Build high-performance storage connectors in C++/Rust that work in **both**
+LMCache modes:
+
+- **Non-MP mode** (single process): via `ConnectorClientBase` (asyncio integration)
+- **MP mode** (multiprocess): via `NativeConnectorL2Adapter` (L2 adapter interface)
+
+Write the connector once, get both modes for free.
+
+```
+Non-MP mode:
+  CacheEngine → RemoteBackend → ConnectorClientBase → native client (C++)
+                                  (asyncio event loop)
+
+MP mode:
+  StoreController / PrefetchController
+        ↓
+  NativeConnectorL2Adapter (Python bridge)
+    ├─ 3 eventfds (store, lookup, load)
+    ├─ completion demux thread
+    ├─ ObjectKey ↔ string serialization
+    └─ client-side lock tracking
+        ↓
+  native client (C++)
+    └─ 1 eventfd, worker threads, GIL-free I/O
+```
+
+## Design principles
+
+There are two sources of overhead in a Python integration:
+
+1. **Submission**: the submitting Python thread shouldn't block, and we
+   should make as few submissions to the event loop as possible.
+
+2. **Completion**: we shouldn't poll for completions, and we should have
+   as few completions as possible.
+
+Therefore the framework enforces:
+
+1. GIL release at pybind layer for true concurrency between native threads
+2. Batching with tiling (work for a batched request split evenly among threads)
+3. eventfd-based non-polling completions (the kernel wakes up Python)
+4. Non-blocking submission (submission queue / completion queue architecture)
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `connector_types.h` | `Request`, `Completion`, `BatchState`, `Op` |
+| `connector_interface.h` | `IStorageConnector` — top-level abstract interface |
+| `connector_base.h` | `ConnectorBase<T>` — core harness (eventfd, SQ/CQ, threading, tiling). Override 4 required + 1 optional method per backend |
+| `connector_pybind_utils.h` | Pybind utilities with GIL release + `LMCACHE_BIND_CONNECTOR_METHODS` macro |
+| `redis/` | Reference implementation (RESP2 protocol over TCP) |
+| `aerospike/` | Optional native Aerospike backend (meta + segment sharding; `BUILD_AEROSPIKE=1`) |
+
+## Aerospike (optional build)
+
+The Aerospike connector is **not** built by default. Enable it when packaging or
+developing:
+
+Set ``AEROSPIKE_INCLUDE_DIR`` and ``AEROSPIKE_LIBRARY_DIR`` to a libaerospike
+development install (or use ``BUILD_AEROSPIKE=1`` after placing headers/libs under
+``.deps/`` as in ``.github/workflows/aerospike_integration.yml``), then:
+
+```bash
+BUILD_AEROSPIKE=1 pip install -e .
+```
+
+MP mode:
+
+```bash
+--l2-adapter '{"type": "aerospike", "hosts": "127.0.0.1:3000", "namespace": "lmcache", "set_name": "kv_chunks", "num_workers": 8}'
+```
+
+Config module: ``lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py``.
+
+## How to add a new native backend
+
+There are 5 steps. The Redis connector is the reference implementation for
+each step.
+
+### Step 1: C++ connector — inherit from ConnectorBase
+
+Create your connector directory (e.g., `csrc/storage_backends/mybackend/`)
+and inherit from `ConnectorBase<YourConnectionType>`. You need to
+override 4 required methods (and optionally `do_single_delete` for eviction):
+
+```cpp
+// csrc/storage_backends/mybackend/connector.h
+#include "../connector_base.h"
+
+struct MyConn {
+  int fd = -1;
+  // your per-thread connection state
+};
+
+class MyConnector : public lmcache::connector::ConnectorBase<MyConn> {
+ public:
+  MyConnector(std::string host, int port, int num_workers)
+      : ConnectorBase(num_workers), host_(host), port_(port) {
+    start_workers();  // IMPORTANT: call at END of constructor
+  }
+
+ protected:
+  // 1. Create a connection (called once per worker thread)
+  MyConn create_connection() override {
+    MyConn conn;
+    // connect to server...
+    return conn;
+  }
+
+  // 2. GET: read value for key into buf (buf has chunk_size bytes)
+  void do_single_get(MyConn& conn, const std::string& key,
+                     void* buf, size_t len, size_t chunk_size) override {
+    // send GET, recv response into buf
+  }
+
+  // 3. SET: write chunk_size bytes from buf under key
+  void do_single_set(MyConn& conn, const std::string& key,
+                     const void* buf, size_t len, size_t chunk_size) override {
+    // send SET with data from buf
+  }
+
+  // 4. EXISTS: check if key exists
+  bool do_single_exists(MyConn& conn, const std::string& key) override {
+    // send EXISTS, return true/false
+  }
+
+  // Optional: delete a key (enables eviction support)
+  bool do_single_delete(MyConn& conn, const std::string& key) override {
+    // send DELETE, return true if deleted, false if not found
+  }
+
+  // Optional: clean shutdown of connections
+  void shutdown_connections() override { /* close sockets */ }
+
+ private:
+  std::string host_;
+  int port_;
+};
+```
+
+**Reference:** `redis/connector.{h,cpp}`
+
+What `ConnectorBase` gives you for free:
+- Worker thread pool with per-thread connections
+- Submission queue (lock-free enqueue) and completion queue
+- Automatic tiling: batch operations are split across workers
+- eventfd signaling on completion (kernel wakes Python)
+- Graceful shutdown (stop flag, drain, join)
+
+### Step 2: Pybind module
+
+Use the `LMCACHE_BIND_CONNECTOR_METHODS` macro which binds all 6 methods
+(`event_fd`, `submit_batch_get/set/exists`, `drain_completions`, `close`)
+with proper GIL release and buffer protocol handling.
+
+```cpp
+// csrc/storage_backends/mybackend/pybind.cpp
+#include <pybind11/pybind11.h>
+#include "../connector_pybind_utils.h"
+#include "connector.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(lmcache_mybackend, m) {
+  py::class_<MyConnector>(m, "LMCacheMyBackendClient")
+      .def(py::init<std::string, int, int>(),
+           py::arg("host"), py::arg("port"), py::arg("num_workers"))
+      LMCACHE_BIND_CONNECTOR_METHODS(MyConnector);
+}
+```
+
+**Reference:** `redis/pybind.cpp`
+
+### Step 3: Build system — register in setup.py
+
+Add your sources to `setup.py` alongside the existing Redis extension:
+
+```python
+# In _common_cpp_extensions():
+mybackend_sources = [
+    "csrc/storage_backends/mybackend/pybind.cpp",
+    "csrc/storage_backends/mybackend/connector.cpp",
+]
+
+# Add to ext_modules list:
+cpp_extension.CppExtension(
+    "lmcache.lmcache_mybackend",
+    sources=mybackend_sources,
+    include_dirs=["csrc/storage_backends", "csrc/storage_backends/mybackend"],
+    extra_compile_args={"cxx": ["-O3", "-std=c++17"]},
+),
+```
+
+Then rebuild: `pip install -e .`
+
+### Step 4: Python client — non-MP mode integration
+
+Inherit from `ConnectorClientBase` which provides asyncio event loop
+integration, future management, and both sync and async methods.
+
+```python
+# lmcache/v1/storage_backend/native_clients/mybackend_client.py
+from .connector_client_base import ConnectorClientBase
+from lmcache.lmcache_mybackend import LMCacheMyBackendClient
+
+class MyBackendClient(ConnectorClientBase[LMCacheMyBackendClient]):
+    def __init__(self, host: str, port: int, num_workers: int, loop=None):
+        native = LMCacheMyBackendClient(host, port, num_workers)
+        super().__init__(native, loop)
+```
+
+This gives you `async get/set/exists`, `batch_get/batch_set/batch_exists`,
+and sync variants, all with automatic eventfd-driven completion handling.
+
+**Reference:** `lmcache/v1/storage_backend/native_clients/resp_client.py`
+
+### Step 5: MP mode integration — L2 adapter config + factory
+
+To use your connector as an L2 adapter in MP mode, add a config class and
+register it in the factory. The `NativeConnectorL2Adapter` bridge handles
+all the complexity (eventfd demuxing, key serialization, locking).
+
+**a) Add config class** in `lmcache/v1/distributed/l2_adapters/config.py`:
+
+```python
+class MyBackendL2AdapterConfig(L2AdapterConfigBase):
+    def __init__(self, host: str, port: int, num_workers: int = 8):
+        self.host = host
+        self.port = port
+        self.num_workers = num_workers
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "MyBackendL2AdapterConfig":
+        host = d.get("host")
+        if not isinstance(host, str) or not host:
+            raise ValueError("host must be a non-empty string")
+        port = d.get("port")
+        if not isinstance(port, int) or port <= 0:
+            raise ValueError("port must be a positive integer")
+        num_workers = d.get("num_workers", 8)
+        return cls(host=host, port=port, num_workers=num_workers)
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "MyBackend L2 adapter config fields:\n"
+            "- host (str): server hostname (required)\n"
+            "- port (int): server port (required)\n"
+            "- num_workers (int): worker threads (default 8)"
+        )
+
+register_l2_adapter_type("mybackend", MyBackendL2AdapterConfig)
+```
+
+**b) Add factory branch** in `lmcache/v1/distributed/l2_adapters/__init__.py`:
+
+```python
+if isinstance(config, MyBackendL2AdapterConfig):
+    from lmcache.lmcache_mybackend import LMCacheMyBackendClient
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+        NativeConnectorL2Adapter,
+    )
+    native_client = LMCacheMyBackendClient(
+        config.host, config.port, config.num_workers
+    )
+    return NativeConnectorL2Adapter(native_client)
+```
+
+**c) Use it** from the command line:
+
+```bash
+# MP mode with your backend as L2 storage
+--l2-adapter '{"type": "mybackend", "host": "10.0.0.1", "port": 9000}'
+```
+
+**Reference:** `RESPL2AdapterConfig` in `config.py` and `_create_resp_l2_adapter`
+in `__init__.py`
+
+## Architecture: how NativeConnectorL2Adapter bridges the gap
+
+The C++ connector has 1 eventfd and mixed completions. MP mode's
+`L2AdapterInterface` requires 3 eventfds and typed results. The bridge
+handles this transparently:
+
+| L2 Adapter method | Native connector call | Extra logic |
+|---|---|---|
+| `submit_store_task(keys, objs)` | `submit_batch_set` | ObjectKey→str, MemoryObj→memoryview |
+| `submit_lookup_and_lock_task(keys)` | `submit_batch_exists` | + client-side lock refcount |
+| `submit_load_task(keys, objs)` | `submit_batch_get` | ObjectKey→str, MemoryObj→memoryview |
+| `submit_unlock(keys)` | _(none)_ | client-side lock decrement |
+| `pop_completed_store_tasks()` | via `drain_completions` | demux by op type |
+| `query_lookup_and_lock_result()` | via `drain_completions` | exists→Bitmap, apply locks |
+| `query_load_result()` | via `drain_completions` | ok/fail→Bitmap |
+
+The demux thread polls the native eventfd, calls `drain_completions()`,
+looks up each `future_id` to determine its operation type, routes the
+result to the correct completion dict, and signals the corresponding
+Python eventfd.
+
+## Checklist for a new backend
+
+- [ ] C++ connector inheriting `ConnectorBase<T>` with 4 required + 1 optional (`do_single_delete`) method overrides
+- [ ] Pybind module using `LMCACHE_BIND_CONNECTOR_METHODS`
+- [ ] `setup.py` entry for the new `CppExtension`
+- [ ] Python client inheriting `ConnectorClientBase` (non-MP mode)
+- [ ] L2 adapter config class + factory registration (MP mode)
+- [ ] Unit tests (see `tests/v1/distributed/test_native_connector_l2_adapter.py`)
+- [ ] Optional: Aerospike integration (`RUN_AEROSPIKE_INTEGRATION=1`, see `tests/v1/distributed/test_aerospike_l2_integration.py`)
diff --git a/csrc/storage_backends/aerospike/connector.cpp b/csrc/storage_backends/aerospike/connector.cpp
new file mode 100644
index 0000000..72731e4
--- /dev/null
+++ b/csrc/storage_backends/aerospike/connector.cpp
@@ -0,0 +1,533 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "connector.h"
+
+#include <aerospike/aerospike_info.h>
+#include <aerospike/aerospike_key.h>
+#include <aerospike/as_config.h>
+#include <aerospike/as_record.h>
+#include <aerospike/as_status.h>
+
+#include <algorithm>
+#include <cassert>
+#include <cstdlib>
+#include <cstring>
+#include <ctime>
+#include <sstream>
+#include <stdexcept>
+
+namespace lmcache {
+namespace connector {
+namespace {
+
+constexpr size_t kSafetyMarginBytes = 64 * 1024;
+constexpr size_t kDefaultRecordCapBytes = 1024 * 1024;
+constexpr const char* kBinPayload = "b";
+constexpr const char* kBinState = "state";
+constexpr const char* kBinNseg = "nseg";
+constexpr const char* kBinSegBytes = "seg_b";
+constexpr const char* kBinTotalBytes = "tot_b";
+constexpr const char* kBinVersion = "ver";
+constexpr const char* kBinCreatedAt = "created_at";
+constexpr const char* kBinPin = "pin";
+constexpr const char* kReady = "ready";
+
+std::vector<std::string> split(const std::string& s, char sep) {
+  std::vector<std::string> out;
+  size_t start = 0;
+  for (size_t i = 0; i <= s.size(); ++i) {
+    if (i == s.size() || s[i] == sep) {
+      out.emplace_back(s.substr(start, i - start));
+      start = i + 1;
+    }
+  }
+  return out;
+}
+
+std::string status_message(as_status status, const as_error& err) {
+  std::ostringstream oss;
+  oss << "Aerospike status " << static_cast<int>(status);
+  if (err.message[0] != '\0') {
+    oss << ": " << err.message;
+  }
+  return oss.str();
+}
+
+// `as_record_get_int64` requires a default to return when a bin is absent or
+// not an int64, so a fallback is unavoidable at the API level. This helper also
+// treats non-positive values as "use the fallback" because the count/size bins
+// written by put_meta_record() are always >= 1 on a healthy record. Integrity-
+// critical fields (e.g. total size) are validated explicitly by the caller and
+// must not rely on this fallback to mask a missing bin.
+int64_t positive_int_bin(as_record* rec, const char* bin, int64_t fallback) {
+  int64_t value = as_record_get_int64(rec, bin, fallback);
+  return value > 0 ? value : fallback;
+}
+
+}  // namespace
+
+AerospikeNativeConnector::AerospikeNativeConnector(
+    std::string hosts, std::string ns, std::string set_name, int num_workers,
+    uint32_t read_timeout_ms, uint32_t write_timeout_ms,
+    uint32_t default_ttl_seconds, size_t target_segment_bytes,
+    size_t max_record_bytes, std::string username, std::string password)
+    : ConnectorBase(num_workers),
+      hosts_(std::move(hosts)),
+      ns_(std::move(ns)),
+      set_name_(std::move(set_name)),
+      read_timeout_ms_(read_timeout_ms),
+      write_timeout_ms_(write_timeout_ms),
+      default_ttl_seconds_(default_ttl_seconds) {
+  as_config config;
+  as_config_init(&config);
+  config.thread_pool_size = static_cast<uint32_t>(std::max(num_workers, 1));
+
+  for (const auto& [host, port] : parse_hosts(hosts_)) {
+    as_config_add_host(&config, host.c_str(), port);
+  }
+  if (!username.empty()) {
+    if (!as_config_set_user(&config, username.c_str(), password.c_str())) {
+      throw std::runtime_error("invalid Aerospike username/password config");
+    }
+  }
+
+  configure_policies();
+  aerospike_init(&as_, &config);
+
+  try {
+    as_error err;
+    if (aerospike_connect(&as_, &err) != AEROSPIKE_OK) {
+      throw std::runtime_error("aerospike_connect failed: " +
+                               status_message(err.code, err));
+    }
+    connected_ = true;
+
+    size_t discovered =
+        max_record_bytes == 0 ? discover_record_cap() : max_record_bytes;
+    if (discovered <= kSafetyMarginBytes) {
+      throw std::runtime_error("Aerospike record cap is too small");
+    }
+    max_record_bytes_ = discovered - kSafetyMarginBytes;
+    target_segment_bytes_ =
+        target_segment_bytes == 0
+            ? max_record_bytes_
+            : std::min(target_segment_bytes, max_record_bytes_);
+    single_record_threshold_bytes_ = target_segment_bytes_;
+
+    start_workers();
+  } catch (...) {
+    if (connected_) {
+      as_error close_err;
+      aerospike_close(&as_, &close_err);
+      connected_ = false;
+    }
+    aerospike_destroy(&as_);
+    throw;
+  }
+}
+
+AerospikeNativeConnector::~AerospikeNativeConnector() { close(); }
+
+void AerospikeNativeConnector::close() {
+  {
+    std::lock_guard<std::mutex> lk(close_mu_);
+    if (closed_native_) {
+      return;
+    }
+    closed_native_ = true;
+  }
+
+  ConnectorBase<WorkerAerospikeConn>::close();
+}
+
+WorkerAerospikeConn AerospikeNativeConnector::create_connection() {
+  WorkerAerospikeConn conn;
+  conn.client = &as_;
+  conn.ns = ns_;
+  conn.set_name = set_name_;
+
+  as_policy_read_init(&conn.read_policy);
+  conn.read_policy.base.total_timeout = read_timeout_ms_;
+  conn.read_policy.base.socket_timeout = read_timeout_ms_;
+  conn.read_policy.base.max_retries = 2;
+  conn.read_policy.key = AS_POLICY_KEY_DIGEST;
+  conn.read_policy.replica = AS_POLICY_REPLICA_SEQUENCE;
+
+  as_policy_write_init(&conn.write_policy);
+  conn.write_policy.base.total_timeout = write_timeout_ms_;
+  conn.write_policy.base.socket_timeout = write_timeout_ms_;
+  conn.write_policy.base.max_retries = 0;
+  conn.write_policy.key = AS_POLICY_KEY_DIGEST;
+  conn.write_policy.exists = AS_POLICY_EXISTS_IGNORE;
+  conn.write_policy.gen = AS_POLICY_GEN_IGNORE;
+  conn.write_policy.commit_level = AS_POLICY_COMMIT_LEVEL_ALL;
+  conn.write_policy.ttl = default_ttl_seconds_;
+
+  as_policy_remove_init(&conn.remove_policy);
+  conn.remove_policy.base.total_timeout = write_timeout_ms_;
+  conn.remove_policy.base.socket_timeout = write_timeout_ms_;
+  conn.remove_policy.base.max_retries = 0;
+  conn.remove_policy.key = AS_POLICY_KEY_DIGEST;
+
+  return conn;
+}
+
+void AerospikeNativeConnector::do_single_get(WorkerAerospikeConn& conn,
+                                             const std::string& key, void* buf,
+                                             size_t len,
+                                             size_t /*chunk_size*/) {
+  std::string meta_key = meta_user_key(key);
+
+  as_key as_meta_key;
+  as_key_init_str(&as_meta_key, conn.ns.c_str(), conn.set_name.c_str(),
+                  meta_key.c_str());
+
+  as_error err;
+  as_record* rec = nullptr;
+  as_status status = aerospike_key_get(conn.client, &err, &conn.read_policy,
+                                       &as_meta_key, &rec);
+  if (status != AEROSPIKE_OK) {
+    throw_status("get-meta", status, err);
+  }
+  if (rec == nullptr) {
+    throw std::runtime_error("get-meta returned no record");
+  }
+
+  const char* state = as_record_get_str(rec, kBinState);
+  if (state == nullptr || std::strcmp(state, kReady) != 0) {
+    as_record_destroy(rec);
+    throw std::runtime_error("meta record is not ready");
+  }
+
+  uint32_t nseg = static_cast<uint32_t>(positive_int_bin(rec, kBinNseg, 1));
+  size_t seg_b = static_cast<size_t>(positive_int_bin(rec, kBinSegBytes, len));
+  // Read the stored total directly with a sentinel so a missing or corrupt bin
+  // fails the integrity check instead of silently matching `len`.
+  int64_t total_raw = as_record_get_int64(rec, kBinTotalBytes, -1);
+  if (total_raw < 0 || static_cast<size_t>(total_raw) != len) {
+    as_record_destroy(rec);
+    throw std::runtime_error("meta record total size mismatch");
+  }
+  bool ok = true;
+  if (nseg == 1) {
+    as_bytes* payload = as_record_get_bytes(rec, kBinPayload);
+    if (payload == nullptr || payload->size != len) {
+      ok = false;
+    } else {
+      std::memcpy(buf, payload->value, len);
+    }
+  }
+  as_record_destroy(rec);
+
+  if (!ok) {
+    throw std::runtime_error("single-record payload size mismatch");
+  }
+  if (nseg == 1) {
+    return;
+  }
+
+  size_t offset = 0;
+  for (uint32_t i = 0; i < nseg; ++i) {
+    std::string segment_key_i = segment_user_key(key, i);
+    size_t chunk_len = std::min(seg_b, len - offset);
+    if (!read_payload_record(conn, segment_key_i,
+                             static_cast<char*>(buf) + offset, chunk_len)) {
+      throw std::runtime_error("missing segment payload");
+    }
+    offset += chunk_len;
+  }
+  if (offset != len) {
+    throw std::runtime_error("segment read size mismatch");
+  }
+}
+
+void AerospikeNativeConnector::do_single_set(WorkerAerospikeConn& conn,
+                                             const std::string& key,
+                                             const void* buf, size_t len,
+                                             size_t /*chunk_size*/) {
+  ShardPlan shard = plan(len);
+
+  if (shard.nseg == 1) {
+    put_meta_record(conn, meta_user_key(key), shard, len, buf);
+    return;
+  }
+
+  for (uint32_t i = 0; i < shard.nseg; ++i) {
+    size_t start = static_cast<size_t>(i) * shard.seg_b;
+    size_t chunk_len = std::min(shard.seg_b, len - start);
+    put_payload_record(conn, segment_user_key(key, i),
+                       static_cast<const char*>(buf) + start, chunk_len);
+  }
+  put_meta_record(conn, meta_user_key(key), shard, len, nullptr);
+}
+
+bool AerospikeNativeConnector::do_single_exists(WorkerAerospikeConn& conn,
+                                                const std::string& key) {
+  std::string user_key = meta_user_key(key);
+
+  as_key as_meta_key;
+  as_key_init_str(&as_meta_key, conn.ns.c_str(), conn.set_name.c_str(),
+                  user_key.c_str());
+
+  as_error err;
+  as_record* rec = nullptr;
+  as_status status = aerospike_key_exists(conn.client, &err, &conn.read_policy,
+                                          &as_meta_key, &rec);
+  if (rec != nullptr) {
+    as_record_destroy(rec);
+  }
+  if (status == AEROSPIKE_OK) {
+    return true;
+  }
+  if (status == AEROSPIKE_ERR_RECORD_NOT_FOUND) {
+    return false;
+  }
+  throw_status("exists", status, err);
+  return false;
+}
+
+bool AerospikeNativeConnector::do_single_delete(WorkerAerospikeConn& conn,
+                                                const std::string& key) {
+  std::string user_key = meta_user_key(key);
+  uint32_t nseg = 1;
+
+  as_key as_meta_key;
+  as_key_init_str(&as_meta_key, conn.ns.c_str(), conn.set_name.c_str(),
+                  user_key.c_str());
+
+  as_error err;
+  as_record* rec = nullptr;
+  as_status status = aerospike_key_get(conn.client, &err, &conn.read_policy,
+                                       &as_meta_key, &rec);
+  if (status == AEROSPIKE_ERR_RECORD_NOT_FOUND) {
+    return false;
+  }
+  if (status != AEROSPIKE_OK) {
+    throw_status("delete-read-meta", status, err);
+  }
+  if (rec != nullptr) {
+    nseg = static_cast<uint32_t>(positive_int_bin(rec, kBinNseg, 1));
+    as_record_destroy(rec);
+  }
+
+  status = aerospike_key_remove(conn.client, &err, &conn.remove_policy,
+                                &as_meta_key);
+  if (status == AEROSPIKE_ERR_RECORD_NOT_FOUND) {
+    return false;
+  }
+  if (status != AEROSPIKE_OK) {
+    throw_status("delete-meta", status, err);
+  }
+
+  for (uint32_t i = 0; i < nseg; ++i) {
+    as_key as_segment_key;
+    std::string segment_key_i = segment_user_key(key, i);
+    as_key_init_str(&as_segment_key, conn.ns.c_str(), conn.set_name.c_str(),
+                    segment_key_i.c_str());
+    as_error seg_err;
+    aerospike_key_remove(conn.client, &seg_err, &conn.remove_policy,
+                         &as_segment_key);
+  }
+  return true;
+}
+
+void AerospikeNativeConnector::shutdown_connections() {
+  // Shared client must outlive worker threads until ConnectorBase drains.
+}
+
+void AerospikeNativeConnector::on_workers_stopped() {
+  if (connected_) {
+    as_error err;
+    aerospike_close(&as_, &err);
+    aerospike_destroy(&as_);
+    connected_ = false;
+  }
+}
+
+std::vector<std::pair<std::string, int>> AerospikeNativeConnector::parse_hosts(
+    const std::string& hosts) {
+  std::vector<std::pair<std::string, int>> out;
+  for (const std::string& part : split(hosts, ',')) {
+    size_t colon = part.rfind(':');
+    if (colon == std::string::npos || colon == 0 || colon + 1 >= part.size()) {
+      throw std::runtime_error("hosts must be host:port[,host:port...]");
+    }
+    try {
+      out.emplace_back(part.substr(0, colon),
+                       std::stoi(part.substr(colon + 1)));
+    } catch (...) {
+      throw std::runtime_error("invalid port in hosts config: " + part);
+    }
+  }
+  if (out.empty()) {
+    throw std::runtime_error("hosts must not be empty");
+  }
+  return out;
+}
+
+std::string AerospikeNativeConnector::meta_user_key(
+    const std::string& cache_key) {
+  return cache_key + "|m";
+}
+
+std::string AerospikeNativeConnector::segment_user_key(
+    const std::string& cache_key, uint32_t index) {
+  return cache_key + "|s|" + std::to_string(index);
+}
+
+void AerospikeNativeConnector::throw_status(const char* op, as_status status,
+                                            const as_error& err) {
+  if (status == AEROSPIKE_ERR_RECORD_NOT_FOUND) {
+    throw std::runtime_error(std::string(op) + ": record not found");
+  }
+  throw std::runtime_error(std::string(op) + ": " +
+                           status_message(status, err));
+}
+
+ShardPlan AerospikeNativeConnector::plan(size_t payload_bytes) const {
+  if (payload_bytes <= single_record_threshold_bytes_ &&
+      payload_bytes <= max_record_bytes_) {
+    return {1, payload_bytes};
+  }
+  uint32_t nseg = static_cast<uint32_t>(
+      (payload_bytes + target_segment_bytes_ - 1) / target_segment_bytes_);
+  size_t seg_b = (payload_bytes + nseg - 1) / nseg;
+  if (seg_b > max_record_bytes_) {
+    throw std::runtime_error("payload cannot be sharded within record cap");
+  }
+  return {nseg, seg_b};
+}
+
+size_t AerospikeNativeConnector::discover_record_cap() {
+  std::string request = "namespace/" + ns_;
+  char* response = nullptr;
+  as_error err;
+  as_status status =
+      aerospike_info_any(&as_, &err, nullptr, request.c_str(), &response);
+  if (status != AEROSPIKE_OK || response == nullptr) {
+    if (response != nullptr) {
+      std::free(response);
+    }
+    throw_status("info namespace", status, err);
+  }
+
+  std::string text(response);
+  std::free(response);
+  for (const char* field : {"max-record-size=", "write-block-size="}) {
+    size_t pos = text.find(field);
+    if (pos == std::string::npos) {
+      continue;
+    }
+    pos += std::strlen(field);
+    size_t end = text.find(';', pos);
+    std::string value =
+        text.substr(pos, end == std::string::npos ? end : end - pos);
+    size_t cap = 0;
+    try {
+      cap = static_cast<size_t>(std::stoull(value));
+    } catch (...) {
+      continue;
+    }
+    if (cap > 0) {
+      return cap;
+    }
+  }
+  return kDefaultRecordCapBytes;
+}
+
+void AerospikeNativeConnector::configure_policies() {}
+
+void AerospikeNativeConnector::put_payload_record(WorkerAerospikeConn& conn,
+                                                  const std::string& user_key,
+                                                  const void* buf, size_t len) {
+  as_key key;
+  as_key_init_str(&key, conn.ns.c_str(), conn.set_name.c_str(),
+                  user_key.c_str());
+
+  as_record rec;
+  as_record_inita(&rec, 1);
+  rec.ttl = AS_RECORD_CLIENT_DEFAULT_TTL;
+  as_record_set_raw(&rec, kBinPayload, reinterpret_cast<const uint8_t*>(buf),
+                    static_cast<uint32_t>(len));
+
+  as_error err;
+  as_status status =
+      aerospike_key_put(conn.client, &err, &conn.write_policy, &key, &rec);
+  as_record_destroy(&rec);
+  if (status != AEROSPIKE_OK) {
+    throw_status("put-payload", status, err);
+  }
+}
+
+void AerospikeNativeConnector::put_meta_record(WorkerAerospikeConn& conn,
+                                               const std::string& user_key,
+                                               const ShardPlan& shard,
+                                               size_t total_bytes,
+                                               const void* inline_buf) {
+  as_key key;
+  as_key_init_str(&key, conn.ns.c_str(), conn.set_name.c_str(),
+                  user_key.c_str());
+
+  as_record rec;
+  as_record_inita(&rec, inline_buf == nullptr ? 7 : 8);
+  rec.ttl = AS_RECORD_CLIENT_DEFAULT_TTL;
+  as_record_set_int64(&rec, kBinVersion, 1);
+  as_record_set_str(&rec, kBinState, kReady);
+  as_record_set_int64(&rec, kBinNseg, shard.nseg);
+  as_record_set_int64(&rec, kBinSegBytes, static_cast<int64_t>(shard.seg_b));
+  as_record_set_int64(&rec, kBinTotalBytes, static_cast<int64_t>(total_bytes));
+  as_record_set_int64(&rec, kBinCreatedAt,
+                      static_cast<int64_t>(std::time(nullptr)));
+  as_record_set_bool(&rec, kBinPin, false);
+  if (inline_buf != nullptr) {
+    // The inline payload path is only taken for single-record writes, where
+    // do_single_set() already guaranteed (via plan()) that
+    // total_bytes <= max_record_bytes_ -- the discovered server record cap
+    // minus a safety margin, which is far below UINT32_MAX. The narrowing cast
+    // below is therefore safe; assert the invariant in case that ever changes.
+    assert(total_bytes <= max_record_bytes_);
+    as_record_set_raw(&rec, kBinPayload,
+                      reinterpret_cast<const uint8_t*>(inline_buf),
+                      static_cast<uint32_t>(total_bytes));
+  }
+
+  as_error err;
+  as_status status =
+      aerospike_key_put(conn.client, &err, &conn.write_policy, &key, &rec);
+  as_record_destroy(&rec);
+  if (status != AEROSPIKE_OK) {
+    throw_status("put-meta", status, err);
+  }
+}
+
+bool AerospikeNativeConnector::read_payload_record(WorkerAerospikeConn& conn,
+                                                   const std::string& user_key,
+                                                   void* buf, size_t len) {
+  as_key key;
+  as_key_init_str(&key, conn.ns.c_str(), conn.set_name.c_str(),
+                  user_key.c_str());
+
+  as_error err;
+  as_record* rec = nullptr;
+  as_status status =
+      aerospike_key_get(conn.client, &err, &conn.read_policy, &key, &rec);
+  if (status == AEROSPIKE_ERR_RECORD_NOT_FOUND) {
+    return false;
+  }
+  if (status != AEROSPIKE_OK) {
+    throw_status("get-payload", status, err);
+  }
+  if (rec == nullptr) {
+    return false;
+  }
+  as_bytes* payload = as_record_get_bytes(rec, kBinPayload);
+  bool ok = payload != nullptr && payload->size == len;
+  if (ok) {
+    std::memcpy(buf, payload->value, payload->size);
+  }
+  as_record_destroy(rec);
+  return ok;
+}
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/aerospike/connector.h b/csrc/storage_backends/aerospike/connector.h
new file mode 100644
index 0000000..f6d23ef
--- /dev/null
+++ b/csrc/storage_backends/aerospike/connector.h
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "../connector_base.h"
+
+#include <aerospike/aerospike.h>
+#include <aerospike/as_policy.h>
+
+#include <cstddef>
+#include <cstdint>
+#include <mutex>
+#include <string>
+#include <vector>
+
+namespace lmcache {
+namespace connector {
+
+struct WorkerAerospikeConn {
+  aerospike* client = nullptr;
+  std::string ns;
+  std::string set_name;
+  as_policy_read read_policy;
+  as_policy_write write_policy;
+  as_policy_remove remove_policy;
+};
+
+struct ShardPlan {
+  uint32_t nseg = 1;
+  size_t seg_b = 0;
+};
+
+// Native Aerospike storage backend.
+//
+// Records use a meta + segment layout: every cache key maps to a meta record
+// (``<key>|m``) carrying the shard plan, and payloads larger than the
+// discovered Aerospike record-size cap are split across segment records
+// (``<key>|s|<i>``). Payloads that fit a single record are stored inline in
+// the meta record. The connector key is used verbatim as the Aerospike user
+// key base (the framework's ObjectKey-to-string format).
+class AerospikeNativeConnector : public ConnectorBase<WorkerAerospikeConn> {
+ public:
+  AerospikeNativeConnector(
+      std::string hosts, std::string ns, std::string set_name, int num_workers,
+      uint32_t read_timeout_ms = 1000, uint32_t write_timeout_ms = 2000,
+      uint32_t default_ttl_seconds = 86400, size_t target_segment_bytes = 0,
+      size_t max_record_bytes = 0, std::string username = "",
+      std::string password = "");
+  ~AerospikeNativeConnector() override;
+
+  void close() override;
+
+ protected:
+  WorkerAerospikeConn create_connection() override;
+  void do_single_get(WorkerAerospikeConn& conn, const std::string& key,
+                     void* buf, size_t len, size_t chunk_size) override;
+  void do_single_set(WorkerAerospikeConn& conn, const std::string& key,
+                     const void* buf, size_t len, size_t chunk_size) override;
+  bool do_single_exists(WorkerAerospikeConn& conn,
+                        const std::string& key) override;
+  bool do_single_delete(WorkerAerospikeConn& conn,
+                        const std::string& key) override;
+  void shutdown_connections() override;
+  void on_workers_stopped() override;
+
+ private:
+  static std::vector<std::pair<std::string, int>> parse_hosts(
+      const std::string& hosts);
+  static std::string meta_user_key(const std::string& cache_key);
+  static std::string segment_user_key(const std::string& cache_key,
+                                      uint32_t index);
+  static void throw_status(const char* op, as_status status,
+                           const as_error& err);
+
+  ShardPlan plan(size_t payload_bytes) const;
+  size_t discover_record_cap();
+  void configure_policies();
+  void put_payload_record(WorkerAerospikeConn& conn,
+                          const std::string& user_key, const void* buf,
+                          size_t len);
+  void put_meta_record(WorkerAerospikeConn& conn, const std::string& user_key,
+                       const ShardPlan& plan, size_t total_bytes,
+                       const void* inline_buf);
+  bool read_payload_record(WorkerAerospikeConn& conn,
+                           const std::string& user_key, void* buf, size_t len);
+
+  std::string hosts_;
+  std::string ns_;
+  std::string set_name_;
+  uint32_t read_timeout_ms_;
+  uint32_t write_timeout_ms_;
+  uint32_t default_ttl_seconds_;
+  size_t target_segment_bytes_;
+  size_t max_record_bytes_;
+  size_t single_record_threshold_bytes_;
+
+  aerospike as_;
+  std::mutex close_mu_;
+  bool connected_ = false;
+  bool closed_native_ = false;
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/aerospike/pybind.cpp b/csrc/storage_backends/aerospike/pybind.cpp
new file mode 100644
index 0000000..df01d70
--- /dev/null
+++ b/csrc/storage_backends/aerospike/pybind.cpp
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <pybind11/pybind11.h>
+#include "../connector_pybind_utils.h"
+#include "connector.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(lmcache_aerospike, m) {
+  m.doc() = "Native Aerospike connector for LMCache";
+
+  py::class_<lmcache::connector::AerospikeNativeConnector>(
+      m, "LMCacheAerospikeClient")
+      .def(py::init<std::string, std::string, std::string, int, uint32_t,
+                    uint32_t, uint32_t, size_t, size_t, std::string,
+                    std::string>(),
+           py::arg("hosts"), py::arg("namespace"), py::arg("set_name"),
+           py::arg("num_workers"), py::arg("read_timeout_ms") = 1000,
+           py::arg("write_timeout_ms") = 2000,
+           py::arg("default_ttl_seconds") = 86400,
+           py::arg("target_segment_bytes") = 0, py::arg("max_record_bytes") = 0,
+           py::arg("username") = "", py::arg("password") = "")
+          LMCACHE_BIND_CONNECTOR_METHODS(
+              lmcache::connector::AerospikeNativeConnector);
+}
diff --git a/csrc/storage_backends/connector_base.h b/csrc/storage_backends/connector_base.h
new file mode 100644
index 0000000..c2cd35a
--- /dev/null
+++ b/csrc/storage_backends/connector_base.h
@@ -0,0 +1,657 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "connector_interface.h"
+#include "connector_types.h"
+#include "event_notifier.h"
+#include <unistd.h>
+#include <algorithm>
+#include <atomic>
+#include <cerrno>
+#include <condition_variable>
+#include <cstdio>
+#include <memory>
+#include <mutex>
+#include <queue>
+#include <stdexcept>
+#include <string>
+#include <thread>
+#include <tuple>
+#include <unordered_map>
+#include <vector>
+
+namespace lmcache {
+namespace connector {
+
+struct WorkerPoolConfig {
+  // Maps lane key (e.g. "lookup", "retrieve", "store") to worker count.
+  // Lane keys not present in this map use the shared num_workers_ pool.
+  std::unordered_map<std::string, int> per_op_workers;
+};
+
+/*
+this base needs to have at least four methods be overridden by the derived
+class:
+- 1. create_connection() e.g. construct TCP socket or RDMA registration
+- 2. do_single_get()
+- 3. do_single_set()
+- 4. do_single_exists()
+
+optionally override do_single_delete() to support eviction (default returns
+false for all keys).
+
+see the RedisConnector (csrc/redis/) implementing the RESP2 protocol over TCP
+for an example
+*/
+template <typename ConnectionType>
+class ConnectorBase : public IStorageConnector {
+ public:
+  ConnectorBase(int num_workers)
+      : ConnectorBase(num_workers, WorkerPoolConfig{}) {}
+
+  ConnectorBase(int num_workers, WorkerPoolConfig worker_pool_config)
+      : num_workers_(num_workers), worker_pool_config_(worker_pool_config) {
+    if (num_workers_ <= 0) {
+      throw std::runtime_error("num_workers must be > 0");
+    }
+    for (auto& [key, count] : worker_pool_config_.per_op_workers) {
+      if (count <= 0) {
+        throw std::runtime_error("per_op_workers count for '" + key +
+                                 "' must be positive");
+      }
+      if (lane_registry().find(key) == lane_registry().end()) {
+        throw std::runtime_error("unknown lane key in per_op_workers: '" + key +
+                                 "'");
+      }
+    }
+
+    // Cross-platform poll-able wakeup fd (eventfd on Linux,
+    // self-pipe on macOS). See event_notifier.h.
+    notifier_ = make_event_notifier();
+  }
+
+  virtual ~ConnectorBase() { close(); }
+
+  ConnectorBase(const ConnectorBase&) = delete;
+  ConnectorBase& operator=(const ConnectorBase&) = delete;
+
+  int event_fd() const override { return notifier_->fileno(); }
+
+  uint64_t submit_batch_get(const std::vector<std::string>& keys,
+                            const std::vector<void*>& bufs,
+                            const std::vector<size_t>& lens,
+                            size_t batch_chunk_num_bytes) override {
+    validate_batch_inputs(keys, bufs, lens);
+
+    size_t num_items = keys.size();
+    auto [batch_future_id, batch_state, num_tiles, tile_size] =
+        prepare_batch_operation(num_items, Op::BATCH_TILE_GET);
+
+    // pre-allocate per-key results for load error tolerance
+    batch_state->per_key_results.assign(num_items, 0);
+
+    // fan out work to threads
+    for (size_t tile_idx = 0; tile_idx < num_tiles; ++tile_idx) {
+      auto tile_req = create_tile_request(
+          keys, bufs, lens, tile_idx, tile_size, num_items, batch_future_id,
+          batch_state, Op::BATCH_TILE_GET, batch_chunk_num_bytes);
+      enqueue_request(std::move(tile_req));
+    }
+
+    return batch_future_id;
+  }
+
+  uint64_t submit_batch_set(const std::vector<std::string>& keys,
+                            const std::vector<void*>& bufs,
+                            const std::vector<size_t>& lens,
+                            size_t batch_chunk_num_bytes) override {
+    validate_batch_inputs(keys, bufs, lens);
+
+    size_t num_items = keys.size();
+    auto [batch_future_id, batch_state, num_tiles, tile_size] =
+        prepare_batch_operation(num_items, Op::BATCH_TILE_SET);
+
+    // fan out work to threads
+    for (size_t tile_idx = 0; tile_idx < num_tiles; ++tile_idx) {
+      auto tile_req = create_tile_request(
+          keys, bufs, lens, tile_idx, tile_size, num_items, batch_future_id,
+          batch_state, Op::BATCH_TILE_SET, batch_chunk_num_bytes);
+      enqueue_request(std::move(tile_req));
+    }
+
+    return batch_future_id;
+  }
+
+  uint64_t submit_batch_exists(const std::vector<std::string>& keys) override {
+    if (keys.empty()) {
+      throw std::runtime_error("keys list is empty");
+    }
+
+    size_t num_items = keys.size();
+    auto [batch_future_id, batch_state, num_tiles, tile_size] =
+        prepare_batch_operation(num_items, Op::BATCH_TILE_EXISTS);
+
+    // pre-allocate results vector with correct size
+    batch_state->per_key_results.assign(num_items, 0);
+
+    // fan out work to threads
+    for (size_t tile_idx = 0; tile_idx < num_tiles; ++tile_idx) {
+      size_t start = tile_idx * tile_size;
+      size_t end = std::min(start + tile_size, num_items);
+
+      Request tile_req;
+      tile_req.op = Op::BATCH_TILE_EXISTS;
+      tile_req.future_id = batch_future_id;
+      tile_req.batch = batch_state;
+      tile_req.start_idx = start;
+
+      for (size_t i = start; i < end; ++i) {
+        tile_req.keys.push_back(keys[i]);
+      }
+
+      enqueue_request(std::move(tile_req));
+    }
+
+    return batch_future_id;
+  }
+
+  uint64_t submit_batch_delete(const std::vector<std::string>& keys) override {
+    if (keys.empty()) {
+      throw std::runtime_error("keys list is empty");
+    }
+
+    size_t num_items = keys.size();
+    auto [batch_future_id, batch_state, num_tiles, tile_size] =
+        prepare_batch_operation(num_items, Op::BATCH_TILE_DELETE);
+
+    // pre-allocate per-key results (1 = deleted, 0 = not found)
+    batch_state->per_key_results.assign(num_items, 0);
+
+    // fan out work to threads
+    for (size_t tile_idx = 0; tile_idx < num_tiles; ++tile_idx) {
+      size_t start = tile_idx * tile_size;
+      size_t end = std::min(start + tile_size, num_items);
+
+      Request tile_req;
+      tile_req.op = Op::BATCH_TILE_DELETE;
+      tile_req.future_id = batch_future_id;
+      tile_req.batch = batch_state;
+      tile_req.start_idx = start;
+
+      for (size_t i = start; i < end; ++i) {
+        tile_req.keys.push_back(keys[i]);
+      }
+
+      enqueue_request(std::move(tile_req));
+    }
+
+    return batch_future_id;
+  }
+
+  std::vector<Completion> drain_completions() override {
+    // Drain the eventfd that triggered this drain_completions callback
+    drain_eventfd_();
+
+    std::vector<Completion> completions_list;
+
+    for (;;) {
+      Completion c;
+      {
+        std::lock_guard<std::mutex> lk(comp_mu_);
+        if (completions_.empty()) {
+          signaled_.store(false, std::memory_order_release);
+          if (!completions_.empty() &&
+              !signaled_.exchange(true, std::memory_order_acq_rel)) {
+            notifier_->notify();
+          }
+          break;
+        }
+
+        c = std::move(completions_.front());
+        completions_.pop();
+      }
+      completions_list.push_back(std::move(c));
+    }
+
+    return completions_list;
+  }
+
+  void close() override {
+    if (closed_.exchange(true, std::memory_order_acq_rel)) {
+      return;  // Already closed
+    }
+
+    // Signal all worker threads to stop
+    stop_.store(true, std::memory_order_release);
+    req_cv_.notify_all();
+    for (auto& [key, lane] : lanes_) {
+      lane->cv.notify_all();
+    }
+
+    // Shutdown all connections (derived class specific)
+    shutdown_connections();
+
+    // Join all worker threads
+    for (auto& worker : workers_) {
+      if (worker.joinable()) {
+        worker.join();
+      }
+    }
+    for (auto& [key, lane] : lanes_) {
+      join_lane_workers(*lane);
+    }
+
+    // Derived cleanup that must only run after workers have stopped.
+    on_workers_stopped();
+
+    // Close wakeup fd
+    if (notifier_) {
+      notifier_->close();
+    }
+
+    // Clear queues (no GIL needed - python guarantees buffers stay alive)
+    {
+      std::lock_guard<std::mutex> lk(req_mu_);
+      while (!requests_.empty()) {
+        requests_.pop();
+      }
+    }
+    for (auto& [key, lane] : lanes_) {
+      clear_lane_queue(*lane);
+    }
+    {
+      std::lock_guard<std::mutex> lk(comp_mu_);
+      while (!completions_.empty()) {
+        completions_.pop();
+      }
+    }
+  }
+
+ protected:
+  // call this at the END of your derived class constructor
+  void start_workers() {
+    // Start dedicated per-op lanes for configured keys.
+    for (auto& [key, count] : worker_pool_config_.per_op_workers) {
+      auto& lane_ptr = lanes_[key];
+      if (!lane_ptr) {
+        lane_ptr = std::make_unique<WorkerLane>();
+      }
+      start_lane_workers(*lane_ptr, count);
+    }
+
+    // Start shared pool if any lane key in the registry is not configured.
+    bool need_shared = false;
+    for (auto& [key, ops] : lane_registry()) {
+      if (worker_pool_config_.per_op_workers.find(key) ==
+          worker_pool_config_.per_op_workers.end()) {
+        need_shared = true;
+        break;
+      }
+    }
+
+    if (need_shared) {
+      workers_.reserve(static_cast<size_t>(num_workers_));
+      for (int i = 0; i < num_workers_; i++) {
+        workers_.emplace_back([this]() { this->worker_loop(); });
+      }
+    }
+  }
+
+  virtual ConnectionType create_connection() = 0;
+  virtual void do_single_get(ConnectionType& conn, const std::string& key,
+                             void* buf, size_t len, size_t chunk_size) = 0;
+  virtual void do_single_set(ConnectionType& conn, const std::string& key,
+                             const void* buf, size_t len,
+                             size_t chunk_size) = 0;
+  virtual bool do_single_exists(ConnectionType& conn,
+                                const std::string& key) = 0;
+  virtual bool do_single_delete(ConnectionType& conn, const std::string& key) {
+    (void)conn;
+    (void)key;
+    return false;  // no-op default for backward compat with plugins
+  }
+  virtual size_t choose_num_tiles(Op op, size_t num_items) const {
+    return std::min<size_t>(worker_count_for_op(op), num_items);
+  }
+  virtual void do_batch_get(ConnectionType& conn, const Request& req) {
+    for (size_t i = 0; i < req.keys.size(); ++i) {
+      try {
+        do_single_get(conn, req.keys[i], req.buf_ptrs[i], req.buf_lens[i],
+                      req.batch_chunk_num_bytes);
+        req.batch->per_key_results[req.start_idx + i] = 1;
+      } catch (const std::exception& e) {
+        req.batch->per_key_results[req.start_idx + i] = 0;
+        fprintf(stderr, "[LMCache GET] key %s failed: %s\n",
+                req.keys[i].c_str(), e.what());
+      }
+    }
+  }
+  virtual void do_batch_set(ConnectionType& conn, const Request& req) {
+    for (size_t i = 0; i < req.keys.size(); ++i) {
+      do_single_set(conn, req.keys[i], req.buf_ptrs[i], req.buf_lens[i],
+                    req.batch_chunk_num_bytes);
+    }
+  }
+  virtual void do_batch_exists(ConnectionType& conn, const Request& req) {
+    for (size_t i = 0; i < req.keys.size(); ++i) {
+      bool exists = do_single_exists(conn, req.keys[i]);
+      req.batch->per_key_results[req.start_idx + i] = exists ? 1 : 0;
+    }
+  }
+  virtual void do_batch_delete(ConnectionType& conn, const Request& req) {
+    for (size_t i = 0; i < req.keys.size(); ++i) {
+      try {
+        bool deleted = do_single_delete(conn, req.keys[i]);
+        req.batch->per_key_results[req.start_idx + i] = deleted ? 1 : 0;
+      } catch (const std::exception& e) {
+        req.batch->per_key_results[req.start_idx + i] = 0;
+        fprintf(stderr, "[LMCache DELETE] key %s failed: %s\n",
+                req.keys[i].c_str(), e.what());
+      }
+    }
+  }
+  virtual void shutdown_connections() {}
+  virtual void on_workers_stopped() {}
+
+  bool is_stopping() const { return stop_.load(std::memory_order_acquire); }
+
+  int worker_count_for_op(Op op) const {
+    const std::string& key = lane_key_for_op(op);
+    auto it = worker_pool_config_.per_op_workers.find(key);
+    if (it != worker_pool_config_.per_op_workers.end()) {
+      return it->second;
+    }
+    return num_workers_;
+  }
+
+ private:
+  struct WorkerLane {
+    std::mutex mu;
+    std::condition_variable cv;
+    std::queue<Request> requests;
+    std::vector<std::thread> workers;
+  };
+
+  void validate_batch_inputs(const std::vector<std::string>& keys,
+                             const std::vector<void*>& bufs,
+                             const std::vector<size_t>& lens) {
+    if (keys.size() != bufs.size() || keys.size() != lens.size()) {
+      throw std::runtime_error("keys, bufs, and lens size mismatch");
+    }
+    if (keys.empty()) {
+      throw std::runtime_error("keys list is empty");
+    }
+  }
+
+  // returns: (batch_future_id, batch_state, num_tiles, tile_size)
+  std::tuple<uint64_t, std::shared_ptr<BatchState>, size_t, size_t>
+  prepare_batch_operation(size_t num_items, Op op) {
+    size_t num_tiles = choose_num_tiles(op, num_items);
+    if (num_tiles == 0 || num_tiles > num_items) {
+      throw std::runtime_error(
+          "choose_num_tiles must return a value in [1, num_items]");
+    }
+    size_t tile_size = (num_items + num_tiles - 1) / num_tiles;  // round up
+
+    // create shared batch state
+    uint64_t batch_future_id =
+        next_future_id_.fetch_add(1, std::memory_order_relaxed);
+    auto batch_state = std::make_shared<BatchState>();
+    batch_state->remaining_tiles.store(num_tiles, std::memory_order_relaxed);
+    batch_state->batch_op = op;
+
+    return {batch_future_id, batch_state, num_tiles, tile_size};
+  }
+
+  Request create_tile_request(const std::vector<std::string>& keys,
+                              const std::vector<void*>& bufs,
+                              const std::vector<size_t>& lens, size_t tile_idx,
+                              size_t tile_size, size_t num_items,
+                              uint64_t batch_future_id,
+                              std::shared_ptr<BatchState> batch_state, Op op,
+                              size_t batch_chunk_num_bytes) {
+    size_t start = tile_idx * tile_size;
+    size_t end = std::min(start + tile_size, num_items);  // clip last tile
+
+    Request tile_req;
+    tile_req.op = op;
+    tile_req.future_id = batch_future_id;
+    tile_req.batch = batch_state;
+    tile_req.batch_chunk_num_bytes = batch_chunk_num_bytes;
+    tile_req.start_idx = start;
+
+    for (size_t i = start; i < end; ++i) {
+      tile_req.keys.push_back(keys[i]);
+      tile_req.buf_ptrs.push_back(bufs[i]);
+      tile_req.buf_lens.push_back(lens[i]);
+    }
+
+    return tile_req;
+  }
+
+  void enqueue_request(Request&& req) {
+    const std::string& key = lane_key_for_op(req.op);
+    auto it = lanes_.find(key);
+    if (it != lanes_.end()) {
+      {
+        std::lock_guard<std::mutex> lk(it->second->mu);
+        it->second->requests.push(std::move(req));
+      }
+      it->second->cv.notify_one();
+      return;
+    }
+
+    {
+      std::lock_guard<std::mutex> lk(req_mu_);
+      requests_.push(std::move(req));
+    }
+    req_cv_.notify_one();
+  }
+
+  void push_completion(Completion&& c) {
+    {
+      std::lock_guard<std::mutex> lk(comp_mu_);
+      completions_.push(std::move(c));
+    }
+    signal_eventfd_();
+  }
+
+  void drain_eventfd_() { notifier_->consume(); }
+
+  void signal_eventfd_() {
+    bool already_signaled = signaled_.exchange(true, std::memory_order_acq_rel);
+    if (already_signaled) return;  // only one signal at a time
+    notifier_->notify();
+  }
+
+  static const std::unordered_map<std::string, std::vector<Op>>&
+  lane_registry() {
+    static const std::unordered_map<std::string, std::vector<Op>> registry = {
+        {"lookup", {Op::BATCH_TILE_EXISTS}},
+        {"retrieve", {Op::BATCH_TILE_GET}},
+        {"store", {Op::BATCH_TILE_SET}},
+        {"delete", {Op::BATCH_TILE_DELETE}},
+    };
+    return registry;
+  }
+
+  static const std::string& lane_key_for_op(Op op) {
+    static const auto& reverse = []() {
+      std::unordered_map<Op, std::string> m;
+      for (auto& [key, ops] : lane_registry()) {
+        for (Op o : ops) {
+          m[o] = key;
+        }
+      }
+      return m;
+    }();
+    auto it = reverse.find(op);
+    if (it == reverse.end()) {
+      throw std::runtime_error("unknown Op type: " +
+                               std::to_string(static_cast<int>(op)));
+    }
+    return it->second;
+  }
+
+  void start_lane_workers(WorkerLane& lane, int num_workers) {
+    lane.workers.reserve(static_cast<size_t>(num_workers));
+    WorkerLane* lane_ptr = &lane;
+    for (int i = 0; i < num_workers; i++) {
+      lane.workers.emplace_back([this, lane_ptr]() {
+        this->worker_loop_for_queue(lane_ptr->mu, lane_ptr->cv,
+                                    lane_ptr->requests);
+      });
+    }
+  }
+
+  void join_lane_workers(WorkerLane& lane) {
+    for (auto& worker : lane.workers) {
+      if (worker.joinable()) {
+        worker.join();
+      }
+    }
+  }
+
+  void clear_lane_queue(WorkerLane& lane) {
+    std::lock_guard<std::mutex> lk(lane.mu);
+    while (!lane.requests.empty()) {
+      lane.requests.pop();
+    }
+  }
+
+  void worker_loop() { worker_loop_for_queue(req_mu_, req_cv_, requests_); }
+
+  void worker_loop_for_queue(std::mutex& req_mu,
+                             std::condition_variable& req_cv,
+                             std::queue<Request>& requests) {
+    try {
+      // create connection (derived class specific)
+      ConnectionType conn = create_connection();
+
+      for (;;) {
+        Request req;
+
+        // 1. grab a request from the submission queue
+        {
+          std::unique_lock<std::mutex> lk(req_mu);
+          req_cv.wait(lk, [&] {
+            return stop_.load(std::memory_order_acquire) || !requests.empty();
+          });
+          if (stop_.load(std::memory_order_acquire) && requests.empty()) {
+            break;  // exit loop
+          }
+          req = std::move(requests.front());
+          requests.pop();
+        }
+
+        Completion comp;
+        comp.future_id = req.future_id;
+
+        // 2. execute the requested operation
+        try {
+          switch (req.op) {
+            case Op::BATCH_TILE_GET:
+              do_batch_get(conn, req);
+              comp.ok = true;
+              break;
+
+            case Op::BATCH_TILE_SET:
+              do_batch_set(conn, req);
+              comp.ok = true;
+              break;
+
+            case Op::BATCH_TILE_EXISTS:
+              do_batch_exists(conn, req);
+              comp.ok = true;
+              break;
+
+            case Op::BATCH_TILE_DELETE:
+              do_batch_delete(conn, req);
+              comp.ok = true;
+              break;
+          }
+        } catch (const std::exception& e) {
+          comp.ok = false;
+          comp.error = e.what();
+          // if shutting down, errors are expected
+          if (stop_.load(std::memory_order_acquire)) {
+            break;  // exit without pushing completion
+          }
+        }
+
+        // 3. update shared batch state and push completion when done
+        handle_tile_completion(req, comp);
+      }
+    } catch (const std::exception& e) {
+      fprintf(stderr, "[LMCache Connector Worker Error] %s\n", e.what());
+    } catch (...) {
+      fprintf(stderr, "[LMCache Connector Worker Error] Unknown exception\n");
+    }
+  }
+
+  void handle_tile_completion(const Request& req, const Completion& comp) {
+    // record failure if any
+    if (!comp.ok) {
+      req.batch->any_failed.store(true, std::memory_order_relaxed);
+      std::lock_guard<std::mutex> lk(req.batch->err_mu);
+      if (req.batch->first_error.empty()) {
+        req.batch->first_error = comp.error;
+      }
+    }
+
+    // check if this is the last tile to complete
+    uint32_t tiles_left =
+        req.batch->remaining_tiles.fetch_sub(1, std::memory_order_relaxed) - 1;
+
+    if (tiles_left == 0) {
+      // last tile to finish - emit single completion for entire batch
+      Completion batch_comp;
+      batch_comp.future_id = req.future_id;
+      batch_comp.ok = !req.batch->any_failed.load(std::memory_order_relaxed);
+      if (!batch_comp.ok) {
+        std::lock_guard<std::mutex> lk(req.batch->err_mu);
+        batch_comp.error = req.batch->first_error;
+      }
+      // for batch exists and batch get, move per-key results
+      if (req.batch->batch_op == Op::BATCH_TILE_EXISTS ||
+          req.batch->batch_op == Op::BATCH_TILE_GET ||
+          req.batch->batch_op == Op::BATCH_TILE_DELETE) {
+        batch_comp.result_bytes = std::move(req.batch->per_key_results);
+      }
+      push_completion(std::move(batch_comp));
+    }
+  }
+
+ protected:
+  int num_workers_;
+  WorkerPoolConfig worker_pool_config_;
+
+  std::atomic<bool> stop_{false};
+  std::atomic<bool> closed_{false};
+  std::atomic<uint64_t> next_future_id_{1};
+
+ private:
+  std::unique_ptr<EventNotifier> notifier_;
+
+  // treat wakeup fd as a binary wakeup flag:
+  // true: Python has been signaled (or will be)
+  // false: Python is asleep, no wakeup pending
+  std::atomic<bool> signaled_{false};
+
+  // submission queue (SQ)
+  std::mutex req_mu_;
+  std::condition_variable req_cv_;
+  std::queue<Request> requests_;
+
+  // completion queue (CQ)
+  std::mutex comp_mu_;
+  std::queue<Completion> completions_;
+
+  std::vector<std::thread> workers_;
+  // Populated only during start_workers() (single-threaded construction).
+  // All subsequent accesses are reads — no lock needed in enqueue_request.
+  std::unordered_map<std::string, std::unique_ptr<WorkerLane>> lanes_;
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/connector_interface.h b/csrc/storage_backends/connector_interface.h
new file mode 100644
index 0000000..9f5de15
--- /dev/null
+++ b/csrc/storage_backends/connector_interface.h
@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "connector_types.h"
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace lmcache {
+namespace connector {
+
+/*
+instantiated in connector_base.h and further overridden by custom storage
+connectors
+*/
+class IStorageConnector {
+ public:
+  virtual ~IStorageConnector() = default;
+
+  virtual int event_fd() const = 0;
+
+  /*
+  submit a batch GET operation
+
+  retrieves values for multiple keys in parallel. work is automatically divided
+  among worker threads (tiling). returns a single future_id for the entire
+  batch.
+
+  args:
+    keys: vector of key strings to retrieve
+    bufs: vector of buffer pointers (must be writable, size ==
+  batch_chunk_num_bytes for each buffer) lens: vector of buffer sizes (each must
+  equal batch_chunk_num_bytes) batch_chunk_num_bytes: expected size of each
+  value (optimization: avoids parsing)
+
+  returns:
+    uint64_t: future id for tracking this batch operation
+  */
+  virtual uint64_t submit_batch_get(const std::vector<std::string>& keys,
+                                    const std::vector<void*>& bufs,
+                                    const std::vector<size_t>& lens,
+                                    size_t batch_chunk_num_bytes) = 0;
+
+  /*
+  submit a batch SET operation
+
+  stores values for multiple keys in parallel. work is automatically divided
+  among worker threads (tiling). returns a single future_id for the entire
+  batch.
+
+  args:
+    keys: vector of key strings to store
+      bufs: vector of buffer pointers (must be readable, size ==
+  batch_chunk_num_bytes for each buffer) lens: vector of buffer sizes (each must
+  equal batch_chunk_num_bytes) batch_chunk_num_bytes: size of each value
+  (optimization: avoids parsing)
+
+  returns:
+    uint64_t: future id for tracking this batch operation
+  */
+  virtual uint64_t submit_batch_set(const std::vector<std::string>& keys,
+                                    const std::vector<void*>& bufs,
+                                    const std::vector<size_t>& lens,
+                                    size_t batch_chunk_num_bytes) = 0;
+
+  /*
+  submit a batch EXISTS operation
+
+  checks existence of multiple keys in parallel. work is automatically divided
+  among worker threads (tiling). returns a single future_id for the entire
+  batch.
+
+  args:
+    keys: vector of key strings to check
+
+  returns:
+    uint64_t: future id for tracking this batch operation
+    completion will contain result_bytes vector with 0/1 for each key
+  */
+  virtual uint64_t submit_batch_exists(
+      const std::vector<std::string>& keys) = 0;
+
+  /*
+  submit a batch DELETE operation
+
+  deletes multiple keys in parallel. work is automatically divided
+  among worker threads (tiling). returns a single future_id for the entire
+  batch.
+
+  args:
+    keys: vector of key strings to delete
+
+  returns:
+    uint64_t: future id for tracking this batch operation
+    completion will contain result_bytes vector with 0/1 for each key
+    (1 = deleted, 0 = not found)
+  */
+  virtual uint64_t submit_batch_delete(
+      const std::vector<std::string>& keys) = 0;
+
+  /*
+  drain all available completions
+
+  this is the ONLY method that should be called when the eventfd becomes
+  readable. it automatically drains the eventfd and returns all available
+  completions.
+
+  returns:
+    std::vector<Completion>: all completions ready since last drain
+  */
+  virtual std::vector<Completion> drain_completions() = 0;
+
+  /*
+  shutdown the connector and cleanup resources
+
+  this method:
+  1. signals all worker threads to stop
+  2. wakes up blocked workers
+  3. shuts down network connections
+  4. joins all worker threads
+  5. closes eventfd
+  6. clears pending requests and completions
+
+  idempotent: safe to call multiple times (subsequent calls are no-ops)
+  */
+  virtual void close() = 0;
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/connector_pybind_utils.h b/csrc/storage_backends/connector_pybind_utils.h
new file mode 100644
index 0000000..49dd146
--- /dev/null
+++ b/csrc/storage_backends/connector_pybind_utils.h
@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "connector_base.h"
+#include "connector_interface.h"
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace py = pybind11;
+
+namespace lmcache {
+namespace connector {
+namespace pybind_utils {
+
+/*
+these utilities:
+1. convert between cpp and python types
+2. release GIL immediately after extracting buffer pointers
+
+example usage (see `redis/pybind.cpp`):
+  py::class_<MyConnector>(m, "MyConnectorClient")
+      .def(py::init<...>(), ...)
+      LMCACHE_BIND_CONNECTOR_METHODS(MyConnector);
+*/
+
+#define LMCACHE_BIND_CONNECTOR_METHODS(ConnectorType)                  \
+  .def("event_fd", &ConnectorType::event_fd)                           \
+      .def("submit_batch_get",                                         \
+           lmcache::connector::pybind_utils::bind_submit_batch_get<    \
+               ConnectorType>(),                                       \
+           py::arg("keys"), py::arg("memoryviews"))                    \
+      .def("submit_batch_set",                                         \
+           lmcache::connector::pybind_utils::bind_submit_batch_set<    \
+               ConnectorType>(),                                       \
+           py::arg("keys"), py::arg("memoryviews"))                    \
+      .def("submit_batch_exists",                                      \
+           lmcache::connector::pybind_utils::bind_submit_batch_exists< \
+               ConnectorType>(),                                       \
+           py::arg("keys"))                                            \
+      .def("submit_batch_delete",                                      \
+           lmcache::connector::pybind_utils::bind_submit_batch_delete< \
+               ConnectorType>(),                                       \
+           py::arg("keys"))                                            \
+      .def("drain_completions",                                        \
+           lmcache::connector::pybind_utils::bind_drain_completions<   \
+               ConnectorType>())                                       \
+      .def("close", &ConnectorType::close)
+
+template <typename ConnectorType>
+auto bind_submit_batch_get() {
+  return [](ConnectorType& self, const std::vector<std::string>& keys,
+            py::list memviews) {
+    if (keys.size() != memviews.size()) {
+      throw std::runtime_error("keys and memviews size mismatch");
+    }
+    if (keys.empty()) {
+      throw std::runtime_error("keys list is empty");
+    }
+
+    // extract all buffer info under GIL
+    std::vector<void*> bufs;
+    std::vector<size_t> lens;
+    bufs.reserve(keys.size());
+    lens.reserve(keys.size());
+
+    for (size_t i = 0; i < keys.size(); ++i) {
+      py::memoryview mv = memviews[i].cast<py::memoryview>();
+      py::buffer_info info = py::buffer(mv).request();
+      bufs.push_back(info.ptr);
+      lens.push_back(static_cast<size_t>(info.size));
+    }
+
+    // use the first buffer's size as batch_chunk_num_bytes (all must match)
+    size_t batch_chunk_num_bytes = lens[0];
+
+    py::gil_scoped_release release;
+    return self.submit_batch_get(keys, bufs, lens, batch_chunk_num_bytes);
+  };
+}
+
+template <typename ConnectorType>
+auto bind_submit_batch_set() {
+  return [](ConnectorType& self, const std::vector<std::string>& keys,
+            py::list memviews) {
+    if (keys.size() != memviews.size()) {
+      throw std::runtime_error("keys and memviews size mismatch");
+    }
+    if (keys.empty()) {
+      throw std::runtime_error("keys list is empty");
+    }
+
+    // extract all buffer info under GIL
+    std::vector<void*> bufs;
+    std::vector<size_t> lens;
+    bufs.reserve(keys.size());
+    lens.reserve(keys.size());
+
+    for (size_t i = 0; i < keys.size(); ++i) {
+      py::memoryview mv = memviews[i].cast<py::memoryview>();
+      py::buffer_info info = py::buffer(mv).request();
+      bufs.push_back(info.ptr);
+      lens.push_back(static_cast<size_t>(info.size));
+    }
+
+    // use the first buffer's size as batch_chunk_num_bytes (all must match)
+    size_t batch_chunk_num_bytes = lens[0];
+
+    py::gil_scoped_release release;
+    return self.submit_batch_set(keys, bufs, lens, batch_chunk_num_bytes);
+  };
+}
+
+template <typename ConnectorType>
+auto bind_submit_batch_exists() {
+  return [](ConnectorType& self, const std::vector<std::string>& keys) {
+    py::gil_scoped_release release;
+    return self.submit_batch_exists(keys);
+  };
+}
+
+template <typename ConnectorType>
+auto bind_submit_batch_delete() {
+  return [](ConnectorType& self, const std::vector<std::string>& keys) {
+    py::gil_scoped_release release;
+    return self.submit_batch_delete(keys);
+  };
+}
+
+template <typename ConnectorType>
+auto bind_drain_completions() {
+  return [](ConnectorType& self) {
+    // call cpp method without holding GIL
+    std::vector<Completion> completions;
+    {
+      py::gil_scoped_release release;
+      completions = self.drain_completions();
+    }
+
+    // convert results to python objects (requires GIL)
+    py::list result;
+    for (auto& c : completions) {
+      // convert result_bytes to python list of bools if not empty
+      py::object bools_obj = py::none();
+      if (!c.result_bytes.empty()) {
+        py::list bools_list;
+        for (uint8_t b : c.result_bytes) {
+          bools_list.append(bool(b));
+        }
+        bools_obj = bools_list;
+      }
+
+      // return tuple: (future_id, ok, error, result_bools)
+      result.append(py::make_tuple(c.future_id, c.ok, c.error, bools_obj));
+    }
+
+    return result;
+  };
+}
+inline WorkerPoolConfig parse_per_op_workers(const py::object& obj) {
+  if (obj.is_none()) {
+    return {};
+  }
+  py::dict d = obj.cast<py::dict>();
+  std::unordered_map<std::string, int> per_op;
+  for (auto& [key, value] : d) {
+    std::string key_str = key.cast<std::string>();
+    int count = value.cast<int>();
+    if (count <= 0) {
+      throw std::runtime_error("per_op_workers['" + key_str +
+                               "'] must be a positive integer");
+    }
+    per_op[key_str] = count;
+  }
+  return {std::move(per_op)};
+}
+
+}  // namespace pybind_utils
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/connector_types.h b/csrc/storage_backends/connector_types.h
new file mode 100644
index 0000000..35b5d75
--- /dev/null
+++ b/csrc/storage_backends/connector_types.h
@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <vector>
+
+// there are four "types" in this file:
+// 1. Op: enum class for the three batched operations (GET, SET, EXISTS)
+// 2. BatchState: shared communication state between threads executing a single
+// batch operation
+// 3. Request: the request data structure for a single operation (submitted to
+// SQ)
+// 4. Completion: the completion data structure for a single operation
+// (collected from CQ)
+
+namespace lmcache {
+namespace connector {
+
+// we only support batched operations
+// benefits are fewer submissions and fewer completions
+enum class Op : uint8_t {
+  BATCH_TILE_GET,
+  BATCH_TILE_SET,
+  BATCH_TILE_EXISTS,
+  BATCH_TILE_DELETE
+};
+
+/*
+shared communication state between threads executing a single batch operation.
+all threads need to complete before the completion is sent.
+
+tiling refers to dividing work for batched operations between threads
+beforehand.
+*/
+struct BatchState {
+  std::atomic<uint32_t> remaining_tiles{0};
+  std::atomic<bool> any_failed{false};
+
+  std::mutex err_mu;
+  std::string first_error;
+
+  // Per-key success/failure results used by both EXISTS and GET.
+  // For EXISTS: 1 = key found, 0 = not found.
+  // For GET: 1 = read succeeded, 0 = read failed (e.g. file
+  //   not found).  This enables per-key error tolerance on loads.
+  // IMPORTANT: not vector<bool> due to concurrent write data race
+  std::vector<uint8_t> per_key_results;
+
+  Op batch_op;
+};
+
+/*
+LIFETIME GUARANTEE:
+we have a strict assumption that Python will NOT clean up any buffer memory
+before all C++ operations finish. This is guaranteed by the Python-side design
+where the caller holds references to all buffers until drain_completions()
+returns the corresponding future_id. Therefore, we do NOT need to track
+buf_owner references or acquire the GIL to prevent premature cleanup.
+we can safely use raw pointers extracted under the GIL without additional
+lifetime management on the C++ side.
+*/
+
+struct Request {
+  uint64_t future_id = 0;
+  Op op;
+
+  // all operations use the batched structure (even single-item operations
+  // are treated as batches of size 1)
+  std::vector<std::string> keys;
+  std::vector<void*> buf_ptrs;
+  std::vector<size_t> buf_lens;
+
+  // shared batch state between threads executing a single batch operation
+  // so that they can coordinate when to send the completion
+  std::shared_ptr<BatchState> batch;
+
+  // for batch exists tiles, track which indices this tile is responsible for
+  size_t start_idx = 0;
+
+  // batch_chunk_num_bytes for get/set operations (passed per-operation, not
+  // per-connection)
+  size_t batch_chunk_num_bytes = 0;
+};
+
+struct Completion {
+  uint64_t future_id = 0;
+
+  bool ok = true;
+
+  // for EXISTS operations, store boolean results as
+  // bytes (0/1). Single EXISTS will have 1 element, batch EXISTS will have N
+  // elements. No result in the completion for SET and GET.
+  std::vector<uint8_t> result_bytes;
+
+  std::string error;
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/event_notifier.h b/csrc/storage_backends/event_notifier.h
new file mode 100644
index 0000000..5fc5506
--- /dev/null
+++ b/csrc/storage_backends/event_notifier.h
@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+// Cross-platform event notification abstraction (C++ mirror of
+// lmcache/v1/platform/event_notifier.py). Provides a unified
+// EventNotifier interface for signaling between threads using a
+// poll-able file descriptor.
+//
+// On Linux we use eventfd(2); on macOS / other POSIX we fall back
+// to a self-pipe with non-blocking I/O. Connector code stays
+// platform-agnostic — only this header has #if branches.
+
+#include <fcntl.h>
+#include <unistd.h>
+#include <cerrno>
+#include <cstdint>
+#include <memory>
+#include <stdexcept>
+
+#if defined(__linux__)
+  #include <sys/eventfd.h>
+#endif
+
+namespace lmcache {
+namespace connector {
+
+// Abstract base: a binary signal that a listener can poll() on.
+// notify() makes fileno() readable; consume() resets it. Multiple
+// notify() calls before a consume() are coalesced.
+class EventNotifier {
+ public:
+  virtual ~EventNotifier() = default;
+
+  // Poll-able file descriptor. Becomes readable after notify().
+  virtual int fileno() const = 0;
+
+  // Signal the notifier (idempotent if already signaled).
+  virtual void notify() = 0;
+
+  // Consume any pending signal (non-blocking). EAGAIN/EWOULDBLOCK
+  // is the only swallowed error; other OS errors propagate.
+  virtual void consume() = 0;
+
+  // Release underlying OS resources. Idempotent.
+  virtual void close() = 0;
+
+  EventNotifier() = default;
+  EventNotifier(const EventNotifier&) = delete;
+  EventNotifier& operator=(const EventNotifier&) = delete;
+};
+
+#if defined(__linux__)
+
+// Linux eventfd-based notifier.
+class EventfdNotifier final : public EventNotifier {
+ public:
+  EventfdNotifier() {
+    efd_ = ::eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC);
+    if (efd_ < 0) {
+      throw std::runtime_error("failed to create eventfd");
+    }
+  }
+
+  ~EventfdNotifier() override { close(); }
+
+  int fileno() const override { return efd_; }
+
+  void notify() override {
+    uint64_t one = 1;
+    for (;;) {
+      ssize_t w = ::write(efd_, &one, sizeof(one));
+      if (w == static_cast<ssize_t>(sizeof(one))) return;
+      if (w < 0) {
+        if (errno == EINTR) continue;
+        if (errno == EAGAIN || errno == EWOULDBLOCK) return;
+        throw std::runtime_error("eventfd write failed unexpectedly");
+      }
+      throw std::runtime_error("partial write to eventfd");
+    }
+  }
+
+  void consume() override {
+    for (;;) {
+      uint64_t x;
+      ssize_t r = ::read(efd_, &x, sizeof(x));
+      if (r == static_cast<ssize_t>(sizeof(x))) continue;
+      if (r < 0 && errno == EINTR) continue;
+      break;  // drained or non-EINTR error (EAGAIN expected)
+    }
+  }
+
+  void close() override {
+    if (efd_ >= 0) {
+      ::close(efd_);
+      efd_ = -1;
+    }
+  }
+
+ private:
+  int efd_ = -1;
+};
+
+#endif  // __linux__
+
+// Pipe-based fallback notifier (macOS / other POSIX).
+class PipeNotifier final : public EventNotifier {
+ public:
+  PipeNotifier() {
+    int fds[2];
+    if (::pipe(fds) != 0) {
+      throw std::runtime_error("failed to create pipe");
+    }
+    for (int i = 0; i < 2; ++i) {
+      int flags = ::fcntl(fds[i], F_GETFL, 0);
+      if (flags < 0 || ::fcntl(fds[i], F_SETFL, flags | O_NONBLOCK) < 0 ||
+          ::fcntl(fds[i], F_SETFD, FD_CLOEXEC) < 0) {
+        ::close(fds[0]);
+        ::close(fds[1]);
+        throw std::runtime_error("failed to configure pipe fd flags");
+      }
+    }
+    read_fd_ = fds[0];
+    write_fd_ = fds[1];
+  }
+
+  ~PipeNotifier() override { close(); }
+
+  int fileno() const override { return read_fd_; }
+
+  void notify() override {
+    const uint8_t one = 1;
+    for (;;) {
+      ssize_t w = ::write(write_fd_, &one, sizeof(one));
+      if (w == 1) return;
+      if (w < 0) {
+        if (errno == EINTR) continue;
+        // Pipe full = signal already pending; readers will see it.
+        if (errno == EAGAIN || errno == EWOULDBLOCK) return;
+        throw std::runtime_error("pipe write failed unexpectedly");
+      }
+    }
+  }
+
+  void consume() override {
+    uint8_t buf[256];
+    for (;;) {
+      ssize_t r = ::read(read_fd_, buf, sizeof(buf));
+      if (r > 0) continue;
+      if (r < 0 && errno == EINTR) continue;
+      break;  // drained, EOF, or EAGAIN
+    }
+  }
+
+  void close() override {
+    if (read_fd_ >= 0) {
+      ::close(read_fd_);
+      read_fd_ = -1;
+    }
+    if (write_fd_ >= 0) {
+      ::close(write_fd_);
+      write_fd_ = -1;
+    }
+  }
+
+ private:
+  int read_fd_ = -1;
+  int write_fd_ = -1;
+};
+
+// Factory: returns the platform-appropriate notifier.
+inline std::unique_ptr<EventNotifier> make_event_notifier() {
+#if defined(__linux__)
+  return std::unique_ptr<EventNotifier>(new EventfdNotifier());
+#else
+  return std::unique_ptr<EventNotifier>(new PipeNotifier());
+#endif
+}
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/fs/connector.cpp b/csrc/storage_backends/fs/connector.cpp
new file mode 100644
index 0000000..e54d98f
--- /dev/null
+++ b/csrc/storage_backends/fs/connector.cpp
@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "connector.h"
+#include <cerrno>
+#include <cstdio>
+#include <stdexcept>
+#include <string>
+
+namespace lmcache {
+namespace connector {
+
+// ---------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------
+
+std::string FSConnector::replace_all(const std::string& str,
+                                     const std::string& from,
+                                     const std::string& to) {
+  std::string result = str;
+  size_t pos = 0;
+  while ((pos = result.find(from, pos)) != std::string::npos) {
+    result.replace(pos, from.size(), to);
+    pos += to.size();
+  }
+  return result;
+}
+
+std::string FSConnector::key_to_filename(const std::string& key) {
+  // Input key format (from _object_key_to_string):
+  //   Unsalted: <model_name>@<kv_rank_hex>@<chunk_hash_hex>
+  //   Salted  : <model_name>@<kv_rank_hex>@<chunk_hash_hex>@<cache_salt>
+  //
+  // Output filename (matching fs_l2_adapter.py._object_key_to_filename):
+  //   Unsalted: <model_name_safe>@0x<kv_rank_hex>@<chunk_hash_hex>.data
+  //   Salted  :
+  //   <model_name_safe>@0x<kv_rank_hex>@<chunk_hash_hex>@<cache_salt>.data
+  //
+  // The unsalted 3-field shape is bit-identical to the pre-cache_salt
+  // format, so existing cache directories remain valid.
+  //
+  // NOTE: both model_name and cache_salt are forbidden from containing
+  // '@' (invariant enforced on the Python side), so splitting on '@'
+  // is unambiguous — no marker, no rsplit.
+
+  // Split on '@' — must yield 3 (unsalted) or 4 (salted) fields.
+  std::vector<std::string> parts;
+  size_t start = 0;
+  for (size_t pos = 0; pos <= key.size(); ++pos) {
+    if (pos == key.size() || key[pos] == KEY_SEP) {
+      parts.emplace_back(key.substr(start, pos - start));
+      start = pos + 1;
+    }
+  }
+  if (parts.size() != 3 && parts.size() != 4) {
+    throw std::runtime_error(
+        "FSConnector: malformed key (expected 3 or 4 '@'-separated fields): " +
+        key);
+  }
+
+  const std::string& model_name = parts[0];
+  const std::string& kv_rank_hex = parts[1];
+  const std::string& chunk_hash = parts[2];
+  const std::string cache_salt = parts.size() == 4 ? parts[3] : std::string();
+
+  // Replace '/' with '-SEP-' for filesystem safety
+  std::string safe_model = replace_all(model_name, "/", PATH_SLASH_REPLACEMENT);
+
+  // Emit filename. Salt is appended at the tail so the unsalted shape
+  // matches what older builds wrote to disk.
+  std::string result;
+  result.reserve(safe_model.size() + kv_rank_hex.size() + chunk_hash.size() +
+                 cache_salt.size() + 32);
+  result += safe_model;
+  result += KEY_SEP;
+  result += "0x";
+  result += kv_rank_hex;
+  result += KEY_SEP;
+  result += chunk_hash;
+  if (!cache_salt.empty()) {
+    result += KEY_SEP;
+    result += cache_salt;
+  }
+  result += FILE_EXT;
+  return result;
+}
+
+// ---------------------------------------------------------------
+// read/write helpers
+// ---------------------------------------------------------------
+
+static void write_all(int fd, const void* data, size_t len) {
+  size_t written = 0;
+  const char* ptr = static_cast<const char*>(data);
+  while (written < len) {
+    ssize_t n = ::write(fd, ptr + written, len - written);
+    if (n < 0) {
+      if (errno == EINTR) continue;
+      throw std::runtime_error("write failed: " + std::string(strerror(errno)));
+    }
+    if (n == 0) {
+      throw std::runtime_error("write returned 0");
+    }
+    written += static_cast<size_t>(n);
+  }
+}
+
+static size_t read_all(int fd, void* buf, size_t len) {
+  size_t total = 0;
+  char* ptr = static_cast<char*>(buf);
+  while (total < len) {
+    ssize_t n = ::read(fd, ptr + total, len - total);
+    if (n < 0) {
+      if (errno == EINTR) continue;
+      throw std::runtime_error("read failed: " + std::string(strerror(errno)));
+    }
+    if (n == 0) break;  // EOF
+    total += static_cast<size_t>(n);
+  }
+  return total;
+}
+
+// ---------------------------------------------------------------
+// FSConnector
+// ---------------------------------------------------------------
+
+FSConnector::FSConnector(std::string base_path, int num_workers,
+                         std::string relative_tmp_dir, bool use_odirect,
+                         size_t read_ahead_size)
+    : ConnectorBase(num_workers),
+      base_path_(std::move(base_path)),
+      relative_tmp_dir_(std::move(relative_tmp_dir)),
+      use_odirect_(use_odirect),
+      disk_block_size_(0),
+      read_ahead_size_(read_ahead_size) {
+  // Create base directory
+  std::filesystem::create_directories(base_path_);
+
+  // Create tmp directory if configured
+  if (!relative_tmp_dir_.empty()) {
+    auto tmp_path = std::filesystem::path(base_path_) / relative_tmp_dir_;
+    std::filesystem::create_directories(tmp_path);
+  }
+
+  // Query disk block size for O_DIRECT
+  if (use_odirect_) {
+    struct statvfs st;
+    if (statvfs(base_path_.c_str(), &st) == 0) {
+      disk_block_size_ = st.f_bsize;
+    }
+  }
+
+  start_workers();  // IMPORTANT: call at END of constructor
+}
+
+FSConnector::~FSConnector() { close(); }
+
+WorkerFSConn FSConnector::create_connection() {
+  WorkerFSConn conn;
+  conn.base_path = base_path_;
+  if (!relative_tmp_dir_.empty()) {
+    conn.tmp_dir = std::filesystem::path(base_path_) / relative_tmp_dir_;
+  }
+  conn.use_odirect = use_odirect_;
+  conn.disk_block_size = disk_block_size_;
+  conn.read_ahead_size = read_ahead_size_;
+  return conn;
+}
+
+void FSConnector::do_single_get(WorkerFSConn& conn, const std::string& key,
+                                void* buf, size_t len, size_t chunk_size) {
+  std::string filename = key_to_filename(key);
+  auto file_path = conn.base_path / filename;
+
+  int flags = O_RDONLY;
+  bool do_odirect = conn.use_odirect;
+  if (do_odirect) {
+    bool aligned = conn.disk_block_size > 0 && len % conn.disk_block_size == 0;
+    if (aligned) {
+#ifdef O_DIRECT
+      flags |= O_DIRECT;
+#endif
+    } else {
+      do_odirect = false;
+    }
+  }
+
+  int fd = ::open(file_path.c_str(), flags);
+  if (fd < 0) {
+    throw std::runtime_error("open for read failed: " + file_path.string() +
+                             ": " + strerror(errno));
+  }
+
+  try {
+    size_t n;
+    if (conn.read_ahead_size > 0 && len > conn.read_ahead_size) {
+      // Trigger filesystem readahead with a small initial
+      // read, then read the remainder.
+      size_t ra = conn.read_ahead_size;
+      size_t n_head = read_all(fd, buf, ra);
+      if (n_head < ra) {
+        // Short read on the head portion — treat as
+        // incomplete
+        n = n_head;
+      } else {
+        size_t n_tail = read_all(fd, static_cast<char*>(buf) + ra, len - ra);
+        n = n_head + n_tail;
+      }
+    } else {
+      n = read_all(fd, buf, len);
+    }
+    if (n != len) {
+      throw std::runtime_error("incomplete read for " + file_path.string() +
+                               ": expected " + std::to_string(len) + ", got " +
+                               std::to_string(n));
+    }
+  } catch (...) {
+    ::close(fd);
+    throw;
+  }
+  ::close(fd);
+}
+
+void FSConnector::do_single_set(WorkerFSConn& conn, const std::string& key,
+                                const void* buf, size_t len,
+                                size_t chunk_size) {
+  std::string filename = key_to_filename(key);
+  auto file_path = conn.base_path / filename;
+
+  // Skip if already stored on disk
+  if (std::filesystem::exists(file_path)) {
+    return;
+  }
+
+  // Determine temp file path
+  std::filesystem::path tmp_path;
+  if (!conn.tmp_dir.empty()) {
+    tmp_path = conn.tmp_dir / filename;
+  } else {
+    tmp_path = file_path;
+    tmp_path.replace_extension(TMP_EXT);
+  }
+
+  int flags = O_CREAT | O_WRONLY | O_TRUNC;
+  bool do_odirect = conn.use_odirect;
+  if (do_odirect) {
+    bool aligned = conn.disk_block_size > 0 && len % conn.disk_block_size == 0;
+    if (aligned) {
+#ifdef O_DIRECT
+      flags |= O_DIRECT;
+#endif
+    } else {
+      do_odirect = false;
+    }
+  }
+
+  int fd = ::open(tmp_path.c_str(), flags, 0644);
+  if (fd < 0) {
+    throw std::runtime_error("open for write failed: " + tmp_path.string() +
+                             ": " + strerror(errno));
+  }
+
+  try {
+    write_all(fd, buf, len);
+  } catch (...) {
+    ::close(fd);
+    // Clean up temp file on failure
+    std::filesystem::remove(tmp_path);
+    throw;
+  }
+  ::close(fd);
+
+  // Atomic rename: tmp -> final
+  std::error_code ec;
+  std::filesystem::rename(tmp_path, file_path, ec);
+  if (ec) {
+    // Try to clean up, but prioritize reporting the original error.
+    std::error_code remove_ec;
+    std::filesystem::remove(tmp_path, remove_ec);
+    throw std::runtime_error("rename failed: " + tmp_path.string() + " -> " +
+                             file_path.string() + ": " + ec.message());
+  }
+}
+
+bool FSConnector::do_single_exists(WorkerFSConn& conn, const std::string& key) {
+  std::string filename = key_to_filename(key);
+  auto file_path = conn.base_path / filename;
+  return std::filesystem::exists(file_path);
+}
+
+bool FSConnector::do_single_delete(WorkerFSConn& conn, const std::string& key) {
+  std::string filename = key_to_filename(key);
+  auto file_path = conn.base_path / filename;
+  std::error_code ec;
+  return std::filesystem::remove(file_path, ec);
+}
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/fs/connector.h b/csrc/storage_backends/fs/connector.h
new file mode 100644
index 0000000..03b7b9c
--- /dev/null
+++ b/csrc/storage_backends/fs/connector.h
@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "../connector_base.h"
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <sys/statvfs.h>
+#include <unistd.h>
+#include <cstring>
+#include <filesystem>
+#include <string>
+#include <vector>
+
+namespace lmcache {
+namespace connector {
+
+// Key encoding constants — must match fs_l2_adapter.py
+static constexpr char KEY_SEP = '@';
+static constexpr const char* PATH_SLASH_REPLACEMENT = "-SEP-";
+static constexpr const char* FILE_EXT = ".data";
+static constexpr const char* TMP_EXT = ".tmp";
+
+// Per-worker connection state for the FS connector.
+// Each worker maintains its own I/O buffer for O_DIRECT.
+struct WorkerFSConn {
+  std::filesystem::path base_path;
+  std::filesystem::path tmp_dir;  // empty if not configured
+  bool use_odirect = false;
+  size_t disk_block_size = 0;
+  // If > 0, trigger filesystem readahead by issuing a small
+  // initial read of this many bytes before reading the rest.
+  size_t read_ahead_size = 0;
+};
+
+class FSConnector : public ConnectorBase<WorkerFSConn> {
+ public:
+  FSConnector(std::string base_path, int num_workers,
+              std::string relative_tmp_dir = "", bool use_odirect = false,
+              size_t read_ahead_size = 0);
+  ~FSConnector() override;
+
+ protected:
+  WorkerFSConn create_connection() override;
+  void do_single_get(WorkerFSConn& conn, const std::string& key, void* buf,
+                     size_t len, size_t chunk_size) override;
+  void do_single_set(WorkerFSConn& conn, const std::string& key,
+                     const void* buf, size_t len, size_t chunk_size) override;
+  bool do_single_exists(WorkerFSConn& conn, const std::string& key) override;
+  bool do_single_delete(WorkerFSConn& conn, const std::string& key) override;
+
+ private:
+  // Build the filesystem-safe filename from a serialized key string.
+  //
+  // Input key (from NativeConnectorL2Adapter._object_key_to_string):
+  //   Unsalted: "{model}@{kv_rank:08x}@{hash.hex()}"
+  //   Salted  : "{model}@{kv_rank:08x}@{hash.hex()}@{cache_salt}"
+  //
+  // Output filename (matching fs_l2_adapter.py._object_key_to_filename):
+  //   Unsalted: "{safe_model}@{kv_rank:#010x}@{hash.hex()}.data"
+  //   Salted  : "{safe_model}@{kv_rank:#010x}@{hash.hex()}@{cache_salt}.data"
+  //
+  // Differences from the input: '/' in model becomes '-SEP-', kv_rank
+  // gains a '0x' prefix, and '.data' is appended. Both model_name and
+  // cache_salt are forbidden from containing '@' (enforced on the
+  // Python side), so the parse is unambiguous.
+  static std::string key_to_filename(const std::string& key);
+
+  static std::string replace_all(const std::string& str,
+                                 const std::string& from,
+                                 const std::string& to);
+
+  std::string base_path_;
+  std::string relative_tmp_dir_;
+  bool use_odirect_;
+  size_t disk_block_size_;
+  size_t read_ahead_size_;
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/fs/pybind.cpp b/csrc/storage_backends/fs/pybind.cpp
new file mode 100644
index 0000000..5fd53ce
--- /dev/null
+++ b/csrc/storage_backends/fs/pybind.cpp
@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <pybind11/pybind11.h>
+#include "../connector_pybind_utils.h"
+#include "connector.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(lmcache_fs, m) {
+  py::class_<lmcache::connector::FSConnector>(m, "LMCacheFSClient")
+      .def(py::init<std::string, int, std::string, bool, size_t>(),
+           py::arg("base_path"), py::arg("num_workers"),
+           py::arg("relative_tmp_dir") = "", py::arg("use_odirect") = false,
+           py::arg("read_ahead_size") = 0)
+          LMCACHE_BIND_CONNECTOR_METHODS(lmcache::connector::FSConnector);
+}
diff --git a/csrc/storage_backends/mooncake/connector.cpp b/csrc/storage_backends/mooncake/connector.cpp
new file mode 100644
index 0000000..685fa41
--- /dev/null
+++ b/csrc/storage_backends/mooncake/connector.cpp
@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Standard
+#include <algorithm>
+#include <cstdint>
+#include <cstdio>
+#include <stdexcept>
+#include <string>
+#include <utility>
+
+// Third Party
+#include "config.h"
+
+// Local
+#include "connector.h"
+
+namespace lmcache {
+namespace connector {
+
+namespace {
+
+template <typename T>
+void ensure_batch_result_size(const std::vector<T>& results, size_t expected,
+                              const char* op_name) {
+  if (results.size() != expected) {
+    throw std::runtime_error(std::string("Mooncake ") + op_name + " returned " +
+                             std::to_string(results.size()) + " results for " +
+                             std::to_string(expected) + " keys");
+  }
+}
+
+}  // namespace
+
+MooncakeConnector::MooncakeConnector(ConfigDict config, int num_workers,
+                                     L1RegistrationConfig l1_registration,
+                                     WorkerPoolConfig worker_pool_config)
+    : ConnectorBase(num_workers, std::move(worker_pool_config)),
+      config_(std::move(config)),
+      l1_registration_(l1_registration) {
+  // Create a RealClient via the static factory.
+  client_ = mooncake::RealClient::create();
+  if (!client_) {
+    throw std::runtime_error("Failed to create mooncake RealClient");
+  }
+
+  // Forward the config dict to setup_internal().
+  mooncake::ConfigDict mc_config(config_.begin(), config_.end());
+  auto result = client_->setup_internal(mc_config);
+  if (!result.has_value()) {
+    throw std::runtime_error("Mooncake setup_internal failed");
+  }
+
+  if (l1_registration.is_valid()) {
+    preregister_l1_memory(l1_registration.base, l1_registration.size);
+  }
+
+  start_workers();  // IMPORTANT: call at END of ctor
+}
+
+MooncakeConnector::~MooncakeConnector() {
+  close();
+  if (client_) {
+    client_->tearDownAll();
+    client_.reset();
+  }
+}
+
+WorkerMooncakeConn MooncakeConnector::create_connection() {
+  WorkerMooncakeConn conn;
+  conn.client = client_.get();
+  return conn;
+}
+
+void MooncakeConnector::do_single_get(WorkerMooncakeConn& conn,
+                                      const std::string& key, void* buf,
+                                      size_t len, size_t chunk_size) {
+  (void)chunk_size;
+  ensure_registered(buf, len);
+  int64_t bytes_read = conn.client->get_into(key, buf, len);
+  if (bytes_read <= 0) {
+    throw std::runtime_error("Mooncake get_into failed for key: " + key);
+  }
+}
+
+void MooncakeConnector::do_single_set(WorkerMooncakeConn& conn,
+                                      const std::string& key, const void* buf,
+                                      size_t len, size_t chunk_size) {
+  (void)chunk_size;
+  ensure_registered(buf, len);
+  int rc = conn.client->put_from(key, const_cast<void*>(buf), len);
+  if (rc != 0) {
+    throw std::runtime_error("Mooncake put_from failed for key: " + key);
+  }
+}
+
+bool MooncakeConnector::do_single_exists(WorkerMooncakeConn& conn,
+                                         const std::string& key) {
+  // isExist returns: 1=exists, 0=not, -1=error
+  int result = conn.client->isExist(key);
+  if (result < 0) {
+    fprintf(stderr,
+            "[LMCache EXISTS] key %s failed: Mooncake isExist returned %d\n",
+            key.c_str(), result);
+    return false;
+  }
+  return result == 1;
+}
+
+bool MooncakeConnector::do_single_delete(WorkerMooncakeConn& conn,
+                                         const std::string& key) {
+  int rc = conn.client->remove(key, /*force=*/true);
+  if (rc != 0) {
+    fprintf(stderr,
+            "[LMCache DELETE] key %s failed: Mooncake remove returned %d\n",
+            key.c_str(), rc);
+    return false;
+  }
+  return true;
+}
+
+void MooncakeConnector::on_workers_stopped() { unregister_all_buffers(); }
+
+size_t MooncakeConnector::choose_num_tiles(Op op, size_t num_items) const {
+  (void)op;
+  (void)num_items;
+  // Mooncake's batch APIs already parallelize internally. Keep each LMCache
+  // batch as one tile so we do not split a single backend batch across workers.
+  return 1;
+}
+
+void MooncakeConnector::do_batch_get(WorkerMooncakeConn& conn,
+                                     const Request& req) {
+  // Keep GET tolerant at per-key granularity: registration failures should
+  // only zero that key. Keep the no-failure path on Mooncake's batch API, and
+  // fall back to ConnectorBase's singleton-style handling on error.
+  for (size_t i = 0; i < req.buf_ptrs.size(); ++i) {
+    try {
+      ensure_registered(req.buf_ptrs[i], req.buf_lens[i]);
+    } catch (const std::exception& e) {
+      fprintf(stderr,
+              "[LMCache GET] Mooncake buffer registration failed for key %zu, "
+              "falling back to per-key get: %s\n",
+              i, e.what());
+      ConnectorBase<WorkerMooncakeConn>::do_batch_get(conn, req);
+      return;
+    }
+  }
+
+  auto results =
+      conn.client->batch_get_into(req.keys, req.buf_ptrs, req.buf_lens);
+  ensure_batch_result_size(results, req.keys.size(), "batch_get_into");
+
+  for (size_t i = 0; i < results.size(); ++i) {
+    if (results[i] <= 0) {
+      req.batch->per_key_results[req.start_idx + i] = 0;
+      fprintf(stderr,
+              "[LMCache GET] key %s failed: Mooncake batch_get_into "
+              "returned %lld\n",
+              req.keys[i].c_str(), static_cast<long long>(results[i]));
+      continue;
+    }
+    req.batch->per_key_results[req.start_idx + i] = 1;
+  }
+}
+
+void MooncakeConnector::do_batch_set(WorkerMooncakeConn& conn,
+                                     const Request& req) {
+  for (size_t i = 0; i < req.buf_ptrs.size(); ++i) {
+    ensure_registered(req.buf_ptrs[i], req.buf_lens[i]);
+  }
+
+  auto results =
+      conn.client->batch_put_from(req.keys, req.buf_ptrs, req.buf_lens);
+  ensure_batch_result_size(results, req.keys.size(), "batch_put_from");
+
+  for (size_t i = 0; i < results.size(); ++i) {
+    if (results[i] != 0) {
+      throw std::runtime_error("Mooncake batch_put_from failed for key: " +
+                               req.keys[i]);
+    }
+  }
+}
+
+void MooncakeConnector::do_batch_exists(WorkerMooncakeConn& conn,
+                                        const Request& req) {
+  auto results = conn.client->batchIsExist(req.keys);
+  ensure_batch_result_size(results, req.keys.size(), "batchIsExist");
+
+  for (size_t i = 0; i < results.size(); ++i) {
+    if (results[i] < 0) {
+      fprintf(stderr,
+              "[LMCache EXISTS] key %s failed: Mooncake batchIsExist "
+              "returned %d\n",
+              req.keys[i].c_str(), results[i]);
+      req.batch->per_key_results[req.start_idx + i] = 0;
+      continue;
+    }
+    req.batch->per_key_results[req.start_idx + i] = results[i] == 1 ? 1 : 0;
+  }
+}
+
+void MooncakeConnector::do_batch_delete(WorkerMooncakeConn& conn,
+                                        const Request& req) {
+  auto results = conn.client->batchRemove(req.keys, /*force=*/true);
+  ensure_batch_result_size(results, req.keys.size(), "batchRemove");
+
+  for (size_t i = 0; i < results.size(); ++i) {
+    if (results[i] != 0) {
+      fprintf(stderr,
+              "[LMCache DELETE] key %s failed: Mooncake batchRemove "
+              "returned %d\n",
+              req.keys[i].c_str(), results[i]);
+      req.batch->per_key_results[req.start_idx + i] = 0;
+      continue;
+    }
+    req.batch->per_key_results[req.start_idx + i] = 1;
+  }
+}
+
+void MooncakeConnector::ensure_registered(const void* buf, size_t len) {
+  if (!l1_registration_.is_valid()) {
+    return;
+  }
+  if (buf == nullptr) {
+    throw std::runtime_error(
+        "Mooncake buffer registration failed: null buffer");
+  }
+  if (len == 0) {
+    throw std::runtime_error(
+        "Mooncake buffer registration failed: zero length");
+  }
+
+  if (preregistered_block_size_ == 0) {
+    throw std::runtime_error("Mooncake preregistered block size is invalid");
+  }
+
+  const auto registered_begin = l1_registration_.base;
+  const auto registered_end = registered_begin + l1_registration_.size;
+  const auto buf_begin = reinterpret_cast<std::uintptr_t>(buf);
+  const auto buf_end = buf_begin + len;
+
+  if (buf_begin < registered_begin || buf_end > registered_end) {
+    throw std::runtime_error(
+        "Buffer is outside of preregistered L1 region; Mooncake lazy "
+        "registration is disabled");
+  }
+
+  const auto relative_begin = buf_begin - registered_begin;
+  const auto relative_end = (buf_end - 1) - registered_begin;
+  const size_t left_region = relative_begin / preregistered_block_size_;
+  const size_t right_region = relative_end / preregistered_block_size_;
+
+  if (left_region != right_region) {
+    throw std::runtime_error("Buffer crosses preregistered Mooncake regions");
+  }
+}
+
+void MooncakeConnector::preregister_l1_memory(std::uintptr_t base,
+                                              size_t size) {
+  if (base == 0 || size == 0) {
+    return;
+  }
+
+  preregistered_block_size_ = mooncake::globalConfig().max_mr_size == 0
+                                  ? size
+                                  : mooncake::globalConfig().max_mr_size;
+  const size_t max_registration_size = preregistered_block_size_;
+  size_t remaining = size;
+  auto current = base;
+
+  while (remaining > 0) {
+    const size_t segment_size = std::min(remaining, max_registration_size);
+    void* segment_ptr = reinterpret_cast<void*>(current);
+    const int register_rc = client_->register_buffer(segment_ptr, segment_size);
+    if (register_rc != 0) {
+      auto rollback_remaining = current - base;
+      while (rollback_remaining > 0) {
+        const auto rollback_size =
+            std::min(rollback_remaining, max_registration_size);
+        rollback_remaining -= rollback_size;
+        void* rollback_ptr = reinterpret_cast<void*>(base + rollback_remaining);
+        try {
+          client_->unregister_buffer(rollback_ptr);
+        } catch (...) {
+          // Keep rolling back the remaining segments so a cleanup failure does
+          // not mask the original registration error or strand later regions.
+        }
+      }
+      preregistered_block_size_ = 0;
+      throw std::runtime_error("Mooncake preregister_l1_memory failed");
+    }
+
+    current += segment_size;
+    remaining -= segment_size;
+  }
+}
+
+void MooncakeConnector::unregister_all_buffers() noexcept {
+  if (client_ == nullptr || !l1_registration_.is_valid() ||
+      preregistered_block_size_ == 0) {
+    return;
+  }
+
+  auto current = l1_registration_.base;
+  size_t remaining = l1_registration_.size;
+  while (remaining > 0) {
+    const auto segment_size = std::min(remaining, preregistered_block_size_);
+    void* segment_ptr = reinterpret_cast<void*>(current);
+    try {
+      client_->unregister_buffer(segment_ptr);
+    } catch (...) {
+      // Preserve noexcept during teardown and keep attempting the remaining
+      // segments so earlier failures do not strand later registrations.
+    }
+    current += segment_size;
+    remaining -= segment_size;
+  }
+
+  preregistered_block_size_ = 0;
+}
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/mooncake/connector.h b/csrc/storage_backends/mooncake/connector.h
new file mode 100644
index 0000000..7626883
--- /dev/null
+++ b/csrc/storage_backends/mooncake/connector.h
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+// Standard
+#include <condition_variable>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+// Third Party
+#include "real_client.h"
+
+// First Party
+#include "../connector_base.h"
+
+namespace lmcache {
+namespace connector {
+
+// ConfigDict mirrors mooncake::ConfigDict
+// (std::unordered_map<std::string, std::string>).
+using ConfigDict = std::unordered_map<std::string, std::string>;
+
+// Per-worker connection state for the Mooncake connector.
+// Each worker holds a raw pointer to the shared
+// RealClient (owned by MooncakeConnector).
+struct WorkerMooncakeConn {
+  mooncake::RealClient* client{nullptr};
+};
+
+struct L1RegistrationConfig {
+  bool enabled{false};
+  std::uintptr_t base{0};
+  size_t size{0};
+
+  bool is_valid() const { return enabled && base != 0 && size != 0; }
+};
+
+class MooncakeConnector : public ConnectorBase<WorkerMooncakeConn> {
+ public:
+  MooncakeConnector(ConfigDict config, int num_workers,
+                    L1RegistrationConfig l1_registration = {},
+                    WorkerPoolConfig worker_pool_config = {});
+  ~MooncakeConnector() override;
+
+ protected:
+  WorkerMooncakeConn create_connection() override;
+
+  void do_single_get(WorkerMooncakeConn& conn, const std::string& key,
+                     void* buf, size_t len, size_t chunk_size) override;
+
+  void do_single_set(WorkerMooncakeConn& conn, const std::string& key,
+                     const void* buf, size_t len, size_t chunk_size) override;
+
+  bool do_single_exists(WorkerMooncakeConn& conn,
+                        const std::string& key) override;
+
+  bool do_single_delete(WorkerMooncakeConn& conn,
+                        const std::string& key) override;
+
+  void on_workers_stopped() override;
+
+  size_t choose_num_tiles(Op op, size_t num_items) const override;
+
+  void do_batch_get(WorkerMooncakeConn& conn, const Request& req) override;
+
+  void do_batch_set(WorkerMooncakeConn& conn, const Request& req) override;
+
+  void do_batch_exists(WorkerMooncakeConn& conn, const Request& req) override;
+
+  void do_batch_delete(WorkerMooncakeConn& conn, const Request& req) override;
+
+ private:
+  void ensure_registered(const void* buf, size_t len);
+  void preregister_l1_memory(std::uintptr_t base, size_t size);
+  void unregister_all_buffers() noexcept;
+
+  // Shared Mooncake RealClient instance.
+  std::shared_ptr<mooncake::RealClient> client_;
+
+  // The original config dict (kept for diagnostics).
+  ConfigDict config_;
+  L1RegistrationConfig l1_registration_;
+  size_t preregistered_block_size_{0};
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/mooncake/pybind.cpp b/csrc/storage_backends/mooncake/pybind.cpp
new file mode 100644
index 0000000..6472916
--- /dev/null
+++ b/csrc/storage_backends/mooncake/pybind.cpp
@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <stdexcept>
+#include <string>
+#include <utility>
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include "../connector_pybind_utils.h"
+#include "connector.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(lmcache_mooncake, m) {
+  py::class_<lmcache::connector::L1RegistrationConfig>(m,
+                                                       "L1RegistrationConfig")
+      .def(py::init<>())
+      .def_readwrite("enabled",
+                     &lmcache::connector::L1RegistrationConfig::enabled)
+      .def_readwrite("base", &lmcache::connector::L1RegistrationConfig::base)
+      .def_readwrite("size", &lmcache::connector::L1RegistrationConfig::size);
+
+  py::class_<lmcache::connector::MooncakeConnector>(m, "LMCacheMooncakeClient")
+      .def(py::init([](lmcache::connector::ConfigDict config, int num_workers,
+                       lmcache::connector::L1RegistrationConfig l1_registration,
+                       py::object per_op_workers) {
+             return new lmcache::connector::MooncakeConnector(
+                 std::move(config), num_workers, l1_registration,
+                 lmcache::connector::pybind_utils::parse_per_op_workers(
+                     per_op_workers));
+           }),
+           py::arg("config"), py::arg("num_workers"),
+           py::arg("l1_registration") =
+               lmcache::connector::L1RegistrationConfig{},
+           py::arg("per_op_workers") = py::none())
+          LMCACHE_BIND_CONNECTOR_METHODS(lmcache::connector::MooncakeConnector);
+}
diff --git a/csrc/storage_backends/redis/connector.cpp b/csrc/storage_backends/redis/connector.cpp
new file mode 100644
index 0000000..320536c
--- /dev/null
+++ b/csrc/storage_backends/redis/connector.cpp
@@ -0,0 +1,377 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "connector.h"
+#include <cerrno>
+#include <stdexcept>
+#include <string_view>
+
+namespace lmcache {
+namespace connector {
+
+void WorkerConn::connect(const std::string& h, int p) {
+  host = h;
+  port = p;
+
+  // 1. create socket
+  fd = socket(AF_INET, SOCK_STREAM, 0);
+  if (fd < 0) {
+    throw std::runtime_error("failed to create socket");
+  }
+
+  // 2. resolve host
+  struct addrinfo hints = {}, *result = nullptr;
+  hints.ai_family = AF_INET;
+  hints.ai_socktype = SOCK_STREAM;
+
+  std::string port_str = std::to_string(p);
+  int err = getaddrinfo(h.c_str(), port_str.c_str(), &hints, &result);
+
+  if (err != 0) {
+    ::close(fd);
+    throw std::runtime_error(std::string("getaddrinfo failed: ") +
+                             gai_strerror(err));
+  }
+
+  // 3. connect to host
+  if (::connect(fd, result->ai_addr, result->ai_addrlen) < 0) {
+    freeaddrinfo(result);
+    ::close(fd);
+    throw std::runtime_error("connection failed");
+  }
+
+  freeaddrinfo(result);
+}
+
+// call send multiple times until all the data is sent
+void WorkerConn::send_all(const void* data, size_t len) {
+  size_t sent_so_far = 0;
+  const char* ptr = static_cast<const char*>(data);
+  while (sent_so_far < len) {
+    ssize_t n = ::send(fd, ptr + sent_so_far, len - sent_so_far, 0);
+    if (n < 0) {
+      if (errno == EINTR) {
+        continue;  // retry on EINTR
+      }
+      throw std::runtime_error("socket send failed");
+    }
+    if (n == 0) {
+      throw std::runtime_error("socket send failed: connection closed");
+    }
+    sent_so_far += n;
+  }
+}
+
+// scatter gather send
+void WorkerConn::send_multipart(
+    const std::vector<std::pair<const void*, size_t>>& parts) {
+  if (parts.empty()) return;
+
+  std::vector<struct iovec> iov;
+  iov.reserve(parts.size());
+  for (const auto& part : parts) {
+    iov.push_back({const_cast<void*>(part.first), part.second});
+  }
+
+  size_t total_to_send = 0;
+  for (const auto& part : parts) {
+    total_to_send += part.second;
+  }
+
+  size_t sent_so_far = 0;
+  size_t iov_idx = 0;
+
+  while (sent_so_far < total_to_send) {
+    ssize_t n = ::writev(fd, &iov[iov_idx], iov.size() - iov_idx);
+    if (n < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      throw std::runtime_error("socket writev failed");
+    }
+    if (n == 0) {
+      throw std::runtime_error("socket writev failed: connection closed");
+    }
+
+    sent_so_far += n;
+
+    // adjust iovec for partial writes
+    size_t remaining = n;
+    while (remaining > 0 && iov_idx < iov.size()) {
+      if (remaining >= iov[iov_idx].iov_len) {
+        remaining -= iov[iov_idx].iov_len;
+        iov_idx++;
+      } else {
+        iov[iov_idx].iov_base =
+            static_cast<char*>(iov[iov_idx].iov_base) + remaining;
+        iov[iov_idx].iov_len -= remaining;
+        remaining = 0;
+      }
+    }
+  }
+}
+
+void WorkerConn::recv_exactly(void* buf, size_t len) {
+  size_t recv_so_far = 0;
+  char* ptr = static_cast<char*>(buf);
+  while (recv_so_far < len) {
+    ssize_t n = ::recv(fd, ptr + recv_so_far, len - recv_so_far, 0);
+    if (n < 0) {
+      if (errno == EINTR) {
+        continue;
+      }
+      throw std::runtime_error("socket recv failed");
+    }
+    if (n == 0) {
+      throw std::runtime_error("socket recv failed: connection closed");
+    }
+    recv_so_far += n;
+  }
+}
+
+std::string WorkerConn::recv_line() {
+  std::string line;
+  line.reserve(128);
+  for (;;) {
+    char c;
+    recv_exactly(&c, 1);
+    line.push_back(c);
+    size_t n = line.size();
+    if (n >= 2 && line[n - 2] == '\r' && line[n - 1] == '\n') {
+      return line;
+    }
+  }
+}
+
+void WorkerConn::authenticate_if_needed() {
+  if (authed) return;
+  if (password.empty()) return;
+
+  if (!username.empty()) {
+    // auth username password
+    std::string u =
+        "$" + std::to_string(username.size()) + "\r\n" + username + "\r\n";
+    std::string p =
+        "$" + std::to_string(password.size()) + "\r\n" + password + "\r\n";
+    static constexpr std::string_view auth_prefix = "*3\r\n$4\r\nAUTH\r\n";
+
+    send_multipart({
+        {auth_prefix.data(), auth_prefix.size()},
+        {u.data(), u.size()},
+        {p.data(), p.size()},
+    });
+  } else {
+    // auth password
+    std::string p =
+        "$" + std::to_string(password.size()) + "\r\n" + password + "\r\n";
+    static constexpr std::string_view auth_prefix = "*2\r\n$4\r\nAUTH\r\n";
+
+    send_multipart({
+        {auth_prefix.data(), auth_prefix.size()},
+        {p.data(), p.size()},
+    });
+  }
+
+  std::string line = recv_line();
+  if (line.rfind("+OK\r\n", 0) == 0) {
+    authed = true;
+    return;
+  }
+  if (!line.empty() && line[0] == '-') {
+    throw std::runtime_error("AUTH failed: " + line);
+  }
+  throw std::runtime_error("AUTH failed: unexpected reply: " + line);
+}
+
+const std::string& WorkerConn::make_key_header(const std::string& key) {
+  key_header_buf.clear();
+
+  const size_t needed = key.size() + 16;
+  if (needed > key_header_buf.capacity()) {
+    key_header_buf.reserve(needed);
+  }
+
+  key_header_buf += '$';
+  key_header_buf += std::to_string(key.size());
+  key_header_buf += crlf;
+  key_header_buf += key;
+  key_header_buf += crlf;
+
+  return key_header_buf;
+}
+
+const std::string& WorkerConn::make_size_header(size_t batch_chunk_num_bytes) {
+  size_header_buf.clear();
+
+  size_header_buf += '$';
+  size_header_buf += std::to_string(batch_chunk_num_bytes);
+  size_header_buf += crlf;
+
+  return size_header_buf;
+}
+
+/*
+RESP set, get, exists are very fragile here since we make hard assumptions about
+the RESP responses. a single error could break our assumptions. we can mitigate
+this by actually parsing the headers and trailers.
+*/
+
+RedisConnector::RedisConnector(std::string host, int port, int num_workers,
+                               std::string username, std::string password)
+    : ConnectorBase(num_workers),
+      host_(std::move(host)),
+      port_(port),
+      username_(std::move(username)),
+      password_(std::move(password)) {
+  worker_fds_.reserve(num_workers);
+  start_workers();  // start after derived class is fully constructed
+}
+
+RedisConnector::~RedisConnector() { close(); }
+
+WorkerConn RedisConnector::create_connection() {
+  WorkerConn conn;
+  conn.connect(host_, port_);
+
+  conn.username = username_;
+  conn.password = password_;
+  conn.authenticate_if_needed();
+
+  // track socket fd for shutdown
+  {
+    std::lock_guard<std::mutex> lk(worker_fds_mu_);
+    worker_fds_.push_back(conn.fd);
+  }
+
+  return conn;
+}
+
+void RedisConnector::do_single_get(WorkerConn& conn, const std::string& key,
+                                   void* buf, size_t len, size_t chunk_size) {
+  if (len != chunk_size) {
+    throw std::runtime_error("buffer size mismatch");
+  }
+
+  const std::string& size_header = conn.make_size_header(chunk_size);
+  const std::string& key_header = conn.make_key_header(key);
+
+  conn.send_multipart({{conn.get_prefix.data(), conn.get_prefix.size()},
+                       {key_header.data(), key_header.size()}});
+
+  // parse response in 3 steps
+
+  // 1. recv size header
+  std::vector<char> recv_size_header_buf(size_header.size());
+  conn.recv_exactly(recv_size_header_buf.data(), size_header.size());
+  if (std::memcmp(recv_size_header_buf.data(), size_header.data(),
+                  size_header.size()) != 0) {
+    throw std::runtime_error("GET: size header mismatch");
+  }
+
+  // 2. recv KV Cache (payload) without parsing
+  conn.recv_exactly(buf, len);
+
+  // 3. recv trailer
+  char trailer[WorkerConn::crlf_len];
+  conn.recv_exactly(trailer, WorkerConn::crlf_len);
+  if (std::memcmp(trailer, WorkerConn::crlf.data(), WorkerConn::crlf_len) !=
+      0) {
+    throw std::runtime_error("GET: trailer mismatch");
+  }
+}
+
+// RESP SET
+void RedisConnector::do_single_set(WorkerConn& conn, const std::string& key,
+                                   const void* buf, size_t len,
+                                   size_t chunk_size) {
+  // we only write exactly batch_chunk_num_bytes bytes (save_unfull_chunk must
+  // be off)
+  if (len != chunk_size) {
+    throw std::runtime_error("buffer size mismatch");
+  }
+
+  // build headers using reusable buffers
+  const std::string& size_header = conn.make_size_header(chunk_size);
+  const std::string& key_header = conn.make_key_header(key);
+
+  // send SET cmd
+  // iovec let's us combine pre-built parts and dynamic strings
+  conn.send_multipart({{conn.set_prefix.data(), conn.set_prefix.size()},
+                       {key_header.data(), key_header.size()},
+                       {size_header.data(), size_header.size()},
+                       {buf, len},
+                       {WorkerConn::crlf.data(), WorkerConn::crlf_len}});
+
+  // parse response which should be exactly +OK\r\n
+  char response[WorkerConn::ok_response_len];
+  conn.recv_exactly(response, WorkerConn::ok_response_len);
+
+  if (std::memcmp(response, WorkerConn::ok_response.data(),
+                  WorkerConn::ok_response_len) != 0) {
+    throw std::runtime_error("SET: response was not OK");
+  }
+}
+
+// RESP EXISTS
+bool RedisConnector::do_single_exists(WorkerConn& conn,
+                                      const std::string& key) {
+  // build key header using reusable buffer
+  const std::string& key_header = conn.make_key_header(key);
+
+  // send EXISTS cmd
+  // iovec let's us combine pre-built parts and dynamic strings
+  conn.send_multipart({{conn.exists_prefix.data(), conn.exists_prefix.size()},
+                       {key_header.data(), key_header.size()}});
+
+  // parse response (either :0\r\n or :1\r\n)
+  char response[WorkerConn::exists_response_len];
+  conn.recv_exactly(response, WorkerConn::exists_response_len);
+
+  if (std::memcmp(response, WorkerConn::exists_one.data(),
+                  WorkerConn::exists_response_len) == 0) {
+    return true;
+  } else if (std::memcmp(response, WorkerConn::exists_zero.data(),
+                         WorkerConn::exists_response_len) == 0) {
+    return false;
+  } else {
+    throw std::runtime_error(
+        "EXISTS returned invalid response that wasn't :0\r\n or :1\r\n");
+  }
+}
+
+// RESP DEL
+bool RedisConnector::do_single_delete(WorkerConn& conn,
+                                      const std::string& key) {
+  // build key header using reusable buffer
+  const std::string& key_header = conn.make_key_header(key);
+
+  // send DEL cmd
+  conn.send_multipart({{conn.del_prefix.data(), conn.del_prefix.size()},
+                       {key_header.data(), key_header.size()}});
+
+  // parse response (either :0\r\n or :1\r\n, same format as EXISTS)
+  char response[WorkerConn::exists_response_len];
+  conn.recv_exactly(response, WorkerConn::exists_response_len);
+
+  if (std::memcmp(response, WorkerConn::exists_one.data(),
+                  WorkerConn::exists_response_len) == 0) {
+    return true;  // key was deleted
+  } else if (std::memcmp(response, WorkerConn::exists_zero.data(),
+                         WorkerConn::exists_response_len) == 0) {
+    return false;  // key did not exist
+  } else {
+    throw std::runtime_error(
+        "DEL returned invalid response that wasn't :0\r\n or :1\r\n");
+  }
+}
+
+void RedisConnector::shutdown_connections() {
+  std::lock_guard<std::mutex> lk(worker_fds_mu_);
+  for (int fd : worker_fds_) {
+    if (fd >= 0) {
+      ::shutdown(fd, SHUT_RDWR);
+    }
+  }
+}
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/redis/connector.h b/csrc/storage_backends/redis/connector.h
new file mode 100644
index 0000000..778c7e8
--- /dev/null
+++ b/csrc/storage_backends/redis/connector.h
@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "../connector_base.h"
+#include <sys/socket.h>
+#include <sys/uio.h>
+#include <netinet/in.h>
+#include <netdb.h>
+#include <unistd.h>
+#include <cstring>
+#include <vector>
+
+namespace lmcache {
+namespace connector {
+
+// a TCP session (one per thread) implementing RESP2
+/*
+key optimizations include:
+1. preset batch_chunk_num_bytes (allows not parsing for \r\n byte-by-byte)
+2. scatter/gather sending of data (with pre-allocated buffers)
+3. zero copy (no bounce buffers)
+*/
+struct WorkerConn {
+  int fd = -1;
+  std::string host;
+  int port;
+
+  // authentication
+  std::string username;  // optional; empty => auth password
+  std::string password;  // required for auth
+  bool authed = false;
+
+  // pre-computed headers
+  std::string get_prefix;
+  std::string set_prefix;
+  std::string exists_prefix;
+  std::string del_prefix;
+
+  // reusable buffers for building headers (avoids repeated dynamic allocations)
+  std::string key_header_buf;
+  std::string size_header_buf;
+
+  // pre-computed constants (for comparisons)
+  static constexpr std::string_view crlf = "\r\n";
+  static constexpr size_t crlf_len = crlf.size();
+
+  static constexpr std::string_view ok_response = "+OK\r\n";
+  static constexpr size_t ok_response_len = ok_response.size();
+
+  static constexpr std::string_view exists_one = ":1\r\n";
+  static constexpr std::string_view exists_zero = ":0\r\n";
+  static constexpr size_t exists_response_len = exists_one.size();
+
+  WorkerConn()
+      : get_prefix("*2\r\n$3\r\nGET\r\n"),
+        set_prefix("*3\r\n$3\r\nSET\r\n"),
+        exists_prefix("*2\r\n$6\r\nEXISTS\r\n"),
+        del_prefix("*2\r\n$3\r\nDEL\r\n") {
+    // pre-allocate key_header_buf to handle typical keys without reallocation
+    // typical key format: model_name@world_size@worker_id@chunk_hash_hex@dtype
+    // - model_name: 25-50 chars (e.g., "meta-llama/Llama-3-70b-instruct")
+    // - world_size: 1-2 chars
+    // - worker_id: 1-2 chars
+    // - chunk_hash (SHA256): 64 chars hex
+    // - dtype: 7-8 chars (e.g., "bfloat16")
+    // - separators: 4 chars
+    // total typical key: ~100-140 chars
+    // resp header overhead: $<len>\r\n<key>\r\n = ~8 bytes
+    // reserve 512 bytes to handle typical keys plus margin
+    key_header_buf.reserve(512);
+
+    // pre-allocate size_header_buf for chunk size headers
+    // typical format: $<batch_chunk_num_bytes>\r\n
+    // typical batch_chunk_num_bytes: 1MB-4MB = 7-8 digit number
+    // reserve 32 bytes to handle up to 20+ digit numbers with margin
+    size_header_buf.reserve(32);
+  }
+
+  ~WorkerConn() {
+    if (fd >= 0) ::close(fd);
+  }
+
+  void connect(const std::string& host, int port);
+  void authenticate_if_needed();
+  void send_all(const void* data, size_t len);
+  void send_multipart(const std::vector<std::pair<const void*, size_t>>& parts);
+  void recv_exactly(void* buf, size_t len);
+  std::string recv_line();
+  const std::string& make_key_header(const std::string& key);
+  const std::string& make_size_header(size_t batch_chunk_num_bytes);
+};
+
+class RedisConnector : public ConnectorBase<WorkerConn> {
+ public:
+  RedisConnector(std::string host, int port, int num_workers,
+                 std::string username = "", std::string password = "");
+  ~RedisConnector() override;
+
+ protected:
+  WorkerConn create_connection() override;
+  void do_single_get(WorkerConn& conn, const std::string& key, void* buf,
+                     size_t len, size_t chunk_size) override;
+  void do_single_set(WorkerConn& conn, const std::string& key, const void* buf,
+                     size_t len, size_t chunk_size) override;
+  bool do_single_exists(WorkerConn& conn, const std::string& key) override;
+  bool do_single_delete(WorkerConn& conn, const std::string& key) override;
+  void shutdown_connections() override;
+
+ private:
+  std::string host_;
+  int port_;
+  std::string username_;
+  std::string password_;
+  std::mutex worker_fds_mu_;
+  std::vector<int> worker_fds_;
+};
+
+}  // namespace connector
+}  // namespace lmcache
diff --git a/csrc/storage_backends/redis/pybind.cpp b/csrc/storage_backends/redis/pybind.cpp
new file mode 100644
index 0000000..be977de
--- /dev/null
+++ b/csrc/storage_backends/redis/pybind.cpp
@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <pybind11/pybind11.h>
+#include "../connector_pybind_utils.h"
+#include "connector.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(lmcache_redis, m) {
+  py::class_<lmcache::connector::RedisConnector>(m, "LMCacheRedisClient")
+      .def(py::init<std::string, int, int, std::string, std::string>(),
+           py::arg("host"), py::arg("port"), py::arg("num_workers"),
+           py::arg("username") = "", py::arg("password") = "")
+          LMCACHE_BIND_CONNECTOR_METHODS(lmcache::connector::RedisConnector);
+}
diff --git a/csrc/storage_manager/bitmap.cpp b/csrc/storage_manager/bitmap.cpp
new file mode 100644
index 0000000..86a6b49
--- /dev/null
+++ b/csrc/storage_manager/bitmap.cpp
@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "bitmap.h"
+
+#include <algorithm>
+
+namespace lmcache {
+namespace storage_manager {
+
+namespace {
+
+constexpr unsigned kBitsPerByte = 8;
+
+inline size_t byte_index(size_t bit_index) { return bit_index / kBitsPerByte; }
+inline unsigned bit_offset(size_t bit_index) {
+  return static_cast<unsigned>(bit_index % kBitsPerByte);
+}
+
+}  // namespace
+
+Bitmap::Bitmap(size_t size)
+    : size_(size), data_(size == 0 ? 0 : (size - 1) / kBitsPerByte + 1, 0) {}
+
+Bitmap::Bitmap(size_t size, size_t prefix_bits) : Bitmap(size) {
+  if (prefix_bits == 0 || size == 0) return;
+  if (prefix_bits > size) prefix_bits = size;
+
+  // Set full bytes to 0xFF
+  const size_t full_bytes = prefix_bits / kBitsPerByte;
+  for (size_t i = 0; i < full_bytes; ++i) {
+    data_[i] = 0xFF;
+  }
+
+  // Set remaining bits in the partial byte
+  const unsigned remaining = prefix_bits % kBitsPerByte;
+  if (remaining > 0) {
+    data_[full_bytes] = static_cast<uint8_t>((1u << remaining) - 1);
+  }
+}
+
+void Bitmap::set(size_t index) {
+  if (index >= size_) return;
+  data_[byte_index(index)] |= static_cast<uint8_t>(1u << bit_offset(index));
+}
+
+void Bitmap::batched_set(const std::vector<size_t>& indices) {
+  for (size_t idx : indices) set(idx);
+}
+
+void Bitmap::set_range(size_t start, size_t end) {
+  if (end > size_) end = size_;
+  if (start >= end) return;
+
+  const size_t first_byte = start / kBitsPerByte;
+  const size_t last_byte = (end - 1) / kBitsPerByte;  // inclusive
+  const unsigned head_low = bit_offset(start);
+
+  if (first_byte == last_byte) {
+    // Whole range lives in one byte: set bits [head_low, head_low + width).
+    const unsigned width = static_cast<unsigned>(end - start);  // 1..8
+    const uint8_t mask = static_cast<uint8_t>(((1u << width) - 1u) << head_low);
+    data_[first_byte] |= mask;
+    return;
+  }
+
+  // Head partial byte: bits [head_low, 8).
+  data_[first_byte] |= static_cast<uint8_t>(0xFFu << head_low);
+  // Middle full bytes.
+  std::fill(data_.begin() + static_cast<std::ptrdiff_t>(first_byte + 1),
+            data_.begin() + static_cast<std::ptrdiff_t>(last_byte),
+            static_cast<uint8_t>(0xFF));
+  // Tail partial byte: bits [0, tail_width).
+  const unsigned tail_width =
+      static_cast<unsigned>(end - last_byte * kBitsPerByte);  // 1..8
+  data_[last_byte] |= static_cast<uint8_t>((1u << tail_width) - 1u);
+}
+
+void Bitmap::clear(size_t index) {
+  if (index >= size_) return;
+  data_[byte_index(index)] &= static_cast<uint8_t>(~(1u << bit_offset(index)));
+}
+
+bool Bitmap::test(size_t index) const {
+  if (index >= size_) return false;
+  return (data_[byte_index(index)] >> bit_offset(index)) & 1u;
+}
+
+size_t Bitmap::popcount() const {
+  if (data_.empty()) return 0;
+
+  // process full bytes
+  size_t count = 0;
+  const size_t num_full_bytes = size_ / kBitsPerByte;
+  for (size_t i = 0; i < num_full_bytes; ++i) {
+    count += static_cast<size_t>(
+        __builtin_popcount(static_cast<unsigned>(data_[i])));
+  }
+
+  // process remaining bits in the last byte
+  const unsigned remaining_bits = size_ % kBitsPerByte;
+  if (remaining_bits > 0) {
+    uint8_t last_byte = data_.back();
+    uint8_t mask = static_cast<uint8_t>((1u << remaining_bits) - 1);
+    last_byte &= mask;
+    count += static_cast<size_t>(
+        __builtin_popcount(static_cast<unsigned>(last_byte)));
+  }
+  return count;
+}
+
+size_t Bitmap::clz() const {
+  if (size_ == 0) return 0;
+
+  const size_t num_full_bytes = size_ / kBitsPerByte;
+  size_t count = 0;
+
+  for (size_t i = 0; i < num_full_bytes; ++i) {
+    uint8_t b = data_[i];
+    if (b == 0) {
+      count += kBitsPerByte;
+    } else {
+      count += static_cast<size_t>(__builtin_ctz(static_cast<unsigned>(b)));
+      return count;
+    }
+  }
+
+  const unsigned remaining_bits = size_ % kBitsPerByte;
+  if (remaining_bits > 0) {
+    uint8_t last_byte = data_.back();
+    uint8_t mask = static_cast<uint8_t>((1u << remaining_bits) - 1);
+    last_byte &= mask;
+    if (last_byte == 0) {
+      count += remaining_bits;
+    } else {
+      count +=
+          static_cast<size_t>(__builtin_ctz(static_cast<unsigned>(last_byte)));
+    }
+  }
+
+  return count;
+}
+
+size_t Bitmap::clo() const {
+  const Bitmap inverted{~(*this)};
+  return inverted.clz();
+}
+
+int64_t Bitmap::highest_set_bit() const {
+  // Scan bytes from the most significant down; the first non-zero byte holds
+  // the highest set bit. Bits beyond size_ are never set, so the result is
+  // always < size_.
+  for (size_t byte = data_.size(); byte-- > 0;) {
+    const uint8_t value = data_[byte];
+    if (value != 0) {
+      const unsigned highest =
+          31u -
+          static_cast<unsigned>(__builtin_clz(static_cast<unsigned>(value)));
+      return static_cast<int64_t>(byte * kBitsPerByte + highest);
+    }
+  }
+  return -1;
+}
+
+Bitmap Bitmap::operator&(const Bitmap& other) const {
+  const size_t result_size = (size_ <= other.size_) ? size_ : other.size_;
+  Bitmap result(result_size);
+  for (size_t i = 0; i < result.data_.size(); ++i) {
+    result.data_[i] = data_[i] & other.data_[i];
+  }
+  return result;
+}
+
+Bitmap Bitmap::operator|(const Bitmap& other) const {
+  const size_t result_size = (size_ <= other.size_) ? size_ : other.size_;
+  Bitmap result(result_size);
+  for (size_t i = 0; i < result.data_.size(); ++i) {
+    result.data_[i] = data_[i] | other.data_[i];
+  }
+  return result;
+}
+
+std::vector<size_t> Bitmap::get_indices() const {
+  std::vector<size_t> indices;
+  indices.reserve(popcount());
+  for (size_t i = 0; i < data_.size(); ++i) {
+    uint8_t byte = data_[i];
+    while (byte != 0) {
+      unsigned bit =
+          static_cast<unsigned>(__builtin_ctz(static_cast<unsigned>(byte)));
+      size_t idx = i * kBitsPerByte + bit;
+      if (idx < size_) {
+        indices.push_back(idx);
+      }
+      byte &= static_cast<uint8_t>(byte - 1);  // clear lowest set bit
+    }
+  }
+  return indices;
+}
+
+std::unordered_set<size_t> Bitmap::get_indices_set() const {
+  auto vec = get_indices();
+  return std::unordered_set<size_t>(vec.begin(), vec.end());
+}
+
+std::string Bitmap::to_string() const {
+  if (size_ == 0) return "";
+
+  std::string result(size_, '0');
+  for (size_t i = 0; i < data_.size(); ++i) {
+    uint8_t byte = data_[i];
+    for (unsigned j = 0; j < kBitsPerByte; ++j) {
+      size_t bit_index = i * kBitsPerByte + j;
+      if (bit_index >= size_) {
+        break;
+      }
+      if ((byte >> j) & 1u) {
+        result[bit_index] = '1';
+      }
+    }
+  }
+
+  return result;
+}
+
+Bitmap Bitmap::operator~() const {
+  Bitmap result(size_);
+  for (size_t i = 0; i < data_.size(); ++i) {
+    result.data_[i] = ~data_[i];
+  }
+
+  // Clear bits that are out of range in the last byte
+  const unsigned remaining_bits = size_ % kBitsPerByte;
+  if (remaining_bits > 0) {
+    uint8_t mask = static_cast<uint8_t>((1u << remaining_bits) - 1);
+    result.data_.back() &= mask;
+  }
+  return result;
+}
+
+Bitmap::~Bitmap() = default;
+
+}  // namespace storage_manager
+}  // namespace lmcache
diff --git a/csrc/storage_manager/bitmap.h b/csrc/storage_manager/bitmap.h
new file mode 100644
index 0000000..4aa4ae8
--- /dev/null
+++ b/csrc/storage_manager/bitmap.h
@@ -0,0 +1,166 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+#include <unordered_set>
+#include <string>
+
+namespace lmcache {
+
+namespace storage_manager {
+
+/**
+ * @brief A simple bitmap implementation for tracking the state of the L2
+ * storage operation results.
+ *
+ * This bitmap is used to track the state of the L2 storage operation results.
+ * Each bit in the bitmap represents the success or failure of a key.
+ */
+class Bitmap {
+ public:
+  /**
+   * @brief Construct a new Bitmap with the specified size.
+   *
+   * @param size The number of bits in the bitmap.
+   */
+  explicit Bitmap(size_t size);
+
+  /**
+   * @brief Construct a new Bitmap with the specified size and
+   * first N prefix bits set to 1.
+   *
+   * @param size The number of bits in the bitmap.
+   * @param prefix_bits The number of leading bits to set to 1.
+   */
+  explicit Bitmap(size_t size, size_t prefix_bits);
+
+  /**
+   * @brief set the bit at the specified index to 1.
+   */
+  void set(size_t index);
+
+  /**
+   * @brief set every bit in ``indices`` to 1 (positions >= size ignored).
+   *
+   * @param indices Bit positions to set.
+   */
+  void batched_set(const std::vector<size_t>& indices);
+
+  /**
+   * @brief set every bit in the half-open range ``[start, end)`` to 1.
+   *
+   * Fills whole bytes at once, so setting a contiguous span is far cheaper than
+   * the equivalent per-bit ``set`` calls. ``end`` is clamped to the bitmap
+   * size; an empty or out-of-range range is a no-op.
+   *
+   * @param start First bit position to set (inclusive).
+   * @param end One past the last bit position to set (exclusive).
+   */
+  void set_range(size_t start, size_t end);
+
+  /**
+   * @brief clear the bit at the specified index to 0.
+   */
+  void clear(size_t index);
+
+  /**
+   * @brief test the bit at the specified index.
+   *
+   * @return true if the bit is set to 1, false otherwise.
+   */
+  bool test(size_t index) const;
+
+  /**
+   * @brief count the number of bits set to 1 in the bitmap.
+   *
+   * @return the number of bits set to 1.
+   */
+  size_t popcount() const;
+
+  /**
+   * @brief count the number of leading zeros in the bitmap.
+   *
+   * @return the number of leading zeros.
+   */
+  size_t clz() const;
+
+  /**
+   * @brief count the number of leading ones in the bitmap.
+   *
+   * @return the number of leading ones.
+   */
+  size_t clo() const;
+
+  /**
+   * @brief index of the highest set bit.
+   *
+   * The return type is signed (``int64_t``) so the empty bitmap can be reported
+   * as ``-1`` (an unsigned index has no spare value for "no bit set").
+   *
+   * @return the largest index whose bit is set, or ``-1`` if no bit is set.
+   */
+  int64_t highest_set_bit() const;
+
+  /**
+   * @brief bitwise AND operation between two bitmaps.
+   *
+   * @return a new Bitmap that is the result of the bitwise AND operation.
+   *
+   * @note If this and other have different sizes, the result will be truncated
+   * to the smaller size.
+   */
+  Bitmap operator&(const Bitmap& other) const;
+
+  /**
+   * @brief bitwise OR operation between two bitmaps.
+   *
+   * @return a new Bitmap that is the result of the bitwise OR operation.
+   *
+   * @note If this and other have different sizes, the result will be truncated
+   * to the smaller size.
+   */
+  Bitmap operator|(const Bitmap& other) const;
+
+  /**
+   * @brief flip the bits in the bitmap (bitwise NOT).
+   *
+   * @return a new Bitmap that is the result of the bitwise NOT operation.
+   */
+  Bitmap operator~() const;
+
+  /**
+   * @brief get the indices of all set bits (value 1) in the bitmap.
+   *
+   * @return a vector of indices where the bit is set to 1, in ascending order.
+   */
+  std::vector<size_t> get_indices() const;
+
+  /**
+   * @brief get the indices of all set bits (value 1) as an unordered set.
+   *
+   * @return an unordered set of indices where the bit is set to 1.
+   */
+  std::unordered_set<size_t> get_indices_set() const;
+
+  /**
+   * @brief convert the bitmap to a string representation.
+   *
+   * @return a string representation of the bitmap, where '1' represents a set
+   * bit and '0' represents a clear bit.
+   */
+  std::string to_string() const;
+
+  /**
+   * @brief Destructor.
+   */
+  ~Bitmap();
+
+ private:
+  size_t size_;
+  std::vector<uint8_t> data_;
+};
+
+}  // namespace storage_manager
+
+}  // namespace lmcache
diff --git a/csrc/storage_manager/fold.cpp b/csrc/storage_manager/fold.cpp
new file mode 100644
index 0000000..54e6157
--- /dev/null
+++ b/csrc/storage_manager/fold.cpp
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "fold.h"
+
+#include <algorithm>
+
+namespace lmcache {
+
+namespace storage_manager {
+
+Bitmap fold(const Bitmap& found, size_t num_chunks, size_t num_ranks,
+            const std::vector<int64_t>& group_windows) {
+  const size_t num_groups = group_windows.size();
+  const size_t group_stride = num_chunks * num_ranks;
+
+  // ``servable[j]`` (bit ``j``, prefix length ``j + 1``) stays set only if
+  // every group can serve a length-``j + 1`` prefix under its rule. ``run`` is
+  // the count of consecutive present chunks ending at the current chunk, so a
+  // length-L prefix needs the last ``min(window, L)`` chunks present, i.e.
+  // ``run >= min(window, L)``.
+  std::vector<char> servable(num_chunks, 1);
+  for (size_t g = 0; g < num_groups; ++g) {
+    const int64_t window = group_windows[g];
+    const size_t eff_window =
+        (window <= 0) ? num_chunks : static_cast<size_t>(window);
+    const size_t gbase = g * group_stride;
+    size_t run = 0;
+    for (size_t prefix_len = 1; prefix_len <= num_chunks; ++prefix_len) {
+      const size_t cbase = gbase + (prefix_len - 1) * num_ranks;
+      bool chunk_present = true;
+      for (size_t r = 0; r < num_ranks; ++r) {
+        if (!found.test(cbase + r)) {
+          chunk_present = false;
+          break;
+        }
+      }
+      run = chunk_present ? run + 1 : 0;
+      if (servable[prefix_len - 1] && run < std::min(eff_window, prefix_len)) {
+        servable[prefix_len - 1] = 0;
+      }
+    }
+  }
+
+  Bitmap servable_lengths(num_chunks);
+  for (size_t j = 0; j < num_chunks; ++j) {
+    if (servable[j]) servable_lengths.set(j);
+  }
+  return servable_lengths;
+}
+
+Bitmap unfold(size_t hit_length, size_t num_chunks, size_t num_ranks,
+              const std::vector<int64_t>& group_windows) {
+  if (hit_length > num_chunks) hit_length = num_chunks;
+  const size_t num_groups = group_windows.size();
+  const size_t group_stride = num_chunks * num_ranks;
+
+  // The chunks each group needs to serve ``hit_length``, expanded over every
+  // kv_rank. The retained cells of a group are a contiguous bit range
+  // ``[gbase + lo * num_ranks, gbase + hit_length * num_ranks)``, so a single
+  // ``set_range`` (whole-byte fill) covers each group.
+  Bitmap retain_mask(num_groups * group_stride);
+  if (hit_length == 0) return retain_mask;
+  for (size_t g = 0; g < num_groups; ++g) {
+    const int64_t window = group_windows[g];
+    size_t lo = 0;
+    if (window > 0 && hit_length > static_cast<size_t>(window)) {
+      lo = hit_length - static_cast<size_t>(window);
+    }
+    const size_t gbase = g * group_stride;
+    retain_mask.set_range(gbase + lo * num_ranks,
+                          gbase + hit_length * num_ranks);
+  }
+  return retain_mask;
+}
+
+}  // namespace storage_manager
+
+}  // namespace lmcache
diff --git a/csrc/storage_manager/fold.h b/csrc/storage_manager/fold.h
new file mode 100644
index 0000000..0f434f1
--- /dev/null
+++ b/csrc/storage_manager/fold.h
@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <utility>
+#include <vector>
+
+#include "bitmap.h"
+
+namespace lmcache {
+
+namespace storage_manager {
+
+/**
+ * @brief Fold per-(group, chunk, rank) presence into servable prefix lengths.
+ *
+ * For each object group, computes which prefix lengths it can serve under its
+ * rule (full attention or a cross-chunk sliding window), and intersects across
+ * groups. The result feeds :func:`Bitmap::highest_set_bit`; the model-wide hit
+ * length is that index plus one (``-1`` -> hit length 0), then :func:`unfold`.
+ *
+ * The input ``found`` is group-major / chunk-major / rank-minor: bit
+ * ``g * (num_chunks * num_ranks) + j * num_ranks + r`` is set iff chunk ``j``
+ * of object group ``g`` is present for kv_rank ``r``. A chunk counts as present
+ * for a group only when every kv_rank shard is present.
+ *
+ * @param found Presence bitmap of length
+ *     ``group_windows.size() * num_chunks * num_ranks``.
+ * @param num_chunks Number of LMCache chunks in the request.
+ * @param num_ranks Number of kv_rank shards per chunk.
+ * @param group_windows Per-object-group cross-chunk sliding-window size in
+ *     chunks, in object-group order; ``<= 0`` means full attention.
+ *
+ * @return A bitmap of size ``num_chunks``; bit ``j`` set iff every group can
+ *     serve a length-``j + 1`` prefix.
+ */
+Bitmap fold(const Bitmap& found, size_t num_chunks, size_t num_ranks,
+            const std::vector<int64_t>& group_windows);
+
+/**
+ * @brief Expand a model-wide hit length into the per-group retain mask.
+ *
+ * Each group retains the chunks it needs to serve ``hit_length``: ``[0,
+ * hit_length)`` for full attention, ``[hit_length - window, hit_length)`` for a
+ * sliding window. The mask is over the same ranked layout as :func:`fold`'s
+ * input (all kv_ranks of each retained ``(group, chunk)`` set).
+ *
+ * @param hit_length Model-wide prefix hit length in chunks (clamped to
+ *     ``num_chunks``).
+ * @param num_chunks Number of LMCache chunks in the request.
+ * @param num_ranks Number of kv_rank shards per chunk.
+ * @param group_windows Per-object-group cross-chunk sliding-window size in
+ *     chunks, in object-group order; ``<= 0`` means full attention.
+ *
+ * @return Retain mask of length
+ *     ``group_windows.size() * num_chunks * num_ranks``.
+ */
+Bitmap unfold(size_t hit_length, size_t num_chunks, size_t num_ranks,
+              const std::vector<int64_t>& group_windows);
+
+}  // namespace storage_manager
+
+}  // namespace lmcache
diff --git a/csrc/storage_manager/periodic_event_notifier.cpp b/csrc/storage_manager/periodic_event_notifier.cpp
new file mode 100644
index 0000000..e3fa914
--- /dev/null
+++ b/csrc/storage_manager/periodic_event_notifier.cpp
@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "periodic_event_notifier.h"
+
+#include <cerrno>
+#include <cstdio>
+#include <algorithm>
+
+namespace lmcache {
+namespace storage_manager {
+
+std::mutex PeriodicEventNotifier::create_mutex_;
+std::unique_ptr<PeriodicEventNotifier> PeriodicEventNotifier::instance_;
+
+PeriodicEventNotifier::PeriodicEventNotifier(int interval_ms, bool use_eventfd)
+    : interval_ms_(std::max(1, interval_ms)), use_eventfd_(use_eventfd) {
+  thread_ = std::thread(&PeriodicEventNotifier::thread_func, this);
+}
+
+PeriodicEventNotifier::~PeriodicEventNotifier() {
+  stop_.store(true, std::memory_order_release);
+  cv_.notify_all();
+  if (thread_.joinable()) {
+    thread_.join();
+  }
+}
+
+void PeriodicEventNotifier::create(int interval_ms, bool use_eventfd) {
+  std::lock_guard<std::mutex> lock(create_mutex_);
+  if (instance_) {
+    return;
+  }
+  instance_.reset(new PeriodicEventNotifier(interval_ms, use_eventfd));
+}
+
+PeriodicEventNotifier* PeriodicEventNotifier::get() { return instance_.get(); }
+
+void PeriodicEventNotifier::shutdown() {
+  std::lock_guard<std::mutex> lock(create_mutex_);
+  if (!instance_) {
+    return;
+  }
+  instance_->stop_.store(true, std::memory_order_release);
+  instance_->cv_.notify_all();
+  if (instance_->thread_.joinable()) {
+    instance_->thread_.join();
+  }
+  instance_.reset();
+}
+
+void PeriodicEventNotifier::register_fd(int fd) {
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    fds_.insert(fd);
+  }
+  cv_.notify_one();
+}
+
+void PeriodicEventNotifier::unregister_fd(int fd) {
+  std::lock_guard<std::mutex> lock(mutex_);
+  fds_.erase(fd);
+}
+
+void PeriodicEventNotifier::set_interval_ms(int interval_ms) {
+  interval_ms_.store(std::max(1, interval_ms), std::memory_order_release);
+  cv_.notify_one();
+}
+
+void PeriodicEventNotifier::signal_fd(int fd) {
+  if (use_eventfd_) {
+    uint64_t one = 1;
+    for (;;) {
+      ssize_t w = ::write(fd, &one, sizeof(one));
+      if (w == static_cast<ssize_t>(sizeof(one))) return;
+      if (w < 0) {
+        if (errno == EINTR) continue;
+        if (errno == EAGAIN || errno == EWOULDBLOCK) return;
+        return;
+      }
+    }
+  } else {
+    uint8_t one = 1;
+    for (;;) {
+      ssize_t w = ::write(fd, &one, sizeof(one));
+      if (w == 1) return;
+      if (w < 0) {
+        if (errno == EINTR) continue;
+        if (errno == EAGAIN || errno == EWOULDBLOCK) return;
+        return;
+      }
+    }
+  }
+}
+
+void PeriodicEventNotifier::thread_func() {
+  while (true) {
+    {
+      std::unique_lock<std::mutex> lock(mutex_);
+      cv_.wait(lock, [this] {
+        return stop_.load(std::memory_order_acquire) || !fds_.empty();
+      });
+      if (stop_.load(std::memory_order_acquire)) {
+        return;
+      }
+    }
+
+    while (!stop_.load(std::memory_order_acquire)) {
+      std::vector<int> snapshot;
+      {
+        std::lock_guard<std::mutex> lock(mutex_);
+        if (fds_.empty()) {
+          break;
+        }
+        snapshot.assign(fds_.begin(), fds_.end());
+      }
+
+      for (int fd : snapshot) {
+        signal_fd(fd);
+      }
+
+      {
+        std::unique_lock<std::mutex> lock(mutex_);
+        cv_.wait_for(lock,
+                     std::chrono::milliseconds(
+                         interval_ms_.load(std::memory_order_acquire)),
+                     [this] { return stop_.load(std::memory_order_acquire); });
+      }
+    }
+  }
+}
+
+}  // namespace storage_manager
+}  // namespace lmcache
diff --git a/csrc/storage_manager/periodic_event_notifier.h b/csrc/storage_manager/periodic_event_notifier.h
new file mode 100644
index 0000000..64761d8
--- /dev/null
+++ b/csrc/storage_manager/periodic_event_notifier.h
@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <unistd.h>
+#include <atomic>
+#include <chrono>
+#include <condition_variable>
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <thread>
+#include <unordered_set>
+#include <vector>
+
+namespace lmcache {
+namespace storage_manager {
+
+class PeriodicEventNotifier {
+ public:
+  static void create(int interval_ms, bool use_eventfd);
+  static PeriodicEventNotifier* get();
+  static void shutdown();
+
+  void register_fd(int fd);
+  void unregister_fd(int fd);
+  void set_interval_ms(int interval_ms);
+
+  ~PeriodicEventNotifier();
+
+  PeriodicEventNotifier(const PeriodicEventNotifier&) = delete;
+  PeriodicEventNotifier& operator=(const PeriodicEventNotifier&) = delete;
+
+ private:
+  PeriodicEventNotifier(int interval_ms, bool use_eventfd);
+
+  void thread_func();
+  void signal_fd(int fd);
+
+  static std::mutex create_mutex_;
+  static std::unique_ptr<PeriodicEventNotifier> instance_;
+
+  std::thread thread_;
+  std::mutex mutex_;
+  std::condition_variable cv_;
+  std::atomic<bool> stop_{false};
+
+  std::atomic<int> interval_ms_;
+  bool use_eventfd_;
+
+  std::unordered_set<int> fds_;
+};
+
+}  // namespace storage_manager
+}  // namespace lmcache
diff --git a/csrc/storage_manager/pybind.cpp b/csrc/storage_manager/pybind.cpp
new file mode 100644
index 0000000..d17436e
--- /dev/null
+++ b/csrc/storage_manager/pybind.cpp
@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include "ttl_lock.h"
+#include "bitmap.h"
+#include "fold.h"
+#include "periodic_event_notifier.h"
+#include "utils.h"
+
+namespace py = pybind11;
+
+using lmcache::storage_manager::Bitmap;
+using lmcache::storage_manager::PeriodicEventNotifier;
+using lmcache::storage_manager::TTLLock;
+using lmcache::utils::ParallelPatternMatcher;
+using lmcache::utils::RangePatternMatcher;
+
+PYBIND11_MODULE(native_storage_ops, m) {
+  m.doc() = "Native storage operations for LMCache";
+
+  m.def("fold", &lmcache::storage_manager::fold, py::arg("found"),
+        py::arg("num_chunks"), py::arg("num_ranks"), py::arg("group_windows"),
+        "Fold per-(group, chunk, rank) presence into a servable-prefix-lengths "
+        "bitmap (size num_chunks + 1); bit L set iff every object group can "
+        "serve a length-L prefix.");
+  m.def(
+      "unfold", &lmcache::storage_manager::unfold, py::arg("hit_length"),
+      py::arg("num_chunks"), py::arg("num_ranks"), py::arg("group_windows"),
+      "Expand a model-wide hit length into the per-group retain mask over the "
+      "group x chunk x kv_rank layout.");
+
+  py::class_<TTLLock>(m, "TTLLock")
+      .def(py::init<uint32_t>(), py::arg("ttl_second") = 300,
+           "Construct a TTLLock with the specified TTL duration in "
+           "seconds. Default is 300 seconds.")
+      .def("lock", &TTLLock::lock,
+           "Increment the lock counter by 1 and update the TTL. "
+           "If the previous TTL has expired, reset counter to 1.")
+      .def("unlock", &TTLLock::unlock,
+           "Decrement the lock counter by 1 (minimum 0).")
+      .def("is_locked", &TTLLock::is_locked,
+           "Check if the lock is held (counter > 0 and TTL not expired).")
+      .def("reset", &TTLLock::reset,
+           "Reset the lock to initial state (counter = 0, TTL expired).");
+
+  py::class_<Bitmap>(m, "Bitmap")
+      .def(py::init<size_t>(), py::arg("size"),
+           "Construct a Bitmap with the specified size.")
+      .def(py::init<size_t, size_t>(), py::arg("size"), py::arg("prefix_bits"),
+           "Construct a Bitmap with the specified size and first N prefix "
+           "bits set to 1.")
+      .def("set", &Bitmap::set, py::arg("index"),
+           "Set the bit at the specified index to 1.")
+      .def("clear", &Bitmap::clear, py::arg("index"),
+           "Clear the bit at the specified index to 0.")
+      .def("test", &Bitmap::test, py::arg("index"),
+           "Test the bit at the specified index.")
+      .def("popcount", &Bitmap::popcount, "Count the number of bits set to 1.")
+      .def("count_leading_zeros", &Bitmap::clz,
+           "Count the number of leading zeros.")
+      .def("count_leading_ones", &Bitmap::clo,
+           "Count the number of leading ones.")
+      .def("highest_set_bit", &Bitmap::highest_set_bit,
+           "Index of the highest set bit, or -1 if no bit is set (the return "
+           "is signed so the empty bitmap is representable).")
+      .def("__and__", &Bitmap::operator&, py::arg("other"),
+           "Bitwise AND operation between two bitmaps.")
+      .def("__or__", &Bitmap::operator|, py::arg("other"),
+           "Bitwise OR operation between two bitmaps.")
+      .def("__invert__", &Bitmap::operator~,
+           "Bitwise NOT operation (flip all bits).")
+      .def("get_indices_list", &Bitmap::get_indices,
+           "Return a list of indices where the bit is set to 1.")
+      .def("get_indices_set", &Bitmap::get_indices_set,
+           "Return a set of indices where the bit is set to 1.")
+      .def("batched_set", &Bitmap::batched_set, py::arg("indices"),
+           "Set every bit in indices to 1 (positions >= size ignored).")
+      .def("set_range", &Bitmap::set_range, py::arg("start"), py::arg("end"),
+           "Set every bit in the half-open range [start, end) to 1 (end "
+           "clamped to size). Fills whole bytes, so far cheaper than per-bit "
+           "set for a contiguous span.")
+      .def(
+          "gather",
+          [](const Bitmap& self, const py::sequence& items) {
+            auto indices = self.get_indices();
+            py::list result;
+            for (auto idx : indices) {
+              if (idx < static_cast<size_t>(py::len(items))) {
+                result.append(items[idx]);
+              }
+            }
+            return result;
+          },
+          py::arg("items"),
+          "Return elements from items at indices where the bit is set to 1.")
+      .def("__repr__", &Bitmap::to_string,
+           "Convert the bitmap to a string representation.");
+
+  py::class_<ParallelPatternMatcher>(m, "ParallelPatternMatcher")
+      .def(py::init<const std::vector<int>&>(), py::arg("pattern"),
+           "Construct a ParallelPatternMatcher with the specified pattern.")
+      .def("match", &ParallelPatternMatcher::match, py::arg("data"),
+           "Match the pattern in the given data and return a sorted list "
+           "of positions where the pattern starts.");
+
+  py::class_<RangePatternMatcher>(m, "RangePatternMatcher")
+      .def(py::init<const std::vector<int>&, const std::vector<int>&>(),
+           py::arg("start_pattern"), py::arg("end_pattern"),
+           "Construct a RangePatternMatcher with start and end patterns. ")
+      .def("match", &RangePatternMatcher::match, py::arg("data"),
+           "Match ranges in the given data. Returns a list of (start_pos, "
+           "end_pos) tuples where start_pos is the beginning of the start "
+           "pattern and end_pos is the exclusive index after the end pattern. "
+           "When multiple end patterns exist after a start pattern, matches "
+           "the first one (minimal range).");
+
+  py::class_<PeriodicEventNotifier>(m, "PeriodicEventNotifier")
+      .def_static("create", &PeriodicEventNotifier::create,
+                  py::call_guard<py::gil_scoped_release>(),
+                  py::arg("interval_ms"), py::arg("use_eventfd"),
+                  "Create the singleton PeriodicEventNotifier. "
+                  "Idempotent -- second call is a no-op.")
+      .def_static("get", &PeriodicEventNotifier::get,
+                  py::return_value_policy::reference,
+                  "Get the singleton instance, or None if not created.")
+      .def_static("shutdown", &PeriodicEventNotifier::shutdown,
+                  py::call_guard<py::gil_scoped_release>(),
+                  "Shut down the singleton. Idempotent.")
+      .def("register_fd", &PeriodicEventNotifier::register_fd, py::arg("fd"),
+           "Register a file descriptor for periodic signaling.")
+      .def("unregister_fd", &PeriodicEventNotifier::unregister_fd,
+           py::arg("fd"), "Unregister a file descriptor.")
+      .def("set_interval_ms", &PeriodicEventNotifier::set_interval_ms,
+           py::arg("interval_ms"),
+           "Change the notification interval in milliseconds.");
+}
diff --git a/csrc/storage_manager/ttl_lock.cpp b/csrc/storage_manager/ttl_lock.cpp
new file mode 100644
index 0000000..352ff77
--- /dev/null
+++ b/csrc/storage_manager/ttl_lock.cpp
@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "ttl_lock.h"
+
+namespace lmcache {
+namespace storage_manager {
+
+TTLLock::TTLLock(uint32_t ttl_sec)
+    : counter_(0),
+      expiration_ms_(0),
+      ttl_ms_(static_cast<int64_t>(ttl_sec) * 1000) {}
+
+void TTLLock::lock() {
+  int64_t current_time = now_ms();
+  int64_t new_expiration = current_time + ttl_ms_;
+
+  // Use compare-and-swap loop to handle the TTL expiration case
+  while (true) {
+    int64_t old_expiration = expiration_ms_.load(std::memory_order_acquire);
+    int64_t old_counter = counter_.load(std::memory_order_acquire);
+
+    // Check if TTL has expired
+    bool expired = (current_time >= old_expiration);
+
+    if (expired) {
+      // TTL expired, try to reset counter to 1 and set new expiration
+      // First, try to update the expiration
+      if (expiration_ms_.compare_exchange_strong(old_expiration, new_expiration,
+                                                 std::memory_order_seq_cst)) {
+        // Successfully updated expiration, now set counter to 1
+        counter_.store(1, std::memory_order_seq_cst);
+        return;
+      }
+      // Another thread updated expiration, retry
+      continue;
+    } else {
+      // TTL not expired, try to increment counter
+      if (counter_.compare_exchange_strong(old_counter, old_counter + 1,
+                                           std::memory_order_seq_cst)) {
+        // Successfully incremented counter, update expiration
+        expiration_ms_.store(new_expiration, std::memory_order_seq_cst);
+        return;
+      }
+      // Another thread modified counter, retry
+      continue;
+    }
+  }
+}
+
+void TTLLock::unlock() {
+  // Use compare-and-swap loop to ensure we don't go below 0
+  while (true) {
+    int64_t old_counter = counter_.load(std::memory_order_acquire);
+
+    if (old_counter <= 0) {
+      // Already at 0, nothing to do
+      return;
+    }
+
+    if (counter_.compare_exchange_strong(old_counter, old_counter - 1,
+                                         std::memory_order_seq_cst)) {
+      return;
+    }
+    // Another thread modified counter, retry
+  }
+}
+
+bool TTLLock::is_locked() const {
+  int64_t current_time = now_ms();
+  int64_t expiration = expiration_ms_.load(std::memory_order_acquire);
+  int64_t counter = counter_.load(std::memory_order_acquire);
+
+  // Lock is held if counter > 0 AND TTL not expired
+  return (counter > 0) && (current_time < expiration);
+}
+
+void TTLLock::reset() {
+  counter_.store(0, std::memory_order_seq_cst);
+  expiration_ms_.store(0, std::memory_order_seq_cst);
+}
+
+int64_t TTLLock::now_ms() {
+  auto now = Clock::now();
+  return to_ms(now);
+}
+
+int64_t TTLLock::to_ms(const TimePoint& tp) {
+  return static_cast<int64_t>(
+      std::chrono::duration_cast<std::chrono::milliseconds>(
+          tp.time_since_epoch())
+          .count());
+}
+
+}  // namespace storage_manager
+}  // namespace lmcache
diff --git a/csrc/storage_manager/ttl_lock.h b/csrc/storage_manager/ttl_lock.h
new file mode 100644
index 0000000..0b4a3f4
--- /dev/null
+++ b/csrc/storage_manager/ttl_lock.h
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <atomic>
+#include <chrono>
+#include <cstdint>
+
+namespace lmcache {
+namespace storage_manager {
+
+/**
+ * @brief A thread-safe lock with TTL (Time-To-Live) support.
+ *
+ * This lock maintains a counter that can be incremented (lock) and decremented
+ * (unlock). The lock also has a TTL mechanism - if the TTL expires, the lock
+ * is considered unlocked regardless of the counter value.
+ *
+ * Thread Safety:
+ * - All operations are thread-safe using atomic operations.
+ * - lock() and unlock() use memory_order_seq_cst for full synchronization.
+ * - is_locked() uses memory_order_acquire for visibility guarantees.
+ */
+class TTLLock {
+ public:
+  /**
+   * @brief Construct a new TTLLock with the specified TTL duration.
+   *
+   * @param ttl_second The TTL duration in seconds. Default is 300 seconds.
+   */
+  explicit TTLLock(uint32_t ttl_second = 300);
+
+  /**
+   * @brief Increment the lock counter by 1 and update the TTL.
+   *
+   * If the previous TTL has expired, the counter is reset to 1.
+   * Otherwise, the counter is incremented by 1.
+   * The TTL is always refreshed to the current time + TTL duration.
+   */
+  void lock();
+
+  /**
+   * @brief Decrement the lock counter by 1.
+   *
+   * The counter will not go below 0.
+   */
+  void unlock();
+
+  /**
+   * @brief Check if the lock is currently held.
+   *
+   * The lock is considered held if:
+   * 1. The counter is greater than 0, AND
+   * 2. The TTL has not expired.
+   *
+   * @return true if the lock is held, false otherwise.
+   */
+  bool is_locked() const;
+
+  /**
+   * @brief Reset the lock to initial state (counter = 0, TTL expired).
+   */
+  void reset();
+
+ private:
+  using Clock = std::chrono::steady_clock;
+  using TimePoint = std::chrono::time_point<Clock>;
+
+  /**
+   * @brief Get the current timestamp in milliseconds since epoch.
+   */
+  static int64_t now_ms();
+
+  /**
+   * @brief Convert TimePoint to milliseconds since epoch.
+   */
+  static int64_t to_ms(const TimePoint& tp);
+
+  // The lock counter
+  std::atomic<int64_t> counter_;
+
+  // The expiration time in milliseconds since steady_clock epoch
+  std::atomic<int64_t> expiration_ms_;
+
+  // The TTL duration in milliseconds
+  const int64_t ttl_ms_;
+};
+
+}  // namespace storage_manager
+}  // namespace lmcache
diff --git a/csrc/storage_manager/utils.cpp b/csrc/storage_manager/utils.cpp
new file mode 100644
index 0000000..f1cb742
--- /dev/null
+++ b/csrc/storage_manager/utils.cpp
@@ -0,0 +1,111 @@
+#include "utils.h"
+#include <algorithm>
+#include <stdexcept>
+
+namespace lmcache {
+namespace utils {
+
+ParallelPatternMatcher::ParallelPatternMatcher(const std::vector<int>& pattern)
+    : pattern_(pattern) {
+  if (pattern_.empty()) {
+    throw std::invalid_argument("Pattern cannot be empty");
+  }
+}
+
+std::vector<int> ParallelPatternMatcher::match(const std::vector<int>& data) {
+  // Handle edge cases
+  if (data.size() < pattern_.size()) {
+    return std::vector<int>();
+  }
+
+  std::vector<int> matches;
+
+  // Search for pattern in the data
+  size_t search_end = data.size() - pattern_.size() + 1;
+
+  for (size_t i = 0; i < search_end; ++i) {
+    bool match = true;
+    for (size_t j = 0; j < pattern_.size(); ++j) {
+      if (data[i + j] != pattern_[j]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) {
+      matches.push_back(static_cast<int>(i));
+    }
+  }
+
+  return matches;
+}
+
+RangePatternMatcher::RangePatternMatcher(const std::vector<int>& start_pattern,
+                                         const std::vector<int>& end_pattern)
+    : start_pattern_(start_pattern), end_pattern_(end_pattern) {
+  if (start_pattern_.empty()) {
+    throw std::invalid_argument("Start pattern cannot be empty");
+  }
+  if (end_pattern_.empty()) {
+    throw std::invalid_argument("End pattern cannot be empty");
+  }
+}
+
+bool RangePatternMatcher::matchesAt(const std::vector<int>& data, size_t pos,
+                                    const std::vector<int>& pattern) const {
+  if (pos + pattern.size() > data.size()) {
+    return false;
+  }
+  for (size_t i = 0; i < pattern.size(); ++i) {
+    if (data[pos + i] != pattern[i]) {
+      return false;
+    }
+  }
+  return true;
+}
+
+std::vector<std::pair<int, int>> RangePatternMatcher::match(
+    const std::vector<int>& data) {
+  std::vector<std::pair<int, int>> ranges;
+
+  // Handle edge cases
+  if (data.size() < start_pattern_.size() + end_pattern_.size()) {
+    return ranges;
+  }
+
+  size_t i = 0;
+  while (i <= data.size() - start_pattern_.size()) {
+    // Check if start pattern matches at position i
+    if (matchesAt(data, i, start_pattern_)) {
+      int start_pos = static_cast<int>(i);
+
+      // Look for the first end pattern after the start pattern
+      size_t search_start = i + start_pattern_.size();
+      bool found_end = false;
+
+      for (size_t j = search_start; j <= data.size() - end_pattern_.size();
+           ++j) {
+        if (matchesAt(data, j, end_pattern_)) {
+          int end_pos = static_cast<int>(j + end_pattern_.size());
+          ranges.push_back({start_pos, end_pos});
+
+          // Move to the position after this range to continue searching
+          i = j + end_pattern_.size();
+          found_end = true;
+          break;
+        }
+      }
+
+      // If no end pattern was found, move past the start pattern
+      if (!found_end) {
+        i += start_pattern_.size();
+      }
+    } else {
+      ++i;
+    }
+  }
+
+  return ranges;
+}
+
+}  // namespace utils
+}  // namespace lmcache
diff --git a/csrc/storage_manager/utils.h b/csrc/storage_manager/utils.h
new file mode 100644
index 0000000..683dd3f
--- /dev/null
+++ b/csrc/storage_manager/utils.h
@@ -0,0 +1,83 @@
+#pragma once
+
+#include <cstddef>
+#include <vector>
+
+namespace lmcache {
+namespace utils {
+
+/**
+ * @brief Pattern matcher for integer vectors
+ *
+ * This class performs pattern matching on a vector of integers.
+ * It finds all positions where a given pattern occurs in the input data.
+ */
+class ParallelPatternMatcher {
+ public:
+  /**
+   * @brief Construct a new Pattern Matcher object
+   *
+   * @param pattern The pattern to search for
+   */
+  ParallelPatternMatcher(const std::vector<int>& pattern);
+
+  /**
+   * @brief Match the pattern in the given data
+   *
+   * @param data The data to search in
+   * @return std::vector<int> Sorted vector of positions where pattern starts
+   */
+  std::vector<int> match(const std::vector<int>& data);
+
+ private:
+  std::vector<int> pattern_;
+};
+
+/**
+ * @brief Range pattern matcher for integer vectors
+ *
+ * This class performs range pattern matching on a vector of integers.
+ * It finds ranges that start with a start pattern and end with an end pattern.
+ * When multiple end patterns exist after a start pattern, it matches the first
+ * one (minimal range).
+ */
+class RangePatternMatcher {
+ public:
+  /**
+   * @brief Construct a new Range Pattern Matcher object
+   *
+   * @param start_pattern The pattern marking the start of a range (1-5
+   * elements)
+   * @param end_pattern The pattern marking the end of a range (1-5 elements)
+   */
+  RangePatternMatcher(const std::vector<int>& start_pattern,
+                      const std::vector<int>& end_pattern);
+
+  /**
+   * @brief Match ranges in the given data
+   *
+   * @param data The data to search in
+   * @return std::vector<std::pair<int, int>> Vector of (start_pos, end_pos)
+   * pairs where start_pos is the beginning of the start pattern and end_pos is
+   * the exclusive index after the end pattern
+   */
+  std::vector<std::pair<int, int>> match(const std::vector<int>& data);
+
+ private:
+  std::vector<int> start_pattern_;
+  std::vector<int> end_pattern_;
+
+  /**
+   * @brief Check if a pattern matches at a specific position
+   *
+   * @param data The data to search in
+   * @param pos The position to check
+   * @param pattern The pattern to match
+   * @return true if pattern matches at pos, false otherwise
+   */
+  bool matchesAt(const std::vector<int>& data, size_t pos,
+                 const std::vector<int>& pattern) const;
+};
+
+}  // namespace utils
+}  // namespace lmcache
diff --git a/csrc/sycl/ac_dec_sycl.cpp b/csrc/sycl/ac_dec_sycl.cpp
new file mode 100644
index 0000000..ff676b4
--- /dev/null
+++ b/csrc/sycl/ac_dec_sycl.cpp
@@ -0,0 +1,551 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Arithmetic-coding decoder for Intel XPU.  Provides:
+//   decode_fast_new_xpu      -- per-channel buffer input
+//   decode_fast_prefsum_xpu  -- 1-D packed bytestream + prefix-sum offsets
+//
+// Algorithm
+// ---------
+//   One work-item per (layer, channel); each runs an independent
+//   arithmetic-decoder state machine over `ntokens` symbols, with an
+//   unrolled binary search over the channel's CDF.
+//
+// Intel XPU mapping
+// -----------------
+//   - 2-D nd_range (layer x channel_block * BLOCK_SIZE).
+//   - SLM: CDF [MAX_LP * BLOCK_SIZE] uint16, per-channel byte buffer
+//     [BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD] uint8.
+//   - Sub-group size locked to 16 (Xe native SIMD).
+//   - Binary search uses a simple loop with compile-time bound
+//     max_symbol <= MAX_LP-2 < 64 so the IGC unrolls it to ~6 comparisons.
+//
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#include <sycl/sycl.hpp>
+#pragma GCC diagnostic pop
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <c10/core/DeviceGuard.h>
+#include <c10/xpu/XPUStream.h>
+
+#include "cachegen_kernels_sycl.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <stdexcept>
+
+namespace {
+
+constexpr int MAX_LP = 64;
+constexpr int OUTPUT_BUFFER_LENGTH_PER_THREAD = 256;
+constexpr int MAX_TOKENS_PER_THREAD = 256;
+constexpr int PRECISION = 16;
+constexpr int INTEL_SUB_GROUP_SIZE = 16;
+
+inline uint32_t big_to_small_u32(uint32_t value) {
+  return ((value & 0xFF000000u) >> 24) | ((value & 0x00FF0000u) >> 8) |
+         ((value & 0x0000FF00u) << 8) | ((value & 0x000000FFu) << 24);
+}
+
+template <int BLOCK_SIZE, typename SLMRef>
+inline uint16_t binsearch(SLMRef cdf_shared, uint16_t target, uint8_t max_sym,
+                          int tid) {
+  uint16_t left = 0;
+  uint16_t right = static_cast<uint16_t>(max_sym + 1);
+  while (left + 1 < right) {
+    const uint16_t m = static_cast<uint16_t>((left + right) / 2);
+    const int offset = m * BLOCK_SIZE + tid;
+    const uint16_t v = cdf_shared[offset];
+    if (v < target) {
+      left = m;
+    } else if (v > target) {
+      right = m;
+    } else {
+      return m;
+    }
+  }
+  return left;
+}
+
+template <int BLOCK_SIZE>
+void launch_decode_per_channel(sycl::queue& queue, const int16_t* cdf,
+                               const uint8_t* bytestreams,
+                               const int32_t* lengths, uint8_t* output,
+                               int nlayers, int nchannels, int ntokens,
+                               int lp) {
+  const int channel_blocks = nchannels / BLOCK_SIZE;
+  sycl::range<2> global_range(static_cast<size_t>(nlayers),
+                              static_cast<size_t>(channel_blocks) * BLOCK_SIZE);
+  sycl::range<2> local_range(1, BLOCK_SIZE);
+
+  queue.submit([&](sycl::handler& cgh) {
+    sycl::local_accessor<uint16_t, 1> cdf_shared(
+        sycl::range<1>(MAX_LP * BLOCK_SIZE), cgh);
+    sycl::local_accessor<uint8_t, 1> bs_shared(
+        sycl::range<1>(BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD), cgh);
+    sycl::local_accessor<int32_t, 1> len_shared(sycl::range<1>(BLOCK_SIZE),
+                                                cgh);
+
+    cgh.parallel_for(
+        sycl::nd_range<2>(global_range, local_range),
+        [=](sycl::nd_item<2> item) [[sycl::reqd_sub_group_size(
+            INTEL_SUB_GROUP_SIZE)]] {
+          const int layer_id = static_cast<int>(item.get_group(0));
+          const int block_y = static_cast<int>(item.get_group(1));
+          const int tx = static_cast<int>(item.get_local_id(1));
+          const int global_channel_offset = block_y * BLOCK_SIZE;
+          const int global_channel_id = global_channel_offset + tx;
+          const int max_symbol = lp - 2;
+
+          // Load per-channel lengths into SLM.
+          len_shared[tx] =
+              lengths[layer_id * nchannels + global_channel_offset + tx];
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Load per-channel byte buffers into SLM, flat sweep over
+          // BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD bytes -- each
+          // sub-group lane handles every BLOCK_SIZE-th byte across the
+          // entire tile, removing the per-channel outer loop and giving
+          // the IGC more freedom to schedule the loads.
+          const int total_bytes = BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+          for (int k = tx; k < total_bytes; k += BLOCK_SIZE) {
+            const int i = k / OUTPUT_BUFFER_LENGTH_PER_THREAD;
+            const int j = k - i * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+            const int channel_id = global_channel_offset + i;
+            const int length = len_shared[i];
+            uint8_t v = 0;
+            if (j < length) {
+              const int64_t off =
+                  (static_cast<int64_t>(layer_id) * nchannels + channel_id) *
+                      OUTPUT_BUFFER_LENGTH_PER_THREAD +
+                  j;
+              v = bytestreams[off];
+            }
+            bs_shared[k] = v;
+          }
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Load CDF[layer_id, channel_block, :] into SLM (column-major).
+          const int cdf_size = lp * BLOCK_SIZE;
+          for (int i = tx; i < cdf_size; i += BLOCK_SIZE) {
+            const int cid = i / lp;
+            const int lid = i % lp;
+            const int16_t v = cdf[(static_cast<int64_t>(layer_id) * nchannels +
+                                   global_channel_offset + cid) *
+                                      lp +
+                                  lid];
+            cdf_shared[lid * BLOCK_SIZE + cid] = static_cast<uint16_t>(v);
+          }
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // ---------- AC decode state ----------
+          uint32_t low = 0u;
+          uint32_t high = 0xFFFFFFFFu;
+          const uint32_t c_count = 0x10000u;
+
+          uint8_t byte_buffer = 0;
+          int bit_idx = 1;  // next bit: (byte_buffer >> (8-bit_idx)) & 1
+          int byte_buffer_offset = 4;
+
+          // Initial 32-bit value from first 4 bytes (big-endian); on
+          // little-endian devices this matches a packed load followed
+          // by a byte-swap.
+          const int row_base = tx * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+          uint32_t v0 = (static_cast<uint32_t>(bs_shared[row_base]) << 24) |
+                        (static_cast<uint32_t>(bs_shared[row_base + 1]) << 16) |
+                        (static_cast<uint32_t>(bs_shared[row_base + 2]) << 8) |
+                        static_cast<uint32_t>(bs_shared[row_base + 3]);
+          (void)big_to_small_u32;
+          uint32_t value = v0;
+          byte_buffer = bs_shared[row_base + byte_buffer_offset];
+
+          for (int i = 0; i < ntokens; ++i) {
+            const uint64_t span =
+                static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+            const uint16_t count =
+                static_cast<uint16_t>(((static_cast<uint64_t>(value) -
+                                        static_cast<uint64_t>(low) + 1) *
+                                           c_count -
+                                       1) /
+                                      span);
+
+            const uint16_t sym_i = binsearch<BLOCK_SIZE>(
+                cdf_shared, count, static_cast<uint8_t>(max_symbol), tx);
+
+            output[(static_cast<int64_t>(layer_id) * ntokens + i) * nchannels +
+                   global_channel_id] = static_cast<uint8_t>(sym_i);
+
+            if (i == ntokens - 1) break;
+
+            const uint32_t c_low = cdf_shared[sym_i * BLOCK_SIZE + tx];
+            const uint32_t c_high =
+                sym_i == max_symbol ? 0x10000u
+                                    : cdf_shared[(sym_i + 1) * BLOCK_SIZE + tx];
+
+            high =
+                (low - 1) + static_cast<uint32_t>((span * c_high) >> PRECISION);
+            low = low + static_cast<uint32_t>((span * c_low) >> PRECISION);
+
+            while (true) {
+              if (low >= 0x80000000u || high < 0x80000000u) {
+                low <<= 1;
+                high <<= 1;
+                high |= 1;
+                value = (value << 1) | ((byte_buffer >> (8 - bit_idx)) & 1u);
+                bit_idx += 1;
+              } else if (low >= 0x40000000u && high < 0xC0000000u) {
+                low <<= 1;
+                low &= 0x7FFFFFFFu;
+                high <<= 1;
+                high |= 0x80000001u;
+                value -= 0x40000000u;
+                value = (value << 1) | ((byte_buffer >> (8 - bit_idx)) & 1u);
+                bit_idx += 1;
+              } else {
+                break;
+              }
+
+              if (bit_idx == 9) {
+                bit_idx = 1;
+                byte_buffer_offset += 1;
+                byte_buffer = bs_shared[row_base + byte_buffer_offset];
+              }
+            }
+          }
+        });
+  });
+}
+
+template <int BLOCK_SIZE>
+void launch_decode_prefsum(sycl::queue& queue, const int16_t* cdf,
+                           const uint8_t* bytestreams,
+                           const int64_t* lengths_prefix, uint8_t* output,
+                           int nlayers, int nchannels, int ntokens, int lp) {
+  const int channel_blocks = nchannels / BLOCK_SIZE;
+  sycl::range<2> global_range(static_cast<size_t>(nlayers),
+                              static_cast<size_t>(channel_blocks) * BLOCK_SIZE);
+  sycl::range<2> local_range(1, BLOCK_SIZE);
+
+  queue.submit([&](sycl::handler& cgh) {
+    sycl::local_accessor<uint16_t, 1> cdf_shared(
+        sycl::range<1>(MAX_LP * BLOCK_SIZE), cgh);
+    sycl::local_accessor<uint8_t, 1> bs_shared(
+        sycl::range<1>(BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD), cgh);
+    sycl::local_accessor<int32_t, 1> sum_shared(sycl::range<1>(BLOCK_SIZE + 1),
+                                                cgh);
+
+    cgh.parallel_for(
+        sycl::nd_range<2>(global_range, local_range),
+        [=](sycl::nd_item<2> item) [[sycl::reqd_sub_group_size(
+            INTEL_SUB_GROUP_SIZE)]] {
+          const int layer_id = static_cast<int>(item.get_group(0));
+          const int block_y = static_cast<int>(item.get_group(1));
+          const int tx = static_cast<int>(item.get_local_id(1));
+          const int global_channel_offset = block_y * BLOCK_SIZE;
+          const int global_channel_id = global_channel_offset + tx;
+          const int max_symbol = lp - 2;
+
+          // Load running prefix sums for [BLOCK_SIZE + 1] positions.
+          // Index is the *global* (layer, channel) flattened position.
+          for (int i = tx; i < BLOCK_SIZE + 1; i += BLOCK_SIZE) {
+            const int gid =
+                layer_id * nchannels + global_channel_offset + i - 1;
+            int32_t val = 0;
+            if (gid >= 0) {
+              const int row = gid / nchannels;
+              const int col = gid % nchannels;
+              val = static_cast<int32_t>(lengths_prefix[row * nchannels + col]);
+            }
+            sum_shared[i] = val;
+          }
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Load per-channel byte buffers via prefix-sum windowing.
+          for (int i = 0; i < BLOCK_SIZE; ++i) {
+            const int start_offset = sum_shared[i];
+            const int end_offset = sum_shared[i + 1];
+            const int length = end_offset - start_offset;
+            for (int j = tx; j < OUTPUT_BUFFER_LENGTH_PER_THREAD;
+                 j += BLOCK_SIZE) {
+              uint8_t v = (j < length) ? bytestreams[start_offset + j] : 0;
+              bs_shared[i * OUTPUT_BUFFER_LENGTH_PER_THREAD + j] = v;
+            }
+          }
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Load CDF.
+          const int cdf_size = lp * BLOCK_SIZE;
+          for (int i = tx; i < cdf_size; i += BLOCK_SIZE) {
+            const int cid = i / lp;
+            const int lid = i % lp;
+            const int16_t v = cdf[(static_cast<int64_t>(layer_id) * nchannels +
+                                   global_channel_offset + cid) *
+                                      lp +
+                                  lid];
+            cdf_shared[lid * BLOCK_SIZE + cid] = static_cast<uint16_t>(v);
+          }
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Decode (identical body to per-channel kernel).
+          uint32_t low = 0u;
+          uint32_t high = 0xFFFFFFFFu;
+          const uint32_t c_count = 0x10000u;
+
+          uint8_t byte_buffer = 0;
+          int bit_idx = 1;
+          int byte_buffer_offset = 4;
+
+          const int row_base = tx * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+          uint32_t value =
+              (static_cast<uint32_t>(bs_shared[row_base]) << 24) |
+              (static_cast<uint32_t>(bs_shared[row_base + 1]) << 16) |
+              (static_cast<uint32_t>(bs_shared[row_base + 2]) << 8) |
+              static_cast<uint32_t>(bs_shared[row_base + 3]);
+          byte_buffer = bs_shared[row_base + byte_buffer_offset];
+
+          for (int i = 0; i < ntokens; ++i) {
+            const uint64_t span =
+                static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+            const uint16_t count =
+                static_cast<uint16_t>(((static_cast<uint64_t>(value) -
+                                        static_cast<uint64_t>(low) + 1) *
+                                           c_count -
+                                       1) /
+                                      span);
+
+            const uint16_t sym_i = binsearch<BLOCK_SIZE>(
+                cdf_shared, count, static_cast<uint8_t>(max_symbol), tx);
+            output[(static_cast<int64_t>(layer_id) * ntokens + i) * nchannels +
+                   global_channel_id] = static_cast<uint8_t>(sym_i);
+
+            if (i == ntokens - 1) break;
+
+            const uint32_t c_low = cdf_shared[sym_i * BLOCK_SIZE + tx];
+            const uint32_t c_high =
+                sym_i == max_symbol ? 0x10000u
+                                    : cdf_shared[(sym_i + 1) * BLOCK_SIZE + tx];
+
+            high =
+                (low - 1) + static_cast<uint32_t>((span * c_high) >> PRECISION);
+            low = low + static_cast<uint32_t>((span * c_low) >> PRECISION);
+
+            while (true) {
+              if (low >= 0x80000000u || high < 0x80000000u) {
+                low <<= 1;
+                high <<= 1;
+                high |= 1;
+                value = (value << 1) | ((byte_buffer >> (8 - bit_idx)) & 1u);
+                bit_idx += 1;
+              } else if (low >= 0x40000000u && high < 0xC0000000u) {
+                low <<= 1;
+                low &= 0x7FFFFFFFu;
+                high <<= 1;
+                high |= 0x80000001u;
+                value -= 0x40000000u;
+                value = (value << 1) | ((byte_buffer >> (8 - bit_idx)) & 1u);
+                bit_idx += 1;
+              } else {
+                break;
+              }
+              if (bit_idx == 9) {
+                bit_idx = 1;
+                byte_buffer_offset += 1;
+                byte_buffer = bs_shared[row_base + byte_buffer_offset];
+              }
+            }
+          }
+        });
+  });
+}
+
+int decoder_get_block_size(int nchannels) {
+  int factor = (nchannels ^ (nchannels - 1)) + 1;
+  factor >>= 1;
+  if (factor > 128) factor = 128;
+  return factor;
+}
+
+#define DISPATCH_DECODE_BLOCKSIZE(LAUNCHER, BLOCKSIZE_VAR, ...) \
+  switch (BLOCKSIZE_VAR) {                                      \
+    case 1:                                                     \
+      LAUNCHER<1>(__VA_ARGS__);                                 \
+      break;                                                    \
+    case 2:                                                     \
+      LAUNCHER<2>(__VA_ARGS__);                                 \
+      break;                                                    \
+    case 4:                                                     \
+      LAUNCHER<4>(__VA_ARGS__);                                 \
+      break;                                                    \
+    case 8:                                                     \
+      LAUNCHER<8>(__VA_ARGS__);                                 \
+      break;                                                    \
+    case 16:                                                    \
+      LAUNCHER<16>(__VA_ARGS__);                                \
+      break;                                                    \
+    case 32:                                                    \
+      LAUNCHER<32>(__VA_ARGS__);                                \
+      break;                                                    \
+    case 64:                                                    \
+      LAUNCHER<64>(__VA_ARGS__);                                \
+      break;                                                    \
+    case 128:                                                   \
+      LAUNCHER<128>(__VA_ARGS__);                               \
+      break;                                                    \
+    default:                                                    \
+      throw std::runtime_error("unsupported block size");       \
+  }
+
+}  // namespace
+
+void decode_fast_new_xpu(const at::Tensor& cdf, const at::Tensor& bytestreams,
+                         const at::Tensor& lengths, at::Tensor& output) {
+  if (!cdf.device().is_xpu() || !bytestreams.device().is_xpu() ||
+      !lengths.device().is_xpu() || !output.device().is_xpu()) {
+    throw std::runtime_error("decode_fast_new_xpu: tensors must be on XPU");
+  }
+
+  TORCH_CHECK(cdf.scalar_type() == at::kShort,
+              "decode_fast_new_xpu: cdf must be int16");
+  TORCH_CHECK(bytestreams.scalar_type() == at::kByte,
+              "decode_fast_new_xpu: bytestreams must be uint8");
+  TORCH_CHECK(lengths.scalar_type() == at::kInt,
+              "decode_fast_new_xpu: lengths must be int32");
+  TORCH_CHECK(
+      output.scalar_type() == at::kByte || output.scalar_type() == at::kChar,
+      "decode_fast_new_xpu: output must be uint8 or int8");
+
+  TORCH_CHECK(cdf.dim() == 3,
+              "decode_fast_new_xpu: cdf must be 3-D [nlayers, nchannels, lp]");
+  TORCH_CHECK(bytestreams.dim() == 3,
+              "decode_fast_new_xpu: bytestreams must be 3-D "
+              "[nlayers, nchannels, OUTPUT_BUFFER_LENGTH_PER_THREAD]");
+  TORCH_CHECK(lengths.dim() == 2,
+              "decode_fast_new_xpu: lengths must be 2-D [nlayers, nchannels]");
+  TORCH_CHECK(
+      output.dim() == 3,
+      "decode_fast_new_xpu: output must be 3-D [nlayers, ntokens, nchannels]");
+
+  TORCH_CHECK(bytestreams.size(2) == OUTPUT_BUFFER_LENGTH_PER_THREAD,
+              "decode_fast_new_xpu: bytestreams last dim must equal "
+              "OUTPUT_BUFFER_LENGTH_PER_THREAD (256)");
+
+  TORCH_CHECK(lengths.numel() == 0 || lengths.max().item<int32_t>() <=
+                                          OUTPUT_BUFFER_LENGTH_PER_THREAD,
+              "decode_fast_new_xpu: per-channel length exceeds "
+              "OUTPUT_BUFFER_LENGTH_PER_THREAD (256)");
+
+  const auto cdf_shape = cdf.sizes();
+  const auto out_shape = output.sizes();
+  const int nlayers = static_cast<int>(cdf_shape[0]);
+  const int nchannels = static_cast<int>(cdf_shape[1]);
+  const int lp = static_cast<int>(cdf_shape[2]);
+  const int ntokens = static_cast<int>(out_shape[1]);
+
+  TORCH_CHECK(lp >= 2, "decode_fast_new_xpu: cdf last dim (lp) must be >= 2");
+
+  if (ntokens > MAX_TOKENS_PER_THREAD) {
+    throw std::runtime_error(
+        "decode_fast_new_xpu: ntokens > MAX_TOKENS_PER_THREAD");
+  }
+  if (lp > MAX_LP) {
+    throw std::runtime_error("decode_fast_new_xpu: lp > MAX_LP");
+  }
+
+  const int block_size = decoder_get_block_size(nchannels);
+  if (nchannels % block_size != 0) {
+    throw std::runtime_error(
+        "decode_fast_new_xpu: nchannels must be divisible by block size");
+  }
+
+  auto cdf_c = cdf.is_contiguous() ? cdf : cdf.contiguous();
+  auto bs_c =
+      bytestreams.is_contiguous() ? bytestreams : bytestreams.contiguous();
+  auto len_c = lengths.is_contiguous() ? lengths : lengths.contiguous();
+
+  const c10::DeviceGuard guard(cdf.device());
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(cdf.device().index()).queue();
+
+  const int16_t* cdf_ptr = cdf_c.data_ptr<int16_t>();
+  const uint8_t* bs_ptr = reinterpret_cast<const uint8_t*>(bs_c.data_ptr());
+  const int32_t* len_ptr = len_c.data_ptr<int32_t>();
+  uint8_t* out_ptr = reinterpret_cast<uint8_t*>(output.data_ptr());
+
+  DISPATCH_DECODE_BLOCKSIZE(launch_decode_per_channel, block_size, queue,
+                            cdf_ptr, bs_ptr, len_ptr, out_ptr, nlayers,
+                            nchannels, ntokens, lp);
+}
+
+void decode_fast_prefsum_xpu(const at::Tensor& cdf,
+                             const at::Tensor& bytestreams,
+                             const at::Tensor& lengths_prefsum,
+                             at::Tensor& output) {
+  if (!cdf.device().is_xpu() || !bytestreams.device().is_xpu() ||
+      !lengths_prefsum.device().is_xpu() || !output.device().is_xpu()) {
+    throw std::runtime_error("decode_fast_prefsum_xpu: tensors must be on XPU");
+  }
+
+  TORCH_CHECK(cdf.scalar_type() == at::kShort,
+              "decode_fast_prefsum_xpu: cdf must be int16");
+  TORCH_CHECK(bytestreams.scalar_type() == at::kByte,
+              "decode_fast_prefsum_xpu: bytestreams must be uint8");
+  TORCH_CHECK(lengths_prefsum.scalar_type() == at::kLong,
+              "decode_fast_prefsum_xpu: lengths_prefsum must be int64");
+  TORCH_CHECK(
+      output.scalar_type() == at::kByte || output.scalar_type() == at::kChar,
+      "decode_fast_prefsum_xpu: output must be uint8 or int8");
+
+  TORCH_CHECK(
+      cdf.dim() == 3,
+      "decode_fast_prefsum_xpu: cdf must be 3-D [nlayers, nchannels, lp]");
+  TORCH_CHECK(lengths_prefsum.dim() == 2,
+              "decode_fast_prefsum_xpu: lengths_prefsum must be 2-D "
+              "[nlayers, nchannels]");
+  TORCH_CHECK(output.dim() == 3,
+              "decode_fast_prefsum_xpu: output must be 3-D "
+              "[nlayers, ntokens, nchannels]");
+
+  const auto cdf_shape = cdf.sizes();
+  const auto out_shape = output.sizes();
+  const int nlayers = static_cast<int>(cdf_shape[0]);
+  const int nchannels = static_cast<int>(cdf_shape[1]);
+  const int lp = static_cast<int>(cdf_shape[2]);
+  const int ntokens = static_cast<int>(out_shape[1]);
+
+  TORCH_CHECK(lp >= 2,
+              "decode_fast_prefsum_xpu: cdf last dim (lp) must be >= 2");
+
+  if (ntokens > MAX_TOKENS_PER_THREAD) {
+    throw std::runtime_error(
+        "decode_fast_prefsum_xpu: ntokens > MAX_TOKENS_PER_THREAD");
+  }
+  if (lp > MAX_LP) {
+    throw std::runtime_error("decode_fast_prefsum_xpu: lp > MAX_LP");
+  }
+
+  const int block_size = decoder_get_block_size(nchannels);
+  if (nchannels % block_size != 0) {
+    throw std::runtime_error(
+        "decode_fast_prefsum_xpu: nchannels must be divisible by block size");
+  }
+
+  auto cdf_c = cdf.is_contiguous() ? cdf : cdf.contiguous();
+  auto bs_c =
+      bytestreams.is_contiguous() ? bytestreams : bytestreams.contiguous();
+  auto pref_c = lengths_prefsum.is_contiguous() ? lengths_prefsum
+                                                : lengths_prefsum.contiguous();
+
+  const c10::DeviceGuard guard(cdf.device());
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(cdf.device().index()).queue();
+
+  const int16_t* cdf_ptr = cdf_c.data_ptr<int16_t>();
+  const uint8_t* bs_ptr = reinterpret_cast<const uint8_t*>(bs_c.data_ptr());
+  const int64_t* pref_ptr = pref_c.data_ptr<int64_t>();
+  uint8_t* out_ptr = reinterpret_cast<uint8_t*>(output.data_ptr());
+
+  DISPATCH_DECODE_BLOCKSIZE(launch_decode_prefsum, block_size, queue, cdf_ptr,
+                            bs_ptr, pref_ptr, out_ptr, nlayers, nchannels,
+                            ntokens, lp);
+}
diff --git a/csrc/sycl/ac_enc_sycl.cpp b/csrc/sycl/ac_enc_sycl.cpp
new file mode 100644
index 0000000..fd39227
--- /dev/null
+++ b/csrc/sycl/ac_enc_sycl.cpp
@@ -0,0 +1,379 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// SYCL/XPU arithmetic encoder for CacheGen.
+//
+// Algorithm
+// ---------
+//   Each (layer, channel) pair runs an independent arithmetic-coder state
+//   machine over `ntokens` 8-bit symbols and writes a per-channel byte
+//   stream into `output_buffer` along with the stream length into
+//   `output_lengths`.
+//
+// Intel XPU mapping
+// -----------------
+//   - 2-D nd_range:
+//       group axis 0 = layer
+//       group axis 1 = channel block (BLOCK_SIZE work-items per WG)
+//   - Each work-item owns ONE (layer, channel).  The state machine is
+//     intrinsically sequential, so we don't parallelise across tokens.
+//   - SLM:
+//       cdf_shared      [MAX_LP * BLOCK_SIZE] uint16  -- column-major
+//                                                       (lid * BLOCK_SIZE + tx)
+//       output_shared   [BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD] u8
+//     Column-major CDF layout lets a sub-group of 16 lanes read 16
+//     *contiguous* uint16s when looking up cdf[s], giving fully coalesced
+//     SLM access without bank conflicts (Xe SLM banks are 4-byte wide, so
+//     two consecutive lanes pack into the same bank line).
+//   - Sub-group size locked to 16 (Intel native SIMD).
+//
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#include <sycl/sycl.hpp>
+#pragma GCC diagnostic pop
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <c10/core/DeviceGuard.h>
+#include <c10/xpu/XPUStream.h>
+
+#include "cachegen_kernels_sycl.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <stdexcept>
+
+namespace {
+
+// Encoder caps lp at 48 to keep cdf_shared SLM at 48*BLOCK_SIZE*2B = 12KB
+// for BLOCK_SIZE=128.  Combined with output_shared (32KB) this fits one WG
+// per Xe sub-slice; bumping to 64 pushes total SLM past the occupancy
+// sweet spot and measurably slows the kernel.
+constexpr int MAX_LP = 48;
+constexpr int OUTPUT_BUFFER_LENGTH_PER_THREAD = 256;
+constexpr int MAX_TOKENS_PER_THREAD = 256;
+constexpr int PRECISION = 16;
+constexpr int INTEL_SUB_GROUP_SIZE = 16;
+
+// ----- bit-stream helpers (functor-style; no recursion, no allocation) ---
+
+template <typename SLMRef>
+inline void spill_reg_to_shared(uint32_t& output_reg, int& output_reg_len,
+                                SLMRef output_shared,
+                                int& output_shared_offset) {
+  // output_reg holds 32 filled bits; write them out big-endian.
+  // Byte-by-byte because output_shared_offset is not guaranteed to be
+  // 4-byte aligned.
+  output_shared[output_shared_offset] = static_cast<uint8_t>(output_reg >> 24);
+  output_shared[output_shared_offset + 1] =
+      static_cast<uint8_t>((output_reg >> 16) & 0xFFu);
+  output_shared[output_shared_offset + 2] =
+      static_cast<uint8_t>((output_reg >> 8) & 0xFFu);
+  output_shared[output_shared_offset + 3] =
+      static_cast<uint8_t>(output_reg & 0xFFu);
+  output_shared_offset += 4;
+  output_reg = 0;
+  output_reg_len = 0;
+}
+
+template <typename SLMRef>
+inline void spill_partial_reg_to_shared(uint32_t output_reg,
+                                        int& output_reg_len,
+                                        SLMRef output_shared,
+                                        int& output_shared_offset) {
+  output_reg <<= 32 - output_reg_len;
+  while (output_reg_len > 0) {
+    output_reg_len -= 8;
+    output_shared[output_shared_offset] =
+        static_cast<uint8_t>(output_reg >> 24);
+    output_shared_offset++;
+    output_reg <<= 8;
+  }
+}
+
+template <typename SLMRef>
+inline void add_bits_to_output(uint32_t bit, int num, uint32_t& output_reg,
+                               int& output_reg_len, SLMRef output_shared,
+                               int& output_shared_offset) {
+  do {
+    const int remaining = sycl::min<int>(num, 32 - output_reg_len);
+    output_reg <<= remaining;
+    output_reg |= (bit << remaining) - bit;
+    num -= remaining;
+    output_reg_len += remaining;
+    if (output_reg_len == 32) {
+      spill_reg_to_shared(output_reg, output_reg_len, output_shared,
+                          output_shared_offset);
+    }
+  } while (num > 0);
+}
+
+template <typename SLMRef>
+inline void append_bit_and_pending(uint32_t bit, uint64_t& pending_bits,
+                                   uint32_t& output_reg, int& output_reg_len,
+                                   SLMRef output_shared,
+                                   int& output_shared_offset) {
+  add_bits_to_output(bit, 1, output_reg, output_reg_len, output_shared,
+                     output_shared_offset);
+  add_bits_to_output(1 - bit, static_cast<int>(pending_bits), output_reg,
+                     output_reg_len, output_shared, output_shared_offset);
+  pending_bits = 0;
+}
+
+// -------------------------------------------------------------------------
+
+template <int BLOCK_SIZE>
+void launch_encode(sycl::queue& queue, const int16_t* cdf,
+                   const uint8_t* input_sym, uint8_t* output_buffer,
+                   int32_t* output_lengths, int nlayers, int nchannels,
+                   int ntokens, int lp) {
+  const int channel_blocks = nchannels / BLOCK_SIZE;
+  const int output_buffer_length_per_thread = OUTPUT_BUFFER_LENGTH_PER_THREAD;
+
+  sycl::range<2> global_range(static_cast<size_t>(nlayers),
+                              static_cast<size_t>(channel_blocks) * BLOCK_SIZE);
+  sycl::range<2> local_range(1, BLOCK_SIZE);
+
+  queue.submit([&](sycl::handler& cgh) {
+    sycl::local_accessor<uint16_t, 1> cdf_shared(
+        sycl::range<1>(MAX_LP * BLOCK_SIZE), cgh);
+    sycl::local_accessor<uint8_t, 1> output_shared(
+        sycl::range<1>(BLOCK_SIZE * OUTPUT_BUFFER_LENGTH_PER_THREAD), cgh);
+    // Per-channel byte-count scratch (used after the encode loop to drive
+    // the coalesced write-out).
+    sycl::local_accessor<int32_t, 1> lengths_shared(sycl::range<1>(BLOCK_SIZE),
+                                                    cgh);
+
+    cgh.parallel_for(
+        sycl::nd_range<2>(global_range, local_range),
+        [=](sycl::nd_item<2> item) [[sycl::reqd_sub_group_size(
+            INTEL_SUB_GROUP_SIZE)]] {
+          const int layer_id = static_cast<int>(item.get_group(0));
+          const int block_y = static_cast<int>(item.get_group(1));
+          const int tx = static_cast<int>(item.get_local_id(1));
+          const int channel_id = block_y * BLOCK_SIZE + tx;
+
+          // Load CDF[layer_id, block_y*BLOCK_SIZE : +BLOCK_SIZE, :]
+          const int cdf_size = BLOCK_SIZE * lp;
+          for (int i = tx; i < cdf_size; i += BLOCK_SIZE) {
+            const int cid = i / lp;
+            const int lid = i % lp;
+            const int shared_offset = lid * BLOCK_SIZE + cid;
+            const int16_t v = cdf[(static_cast<int64_t>(layer_id) * nchannels +
+                                   block_y * BLOCK_SIZE + cid) *
+                                      lp +
+                                  lid];
+            cdf_shared[shared_offset] = static_cast<uint16_t>(v);
+          }
+
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Per-(layer, channel) AC state machine.
+          uint32_t low = 0u;
+          uint32_t high = 0xFFFFFFFFu;
+          uint64_t pending_bits = 0;
+          const int max_symbol = lp - 2;
+
+          uint32_t output_reg = 0;
+          int output_reg_len = 0;
+          int output_shared_offset = tx * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+
+          auto out_acc = output_shared;  // alias
+
+          for (int i = 0; i < ntokens; ++i) {
+            const uint8_t sym =
+                input_sym[(static_cast<int64_t>(layer_id) * ntokens + i) *
+                              nchannels +
+                          channel_id];
+            const uint64_t span =
+                static_cast<uint64_t>(high) - static_cast<uint64_t>(low) + 1;
+            const uint32_t c_low = cdf_shared[sym * BLOCK_SIZE + tx];
+            const uint32_t c_high =
+                sym == max_symbol ? 0x10000u
+                                  : cdf_shared[(sym + 1) * BLOCK_SIZE + tx];
+
+            high =
+                (low - 1) + static_cast<uint32_t>((span * c_high) >> PRECISION);
+            low = low + static_cast<uint32_t>((span * c_low) >> PRECISION);
+
+            while (true) {
+              if (high < 0x80000000u) {
+                append_bit_and_pending(0, pending_bits, output_reg,
+                                       output_reg_len, out_acc,
+                                       output_shared_offset);
+                low <<= 1;
+                high <<= 1;
+                high |= 1;
+              } else if (low >= 0x80000000u) {
+                append_bit_and_pending(1, pending_bits, output_reg,
+                                       output_reg_len, out_acc,
+                                       output_shared_offset);
+                low <<= 1;
+                high <<= 1;
+                high |= 1;
+              } else if (low >= 0x40000000u && high < 0xC0000000u) {
+                pending_bits++;
+                low <<= 1;
+                low &= 0x7FFFFFFFu;
+                high <<= 1;
+                high |= 0x80000001u;
+              } else {
+                break;
+              }
+            }
+          }
+
+          pending_bits += 1;
+          if (low < 0x40000000u) {
+            append_bit_and_pending(0, pending_bits, output_reg, output_reg_len,
+                                   out_acc, output_shared_offset);
+          } else {
+            append_bit_and_pending(1, pending_bits, output_reg, output_reg_len,
+                                   out_acc, output_shared_offset);
+          }
+          spill_partial_reg_to_shared(output_reg, output_reg_len, out_acc,
+                                      output_shared_offset);
+
+          const int my_len =
+              output_shared_offset - tx * OUTPUT_BUFFER_LENGTH_PER_THREAD;
+          output_lengths[layer_id * nchannels + channel_id] = my_len;
+          lengths_shared[tx] = my_len;
+
+          item.barrier(sycl::access::fence_space::local_space);
+
+          // Coalesced write-out by channel.
+          for (int i = 0; i < BLOCK_SIZE; ++i) {
+            const int peer_len = lengths_shared[i];
+            const int current_channel = block_y * BLOCK_SIZE + i;
+            for (int j = tx; j < peer_len; j += BLOCK_SIZE) {
+              const int64_t global_offset =
+                  (static_cast<int64_t>(layer_id) * nchannels +
+                   current_channel) *
+                      output_buffer_length_per_thread +
+                  j;
+              const int local_offset = i * OUTPUT_BUFFER_LENGTH_PER_THREAD + j;
+              output_buffer[global_offset] = output_shared[local_offset];
+            }
+          }
+        });
+  });
+}
+
+int encoder_get_block_size(int nchannels) {
+  int factor = (nchannels ^ (nchannels - 1)) + 1;
+  factor >>= 1;
+  if (factor > 128) factor = 128;
+  return factor;
+}
+
+}  // namespace
+
+void encode_fast_new_xpu(const at::Tensor& cdf, const at::Tensor& input_sym,
+                         at::Tensor& output_buffer,
+                         at::Tensor& output_lengths) {
+  if (!cdf.device().is_xpu() || !input_sym.device().is_xpu() ||
+      !output_buffer.device().is_xpu() || !output_lengths.device().is_xpu()) {
+    throw std::runtime_error("encode_fast_new_xpu: all tensors must be on XPU");
+  }
+
+  TORCH_CHECK(cdf.scalar_type() == at::kShort,
+              "encode_fast_new_xpu: cdf must be int16");
+  TORCH_CHECK(input_sym.scalar_type() == at::kByte ||
+                  input_sym.scalar_type() == at::kChar,
+              "encode_fast_new_xpu: input_sym must be uint8 or int8");
+  TORCH_CHECK(output_buffer.scalar_type() == at::kByte,
+              "encode_fast_new_xpu: output_buffer must be uint8");
+  TORCH_CHECK(output_lengths.scalar_type() == at::kInt,
+              "encode_fast_new_xpu: output_lengths must be int32");
+
+  TORCH_CHECK(cdf.dim() == 3,
+              "encode_fast_new_xpu: cdf must be 3-D [nlayers, nchannels, lp]");
+  TORCH_CHECK(input_sym.dim() == 3,
+              "encode_fast_new_xpu: input_sym must be 3-D [nlayers, ntokens, "
+              "nchannels]");
+  TORCH_CHECK(output_buffer.dim() == 3,
+              "encode_fast_new_xpu: output_buffer must be 3-D");
+  TORCH_CHECK(output_lengths.dim() == 2,
+              "encode_fast_new_xpu: output_lengths must be 2-D");
+
+  const auto cdf_shape = cdf.sizes();
+  const auto input_shape = input_sym.sizes();
+  const auto output_shape = output_buffer.sizes();
+
+  const int nlayers = static_cast<int>(cdf_shape[0]);
+  const int nchannels = static_cast<int>(cdf_shape[1]);
+  const int lp = static_cast<int>(cdf_shape[2]);
+  const int ntokens = static_cast<int>(input_shape[1]);
+
+  TORCH_CHECK(lp >= 2, "encode_fast_new_xpu: cdf last dim (lp) must be >= 2");
+
+  if (ntokens > MAX_TOKENS_PER_THREAD) {
+    throw std::runtime_error(
+        "encode_fast_new_xpu: ntokens must be <= MAX_TOKENS_PER_THREAD");
+  }
+  if (lp > MAX_LP) {
+    throw std::runtime_error(
+        "encode_fast_new_xpu: cdf last dim must be <= MAX_LP");
+  }
+  if (output_shape[2] != OUTPUT_BUFFER_LENGTH_PER_THREAD) {
+    throw std::runtime_error(
+        "encode_fast_new_xpu: output buffer last dim must equal "
+        "OUTPUT_BUFFER_LENGTH_PER_THREAD (256)");
+  }
+
+  const int block_size = encoder_get_block_size(nchannels);
+  if (nchannels % block_size != 0) {
+    throw std::runtime_error(
+        "encode_fast_new_xpu: nchannels must be divisible by block size");
+  }
+
+  auto cdf_c = cdf.is_contiguous() ? cdf : cdf.contiguous();
+  auto sym_c = input_sym.is_contiguous() ? input_sym : input_sym.contiguous();
+
+  const c10::DeviceGuard guard(cdf.device());
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(cdf.device().index()).queue();
+
+  const int16_t* cdf_ptr = cdf_c.data_ptr<int16_t>();
+  // Accept both Byte (uint8) and Char (int8) input symbols; the AC
+  // state machine reads the raw bit pattern either way.
+  const uint8_t* sym_ptr = reinterpret_cast<const uint8_t*>(sym_c.data_ptr());
+  uint8_t* out_buf_ptr = reinterpret_cast<uint8_t*>(output_buffer.data_ptr());
+  int32_t* out_len_ptr = output_lengths.data_ptr<int32_t>();
+
+  switch (block_size) {
+    case 1:
+      launch_encode<1>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                       nlayers, nchannels, ntokens, lp);
+      break;
+    case 2:
+      launch_encode<2>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                       nlayers, nchannels, ntokens, lp);
+      break;
+    case 4:
+      launch_encode<4>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                       nlayers, nchannels, ntokens, lp);
+      break;
+    case 8:
+      launch_encode<8>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                       nlayers, nchannels, ntokens, lp);
+      break;
+    case 16:
+      launch_encode<16>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                        nlayers, nchannels, ntokens, lp);
+      break;
+    case 32:
+      launch_encode<32>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                        nlayers, nchannels, ntokens, lp);
+      break;
+    case 64:
+      launch_encode<64>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                        nlayers, nchannels, ntokens, lp);
+      break;
+    case 128:
+      launch_encode<128>(queue, cdf_ptr, sym_ptr, out_buf_ptr, out_len_ptr,
+                         nlayers, nchannels, ntokens, lp);
+      break;
+    default:
+      throw std::runtime_error("encode_fast_new_xpu: unsupported block size");
+  }
+}
diff --git a/csrc/sycl/cachegen_kernels_sycl.h b/csrc/sycl/cachegen_kernels_sycl.h
new file mode 100644
index 0000000..8bd7aa6
--- /dev/null
+++ b/csrc/sycl/cachegen_kernels_sycl.h
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Declarations of SYCL/XPU implementations of CacheGen + RoPE kernels.
+// Implementations live in csrc/sycl/*.cpp and are exposed to Python via
+// lmcache.xpu_ops.
+//
+#pragma once
+
+#include <torch/all.h>
+
+// CacheGen ---------------------------------------------------------------
+//
+// Calculate per-(layer, channel) CDF from an int8/uint8 input tensor.
+// Input:  [nlayers, ntokens, nchannels] (uint8)
+// Output: [nlayers, nchannels, max_bins + 1] (int16)
+at::Tensor calculate_cdf_xpu(const at::Tensor& input, int64_t max_bins);
+
+// Arithmetic encoder (forward): produces a byte buffer + per-channel
+// length tensor.
+void encode_fast_new_xpu(const at::Tensor& cdf, const at::Tensor& input_sym,
+                         at::Tensor& output_buffer, at::Tensor& output_lengths);
+
+// Arithmetic decoder (per-channel buffer): inverse of encode_fast_new.
+void decode_fast_new_xpu(const at::Tensor& cdf, const at::Tensor& bytestreams,
+                         const at::Tensor& lengths, at::Tensor& output);
+
+// Arithmetic decoder (1-D bytestream with prefix-sum offsets):
+// inverse of encode_fast_new packed via prefix sums.
+void decode_fast_prefsum_xpu(const at::Tensor& cdf,
+                             const at::Tensor& bytestreams,
+                             const at::Tensor& lengths_prefsum,
+                             at::Tensor& output);
+
+// Position encoding -------------------------------------------------------
+//
+// Fused undo-then-apply rotary embedding on key tensor (in-place).
+void rotary_embedding_k_fused_xpu(const torch::Tensor& old_positions,
+                                  const torch::Tensor& new_positions,
+                                  torch::Tensor& key, int64_t head_size,
+                                  const torch::Tensor& cos_sin_cache,
+                                  bool is_neox);
diff --git a/csrc/sycl/cal_cdf_sycl.cpp b/csrc/sycl/cal_cdf_sycl.cpp
new file mode 100644
index 0000000..2b689cc
--- /dev/null
+++ b/csrc/sycl/cal_cdf_sycl.cpp
@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// SYCL/XPU implementation of calculate_cdf, hand-tuned for the Intel Xe
+// architecture (PVC / DG2 / BMG / Arc).
+//
+// Algorithm
+// ---------
+//   For each (layer_id, channel_id) we build a histogram of the uint8
+//   input values along the `ntokens` axis, prefix-sum it into a CDF,
+//   normalise to a uint16 range, and add the bin index so values are
+//   strictly monotonic (see normalize_cdf_value()).
+//
+// Intel XPU mapping
+// -----------------
+//   - 2-D nd_range: dim 0 = layer, dim 1 = channel (BLOCK_SIZE per WG).
+//   - Each work-item owns one channel (no atomic contention).
+//   - Histogram lives in Shared Local Memory (SLM) as a 2-D tile of
+//     [MAX_BINS_SUPPORTED+1][BLOCK_SIZE] uint16s -- one column per
+//     channel.  All traffic stays local; no cross work-item sync in the
+//     inner increment loop.
+//   - sub_group_size locked to 16 (native SIMD on Intel discrete GPUs).
+//   - BLOCK_SIZE is a template parameter so IGC can fully unroll and
+//     statically size the SLM allocation.
+//
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#include <sycl/sycl.hpp>
+#pragma GCC diagnostic pop
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <c10/core/DeviceGuard.h>
+#include <c10/xpu/XPUStream.h>
+
+#include "cachegen_kernels_sycl.h"
+
+#include <cstdint>
+#include <stdexcept>
+
+namespace {
+
+constexpr int MAX_BINS_SUPPORTED = 64;
+constexpr int INTEL_SUB_GROUP_SIZE = 16;
+
+// Linear remap into [0, 0xFFFF - max_bins].
+inline uint16_t normalize_cdf_value(uint16_t cdf_value, uint16_t total_count,
+                                    int max_bins) {
+  const uint32_t MAX_UINT16_VALUE = 0xFFFFu - static_cast<uint32_t>(max_bins);
+  return static_cast<uint16_t>(MAX_UINT16_VALUE *
+                               static_cast<uint32_t>(cdf_value) /
+                               static_cast<uint32_t>(total_count));
+}
+
+template <int BLOCK_SIZE>
+void launch_calculate_cdf(sycl::queue& queue, const uint8_t* input,
+                          int16_t* output, int nlayers, int ntokens,
+                          int nchannels, int max_bins) {
+  const int channel_blocks = (nchannels + BLOCK_SIZE - 1) / BLOCK_SIZE;
+  const int lp = max_bins + 1;
+
+  sycl::range<2> global_range(static_cast<size_t>(nlayers),
+                              static_cast<size_t>(channel_blocks) * BLOCK_SIZE);
+  sycl::range<2> local_range(1, BLOCK_SIZE);
+
+  queue.submit([&](sycl::handler& cgh) {
+    // SLM histogram: [MAX_BINS_SUPPORTED + 1][BLOCK_SIZE] uint16.
+    sycl::local_accessor<uint16_t, 2> hist(
+        sycl::range<2>(MAX_BINS_SUPPORTED + 1, BLOCK_SIZE), cgh);
+
+    cgh.parallel_for(
+        sycl::nd_range<2>(global_range, local_range),
+        [=](sycl::nd_item<2> item)
+            [[sycl::reqd_sub_group_size(INTEL_SUB_GROUP_SIZE)]] {
+              const int layer_id = static_cast<int>(item.get_group(0));
+              const int tx = static_cast<int>(item.get_local_id(1));
+              const int channel_block = static_cast<int>(item.get_group(1));
+              const int start_channel = channel_block * BLOCK_SIZE;
+              const int channel_id = start_channel + tx;
+              const bool in_range = (channel_id < nchannels);
+
+              // Zero this column of the SLM histogram.  No barrier
+              // needed: every work-item only ever touches column `tx`,
+              // so there is zero cross-thread sharing in SLM.  Profiler
+              // (unitrace --stall-sampling) confirmed that the previous
+              // barriers caused ~67% SyncStall — removing them was the
+              // single largest win on this kernel.
+              for (int i = 0; i <= max_bins; ++i) {
+                hist[i][tx] = 0;
+              }
+
+              if (in_range) {
+                // Histogram pass: counts at hist[v+1][tx].  hist[0][tx] stays
+                // 0.
+                for (int i = 0; i < ntokens; ++i) {
+                  const uint8_t v =
+                      input[(static_cast<int64_t>(layer_id) * ntokens + i) *
+                                nchannels +
+                            channel_id];
+                  hist[v + 1][tx] += 1;
+                }
+
+                // Inclusive prefix sum so hist[i] = sum of counts of
+                // bins [0..i-1].
+                uint16_t total = 0;
+                for (int i = 0; i < max_bins; ++i) {
+                  uint16_t value = hist[i + 1][tx];
+                  hist[i + 1][tx] = total + value;
+                  total += value;
+                }
+
+                // Normalise + add bin index for strict monotonicity.
+                if (total > 0) {
+                  for (int i = 0; i <= max_bins; ++i) {
+                    hist[i][tx] =
+                        normalize_cdf_value(hist[i][tx], total, max_bins) +
+                        static_cast<uint16_t>(i);
+                  }
+                } else {
+                  for (int i = 0; i <= max_bins; ++i) {
+                    hist[i][tx] = static_cast<uint16_t>(i);
+                  }
+                }
+              }
+
+              if (in_range) {
+                const int64_t base =
+                    (static_cast<int64_t>(layer_id) * nchannels + channel_id) *
+                    lp;
+                for (int i = 0; i <= max_bins; ++i) {
+                  output[base + i] = static_cast<int16_t>(hist[i][tx]);
+                }
+              }
+            });
+  });
+}
+
+// Largest power-of-two divisor of nchannels, capped at 128.
+int get_block_size_xpu(int nchannels) {
+  static const int kCandidates[] = {128, 64, 32, 16, 8, 4, 2, 1};
+  for (int bs : kCandidates) {
+    if (nchannels % bs == 0) return bs;
+  }
+  return 1;
+}
+
+}  // namespace
+
+at::Tensor calculate_cdf_xpu(const at::Tensor& input, int64_t max_bins) {
+  if (!input.device().is_xpu()) {
+    throw std::runtime_error("calculate_cdf_xpu: input must be an XPU tensor");
+  }
+  if (max_bins >= MAX_BINS_SUPPORTED) {
+    throw std::runtime_error("calculate_cdf_xpu: max_bins must be < 64");
+  }
+  if (input.dim() != 3) {
+    throw std::runtime_error(
+        "calculate_cdf_xpu: input must be 3-D [nlayers, ntokens, nchannels]");
+  }
+
+  const auto sizes = input.sizes();
+  const int nlayers = static_cast<int>(sizes[0]);
+  const int ntokens = static_cast<int>(sizes[1]);
+  const int nchannels = static_cast<int>(sizes[2]);
+
+  auto contiguous = input.is_contiguous() ? input : input.contiguous();
+  auto output = torch::zeros({nlayers, nchannels, max_bins + 1},
+                             input.options().dtype(at::kShort));
+
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(input.device().index()).queue();
+  // Accept both Byte (uint8) and Char (int8) inputs: values are bin
+  // indices in [0, max_bins), so byte-pattern is identical either way.
+  const uint8_t* in_ptr =
+      reinterpret_cast<const uint8_t*>(contiguous.data_ptr());
+  int16_t* out_ptr = output.data_ptr<int16_t>();
+
+  const int block_size = get_block_size_xpu(nchannels);
+  switch (block_size) {
+    case 1:
+      launch_calculate_cdf<1>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                              nchannels, static_cast<int>(max_bins));
+      break;
+    case 2:
+      launch_calculate_cdf<2>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                              nchannels, static_cast<int>(max_bins));
+      break;
+    case 4:
+      launch_calculate_cdf<4>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                              nchannels, static_cast<int>(max_bins));
+      break;
+    case 8:
+      launch_calculate_cdf<8>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                              nchannels, static_cast<int>(max_bins));
+      break;
+    case 16:
+      launch_calculate_cdf<16>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                               nchannels, static_cast<int>(max_bins));
+      break;
+    case 32:
+      launch_calculate_cdf<32>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                               nchannels, static_cast<int>(max_bins));
+      break;
+    case 64:
+      launch_calculate_cdf<64>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                               nchannels, static_cast<int>(max_bins));
+      break;
+    case 128:
+      launch_calculate_cdf<128>(queue, in_ptr, out_ptr, nlayers, ntokens,
+                                nchannels, static_cast<int>(max_bins));
+      break;
+    default:
+      throw std::runtime_error("calculate_cdf_xpu: unsupported block size");
+  }
+
+  return output;
+}
diff --git a/csrc/sycl/mem_kernels_sycl.cpp b/csrc/sycl/mem_kernels_sycl.cpp
new file mode 100644
index 0000000..8cdd434
--- /dev/null
+++ b/csrc/sycl/mem_kernels_sycl.cpp
@@ -0,0 +1,1023 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// SYCL implementation of LMCache memory kernels for Intel XPU
+// (PVC / Arc / Battlemage).
+//
+// Performance-critical design choices:
+//
+// 1. Work-group size 256 -- keeps Intel EU ALUs fed and hides
+//    global-memory latency.
+// 2. [[sycl::reqd_sub_group_size(16)]] -- native SIMD width on all
+//    Intel discrete GPUs; prevents IGC from falling back to width 32
+//    on PVC (which would halve occupancy).
+// 3. Compile-time template parameters (DIRECTION, USE_MLA) eliminate
+//    run-time branches in the innermost loop.
+// 4. Hoisted loop-invariant base offsets -- integer division/modulo
+//    (flash_infer block indexing) is computed once per token+layer
+//    rather than per inner-loop iteration.
+// 5. 64-bit (int64_t) bulk transfers pack two fp32 / four fp16 /
+//    eight int8 values per move.
+// 6. Fused K+V work-groups (non-MLA multi-layer kernels) -- one
+//    work-group handles both K and V, halving dispatch count and
+//    avoiding redundant slot/pointer/division work.
+
+// sycl/accessor.hpp references the deprecated 'host_buffer' internally
+// even when user code only uses USM pointers; suppress the noise.
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#include <sycl/sycl.hpp>
+#pragma GCC diagnostic pop
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <c10/core/DeviceGuard.h>
+#include <c10/xpu/XPUStream.h>
+
+#include "mem_kernels_sycl.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+
+// ---------------------------------------------------------------------------
+// Tuning constants
+// ---------------------------------------------------------------------------
+// Native SIMD width on PVC, DG2, and BMG.
+constexpr int INTEL_SUB_GROUP_SIZE = 16;
+
+// Max work-group size; must be a multiple of INTEL_SUB_GROUP_SIZE.
+constexpr int MAX_WG_SIZE = 256;
+
+// ---------------------------------------------------------------------------
+// Round up so the work-group divides evenly into sub-groups.
+// ---------------------------------------------------------------------------
+inline int round_up_to_sg(int n) {
+  return ((n + INTEL_SUB_GROUP_SIZE - 1) / INTEL_SUB_GROUP_SIZE) *
+         INTEL_SUB_GROUP_SIZE;
+}
+
+// ---------------------------------------------------------------------------
+// Namespace lmc -- device-side helper functions
+// ---------------------------------------------------------------------------
+namespace lmc {
+
+template <EngineKVFormat format>
+inline int64_t page_buffer_offset(const int k_or_v, const int token_idx,
+                                  const int scalar_offset,
+                                  const int scalars_per_token,
+                                  const int page_buffer_size,
+                                  const int block_size) {
+  // vLLM cross layer
+  if constexpr (format == EngineKVFormat::NB_NL_TWO_BS_NH_HS) {
+    return k_or_v * page_buffer_size * scalars_per_token +
+           token_idx * scalars_per_token + scalar_offset;
+  }
+  // vLLM flash attention
+  else if constexpr (format == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS) {
+    return k_or_v * page_buffer_size * scalars_per_token +
+           token_idx * scalars_per_token + scalar_offset;
+  }
+  // vLLM flash infer
+  else if constexpr (format == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS) {
+    const int block_idx = token_idx / block_size;
+    const int block_offset = token_idx % block_size;
+    return block_idx * 2 * block_size * scalars_per_token +
+           k_or_v * block_size * scalars_per_token +
+           block_offset * scalars_per_token + scalar_offset;
+  }
+  // MLA formats: vLLM (NL_X_NB_BS_HS) and SGLang (NL_X_NBBS_ONE_HS)
+  else if constexpr (format == EngineKVFormat::NL_X_NB_BS_HS ||
+                     format == EngineKVFormat::NL_X_NBBS_ONE_HS) {
+    return token_idx * scalars_per_token + scalar_offset;
+  }
+}
+
+/// Loop-invariant base offset for the paged buffer.
+/// page_buffer_offset(k_or_v, slot, i, ...) == base_offset(...) + i.
+/// Hoisting this out of the inner loop avoids re-computing the
+/// integer division / modulo (flash_infer) on every iteration.
+template <EngineKVFormat format>
+inline int64_t page_buffer_base_offset(const int k_or_v, const int token_idx,
+                                       const int scalars_per_token,
+                                       const int page_buffer_size,
+                                       const int block_size) {
+  if constexpr (format == EngineKVFormat::NB_NL_TWO_BS_NH_HS) {
+    return k_or_v * page_buffer_size * scalars_per_token +
+           token_idx * scalars_per_token;
+  } else if constexpr (format == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS) {
+    return k_or_v * page_buffer_size * scalars_per_token +
+           token_idx * scalars_per_token;
+  } else if constexpr (format == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS) {
+    const int block_idx = token_idx / block_size;
+    const int block_offset = token_idx % block_size;
+    return block_idx * 2 * block_size * scalars_per_token +
+           k_or_v * block_size * scalars_per_token +
+           block_offset * scalars_per_token;
+  } else if constexpr (format == EngineKVFormat::NL_X_NB_BS_HS ||
+                       format == EngineKVFormat::NL_X_NBBS_ONE_HS) {
+    return token_idx * scalars_per_token;
+  }
+}
+
+inline int64_t page_buffer_offset_unilateral(const int token_idx,
+                                             const int scalar_offset,
+                                             const int scalars_per_token) {
+  return token_idx * scalars_per_token + scalar_offset;
+}
+
+inline int64_t key_value_offset(const int k_or_v, const int layer_idx,
+                                const int token_idx, const int scalar_offset,
+                                const int scalars_per_token,
+                                const int num_tokens, const int num_layers) {
+  return k_or_v * num_layers * num_tokens * scalars_per_token +
+         layer_idx * num_tokens * scalars_per_token +
+         token_idx * scalars_per_token + scalar_offset;
+}
+
+/// Loop-invariant base offset for the LMCache key_value buffer.
+/// key_value_offset(k_or_v, layer, token, i, ...) == base(...) + i.
+inline int64_t key_value_base_offset(const int k_or_v, const int layer_idx,
+                                     const int token_idx,
+                                     const int scalars_per_token,
+                                     const int num_tokens,
+                                     const int num_layers) {
+  return k_or_v * num_layers * num_tokens * scalars_per_token +
+         layer_idx * num_tokens * scalars_per_token +
+         token_idx * scalars_per_token;
+}
+
+}  // namespace lmc
+
+// ---------------------------------------------------------------------------
+// Pointer helper -- returns a kernel-accessible pointer of the given type.
+// XPU tensors expose their USM device pointer; CPU tensors must be backed
+// by USM host memory (e.g. sycl::malloc_host) to be device-accessible.
+// ---------------------------------------------------------------------------
+template <typename T, typename TENSOR_TYPE>
+T* get_kernel_ptr(TENSOR_TYPE& tensor) {
+  torch::Device device = tensor.device();
+  if (device.is_xpu()) {
+    return static_cast<T*>(tensor.data_ptr());
+  } else if (device.is_cpu()) {
+    // USM host pointers are device-accessible.
+    return static_cast<T*>(tensor.data_ptr());
+  } else {
+    TORCH_CHECK(false,
+                "Invalid device. Device must be xpu or cpu (USM pinned).");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Kernel-launch helpers -- multi-layer kernels
+// ---------------------------------------------------------------------------
+
+/**
+ * Submit the multi-layer KV transfer kernel for MLA formats
+ * (k_or_v_size == 1).
+ *
+ * nd_range layout: group(0)=k_or_v, group(1)=layer, group(2)=token;
+ * local_id(2)=tid, local_range(2)=num_threads.
+ *
+ * Optimizations:
+ *   - DIRECTION is a compile-time bool (no branch in hot loop)
+ *   - Loop-invariant base offsets (including flash_infer's integer
+ *     division) are computed once before the inner loop
+ *   - Work-group size rounded to a sub-group multiple for full SIMD
+ *     utilisation
+ */
+template <typename scalar_t, bool DIRECTION, EngineKVFormat format>
+void submit_multi_layer_kernel(sycl::queue& queue, scalar_t* key_value_ptr,
+                               scalar_t** page_buffer_ptrs,
+                               const int64_t* slot_mapping_ptr,
+                               int scalars_per_token, int num_tokens,
+                               int num_layers, int page_buffer_size,
+                               int block_size, int skip_prefix_n_tokens,
+                               int k_or_v_size, int wg_size) {
+  int num_transfer_tokens = num_tokens - skip_prefix_n_tokens;
+  if (num_transfer_tokens <= 0 || num_layers <= 0) return;
+
+  sycl::range<3> global_range(
+      static_cast<size_t>(k_or_v_size), static_cast<size_t>(num_layers),
+      static_cast<size_t>(num_transfer_tokens) * wg_size);
+  sycl::range<3> local_range(1, 1, static_cast<size_t>(wg_size));
+
+  queue.parallel_for(
+      sycl::nd_range<3>(global_range, local_range),
+      [=](sycl::nd_item<3> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int token_id = static_cast<int>(item.get_group(2));
+        const int layer_id = static_cast<int>(item.get_group(1));
+        const int k_or_v = static_cast<int>(item.get_group(0));
+        const int tid = static_cast<int>(item.get_local_id(2));
+        const int num_threads = static_cast<int>(item.get_local_range(2));
+
+        const int kv_token_id = token_id + skip_prefix_n_tokens;
+        const int64_t slot_idx = slot_mapping_ptr[kv_token_id];
+        scalar_t* paged_buffer_ptr = page_buffer_ptrs[layer_id];
+
+        if (slot_idx < 0) return;
+
+        // Hoist loop-invariant base offsets (flash_infer's integer
+        // division happens here, once, not per loop iteration).
+        const int64_t lmc_base = lmc::key_value_base_offset(
+            k_or_v, layer_id, kv_token_id, scalars_per_token, num_tokens,
+            num_layers);
+        const int64_t vllm_base = lmc::page_buffer_base_offset<format>(
+            k_or_v, slot_idx, scalars_per_token, page_buffer_size, block_size);
+
+        for (int i = tid; i < scalars_per_token; i += num_threads) {
+          if constexpr (DIRECTION) {
+            key_value_ptr[lmc_base + i] = paged_buffer_ptr[vllm_base + i];
+          } else {
+            paged_buffer_ptr[vllm_base + i] = key_value_ptr[lmc_base + i];
+          }
+        }
+      });
+}
+
+/**
+ * Submit a fused K+V multi-layer kernel for non-MLA formats.
+ *
+ * Processes both key (k_or_v=0) and value (k_or_v=1) within the same
+ * work-group, halving work-group count compared to dispatching K and
+ * V separately. Slot mapping, pointer-array lookup, and flash_infer's
+ * block-index division are each performed once and reused for both.
+ */
+template <typename scalar_t, bool DIRECTION, EngineKVFormat format>
+void submit_multi_layer_kernel_fused_kv(
+    sycl::queue& queue, scalar_t* key_value_ptr, scalar_t** page_buffer_ptrs,
+    const int64_t* slot_mapping_ptr, int scalars_per_token, int num_tokens,
+    int num_layers, int page_buffer_size, int block_size,
+    int skip_prefix_n_tokens, int wg_size) {
+  int num_transfer_tokens = num_tokens - skip_prefix_n_tokens;
+  if (num_transfer_tokens <= 0 || num_layers <= 0) return;
+
+  // Grid: (1, num_layers, num_transfer_tokens * wg_size);
+  // no k_or_v dimension — K and V share one work-group.
+  sycl::range<3> global_range(
+      1, static_cast<size_t>(num_layers),
+      static_cast<size_t>(num_transfer_tokens) * wg_size);
+  sycl::range<3> local_range(1, 1, static_cast<size_t>(wg_size));
+
+  queue.parallel_for(
+      sycl::nd_range<3>(global_range, local_range),
+      [=](sycl::nd_item<3> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int token_id = static_cast<int>(item.get_group(2));
+        const int layer_id = static_cast<int>(item.get_group(1));
+        const int tid = static_cast<int>(item.get_local_id(2));
+        const int num_threads = static_cast<int>(item.get_local_range(2));
+
+        const int kv_token_id = token_id + skip_prefix_n_tokens;
+        const int64_t slot_idx = slot_mapping_ptr[kv_token_id];
+        scalar_t* paged_buffer_ptr = page_buffer_ptrs[layer_id];
+
+        if (slot_idx < 0) return;
+
+        // Base offsets for K (k_or_v=0) and V (k_or_v=1); the
+        // flash_infer division/modulo runs once per token+layer.
+        const int64_t lmc_base_k = lmc::key_value_base_offset(
+            0, layer_id, kv_token_id, scalars_per_token, num_tokens,
+            num_layers);
+        const int64_t lmc_base_v = lmc::key_value_base_offset(
+            1, layer_id, kv_token_id, scalars_per_token, num_tokens,
+            num_layers);
+        const int64_t vllm_base_k = lmc::page_buffer_base_offset<format>(
+            0, slot_idx, scalars_per_token, page_buffer_size, block_size);
+        const int64_t vllm_base_v = lmc::page_buffer_base_offset<format>(
+            1, slot_idx, scalars_per_token, page_buffer_size, block_size);
+
+        for (int i = tid; i < scalars_per_token; i += num_threads) {
+          if constexpr (DIRECTION) {
+            // paged buffer → LMCache
+            key_value_ptr[lmc_base_k + i] = paged_buffer_ptr[vllm_base_k + i];
+            key_value_ptr[lmc_base_v + i] = paged_buffer_ptr[vllm_base_v + i];
+          } else {
+            // LMCache → paged buffer
+            paged_buffer_ptr[vllm_base_k + i] = key_value_ptr[lmc_base_k + i];
+            paged_buffer_ptr[vllm_base_v + i] = key_value_ptr[lmc_base_v + i];
+          }
+        }
+      });
+}
+
+/**
+ * Submit the multi-layer unilateral kernel (SGLang MHA).
+ *
+ * DIRECTION = true  → paged buffer → LMCache (D2H)
+ * DIRECTION = false → LMCache → paged buffer (H2D)
+ *
+ * Uses `if constexpr (DIRECTION)` so the compiler can
+ * dead-strip the unused branch entirely.
+ */
+template <typename scalar_t, bool DIRECTION>
+void submit_multi_layer_unilateral_kernel(
+    sycl::queue& queue, scalar_t* key_value_ptr, scalar_t** page_buffer_ptrs,
+    const int64_t* slot_mapping_ptr, int scalars_per_token, int num_tokens,
+    int num_layers, int page_buffer_size, int k_or_v_size, int kv_num_tokens,
+    int wg_size) {
+  if (kv_num_tokens <= 0 || num_layers <= 0) return;
+
+  sycl::range<3> global_range(static_cast<size_t>(k_or_v_size),
+                              static_cast<size_t>(num_layers),
+                              static_cast<size_t>(kv_num_tokens) * wg_size);
+  sycl::range<3> local_range(1, 1, static_cast<size_t>(wg_size));
+
+  queue.parallel_for(
+      sycl::nd_range<3>(global_range, local_range),
+      [=](sycl::nd_item<3> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int token_id = static_cast<int>(item.get_group(2));
+        const int layer_id = static_cast<int>(item.get_group(1));
+        const int k_or_v = static_cast<int>(item.get_group(0));
+        const int tid = static_cast<int>(item.get_local_id(2));
+        const int num_threads = static_cast<int>(item.get_local_range(2));
+
+        const int64_t slot_idx = slot_mapping_ptr[token_id];
+        scalar_t* key_ptr = page_buffer_ptrs[layer_id];
+        scalar_t* value_ptr = page_buffer_ptrs[layer_id + num_layers];
+
+        if (slot_idx < 0) return;
+
+        const int64_t lmc_base = lmc::key_value_base_offset(
+            k_or_v, layer_id, token_id, scalars_per_token, num_tokens,
+            num_layers);
+        const int64_t sgl_base = slot_idx * scalars_per_token;
+
+        for (int i = tid; i < scalars_per_token; i += num_threads) {
+          if (k_or_v == 0) {
+            if constexpr (DIRECTION)
+              key_value_ptr[lmc_base + i] = key_ptr[sgl_base + i];
+            else
+              key_ptr[sgl_base + i] = key_value_ptr[lmc_base + i];
+          } else {
+            if constexpr (DIRECTION)
+              key_value_ptr[lmc_base + i] = value_ptr[sgl_base + i];
+            else
+              value_ptr[sgl_base + i] = key_value_ptr[lmc_base + i];
+          }
+        }
+      });
+}
+
+// ---------------------------------------------------------------------------
+// Macros to dispatch multi-layer kernels with a specific EngineKVFormat.
+// MLA formats (k_or_v_size==1) use the per-component kernel.
+// Non-MLA formats (k_or_v_size==2) use the fused K+V kernel.
+// ---------------------------------------------------------------------------
+#define LAUNCH_KERNEL_WITH_FORMAT(T, DIRECTION, FORMAT)                     \
+  submit_multi_layer_kernel<T, DIRECTION, FORMAT>(                          \
+      queue, key_value_ptr, page_buffer_ptrs, slot_mapping_ptr, num_xwords, \
+      num_tokens, num_layers, page_buffer_size, block_size,                 \
+      skip_prefix_n_tokens, k_or_v_size, wg_size);
+
+#define LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(T, DIRECTION, FORMAT)            \
+  submit_multi_layer_kernel_fused_kv<T, DIRECTION, FORMAT>(                 \
+      queue, key_value_ptr, page_buffer_ptrs, slot_mapping_ptr, num_xwords, \
+      num_tokens, num_layers, page_buffer_size, block_size,                 \
+      skip_prefix_n_tokens, wg_size);
+
+// ---------------------------------------------------------------------------
+// multi_layer_kv_transfer -- templated implementation
+// ---------------------------------------------------------------------------
+template <typename T>
+void multi_layer_kv_transfer_templated(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format, const int block_size,
+    const int skip_prefix_n_tokens) {
+  T* key_value_ptr = get_kernel_ptr<T, torch::Tensor>(key_value);
+  T** page_buffer_ptrs =
+      get_kernel_ptr<T*, const torch::Tensor>(key_value_ptrs);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int num_layers = key_value.size(1);
+  int num_tokens = key_value.size(2);
+  int num_origin_elements = key_value.size(3);
+  int elements_per_xword = sizeof(T) / key_value.element_size();
+  int num_xwords = num_origin_elements / elements_per_xword;
+
+  int k_or_v_size = ::is_mla(engine_kv_format) ? 1 : 2;
+
+  // Round up to a sub-group multiple so every sub-group is full.
+  int wg_size = round_up_to_sg(std::min(num_xwords, MAX_WG_SIZE));
+
+  const c10::OptionalDeviceGuard device_guard(paged_memory_device);
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(paged_memory_device.index()).queue();
+
+  // Non-MLA formats use the fused K+V kernel; MLA formats
+  // (k_or_v_size==1) use the per-component kernel.
+  if (k_or_v_size == 2) {
+    if (direction == TransferDirection::H2D) {
+      switch (engine_kv_format) {
+        case EngineKVFormat::NB_NL_TWO_BS_NH_HS:
+          LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(
+              T, false, EngineKVFormat::NB_NL_TWO_BS_NH_HS);
+          break;
+        case EngineKVFormat::NL_X_TWO_NB_BS_NH_HS:
+          LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(
+              T, false, EngineKVFormat::NL_X_TWO_NB_BS_NH_HS);
+          break;
+        case EngineKVFormat::NL_X_NB_TWO_BS_NH_HS:
+          LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(
+              T, false, EngineKVFormat::NL_X_NB_TWO_BS_NH_HS);
+          break;
+        default:
+          throw std::runtime_error("Unsupported non-MLA EngineKVFormat");
+      }
+    } else {
+      switch (engine_kv_format) {
+        case EngineKVFormat::NB_NL_TWO_BS_NH_HS:
+          LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(
+              T, true, EngineKVFormat::NB_NL_TWO_BS_NH_HS);
+          break;
+        case EngineKVFormat::NL_X_TWO_NB_BS_NH_HS:
+          LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(
+              T, true, EngineKVFormat::NL_X_TWO_NB_BS_NH_HS);
+          break;
+        case EngineKVFormat::NL_X_NB_TWO_BS_NH_HS:
+          LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT(
+              T, true, EngineKVFormat::NL_X_NB_TWO_BS_NH_HS);
+          break;
+        default:
+          throw std::runtime_error("Unsupported non-MLA EngineKVFormat");
+      }
+    }
+  } else {
+    // MLA path (k_or_v_size == 1)
+    if (direction == TransferDirection::H2D) {
+      switch (engine_kv_format) {
+        case EngineKVFormat::NL_X_NB_BS_HS:
+          LAUNCH_KERNEL_WITH_FORMAT(T, false, EngineKVFormat::NL_X_NB_BS_HS);
+          break;
+        case EngineKVFormat::NL_X_NBBS_ONE_HS:
+          LAUNCH_KERNEL_WITH_FORMAT(T, false, EngineKVFormat::NL_X_NBBS_ONE_HS);
+          break;
+        default:
+          throw std::runtime_error("Unsupported MLA EngineKVFormat");
+      }
+    } else {
+      switch (engine_kv_format) {
+        case EngineKVFormat::NL_X_NB_BS_HS:
+          LAUNCH_KERNEL_WITH_FORMAT(T, true, EngineKVFormat::NL_X_NB_BS_HS);
+          break;
+        case EngineKVFormat::NL_X_NBBS_ONE_HS:
+          LAUNCH_KERNEL_WITH_FORMAT(T, true, EngineKVFormat::NL_X_NBBS_ONE_HS);
+          break;
+        default:
+          throw std::runtime_error("Unsupported MLA EngineKVFormat");
+      }
+    }
+  }
+}
+
+#undef LAUNCH_KERNEL_WITH_FORMAT
+#undef LAUNCH_FUSED_KV_KERNEL_WITH_FORMAT
+
+// ---------------------------------------------------------------------------
+// Public API: multi_layer_kv_transfer
+// ---------------------------------------------------------------------------
+void multi_layer_kv_transfer(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format, const int block_size,
+    const int head_size, const int skip_prefix_n_tokens) {
+  // head_size is currently unused in the SYCL implementation; accepted to
+  // keep ABI parity with the CUDA c_ops binding so callers can pass the
+  // same kwargs to either backend.
+  (void)head_size;
+  int num_origin_elements = key_value.size(3);
+  int copy_size = num_origin_elements * key_value.element_size();
+
+#define LAUNCH_MULTI_LAYER_KV_TRANSFER(type)                          \
+  do {                                                                \
+    multi_layer_kv_transfer_templated<type>(                          \
+        key_value, key_value_ptrs, slot_mapping, paged_memory_device, \
+        page_buffer_size, direction, engine_kv_format, block_size,    \
+        skip_prefix_n_tokens);                                        \
+  } while (0)
+  if (copy_size % 8 == 0) {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int64_t);
+  } else if (copy_size % 4 == 0) {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int32_t);
+  } else if (copy_size % 2 == 0) {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int16_t);
+  } else {
+    LAUNCH_MULTI_LAYER_KV_TRANSFER(int8_t);
+  }
+#undef LAUNCH_MULTI_LAYER_KV_TRANSFER
+}
+
+// ---------------------------------------------------------------------------
+// Public API: multi_layer_kv_transfer_unilateral
+// ---------------------------------------------------------------------------
+void multi_layer_kv_transfer_unilateral(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format) {
+  const bool use_mla = ::is_mla(engine_kv_format);
+  // MLA case collapses back to multi_layer_kv_transfer
+  if (use_mla) {
+    return multi_layer_kv_transfer(key_value, key_value_ptrs, slot_mapping,
+                                   paged_memory_device, page_buffer_size,
+                                   direction, engine_kv_format);
+  }
+
+  int64_t* key_value_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_value);
+  int64_t** page_buffer_ptrs =
+      get_kernel_ptr<int64_t*, const torch::Tensor>(key_value_ptrs);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int num_layers = key_value.size(1);
+  int num_tokens = slot_mapping.size(0);
+  int num_origin_elements = key_value.size(3);
+  int elements_per_qword = 8 / key_value.element_size();
+  int num_qwords = num_origin_elements / elements_per_qword;
+
+  int k_or_v_size = 2;
+  int kv_num_tokens = key_value.size(2);
+  int wg_size = round_up_to_sg(std::min(num_qwords, MAX_WG_SIZE));
+
+  const c10::OptionalDeviceGuard device_guard(paged_memory_device);
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(paged_memory_device.index()).queue();
+
+  if (direction == TransferDirection::H2D) {
+    submit_multi_layer_unilateral_kernel<int64_t, false>(
+        queue, key_value_ptr, page_buffer_ptrs, slot_mapping_ptr, num_qwords,
+        num_tokens, num_layers, page_buffer_size, k_or_v_size, kv_num_tokens,
+        wg_size);
+  } else {
+    submit_multi_layer_unilateral_kernel<int64_t, true>(
+        queue, key_value_ptr, page_buffer_ptrs, slot_mapping_ptr, num_qwords,
+        num_tokens, num_layers, page_buffer_size, k_or_v_size, kv_num_tokens,
+        wg_size);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// single_layer_kv_transfer — helper template
+// ---------------------------------------------------------------------------
+// USE_MLA and IS_D2H are template parameters so the compiler can
+// dead-strip the unused branch.
+template <bool USE_MLA, bool IS_D2H>
+void single_layer_kv_transfer_impl(sycl::queue& queue, int64_t* lmc_ptr,
+                                   int64_t* vllm_ptr, const int64_t* slot_ptr,
+                                   int num_tokens, int n, int lmc_stride,
+                                   int lmc_value_offset, int block_size,
+                                   int vllm_block_key_stride_in_64bit,
+                                   int vllm_value_offset, int num_heads,
+                                   int head_size_in_64bit, int wg_size) {
+  if (num_tokens <= 0) return;
+
+  sycl::range<1> global_range(static_cast<size_t>(num_tokens) * wg_size);
+  sycl::range<1> local_range(static_cast<size_t>(wg_size));
+
+  queue.parallel_for(
+      sycl::nd_range<1>(global_range, local_range),
+      [=](sycl::nd_item<1> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int64_t token_idx = static_cast<int64_t>(item.get_group(0));
+        const int64_t slot_idx = slot_ptr[token_idx];
+        if (slot_idx < 0) return;
+
+        const int64_t block_idx = slot_idx / block_size;
+        const int64_t block_offset = slot_idx % block_size;
+
+        const int tid = static_cast<int>(item.get_local_id(0));
+        const int nthreads = static_cast<int>(item.get_local_range(0));
+
+        for (int i = tid; i < n; i += nthreads) {
+          const int64_t lmc_key_idx = token_idx * lmc_stride + i;
+          const int head_idx = i / head_size_in_64bit;
+          const int head_offset = i % head_size_in_64bit;
+          const int64_t vllm_key_idx =
+              block_idx * vllm_block_key_stride_in_64bit +
+              block_offset * num_heads * head_size_in_64bit +
+              head_idx * head_size_in_64bit + head_offset;
+
+          if constexpr (IS_D2H) {
+            lmc_ptr[lmc_key_idx] = vllm_ptr[vllm_key_idx];
+            if constexpr (!USE_MLA) {
+              const int64_t lmc_value_idx = lmc_key_idx + lmc_value_offset;
+              const int64_t vllm_value_idx = vllm_key_idx + vllm_value_offset;
+              lmc_ptr[lmc_value_idx] = vllm_ptr[vllm_value_idx];
+            }
+          } else {
+            vllm_ptr[vllm_key_idx] = lmc_ptr[lmc_key_idx];
+            if constexpr (!USE_MLA) {
+              const int64_t lmc_value_idx = lmc_key_idx + lmc_value_offset;
+              const int64_t vllm_value_idx = vllm_key_idx + vllm_value_offset;
+              vllm_ptr[vllm_value_idx] = lmc_ptr[lmc_value_idx];
+            }
+          }
+        }
+      });
+}
+
+// ---------------------------------------------------------------------------
+// Public API: single_layer_kv_transfer
+// ---------------------------------------------------------------------------
+void single_layer_kv_transfer(torch::Tensor& lmc_key_value_cache,
+                              torch::Tensor& vllm_key_value_cache,
+                              torch::Tensor& slot_mapping,
+                              const TransferDirection direction,
+                              const EngineKVFormat engine_kv_format,
+                              const bool token_major) {
+  int64_t* lmc_key_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(lmc_key_value_cache);
+  int64_t* vllm_key_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(vllm_key_value_cache);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / vllm_key_value_cache.element_size();
+
+  int num_tokens = slot_mapping.size(0);
+  int num_heads;
+  int head_size_in_64bit;
+  int block_size;
+
+  const bool use_mla = ::is_mla(engine_kv_format);
+
+  if (use_mla) {
+    num_heads = 1;
+    block_size = vllm_key_value_cache.size(1);
+    head_size_in_64bit = vllm_key_value_cache.size(2) / elements_per_entry;
+  } else {
+    num_heads = vllm_key_value_cache.size(3);
+    head_size_in_64bit = vllm_key_value_cache.size(4) / elements_per_entry;
+    block_size = vllm_key_value_cache.size(2);
+  }
+
+  int lmc_stride;
+  int lmc_value_offset;
+  if (use_mla) {
+    lmc_stride = lmc_key_value_cache.stride(0) / elements_per_entry;
+    lmc_value_offset = 0;
+  } else if (token_major) {
+    lmc_stride = lmc_key_value_cache.stride(0) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(1) / elements_per_entry;
+  } else {
+    lmc_stride = lmc_key_value_cache.stride(1) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(0) / elements_per_entry;
+  }
+
+  int vllm_block_key_stride_in_64bit;
+  int vllm_value_offset;
+  if (use_mla) {
+    vllm_block_key_stride_in_64bit =
+        vllm_key_value_cache.stride(0) / elements_per_entry;
+    vllm_value_offset = 0;
+  } else if (engine_kv_format == EngineKVFormat::NL_X_TWO_NB_BS_NH_HS) {
+    vllm_block_key_stride_in_64bit =
+        vllm_key_value_cache.stride(1) / elements_per_entry;
+    vllm_value_offset = vllm_key_value_cache.stride(0) / elements_per_entry;
+  } else if (engine_kv_format == EngineKVFormat::NL_X_NB_TWO_BS_NH_HS) {
+    vllm_block_key_stride_in_64bit =
+        vllm_key_value_cache.stride(0) / elements_per_entry;
+    vllm_value_offset = vllm_key_value_cache.stride(1) / elements_per_entry;
+  } else {
+    throw std::runtime_error(
+        "Unsupported non-MLA EngineKVFormat in single_layer_kv_transfer: " +
+        std::to_string(static_cast<int>(engine_kv_format)));
+  }
+
+  int n = num_heads * head_size_in_64bit;
+  int wg_size = round_up_to_sg(std::min(n, MAX_WG_SIZE));
+  if (num_tokens <= 0) return;
+
+  const c10::OptionalDeviceGuard device_guard(device_of(vllm_key_value_cache));
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(vllm_key_value_cache.device().index())
+          .queue();
+
+  auto lmc_ptr = lmc_key_value_cache_ptr;
+  auto vllm_ptr = vllm_key_value_cache_ptr;
+  auto slot_ptr = slot_mapping_ptr;
+
+  // Dispatch to 4 compile-time specialisations (USE_MLA × IS_D2H)
+  // so the inner loop is branch-free.
+  if (use_mla) {
+    if (direction == TransferDirection::D2H)
+      single_layer_kv_transfer_impl<true, true>(
+          queue, lmc_ptr, vllm_ptr, slot_ptr, num_tokens, n, lmc_stride,
+          lmc_value_offset, block_size, vllm_block_key_stride_in_64bit,
+          vllm_value_offset, num_heads, head_size_in_64bit, wg_size);
+    else
+      single_layer_kv_transfer_impl<true, false>(
+          queue, lmc_ptr, vllm_ptr, slot_ptr, num_tokens, n, lmc_stride,
+          lmc_value_offset, block_size, vllm_block_key_stride_in_64bit,
+          vllm_value_offset, num_heads, head_size_in_64bit, wg_size);
+  } else {
+    if (direction == TransferDirection::D2H)
+      single_layer_kv_transfer_impl<false, true>(
+          queue, lmc_ptr, vllm_ptr, slot_ptr, num_tokens, n, lmc_stride,
+          lmc_value_offset, block_size, vllm_block_key_stride_in_64bit,
+          vllm_value_offset, num_heads, head_size_in_64bit, wg_size);
+    else
+      single_layer_kv_transfer_impl<false, false>(
+          queue, lmc_ptr, vllm_ptr, slot_ptr, num_tokens, n, lmc_stride,
+          lmc_value_offset, block_size, vllm_block_key_stride_in_64bit,
+          vllm_value_offset, num_heads, head_size_in_64bit, wg_size);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// single_layer_kv_transfer_sgl — helper template
+// ---------------------------------------------------------------------------
+template <bool IS_D2H>
+void single_layer_kv_transfer_sgl_impl(
+    sycl::queue& queue, int64_t* lmc_ptr, int64_t* sgl_k_ptr,
+    int64_t* sgl_v_ptr, const int64_t* slot_ptr, int num_tokens, int n,
+    int lmc_stride, int lmc_value_offset, int block_stride_in_64bit,
+    int block_size, int num_heads, int head_size_in_64bit, int wg_size) {
+  if (num_tokens <= 0) return;
+
+  sycl::range<1> global_range(static_cast<size_t>(num_tokens) * wg_size);
+  sycl::range<1> local_range(static_cast<size_t>(wg_size));
+
+  queue.parallel_for(
+      sycl::nd_range<1>(global_range, local_range),
+      [=](sycl::nd_item<1> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int64_t token_idx = static_cast<int64_t>(item.get_group(0));
+        const int64_t slot_idx = slot_ptr[token_idx];
+        if (slot_idx < 0) return;
+
+        const int64_t block_idx = slot_idx / block_size;
+        const int64_t block_offset = slot_idx % block_size;
+
+        const int tid = static_cast<int>(item.get_local_id(0));
+        const int nthreads = static_cast<int>(item.get_local_range(0));
+
+        for (int i = tid; i < n; i += nthreads) {
+          const int64_t lmc_key_idx = token_idx * lmc_stride + i;
+          const int64_t lmc_value_idx = lmc_key_idx + lmc_value_offset;
+
+          const int head_idx = i / head_size_in_64bit;
+          const int head_offset = i % head_size_in_64bit;
+          const int64_t sgl_kv_idx =
+              block_idx * block_stride_in_64bit +
+              block_offset * num_heads * head_size_in_64bit +
+              head_idx * head_size_in_64bit + head_offset;
+
+          if constexpr (IS_D2H) {
+            lmc_ptr[lmc_key_idx] = sgl_k_ptr[sgl_kv_idx];
+            lmc_ptr[lmc_value_idx] = sgl_v_ptr[sgl_kv_idx];
+          } else {
+            sgl_k_ptr[sgl_kv_idx] = lmc_ptr[lmc_key_idx];
+            sgl_v_ptr[sgl_kv_idx] = lmc_ptr[lmc_value_idx];
+          }
+        }
+      });
+}
+
+// ---------------------------------------------------------------------------
+// Public API: single_layer_kv_transfer_sgl (SGLang)
+// ---------------------------------------------------------------------------
+void single_layer_kv_transfer_sgl(torch::Tensor& lmc_key_value_cache,
+                                  torch::Tensor& sgl_key_cache,
+                                  torch::Tensor& sgl_value_cache,
+                                  torch::Tensor& slot_mapping,
+                                  const TransferDirection direction,
+                                  const bool token_major) {
+  int64_t* lmc_key_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(lmc_key_value_cache);
+  int64_t* sgl_key_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(sgl_key_cache);
+  int64_t* sgl_value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(sgl_value_cache);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / sgl_key_cache.element_size();
+
+  int num_tokens = slot_mapping.size(0);
+  int num_heads = sgl_key_cache.size(2);
+  int head_size_in_64bit = sgl_key_cache.size(3) / elements_per_entry;
+  int block_size = sgl_key_cache.size(1);
+
+  int lmc_stride;
+  int lmc_value_offset;
+  if (token_major) {
+    lmc_stride = lmc_key_value_cache.stride(0) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(1) / elements_per_entry;
+  } else {
+    lmc_stride = lmc_key_value_cache.stride(1) / elements_per_entry;
+    lmc_value_offset = lmc_key_value_cache.stride(0) / elements_per_entry;
+  }
+
+  int block_stride_in_64bit = sgl_key_cache.stride(0) / elements_per_entry;
+  TORCH_CHECK(sgl_key_cache.stride(0) == sgl_value_cache.stride(0));
+
+  int n = num_heads * head_size_in_64bit;
+  int wg_size = round_up_to_sg(std::min(n, MAX_WG_SIZE));
+  if (num_tokens <= 0) return;
+
+  const c10::OptionalDeviceGuard device_guard(device_of(sgl_key_cache));
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(sgl_key_cache.device().index()).queue();
+
+  if (direction == TransferDirection::D2H)
+    single_layer_kv_transfer_sgl_impl<true>(
+        queue, lmc_key_value_cache_ptr, sgl_key_cache_ptr, sgl_value_cache_ptr,
+        slot_mapping_ptr, num_tokens, n, lmc_stride, lmc_value_offset,
+        block_stride_in_64bit, block_size, num_heads, head_size_in_64bit,
+        wg_size);
+  else
+    single_layer_kv_transfer_sgl_impl<false>(
+        queue, lmc_key_value_cache_ptr, sgl_key_cache_ptr, sgl_value_cache_ptr,
+        slot_mapping_ptr, num_tokens, n, lmc_stride, lmc_value_offset,
+        block_stride_in_64bit, block_size, num_heads, head_size_in_64bit,
+        wg_size);
+}
+
+// ---------------------------------------------------------------------------
+// Public API: load_and_reshape_flash (deprecated -- unit tests only)
+// ---------------------------------------------------------------------------
+void load_and_reshape_flash(torch::Tensor& key_value, torch::Tensor& key_cache,
+                            torch::Tensor& value_cache,
+                            torch::Tensor& slot_mapping, const int layer_idx) {
+  int64_t* key_value_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_value);
+  int64_t* key_cache_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_cache);
+  int64_t* value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(value_cache);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / key_cache.element_size();
+  int num_tokens = slot_mapping.size(0);
+  int num_heads = key_cache.size(2);
+  int head_size_in_64bit = key_cache.size(3) / elements_per_entry;
+  int block_size = key_cache.size(1);
+  int key_value_stride = key_value.stride(2) / elements_per_entry;
+  int num_layers = key_value.size(1);
+  int key_layer_offset = layer_idx * key_value.stride(1) / elements_per_entry;
+  int value_layer_offset =
+      (layer_idx + num_layers) * key_value.stride(1) / elements_per_entry;
+  int block_stride_in_64bit = key_cache.stride(0) / elements_per_entry;
+  TORCH_CHECK(key_cache.stride(0) == value_cache.stride(0));
+
+  int n = num_heads * head_size_in_64bit;
+  int wg_size = round_up_to_sg(std::min(n, MAX_WG_SIZE));
+  if (num_tokens <= 0) return;
+
+  sycl::range<1> global_range(static_cast<size_t>(num_tokens) * wg_size);
+  sycl::range<1> local_range(static_cast<size_t>(wg_size));
+
+  const c10::OptionalDeviceGuard device_guard(device_of(key_cache));
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(key_cache.device().index()).queue();
+
+  auto kv_ptr = key_value_ptr;
+  auto k_ptr = key_cache_ptr;
+  auto v_ptr = value_cache_ptr;
+  auto slot_ptr = slot_mapping_ptr;
+
+  queue.parallel_for(
+      sycl::nd_range<1>(global_range, local_range),
+      [=](sycl::nd_item<1> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int64_t token_idx = static_cast<int64_t>(item.get_group(0));
+        const int64_t slot_idx = slot_ptr[token_idx];
+        if (slot_idx < 0) return;
+
+        const int64_t blk_idx = slot_idx / block_size;
+        const int64_t blk_off = slot_idx % block_size;
+
+        const int tid = static_cast<int>(item.get_local_id(0));
+        const int nthreads = static_cast<int>(item.get_local_range(0));
+
+        for (int i = tid; i < n; i += nthreads) {
+          const int64_t tgt_key_idx =
+              key_layer_offset + token_idx * key_value_stride + i;
+          const int64_t tgt_value_idx =
+              value_layer_offset + token_idx * key_value_stride + i;
+
+          const int head_idx = i / head_size_in_64bit;
+          const int head_offset = i % head_size_in_64bit;
+          const int64_t src_kv_idx = blk_idx * block_stride_in_64bit +
+                                     blk_off * num_heads * head_size_in_64bit +
+                                     head_idx * head_size_in_64bit +
+                                     head_offset;
+
+          kv_ptr[tgt_key_idx] = k_ptr[src_kv_idx];
+          kv_ptr[tgt_value_idx] = v_ptr[src_kv_idx];
+        }
+      });
+}
+
+// ---------------------------------------------------------------------------
+// Public API: reshape_and_cache_back_flash (deprecated -- unit
+// tests only)
+// ---------------------------------------------------------------------------
+void reshape_and_cache_back_flash(torch::Tensor& key_value,
+                                  torch::Tensor& key_cache,
+                                  torch::Tensor& value_cache,
+                                  torch::Tensor& slot_mapping,
+                                  const int layer_idx) {
+  int64_t* key_cache_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_cache);
+  int64_t* value_cache_ptr =
+      get_kernel_ptr<int64_t, torch::Tensor>(value_cache);
+  int64_t* key_value_ptr = get_kernel_ptr<int64_t, torch::Tensor>(key_value);
+  const int64_t* slot_mapping_ptr =
+      get_kernel_ptr<const int64_t, const torch::Tensor>(slot_mapping);
+
+  int elements_per_entry = 8 / key_cache.element_size();
+  int num_tokens = slot_mapping.size(0);
+  int num_heads = key_cache.size(2);
+  int head_size_in_64bit = key_cache.size(3) / elements_per_entry;
+  int block_size = key_cache.size(1);
+  int key_value_stride = key_value.stride(2) / elements_per_entry;
+  int num_layers = key_value.size(1);
+  int key_layer_offset = layer_idx * key_value.stride(1) / elements_per_entry;
+  int value_layer_offset =
+      (layer_idx + num_layers) * key_value.stride(1) / elements_per_entry;
+  int block_stride_in_64bit = key_cache.stride(0) / elements_per_entry;
+  TORCH_CHECK(key_cache.stride(0) == value_cache.stride(0));
+
+  int n = num_heads * head_size_in_64bit;
+  int wg_size = round_up_to_sg(std::min(n, MAX_WG_SIZE));
+  if (num_tokens <= 0) return;
+
+  sycl::range<1> global_range(static_cast<size_t>(num_tokens) * wg_size);
+  sycl::range<1> local_range(static_cast<size_t>(wg_size));
+
+  const c10::OptionalDeviceGuard device_guard(device_of(key_cache));
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(key_cache.device().index()).queue();
+
+  auto kv_ptr = key_value_ptr;
+  auto k_ptr = key_cache_ptr;
+  auto v_ptr = value_cache_ptr;
+  auto slot_ptr = slot_mapping_ptr;
+
+  queue.parallel_for(
+      sycl::nd_range<1>(global_range, local_range),
+      [=](sycl::nd_item<1> item) [[sycl::reqd_sub_group_size(16)]] {
+        const int64_t token_idx = static_cast<int64_t>(item.get_group(0));
+        const int64_t slot_idx = slot_ptr[token_idx];
+        if (slot_idx < 0) return;
+
+        const int64_t blk_idx = slot_idx / block_size;
+        const int64_t blk_off = slot_idx % block_size;
+
+        const int tid = static_cast<int>(item.get_local_id(0));
+        const int nthreads = static_cast<int>(item.get_local_range(0));
+
+        for (int i = tid; i < n; i += nthreads) {
+          const int64_t tgt_key_idx =
+              key_layer_offset + token_idx * key_value_stride + i;
+          const int64_t tgt_value_idx =
+              value_layer_offset + token_idx * key_value_stride + i;
+
+          const int head_idx = i / head_size_in_64bit;
+          const int head_offset = i % head_size_in_64bit;
+          const int64_t src_kv_idx = blk_idx * block_stride_in_64bit +
+                                     blk_off * num_heads * head_size_in_64bit +
+                                     head_idx * head_size_in_64bit +
+                                     head_offset;
+
+          k_ptr[src_kv_idx] = kv_ptr[tgt_key_idx];
+          v_ptr[src_kv_idx] = kv_ptr[tgt_value_idx];
+        }
+      });
+}
+
+// ---------------------------------------------------------------------------
+// Public API: lmcache_memcpy_async
+// ---------------------------------------------------------------------------
+void lmcache_memcpy_async(uintptr_t dest, uintptr_t src, size_t nbytes,
+                          TransferDirection direction,
+                          size_t host_buffer_offset,
+                          size_t host_buffer_alignments) {
+  TORCH_CHECK((host_buffer_alignments & (host_buffer_alignments - 1)) == 0,
+              "host_buffer_alignments must be power of two");
+
+  // SYCL USM memcpy infers direction from pointer allocation types;
+  // the `direction` parameter is retained only for API compatibility.
+  (void)direction;
+
+  sycl::queue& queue = c10::xpu::getCurrentXPUStream().queue();
+
+  size_t offset = 0;
+  const size_t mask = host_buffer_alignments - 1;
+
+  while (offset < nbytes) {
+    size_t current_src = src + offset;
+    size_t current_dest = dest + offset;
+
+    size_t aligned_area_end =
+        ((offset + host_buffer_offset) & ~mask) + host_buffer_alignments;
+    size_t real_end = std::min(host_buffer_offset + nbytes, aligned_area_end);
+    size_t max_nbytes = real_end - offset - host_buffer_offset;
+
+    // USM memcpy is direction-agnostic.
+    queue.memcpy(reinterpret_cast<void*>(current_dest),
+                 reinterpret_cast<const void*>(current_src), max_nbytes);
+
+    offset += max_nbytes;
+  }
+}
diff --git a/csrc/sycl/mem_kernels_sycl.h b/csrc/sycl/mem_kernels_sycl.h
new file mode 100644
index 0000000..5a36763
--- /dev/null
+++ b/csrc/sycl/mem_kernels_sycl.h
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <c10/util/Exception.h>
+#include "../kv_transfer_types.h"
+
+void multi_layer_kv_transfer(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format, const int block_size = 0,
+    const int head_size = 0, const int skip_prefix_n_tokens = 0);
+
+// collapses to multi_layer_kv_transfer for MLA
+void multi_layer_kv_transfer_unilateral(
+    torch::Tensor& key_value, const torch::Tensor& key_value_ptrs,
+    const torch::Tensor& slot_mapping, const torch::Device& paged_memory_device,
+    const int page_buffer_size, const TransferDirection direction,
+    const EngineKVFormat engine_kv_format);
+
+void single_layer_kv_transfer(torch::Tensor& lmc_key_value_cache,
+                              torch::Tensor& vllm_key_value_cache,
+                              torch::Tensor& slot_mapping,
+                              const TransferDirection direction,
+                              const EngineKVFormat engine_kv_format,
+                              const bool token_major = false);
+
+void single_layer_kv_transfer_sgl(torch::Tensor& lmc_key_value_cache,
+                                  torch::Tensor& sgl_key_cache,
+                                  torch::Tensor& sgl_value_cache,
+                                  torch::Tensor& slot_mapping,
+                                  const TransferDirection direction,
+                                  const bool token_major = false);
+
+// Asynchronous memory copy between host and device buffers.
+// The `direction` parameter is retained for API compatibility but is unused:
+// SYCL USM memcpy infers direction from pointer allocation types.
+void lmcache_memcpy_async(uintptr_t dest, uintptr_t src, size_t nbytes,
+                          TransferDirection direction,
+                          size_t host_buffer_offset,
+                          size_t host_buffer_alignments);
+
+// deprecated / unused except in unit tests
+void load_and_reshape_flash(torch::Tensor& key_value, torch::Tensor& key_cache,
+                            torch::Tensor& value_cache,
+                            torch::Tensor& slot_mapping, const int layer_idx);
+
+// deprecated / unused except in unit tests
+void reshape_and_cache_back_flash(torch::Tensor& key_value,
+                                  torch::Tensor& key_cache,
+                                  torch::Tensor& value_cache,
+                                  torch::Tensor& slot_mapping,
+                                  const int layer_idx);
diff --git a/csrc/sycl/pos_kernels_sycl.cpp b/csrc/sycl/pos_kernels_sycl.cpp
new file mode 100644
index 0000000..9909f80
--- /dev/null
+++ b/csrc/sycl/pos_kernels_sycl.cpp
@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// Fused rotary embedding (undo-then-redo) for Intel XPU.
+//
+// Algorithm
+// ---------
+//   For each token, "undo" the rotary embedding that was applied at
+//   old_positions[token] and "redo" the rotary embedding at
+//   new_positions[token].  Operates in-place on `key`.
+//
+// Intel XPU mapping
+// -----------------
+//   - 1-D nd_range, one work-group per token, work-group size =
+//     min(num_kv_heads * embed_dim, MAX_WG_SIZE).
+//   - sub_group_size locked to 16 (Intel native SIMD).
+//   - The cos/sin cache rows for both old and new positions are loaded
+//     once per token via cached global reads.  rot_dim is typically <=
+//     256 floats so register/L1 pressure is fine.
+//   - IS_NEOX is a template parameter so the IGC can specialise and drop
+//     the run-time test inside the hot loop.
+//
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
+#include <sycl/sycl.hpp>
+#pragma GCC diagnostic pop
+
+#include <torch/all.h>
+#include <ATen/ATen.h>
+#include <c10/core/DeviceGuard.h>
+#include <c10/xpu/XPUStream.h>
+
+#include "cachegen_kernels_sycl.h"
+
+#include <algorithm>
+#include <cstdint>
+#include <stdexcept>
+
+namespace {
+
+constexpr int INTEL_SUB_GROUP_SIZE = 16;
+constexpr int MAX_WG_SIZE = 512;
+// Upper bound on rot_dim for SLM caching of (old_cos|old_sin|new_cos|new_sin).
+// 4 * 256 * sizeof(fp32) = 4 KB SLM per WG -- well under PVC's 64 KB/sub-slice
+// budget and lets multiple WGs co-reside.
+constexpr int ROPE_MAX_ROT_DIM = 256;
+
+template <typename scalar_t, bool IS_NEOX>
+void rotary_embedding_kernel_sycl(sycl::queue& queue,
+                                  const int64_t* old_positions,
+                                  const int64_t* new_positions, scalar_t* key,
+                                  const scalar_t* cos_sin_cache, int rot_dim,
+                                  int64_t key_stride, int num_kv_heads,
+                                  int head_size, int num_tokens) {
+  // Total work items per token (one per (head, rot_pair)).
+  const int embed_dim = rot_dim / 2;
+  const int wg_size = std::min<int>(num_kv_heads * embed_dim, MAX_WG_SIZE);
+  if (wg_size <= 0 || num_tokens <= 0) return;
+
+  sycl::range<1> global_range(static_cast<size_t>(num_tokens) *
+                              static_cast<size_t>(wg_size));
+  sycl::range<1> local_range(static_cast<size_t>(wg_size));
+
+  queue.submit([&](sycl::handler& cgh) {
+    // Cache the per-token cos/sin rows in SLM so the inner loop hits SLM
+    // (latency ~3-5 cycles on Xe) instead of HBM for every rot_offset.
+    sycl::local_accessor<scalar_t, 1> cs_shared(
+        sycl::range<1>(4 * ROPE_MAX_ROT_DIM), cgh);
+
+    cgh.parallel_for(
+        sycl::nd_range<1>(global_range, local_range),
+        [=](sycl::nd_item<1> item)
+            [[sycl::reqd_sub_group_size(INTEL_SUB_GROUP_SIZE)]] {
+              const int token_idx = static_cast<int>(item.get_group(0));
+              const int tid = static_cast<int>(item.get_local_id(0));
+              const int nthreads = static_cast<int>(item.get_local_range(0));
+
+              const int64_t old_pos = old_positions[token_idx];
+              const int64_t new_pos = new_positions[token_idx];
+
+              const scalar_t* old_cache = cos_sin_cache + old_pos * rot_dim;
+              const scalar_t* new_cache = cos_sin_cache + new_pos * rot_dim;
+
+              // Stage [old_cos | old_sin | new_cos | new_sin], each of
+              // length embed_dim, into SLM in one coalesced sweep.
+              scalar_t* sl_old_cos = &cs_shared[0];
+              scalar_t* sl_old_sin = &cs_shared[embed_dim];
+              scalar_t* sl_new_cos = &cs_shared[2 * embed_dim];
+              scalar_t* sl_new_sin = &cs_shared[3 * embed_dim];
+              for (int j = tid; j < embed_dim; j += nthreads) {
+                sl_old_cos[j] = old_cache[j];
+                sl_old_sin[j] = old_cache[embed_dim + j];
+                sl_new_cos[j] = new_cache[j];
+                sl_new_sin[j] = new_cache[embed_dim + j];
+              }
+              item.barrier(sycl::access::fence_space::local_space);
+
+              const int nk = num_kv_heads * embed_dim;
+              for (int i = tid; i < nk; i += nthreads) {
+                const int head_idx = i / embed_dim;
+                const int rot_offset = i % embed_dim;
+                const int64_t token_head =
+                    static_cast<int64_t>(token_idx) * key_stride +
+                    static_cast<int64_t>(head_idx) * head_size;
+                scalar_t* arr = key + token_head;
+
+                int x_index, y_index;
+                if constexpr (IS_NEOX) {
+                  x_index = rot_offset;
+                  y_index = embed_dim + rot_offset;
+                } else {
+                  x_index = 2 * rot_offset;
+                  y_index = 2 * rot_offset + 1;
+                }
+                const scalar_t oc = sl_old_cos[rot_offset];
+                const scalar_t os_ = sl_old_sin[rot_offset];
+                const scalar_t nc = sl_new_cos[rot_offset];
+                const scalar_t ns = sl_new_sin[rot_offset];
+
+                const scalar_t x = arr[x_index];
+                const scalar_t y = arr[y_index];
+
+                const scalar_t x_rev = x * oc + y * os_;
+                const scalar_t y_rev = y * oc - x * os_;
+
+                arr[x_index] = x_rev * nc - y_rev * ns;
+                arr[y_index] = y_rev * nc + x_rev * ns;
+              }
+            });
+  });
+}
+
+template <typename scalar_t>
+void dispatch_neox(sycl::queue& queue, const int64_t* old_pos,
+                   const int64_t* new_pos, scalar_t* key,
+                   const scalar_t* cos_sin_cache, int rot_dim,
+                   int64_t key_stride, int num_kv_heads, int head_size,
+                   int num_tokens, bool is_neox) {
+  if (is_neox) {
+    rotary_embedding_kernel_sycl<scalar_t, true>(
+        queue, old_pos, new_pos, key, cos_sin_cache, rot_dim, key_stride,
+        num_kv_heads, head_size, num_tokens);
+  } else {
+    rotary_embedding_kernel_sycl<scalar_t, false>(
+        queue, old_pos, new_pos, key, cos_sin_cache, rot_dim, key_stride,
+        num_kv_heads, head_size, num_tokens);
+  }
+}
+
+}  // namespace
+
+void rotary_embedding_k_fused_xpu(const torch::Tensor& old_positions,
+                                  const torch::Tensor& new_positions,
+                                  torch::Tensor& key, int64_t head_size,
+                                  const torch::Tensor& cos_sin_cache,
+                                  bool is_neox) {
+  if (!key.device().is_xpu()) {
+    throw std::runtime_error(
+        "rotary_embedding_k_fused_xpu: key must be an XPU tensor");
+  }
+  if (!old_positions.device().is_xpu() || !new_positions.device().is_xpu() ||
+      !cos_sin_cache.device().is_xpu()) {
+    throw std::runtime_error(
+        "rotary_embedding_k_fused_xpu: all tensors must be on XPU");
+  }
+  if (old_positions.scalar_type() != at::kLong ||
+      new_positions.scalar_type() != at::kLong) {
+    throw std::runtime_error(
+        "rotary_embedding_k_fused_xpu: positions must be int64");
+  }
+  if (cos_sin_cache.dim() != 2) {
+    throw std::runtime_error(
+        "rotary_embedding_k_fused_xpu: cos_sin_cache must be 2-D");
+  }
+  if (cos_sin_cache.size(1) > ROPE_MAX_ROT_DIM) {
+    throw std::runtime_error(
+        "rotary_embedding_k_fused_xpu: rot_dim exceeds ROPE_MAX_ROT_DIM (256)");
+  }
+
+  const int64_t num_tokens = key.numel() / (key.size(-1) * key.size(-2));
+  const int rot_dim = static_cast<int>(cos_sin_cache.size(1));
+  const int num_kv_heads = static_cast<int>(key.size(-2));
+  const int64_t key_stride = static_cast<int64_t>(num_kv_heads) * head_size;
+
+  const c10::DeviceGuard guard(key.device());
+  sycl::queue& queue =
+      c10::xpu::getCurrentXPUStream(key.device().index()).queue();
+
+  // Mirror LMC_DISPATCH_FLOATING_TYPES.
+  AT_DISPATCH_FLOATING_TYPES_AND2(
+      at::ScalarType::Half, at::ScalarType::BFloat16, key.scalar_type(),
+      "rotary_embedding_k_fused_xpu", [&] {
+        dispatch_neox<scalar_t>(
+            queue, old_positions.data_ptr<int64_t>(),
+            new_positions.data_ptr<int64_t>(), key.data_ptr<scalar_t>(),
+            cos_sin_cache.data_ptr<scalar_t>(), rot_dim, key_stride,
+            num_kv_heads, static_cast<int>(head_size),
+            static_cast<int>(num_tokens), is_neox);
+      });
+}
diff --git a/csrc/sycl/pybind_sycl.cpp b/csrc/sycl/pybind_sycl.cpp
new file mode 100644
index 0000000..c3c4b76
--- /dev/null
+++ b/csrc/sycl/pybind_sycl.cpp
@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//
+// Python bindings for the SYCL/XPU memory and CacheGen kernels.
+// Exposed as `lmcache.xpu_ops`.
+//
+#include <pybind11/pybind11.h>
+#include <torch/torch.h>
+#include "mem_kernels_sycl.h"
+#include "cachegen_kernels_sycl.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(xpu_ops, m) {
+  py::enum_<TransferDirection>(m, "TransferDirection")
+      .value("H2D", TransferDirection::H2D)
+      .value("D2H", TransferDirection::D2H)
+      .export_values();
+  py::enum_<EngineKVFormat>(m, "EngineKVFormat")
+      .value("NB_NL_TWO_BS_NH_HS", EngineKVFormat::NB_NL_TWO_BS_NH_HS)
+      .value("NL_X_TWO_NB_BS_NH_HS", EngineKVFormat::NL_X_TWO_NB_BS_NH_HS)
+      .value("NL_X_NB_TWO_BS_NH_HS", EngineKVFormat::NL_X_NB_TWO_BS_NH_HS)
+      .value("NL_X_NB_BS_HS", EngineKVFormat::NL_X_NB_BS_HS)
+      .value("TWO_X_NL_X_NBBS_NH_HS", EngineKVFormat::TWO_X_NL_X_NBBS_NH_HS)
+      .value("NL_X_NBBS_ONE_HS", EngineKVFormat::NL_X_NBBS_ONE_HS)
+      .value("NL_X_TWO_NB_NH_BS_HS", EngineKVFormat::NL_X_TWO_NB_NH_BS_HS)
+      .value("NL_X_NB_TWO_NH_BS_HS", EngineKVFormat::NL_X_NB_TWO_NH_BS_HS)
+      .value("NB_NL_TWO_NH_BS_HS", EngineKVFormat::NB_NL_TWO_NH_BS_HS)
+      .value("TWO_X_NL_X_NB_BS_NH_HS", EngineKVFormat::TWO_X_NL_X_NB_BS_NH_HS)
+      .value("NL_X_NB_NH_BS_TWO_HS", EngineKVFormat::NL_X_NB_NH_BS_TWO_HS)
+      .export_values();
+  m.def("multi_layer_kv_transfer", &multi_layer_kv_transfer,
+        py::arg("key_value"), py::arg("key_value_ptrs"),
+        py::arg("slot_mapping"), py::arg("paged_memory_device"),
+        py::arg("page_buffer_size"), py::arg("direction"),
+        py::arg("engine_kv_format"), py::arg("block_size") = 0,
+        py::arg("head_size") = 0, py::arg("skip_prefix_n_tokens") = 0,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("single_layer_kv_transfer", &single_layer_kv_transfer,
+        py::arg("lmc_key_value_cache"), py::arg("vllm_key_value_cache"),
+        py::arg("slot_mapping"), py::arg("direction"),
+        py::arg("engine_kv_format"), py::arg("token_major") = false,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("single_layer_kv_transfer_sgl", &single_layer_kv_transfer_sgl,
+        py::arg("lmc_key_value_cache"), py::arg("sgl_key_cache"),
+        py::arg("sgl_value_cache"), py::arg("slot_mapping"),
+        py::arg("direction"), py::arg("token_major") = false,
+        py::call_guard<py::gil_scoped_release>());
+  m.def("multi_layer_kv_transfer_unilateral",
+        &multi_layer_kv_transfer_unilateral, py::arg("key_value"),
+        py::arg("key_value_ptrs"), py::arg("slot_mapping"),
+        py::arg("paged_memory_device"), py::arg("page_buffer_size"),
+        py::arg("direction"), py::arg("engine_kv_format"),
+        py::call_guard<py::gil_scoped_release>());
+  m.def("load_and_reshape_flash", &load_and_reshape_flash);
+  m.def("reshape_and_cache_back_flash", &reshape_and_cache_back_flash);
+  m.def("lmcache_memcpy_async", &lmcache_memcpy_async,
+        py::call_guard<py::gil_scoped_release>());
+
+  // CacheGen / RoPE kernels (Intel XPU).  Names match the
+  // lmcache.python_ops_fallback module so the backend selection in
+  // lmcache.v1.platform can transparently override.
+  m.def("calculate_cdf", &calculate_cdf_xpu, py::arg("input"),
+        py::arg("max_bins"));
+  m.def("rotary_embedding_k_fused", &rotary_embedding_k_fused_xpu,
+        py::arg("old_positions"), py::arg("new_positions"), py::arg("key"),
+        py::arg("head_size"), py::arg("cos_sin_cache"), py::arg("is_neox"));
+  m.def("encode_fast_new", &encode_fast_new_xpu, py::arg("cdf"),
+        py::arg("input_sym"), py::arg("output_buffer"),
+        py::arg("output_lengths"));
+  m.def("decode_fast_new", &decode_fast_new_xpu, py::arg("cdf"),
+        py::arg("bytestreams"), py::arg("lengths"), py::arg("output"));
+  m.def("decode_fast_prefsum", &decode_fast_prefsum_xpu, py::arg("cdf"),
+        py::arg("bytestreams"), py::arg("lengths_prefsum"), py::arg("output"));
+  // Backward-compat alias: GPUKVFormat -> EngineKVFormat
+  m.attr("GPUKVFormat") = m.attr("EngineKVFormat");
+}
diff --git a/csrc/utils.cpp b/csrc/utils.cpp
new file mode 100644
index 0000000..85b249d
--- /dev/null
+++ b/csrc/utils.cpp
@@ -0,0 +1,13 @@
+#include <cuda_runtime.h>
+#include <stdexcept>
+#include "utils.h"
+
+std::string get_gpu_pci_bus_id(int device) {
+  char pciBusId[13];  // 13 bytes per CUDA doc
+  cudaError_t err = cudaDeviceGetPCIBusId(pciBusId, sizeof(pciBusId), device);
+  if (err != cudaSuccess) {
+    throw std::runtime_error(std::string("cudaDeviceGetPCIBusId failed: ") +
+                             cudaGetErrorString(err));
+  }
+  return std::string(pciBusId);
+}
diff --git a/csrc/utils.h b/csrc/utils.h
new file mode 100644
index 0000000..c94942d
--- /dev/null
+++ b/csrc/utils.h
@@ -0,0 +1,3 @@
+#include <string>
+
+std::string get_gpu_pci_bus_id(int device);
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 0000000..4c5cdb9
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,155 @@
+# The LMCache Dockerfile is used to build a LMCache image that is integrated
+# to run with vLLM OpenAI server.
+
+# Please update any changes made here to
+# docs/source/developer_guide/docker_file.rst
+# docs/source/getting_started/installation.rst
+# docs/source/production/docker_deployment.rst
+
+ARG CUDA_VERSION=13.0
+ARG UBUNTU_VERSION=24.04
+ARG NGC_VERSION=25.09
+ARG BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:${NGC_VERSION}-cuda${CUDA_VERSION}-devel-ubuntu${UBUNTU_VERSION}
+
+#################### BASE BUILD IMAGE ####################
+# Prepare basic build environment
+
+FROM ${BASE_IMAGE} AS base
+
+ARG CUDA_VERSION
+ARG PYTHON_VERSION=3.12
+ARG UBUNTU_VERSION
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PATH="/opt/venv/bin:${PATH}"
+
+# Install Python and other dependencies
+RUN echo 'tzdata tzdata/Areas select America' | debconf-set-selections \
+    && echo 'tzdata tzdata/Zones/America select Los_Angeles' | debconf-set-selections \
+    && apt-get update -y \
+    && apt-get install -y --no-install-recommends \
+        ccache software-properties-common git curl sudo \
+        python3 python3-dev python3-venv python3-pip tzdata libxcb1-dev \
+    && ldconfig /usr/local/cuda-$(echo $CUDA_VERSION | cut -d. -f1,2)/compat/ \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv ~/.local/bin/uv /usr/local/bin/ \
+    && mv ~/.local/bin/uvx /usr/local/bin/ \
+    && uv venv /opt/venv \
+    && . /opt/venv/bin/activate \
+    && python3 --version
+
+WORKDIR /workspace
+
+# CUDA arch list used by torch
+ARG torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX'
+ENV TORCH_CUDA_ARCH_LIST=${torch_cuda_arch_list}
+
+#################### vLLM IMAGE & LMCache (Build) ##########################
+# Integrate vLLM nightly build and LMCache build, and expose vLLM OpenAI API
+
+FROM base AS image-build
+
+# install build dependencies
+COPY ./requirements/build.txt build.txt
+
+# Max jobs used by Ninja to build extensions
+ARG max_jobs=2
+ENV MAX_JOBS=${max_jobs}
+
+# Number of threads used by nvcc
+ARG nvcc_threads=8
+ENV NVCC_THREADS=$nvcc_threads
+
+ARG CUDA_VERSION
+ARG VLLM_VERSION=nightly
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    . /opt/venv/bin/activate && \
+    uv pip install -r build.txt
+
+ARG LMCACHE_COMMIT_ID=1
+
+COPY . /workspace/LMCache
+WORKDIR /workspace/LMCache
+
+ 
+RUN --mount=type=cache,target=/root/.cache/ccache,id=ccache \
+    --mount=type=cache,target=/root/.cache/uv,id=uv-cache,sharing=locked \
+    . /opt/venv/bin/activate && \
+    CUDA_TAG=cu$(echo ${CUDA_VERSION} | tr -d '.') && \
+    export LMCACHE_CUDA_MAJOR=$(echo ${CUDA_VERSION} | cut -d. -f1) && \
+    if [ "$VLLM_VERSION" = "nightly" ]; then \
+        VLLM_PRECOMPILED_WHEEL_VARIANT=${CUDA_TAG} uv pip install --prerelease=allow \
+            'vllm[runai,tensorizer,flashinfer]' \
+            --extra-index-url https://wheels.vllm.ai/nightly/${CUDA_TAG} \
+            --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+            --index-strategy unsafe-first-match ; \
+    else \
+        VLLM_PRECOMPILED_WHEEL_VARIANT=${CUDA_TAG} uv pip install --prerelease=allow \
+            "vllm[runai,tensorizer,flashinfer]==${VLLM_VERSION}" ; \
+    fi && \
+    python3 -c 'import torch; print("TORCH=", torch.__version__)' && \
+    python3 setup.py bdist_wheel --dist-dir=dist_lmcache && \
+    uv pip install ./dist_lmcache/*.whl --verbose && \
+  
+    uv pip install --reinstall-package "nixl-cu${LMCACHE_CUDA_MAJOR}" \
+        "nixl-cu${LMCACHE_CUDA_MAJOR}"
+
+WORKDIR /workspace
+ENTRYPOINT ["/opt/venv/bin/vllm", "serve"]
+
+#################### vLLM IMAGE & LMCache (Release, cu13) #######################
+# Integrate vLLM and LMCache stable releases, and expose vLLM OpenAI API.
+# The default lmcache wheel on PyPI is built against cu13; the cu13 torch
+# index is hinted explicitly so vLLM also resolves to its cu13 build.
+
+FROM base AS image-release
+
+ARG CUDA_VERSION
+
+ARG LMCACHE_VERSION
+
+RUN . /opt/venv/bin/activate && \
+    CUDA_TAG=cu$(echo ${CUDA_VERSION} | tr -d '.') && \
+    CUDA_MAJOR=$(echo ${CUDA_VERSION} | cut -d. -f1) && \
+    VER=$(echo "${LMCACHE_VERSION}" | sed 's/^v//') && \
+    VLLM_PRECOMPILED_WHEEL_VARIANT=${CUDA_TAG} uv pip install --prerelease=allow \
+        vllm[runai,tensorizer,flashinfer] \
+        --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+        --index-strategy unsafe-best-match && \
+    uv pip install "lmcache${VER:+==${VER}}" \
+        --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+        --index-strategy unsafe-best-match --verbose && \
+  
+    uv pip install --reinstall-package "nixl-cu${CUDA_MAJOR}" "nixl-cu${CUDA_MAJOR}"
+
+WORKDIR /workspace
+ENTRYPOINT ["/opt/venv/bin/vllm", "serve"]
+
+#################### vLLM IMAGE & LMCache (Release, cu129) ######################
+# Installs the stable cu129 vLLM release wheel and
+# lmcache from the v{tag}-cu129 GitHub Release.
+# The cu129 torch index is hinted explicitly so vLLM resolves to its cu129 build.
+
+FROM base AS image-release-cu129
+
+ARG CUDA_VERSION=12.9
+ARG LMCACHE_VERSION
+
+RUN . /opt/venv/bin/activate && \
+    CUDA_TAG=cu$(echo ${CUDA_VERSION} | tr -d '.') && \
+    CUDA_MAJOR=$(echo ${CUDA_VERSION} | cut -d. -f1) && \
+    VER=$(echo ${LMCACHE_VERSION} | sed 's/^v//') && \
+    VLLM_PRECOMPILED_WHEEL_VARIANT=${CUDA_TAG} uv pip install --prerelease=allow \
+        vllm[runai,tensorizer,flashinfer] \
+        --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+        --index-strategy unsafe-best-match && \
+    python3 -c 'import torch; print("TORCH=", torch.__version__)' && \
+    uv pip install lmcache==${VER} \
+        --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+        --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VER}-cu129 \
+        --index-strategy unsafe-best-match --verbose && \
+    
+    uv pip install --reinstall-package "nixl-cu${CUDA_MAJOR}" "nixl-cu${CUDA_MAJOR}"
+
+WORKDIR /workspace
+ENTRYPOINT ["/opt/venv/bin/vllm", "serve"]
diff --git a/docker/Dockerfile.lightweight b/docker/Dockerfile.lightweight
new file mode 100644
index 0000000..0f19949
--- /dev/null
+++ b/docker/Dockerfile.lightweight
@@ -0,0 +1,21 @@
+# This is a lightweight image of the latest release of LMCache (without NIXL) bundled with the latest release of vLLM.
+# Note: You will not be able to run Prefill-Decode Disaggregation (PD) with this image because NIXL is not installed.
+FROM vllm/vllm-openai:latest
+
+RUN uv pip install --system --no-cache lmcache
+
+
+# Build: 
+# docker build -f Dockerfile.lightweight -t 'lmcache/vllm-openai:lightweight' .
+
+# Run: 
+# export HF_TOKEN=<your_huggingface_token>
+# docker run --runtime nvidia --gpus all \
+#    -v ~/.cache/huggingface:/root/.cache/huggingface \
+#    --env "HF_TOKEN=$HF_TOKEN" \
+#    -p 8000:8000 \
+#    --ipc=host \
+#    lmcache/vllm-openai:lightweight \
+#    --model Qwen/Qwen3-0.6B \
+#    --kv-transfer-config \
+#    '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
diff --git a/docker/Dockerfile.payload b/docker/Dockerfile.payload
new file mode 100644
index 0000000..af2c623
--- /dev/null
+++ b/docker/Dockerfile.payload
@@ -0,0 +1,62 @@
+# LMCache payload image for the operator's code-payload injection.
+#
+# When an LMCacheEngine sets spec.injection.payloadImage, the mutating webhook
+# (operator/internal/webhook/lmcache_pod_injector.go) stages this image into a
+# vLLM pod: it ships the `lmcache` tree under /payload and, on start, copies it
+# into a shared emptyDir that the vLLM container imports via
+# PYTHONPATH=/lmcache-payload — overriding the lmcache baked into the vLLM image
+# so the vLLM client and the LMCache engine server run one matched build.
+#
+# Webhook contract (keep in lockstep):
+#   - the tree lives under /payload;
+#   - the ENTRYPOINT copies /payload into $SHARED_DIR (the webhook sets
+#     SHARED_DIR=/lmcache-payload and mounts a RW emptyDir there);
+#   - no command override — one makes the webhook skip staging.
+#
+# lmcache ships COMPILED extensions (.so) tied to a Python minor + torch/CUDA
+# ABI, so this image EXTRACTS the already-built lmcache from a source image
+# rather than recompiling. Set SOURCE_IMAGE to your vLLM image (or an
+# ABI-compatible one).
+#
+# Build:
+#   docker build -f docker/Dockerfile.payload \
+#     --build-arg SOURCE_IMAGE=lmcache/vllm-openai:latest-nightly \
+#     -t <registry>/lmcache-payload:latest-nightly .
+#
+# Smoke test:
+#   docker run --rm -e SHARED_DIR=/out -v "$PWD/out:/out" <registry>/lmcache-payload:...
+#   test -f out/lmcache/__init__.py
+
+# The image whose installed lmcache tree is extracted into the payload. Its
+# Python/torch/CUDA ABI must match the vLLM pods that will import the payload.
+ARG SOURCE_IMAGE=lmcache/vllm-openai:latest-nightly
+
+#################### EXTRACT ####################
+# Pull the installed `lmcache` package (and its dist-info, for version metadata)
+# out of the source image into /payload. The location is resolved from the
+# running interpreter so it tracks whatever site-packages / venv the image uses.
+FROM ${SOURCE_IMAGE} AS extract
+
+RUN set -eux; \
+    SITE="$(python3 -c 'import os, lmcache; print(os.path.dirname(os.path.dirname(os.path.abspath(lmcache.__file__))))')"; \
+    test -f "$SITE/lmcache/__init__.py"; \
+    mkdir -p /payload; \
+    for d in "$SITE"/lmcache "$SITE"/lmcache-*.dist-info; do \
+        [ -e "$d" ] && cp -a "$d" /payload/; \
+    done; \
+    test -f /payload/lmcache/__init__.py; \
+    python3 -c 'import lmcache; print("payload lmcache:", getattr(lmcache, "__version__", "unknown"))'
+
+#################### PAYLOAD ####################
+# Minimal image whose only job is to copy /payload into the injected emptyDir.
+# busybox provides `cp -a`; SHARED_DIR is supplied at run time by the webhook
+# (defaulted here only so a standalone `docker run -e SHARED_DIR=...` works).
+FROM busybox:1.37
+
+COPY --from=extract /payload /payload
+
+ENV SHARED_DIR=/lmcache-payload
+
+# `cp -a /payload/.` copies the tree CONTENTS (so $SHARED_DIR/lmcache/... lands
+# directly on PYTHONPATH). `${SHARED_DIR:?}` fails loudly if the env is missing.
+ENTRYPOINT ["/bin/sh", "-c", "set -eux; mkdir -p \"${SHARED_DIR:?SHARED_DIR must be set}\"; cp -a /payload/. \"${SHARED_DIR}/\""]
diff --git a/docker/Dockerfile.rocm b/docker/Dockerfile.rocm
new file mode 100644
index 0000000..9bae5b5
--- /dev/null
+++ b/docker/Dockerfile.rocm
@@ -0,0 +1,126 @@
+# The LMCache ROCm Dockerfile builds an LMCache image integrated with
+# vLLM-ROCm for AMD Instinct GPUs (MI300X/MI325X, MI350X/MI355X).
+#
+# Please update any changes made here to:
+# docs/source/developer_guide/docker_file.rst
+# docs/source/getting_started/installation.rst
+# docs/source/production/docker_deployment.rst
+#
+# Key differences from the CUDA Dockerfile:
+# - Uses ROCm base image instead of CUDA
+# - Builds HIP extensions (BUILD_WITH_HIP=1, CXX=hipcc)
+# - Skips flashinfer (not available on ROCm)
+# - Skips NIXL (not yet available on ROCm)
+
+ARG ROCM_VERSION=7.0
+ARG BASE_IMAGE=rocm/dev-ubuntu-24.04:${ROCM_VERSION}-complete
+
+#################### BASE BUILD IMAGE ####################
+
+FROM ${BASE_IMAGE} AS base
+
+ARG PYTHON_VERSION=3.12
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PATH="/opt/venv/bin:${PATH}"
+
+# Install Python and other dependencies
+RUN echo 'tzdata tzdata/Areas select America' | debconf-set-selections \
+    && echo 'tzdata tzdata/Zones/America select Los_Angeles' | debconf-set-selections \
+    && apt-get update -y \
+    && apt-get install -y --no-install-recommends \
+        ccache software-properties-common git curl sudo \
+        python3 python3-dev python3-venv python3-pip tzdata \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv ~/.local/bin/uv /usr/local/bin/ \
+    && mv ~/.local/bin/uvx /usr/local/bin/ \
+    && uv venv /opt/venv \
+    && . /opt/venv/bin/activate \
+    && python3 --version
+
+WORKDIR /workspace
+
+# ROCm GPU architectures — use PYTORCH_ROCM_ARCH (comma-separated)
+# which is what PyTorch's extension builder reads for ROCm targets.
+ARG PYTORCH_ROCM_ARCH="gfx942,gfx950"
+ENV PYTORCH_ROCM_ARCH=${PYTORCH_ROCM_ARCH}
+
+#################### vLLM-ROCm & LMCache (Build) ##########################
+
+FROM base AS image-build
+
+ARG ROCM_VERSION
+
+COPY ./requirements/build.txt build.txt
+
+ARG max_jobs=2
+ENV MAX_JOBS=${max_jobs}
+
+ARG VLLM_VERSION=nightly
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    . /opt/venv/bin/activate && \
+    uv pip install -r build.txt
+
+ARG LMCACHE_COMMIT_ID=1
+
+COPY . /workspace/LMCache
+WORKDIR /workspace/LMCache
+
+# Build LMCache with HIP extensions and install vLLM-ROCm.
+# - BUILD_WITH_HIP=1: compile HIP kernels instead of CUDA
+# - CXX=hipcc: required by setup.py for HIP compilation
+# - --no-build-isolation: use the ROCm torch installed by vLLM
+# - vLLM ROCm wheels from vllm.ai index (dynamic ROCM_TAG)
+# - Skip flashinfer (CUDA-only)
+RUN --mount=type=cache,target=/root/.cache/ccache,id=ccache \
+    --mount=type=cache,target=/root/.cache/uv,id=uv-cache,sharing=locked \
+    . /opt/venv/bin/activate && \
+    ROCM_TAG=rocm$(echo ${ROCM_VERSION} | tr -d '.') && \
+    if [ "$VLLM_VERSION" = "nightly" ]; then \
+        uv pip install --prerelease=allow \
+            'vllm[runai,tensorizer]' \
+            --extra-index-url https://wheels.vllm.ai/nightly/${ROCM_TAG} \
+            --index-strategy unsafe-best-match ; \
+    else \
+        uv pip install --prerelease=allow \
+            "vllm[runai,tensorizer]==${VLLM_VERSION}" \
+            --extra-index-url https://wheels.vllm.ai/${ROCM_TAG} \
+            --index-strategy unsafe-best-match ; \
+    fi && \
+    python3 -c 'import torch; print("TORCH=", torch.__version__, "HIP=", torch.version.hip)' && \
+    BUILD_WITH_HIP=1 CXX=hipcc python3 setup.py bdist_wheel --dist-dir=dist_lmcache && \
+    uv pip install ./dist_lmcache/*.whl --verbose
+
+WORKDIR /workspace
+ENTRYPOINT ["/opt/venv/bin/vllm", "serve"]
+
+#################### vLLM-ROCm & LMCache (Release) #######################
+
+FROM base AS image-release
+
+ARG ROCM_VERSION
+
+# Install vLLM-ROCm and build LMCache from source with HIP extensions.
+# PyPI lmcache>=0.4 ships only binary wheels (no sdist), so --no-binary
+# cannot force a source build.  Cloning from git ensures HIP extensions
+# are compiled against the ROCm torch installed by vLLM.
+# Build deps are installed from the cloned source's requirements/build.txt
+# to avoid version mismatches with a local COPY.
+ARG max_jobs=2
+ENV MAX_JOBS=${max_jobs}
+
+ARG LMCACHE_RELEASE_VERSION=dev
+RUN . /opt/venv/bin/activate && \
+    ROCM_TAG=rocm$(echo ${ROCM_VERSION} | tr -d '.') && \
+    uv pip install --prerelease=allow 'vllm[runai,tensorizer]' \
+        --extra-index-url https://wheels.vllm.ai/${ROCM_TAG} \
+        --index-strategy unsafe-best-match && \
+    git clone --depth 1 -b ${LMCACHE_RELEASE_VERSION} \
+        https://github.com/LMCache/LMCache.git /tmp/lmcache && \
+    cd /tmp/lmcache && \
+    uv pip install -r requirements/build.txt && \
+    BUILD_WITH_HIP=1 CXX=hipcc uv pip install --no-build-isolation . --verbose && \
+    rm -rf /tmp/lmcache
+
+WORKDIR /workspace
+ENTRYPOINT ["/opt/venv/bin/vllm", "serve"]
diff --git a/docker/Dockerfile.rocm-lightweight b/docker/Dockerfile.rocm-lightweight
new file mode 100644
index 0000000..fa09271
--- /dev/null
+++ b/docker/Dockerfile.rocm-lightweight
@@ -0,0 +1,43 @@
+# Lightweight ROCm image: latest LMCache release on top of vLLM-ROCm.
+# No NIXL, no Prefill-Decode Disaggregation.
+# For AMD Instinct GPUs (MI300X/MI325X, MI350X/MI355X).
+#
+# Note: lmcache is built from source with HIP extensions using
+# --no-build-isolation to link against the ROCm torch in the base image.
+FROM vllm/vllm-openai-rocm:latest
+
+# ROCm GPU architectures — required during build (no GPU present)
+ARG PYTORCH_ROCM_ARCH="gfx942,gfx950"
+ENV PYTORCH_ROCM_ARCH=${PYTORCH_ROCM_ARCH}
+
+# Build LMCache from source with HIP extensions.
+# PyPI lmcache>=0.4 ships only binary wheels (no sdist), so `--no-binary`
+# cannot force a source build.  Cloning the repo ensures HIP extensions
+# are compiled against the ROCm torch already present in the base image.
+# Build deps are installed from the cloned source to stay version-consistent.
+ARG max_jobs=2
+ENV MAX_JOBS=${max_jobs}
+
+ARG LMCACHE_VERSION=dev
+RUN git clone --depth 1 -b ${LMCACHE_VERSION} https://github.com/LMCache/LMCache.git /tmp/lmcache && \
+    cd /tmp/lmcache && \
+    uv pip install --system --no-cache -r requirements/build.txt && \
+    BUILD_WITH_HIP=1 CXX=hipcc \
+    uv pip install --system --no-cache --no-build-isolation . && \
+    rm -rf /tmp/lmcache
+
+
+# Build (no repo context needed — everything is cloned from git):
+# docker build -f docker/Dockerfile.rocm-lightweight -t 'lmcache/vllm-openai-rocm:light' docker/
+
+# Run:
+# export HF_TOKEN=<your_huggingface_token>
+# docker run --device /dev/kfd --device /dev/dri --group-add video \
+#    -v ~/.cache/huggingface:/root/.cache/huggingface \
+#    --env "HF_TOKEN=$HF_TOKEN" \
+#    -p 8000:8000 \
+#    --ipc=host \
+#    lmcache/vllm-openai-rocm:light \
+#    --model Qwen/Qwen3-0.6B \
+#    --kv-transfer-config \
+#    '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
diff --git a/docker/Dockerfile.standalone b/docker/Dockerfile.standalone
new file mode 100644
index 0000000..5899b0d
--- /dev/null
+++ b/docker/Dockerfile.standalone
@@ -0,0 +1,151 @@
+# The LMCache Standalone Dockerfile is used to build a LMCache image
+# without vLLM integration.
+
+ARG CUDA_VERSION=13.0
+ARG UBUNTU_VERSION=24.04
+ARG NGC_VERSION=25.09
+ARG BASE_IMAGE=nvcr.io/nvidia/cuda-dl-base:${NGC_VERSION}-cuda${CUDA_VERSION}-devel-ubuntu${UBUNTU_VERSION}
+# Override to a stable version for releases.
+ARG VLLM_VERSION=nightly
+
+#################### BASE BUILD IMAGE ####################
+# Prepare basic build environment
+
+FROM ${BASE_IMAGE} AS base
+
+ARG CUDA_VERSION
+ARG PYTHON_VERSION=3.12
+ARG UBUNTU_VERSION
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PATH="/opt/venv/bin:${PATH}"
+
+# Install Python and other dependencies
+RUN echo 'tzdata tzdata/Areas select America' | debconf-set-selections \
+    && echo 'tzdata tzdata/Zones/America select Los_Angeles' | debconf-set-selections \
+    && apt-get update -y \
+    && apt-get install -y --no-install-recommends \
+        ccache software-properties-common git curl sudo \
+        python3 python3-dev python3-venv tzdata \
+    && rm -rf /var/lib/apt/lists/* \
+    && ldconfig /usr/local/cuda-$(echo $CUDA_VERSION | cut -d. -f1,2)/compat/ \
+    && curl -LsSf https://astral.sh/uv/install.sh | sh \
+    && mv ~/.local/bin/uv /usr/local/bin/ \
+    && mv ~/.local/bin/uvx /usr/local/bin/ \
+    && uv venv /opt/venv \
+    && . /opt/venv/bin/activate \
+    && python3 --version
+
+WORKDIR /workspace
+
+# Install small non-torch runtime dependencies; torch is installed in lmcache-build
+# against the exact CUDA version so the compiled C extensions match at runtime.
+# The CLI requirements (e.g. ``openai`` for the bench client) are also installed
+# here so ``lmcache`` subcommand discovery in ``lmcache.cli.commands`` -- which
+# eagerly imports every command module -- does not crash with
+# ``ModuleNotFoundError: No module named 'openai'`` when the standalone image
+# boots ``lmcache server``. See LMCache#3353.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=requirements/cli.txt,target=/tmp/cli.txt \
+    . /opt/venv/bin/activate && \
+    uv pip install ray nvidia-ml-py -r /tmp/cli.txt
+
+# CUDA arch list used by torch
+ARG torch_cuda_arch_list='7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX'
+ENV TORCH_CUDA_ARCH_LIST=${torch_cuda_arch_list}
+
+#################### TORCH RESOLVER ##########################
+# Resolve the torch version vLLM uses for this CUDA tag into /torch.pin.
+# vLLM is not installed; only the pin is consumed by downstream stages.
+
+FROM base AS torch-resolver
+
+ARG CUDA_VERSION
+ARG VLLM_VERSION
+
+RUN --mount=type=cache,target=/root/.cache/uv,id=uv-resolver \
+    . /opt/venv/bin/activate && \
+    CUDA_TAG=cu$(echo ${CUDA_VERSION} | tr -d '.') && \
+    if [ "$VLLM_VERSION" = "nightly" ]; then \
+        echo "vllm" > /tmp/req.in && \
+        uv pip compile /tmp/req.in --quiet --prerelease=allow \
+            --extra-index-url https://wheels.vllm.ai/nightly/${CUDA_TAG} \
+            --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+            --index-strategy unsafe-best-match \
+            > /tmp/resolved.txt ; \
+    else \
+        echo "vllm==${VLLM_VERSION}" > /tmp/req.in && \
+        uv pip compile /tmp/req.in --quiet --prerelease=allow \
+            --extra-index-url https://download.pytorch.org/whl/${CUDA_TAG} \
+            > /tmp/resolved.txt ; \
+    fi && \
+    grep -E '^torch==' /tmp/resolved.txt > /torch.pin && \
+    echo "Resolved torch pin (matches vllm ${VLLM_VERSION} on ${CUDA_TAG}):" && \
+    cat /torch.pin
+
+#################### LMCache Build ##########################
+# Build LMCache wheel
+
+FROM base AS lmcache-build
+
+ARG CUDA_VERSION
+
+# install build dependencies
+COPY ./requirements/build.txt build.txt
+COPY --from=torch-resolver /torch.pin /torch.pin
+
+# Max jobs used by Ninja to build extensions
+ARG max_jobs=2
+ENV MAX_JOBS=${max_jobs}
+
+# Number of threads used by nvcc
+ARG nvcc_threads=8
+ENV NVCC_THREADS=$nvcc_threads
+
+# --index-url (singular) keeps PyPI out of torch resolution so uv can't
+# pick PyPI's default cu13 wheel on a cu12.9 host.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    . /opt/venv/bin/activate && \
+    CUDA_TAG=cu$(echo ${CUDA_VERSION} | tr -d '.') && \
+    uv pip install -r /torch.pin \
+        --index-url https://download.pytorch.org/whl/${CUDA_TAG} && \
+    uv pip install -r build.txt
+
+ARG LMCACHE_COMMIT_ID=1
+
+COPY . /workspace/LMCache
+WORKDIR /workspace/LMCache
+
+# Build LMCache wheel (don't install yet)
+RUN --mount=type=cache,target=/root/.cache/ccache,id=ccache \
+    --mount=type=cache,target=/root/.cache/uv,id=uv-cache,sharing=locked \
+    . /opt/venv/bin/activate && \
+    export LMCACHE_CUDA_MAJOR=$(echo ${CUDA_VERSION} | cut -d. -f1) && \
+    python3 -c 'import torch; print("TORCH=", torch.__version__)' && \
+    python3 setup.py bdist_wheel --dist-dir=dist_lmcache
+
+#################### LMCache Final Image ##########################
+# Clean install of LMCache from wheel
+
+FROM base AS lmcache-final
+
+ARG CUDA_VERSION
+
+# Copy the built wheel from build stage
+COPY --from=lmcache-build /workspace/LMCache/dist_lmcache/*.whl /tmp/
+COPY --from=torch-resolver /torch.pin /torch.pin
+
+# Install torch from the CUDA index first; the wheel's torch dep is then
+# already satisfied, so uv won't re-resolve it against PyPI default cu13.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    . /opt/venv/bin/activate && \
+    CUDA_TAG=cu$(echo ${CUDA_VERSION} | tr -d '.') && \
+    uv pip install -r /torch.pin \
+        --index-url https://download.pytorch.org/whl/${CUDA_TAG} && \
+    uv pip install /tmp/*.whl --verbose && \
+    rm -rf /tmp/*.whl /torch.pin
+
+WORKDIR /workspace
+
+# Default shell entrypoint (no vLLM server)
+CMD ["/bin/bash"]
+
diff --git a/docker/Dockerfile.xpu b/docker/Dockerfile.xpu
new file mode 100644
index 0000000..95bf288
--- /dev/null
+++ b/docker/Dockerfile.xpu
@@ -0,0 +1,124 @@
+# The LMCache XPU Dockerfile layers LMCache on top of a prebuilt vLLM XPU
+# runtime image so we can test LMCache + vLLM OpenAI server without rebuilding
+# vLLM, UCX/NIXL, or oneCCL (all already provided by the base image).
+
+# vLLM: 0.21.0+xpu, UCX: 1.21.0, NIXL: 0.7.0, oneCCL: 2021.15
+ARG BASE_IMAGE=public.ecr.aws/q9t5s3a7/vllm-ci-test-repo
+ARG BASE_IMAGE_TAG=ad7125a431e176d4161099480a66f0169609a690-xpu
+
+# Optional proxy args (pass via --build-arg)
+ARG http_proxy
+ARG https_proxy
+ARG no_proxy
+
+#################### BASE RUNTIME IMAGE ####################
+
+FROM ${BASE_IMAGE}:${BASE_IMAGE_TAG} AS base
+
+ARG http_proxy
+ARG https_proxy
+ARG no_proxy
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV VIRTUAL_ENV=/opt/venv
+ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
+ENV UV_HTTP_TIMEOUT=500
+ENV http_proxy=${http_proxy}
+ENV https_proxy=${https_proxy}
+ENV no_proxy=${no_proxy}
+
+WORKDIR /workspace
+
+#################### LMCache (Build, XPU) ####################
+
+FROM base AS image-build
+
+ARG LMCACHE_COMMIT_ID=1
+# Set UPDATE_NIXL=1 to rebuild UCX/NIXL from source in this Dockerfile.
+ARG UPDATE_NIXL=0
+ARG UCX_VERSION=v1.21.0-rc2
+ARG NIXL_VERSION=0.10.1
+
+ENV VLLM_TARGET_DEVICE=xpu
+ENV VLLM_WORKER_MULTIPROC_METHOD=spawn
+# Rebuilt UCX (when enabled) is installed here.
+ENV LD_LIBRARY_PATH=/tmp/ucx_install/lib:${LD_LIBRARY_PATH}
+
+# Optional UCX/NIXL rebuild path (disabled by default).
+# 1) build UCX + NIXL wheel, 2) install RDMA runtime libs, 3) install local NIXL wheel.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ "${UPDATE_NIXL}" = "1" ]; then \
+      apt-get update -y && apt-get install -y --no-install-recommends \
+        build-essential autoconf automake libtool pkg-config \
+        libibverbs-dev librdmacm-dev && \
+      rm -rf /var/lib/apt/lists/* && \
+      git clone https://github.com/openucx/ucx /tmp/ucx_source && \
+      cd /tmp/ucx_source && git checkout "${UCX_VERSION}" && \
+      bash autogen.sh && \
+      ./configure --prefix=/tmp/ucx_install --with-ze=yes --enable-examples --enable-mt && \
+      make CFLAGS="-Wno-error=incompatible-pointer-types" -j8 && make install && \
+      git clone https://github.com/ai-dynamo/nixl /tmp/nixl_source && \
+      cd /tmp/nixl_source && git checkout "${NIXL_VERSION}" && \
+      uv pip install --upgrade meson pybind11 patchelf && \
+      uv pip install -r requirements.txt && \
+      PKG_CONFIG_PATH=/tmp/ucx_install/lib/pkgconfig \
+      LD_LIBRARY_PATH=/tmp/ucx_install/lib \
+      python -m pip wheel --no-deps . -w /tmp/nixl_wheels/ && \
+      find /tmp/ucx_install -type f \( -name '*.a' -o -name '*.la' \) -delete && \
+      rm -rf /tmp/ucx_install/include /tmp/ucx_install/share /tmp/ucx_install/etc /tmp/ucx_install/lib/cmake /tmp/ucx_install/bin && \
+      cd /workspace && \
+      rm -rf /tmp/ucx_source /tmp/nixl_source && \
+      apt-get update -y && apt-get install -y --no-install-recommends \
+        rdma-core libibverbs1 librdmacm1 libibumad3 libibmad5 \
+        libmlx5-1 libmlx4-1 ibverbs-providers librdmacm1t64 && \
+      rm -rf /var/lib/apt/lists/* && \
+      uv pip install --no-deps /tmp/nixl_wheels/nixl*.whl && \
+      uv pip install nixl==${NIXL_VERSION} && \
+      rm -rf /tmp/nixl_wheels; \
+    else \
+      echo "Skipping UCX/NIXL rebuild (UPDATE_NIXL=${UPDATE_NIXL})"; \
+    fi
+
+COPY ./requirements/build.txt /workspace/build.txt
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv pip install -r /workspace/build.txt
+
+COPY . /workspace/LMCache
+WORKDIR /workspace/LMCache
+
+RUN --mount=type=cache,target=/root/.cache/uv,id=uv-cache,sharing=locked \
+    python3 -c 'import torch; print("TORCH=", torch.__version__)' && \
+    BUILD_WITH_SYCL=1 python setup.py bdist_wheel --dist-dir=dist_lmcache && \
+    uv pip install ./dist_lmcache/*.whl --verbose && \
+    BUILD_WITH_SYCL=1 python setup.py build_ext --inplace
+
+WORKDIR /workspace
+ENTRYPOINT ["vllm", "serve"]
+
+
+# Build:
+# docker build -f docker/Dockerfile.xpu -t lmcache-xpu:latest \
+#   --progress=plain \
+#   --build-arg UPDATE_NIXL=1 \
+#   --build-arg BASE_IMAGE=public.ecr.aws/q9t5s3a7/vllm-ci-test-repo \
+#   --build-arg BASE_IMAGE_TAG=ad7125a431e176d4161099480a66f0169609a690-xpu \
+#   --build-arg http_proxy=<proxy> \
+#   --build-arg https_proxy=<proxy> \
+#   --build-arg no_proxy=localhost,127.0.0.1 \
+#   .
+
+# Run:
+# docker run --device /dev/dri  \
+#  --ipc=host \
+#  --shm-size=16g \
+#   -p 8001:8000 \
+#   -e ZE_AFFINITY_MASK=1 \
+#   -e HF_ENDPOINT=https://hf-mirror.com \
+#   -e HF_TOKEN=<hf-token > \
+#   -e http_proxy=<proxy> \
+#   -e https_proxy=<proxy> \
+#   lmcache-xpu:latest \
+#   Qwen/Qwen3-0.6B \
+#   --kv-transfer-config \
+#   '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 0000000..819283b
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,225 @@
+# LMCache Docker Images
+
+This directory contains Dockerfiles for building different LMCache images. Each Dockerfile serves a specific use case depending on your needs.
+
+## Available Dockerfiles
+
+### 1. `Dockerfile` - Full Integration with vLLM
+
+**Image**: `lmcache/vllm-openai:latest`
+
+**Description**: The main Dockerfile that builds LMCache from source and integrates it with vLLM OpenAI server. This is the recommended image for production deployments with full feature support including Prefill-Decode Disaggregation (PD).
+
+**Features**:
+- ✅ LMCache built from source
+- ✅ vLLM integration (nightly or stable)
+- ✅ Full NIXL support for Prefill-Decode Disaggregation
+- ✅ CUDA support
+- ✅ Optimized multi-stage build
+
+**Build Targets**:
+- `image-build`: Builds with vLLM nightly and LMCache from source
+- `image-release`: Uses stable vLLM release and LMCache from PyPI
+- `image-release-cu129`: Uses nightly cu12.9 vLLM and LMCache from the cu12.9 GitHub Release
+
+**Usage**:
+
+```bash
+# Build with nightly vLLM
+docker build \
+  --build-arg CUDA_VERSION=13.0 \
+  --build-arg UBUNTU_VERSION=24.04 \
+  --target image-build \
+  --tag lmcache/vllm-openai:latest \
+  --file docker/Dockerfile .
+
+# Build with stable releases
+docker build \
+  --build-arg CUDA_VERSION=13.0 \
+  --build-arg UBUNTU_VERSION=24.04 \
+  --target image-release \
+  --tag lmcache/vllm-openai:latest \
+  --file docker/Dockerfile .
+
+# Build with cu12.9 release packages
+docker build \
+  --build-arg CUDA_VERSION=12.9 \
+  --build-arg UBUNTU_VERSION=24.04 \
+  --build-arg LMCACHE_VERSION=<version> \
+  --target image-release-cu129 \
+  --tag lmcache/vllm-openai:cu129 \
+  --file docker/Dockerfile .
+```
+
+**Run Example**:
+
+```bash
+export HF_TOKEN=<your_huggingface_token>
+
+docker run --runtime nvidia --gpus all \
+  -v ~/.cache/huggingface:/root/.cache/huggingface \
+  -p 8000:8000 \
+  --ipc=host \
+  lmcache/vllm-openai:latest \
+  Qwen/Qwen3-0.6B \
+  --kv-transfer-config \
+  '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+```
+
+---
+
+### 2. `Dockerfile.standalone` - LMCache Only
+
+**Image**: `lmcache/standalone:latest`
+
+**Description**: A standalone Docker image that builds and installs LMCache from source without vLLM. This will be useful when running LMCache in the standalone mode.
+
+**Features**:
+- ✅ LMCache built from source
+- ✅ No vLLM dependency
+- ✅ CUDA support
+
+**Build Target**:
+- `lmcache-final`: Final optimized image with LMCache installed
+
+**Usage**:
+
+```bash
+docker build \
+  --build-arg CUDA_VERSION=13.0 \
+  --build-arg UBUNTU_VERSION=24.04 \
+  --target lmcache-final \
+  --tag lmcache/standalone:latest \
+  --file docker/Dockerfile.standalone .
+```
+
+**Run Example**:
+
+```bash
+# Start the LMCache server
+docker run --runtime nvidia --gpus all -it \
+  lmcache/standalone:latest \
+  /opt/venv/bin/lmcache server \
+  --l1-size-gb 60 \
+  --eviction-policy LRU \
+  --max-workers 4 \
+  --max-gpu-workers 2 \
+  --port 6555
+```
+
+---
+
+### 3. `Dockerfile.lightweight` - Quick Setup
+
+**Image**: `lmcache/vllm-openai:lightweight`
+
+**Description**: A lightweight image that extends the official vLLM image and installs LMCache from PyPI. This is the fastest way to get started but does not include NIXL support.
+
+**Features**:
+- ✅ Based on official `vllm/vllm-openai:latest` image
+- ✅ LMCache installed from PyPI (latest release)
+- ✅ Quick build time
+- ✅ Small image size
+- ❌ No NIXL support (no Prefill-Decode Disaggregation)
+
+**Limitations**:
+- Cannot use Prefill-Decode Disaggregation features
+
+**Usage**:
+
+```bash
+docker build \
+  --tag lmcache/vllm-openai:lightweight \
+  --file docker/Dockerfile.lightweight .
+```
+
+**Run Example**:
+
+```bash
+export HF_TOKEN=<your_huggingface_token>
+
+docker run --runtime nvidia --gpus all \
+  -v ~/.cache/huggingface:/root/.cache/huggingface \
+  --env "HF_TOKEN=$HF_TOKEN" \
+  -p 8000:8000 \
+  --ipc=host \
+  lmcache/vllm-openai:lightweight \
+  Qwen/Qwen3-0.6B \
+  --kv-transfer-config \
+  '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+```
+
+---
+
+## Which Dockerfile Should I Use?
+
+### Use `Dockerfile` if you:
+- Need full LMCache + vLLM integration
+- Want Prefill-Decode Disaggregation support
+- Are deploying to production
+- Need the latest features built from source
+
+### Use `Dockerfile.standalone` if you:
+- Want LMCache without vLLM
+- Need a clean LMCache installation for development
+- Want to integrate LMCache with custom tools
+
+### Use `Dockerfile.lightweight` if you:
+- Prefer stable releases from PyPI
+- Need fast build times
+
+---
+
+## CUDA Build Arguments
+
+`Dockerfile` and `Dockerfile.standalone` support the following build arguments:
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `CUDA_VERSION` | `13.0` | CUDA version to use |
+| `UBUNTU_VERSION` | `24.04` | Ubuntu base version |
+| `PYTHON_VERSION` | `3.12` | Python version |
+| `max_jobs` | `2` | Max parallel jobs for build |
+| `nvcc_threads` | `8` | Number of nvcc threads |
+| `torch_cuda_arch_list` | `7.5 8.0 8.6 8.9 9.0 10.0 12.0+PTX` | CUDA architectures |
+
+`Dockerfile.lightweight` does not define build arguments. ROCm images use ROCm-specific arguments such as `ROCM_VERSION` and `PYTORCH_ROCM_ARCH`.
+
+**Example with custom arguments**:
+
+```bash
+docker build \
+  --build-arg CUDA_VERSION=12.4 \
+  --build-arg max_jobs=4 \
+  --build-arg nvcc_threads=16 \
+  --target image-build \
+  --tag lmcache/vllm-openai:cuda12.4 \
+  --file docker/Dockerfile .
+```
+
+---
+
+## Published Images
+
+Pre-built images are available on Docker Hub:
+
+- `lmcache/vllm-openai:latest` - Latest stable release with vLLM
+- `lmcache/vllm-openai:{version}` - Specific version (e.g., `v0.1.0`)
+- `lmcache/vllm-openai:lightweight` - Lightweight version
+- `lmcache/standalone:latest` - Latest standalone release
+- `lmcache/standalone:{version}` - Specific standalone version
+
+```bash
+# Pull pre-built images
+docker pull lmcache/vllm-openai:latest
+docker pull lmcache/standalone:latest
+```
+
+---
+
+## Additional Resources
+
+- [LMCache Documentation](https://docs.lmcache.ai/)
+- [vLLM Documentation](https://docs.vllm.ai/)
+- [Installation Guide](https://docs.lmcache.ai/getting_started/installation.html)
+- [Docker Deployment Guide](https://docs.lmcache.ai/production/docker_deployment.html)
diff --git a/docker/example_build.sh b/docker/example_build.sh
new file mode 100644
index 0000000..10cbdc7
--- /dev/null
+++ b/docker/example_build.sh
@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Example script to build the LMCache integrated with vLLM container image
+
+# Update the following variables accordingly
+CUDA_VERSION=13.0
+DOCKERFILE_NAME='Dockerfile'
+# Set VLLM_VERSION to a specific version before running this script,
+# e.g.: VLLM_VERSION=0.9.1 ./example_build.sh
+# Defaults to "nightly" if not set.
+VLLM_VERSION="${VLLM_VERSION:-nightly}"
+DOCKER_BUILD_PATH='../' # This path should point to the LMCache root for access to 'requirements' directory
+UBUNTU_VERSION=24.04
+
+# `image-build` target will use the latest LMCache and vLLM code
+# Change to 'image-release' target for using release package versions of vLLM and LMCache
+BUILD_TARGET=image-build 
+
+IMAGE_TAG='lmcache/vllm-openai:build-latest' # Name of container image to build
+
+docker build \
+    --build-arg CUDA_VERSION=$CUDA_VERSION \
+    --build-arg UBUNTU_VERSION=$UBUNTU_VERSION \
+    --build-arg VLLM_VERSION=$VLLM_VERSION \
+    --target $BUILD_TARGET --file $DOCKERFILE_NAME \
+    --tag $IMAGE_TAG  $DOCKER_BUILD_PATH
diff --git a/docker/example_run.sh b/docker/example_run.sh
new file mode 100644
index 0000000..f51d1b8
--- /dev/null
+++ b/docker/example_run.sh
@@ -0,0 +1,21 @@
+# Example script to run the container vLLM OpenAI server with LMCache
+#
+# Prerequisite:
+# - If CUDA then require NVIDIA Container Toolkit:
+# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
+
+# Set the following variables:
+IMAGE=<IMAGE_NAME>:<TAG>
+HF_MODEL_NAME='meta-llama/Llama-3.1-8B-Instruct'
+RUNTIME=nvidia
+
+docker run --runtime $RUNTIME --gpus all \
+    --env "HF_TOKEN=<REPLACE_WITH_YOUR_HF_TOKEN>" \
+    --env "LMCACHE_CHUNK_SIZE=256" \
+    --env "LMCACHE_LOCAL_CPU=True" \
+    --env "LMCACHE_MAX_LOCAL_CPU_SIZE=5" \
+    --volume ~/.cache/huggingface:/root/.cache/huggingface \
+    --network host \
+    $IMAGE \
+    $HF_MODEL_NAME --kv-transfer-config \
+    '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d0c3cbf
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..d81f16f
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1 @@
+Check out the [online doc](https://docs.lmcache.ai/developer_guide/contributing.html#building-the-docs) on how to build docs locally.
diff --git a/docs/coding_standards.md b/docs/coding_standards.md
new file mode 100644
index 0000000..7c10a7b
--- /dev/null
+++ b/docs/coding_standards.md
@@ -0,0 +1,376 @@
+# LMCache Code Quality and Review Standard
+
+This document defines the coding quality standards and code review expectations for the LMCache project. All contributors (human and AI) should follow these standards. Reviewers should use this as the authoritative reference when reviewing PRs.
+
+> **Source of truth**: This file is the canonical reference. `AGENTS.md` contains the
+> quick-reference checklist; `CLAUDE.md` and `.gemini/styleguide.md` point here for details.
+
+---
+
+## 1. General Rules
+
+### 1.1 PR Scope and Breakdown
+
+- **PRs must be small and focused.** If the number of changed files is large, break it down conceptually into multiple PRs. Each PR should do one thing well.
+- Prefer a series of small, reviewable PRs over one large omnibus PR.
+- If a feature spans multiple modules, split by module boundary or by logical phase (e.g., interface change first, then implementation, then tests).
+
+### 1.2 Documentation Requirements
+
+- **User docs** (`docs/source/`) and **design docs** (`docs/design/`) must be updated whenever there are user-facing changes or new functionalities.
+- **Docstrings** must be updated whenever there are changes to existing functions, methods, or class fields.
+- If there are documents specifying schemas of arguments or return values, update them as well.
+- **Code owners** must be updated if ownership changes. Reviewers should remind PR authors.
+
+### 1.3 License Header
+
+All Python files must have `# SPDX-License-Identifier: Apache-2.0` as the first line.
+
+---
+
+## 2. Typing
+
+### 2.1 Strong Typing is Enforced
+
+- All functions and methods must have type hints for arguments and return values.
+- **Avoid `Any`**. If the type is not clear, redesign the interface until it is.
+- Generic containers must be fully typed:
+  - Use `list[SomeType]`, not bare `list`.
+  - Use `dict[KeyType, ValueType]`, not bare `dict`.
+  - Use `tuple[int, str]` or `tuple[int, ...]`, not bare `tuple`.
+- **Avoid `Optional`**. Prefer always initializing objects (even if empty/unused) over wrapping in `Optional`. If a value can genuinely be absent, use `X | None` syntax rather than `Optional[X]`.
+
+### 2.2 Runtime Validation
+
+- **Never use `assert` for runtime-dependent checks** (e.g., config validation, input validation). Assertions are stripped by `python -O`. Use explicit `if ...: raise ValueError(...)` instead.
+- Only use `assert` for development-time invariant checks that indicate programmer errors.
+
+---
+
+## 3. Docstrings
+
+### 3.1 When Docstrings Are Required
+
+| Scope | Requirement |
+|-------|-------------|
+| Public functions and methods | Full docstring (always required) |
+| Module-level / global helper functions | Full docstring |
+| Long private helper functions | Full docstring |
+| Short, clear class-private helpers | Short docstring acceptable |
+| Override methods with no new behavior | Short docstring acceptable |
+
+### 3.2 Full Docstring Format
+
+A full docstring must include:
+
+1. **Summary**: A clear one-sentence description of what the function does.
+2. **Details** (when needed): A few more sentences covering:
+   - Thread safety guarantees or requirements
+   - Assumptions about the caller/callee
+   - Important invariants
+3. **Args**: Detailed description of every argument, including:
+   - Type and purpose
+   - Assumptions or constraints (e.g., "length of `keys` must equal length of `values`")
+4. **Returns**: Detailed description of the return value.
+5. **Raises**: All exceptions the function may raise.
+6. **Note** (when needed): Important assumptions or caveats that developers should be aware of.
+
+### 3.3 Docstring Accuracy
+
+- Docstrings must match the function's **actual current behavior**, not planned future behavior.
+- When modifying a function, always update the docstring to reflect the change.
+- If a parameter is currently a no-op (accepted but not yet used), the docstring must say so explicitly. Do not describe behavior that is not yet implemented.
+
+---
+
+## 4. Function and Interface Design
+
+### 4.1 Naming
+
+- Function names must be **self-explanatory**. A developer should understand the behavior without reading the implementation.
+- Parameter names should imply semantics. For predicates/filters, name them to indicate what `True`/`False` means (e.g., `key_eligible_filter` rather than just `filter`).
+- Variable naming must be consistent across files and modules.
+- Private methods and private members start with `_`.
+
+### 4.2 Self-Contained Functions
+
+- Functions should be self-contained. If a function's input is expected to come from another specific function (or its output is expected to feed into another), this must be **documented explicitly** in the docstring.
+
+### 4.3 Parameter and Return Value Design
+
+- **Avoid ambiguity in return values.** For example, returning `None` for both "process not finished" and "request not found" makes it impossible for the caller to distinguish. Use distinct return types or raise exceptions.
+- **Document schemas** if the parameter or return value includes `dict` or complex containers. Specify the expected keys, value types, and semantics.
+- **Avoid boolean parameters.** They make call sites unreadable. Prefer:
+  - Breaking into two separate functions, or
+  - Using an `enum` to make intent explicit.
+- **Clarify caller assumptions** in the docstring (e.g., "caller must hold the lock", "must be called from the main thread").
+
+### 4.4 Class Design
+
+- **Minimize the public interface.** Follow the principle of minimal surface area -- only add a new public method or property when there is a concrete need.
+- **Class fields with internal state** must have:
+  - A clear, documented meaning
+  - A clear invariant (at any point in time, a developer should know what the value should be without running the code)
+  - A docstring or inline comment explaining it
+- **Private members must never be directly accessed by other classes.** Interact only through public APIs. This is enforced by CI in `lmcache/v1/multiprocess/` and `lmcache/v1/distributed/`, but applies project-wide.
+- Prefer `@property` that derives from existing data over storing redundant fields.
+
+### 4.5 Config and Dispatch
+
+- Use `isinstance()` on config objects to determine behavior, not string-based type names.
+- Config classes should follow existing conventions (e.g., `@dataclass`). Controllers and managers should always be created (even with empty/default config), never wrapped in `Optional`.
+
+---
+
+## 5. New Functionality
+
+### 5.1 Design Documentation
+
+- **A design doc is required** for non-trivial new features or architectural changes.
+- **`docs/design/` mirrors the `lmcache/` package tree.** A design doc for code at
+  `lmcache/<path>/` lives at `docs/design/<path>/`. For example, design docs for
+  `lmcache/v1/distributed/l2_adapters/` go under
+  `docs/design/v1/distributed/l2_adapters/`. A doc that spans several sibling
+  submodules belongs at their common parent directory.
+- Use descriptive file names (e.g., `overall.md`, `l2_eviction.md`, `query-command.md`)
+  rather than mirroring module file names. See `docs/design/README.md` for the full
+  convention.
+- User-facing READMEs (`README.md` in module directories) stay next to the code and
+  are symlinked from the corresponding `docs/design/<path>/` location — do not move
+  them.
+
+### 5.2 Testing
+
+- All new features must include corresponding unit tests.
+- All bug fixes must include regression tests.
+- Tests must:
+  - Verify the **public interface and docstring contract**, not implementation details.
+  - Be written as if the function's implementation is unknown.
+  - **Not access private members** (`_`-prefixed) of the class under test.
+  - Not test private helper functions directly. Exercise them through the public API.
+- Test files should mirror the source structure under `tests/`.
+
+### 5.3 Reuse Existing Code
+
+- When adding or updating functions, variables, or logic, check whether there is existing code that can be reused or existing state that can be exported instead of duplicating.
+
+---
+
+## 6. Modification to Existing Code
+
+### 6.1 Documentation and Schema Updates
+
+- **Must update docstrings** for any modified functions or fields.
+- **Should update** user docs and design docs if the change affects behavior or APIs.
+- Update schema documents if argument or return value structures change.
+- Check for existing reusable code before introducing new helpers or utilities.
+
+### 6.2 Caller Impact Analysis (Global View)
+
+Any change to an existing function, class, or module must be evaluated in the
+context of its **callers**, not just the file being edited. A local change that
+looks correct in isolation can silently break unchanged code that depends on the
+prior contract. Authors and reviewers must both take this global view.
+
+**When caller analysis is required:**
+
+- Adding, removing, renaming, or reordering function parameters
+- Changing a parameter's type, default value, or accepted domain (e.g., allowing `None` where it wasn't before, or narrowing an accepted type)
+- Changing the return type, return semantics, or the meaning of sentinel values (e.g., what `None` means)
+- Adding, removing, or changing the exceptions a function raises
+- Changing side effects, ordering guarantees, thread-safety guarantees, or blocking vs. non-blocking behavior
+- Changing invariants of a class field that other classes read via a public accessor
+- Modifying a public method that is part of an interface or base class (subclasses are callers too)
+
+**How to perform the analysis:**
+
+1. **Find every caller** of the changed symbol across the codebase, including:
+   - Non-test production code
+   - Unit tests and integration tests
+   - Documentation snippets and examples
+   - Downstream integrations (e.g., `lmcache/integration/vllm/`)
+2. **For each caller, verify:**
+   - The new signature is compatible (keyword-arg callers are especially sensitive to renames).
+   - Caller assumptions about return values, exceptions, and side effects still hold.
+   - If the caller passes the function's output to another function, that downstream contract still holds.
+3. **Update callers in the same PR** when a breaking change is genuinely required. Do not leave callers broken with the intent to fix them later.
+4. **Prefer backwards-compatible extensions** (new parameter with a default, new optional return field) over breaking changes unless there is a strong reason.
+5. **If the change affects a base class or protocol**, check all implementers, not just direct callers.
+
+**When in doubt, err on the side of reading one more caller.** The cost of
+reading five call sites is small; the cost of a latent bug that ships because no
+one looked is large.
+
+---
+
+## 7. Code Organization and Style
+
+### 7.1 File Structure
+
+- Module-level helper functions go **at the top** of the file (after imports, before classes).
+- Private/helper methods within a class go **at the end** of the class, after all public methods.
+- Code file length should not be too long. If a file is growing large, think about breaking it into smaller modules.
+
+### 7.2 Import Ordering
+
+Imports must follow this section-heading convention:
+
+```python
+# Standard
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+
+# Local
+from .utils import helper
+```
+
+- All imports must be at the top of the file. No lazy imports.
+- Always `import torch` before importing native C extensions (`lmcache.c_ops`, etc.).
+
+### 7.3 Formatting and Linting
+
+```bash
+# Run all checks (mirrors CI)
+pre-commit run --all-files
+
+# Individual tools
+ruff check .              # Lint (E, F, B, SLF rules)
+ruff format .             # Format (line-length 88)
+isort .                   # Import sorting (black profile, from_first=true)
+mypy --config-file=pyproject.toml   # Type checking
+codespell --toml pyproject.toml     # Spell checking
+```
+
+C++/CUDA files use clang-format (Google style, 80-col). Rust code uses `cargo fmt` and `cargo clippy`.
+
+### 7.4 Logging
+
+- Use the project's `init_logger(__name__)` from `lmcache.logging`, not bare `logging.getLogger()`.
+- Operational logs (store/retrieve activity, background task progress) should be at `DEBUG` level, not `INFO`.
+- Log levels must be appropriate: do not use `WARNING` for conditions that are expected during normal concurrent operation (e.g., a key not found due to a benign race condition).
+
+### 7.5 Error Handling
+
+- Replace `assert` with `if/raise` for all runtime validation (see Section 2.2).
+- Error/failure paths must not leave the system in an inconsistent state. Check:
+  - Locks are released
+  - Pool entries are freed
+  - File descriptors are closed
+  - Partial state is cleaned up on failure
+
+### 7.6 Resource Management
+
+- Unbounded collections are memory leaks. If a set or dict grows over time (e.g., tracking seen keys), ensure entries are cleaned up when the corresponding resource is freed.
+- CUDA/GPU resources must be properly managed (allocated, freed, synchronized).
+- No unnecessary memory copies or allocations in hot paths.
+
+---
+
+## 8. Thread Safety
+
+- All shared state access must be protected by appropriate locks.
+- Lock granularity should be appropriate -- not too coarse (blocking unrelated operations) and not too fine (risking missed synchronization).
+- Even test-only or debug methods must hold `self._lock` for thread safety.
+- When code runs under multiple controller threads (e.g., StoreController + PrefetchController), verify that concurrent access is safe.
+- Start with the simplest correct design. Only introduce threading, locks, and queues when there is a concrete need that cannot be met otherwise.
+
+---
+
+## 9. Code Review Process
+
+### 9.1 Review Focus
+
+Reviews should focus on:
+1. **Design decisions and architectural soundness** -- is this the right approach?
+2. **Correctness** -- logic bugs, error handling, resource management, edge cases.
+3. **Caller impact (global view)** -- do the changes break any unchanged callers, tests, or subclasses? (See Section 6.2.)
+4. **Thread safety** -- shared state, lock protocols, concurrent access patterns.
+5. **Code cleanliness and maintainability** -- naming, modularity, readability.
+6. **Documentation** -- docstrings, design docs, user docs.
+7. **Test coverage** -- especially failure paths and concurrent access.
+8. **Design doc compliance** -- does the implementation match documented contracts?
+
+Reviews should **not** focus on:
+- Security-related issues (out of scope for most changes)
+- Trivial style matters already caught by linters
+- Unrelated refactors of unchanged code (only flag unchanged code when it is a **caller of a changed symbol** and the change affects it; do not report unrelated issues in unchanged code)
+
+### 9.2 Severity Levels
+
+| Severity | Meaning | Examples |
+|----------|---------|----------|
+| **error** | Must fix before merge | Missing SPDX header, missing type hints on public function, missing docstring on public function, new feature with zero tests, cross-class private member access, poor architectural decision, ambiguous return values, `assert` used for runtime validation, **breaking change that leaves unchanged callers broken** |
+| **warning** | Should fix | Docstring could be more detailed, tests that test implementation details, naming could be clearer, code could be more modular, missing `strict=True` on `zip` of parallel lists, **caller assumptions weakened without audit** |
+| **info** | Suggestion only, non-blocking | Optional naming improvement, minor refactor for readability, style preference, **backwards-compatible extension where a cleaner API break might be justified** |
+
+### 9.3 Reviewer Guidelines
+
+- Only review lines in the diff. Do not report issues in unchanged code.
+- Do not praise the code. Only report issues or confirm the PR is clean.
+- Do not pad findings. If the PR is clean, say so.
+- Be precise about file paths and line numbers.
+- If unsure whether something is an issue, treat it as `info`, not `error`.
+- Do not leave trivial or nitpick comments that do not affect correctness, maintainability, or readability.
+
+### 9.4 Review Output Format
+
+1. Start with a short summary of what the PR does.
+2. Present **design doc compliance** as a table (requirement | pass/fail | notes) if a relevant design doc exists.
+3. List issues grouped by severity (`error` > `warning` > `info`).
+4. End with a summary table: severity | count | key items.
+
+---
+
+## 10. Quick Reference Checklist
+
+Use this checklist before submitting a PR or during review:
+
+### Correctness
+- [ ] Code does what it claims; matches PR description
+- [ ] Edge cases handled (empty inputs, `None` values, boundary conditions)
+- [ ] Error/failure paths do not leave inconsistent state
+- [ ] No regressions (existing tests still pass)
+
+### Typing and Style
+- [ ] `pre-commit run --all-files` passes
+- [ ] All functions have type hints (arguments + return values)
+- [ ] No use of `Any` or bare generic containers
+- [ ] License header present on all Python files
+- [ ] Import ordering follows section-heading convention
+
+### Documentation
+- [ ] All public functions have complete docstrings
+- [ ] Docstrings match actual behavior
+- [ ] Design docs updated for non-trivial changes
+- [ ] User docs updated for user-facing changes
+
+### Encapsulation and Design
+- [ ] No cross-class private member access
+- [ ] Public APIs minimal and well-defined
+- [ ] Module-level helpers at top; private methods at end of class
+- [ ] No boolean parameters (use enum or split into separate functions)
+- [ ] No ambiguous return values
+
+### Caller Impact (Global View)
+- [ ] All callers of changed signatures still compile/pass type checks
+- [ ] All callers still handle the new return type / new exceptions correctly
+- [ ] Subclasses/implementers of modified base classes or protocols updated
+- [ ] Tests and integration code (`tests/`, `lmcache/integration/`) checked, not just production paths
+
+### Testing
+- [ ] New features have corresponding tests
+- [ ] Bug fixes have regression tests
+- [ ] Tests target public interface, not implementation details
+- [ ] Tests do not access private members
+
+### Safety and Performance
+- [ ] No `assert` for runtime validation (use `if/raise`)
+- [ ] No unbounded collection growth
+- [ ] Thread safety maintained for shared state
+- [ ] No unnecessary memory copies in hot paths
+- [ ] CUDA/GPU resources properly managed
diff --git a/docs/design/ARCHITECTURE_MULTI_HARDWARE.md b/docs/design/ARCHITECTURE_MULTI_HARDWARE.md
new file mode 100644
index 0000000..e33c5e3
--- /dev/null
+++ b/docs/design/ARCHITECTURE_MULTI_HARDWARE.md
@@ -0,0 +1,136 @@
+
+# LMCache Multi-Hardware Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      lmcache/__init__.py                        │
+│                                                                 │
+│  torch_dev, torch_device_type = _detect_device()                │
+│                                                                 │
+│  ┌───────────┐     ┌───────────┐     ┌───────────┐              │
+│  │ torch.cuda│     │ torch.xpu │     │ torch.hpu │  ...         │
+│  └─────┬─────┘     └─────┬─────┘     └─────┬─────┘              │
+│        └──────────────────┴──────────────────┘                  │
+│                           │                                     │
+│                     torch_dev (unified entry)                   │
+│                  torch_device_type ("cuda"/"xpu"/"hpu"/"cpu")   │
+│                                                                 │
+│  [Monkey Patch Point]                                           │
+│  New hardware can be added by extending _detect_device()        │
+│  and providing a gpu_connector implementation.                  │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+              ┌────────────────┼──────────────────┐
+              ▼                ▼                  ▼
+┌──────────────────┐ ┌──────────────┐ ┌──────────────────────────┐
+│ Cache Engine     │ │ Storage      │ │ Multiprocess             │
+│                  │ │ Backends     │ │ Server / Client          │
+│ • store          │ │              │ │                          │
+│ • retrieve       │ │ • LocalCPU   │ │ • IPC futures            │
+│ • lookup         │ │ • Disk       │ │ • message queue          │
+│                  │ │ • Remote     │ │ • blend server           │
+│ torch_dev:       │ │ • PD Backend │ │                          │
+│ .synchronize()   │ │              │ │ torch_dev:               │
+│ .empty_cache()   │ │ torch_dev:   │ │ .device()                │
+│ .set_device()    │ │ .current_    │ │ .stream()                │
+│                  │ │  device()    │ │ .Event()                 │
+│                  │ │ .device_     │ │ .Stream()                │
+│                  │ │  count()     │ │                          │
+│                  │ │              │ │ CUDA-only (hasattr):     │
+│                  │ │              │ │ .Event(interprocess)     │
+│                  │ │              │ │ .from_ipc_handle()       │
+│                  │ │              │ │ .cudart()                │
+└────────┬─────────┘ └──────┬───────┘ └─────────────┬────────────┘
+         │                  │                       │
+         └──────────────────┼───────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Memory Management Layer                      │
+│                                                                 │
+│ ┌──────────────┐  ┌──────────────┐  ┌──────────────┐            │
+│ │ MixedMemory  │  │ PinMemory    │  │ LazyMemory   │            │
+│ │ Allocator    │  │ Allocator    │  │ Allocator    │            │
+│ └──────────────┘  └──────────────┘  └──────────────┘            │
+│ ┌──────────────┐  ┌──────────────┐                              │
+│ │ XPUMemory    │  │ PagedTensor  │   uses torch_dev:            │
+│ │ Allocator    │  │ MemAllocator │   .synchronize()             │
+│ └──────────────┘  └──────────────┘   .cudart() (hasattr)        │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│        GPU Connector Layer (per-hardware, no unification)       │
+│                                                                 │
+│ ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐   │
+│ │ CUDA            │  │ XPU             │  │ HPU             │   │
+│ │                 │  │                 │  │                 │   │
+│ │ • PagedMemV2/V3 │  │ • PagedMemXPUV2 │  │ • PagedMemHPU   │   │
+│ │ • Layerwise     │  │ • LayerwiseXPU  │  │                 │   │
+│ │ • Buffer        │  │                 │  │ torch.hpu.*     │   │
+│ │ • SGLang        │  │ torch.xpu.*     │  │                 │   │
+│ │                 │  │ python_ops_fb   │  │                 │   │
+│ │ torch.cuda.*    │  │                 │  │                 │   │
+│ │ c_ops + cupy    │  │                 │  │                 │   │
+│ └─────────────────┘  └─────────────────┘  └─────────────────┘   │
+│                                                                 │
+│ Route: torch_device_type -> cuda/xpu/hpu -> Connector           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Design Principles
+
+| Layer | Device Reference | Notes |
+|-------|-----------------|-------|
+| **Entry** `__init__.py` | `_detect_device()` -> `torch_dev` | Monkey patch point. Detect once, reuse globally. |
+| **Middle** engine / storage / multiprocess | `from lmcache import torch_dev` | Hardware-agnostic unified code |
+| **Middle** CUDA-only APIs | `hasattr(torch_dev, 'xxx')` guard | Graceful runtime degradation |
+| **Bottom** GPU Connector | Direct `torch.cuda` / `torch.xpu` / `torch.hpu` | Per-hardware impl, no abstraction |
+
+## Connector Routing (`gpu_connector/__init__.py`)
+
+```
+torch_device_type == "cuda"  -->  VLLMPagedMemGPUConnectorV2/V3
+torch_device_type == "xpu"   -->  VLLMPagedMemXPUConnectorV2
+torch_device_type == "hpu"   -->  VLLMPagedMemHPUConnector
+torch_device_type == "cpu"   -->  (no GPU connector; raises RuntimeError)
+```
+
+## CPU-Only Stub Fallback
+
+`_detect_device()` also accepts a CPU-only environment where none of the
+supported accelerators (CUDA, XPU, HPU) is available. In that case
+`torch_device_type` is `"cpu"` and `torch_dev` is either:
+
+- `lmcache.v1.platform.cpu.stub_cpu_device.StubCPUDevice` — when `torch`
+  is importable but no GPU is detected. The stub implements the subset of
+  the `torch.cuda` / `torch.xpu` / `torch.hpu` surface used by the middle
+  layer (`Event`, `Stream`, `device`, `synchronize`, `set_device`,
+  `current_device`, `device_count`, `get_device_properties`,
+  `empty_cache`), as no-op or constant returns. `is_available()` is
+  `False`, so any `hasattr(torch_dev, 'xxx')` consumer that gates on the
+  real device's availability stays on the degraded path.
+- `None` — when `torch` itself is not importable (the `lmcache-cli`
+  slim install). The CLI surface (`lmcache ping`, `lmcache describe`,
+  `lmcache query`, `lmcache bench engine`) tolerates this; engine and
+  storage paths do not.
+
+The stub is intended for L1-adapter-only flows (e.g., end-to-end MP
+server smoke tests on a CPU-only host) and CLI loading without torch. It
+is **not** a CPU connector: there is no entry for `"cpu"` in
+`gpu_connector/__init__.py`, so calling `CreateGPUConnector` with
+`torch_device_type == "cpu"` raises `RuntimeError("No supported cpu
+connector found.")`.
+
+`normalize_kv_and_discover_format` also hardcodes `kv_layout = "HND"`
+when `torch_device_type == "cpu"`, because vLLM's
+`get_kv_cache_layout()` reports `NHD` for its CPU attention backend
+which is wrong for that backend's actual KV cache layout.
+
+## Adding New Hardware
+
+1. Add detection branch in `__init__.py` `_detect_device()`
+2. Create `gpu_connector/xxx_connectors.py`, implement `GPUConnectorInterface`
+3. Add routing branch in `gpu_connector/__init__.py`
+4. Add kernels in `c_ops/` or fallback in `python_ops_fallback.py`
+5. No changes needed in middle layer code
diff --git a/docs/design/README.md b/docs/design/README.md
new file mode 100644
index 0000000..72ae742
--- /dev/null
+++ b/docs/design/README.md
@@ -0,0 +1,33 @@
+# LMCache Design Docs
+
+This directory holds design documents for LMCache modules.
+
+## Layout Convention
+
+**`docs/design/` mirrors the `lmcache/` package tree.**
+
+The design doc(s) for a given module live under the same relative path as the
+module's source. To find design docs for code at `lmcache/<path>/`, look under
+`docs/design/<path>/`.
+
+Examples:
+
+| Source module | Design doc location |
+|---|---|
+| `lmcache/cli/` | `docs/design/cli/` |
+| `lmcache/cli/commands/ping.py` | `docs/design/cli/commands/ping.md` |
+| `lmcache/cli/commands/bench/engine_bench/` | `docs/design/cli/commands/bench/engine_bench/` |
+| `lmcache/v1/distributed/l2_adapters/` | `docs/design/v1/distributed/l2_adapters/` |
+
+Not every module has a design doc — only modules whose design warrants prose
+beyond what the code and docstrings already communicate. Missing directories
+here simply mean "no standalone design doc exists yet."
+
+## Guidelines for Adding Docs
+
+- Place the doc at the path that matches the module it describes. A doc that
+  spans multiple sibling submodules belongs at their common parent directory.
+- Keep the file name descriptive of the topic, not the module (e.g.
+  `query-command.md` under `docs/design/cli/commands/`, not `query.md`).
+- When linking between design docs, use relative paths so links survive renames
+  within this tree.
diff --git a/docs/design/cli/commands.md b/docs/design/cli/commands.md
new file mode 100644
index 0000000..12ed718
--- /dev/null
+++ b/docs/design/cli/commands.md
@@ -0,0 +1,403 @@
+# LMCache CLI Design
+
+**Status:** Proposal  |  **Date:** 2026-03-11
+
+## Why
+
+Today users must remember `python3 -m lmcache.v1.multiprocess.http_server ...` and
+similar module paths. We need a single `lmcache` command as the front door to all
+LMCache functionality.
+
+## Command Overview
+
+```
+lmcache
+├── server                          # Launch LMCache server (ZMQ + HTTP)
+├── coordinator                     # Launch the mp coordinator (HTTP)
+├── describe {kvcache,engine}       # Rich status view of a running endpoint
+├── ping     {kvcache,engine}       # Pure liveness check (OK/FAIL)
+├── query    {kvcache,engine}       # Single-shot query with metrics
+├── bench    {engine,server,l2}    # Sustained performance benchmarking
+└── kvcache  {clear,end-session}    # KV cache management actions
+```
+
+| Verb | Question it answers | Weight |
+|------|-------------------|--------|
+| `ping` | Is it alive? | Single-shot, instant (OK/FAIL) |
+| `query` | What happens when I send one request? | Single-shot, with metrics |
+| `describe` | What is this thing? | Rich status dashboard |
+| `bench` | How fast is it? | Multi-iteration, metrics-heavy |
+| `kvcache` | Mutate cache state | Clear, end-session, evict (future) |
+
+All client commands use a `--url` flag pointing to the **LMCache HTTP server**
+(e.g. `--url http://localhost:8000`).
+
+---
+
+## Commands in Detail
+
+### `lmcache server`
+
+Replaces `python3 -m lmcache.v1.multiprocess.http_server`. Runs in foreground,
+Ctrl-C to stop. HTTP frontend is enabled by default; use `--no-http` to run
+ZMQ-only.
+
+```bash
+lmcache server \
+    --engine-type blend --host 0.0.0.0 --port 5555 \
+    --max-gpu-workers 2 \
+    --l1-size-gb 60 --eviction-policy LRU \
+    --no-http  # opt out of HTTP frontend
+```
+
+Server args are composed from existing helpers: `add_mp_server_args()`,
+`add_storage_manager_args()`, `add_prometheus_args()`, `add_telemetry_args()`,
+`add_http_frontend_args()`.
+
+### `lmcache coordinator`
+
+Replaces `python3 -m lmcache.v1.mp_coordinator`. Runs the mp coordinator's
+FastAPI/HTTP app in the foreground (Ctrl-C to stop). The coordinator tracks mp
+server instances in a registry and evicts those whose heartbeats lapse.
+
+```bash
+lmcache coordinator \
+    --host 0.0.0.0 --port 9300 \
+    --instance-timeout 30 \
+    --health-check-interval 10
+```
+
+Config resolves from `MPCoordinatorConfig.from_env()` (the
+`LMCACHE_MP_COORDINATOR_*` environment variables); any CLI flag that is supplied
+overrides the corresponding field. Each flag defaults to unset so env-only
+deployments keep working. See
+[../v1/mp_coordinator/README.md](../v1/mp_coordinator/README.md).
+
+### `lmcache describe`
+
+```bash
+$ lmcache describe kvcache --url localhost:5555
+
+============ LMCache KV Cache Service ============
+Health:                                  OK
+ZMQ endpoint:                            tcp://localhost:5555
+HTTP endpoint:                           http://localhost:8000
+Engine type:                             blend
+Chunk size:                              256
+L1 capacity (GB):                        60.0
+L1 used (GB):                            42.3 (70.5%)
+Eviction policy:                         LRU
+Cached objects:                          1024
+Uptime:                                  2h 14m 32s
+==================================================
+
+$ lmcache describe engine --url http://localhost:8000
+
+================ Inference Engine ================
+Model:                                   meta-llama/Llama-3.1-70B-Instruct
+Max context (tokens):                    131072
+Status:                                  healthy
+Running requests:                        3
+==================================================
+```
+
+`describe kvcache` gathers data from multiple ZMQ request types (`NOOP` for debug
+info, `GET_CHUNK_SIZE` for chunk size) and `/status` (HTTP) to build a
+consolidated view.
+
+### `lmcache ping`
+
+Pure liveness check for both targets. Returns OK/FAIL with round-trip time,
+measuring only the network round-trip excluding local Python overhead.
+
+**`ping kvcache`** -- pings the LMCache server process via HTTP `/healthcheck`:
+```bash
+$ lmcache ping kvcache --url http://localhost:8080
+
+======= Ping KV Cache =======
+Status:                  OK
+Round trip time (ms):    0.42
+==============================
+
+```
+
+**`ping engine`** -- pings the vLLM server process via HTTP `/health`:
+```bash
+$ lmcache ping engine --url http://localhost:8000
+
+======== Ping Engine =========
+Status:                  OK
+Round trip time (ms):    12.3
+==============================
+```
+
+### `lmcache query`
+
+Single-shot query with detailed metrics. Use this to test a specific request
+and see what happened.
+
+**`query engine`** -- single inference request with TTFT/TPOT. Supports `{corpus}`
+templates for realistic long-context prompts:
+```bash
+$ lmcache query engine --url http://localhost:8000 \
+    --prompt "{ffmpeg} What is the example usage of ffmpeg?" --max-tokens 128
+
+========== Query Engine Result ==========
+Prompt tokens:                           8192
+  Corpus 'ffmpeg':                       8186
+  Query:                                 6
+Output tokens:                           128
+-----------Latency Metrics---------------
+TTFT (ms):                               892.3
+TPOT (ms/token):                         11.8
+Total latency (ms):                      2403.7
+Throughput (tokens/s):                   53.2
+=========================================
+```
+
+**`query kvcache`** -- query KV cache state for specific keys or tokens:
+```bash
+# Check if a specific token sequence is cached (lookup)
+$ lmcache query kvcache --url localhost:5555 \
+    --prompt "{ffmpeg} What is the example usage of ffmpeg?" \
+    --model meta-llama/Llama-3.1-8B-Instruct
+
+======== Query KV Cache Result ==========
+Prompt tokens:                           8192
+Cached chunks:                           30/32 (93.8%)
+Cached tokens:                           7680/8192
+Cache status:                            HIT (partial)
+=========================================
+
+# Store-retrieve round-trip with latency and correctness
+$ lmcache query kvcache --url localhost:5555 --round-trip
+
+==== Query KV Cache Result (round-trip) ====
+Store latency (ms):                      1.23
+Retrieve latency (ms):                   0.87
+Checksum:                                OK
+============================================
+```
+
+### `lmcache bench`
+
+**`bench server`** -- end-to-end sanity test for a running LMCache MP cache
+server (ZMQ + HTTP). For each sequence in ``[--start, --end)`` the tool runs a
+cold pass (``LOOKUP`` miss → ``STORE``) and a warm pass (``LOOKUP`` hit →
+``RETRIEVE``), then cross-checks per-chunk checksums against the server's HTTP
+API. Exercises the full RPC path
+(``REGISTER_KV_CACHE → GET_CHUNK_SIZE → LOOKUP → QUERY_PREFETCH_STATUS →
+RETRIEVE → STORE → END_SESSION``).
+
+Supports two run modes via ``--mode``:
+
+- **``gpu``** (default) -- allocates real CUDA tensors and uses CUDA IPC
+  (LMCache-driven handle transfer path).
+- **``cpu``** -- allocates POSIX-SHM-backed tensors; the server maps the same
+  physical pages for zero-copy STORE/RETRIEVE (engine-driven transfer path by
+  default). To use the zero-copy SHM handle path, add
+  ``--transfer-mode lmcache_driven``.
+
+The transfer path can be overridden explicitly with ``--transfer-mode
+{auto,engine_driven,lmcache_driven}``. ``auto`` keeps the historical mapping:
+gpu→lmcache_driven, cpu→engine_driven.
+
+```bash
+$ lmcache bench server \
+    --rpc-url tcp://localhost:5555 \
+    --url http://localhost:8080 \
+    --start 0 --end 2
+
+Connecting to LMCache MP Server at tcp://localhost:5555 (mode=gpu, transfer=auto) ...
+Server chunk_size = 256
+Resolved KV shape spec: (2,1024,16,8,128):float16:32
+[seq=0] LOOKUP cold:  0/2 chunks hit (1.82 ms)
+[seq=0] STORE:        2 chunks stored (1.74 ms)
+[seq=0] LOOKUP warm:  2/2 chunks hit (1.31 ms)
+[seq=0] RETRIEVE:     2 chunks retrieved (1.48 ms)
+[seq=0] CHECKSUM MATCH OK
+[seq=1] ...
+```
+
+With ``--end`` unset, the loop runs forever; stop with ``Ctrl-C``. The KV
+tensor layout is controlled by ``--kvcache-shape-spec`` (see
+``lmcache/v1/kv_layer_groups.py``); see :doc:`bench_server` in the user guide
+for the full flag list.
+
+**`bench l2`** -- store / lookup / load throughput benchmark against an
+``L2AdapterInterface`` implementation (no MP server required). Implemented at
+``lmcache/cli/commands/bench/l2_adapter_bench/``; see the
+``docs/source/cli/bench_l2.rst`` user guide for full options.
+
+**`bench engine`** -- **superset of `vllm bench serve`**. Same CLI args, same output
+format, plus an extra LMCache KV cache metrics section:
+
+```bash
+# vllm bench serve compatible -- just swap the command name
+$ lmcache bench engine \
+    --url http://localhost:8000 \
+    --model meta-llama/Llama-3.1-8B-Instruct \
+    --dataset-name random --random-input-len 7500 --random-output-len 200 \
+    --num-prompts 30 --request-rate 1 --ignore-eos
+
+============ Serving Benchmark Result ============
+Successful requests:                     30
+Benchmark duration (s):                  31.34
+Total input tokens:                      224970
+Total generated tokens:                  6000
+Request throughput (req/s):              0.96
+Output token throughput (tok/s):         191.44
+Total Token throughput (tok/s):          7369.36
+---------------Time to First Token----------------
+Mean TTFT (ms):                          313.41
+Median TTFT (ms):                        272.83
+P99 TTFT (ms):                           837.32
+-----Time per Output Token (excl. 1st token)------
+Mean TPOT (ms):                          8.84
+Median TPOT (ms):                        8.72
+P99 TPOT (ms):                           11.35
+----------LMCache KV Cache Performance------------
+KV cache hit rate (L1):                  92.3%
+KV cache hit rate (L2):                  67.8%
+L1 read bandwidth:                       12.4 GB/s
+L1 write bandwidth:                      8.7 GB/s
+Avg tokens saved by cache (per req):     6420
+Cache-assisted TTFT savings (est.):      58.2%
+==================================================
+```
+
+LMCache-specific additions on top of vLLM args: `--url` (replaces `--port`),
+`--prompt` with `{corpus}` templates, `--corpus name=path` for custom corpora.
+
+### `lmcache kvcache`
+
+```bash
+$ lmcache kvcache clear --url localhost:5555
+
+========== KV Cache Clear ==========
+Status:                              OK
+Objects removed:                     1024
+====================================
+
+$ lmcache kvcache end-session --url localhost:5555 <request_id>
+
+======== KV Cache End Session ========
+Status:                              OK
+Request ID:                          <request_id>
+======================================
+```
+
+---
+
+## Prompt Corpora
+
+`query engine`, `bench engine`, and `query kvcache` support `{name}` in `--prompt`
+to expand built-in text corpora (e.g., `{paul_graham}` ~12k tokens, `{ffmpeg}`
+~8k tokens). Custom corpora: `--corpus my_doc=./file.txt`. Built-in corpora ship
+in `lmcache/cli/corpora/`.
+
+## Implementation Notes
+
+### Architecture
+
+- **Auto-discovery (N-level):** Commands at all levels are discovered
+  automatically via `discover_subclasses()` (in
+  `lmcache/v1/utils/subclass_discovery.py`). No manual registration is needed
+  — adding a new command at any depth is a single-file change.
+  - **Leaf commands:** Inherit from `BaseCommand` directly.
+  - **Command groups:** Inherit from `CompositeCommand(BaseCommand)`. Its
+    `register()` scans the package where the concrete subclass is defined for
+    nested `BaseCommand` subclasses and registers each one automatically.
+  - **Recursive nesting:** A discovered subcommand can itself be a
+    `CompositeCommand`, enabling arbitrary depth (e.g.
+    `tool → cache-simulator → simulate`).
+- **Class hierarchy:**
+  - `BaseCommand` — abstract base class for all CLI commands (leaf or composite).
+  - `CompositeCommand(BaseCommand)` — base class for commands that contain
+    auto-discovered sub-subcommands (e.g. `query`, `bench`, `quota`, `trace`,
+    `tool`). Subclasses only need to implement `name()` and `help()`.
+- **Adding a new command:**
+  - *Top-level:* Create a new `.py` file (or sub-package with `__init__.py`)
+    under `commands/` with a concrete `BaseCommand` subclass. Done.
+  - *Second-level:* Create a new `.py` file (or sub-package with `__init__.py`)
+    under the parent command's package with a concrete `BaseCommand` subclass.
+    Done. No edits to the parent's `__init__.py` required.
+- **`send_request()` helper:** Creates a temporary `MessageQueueClient`, submits
+  a ZMQ request, waits with timeout (default 5s), tears down. All ZMQ commands
+  use this. Extended to handle HTTP targets alongside ZMQ.
+- **Framework:** `argparse` with subparsers (no new deps). Reuses existing
+  `add_*_args()` helpers.
+- **`--url` flag:** Configured per-subcommand (ZMQ vs HTTP semantics vary).
+
+### File layout
+
+```
+lmcache/cli/
+├── __init__.py
+├── main.py              # main() entry point
+├── metrics/             # Metrics system (see framework-and-metrics.md)
+├── commands/
+│   ├── __init__.py      # Auto-discovers ALL_COMMANDS (no manual edits)
+│   ├── base.py          # BaseCommand ABC + CompositeCommand
+│   ├── mock.py          # lmcache mock  (example/test command)
+│   ├── server.py        # lmcache server
+│   ├── coordinator.py   # lmcache coordinator
+│   ├── describe.py      # lmcache describe {kvcache}
+│   ├── ping.py          # lmcache ping {kvcache,engine}
+│   ├── kvcache.py       # lmcache kvcache {clear,end-session}
+│   ├── query/           # lmcache query (CompositeCommand)
+│   │   ├── __init__.py          # QueryCommand(CompositeCommand)
+│   │   ├── engine_command.py    # Auto-discovered: lmcache query engine
+│   │   └── kvcache_command.py   # Auto-discovered: lmcache query kvcache
+│   ├── bench/           # lmcache bench (CompositeCommand)
+│   │   ├── __init__.py          # BenchCommand(CompositeCommand)
+│   │   ├── engine_bench/        # Auto-discovered: lmcache bench engine
+│   │   ├── server_bench/        # Auto-discovered: lmcache bench server
+│   │   └── l2_adapter_bench/    # Auto-discovered: lmcache bench l2
+│   ├── quota/           # lmcache quota (CompositeCommand)
+│   │   ├── __init__.py          # QuotaCommand(CompositeCommand)
+│   │   ├── set_command.py       # Auto-discovered: lmcache quota set
+│   │   ├── get_command.py       # Auto-discovered: lmcache quota get
+│   │   ├── list_command.py      # Auto-discovered: lmcache quota list
+│   │   └── delete_command.py    # Auto-discovered: lmcache quota delete
+│   ├── trace/           # lmcache trace (CompositeCommand)
+│   │   ├── __init__.py          # TraceCommand(CompositeCommand)
+│   │   ├── info_command.py      # Auto-discovered: lmcache trace info
+│   │   └── replay_command.py    # Auto-discovered: lmcache trace replay
+│   └── tool/            # lmcache tool (CompositeCommand)
+│       ├── __init__.py          # ToolCommand(CompositeCommand)
+│       └── cache_simulator/     # Auto-discovered: lmcache tool cache-simulator
+│           ├── __init__.py              # CacheSimulatorCommand(CompositeCommand)
+│           ├── simulate_command.py      # Auto-discovered: simulate
+│           ├── sweep_command.py         # Auto-discovered: sweep
+│           └── gen_dataset_command.py   # Auto-discovered: gen-dataset
+├── config.py            # CLIConfig (centralized config system)
+└── corpora/             # Built-in prompt corpora
+```
+
+### Other notes
+
+- **Entry point:** `lmcache = "lmcache.cli.main:main"` in `pyproject.toml`.
+- **Auto-discovery mechanism:** Powered by `discover_subclasses()` in
+  `lmcache/v1/utils/subclass_discovery.py`. Uses `pkgutil.iter_modules` to
+  scan direct submodules, then `inspect.getmembers` to find concrete
+  `BaseCommand` subclasses. Each subclass is yielded at most once.
+- **`CompositeCommand` pattern:** A `CompositeCommand` scans its own package
+  for `BaseCommand` subclasses (excluding itself and abstract classes).
+  Sub-packages with `__init__.py` defining a `BaseCommand` are also discovered,
+  enabling nested command groups (e.g. `tool cache-simulator simulate`).
+- **`bench engine`:** Wraps `vllm.benchmarks`, then queries `/status` for
+  cache metrics.
+- **`query kvcache`:** Tokenizes `--prompt` using the model's tokenizer, then
+  performs a lookup over ZMQ to check which chunks are cached.
+
+## Phasing
+
+| Phase | Scope |
+|-------|-------|
+| **0** | CLI framework (explicit registration, `Metrics`), `mock` example command, entry point — see [framework-and-metrics.md](framework-and-metrics.md) |
+| **1** | **`server`** (done), `ping kvcache`, `kvcache clear`, `kvcache end-session`, `describe kvcache` |
+| **2** | `ping engine`, `query engine`, `query kvcache`, `bench engine`, `bench server`, `bench l2`, `describe engine`, corpora |
+| **3** | `kvcache evict` (future) |
+
+Existing `lmcache_server` entry point kept as a deprecated alias for 2 minor releases.
diff --git a/docs/design/cli/commands/bench/engine_bench/bench-engine.md b/docs/design/cli/commands/bench/engine_bench/bench-engine.md
new file mode 100644
index 0000000..8b1f5d2
--- /dev/null
+++ b/docs/design/cli/commands/bench/engine_bench/bench-engine.md
@@ -0,0 +1,691 @@
+# `lmcache bench engine` — Design & Extension Guide
+
+**Status:** Implemented  |  **Date:** 2026-05-05
+
+## Overview
+
+`lmcache bench engine` runs sustained benchmarks against an OpenAI-compatible
+inference engine. It ships five workload types that exercise different
+caching patterns, each controlling its own request scheduling while shared
+modules handle request sending, stats collection, and real-time progress
+display.
+
+If required arguments (`--engine-url`, `--workload`, and either
+`--tokens-per-gb-kvcache` or `--lmcache-url`) are missing, the command drops
+into a guided **interactive TUI** to fill them in. `--config FILE` loads a
+previously-exported JSON config and skips the TUI; `--no-interactive` errors
+out instead of prompting; `--export-config FILE` writes the resolved config
+to JSON and exits without running the benchmark.
+
+```bash
+# Long-document Q&A (semaphore-controlled concurrency)
+lmcache bench engine --engine-url http://localhost:8000 \
+    --workload long-doc-qa --tokens-per-gb-kvcache 6000
+
+# Multi-round chat (QPS-controlled dispatch)
+lmcache bench engine --engine-url http://localhost:8000 \
+    --workload multi-round-chat --tokens-per-gb-kvcache 6000 \
+    --mrc-qps 2.0 --mrc-duration 120
+
+# Random prefill (all requests at once, 1-token output)
+lmcache bench engine --engine-url http://localhost:8000 \
+    --workload random-prefill --tokens-per-gb-kvcache 6000 \
+    --rp-num-requests 100
+
+# Long-doc permutator (blended-prefix cache reuse stress test)
+lmcache bench engine --engine-url http://localhost:8000 \
+    --workload long-doc-permutator --tokens-per-gb-kvcache 6000 \
+    --ldp-num-contexts 5 --ldp-num-permutations 20
+
+# Prefix-suffix tuner (tiered KV-cache demonstrator, sequential 2-pass)
+lmcache bench engine --engine-url http://localhost:8000 \
+    --workload prefix-suffix-tuner --lmcache-url http://localhost:8080 \
+    --psf-context-length 8000 --psf-prefix-ratio 0.8 --psf-thrash 100
+```
+
+---
+
+## 1. Architecture
+
+### File Layout
+
+```
+lmcache/cli/commands/bench/
+├── __init__.py                    # BenchCommand (CLI registration + orchestrator)
+└── engine_bench/
+    ├── __init__.py                # Package marker
+    ├── config.py                  # EngineBenchConfig, auto-detection helpers
+    ├── stats.py                   # RequestResult, StatsCollector, FinalStats
+    ├── request_sender.py          # RequestSender (async streaming)
+    ├── progress.py                # ProgressMonitor (real-time terminal display)
+    ├── interactive/               # Guided TUI for missing-arg resolution
+    │   ├── __init__.py            # run_interactive() entry point
+    │   ├── schema.py              # Field schema + workload-specific items
+    │   ├── state.py               # InteractiveState (load/save JSON, merge CLI args)
+    │   ├── terminal.py            # Terminal rendering primitives
+    │   └── config.json            # Static schema for interactive prompts
+    └── workloads/
+        ├── __init__.py            # create_workload() factory
+        ├── base.py                # BaseWorkload (ABC with run loop)
+        ├── long_doc_permutator.py # LongDocPermutatorConfig + LongDocPermutatorWorkload
+        ├── long_doc_qa.py         # LongDocQAConfig + LongDocQAWorkload
+        ├── multi_round_chat.py    # MultiRoundChatConfig + Session + MultiRoundChatWorkload
+        ├── prefix_suffix_tuner.py # PrefixSuffixTunerConfig + PrefixSuffixTunerWorkload
+        └── random_prefill.py      # RandomPrefillConfig + RandomPrefillWorkload
+```
+
+### Module Dependency Graph
+
+```
+BenchCommand (orchestrator)
+  ├── config.py          → EngineBenchConfig
+  ├── stats.py           → StatsCollector
+  ├── progress.py        → ProgressMonitor
+  ├── request_sender.py  → RequestSender
+  └── workloads/
+       ├── __init__.py   → create_workload() factory
+       └── base.py       → BaseWorkload (used by all concrete workloads)
+```
+
+All concrete workloads depend on `BaseWorkload`, `RequestSender`,
+`StatsCollector`, and `ProgressMonitor` — but never on each other.
+
+---
+
+## 2. Core Modules
+
+### 2.1 `config.py` — Configuration
+
+```python
+@dataclass
+class EngineBenchConfig:
+    engine_url: str
+    model: str                    # auto-detected if not provided
+    workload: str                 # "long-doc-qa", "multi-round-chat", "random-prefill"
+    kv_cache_volume_gb: float
+    tokens_per_gb_kvcache: int    # auto-resolved via --lmcache-url or explicit
+    seed: int
+    output_dir: str
+    export_csv: bool
+    export_json: bool
+    quiet: bool
+```
+
+Key functions:
+
+| Function | Purpose |
+|----------|---------|
+| `parse_args_to_config(args) -> EngineBenchConfig` | Converts CLI args to fully-resolved config |
+| `auto_detect_model(engine_url) -> str` | Fetches model ID from `/v1/models` |
+| `resolve_tokens_per_gb(lmcache_url, model_name) -> int` | Queries LMCache `/status` for `cache_size_per_token * world_size` |
+
+`EngineBenchConfig` contains only general parameters. Workload-specific
+configs live in their own modules and are resolved by the workload factory.
+
+### 2.2 `stats.py` — Stats Collection
+
+```python
+@dataclass
+class RequestResult:
+    request_id: str
+    successful: bool
+    ttft: float                   # seconds (time to first token)
+    request_latency: float        # seconds (total request time)
+    num_input_tokens: int
+    num_output_tokens: int
+    decode_speed: float           # tokens/second
+    submit_time: float            # absolute timestamp
+    first_token_time: float       # absolute timestamp
+    finish_time: float            # absolute timestamp
+    error: str                    # empty if successful
+
+@dataclass
+class AggregatedStats:
+    total_requests: int
+    successful_requests: int
+    failed_requests: int
+    elapsed_time: float
+    mean_ttft_ms: float
+    mean_decode_speed: float
+    mean_request_latency_ms: float
+    input_throughput: float       # tokens/second
+    output_throughput: float      # tokens/second
+    total_input_tokens: int
+    total_output_tokens: int
+
+@dataclass
+class FinalStats(AggregatedStats):
+    p50_ttft_ms: float            # plus p90, p99
+    p50_decode_speed: float       # plus p90, p99
+    p50_request_latency_ms: float # plus p90, p99
+```
+
+`StatsCollector` is **thread-safe** (uses `threading.Lock`):
+
+| Method | Called by | Description |
+|--------|-----------|-------------|
+| `on_request_finished(result)` | RequestSender callback | Records a completed request |
+| `get_current_stats() -> AggregatedStats` | ProgressMonitor (every 1s) | Returns a snapshot for live display |
+| `get_final_stats() -> FinalStats` | Orchestrator (after benchmark) | Computes percentiles |
+| `reset()` | BaseWorkload (between warmup/benchmark) | Clears warmup stats |
+| `export_csv(path)` | Orchestrator | Writes per-request CSV |
+| `export_json(path, config)` | Orchestrator | Writes summary JSON |
+
+### 2.3 `request_sender.py` — Async Streaming
+
+```python
+OnFinishedCallback = Callable[[RequestResult, str], None]
+
+class RequestSender:
+    def __init__(self, engine_url, model, completions_mode=False, on_finished=[])
+    async def send_request(self, request_id, messages, max_tokens=128) -> RequestResult
+    async def send_warmup_request(self, request_id, messages, max_tokens=1) -> RequestResult
+    async def close(self) -> None
+```
+
+- Uses `AsyncOpenAI` for streaming chat/completions.
+- Measures TTFT, decode speed, total latency per request.
+- Extracts token counts from server usage reports.
+- After each request (success or failure), invokes all `on_finished`
+  callbacks with `(RequestResult, response_text)`.
+
+Each `send_request` call is a **self-contained coroutine** — concurrency is
+controlled externally by the workload (semaphore, QPS, or fire-all-at-once).
+
+### 2.4 `progress.py` — Real-Time Display
+
+```python
+class ProgressMonitor:
+    def __init__(self, stats_collector, quiet=False)
+    def start(self) -> None          # starts daemon thread
+    def stop(self) -> None           # stops thread, prints final state
+    def on_request_sent(request_id)  # increments in-flight count
+    def on_request_finished(request_id, successful)  # decrements in-flight count
+    def log_message(message)         # adds to rolling log (last 5 lines)
+```
+
+Runs a daemon thread that redraws every second using ANSI cursor control.
+Reads aggregated stats from `StatsCollector.get_current_stats()`. Tracks
+in-flight count and rolling log messages internally. No-op when `quiet=True`.
+
+### 2.5 `workloads/base.py` — Base Workload
+
+```python
+class BaseWorkload(ABC):
+    def __init__(self, request_sender, stats_collector, progress_monitor)
+
+    # --- Must implement ---
+    @abstractmethod async def warmup(self) -> None
+    @abstractmethod async def step(self, time_offset: float) -> float
+    @abstractmethod def log_config(self) -> None
+    @abstractmethod def on_request_finished(self, request_id: str, output: str) -> None
+
+    # --- Provided by base class ---
+    def run(self) -> None                         # entry point (blocks)
+    def request_finished(self, result, text)      # thread-safe queue bridge
+```
+
+**`run()` loop** (in base class):
+
+```
+log_config()           ← print workload config (before progress monitor starts)
+warmup()               ← workload-specific warmup
+stats_collector.reset()
+loop:
+    drain_finished_queue() → on_request_finished()
+    next_wakeup = step(time_offset)
+    if next_wakeup < 0: break
+    sleep until next_wakeup
+drain_finished_queue()   ← final drain
+```
+
+**`step()` contract:**
+
+- Returns the **absolute time offset** (from benchmark start) when the loop
+  should call `step()` again. The loop sleeps until that time.
+- Returns a **negative value** to signal the workload is complete.
+- The loop calls `_drain_finished_queue()` before each `step()`, which
+  calls `on_request_finished()` for any completed requests.
+
+**Callback bridge — `request_finished()`:**
+
+This method matches the `OnFinishedCallback` signature and is registered
+on `RequestSender._on_finished` by the orchestrator. It enqueues
+`(request_id, response_text)` onto a `queue.Queue`. The loop thread drains
+this queue and calls `on_request_finished()` from a single thread, so
+workload implementations do not need to handle cross-thread concerns.
+
+### 2.6 `workloads/__init__.py` — Factory
+
+```python
+def create_workload(config, args, request_sender, stats_collector, progress_monitor) -> BaseWorkload
+```
+
+Dispatches on `config.workload` string to the appropriate workload module.
+Resolves workload-specific config from `args`, constructs the workload
+instance, and returns it ready to `run()`.
+
+---
+
+## 3. End-to-End Flow
+
+The orchestrator in `engine_bench.command.run_engine_bench()` wires everything together:
+
+```
+0. _resolve_args(args)            → argparse.Namespace
+     (a) --config FILE            → load InteractiveState, merge CLI overrides
+     (b) --no-interactive / --export-config → error if required args missing
+     (c) interactive TUI          → if any required arg is missing
+     (d) pass through             → if all required args present
+1. parse_args_to_config(args)     → EngineBenchConfig
+   (--export-config: write JSON and return without running)
+2. StatsCollector()
+3. ProgressMonitor(stats_collector, quiet)
+4. RequestSender(engine_url, model)
+5. create_workload(config, args, sender, collector, monitor) → workload
+6. Wire callbacks on sender:
+     - stats_collector.on_request_finished(result)
+     - progress_monitor.on_request_finished(request_id, successful)
+     - workload.request_finished(result, response_text)
+7. workload.log_config()          → print config to terminal
+8. progress_monitor.start()       → start live display
+9. workload.run()                 → blocks until benchmark complete
+10. progress_monitor.stop()
+11. request_sender.close()
+12. Emit final metrics (CLI metrics system)
+13. Export CSV / JSON
+14. sys.exit(1) if any failures
+```
+
+### Callback Wiring
+
+```
+Workload.step()
+    │
+    ├── send_request()  ──────────────────┐
+    │                                     │
+    └── progress_monitor.on_request_sent()│
+                                          ▼
+                                   RequestSender
+                                   (streams SSE, collects stats)
+                                          │
+                              on_finished callbacks:
+                              ├── stats_collector.on_request_finished(result)
+                              ├── progress_monitor.on_request_finished(id, ok)
+                              └── workload.request_finished(result, text)
+                                          │
+                                          ▼
+                                   finished_queue
+                                          │
+                              loop drains → workload.on_request_finished(id, text)
+```
+
+---
+
+## 4. Existing Workloads
+
+### 4.1 `long-doc-qa` — Long Document Q&A
+
+Tests KV cache reuse by asking repeated questions over long documents.
+
+**Config** (`LongDocQAConfig`):
+
+| Field | CLI arg | Default | Description |
+|-------|---------|---------|-------------|
+| `document_length` | `--ldqa-document-length` | 10000 | Tokens per document |
+| `query_per_document` | `--ldqa-query-per-document` | 2 | Questions per document |
+| `num_documents` | computed | — | `kv_cache_volume * tokens_per_gb / document_length` |
+| `shuffle_policy` | `--ldqa-shuffle-policy` | `random` | `random` or `tile` |
+| `num_inflight_requests` | `--ldqa-num-inflight-requests` | 3 | Max concurrent requests |
+
+**Behavior:**
+
+- **Warmup:** Sends each document once sequentially (`max_tokens=1`)
+- **Dispatch:** Semaphore-controlled — `step()` acquires semaphore, fires
+  async task, returns `0.0` (immediate re-call). Semaphore released when
+  task completes.
+- **`on_request_finished`:** No-op (stateless).
+- **Termination:** Returns `-1.0` when schedule exhausted and all tasks done.
+
+### 4.2 `multi-round-chat` — Multi-Round Chat
+
+Simulates concurrent chat users with growing conversation history.
+
+**Config** (`MultiRoundChatConfig`):
+
+| Field | CLI arg | Default | Description |
+|-------|---------|---------|-------------|
+| `shared_prompt_length` | `--mrc-shared-prompt-length` | 2000 | System prompt tokens |
+| `chat_history_length` | `--mrc-chat-history-length` | 10000 | Pre-filled history tokens |
+| `user_input_length` | `--mrc-user-input-length` | 50 | Tokens per query |
+| `output_length` | `--mrc-output-length` | 200 | Max tokens per response |
+| `qps` | `--mrc-qps` | 1.0 | Queries per second |
+| `duration` | `--mrc-duration` | 60.0 | Benchmark duration (seconds) |
+| `num_concurrent_users` | computed | — | `kv_cache_volume * tokens_per_gb / (prompt + history)` |
+
+**Behavior:**
+
+- **Warmup:** Sends one request per session sequentially (`max_tokens=1`)
+- **Dispatch:** QPS-controlled — `step()` dispatches at `1/qps` intervals
+  using round-robin session scheduling. Returns `global_index * interval`.
+  If the target session is busy, returns `time_offset + 0.01` to retry
+  after queue drain.
+- **`on_request_finished`:** **Stateful** — records the response in the
+  session's conversation history via `Session.record_answer()`, which
+  marks the session as ready for its next request.
+- **Termination:** Returns `-1.0` when `time_offset >= duration` and all
+  pending tasks are complete.
+
+**Session state:** Each `Session` holds a system prompt, pre-filled history,
+and a growing list of `(query, answer)` exchanges. `build_messages()` constructs
+the full OpenAI message list including all prior context.
+
+### 4.3 `random-prefill` — Prefill Speed Testing
+
+Tests raw prefill throughput by firing all requests simultaneously.
+
+**Config** (`RandomPrefillConfig`):
+
+| Field | CLI arg | Default | Description |
+|-------|---------|---------|-------------|
+| `request_length` | `--rp-request-length` | 10000 | Tokens per request |
+| `num_requests` | `--rp-num-requests` | 50 | Number of requests |
+
+**Behavior:**
+
+- **Warmup:** None.
+- **Dispatch:** Fire-all-at-once — first `step()` dispatches all requests
+  as concurrent async tasks with `max_tokens=1`, returns `0.0`. Subsequent
+  `step()` calls wait via `asyncio.wait(FIRST_COMPLETED)`.
+- **`on_request_finished`:** No-op (stateless).
+- **Termination:** Returns `-1.0` when all tasks are complete.
+
+### 4.4 `long-doc-permutator` — Blended Cache-Reuse Stress Test
+
+Stresses **blended** KV cache reuse — not just prefix reuse — by sending
+permutations of a fixed set of context documents. Each request is:
+
+```
+[System Prompt] + [Doc_i1] + [Doc_i2] + ... + [Doc_iN]
+```
+
+where `(i1, …, iN)` is one permutation of the `N` contexts. Most permutations
+share *some* chunks with prior requests but rarely the same prefix, exercising
+chunk-level cache lookup and eviction.
+
+**Config** (`LongDocPermutatorConfig`):
+
+| Field | CLI arg | Default | Description |
+|-------|---------|---------|-------------|
+| `num_contexts` | `--ldp-num-contexts` | 5 | Number of unique context documents (`N`) |
+| `context_length` | `--ldp-context-length` | 5000 | Tokens per context |
+| `system_prompt_length` | `--ldp-system-prompt-length` | 1000 | Shared system prompt tokens (`0` disables) |
+| `num_permutations` | `--ldp-num-permutations` | 10 | Distinct permutations to send (capped at `N!`) |
+| `vocab_size` | (none — hardcoded in factory) | 8000 | Vocabulary pool size for synthetic context generation |
+| `num_inflight_requests` | `--ldp-num-inflight-requests` | 1 | Max concurrent in-flight requests |
+
+**Stress axes** (each config field tunes one):
+
+| Axis | Knob |
+|------|------|
+| Blended-context boundaries | `num_contexts` |
+| Eviction pressure | `num_permutations` |
+| Chunk homogeneity (hash collisions) | `vocab_size` |
+| Prefix domination | `system_prompt_length` |
+| Concurrency | `num_inflight_requests` |
+
+**Behavior:**
+
+- **Data generation:** Builds a deterministic vocab pool of pseudo-words,
+  generates `num_contexts` distinct contexts (each seeded independently so
+  token sequences truly diverge), and enumerates permutations.
+- **Permutation enumeration:** For small `N`, iterates `itertools.permutations`
+  and truncates. When `N!` is much larger than `num_permutations * 10`, samples
+  random permutations into a `set` to avoid exhausting an enormous search
+  space. Returns all `N!` permutations when `num_permutations >= N!`.
+- **Warmup:** A single dummy request (`max_tokens=1`) to prime the engine.
+- **Dispatch:** Semaphore-controlled — `step()` acquires the semaphore, fires
+  an async task with the next permutation, returns `0.0` for immediate
+  re-call. Once all permutations are dispatched, awaits remaining tasks via
+  `asyncio.wait(FIRST_COMPLETED)`.
+- **`on_request_finished`:** No-op (stateless).
+- **Termination:** Returns `-1.0` when the request list is exhausted and all
+  pending tasks have completed.
+
+**`run()` override:** Unlike the other workloads, `LongDocPermutatorWorkload`
+overrides `BaseWorkload.run()` to close `RequestSender`'s async HTTP client
+inside the same `asyncio.run()` call as the benchmark loop. `asyncio.run()`
+closes the loop on exit, which would orphan any open `httpx` connections;
+closing the client here ensures clean teardown. The orchestrator's subsequent
+`asyncio.run(request_sender.close())` then finds nothing to close and
+completes without error.
+
+### 4.5 `prefix-suffix-tuner` — Tiered KV-Cache Demonstrator
+
+A single sequential workload designed to be run **unchanged** across three
+LMCache configurations to demonstrate the value of each cache tier:
+
+| Baseline | LMCache config | Targeted overflow | Expected pass-2 hits |
+|----------|---------------|-------------------|----------------------|
+| 1 | vanilla vLLM (L0 only) | L0 (HBM) | none — every request a cold prefill |
+| 2 | vLLM + LMCache L1 + L2 | L1 (DRAM) | L2 prefix hits (suffix recomputed) |
+| 3 | vLLM + LMCache L1 + L2 + CacheBlend | L1 (DRAM) | L2 prefix hits + CacheBlend suffix hits |
+
+The user picks `--psf-thrash` to match the size of the tier they want to
+overflow (L0 size for Baseline 1, L1 size for Baselines 2 and 3). The
+workload itself does not need to know which baseline it is running — the
+internal `_OVERFLOW_FACTOR` (1.05) sizes the pool slightly larger than the
+named target, and sequential dispatch + LRU does the rest.
+
+`--kv-cache-volume` is unused by this workload (it remains required for
+other workloads that size themselves around a user-provided GB budget).
+
+**Request layout:**
+
+```
+[prefix_i with unique-ID][random breaker][shared suffix]
+```
+
+- `num_prefixes` distinct prefixes — each begins with `PREFIX_<8-hex-digits>`
+  so the prefix's chained block hash differs from every other prefix.
+- A **fresh random breaker** per request (32 tokens by default), defeating
+  ordinary prefix caching past the prefix boundary and preventing
+  non-CacheBlend reuse of the suffix.
+- A **single shared suffix**, deterministic and bit-identical across every
+  request — the only entry CacheBlend can reuse.
+
+**Synthetic body generation** uses a vocabulary pool of pseudo-words
+(consonant-vowel patterns + numeric suffix, e.g. `"boko42"`), shared by all
+prefixes / suffix / breakers but sampled with a *different* per-component
+RNG offset. Mirrors `long_doc_permutator`'s approach. This guarantees:
+
+- **CacheBlend correctness**: each prefix samples a different random
+  sequence, so chunk-level content fingerprints don't collide across
+  prefixes and inflate the blend hit rate. The shared suffix is the *only*
+  bit-identical chunk surface CacheBlend can reuse — which is what the
+  workload measures.
+- **Predictable token counts**: pseudo-words tokenize to ~2 BPE tokens on
+  most modern tokenizers (vs. ~3 for raw 6-digit numbers), so the actual
+  prompt length is closer to the configured `context_length`.
+
+**Config** (`PrefixSuffixTunerConfig`):
+
+| Field | CLI arg | Default | Description |
+|-------|---------|---------|-------------|
+| `context_length` | `--psf-context-length` | 8000 | Total tokens per request (prefix + breaker + suffix) |
+| `prefix_ratio` | `--psf-prefix-ratio` | 0.8 | Fraction of context allocated to the prefix; must be in (0.0, 1.0) |
+| `thrash` | `--psf-thrash` | 20.0 | **Size in GB of the targeted KV-cache tier** (L0 for Baseline 1, L1 for Baselines 2 and 3). Pool footprint is `thrash * _OVERFLOW_FACTOR` GB. |
+| `num_prefixes` | (computed) | — | `floor(thrash * _OVERFLOW_FACTOR * tokens_per_gb / prefix_tokens)` |
+| `prefix_tokens` | (computed) | — | `round(context_length * prefix_ratio)` |
+| `suffix_tokens` | (computed) | — | `context_length - prefix_tokens - breaker_tokens`; errors if `< 100` |
+| `breaker_tokens` | (hardcoded) | 32 | Random breaker length |
+| `_OVERFLOW_FACTOR` | (module constant) | 1.05 | How much to overflow the targeted tier. Hardcoded at 1.05 because the LRU invariant proves that a 5% overflow is sufficient under sequential same-order replay. |
+
+**Behavior:**
+
+- **Concurrency:** Strictly sequential, one in-flight request at a time —
+  `step()` awaits each request inline. No semaphore, no concurrent tasks.
+- **Pass 1 (warmup):** Sends each prefix once in pool order using
+  `send_warmup_request` (`max_tokens=1`). Stats are discarded by the base
+  class's `_run_async` after warmup.
+- **Pass 2 (measured):** Sends each prefix once **in identical pool order**
+  with `max_tokens=1`. These are the requests captured in final stats.
+- **Termination:** `step()` returns `-1.0` once `pass2_index` reaches
+  `num_prefixes`.
+
+**Why 1.05× is enough:** With sequential dispatch and LRU eviction in any
+single tier of capacity `K`:
+
+- After pass 1 of `N = 1.05K` prefixes, the `0.05K` oldest accesses have
+  been evicted; L1 holds prefixes `[0.05K..1.05K-1]` in LRU order.
+- Pass 2 access of prefix `0` misses (it was evicted), and serving it
+  evicts the LRU = prefix `0.05K` — *the very next prefix pass 2 will need*.
+- This pattern continues for the whole pass: every access misses the
+  targeted tier and the LRU it evicts is exactly the prefix needed next.
+
+So the workload does not need to overprovision by 2× or more; even a 5%
+overflow is sufficient to drive every measured request to the next tier
+down (Baseline 1 → cold prefill, Baseline 2/3 → L2).
+
+**Pass-1 vs pass-2 breakers:** The breaker is freshly randomized on every
+`_build_messages()` call, so pass 1 and pass 2 use different breakers per
+prefix. This makes the suffix unreachable by ordinary prefix caching even
+within a single benchmark run — exactly the case CacheBlend is designed to
+handle, and exactly what Baseline 3 should improve over Baseline 2.
+
+---
+
+## 5. Adding a New Workload
+
+### Step 1: Create the workload module
+
+Create `workloads/my_workload.py` with:
+
+```python
+from dataclasses import dataclass
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+
+@dataclass
+class MyWorkloadConfig:
+    """Workload-specific config fields with defaults."""
+    my_param: int = 100
+
+    def __post_init__(self) -> None:
+        # Validate all fields
+        if self.my_param <= 0:
+            raise ValueError(f"my_param must be positive, got {self.my_param}")
+
+    @classmethod
+    def resolve(cls, kv_cache_volume_gb, tokens_per_gb_kvcache, **kwargs):
+        """Compute derived fields from the KV cache budget + CLI args."""
+        # Example: compute a count from the cache budget
+        computed_count = max(1, int(kv_cache_volume_gb * tokens_per_gb_kvcache / kwargs["my_param"]))
+        return cls(my_param=kwargs["my_param"], ...)
+
+
+class MyWorkload(BaseWorkload):
+    def __init__(self, config, request_sender, stats_collector, progress_monitor, seed=42):
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self._config = config
+        # ... generate data, build schedule, etc.
+
+    def log_config(self) -> None:
+        """Print workload config. Called BEFORE progress monitor starts."""
+        print(f"Workload: my-workload\n  my_param: {self._config.my_param}")
+
+    async def warmup(self) -> None:
+        """Run warmup requests (or no-op)."""
+
+    async def step(self, time_offset: float) -> float:
+        """Dispatch logic. Return next wakeup time, or negative when done."""
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """Handle completed request. No-op for stateless, or record state."""
+```
+
+### Step 2: Register in the factory
+
+In `workloads/__init__.py`, add the import and dispatch:
+
+```python
+from lmcache.cli.commands.bench.engine_bench.workloads.my_workload import (
+    MyWorkloadConfig, MyWorkload,
+)
+
+_WORKLOAD_NAMES = (..., "my-workload")
+
+def create_workload(...):
+    ...
+    if config.workload == "my-workload":
+        wl_config = MyWorkloadConfig.resolve(
+            kv_cache_volume_gb=config.kv_cache_volume_gb,
+            tokens_per_gb_kvcache=config.tokens_per_gb_kvcache,
+            my_param=args.mw_my_param,
+        )
+        return MyWorkload(wl_config, request_sender, stats_collector, progress_monitor, seed=config.seed)
+    ...
+```
+
+### Step 3: Add CLI args
+
+In `engine_bench/command.py`, inside `register_engine_parser()`:
+
+1. Add `"my-workload"` to the `--workload` choices list.
+2. Add a new argument group with **prefixed** arg names:
+
+```python
+mw_group = parser.add_argument_group("my-workload workload options")
+mw_group.add_argument("--mw-my-param", type=int, default=100, help="...")
+```
+
+All workload-specific args must be prefixed with a short workload identifier
+(e.g., `ldqa-`, `ldp-`, `mrc-`, `psf-`, `rp-`, `mw-`) to avoid name collisions.
+
+### Step 4: Add tests
+
+Create `tests/cli/commands/bench/engine_bench/workloads/test_my_workload.py`
+with tests for:
+
+- Config validation (`__post_init__` raises on invalid values)
+- Config resolution (`resolve()` computes derived fields correctly)
+- Workload data generation
+- `warmup()` behavior (async)
+- `step()` dispatch logic and return values (async)
+- `on_request_finished()` behavior
+- `run()` end-to-end with mocked `RequestSender`
+
+Add factory tests to `test_create_workload.py`.
+
+### Key Design Constraints
+
+- **`step()` must not block indefinitely.** It should dispatch or wait
+  briefly and return. The loop handles sleeping between calls.
+- **`on_request_finished()` runs on the loop thread** (via queue drain),
+  not the async sender thread. No locking needed within the workload.
+- **`log_config()` prints via `print()`**, not `log_message()`, because
+  it runs before the progress monitor starts. Use ANSI colors for
+  readability.
+- **Use `progress_monitor.log_message()`** for all runtime logging during
+  the benchmark to avoid corrupting the terminal display.
+- **Warmup stats are discarded** — `stats_collector.reset()` is called
+  after warmup, so warmup request metrics don't affect final results.
+
+---
+
+## 6. Tests
+
+```bash
+# All bench tests (~190 tests)
+pytest -xvs tests/cli/commands/bench/
+
+# Specific workload
+pytest -xvs tests/cli/commands/bench/engine_bench/workloads/test_long_doc_qa.py
+pytest -xvs tests/cli/commands/bench/engine_bench/workloads/test_multi_round_chat.py
+pytest -xvs tests/cli/commands/bench/engine_bench/workloads/test_random_prefill.py
+
+# Factory
+pytest -xvs tests/cli/commands/bench/engine_bench/workloads/test_create_workload.py
+
+# CLI registration + orchestrator
+pytest -xvs tests/cli/commands/bench/test_bench_command.py
+```
diff --git a/docs/design/cli/commands/describe.md b/docs/design/cli/commands/describe.md
new file mode 100644
index 0000000..7c0770c
--- /dev/null
+++ b/docs/design/cli/commands/describe.md
@@ -0,0 +1,476 @@
+# `lmcache describe` — Design & Implementation Plan
+
+**Status:** Proposal  |  **Date:** 2026-03-19
+
+## Context
+
+The CLI framework (Phase 0) is complete — `BaseCommand`, `Metrics`, `MockCommand`,
+and entry point are all working. The next step (Phase 1 per
+[commands.md](../commands.md)) is to implement `lmcache describe kvcache`, which
+provides a rich status dashboard of a running LMCache KV cache service.
+
+`describe engine` (Phase 2) is now implemented — see the
+[`describe engine`](#lmcache-describe-engine) section below.
+
+---
+
+## Command UX
+
+```bash
+$ lmcache describe kvcache --url http://localhost:8000
+
+============ LMCache KV Cache Service ============
+Health:                                  OK
+ZMQ endpoint:                            tcp://localhost:5555
+HTTP endpoint:                           http://localhost:8000
+Engine type:                             blend
+Chunk size:                              256
+L1 capacity (GB):                        60.00
+L1 used (GB):                            42.30 (70.5%)
+Eviction policy:                         LRU
+Cached objects:                          1024
+Active sessions:                         3
+Uptime:                                  2h 14m 32s
+------ Model: meta-llama/Llama-3.1-70B-Instruct ---
+World size:                              4
+GPU IDs:                                 0, 1, 2, 3
+Num layers:                              80
+Num blocks:                              2048
+Cache size per token (bytes):            327680
+--- Kernel group 0 (meta-llama/Llama-3.1-70B-Instruct) ---
+Kernel group index:                      0
+Engine group index:                      0
+Object group index:                      0
+Num layers:                              80
+Slots per block:                         128
+Dtype:                                   torch.float16
+MLA:                                     False
+Attention backend:         vLLM non-MLA flash attention
+Engine KV shape:           NL x [2, NB, BS, NH, HS]
+Engine KV tensor shape:    80 x [2, 2048, 128, 8, 128]
+----------- L2: NixlStoreL2Adapter ------------
+Type:                          NixlStoreL2Adapter
+Health:                                  OK
+Backend:                                 nixl_rdma
+Stored objects:                          512
+Pool used:                     480 / 512 (93.8%)
+==================================================
+```
+
+JSON output collects model and L2 adapter sections into lists for easier
+programmatic access:
+
+```json
+{
+  "title": "LMCache KV Cache Service",
+  "metrics": {
+    "health": "OK",
+    "url": "http://localhost:8000",
+    "engine_type": "blend",
+    ...
+    "models": [
+      {
+        "model": "meta-llama/Llama-3.1-70B-Instruct",
+        "world_size": 4,
+        "gpu_ids": "0, 1, 2, 3",
+        "num_layers": 80,
+        "num_blocks": 2048,
+        "cache_size_per_token": 327680
+      }
+    ],
+    "kernel_groups": [
+      {
+        "model": "meta-llama/Llama-3.1-70B-Instruct",
+        "kernel_group_idx": 0,
+        "engine_group_idx": 0,
+        "object_group_idx": 0,
+        "num_layers": 80,
+        "slots_per_block": 128,
+        "dtype": "torch.float16",
+        "is_mla": false,
+        "attention_backend": "vLLM non-MLA flash attention",
+        "engine_kv_shape": "NL x [2, NB, BS, NH, HS]",
+        "engine_kv_concrete_shape": "80 x [2, 2048, 128, 8, 128]"
+      }
+    ],
+    "l2_adapters": [
+      {
+        "type": "NixlStoreL2Adapter",
+        "health": "OK",
+        "backend": "nixl_rdma",
+        "stored_object_count": 512,
+        "pool_used": "480 / 512 (93.8%)"
+      }
+    ]
+  }
+}
+```
+
+Per-model sections are generated for each unique `(model_name, world_size)` pair
+registered with the engine. The model section carries the context-wide fields —
+`num_layers`, `num_blocks`, and `cache_size_per_token` — and is followed by one
+**kernel group** section per kernel group, since a hybrid model's groups can
+differ in geometry.
+
+Each kernel group section includes:
+
+- **Kernel / engine / object group index** — the group's identity:
+  `kernel_group_idx` enumerates the manager's kernel groups, `engine_group_idx`
+  is the paged-block address space (0 for non-hybrid), and `object_group_idx` is
+  the owning object group.
+- **Num layers** and **Slots per block** — the group's layer count and
+  `shape_desc.bs`.
+- **Dtype** and **MLA** — the group's torch dtype and MLA flag.
+- **Attention backend** — which attention implementation is active (e.g.,
+  `vLLM non-MLA flash attention`, `vLLM MLA`, `SGLang MHA`), derived from the
+  `EngineKVFormat` enum.
+- **Engine KV shape** — the symbolic tensor layout using short names matching the
+  `EngineKVFormat` enum (NB=num_blocks, NL=num_layers, BS=block_size, NH=num_heads,
+  HS=head_size, PBS=page_buffer_size). E.g., `NL x [2, NB, BS, NH, HS]`.
+- **Engine KV tensor shape** — the same layout with actual numeric values substituted
+  from the group's `shape_desc` (e.g., `80 x [2, 2048, 128, 8, 128]`), so it is
+  group-accurate.
+
+L2 adapter sections are generated for each adapter in
+`storage_manager.l2_adapters`. Fields shown depend on the adapter type:
+
+- **Type** and **Health** — always shown.
+- **Backend** — Nixl adapter backend (e.g., `nixl_rdma`).
+- **Base path** — filesystem adapter storage directory.
+- **Stored objects** — number of cached objects (Mock, Nixl).
+- **Used** — size used vs capacity with percentage (Mock).
+- **Pool used** — pool slots used vs total with percentage (Nixl).
+
+---
+
+## `lmcache describe engine`
+
+`describe engine` is the engine-side counterpart to `describe kvcache`. Where
+`kvcache` inspects the LMCache service, `engine` inspects the **inference
+engine** (vLLM) that LMCache is paired with, reading only the engine's own HTTP
+surface.
+
+```bash
+$ lmcache describe engine --url http://localhost:8000
+
+================ Inference Engine ================
+Model:                  meta-llama/Llama-3.1-8B-Instruct
+Max context (tokens):   131072
+Status:                 OK
+Running requests:       3
+==================================================
+```
+
+```json
+{
+  "title": "Inference Engine",
+  "metrics": {
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "max_context": 131072,
+    "status": "OK",
+    "running_requests": 3
+  }
+}
+```
+
+### Data sources
+
+Unlike `kvcache` (a single `/status` call), `engine` composes three vLLM
+endpoints, so no LMCache-server cooperation is required:
+
+| Display label | Machine key | Source |
+|---|---|---|
+| Model | `model` | `/v1/models` → `data[0].id` |
+| Max context (tokens) | `max_context` | `/v1/models` → `data[0].max_model_len` |
+| Status | `status` | `/health` HTTP 200 → `"OK"` / `"UNHEALTHY"` |
+| Running requests | `running_requests` | `/metrics` → sum of `vllm:num_requests_running` series |
+
+`--url` defaults to `http://localhost:8000` (the engine default; `kvcache`
+defaults to `http://localhost:8080`).
+
+### Error handling
+
+| Condition | Behavior |
+|---|---|
+| `/v1/models` unreachable / errors | Print error to stderr, exit 1 (same as `kvcache`) |
+| `/health` not reachable or non-200 | `Status: UNHEALTHY` (does not fail the command) |
+| `/metrics` unreachable or metric absent | `Running requests: N/A` (best-effort; metric is informational) |
+| Empty model list | `Model` / `Max context` render as `N/A` |
+
+The `/health` and `/metrics` lookups are intentionally non-fatal: an engine that
+is up but has metrics disabled, or is momentarily unhealthy, still yields a
+useful report rather than a hard failure. Only the primary `/v1/models` fetch
+exits non-zero on failure.
+
+---
+
+## Design Decisions
+
+### 1. Sub-target as positional argument
+
+```
+lmcache describe kvcache --url http://localhost:8000
+lmcache describe engine  --url http://localhost:8000
+```
+
+Uses a positional `target` argument with `choices=["kvcache", "engine"]`,
+matching the `describe {kvcache,engine}` pattern in
+[commands.md](../commands.md). Each target resolves its own default `--url`
+(`8080` for `kvcache`, `8000` for `engine`) via the `DEFAULT_URLS` map.
+
+### 2. `--url` points to the HTTP endpoint
+
+The original design doc example shows `--url localhost:5555` (ZMQ port), but also
+states that `describe kvcache` "gathers data from ... `/status` (HTTP)". The
+HTTP `/status` endpoint already exposes **all** data needed (engine type, chunk
+size, L1 memory, eviction policy, cached objects, health, sessions, etc.). Using
+HTTP as the sole data source keeps the CLI simple — no ZMQ client needed.
+
+`--url` accepts the HTTP base URL (e.g., `http://localhost:8000`). The command
+normalizes it (adds `http://` if missing) and appends `/status`.
+
+### 3. Output fields mapped from `/status`
+
+| Display label | Machine key | Source in `/status` response |
+|---|---|---|
+| Health | `health` | `is_healthy` → `"OK"` / `"UNHEALTHY"` |
+| ZMQ endpoint | `zmq_endpoint` | `zmq_endpoint` **(new — see Server-Side Changes)** |
+| HTTP endpoint | `http_endpoint` | `http_endpoint` **(new — see Server-Side Changes)** |
+| Engine type | `engine_type` | `engine_type` |
+| Chunk size | `chunk_size` | `chunk_size` |
+| L1 capacity (GB) | `l1_capacity_gb` | `storage_manager.l1_manager.memory_total_bytes` / 1024^3 |
+| L1 used (GB) | `l1_used_gb` | `storage_manager.l1_manager.memory_used_bytes` / 1024^3, with `memory_usage_ratio` × 100 for % |
+| Eviction policy | `eviction_policy` | `storage_manager.eviction_controller.eviction_policy` |
+| Cached objects | `cached_objects` | `storage_manager.l1_manager.total_object_count` |
+| Active sessions | `active_sessions` | `active_sessions` |
+| Uptime | `uptime` | `uptime_seconds` **(new — see Server-Side Changes)**, formatted as `Xh Ym Zs` |
+
+### 4. HTTP client: stdlib `urllib`
+
+No new dependencies. Uses `urllib.request` following the same pattern as the
+existing `lmcache/tools/mp_status_viewer/__main__.py`.
+
+### 5. Error handling
+
+| Condition | Behavior |
+|---|---|
+| Connection refused / timeout | Print error to stderr, exit 1 |
+| HTTP 503 (engine not initialized) | Print "Server unhealthy: engine not initialized", exit 1 |
+| Missing fields in response | Display as `N/A` (Metrics default for `None` values) |
+
+---
+
+## Server-Side Changes
+
+Three fields in the design doc's `describe kvcache` output are **not currently
+available** from `/status`. The following changes surface them.
+
+### 1. Add `start_time` to `MPCacheServer` → expose `uptime_seconds`
+
+**File:** `lmcache/v1/multiprocess/server.py`
+
+`MPCacheServer.__init__()` (line 147) records `self._start_time = time.monotonic()`
+at construction. `report_status()` (line 696) includes a new field:
+
+```python
+"uptime_seconds": time.monotonic() - self._start_time,
+```
+
+The CLI formats this as a human-readable string (e.g., `2h 14m 32s`).
+
+### 2. Pass endpoint addresses into `MPCacheServer` → expose in status
+
+**File:** `lmcache/v1/multiprocess/server.py`
+
+Currently `MPCacheServer` does not know the ZMQ or HTTP addresses — those live in
+`MPServerConfig` and `HTTPFrontendConfig`, which are only available in
+`run_cache_server()` / `run_http_server()`.
+
+**Option A — engine constructor params:** Add optional `zmq_endpoint: str | None`
+and `http_endpoint: str | None` kwargs to `MPCacheServer.__init__()`. Callers
+(`run_cache_server` at line 787, and the blend variant) pass these when available.
+`report_status()` includes them.
+
+**Option B — set after construction:** Add setter methods or attrs that
+`run_cache_server()` / `run_http_server()` set after creating the engine, before
+returning it. This avoids changing the constructor signature.
+
+**Recommendation:** Option A is simpler and more explicit.
+
+```python
+# In run_cache_server() (line 787):
+engine = MPCacheServer(
+    storage_manager_config=storage_manager_config,
+    chunk_size=mp_config.chunk_size,
+    hash_algorithm=mp_config.hash_algorithm,
+    zmq_endpoint=f"tcp://{mp_config.host}:{mp_config.port}",
+)
+
+# In run_http_server() lifespan (line 77):
+# After engine is created, set http_endpoint:
+engine.http_endpoint = f"http://{http_config.http_host}:{http_config.http_port}"
+```
+
+Note: The ZMQ endpoint is known at `run_cache_server()` time, but the HTTP
+endpoint is only known in `run_http_server()`. Since `run_http_server()` calls
+`run_cache_server(return_engine=True)` and gets back the engine, it can set
+`http_endpoint` after construction. So a hybrid approach works:
+- `zmq_endpoint` passed via constructor (always available)
+- `http_endpoint` set as an attribute after construction (only when HTTP frontend
+  is enabled)
+
+`report_status()` returns both:
+
+```python
+"zmq_endpoint": self.zmq_endpoint,
+"http_endpoint": getattr(self, "http_endpoint", None),
+```
+
+### 3. Same changes for `BlendCacheEngine`
+
+**File:** `lmcache/v1/multiprocess/blend_server.py` (and `blend_server_v2.py`)
+
+Mirror the same `start_time`, `zmq_endpoint`, and `http_endpoint` additions if
+`BlendCacheEngine` has its own `report_status()`. If it delegates to
+`MPCacheServer`, no separate change is needed.
+
+### Summary of server-side changes
+
+| Field | Where | Change |
+|---|---|---|
+| `uptime_seconds` | `MPCacheServer.__init__` + `report_status()` | Record `time.monotonic()` at init, compute delta in status |
+| `zmq_endpoint` | `MPCacheServer.__init__` + `run_cache_server()` | New constructor kwarg, passed from `MPServerConfig` |
+| `http_endpoint` | `run_http_server()` lifespan + `report_status()` | Set on engine after construction when HTTP is enabled |
+
+### 4. Expose engine KV format, shape, and attention backend in `kv_cache_layout`
+
+**Files:** `lmcache/v1/gpu_connector/utils.py`, `lmcache/v1/platform/cuda/cache_context.py`, `lmcache/v1/multiprocess/server.py`
+
+Helper functions in `utils.py` (derived from `legible_print_engine_kv_format()`):
+- `get_engine_kv_shape_description(engine_kv_format)` — symbolic shape (e.g., `NL x [2, NB, BS, NH, HS]`)
+- `get_attention_backend(engine_kv_format)` — backend name (e.g., `vLLM non-MLA flash attention`)
+- `get_concrete_engine_kv_shape(kv_caches, engine_kv_format)` — whole-context shape with actual values
+- `get_concrete_engine_kv_shape_from_shape_desc(shape_desc, engine_kv_format)` — **group-accurate** shape with actual values, read from a single kernel group's `PageBufferShapeDesc` (used by `report_status`)
+
+`report_status()` is organised **per kernel group**: a small set of context-wide
+fields at the top level, plus a `kernel_groups` list where each entry is
+self-describing. The format-derived fields (`engine_kv_format`, `engine_kv_shape`,
+`attention_backend`, `is_mla`) and the group-accurate `engine_kv_concrete_shape`
+live inside each group:
+
+```python
+"kv_cache_layout": {
+    "num_layers": 80,
+    "num_blocks": 2048,
+    "cache_size_per_token": 327680,
+    "kernel_groups": [
+        {
+            "kernel_group_idx": 0,
+            "engine_group_idx": 0,
+            "object_group_idx": 0,
+            "num_layers": 80,
+            "layer_indices": [0, 1, ...],
+            "tokens_per_block": 128,
+            "slots_per_block": 128,
+            "dtype": "torch.float16",
+            "engine_kv_concrete_shape": "80 x [2, 2048, 128, 8, 128]",
+            "is_mla": false,
+            "engine_kv_format": "NL_X_TWO_NB_BS_NH_HS",
+            "engine_kv_shape": "NL x [2, NB, BS, NH, HS]",
+            "attention_backend": "vLLM non-MLA flash attention",
+        },
+    ],
+}
+```
+
+---
+
+## CLI Implementation
+
+### New file: `lmcache/cli/commands/describe.py`
+
+```python
+class DescribeCommand(BaseCommand):
+    name() → "describe"
+    help() → "Show detailed status of a running LMCache service."
+
+    add_arguments(parser):
+        parser.add_argument("target", choices=["kvcache", "engine"],
+                            help="What to describe.")
+        parser.add_argument("--url", default=None,
+                            help="Server URL (per-target default applied)")
+
+    execute(args):
+        if args.url is None:
+            args.url = DEFAULT_URLS[args.target]
+        if args.target == "kvcache":
+            self._describe_kvcache(args)
+        elif args.target == "engine":
+            self._describe_engine(args)
+
+    _describe_kvcache(args):
+        1. Normalize URL (ensure http:// prefix)
+        2. Fetch JSON from {url}/status (timeout=10s)
+        3. On error: print to stderr, sys.exit(1)
+        4. Extract fields from nested response dict
+        5. Format uptime_seconds → "Xh Ym Zs"
+        6. Format L1 used bytes → "XX.XX (YY.Y%)"
+        7. Build flat Metrics via self.create_metrics() (width=48)
+        8. metrics.emit()
+```
+
+Module-level helpers:
+
+```python
+def _fetch_json(url: str, timeout: int = 10) -> dict:
+    """GET *url*, return parsed JSON. Raises on HTTP/network errors."""
+
+def _normalize_url(url: str) -> str:
+    """Ensure URL has http:// scheme, strip trailing slash."""
+
+def _fmt_uptime(seconds: float) -> str:
+    """Format seconds as 'Xh Ym Zs'."""
+
+def _fmt_used_gb(used_bytes: int, ratio: float) -> str:
+    """Format as 'XX.XX (YY.Y%)'."""
+```
+
+### Modify: `lmcache/cli/commands/__init__.py`
+
+Add import and registry entry:
+
+```python
+from lmcache.cli.commands.describe import DescribeCommand
+
+ALL_COMMANDS: list[BaseCommand] = [
+    MockCommand(),
+    DescribeCommand(),
+]
+```
+
+### Patterns to follow
+
+- **Reuse `BaseCommand.create_metrics()`** — auto-handles `--format` and `--output`
+  flags (see `base.py`).
+- **Flat metrics, no sections** — all fields at top level, matching the design doc
+  output style. Use `metrics.add(key, label, value)` directly.
+- **Width = 48** — matches the divider width in `commands.md` examples.
+
+---
+
+## Verification
+
+1. **Unit test:** Test `_normalize_url()`, `_fmt_uptime()`, `_fmt_used_gb()`, and
+   field extraction logic with a synthetic `/status` response dict (no live
+   server needed).
+2. **Manual test against running server:**
+   ```bash
+   lmcache describe kvcache --url http://localhost:8000
+   lmcache describe kvcache --url http://localhost:8000 --format json
+   lmcache describe kvcache --url localhost:8000          # auto-prefix http://
+   lmcache describe kvcache --url http://localhost:8000 --output status.json
+   lmcache describe kvcache --url http://localhost:9999   # connection refused → exit 1
+   ```
+3. **JSON output:** Verify machine keys are snake_case and values are raw types
+   (not display-formatted strings), except `l1_used_gb` and `uptime` which include
+   human-readable formatting.
diff --git a/docs/design/cli/commands/kvcache-command.md b/docs/design/cli/commands/kvcache-command.md
new file mode 100644
index 0000000..5239787
--- /dev/null
+++ b/docs/design/cli/commands/kvcache-command.md
@@ -0,0 +1,254 @@
+# `lmcache kvcache` CLI Command Design
+
+**Status:** Proposal  |  **Date:** 2026-03-19
+
+## Why
+
+Users need a way to manage KV cache state for **specific requests** from the
+command line — pin a request's cache to prevent eviction, compress it, or clear
+it. Part of **Phase 1** of the
+[CLI design](../commands.md).
+
+---
+
+## Design Principles
+
+`lmcache kvcache` is a **per-request management tool**. Every sub-command
+operates on a specific request's KV cache, identified by request ID or token
+sequence.
+
+### All management goes through HTTP
+
+ZMQ is reserved for **performance-critical data-path** communication between the
+inference engine and LMCache (store, retrieve, prefetch). Every `lmcache kvcache`
+CLI operation goes through the **MP HTTP server**
+(`lmcache/v1/multiprocess/http_server.py`).
+
+Today some operations (e.g. `pin`) only have ZMQ implementations. These
+need new HTTP endpoints on the MP HTTP server before the CLI can use them.
+
+### Indexing KV caches
+
+Per-request sub-commands (`pin`, `compress`, `info`) take a **positional
+request ID** and optional range flags:
+
+- **`<request_id>`** (positional, required) — identifies the request whose
+  KV cache to operate on.
+- **`--start <st> --end <ed>`** (optional) — narrow the operation to a token
+  range `[st, ed)` within the request. Defaults to the full sequence.
+
+`clear` is a **bulk operation** — it clears all L1 cache and does not take a
+request ID.
+
+### Pipe- and script-friendly output
+
+- **Exit codes:** `0` = success, `1` = error, `2` = rejected (e.g. pin rejected
+  due to memory pressure). Scripts branch on `$?` without parsing output.
+- **`--format json`:** Structured output for piping into `jq` (already exists).
+- **`--format terminal`:** Human-readable ASCII table (default, already exists).
+- **`--quiet` / `-q`:** Suppress all stdout. Exit code only.
+- **Stdout vs stderr:** Metrics to stdout (pipeable). Errors to stderr.
+
+---
+
+## Command Overview
+
+```
+lmcache kvcache
+├── info           # Per-request cache state (locations, pinned status)
+├── clear          # Clear all cached KV data in L1 (CPU)
+├── pin            # Pin a request's KV cache to L1/CPU (may be rejected)
+└── compress       # Compress a request's KV cache in-place
+```
+
+| Sub-command | Target | Description |
+|------------|--------|-------------|
+| `info` | instance | Show per-request cache state: which chunks, where stored, pinned status |
+| `clear` | instance | Clear all cached KV data in L1 (CPU) |
+| `pin` | instance | Pin a request's KV cache to L1/CPU; may be rejected if memory pressure is too high |
+| `compress` | instance | Compress a request's KV cache to reduce memory footprint |
+
+```bash
+$ lmcache kvcache -h
+usage: lmcache kvcache [-h] {clear} ...
+
+Manage KV cache state.
+
+subcommands:
+  clear         Clear all cached KV data in L1 (CPU)
+
+# info, pin, compress will appear here once implemented
+```
+
+---
+
+## Commands in Detail
+
+### `info`
+
+> **Status: needs further design — will not be implemented yet.**
+> The output format, filtering options, and server-side endpoint are TBD.
+> The sketch below is a placeholder to illustrate intent.
+
+Show the cache state for a specific request: which chunks exist, which storage
+backend holds each one, and whether they are pinned.
+
+```bash
+# By request ID
+$ lmcache kvcache info --url http://localhost:8000 req-abc-123
+
+===== KV Cache Info (req-abc-123) =====
+Total chunks:                         32
+Pinned:                                8
+---------------- Chunks ---------------
+[0:256]:                  L1, pinned
+[256:512]:                L1, pinned
+[512:768]:                L1, L2
+[768:1024]:               L2
+...
+========================================
+
+# Narrowed to a token range
+$ lmcache kvcache info --url http://localhost:8000 \
+    req-abc-123 --start 0 --end 512
+
+# JSON for scripting
+$ lmcache kvcache info --url http://localhost:8000 \
+    req-abc-123 --format json
+{
+  "title": "KV Cache Info (req-abc-123)",
+  "metrics": {
+    "total_chunks": 32,
+    "pinned": 8,
+    "chunks": {
+      "0:256": "L1, pinned",
+      "256:512": "L1, pinned",
+      "512:768": "L1, L2",
+      "768:1024": "L2"
+    }
+  }
+}
+
+# Find chunks on L2
+$ lmcache kvcache info --url http://localhost:8000 \
+    req-abc-123 --format json \
+    | jq '.metrics.chunks | to_entries[] | select(.value | contains("L2"))'
+```
+
+### `clear`
+
+Clear all cached KV data in **L1 (CPU memory)** on the target instance.
+
+```bash
+$ lmcache kvcache clear --url http://localhost:8000
+
+========== KV Cache Clear ==================
+Status:                                   OK
+=============================================
+```
+
+### `pin`
+
+Pin a request's KV cache chunks to L1 (CPU memory) to prevent eviction. The
+server **may reject** the request if CPU memory pressure is too high.
+
+Exit codes: `0` = pinned, `2` = rejected, `1` = error.
+
+```bash
+$ lmcache kvcache pin --url http://localhost:8000 req-abc-123
+
+======== KV Cache Pin (req-abc-123) ========
+Status:                                   OK
+Chunks pinned:                            32
+=============================================
+$ echo $?
+0
+
+# Quiet mode for scripts
+if lmcache kvcache pin -q --url http://localhost:8000 req-abc-123; then
+    echo "pinned"
+else
+    echo "rejected or error"
+fi
+
+# Narrowed to a token range
+$ lmcache kvcache pin --url http://localhost:8000 \
+    req-abc-123 --start 0 --end 512
+
+# Rejected case (exit code 2)
+$ lmcache kvcache pin --url http://localhost:8000 req-xyz
+
+======== KV Cache Pin (req-xyz) =============
+Status:                             REJECTED
+Reason:              L1 memory pressure (91%)
+=============================================
+$ echo $?
+2
+```
+
+### `compress`
+
+Compress a request's KV cache chunks in-place to reduce memory footprint.
+
+```bash
+$ lmcache kvcache compress --url http://localhost:8000 \
+    req-abc-123 --method zstd
+
+===== KV Cache Compress (req-abc-123) ======
+Status:                                   OK
+Method:                                 zstd
+Chunks compressed:                        32
+=============================================
+
+$ lmcache kvcache compress --url http://localhost:8000 \
+    req-abc-123 --start 0 --end 512 --method zstd
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `<request_id>` | yes (positional) | Target request |
+| `--method` | yes | Compression method (e.g. `zstd`) |
+| `--start`, `--end` | no | Narrow to token range `[st, ed)` |
+
+---
+
+## Existing API Surface & Gaps
+
+All CLI operations target the **MP HTTP server**
+(`lmcache/v1/multiprocess/http_server.py`).
+
+### Usable today (no new endpoints needed)
+
+| CLI sub-command | Existing MP HTTP endpoint | Notes |
+|----------------|--------------------------|-------|
+| `clear` | `POST /cache/clear` | Clears all L1 cache. Works as-is. |
+
+### Needs new MP HTTP endpoints
+
+| CLI sub-command | What exists today | New endpoint needed on MP HTTP server |
+|----------------|------------------|---------------------------------------|
+| `info` | No per-request HTTP endpoint | `GET /kvcache-info?request_id=...` returning chunk ranges, locations, pinned status |
+| `pin` | ZMQ only (no HTTP) | `POST /pin` accepting request-id, returning OK or REJECTED with reason |
+| `compress` | ZMQ only (no HTTP) | `POST /compress` accepting request-id + method |
+
+---
+
+## Implementation
+
+- **Single `KVCacheCommand`** (`BaseCommand` subclass) with second-level
+  argparse subparsers. File: `lmcache/cli/commands/kvcache.py`.
+- **MP HTTP only:** `_http_request()` wraps `urllib.request` (no new deps).
+  All requests target the MP HTTP server.
+- **Indexing args** for future per-request sub-commands: positional
+  `request_id` + optional `--start`/`--end`, added via a shared helper.
+- **Output:** `self.create_metrics()` — use `--format json | jq` for scripting.
+- **New `--quiet` / `-q` flag** on `BaseCommand`: skips `StreamHandler`.
+- **Exit codes:** `0` success, `1` error, `2` rejected. Errors to stderr.
+
+## Phasing
+
+| Phase | Work |
+|-------|------|
+| **1a** | `clear` (HTTP exists) |
+| **1b** | `pin` (needs per-instance endpoint), `compress` (needs per-instance endpoint) |
+| **future** | `info` (needs further design — deferred) |
diff --git a/docs/design/cli/commands/ping.md b/docs/design/cli/commands/ping.md
new file mode 100644
index 0000000..9b9f209
--- /dev/null
+++ b/docs/design/cli/commands/ping.md
@@ -0,0 +1,221 @@
+# `lmcache ping` — Design & Implementation Plan
+
+**Status:** Proposal  |  **Date:** 2026-03-23
+
+## Context
+
+The CLI framework (Phase 0) and `describe kvcache` (Phase 1, PR #2825) are
+complete. The next Phase 1 command is `lmcache ping`, a pure liveness check for
+the LMCache server process and the vLLM server process.
+
+---
+
+## Command UX
+
+```bash
+$ lmcache ping kvcache --url http://localhost:8080
+
+======= Ping KV Cache =======
+Status:                  OK
+Round trip time (ms):    0.42
+==============================
+```
+
+```bash
+$ lmcache ping engine --url http://localhost:8000
+
+======== Ping Engine =========
+Status:                  OK
+Round trip time (ms):    12.3
+==============================
+```
+
+JSON output:
+
+```bash
+$ lmcache ping kvcache --url http://localhost:8080 --format json
+```
+
+```json
+{
+  "title": "Ping KV Cache",
+  "metrics": {
+    "status": "OK",
+    "round_trip_time_ms": 0.42
+  }
+}
+```
+
+```bash
+$ lmcache ping engine --url http://localhost:8000 --format json
+```
+
+```json
+{
+  "title": "Ping Engine",
+  "metrics": {
+    "status": "OK",
+    "round_trip_time_ms": 12.3
+  }
+}
+```
+
+---
+
+## Design Decisions
+
+### 1. Sub-target as positional argument
+
+```
+lmcache ping kvcache --url http://localhost:8080
+lmcache ping engine  --url http://localhost:8000
+```
+
+Uses a positional `target` argument with `choices=["kvcache", "engine"]`.
+Matches the `ping {kvcache,engine}` pattern in [commands.md](../commands.md).
+
+### 2. Both targets use HTTP
+
+Both `ping kvcache` and `ping engine` use a simple HTTP GET to the respective
+server's health endpoint. No ZMQ client is needed.
+
+| Target | Server process | Endpoint | Healthy | Unhealthy |
+|--------|---------------|----------|---------|-----------|
+| `kvcache` | LMCache MP server | `GET /healthcheck` | 200 `{"status": "healthy"}` | 503 `{"status": "unhealthy", "reason": "..."}` |
+| `engine` | vLLM server | `GET /health` | 200 (empty body) | 503 (empty body) |
+
+### 3. `--url` defaults
+
+| Target | Default URL |
+|--------|-------------|
+| `kvcache` | `http://localhost:8080` |
+| `engine` | `http://localhost:8000` |
+
+The default for `kvcache` matches `describe kvcache`. The default for `engine`
+matches the standard vLLM serving port.
+
+### 4. Round-trip time measurement
+
+The round-trip time measures only the HTTP request-response cycle, using
+`time.monotonic()` around the `urllib.request.urlopen()` call. This excludes
+Python startup, argument parsing, and output formatting overhead.
+
+### 5. HTTP client: stdlib `urllib`
+
+Same as `describe` — uses `urllib.request` with no new dependencies.
+
+### 6. Error handling
+
+| Condition | Status | Exit code |
+|-----------|--------|-----------|
+| 200 response | OK | 0 |
+| 503 response | FAIL | 1 |
+| Connection refused / timeout | FAIL (with error detail) | 1 |
+| Other HTTP error | FAIL (with HTTP status) | 1 |
+
+On failure, `status` is reported as `"FAIL"` and the round-trip time is still
+reported (it shows how long we waited before the error). A detail message is
+printed to stderr.
+
+---
+
+## CLI Implementation
+
+### New file: `lmcache/cli/commands/ping.py`
+
+```python
+class PingCommand(BaseCommand):
+    name() → "ping"
+    help() → "Ping LMCache or vLLM server (liveness check)."
+
+    add_arguments(parser):
+        parser.add_argument("target", choices=["kvcache", "engine"],
+                            help="What to ping.")
+        parser.add_argument("--url", default=None,
+                            help="Server URL (default: http://localhost:8080 "
+                                 "for kvcache, http://localhost:8000 for engine)")
+
+    execute(args):
+        url = args.url or DEFAULT_URLS[args.target]
+        url = normalize_url(url)
+        endpoint = HEALTH_ENDPOINTS[args.target]  # "/healthcheck" or "/health"
+        title = TITLES[args.target]               # "Ping KV Cache" or "Ping Engine"
+
+        status, rtt_ms, error = ping(f"{url}{endpoint}")
+
+        metrics = self.create_metrics(title, args, width=30)
+        metrics.add("status", "Status", status)
+        metrics.add("round_trip_time_ms", "Round trip time (ms)", round(rtt_ms, 2))
+        metrics.emit()
+
+        if error:
+            print(error, file=sys.stderr)
+            sys.exit(1)
+```
+
+Module-level helper:
+
+```python
+HEALTH_ENDPOINTS = {"kvcache": "/healthcheck", "engine": "/health"}
+DEFAULT_URLS = {"kvcache": "http://localhost:8080", "engine": "http://localhost:8000"}
+TITLES = {"kvcache": "Ping KV Cache", "engine": "Ping Engine"}
+
+def ping(url: str, timeout: int = 10) -> tuple[str, float, str | None]:
+    """GET *url* and return (status, rtt_ms, error_msg).
+
+    Returns:
+        ("OK", rtt_ms, None) on 200.
+        ("FAIL", rtt_ms, detail) on error.
+    """
+    start = time.monotonic()
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            rtt_ms = (time.monotonic() - start) * 1000
+            if resp.status == 200:
+                return ("OK", rtt_ms, None)
+            return ("FAIL", rtt_ms, f"HTTP {resp.status}")
+    except urllib.error.HTTPError as exc:
+        rtt_ms = (time.monotonic() - start) * 1000
+        return ("FAIL", rtt_ms, f"HTTP {exc.code}: {exc.reason}")
+    except (urllib.error.URLError, OSError) as exc:
+        rtt_ms = (time.monotonic() - start) * 1000
+        reason = getattr(exc, "reason", str(exc))
+        return ("FAIL", rtt_ms, f"Cannot connect to {url}: {reason}")
+```
+
+Reuses `normalize_url()` from `describe.py` (import it, or move to a shared
+`lmcache/cli/utils.py` if preferred).
+
+### Modify: `lmcache/cli/commands/__init__.py`
+
+```python
+from lmcache.cli.commands.ping import PingCommand
+
+ALL_COMMANDS: list[BaseCommand] = [
+    MockCommand(),
+    DescribeCommand(),
+    PingCommand(),
+]
+```
+
+---
+
+## Verification
+
+1. **Unit tests** (`tests/cli/test_ping.py`):
+   - Test `ping()` helper with a real local `HTTPServer` returning 200 and 503.
+   - Test connection refused (unreachable port) returns `"FAIL"`.
+   - Test `PingCommand.execute()` end-to-end with mocked `ping()` for both
+     targets, verifying JSON output fields.
+   - Test `--url` default resolution per target.
+2. **Manual tests:**
+   ```bash
+   lmcache ping kvcache --url http://localhost:8080
+   lmcache ping kvcache --url http://localhost:8080 --format json
+   lmcache ping engine  --url http://localhost:8000
+   lmcache ping engine  --url http://localhost:8000 --format json
+   lmcache ping kvcache --url http://localhost:9999   # connection refused → FAIL, exit 1
+   lmcache ping engine  --url http://localhost:9999   # connection refused → FAIL, exit 1
+   lmcache ping kvcache                               # uses default http://localhost:8080
+   lmcache ping engine                                # uses default http://localhost:8000
+   ```
diff --git a/docs/design/cli/commands/query-command.md b/docs/design/cli/commands/query-command.md
new file mode 100644
index 0000000..11f4064
--- /dev/null
+++ b/docs/design/cli/commands/query-command.md
@@ -0,0 +1,193 @@
+# `lmcache query` CLI Command Design
+
+**Status:** Proposal  |  **Date:** 2026-03-20
+
+## Goal
+Provide a formal single-shot query interface for both the serving engine and KV cache worker, with metrics output. besides normal request query to serving engine, offers the feature to query the detailed KV cache info by the request prompt.
+ 
+
+---
+
+## Design Principles
+
+### Single-shot, metrics-first command
+
+`lmcache query` performs exactly one request and reports latency + result metrics
+through the shared metrics framework (`BaseCommand.create_metrics()`), so users
+can choose `--format terminal` or `--format json`.
+
+### Two targets with one verb
+
+`query` has two second-level targets:
+
+- `query engine`: run one inference request and measure TTFT/TPOT/throughput.
+- `query kvcache`: inspect cache coverage for one prompt (lookup).
+ 
+### Script-friendly output and behavior
+
+- `--format json` produces machine-readable metrics.
+- `--output` writes the same formatted result to file.
+- Exit codes: `0` success, `1` error.
+- Errors go to stderr, metrics go to stdout.
+
+### Prompt corpora support
+
+Both subcommands accept prompt templates like `{ffmpeg}` and `{paul_graham}`,
+using the shared corpora expansion mechanism described in `commands.md`.
+
+---
+
+## Command Overview
+
+```text
+lmcache query
+├── engine    # Single inference query with latency/token metrics
+└── kvcache   # Single request cache lookup or round-trip verification
+```
+
+```bash
+$ lmcache query -h
+usage: lmcache query [-h] {engine,kvcache} ...
+
+Run one query and report metrics.
+
+subcommands:
+  engine      Run one inference request and report TTFT/TPOT metrics
+  kvcache     Query KV cache coverage or run store-retrieve round-trip
+```
+
+---
+
+## Commands in Detail
+
+### `query engine`
+
+Send one inference request to an engine HTTP endpoint and report token/latency metrics; ``--prompt`` supports placeholders, where ``{lmcache}`` loads ``lmcache/cli/documents/lmcache.txt`` and custom documents use ``--documents NAME=PATH``.
+ 
+
+```bash
+# Single inference query
+$ lmcache query engine --url http://localhost:8000/v1 \
+     --prompt "{lmcache} Summarize LMCache usage." \
+     --format terminal \
+     --max-tokens 128
+   
+================= Query Engine =================
+Model:                         facebook/opt-125m
+Prompt documents lmcache:                    608
+Prompt query:                                  9
+--------------- Latency Metrics ----------------
+Input tokens:                             618.00
+Output tokens:                              9.00
+TTFT (ms):                                 26.88
+TPOT (ms/token):                            0.91
+Total latency (ms):                        35.05
+Throughput (tokens/s):                   1100.64
+================================================
+```
+
+#### Proposed flags besides native engine query flags
+
+| Flag | Description |
+|------|-------------|
+| `--url` | Engine HTTP endpoint (`http://host:port`) |
+| `--prompt` | Prompt text, supports `{documents}` templates |
+| `--timeout` | Request timeout in seconds (default: 30) |
+| `--documents name=path` | Register custom documents template |
+
+
+
+#### Output metrics
+ 
+- `prompt_tokens`, `output_tokens`, `model`
+- `ttft_ms`, `tpot_ms_per_token`, `total_latency_ms`, `throughput_tokens_per_s`
+
+ 
+
+### `query kvcache`
+
+Two modes under one command:
+
+1. **Lookup mode (default):** tokenize prompt and query cache coverage.
+ 
+```bash
+# Lookup mode
+$ lmcache query kvcache --url http://localhost:5555 \
+    --prompt "{ctx} What is the example usage of lmcache?" \
+    --documents ctx=LMCache/lmcache/cli/documents/lmcache.txt  \
+    --model meta-llama/Llama-3.1-8B-Instruct
+
+======== Query KV Cache Result ==========
+Prompt tokens:                           8192
+Cached chunks:                       30/32 (93.8%)
+Cache locations:               [cpu=12, disk=0, ...]
+Cached tokens:                         7680/8192
+Cache status:                       HIT (partial)
+=========================================
+```
+ 
+
+#### Proposed flags
+
+| Flag | Description |
+|------|-------------|
+| `--url` | KV cache HTTP endpoint (`http://host:port`) |
+| `--prompt` | Prompt for tokenization + lookup |
+| `--model` | Tokenizer/model used to derive token IDs |
+| `--documents name=path` | Register custom documents template |
+
+#### Output metrics (lookup mode)
+
+- `prompt_tokens`
+- `cached_chunks_hit`
+- `cached_chunks_total`
+- `cached_chunk_location`
+- `cached_tokens_hit`
+- `cached_tokens_total`
+- `cache_status` (`HIT`, `MISS`, `HIT (partial)`)
+
+
+---
+
+## API Surface and Dependencies
+
+### `query engine`
+
+Uses inference engine HTTP APIs (OpenAI-compatible or engine-native endpoint),
+then computes CLI-side metrics from the single response stream/non-stream result.
+
+No new dependencies required: use stdlib `urllib.request` and existing helpers.
+
+### `query kvcache`
+
+All `lmcache query kvcache` CLI operations go through HTTP, using either the
+per-instance HTTP server or the controller HTTP server.
+ 
+
+---
+
+## Implementation
+
+- **Single `QueryCommand`** (`BaseCommand` subclass) with second-level
+  subparsers (`engine`, `kvcache`) in `lmcache/cli/commands/query.py`.
+- **`query engine`:** `PromptBuilder` (`lmcache/cli/prompt.py`) expands `{name}`
+  placeholders from `--documents`; top-level metrics include model plus per-slot
+  token estimates (e.g. prompt documents, prompt query). `Request`
+  (`lmcache/cli/request.py`) streams an OpenAI-compatible `/v1/chat/completions`
+  or `/v1/completions` request; **Latency Metrics** repeats server usage (labeled
+  **Input tokens**, not a duplicate client-side total).
+- **`query kvcache`:** stub; no handler yet.
+- **Errors:** `query_engine` catches `RuntimeError` / `ValueError`, prints the
+  message to stderr, exits `1`; unknown `query_target` prints to stderr and exits
+  `1`.
+
+---
+
+## Phasing
+
+| Phase | Work |
+|-------|------|
+| **1a** | `query engine` with prompt, max-tokens, TTFT/TPOT/throughput metrics |
+| **1b** | `query kvcache` lookup mode (prompt tokenization + cache coverage) |
+| **future** | richer query diagnostics (per-chunk detail) |
+
diff --git a/docs/design/cli/framework-and-metrics.md b/docs/design/cli/framework-and-metrics.md
new file mode 100644
index 0000000..d61e4ab
--- /dev/null
+++ b/docs/design/cli/framework-and-metrics.md
@@ -0,0 +1,381 @@
+# LMCache CLI Framework & Metrics System Design
+
+**Status:** Proposal  |  **Date:** 2026-03-14
+
+## Scope
+
+This document covers the **CLI framework** (pluggable command discovery) and the
+**hierarchical metrics logging system**. It is the implementation plan for Phase 1
+of the [CLI design](commands.md), minus the actual server/ping/describe commands
+(those come later). A `lmcache mock` command is included as a working example.
+
+---
+
+## 1. Explicit Command Registration
+
+### Goal
+
+Adding a new subcommand (e.g., `lmcache describe`) requires:
+
+1. Creating a new file in `lmcache/cli/commands/` with a `BaseCommand` subclass.
+2. Adding one import + one entry to `ALL_COMMANDS` in `commands/__init__.py`.
+
+### Mechanism
+
+```python
+# lmcache/cli/commands/my_cmd.py
+from lmcache.cli.commands.base import BaseCommand
+
+class MyCommand(BaseCommand):
+    def name(self) -> str:
+        return "my-cmd"
+
+    def help(self) -> str:
+        return "Short help text."
+
+    def add_arguments(self, parser) -> None:
+        parser.add_argument("--flag", ...)
+
+    def execute(self, args) -> None:
+        ...  # command logic
+```
+
+```python
+# lmcache/cli/commands/__init__.py  (add import + list entry)
+from lmcache.cli.commands.my_cmd import MyCommand
+
+ALL_COMMANDS: list[BaseCommand] = [
+    ...,
+    MyCommand(),
+]
+```
+
+`BaseCommand` enforces that all four abstract methods (`name`, `help`,
+`add_arguments`, `execute`) are implemented — instantiation fails otherwise.
+The concrete `register()` method (inherited, not typically overridden) wires
+everything up automatically.
+
+### How command discovery works
+
+1. `lmcache <cmd> ...` invokes `main()` in `main.py`.
+2. `main.py` imports `ALL_COMMANDS` from `commands/__init__.py`.
+3. At import time, `__init__.py` imports each command class and instantiates
+   it into the `ALL_COMMANDS` list.  Instantiation validates that all abstract
+   methods are implemented (`TypeError` on failure).
+4. `main.py` iterates `ALL_COMMANDS` and calls `cmd.register(subparsers)`.
+5. `BaseCommand.register()` creates an argparse subparser (using `name()` and
+   `help()`), calls `add_arguments()` to wire up flags, and sets
+   `parser.set_defaults(func=self.execute)`.
+6. After parsing, `main.py` dispatches via `args.func(args)`, which calls the
+   matched command's `execute()`.
+
+### How to add a new subcommand
+
+**Step 1.** Create `lmcache/cli/commands/describe.py`:
+
+```python
+from lmcache.cli.commands.base import BaseCommand
+
+class DescribeCommand(BaseCommand):
+    def name(self) -> str:
+        return "describe"
+
+    def help(self) -> str:
+        return "Describe a running KV cache server."
+
+    def add_arguments(self, parser) -> None:
+        parser.add_argument("--url", required=True)
+
+    def execute(self, args) -> None:
+        ...  # implementation
+```
+
+**Step 2.** Register it in `lmcache/cli/commands/__init__.py`:
+
+```python
+from lmcache.cli.commands.describe import DescribeCommand
+
+ALL_COMMANDS: list[BaseCommand] = [
+    MockCommand(),
+    DescribeCommand(),   # <-- add here
+]
+```
+
+That's it — `lmcache describe --url http://localhost:8000` is now available.
+
+### File layout
+
+```
+lmcache/cli/
+├── __init__.py          # empty
+├── main.py              # main() entry point
+├── metrics/             # Metrics system (Section 2)
+│   ├── __init__.py      # re-exports
+│   ├── metrics.py       # Metrics collector
+│   ├── section.py       # Section data class
+│   ├── handler.py       # StreamHandler, FileHandler
+│   └── formatter.py     # TerminalFormatter, JsonFormatter
+├── commands/
+│   ├── __init__.py      # ALL_COMMANDS registry
+│   ├── base.py          # BaseCommand ABC
+│   └── mock.py          # lmcache mock  (example command)
+└── corpora/             # built-in prompt corpora (future)
+```
+
+### Entry point (pyproject.toml)
+
+```toml
+[project.scripts]
+lmcache = "lmcache.cli.main:main"
+```
+
+---
+
+## 2. Hierarchical Metrics System
+
+### Goal
+
+A lightweight, dependency-free metrics system that:
+
+1. Accepts metrics organized into **sections** (categories).
+2. Uses a **handler + formatter** architecture (like Python `logging`) to
+   separate *where* metrics are written from *how* they are rendered.
+3. Supports stdout, file, and future destinations (e.g. Kafka) without
+   requiring command authors to manage handlers themselves.
+
+### Architecture
+
+The metrics system has three layers:
+
+- **`Metrics`** — the collector. Holds sections and entries. Calls `emit()`
+  to trigger all registered handlers.
+- **`MetricsHandler`** — the destination (where to write). Each handler holds
+  a formatter. Built-in: `StreamHandler` (writes to a stream like stdout),
+  `FileHandler` (writes to a file path).
+- **`MetricsFormatter`** — the rendering (how to format). Built-in:
+  `TerminalFormatter` (ASCII table), `JsonFormatter` (JSON string).
+
+```
+Metrics ──emit()──▶ Handler (destination) ──▶ Formatter (rendering)
+                     StreamHandler(stdout)      TerminalFormatter
+                     FileHandler("out.json")    JsonFormatter
+```
+
+### File layout
+
+```
+lmcache/cli/metrics/
+├── __init__.py       # re-exports
+├── metrics.py        # Metrics collector
+├── section.py        # Section data class
+├── handler.py        # MetricsHandler, StreamHandler, FileHandler
+└── formatter.py      # MetricsFormatter, TerminalFormatter, JsonFormatter
+```
+
+### API
+
+Each metric has a **machine key** (used in JSON output) and a **human-readable
+label** (used in terminal output). Sections work the same way.
+
+```python
+from lmcache.cli.metrics import Metrics, StreamHandler, TerminalFormatter
+
+metrics = Metrics(title="Bench KV Cache Result (30s)")
+
+# Title can be changed after construction
+metrics.title("Bench KV Cache Result (60s)")
+
+# Create named sections (machine key + display label)
+metrics.add_section("ops", "Operations (ops/s)")
+metrics.add_section("hit_rate", "Hit Rate")
+metrics.add_section("correctness", "Correctness")
+
+# Add metrics to sections via dict-like access
+metrics["ops"].add("store", "Store", 41.3)
+metrics["ops"].add("retrieve", "Retrieve", 127.3)
+metrics["hit_rate"].add("l1", "L1", "92.3%")
+metrics["correctness"].add("checksums", "Checksums", "5060/5060 OK")
+
+# Trigger all handlers
+metrics.emit()
+```
+
+**Command authors don't register handlers manually.** `BaseCommand.create_metrics()`
+sets up default handlers automatically:
+
+```python
+# Inside a command's execute() method:
+metrics = self.create_metrics("Bench Result", args, width=48)
+# ^ automatically adds:
+#   - StreamHandler → stdout (formatter chosen by --format, default: terminal)
+#   - FileHandler   → if --output is set (same format as --format)
+```
+
+### Handlers and Formatters
+
+**Handlers** (destination):
+
+| Handler | Default Formatter | Description |
+|---|---|---|
+| `StreamHandler(formatter, stream)` | `TerminalFormatter` | Writes to a text stream (default: stdout) |
+| `FileHandler(path, formatter)` | `JsonFormatter` | Writes to a file |
+
+**Formatters** (rendering):
+
+| Formatter | Description |
+|---|---|
+| `TerminalFormatter(width)` | ASCII table with `=`/`-` dividers |
+| `JsonFormatter(indent)` | JSON string |
+
+Custom handlers and formatters can be added by subclassing `MetricsHandler`
+and `MetricsFormatter`.
+
+### Terminal output format
+
+```
+========= Bench KV Cache Result (30s) =========
+--------------Operations (ops/s)----------------
+Store:                                   41.3
+Retrieve:                                127.3
+-----------------Hit Rate-----------------------
+L1:                                      92.3%
+--------------Correctness-----------------------
+Checksums:                               5060/5060 OK
+================================================
+```
+
+Design choices:
+- **Fixed total width** of 48 characters (configurable via `width` param on
+  `TerminalFormatter`).
+- Title row is centered within `=` borders.
+- Section headers are centered within `-` borders.
+- Key-value lines are left-aligned label, right-aligned value.
+- Values are formatted automatically: floats get 2 decimal places, strings are
+  printed as-is, `None` is printed as `N/A`.
+- Output goes directly to stdout (conventional CLI behavior, not via `logging`).
+
+### JSON output format
+
+JSON uses machine keys, not display labels:
+
+```json
+{
+  "title": "Bench KV Cache Result (30s)",
+  "metrics": {
+    "ops": {
+      "store": 41.3,
+      "retrieve": 127.3
+    },
+    "hit_rate": {
+      "l1": "92.3%"
+    },
+    "correctness": {
+      "checksums": "5060/5060 OK"
+    }
+  }
+}
+```
+
+### Flat metrics (no section)
+
+For top-level metrics that don't belong to a section, use `metrics.add()`
+directly:
+
+```python
+metrics = self.create_metrics("Ping KV Cache", args)
+metrics.add("status", "Status", "OK")
+metrics.add("rtt_ms", "Round trip time (ms)", 0.42)
+metrics.emit()
+```
+
+Produces:
+
+```
+======= Ping KV Cache =======
+Status:                  OK
+Round trip time (ms):    0.42
+==============================
+```
+
+These go into a default unnamed section — no header line is rendered, and in
+JSON the entries appear at the top level of `"metrics"`.
+
+### Implementation notes
+
+- `Metrics` holds an ordered list of `Section` objects. Each `Section` stores
+  a machine key, a display label, and a list of `(key, label, value)` entries.
+- `metrics["name"]` returns the `Section` with that machine key. `KeyError`
+  if `add_section()` was not called first.
+- `metrics.add(key, label, value)` appends to a default unnamed section
+  (created implicitly on first use).
+- `emit()` iterates all registered handlers and calls `handler.emit()`.
+- `to_dict()` returns `{"title": ..., "metrics": ...}` for programmatic access.
+- No external dependencies beyond the Python standard library.
+
+---
+
+## 3. `lmcache mock` — Example Command
+
+A mock command that demonstrates the full framework: argument parsing, metrics
+logging, and both terminal and JSON output. It doesn't connect to any server.
+
+```bash
+$ lmcache mock --name test-run --num-items 5
+
+============= Mock Result ==============
+----------- Input Parameters -----------
+Name:                           test-run
+Num items:                             5
+------------- Mock Metrics -------------
+Items processed:                      42
+Total time (ms):                   12.34
+Throughput (items/s):            3403.73
+-------------- Validation --------------
+Status:                               OK
+========================================
+
+# With --output, both stdout and file are produced (two handlers)
+$ lmcache mock --name test-run --num-items 5 --output result.json
+(same terminal output)
+# result.json → {"title": "Mock Result", "metrics": {"input": {"name": "test-run", ...}, ...}}
+```
+
+This command lives in `lmcache/cli/commands/mock.py` and serves as a reference
+implementation for future commands. Note how it uses `self.create_metrics()`
+instead of manually registering handlers.
+
+---
+
+## 4. Shared CLI Conventions
+
+### `--format` flag
+
+Controls the stdout rendering format. Default: `terminal` (ASCII table). Available:
+`terminal`, `json`. Added automatically by `BaseCommand.register()`.
+
+```bash
+lmcache bench ... --format json       # JSON on stdout (for scripts)
+lmcache bench ... --format terminal   # ASCII table (default)
+```
+
+### `--output` flag
+
+Saves metrics to a file. The file format follows ``--format`` (default:
+``terminal``). Also added automatically by `BaseCommand.register()`.
+Can be combined with `--format`:
+
+```bash
+lmcache bench ... --output result.txt                  # terminal format to both stdout and file
+lmcache bench ... --format json --output result.json   # JSON to both stdout and file
+```
+
+### `--url` flag
+
+The `--url` flag points to the **LMCache HTTP server** (e.g.
+`http://localhost:8000`).  Each subcommand configures its own `--url`
+flag as needed.
+
+### Error handling
+
+Commands print errors to stderr and return exit code 1. The dispatcher catches
+exceptions from `args.func(args)` and prints a clean error message.
diff --git a/docs/design/integration/tensorrt_llm/README.md b/docs/design/integration/tensorrt_llm/README.md
new file mode 100644
index 0000000..96eae31
--- /dev/null
+++ b/docs/design/integration/tensorrt_llm/README.md
@@ -0,0 +1,81 @@
+# TensorRT-LLM integration
+
+## Adapter shape
+
+```
+lmcache/integration/tensorrt_llm/
+├── __init__.py             # Optional-import surface
+├── utils.py                # ENGINE_NAME, lmcache_get_config,
+│                           # create_trtllm_metadata
+├── tensorrt_adapter.py     # In-process — engine in TRT-LLM process
+└── tensorrt_mp_adapter.py  # Multi-process — engine in standalone server
+```
+
+Both adapters subclass TRT-LLM's `KvCacheConnectorScheduler` and
+`KvCacheConnectorWorker`. The TRT-LLM imports are *guarded at module
+level only via the package's `__init__`*; nothing in core LMCache
+imports the adapter modules. This keeps `pip install lmcache` unaffected
+when TRT-LLM is absent.
+
+The TRT-LLM connector preset registry (PR
+[NVIDIA/TensorRT-LLM#12626](https://github.com/NVIDIA/TensorRT-LLM/pull/12626))
+maps:
+
+| Preset | Module | Scheduler | Worker |
+|---|---|---|---|
+| `lmcache` | `lmcache.integration.tensorrt_llm.tensorrt_adapter` | `LMCacheKvConnectorScheduler` | `LMCacheKvConnectorWorker` |
+| `lmcache-mp` | `lmcache.integration.tensorrt_llm.tensorrt_mp_adapter` | `LMCacheMPKvConnectorScheduler` | `LMCacheMPKvConnectorWorker` |
+
+## Lifecycle
+
+| Stage | TRT-LLM hook | LMCache call |
+|---|---|---|
+| Init | `worker.register_kv_caches(kv_cache_tensor)` | Build engine via `_get_or_create_engine`; call `gpu_connector.register_kv_caches(kv_cache_tensor)` |
+| Before scheduling | `scheduler.get_num_new_matched_tokens(req, num_computed)` | `engine.lookup(tokens)` (in-process) or `LOOKUP` + `QUERY_PREFETCH_STATUS` (MP) |
+| Pre-forward | `scheduler.build_connector_meta(scheduler_output)` | `LMCacheConnectorMetadata(loads=..., saves=...)` |
+| Forward | `worker.start_load_kv(stream)` | `engine.retrieve(tokens, block_ids)` |
+| Forward | `worker.wait_for_save(stream)` | `engine.store(tokens, block_ids)` |
+
+## In-process vs MP
+
+The two modes share the lifecycle but differ in where state lives.
+
+| Aspect | In-process (`lmcache`) | Multi-process (`lmcache-mp`) |
+|---|---|---|
+| LMCache engine | Singleton inside the TRT-LLM process | Standalone ZMQ server |
+| Tensor sharing | Direct (same process) | `RawCudaIPCWrapper` (cudaIpc + cupy DLPack) |
+| Lookup | `engine.lookup(tokens)` returns chunk count | `LOOKUP` enqueues prefetch; `QUERY_PREFETCH_STATUS` reads result keyed by `request_id` |
+| Configuration | `LMCACHE_CONFIG_FILE` env var | Same; plus `server_url` in connector config (or `LMCACHE_SERVER_URL` env) |
+| Failure mode | One process crash takes down both | Engine survives TRT-LLM crash; multiple TRT-LLM instances can share cache |
+| Setup cost | None | Run `python -m lmcache.v1.multiprocess.server` |
+
+## Why **not** subclass `VLLMPagedMemGPUConnectorV3`
+
+V3's transfer path is wrong for TRT-LLM:
+
+- **V3 uses the in-process kernel** (`multi_layer_kv_transfer`) with a
+  `slot_mapping` of token positions and per-layer pointers. TRT-LLM's
+  cross-layer pool is a *single* base pointer and we want to transfer
+  by *block ids*, not slot positions.
+- **TRT-LLM needs the MP kernel** (`multi_layer_block_kv_transfer`)
+  which natively handles single-base-pointer cross-layer with
+  `shape_desc.nl` walking layers internally. There is nothing to
+  inherit.
+
+`TRTLLMGPUConnector` is therefore a *standalone* `GPUConnectorInterface`
+implementation. It also exposes a bespoke
+`register_kv_caches(kv_cache_tensor)` method called by the worker once
+at init — separate from `to_gpu`/`from_gpu`. The factory in
+`lmcache/v1/gpu_connector/__init__.py` constructs it from
+`LMCacheMetadata` plus the device, and the adapter wires the pool
+tensor in afterwards.
+
+## Forcing real LMCache hits in tests
+
+TRT-LLM has its own GPU block reuse. To verify LMCache contributes the
+hit (and not TRT-LLM's reuse), the E2E tests size TRT-LLM's pool tiny
+(`KvCacheConfig(max_tokens=512)`) while sending prompts much larger than
+512 tokens. The first request fills LMCache and TRT-LLM. The second is
+guaranteed-evicted from TRT-LLM's pool and *must* come from LMCache —
+which the test asserts via the `lmcache_cached=… new_matched=…` log
+line on request 3.
diff --git a/docs/design/integration/vllm/hybrid-kv-cache-groups.md b/docs/design/integration/vllm/hybrid-kv-cache-groups.md
new file mode 100644
index 0000000..e42a7eb
--- /dev/null
+++ b/docs/design/integration/vllm/hybrid-kv-cache-groups.md
@@ -0,0 +1,187 @@
+# Hybrid KV Cache Groups
+
+## Summary
+
+Minimal hybrid memory allocator (HMA) design for the multiprocess vLLM
+connector. It separates three concepts:
+
+- **Engine KV cache group** — a group defined by the serving engine (vLLM's
+  `KVCacheConfig.kv_cache_groups`). Each is one distinct paged-block address
+  space; block IDs are only meaningful within one group.
+- **`EngineGroupInfo`** — LMCache's engine-neutral, `msgspec`-encoded record of
+  one such group (`group_view.py`). A `list[EngineGroupInfo]` is the
+  registration contract.
+- **`KVLayerGroupInfo`** — the server's runtime transfer-kernel dispatch unit,
+  built from the engine group infos + the real tensors (`kv_layer_groups.py`).
+
+vLLM groups layers by cache behavior; LMCache must transfer by physical layout
+(kv_size, num_heads, head_size, block_size, dtype) *and* keep distinct engine
+block-id spaces separate. So at registration we build engine group infos, and
+store/retrieve address those infos directly.
+
+## Goals / Non-Goals
+
+- Keep the ZMQ API engine-neutral; confine vLLM field reads to
+  `lmcache.integration.vllm`.
+- Registration defines the protocol-visible group order; store/retrieve block
+  IDs are indexed by that order.
+- Reuse one grouping primitive (`group_layers_by_identity`) on both the vLLM and
+  server sides so group order matches.
+- **Not** in scope: sliding-window load-plan trimming; HMA on the non-GPU
+  transfer path (it rejects multi-group); removing `layout_hints` (still used
+  for tensor layout). Per-group block *sizes*, cross-layer KV sharing, and
+  DeepSeek-V4-style slot compression (`compress_ratio > 1`, packing several
+  logical tokens per physical slot) *are* supported (see Store and retrieve).
+
+## Types
+
+- **`EngineGroupInfo`** (`msgspec.Struct`): `engine_group_id` (which engine
+  block group its layers live in; dense from 0) + `layer_indices` +
+  `tokens_per_block` (logical tokens covered by one of the group's paged
+  chunks, from the engine's KV cache spec `block_size`; `0` = unreported).
+  Several infos may share an `engine_group_id` when one engine group is split
+  by physical transfer identity. The list order is the protocol-visible group
+  order; an empty list means a single non-hybrid group.
+- Helpers in `group_view.py` operate on `Sequence[EngineGroupInfo]`:
+  `num_engine_groups`, `num_engine_group_infos`, `expand_engine_block_ids`,
+  `get_engine_group_indices`.
+- **`KVLayerGroupInfo`** (runtime, server-only): layer indices,
+  `PageBufferShapeDesc`, dtype, `tokens_per_block` / `slots_per_block`,
+  `slots_per_chunk`, `engine_group_idx`. Derived from real tensors — never the
+  API contract.
+
+## Data flow
+
+```text
+vLLM KVCacheConfig + registered kv_caches
+  | integration.vllm.kv_cache_groups.create_engine_group_infos_from_vllm
+  v
+list[EngineGroupInfo]  --REGISTER_KV_CACHE (msgspec)-->  server msgspec-decode
+  | KVLayerGroupsManager validates against real tensors
+  v
+KVLayerGroupInfo list   --STORE/RETRIEVE block_ids per info-->  transfer kernels
+```
+
+## Registration
+
+`create_engine_group_infos_from_vllm` (the only place that reads vLLM `KVCacheConfig`):
+
+1. Discover each layer's Engine KV format from its registered tensor
+   (`normalize_and_discover_per_layer_formats`). Detection is per *layout*, not
+   per engine group: a single engine group can contain layers whose registered
+   KV tensors have different shapes — for example a 5-D key+value cache
+   (`[NB, 2, BS, NH, HS]`, `kv_size=2`) alongside a 3-D key-only cache
+   (`[NB, BS, HS]`, `kv_size=1`) in one `UniformTypeKVCacheSpecs` group — so each
+   distinct layout within a group is detected and reported separately.
+   ("5-D"/"3-D" is the tensor rank: the number of dimensions of one layer's
+   registered KV tensor.)
+2. Map each registered layer to its engine group index; layers absent from
+   every group's `layer_names` (cross-layer KV-sharing layers) are tagged
+   `EXCLUDED_ENGINE_GROUP` and dropped (see Cross-layer KV sharing).
+3. `group_layers_by_identity` splits layers by transfer identity
+   `(kv_size, num_heads, head_size, block_size, engine_group_idx, dtype,
+   engine_kv_format)` — `engine_group_idx` keeps identically-shaped layers from
+   different engine groups in separate infos, and `engine_kv_format` keeps
+   different layouts that share one engine group apart (the 5-D key+value vs the
+   3-D key-only cache from step 1).
+4. Emit one `EngineGroupInfo` per identity; send the list in the
+   `REGISTER_KV_CACHE` payload (the message queue encodes it).
+
+## Store and retrieve
+
+vLLM reports block IDs per engine group. The worker adapter re-indexes them to
+engine-group-info order with `expand_engine_block_ids(engine_group_infos, block_ids)` (each
+info reuses its source engine group's block IDs), so `STORE`/`RETRIEVE` receive
+`list[list[int]]` indexed by info order. The server loop is then trivial: for
+info `i`, use `gpu_block_ids[i]`.
+
+### Per-group block sizes and compression
+
+There is no single "engine block size". Each group has two per-group
+quantities, and everything else is derived from them:
+
+- **`tokens_per_block`** — logical tokens covered by one of the group's paged
+  chunks (one block ID). Read from the group's KV cache spec `block_size` in
+  `kv_cache_config` at initialization and carried in `EngineGroupInfo`.
+  Hybrid models mix values freely (`google/gemma-4-E4B-it`: sliding-window
+  groups 32, full-attention groups 16; DeepSeek-V4-Flash: 256/64/8/4).
+- **`slots_per_block`** — physical slots in one paged chunk, detected from the
+  registered tensors at registration time (the batch-size dimension,
+  `shape_desc.bs`). Only available per kernel group.
+
+A group is compressed when `tokens_per_block > slots_per_block` (each physical
+slot packs `tokens_per_block // slots_per_block` logical tokens): ordinary
+attention has one token per slot, while DeepSeek-V4-Flash's MLA / indexer
+caches pack 4 and 128. No `compress_ratio` is stored — wherever a ratio is
+needed it is computed inline from these two ground-truth quantities. The
+LMCache chunk size must be a multiple of every group's `tokens_per_block`
+(validated at connector init and registration).
+
+The scheduler-side connector does all accounting (hit counts, store/retrieve
+ranges) in *tokens* — the only unit shared by every group — and slices each
+group's block IDs by `token_range / tokens_per_block_g`
+(`slice_block_ids_per_group`). The server counts
+`blocks_per_chunk = lmcache_tokens_per_chunk // tokens_per_block` per group.
+
+### Cross-layer KV sharing
+
+Some models (e.g. `google/gemma-4-E4B-it`) reuse one layer's KV cache for
+another (`kv_caches[layer] = kv_caches[target]`). vLLM lists only cache-*owning*
+layers in `kv_cache_groups`; a sharing layer is absent from every group's
+`layer_names`. Such a layer's KV physically lives in its target owner's blocks,
+so storing/retrieving the owner already covers it. Registration therefore tags
+unlisted layers with `EXCLUDED_ENGINE_GROUP` and `group_layers_by_identity`
+skips them — they never form their own info. (Placing them in a group would
+duplicate work and, when their block size differs from the group they default
+into, corrupt the per-group block-id counts.)
+
+**Store is all-or-nothing (fail-closed):** if the block IDs don't fully cover
+every chunk for every group (e.g. a caller bug), or a copy fails, the whole
+store is skipped and nothing is committed — a later retrieve simply misses and
+the engine recomputes. The non-GPU transfer path rejects multi-group transfers
+outright.
+
+## Example
+
+vLLM exposes two engine groups — group 0: layers [0,2,4], group 1: [1,3]. If
+layers 0–3 share a shape but layer 4 differs, registration produces:
+
+```text
+info 0: engine group 0, layers [0, 2]
+info 1: engine group 1, layers [1, 3]
+info 2: engine group 0, layers [4]
+```
+
+Block IDs `{group 0: [10,11], group 1: [20,21]}` are sent as
+`[[10,11], [20,21], [10,11]]` (infos 0 and 2 share group 0's IDs).
+
+## Invariants
+
+- The `list[EngineGroupInfo]` order is the protocol-visible group order; callers
+  send one block-id list per info.
+- vLLM-specific access stays in `lmcache.integration.vllm`; infos carry neutral
+  metadata only.
+- The server reproduces grouping with the same `group_layers_by_identity`; real
+  tensors remain the source of truth for shape/dtype/stride.
+
+## Mamba / linear-attention hybrids
+
+Supported via registration-time tensor re-views (e.g. Qwen3.5 GDN): Mamba
+state pairs become opaque page views, and full-attention layers whose logical
+block size was inflated for page-size unification are re-viewed at
+logical-block granularity. See
+[kv-cache-group-edits](kv_cache_group_edits.md) for the design and its
+limits (notably: edited groups are byte-opaque — no content-aware processing,
+no cross-backend cache sharing).
+
+## Code map
+
+| Area | File |
+|---|---|
+| Engine group info (IPC type) + helpers | `lmcache/v1/multiprocess/group_view.py` |
+| Shared grouping primitive | `lmcache/v1/kv_layer_groups.py` |
+| vLLM → `list[EngineGroupInfo]` | `lmcache/integration/vllm/kv_cache_groups.py` |
+| Group metadata edits (Mamba, sub-paged attention) | `lmcache/integration/vllm/kv_cache_group_edits.py` |
+| Register / store / retrieve | `lmcache/integration/vllm/{lmcache_mp_connector,vllm_multi_process_adapter}.py` |
+| Server GPU context / transfer | `lmcache/v1/multiprocess/{gpu_context,modules/lmcache_driven_transfer}.py` |
+| ZMQ protocol | `lmcache/v1/multiprocess/protocols/engine.py` |
diff --git a/docs/design/integration/vllm/kv_cache_group_edits.md b/docs/design/integration/vllm/kv_cache_group_edits.md
new file mode 100644
index 0000000..b63a3b5
--- /dev/null
+++ b/docs/design/integration/vllm/kv_cache_group_edits.md
@@ -0,0 +1,150 @@
+# KV Cache Group Edits
+
+## Summary
+
+`lmcache/integration/vllm/kv_cache_group_edits.py` is the single place where
+vLLM KV cache groups are re-presented ("edited") before LMCache registration.
+The connector calls `apply_kv_cache_group_edits(kv_cache_config, kv_caches)`
+once in `register_kv_caches`, and the edited dict feeds both engine-group-info
+creation (`kv_cache_groups.py`) and transfer registration.
+
+LMCache derives each group's transfer metadata (block size, page layout,
+dtype) from the registered tensors, and interprets store/retrieve block IDs in
+vLLM's scheduler-side block-id space (`kv_cache_spec.block_size` units). The
+edits exist to restore one invariant the raw tensors can violate:
+
+> **The registered tensor's paging granularity must equal the block-id
+> granularity.**
+
+## Structure
+
+Each case is one `KVCacheGroupEdit` rule in the module's `_EDITS` registry:
+`matches(spec, kv_cache)` decides **structurally** — from the vLLM spec kind
+(`get_kv_cache_spec_kind`, which also unwraps `UniformTypeKVCacheSpecs`) and
+the registered tensor, never from model name or architecture — and
+`apply(spec, kv_cache)` produces a view over the same storage. First matching
+rule wins; unmatched layers pass through. Covering a new group kind means
+adding one rule.
+
+Model name/arch is deliberately not an input: the same architecture yields
+different group structures depending on runtime decisions
+(`mamba_cache_mode`, attention backend's kernel block size, TP), all of which
+the config + tensors already resolve.
+
+## Edits
+
+Both rules apply only to Mamba-hybrid models (the registry is only consulted
+when `kv_cache_config.has_mamba_layers`).
+
+### 1. Mamba state pages
+
+A Mamba / linear-attention layer (e.g. Qwen3.5 GDN) registers `[conv_state,
+ssm_state]` — two tensors with different shapes and dtypes, laid out
+contiguously in one padded page (`conv | ssm | pad`). The raw pair trips
+format discovery (the SSM view starts mid-page). The edit reinterprets each
+page as one bf16 tensor shaped `(num_blocks, 2, block_size, 1, head_size)`
+over the same storage, where `head_size` is derived so the bytes fill the page
+exactly.
+
+### 2. Sub-paged full attention
+
+vLLM unifies page sizes across hybrid groups by inflating the attention
+*logical* block size (`vllm/platforms/interface.py:_align_hybrid_block_size`;
+Qwen3.5-0.8B: 544), while the attention backend re-pages the physical tensor
+at its own *kernel* block size (`vllm/v1/worker/utils.py:
+prepare_kernel_block_sizes`; FlashAttention on hybrids: 32). Logical block `n`
+then occupies the `k = logical/kernel` contiguous kernel pages
+`n*k .. n*k+k-1` (vLLM expands the worker-side block table the same way,
+`BlockTable.map_to_kernel_blocks`); the scheduler-side block IDs LMCache
+receives stay logical.
+
+Registering the raw kernel-paged tensor makes LMCache discover
+`block_size == kernel < logical`, and `_derive_compression_metadata`
+(`lmcache/v1/kv_layer_groups.py`) misclassifies the group as compressed:
+only `1/k` of each chunk's KV is transferred, addressed against the kernel
+page space. The edit re-views the tensor as
+`(num_kernel_pages / k, 2, logical_block_size, 1, head_size)` — a pure
+`view()`, valid because `k` kernel pages tile each logical page's bytes
+exactly (enforced; see Invariants).
+
+## Startup validation
+
+`validate_kv_cache_groups` (called at connector init and again at
+registration) rejects group specs the transfer path cannot serve correctly,
+with one aggregated error: `CrossAttentionSpec`, and Mamba with
+`mamba_cache_mode != "align"` (no reusable snapshots). Declared slot
+compression (`compress_ratio > 1` / `tq_slot_size > 0`, e.g. DeepSeek-V4) is
+*not* rejected — those groups are served by the compression path in
+`lmcache/v1/kv_layer_groups.py` and only skipped by the edits here. Note the
+compression path still derives per-group ratios from the unified vLLM block
+size; switching it to per-group block sizes is pending in a separate PR.
+
+Reference: vLLM PR #42828 (Mooncake store HMA support) uses the same
+validate-and-reject-up-front pattern, and is the reference design for the
+deferred follow-ups (per-group store/load masks; manager-mirroring hit
+computation). Caveat for the latter: LMCache's lookup doubles as prefetch, so
+vLLM's lookup-first-then-trim flow does not map directly. See the module
+docstring for the full check-when list.
+
+## Non-edit: declared compression
+
+Groups whose spec *declares* slot compression — `MLAAttentionSpec.
+compress_ratio > 1` (DeepSeek-V4 slot packing, `storage_block_size <
+block_size`) or `TQFullAttentionSpec.tq_slot_size > 0` — genuinely store fewer
+physical slots than logical tokens. They must reach the compression path in
+`lmcache/v1/kv_layer_groups.py` unedited. (DeepSeek-V3.2's `fp8_ds_mla` cache
+packs *bytes per slot*, not slots per block: its specs keep
+`block_size == scheduler block size` and `compress_ratio == 1`, so it never
+needs an edit either.)
+
+The sub-paged rule's `matches` excludes declared-compression specs by their
+own fields (`compress_ratio` / `tq_slot_size`), and its `apply` additionally
+verifies by byte accounting that `k` kernel pages tile the logical page's
+bytes exactly — any *undeclared* packed layout fails with a loud `ValueError`
+rather than being transferred wrongly.
+
+## The opaque-page contract
+
+An edited view's dims are addressing metadata only (block id → byte range).
+The named dims are **not** semantic: a Mamba view's "K plane" is conv/ssm
+bytes, and a sub-paged attention view's "K plane" interleaves true K and V at
+kernel-page granularity (true K is not contiguous across kernel pages, so no
+logical-block view can have a pure-K plane). The synthetic head shape
+`(1, page_bytes / (2 * block_size * elem))` signals this deliberately.
+
+Byte transport round-trips correctly because store and retrieve share the same
+bijective block-id → bytes mapping. Consequences:
+
+- **Valid**: store/retrieve through the MP transfer path on the same engine
+  configuration.
+- **Not valid** for edited groups: content-aware processing (serde
+  compression, blending, head resharding, layout conversion), and sharing
+  cache entries across engines whose attention backends choose different
+  kernel block sizes (the byte order inside a logical page is
+  backend-dependent).
+
+## Invariants
+
+- Edits are pure tensor views over the registered storage — never copies.
+- A sub-paged view is only produced when `kernel_page_bytes * k ==
+  spec.page_size_bytes`; any mismatch raises `ValueError` (fail loudly rather
+  than silently transfer a compressed layout).
+- After edits, every registered tensor's block dim equals its group's
+  `kv_cache_spec.block_size`, so the server derives `compress_ratio == 1` for
+  these groups.
+
+## Code map
+
+| Area | File |
+|---|---|
+| Edits (this doc) | `lmcache/integration/vllm/kv_cache_group_edits.py` |
+| Caller | `lmcache/integration/vllm/lmcache_mp_connector.py` (`register_kv_caches`) |
+| Compression-ratio derivation (downstream consumer) | `lmcache/v1/kv_layer_groups.py` |
+| vLLM block-size inflation | `vllm/platforms/interface.py` (`_align_hybrid_block_size`) |
+| vLLM kernel-page split + block-table expansion | `vllm/v1/worker/utils.py`, `vllm/v1/worker/block_table.py` |
+| End-to-end test | `.buildkite/k3_tests/multiprocess/scripts/run-single-test.sh` (`hma_lm_eval_qwen3_5`) |
+
+Testing is end-to-end only (the `hma_lm_eval_qwen3_5` store-vs-retrieve gsm8k
+check): the edit internals are expected to change as more group kinds are
+covered, so tests pin the observable contract — faithful retrieve — rather
+than view shapes.
diff --git a/docs/design/observability/request-event-span.md b/docs/design/observability/request-event-span.md
new file mode 100644
index 0000000..5c9e759
--- /dev/null
+++ b/docs/design/observability/request-event-span.md
@@ -0,0 +1,375 @@
+# Per-Request Root Span
+
+This document describes the root span design for `MPServerTracingSubscriber`:
+how a single `"request"` OTel span wraps all child operations for one request,
+and how the span close is deferred correctly when GPU stores are still in flight.
+
+## Problem
+
+Before this change, `MPServerTracingSubscriber` emitted flat, orphaned child
+spans (`mp.store`, `mp.retrieve`, `mp.lookup_prefetch`) with no parent context.
+Traces in Tempo/Jaeger showed disconnected spans with no request-level view.
+
+## Design
+
+Each request gets one root `"request"` span that:
+
+- Opens at `MP_REQUEST_START` — the first CPU-synchronous touch of a `request_id`
+- Nests all child spans beneath it via OTel context propagation
+- Closes at `MP_REQUEST_END`, deferred if async GPU stores are still in flight
+
+### New Events
+
+Four new `EventType` values, all CPU-synchronous:
+
+| Event | Published from | Purpose |
+|-------|---------------|---------|
+| `MP_REQUEST_START` | `lookup_prefetch_start()`, top of method | Open root span at true request arrival |
+| `MP_STORE_SUBMITTED` | `store()`, before `publish_on_stream(MP_STORE_START)` | Register a pending GPU store before it's enqueued |
+| `MP_RETRIEVE_SUBMITTED` | `retrieve()`, before `publish_on_stream(MP_RETRIEVE_START)` | Register a pending GPU retrieve before it's enqueued |
+| `MP_REQUEST_END` | `end_session()`, after `session_manager.remove()` | Signal that the session lifecycle is complete |
+
+### Deferral Protocol
+
+`end_session()` is CPU-synchronous; GPU store/retrieve callbacks (`MP_STORE_END`,
+`MP_RETRIEVE_END`) fire later via CUDA host callbacks. Without coordination,
+`MP_REQUEST_END` can arrive and close the root span before GPU work finishes —
+producing orphaned child spans.
+
+The fix: `MP_STORE_SUBMITTED` and `MP_RETRIEVE_SUBMITTED` are published *before*
+the respective GPU work is enqueued, incrementing `_pending_store_count` and
+`_pending_retrieve_count`. When `MP_REQUEST_END` arrives:
+
+- If both counters are zero → close root immediately
+- Otherwise → save the `REQUEST_END` timestamp; the last `MP_STORE_END` or
+  `MP_RETRIEVE_END` to decrement its counter to zero (when the other counter is
+  also zero) closes the root using that saved timestamp
+
+Root end-time is always the `REQUEST_END` timestamp (the logical request end),
+not the GPU callback timestamp.
+
+**Why `MP_RETRIEVE_SUBMITTED` is needed**: vLLM's IPC completion event is
+recorded on the CUDA stream between `MP_RETRIEVE_START` and `MP_RETRIEVE_END`.
+When vLLM unblocks on that event, it can call `end_session()` before the GPU
+callback for `MP_RETRIEVE_END` fires. EventBus queue becomes:
+`→ MP_RETRIEVE_START → MP_REQUEST_END → MP_RETRIEVE_END`
+Without `MP_RETRIEVE_SUBMITTED`, `_on_session_end` sees no in-flight work and
+closes the root span before the retrieve child span ends.
+
+## Root Span Attributes
+
+In addition to `session_id`, the root `"request"` span carries three hit rate
+attributes that are set when `MP_LOOKUP_PREFETCH_END` is processed:
+
+| Attribute | OTel type | Value |
+|-----------|-----------|-------|
+| `hit_tokens` | `int` | tokens found in L1+L2 (numerator) |
+| `requested_tokens` | `int` | chunk-aligned tokens submitted for lookup (denominator) |
+| `hit_rate` | `float` | `hit_tokens / requested_tokens`; `0.0` when denominator is zero |
+
+`hit_rate` is stored as a precomputed float because trace UIs (Tempo, Jaeger)
+cannot derive it from two integer attributes at query time.
+
+**Invariant:** these attributes are set at `MP_LOOKUP_PREFETCH_END` time, while
+the root span is still open.  `LP_END` always precedes `MP_REQUEST_END` in the
+event stream, so the root span is guaranteed to be live in the registry when the
+attributes are written.
+
+**Store-only requests** (no `lookup_prefetch_start()` call) never emit
+`MP_LOOKUP_PREFETCH_END`, so the root span will not carry these attributes.
+
+### CB path — `cb.request` span
+
+The same three attributes appear on the `"cb.request"` root span and are set
+when `CB_LOOKUP_END` is processed by `BlendTracingSubscriber`.
+
+`CB_LOOKUP_END` carries `hit_tokens` and `requested_tokens` in its metadata,
+computed at the emit site in `lmcache/v1/multiprocess/modules/blend.py`:
+
+| Field | Value |
+|-------|-------|
+| `hit_tokens` | `storage_hits * chunk_size` |
+| `requested_tokens` | `(num_tokens // chunk_size) * chunk_size` (chunk-aligned) |
+
+All three `CB_LOOKUP_END` emit sites (no-fingerprint-match, no-GPU-context,
+happy path) populate these fields, so `hit_rate` is always present on the
+`cb.request` span.
+
+A fourth attribute is also set on `"cb.request"` at `CB_LOOKUP_END` time:
+
+| Attribute | OTel type | Value |
+|-----------|-----------|-------|
+| `prefix_hits` | `int` | chunks found via the prefix probe (not fingerprint matching) |
+
+#### Prefix probe
+
+`cb_lookup_pre_computed` has two lookup paths:
+
+1. **Fingerprint path** — `BlendTokenRangeMatcher.match_sub_sequence` finds
+   sub-sequence matches using polynomial rolling hashes.  Covers arbitrary
+   (non-prefix) positions in the token sequence.
+2. **Prefix probe** — a fallback that runs after the fingerprint path and fills
+   in chunks at contiguous prefix positions not already covered by fingerprint
+   results.  It calls `token_hasher.compute_chunk_hashes(token_ids)` to derive
+   the same storage keys used by `cb_store_final` and `cb_store_pre_computed`,
+   then creates `CBMatchResult(old_st==cur_st)` candidates for uncovered slots.
+   These candidates flow through the same prefetch/poll/evict machinery as
+   fingerprint results.
+
+The prefix probe closes the gap between the MP and CB storage paths: chunks
+written by `cb_store_final` (which only registers fingerprints when
+`worker_id in [0, None]`) and chunks written via the MP `store()` path (which
+uses block hashes incompatible with fingerprint matching) are both visible to
+`cb_lookup_pre_computed` through the prefix probe.
+
+#### Lazy registration
+
+When `cb_lookup_pre_computed` returns results that came *entirely* from the
+prefix probe (i.e. `fingerprint_results` is empty) and the calling worker is
+rank 0 or the driver (`worker_id in [0, None]`), the found prefix chunks are
+registered into `BlendTokenRangeMatcher` so that future lookups can find them
+via the faster fingerprint path.  Registration is guarded by
+`BlendTokenRangeMatcher.has_chunk(token_hash)` to prevent overwriting existing
+compact-ID assignments when the range matcher already has entries for the same
+token sequence.
+
+`prefix_hits` counts the chunks found exclusively through the prefix probe
+(after deduplication against fingerprint results).  When `fingerprint_results`
+is non-empty and prefix candidates fill in additional positions,
+`prefix_hits` reflects only the prefix-probe portion of the total
+`storage_hits`.
+
+## Request Scenarios
+
+### Scenario 1 — Full Cache Hit
+
+Path: `lookup_prefetch → retrieve → store`
+
+```
+CPU  ─[REQUEST_START]─[LP_START]─[LP_END]──[RETR_SUBMITTED]──[STORE_SUBMITTED]─[REQUEST_END]─►
+GPU  ──────────────────────────────[RETR_START]─[vLLM_IPC]─[RETR_END]──[STORE_START]─[STORE_END]─►
+
+root "request"  [═══════════════════════════════════════════════════════════════════════════════]
+  mp.lookup_prefetch    [══════════]
+  mp.retrieve                          [══════════════════]
+  mp.store                                                        [══════════════════════]
+```
+
+Root closes at `REQUEST_END` (deferred until both retrieve and store complete).
+
+---
+
+### Scenario 2 — Cache Miss (no retrieve)
+
+Path: `lookup_prefetch → store`, no retrieve
+
+```
+CPU  ─[REQUEST_START]─[LP_START]─[LP_END]──────────[STORE_SUBMITTED]─[REQUEST_END]─►
+GPU  ───────────────────────────────────────────────────────[STORE_START]─[STORE_END]─►
+
+root "request"  [═══════════════════════════════════════════════════════════════════]
+  mp.lookup_prefetch    [══════════]
+  mp.store                                                    [══════════════════════]
+```
+
+No retrieve occurred, so `mp.retrieve` is absent.
+
+---
+
+### Scenario 3 — Lookup Only
+
+Path: `lookup_prefetch` only, no store
+
+```
+CPU  ─[REQUEST_START]─[LP_START]─[LP_END]─[REQUEST_END]─►
+
+root "request"  [════════════════════════════════════════]
+  mp.lookup_prefetch    [══════════]
+```
+
+Root closes immediately at `REQUEST_END`.
+
+---
+
+### Scenario 4 — Store Only (no lookup)
+
+Path: `store` with no prior `lookup_prefetch_start()` call
+
+```
+CPU  ─(no REQUEST_START)──────[STORE_SUBMITTED]─[REQUEST_END]─►
+GPU  ──────────────────────────────────[STORE_START]─[STORE_END]─►
+
+root "request" (lazy, created at MP_STORE_START)
+                                       [═════════════════════════]
+  mp.store                             [══════════════]
+```
+
+`MP_REQUEST_START` is only emitted from `lookup_prefetch_start()`. If that path
+was not taken, `_get_or_create_request_span()` is called lazily on the first child
+`_on_start()`. Root start time equals `STORE_START` timestamp.
+
+---
+
+### Scenario 5 — REQUEST_END Races GPU Store
+
+`end_session()` called before the GPU store callback fires.
+
+```
+CPU  ─[REQUEST_START]─[LP_START]─[LP_END]─[STORE_SUBMITTED]─[REQUEST_END]────────────────────►
+GPU  ──────────────────────────────────────────────[STORE_START]──────────────[STORE_END]─────►
+                                                                       ▲
+                                              REQUEST_END arrives here─┘ (before STORE_END)
+
+root "request"  [═══════════════════════════════════════════════════════════════════════════]
+  mp.lookup_prefetch    [══════════]
+  mp.store                                                    [═══════════════════]
+                                                                                  ▲
+                   STORE_SUBMITTED → count=1                                      │
+                   REQUEST_END → count>0 → defer (save ts)                        │
+                   STORE_END → count=0 → _close_request_span(deferred_ts) ────────────────┘
+```
+
+---
+
+### Scenario 6 — Multiple Stores, Deferred Close
+
+Two concurrent stores; root stays open until both complete.
+
+```
+CPU  ─[REQUEST_START]─[LP_START]─[LP_END]─[SUBMITTED×2]─[REQUEST_END]──────────────────────────────────►
+GPU  ────────────────────────────────────────────────────[S1_START]─[S1_END]─[S2_START]─[S2_END]────────►
+
+root "request"  [═══════════════════════════════════════════════════════════════════════════════════════]
+  mp.lookup_prefetch    [══════════]
+  mp.store (1)                                                       [══════════]
+  mp.store (2)                                                                    [══════════]
+                                                                                            ▲
+                   count=2 at REQUEST_END → defer                                           │
+                   S1_END → count=1 → still open                                            │
+                   S2_END → count=0 → _close_request_span(deferred_ts) ─────────────────────────────┘
+```
+
+## Summary
+
+| Scenario | Root opens | Root closes |
+|----------|-----------|-------------|
+| Full hit | `MP_REQUEST_START` | last `MP_STORE_END` / `MP_RETRIEVE_END` (stamped at `REQUEST_END` time) |
+| Cache miss | `MP_REQUEST_START` | last `MP_STORE_END` (stamped at `REQUEST_END` time) |
+| Lookup only | `MP_REQUEST_START` | `REQUEST_END` (immediate) |
+| Store only | `MP_STORE_START` (lazy) | `REQUEST_END` (immediate) |
+| REQUEST_END races store | `MP_REQUEST_START` | last `MP_STORE_END` (stamped at `REQUEST_END` time) |
+| REQUEST_END races retrieve | `MP_REQUEST_START` | last `MP_RETRIEVE_END` (stamped at `REQUEST_END` time) |
+| Multiple stores | `MP_REQUEST_START` | last `MP_STORE_END` (stamped at `REQUEST_END` time) |
+
+## Implementation
+
+| File | Change |
+|------|--------|
+| `lmcache/v1/mp_observability/event.py` | Add `MP_REQUEST_START`, `MP_STORE_SUBMITTED`, `MP_RETRIEVE_SUBMITTED`, `MP_REQUEST_END` |
+| `lmcache/v1/multiprocess/server.py` | Emit the 4 events at `lookup_prefetch_start()`, `store()`, `retrieve()`, `end_session()` |
+| `lmcache/v1/mp_observability/subscribers/tracing/mp_server.py` | Root span logic: `_pending_store_count`, `_pending_retrieve_count`, `_deferred_session_end_ts`; handlers `_on_request_start`, `_on_store_submitted`, `_on_retrieve_submitted`, `_on_session_end`; helpers `_get_or_create_request_span`, `_close_request_span` |
+| `lmcache/v1/mp_observability/subscribers/tracing/span_registry.py` | `SpanRegistry`: shared dict of open spans keyed by `(session_id, span_name)` for cross-subscriber parent lookup |
+| `tests/v1/mp_observability/subscribers/tracing/test_mp_server.py` | Tests for all scenarios including retrieve deferral |
+| `lmcache/v1/multiprocess/modules/blend.py` | Prefix probe in `cb_lookup_pre_computed`; lazy registration; `has_chunk` on `BlendTokenRangeMatcher`; `prefix_hits` in `CB_LOOKUP_END` metadata |
+| `lmcache/v1/mp_observability/subscribers/tracing/cb_server.py` | Stamp `prefix_hits` on `"cb.request"` root span from `CB_LOOKUP_END` |
+| `tests/v1/multiprocess/test_blend_server_v2.py` | `has_chunk` unit tests |
+| `tests/v1/mp_observability/subscribers/tracing/test_cb_server.py` | `prefix_hits` attribute tests |
+
+---
+
+## Extending the Span Hierarchy
+
+### How the registry works
+
+`MPServerTracingSubscriber` writes every open span into a shared
+`SpanRegistry` while it is live:
+
+```
+registry[(session_id, "request")]       → (root_span, root_ctx)       # open: REQUEST_START → REQUEST_END
+registry[(session_id, "retrieve")]      → (retrieve_span, ctx)         # open: RETRIEVE_START → RETRIEVE_END
+registry[(session_id, "store")]         → (store_span, ctx)            # open: STORE_START → STORE_END
+registry[(session_id, "lookup_prefetch")] → (lp_span, ctx)            # open: LP_START → LP_END
+```
+
+Any subscriber that receives the same `SpanRegistry` instance can call
+`registry.get_context(session_id, "request")` (or any other name) to obtain
+the OTel context needed to nest a new span.
+
+---
+
+### Example 1 — new span at the same level
+
+To add an `l1.read` span nested directly under the root `"request"` span,
+create a new subscriber file and register it with the shared registry.
+No existing files need to change.
+
+**`subscribers/tracing/l1.py`**:
+
+```python
+# SPDX-License-Identifier: Apache-2.0
+from opentelemetry import trace
+
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import SpanRegistry
+
+_tracer = trace.get_tracer("lmcache_mp.l1")
+
+class L1TracingSubscriber(EventSubscriber):
+    def __init__(self, registry: SpanRegistry) -> None:
+        self._registry = registry
+        self._pending: dict[str, object] = {}
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L1_READ_RESERVED: self._on_start,
+            EventType.L1_READ_FINISHED: self._on_end,
+        }
+
+    def _on_start(self, event: Event) -> None:
+        parent_ctx = self._registry.get_context(event.session_id, "request")
+        span = _tracer.start_span(
+            "l1.read", context=parent_ctx, start_time=int(event.timestamp * 1e9)
+        )
+        self._pending[event.session_id] = span
+
+    def _on_end(self, event: Event) -> None:
+        span = self._pending.pop(event.session_id, None)
+        if span:
+            span.end(end_time=int(event.timestamp * 1e9))
+```
+
+**`config.py`** (the only change needed):
+
+```python
+registry = SpanRegistry()
+bus.register_subscriber(MPServerTracingSubscriber(registry))
+bus.register_subscriber(L1TracingSubscriber(registry))   # ← add this line
+```
+
+This produces: `request → l1.read` (alongside `mp.retrieve`, `mp.store`, etc.)
+
+---
+
+### Example 2 — sub-span nested under an existing child span
+
+To nest a span *inside* `mp.retrieve` (e.g. an L2 disk load that happens
+during a retrieve), look up `"retrieve"` as the parent instead of `"request"`.
+The `"retrieve"` entry is live in the registry from `MP_RETRIEVE_START` to
+`MP_RETRIEVE_END`.
+
+```python
+    def _on_detail_start(self, event: Event) -> None:
+        sid = event.session_id
+        # Prefer the immediate parent; fall back to root if retrieve has ended.
+        parent_ctx = (
+            self._registry.get_context(sid, "retrieve")
+            or self._registry.get_context(sid, "request")
+        )
+        span = _tracer.start_span(
+            "l2.disk_load", context=parent_ctx, start_time=int(event.timestamp * 1e9)
+        )
+        self._pending[sid] = span
+```
+
+This produces a three-level trace: `request → mp.retrieve → l2.disk_load`.
diff --git a/docs/design/sdk/batch.md b/docs/design/sdk/batch.md
new file mode 100644
index 0000000..18e1e15
--- /dev/null
+++ b/docs/design/sdk/batch.md
@@ -0,0 +1,53 @@
+# Batched Stream SDK
+
+> Wrapper over the [Stream SDK](stream.md) for batching many requests
+
+## Goal
+
+`LMCacheStream` drives one request. `LMCacheBatchedStream` groups many of them
+and runs each phase — prefill, modify, decode — across the whole batch at once
+(one thread per stream), then aggregates the per-stream `StreamPerfMetrics`
+into a single `Metrics` report.
+
+```py
+import lmcache.sdk.stream as lmc_stream
+import lmcache.sdk.batch as lmc_batch
+
+batch = lmc_batch.LMCacheBatchedStream()
+for toks in prompts:
+    batch.add(lmc_stream.create_request(ctx, post_completion, toks))
+
+batch.prefill({"temperature": 1.0}) # max_tokens forced to 1
+batch.modify(drop_tokens) # edit every stream's KV concurrently
+results = batch.decode({"max_tokens": 256})  # returns Metrics
+results.emit() # print the Metric in a table on terminal
+data = results.to_dict() # to get the Metric as a dictionary
+```
+
+See example in [token-dropping example](../../../examples/token_dropping/).
+
+## Pipeline
+
+The three high-level methods mirror the stream phases and each return a
+`Metrics`:
+
+- **`prefill(sampling_params, fmt="terminal", width=80, stream_ids=None)`**:
+  forces `max_tokens=1`, runs every stream, reports prefill metrics.
+- **`modify(fn, fmt="terminal", width=80, stream_ids=None)`**: applies
+  `fn` to every stream's KV (`modify_kv`). Only reports duration (s).
+- **`decode(sampling_params, fmt="terminal", width=80, stream_ids=None)`**:
+  runs every stream and reports decode metrics.
+
+Lower-level pieces:
+
+- **`add(stream)`** / **`get_stream(stream_id)`**: register / fetch a stream
+  (keyed by `stream.stream_id()`).
+- **`run_streams(sampling_params, stream_ids=None)`** returns duration (s).
+  Batches `stream.generate(sampling_params)` across thread pool and stores each
+  result in `perf_metrics`. Used by `prefill`/`decode`.
+- **`modify_stream(fn, stream_ids=None)`** returns duration (s). Batches
+  `stream.modify_kv(fn)` across thread pool.
+- **`get_perf_metrics(duration, fmt, width, mode, stream_ids=None)`** returns
+  the aggregated Metrics. `mode` can be `"prefill"` or `"decode"`.
+
+`stream_ids=None` means "all streams in the batch".
diff --git a/docs/design/sdk/kvcache.md b/docs/design/sdk/kvcache.md
new file mode 100644
index 0000000..884d2bb
--- /dev/null
+++ b/docs/design/sdk/kvcache.md
@@ -0,0 +1,116 @@
+# KV Cache SDK
+
+> Status: out-of-process, CPU-only client for the LMCache multiprocess (MP) server.
+
+## Goal
+
+A small Python surface for moving KV cache tensors in and out of a running LMCache MP
+server, addressed by **token ids** — so an ML engineer can retrieve a prefix's KV, edit it,
+and store it back (e.g. token-dropping inside a KV connector).
+
+```py
+import lmcache.sdk.kvcache as lmc_sdk
+
+ctx = lmc_sdk.connect(
+    url="tcp://localhost:5555",       # ZMQ url
+    http_url="http://localhost:9000", # HTTP url for retrieving KV cache shape
+    model_name="Qwen/Qwen3-8B",
+)
+kv = lmc_sdk.retrieve(ctx, tokens=[1, 2, 3, ...])  # [2, L, hit_tokens, D] or None
+# ... edit kv ...
+ok = lmc_sdk.store(ctx, kv=kv, tokens=[4, 5, 6, ...])
+lmc_sdk.close(ctx)
+```
+
+See the [token-dropping example](../../../examples/kvcache_sdk/e2e_kv_edit.py).
+
+The model layout must already be registered in the server by a vLLM instance that called
+`REGISTER_KV_CACHE`; the SDK reads that layout from `/status` and `/config` to configure itself.
+
+## Architecture
+
+The SDK is a **separate, CPU-only process** from the LMCache server.
+
+```
+SDK process                                  LMCache MP server
+-----------                                  -----------------
+LMCacheKVCacheContext
+  ├ ContiguousTransferWrapper
+  │   └ EngineDrivenContext{Shm,Pickle} ──MQ──▶ EngineDrivenTransferModule
+  │                                             └ StorageManager (L1 pool, locks, prefetch)
+  └ MessageQueueClient ──────────────────ZMQ──▶ LookupModule (LOOKUP / QUERY_PREFETCH_STATUS)
+  SharedMemory(name) ◀────────────────────────  L1 POSIX segment (SHM transport only)
+```
+
+- **Control plane (ZMQ):** lookup/prefetch, slot reservation, lock release, session end.
+- **Data plane:** **SHM** when the server exposes an L1 pool, otherwise **pickle** over the
+  MQ — both driven through one `EngineDrivenContext`, so the SDK never branches on transport.
+- **`ContiguousTransferWrapper`** ([wrapper/contiguous.py](../../../lmcache/sdk/wrapper/contiguous.py))
+  bridges a contiguous `[2, L, T, D]` tensor to the per-chunk `prepare`/`commit` protocol and
+  masks the SHM-vs-pickle difference.
+
+## Registration handshake
+
+`connect()` builds the context, then `register_kv_caches()` runs once:
+
+1. HTTP `/config` → `chunk_size`.
+2. HTTP `/status` → the `cache_context_meta` entry for `model_name`: `world_size` and the GPU
+   `kv_cache_layout` (`num_layers`, `dtype`, `tokens_per_block`, `engine_kv_format`,
+   `engine_kv_concrete_shape`).
+3. Decode geometry from the layout: `num_kv_heads` / `block_size` via the format-aware
+   `get_num_heads` / `get_block_size` (on a `meta` probe tensor — no allocation), `head_dim`
+   from the last dim; assert `block_size == tokens_per_block`.
+4. Allocate a **dummy 1-block** HND buffer `{layer.i: zeros([1, 2, NH, BS, HS], cpu)}` — used
+   only to register the layout; the data plane never touches it.
+5. `create_transfer_context(buffer)` → `EngineDrivenTransferContext.register(...)`, which sends
+   `REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT` (server reserves the SHM pool / picks SHM vs pickle).
+6. Wrap `transfer_ctx.engine_driven_context` in a `ContiguousTransferWrapper`.
+
+`instance_id` is the SDK process PID.
+
+## Public API
+
+Module functions in `lmcache.sdk.kvcache`; `LMCacheKVCacheContext` / `KVCacheSDKError` are
+exported from `lmcache.sdk`.
+
+- **`connect(url, http_url, model_name, timeout=60.0)`** — open the MQ client, fetch config,
+  run the handshake.
+- **`retrieve(ctx, tokens, cache_salt="")`** → contiguous CPU `[2, num_layers, hit_tokens,
+  hidden_dim]` for the cached prefix, or `None` (empty/sub-chunk input, or nothing cached).
+- **`store(ctx, kv, tokens, cache_salt="")`** → `bool`. `kv` is `[2, L, T, D]`; `len(tokens)`
+  must equal `T`; both are truncated to whole chunks before storing.
+- **`close(ctx)`** — shut down the MQ client and ZMQ context.
+
+## Cache addressing
+
+Both build an `IPCCacheServerKey(model_name, world_size=1, worker_id=0, token_ids, start=0,
+end=<chunk-aligned>, request_id, cache_salt)`. The server resolves it to per-chunk `ObjectKey`s;
+**cache identity** = token-chunk hashes + `model_name` + `kv_rank(worker_id)` + `cache_salt`.
+`request_id` (`store-`/`retrieve-<uuid>`) only keys the per-request session, not cache identity.
+
+- `worker_id=0` is valid because the SDK is `world_size == 1` (one shard per chunk).
+- LOOKUP uses the `worker_id=None` (expand-to-all-workers) variant.
+
+## Flows
+
+**store** — validate `len(tokens) == kv.shape[2]`, truncate to whole chunks, then
+`transfer_ctx.store(key, instance_id, kv_cpu)`: `prepare_store` returns writable SHM slots
+(filled in place) or `None` for pickle (gather all chunks); `commit_store`. Writes use mode
+`"new"`, so already-cached chunks are deduplicated.
+
+**retrieve** — Phase 0: `LOOKUP` + poll `QUERY_PREFETCH_STATUS` until non-`None`; if 0 → `None`.
+Phase 1: `transfer_ctx.retrieve(key, instance_id)`: `prepare_retrieve` → `torch.cat` the chunk
+slots into one contiguous tensor → `commit_retrieve`. `end_session` always runs in `finally`.
+
+## Copy summary
+
+| Flow | SHM | Pickle |
+| --- | --- | --- |
+| store | 1 (tensor → SHM slot) | ~2 (tensor → chunks, then serialize) |
+| retrieve | 1 (slot → contiguous) | ~2 (deserialize, then → contiguous) |
+
+## Constraints & known gaps
+
+- **`world_size == 1` only**, and a **single non-hybrid kernel group** only.
+- **Model must be pre-registered** by a vLLM instance (`REGISTER_KV_CACHE`); the SDK reads the
+  GPU layout from `/status` and cannot derive it from `model_name` alone.
diff --git a/docs/design/sdk/stream.md b/docs/design/sdk/stream.md
new file mode 100644
index 0000000..7401cff
--- /dev/null
+++ b/docs/design/sdk/stream.md
@@ -0,0 +1,75 @@
+# Stream SDK
+
+> Stateful, single-request orchestration over the [KV Cache SDK](kvcache.md).
+
+## Goal
+
+`lmcache.sdk.kvcache` is stateless — it moves KV by token ids and forgets. A
+token dropping request spans several passes (prefill, modify the cached KV, 
+decode), which are encoded as different requests. `LMCacheStream` binds all
+request belonging to a request as a stream instead of leaving the management
+to the user.
+
+```py
+import lmcache.sdk.kvcache as lmc_sdk
+import lmcache.sdk.stream as lmc_stream
+
+ctx = lmc_sdk.connect(url=..., http_url=..., model_name="Qwen/Qwen3-8B")
+stream = lmc_stream.create_request(
+    ctx, post_completion, prompt_token_ids=source_tokens
+)
+
+stream.generate({"max_tokens": 1})    # prefill -> offload the prompt KV
+stream.modify_kv(drop_tokens)         # drop_tokens: retrieve -> edit -> store
+stream.generate({"max_tokens": 256})  # replay the uncached tail + decode
+```
+
+`post_completion(prompt_token_ids, sampling_params, cache_salt)` calls the
+engine (e.g. vLLM `/v1/completions`, streaming) and yields one
+`TokenEvent(token_id, text)` per token. See the 
+[token-dropping example](../../../examples/token_dropping/).
+
+Stream is not used on its own. `LMCacheBatchedStream` wraps it for submitting
+batched requests. See [batch.md](batch.md).
+
+## State model
+
+The full logical sequence is `tokens` + `_suffix_tokens`. The token-bearing
+fields mean different things:
+
+- **`tokens`** — sequence backing the stored KV; sent as the next prompt.
+  Replaced when the KV is modified via `update_kv`.
+- **`_suffix_tokens`** — tokens *not* in the stored KV: the non-chunk-aligned
+  tail left after `modify_kv`. Managed by the next `generate`.
+- **`_decoded` / `_text_parts`** — cumulative generated count / text across all
+  `generate`s (`decoded_tokens()`, `output_text()`); unaffected by compaction.
+- **`done`** — True once a `generate` yields `< max_tokens` (EOS). Reset when
+  `update_kv` is called.
+
+## Suffix contract
+
+`retrieve_kv` returns only a **chunk-aligned** prefix, so after `modify_kv`
+edits it the remainder (sub-chunk tail + not-yet-offloaded tokens) has no
+stored KV. The stream carries it across the edit:
+
+- **`modify_kv`** records the uncached tail `tokens[cached_len:]` after KV
+  modification (e.g. compaction).
+- **`generate`** prepends `_suffix_tokens` (plus any caller `suffix_tokens`)
+  to `tokens` for request submission, then clears it.
+
+## Public API
+
+- **`LMCacheStream(ctx, post_completion, prompt_token_ids, cache_salt="")`**
+  or the `create_request()`.
+- **`generate(sampling_params, suffix_tokens=())`** returns `StreamPerfMetrics`
+  the performance metrics of one request
+- **`modify_kv(fn)`**: calls `retrieve_kv`, passing the KV and tokens so far
+  to the function `fn(kv[2,L,T,D], tokens[:cached_len])` which returns the new
+  pair of `(new_kv, new_tokens)`, then replaces the original KV by `update_kv`.
+- **`retrieve_kv(timeout=30, poll_interval=0.2)`** and
+  **`update_kv(kv, tokens)`**: wraps `lmc_sdk.retrieve()` and `lmc_sdk.store()`
+- Accessors: `stream_id()`, `suffix_tokens()`, `decoded_tokens()`,
+  `output_text()`, `output_tokens()`, `is_done()`.
+- **`StreamPerfMetrics`** (per call metric, times in **seconds**).
+- **`TokenEvent(token_id, text)`**, **`PostCompletion`** (Protocol),
+  **`LMCacheStreamError`**.
diff --git a/docs/design/tools/controller_benchmark/README.md b/docs/design/tools/controller_benchmark/README.md
new file mode 120000
index 0000000..02254d8
--- /dev/null
+++ b/docs/design/tools/controller_benchmark/README.md
@@ -0,0 +1 @@
+../../../../lmcache/tools/controller_benchmark/README.md
\ No newline at end of file
diff --git a/docs/design/tools/transfer_channel_benchmark/README.md b/docs/design/tools/transfer_channel_benchmark/README.md
new file mode 120000
index 0000000..3bbf870
--- /dev/null
+++ b/docs/design/tools/transfer_channel_benchmark/README.md
@@ -0,0 +1 @@
+../../../../lmcache/tools/transfer_channel_benchmark/README.md
\ No newline at end of file
diff --git a/docs/design/usage_telemetry/README.md b/docs/design/usage_telemetry/README.md
new file mode 120000
index 0000000..0d3a904
--- /dev/null
+++ b/docs/design/usage_telemetry/README.md
@@ -0,0 +1 @@
+../../../lmcache/usage_telemetry/README.md
\ No newline at end of file
diff --git a/docs/design/v1/distributed/bitmap_ops/README.md b/docs/design/v1/distributed/bitmap_ops/README.md
new file mode 100644
index 0000000..3685e0b
--- /dev/null
+++ b/docs/design/v1/distributed/bitmap_ops/README.md
@@ -0,0 +1,57 @@
+# `bitmap_ops`
+
+Bitmap operators for computing a **cross-object-group prefix-cache hit**. A
+hybrid model splits one request across several object groups (full attention,
+sliding window, mamba) with different rules: full attention can serve a prefix
+of length `L` only if chunks `[0, L)` are present; a sliding window of `w` chunks
+needs only the last `min(w, L)`. Given each group's per-chunk presence, these
+operators produce the longest length **every** group can serve and the concrete
+chunks each group must keep.
+
+## Operators
+
+The pipeline is three composable operators (so the selection logic can evolve
+without rewriting the primitives):
+
+| Operator | Purpose |
+|---|---|
+| `fold` | Presence (`group x chunk x kv_rank`) → servable bitmap (bit `j` set iff every group can serve a length-`j+1` prefix). |
+| `highest_set_bit` | Highest set bit of a bitmap, or `-1` if none — on `fold`'s output, the hit length minus one (hit length = result + 1, so `-1` → 0). |
+| `unfold` | Hit length → per-group retain mask over the ranked layout. |
+
+Supporting / convenience:
+
+| Function | Purpose |
+|---|---|
+| `fold_unfold_ranked` | Composes `fold` → `highest_set_bit` → `unfold`. |
+| `fold_unfold` | `fold_unfold_ranked` for the single-rank (`group x chunk`) layout. |
+| `unfold_range` | Chunk range one group needs for a given hit length. |
+| `merge_bitmaps` | Bitwise-OR several presence bitmaps (e.g. L1 ∪ L2). |
+| `select_retained` | Non-windowed `TrimPolicy` selection (`PREFIX` = longest prefix; any other = keep every set bit). |
+
+A chunk counts as present for a group only when **all** its `kv_rank` shards are
+present, and `unfold` sets all ranks of each retained `(group, chunk)`. With a
+single full-attention group the result is plain longest-contiguous-prefix
+matching.
+
+## Performance
+
+`fold` and `unfold` delegate to native C++ (`csrc/storage_manager/fold.cpp`,
+exported as `native_storage_ops.fold` / `unfold`) and `highest_set_bit` to
+`Bitmap.highest_set_bit()`. They scan the packed `Bitmap` buffer directly —
+no Python per-bit loop and no `Bitmap`↔tensor conversion. `_fold_python` /
+`_unfold_python` are reference implementations used only as test oracles. See
+`benchmarks/microbenchmark/bitmap_ops_benchmark.py`
+(`python benchmarks/microbenchmark/bitmap_ops_benchmark.py`):
+
+| Case (full pipeline) | Python | native | speedup |
+|---|---|---|---|
+| DeepSeek 1M @256, 8 groups, world_size=8 (262k keys), all present | ~158 ms | ~0.6 ms | ~260× |
+| same, 50% prefix present (realistic) | ~75 ms | ~0.35 ms | ~215× |
+| world_size=1 (32k keys) | ~46 ms | ~0.17 ms | ~275× |
+| stress: 4M keys | ~1300 ms | ~5 ms | ~255× |
+
+`unfold` writes the retained keys back as contiguous spans via
+`Bitmap::set_range` (whole-byte fills) rather than per-bit sets, so even the
+all-present worst case stays sub-millisecond at the DeepSeek scale. The
+remaining cost is the presence scan in `fold`.
diff --git a/docs/design/v1/distributed/l2_adapters/dax.md b/docs/design/v1/distributed/l2_adapters/dax.md
new file mode 100644
index 0000000..43be084
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/dax.md
@@ -0,0 +1,139 @@
+# DAX L2 Adapter Design
+
+This document describes the built-in `dax` L2 adapter for LMCache
+multiprocess mode and how it shares implementation with the non-MP DAX
+storage backend.
+
+## Goals
+
+- Reuse one synchronous DAX core for MP and non-MP DAX storage.
+- Keep the MP controller flow unchanged: adapters still use the normal
+  submit, event-fd, and query-result contract.
+- Keep the adapter facade stable while the runtime DAX device pool changes.
+- Keep DAX volatile-only. Keys are indexed in process memory and are not
+  recovered from device bytes after restart.
+
+## Components
+
+`lmcache/v1/storage_backend/dax/core.py` defines `DaxCore[KeyT]`. The core owns
+the mapped DAX arena, fixed-size slot allocation, in-memory index, LRU order,
+in-flight writes, external lock refcounts, active read borrow counts, close
+coordination, and direct `ctypes.memmove` copies.
+
+`lmcache/v1/storage_backend/plugins/dax_backend.py` is the non-MP wrapper. It
+keeps existing non-MP behavior such as the local CPU backend requirement, TP=1
+validation, optional async put, and the staging-slab batched restore path.
+
+`lmcache/v1/distributed/l2_adapters/dax_l2_adapter.py` is the MP adapter. It
+self-registers adapter type `dax`, owns separate event notifiers and worker
+pools for store, lookup, and load operations, and uses one or more
+`DaxCore[ObjectKey]` instances behind a stable facade.
+
+`lmcache/v1/multiprocess/http_apis/reconfigure_api.py` exposes runtime
+reconfiguration endpoints:
+
+- `GET /reconfigure/dax/status`
+- `POST /reconfigure/dax/add`
+- `POST /reconfigure/dax/remove`
+- `POST /reconfigure/dax/resize`
+
+The HTTP layer routes `backend`, `operation`, and adapter-specific JSON payloads
+into the generic L2 adapter reconfiguration API on `StorageManager`.
+`StorageManager` only routes `operation` plus payload to a reconfigurable
+adapter; DAX path, mode, and migration semantics stay inside `DaxL2Adapter`.
+The same interface is intended for future adapters such as P2P, so the HTTP
+layer does not inspect private adapter lists or DAX core state directly.
+
+## Slot State
+
+Each committed key points to one fixed-size slot. A slot is reusable only when:
+
+- The key has been removed from the index.
+- No external lock is held for the key.
+- No store is in flight for the key.
+- No active read has borrowed the slot.
+
+Delete operations remove unlocked keys from the index immediately. If a read
+has borrowed the slot, the slot is marked pending-free and recycled when the
+borrow count reaches zero.
+
+## MP Flow
+
+Store:
+
+1. `StoreController` calls `submit_store_task(keys, objects)`.
+2. The adapter chooses an active DAX device. Existing keys prefer their current
+   mapped device; new keys use the active device with the lowest slot usage.
+3. A store worker copies each object into a DAX slot through `DaxCore.put_many`.
+4. The adapter records task-level success as `all(per_key_results)`.
+5. The store event fd is signaled and store listeners are notified for the keys
+   that were actually accepted by the core.
+
+Lookup and load:
+
+1. `PrefetchController` calls `submit_lookup_and_lock_task(keys)`.
+2. The adapter checks `key -> device` mappings first, then scans readable
+   devices if needed.
+3. The adapter calls `DaxCore.exists_many(keys, lock=True)` and returns a full
+   bitmap, including holes.
+4. Load workers call `DaxCore.load_many_into(keys, objects)` on the device that
+   currently owns each key.
+5. `submit_unlock(keys)` releases the external lock refcounts on every DAX
+   core. This is deliberate because migration can update `key -> device`
+   mappings between lookup and unlock.
+
+## Runtime Hotplug
+
+The DAX facade keeps the event fds and worker pools stable. Runtime hotplug only
+mutates the device pool behind the facade, so `StoreController`,
+`PrefetchController`, and the vLLM MP connector do not need ZMQ protocol changes
+or poll-set re-registration.
+
+Add:
+
+1. Validate `hotplug_enabled`, path, and size.
+2. Map a new `DaxCore[ObjectKey]`.
+3. Append a `DaxDeviceEntry(state="active")`.
+4. Return per-device status. Existing KV entries stay on their current devices.
+
+Remove with migration:
+
+1. Mark the source device `draining` so new stores do not choose it.
+2. Reject the operation if externally locked or borrowed slots would be deleted.
+3. Snapshot source keys and reserve source reads.
+4. Copy each reserved payload from the source DAX pointer into another active
+   DAX core with `put_reserved_from_ptr`.
+5. Update `key -> device` mappings, delete the source entries, then close the
+   source core.
+
+Resize:
+
+- Grow remaps the same core to a larger size after active reads and writes
+  drain. No KV payload movement is needed.
+- Shrink first proves that every live slot fits below the new slot count. If
+  not, the out-of-range keys must migrate to another active device or the
+  request fails. Shrink never silently evicts data.
+
+## Restart Behavior
+
+The adapter stores keys and metadata only in memory. Closing the adapter and
+opening a new adapter against the same DAX device starts with an empty index.
+Old bytes may remain on the device, but they are unreachable because PR1 does
+not define any on-device metadata, scan, checkpoint, or recovery format.
+
+## Capacity And Eviction
+
+Usage is slot-based, not payload-byte-based. `get_usage()` reports occupied
+slot capacity because the DAX arena is exhausted by slot count. The eviction
+controller calls `delete(keys)`, which skips externally locked keys and
+reclaims slots after active read borrows drain.
+
+Runtime capacity is the sum of active, draining, migrating, resizing, and
+removing device capacities. Closed, removed, and failed devices are excluded.
+
+## Current Limits
+
+- Runtime hotplug does not perform kernel-level CXL or DAX reconfiguration.
+- No per-TP partitioning.
+- No restart recovery.
+- Only single-buffer objects are supported.
diff --git a/docs/design/v1/distributed/l2_adapters/fault_inject.md b/docs/design/v1/distributed/l2_adapters/fault_inject.md
new file mode 100644
index 0000000..8145454
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/fault_inject.md
@@ -0,0 +1,100 @@
+# Fault-Injecting L2 Adapter
+
+`lmcache/v1/distributed/l2_adapters/fault_inject_l2_adapter.py`
+
+A **test/diagnostic-only** L2 adapter that wraps a real inner adapter (e.g.
+`fs_native`) and deterministically drops keys on the load read, simulating
+partial L2 retrieve failures. Its purpose is to exercise the **segmented**
+code paths — gapped found-set → segmented prefetch → segmented scatter /
+attention — that a healthy cache never produces, so CacheBlend's
+segmented-prefix handling can be tested without an actual faulty L2.
+
+## Fault model
+
+It faults the **load read primitive only**. A dropped key is reported
+**present at lookup** but its **load fails** — the faithful "L2 retrieve
+error". The lookup-miss case is *intentionally not modeled*: a key absent at
+lookup merely shortens the found-set, which the `PREFIX` trim policy
+(`count_leading_ones`) already covers. Modeling load-failure-after-lookup is
+what produces a *gapped* found-set (hit … miss … hit), the input the
+segmented path is built to handle.
+
+When a load fails, **no unlock is issued here** — the prefetch controller
+releases the load-failed read locks itself via the trim mask.
+
+## Drop selection
+
+A load position is dropped (`_drop_positions` / `_should_drop_key`) if **any**
+of the following hold:
+
+| knob | meaning | use |
+|---|---|---|
+| `gap_tail_ratios: list[float]` | positions given as **distance-from-tail ÷ load-length** in `[0,1]` (`0.0`=last, `0.5`=middle, `1.0`=first); the dropped slot `round((1-ratio)·(n-1))` is computed from the `n`-key load batch the server actually receives. **Workload-agnostic and self-scaling** — the server needs no advance knowledge of the stored content, and the same fraction picks the right chunk at any context length. | primary lever for segmented repros (drop the mid chunk → a stable gap at any length) |
+| `gap_indices: list[int]` | exact head-relative task-positions to always drop | precise single-gap unit tests |
+| `rate: float` + `seed: int` | per-key drop probability in `[0,1]` via a stable seeded hash of the key, bucketed by `rate` | randomized resilience sweeps; deterministic given the seed |
+
+Defaults are pass-through (`rate=0.0`, empty `gap_indices`/`gap_tail_ratios`).
+
+> **Why a ratio and not a chunk hash?** An earlier `drop_chunk_hashes` knob keyed
+> drops on `ObjectKey.chunk_hash` — content-addressed, so the *same* chunk failed
+> on every leg. But it forced the test author (and thus the server config) to know
+> a hash computed from a not-yet-stored workload, which inverted the dependency
+> (the server "knowing" a future workload). `gap_tail_ratios` is a positional rule
+> the server evaluates from the load batch alone, so no content needs to be known
+> in advance. Trade-off: the drop is **per-load-batch**, not content-identical
+> across legs — for the segmented-prefix repro the gap lives in the prefix leg's
+> load, which is exactly what's exercised.
+
+## Configuration
+
+Activated through `--l2-adapter` (or the engine L2 spec). The required
+`inner` sub-dict is a full adapter spec — dispatched through the L2 adapter
+config registry — so any inner adapter type works and keeps its own
+eviction/persist/serde config:
+
+```json
+{
+  "type": "fault_inject",
+  "inner": { "type": "fs_native", "base_path": "/dev/shm/cb_l2" },
+  "gap_tail_ratios": [0.5],
+  "rate": 0.0,
+  "seed": 0,
+  "gap_indices": []
+}
+```
+
+`"gap_tail_ratios": [0.5]` drops the middle chunk of every load — the stable
+mid-prefix gap the segmented repro needs, at any context length.
+
+At startup it logs `FaultInjectL2Adapter ACTIVE (rate=… seed=… gap_indices=…
+gap_tail_ratios=[…]) wrapping <inner> -- test/diagnostic use only.`
+
+## Data flow
+
+```
+submit_load_task(keys)         → delegate to inner; stash keys under task_id
+query_load_result(task_id)     → bitmap = inner.query_load_result(task_id)
+                                 for i in _drop_positions(keys): bitmap.clear(i)
+                                 return bitmap        # dropped bits now read "miss"
+```
+
+`submit_load_task` records the per-task key list so `query_load_result` can map
+the dropped bit positions back to keys; the result query is **non-idempotent**
+(a non-`None` bitmap is returned once per task), matching the inner contract.
+
+## Delegation
+
+Everything other than the load-result query passes straight through to the
+inner adapter: store, lookup-and-lock, unlock, delete, the event fds,
+listener registration, usage, and global-eviction support. The fault layer
+holds no data of its own. `report_status()` returns the inner status annotated
+with a `fault_inject` sub-dict (`rate`, `seed`, `gap_indices`,
+`gap_tail_ratios`) so the active fault config is visible in diagnostics.
+
+## Scope and safety
+
+Test/diagnostic only — never enable in production. It silently makes reads
+fail, so any served KV is intentionally incomplete. The primary consumer is
+the CacheBlend **segmented-prefix** validation (the `ci_v3_l2_hit`
+`segmented_prefix` workload sets `gap_tail_ratios=[0.5]` to force a gapped
+prefix, so V3 loads prefix+tail and recomputes only the gap).
diff --git a/docs/design/v1/distributed/l2_adapters/l2_eviction.md b/docs/design/v1/distributed/l2_adapters/l2_eviction.md
new file mode 100644
index 0000000..8d2a845
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/l2_eviction.md
@@ -0,0 +1,273 @@
+# L2 Adapter Eviction Design
+
+This document describes the eviction mechanism for L2 adapters: how eviction is
+configured, how the eviction controller tracks key lifecycle events, and how
+adapters participate in the eviction loop.
+
+## Overview
+
+L2 eviction is **per-adapter** and **opt-in**. Each L2 adapter instance can
+independently declare an eviction policy via its JSON config. Adapters without
+an `"eviction"` key in their config are excluded from the eviction loop.
+
+A single `L2EvictionController` manages all adapters that have eviction enabled.
+Its background thread loops over every adapter each cycle, checking usage and
+triggering eviction independently per adapter.
+
+## Architecture
+
+```
+StorageManager
+  │
+  └─ L2EvictionController  (single instance, single thread)
+       │
+       ├─ L2AdapterEvictionState[0]
+       │     adapter ──► L2Adapter[0]   (eviction_config set)
+       │     policy  ──► EvictionPolicy
+       │     listener ─► L2EvictionPolicy (bridge)
+       │
+       ├─ (L2Adapter[1] has no eviction config → not tracked)
+       │
+       └─ L2AdapterEvictionState[1]
+             adapter ──► L2Adapter[2]   (eviction_config set)
+             policy  ──► EvictionPolicy
+             listener ─► L2EvictionPolicy (bridge)
+```
+
+Each adapter with eviction enabled gets an `L2AdapterEvictionState` that bundles:
+
+- An **`EvictionPolicy`** instance (e.g., LRU) that tracks key state.
+- An **`L2EvictionPolicy`** listener bridge registered on the adapter. The
+  bridge translates adapter events into policy `on_keys_*` calls via
+  composition (no multi-inheritance).
+
+The controller and each adapter communicate through two channels:
+
+1. **Listener callbacks** — the `L2EvictionPolicy` bridge is registered as an
+   `L2AdapterListener` on the adapter. The adapter fires events when keys are
+   stored, accessed, or deleted, and the bridge forwards them to the eviction
+   policy to keep its key tracking up-to-date.
+
+2. **`delete(keys)`** — when the eviction policy decides to evict, the
+   controller calls `adapter.delete(keys)` directly. The adapter removes those
+   keys from its storage and fires an `on_l2_keys_deleted` callback, which the
+   bridge forwards to the policy so it removes them from its tracking state.
+
+## Configuration
+
+Eviction is configured as an optional `"eviction"` sub-object in each adapter's
+JSON spec passed to `--l2-adapter`:
+
+```json
+{
+  "type": "mock",
+  "max_size_gb": 10,
+  "mock_bandwidth_gb": 4,
+  "eviction": {
+    "eviction_policy": "LRU",
+    "trigger_watermark": 0.8,
+    "eviction_ratio": 0.2
+  }
+}
+```
+
+| Field               | Type    | Default | Description                                                     |
+|---------------------|---------|---------|-----------------------------------------------------------------|
+| `eviction_policy`   | string  | —       | Policy name: `"LRU"` or `"noop"`. Required.                    |
+| `trigger_watermark` | float   | `0.8`   | Usage fraction [0, 1] above which eviction is triggered.        |
+| `eviction_ratio`    | float   | `0.2`   | Fraction of **used** capacity to evict each cycle.              |
+
+If the `"eviction"` key is absent, no `L2AdapterEvictionState` is created for
+that adapter instance and it is excluded from the eviction loop.
+
+The eviction config is parsed by `L2AdapterConfigBase._parse_eviction_config()`
+and stored as `adapter_config.eviction_config: EvictionConfig | None`.
+
+## Key Components
+
+### `L2AdapterListener` (`internal_api.py`)
+
+Abstract interface for receiving L2 adapter events:
+
+```python
+class L2AdapterListener:
+    def on_l2_keys_stored(self, keys: list[ObjectKey]): ...
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]): ...
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]): ...
+```
+
+### Listener Infrastructure in `L2AdapterInterface` (`l2_adapters/base.py`)
+
+The base class owns the listener list and provides:
+
+- `register_listener(listener)` — adds a listener; called by
+  `L2AdapterEvictionState.__init__`.
+- `_notify_keys_stored(keys)` / `_notify_keys_accessed(keys)` /
+  `_notify_keys_deleted(keys)` — protected helpers that fan out to all
+  registered listeners. Adapter implementations call these after mutating
+  their storage.
+
+No per-adapter code is needed to support listeners — just call
+`super().__init__()` and use the `_notify_*` helpers.
+
+### `L2AdapterEvictionState` (`storage_controllers/eviction_controller.py`)
+
+Bundles the per-adapter eviction state: the adapter reference, its
+`EvictionConfig`, an `EvictionPolicy` instance, and an `L2EvictionPolicy`
+listener bridge. On construction, it registers the bridge on the adapter:
+
+```python
+L2AdapterEvictionState(adapter, eviction_config)
+  → creates EvictionPolicy from config
+  → creates L2EvictionPolicy(policy)   # listener bridge
+  → adapter.register_listener(bridge)  # subscribe to adapter events
+```
+
+### `L2EvictionPolicy` (`eviction.py`)
+
+Listener bridge that inherits only `L2AdapterListener` and delegates events
+to an `EvictionPolicy` via composition:
+
+| Callback               | Delegates to              |
+|------------------------|---------------------------|
+| `on_l2_keys_stored`    | `policy.on_keys_created`  |
+| `on_l2_keys_accessed`  | `policy.on_keys_touched`  |
+| `on_l2_keys_deleted`   | `policy.on_keys_removed`  |
+
+### `L2EvictionController` (`storage_controllers/eviction_controller.py`)
+
+A single controller that manages all adapters with eviction enabled. It owns
+one background thread and a list of `L2AdapterEvictionState` objects.
+
+**Eviction loop:**
+
+Every second, the thread iterates over all adapter states. For each adapter,
+it calls `adapter.get_usage()` which returns
+`(current_usage, usage_after_ongoing_eviction)`. If `current_usage` exceeds
+that adapter's `trigger_watermark`, the policy's
+`get_eviction_actions(eviction_ratio)` is called and the resulting keys are
+passed to `adapter.delete()`.
+
+### Eviction Policy (`eviction_policy/`)
+
+The eviction policy is a pure data structure — it tracks keys and decides which
+to evict. It has no knowledge of adapters or listeners:
+
+```
+EvictionPolicy (abstract)
+  ├─ LRUEvictionPolicy   — evicts least-recently-used keys
+  └─ NoOpEvictionPolicy  — never evicts
+```
+
+Policies are created by `CreateEvictionPolicy(eviction_config)` in
+`eviction_policy/factory.py`.
+
+## Adapter Implementation Guide
+
+To support eviction in a new adapter:
+
+1. **Call `super().__init__()`** in the adapter's `__init__`. This initializes
+   the listener list from the base class.
+
+2. **Fire `_notify_keys_stored(keys)`** after keys are durably written to L2
+   storage (e.g., after a store task completes).
+
+3. **Fire `_notify_keys_deleted(keys)`** inside `delete()` after keys are
+   removed. Only fire for keys that were actually removed — skip keys not found
+   and keys skipped due to pinning.
+
+4. **Fire `_notify_keys_accessed(keys)`** when a lookup or load marks a key as
+   recently used (optional — improves LRU accuracy).
+
+5. **Implement `delete(keys)`** to remove keys from storage. Pinned keys (in use
+   by an in-flight load) should be skipped; the eviction controller will retry
+   them on the next cycle.
+
+6. **Implement `get_usage() -> (current, projected)`** to return the current
+   storage utilization as a fraction in [0, 1]. `projected` may equal `current`
+   if in-flight deletions are not tracked.
+
+Adapters that do not support eviction (e.g., a remote adapter with unbounded
+capacity) can omit steps 2–6 and rely on the base class no-op defaults.
+
+## Adapter Support Matrix
+
+| Adapter                    | `delete` | `get_usage` | Listener events     |
+|----------------------------|----------|-------------|---------------------|
+| `MockL2Adapter`            | ✓        | ✓           | stored, deleted     |
+| `NixlStoreL2Adapter`       | ✓ (skips pinned) | ✓ (pool-based) | stored, deleted |
+| `RawBlockL2Adapter`        | ✓ (skips locked) | ✓ | stored, accessed, deleted |
+| `FSL2Adapter`              | no-op    | `(-1, -1)`  | none                |
+| `NativeConnectorL2Adapter` | ✓ (via `submit_batch_delete`) | ✓ (client-side, requires `max_capacity_gb`) | stored, deleted |
+
+**Note on `NativeConnectorL2Adapter`:** Eviction support requires two things:
+
+1. The underlying C++ connector must implement `do_single_delete()` (built-in Redis
+   and FS connectors do; third-party plugins may not — in which case `delete()` is a
+   no-op).
+2. The adapter must be configured with `max_capacity_gb > 0` to enable client-side
+   size tracking for `get_usage()`. Without it, `get_usage()` returns `(-1, -1)` and
+   the eviction controller will not trigger.
+
+Example configuration with eviction enabled:
+
+```json
+{
+  "type": "resp",
+  "host": "localhost",
+  "port": 6379,
+  "max_capacity_gb": 10,
+  "eviction": {
+    "eviction_policy": "LRU",
+    "trigger_watermark": 0.8,
+    "eviction_ratio": 0.2
+  }
+}
+```
+
+## Data Flow: Eviction Cycle
+
+```
+[Background thread — every 1s]
+  │
+  ▼
+for each L2AdapterEvictionState:
+  │
+  ▼
+  state.adapter.get_usage()
+    → (current_usage, _)
+    │
+    ├─ current_usage < watermark → skip this adapter
+    │
+    └─ current_usage ≥ watermark
+         │
+         ▼
+    state.policy.get_eviction_actions(eviction_ratio)
+         → list[EvictionAction(keys, destination=DISCARD)]
+         │
+         ▼
+    state.adapter.delete(eviction_action.keys)
+         │
+         ├─ removes keys from storage
+         └─ calls _notify_keys_deleted(deleted_keys)
+              │
+              ▼
+         L2EvictionPolicy bridge → policy.on_keys_removed
+              → updates internal tracking (e.g., LRU order)
+```
+
+## Relationship to L1 Eviction
+
+L1 and L2 eviction share the same policy classes (`LRUEvictionPolicy`,
+`NoOpEvictionPolicy`) and the same listener-bridge pattern (composition over
+multi-inheritance). They differ in how they are wired:
+
+| Aspect              | L1                                   | L2                                    |
+|---------------------|--------------------------------------|---------------------------------------|
+| Controller          | `L1EvictionController`               | `L2EvictionController`                |
+| Listener bridge     | `L1EvictionPolicy`                   | `L2EvictionPolicy`                    |
+| Listener interface  | `L1ManagerListener`                  | `L2AdapterListener`                   |
+| Usage source        | `L1Manager.get_memory_usage()`       | `L2AdapterInterface.get_usage()`      |
+| Config location     | `StorageManagerConfig.eviction_config` | `L2AdapterConfigBase.eviction_config` |
+| Cardinality         | One per `StorageManager`             | One controller for all adapters       |
+| Created by          | `StorageManager.__init__`            | `StorageManager.__init__`             |
diff --git a/docs/design/v1/distributed/l2_adapters/l2_per_user_quota.md b/docs/design/v1/distributed/l2_adapters/l2_per_user_quota.md
new file mode 100644
index 0000000..2a63242
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/l2_per_user_quota.md
@@ -0,0 +1,850 @@
+# L2 Per-User Quota Design
+
+This document describes the per-user quota mechanism for L2 adapters: how
+per-user storage limits are enforced, how user identity propagates through the
+system, and what changes are needed across the codebase.
+
+## Motivation
+
+Currently, L2 eviction operates on **aggregate** storage usage. A single
+`trigger_watermark` governs whether eviction fires, and the LRU policy evicts
+globally without regard to who stored what. In a multi-tenant serving
+environment (multiple users sharing a single vLLM + LMCache deployment), one
+user's burst of traffic can fill L2 and push out other users' cached KV data.
+
+Per-user quotas add a second eviction dimension: **each user has an independent
+storage budget**. When a user exceeds their budget, only that user's
+least-recently-used keys are evicted — other users' cached data remains
+untouched.
+
+## Design Overview
+
+```
+vLLM API Server
+  │  sends cache_salt directly on IPCCacheServerKey
+  ▼
+LMCache MP Server
+  │  ipc_key_to_object_keys(key, chunk_hashes)
+  │    reads key.cache_salt internally and propagates
+  ▼
+ObjectKey(chunk_hash, model_name, kv_rank, cache_salt="alice")
+  │                                         ▲
+  │                            cache_salt IS part of key identity
+  │                            (participates in __eq__ / __hash__)
+  │                            same tokens + different user = different key
+  ▼
+L1 Manager → StoreController → L2 Adapter
+  │                                │
+  │                    _notify_keys_stored(keys, sizes)
+  │                      → base class updates _total_bytes_used
+  │                        and _bytes_by_cache_salt
+  ▼
+Listeners:  L2EvictionPolicy bridge → IsolatedLRUEvictionPolicy
+            ┌──────────────────────┐
+            │ "alice" → OrderedDict │
+            │ "bob"   → OrderedDict │
+            └──────────────────────┘
+
+L2EvictionController (every 1s):
+  for each adapter state:
+    usage = adapter.get_usage()  → AdapterUsage dataclass
+    if policy.is_user_level:
+      for cache_salt, bytes in usage.bytes_by_cache_salt:
+        if bytes > watermark * quota(cache_salt):
+          policy.get_eviction_actions(ratio, cache_salt=cache_salt)
+    else:
+      if usage.usage_fraction ≥ watermark:
+        policy.get_eviction_actions(ratio)
+```
+
+## Key Design Decisions
+
+### 1. Strict User Isolation — `cache_salt` as ObjectKey Identity Field
+
+User identity is a **full identity field** on `ObjectKey`, participating in
+`__eq__` and `__hash__`:
+
+```python
+@dataclass(frozen=True)
+class ObjectKey:
+    chunk_hash: bytes
+    model_name: str
+    kv_rank: int
+    cache_salt: str = ""
+```
+
+Two ObjectKeys with the same (chunk_hash, model_name, kv_rank) but different
+`cache_salt` values are **different keys**. If Alice and Bob send identical token
+sequences, they produce separate ObjectKeys and store separate copies in both
+L1 and L2.
+
+**Why strict isolation?**
+
+- **No cross-user interference:** Evicting Alice's keys never affects Bob's
+  cache hits. Each user's cached data is fully independent.
+- **Simple ownership:** Every key belongs to exactly one user — no ambiguity,
+  no "first-storer-wins" races, no shared-ownership accounting.
+- **Clean retrieval:** Lookup and retrieve naturally scope to the correct
+  user because `cache_salt` is part of the key. No special filtering needed.
+- **Predictable quotas:** Per-user byte accounting is exact. A user's usage
+  equals the sum of their keys' sizes, with no shared entries to split.
+
+**Trade-off — storage duplication:** The same token sequence cached by N
+users consumes N times the storage (in both L1 and L2). This is the cost of
+strict isolation. In practice, this is acceptable for multi-tenant deployments
+where isolation guarantees outweigh storage efficiency, and where distinct
+users typically have distinct prompts anyway.
+
+### 2. Cache Salt Propagation: API → vLLM → LMCache
+
+User identity is derived from vLLM's **`cache_salt`** field — a per-request
+string already supported by the OpenAI-compatible API for prefix cache
+isolation. No custom `kv_transfer_params` or `extra_args` are needed.
+
+**Note:** In the context of per-user quotas, **one `cache_salt` value =
+one user**. All requests sharing the same `cache_salt` are treated as
+belonging to the same user and share a single quota and LRU list.
+Different `cache_salt` values are fully isolated from each other.
+
+**API caller** sets `cache_salt` per request:
+
+```json
+{
+  "model": "llama-3-8b",
+  "messages": [...],
+  "cache_salt": "alice"
+}
+```
+
+`cache_salt` already flows through vLLM as a first-class field:
+`request body → vLLM input processor → Request.cache_salt`. The LMCache
+MP connector (`lmcache_mp_connector.py` in the vLLM repo) stores
+`cache_salt` on the request tracker and passes it through metadata to
+both the scheduler and worker adapters.
+
+**Propagation path:**
+
+Both the scheduler adapter (LOOKUP) and worker adapter (STORE/RETRIEVE)
+receive `cache_salt` from the vLLM connector via
+`LMCacheMPRequestMetadata`. Both set `cache_salt` on `IPCCacheServerKey`
+directly. No server-side session caching is needed.
+
+```
+API request body
+  │  cache_salt = "alice"
+  ▼
+vLLM Request.cache_salt = "alice"     (first-class vLLM field)
+  ▼
+lmcache_mp_connector.py               (vLLM's LMCache connector)
+  │  LMCacheMPRequestTracker stores request.cache_salt
+  │  LMCacheMPRequestMetadata carries cache_salt to worker
+  ▼
+Scheduler path (LOOKUP):
+  scheduler_adapter.maybe_submit_lookup_request(
+      request_id, token_ids, cache_salt=tracker.cache_salt)
+  → _create_key(..., cache_salt="alice")
+  → IPCCacheServerKey(cache_salt="alice", ...)  ──LOOKUP──►  MP Server
+                                                           │
+Worker path (STORE/RETRIEVE):                              │
+  worker_adapter.batched_submit_store_requests(            │
+      request_ids, ops, event, cache_salts=["alice", ...])    │
+  → _create_key(..., cache_salt="alice")                      │
+  → IPCCacheServerKey(cache_salt="alice", ...) ──STORE──►  MP Server
+                                                           │
+                                              key.cache_salt = "alice"
+                                              ipc_key_to_object_keys(key, hashes)
+                                                — reads key.cache_salt
+                                              → ObjectKey(cache_salt="alice", ...)
+```
+
+Because both scheduler and worker set `cache_salt` directly on the IPC key,
+the server simply reads `key.cache_salt` in all code paths. No session-based
+fallback is needed.
+
+`cache_salt` is added as an identity field on `IPCCacheServerKey` (with
+`compare=True`, unlike `request_id`). `request_id` is ephemeral session
+metadata — two requests with different `request_id`s but the same tokens
+should hit the same cache. `cache_salt` is the opposite: same tokens from
+different users must **not** match. This is consistent with `cache_salt`
+participating in `ObjectKey.__eq__` / `__hash__`.
+
+```python
+@dataclass(order=True, frozen=True)
+class IPCCacheServerKey:
+    model_name: str
+    world_size: int
+    worker_id: int | None
+    token_ids: tuple[int, ...]
+    start: int
+    end: int
+    request_id: str = field(compare=False)   # position 7 — unchanged
+    cache_salt: str = ""                         # position 8 — appended at end
+```
+
+`cache_salt` is placed **after** `request_id` (at the end) to preserve
+msgspec wire compatibility. `IPCCacheServerKey` is serialized positionally
+via `msgspec.msgpack`; appending `cache_salt` at the end means an old client
+sending 7 fields to a new server will decode correctly with `cache_salt`
+defaulting to `""`. No changes to existing field positions.
+
+`no_worker_id_version()` must be updated to preserve `cache_salt` when
+copying the key (currently reconstructs explicitly and would drop the
+new field).
+
+### 3. Dynamic Per-User Quotas via `QuotaManager`
+
+Per-user quotas are **dynamic** — they can be created, updated, and deleted
+at runtime via the HTTP API. A `QuotaManager` holds the per-user limit
+registry and is queried by the eviction controller each cycle.
+
+**Quota lookup rules:**
+
+1. If a cache_salt has an explicit entry in the quota registry → use that limit.
+2. If a cache_salt has **no** entry → effective limit is **0 bytes**.
+   - Stores are still allowed (we never reject writes on the hot path).
+   - At the next eviction cycle (~1s), the controller sees
+     `usage > 0 > limit 0` and triggers eviction.
+   - The user's keys are evicted, freeing the space.
+
+This means the system is **allowlist-based**: only users with an explicit
+quota can retain cached data. Unknown users get temporary write access, but
+their data is cleaned up within one eviction cycle.
+
+Per-user quotas are enabled by choosing the `IsolatedLRU` eviction policy.
+If the operator does not want per-user quotas, they simply use the `LRU`
+policy — no special "disable" flag is needed.
+
+### 4. HTTP API for Quota Management
+
+The existing FastAPI HTTP server (`lmcache/v1/multiprocess/http_server.py`)
+already serves `/healthcheck`, `/status`, and `/cache/clear`.
+Add quota management endpoints:
+
+```
+PUT    /quota/{cache_salt}          Set/update quota for a user
+GET    /quota/{cache_salt}          Get quota and current usage for a user
+DELETE /quota/{cache_salt}          Remove quota (user's data evicted next cycle)
+GET    /quota                    List all quotas and per-user usage
+```
+
+**`_default` sentinel:** Empty strings cannot be URL path parameters. Use
+`_default` as the `cache_salt` in the URL to refer to the `cache_salt=""`
+namespace (anonymous / un-isolated traffic). For example,
+`PUT /quota/_default` sets the quota for `cache_salt=""`.
+
+**`PUT /quota/{cache_salt}`** — Set or update a user's quota.
+`limit_gb` is required.
+
+```json
+// Request body
+{"limit_gb": 2.0}
+
+// Response
+{"cache_salt": "alice", "limit_gb": 2.0, "status": "ok"}
+```
+
+**`GET /quota/{cache_salt}`** — Get quota and current usage.
+
+```json
+// Response
+{
+  "cache_salt": "alice",
+  "limit_gb": 2.0,
+  "current_usage_gb": 1.3,
+  "exists": true
+}
+```
+
+**`DELETE /quota/{cache_salt}`** — Remove quota entry. The user's cached
+data will be evicted at the next eviction cycle (effective limit becomes 0).
+
+```json
+// Response
+{"cache_salt": "alice", "status": "removed"}
+```
+
+**`GET /quota`** — List all registered quotas with per-user usage.
+
+```json
+// Response
+{
+  "users": {
+    "alice": {"limit_gb": 2.0, "current_usage_gb": 1.3},
+    "bob":   {"limit_gb": 5.0, "current_usage_gb": 4.1}
+  }
+}
+```
+
+### 5. Policy Selection
+
+Set `eviction_policy: "IsolatedLRU"` in the adapter's eviction config to
+enable per-user quotas. `"LRU"` retains existing aggregate-only behavior.
+See the **Configuration** section for the full JSON example.
+
+## Component Changes
+
+### 1. `ObjectKey` and `ipc_key_to_object_keys()`
+
+**File:** `lmcache/v1/distributed/api.py`
+
+Add `cache_salt: str = ""` to `ObjectKey` (as shown in section 1).
+`ipc_key_to_object_keys()` reads `ipc_key.cache_salt` directly and
+propagates it to each constructed `ObjectKey` — no separate parameter,
+so callers cannot accidentally drop the salt.
+
+### 2. Server — `cache_salt` is carried by `IPCCacheServerKey`
+
+**File:** `lmcache/v1/multiprocess/server.py`
+
+Since both the scheduler and worker adapters set `cache_salt` on
+`IPCCacheServerKey`, the server simply calls `ipc_key_to_object_keys(...)`
+and the salt flows through automatically:
+
+```python
+obj_keys = ipc_key_to_object_keys(key, chunk_hashes)
+```
+
+**`session.py` is unchanged** — no `cache_salt` field needed on `Session`.
+
+### 3. vLLM Connector & Adapter Layer
+
+**File (vLLM repo):**
+`vllm/distributed/kv_transfer/kv_connector/v1/lmcache_mp_connector.py`
+
+The MP connector stores `cache_salt` on the request tracker and
+propagates it through metadata to both scheduler and worker:
+
+```python
+# LMCacheMPRequestTracker.__init__:
+self.cache_salt: str = request.cache_salt or ""
+
+# LMCacheMPRequestMetadata: add field
+cache_salt: str = ""
+
+# GetStoreMetadata / GetRetrieveMetadata: copy from tracker
+cache_salt=tracker.cache_salt
+
+# Scheduler LOOKUP call:
+self.scheduler_adapter.maybe_submit_lookup_request(
+    request.request_id,
+    token_ids=list(request.all_token_ids),
+    cache_salt=tracker.cache_salt,
+)
+
+# Worker start_load_kv / wait_for_save:
+# Pass cache_salts alongside request_ids
+cache_salts = [meta.cache_salt for meta in metadata.requests if ...]
+self.worker_adapter.batched_submit_store_requests(
+    request_ids, ops, event, cache_salts=cache_salts)
+self.worker_adapter.batched_submit_retrieve_requests(
+    request_ids, ops, event, cache_salts=cache_salts)
+```
+
+**File (LMCache repo):**
+`lmcache/integration/vllm/vllm_multi_process_adapter.py`
+
+**Scheduler adapter** (LOOKUP path):
+
+- `maybe_submit_lookup_request(request_id, token_ids, cache_salt="")`
+- `free_lookup_locks(..., cache_salt="")`
+- `_create_key(..., cache_salt="")` — passes `cache_salt` to `IPCCacheServerKey`
+
+**Worker adapter** (STORE/RETRIEVE path):
+
+- `batched_submit_store_requests(request_ids, ops, event, cache_salts=None)`
+- `batched_submit_retrieve_requests(request_ids, ops, event, cache_salts=None)`
+- `submit_store_request(request_id, op, event, cache_salt="")`
+- `submit_retrieve_request(request_id, op, event, cache_salt="")`
+- `_create_key(..., cache_salt="")` — passes `cache_salt` to `IPCCacheServerKey`
+
+Both adapters' `_create_key()` passes `cache_salt` through:
+
+```python
+def _create_key(self, token_ids, start, end, request_id, cache_salt=""):
+    return IPCCacheServerKey(
+        model_name=self.model_name,
+        world_size=self.world_size,
+        worker_id=...,
+        token_ids=tuple(token_ids),
+        start=start, end=end,
+        request_id=request_id,
+        cache_salt=cache_salt,
+    )
+```
+
+**Non-MP adapters (`vllm_v1_adapter.py`, lookup clients) are unchanged.**
+Per-user quota is an MP-mode-only feature.
+
+### 4. Unified Usage Tracking in the Adapter Base Class
+
+**File:** `lmcache/v1/distributed/l2_adapters/base.py`
+
+All byte tracking — both aggregate and per-user — lives in the base class
+and is updated exclusively in `_notify_keys_stored` / `_notify_keys_deleted`.
+Adapters do not maintain their own byte counters. They pass `sizes` to
+the `_notify_*` helpers and the base class does all accounting.
+
+A new `AdapterUsage` dataclass replaces both the old `get_usage()` (which
+returned a `tuple[float, float]`) and `get_per_user_usage()` (which
+returned a `dict`) with a single structured report:
+
+```python
+@dataclass(frozen=True)
+class AdapterUsage:
+    """Unified usage report for an L2 adapter."""
+
+    total_bytes_used: int
+    """Aggregate bytes across all users."""
+
+    total_capacity_bytes: int
+    """Adapter's maximum capacity. 0 means unknown/unlimited."""
+
+    bytes_by_cache_salt: dict[str, int]
+    """Bytes used per cache_salt. Only entries with positive usage."""
+
+    @property
+    def usage_fraction(self) -> float:
+        """Aggregate usage as a fraction in [0, 1]. -1 if capacity unknown."""
+        if self.total_capacity_bytes <= 0:
+            return -1.0
+        return self.total_bytes_used / self.total_capacity_bytes
+```
+
+Base class changes:
+
+```python
+class L2AdapterInterface(ABC):
+    def __init__(self, max_capacity_bytes: int = 0):
+        self._listeners: list[L2AdapterListener] = []
+        self._max_capacity_bytes = max_capacity_bytes
+        self._total_bytes_used: int = 0
+        self._bytes_by_cache_salt: dict[str, int] = {}
+        self._usage_lock = threading.Lock()
+
+    @property
+    def supports_global_eviction(self) -> bool:
+        """Whether this adapter supports eviction.
+
+        True when the adapter declared a positive capacity via
+        max_capacity_bytes. Adapters that don't support eviction
+        (e.g., FSL2Adapter) pass 0 and this returns False.
+        """
+        return self._max_capacity_bytes > 0
+
+    def _notify_keys_stored(
+        self, keys: list[ObjectKey], sizes: list[int]
+    ) -> None:
+        with self._usage_lock:
+            for key, size in zip(keys, sizes, strict=True):
+                self._total_bytes_used += size
+                self._bytes_by_cache_salt[key.cache_salt] = (
+                    self._bytes_by_cache_salt.get(key.cache_salt, 0) + size
+                )
+        for listener in self._listeners:
+            listener.on_l2_keys_stored(keys)
+
+    def _notify_keys_deleted(
+        self, keys: list[ObjectKey], sizes: list[int]
+    ) -> None:
+        with self._usage_lock:
+            for key, size in zip(keys, sizes, strict=True):
+                self._total_bytes_used -= size
+                self._bytes_by_cache_salt[key.cache_salt] = (
+                    self._bytes_by_cache_salt.get(key.cache_salt, 0) - size
+                )
+        for listener in self._listeners:
+            listener.on_l2_keys_deleted(keys)
+
+    def get_usage(self) -> AdapterUsage:
+        with self._usage_lock:
+            return AdapterUsage(
+                total_bytes_used=self._total_bytes_used,
+                total_capacity_bytes=self._max_capacity_bytes,
+                bytes_by_cache_salt={
+                    k: v for k, v in self._bytes_by_cache_salt.items()
+                    if v > 0
+                },
+            )
+```
+
+`_notify_keys_accessed(keys)` is unchanged — it does not affect byte
+counts. The external `L2AdapterListener` interface still receives only
+keys — `sizes` is internal to the adapter/base-class boundary.
+
+### 5. Adapter Implementations
+
+Each adapter passes `max_capacity_bytes` to `super().__init__()` and
+fires `_notify_keys_stored(keys, sizes)` / `_notify_keys_deleted(keys,
+sizes)`. The base class handles all byte accounting.
+
+**What each adapter removes:**
+- `_current_size_bytes` counter
+- `get_usage()` override
+- `get_per_user_usage()` override (if any)
+
+**What each adapter adds/keeps:**
+- `super().__init__(max_capacity_bytes=...)` in `__init__`
+- `_notify_keys_stored(stored_keys, sizes=stored_sizes)` after store
+- `_notify_keys_deleted(deleted_keys, sizes=deleted_sizes)` after delete
+
+| Adapter | `max_capacity_bytes` source | `supports_global_eviction` |
+|---------|-----------------------------|---------------------|
+| MockL2Adapter | `int(config.max_size_gb * 1024**3)` | `True` |
+| NixlStoreL2Adapter | Pool total size | `True` |
+| RawBlockL2Adapter | RawBlockCore usable capacity | `True` |
+| NativeConnectorL2Adapter | `int(max_capacity_gb * 1024**3)` | `True` |
+| FSL2Adapter | 0 | `False` |
+
+`L2AdapterEvictionState` is only created for adapters where both
+`eviction_config is not None` AND `adapter.supports_global_eviction` are true.
+Adapters that don't support eviction are excluded from the eviction loop
+entirely — no runtime checks needed.
+
+Future adapters inherit all tracking automatically — just call
+`super().__init__(max_capacity_bytes=...)` and fire `_notify_*` with
+sizes.
+
+### 6. `EvictionPolicy` — `is_user_level` property
+
+**File:** `lmcache/v1/distributed/eviction.py`
+
+Add a property to the abstract base class. The eviction controller uses
+this to decide whether to check per-user quotas or aggregate usage —
+no `isinstance` checks.
+
+```python
+class EvictionPolicy:
+    @property
+    def is_user_level(self) -> bool:
+        """Whether this policy supports per-user eviction.
+
+        When True, the controller checks per-user usage and passes
+        cache_salt to get_eviction_actions(). When False, the
+        controller uses aggregate usage only.
+        """
+        return False
+```
+
+| Policy | `is_user_level` |
+|--------|----------------|
+| `LRUEvictionPolicy` | `False` (inherits default) |
+| `NoOpEvictionPolicy` | `False` (inherits default) |
+| `IsolatedLRUEvictionPolicy` | `True` (override) |
+
+### 7. `IsolatedLRUEvictionPolicy` — Per-user LRU tracking
+
+**File (new):** `lmcache/v1/distributed/eviction_policy/isolated_lru.py`
+
+Overrides `is_user_level` to return `True`. `get_eviction_actions` gains
+an optional `cache_salt` parameter. When set, eviction is scoped to that
+user's LRU list. When `None` (default), eviction is global.
+
+```python
+class IsolatedLRUEvictionPolicy(EvictionPolicy):
+
+    @property
+    def is_user_level(self) -> bool:
+        return True
+
+    def __init__(
+        self,
+        default_destination: EvictionDestination = EvictionDestination.DISCARD,
+    ):
+        self._lock = threading.Lock()
+        self._per_user_order: dict[str, OrderedDict[ObjectKey, None]] = {}
+        self._default_destination = default_destination
+
+    def on_keys_created(self, keys: list[ObjectKey]):
+        with self._lock:
+            for key in reversed(keys):
+                cache_salt = key.cache_salt
+                if cache_salt not in self._per_user_order:
+                    self._per_user_order[cache_salt] = OrderedDict()
+                user_order = self._per_user_order[cache_salt]
+                if key in user_order:
+                    user_order.move_to_end(key)
+                else:
+                    user_order[key] = None
+
+    def on_keys_touched(self, keys: list[ObjectKey]):
+        with self._lock:
+            for key in reversed(keys):
+                cache_salt = key.cache_salt
+                user_order = self._per_user_order.get(cache_salt)
+                if user_order and key in user_order:
+                    user_order.move_to_end(key)
+
+    def on_keys_removed(self, keys: list[ObjectKey]):
+        with self._lock:
+            for key in keys:
+                cache_salt = key.cache_salt
+                user_order = self._per_user_order.get(cache_salt)
+                if user_order:
+                    user_order.pop(key, None)
+                    if not user_order:
+                        del self._per_user_order[cache_salt]
+
+    def get_eviction_actions(
+        self,
+        expected_ratio: float,
+        cache_salt: str | None = None,
+    ) -> list[EvictionAction]:
+        """Select victims, optionally scoped to a user.
+
+        Args:
+            expected_ratio: Fraction of keys to evict.
+            cache_salt: If set, evict from this user's list only.
+                If None, evict globally across all users.
+        """
+        with self._lock:
+            if cache_salt is not None:
+                order = self._per_user_order.get(cache_salt)
+                if not order:
+                    return []
+                pool = list(order.keys())
+            else:
+                pool = []
+                for user_order in self._per_user_order.values():
+                    pool.extend(user_order.keys())
+
+            if not pool:
+                return []
+
+            expected_ratio = max(0.0, min(1.0, expected_ratio))
+            target = int(len(pool) * expected_ratio)
+            if expected_ratio > 0 and target == 0 and len(pool) > 0:
+                target = 1
+            if target == 0:
+                return []
+
+            return [EvictionAction(
+                keys=pool[:target],
+                destination=self._default_destination,
+            )]
+```
+
+**`EvictionPolicy` abstract class** — add `cache_salt: str | None = None`
+to `get_eviction_actions`. Existing implementations (`LRUEvictionPolicy`,
+`NoOpEvictionPolicy`) accept and ignore it — backward compatible.
+
+### 8. L2 Eviction Controller — Per-user eviction trigger
+
+**File:** `lmcache/v1/distributed/storage_controllers/eviction_controller.py`
+
+The controller receives a reference to the `QuotaManager`. Each eviction
+cycle it finds **all** users who violate their watermark threshold and
+evicts from each of them. After one cycle, no user should be violating.
+
+```python
+class L2EvictionController(StorageControllerInterface):
+    def __init__(
+        self,
+        l2_adapter_states: list[L2AdapterEvictionState],
+        quota_manager: QuotaManager,
+    ):
+        self._adapter_states = l2_adapter_states
+        self._quota_manager = quota_manager
+        ...
+
+    def _check_and_evict(self, state: L2AdapterEvictionState):
+        watermark = state.eviction_config.trigger_watermark
+        eviction_ratio = state.eviction_config.eviction_ratio
+        policy = state.eviction_policy
+        usage = state.adapter.get_usage()
+
+        if policy.is_user_level and self._quota_manager:
+            # Per-user watermark check
+            for cache_salt, user_bytes in usage.bytes_by_cache_salt.items():
+                limit = self._quota_manager.get_limit_bytes(cache_salt)
+                if user_bytes <= watermark * limit:
+                    continue
+                effective_ratio = 1.0 if limit == 0 else eviction_ratio
+                actions = policy.get_eviction_actions(
+                    effective_ratio, cache_salt=cache_salt
+                )
+                for action in actions:
+                    self._execute_eviction_action(state.adapter, action)
+        else:
+            # Global aggregate watermark
+            if usage.usage_fraction < watermark:
+                return
+            actions = policy.get_eviction_actions(eviction_ratio)
+            for action in actions:
+                self._execute_eviction_action(state.adapter, action)
+```
+
+The controller uses `policy.is_user_level` (not `isinstance`) to branch:
+- **`is_user_level=True`**: reads `usage.bytes_by_cache_salt`, checks each user
+  against `watermark * quota`. Unregistered users (quota=0) get ratio=1.0.
+- **`is_user_level=False`**: reads `usage.usage_fraction` for global check.
+
+## Configuration
+
+### Example: L2 adapter with per-user quota
+
+```json
+{
+  "type": "mock",
+  "max_size_gb": 10,
+  "mock_bandwidth_gb": 4,
+  "eviction": {
+    "eviction_policy": "IsolatedLRU",
+    "trigger_watermark": 0.8,
+    "eviction_ratio": 0.2
+  }
+}
+```
+
+| Field               | Type    | Default | Description                                           |
+|---------------------|---------|---------|-------------------------------------------------------|
+| `eviction_policy`   | string  | —       | `"LRU"`, `"IsolatedLRU"`, or `"noop"`. Required.         |
+| `trigger_watermark` | float   | `0.8`   | Usage fraction to trigger eviction. For `LRU`: against aggregate capacity. For `IsolatedLRU`: against each user's quota. |
+| `eviction_ratio`    | float   | `0.2`   | Fraction of keys to evict each cycle.                 |
+
+### Usage examples
+
+```bash
+# Send a request with user identity
+curl -X POST http://vllm:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model": "llama-3-8b", "messages": [...], "cache_salt": "alice"}'
+
+# Manage quotas at runtime
+curl -X PUT http://localhost:8000/quota/alice \
+  -H "Content-Type: application/json" -d '{"limit_gb": 2.0}'
+curl http://localhost:8000/quota/alice
+curl -X DELETE http://localhost:8000/quota/alice
+curl http://localhost:8000/quota
+```
+
+## Behavioral Notes
+
+- **No cache_salt from API:** When the API caller doesn't set `cache_salt`,
+  `request.cache_salt` is `None`, which maps to `cache_salt=""`.
+  `IPCCacheServerKey.cache_salt` defaults to `""`. All such keys share the
+  same (anonymous) namespace.
+- **`eviction_policy: "LRU"`:** Per-user quota logic is not active. The
+  watermark is applied against aggregate capacity as before. Existing
+  behavior is fully unchanged.
+- **ObjectKey equality:** `cache_salt` is part of identity (eq/hash). Two
+  `ObjectKey`s with different salts are distinct, preventing cross-user
+  collisions. With the default `cache_salt=""` all un-salted traffic
+  hashes identically (unchanged from the pre-cache_salt adapter).
+- **Serialization format — trailing salt:** ``cache_salt`` is appended as
+  a 4th field when non-empty; unsalted keys use the 3-field shape, which
+  is bit-identical to the pre-cache_salt format:
+
+  ```python
+  def _object_key_to_string(key: ObjectKey) -> str:
+      base = f"{key.model_name}@{key.kv_rank:08x}@{key.chunk_hash.hex()}"
+      if key.cache_salt:
+          return f"{base}@{key.cache_salt}"
+      return base
+  ```
+
+  Because un-salted wire keys and filenames are unchanged, existing
+  cache directories and remote stores need **no migration**. Parsers
+  split on ``@`` and dispatch by field count (3 vs 4); both
+  ``model_name`` and ``cache_salt`` are forbidden from containing
+  ``@`` so the parse is unambiguous.
+
+- **Listener interface:** `L2AdapterListener` method signatures are unchanged.
+  `cache_salt` flows through `ObjectKey.cache_salt`, not through callback
+  parameters.
+
+## PR Plan
+
+The implementation is split into 6 PRs to keep each reviewable and
+independently mergeable. **Merge order matters** for wire compatibility.
+
+```
+PR1a (LMCache adapter) ──► PR1b (vLLM connector)
+                                  │
+PR2  (LMCache data model) ────────┤
+                                  ├──► PR5 (per-user LRU)
+PR3  (LMCache adapter interface) ─┤
+                                  │
+PR4  (LMCache eviction policy) ───┘
+```
+
+PR1a, PR2, PR3, PR4 are independent — can merge in any order.
+PR1b depends on PR1a (LMCache must accept `cache_salt` before vLLM sends it).
+PR5 depends on all others.
+
+### PR1a — LMCache: Adapter `cache_salt` plumbing (LMCache repo)
+
+Add `cache_salt=""` defaults to scheduler and worker adapter interfaces.
+No-op with defaults — safe to merge independently.
+
+| File | Change |
+|------|--------|
+| `lmcache/integration/vllm/vllm_multi_process_adapter.py` | Scheduler: `cache_salt=""` on `maybe_submit_lookup_request`, `free_lookup_locks`, `_create_key`. Worker: `cache_salt=""` on `submit_store_request`, `submit_retrieve_request`, `batched_submit_*`, `_create_key`. |
+
+### PR1b — vLLM: Connector propagates `cache_salt` (vLLM repo)
+
+Populate `cache_salt` from `request.cache_salt` and pass to adapters.
+
+| File | Change |
+|------|--------|
+| `vllm/.../lmcache_mp_connector.py` | Store `cache_salt` on `LMCacheMPRequestTracker`; add `cache_salt` to `LMCacheMPRequestMetadata`; pass to scheduler + worker adapter methods |
+
+### PR2 — LMCache: `cache_salt` on data model + server (LMCache repo)
+
+Add `cache_salt` to `ObjectKey` and `IPCCacheServerKey`. Server passes
+it through. Update serialization. No behavioral change with `cache_salt=""`.
+
+| File | Change |
+|------|--------|
+| `lmcache/v1/distributed/api.py` | `cache_salt: str = ""` on `ObjectKey` with `__post_init__` validation (`@`, `/`, `\`, NUL, length cap on `cache_salt`; `@` rejected on `model_name`); `ipc_key_to_object_keys()` reads `ipc_key.cache_salt` directly (no separate param) |
+| `lmcache/v1/multiprocess/custom_types.py` | `cache_salt: str = ""` on `IPCCacheServerKey` with `__post_init__` validation; update `no_worker_id_version()`, `from_token_ids()` |
+| `lmcache/v1/multiprocess/server.py` / `blend_server_v2.py` | No code changes — existing `ipc_key_to_object_keys(key, chunk_hashes)` calls now carry salt automatically |
+| `lmcache/integration/vllm/vllm_multi_process_adapter.py` | Scheduler + worker `_create_key()` now forward `cache_salt` to `IPCCacheServerKey` |
+| `lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py` | `_object_key_to_string()` appends trailing `@<cache_salt>` when salted; un-salted output is unchanged |
+| `lmcache/v1/distributed/l2_adapters/fs_l2_adapter.py` | `_object_key_to_filename()` / `_filename_to_object_key()` accept 3-field (unsalted) or 4-field (salted) shapes |
+| `csrc/storage_backends/fs/connector.cpp` | `key_to_filename()` splits on `@` and dispatches by field count |
+
+### PR3 — LMCache: Adapter interface refactor (LMCache repo)
+
+`AdapterUsage` dataclass, `supports_global_eviction` property, unified
+`get_usage()`, `_notify_*` with `sizes`. Purely internal refactor —
+existing LRU eviction behavior unchanged.
+
+| File | Change |
+|------|--------|
+| `lmcache/v1/distributed/l2_adapters/base.py` | `AdapterUsage` dataclass; `max_capacity_bytes` + `supports_global_eviction`; `_notify_*` with `sizes`; unified `get_usage() -> AdapterUsage` |
+| `lmcache/v1/distributed/l2_adapters/mock_l2_adapter.py` | Pass `max_capacity_bytes` to super; pass `sizes` to `_notify_*`; remove `_current_size_bytes`, `get_usage()` |
+| `lmcache/v1/distributed/l2_adapters/nixl_store_l2_adapter.py` | Same |
+| `lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py` | Same |
+| `lmcache/v1/distributed/l2_adapters/mooncake_store_l2_adapter.py` | Same (if fires `_notify_*` directly) |
+| `lmcache/v1/distributed/storage_controllers/eviction_controller.py` | Use `AdapterUsage.usage_fraction` instead of tuple |
+| `lmcache/v1/distributed/storage_manager.py` | Filter `L2AdapterEvictionState` by `adapter.supports_global_eviction` |
+
+### PR4 — LMCache: Eviction policy interface (LMCache repo)
+
+`is_user_level` property, `cache_salt` param on `get_eviction_actions`.
+No new policies yet — just the interface extension.
+
+| File | Change |
+|------|--------|
+| `lmcache/v1/distributed/eviction.py` | `is_user_level` property (default `False`); `cache_salt` param on `get_eviction_actions()` |
+| `lmcache/v1/distributed/eviction_policy/lru.py` | Accept (ignore) `cache_salt` |
+| `lmcache/v1/distributed/eviction_policy/noop.py` | Accept (ignore) `cache_salt` |
+
+### PR5 — LMCache: Per-user LRU eviction (LMCache repo)
+
+The feature PR. Depends on PR1a + PR1b + PR2 + PR3 + PR4.
+
+| File | Change |
+|------|--------|
+| `lmcache/v1/distributed/eviction_policy/isolated_lru.py` (new) | `IsolatedLRUEvictionPolicy` |
+| `lmcache/v1/distributed/quota_manager.py` (new) | `QuotaManager` |
+| `lmcache/v1/distributed/eviction_policy/factory.py` | Register `"IsolatedLRU"` |
+| `lmcache/v1/distributed/eviction_policy/__init__.py` | Export `IsolatedLRUEvictionPolicy` |
+| `lmcache/v1/distributed/config.py` | Add `"IsolatedLRU"` to literal |
+| `lmcache/v1/distributed/l2_adapters/config.py` | Add `"IsolatedLRU"` to allowed values |
+| `lmcache/v1/distributed/storage_controllers/eviction_controller.py` | `QuotaManager`; per-user branch using `is_user_level` + `bytes_by_cache_salt` |
+| `lmcache/v1/distributed/storage_manager.py` | Create `QuotaManager`; wire to controller + HTTP |
+| `lmcache/v1/multiprocess/http_server.py` | Quota CRUD endpoints |
+| `tests/v1/distributed/test_isolated_lru_eviction_policy.py` (new) | Unit tests |
+| `tests/v1/distributed/test_quota_manager.py` (new) | Unit tests |
+| `tests/v1/distributed/test_per_user_l2_eviction.py` (new) | Integration tests |
diff --git a/docs/design/v1/distributed/l2_adapters/nixl_store.md b/docs/design/v1/distributed/l2_adapters/nixl_store.md
new file mode 100644
index 0000000..8eb2837
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/nixl_store.md
@@ -0,0 +1,296 @@
+# Nixl Store L2 Adapter Design
+
+## Overview
+
+The Nixl L2 adapter family implements `L2AdapterInterface` using the
+[Nixl](https://github.com/ai-infra-org/nixl) library to offload KV-cache
+objects from L1 (DRAM/VRAM) to a secondary storage tier via DMA. There are
+two variants:
+
+| Adapter | Type name | Storage mode | Persist | Backends |
+|---|---|---|---|---|
+| `NixlStoreL2Adapter` | `nixl_store` | Static (pre-allocated files) | Not supported | GDS, GDS_MT, POSIX, HF3FS, OBJ, AZURE_BLOB |
+| `DynamicNixlStoreL2Adapter` | `nixl_store_dynamic` | Dynamic (per-operation files) | Supported (default on) | GDS, GDS_MT, POSIX, HF3FS |
+
+The **static** adapter pre-allocates all storage files at init and registers
+them with Nixl as a single prepped descriptor list. The **dynamic** adapter
+opens/registers files per operation, enabling persist/recover of cached KV
+metadata across restarts and avoiding OS open-file-descriptor limits.
+
+---
+
+## Static Adapter: `NixlStoreL2Adapter`
+
+### Key Components
+
+#### `NixlStoreObj`
+Metadata record for a single cached object in Nixl storage:
+- `page_indices` — list of pre-allocated storage slot indices holding the data.
+- `size` — byte size of the stored object.
+- `layout` — optional `MemoryLayoutDesc` (shapes/dtypes) for reconstruction.
+- `pin_count` — reference count preventing eviction while a load is in flight.
+
+#### `NixlObjPool`
+Thread-safe integer index pool representing the fixed set of pre-allocated
+storage slots (`pool_size` entries). Slots are allocated before a store and
+freed after a failed transfer or when the object is evicted.
+
+#### `NixlStorageAgent`
+Thin wrapper around the Nixl agent API. Responsibilities:
+- Register the L1 memory buffer with Nixl (`init_mem_handlers`).
+- Register storage slots (files or object keys) with Nixl
+  (`init_storage_handlers_file` / `init_storage_handlers_object`).
+- Produce pre-prepared transfer handles for batched DMA reads/writes
+  (`get_mem_to_storage_handle`, `get_storage_to_mem_handle`).
+- Drive transfers asynchronously (`post_non_blocking`).
+
+#### `NixlStoreL2Adapter`
+The public adapter implementing `L2AdapterInterface`. It owns:
+- A background asyncio event loop (in a dedicated daemon thread) that
+  executes all DMA coroutines.
+- Three Linux event-fds (store / lookup / load) used to signal completion
+  to the caller without polling.
+- A shared `dict[ObjectKey, NixlStoreObj]` as the in-memory index.
+- A single `threading.Lock` protecting all shared state.
+
+---
+
+## Operation Flow
+
+### Store
+```
+submit_store_task(keys, objects)
+  └─ schedules _execute_store_in_the_loop on the asyncio loop
+       ├─ for each key/object: allocate storage slots, collect page indices
+       ├─ issue single batched DMA write (mem → storage)
+       ├─ on success: record key→NixlStoreObj in _memory_objects
+       └─ on failure: free allocated slots; mark task failed
+  └─ signals store event-fd
+```
+
+### Lookup & Lock
+```
+submit_lookup_and_lock_task(keys)
+  └─ schedules _execute_lookup_in_the_loop (sync, via call_soon_threadsafe)
+       ├─ for each key present: set bitmap bit, increment pin_count
+       └─ records bitmap in _completed_lookup_tasks
+  └─ signals lookup event-fd
+
+submit_unlock(keys)
+  └─ schedules pin_count decrement for each key (fire-and-forget)
+```
+
+### Load
+```
+submit_load_task(keys, objects)
+  └─ schedules _execute_load_in_loop on the asyncio loop
+       ├─ for each found key: collect mem/storage page indices, set bitmap bit
+       ├─ issue single batched DMA read (storage → mem)
+       └─ records bitmap in _completed_load_tasks
+  └─ signals load event-fd
+```
+
+---
+
+## Threading Model
+
+| Thread | Role |
+|---|---|
+| Caller thread(s) | Call `submit_*` / `query_*`; never touch storage directly |
+| Event-loop thread | Executes all Nixl DMA coroutines; owns `_memory_objects` mutations |
+| Shared lock | Protects `_memory_objects`, task result dicts, and task-id counter |
+
+Lookup is synchronous (scheduled via `call_soon_threadsafe`); store and load
+are async coroutines (scheduled via `run_coroutine_threadsafe`).
+
+---
+
+## Memory Address → Page Index Mapping
+
+L1 memory is registered with Nixl as a single contiguous buffer split into
+fixed-size pages of `align_bytes`. A memory object at address `addr` of size
+`sz` maps to page indices:
+
+```
+[addr // align_bytes, addr // align_bytes + 1, ..., addr // align_bytes + sz // align_bytes - 1]
+```
+
+Both `addr` and `sz` must be multiples of `align_bytes`.
+
+---
+
+## Dynamic Adapter: `DynamicNixlStoreL2Adapter`
+
+**Source:** `l2_adapters/nixl_store_dynamic_l2_adapter.py`
+
+### Motivation
+
+The static adapter pre-allocates all storage files and registers them with
+Nixl at init time. This has two limitations:
+
+1. **OS file descriptor limits.** Each storage slot requires an open fd,
+   limiting pool size in practice.
+2. **No persist/recover.** Files are created with random UUIDs and the
+   in-memory index (`_memory_objects`) is lost on shutdown.
+
+The dynamic adapter solves both by opening/registering files per operation
+and using deterministic file names derived from `ObjectKey`.
+
+### Key Differences from Static
+
+| Aspect | Static | Dynamic |
+|---|---|---|
+| File lifecycle | All opened at init, closed at shutdown | Opened per store/load, closed after each transfer |
+| File naming | Random UUID (`obj_{i}_{uuid}.bin`) | Deterministic from ObjectKey (`{model}_{rank}_{hash}.bin`) |
+| Nixl registration | Single prepped dlist for all storage | Per-operation register → transfer → deregister |
+| Pool / page indices | `NixlObjPool` manages fixed slots | No pool; `NixlStoreObj.page_indices` unused (`[]`) |
+| Capacity control | Pool size (slot count) | `max_capacity_gb` (byte-based) |
+| Persist/recover | Not supported | Supported |
+| Batching | One DMA transfer per batch of keys | One DMA transfer per key (each key = separate file) |
+
+### Key Components
+
+#### `DynamicNixlStorageAgent`
+
+Similar to `NixlStorageAgent` but only registers L1 memory at init. Storage
+file registration is per-operation:
+
+- `dynamic_store_file(mem_indices, file_path, page_size)` — create file,
+  register with Nixl, DMA write, deregister, close fd.
+- `dynamic_load_file(mem_indices, file_path, page_size)` — open existing
+  file, register, DMA read, deregister, close fd.
+- `dynamic_delete_file(file_path)` — `os.unlink()`.
+
+#### `DynamicNixlStoreL2Adapter`
+
+Same `L2AdapterInterface` contract as the static adapter. Differences:
+
+- **Store:** Iterates per key, calling `dynamic_store_file` for each.
+  Checks `_total_bytes + obj_size > _max_capacity_bytes` before each write;
+  stops the batch if capacity is exceeded.
+- **Delete:** Removes the file from disk via `dynamic_delete_file` in
+  addition to removing the key from `_memory_objects`.
+- **Capacity:** Tracks `_total_bytes` (incremented on store and on
+  secondary lookup, decremented on delete). `get_usage()` returns
+  `_total_bytes / _max_capacity_bytes` for the eviction controller.
+- **Close:** Stops the event loop first (waits for in-flight tasks);
+  when `persist_enabled`, data files are kept on disk, otherwise all
+  data files are deleted.
+- **Lookup:** A lookup miss always falls through to a synchronous
+  secondary lookup on disk; see the Persist / Secondary Lookup section
+  below.
+
+### Operation Flow
+
+#### Store
+```
+submit_store_task(keys, objects)
+  └─ schedules _execute_store_in_the_loop on the asyncio loop
+       ├─ for each key/object:
+       │    ├─ check capacity (skip remaining if exceeded)
+       │    ├─ compute deterministic file path from ObjectKey
+       │    ├─ open file, register with Nixl, DMA write, deregister, close
+       │    └─ record key→NixlStoreObj in _memory_objects, update _total_bytes
+       └─ signals store event-fd
+```
+
+#### Load
+```
+submit_load_task(keys, objects)
+  └─ schedules _execute_load_in_loop on the asyncio loop
+       ├─ for each found key:
+       │    ├─ compute file path from ObjectKey
+       │    └─ open file, register with Nixl, DMA read, deregister, close
+       └─ signals load event-fd
+```
+
+Lookup and unlock are identical to the static adapter (in-memory index
+lookup + pin count management).
+
+---
+
+## Persist / Secondary Lookup
+
+### Config
+
+`PersistConfig` (`l2_adapters/config.py`) has one boolean flag:
+
+| Field | Default | Purpose |
+|---|---|---|
+| `persist_enabled` | `True` | If True, data files are kept on disk at shutdown. |
+
+Parsed from the adapter JSON config key `"persist_enabled"` by
+`L2AdapterConfigBase._parse_persist_config()`.
+
+Lookup always checks secondary storage (disk) on miss — this is not
+configurable.
+
+Only the dynamic adapter (`nixl_store_dynamic`) uses persist; the
+static adapter ignores it.
+
+### How it works
+
+There is no dedicated `persist()` or `recover()` method on the
+`L2AdapterInterface`. Persist and recover are implemented implicitly
+through two existing hooks:
+
+#### Persist (file retention at shutdown)
+
+In `close()`, after the event loop has stopped:
+
+- If `persist_enabled`, data files are left on disk untouched.
+- Otherwise, every file in `_memory_objects` is `os.unlink`'d to avoid
+  orphaned storage.
+
+No metadata JSON is written — the deterministic `ObjectKey → filename`
+mapping is sufficient to rediscover each file on restart.
+
+#### Secondary Lookup (lazy disk recovery)
+
+`_execute_lookup_in_the_loop` always extends the in-memory index lookup
+with a secondary lookup on miss:
+
+1. Compute deterministic file path from the ObjectKey.
+2. `os.stat(file_path)` — if the file exists, treat as a hit.
+3. Populate `_memory_objects[key]` lazily with `size` from the stat
+   result and `layout=None`.
+4. Update `_total_bytes`; enforce capacity (skip if it would exceed).
+
+The `NixlStoreObj.layout` field is left as `None` on secondary lookup. Layout
+information is only needed at load time, where the caller supplies it
+via the provided `MemoryObj`'s shape/dtype/phy_size.
+
+---
+
+## Configuration
+
+### Static Adapter (`nixl_store`)
+
+```json
+{
+  "type": "nixl_store",
+  "backend": "POSIX",
+  "backend_params": {
+    "file_path": "/path/to/storage",
+    "use_direct_io": "false"
+  },
+  "pool_size": 100
+}
+```
+
+### Dynamic Adapter (`nixl_store_dynamic`)
+
+```json
+{
+  "type": "nixl_store_dynamic",
+  "backend": "POSIX",
+  "backend_params": {
+    "file_path": "/path/to/storage",
+    "use_direct_io": "false",
+    "max_capacity_gb": "10"
+  },
+  "persist_enabled": true
+}
+```
+
+---
\ No newline at end of file
diff --git a/docs/design/v1/distributed/l2_adapters/overall.md b/docs/design/v1/distributed/l2_adapters/overall.md
new file mode 100644
index 0000000..7710bb9
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/overall.md
@@ -0,0 +1,599 @@
+# L2 Store and Prefetch Controller Design
+
+This document describes how the StoreController and PrefetchController interact
+with L2 adapters, the invariants they maintain, and the assumptions they rely on.
+It is intended for developers implementing new L2 adapters or modifying the
+controller logic.
+
+## Architecture Overview
+
+```
+                    ┌────────────────────────┐
+                    │    StorageManager       │
+                    │  submit_prefetch_task   │
+                    │  query_prefetch_status  │
+                    │  reserve/finish_write   │
+                    └────┬──────────┬─────────┘
+                         │          │
+              ┌──────────┘          └──────────┐
+              ▼                                ▼
+   ┌────────────────────┐           ┌────────────────────┐
+   │  StoreController   │           │ PrefetchController  │
+   │  (background thread)│          │  (background thread) │
+   │                    │           │                     │
+   │  L1 write done     │           │  external submit    │
+   │   → store to L2    │           │   → lookup L2       │
+   │   → release locks  │           │   → plan + load     │
+   └────┬───────────────┘           │   → read-lock L1    │
+        │                           └──────┬──────────────┘
+        │                                  │
+        ▼                                  ▼
+   ┌─────────────────────────────────────────────┐
+   │           L2AdapterInterface(s)             │
+   │   store / lookup_and_lock / load / unlock   │
+   │                                             │
+   │  Each adapter has 3 distinct event fds:     │
+   │   store_efd, lookup_efd, load_efd           │
+   └─────────────────────────────────────────────┘
+```
+
+Both controllers run a single background thread each, using `select.poll()`
+on eventfds for event-driven I/O. They share the same set of L2 adapter
+instances (thread-safe by contract) but use different eventfds.
+
+## L2 Adapter Interface
+
+`L2AdapterInterface` (`l2_adapters/base.py`) provides the non-blocking I/O
+primitives that both controllers call. All operations follow a
+**submit → poll eventfd → query result** pattern.
+
+### Event Fds
+
+Each adapter exposes **three distinct** eventfds:
+
+| Method                         | Used by            | Signaled when                |
+|--------------------------------|--------------------|------------------------------|
+| `get_store_event_fd()`         | StoreController    | A store task completes       |
+| `get_lookup_and_lock_event_fd()` | PrefetchController | A lookup task completes    |
+| `get_load_event_fd()`          | PrefetchController | A load task completes        |
+
+**Critical invariant:** All event fds across all adapters must be globally
+unique. The controllers build `fd → adapter_index` maps; duplicate fds would
+silently misroute events.
+
+### Store Operations
+
+```
+submit_store_task(keys, objects) -> L2TaskId
+pop_completed_store_tasks() -> dict[L2TaskId, L2StoreResult]
+```
+
+- **Caller provides buffers:** The `objects` list contains `MemoryObj` references
+  managed by the caller (StoreController holds L1 read locks on them).
+- **Coarse-grained errors:** A store task either fully succeeds or fully fails.
+  The completion dict maps each task id to an `L2StoreResult`
+  (`lmcache.v1.distributed.internal_api.L2StoreResult`) that encodes both
+  the success flag and the bytes actually transferred. Use
+  `result.is_successful()` to check the outcome and
+  `result.bytes_transferred()` to read the real byte count written to L2
+  (always `0` on failure). Adapters that fast-path duplicate keys (e.g.
+  skip the write when the key already exists in the backend) should
+  report the real, non-skipped byte count here so the L2 throughput
+  histogram reflects actual work — not submitted-but-skipped bytes.
+- **Pop semantics:** `pop_completed_store_tasks()` drains all completed tasks.
+  Each task appears exactly once.
+
+### Lookup and Lock Operations
+
+```
+submit_lookup_and_lock_task(keys) -> L2TaskId
+query_lookup_and_lock_result(task_id) -> Bitmap | None
+submit_unlock(keys) -> None
+```
+
+- **Locking:** `lookup_and_lock` atomically checks which keys exist and acquires
+  L2-side locks on found keys. This prevents L2 eviction between lookup and load.
+- **Fine-grained results:** Returns a `Bitmap` where bit `i` is set if `keys[i]`
+  was found and locked.
+- **One-shot query:** `query_lookup_and_lock_result` returns `None` while pending,
+  then the `Bitmap` exactly once. Subsequent calls return `None`.
+- **Unlock contract:** `submit_unlock` is fire-and-forget. The adapter **must**
+  guarantee eventual success (retry internally if needed). The caller will never
+  retry.
+
+### Load Operations
+
+```
+submit_load_task(keys, objects) -> L2TaskId
+query_load_result(task_id) -> Bitmap | None
+```
+
+- **Caller provides buffers:** The `objects` list contains pre-allocated L1 write
+  buffers. The adapter writes loaded data directly into these buffers.
+- **Fine-grained results:** Returns a `Bitmap` where bit `i` is set if `keys[i]`
+  was successfully loaded.
+- **One-shot query:** Same semantics as lookup — returns the Bitmap exactly once.
+
+### Thread Safety
+
+The adapter must be safe for concurrent calls from the StoreController thread
+and the PrefetchController thread. In practice, the store operations and
+lookup/load operations use separate internal state, so this is usually
+straightforward with per-operation locks or lock-free queues.
+
+### Task ID Scope
+
+`L2TaskId` values are only unique **within a single adapter**. When tracking
+tasks across multiple adapters, use the composite key `(adapter_index, task_id)`.
+
+## StoreController
+
+**Purpose:** Asynchronously replicate L1 data to L2 after writes complete.
+
+**Source:** `storage_controllers/store_controller.py`
+
+### Lifecycle
+
+```
+StorageManager.__init__
+  → StoreController(l1_manager, l2_adapters, descriptors, policy)
+  → controller.start()        # spawns background thread
+  ...
+StorageManager.close()
+  → controller.stop()         # joins thread, releases locks
+```
+
+### Event-Driven Loop
+
+The StoreController's background thread polls on:
+
+1. **StoreListener eventfd** — fired by L1Manager when `finish_write()` completes.
+   The listener is an `L1ManagerListener` registered with L1Manager.
+2. **Per-adapter store eventfds** — fired when L2 store tasks complete.
+
+### Data Flow
+
+```
+L1 finish_write()
+  │
+  ▼ (L1Manager listener callback, inside L1 lock — must be non-blocking)
+StoreListener.on_l1_keys_write_finished(keys)
+  │  appends keys + signals eventfd
+  ▼
+_store_loop: poll wakes up
+  │
+  ▼
+_process_new_keys(keys)
+  │
+  ├─ 1. Group keys by shape (today: (model_name, kv_rank); L1 is a shared
+  │     pool so one drain may span models/parallelism configs with different
+  │     KV shapes, and each submit_store_task must see uniform (shape, dtype)).
+  │
+  ├─ 2. For each per-shape group:
+  │     StorePolicy.select_store_targets(group_keys, adapters)
+  │       → dict[adapter_index, list[ObjectKey]]
+  │
+  ├─ 3. For each adapter target:
+  │     L1Manager.reserve_read(target_keys)  → get MemoryObj + read lock
+  │     adapter.submit_store_task(keys, objs)
+  │     Track as InFlightStoreTask
+  │
+  ▼ (later, for each adapter whose store_efd signaled)
+_drain_l2_store_completions(signaled_adapters)
+  │  adapter.pop_completed_store_tasks() → deposit L2StoreResult
+  │  (success flag + bytes_transferred) on each InFlightStoreTask
+  │
+  ▼
+_advance_request(task_key, task)  [state transition]
+  │  skip if l2_store_result still None
+  │
+  ▼
+_finalize_store(task_key, task)  [terminal execution]
+  │
+  ├─ 4. L1Manager.finish_read(read_locked_keys)  → release read locks
+  │
+  ├─ 5. If success: StorePolicy.select_l1_deletions(keys) → delete from L1
+  │     If failure: log warning (best-effort, no retry)
+  │
+  ▼
+Done. Keys remain in L1 unless the policy deletes them.
+```
+
+### Lock Invariants
+
+| Phase             | L1 Lock State | L2 Lock State |
+|-------------------|---------------|---------------|
+| Before store      | Unlocked      | N/A           |
+| During store      | Read-locked   | N/A           |
+| After store       | Unlocked      | N/A           |
+
+- **Read locks during store** prevent eviction from removing L1 data while the
+  adapter is reading it.
+- **Always released:** `stop()` calls `_cleanup_in_flight_tasks()` which releases
+  all in-flight read locks, even if tasks haven't completed.
+
+### StorePolicy
+
+The policy decides two things:
+
+1. **`select_store_targets(keys, adapters) → dict[int, list[ObjectKey]]`**
+   Which adapters get which keys. A key can go to multiple adapters.
+   `DefaultStorePolicy`: all keys → all adapters.
+
+2. **`select_l1_deletions(keys) → list[ObjectKey]`**
+   Which keys to evict from L1 after successful L2 store.
+   `DefaultStorePolicy`: never delete (empty list).
+
+Policies are selected by name via `--l2-store-policy` (default: `"default"`).
+New policies self-register with `register_store_policy(name, cls)` at import
+time and are auto-discovered by `storage_controllers/__init__.py`.
+
+## PrefetchController
+
+**Purpose:** Asynchronously load KV cache data from L2 into L1 ahead of a
+serving request. Called by `StorageManager.submit_prefetch_task()` for keys
+not already in L1.
+
+**Source:** `storage_controllers/prefetch_controller.py`
+
+### Lifecycle
+
+```
+StorageManager.__init__
+  → PrefetchController(l1_manager, l2_adapters, descriptors, policy)
+  → controller.start()        # spawns background thread
+  ...
+StorageManager.close()
+  → controller.stop()         # joins thread, releases all locks
+```
+
+### External API (Thread-Safe)
+
+```python
+# Called from the serving thread
+request_id = controller.submit_prefetch_request(keys, layout_desc)
+
+# Polled by the serving thread
+result = controller.query_prefetch_result(request_id)  # int | None
+```
+
+- `submit_prefetch_request` enqueues the request and signals the background thread
+  via an eventfd. Returns immediately.
+- `query_prefetch_result` returns `None` while in-progress, then the **prefix hit
+  count** exactly once (pop semantics).
+
+### Prefix-Only Loading
+
+**Key invariant:** Only the **contiguous prefix** of found keys is loaded.
+
+If L2 has keys `{0, 1, 3, 4}` but not key `2`, only keys `{0, 1}` are loaded.
+The gap at index 2 means the vLLM engine cannot use keys 3 and 4 (it needs a
+contiguous prefix of computed KV cache). Loading them would waste I/O bandwidth
+and L1 memory.
+
+This is enforced by `trim_load_plan_to_prefix()` after the policy computes the
+raw load plan.
+
+### Event-Driven Loop
+
+The PrefetchController's background thread polls on:
+
+1. **Submission eventfd** — signaled by `submit_prefetch_request()`.
+2. **Per-adapter lookup eventfds** — signaled when lookup tasks complete.
+3. **Per-adapter load eventfds** — signaled when load tasks complete.
+
+### Request State Machine
+
+Each request goes through two phases:
+
+```
+LOOKUP ──────────────────────────► PLAN_AND_LOAD ──────────► COMPLETED
+  │                                    │
+  │ submit lookup_and_lock             │ compute load plan
+  │ to ALL adapters                    │ reserve L1 write buffers
+  │                                    │ submit load tasks
+  │ wait for all lookups               │ wait for all loads
+  │ to complete                        │ finalize
+  ▼                                    ▼
+```
+
+### Data Flow
+
+```
+submit_prefetch_request(keys, layout_desc)
+  │
+  ▼ (cross-thread: submission queue + eventfd signal)
+_drain_submission_queue → _pending_queue
+  │
+  ▼ (if below max_in_flight)
+_start_lookup_phase(request_id, keys, layout_desc)
+  │
+  ├─ Submit lookup_and_lock_task(keys) to EVERY adapter
+  │
+  ▼ (wait for all adapter lookups to complete)
+_advance_request(request, signaled_adapters)  [LOOKUP branch]
+  │  _poll_lookup_results(request, signaled_adapters[LOOKUP])
+  │  when all_lookups_done():
+  │
+  ▼
+_transition_to_load_phase(request)
+  │
+  ├─ 1. PrefetchPolicy.select_load_plan(keys, lookup_results, adapters)
+  │     → dict[adapter_index, Bitmap]
+  │
+  ├─ 2. trim_load_plan_to_prefix()
+  │     → only keep contiguous prefix keys
+  │
+  ├─ 3. L1Manager.reserve_write(keys, is_temporary=True, mode="new")
+  │     → allocate L1 write buffers
+  │
+  ├─ 4. Re-trim plan to only successfully reserved keys
+  │
+  ├─ 5. Phase 1 unlock: unlock L2 keys locked in lookup but NOT in load plan
+  │
+  ├─ 6. Submit load_task(keys, objs) per adapter
+  │
+  ▼ (wait for all adapter loads to complete)
+_advance_request(request, signaled_adapters)  [PLAN_AND_LOAD branch]
+  │  _poll_load_results(request, signaled_adapters[PLAN_AND_LOAD])
+  │  when all_loads_done():
+  │
+  ▼
+_finalize_load(request)
+  │
+  ├─ 7. Phase 2 unlock: unlock all L2 keys in the load plan
+  │
+  ├─ 8. L1Manager.finish_write_and_reserve_read(loaded_keys)
+  │     → atomically: write unlock + read lock
+  │
+  ├─ 9. L1Manager.finish_write(failed_keys) + delete(failed_keys)
+  │     → clean up partial failures
+  │
+  ├─ 10. Release read locks for loaded keys beyond the prefix
+  │      (partial load failures can create gaps)
+  │
+  ▼
+_complete_request(request_id, prefix_hits)
+  │  store result, remove from in-flight tracking
+```
+
+### Lock Invariants
+
+| Phase             | L1 Lock State                    | L2 Lock State               |
+|-------------------|----------------------------------|-----------------------------|
+| Lookup            | None                             | Found keys are locked       |
+| After plan        | Write-locked (reserved buffers)  | Plan keys locked; others unlocked (phase 1) |
+| During load       | Write-locked                     | Plan keys locked            |
+| After load        | **Read-locked** (prefix keys)    | All unlocked (phase 2)      |
+| After finalize    | Read-locked (prefix only)        | All unlocked                |
+
+- **L1 write buffers are temporary:** `is_temporary=True` allows the eviction
+  controller to reclaim them if needed, although normally they are short-lived.
+- **Atomic write→read transition:** `finish_write_and_reserve_read()` ensures no
+  eviction window between write completion and read lock acquisition.
+- **Post-finalize read locks:** The prefix keys remain read-locked in L1 so the
+  serving engine can consume them. The caller (`StorageManager`) releases these
+  via `finish_read_prefetched()` after use.
+
+### L2 Lock Management
+
+L2 locks prevent adapter-side eviction between lookup and load. They must be
+released in all cases — success, failure, and shutdown.
+
+**Phase 1 unlock** (`_unlock_unneeded_keys`): After the load plan is computed,
+keys that were locked during lookup but are NOT in the final load plan are
+unlocked immediately. This happens when:
+- The policy assigned a key to a different adapter.
+- The key was trimmed by prefix trimming.
+- L1 write reservation failed.
+
+**Phase 2 unlock** (`_unlock_all_plan_keys`): After load completes (regardless
+of success or failure), all keys in the load plan are unlocked.
+
+**Shutdown cleanup** (`_cleanup_in_flight_requests`): Releases all held L1 and
+L2 locks for any in-flight requests.
+
+### PrefetchPolicy
+
+```python
+select_load_plan(keys, lookup_results, adapters) → dict[int, Bitmap]
+```
+
+Receives lookup bitmaps from all adapters and produces a non-overlapping
+assignment of keys to adapters. Each key appears in at most one adapter's bitmap.
+
+`DefaultPrefetchPolicy`: For each key, assign it to the first (lowest-indexed)
+adapter that has it. This is a simple greedy approach.
+
+Policies are selected by name via `--l2-prefetch-policy` (default: `"default"`).
+New policies self-register with `register_prefetch_policy(name, cls)` at import
+time and are auto-discovered by `storage_controllers/__init__.py`.
+
+### Max In-Flight Limiting
+
+The controller limits concurrent prefetch requests to `max_in_flight` (default: 8).
+Requests beyond this limit are queued in `_pending_queue` and dequeued as
+in-flight requests complete.
+
+Note: This is a simple count-based limit. A future improvement would use a
+dynamic admission controller based on L1 memory usage of in-flight requests.
+
+## Integration: StorageManager
+
+`StorageManager` (`storage_manager.py`) is the top-level entry point that wires
+everything together.
+
+### Prefetch Flow (from the serving engine's perspective)
+
+```python
+# 1. Submit: check L1 first, then delegate remainder to L2
+handle = sm.submit_prefetch_task(keys, layout_desc)
+
+# 2. Poll: busy-wait for completion
+while True:
+    found_count = sm.query_prefetch_status(handle)
+    if found_count is not None:
+        break
+
+# 3. Read: access the prefetched data (holds read locks)
+with sm.read_prefetched_results(keys[:found_count]) as objs:
+    # use objs ...
+    pass
+
+# 4. Release: drop read locks
+sm.finish_read_prefetched(keys[:found_count])
+```
+
+### PrefetchHandle
+
+```python
+@dataclass(frozen=True)
+class PrefetchHandle:
+    request_id: int          # -1 if no L2 request needed
+    l1_prefix_hit_count: int # leading keys already in L1
+    total_requested_keys: int
+    submit_time: float       # for latency logging
+```
+
+`submit_prefetch_task` first checks L1 for a contiguous prefix of hits:
+- If all keys hit L1: returns handle with `request_id=-1` (no L2 work).
+- If some keys miss: submits the **remaining** keys to PrefetchController.
+
+`query_prefetch_status` combines L1 hits with L2 results:
+`total_hits = l1_prefix_hit_count + l2_prefix_hits`.
+
+## Assumptions and Invariants Summary
+
+1. **All eventfds are globally unique** across all adapters and all operation
+   types. Violating this corrupts the poll-based dispatch.
+
+2. **L2 task IDs are per-adapter, not global.** Use `(adapter_index, task_id)`
+   as composite keys.
+
+3. **Query results are one-shot.** Both `query_lookup_and_lock_result()` and
+   `query_load_result()` return a non-None value exactly once per task.
+
+4. **`submit_unlock` must eventually succeed.** The controllers will never
+   retry. The adapter must handle retries internally.
+
+5. **Prefix-only loading.** Only the contiguous prefix of found keys is loaded
+   from L2. Gaps break the prefix.
+
+6. **Listener callbacks run inside L1Manager's lock.** `StoreListener` must be
+   non-blocking (append + eventfd signal only). It must never call L1Manager
+   methods (deadlock).
+
+7. **L1 write buffers for prefetch are temporary.** Allocated with
+   `is_temporary=True` to allow eviction if needed.
+
+8. **Atomic write→read transition.** `finish_write_and_reserve_read()` prevents
+   eviction between completing a prefetch write and acquiring the read lock
+   for the serving engine.
+
+9. **Both controllers release all locks on shutdown.** `stop()` always cleans
+   up in-flight tasks, regardless of completion state.
+
+10. **L2 adapters are thread-safe.** Concurrent calls from the StoreController
+    thread and PrefetchController thread are expected.
+
+## Implementing a New L2 Adapter
+
+### Pure-Python Adapters
+
+Implement `L2AdapterInterface` directly. See `mock_l2_adapter.py` for a
+reference implementation for an in-memory adapter, or
+[`raw_block.md`](raw_block.md) for a durable local-device adapter.
+**No existing files need to be modified.** Create a new module
+(e.g., `my_l2_adapter.py`) in the `l2_adapters/` package and self-register at
+module level:
+
+```python
+# At the bottom of your module:
+register_l2_adapter_type("my_type", MyL2AdapterConfig)
+register_l2_adapter_factory("my_type", _create_my_l2_adapter)
+```
+
+The `__init__.py` uses `pkgutil.iter_modules()` to discover all
+`*_l2_adapter.py` modules automatically, but imports them **lazily** — a
+module (and its third-party dependencies) is only loaded when the
+corresponding adapter type is actually requested at runtime.
+
+### Persist / Recover (Optional)
+
+Adapters that support persisting cached data across restarts use
+`PersistConfig` (parsed from the JSON key `"persist_enabled"`, defaulting
+to ``True``). Lookup always checks secondary storage on miss. There is
+no dedicated interface method — adapters integrate persist into their
+existing `close()` (to keep data on disk) path. See
+`nixl_store_dynamic_l2_adapter.py` for a reference implementation and
+[`nixl_store.md`](nixl_store.md) for design details.
+
+### Native (C++/Rust) Storage Backends
+
+For high-performance backends written in C++ or Rust, use the shared native
+connector framework. A single C++ connector implementation works in **both**
+non-MP mode (via `ConnectorClientBase`) and MP mode (via
+`NativeConnectorL2Adapter`).
+
+**Full guide:** [`csrc/storage_backends/README.md`](../../../../../csrc/storage_backends/README.md)
+
+The `NativeConnectorL2Adapter` (`native_connector_l2_adapter.py`) bridges any
+pybind-wrapped `IStorageConnector` to the `L2AdapterInterface`:
+
+- Creates 3 Python eventfds from the connector's single eventfd
+- Runs a background demux thread that routes completions by operation type
+- Handles `ObjectKey` serialization and `MemoryObj` buffer extraction
+- Implements client-side locking (refcount dict) for remote backends
+
+**Reference implementation:** The Redis (RESP) connector in
+`csrc/storage_backends/redis/` demonstrates all 5 steps of the integration
+guide.
+
+## Implementing a New Store or Prefetch Policy
+
+Both store and prefetch policies use a name-based registry with automatic
+module discovery. **To add a new policy, create a single file in
+`storage_controllers/` — no changes to any existing file are needed.**
+
+### Store Policy
+
+1. Create a new file (e.g., `storage_controllers/store_policy_tiered.py`).
+2. Subclass `StorePolicy` and implement `select_store_targets()` and
+   `select_l1_deletions()`.
+3. Call `register_store_policy("tiered", TieredStorePolicy)` at module level.
+
+```python
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    StorePolicy,
+    AdapterDescriptor,
+    register_store_policy,
+)
+from lmcache.v1.distributed.api import ObjectKey
+
+
+class TieredStorePolicy(StorePolicy):
+    def select_store_targets(self, keys, adapters):
+        # custom logic ...
+        ...
+
+    def select_l1_deletions(self, keys):
+        return []
+
+
+register_store_policy("tiered", TieredStorePolicy)
+```
+
+The policy is now available via `--l2-store-policy tiered`.
+
+### Prefetch Policy
+
+Same pattern: subclass `PrefetchPolicy`, implement `select_load_plan()`,
+and call `register_prefetch_policy("name", cls)`.
+
+### How Discovery Works
+
+`storage_controllers/__init__.py` uses `pkgutil.iter_modules()` to import
+every module in the package at import time. When your module is imported,
+the `register_*_policy()` call at module level adds it to the registry.
+The `--l2-store-policy` and `--l2-prefetch-policy` CLI arguments use the
+registry to populate their `choices` list.
diff --git a/docs/design/v1/distributed/l2_adapters/p2p_l2_adapter.md b/docs/design/v1/distributed/l2_adapters/p2p_l2_adapter.md
new file mode 100644
index 0000000..3fe7cc5
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/p2p_l2_adapter.md
@@ -0,0 +1,108 @@
+# P2P L2 Adapter
+
+`lmcache/v1/distributed/l2_adapters/p2p_l2_adapter.py`
+
+An L2 adapter that treats a **single peer cache server** as a read-only L2
+tier. Instead of a storage backend, it looks up objects that are resident in
+the peer's L1 (CPU RAM) and pulls them directly over the transfer channel
+(RDMA). One adapter instance is created per connected peer; the peer discovery
+and the dynamic add/remove that wire these into the storage manager are owned
+by separate PRs (the P2P controller and the runtime `add_l2_adapter`
+interface).
+
+See the Confluence design *LMCache MP P2P design → P2P L2 adapter design* for
+the full system context.
+
+## What it talks to
+
+| Dependency | Used for |
+|---|---|
+| `MessageQueueClient` → peer's P2P controller | lookup-and-lock, unlock RPCs |
+| `TransferChannelContext` / `TransferChannelClient` | translating local L1 addresses + reading the peer's L1 |
+| `PeriodicEventNotifier` | pulsing the lookup / load event fds (see below) |
+
+## Lifecycle
+
+```
+lookup-and-lock  → query (addresses)  → load (RDMA read)  → unlock
+```
+
+1. **lookup-and-lock** — send `P2P_LOOKUP_AND_LOCK([keys, layout_desc])` to the
+   peer; it read-locks the cached prefix in its L1 and returns a task id.
+2. **query** — poll `P2P_QUERY_LOOKUP_RESULTS(task_id)`; once ready the peer
+   returns one `TransferChannelAddress` per key (invalid offset for keys it did
+   not lock). The adapter stashes the valid addresses keyed by `ObjectKey` and
+   reports a found/not-found `Bitmap` to the prefetch controller.
+3. **load** — for the found keys, translate the local destination objects'
+   `(shm_offset, shm_byte_length)` into transfer-channel addresses, pair them
+   with the stashed remote addresses, and issue `submit_read`. `query_load_result`
+   maps the read's `succeeded_mask` to a `Bitmap`.
+4. **unlock** — `P2P_UNLOCK_OBJECTS([keys])` releases the peer's read locks and
+   drops the stashed addresses. Fire-and-forget: the result future is not awaited.
+
+`layout_desc` is the advisory hint added to the L2 lookup interface; the P2P
+adapter forwards the real descriptor verbatim so the peer can size objects.
+
+## Why the periodic notifier
+
+Neither the lookup RPC nor the transfer-channel read exposes a completion fd:
+the MQ response resolves on the shared client polling thread, and the RDMA read
+completes asynchronously inside the transfer engine. So the adapter registers
+its lookup and load event fds with the `PeriodicEventNotifier` singleton, which
+pulses them every few milliseconds. Each pulse drives the prefetch controller
+to re-poll `query_lookup_and_lock_result` / `query_load_result`, which in turn
+check the in-flight RPC / transfer state. The store fd is not pulsed by the
+notifier; it is signaled directly on submit (see *No store* below).
+
+Both RPCs are non-blocking handlers, so the adapter uses **submit-then-wait**:
+`submit_lookup_and_lock_task` submits the lookup and waits (hard-coded ~3 s) for
+the task id; each `query_lookup_and_lock_result` pulse submits
+`P2P_QUERY_LOOKUP_RESULTS` and waits — `None` means not ready (re-queried on the
+next pulse), addresses mean ready.
+
+## Timeouts
+
+P2P is error-prone, so both queries are bounded by a per-task deadline
+(`lookup_timeout_s` / `load_timeout_s`). A lookup past its deadline returns an
+all-zero `Bitmap` (treated as a miss); a load past its deadline returns an
+all-zero `Bitmap` (treated as a failure). The prefetch controller then trims
+those keys as if the peer never had them.
+
+## No store / no eviction
+
+Writing to a peer's L1 is intentionally unsupported (it would require remote
+allocation and existence/status checks that can corrupt both nodes on failure).
+But the store controller still tracks every task it submits — and the L1 read
+locks it reserved for that task — until the result is popped. So rather than
+drop store tasks, `submit_store_task` records a 0-byte success and signals the
+store fd immediately, and `pop_completed_store_tasks` returns it; the controller
+then finalizes its bookkeeping and releases the read locks instead of leaking
+them. No data is moved and no bytes are accounted.
+
+The adapter is constructed with `max_capacity_bytes=0`, so
+`supports_global_eviction` is `False`, `delete` is the inherited no-op, and
+`get_usage` reports the (empty) base counters.
+
+## Configuration
+
+The adapter is built through the standard factory (`create_l2_adapter`), so the
+storage manager owns its lifecycle. The config carries the peer's two URLs:
+
+```json
+{
+  "type": "p2p",
+  "peer_mq_server_url": "tcp://peer-host:5555",
+  "peer_transfer_channel_server_url": "peer-host:7600",
+  "lookup_timeout_s": 10.0,
+  "load_timeout_s": 10.0
+}
+```
+
+## close()
+
+Sets a closed flag (later submits are inert), unregisters the lookup/load fds
+from the periodic notifier, removes the transfer-channel client from the
+`TransferChannelContext` via `remove_transfer_channel_client(peer_url)` (which
+closes it and releases its transport handles), closes the MQ client, and closes
+the three event notifiers. `close()` is idempotent: the closed flag guards
+against a second teardown of these shared resources.
diff --git a/docs/design/v1/distributed/l2_adapters/plugin.md b/docs/design/v1/distributed/l2_adapters/plugin.md
new file mode 100644
index 0000000..2373556
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/plugin.md
@@ -0,0 +1,359 @@
+# Plugin L2 Adapter Design
+
+## Overview
+
+The **Plugin L2 Adapter** framework allows third-party developers to extend
+LMCache with custom L2 storage backends **without modifying any LMCache source
+code**. A plugin is simply a Python module that implements `L2AdapterInterface`
+and is loaded at runtime via the `PluginL2AdapterConfig` mechanism.
+
+This is the recommended way to integrate external storage systems (e.g.
+NitroFS, custom distributed caches) into LMCache's MP-mode L2 pipeline.
+
+---
+
+## Key Components
+
+### `PluginL2AdapterConfig`
+
+Config class registered under the type name `"plugin"`. Fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `module_path` | `str` | yes | Dotted Python import path of the module containing the adapter class. |
+| `class_name` | `str` | yes | Name of the class inside `module_path` that implements `L2AdapterInterface`. |
+| `adapter_params` | `dict` | no | Arbitrary keyword arguments forwarded to the adapter class constructor. |
+
+Defined in `plugin_l2_adapter.py` and self-registered at import time via:
+```python
+register_l2_adapter_type("plugin", PluginL2AdapterConfig)
+register_l2_adapter_factory("plugin", _create_plugin_adapter)
+```
+
+### `_create_plugin_adapter`
+
+Factory function that:
+1. Calls `importlib.import_module(config.module_path)` to load the user module.
+2. Retrieves `config.class_name` from the module via `getattr`.
+3. Validates it is a subclass of `L2AdapterInterface`.
+4. Resolves a config class via `_resolve_config_class` (see below).
+5. If a config class is found, builds a config instance via `from_dict()`
+   and passes it to the adapter constructor (built-in convention).
+   Otherwise falls back to passing the raw `adapter_params` dict.
+
+### Config Class Auto-Discovery (`_resolve_config_class`)
+
+The factory automatically resolves the adapter's config class using
+the following priority chain (first match wins):
+
+| Priority | Strategy | Example |
+|---|---|---|
+| 1 | Explicit `config_class_name` field in JSON config | `"config_class_name": "MyConfig"` |
+| 2 | Convention: adapter class name + `"Config"` suffix | `MyL2Adapter` → looks for `MyL2AdapterConfig` |
+| 3 | `config_class_name` attribute on the adapter class | `class MyAdapter: config_class_name = "MyConfig"` |
+| 4 | No config class found — pass raw `adapter_params` dict | legacy / simple plugins |
+
+Each candidate name is looked up in the loaded module and validated as
+an `L2AdapterConfigBase` subclass.  Non-existent or invalid names are
+silently skipped, moving to the next candidate.
+
+This means most plugins that follow the naming convention (e.g.
+`InMemoryL2Adapter` + `InMemoryL2AdapterConfig` in the same module)
+will **automatically** receive a typed config instance without any
+extra configuration.
+
+---
+
+## Loading Flow
+
+```
+CLI / config JSON
+  │
+  ▼
+parse_args_to_l2_adapters_config()
+  │  JSON: {"type": "plugin",
+  │         "module_path": "my_plugin",
+  │         "class_name": "MyL2Adapter",
+  │         "adapter_params": {...}}
+  │
+  ▼
+PluginL2AdapterConfig.from_dict(d)
+  │  validates module_path, class_name, adapter_params
+  │
+  ▼
+create_l2_adapter_from_registry(config, **kwargs)
+  │  looks up factory for "plugin"
+  │
+  ▼
+_create_plugin_adapter(config, ...)
+  │
+  ├─ importlib.import_module(config.module_path)
+  ├─ getattr(module, config.class_name)
+  ├─ issubclass check against L2AdapterInterface
+  │
+  ├─ _resolve_config_class(module, config, adapter_cls)
+  │   ├─ 1. config.config_class_name (explicit)
+  │   ├─ 2. class_name + "Config" (convention)
+  │   ├─ 3. adapter_cls.config_class_name (attribute)
+  │   └─ 4. None (fall back to raw dict)
+  │
+  ├─ [if config class found]
+  │   └─ adapter_cls(cfg_cls.from_dict(adapter_params))
+  │
+  └─ [otherwise]
+      └─ adapter_cls(adapter_params)
+          │
+          ▼
+  L2AdapterInterface instance (ready for use)
+```
+
+---
+
+
+## Plugin Contract
+
+A plugin adapter class **must**:
+
+1. **Subclass `L2AdapterInterface`** from `lmcache.v1.distributed.l2_adapters.base`.
+2. **Implement all abstract methods**: store, lookup & lock, load, close,
+   and all three event-fd getters.
+3. **Provide three distinct event fds** (store / lookup / load). The
+   controllers build `fd → adapter` maps; duplicates will misroute events.
+4. **Be thread-safe**: the `StoreController` and `PrefetchController`
+   call adapter methods from different threads concurrently.
+5. **Accept `**kwargs` in `__init__`** to stay forward-compatible with new
+   framework-level arguments.
+
+A plugin adapter class **should**:
+
+1. Create its own asyncio event loop and background thread if it needs
+   async I/O (the framework does **not** provide a loop to L2 adapters,
+   unlike the old Connector-based architecture).
+2. Use `create_event_notifier()` from `lmcache.v1.platform` for the
+   three event fds (cross-platform: `os.eventfd` on Linux,
+   `os.pipe` fallback elsewhere).
+3. Clean up all resources (event fds, threads, connections) in `close()`.
+
+---
+
+## Threading Model (Plugin Side)
+
+Since the framework does **not** provide an event loop to L2 adapters
+(unlike the old non-MP `ConnectorContext.loop`), plugins that need async
+I/O must manage their own:
+
+```
+Plugin.__init__()
+  ├─ self._loop = asyncio.new_event_loop()
+  └─ self._thread = Thread(target=run_loop, daemon=True)
+
+Caller threads (StoreController / PrefetchController)
+  │
+  ├─ submit_store_task()    → run_coroutine_threadsafe(...)
+  ├─ submit_lookup_task()   → call_soon_threadsafe(...)
+  └─ submit_load_task()     → run_coroutine_threadsafe(...)
+  │
+  ▼
+Plugin background thread (event loop)
+  │
+  ├─ Executes store/load coroutines
+  ├─ Writes to eventfd on completion
+  └─ Accesses shared state under lock
+```
+
+This pattern is identical to the one used by `MockL2Adapter` and
+`NixlStoreL2Adapter`.
+
+---
+
+
+## Example: Minimal Plugin
+
+### 1. Implement the Adapter
+
+```python
+# my_plugin/adapter.py
+import asyncio, threading
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface, L2TaskId,
+)
+from lmcache.v1.platform import create_event_notifier
+
+class MyL2Adapter(L2AdapterInterface):
+    def __init__(self, host="localhost", **_kw):
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+        # ... set up connection to `host`, background thread, etc.
+
+    # implement all abstract methods ...
+```
+
+### 2. Configure via JSON
+
+```json
+{
+  "type": "plugin",
+  "module_path": "my_plugin.adapter",
+  "class_name": "MyL2Adapter",
+  "adapter_params": {
+    "host": "10.0.0.1"
+  }
+}
+```
+
+### 3. Launch
+
+```bash
+# via CLI
+--l2-adapter '{"type":"plugin","module_path":"my_plugin.adapter","class_name":"MyL2Adapter","adapter_params":{"host":"10.0.0.1"}}'
+
+# or via pytest (for testing)
+cfg = PluginL2AdapterConfig.from_dict({...})
+adapter = create_l2_adapter_from_registry(cfg)
+```
+
+---
+
+## Reference Implementation
+
+See `examples/lmc_external_l2_adapter/` for a complete, pip-installable
+example plugin (`InMemoryL2Adapter`) that demonstrates:
+
+- FIFO eviction with configurable capacity.
+- Simulated bandwidth delay for realistic testing.
+- Background asyncio event loop with proper shutdown.
+- Full test suite covering store, lookup, load, batch operations,
+  and eviction behavior.
+
+---
+
+## Native Plugin L2 Adapter (`native_plugin`)
+
+The **Native Plugin** adapter type (`"native_plugin"`) enables loading
+third-party **native connectors** (pybind-wrapped C++ or pure-Python
+implementations of the `IStorageConnector` interface) without requiring
+them to re-implement the Python-side demux/lock bridging logic.
+
+### How It Differs from `plugin`
+
+| Aspect | `plugin` | `native_plugin` |
+|---|---|---|
+| What is loaded | A full `L2AdapterInterface` subclass | A **connector** object (lower level) |
+| Bridging logic | Provided by the plugin itself | Reused from `NativeConnectorL2Adapter` |
+| Third-party effort | Must implement all abstract methods + 3 eventfds | Only 6 connector methods |
+
+### `NativePluginL2AdapterConfig`
+
+Config class registered under the type name `"native_plugin"`. Fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `module_path` | `str` | yes | Dotted Python import path of the module containing the connector class. |
+| `class_name` | `str` | yes | Name of the connector class inside `module_path`. |
+| `adapter_params` | `dict` | no | Forwarded as `**kwargs` to the connector class constructor. |
+
+### Required Connector Interface
+
+The dynamically loaded connector instance must expose the following
+methods (identical to the pybind `LMCACHE_BIND_CONNECTOR_METHODS` contract):
+
+```python
+class NativeConnectorProtocol:
+    def event_fd(self) -> int: ...
+    def submit_batch_get(self, keys: list[str], memoryviews: list[memoryview]) -> int: ...
+    def submit_batch_set(self, keys: list[str], memoryviews: list[memoryview]) -> int: ...
+    def submit_batch_exists(self, keys: list[str]) -> int: ...
+    def drain_completions(self) -> list[tuple[int, bool, str, list[bool] | None]]: ...
+    def close(self) -> None: ...
+```
+
+The factory validates these methods at creation time and raises
+`TypeError` if any are missing.
+
+### Loading Flow
+
+```
+CLI / config JSON
+  │
+  ▼
+parse_args_to_l2_adapters_config()
+  │  JSON: {"type": "native_plugin",
+  │         "module_path": "my_ext.connector",
+  │         "class_name": "MyConnectorClient",
+  │         "adapter_params": {"host": "localhost"}}
+  │
+  ▼
+NativePluginL2AdapterConfig.from_dict(d)
+  │
+  ▼
+_create_native_plugin_l2_adapter(config, ...)
+  │
+  ├─ importlib.import_module(config.module_path)
+  ├─ getattr(module, config.class_name)
+  ├─ connector_cls(**config.adapter_params)
+  ├─ validate 6 required methods
+  └─ NativeConnectorL2Adapter(native_client)
+          │
+          ▼
+  L2AdapterInterface instance (ready for use)
+```
+
+### Example
+
+```json
+{
+  "type": "native_plugin",
+  "module_path": "lmc_external_native_connector",
+  "class_name": "ExampleNativeConnector",
+  "adapter_params": {
+    "backend": "fs",
+    "base_path": "/tmp/lmcache_ext",
+    "num_workers": 2
+  }
+}
+```
+
+### Reference Implementation
+
+See `examples/lmc_external_native_connector/` for a complete,
+pip-installable example connector plugin that demonstrates:
+
+- C++ pybind11-wrapped connectors inheriting from
+  `ConnectorBase<T>` (same as built-in Redis/FS).
+- Two backends: filesystem (ExampleFSConnector) and
+  in-memory (ExampleMemoryConnector), both in C++.
+- A thin Python factory class (`ExampleNativeConnector`)
+  that selects the backend via a `"backend"` parameter.
+- Worker thread pool with eventfd notification
+  (inherited from `ConnectorBase`).
+- Build via `pip install -e .` using pybind11 + setuptools.
+
+---
+
+## Self-Registration Mechanism
+
+The `plugin_l2_adapter.py` and `native_connector_l2_adapter.py`
+modules follow the same self-registration pattern as all other
+adapters in the package:
+
+```
+__init__.py
+  └─ pkgutil.iter_modules → importlib.import_module
+       ├─ plugin_l2_adapter.py (auto-discovered)
+       │    ├─ register_l2_adapter_type("plugin", PluginL2AdapterConfig)
+       │    └─ register_l2_adapter_factory("plugin", _create_plugin_adapter)
+       │
+       ├─ raw_block_l2_adapter.py (auto-discovered)
+       │    ├─ register_l2_adapter_type("raw_block", RawBlockL2AdapterConfig)
+       │    └─ register_l2_adapter_factory("raw_block", _create_raw_block_adapter)
+       │
+       └─ native_connector_l2_adapter.py (auto-discovered)
+            ├─ register_l2_adapter_type("resp", ...)
+            ├─ register_l2_adapter_type("fs_native", ...)
+            └─ register_l2_adapter_type("native_plugin", NativePluginL2AdapterConfig)
+```
+
+No changes to existing codes are needed when these modules
+are present in the `l2_adapters/` package directory.
diff --git a/docs/design/v1/distributed/l2_adapters/raw_block.md b/docs/design/v1/distributed/l2_adapters/raw_block.md
new file mode 100644
index 0000000..1f14896
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/raw_block.md
@@ -0,0 +1,155 @@
+# Raw Block L2 Adapter Design
+
+This document describes the built-in `raw_block` L2 adapter for LMCache MP
+mode. It covers the adapter shape, the shared raw-block core, and the recovery
+model.
+
+## Overview
+
+`raw_block` is a persistent MP L2 adapter backed by a raw block device or a
+dedicated file. It is designed to keep the MP request flow unchanged while
+reusing the existing raw-block on-device metadata format and the low-level Rust
+raw-device I/O path.
+
+```text
+StoreController / PrefetchController
+                |
+                v
+        RawBlockL2Adapter
+                |
+                v
+           RawBlockCore
+      (index, locks, slots, checkpoints)
+                |
+                v
+         lmcache_rust_raw_block_io
+      (pwrite_from_buffer / pread_into)
+                |
+                v
+         raw block device / file
+```
+
+## Goals
+
+- Support LMCache MP mode using raw block storage as an L2 cache.
+- Reuse the same durable metadata and checkpoint model as the existing
+  non-MP raw-block backend.
+- Reuse the existing Rust raw-device I/O layer.
+- Preserve restart recovery semantics.
+- Keep the MP controller flow unchanged: store, lookup-and-lock, load, unlock.
+
+## TODO
+
+- FDP / placement-hint support.
+- A raw NVMe command path.
+
+## Key Design Choice
+
+The implementation is split into:
+
+- `RawBlockCore` in `lmcache/v1/storage_backend/raw_block/`
+- `RawBlockL2Adapter` in `lmcache/v1/distributed/l2_adapters/`
+- `RustRawBlockBackend` as the legacy non-MP wrapper
+
+`RawBlockCore` owns the durable state and blocking I/O:
+
+- raw device open/close
+- in-memory key index
+- free-slot tracking
+- lock refcounts used by MP lookup/load/unlock
+- metadata checkpointing and recovery
+- direct reads and writes through the Rust binding
+
+This avoids maintaining separate raw-block implementations for MP and non-MP
+mode.
+
+## Adapter Contract
+
+`RawBlockL2Adapter` implements `L2AdapterInterface` directly. It exposes:
+
+- three distinct eventfds: store, lookup, load
+- non-blocking task submission APIs
+- worker-thread execution for blocking raw-device operations
+- result maps keyed by adapter-local task id
+- listener notifications for stored, accessed, and deleted keys
+
+The adapter uses caller-provided `MemoryObj` buffers for load operations. It
+does not allocate destination buffers on the load path.
+
+## Locking Model
+
+LMCache MP already uses L1 locks for CPU-memory object lifetime. `raw_block`
+adds a separate L2-side lock refcount so a looked-up key cannot be deleted
+between `lookup_and_lock` and `load`.
+
+Rules:
+
+- `exists_many(..., lock=True)` increments the refcount for hits
+- `unlock_many(keys)` decrements and floors at zero
+- `delete(keys)` skips locked entries
+
+## Persistence and Recovery
+
+`RawBlockCore` keeps the existing metadata checkpoint model:
+
+- metadata region reserved on the same device
+- periodic checkpointing
+- optional checkpoint load on startup
+- optional verification on load
+- recovery by loading the latest durable checkpoint and rebuilding the in-memory
+  index
+
+The on-device format is intentionally unchanged by the MP adapter work.
+
+Recovered keys are exposed to the shared L2 eviction policy on adapter startup,
+so reclaimed slots come from global L2 eviction or explicit `delete()` calls.
+
+## Configuration
+
+The MP adapter is configured through `--l2-adapter` JSON:
+
+```json
+{
+  "type": "raw_block",
+  "device_path": "/dev/nvme0n1",
+  "slot_bytes": 1048576,
+  "capacity_bytes": 0,
+  "use_odirect": true,
+  "block_align": 4096,
+  "header_bytes": 4096,
+  "meta_total_bytes": 268435456,
+  "meta_magic": "LMCIDX01",
+  "meta_version": 1,
+  "meta_checkpoint_interval_sec": 60,
+  "meta_enable_periodic": true,
+  "load_checkpoint_on_init": true,
+  "meta_verify_on_load": true,
+  "num_store_workers": 2,
+  "num_lookup_workers": 1,
+  "num_load_workers": 4
+}
+```
+
+Important validation rules:
+
+- `slot_bytes`, `header_bytes`, and `meta_total_bytes` must be aligned to
+  `block_align`
+- `slot_bytes >= header_bytes + 1`
+- `per_tp_device_paths` is rejected in MP mode
+- `load_checkpoint_on_init=false` starts with an empty in-memory index instead
+  of loading the latest on-device metadata checkpoint
+- with `use_odirect=true`, MP L1 alignment must satisfy
+  `l1_align_bytes >= block_align`
+
+## Relationship to Non-MP Mode
+
+The legacy `RustRawBlockBackend` now acts as a thin facade over `RawBlockCore`.
+It preserves non-MP behavior such as prefix-oriented contains/get semantics,
+while the MP adapter uses the core's full-bitmap lookup/load API.
+
+## References
+
+- Implementation: `lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py`
+- Shared core: `lmcache/v1/storage_backend/raw_block/core.py`
+- User docs: `docs/source/mp/l2_storage/raw_block.rst`
+- Rust device layer: `rust/raw_block/README.md`
diff --git a/docs/design/v1/distributed/l2_adapters/serde_wrapper.md b/docs/design/v1/distributed/l2_adapters/serde_wrapper.md
new file mode 100644
index 0000000..037eaf4
--- /dev/null
+++ b/docs/design/v1/distributed/l2_adapters/serde_wrapper.md
@@ -0,0 +1,301 @@
+# `SerdeL2AdapterWrapper` — Transparent Serde via Adapter Composition
+
+## Scope
+
+Describes how serialization / deserialization is integrated into the
+L2 path. The serde package itself
+([`docs/design/v1/distributed/serde/README.md`](../serde/README.md))
+defines the generic `Serializer` / `Deserializer` / `SerdeProcessor`
+interfaces and the fp8 built-in. **This** doc is about the adapter
+that stitches serde into the distributed storage pipeline.
+
+## Design Summary
+
+`SerdeL2AdapterWrapper` implements `L2AdapterInterface` by composing
+an inner L2 adapter with a `SerdeProcessor` and an `L1Manager`. The
+caller sees the wrapper's public API only; the wrapper's internal
+thread is the sole consumer of the inner adapter's and serde's event
+fds.
+
+Step numbers below show **call ordering**. Solid `─►` arrows are
+direct synchronous calls; dotted `╌►` arrows are eventfd wakeups
+consumed by the wrapper's internal thread.
+
+### Store path
+
+```
+   caller                                                          
+     │                                                             
+     │ (1) submit_store_task(keys, objs)                           
+     ▼                                                             
+   ┌─────────────────┐  (2) reserve_write(tmp)   ┌──────────────┐  
+   │  wrapper (API)  │ ─────────────────────────►│  L1Manager   │  
+   │                 │ ◄────── tmp_objs ─────────│              │  
+   └────────┬────────┘                           └──────────────┘  
+            │ (3) submit_serialize(objs, tmp_objs)                 
+            ▼                                                      
+   ┌─────────────────┐                                             
+   │ SerdeProcessor  │   transforms objs → tmp_objs                
+   └────────┬────────┘                                             
+            ╎ (4) serialize_efd                                    
+            ▼                                                      
+   ┌─────────────────┐  (5) inner.submit_store_   ┌──────────────┐ 
+   │ wrapper thread  │      task(keys, tmp_objs)  │   inner L2   │ 
+   │   (_loop)       │ ─────────────────────────► │   adapter    │ 
+   └────────┬────────┘                            └──────┬───────┘ 
+            ▲                                            │         
+            ╎ (6) inner.store_efd ◄──────────────────────┘         
+            │                                                      
+   ┌────────┴────────┐                                             
+   │ wrapper thread  │  (7) finish_read(tmp_objs)  → auto-delete   
+   │                 │      signal wrapper.store_efd               
+   └────────┬────────┘                                             
+            │                                                      
+            │ (8) pop_completed_store_tasks() →                   
+            │     {wrapped_id: L2StoreResult(success=True,         
+            │                                bytes_transferred=N)}
+            ▼                                                      
+          caller                                                   
+```
+
+### Load path
+
+```
+   caller                                                          
+     │                                                             
+     │ (1) submit_load_task(keys, dst_objs)                        
+     ▼                                                             
+   ┌─────────────────┐  (2) reserve_write(tmp)   ┌──────────────┐  
+   │  wrapper (API)  │ ─────────────────────────►│  L1Manager   │  
+   │                 │ ◄────── tmp_objs ─────────│              │  
+   └────────┬────────┘                           └──────────────┘  
+            │ (3) inner.submit_load_task(keys, tmp_objs)           
+            ▼                                                      
+   ┌─────────────────┐                                             
+   │  inner L2       │   loads serialized bytes into tmp_objs      
+   │  adapter        │                                             
+   └────────┬────────┘                                             
+            ╎ (4) inner.load_efd                                   
+            ▼                                                      
+   ┌─────────────────┐  (5) submit_deserialize    ┌──────────────┐ 
+   │ wrapper thread  │      (tmp_objs, dst_objs)  │   Serde      │ 
+   │   (_loop)       │ ─────────────────────────► │  Processor   │ 
+   └────────┬────────┘                            └──────┬───────┘ 
+            ▲                                            │         
+            ╎ (6) deserialize_efd ◄──────────────────────┘         
+            │                                                      
+   ┌────────┴────────┐                                             
+   │ wrapper thread  │  (7) finish_write + delete(tmp_objs)        
+   │                 │      signal wrapper.load_efd                
+   └────────┬────────┘                                             
+            │                                                      
+            │ (8) query_load_result() → per-key bitmap             
+            ▼                                                      
+          caller                                                   
+```
+
+## Store Path
+
+```mermaid
+sequenceDiagram
+    participant Controller as StoreController
+    participant W as SerdeL2AdapterWrapper
+    participant Thread as wrapper internal thread
+    participant Serde as SerdeProcessor
+    participant L1 as L1Manager
+    participant Inner as inner L2 adapter
+
+    Controller->>W: submit_store_task(keys, objs)
+    W->>L1: reserve_write(temp_keys, byte layout)
+    L1-->>W: temp_objs (write-locked)
+    W->>Serde: submit_serialize(objs, temp_objs) → serde_id
+    W-->>Controller: wrapped_id
+
+    Note over Serde,Thread: serde thread pool transforms<br/>objs → temp_objs, signals fd
+
+    Serde-->>Thread: serialize_efd fires
+    Thread->>Serde: query_serialize_result(serde_id)
+    Serde-->>Thread: success
+    Thread->>L1: finish_write_and_reserve_read(temp_keys)
+    Thread->>Inner: submit_store_task(keys, temp_objs) → inner_id
+
+    Note over Inner: inner stores serialized bytes,<br/>signals its store_efd
+
+    Inner-->>Thread: store_efd fires
+    Thread->>Inner: pop_completed_store_tasks()
+    Inner-->>Thread: {inner_id: L2StoreResult(ok=True, bytes=N)}
+    Thread->>L1: finish_read(temp_keys)   %% auto-deletes temps
+    Thread->>W: _finalize_store(wrapped_id, inner_result)
+    W-->>Controller: store_efd fires
+
+    Controller->>W: pop_completed_store_tasks()
+    W-->>Controller: {wrapped_id: L2StoreResult(ok=True, bytes=N)}
+```
+
+## Load Path
+
+```mermaid
+sequenceDiagram
+    participant Controller as PrefetchController
+    participant W as SerdeL2AdapterWrapper
+    participant Thread as wrapper internal thread
+    participant Inner as inner L2 adapter
+    participant Serde as SerdeProcessor
+    participant L1 as L1Manager
+
+    Controller->>W: submit_load_task(keys, dst_objs)
+    W->>L1: reserve_write(temp_keys, byte layout)
+    L1-->>W: temp_objs (write-locked)
+    W->>Inner: submit_load_task(keys, temp_objs) → inner_id
+    W-->>Controller: wrapped_id
+
+    Note over Inner: inner loads serialized bytes<br/>into temp_objs, signals load_efd
+
+    Inner-->>Thread: load_efd fires
+    Thread->>Inner: query_load_result(inner_id)
+    Inner-->>Thread: bitmap (per-key success)
+
+    alt all-zeros bitmap
+        Thread->>L1: finish_write + delete temp_keys
+        Thread->>W: _finalize_load(wrapped_id, bitmap)
+    else some keys loaded
+        Thread->>Serde: submit_deserialize(temp_objs, dst_objs) → serde_id
+        Note over Serde: serde thread transforms<br/>temp_objs → dst_objs
+        Serde-->>Thread: deserialize_efd fires
+        Thread->>Serde: query_deserialize_result(serde_id)
+        alt success
+            Thread->>L1: finish_write + delete temp_keys
+            Thread->>W: _finalize_load(wrapped_id, bitmap)
+        else failure
+            Thread->>L1: finish_write + delete temp_keys
+            Thread->>W: _finalize_load(wrapped_id, Bitmap(0, len))
+            Note right of W: zero bitmap ⇒ controller<br/>treats keys as load failures
+        end
+    end
+
+    W-->>Controller: load_efd fires
+    Controller->>W: query_load_result(wrapped_id)
+    W-->>Controller: final bitmap
+```
+
+## Lookup / Unlock / Eviction
+
+These paths don't involve any transform, so the wrapper delegates
+directly to the inner adapter — including the lookup event fd
+itself, to avoid an unnecessary thread hop per lookup.
+
+| API | Behavior |
+|---|---|
+| `get_lookup_and_lock_event_fd` | Returns the inner adapter's fd (pass-through) |
+| `submit_lookup_and_lock_task` / `query_lookup_and_lock_result` | Delegated directly |
+| `submit_unlock` | Delegated directly |
+| `delete` / `get_usage` / `supports_global_eviction` | Delegated directly |
+| `register_listener` | Registers on the inner adapter (listeners track real storage state) |
+
+The wrapper does **not** maintain its own byte accounting — it
+reports whatever the inner adapter reports. This keeps
+`L2EvictionController` and per-cache_salt quota logic unchanged:
+they see the inner adapter's byte totals through the wrapper's
+`get_usage()`.
+
+## Temp Buffer Lifecycle
+
+Temp byte buffers are the only new L1 state the wrapper introduces.
+They exist entirely within the wrapper's knowledge — the caller never
+sees the temp keys.
+
+**Store path:**
+
+1. `reserve_write(temp_keys, is_temporary=True, layout=ser_layout, mode="new")`
+   — temps are write-locked and marked temporary so
+   `finish_read` will auto-delete them later.
+2. Serialize runs, filling temps.
+3. On success: `finish_write_and_reserve_read(temp_keys)` — temps
+   become read-locked so `inner.submit_store_task` can safely read
+   them.
+4. Inner store completes → `finish_read(temp_keys)` — since
+   `is_temporary=True`, finish_read also deletes them.
+5. On serialize or inner failure: `finish_write(temp_keys) + delete(temp_keys)`
+   while temps are still write-locked.
+
+**Load path:**
+
+1. `reserve_write(temp_keys, is_temporary=True, layout=ser_layout, mode="new")`
+   — same as store, temps write-locked.
+2. `inner.submit_load_task(keys, temp_objs)` — inner loads serialized
+   bytes into temps.
+3. Inner completes → `submit_deserialize(temp_objs, dst_objs)` — note
+   temps stay write-locked (the wrapper owns them; only the wrapper
+   reads them during deserialize).
+4. Deserialize completes → `finish_write(temp_keys) + delete(temp_keys)`
+   regardless of deserialize success.
+
+## Failure Policy: All-or-Nothing per Submit
+
+If **any** key's temp allocation fails or `submit_serialize` /
+`submit_deserialize` / `inner.submit_*` raises, the **whole wrapped
+task fails**:
+
+- Store task: `pop_completed_store_tasks()` returns
+  `{wrapped_id: L2StoreResult(success=False, bytes_transferred=0)}`.
+- Load task: `query_load_result(wrapped_id)` returns an all-zeros
+  `Bitmap(len(keys))`.
+
+This preserves the **coarse-grained success semantic** of
+`L2AdapterInterface` — store is task-level (the `L2StoreResult.is_successful()`
+flag), load is per-key via bitmap. The alternative ("drop the failed keys,
+succeed with the rest") would silently violate the caller's assumption
+that every key it passed either succeeded (task-level) or failed
+(task-level). Keeping the policy coarse is what lets the controllers
+stay untouched.
+
+Partial load failures inside the inner adapter (some keys in the
+inner bitmap succeed, some fail) are faithfully preserved: only keys
+with `bitmap.test(i) == True` are deserialized, and the wrapper
+reports the same bitmap to the controller (zeroed if deserialize
+itself fails).
+
+## Homogeneity Invariant
+
+`_alloc_temp_buffers` sizes temps from `objects[0].get_shapes() /
+get_dtypes()` under the assumption that **all MemoryObjs in one
+submit share a single layout**. The store controller already
+shape-groups keys before calling `submit_store_task`; the prefetch
+controller uses a single `layout_desc` per request for all write
+reservations. The wrapper enforces the invariant with an explicit
+`raise ValueError` to catch future regressions.
+
+## Threading Model
+
+One background thread per wrapper instance, started in `__init__`.
+
+- Poll loop over four fds: `inner.store_efd`, `inner.load_efd`,
+  `serde.serialize_efd`, `serde.deserialize_efd`.
+- Single `threading.Lock` protecting: the task-id counter, the four
+  reverse-lookup dicts, the two completion dicts, and the phase flip
+  on store tasks.
+- `close()` sets a stop flag and joins the thread; the poll timeout
+  (`500 ms`) bounds shutdown latency.
+- `_finalize_store` / `_finalize_load` write 1 to the wrapper's own
+  eventfd to wake the upstream controller's poll loop.
+
+The wrapper does **not** share any state with the inner adapter or
+the `SerdeProcessor` beyond the public interface — both are
+independent thread-safe components, and the wrapper's thread
+interacts with them only through their documented APIs.
+
+## Known Limitations / Follow-ups
+
+- **Temp buffer allocation per submit.** Every store / load call
+  issues an `L1Manager.reserve_write` for fresh temp keys. A free-list
+  keyed on `(shape, dtype)` would skip the allocator on the hot path.
+  Not done in the initial version — correctness first.
+- **Bookkeeping-dict duplication.** Six of the existing L2 adapters
+  maintain their own `_next_task_id + lock + completion_dict + eventfd`
+  quartet; `AsyncSerdeProcessor` is a seventh; this wrapper is an
+  eighth. An `EventfdTaskQueue` base helper could dedupe this across
+  the tree — a separate cleanup PR.
+- **No wrapper-level metrics.** `report_status` delegates to the inner
+  and adds `{"serde_wrapped": True}`. Adding per-serde-step latency
+  histograms would need either new metrics from `AsyncSerdeProcessor`
+  or timing hooks in the wrapper's drains.
diff --git a/docs/design/v1/distributed/serde/README.md b/docs/design/v1/distributed/serde/README.md
new file mode 100644
index 0000000..5c19894
--- /dev/null
+++ b/docs/design/v1/distributed/serde/README.md
@@ -0,0 +1,269 @@
+# `lmcache.v1.distributed.serde` — Serialization / Deserialization Package
+
+## Scope
+
+This package holds the **generic serde primitives** used by the
+distributed storage stack. It does not know anything about L2 adapters
+or controllers — it just defines:
+
+- A pair of **sync interfaces** users implement (`Serializer`,
+  `Deserializer`) for the actual byte transform.
+- An **async interface** (`SerdeProcessor`) with the same
+  `submit → eventfd → query` shape as an L2 adapter, so downstream
+  consumers can poll it uniformly.
+- A default implementation (`AsyncSerdeProcessor`) that turns any pair
+  of sync implementations into the async interface by running them in
+  a thread pool and signaling an eventfd on completion.
+- A factory / registration mechanism so adapters can reference a serde
+  by name (`{"type": "fp8", ...}` in JSON config).
+- One built-in serde: **fp8 quantization**.
+
+How the async interface is actually plugged into the L2 path lives in
+[`docs/design/v1/distributed/l2_adapters/serde_wrapper.md`][wrapper-doc]
+— the wrapper is the sole consumer of `SerdeProcessor`'s event fds.
+
+[wrapper-doc]: ../l2_adapters/serde_wrapper.md
+
+## Module Layout
+
+```
+lmcache/v1/distributed/serde/
+  base.py             # Serializer, Deserializer (sync ABCs)
+                      # SerdeProcessor (async ABC)
+                      # SerdeConfig, SerdeTaskId
+  async_processor.py  # AsyncSerdeProcessor (thread-pool + eventfd wrapper)
+  factory.py          # register_serde_factory / create_serde_processor
+  fp8.py              # Fp8QuantizationSerializer / Deserializer
+  multi.py            # MultiSerializer / MultiDeserializer (tuple-shaped
+                      # extension; see "Multi-output extension" below)
+  utils.py            # serialized_layout_desc, make_temp_key
+```
+
+## Two-Layer Interface
+
+```
+                 ┌────────────────────────────────┐
+ user writes →   │  Serializer / Deserializer     │  sync transform
+                 │  (pure: src MemoryObj → dst)   │
+                 └──────────────┬─────────────────┘
+                                │ wrapped by AsyncSerdeProcessor
+                                ▼
+                 ┌────────────────────────────────┐
+ wrapper uses →  │  SerdeProcessor                │  async:
+                 │    submit_serialize(...) → id  │   submit / eventfd /
+                 │    query_serialize_result(id)  │   query
+                 │    get_serialize_event_fd()    │
+                 │    (plus deserialize pair)     │
+                 └────────────────────────────────┘
+```
+
+- **Sync layer** is where the user cares. Pure Python (or torch) code,
+  no threads, no fds. Two abstract methods: `serialize(src, dst)` and
+  `estimate_serialized_size(layout_desc)`.
+- **Async layer** is what the `SerdeL2AdapterWrapper` talks to. It
+  owns two eventfds (one for serialize, one for deserialize) that
+  must be distinct, and queues completed tasks in a dict the wrapper
+  drains.
+
+`AsyncSerdeProcessor` is the default and typically only implementation
+of the async layer — most custom serdes only need to provide the sync
+classes and register a factory.
+
+## Contracts
+
+### `Serializer.serialize(src, dst) -> int`
+
+- `src` is a `MemoryObj` holding KV data (read-locked by the caller).
+- `dst` is a `MemoryObj` byte buffer (write-locked by the caller),
+  sized ≥ `estimate_serialized_size(layout_of_src)`.
+- Must return the number of bytes actually written to `dst`.
+- Must be **deterministic** given the same `src` — the wrapper relies
+  on the serialize step being reproducible across retries.
+
+### `Serializer.estimate_serialized_size(layout_desc) -> int`
+
+- Called once per batch to size the temp buffer **before** any work.
+- Must be an **upper bound** on the actual serialized output. Include
+  any safety margin inside this method (the fp8 serializer returns
+  `1.5 × num_elements` for exactly this reason).
+- Must only depend on `layout_desc` (shapes + dtypes). The wrapper
+  uses the first object's layout to size temps for the whole batch,
+  so a data-dependent estimate would break all-or-nothing allocation.
+
+### `Deserializer.deserialize(src, dst) -> None`
+
+- `src` is a byte-buffer MemoryObj filled by L2 load.
+- `dst` is a KV-shaped MemoryObj (write-locked), already the correct
+  shape and dtype.
+- No return value — the caller observes completion via the async
+  layer's event fd.
+
+### `SerdeProcessor` (async)
+
+- `submit_serialize(src_objs, dst_objs) → SerdeTaskId` must be
+  non-blocking. The actual transform runs asynchronously.
+- `query_serialize_result(task_id) → bool | None` is
+  **non-idempotent**: it returns a non-None value exactly once per
+  task id. `None` means the task is still in flight.
+- `get_serialize_event_fd()` returns an eventfd signaled once per
+  completed serialize task; distinct from the deserialize fd.
+- The deserialize side has the identical shape.
+- `close()` must release both event fds and any worker threads.
+
+## `AsyncSerdeProcessor`
+
+Wraps any `(Serializer, Deserializer)` pair. Internal design:
+
+- One `ThreadPoolExecutor(max_workers=N)` runs both serialize and
+  deserialize tasks; they're independent, so the pool is shared.
+- One task-id counter under a single lock; two `_completed_*` dicts
+  (one per direction) protected by the same lock.
+- Two `os.eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC)` file descriptors —
+  one per direction, signaled after the result is written to the
+  completion dict.
+
+**Why a pool, not an asyncio executor:** the CPU-bound fp8 / encryption
+transforms release the GIL under torch / native calls, so a real
+thread pool is useful. `N=1` is a safe default (one in-flight
+transform at a time), and the fp8 factory accepts `max_workers` to
+bump it.
+
+## Factory / Registration
+
+```python
+from lmcache.v1.distributed.serde import (
+    AsyncSerdeProcessor, Deserializer, Serializer,
+    register_serde_factory,
+)
+
+def _create_my_serde(kwargs: dict[str, object]) -> SerdeProcessor:
+    return AsyncSerdeProcessor(MySerializer(...), MyDeserializer(...))
+
+register_serde_factory("mine", _create_my_serde)
+```
+
+The factory receives the type-specific kwargs from the JSON config
+(everything except `"type"`). The registry is process-global and
+rejects duplicate names, matching the pattern already used by
+`register_l2_adapter_type`.
+
+The factory is called exactly once per `SerdeL2AdapterWrapper`
+construction — each wrapped adapter gets its own `SerdeProcessor`
+instance.
+
+## Built-in fp8
+
+`Fp8QuantizationSerializer` / `Fp8QuantizationDeserializer`:
+
+- Cast each element to `torch.float8_e4m3fn` (default) or
+  `torch.float8_e5m2`, reinterpret the bytes as `uint8`, and copy into
+  the temp buffer.
+- Deserialize reinterprets the `uint8` bytes as the chosen fp8 dtype,
+  reshapes back to the original KV shape, and casts to the destination
+  tensor's dtype.
+- `estimate_serialized_size` returns `int(total_elements × 1.5)` — the
+  exact fp8 size is `num_elements × 1 byte`, and the 1.5× headroom
+  absorbs future format changes or alignment padding.
+
+## Extension Guide
+
+Most custom serdes only need:
+
+1. Two classes implementing `Serializer` / `Deserializer`.
+2. A factory function registered at import time.
+3. A JSON `serde` sub-dict on the adapter config: `{"type": "mine", ...}`.
+
+Everything else — temp buffer allocation, eventfd plumbing, lock /
+lifecycle transitions, all-or-nothing failure handling — is provided
+by `AsyncSerdeProcessor` and the wrapper. Users never need to touch
+controllers, eventfds, or L1 locks.
+
+## Multi-output extension
+
+The `Serializer` / `Deserializer` classes above operate on one
+typed tensor at each endpoint: one tensor in, one byte buffer out
+on serialize, and the reverse on deserialize. That shape works
+when K and V share a single data type -- the serde just sees them
+as one combined tensor. It does not work in two cases:
+
+- **K and V at different data types.** A typed tensor has one
+  dtype, so a serde that wants K at one dtype (e.g. fp16/bf16) and
+  V at another (e.g. FP8) cannot carry both.
+- **One side absent.** For tier-split placements where K or V is
+  held outside this serde's data path -- e.g. K kept in L1 (CPU
+  pinned host memory) while V flows to L2 (durable storage) -- the
+  serialize input has no tensor for the absent slot and the
+  deserialize output has no destination for it.
+
+`multi.py` defines the additive contract for this case:
+
+- `MemoryObjGroup = Tuple[Optional[MemoryObj], ...]` is a
+  fixed-length tuple of optional MemoryObjs.
+- `LayoutDescGroup = Tuple[Optional[MemoryLayoutDesc], ...]` is the
+  parallel layout-descriptor tuple used by size estimators.
+- `MultiSerializer.serialize(src: MemoryObjGroup, dst: MemoryObj)`
+  takes a group whose length equals `MultiSerializer.group_size`.
+- `MultiDeserializer.deserialize(src: MemoryObj, dst: MemoryObjGroup)`
+  produces a group whose length equals
+  `MultiDeserializer.group_size`.
+- `single_to_multi_serializer(s)` and
+  `single_to_multi_deserializer(d)` adapt an existing single-tensor
+  pair to the tuple interface as a length-1 group; the adapter is
+  layout-equivalent (same on-the-wire bytes as a direct call).
+
+The single-tensor `Serializer` / `Deserializer` ABCs and all their
+existing callers — `AsyncSerdeProcessor`, the factory registry, the
+L2 adapter wrapper, the built-in `fp8` serde — are unchanged. A
+serde implementation that needs multiple tensors at an endpoint
+implements `MultiSerializer` / `MultiDeserializer` instead of (or in
+addition to) the single-tensor ABCs. The async wiring around the
+multi interface — a tuple-aware `AsyncSerdeProcessor` analog and a
+tuple-aware `submit_*` shape on the wrapper — is added in a follow-up
+once a concrete multi-output serde lands.
+
+### Per-slot semantics
+
+Implementations MUST document, at minimum:
+
+1. The fixed value of `group_size`.
+2. The semantic carried by each slot (e.g., `slot 0 = K`,
+   `slot 1 = V`).
+3. Which slots are required and which may be `None`. A slot that may
+   be `None` MUST be tolerated by `estimate_serialized_size` with a
+   `None` layout descriptor at the same index.
+
+`None` semantics, mirroring serialize input vs deserialize output:
+
+- **Serialize input.** A `None` slot means the caller is not
+  supplying that tensor; e.g., a V-only write where K is held
+  outside this serde's data path. The implementation MUST raise
+  `ValueError` when a required slot is `None`.
+- **Deserialize output.** A `None` slot means the caller does not
+  want that tensor materialized; e.g., a V-only read where K is
+  sourced elsewhere. The implementation MUST NOT touch the missing
+  slot.
+
+### Single-element bridge
+
+A length-1 `MemoryObjGroup` is the trivial bridge to the existing
+single-tensor API. `single_to_multi_serializer(inner)` wraps an
+existing `Serializer` so callers that work in groups can invoke it
+uniformly:
+
+```python
+from lmcache.v1.distributed.serde import (
+    single_to_multi_serializer,
+    single_to_multi_deserializer,
+)
+
+multi_s = single_to_multi_serializer(existing_serializer)
+multi_d = single_to_multi_deserializer(existing_deserializer)
+n = multi_s.serialize((src,), dst_buffer)         # length-1 group
+multi_d.deserialize(src_buffer, (dst,))           # length-1 group
+```
+
+The wrapper rejects non-unit groups with `ValueError`, rejects a
+`None` src slot (single-tensor serializers do not admit absence),
+and treats a `None` dst slot as a deliberate skip rather than an
+error. On-the-wire bytes are byte-for-byte identical to a direct
+call against the underlying single-tensor serde.
diff --git a/docs/design/v1/distributed/serde/turboquant.md b/docs/design/v1/distributed/serde/turboquant.md
new file mode 100644
index 0000000..09e098a
--- /dev/null
+++ b/docs/design/v1/distributed/serde/turboquant.md
@@ -0,0 +1,336 @@
+# `lmcache.v1.distributed.serde.turboquant` — TurboQuant Serde Backend
+
+## Scope
+
+This document describes the TurboQuant serde backend for LMCache L2 adapters.
+TurboQuant serde is a storage-layer transform. It compresses LMCache KV tensors
+before they are written to L2 storage and reconstructs KV tensors after L2
+prefetch. It does not implement an attention backend and does not change the
+StorageManager or L2 adapter public APIs.
+
+The serde is intended to be used through the generic serde framework described
+in [`docs/design/v1/distributed/serde/README.md`](README.md) and the L2 adapter
+wrapper described in
+[`docs/design/v1/distributed/l2_adapters/serde_wrapper.md`](../l2_adapters/serde_wrapper.md).
+
+## Motivation
+
+KV cache tensors can be large, especially for long-context workloads and
+multi-layer models. Storing raw fp16/bf16 KV tensors in L2 increases storage
+capacity requirements and L2 transfer volume.
+
+TurboQuant serde reduces the serialized KV size by applying low-bit KV
+compression before L2 store. During L2 load / prefetch, the compressed bytes are
+decompressed back into the original LMCache KV tensor layout.
+
+## Data Path
+
+### Store Path
+
+```text
+MemoryObj(KV tensor)
+  -> TurboQuantSerializer.serialize(src, dst)
+  -> TurboQuant store Triton kernel
+  -> MemoryObj(uint8 compressed bytes)
+  -> inner L2 adapter store
+```
+
+### Load / Prefetch Path
+
+```text
+inner L2 adapter load
+  -> MemoryObj(uint8 compressed bytes)
+  -> TurboQuantDeserializer.deserialize(src, dst)
+  -> TurboQuant decode Triton kernel
+  -> MemoryObj(restored KV tensor)
+```
+
+The caller only observes the normal LMCache L2 store / load behavior. Temporary
+byte buffers, serde task scheduling, eventfd signaling, and lock lifecycle are
+handled by SerdeL2AdapterWrapper and AsyncSerdeProcessor.
+
+## Public Interfaces
+
+TurboQuant serde provides the synchronous serde interfaces required by the
+generic serde framework:
+
+* `TurboQuantSerializer.serialize(src, dst) -> int`
+* `TurboQuantSerializer.estimate_serialized_size(layout_desc) -> int`
+* `TurboQuantDeserializer.deserialize(src, dst) -> None`
+
+It is registered under the serde type name:
+
+```json
+{
+  "type": "turboquant"
+}
+```
+
+The factory accepts TurboQuant-specific kwargs and constructs an
+AsyncSerdeProcessor wrapping the serializer and deserializer.
+
+## Configuration
+
+`TurboQuantSerdeConfig` controls the compression preset and layout parameters.
+
+Supported presets:
+
+| Preset | Key path | Value path | Norm correction |
+| --- | --- | --- | --- |
+| `turboquant_k8v4` | FP8 key | 4-bit value quantization | No |
+| `turboquant_4bit_nc` | 4-bit MSE key | 4-bit value quantization | Yes |
+| `turboquant_k3v4_nc` | 3-bit MSE key | 4-bit value quantization | Yes |
+| `turboquant_3bit_nc` | 3-bit MSE key | 3-bit value quantization | Yes |
+
+Other config fields:
+
+* `head_dim`: per-head hidden dimension.
+* `block_size`: token block size used by the compressed layout.
+* `skip_first_layers`: number of leading layers stored in the original raw KV
+  format instead of the TurboQuant compressed format. The default is `2`.
+* `skip_last_layers`: number of trailing layers stored in the original raw KV
+  format instead of the TurboQuant compressed format. The default is `2`.
+
+The skipped layer settings implement boundary-layer protection. By default,
+TurboQuant serde stores the first two and last two layers without quantization
+and only compresses the middle layers. This matches the default vLLM
+TurboQuant behavior, where the first and last two attention layers are skipped
+from TurboQuant KV-cache compression because they are more sensitive to
+quantization error.
+
+For a model with `num_layers` layers, the compressed range is:
+
+```text
+quant_start = min(skip_first_layers, num_layers)
+quant_end = max(quant_start, num_layers - skip_last_layers)
+```
+
+Layers `[0, quant_start)` and `[quant_end, num_layers)` are serialized as raw
+KV bytes. Layers `[quant_start, quant_end)` are serialized with the TurboQuant
+packed layout.
+
+Invalid presets are rejected with `ValueError`.
+
+## Tensor Layout
+
+TurboQuant serde expects LMCache KV tensors in this layout:
+
+```text
+[2, num_layers, num_tokens, hidden_dim]
+```
+
+The first dimension separates key and value tensors:
+
+* `src[0]`: key cache
+* `src[1]`: value cache
+
+The serialized byte layout is:
+
+```text
+raw first layers | compressed middle layers | raw last layers
+```
+
+where:
+
+* raw layer groups use the original `[2, num_layers, num_tokens, hidden_dim]`
+  KV byte layout.
+
+* compressed middle layers use
+  `[num_compressed_layers, num_blocks, block_size, num_heads, slot_size]`.
+
+* `num_blocks = ceil(num_tokens / block_size)`
+* `num_heads = hidden_dim / head_dim`
+* `slot_size = key_packed_size + value_packed_size`
+* `slot_size_aligned` is used for the serialized byte layout
+
+`estimate_serialized_size()` computes the number of bytes required for this
+compressed layout from `MemoryLayoutDesc`.
+
+## Compression Path
+
+`TurboQuantSerializer` launches Triton store kernels to compress each layer.
+
+The store path performs:
+
+1. KV layout validation.
+2. Temporary CUDA staging when StorageManager provides CPU / pinned-memory
+   `MemoryObj` tensors.
+3. Key compression:
+   * FP8 key path for `turboquant_k8v4`.
+   * MSE / centroid low-bit key path for low-bit presets.
+4. Value uniform quantization.
+5. 3-bit or 4-bit bit-packing into a uint8 byte buffer.
+6. Metadata storage, including scale / zero for values and norm metadata when
+   required by the preset.
+
+The compressed output is written into the destination uint8 `MemoryObj`.
+
+## Decompression Path
+
+`TurboQuantDeserializer` launches Triton decode kernels to reconstruct KV
+tensors from compressed bytes.
+
+The load path performs:
+
+1. Serialized byte buffer validation.
+2. Temporary CUDA staging when StorageManager provides CPU / pinned-memory
+   `MemoryObj` tensors.
+3. Key unpacking and dequantization:
+   * FP8 key decode for FP8 presets.
+   * MSE / centroid decode for low-bit presets.
+4. Value unpacking and scale / zero dequantization.
+5. Restoration of the LMCache KV tensor layout:
+   `[2, num_layers, num_tokens, hidden_dim]`.
+
+The deserializer reconstructs KV tensors for storage reuse. It does not compute
+attention outputs.
+
+## Device Handling
+
+TurboQuant uses Triton kernels, so tensors participating in one kernel launch
+must be on the same CUDA device.
+
+Device selection follows these rules:
+
+1. If any source or destination tensor is already on CUDA, all CUDA tensors in
+   the same serde operation must be on the same device. Otherwise, TurboQuant
+   serde raises `ValueError`.
+2. If `cuda_device` is configured, that device is used as the staging device.
+   If CUDA tensors already exist, the configured device must match them.
+3. If all source and destination tensors are CPU tensors and `cuda_device` is
+   not configured, TurboQuant serde selects a CUDA device with sufficient free
+   memory and the lowest GPU utilization.
+4. CPU / pinned-memory tensors are staged to the selected CUDA working device
+   before Triton kernel execution and copied back afterward.
+
+This backend does not change LMCache runtime placement policy; the automatic
+selection only applies to CPU-only serde staging.
+
+## Relationship to vLLM TurboQuant
+
+The TurboQuant store/decode Triton kernel logic follows the implementation
+approach used by the vLLM TurboQuant PR. The integration target is different:
+
+* vLLM integrates TurboQuant into the attention backend.
+* LMCache integrates TurboQuant into the L2 serde path.
+
+In LMCache, TurboQuant is a storage transform only: it compresses objects before
+L2 store and reconstructs objects after L2 load / prefetch.
+
+## Performance Snapshot
+
+The following numbers are from a local H20 serde microbenchmark. They are
+intended as a sanity check for compression ratio, latency, and reconstruction
+error rather than full serving benchmark results.
+
+### Serde microbenchmark
+
+| Serde | Preset | Raw MB | Serialized MB | Compression ratio | Encode ms | Decode ms | Corr | Mean abs err | Max abs err |
+| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| fp8 | `float8_e4m3fn` | 8.00 | 4.00 | 2.00 | 0.024 | 0.040 | 0.999645 | 0.017948 | 0.250000 |
+| turboquant | `turboquant_k8v4` | 8.00 | 3.06 | 2.61 | 0.375 | 0.523 | 0.997342 | 0.051538 | 0.273438 |
+| turboquant | `turboquant_4bit_nc` | 8.00 | 2.09 | 3.82 | 0.554 | 0.642 | 0.995225 | 0.080693 | 0.505249 |
+| turboquant | `turboquant_k3v4_nc` | 8.00 | 1.84 | 4.34 | 0.555 | 0.642 | 0.989075 | 0.115782 | 0.970703 |
+| turboquant | `turboquant_3bit_nc` | 8.00 | 1.59 | 5.02 | 0.557 | 0.643 | 0.980405 | 0.164546 | 0.970703 |
+
+### Generation validation
+
+I also ran generation-based sanity checks to compare Base, vLLM Native
+TurboQuant, and the LMCache TurboQuant serde-only path.
+
+On a RULER-style 8K replay task, LMCache serde round2 is close to Base /
+Native TurboQuant across the tested presets:
+
+| Group | Preset | Accuracy |
+| --- | --- | ---: |
+| Base | none | 0.998 |
+| Native TQ | k8v4 | 0.998 |
+| Native TQ | 4bit_nc | 0.996 |
+| Native TQ | k3v4_nc | 0.982 |
+| Native TQ | 3bit_nc | 0.972 |
+| LMCache serde round2 | k8v4 | 0.992 |
+| LMCache serde round2 | 4bit_nc | 0.994 |
+| LMCache serde round2 | k3v4_nc | 0.982 |
+| LMCache serde round2 | 3bit_nc | 0.988 |
+
+For the follow-up correctness check, I used a smaller but more diagnostic
+CLBench subset instead of the full 163-case table.
+
+Subset construction:
+
+- First, I ran the bf16/fp16 baseline on the long-context CLBench samples.
+- Then I selected 64 samples where the baseline model scored highly. This avoids
+  cases where the base model itself fails, because those samples are not useful
+  for comparing KV-cache correctness.
+- Therefore, this subset is not meant to report absolute CLBench capability. It
+  is meant to compare relative correctness degradation between no-serde, native
+  TurboQuant, and LMCache TurboQuant serde on cases where the model can normally
+  answer.
+
+Metric:
+
+- I used the official CLBench-style rubric judge.
+- For each task:
+
+      task_score = passed_rubrics / len(rubrics[:50])
+
+- For each context:
+
+      context_score = mean(task_score over tasks in that context)
+
+- Final score:
+
+      avg_context_score = mean(context_score over contexts)
+
+This gives each context equal weight, so contexts with more tasks or more rubrics
+do not dominate the result.
+
+Results on the selected 64-sample subset:
+
+| Group | Preset | Avg context score |
+| --- | --- | ---: |
+| LMCache | no serde | 0.8343 |
+| Native TQ | 4bit_nc | 0.8073 |
+| Native TQ | k3v4_nc | 0.7669 |
+| Native TQ | 3bit_nc | 0.7647 |
+| LMCache serde | 4bit_nc | 0.7725 |
+| LMCache serde | k3v4_nc | 0.7628 |
+| LMCache serde | 3bit_nc | 0.8409 |
+
+The main point is that, after the serde fix, LMCache TurboQuant serde is in the
+same range as native TurboQuant and no-serde on this controlled subset.
+
+
+
+## Limitations
+
+This backend currently focuses on LMCache L2 serde integration. The main
+limitation is that the current path restores TurboQuant-compressed KV back to
+ordinary bf16 KV and then relies on the normal attention backend.
+
+This differs from vLLM Native TurboQuant, which computes attention directly in
+the rotated quantized space with its backend-specific layout and metadata. As
+shown in the generation validation above, this serde-only restore path can be
+reasonable for shorter replay-style tasks, but it is not yet robust for
+longer-context generation.
+
+A follow-up direction is to align LMCache TurboQuant more deeply with the
+serving backend semantics, including compressed KV layout, block/slot mapping,
+K/V-specific metadata, and the attention path, rather than treating TurboQuant
+only as an independent external serde format.
+
+## Tests
+
+The TurboQuant serde tests cover:
+
+* serde factory / processor creation
+* preset config parsing
+* invalid preset rejection
+* serialized size estimation
+* direct CUDA serialize / deserialize roundtrip
+* StorageManager roundtrip through serde-wrapped L2
+* filesystem-backed L2 roundtrip
+* reconstruction quality checks using correlation and error thresholds
+
+These tests validate the core LMCache L2 serde path. They do not claim
+serving-level performance speedups or task-level quality preservation.
diff --git a/docs/design/v1/distributed/transfer_channel/overall.md b/docs/design/v1/distributed/transfer_channel/overall.md
new file mode 100644
index 0000000..cc3c729
--- /dev/null
+++ b/docs/design/v1/distributed/transfer_channel/overall.md
@@ -0,0 +1,221 @@
+# Transfer Channel Design
+
+This document describes the **transfer channel** abstraction
+(`lmcache/v1/distributed/transfer_channel/`): its public API, how a read flows
+end to end, the nixl-backed implementation, and how to add a new implementation.
+
+It is intended for developers using the transfer channel to move L1 memory
+objects between peers, or implementing a new transport backend.
+
+## Purpose
+
+The transfer channel provides **peer-to-peer reads** of registered L1 memory.
+A peer registers its L1 buffer once, exchanges metadata with another peer during
+a handshake, and can then read arbitrary `(offset, size)` regions out of the
+remote peer's L1 buffer into its own. Only **reads** are supported today (a peer
+pulls data from a remote; it never pushes).
+
+The abstraction is transport-agnostic; the only implementation today is
+[`nixl`](#nixl-implementation) (RDMA/UCX via the NIXL bindings).
+
+## Architecture Overview
+
+```
+            ┌──────────────────────────────────────────────┐
+            │            TransferChannelContext              │
+            │  (one per peer; owns the transport + L1 reg.)  │
+            │                                                │
+            │  get_transfer_channel_server()  ── singleton ──┼──► TransferChannelServer
+            │  get_transfer_channel_client(peer_url) ────────┼──► TransferChannelClient (per peer)
+            │  remove_transfer_channel_client(peer_url)      │
+            │  get_transfer_channel_address([(off,size)…])   │
+            │  get_num_connected_clients()                   │
+            │  close()                                       │
+            └───────────────┬──────────────┬─────────────────┘
+                            │              │
+              one per ctx   │              │  one per remote peer
+                            ▼              ▼
+                ┌────────────────┐   ┌────────────────────────┐
+                │ ...Server      │   │ ...Client              │
+                │ handshake REP  │   │ submit_read(local,     │
+                │ (metadata only)│   │             remote)    │
+                │                │   │ query_read_status(id)  │
+                │                │   │ close()                │
+                └────────────────┘   └────────────────────────┘
+```
+
+Each peer constructs **one** `TransferChannelContext`. The context eagerly owns
+exactly one `TransferChannelServer` (bound at construction) and a set of
+`TransferChannelClient`s keyed by peer url, created lazily on first use.
+
+The context is also available as a **process-global singleton** through the
+package-level lifecycle functions (see [Global lifecycle](#global-lifecycle)),
+which is the normal entry point for application code.
+
+## Public API
+
+All names below are exported from
+`lmcache.v1.distributed.transfer_channel` (`__init__.py`).
+
+### Data types (`api.py`)
+
+| Type | Fields | Notes |
+|---|---|---|
+| `TransferChannelAddress` | `offset: int`, `size: int` | A transfer-channel address (frozen). `offset` is relative to the L1 base. Wrapped in a class for future extensibility. |
+| `TransferChannelReadResult` | `finished: bool`, `succeeded_mask: list[bool]` | Result of `query_read_status`. `is_finished()` accessor. `succeeded_mask` holds a per-object success flag aligned with the submitted addresses; empty while in flight. |
+
+### Abstract interfaces (`abstract.py`)
+
+- **`TransferChannelContext`** — owns the server and clients; translates L1
+  `(offset, size)` objects into transfer-channel addresses.
+  - `get_transfer_channel_server() -> TransferChannelServer`
+  - `get_transfer_channel_client(peer_advertise_url: str) -> TransferChannelClient`
+    — get or create a client to the peer. Note: for bidirectional transports
+    (like NIXL) the client may instead be created *passively* when the peer
+    dials this context's server; this is transparent to the caller.
+  - `remove_transfer_channel_client(peer_advertise_url: str) -> None`
+    — discard the peer's client when reads from it are no longer needed (e.g.
+    its owning L2 adapter is being removed) and free its resources. Outstanding
+    task ids for that client become invalid; a later
+    `get_transfer_channel_client` returns a fresh one. A no-op for an unknown
+    peer.
+  - `get_transfer_channel_address(lmcache_addresses: list[tuple[int, int]]) -> list[TransferChannelAddress]`
+    — validate `(offset, size)` pairs against the registered region and convert.
+  - `get_num_connected_clients() -> int`
+  - `close() -> None`
+- **`TransferChannelServer`** — listens for peer connections and exchanges
+  transfer metadata during the handshake. `close()` frees its resources.
+- **`TransferChannelClient`** — reads from one remote peer's memory.
+  - `submit_read(local_addresses, remote_addresses) -> int` — returns a task id.
+    The two address lists must have equal length; element *i* of `remote` is read
+    into element *i* of `local`.
+  - `query_read_status(task_id: int) -> TransferChannelReadResult`
+  - `close() -> None`
+
+### Global lifecycle (`__init__.py`)
+
+The normal way application code obtains a context:
+
+| Function | Purpose |
+|---|---|
+| `initialize_transfer_channel_context(transfer_channel_type, l1_memory_desc, listen_url, advertise_url, **kwargs)` | Create the process-global context via the registered factory. Raises if one already exists, or if the type is unknown. `**kwargs` are forwarded to the factory (e.g. `backends=["UCX"]` for nixl). |
+| `get_transfer_channel_context()` | Return the global context (raises if not initialized). |
+| `delete_transfer_channel_context()` | Close and clear the global context. |
+
+`listen_url` is the `host:port` this peer's singleton server binds to;
+`advertise_url` is the `host:port` this peer announces as its identity (the key
+peers store its reverse client under). `l1_memory_desc` is an
+`L1MemoryDesc(ptr, size, align_bytes)` (`distributed/internal_api.py`),
+typically obtained from `L1MemoryManager.get_l1_memory_desc()`.
+
+## How a read flows
+
+1. **Register.** Each peer builds a context, which registers its whole L1 buffer
+   with the transport and binds its handshake server.
+2. **Connect / handshake.** The reader calls
+   `get_transfer_channel_client(peer_url)`. If no client exists, the context
+   dials the peer's server and exchanges transport metadata (agent identity and
+   the serialized transfer-descriptor list covering the whole buffer).
+3. **Translate addresses.** Both sides express objects as `(offset, size)` pairs
+   relative to their own L1 base. The reader converts its **local**
+   (destination) addresses via `get_transfer_channel_address(...)`. **Remote**
+   (source) addresses are constructed directly as `TransferChannelAddress`
+   instances (they refer to the peer's region, so they are not validated against
+   the local region).
+4. **Submit + poll.** `submit_read(local, remote)` returns a task id; the caller
+   polls `query_read_status(task_id)` until `is_finished()`. The result's
+   `succeeded_mask` holds a per-object success flag aligned with the submitted
+   addresses (all `True` on success, all `False` on error).
+
+> **Alignment contract.** Object offsets must be aligned to the registered
+> `align_bytes`, and the reader and the peer must use the **same** `align_bytes`,
+> because the page-index math used to address the remote buffer is computed
+> against the reader's alignment but indexes the peer's page-granular descriptor
+> list.
+
+## nixl implementation
+
+`impl/nixl_impl.py` implements the abstraction over the NIXL bindings (UCX by
+default). It self-registers under the type name `"nixl"` at import time. Notable
+points:
+
+- **One agent per context.** The context creates a single `nixl_agent`, registers
+  the whole L1 buffer once, and builds a page-granular transfer-descriptor list
+  over `[base, base+size)` using `align_bytes` as the page size.
+- **Handshake over ZMQ.** Metadata is exchanged over a ZMQ `REP`/`REQ` socket
+  (not the LMCache MQ — that would be overkill and would leak transfer-channel
+  functions into the global MQ). The messages are a small `msgspec` tagged union
+  (`InitReq`/`InitResp`, `MemRegReq`/`MemRegResp`).
+- **Passive client creation.** When a peer dials this context's server and sends
+  its descriptor list, the server registers a reverse `NixlTransferChannelClient`
+  for that peer, so reads can flow in either direction after a single handshake.
+- **Address → page indices.** `addresses_to_indices` turns `(offset, size)` into
+  the list of page indices `[offset/align, …]`, expanding multi-page objects.
+- **Handshake timeout.** The dialing side sets a `RCVTIMEO` of
+  `_HANDSHAKE_TIMEOUT_MS` (60 s) on the handshake socket. A wrong/unreachable
+  url or a blocked port therefore raises a clear `TimeoutError` instead of
+  hanging forever. The server's `_serve_loop` polls with a 1 s timeout so it can
+  observe shutdown.
+
+## Extending: add a new transfer channel implementation
+
+Implementations live under `impl/` and **self-register a factory** with the
+registry in `factory.py`. There is no central switch statement to edit.
+
+1. **Implement the three interfaces** from `abstract.py`
+   (`TransferChannelContext`, `TransferChannelServer`, `TransferChannelClient`)
+   and use the `api.py` data types. Put the module under `impl/`. If it wraps a
+   third-party library, name the module after the *implementation*, not the
+   library it wraps (e.g. `nixl_impl.py`, not `nixl.py`, to avoid colliding with
+   the third-party `nixl` package).
+
+2. **Provide a factory and register it** at module import time:
+
+   ```python
+   from lmcache.v1.distributed.transfer_channel.factory import (
+       register_transfer_channel_factory,
+   )
+
+   def create_my_transfer_channel_context(
+       l1_memory_desc, listen_url, advertise_url, **kwargs
+   ):
+       return MyTransferChannelContext(...)
+
+   register_transfer_channel_factory("mytype", create_my_transfer_channel_context)
+   ```
+
+   The factory is always called with the keyword arguments `l1_memory_desc`,
+   `listen_url`, `advertise_url`, plus any implementation-specific keyword
+   arguments forwarded by the caller. Registering a duplicate type raises
+   `ValueError`.
+
+3. **Make the module import-loaded** so the registration runs. Add it to
+   `impl/__init__.py` (which the package `__init__.py` imports eagerly). Keep the
+   heavy/optional third-party import lazy (inside the context constructor), so
+   importing the module to register the factory does not require the dependency
+   to be installed.
+
+4. **Use it** via `initialize_transfer_channel_context("mytype", …)`. The
+   `transfer_channel_type` is a plain string identifier (not a module path); it
+   is resolved through the registry, and unknown types raise a `ValueError`
+   listing the registered types.
+
+`register_transfer_channel_factory` and the internal
+`create_transfer_channel_context` live in `factory.py` and are deliberately
+**not** part of the package's public `__all__` — implementations import the
+register function directly from `factory`, and `initialize_transfer_channel_context`
+is the public creation entry point.
+
+## Testing
+
+- Unit tests for the data types, factory registry, and global lifecycle:
+  `tests/v1/distributed/transfer_channel/test_api.py`,
+  `test_factory.py`, `test_context_lifecycle.py`.
+- Integration tests for the nixl implementation (guarded by
+  `pytest.importorskip("nixl")`, public interface only):
+  `tests/v1/distributed/transfer_channel/test_nixl_impl.py`.
+
+## Related
+
+- Throughput benchmark tool: `lmcache/tools/transfer_channel_benchmark/`
+  (design/usage symlinked at `docs/design/tools/transfer_channel_benchmark/`).
diff --git a/docs/design/v1/encoder-cache.md b/docs/design/v1/encoder-cache.md
new file mode 100644
index 0000000..c6ec569
--- /dev/null
+++ b/docs/design/v1/encoder-cache.md
@@ -0,0 +1,240 @@
+# Encoder Cache (EC) Design
+
+## Overview
+
+The **Encoder Cache (EC)** subsystem persists vLLM multimodal encoder
+outputs through LMCache's existing storage backends, so that encoder
+work performed for one request can be reused by future requests with
+the same multimodal inputs (e.g. an image referenced by the same hash
+in two chat completions).
+
+EC is a sibling of, not part of, the KV cache pipeline. It mirrors the
+KV engine's layering but with a much narrower contract: each entry is a
+single tensor keyed by a single `mm_hash`. There is no token chunking,
+no layerwise streaming, and no paged gather/scatter.
+
+---
+
+## Layering
+
+```
+        vLLM scheduler / worker
+                 │
+                 ▼
+   ┌──────────────────────────────┐    lmcache/integration/vllm/
+   │  LMCacheECConnectorImpl      │    vllm_ec_adapter.py
+   │  (vLLM ECConnectorBase glue) │
+   └──────────────────────────────┘
+                 │
+                 ▼
+   ┌──────────────────────────────┐    lmcache/v1/ec_engine.py
+   │  ECCacheEngine               │
+   │  - put(mm_hash, tensor)      │
+   │  - get(mm_hash, device)      │
+   │  - contains(mm_hash)         │
+   └──────────────────────────────┘
+                 │
+                 ▼
+   ┌──────────────────────────────┐    lmcache/v1/storage_backend/
+   │  StorageManager              │    storage_manager.py
+   │  (existing KV-cache plumbing)│
+   └──────────────────────────────┘
+                 │
+                 ▼
+        Local CPU / disk / remote / NIXL backends
+```
+
+The connector implements the vLLM `ECConnectorBase` API and is
+duplexed: scheduler-side methods (`has_cache_item`,
+`update_state_after_alloc`, `build_connector_meta`) and worker-side
+methods (`start_load_caches`, `save_caches`) live on the same class
+because vLLM's API requires it. The scheduler-only state
+(`_mm_hashes_need_loads`) is unused on worker-side instances.
+
+The engine is **transport-agnostic**: it speaks tensors and `mm_hash`
+strings. The adapter owns all knowledge of vLLM's `encoder_cache` dict,
+producer/consumer roles, and connector metadata.
+
+---
+
+## Cache Key
+
+EC uses the same `CacheEngineKey` type as KV, but with deliberately
+different field semantics:
+
+| Field          | KV cache                         | EC cache                              |
+|----------------|----------------------------------|---------------------------------------|
+| `model_name`   | model identity                   | model identity (same value)           |
+| `world_size`   | tensor-parallel world size       | sentinel `1`                          |
+| `worker_id`    | tensor-parallel rank             | sentinel `0`                          |
+| `chunk_hash`   | hash of token chunk              | `_stable_u64_from_str(mm_hash)`       |
+| `dtype`        | KV cache dtype (post-quant)      | encoder output dtype (model dtype)    |
+| `request_configs` | per-request config tags       | empty                                 |
+
+### Why sentinel `world_size` / `worker_id`
+
+Encoder outputs are **replicated across tensor-parallel ranks**: every
+TP rank computes the same encoder output for a given multimodal input.
+If we keyed EC entries by `worker_id` we would store N redundant copies
+on shared disk for TP=N. By collapsing to a single logical rank, all
+TP processes write to the same on-disk key. Concurrent puts are
+idempotent (identical contents).
+
+### Why the dtype is decoupled from `metadata.kv_dtype`
+
+If we used `metadata.kv_dtype` (the KV cache's quantization dtype) for
+the EC cache key, changing KV quantization settings (fp16 → fp8) would
+silently invalidate every EC entry on disk, even though encoder outputs
+have nothing to do with KV quant. The engine therefore takes
+`encoder_dtype` explicitly, sourced from `vllm_config.model_config.dtype`.
+
+---
+
+## Engine API
+
+The engine exposes three operations:
+
+```python
+def contains(self, mm_hash: str) -> bool: ...
+def put(self, mm_hash: str, tensor: torch.Tensor) -> bool: ...
+def get(self, mm_hash: str, device: str) -> Optional[torch.Tensor]: ...
+```
+
+- `put` returns `True` on successful submission to the storage manager,
+  `False` only on transient allocator pressure. It does not enforce
+  caller invariants (e.g. tensor presence) — it expects a real tensor.
+- `get` returns the tensor on a hit, `None` on a miss. The returned
+  tensor never aliases an LMCache-managed buffer; callers can keep it
+  indefinitely. The engine takes care of `ref_count_down` on every path,
+  including the `mem_obj is not None / mem_obj.tensor is None` case.
+
+This shape was chosen deliberately to keep return values
+unambiguous — a `False`/`None` return has exactly one meaning each, in
+line with the project's coding-standards rule against multi-meaning
+return values.
+
+---
+
+## Configuration
+
+EC engines accept overrides on top of the base LMCache config:
+
+| Source        | Prefix        | Example                                  |
+|---------------|---------------|------------------------------------------|
+| Environment   | `LMCACHE_EC_` | `LMCACHE_EC_CHUNK_SIZE=1024`             |
+| YAML key      | `ec_`         | `ec_local_disk: /tmp/ec-disk`            |
+| YAML map      | `ec:` nested  | `ec: { local_disk: /tmp/ec-disk }`       |
+
+Overrides land via `load_ec_engine_config()` in `lmcache/v1/config.py`,
+which clones the base `LMCacheEngineConfig` and applies the EC-prefixed
+keys. Unknown keys are logged and dropped — EC config is best-effort.
+
+EC can run with no explicit storage configuration: the loader
+unconditionally enables ``local_cpu`` and sets ``max_local_cpu_size``
+to 1 GiB if it is unset, so the engine always has somewhere to put
+data. The disk default is **conditional** — it only applies if the
+user has set a ``local_disk`` path. In that case ``max_local_disk_size``
+defaults to 64 GiB if not specified. Without an explicit ``local_disk``
+path EC entries live in CPU memory only and do not survive process
+restart; this is intentional, because picking an on-disk location for
+the user could overwrite or fill an unintended directory.
+
+---
+
+## Storage Format
+
+EC tensors are stored under `MemoryFormat.EC_TD` (token, dim). The
+StorageManager's allocator produces a pinned-CPU buffer which the
+engine's `put` populates with a single `copy_` from the source tensor —
+this handles GPU→CPU transfer and dtype casting in one step.
+
+Eviction policy and L1/L2/L3 routing follow the existing StorageManager
+defaults: EC entries participate in the same eviction queue as KV
+chunks unless an EC-specific override changes the relevant config.
+
+---
+
+## Concurrency Notes
+
+- All TP ranks may call `put` concurrently for the same `mm_hash`. This
+  is safe because (a) the on-disk key is identical and (b) the contents
+  are identical bytes; the storage backend simply overwrites with the
+  same payload.
+- `start_load_caches` is called once per scheduler step on the worker
+  side; it iterates the metadata's `mm_datas` and calls `engine.get`
+  for each, populating vLLM's `encoder_cache` only on hits.
+- The scheduler-side `_mm_hashes_need_loads` set is drained on every
+  `build_connector_meta` call; it does not persist across steps.
+
+---
+
+## Testing
+
+`tests/v1/test_ec_connector.py` exercises the full save → contains →
+load roundtrip through `LMCacheECConnectorImpl` against a real
+`StorageManager` backed by a temporary directory. The test depends on
+vLLM being importable and uses `pytest.importorskip("vllm")` at module
+top so it cleanly skips in environments where vLLM is not installed
+(e.g. the unit-test CI image).
+
+---
+
+## Design Decisions
+
+### Separate StorageManager from KV
+
+KV cache and EC cache each construct their own `StorageManager`. This
+is **intentional**, not an oversight to be cleaned up:
+
+- KV and EC have very different access patterns. KV is chunked,
+  layerwise, and high-throughput; EC is single-tensor, request-scoped,
+  and far lower-volume. Mixing them in one allocator pool and
+  eviction queue lets hot KV chunks evict cold-but-valuable EC
+  entries (or vice versa) in non-obvious ways.
+- Resource budgeting becomes auditable: an operator can size local
+  CPU and disk pools per workload (`max_local_cpu_size`,
+  `max_local_disk_size` for KV; `ec_max_local_cpu_size`,
+  `ec_max_local_disk_size` for EC) without one cache cannibalizing
+  the other.
+- The price is one extra background event-loop thread per process,
+  and modest duplication of allocator metadata. Both are negligible
+  next to the determinism gain.
+
+If a future workload genuinely benefits from shared pools, the
+mechanism would be: pass an externally-constructed `StorageManager`
+into `ECCacheEngine.__init__` (DI), instead of having the engine
+construct one. Today no caller wants that.
+
+### Role pinned to `"worker"` for the storage manager
+
+vLLM's `ECConnectorBase` multiplexes scheduler-side and worker-side
+methods onto a single class with a `role` discriminator. Naively one
+would forward that role to `create_lmcache_metadata` so LMCache can
+size resources per role. **We deliberately do not** — the EC connector
+calls `create_lmcache_metadata(vllm_config, role="worker")` regardless
+of the vLLM-side role.
+
+The reason: scheduler-side `has_cache_item` calls `engine.contains()`,
+which needs a fully constructed `StorageManager` (including
+`LocalCPUBackend`, since `LocalDiskBackend` is layered on top of it).
+LMCache's `CreateStorageBackends` short-circuits the CPU backend when
+`metadata.role == "scheduler"` and then asserts on it for the disk
+backend — so threading the real role aborts startup with an
+`AssertionError`. Until LMCache grows a scheduler-friendly storage
+path (or EC splits scheduler/worker into separate engines), the
+connector keeps the role pinned to `"worker"`.
+
+`_mm_hashes_need_loads` is scheduler-only state; it is initialized on
+both roles for simplicity but only mutated/read on the scheduler side.
+
+## Future Work
+
+- **Encoder dtype on metadata.** `LMCacheMetadata` does not yet carry
+  an `encoder_dtype` field; the connector currently passes
+  `vllm_config.model_config.dtype` directly to `ECCacheEngine.__init__`.
+  If more producers (sglang, etc.) gain encoder caches, lifting the
+  field onto `LMCacheMetadata` would let the engine become connector-
+  agnostic.
+- **Public connector-metadata accessor in vLLM.** `start_load_caches`
+  reaches into `self._parent._get_connector_metadata()`; once vLLM
+  exposes a public method, drop the `# noqa: SLF001`.
diff --git a/docs/design/v1/gpu_connector/layout-invariant.md b/docs/design/v1/gpu_connector/layout-invariant.md
new file mode 100644
index 0000000..ddf7de9
--- /dev/null
+++ b/docs/design/v1/gpu_connector/layout-invariant.md
@@ -0,0 +1,270 @@
+# GPU KV Cache Layout — Single Source of Truth
+
+## Invariant
+
+> **`normalize_kv_and_discover_format` is the only place that parses
+> KV-cache layout.** It also returns the canonical (post-permute) form
+> of the kv_caches alongside the format, so callers never need a
+> separate normalization step. Every other module queries KV-cache
+> information via helpers in `lmcache/v1/gpu_connector/utils.py` that
+> accept an `EngineKVFormat` argument.
+
+"Layout parsing" means: list-nesting depth, tensor-dimension ordering,
+HND vs NHD, MLA vs MHA, per-layer vs cross-layer. All of that is
+encoded in `EngineKVFormat`; downstream code must never re-derive it
+from raw shapes.
+
+## Canonical type
+
+```python
+DiscoverableKVCache = Union[torch.Tensor, list["DiscoverableKVCache"]]
+```
+
+Every KV-cache value in LMCache is one of these shapes:
+
+- a single `torch.Tensor` (vLLM cross-layer, TRT-LLM),
+- a flat `list[torch.Tensor]` (vLLM per-layer, SGLang MLA),
+- a nested `list[list[torch.Tensor]]` (SGLang MHA's `[K_list, V_list]`).
+
+Engine adapters that hand us other containers (vLLM's `dict[str, Tensor]`)
+are responsible for unwrapping to this form before calling any helper.
+
+## Package structure
+
+The layout logic lives in `lmcache/v1/gpu_connector/kv_format/`. The
+public `utils.py` helpers below are a thin **facade** that delegates
+into it, so the single-source-of-truth surface is unchanged for callers.
+
+```
+kv_format/
+├── types.py       # DiscoverableKVCache, LayoutHints (foundational types)
+├── contiguity.py  # attempt_permute_to_contiguous_view (zero-copy view recovery)
+├── detection.py   # detect_format() orchestration
+├── specs/         # geometry layer
+│   ├── base.py    #   KVFormatSpec ABC + shape_desc/concrete_shape rendering
+│   ├── registry.py #  auto-discovers the spec files; get_spec/get_spec_class
+│   └── <engine_kv_format>.py  #   one file per format
+└── detectors/     # per-engine detection layer
+    ├── base.py    #   EngineDetector ABC + measure_structure()
+    ├── registry.py #  auto-discovers the detector files; get_detector
+    └── <engine>.py            #   one file per engine (a single discover())
+```
+
+- **One spec class per format — pure geometry.** Each `EngineKVFormat`
+  maps to exactly one `KVFormatSpec` subclass that knows how to index a
+  value of that format. A spec describes *only* layout geometry; both the
+  class and its file are named after the format member (e.g.
+  `NB_NL_TWO_BS_NH_HS_Spec` in `nb_nl_two_bs_nh_hs.py`) — a geometry
+  encoding, never an engine. `get_spec(kv, fmt)` returns an instance for
+  geometry; `get_spec_class(fmt)` returns the class for static facts
+  (`is_mla`, `is_hnd`, `is_cross_layer`, `attention_backends`).
+- **Backend labels are diagnostic, colocated on the spec.** A single
+  `EngineKVFormat` can be produced by several (engine, attention-backend)
+  combinations, so each spec lists them in `attention_backends` (a tuple),
+  first entry = canonical representative. `get_attention_backend(fmt)` (the
+  `utils` facade) returns that first entry for logging. These labels are
+  diagnostic only — they never drive geometry decisions, and they replace
+  the old hand-maintained `EngineKVFormat → label` dict.
+- **The enum is the single identity.** Each spec declares its
+  `engine_kv_format` in its class body; the registry is derived from it.
+  No separate string id, no engine attribute. The C++ `EngineKVFormat`
+  enum is the one authority for which formats exist. Its **member name is
+  the layout legend** — a `_`-joined token sequence where `X` marks a
+  list-nesting boundary (`TWO_X_NL_X_NBBS_NH_HS` → `2 x NL x [PBS, NH, HS]`).
+  The symbolic `shape_desc(fmt)` and numeric `concrete_shape(fmt, size)` are
+  both *rendered* from that name (`specs/base.py`), so they cannot drift from
+  the enum or from each other.
+- **One file per spec; auto-discovered in one place.** Each spec lives in its
+  own `specs/<engine_kv_format>.py` (named after the format it implements).
+  `specs/registry.py` imports every file in the folder and indexes each spec by
+  the `engine_kv_format` it declares, into the `SPECS` table that `get_spec` /
+  `get_spec_class` look up. Adding a format = just drop a new file; the
+  discovery is one readable loop in `registry.py` (no `__init_subclass__`, no
+  registration scattered across files). There is no inheritance taxonomy:
+  "family" base classes are avoided (formats vary on ≥5 orthogonal axes —
+  engine, per-/cross-layer, MLA/MHA, NHD/HND, fused/separate PBS — which a
+  single inheritance spine cannot model without orphans). Add structure only
+  when a concrete need appears.
+- **Detection is the one engine-aware layer.** `detect_format` does the
+  engine-agnostic contiguous-view recovery, then dispatches to the
+  `EngineDetector` for the `EngineType`. Each `detectors/<engine>.py` is one
+  `discover(kv, hints)` that reshapes the engine's raw layout into canonical
+  form *and* identifies the format in one step (returning `(format, kv)`);
+  `detectors/registry.py` auto-discovers them the same way `specs/` does. The
+  spec layer never sees `EngineType`. Adding an engine = just drop a new
+  detector file.
+
+## Adding a new format
+
+1. Add the enum value in `csrc/kv_transfer_types.h` (the single
+   backend-agnostic definition shared by every accelerator backend), then
+   register it in each backend's pybind module — `csrc/pybind.cpp` (CUDA)
+   and `csrc/sycl/pybind_sycl.cpp` (SYCL/XPU).
+2. Add a branch in the engine's `detectors/<engine>.py` `discover()`. It keys
+   off `(list_depth, tensor_ndim)` from `measure_list_depth_until_tensor`,
+   returning `(format, kv)`; any reshape-via-hints (e.g. TRT-LLM's 4-D `view`'d
+   to 6-D) happens in the same method before the shape checks.
+3. Add a `KVFormatSpec` subclass as a new `specs/<engine_kv_format>.py` file
+   (named after the format, declaring its `engine_kv_format`). `registry.py`
+   discovers it automatically — no other file changes. The ABC makes the
+   required accessors explicit (a spec missing one raises `TypeError` on first
+   `get_spec`, which the golden test triggers).
+4. Add a row to the golden table in
+   `tests/v1/gpu_connector/test_kv_format_specs.py` and a detection
+   case in `test_kv_format_detection.py`.
+
+No other Python module should need edits. If you're editing
+`kv_layer_groups.py`, `gpu_context.py`, or any `KVLayerGroupInfo`
+consumer for a new layout — the branching belongs in a spec.
+
+## Helper surface
+
+Every helper below takes `DiscoverableKVCache` and (where layout matters)
+an `EngineKVFormat`. Nothing else may index raw shapes.
+
+### Discovery
+
+| Helper | Returns |
+|---|---|
+| `normalize_kv_and_discover_format(kv_caches, engine, layout_hints)` | `tuple[EngineKVFormat, DiscoverableKVCache]` — the one parser. Returns the canonical (permuted-to-contiguous) kv_caches alongside the detected format; callers must use the returned tensor structure for subsequent operations. |
+
+### Format → engine map
+
+| `EngineKVFormat` | Engine | Layout | Structure |
+|---|---|---|---|
+| `NB_NL_TWO_BS_NH_HS` | vLLM cross-layer | NHD | bare 6-D tensor `[NB, NL, 2, BS, NH, HS]` |
+| `NB_NL_TWO_NH_BS_HS` | TRT-LLM cross-layer | HND | bare 6-D tensor `[NB, NL, 2, NH, BS, HS]` |
+| `NL_X_TWO_NB_BS_NH_HS` | vLLM flash-attn | NHD | `NL × [2, NB, BS, NH, HS]` |
+| `NL_X_NB_TWO_BS_NH_HS` | vLLM flash-infer | NHD | `NL × [NB, 2, BS, NH, HS]` |
+| `NL_X_TWO_NB_NH_BS_HS` | vLLM flash-attn | HND | `NL × [2, NB, NH, BS, HS]` |
+| `NL_X_NB_TWO_NH_BS_HS` | vLLM flash-infer | HND | `NL × [NB, 2, NH, BS, HS]` |
+| `NL_X_NB_BS_HS` | vLLM MLA | — | `NL × [NB, BS, HS]` |
+| `TWO_X_NL_X_NBBS_NH_HS` | SGLang MHA | NHD | `[K_list, V_list]`, each `NL × [PBS, NH, HS]` |
+| `TWO_X_NL_X_NB_BS_NH_HS` | SGLang MHA via MP daemon | NHD | `[K_list, V_list]`, each `NL × [NB, BS, NH, HS]` |
+| `NL_X_NBBS_ONE_HS` | SGLang MLA | — | `NL × [PBS, 1, HS]` |
+| `NL_X_NB_NH_BS_TWO_HS` | vLLM blocks-first fused (CPU) | HND | `NL × [NB, NH, BS, 2, HS]`, split from raw `[NB, NH, BS, 2·HS]` |
+
+The two cross-layer formats (`NB_NL_TWO_*`) share a single base
+pointer, the kernel walks layers internally via `shape_desc.nl`. Use
+`is_cross_layer_format(fmt)` for that dispatch and `is_hnd(fmt)` to
+detect head-major within-block layouts.
+
+### Reshape-via-hints (TRT-LLM)
+
+TRT-LLM hands LMCache a 4-D pool tensor
+`[NB, NL, 2, num_kv_heads * tokens_per_block * head_dim]` (HND, K and V
+interleaved on dim 2). `normalize_kv_and_discover_format` reshapes it
+to canonical 6-D form *before* the contiguity check, using
+`layout_hints["num_kv_heads" | "tokens_per_block" | "head_dim"]`. The
+function also collapses a 1-element list of a 6-D tensor down to the
+bare 6-D tensor so detection lands on `list_depth == 0`. Adapters pass
+either the 4-D bare tensor or `[4-D]`; the function handles both.
+
+### Scalar accessors
+
+All of these dispatch on `EngineKVFormat`. The ones that can vary per layer
+take an optional `layer_idx: int = 0`; passing an explicit index enables
+per-layer queries (for heterogeneous groups) without any intermediate
+helper.
+
+| Helper | Per-layer? | Notes |
+|---|---|---|
+| `get_num_layers(kv, fmt)` | no | Total layer count. |
+| `get_num_blocks(kv, fmt)` | no | Paged block count (group-level). |
+| `get_block_size(kv, fmt)` | no | Tokens per block. |
+| `get_page_buffer_size(kv, fmt)` | no | |
+| `get_tokens_per_layer(kv, fmt)` | no | |
+| `get_elements_per_layer(kv, fmt)` | no | |
+| `get_num_heads(kv, fmt, layer_idx=0)` | yes | |
+| `get_head_size(kv, fmt, layer_idx=0)` | yes | |
+| `get_hidden_dim_size(kv, fmt, layer_idx=0)` | yes | |
+| `get_dtype(kv, fmt, layer_idx=0)` | yes | |
+| `is_mla(fmt)`, `is_hnd(fmt)` | — | Format predicates. |
+| `get_device(kv)` | — | Format-agnostic (descends to any leaf). |
+
+### Pointer and descriptor builders
+
+| Helper | Returns | Notes |
+|---|---|---|
+| `get_group_data_ptrs(kv, fmt, layer_indices)` | `list[int]` | Pointer array in **kernel-expected order**: `[base]` for cross-layer (`layer_indices` ignored), `[K_0…K_N, V_0…V_N]` for SGLang MHA, per-layer flat elsewhere. Matches the dispatch in `csrc/mp_mem_kernels.cu:161-169`. The pointer-array shape is a property of the format — callers never ask "does this format have per-layer pointers?". |
+| `make_page_buffer_shape_desc(kv, fmt, layer_idx, num_layers_in_group, num_blocks, block_size, block_stride_elems)` | `PageBufferShapeDesc` | The kernel-facing shape struct. ``block_stride_elems`` carries the per-block dim-0 element stride; pass the value returned by `resolve_block_stride_and_log_layout` so groups with different physical block sizes (e.g. a compressed DeepSeek V4 indexer group alongside dense layers) share a single GPU pool. |
+
+### Contiguity
+
+| Helper | Returns | Notes |
+|---|---|---|
+| `attempt_permute_to_contiguous_view(kv)` | `DiscoverableKVCache` | Recursive, metadata-only. No-op if already contiguous; raises `ValueError` for non-permutation-recoverable cases (slicing, `as_strided`). **Never copies.** Walks the full structure and permutes every tensor leaf. Called internally by `normalize_kv_and_discover_format`; remains public only for callers that handle a tensor *outside* the discover flow (`GPUConnectorInterface.initialize_kvcaches_ptr`, `CudaIPCWrapper.__init__`). |
+
+## Forbidden in consumer code
+
+Raw-shape indexing belongs inside the `kv_format` layer (the spec classes);
+consumer code must never do any of the following — it queries via the
+`utils.py` facade instead:
+
+- `isinstance(kv_cache, (tuple, list))` to distinguish layouts.
+- Indexing raw shapes (`tensor.shape[3]`, `len(shape) == 5`) to derive
+  dimensions.
+- Hand-rolled list-depth probing (`while isinstance(x, list): depth +=
+  1; x = x[0]`). There is no public depth helper and there shouldn't
+  be one — `normalize_kv_and_discover_format` encapsulates the
+  descent, and downstream code only ever needs the resulting
+  `EngineKVFormat`.
+- Wrapping a tensor with `[tensor]` to adapt to a helper's list-depth
+  expectation — the accessors take `layer_idx` directly.
+- Hand-rolled pointer assembly (`[t.data_ptr() for t in kv_caches]`) —
+  use `get_group_data_ptrs`.
+- Hand-rolled device discovery (`kv_caches[0][0].device`) — use
+  `get_device`.
+- Hand-rolled contiguity fixes (`tensor.contiguous()`, `.clone()`) —
+  use `attempt_permute_to_contiguous_view` which refuses to copy.
+- "Canonicalize" functions that rewrite `kv_caches` to a uniform shape
+  before passing to helpers. The helpers already canonicalize by
+  accepting `EngineKVFormat`, and any reshape/normalize step that *is*
+  needed lives inside `normalize_kv_and_discover_format` — callers
+  receive the canonical form back from that one call.
+
+## Consumers
+
+- **`lmcache/v1/kv_layer_groups.py::KVLayerGroupsManager.__init__`** —
+  partitions layers by the 5-tuple `(kv_size, num_heads, head_size,
+  block_size, dtype)` using `is_mla`, `get_num_heads`, `get_head_size`,
+  `get_block_size`, and `get_dtype` with each layer's index. Including
+  `block_size` in the identity lets compressed groups (e.g. a DeepSeek
+  V4 indexer with a smaller physical slot count) sit alongside
+  non-compressed groups under a single `GPUCacheContext`. Builds a
+  `PageBufferShapeDesc` per group via `make_page_buffer_shape_desc`,
+  passing the `block_stride_elems` resolved by
+  `resolve_block_stride_and_log_layout`. The real constructor is the
+  only way in — no test-only shortcuts, no cached topology fields; the
+  manager exposes only `kv_layer_groups`, `num_groups`, and
+  `get_shape_desc`.
+- **`lmcache/v1/platform/cuda/cache_context.py::GPUCacheContext`** —
+  constructs the manager directly at init, delegates
+  `get_shape_desc(group_idx)` to it, assembles per-group GPU pointer
+  tensors via `get_group_data_ptrs`. No parallel `shape_descs_` /
+  `hidden_dim_sizes_` state.
+- **`lmcache/v1/gpu_connector/gpu_connectors.py::VLLMPagedMemGPUConnectorV3._initialize_kv_cache_pointers`**
+  — for the in-process vLLM path, calls
+  `normalize_kv_and_discover_format` (which permutes for HND support
+  and detects the format in one step) and constructs
+  `metadata.kv_layer_groups_manager` lazily on first store/retrieve.
+  The adapter (`vllm_v1_adapter.py`) does not participate in format
+  discovery — it only stores `self.kv_caches` at register time.
+
+Only `normalize_kv_and_discover_format` consumes `layout_hints`.
+`attempt_permute_to_contiguous_view` (called internally) infers the
+permutation from strides and needs no hints.
+
+## Implementation note: mypy and the recursive union
+
+Format-dispatched raw indexing on `DiscoverableKVCache`
+(`kv_caches.shape[i]`, `kv_caches[0][j]`) is concentrated in the
+`kv_format` layer: each `specs/<format>.py` sets
+`# mypy: disable-error-code="union-attr,call-overload"` at the file level
+(the `detectors/` and `contiguity.py` files use `union-attr` alone, and the
+`utils.py` facade keeps the directive for its remaining structural helpers). The
+`engine_kv_format` — or, in a spec, the class identity itself — is the
+proof the indexing is well-defined, but mypy can't carry that proof
+through a recursive Union without per-line casts. The file-level directive
+replaces scattered `# type: ignore` comments; all other type checks remain
+live.
diff --git a/docs/design/v1/hidden_state_store.md b/docs/design/v1/hidden_state_store.md
new file mode 100644
index 0000000..2e964f1
--- /dev/null
+++ b/docs/design/v1/hidden_state_store.md
@@ -0,0 +1,109 @@
+# HiddenStateStore
+
+`HiddenStateStore` is an LMCache-internal store dedicated to caching per-token
+hidden-state tensors next to KV chunks. It exists to support any system where
+we may need to draw out intermediate activations from an inference forward
+pass (e.g. vLLM-Omni thinker -> talker) where a downstream stage needs the
+upstream stage's intermediate activations for the cached prefix and cannot
+reconstruct them from KV alone.
+
+## Goals
+
+- Keep KV cache logic and hidden-state cache logic in **separate classes**.
+  `LMCacheEngine` owns one instance and exposes it via
+  `engine.hidden_state_store`, but does not embed hidden-state state in
+  itself.
+- Use a **separate pinned CPU memory pool** so that hidden-state allocations
+  cannot fragment the KV pool. KV tensors and intermediate activations have
+  **heterogeneous shapes** (KV is per-layer `[num_tokens, 2, head_dim]`-style
+  while hidden states / other activations are typically
+  `[num_tokens, hidden_dim]` and may differ in dtype and per-layer count), so
+  packing them into a shared allocator would either waste space or force
+  one cache to evict the other under pressure.
+- **Reuse** existing chunking and key generation
+  (`ChunkedTokenDatabase.process_tokens` -> `CacheEngineKey`) so each hidden
+  chunk is keyed identically to its KV counterpart.
+- Implement the **coupled-but-asymmetric** eviction rule:
+  - KV evicted -> HS for that chunk is dropped on the next access.
+  - HS evicted -> KV stays.
+  - Restore stops at the first chunk where HS is missing.
+
+## Class layout
+
+```
+LMCacheEngine
+  - storage_manager       (KV: LocalCPUBackend + LocalDiskBackend + ...)
+  - hidden_state_store    (HiddenStateStore, owns its own pinned pool)
+       - _allocator       (MixedMemoryAllocator, independent buffer)
+       - _chunks: dict[CacheEngineKey, dict[layer_idx, MemoryObj]]
+       - _lru:    OrderedDict[CacheEngineKey, None]
+```
+
+`HiddenStateStore` does not depend on `StorageManager` for storage. It does
+hold a reference to the storage manager (set via `bind_storage_manager()`) so
+that on retrieve it can ask "is KV still here for this key?" via
+`storage_manager.contains(key)`.
+
+## Public API
+
+Integrators call these methods on **`engine.hidden_state_store`** when it is
+not `None` (when `config.enable_hidden_state_cache` is `True`). They are not
+methods on `LMCacheEngine`. Callers **must** check for `None` themselves (same
+pattern as vLLM-Omni ``OmniGPUModelRunner``: skip store/retrieve when HS
+caching is disabled).
+
+`HiddenStateStore`:
+
+- `store_hidden_states(token_ids, hidden_states, *, layer_idx=0) -> int`
+  Chunks `token_ids` with the engine's `token_database`, copies the matching
+  rows of `hidden_states` into pinned memory under the KV chunk key, returns
+  the number of chunks stored.
+- `retrieve_hidden_states(token_ids, *, layer_idx=0) -> torch.Tensor | None`
+  Walks chunks of `token_ids` in order. Stops at the first chunk where
+  either KV is missing (lazy coupled-eviction cleanup) or HS is missing
+  (prefix-strict). Returns the contiguous prefix tensor or `None` for a
+  full miss.
+- `close()`
+  Frees the pinned pool.
+
+Multi-layer payloads are handled by invoking `store_hidden_states` once per
+distinct `layer_idx` (and `retrieve_hidden_states` per layer on restore).
+
+When `enable_hidden_state_cache` is `False`, `engine.hidden_state_store` is
+`None`; callers must omit HS APIs on that worker.
+
+## Eviction (lazy coupled-check)
+
+- HS-only allocator pressure: `HiddenStateStore` evicts its own LRU entry
+  and retries; KV is never touched.
+- KV evictions are **not** observed eagerly. Instead, on every retrieve we
+  ask `storage_manager.contains(key)`. If KV is gone for a chunk we hold HS
+  for, we drop that HS entry and stop the prefix there.
+
+This keeps the engine surface tiny (no callbacks, no shared index) while
+still satisfying:
+
+- KV evict implies HS evict (next read drops the orphan).
+- HS evict does not imply KV evict.
+- Restore stops at first missing HS *or* missing KV chunk.
+
+## Configuration
+
+All four fields already exist in `LMCacheEngineConfig` (PR 1330). The pool
+size **is** the new pool size; no extra field is required:
+
+| Field                             | Meaning                                                         |
+| --------------------------------- | --------------------------------------------------------------- |
+| `enable_hidden_state_cache`       | Master toggle. When `False`, `engine.hidden_state_store` is `None`; integrators gate store/retrieve on this field before calling HS APIs. |
+| `max_hidden_state_cpu_size` (GB)  | Independent pinned-CPU pool size for the HS allocator.          |
+| `hidden_state_layers`             | Optional allowlist of `layer_idx` values accepted on store.     |
+
+Retrieve always stops at the first chunk without KV or without HS for the requested layer (prefix-strict); there is no alternate assembly mode.
+
+## Why lazy eviction (not callbacks)
+
+- No invasive changes to `LocalCPUBackend` or any cache policy.
+- Works uniformly for any backend that implements `contains()` (LocalCPU,
+  LocalDisk, remote, etc.).
+- The cost is one extra `contains()` call per chunk on retrieve, which is a
+  cheap dict lookup for the local case.
diff --git a/docs/design/v1/mp_coordinator/README.md b/docs/design/v1/mp_coordinator/README.md
new file mode 100644
index 0000000..ec011f0
--- /dev/null
+++ b/docs/design/v1/mp_coordinator/README.md
@@ -0,0 +1,163 @@
+# MP Coordinator
+
+The mp coordinator is a standalone **FastAPI / REST** process that coordinates
+LMCache multi-process (mp) cache servers running across nodes as a fleet. This
+document describes the backbone: the REST API, the instance registry, and the
+health-check loop. Domain capabilities (quota reconcile, blend-lookup routing,
+KV-op fan-out) are not implemented yet; they are added as new REST routers.
+
+Code: `lmcache/v1/mp_coordinator/`.
+
+## Why
+
+mp servers are independent today: quota is per-instance and in-memory, there is
+no cross-node token-match routing for model replicas, and KV operations are
+local. The coordinator is the fleet-level component those features will hang
+off. This PR ships the framework plus membership so future work plugs in
+without re-architecting.
+
+## Transport
+
+The coordinator is a FastAPI app served by uvicorn. mp servers register /
+heartbeat / deregister over REST.
+
+| Method & path | Direction | Purpose |
+| --- | --- | --- |
+| `POST /instances` | mp → coordinator | register (or re-register) |
+| `PUT /instances/{id}/heartbeat` | mp → coordinator | heartbeat (404 ⇒ re-register) |
+| `DELETE /instances/{id}` | mp → coordinator | deregister (idempotent, 204) |
+| `GET /instances` | operator/tools | list the fleet |
+| `GET /healthz` | k8s probe | liveness |
+
+For server-initiated work (future quota reconcile, KV-op fan-out) a coordinator
+router resolves an instance's address from the registry (`ip` + `http_port`) and
+POSTs to that mp server's **specific** existing endpoint (e.g. `/pin`,
+`/quota`). There is no generic command channel and no per-instance connection
+state — just an HTTP call to the relevant resource.
+
+## Layout
+
+```
+lmcache/v1/mp_coordinator/
+  app.py            # create_app + lifespan + router discovery + health eviction
+  __main__.py       # uvicorn entrypoint
+  config.py         # MPCoordinatorConfig (LMCACHE_MP_COORDINATOR_*)
+  registry.py       # InstanceRegistry + MPInstance (pure membership)
+  schemas.py        # Pydantic request/response models (shared wire contract)
+  registrar.py      # mp-server-side register/heartbeat/deregister helpers
+  http_apis/
+    instances_api.py  # the /instances REST resource
+    health_api.py     # /healthz
+```
+
+## Request flow
+
+Registration, end to end:
+
+```mermaid
+sequenceDiagram
+    participant C as mp server
+    participant API as POST /instances
+    participant Reg as InstanceRegistry
+
+    C->>API: POST /instances {instance_id, ip, http_port}
+    API->>API: validate JSON body
+    API->>Reg: register(MPInstance(...))
+    API-->>C: 200 {instance_id, re_registered}
+```
+
+Heartbeat is `PUT /instances/{id}/heartbeat` → `registry.update_heartbeat`; a
+404 tells the client to re-register. The health loop (in `app.py`, started by
+the lifespan) evicts instances whose heartbeat lapsed. Future server push
+resolves the address (`ip` + `http_port`) from the registry and calls the mp
+server's specific endpoint directly:
+
+```mermaid
+sequenceDiagram
+    participant Ctl as future router
+    participant Reg as InstanceRegistry
+    participant M as mp server HTTP API
+
+    Ctl->>Reg: get(instance_id) -> ip, http_port
+    Ctl->>M: POST http://ip:http_port/<resource> (e.g. /pin)
+    M-->>Ctl: 200 JSON
+```
+
+## Extension seam (adding a capability)
+
+`app.state` carries the **shared collaborators** every capability composes from:
+`config` and `registry`. Endpoints use them directly — membership is thin enough
+to have no service layer (the `/instances` router calls the registry straight,
+matching the mp server's own `http_apis` convention).
+
+To add a capability (e.g. quota):
+
+1. `http_apis/quota_api.py` — a module-level `router` (FastAPI `APIRouter`).
+   `create_app` auto-discovers it (via `lmcache/v1/utils/router_discovery.py`,
+   the same convention as the mp server's HTTP API). No edits elsewhere for the
+   route to appear; the router reads `app.state.registry`, and to push it
+   resolves an instance's `ip`/`http_port` and POSTs to that mp server's
+   endpoint.
+2. Only if the domain has real logic/state of its own (e.g. quota: persistence,
+   broadcast-on-join) add a `quota_service.py` over the shared collaborators and
+   stash it on `app.state` in `create_app`. Thin domains skip this.
+
+A capability that must react to instance join/leave can hook into the
+registration endpoint (a small observer can be reintroduced then — it was
+dropped from the backbone as it had no consumer yet).
+
+> **Notice — keep request handlers non-blocking.** Endpoints run on the event
+> loop. Heavy work (pushing to mp servers, store reads) must be `await`ed on
+> async clients or scheduled as a task (`asyncio.create_task`), and CPU-bound
+> work sent to a thread (`run_in_executor`), so request latency and the health
+> loop are not blocked.
+
+## Registry (`registry.py`)
+
+`InstanceRegistry` maps `instance_id` → `MPInstance` (ip, http_port,
+heartbeat timestamps, metadata). Membership is pure — no sockets, no model or
+parallel-config info — so a server hosting several models is represented
+correctly; model-aware indexing belongs to a future routing router. Thread-safe
+(`threading.Lock`); `stale()` uses a monotonic clock so an NTP step cannot skew
+liveness.
+
+## Concurrency & lifecycle
+
+- Everything runs on the uvicorn event loop; the registry lock guards the one
+  piece of shared state.
+- The health-check loop is an asyncio task started in the app lifespan; it
+  evicts instances whose heartbeat lapsed (`instance_timeout`) and is cancelled
+  on shutdown. `health_check_interval = 0` disables it.
+- Registration is idempotent: re-registering replaces the entry. The registry
+  is ephemeral — rebuilt from heartbeats after a coordinator restart; durable
+  state (quota) belongs in an external store (Redis), not here.
+
+## Running
+
+```
+lmcache coordinator [--host HOST] [--port PORT] \
+    [--instance-timeout SECS] [--health-check-interval SECS]
+```
+
+(or, equivalently, `python -m lmcache.v1.mp_coordinator`).
+
+Configured via `LMCACHE_MP_COORDINATOR_*` environment variables — see
+`MPCoordinatorConfig` in `config.py` (`HOST`, `PORT`, `INSTANCE_TIMEOUT`,
+`HEALTH_CHECK_INTERVAL`). The `lmcache coordinator` CLI flags override the
+matching env-derived field; unset flags fall back to the env vars and then the
+config defaults.
+
+An mp server joins via the `registrar.py` helpers — no dedicated client object,
+mirroring how the coordinator just calls mp endpoints. The mp server's FastAPI
+lifespan creates a generic `httpx.AsyncClient` and launches `keep_registered()`
+as a task: it `POST`s `/instances`, `PUT`s `/instances/{id}/heartbeat` on a
+timer, and `DELETE`s on cancellation — on the mp server's own event loop, using
+the shared `schemas` models. It is wired into
+`lmcache/v1/multiprocess/http_server.py`'s lifespan and configured by a
+`CoordinatorConfig` (`lmcache/v1/multiprocess/config.py`), built from
+`--coordinator-*` flags that fall back to `LMCACHE_COORDINATOR_*` env vars. It is
+**opt-in**: with no coordinator URL, the mp server is unaffected. It is
+best-effort — failures are logged and retried (a down coordinator never blocks
+the server), while a malformed config is rejected at startup. The server
+advertises its own HTTP address (`ip` + `http_port`, e.g. the pod IP via the k8s
+downward API) so the coordinator can reach it.
diff --git a/docs/design/v1/mp_coordinator/blend_lookup.md b/docs/design/v1/mp_coordinator/blend_lookup.md
new file mode 100644
index 0000000..d601c79
--- /dev/null
+++ b/docs/design/v1/mp_coordinator/blend_lookup.md
@@ -0,0 +1,262 @@
+# Global CacheBlend Lookup (Coordinator Fingerprint Directory)
+
+A coordinator-level capability that lets a CacheBlend lookup on one mp-server
+find and reuse chunk KV cached anywhere in the fleet, fetched from a shared,
+content-addressed L2. Blend servers **publish fingerprints on STORE** and
+**query on LOOKUP**; the coordinator holds the fleet-wide directory and runs the
+match. It is **opt-in** (enabled only when a coordinator URL is configured) and
+**additive** (the existing local matcher fast path is unchanged).
+
+Code: `lmcache/v1/mp_coordinator/blend_directory.py`,
+`lmcache/v1/mp_coordinator/http_apis/blend_directory_api.py`,
+`lmcache/v1/multiprocess/modules/blend_coordinator.py`.
+
+## Why
+
+CacheBlend lookup today is **local to one mp-server**: the matcher
+(`BlendTokenRangeMatcherV3`, `lmcache/v1/multiprocess/modules/blend_v3.py`)
+indexes only chunks that server stored, so a request routed to a different
+replica recomputes KV a peer already holds. As replicas scale, cache sharding
+works against reuse. The coordinator directory federates fingerprints so any
+server can discover and reuse content cached fleet-wide.
+
+## This PR: the original matching algorithm, globalized
+
+The coordinator reuses the **exact matching algorithm** the local matcher
+already uses — non-overlapping chunk fingerprints + a strided rolling-hash probe
+— lifted to a fleet table. Nothing about the match semantics changes; only its
+*scope* (one server → the fleet) and its *transport* (in-process → HTTP).
+
+**The coordinator does all hashing.** Servers send **raw tokens** plus the
+storage mapping only they know; the coordinator chunks, hashes, and matches. This
+keeps the whole matching algorithm in one place, so future evolution (see below)
+is a coordinator-only change — no server hashing change, no fleet redeploy, no
+cross-server hash-base consistency to maintain.
+
+```
+STORE (blend server, worker-0)
+  per stored range: tokens[start:end] + object_keys (per chunk) + old_st_base
+        ── POST /blend/fingerprints ──▶ coordinator.register():
+                                          chunk tokens, hash each → (poly→object_key,old_st)
+
+LOOKUP (blend server, cb_unified_lookup)
+  coordinator present? fleet match only (local matcher skipped); else local only
+  request tokens
+        ── POST /blend/match ──▶ coordinator.match():
+                                   roll hash over tokens, probe every probe_stride
+        ◀── matches: [(object_key, old_st, cur_st)] ──
+  → non-prefix set (drop prefix-covered, leftmost-greedy overlap dedup)
+  → one sparse prefetch from shared L2 → retrieve + re-RoPE
+```
+
+The coordinator owns `chunk_size` (fleet config, must equal the servers'
+LMCache chunk size) and the polynomial base; servers carry neither.
+**Trust note:** the coordinator now sees raw tokens (content), not just opaque
+hashes — acceptable when it is trusted fleet infra; revisit if not.
+
+### What is matched, and the granularity knob
+
+- **Match window = `chunk_size`** (the LMCache chunk, 256, a fleet config). A
+  stored chunk's content is one polynomial hash (`chunk_hash_windows_numba`);
+  a match is "this request window equals a stored chunk."
+- **Probe stride** = how many positions the coordinator skips between probes
+  (`rolling_hash_windows_numba` is computed over every position; the table is
+  probed every `probe_stride`). It is a **coordinator-side config**
+  (`blend_probe_stride`, default `1`), **not** sent by servers and **not** tied
+  to any vLLM block size.
+
+Why not the vLLM block size: with **partial-fill** KV transfer a matched chunk is
+reusable at **any** `cur_st` (the server scatters it token-wise, filling ragged
+pages), so there is no block-alignment constraint to honor. The default
+`probe_stride=1` therefore probes every offset for full recall; raise it only to
+trade recall for coordinator CPU. (vLLM block sizes are per-machine and
+dynamically computed — another reason not to bake one into the match.) `stride`
+controls probe density; `chunk_size` is the reuse unit.
+
+### Identity and scope
+
+The table is keyed by `(model_scope, poly_hash)`:
+
+- **`poly_hash`** — the content-only 64-bit polynomial chunk hash
+  (`chunk_hash_windows_numba` with the fleet-constant base `POLY_BASE`), computed
+  **by the coordinator** from the published tokens.
+- **`model_scope`** = the model name. CacheBlend reuse is same-model only
+  (K is model-specific), so cross-model content never matches.
+
+**`cache_salt` is not in the key** (and neither is TP rank): both are applied at
+retrieve. The querying server expands a matched `object_key` into per-rank
+`ObjectKey`s using **its own** `cache_salt` and `world_size`
+(`ipc_key_to_object_keys` reads them from the request's key), exactly as the
+local path does. So a cross-salt match lands in the requester's own salt
+namespace and confirmed-misses at the sparse prefetch unless a same-salt copy
+exists — tenant isolation holds with **one table per model** instead of one per
+`(model, salt)`. Filtering by the *storer's* salt would be wrong: the directory
+is first-writer-wins per content, so the first storer's salt would get pinned
+and other tenants could never match their own copies of identical content.
+(Cost: a cross-salt match with no same-salt copy is a wasted prefetch — the
+already-tolerated stale-entry failure mode. The directory does reveal cross-salt
+content *existence* to the trusted mp-servers; acceptable for trusted fleet
+infra, revisit if not.)
+
+The 64-bit poly-hash carries the same collision behavior as the local matcher
+(which also matches on the 64-bit poly); acceptable within a model scope, and a
+collision only causes a wasted prefetch (caught downstream), never wrong KV.
+
+## Coordinator directory (`blend_directory.py`)
+
+`GlobalBlendMatcher` (thread-safe) partitions fingerprints **per scope**, each in
+a `_ScopeTable` with its own lock; a small top-level lock guards only the scope
+map and the reverse eviction map:
+
+```
+_scopes  : dict[model_scope -> _ScopeTable]
+  _ScopeTable.slots       : np.int64 direct-address table, low hash bits -> cid
+  _ScopeTable.hashes/locs : per-cid full poly hash + ChunkLoc(object_key, old_st)
+  _ScopeTable.poly_to_cid : dict for idempotent insert / eviction lookup
+_by_key  : dict[object_key -> list[(model_scope, poly_hash)]]   # for eviction
+```
+
+- `register(ranges)` — for each `StoreRange(model_scope, tokens, object_keys,
+  old_st_base)`, chunk the tokens, hash each chunk, and insert each fingerprint
+  **in place** (O(1) per chunk); idempotent (first-writer wins per key).
+- `remove(object_keys)` — tombstone all entries for an evicted chunk (reverse
+  map); a tombstoned entry is skipped at match.
+- `match(model_scope, tokens)` — roll a chunk-window hash over the request
+  tokens, then probe every `probe_stride` position against the scope's
+  **direct-address table** in one numpy gather; a full-64-bit re-check in the
+  sparse hit loop rejects bucket collisions; dedup by `object_key`; return
+  `[(object_key, old_st, cur_st)]`. Mirrors the local
+  `BlendTokenRangeMatcherV3.match_sub_sequence`.
+
+**Match is vectorized; mutation is in place.** All operations on a scope run
+under its lock, which is cheap because the probe is one gather plus a sparse
+verify loop (sub-millisecond). Tables are sized per scope and grow by rebuild
+(power of two, a few times the live entry count — small scopes stay small,
+unlike the local matcher's fixed 2^20 array); rebuilds happen only on the write
+path, at load-factor growth or when tombstones outnumber live entries, so
+lookups never pay them. On a bucket collision the later insert wins; the loser
+is merely unmatchable — a missed reuse recomputed downstream, never wrong KV.
+This replaces the original per-position Python `dict.get` probe loop, which was
+O(n) per query and held the directory's single global lock for its duration.
+
+It is **ephemeral**: rebuilt from publishes after a restart; a stale instance
+leaving the fleet does not drop fingerprints (shared-L2 object keys stay valid).
+
+## Blend-server comms (`blend_coordinator.py`)
+
+Blend handlers run in sync thread pools with no asyncio loop, so the client owns
+a synchronous `httpx.Client` plus a daemon, mirroring the module's existing
+`_fingerprint_queue` worker:
+
+- **STORE**: `enqueue_register` → best-effort, fire-and-forget `POST
+  /blend/fingerprints` (register). Eviction, when wired, is the distinct
+  `enqueue_evict` → `DELETE /blend/fingerprints`.
+- **LOOKUP**: `submit_match` (once per request) + `poll_match` — the same
+  non-blocking submit/poll pattern the prefix and sparse legs already use;
+  `cb_unified_lookup` polls until the match resolves and merges it. The single
+  wall-clock bound is the client HTTP `request_timeout` (default 50 ms): a slow
+  or down coordinator returns/​times-out into an empty result, so the lookup
+  proceeds local-only without stalling. No separate poll-count budget.
+  - **Match queries run concurrently.** The daemon dispatches each match to a
+    thread pool (`LMCACHE_COORDINATOR_BLEND_MATCH_CONCURRENCY`, default 8), so
+    one slow coordinator reply no longer stalls the queries behind it.
+  - **Compact wire form.** Request tokens ship as a base64 little-endian
+    `uint32` buffer (`tokens_b64`, via `encode_tokens`/`decode_tokens` in
+    `schemas.py`) — ~1.4x smaller than a JSON list and decoded in one
+    `np.frombuffer` straight to the matcher's array. Register still ships raw
+    tokens as JSON (lower frequency).
+
+Opt-in via `LMCACHE_COORDINATOR_URL`; absent → the module receives `None` and
+every publish/query path is skipped (behavior unchanged).
+
+## Lookup flow in `cb_unified_lookup`
+
+Local and coordinator matching are **mutually exclusive**, chosen by coordinator
+presence: with a coordinator configured the fleet directory (a superset of the
+local table) is the *only* match source and the local matcher is skipped
+entirely; with none, matching is purely local as before. There is no merge.
+
+With a coordinator:
+
+1. First call: skip the local fingerprint match; submit only the coordinator
+   match (request tokens). A per-lookup wall-clock deadline is armed
+   (`match_budget_s`, from `LMCACHE_COORDINATOR_BLEND_TIMEOUT`).
+2. After the prefix resolves, poll the coordinator **before** the sparse
+   prefetch: defer while pending, give up at the deadline (then no fleet matches
+   that lookup). The deadline (not just the per-request HTTP timeout) bounds
+   total wait, since the coordinator daemon services match queries serially.
+3. Keep matches outside the prefix coverage and apply **leftmost-greedy overlap
+   dedup** — the coordinator dedups only by `object_key`, so its matches can
+   still overlap, and two matches over the same request range can't both scatter.
+4. Submit **one** sparse prefetch over that set, classify, retrieve.
+
+Without a coordinator, step 1 instead runs the local matcher and steps 3–4 use
+its matches (already non-overlapping, so the dedup is a no-op).
+
+Fleet matches are `CBMatchResult` (each `hash` is the chunk content hash — the
+coordinator's `object_key` hex — which `ipc_key_to_object_keys` expands to
+per-rank shared-L2 keys), so they ride the **identical** sparse prefetch +
+classify + retrieve + re-RoPE path as local matches and surface in
+`CBUnifiedLookupResult.non_prefix_segments`. There is no separate
+`global_segments` field and no protocol change.
+
+## Eviction & staleness
+
+Lazy. On local eviction the server may publish a `remove`, but the directory
+tolerates stale entries: a match to an evicted object key simply misses at sparse
+prefetch → the server recomputes. Never wrong KV. (Eager per-chunk eviction
+publish is optional and not required for correctness.)
+
+## Failure modes
+
+| event | effect | handling |
+| --- | --- | --- |
+| coordinator down | no global leg | HTTP times out → empty result → local-only |
+| poly-hash collision | wasted prefetch | confirmed-miss → recompute |
+| stale entry (evicted) | wasted prefetch | miss → recompute; lazy remove |
+| cross-salt match, no same-salt copy | wasted prefetch | requester-salt ObjectKey misses → recompute |
+| publish dropped | a chunk unindexed globally | recomputed on a peer until re-published |
+
+## Future evolution (not in this PR)
+
+The original algorithm reuses content only at **chunk granularity** and only when
+the content is chunk-phase aligned (store-side non-overlapping chunks). Two
+refinements raise reuse, gated by the partial-KV-transfer work:
+
+- **Block-level** — match at the inference block size `G` (`block_content_hashes`
+  + minimizer-sparse anchor index + seed-and-extend), so reuse is `G`-grained and
+  partial chunks are reusable. Still `G`-phase-sensitive.
+- **Token-level** — rolling k-mer **minimizer seeds** + **token-level extend**,
+  giving arbitrary-offset reuse and ragged partial-page tails. Requires dense
+  per-token hash arrays at the coordinator.
+
+### Role of the minimizer (for the refinements)
+
+The minimizer picks ~1 anchor per window `W` by **content** (local-min hash). It
+**decouples** three things: match completeness (a run `≥ W` shares an anchor),
+index cost (`÷W`), and offset (content-defined selection is offset-free). It
+sparsifies the *seed index* only; the dense per-position arrays needed to
+*extend* stay dense. With it, you keep a fine match granularity *and* a small
+index; without it you must coarsen granularity to shrink the index.
+
+### Complexity (n=request tokens, m=stored tokens, C=chunk, G=block, W=window)
+
+| | original (this PR) | block-level | token-level |
+| --- | --- | --- | --- |
+| store | O(m) hash + O(m/C) insert | O(m) + O(m/(G·W)) | O(m) + O(m/W) |
+| lookup | O(n) roll + O(n/stride) probe | O(n) + O(n/(G·W)) + O(hit/G) | O(n) + O(n/W) + O(hit) |
+| coordinator hash mem | O(m/C) | O(m/G) | O(m) |
+| match unit | C (256) | G | 1 token |
+| offset | store chunk-phase bound | G-phase bound | arbitrary |
+
+All lookups are O(n + hit) asymptotically; the differences are constants,
+coordinator memory (`m/C : m/G : m` ≈ `1 : 16 : 256` at C=256,G=16), and
+capability (granularity + offset). This PR takes the cheapest, simplest point;
+the refinements trade coordinator memory for finer, offset-robust reuse.
+
+## Scope
+
+Additive: no change to local prefix/blend lookup, retrieve/re-RoPE/scatter, or
+the coordinator backbone. Composes via the documented extension seam — a new
+`http_apis` router reading `app.state`, plus the opt-in blend client — with no
+edits to membership or the health loop.
diff --git a/docs/design/v1/mp_coordinator/l2_prefetch.md b/docs/design/v1/mp_coordinator/l2_prefetch.md
new file mode 100644
index 0000000..d0c9e56
--- /dev/null
+++ b/docs/design/v1/mp_coordinator/l2_prefetch.md
@@ -0,0 +1,105 @@
+# Coordinator-Controlled L2→L1 Prefetch
+
+## Why
+
+An operator or scheduler that knows a node will soon serve a particular prompt
+(a traffic shift, a known-hot shared prefix) needs a way to **pre-warm** that
+node's L1 from L2 before the requests land. The coordinator already pushes L2
+*evict* and *resync* to nodes; this adds the symmetric *prefetch* control.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+    participant Cl as client / scheduler
+    participant Co as coordinator
+    participant M as mp server
+
+    Cl->>Co: POST /cache/prefetches {instance_id, model_name, world_size, token_ids, cache_salt}
+    Co->>M: POST /cache/prefetches (tokens forwarded verbatim)
+    M-->>Co: {request_id, chunks, status: "submitted"}
+    Co-->>Cl: {instance_id, request_id, chunks, status}
+    loop until completed
+        Cl->>Co: GET /cache/prefetches/{instance_id}/{request_id}
+        Co->>M: GET /cache/prefetches/{request_id}
+        M-->>Co: {status: pending | completed}
+        Co-->>Cl: (relayed verbatim)
+    end
+```
+
+A client names **one** registered MP server and a **token sequence** (plus the
+model/world_size and tenant salt, and the optional `source_tier`=`l2` /
+`target_tier`=`l1`). The coordinator resolves the target's address from the
+registry, `POST`s to its `/cache/prefetches`, and relays the server's
+`request_id` back. The client then polls
+`GET /cache/prefetches/{instance_id}/{request_id}` on the coordinator, which proxies
+the server's status. The warm holds **no read-lock** — completion is reported
+reactively and releases nothing; see `docs/design/v1/multiprocess/l2_apis.md`
+for the warm-prefetch lifecycle (retain-permanent, no-lock load). There is no
+background polling on either side: the submit and status calls are quick and
+the client drives completion on demand.
+
+## Components
+
+- **`schemas.py`** — `PrefetchRequest {instance_id, model_name, world_size,
+  token_ids, cache_salt, source_tier=l2, target_tier=l1}` and
+  `PrefetchResponse {instance_id, request_id, chunks, status}`.
+- **`cache_control/prefetch_manager.py`** — `PrefetchManager`. `submit_prefetch`
+  awaits the target's `POST /cache/prefetches` and returns its reply;
+  `get_status` proxies `GET /cache/prefetches/{request_id}` and relays
+  `(status_code, body)`. No fire-and-forget tasks — both calls are quick.
+- **`http_apis/cache_api.py`** — `POST /cache/prefetches` and
+  `GET /cache/prefetches/{instance_id}/{request_id}`. Each resolves the target
+  via `get_context(request).registry.get(instance_id)` (**404** if unknown) and
+  uses the shared outbound `httpx.AsyncClient` (`get_outbound_client(request)`);
+  a transport error to the target surfaces as **502**.
+
+## Wiring (`app.py`)
+
+`create_app` builds the `CoordinatorContext` (carrying `prefetch_manager`) and
+puts it on `app.state.ctx`. The lifespan stashes the outbound client on
+`app.state.ctx.outbound_client` (it previously reached only the background
+loops) so request handlers can issue outbound calls.
+
+## Failure modes
+
+- **Unknown `instance_id`** → 404 (synchronous, before any outbound call).
+- **Target unreachable / non-2xx submit** → 502 from the coordinator (the
+  caller learns the submit failed, unlike a fire-and-forget dispatch).
+- **Target has no layout for `(model_name, world_size)`** → the server returns
+  503 (`Unavailable`), surfaced to the caller via the 502/proxy path.
+- **Client abandons polling** → the server's job lingers as a small handle
+  entry (no lock held, no L1 pinned) until polled or swept — see the no-lock
+  lifecycle in `l2_apis.md`.
+
+## Scope
+
+The coordinator only routes submit + status; it does not track which keys a
+node already holds or retry. Completion is observed via the status endpoint
+(the warm acquires no read-lock, so it emits no `SM_READ_PREFETCHED_FINISHED`;
+the load itself still surfaces through the controller's
+`L2_PREFETCH_LOAD_COMPLETED` event).
+
+### Single-node vs. multi-node
+
+One `instance_id` is **one node's** MP server, and its L1 is shared with that
+node's workers via intra-node CUDA IPC — so it holds only the KV shards for the
+`global_rank`s served on that node. Concretely:
+
+- **Single-node deployment** (all `world_size` workers on one box, e.g. TP=8 on
+  one node): one instance holds every shard. A single `POST /cache/prefetches`
+  warms the whole model's KV for the prompt. **This is the supported case.**
+- **Multi-node deployment** (TP/PP spanning nodes): each node holds only its
+  slice. A single dispatch warms one node; the caller must warm *each* node's
+  `instance_id` to cover the full model. The MP server's all-rank fan-out also
+  loads foreign-rank keys that no local worker reads — harmless (best-effort:
+  they occupy L1 as unread, retained-but-unlocked entries that eviction
+  reclaims under pressure), but not optimal.
+
+**Coordinating multi-node fan-out — choosing the right set of `instance_id`s
+and restricting each to its local ranks — is deferred to the KV cache
+directory** (separate PR). The directory is the component that knows which node
+holds which shard; this endpoint is the per-node primitive it will drive.
+Restricting the fan-out to local ranks is intentionally *not* done here because
+the MP server does not yet track which `global_rank`s it serves — that per-node
+rank topology is directory-owned infrastructure.
diff --git a/docs/design/v1/mp_coordinator/l2_usage_and_eviction.md b/docs/design/v1/mp_coordinator/l2_usage_and_eviction.md
new file mode 100644
index 0000000..5964870
--- /dev/null
+++ b/docs/design/v1/mp_coordinator/l2_usage_and_eviction.md
@@ -0,0 +1,210 @@
+# Fleet-Wide L2 Usage Tracking and Eviction
+
+A coordinator-level capability that gives fleet-wide visibility into per-tenant
+L2 cache usage and enforces per-``cache_salt`` byte quotas via LRU eviction.
+MP servers **report store/lookup events** to the coordinator; the coordinator
+aggregates usage, manages quotas, and periodically selects LRU keys to evict
+when a tenant exceeds its quota. It is **opt-in** (gated by
+``l2_event_reporting`` in ``CoordinatorConfig``) and **additive** (the existing
+per-server eviction is unchanged).
+
+Code: `lmcache/v1/mp_coordinator/cache_control/` (coordinator side),
+`lmcache/v1/mp_coordinator/http_apis/cache_api.py` (REST endpoints),
+`lmcache/v1/mp_coordinator/schemas.py` (wire types),
+`lmcache/v1/multiprocess/http_server.py` (MP-server wiring).
+
+## Why
+
+L2 eviction today is **local to each MP server**: the ``IsolatedLRUEvictionPolicy``
+tracks only what that server stored and enforces quotas within that scope. With
+a shared L2 backend (e.g. S3), multiple servers write to the same storage, but
+no single server has a fleet-wide view of total per-tenant usage. The coordinator
+centralizes usage accounting and quota enforcement so limits apply to the
+aggregate, not per-replica.
+
+## Architecture
+
+```
+MP server (store/lookup)
+  L2 adapter fires on_l2_keys_stored / on_l2_keys_accessed
+        │
+        ▼
+  L2EventListener (L2AdapterListener)
+    converts ObjectKey → EncodedObjectKey, buffers UsageEvents
+        │  flush every l2_event_flush_interval (default 1s)
+        │
+        ▼
+  POST /quota/events ──▶ Coordinator
+                        ├─ L2UsageManager: per-salt byte accounting
+                        ├─ L2EvictionManager: per-salt LRU
+                        └─ QuotaManager: per-salt byte limits
+
+  Coordinator background loop (every eviction_check_interval, default 5s)
+        │
+        ▼
+  execute_evictions():
+    for each tracked salt:
+      limit = quota (default 0 → evict all)
+      if usage ≥ watermark·limit → select LRU keys,
+        fire-and-forget DELETE /cache/objects to a holder
+```
+
+## Wire types (`schemas.py`)
+
+- **``EncodedObjectKey``** — torch-free wire shape of ``ObjectKey`` (owned by
+  ``lmcache.v1.distributed.api``); ``chunk_hash`` is hex-encoded instead of raw
+  bytes. The coordinator rebuilds the canonical ``ObjectKey`` via
+  ``key.to_object_key()``.
+- **``EventType``** — ``str`` enum: ``STORE``, ``LOOKUP``, ``DELETE``.
+- **``UsageEvent``** — ``type: EventType``, ``key: EncodedObjectKey``,
+  ``bytes: int``.
+- **``ReportUsageRequest``** — ``instance_id``, ``seq``, ``events:
+  list[UsageEvent]``, ``tier`` (data, default ``l2``).
+
+The ``ObjectKey`` → ``EncodedObjectKey`` conversion happens at the MP-server
+boundary (``obj.to_encoded_object_key()`` in ``event_listener.py``), so the
+coordinator never imports ``torch``.
+
+## Coordinator components (`cache_control/`)
+
+### L2UsageManager (`usage_manager.py`)
+
+Thread-safe per-salt byte counter. Two operations:
+
+- ``record_stored(cache_salt, n_bytes)`` — increment.
+- ``record_evicted(cache_salt, n_bytes)`` — decrement (clamped at zero).
+
+Exposes ``get(salt)``, ``get_all()``, ``get_total()`` for the status endpoints.
+
+### QuotaManager (reused from ``lmcache.v1.distributed.quota_manager``)
+
+Thread-safe in-memory quota registry (``dict[str, int]`` + lock). CRUD via
+``set_quota``, ``get_limit_bytes``, ``delete_quota``, ``list_quotas``.
+Quotas are set in GiB at the API and stored as bytes internally.
+
+Unregistered salts resolve through a configurable **default limit**
+(``set_default_limit_bytes`` / ``effective_limit_bytes``), which starts as ``None``:
+
+- ``None`` (boot default) — unregistered salts are **exempt** from coordinator
+  eviction. Quotas live in memory, so a restarted coordinator has an empty
+  table until the external quota controller re-syncs it; the exempt default
+  makes that window safe (an empty table cannot mass-evict unknown tenants).
+- ``0`` — strict allowlist: all bytes under unregistered salts become
+  evictable next cycle. The external controller sets this via
+  ``PUT /quota/config`` **after** re-registering every per-salt quota — it is
+  the explicit signal that arms fleet-wide eviction of unquota'd data.
+- ``> 0`` — every unregistered salt gets that byte budget.
+
+The MP server's local eviction controller keeps the legacy
+``get_limit_bytes`` path (unregistered ⇒ 0) and is unaffected by the default.
+Because the server-local and coordinator quota registries are independent and
+never synchronized, a deployment must register quotas through **one** of the
+two ``/quota`` APIs, never both — the server-side enforcer fully evicts any
+salt missing from its own table, so it would fight quotas registered only on
+the coordinator (see the warning in ``docs/source/mp/coordinator.rst``).
+
+### L2EvictionManager (`eviction_manager.py`)
+
+Per-``cache_salt`` LRU for the coordinator process. It delegates the ordering to
+a coordinator-side ``IsolatedLRUEvictionPolicy`` instance, keyed by the canonical
+``ObjectKey`` (rebuilt from the wire ``EncodedObjectKey``). Per-salt byte
+accounting lives in ``L2UsageManager``; the eviction manager only tracks order.
+
+- ``on_store(key)`` — register the key in the LRU
+  (``policy.on_keys_created``). The paired byte increment is the caller's job
+  (``L2UsageManager.record_stored``).
+- ``on_lookup(key)`` — touch (``policy.on_keys_touched``, move to MRU end).
+- ``on_remove(key)`` — drop from the LRU (``policy.on_keys_removed``); the paired
+  byte decrement is the caller's job (``L2UsageManager.record_evicted``).
+- ``compute_eviction_plan() -> dict[str, list[ObjectKey]]`` — **pure**: for each
+  tracked salt, fire when ``usage ≥ trigger_watermark · quota`` (quota 0 ⇒ evict
+  all), selecting ``eviction_ratio`` of the salt's LRU keys via
+  ``policy.get_eviction_actions``. Salts without an explicit quota use the
+  registry's default limit; while it is unset (``None``) they are skipped
+  entirely — see QuotaManager above. No network, no mutation.
+- ``execute_evictions(registry, http_client)`` — computes the plan and
+  **fire-and-forget** ``DELETE /cache/objects`` to a holder MP server for each
+  salt's victims; on confirmed deletion ``on_remove`` drops them from tracking.
+  The plan's keys are split into chunks of at most ``MAX_DELETE_BATCH`` (imported
+  from the MP server's ``object_service``) and each chunk is dispatched as its
+  own request, because the endpoint rejects any single delete over that cap with
+  HTTP 400 — a full-salt eviction (quota dropped to 0) routinely exceeds it.
+
+## REST endpoints (`quota_api.py`)
+
+| Method | Path | Description |
+| --- | --- | --- |
+| ``PUT`` | ``/quota/config`` | Set the default limit for unquota'd salts (``null`` ⇒ exempt; ``0`` arms allowlist eviction) |
+| ``GET`` | ``/quota/config`` | Read the default limit |
+| ``PUT`` | ``/quota/{cache_salt}`` | Set quota (GiB) |
+| ``DELETE`` | ``/quota/{cache_salt}`` | Remove quota |
+| ``GET`` | ``/quota/{cache_salt}`` | Quota + usage for one salt |
+| ``GET`` | ``/quota`` | Quota + usage for all salts |
+| ``POST`` | ``/quota/events`` | Ingest batch of store/lookup/delete events |
+
+The ``/quota/config`` routes are declared before ``/quota/{cache_salt}`` so the
+literal ``config`` segment is not captured as a salt. Expected controller flow
+after a coordinator (re)start: ``PUT /quota/{salt}`` for every tenant, then
+``PUT /quota/config {"default_limit_gb": 0}`` to arm eviction of everything
+else.
+
+These quota/usage-accounting endpoints live in the ``/quota`` group (mirroring
+the MP server's node-local ``/quota``); warm-prefetch dispatch is the only thing
+left on the coordinator's ``/cache/*`` surface (``cache_api.py``). Paths are
+tier-neutral; the tier is request data (`tier`, default `l2`). Status responses
+report usage in GiB only (no raw bytes in the API).
+
+## MP-server event listener (`event_listener.py`)
+
+``L2EventListener`` implements ``L2AdapterListener`` and is registered
+on all L2 adapters via ``StorageManager.register_l2_listener()``. It:
+
+1. Receives ``on_l2_keys_stored(keys, sizes)``, ``on_l2_keys_accessed(keys)``,
+   and ``on_l2_keys_deleted(keys)`` callbacks from the L2 adapter (any thread).
+2. Converts each ``ObjectKey`` to ``EncodedObjectKey`` (hex-encodes
+   ``chunk_hash``).
+3. Buffers ``UsageEvent``s under a lock.
+4. Flushes the buffer to ``POST /quota/events`` on a timer
+   (``l2_event_flush_interval``, default 1s). Failures are logged and the
+   batch is dropped to prevent unbounded growth.
+
+``on_l2_keys_deleted`` buffers a ``DELETE`` event so the coordinator can drop
+the key from its usage accounting and LRU tracking.
+
+## Configuration
+
+### Coordinator side (`MPCoordinatorConfig`)
+
+| Field | Default | Description |
+| --- | --- | --- |
+| ``eviction_check_interval`` | ``5.0`` | Seconds between eviction cycles (0 disables) |
+| ``eviction_ratio`` | ``0.2`` | Fraction of a salt's LRU keys (by count) to evict per cycle |
+| ``trigger_watermark`` | ``1.0`` | Eviction fires when usage reaches this fraction of the quota |
+
+### MP-server side (`CoordinatorConfig`)
+
+| Field | Default | Env var | Description |
+| --- | --- | --- | --- |
+| ``l2_event_reporting`` | ``False`` | ``LMCACHE_COORDINATOR_L2_EVENT_REPORTING`` | Enable event reporting |
+| ``l2_event_flush_interval`` | ``1.0`` | ``LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL`` | Seconds between flushes |
+
+Both also accept CLI flags (``--coordinator-l2-event-reporting``,
+``--coordinator-l2-event-flush-interval``).
+
+## Failure modes
+
+| Event | Effect | Handling |
+| --- | --- | --- |
+| Coordinator down | Events not delivered | Flush fails → batch dropped, logged; MP server unaffected |
+| Coordinator restart | Usage/LRU state lost | Rebuilt from incoming events; stale until servers report |
+| Flush timeout | One batch delayed | Next flush sends new batch; no retry of old batch |
+| Usage accounting drift | Quota enforcement imprecise | Self-correcting as new events arrive |
+
+## Scope
+
+Additive: no change to per-server eviction, L2 adapter store/lookup paths, or
+the coordinator's membership/health loop. Composes via the ``L2AdapterListener``
+interface and the ``http_apis`` auto-discovery — a new router reading
+``app.state``, plus the opt-in event listener — with no edits to existing
+controllers or adapters beyond passing ``sizes`` through to
+``on_l2_keys_stored``.
diff --git a/docs/design/v1/mp_observability/DEBUG.md b/docs/design/v1/mp_observability/DEBUG.md
new file mode 100644
index 0000000..5c4ee40
--- /dev/null
+++ b/docs/design/v1/mp_observability/DEBUG.md
@@ -0,0 +1,93 @@
+# MP Observability — Debug Recipes
+
+How to derive L1-only / L2-only / blend hit rates from the counters in
+[METRICS.md](METRICS.md), and what to send to a maintainer when reporting
+a hit-rate regression.
+
+---
+
+## Common parameters
+
+All from `GET <lmcache-url>/status`:
+
+| Field | Source | Example |
+|---|---|---|
+| `chunk_size` | top-level | 256 |
+| L1 capacity (bytes) | `storage_manager.l1_manager.memory_total_bytes` | `5 * 2**30` |
+| L1 used (bytes) | `storage_manager.l1_manager.memory_used_bytes` | varies |
+
+## Token-level hit rate (L1 + L2 combined)
+
+```
+lmcache_mp_lookup_hit_tokens_total / lmcache_mp_lookup_requested_tokens_total
+```
+
+Fraction of chunk-aligned tokens that came back from cache anywhere.
+Reported per `(model_name, cache_salt)`.
+
+## L2-only hit rate
+
+L2's prefetch lookups carry per-key counts, not per-token:
+
+```
+L2_hit_tokens_total = increase(lmcache_mp_l2_prefetch_hit_chunks_total) * chunk_size
+L2_hit_rate         = L2_hit_tokens_total
+                    / increase(lmcache_mp_lookup_requested_tokens_total)
+```
+
+The keys-to-tokens conversion is exact — every L2 hit is a full chunk.
+
+## L1-only hit rate (derived)
+
+Total minus L2:
+
+```
+L1_hit_tokens_total = increase(lmcache_mp_lookup_hit_tokens_total)
+                    - increase(lmcache_mp_l2_prefetch_hit_chunks_total) * chunk_size
+L1_hit_rate         = L1_hit_tokens_total
+                    / increase(lmcache_mp_lookup_requested_tokens_total)
+```
+
+Sanity check: `L1_hit_tokens_total >= 0`.  A sustained negative value
+indicates a metric-emission bug.
+
+## Blend total hit rate
+
+```
+lmcache_blend_lookup_hit_tokens_total / lmcache_blend_lookup_requested_tokens_total
+```
+
+Reported per CacheBlend lookup (`CB_LOOKUP_END`).
+
+## Blend L1 vs L2 — *not separable today*
+
+The blend lookup consults L1 (fingerprint table) and L2 (storage
+prefetch) as a single pipelined operation, and `lmcache_blend.lookup_storage_hits`
+aggregates them.  Splitting requires per-chunk attribution inside the
+blend lookup; tracked as an open follow-up.
+
+## Did eviction fire during my run?
+
+```
+ticks      = increase(lmcache_mp_l1_eviction_loop_ticks_total)
+triggered  = increase(lmcache_mp_l1_eviction_loop_triggered_total)
+fire_ratio = triggered / ticks   # 0.0 = never fired; 1.0 = fired every cycle
+```
+
+If `triggered == 0` over a thrash test, the benchmark completed faster
+than the 1Hz polling interval.  Lower `--eviction-trigger-watermark` or
+raise `--eviction-ratio` (or run the workload longer) to see eviction
+engage.
+
+## Self-service checklist
+
+Attach these four artifacts when reporting a hit-rate regression:
+
+1. `GET <lmcache-url>/status` (config + state snapshot).
+2. `GET <lmcache-url>/metrics` snapshots taken **before** and **after** the run.
+3. The bench's `bench_summary.json` and `bench_results.csv` (TTFT per request).
+4. The LMCache server's stdout/stderr (eviction-trigger logs are at INFO level).
+
+(1)–(3) plus the formulas above let a maintainer compute L1, L2, blend,
+and combined hit rates; the eviction-loop counters confirm whether the
+LRU machinery actually engaged.
diff --git a/docs/design/v1/mp_observability/EVENTS.md b/docs/design/v1/mp_observability/EVENTS.md
new file mode 100644
index 0000000..829245a
--- /dev/null
+++ b/docs/design/v1/mp_observability/EVENTS.md
@@ -0,0 +1,268 @@
+# Event Metadata Contracts
+
+Each `EventType` has a documented metadata schema.  Producers **must** populate
+these keys; subscribers **may** rely on them being present.
+
+For the full list of event types see `event.py`.  For metrics derived from
+these events see [METRICS.md](METRICS.md).
+
+---
+
+## L1Manager Events
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `L1_READ_RESERVED` | `keys` | `list[ObjectKey]` |
+| `L1_READ_FINISHED` | `keys` | `list[ObjectKey]` |
+| `L1_WRITE_RESERVED` | `keys` | `list[ObjectKey]` |
+| `L1_WRITE_FINISHED` | `keys` | `list[ObjectKey]` |
+| `L1_WRITE_FINISHED_AND_READ_RESERVED` | `keys` | `list[ObjectKey]` |
+| `L1_KEYS_EVICTED` | `keys` | `list[ObjectKey]` |
+| `L1_EVICTION_LOOP_TICK` | `usage`, `watermark`, `triggered` | `float`, `float`, `bool` |
+
+`L1_EVICTION_LOOP_TICK` fires once per `L1EvictionController.eviction_loop`
+iteration (default ~1Hz).  `triggered` is `True` when `usage >= watermark`
+and the policy ran this cycle, `False` otherwise.
+
+---
+
+## L1 Failure Events
+
+Published at the caller of the L1 API — **not** inside `L1Manager` — so the
+caller context (`during`) can be attached without leaking caller identity
+into the manager. See LM-291 for the health-monitoring rationale.
+
+Producers split keys by `(during[, reason])` and publish one event per
+non-empty bucket; `keys` is the list of ObjectKeys that failed for that
+bucket. Subscribers bucket by `ObjectKey.model_name` to emit per-model
+counter increments.
+
+| EventType | Metadata keys | Types | Vocabulary |
+|---|---|---|---|
+| `L1_ALLOCATION_FAILED` | `during`, `keys` | `str`, `list[ObjectKey]` | `during` ∈ {`l1_store`, `l2_prefetch`} |
+| `L1_READ_FAILED` | `during`, `reason`, `keys` | `str`, `str`, `list[ObjectKey]` | `during` ∈ {`l2_store`, `l1_retrieve`}; `reason` ∈ {`not_found`, `write_locked`} |
+
+`L1_READ_FAILED` is a **post-lookup anomaly** event, not a cache-miss
+event: in MP mode every `reserve_read` / `unsafe_read` that raises one of
+these errors represents a lookup/reserve race or unexpected eviction. The
+counter should stay near zero in healthy operation.
+
+Producers:
+- `L1_ALLOCATION_FAILED(during=l1_store)` — `StorageManager.reserve_write`, on `L1Error.OUT_OF_MEMORY`.
+- `L1_ALLOCATION_FAILED(during=l2_prefetch)` — `PrefetchController._transition_to_load_phase`, on `L1Error.OUT_OF_MEMORY` from L1 reservation.
+- `L1_READ_FAILED(during=l1_retrieve)` — `StorageManager.read_prefetched_results` (`unsafe_read` failure). `not_found` = `KEY_NOT_EXIST`, `write_locked` = `KEY_NOT_READABLE` (read lock lost).
+- `L1_READ_FAILED(during=l2_store)` — `StoreController._process_new_keys` (`reserve_read` failure on keys that just finished L1 write). `not_found` = `KEY_NOT_EXIST`, `write_locked` = `KEY_NOT_READABLE`.
+
+---
+
+## StorageManager Events
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `SM_READ_PREFETCHED` | `succeeded_keys`, `failed_keys` | `list[ObjectKey]`, `list[ObjectKey]` |
+| `SM_READ_PREFETCHED_FINISHED` | `succeeded_keys`, `failed_keys` | `list[ObjectKey]`, `list[ObjectKey]` |
+| `SM_WRITE_RESERVED` | `succeeded_keys`, `failed_keys` | `list[ObjectKey]`, `list[ObjectKey]` |
+| `SM_WRITE_FINISHED` | `succeeded_keys`, `failed_keys` | `list[ObjectKey]`, `list[ObjectKey]` |
+
+---
+
+## L2 Store Controller Events
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `L2_STORE_SUBMITTED` | `adapter_index`, `task_id`, `l2_name`, `key_count`, `total_bytes`, `key_count_per_salt` | `int`, `int`, `str`, `int`, `int`, `dict[str, int]` |
+| `L2_STORE_COMPLETED` | `adapter_index`, `task_id`, `l2_name`, `bytes_transferred`, `succeeded_count`, `failed_count`, `key_count_per_salt` | `int`, `int`, `str`, `int`, `int`, `int`, `dict[str, int]` |
+
+`key_count_per_salt` maps each `cache_salt` to its key count, pre-grouped
+at the emit site so the drain thread iterates tenants (O(T)) not keys (O(N)).
+Store tasks can batch keys from multiple tenants; `key_count_per_salt`
+enables per-tenant attribution on the subscriber side.
+On the failure path of `L2_STORE_COMPLETED`, `key_count_per_salt` is absent
+(no succeeded keys to attribute).
+
+---
+
+## L2 Prefetch Controller Events
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `L2_PREFETCH_LOOKUP_SUBMITTED` | `request_id`, `key_count`, `adapter_count`, `key_count_per_salt` | `int`, `int`, `int`, `dict[str, int]` |
+| `L2_PREFETCH_LOOKUP_COMPLETED` | `request_id`, `prefix_hit_count` | `int`, `int` |
+| `L2_PREFETCH_LOAD_SUBMITTED` | `request_id`, `key_count`, `adapter_count`, `key_count_per_salt` | `int`, `int`, `int`, `dict[str, int]` |
+| `L2_PREFETCH_LOAD_COMPLETED` | `request_id`, `loaded_count`, `failed_count`, `key_count_per_salt` | `int`, `int`, `int`, `dict[str, int]` |
+| `L2_LOAD_TASK_SUBMITTED` | `request_id`, `adapter_index`, `task_id`, `l2_name`, `key_count`, `total_bytes` | `int`, `int`, `int`, `str`, `int`, `int` |
+| `L2_LOAD_TASK_COMPLETED` | `request_id`, `adapter_index`, `task_id`, `l2_name` | `int`, `int`, `int`, `str` |
+
+`key_count_per_salt` on `L2_PREFETCH_LOOKUP_SUBMITTED`,
+`L2_PREFETCH_LOAD_SUBMITTED`, and `L2_PREFETCH_LOAD_COMPLETED` enables
+per-tenant metric attribution. `key_count_per_salt` on load-completed
+covers only loaded (succeeded) keys.
+
+`L2_LOAD_TASK_*` events fire once per `(request_id, adapter_index)` pair
+— unlike the request-level `L2_PREFETCH_LOAD_*` events above, which
+aggregate across adapters.  Throughput subscribers that need per-adapter
+attribution (e.g. `L2ThroughputSubscriber`) consume these task-level
+events; key-count counters continue to consume the request-level events.
+
+---
+
+## L2 Eviction Controller Events
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `L2_KEYS_EVICTED` | `key_count`, `key_count_per_salt` | `int`, `dict[str, int]` |
+
+Published by `L2EvictionController._execute_eviction_action` after
+`adapter.delete()` completes. Only emitted when at least one key was
+evicted. `key_count_per_salt` enables per-tenant eviction dashboards.
+
+---
+
+## L2 Failure Events
+
+Health-monitoring event for the L2 prefetch path. See LM-291.
+
+| EventType | Metadata keys | Types | Vocabulary |
+|---|---|---|---|
+| `L2_PREFETCH_FAILED` | `reason`, `keys` | `str`, `list[ObjectKey]` | `reason` ∈ {`l1_oom`, `not_found`} |
+
+Producers (both in `PrefetchController`):
+- `reason=l1_oom` — emitted when `reserve_write` into L1 returns `OUT_OF_MEMORY` during the transition-to-load phase. Published in parallel with `L1_ALLOCATION_FAILED(during=l2_prefetch)`.
+- `reason=not_found` — emitted in `_finalize_load` for keys reserved in L1 but missing from the adapter's load bitmap (L2 reported the key present at lookup but produced no data).
+
+The third reason `serde_failure` will be added as an additive, non-breaking
+extension once the serde PR lands and adapters can distinguish
+deserialization errors from missing objects. No dashboard migration
+needed when that happens.
+
+---
+
+## Timeout Events
+
+Cross-component health event. Published by `LMCacheTimeoutError.__init__`
+(see `lmcache/v1/mp_observability/errors.py`) every time the exception is
+constructed, gated by `is_observability_enabled()` so it is a no-op outside
+the MP server process. The `session_id` on the `Event` dataclass correlates
+the timeout with the originating request when the raise site has it; it is
+empty otherwise.
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `TIMEOUT_RAISED` | `message`, `exception_type`, `stacktrace` | `str`, `str`, `str` |
+
+- `message` — the exception's message string (`str(exc)`).
+- `exception_type` — the class name (`LMCacheTimeoutError` or a subclass).
+- `stacktrace` — the formatted construction stack (`traceback.format_stack()`
+  minus the `__init__` frame), surfaced as the OTel `exception.stacktrace`
+  attribute by the tracing subscriber.
+
+Consumed by `TimeoutMetricsSubscriber` (counter), `TimeoutLoggingSubscriber`
+(warning log), and `TimeoutTracingSubscriber` (OTel span with an `exception`
+event + ERROR status).
+
+---
+
+## MP Server Lifecycle Sentinels
+
+CPU-synchronous sentinels published by `server.py` to bracket request scope.
+Published via `EventBus.publish()` (not `publish_on_stream`) so the drain
+thread processes them in strict order before any GPU-callback events.
+
+| EventType | Metadata keys | Types | Published by / when |
+|---|---|---|---|
+| `MP_REQUEST_START` | *(none)* | — | `MPServer.handle_request` — at request arrival, before any GPU work |
+| `MP_STORE_SUBMITTED` | `device` | `str` | `MPServer.store` — CPU-synchronous, before the GPU store is enqueued |
+| `MP_RETRIEVE_SUBMITTED` | `device` | `str` | `MPServer.retrieve` — CPU-synchronous, before the GPU retrieve is enqueued |
+| `MP_REQUEST_END` | *(none)* | — | `MPServer.handle_request` — after all CPU work; may precede GPU callbacks |
+
+---
+
+## MP Server Events
+
+These events use `session_id` on the `Event` dataclass (not in `metadata`)
+to correlate START/END pairs.
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `MP_STORE_START` | `device`, `engine_id`, `model_name` | `str`, `int`, `str` |
+| `MP_STORE_END` | `device`, `stored_count`, `engine_id`, `model_name`, `total_bytes` | `str`, `int`, `int`, `str`, `int` |
+| `MP_RETRIEVE_START` | `device`, `engine_id`, `model_name` | `str`, `int`, `str` |
+| `MP_RETRIEVE_END` | `device`, `retrieved_count`, `engine_id`, `model_name`, `cache_salt`, `total_bytes` | `str`, `int`, `int`, `str`, `str`, `int` |
+| `MP_LOOKUP_PREFETCH_START` | *(none)* | — |
+| `MP_LOOKUP_PREFETCH_END` | `found_count`, `requested_tokens`, `hit_tokens`, `model_name`, `cache_salt` | `int`, `int`, `int`, `str`, `str` |
+| `MP_LOOKUP` | `request_id`, `chunk_hashes`, `model_name`, `chunk_size`, `seq_len`, `dtypes`, `shapes` | `str`, `list[str]`, `str`, `int`, `int`, `list[str]`, `list[list[int]]` |
+| `MP_VLLM_BLOCK_ALLOCATION` | `instance_id`, `model_name`, `records` | `int`, `str`, `list[BlockAllocationRecord]` (each has `req_id: str`, `new_block_ids: list[int]`, `new_token_ids: list[int]`) |
+| `MP_VLLM_END_SESSION` | `request_id` | `str` |
+
+### `MP_LOOKUP_PREFETCH_END` metadata
+
+`found_count` is the contiguous prefix hit at chunk granularity, already
+divided by `world_size` at the emit site.  `requested_tokens` and
+`hit_tokens` are denormalized token-level counts so subscribers need not
+know `chunk_size`:
+
+- `requested_tokens = len(chunk_hashes) * chunk_size` on the happy path; `0`
+  on the two early-exit paths in `lookup()` (no matching GPU context,
+  empty `chunk_hashes`).  Sub-chunk trailing tokens are excluded — they
+  cannot hit at chunk granularity.
+- `hit_tokens = found_count * chunk_size`.
+- `model_name` and `cache_salt` are captured at lookup time from
+  `IPCCacheServerKey` and surface as OTel attributes on the
+  `lmcache_mp.lookup_*_tokens` counters so the hit rate can be sliced
+  per model and per tenant / isolation domain on the dashboard.
+  `cache_salt` may have high cardinality (e.g. one entry per tenant);
+  operators can drop the label at scrape time with a `metric_relabel_configs`
+  rule if storage cost matters.
+
+Together they drive the `lmcache_mp.lookup_*_tokens` counters used to
+compute the L1+L2 token-level hit rate.  See
+[L1_L2_HIT_RATE_PLAN.md](L1_L2_HIT_RATE_PLAN.md) for the design.
+
+---
+
+## Trace Recording Events
+
+A single unified event used by the `@enable_tracing` decorator (see
+[trace.md](trace.md)). All instrumented call sites publish the same
+`EventType` regardless of which method or layer; the `qualname` field
+inside `metadata` discriminates ops.
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `TRACE_CALL` | `qualname`, `args` | `str`, `dict[str, Any]` (codec-encoded; see `lmcache.v1.mp_observability.trace.codecs`) |
+
+---
+
+## Blend Server Lifecycle Sentinels
+
+CPU-synchronous sentinels published by `blend_server_v2.py` to bracket
+request scope and guard GPU callback races.  Published via `EventBus.publish()`
+(not `publish_on_stream`).
+
+| EventType | Metadata keys | Types | Published by / when |
+|---|---|---|---|
+| `CB_REQUEST_START` | *(none)* | — | `BlendEngineV2.cb_lookup_pre_computed` — at request arrival |
+| `CB_STORE_PRE_COMPUTED_SUBMITTED` | `instance_id` | `int` | `BlendEngineV2.cb_store_pre_computed` — before GPU store enqueue |
+| `CB_RETRIEVE_SUBMITTED` | `instance_id` | `int` | `BlendEngineV2.cb_retrieve_pre_computed` — before GPU retrieve enqueue |
+| `CB_STORE_FINAL_SUBMITTED` | `instance_id` | `int` | `BlendEngineV2.cb_store_final` — before GPU store enqueue |
+| `CB_REQUEST_END` | *(none)* | — | `BlendEngineV2.cb_lookup_pre_computed` (early return: no matches or no GPU context) **or** `BlendEngineV2.cb_store_final` — after SUBMITTED, before GPU work |
+
+---
+
+## Blend Server Events
+
+These events use `session_id` on the `Event` dataclass (sourced from
+`IPCCacheServerKey.request_id`) to correlate START/END pairs.
+
+| EventType | Metadata keys | Types |
+|---|---|---|
+| `CB_LOOKUP_START` | `num_tokens` | `int` |
+| `CB_LOOKUP_END` | `num_tokens`, `requested_tokens`, `hit_tokens`, `fingerprint_hits`, `storage_hits`, `stale_chunks`, `no_gpu_context` | `int`, `int`, `int`, `int`, `int`, `int`, `bool` |
+| `CB_STORE_PRE_COMPUTED_START` | `instance_id`, `num_tokens` | `int`, `int` |
+| `CB_STORE_PRE_COMPUTED_END` | `instance_id`, `num_tokens`, `stored_chunks`, `success` | `int`, `int`, `int`, `bool` |
+| `CB_RETRIEVE_START` | `instance_id`, `num_chunks` | `int`, `int` |
+| `CB_RETRIEVE_END` | `instance_id`, `num_chunks`, `success` | `int`, `int`, `bool` |
+| `CB_STORE_FINAL_START` | `instance_id`, `num_tokens` | `int`, `int` |
+| `CB_STORE_FINAL_END` | `instance_id`, `num_tokens`, `stored_chunks`, `success` | `int`, `int`, `int`, `bool` |
+| `CB_FINGERPRINTS_REGISTERED` | `num_chunks`, `num_tokens` | `int`, `int` |
+| `CB_CHUNKS_EVICTED` | `num_chunks` | `int` |
diff --git a/docs/design/v1/mp_observability/METRICS.md b/docs/design/v1/mp_observability/METRICS.md
new file mode 100644
index 0000000..88bf56f
--- /dev/null
+++ b/docs/design/v1/mp_observability/METRICS.md
@@ -0,0 +1,543 @@
+# LMCache MP Mode Observability Metrics
+
+## Overview
+
+The observability system uses an **EventBus with pub/sub dispatch** and
+**OpenTelemetry** for metrics instrumentation.
+
+- **Producers** (`L1Manager`, `StorageManager`, `MPCacheServer`) publish `Event` objects
+  to the EventBus.
+- **Metrics subscribers** (e.g. `L1MetricsSubscriber`, `L2MetricsSubscriber`) subscribe to
+  specific event types and update OTel counters.
+- **Logging subscribers** (`MPServerLoggingSubscriber`) log events at debug level.
+- **Tracing subscribers** (`MPServerTracingSubscriber`) create OTel spans from START/END pairs.
+- **Export** is via OTLP push to an OTel collector (production) or an in-process
+  Prometheus `/metrics` endpoint (dev/debug fallback).
+
+All metrics use the `lmcache_mp.` prefix (mp = multiprocess), distinct from the main
+engine's `lmcache.` namespace. On Prometheus, `.` is converted to `_` and counters get
+a `_total` suffix (e.g., `lmcache_mp.l1_read` with `unit="chunks"` is exposed as
+`lmcache_mp_l1_read_chunks_total`).
+
+For implementation guidance on adding new events and subscribers, see [README.md](README.md).
+
+## Global Resource Attributes
+
+Every metric (and span) exported by an MP server carries Resource-level
+attributes built at startup:
+
+| Attribute | CLI flag | Source | Applies to |
+|---|---|---|---|
+| `service.instance.id` | `--instance-id` | `MPServerConfig.instance_id` (defaults to a random UUID v4 at startup; projected onto `ObservabilityConfig.service_instance_id` by `run_cache_server` so telemetry and coordinator membership share one id) | All metrics + spans |
+
+Resource attributes are attached to the `MeterProvider` / `TracerProvider`
+in `otel_init.py` and therefore appear on every datapoint exported via
+OTLP.  On Prometheus, SDK resource attributes are typically surfaced via
+the `target_info` series rather than on each time-series.
+
+Per-metric attributes (e.g. `cache_salt`) remain on the individual
+datapoints and are orthogonal to these Resource attributes.
+
+---
+
+## L1 Read Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l1_read` | `lmcache_mp_l1_read_chunks_total` | Counter (attr: `cache_salt`) | `L1_READ_FINISHED` | `+len(keys)` per `cache_salt` |
+
+**What it answers:** How many chunks are being read from L1?
+
+> **Note:** `L1_READ_RESERVED` is published but has no metrics subscriber — key counts
+> are recorded only when the read actually completes.
+
+---
+
+## L1 Write Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l1_write` | `lmcache_mp_l1_write_chunks_total` | Counter (attr: `cache_salt`) | `L1_WRITE_FINISHED` | `+len(keys)` per `cache_salt` |
+| *(same counter)* | *(same)* | Counter (attr: `cache_salt`) | `L1_WRITE_FINISHED_AND_READ_RESERVED` | `+len(keys)` per `cache_salt` |
+
+**What it answers:** How many chunks are being written to L1?
+
+> **Note:** `L1_WRITE_RESERVED` is published but has no metrics subscriber.
+> `L1_WRITE_FINISHED_AND_READ_RESERVED` (atomic write-then-read used by prefetch)
+> increments the same write counter.
+
+---
+
+## L1 Eviction Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l1_evicted` | `lmcache_mp_l1_evicted_chunks_total` | Counter (attr: `cache_salt`) | `L1_KEYS_EVICTED` | `+len(keys)` per `cache_salt` |
+| `lmcache_mp.l1_eviction_loop_ticks` | `lmcache_mp_l1_eviction_loop_ticks_total` | Counter | `L1_EVICTION_LOOP_TICK` | +1 per loop iteration |
+| `lmcache_mp.l1_eviction_loop_triggered` | `lmcache_mp_l1_eviction_loop_triggered_total` | Counter | `L1_EVICTION_LOOP_TICK` | +1 when `triggered=True` |
+| `lmcache_mp.l1_usage_ratio` | `lmcache_mp_l1_usage_ratio` | Observable Gauge | (callback on `L1Manager`) | `used / total` at scrape time |
+
+**What it answers:** How aggressively is the eviction controller clearing L1?  Is the eviction loop alive but staying below the watermark, or actively firing?  What is the current L1 fullness?
+
+The two loop counters distinguish "loop is alive" from "eviction fired" — important when debugging short-lived benchmarks (a workload that completes in <1 s never gives the 1Hz polling loop a chance to fire even when usage exceeds the watermark).  `l1_usage_ratio` is registered via :func:`register_gauge` against `L1Manager`, so its value reflects current state at scrape time, not a per-tick sample.
+
+---
+
+## L1 Failure Metrics (LM-291 health monitoring)
+
+Tagged counters covering L1 allocation and read failures. The subscriber
+groups keys by `ObjectKey.model_name` to emit a `model_name` OTel
+attribute on every data point, enabling per-model Prometheus slicing
+(e.g. `lmcache_mp_l1_allocation_failure_total{during="l1_store",model_name="llama-7b"}`).
+
+The ticket-specified `lmcache_instance_id` tag is **deferred** to a
+follow-up: threading it through `StorageManager`/`StoreController` would
+require a cross-cutting API change out of scope for this PR.
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation | Tags |
+|---|---|---|---|---|---|
+| `lmcache_mp.l1_allocation_failure` | `lmcache_mp_l1_allocation_failure_chunks_total` | Counter | `L1_ALLOCATION_FAILED` | `+count` per `(during, model_name)` bucket | `during` ∈ {`l1_store`, `l2_prefetch`}, `model_name` |
+| `lmcache_mp.l1_read_failure` | `lmcache_mp_l1_read_failure_chunks_total` | Counter | `L1_READ_FAILED` | `+count` per `(during, reason, model_name)` bucket | `during` ∈ {`l2_store`, `l1_retrieve`}, `reason` ∈ {`not_found`, `write_locked`}, `model_name` |
+
+**What it answers:**
+- `l1_allocation_failure` — how often is L1 rejecting writes for lack of memory, split by whether the pressure is user stores or L2 prefetch?
+- `l1_read_failure` — a **post-lookup anomaly counter**, not a cache-miss counter. Should stay near zero in healthy operation; any non-zero value indicates a lookup/reserve race or unexpected eviction in MP mode.
+
+---
+
+## Timeout Metrics
+
+Cross-component anomaly counter. Incremented once per `LMCacheTimeoutError`
+constructed (see `errors.py` and the `TIMEOUT_RAISED` event in
+[EVENTS.md](EVENTS.md)), tagged by `exception_type` so operators can alert on
+the timeout rate per class.
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation | Tags |
+|---|---|---|---|---|---|
+| `lmcache_mp.timeouts` | `lmcache_mp_timeouts_total` | Counter | `TIMEOUT_RAISED` | `+1` per event | `exception_type` |
+
+**What it answers:** how often are operations timing out, and of which kind?
+Should stay near zero in healthy operation; a rising rate signals an
+overloaded or stuck MQ/transfer/adapter path.
+
+---
+
+## L1 Chunk Lifecycle Histograms
+
+Sampled (default 1%) chunk-level lifecycle tracking.  Only sampled chunks
+contribute to histograms; counters above always count all events.
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l1_chunk_lifetime` | `lmcache_mp_l1_chunk_lifetime_seconds` | Histogram | `L1_KEYS_EVICTED` | `eviction_time - alloc_time` per sampled chunk |
+| `lmcache_mp.l1_chunk_idle_before_evict` | `lmcache_mp_l1_chunk_idle_before_evict_seconds` | Histogram | `L1_KEYS_EVICTED` | `eviction_time - last_access_time` per sampled chunk |
+| `lmcache_mp.l1_chunk_reuse_gap` | `lmcache_mp_l1_chunk_reuse_gap_seconds` | Histogram | `L1_READ_FINISHED`, `L1_WRITE_FINISHED`, `L1_WRITE_FINISHED_AND_READ_RESERVED` | Time gap between consecutive touches of the same chunk |
+| `lmcache_mp.l1_chunk_evict_reuse_gap` | `lmcache_mp_l1_chunk_evict_reuse_gap_seconds` | Histogram | `L1_KEYS_EVICTED` → `L1_WRITE_FINISHED` | Time from eviction to next reuse (capped at 300 s) |
+| `lmcache_mp.real_reuse_gap` | `lmcache_mp_real_reuse_gap_seconds` | Histogram (tagged `cache_salt`) | `SM_READ_PREFETCHED_FINISHED`, `SM_WRITE_FINISHED` | Time gap between a chunk's last access (read or write) and the next read.  Captures **storage cost**.  Emitted only on read events. |
+| `lmcache_mp.real_reuse_gap_objects` | `lmcache_mp_real_reuse_gap_objects_chunks` | Histogram (tagged `cache_salt`) | `SM_READ_PREFETCHED_FINISHED`, `SM_WRITE_FINISHED` | Per-`cache_salt` access-counter gap between two reads of the same chunk.  Counter bumps on every read and write of every chunk; histogram emitted only on read events for sampled chunks.  Captures **storage volume**. |
+
+**What it answers:** How long do L1 chunks live? How idle are they before eviction? How quickly are evicted chunks reused?
+
+---
+
+
+## L2 Store Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l2_store_submitted` | `lmcache_mp_l2_store_submitted_requests_total` | Counter | `L2_STORE_SUBMITTED` | +1 per event |
+| `lmcache_mp.l2_store_submitted_objects` | `lmcache_mp_l2_store_submitted_objects_chunks_total` | Counter (attr: `cache_salt`) | `L2_STORE_SUBMITTED` | `+count` per `cache_salt` via `key_count_per_salt` |
+| `lmcache_mp.l2_store_completed` | `lmcache_mp_l2_store_completed_requests_total` | Counter (attr: `l2_name`) | `L2_STORE_COMPLETED` | +1 per event |
+| `lmcache_mp.l2_store_completed_objects` | `lmcache_mp_l2_store_completed_objects_chunks_total` | Counter (attr: `cache_salt`) | `L2_STORE_COMPLETED` | `+count` per `cache_salt` via `key_count_per_salt` |
+
+**What it answers:** How many chunks are being pushed to L2? What fraction fail?
+
+---
+
+## L2 Prefetch Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l2_prefetch_lookup` | `lmcache_mp_l2_prefetch_lookup_requests_total` | Counter | `L2_PREFETCH_LOOKUP_SUBMITTED` | +1 per event |
+| `lmcache_mp.l2_prefetch_lookup_objects` | `lmcache_mp_l2_prefetch_lookup_objects_chunks_total` | Counter (attr: `cache_salt`) | `L2_PREFETCH_LOOKUP_SUBMITTED` | `+count` per `cache_salt` via `key_count_per_salt` |
+| `lmcache_mp.l2_prefetch_hit` | `lmcache_mp_l2_prefetch_hit_chunks_total` | Counter | `L2_PREFETCH_LOOKUP_COMPLETED` | `+prefix_hit_count` |
+| `lmcache_mp.l2_prefetch_load_submitted` | `lmcache_mp_l2_prefetch_load_submitted_requests_total` | Counter | `L2_PREFETCH_LOAD_SUBMITTED` | `+adapter_count` (per-adapter task count) |
+| `lmcache_mp.l2_prefetch_load_submitted_objects` | `lmcache_mp_l2_prefetch_load_submitted_objects_chunks_total` | Counter (attr: `cache_salt`) | `L2_PREFETCH_LOAD_SUBMITTED` | `+count` per `cache_salt` via `key_count_per_salt` |
+| `lmcache_mp.l2_prefetch_load_completed` | `lmcache_mp_l2_prefetch_load_completed_chunks_total` | Counter (attr: `cache_salt`) | `L2_PREFETCH_LOAD_COMPLETED` | `+count` per `cache_salt` via `key_count_per_salt` |
+| `lmcache_mp.l2_load_completed` | `lmcache_mp_l2_load_completed_requests_total` | Counter (attr: `l2_name`) | `L2_LOAD_TASK_COMPLETED` | +1 per event |
+
+**What it answers:** How effective is L2 prefetching? What is the L2 hit rate?
+
+**Per-backend IOPS.**  `lmcache_mp.l2_store_completed` (attr `l2_name`) counts
+completed L1→L2 store tasks; `lmcache_mp.l2_load_completed` (attr `l2_name`)
+counts completed per-adapter L2→L1 load tasks.  Derive per-backend ops/sec on
+the dashboard with
+`rate(lmcache_mp_l2_store_completed_requests_total{l2_name="..."}[1m])`
+(and the equivalent for loads).  No separate `*_iops` metric is exported — the
+raw counter keeps the window choice in the dashboard.
+
+---
+
+## L2 Eviction Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l2_evicted_objects` | `lmcache_mp_l2_evicted_chunks_total` | Counter (attr: `cache_salt`) | `L2_KEYS_EVICTED` | `+count` per `cache_salt` via `key_count_per_salt` |
+
+**What it answers:** How many chunks are being evicted from L2? Which tenants are losing data?
+
+---
+
+## Lookup Hit-Rate Metrics (L1 + L2 combined)
+
+Token-level counters derived from the `MP_LOOKUP_PREFETCH_END` event.  Their
+ratio is the fraction of tokens requested by a lookup that were served from
+either L1 or L2.  L0 (GPU prefix cache) is intentionally excluded — it is
+vLLM-owned and not observable from LMCache.
+
+Both counters carry `model_name` and `cache_salt` OTel attributes (captured
+at lookup time from `IPCCacheServerKey`), enabling per-model and per-tenant
+slicing of the hit rate.  `cache_salt` can be high-cardinality; drop it at
+scrape time with `metric_relabel_configs` if storage cost matters.
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.lookup_requested` | `lmcache_mp_lookup_requested_tokens_total` | Counter (attrs: `model_name`, `cache_salt`) | `MP_LOOKUP_PREFETCH_END` | `+requested_tokens` |
+| `lmcache_mp.lookup_hit` | `lmcache_mp_lookup_hit_tokens_total` | Counter (attrs: `model_name`, `cache_salt`) | `MP_LOOKUP_PREFETCH_END` | `+hit_tokens` |
+
+**What it answers:** What fraction of tokens requested by a lookup were served from cache (L1 or L2)?
+
+```promql
+# Aggregate hit rate (all models, all salts):
+rate(lmcache_mp_lookup_hit_tokens_total[5m])
+/ rate(lmcache_mp_lookup_requested_tokens_total[5m])
+
+# Per-model hit rate:
+sum(rate(lmcache_mp_lookup_hit_tokens_total[5m])) by (model_name)
+/ sum(rate(lmcache_mp_lookup_requested_tokens_total[5m])) by (model_name)
+```
+
+> **Note:** Both counters are driven by the *same* event, so they always
+> advance together per completed lookup.  Early-exit lookups (no GPU
+> context matches, empty `chunk_hashes`) contribute `0` to both, and
+> abandoned lookups (client never polls `query_prefetch_status`)
+> contribute to neither.  See
+> [L1_L2_HIT_RATE_PLAN.md](L1_L2_HIT_RATE_PLAN.md) for the full rationale.
+
+---
+
+## L2 Failure Metrics (LM-291 health monitoring)
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation | Tags |
+|---|---|---|---|---|---|
+| `lmcache_mp.l2_prefetch_failure` | `lmcache_mp_l2_prefetch_failure_chunks_total` | Counter | `L2_PREFETCH_FAILED` | `+count` per `(reason, model_name)` bucket | `reason` ∈ {`l1_oom`, `not_found`}, `model_name` |
+
+**What it answers:** For keys L2 reported present at lookup but failed to land in L1: was L1 full (`l1_oom`), or did the adapter fail to produce the data (`not_found`)?
+
+> **Serde failures**: a third `reason=serde_failure` value will be added as an additive, non-breaking extension once the serde PR lands and L2 adapters distinguish deserialization errors from missing objects. No dashboard migration needed when that happens.
+
+> **TTL lock expiration**: `lmcache_mp.l1_ttl_lock_expire` from the ticket is deferred to a follow-up because the current `TTLLock` primitive (native) has no expiration callback; lazy detection requires a C++/Rust-side change.
+
+---
+
+## L0 (GPU) Block Lifecycle Histograms
+
+Sampled (default 1%) GPU KV cache block lifecycle tracking via shadow monitoring
+of `MP_VLLM_BLOCK_ALLOCATION` and `MP_VLLM_END_SESSION` events.  Eviction is
+detected at reallocation time (when a block is assigned different tokens).
+
+All L0 histograms carry `instance_id` and `model_name` OTel attributes, enabling
+per-instance and per-model Prometheus metric slicing (e.g.
+`lmcache_mp_l0_block_lifetime_seconds{instance_id="12345",model_name="llama-7b"}`).
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l0_block_lifetime` | `lmcache_mp_l0_block_lifetime_seconds` | Histogram | `MP_VLLM_BLOCK_ALLOCATION` (eviction detected) | `eviction_time - alloc_time` per sampled block |
+| `lmcache_mp.l0_block_idle_before_evict` | `lmcache_mp_l0_block_idle_before_evict_seconds` | Histogram | `MP_VLLM_BLOCK_ALLOCATION` (eviction detected) | `eviction_time - last_access_time` per sampled block |
+| `lmcache_mp.l0_block_reuse_gap` | `lmcache_mp_l0_block_reuse_gap_seconds` | Histogram | `MP_VLLM_BLOCK_ALLOCATION` (cache hit) | Time gaps between consecutive accesses from access history |
+
+**What it answers:** How long do GPU blocks live before eviction? How idle are they? How frequently are cached blocks reused? Which instance/model is experiencing the most churn?
+
+---
+
+## L0 ↔ L1 Throughput Histograms
+
+Per-request throughput of GPU↔CPU copies via
+`L0L1ThroughputSubscriber`. Correlates `MP_{STORE,RETRIEVE}_START` → `MP_{STORE,RETRIEVE}_END`
+pairs by `session_id`, computes `total_bytes / (end_ts - start_ts)` in GB/s.
+Every request contributes one sample (no sampling).
+START/END events fire on the GPU cupy stream (`publish_on_stream`), so
+timestamps reflect true GPU-stream copy time — not Python/lock overhead.
+
+All throughput histograms carry `engine_id` (vLLM worker instance id),
+`device` (e.g. `"cuda:3"`), and `model_name` OTel attributes, enabling
+per-worker, per-device, and per-model slicing in Prometheus (e.g.
+`lmcache_mp_l0_l1_store_throughput_gbs{engine_id="0",device="cuda:3",model_name="meta-llama/Llama-3.1-8B"}`).
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l0_l1_store_throughput` | `lmcache_mp_l0_l1_store_throughput_GBs` | Histogram | `MP_STORE_START` → `MP_STORE_END` | `total_bytes / (end_ts - start_ts) / 1e9` per request |
+| `lmcache_mp.l0_l1_load_throughput` | `lmcache_mp_l0_l1_load_throughput_GBs` | Histogram | `MP_RETRIEVE_START` → `MP_RETRIEVE_END` | `total_bytes / (end_ts - start_ts) / 1e9` per request |
+
+**What it answers:** What GPU↔CPU throughput is each vLLM worker actually
+achieving for KV store/load? Does it match the theoretical PCIe bandwidth?
+Are some workers or GPUs underperforming?
+
+---
+
+## L1 ↔ L2 Throughput Histograms
+
+Per-task throughput of L1↔L2 transfers via
+`L2ThroughputSubscriber`. The store path correlates `L2_STORE_SUBMITTED` →
+`L2_STORE_COMPLETED` by `(adapter_index, task_id)`. The load path
+correlates the new per-adapter `L2_LOAD_TASK_SUBMITTED` →
+`L2_LOAD_TASK_COMPLETED` events by `(request_id, adapter_index)`; the
+pre-existing request-level `L2_PREFETCH_LOAD_*` events aggregate across
+adapters and cannot attribute throughput to a specific `l2_name`.
+Every task contributes one sample (no sampling).
+
+Unlike the L0↔L1 histograms, these timestamps span **submit → complete**,
+so `(end_ts - start_ts)` includes adapter queue, network, and disk I/O
+time. Treat the value as *bytes / end-to-end latency*, not raw transfer
+rate — useful for comparing adapter types and tracking regressions, not
+for validating peak fabric bandwidth.
+
+All throughput histograms carry a single `l2_name` OTel attribute — the
+registered adapter type (e.g. `"fs"`, `"nixl_store"`, `"mooncake_store"`)
+— enabling per-adapter-type slicing in Prometheus (e.g.
+`lmcache_mp_l2_store_throughput_gbs{l2_name="nixl_store"}`).
+
+**Store-path fast-path accounting.** Some adapters skip the write when
+a key is already present in the backend, collapsing
+`(completed_ts - submitted_ts)` to near-zero while the submitted
+`total_bytes` count stays unchanged. To avoid inflated throughput
+samples, the `L2StoreResult` returned by `pop_completed_store_tasks()`
+carries `bytes_transferred()` covering only the bytes actually written.
+The `L2_STORE_COMPLETED` event propagates this value, and the store
+throughput subscriber records `bytes_transferred / dt`; when
+`bytes_transferred <= 0` (every key fast-pathed) the sample is dropped
+entirely. The load path continues to use the submitted `total_bytes`.
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l2_store_throughput` | `lmcache_mp_l2_store_throughput_GBs` | Histogram | `L2_STORE_SUBMITTED` → `L2_STORE_COMPLETED` | `bytes_transferred / (completed_ts - submitted_ts) / 1e9` per task. `bytes_transferred` is read from the `L2_STORE_COMPLETED` event (populated from the `L2StoreResult` returned by `pop_completed_store_tasks()`); samples where `bytes_transferred <= 0` (e.g. duplicate-key fast paths that skip the write) are dropped, so the histogram reflects real work, not submitted-but-skipped bytes. |
+| `lmcache_mp.l2_load_throughput` | `lmcache_mp_l2_load_throughput_GBs` | Histogram | `L2_LOAD_TASK_SUBMITTED` → `L2_LOAD_TASK_COMPLETED` | `total_bytes / (completed_ts - submitted_ts) / 1e9` per (request, adapter) pair. The load path still uses submitted `total_bytes`; per-task real-bytes accounting only applies to the store path. |
+
+**What it answers:** What end-to-end throughput is each L2 adapter
+delivering? Which backends are keeping up with demand, and which are
+queue-bound or I/O-bound?
+
+---
+
+## Engine Counters
+
+Worker-scoped counters tied to what the MP server delivers back to each
+vLLM worker.  Labeled by `worker_id` — the vLLM worker instance id,
+distinct from any scheduler-scoped id used elsewhere.
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.num_chunks_loaded` | `lmcache_mp_num_chunks_loaded_total` | Counter (attrs: `worker_id`, `model_name`, `cache_salt`) | `MP_RETRIEVE_END` | `+retrieved_count` per event |
+
+**What it answers:** How many LMCache chunks is each vLLM worker loading
+from LMCache into its engine?  Compare across workers to spot uneven
+demand or underserved ranks.  Slice by `model_name` to see per-model
+load volume in multi-model deployments, or by `cache_salt` for per-tenant
+attribution (note: `cache_salt` can be high-cardinality — drop it at
+scrape time with `metric_relabel_configs` if storage cost matters).
+
+---
+
+## EventBus Self-Monitoring
+
+Health metrics for the EventBus itself. The two gauges are registered
+inside `EventBus.__init__` via `register_gauge`; the two observable
+counters are registered by `EventBusSelfMetricsSubscriber`. Unlike the
+other metrics subscribers, these are not driven by events — they observe
+bus state directly via the `EventBus` accessors and report on every OTel
+scrape.
+
+| OTel metric name | Prometheus name | Type | Source | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.event_bus.queue_depth` | `lmcache_mp_event_bus_queue_depth` | ObservableGauge | `EventBus.queue_depth()` | `len(_queue)` at scrape time |
+| `lmcache_mp.event_bus.drain_lag_seconds` | `lmcache_mp_event_bus_drain_lag_seconds` | ObservableGauge | `EventBus.oldest_event_lag_seconds()` | `time.time() - oldest.timestamp`, or `0.0` when empty |
+| `lmcache_mp.event_bus.dropped_events_total` | `lmcache_mp_event_bus_dropped_events_total` | ObservableCounter | `EventBus.dropped_events_count()` | cumulative `_discard_count` |
+| `lmcache_mp.event_bus.subscriber_exceptions` | `lmcache_mp_event_bus_subscriber_exceptions_total` | ObservableCounter (attr: `subscriber_name`) | `EventBus.subscriber_exception_counts()` | cumulative count per subscriber, incremented when `_drain_all` catches a callback exception |
+
+**What it answers:** Is the EventBus keeping up with publishers? Is anything being dropped? Are any subscriber callbacks raising?
+
+`subscriber_name` is derived from the failing callback: bound methods report their owning class (e.g. `L1MetricsSubscriber`); free functions report `__qualname__`.
+
+---
+
+## MPCacheServer Observable Gauges
+
+These metrics are registered directly via `register_gauge` (pull-based OTel
+observable gauges) rather than through the EventBus, because they represent
+point-in-time state snapshots that do not correspond to discrete events.
+
+| OTel metric name | Prometheus name | Type | Source | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.active_prefetch_jobs` | `lmcache_mp_active_prefetch_jobs` | ObservableGauge | `MPCacheServer._prefetch_jobs` | `len(_prefetch_jobs)` at scrape time |
+
+**What it answers:** How many prefetch jobs are currently in-flight? A sustained high value may indicate slow L2 backends or client-side polling delays.
+
+---
+
+## L1 / L2 State Metrics
+
+Live state of the L1 memory pool, the per-adapter L2 byte usage, and the
+in-flight L2 store / prefetch-load queues.  These metrics are useful for
+capacity planning, sizing L1, watching L2 fullness, and spotting
+backpressure on individual L2 adapters.
+
+All five metrics are OTel `ObservableGauge` instruments registered via the
+shared `register_gauge` helper.  At scrape time, OTel invokes the
+registered callback, which iterates the controller's live state and
+returns one observation per adapter (for `l2_usage_bytes`, one per
+configured adapter; for the in-flight gauges, only adapters with work).
+Adapters with no in-flight work emit no datapoint for the three
+in-flight gauges.
+
+`lmcache_mp.l2_usage_bytes` carries a single `l2_name` attribute — the
+adapter's registered type name (e.g. `"fs"`, `"mock"`,
+`"nixl_store"`).  The three in-flight metrics carry two attributes
+that disambiguate adapters even when more than one is registered with
+the same backend type — same shape as the existing
+`lmcache_mp.l2_store_completed` counter:
+
+- `l2_name` — the registered adapter type (e.g. `"fs"`, `"mock"`,
+  `"nixl_store"`).
+- `adapter_index` — position in the `StoreController`/`PrefetchController`
+  adapter list.  Distinguishes two adapters of the same type (e.g.
+  `fs[0]` and `fs[1]`).
+
+| OTel metric name | Prometheus name | Type | Source of truth | Calculation |
+|---|---|---|---|---|
+| `lmcache_mp.l1_memory_usage_bytes` | `lmcache_mp_l1_memory_usage_bytes` | ObservableGauge | `L1Manager.get_memory_usage()` | Bytes currently held in L1 at scrape time |
+| `lmcache_mp.l2_usage_bytes` | `lmcache_mp_l2_usage_bytes` | ObservableGauge (attr: `l2_name`) | `StorageManager.get_l2_usages()` (calls `L2AdapterInterface.get_usage().total_bytes_used`) | Per-adapter bytes currently held in L2 at scrape time; one observation per configured adapter.  Adapters whose `get_usage()` raises are skipped silently. |
+| `lmcache_mp.num_inflight_l2_stores` | `lmcache_mp_num_inflight_l2_stores` | ObservableGauge (attrs: `l2_name`, `adapter_index`) | `StoreController.get_inflight_count_by_adapter()` | Snapshot of in-flight L2 store tasks grouped by adapter |
+| `lmcache_mp.num_inflight_l2_loads` | `lmcache_mp_num_inflight_l2_loads` | ObservableGauge (attrs: `l2_name`, `adapter_index`) | `PrefetchController.get_inflight_load_state_by_adapter()` | Per-adapter count from the same snapshot |
+| `lmcache_mp.inflight_load_memory_usage_bytes` | `lmcache_mp_inflight_load_memory_usage_bytes` | ObservableGauge (attrs: `l2_name`, `adapter_index`) | `PrefetchController.get_inflight_load_state_by_adapter()` | Per-adapter reserved bytes from the same snapshot |
+
+**What `l1_memory_usage_bytes` answers:** How full is the L1 cache? Helps
+size L1 against working set and detect leaks (steadily climbing without
+plateauing).
+
+**What `l2_usage_bytes` answers:** How full is each L2 backend? Lets
+operators query how much each L2 tier currently holds, decide whether
+an adapter needs eviction or purge, and spot per-backend asymmetries
+when more than one L2 is configured.  Parallel to `l1_memory_usage_bytes`
+on the L2 tier.
+
+**What `num_inflight_l2_stores` answers:** Are L2 stores piling up on a
+particular adapter? Sustained non-zero values indicate the adapter cannot
+keep up with the L1 → L2 write rate.
+
+**What `num_inflight_l2_loads` answers:** Are L2 → L1 prefetch loads
+backing up? Pair with `num_inflight_l2_stores` to see whether read or
+write traffic dominates a given backend.
+
+**What `inflight_load_memory_usage_bytes` answers:** How much L1 capacity
+is currently *reserved but not yet filled* by in-flight prefetches? Rising
+in-flight bytes alongside rising `l1_memory_usage_bytes` is a signal that
+prefetch reservations are crowding out cacheable data.
+
+> **Bytes attribution.** A single prefetch request may load from multiple
+> adapters.  The byte count is split per-adapter via the request's
+> `load_plan` bitmap × per-key `MemoryObj.size` (precomputed at submit
+> time and stored on `InFlightPrefetchRequest.load_bytes_by_adapter`) so
+> each in-flight byte is attributed to exactly one `(l2_name,
+> adapter_index)` pair — sums across adapters are not double-counted.
+
+> **Singleton dispatch.** L1Manager / StoreController / PrefetchController
+> are singletons in MP mode.  Each controller registers its gauge once
+> (guarded by a class-level `_gauge_registered` flag) and the callback
+> dispatches via a class-level `_gauge_target` so the most recently
+> constructed instance owns the reported values.  This is invisible in
+> production (one instance per process); it matters in tests that create
+> multiple controllers.
+
+> **Thread safety.** Callbacks run on the OTel reader thread and read
+> state mutated by the controller's background loop thread.  Snapshots
+> use `dict.copy()`, which is implemented in C and atomic under the
+> CPython GIL — concurrent mutation cannot crash the snapshot, though it
+> may briefly see a state that is one mutation stale.  Acceptable for a
+> 10-second scrape cadence.
+
+---
+
+## Cache Blending (CB) Metrics
+
+Metrics for Cache Blending operations use the `lmcache_blend.` prefix (distinct from the
+MP mode `lmcache_mp.` namespace).  On Prometheus, `.` becomes `_` and counters get
+`_total` suffix (e.g., `lmcache_blend_lookup_requests_total`).
+
+### CB Lookup Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_blend.lookup_requests` | `lmcache_blend_lookup_requests_total` | Counter | `CB_LOOKUP_START` | +1 per event |
+| `lmcache_blend.lookup_requested_tokens` | `lmcache_blend_lookup_requested_tokens_total` | Counter | `CB_LOOKUP_END` | `+requested_tokens` |
+| `lmcache_blend.lookup_hit_tokens` | `lmcache_blend_lookup_hit_tokens_total` | Counter | `CB_LOOKUP_END` | `+hit_tokens` |
+| `lmcache_blend.lookup_fingerprint_hits` | `lmcache_blend_lookup_fingerprint_hits_total` | Counter | `CB_LOOKUP_END` | `+fingerprint_hits` |
+| `lmcache_blend.lookup_storage_hits` | `lmcache_blend_lookup_storage_hits_total` | Counter | `CB_LOOKUP_END` | `+storage_hits` |
+| `lmcache_blend.lookup_stale_chunks` | `lmcache_blend_lookup_stale_chunks_total` | Counter | `CB_LOOKUP_END` | `+stale_chunks` |
+| `lmcache_blend.lookup_no_gpu_context_errors` | `lmcache_blend_lookup_no_gpu_context_errors_total` | Counter | `CB_LOOKUP_END` | +1 when `no_gpu_context=True` |
+
+**What it answers:** How often does the CB server receive lookup requests? What fraction of requested tokens are served by blend (token-level hit rate)? What fraction hit the fingerprint table? What fraction are confirmed in storage? How many stale evictions occur?
+
+**Blend token-level hit rate** (numerator and denominator co-emit on the same `CB_LOOKUP_END` event so the ratio is meaningful even under partial-failure paths):
+
+```
+rate(lmcache_blend_lookup_hit_tokens_total[5m])
+/ rate(lmcache_blend_lookup_requested_tokens_total[5m])
+```
+
+### CB Retrieve Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_blend.retrieve_requests` | `lmcache_blend_retrieve_requests_total` | Counter | `CB_RETRIEVE_START` | +1 per event |
+| `lmcache_blend.retrieve_chunks` | `lmcache_blend_retrieve_chunks_total` | Counter | `CB_RETRIEVE_START` | `+num_chunks` |
+| `lmcache_blend.retrieve_failures` | `lmcache_blend_retrieve_failures_total` | Counter | `CB_RETRIEVE_END` | +1 when `success=False` |
+
+**What it answers:** How often is CB retrieval invoked? How many chunks are retrieved per call? What is the failure rate?
+
+### CB Store Pre-computed Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_blend.store_pre_computed_requests` | `lmcache_blend_store_pre_computed_requests_total` | Counter | `CB_STORE_PRE_COMPUTED_START` | +1 per event |
+| `lmcache_blend.store_pre_computed_chunks` | `lmcache_blend_store_pre_computed_chunks_total` | Counter | `CB_STORE_PRE_COMPUTED_END` | `+stored_chunks` |
+| `lmcache_blend.store_pre_computed_failures` | `lmcache_blend_store_pre_computed_failures_total` | Counter | `CB_STORE_PRE_COMPUTED_END` | +1 when `success=False` |
+
+**What it answers:** How often is pre-computed CB storage invoked? How many chunks are written? What is the failure rate?
+
+### CB Store Final Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_blend.store_final_requests` | `lmcache_blend_store_final_requests_total` | Counter | `CB_STORE_FINAL_START` | +1 per event |
+| `lmcache_blend.store_final_chunks` | `lmcache_blend_store_final_chunks_total` | Counter | `CB_STORE_FINAL_END` | `+stored_chunks` |
+| `lmcache_blend.store_final_failures` | `lmcache_blend_store_final_failures_total` | Counter | `CB_STORE_FINAL_END` | +1 when `success=False` |
+
+**What it answers:** How often is final CB storage invoked? How many chunks are committed? What is the failure rate?
+
+### CB Fingerprint Table Metrics
+
+| OTel metric name | Prometheus name | Type | Source event | Calculation |
+|---|---|---|---|---|
+| `lmcache_blend.fingerprints_registered` | `lmcache_blend_fingerprints_registered_total` | Counter | `CB_FINGERPRINTS_REGISTERED` | `+num_chunks` |
+| `lmcache_blend.chunks_evicted` | `lmcache_blend_chunks_evicted_total` | Counter | `CB_CHUNKS_EVICTED` | `+num_chunks` |
+
+**What it answers:** How many chunks are indexed into the fingerprint table? How many stale entries are evicted?
+
+---
+
+For derivations of L1-only / L2-only / blend hit rates from these
+counters, and a "what to send when reporting" checklist, see
+[DEBUG.md](DEBUG.md).
+
+For event metadata contracts (what keys each `EventType` carries), see
+[EVENTS.md](EVENTS.md).
diff --git a/docs/design/v1/mp_observability/README.md b/docs/design/v1/mp_observability/README.md
new file mode 120000
index 0000000..9f67d59
--- /dev/null
+++ b/docs/design/v1/mp_observability/README.md
@@ -0,0 +1 @@
+../../../../lmcache/v1/mp_observability/README.md
\ No newline at end of file
diff --git a/docs/design/v1/mp_observability/blend_v3_observability.md b/docs/design/v1/mp_observability/blend_v3_observability.md
new file mode 100644
index 0000000..e0ad066
--- /dev/null
+++ b/docs/design/v1/mp_observability/blend_v3_observability.md
@@ -0,0 +1,209 @@
+# CacheBlend V3 Observability — Design
+
+**Status:** Proposal · **Scope:** unify CB V3 tracing across the vLLM plugin
+(scheduler + worker) and the LMCache blend server into one distributed trace,
+plus the metrics each side exposes.
+
+## 1. Goal
+
+A single CB request touches **three processes**:
+
+```
+vLLM scheduler ──CB_UNIFIED_LOOKUP──▶ LMCache blend server
+vLLM worker    ──CB_RETRIEVE_V3─────▶ LMCache blend server
+vLLM worker    ── model forward (FULL_RECOMP → CHECK → PARTIAL)
+```
+
+Today these are observed by **two disjoint systems**:
+
+| side | mechanism | output |
+|---|---|---|
+| LMCache blend server | EventBus → `BlendTracingSubscriber` (`subscribers/tracing/cb_server.py`) | **OTel spans** (`cb.request` + children), OTLP export |
+| vLLM plugin (connector/shim/attn) | `_cb_span` / `_cb_stats_emit` (`lmcache_cacheblend/connector.py`) | **ad-hoc JSONL** (`CB_PROFILE=1`) |
+
+They never share a trace: you cannot see, in one view, that a slow request's
+time went into the server-side L2 load vs the worker-side scatter vs the PARTIAL
+forward. **Goal: one `cb.request` trace spanning all three processes**, with
+sub-spans owned by whichever process did the work, plus aligned metrics.
+
+## 2. The unified trace model
+
+One trace per `request_id`. Process owner in brackets; cross-process children
+linked by trace-context propagation (§5).
+
+```
+cb.request                         [scheduler — root]  request_id, model, world_size, n_prompt_tokens
+│
+├─ cb.schedule                     [scheduler]  the get_num_new_matched_tokens defer loop
+│  ├─ cb.lookup.rpc                [scheduler]  CB_UNIFIED_LOOKUP incl. N poll re-issues; attr: n_polls
+│  │  └─ cb.lookup                 [SERVER]  ← cross-process child; attr prefix_chunks
+│  │     ├─ cb.fingerprint_match   [server]  n_probes, table_hits, matches (token-stride=1, any offset)
+│  │     │  (cb.coordinator_match instead, when a coordinator is configured)  matches, timed_out
+│  │     │  (no cb.prefix_lookup span — prefix is traced by mp.lookup_prefetch)
+│  │     ├─ cb.sparse_prefetch     [server]  n_keys, l1_hits, l2_misses
+│  │     │  └─ cb.l2_load          [server·IO]  chunks, bytes, ms        (coalesced L2→L1)
+│  │     └─ cb.classify            [server]  found, stale, per_rank_ok
+│  │        ↳ on end: stamp hit_rate / prefix_coverage_tokens / n_non_prefix_tokens on cb.request
+│  └─ cb.build_meta                [scheduler]  broadcast metadata to workers
+│
+└─ cb.execute                      [worker]
+   ├─ cb.start_load_kv             [worker]  submit + stream-wait (may fire 2×: partial→full block alloc)
+   │  └─ cb.retrieve               [SERVER]  ← cross-process child
+   │     └─ cb.scatter             [server·GPU]  scattered_tokens, n_prefix, n_shifted (re-RoPE'd), dropped
+   │        (re-RoPE folded in — interleaved per-batch, not a separate span)
+   └─ cb.model_forward             [worker]  the sliced forward
+      ├─ cb.full_recomp            [worker·GPU]  layers 0..cl-1
+      ├─ cb.check                  [worker·GPU]  layer cl; imp_count, recomp_ratio
+      └─ cb.partial                [worker·GPU]  layers cl+1..L; dispatch=flex|unified, imp_empty
+```
+
+This is the contract both sides implement against. The server owns `cb.lookup`
+and `cb.retrieve` subtrees; the plugin owns everything else.
+
+### 2.1 V3 reuse is token-granular (#3582)
+
+As of #3582, CB matches and scatters at **token** granularity, not vLLM-block /
+chunk granularity — which is what the spans/attrs below must reflect:
+
+- **Matching** runs at `probe_stride=1`, so the shared body is found at *any*
+  token offset (`cb_unified_lookup` no longer filters non-prefix matches to a
+  chunk-aligned `cur_st`). `cb.fingerprint_match` reports token-offset matches,
+  not aligned chunks.
+- **Scatter** writes per-token via `multi_layer_kv_transfer` with
+  `slot_mapping = block_id[pos // bs] * bs + pos % bs`. The reused token range is
+  written slot-by-slot, so a **partial vLLM block** holding both matched and
+  recomputed tokens is written correctly with **no block-alignment trim on the
+  write** — the old whole-block scatter path and block-aligned drop checks are
+  gone. `cb.scatter`'s unit is `scattered_tokens` / `slot_writes`.
+- **L2 storage stays chunk-granular** (256-token chunks): a non-block-aligned
+  match still fetches whole chunks (`cb.l2_load` = chunks/bytes), then
+  `cb.scatter` writes only the matched token sub-range. So `cb.l2_load` is
+  measured in chunks while `cb.scatter` is measured in tokens/slots.
+- **`cb.start_load_kv` may fire twice** (vLLM allocates the request's blocks
+  partial-then-full). The first pass writes only slots inside the
+  already-allocated block table — a slot-bound guard (`cur_ed > num_slots`),
+  *not* a block-alignment trim; the second writes the rest. Expect two
+  `cb.retrieve` children, the first with `scattered_tokens` < total.
+
+## 3. LMCache-server side — what to expose
+
+The server already emits `cb.request` / `cb.lookup` / `cb.retrieve` via the
+EventBus. Two changes:
+
+**(a) Finer V3 events for the lookup/retrieve subtrees.** V3 currently emits only
+`CB_LOOKUP_START/END` and `CB_RETRIEVE_START/END` — too coarse for the subtree in
+§2. Add paired events (CPU-sync for compute, `publish_on_stream` for GPU ops so
+timing is GPU-accurate):
+
+| new event pair | span | timing source |
+|---|---|---|
+| `CB_FINGERPRINT_MATCH_*` | `cb.fingerprint_match` | CPU |
+| `CB_COORDINATOR_MATCH_*` | `cb.coordinator_match` (fleet directory leg; mutually exclusive with the local matcher) | CPU + IO |
+| (prefix lookup) | `mp.lookup_prefetch` (reused; `prefix_chunks` attr on `cb.lookup`) | CPU |
+| `CB_SPARSE_PREFETCH_*` | `cb.sparse_prefetch` (+ existing L2 prefetch span as `cb.l2_load`) | CPU + IO |
+| `CB_SCATTER_*` | `cb.scatter` (re-RoPE folded in via `n_shifted`) | `publish_on_stream` (GPU) |
+
+`BlendTracingSubscriber.SPAN_DEFS` gains the matching entries; all nest under
+`cb.lookup` / `cb.retrieve` via the existing `SpanRegistry`.
+
+**(b) Simplify the deferral logic for the V3 model.** The current root-close
+deferral (`_waiting_for_store_final`, the `STORE_FINAL_SUBMITTED` bridge) is V2-only
+and **inert under V3** (V3 never emits those). Under V3 the request ends at
+`CB_RETRIEVE_END` (no async store-final after inference). Gate the `cb.request`
+close on `_pending_gpu_ops[sid] == 0` only, and drop the V2 store-final bridge
+from the V3 path. (The V2-only event handlers stay for `blend_legacy`.)
+
+**Span attributes (server):** `request_id`, `prefix_coverage_tokens`,
+`fingerprint_hits`, `storage_hits`, `stale_chunks`, `hit_tokens`,
+`requested_tokens`, `hit_rate`, `prefix_hit_tokens`, `non_prefix_hit_tokens`,
+`scatter_ms`, `scattered_tokens`, `slot_writes`, `partial_blocks`,
+`n_shifted_tokens`, `n_prefix_tokens` (token-granular per §2.1 — not chunks).
+
+**V3 hit rate.** `hit_rate = hit_tokens / requested_tokens`, where the numerator
+counts **both reuse paths**: `hit_tokens = prefix_hit_tokens +
+non_prefix_hit_tokens`. The two ranges are disjoint (the non-prefix complement
+is `cur_st >= prefix coverage`), so they sum without double-counting. Both
+components are also recorded individually on `cb.request` so a dashboard can
+split prefix-reuse vs re-RoPE'd non-prefix reuse.
+
+**Metrics (already present, keep):** the `lmcache_blend.*` counters
+(`lookup_requests`, `lookup_hit_tokens`, `lookup_storage_hits`,
+`lookup_stale_chunks`, `retrieve_requests`, `retrieve_failures`,
+`chunks_evicted`, …). Note the V2-only store counters won't populate under V3 —
+document, or recompute the "stored" notion from the unified path.
+
+## 4. vLLM-plugin side — what to expose
+
+The plugin's `_cb_span` spans (`sched.gnnmt`, `gnnmt.cb_unified_submit/poll`,
+`sched.build_meta`, `slk.*`, `shim.wrapper.{prepare,fwd}`, `flex.*`,
+`cb_admission_check`) already cover the §2 plugin subtree — but as **JSONL, not
+OTel**. Make `_cb_span` dual-mode:
+
+- when an OTel tracer is available → emit an **OTel span** (start/end, attributes);
+- always (under `CB_PROFILE`) → keep the JSONL line (cheap local profiling).
+
+Mapping plugin span → unified name: `sched.gnnmt`→`cb.schedule`,
+`gnnmt.cb_unified_*`→`cb.lookup.rpc`, `sched.build_meta`→`cb.build_meta`,
+`slk.*`→`cb.start_load_kv`, `shim.wrapper.fwd`→`cb.model_forward`,
+`flex.*` + the layer hooks → `cb.full_recomp`/`cb.check`/`cb.partial`.
+
+**Tracer source.** vLLM has its own OTel (`--otlp-traces-endpoint`) and creates a
+per-request span. Prefer to **reuse vLLM's tracer** so CB spans nest under vLLM's
+request span intra-process; if vLLM tracing is off, the plugin owns a tracer
+pointed at the same OTLP endpoint as the LMCache server. Gate on a single
+`CB_TRACING=1` (or reuse `--enable-tracing` semantics) so it's off by default.
+
+## 5. Unification — linking the three processes
+
+The blocker (from the surface map): **the RPC envelope carries no trace-context**
+— `IPCCacheServerKey` and `CBUnifiedLookupResult` have no `traceparent` field. Two
+ways to bridge:
+
+**Option A — propagate W3C trace-context through the RPC (recommended).**
+Add an optional `trace_context: str | None` (W3C `traceparent`) to the CB RPC
+payloads (the lookup key + the retrieve args). The scheduler/worker **inject**
+the current span's context; the server **extracts** it and starts `cb.lookup` /
+`cb.retrieve` as remote children of it. Result: a *true* parent→child distributed
+trace across processes. Cost: one optional protocol field (backward-compatible —
+`None` when tracing off), an `inject`/`extract` at the two RPC boundaries.
+
+**Option B — deterministic trace-id from `request_id` (zero protocol change).**
+Both sides derive a 128-bit trace-id `= hash(request_id)` and tag every span with
+it (+ `request_id` attribute). Backends group by trace-id, so the spans land in
+one trace — but there are **no cross-process parent links** (sibling spans, not
+nested). Use if the protocol field is undesirable short-term.
+
+**Recommendation:** Option A. The field is tiny, optional, and gives real
+parent/child causality (e.g. "the 90 ms gnnmt was 50 ms server L2-load + 40 ms
+poll-wait"). Keep `request_id` as a span attribute regardless, so Option B is a
+trivial fallback. The `SpanRegistry` already handles intra-process nesting on
+each side; Option A only adds the *cross*-process edge.
+
+## 6. Phasing
+
+1. **Plugin OTel** — make `_cb_span` dual-mode (OTel + JSONL); reuse vLLM's tracer;
+   gate with `CB_TRACING`. (plugin repo)
+2. **V3 server sub-spans** — add the §3(a) events + `SPAN_DEFS`; simplify the
+   §3(b) V3 deferral. (LMCache) — **DONE**: `cb.fingerprint_match` /
+   `cb.sparse_prefetch` nest under `cb.lookup` (prefix lookup reuses
+   `mp.lookup_prefetch`; `prefix_chunks` is a `cb.lookup` attr); `cb.scatter`
+   (re-RoPE folded) nests under `cb.retrieve`; `hit_rate` = prefix + non-prefix.
+   `cb.l2_load` GB/s is already covered by the existing `L2ThroughputSubscriber`
+   (`L2_LOAD_TASK_*`), correlated by request; nesting that span under
+   `cb.sparse_prefetch` is a cross-subsystem follow-up.
+3. **Cross-process link** — add the optional `trace_context` RPC field; inject on
+   the plugin side, extract on the server side. (both repos, in lockstep)
+4. **Dashboards** — one trace view + the `lmcache_blend.*` / plugin latency metrics
+   aligned on `request_id`.
+
+Each phase is independently useful (1 and 2 give per-process traces; 3 unifies).
+
+## 7. Open questions
+
+- Reuse vLLM's tracer/provider, or a CB-owned one? (affects nesting under vLLM's
+  request span vs a standalone `cb.request` root)
+- Is the protocol field (Option A) acceptable for upstream, or start with the
+  deterministic-trace-id fallback (Option B)?
+- Sampling: per-request tracing is expensive at scale — head sampling at the
+  scheduler (propagated via the same `trace_context`) so a sampled-out request is
+  cheap on all three processes.
diff --git a/docs/design/v1/mp_observability/errors.md b/docs/design/v1/mp_observability/errors.md
new file mode 100644
index 0000000..b8ffee2
--- /dev/null
+++ b/docs/design/v1/mp_observability/errors.md
@@ -0,0 +1,70 @@
+# Observability-aware errors (`errors.py`)
+
+`lmcache/v1/mp_observability/errors.py` defines `LMCacheTimeoutError`, a
+timeout exception that reports itself to the MP observability EventBus when it
+is constructed. It is the single place timeouts in `lmcache/` should be raised
+from; the `ban-raw-timeout-error` pre-commit hook enforces this by rejecting
+any bare `raise TimeoutError(...)` / `raise asyncio.TimeoutError(...)` under
+`lmcache/`.
+
+## Why
+
+Timeouts are the most common "something is stuck" failure in MP mode (MQ
+round-trips, GPU transfer waits, adapter drains, NIXL handshakes). Before this,
+each site raised the built-in `TimeoutError`, which left no trace in the
+observability stack — operators only learned of a timeout if the surrounding
+code happened to log it. Routing every timeout through one class makes them
+uniformly observable (counter + log + trace) without touching each call site
+beyond the class swap.
+
+## Contract
+
+`LMCacheTimeoutError(message: str, *, session_id: str = "")`
+
+- **Subclass of the built-in `TimeoutError`.** Every existing
+  `except TimeoutError` handler continues to catch it unchanged, so swapping a
+  raw `raise TimeoutError(...)` for `raise LMCacheTimeoutError(...)` is
+  behaviour-preserving. (On Python 3.11+ `asyncio.TimeoutError` is the same
+  type, so `except asyncio.TimeoutError` catches it too; on 3.10 it does not —
+  do not rely on the async alias for catching these raises.)
+- **Emits on construction, not on raise.** `__init__` publishes one
+  `EventType.TIMEOUT_RAISED` event (see [EVENTS.md](EVENTS.md)) to the global
+  EventBus via `get_event_bus()`.
+- **Zero-cost when observability is off.** The emit path is guarded by
+  `is_observability_enabled()`, which is only `True` inside the MP server
+  process. In single-process / CLI mode the constructor does nothing beyond
+  `super().__init__(message)` (one boolean check) — no event, no stack-trace
+  capture, no OTel dependency exercised.
+- **Never raises from `__init__`.** Any failure to publish is swallowed and
+  logged at debug level: observability must never break error handling.
+- **`session_id`** is forwarded onto the event so the timeout span can nest
+  under the originating request's root span. Pass it where the raise site has a
+  request/`IPCCacheServerKey.request_id` in scope (e.g. `shm.prepare_store`);
+  leave it empty otherwise.
+
+## What gets recorded
+
+The emitted `TIMEOUT_RAISED` event carries `message`, `exception_type`, and a
+captured `stacktrace` (the construction stack minus the `__init__` frame,
+following the OTel `exception.*` semantic conventions). Three subscribers
+consume it, registered by `init_observability` under the usual
+metrics/logging/tracing toggles:
+
+| Subscriber | Output | Default |
+|---|---|---|
+| `TimeoutMetricsSubscriber` | `lmcache_mp.timeouts` counter, tagged `exception_type` | on (`metrics_enabled`) |
+| `TimeoutLoggingSubscriber` | `WARNING` log with message + stack trace | on (`logging_enabled`) |
+| `TimeoutTracingSubscriber` | zero-duration `timeout` span with an `exception` event + ERROR status | on when tracing enabled |
+
+The tracing subscriber records the exception the same way OTel's
+`Span.record_exception` would (an `exception` span event with `exception.type`
+/ `exception.message` / `exception.stacktrace` plus ERROR status), driven from
+the EventBus drain thread where the original exception object is no longer
+available.
+
+## Extending
+
+To make another timeout observable, raise `LMCacheTimeoutError` instead of the
+built-in. To add a new observable error family, define a sibling subclass of
+the relevant built-in here, add a matching `EventType`, and add subscriber(s)
+that consume it — mirroring the timeout wiring.
diff --git a/docs/design/v1/mp_observability/event-bus.md b/docs/design/v1/mp_observability/event-bus.md
new file mode 100644
index 0000000..ac59460
--- /dev/null
+++ b/docs/design/v1/mp_observability/event-bus.md
@@ -0,0 +1,203 @@
+# MP Observability: EventBus Design
+
+This document describes the design rationale behind the EventBus-based
+observability system.  For configuration reference see [README.md](README.md).
+For metrics, see [METRICS.md](METRICS.md).  For event metadata contracts,
+see [EVENTS.md](EVENTS.md).
+
+---
+
+## 1. Architecture: Event Bus with Pub/Sub
+
+```
+Producers (L1Manager, StorageManager, MPCacheServer)
+    │
+    │  bus.publish(Event(...))
+    ▼
+EventBus  (single deque + drain thread)
+    │
+    │  dispatches by EventType
+    │
+    ├──► Metrics subscribers   → OTel counter.add(...)
+    ├──► Logging subscribers   → logger.debug(...)
+    └──► Tracing subscribers   → OTel span start/end (explicit timestamps)
+
+OpenTelemetry SDK  (configured once at startup)
+    │
+    ├──► OTLP push (production)     → OTel collector → Prometheus / Grafana / etc.
+    └──► Prometheus pull (dev/debug) → /metrics endpoint
+```
+
+Producers publish a single `Event` object.  Subscribers register callbacks
+for the `EventType`s they care about.  The EventBus queues events in a
+lock-free deque and dispatches them from a background drain thread.
+
+---
+
+## 2. Event Model
+
+```python
+class EventType(Enum):
+    L1_READ_RESERVED     = "l1.read.reserved"
+    L1_READ_FINISHED     = "l1.read.finished"
+    # ... (see event.py for the full list)
+
+@dataclass
+class Event:
+    event_type: EventType
+    timestamp: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    session_id: str = ""
+```
+
+### Timestamp semantics
+
+`timestamp` is set by `EventBus.publish()` at the moment it is called — **not**
+when the drain thread processes the event.  This matters because:
+
+- Subscribers that compute durations (tracing, latency metrics) need the
+  real operation time, not the queue-processing time.
+- For MP server events, `publish()` is invoked from **CUDA host callbacks**
+  (`cupy_stream.launch_host_func`).  The CUDA runtime calls the host function
+  when the GPU stream reaches that point, so `time.time()` inside `publish()`
+  captures the GPU-accurate moment.
+- For L1Manager / StorageManager events, `publish()` is called directly from
+  Python, so the timestamp reflects the actual operation time.
+
+### Metadata
+
+All event-specific data lives in `metadata: dict[str, Any]`.  Each `EventType`
+has a documented metadata schema (see [EVENTS.md](EVENTS.md)).  This design
+keeps the `Event` dataclass generic and avoids coupling between producers and
+subscribers.
+
+---
+
+## 3. Event Bus Internals
+
+```python
+class EventBus:
+    def publish(self, event: Event) -> None:
+        """Hot path — stamps timestamp, appends to deque, signals drain."""
+        event.timestamp = time.time()
+        self._queue.append(event)
+        self._wake.set()
+
+    def _drain_all(self) -> None:
+        """Background thread pops events and dispatches to subscribers."""
+        while event := self._queue.popleft():
+            for cb in self._subscribers.get(event.event_type, []):
+                cb(event)  # exceptions are caught and logged
+```
+
+Key design choices:
+
+- **Async-only dispatch.**  All events go through the queue.  Subscribers
+  never run on the producer's thread.  This keeps the hot path (L1Manager,
+  StorageManager GPU copies) fast.
+- **Tail-drop backpressure.**  When the queue exceeds `max_queue_size`, new
+  events are silently dropped with a rate-limited warning.  This prevents
+  unbounded memory growth without blocking producers.
+- **Exception isolation.**  A failing subscriber callback does not affect other
+  subscribers or the drain thread.
+- **Self-monitoring.**  The bus exposes four read-only accessors —
+  `queue_depth()`, `oldest_event_lag_seconds()`, `dropped_events_count()`,
+  `subscriber_exception_counts()` — that surface its own health.  These
+  drive the `lmcache_mp.event_bus.*` metrics registered by
+  `EventBusSelfMetricsSubscriber` (see [METRICS.md](METRICS.md)). Keeping
+  the accessors OTel-free preserves the bus's decoupling from the metrics
+  system.
+
+---
+
+## 4. Subscriber Model
+
+```python
+class EventSubscriber(ABC):
+    @abstractmethod
+    def get_subscriptions(self) -> dict[EventType, EventCallback]: ...
+
+    def shutdown(self) -> None:  # optional cleanup
+        pass
+```
+
+Subscribers are organized by concern:
+
+| Subdirectory | Concern | Examples |
+|---|---|---|
+| `subscribers/metrics/` | OTel counters / histograms | `L1MetricsSubscriber`, `SMMetricsSubscriber` |
+| `subscribers/logging/` | Debug log output | `L1LoggingSubscriber`, `MPServerLoggingSubscriber` |
+| `subscribers/tracing/` | OTel spans from START/END pairs | `MPServerTracingSubscriber` |
+
+Each concern can be toggled independently via `ObservabilityConfig`
+(`metrics_enabled`, `logging_enabled`, `tracing_enabled`).
+
+---
+
+## 5. OTel Span Strategy
+
+All MP server operations have their START and END in **different call sites**:
+
+- **`store` / `retrieve`:** START and END fire from separate CUDA host callbacks.
+- **`lookup_and_prefetch`:** START is in `lookup()`, END is in
+  `query_prefetch_status()` — two separate RPC methods.
+
+OTel's idiomatic `with tracer.start_as_current_span(...)` pattern requires
+start and end in the same lexical scope, which does not apply here.  Instead,
+the tracing subscriber uses explicit span management with caller-provided
+timestamps:
+
+```python
+class MPServerTracingSubscriber(EventSubscriber):
+    def _on_start(self, event: Event) -> None:
+        span = tracer.start_span("mp.store", start_time=ns(event.timestamp))
+        self._pending[key] = span
+
+    def _on_end(self, event: Event) -> None:
+        span = self._pending.pop(key)
+        span.end(end_time=ns(event.timestamp))
+```
+
+This preserves GPU-accurate timing while producing real OTel spans exportable
+to any OTLP-compatible backend (Jaeger, Tempo, Grafana, etc.).
+
+---
+
+## 6. OTel SDK Initialization
+
+Configured once at startup via `ObservabilityConfig`:
+
+- **`otlp_endpoint` is set** → OTLP push mode.  Metrics and traces are
+  exported to an OTel collector.
+- **`otlp_endpoint` is `None`** → Prometheus pull fallback.  An in-process
+  `/metrics` endpoint is served on `prometheus_port`.
+
+Tracing requires an OTLP endpoint (there is no local fallback for spans).
+When `tracing_enabled` is set without `otlp_endpoint`, the TracerProvider
+init is skipped and spans are silently dropped.
+
+---
+
+## 7. L1Manager Listener Coexistence
+
+`L1Manager` still uses its `L1ManagerListener` ABC for **business-logic
+consumers** (`StoreController`, `EvictionPolicy`).  These are not observability
+— they drive store scheduling and LRU eviction.
+
+For observability, L1Manager publishes events **directly** to the EventBus
+alongside its existing listener iteration:
+
+```python
+# Business logic — listener pattern stays
+for listener in self._registered_listeners:
+    listener.on_l1_keys_read_finished(successful_keys)
+
+# Observability — EventBus
+self._event_bus.publish(Event(
+    event_type=EventType.L1_READ_FINISHED,
+    metadata={"keys": successful_keys},
+))
+```
+
+`StorageManager`, by contrast, has no business-logic listeners and publishes
+exclusively to the EventBus.
diff --git a/docs/design/v1/mp_observability/trace.md b/docs/design/v1/mp_observability/trace.md
new file mode 100644
index 0000000..02404d2
--- /dev/null
+++ b/docs/design/v1/mp_observability/trace.md
@@ -0,0 +1,546 @@
+# Trace Recording & Replay (`lmcache trace`)
+
+Trace recording captures LMCache's operational stream during a real run so
+the same workload can be **replayed** later for testing, regression hunting,
+and benchmarking — without needing vLLM or, eventually, a GPU. This
+document covers both halves:
+
+- **PR1 — capture.** `lmcache server --trace-level storage --trace-output
+  FILE` and the decorator/recorder/format machinery.
+- **PR2 — replay.** `lmcache trace info|replay|record` and the
+  `StorageReplayDriver`.  All replay output (per-record stream,
+  aggregated CSV/JSON summary, terminal metrics table) lives under
+  `lmcache trace replay`; there is no separate `bench trace-replay`
+  command.
+
+For configuration reference see [README.md](README.md). For event metadata
+contracts see [EVENTS.md](EVENTS.md).
+
+---
+
+## 1. Goals and non-goals
+
+### Goals
+
+- Capture every public `StorageManager` API call to a single binary file.
+- **Off** by default; near-zero overhead when off (one boolean check per
+  decorated call).
+- Recording is opt-in via a single CLI flag on `lmcache server`.
+- The on-disk format is forwards-extensible: future trace **levels**
+  (`mq`, `gpu`) can land without breaking the file layout or replay CLI.
+- The decorator (`@enable_tracing`) is reusable on any future public API
+  layer; instrumenting MQ handlers later requires no new event types or
+  format changes.
+
+### Non-goals (deferred to follow-up PRs)
+
+- **No KV tensor data is captured.** Replay exercises bookkeeping and
+  controller logic; payloads at replay time are zeros.
+- **No MQ-, MPCacheServer-, or GPU-copy-level capture.** Those layers
+  carry GPU IPC handles and require a swappable GPU-copy abstraction
+  that is out of scope.
+- **No runtime enable/disable.** Capture is configured at server
+  startup. Runtime toggling via the HTTP admin server can be layered on
+  later by flipping the trace gate without touching the format.
+
+---
+
+## 2. Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  StorageManager.<method>      (+ context-manager publishes) │
+│      │                                                      │
+│      │  @enable_tracing()                                   │
+│      ▼                                                      │
+│  publish_call_event(qualname, raw_args)  ───── gated ─────► (no-op)
+│      │                                          │           │
+│      │  if _tracing_enabled                     │           │
+│      ▼                                                      │
+│  EventBus.publish(Event(TRACE_CALL, …))                     │
+│      │                                                      │
+│      │ (drain thread)                                       │
+│      ▼                                                      │
+│  StorageTraceRecorder._on_trace_call()                      │
+│      │                                                      │
+│      │  codecs.encode_args() + msgspec.msgpack              │
+│      ▼                                                      │
+│  trace file:  [Header][Record][Record]…                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Three pieces, each in its own module under
+`lmcache/v1/mp_observability/trace/`:
+
+| Module | Responsibility |
+|--------|----------------|
+| `decorator.py` | `@enable_tracing`, the trace gate, `publish_call_event` helper for context managers |
+| `codecs.py` | Per-type encode/decode registry shared by recorder and (PR2) replay driver |
+| `format.py` | `Header` + `Record` msgspec structs; length-prefixed framing |
+| `recorder.py` | `TraceRecorder` ABC + `StorageTraceRecorder` `EventSubscriber` |
+| `reader.py` | Streaming `TraceReader` (used by `trace info` / replay in PR2) |
+| `lifecycle.py` | `maybe_initialize_trace_recorder` server-side wiring helper |
+
+---
+
+## 3. Capture: the `@enable_tracing` decorator
+
+### Single unified event
+
+All captured calls publish the same `EventType.TRACE_CALL` event:
+
+```python
+Event(
+    event_type = EventType.TRACE_CALL,
+    timestamp  = <time.time() stamped by EventBus.publish()>,
+    metadata   = {
+        "qualname": "lmcache.v1.distributed.storage_manager.StorageManager.reserve_write",
+        "args":     {"keys": [...], "layout_desc": {...}, "mode": "new"},
+        "t_mono":   <time.monotonic() captured inside publish_call_event>,
+    },
+)
+```
+
+One event type instead of one per method keeps the EventBus enum and
+subscriber dispatch table small and lets new traced methods land
+without schema bumps. The `qualname` field discriminates ops; the
+`args` dict carries everything needed to reissue the call at replay
+time.
+
+`t_mono` is sampled inside `publish_call_event` (the publish-time
+path), not on the EventBus drain thread. Otherwise the `t_mono` and
+`t_wall` values recorded per call would drift by the drain queue
+latency, rendering relative-timing analyses off by up to a frame's
+worth of processing time.
+
+### Signature-driven argument capture
+
+The decorator binds `inspect.signature(func)` **once at decoration
+time**:
+
+```python
+@enable_tracing()
+def reserve_write(self, keys, layout_desc, mode): ...
+```
+
+On call, the wrapper:
+
+1. Checks the gate (`_tracing_enabled`). If off, jumps straight to the
+   real function — overhead is one bool load.
+2. If on, runs `sig.bind_partial(*args, **kwargs).apply_defaults()`,
+   filters to the configured `capture` / `redact` set (default:
+   everything except `self` / `cls`), and publishes the event.
+
+This keeps the per-call cost when enabled to a single signature bind +
+dict-comprehension. No per-method instrumentation code; adding a new
+traced method on either side reduces to slapping the decorator on.
+
+### Entry-only
+
+The decorator publishes on entry only; outputs and exceptions are not
+captured. Replay re-runs the method and observes the live outcome
+itself, so recorded outcomes would be redundant. Halving the event
+volume also keeps the file smaller. Return values like `PrefetchHandle`
+do not need to be correlated across records because the public
+`StorageManager` API takes no handle as an input — later calls
+reference keys, not handles.
+
+### Context managers
+
+`StorageManager.read_prefetched_results` is a `@contextmanager`
+generator. The decorator cannot wrap it (it would publish the call to
+the wrapper, not to `__enter__`). Instead the method calls
+`publish_call_event(...)` manually at enter and exit, gated on
+`is_tracing_enabled()`. The qualnames carry the
+`.read_prefetched_results.__enter__` / `.__exit__` suffixes so replay
+can re-enter the context manager faithfully.
+
+### Why the decorator publishes raw values
+
+The decorator publishes raw Python values; codec encoding happens later
+on the EventBus drain thread inside the recorder. This keeps the
+decorator import-cheap: it has no dependency on `codecs.py`, so adding
+a new codec cannot pull the decorator's dependency graph.
+
+All codec-targeted types (`ObjectKey`, `MemoryLayoutDesc`,
+`PrefetchHandle`, `torch.Size`, `torch.dtype`) live in
+`lmcache/v1/distributed/api.py`. Keeping them in a leaf module means
+`codecs.py` imports them eagerly and registers every codec at import
+time, with no cycle-break machinery.
+
+---
+
+## 4. The trace gate
+
+A single module-level boolean in `decorator.py`:
+
+```python
+_tracing_enabled: bool = False
+```
+
+Flipped on inside `TraceRecorder.__init__` (after the file is open) and
+off inside `TraceRecorder.close()`. A bool is sufficient: capture is
+single-process; cross-thread visibility is not required for
+correctness — at worst a few events are missed during the toggle
+window. The bool sits at the head of every decorated call's hot path,
+so the disabled cost is one attribute load.
+
+---
+
+## 5. Recorder
+
+`StorageTraceRecorder(TraceRecorder)` subscribes to `TRACE_CALL` on the
+EventBus. Subscriber callbacks already run on the EventBus drain
+thread, so the recorder is off the request path by construction.
+Encoding (codec + msgspec) and disk I/O happen inline in the callback;
+adding a second worker thread would be premature optimization.
+
+### Lifecycle
+
+| Phase | Action |
+|-------|--------|
+| `__init__(output_path)` | Open file (unbuffered), capture `t_mono_start` / `t_wall_start`, flip the gate on. **Header write is deferred.** |
+| `attach_storage_config(cfg)` | First call: serialize the StorageManagerConfig, hash it, write the header. Idempotent; subsequent calls are silently ignored. |
+| `_on_trace_call(event)` | If the header has not been written, write a placeholder (empty config) header, then append the encoded record. |
+| `close()` / `shutdown()` | Idempotent. Writes the placeholder header if neither attach nor any record ran. Flushes, fsyncs, closes the fd; flips the gate off. |
+
+The "deferred header" design exists because the header carries the
+serialized `StorageManagerConfig`, which is generally **longer** than
+any placeholder. Writing a placeholder up front and seeking back to
+overwrite it would land the new (longer) header bytes on top of any
+records that landed in the meantime, corrupting the file. Deferring
+the write avoids the in-place rewrite entirely and guarantees the file
+is always readable regardless of whether `attach_storage_config` is
+ever called.
+
+### Failure modes
+
+- **Codec error** (unknown arg type): the record is dropped, a
+  WARNING is logged, `dropped_count` is incremented. The recorder
+  continues. Losing a record is preferable to taking down the EventBus
+  drain thread.
+- **OSError on write**: same — drop and count.
+- **fsync failure on close**: logged with `exc_info`; the close path
+  still completes.
+
+`dropped_count` is exposed as a property for tests and (future)
+metrics integration.
+
+### Shutdown contract
+
+The recorder relies on `EventBus.stop()` to flush and close the file.
+The chain is:
+
+```
+<server shutdown>
+  → event_bus.stop()
+      → _drain_all()                       (process queued events)
+      → subscriber.shutdown() per sub      (EventBus contract)
+          → TraceRecorder.close()          (flush + fsync + close fd)
+```
+
+All three cache-server entry points already invoke `event_bus.stop()`
+in their shutdown paths:
+
+- `server.py :: run_cache_server` — in the `KeyboardInterrupt`
+  handler.
+- `blend_server_v2.py :: run_cache_server` — same.
+- `http_server.py :: lifespan` — in the FastAPI lifespan teardown
+  branch.
+
+`close()` is idempotent; calling it directly (for tests) and then
+letting `shutdown()` fire is safe. The trace gate is flipped off
+inside `close()`, so any events that race the shutdown after the
+final drain become cheap no-ops in the publisher.
+
+---
+
+## 6. On-disk format
+
+```
+[ 4-byte big-endian length ][ msgpack Header  ]
+[ 4-byte big-endian length ][ msgpack Record  ]
+[ 4-byte big-endian length ][ msgpack Record  ]
+...
+```
+
+Length-prefixed frames keep the reader simple and let truncated tails
+(SIGKILL, fs buffer loss) be detected and recovered cleanly.
+
+### `Header`
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `magic` | `bytes` (`LMCT`) | Sanity check; reader rejects non-matching files |
+| `format_version` | `int` (1) | Bumped on incompatible **framing** layout changes (length prefix, struct shape). Reader rejects unknown versions |
+| `level` | `str` (`storage`) | Trace level discriminator. Future `mq` / `gpu` levels will share this format and use this field for replay-driver dispatch |
+| `trace_schema_version` | `int` (1) | Bumped on incompatible changes to the captured API surface (e.g. a traced method's args change, a codec wire form changes). Owned by the trace subsystem, not tied to `lmcache.__version__`; reader rejects mismatches |
+| `t_mono_start` | `float` | `time.monotonic()` at recorder construction; record `t_mono` is relative to this |
+| `t_wall_start` | `float` | `time.time()` at construction, for absolute correlation with external logs |
+| `sm_config_json` | `str` | JSON dump of `StorageManagerConfig` at record time, or empty string if attach was skipped |
+| `sm_config_digest` | `str` | SHA-256 of `sm_config_json`. Replay drivers use this to detect mismatched configurations |
+
+### `Record`
+
+A single homogeneous shape across all ops; `qualname` discriminates.
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `t_mono` | `float` | Seconds since `Header.t_mono_start` |
+| `t_wall` | `float` | Wall-clock `time.time()` at the moment `EventBus.publish()` ran |
+| `qualname` | `str` | Fully-qualified call-site name |
+| `args` | `dict[str, Any]` | Codec-encoded argument dict |
+
+The single-shape design means new traced ops are purely additive on
+both write and read: no per-op msgspec class, no `Union` dispatch.
+
+---
+
+## 7. Codec registry
+
+The `args` dict needs to round-trip values that msgpack does not
+natively understand: `ObjectKey`, `MemoryLayoutDesc`, `PrefetchHandle`,
+`torch.Size`, `torch.dtype`. A small per-type registry handles this:
+
+```python
+register_codec(t, TypeCodec(tag, encode, decode))
+```
+
+Encode wraps non-native values in `{"__t__": tag, "v": payload}` so
+the decoder recognizes them. The same registry is used by the recorder
+(encode-only in PR1) and by the replay driver (decode-only in PR2),
+ensuring the read and write halves cannot drift apart.
+
+Tuples are tagged separately so they decode back as tuples instead of
+lists. `torch.Size` is a tuple subclass, so codec lookup checks the
+exact type **before** the generic `isinstance(v, tuple)` branch.
+
+Unknown types fail loudly (`TypeError`) rather than silently dropping
+fields — silent drops would let bugs masquerade as test successes at
+replay time.
+
+---
+
+## 8. CLI surface
+
+`lmcache server` gains two new flags in the existing `Observability`
+arg group:
+
+| Flag | Description |
+|------|-------------|
+| `--trace-level {storage}` | **Primary enable flag.** Currently only `storage` is supported. |
+| `--trace-output FILE` | Output path. Optional; if omitted while `--trace-level` is set, a timestamped file under `$TMPDIR` is minted (`lmcache-trace-<pid>-<UTC>.lct`) and its path is logged at INFO. |
+
+Both flags flow through `ObservabilityConfig` and are consumed by
+`maybe_initialize_trace_recorder`, called from `run_cache_server` in
+both `multiprocess/server.py` and `multiprocess/blend_server_v2.py`.
+When `--trace-level` is unset, the helper returns `None` and no
+recorder is registered — true zero overhead.
+
+`lmcache trace info|replay|record` reads the format defined here;
+see §9 for details.
+
+---
+
+## 9. Replay (`lmcache trace`)
+
+The replay half lives under `lmcache/cli/commands/trace/` — the CLI
+entry point and its supporting driver/dispatcher/stats modules are
+co-located in a single package.  It reads trace files written by the
+recorder and reissues each captured call against a fresh
+`StorageManager` that the caller configures independently.
+
+### 9.1 Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  trace file: [Header][Record]…                                  │
+│         │                                                        │
+│         ▼                                                        │
+│  TraceReader.records()                                           │
+│         │                                                        │
+│         │  codecs.decode_args(record.args)                       │
+│         ▼                                                        │
+│  CallDispatcher.dispatch(qualname, ctx, decoded_args)            │
+│         │                                                        │
+│         │  handler registered in build_default_dispatcher()      │
+│         ▼                                                        │
+│  StorageManager.<method>(**decoded_args)   ── timed, counted ──► │
+│                                                            │     │
+│                                        ReplayStatsCollector│     │
+│                                       (per-qualname p50/p90/p99) │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Four modules, all under `lmcache/cli/commands/trace/`:
+
+| Module | Responsibility |
+|--------|----------------|
+| `cli/commands/trace/__init__.py` | `lmcache trace info|replay|record` |
+| `cli/commands/trace/dispatch.py` | `CallDispatcher`, `ReplayContext`, default v1 handler table |
+| `cli/commands/trace/driver.py` | `StorageReplayDriver`, `ReplayResult` |
+| `cli/commands/trace/stats.py` | `ReplayStatsCollector` + `OpStats`; CSV/JSON export |
+
+### 9.2 Auto-resolve: no per-op glue
+
+Adding a new traced method is a two-line change:
+
+1. Decorate it with `@enable_tracing()` (PR1's decorator picks up
+   the `qualname` from `f.__module__ + "." + f.__qualname__`).
+2. Register a handler under that `qualname` in
+   `build_default_dispatcher`.
+
+For plain methods on `StorageManager`, step 2 is literally
+`_call_sm_method("<method_name>")`, which `getattr`s the live
+instance and calls it with `**decoded_args`.  Context managers use
+two handlers (`_enter_read_prefetched` + `_exit_read_prefetched`)
+because the decorator cannot wrap a generator-based `@contextmanager`.
+
+No per-op schemas live on either side.  Decoded arg names feed
+straight into `**kwargs`, matching the signature the recorder bound
+with `inspect.signature` at decoration time.
+
+### 9.3 Dispatcher & context
+
+`CallDispatcher` is a simple `qualname → Handler` map with
+`register`, `has`, `dispatch`.  `ReplayContext` carries:
+
+- The live `StorageManager` (owned by the driver).
+- `open_read_contexts: dict[tuple[ObjectKey, ...], deque[CM]]` — a
+  FIFO per key tuple so overlapping `read_prefetched_results`
+  contexts entered and exited via the trace pair up correctly.
+
+Unmatched `__exit__` records (typically from a truncated tail) log a
+warning and are ignored; the driver's final sweep calls `__exit__`
+on any still-open contexts to keep the StorageManager in a
+consistent state.
+
+### 9.4 Pacing
+
+The driver always sleeps just long enough to align each dispatch to
+the recorded `t_mono` offset from replay start.  **Never speeds a
+trace up** — if the replay host is slower than recording, the loop
+lags the recorded schedule.  This reproduces the original pressure on
+eviction/prefetch queues.
+
+There is no as-fast-as-possible mode.  `StorageManager` reads and
+writes are async and carry cross-call dependencies (e.g. a retrieve
+may depend on an earlier L2 load completing); collapsing the recorded
+inter-call gaps races those queues and turns reproducible traces
+into non-deterministic retrieve misses.
+
+### 9.5 `ReplayResult`
+
+`StorageReplayDriver.run()` returns:
+
+| Field | Meaning |
+|-------|---------|
+| `records_replayed` | Successful dispatches. |
+| `records_skipped` | Records whose `qualname` had no handler (likely from a newer trace level). |
+| `records_failed` | Records whose handler raised. |
+| `stats` | `ReplayStatsCollector` with per-qualname latency and duration. |
+| `header_level` | Copied from trace header for the caller to dispatch on. |
+| `header_digest` | `sm_config_digest` from the header. |
+| `replay_config_digest` | SHA-256 of the replay-side StorageManagerConfig (same algorithm as `safe_storage_config_dict` used by the recorder). Mismatch vs. `header_digest` indicates the replay config differs from recording. |
+
+### 9.6 CLI
+
+| Command | Purpose |
+|---------|---------|
+| `lmcache trace info FILE` | Header metadata + per-qualname record counts + total duration. |
+| `lmcache trace replay FILE <storage-manager flags> [--verbose] [--jsonl-out PATH] [--output-dir DIR] [--no-csv] [--json] [-q]` | Replay the trace, always honoring the recorded inter-call timings (see §9.4). Logs progress (`[N/total] qualname ...`) per record. Emits a terminal metrics table (unless `-q`) with count / mean / p50 / p99 per qualname, and writes `trace_replay_ops.csv` / `trace_replay_summary.json` in `--output-dir` (CSV by default; JSON with `--json`). `--verbose` and `--jsonl-out` stream per-record output for post-hoc analysis. |
+
+Trace *capture* is intentionally not a `trace` subcommand: recording
+is bound to a live process, so it is enabled via
+`lmcache server --trace-level storage [--trace-output ...]`.  A
+separate `trace record` stub would only duplicate that flag while
+suggesting a runtime-capture CLI that does not yet exist.
+
+The `replay` command accepts the full `lmcache/v1/distributed/config.py`
+`add_storage_manager_args` flag set (`--l1-size-gb`,
+`--eviction-policy`, `--l2-adapter`, …), so replay can target any
+L1/L2 configuration the production StorageManager supports.
+
+### 9.7 Data correctness
+
+The replay-side `StorageManager` does not receive real KV bytes —
+the trace does not carry them.  Memory objects returned by
+`reserve_write` are zero-filled and `finish_write` is called without
+writing to them.  Replay therefore exercises:
+
+- L1 bookkeeping (reserve/finish, read-lock counts)
+- Eviction controllers
+- Prefetch controller
+- L2 adapter lifecycles (when an L2 adapter is configured on the
+  replay side)
+
+Replay does **not** validate KV payloads or GPU copy correctness —
+those layers are intentionally out of scope.
+
+### 9.8 Forward compatibility
+
+`Header.level` is checked by the replay driver via `header_level`
+on the result; unknown levels simply pass through with every record
+"skipped" (no handler registered).  A future `lmcache trace replay
+--level mq …` would register a different dispatcher; the file
+format itself does not change.
+
+---
+
+## 10. Extensibility seams
+
+Future MQ / GPU trace levels reuse this design without breaking the
+file format:
+
+1. **`level` header field** — the same `Header` carries the
+   discriminator; replay dispatches on it.
+2. **Reusable decorator** — apply `@enable_tracing` to MQ handlers or
+   `MPCacheServer` methods. No new event type, no format change. The
+   `qualname` string differentiates them.
+3. **Polymorphic recorder** — `TraceRecorder` ABC accepts new
+   subclasses with different `get_subscriptions()` mappings (or, more
+   likely, the same `TRACE_CALL` mapping with a different `level`
+   passed to the base).
+4. **Codec registry** — new arg types slot in by calling
+   `register_codec`. No format bump. Keep newly-traced argument types
+   in `lmcache/v1/distributed/api.py` (or another leaf module) so
+   `codecs.py` can import them without pulling in modules that import
+   the trace decorator.
+
+---
+
+## 11. Test coverage
+
+### Capture (PR1) — `tests/v1/mp_observability/trace/`
+
+- `test_decorator.py` — gate on/off; zero-overhead semantics when off;
+  arg capture; `capture` / `redact` filters; entry-only on exception.
+- `test_codecs.py` — round-trip every registered type, including
+  primitives, tuples, `torch.Size`, `torch.dtype`,
+  `MemoryLayoutDesc`, `ObjectKey`, `PrefetchHandle`. Unknown-type and
+  unknown-tag error paths.
+- `test_recorder.py` — header round-trip with and without
+  `attach_storage_config`; gate flip on init / off on close;
+  publish-via-EventBus end-to-end (codec encode → file → reader → codec
+  decode); truncated-tail tolerance; bad-magic rejection;
+  `dropped_count` increments on unencodable args.
+
+### Replay (PR2) — `tests/cli/commands/trace/`
+
+- `test_stats.py` — percentile math; CSV/JSON export; thread safety of
+  `record()`; failed-call bucketing.
+- `test_dispatch.py` — dispatcher registration semantics; default v1
+  qualname coverage; FIFO context-manager pairing; exit-without-enter
+  warns without crashing.
+- `test_driver.py` — record-then-replay round trips against a real
+  `StorageManager` (CPU memory, no GPU): `reserve_write` +
+  `finish_write`, full prefetch cycle including
+  `read_prefetched_results`, `on_record` callback firing, unknown-
+  qualname skipping, handler-failure counting, and pacing
+  (`REALTIME` waits, `ASAP` does not).
+- `tests/cli/commands/test_trace_command.py` — subparser wiring
+  (positional + required flags, output-flag parsing), `info` end-to-
+  end against a tiny fixture, `record` stub exits with code 2,
+  `replay` end-to-end: CSV/JSON export and `-q` terminal-summary
+  suppression against a recorded `reserve_write` + `finish_write`
+  fixture.
diff --git a/docs/design/v1/multiprocess/device_ipc_wrapper_design.md b/docs/design/v1/multiprocess/device_ipc_wrapper_design.md
new file mode 100644
index 0000000..0a25127
--- /dev/null
+++ b/docs/design/v1/multiprocess/device_ipc_wrapper_design.md
@@ -0,0 +1,79 @@
+# `DeviceIPCWrapper` — a device-agnostic base for KV-cache IPC
+
+## Motivation
+
+The multiprocess (MP) transport shares a paged KV-cache buffer between the producer process (vLLM / SGLang / TRT-LLM) and the LMCache server by sending an IPC handle for the underlying storage once, at `REGISTER_KV_CACHE` time. Every later `STORE`/`RETRIEVE` carries only paged block IDs, never tensors.
+
+Historically all of these handle wrappers subclassed `CudaIPCWrapper`:
+
+```text
+CudaIPCWrapper
+├── RawCudaIPCWrapper      (TRT-LLM raw cudaMalloc pool)
+└── CpuShmTensorWrapper    (CPU POSIX-SHM, in platform/cpu/shm.py)
+```
+
+In fact a CPU shared-memory wrapper and a TRT-LLM raw-pointer wrapper are not CUDA caching-allocator tensors, yet they inherited `_share_cuda_`- based machinery they never used. It also made non-CUDA backends impossible to add cleanly.
+
+## The new hierarchy
+
+A device-agnostic base, `DeviceIPCWrapper`, now owns everything that is not transport-specific. Each concrete wrapper is a direct sibling:
+
+```text
+DeviceIPCWrapper                        base: contract + (de)serialize
+├── CudaIPCWrapper                      cuda  — torch caching allocator
+├── RawCudaIPCWrapper                   cuda — raw cudaMalloc, TRT-LLM
+├── CpuShmTensorWrapper                 cpu   — POSIX shared memory
+└── MusaIPCWrapper                      musa  — TorchMUSA memory IPC
+```
+
+All of them live behind a single msgspec ext code 1 and a single `KVCache = list[DeviceIPCWrapper]` wire type, so new device backends can be added as further siblings without touching the wire format.
+
+## What the base class owns
+
+`DeviceIPCWrapper` (in `platform/base_ipc_wrapper.py`) provides the parts that every
+transport shares:
+
+- **Interface fields** — `dtype`, `shape`, `stride`, `storage_offset`, `device_uuid`. Subclasses populate these in `__init__`; the base uses them for equality and the receiving side uses them to rebuild the logical view.
+- **Device discovery** — `_get_device_uuid`, `_discover_devices`,`_get_device_index_from_uuid`. These are `@classmethod`s (not static) and route through the `torch_dev` abstraction, so they work across device backends, and a subclass can override `_get_device_uuid` if its backend needs a different identity source.
+- **Equality** — `__eq__` uses a `type(self) is type(other)` guard, so two different wrapper subclasses never compare equal even if their fields coincide.
+- **Serialization** — `Serialize`/`Deserialize` are `pickle.dumps` / `pickle.loads`. Pickle preserves the concrete subclass identity across the wire, which is what lets a single ext code carry every wrapper type (see below).
+- **`to_tensor()`** — abstract; raises `NotImplementedError`. Every subclass overrides it with its transport-specific reconstruction.
+
+## How to dispatch
+
+- `_CUSTOMERIZED_SERIALIZERS` is keyed on `DeviceIPCWrapper` with ext code 1, dispatched by `isinstance` in the encoder hook. Every subclass instance therefore encodes through the same path.
+- `Serialize` is `pickle.dumps(obj)` -> the concrete subclass survives on the wire. `Deserialize` reconstructs it and `to_tensor()` dispatches to the correct override.
+- `KVCache = list[DeviceIPCWrapper]` is the registered msgspec type, so a single `list[...]` payload can mix any of the wrappers and the server needs zero per-type branching.
+
+## The concrete wrappers
+
+| Wrapper | Device type | Transport | Reconstruction |
+|---|---|---|---|
+| `CudaIPCWrapper` | `cuda` | `UntypedStorage._share_cuda_()` | `_new_shared_cuda` + `set_()` |
+| `RawCudaIPCWrapper` | `cuda` | `cudaIpcGetMemHandle` (raw ptr) | `cudaIpcOpenMemHandle` → CuPy → DLPack |
+| `CpuShmTensorWrapper` | `cpu` | POSIX `shm_open` | `mmap` same segment |
+| `MusaIPCWrapper` | `musa` | TorchMUSA memory IPC handle | `ipc_open_mem_handle` + DLPack / tensor view |
+
+## Platform registration
+
+The factory lookup (`platform/_registry.py`) keys on `tensor.device.type`, so
+the integration adapter never has an if/elif chain.  Concrete wrappers are
+discovered automatically at runtime — no static `register_kv_wrapper` calls
+needed:
+
+- Each concrete subclass sets a ``device_type`` ClassVar (e.g. ``"cuda"``)
+  and exposes a ``wrap`` factory classmethod.
+- :func:`~lmcache.v1.platform._registry._discover_wrappers_once` scans
+  ``lmcache.v1.platform`` two levels deep for ``DeviceIPCWrapper`` subclasses
+  on first use, indexes them by ``device_type``, and skips any subclass where
+  ``_is_default_wrapper`` is ``False`` (so ``RawCudaIPCWrapper`` coexists with
+  ``CudaIPCWrapper`` without colliding).
+- Adding a new accelerator backend only requires shipping a sub-package under
+  ``platform/<device>/`` with a ``DeviceIPCWrapper`` subclass — zero changes
+  to the dispatcher or the registry.
+
+## Backward compatibility
+
+- Wire format is unchanged. Still ext code 1, still `pickle`-over-`Ext`. Previously serialized payloads round-trip.
+- `CudaIPCWrapper` / `RawCudaIPCWrapper` keep their names, fields, and behavior; only their base class changed. Existing callers and the TRT-LLM adapter are unaffected.
+- The single `isinstance`-based equality check now uses `type(self) is type(other)`, which is stricter and correct.
diff --git a/docs/design/v1/multiprocess/engine_driven_transfer_design.md b/docs/design/v1/multiprocess/engine_driven_transfer_design.md
new file mode 100644
index 0000000..d12fe91
--- /dev/null
+++ b/docs/design/v1/multiprocess/engine_driven_transfer_design.md
@@ -0,0 +1,290 @@
+# Engine-Driven Transfer Design (Multiprocess Mode)
+
+## 1. Motivation
+
+LMCache multiprocess mode originally depended on CUDA IPC: workers send IPC
+handles, and the server reads/writes worker GPU memory directly. That path
+(now exposed as the **lmcache-driven** transfer mode) works well on CUDA, but
+the required primitives are CUDA-specific (IPC memory handles, interprocess
+CUDA events, CUDA stream semantics).
+
+For **CPU, XPU, HPU, and other non-CUDA devices**, those primitives do not
+exist. The **engine-driven** transfer mode introduces a device-agnostic path
+where the engine side (worker adapter) gathers/scatters KV through CPU chunks
+instead of CUDA IPC handles, then commits the bytes to the server.
+
+Goal: keep the existing lmcache-driven (CUDA IPC) path unchanged while adding
+a second engine-driven path that works across non-CUDA backends.
+
+## 2. Design
+
+### 2.1 Architecture Overview
+
+```text
+Worker adapter (vLLM MP adapter)
+  └─ TransferContext (transfer_context/worker_transfer.py)
+      ├─ LMCacheDrivenTransferContext  (IPC path via stream/event)
+      └─ EngineDrivenTransferContext    (data path via data copying in adapter)
+          ├─ AsyncEngineDrivenTransferContext (async_engine_driven.py)
+          │    (store-only async: all three phases run in background thread pool)
+          └─ EngineDrivenContext (transfer_context/base.py)
+             ├─ EngineDrivenContextPickle (transfer_context/pickle.py)
+             └─ EngineDrivenContextShm    (transfer_context/shm.py)
+
+MPCacheServer (server)
+├─ MPCacheServerContext (engine_context.py)
+│    ├─ StorageManager
+│    ├─ TokenHasher
+│    ├─ SessionManager
+│    ├─ EventBus
+│    ├─ LayoutDescRegistry
+│    └─ shm_pool_info (pre-computed once)
+└─ EngineDrivenTransferModule (modules/engine_driven_transfer.py)
+     └─ TransferStrategy (modules/server_transfer.py)
+          ├─ PickleTransferStrategy
+          └─ ShmTransferStrategy
+```
+
+State machine overview (worker-side):
+
+```text
+                       create_transfer_context()
+                                 |
+                 +---------------+---------------+
+                 |                               |
+                 v                               v
+      LMCacheDrivenTransferContext    EngineDrivenTransferContext
+          (device == CUDA)            (device != CUDA, sync fallback)
+                 |                       AsyncEngineDrivenTransferContext
+                 |                       (device != CUDA, async primitives available)
+                 |                               |
+                 v                               v
+              register()                      register()
+                 |                               |
+                 +---------------+---------------+
+                                 |
+                                 v
+                                READY
+                                 |
+                 +---------------+-------------------------------+
+                 |                                               |
+                 v                                               v
+    submit_store (lmcache-driven path)         submit_store (engine-driven path)
+    -> STORE request (async)          sync:    -> prepare_store -> gather -> commit_store
+                                      async:   -> background thread:
+                                                    prepare_store -> gather (copy stream)
+                                                    -> commit_store
+                                                  returns unresolved future
+                 |                                               |
+                 +---------------+-------------------------------+
+                                 |
+                                 v
+                                READY
+                                 |
+                 +---------------+-------------------------------+
+                 |                                               |
+                 v                                               v
+  submit_retrieve (lmcache-driven path)      submit_retrieve (engine-driven path)
+  -> RETRIEVE request (async)                 -> prepare_retrieve -> scatter -> commit_retrieve
+                 |                                               |
+                 +---------------+-------------------------------+
+                                 |
+                                 v
+                                READY
+                                 |
+                                 v
+                               close()
+```
+
+Overall data flow:
+- **lmcache-driven path** (CUDA IPC): worker sends a handle, server pulls/pushes
+  data directly via device memory.
+- **engine-driven path** (CPU/SHM/pickle): worker gathers/scatters paged KV and
+  exchanges CPU-side data via a transport-specific `EngineDrivenContext`
+  implementation.
+
+### 2.2 Worker Side: TransferContext
+
+`TransferContext` is the worker-side transport abstraction with four methods:
+`register`, `submit_store`, `submit_retrieve`, and `close`.
+The contract is intentionally minimal so worker adapters only depend on these
+four lifecycle and transfer operations.
+
+- **LMCacheDrivenTransferContext** keeps the original CUDA IPC behavior:
+  worker sends a handle and server performs direct GPU-side transfer.
+- **EngineDrivenTransferContext** is the engine-driven (non-CUDA) path:
+  worker transfers actual data chunks through `EngineDrivenContext`.
+- **AsyncEngineDrivenTransferContext** extends `EngineDrivenTransferContext` to make
+  the store path fully asynchronous. `submit_retrieve` is unchanged (synchronous);
+  only `submit_store` becomes async.
+
+`EngineDrivenTransferContext` flows:
+- **submit_store**: `prepare_store` → `gather_paged_kv_to_cpu` → `commit_store`
+- **submit_retrieve**: `prepare_retrieve` → `scatter_cpu_to_paged_kv` → `commit_retrieve`
+
+`AsyncEngineDrivenTransferContext` async store flow:
+- **submit_store**: performs only O(1) work on the forward thread (registration check
+and block-id flattening), then submits all three phases to a background
+`ThreadPoolExecutor` (`commit_executor`) and returns an unresolved
+`MessagingFuture`
+- **submit_retrieve**: `prepare_retrieve` → `scatter_cpu_to_paged_kv` → `commit_retrieve`
+
+During `register`, worker receives `RegisterEngineDrivenContextResponse(shm_name, pool_size)`
+from server and then calls `create_engine_driven_context(...)` to construct
+`EngineDrivenContextPickle` or `EngineDrivenContextShm`.
+
+Why `prepare → data operation → commit`:
+- `prepare_*`: set up transport state (for SHM this allocates/returns shared buffers;
+  for pickle it is a protocol RPC that does not allocate transfer buffers).
+- gather/scatter: worker-local data movement between paged KV and contiguous
+  CPU chunks, performed between protocol phases.
+- `commit_*`: finalize and notify server to consume or release transfer state.
+
+`create_transfer_context()` selects the implementation once based on device type
+and async capability:
+- CUDA device → `LMCacheDrivenTransferContext`
+- Non-CUDA device → `_build_engine_driven_context()`, which probes async primitives:
+  - async primitives available (stream, event with record/synchronize/wait, pin_memory) →
+    `AsyncEngineDrivenTransferContext`
+  - otherwise → `EngineDrivenTransferContext` (synchronous fallback)
+
+It also validates that all KV cache tensors share one device type and rejects
+mixed-device configurations by raising an error.
+
+| Context | What is transferred | Who performs copy work | Completion style |
+|---|---|---|---|
+| LMCacheDrivenTransferContext | Device handle/reference | Server pulls/pushes via IPC | Async MQ future |
+| EngineDrivenTransferContext | Actual CPU chunk data | Worker gather/scatter + transport commit | Synchronous worker-side flow |
+| AsyncEngineDrivenTransferContext | Actual CPU chunk data | Worker gather/scatter (copy stream) + background commit | Async future (resolved in background thread) |
+
+### 2.3 Server Side: LMCache-Driven Module vs Engine-Driven Module
+
+- **LMCache-driven module (existing path):** server uses `LMCacheDrivenTransferModule`
+  with CUDA IPC handles to access worker device memory directly.
+- **Engine-driven module:** server uses `EngineDrivenTransferModule`, which
+  stores per-instance `EngineDrivenContextEntry` metadata and delegates transfer
+  logic to a `TransferStrategy`.
+
+Server transfer strategy implementations:
+- **PickleTransferStrategy**: pure pickle prepare/commit behavior.
+- **ShmTransferStrategy**: SHM slot-based prepare/commit behavior, with pickle
+  fallback when inline bytes are provided.
+
+This mirrors the worker split (`EngineDrivenContextPickle` / `EngineDrivenContextShm`):
+both sides keep common request flow while isolating transport-specific logic.
+
+`MPCacheServerContext` is the shared container injected into modules at init.
+It also computes `shm_pool_info` once from `StorageManagerConfig`:
+- disable SHM when `shm_name` is empty or `use_lazy=True`
+- normalize name (`lstrip("/")` and enforce `lmcache_l1_pool_` prefix)
+- keep final `{shm_name, pool_size}` for all later registrations
+
+### 2.4 Transport Comparison
+
+**Store (worker → server storage):**
+
+| Transport | Copies | Data flow |
+|---|---|---|
+| LMCache-driven (CUDA IPC) | 2 | GPU KV → GPU staging buffer → CPU memory object |
+| Pickle | 4 | GPU KV → CPU chunk → serialize → deserialize → CPU memory object |
+| SHM | 1 | GPU KV → CPU memory object (SHM mapped) |
+
+**Retrieve (server storage → worker):**
+
+| Transport | Copies | Data flow |
+|---|---|---|
+| LMCache-driven (CUDA IPC) | 2 | CPU memory object → GPU staging buffer → GPU KV |
+| Pickle | 4 | CPU memory object → serialize → deserialize → CPU chunk → GPU KV |
+| SHM | 1 | CPU memory object (SHM mapped) → GPU KV |
+
+| Transport | Pros | Cons | Best fit |
+|---|---|---|---|
+| LMCache-driven (CUDA IPC) | Mature path, good async overlap | CUDA-only | NVIDIA CUDA deployments |
+| Pickle | Works everywhere, no SHM setup | Extra serialization + copy overhead | Universal fallback |
+| SHM | Lowest copy count, no serialization | Requires enough `/dev/shm` and synchronization | High-throughput engine-driven setups |
+
+### 2.5 Current File Layout (Key Components)
+
+- `lmcache/v1/multiprocess/modules/engine_driven_transfer.py`: `EngineDrivenTransferModule`
+- `lmcache/v1/multiprocess/modules/server_transfer.py`: `TransferStrategy`, `PickleTransferStrategy`, `ShmTransferStrategy`
+- `lmcache/v1/multiprocess/transfer_context/worker_transfer.py`: `EngineDrivenTransferContext`, `LMCacheDrivenTransferContext`, `create_transfer_context`, `MPTransferMode`
+- `lmcache/v1/multiprocess/transfer_context/async_engine_driven.py`: `AsyncEngineDrivenTransferContext`
+- `lmcache/v1/multiprocess/transfer_context/base.py`: `EngineDrivenContext`, `gather_paged_kv_to_cpu`, `scatter_cpu_to_paged_kv`, `compute_kv_layout`
+- `lmcache/v1/multiprocess/transfer_context/pickle.py`: `EngineDrivenContextPickle`
+- `lmcache/v1/multiprocess/transfer_context/shm.py`: `EngineDrivenContextShm`
+
+## 3. Protocol & Data Flow
+
+### 3.1 MQ Request Types Used by Engine-Driven Path
+
+The engine-driven path uses five request types:
+
+1. `REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT`  
+   Worker registers engine-driven KV layout metadata. Server then:
+   - stores `EngineDrivenContextEntry` (metadata + model/world info)
+   - registers `MemoryLayoutDesc` in `LayoutDescRegistry`
+   - creates `TransferStrategy` from engine-level `shm_pool_info`
+   - returns `shm_name/pool_size` so worker creates matching `EngineDrivenContext`
+
+2. `PREPARE_STORE`  
+   Worker asks server/transport to prepare store-side transfer state.
+
+3. `COMMIT_STORE`  
+   Worker commits store data so server can persist it into storage.
+
+4. `PREPARE_RETRIEVE`  
+   Worker asks server to prepare retrieval payload/state for a key.
+
+5. `COMMIT_RETRIEVE`  
+   Worker acknowledges retrieval completion so transport state can be finalized.
+
+### 3.2 Data Flow: Pickle Path
+
+Store:
+1. Worker `prepare_store` RPC.
+2. Worker gathers paged KV into CPU chunks.
+3. Worker `commit_store` sends serialized bytes.
+4. Server deserializes and writes to storage.
+
+Retrieve:
+1. Worker `prepare_retrieve` RPC.
+2. Server reads from storage and returns serialized bytes.
+3. Worker deserializes to CPU chunks.
+4. Worker scatters chunks back to paged KV.
+5. Worker `commit_retrieve` finalizes protocol state.
+
+```text
+Store (pickle)
+Worker: prepare_store --> Server
+Worker: gather paged KV -> CPU chunks
+Worker: commit_store(serialized bytes) --> Server
+Server: deserialize -> storage write
+
+Retrieve (pickle)
+Worker: prepare_retrieve --> Server
+Server: read storage -> serialize bytes
+Server: serialized bytes --> Worker
+Worker: deserialize -> scatter to paged KV
+Worker: commit_retrieve --> Server
+```
+
+### 3.3 Data Flow: SHM Path
+
+Store:
+1. Worker `prepare_store` gets `slots` and `chunk_indices`.
+2. Server includes only chunks that still need writes (already-cached chunks are skipped).
+3. Worker gathers only `chunk_indices` into SHM-backed buffers.
+4. Worker `commit_store` notifies server to finalize reserved write locks.
+
+If all chunks are already cached, server returns empty `slots/chunk_indices` and
+worker short-circuits store as success (no gather, no commit payload).
+
+Retrieve:
+1. Worker `prepare_retrieve` asks server to populate SHM.
+2. Server reads from storage and returns SHM slot descriptors.
+3. Worker scatters from SHM-backed buffers into paged KV.
+4. Worker `commit_retrieve` releases/read-completes SHM state.
+
+Notes:
+- SHM pool metadata is computed once in `MPCacheServerContext` init, not per registration.
+- `chunk_indices` optimization reduces unnecessary gather/copy work on partial cache hits.
diff --git a/docs/design/v1/multiprocess/http_api_extension.md b/docs/design/v1/multiprocess/http_api_extension.md
new file mode 100644
index 0000000..519606e
--- /dev/null
+++ b/docs/design/v1/multiprocess/http_api_extension.md
@@ -0,0 +1,166 @@
+# HTTP API Extension Design
+
+## Overview
+
+The **HTTP API Extension** framework allows developers to add new HTTP
+endpoints to the LMCache multiprocess HTTP server **without modifying
+any existing source code**. A new endpoint is simply a Python module
+placed in the `http_apis/` directory that exposes a FastAPI `APIRouter`.
+
+This follows the same **zero-modification extension** principle used by
+the L2 Adapter plugin system and the Internal API Server.
+
+---
+
+## Key Components
+
+### `HTTPAPIRegistry`
+
+Located at `lmcache/v1/multiprocess/http_api_registry.py`.
+
+Responsible for auto-discovering and registering all API modules:
+
+1. Scans the `http_apis/` directory using `pkgutil.iter_modules`.
+2. Imports every module whose name ends with `_api`.
+3. Checks for a module-level `router` attribute of type `APIRouter`.
+4. Includes the router into the FastAPI application.
+
+### `http_apis/` Directory
+
+Located at `lmcache/v1/multiprocess/http_apis/`.
+
+Each file in this directory that matches the `*_api.py` naming
+convention is automatically discovered and registered. Existing
+modules:
+
+| Module | Endpoint | Method | Description |
+|---|---|---|---|
+| `info_api.py` | `/` | GET | Basic liveness check |
+| `info_api.py` | `/healthcheck` | GET | K8s probe endpoint |
+| `info_api.py` | `/status` | GET | Internal status report |
+| `config_api.py` | `/config` | GET | Server config dump |
+| `cache_api.py` | `/cache/clear` | POST | Force-clear L1 cache |
+
+### `http_server.py`
+
+The main server module creates the `FastAPI` app and delegates all
+route registration to `HTTPAPIRegistry`:
+
+```python
+app = FastAPI(
+    title="LMCache HTTP API",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+registry = HTTPAPIRegistry(app)
+registry.register_all_apis()
+```
+
+---
+
+## Auto-Discovery Flow
+
+```
+http_server.py
+  │
+  ▼
+HTTPAPIRegistry(app)
+  │
+  ▼
+register_all_apis()
+  │
+  ├─ pkgutil.iter_modules("http_apis/")
+  │    ├─ info_api        → has router? ✓ → include
+  │    ├─ config_api      → has router? ✓ → include
+  │    ├─ cache_api       → has router? ✓ → include
+  │    ├─ quota_api       → has router? ✓ → include
+  │    └─ my_new_api      → has router? ✓ → include
+  │
+  └─ app.include_router(collected_router)
+```
+
+No changes to `http_server.py` or `http_api_registry.py` are needed
+when adding new endpoint modules.
+
+---
+
+## Adding a New Endpoint
+
+### Step 1: Create the Module
+
+Create a new file in `lmcache/v1/multiprocess/http_apis/` with the
+`*_api.py` naming convention:
+
+```python
+# lmcache/v1/multiprocess/http_apis/metrics_api.py
+# SPDX-License-Identifier: Apache-2.0
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+router = APIRouter()
+
+
+@router.get("/metrics")
+async def metrics(request: Request):
+    """Return cache hit/miss metrics."""
+    engine = getattr(request.app.state, "engine", None)
+    if engine is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "engine not initialized"},
+        )
+    return {"hits": 42, "misses": 7}
+```
+
+### Step 2: Done
+
+That's it. The `HTTPAPIRegistry` will automatically discover and
+register the new endpoint on the next server startup. No other files
+need to be modified.
+
+---
+
+## API Module Contract
+
+An API module **must**:
+
+1. Be placed in `lmcache/v1/multiprocess/http_apis/`.
+2. Have a filename ending with `_api.py`.
+3. Expose a module-level variable named `router` of type
+   `fastapi.APIRouter`.
+
+An API module **should**:
+
+1. Guard against uninitialized engine state by checking
+   `request.app.state.engine` and returning 503 if `None`.
+2. Use `lmcache.logging.init_logger(__name__)` for logging.
+3. Follow the project's import ordering convention
+   (Standard → Third Party → First Party).
+
+An API module **must not**:
+
+1. Directly import or modify the `app` object from `http_server.py`.
+2. Perform blocking I/O in endpoint handlers (use `async` properly).
+
+---
+
+## Accessing Shared State
+
+The FastAPI `app.state` object is the shared context between the
+server lifecycle and all endpoint handlers. Available attributes
+(set during the `lifespan` startup phase):
+
+| Attribute | Type | Description |
+|---|---|---|
+| `app.state.engine` | Cache engine instance | Main cache engine for KV operations |
+| `app.state.zmq_server` | ZMQ server instance | Underlying multiprocess ZMQ server |
+
+Access these via the `Request` object in your handler:
+
+```python
+@router.get("/my-endpoint")
+async def my_endpoint(request: Request):
+    engine = request.app.state.engine
+    # ... use engine ...
+```
diff --git a/docs/design/v1/multiprocess/mp_runtime_plugin.md b/docs/design/v1/multiprocess/mp_runtime_plugin.md
new file mode 100644
index 0000000..388d43e
--- /dev/null
+++ b/docs/design/v1/multiprocess/mp_runtime_plugin.md
@@ -0,0 +1,422 @@
+# MP Runtime Plugin Design
+
+## Overview
+
+The **MP Runtime Plugin** framework allows users to run custom
+scripts (Python or Bash) alongside the LMCache multiprocess (MP /
+ZMQ) server. Plugins receive the full server configuration via an
+environment variable and run as child processes whose stdout is
+captured into the LMCache logger.
+
+Unlike the non-MP (vLLM integration) mode where plugins receive a
+single `LMCacheEngineConfig`, the MP mode has multiple independent
+config dataclasses (`MPServerConfig`, `StorageManagerConfig`,
+`ObservabilityConfig`, etc.). The `MPRuntimePluginLauncher`
+aggregates them all into a single JSON blob before delegating to
+the base `RuntimePluginLauncher`.
+
+---
+
+## Key Components
+
+### `MPRuntimePluginLauncher`
+
+The MP-specific entry point. Accepts arbitrary dataclass configs
+via `**kwargs`, serializes them into a single JSON dict, and
+delegates all process management to `RuntimePluginLauncher`.
+
+| Method | Description |
+|---|---|
+| `__init__(runtime_plugin_config, **configs)` | Aggregate configs → JSON, create inner launcher |
+| `launch_plugins()` | Delegate to `RuntimePluginLauncher.launch_plugins()` |
+| `stop_plugins()` | Delegate to `RuntimePluginLauncher.stop_plugins()` |
+
+Key design decisions:
+
+- **`role=None`**: MP mode has no role concept (no SCHEDULER /
+  WORKER split). Passing `None` disables the filename prefix-based
+  role filtering in the base launcher.
+- **`worker_count=1, worker_id=0`**: The MP server runs a single
+  process instance; there is no TP-style worker sharding.
+
+### `RuntimePluginConfig`
+
+A dataclass that holds plugin configuration:
+
+| Field | Type | Description |
+|---|---|---|
+| `locations` | `list[str]` | Plugin file / directory paths |
+| `extra_config` | `dict` | Extra key-value config forwarded to plugins via JSON blob |
+
+Accepted via `--runtime-plugin-config` CLI argument as a JSON string.
+
+### `_MPPluginConfig`
+
+A thin `@dataclass` wrapper that satisfies the duck-type contract
+expected by `RuntimePluginLauncher`:
+
+| Field / Method | Type | Description |
+|---|---|---|
+| `runtime_plugin_locations` | `list[str]` | Plugin file / directory paths |
+| `extra_config` | `dict` | Extra config from `RuntimePluginConfig.extra_config` |
+| `configs_dict` | `dict` | Aggregated config sections |
+| `to_json()` | `str` | Serialize `configs_dict` + `extra_config` to JSON string |
+
+### `safe_asdict` / `make_json_safe`
+
+Public helpers in `lmcache.v1.utils.json_utils` that convert
+dataclass instances to dicts while handling non-serializable
+fields (e.g. `pathlib.Path`) by falling back to `str()`.
+`safe_asdict` operates on dataclass instances; `make_json_safe`
+recursively sanitizes arbitrary values (dicts, lists, tuples,
+primitives) and is also reused by the `/config` HTTP endpoint.
+
+### `RuntimePluginLauncher` (base)
+
+The base launcher (in `lmcache.v1.plugin`) handles:
+
+- Discovering plugin files (`.py` / `.sh`) in configured locations
+- Role-based filtering (skipped when `role=None`)
+- Worker-ID-based filtering
+- Interpreter detection (shebang → fallback)
+- Subprocess management (`Popen` with piped stdout)
+- Real-time log capture via background threads
+- Graceful shutdown via `atexit`
+
+---
+
+## Architecture
+
+```mermaid
+classDiagram
+    class MPRuntimePluginLauncher {
+        -_inner: RuntimePluginLauncher
+        +launch_plugins()
+        +stop_plugins()
+    }
+    class RuntimePluginLauncher {
+        +config
+        +role: str | None
+        +worker_count: int
+        +worker_id: int
+        +launch_plugins()
+        +stop_plugins()
+        -_launch_plugin(file)
+        -_should_skip_plugin(file, parts)
+        -_capture_plugin_output(proc, name)
+    }
+    class RuntimePluginConfig {
+        +locations: list~str~
+        +extra_config: dict
+    }
+    class _MPPluginConfig {
+        +runtime_plugin_locations: list~str~
+        +extra_config: dict
+        +configs_dict: dict
+        +to_json() str
+    }
+    MPRuntimePluginLauncher --> RuntimePluginLauncher : delegates
+    MPRuntimePluginLauncher ..> _MPPluginConfig : creates
+    MPRuntimePluginLauncher ..> RuntimePluginConfig : reads
+    RuntimePluginLauncher --> _MPPluginConfig : uses as config
+```
+
+---
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant S as MP Server
+    participant MPL as MPRuntimePluginLauncher
+    participant RPL as RuntimePluginLauncher
+    participant P as Plugin Process
+
+    S->>MPL: init(runtime_plugin_config, mp_config, storage_config, ...)
+    MPL->>MPL: safe_asdict() each config
+    MPL->>MPL: Build _MPPluginConfig wrapper
+    MPL->>RPL: init(config=wrapper, role=None)
+
+    S->>MPL: launch_plugins()
+    MPL->>RPL: launch_plugins()
+    RPL->>RPL: Discover .py / .sh files
+    RPL->>RPL: Skip role/worker filtering (role=None)
+    RPL->>P: subprocess.Popen(env={CONFIG=json})
+    Note over P: PYTHONUNBUFFERED=1
+    P->>P: Parse LMCACHE_RUNTIME_PLUGIN_CONFIG
+    P-->>RPL: stdout lines
+    RPL-->>S: logger.info("[plugin_name] ...")
+
+    S->>MPL: stop_plugins()
+    MPL->>RPL: stop_plugins()
+    RPL->>P: proc.terminate()
+```
+
+---
+
+## Environment Variables
+
+The base launcher sets the following environment variables for
+each plugin subprocess:
+
+| Variable | Value in MP mode | Description |
+|---|---|---|
+| `LMCACHE_RUNTIME_PLUGIN_CONFIG` | Aggregated JSON | Full server config |
+| `LMCACHE_RUNTIME_PLUGIN_ROLE` | `""` (empty) | No role in MP mode |
+| `LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT` | `"1"` | Single server process |
+| `LMCACHE_RUNTIME_PLUGIN_WORKER_ID` | `"0"` | Always worker 0 |
+| `PYTHONUNBUFFERED` | `"1"` | Force real-time stdout |
+
+Legacy aliases (`LMCACHE_PLUGIN_*`) are also set for backwards
+compatibility.
+
+---
+
+## Input from LMCache to Plugin
+
+LMCache passes configuration to plugins via **environment
+variables**. The core variable is `LMCACHE_RUNTIME_PLUGIN_CONFIG`,
+whose value is a JSON string containing the full LMCache server
+configuration.
+
+### Input Sources
+
+```
+CLI arguments
+  --runtime-plugin-locations  ->  RuntimePluginConfig.locations
+  --runtime-plugin-config     ->  RuntimePluginConfig.extra_config (JSON)
+  --http-host / --http-port   ->  HTTPFrontendConfig
+                                  (optional, forwarded by http_server.py)
+
+MPRuntimePluginLauncher.__init__(
+    runtime_plugin_config,   # locations + extra_config
+    mp_config,               # ZMQ server config
+    storage_manager_config,  # storage config
+    obs_config,              # observability config
+    http_config,             # HTTP config (optional)
+)
+```
+
+### Config JSON Structure
+
+```json
+{
+  "mp_config": {
+    "host": "localhost",
+    "port": 5555,
+    "chunk_size": 256,
+    "max_workers": 1,
+    "hash_algorithm": "blake3",
+    "engine_type": "default",
+    "runtime_plugin_config": {
+      "locations": ["examples/mp_runtime_plugins/"],
+      "extra_config": {}
+    }
+  },
+  "storage_manager_config": {
+    "l1_manager_config": {
+      "memory_config": {
+        "size_in_bytes": 10737418240,
+        "use_lazy": true
+      }
+    },
+    "eviction_config": {
+      "eviction_policy": "LRU",
+      "trigger_watermark": 0.8,
+      "eviction_ratio": 0.2
+    }
+  },
+  "obs_config": {
+    "enabled": true,
+    "metrics_enabled": true,
+    "logging_enabled": true,
+    "tracing_enabled": false
+  },
+  "http_config": {
+    "http_host": "0.0.0.0",
+    "http_port": 8080
+  },
+  "runtime_plugin_extra_config": {
+    "plugin.frontend.heartbeat_url": "http://discover-service:5000/heartbeat"
+  }
+}
+```
+
+`runtime_plugin_extra_config` is only present when
+`RuntimePluginConfig.extra_config` is non-empty; it is merged in by
+`_MPPluginConfig.to_json()`.
+
+### How Plugins Read the Config
+
+```python
+import json
+import os
+
+raw = os.getenv("LMCACHE_RUNTIME_PLUGIN_CONFIG", "{}")
+config = json.loads(raw)
+
+mp_cfg = config.get("mp_config", {})
+http_cfg = config.get("http_config", {})
+extra = config.get("runtime_plugin_extra_config", {})
+```
+
+---
+
+## Use Cases
+
+### Use Case 1: Frontend Plugin (Service Discovery Heartbeat)
+
+**Scenario**: Run an HTTP frontend process alongside the LMCache MP
+server; the process periodically sends heartbeats to a discovery
+service so that a centralized frontend can track live LMCache nodes.
+
+**Components**:
+
+| Component | Path | Description |
+|---|---|---|
+| `lmcache_mp_frontend_plugin.py` | `lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py` | Plugin script; reads config and launches the frontend app |
+| `simple_discover_service.py` | `lmcache/tools/simple_discover_service.py` | Simple discovery service that receives heartbeats |
+| `app.py` | `lmcache/lmcache_frontend/app.py` | Centralized LMCache frontend; proxies requests to backend nodes |
+
+**Data Flow**:
+
+```mermaid
+sequenceDiagram
+    participant CLI as CLI / server.py
+    participant P as lmcache_mp_frontend_plugin.py
+    participant FA as Frontend App (app.py)
+    participant DS as Discover Service
+
+    CLI->>P: LMCACHE_RUNTIME_PLUGIN_CONFIG (env)
+    P->>P: Parse http_config + extra_config
+    P->>FA: app.main(--nodes [...] --port ... --no-http)
+    loop Every N seconds
+        FA->>DS: GET /heartbeat?api_address=http://localhost:8080
+    end
+    DS->>DS: Store heartbeat data
+    Note over DS: GET /lmcache_infos returns active nodes
+```
+
+**Startup Commands**:
+
+```bash
+# 1. Start discover service
+python -m lmcache.tools.simple_discover_service
+
+# 2. Start LMCache MP server with frontend plugin
+python -m lmcache.v1.multiprocess.http_server \
+    --host localhost --port 5555 \
+    --l1-size-gb 10 \
+    --http-host 0.0.0.0 --http-port 8080 \
+    --runtime-plugin-locations lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py \
+    --runtime-plugin-config '{"plugin.frontend.heartbeat_url": "http://localhost:5000/heartbeat"}'
+```
+
+**How the Plugin Uses the Config**:
+
+1. Reads `http_host` / `http_port` from `http_config` to
+   auto-build the `--nodes` argument, avoiding duplicate CLI flags.
+2. Reads `plugin.frontend.*` keys from `runtime_plugin_extra_config`
+   and converts them into `app.main()` CLI arguments (e.g.
+   `--heartbeat-url`).
+
+---
+
+### Use Case 2: Chunk Hash File Upload Agent
+
+**Scenario**: LMCache produces JSONL-format chunk hash files during
+operation (see [PR #2928](https://github.com/LMCache/LMCache/pull/2928)).
+A plugin acts as an agent that periodically scans and uploads those
+files to a remote storage service (S3, HDFS, OSS, etc.).
+
+**Plugin Responsibilities**:
+
+1. Read `storage_manager_config` from
+   `LMCACHE_RUNTIME_PLUGIN_CONFIG` to determine the chunk hash file
+   output directory.
+2. Read upload target settings from `runtime_plugin_extra_config`
+   (e.g. `plugin.uploader.s3_bucket`, `plugin.uploader.prefix`).
+3. Periodically scan the output directory and upload newly
+   produced `.jsonl` files to remote storage.
+4. Optionally archive or delete local files after successful
+   upload.
+
+---
+
+## Plugin Contract
+
+A runtime plugin **must**:
+
+1. Be a `.py` or `.sh` file in one of the configured
+   `runtime_plugin_locations`.
+2. Be executable by the detected interpreter (Python or Bash).
+3. Read configuration from the `LMCACHE_RUNTIME_PLUGIN_CONFIG`
+   environment variable if needed.
+
+A runtime plugin **should**:
+
+1. Print status / heartbeat messages to stdout (they will be
+   captured by the launcher and logged via `logger.info`).
+2. Handle `SIGTERM` gracefully for clean shutdown.
+3. Output single-line messages (each stdout line becomes a
+   separate log entry).
+
+---
+
+## Plugin Discovery & Filtering
+
+```
+runtime_plugin_locations: ["examples/mp_runtime_plugins/"]
+         │
+         ▼
+    Path.rglob("*.py") + Path.rglob("*.sh")
+         │
+         ▼
+    _should_skip_plugin(file, parts)
+         │
+         ├─ role is None? → skip role check (MP mode)
+         │
+         ├─ role is set? → parts[0].upper() must match
+         │                  role or be "ALL"
+         │
+         └─ worker_id check → parts[1] if numeric
+         │
+         ▼
+    _launch_plugin(file)
+         │
+         ├─ Detect interpreter (shebang → fallback)
+         ├─ Set environment variables
+         ├─ subprocess.Popen(...)
+         └─ Start capture thread
+```
+
+---
+
+## Example Plugins
+
+See `examples/mp_runtime_plugins/` for reference implementations:
+
+| File | Language | Description |
+|---|---|---|
+| `mp_plugin.py` | Python | Parses config, prints summary, runs periodic heartbeat |
+| `mp_heartbeat.sh` | Bash | Extracts config via `jq`, runs heartbeat loop |
+
+### Quick Start
+
+```bash
+python -m lmcache.v1.multiprocess.http_server \
+    --host localhost --port 5555 \
+    --l1-size-gb 10 \
+    --eviction-policy LRU \
+    --runtime-plugin-locations examples/mp_runtime_plugins/
+```
+
+Expected log output:
+
+```
+[mp_plugin.py] Started
+[mp_plugin.py] Config: {"mp_config": {...}, ...}
+[mp_heartbeat.sh] Config: {"mp_config": {...}, ...}
+```
+
+---
diff --git a/docs/design/v1/multiprocess/protocols/README.md b/docs/design/v1/multiprocess/protocols/README.md
new file mode 120000
index 0000000..dfca8dd
--- /dev/null
+++ b/docs/design/v1/multiprocess/protocols/README.md
@@ -0,0 +1 @@
+../../../../../lmcache/v1/multiprocess/protocols/README.md
\ No newline at end of file
diff --git a/docs/design/v1/multiprocess/raw_cuda_ipc.md b/docs/design/v1/multiprocess/raw_cuda_ipc.md
new file mode 100644
index 0000000..ef3d5f7
--- /dev/null
+++ b/docs/design/v1/multiprocess/raw_cuda_ipc.md
@@ -0,0 +1,75 @@
+# `RawCudaIPCWrapper` — sharing tensors allocated outside PyTorch
+
+## Why a second wrapper
+
+The default `CudaIPCWrapper` in `platform/cuda/ipc_wrapper.py` calls
+`tensor.untyped_storage()._share_cuda_()` to publish the storage over
+CUDA IPC. That path only works when the storage is owned by PyTorch's
+caching allocator. TRT-LLM's KV pool is published via
+`at::for_blob(...)` over a raw `cudaMalloc`, which means
+`_share_cuda_()` raises and the `vLLM`-style wrapper cannot be used.
+
+`RawCudaIPCWrapper` bypasses PyTorch's IPC layer:
+
+- **Sender** calls `cudaIpcGetMemHandle(data_ptr)` directly via
+  `cuda.bindings.runtime` to obtain a portable handle.
+- **Receiver** calls `cudaIpcOpenMemHandle(handle, ...)` to map the
+  remote pointer, wraps it as a flat `uint8` `cupy.ndarray` via
+  `UnownedMemory`, converts to `torch.Tensor` via DLPack, then
+  `view(dtype).reshape(shape)` to restore the logical layout.
+
+The `uint8` round-trip is deliberate — `bfloat16` and FP8 dtypes have
+no direct CuPy/NumPy equivalent, but the size in bytes is enough.
+DLPack carries no dtype semantics for the bytes view; `view(dtype)` on
+the torch side restores them.
+
+## Shared base rather than separate type
+
+`RawCudaIPCWrapper` is a **sibling** of `CudaIPCWrapper`: both subclass
+the device-agnostic `DeviceIPCWrapper` base (see
+[`device_ipc_wrapper_design.md`](device_ipc_wrapper_design.md) for the
+full hierarchy). Sharing a single base is load-bearing for the wire
+format:
+
+- `KVCache = list[DeviceIPCWrapper]` is the registered msgspec type for
+  `REGISTER_KV_CACHE`. msgspec does **not** support unions of custom
+  ext-encoded types — adding a parallel class with its own ext code
+  would force a wider decoder type and break either round-trip or the
+  existing `DeviceIPCWrapper` consumers.
+- The customized serializer (`_CUSTOMERIZED_SERIALIZERS`) is keyed on
+  `DeviceIPCWrapper` and dispatched by `isinstance`, so every subclass
+  instance encodes through the same path with **ext code 1**.
+- `Serialize` is `pickle.dumps(obj)`, which preserves the concrete
+  subclass identity. On the receiving side `Deserialize` reconstructs
+  the concrete subclass and `to_tensor` dispatches to the correct
+  override.
+
+The receiving server therefore needs no per-type branching: a
+`list[DeviceIPCWrapper]` arriving at
+`LMCacheDrivenTransferModule.register_kv_cache` contains any mix of
+concrete wrappers, and `to_tensor()` does the right thing.
+
+## Sender-side validation
+
+`RawCudaIPCWrapper.__init__` calls `assert_contiguous` (from
+`gpu_connector/utils.py`) instead of permuting. TRT-LLM allocates the
+pool contiguously, so the only valid recovery from a non-contiguous
+input is "the sender did something wrong" — surface it loudly rather
+than silently `.contiguous()`-ing and copying GBs of KV cache.
+
+## Reconstruction lifetime
+
+`UnownedMemory` takes `owner=self`, so the wrapper instance pins the
+mapping for the tensor's lifetime. The mapping is dropped when the
+wrapper is GC'd; the underlying TRT-LLM allocation outlives the
+wrapper. There is no symmetric `cudaIpcCloseMemHandle` call — torch
+controls the lifetime through DLPack reference counting plus
+CuPy/MemoryPointer's owner field.
+
+## Why no `_share_cuda_` fallback
+
+The wrapper does not try `_share_cuda_()` first. That would couple the
+two codepaths, and the failure mode is silent corruption (PyTorch
+returns a handle for a different region of memory than what the
+caller intended). Keeping `RawCudaIPCWrapper` as its own concrete
+sibling of `CudaIPCWrapper` keeps the choice at the call site.
diff --git a/docs/design/v1/multiprocess/worker_liveness.md b/docs/design/v1/multiprocess/worker_liveness.md
new file mode 100644
index 0000000..3173276
--- /dev/null
+++ b/docs/design/v1/multiprocess/worker_liveness.md
@@ -0,0 +1,184 @@
+# Worker Liveness Tracking and Reaping (Multiprocess Mode)
+
+Covers the MP server (`lmcache/v1/multiprocess/`) and the worker heartbeat in
+the vLLM multiprocess adapter.
+
+## 1. Problem
+
+When an engine worker dies without sending `UNREGISTER_KV_CACHE` (SIGKILL,
+OOM-kill, node loss), its per-instance state leaks on the MP server forever: the
+LMCache-driven `ContextEntry` (a `GPUCacheContext` holding CUDA IPC handles), the
+`EngineDrivenContextEntry` + `TransferStrategy` pair, and any blend-mode
+per-instance state (e.g. CB rope caches). Nothing observes worker death; on a
+shared server, leaked contexts accumulate until device memory is exhausted.
+
+Worse, `instance_id` is `os.getpid()`: containerized pods reuse small PIDs, so a
+new worker can register with a dead worker's id, and the idempotent register
+silently binds it to the stale context — wrong IPC handles, corrupted transfers.
+
+## 2. Design Overview
+
+The server already receives a periodic signal from every actively serving worker:
+the heartbeat PING. The design adds the worker's `instance_id` to that message,
+stamps `last_seen` on the per-instance entries that already exist, and runs one
+periodic scan that reaps entries silent longer than a timeout via the same cleanup
+as a client unregister. The heartbeat keeps its lazy start (first store/retrieve)
+and starts healthy; a live worker pings every interval, refreshing its `last_seen`,
+so it is never reaped while alive. Entries that never produced a liveness signal
+fall under a generous registration grace. Recovery reuses existing client
+machinery: on a genuine outage the heartbeat's pings fail, clearing `health_event`;
+when the server returns the unhealthy-to-healthy edge fires the recover callback,
+which re-registers — a noop when the entry survived.
+
+```
+engine worker adapter                            MP server
++---------------------------+                   +--------------------------------------+
+| HeartbeatThread           |   PING [id]       | ManagementModule                     |
+|  (instance_id, 10s)  -----+------------------>|  ping(id) -> touch_instance(id)      |
+|  lazy start on first req, |   (NORMAL pool)   |  reaper thread (scan = timeout/4)    |
+|   (starts healthy)        |                   |   -> reap_stale_instances(           |
+|  unhealthy->healthy edge  |                   |        timeout, registration_grace)  |
+|   -> re-register callback |   REGISTER        |   -> drop_instance_state(id) fan-out |
+|                           +------------------>|        |                |            |
+| register_kv_caches        |   STORE/RETRIEVE  |        v                v            |
+|  (no pings until traffic) |   (refresh too)   | LMCacheDriven/          BlendV3      |
+|                           |                   |  EngineDriven           (CB rope     |
+|                           |                   |  TransferModule          dropped)    |
+|                           |                   |  Entry{.., last_seen,               |
+|                           |                   |   has_liveness_signal}               |
++---------------------------+                   |  _lock (leaf); pop -> cleanup        |
+                                                +--------------------------------------+
+```
+
+## 3. Protocol Change
+
+The PING payload changes in place from `[]` to `[int | None]`; the response stays
+`bool`, always `True` (`None` marks an untracked prober such as the scheduler
+adapter, which registers nothing and is never reapable). PING keeps its BLOCKING
+dispatch on the NORMAL thread pool. SYNC dispatch was considered but rejected:
+SYNC runs on the MQ main loop, where a slow `REGISTER_KV_CACHE` (also SYNC) would
+block PING and make a live worker look dead. Sharing the NORMAL pool is in fact
+desirable — if the pool cannot answer PING within the heartbeat timeout, the
+worker *should* enter degraded mode (the same back-pressure signal). The payload
+change is wire-visible, so both sides upgrade together (Section 7).
+
+## 4. Instance ID Generation
+
+The worker adapter replaces `os.getpid()` with
+`uuid.uuid4().int & ((1 << 63) - 1)`, INFO-logged at construction so operators can
+correlate reap warnings with a specific pod. `uuid4` reads OS entropy (identically
+seeded processes cannot collide); the 63-bit mask keeps the value int64-safe.
+Every id-carrying request reads the same field, so no other payloads change.
+
+## 5. Server Side
+
+### 5.1 Liveness state and two-tier windows
+
+`ContextEntry` (LMCache-driven) and `EngineDrivenContextEntry` gain
+`last_seen: float` (`time.monotonic()`) and `has_liveness_signal: bool`, latched
+only by PING. The flag selects the staleness window: an entry that has pinged
+provably runs the heartbeat protocol and is judged on the reap timeout; one that
+never pinged (e.g. still warming under lazy start) is judged on the generous
+registration grace. `last_seen` is refreshed by PING (`touch_instance`: refresh
+if present, never insert), register (create and NOOP paths), and every transfer
+path, so a worker mid-transfer is never reaped; traffic never latches the flag.
+
+### 5.2 Locking
+
+The reaper runs on its own thread, so the per-instance dicts are now mutated off
+the MQ handler threads. Each transfer module gains one `threading.Lock` so the
+reaper's scan-and-pop cannot race a concurrent register/unregister/transfer (which
+would otherwise corrupt the dict or hand out a half-removed entry). In
+`EngineDrivenTransferModule` the context and strategy dicts mutate as a pair under
+that lock, so a reap racing a re-register can never strand a fresh context without its
+strategy. It is a leaf lock — never held across context construction, storage
+calls, or any other component — so no thread ever holds two locks. External
+readers use the locked accessors `get_and_touch_context_entry` (get-and-refresh) and
+`context_entries_snapshot` instead of touching the dict directly.
+
+### 5.3 Reaper
+
+`ManagementModule` (the PING owner) owns the reaper thread, scanning every
+`reap_timeout / 4`. Each scan calls `reap_stale_instances` on every target: under
+the module lock, collect ids whose staleness exceeds their window and pop them;
+outside the lock, run the same cleanup as a client unregister and log a WARNING
+per instance (repeated reaps of one id signal a too-small timeout). Reaped ids are
+then passed to `drop_instance_state(id)` on every target; `BlendV3Module` drops
+the reaped instance's per-instance CB state (e.g. rope state) there. (It no longer
+mirrors the GPU cache context — that mirror was removed upstream, so reaping the
+GPU entry now frees the context directly.) Collect+pop shares the module lock with
+register's refresh, serializing every register-vs-reap race; on close, the reaper
+is stopped and joined before any module clears state.
+
+### 5.4 Public protocol and config
+
+```python
+class InstanceLivenessTarget(Protocol):
+    # All methods default to a no-op; an implementer overrides only its role.
+    def touch_instance(self, instance_id: int) -> None: ...
+    def reap_stale_instances(
+        self, reap_timeout_s: float, registration_grace_s: float
+    ) -> list[int]: ...
+    def tracked_instance_count(self) -> int: ...
+    def drop_instance_state(self, instance_id: int) -> None: ...
+```
+
+One protocol covers both reaper-driven roles. The transfer modules override the
+liveness methods (`touch`/`reap`/`count`); `BlendV3Module` overrides only
+`drop_instance_state` to drop its mirrored CB state. `ManagementModule` receives
+all targets in a single injected list. (Earlier a separate one-method
+`InstanceReapListener` held `drop_instance_state`; it was folded in since only
+`BlendV3Module` ever implemented it.)
+
+Config: `worker_reap_timeout_seconds` (default `120.0`; `0` disables, otherwise
+`>= 30.0`) and `worker_registration_grace_seconds` (default `3600.0`; `>=` the
+reap timeout — a tighter grace would reap warming workers faster than crashed
+ones), with matching CLI flags. Keep the timeout `>= 3 x` the client's
+`lmcache.mp.heartbeat_interval` so a few missed pings never reap a live worker;
+the worker adapter warns at startup when `3 x interval` exceeds the 30 s floor.
+
+## 6. Adapter Side
+
+### 6.1 Lazy start
+
+The heartbeat keeps its lazy start on first store/retrieve — no pings during
+warmup; the registration grace covers that window. It starts healthy (the event
+is set at construction), so the first store/retrieve is not gated. A live worker
+then pings every interval, refreshing its server-side `last_seen`, so it is never
+reaped while alive — no re-registration is needed at start. The recover callback
+re-registers only on a genuine recovery edge (Section 6.2). A retrieve dropped
+while the server is unhealthy is still reported via `get_finished` so async loads
+cannot hang.
+
+### 6.2 Recovery after a reap
+
+```
+T0        outage begins; pings time out -> health_event cleared, traffic stops
+T0+120s   server: entry stale -> reap pops it, frees GPUCacheContext/IPC,
+          layout-desc refcount; blend rope state dropped via listener <- leak fixed
+T1        connectivity back; next ping succeeds -> unhealthy->healthy edge
+T1        recover callback re-registers (id absent -> fresh context) before
+          health_event is set; traffic resumes             <- exactly one context
+```
+
+A shorter outage hits the NOOP register path, which refreshes `last_seen` and
+builds nothing — the server never asks a worker to re-register.
+
+### 6.3 Shutdown
+
+`shutdown()` stops the heartbeat before sending UNREGISTER, so no stray ping
+lands on a closing client. The heartbeat cycle skips the recover callback and
+`health_event.set()` once stopped, and the callback skips re-registration when a
+stop is already requested — a straggling cycle cannot re-create a ghost context.
+
+## 7. Failure Modes
+
+| Scenario | Behavior |
+|---|---|
+| Worker crash (SIGKILL, no UNREGISTER) after serving | Pings stop; reaped within ~`timeout + timeout/4`. Context, IPC handles, layout-desc refcount, and non-GPU strategy released via the same cleanup as a clean unregister; blend rope state dropped via the reap listener. The bug being fixed. |
+| Worker crash during warmup (registered, never pinged) | Reaped on the registration grace. Bounded leak instead of a permanent one. |
+| Worker alive but never pinged, idle past the grace | Reaped while alive only if it never pinged (heartbeat never started). Once the heartbeat is running, pings refresh `last_seen` every interval, so a live worker is never reaped regardless of traffic. |
+| Heartbeat thread starved, worker transferring | Store/retrieve/prepare/commit refresh `last_seen`; never reaped. |
+| Partition shorter than the reap window | No reap. On heal, the recover callback re-registers; the NOOP path refreshes `last_seen`; zero context churn. |
+| Worker crash + restart | The new process gets a fresh uuid-derived id and a fresh entry; the dead id is reaped independently. No PID-reuse aliasing. |
+| Mixed client/server versions | Every PING fails the payload-count check; the client sits permanently unhealthy. Loud, never silent corruption; upgrade both sides together. |
diff --git a/docs/design/v1/pd_async_reservation_design.md b/docs/design/v1/pd_async_reservation_design.md
new file mode 100644
index 0000000..6dee729
--- /dev/null
+++ b/docs/design/v1/pd_async_reservation_design.md
@@ -0,0 +1,171 @@
+# PD Async Reservation-Based Admission Control
+
+## Problem
+
+In chunked-prefill mode, large prompts are split into multiple sequential batches. Each batch allocates physical buffer slots on the receiver before the RDMA write. With multiple concurrent requests, this interleaved allocation creates a deadlock: N requests each partially fill the staging buffer, none can complete their full chunk set, and the buffer never drains.
+
+**Example (buffer = 10 chunks):**
+```
+Req A needs 8 chunks, Req B needs 8 chunks
+A allocates 5 → B allocates 5 → buffer full
+A needs 3 more → blocked, B needs 3 more → blocked → DEADLOCK
+```
+
+## Solution: Reservation-Based Admission
+
+Reserve `total_chunks` upfront per request before any physical allocation. If the buffer can't accommodate the full reservation, the request waits. Once admitted, all subsequent allocations for that request are guaranteed to succeed.
+
+```
+Buffer = 10 chunks
+A requests admission (8 chunks) → reserved=8, available=2
+B requests admission (8 chunks) → 8 > 2 → WAIT
+A completes all 8 chunks → RDMA done → release reservation → available=10
+B admitted → reserved=8, proceeds
+```
+
+## Architecture
+
+### Components
+
+```
+┌─────────────────────────────────────────────┐
+│                vLLM Worker Thread            │
+│  wait_for_save()                            │
+│    ├─ store() × N batches              ←─── allocate + from_gpu per batch
+│    │   ├─ allocate()                   ←─── blocks on _staging_condition if buffer full
+│    │   └─ batched_submit_put_task()    ←─── submits to sender loop, returns immediately
+└─────────────────────────────────────────────┘
+              │ asyncio.run_coroutine_threadsafe
+              ▼
+┌─────────────────────────────────────────────┐
+│             Sender Event Loop               │
+│  _async_transfer_task() (concurrent)        │
+│    ├─ _async_remote_allocate()  ←────────── ZMQ REQ/REP to receiver
+│    ├─ async_batched_write()     ←────────── RDMA write
+│    ├─ ref_count_down()          ←────────── free sender staging buffer
+│    ├─ _notify_staging_freed()   ←────────── wake allocate() waiters
+│    └─ _check_and_send_proxy_notif()         │
+│         └─ ProxyNotif via ZMQ PUSH          │
+└─────────────────────────────────────────────┘
+              │ ZMQ DEALER/ROUTER
+              ▼
+┌─────────────────────────────────────────────┐
+│           Receiver Event Loop               │
+│  _handle_alloc_request()                    │
+│    ├─ CancelNotif → release keys + reservation
+│    └─ AllocRequest → _async_allocate_and_put()
+│         ├─ async_try_admit() (first batch)  │
+│         ├─ allocate() per chunk             │
+│         └─ put() → register KV object       │
+└─────────────────────────────────────────────┘
+```
+
+### ReservationManager
+
+**Used exclusively on the receiver side** for reservation-based admission control:
+
+- **Receiver** (asyncio): `async_try_admit()` / `async_release_reservation()` — called from receiver event loop
+
+The sender does NOT use `ReservationManager`. Instead, the sender uses **physical staging buffer flow control**: `allocate()` blocks on `_staging_condition` when the staging buffer is full, and is woken by `_notify_staging_freed()` after RDMA completes and `ref_count_down()` frees buffer slots.
+
+Key invariant (receiver only): `total_reserved <= total_chunks` at all times.
+
+### Lock Inventory
+
+| Path | Lock | Type | Purpose |
+|------|------|------|---------|
+| Sender worker thread | `_staging_condition` | threading.Condition | Wait for staging buffer slots |
+| Sender loop | `_async_alloc_locks[receiver_id]` | asyncio.Lock | Serialize ZMQ to same receiver |
+| Sender loop | `_proxy_send_lock` | asyncio.Lock | Serialize ProxyNotif sends |
+| Receiver loop | `_recv_reservation_mgr._async_admit_condition` | asyncio.Condition | Async admission wait |
+| Receiver loop | `_alloc_freed_condition` | asyncio.Condition | Wake allocation retries when chunks freed |
+
+### ProxyNotif Ordering
+
+Since batches run concurrently, `is_last_prefill` batch may complete RDMA before earlier batches. ProxyNotif fires only when BOTH:
+1. `completed_chunks >= total_chunks` (all RDMA done)
+2. `req_has_last == True` (is_last_prefill batch completed)
+
+**Note:** Legacy senders that do not set `total_chunks` (i.e., `total_chunks == 0`) are no longer supported. The receiver will raise a `RuntimeError` if it encounters a request with `total_chunks == 0` on the first batch.
+
+### Abort Flow
+
+```
+request_finished(ABORTED)
+  → cancel_request(req_id)           # any thread
+    → wake _staging_condition        # unblocks allocate() if waiting
+    → schedule _abort_request()      # on sender loop
+      → CancelNotif to receiver      # release remote keys + reservation
+      → clear per-request state      # clean up sender tracking
+```
+
+### Message Types
+
+| Message | Direction | Purpose |
+|---------|-----------|---------|
+| AllocRequest | sender → receiver | Allocate remote buffer slots. `total_chunks` field for first-batch reservation |
+| AllocResponse | receiver → sender | Remote buffer addresses (-1 on failure) |
+| ProxyNotif | sender → proxy | All RDMA done, decoder can start consuming |
+| CancelNotif | sender → receiver | Request aborted, release allocated keys |
+
+### Concurrency Model (2P1D example)
+
+```
+Buffer = 20 chunks, P1 req A (10), P2 req B (10)
+
+Old (serial admission):
+  P1: [=== transfer A ===]
+  P2: [     wait          ][=== transfer B ===]
+  Total: A + B
+
+New (reservation):
+  P1: [=== transfer A ===]
+  P2: [=== transfer B ===]    ← concurrent RDMA from different peers
+  Total: max(A, B)
+```
+
+## Receiver Admission Control
+
+The receiver uses a single `ReservationManager` (`_recv_reservation_mgr`) as the sole source of truth for buffer capacity. On the first batch for each request, the receiver calls `async_try_admit(req_id, total_chunks)` to reserve the full chunk set. Subsequent batches for the same request draw from the existing reservation and allocate immediately.
+
+**All senders must set `total_chunks > 0`.** If the receiver encounters a request with `total_chunks == 0` on the first batch, it raises a `RuntimeError` immediately. Legacy senders are no longer supported.
+
+The reservation is released on the receiver side when the last batch of a request is successfully allocated (signaled by `is_last_batch == True` in the `AllocRequest`), when a batch fails (triggering full request rollback), or on abort via `CancelNotif`.
+
+## Sender Flow Control
+
+The sender does NOT use reservation-based admission control. Instead, it relies on **physical staging buffer flow control**:
+
+1. **Allocation**: When a vLLM worker thread calls `allocate()` to get staging buffer slots for a new chunk:
+   - If slots are available, allocation succeeds immediately
+   - If the staging buffer is full, `allocate()` blocks on `_staging_condition`
+
+2. **RDMA Completion**: After each batch completes RDMA write in `_async_transfer_task()`:
+   - `ref_count_down()` frees the staging buffer slots
+   - `_notify_staging_freed()` wakes all threads waiting on `_staging_condition`
+   - Blocked `allocate()` calls retry and may now succeed
+
+3. **Concurrency**: Multiple requests can allocate and transfer concurrently, limited only by physical staging buffer capacity. The receiver's reservation system prevents deadlock by ensuring each admitted request can complete its full chunk set.
+
+## Fail-Fast Detection and Error Handling
+
+### Protocol Violation Detection
+
+If the cumulative number of chunks for a request exceeds the declared `total_chunks` from the `AllocRequest`, the receiver raises a `RuntimeError` immediately. This detects protocol violations where the sender attempts to send more chunks than it originally declared.
+
+When a protocol violation is detected:
+1. All previously allocated chunks for the request are removed (rollback of prior batches)
+2. The request tracking state is cleaned up
+3. The reservation is released to free buffer capacity
+4. A `RuntimeError` is raised with details about the violation
+
+### Batch Failure Handling
+
+If any batch for a request fails during allocation (e.g., timeout, memory exhaustion), the receiver performs a **full request rollback**:
+
+1. **Current batch rollback**: Remove all chunks allocated in the failing batch
+2. **Prior batch rollback**: Remove all chunks allocated in previous successful batches for the same request
+3. **State cleanup**: Remove request tracking (`_req_allocated_keys`) and release the reservation
+4. **Error propagation**: Raise the exception to inform the sender
+
+This comprehensive rollback ensures that partial request state is never left in the buffer when any batch fails, since the decoder requires all chunks to proceed.
diff --git a/docs/design/v1/platform/event_notifier.md b/docs/design/v1/platform/event_notifier.md
new file mode 100644
index 0000000..9ca05ec
--- /dev/null
+++ b/docs/design/v1/platform/event_notifier.md
@@ -0,0 +1,206 @@
+# Cross-Platform Event Notification
+
+Location: `lmcache/v1/platform/event_notifier.py`
+(re-exported from the `lmcache.v1.platform` package)
+
+## Background
+
+LMCache's multiprocess / distributed runtime uses a large number of
+**pollable file descriptors** to wake background loops from other
+threads:
+
+- `mq.MessageQueueServer._output_efd` — notify the poller that a
+  response frame is ready on the thread-pool output queue.
+- `StoreListener._event_fd` — notify the store-controller loop that
+  L1 has finished writing new keys.
+- `PrefetchController._submission_efd` — notify the prefetch loop of
+  a newly submitted request.
+- Every `L2Adapter` exposes three event fds
+  (`get_store_event_fd()`, `get_lookup_and_lock_event_fd()`,
+  `get_load_event_fd()`) so controllers can `select.poll()` across
+  all adapters in a single loop.
+
+Previously these were all raw `os.eventfd(...)`. `os.eventfd` is a
+Linux-only syscall, which blocks the MP/distributed stack from
+running on macOS (and any other non-Linux POSIX system).
+
+## Goals
+
+1. Let the exact same code paths run on Linux (using `eventfd`) and
+   on macOS / other POSIX (using a self-pipe).
+2. Keep the call-site diff small — existing sites should look as
+   close as possible to the `os.eventfd(...)` version they replace.
+3. No global state, no monkey-patching of `os`, no hidden
+   process-wide registries.
+4. Give callers a single abstraction rather than each module doing
+   its own `hasattr(os, "eventfd")` dance.
+
+## Non-Goals
+
+- Cross-process signaling. `EventNotifier` is for in-process
+  thread-to-thread wake-ups. The fd is created in one process and
+  never shared via IPC.
+- Counting semaphore semantics. `notify()` is a **binary signal**;
+  coalescing is expected.
+
+## Design
+
+### Public API
+
+```python
+# lmcache/v1/platform/event_notifier.py
+# (re-exported via `lmcache.v1.platform` for short imports)
+
+class EventNotifier(ABC):
+    def fileno(self) -> int: ...      # poll-able fd
+    def notify(self) -> None: ...     # signal (idempotent)
+    def consume(self) -> None: ...    # drain (non-blocking)
+    def close(self) -> None: ...      # idempotent
+
+    def __enter__(self) -> "EventNotifier": ...
+    def __exit__(self, *exc) -> None: ...
+
+def create_event_notifier() -> EventNotifier: ...
+def consume_fd(fd: int) -> None: ...
+```
+
+Two concrete implementations:
+
+| Implementation    | Backend      | Selected when                    |
+|-------------------|--------------|----------------------------------|
+| `EventfdNotifier` | `os.eventfd` | `HAS_EVENTFD` (Linux + Py 3.10+) |
+| `PipeNotifier`    | `os.pipe`    | otherwise (macOS / other POSIX)  |
+
+Selection is centralized in `create_event_notifier()`; callers never
+branch on the platform. `HAS_EVENTFD` is defined as
+`hasattr(os, "eventfd")` in `lmcache/v1/platform/event_notifier.py`
+and re-exported from the `lmcache.v1.platform` package — the single
+source of truth for platform capability detection.
+
+On non-Linux platforms the `EventfdNotifier` symbol still exists as
+a placeholder whose `__init__` raises `RuntimeError`, so
+`isinstance(..., EventfdNotifier)` checks in tests stay valid.
+
+`consume_fd(fd)` is a module-level helper for callers that only have
+a raw fd (typical case: a controller that received an fd via
+`adapter.get_store_event_fd()` and wants to drain it after
+`poll()`). It dispatches to the right syscall based on the same
+`HAS_EVENTFD` flag.
+
+### Semantics
+
+`EventNotifier` models a **binary signal**:
+
+- After `notify()`, the fd is readable via `select.poll()`.
+- `consume()` drains all pending signals so the fd is no longer
+  readable.
+- Multiple `notify()` calls before a `consume()` are coalesced.
+  Callers must not rely on a counter — they must re-check the
+  underlying work queue after being woken.
+- `consume()` is non-blocking and safe to call on an unsignaled fd.
+- `close()` is idempotent.
+
+### Exception contract
+
+`consume()` and the module-level `consume_fd(fd)` helper **only
+swallow `BlockingIOError`** (i.e. "no data pending on a non-blocking
+fd"). Every other `OSError` subclass — most importantly `EBADF` from
+a stale or already-closed fd — propagates to the caller so caller
+bugs surface instead of being silently absorbed.
+
+`notify()` swallows `BlockingIOError` in `PipeNotifier` because a
+full pipe means a signal is *already* pending, which is the
+post-condition we want. On `EventfdNotifier`, the counter only
+blocks on overflow (max `2**64 - 2`), which we treat as unreachable
+in practice.
+
+`close()` is fully idempotent and swallows any `OSError` during
+`os.close`, since there is nothing a caller could do about it.
+
+### Backend Differences
+
+**`EventfdNotifier`** (Linux) wraps a single eventfd opened with
+`EFD_NONBLOCK | EFD_CLOEXEC`. `notify()` writes `1`, `consume()`
+reads the 8-byte counter.
+
+**`PipeNotifier`** (macOS / other POSIX) wraps an `os.pipe()` pair.
+Since Python 3.4 (PEP 446) `os.pipe()` already sets `FD_CLOEXEC`,
+so `__init__` only needs to flip both ends to non-blocking via
+`os.set_blocking(fd, False)` — a portable API that avoids pulling
+in `fcntl` and is friendlier to a future Windows pipe backend. If
+either `set_blocking` call fails, both fds are closed before the
+error propagates so no descriptors leak.
+
+`notify()` writes a single `\x01` byte; `consume()` drains the read
+end in a loop. If the pipe buffer is full, `notify()` is a no-op —
+the signal is already pending. Both `PipeNotifier.consume()` and
+the module-level `consume_fd()` treat an empty read (`b''`, i.e.
+the write end was closed) as "drained" and stop looping, so a dead
+pipe can never spin a background event loop.
+
+### Architecture
+
+```mermaid
+graph LR
+  Caller -->|create_event_notifier| Factory
+  Factory -->|HAS_EVENTFD| EventfdNotifier
+  Factory -->|fallback| PipeNotifier
+  EventfdNotifier -->|os.eventfd| Kernel
+  PipeNotifier -->|os.pipe| Kernel
+```
+
+## Call-Site Migration
+
+Before (Linux-only):
+
+```python
+import os
+self._event_fd = os.eventfd(0, os.EFD_NONBLOCK | os.EFD_CLOEXEC)
+...
+os.eventfd_write(self._event_fd, 1)
+...
+os.eventfd_read(self._event_fd)
+...
+os.close(self._event_fd)
+```
+
+After (cross-platform):
+
+```python
+from lmcache.v1.platform import create_event_notifier
+
+self._event_fd = create_event_notifier()
+...
+self._event_fd.notify()
+...
+self._event_fd.consume()        # or: consume_fd(raw_fd)
+...
+self._event_fd.close()
+```
+
+The field name (`_event_fd`, `_output_efd`, `_submission_efd`, etc.)
+is kept deliberately — the variable is still "the thing you poll
+on", and reusing the name keeps the diff focused on the semantic
+change.
+
+## Testing
+
+Unit tests live in `tests/v1/test_event_notifier.py`. They cover:
+
+- **`TestEventNotifierAPI`** — platform-agnostic contract:
+  factory returns an `EventNotifier` subclass; `fileno()` returns a
+  valid fd; `notify()` makes the fd readable and `consume()` clears
+  it; multiple `notify()` calls coalesce; `consume()` and `close()`
+  are idempotent; context-manager usage.
+- **`TestPipeNotifier`** — pipe-specific: both read/write fds are
+  released by `close()`; pipe-full triggers the `BlockingIOError`
+  swallow path in `notify()`; many create/close cycles do not leak
+  fds; fd is pollable.
+- **`TestConsumeFd`** — the `consume_fd(raw_fd)` utility drains a
+  signaled fd and is a no-op on an unsignaled one.
+- **`TestBackendSelection`** — asserts the factory picks
+  `EventfdNotifier` when `HAS_EVENTFD` and `PipeNotifier` otherwise.
+- **`TestForcedPipeFallback`** — on Linux CI the factory would
+  normally return `EventfdNotifier`; this class `monkeypatch`es
+  `HAS_EVENTFD` to `False` so the pipe fallback (and `consume_fd`'s
+  pipe branch) is exercised on every platform.
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..747ffb7
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/.nojekyll b/docs/source/.nojekyll
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/_static/basic_codepath.svg b/docs/source/_static/basic_codepath.svg
new file mode 100644
index 0000000..d910b87
--- /dev/null
+++ b/docs/source/_static/basic_codepath.svg
@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="800" height="600" xmlns="http://www.w3.org/2000/svg">
+  <!-- Background -->
+  <rect width="800" height="600" fill="#f8f9fa"/>
+  
+  <!-- GPU Model Runner Box -->
+  <rect x="50" y="50" width="700" height="500" fill="#e3f2fd" stroke="#1976d2" stroke-width="3" rx="10"/>
+  <text x="400" y="40" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="#1976d2">GPU Model Runner</text>
+  
+  <!-- start_load_kv() -->
+  <rect x="80" y="80" width="640" height="40" fill="#ffecb3" stroke="#f57f17" stroke-width="2" rx="5"/>
+  <text x="400" y="105" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#f57f17">start_load_kv()</text>
+  
+  <!-- Layer 1 -->
+  <g>
+    <rect x="100" y="140" width="600" height="80" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+    
+    <!-- wait_for_layer_load() -->
+    <rect x="120" y="150" width="200" height="25" fill="#e1bee7" stroke="#8e24aa" stroke-width="1" rx="3"/>
+    <text x="220" y="167" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#4a148c">wait_for_layer_load()</text>
+    
+    <!-- Attention 1 -->
+    <rect x="340" y="150" width="120" height="25" fill="#fff3e0" stroke="#ef6c00" stroke-width="1" rx="3"/>
+    <text x="400" y="167" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#bf360c">Attention 1</text>
+    
+    <!-- save_kv_layer() -->
+    <rect x="480" y="150" width="200" height="25" fill="#e8f5e8" stroke="#388e3c" stroke-width="1" rx="3"/>
+    <text x="580" y="167" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#1b5e20">save_kv_layer()</text>
+    
+    <!-- Arrow from wait_for_layer_load to Attention -->
+    <path d="M 320 162.5 L 340 162.5" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+    
+    <!-- Arrow from Attention to save_kv_layer -->
+    <path d="M 460 162.5 L 480 162.5" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+  </g>
+  
+  <!-- Layer 2 -->
+  <g>
+    <rect x="100" y="240" width="600" height="80" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+    
+    <!-- wait_for_layer_load() -->
+    <rect x="120" y="250" width="200" height="25" fill="#e1bee7" stroke="#8e24aa" stroke-width="1" rx="3"/>
+    <text x="220" y="267" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#4a148c">wait_for_layer_load()</text>
+    
+    <!-- Attention 2 -->
+    <rect x="340" y="250" width="120" height="25" fill="#fff3e0" stroke="#ef6c00" stroke-width="1" rx="3"/>
+    <text x="400" y="267" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#bf360c">Attention 2</text>
+    
+    <!-- save_kv_layer() -->
+    <rect x="480" y="250" width="200" height="25" fill="#e8f5e8" stroke="#388e3c" stroke-width="1" rx="3"/>
+    <text x="580" y="267" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#1b5e20">save_kv_layer()</text>
+    
+    <!-- Arrow from wait_for_layer_load to Attention -->
+    <path d="M 320 262.5 L 340 262.5" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+    
+    <!-- Arrow from Attention to save_kv_layer -->
+    <path d="M 460 262.5 L 480 262.5" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+  </g>
+  
+  <!-- Dots indicating more layers -->
+  <g>
+    <circle cx="400" y="350" r="3" fill="#666"/>
+    <circle cx="400" y="365" r="3" fill="#666"/>
+    <circle cx="400" y="380" r="3" fill="#666"/>
+  </g>
+  
+  <!-- Layer N -->
+  <g>
+    <rect x="100" y="400" width="600" height="80" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+    
+    <!-- wait_for_layer_load() -->
+    <rect x="120" y="410" width="200" height="25" fill="#e1bee7" stroke="#8e24aa" stroke-width="1" rx="3"/>
+    <text x="220" y="427" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#4a148c">wait_for_layer_load()</text>
+    
+    <!-- Attention N -->
+    <rect x="340" y="410" width="120" height="25" fill="#fff3e0" stroke="#ef6c00" stroke-width="1" rx="3"/>
+    <text x="400" y="427" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#bf360c">Attention N</text>
+    
+    <!-- save_kv_layer() -->
+    <rect x="480" y="410" width="200" height="25" fill="#e8f5e8" stroke="#388e3c" stroke-width="1" rx="3"/>
+    <text x="580" y="427" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#1b5e20">save_kv_layer()</text>
+    
+    <!-- Arrow from wait_for_layer_load to Attention -->
+    <path d="M 320 422.5 L 340 422.5" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+    
+    <!-- Arrow from Attention to save_kv_layer -->
+    <path d="M 460 422.5 L 480 422.5" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+  </g>
+  
+  <!-- wait_for_save() -->
+  <rect x="150" y="500" width="500" height="40" fill="#ffcdd2" stroke="#c62828" stroke-width="2" rx="5"/>
+  <text x="400" y="525" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#b71c1c">wait_for_save()</text>
+  
+  <!-- Arrow definitions -->
+  <defs>
+    <marker id="arrowhead" markerWidth="10" markerHeight="7" 
+            refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#666"/>
+    </marker>
+  </defs>
+  
+  <!-- Vertical flow arrows -->
+  <path d="M 400 120 L 400 140" stroke="#333" stroke-width="3" marker-end="url(#arrowhead)"/>
+  <path d="M 400 220 L 400 240" stroke="#333" stroke-width="3" marker-end="url(#arrowhead)"/>
+  <path d="M 400 480 L 400 500" stroke="#333" stroke-width="3" marker-end="url(#arrowhead)"/>
+  
+</svg> 
\ No newline at end of file
diff --git a/docs/source/_static/bench_interactive_demo.gif b/docs/source/_static/bench_interactive_demo.gif
new file mode 100644
index 0000000..3224152
Binary files /dev/null and b/docs/source/_static/bench_interactive_demo.gif differ
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
new file mode 100644
index 0000000..ede2e7b
--- /dev/null
+++ b/docs/source/_static/custom.css
@@ -0,0 +1,143 @@
+/* Force white background on all Mermaid diagrams and fix sizing */
+.mermaid {
+    background-color: #ffffff !important;
+    padding: 10px !important;
+    border-radius: 8px !important;
+    margin: 10px 0 !important;
+    display: flex !important;
+    justify-content: center !important;
+}
+
+.mermaid svg {
+    background-color: #ffffff !important;
+    height: auto !important;
+    max-height: 300px !important;
+}
+
+/* Tighter fit for flowcharts */
+.mermaid[data-processed="true"] {
+    overflow: visible !important;
+}
+
+.mermaid svg[id^="flowchart"] {
+    max-height: 250px !important;
+}
+
+/* Hide extra buttons if multiple are showing */
+div.highlight button.copybtn + button.copybtn {
+    display: none;
+  }
+
+  /* Remove unwanted "Copy code" text from clipboard (for older versions) */
+  .copybtn::before {
+    content: none !important;
+  }
+
+  /* Style the copy button */
+  button.copybtn {
+    background-color: #4a90e2;
+    color: white;
+    border: none;
+    border-radius: 5px;
+    font-size: 12px;
+    padding: 4px 8px;
+    cursor: pointer;
+    position: absolute;
+    top: 0.4em;
+    right: 0.6em;
+    opacity: 0.8;
+    transition: opacity 0.2s ease-in-out;
+    z-index: 3;
+  }
+
+  button.copybtn:hover {
+    opacity: 1;
+  }
+
+  /* Optional: Hide the copied tooltip or style it */
+  .copybtn:after {
+    content: "Copied!";
+    display: none;
+    position: absolute;
+    top: -1.5em;
+    right: 0;
+    background: #333;
+    color: #fff;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-size: 10px;
+  }
+
+/* Language switcher (中文 | Eng) — lives in the top nav bar,
+   or floats at top-right if the nav bar isn't found. */
+.lmcache-language-switcher {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    margin: 0 6px;
+    padding: 4px 10px;
+    white-space: nowrap;
+    font-size: 16px;
+    font-weight: 700;
+    line-height: 1;
+    color: var(--foreground);
+    border-radius: 8px;
+}
+
+/* When there's no nav bar, float at top-right instead */
+.lmcache-language-switcher--fallback {
+    position: fixed;
+    top: 10px;
+    right: 72px;
+    z-index: 60;
+}
+
+.lmcache-language-switcher a {
+    color: inherit;
+    opacity: 0.72;
+    text-decoration: none;
+}
+
+.lmcache-language-switcher a:hover,
+.lmcache-language-switcher a:focus-visible,
+.lmcache-language-switcher a[aria-current="page"] {
+    opacity: 1;
+}
+
+.lmcache-language-switcher__divider {
+    opacity: 0.38;
+}
+
+/* Make top-level collapsible nav items read as section headers:
+   when a section is represented as a single index page (no toctree
+   :caption:), bold its top-level entry so it still looks like a section
+   while remaining a fold-out dropdown. */
+nav .toctree-l1 > a.expandable {
+    font-weight: 700;
+}
+
+/* Separate top-level collapsible sections with spacing + a subtle divider
+   so each reads as its own section even without a :caption: header. */
+nav .toctree-l1:has(> a.expandable) {
+    margin-top: 0.85rem;
+    padding-top: 0.6rem;
+    border-top: 1px solid rgba(128, 128, 128, 0.25);
+}
+
+/* Homepage hero text (translatable RST replacing former raw HTML) */
+.hero-tagline {
+    text-align: center;
+    font-size: 24px;
+    font-weight: bold;
+}
+
+.hero-description {
+    text-align: justify;
+}
+
+/* Theme-aware images: show the light variant by default, swap to the dark
+   variant when the sphinxawesome theme is in dark mode (html.dark). */
+.only-dark { display: none; }
+html.dark .only-light { display: none; }
+html.dark .only-dark { display: revert; }
diff --git a/docs/source/_static/custom.js b/docs/source/_static/custom.js
new file mode 100644
index 0000000..21202ab
--- /dev/null
+++ b/docs/source/_static/custom.js
@@ -0,0 +1,283 @@
+/**
+ * Add the RunLLM assistant widget script once per page.
+ *
+ * @returns {void}
+ */
+function addRunLlmWidget() {
+  if (document.getElementById("runllm-widget-script")) {
+    return;
+  }
+
+  var script = document.createElement("script");
+  script.type = "module";
+  script.id = "runllm-widget-script";
+
+  script.src = "https://widget.runllm.com";
+
+  script.setAttribute("version", "stable");
+  script.setAttribute("crossorigin", "true");
+  script.setAttribute("runllm-keyboard-shortcut", "Mod+j");
+  script.setAttribute("runllm-name", "LMCache Assistant");
+  script.setAttribute("runllm-position", "BOTTOM_RIGHT");
+  script.setAttribute("runllm-assistant-id", "1185");
+
+  script.async = true;
+  document.head.appendChild(script);
+}
+
+/**
+ * Return true when the current page is rendered under the Chinese docs prefix.
+ *
+ * @returns {boolean} Whether the current path is a Chinese documentation page.
+ */
+function isChineseDocsPage() {
+  return window.location.pathname.split("/").includes("zh_CN");
+}
+
+/**
+ * Build the target language URL for the current page.
+ *
+ * @param {"en" | "zh_CN"} language The target language.
+ * @returns {string} The target URL.
+ */
+function buildLanguageUrl(language) {
+  var pathParts = window.location.pathname.split("/");
+  var zhIndex = pathParts.indexOf("zh_CN");
+
+  if (language === "zh_CN" && zhIndex === -1) {
+    pathParts.splice(1, 0, "zh_CN");
+  } else if (language === "en" && zhIndex !== -1) {
+    pathParts.splice(zhIndex, 1);
+  }
+
+  var nextPath = pathParts.join("/") || "/";
+  return nextPath + window.location.search + window.location.hash;
+}
+
+/**
+ * Build the home URL for a target language.
+ *
+ * @param {"en" | "zh_CN"} language The target language.
+ * @returns {string} The target language home URL.
+ */
+function buildLanguageHomeUrl(language) {
+  return language === "zh_CN" ? "/zh_CN/" : "/";
+}
+
+/**
+ * Fall back to the target language home page if the equivalent page is absent.
+ *
+ * @param {HTMLAnchorElement} link The language link to validate.
+ * @param {"en" | "zh_CN"} language The target language.
+ * @returns {void}
+ */
+function fallbackMissingLanguagePage(link, language) {
+  window
+    .fetch(link.href, { method: "HEAD" })
+    .then(function (response) {
+      if (!response.ok) {
+        link.href = buildLanguageHomeUrl(language);
+      }
+    })
+    .catch(function () {
+      link.href = buildLanguageHomeUrl(language);
+    });
+}
+
+/**
+ * Add a compact language switcher to the docs header.
+ *
+ * @returns {void}
+ */
+function addLanguageSwitcher() {
+  if (document.querySelector(".lmcache-language-switcher")) {
+    return;
+  }
+
+  var switcher = document.createElement("div");
+  var chineseLink = document.createElement("a");
+  var divider = document.createElement("span");
+  var englishLink = document.createElement("a");
+  var isChinesePage = isChineseDocsPage();
+
+  switcher.className = "lmcache-language-switcher";
+  switcher.setAttribute("aria-label", "Documentation language");
+
+  chineseLink.href = buildLanguageUrl("zh_CN");
+  chineseLink.textContent = "中文";
+  chineseLink.setAttribute("aria-label", "Switch to Chinese");
+
+  divider.className = "lmcache-language-switcher__divider";
+  divider.textContent = "|";
+
+  englishLink.href = buildLanguageUrl("en");
+  englishLink.textContent = "Eng";
+  englishLink.setAttribute("aria-label", "Switch to English");
+
+  if (isChinesePage) {
+    chineseLink.setAttribute("aria-current", "page");
+  } else {
+    englishLink.setAttribute("aria-current", "page");
+  }
+
+  switcher.appendChild(chineseLink);
+  switcher.appendChild(divider);
+  switcher.appendChild(englishLink);
+
+  // Place the switcher in the top nav bar with the other icons.
+  // If the nav bar isn't there, show it as a floating button instead.
+  var navbar = findDocsNavbar();
+  if (navbar) {
+    navbar.appendChild(switcher);
+  } else {
+    switcher.classList.add("lmcache-language-switcher--fallback");
+    document.body.appendChild(switcher);
+  }
+
+  fallbackMissingLanguagePage(chineseLink, "zh_CN");
+  fallbackMissingLanguagePage(englishLink, "en");
+}
+
+/**
+ * Locate the top nav bar that holds the GitHub / profile / theme-toggle
+ * icons. Prefers the structural `header nav` selector; falls back to
+ * the GitHub link's parent if the theme markup differs.
+ *
+ * @returns {HTMLElement | null} The nav bar element, or null if not found.
+ */
+function findDocsNavbar() {
+  var navbar = document.querySelector("header nav");
+  if (navbar) {
+    return navbar;
+  }
+  var githubLink = document.querySelector('a[title="Visit GitHub"]');
+  return githubLink ? githubLink.parentElement : null;
+}
+
+/**
+ * Initialize docs widgets after the DOM is ready.
+ *
+ * @returns {void}
+ */
+function initializeDocsWidgets() {
+  addLanguageSwitcher();
+  addRunLlmWidget();
+}
+
+document.addEventListener("DOMContentLoaded", initializeDocsWidgets);
+
+/**
+ * Default-expand the top-level sidebar sections so visitors can skim the full
+ * information architecture at a glance. Sections remain collapsible -- this
+ * only changes the initial Alpine ``expanded`` state of each ``.toctree-l1``
+ * (the theme starts them collapsed unless they are the current page).
+ *
+ * @returns {void}
+ */
+// Top-level sections that should start collapsed (secondary / reference /
+// deprecated material) rather than expanded-by-default.
+const COLLAPSED_BY_DEFAULT = [
+  "legacy/index",
+  "developer_guide/index",
+  "non_kv_cache/index",
+  "community/index",
+  "kv_cache_optimizations/index",
+];
+
+let didInitialNavExpand = false;
+
+function expandTopLevelNavSections() {
+  // Run the default expansion exactly once. Without this guard it fires on
+  // both `alpine:initialized` and the DOMContentLoaded fallback, and if the
+  // user collapses a section between the two calls the second one re-opens it.
+  if (didInitialNavExpand) {
+    return;
+  }
+  // Need Alpine ready to set the reactive `expanded` state; bail without
+  // marking done so a later trigger can retry.
+  if (!(window.Alpine && window.Alpine.$data)) {
+    return;
+  }
+  let expandedAny = false;
+  document.querySelectorAll("nav .toctree-l1").forEach((li) => {
+    const link = li.querySelector(":scope > a");
+    const href = link ? link.getAttribute("href") || "" : "";
+    if (COLLAPSED_BY_DEFAULT.some((p) => href.includes(p))) {
+      return;
+    }
+    try {
+      const data = window.Alpine.$data(li);
+      if (data && "expanded" in data) {
+        data.expanded = true;
+        expandedAny = true;
+      }
+    } catch (e) {
+      /* nav item not yet managed by Alpine */
+    }
+  });
+  if (expandedAny) {
+    didInitialNavExpand = true;
+  }
+}
+
+// Run both on Alpine init and as a fallback, to cover either load ordering.
+document.addEventListener("alpine:initialized", expandTopLevelNavSections);
+document.addEventListener("DOMContentLoaded", () =>
+  setTimeout(expandTopLevelNavSections, 0),
+);
+
+/**
+ * Preserve the left sidebar's scroll position across page navigations. The
+ * sidebar (``#left-sidebar``) is an independently scrollable container, so a
+ * normal page load re-renders it at the top -- making the nav "jump" every
+ * time you click a link. We stash its scrollTop in sessionStorage before
+ * leaving and restore it on the next page.
+ *
+ * @returns {void}
+ */
+const SIDEBAR_SCROLL_KEY = "lmcacheSidebarScroll";
+
+function saveSidebarScroll() {
+  const sidebar = document.getElementById("left-sidebar");
+  if (sidebar) {
+    sessionStorage.setItem(SIDEBAR_SCROLL_KEY, String(sidebar.scrollTop));
+  }
+}
+
+function restoreSidebarScroll() {
+  const sidebar = document.getElementById("left-sidebar");
+  const saved = sessionStorage.getItem(SIDEBAR_SCROLL_KEY);
+  if (!sidebar || saved === null) {
+    return;
+  }
+  const target = parseInt(saved, 10) || 0;
+  // Sections expand asynchronously (Alpine reveals the child <ul> via x-show),
+  // so the sidebar starts short and scrollTop gets clamped near the top.
+  // Re-apply the target across several animation frames until it sticks.
+  let tries = 0;
+  const apply = () => {
+    sidebar.scrollTop = target;
+    tries += 1;
+    if (tries < 20 && Math.abs(sidebar.scrollTop - target) > 1) {
+      requestAnimationFrame(apply);
+    }
+  };
+  requestAnimationFrame(apply);
+}
+
+// Save the position whenever a sidebar link is clicked (captures it exactly
+// at click time) and as a fallback right before the page is hidden.
+document.addEventListener("DOMContentLoaded", () => {
+  const sidebar = document.getElementById("left-sidebar");
+  if (sidebar) {
+    sidebar.addEventListener("click", (e) => {
+      if (e.target.closest("a")) {
+        saveSidebarScroll();
+      }
+    });
+  }
+});
+window.addEventListener("pagehide", saveSidebarScroll);
+// Restore on initial load and on bfcache restore (pageshow).
+document.addEventListener("DOMContentLoaded", restoreSidebarScroll);
+window.addEventListener("pageshow", restoreSidebarScroll);
diff --git a/docs/source/_static/full_layerwise_diagram.svg b/docs/source/_static/full_layerwise_diagram.svg
new file mode 100644
index 0000000..90c9973
--- /dev/null
+++ b/docs/source/_static/full_layerwise_diagram.svg
@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="0 0 1600 1400"
+     xmlns="http://www.w3.org/2000/svg"
+     preserveAspectRatio="xMinYMin meet">
+
+  <!-- GPU Model Runner Box -->
+  <rect x="50" y="50" width="450" height="650" fill="#e3f2fd" stroke="#1976d2" stroke-width="3" rx="10"/>
+  <text x="275" y="35" text-anchor="middle" font-family="Arial, sans-serif" font-size="18" font-weight="bold" fill="#1976d2">GPU Model Runner</text>
+  
+  <!-- KV Cache Layers (Left Side) -->
+  <g id="kv-cache-layers">
+    
+    <!-- Layer 1 KV Cache -->
+    <rect x="20" y="110" width="90" height="35" fill="#ffe0b2" stroke="#f57c00" stroke-width="2" rx="5"/>
+    <text x="65" y="130" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#e65100">KV Cache 1</text>
+    
+    <!-- Layer 2 KV Cache -->
+    <rect x="20" y="210" width="90" height="35" fill="#ffe0b2" stroke="#f57c00" stroke-width="2" rx="5"/>
+    <text x="65" y="230" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#e65100">KV Cache 2</text>
+    
+    <!-- Dots for more layers -->
+    <circle cx="65" cy="280" r="4" fill="#666"/>
+    <circle cx="65" cy="295" r="4" fill="#666"/>
+    <circle cx="65" cy="310" r="4" fill="#666"/>
+    
+    <!-- Layer N KV Cache -->
+    <rect x="20" y="340" width="90" height="35" fill="#ffe0b2" stroke="#f57c00" stroke-width="2" rx="5"/>
+    <text x="65" y="360" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" fill="#e65100">KV Cache N</text>
+  </g>
+  
+  <!-- Numbered Operations in GPU Model Runner -->
+  
+  <!-- 1. start_load_kv() -->
+  <rect x="130" y="80" width="350" height="45" fill="#ffecb3" stroke="#f57f17" stroke-width="2" rx="5"/>
+  <text x="305" y="107" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#f57f17">start_load_kv()</text>
+  <circle cx="145" cy="90" r="12" fill="#ff9800" stroke="#ef6c00" stroke-width="2"/>
+  <text x="145" y="95" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">1</text>
+  
+  <!-- Layer 1 Processing -->
+  <g id="layer1">
+    <rect x="140" y="140" width="340" height="85" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+    
+    <!-- 2. wait_for_layer_load() -->
+    <rect x="150" y="150" width="100" height="30" fill="#e1bee7" stroke="#8e24aa" stroke-width="1" rx="3"/>
+    <text x="200" y="168" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4a148c">wait_for_layer_load()</text>
+    <circle cx="165" cy="140" r="12" fill="#9c27b0" stroke="#6a1b9a" stroke-width="2"/>
+    <text x="165" y="145" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">2</text>
+    
+    <!-- Attention 1 -->
+    <rect x="265" y="150" width="70" height="30" fill="#fff3e0" stroke="#ef6c00" stroke-width="1" rx="3"/>
+    <text x="300" y="168" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#bf360c">Attention 1</text>
+    
+    <!-- 3. save_kv_layer() -->
+    <rect x="350" y="150" width="120" height="30" fill="#e8f5e8" stroke="#388e3c" stroke-width="1" rx="3"/>
+    <text x="410" y="168" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#1b5e20">save_kv_layer()</text>
+    <circle cx="365" cy="140" r="12" fill="#388e3c" stroke="#2e7d32" stroke-width="2"/>
+    <text x="365" y="145" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">3</text>
+    
+    <!-- Arrows -->
+    <path d="M 250 165 L 265 165" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+    <path d="M 335 165 L 350 165" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+  </g>
+  
+  <!-- Layer 2 Processing -->
+  <g id="layer2">
+    <rect x="140" y="240" width="340" height="85" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+    
+    <rect x="150" y="250" width="100" height="30" fill="#e1bee7" stroke="#8e24aa" stroke-width="1" rx="3"/>
+    <text x="200" y="268" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4a148c">wait_for_layer_load()</text>
+    <circle cx="165" cy="240" r="12" fill="#9c27b0" stroke="#6a1b9a" stroke-width="2"/>
+    <text x="165" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">2</text>
+    
+    <rect x="265" y="250" width="70" height="30" fill="#fff3e0" stroke="#ef6c00" stroke-width="1" rx="3"/>
+    <text x="300" y="268" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#bf360c">Attention 2</text>
+    
+    <rect x="350" y="250" width="120" height="30" fill="#e8f5e8" stroke="#388e3c" stroke-width="1" rx="3"/>
+    <text x="410" y="268" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#1b5e20">save_kv_layer()</text>
+    <circle cx="365" cy="240" r="12" fill="#388e3c" stroke="#2e7d32" stroke-width="2"/>
+    <text x="365" y="245" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">3</text>
+    
+    <path d="M 250 265 L 265 265" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+    <path d="M 335 265 L 350 265" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+  </g>
+  
+  <!-- Dots for more layers -->
+  <circle cx="305" cy="350" r="4" fill="#666"/>
+  <circle cx="305" cy="365" r="4" fill="#666"/>
+  <circle cx="305" cy="380" r="4" fill="#666"/>
+  
+  <!-- Layer N Processing -->
+  <g id="layerN">
+    <rect x="140" y="400" width="340" height="85" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+    
+    <rect x="150" y="410" width="100" height="30" fill="#e1bee7" stroke="#8e24aa" stroke-width="1" rx="3"/>
+    <text x="200" y="428" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#4a148c">wait_for_layer_load()</text>
+    <circle cx="165" cy="400" r="12" fill="#9c27b0" stroke="#6a1b9a" stroke-width="2"/>
+    <text x="165" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">2</text>
+    
+    <rect x="265" y="410" width="70" height="30" fill="#fff3e0" stroke="#ef6c00" stroke-width="1" rx="3"/>
+    <text x="300" y="428" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#bf360c">Attention N</text>
+    
+    <rect x="350" y="410" width="120" height="30" fill="#e8f5e8" stroke="#388e3c" stroke-width="1" rx="3"/>
+    <text x="410" y="428" text-anchor="middle" font-family="Arial, sans-serif" font-size="11" fill="#1b5e20">save_kv_layer()</text>
+    <circle cx="365" cy="400" r="12" fill="#388e3c" stroke="#2e7d32" stroke-width="2"/>
+    <text x="365" y="405" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">3</text>
+    
+    <path d="M 250 425 L 265 425" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+    <path d="M 335 425 L 350 425" stroke="#666" stroke-width="2" marker-end="url(#arrowhead)"/>
+  </g>
+  
+  <!-- 4. wait_for_save() -->
+  <rect x="170" y="520" width="280" height="45" fill="#ffcdd2" stroke="#c62828" stroke-width="2" rx="5"/>
+  <text x="310" y="547" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#b71c1c">wait_for_save()</text>
+  <circle cx="185" cy="530" r="12" fill="#c62828" stroke="#b71c1c" stroke-width="2"/>
+  <text x="185" y="535" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">4</text>
+  
+  <!-- MAIN CACHE ENGINE -->
+  <rect x="520" y="100" width="600" height="600" fill="#e0f2f1" stroke="#00695c" stroke-width="3" rx="10"/>
+  <text x="820" y="125" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="bold" fill="#004d40">CacheEngine</text>
+  
+  <!-- Multi-layer Cache Engine Key (note inside CacheEngine) -->
+  <text x="530" y="145" font-family="Arial, sans-serif" font-size="10" fill="#6a1b9a">Note: Multi-layer Cache Engine Key uses split_layers(N)</text>
+  
+  <!-- Retrieval Generator (inside CacheEngine) -->
+  <rect x="540" y="160" width="270" height="90" fill="#e1f5fe" stroke="#0277bd" stroke-width="2" rx="5"/>
+  <text x="675" y="180" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#01579b">Retrieval Generator (N + 2 yields)</text>
+  <text x="675" y="195" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#01579b">retrieve_layer() called by start_load_kv()</text>
+  <text x="675" y="210" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#01579b">• Layer-by-layer memory allocation</text>
+  <text x="675" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#01579b">• Contains GPU Load Generator (batched_to_gpu)</text>
+  <text x="675" y="240" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#01579b">• Calls StorageManager.layerwise_batched_get()</text>
+  
+  <!-- Storage Generator (inside CacheEngine) -->
+  <rect x="830" y="160" width="270" height="90" fill="#fff3e0" stroke="#ef6c00" stroke-width="2" rx="5"/>
+  <text x="965" y="180" text-anchor="middle" font-family="Arial, sans-serif" font-size="14" font-weight="bold" fill="#bf360c">Storage Generator (N + 1 yields)</text>
+  <text x="965" y="195" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#bf360c">store_layer() - FIRST save_kv_layer() only</text>
+  <text x="965" y="210" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#bf360c">• Upfront CPU memory allocation (all layers)</text>
+  <text x="965" y="225" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#bf360c">• Contains GPU Store Generator (batched_from_gpu)</text>
+  <text x="965" y="240" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#bf360c">• Calls StorageManager.batched_put()</text>
+  
+  <!-- StorageManager (sub-component inside CacheEngine) -->
+  <rect x="540" y="270" width="250" height="120" fill="#fce4ec" stroke="#c2185b" stroke-width="2" rx="5"/>
+  <text x="665" y="290" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#880e4f">StorageManager</text>
+  
+  <!-- StorageManager Methods -->
+  <rect x="550" y="305" width="230" height="25" fill="#f8bbd9" stroke="#ad1457" stroke-width="1" rx="3"/>
+  <text x="665" y="320" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#4a148c">layerwise_batched_get() [async → .result()]</text>
+  
+  <rect x="550" y="340" width="230" height="25" fill="#f8bbd9" stroke="#ad1457" stroke-width="1" rx="3"/>
+  <text x="665" y="355" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#4a148c">batched_put(memory_objects)</text>
+  
+  <!-- LayerwiseGPUConnector (sub-component inside CacheEngine) -->
+  <rect x="810" y="270" width="290" height="200" fill="#fff9c4" stroke="#f9a825" stroke-width="2" rx="5"/>
+  <text x="955" y="290" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" font-weight="bold" fill="#f57f17">LayerwiseGPUConnector</text>
+  <text x="955" y="305" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#ef6c00">VLLMPagedMemLayerwiseGPUConnector</text>
+  
+  <!-- Batch Request Management -->
+  <rect x="820" y="315" width="270" height="30" fill="#fff8e1" stroke="#ff8f00" stroke-width="1" rx="3"/>
+  <text x="955" y="330" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#e65100">Batch: Req 1 (First) | Req 2 | ... | Req N (Last)</text>
+  
+  <!-- GPU Buffers -->
+  <rect x="820" y="355" width="120" height="50" fill="#ffecb3" stroke="#ffa000" stroke-width="1" rx="3"/>
+  <text x="880" y="375" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#ff6f00">Load GPU Buffer</text>
+  <text x="880" y="390" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#ff6f00">(use_gpu: true)</text>
+  
+  <rect x="960" y="355" width="120" height="50" fill="#ffecb3" stroke="#ffa000" stroke-width="1" rx="3"/>
+  <text x="1020" y="375" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#ff6f00">Store GPU Buffer</text>
+  <text x="1020" y="390" text-anchor="middle" font-family="Arial, sans-serif" font-size="9" fill="#ff6f00">(use_gpu: true)</text>
+  
+  <!-- CUDA Streams -->
+  <rect x="820" y="415" width="270" height="45" fill="#f3e5f5" stroke="#7b1fa2" stroke-width="2" rx="5"/>
+  <text x="955" y="435" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#4a148c">CUDA Streams</text>
+  <text x="955" y="450" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#4a148c">load_stream | store_stream | current_stream</text>
+  
+  <!-- Synchronization details -->
+  <rect x="540" y="480" width="560" height="60" fill="#ffcdd2" stroke="#c62828" stroke-width="2" rx="5"/>
+  <text x="820" y="500" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#b71c1c">Synchronization Details</text>
+  <text x="820" y="515" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#b71c1c">First Req: store_stream.wait_stream(current_stream) + sync prevents buffer override</text>
+  <text x="820" y="530" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#b71c1c">Last Req: current_stream.wait_stream(load_stream) prevents forward pass until KV loaded</text>
+  
+  <!-- Operation Boxes for Numbered Steps -->
+  
+  <!-- Operation 1 Box -->
+  <rect x="20" y="750" width="250" height="80" fill="#ffcc80" stroke="#ef6c00" stroke-width="2" rx="5"/>
+  <circle cx="35" cy="765" r="12" fill="#ff9800" stroke="#ef6c00" stroke-width="2"/>
+  <text x="35" y="770" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">1</text>
+  <text x="140" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#01579b">start_load_kv() Operations</text>
+  <text x="140" y="780" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#01579b">• Initialize Retrieval Generator</text>
+  <text x="140" y="795" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#01579b">• Call retrieve_layer() - 1st next() (setup)</text>
+  <text x="140" y="810" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#01579b">• Call retrieve_layer() - 2nd next() (layer 0)</text>
+  
+  <!-- Operation 2 Box -->
+  <rect x="290" y="750" width="250" height="80" fill="#d1c4e9" stroke="#6a1b9a" stroke-width="2" rx="5"/>
+  <circle cx="305" cy="765" r="12" fill="#9c27b0" stroke="#6a1b9a" stroke-width="2"/>
+  <text x="305" y="770" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">2</text>
+  <text x="415" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#0d47a1">wait_for_layer_load() Operations</text>
+  <text x="415" y="780" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#0d47a1">• Call retrieve_layer() - next() (layer i)</text>
+  <text x="415" y="795" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#0d47a1">• StorageManager.layerwise_batched_get()</text>
+  <text x="415" y="810" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#0d47a1">• GPU Load Gen: batched_to_gpu() next()</text>
+  
+  <!-- Operation 3 Box -->
+  <rect x="560" y="750" width="250" height="80" fill="#e8f5e8" stroke="#388e3c" stroke-width="2" rx="5"/>
+  <circle cx="575" cy="765" r="12" fill="#388e3c" stroke="#2e7d32" stroke-width="2"/>
+  <text x="575" y="770" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">3</text>
+  <text x="685" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#2e7d32">save_kv_layer() Operations</text>
+  <text x="685" y="780" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#2e7d32">• FIRST call: Create Storage Generator</text>
+  <text x="685" y="795" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#2e7d32">• Call store_layer() - next() (layer i)</text>
+  <text x="685" y="810" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#2e7d32">• GPU Store Gen: batched_from_gpu() next()</text>
+  
+  <!-- Operation 4 Box -->
+  <rect x="830" y="750" width="250" height="80" fill="#ffcdd2" stroke="#c62828" stroke-width="2" rx="5"/>
+  <circle cx="845" cy="765" r="12" fill="#c62828" stroke="#b71c1c" stroke-width="2"/>
+  <text x="845" y="770" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="white">4</text>
+  <text x="955" y="765" text-anchor="middle" font-family="Arial, sans-serif" font-size="12" font-weight="bold" fill="#b71c1c">wait_for_save() Operations</text>
+  <text x="955" y="780" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#b71c1c">• Call store_layer() - final next()</text>
+  <text x="955" y="795" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#b71c1c">• StorageManager.batched_put()</text>
+  <text x="955" y="810" text-anchor="middle" font-family="Arial, sans-serif" font-size="10" fill="#b71c1c">• GPU Store Gen: final next() + cleanup</text>
+  <!-- Arrowhead definitions -->
+  <defs>
+    <!-- Standard arrowhead -->
+    <marker id="arrowhead" markerWidth="10" markerHeight="7" 
+            refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#666"/>
+    </marker>
+    <!-- Optional start arrowhead -->
+    <marker id="arrowhead-start" markerWidth="10" markerHeight="7" 
+            refX="1" refY="3.5" orient="auto">
+      <polygon points="10 0, 0 3.5, 10 7" fill="#666"/>
+    </marker>
+  </defs>
+
+  <!-- Rainbow trunk from all KV Caches up and over -->
+  <path d="M 110 127 
+           L 110 40 
+           L 1220 40 
+           L 1220 375"
+        stroke="#f57c00" stroke-width="2" stroke-dasharray="6,3"
+        fill="none" marker-start="url(#arrowhead-start)"/>
+  <path d="M 110 227 
+           L 110 40"
+        stroke="#f57c00" stroke-width="2" stroke-dasharray="6,3"
+        fill="none" marker-start="url(#arrowhead-start)"/>
+  <path d="M 110 357 
+           L 110 40"
+        stroke="#f57c00" stroke-width="2" stroke-dasharray="6,3"
+        fill="none" marker-start="url(#arrowhead-start)"/>
+
+  <!-- Fork into Load GPU Buffer -->
+  <path d="M 1220 375 L 940 375"
+        stroke="#f57c00" stroke-width="2" stroke-dasharray="6,3"
+        fill="none" marker-end="url(#arrowhead)"/>
+
+  <!-- Fork into Store GPU Buffer -->
+  <path d="M 1220 375 L 1080 375"
+        stroke="#f57c00" stroke-width="2" stroke-dasharray="6,3"
+        fill="none" marker-end="url(#arrowhead)"/>
+</svg> 
\ No newline at end of file
diff --git a/docs/source/_static/kv_cache_calculator.html b/docs/source/_static/kv_cache_calculator.html
new file mode 100644
index 0000000..f16f076
--- /dev/null
+++ b/docs/source/_static/kv_cache_calculator.html
@@ -0,0 +1,874 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>KV Cache Size Calculator</title>
+    <style>
+        * {
+            box-sizing: border-box;
+        }
+        
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            margin: 0;
+            padding: 0;
+            background: transparent;
+            overflow: hidden;
+        }
+        
+        .calculator-container {
+            max-width: 100%;
+            margin: 0;
+            background: transparent;
+            padding: 0;
+        }
+        
+        h1 {
+            display: none;
+        }
+        
+        .form-group {
+            margin-bottom: 20px;
+        }
+        
+        label {
+            display: block;
+            font-weight: 600;
+            margin-bottom: 8px;
+            color: #333;
+            font-size: 14px;
+        }
+        
+        select, input {
+            width: 100%;
+            padding: 12px;
+            font-size: 15px;
+            border: 2px solid #e0e0e0;
+            border-radius: 8px;
+            background: white;
+            transition: border-color 0.2s;
+        }
+        
+        select:focus, input:focus {
+            outline: none;
+            border-color: #3898ec;
+        }
+        
+        button {
+            width: 100%;
+            padding: 14px;
+            font-size: 16px;
+            font-weight: 600;
+            background: #3898ec;
+            color: white;
+            border: none;
+            border-radius: 8px;
+            cursor: pointer;
+            transition: background 0.2s;
+        }
+        
+        button:hover {
+            background: #2578cc;
+        }
+        
+        button:active {
+            transform: scale(0.98);
+        }
+        
+        .result {
+            margin-top: 24px;
+            padding: 20px;
+            background: #f0f9ff;
+            border-left: 4px solid #3898ec;
+            border-radius: 8px;
+            display: none;
+        }
+        
+        .result.show {
+            display: block;
+        }
+        
+        .result-value {
+            font-size: 32px;
+            font-weight: 700;
+            color: #1a1a1a;
+            margin: 8px 0;
+        }
+        
+        .result-label {
+            font-size: 14px;
+            color: #666;
+            margin-bottom: 4px;
+        }
+        
+        .details {
+            margin-top: 16px;
+            padding-top: 16px;
+            border-top: 1px solid #d0e8f7;
+            font-size: 13px;
+            color: #555;
+            line-height: 1.6;
+        }
+        
+        .details strong {
+            color: #333;
+        }
+        
+        .error {
+            background: #fee;
+            border-left-color: #f44;
+        }
+        
+        .loading {
+            text-align: center;
+            color: #666;
+            padding: 20px;
+            font-size: 14px;
+        }
+        
+    </style>
+</head>
+<body>
+    <div class="calculator-container">
+        <h1>KV Cache Size Calculator</h1>
+        
+        <div class="loading" id="loading">Loading model configurations...</div>
+        
+        <div id="calculator-form" style="display: none;">
+            <div class="form-group">
+                <label for="model">Model:</label>
+                <select id="model" onchange="updatePrecisionVisibility('')">
+                    <!-- Options will be populated dynamically -->
+                </select>
+            </div>
+
+            <div class="form-group">
+                <label for="dtype">Data Type:</label>
+                <select id="dtype">
+                    <option value="float16">float16 (FP16)</option>
+                    <option value="bfloat16" selected>bfloat16 (BF16)</option>
+                    <option value="float32">float32 (FP32)</option>
+                    <option value="int8">int8 (INT8)</option>
+                </select>
+            </div>
+
+            <div class="form-group" id="precision-group" style="display: none;">
+                <label for="precision-mode">DeepSeek V4 KV Precision (bytes / dimension):</label>
+                <select id="precision-mode" onchange="togglePrecisionInputs('')">
+                    <option value="default" selected>Paper default — FP8 NoPE / BF16 RoPE / FP4 indexer</option>
+                    <option value="custom">Custom…</option>
+                </select>
+                <div id="precision-custom" style="display: none; margin-top: 10px;">
+                    <label for="nope-bytes">NoPE bytes/dim:</label>
+                    <input type="number" id="nope-bytes" min="0" step="0.1" value="1">
+                    <label for="rope-bytes">RoPE bytes/dim:</label>
+                    <input type="number" id="rope-bytes" min="0" step="0.1" value="2">
+                    <label for="indexer-bytes">Indexer bytes/dim:</label>
+                    <input type="number" id="indexer-bytes" min="0" step="0.1" value="0.5">
+                </div>
+            </div>
+
+            <div class="form-group">
+                <label for="tokens">Number of Tokens:</label>
+                <input type="number" id="tokens" placeholder="e.g., 1000" min="1" value="1000">
+            </div>
+            
+            <button onclick="calculateKVCache()">Calculate KV Cache Size</button>
+            
+            <div id="result" class="result"></div>
+            
+            <hr style="margin: 40px 0; border: none; border-top: 1px solid #e0e0e0;">
+            
+            <h2 style="font-size: 18px; margin-bottom: 20px; color: #1a1a1a;">Reverse Calculator: Find Maximum Tokens</h2>
+            
+            <div class="form-group">
+                <label for="model-reverse">Model:</label>
+                <select id="model-reverse" onchange="updatePrecisionVisibility('-reverse')">
+                    <!-- Options will be populated dynamically -->
+                </select>
+            </div>
+
+            <div class="form-group">
+                <label for="dtype-reverse">Data Type:</label>
+                <select id="dtype-reverse">
+                    <option value="float16">float16 (FP16)</option>
+                    <option value="bfloat16" selected>bfloat16 (BF16)</option>
+                    <option value="float32">float32 (FP32)</option>
+                    <option value="int8">int8 (INT8)</option>
+                </select>
+            </div>
+
+            <div class="form-group" id="precision-group-reverse" style="display: none;">
+                <label for="precision-mode-reverse">DeepSeek V4 KV Precision (bytes / dimension):</label>
+                <select id="precision-mode-reverse" onchange="togglePrecisionInputs('-reverse')">
+                    <option value="default" selected>Paper default — FP8 NoPE / BF16 RoPE / FP4 indexer</option>
+                    <option value="custom">Custom…</option>
+                </select>
+                <div id="precision-custom-reverse" style="display: none; margin-top: 10px;">
+                    <label for="nope-bytes-reverse">NoPE bytes/dim:</label>
+                    <input type="number" id="nope-bytes-reverse" min="0" step="0.1" value="1">
+                    <label for="rope-bytes-reverse">RoPE bytes/dim:</label>
+                    <input type="number" id="rope-bytes-reverse" min="0" step="0.1" value="2">
+                    <label for="indexer-bytes-reverse">Indexer bytes/dim:</label>
+                    <input type="number" id="indexer-bytes-reverse" min="0" step="0.1" value="0.5">
+                </div>
+            </div>
+
+            <div class="form-group">
+                <label for="gpu-ram">GPU RAM Size (GB):</label>
+                <input type="number" id="gpu-ram" placeholder="e.g., 20" min="0.1" step="0.1" value="20">
+            </div>
+            
+            <button onclick="calculateMaxTokens()">Calculate Maximum Tokens</button>
+            
+            <div id="result-reverse" class="result"></div>
+        </div>
+    </div>
+    
+    <script>
+        let modelConfigs = {};
+        
+        // Load model configurations
+        async function loadModelConfigs() {
+            const urls = [
+                'modelconfig.json',
+                '_static/modelconfig.json',
+                '../_static/modelconfig.json',
+                'https://raw.githubusercontent.com/LMCache/LMCache/refs/heads/dev/examples/kv_cache_calculator/modelconfig.json'
+            ];
+            
+            for (const url of urls) {
+                try {
+                    const response = await fetch(url);
+                    if (response.ok) {
+                        modelConfigs = await response.json();
+                        populateModelDropdown();
+                        document.getElementById('loading').style.display = 'none';
+                        document.getElementById('calculator-form').style.display = 'block';
+                        return;
+                    }
+                } catch (error) {
+                    console.log('Failed to load from:', url);
+                }
+            }
+            
+            document.getElementById('loading').innerHTML = 
+                '<div class="error">Failed to load model configurations. Please check your connection.</div>';
+        }
+        
+        // Populate model dropdown
+        function populateModelDropdown() {
+            const select = document.getElementById('model');
+            const selectReverse = document.getElementById('model-reverse');
+            select.innerHTML = '';
+            selectReverse.innerHTML = '';
+            
+            const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+            const sortedModels = Object.keys(modelConfigs).sort(collator.compare);
+            const defaultModel = 'Qwen/Qwen3-8B';
+            
+            for (const modelName of sortedModels) {
+                const option = document.createElement('option');
+                option.value = modelName;
+                option.textContent = modelName;
+                if (modelName === defaultModel) {
+                    option.selected = true;
+                }
+                select.appendChild(option);
+                
+                const optionReverse = document.createElement('option');
+                optionReverse.value = modelName;
+                optionReverse.textContent = modelName;
+                if (modelName === defaultModel) {
+                    optionReverse.selected = true;
+                }
+                selectReverse.appendChild(optionReverse);
+            }
+
+            updatePrecisionVisibility('');
+            updatePrecisionVisibility('-reverse');
+        }
+
+        // Show the V4 precision controls only for DSA (compress_ratios) models, and
+        // seed the custom inputs with the selected model's paper-default byte widths.
+        function updatePrecisionVisibility(suffix) {
+            const model = document.getElementById('model' + suffix).value;
+            const config = modelConfigs[model] || {};
+            const isDSA = Array.isArray(config.compress_ratios)
+                && Number.isFinite(config.head_dim);
+            document.getElementById('precision-group' + suffix).style.display =
+                isDSA ? 'block' : 'none';
+            if (isDSA) {
+                document.getElementById('nope-bytes' + suffix).value =
+                    Number.isFinite(config.nope_bytes) ? config.nope_bytes : 1;
+                document.getElementById('rope-bytes' + suffix).value =
+                    Number.isFinite(config.rope_bytes) ? config.rope_bytes : 2;
+                document.getElementById('indexer-bytes' + suffix).value =
+                    Number.isFinite(config.indexer_bytes) ? config.indexer_bytes : 0.5;
+            }
+        }
+
+        // Reveal the custom byte inputs only when "Custom" is selected.
+        function togglePrecisionInputs(suffix) {
+            const mode = document.getElementById('precision-mode' + suffix).value;
+            document.getElementById('precision-custom' + suffix).style.display =
+                mode === 'custom' ? 'block' : 'none';
+        }
+
+        // Resolve the per-dimension byte widths for a DSA model: paper defaults from
+        // the config (nope/rope/indexer_bytes), overridden by the custom inputs when
+        // the precision mode is "custom". Returns bytes/dim for each component + mode.
+        function getDSAPrecision(suffix, config) {
+            const def = {
+                nope: Number.isFinite(config.nope_bytes) ? config.nope_bytes : 1,
+                rope: Number.isFinite(config.rope_bytes) ? config.rope_bytes : 2,
+                indexer: Number.isFinite(config.indexer_bytes) ? config.indexer_bytes : 0.5,
+                mode: 'default',
+            };
+            if (document.getElementById('precision-mode' + suffix).value !== 'custom') {
+                return def;
+            }
+            const nope = parseFloat(document.getElementById('nope-bytes' + suffix).value);
+            const rope = parseFloat(document.getElementById('rope-bytes' + suffix).value);
+            const indexer = parseFloat(document.getElementById('indexer-bytes' + suffix).value);
+            return {
+                nope: Number.isFinite(nope) ? nope : def.nope,
+                rope: Number.isFinite(rope) ? rope : def.rope,
+                indexer: Number.isFinite(indexer) ? indexer : def.indexer,
+                mode: 'custom',
+            };
+        }
+
+        // Calculate KV cache size
+        function calculateKVCache() {
+            const model = document.getElementById('model').value;
+            const tokens = parseInt(document.getElementById('tokens').value);
+            const dtype = document.getElementById('dtype').value;
+            const resultDiv = document.getElementById('result');
+            
+            // Validation
+            if (isNaN(tokens) || tokens <= 0) {
+                resultDiv.className = 'result show error';
+                resultDiv.innerHTML = '<div class="result-label">Error</div><div>Please enter a valid number of tokens (greater than 0).</div>';
+                return;
+            }
+            
+            const config = modelConfigs[model];
+            if (!config) {
+                resultDiv.className = 'result show error';
+                resultDiv.innerHTML = '<div class="result-label">Error</div><div>Model configuration not found.</div>';
+                return;
+            }
+            
+            // Get dtype size
+            const dtypeSizes = {
+                'float32': 4,
+                'float16': 2,
+                'bfloat16': 2,
+                'int8': 1
+            };
+            const dtypeSize = dtypeSizes[dtype];
+            
+            // Calculate based on model architecture
+            // DeepSeek V4 sparse attention: per-layer compression schedule.
+            const isDSA = Array.isArray(config.compress_ratios)
+                && Number.isFinite(config.head_dim);
+            // Multi-head Latent Attention (DeepSeek V3/R1, GLM-5.x DSA): a single
+            // latent KV vector per layer per token. Feature-gated on kv_lora_rank
+            // rather than the model name, so non-DeepSeek MLA models are caught too.
+            const isMLA = Number.isFinite(config.kv_lora_rank)
+                && Number.isFinite(config.qk_rope_head_dim);
+            // Interleaved sliding-window / full attention (Gemma 2/3/4): the sliding
+            // layers cap their KV cache at the window, only the full layers grow.
+            const isHybridSWA = Number.isFinite(config.full_attention_layers)
+                && Number.isFinite(config.sliding_attention_layers)
+                && Number.isFinite(config.sliding_window)
+                && Number.isFinite(config.num_key_value_heads)
+                && Number.isFinite(config.head_dim);
+            // Linear/full hybrid (Qwen3-Next / Qwen3.5): Gated DeltaNet layers keep a
+            // fixed-size recurrent state (no per-token KV); only full layers grow.
+            const isHybridLinear = Number.isFinite(config.full_attention_layers)
+                && Number.isFinite(config.linear_attention_layers)
+                && Number.isFinite(config.num_key_value_heads)
+                && Number.isFinite(config.head_dim);
+            const hasHeadDim = Number.isFinite(config.head_dim)
+                && Number.isFinite(config.num_key_value_heads);
+
+            let totalElements;
+            let totalBytes;
+            let sizeGB;
+            let details = '';
+
+            if (isDSA) {
+                // DeepSeek V4 hybrid attention: Compressed Sparse Attention (CSA)
+                // + Heavily Compressed Attention (HCA). This is NOT MLA — V4 has no
+                // kv_lora_rank; head_dim (512) is the width of one shared compressed
+                // KV entry (per the paper's CSA/HCA shared-KV MQA). Each layer
+                // compresses every `r` tokens into one entry, so the amortized
+                // per-token KV cost is head_dim × Σ(1/r) over layers with r > 0.
+                // (r == 0 layers are pure sliding-window; no compressed entries.)
+                //
+                // This branch MUST come before the head_dim/GQA branch below:
+                // V4 configs carry num_key_value_heads == 1 and head_dim == 512,
+                // which would otherwise (incorrectly) match the standard
+                // 2 × layers × kv_heads × head_dim formula and overestimate wildly.
+                //
+                // Lightning-indexer keys: the paper compresses them at the SAME
+                // ratio as the KV entries (K_IComp ∈ R^{(n/m)×c_I}), so the indexer
+                // key cache is index_head_dim × Σ(1/r) — NOT full-rate. It is a
+                // ~25% addition to the compressed KV term, not ~2×. (Only CSA
+                // layers run the indexer; HCA keeps dense attention, but HCA's
+                // large r contributes negligibly to Σ(1/r), so summing over all
+                // r > 0 overcounts by <1%.) Net per-token: (head_dim + c_I) × Σ(1/r).
+                //
+                // Plus a constant sliding-window floor (numLayers × sliding_window
+                // × head_dim): ~50% of the total below ~1K tokens, <3% above ~32K.
+                //
+                // V4 uses its NATIVE mixed precision (paper §2.3.4), so this branch
+                // computes bytes directly and the dtype dropdown does NOT apply. The
+                // per-dimension byte widths come from getDSAPrecision(): the model's
+                // nope_bytes / rope_bytes / indexer_bytes config defaults (the paper
+                // values below), overridable live via the "Custom" precision control.
+                //  - KV entry (head_dim dims): RoPE dims (qk_rope_head_dim) in BF16
+                //    (2 B), the rest in FP8 (1 B) -> bytes/entry = (head_dim - rope)
+                //    ·nope + rope·rope_bytes. Paper V4: (512-64)·1 + 64·2 = 576 B
+                //    ("nearly half" of the 1024 B a pure-BF16 entry would take).
+                //  - Indexer keys: FP4 (0.5 B/dim), compressed at the same ratio.
+                //  - Sliding-window entries are uncompressed KV -> same 576 B/entry.
+                // Only remaining simplification: amortized Σ(1/r), not Σ ceil(tokens/r)
+                // (<1% at long context). Absolute check: V4-Pro ≈ 4.8 GB @ 1M ctx,
+                // ~10-12% of a same-precision V3.2 estimate — matching the paper's
+                // "~10% of V3.2 KV cache". (The V4/V3.2 ratio is ~8.7× / ~12.4× for
+                // Pro/Flash; precision cancels in the ratio, so the small gap to the
+                // paper's 9.5× / 13.7× is V3.2-side modeling detail, not V4.)
+                const activeRatios = config.compress_ratios.filter(r => r > 0);
+                const compressFactor = activeRatios.reduce((sum, r) => sum + 1 / r, 0);
+                const ropeDim = Number.isFinite(config.qk_rope_head_dim) ? config.qk_rope_head_dim : 0;
+                const indexerDim = Number.isFinite(config.index_head_dim) ? config.index_head_dim : 0;
+                const prec = getDSAPrecision('', config);
+                const kvBytesPerEntry = (config.head_dim - ropeDim) * prec.nope + ropeDim * prec.rope;
+                const indexerBytesPerEntry = indexerDim * prec.indexer;
+                const bytesPerToken = (kvBytesPerEntry + indexerBytesPerEntry) * compressFactor;
+                const numLayers = config.compress_ratios.length;
+                const windowBytes = numLayers * config.sliding_window * kvBytesPerEntry;
+                totalBytes = bytesPerToken * tokens + windowBytes;
+                totalElements = totalBytes; // unused downstream; bytes are authoritative for V4
+                sizeGB = totalBytes / (1024 ** 3);
+                const precLabel = prec.mode === 'custom'
+                    ? `custom (NoPE ${prec.nope} / RoPE ${prec.rope} / indexer ${prec.indexer} B/dim)`
+                    : `paper default (NoPE ${prec.nope}=FP8 / RoPE ${prec.rope}=BF16 / indexer ${prec.indexer}=FP4); dtype selector not applied`;
+                const indexerLine = indexerDim
+                    ? `<strong>Indexer Key (CSA, compressed):</strong> ${indexerDim} × ${prec.indexer} × Σ(1/r) = ${(indexerBytesPerEntry * compressFactor).toFixed(1)} B/token<br>`
+                    : '';
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim} (RoPE ${ropeDim} @ ${prec.rope} B, NoPE ${config.head_dim - ropeDim} @ ${prec.nope} B)<br>
+                    <strong>Compressed Layers (ratio &gt; 0):</strong> ${activeRatios.length} of ${numLayers}<br>
+                    <strong>Sliding Window:</strong> ${config.sliding_window} (per layer)<br>
+                    <strong>KV Bytes / Entry:</strong> (${config.head_dim} − ${ropeDim}) × ${prec.nope} + ${ropeDim} × ${prec.rope} = ${kvBytesPerEntry} B<br>
+                    ${indexerLine}<strong>Precision:</strong> ${precLabel}<br>
+                    <strong>Bytes per Token:</strong> (${kvBytesPerEntry} + ${indexerBytesPerEntry}) × Σ(1/r) = ${bytesPerToken.toFixed(1)} B<br>
+                    <strong>Sliding-Window Floor:</strong> ${numLayers} × ${config.sliding_window} × ${kvBytesPerEntry} = ${windowBytes} B<br>
+                    <strong>Total Bytes:</strong> ${bytesPerToken.toFixed(1)} × ${tokens} + ${windowBytes} = ${totalBytes.toFixed(0)} bytes<br>
+                    <strong>KV Cache Size:</strong> ${totalBytes.toFixed(0)} / (1024³) ≈ ${sizeGB.toFixed(4)} GB
+                `;
+            } else if (isMLA) {
+                // Multi-head Latent Attention (DeepSeek V3/R1, GLM-5.x). Each layer
+                // caches one latent KV vector of (kv_lora_rank + qk_rope_head_dim)
+                // per token. DSA models (e.g. GLM-5.x) additionally cache a
+                // lightning-indexer key of index_head_dim per token; LMCache stores
+                // that indexer group in the same KV pool, so we fold it in whenever
+                // index_head_dim is present. The indexer key is often kept at lower
+                // precision than the latent cache, so at one uniform dtype this is a
+                // slight over-estimate (the safe direction for capacity planning).
+                const latentDim = config.kv_lora_rank + config.qk_rope_head_dim;
+                const indexerDim = Number.isFinite(config.index_head_dim) ? config.index_head_dim : 0;
+                const elementsPerToken = config.num_hidden_layers * (latentDim + indexerDim);
+                totalElements = elementsPerToken * tokens;
+                totalBytes = totalElements * dtypeSize;
+                sizeGB = totalBytes / (1024 ** 3);
+                const indexerLine = indexerDim
+                    ? `<strong>Indexer Head Dim (DSA):</strong> ${indexerDim}<br>`
+                    : '';
+                const latentExpr = indexerDim
+                    ? `(${config.kv_lora_rank} + ${config.qk_rope_head_dim} + ${indexerDim})`
+                    : `(${config.kv_lora_rank} + ${config.qk_rope_head_dim})`;
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>KV LoRA Rank:</strong> ${config.kv_lora_rank}<br>
+                    <strong>QK RoPE Head Dim:</strong> ${config.qk_rope_head_dim}<br>
+                    ${indexerLine}<strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Total Elements:</strong> ${config.num_hidden_layers} × ${tokens} × ${latentExpr} = ${totalElements}<br>
+                    <strong>Total Bytes:</strong> ${totalElements} × ${dtypeSize} = ${totalBytes} bytes<br>
+                    <strong>KV Cache Size:</strong> ${totalBytes} / (1024³) ≈ ${sizeGB.toFixed(4)} GB
+                `;
+            } else if (isHybridLinear) {
+                // Attention/recurrent hybrid (Qwen3-Next / Qwen3.5 Gated DeltaNet;
+                // Nemotron-H Mamba2 SSM). The recurrent (linear) layers keep a
+                // fixed-size state (no per-token KV growth); only the full-attention
+                // layers grow with the sequence:
+                //   2 × kv_heads × head_dim × n_full × tokens  (growing KV)
+                //
+                // TODO(SSM): the recurrent layers also hold a constant SSM/conv state.
+                // We are holding off on counting it until LMCache decides how it stores
+                // linear-attention layers (whether the state lives in the KV-cache pool
+                // at all, and at what precision / layout). The model's linear_* dims are
+                // kept in the config so we can wire in the exact constant once that's
+                // settled. For now we report only the full-attention KV cache.
+                //
+                // linear_attention_layers counts only the recurrent layers; any
+                // remaining layers (e.g. Nemotron's pure-MLP/MoE layers) hold no cache,
+                // so n_full + n_linear need not equal num_hidden_layers.
+                const linType = typeof config.linear_attention_type === 'string'
+                    ? config.linear_attention_type : 'Gated DeltaNet';
+                const perLayer = 2 * config.num_key_value_heads * config.head_dim;
+                const nFull = config.full_attention_layers;
+                const nLin = config.linear_attention_layers;
+                totalElements = perLayer * nFull * tokens;
+                totalBytes = totalElements * dtypeSize;
+                sizeGB = totalBytes / (1024 ** 3);
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim}<br>
+                    <strong>Full-Attention Layers:</strong> ${nFull} (growing KV)<br>
+                    <strong>Linear (${linType}) Layers:</strong> ${nLin} (recurrent state — not yet counted, TODO pending LMCache storage decision)<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements / Token / Layer:</strong> 2 × ${config.num_key_value_heads} × ${config.head_dim} = ${perLayer}<br>
+                    <strong>Total Elements:</strong> ${perLayer} × ${nFull} × ${tokens} = ${totalElements}<br>
+                    <strong>Total Bytes:</strong> ${totalElements} × ${dtypeSize} = ${totalBytes} bytes<br>
+                    <strong>KV Cache Size (full-attention layers only):</strong> ${totalBytes} / (1024³) ≈ ${sizeGB.toFixed(4)} GB
+                `;
+            } else if (isHybridSWA) {
+                // Gemma-style interleaved attention: full-attention layers cache the
+                // whole sequence; sliding-attention layers cap their KV at the window.
+                // So the cache grows only with the full layers once tokens > window:
+                //   2 × kv_heads × head_dim × (n_full × tokens + n_sliding × min(tokens, window)).
+                const perLayer = 2 * config.num_key_value_heads * config.head_dim;
+                const nFull = config.full_attention_layers;
+                const nSwa = config.sliding_attention_layers;
+                const win = config.sliding_window;
+                const swaTokens = Math.min(tokens, win);
+                totalElements = perLayer * (nFull * tokens + nSwa * swaTokens);
+                totalBytes = totalElements * dtypeSize;
+                sizeGB = totalBytes / (1024 ** 3);
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim}<br>
+                    <strong>Full-Attention Layers:</strong> ${nFull} (cache full sequence)<br>
+                    <strong>Sliding-Attention Layers:</strong> ${nSwa} (cap at window ${win}; using ${swaTokens} tokens)<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements / Token / Layer:</strong> 2 × ${config.num_key_value_heads} × ${config.head_dim} = ${perLayer}<br>
+                    <strong>Total Elements:</strong> ${perLayer} × (${nFull} × ${tokens} + ${nSwa} × ${swaTokens}) = ${totalElements}<br>
+                    <strong>Total Bytes:</strong> ${totalElements} × ${dtypeSize} = ${totalBytes} bytes<br>
+                    <strong>KV Cache Size:</strong> ${totalBytes} / (1024³) ≈ ${sizeGB.toFixed(4)} GB
+                `;
+            } else if (hasHeadDim) {
+                // Models with explicit head_dim (e.g., GQA architectures)
+                totalElements = 2 * config.num_hidden_layers * tokens * config.num_key_value_heads * config.head_dim;
+                totalBytes = totalElements * dtypeSize;
+                sizeGB = totalBytes / (1024 ** 3);
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>Hidden Size:</strong> ${config.hidden_size}<br>
+                    <strong>Number of Attention Heads:</strong> ${config.num_attention_heads}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim}<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Total Elements:</strong> 2 × ${config.num_hidden_layers} × ${tokens} × ${config.num_key_value_heads} × ${config.head_dim} = ${totalElements}<br>
+                    <strong>Total Bytes:</strong> ${totalElements} × ${dtypeSize} = ${totalBytes} bytes<br>
+                    <strong>KV Cache Size:</strong> ${totalBytes} / (1024³) ≈ ${sizeGB.toFixed(4)} GB
+                `;
+            } else {
+                // Standard transformer architecture
+                const headSize = config.hidden_size / config.num_attention_heads;
+                totalElements = 2 * config.num_hidden_layers * tokens * config.num_key_value_heads * headSize;
+                totalBytes = totalElements * dtypeSize;
+                sizeGB = totalBytes / (1024 ** 3);
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>Hidden Size:</strong> ${config.hidden_size}<br>
+                    <strong>Number of Attention Heads:</strong> ${config.num_attention_heads}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Size:</strong> ${headSize} (Hidden Size / Attention Heads)<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Total Elements:</strong> 2 × ${config.num_hidden_layers} × ${tokens} × ${config.num_key_value_heads} × ${headSize} = ${totalElements}<br>
+                    <strong>Total Bytes:</strong> ${totalElements} × ${dtypeSize} = ${totalBytes} bytes<br>
+                    <strong>KV Cache Size:</strong> ${totalBytes} / (1024³) ≈ ${sizeGB.toFixed(4)} GB
+                `;
+            }
+            
+            resultDiv.className = 'result show';
+            resultDiv.innerHTML = `
+                <div class="result-value">KV Cache Size: ${sizeGB.toFixed(4)} GB</div>
+                <div class="result-label">Calculation Details:</div>
+                <div class="details">${details}</div>
+            `;
+        }
+        
+        // Calculate maximum tokens from GPU RAM
+        function calculateMaxTokens() {
+            const model = document.getElementById('model-reverse').value;
+            const gpuRamGB = parseFloat(document.getElementById('gpu-ram').value);
+            const dtype = document.getElementById('dtype-reverse').value;
+            const resultDiv = document.getElementById('result-reverse');
+            
+            // Validation
+            if (isNaN(gpuRamGB) || gpuRamGB <= 0) {
+                resultDiv.className = 'result show error';
+                resultDiv.innerHTML = '<div class="result-label">Error</div><div>Please enter a valid GPU RAM size (greater than 0).</div>';
+                return;
+            }
+            
+            const config = modelConfigs[model];
+            if (!config) {
+                resultDiv.className = 'result show error';
+                resultDiv.innerHTML = '<div class="result-label">Error</div><div>Model configuration not found.</div>';
+                return;
+            }
+            
+            // Get dtype size
+            const dtypeSizes = {
+                'float32': 4,
+                'float16': 2,
+                'bfloat16': 2,
+                'int8': 1
+            };
+            const dtypeSize = dtypeSizes[dtype];
+            
+            // Convert GPU RAM to bytes
+            const totalBytes = gpuRamGB * (1024 ** 3);
+            
+            // Calculate based on model architecture
+            // DeepSeek V4 sparse attention: per-layer compression schedule.
+            const isDSA = Array.isArray(config.compress_ratios)
+                && Number.isFinite(config.head_dim);
+            // Multi-head Latent Attention (DeepSeek V3/R1, GLM-5.x DSA): feature-gated
+            // on kv_lora_rank rather than the model name.
+            const isMLA = Number.isFinite(config.kv_lora_rank)
+                && Number.isFinite(config.qk_rope_head_dim);
+            // Interleaved sliding-window / full attention (Gemma 2/3/4): the sliding
+            // layers cap their KV cache at the window, only the full layers grow.
+            const isHybridSWA = Number.isFinite(config.full_attention_layers)
+                && Number.isFinite(config.sliding_attention_layers)
+                && Number.isFinite(config.sliding_window)
+                && Number.isFinite(config.num_key_value_heads)
+                && Number.isFinite(config.head_dim);
+            // Linear/full hybrid (Qwen3-Next / Qwen3.5): Gated DeltaNet layers keep a
+            // fixed-size recurrent state (no per-token KV); only full layers grow.
+            const isHybridLinear = Number.isFinite(config.full_attention_layers)
+                && Number.isFinite(config.linear_attention_layers)
+                && Number.isFinite(config.num_key_value_heads)
+                && Number.isFinite(config.head_dim);
+            const hasHeadDim = Number.isFinite(config.head_dim)
+                && Number.isFinite(config.num_key_value_heads);
+
+            let maxTokens;
+            let details = '';
+
+            if (isDSA) {
+                // DeepSeek V4 (CSA + HCA hybrid; NOT MLA). Bytes are computed in V4's
+                // native mixed precision (paper §2.3.4) — the dtype dropdown does NOT
+                // apply. KV entry = (head_dim - rope) FP8 + rope BF16; indexer keys
+                // FP4; both compressed at Σ(1/r). Sliding-window floor uses the same
+                // KV byte width and must be covered by the available RAM first.
+                const activeRatios = config.compress_ratios.filter(r => r > 0);
+                const compressFactor = activeRatios.reduce((sum, r) => sum + 1 / r, 0);
+                const ropeDim = Number.isFinite(config.qk_rope_head_dim) ? config.qk_rope_head_dim : 0;
+                const indexerDim = Number.isFinite(config.index_head_dim) ? config.index_head_dim : 0;
+                const prec = getDSAPrecision('-reverse', config);
+                const kvBytesPerEntry = (config.head_dim - ropeDim) * prec.nope + ropeDim * prec.rope;
+                const indexerBytesPerEntry = indexerDim * prec.indexer;
+                const bytesPerToken = (kvBytesPerEntry + indexerBytesPerEntry) * compressFactor;
+                const numLayers = config.compress_ratios.length;
+                const windowBytes = numLayers * config.sliding_window * kvBytesPerEntry;
+                maxTokens = Math.max(0, Math.floor((totalBytes - windowBytes) / bytesPerToken));
+
+                const precLabel = prec.mode === 'custom'
+                    ? `custom (NoPE ${prec.nope} / RoPE ${prec.rope} / indexer ${prec.indexer} B/dim)`
+                    : `paper default (NoPE ${prec.nope}=FP8 / RoPE ${prec.rope}=BF16 / indexer ${prec.indexer}=FP4); dtype selector not applied`;
+                const indexerLine = indexerDim
+                    ? `<strong>Indexer Key (CSA, compressed):</strong> ${indexerDim} × ${prec.indexer} × Σ(1/r) = ${(indexerBytesPerEntry * compressFactor).toFixed(1)} B/token<br>`
+                    : '';
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>GPU RAM Size:</strong> ${gpuRamGB} GB<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim} (RoPE ${ropeDim} @ ${prec.rope} B, NoPE ${config.head_dim - ropeDim} @ ${prec.nope} B)<br>
+                    <strong>Compressed Layers (ratio &gt; 0):</strong> ${activeRatios.length} of ${numLayers}<br>
+                    <strong>Sliding Window:</strong> ${config.sliding_window} (per layer)<br>
+                    <strong>KV Bytes / Entry:</strong> (${config.head_dim} − ${ropeDim}) × ${prec.nope} + ${ropeDim} × ${prec.rope} = ${kvBytesPerEntry} B<br>
+                    ${indexerLine}<strong>Precision:</strong> ${precLabel}<br>
+                    <strong>Bytes per Token:</strong> (${kvBytesPerEntry} + ${indexerBytesPerEntry}) × Σ(1/r) = ${bytesPerToken.toFixed(1)} B<br>
+                    <strong>Sliding-Window Floor:</strong> ${numLayers} × ${config.sliding_window} × ${kvBytesPerEntry} = ${windowBytes} B<br>
+                    <strong>Maximum Tokens:</strong> (${totalBytes} − ${windowBytes}) / ${bytesPerToken.toFixed(1)} = ${maxTokens} tokens
+                `;
+            } else if (isMLA) {
+                // Multi-head Latent Attention (DeepSeek V3/R1, GLM-5.x): per-token
+                // cost is layers × (kv_lora_rank + qk_rope_head_dim), plus a DSA
+                // lightning-indexer key of index_head_dim per layer per token when
+                // present (LMCache stores the indexer group in the same KV pool).
+                const latentDim = config.kv_lora_rank + config.qk_rope_head_dim;
+                const indexerDim = Number.isFinite(config.index_head_dim) ? config.index_head_dim : 0;
+                const elementsPerToken = config.num_hidden_layers * (latentDim + indexerDim);
+                const bytesPerToken = elementsPerToken * dtypeSize;
+                maxTokens = Math.floor(totalBytes / bytesPerToken);
+
+                const indexerLine = indexerDim
+                    ? `<strong>Indexer Head Dim (DSA):</strong> ${indexerDim}<br>`
+                    : '';
+                const latentExpr = indexerDim
+                    ? `(${config.kv_lora_rank} + ${config.qk_rope_head_dim} + ${indexerDim})`
+                    : `(${config.kv_lora_rank} + ${config.qk_rope_head_dim})`;
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>GPU RAM Size:</strong> ${gpuRamGB} GB<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>KV LoRA Rank:</strong> ${config.kv_lora_rank}<br>
+                    <strong>QK RoPE Head Dim:</strong> ${config.qk_rope_head_dim}<br>
+                    ${indexerLine}<strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements per Token:</strong> ${config.num_hidden_layers} × ${latentExpr} = ${elementsPerToken}<br>
+                    <strong>Bytes per Token:</strong> ${elementsPerToken} × ${dtypeSize} = ${bytesPerToken} bytes<br>
+                    <strong>Maximum Tokens:</strong> ${totalBytes} / ${bytesPerToken} = ${maxTokens} tokens
+                `;
+            } else if (isHybridLinear) {
+                // Attention/recurrent hybrid: only the full-attention layers grow.
+                // TODO(SSM): the recurrent (Gated DeltaNet / Mamba2 SSM) layers' constant
+                // state is NOT subtracted yet — holding off until LMCache decides how it
+                // stores linear-attention layers. For now max tokens is computed from the
+                // full-attention KV cache alone.
+                const linType = typeof config.linear_attention_type === 'string'
+                    ? config.linear_attention_type : 'Gated DeltaNet';
+                const perLayer = 2 * config.num_key_value_heads * config.head_dim;
+                const nFull = config.full_attention_layers;
+                const nLin = config.linear_attention_layers;
+                const availElements = totalBytes / dtypeSize;
+                maxTokens = Math.max(0, Math.floor(availElements / (perLayer * nFull)));
+
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>GPU RAM Size:</strong> ${gpuRamGB} GB<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim}<br>
+                    <strong>Full-Attention Layers:</strong> ${nFull} (growing KV)<br>
+                    <strong>Linear (${linType}) Layers:</strong> ${nLin} (recurrent state — not yet counted, TODO pending LMCache storage decision)<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements / Token / Layer:</strong> 2 × ${config.num_key_value_heads} × ${config.head_dim} = ${perLayer}<br>
+                    <strong>Maximum Tokens (full-attention layers only):</strong> ${availElements} / (${perLayer} × ${nFull}) = ${maxTokens} tokens
+                `;
+            } else if (isHybridSWA) {
+                // Gemma-style interleaved attention. Sliding layers cap at the window,
+                // so the token count is piecewise: below the window all layers count
+                // as full; above it only the full layers keep growing.
+                const perLayer = 2 * config.num_key_value_heads * config.head_dim;
+                const nFull = config.full_attention_layers;
+                const nSwa = config.sliding_attention_layers;
+                const win = config.sliding_window;
+                const availElements = totalBytes / dtypeSize;
+                // First assume tokens <= window (every layer caches the full sequence).
+                let n = Math.floor(availElements / (perLayer * (nFull + nSwa)));
+                let regime = 'tokens ≤ window (all layers full)';
+                if (n > win) {
+                    // tokens > window: sliding layers are pinned at `win` tokens.
+                    n = Math.floor((availElements / perLayer - nSwa * win) / nFull);
+                    regime = 'tokens &gt; window (sliding layers capped)';
+                }
+                maxTokens = Math.max(0, n);
+
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>GPU RAM Size:</strong> ${gpuRamGB} GB<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim}<br>
+                    <strong>Full-Attention Layers:</strong> ${nFull}<br>
+                    <strong>Sliding-Attention Layers:</strong> ${nSwa} (window ${win})<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements / Token / Layer:</strong> 2 × ${config.num_key_value_heads} × ${config.head_dim} = ${perLayer}<br>
+                    <strong>Regime:</strong> ${regime}<br>
+                    <strong>Maximum Tokens:</strong> ${maxTokens} tokens
+                `;
+            } else if (hasHeadDim) {
+                // Explicit head_dim: tokens = total_bytes / (2 × layers × kv_heads × head_dim × dtype_size)
+                const elementsPerToken = 2 * config.num_hidden_layers * config.num_key_value_heads * config.head_dim;
+                const bytesPerToken = elementsPerToken * dtypeSize;
+                maxTokens = Math.floor(totalBytes / bytesPerToken);
+
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>GPU RAM Size:</strong> ${gpuRamGB} GB<br>
+                    <strong>Hidden Size:</strong> ${config.hidden_size}<br>
+                    <strong>Number of Attention Heads:</strong> ${config.num_attention_heads}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Dimension:</strong> ${config.head_dim}<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements per Token:</strong> 2 × ${config.num_hidden_layers} × ${config.num_key_value_heads} × ${config.head_dim} = ${elementsPerToken}<br>
+                    <strong>Bytes per Token:</strong> ${elementsPerToken} × ${dtypeSize} = ${bytesPerToken} bytes<br>
+                    <strong>Maximum Tokens:</strong> ${totalBytes} / ${bytesPerToken} = ${maxTokens} tokens
+                `;
+            } else {
+                // Standard transformer: tokens = total_bytes / (2 × layers × kv_heads × head_size × dtype_size)
+                const headSize = config.hidden_size / config.num_attention_heads;
+                const elementsPerToken = 2 * config.num_hidden_layers * config.num_key_value_heads * headSize;
+                const bytesPerToken = elementsPerToken * dtypeSize;
+                maxTokens = Math.floor(totalBytes / bytesPerToken);
+                
+                details = `
+                    <strong>Selected Model:</strong> ${model}<br>
+                    <strong>GPU RAM Size:</strong> ${gpuRamGB} GB<br>
+                    <strong>Hidden Size:</strong> ${config.hidden_size}<br>
+                    <strong>Number of Attention Heads:</strong> ${config.num_attention_heads}<br>
+                    <strong>Number of Hidden Layers:</strong> ${config.num_hidden_layers}<br>
+                    <strong>Number of Key-Value Heads:</strong> ${config.num_key_value_heads}<br>
+                    <strong>Head Size:</strong> ${headSize} (Hidden Size / Attention Heads)<br>
+                    <strong>Data Type Size:</strong> ${dtypeSize} bytes<br>
+                    <strong>Elements per Token:</strong> 2 × ${config.num_hidden_layers} × ${config.num_key_value_heads} × ${headSize} = ${elementsPerToken}<br>
+                    <strong>Bytes per Token:</strong> ${elementsPerToken} × ${dtypeSize} = ${bytesPerToken} bytes<br>
+                    <strong>Maximum Tokens:</strong> ${totalBytes} / ${bytesPerToken} = ${maxTokens} tokens
+                `;
+            }
+            
+            resultDiv.className = 'result show';
+            resultDiv.innerHTML = `
+                <div class="result-value">Maximum Tokens: ${maxTokens.toLocaleString()}</div>
+                <div class="result-label">Calculation Details:</div>
+                <div class="details">${details}</div>
+            `;
+        }
+        
+        // Enter key handler
+        document.addEventListener('DOMContentLoaded', () => {
+            const tokensInput = document.getElementById('tokens');
+            if (tokensInput) {
+                tokensInput.addEventListener('keypress', (e) => {
+                    if (e.key === 'Enter') {
+                        calculateKVCache();
+                    }
+                });
+            }
+            
+            const gpuRamInput = document.getElementById('gpu-ram');
+            if (gpuRamInput) {
+                gpuRamInput.addEventListener('keypress', (e) => {
+                    if (e.key === 'Enter') {
+                        calculateMaxTokens();
+                    }
+                });
+            }
+        });
+        
+        // Load configurations on page load
+        window.addEventListener('load', loadModelConfigs);
+    </script>
+</body>
+</html>
diff --git a/docs/source/_static/modelconfig.json b/docs/source/_static/modelconfig.json
new file mode 100644
index 0000000..9310775
--- /dev/null
+++ b/docs/source/_static/modelconfig.json
@@ -0,0 +1,292 @@
+{
+    "meta-llama/Llama-3.1-8B-Instruct": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8
+    },
+    "meta-llama/Llama-3.1-70B-Instruct": {
+        "hidden_size": 8192,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 80,
+        "num_key_value_heads": 8
+    },
+    "mistralai/Mistral-7B-Instruct-v0.2": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8
+    },
+    "mistralai/Mistral-Large-Instruct-2407": {
+        "hidden_size": 12288,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 88,
+        "num_key_value_heads": 8
+    },
+    "lmsys/longchat-7b-16k": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 32
+    },
+    "Sao10K/L3-8B-Lunaris-v1": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8
+    },
+    "meta-llama/Llama-3.2-3B-Instruct": {
+        "hidden_size": 3072,
+        "num_attention_heads": 24,
+        "num_hidden_layers": 28,
+        "num_key_value_heads": 8
+    },
+    "deepseek-ai/DeepSeek-V3": {
+        "hidden_size": 7168,
+        "num_attention_heads": 128,
+        "num_hidden_layers": 61,
+        "num_key_value_heads": 128,
+        "kv_lora_rank": 512,
+        "qk_rope_head_dim": 64
+    },
+    "deepseek-ai/DeepSeek-R1": {
+        "hidden_size": 7168,
+        "num_attention_heads": 128,
+        "num_hidden_layers": 61,
+        "num_key_value_heads": 128,
+        "kv_lora_rank": 512,
+        "qk_rope_head_dim": 64
+    },
+    "moonshotai/Kimi-K2.6": {
+        "hidden_size": 7168,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 61,
+        "num_key_value_heads": 64,
+        "kv_lora_rank": 512,
+        "qk_rope_head_dim": 64
+    },
+    "deepseek-ai/DeepSeek-V4-Pro": {
+        "num_hidden_layers": 61,
+        "head_dim": 512,
+        "qk_rope_head_dim": 64,
+        "sliding_window": 128,
+        "index_head_dim": 128,
+        "nope_bytes": 1,
+        "rope_bytes": 2,
+        "indexer_bytes": 0.5,
+        "compress_ratios": [128, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 0]
+    },
+    "deepseek-ai/DeepSeek-V4-Flash": {
+        "num_hidden_layers": 43,
+        "head_dim": 512,
+        "qk_rope_head_dim": 64,
+        "sliding_window": 128,
+        "index_head_dim": 128,
+        "nope_bytes": 1,
+        "rope_bytes": 2,
+        "indexer_bytes": 0.5,
+        "compress_ratios": [0, 0, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 128, 4, 0]
+    },
+    "zai-org/GLM-5.1": {
+        "num_hidden_layers": 78,
+        "kv_lora_rank": 512,
+        "qk_rope_head_dim": 64,
+        "index_head_dim": 128
+    },
+    "MiniMaxAI/MiniMax-M2.5": {
+        "hidden_size": 3072,
+        "num_attention_heads": 48,
+        "num_hidden_layers": 62,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "MiniMaxAI/MiniMax-M2.7": {
+        "hidden_size": 3072,
+        "num_attention_heads": 48,
+        "num_hidden_layers": 62,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-235B-A22B": {
+        "hidden_size": 4096,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 94,
+        "num_key_value_heads": 4,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3.5-397B-A17B-FP8": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 60,
+        "num_key_value_heads": 2,
+        "head_dim": 256,
+        "full_attention_layers": 15,
+        "linear_attention_layers": 45,
+        "linear_num_value_heads": 64,
+        "linear_key_head_dim": 128,
+        "linear_value_head_dim": 128
+    },
+    "Qwen/Qwen3-30B-A3B": {
+        "hidden_size": 2048,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 48,
+        "num_key_value_heads": 4,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-Coder-30B-A3B-Instruct": {
+        "hidden_size": 2048,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 48,
+        "num_key_value_heads": 4,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8": {
+        "hidden_size": 6144,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 62,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "meta-llama/Llama-3.1-405B": {
+        "hidden_size": 16384,
+        "num_attention_heads": 128,
+        "num_hidden_layers": 126,
+        "num_key_value_heads": 8
+    },
+    "meta-llama/Llama-3.2-1B-Instruct": {
+        "hidden_size": 2048,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 16,
+        "num_key_value_heads": 8
+    },
+    "Qwen/Qwen3-32B": {
+        "hidden_size": 5120,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 64,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-14B": {
+        "hidden_size": 5120,
+        "num_attention_heads": 40,
+        "num_hidden_layers": 40,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-8B": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-4B": {
+        "hidden_size": 2560,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-0.6B": {
+        "hidden_size": 1024,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 28,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen2.5-7B-Instruct": {
+        "hidden_size": 3584,
+        "num_attention_heads": 28,
+        "num_hidden_layers": 28,
+        "num_key_value_heads": 4
+    },
+    "Qwen/Qwen2.5-3B-Instruct": {
+        "hidden_size": 2048,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 2
+    },
+    "Qwen/Qwen2.5-0.5B": {
+        "hidden_size": 896,
+        "num_attention_heads": 14,
+        "num_hidden_layers": 24,
+        "num_key_value_heads": 2
+    },
+    "Qwen/Qwen-7B": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 32
+    },
+    "zai-org/GLM-4.5": {
+        "hidden_size": 5120,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 92,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "zai-org/GLM-4.6": {
+        "hidden_size": 5120,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 92,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "google/gemma-4-31B-it": {
+        "hidden_size": 5376,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 60,
+        "num_key_value_heads": 16,
+        "head_dim": 256,
+        "sliding_window": 1024,
+        "full_attention_layers": 10,
+        "sliding_attention_layers": 50
+    },
+    "openai/gpt-oss-120b": {
+        "hidden_size": 2880,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 8,
+        "head_dim": 64,
+        "sliding_window": 128,
+        "full_attention_layers": 18,
+        "sliding_attention_layers": 18
+    },
+    "openai/gpt-oss-20b": {
+        "hidden_size": 2880,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 24,
+        "num_key_value_heads": 8,
+        "head_dim": 64,
+        "sliding_window": 128,
+        "full_attention_layers": 12,
+        "sliding_attention_layers": 12
+    },
+    "poolside/Laguna-XS.2": {
+        "hidden_size": 2048,
+        "num_attention_heads": 48,
+        "num_hidden_layers": 40,
+        "num_key_value_heads": 8,
+        "head_dim": 128,
+        "sliding_window": 512,
+        "full_attention_layers": 10,
+        "sliding_attention_layers": 30
+    },
+    "tencent/Hy3-preview": {
+        "hidden_size": 4096,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 80,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-FP8": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 88,
+        "num_key_value_heads": 2,
+        "head_dim": 128,
+        "full_attention_layers": 8,
+        "linear_attention_layers": 40,
+        "linear_attention_type": "Mamba2 SSM"
+    }
+}
diff --git a/docs/source/_static/scroll.css b/docs/source/_static/scroll.css
new file mode 100644
index 0000000..effd29d
--- /dev/null
+++ b/docs/source/_static/scroll.css
@@ -0,0 +1,32 @@
+div.highlight pre {
+    overflow-x: auto;
+    white-space: pre;
+}
+
+/* Wide CSV / docutils tables: horizontal scroll in HTML */
+.compat-table-scroll {
+    overflow-x: auto;
+    max-width: 100%;
+    -webkit-overflow-scrolling: touch;
+}
+
+.compat-table-scroll table {
+    width: max-content;
+    min-width: 100%;
+    max-width: none;
+}
+
+/* Keep wide content tables and long inline strings from overflowing the
+   content column into the right-hand "On this page" ToC. Wide tables scroll
+   horizontally within the column instead of pushing into the ToC. */
+#content {
+    min-width: 0;
+    overflow-wrap: break-word;
+}
+
+#content table.docutils {
+    display: block;
+    width: fit-content;
+    max-width: 100%;
+    overflow-x: auto;
+}
\ No newline at end of file
diff --git a/docs/source/_templates/custom.html b/docs/source/_templates/custom.html
new file mode 100644
index 0000000..e69de29
diff --git a/docs/source/_templates/versioning.html b/docs/source/_templates/versioning.html
new file mode 100644
index 0000000..338439f
--- /dev/null
+++ b/docs/source/_templates/versioning.html
@@ -0,0 +1,17 @@
+{%- if versions %}
+<div class="version-selector">
+  <label for="version-select">Version:</label>
+  <select id="version-select" onchange="location.href=this.value;">
+    {%- for version in versions %}
+    <option value="{{ version.url }}" 
+            {%- if version.name == current_version %} selected="selected"{% endif %}>
+      {%- if version.name == smv_latest_version -%}
+        {{ version.name }} (latest)
+      {%- else -%}
+        {{ version.name }}
+      {%- endif -%}
+    </option>
+    {%- endfor %}
+  </select>
+</div>
+{%- endif %}
diff --git a/docs/source/api_reference/configurations.rst b/docs/source/api_reference/configurations.rst
new file mode 100644
index 0000000..c93b4fb
--- /dev/null
+++ b/docs/source/api_reference/configurations.rst
@@ -0,0 +1,557 @@
+Configuring LMCache
+===================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/configuration`.
+
+
+LMCache supports two types of configurations:
+
+1. **Configuration file**: a YAML (recommended) or JSON file that contains the configuration items.
+2. **Environment variables**: environment variables that start with ``LMCACHE_``. 
+
+To use a configuration file, you can set the ``LMCACHE_CONFIG_FILE`` environment variable to the path of the configuration file.
+
+.. note::
+
+    The environment variable configurations will be ignored if the configuration file is present.
+
+
+General Configurations
+----------------------
+
+Basic cache settings that control the core functionality of LMCache.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - chunk_size
+     - LMCACHE_CHUNK_SIZE
+     - Size of cache chunks. Default: 256
+   * - local_cpu
+     - LMCACHE_LOCAL_CPU
+     - Whether to enable CPU caching. Values: true/false. Default: true
+   * - max_local_cpu_size
+     - LMCACHE_MAX_LOCAL_CPU_SIZE
+     - Maximum CPU cache size in GB. Default: 5.0
+   * - local_cpu_use_hugepages
+     - LMCACHE_LOCAL_CPU_USE_HUGEPAGES
+     - Whether to use Linux hugepages (2 MB) for CPU-pinned KV cache memory. Not compatible with P2P mode or shared memory (multiprocess). Requires pre-allocated hugepages (``sysctl vm.nr_hugepages``). Values: true/false. Default: false
+   * - local_disk
+     - LMCACHE_LOCAL_DISK
+     - Path (or comma-separated paths) to local disk cache directories. Format: ``"file:///path/to/cache"`` or ``"/path/a,/path/b"`` for multi-device I/O. See ``local_disk_path_sharding`` for how paths are assigned to GPUs.
+   * - local_disk_path_sharding
+     - LMCACHE_LOCAL_DISK_PATH_SHARDING
+     - Strategy for selecting a path when multiple paths are provided. Currently only ``"by_gpu"`` is supported, which selects paths based on GPU device ID (default: "by_gpu").
+   * - max_local_disk_size
+     - LMCACHE_MAX_LOCAL_DISK_SIZE
+     - Maximum disk cache size in GB. Default: 0.0
+   * - remote_url
+     - LMCACHE_REMOTE_URL
+     - Remote storage URL. Format: "protocol://host:port".
+   * - remote_serde
+     - LMCACHE_REMOTE_SERDE
+     - Serialization format. Values: "naive" or "cachegen". Default: "naive"
+   * - save_decode_cache
+     - LMCACHE_SAVE_DECODE_CACHE
+     - Whether to store decode KV cache. Values: true/false. Default: false
+   * - use_layerwise
+     - LMCACHE_USE_LAYERWISE
+     - Whether to enable layerwise pipelining. Values: true/false. Default: false
+   * - pre_caching_hash_algorithm
+     - LMCACHE_PRE_CACHING_HASH_ALGORITHM
+     - Hash algorithm for prefix-caching. Default: "builtin"
+   * - save_unfull_chunk
+     - LMCACHE_SAVE_UNFULL_CHUNK
+     - Whether to save unfull chunks. Values: true/false. Default: false
+   * - blocking_timeout_secs
+     - LMCACHE_BLOCKING_TIMEOUT_SECS
+     - Timeout for blocking operations in seconds. Default: 10
+   * - py_enable_gc
+     - LMCACHE_PY_ENABLE_GC
+     - Whether to enable Python garbage collection. Values: true/false. Default: true
+   * - cache_policy
+     - LMCACHE_CACHE_POLICY
+     - Cache eviction policy (e.g. "LRU", "LFU", "FIFO"). Default: "LRU"
+   * - numa_mode
+     - LMCACHE_NUMA_MODE
+     - NUMA-aware memory allocation mode. Values: "auto" (detect from system), "manual" (use extra_config mapping), null (disabled). When enabled, allocates pinned memory on specific NUMA nodes for better GPU-CPU memory bandwidth. Default: null
+   * - external_lookup_client
+     - LMCACHE_EXTERNAL_LOOKUP_CLIENT
+     - External KV lookup service URI (e.g., "mooncakestore://address"). If null, defaults to LMCache's internal lookup client. Default: null
+   * - priority_limit
+     - LMCACHE_PRIORITY_LIMIT
+     - Caches requests only if priority value ≤ limit. (**Not applicable for PD Disaggregation**) Type: int. Default: None
+   * - min_retrieve_tokens
+     - LMCACHE_MIN_RETRIEVE_TOKENS
+     - Minimum number of hit tokens required to perform retrieve. If hit tokens < this value, skip retrieve but still record the hits to avoid re-storing existing chunks. See :ref:`performance_tuning` for a working example. Default: 0 (disabled)
+   * - store_location
+     - LMCACHE_STORE_LOCATION
+     - A single storage backend name to store KV caches into. When specified, only the matching backend receives store operations. Valid values are the backend class names registered in the storage manager, including: ``"LocalCPUBackend"``, ``"LocalDiskBackend"``, ``"RemoteBackend"``, ``"PDBackend"``, ``"P2PBackend"``, ``"GdsBackend"``, etc, and any storage plugin backends. Note: ``"PDBackend"`` cannot be used as a store location for a decoder instance in a PD setup, since PDBackend is one-way from prefiller to decoder only. Default: null (store to all active backends)
+   * - retrieve_locations
+     - LMCACHE_RETRIEVE_LOCATIONS
+     - List of storage backend names to search when retrieving or looking up KV caches. When specified, only the listed backends are searched. Valid values are the backend class names registered in the storage manager, including: ``"LocalCPUBackend"``, ``"LocalDiskBackend"``, ``"RemoteBackend"``, ``"PDBackend"``, ``"P2PBackend"``, ``"GdsBackend"``, etc, and any storage plugin backends. Default: null (search all active backends)
+   * - extra_config
+     - LMCACHE_EXTRA_CONFIG={"key": value, ...}
+     - Additional configuration as JSON dict. For NUMA manual mode, include "gpu_to_numa_mapping": {gpu_id: numa_node, ...}. Default: {}
+
+Lazy Memory Allocator Configurations
+------------------------------------
+
+Settings for the lazy memory allocator that enables gradual memory allocation to reduce startup time and initial memory footprint.
+
+.. note::
+
+    The lazy memory allocator is designed for scenarios with large CPU memory configurations. It starts with a small initial allocation and gradually expands as needed, reducing startup wait time and avoiding unnecessary memory consumption when the full capacity is not required.
+    
+    **Key characteristics:**
+    
+    - **One-time expansion**: Memory expands until target size is reached, then stops
+    - **No shrinking**: Once allocated, memory is never released back to the system
+    - **Automatic activation**: Only activates when ``max_local_cpu_size`` exceeds ``lazy_memory_safe_size``
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - enable_lazy_memory_allocator
+     - LMCACHE_ENABLE_LAZY_MEMORY_ALLOCATOR
+     - Whether to enable lazy memory allocator. Values: true/false. Default: false
+   * - lazy_memory_initial_ratio
+     - LMCACHE_LAZY_MEMORY_INITIAL_RATIO
+     - Initial memory allocation ratio (0.0-1.0). Determines the fraction of max_local_cpu_size to allocate at startup. Default: 0.2 (20%)
+   * - lazy_memory_expand_trigger_ratio
+     - LMCACHE_LAZY_MEMORY_EXPAND_TRIGGER_RATIO
+     - Memory usage ratio (0.0-1.0) that triggers expansion. When used memory exceeds this ratio of current capacity, expansion begins. Default: 0.5 (50%)
+   * - lazy_memory_step_ratio
+     - LMCACHE_LAZY_MEMORY_STEP_RATIO
+     - Memory expansion step ratio (0.0-1.0). Each expansion adds this fraction of max_local_cpu_size. Default: 0.1 (10%)
+   * - lazy_memory_safe_size
+     - LMCACHE_LAZY_MEMORY_SAFE_SIZE
+     - Threshold in GB above which lazy allocator activates. If max_local_cpu_size ≤ this value, lazy allocator is disabled regardless of enable_lazy_memory_allocator setting. Default: 0.0
+   * - reserve_local_cpu_size
+     - LMCACHE_RESERVE_LOCAL_CPU_SIZE
+     - Reserved system memory in GB that should not be allocated by LMCache. Used to prevent out-of-memory conditions. Default: 0.0
+     
+Cache Blending Configurations
+-----------------------------
+
+Settings related to cache blending functionality.
+
+.. note::
+
+    We have an end-to-end `example <https://github.com/LMCache/LMCache/tree/dev/examples/blend_kv_v1>`_.
+    We also have more :doc:`detailed documentation <../kv_cache_optimizations/blending>`.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - enable_blending
+     - LMCACHE_ENABLE_BLENDING
+     - Whether to enable blending. Values: true/false. Default: false
+   * - blend_recompute_ratios
+     - LMCACHE_BLEND_RECOMPUTE_RATIOS
+     - Ratio of blending recompute. Default: 0.15
+   * - blend_check_layers
+     - LMCACHE_BLEND_CHECK_LAYERS
+     - Layers to determine the recomputed tokens. Default: 1
+   * - blend_special_str
+     - LMCACHE_BLEND_SPECIAL_STR
+     - Separator string for blending. Default: " # # "
+
+Peer-to-Peer Sharing Configurations
+-----------------------------------
+
+Settings for enabling and configuring peer-to-peer CPU KV cache sharing and global KV cache lookup.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - enable_p2p
+     - LMCACHE_ENABLE_P2P
+     - Whether to enable peer-to-peer sharing. Values: true/false. Default: false
+   * - p2p_host
+     - LMCACHE_P2P_HOST
+     - Ip address. Required if enable_p2p is true
+   * - peer_init_ports
+     - LMCACHE_PEER_INIT_PORTS
+     - Ports for p2p peer init. Required if enable_p2p is true
+   * - peer_lookup_ports
+     - LMCACHE_PEER_lookup_PORTS
+     - Ports for p2p peer lookup. Required if enable_p2p is true
+   * - transfer_channel
+     - LMCACHE_TRANSFER_CHANNEL
+     - Such as `nixl`. Required if enable_p2p is true
+
+Controller Configurations
+-------------------------
+
+Settings for the KV cache controller functionality.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - enable_controller
+     - LMCACHE_ENABLE_CONTROLLER
+     - Whether to enable controller. Values: true/false. Default: false
+   * - lmcache_instance_id
+     - LMCACHE_LMCACHE_INSTANCE_ID
+     - ID of the LMCache instance. Default: "lmcache_default_instance"
+   * - controller_url
+     - LMCACHE_CONTROLLER_URL
+     - URL of the controller server
+   * - lmcache_worker_port
+     - LMCACHE_LMCACHE_WORKER_PORT
+     - Port number for LMCache worker
+
+Disaggregated Prefill Configurations
+-------------------------------------------
+
+Settings for disaggregated prefill functionality. The latest/default PD is implemented inside of `lmcache/v1/storage_backend/pd_backend.py`.
+
+.. note::
+
+    When PD is enabled, the following restrictions apply (welcome contributions to remove these restrictions):
+    
+    - remote_url must be null
+    - save_decode_cache must be false
+    - enable_p2p must be false
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - enable_pd
+     - LMCACHE_ENABLE_PD
+     - Whether to enable PD. Values: true/false. Default: false
+   * - transfer_channel
+     - LMCACHE_TRANSFER_CHANNEL
+     - Transfer channel used for PD. Values: "nixl". Default: none
+   * - pd_role
+     - LMCACHE_PD_ROLE
+     - PD role. Values: "sender" (prefiller) or "receiver" (decoder).
+   * - pd_buffer_size
+     - LMCACHE_PD_BUFFER_SIZE
+     - Upper bound of PD transport buffer size (in bytes), aligned to chunk size. Required for both senders and receivers when enable_pd=true
+   * - pd_buffer_device
+     - LMCACHE_PD_BUFFER_DEVICE
+     - Device for PD buffer. Values: "cpu", "cuda". Required for both senders and receivers when enable_pd=true
+   * - nixl_backends
+     - LMCACHE_NIXL_BACKENDS
+     - List of Nixl transport backends. Useful for non-disaggregated use case (see below). UCX default is sufficient for disagg use case. Default: ["UCX"]
+   * - pd_peer_host
+     - LMCACHE_PD_PEER_HOST
+     - Host for peer connections. Required for receivers to bind to
+   * - pd_peer_init_port
+     - LMCACHE_PD_PEER_INIT_PORT
+     - Initialization port for peer connections. Required for receivers to bind to
+   * - pd_peer_alloc_port
+     - LMCACHE_PD_PEER_ALLOC_PORT
+     - Allocation port for peer connections. Required for receivers to bind to
+   * - pd_proxy_host
+     - LMCACHE_PD_PROXY_HOST
+     - Host for proxy server. Required for senders to connect to inform the proxy when transfer to decoder has been completed
+   * - pd_proxy_port
+     - LMCACHE_PD_PROXY_PORT
+     - Port for proxy server. Required for senders to connect to inform the proxy when transfer to decoder has been completed
+   * - pd_allocation_timeout_sec
+     - LMCACHE_PD_ALLOCATION_TIMEOUT_SEC
+     - Maximum seconds to retry memory allocation before giving up. Default: 5.0
+   * - pd_shutdown_timeout_sec
+     - LMCACHE_PD_SHUTDOWN_TIMEOUT_SEC
+     - Maximum seconds to wait for event loop shutdown and thread join. Default: 5.0
+   * - pd_condition_poll_interval_sec
+     - LMCACHE_PD_CONDITION_POLL_INTERVAL_SEC
+     - Polling interval in seconds when waiting on a threading/asyncio Condition. Small enough to be responsive, large enough not to spin-waste CPU. Default: 0.05
+   * - pd_max_prefill_len
+     - LMCACHE_PD_MAX_PREFILL_LEN
+     - Maximum prefill token length that the PD buffer must be able to hold. If > 0, initialization raises ValueError when the buffer capacity (in tokens) is smaller than this value. Set to 0 (default) to skip the check.
+   * - pd_backend_mode
+     - LMCACHE_PD_BACKEND_MODE
+     - Select the PD backend implementation: 'async' (default) uses the asyncio-based implementation; 'sync' uses the original thread-based synchronous implementation. Default: "async"
+   * - pd_skip_proxy_notification
+     - LMCACHE_PD_SKIP_PROXY_NOTIFICATION
+     - When true, the sender skips ZMQ proxy notification after KV transfer and does not require pd_proxy_host/pd_proxy_port. This option is intended for external orchestrators only (e.g., vLLM Production Stack router) that manage the prefill-decode request flow via HTTP and do not rely on ZMQ notifications. It must not be used with LMCache's built-in disaggregation proxy (``disagg_proxy_server.py``), which depends on ZMQ notifications to know when KV transfer is complete before forwarding the decode request. Values: true/false. Default: false
+   * - pd_bidirectional
+     - LMCACHE_PD_BIDIRECTIONAL
+     - When true, enables bidirectional NIXL cache probe. The prefiller queries the decoder for cached KV blocks before transfer, and reads cached blocks via NIXL RDMA instead of recomputing. Values: true/false. Default: false
+   * - pd_peer_query_port
+     - LMCACHE_PD_PEER_QUERY_PORT
+     - ZMQ ports for the bidirectional cache query channel (one per TP rank). Required on both prefiller and decoder when pd_bidirectional=true. Example: [7500, 7501, 7502, 7503]
+
+P2P Backend Configurations
+--------------------------
+
+Settings for P2P (peer-to-peer) backend timeout behavior. These configurations are specified through ``extra_config``.
+
+.. code-block:: yaml
+
+    extra_config:
+      p2p_socket_recv_timeout_ms: 30000
+      p2p_socket_send_timeout_ms: 10000
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Configuration Key
+     - Default
+     - Description
+   * - p2p_socket_recv_timeout_ms
+     - 30000
+     - Timeout in milliseconds for socket receive operations
+   * - p2p_socket_send_timeout_ms
+     - 10000
+     - Timeout in milliseconds for socket send operations
+
+Disk I/O Backend Configurations
+---------------------------------
+
+Settings shared by disk-based storage backends (local disk and GDS). These configurations are specified through ``extra_config``.
+
+.. code-block:: yaml
+
+    extra_config:
+      use_odirect: true
+      disk_io_threads: 8
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Configuration Key
+     - Default
+     - Description
+   * - use_odirect
+     - false
+     - Enable O_DIRECT for disk I/O, bypassing the kernel page cache. Recommended when most local CPU memory is already used for KV cache offloading.
+   * - disk_io_threads
+     - 4
+     - Number of worker threads in the disk I/O thread pool. Applies to both the local disk backend and the GDS backend. Increase for higher parallelism on fast NVMe drives. (Replaces the deprecated ``gds_io_threads`` key.)
+
+Nixl (as a storage backend) Configurations
+------------------------------------------
+
+Settings for using Nixl as a storage backend instead of disaggregated prefill. This mode requires additional configurations in ``extra_config``.
+
+.. note::
+
+    This is a different mode from disaggregated prefill. When using Nixl as a storage backend, you need to configure it through ``extra_config``.
+
+.. code-block:: yaml
+
+  
+    extra_config: 
+      # enable_nixl_storage will disable disaggregated prefill mode.
+      enable_nixl_storage: true
+      nixl_backend: "POSIX"  # Options: "GDS", "GDS_MT", "POSIX", "HF3FS", "OBJ"
+      nixl_path: "/path/to/storage/"
+      nixl_pool_size: 64
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 40
+
+   * - Configuration Key
+     - Description
+   * - enable_nixl_storage
+     - Whether to enable Nixl storage backend. Values: true/false
+   * - nixl_backend
+     - Storage backend type. Options: "GDS", "GDS_MT", "POSIX", "HF3FS", "OBJ"
+   * - nixl_path
+     - File system path for Nixl storage
+   * - nixl_pool_size
+     - Number of files or objects in the storage pool
+   * - nixl_endpoint_list
+     - List of object-storage endpoint URLs for per-worker distribution. Each TP worker selects an entry round-robin by ``local_worker_id``, overriding ``nixl_backend_params.endpoint_override``. Only applied when ``nixl_backend`` is ``"OBJ"`` (silently ignored otherwise). Each entry must start with ``http://`` or ``https://``; an empty list raises ``ValueError`` at engine init.
+   * - nixl_use_hugepages
+     - **Deprecated.** Use ``local_cpu_use_hugepages`` instead. When set, the value is copied into ``local_cpu_use_hugepages`` (a warning is logged) and the key is dropped. Hugepages have never applied to GPU buffers; in CPU mode the NIXL pool is now owned by ``LocalCPUBackend``.
+
+
+Additional Storage Configurations
+---------------------------------
+
+Settings for different storage backends and paths.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - gds_path
+     - LMCACHE_GDS_PATH
+     - Path for GDS backend. Supports comma-separated paths for multi-device I/O (e.g. ``/mnt/nvme0/cache,/mnt/nvme1/cache``). See ``gds_path_sharding`` for how paths are assigned to GPUs.
+   * - gds_path_sharding
+     - LMCACHE_GDS_PATH_SHARDING
+     - Strategy for selecting a path when multiple paths are provided. Currently only ``"by_gpu"`` is supported, which selects paths based on GPU device ID (default: "by_gpu").
+   * - gds_buffer_size
+     - LMCACHE_GDS_BUFFER_SIZE
+     - Buffer size for GDS operations
+   * - use_gds
+     - LMCACHE_USE_GDS
+     - Enable or disable GPU Direct Storage API usage (default: true)
+   * - gds_backend
+     - LMCACHE_GDS_BACKEND
+     - GDS library backend to use (default: "cufile")
+
+Custom Prometheus Histogram Buckets
+------------------------------------
+
+You can override the default bucket boundaries for any Prometheus histogram metric
+by adding a key ``histogram_bucket_<name>`` to ``extra_config``, where ``<name>``
+is the metric name **without** the ``lmcache:`` prefix.
+
+The value must be a list of numeric boundaries (floats or ints).
+
+.. code-block:: yaml
+
+    extra_config:
+      histogram_bucket_time_to_retrieve: [0.01, 0.05, 0.1, 0.5, 1.0, 5.0]
+      histogram_bucket_retrieve_speed: [100, 500, 1000, 5000, 10000]
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Available Histogram Names
+     - Description
+   * - ``time_to_retrieve``
+     - Time to retrieve from cache (seconds)
+   * - ``time_to_store``
+     - Time to store to cache (seconds)
+   * - ``time_to_lookup``
+     - Time to lookup in cache (seconds)
+   * - ``retrieve_process_tokens_time``
+     - Time to process tokens in retrieve (seconds)
+   * - ``retrieve_broadcast_time``
+     - Time to broadcast memory objects in retrieve (seconds)
+   * - ``retrieve_to_gpu_time``
+     - Time to move data to GPU in retrieve (seconds)
+   * - ``remote_backend_batched_get_blocking_time``
+     - Time to get data from remote backend (seconds)
+   * - ``instrumented_connector_batched_get_time``
+     - Time used by the connector (seconds)
+   * - ``store_process_tokens_time``
+     - Time to process tokens in store (seconds)
+   * - ``store_from_gpu_time``
+     - Time to move data from GPU in store (seconds)
+   * - ``store_put_time``
+     - Time to put data to storage in store (seconds)
+   * - ``retrieve_speed``
+     - Retrieve speed (tokens per second)
+   * - ``store_speed``
+     - Store speed (tokens per second)
+   * - ``p2p_time_to_transfer``
+     - Time to transfer via P2P (seconds)
+   * - ``p2p_transfer_speed``
+     - P2P transfer speed (tokens per second)
+   * - ``remote_time_to_get``
+     - Time to get from remote backends (ms)
+   * - ``remote_time_to_put``
+     - Time to put to remote backends (ms)
+   * - ``remote_time_to_get_sync``
+     - Time to get from remote backends synchronously (ms)
+   * - ``request_cache_hit_rate``
+     - Request cache hit rate (0.0 to 1.0)
+   * - ``request_cache_lifespan``
+     - Request cache lifespan (minutes)
+
+Internal API Server Configurations
+----------------------------------
+
+Settings for the internal API server that provides management and debugging APIs for LMCache engines. The API server runs on each worker and scheduler, allowing you to inspect and control LMCache behavior at runtime.
+
+.. note::
+
+    The internal API server provides endpoints for:
+    
+    - **Metrics**: Performance and cache statistics 
+    - **Configuration**: Runtime configuration inspection
+    - **Metadata**: Engine and model metadata
+    - **Threads**: Thread debugging information
+    - **Log Level**: Dynamic log level adjustment
+    - **Script Execution**: Run custom Python scripts with access to the LMCache engine
+
+Configuration Options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - internal_api_server_enabled
+     - LMCACHE_INTERNAL_API_SERVER_ENABLED
+     - Whether to enable internal API server. Default: false
+   * - internal_api_server_host
+     - LMCACHE_INTERNAL_API_SERVER_HOST
+     - Host for internal API server to bind to. Default: "0.0.0.0"
+   * - internal_api_server_port_start
+     - LMCACHE_INTERNAL_API_SERVER_PORT_START
+     - Starting port for internal API server. Port assignment: Scheduler = port_start + 0, Worker i = port_start + i + 1. Example: If port_start=6999, then Scheduler=6999, Worker 0=7000, Worker 1=7001, etc. Default: 6999
+   * - internal_api_server_include_index_list
+     - LMCACHE_INTERNAL_API_SERVER_INCLUDE_INDEX_LIST
+     - List of worker/scheduler indices to enable API server on. Use 0 for scheduler, 1 for worker 0, 2 for worker 1, etc. If null, enables on all workers/scheduler. Example: [0, 1] enables only on scheduler and worker 0. Default: null
+   * - internal_api_server_socket_path_prefix
+     - LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX
+     - If specified, use Unix domain sockets instead of TCP ports. Socket paths will be "{prefix}_{port}". Example: "/tmp/lmcache_api_socket" creates "/tmp/lmcache_api_socket_6999", "/tmp/lmcache_api_socket_7000", etc. Default: null
+
+Plugin Configurations
+---------------------
+
+Settings for plugin system.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - plugin_locations
+     - LMCACHE_PLUGIN_LOCATIONS
+     - List of plugin locations. Default: []
+
+Deprecated Configurations
+-------------------------
+
+These configurations are deprecated and may be removed in future versions.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 30 40
+
+   * - YAML Config Name
+     - Environment Variable
+     - Description
+   * - audit_actual_remote_url
+     - LMCACHE_AUDIT_ACTUAL_REMOTE_URL
+     - (Deprecated) URL of actual remote LMCache instance for auditing. Use extra_config['audit_actual_remote_url'] instead
+     
diff --git a/docs/source/api_reference/dynamic_connector.rst b/docs/source/api_reference/dynamic_connector.rst
new file mode 100644
index 0000000..edece38
--- /dev/null
+++ b/docs/source/api_reference/dynamic_connector.rst
@@ -0,0 +1,72 @@
+vLLM Dynamic Connector
+======================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+Upstream Integration:
+~~~~~~~~~~~~~~~~~~~~~
+
+LMCache integration with official upstream vLLM was introduced in `early February 2025 <https://github.com/vllm-project/vllm/pull/12953>`_.
+
+vLLM imports the connector from the lmcache package and wraps it in `vllm/distributed/kv_transfer/kv_connector/v1/lmcache_connector.py <https://github.com/vllm-project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/lmcache_connector.py>`_:
+
+.. code-block:: python
+
+    from lmcache.integration.vllm.vllm_v1_adapter import LMCacheConnectorV1Impl
+
+This means that any updates to LMCache connector need to be synced/updated in the upstream vLLM. 
+
+Example usage of vLLM upstream connector: 
+
+**Pythonic Transfer Config:** 
+
+.. code-block:: python
+
+    from vllm.config import KVTransferConfig
+    ktc = KVTransferConfig(
+        kv_connector="LMCacheConnectorV1",
+        kv_role="kv_both",
+    )
+
+**Command Line Transfer Configs:** 
+
+.. code-block:: bash
+
+    vllm serve "YOUR_MODEL" \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Dynamic Connector:
+~~~~~~~~~~~~~~~~~~
+
+`In June 2025 <https://github.com/vllm-project/vllm/pull/18142>`_, vLLM supports dynamic loading of KV connector implementations so we can directly reference connectors from the LMCache package without having to update vLLM. 
+
+Example usage of dynamic connector from LMCache: 
+
+**Pythonic Transfer Config:** 
+
+.. code-block:: python
+
+    from vllm.config import KVTransferConfig
+    ktc = KVTransferConfig(
+        kv_connector="LMCacheConnectorV1Dynamic",
+        kv_role="kv_both",
+        kv_connector_module_path="lmcache.integration.vllm.lmcache_connector_v1",
+    )
+
+**Command Line Transfer Config:** 
+
+.. code-block:: bash
+
+    vllm serve "YOUR_MODEL" \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1Dynamic","kv_role":"kv_both","kv_connector_module_path":"lmcache.integration.vllm.lmcache_connector_v1"}'
+
+This allows LMCache to modify/develop connectors and quickly plug-and-play. 
+
+Any custom adapters will be documented here in the future as well as possible deprecations to the upstream connector. 
+
+
diff --git a/docs/source/api_reference/multimodality.rst b/docs/source/api_reference/multimodality.rst
new file mode 100644
index 0000000..3be50bb
--- /dev/null
+++ b/docs/source/api_reference/multimodality.rst
@@ -0,0 +1,464 @@
+KV Caching for Multimodal Models with vLLM
+##########################################
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+Overview
+********
+
+vLLM is building on its multimodal capability and currently supports the following `List of Multimodal Language Models <https://docs.vllm.ai/en/latest/models/supported_models.html#list-of-multimodal-language-models>`_. 
+
+LMCache can therefore be used to speed up inference time for all multimodal models supported by vLLM. This document shows the speedup improvements using LMCache for KV caching in vLLM for multimodal models.
+
+Examples of TTFT speed up for different multimodal types 
+========================================================
+
+Prerequisites
+-------------
+
+- A Machine with at least one GPU. You can adjust the max model length of your vLLM instance depending on your GPU memory
+- vLLM and LMCache installed (:doc:`Installation Guide <../getting_started/installation>`)
+- vLLM audio dependencies installed: ``pip install vllm[audio]``
+
+Examples
+--------
+
+.. note::
+
+    The examples below use a python script for inferencing multimodal models hosted by vLLM.
+    The script is the `openai_chat_completion_client_for_multimodal python script in vLLM <https://github.com/vllm-project/vllm/blob/main/examples/online_serving/openai_chat_completion_client_for_multimodal.py>`_.
+    You will need to download it locally for running the examples below.
+    The script is printed in the `reference section <#reference-inferencing-multimodal-models-in-vllm-example-python-script>`_ that follows for you perusal.
+    Go to the `Example output <#example-output>`_ section to see the output in the vLLM logs that demonstrate the speedup improvements.
+
+
+Audio Inference with Ultravox:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Start vLLM server with ``fixie-ai/ultravox-v0_5-llama-3_2-1b`` model and LMCache KV caching:
+
+.. code-block:: bash
+
+   vllm serve fixie-ai/ultravox-v0_5-llama-3_2-1b \
+       --max-model-len 4096 --trust-remote-code \
+       --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+Run the python script twice to demonstrate TTFT speedup on the second turn because of the caching:
+
+.. code-block:: bash
+
+   # run twice to see TTFT speedup
+   python openai_chat_completion_client_for_multimodal.py --chat-type audio
+
+Single Image Inference with Llava:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Start vLLM server with ``llava-hf/llava-1.5-7b-hf`` model and LMCache KV caching:
+
+.. code-block:: bash
+
+   vllm serve llava-hf/llava-1.5-7b-hf \
+       --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+Run the python script twice to demonstrate TTFT speedup on the second turn because of the caching:
+
+.. code-block:: bash
+
+   # run twice to see TTFT speedup
+   python openai_chat_completion_client_for_multimodal.py --chat-type single-image
+
+Multi-image Inference with Phi-3.5-vision-instruct:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Start vLLM server with ``microsoft/Phi-3.5-vision-instruct`` model and LMCache KV caching:
+
+.. code-block:: bash
+
+   vllm serve microsoft/Phi-3.5-vision-instruct \
+       --trust-remote-code --max-model-len 4096 --limit-mm-per-prompt '{"image":2}' \
+       --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+Run the python script twice to demonstrate TTFT speedup on the second turn because of the caching:
+
+.. code-block:: bash
+
+   # run twice to see TTFT speedup
+   python openai_chat_completion_client_for_multimodal.py --chat-type multi-image
+
+Video Inference with Llava-OneVision:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Start vLLM server with ``llava-hf/llava-onevision-qwen2-7b-ov-hf`` model and LMCache KV caching:
+
+.. code-block:: bash
+
+   vllm serve llava-hf/llava-onevision-qwen2-7b-ov-hf \
+       --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+Run the python script twice to demonstrate TTFT speedup on the second turn because of the caching:
+
+.. code-block:: bash
+
+   # run twice to see TTFT speedup
+   python openai_chat_completion_client_for_multimodal.py --chat-type video
+
+
+Example output
+--------------
+
+When running the examples above you will notice output in the vLLM logs similar to below. 
+
+This first output demonstrates the tokens being cached and loaded.
+
+.. code-block:: text
+
+   [2025-08-04 22:43:35,484] LMCache INFO: Reqid: chatcmpl-05e2d296601046b29210f53a1fa30b13, Total tokens 1536, LMCache hit tokens: 1536, need to load: 1535 (vllm_v1_adapter.py:803:lmcache.integration.vllm.vllm_v1_adapter)
+
+This then shows the speedup between the first and second runs.
+
+1. First request: 
+
+.. code-block:: text
+
+   Chat completion output from input audio: It seems like you're excitedly sharing your thoughts and predictions about a game you're about to watch. The audio appears to be a stream of comments or a social media post. The words "one pitch on the way to Edgar Martinez" suggest that someone is saying something in a baseball chat or social media post about the
+   Chat completion output from audio url: It appears to be a enthusiastic and excited baseball comment from an individual. The content seems to be a play-by-play description of a specific baseball game, with the narrator belonging to a team that is competing in the American League Championship Series. The reference to the player Edgar Martinez is a nod to a well-known baseball player,
+   Chat completion output from base64 encoded audio: It seems like you're excited about a baseball game, possibly the Los Angeles Dodgers or the Boston Red Sox, but it's unclear which one. The text mentions a "pitcher" and "swung on the line," but it's not entirely obvious which team it's referring to.
+   
+   However, the mention of "
+   Time taken: 50.828808307647705 seconds
+
+2. Second request: 
+
+.. code-block:: text
+
+   Chat completion output from input audio: It seems like you're extremely excited about the possibility of the San Francisco Giants winning the American League championship and playing in the World Series. The audio is filled with emotions and a sense of optimism, with you enthusiastically expressing your thoughts and feelings. It's clear that this is a significant moment for you, particularly given the fact
+   Chat completion output from audio url: I can tell you're excited about a baseball game. It seems like you're reliving a moment during the middle of a game, especially the highlight of a six runs game for the Golden Giants. The audio appears to include a local sports radio talk show style broadcast, with a ringer ("the guy" in the
+   Chat completion output from base64 encoded audio: It seems like you're having a lively discussion about a Major League Baseball game, specifically about the shortstop playing for the Mariners and,Mario Upton swinging at a pitch and eventually being thrown out on a play at the plate. The atmosphere is excited, with all the cheering and commentary you've written. It appears to
+   Time taken: 3.3407371044158936 seconds
+
+
+Reference: Inferencing multimodal models in vLLM example Python script 
+======================================================================
+
+Source: https://github.com/vllm-project/vllm/blob/main/examples/online_serving/openai_chat_completion_client_for_multimodal.py
+
+.. code-block:: python
+
+   # SPDX-License-Identifier: Apache-2.0
+   # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+   
+   import base64
+   
+   import requests
+   from openai import OpenAI
+   
+   from vllm.utils import FlexibleArgumentParser
+   
+   # SPDX-License-Identifier: Apache-2.0
+   # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+   from openai import APIConnectionError, OpenAI
+   from openai.pagination import SyncPage
+   from openai.types.model import Model
+   
+   import time
+   
+   
+   def get_first_model(client: OpenAI) -> str:
+       """
+       Get the first model from the vLLM server.
+       """
+       try:
+           models: SyncPage[Model] = client.models.list()
+       except APIConnectionError as e:
+           raise RuntimeError(
+               "Failed to get the list of models from the vLLM server at "
+               f"{client.base_url} with API key {client.api_key}. Check\n"
+               "1. the server is running\n"
+               "2. the server URL is correct\n"
+               "3. the API key is correct"
+           ) from e
+   
+       if len(models.data) == 0:
+           raise RuntimeError(f"No models found on the vLLM server at {client.base_url}")
+   
+       return models.data[0].id
+   
+   # Modify OpenAI's API key and API base to use vLLM's API server.
+   openai_api_key = "EMPTY"
+   openai_api_base = "http://localhost:8000/v1"
+   
+   client = OpenAI(
+       # defaults to os.environ.get("OPENAI_API_KEY")
+       api_key=openai_api_key,
+       base_url=openai_api_base,
+   )
+   
+   
+   def encode_base64_content_from_url(content_url: str) -> str:
+       """Encode a content retrieved from a remote url to base64 format."""
+   
+       with requests.get(content_url) as response:
+           response.raise_for_status()
+           result = base64.b64encode(response.content).decode("utf-8")
+   
+       return result
+   
+   
+   # Text-only inference
+   def run_text_only(model: str) -> None:
+       chat_completion = client.chat.completions.create(
+           messages=[{"role": "user", "content": "What's the capital of France?"}],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion.choices[0].message.content
+       print("Chat completion output:", result)
+   
+   
+   # Single-image input inference
+   def run_single_image(model: str) -> None:
+       ## Use image url in the payload
+       image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
+       chat_completion_from_url = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this image?"},
+                       {
+                           "type": "image_url",
+                           "image_url": {"url": image_url},
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_url.choices[0].message.content
+       print("Chat completion output from image url:", result)
+   
+       ## Use base64 encoded image in the payload
+       image_base64 = encode_base64_content_from_url(image_url)
+       chat_completion_from_base64 = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this image?"},
+                       {
+                           "type": "image_url",
+                           "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"},
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_base64.choices[0].message.content
+       print("Chat completion output from base64 encoded image:", result)
+   
+   
+   # Multi-image input inference
+   def run_multi_image(model: str) -> None:
+       image_url_duck = "https://upload.wikimedia.org/wikipedia/commons/d/da/2015_Kaczka_krzy%C5%BCowka_w_wodzie_%28samiec%29.jpg"
+       image_url_lion = "https://upload.wikimedia.org/wikipedia/commons/7/77/002_The_lion_king_Snyggve_in_the_Serengeti_National_Park_Photo_by_Giles_Laurent.jpg"
+       chat_completion_from_url = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What are the animals in these images?"},
+                       {
+                           "type": "image_url",
+                           "image_url": {"url": image_url_duck},
+                       },
+                       {
+                           "type": "image_url",
+                           "image_url": {"url": image_url_lion},
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_url.choices[0].message.content
+       print("Chat completion output:", result)
+   
+   
+   # Video input inference
+   def run_video(model: str) -> None:
+       video_url = "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerFun.mp4"
+       video_base64 = encode_base64_content_from_url(video_url)
+   
+       ## Use video url in the payload
+       chat_completion_from_url = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this video?"},
+                       {
+                           "type": "video_url",
+                           "video_url": {"url": video_url},
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_url.choices[0].message.content
+       print("Chat completion output from image url:", result)
+   
+       ## Use base64 encoded video in the payload
+       chat_completion_from_base64 = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this video?"},
+                       {
+                           "type": "video_url",
+                           "video_url": {"url": f"data:video/mp4;base64,{video_base64}"},
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_base64.choices[0].message.content
+       print("Chat completion output from base64 encoded image:", result)
+   
+   
+   # Audio input inference
+   def run_audio(model: str) -> None:
+       from vllm.assets.audio import AudioAsset
+   
+       audio_url = AudioAsset("winning_call").url
+       audio_base64 = encode_base64_content_from_url(audio_url)
+   
+       # OpenAI-compatible schema (`input_audio`)
+       chat_completion_from_base64 = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this audio?"},
+                       {
+                           "type": "input_audio",
+                           "input_audio": {
+                               # Any format supported by librosa is supported
+                               "data": audio_base64,
+                               "format": "wav",
+                           },
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_base64.choices[0].message.content
+       print("Chat completion output from input audio:", result)
+   
+       # HTTP URL
+       chat_completion_from_url = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this audio?"},
+                       {
+                           "type": "audio_url",
+                           "audio_url": {
+                               # Any format supported by librosa is supported
+                               "url": audio_url
+                           },
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_url.choices[0].message.content
+       print("Chat completion output from audio url:", result)
+   
+       # base64 URL
+       chat_completion_from_base64 = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this audio?"},
+                       {
+                           "type": "audio_url",
+                           "audio_url": {
+                               # Any format supported by librosa is supported
+                               "url": f"data:audio/ogg;base64,{audio_base64}"
+                           },
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_base64.choices[0].message.content
+       print("Chat completion output from base64 encoded audio:", result)
+   
+   
+   example_function_map = {
+       "text-only": run_text_only,
+       "single-image": run_single_image,
+       "multi-image": run_multi_image,
+       "video": run_video,
+       "audio": run_audio,
+   }
+   
+   
+   def parse_args():
+       parser = FlexibleArgumentParser(
+           description="Demo on using OpenAI client for online serving with "
+           "multimodal language models served with vLLM."
+       )
+       parser.add_argument(
+           "--chat-type",
+           "-c",
+           type=str,
+           default="single-image",
+           choices=list(example_function_map.keys()),
+           help="Conversation type with multimodal data.",
+       )
+       return parser.parse_args()
+   
+   
+   def main(args) -> None:
+       chat_type = args.chat_type
+       model = get_first_model(client)
+       example_function_map[chat_type](model)
+   
+   
+   if __name__ == "__main__":
+       args = parse_args()
+       start_time = time.time()
+       main(args)
+       end_time = time.time()
+       print(f"Time taken: {end_time - start_time} seconds")
+
diff --git a/docs/source/api_reference/storage_backends.rst b/docs/source/api_reference/storage_backends.rst
new file mode 100644
index 0000000..6fc4120
--- /dev/null
+++ b/docs/source/api_reference/storage_backends.rst
@@ -0,0 +1,9 @@
+Adding new storage backends
+===========================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+Coming soon... 
\ No newline at end of file
diff --git a/docs/source/assets/InfiniStore-usage.png b/docs/source/assets/InfiniStore-usage.png
new file mode 100644
index 0000000..20f796f
Binary files /dev/null and b/docs/source/assets/InfiniStore-usage.png differ
diff --git a/docs/source/assets/deployment_modes_dark.png b/docs/source/assets/deployment_modes_dark.png
new file mode 100644
index 0000000..9ec05f2
Binary files /dev/null and b/docs/source/assets/deployment_modes_dark.png differ
diff --git a/docs/source/assets/deployment_modes_light.png b/docs/source/assets/deployment_modes_light.png
new file mode 100644
index 0000000..127bd3d
Binary files /dev/null and b/docs/source/assets/deployment_modes_light.png differ
diff --git a/docs/source/assets/ecosystem.png b/docs/source/assets/ecosystem.png
new file mode 100644
index 0000000..146ce57
Binary files /dev/null and b/docs/source/assets/ecosystem.png differ
diff --git a/docs/source/assets/lmcache-controller.png b/docs/source/assets/lmcache-controller.png
new file mode 100644
index 0000000..d8c276b
Binary files /dev/null and b/docs/source/assets/lmcache-controller.png differ
diff --git a/docs/source/assets/lmcache-logo.png b/docs/source/assets/lmcache-logo.png
new file mode 100644
index 0000000..524bffd
Binary files /dev/null and b/docs/source/assets/lmcache-logo.png differ
diff --git a/docs/source/assets/lmcache-logo_crop.png b/docs/source/assets/lmcache-logo_crop.png
new file mode 100644
index 0000000..502de26
Binary files /dev/null and b/docs/source/assets/lmcache-logo_crop.png differ
diff --git a/docs/source/assets/maru-kvcache.png b/docs/source/assets/maru-kvcache.png
new file mode 100644
index 0000000..1372612
Binary files /dev/null and b/docs/source/assets/maru-kvcache.png differ
diff --git a/docs/source/assets/mooncake-store-preview.png b/docs/source/assets/mooncake-store-preview.png
new file mode 100644
index 0000000..afb4c79
Binary files /dev/null and b/docs/source/assets/mooncake-store-preview.png differ
diff --git a/docs/source/cli/bench.rst b/docs/source/cli/bench.rst
new file mode 100644
index 0000000..019f959
--- /dev/null
+++ b/docs/source/cli/bench.rst
@@ -0,0 +1,1382 @@
+.. _lmcache-bench:
+
+lmcache bench
+=============
+
+The ``lmcache bench`` command runs sustained performance benchmarks. It has
+three sub-commands, each targeting a different layer of the stack:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Sub-command
+     - Description
+   * - ``engine``
+     - Benchmark an inference engine (e.g. vLLM) with workloads that
+       exercise different KV-cache reuse patterns.
+   * - ``server``
+     - End-to-end sanity test against a running LMCache MP cache server
+       (ZMQ + HTTP). Requires the full ``lmcache`` install and a GPU.
+   * - ``l2``
+     - Throughput / latency benchmark against an L2 cache adapter
+       (store / lookup / load).
+
+.. code-block:: bash
+
+   lmcache bench {engine,server,l2} [options]
+
+
+.. _lmcache-bench-engine:
+
+engine
+------
+
+The ``lmcache bench engine`` command runs sustained performance benchmarks
+against an inference engine (e.g., vLLM). It supports multiple workload types
+that exercise different caching patterns and reports TTFT, decoding speed, and
+throughput metrics.
+
+.. code-block:: bash
+
+   lmcache bench engine [options]
+
+There are three ways to configure the benchmark:
+
+1. **CLI arguments** -- pass all options on the command line.
+2. **Interactive mode** -- run ``lmcache bench engine`` without required args
+   and follow the step-by-step prompts.
+3. **Config file** -- save a configuration to JSON and replay it with
+   ``--config``.
+
+
+Quick Start
+~~~~~~~~~~~
+
+**Minimal (with all required arguments):**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload long-doc-qa \
+       --lmcache-url http://localhost:8080
+
+**Interactive mode (guided setup):**
+
+.. code-block:: bash
+
+   lmcache bench engine
+
+The interactive mode walks you through each required setting, then asks
+whether you want to configure general and workload-specific options or use
+defaults.
+
+**From a saved config file:**
+
+.. code-block:: bash
+
+   lmcache bench engine --engine-url http://localhost:8000 \
+       --config my_bench.json
+
+Config files contain benchmark parameters (workload, KV cache settings, etc.)
+but not the engine URL, so you can reuse the same config against different
+engines.
+
+**Export a config without running the benchmark:**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload long-doc-qa \
+       --lmcache-url http://localhost:8080 \
+       --export-config my_bench.json
+
+This resolves all auto-detected values (model name, tokens per GB) and saves
+them to a portable JSON file that works without an LMCache server.
+
+**Non-interactive mode (for scripts and CI):**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload long-doc-qa \
+       --lmcache-url http://localhost:8080 \
+       --no-interactive
+
+Errors immediately if any required argument is missing, instead of entering
+interactive mode. Useful in automated pipelines.
+
+If you don't have an LMCache server, you can pass ``--tokens-per-gb-kvcache``
+directly instead of ``--lmcache-url``
+(see :ref:`bench-tokens-per-gb` for how to find this value).
+
+
+General Options
+~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 10 60
+
+   * - Flag
+     - Required
+     - Description
+   * - ``--config FILE``
+     - No
+     - Load configuration from a JSON file. Skips interactive mode.
+       CLI flags override values in the file. The engine URL is not
+       stored in config files and must be provided separately.
+   * - ``--export-config FILE``
+     - No
+     - Export resolved configuration to a JSON file and exit. Does not
+       run the benchmark. Auto-detected values (model, tokens per GB)
+       are resolved and saved so the config is portable. Environment-
+       specific values (engine URL, LMCache URL) are excluded.
+   * - ``--no-interactive``
+     - No
+     - Disable interactive mode. Errors if required arguments are
+       missing instead of prompting. Useful for scripts and CI.
+   * - ``--engine-url URL``
+     - Yes
+     - Inference engine URL (e.g., ``http://localhost:8000``).
+       Set ``OPENAI_API_KEY`` env var if authentication is needed.
+   * - ``--workload TYPE``
+     - Yes
+     - Workload type: ``long-doc-qa``, ``multi-round-chat``,
+       ``long-doc-permutator``, ``prefix-suffix-tuner``, or
+       ``random-prefill``.
+   * - ``--tokens-per-gb-kvcache N``
+     - \*
+     - Tokens per GB of KV cache. Required unless ``--lmcache-url`` is set.
+       See :ref:`bench-tokens-per-gb` for how to find this value.
+   * - ``--lmcache-url URL``
+     - No
+     - LMCache HTTP server URL. When provided, ``--tokens-per-gb-kvcache``
+       is auto-detected from the server.
+   * - ``--model NAME``
+     - No
+     - Model name. Auto-detected from the engine if omitted.
+   * - ``--kv-cache-volume GB``
+     - No
+     - Target active KV cache volume in GB (default: 100).
+   * - ``--seed N``
+     - No
+     - Random seed (default: 42).
+   * - ``--output-dir DIR``
+     - No
+     - Directory for CSV and JSON output files (default: current directory).
+   * - ``--no-csv``
+     - No
+     - Skip CSV export.
+   * - ``--json``
+     - No
+     - Export a JSON summary file.
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress the real-time progress display.
+
+
+.. _bench-tokens-per-gb:
+
+Finding ``--tokens-per-gb-kvcache``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have an LMCache server running, the easiest approach is to pass
+``--lmcache-url`` and let the tool auto-detect the value.
+
+If you are using **vLLM without LMCache**, look for these lines in vLLM's
+startup log:
+
+.. code-block:: text
+
+   INFO: Available KV cache memory: 12.34 GiB
+   INFO: GPU KV cache size: 567,890 tokens
+
+Then compute::
+
+   tokens_per_gb = 567890 / 12.34 = 46,020
+
+
+Workloads
+~~~~~~~~~
+
+long-doc-qa
+^^^^^^^^^^^
+
+Simulates repeated Q&A over long documents. Warmup sends each document once
+to populate the KV cache, then benchmark queries are dispatched with
+semaphore-controlled concurrency.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 10 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--ldqa-document-length``
+     - 10000
+     - Token length of each synthetic document.
+   * - ``--ldqa-query-per-document``
+     - 2
+     - Number of questions asked per document.
+   * - ``--ldqa-shuffle-policy``
+     - random
+     - Request ordering: ``random`` (shuffled) or ``tile`` (round-by-round).
+   * - ``--ldqa-num-inflight-requests``
+     - 3
+     - Maximum concurrent in-flight requests.
+
+**Example:**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload long-doc-qa \
+       --lmcache-url http://localhost:8080 \
+       --kv-cache-volume 50 \
+       --ldqa-document-length 8000 \
+       --ldqa-query-per-document 4 \
+       --ldqa-shuffle-policy tile
+
+
+multi-round-chat
+^^^^^^^^^^^^^^^^
+
+Simulates multi-round chat with stateful sessions. Creates concurrent user
+sessions, dispatches requests at a fixed QPS rate, and records responses in
+session history so each subsequent query includes prior context.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 10 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--mrc-shared-prompt-length``
+     - 2000
+     - System prompt token length per session.
+   * - ``--mrc-chat-history-length``
+     - 10000
+     - Pre-filled chat history token length.
+   * - ``--mrc-user-input-length``
+     - 50
+     - Tokens per user query.
+   * - ``--mrc-output-length``
+     - 200
+     - Max tokens to generate per response.
+   * - ``--mrc-qps``
+     - 1.0
+     - Target queries per second.
+   * - ``--mrc-duration``
+     - 60.0
+     - Benchmark duration in seconds.
+
+**Example:**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload multi-round-chat \
+       --lmcache-url http://localhost:8080 \
+       --mrc-qps 2.0 \
+       --mrc-duration 120
+
+
+long-doc-permutator
+^^^^^^^^^^^^^^^^^^^
+
+Stress-tests blended KV cache reuse by sending permutations of a set of context
+documents. Each request concatenates all context documents in a different order:
+
+.. code-block:: text
+
+   [System Prompt] + [Doc_i1] + [Doc_i2] + ... + [Doc_iN]
+
+A single dummy warmup request is sent before the benchmark phase. Requests are
+dispatched with semaphore-controlled concurrency.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 10 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--ldp-num-contexts``
+     - 5
+     - Number of unique context documents.
+   * - ``--ldp-context-length``
+     - 5000
+     - Token length of each context document.
+   * - ``--ldp-system-prompt-length``
+     - 1000
+     - Token length of the shared system prompt. Use ``0`` for no system prompt.
+   * - ``--ldp-num-permutations``
+     - 10
+     - Number of distinct permutations to send. Capped at N! where
+       N = ``--ldp-num-contexts``.
+   * - ``--ldp-num-inflight-requests``
+     - 1
+     - Maximum concurrent in-flight requests.
+
+**Example:**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload long-doc-permutator \
+       --lmcache-url http://localhost:8080 \
+       --ldp-num-contexts 4 \
+       --ldp-context-length 8000 \
+       --ldp-num-permutations 24 \
+       --ldp-num-inflight-requests 2
+
+
+prefix-suffix-tuner
+^^^^^^^^^^^^^^^^^^^
+
+A two-pass sequential workload designed to be run **unchanged** across
+three LMCache configurations to demonstrate the value of each cache tier
+(L0 HBM, L1 DRAM, L2 disk):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 25 30 30
+
+   * - Baseline
+     - LMCache config
+     - Targeted overflow
+     - Expected pass-2 hits
+   * - 1
+     - vanilla vLLM (L0 only)
+     - L0 (HBM)
+     - none -- every request a cold prefill
+   * - 2
+     - vLLM + LMCache L1 + L2
+     - L1 (DRAM)
+     - L2 prefix hits (suffix recomputed)
+   * - 3
+     - vLLM + LMCache L1 + L2 + CacheBlend
+     - L1 (DRAM)
+     - L2 prefix hits + CacheBlend suffix hits
+
+Set ``--kv-cache-volume`` to the size in GB of the tier you want to overflow
+(L0 size for Baseline 1, L1 size for Baselines 2 and 3). The workload itself
+is identical across baselines.
+
+Each request has the layout::
+
+   [prefix_i with unique-ID][random breaker][shared suffix]
+
+- ``num_prefixes`` distinct prefixes, each starting with ``PREFIX_<8-hex>``
+  so the prefix's tokenized hash differs across the pool.
+- A fresh random 32-token breaker per request, defeating ordinary prefix
+  caching past the prefix boundary.
+- A single shared suffix used by every request -- the only entry CacheBlend
+  can reuse.
+
+Pass 1 (warmup) sends each prefix once to populate the cache; its stats are
+discarded. Pass 2 sends them again in identical order. Because LRU evicts
+the next-needed prefix on each pass-2 access, even a 1.05x overflow of the
+targeted tier is enough to make every pass-2 request miss that tier and
+fall through to the next one.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 10 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--psf-context-length``
+     - 8000
+     - Total tokens per request (prefix + breaker + suffix).
+   * - ``--psf-prefix-ratio``
+     - 0.8
+     - Fraction of context-length used by the prefix. Must be in (0.0, 1.0).
+       The remainder (minus a 32-token breaker) is the shared suffix.
+   * - ``--psf-thrash``
+     - 20.0
+     - **Size in GB of the KV-cache tier to overflow.** Use the L0 (HBM)
+       size for vanilla vLLM, or the L1 (LMCache DRAM) size for tiered
+       baselines. The workload sizes its prefix pool to slightly more than
+       this (5% overflow internally), enough to drive every pass-2 request
+       to a miss of that tier under sequential dispatch + LRU.
+
+The number of pass-2 (measured) requests equals the prefix pool size,
+computed as
+``floor(psf_thrash * 1.05 * tokens_per_gb / prefix_tokens)``.
+``--kv-cache-volume`` is unused by this workload — sizing is driven solely
+by ``--psf-thrash``.
+
+**Example:**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload prefix-suffix-tuner \
+       --lmcache-url http://localhost:8080 \
+       --psf-context-length 8000 \
+       --psf-prefix-ratio 0.8 \
+       --psf-thrash 100
+
+.. note::
+   For the analytical-model claim "thrash ≈ L1 size → ~0% LMCache hit rate"
+   to hold empirically, the LMCache server must be started with
+   ``--eviction-ratio 0.99`` (default ``0.20`` only clears 20% per cycle,
+   leaving ~60% of pass-1 content in cache through pass 2):
+
+   .. code-block:: bash
+
+      lmcache server --l1-size-gb <SIZE> --eviction-policy LRU \
+          --eviction-trigger-watermark 0.80 \
+          --eviction-ratio 0.99
+
+   The workload itself sleeps 5 seconds between pass 1 (warmup) and pass 2
+   (measured), so LMCache's 1Hz batched-eviction polling thread has time
+   to actually run.  Without that sleep, fast benchmarks complete before
+   any eviction fires.
+
+
+random-prefill
+^^^^^^^^^^^^^^
+
+Fires all requests simultaneously with ``max_tokens=1`` to measure pure
+prefill performance. No warmup phase.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 10 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--rp-request-length``
+     - 10000
+     - Token length per prefill request.
+   * - ``--rp-num-requests``
+     - 50
+     - Number of requests to fire.
+
+**Example:**
+
+.. code-block:: bash
+
+   lmcache bench engine \
+       --engine-url http://localhost:8000 \
+       --workload random-prefill \
+       --lmcache-url http://localhost:8080 \
+       --rp-request-length 15000 \
+       --rp-num-requests 100
+
+
+Interactive Mode
+~~~~~~~~~~~~~~~~
+
+.. image:: /_static/bench_interactive_demo.gif
+   :alt: Interactive mode demo
+   :width: 100%
+
+When ``--engine-url`` or ``--workload`` is not provided (and
+``--no-interactive`` is not set), the tool enters interactive mode. It guides
+you through four phases:
+
+1. **Required settings** -- engine URL, workload type, LMCache server
+   (or tokens per GB).
+2. **General settings** (optional gate) -- model name, KV cache volume.
+3. **Workload settings** (optional gate) -- workload-specific parameters.
+4. **Summary and action** -- review configuration, then start the benchmark
+   or export to a JSON file.
+
+Each prompt focuses on a single setting. Selection prompts use arrow keys;
+text and number prompts accept typed input with defaults shown in brackets.
+
+.. code-block:: text
+
+   ══════════════════════════════════════════════════
+    lmcache bench engine -- Interactive Setup
+   ══════════════════════════════════════════════════
+
+   Engine URL
+     URL of the inference engine.
+     [default: http://localhost:8000] >
+
+   Workload
+     The type of benchmark workload to run.
+     Use up/down to navigate, Enter to select.
+
+     * long-doc-qa           Repeated Q&A over long documents
+       multi-round-chat       Multi-turn chat with stateful sessions
+       long-doc-permutator    Permutations of context documents
+       prefix-suffix-tuner    Two-pass tiered KV-cache demonstrator
+       random-prefill         Prefill-only requests fired simultaneously
+
+   LMCache Server
+     Do you have a running LMCache server?
+     It can auto-detect KV cache size information.
+     [default: Y] (Y/n) >
+
+   ...
+
+   ──────────────────────────────────────────────────
+    Configuration Summary
+   ──────────────────────────────────────────────────
+     Workload:             long-doc-qa
+     Model:                Qwen/Qwen3-14B
+     Tokens per GB:        6553
+     ...
+   ──────────────────────────────────────────────────
+
+   What would you like to do?
+     * Start benchmark
+       Export configuration for later use and exit
+
+When you choose "Export configuration", all auto-detected values (model name,
+tokens per GB) are resolved and saved to a portable JSON file.
+
+
+Config File
+~~~~~~~~~~~
+
+Config files store benchmark parameters but **not** environment-specific
+values like engine URL or LMCache URL. This lets you reuse the same config
+across different environments.
+
+You can create a config file in three ways:
+
+1. **Interactive mode** -- choose "Export configuration" at the summary step.
+2. **``--export-config``** -- resolve and export from CLI without running.
+3. **Manually** -- write JSON with keys matching CLI arg names (dashes
+   replaced by underscores).
+
+Example config file:
+
+.. code-block:: json
+
+   {
+     "model": "Qwen/Qwen3-14B",
+     "workload": "long-doc-qa",
+     "tokens_per_gb_kvcache": 6553,
+     "kv_cache_volume": 100.0,
+     "ldqa_document_length": 10000,
+     "ldqa_query_per_document": 2,
+     "ldqa_shuffle_policy": "random",
+     "ldqa_num_inflight_requests": 3
+   }
+
+Load it with ``--config`` (engine URL must be provided separately):
+
+.. code-block:: bash
+
+   lmcache bench engine --engine-url http://localhost:8000 \
+       --config my_bench.json
+
+CLI arguments override config file values, so you can use a base config and
+tweak individual settings:
+
+.. code-block:: bash
+
+   # Use saved config but override KV cache volume
+   lmcache bench engine --engine-url http://localhost:8000 \
+       --config my_bench.json --kv-cache-volume 200
+
+
+Output
+~~~~~~
+
+Terminal (real-time progress)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+During the benchmark, a live progress display shows in-flight requests,
+average TTFT, decode speed, and throughput. Suppress it with ``-q``.
+
+Terminal (final summary)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+After completion, a summary table is printed:
+
+.. code-block:: text
+
+   ======= Engine Benchmark Result (long-doc-qa) ========
+   ---------------------- Configuration ------------------
+   Engine URL:                       http://localhost:8000
+   Model:                            Qwen/Qwen3-14B
+   Workload:                         long-doc-qa
+   ------------------------- Results ---------------------
+   Successful requests:              20
+   Failed requests:                  0
+   Benchmark duration (s):           31.34
+   Total input tokens:               200000
+   Total output tokens:              2560
+   Input throughput (tok/s):         6381.62
+   Output throughput (tok/s):        81.69
+   --------------- Time to First Token -------------------
+   Mean TTFT (ms):                   313.41
+   P50 TTFT (ms):                    272.83
+   P90 TTFT (ms):                    587.21
+   P99 TTFT (ms):                    837.32
+   ------------------ Decoding Speed ---------------------
+   Mean decode (tok/s):              48.23
+   P99 decode (tok/s):               38.55
+   ======================================================
+
+CSV and JSON
+^^^^^^^^^^^^
+
+- ``bench_results.csv`` -- per-request metrics (TTFT, latency, decode speed,
+  token counts). Written by default; skip with ``--no-csv``.
+- ``bench_summary.json`` -- aggregate statistics with percentiles and config
+  metadata. Opt-in with ``--json``.
+
+Both files are written to ``--output-dir`` (default: current directory).
+
+
+Exit Codes
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Code
+     - Meaning
+   * - ``0``
+     - All requests succeeded.
+   * - ``1``
+     - One or more requests failed.
+
+
+.. _lmcache-bench-server:
+
+server
+------
+
+The ``lmcache bench server`` command is an end-to-end sanity test for the
+LMCache Multi-Process (MP) cache server. It connects to a running server
+over ZMQ and exercises the full KV-cache data path for a sequence of
+synthetic requests, then optionally verifies per-chunk checksums through
+the HTTP API.
+
+.. code-block:: bash
+
+   lmcache bench server [options]
+
+Unlike :ref:`lmcache bench engine <lmcache-bench-engine>`, this command does
+**not** require an inference engine. It only needs a running LMCache MP
+server (ZMQ + HTTP). GPU mode additionally requires a CUDA-capable device.
+It also requires the full ``lmcache`` install (not the lightweight
+``lmcache-cli`` package).
+
+
+What it does
+~~~~~~~~~~~~
+
+For each sequence in ``[--start, --end)``, the tool runs two passes:
+
+1. **Cold pass** -- ``LOOKUP`` is expected to miss, so the generated KV
+   tensors are ``STORE``\ d on the server.
+2. **Warm pass** -- ``LOOKUP`` is expected to hit; the tool issues
+   ``RETRIEVE`` and compares the retrieved KV chunks' checksums to the
+   originals.
+
+The full RPC path exercised is::
+
+   REGISTER_KV_CACHE → GET_CHUNK_SIZE → LOOKUP
+     → QUERY_PREFETCH_STATUS → RETRIEVE → STORE
+     → END_SESSION
+
+When ``--url`` points to the server's HTTP endpoint, per-chunk checksums
+are additionally cross-checked against the server-side computation, so a
+mismatch between producer and consumer surfaces as a loud
+``CHECKSUM MISMATCH`` log line.
+
+
+Quick start
+~~~~~~~~~~~
+
+Start the MP server in one terminal:
+
+.. code-block:: bash
+
+   lmcache server \
+       --host localhost --port 15556 \
+       --chunk-size 256 --l1-size-gb 5 \
+       --eviction-policy LRU --max-workers 1
+
+Then in another terminal:
+
+.. code-block:: bash
+
+   lmcache bench server \
+       --rpc-url tcp://localhost:15556 \
+       --url http://localhost:8080
+
+By default the tool runs forever (``--end`` unset); stop it with
+``Ctrl-C`` at any time. Pass ``--end N`` for a bounded run.
+
+
+Options
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--rpc-url URL``
+     - ``tcp://localhost:5555``
+     - ZMQ endpoint of the MP cache server.
+   * - ``--url URL``
+     - ``http://localhost:8080``
+     - HTTP base URL of the server's checksum API. Used to
+       verify per-chunk checksums end-to-end.
+   * - ``--mode {gpu,cpu}``
+     - ``gpu``
+     - Run mode. ``gpu`` allocates real CUDA tensors and uses CUDA IPC
+       (lmcache-driven handle path). ``cpu`` allocates POSIX-SHM-backed tensors
+       and uses the engine-driven (worker-side gather/scatter) path by default.
+   * - ``--transfer-mode {auto,engine_driven,lmcache_driven}``
+     - ``auto``
+     - Transport routing for STORE/RETRIEVE. ``lmcache_driven`` forces the
+       single-shot handle path (``REGISTER_KV_CACHE`` + ``STORE``/``RETRIEVE``),
+       which supports both CUDA IPC and CPU SHM zero-copy transfers.
+       ``engine_driven`` forces the worker-side gather/scatter path
+       (``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT`` + ``PREPARE``/``COMMIT``).
+       ``auto`` maps gpu→lmcache_driven and cpu→engine_driven.
+   * - ``--num-tokens N``
+     - ``512``
+     - Tokens per synthetic request.
+   * - ``--num-blocks N``
+     - ``1024``
+     - Number of paged blocks allocated on the GPU.
+   * - ``--block-size N``
+     - ``16``
+     - Tokens per paged block.
+   * - ``--start N``
+     - ``0``
+     - First sequence number to run.
+   * - ``--end N``
+     - *(unset)*
+     - Exclusive upper bound on sequence numbers. When omitted the
+       loop runs forever.
+   * - ``--interval SECS``
+     - ``0.5``
+     - Delay between successive sub-passes.
+   * - ``--kvcache-shape-spec SPEC``
+     - ``(2,1024,16,8,128):float16:32``
+     - KV cache shape spec (see below).
+   * - ``--format FORMAT``
+     - ``terminal``
+     - Stdout output format for the final metrics summary. Available:
+       ``terminal``, ``json``.
+   * - ``--output PATH``
+     - *(unset)*
+     - Save the final metrics summary to a file at PATH (format chosen
+       by ``--format``).
+   * - ``-q`` / ``--quiet``
+     - *(unset)*
+     - Suppress all progress messages during the run. Only the final
+       structured metrics summary is emitted (unless also redirected
+       via ``--output``).
+
+
+CPU mode (no GPU)
+~~~~~~~~~~~~~~~~~
+
+``--mode cpu`` runs the same end-to-end path without a GPU. The server
+runs on a CPU-only host (``StubCPUDevice``); the bench tool allocates
+POSIX-SHM-backed KV tensors and exercises the full RPC path.
+
+By default ``--mode cpu`` uses the engine-driven gather/scatter path
+(``auto`` → ``cpu→engine_driven``). To use the zero-copy SHM
+handle path instead, pass ``--transfer-mode lmcache_driven``:
+
+.. code-block:: bash
+
+   # Terminal 1 -- start the LMCache server (no GPU required)
+   lmcache server \
+       --host localhost --port 5555 \
+       --l1-size-gb 2 --eviction-policy LRU
+
+   # Terminal 2 -- run bench in CPU + lmcache_driven mode
+   lmcache bench server \
+       --rpc-url tcp://localhost:5555 \
+       --url http://localhost:8080 \
+       --mode cpu --transfer-mode lmcache_driven \
+       --start 0 --end 2
+
+
+KV cache shape spec
+~~~~~~~~~~~~~~~~~~~
+
+The ``--kvcache-shape-spec`` flag describes how KV tensors are laid out on
+the GPU. A spec is one or more groups separated by ``;``:
+
+.. code-block:: text
+
+   (kv_size,NB,BS,NH,HS):dtype:layers[;(...):dtype:layers...]
+
+Fields:
+
+* ``kv_size`` -- 2 for classical attention (separate K/V), 1 for MLA.
+* ``NB`` -- number of paged blocks.
+* ``BS`` -- block size (tokens per block).
+* ``NH`` -- number of attention heads per layer.
+* ``HS`` -- head size (in elements).
+* ``dtype`` -- element dtype (e.g. ``float16``, ``bfloat16``, ``float32``,
+  ``uint8``). The full set matches the keys of ``DTYPE_MAP`` in
+  ``lmcache/v1/kv_layer_groups.py``.
+* ``layers`` -- number of layers in this group.
+
+Multi-group specs let you model heterogeneous layers (for example, MLA
+layers + classical attention layers in the same model):
+
+.. code-block:: bash
+
+   lmcache bench server \
+       --rpc-url tcp://localhost:15556 \
+       --kvcache-shape-spec "(1,1024,16,1,128):float16:4;(2,1024,16,8,128):float16:28"
+
+All groups must share the same ``NB`` and ``BS`` (this is a physical
+constraint of paged KV). Layer counts across groups sum to the total
+layer count registered with the server.
+
+See ``parse_kvcache_shape_spec`` in ``lmcache/v1/kv_layer_groups.py``
+for the authoritative parsing rules and validation errors.
+
+
+Output
+~~~~~~
+
+After the run completes (or is interrupted with ``Ctrl-C``), a structured
+metrics summary is printed. The summary includes:
+
+* **Configuration** -- RPC URL, mode, transfer mode, tokens per request,
+  interval.
+* **Results** -- total requests, checksum OK / FAIL counts, pass rate.
+* **Latency sections** -- per-operation latency statistics (count, mean,
+  min, max, p50, p99) for cold lookup, cold store, warm lookup, and warm
+  retrieve.
+
+Use ``--format json`` to get machine-readable output, or ``--output FILE``
+to save the summary to a file.
+
+.. code-block:: text
+
+   ================ Server Bench Result =================
+   ---------------------- Configuration -----------------
+   RPC URL:                          tcp://localhost:15556
+   Mode:                             gpu
+   Transfer mode:                    auto
+   Tokens / request:                 512
+   Interval (s):                     0.5
+   ------------------------- Results --------------------
+   Total requests:                   3
+   Checksum OK:                      3
+   Checksum FAIL:                    0
+   Pass rate (%):                    100.0
+   -------------------- Cold Lookup (ms) ---------------
+   count:                            3
+   mean:                             1.647
+   min:                              1.312
+   max:                              1.823
+   p50:                              1.647
+   p99:                              1.823
+   --------------------- Cold Store (ms) ---------------
+   count:                            3
+   mean:                             1.740
+   min:                              1.521
+   max:                              1.982
+   p50:                              1.740
+   p99:                              1.982
+   -------------------- Warm Lookup (ms) ---------------
+   count:                            3
+   mean:                             1.310
+   min:                              1.102
+   max:                              1.512
+   p50:                              1.310
+   p99:                              1.512
+   ------------------- Warm Retrieve (ms) --------------
+   count:                            3
+   mean:                             1.480
+   min:                              1.321
+   max:                              1.612
+   p50:                              1.480
+   p99:                              1.612
+   =====================================================
+
+
+Example output (progress)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+During the run, progress messages are printed to stdout (suppressed by
+``-q`` / ``--quiet``):
+
+.. code-block:: text
+
+   Connecting to LMCache MP Server at tcp://localhost:15556 (mode=gpu) ...
+   Server chunk_size = 256
+   Resolved KV shape spec: (2,1024,16,8,128):float16:32
+   [seq=0] LOOKUP cold:  0/2 chunks hit (1.82 ms)
+   [seq=0] STORE:        2 chunks stored (1.74 ms)
+   [seq=0] LOOKUP warm:  2/2 chunks hit (1.31 ms)
+   [seq=0] RETRIEVE:     2 chunks retrieved (1.48 ms)
+   [seq=0] CHECKSUM MATCH OK
+   [seq=1] ...
+
+Any ``CHECKSUM MISMATCH``, ``ERROR``, or Python traceback in the log
+indicates a real problem worth investigating.
+
+
+Exit codes
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Code
+     - Meaning
+   * - ``0``
+     - Test loop completed (or was interrupted cleanly with Ctrl-C)
+       with no checksum mismatches.
+   * - ``1``
+     - Fatal error (for example, CUDA unavailable in ``--mode gpu``,
+       server unreachable, or a checksum mismatch).
+
+.. _lmcache-bench-l2:
+
+l2
+--
+
+The ``lmcache bench l2`` command benchmarks an L2 cache adapter
+(e.g. the local-filesystem adapter) end-to-end through the same
+``parse_args_to_l2_adapters_config`` + ``create_l2_adapter`` pipeline that
+LMCache uses in production. Any registered adapter type can be tested
+without code changes: you describe the adapter with a single JSON spec
+and pick the operations to exercise.
+
+.. code-block:: bash
+
+   lmcache bench l2 [options]
+
+Unlike :ref:`lmcache bench engine <lmcache-bench-engine>`, this command
+does **not** require an inference engine or an LMCache MP server. It
+only needs the adapter's own backing storage to be reachable (for the
+``fs`` adapter, that simply means a writable directory).
+
+
+What it does
+~~~~~~~~~~~~
+
+For each measured operation the tool drives the adapter directly via
+its public submit/wait API:
+
+* ``Store``  -- ``submit_store_task`` writes ``num_keys`` MemoryObjs per
+  submit and waits for the store eventfd.
+* ``Lookup`` -- ``submit_lookup_and_lock_task`` checks key existence
+  (no payload transfer) and waits for the lookup eventfd.
+* ``Load``   -- ``submit_load_task`` reads ``num_keys`` MemoryObjs per
+  submit and waits for the load eventfd.
+
+Each measured **round** issues ``--in-flight`` submits sequentially from
+a single producer thread and then waits for all of them to complete; the
+round duration is the wall-clock time from the first submit until the
+last completion. Warmup rounds run before measurement and their results
+are discarded from the final summary.
+
+All three operations share the same key idx universe, so running
+``--only store`` followed by ``--only load`` (or ``--only lookup``) with
+identical other flags hits exactly the same keys. This makes the
+benchmark useful as a quick regression test for adapters that should
+support a clean store -> load round-trip.
+
+.. note::
+
+   When ``--only`` is not given, the three operations are run **in a
+   single process in the order** ``store -> lookup -> load``. For
+   adapters whose backing storage sits behind an OS-level cache --
+   most notably the local-filesystem (``fs``) adapter, which is
+   subject to the Linux **page cache** -- this means ``lookup`` and
+   ``load`` will almost always observe the data that ``store`` just
+   wrote still hot in RAM, and the reported numbers reflect
+   page-cache throughput rather than the underlying device.
+
+   To benchmark each operation against a cold cache, run them
+   separately with ``--only`` and drop the OS caches in between, for
+   example::
+
+      lmcache bench l2 --l2-adapter '...' --only store
+      sync && echo 3 | sudo tee /proc/sys/vm/drop_caches
+      lmcache bench l2 --l2-adapter '...' --only lookup
+      sync && echo 3 | sudo tee /proc/sys/vm/drop_caches
+      lmcache bench l2 --l2-adapter '...' --only load
+
+   For adapters that bypass the page cache (e.g. ``fs`` with
+   ``"use_odirect": true``) or that talk to a remote service without
+   a local cache, the default combined run is usually fine.
+
+   O_DIRECT adapters may also require the benchmark L1 buffer to
+   satisfy the adapter's block alignment. Use ``--l1-align-bytes`` to
+   set that alignment, commonly ``4096`` for local block devices. The
+   payload size (``--data-size-kb * 1024``) must be a multiple of the
+   selected alignment.
+
+
+Quick start
+~~~~~~~~~~~
+
+Benchmark the local filesystem adapter with default parameters:
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"fs","base_path":"/tmp/lmcache-bench"}'
+
+This runs all three operations (store, lookup, load) with one warmup
+round and one measurement round.
+
+Stress the adapter with more in-flight submits and larger payloads:
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"fs","base_path":"/data/lmcache-bench","relative_tmp_dir":"tmp"}' \
+       --num-keys 32 --in-flight 4 \
+       --data-size-kb 512 \
+       --rounds 5 --warmup-rounds 1
+
+Benchmark an O_DIRECT adapter with aligned L1 buffers:
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"raw_block","device_path":"/dev/nvme0n1","slot_bytes":4194304,"use_odirect":true,"block_align":4096}' \
+       --data-size-kb 1024 \
+       --l1-align-bytes 4096
+
+Run only one operation (useful to isolate store vs. load throughput):
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"fs","base_path":"/tmp/lmcache-bench"}' \
+       --only store
+
+Lookup with a controlled hit rate (the benchmark splits the lookup keys
+between a potentially-existing range and a guaranteed-non-existent
+range):
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"fs","base_path":"/tmp/lmcache-bench"}' \
+       --only lookup --lookup-max-hit-rate 0.5
+
+Enable a store -> load round-trip data integrity check on the last
+measured round:
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"fs","base_path":"/tmp/lmcache-bench"}' \
+       --no-skip-verify
+
+If you prefer to keep the JSON spec out of the command line, set the
+``L2_ADAPTER_JSON`` environment variable instead of passing
+``--l2-adapter``:
+
+.. code-block:: bash
+
+   export L2_ADAPTER_JSON='{"type":"fs","base_path":"/tmp/lmcache-bench"}'
+   lmcache bench l2 --num-keys 32 --in-flight 2
+
+
+Options
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--l2-adapter JSON``
+     - *(unset)*
+     - L2 adapter spec as JSON with a ``"type"`` field plus
+       adapter-specific configs, e.g.
+       ``'{"type":"fs","base_path":"/tmp/bench"}'``. May be passed
+       multiple times; only the first spec is benchmarked. If not
+       provided, falls back to the ``L2_ADAPTER_JSON`` environment
+       variable. Either the flag or the env var is **required**.
+   * - ``--num-keys N``
+     - ``32``
+     - Number of keys per submit.
+   * - ``--in-flight N``
+     - ``1``
+     - In-flight submits per round. Each round issues this many
+       submits sequentially from a single producer thread, then waits
+       for all of them.
+   * - ``--data-size-kb N``
+     - ``256``
+     - Data size per key, in KiB.
+   * - ``--l1-align-bytes N``
+     - ``1``
+     - Alignment in bytes for benchmark L1 buffers. Use a value
+       at least as large as the adapter's block alignment when
+       benchmarking O_DIRECT backends, for example ``4096`` for local
+       block devices. ``--data-size-kb * 1024`` must be a multiple of
+       this value.
+   * - ``--rounds N``
+     - ``1``
+     - Measurement rounds per operation.
+   * - ``--warmup-rounds N``
+     - ``1``
+     - Warmup rounds run before measurement; their results are
+       discarded.
+   * - ``--lookup-max-hit-rate F``
+     - ``0.0``
+     - Upper bound on the lookup hit rate, in ``[0, 1]``. The benchmark
+       requests ``floor(N * rate)`` keys from the
+       potentially-existing range and ``N - hit`` keys from a
+       guaranteed-non-existent range, where ``N`` is the total number
+       of lookup keys. The actual hit rate may be lower if those keys
+       were never stored in this run.
+   * - ``--skip-verify`` / ``--no-skip-verify``
+     - ``--skip-verify``
+     - Skip the store -> load round-trip data integrity check (the
+       default). Pass ``--no-skip-verify`` to enable verification on
+       the last measured round; this requires both ``store`` and
+       ``load`` to be exercised.
+   * - ``--only {lookup,store,load}``
+     - *(unset)*
+     - Run only the specified operation. When omitted, all three
+       operations are run in the order ``store -> lookup -> load``.
+   * - ``--flamegraph {on,off}``
+     - ``off``
+     - Capture a flame graph of the measured phases (``on``) or run the
+       benchmark normally (``off``). When ``on``, the benchmark profiles
+       itself and renders an SVG. Default ``off`` leaves benchmark
+       behavior unchanged. See
+       :ref:`Profiling / flame charts <lmcache-bench-l2-profiling>`.
+   * - ``--flamegraph-mode {on-cpu,off-cpu}``
+     - ``on-cpu``
+     - Flame-graph mode for ``--flamegraph on``. ``on-cpu`` shows
+       where CPU time goes; ``off-cpu`` shows time blocked on I/O /
+       locks (best for I/O-bound adapters).
+   * - ``--flamegraph-output PATH``
+     - *(auto)*
+     - SVG output path. Default:
+       ``/tmp/lmcache_bench_flames/<adapter>.<mode>.svg``.
+   * - ``--flamegraph-dir DIR``
+     - *($FLAMEGRAPH_DIR or ~/FlameGraph)*
+     - Directory with the FlameGraph scripts (``flamegraph.pl``,
+       ``stackcollapse-perf.pl``).
+
+
+Adapter JSON spec
+~~~~~~~~~~~~~~~~~
+
+The ``--l2-adapter`` JSON is parsed by
+``lmcache.v1.distributed.l2_adapters.config.parse_args_to_l2_adapters_config``,
+the same entry point LMCache uses everywhere else. The minimum required
+field is ``type``; all remaining fields are forwarded to the adapter
+implementation as keyword arguments.
+
+Example for the local-filesystem adapter:
+
+.. code-block:: json
+
+   {
+     "type": "fs",
+     "base_path": "/data/lmcache-bench",
+     "relative_tmp_dir": "tmp",
+     "read_ahead_size": null,
+     "use_odirect": false
+   }
+
+See the source under ``lmcache/v1/distributed/l2_adapters/`` for the
+full list of adapter types and their accepted fields.
+
+
+Example output
+~~~~~~~~~~~~~~
+
+Per-round progress (suppressed by ``-q``):
+
+.. code-block:: text
+
+   ============================================================
+   L2 Adapter Benchmark
+   ============================================================
+     Adapter config         : FSL2AdapterConfig
+     L2 adapter JSON        : {"type":"fs","base_path":"/data/lmcache-bench","relative_tmp_dir":"tmp"}
+     Keys / submit          : 32
+     In-flight / round      : 3
+     Keys / round           : 96
+     Data size / key        : 256 KB
+     Data / round           : 24.00 MB
+     Rounds                 : 1 (+ 1 warmup)
+     Lookup max hit rate    : 0.00%
+   ============================================================
+
+   [Init] Creating adapter...
+   [Init] Adapter created successfully (FSL2Adapter).
+
+   [Store] Running 1 warmup + 1 measurement rounds...
+     [Store] Round 1: 47.83 ms, success_keys=96/96
+     [Store] Round 2: 46.19 ms, success_keys=96/96
+
+   [Lookup] Running 1 warmup + 1 measurement rounds...
+     [Lookup] Round 1:  5.36 ms, found=96/96
+     [Lookup] Round 2:  5.03 ms, found=96/96
+
+   [Load] Running 1 warmup + 1 measurement rounds...
+     [Load] Round 1: 18.15 ms, loaded=96/96
+     [Load] Round 2: 17.63 ms, loaded=96/96
+
+Final summary (one section per exercised operation):
+
+.. code-block:: text
+
+   ====== L2 Adapter Benchmark Result (FSL2Adapter) =======
+   ----------------------- Configuration -------------------
+   Adapter:                          FSL2Adapter
+   Keys / submit:                    32
+   In-flight / round:                3
+   Data size / key (KB):             256
+   Measurement rounds:               1
+   Warmup rounds:                    1
+   Lookup max hit rate:              0.0
+   --------------------------- Store -----------------------
+   Operation:                        Store
+   Rounds:                           1
+   Keys / round:                     96
+   Total keys:                       96
+   Total success:                    96
+   Duration avg (ms):                46.19
+   ...
+   Throughput avg (MB/s):            519.62
+   Avg ops/s:                        2078.50
+   Avg latency / key (ms):           0.481
+   --------------------------- Lookup ----------------------
+   ...
+   ---------------------------- Load -----------------------
+   ...
+   =========================================================
+
+Each operation section reports per-round duration statistics
+(avg / min / max / p50 / p99 / std), aggregate throughput
+(``avg_throughput_mbps`` -- 0 for ``Lookup`` since it has no payload),
+average key-rate (``avg_ops_per_sec``), and a per-key latency.
+
+For ``Lookup``, three additional fields are reported when
+``--lookup-max-hit-rate`` is non-zero or some keys were found:
+
+* ``Expected max hit rate`` -- the configured upper bound.
+* ``Expected hit keys`` -- ``floor(total_keys * rate)``, scaled for
+  the measured rounds only.
+* ``Actual hit rate`` -- the measured hit rate over the kept rounds.
+
+
+Round-trip verification
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``--no-skip-verify`` is passed and both ``store`` and ``load`` were
+run, the benchmark compares the load buffers from the last measured
+round against the byte pattern that ``store`` wrote (see
+``make_memory_objects`` in
+``lmcache/cli/commands/bench/l2_adapter_bench/data.py``):
+
+.. code-block:: text
+
+   [Verify] Checking store -> load data integrity for last measured round...
+   [Verify] OK
+
+Verification is **off** by default because the stricter byte pattern
+requires both the store and load object batches to stay resident so the
+loaded data can be compared against the original store pattern.
+
+
+.. _lmcache-bench-l2-profiling:
+
+Profiling / flame charts
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``--flamegraph on`` is passed, the benchmark profiles the L2
+adapter's performance and renders a flame graph of the measured phases:
+
+.. code-block:: bash
+
+   lmcache bench l2 \
+       --l2-adapter '{"type":"fs","base_path":"/data/lmcache-bench"}' \
+       --rounds 300 --flamegraph on --flamegraph-mode on-cpu
+   #   [Profile] on-cpu recording started (pid=12345) -> .../FSL2Adapter.oncpu.svg
+   #   [Profile] wrote /tmp/lmcache_bench_flames/FSL2Adapter.oncpu.svg
+
+The recorder samples every thread of the process (including native
+worker threads). Two modes are available via ``--flamegraph-mode``:
+
+* **on-cpu** (default) -- ``perf record``; where CPU cycles go
+  (serialization, copies, hashing).
+* **off-cpu** -- ``offcputime-bpfcc`` (bcc); time spent blocked
+  (waiting on I/O, locks, eventfds). Often the more informative view
+  for I/O-bound adapters such as ``fs`` and ``s3``.
+
+Recording covers only the measured store/lookup/load work, so make the
+run long enough to collect samples (a few seconds is plenty -- use a
+large ``--rounds``). The SVG is written to ``--flamegraph-output``
+(default ``/tmp/lmcache_bench_flames/<adapter>.<mode>.svg``).
+
+**Requirements.** Rendering needs Brendan Gregg's
+`FlameGraph <https://github.com/brendangregg/FlameGraph>`__ scripts
+(``--flamegraph-dir`` or ``FLAMEGRAPH_DIR``, default ``~/FlameGraph``;
+auto-cloned to a temp directory when absent). ``on-cpu`` needs ``perf``
+(and ``kernel.perf_event_paranoid`` low enough to profile non-root, or
+run as root); ``off-cpu`` needs ``bcc`` (``offcputime-bpfcc``) and
+``sudo``. The required tools are checked up front: when ``--flamegraph
+on`` is requested but a tool is missing, the benchmark exits with a
+non-zero status and an actionable message naming the missing tool
+instead of running unprofiled. The default ``--flamegraph off`` skips
+all of this and leaves benchmark behavior unchanged.
+
+.. note::
+
+   When comparing a change, profile each variant with the same
+   ``--rounds`` and ``--flamegraph-mode`` and distinct
+   ``--flamegraph-output`` paths (e.g. ``baseline.svg`` vs
+   ``after.svg``) so the two flame graphs are directly comparable.
+
+
+Exit codes
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Code
+     - Meaning
+   * - ``0``
+     - All requested operations completed and (when enabled) the
+       round-trip verification passed.
+   * - ``1``
+     - Adapter creation failed, round-trip verification failed, or
+       an operation hit a fatal error (e.g. all rounds timed out).
+   * - ``2``
+     - Invalid invocation: the ``--l2-adapter`` JSON / ``L2_ADAPTER_JSON``
+       env var was missing or could not be parsed, an option value was
+       invalid, or ``--flamegraph on`` was requested but the profiling
+       toolchain is unavailable.
diff --git a/docs/source/cli/coordinator.rst b/docs/source/cli/coordinator.rst
new file mode 100644
index 0000000..a2ed758
--- /dev/null
+++ b/docs/source/cli/coordinator.rst
@@ -0,0 +1,97 @@
+lmcache coordinator
+===================
+
+The ``lmcache coordinator`` command launches the LMCache MP **coordinator**, a
+standalone HTTP service that tracks the MP server instances in a deployment. MP
+servers register with it and send periodic heartbeats; the coordinator evicts
+any instance whose heartbeat lapses past ``--instance-timeout``.
+
+It replaces ``python -m lmcache.v1.mp_coordinator``. The process runs in the
+foreground; stop it with ``Ctrl-C``.
+
+.. code-block:: bash
+
+   lmcache coordinator [options]
+
+Quick start
+-----------
+
+.. code-block:: bash
+
+   lmcache coordinator \
+       --host 0.0.0.0 --port 9300 \
+       --instance-timeout 30 \
+       --health-check-interval 10
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Flag
+     - Description
+   * - ``--host HOST``
+     - Bind address for the coordinator's HTTP server (default: ``0.0.0.0``).
+   * - ``--port PORT``
+     - HTTP port (default: ``9300``).
+   * - ``--instance-timeout SECS``
+     - Seconds without a heartbeat after which an instance is evicted
+       (default: ``30``).
+   * - ``--health-check-interval SECS``
+     - Seconds between health-check sweeps; ``0`` disables the loop
+       (default: ``10``).
+   * - ``--eviction-check-interval SECS``
+     - Seconds between L2 eviction sweeps; ``0`` disables the loop
+       (default: ``5``).
+   * - ``--eviction-ratio RATIO``
+     - Fraction of tracked keys (by count) to evict per cycle, ``0.0`` to
+       ``1.0`` (default: ``0.2``).
+   * - ``--trigger-watermark RATIO``
+     - Eviction fires when usage reaches this fraction of the quota, ``0.0``
+       (exclusive) to ``1.0`` (default: ``1.0``).
+   * - ``--chunk-size N``
+     - Tokens per KV chunk: the CacheBlend match unit and the unit used to
+       resolve pin ``token_ids`` to keys. Must equal the MP servers'
+       ``--chunk-size`` (default: ``256``).
+   * - ``--hash-algorithm NAME``
+     - Token hash algorithm for pin key resolution; must equal the MP servers'
+       ``--hash-algorithm``. ``blake3`` (default) is self-contained; other
+       algorithms require vLLM importable in the coordinator.
+   * - ``--blend-probe-stride N``
+     - Positions between CacheBlend match probes; ``1`` probes every offset
+       for full recall (default: ``1``).
+   * - ``--timeout-keep-alive SECS``
+     - Seconds the HTTP server keeps idle connections open before closing
+       them. Must be greater than the MP servers' heartbeat interval
+       (default ``5``), otherwise heartbeat requests may hit a closing
+       connection and fail with ``Server disconnected without sending a
+       response`` (default: ``10``).
+
+Configuration
+-------------
+
+Every flag is optional. Unset flags fall back to the
+``LMCACHE_MP_COORDINATOR_*`` environment variables (``HOST``, ``PORT``,
+``INSTANCE_TIMEOUT``, ``HEALTH_CHECK_INTERVAL``, ``EVICTION_CHECK_INTERVAL``,
+``EVICTION_RATIO``, ``TRIGGER_WATERMARK``, ``CHUNK_SIZE``, ``HASH_ALGORITHM``,
+``BLEND_PROBE_STRIDE``, ``TIMEOUT_KEEP_ALIVE``), and then to the built-in
+defaults. A supplied flag always overrides the matching env-derived value, so
+env-only deployments keep working unchanged.
+
+A second set of env-only knobs controls the startup L2 resync —
+``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC`` (default ``True``),
+``LMCACHE_MP_COORDINATOR_RESYNC_POLL_INTERVAL`` (``1``),
+``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT`` (``60``), and
+``LMCACHE_MP_COORDINATOR_RESYNC_PAGE_SIZE`` (``1000``). See
+:doc:`/mp/coordinator` for the boot-time resync flow and the active
+eviction loop.
+
+The coordinator drives fleet-wide L2 eviction by calling each MP
+server's ``DELETE /l2`` endpoint, and resync paginates ``GET /l2/keys``
+on a registered MP server. Both endpoints are documented at
+:ref:`mp-http-l2-keys-api`.
+
+See :doc:`/mp/coordinator` for the coordinator's architecture, registration
+protocol, and HTTP API.
diff --git a/docs/source/cli/describe.rst b/docs/source/cli/describe.rst
new file mode 100644
index 0000000..bddc737
--- /dev/null
+++ b/docs/source/cli/describe.rst
@@ -0,0 +1,218 @@
+lmcache describe
+================
+
+The ``lmcache describe`` command shows the detailed status of a running
+service. Two targets are supported:
+
+- ``kvcache`` — the LMCache KV cache service (health, L1 storage, registered
+  models, L2 adapters).
+- ``engine`` — the inference engine (vLLM) LMCache is paired with (model,
+  context window, health, in-flight requests).
+
+KV Cache Service (``kvcache``)
+------------------------------
+
+.. code-block:: bash
+
+   lmcache describe kvcache --url http://localhost:8000
+
+.. code-block:: text
+
+   ============ LMCache KV Cache Service ============
+   Health:                                         OK
+   URL:                         http://localhost:8000
+   Engine type:                           BlendEngine
+   Chunk size:                                    256
+   L1 capacity (GB):                            60.00
+   L1 used (GB):                        42.30 (70.5%)
+   Eviction policy:                               LRU
+   Cached objects:                               1024
+   Active sessions:                                 3
+   ---- Model: meta-llama/Llama-3.1-70B-Instruct ----
+   Model:           meta-llama/Llama-3.1-70B-Instruct
+   World size:                                      4
+   GPU IDs:                                0, 1, 2, 3
+   Num layers:                                     80
+   Num blocks:                                   2048
+   Cache size per token (bytes):               327680
+   --- Kernel group 0 (meta-llama/Llama-3.1-70B-Instruct) ---
+   Kernel group index:                              0
+   Engine group index:                              0
+   Object group index:                              0
+   Num layers:                                     80
+   Slots per block:                               128
+   Dtype:                               torch.float16
+   MLA:                                         False
+   Attention backend:    vLLM non-MLA flash attention
+   Engine KV shape:          NL x [2, NB, BS, NH, HS]
+   Engine KV tensor shape: 80 x [2, 2048, 128, 8, 128]
+   ------------- L2: NixlStoreL2Adapter -------------
+   Type:                           NixlStoreL2Adapter
+   Health:                                         OK
+   Backend:                                 nixl_rdma
+   Stored objects:                                512
+   Pool used:                       480 / 512 (93.8%)
+   ==================================================
+
+The output shows:
+
+- **Overview** — health status, engine type, chunk size.
+- **L1 storage** — capacity, usage, eviction policy, cached object count.
+- **Registered models** — per-model KV cache layout: a context-wide summary
+  followed by one kernel group section per kernel group, each with the engine
+  KV tensor shape (symbolic and concrete), attention backend, and group geometry.
+- **L2 adapters** — type, health, backend, stored objects, and utilization.
+
+Inference Engine (``engine``)
+-----------------------------
+
+``describe engine`` inspects the vLLM inference engine instead of the LMCache
+service, reading only the engine's own HTTP endpoints (``/v1/models``,
+``/health``, ``/metrics``).
+
+.. code-block:: bash
+
+   lmcache describe engine --url http://localhost:8000
+
+.. code-block:: text
+
+   ================ Inference Engine ================
+   Model:                  meta-llama/Llama-3.1-8B-Instruct
+   Max context (tokens):   131072
+   Status:                 OK
+   Running requests:       3
+   ==================================================
+
+The output shows:
+
+- **Model** and **Max context** — the served model id and its maximum context
+  length, from ``/v1/models``.
+- **Status** — ``OK`` / ``UNHEALTHY`` from the engine's ``/health`` probe.
+- **Running requests** — in-flight requests, summed from the
+  ``vllm:num_requests_running`` metric. Shows ``N/A`` if metrics are disabled
+  or unreachable.
+
+Only the ``/v1/models`` fetch is required: if ``/health`` or ``/metrics`` is
+unavailable the command still reports what it can rather than failing.
+
+.. code-block:: bash
+
+   lmcache describe engine --url http://localhost:8000 --format json
+
+.. code-block:: json
+
+   {
+     "title": "Inference Engine",
+     "metrics": {
+       "model": "meta-llama/Llama-3.1-8B-Instruct",
+       "max_context": 131072,
+       "status": "OK",
+       "running_requests": 3
+     }
+   }
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Flag
+     - Description
+   * - ``target``
+     - What to describe (positional, required): ``kvcache`` or ``engine``.
+   * - ``--url``
+     - Server URL. Defaults per target: ``http://localhost:8080`` for
+       ``kvcache``, ``http://localhost:8000`` for ``engine``.
+   * - ``--format``
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output PATH``
+     - Save metrics to a file (format follows ``--format``).
+   * - ``-q`` / ``--quiet``
+     - Suppress stdout output. Exit code only.
+
+JSON Output
+-----------
+
+Use ``--format json`` for machine-readable output. Models, kernel groups, and
+L2 adapters are collected into lists for easy programmatic access:
+
+.. code-block:: bash
+
+   lmcache describe kvcache --url http://localhost:8000 --format json
+
+.. code-block:: json
+
+   {
+     "title": "LMCache KV Cache Service",
+     "metrics": {
+       "health": "OK",
+       "url": "http://localhost:8000",
+       "engine_type": "BlendEngine",
+       "chunk_size": 256,
+       "l1_capacity_gb": 60.0,
+       "l1_used_gb": "42.30 (70.5%)",
+       "eviction_policy": "LRU",
+       "cached_objects": 1024,
+       "active_sessions": 3,
+       "models": [
+         {
+           "model": "meta-llama/Llama-3.1-70B-Instruct",
+           "world_size": 4,
+           "gpu_ids": "0, 1, 2, 3",
+           "num_layers": 80,
+           "num_blocks": 2048,
+           "cache_size_per_token": 327680
+         }
+       ],
+       "kernel_groups": [
+         {
+           "model": "meta-llama/Llama-3.1-70B-Instruct",
+           "kernel_group_idx": 0,
+           "engine_group_idx": 0,
+           "object_group_idx": 0,
+           "num_layers": 80,
+           "slots_per_block": 128,
+           "dtype": "torch.float16",
+           "is_mla": false,
+           "attention_backend": "vLLM non-MLA flash attention",
+           "engine_kv_shape": "NL x [2, NB, BS, NH, HS]",
+           "engine_kv_concrete_shape": "80 x [2, 2048, 128, 8, 128]"
+         }
+       ],
+       "l2_adapters": [
+         {
+           "type": "NixlStoreL2Adapter",
+           "health": "OK",
+           "backend": "nixl_rdma",
+           "stored_object_count": 512,
+           "pool_used": "480 / 512 (93.8%)"
+         }
+       ]
+     }
+   }
+
+Engine KV Shape Abbreviations
+-----------------------------
+
+The ``engine_kv_shape`` field uses short names from the ``EngineKVFormat`` enum:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Abbrev
+     - Meaning
+   * - NB
+     - num_blocks
+   * - NL
+     - num_layers
+   * - BS
+     - block_size
+   * - NH
+     - num_heads
+   * - HS
+     - head_size
+   * - PBS
+     - page_buffer_size (NB × BS)
diff --git a/docs/source/cli/index.rst b/docs/source/cli/index.rst
new file mode 100644
index 0000000..1647513
--- /dev/null
+++ b/docs/source/cli/index.rst
@@ -0,0 +1,108 @@
+CLI Reference
+=============
+
+The ``lmcache`` command-line interface provides tools for launching,
+managing, inspecting, and benchmarking LMCache servers and the inference
+engines in front of them.
+
+.. code-block:: bash
+
+   lmcache <command> [options]
+
+After installing LMCache, the ``lmcache`` command is available globally.
+Run ``lmcache -h`` to see all commands, or ``lmcache <command> -h`` for a
+specific command.
+
+Installation
+------------
+
+The ``lmcache`` CLI ships in two packages:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 30 45
+
+   * - Package
+     - Install
+     - When to use
+   * - ``lmcache``
+     - ``pip install lmcache``
+     - Full install: server, CLI, and CUDA extensions. Required for
+       ``server``, ``bench server``, ``bench l2``, and ``trace``.
+       Linux + GPU.
+   * - ``lmcache-cli``
+     - ``pip install lmcache-cli``
+     - CLI only: ``ping``, ``query``, ``describe``, ``kvcache``,
+       ``quota``, ``bench engine``. No GPU required, any OS.
+
+.. note::
+
+   Do not install both packages in the same environment — they both provide
+   the ``lmcache`` entry point.
+
+Available Commands
+------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Command
+     - Description
+   * - :doc:`server`
+     - Launch the LMCache MP server (ZMQ + HTTP). Requires the full install.
+   * - :doc:`coordinator`
+     - Launch the LMCache MP coordinator (HTTP instance registry).
+   * - :doc:`describe`
+     - Show detailed status of a running LMCache service.
+   * - :doc:`ping`
+     - Liveness check for LMCache or vLLM servers.
+   * - :doc:`query`
+     - Single-shot query interface for the serving engine.
+   * - :doc:`bench`
+     - Run sustained benchmarks against an inference engine
+       (``engine``), an LMCache MP server (``server``), or an L2 cache
+       adapter (``l2``).
+   * - :doc:`kvcache`
+     - Manage KV cache state (e.g. clear L1 cache) on a running server.
+   * - :doc:`quota`
+     - Manage per-salt cache quotas (set, get, list, delete).
+   * - :doc:`trace`
+     - Inspect and replay storage-level trace files.
+   * - :doc:`tool`
+     - Run offline analysis tools (e.g. the cache simulator).
+
+Output Formats
+--------------
+
+Commands that produce metrics share three common flags:
+
+* ``--format {terminal,json}`` — stdout format (default: ``terminal``).
+* ``--output PATH`` — also write metrics to a file (uses ``--format``).
+* ``-q`` / ``--quiet`` — suppress stdout; rely on the exit code.
+
+The terminal output uses human-readable labels (e.g. ``"Round trip time
+(ms)"``), while JSON uses machine-readable keys (e.g.
+``"round_trip_time_ms"``).
+
+Adding New Commands
+-------------------
+
+New CLI subcommands are added by creating a ``BaseCommand`` subclass under
+``lmcache/cli/commands/``; they are discovered and registered automatically.
+See :doc:`/developer_guide/cli` for details.
+
+.. toctree::
+   :maxdepth: 1
+
+   server
+   coordinator
+   describe
+   ping
+   query
+   bench
+   kvcache
+   quota
+   trace
+   tool
+
diff --git a/docs/source/cli/kvcache.rst b/docs/source/cli/kvcache.rst
new file mode 100644
index 0000000..f115a4d
--- /dev/null
+++ b/docs/source/cli/kvcache.rst
@@ -0,0 +1,126 @@
+lmcache kvcache
+===============
+
+The ``lmcache kvcache`` command manages KV cache state on a running LMCache
+server.
+
+.. code-block:: bash
+
+   lmcache kvcache <sub-command> [options]
+
+.. code-block:: text
+
+   $ lmcache kvcache -h
+   usage: lmcache kvcache [-h] [--format FORMAT] [--output PATH] [-q] {clear} ...
+
+   Manage KV cache state.
+
+   subcommands:
+     clear          Clear all cached KV data in L1 (CPU)
+
+   options:
+     -h, --help       show this help message and exit
+     --format FORMAT  Stdout output format (default: terminal). Available: terminal, json.
+     --output PATH    Save metrics to a file at PATH (format chosen by --format).
+     -q, --quiet      Suppress stdout output. Exit code only.
+
+clear
+-----
+
+Clear all cached KV data in **L1 (CPU memory)** on the target LMCache server.
+
+.. code-block:: bash
+
+   lmcache kvcache clear --url <MP_HTTP_URL>
+
+**Example:**
+
+.. code-block:: bash
+
+   $ lmcache kvcache clear --url http://localhost:8000
+
+   ================ KV Cache Clear ================
+   Status:                                       OK
+   ================================================
+
+**JSON output** (for scripting with ``jq``):
+
+.. code-block:: bash
+
+   $ lmcache kvcache clear --url http://localhost:8000 --format json
+   {
+     "title": "KV Cache Clear",
+     "metrics": {
+       "status": "OK"
+     }
+   }
+
+**Quiet mode** (exit code only, no output):
+
+.. code-block:: bash
+
+   $ lmcache kvcache clear -q --url http://localhost:8000
+   $ echo $?
+   0
+
+Options
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - Flag
+     - Required
+     - Description
+   * - ``--url``
+     - Yes
+     - URL of the LMCache MP HTTP server (e.g. ``http://localhost:8000``).
+   * - ``--format``
+     - No
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output``
+     - No
+     - Save output to a file (uses the format chosen by ``--format``).
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress stdout. Useful in scripts where you only need the exit code.
+
+Exit Codes
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Code
+     - Meaning
+   * - ``0``
+     - Success.
+   * - ``1``
+     - Error (connection failure, server error, bad arguments).
+
+Common Patterns
+---------------
+
+**Handle temporary server unavailability:**
+
+If the server is temporarily unreachable (e.g. due to network issue), the command
+fails with exit code 1. For persistent connectivity issues, use ``lmcache ping``
+to diagnose.
+
+.. code-block:: bash
+
+   if lmcache kvcache clear -q --url http://localhost:8000; then
+       echo "Cache cleared"
+   else
+       echo "Clear failed — server temporarily unreachable, retrying later"
+   fi
+
+**Clear cache and capture JSON result:**
+
+.. code-block:: bash
+
+   RESULT=$(lmcache kvcache clear --url http://localhost:8000 --format json)
+   STATUS=$(echo "$RESULT" | jq -r '.metrics.status')
+   echo "Clear status: $STATUS"
diff --git a/docs/source/cli/ping.rst b/docs/source/cli/ping.rst
new file mode 100644
index 0000000..bf109f3
--- /dev/null
+++ b/docs/source/cli/ping.rst
@@ -0,0 +1,75 @@
+lmcache ping
+============
+
+The ``lmcache ping`` command is a liveness check for an LMCache KV cache
+server or a vLLM serving engine.
+
+.. code-block:: bash
+
+   # Ping the KV cache server (default: http://localhost:8080)
+   lmcache ping kvcache
+
+   # Ping the serving engine (default: http://localhost:8000)
+   lmcache ping engine --url http://localhost:8000
+
+.. code-block:: text
+
+   ======= Ping KV Cache ========
+   Status:                   OK
+   Round trip time (ms):     3.42
+   ==============================
+
+``ping kvcache`` checks the ``/healthcheck`` endpoint; ``ping engine`` checks
+``/health``.
+
+Options
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Flag
+     - Description
+   * - ``kvcache`` | ``engine``
+     - Target to ping (positional, required).
+   * - ``--url``
+     - Server URL. Defaults to ``http://localhost:8080`` for ``kvcache``,
+       ``http://localhost:8000`` for ``engine``.
+   * - ``--format``
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output PATH``
+     - Save metrics to a file (format follows ``--format``).
+   * - ``-q`` / ``--quiet``
+     - Suppress stdout output. Exit code only.
+
+JSON Output
+-----------
+
+.. code-block:: bash
+
+   lmcache ping kvcache --format json
+
+.. code-block:: json
+
+   {
+     "title": "Ping KV Cache",
+     "metrics": {
+       "status": "OK",
+       "round_trip_time_ms": 3.42
+     }
+   }
+
+Exit Codes
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Code
+     - Meaning
+   * - ``0``
+     - Server is reachable (HTTP 200).
+   * - ``1``
+     - Connection failure or non-200 response.
diff --git a/docs/source/cli/query.rst b/docs/source/cli/query.rst
new file mode 100644
index 0000000..88a8ee1
--- /dev/null
+++ b/docs/source/cli/query.rst
@@ -0,0 +1,90 @@
+lmcache query
+=============
+
+The ``lmcache query`` command sends a single OpenAI-compatible inference
+request and reports token and latency metrics. It has two targets:
+
+.. code-block:: bash
+
+   lmcache query {engine,kvcache} [options]
+
+* ``engine`` — send one request to a serving engine's HTTP API.
+* ``kvcache`` — query KV-cache endpoints (not implemented yet).
+
+
+query engine
+------------
+
+The ``query engine`` subcommand sends one request to the engine API and
+reports metrics. ``--prompt`` supports placeholders: ``{lmcache}`` loads
+``lmcache/cli/documents/lmcache.txt``, and custom documents can be passed with
+``--documents NAME=PATH``. The prompt token count is taken directly from the
+usage data reported by the engine (``stream_options: {include_usage: true}``).
+
+.. code-block:: bash
+
+   lmcache query engine --url http://localhost:8000/v1 \
+     --prompt "{lmcache} Summarize LMCache usage." \
+     --format terminal \
+     --max-tokens 128
+
+.. code-block:: text
+
+   ================= Query Engine =================
+   Model:                         facebook/opt-125m
+   Input tokens:                                618
+   --------------- Latency Metrics ----------------
+   Output tokens:                                 9
+   TTFT (ms):                                 26.88
+   TPOT (ms/token):                            0.91
+   Total latency (ms):                        35.05
+   Throughput (tokens/s):                   1100.64
+   ================================================
+
+Options
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Flag
+     - Required
+     - Description
+   * - ``--url URL``
+     - Yes
+     - Serving engine base URL (e.g. ``http://localhost:8000/v1``).
+   * - ``--prompt TEXT``
+     - Yes
+     - Prompt text with optional ``{name}`` placeholders. ``{lmcache}``
+       expands to the bundled sample document.
+   * - ``--model ID``
+     - No
+     - Model ID for the serving engine. Auto-detected from the engine's
+       reported usage if omitted.
+   * - ``--max-tokens N``
+     - No
+     - Maximum completion tokens (default: 128).
+   * - ``--timeout SECS``
+     - No
+     - HTTP timeout in seconds (default: 30).
+   * - ``--documents NAME=PATH``
+     - No
+     - Load file text for ``{NAME}`` in ``--prompt``. Accepts one or more
+       ``NAME=PATH`` values.
+   * - ``--completions``
+     - No
+     - Use ``POST /v1/completions`` only.
+   * - ``--chat-first``
+     - No
+     - Try ``/v1/chat/completions`` first, then fall back to
+       ``/v1/completions``.
+   * - ``--format``
+     - No
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output PATH``
+     - No
+     - Save metrics to a file (format follows ``--format``).
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress stdout output. Exit code only.
diff --git a/docs/source/cli/quota.rst b/docs/source/cli/quota.rst
new file mode 100644
index 0000000..114d5b8
--- /dev/null
+++ b/docs/source/cli/quota.rst
@@ -0,0 +1,301 @@
+lmcache quota
+=============
+
+The ``lmcache quota`` command manages per-salt cache quotas on a running
+LMCache server. Quotas are soft limits: exceeding a quota triggers eviction
+on the next cycle (~1 s) rather than rejecting writes.
+
+.. code-block:: bash
+
+   lmcache quota <sub-command> [options]
+
+.. code-block:: text
+
+   $ lmcache quota -h
+   usage: lmcache quota [-h] {set,get,list,delete} ...
+
+   Manage per-salt cache quotas on the LMCache server.
+
+   subcommands:
+     set            Create or update a quota for a cache_salt
+     get            Show the quota and current usage for a cache_salt
+     list           List all registered quotas and their usage
+     delete         Remove a quota for a cache_salt
+
+   options:
+     -h, --help     show this help message and exit
+
+set
+---
+
+Create or update a quota for a given ``cache_salt``.
+
+.. code-block:: bash
+
+   lmcache quota set <salt> --limit-gb <GB> [--url <URL>]
+
+**Example:**
+
+.. code-block:: bash
+
+   $ lmcache quota set tenant1 --limit-gb 10.5
+
+   ================ Quota Set =================
+   Cache salt:                          tenant1
+   Limit (GB):                             10.5
+   Status:                                   ok
+   =============================================
+
+**Options:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - Flag
+     - Required
+     - Description
+   * - ``<salt>``
+     - Yes
+     - The ``cache_salt`` identifier. Use ``_default`` for anonymous
+       (un-salted) traffic.
+   * - ``--limit-gb``
+     - Yes
+     - Quota limit in gigabytes (non-negative float).
+   * - ``--url``
+     - No
+     - LMCache HTTP server URL (default: ``http://localhost:8080``).
+   * - ``--format``
+     - No
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output``
+     - No
+     - Save output to a file (uses the format chosen by ``--format``).
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress stdout output. Exit code only.
+
+get
+---
+
+Show the current quota limit and live usage for a specific ``cache_salt``.
+
+.. code-block:: bash
+
+   lmcache quota get <salt> [--url <URL>]
+
+**Example:**
+
+.. code-block:: bash
+
+   $ lmcache quota get tenant1
+
+   ================ Quota Info ================
+   Cache salt:                          tenant1
+   Limit (GB):                             10.5
+   Current usage (GB):                     3.27
+   Exists:                                 True
+   =============================================
+
+**Options:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - Flag
+     - Required
+     - Description
+   * - ``<salt>``
+     - Yes
+     - The ``cache_salt`` identifier.
+   * - ``--url``
+     - No
+     - LMCache HTTP server URL (default: ``http://localhost:8080``).
+   * - ``--format``
+     - No
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output``
+     - No
+     - Save output to a file.
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress stdout output.
+
+list
+----
+
+List all registered quotas along with their current usage.
+
+.. code-block:: bash
+
+   lmcache quota list [--url <URL>]
+
+**Example:**
+
+.. code-block:: bash
+
+   $ lmcache quota list
+
+   =================== Quota List ====================
+   --- Salt: tenant1 ---
+   Cache salt:                               tenant1
+   Limit (GB):                                  10.5
+   Current usage (GB):                          3.27
+   --- Salt: _default ---
+   Cache salt:                              _default
+   Limit (GB):                                   5.0
+   Current usage (GB):                          1.82
+   ===================================================
+
+**JSON output:**
+
+.. code-block:: bash
+
+   $ lmcache quota list --format json
+   {
+     "title": "Quota List",
+     "sections": {
+       "quota_0": {
+         "label": "Salt: tenant1",
+         "metrics": {
+           "cache_salt": "tenant1",
+           "limit_gb": 10.5,
+           "current_usage_gb": 3.27
+         }
+       },
+       "quota_1": {
+         "label": "Salt: _default",
+         "metrics": {
+           "cache_salt": "_default",
+           "limit_gb": 5.0,
+           "current_usage_gb": 1.82
+         }
+       }
+     }
+   }
+
+**Options:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - Flag
+     - Required
+     - Description
+   * - ``--url``
+     - No
+     - LMCache HTTP server URL (default: ``http://localhost:8080``).
+   * - ``--format``
+     - No
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output``
+     - No
+     - Save output to a file.
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress stdout output.
+
+delete
+------
+
+Remove a quota entry for a given ``cache_salt``. Any bytes still cached
+under this salt become over-budget on the next eviction cycle and will be
+evicted (effective limit drops to 0).
+
+.. code-block:: bash
+
+   lmcache quota delete <salt> [--url <URL>]
+
+**Example:**
+
+.. code-block:: bash
+
+   $ lmcache quota delete tenant1
+
+   ============== Quota Delete ===============
+   Cache salt:                        tenant1
+   Status:                            removed
+   ===========================================
+
+**Options:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 10 65
+
+   * - Flag
+     - Required
+     - Description
+   * - ``<salt>``
+     - Yes
+     - The ``cache_salt`` identifier.
+   * - ``--url``
+     - No
+     - LMCache HTTP server URL (default: ``http://localhost:8080``).
+   * - ``--format``
+     - No
+     - Output format: ``terminal`` (default) or ``json``.
+   * - ``--output``
+     - No
+     - Save output to a file.
+   * - ``-q`` / ``--quiet``
+     - No
+     - Suppress stdout output.
+
+Exit Codes
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Code
+     - Meaning
+   * - ``0``
+     - Success.
+   * - ``1``
+     - Error (connection failure, server error, bad arguments).
+
+The ``_default`` Salt
+---------------------
+
+The LMCache server uses an empty string (``""``) as the ``cache_salt`` for
+anonymous / un-salted traffic. Since empty strings cannot appear in URL path
+parameters, the HTTP API (and this CLI) uses the sentinel ``_default`` in
+its place.
+
+.. code-block:: bash
+
+   # Set a 5 GB quota for anonymous traffic
+   lmcache quota set _default --limit-gb 5.0
+
+   # Check usage
+   lmcache quota get _default
+
+Common Patterns
+---------------
+
+**Provision quotas for multiple tenants:**
+
+.. code-block:: bash
+
+   for tenant in tenant_a tenant_b tenant_c; do
+       lmcache quota set "$tenant" --limit-gb 8.0
+   done
+
+**Monitor usage in a script:**
+
+.. code-block:: bash
+
+   USAGE=$(lmcache quota get tenant1 --format json | jq '.metrics.current_usage_gb')
+   LIMIT=$(lmcache quota get tenant1 --format json | jq '.metrics.limit_gb')
+   echo "tenant1: ${USAGE} / ${LIMIT} GB"
+
+**Revoke access (evict all cached data for a salt):**
+
+.. code-block:: bash
+
+   # Deleting the quota causes all data under this salt to be evicted
+   lmcache quota delete tenant1
diff --git a/docs/source/cli/server.rst b/docs/source/cli/server.rst
new file mode 100644
index 0000000..9cd4437
--- /dev/null
+++ b/docs/source/cli/server.rst
@@ -0,0 +1,103 @@
+lmcache server
+==============
+
+The ``lmcache server`` command launches the standalone LMCache
+Multi-Process (MP) server, which exposes a ZMQ control plane and an HTTP
+frontend (status, healthcheck, cache-clear, checksum APIs). It is the server
+that ``lmcache describe``, ``lmcache ping kvcache``, ``lmcache kvcache``, and
+``lmcache bench server`` talk to.
+
+.. note::
+
+   This command requires the full ``lmcache`` installation with CUDA
+   extensions. It is **not** available in the lightweight ``lmcache-cli``
+   package.
+
+.. code-block:: bash
+
+   lmcache server [options]
+
+Quick start
+-----------
+
+.. code-block:: bash
+
+   lmcache server \
+       --host 0.0.0.0 --port 5555 \
+       --l1-size-gb 100 \
+       --eviction-policy LRU
+
+Options
+-------
+
+The server composes its arguments from several configuration modules — the
+multiprocess server, the storage manager (L1 / L2 adapters / eviction), the
+HTTP frontend, and the Prometheus / telemetry observability layer. The full,
+authoritative list is large and evolves with the runtime, so consult:
+
+.. code-block:: bash
+
+   lmcache server --help
+
+Commonly used flags include:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Flag
+     - Description
+   * - ``--host HOST``
+     - Bind address for the server.
+   * - ``--port PORT``
+     - ZMQ control-plane port.
+   * - ``--chunk-size N``
+     - KV cache chunk size in tokens.
+   * - ``--l1-size-gb GB``
+     - L1 (CPU/DRAM) cache capacity in GB.
+   * - ``--eviction-policy POLICY``
+     - L1 eviction policy (e.g. ``LRU``).
+   * - ``--eviction-trigger-watermark RATIO``
+     - L1 fill ratio at which eviction begins.
+   * - ``--eviction-ratio RATIO``
+     - Fraction of L1 cleared per eviction cycle.
+   * - ``--max-workers N``
+     - Number of server worker processes.
+   * - ``--coordinator-url URL``
+     - Register with an MP coordinator at this base URL (e.g.
+       ``http://coordinator:9300``). Opt-in; enables fleet registration. See
+       :doc:`/mp/coordinator`.
+   * - ``--coordinator-advertise-ip IP``
+     - IP the coordinator should reach this server at (defaults to the
+       outbound IP).
+   * - ``--coordinator-heartbeat-interval SECONDS``
+     - Seconds between heartbeats (``> 0``, default ``5``). Keep well below the
+       coordinator's instance timeout.
+   * - ``--coordinator-l2-event-reporting``
+     - Enable reporting L2 store/lookup events to the coordinator for
+       fleet-wide usage tracking and quota-based eviction.
+   * - ``--coordinator-l2-event-flush-interval SECONDS``
+     - Seconds between L2 event batch flushes (``> 0``, default ``1``).
+   * - ``--p2p-advertise-url HOST:PORT``
+     - Enable P2P KV cache sharing and advertise this server's
+       transfer-channel endpoint to peers (e.g. ``10.0.0.1:8500``). Setting it
+       turns P2P on; it additionally requires ``--coordinator-url`` for peer
+       discovery. See :doc:`/mp/p2p`.
+   * - ``--p2p-listen-url HOST:PORT``
+     - Address the transfer-channel server binds to. Defaults to
+       ``--p2p-advertise-url``. Set it when the advertised address differs from
+       the bind address (e.g. bind ``0.0.0.0`` while advertising a routable IP).
+   * - ``--p2p-lookup-timeout SECONDS``
+     - Deadline for a peer lookup before it counts as a miss (default ``30``).
+   * - ``--p2p-load-timeout SECONDS``
+     - Deadline for a peer KV read before it counts as a failure
+       (default ``30``).
+   * - ``--p2p-transfer-engine ENGINE``
+     - Transfer-channel implementation for P2P reads (default ``nixl``).
+   * - ``--trace-level {storage}``
+     - Enable storage-level trace recording (see :doc:`trace`).
+   * - ``--trace-output PATH``
+     - Destination for recorded ``.lct`` trace files.
+
+L2 adapters, observability, and Prometheus exporters are configured through
+their own flag groups; see ``lmcache server --help`` for the complete set.
diff --git a/docs/source/cli/tool.rst b/docs/source/cli/tool.rst
new file mode 100644
index 0000000..37c679f
--- /dev/null
+++ b/docs/source/cli/tool.rst
@@ -0,0 +1,53 @@
+lmcache tool
+============
+
+The ``lmcache tool`` command groups offline analysis utilities bundled with
+LMCache.
+
+.. code-block:: bash
+
+   lmcache tool <tool-name> <action> [options]
+
+Currently one tool is available: ``cache-simulator``.
+
+.. note::
+
+   ``cache-simulator`` depends on the optional ``plot`` extras
+   (``sortedcontainers`` / ``matplotlib``). If they are not installed, the
+   sub-command is silently omitted from the CLI. Install the extras to enable
+   it.
+
+
+cache-simulator
+---------------
+
+Replay LMCache lookup-hash JSONL logs through an LRU cache to measure the
+KV-cache token hit rate. It has three actions:
+
+.. code-block:: bash
+
+   lmcache tool cache-simulator {simulate,sweep,gen-dataset} [options]
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Action
+     - Description
+   * - ``simulate``
+     - Replay logs at a fixed cache capacity; print a text report and save a
+       7-panel statistics PNG.
+   * - ``sweep``
+     - Sweep across a range of cache capacities and save a hit-rate vs.
+       capacity PNG.
+   * - ``gen-dataset``
+     - Generate a ``vllm bench serve`` custom dataset (JSONL) from
+       lookup-hash JSONL logs, preserving prefix-sharing structure.
+
+Each action has its own flags. Run the built-in help for the full list:
+
+.. code-block:: bash
+
+   lmcache tool cache-simulator simulate --help
+   lmcache tool cache-simulator sweep --help
+   lmcache tool cache-simulator gen-dataset --help
diff --git a/docs/source/cli/trace.rst b/docs/source/cli/trace.rst
new file mode 100644
index 0000000..598a6f6
--- /dev/null
+++ b/docs/source/cli/trace.rst
@@ -0,0 +1,102 @@
+lmcache trace
+=============
+
+The ``lmcache trace`` command inspects and replays LMCache storage-level
+trace files (``.lct``). It has two sub-commands:
+
+.. code-block:: bash
+
+   lmcache trace {info,replay} FILE [options]
+
+.. note::
+
+   ``lmcache trace`` needs the full ``lmcache`` package (StorageManager,
+   trace codecs, ``TraceReader``). It is not available in the lightweight
+   ``lmcache-cli`` install and exits with status ``2`` if those modules are
+   missing.
+
+Trace *capture* is not a ``trace`` sub-command — recording is bound to a live
+server via ``lmcache server --trace-level storage [--trace-output ...]`` (see
+:doc:`server`).
+
+
+info
+----
+
+Print a one-screen summary of a trace file: header metadata plus per-qualname
+record counts.
+
+.. code-block:: bash
+
+   lmcache trace info path/to/trace.lct
+
+.. code-block:: text
+
+   Trace file: path/to/trace.lct
+     level:                storage
+     format_version:       1
+     trace_schema_version: 1
+     duration:             12.345s
+     sm_config_digest:     a1b2c3d4
+     total_records:        2048
+     ops:
+       StorageManager.store: 1024
+       StorageManager.retrieve: 1024
+
+The only argument is the positional ``FILE`` (path to a ``.lct`` trace file).
+
+
+replay
+------
+
+Reissue every recorded call against a fresh ``StorageManager``, honoring the
+recorded inter-call timings.
+
+.. code-block:: bash
+
+   lmcache trace replay path/to/trace.lct \
+       --l1-size-gb 10 --eviction-policy LRU
+
+``replay`` accepts the standard storage-manager configuration flags
+(``--l1-size-gb``, ``--eviction-policy``, ``--l2-...``); see
+``lmcache server --help`` for the full list. The replay-side config may
+differ from the config recorded in the trace, which can legitimately cause
+retrieve misses.
+
+.. warning::
+
+   A replay environment mismatch may cause retrieve misses. Replay uses the
+   replay-side StorageManager config (which may differ from the recorded
+   config), runs on a host whose performance may differ from the recording
+   host, and StorageManager reads/writes are async. Treat retrieve-miss
+   counts as a signal about the replay environment, not a defect in the trace.
+
+Options
+~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Flag
+     - Description
+   * - ``FILE``
+     - Path to a ``.lct`` trace file (positional, required).
+   * - ``--verbose``
+     - Print one line per replayed record.
+   * - ``--jsonl-out PATH``
+     - Write one JSON object per replayed record to ``PATH`` (qualname,
+       latency_ms, failed).
+   * - ``--output-dir DIR``
+     - Directory for aggregated CSV / JSON summary output (default: current
+       directory).
+   * - ``--no-csv``
+     - Skip the aggregated CSV summary export.
+   * - ``--json``
+     - Also export an aggregated JSON summary.
+   * - ``-q`` / ``--quiet``
+     - Suppress the terminal metrics table (files are still written).
+
+The terminal summary reports overall replay stats (records replayed /
+skipped / failed, duration, config-digest match) and per-op latency
+percentiles. ``replay`` exits with status ``1`` if any record failed.
diff --git a/docs/source/community/blogs.rst b/docs/source/community/blogs.rst
new file mode 100644
index 0000000..247f356
--- /dev/null
+++ b/docs/source/community/blogs.rst
@@ -0,0 +1,7 @@
+Blogs
+=====
+
+LMCache is a community-driven open-source project and we publish regular blog posts to share updates,
+performance comparison and new features. You can find the latest blog posts below:
+
+`LMCache blogs <https://blog.lmcache.ai/>`_
\ No newline at end of file
diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst
new file mode 100644
index 0000000..37936e9
--- /dev/null
+++ b/docs/source/community/index.rst
@@ -0,0 +1,11 @@
+Community
+=========
+
+Get involved with the LMCache community -- join our meetings and follow the
+blog.
+
+.. toctree::
+   :maxdepth: 1
+
+   meetings
+   blogs
diff --git a/docs/source/community/meetings.rst b/docs/source/community/meetings.rst
new file mode 100644
index 0000000..13fa5f9
--- /dev/null
+++ b/docs/source/community/meetings.rst
@@ -0,0 +1,49 @@
+Community meetings
+====================================================
+
+LMCache hosts regular community meetings to discuss updates, address new feature requests, 
+and feedback from the community. If you are interested in contributing to the LMCache projects
+(core LMCache or Production Stack), we encourage you to join the meetings.
+We also host a monthly "Office Hour" on select topics.
+
+Meeting schedule
+-----------------
+The LMCache community meetings held separately for each project: 
+
+- LMCache - `Github <https://github.com/LMCache/LMCache/>`__
+- Production Stack - `Github <https://github.com/vllm-project/production-stack>`__
+
+LMCache Project
+++++++++++++++++
+
+The LMCache community meeting is held bi-weekly on **Tuesdays** at **9:00-9:30 AM PT**. 
+
+Please find the meeting invite link below:
+
+- **Meeting link**: `Zoom link <https://uchicago.zoom.us/j/6603596916?pwd=Z1E5MDRWUSt2am5XbEt4dTFkNGx6QT09>`_
+- **Calendar Invite**: `Google Calendar <https://drive.usercontent.google.com/u/0/uc?id=15Xz8-LtpBQ5QgR7KrorOOyfuohCFQmwn&export=download>`__
+- **Slack Channel**: `#lmcache <https://join.slack.com/t/lmcacheworkspace/shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA>`_
+
+vLLM Production Stack Project
++++++++++++++++++++++++++++++++
+
+The Production Stack community meeting is held bi-weekly on **Tuesdays** at **5:30-6:00 PM PT**.
+Please find the meeting invite link below:
+
+- **Meeting link**: `Zoom link <https://uchicago.zoom.us/j/6603596916?pwd=Z1E5MDRWUSt2am5XbEt4dTFkNGx6QT09>`_
+- **Calendar Invite**: `Google Calendar <https://drive.usercontent.google.com/u/0/uc?id=1I3WuivUVAq1vZ2XSW4rmqgD5c0bQcxE0&export=download>`__
+- **Slack Channel**: `#production-stack <https://vllm-dev.slack.com/archives/C089SMEAKRA>`_
+
+
+.. note:: 
+    The Zoom meeting link is the same for both LMCache and Production Stack community meetings. 
+    Meeting notes are available here: `Meeting notes <https://docs.google.com/document/d/1vX0g2q3j4x5m7J6z8Q9Gk4Z5l7f3K8h0nqYwW1a2c4o/edit?usp=sharing>`_.
+
+LMCache Office Hours
+++++++++++++++++++++
+
+Held monthly on the second Wednesday of the month at 2PM ET, 11AM PT.  
+
+- Topic announced on the LMCache #office-hour Slack channel
+- Request a calendar invite via `this form <https://lmcache-officehours.zapier.app/>`_
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..2536a37
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: Apache-2.0
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+# Standard
+from dataclasses import asdict
+from typing import Any
+import os
+import sys
+
+# Third Party
+from sphinx.ext import autodoc
+from sphinxawesome_theme import ThemeOptions
+
+sys.path.insert(0, os.path.abspath("../.."))
+
+project = "LMCache"
+copyright = "2024, The LMCache Team"
+author = "The LMCache Team"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinxcontrib.mermaid",
+    # "sphinx_copybutton",
+    "sphinx_multiversion",
+    "sphinxcontrib.images",
+    "sphinx_design",
+]
+
+copybutton_prompt_text = r"^(\$ |>>> |\# )"
+copybutton_prompt_is_regexp = True
+autosectionlabel_prefix_document = True
+
+
+class MockedClassDocumenter(autodoc.ClassDocumenter):
+    """Remove note about base class when a class is
+    derived from object."""
+
+    def add_line(self, line: str, source: str, *lineno: int) -> None:
+        if line == "   Bases: :py:class:`object`":
+            return
+        super().add_line(line, source, *lineno)
+
+
+autodoc.ClassDocumenter = MockedClassDocumenter
+
+# autodoc_default_options = {
+#     "members": True,
+#     "undoc-members": True,
+#     "private-members": True
+# }
+
+templates_path = ["_templates"]
+exclude_patterns: list[Any] = []
+add_module_names = False
+language = os.environ.get("SPHINX_LANGUAGE", "en")
+locale_dirs = ["locale/"]
+gettext_compact = False
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# html style
+html_title = project
+html_theme = "sphinxawesome_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css", "scroll.css"]
+html_js_files = ["custom.js"]
+html_favicon = "assets/lmcache-logo.png"
+html_permalinks_icon = "<span>#</span>"
+pygments_style = "sphinx"
+pygments_style_dark = "fruity"
+
+theme_options = ThemeOptions(  # Add your theme options.
+    extra_header_link_icons={
+        "GitHub": {
+            "link": "https://github.com/LMCache/LMCache/",
+            "icon": (
+                '<svg height="26px" style="margin-top:-2px;display:inline" '
+                'viewBox="0 0 45 44" '
+                'fill="currentColor" xmlns="http://www.w3.org/2000/svg">'
+                '<path fill-rule="evenodd" clip-rule="evenodd" '
+                'd="M22.477.927C10.485.927.76 10.65.76 22.647c0 9.596 6.223 \
+                17.736 '
+                "14.853 20.608 1.087.2 1.483-.47 1.483-1.047 "
+                "0-.516-.019-1.881-.03-3.693-6.04 "
+                "1.312-7.315-2.912-7.315-2.912-.988-2.51-2.412-3.178-2.412 \
+                -3.178-1.972-1.346.149-1.32.149-1.32 "  # noqa
+                "2.18.154 3.327 2.24 3.327 2.24 1.937 3.318 5.084 2.36 6.321 "
+                "1.803.197-1.403.759-2.36 "
+                "1.379-2.903-4.823-.548-9.894-2.412-9.894-10.734 "
+                "0-2.37.847-4.31 2.236-5.828-.224-.55-.969-2.759.214-5.748 0 0 "
+                "1.822-.584 5.972 2.226 "
+                "1.732-.482 3.59-.722 5.437-.732 1.845.01 3.703.25 5.437.732 "
+                "4.147-2.81 5.967-2.226 "
+                "5.967-2.226 1.185 2.99.44 5.198.217 5.748 1.392 1.517 2.232 \
+                 3.457 "
+                "2.232 5.828 0 "
+                "8.344-5.078 10.18-9.916 10.717.779.67 1.474 1.996 1.474 \
+                4.021 0 "
+                "2.904-.027 5.247-.027 "
+                "5.96 0 .58.392 1.256 1.493 1.044C37.981 40.375 44.2 32.24 \
+                 44.2 "
+                '22.647c0-11.996-9.726-21.72-21.722-21.72" '
+                'fill="currentColor"/></svg>'
+            ),
+        }
+    },
+)
+
+images_config = {
+    "default_image_width": "80%",
+    "default_image_target": "_blank",
+}
+
+html_theme_options = asdict(theme_options)
+
+# more_options = {
+#     # navigation and sidebar
+#     'show_toc_level': 2,
+#     'announcement': None,
+#     'secondary_sidebar_items': [
+#         'page-toc',
+#     ],
+#     'navigation_depth': 3,
+#     'primary_sidebar_end': [],
+# }
+
+# html_theme_options.update(more_options)
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "typing_extensions": (
+        "https://typing-extensions.readthedocs.io/en/latest",
+        None,
+    ),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "torch": ("https://pytorch.org/docs/stable", None),
+    "psutil": ("https://psutil.readthedocs.io/en/stable", None),
+}
+
+# Mock import
+autodoc_mock_imports = [
+    "sortedcontainers",
+    "torch",
+    "prometheus_client",
+    "yaml",
+    "vllm",
+    "nvtx",
+    "redis",
+    "lmcache.c_ops",
+    "aiofiles",
+    "zmq",
+    "transformers",
+    "safetensors",
+    "torch.Tensor",
+]
+
+# -- sphinx-multiversion configuration -------------------------------------------
+
+# Whitelist pattern for tags (build docs for all v* tags)
+smv_tag_whitelist = r"^v\d+\.\d+.*$"
+
+# Whitelist pattern for branches (build docs for dev and main)
+smv_branch_whitelist = r"^(dev|main)$"
+
+# Pattern for released versions (tags only)
+smv_released_pattern = r"^tags/v.*$"
+
+# Remote whitelist pattern (for security)
+smv_remote_whitelist = r"^(origin)$"
+
+# Output directories
+smv_latest_version = "dev"  # Point latest to dev branch
+smv_prefer_remote_refs = False
diff --git a/docs/source/controller/freeze_mode.rst b/docs/source/controller/freeze_mode.rst
new file mode 100644
index 0000000..3fc2df6
--- /dev/null
+++ b/docs/source/controller/freeze_mode.rst
@@ -0,0 +1,100 @@
+Freeze Mode
+==========
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/coordinator`.
+
+
+Overview
+--------
+
+Freeze Mode is a safety mechanism in LMCache Controller designed to prevent data inconsistency and potential data loss during critical system events. When the controller detects severe state inconsistencies or is undergoing restart/recovery, it can activate Freeze Mode to temporarily restrict certain operations.
+
+Motivation
+----------
+
+The primary motivations for Freeze Mode are:
+
+1. **Controller Failure Recovery**
+   - When the controller crashes and restarts, it may need to perform a full synchronization with workers
+   - During this sync period, the system state may be incomplete or inconsistent
+
+2. **State Inconsistency Detection**
+   - When severe state mismatches are detected between the controller and workers
+   - This could happen due to network issues, worker failures, or unexpected system behavior
+
+3. **Full Synchronization Safety**
+   - During full sync operations triggered by the above events
+   - To prevent operations that could cause eviction or admission events while state is being rebuilt
+
+Purpose
+-------
+
+When Freeze Mode is activated:
+
+- **All operations that could generate evict/admit events are disabled**
+- Only read operations and basic queries are allowed
+- The system essentially enters a "read-only" state for cache management operations
+- This prevents data corruption or loss during the recovery/sync process
+
+Current Implementation Status
+------------------------------
+
+**Currently Implemented:**
+
+1. **Freeze Mode Mechanism**
+   - StorageManager supports freeze mode
+   - When frozen, only LocalCPUBackend is used for retrieval operations
+   - Other storage backends are temporarily excluded from active use
+
+2. **API Endpoints**
+   - Freeze mode can be toggled via controller API
+   - Status can be queried to check if system is in freeze mode
+
+**Not Yet Implemented:**
+
+1. **Automatic Triggering**
+   - Controller does not yet automatically trigger freeze mode
+   - Manual activation via API is currently required
+
+2. **Full Sync Integration**
+   - Full synchronization process that would trigger freeze mode is not implemented
+   - Controller restart detection and automatic freeze mode activation not yet developed
+
+3. **Recovery Completion**
+   - Automatic unfreeze after sync completion not yet implemented
+   - Manual intervention currently required to exit freeze mode
+
+Usage
+-----
+
+**Manual Activation/Deactivation:**
+
+Freeze mode can be manually controlled through the Controller API:
+
+.. code-block:: bash
+
+    # Enable freeze mode
+    curl -X POST http://localhost:9000/api/v1/freeze -d '{"enabled": true}'
+
+    # Disable freeze mode
+    curl -X POST http://localhost:9000/api/v1/freeze -d '{"enabled": false}'
+
+    # Check freeze mode status
+    curl http://localhost:9000/api/v1/freeze/status
+
+**System Behavior in Freeze Mode:**
+
+- Cache retrieval operations continue to work
+- Only LocalCPUBackend is used for all retrievals
+- Cache admission/eviction operations are blocked
+- Write operations to storage backends are prevented
+- Monitoring and health checks continue normally
+
+Related Documentation
+--------------------
+
+- :doc:`index` - Controller WebUI overview
+- :doc:`../api_reference/configurations` - API and configuration reference
+- :doc:`../storage_backend/index` - Storage backend architecture
\ No newline at end of file
diff --git a/docs/source/controller/index.rst b/docs/source/controller/index.rst
new file mode 100644
index 0000000..3e97237
--- /dev/null
+++ b/docs/source/controller/index.rst
@@ -0,0 +1,59 @@
+Controller WebUI
+===============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/coordinator`.
+
+
+Overview
+--------
+
+The LMCache Controller provides a web-based dashboard for monitoring your LMCache instances. This web interface allows you to monitor system status, instances, workers, and performance metrics.
+
+Quick Start
+-----------
+
+To enable the Controller WebUI, start your LMCache instance with the following command:
+
+.. code-block:: bash
+
+    python3 -m lmcache.v1.api_server \
+        --host 0.0.0.0 \
+        --port 9000 \
+        --monitor-ports '{"pull":8300,"reply":8400}' \
+        --lmcache-worker-timeout 100 \
+        --health-check-interval 10
+
+After starting the controller, access the WebUI at:
+
+.. code-block:: text
+
+    http://localhost:9000/
+
+Configuration Options
+-------------------
+
+- ``--host``: Bind address for the API server (default: 0.0.0.0)
+- ``--port``: Port for the API server (default: 9000)
+- ``--monitor-ports``: ZMQ ports for controller communication
+- ``--lmcache-worker-timeout``: Worker timeout in seconds
+- ``--health-check-interval``: Health check interval in seconds
+
+Dashboard Features
+------------------
+
+The Controller Dashboard provides:
+
+- System overview and health monitoring
+- Instance and worker management
+- Performance metrics
+- Thread information
+- Environment variables inspection
+
+Related Documentation
+--------------------
+
+- :doc:`../api_reference/configurations` - Complete configuration reference
+- :doc:`../kv_cache_management/index` - KV cache management guide
+- :doc:`freeze_mode` - Freeze Mode safety mechanism guide
\ No newline at end of file
diff --git a/docs/source/developer_guide/architecture.rst b/docs/source/developer_guide/architecture.rst
new file mode 100644
index 0000000..11c85d9
--- /dev/null
+++ b/docs/source/developer_guide/architecture.rst
@@ -0,0 +1,112 @@
+Architecture Overview
+=====================
+
+High-Level System Architecture
+------------------------------
+
+
+LMCache extends an LLM inference engine (e.g., vLLM) with a multi-tier KV cache storage system spanning GPU memory, CPU memory, and disk/remote backends. The diagram below illustrates how KV cache blocks move across these layers.
+
+**Multi-Tier Storage Architecture**
+
+LMCache implements a hierarchical storage system with three distinct tiers:
+
+* **GPU Memory**: Holds the active working set of KV caches that are currently being used by the model
+* **CPU DRAM**: Acts as a "hot cache" for recently used KV chunks, using pinned memory for efficient GPU-CPU transfers
+* **Local storage (e.g., local disk, NVMe GDS)**: Provides a large tier for local KV caching (e.g. for long documents)
+* **Remote storage (e.g., Redis, Mooncake, InfiniStore)**: Persistent storage for KV caches. Reliable but not as performant as previous tiers.
+
+**Data Flow and Operations**
+
+When the model generates new key-value (KV) cache chunks on the GPU, LMCache can:
+
+1. **Offload overflow KV caches** from GPU to CPU DRAM, freeing precious GPU memory
+2. **Asynchronously write** KV caches from CPU to disk or remote storage using LRU eviction policies
+3. **Prefetch hot KV caches** from disk/remote storage back to CPU when needed
+4. **On-demand reuse** of cached segments by moving them from CPU back to GPU
+
+This architecture enables LMCache to significantly reduce prefill delays and GPU memory pressure while maintaining high performance through intelligent cache management.
+
+.. mermaid::
+   :align: center
+
+   flowchart TB
+       subgraph "LLM Engine (with LMCache Integration)"
+         direction TB
+         GPU["GPU Memory"]
+         CPU["CPU DRAM"]
+         GPU -- "Offload overflow KV" --> CPU
+         CPU -- "On-demand reuse" --> GPU
+       end
+       Disk[(Disk Storage Backend)]
+       Remote[(Remote Storage Backend)]
+       CPU -- "Async write (LRU evict)" --> Disk
+       CPU -- "Async upload" --> Remote
+       Disk -- "Prefetch hot KV" --> CPU
+       Remote -- "Fetch on reuse" --> CPU
+
+Two modes
+---------
+
+**Storage Mode (KV cache offloading)**
+   LMCache acts as a persistent KV store, optimizing for high reuse across queries or sessions. It offloads infrequently used KV blocks from GPU memory and persists popular caches across sessions, boosting cache hit rates for "hot" content. KV caches survive beyond single inference calls and even process restarts when backed by disk or external storage.
+
+
+.. mermaid::
+
+    sequenceDiagram
+    participant Main as LLM Inference Thread
+    participant DiskTask as Disk Offload Task
+    participant RemoteTask as Remote Offload Task
+    Main->>Main: New KV chunk created (GPU memory)
+    Main->>Main: Copy KV chunk to CPU buffer
+    par Disk backend offload
+        Main--)DiskTask: Spawn async disk write task
+        DiskTask-->>DiskTask: Compress & save chunk to disk
+    and Remote backend offload
+        Main--)RemoteTask: Spawn async remote upload task
+        RemoteTask-->>RemoteTask: Send chunk to remote store
+    end
+    Main-->>Main: Continue with next inference (no blocking)
+
+
+**Transport Mode (Prefill-decode disaggregation)**
+   Focuses on accelerating distributed inference by routing KV cache data between nodes in real-time. Enables prefill-decode disaggregation where one server computes KV for prompts and delivers them to another server for generation without recomputation. Uses peer-to-peer channels with communication libraries like NIXL for low-latency, high-bandwidth transfers.
+
+
+Core Components
+---------------
+
+**LLM Inference Engine Integration Module (Connector)**
+   Integrated into the LLM engine (vLLM), the Connector taps into the paged KV memory manager. During prompt processing, it checks if token sequences were seen before:
+
+   * **Cache hit**: Fetches precomputed KV cache chunks from LMCache, bypassing computation
+   * **Cache miss**: Model computes KV as usual, then Connector hands newly-generated KV data to LMCache for storage
+
+**Cache Index (Token Database)**
+   Maintains an internal index mapping token sequences to cached KV entries and their locations. Enables cross-request and cross-instance cache lookups with configurable chunking strategy (default 256 tokens) and hashing scheme.
+
+**Memory Object & Allocator**
+   Manages KV cache entries as MemoryObj instances using a custom memory allocator within LocalCPUBackend. Ensures pinned memory for fast GPU↔CPU transfers, NUMA-aware allocation, and interfaces with eviction policies (LRU by default).
+
+**Asynchronous Offloading**
+   Offloading / loading the KV cache chunks in an asynchronous manner to avoid blocking inference threads and GPU cycles.
+
+**Remote Connectors**
+   Plugin-based system for remote backends (Redis, Mooncake, NiXL). Uses generic RemoteBackend wrapper that delegates operations to connector implementations, supporting dynamic loading of custom backends.
+
+LMCache Controller
+------------------
+
+The Controller provides a management API for runtime cache operations:
+
+* **Lookup**: Query cache entries for given token sequences and their locations
+* **Clear**: Purge KV cache entirely or for specific entries
+* **Compress/Decompress**: On-demand compression using CacheGen or decompression to full precision
+* **Move**: Migrate caches to specified locations for cache warming or optimization
+* **Pin/Unpin**: Mark cache entries as persistent to prevent eviction
+* **Health & Finish Checks**: Report worker health and confirm completion of async operations
+
+The Controller coordinates with all LMCache workers in the system, providing centralized management for both single-instance and distributed deployments.
+
+
diff --git a/docs/source/developer_guide/cli.rst b/docs/source/developer_guide/cli.rst
new file mode 100644
index 0000000..9013637
--- /dev/null
+++ b/docs/source/developer_guide/cli.rst
@@ -0,0 +1,503 @@
+Extending the CLI
+=================
+
+LMCache's CLI is built on a plugin-style architecture that supports
+**N-level nested subcommands** with zero-registration auto-discovery.
+This guide explains how to add commands at each level.
+
+Architecture Overview
+---------------------
+
+The CLI framework is composed of two core classes in
+``lmcache/cli/commands/base.py``:
+
+- **BaseCommand** — Abstract base class for leaf commands (commands that
+  perform actual work).
+- **CompositeCommand** — A ``BaseCommand`` subclass for commands that
+  only group sub-subcommands. It auto-discovers child commands by
+  scanning the package where it is defined.
+
+The discovery mechanism uses ``pkgutil.iter_modules`` to scan direct
+submodules of a package, then collects all concrete ``BaseCommand``
+subclasses found in those modules. This means:
+
+1. Each command is a separate ``.py`` file (or a sub-package with an
+   ``__init__.py``).
+2. No manual registration is needed — just create the file and it is
+   picked up automatically.
+3. Utility/helper modules should be prefixed with ``_`` (e.g.
+   ``_helpers.py``) so they are excluded from the scan.
+
+Auto-Discovery Mechanism
+------------------------
+
+The CLI uses a unified ``discover_subclasses()`` utility (defined in
+``lmcache/v1/utils/subclass_discovery.py``) to locate command classes at
+every level.  Understanding the two discovery entry points is key to
+extending the CLI.
+
+Top-Level Command Discovery
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the CLI starts, ``lmcache/cli/commands/__init__.py`` calls
+``discover_subclasses()`` on its own package (``lmcache.cli.commands``).
+This scans all **direct submodules** — both ``.py`` files and
+sub-packages (via their ``__init__.py``) — and collects every concrete
+``BaseCommand`` subclass found.
+
+.. code-block:: python
+
+   # Simplified from lmcache/cli/commands/__init__.py
+   from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+   ALL_COMMANDS = [
+       cls()
+       for cls in discover_subclasses(
+           __name__,                          # "lmcache.cli.commands"
+           BaseCommand,
+           module_filter=lambda name: name != "base",  # skip base.py itself
+       )
+   ]
+
+The resulting ``ALL_COMMANDS`` list is then registered with the root
+``argparse`` parser in ``main.py``.  This means any new ``.py`` file (or
+sub-package) placed under ``lmcache/cli/commands/`` is automatically
+available as a top-level command — no manual imports or registration
+needed.
+
+**Filtering rules for top-level discovery:**
+
+- The module named ``base`` is explicitly excluded (it defines the
+  abstract base classes, not a command).
+- Modules whose name starts with ``_`` are excluded by the underlying
+  ``pkgutil.iter_modules`` convention (they are treated as private).
+- Only **concrete** subclasses are collected — abstract classes are
+  skipped.
+- Only classes **defined in** the scanned module are collected (re-exports
+  are ignored via ``require_defined_in_module=True``).
+
+Sub-Command Discovery (CompositeCommand)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When a ``CompositeCommand`` registers itself with the parser, its
+``register()`` method calls ``discover_subclasses()`` on the package
+where the ``CompositeCommand`` subclass is defined (i.e. its own
+``__init__.py``'s package).
+
+.. code-block:: python
+
+   # Simplified from CompositeCommand.register() in base.py
+   package = self.__class__.__module__   # e.g. "lmcache.cli.commands.bench"
+
+   for cls in discover_subclasses(
+       package,
+       BaseCommand,
+       module_filter=lambda name: not name.startswith("_"),
+       require_defined_in_module=True,
+   ):
+       if cls is self.__class__:
+           continue          # skip the CompositeCommand itself
+       inst = cls()
+       inst.register(inner)  # register as a nested subcommand
+
+**Filtering rules for sub-command discovery:**
+
+- Modules starting with ``_`` are excluded (use this prefix for helper
+  files like ``_utils.py``).
+- The ``CompositeCommand`` class itself is skipped to avoid infinite
+  recursion.
+- Only concrete ``BaseCommand`` subclasses **defined in** the scanned
+  module are collected.
+- The scan is **non-recursive** (depth 1 only) — each
+  ``CompositeCommand`` only sees its own package's direct children.
+
+**How nesting works:** If a child is itself a ``CompositeCommand``
+(defined in a sub-package's ``__init__.py``), its own ``register()``
+method will in turn scan *its* package for further children.  This
+creates the recursive nesting without any special configuration.
+
+.. code-block:: text
+
+   CLI startup
+   └── __init__.py discovers ALL top-level commands
+       ├── ping.py          → PingCommand (leaf)
+       ├── bench/__init__.py → BenchCommand (composite)
+       │   └── BenchCommand.register() discovers:
+       │       ├── server_bench/__init__.py → ServerBenchCommand (leaf)
+       │       ├── l2_adapter_bench/__init__.py → L2AdapterBenchCommand (leaf)
+       │       └── engine_bench/__init__.py → EngineBenchCommand (leaf)
+       └── tool/__init__.py → ToolCommand (composite)
+           └── ToolCommand.register() discovers:
+               └── cache_simulator/__init__.py → CacheSimulatorCommand (composite)
+                   └── CacheSimulatorCommand.register() discovers:
+                       ├── simulate_command.py     → SimulateCommand (leaf)
+                       ├── sweep_command.py        → SweepCommand (leaf)
+                       └── gen_dataset_command.py  → GenDatasetCommand (leaf)
+
+Directory Layout
+----------------
+
+.. code-block:: text
+
+   lmcache/cli/commands/
+   ├── __init__.py            # Top-level discovery (scans this package)
+   ├── base.py                # BaseCommand & CompositeCommand
+   ├── ping.py                # Level-1 leaf command
+   ├── server.py              # Level-1 leaf command
+   ├── quota/                 # Level-2 composite command
+   │   ├── __init__.py        # QuotaCommand(CompositeCommand)
+   │   ├── _helpers.py        # Utility (excluded from scan by _ prefix)
+   │   ├── get_command.py     # Level-2 leaf: ``lmcache quota get``
+   │   ├── set_command.py     # Level-2 leaf: ``lmcache quota set``
+   │   └── ...
+   └── tool/                  # Level-2 composite command
+       ├── __init__.py         # ToolCommand(CompositeCommand)
+       └── cache_simulator/    # Level-3 composite command
+           ├── __init__.py     # CacheSimulatorCommand(CompositeCommand)
+           ├── simulate_command.py   # Level-3 leaf: ``lmcache tool cache-simulator simulate``
+           └── sweep_command.py      # Level-3 leaf: ``lmcache tool cache-simulator sweep``
+
+Key Rules
+^^^^^^^^^
+
+- A ``CompositeCommand`` subclass **must** be defined in the
+  ``__init__.py`` of its package.
+- Modules starting with ``_`` are **excluded** from auto-discovery
+  (use this for helpers, utilities, internal logic).
+- Each leaf command file should contain exactly one concrete
+  ``BaseCommand`` subclass.
+- The scan is **non-recursive** — each ``CompositeCommand`` only scans
+  its own package's direct submodules.
+
+Level 1: Adding a Top-Level Command
+------------------------------------
+
+A top-level command appears directly under ``lmcache <command>``.
+
+**Step 1**: Create a new file under ``lmcache/cli/commands/``:
+
+.. code-block:: python
+
+   # lmcache/cli/commands/hello.py
+   """``lmcache hello`` — a simple greeting command."""
+
+   import argparse
+
+   from lmcache.cli.commands.base import BaseCommand
+
+
+   class HelloCommand(BaseCommand):
+       """Print a greeting message."""
+
+       def name(self) -> str:
+           return "hello"
+
+       def help(self) -> str:
+           return "Print a greeting message."
+
+       def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+           parser.add_argument("--name", default="World", help="Who to greet.")
+
+       def execute(self, args: argparse.Namespace) -> None:
+           metrics = self.create_metrics("Hello", args)
+           metrics.add("greeting", "Greeting", f"Hello, {args.name}!")
+           metrics.emit()
+
+**Step 2**: Done! The command is automatically discovered. Test it:
+
+.. code-block:: bash
+
+   lmcache hello --name LMCache
+
+.. note::
+
+   This works because the top-level ``lmcache/cli/commands/__init__.py``
+   calls ``discover_subclasses`` on its own package at import time. It
+   uses ``pkgutil.iter_modules`` to find all direct submodules (files and
+   sub-packages), imports each one, and collects every concrete
+   ``BaseCommand`` subclass. The resulting list is stored in
+   ``ALL_COMMANDS`` and registered with the argument parser in
+   ``main.py``. So adding a new ``.py`` file with a ``BaseCommand``
+   subclass is all that is needed — no edits to any other file.
+
+Level 2: Adding a Subcommand Group
+-----------------------------------
+
+A subcommand group appears as ``lmcache <group> <subcommand>``.
+
+**Step 1**: Create a package directory:
+
+.. code-block:: bash
+
+   mkdir lmcache/cli/commands/mygroup/
+
+**Step 2**: Define the ``CompositeCommand`` in ``__init__.py``:
+
+.. code-block:: python
+
+   # lmcache/cli/commands/mygroup/__init__.py
+   """``lmcache mygroup`` command group.
+
+   Sub-subcommands are auto-discovered from modules in this package.
+   """
+
+   from lmcache.cli.commands.base import CompositeCommand
+
+
+   class MyGroupCommand(CompositeCommand):
+       """Command group for my custom operations."""
+
+       def name(self) -> str:
+           return "mygroup"
+
+       def help(self) -> str:
+           return "My custom command group."
+
+**Step 3**: Add leaf subcommands as separate files:
+
+.. code-block:: python
+
+   # lmcache/cli/commands/mygroup/foo_command.py
+   """``lmcache mygroup foo`` — do something."""
+
+   import argparse
+
+   from lmcache.cli.commands.base import BaseCommand
+
+
+   class FooCommand(BaseCommand):
+       """Execute the foo action."""
+
+       def name(self) -> str:
+           return "foo"
+
+       def help(self) -> str:
+           return "Execute the foo action."
+
+       def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+           parser.add_argument("--value", type=int, required=True)
+
+       def execute(self, args: argparse.Namespace) -> None:
+           metrics = self.create_metrics("Foo Result", args)
+           metrics.add("result", "Result", args.value * 2)
+           metrics.emit()
+
+**Step 4**: (Optional) Add helper modules with ``_`` prefix:
+
+.. code-block:: python
+
+   # lmcache/cli/commands/mygroup/_utils.py
+   """Internal utilities for mygroup commands (not auto-discovered)."""
+
+   def compute_something(x: int) -> int:
+       return x * 42
+
+**Result**:
+
+.. code-block:: bash
+
+   lmcache mygroup foo --value 5
+
+Level 2: Adding a Subcommand to an Existing Group
+---------------------------------------------------
+
+If a ``CompositeCommand`` group already exists (e.g. ``bench``, ``quota``,
+``trace``), you can extend it by simply adding **one new file** — no other
+changes are required.
+
+For example, to add a new ``lmcache bench l2`` subcommand under the
+existing ``bench`` group:
+
+**Step 1**: Create a single file (or sub-package) in the existing group's
+package directory:
+
+.. code-block:: python
+
+   # lmcache/cli/commands/bench/l2_adapter_bench/__init__.py
+   """``lmcache bench l2`` subpackage."""
+
+   import argparse
+
+   from lmcache.cli.commands.base import BaseCommand
+
+
+   class L2AdapterBenchCommand(BaseCommand):
+       """Benchmark an L2 adapter (store / lookup / load)."""
+
+       def name(self) -> str:
+           return "l2"
+
+       def help(self) -> str:
+           return "Benchmark an L2 adapter (store / lookup / load)."
+
+       def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+           from lmcache.cli.commands.bench.l2_adapter_bench.command import (
+               add_l2_arguments,
+           )
+           add_l2_arguments(parser)
+
+       def execute(self, args: argparse.Namespace) -> None:
+           from lmcache.cli.commands.bench.l2_adapter_bench.command import (
+               run_l2_adapter_bench,
+           )
+           run_l2_adapter_bench(self, args)
+
+**Step 2**: Done! The parent ``CompositeCommand`` (``BenchCommand``)
+auto-discovers the new subcommand at startup. No registration code, no
+imports to add, no ``__init__.py`` edits in the parent.
+
+.. note::
+
+   This works because ``CompositeCommand.register()`` scans all direct
+   submodules of its package each time the CLI starts. A new file (or
+   sub-package) is automatically picked up as long as:
+
+   - It does **not** start with ``_``.
+   - It contains a concrete ``BaseCommand`` subclass.
+
+Level N: Arbitrary Nesting
+--------------------------
+
+The framework supports **unlimited nesting depth**. Each level follows
+the same pattern: a ``CompositeCommand`` in a package's ``__init__.py``
+auto-discovers its children.
+
+**Example**: Adding a 3rd level under ``lmcache mygroup``:
+
+.. code-block:: bash
+
+   mkdir lmcache/cli/commands/mygroup/nested/
+
+.. code-block:: python
+
+   # lmcache/cli/commands/mygroup/nested/__init__.py
+   """``lmcache mygroup nested`` — a nested command group."""
+
+   from lmcache.cli.commands.base import CompositeCommand
+
+
+   class NestedCommand(CompositeCommand):
+       """Nested subcommand group."""
+
+       def name(self) -> str:
+           return "nested"
+
+       def help(self) -> str:
+           return "A nested command group under mygroup."
+
+.. code-block:: python
+
+   # lmcache/cli/commands/mygroup/nested/bar_command.py
+   """``lmcache mygroup nested bar`` — a deeply nested command."""
+
+   import argparse
+
+   from lmcache.cli.commands.base import BaseCommand
+
+
+   class BarCommand(BaseCommand):
+       """Execute the bar action at level 3."""
+
+       def name(self) -> str:
+           return "bar"
+
+       def help(self) -> str:
+           return "Execute the bar action."
+
+       def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+           parser.add_argument("--msg", default="deep")
+
+       def execute(self, args: argparse.Namespace) -> None:
+           metrics = self.create_metrics("Bar Result", args)
+           metrics.add("message", "Message", args.msg)
+           metrics.emit()
+
+**Result**:
+
+.. code-block:: bash
+
+   lmcache mygroup nested bar --msg "hello from level 3"
+
+You can continue nesting indefinitely by repeating this pattern.
+
+Real-World Example
+------------------
+
+The existing ``lmcache tool cache-simulator simulate`` command
+demonstrates 3-level nesting:
+
+.. code-block:: text
+
+   lmcache tool cache-simulator simulate
+   │       │    │               └── Level-3 leaf (SimulateCommand in simulate_command.py)
+   │       │    └── Level-2 composite (CacheSimulatorCommand in cache_simulator/__init__.py)
+   │       └── Level-1 composite (ToolCommand in tool/__init__.py)
+   └── CLI entry point
+
+Using the Metrics System
+------------------------
+
+The metrics system uses a **handler + formatter** architecture:
+
+- **Metrics** — the collector. Holds sections and entries.
+- **Handler** — the destination (stdout, file, etc.).
+- **Formatter** — the rendering (ASCII table, JSON, etc.).
+
+``BaseCommand.create_metrics()`` sets up default handlers automatically, so
+command authors just build metrics and call ``emit()``:
+
+.. code-block:: python
+
+   def execute(self, args: argparse.Namespace) -> None:
+       # create_metrics() auto-registers:
+       #   - StreamHandler → stdout (formatter chosen by --format, default: terminal)
+       #   - FileHandler   → if --output is set (same format as --format)
+       metrics = self.create_metrics("Bench KV Cache Result", args)
+
+       # Create named sections
+       metrics.add_section("ops", "Operations (ops/s)")
+       metrics["ops"].add("store", "Store", 41.3)
+       metrics["ops"].add("retrieve", "Retrieve", 127.3)
+
+       # Top-level metrics (no section header)
+       metrics.add("status", "Status", "OK")
+
+       # Trigger all handlers
+       metrics.emit()
+
+The ``--format`` and ``--output`` flags are added automatically by
+``BaseCommand.register()`` — subcommands do not need to add them manually.
+
+Summary
+-------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 25 60
+
+   * - Level
+     - Pattern
+     - How to add
+   * - 1 (top)
+     - Single ``.py`` file
+     - Create ``lmcache/cli/commands/<name>.py`` with a ``BaseCommand``
+       subclass.
+   * - 2+
+     - Package directory
+     - Create ``lmcache/cli/commands/<group>/__init__.py`` with a
+       ``CompositeCommand`` subclass, then add leaf commands as sibling
+       ``.py`` files.
+   * - N (any)
+     - Nested package
+     - Same as level 2, but inside an existing composite command's
+       package. Each ``CompositeCommand`` scans only its own direct
+       submodules.
+
+.. tip::
+
+   - Prefix helper/utility modules with ``_`` to exclude them from
+     auto-discovery.
+   - Each ``CompositeCommand`` must be defined in its package's
+     ``__init__.py``.
+   - The ``name()`` method determines the CLI token (e.g. ``"foo"``
+     becomes ``lmcache ... foo``).
diff --git a/docs/source/developer_guide/contributing.rst b/docs/source/developer_guide/contributing.rst
new file mode 100644
index 0000000..dd963a5
--- /dev/null
+++ b/docs/source/developer_guide/contributing.rst
@@ -0,0 +1,204 @@
+Contributing Guide
+==================
+
+Thank you for your interest in contributing to LMCache! We welcome and accept all kinds of contributions, no matter how small or large. There are several ways you can contribute to the project:
+
+- Identify and report any issues or bugs
+- Request or add support for a new model
+- Suggest or implement new features
+- Improve documentation or contribute a how-to guide
+
+A comprehensive list of good first issues can be found in the issue `[Onboarding 2026] Good first issues — start contributing to LMCache in one PR <https://github.com/LMCache/LMCache/issues/3372>`_.
+
+If you'd like to support our community further, then answering queries, offering PR reviews, and assisting others are also impactful ways to contribute and take LMCache further.
+
+Finally, you can support us by raising awareness about LMCache. Feel free to share our blog posts, check out our handle on X at `LMCache <https://x.com/lmcache>`_ and see the latest of what we are up to. If using LMCache helped your project or product in any way, you can simply offer your appreciation by starring our repository!
+
+License
+-------
+
+See the `LICENSE <https://github.com/LMCache/LMCache/blob/dev/LICENSE>`_ file for details.
+
+Code of Conduct
+---------------
+
+This project adheres to the `Code of Conduct <https://github.com/LMCache/LMCache/blob/dev/CODE_OF_CONDUCT.md>`_. By participating, you are expected to uphold this code.
+
+Contribution Guidelines
+-----------------------
+
+Help on open source projects is always welcome and there is always something that can be improved. For example, documentation (like the text you are reading now) can always use improvement, code can always be clarified, variables or functions can always be renamed or commented on, and there is always a need for more test coverage. If you see something that you think should be fixed, take ownership! Here is how you get started.
+
+How Can I Contribute?
+^^^^^^^^^^^^^^^^^^^^^
+
+When contributing, it's useful to start by looking at `issues <https://github.com/LMCache/LMCache/issues>`_. After picking up an issue, writing code, or updating a document, make a pull request and your work will be reviewed and merged. If you're adding a new feature or find a bug, it's best to `write an issue <https://github.com/LMCache/LMCache/issues/new>`_ first to discuss it with maintainers.
+
+If you discover a security vulnerability, please follow the instructions in the `Security doc <https://github.com/LMCache/LMCache/blob/dev/SECURITY.md>`_.
+
+To contribute to this repo, you'll use the Fork and Pull model common in many open source repositories. For details on this process, check out `The GitHub Workflow Guide <https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md>`_ from Kubernetes. In short:
+
+- Fork the repository
+- Create a branch
+- Run code style checks and fix any issues
+- Run unit tests and fix any broken tests
+- Submit a pull request with detailed descriptions
+
+When your contribution is ready, you can create a pull request. Pull requests are often referred to as "PRs". In general, we follow the standard `GitHub pull request <https://help.github.com/en/articles/about-pull-requests>`_ process. Follow the template to provide details about your pull request to the maintainers.
+
+Please try to classify PRs for easy understanding of the type of changes. The PR title is prefixed appropriately to indicate the type of change. Please use one of the following:
+
+- [Bugfix] for bug fixes
+- [Build] for build fixes and improvements
+- [CI] for continuous integration fixes and iimprovements
+- [Core] for changes in the core LMCache logic (e.g., ``LMCacheEngine``, ``Backend`` etc.)
+- [Doc] for documentation fixes and improvements
+- [Misc] for PRs that do not fit the above categories. Please use this sparingly
+- [Model] for adding a new model or improving an existing model. Model name should appear in the title
+- [Test] for unit tests
+
+.. note::
+
+    If the PR spans more than one category, please include all relevant prefixes
+
+It's best to break your contribution into smaller PRs with incremental changes, and include a good description of the changes. We require new unit tests to be contributed with any new functionality added and docs if user facing changes.
+
+Before sending pull requests, make sure your changes pass code quality checks and unit tests. These checks will run when the pull request builds. Alternatively, you can run the checks manually on your local machine `as specified in Development <#development>`_ .
+
+DCO and Signed-off-by
+^^^^^^^^^^^^^^^^^^^^^
+
+When contributing changes to the project, you must agree to the `DCO <https://github.com/LMCache/LMCache/blob/dev/DCO>`_. Commits must include a :code:`Signed-off-by` header which certifies agreement with the terms of the `DCO <https://github.com/LMCache/LMCache/blob/dev/DCO>`_.
+
+.. note::
+
+    Using :code:`-s` or :code:`--signoff` flag with :code:`git commit` will automatically add this header. The flags can also be used with :code:`--amend` if you forget to sign your last commit.
+
+Code Review
+^^^^^^^^^^^
+
+Once you've created a pull request, maintainers will review your code and may make suggestions to fix before merging. It will be easier for your pull request to receive reviews if you consider the criteria the reviewers follow while working. Remember to:
+
+- Document the code well to help future contributors and maintainers
+- Follow the project coding conventions for consistency and best practices
+- Include sufficient tests to maintain robustness of the code
+- Add or update documentation in :code:`/docs` if PR modifies user facing behavior to help people using LMCache
+- Run coding style checks to ensure consistency and correctness
+- Run tests locally and ensure they pass and don't break the existing code base
+- Write detailed commit messages to help future contributors and maintainers
+- Break large changes into a logical series of smaller patches, which are easy to understand individually and combine to solve a broader issue
+
+.. note::
+
+    Maintainers will perform "squash and merge" actions on PRs in this repo, so it doesn't matter how many commits your PR has, as they will end up being a single commit after merging.
+
+Development
+-----------
+
+Set up your dev environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following prerequisites are required:
+
+- OS: Linux
+- GPU: NVIDIA compute capability 7.0+ (e.g., V100, T4, RTX20xx, A100, L4, H100, etc.)
+- CUDA 12.8+
+
+The following tools are required:
+
+- `git <https://git-scm.com>`_
+- `python <https://www.python.org>`_ (v3.10 -- v3.13)
+- `pip <https://pypi.org/project/pip/>`_ (v23.0+)
+
+The first step is to install the necessary Python packages required for development. The commands to do this are as follows:
+
+.. code-block:: bash
+
+    # Equivalent to pip install -r requirements/common.txt
+    pip install -e .
+
+    pip install -r requirements/lint.txt
+    pip install -r requirements/test.txt
+
+Before pushing changes to GitHub, you need to run the coding style checks and unit tests as shown below.
+
+Coding style
+^^^^^^^^^^^^
+
+LMCache follows the Python `pep8 <https://peps.python.org/pep-0008/>`_ coding style for Python and `Google C++ style guide <https://google.github.io/styleguide/cppguide.html>`_ for C++. We use the following tools to enforce the coding style:
+
+- Python linting and formatting: `Ruff <https://docs.astral.sh/ruff/>`_, and `isort <https://pycqa.github.io/isort/>`_
+- Python static code checking: `mypy <https://github.com/python/mypy>`_
+- Spell checking: `codespell <https://github.com/codespell-project/codespell>`_
+- C++ formatting: `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_
+
+The tools are managed by `pre-commit <https://pre-commit.com/>`_. It is installed as follows:
+
+.. code-block:: bash
+
+    pip install -r requirements/lint.txt
+    pre-commit install
+
+It will run automatically when you add a commit. You can also run it manually on all files with the following command:
+
+.. code-block:: bash
+
+    pre-commit run --all-files
+
+.. note::
+
+    For all new code added, please write docstrings in `sphinx-doc format <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_.
+
+Unit tests
+^^^^^^^^^^
+
+When making changes, run the tests before pushing the changes. Running unit tests ensures your contributions do not break existing code. We use the `pytest <https://docs.pytest.org/>`_ framework to run unit tests. The framework is setup to run all files in the `tests <https://github.com/LMCache/LMCache/tree/dev/tests>`_ directory which have a prefix or posfix of "test".
+
+Running unit tests is as simple as:
+
+.. code-block:: bash
+
+    pytest
+
+.. note::
+
+    ``vLLM`` (``pip install vllm``) and the dependencies in ``requirements/test.txt`` need to be installed prior to running unit tests.
+
+By default, all tests found within the tests directory are run. However, specific unit tests can run by passing filenames, classes and/or methods to `pytest`. The following example invokes a single test method "test_lm_connector" that is declared in the "tests/test_connector.py" file:
+
+.. code-block:: bash
+
+    pytest tests/test_connector.py::test_lm_connector
+
+.. note::
+
+    Some unit tests require a NVIDIA GPU. This means that on a non Linux NVIDIA GPU system, the full suite of tests will not be run (tests requiring CUDA will be skipped). The Buildkite continuous integration (CI)  system executes a full run of all the tests.
+
+.. note::
+
+    The `NVIDIA Inference Xfer Library (NIXL) <https://github.com/ai-dynamo/nixl>`_ unit tests require NIXL to be to be installed. This is not installed by LMCache by and therefore requires you to install it separately. Please follow the details in the NIXL GitHub repo to install.
+    If the NIXL package is not installed, the NIXL unit tests are skipped.
+
+Building the docs
+^^^^^^^^^^^^^^^^^
+
+Install the dependencies:
+
+.. code-block:: bash
+
+    pip install -r requirements/docs.txt
+
+After that, you can build the docs (from :code:`docs/` directory) using `make`:
+
+.. code-block:: bash
+
+    make clean
+    make html
+
+Serve docs page locally at http://localhost:8000: :code:`python -m http.server -d build/html/`
+
+Thank You
+---------
+
+Thank you for your contribution to LMCache and making it a better, and accessible framework for all. 
+
diff --git a/docs/source/developer_guide/extending_http_api.rst b/docs/source/developer_guide/extending_http_api.rst
new file mode 100644
index 0000000..deac4f5
--- /dev/null
+++ b/docs/source/developer_guide/extending_http_api.rst
@@ -0,0 +1,109 @@
+Extending the HTTP API
+======================
+
+You can add new endpoints to the ``lmcache server`` HTTP frontend **without
+modifying any existing code**. An endpoint is just a Python module placed in
+``lmcache/v1/multiprocess/http_apis/`` that exposes a FastAPI ``APIRouter``;
+``HTTPAPIRegistry`` auto-discovers and mounts it at startup -- the same
+zero-modification pattern used by the :doc:`L2 adapters
+</mp/l2_storage/index>`.
+
+How discovery works
+-------------------
+
+At startup, ``http_server.py`` hands the FastAPI app to ``HTTPAPIRegistry``
+(``lmcache/v1/multiprocess/http_api_registry.py``), which scans the
+``http_apis/`` directory with ``pkgutil``, imports every module whose name ends
+with ``_api``, and includes any module-level ``router``. The built-in modules
+follow this pattern:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 20 12 40
+
+   * - Module
+     - Endpoint
+     - Method
+     - Description
+   * - ``info_api.py``
+     - ``/``
+     - GET
+     - Basic liveness check
+   * - ``info_api.py``
+     - ``/healthcheck``
+     - GET
+     - Kubernetes probe endpoint
+   * - ``cache_api.py``
+     - ``/cache/clear``
+     - POST
+     - Force-clear the L1 cache
+   * - ``info_api.py``
+     - ``/status``
+     - GET
+     - Internal status report
+
+Adding an endpoint
+------------------
+
+Create a file in ``lmcache/v1/multiprocess/http_apis/`` whose name ends with
+``_api.py`` and expose a ``router``:
+
+.. code-block:: python
+
+   # lmcache/v1/multiprocess/http_apis/metrics_api.py
+   # SPDX-License-Identifier: Apache-2.0
+   from fastapi import APIRouter, Request
+   from fastapi.responses import JSONResponse
+
+   router = APIRouter()
+
+
+   @router.get("/metrics")
+   async def metrics(request: Request):
+       """Return cache hit/miss metrics."""
+       engine = getattr(request.app.state, "engine", None)
+       if engine is None:
+           return JSONResponse(
+               status_code=503,
+               content={"error": "engine not initialized"},
+           )
+       return {"hits": 42, "misses": 7}
+
+That's it -- ``HTTPAPIRegistry`` discovers and mounts it on the next server
+startup; no other file needs to change.
+
+Module contract
+---------------
+
+An API module **must**:
+
+- live in ``lmcache/v1/multiprocess/http_apis/`` with a filename ending in
+  ``_api.py``;
+- expose a module-level ``router`` of type ``fastapi.APIRouter``.
+
+An API module **should**:
+
+- guard against uninitialized state by checking ``request.app.state.engine``
+  and returning ``503`` when it is ``None``;
+- use ``lmcache.logging.init_logger(__name__)`` for logging;
+- use ``async`` handlers and avoid blocking I/O.
+
+An API module **must not** import or mutate the ``app`` object from
+``http_server.py``.
+
+Accessing shared state
+----------------------
+
+``app.state`` is the shared context populated during server startup. Reach it
+through the request object:
+
+.. code-block:: python
+
+   @router.get("/my-endpoint")
+   async def my_endpoint(request: Request):
+       engine = request.app.state.engine          # main cache engine
+       zmq_server = request.app.state.zmq_server   # underlying ZMQ server
+       ...
+
+For the full design rationale see
+``docs/design/v1/multiprocess/http_api_extension.md`` in the source tree.
diff --git a/docs/source/developer_guide/extending_lmcache/native_connectors.rst b/docs/source/developer_guide/extending_lmcache/native_connectors.rst
new file mode 100644
index 0000000..b77e582
--- /dev/null
+++ b/docs/source/developer_guide/extending_lmcache/native_connectors.rst
@@ -0,0 +1,686 @@
+Adding Native Backends
+======================
+
+.. _native-connectors-overview:
+
+Overview
+--------
+
+Native connectors are high-performance C++ storage backends that integrate with LMCache
+through pybind11. They work in **both** LMCache operating modes:
+
+- **Non-MP mode** (single process): via ``ConnectorClientBase`` (asyncio integration)
+- **MP mode** (multiprocess): via ``NativeConnectorL2Adapter`` (L2 adapter interface)
+
+Write the connector once, get both modes for free.
+
+The framework lives in ``csrc/storage_backends/`` with the Redis RESP connector as the
+reference implementation.
+
+Architecture
+~~~~~~~~~~~~
+
+.. code-block:: text
+
+    Non-MP mode:
+      CacheEngine -> RemoteBackend -> ConnectorClientBase -> native client (C++)
+                                        (asyncio event loop)
+
+    MP mode:
+      StoreController / PrefetchController
+            |
+      NativeConnectorL2Adapter (Python bridge)
+        +-- 3 eventfds (store, lookup, load)
+        +-- completion demux thread
+        +-- ObjectKey <-> string serialization
+        +-- client-side lock tracking
+            |
+      native client (C++)
+        +-- 1 eventfd, worker threads, GIL-free I/O
+
+**Design principles:**
+
+1. **GIL release** at the pybind layer for true concurrency between native threads
+2. **Batching with tiling**: work for a batched request is split evenly among threads
+3. **eventfd-based completions**: the kernel wakes Python -- no polling
+4. **Non-blocking submission**: submission queue / completion queue architecture
+
+
+Step 1: C++ Connector
+---------------------
+
+Create your connector directory (e.g., ``csrc/storage_backends/mybackend/``) and
+inherit from ``ConnectorBase<YourConnectionType>``. You need to override 4 required methods
+(and optionally ``do_single_delete`` to support eviction).
+
+**connector.h:**
+
+.. code-block:: cpp
+
+    // csrc/storage_backends/mybackend/connector.h
+    #pragma once
+    #include "../connector_base.h"
+
+    namespace lmcache {
+    namespace connector {
+
+    // Per-thread connection state
+    struct MyConn {
+      int fd = -1;
+      // your connection fields
+    };
+
+    class MyConnector : public ConnectorBase<MyConn> {
+     public:
+      MyConnector(std::string host, int port, int num_workers)
+          : ConnectorBase(num_workers), host_(host), port_(port) {
+        start_workers();  // IMPORTANT: call at END of constructor
+      }
+
+     protected:
+      // 1. Create a connection (called once per worker thread)
+      MyConn create_connection() override {
+        MyConn conn;
+        // connect to server...
+        return conn;
+      }
+
+      // 2. GET: read value for key into buf
+      void do_single_get(MyConn& conn, const std::string& key,
+                         void* buf, size_t len,
+                         size_t chunk_size) override {
+        // send GET command, recv response into buf
+      }
+
+      // 3. SET: write data from buf under key
+      void do_single_set(MyConn& conn, const std::string& key,
+                         const void* buf, size_t len,
+                         size_t chunk_size) override {
+        // send SET command with data from buf
+      }
+
+      // 4. EXISTS: check if key exists
+      bool do_single_exists(MyConn& conn,
+                            const std::string& key) override {
+        // send EXISTS, return true/false
+      }
+
+      // 5. DELETE: remove key (optional, has default no-op)
+      bool do_single_delete(MyConn& conn,
+                            const std::string& key) override {
+        // send DELETE, return true if deleted, false if not found
+      }
+
+      // Optional: clean shutdown
+      void shutdown_connections() override {
+        // close sockets, free resources
+      }
+
+     private:
+      std::string host_;
+      int port_;
+    };
+
+    }  // namespace connector
+    }  // namespace lmcache
+
+**What ConnectorBase gives you for free:**
+
+- Worker thread pool with per-thread connections
+- Submission queue (lock-free enqueue) and completion queue
+- Automatic tiling: batch operations are split across workers
+- eventfd signaling on completion (kernel wakes Python)
+- Graceful shutdown (stop flag, drain, join)
+
+.. important::
+   Always call ``start_workers()`` at the **end** of your derived constructor,
+   after all member variables are initialized. Worker threads call
+   ``create_connection()`` immediately, so the object must be fully constructed.
+
+**Reference:** ``csrc/storage_backends/redis/connector.h`` and ``connector.cpp``
+
+
+Step 2: Pybind Module
+---------------------
+
+Use the ``LMCACHE_BIND_CONNECTOR_METHODS`` macro, which binds all 7 methods
+(``event_fd``, ``submit_batch_get/set/exists/delete``, ``drain_completions``, ``close``)
+with proper GIL release and Python buffer protocol handling.
+
+.. code-block:: cpp
+
+    // csrc/storage_backends/mybackend/pybind.cpp
+    #include <pybind11/pybind11.h>
+    #include "../connector_pybind_utils.h"
+    #include "connector.h"
+
+    namespace py = pybind11;
+
+    PYBIND11_MODULE(lmcache_mybackend, m) {
+      py::class_<lmcache::connector::MyConnector>(m, "LMCacheMyBackendClient")
+          .def(py::init<std::string, int, int>(),
+               py::arg("host"), py::arg("port"),
+               py::arg("num_workers"))
+          LMCACHE_BIND_CONNECTOR_METHODS(
+              lmcache::connector::MyConnector);
+    }
+
+The pybind utilities automatically:
+
+- Extract buffer pointers from Python ``memoryview`` objects under the GIL
+- Release the GIL before calling into C++
+- Convert C++ ``Completion`` structs to Python tuples ``(future_id, ok, error, result_bools)``
+
+**Reference:** ``csrc/storage_backends/redis/pybind.cpp``
+
+
+Step 3: Build System
+--------------------
+
+Register your C++ sources in ``setup.py`` alongside the existing Redis extension:
+
+.. code-block:: python
+
+    # In cuda_extension() and rocm_extension():
+    mybackend_sources = [
+        "csrc/storage_backends/mybackend/pybind.cpp",
+        "csrc/storage_backends/mybackend/connector.cpp",
+    ]
+
+    # Add to ext_modules list:
+    cpp_extension.CppExtension(
+        "lmcache.lmcache_mybackend",
+        sources=mybackend_sources,
+        include_dirs=[
+            "csrc/storage_backends",
+            "csrc/storage_backends/mybackend",
+        ],
+        extra_compile_args={"cxx": ["-O3", "-std=c++17"]},
+    ),
+
+Then rebuild:
+
+.. code-block:: bash
+
+    pip install -e .
+
+
+Step 4: Python Client (Non-MP Mode)
+------------------------------------
+
+Inherit from ``ConnectorClientBase`` which provides asyncio event loop integration,
+future management, and both sync and async methods.
+
+.. code-block:: python
+
+    # lmcache/v1/storage_backend/native_clients/mybackend_client.py
+    from .connector_client_base import ConnectorClientBase
+    from lmcache.lmcache_mybackend import LMCacheMyBackendClient
+
+    class MyBackendClient(ConnectorClientBase[LMCacheMyBackendClient]):
+        def __init__(self, host: str, port: int,
+                     num_workers: int, loop=None):
+            native = LMCacheMyBackendClient(host, port, num_workers)
+            super().__init__(native, loop)
+
+This gives you ``batch_get``, ``batch_set``, ``batch_exists`` (async), and their
+synchronous variants, all with automatic eventfd-driven completion handling.
+
+**Reference:** ``lmcache/v1/storage_backend/native_clients/resp_client.py``
+
+
+Step 5: L2 Adapter (MP Mode)
+-----------------------------
+
+To use your connector as an L2 adapter in MP mode, create a single Python module that
+defines the config class, factory function, and self-registers both. The
+``NativeConnectorL2Adapter`` bridge handles all the complexity (eventfd demuxing,
+key serialization, locking).
+
+Create a new file in the L2 adapters package:
+
+.. code-block:: python
+
+    # lmcache/v1/distributed/l2_adapters/mybackend_l2_adapter.py
+    from __future__ import annotations
+    from typing import TYPE_CHECKING, Optional
+
+    if TYPE_CHECKING:
+        from lmcache.v1.distributed.internal_api import L1MemoryDesc
+
+    from lmcache.v1.distributed.l2_adapters.base import (
+        L2AdapterInterface,
+    )
+    from lmcache.v1.distributed.l2_adapters.config import (
+        L2AdapterConfigBase,
+        register_l2_adapter_type,
+    )
+    from lmcache.v1.distributed.l2_adapters.factory import (
+        register_l2_adapter_factory,
+    )
+
+
+    class MyBackendL2AdapterConfig(L2AdapterConfigBase):
+        def __init__(self, host: str, port: int,
+                     num_workers: int = 8,
+                     max_capacity_gb: float = 0):
+            self.host = host
+            self.port = port
+            self.num_workers = num_workers
+            self.max_capacity_gb = max_capacity_gb
+
+        @classmethod
+        def from_dict(cls, d: dict) -> "MyBackendL2AdapterConfig":
+            host = d.get("host")
+            if not isinstance(host, str) or not host:
+                raise ValueError("host must be a non-empty string")
+            port = d.get("port")
+            if not isinstance(port, int) or port <= 0:
+                raise ValueError("port must be a positive integer")
+            num_workers = d.get("num_workers", 8)
+            max_capacity_gb = d.get("max_capacity_gb", 0)
+            return cls(host=host, port=port,
+                       num_workers=num_workers,
+                       max_capacity_gb=max_capacity_gb)
+
+        @classmethod
+        def help(cls) -> str:
+            return (
+                "MyBackend L2 adapter config fields:\n"
+                "- host (str): server hostname (required)\n"
+                "- port (int): server port (required)\n"
+                "- num_workers (int): worker threads (default 8)"
+            )
+
+
+    def _create_mybackend_l2_adapter(
+        config: L2AdapterConfigBase,
+        l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+    ) -> L2AdapterInterface:
+        from lmcache.lmcache_mybackend import LMCacheMyBackendClient
+        from lmcache.v1.distributed.l2_adapters \
+            .native_connector_l2_adapter import (
+            NativeConnectorL2Adapter,
+        )
+
+        assert isinstance(config, MyBackendL2AdapterConfig)
+        native_client = LMCacheMyBackendClient(
+            config.host, config.port, config.num_workers
+        )
+        return NativeConnectorL2Adapter(
+            native_client,
+            max_capacity_gb=config.max_capacity_gb,
+        )
+
+
+    # Self-register -- runs automatically when the module
+    # is imported by the L2 adapter auto-discovery mechanism
+    register_l2_adapter_type("mybackend", MyBackendL2AdapterConfig)
+    register_l2_adapter_factory("mybackend", _create_mybackend_l2_adapter)
+
+.. note::
+   The L2 adapter package uses ``pkgutil.iter_modules`` to auto-discover all modules
+   in ``lmcache/v1/distributed/l2_adapters/``. Simply creating the file above is
+   sufficient -- no changes to ``__init__.py`` or any other existing file are needed.
+
+**Usage from the command line:**
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --l2-adapter '{"type": "mybackend", "host": "10.0.0.1", "port": 9000}'
+
+
+How NativeConnectorL2Adapter Bridges the Gap
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The C++ connector has 1 eventfd and mixed completions. MP mode's ``L2AdapterInterface``
+requires 3 separate eventfds and typed results. The bridge handles this transparently:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 25 45
+
+   * - L2 Adapter Method
+     - Native Call
+     - Extra Logic
+   * - ``submit_store_task(keys, objs)``
+     - ``submit_batch_set``
+     - ObjectKey to string, MemoryObj to memoryview
+   * - ``submit_lookup_and_lock_task(keys)``
+     - ``submit_batch_exists``
+     - + client-side lock refcount
+   * - ``submit_load_task(keys, objs)``
+     - ``submit_batch_get``
+     - ObjectKey to string, MemoryObj to memoryview
+   * - ``submit_unlock(keys)``
+     - *(none)*
+     - client-side lock decrement
+   * - ``pop_completed_store_tasks()``
+     - via ``drain_completions``
+     - demux by op type
+   * - ``query_lookup_and_lock_result()``
+     - via ``drain_completions``
+     - exists results to Bitmap, apply locks
+   * - ``query_load_result()``
+     - via ``drain_completions``
+     - ok/fail to Bitmap
+
+A background demux thread polls the native eventfd, calls ``drain_completions()``,
+looks up each ``future_id`` to determine its operation type, routes the result to
+the correct completion dict, and signals the corresponding Python eventfd.
+
+
+Third-Party Native Connector Plugins (``native_plugin``)
+---------------------------------------------------------
+
+.. _native-plugin-overview:
+
+The steps above describe how to add a native connector **inside** the LMCache source tree.
+If you want to ship a connector as a **separate, pip-installable package** (e.g. a proprietary
+storage backend), use the ``native_plugin`` L2 adapter type instead. It dynamically loads your
+connector at runtime -- no LMCache source modifications required.
+
+How It Works
+~~~~~~~~~~~~
+
+The ``native_plugin`` adapter type loads a third-party **connector object** (pybind-wrapped C++
+or pure Python) and wraps it with the built-in ``NativeConnectorL2Adapter`` bridge. This means
+you only need to implement the 6 connector methods -- the Python-side demux/lock bridging logic
+is reused from LMCache.
+
+.. list-table:: ``plugin`` vs ``native_plugin``
+   :header-rows: 1
+   :widths: 25 35 40
+
+   * - Aspect
+     - ``plugin``
+     - ``native_plugin``
+   * - What is loaded
+     - A full ``L2AdapterInterface`` subclass
+     - A **connector** object (lower level)
+   * - Bridging logic
+     - Provided by the plugin itself
+     - Reused from ``NativeConnectorL2Adapter``
+   * - Third-party effort
+     - Must implement all abstract methods + 3 eventfds
+     - Only 6 connector methods
+
+Required Connector Interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The dynamically loaded connector instance must expose the following methods (identical to the
+pybind ``LMCACHE_BIND_CONNECTOR_METHODS`` contract):
+
+.. code-block:: python
+
+    class NativeConnectorProtocol:
+        def event_fd(self) -> int: ...
+        def submit_batch_get(
+            self,
+            keys: list[str],
+            memoryviews: list[memoryview],
+        ) -> int: ...
+        def submit_batch_set(
+            self,
+            keys: list[str],
+            memoryviews: list[memoryview],
+        ) -> int: ...
+        def submit_batch_exists(
+            self,
+            keys: list[str],
+        ) -> int: ...
+        def submit_batch_delete(
+            self,
+            keys: list[str],
+        ) -> int: ...
+        def drain_completions(
+            self,
+        ) -> list[tuple[int, bool, str, list[bool] | None]]: ...
+        def close(self) -> None: ...
+
+The factory validates the first 6 methods at creation time and raises ``TypeError`` if
+any are missing. ``submit_batch_delete`` is **optional** -- if absent, the adapter's
+``delete()`` method will be a no-op (eviction will not remove keys from the backend).
+
+Configuration
+~~~~~~~~~~~~~
+
+.. code-block:: json
+
+    {
+      "type": "native_plugin",
+      "module_path": "my_ext_package",
+      "class_name": "MyConnectorClient",
+      "adapter_params": {
+        "host": "localhost",
+        "port": 1234
+      }
+    }
+
+.. list-table:: ``NativePluginL2AdapterConfig`` fields
+   :header-rows: 1
+   :widths: 20 10 10 60
+
+   * - Field
+     - Type
+     - Required
+     - Description
+   * - ``module_path``
+     - ``str``
+     - yes
+     - Dotted Python import path of the module containing the connector class.
+   * - ``class_name``
+     - ``str``
+     - yes
+     - Name of the connector class inside ``module_path``.
+   * - ``adapter_params``
+     - ``dict``
+     - no
+     - Forwarded as ``**kwargs`` to the connector class constructor.
+   * - ``max_capacity_gb``
+     - ``float``
+     - no
+     - Maximum L2 storage capacity in GB for client-side usage tracking. Required for L2 eviction. Default 0 (disabled).
+
+Loading Flow
+~~~~~~~~~~~~
+
+.. code-block:: text
+
+    CLI / config JSON
+      |
+      v
+    NativePluginL2AdapterConfig.from_dict(d)
+      |
+      v
+    _create_native_plugin_l2_adapter(config, ...)
+      |
+      +-- importlib.import_module(config.module_path)
+      +-- getattr(module, config.class_name)
+      +-- connector_cls(**config.adapter_params)
+      +-- validate 6 required methods
+      +-- NativeConnectorL2Adapter(native_client)
+              |
+              v
+      L2AdapterInterface instance (ready for use)
+
+Step-by-Step: Building an External Native Connector Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Create a Python package** with a C++ pybind11 extension that inherits from
+   ``ConnectorBase<T>`` (same base class as built-in connectors).
+
+   Project layout:
+
+   .. code-block:: text
+
+       my_ext_connector/
+       +-- csrc/
+       |   +-- connector.h      # C++ connector class
+       |   +-- connector.cpp    # C++ implementation
+       |   +-- pybind.cpp       # pybind11 bindings
+       +-- src/
+       |   +-- my_ext_connector/
+       |       +-- __init__.py   # re-export the factory class
+       |       +-- connector.py  # Python factory wrapper
+       +-- pyproject.toml
+       +-- setup.py              # build C++ extension
+
+2. **Implement the C++ connector** inheriting from ``ConnectorBase<T>`` and override
+   the 4 required methods (``create_connection``, ``do_single_get``, ``do_single_set``,
+   ``do_single_exists``) and optionally ``do_single_delete`` for eviction support.
+
+3. **Create pybind11 bindings** using the ``LMCACHE_BIND_CONNECTOR_METHODS`` macro:
+
+   .. code-block:: cpp
+
+       #include <pybind11/pybind11.h>
+       #include "connector_pybind_utils.h"
+       #include "connector.h"
+
+       namespace py = pybind11;
+
+       PYBIND11_MODULE(_native, m) {
+         py::class_<MyFSConnector>(m, "MyFSConnector")
+             .def(py::init<std::string, int>(),
+                  py::arg("base_path"),
+                  py::arg("num_workers"))
+             LMCACHE_BIND_CONNECTOR_METHODS(MyFSConnector);
+       }
+
+4. **Write a Python factory class** that selects the backend and returns the native
+   connector instance:
+
+   .. code-block:: python
+
+       from my_ext_connector._native import MyFSConnector
+
+       class MyConnectorClient:
+           def __new__(
+               cls,
+               base_path: str = "/tmp/my_ext",
+               num_workers: int = 2,
+           ):
+               return MyFSConnector(base_path, num_workers)
+
+5. **Build and install** the package:
+
+   .. code-block:: bash
+
+       cd my_ext_connector
+       pip install -e .
+
+6. **Configure LMCache** to use it:
+
+   .. code-block:: bash
+
+       --l2-adapter '{
+         "type": "native_plugin",
+         "module_path": "my_ext_connector",
+         "class_name": "MyConnectorClient",
+         "adapter_params": {
+           "base_path": "/tmp/my_ext",
+           "num_workers": 2
+         }
+       }'
+
+Reference Implementation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See ``examples/lmc_external_native_connector/`` for a complete, pip-installable example
+connector plugin that demonstrates:
+
+- C++ pybind11-wrapped connectors inheriting from ``ConnectorBase<T>`` (same as built-in
+  Redis/FS).
+- Two backends: filesystem (``ExampleFSConnector``) and in-memory
+  (``ExampleMemoryConnector``), both in C++.
+- A thin Python factory class (``ExampleNativeConnector``) that selects the backend via a
+  ``"backend"`` parameter.
+- Worker thread pool with eventfd notification (inherited from ``ConnectorBase``).
+- Build via ``pip install -e .`` using pybind11 + setuptools.
+
+
+Checklist
+---------
+
+Use this checklist when adding a new native connector:
+
+1. C++ connector inheriting ``ConnectorBase<T>`` with 4 required + 1 optional (``do_single_delete``) method overrides
+2. Pybind module using ``LMCACHE_BIND_CONNECTOR_METHODS``
+3. ``setup.py`` entry for the new ``CppExtension``
+4. Python client inheriting ``ConnectorClientBase`` (non-MP mode)
+5. L2 adapter module with config class + factory self-registration (MP mode)
+6. Unit tests (see ``tests/v1/distributed/test_native_connector_l2_adapter.py``)
+7. Rebuild with ``pip install -e .`` and verify both modes work
+
+For **external** native connector plugins (``native_plugin``):
+
+1. Separate pip-installable package with C++ pybind11 extension
+2. Connector class exposing the 6 required methods (+ optional ``submit_batch_delete`` for eviction)
+3. Python factory class for backend selection
+4. ``pip install -e .`` and configure via ``--l2-adapter`` JSON
+5. Unit tests (see ``examples/lmc_external_native_connector/tests/``)
+
+
+Built-in Aerospike backend (optional)
+-------------------------------------
+
+LMCache ships an optional in-tree Aerospike native connector (same
+``ConnectorBase`` harness as Redis). It is compiled only when
+``BUILD_AEROSPIKE=1`` or ``AEROSPIKE_INCLUDE_DIR`` is set during
+``pip install -e .``.
+
+**Build:**
+
+.. code-block:: bash
+
+   See ``.github/workflows/aerospike_integration.yml`` for installing the C client into ``.deps/``
+   source .deps/aerospike-client-c.env
+   BUILD_AEROSPIKE=1 pip install -e .
+
+The ``aerospike-client-c.env`` file simply points the build at the C client
+headers and shared libraries you unpacked into ``.deps/``. Adjust the paths to
+match where the client was installed. Example:
+
+.. code-block:: bash
+
+   # .deps/aerospike-client-c.env
+   export AEROSPIKE_INCLUDE_DIR="${PWD}/.deps/aerospike-install/usr/include"
+   export AEROSPIKE_LIBRARY_DIR="${PWD}/.deps/aerospike-install/usr/lib"
+   # Needed at build and runtime so the loader can find libaerospike (and
+   # libyaml if you built it locally):
+   export LD_LIBRARY_PATH="${AEROSPIKE_LIBRARY_DIR}:${PWD}/.deps/libyaml-install/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH:-}"
+
+Setting ``AEROSPIKE_INCLUDE_DIR`` is enough to enable the extension, so
+``BUILD_AEROSPIKE=1`` is optional once the env file is sourced. Multiple include
+or library directories can be passed as ``;``-separated lists.
+
+**MP mode:**
+
+.. code-block:: bash
+
+   --l2-adapter '{"type": "aerospike", "hosts": "127.0.0.1:3000", "namespace": "lmcache", "set_name": "kv_chunks", "num_workers": 8}'
+
+Implementation: ``csrc/storage_backends/aerospike/``,
+``lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py``.
+
+
+Additional Resources
+--------------------
+
+- Framework source: ``csrc/storage_backends/``
+- ``ConnectorBase`` template: ``csrc/storage_backends/connector_base.h``
+- ``IStorageConnector`` interface: ``csrc/storage_backends/connector_interface.h``
+- Pybind utilities: ``csrc/storage_backends/connector_pybind_utils.h``
+- Redis reference implementation: ``csrc/storage_backends/redis/``
+- Aerospike implementation (optional): ``csrc/storage_backends/aerospike/``
+- Architecture README: ``csrc/storage_backends/README.md``
+- External native connector example:
+  ``examples/lmc_external_native_connector/``
+- Native plugin adapter source:
+  ``lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py``
+- Design document:
+  ``lmcache/v1/distributed/l2_adapters/design_docs/plugin.md``
+- RESP backend user guide: :doc:`RESP (Native Redis/Valkey) <../../kv_cache/storage_backends/resp>`
diff --git a/docs/source/developer_guide/extending_lmcache/remote_storage_plugins.rst b/docs/source/developer_guide/extending_lmcache/remote_storage_plugins.rst
new file mode 100644
index 0000000..e0261f7
--- /dev/null
+++ b/docs/source/developer_guide/extending_lmcache/remote_storage_plugins.rst
@@ -0,0 +1,294 @@
+Remote Storage Plugins
+========================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+LMCache supports built-in remote storage connectors for Redis, InfiniStore,
+MooncakeStore, S3, Hugging Face Buckets, and more.
+The remote storage plugin system provides the ability to add custom storage connectors through dynamic loading. This enables extending remote storage capabilities without modifying core code.
+
+.. note::
+
+   The ``remote_url`` configuration is **deprecated** and will be removed in a future release.
+   Please use ``remote_storage_plugins`` instead.
+
+Connector Definition Requirements
+---------------------------------
+A custom remote storage connector requires two classes:
+
+1. **ConnectorAdapter**: Handles URL scheme matching and connector instantiation
+
+   - Inherit from ``ConnectorAdapter``
+   - Set the URL scheme in the constructor (e.g., ``mystore://``)
+   - Implement the ``create_connector`` method
+
+2. **RemoteConnector**: Implements the actual storage operations
+
+   - Inherit from ``RemoteConnector``
+   - Implement all abstract methods: ``exists``, ``exists_sync``, ``get``, ``put``, ``list``, ``close``
+
+.. note::
+
+   The ``ConnectorAdapter`` constructor receives no arguments from LMCache. The scheme should be set by calling the parent constructor with the scheme string.
+
+   The ``create_connector`` method receives a ``ConnectorContext`` object containing the URL, event loop, local CPU backend, config, metadata, and ``plugin_name``.
+
+Plugin Naming Convention
+-------------------------
+Plugin names follow the format ``{type}`` or ``{type}.{instance}``:
+
+- ``{type}`` — a single instance of that connector type (e.g. ``fs``, ``mooncakestore``)
+- ``{type}.{instance}`` — a named instance, allowing **multiple instances of the same type** (e.g. ``fs.primary``, ``fs.backup``)
+
+The framework extracts the *type* portion (everything before the first ``.``) to locate the matching ``ConnectorAdapter``. The full plugin name is used as the configuration key prefix.
+
+Using Built-in Connectors via Plugins
+-------------------------------------
+Built-in connectors (``fs``, ``mooncakestore``, ``hfbucket``, etc.) can be used
+directly via ``remote_storage_plugins`` without specifying ``module_path`` or
+``class_name``. Their configuration is placed under ``extra_config``:
+
+.. code-block:: yaml
+
+    chunk_size: 64
+    local_cpu: False
+    max_local_cpu_size: 5
+    remote_storage_plugins: ["fs"]
+    extra_config:
+      remote_storage_plugin.fs.base_path: /tmp/lmcache
+
+Multiple instances of the same connector type:
+
+.. code-block:: yaml
+
+    remote_storage_plugins: ["fs.primary", "fs.backup"]
+    extra_config:
+      remote_storage_plugin.fs.primary.base_path: /data/cache1
+      remote_storage_plugin.fs.backup.base_path: /data/cache2
+
+Mixing different connector types:
+
+.. code-block:: yaml
+
+    remote_storage_plugins: ["fs.local", "mooncakestore"]
+    extra_config:
+      remote_storage_plugin.fs.local.base_path: /data/cache
+      remote_storage_plugin.mooncakestore.master_server_address: "localhost:50051"
+
+Built-in Hugging Face Buckets example:
+
+.. code-block:: yaml
+
+    remote_storage_plugins: ["hfbucket"]
+    extra_config:
+      remote_storage_plugin.hfbucket.bucket_handle: hf://buckets/my-org/lmcache-kv/prod
+      remote_storage_plugin.hfbucket.token_env: HF_TOKEN
+
+How to Integrate Custom Remote Storage with LMCache
+---------------------------------------------------
+1. Install your connector package in the LMCache environment
+2. Add ``remote_storage_plugins`` and its related ``module_path`` and ``class_name`` to the ``extra_config`` section of LMCache configuration as follows:
+
+.. code-block:: yaml
+
+    chunk_size: 64
+    local_cpu: False
+    max_local_cpu_size: 5
+    remote_storage_plugins: ["mystore"]
+    extra_config:
+      remote_storage_plugin.mystore.module_path: <module_path>
+      remote_storage_plugin.mystore.class_name: <adapter_class_name>
+
+An example configuration for a custom remote storage connector:
+
+.. code-block:: yaml
+
+    chunk_size: 64
+    local_cpu: False
+    max_local_cpu_size: 5
+    remote_storage_plugins: ["mystore"]
+    extra_config:
+      remote_storage_plugin.mystore.module_path: my_package.my_connector
+      remote_storage_plugin.mystore.class_name: MyStoreConnectorAdapter
+
+Multiple instances of a custom connector:
+
+.. code-block:: yaml
+
+    remote_storage_plugins: ["mystore.region_a", "mystore.region_b"]
+    extra_config:
+      remote_storage_plugin.mystore.region_a.module_path: my_package.my_connector
+      remote_storage_plugin.mystore.region_a.class_name: MyStoreConnectorAdapter
+      remote_storage_plugin.mystore.region_b.module_path: my_package.my_connector
+      remote_storage_plugin.mystore.region_b.class_name: MyStoreConnectorAdapter
+
+.. note::
+
+   - ``remote_url`` is **deprecated**; use ``remote_storage_plugins`` instead
+   - ``remote_storage_plugin.<plugin_name>`` uses the full plugin name (including instance suffix) as the key prefix
+   - Multiple remote storage plugins can be loaded simultaneously
+   - Built-in connectors do not require ``module_path`` / ``class_name``
+
+ConnectorAdapter Implementation
+-------------------------------
+The ``ConnectorAdapter`` class is responsible for:
+
+- Defining the URL scheme it handles
+- Creating the appropriate ``RemoteConnector`` instance
+
+.. code-block:: python
+
+    from lmcache.v1.storage_backend.connector import (
+        ConnectorAdapter,
+        ConnectorContext,
+    )
+    from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+    from lmcache.v1.storage_backend.connector import extract_plugin_type
+
+    PLUGIN_TYPE = "mystore"
+
+    class MyStoreConnectorAdapter(ConnectorAdapter):
+        """Adapter for MyStore remote storage."""
+
+        def __init__(self) -> None:
+            # Register the URL scheme this adapter handles
+            super().__init__("mystore://")
+
+        def can_parse(self, url: str) -> bool:
+            """Match legacy URL or plugin://{type}[.{instance}] format."""
+            if url.startswith(self.schema):
+                return True
+            if url.startswith("plugin://"):
+                pname = url[len("plugin://"):]
+                return extract_plugin_type(pname) == PLUGIN_TYPE
+            return False
+
+        def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+            """Create and return a MyStoreConnector instance."""
+            # Access context properties as needed:
+            # - context.url: the full remote URL
+            # - context.loop: asyncio event loop
+            # - context.config: LMCacheEngineConfig
+            # - context.metadata: LMCacheMetadata
+            # - context.plugin_name: plugin instance name
+            #   (e.g. "mystore", "mystore.region_a")
+            return MyStoreConnector(
+                context.config,
+                context.metadata,
+                plugin_name=context.plugin_name,
+            )
+
+RemoteConnector Implementation
+------------------------------
+The ``RemoteConnector`` class defines the interface for remote storage operations. Your implementation must provide the following abstract methods:
+
+.. code-block:: python
+
+    from typing import List, Optional
+    from lmcache.utils import CacheEngineKey
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.metadata import LMCacheMetadata
+    from lmcache.v1.memory_management import MemoryObj
+    from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+    class MyStoreConnector(RemoteConnector):
+        """Custom connector for MyStore remote storage."""
+
+        def __init__(
+            self,
+            config: LMCacheEngineConfig,
+            metadata: Optional[LMCacheMetadata]
+        ):
+            super().__init__(config, metadata)
+            # Initialize your connection here
+
+        async def exists(self, key: CacheEngineKey) -> bool:
+            """Check if a key exists in the remote store."""
+            raise NotImplementedError
+
+        def exists_sync(self, key: CacheEngineKey) -> bool:
+            """Synchronous version of exists."""
+            raise NotImplementedError
+
+        async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+            """Retrieve a memory object by key. Return None if not found."""
+            raise NotImplementedError
+
+        async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+            """Store a memory object with the given key."""
+            raise NotImplementedError
+
+        async def list(self) -> List[str]:
+            """List all keys in the remote store."""
+            raise NotImplementedError
+
+        async def close(self):
+            """Close the connection to the remote store."""
+            raise NotImplementedError
+
+Optional Methods
+----------------
+The ``RemoteConnector`` base class also provides optional methods that can be overridden for enhanced functionality:
+
+- ``support_ping()`` / ``ping()``: Health check support
+- ``support_batched_get()`` / ``batched_get()``: Batch retrieval operations
+- ``support_batched_put()`` / ``batched_put()``: Batch storage operations
+- ``support_batched_contains()`` / ``batched_contains()``: Batch existence checks
+- ``remove_sync()``: Synchronous key removal
+
+Implementation Example
+----------------------
+A complete remote storage connector implementation would include both the adapter and connector classes in a single module or package. Here's a minimal working example structure:
+
+.. code-block:: text
+
+    my_connector_package/
+    ├── __init__.py
+    ├── adapter.py      # Contains MyStoreConnectorAdapter
+    └── connector.py    # Contains MyStoreConnector
+
+The adapter module (``adapter.py``):
+
+.. code-block:: python
+
+    from lmcache.v1.storage_backend.connector import (
+        ConnectorAdapter,
+        ConnectorContext,
+        extract_plugin_type,
+    )
+    from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+    from .connector import MyStoreConnector
+
+    PLUGIN_TYPE = "mystore"
+
+    class MyStoreConnectorAdapter(ConnectorAdapter):
+        def __init__(self) -> None:
+            super().__init__("mystore://")
+
+        def can_parse(self, url: str) -> bool:
+            if url.startswith(self.schema):
+                return True
+            if url.startswith("plugin://"):
+                pname = url[len("plugin://"):]
+                return extract_plugin_type(pname) == PLUGIN_TYPE
+            return False
+
+        def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+            return MyStoreConnector(
+                context.config,
+                context.metadata,
+                plugin_name=context.plugin_name,
+            )
+
+Configuration would then reference the adapter:
+
+.. code-block:: yaml
+
+    remote_storage_plugins: ["mystore"]
+    extra_config:
+      remote_storage_plugin.mystore.module_path: my_connector_package.adapter
+      remote_storage_plugin.mystore.class_name: MyStoreConnectorAdapter
diff --git a/docs/source/developer_guide/extending_lmcache/runtime_plugins.rst b/docs/source/developer_guide/extending_lmcache/runtime_plugins.rst
new file mode 100644
index 0000000..adca6bf
--- /dev/null
+++ b/docs/source/developer_guide/extending_lmcache/runtime_plugins.rst
@@ -0,0 +1,89 @@
+Runtime Plugins
+===============
+
+The LMCache runtime plugin system provides the ability to extend functionality by running custom scripts alongside LMCache processes. Plugins can be written in Python and Bash for now, and are managed by the ``RuntimePluginLauncher`` class.
+
+Key Use Cases
+-------------
+- Start metric reporters for centralized monitoring
+- Implement log reporters for log collection systems
+- Report process-level metrics to alerting systems
+- Implement health checks and service discovery
+- Custom cache management operations
+
+Configuration
+-------------
+Runtime plugins are configured through environment variables and configuration files:
+
+Environment Variables:
+- ``LMCACHE_RUNTIME_PLUGIN_ROLE``: Process role (e.g., ``SCHEDULER``, ``WORKER``)
+- ``LMCACHE_RUNTIME_PLUGIN_CONFIG``: JSON string containing plugin configuration
+- ``LMCACHE_RUNTIME_PLUGIN_WORKER_ID``: Current worker ID
+- ``LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT``: Total worker count in cluster
+
+Configuration File (``lmcache.yaml``):
+
+.. code-block:: yaml
+
+   runtime_plugin_locations:
+     - "/path/to/plugins"
+
+   extra_config:
+     custom_setting: value
+
+Runtime Plugin Naming Convention
+--------------------------------
+Plugin filenames determine execution targets:
+
+Role-Specific Plugins:
+- Format: ``<ROLE>[_<WORKER_ID>][_<DESCRIPTION>].<EXTENSION>``
+- Examples:
+
+  - ``scheduler_foo_plugin.py``: Runs only on ``SCHEDULER``
+  - ``worker_0_test.sh``: Runs only on worker ID 0
+  - ``all_plugin.sh``: Runs on all workers
+
+Notes:
+- Role names are case-insensitive
+- Worker ID must be numeric when specified
+- To target a specific worker ID, the filename must have at least three parts separated by underscores (e.g., `worker_<ID>_<DESCRIPTION>.ext`). A file named `worker_<DESCRIPTION>.ext` will run on all workers.
+
+Execution Model
+---------------
+1. **Interpreter Detection**:
+   - Uses shebang line (e.g., ``#!/opt/venv/bin/python``)
+   - Fallback interpreters:
+
+     - ``.py`` → ``python``
+     - ``.sh`` → ``bash``
+
+2. **Output Handling**:
+   - Stdout/stderr captured continuously
+   - Logged with plugin name prefix
+
+3. **Process Management**:
+   - Launched as subprocesses
+   - Terminated when parent process exits
+
+Example Runtime Plugins
+-----------------------
+Python Plugin (``scheduler_foo_plugin.py``):
+
+.. literalinclude:: ../../../../examples/plugins/scheduler_foo_plugin.py
+   :language: python
+   :linenos:
+
+Bash Plugin (``all_plugin.sh``):
+
+.. literalinclude:: ../../../../examples/plugins/all_plugin.sh
+   :language: bash
+   :linenos:
+
+Best Practices
+--------------
+1. Keep runtime plugins lightweight and efficient
+2. Use descriptive naming conventions
+3. Implement graceful error handling
+4. Include shebang for portability
+5. Validate configuration inputs
+6. Add timeout mechanisms for long operations
\ No newline at end of file
diff --git a/docs/source/developer_guide/extending_lmcache/storage_plugins.rst b/docs/source/developer_guide/extending_lmcache/storage_plugins.rst
new file mode 100644
index 0000000..38ee800
--- /dev/null
+++ b/docs/source/developer_guide/extending_lmcache/storage_plugins.rst
@@ -0,0 +1,248 @@
+Storage Plugins
+===============
+
+LMCache supports out of the box storage backends like Mooncake, S3 and NIXL.
+The LMCache storage plugin system provides the ability to add custom storage backends through dynamic loading or plug and play capability. In other words, extending cache storage capabilities without modifying core code.
+
+Backend Definition Requirements
+-------------------------------
+1. Inherit from ``StoragePluginInterface``
+2. Implement all the abstract methods of the parent interface of ``StoragePluginInterface``- ``StorageBackendInterface``
+3. Package as an installable Python module
+
+.. note::
+
+  The interface constructor is the instantiation contract that the LMCache loading system will use when loading custom storage backends.
+  If you wish to implement a constructor, it should have the same parameter signature and call the interface constructor.
+
+How to Integrate the Backend with LMCache
+-----------------------------------------
+1. Install your backend package in the LMCache environment
+2. Add ``storage_plugins`` and its related ``module_path`` and ``class_name`` to ``extra_config`` section of LMCache configuration as follows:
+
+.. code-block:: yaml
+
+    chunk_size: 64
+    local_cpu: False
+    max_local_cpu_size: 5
+    storage_plugins: <backend_name>
+    extra_config:
+      storage_plugin.<backend_name>.module_path: <module_path>
+      storage_plugin.<backend_name>.class_name: <class_name>
+
+An example configuration for a logging backend is as follows:
+
+.. code-block:: yaml
+
+    chunk_size: 64
+    local_cpu: False
+    max_local_cpu_size: 5
+    storage_plugins: "log_backend"
+    extra_config:
+      storage_plugin.log_backend.module_path: lmc_external_log_backend.lmc_external_log_backend
+      storage_plugin.log_backend.class_name: ExternalLogBackend
+
+.. note::
+
+   - Storage backends are initialized in order during LMCache startup - earlier backends have higher priority during cache lookups
+   - ``storage_plugin.<backend_name>`` distinguishes the different dynamic loaded backends
+
+Backend Implementation Example
+------------------------------
+A sample custom backend implementation can be viewed at https://github.com/opendataio/lmc_external_log_backend/
+
+
+MP-Mode L2 Adapter Plugins (``plugin``)
+----------------------------------------
+
+.. _plugin-l2-adapter-overview:
+
+The storage plugin system described above applies to **non-MP mode** (single-process). For
+**MP mode** (multiprocess), LMCache provides the ``plugin`` L2 adapter type, which dynamically
+loads a third-party ``L2AdapterInterface`` implementation at runtime.
+
+Overview
+~~~~~~~~
+
+The ``plugin`` adapter type lets you ship a full L2 adapter as a **separate, pip-installable
+package**. At startup, LMCache imports your module, instantiates your adapter class, and uses it
+just like a built-in adapter -- no LMCache source modifications required.
+
+.. note::
+
+   If your storage backend is a native C++ connector (pybind-wrapped), consider using the
+   ``native_plugin`` type instead (see :doc:`native_connectors`). It reuses the built-in
+   bridging logic so you only need to implement 6 connector methods rather than the full
+   ``L2AdapterInterface``.
+
+Configuration
+~~~~~~~~~~~~~
+
+.. code-block:: json
+
+    {
+      "type": "plugin",
+      "module_path": "my_plugin.adapter",
+      "class_name": "MyL2Adapter",
+      "adapter_params": {
+        "host": "localhost",
+        "capacity": 1000
+      }
+    }
+
+.. list-table:: ``PluginL2AdapterConfig`` fields
+   :header-rows: 1
+   :widths: 22 10 10 58
+
+   * - Field
+     - Type
+     - Required
+     - Description
+   * - ``module_path``
+     - ``str``
+     - yes
+     - Dotted Python import path of the module containing the adapter class.
+   * - ``class_name``
+     - ``str``
+     - yes
+     - Name of the class inside ``module_path`` that implements ``L2AdapterInterface``.
+   * - ``adapter_params``
+     - ``dict``
+     - no
+     - Forwarded to the adapter class constructor (as a typed config or raw dict).
+   * - ``config_class_name``
+     - ``str``
+     - no
+     - Explicit config class name; when omitted the factory auto-discovers it.
+
+Config Class Auto-Discovery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The factory automatically resolves the adapter's config class using the following priority
+chain (first match wins):
+
+1. **Explicit** ``config_class_name`` field in JSON config.
+2. **Convention**: adapter class name + ``"Config"`` suffix (e.g. ``MyL2Adapter`` looks for
+   ``MyL2AdapterConfig``).
+3. **Attribute**: ``config_class_name`` attribute on the adapter class itself.
+4. **Fallback**: no config class found -- pass raw ``adapter_params`` dict.
+
+Each candidate is looked up in the loaded module and validated as an ``L2AdapterConfigBase``
+subclass. This means most plugins that follow the naming convention will **automatically**
+receive a typed config instance without any extra configuration.
+
+Plugin Contract
+~~~~~~~~~~~~~~~
+
+A plugin adapter class **must**:
+
+1. Subclass ``L2AdapterInterface`` from ``lmcache.v1.distributed.l2_adapters.base``.
+2. Implement all abstract methods: ``submit_store_task``, ``pop_completed_store_tasks``,
+   ``submit_lookup_and_lock_task``, ``query_lookup_and_lock_result``, ``submit_unlock``,
+   ``submit_load_task``, ``query_load_result``, ``close``, and all three event-fd getters.
+3. Provide **three distinct event fds** (store / lookup / load). The controllers build
+   ``fd -> adapter`` maps; duplicates will misroute events.
+4. Be **thread-safe**: ``StoreController`` and ``PrefetchController`` call adapter methods
+   from different threads concurrently.
+5. Accept ``**kwargs`` in ``__init__`` to stay forward-compatible.
+
+A plugin adapter class **should**:
+
+1. Create its own asyncio event loop and background thread if it needs async I/O.
+2. Use ``create_event_notifier()`` from ``lmcache.v1.platform`` for the three event fds
+   (cross-platform: ``os.eventfd`` on Linux, ``os.pipe`` fallback elsewhere).
+3. Clean up all resources (event fds, threads, connections) in ``close()``.
+
+Loading Flow
+~~~~~~~~~~~~
+
+.. code-block:: text
+
+    CLI / config JSON
+      |
+      v
+    PluginL2AdapterConfig.from_dict(d)
+      |  validates module_path, class_name, adapter_params
+      |
+      v
+    _create_plugin_adapter(config, ...)
+      |
+      +-- importlib.import_module(config.module_path)
+      +-- getattr(module, config.class_name)
+      +-- issubclass check against L2AdapterInterface
+      |
+      +-- _resolve_config_class(module, config, adapter_cls)
+      |   +-- 1. config.config_class_name (explicit)
+      |   +-- 2. class_name + "Config" (convention)
+      |   +-- 3. adapter_cls.config_class_name (attribute)
+      |   +-- 4. None (fall back to raw dict)
+      |
+      +-- [if config class found]
+      |   +-- adapter_cls(cfg_cls.from_dict(adapter_params))
+      |
+      +-- [otherwise]
+          +-- adapter_cls(adapter_params)
+              |
+              v
+      L2AdapterInterface instance (ready for use)
+
+Minimal Example
+~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    # my_plugin/adapter.py
+    import asyncio
+    import threading
+
+    from lmcache.native_storage_ops import Bitmap
+    from lmcache.v1.distributed.l2_adapters.base import (
+        L2AdapterInterface,
+        L2TaskId,
+    )
+    from lmcache.v1.platform import create_event_notifier
+
+
+    class MyL2Adapter(L2AdapterInterface):
+        def __init__(self, params, **_kw):
+            self._store_efd = create_event_notifier()
+            self._lookup_efd = create_event_notifier()
+            self._load_efd = create_event_notifier()
+            # ... set up connection, background thread, etc.
+
+        # implement all abstract methods ...
+
+        def close(self) -> None:
+            self._store_efd.close()
+            self._lookup_efd.close()
+            self._load_efd.close()
+
+Launch via CLI:
+
+.. code-block:: bash
+
+    --l2-adapter '{
+      "type": "plugin",
+      "module_path": "my_plugin.adapter",
+      "class_name": "MyL2Adapter",
+      "adapter_params": {"host": "localhost"}
+    }'
+
+Reference Implementation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+See ``examples/lmc_external_l2_adapter/`` for a complete, pip-installable example plugin
+(``InMemoryL2Adapter``) that demonstrates:
+
+- FIFO eviction with configurable capacity.
+- Simulated bandwidth delay for realistic testing.
+- Background asyncio event loop with proper shutdown.
+- Full test suite covering store, lookup, load, batch operations, and eviction behavior.
+
+Additional Resources
+~~~~~~~~~~~~~~~~~~~~
+
+- Plugin adapter source: ``lmcache/v1/distributed/l2_adapters/plugin_l2_adapter.py``
+- Native plugin adapter: ``lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py``
+- Design document: ``lmcache/v1/distributed/l2_adapters/design_docs/plugin.md``
+- L2 adapter base interface: ``lmcache/v1/distributed/l2_adapters/base.py``
diff --git a/docs/source/developer_guide/index.rst b/docs/source/developer_guide/index.rst
new file mode 100644
index 0000000..ad30b99
--- /dev/null
+++ b/docs/source/developer_guide/index.rst
@@ -0,0 +1,13 @@
+Developer Guide
+===============
+
+How to contribute to LMCache and extend it with new storage backends, CLI
+commands, and HTTP endpoints.
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing
+   extending_lmcache/native_connectors
+   cli
+   extending_http_api
diff --git a/docs/source/developer_guide/integration.rst b/docs/source/developer_guide/integration.rst
new file mode 100644
index 0000000..9dafc9c
--- /dev/null
+++ b/docs/source/developer_guide/integration.rst
@@ -0,0 +1,48 @@
+Integration
+===========
+
+LMCache acts as a caching middleware that sits between LLM inference engines and storage systems, enabling:
+
+- **Transparent Cache Reuse**: Automatic detection and reuse of previously computed KV caches
+- **Performance Optimization**: 3×–10× reduction in time-to-first-token (TTFT) for multi-round conversation and RAG.
+- **Resource Efficiency**: Significant GPU cycle savings through cache reuse
+- **Scalable Architecture**: Support for single-node and multi-node deployments
+
+Supported Engines
+-----------------
+
+LMCache currently supports integration with:
+
+- **vLLM**
+- **SGLang**
+- **TRT-LLM** (coming soon)
+
+Integration with vLLM
+---------------------
+
+When LMCache is integrated with vLLM, the inference pipeline is augmented to lookup and inject cached KV chunks for any reused input content. The sequence diagram below shows how a prompt request flows through vLLM with LMCache:
+
+.. mermaid::
+
+    sequenceDiagram
+    participant User as User Application
+    participant VLLM as vLLM Engine (LMCache Connector)
+    participant Cache as LMCache Storage (CPU/Disk)
+    User->>VLLM: Prompt request (LLM query)
+    VLLM->>Cache: **Lookup** KV cache for prompt tokens
+    alt Cache hit for some tokens
+        Cache-->>VLLM: Return cached KV chunk(s)
+        VLLM->>VLLM: Inject KV into model's cache (skip recomputation)
+    else Cache miss (no KV for tokens)
+        Cache-->>VLLM: No cached data (proceed normally)
+    end
+    VLLM->>VLLM: **Generate** remaining tokens (compute new KV)
+    VLLM-->>User: Respond with completion
+    Note right of VLLM: *LLM output is returned without waiting for cache storage.*
+    VLLM->>Cache: **Store** new KV chunk(s) (async background put)
+
+**Cache Lookup**: Upon receiving a new prompt, vLLM (via the LMCache connector) computes identifiers (e.g. hashes of token sequences) and queries LMCache for matching KV cache chunks. If a cache hit occurs, LMCache retrieves the KV chunk (potentially from CPU or disk) and returns it to vLLM. vLLM then injects these KV tensors into the model's attention cache instead of recomputing them from scratch.
+
+**Inference with Cache**: vLLM proceeds with inference. For any parts of the prompt where no cache was available (cache miss), the model computes new KV values as usual. Cached segments (e.g. previously seen text) are skipped in computation, significantly reducing the time-to-first-token (TTFT) and saving GPU cycles.
+
+**Async Cache Write**: After processing the prompt, any newly generated KV cache chunks (corresponding to this prompt's content) are handed off to LMCache for storage. This put operation is done asynchronously (in the background) so it doesn't delay the response. The response is returned to the user promptly, and LMCache's background tasks will offload the new KV data to CPU, disk, or other backends for future reuse.
diff --git a/docs/source/developer_guide/usage/basic_check.rst b/docs/source/developer_guide/usage/basic_check.rst
new file mode 100644
index 0000000..4e9929f
--- /dev/null
+++ b/docs/source/developer_guide/usage/basic_check.rst
@@ -0,0 +1,144 @@
+Basic Check Tool
+================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The LMCache Basic Check Tool is a testing and validation utility that helps you verify your LMCache installation, configuration, and functionality. It provides multiple testing modes to validate different components of the LMCache system.
+
+Overview
+--------
+
+The basic check tool (``lmcache.v1.basic_check``) is designed to:
+
+* Test remote backend connectivity and functionality
+* Validate storage manager operations
+* Generate test keys for performance testing
+* Verify configuration settings
+* Provide diagnostic information for troubleshooting
+
+Available Check Modes
+---------------------
+
+The tool supports several check modes, each targeting specific functionality:
+
+test_remote
+~~~~~~~~~~~
+
+Tests the remote backend functionality including:
+
+* Connection establishment to remote backends (fs, etc.)
+* put/get operations with data integrity validation
+* put/get/exists operations with performance reports
+
+**Usage:**
+
+.. code-block:: bash
+
+   python -m lmcache.v1.basic_check --mode test_remote
+
+test_storage_manager
+~~~~~~~~~~~~~~~~~~~~
+
+Tests the storage manager operations including:
+
+* Configuration validation
+* batched_put/get operations with data integrity validation
+* batched_put/get/contains operations with performance reports
+
+**Usage:**
+
+.. code-block:: bash
+
+   python -m lmcache.v1.basic_check --mode test_storage_manager
+
+gen (Key Generation)
+~~~~~~~~~~~~~~~~~~~~
+
+Generates test keys for performance testing and benchmarking:
+
+* Configurable number of keys and concurrency levels
+* Memory-efficient batch processing
+* Progress tracking and performance metrics
+* Offset support for distributed testing
+
+**Usage:**
+
+.. code-block:: bash
+
+   python -m lmcache.v1.basic_check --mode gen --num-keys 1000 --concurrency 16
+
+Command Line Interface
+----------------------
+
+Basic Usage
+~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.basic_check --mode <MODE> [OPTIONS]
+
+List Available Modes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.basic_check --mode list
+
+Command Line Options
+~~~~~~~~~~~~~~~~~~~~
+
+.. option:: --mode MODE
+
+   **Required.** Operation mode to run. Use ``list`` to see available modes.
+
+.. option:: --model MODEL
+
+   Model name for testing, just a part of key of persist kv-cache. Default: ``/lmcache_test_model/``
+
+.. option:: --num-keys NUM
+
+   Number of keys to generate (gen mode only). Default: 100
+
+.. option:: --concurrency NUM
+
+   Concurrency level for operations (gen mode only). Default: 16
+
+.. option:: --offset NUM
+
+   Offset for key generation (gen mode only). Default: 0
+
+Configuration
+-------------
+
+The basic check tool uses your existing LMCache configuration. You can specify configuration in several ways:
+
+Environment Variable
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   export LMCACHE_CONFIG_PATH=/path/to/config.yaml
+   python -m lmcache.v1.basic_check --mode test_remote
+
+Example Configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+Here's an example configuration optimized for basic checks:
+
+.. code-block:: yaml
+
+   # Basic cache settings
+   chunk_size: 256
+   local_cpu: true
+   max_local_cpu_size: 1.0  # 1GB for basic checks
+
+   # Remote backend (optional)
+   remote_url: "file:///tmp/lmcache_basic_check"
+
+Examples
+--------
+
+The ``examples/basic_check/`` directory contains comprehensive examples:
diff --git a/docs/source/developer_guide/usage/index.rst b/docs/source/developer_guide/usage/index.rst
new file mode 100644
index 0000000..ecb2b2b
--- /dev/null
+++ b/docs/source/developer_guide/usage/index.rst
@@ -0,0 +1,7 @@
+Usage Data Module
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   usage_stats_collection
diff --git a/docs/source/developer_guide/usage/usage_stats_collection.rst b/docs/source/developer_guide/usage/usage_stats_collection.rst
new file mode 100644
index 0000000..7a9d6f1
--- /dev/null
+++ b/docs/source/developer_guide/usage/usage_stats_collection.rst
@@ -0,0 +1,155 @@
+.. _usage-stats-collection:
+
+Usage Stats Collection
+======================
+
+LMCache collects anonymous usage data by default to help the engineering team understand real-world workloads, prioritize optimizations, and improve reliability. All collected data is aggregated and contains no sensitive user information.
+
+A sanitized subset of the aggregated data may be publicly released for the community’s benefit (for example, see a daily usage report `here <https://github.com/Hanchenli/OSS_Growth_Toolkit/tree/main/usage_tracker/report>`_).
+
+What data is collected?
+-----------------------
+
+Usage stats are implemented in the ``lmcache/usage_telemetry/`` package. The
+one-shot messages sent at startup depend on how LMCache runs.
+
+When LMCache runs **inside the serving engine** (the single-process
+integrations for vLLM, SGLang, and TensorRT-LLM), engine startup sends:
+
+- **EnvMessage**
+  Captures environment details such as cloud provider, CPU info, total memory, architecture, GPU count/type, and execution source.
+
+- **EngineMessage**
+  Records engine configuration and metadata, including cache settings (chunk size, local device, cache limits), remote backend parameters, blending settings, model name, world size, and KV-cache dtype/shape.
+
+- **MetadataMessage**
+  Reports execution metadata: the timestamp when the run started and total duration in seconds.
+
+When LMCache runs as a **standalone multiprocess (MP) cache server**
+(``lmcache server``), server startup sends:
+
+- **EnvMessage**
+  Same environment snapshot as above, taken on the cache-server host.
+
+- **MPServerMessage**
+  Records the server configuration: LMCache version, chunk size, hash
+  algorithm, engine type, transfer mode, worker pool sizes, whether P2P is
+  enabled, L1 size and medium (DRAM / GDS / DRAM+DevDAX), eviction policy,
+  the configured L2 adapter and serde types, and the L2 store/prefetch
+  policies.
+
+  The MP server's ``--instance-id`` is **never** sent: it can be
+  operator-chosen and therefore identifying. Model names are not known at
+  server startup (vLLM instances register later) and are not part of this
+  message.
+
+In addition to the one-shot messages above, a continuous reporter periodically
+sends interval counters (**ContinuousContextMessage**: tokens stored/hit and
+stored KV bytes in the interval) and a cache-lifespan histogram
+(**CacheLifespanMessage**). The flush interval is controlled by
+``LMCACHE_USAGE_TRACK_INTERVAL`` (seconds, default 600).
+
+Every payload carries four common fields:
+
+- ``session_id`` -- a random UUID minted once per process, joining the
+  one-shot context with the continuous messages of the same run.
+- ``machine_id`` -- a random UUID persisted at
+  ``~/.config/lmcache/machine_id``, grouping sessions from the same machine.
+  It is never derived from hardware identifiers (MAC address, hostname).
+- ``schema_version`` -- the version of the message schema.
+- ``deployment_mode`` -- ``single_process`` (LMCache inside the serving
+  engine) or ``mp_server`` (standalone MP cache server).
+
+These messages are serialized to JSON and POSTed to the LMCache usage server.
+
+Example JSON payload
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: json
+
+   {
+     "message_type": "EnvMessage",
+     "provider": "GCP",
+     "num_cpu": 24,
+     "cpu_type": "Intel(R) Xeon(R) CPU @ 2.20GHz",
+     "cpu_family_model_stepping": "6,85,7",
+     "total_memory": 101261135872,
+     "architecture": ["64bit", "ELF"],
+     "platforms": "Linux-5.10.0-28-cloud-amd64-x86_64-with-glibc2.31",
+     "gpu_count": 2,
+     "gpu_type": "NVIDIA L4",
+     "gpu_memory_per_device": 23580639232,
+     "source": "DOCKER"
+   }
+
+Previewing collected data
+-------------------------
+
+If you enable **local logging**, usage messages are appended to your specified log file. To inspect the most recent entries:
+
+.. code-block:: bash
+
+   tail ~/.config/lmcache/usage.log
+
+Configuration & Opt-out
+-----------------------
+
+By default, usage tracking is **enabled**. Any one of the following opt-outs
+disables all usage stats collection:
+
+.. code-block:: bash
+
+   # LMCache-specific opt-out
+   export LMCACHE_TRACK_USAGE=false
+
+   # The cross-tool "do not track" convention (1/true/yes)
+   export DO_NOT_TRACK=1
+
+When tracking is disabled, ``InitializeUsageContext`` will return ``None`` and
+no data will be sent or logged, and no state files (such as ``machine_id``)
+will be created.
+
+Reference
+~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 14 52
+
+   * - Environment variable / file
+     - Default
+     - Effect
+   * - ``LMCACHE_TRACK_USAGE``
+     - unset
+     - Set to ``false`` to disable all usage stats collection.
+   * - ``DO_NOT_TRACK``
+     - unset
+     - Set to ``1``/``true``/``yes`` to disable collection (cross-tool
+       convention).
+   * - ``LMCACHE_USAGE_TRACK_URL``
+     - ``http://stats.lmcache.ai:8080``
+     - Override the stats server endpoint (e.g. for a private sink).
+   * - ``LMCACHE_USAGE_TRACK_INTERVAL``
+     - ``600``
+     - Seconds between continuous-message flushes.
+   * - ``~/.config/lmcache/machine_id``
+     - created on first send
+     - Holds the random anonymous machine UUID. Delete it to rotate the
+       identifier.
+
+Local logging
+~~~~~~~~~~~~~
+
+If you would like to log to a file in addition to (or instead of) sending data to the server, pass a local-log path when initializing:
+
+.. code-block:: python
+
+   from lmcache.usage_telemetry import InitializeUsageContext
+
+   usage_ctx = InitializeUsageContext(
+       config=engine_config,
+       metadata=engine_metadata,
+       local_log="~/.config/lmcache/usage.log"
+   )
+
+Omitting the ``local_log`` argument (or passing ``None``) disables local file logging.
diff --git a/docs/source/disaggregated_prefill/nixl/1p1d.rst b/docs/source/disaggregated_prefill/nixl/1p1d.rst
new file mode 100644
index 0000000..7ccad68
--- /dev/null
+++ b/docs/source/disaggregated_prefill/nixl/1p1d.rst
@@ -0,0 +1,275 @@
+1p1d
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/disaggregated_prefill`.
+
+
+One Prefiller, One Decoder (1p1d) Example
+------------------------------------------
+
+This example demonstrates how to run LMCache with disaggregated prefill using NIXL on a single node with a 1 prefiller + 1 decoder setup. This configuration separates the compute-intensive prefill operations from the decode operations, allowing for better resource utilization and performance optimization.
+
+Architecture Overview
+~~~~~~~~~~~~~~~~~~~~~
+
+The 1p1d setup consists of three main components:
+
+1. **Prefiller Server** - Handles the prefill phase of inference (initial prompt processing)
+2. **Decoder Server** - Handles the decode phase of inference (token generation) 
+3. **Proxy Server** - Coordinates requests between the prefiller and decoder
+
+.. code-block::
+
+                ┌─────────────┐
+                │   Client    │
+                └─────┬───────┘
+                      │
+              ┌───────▼───────┐
+              │ Proxy Server  │
+              │   Port 9100   │
+              └───▲───────┬───┘
+                  │       │
+         ┌────────▼──┐  ┌─▼────────┐
+         │ Prefiller │  │ Decoder  │
+         │Port 7100  │  │Port 7200 │
+         │  GPU 0    │  │  GPU 1   │
+         └───────────┘  └──────────┘
+                  ▲       ▲
+                  │       │
+                  └───────┘
+                   NIXL Transfer
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- **LMCache**: Install with ``pip install lmcache``
+- **NIXL**: Install from `NIXL GitHub repository <https://github.com/ai-dynamo/nixl>`_
+- **Hardware**: At least 2 GPUs
+- **Model Access**: Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B Instruct
+
+Quick Start
+~~~~~~~~~~~
+
+1. **Set your Hugging Face token**:
+
+   .. code-block:: bash
+
+      export HF_TOKEN=hf_your_token_here
+
+2. **Navigate to the example directory**:
+
+   .. code-block:: bash
+
+      cd examples/disagg_prefill/1p1d_experimental
+
+3. **Run the example**:
+
+   .. code-block:: bash
+
+      bash disagg_example_1p1d.sh
+
+The script will automatically:
+
+- Launch a prefiller instance on port 7100 (GPU 0)
+- Launch a decoder instance on port 7200 (GPU 1)  
+- Launch a proxy server on port 9100
+- Wait for all servers to be ready
+
+Press ``Ctrl+C`` to stop all servers.
+
+Configuration
+~~~~~~~~~~~~~
+
+**Important**: For correct KV cache transfer, ensure all processes use the same ``PYTHONHASHSEED`` to keep the hash of the KV cache consistent across processes:
+
+   .. code-block:: bash
+
+      export PYTHONHASHSEED=0
+
+Prefiller Configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The prefiller is configured via ``configs/lmcache-prefiller-config.yaml``:
+
+.. code-block:: yaml
+
+   local_cpu: True
+   max_local_cpu_size: 5
+   max_local_disk_size: 0
+
+   enable_pd: True
+   transfer_channel: "nixl"
+   pd_role: "sender"
+   pd_proxy_host: "localhost"
+   pd_proxy_port: 7500
+   pd_buffer_size: 1073741824 # 1GB
+   pd_buffer_device: "cuda"
+
+Key settings:
+
+- ``pd_role: "sender"`` - Configures this instance to send KV cache data
+- ``pd_buffer_size: 1073741824 # 1GB`` - Buffer size for transfers
+- ``pd_buffer_device: "cuda"`` - Uses GPU memory for buffering
+
+Decoder Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+The decoder is configured via ``configs/lmcache-decoder-config.yaml``:
+
+.. code-block:: yaml
+
+   local_cpu: False
+   max_local_cpu_size: 0
+
+   enable_pd: True
+   transfer_channel: "nixl"
+   pd_role: "receiver"
+   pd_peer_host: "localhost"
+   pd_peer_init_port: 7300
+   pd_peer_alloc_port: 7400
+   pd_buffer_size: 2147483648 # 2GB
+   pd_buffer_device: "cuda"
+   nixl_backends: [UCX]
+
+Key settings:
+
+- ``pd_role: "receiver"`` - Configures this instance to receive KV cache data
+- ``pd_buffer_size: 2147483648 # 2GB`` - Buffer size for transfers
+- ``pd_buffer_device: "cuda"`` - Uses GPU memory for buffering
+
+Components Deep Dive
+~~~~~~~~~~~~~~~~~~~~
+
+Proxy Server (disagg_proxy_server.py)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The proxy server coordinates the disaggregated prefill workflow:
+
+1. **Request Handling**: Receives client requests on port 9100
+2. **Prefill Coordination**: Sends requests to the prefiller with ``max_tokens=1``
+3. **Prefill Response**: Receives prefiller that says nixl transfer is done
+4. **Response Streaming**: Streams the full response from the decoder
+5. **Performance Monitoring**: Tracks Time-To-First-Token (TTFT) statistics
+
+Supported endpoints:
+
+- ``/v1/completions``
+- ``/v1/chat/completions``
+
+vLLM Server Launcher (disagg_vllm_launcher.sh)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This script launches individual vLLM servers with appropriate configurations:
+
+**Prefiller Launch Command**:
+
+.. code-block:: bash
+
+   UCX_TLS=cuda_ipc,cuda_copy,tcp \
+      LMCACHE_CONFIG_FILE=$prefill_config_file \
+      VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+      VLLM_WORKER_MULTIPROC_METHOD=spawn \
+      CUDA_VISIBLE_DEVICES=0 \
+      vllm serve $MODEL \
+      --port 7100 \
+      --disable-log-requests \
+      --enforce-eager \
+      --no-enable-prefix-caching \
+      --kv-transfer-config \
+      '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer1"}}'
+
+**Decoder Launch Command**:
+
+.. code-block:: bash
+
+   UCX_TLS=cuda_ipc,cuda_copy,tcp \
+      LMCACHE_CONFIG_FILE=$decode_config_file \
+      VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+      VLLM_WORKER_MULTIPROC_METHOD=spawn \
+      CUDA_VISIBLE_DEVICES=1 \
+      vllm serve $MODEL \
+      --port 7200 \
+      --disable-log-requests \
+      --enforce-eager \
+      --no-enable-prefix-caching \
+      --kv-transfer-config \
+      '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer1", "skip_last_n_tokens": 1}}'
+
+Testing and Benchmarking
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basic Test
+^^^^^^^^^^
+
+Once all servers are running, you can test with a simple curl command:
+
+.. code-block:: bash
+
+   curl -s -N -X POST http://127.0.0.1:9100/v1/completions   -H "Content-Type: application/json"   -d '{
+      "model": "meta-llama/Llama-3.1-8B-Instruct",
+      "prompt": "What date is today?",
+      "max_tokens": 20,
+      "temperature": 0.0
+   }'
+
+Performance Benchmarking
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+For comprehensive performance testing, use vLLM's benchmark tool:
+
+.. code-block:: bash
+
+   vllm bench serve --port 9100 --seed $(date +%s) \
+       --model meta-llama/Llama-3.1-8B-Instruct \
+       --dataset-name random --random-input-len 7500 --random-output-len 200 \
+       --num-prompts 30 --burstiness 100 --request-rate 1 --ignore-eos
+
+This benchmark:
+- Sends requests to port 9100 (proxy server)
+- Uses random prompts with 7500 input tokens
+- Generates 200 output tokens per request
+- Tests with 30 total prompts at 1 request/second
+
+Log Files and Monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The example generates three log files for monitoring:
+
+- ``prefiller.log`` - Prefiller server logs and errors
+- ``decoder.log`` - Decoder server logs and errors  
+- ``proxy.log`` - Proxy server logs and TTFT statistics
+
+The proxy server automatically calculates and displays TTFT statistics every 5 seconds:
+
+.. code-block::
+
+   ===============================
+   Num requests: 10
+   Prefill node TTFT stats:
+    - Average (ms): 45.2
+    - Median (ms): 43.1
+    - 99th Percentile (ms): 52.8
+   ===============================
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+Common Issues
+^^^^^^^^^^^^^
+
+1. **GPU Memory**: Ensure each GPU has sufficient memory for the model
+2. **NIXL Installation**: Verify NIXL is properly installed and accessible
+3. **Port Conflicts**: Check that ports 7100, 7200, and 9000 are available
+4. **HF Token**: Ensure your Hugging Face token has access to Llama models
+
+Error Recovery
+^^^^^^^^^^^^^^
+
+If any server fails to start:
+
+1. Check the corresponding log file for error details
+2. Verify GPU availability with ``nvidia-smi``
+3. Ensure all dependencies are installed
+4. Try restarting with ``Ctrl+C`` followed by re-running the script
diff --git a/docs/source/disaggregated_prefill/nixl/index.rst b/docs/source/disaggregated_prefill/nixl/index.rst
new file mode 100644
index 0000000..6245654
--- /dev/null
+++ b/docs/source/disaggregated_prefill/nixl/index.rst
@@ -0,0 +1,23 @@
+Using NIXL
+==========
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/disaggregated_prefill`.
+
+
+NIXL (NVIDIA Inference Xfer Library) is a high-performance library designed for accelerating point to point communications in AI inference frameworks.
+It provides an abstraction over various types of memory (CPU and GPU) and storage through a modular plug-in architecture, enabling efficient data transfer and coordination between different components of the inference pipeline.
+
+LMCache supports using NIXL as the underlying communication library for prefill-decode disaggregation.
+
+For detailed installation instructions of LMCache with NIXL, please refer to our `installation guide <https://docs.google.com/document/d/1c93fANc2DPSUvR5ndCMysU2E29nYvjE2e3GLxHRWZls/edit?tab=t.0>`_.
+
+Examples
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   1p1d
+   xpyd 
diff --git a/docs/source/disaggregated_prefill/nixl/xpyd.rst b/docs/source/disaggregated_prefill/nixl/xpyd.rst
new file mode 100644
index 0000000..f9cb975
--- /dev/null
+++ b/docs/source/disaggregated_prefill/nixl/xpyd.rst
@@ -0,0 +1,361 @@
+XpYd
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/disaggregated_prefill`.
+
+
+X Prefiller, Y Decoder (XpYd) Example
+--------------------------------------
+
+This example demonstrates how to run LMCache with disaggregated prefill using NIXL on a single node with multiple prefiller and decoder instances. This configuration allows for horizontal scaling of both the compute-intensive prefill operations and the decode operations, enabling better resource utilization and higher throughput.
+
+Architecture Overview
+~~~~~~~~~~~~~~~~~~~~~
+
+The XpYd setup consists of multiple components that can be scaled independently:
+
+1. **Multiple Prefiller Servers** - Handle the prefill phase of inference (initial prompt processing)
+2. **Multiple Decoder Servers** - Handle the decode phase of inference (token generation) 
+3. **Proxy Server** - Coordinates requests between prefillers and decoders using round-robin load balancing
+
+Example 2p2d Architecture:
+
+.. code-block::
+
+                ┌─────────────┐
+                │   Client    │
+                └─────┬───────┘
+                      │
+              ┌───────▼────────┐
+              │  Proxy Server  │
+              │    Port 9100   │──────────────────────|
+              │  (Round-Robin) │                      |
+              └───▲────────▲───┘                      |
+                  │        │                          |
+         ┌────────▼───┐  ┌─▼──────────┐               |
+         │ Prefiller1 │  │ Prefiller2 │               |
+         │ Port 7100  │  │ Port 7101  │               |
+         │   GPU 0    │  │   GPU 1    │               |
+         └─────▲──────┘  └─────▲──────┘               |
+               │               │                      |
+               │ NIXL transfer |                      |
+               │               │                      |
+          ┌────▼───────┐  ┌────▼──────┐               |
+          │ Decoder 1  │  │ Decoder 2 │               |
+          │ Port 7200  │  │ Port 7201 │               |
+          │  GPU 2     │  │  GPU 3    │               |
+          └────▲───────┘  └────▲──────┘               |
+               │               │                      |
+               └───────────────┴──────────────────────|
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- **LMCache**: Install with ``pip install lmcache``
+- **NIXL**: Install from `NIXL GitHub repository <https://github.com/ai-dynamo/nixl>`_
+- **Hardware**: At least 4 GPUs (2 for prefillers + 2 for decoders in 2p2d setup)
+- **Model Access**: Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B Instruct
+
+Quick Start (2p2d Example)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. **Set your Hugging Face token**:
+
+   .. code-block:: bash
+
+      export HF_TOKEN=hf_your_token_here
+
+2. **Navigate to the example directory**:
+
+   .. code-block:: bash
+
+      cd examples/disagg_prefill/xpyd_experimental
+
+3. **Run the example**:
+
+   .. code-block:: bash
+
+      bash disagg_example_xpyd.sh
+
+The script will automatically:
+
+- Launch two decoder instances on port 8200 and 8201 (GPU 2 and GPU 3)
+- Launch two prefiller instances on ports 7100 and 7101 (GPU 0 and GPU 1)
+- Launch a proxy server on port 9100 with round-robin load balancing
+- Wait for all servers to be ready
+
+Press ``Ctrl+C`` to stop all servers.
+
+Configuration
+~~~~~~~~~~~~~
+
+**Important**: For correct KV cache transfer, ensure all processes use the same ``PYTHONHASHSEED`` to keep the hash of the KV cache consistent across processes:
+
+   .. code-block:: bash
+
+      export PYTHONHASHSEED=0
+
+Prefiller Configuration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+All prefillers share the same configuration via ``configs/lmcache-prefiller-config.yaml``:
+
+.. code-block:: yaml
+
+   local_cpu: False
+   max_local_cpu_size: 0
+   max_local_disk_size: 0
+
+   enable_pd: True
+   transfer_channel: "nixl"
+   pd_role: "sender"
+   pd_proxy_host: "localhost"
+   pd_proxy_port: 7500
+   pd_buffer_size: 1073741824 # 1GB
+   pd_buffer_device: "cuda"
+
+Key settings:
+
+- ``pd_role: "sender"`` - Configures these instances to send KV cache data
+- ``pd_buffer_size: 1073741824 # 1GB`` - Upper bound of PD transport buffer size (in bytes), aligned to chunk size
+- ``pd_buffer_device: "cuda"`` - Uses GPU memory for buffering
+
+Decoder Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+The decoder(s) are configured via ``configs/lmcache-decoder-x-config.yaml``:
+
+.. code-block:: yaml
+
+   local_cpu: False
+   max_local_cpu_size: 0
+
+   enable_pd: True
+   transfer_channel: "nixl"
+   pd_role: "receiver"
+   pd_peer_host: "localhost"
+   pd_peer_init_port: 730x
+   pd_peer_alloc_port: 740x
+   pd_buffer_size: 2147483648 # 2GB
+   pd_buffer_device: "cuda"
+   pd_backends: [UCX]
+
+Key settings:
+
+- ``pd_role: "receiver"`` - Configures these instances to receive KV cache data
+- ``pd_buffer_size: 2147483648 # 2GB`` - Upper bound of PD transport buffer size (in bytes), aligned to chunk size
+- ``pd_buffer_device: "cuda"`` - Uses GPU memory for buffering
+
+Components Deep Dive
+~~~~~~~~~~~~~~~~~~~~
+
+Proxy Server (disagg_proxy_server.py)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The proxy server coordinates the multi-prefiller disaggregated workflow:
+
+1. **Request Handling**: Receives client requests on port 9000
+2. **Load Balancing**: Distributes requests across multiple prefillers using round-robin
+3. **Prefill Coordination**: Sends requests to prefillers with ``max_tokens=1``
+4. **Prefill Response**: Receives prefiller that says nixl transfer is done
+5. **Response Streaming**: Streams the full response from the decoder
+6. **Performance Monitoring**: Tracks Time-To-First-Token (TTFT) statistics
+
+Key features:
+- **Round-robin distribution**: Balances load across ``--num-prefillers`` instances
+- **Fault tolerance**: Handles prefiller failures gracefully
+- **Monitoring**: Provides detailed TTFT statistics for each prefiller
+
+Supported endpoints:
+- ``/v1/completions``
+- ``/v1/chat/completions``
+
+vLLM Server Launcher (disagg_vllm_launcher.sh)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This script launches individual vLLM servers with appropriate configurations:
+
+**Prefiller1 Launch Command**:
+
+.. code-block:: bash
+
+   UCX_TLS=cuda_ipc,cuda_copy,tcp \
+      LMCACHE_CONFIG_FILE=$prefill_config_file \
+      VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+      VLLM_WORKER_MULTIPROC_METHOD=spawn \
+      CUDA_VISIBLE_DEVICES=0 \
+      vllm serve $MODEL \
+      --port 7100 \
+      --disable-log-requests \
+      --enforce-eager \
+      --no-enable-prefix-caching \
+      --kv-transfer-config \
+      '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer1"}}'
+
+**Prefiller2 Launch Command**:
+
+.. code-block:: bash
+
+   UCX_TLS=cuda_ipc,cuda_copy,tcp \
+      LMCACHE_CONFIG_FILE=$prefill_config_file \
+      VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+      VLLM_WORKER_MULTIPROC_METHOD=spawn \
+      CUDA_VISIBLE_DEVICES=1 \
+      vllm serve $MODEL \
+      --port 7101 \
+      --disable-log-requests \
+      --enforce-eager \
+      --no-enable-prefix-caching \
+      --kv-transfer-config \
+      '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer2"}}'
+
+**Decoder1 Launch Command**:
+
+.. code-block:: bash
+
+   UCX_TLS=cuda_ipc,cuda_copy,tcp \
+      LMCACHE_CONFIG_FILE=$decode_config_file \
+      VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+      VLLM_WORKER_MULTIPROC_METHOD=spawn \
+      CUDA_VISIBLE_DEVICES=2 \
+      vllm serve $MODEL \
+      --port 7200 \
+      --disable-log-requests \
+      --enforce-eager \
+      --no-enable-prefix-caching \
+      --kv-transfer-config \
+      '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer1", "skip_last_n_tokens": 1}}'
+
+**Decoder2 Launch Command**:
+
+.. code-block:: bash
+
+   UCX_TLS=cuda_ipc,cuda_copy,tcp \
+      LMCACHE_CONFIG_FILE=$decode_config_file \
+      VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+      VLLM_WORKER_MULTIPROC_METHOD=spawn \
+      CUDA_VISIBLE_DEVICES=3 \
+      vllm serve $MODEL \
+      --port 7201 \
+      --disable-log-requests \
+      --enforce-eager \
+      --no-enable-prefix-caching \
+      --kv-transfer-config \
+      '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer2", "skip_last_n_tokens": 1}}'
+
+Key differences from 1p1d:
+- Each prefiller gets a unique ``lmcache_rpc_port`` (producer1, producer2, etc.)
+- Each prefiller runs on a different GPU (CUDA_VISIBLE_DEVICES)
+- Different ports for each prefiller (7100, 7101, etc.)
+- Different ports for each decoder (7200, 7201, etc.)
+
+Basic Test
+~~~~~~~~~~
+
+Once all servers are running, you can test with a simple curl command:
+
+.. code-block:: bash
+
+   curl -s -N -X POST http://127.0.0.1:9100/v1/completions   -H "Content-Type: application/json"   -d '{
+      "model": "meta-llama/Llama-3.1-8B-Instruct",
+      "prompt": "What date is today?",
+      "max_tokens": 20,
+      "temperature": 0.0
+   }'
+
+Performance Benchmarking
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+For comprehensive performance testing, use vLLM's benchmark tool:
+
+.. code-block:: bash
+
+   vllm bench serve --port 9100 --seed $(date +%s) \
+      --model meta-llama/Llama-3.1-8B-Instruct \
+      --dataset-name random --random-input-len 7500 --random-output-len 200 \
+      --num-prompts 30 --burstiness 100 --request-rate 1 --ignore-eos
+
+Expected performance improvements with 2p2d:
+- **Higher throughput**: Multiple prefillers can handle more concurrent requests
+- **Better TTFT**: Load balancing reduces queuing delays
+- **Improved utilization**: Better GPU utilization across multiple devices
+
+Sample benchmark results:
+
+.. code-block::
+
+   ============ Serving Benchmark Result ============
+   Successful requests:                     30
+   Benchmark duration (s):                  31.34
+   Total input tokens:                      224970
+   Total generated tokens:                  6000
+   Request throughput (req/s):              0.96
+   Output token throughput (tok/s):         191.44
+   Total Token throughput (tok/s):          7369.36
+   ---------------Time to First Token----------------
+   Mean TTFT (ms):                          313.41
+   Median TTFT (ms):                        272.83
+   P99 TTFT (ms):                           837.32
+   -----Time per Output Token (excl. 1st token)------
+   Mean TPOT (ms):                          8.84
+   Median TPOT (ms):                        8.72
+   P99 TPOT (ms):                           11.35
+   ---------------Inter-token Latency----------------
+   Mean ITL (ms):                           8.84
+   Median ITL (ms):                         8.61
+   P99 ITL (ms):                            11.43
+   ==================================================
+
+Log Files and Monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The example generates multiple log files for comprehensive monitoring:
+
+- ``prefiller1.log`` - First prefiller server logs and errors
+- ``prefiller2.log`` - Second prefiller server logs and errors  
+- ``decoder1.log`` - First decoder server logs and errors
+- ``decoder1.log`` - First decoder server logs and errors
+- ``proxy.log`` - Proxy server logs and TTFT statistics
+
+The proxy server provides detailed statistics for each prefiller:
+
+.. code-block::
+
+   ===============================
+   Num requests: 20
+   Prefiller 1 TTFT stats:
+    - Average (ms): 42.3
+    - Median (ms): 40.1
+    - 99th Percentile (ms): 48.7
+   Prefiller 2 TTFT stats:
+    - Average (ms): 43.8
+    - Median (ms): 41.5
+    - 99th Percentile (ms): 52.1
+   ===============================
+
+This helps identify performance differences between prefiller instances and optimize load balancing.
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+Common Issues
+^^^^^^^^^^^^^
+
+1. **GPU Memory**: Ensure each GPU has sufficient memory for the model
+2. **NIXL Installation**: Verify NIXL is properly installed and accessible
+3. **Port Conflicts**: Check that all required ports are available
+4. **HF Token**: Ensure your Hugging Face token has access to Llama models
+5. **GPU Assignment**: Verify CUDA_VISIBLE_DEVICES assignments don't conflict
+
+Multi-Instance Specific Issues
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. **Uneven Load**: Monitor prefiller statistics to ensure balanced distribution
+2. **Resource Contention**: Watch for GPU memory pressure with multiple instances
+3. **Network Bottlenecks**: Monitor NIXL transfer performance between instances
+4. **Startup Timing**: Stagger prefiller launches to avoid resource conflicts
+
+
+
diff --git a/docs/source/disaggregated_prefill/shared_storage.rst b/docs/source/disaggregated_prefill/shared_storage.rst
new file mode 100644
index 0000000..8c147e9
--- /dev/null
+++ b/docs/source/disaggregated_prefill/shared_storage.rst
@@ -0,0 +1,4 @@
+Using shared storage
+====================
+
+Coming soon... 
diff --git a/docs/source/distributed_kv_cache.rst b/docs/source/distributed_kv_cache.rst
new file mode 100644
index 0000000..a92810f
--- /dev/null
+++ b/docs/source/distributed_kv_cache.rst
@@ -0,0 +1,14 @@
+Distributed KV Cache
+====================
+
+Sharing and coordinating KV cache across multiple LMCache servers and inference
+instances -- disaggregated prefill, peer-to-peer sharing, multi-server
+coordination, and cache management.
+
+.. toctree::
+   :maxdepth: 1
+
+   mp/disaggregated_prefill
+   mp/p2p
+   mp/coordinator
+   mp/kv_cache_management
diff --git a/docs/source/getting_started/benchmarking.rst b/docs/source/getting_started/benchmarking.rst
new file mode 100644
index 0000000..f485fde
--- /dev/null
+++ b/docs/source/getting_started/benchmarking.rst
@@ -0,0 +1,157 @@
+Benchmarking
+============
+
+This is a simple tutorial on how to deploy and benchmark LMCache using the
+``lmcache bench engine`` CLI.
+
+The ``lmcache bench engine`` command is a flexible traffic simulator that
+sends configurable workloads to your inference engine and reports TTFT,
+decoding speed, and throughput metrics. This tutorial walks through a
+long-document Q&A benchmark that exercises LMCache's CPU offloading path.
+
+For the full CLI reference -- including every flag, every workload type, and
+config-file usage -- see :doc:`/cli/bench`.
+
+Long Doc QA workload
+--------------------
+
+The ``long-doc-qa`` workload simulates repeated Q&A over long synthetic
+documents: a warmup round primes the KV cache with each document, then a
+benchmark round dispatches the questions. The number of documents is
+derived from ``--kv-cache-volume`` and the model's tokens-per-GB rather
+than set directly. See :doc:`/cli/bench` for the full flag list.
+
+Example
+-------
+
+To measure the benefit of LMCache, run the **same benchmark against two
+setups** and compare the results:
+
+- **Setup A (baseline)** -- vLLM alone.
+- **Setup B (with LMCache)** -- vLLM plus a standalone LMCache server.
+
+The steps below reproduce both runs on ``Qwen/Qwen3-8B``. Adjust the sizes
+to match your hardware.
+
+Setup A: vLLM alone (baseline)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    vllm serve Qwen/Qwen3-8B
+
+Setup B: vLLM with LMCache
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run LMCache as a standalone service and point vLLM at it with the
+``LMCacheMPConnector``. See :doc:`/getting_started/quickstart` for the full MP-mode
+walkthrough.
+
+**Start the LMCache server:**
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 66 --eviction-policy LRU
+
+The ZMQ port defaults to **5555** (used by vLLM) and the HTTP frontend
+defaults to **8080** (used by ``lmcache bench engine --lmcache-url``).
+
+**Start vLLM with the MP connector in a separate terminal:**
+
+.. code-block:: bash
+
+    vllm serve Qwen/Qwen3-8B \
+        --kv-transfer-config \
+        '{"kv_connector": "LMCacheMPConnector", "kv_role": "kv_both"}'
+
+Run the benchmark
+~~~~~~~~~~~~~~~~~
+
+To make the comparison fair, capture the benchmark settings **once** in a
+config file, then replay the same config against both setups.
+
+**Step 1 -- export a shared config.** With the LMCache server from Setup B
+still running, launch ``lmcache bench engine`` in interactive mode:
+
+.. code-block:: bash
+
+    lmcache bench engine --lmcache-url http://localhost:8080
+
+Interactive mode triggers because ``--engine-url`` and ``--workload`` are
+missing, and ``--lmcache-url`` auto-detects ``tokens-per-gb-kvcache`` from
+the server. Walk through the prompts and pick:
+
+- Engine URL: ``http://localhost:8000``
+- Workload: ``long-doc-qa``
+- Model: auto-detected from the engine (or type ``Qwen/Qwen3-8B``)
+- KV cache volume (GB): ``10``
+- ``ldqa-query-per-document``: ``1``
+- ``ldqa-shuffle-policy``: ``tile``
+- ``ldqa-num-inflight-requests``: ``4``
+- Leave the rest at their defaults.
+
+At the **summary** step, choose **"Export configuration for later use and
+exit"** and save to ``bench_config.json``. The file looks like:
+
+.. code-block:: json
+
+    {
+      "model": "Qwen/Qwen3-8B",
+      "workload": "long-doc-qa",
+      "kv_cache_volume": 10.0,
+      "tokens_per_gb_kvcache": 46020,
+      "ldqa_document_length": 10000,
+      "ldqa_query_per_document": 1,
+      "ldqa_shuffle_policy": "tile",
+      "ldqa_num_inflight_requests": 4
+    }
+
+Note that the exported config stores ``tokens_per_gb_kvcache`` (resolved
+from ``--lmcache-url``) but **not** the engine URL or the LMCache URL, so
+the same file is portable across environments.
+
+**Step 2 -- replay against each setup.** Point ``--engine-url`` at whichever
+vLLM you want to benchmark and pass the shared config:
+
+.. code-block:: bash
+
+    lmcache bench engine \
+        --engine-url http://localhost:8000 \
+        --config bench_config.json
+
+Run this once against Setup A's vLLM and once against Setup B's
+vLLM-plus-LMCache, recording the metrics from each run.
+
+Results
+~~~~~~~
+
+Pull the headline numbers out of each run's
+``Engine Benchmark Result (long-doc-qa)`` summary:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 30 30
+
+   * - Metric
+     - Setup A (vLLM)
+     - Setup B (+ LMCache)
+   * - Successful requests
+     - 46
+     - 46
+   * - Benchmark duration (s)
+     - 23.47
+     - 13.79
+   * - Mean TTFT (ms)
+     - 757.00
+     - 185.00
+
+That's a **75%** reduction in Mean TTFT (757 ms → 185 ms) and a **41%**
+reduction in benchmark duration (23.47 s → 13.79 s) from LMCache offloading.
+
+.. note::
+   Without LMCache, once the benchmark's working set overflows the GPU KV
+   cache the second round has to recompute every prefix, so TTFT and
+   throughput don't improve even when content repeats. LMCache keeps the
+   evicted blocks on CPU RAM and restores them on demand -- that's where
+   the speedup comes from.
diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
new file mode 100644
index 0000000..5151beb
--- /dev/null
+++ b/docs/source/getting_started/index.rst
@@ -0,0 +1,16 @@
+Getting Started
+===============
+
+New to LMCache? Start here -- an overview of multiprocess mode, installation, a
+quickstart, the configuration reference, and tools for benchmarking and sizing
+the cache.
+
+.. toctree::
+   :maxdepth: 1
+
+   /mp/index
+   installation
+   quickstart
+   /mp/configuration
+   benchmarking
+   kv_cache_calculator
diff --git a/docs/source/getting_started/installation.rst b/docs/source/getting_started/installation.rst
new file mode 100644
index 0000000..6e1ecca
--- /dev/null
+++ b/docs/source/getting_started/installation.rst
@@ -0,0 +1,265 @@
+.. _installation_guide:
+
+Installation
+============
+
+**Prerequisites:** Linux · Python 3.9–3.13 · NVIDIA GPU (compute 7.0+) · CUDA 12.1+ · `uv <https://astral.sh/uv>`_
+
+Install LMCache
+---------------
+
+.. tab-set::
+
+    .. tab-item:: Python (pip / uv)
+
+        .. tab-set::
+
+            .. tab-item:: Stable  
+
+                .. tab-set::
+
+                    .. tab-item:: CUDA 13.0
+
+                        .. code-block:: bash
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+                            uv pip install lmcache
+
+                        .. important::
+
+                            You're all set! You can now start using LMCache. For hands-on guides and more
+                            usage examples, see the :ref:`quickstart_examples` section.
+
+                        .. note::
+
+                            NIXL support (e.g. for disaggregated prefill and P2P KV
+                            sharing) is an optional extra:
+
+                            .. code-block:: bash
+
+                                uv pip install lmcache[nixl]
+
+                    .. tab-item:: CUDA 12.9
+
+                        The CUDA 12.9 wheel is published to a dedicated
+                        `GitHub Release <https://github.com/LMCache/LMCache/releases>`__ rather than PyPI.
+
+                        .. code-block:: bash
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+                            VERSION=0.4.3  # replace with target release
+                            uv pip install lmcache==${VERSION} \
+                                --extra-index-url https://download.pytorch.org/whl/cu129 \
+                                --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/v${VERSION}-cu129 \
+                                --index-strategy unsafe-best-match
+
+                        .. note::
+
+                            ``--extra-index-url https://download.pytorch.org/whl/cu129`` ensures the CUDA 12.9
+                            build of PyTorch is resolved. Without it, pip may select a mismatched CUDA variant.
+
+            .. tab-item:: Nightly
+
+                Nightly wheels are built from the latest ``dev`` branch each day at 07:30 UTC
+                and published to GitHub Releases. No version pinning required — ``--pre``
+                picks the latest nightly automatically.
+
+                .. tab-set::
+
+                    .. tab-item:: CUDA 13.0
+
+                        .. code-block:: bash
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+                            uv pip install lmcache --pre \
+                                --extra-index-url https://download.pytorch.org/whl/cu130 \
+                                --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/nightly \
+                                --index-strategy unsafe-best-match
+
+                    .. tab-item:: CUDA 12.9
+
+                        .. code-block:: bash
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+                            uv pip install lmcache --pre \
+                                --extra-index-url https://download.pytorch.org/whl/cu129 \
+                                --find-links https://github.com/LMCache/LMCache/releases/expanded_assets/nightly-cu129 \
+                                --index-strategy unsafe-best-match
+
+            .. tab-item:: From Source
+
+                ``--no-build-isolation`` ensures the kernels are compiled against the same torch
+                already installed in your environment, preventing undefined symbol errors at runtime.
+
+                .. tab-set::
+
+                    .. tab-item:: CUDA 13.0
+
+                        .. code-block:: bash
+
+                            git clone https://github.com/LMCache/LMCache.git
+                            cd LMCache
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+
+                            uv pip install -r requirements/build.txt
+                            uv pip install vllm  # pulls in required torch version (cu13)
+                            uv pip install -e . --no-build-isolation
+
+                    .. tab-item:: CUDA 12.9
+
+                        .. code-block:: bash
+
+                            git clone https://github.com/LMCache/LMCache.git
+                            cd LMCache
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+
+                            uv pip install -r requirements/build.txt
+                            # Pin vLLM (and torch) to the cu12.9 wheel index so the local
+                            # CUDA 12 toolchain matches what the extensions are built against.
+                            uv pip install vllm \
+                                --extra-index-url https://download.pytorch.org/whl/cu129 \
+                                --index-strategy unsafe-best-match
+                            # LMCACHE_CUDA_MAJOR=12 makes setup.py pick cupy-cuda12x
+                            # for install_requires instead of the cu13 default.
+                            LMCACHE_CUDA_MAJOR=12 \
+                                uv pip install -e . --no-build-isolation
+
+                    .. tab-item:: ROCm
+
+                        .. code-block:: bash
+
+                            git clone https://github.com/LMCache/LMCache.git
+                            cd LMCache
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+
+                            # Need to install these packages manually to avoid build isolation
+                            uv pip install -r requirements/build.txt
+
+                            # Install torch from the ROCm wheel index
+                            uv pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm7.0
+
+                            # Build LMCache. BUILD_WITH_HIP=1 makes setup.py pick cupy-rocm-7-0 automatically.
+                            # PYTORCH_ROCM_ARCH selects the target GPU(s):
+                            #   gfx942  -> MI300X / MI325X
+                            #   gfx950  -> MI350X / MI355X
+                            # Comma-separate to build a fat binary for multiple archs.
+                            PYTORCH_ROCM_ARCH="gfx942,gfx950" \
+                            TORCH_DONT_CHECK_COMPILER_ABI=1 \
+                            CXX=hipcc \
+                            BUILD_WITH_HIP=1 \
+                            uv pip install -e . --no-build-isolation
+
+                    .. tab-item:: Intel XPU
+
+                        .. code-block:: bash
+
+                            git clone https://github.com/LMCache/LMCache.git
+                            cd LMCache
+
+                            uv venv --python 3.12
+                            source .venv/bin/activate
+
+                            # Need to install these packages manually to avoid build isolation
+                            uv pip install -r requirements/build.txt
+
+                            # Build LMCache with SYCL backend.
+                            BUILD_WITH_SYCL=1 uv pip install --no-build-isolation -e .
+
+
+    .. tab-item:: Docker
+
+        .. tab-set::
+
+            .. tab-item:: Stable
+
+                .. tab-set::
+
+                    .. tab-item:: CUDA 13.0
+
+                        .. code-block:: bash
+
+                            docker pull lmcache/vllm-openai
+
+                    .. tab-item:: CUDA 12.9
+
+                        .. code-block:: bash
+
+                            docker pull lmcache/vllm-openai:latest-cu129
+
+            .. tab-item:: Nightly
+
+                .. tab-set::
+
+                    .. tab-item:: CUDA 13.0
+
+                        .. code-block:: bash
+
+                            docker pull lmcache/vllm-openai:latest-nightly
+
+                    .. tab-item:: CUDA 12.9
+
+                        .. code-block:: bash
+
+                            docker pull lmcache/vllm-openai:latest-nightly-cu129
+
+            .. tab-item:: ROCm
+
+                .. code-block:: bash
+
+                    docker pull rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620
+
+            .. tab-item:: Intel XPU
+
+                .. code-block:: bash
+
+                    docker pull intel/vllm:0.17.0-xpu
+
+        See :ref:`docker_deployment` for running the container and ROCm images.
+
+    .. tab-item:: CLI Only  
+
+        Lightweight CLI-only package for querying or benchmarking a remote LMCache server.
+        No CUDA required, works on any OS.
+
+        .. code-block:: bash
+
+            pip install lmcache-cli
+
+        .. note::
+
+            ``lmcache-cli`` and ``lmcache`` ship the same ``lmcache`` CLI command.
+            Do not install both in the same environment.
+
+Build the Docker Image
+----------------------
+
+Instead of pulling a prebuilt image, you can build the LMCache (integrated with
+vLLM) image yourself from the provided Dockerfile, located in
+`docker/ <https://github.com/LMCache/LMCache/tree/dev/docker>`_.
+
+From the root of the LMCache repository:
+
+.. code-block:: bash
+
+    docker build --tag <IMAGE_NAME>:<TAG> --target image-build --file docker/Dockerfile .
+
+Replace ``<IMAGE_NAME>`` and ``<TAG>`` with your desired image name and tag. See
+the example build file in `docker/ <https://github.com/LMCache/LMCache/tree/dev/docker>`_
+for an explanation of all build arguments.
+
+Verify Installation
+-------------------
+
+.. code-block:: bash
+
+    python -c "import lmcache.c_ops"
diff --git a/docs/source/getting_started/kv_cache_calculator.rst b/docs/source/getting_started/kv_cache_calculator.rst
new file mode 100644
index 0000000..964144b
--- /dev/null
+++ b/docs/source/getting_started/kv_cache_calculator.rst
@@ -0,0 +1,18 @@
+KV Cache Size Calculator
+========================
+
+Use this interactive calculator to:
+
+- **Calculate KV Cache Size**: Estimate the memory required for caching a specific number of tokens
+- **Calculate Maximum Tokens**: Find out how many tokens you can cache given your available GPU RAM
+
+This helps you plan memory requirements for your LMCache deployment.
+
+.. raw:: html
+
+   <div style="margin: 20px 0;">
+       <iframe src="../_static/kv_cache_calculator.html" 
+               style="width: 100%; height: 1400px; border: none;"
+               title="KV Cache Size Calculator">
+       </iframe>
+   </div>
diff --git a/docs/source/getting_started/quickstart.rst b/docs/source/getting_started/quickstart.rst
new file mode 100644
index 0000000..760f4b1
--- /dev/null
+++ b/docs/source/getting_started/quickstart.rst
@@ -0,0 +1,480 @@
+.. _quickstart:
+
+Quickstart
+==========
+
+This guide helps you get LMCache running end-to-end in a couple of minutes. Use the tabs below to switch the engine. Steps are the same; only the libraries and launch commands change.
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Install LMCache**
+
+      .. code-block:: bash
+
+         uv venv --python 3.12
+         source .venv/bin/activate
+         uv pip install lmcache vllm
+
+      LMCache supports two deployment modes with vLLM:
+
+      - **Multiprocess (MP) mode** -- **recommended.** LMCache runs as a
+        standalone service and vLLM attaches via ``LMCacheMPConnector``.
+        Scales better, exposes management/observability endpoints, and
+        supports sharing one cache across multiple engine instances.
+      - **In-process mode** -- LMCache runs inside the vLLM process via
+        ``LMCacheConnectorV1``. Single command, convenient for quick
+        single-node experiments.
+
+      .. tab-set::
+         :sync-group: vllm-mode
+
+         .. tab-item:: MP mode (recommended)
+            :sync: mp
+
+            Start the LMCache server. ``--host`` / ``--port`` set the ZMQ
+            address vLLM connects to; they are spelled out here so the two
+            commands line up (these are also the defaults):
+
+            .. code-block:: bash
+
+               # chunk-size 16 is an illustrative demo value so a short
+               # prompt produces visible cache traffic; use the default
+               # (256) in production.
+               lmcache server \
+                   --host localhost --port 5555 \
+                   --l1-size-gb 20 --eviction-policy LRU --chunk-size 16
+
+            The ZMQ port (``--port``, default **5555**) accepts connections
+            from vLLM; the HTTP frontend (default **8080**) serves the
+            management and metrics endpoints. See :doc:`../mp/configuration`
+            for the full list of ``lmcache server`` and connector options.
+
+            Start vLLM with the MP connector in a separate terminal. Point the
+            connector at the server above via ``lmcache.mp.host`` /
+            ``lmcache.mp.port`` in ``kv_connector_extra_config`` -- the host
+            **must** carry a ZMQ transport prefix such as ``tcp://``:
+
+            .. code-block:: bash
+
+               vllm serve Qwen/Qwen3-8B \
+                   --port 8000 --kv-transfer-config \
+                   '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.host": "tcp://localhost", "lmcache.mp.port": 5555}}'
+
+            .. note::
+               **Where does** ``LMCacheMPConnector`` **resolve to?** This depends on your vLLM version:
+
+               - **vLLM < 0.20.0** -- ``"kv_connector":"LMCacheMPConnector"`` always
+                 resolves to vLLM's built-in
+                 ``vllm.distributed.kv_transfer.kv_connector.v1.LMCacheMPConnector``;
+                 there is no way to redirect it to the LMCache-shipped implementation.
+
+               - **vLLM >= 0.20.0** -- ``"kv_connector":"LMCacheMPConnector"`` still
+                 defaults to vLLM's built-in connector, but you can opt in to the
+                 LMCache-shipped implementation
+                 (:mod:`lmcache.integration.vllm.lmcache_mp_connector`) by adding
+                 ``kv_connector_module_path``:
+
+                 .. code-block:: bash
+
+                    vllm serve Qwen/Qwen3-8B \
+                        --port 8000 --kv-transfer-config \
+                        '{"kv_connector":"LMCacheMPConnector", "kv_connector_module_path":"lmcache.integration.vllm.lmcache_mp_connector", "kv_role":"kv_both"}'
+
+                 The LMCache-shipped connector tracks the latest LMCache server
+                 protocol and ships fixes/features ahead of the version vendored
+                 into vLLM, so prefer it whenever you are on vLLM 0.20.0 or newer.
+
+            **Test** -- open a new terminal and send two requests whose
+            prompts share a prefix:
+
+            **First request**
+
+            .. code-block:: bash
+
+               curl http://localhost:8000/v1/completions \
+                 -H "Content-Type: application/json" \
+                 -d '{
+                   "model": "Qwen/Qwen3-8B",
+                   "prompt": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts",
+                   "max_tokens": 100,
+                   "temperature": 0.7
+                 }'
+
+            **Second request**
+
+            .. code-block:: bash
+
+               curl http://localhost:8000/v1/completions \
+                 -H "Content-Type: application/json" \
+                 -d '{
+                   "model": "Qwen/Qwen3-8B",
+                   "prompt": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts (MoE) models",
+                   "max_tokens": 100,
+                   "temperature": 0.7
+                 }'
+
+            **You should see LMCache logs like this** -- in MP mode the
+            store/retrieve logs come from the standalone ``lmcache server``
+            process, one entry per chunk.
+
+            **First request** -- cache is empty, so every aligned chunk is
+            offloaded:
+
+            .. code-block:: text
+
+               [2026-04-22 19:49:56,316] LMCache INFO: Stored 16 tokens in 0.023 seconds (server.py:390:lmcache.v1.multiprocess.server)
+               [2026-04-22 19:49:56,555] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server)
+               [2026-04-22 19:49:56,691] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server)
+               ...
+
+            **Second request** -- the shared prefix is retrieved from CPU
+            RAM; only the new tail is stored:
+
+            .. code-block:: text
+
+               [2026-04-22 19:50:04,686] LMCache INFO: Retrieved 16 tokens in 0.003 seconds (server.py:573:lmcache.v1.multiprocess.server)
+               [2026-04-22 19:50:04,832] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server)
+               [2026-04-22 19:50:04,968] LMCache INFO: Stored 16 tokens in 0.005 seconds (server.py:390:lmcache.v1.multiprocess.server)
+               ...
+
+            For request-level statistics (hit ratio, bytes transferred) see
+            :doc:`../mp/observability/index`.
+
+         .. tab-item:: In-process mode
+            :sync: inproc
+
+            Start vLLM with LMCache embedded in the engine process:
+
+            .. code-block:: bash
+
+               # The chunk size here is only for illustration purpose, use default one (256) later
+               LMCACHE_CHUNK_SIZE=8 \
+               vllm serve Qwen/Qwen3-8B \
+                   --port 8000 --kv-transfer-config \
+                   '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+            .. note::
+               To customize further, create a config file. See
+               :doc:`../api_reference/configurations` for all options.
+
+            **Alternative simpler command:**
+
+            .. code-block:: bash
+
+               vllm serve <MODEL NAME> \
+                   --kv-offloading-backend lmcache \
+                   --kv-offloading-size <SIZE IN GB> \
+                   --disable-hybrid-kv-cache-manager
+
+            The ``--disable-hybrid-kv-cache-manager`` flag is mandatory.
+            All configuration options from the
+            :doc:`../api_reference/configurations` page still apply.
+
+            **Test** -- open a new terminal and send two requests whose
+            prompts share a prefix:
+
+            **First request**
+
+            .. code-block:: bash
+
+               curl http://localhost:8000/v1/completions \
+                 -H "Content-Type: application/json" \
+                 -d '{
+                   "model": "Qwen/Qwen3-8B",
+                   "prompt": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts",
+                   "max_tokens": 100,
+                   "temperature": 0.7
+                 }'
+
+            **Second request**
+
+            .. code-block:: bash
+
+               curl http://localhost:8000/v1/completions \
+                 -H "Content-Type: application/json" \
+                 -d '{
+                   "model": "Qwen/Qwen3-8B",
+                   "prompt": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts (MoE) models",
+                   "max_tokens": 100,
+                   "temperature": 0.7
+                 }'
+
+            **You should see LMCache logs like this** -- in-process mode
+            emits the logs inline with the vLLM engine core.
+
+            **First request** -- prompt is offloaded to LMCache:
+
+            .. code-block:: text
+
+               (EngineCore_DP0 pid=458469) [2025-09-30 00:08:43,982] LMCache INFO: Stored 31 out of total 31 tokens. size: 0.0040 gb, cost 1.95 ms, throughput: 1.98 GB/s; offload_time: 1.88 ms, put_time: 0.07 ms
+
+            **Second request** -- hits the cache and stores the new tail:
+
+            .. code-block:: text
+
+               Reqid: cmpl-6709d8795d3c4464b01999c9f3fffede-0, Total tokens 32, LMCache hit tokens: 24, need to load: 8
+               (EngineCore_DP0 pid=494270) [2025-09-30 01:12:36,502] LMCache INFO: Retrieved 8 out of 24 required tokens (from 32 total tokens). size: 0.0011 gb, cost 0.55 ms, throughput: 1.98 GB/s;
+               (EngineCore_DP0 pid=494270) [2025-09-30 01:12:36,509] LMCache INFO: Storing KV cache for 8 out of 32 tokens (skip_leading_tokens=24)
+               (EngineCore_DP0 pid=494270) [2025-09-30 01:12:36,510] LMCache INFO: Stored 8 out of total 8 tokens. size: 0.0011 gb, cost 0.43 ms, throughput: 2.57 GB/s; offload_time: 0.40 ms, put_time: 0.03 ms
+
+            - **Total tokens 32**: The new prompt has 32 tokens after tokenization.
+            - **LMCache hit tokens: 24**: 24 tokens (full 8-token chunks) were found in the cache from the first request that stored 31 tokens.
+            - **Need to load: 8**: vLLM auto prefix caching uses block size 16; 16 tokens already sit in GPU RAM, so LMCache only loads 24-16=8.
+            - **Why 24 hit tokens instead of 31?** LMCache hashes every 8 tokens (8, 16, 24, 31). It matches page-aligned chunks, so it uses the 24-token hash.
+            - **Stored another 8 tokens**: The new 8 tokens form a full chunk and are stored for future reuse.
+
+   .. tab-item:: SGLang
+
+      .. note::
+         The SGLang integration now defaults to MP (multi-process) mode.
+         Please refer to `examples/sgl_integration/README.md`_ for the current setup instructions.
+
+      .. _examples/sgl_integration/README.md: https://github.com/LMCache/LMCache/blob/dev/examples/sgl_integration/README.md
+
+      **Install SGLang**
+
+      .. code-block:: bash
+
+         uv venv --python 3.12
+         source .venv/bin/activate
+         uv pip install --prerelease=allow lmcache "sglang"
+
+      **Start SGLang with LMCache**
+
+      .. code-block:: bash
+
+         cat > lmc_config.yaml <<'EOF'
+         chunk_size: 8  # demo only; use 256 for production
+         local_cpu: true
+         use_layerwise: true
+         max_local_cpu_size: 10  # GB
+         EOF
+
+         export LMCACHE_CONFIG_FILE=$PWD/lmc_config.yaml
+
+         python -m sglang.launch_server \
+           --model-path Qwen/Qwen3-8B \
+           --host 0.0.0.0 \
+           --port 30000 \
+           --enable-lmcache
+
+      .. note::
+         Configure LMCache via the config file. See :doc:`../api_reference/configurations` for the full list.
+
+      **Test** -- open a new terminal and send two requests whose prompts
+      share a prefix:
+
+      **First request**
+
+      .. code-block:: bash
+
+         curl http://localhost:30000/v1/chat/completions \
+           -H "Content-Type: application/json" \
+           -d '{
+             "model": "Qwen/Qwen3-8B",
+             "messages": [{"role": "user", "content": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts"}],
+             "max_tokens": 100,
+             "temperature": 0.7
+           }'
+
+      **Second request**
+
+      .. code-block:: bash
+
+         curl http://localhost:30000/v1/chat/completions \
+           -H "Content-Type: application/json" \
+           -d '{
+             "model": "Qwen/Qwen3-8B",
+             "messages": [{"role": "user", "content": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts (MoE) models"}],
+             "max_tokens": 100,
+             "temperature": 0.7
+           }'
+
+      **You should see LMCache logs like this:**
+
+      **First request** -- prompt plus generated tokens are stored:
+
+      .. code-block:: text
+
+         Prefill batch, #new-seq: 1, #new-token: 35, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0,
+         Decode batch, #running-req: 1, #token: 74, token usage: 0.00, cuda graph: True, gen throughput (token/s): 1.63, #queue-req: 0,
+         Decode batch, #running-req: 1, #token: 114, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.95, #queue-req: 0,
+         LMCache INFO: Stored 128 out of total 135 tokens. size: 0.0195 GB, cost 12.8890 ms, throughput: 1.5153 GB/s (cache_engine.py:623:lmcache.v1.cache_engine)
+
+      **Second request** -- Radix Cache and LMCache share the prefix; only the new portion is stored:
+
+      .. code-block:: text
+
+         Prefill batch, #new-seq: 1, #new-token: 10, #cached-token: 30, token usage: 0.00, #running-req: 0, #queue-req: 0,
+         Decode batch, #running-req: 1, #token: 64, token usage: 0.00, cuda graph: True, gen throughput (token/s): 8.29, #queue-req: 0,
+         Decode batch, #running-req: 1, #token: 104, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.95, #queue-req: 0,
+         Decode batch, #running-req: 1, #token: 144, token usage: 0.00, cuda graph: True, gen throughput (token/s): 87.89, #queue-req: 0,
+         LMCache INFO: Stored 112 out of total 140 tokens. size: 0.0171 GB, cost 11.1986 ms, throughput: 1.5261 GB/s (cache_engine.py:623:lmcache.v1.cache_engine)
+
+      - **Total tokens 140**: SGLang stores KV cache for both prefill and decode tokens together, so total = 40 prompt + 100 generated = 140 tokens.
+      - **Cached tokens: 30**: SGLang's Radix Attention Cache reused 30 tokens from the first request.
+      - **LMCache hit tokens: 24**: LMCache detected 24 tokens (3 full 8-token chunks) stored from the first request. Since Radix Cache already provides 30 tokens in GPU memory, these 24 tokens don't need to be loaded from LMCache or stored again.
+      - **New tokens: 10**: Only 10 prompt tokens need prefill computation (40 prompt - 30 cached = 10).
+      - **Stored 112 out of 140**: 24 tokens (3 full chunks) are already in LMCache and skipped. Of the remaining 116 tokens, 112 (14 full 8-token chunks) are stored.
+
+   .. tab-item:: TensorRT-LLM
+
+      .. note::
+         This integration depends on the connector preset registry from
+         `NVIDIA/TensorRT-LLM PR #12626
+         <https://github.com/NVIDIA/TensorRT-LLM/pull/12626>`_ and the
+         matching LMCache adapter, neither of which has shipped in a
+         stable release yet. Until they do, install both from source:
+
+         .. code-block:: bash
+
+            uv venv --python 3.12
+            source .venv/bin/activate
+
+            # LMCache from source (dev branch)
+            uv pip install git+https://github.com/LMCache/LMCache.git@dev
+
+            # TensorRT-LLM from source — see NVIDIA's build guide:
+            # https://nvidia.github.io/TensorRT-LLM/installation/build-from-source-linux.html
+
+         Once both ship in a stable release, the install command will be:
+
+         .. code-block:: bash
+
+            uv pip install lmcache "tensorrt_llm>=<version>" \
+                --extra-index-url https://pypi.nvidia.com
+
+      LMCache integrates with TensorRT-LLM via TRT-LLM's
+      **KV Cache Connector** API and supports two deployment modes:
+
+      - **In-process mode** (``connector: lmcache``) -- LMCache runs as
+        a singleton inside the TRT-LLM process. Simplest setup; no
+        extra service to manage.
+      - **MP mode** (``connector: lmcache-mp``) -- LMCache runs as a
+        standalone server. Multiple TRT-LLM workers on the same node
+        can share the cache, and the cache survives a TRT-LLM crash.
+
+      .. tab-set::
+         :sync-group: trtllm-mode
+
+         .. tab-item:: In-process mode
+            :sync: inproc
+
+            Configure LMCache via env vars:
+
+            .. code-block:: bash
+
+               export PYTHONHASHSEED=0  # required — chunk hashing depends on stable hash()
+               export LMCACHE_CHUNK_SIZE=256
+               export LMCACHE_LOCAL_CPU=True
+               export LMCACHE_MAX_LOCAL_CPU_SIZE=2.0  # GiB
+
+            Build the TRT-LLM ``LLM`` with ``connector: lmcache``:
+
+            .. code-block:: python
+
+               from tensorrt_llm import LLM, SamplingParams
+               from tensorrt_llm.llmapi.llm_args import (
+                   KvCacheConfig, KvCacheConnectorConfig,
+               )
+
+               llm = LLM(
+                   model="Qwen/Qwen2-1.5B-Instruct",
+                   backend="pytorch",
+                   kv_cache_config=KvCacheConfig(enable_block_reuse=True),
+                   kv_connector_config=KvCacheConnectorConfig(connector="lmcache"),
+               )
+
+               out = llm.generate(["Your prompt here"], SamplingParams(max_tokens=64))
+               print(out[0].outputs[0].text)
+
+         .. tab-item:: MP mode
+            :sync: mp
+
+            ``PYTHONHASHSEED=0`` must be set in **both** terminals --
+            chunk hashing depends on a stable ``hash()``, and the
+            server and client must agree on the seed.
+
+            Start the LMCache server:
+
+            .. code-block:: bash
+
+               export PYTHONHASHSEED=0
+               lmcache server \
+                   --l1-size-gb 10 --eviction-policy LRU --chunk-size 256
+
+            In a separate terminal, point TRT-LLM at the server via
+            ``server_url``:
+
+            .. code-block:: bash
+
+               export PYTHONHASHSEED=0
+               python run_trtllm.py
+
+            where ``run_trtllm.py`` contains:
+
+            .. code-block:: python
+
+               from tensorrt_llm import LLM, SamplingParams
+               from tensorrt_llm.llmapi.llm_args import (
+                   KvCacheConfig, KvCacheConnectorConfig,
+               )
+
+               llm = LLM(
+                   model="Qwen/Qwen2-1.5B-Instruct",
+                   backend="pytorch",
+                   kv_cache_config=KvCacheConfig(enable_block_reuse=True),
+                   kv_connector_config=KvCacheConnectorConfig(
+                       connector="lmcache-mp",
+                       server_url="tcp://localhost:5555",
+                   ),
+               )
+
+               out = llm.generate(["Your prompt here"], SamplingParams(max_tokens=64))
+               print(out[0].outputs[0].text)
+
+      .. note::
+         The TRT-LLM adapter reads :class:`LMCacheEngineConfig` the
+         same way the vLLM adapter does: ``LMCACHE_CONFIG_FILE`` for
+         a YAML file, otherwise individual ``LMCACHE_*`` environment
+         variables. See :doc:`../api_reference/configurations` for
+         all options.
+
+🎉 **You now have LMCache caching and reusing KV caches across all three engines.**
+
+More MP server options
+----------------------
+
+The vLLM MP example above runs ``lmcache server`` locally on the default
+ports. Common variations:
+
+**Custom port or remote host** -- by default the connector talks to
+``localhost:5555``. To use a different port, or a server on another host,
+pass ``lmcache.mp.host`` / ``lmcache.mp.port`` in
+``kv_connector_extra_config``:
+
+.. code-block:: bash
+
+   vllm serve Qwen/Qwen3-8B --kv-transfer-config \
+     '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.host": "tcp://10.0.0.1", "lmcache.mp.port": 6555}}'
+
+**CPU-only (no GPU)** -- the server runs with a ``StubCPUDevice`` and shares
+KV tensors with vLLM over POSIX shared memory. Start ``lmcache server``
+normally, then set ``lmcache.mp.mp_transfer_mode=lmcache_driven`` on the vLLM
+side to enable the zero-copy SHM handle path (the default ``auto`` routing
+maps non-CUDA devices to ``engine_driven``, which uses the worker-side
+gather/scatter copy path instead).
+
+**Docker** -- see :doc:`../production/docker_deployment`.
+
+**HTTP management endpoints** (health, clear-cache, status) -- see
+:doc:`../mp/http_api`.
+
+Next Steps
+----------
+
+- **Performance Testing**: Try the :doc:`benchmarking` section to experience LMCache's performance benefits with more comprehensive examples
+- **Production**: Deploy LMCache with Docker or Kubernetes, plus observability and tuning -- see :doc:`../mp/deployment`
\ No newline at end of file
diff --git a/docs/source/getting_started/quickstart/disaggregated_prefill.rst b/docs/source/getting_started/quickstart/disaggregated_prefill.rst
new file mode 100644
index 0000000..713c1ba
--- /dev/null
+++ b/docs/source/getting_started/quickstart/disaggregated_prefill.rst
@@ -0,0 +1,213 @@
+.. _disaggregated_prefill:
+
+Example: Disaggregated prefill
+==============================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/disaggregated_prefill`.
+
+
+With LMCache as a KV cache transfer library, we can run disaggregated prefill with vLLM.
+Right now, LMCache uses NIXL as a transport layer to enable fast KV cache transfer via NVLink, RDMA, or TCP.
+
+This guide demonstrates how to run LMCache with disaggregated prefill using a single prefiller and decoder setup (1P1D) on a single machine.
+The architecture splits the LLM inference into two stages: prefill and decode, running on separate GPUs for better resource utilization.
+
+Prerequisites
+-------------
+
+Before you begin, ensure you have:
+
+* At least 2 GPUs 
+* Python packages installed:
+    * ``lmcache`` (0.2.1 or above)
+    * ``nixl`` (Install instructions `here <https://github.com/ai-dynamo/nixl>`_)
+    * ``vllm`` (latest main branch)
+    * ``httpx``, ``fastapi``, and ``uvicorn``
+* A valid Hugging Face token (``HF_TOKEN``) with access to Llama 3.1 8B models
+
+* (Recommended) A machine with NVLink or RDMA enabled GPUs
+
+.. note::
+
+    You can use ``ucx_perftest`` to check the GPU-GPU memory transfer and verify the NVLink or RDMA connection.
+    Please refer to this link: `UCX Performance Test <https://ucx-py.readthedocs.io/en/latest/ucx-debug.html>`_.
+
+Architecture Overview
+---------------------
+
+The disaggregated prefill setup consists of three main components:
+
+1. **Prefiller Server (Port 8100)**: Handles the prefill phase of LLM inference
+2. **Decoder Server (Port 8200)**: Manages the decoding/generation phase
+3. **Proxy Server (Port 9000)**: Coordinates between prefiller and decoder
+
+Configuration
+-------------
+
+1. **Prefiller Server Configuration** (``lmcache-prefiller-config.yaml``):
+
+   .. code-block:: yaml
+
+       local_cpu: False
+
+       # PD-related configurations
+       enable_pd: True
+       transfer_channel: "nixl"  # Using NIXL for transfer
+       pd_role: "sender"          # Prefiller acts as KV cache sender
+       pd_proxy_host: "localhost" # Host where proxy server is running
+       pd_proxy_port: 7500        # Port where proxy server is listening
+       pd_buffer_size: 1073741824  # 1GB buffer for KV cache transfer
+       pd_buffer_device: "cuda"   # Use GPU memory for buffer
+
+2. **Decoder Server Configuration** (``lmcache-decoder-config.yaml``):
+
+   .. code-block:: yaml
+
+       local_cpu: False
+
+       # PD-related configurations
+       enable_pd: True
+       transfer_channel: "nixl" # Using NIXL for transfer
+       pd_role: "receiver"        # Decoder acts as KV cache receiver
+       pd_peer_host: "localhost"  # Host where decoder is listening
+       pd_peer_init_port: 7300    # Port where initialization happens
+       pd_peer_alloc_port: 7400   # Port for memory allocation
+       pd_buffer_size: 1073741824  # 1GB buffer for KV cache transfer
+       pd_buffer_device: "cuda"   # Use GPU memory for buffer
+
+Step-by-Step Setup
+------------------
+
+1. **Environment Setup**
+
+   Set your Hugging Face token before running the vLLM servers.
+
+   .. code-block:: bash
+
+       export HF_TOKEN=your_hugging_face_token
+
+2. **Launch the vLLM + LMCache Inference Servers**
+
+   You can launch the components individually:
+
+   a. Launch Decoder (on GPU 1):
+
+      .. code-block:: bash
+
+          UCX_TLS=cuda_ipc,cuda_copy,tcp \
+              LMCACHE_CONFIG_FILE=lmcache-decoder-config.yaml \
+              CUDA_VISIBLE_DEVICES=1 \
+              vllm serve meta-llama/Llama-3.1-8B-Instruct \
+              --port 7200 \
+              --disable-log-requests \
+              --kv-transfer-config \
+              '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer1"}}'
+
+   b. Launch Prefiller (on GPU 0):
+
+      .. code-block:: bash
+
+          UCX_TLS=cuda_ipc,cuda_copy,tcp \
+              LMCACHE_CONFIG_FILE=lmcache-prefiller-config.yaml \
+              CUDA_VISIBLE_DEVICES=0 \
+              vllm serve meta-llama/Llama-3.1-8B-Instruct \
+              --port 7100 \
+              --disable-log-requests \
+              --kv-transfer-config \
+              '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer1"}}'
+
+   c. Launch a proxy server to coordinate between prefiller and decoder:
+
+      The code for the proxy server is available `in vLLM repo <https://github.com/vllm-project/vllm/blob/main/examples/others/lmcache/disagg_prefill_lmcache_v1/disagg_proxy_server.py>`_.
+
+      .. code-block:: bash
+
+          python3 ../disagg_proxy_server.py \
+            --host localhost \
+            --port 9100 \
+            --prefiller-host localhost \
+            --prefiller-port 7100 \
+            --num-prefillers 1 \
+            --decoder-host localhost \
+            --decoder-port 7200  \
+            --decoder-init-port 7300 \
+            --decoder-alloc-port 7400 \
+            --proxy-host localhost \
+            --proxy-port 7500 \
+            --num-decoders 1
+
+.. note::
+
+    The ``UCX_TLS`` environment variable is used to specify the transport layer for UCX (the example uses NVLink)
+    The ``CUDA_VISIBLE_DEVICES`` environment variable is used to specify the GPUs to use for the servers.
+    
+
+3. **Verify Setup**
+
+   The servers are ready when you can access:
+   
+   * Prefiller: ``http://localhost:7100/v1/completions``
+   * Decoder: ``http://localhost:7200/v1/completions``
+   * Proxy: ``http://localhost:9100/v1/completions``
+
+Usage
+-----
+
+Send requests to the proxy server (port 9000) using either the completions or chat completions endpoint:
+
+.. code-block:: bash
+
+    curl http://localhost:9000/v1/completions \
+        -H "Content-Type: application/json" \
+        -d '{
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "prompt": "Tell me a story",
+            "max_tokens": 100
+        }'
+
+You can also test the setup with the following command, which runs vLLM's serving benchmark:
+
+.. code-block:: bash
+
+    git clone https://github.com/vllm-project/vllm.git
+    cd vllm/benchmarks
+    vllm bench serve --port 9000 --seed $(date +%s) \
+        --model meta-llama/Llama-3.1-8B-Instruct \
+        --dataset-name random --random-input-len 5000 --random-output-len 200 \
+        --num-prompts 50 --burstiness 100 --request-rate 1
+
+Monitoring
+----------
+
+The prefiller instance will log the throughput of KV cache transfer:
+
+    LMCache INFO: Store 5271 tokens takes: 6.5000 ms, throughput: 98.9889 GB/s; offload_time: 2.6594 ms, put_time: 3.4539 ms (cache_engine.py:190:lmcache.v1.cache_engine)
+
+The decoder instance will log how many tokens are fetched from the LMCache:
+
+    LMCache INFO: Reqid: cmpl-b8bf01cbe47e4d108732ceeb4158d310-0, Total tokens 5170, LMCache hit tokens: 5169, need to load: 5169 (vllm_v1_adapter.py:543:lmcache.integration.vllm.vllm_v1_adapter)
+
+The proxy server will log the TTFT of the prefiller node:
+
+.. code-block:: text
+
+    ===============================
+    Num requests: 49
+    Prefill node TTFT stats:
+    - Average (ms): 0.1530598815606565
+    - Median (ms): 0.15739011764526367
+    - 99th Percentile (ms): 0.1643616008758545
+    ===============================
+
+
+Troubleshooting
+---------------
+
+Common issues and solutions:
+
+1. **GPU Requirements**: Ensure you have at least 2 GPUs available
+2. **Port Conflicts**: Check if ports used above are available
+3. **HF Token**: Verify your token starts with ``hf_`` and has necessary model access
+4. **CUDA Errors**: Ensure CUDA_VISIBLE_DEVICES is set correctly for each server
diff --git a/docs/source/getting_started/quickstart/index.rst b/docs/source/getting_started/quickstart/index.rst
new file mode 100644
index 0000000..14782ab
--- /dev/null
+++ b/docs/source/getting_started/quickstart/index.rst
@@ -0,0 +1,72 @@
+.. _quickstart_examples:
+
+More Examples
+=============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+This section provides quick examples to help you get started with LMCache's key features.
+
+KV Cache Offloading
+-------------------
+
+KV cache offloading allows you to move KV caches from GPU memory to CPU memory or other storage devices. This feature is particularly useful when:
+
+- There are requests shares the same prefix (e.g., long system prompt, reusing chat history in chat applications, or caching offline-processed data).
+- The GPU memory is limited to save all the KV caches.
+
+By offloading KV caches, LMCache can reduce both time-to-first-token (TTFT) and GPU cycles.
+
+See :ref:`offload_kv_cache` for more details.
+
+KV Cache Sharing
+----------------
+
+KV cache sharing enables sharing the KV cache across different LLM instances. This feature is beneficial when:
+
+- There are multiple LLM instances running in the same system.
+- The requests that share the same prefix may go to different LLM instances.
+
+Sharing KV caches also reduces TTFT and GPU computation by eliminating redundant calculations across different LLM instances.
+
+See :ref:`share_kv_cache` for more details.
+
+Disaggregated Prefill
+---------------------
+
+Disaggregated prefill separates the prefill and decode phases across different compute resources. This approach:
+
+- Allows specialized hardware allocation for each phase of inference
+- Enables more efficient resource utilization in distributed settings
+- Improves overall system throughput by optimizing for the different computational patterns of prefill vs. decode
+
+This architecture is particularly valuable in large-scale deployment scenarios where maximizing resource efficiency and keeping a stable generation speed are both important.
+
+See :ref:`disaggregated_prefill` for more details.
+
+Standalone Starter
+------------------
+
+The LMCache Standalone Starter allows you to run LMCacheEngine as a standalone service without vLLM or GPU dependencies. This is particularly useful for:
+
+- Testing and development environments
+- CPU-only deployments
+- Distributed cache scenarios
+- Integration with custom applications
+
+See :ref:`standalone_starter` for more details.
+
+Detailed Examples
+-----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   offload_kv_cache
+   share_kv_cache
+   disaggregated_prefill 
+   multimodality
+   standalone_starter
\ No newline at end of file
diff --git a/docs/source/getting_started/quickstart/multimodality.rst b/docs/source/getting_started/quickstart/multimodality.rst
new file mode 100644
index 0000000..29cd341
--- /dev/null
+++ b/docs/source/getting_started/quickstart/multimodality.rst
@@ -0,0 +1,225 @@
+Example: Multimodal KV Cache Support
+====================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+Quick Start Example (Audio Model): 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We  going to be running audio inference with ``ultravox-v0_5-llama-3_2-1b`` and using LMCache to speed up the TTFT after the first request.
+
+**Install and Serve:** 
+
+``pip install lmcache vllm[audio] openai``
+
+.. code-block:: bash
+
+   vllm serve fixie-ai/ultravox-v0_5-llama-3_2-1b \
+       --max-model-len 4096 --trust-remote-code \
+       --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+
+**Benchmark:** 
+
+Save as ``audio_query.py``
+
+.. code-block:: python
+
+   # SPDX-License-Identifier: Apache-2.0
+   # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+
+   import base64
+
+   import requests
+   from openai import OpenAI
+
+   # SPDX-License-Identifier: Apache-2.0
+   # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+   from openai import APIConnectionError, OpenAI
+   from openai.pagination import SyncPage
+   from openai.types.model import Model
+
+   import time
+
+   def get_first_model(client: OpenAI) -> str:
+       """
+       Get the first model from the vLLM server.
+       """
+       try:
+           models: SyncPage[Model] = client.models.list()
+       except APIConnectionError as e:
+           raise RuntimeError(
+               "Failed to get the list of models from the vLLM server at "
+               f"{client.base_url} with API key {client.api_key}. Check\n"
+               "1. the server is running\n"
+               "2. the server URL is correct\n"
+               "3. the API key is correct"
+           ) from e
+
+       if len(models.data) == 0:
+           raise RuntimeError(f"No models found on the vLLM server at {client.base_url}")
+
+       return models.data[0].id
+
+   # Modify OpenAI's API key and API base to use vLLM's API server.
+   openai_api_key = "EMPTY"
+   openai_api_base = "http://localhost:8000/v1"
+
+   client = OpenAI(
+       # defaults to os.environ.get("OPENAI_API_KEY")
+       api_key=openai_api_key,
+       base_url=openai_api_base,
+   )
+
+
+   def encode_base64_content_from_url(content_url: str) -> str:
+       """Encode a content retrieved from a remote url to base64 format."""
+
+       with requests.get(content_url) as response:
+           response.raise_for_status()
+           result = base64.b64encode(response.content).decode("utf-8")
+
+       return result
+   # Audio input inference
+   def run_audio(model: str) -> None:
+       from vllm.assets.audio import AudioAsset
+   
+       audio_url = AudioAsset("winning_call").url
+       audio_base64 = encode_base64_content_from_url(audio_url)
+   
+       # OpenAI-compatible schema (`input_audio`)
+       chat_completion_from_base64 = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this audio?"},
+                       {
+                           "type": "input_audio",
+                           "input_audio": {
+                               # Any format supported by librosa is supported
+                               "data": audio_base64,
+                               "format": "wav",
+                           },
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_base64.choices[0].message.content
+       print("Chat completion output from input audio:", result)
+   
+       # HTTP URL
+       chat_completion_from_url = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this audio?"},
+                       {
+                           "type": "audio_url",
+                           "audio_url": {
+                               # Any format supported by librosa is supported
+                               "url": audio_url
+                           },
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_url.choices[0].message.content
+       print("Chat completion output from audio url:", result)
+   
+       # base64 URL
+       chat_completion_from_base64 = client.chat.completions.create(
+           messages=[
+               {
+                   "role": "user",
+                   "content": [
+                       {"type": "text", "text": "What's in this audio?"},
+                       {
+                           "type": "audio_url",
+                           "audio_url": {
+                               # Any format supported by librosa is supported
+                               "url": f"data:audio/ogg;base64,{audio_base64}"
+                           },
+                       },
+                   ],
+               }
+           ],
+           model=model,
+           max_completion_tokens=64,
+       )
+   
+       result = chat_completion_from_base64.choices[0].message.content
+       print("Chat completion output from base64 encoded audio:", result)
+       
+   start_time = time.time()
+
+   model = get_first_model(client)
+   run_audio(model)
+   end_time = time.time()
+   print(f"Time taken: {end_time - start_time} seconds")   
+
+
+**Run and see TTFT speedup:** 
+
+.. code-block:: bash
+
+   # first time: 
+   python audio_query.py
+
+   # second time: 
+   python audio_query.py
+
+
+**Retrieval and speed up in logs:**
+
+1. After First Request:
+
+.. code-block:: text
+
+   [2025-08-05 09:58:06,965] LMCache INFO: Reqid: chatcmpl-dd6e8a131f2b455fa3cd133a9bfab26f, Total tokens 201, LMCache hit tokens: 201, need to load: 8 (vllm_v1_adapter.py:803:lmcache.integration.vllm.vllm_v1_adapter)
+   [2025-08-05 09:58:06,967] LMCache INFO: Retrieved 201 out of 201 out of total 201 tokens (cache_engine.py:500:lmcache.v1.cache_engine)
+   [2025-08-05 09:58:07,178] LMCache INFO: Storing KV cache for 256 out of 256 tokens (skip_leading_tokens=0) for request chatcmpl-dd6e8a131f2b455fa3cd133a9bfab26f (vllm_v1_adapter.py:709:lmcache.integration.vllm.vllm_v1_adapter)
+   [2025-08-05 09:58:07,178] LMCache INFO: Stored 256 out of total 256 tokens. size: 0.0078 gb, cost 0.5096 ms, throughput: 15.3291 GB/s; offload_time: 0.4897 ms, put_time: 0.0200 ms (cache_engine.py:251:lmcache.v1.cache_engine)
+
+*Example Output:*
+
+.. code-block:: text
+
+   Chat completion output from input audio: It seems like you're excitedly sharing your thoughts and predictions about a game you're about to watch. The audio appears to be a stream of text messages or social media updates. The words and phrases you've copied seem to indicate that you're a sports fan, particularly in Major League Baseball (MLB). 
+
+   Are
+   Chat completion output from audio url: It appears to be a enthusiastic and excited baseball comment from an individual. The language used, such as "And the one pitch on the way to Edgar Martinez has swung on and line down the line for a base hit," suggests a strong amateur athlete's excitement and commentary. The reference to the playoff qualification and the praise for
+   Chat completion output from base64 encoded audio: It seems like you're excited about a sports game, possibly the California Athletics (now known as the Los Angeles Angels), given the reference to Edgar Martinez and the Birds (no team by that name in the AL) in the mixed messages.
+
+   However, I'm not seeing any audio in the conversation. Are you referring to
+   Time taken: 37.96290421485901 seconds
+
+2. After Second Request: 
+
+.. code-block:: text
+
+   [2025-08-05 09:58:07,371] LMCache INFO: Reqid: chatcmpl-2a130545a6a24f33b41e219ef0807a61, Total tokens 201, LMCache hit tokens: 201, need to load: 8 (vllm_v1_adapter.py:803:lmcache.integration.vllm.vllm_v1_adapter)
+   [2025-08-05 09:58:07,372] LMCache INFO: Retrieved 201 out of 201 out of total 201 tokens (cache_engine.py:500:lmcache.v1.cache_engine)
+   [2025-08-05 09:58:07,558] LMCache INFO: Storing KV cache for 256 out of 256 tokens (skip_leading_tokens=0) for request chatcmpl-2a130545a6a24f33b41e219ef0807a61 (vllm_v1_adapter.py:709:lmcache.integration.vllm.vllm_v1_adapter)
+   [2025-08-05 09:58:07,558] LMCache INFO: Stored 256 out of total 256 tokens. size: 0.0078 gb, cost 0.4962 ms, throughput: 15.7450 GB/s; offload_time: 0.4782 ms, put_time: 0.0179 ms (cache_engine.py:251:lmcache.v1.cache_engine)
+
+*Example Output:*
+
+.. code-block:: text
+
+   Chat completion output from input audio: It seems like you're extremely excited about the possibility of the San Francisco Giants winning the American League championship and playing in the World Series. The audio is filled with emotions and a sense of optimism, with you enthusiastically expressing your thoughts and feelings. It's clear that this is a significant moment for you, particularly given the fact
+   Chat completion output from audio url: I can tell you're excited about a baseball game. It seems like you're reliving a moment during the middle of a game, especially the highlight of a six runs game for the Golden Giants. The audio appears to include a local sports radio talk show style broadcast, with a narrator (or DJs) discussing the importance
+   Chat completion output from base64 encoded audio: It seems like you're having a lively discussion about baseball, specifically about the Arizona Diamondbacks and their chances of winning the American League championship. You're using colloquial expressions and slang, such as "the Oone hitter," " rejoice," and "waving him in." These cues suggest that you're engaged in
+   Time taken: 5.39893364906311 seconds
\ No newline at end of file
diff --git a/docs/source/getting_started/quickstart/offload_kv_cache.rst b/docs/source/getting_started/quickstart/offload_kv_cache.rst
new file mode 100644
index 0000000..b3e6872
--- /dev/null
+++ b/docs/source/getting_started/quickstart/offload_kv_cache.rst
@@ -0,0 +1,480 @@
+.. _offload_kv_cache:
+
+Example: Offload KV cache to CPU
+================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+In this example, we will show you how to offload KV cache to CPU memory.
+
+.. note::
+    Besides CPU memory, LMCache also supports offloading KV cache to many different destinations.
+    See :ref:`getting_started/quickstart/offload_kv_cache:Supported offloading destinations` for more details.
+
+Prerequisites
+-------------
+
+Before you begin, make sure you have:
+
+- vLLM v1 with LMCache installed (see :doc:`Installation <../installation>`)
+- A GPU that can run a LLM
+
+
+Use CPU offloading in offline inference
+---------------------------------------
+
+This section demonstrates how to use CPU memory offloading in offline inference scenarios using LMCache with vLLM.
+The example script we use here is available in `vLLM examples <https://github.com/vllm-project/vllm/blob/main/examples/others/lmcache/cpu_offload_lmcache.py>`_.
+See the `examples README <https://github.com/vllm-project/vllm/tree/main/examples/others/lmcache#2-cpu-offload-examples>`_ to understand how to run the script for vLLM v1.
+
+First, set up the necessary environment variables for LMCache:
+
+.. code-block:: python
+
+    import os
+
+    # Set token chunk size to 256
+    os.environ["LMCACHE_CHUNK_SIZE"] = "256"
+    # Enable CPU memory backend
+    os.environ["LMCACHE_LOCAL_CPU"] = "True"
+    # Set CPU memory limit to 5GB
+    os.environ["LMCACHE_MAX_LOCAL_CPU_SIZE"] = "5.0"
+
+Next, configure vLLM with LMCache integration:
+
+.. code-block:: python
+
+    from vllm import LLM, SamplingParams
+    from vllm.config import KVTransferConfig
+
+    # Configure KV cache transfer to use LMCache
+    ktc = KVTransferConfig(
+        kv_connector="LMCacheConnectorV1",
+        kv_role="kv_both",
+    )
+
+    # Initialize LLM with LMCache configuration
+    # Adjust gpu_memory_utilization based on your GPU memory
+    llm = LLM(model="Qwen/Qwen3-8B",
+              kv_transfer_config=ktc,
+              max_model_len=8000,
+              gpu_memory_utilization=0.8)
+
+Now you can run inference with automatic KV cache offloading:
+
+.. code-block:: python
+
+    # Create example prompts with shared prefix
+    shared_prompt = "Hello, how are you?" * 1000
+    prompts = [
+        shared_prompt + "Hello, my name is",
+    ]
+
+    # Define sampling parameters
+    sampling_params = SamplingParams(temperature=0, top_p=0.95, max_tokens=10)
+
+    # Run inference
+    outputs = llm.generate(prompts, sampling_params)
+    for output in outputs:
+        generated_text = output.outputs[0].text
+        print(f"Generated text: {generated_text!r}")
+
+When the inference is complete, clean up the LMCache backend:
+
+.. code-block:: python
+
+    from lmcache.v1.cache_engine import LMCacheEngineBuilder
+    from lmcache.integration.vllm.utils import ENGINE_NAME
+
+    LMCacheEngineBuilder.destroy(ENGINE_NAME)
+
+During inference, LMCache will automatically handle storing and managing KV cache in CPU memory. You can monitor this through the logs, which will show messages like::
+
+    LMCache INFO: Storing KV cache for 6006 out of 6006 tokens for request 0
+
+This indicates that the KV cache has been successfully offloaded to CPU memory.
+
+.. note::
+    - Adjust ``gpu_memory_utilization`` based on your GPU's available memory
+    - The CPU offloading buffer size can be adjusted through ``LMCACHE_MAX_LOCAL_CPU_SIZE``
+
+Use CPU offloading in online inference
+--------------------------------------
+
+This section demonstrates how to use CPU memory offloading in online serving scenarios. 
+
+First, create a configuration file named ``lmcache_config.yaml`` with the following content:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    max_local_cpu_size: 5
+
+.. note::
+    LMCache supports extensive configuration through a ``lmcache_config.yaml`` file where you can customize chunk sizes, memory limits, storage backends, and more. We'll cover advanced configuration options in later examples. For now, let's run a minimal example with default configuration.
+
+Launch the vLLM server with LMCache integration using environment variables. Here's an example command:
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE=lmcache_config.yaml \
+    vllm serve \
+        Qwen/Qwen3-8B \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1",
+          "kv_role":"kv_both"
+        }'
+
+Key parameters explained:
+
+- ``LMCACHE_CONFIG_FILE``: Path to the LMCache configuration file.
+- ``--kv-transfer-config``: Configures LMCache integration
+    - ``kv_connector``: Specifies the LMCache connector 
+    - ``kv_role``: Set to "kv_both" for both storing and loading KV cache
+
+Once the server is running, you can send requests to it using curl. Here's an example of how to send a request to the vLLM server with LMCache integration:
+
+.. code-block:: bash
+
+    curl http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "Qwen/Qwen3-8B",
+        "prompt": "<|im_start|>system\nYou are a helpful AI assistant.<|im_end|>\n<|im_start|>user\nWhat is the capital of France?<|im_end|>\n<|im_start|>assistant\n",
+        "max_tokens": 100,
+        "temperature": 0.7
+      }'
+
+You should see the following logs:
+
+.. code-block:: text
+    :emphasize-lines: 1
+
+    LMCache INFO: Storing KV cache for 31 out of 31 tokens for request cmpl-274bcaa80837444dbf9fbba4155d2620-0 (vllm_v1_adapter.py:497:lmcache.integration.vllm.vllm_v1_adapter)
+
+Once you send the same curl request again, you should see the following logs:
+
+.. code-block:: text
+    :emphasize-lines: 1
+
+    LMCache INFO: Reqid: cmpl-4ddf8863a6ac4dc3b6a952f2a107e9b2-0, Total tokens 31, LMCache hit tokens: 30, need to load: 14 (vllm_v1_adapter.py:543:lmcache.integration.vllm.vllm_v1_adapter)
+
+
+Example: CPU offloading benefits
+--------------------------------
+
+This section demonstrates the performance benefits of using CPU offloading with LMCache. We'll use a script that generates multiple prompts and compare the performance with and without LMCache.
+
+Prerequisites (Setup)
+~~~~~~~~~~~~~~~~~~~~~~
+
+- A CUDA GPU. The example picks a model that fits the GPU automatically:
+
+  - ``Qwen/Qwen3-8B`` (bf16) when the GPU has ~36 GiB or more (e.g. A100-80G, H100).
+  - ``Qwen/Qwen3-8B-FP8`` with ``kv_cache_dtype="fp8"`` when the GPU has ~24 GiB
+    and supports native FP8 (Ada Lovelace / Hopper, ``sm_89+``; e.g. L4, L40, RTX 4090).
+  - ``Qwen/Qwen3-1.7B`` as the fallback for smaller GPUs (~10 GiB and up),
+    including Ampere 24 GiB cards (RTX A5000, RTX 3090) where FP8 is unsupported.
+
+- Sufficient CPU memory. The example clamps the LMCache pinned host buffer to
+  fit your system RAM and ``RLIMIT_MEMLOCK`` (``ulimit -l``), so it also works
+  on smaller hosts without manual tuning.
+
+Example script
+~~~~~~~~~~~~~~
+
+Save the following script as ``cpu-offloading.py``:
+
+.. code-block:: python
+
+    # SPDX-License-Identifier: Apache-2.0
+    """
+    This file demonstrates the example usage of cpu offloading
+    with LMCache in vLLM v1.
+
+    Note that lmcache needs to be installed to run this example.
+    Learn more about LMCache in https://github.com/LMCache/LMCache.
+    """
+    import os
+    import torch
+    import argparse
+    import time
+    from lmcache.v1.cache_engine import LMCacheEngineBuilder
+    from lmcache.integration.vllm.utils import ENGINE_NAME
+    from vllm import LLM, SamplingParams
+    from vllm.config import KVTransferConfig
+
+    def parse_arguments() -> argparse.Namespace:
+        """Parse command line arguments."""
+        parser = argparse.ArgumentParser(description="CPU offloading example with LMCache")
+        parser.add_argument("--num-prompts", type=int, default=10,
+                          help="Number of prompts to generate (default: 10)")
+        parser.add_argument("--num-tokens", type=int, default=10000,
+                          help="Number of tokens per prompt (default: 10000)")
+        parser.add_argument("--enable-lmcache", action="store_true",
+                          help="Enable LMCache for CPU offloading (default: True)")
+        return parser.parse_args()
+
+    def pick_cpu_size_gb(workload_gb: float) -> float:
+        """
+        Clamp the LMCache pinned host buffer to fit system RAM and RLIMIT_MEMLOCK.
+
+        cudaHostAlloc pins pages, so the buffer cannot exceed total RAM nor the
+        per-process memlock limit (`ulimit -l`). On hosts where either is small,
+        the original "1.5 GB per 10k tokens" formula fails with cudaErrorMemoryAllocation.
+
+        Args:
+            workload_gb: Desired buffer size for the workload, in GiB.
+        Returns:
+            float: A buffer size in GiB that fits both caps, never below 1.0.
+        """
+        import psutil
+
+        ram_gib = psutil.virtual_memory().total / (1024 ** 3)
+        try:
+            import resource
+            memlock_soft, _ = resource.getrlimit(resource.RLIMIT_MEMLOCK)
+            memlock_gib = (
+                float("inf")
+                if memlock_soft == resource.RLIM_INFINITY
+                else memlock_soft / (1024 ** 3)
+            )
+        except ImportError:
+            # `resource` is POSIX-only; on Windows treat memlock as unbounded.
+            memlock_gib = float("inf")
+        return max(min(workload_gb, ram_gib * 0.5, memlock_gib * 0.9), 1.0)
+
+    def setup_lmcache_environment(num_prompts: int, num_tokens: int) -> None:
+        """
+        Configure LMCache environment variables.
+        Args:
+            num_prompts: Number of prompts to process
+            num_tokens: Number of tokens per prompt
+        """
+        workload_gb = num_prompts * num_tokens * 1.5 / 10000  # 1.5 GB per 10k tokens
+        cpu_size = pick_cpu_size_gb(workload_gb)
+
+        env_vars = {
+            "LMCACHE_CHUNK_SIZE": "256",         # Set tokens per chunk
+            "LMCACHE_LOCAL_CPU": "True",         # Enable local CPU backend
+            "LMCACHE_MAX_LOCAL_CPU_SIZE": str(cpu_size)  # CPU memory limit (GB)
+        }
+        for key, value in env_vars.items():
+            os.environ[key] = value
+
+    def pick_model_and_kwargs() -> tuple[str, dict]:
+        """
+        Pick a Qwen model that fits the current GPU's memory and compute capability.
+
+        Tiers:
+            - >= 36 GiB                    -> Qwen/Qwen3-8B (bf16)
+            - >= 20 GiB and sm >= 89       -> Qwen/Qwen3-8B-FP8 (native FP8)
+            - >= 10 GiB                    -> Qwen/Qwen3-1.7B
+            - otherwise                    -> RuntimeError
+
+        Returns:
+            tuple[str, dict]: (model id, extra kwargs to pass to ``LLM``).
+        Raises:
+            RuntimeError: If no CUDA GPU is visible or it is too small.
+        """
+        if not torch.cuda.is_available():
+            raise RuntimeError("No GPU available")
+
+        total_gib = torch.cuda.get_device_properties(0).total_memory / (1024 ** 3)
+        major, minor = torch.cuda.get_device_capability(0)
+        sm = major * 10 + minor
+        has_fp8 = sm >= 89  # Ada Lovelace / Hopper
+
+        if total_gib >= 36:
+            return "Qwen/Qwen3-8B", {}
+        if total_gib >= 20 and has_fp8:
+            print(f"[fallback] GPU {total_gib:.1f} GiB sm_{sm}: using Qwen3-8B-FP8")
+            return "Qwen/Qwen3-8B-FP8", {"kv_cache_dtype": "fp8"}
+        if total_gib >= 10:
+            print(f"[fallback] GPU {total_gib:.1f} GiB sm_{sm}: using Qwen3-1.7B")
+            return "Qwen/Qwen3-1.7B", {}
+        raise RuntimeError(
+            f"GPU has {total_gib:.1f} GiB; need at least 10 GiB for Qwen3-1.7B"
+        )
+
+    def create_test_prompts(num_prompts: int = 10, num_tokens: int = 1000) -> list[str]:
+        """
+        Create test prompts with index prefix and dummy body.
+        Args:
+            num_prompts: Number of prompts to generate
+            num_tokens: Approximate number of tokens per prompt (using 'Hi ' as token unit)
+        Returns:
+            list: List of prompts with format '[index] Hi Hi Hi...'
+        """
+        prompts = []
+        dummy_text = "Hi " * num_tokens
+
+        for i in range(num_prompts):
+            prompt = f"[Prompt {i}] {dummy_text} how are you?"
+            prompts.append(prompt)
+
+        return prompts
+
+    def initialize_llm(max_len: int = 16384, enable_lmcache: bool = True) -> LLM:
+        """
+        Initialize the LLM with a model auto-selected for the current GPU.
+        Args:
+            max_len: Maximum sequence length
+            enable_lmcache: Whether to wire up the LMCache KV connector
+        Returns:
+            LLM: Configured LLM instance
+        """
+        model_name, extra_kwargs = pick_model_and_kwargs()
+
+        ktc = KVTransferConfig(
+            kv_connector="LMCacheConnectorV1",
+            kv_role="kv_both",
+        ) if enable_lmcache else None
+
+        return LLM(
+            model=model_name,
+            kv_transfer_config=ktc,
+            max_model_len=max_len,
+            enable_prefix_caching=False,
+            gpu_memory_utilization=0.9,
+            **extra_kwargs,
+        )
+
+    def generate_and_print_output(
+        llm: LLM,
+        prompts: list[str],
+        sampling_params: SamplingParams,
+    ) -> float:
+        """
+        Generate text and print the results.
+        Args:
+            llm: LLM instance
+            prompts: List of input prompts
+            sampling_params: Configured sampling parameters
+        Returns:
+            float: Time taken for generation in seconds
+        """
+        start_time = time.time()
+        outputs = llm.generate(prompts, sampling_params)
+        end_time = time.time()
+
+        for output in outputs:
+            generated_text = output.outputs[0].text
+            print(f"Generated text: {generated_text!r}")
+
+        return end_time - start_time
+
+    def main() -> None:
+        """Main execution function."""
+        # Parse command line arguments
+        args = parse_arguments()
+        
+        # Setup environment if LMCache is enabled
+        if args.enable_lmcache:
+            setup_lmcache_environment(args.num_prompts, args.num_tokens)
+        
+        # Create prompts and sampling parameters
+        prompts = create_test_prompts(num_prompts=args.num_prompts, num_tokens=args.num_tokens)
+        sampling_params = SamplingParams(temperature=0, top_p=0.95, max_tokens=1)
+        
+        # Initialize model
+        llm = initialize_llm(enable_lmcache=args.enable_lmcache)
+        
+        # First run
+        print("\nFirst run:")
+        first_run_time = generate_and_print_output(llm, prompts, sampling_params)
+        print(f"First run time: {first_run_time:.2f} seconds")
+        
+        # Second run
+        print("\nSecond run:")
+        second_run_time = generate_and_print_output(llm, prompts, sampling_params)
+        print(f"Second run time: {second_run_time:.2f} seconds")
+        
+        # Print speedup
+        if first_run_time > 0:
+            speedup = first_run_time / second_run_time
+            print(f"\nSpeedup (first run / second run): {speedup:.2f}x")
+        
+        # Cleanup if LMCache was enabled
+        if args.enable_lmcache:
+            LMCacheEngineBuilder.destroy(ENGINE_NAME)
+
+    if __name__ == "__main__":
+        main()
+
+Running the Example
+~~~~~~~~~~~~~~~~~~~
+
+1. First, run the script without LMCache:
+
+   .. code-block:: bash
+
+       python cpu-offloading.py 
+
+   You'll see output like:
+
+   .. code-block:: text
+
+       Speedup (first run / second run): 1.00x
+
+   Without LMCache, there's no speedup between runs even if vLLM has prefix caching enabled.
+   This is because the KV cache exceeds GPU memory and can't be reused.
+
+2. Now, run with LMCache enabled:
+
+   .. code-block:: bash
+
+       python cpu-offloading.py --enable-lmcache
+
+   You'll see output like:
+
+   .. code-block:: text
+
+       Speedup (first run / second run): 7.43x
+
+The significant speedup in the second case demonstrates how LMCache effectively manages KV cache offloading to CPU memory. 
+When the total size of KV cache exceeds GPU memory, LMCache allows you to store and reuse the cache from CPU memory, 
+resulting in much faster subsequent generations for prompts with shared prefixes.
+
+
+Supported offloading destinations
+---------------------------------
+
+LMCache now supports offloading KV cache to the following destinations:
+
+- :doc:`CPU memory <../../kv_cache/storage_backends/cpu_ram>`
+- :doc:`Local file system <../../kv_cache/storage_backends/local_storage>`
+- :doc:`Mooncake Storage <../../kv_cache/storage_backends/mooncake>`
+- :doc:`InfiniStore <../../kv_cache/storage_backends/infinistore>`
+- :doc:`Redis <../../kv_cache/storage_backends/redis>`
+- :doc:`ValKey <../../kv_cache/storage_backends/valkey>`
+
+Troubleshooting
+---------------
+
+If you encounter the following error:
+
+.. code-block:: text
+
+    (EngineCore_DP0 pid=55437) ERROR 10-04 14:44:47 [core.py:708] RuntimeError: 
+    Cannot re-initialize CUDA in forked subprocess. To use CUDA with multiprocessing, you must use the 'spawn' start method
+
+You can resolve this issue using one of the following methods:
+
+- Set ``VLLM_WORKER_MULTIPROC_METHOD=spawn`` in the environment variables.
+- Or update the Python code to guard usage of vllm behind a if ``__name__ == '__main__':`` block.
+
+.. code-block:: python
+
+    if __name__ == '__main__':
+        from vllm import LLM, SamplingParams
+        from vllm.config import KVTransferConfig
+        from lmcache.v1.cache_engine import LMCacheEngineBuilder
+        from lmcache.integration.vllm.utils import ENGINE_NAME
+        main()
+
+For details, please refer to the `vLLM Troubleshooting Guide: Python multiprocessing <https://docs.vllm.ai/en/latest/usage/troubleshooting.html#python-multiprocessing>`_.
\ No newline at end of file
diff --git a/docs/source/getting_started/quickstart/share_kv_cache.rst b/docs/source/getting_started/quickstart/share_kv_cache.rst
new file mode 100644
index 0000000..8a0e258
--- /dev/null
+++ b/docs/source/getting_started/quickstart/share_kv_cache.rst
@@ -0,0 +1,270 @@
+.. _share_kv_cache:
+
+Example: Share KV cache across multiple LLMs
+============================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+LMCache should be able to reduce the generation time of the second and following calls.
+
+We have examples for the following types of across-instance KV cache sharing:
+
+- KV cache sharing through a centralized cache server: ``centralized_sharing``
+- KV cache sharing through p2p cache transfer: ``p2p_sharing``
+
+Prerequisites
+-------------
+
+Your server should have at least 2 GPUs.
+
+For Centralized sharing, this will use the port 8000 and 8001 (for vLLM) and port 65432 (for LMCache).  
+
+For P2P sharing: 
+
+- `NIXL <https://github.com/ai-dynamo/nixl>`_ installed on the host.
+- Port 8010 and 8011 for 2 vllms servers.
+- Port 8200 and 8202 for 2 p2p initialization connections.
+- Port 8201 and 8203 for 2 p2p lookup connections.
+- Port 8300 for controller pull requests.
+- Port 8400 for controller reply requests.
+- Port 8500 and 8501 for 2 LMCache workers.
+- Port 9000 for controller main port (arbitrary and can be changed) to start the controller.
+
+Centralized KV cache sharing
+----------------------------
+
+This section demonstrates how to share KV cache across multiple vLLM instances using a centralized LMCache server.
+
+**Important**: For centralized cache sharing (which is cross-process cases), ensure all processes use the same `PYTHONHASHSEED` to keep the hash of the KV cache consistent across processes: ``export PYTHONHASHSEED=0``.
+
+Setup centralized sharing
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First, create a configuration file named ``lmcache_config.yaml`` with the following content:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    remote_url: "lm://localhost:65432"
+    remote_serde: "cachegen"
+
+Run centralized sharing example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Start the LMCache centralized server,
+
+.. code-block:: bash
+
+    lmcache_server localhost 65432
+
+2. In a different terminal,
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=0 \
+    LMCACHE_CONFIG_FILE=lmcache_config.yaml \
+    CUDA_VISIBLE_DEVICES=0 \
+    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+        --gpu-memory-utilization 0.8 \
+        --port 8000 --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+In another terminal,
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=0 \
+    LMCACHE_CONFIG_FILE=lmcache_config.yaml \
+    CUDA_VISIBLE_DEVICES=1 \
+    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+        --gpu-memory-utilization 0.8 \
+        --port 8001 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Wait until both engines are ready.
+
+3.  Send one request to the engine at port 8000,
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+        -H "Content-Type: application/json" \
+        -d '{
+            "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models.",
+            "max_tokens": 10
+        }'
+
+4. Send the same request to the engine at port 8001,
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8001/v1/completions \
+        -H "Content-Type: application/json" \
+        -d '{
+            "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models.",
+            "max_tokens": 10
+        }'
+
+The second request will automatically retrieve and reuse the KV cache from the first instance, significantly reducing generation time.
+
+P2P KV cache sharing
+--------------------
+
+This section demonstrates how to share KV cache across multiple vLLM instances using peer-to-peer transfer.
+
+Configure LMCache instances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create two configuration files for the P2P sharing setup. The values that differ between the files are the ``lmcache_instance_id`` and the P2P/controller port assignments.
+
+Instance 1 configuration (``p2p_example1.yaml``):
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    max_local_cpu_size: 5
+    enable_async_loading: True
+
+    # P2P configurations
+    enable_p2p: true
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+    p2p_lookup_ports: 8201
+    transfer_channel: "nixl"
+
+    # Controller configurations
+    enable_controller: true
+    lmcache_instance_id: "lmcache_instance_1"
+    controller_pull_url: "localhost:8300"
+    controller_reply_url: "localhost:8400"
+    lmcache_worker_ports: 8500
+
+    extra_config:
+      lookup_backoff_time: 0.001
+
+Instance 2 configuration (``p2p_example2.yaml``):
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    max_local_cpu_size: 5
+    enable_async_loading: True
+
+    # P2P configurations
+    enable_p2p: true
+    p2p_host: "localhost"
+    p2p_init_ports: 8202
+    p2p_lookup_ports: 8203
+    transfer_channel: "nixl"
+
+    # Controller configurations
+    enable_controller: true
+    lmcache_instance_id: "lmcache_instance_2"
+    controller_pull_url: "localhost:8300"
+    controller_reply_url: "localhost:8400"
+    lmcache_worker_ports: 8501
+
+    extra_config:
+      lookup_backoff_time: 0.001
+
+Save both files in the directory that you will mount into the container (referenced later as ``$YAML_FILES``).
+
+Run the P2P sharing workflow
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Configure the environment on the host and open a shell inside the container:
+
+.. code-block:: bash
+
+    docker pull vllm/vllm-openai:latest
+    export WEIGHT_DIR="/models"          # model weights directory
+    export CONTAINER_NAME="lmcache_vllm" # container name
+    export YAML_FILES="/path/to/yaml"    # directory containing the YAML files
+    docker run --name "$CONTAINER_NAME" \
+            --detach \
+            --ipc=host \
+            --network host \
+            --gpus all \
+            --volume "$WEIGHT_DIR:$WEIGHT_DIR" \
+            --volume "$YAML_FILES:$YAML_FILES" \
+            --entrypoint "/bin/bash" \
+            vllm/vllm-openai:latest -c "time sleep 452d"
+    docker exec -it "$CONTAINER_NAME" /bin/bash
+    pip install -U lmcache # update lmcache to the latest version
+
+2. Start the LMCache controller and monitoring endpoints:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-ports '{"pull": 8300, "reply": 8400}'
+
+3. Launch two vLLM engines, each with its own LMCache worker configuration.
+
+Start vLLM engine 1 on GPU 0:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=p2p_example1.yaml \
+    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+        --gpu-memory-utilization 0.8 \
+        --port 8010 \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Start vLLM engine 2 on GPU 1:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=p2p_example2.yaml \
+    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+        --gpu-memory-utilization 0.8 \
+        --port 8011 \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+4. Populate the KV cache by sending a request to the first engine:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8010/v1/completions \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
+            \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+            \"max_tokens\": 10
+        }"
+
+5. Send the same request to the second engine to demonstrate cache retrieval:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8011/v1/completions \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
+            \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+            \"max_tokens\": 10
+        }"
+
+Expected output
+~~~~~~~~~~~~~~~
+
+When the second request successfully retrieves the cache from the first instance, the logs should include entries similar to:
+
+.. code-block:: bash
+
+    (EngineCore_DP0 pid=305) [2025-11-16 07:24:11,522] LMCache INFO: Got layout info from controller: ('lmcache_instance_2', 'LocalCPUBackend', 3, 'localhost:8202') (p2p_backend.py:196:lmcache.v1.storage_backend.p2p_backend)                                                  
+    (EngineCore_DP0 pid=305) [2025-11-16 07:24:11,607] LMCache INFO: Established connection to peer_init_url localhost:8202. The peer_lookup_url: localhost:8203 (p2p_backend.py:349:lmcache.v1.storage_backend.p2p_backend)                                                      
+    (EngineCore_DP0 pid=305) [2025-11-16 07:24:11,706] LMCache INFO: Responding to scheduler for lookup id cmpl-e9ec2875bf954bd298ca26d14e083b80-0 with retrieved length 768 (storage_manager.py:531:lmcache.v1.storage_backend.storage_manager)                                  
+    (EngineCore_DP0 pid=305) [2025-11-16 07:24:11,708] LMCache INFO: Reqid: cmpl-e9ec2875bf954bd298ca26d14e083b80-0, Total tokens 1002, LMCache hit tokens: 768, need to load: 768 (vllm_v1_adapter.py:1330:lmcache.integration.vllm.vllm_v1_adapter)                             
+    (EngineCore_DP0 pid=305) [2025-11-16 07:24:11,724] LMCache INFO: Retrieved 768 out of 768 required tokens (from 768 total tokens). size: 0.0938 gb, cost 7.9816 ms, throughput: 11.7458 GB/s; (cache_engine.py:531:lmcache.v1.cache_engine)
+
+
+These logs indicate that the peer connection was established and the cache was transferred successfully.
diff --git a/docs/source/getting_started/quickstart/standalone_starter.rst b/docs/source/getting_started/quickstart/standalone_starter.rst
new file mode 100644
index 0000000..4cf7ac8
--- /dev/null
+++ b/docs/source/getting_started/quickstart/standalone_starter.rst
@@ -0,0 +1,303 @@
+.. _standalone_starter:
+
+Standalone Starter
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The LMCache Standalone Starter allows you to run LMCacheEngine as a standalone service without vLLM or GPU dependencies. This is particularly useful for:
+
+- Testing and development environments
+- CPU-only or P2P backend deployments
+
+Quick Start
+-----------
+
+Basic Usage
+~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Start with default configuration
+   python -m lmcache.v1.standalone
+
+   # Start with custom configuration file
+   python -m lmcache.v1.standalone --config examples/cache_with_configs/example.yaml
+
+   # Start with environment variables
+   export LMCACHE_CONFIG_FILE=examples/cache_with_configs/example.yaml
+   python -m lmcache.v1.standalone
+
+CPU-Only Mode
+~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.standalone \
+       --config examples/cache_with_configs/example.yaml \
+       --model_name my_model \
+       --worker_id 0 \
+       --world_size 1
+
+Remote P2P Mode
+~~~~~~~~~~~~~
+TO be added
+
+Configuration Section
+---------------------
+
+The standalone starter supports multiple configuration sources with the following priority order:
+
+1. **Command-line arguments** (highest priority)
+2. **Configuration file** (specified by ``--config`` or ``LMCACHE_CONFIG_FILE``)
+3. **Environment variables** (e.g., ``LMCACHE_CHUNK_SIZE=512``)
+4. **Default values** (lowest priority)
+
+Parameter Details
+~~~~~~~~~~~~~~~~~
+
+**KV Cache Shape Specification**
+
+The ``--kvcache_shape_spec`` parameter supports multi-layer group configurations:
+
+- Format: ``(shape_string):dtype:layer_count;[...]``
+- shape_string: comma-separated shape (e.g., '2,2,256,4,16')
+- Examples:
+  - Single group: ``(2,2,256,4,16):float16:2``
+  - Multiple groups: ``(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3``
+
+**Device Support**
+
+- ``--device=cpu``: CPU-only mode (default)
+- ``--device=cuda``: CUDA GPU acceleration
+- ``--device=xpu``: XPU GPU acceleration
+
+**MLA (Multi-Level Attention)**
+
+- ``--use_mla``: Enable MLA for improved attention performance
+- Requires compatible model and configuration
+
+**Cache Formats**
+
+- ``--fmt=vllm``: vLLM-compatible format (default)
+- Supports other formats for different inference engines
+
+Command-Line Parameters
+-----------------------
+
+Basic Parameters
+~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   --config CONFIG_FILE             # Path to configuration file
+   --model_name MODEL_NAME          # Model name for cache identification
+   --worker_id WORKER_ID            # Worker ID (default: 0)
+   --world_size WORLD_SIZE          # Total workers (default: 1)
+   --kv_dtype {float16,float32,bfloat16,uint8}  # KV cache data type
+   --kv_shape KV_SHAPE              # KV cache shape (default: "2,2,256,4,16")
+   --kvcache_shape_spec SPEC       # Multi-group KV shape specification
+   --device {cpu,cuda,xpu}          # Device to run on (default: cpu)
+   --fmt FORMAT                     # Cache format (default: vllm)
+   --use_mla                        # Enable MLA (Multi-Level Attention)
+
+
+Usage Examples
+--------------
+
+Custom Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.standalone \
+       --config examples/cache_with_configs/example.yaml \
+       --chunk_size=512 \
+       --max_local_cpu_size=4.0 \
+       --model_name=custom_model
+
+Multi-Layer Group Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.standalone \
+       --config examples/cache_with_configs/example.yaml \
+       --kvcache_shape_spec="(2,2,256,4,16):float16:2" \
+       --kv_shape="2,2,256,4,16" \
+       --model_name=multi_group_model \
+       --device=cpu
+
+GPU device
+~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.standalone \
+       --config examples/cache_with_configs/example.yaml \
+       --kvcache_shape_spec="(2,2,256,4,16):float16:2" \
+       --kv_shape="2,2,256,4,16" \
+       --kv_dtype=float16 \
+       --device=cuda \
+       --use_mla \
+       --model_name=gpu_model
+
+MLA Configuration
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   python -m lmcache.v1.standalone \
+       --config examples/cache_with_configs/example.yaml \
+       --kv_shape="16,2,512,16,64" \
+       --kv_dtype=bfloat16 \
+       --use_mla \
+       --fmt=vllm \
+       --model_name=mla_model
+
+Internal API Server
+-------------------
+
+The standalone starter includes an internal API server for monitoring and management:
+
+.. code-block:: bash
+
+   python -m lmcache.v1.standalone \
+       --config examples/cache_with_configs/example.yaml \
+       --chunk_size=512 \
+       --max_local_cpu_size=4.0 \
+       --model_name=custom_model \
+       --internal_api_server_enabled=True
+
+
+Troubleshooting
+----------------
+
+Common Issues
+~~~~~~~~~~~~~
+
+**Issue**: "No config file specified"
+**Solution**: Set ``LMCACHE_CONFIG_FILE`` or use ``--config`` parameter
+
+**Issue**: "Failed to connect to controller"
+**Solution**: Start controller first: ``python -m lmcache.v1.api_server``
+
+**Issue**: "Invalid KV shape specification"
+**Solution**: Check format: ``(shape):dtype:layer_count``, e.g., ``(2,2,256,4,16):float16:2``
+
+**Issue**: "Device not available"
+**Solution**: Verify device support: use ``--device=cpu`` if GPU not available
+
+**Issue**: "MLA configuration error"
+**Solution**: Ensure compatible model and check ``--use_mla`` parameter
+
+Debug Mode
+~~~~~~~~~~
+
+Enable debug logging for troubleshooting:
+
+.. code-block:: bash
+
+   export LMCACHE_LOG_LEVEL=DEBUG
+   python -m lmcache.v1.standalone
+
+Advanced Debugging
+~~~~~~~~~~~~~~~~~~
+
+For detailed layer group information:
+
+.. code-block:: bash
+
+   export LMCACHE_LOG_LEVEL=DEBUG
+   python -m lmcache.v1.standalone \
+       --kvcache_shape_spec="(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3" \
+       --device=cpu
+
+Performance Tuning
+------------------
+
+Memory Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # For systems with large memory
+   --max_local_cpu_size=8.0
+
+   # For memory-constrained systems
+   --max_local_cpu_size=1.0
+
+Layer Group Optimization
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Optimize for mixed precision models
+   --kvcache_shape_spec="(2,2,256,4,16):float16:2;(3,2,256,4,4):bfloat16:3"
+
+   # Optimize for different layer configurations
+   --kvcache_shape_spec="(2,2,512,8,32):float16:4;(4,2,256,16,16):float32:2"
+
+GPU Acceleration
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # GPU-optimized configuration
+   --device=cuda --kv_dtype=float16 --use_mla
+
+   # Large model on GPU
+   --device=cuda --kv_shape="64,2,512,64,128" --max_local_cpu_size=16.0
+
+MLA Performance
+~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Enable MLA for attention optimization
+   --use_mla --kv_dtype=bfloat16 --device=cuda
+
+   # MLA with custom shape
+   --use_mla --kv_shape="32,2,1024,32,64" --fmt=vllm
+
+
+Best Practices
+--------------
+
+1. **Use configuration files** for production deployments
+2. **Set appropriate cache sizes** based on available memory
+3. **Enable internal API** for monitoring and management
+4. **Monitor logs** for performance and error tracking
+5. **Use multi-layer group configurations** for complex model architectures
+6. **Enable MLA** for improved attention performance on supported hardware
+7. **Choose appropriate device** based on available resources (CPU/GPU/XPU)
+8. **Validate KV shape specifications** before deployment
+9. **Test with debug logging** when configuring new layer groups
+10. **Optimize chunk sizes** for specific hardware configurations
+
+Multi-Layer Group Best Practices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Use consistent chunk sizes across layer groups for optimal performance
+- Group layers with similar precision requirements together
+- Validate shape specifications in development environment first
+- Monitor memory usage when using multiple layer groups
+
+MLA Configuration Tips
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- Enable MLA only on supported hardware configurations
+- Use bfloat16 or float16 precision for best MLA performance
+- Test MLA performance impact before production deployment
+- Monitor attention performance metrics with MLA enabled
+
+Related Documentation
+---------------------
+
+- :doc:`../quickstart`
+- :doc:`../../api_reference/configurations`
+- :doc:`../../kv_cache/storage_backends/index`
+- :doc:`../../kv_cache_management/index`
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..2189143
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,203 @@
+.. LMCache documentation master file, created by
+   sphinx-quickstart on Mon Sep 30 10:39:18 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. role:: raw-html(raw)
+    :format: html
+
+Welcome to LMCache!
+=====================
+
+.. figure:: ./assets/lmcache-logo_crop.png
+  :width: 60%
+  :align: center
+  :alt: LMCache
+  :class: no-scaled-link
+
+.. rst-class:: hero-tagline
+
+**A KV Cache Management Layer for Scalable LLM Inference.**
+
+.. note::
+   We are currently in the process of upgrading our documentation to provide better guidance and examples. Some sections may be under construction. Thank you for your patience!
+
+.. raw:: html
+
+   <p style="text-align:center">
+   <script async defer src="https://buttons.github.io/buttons.js"></script>
+   <a class="github-button" href="https://github.com/LMCache/LMCache" data-show-count="true" data-size="large" aria-label="Star">Star</a>
+   <a class="github-button" href="https://github.com/LMCache/LMCache/subscription" data-icon="octicon-eye" data-size="large" aria-label="Watch">Watch</a>
+   <a class="github-button" href="https://github.com/LMCache/LMCache/fork" data-show-count="true" data-icon="octicon-repo-forked" data-size="large" aria-label="Fork">Fork</a>
+   </p>
+
+.. container:: hero-description
+
+   LMCache is a **KV cache management layer** for LLM inference. It turns KV cache from a temporary state into reusable *AI-native knowledge* that can be *stored* persistently, *reused* across multiple serving engines, *monitored* with an observability stack, and *transformed* for better generation quality. As a result, LMCache **reduces TTFT** (time-to-first-token) and **improves throughput**, especially for long-context agentic, multi-turn conversation, and knowledge-augmented workloads (e.g., RAG).
+
+   LMCache is **vendor-neutral**. It can be used as a KV cache layer for a range of mainstream open-source serving engines, inference frameworks, hardware vendors, storage systems, and infrastructure providers. The vendor neutrality allows users to freely switch between serving engines and storage vendors, while reusing the stored KV caches.
+
+.. image:: ./assets/deployment_modes_light.png
+  :width: 90%
+  :align: center
+  :alt: LMCache Deployment Modes
+  :class: only-light no-scaled-link
+
+.. image:: ./assets/deployment_modes_dark.png
+  :width: 90%
+  :align: center
+  :alt: LMCache Deployment Modes
+  :class: only-dark no-scaled-link
+
+:raw-html:`<br />`
+
+Key features
+------------
+
+- **Engine-independent deployment**: LMCache, as a standalone daemon process, manages KV cache independently from the inference engine process, so that KV cache will not be lost even if the inference engine crashes (i.e., no fate-sharing with engines).
+
+- **Persistent, tiered KV cache offloading and reuse**: Move KV caches out of GPU memory into a tiered storage hierarchy spanning CPU memory, local storage, and remote backends, enabling reuse across requests, sessions, and engine instances to reduce repeated prefill computation and improve TTFT.
+
+- **Production-level KV cache observability**: LMCache provides a rich set of KV cache observability metrics, including typical Kubernetes metrics (health monitoring, performance diagnostics), KV-cache-specific metrics (request-level and token-level prefix cache hits, lifecycle, request-level KV cache performance), management metrics (user-specific usage), and more.
+
+- **Pluggable storage and transport backends**: Easily integrate remote storage and KV transfer backends through a unified interface, enabling KV cache offloading and sharing across storage providers. Through this interface, LMCache supports storage backends including CPU RAM, local disk (SSD), Redis/Valkey, Mooncake, InfiniStore, S3-compatible object storage, NIXL, and GDS.
+
+- **Non-prefix KV reuse**: Extend KV reuse beyond prefix caching by reusing cached KV blocks at any position in the prompt. This leverages CacheBlend to selectively recompute tokens for quality recovery.
+
+- **PD disaggregation and KV transfer**: Support KV cache transfer from prefill workers to decode workers over NVLink, RDMA, or TCP through transport layers such as NIXL.
+
+- **Pluggable KV transformation**: A simple interface for researchers to write compression, token dropping, and custom serialization through a flexible SERDE interface.
+
+LMCache is becoming an integral layer in the LLM inference *ecosystem*, with *community*-driven integration with serving engines, inference frameworks, hardware vendors, storage systems, and infrastructure providers:
+
+.. figure:: ./assets/ecosystem.png
+  :width: 90%
+  :align: center
+  :alt: LMCache ecosystem
+  :class: no-scaled-link
+
+:raw-html:`<br />`
+
+Updates
+-------
+
+- [2026/06] 🔥 LMCache multi-platform development support with no GPU required (`blog <https://blog.lmcache.ai/en/2026/06/23/vllm-lmcache-a-starter-guide-no-gpu-required/>`__, `blog <https://blog.lmcache.ai/en/2026/06/15/understanding-lmcache-mp-mode-transfer-paths-a-beginners-guide/>`__).
+- [2026/05] 🔥 Agentic workload benchmark on AMD MI300X (`blog <https://blog.lmcache.ai/en/2026/05/12/benchmarking-lmcache-for-multi-turn-agentic-workloads-on-amd-mi300x/>`__).
+- [2026/04] 🔥 LMCache's new multiprocess (MP) architecture release (`blog <https://blog.lmcache.ai/en/2026/04/03/lmcaches-new-architecture-boosts-moe-inference-performance-by-10x/>`__).
+- [2026/03] LMCache at GTC 2026 (`post <https://www.linkedin.com/posts/lmcache-lab_llm-opensource-nvidiagtc-activity-7442721875664826369-pMAu>`__).
+- [2026/01] LMCache multi-node P2P CPU memory sharing, from experimental feature to production (`blog <https://blog.lmcache.ai/en/2026/01/21/p2p-1/>`__).
+
+.. dropdown:: More
+
+   - [2025/11] LMCache x CoreWeave accelerate efficient LLM inference for Cohere (`blog <https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/>`__).
+   - [2025/10] LMCache joins the PyTorch Foundation and Tensormesh unveiled (`blog <https://blog.lmcache.ai/en/2025/10/31/tensormesh-unveiled-and-lmcache-joins-the-pytorch-foundation/>`__, `PyTorch <https://pytorch.org/blog/lmcache-joins-pytorch-ecosystem/>`__).
+   - [2025/09] NVIDIA Dynamo integrates LMCache, accelerating LLM inference (`blog <https://blog.lmcache.ai/en/2025/09/18/nvidia-dynamo-integrates-lmcache-accelerating-llm-inference/>`__).
+   - [2025/08] 🎉 LMCache hits 5,000+ GitHub stars (`blog <https://blog.lmcache.ai/en/2025/08/28/%f0%9f%8e%89-lmcache-hits-5000-github-stars-thank-you-community/>`__).
+   - [2025/08] LMCache supports gpt-oss (20B/120B) on day 1 (`blog <https://blog.lmcache.ai/en/2025/08/05/lmcache-supports-gpt-oss-20b-120b-on-day-1/>`__).
+   - [2025/07] Get faster LLM inference and cheaper responses with LMCache and Redis (`Redis blog <https://redis.io/blog/get-faster-llm-inference-and-cheaper-responses-with-lmcache-and-redis/>`__).
+   - [2025/07] LMCache extends its turbo-boost to multimodal models in vLLM V1 (`blog <https://blog.lmcache.ai/en/2025/07/03/lmcache-extends-its-turbo-boost-to-multimodal-models-in-vllm-v1/>`__).
+   - [2025/06] LLM Production Stack goes cross-hardware: AMD, Arm and Ascend (`blog <https://blog.lmcache.ai/en/2025/06/20/llm-production-stack-goes-cross-hardware-ascend-arm-and-amd-support-incoming/>`__).
+
+:raw-html:`<br />`
+
+
+For more information, check out the following:
+
+* `LMCache blogs <https://lmcache.github.io>`_
+* `Join LMCache slack workspace <https://join.slack.com/t/lmcacheworkspace/shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA>`_
+* Our papers:
+
+  * `CacheGen: KV Cache Compression and Streaming for Fast Large Language Model Serving <https://dl.acm.org/doi/10.1145/3651890.3672274>`_
+  * `CacheBlend: Fast Large Language Model Serving with Cached Knowledge Fusion <https://arxiv.org/abs/2405.16444>`_
+  * `Do Large Language Models Need a Content Delivery Network? <https://arxiv.org/abs/2409.13761>`_
+
+:raw-html:`<br />`
+
+
+Documentation
+-------------
+
+
+.. toctree::
+   :maxdepth: 2
+
+   getting_started/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 3
+
+   interacting_with_server
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 3
+
+   recipes/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 4
+
+   mp/l2_storage/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   distributed_kv_cache
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   production/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   mp/observability/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   community/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   kv_cache_optimizations/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   developer_guide/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   non_kv_cache/index
+
+:raw-html:`<br />`
+
+.. toctree::
+   :maxdepth: 2
+
+   legacy/index
+
+:raw-html:`<br />`
\ No newline at end of file
diff --git a/docs/source/interacting_with_server.rst b/docs/source/interacting_with_server.rst
new file mode 100644
index 0000000..51c21f8
--- /dev/null
+++ b/docs/source/interacting_with_server.rst
@@ -0,0 +1,13 @@
+KV Cache Operations
+===================
+
+Ways to inspect, manage, and observe a running ``lmcache server`` -- from the
+command line, over HTTP, or through the web frontend.
+
+.. toctree::
+   :maxdepth: 2
+
+   cli/index
+   mp/http_api
+   mp/frontend_dashboard
+   mp/sdk
diff --git a/docs/source/internal_api_server/common_apis.rst b/docs/source/internal_api_server/common_apis.rst
new file mode 100644
index 0000000..fd2306b
--- /dev/null
+++ b/docs/source/internal_api_server/common_apis.rst
@@ -0,0 +1,355 @@
+.. _common_apis:
+
+Common APIs
+===========
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/http_api`.
+
+
+Common APIs are available across all components (scheduler, worker, controller).
+
+.. contents:: Endpoints
+   :local:
+   :depth: 2
+
+
+``GET /env`` — Environment Variables
+-------------------------------------
+
+Get all environment variables of the running process.
+
+- **Method**: ``GET``
+- **Path**: ``/env``
+- **Parameters**: None
+- **Response**: ``application/json`` — JSON object of all environment variables (sorted by key).
+
+.. code-block:: bash
+
+    curl http://localhost:7000/env
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "HOME": "/root",
+      "PATH": "/usr/local/bin:/usr/bin",
+      "PYTHONPATH": "/app"
+    }
+
+
+``GET /loglevel`` — Log Level Management
+------------------------------------------
+
+Get or set the log level for Python loggers. Behavior depends on query parameters:
+
+- **No parameters**: List all loggers and their levels.
+- **``logger_name`` only**: Get the level of the specified logger.
+- **``logger_name`` and ``level``**: Set the level of the specified logger (including all its handlers).
+
+- **Method**: ``GET``
+- **Path**: ``/loglevel``
+- **Parameters**:
+
+  =============== ======== ============================================
+  Name            Type     Description
+  =============== ======== ============================================
+  ``logger_name`` str      (Optional) Logger name to query or set
+  ``level``       str      (Optional) Log level to set (e.g. ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``)
+  =============== ======== ============================================
+
+- **Response**: ``text/plain``
+
+.. code-block:: bash
+
+    # List all loggers
+    curl http://localhost:7000/loglevel
+
+    # Get a specific logger level
+    curl "http://localhost:7000/loglevel?logger_name=lmcache.v1.cache_engine"
+
+    # Set a specific logger level
+    curl "http://localhost:7000/loglevel?logger_name=lmcache.v1.cache_engine&level=DEBUG"
+
+**Example Response** (list all):
+
+.. code-block:: text
+
+    === Loggers and Levels ===
+    lmcache.v1.cache_engine: WARNING
+    lmcache.v1.storage_backend: INFO
+
+**Example Response** (get):
+
+.. code-block:: text
+
+    lmcache.v1.cache_engine: WARNING
+
+**Example Response** (set):
+
+.. code-block:: text
+
+    Set lmcache.v1.cache_engine level to DEBUG (including all handlers)
+
+**Error Response** (invalid level, HTTP 400):
+
+.. code-block:: text
+
+    Invalid log level: INVALID_LEVEL
+
+
+``GET /metrics`` — Prometheus Metrics
+--------------------------------------
+
+Get Prometheus metrics data in the standard exposition format.
+
+- **Method**: ``GET``
+- **Path**: ``/metrics``
+- **Parameters**: None
+- **Response**: ``text/plain`` — Prometheus text-based exposition format.
+
+.. code-block:: bash
+
+    curl http://localhost:7000/metrics
+
+
+``POST /metrics/reset`` — Reset Prometheus Metrics
+----------------------------------------------------
+
+Reset all Prometheus metrics to their initial state.
+
+- **Method**: ``POST``
+- **Path**: ``/metrics/reset``
+- **Parameters**: None
+- **Response**: ``text/plain`` — ``"ok"`` on success.
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/metrics/reset
+
+
+``GET /threads`` — Thread Information
+--------------------------------------
+
+Get information about active threads with optional filtering.
+
+- **Method**: ``GET``
+- **Path**: ``/threads``
+- **Parameters**:
+
+  ============== ======= ===========================================
+  Name           Type    Description
+  ============== ======= ===========================================
+  ``name``       str     (Optional) Filter by thread name (fuzzy match, case-insensitive)
+  ``thread_id``  int     (Optional) Filter by thread ID
+  ============== ======= ===========================================
+
+- **Response**: ``text/plain`` — Thread info with stack traces and summary.
+
+.. code-block:: bash
+
+    # Get all threads
+    curl http://localhost:7000/threads
+
+    # Filter by name
+    curl "http://localhost:7000/threads?name=api-server"
+
+    # Filter by thread ID
+    curl "http://localhost:7000/threads?thread_id=12345"
+
+
+``GET /periodic-threads`` — Periodic Thread Status
+----------------------------------------------------
+
+Get information about registered periodic threads.
+
+- **Method**: ``GET``
+- **Path**: ``/periodic-threads``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``level``        str     (Optional) Filter by thread level: ``critical``, ``high``, ``medium``, ``low``
+  ``running_only`` bool    (Optional) Only show running threads (default: ``false``)
+  ``active_only``  bool    (Optional) Only show active threads (default: ``false``)
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    # Get all periodic threads
+    curl http://localhost:7000/periodic-threads
+
+    # Filter by level
+    curl "http://localhost:7000/periodic-threads?level=critical"
+
+    # Only running threads
+    curl "http://localhost:7000/periodic-threads?running_only=true"
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "summary": {
+        "total_count": 5,
+        "running_count": 3,
+        "active_count": 3,
+        "by_level": {
+          "critical": {"total": 1, "running": 1, "active": 1},
+          "high": {"total": 2, "running": 1, "active": 1}
+        }
+      },
+      "threads": [
+        {
+          "name": "heartbeat",
+          "level": "critical",
+          "is_running": true,
+          "is_active": true,
+          "last_run_time": "2025-01-01T00:00:00",
+          "interval": 10.0
+        }
+      ]
+    }
+
+**Error Response** (invalid level, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "error": "Invalid level: unknown. Valid values: critical, high, medium, low"
+    }
+
+
+``GET /periodic-threads/{thread_name}`` — Single Periodic Thread
+------------------------------------------------------------------
+
+Get detailed information about a specific periodic thread by name.
+
+- **Method**: ``GET``
+- **Path**: ``/periodic-threads/{thread_name}``
+- **Path Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``thread_name``  str     Name of the periodic thread
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/periodic-threads/heartbeat
+
+**Error Response** (not found, HTTP 404):
+
+.. code-block:: json
+
+    {
+      "error": "Thread not found: heartbeat"
+    }
+
+
+``GET /periodic-threads-health`` — Periodic Thread Health Check
+-----------------------------------------------------------------
+
+Quick health check for periodic threads. Returns healthy status if all
+``critical`` and ``high`` level threads are active.
+
+- **Method**: ``GET``
+- **Path**: ``/periodic-threads-health``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/periodic-threads-health
+
+**Example Response** (healthy):
+
+.. code-block:: json
+
+    {
+      "healthy": true,
+      "unhealthy_count": 0,
+      "unhealthy_threads": []
+    }
+
+**Example Response** (unhealthy):
+
+.. code-block:: json
+
+    {
+      "healthy": false,
+      "unhealthy_count": 1,
+      "unhealthy_threads": [
+        {
+          "name": "heartbeat",
+          "level": "critical",
+          "last_run_ago": 120.5,
+          "interval": 10.0
+        }
+      ]
+    }
+
+
+``POST /run_script`` — Run Script
+-----------------------------------
+
+Upload and execute a Python script in a restricted sandbox environment.
+The script has access to ``app`` (the FastAPI application instance) and
+a limited set of builtins. Import is restricted to modules configured
+in ``script_allowed_imports``.
+
+- **Method**: ``POST``
+- **Path**: ``/run_script``
+- **Content-Type**: ``multipart/form-data``
+- **Parameters**:
+
+  ============ ======== =============================================
+  Name         Type     Description
+  ============ ======== =============================================
+  ``script``   file     Python script file to execute
+  ============ ======== =============================================
+
+- **Response**: ``text/plain`` — The ``result`` variable from the script, or
+  ``"Script executed successfully"`` if no ``result`` is set.
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/run_script \
+      -F "script=@/path/to/scratch.py"
+
+**Example Script** (``scratch.py``):
+
+.. code-block:: python
+
+    lmcache_engine = app.state.lmcache_adapter.lmcache_engine
+
+    result = {
+        "is_first_rank": lmcache_engine.metadata.is_first_rank(),
+        "model_version": lmcache_engine.metadata.kv_shape,
+    }
+
+**Example Response**:
+
+.. code-block:: text
+
+    {'is_first_rank': True, 'model_version': (27, 1, 64, 1, 576)}
+
+**Error Response** (no script, HTTP 400):
+
+.. code-block:: text
+
+    No script file provided
+
+**Error Response** (execution error, HTTP 500):
+
+.. code-block:: text
+
+    Error executing script: Import of 'os' is not allowed
diff --git a/docs/source/internal_api_server/controller_apis.rst b/docs/source/internal_api_server/controller_apis.rst
new file mode 100644
index 0000000..6d08553
--- /dev/null
+++ b/docs/source/internal_api_server/controller_apis.rst
@@ -0,0 +1,201 @@
+.. _controller_apis:
+
+Controller APIs
+===============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/http_api`.
+
+
+These APIs are specific to the LMCache Controller component. They provide
+visibility into registered instances, workers, and key statistics.
+
+.. contents:: Endpoints
+   :local:
+   :depth: 2
+
+
+``GET /controller/key-stats`` — Key Statistics
+------------------------------------------------
+
+Get key statistics across all instances and workers.
+
+- **Method**: ``GET``
+- **Path**: ``/controller/key-stats``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:6999/controller/key-stats
+
+**Example Response** (HTTP 200):
+
+.. code-block:: json
+
+    {
+      "total_key_count": 1500,
+      "total_instance_count": 2,
+      "total_worker_count": 4,
+      "instances": [
+        {
+          "instance_id": "instance_001",
+          "key_count": 800,
+          "worker_count": 2
+        },
+        {
+          "instance_id": "instance_002",
+          "key_count": 700,
+          "worker_count": 2
+        }
+      ]
+    }
+
+**Error Response** (controller not available, HTTP 503):
+
+.. code-block:: json
+
+    {
+      "detail": "Controller manager not available"
+    }
+
+**Response Schema**:
+
+  ========================= ======= =============================================
+  Field                     Type    Description
+  ========================= ======= =============================================
+  ``total_key_count``       int     Total number of KV keys across all instances
+  ``total_instance_count``  int     Total number of registered instances
+  ``total_worker_count``    int     Total number of workers across all instances
+  ``instances``             list    Per-instance breakdown (see below)
+  ========================= ======= =============================================
+
+**Instance Schema**:
+
+  ================= ======= =============================================
+  Field             Type    Description
+  ================= ======= =============================================
+  ``instance_id``   str     Unique identifier of the instance
+  ``key_count``     int     Number of KV keys held by this instance
+  ``worker_count``  int     Number of workers in this instance
+  ================= ======= =============================================
+
+
+``GET /controller/workers`` — Worker Information
+--------------------------------------------------
+
+Get worker information with flexible query parameters. Behavior depends
+on the combination of parameters:
+
+- **No parameters**: List all registered workers across all instances.
+- **``instance_id`` only**: List all workers for a specific instance.
+- **``instance_id`` and ``worker_id``**: Get detailed info about a specific worker.
+
+- **Method**: ``GET``
+- **Path**: ``/controller/workers``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``instance_id``  str     (Optional) Instance ID to filter workers
+  ``worker_id``    int     (Optional) Worker ID for specific worker details (requires ``instance_id``)
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    # List all workers
+    curl http://localhost:6999/controller/workers
+
+    # List workers for a specific instance
+    curl "http://localhost:6999/controller/workers?instance_id=instance_001"
+
+    # Get a specific worker
+    curl "http://localhost:6999/controller/workers?instance_id=instance_001&worker_id=0"
+
+**Example Response** (list workers):
+
+.. code-block:: json
+
+    {
+      "workers": [
+        {
+          "instance_id": "instance_001",
+          "worker_id": 0,
+          "ip": "10.0.0.1",
+          "port": 8000,
+          "peer_init_url": "http://10.0.0.1:8000/init",
+          "registration_time": 1706745600.0,
+          "last_heartbeat_time": 1706745660.0,
+          "key_count": 400
+        },
+        {
+          "instance_id": "instance_001",
+          "worker_id": 1,
+          "ip": "10.0.0.2",
+          "port": 8001,
+          "peer_init_url": "http://10.0.0.2:8001/init",
+          "registration_time": 1706745600.0,
+          "last_heartbeat_time": 1706745660.0,
+          "key_count": 400
+        }
+      ],
+      "total_count": 2
+    }
+
+**Example Response** (single worker):
+
+.. code-block:: json
+
+    {
+      "instance_id": "instance_001",
+      "worker_id": 0,
+      "ip": "10.0.0.1",
+      "port": 8000,
+      "peer_init_url": "http://10.0.0.1:8000/init",
+      "registration_time": 1706745600.0,
+      "last_heartbeat_time": 1706745660.0,
+      "key_count": 400
+    }
+
+**Error Response** (worker not found, HTTP 404):
+
+.. code-block:: json
+
+    {
+      "detail": "Worker (instance_001, 99) not found"
+    }
+
+**Error Response** (instance not found, HTTP 404):
+
+.. code-block:: json
+
+    {
+      "detail": "No workers found for instance unknown_instance"
+    }
+
+**Error Response** (controller not available, HTTP 503):
+
+.. code-block:: json
+
+    {
+      "detail": "Controller manager not available"
+    }
+
+**Worker Response Schema**:
+
+  ========================== ======= =============================================
+  Field                      Type    Description
+  ========================== ======= =============================================
+  ``instance_id``            str     Instance this worker belongs to
+  ``worker_id``              int     Worker index within the instance
+  ``ip``                     str     Worker IP address
+  ``port``                   int     Worker port number
+  ``peer_init_url``          str     (Optional) Peer initialization URL
+  ``registration_time``      float   Unix timestamp of worker registration
+  ``last_heartbeat_time``    float   Unix timestamp of last heartbeat
+  ``key_count``              int     Number of KV keys held by this worker
+  ========================== ======= =============================================
diff --git a/docs/source/internal_api_server/dynamic_backend_management.rst b/docs/source/internal_api_server/dynamic_backend_management.rst
new file mode 100644
index 0000000..7e03c8a
--- /dev/null
+++ b/docs/source/internal_api_server/dynamic_backend_management.rst
@@ -0,0 +1,181 @@
+.. _dynamic_backend_management:
+
+Dynamic Backend Management
+==========================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/http_api`.
+
+
+LMCache provides a set of internal API endpoints that allow you to **list**,
+**close**, and **create** storage backends at runtime without restarting the
+serving engine.  This is useful when you need to switch between different
+storage configurations on the fly — for example, migrating from a
+``LocalDiskBackend`` to a ``GdsBackend``, or changing the remote connector
+from a filesystem connector to Redis.
+
+Overview
+--------
+
+The workflow for dynamically switching a storage backend is:
+
+1. **Close** the backend you want to replace.
+2. **Update** the relevant configuration via the ``POST /conf`` API.
+3. **Create** new backends — only backends that are not already present
+   will be created.
+
+Any backend that was **not** closed will be skipped during creation,
+so the operation is safe and idempotent.
+
+API Endpoints
+-------------
+
+``GET /backends``
+^^^^^^^^^^^^^^^^^
+
+List all active storage backends.
+
+.. code-block:: bash
+
+    curl http://localhost:7000/backends
+
+Response:
+
+.. code-block:: json
+
+    {
+      "LocalCPUBackend": "LocalCPUBackend",
+      "RemoteBackend": "RemoteBackend"
+    }
+
+``DELETE /backends/{backend_name}``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Close and remove a specific storage backend.  After this call the backend
+is fully shut down and removed from the internal dictionary, ensuring no
+stale references remain.
+
+.. code-block:: bash
+
+    curl -X DELETE http://localhost:7000/backends/RemoteBackend
+
+Response:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "message": "Backend RemoteBackend closed",
+      "backends": {
+        "LocalCPUBackend": "LocalCPUBackend"
+      }
+    }
+
+``POST /backends``
+^^^^^^^^^^^^^^^^^^
+
+Create new storage backends based on the current ``LMCacheEngineConfig``.
+Existing backends are skipped.
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/backends
+
+Response:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "created": {
+        "RemoteBackend": "RemoteBackend"
+      },
+      "backends": {
+        "LocalCPUBackend": "LocalCPUBackend",
+        "RemoteBackend": "RemoteBackend"
+      }
+    }
+
+Use-Case Examples
+-----------------
+
+Switching from ``LocalDiskBackend`` to ``GdsBackend``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you originally configured a local-disk backend and want to migrate to
+NVIDIA GPUDirect Storage (GDS) at runtime:
+
+.. code-block:: bash
+
+    # 1. Close the old disk backend
+    curl -X DELETE http://localhost:7000/backends/LocalDiskBackend
+
+    # 2. Disable local_disk and set the GDS path
+    curl -X POST http://localhost:7000/conf \
+      -H "Content-Type: application/json" \
+      -d '{
+        "local_disk": false,
+        "gds_path": "/mnt/nvme/lmcache_gds"
+      }'
+
+    # 3. Create the new GDS backend
+    curl -X POST http://localhost:7000/backends
+
+    # 4. Verify the new backend list
+    curl http://localhost:7000/backends
+
+Switching ``RemoteBackend`` connector (FS → Redis)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To change the remote connector type without restarting:
+
+.. code-block:: bash
+
+    # 1. Close the old remote backend
+    curl -X DELETE http://localhost:7000/backends/RemoteBackend
+
+    # 2. Update the remote URL to point to Redis
+    curl -X POST http://localhost:7000/conf \
+      -H "Content-Type: application/json" \
+      -d '{
+        "remote_url": "redis://redis-host:6379"
+      }'
+
+    # 3. Create the new remote backend with Redis connector
+    curl -X POST http://localhost:7000/backends
+
+    # 4. Verify
+    curl http://localhost:7000/backends
+
+Replacing only one backend while keeping others
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If only the ``RemoteBackend`` needs to be updated but the
+``LocalCPUBackend`` should stay untouched:
+
+.. code-block:: bash
+
+    # Close only the remote backend
+    curl -X DELETE http://localhost:7000/backends/RemoteBackend
+
+    # Update config
+    curl -X POST http://localhost:7000/conf \
+      -H "Content-Type: application/json" \
+      -d '{"remote_url": "redis://new-redis:6379"}'
+
+    # Create — LocalCPUBackend is skipped (already present)
+    curl -X POST http://localhost:7000/backends
+
+Notes
+-----
+
+- Closing the ``LocalCPUBackend`` is possible but should be done with
+  caution since many other backends rely on it as an intermediate buffer.
+- The ``POST /backends`` endpoint calls the same ``CreateStorageBackends``
+  factory that is used during engine initialization, so all backend types
+  (local CPU, local disk, GDS, remote, P2P, plugins, etc.) are
+  supported.
+- After creating backends, the ``StorageManager`` automatically refreshes
+  its internal references (``non_allocator_backends``,
+  ``local_cpu_backend``, etc.).
diff --git a/docs/source/internal_api_server/internal_api_server.rst b/docs/source/internal_api_server/internal_api_server.rst
new file mode 100644
index 0000000..4a4a527
--- /dev/null
+++ b/docs/source/internal_api_server/internal_api_server.rst
@@ -0,0 +1,85 @@
+.. _internal_api_server:
+
+Internal API Server
+===================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/http_api`.
+
+
+The ``internal_api_server`` provides HTTP APIs for managing and inspecting
+the LMCache engine at runtime. APIs are organized into three categories:
+
+- **Common APIs** — Available across all components (scheduler, worker, controller).
+- **vLLM / Inference APIs** — Specific to vLLM inference workers.
+- **Controller APIs** — Specific to the LMCache Controller.
+
+.. toctree::
+   :maxdepth: 2
+
+   common_apis
+   vllm_apis
+   controller_apis
+
+
+Configuration
+-------------
+
+The following parameters can be configured in the YAML file:
+
+.. code-block:: yaml
+
+    # Enable/disable the internal API server
+    internal_api_server_enabled: True
+    # Base port for the API server
+    # actual_port = internal_api_server_port_start + index
+    # Scheduler → 6999 + 0 = 6999
+    # Worker 0 → 6999 + 1 = 7000
+    internal_api_server_port_start: 6999
+    # List of scheduler/worker indices: 0 for scheduler, 1 for worker 0, 2 for worker 1, etc.
+    internal_api_server_include_index_list: [0, 1]
+    # Socket path prefix for the API server. If configured, the server will use a Unix socket instead of listening on a port.
+    internal_api_server_socket_path_prefix: "/tmp/lmcache_internal_api_server/socket"
+
+    # Actual socket files will be:
+    #   /tmp/lmcache_internal_api_server/socket_6999 (scheduler)
+    #   /tmp/lmcache_internal_api_server/socket_7000 (worker 0)
+
+
+Port Assignment
+^^^^^^^^^^^^^^^
+
+The port for each component is computed as:
+
+.. code-block:: text
+
+    actual_port = internal_api_server_port_start + port_offset
+
+Where ``port_offset`` is:
+
+- ``0`` for the Scheduler
+- ``1 + worker_id`` for Workers (e.g., Worker 0 → offset 1, Worker 1 → offset 2)
+
+
+API Category & Route Discovery
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The server uses ``APIRegistry`` to automatically discover and register
+API endpoint modules. Any file named ``*_api.py`` under
+``lmcache/v1/internal_api_server/{common,vllm,controller}/`` that
+exports a ``router = APIRouter()`` will be automatically included.
+
+
+Extending the Server
+^^^^^^^^^^^^^^^^^^^^^
+
+To add a new API endpoint:
+
+1. Create a new file in the appropriate category directory
+   (``common/``, ``vllm/``, or ``controller/``).
+2. Name the file with ``_api.py`` suffix (e.g., ``my_feature_api.py``).
+3. Define ``router = APIRouter()`` and add your endpoints.
+
+The endpoint will be automatically discovered and registered on the
+next server startup.
diff --git a/docs/source/internal_api_server/vllm_apis.rst b/docs/source/internal_api_server/vllm_apis.rst
new file mode 100644
index 0000000..23c9165
--- /dev/null
+++ b/docs/source/internal_api_server/vllm_apis.rst
@@ -0,0 +1,1112 @@
+.. _vllm_apis:
+
+vLLM / Inference APIs
+=====================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/http_api`.
+
+
+These APIs are specific to vLLM inference workers and provide cache management,
+configuration, freeze control, chunk statistics, and version information.
+
+.. contents:: Endpoints
+   :local:
+   :depth: 2
+
+
+Version & Info
+--------------
+
+``GET /lmc_version`` — LMCache Version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the LMCache library version string.
+
+- **Method**: ``GET``
+- **Path**: ``/lmc_version``
+- **Parameters**: None
+- **Response**: Plain version string.
+
+.. code-block:: bash
+
+    curl http://localhost:7000/lmc_version
+
+
+``GET /commit_id`` — LMCache Commit ID
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the LMCache git commit ID.
+
+- **Method**: ``GET``
+- **Path**: ``/commit_id``
+- **Parameters**: None
+- **Response**: Plain commit ID string.
+
+.. code-block:: bash
+
+    curl http://localhost:7000/commit_id
+
+
+``GET /version`` — Full Version Info
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get full version info (version + commit ID).
+
+- **Method**: ``GET``
+- **Path**: ``/version``
+- **Parameters**: None
+- **Response**: Combined version string.
+
+.. code-block:: bash
+
+    curl http://localhost:7000/version
+
+
+``GET /inference_info`` — Inference Information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get inference information including vLLM config and LMCache details.
+
+- **Method**: ``GET``
+- **Path**: ``/inference_info``
+- **Parameters**:
+
+  ========== ======= =============================================
+  Name       Type    Description
+  ========== ======= =============================================
+  ``format`` str     (Optional) Reserved for future use
+  ========== ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/inference_info
+
+**Error Response** (HTTP 500):
+
+.. code-block:: json
+
+    {
+      "error": "Failed to get inference info",
+      "message": "..."
+    }
+
+
+``GET /inference_version`` — vLLM Version
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the vLLM version information.
+
+- **Method**: ``GET``
+- **Path**: ``/inference_version``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/inference_version
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "vllm_version": "0.8.0"
+    }
+
+
+Configuration & Metadata
+-------------------------
+
+``GET /conf`` — Get Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get current LMCache engine configuration values.
+
+- **Method**: ``GET``
+- **Path**: ``/conf``
+- **Parameters**:
+
+  ========= ======= =============================================
+  Name      Type    Description
+  ========= ======= =============================================
+  ``names`` str     (Optional) Comma-separated list of config names to filter
+  ========= ======= =============================================
+
+- **Response**: ``application/json`` — JSON object of configuration key-value pairs.
+
+.. code-block:: bash
+
+    # Get all config
+    curl http://localhost:7000/conf
+
+    # Get specific config values
+    curl "http://localhost:7000/conf?names=min_retrieve_tokens,save_decode_cache"
+
+
+``POST /conf`` — Update Configuration (Experimental)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Update one or more configuration values at runtime.
+
+.. warning::
+
+    This feature is currently **experimental**. All configuration keys are
+    mutable at runtime by default unless explicitly marked as
+    ``"mutable": False`` in ``_CONFIG_DEFINITIONS``. The default will be
+    changed to **immutable** once the feature is stabilized.
+
+    Updating a configuration only modifies the value in the
+    ``LMCacheEngineConfig`` object. If a component has already cached the
+    value elsewhere, the change will **not** take effect for that component.
+
+- **Method**: ``POST``
+- **Path**: ``/conf``
+- **Content-Type**: ``application/json``
+- **Request Body**: JSON object with config name-value pairs.
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/conf \
+      -H "Content-Type: application/json" \
+      -d '{"min_retrieve_tokens": 512, "save_decode_cache": true}'
+
+**Example Response** (HTTP 200):
+
+.. code-block:: json
+
+    {
+      "updated": {
+        "min_retrieve_tokens": 512,
+        "save_decode_cache": true
+      }
+    }
+
+**Example Response** (partial failure, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "updated": {"min_retrieve_tokens": 512},
+      "errors": {"unknown_key": "Unknown config"}
+    }
+
+**Error Cases**:
+
+- Unknown config key → ``"Unknown config"``
+- Immutable config key → ``"Config is not mutable at runtime"``
+- Invalid JSON body → HTTP 400
+
+
+``GET /meta`` — Engine Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get metadata of the LMCache engine (e.g., worker_id, model_name, kv_shape).
+
+- **Method**: ``GET``
+- **Path**: ``/meta``
+- **Parameters**:
+
+  ========= ======= =============================================
+  Name      Type    Description
+  ========= ======= =============================================
+  ``names`` str     (Optional) Comma-separated list of attribute names to filter
+  ========= ======= =============================================
+
+- **Response**: ``application/json`` — JSON object of metadata attributes.
+
+.. code-block:: bash
+
+    # Get all metadata
+    curl http://localhost:7000/meta
+
+    # Get specific attributes
+    curl "http://localhost:7000/meta?names=worker_id,model_name"
+
+
+Cache Operations
+-----------------
+
+``DELETE /cache/clear`` — Clear Cache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clear cached KV data from the LMCache engine.
+
+- **Method**: ``DELETE``
+- **Path**: ``/cache/clear``
+- **Parameters**:
+
+  =================== ========== =============================================
+  Name                Type       Description
+  =================== ========== =============================================
+  ``locations``       list[str]  (Optional) Storage backends to clear (e.g. ``LocalCPUBackend``, ``LocalDiskBackend``). If not specified, clears all.
+  =================== ========== =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    # Clear all cache
+    curl -X DELETE http://localhost:7000/cache/clear
+
+    # Clear specific backends
+    curl -X DELETE "http://localhost:7000/cache/clear?locations=LocalCPUBackend&locations=LocalDiskBackend"
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "num_removed": 10
+    }
+
+
+``POST /cache/store`` — Store KV Cache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Store KV cache data into the LMCache engine using mock tokens.
+
+- **Method**: ``POST``
+- **Path**: ``/cache/store``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``tokens_mock``  str     Two comma-separated numbers: ``"start,end"`` (e.g. ``"0,100"`` generates tokens [0..99])
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST "http://localhost:7000/cache/store?tokens_mock=0,100"
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "num_tokens": 100
+    }
+
+**Error Response** (missing params, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "error": "Missing parameters",
+      "message": "Must specify either tokens_input or tokens_mock"
+    }
+
+
+``POST /cache/retrieve`` — Retrieve KV Cache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieve KV cache data from the LMCache engine using mock tokens.
+
+- **Method**: ``POST``
+- **Path**: ``/cache/retrieve``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``tokens_mock``  str     Two comma-separated numbers: ``"start,end"`` (e.g. ``"0,100"``)
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST "http://localhost:7000/cache/retrieve?tokens_mock=0,100"
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "num_tokens": 100,
+      "num_retrieved": 80
+    }
+
+
+``GET /cache/kvcache/check`` — KVCache Checksum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Compute MD5 checksums for kvcaches at specified slot_mapping positions.
+Used for verifying that stored and retrieved kvcaches are identical.
+
+- **Method**: ``GET``
+- **Path**: ``/cache/kvcache/check``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``slot_mapping`` str     Slot indices, comma-separated. Supports ranges: ``"0,1,2,3"`` or ``"1,2,3,[9,12],17,19"``
+  ``chunk_size``   int     Chunk size for computing per-chunk checksums (required)
+  ``layerwise``    bool    If ``true``, output per-layer checksums per chunk (default: ``false``)
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    # Per-chunk checksum (all layers combined)
+    curl "http://localhost:7000/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"
+
+    # Per-layer per-chunk checksum
+    curl "http://localhost:7000/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2&layerwise=true"
+
+**Example Response** (``layerwise=false``):
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "slot_mapping_ranges": [[0, 3]],
+      "chunk_size": 2,
+      "num_chunks": 2,
+      "chunk_checksums": ["abc123...", "def456..."],
+      "layerwise": false
+    }
+
+**Example Response** (``layerwise=true``):
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "slot_mapping_ranges": [[0, 3]],
+      "chunk_size": 2,
+      "num_chunks": 2,
+      "chunk_checksums": {
+        "layer_0": ["abc123...", "def456..."],
+        "layer_1": ["ghi789...", "jkl012..."]
+      },
+      "layerwise": true
+    }
+
+
+``POST /cache/kvcache/record_slot`` — Toggle Slot Logging
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable or disable KVCache slot_mapping logging during store/retrieve operations.
+
+- **Method**: ``POST``
+- **Path**: ``/cache/kvcache/record_slot``
+- **Parameters**:
+
+  =========== ======= =============================================
+  Name        Type    Description
+  =========== ======= =============================================
+  ``enabled`` str     ``"true"`` to enable, ``"false"`` to disable. Omit to query current status.
+  =========== ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    # Enable logging
+    curl -X POST "http://localhost:7000/cache/kvcache/record_slot?enabled=true"
+
+    # Disable logging
+    curl -X POST "http://localhost:7000/cache/kvcache/record_slot?enabled=false"
+
+    # Check current status
+    curl -X POST http://localhost:7000/cache/kvcache/record_slot
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "kvcache_check_log_enabled": true
+    }
+
+
+``GET /cache/kvcache/info`` — KVCache Information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get information about the current kvcaches structure including layer names,
+shapes, and device info.
+
+- **Method**: ``GET``
+- **Path**: ``/cache/kvcache/info``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/cache/kvcache/info
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "num_layers": 32,
+      "layers": {
+        "layer_0": {
+          "shape": [2, 128, 16, 64, 128],
+          "dtype": "torch.bfloat16",
+          "device": "cuda:0"
+        }
+      }
+    }
+
+
+``POST /cache/load-fs-chunks`` — Load FS Chunks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Load chunk files from FSConnector storage into LocalCPUBackend's hot cache.
+
+- **Method**: ``POST``
+- **Path**: ``/cache/load-fs-chunks``
+- **Content-Type**: ``application/json``
+- **Request Body**:
+
+  ==================== ======= =============================================
+  Field                Type    Description
+  ==================== ======= =============================================
+  ``config_path``      str     Path to LMCache engine configuration YAML file (required)
+  ``max_chunks``       int     (Optional) Maximum number of chunks to load
+  ``max_failed_keys``  int     Maximum failed keys to report (default: 10)
+  ==================== ======= =============================================
+
+- **Response**: ``application/json``
+- **Tags**: ``cache-management``
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/cache/load-fs-chunks \
+      -H "Content-Type: application/json" \
+      -d '{"config_path": "/path/to/lmcache.yaml", "max_chunks": 100}'
+
+**Example Response** (HTTP 200):
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "loaded_chunks": 95,
+      "total_files": 100,
+      "failed_keys": ["key1", "key2"],
+      "config_path": "/path/to/lmcache.yaml"
+    }
+
+**Error Response** (invalid config, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "error": "Failed to load chunks from FSConnector",
+      "message": "Configuration file not found",
+      "config_path": "/path/to/lmcache.yaml"
+    }
+
+
+Freeze Mode
+------------
+
+``PUT /freeze/enable`` — Enable Freeze Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable freeze mode for the LMCache engine. When enabled:
+
+- All store operations will be skipped (no new data stored)
+- Only ``local_cpu`` backend will be used for retrieval
+- No admit/evict messages will be generated
+
+This protects the local_cpu hot cache from changes.
+
+- **Method**: ``PUT``
+- **Path**: ``/freeze/enable``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X PUT http://localhost:7000/freeze/enable
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "freeze": true,
+      "message": "Freeze mode enabled successfully"
+    }
+
+
+``PUT /freeze/disable`` — Disable Freeze Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Disable freeze mode. Store operations will proceed normally.
+
+- **Method**: ``PUT``
+- **Path**: ``/freeze/disable``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X PUT http://localhost:7000/freeze/disable
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "freeze": false,
+      "message": "Freeze mode disabled successfully"
+    }
+
+
+``GET /freeze/status`` — Freeze Status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the current freeze mode status.
+
+- **Method**: ``GET``
+- **Path**: ``/freeze/status``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/freeze/status
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "freeze": true,
+      "message": "Freeze mode is enabled"
+    }
+
+
+Hot Cache
+----------
+
+These endpoints control the hot cache feature of LocalCPUBackend.
+When hot cache is enabled, frequently accessed KV cache data will be kept
+in CPU memory for faster retrieval.
+
+``PUT /hot_cache/enable`` — Enable Hot Cache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable hot cache for the LocalCPUBackend.
+
+- **Method**: ``PUT``
+- **Path**: ``/hot_cache/enable``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X PUT http://localhost:7000/hot_cache/enable
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "hot_cache": true,
+      "message": "Hot cache enabled successfully"
+    }
+
+
+``PUT /hot_cache/disable`` — Disable Hot Cache
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Disable hot cache for the LocalCPUBackend. Existing hot cache entries
+will be cleared and no new data will be written.
+
+- **Method**: ``PUT``
+- **Path**: ``/hot_cache/disable``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X PUT http://localhost:7000/hot_cache/disable
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "hot_cache": false,
+      "message": "Hot cache disabled successfully"
+    }
+
+
+``GET /hot_cache/status`` — Hot Cache Status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get the current hot cache status of LocalCPUBackend.
+
+- **Method**: ``GET``
+- **Path**: ``/hot_cache/status``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/hot_cache/status
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "hot_cache": true,
+      "message": "Hot cache is enabled"
+    }
+
+
+Chunk Statistics
+-----------------
+
+These endpoints manage chunk-level statistics collection via
+``ChunkStatisticsLookupClient``. They are only available when the
+lookup client supports statistics.
+
+
+Lookup Client/Server Management
+-----------------------------------
+
+These endpoints allow runtime management of the lookup client and server.
+They are useful for dynamically reconfiguring the lookup mechanism without
+restarting the service.
+
+.. important::
+
+    **Configuration Update Required First**
+
+    Before calling ``/lookup/create`` or ``/lookup/recreate``, you **MUST**
+    update the configuration via the ``/conf`` API first. The new lookup
+    client/server will be created using ``LookupClientFactory``.
+
+    For some configurations (e.g., switching ``enable_scheduler_bypass_lookup``),
+    you only need to update the **scheduler's** configuration and recreate its
+    lookup client. The workers don't need changes in this case.
+
+
+``GET /lookup/info`` — Lookup Client/Server Information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get information about the current lookup client and server status.
+Shows wrapper chain if applicable (e.g., ``HitLimitLookupClient(LMCacheLookupClient)``).
+
+- **Method**: ``GET``
+- **Path**: ``/lookup/info``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:6999/lookup/info
+
+**Example Response** (scheduler):
+
+.. code-block:: json
+
+    {
+      "client": "HitLimitLookupClient(LMCacheBypassLookupClient)",
+      "server": "None",
+      "role": "scheduler"
+    }
+
+**Example Response** (worker):
+
+.. code-block:: json
+
+    {
+      "client": "None",
+      "server": "LMCacheLookupServer",
+      "role": "worker"
+    }
+
+
+``POST /lookup/close`` — Close Lookup Client/Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Close the current lookup client (scheduler) or server (worker).
+
+- **Method**: ``POST``
+- **Path**: ``/lookup/close``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:6999/lookup/close
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "old": "HitLimitLookupClient(LMCacheBypassLookupClient)",
+      "role": "scheduler"
+    }
+
+
+``POST /lookup/create`` — Create Lookup Client/Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create a new lookup client (scheduler) or server (worker) using current config.
+
+- **Method**: ``POST``
+- **Path**: ``/lookup/create``
+- **Parameters**:
+
+  =========== ======= =============================================
+  Name        Type    Description
+  =========== ======= =============================================
+  ``dryrun``  bool    If ``true``, only show what would be created
+  =========== ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    # Dryrun - preview what would be created
+    curl -X POST "http://localhost:6999/lookup/create?dryrun=true"
+
+    # Actually create
+    curl -X POST http://localhost:6999/lookup/create
+
+**Example Response** (dryrun):
+
+.. code-block:: json
+
+    {
+      "new": "LMCacheLookupClient",
+      "dryrun": true,
+      "role": "scheduler"
+    }
+
+**Example Response** (actual create):
+
+.. code-block:: json
+
+    {
+      "new": "LMCacheLookupClient",
+      "role": "scheduler"
+    }
+
+
+``POST /lookup/recreate`` — Recreate Lookup Client/Server
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Recreate the lookup client or server (equivalent to close + create).
+The endpoint automatically determines which component based on role:
+
+- **scheduler** role: recreates lookup client
+- **worker** role: recreates lookup server
+
+- **Method**: ``POST``
+- **Path**: ``/lookup/recreate``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+**Usage Flow**:
+
+.. code-block:: bash
+
+    # Step 1: Update worker configuration (if needed)
+    curl -X POST "http://localhost:7000/conf" \
+      -H "Content-Type: application/json" \
+      -d '{"enable_async_loading": true}'
+
+    # Step 2: Recreate lookup server on worker
+    curl -X POST "http://localhost:7000/lookup/recreate"
+
+    # Step 3: Update scheduler configuration
+    curl -X POST "http://localhost:6999/conf" \
+      -H "Content-Type: application/json" \
+      -d '{"enable_scheduler_bypass_lookup": true}'
+
+    # Step 4: Recreate lookup client on scheduler
+    curl -X POST "http://localhost:6999/lookup/recreate"
+
+**Example Response** (scheduler):
+
+.. code-block:: json
+
+    {
+      "old": "HitLimitLookupClient(LMCacheBypassLookupClient)",
+      "new": "LMCacheLookupClient",
+      "role": "scheduler"
+    }
+
+**Example Response** (worker):
+
+.. code-block:: json
+
+    {
+      "old": "LMCacheLookupServer",
+      "new": "LMCacheAsyncLookupServer",
+      "role": "worker"
+    }
+
+.. note::
+
+    **Client-only Changes**
+
+    For some configuration changes (e.g., switching ``enable_scheduler_bypass_lookup``),
+    you only need to update the scheduler's configuration and recreate its lookup
+    client. Worker-side lookup servers don't need to be recreated in this case.
+
+
+``POST /chunk_statistics/start`` — Start Statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Start collecting chunk statistics.
+
+- **Method**: ``POST``
+- **Path**: ``/chunk_statistics/start``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/chunk_statistics/start
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "message": "Started"
+    }
+
+**Error Response** (not supported, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "error": "Not available",
+      "message": "Client does not support statistics."
+    }
+
+
+``POST /chunk_statistics/stop`` — Stop Statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Stop collecting chunk statistics.
+
+- **Method**: ``POST``
+- **Path**: ``/chunk_statistics/stop``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/chunk_statistics/stop
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "message": "Stopped"
+    }
+
+
+``POST /chunk_statistics/reset`` — Reset Statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Reset all collected chunk statistics.
+
+- **Method**: ``POST``
+- **Path**: ``/chunk_statistics/reset``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:7000/chunk_statistics/reset
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "message": "Reset"
+    }
+
+
+``GET /chunk_statistics/status`` — Statistics Status
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Get current chunk statistics and auto-exit configuration.
+
+- **Method**: ``GET``
+- **Path**: ``/chunk_statistics/status``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/chunk_statistics/status
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "is_collecting": true,
+      "total_chunks": 1000,
+      "unique_chunks": 500,
+      "timestamp": 1706745600.0,
+      "auto_exit_enabled": true,
+      "auto_exit_timeout_hours": 24.0,
+      "auto_exit_target_unique_chunks": 1000
+    }
+
+
+.. _bypass_mode:
+
+Bypass Mode
+------------
+
+Bypass mode allows dynamically skipping specific storage backends at runtime.
+Bypassed backends are excluded from ``contains``/``put``/``get`` operations.
+This is useful for fault injection testing, isolating a problematic backend,
+or debugging without restarting the engine.
+
+
+``GET /bypass/list`` — List Bypassed Backends
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+List all currently bypassed backends and all available backend names.
+
+- **Method**: ``GET``
+- **Path**: ``/bypass/list``
+- **Parameters**: None
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl http://localhost:7000/bypass/list
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "bypassed_backends": ["RemoteBackend"],
+      "all_backends": ["LocalCPUBackend", "RemoteBackend"]
+    }
+
+
+``PUT /bypass/add`` — Add a Backend to Bypass List
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Add a backend to the bypass list. The bypassed backend will be excluded
+from ``contains``/``put``/``get`` operations.
+
+- **Method**: ``PUT``
+- **Path**: ``/bypass/add``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``backend_name`` str     Name of the backend to bypass (required)
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X PUT "http://localhost:7000/bypass/add?backend_name=RemoteBackend"
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "backend_name": "RemoteBackend",
+      "bypassed": true,
+      "was_already_bypassed": false,
+      "bypassed_backends": ["RemoteBackend"]
+    }
+
+**Error Response** (unknown backend, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "error": "Unknown backend",
+      "message": "Backend 'FooBackend' not found. Available: ['LocalCPUBackend', 'RemoteBackend']"
+    }
+
+
+``PUT /bypass/remove`` — Remove a Backend from Bypass List
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Remove a backend from the bypass list, restoring it to normal operation.
+
+- **Method**: ``PUT``
+- **Path**: ``/bypass/remove``
+- **Parameters**:
+
+  ================ ======= =============================================
+  Name             Type    Description
+  ================ ======= =============================================
+  ``backend_name`` str     Name of the backend to restore (required)
+  ================ ======= =============================================
+
+- **Response**: ``application/json``
+
+.. code-block:: bash
+
+    curl -X PUT "http://localhost:7000/bypass/remove?backend_name=RemoteBackend"
+
+**Example Response**:
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "backend_name": "RemoteBackend",
+      "bypassed": false,
+      "was_bypassed": true,
+      "bypassed_backends": []
+    }
+
+**Error Response** (unknown backend, HTTP 400):
+
+.. code-block:: json
+
+    {
+      "error": "Unknown backend",
+      "message": "Backend 'FooBackend' not found. Available: ['LocalCPUBackend', 'RemoteBackend']"
+    }
diff --git a/docs/source/kv_cache/async_loading.rst b/docs/source/kv_cache/async_loading.rst
new file mode 100644
index 0000000..57753d1
--- /dev/null
+++ b/docs/source/kv_cache/async_loading.rst
@@ -0,0 +1,132 @@
+Async Loading
+=============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+Overview
+--------
+
+This document explains the principle, benefits, differences from vLLM PR `19330 <https://github.com/vllm-project/vllm/pull/19330>`_, and limitations of the LMCache ``async_loading`` feature.
+It focuses on LMCache v1 integration with vLLM and the internal storage pipeline.
+
+Key change of components in this feature include:
+
+- LMCache async lookup client/server (ZMQ-based)
+- Storage manager orchestrating backends and concurrency
+- Cache engine async API entrypoints
+- vLLM adapter integration points
+
+Principle and Theory
+--------------------
+
+At a high level, ``async_loading`` decouples scheduler-side lookup from worker-side prefetch/retrieval, allowing overlap between I/O and computation while preserving prefix-based correctness.
+
+- The scheduler sends lookup requests with token chunk hashes and offsets.
+- Worker-side servers perform tiered ``batched_async_contains`` over available backends and eagerly launch non-blocking batched get operations for hit prefixes.
+- Completion is tracked via an ``EventManager`` to safely deliver loaded memory objects back to the requesting path.
+- A weighted semaphore with an ``AsyncSerializer`` prevents allocator deadlocks by shaping concurrency according to chunk budget.
+
+The following Mermaid sequence diagram illustrates the end-to-end flow:
+
+.. mermaid::
+
+   sequenceDiagram
+     autonumber
+     participant S as Scheduler (vLLM)
+     participant LC as LMCacheAsyncLookupClient
+     participant WS as LMCacheAsyncLookupServer (Worker)
+     participant SM as StorageManager
+     participant BE as Backends (LocalCPU/LocalDisk/FSConnector)
+     participant EM as EventManager
+
+     S->>LC: lookup(token_ids, lookup_id, request_configs)
+     note right of LC: Hashes + offsets via TokenDatabase
+     LC->>WS: ZMQ PUSH multipart [lookup_id, hashes, offsets, configs]
+     WS->>SM: async_lookup_and_prefetch(lookup_id, keys, cum_chunk_lengths)
+     SM->>BE: batched_async_contains(lookup_id, keys, pin=True)
+     alt prefix hit across tiers
+       BE-->>SM: num_hit_chunks (per tier)
+       SM->>BE: batched_get_non_blocking(lookup_id, hit_prefix)
+       BE-->>SM: Future[List[MemoryObj]]
+       SM->>EM: add_event(EventType.LOADING, lookup_id, gather_all)
+       SM-->>WS: send_response_to_scheduler(lookup_id, retrieved_length)
+       WS-->>LC: ZMQ PUSH [lookup_id, num_hit_tokens]
+     else cache miss
+       SM-->>WS: send_response_to_scheduler(lookup_id, 0)
+       WS-->>LC: ZMQ PUSH [lookup_id, 0]
+     end
+
+
+Architecture (Worker Side)
+--------------------------
+
+.. mermaid::
+   :align: center
+
+   flowchart LR
+       subgraph Worker
+         direction TB
+         A["LMCacheAsyncLookupServer<br/>ZMQ PULL/PUSH"]
+         B["StorageManager<br/>Async loop (thread)"]
+         C["AsyncSerializer<br/>WeightedSemaphore"]
+         D["EventManager<br/>EventType.LOADING"]
+       end
+
+       subgraph Backends
+         E["LocalCPUBackend<br/>contains/get"]
+         F["LocalDiskBackend<br/>async contains/get"]
+         G["FSConnector<br/>remote FS"]
+       end
+
+       A --> B
+       B --> C
+       B --> D
+       B -.contains/get.-> E
+       B -.contains/get.-> F
+       B -.contains/get.-> G
+
+       style E fill:#dff,stroke:#333,stroke-width:1px
+       style F fill:#ffd,stroke:#333,stroke-width:1px
+       style G fill:#dfd,stroke:#333,stroke-width:1px
+
+
+Benefits
+--------
+
+- Performance overlap
+    - **I/O–Compute Overlap**: Decoupling lookup/prefetch from loading enables fetching KV chunks while vLLM continues scheduling/computation.
+- Robustness and error handling
+    - **Event-driven Synchronization**: ``EventManager`` ensures safe hand-off of futures and avoids race conditions between threads and the async loop.
+    - **Backpressure & Deadlock Avoidance**: ``AsyncSerializer`` with a weighted semaphore caps concurrent chunk retrievals based on allocator budget, preventing starvation or allocator lockups.
+    - **Graceful Miss Path**: Immediate response with ``None`` hit tokens when nothing is retrievable; worker returns quickly without stalling the scheduler.
+
+Comparison with vLLM Load Failure Recovery feature
+---------------------------------------------------
+
+The `VLLM_PR_19330 <https://github.com/vllm-project/vllm/pull/19330>`_ introduces a fault recovery mechanism for vLLM's KV connector infrastructure that enables graceful handling of KV cache load failures by automatically detecting failed block loads and rescheduling only affected requests for recomputation from a valid prefix.
+By contrast, LMCache’s ``async_loading`` is an externalized caching layer with its own client/server, storage backends, and concurrency control.
+
+Limitations
+-----------
+
+- Only works with vllm merged `VLLM_PR_23620 <https://github.com/vllm-project/vllm/pull/23620>`_
+- Backend support constraint: This feature currently requires backends that implement ``batched_async_contains``; limited to a few backends, e.g.:
+    - ``LocalCpuBackend``
+    - ``LocalDiskBackend``
+    - ``S3Connector``
+    - ``FSConnector``
+    - ``RedisConnector/RedisClusterConnector``
+
+Future Work
+-----------
+
+- Introduce a default ``batched_async_contains`` implementation, so all backends can support ``async_loading``.
+- Add metrics and observability to track the number of asynchronous lookup requests and the number of occupied ``MemoryObj`` instances.
+- Improve the lookup framework by passing vLLM prefix cache hit tokens so that async lookup can skip loading parts already hit in vLLM.
diff --git a/docs/source/kv_cache/caching_policies.rst b/docs/source/kv_cache/caching_policies.rst
new file mode 100644
index 0000000..7bd0034
--- /dev/null
+++ b/docs/source/kv_cache/caching_policies.rst
@@ -0,0 +1,13 @@
+Using Different Caching Policies
+===================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+LMCache supports multiple caching policies.
+
+For example, to use LRU, you can set the environment variable ``LMCACHE_CACHE_POLICY=LRU`` or set it in the configuration file with ``cache_policy="LRU"``.
+
+Currently, LMCache supports "LRU" (Least Recently Used), "MRU" (Most Recently Used), "LFU" (Least Frequently Used) and "FIFO" (First-In-First-Out) caching policies.
diff --git a/docs/source/kv_cache/multiprocess_mode.rst b/docs/source/kv_cache/multiprocess_mode.rst
new file mode 100644
index 0000000..28b5488
--- /dev/null
+++ b/docs/source/kv_cache/multiprocess_mode.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+Multiprocess Mode (Redirect)
+=============================
+
+.. note::
+   This page has moved.  The multiprocess mode documentation is now at
+   :doc:`/mp/index`.
+
+Please see the new :doc:`/mp/index` section for complete documentation
+including quick start, configuration reference, L2 storage, deployment,
+observability, and architecture guides.
\ No newline at end of file
diff --git a/docs/source/kv_cache/p2p_sharing.rst b/docs/source/kv_cache/p2p_sharing.rst
new file mode 100644
index 0000000..9682e18
--- /dev/null
+++ b/docs/source/kv_cache/p2p_sharing.rst
@@ -0,0 +1,237 @@
+.. _p2p_sharing:
+
+P2P KV Cache Sharing
+====================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/p2p`.
+
+
+P2P (Peer-to-Peer) KV cache sharing enables direct cache transfer between multiple serving engine instances without requiring a centralized cache server. This approach provides high-performance cache sharing with reduced latency and improved scalability, especially beneficial in distributed inference scenarios.
+
+LMCache supports P2P sharing through a controller-based architecture using NIXL (NVIDIA Inference Xfer Library) for optimized data transfer between instances.
+
+Prerequisites
+-------------
+
+- **Multi-GPU Setup**: Your server should have at least 2 GPUs
+- **NIC**: RDMA is recommended for more performance.
+- **NIXL**: Install from `NIXL <https://github.com/ai-dynamo/nixl>`_
+- **vLLM**: v1 version is required, refer to :ref:`installation_guide` for details.
+- **LMCache**: Install from :ref:`installation_guide`
+
+Configuration
+-------------
+
+Create two configuration files for the P2P sharing setup.
+ 
+
+**Instance 1 Configuration (example1.yaml)**:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 100
+    enable_async_loading: True
+
+    # P2P configurations
+    enable_p2p: True
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+    p2p_lookup_ports: 8201
+    transfer_channel: "nixl"
+
+    # Controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_instance_1"
+    controller_pull_url: "localhost:8300"
+    controller_reply_url: "localhost:8400"
+    lmcache_worker_ports: 8500
+
+    extra_config:
+      lookup_backoff_time: 0.001
+
+**Instance 2 Configuration (example2.yaml)**:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 100
+    enable_async_loading: True
+
+    # P2P configurations
+    enable_p2p: True
+    p2p_host: "localhost"
+    p2p_init_ports: 8202
+    p2p_lookup_ports: 8203
+    transfer_channel: "nixl"
+
+    # Controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_instance_2"
+    controller_pull_url: "localhost:8300"
+    controller_reply_url: "localhost:8400"
+    lmcache_worker_ports: 8501
+
+    extra_config:
+      lookup_backoff_time: 0.001
+
+Setup and Usage
+---------------
+
+**Step 1: Start the LMCache Controller**
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-ports '{"pull": 8300, "reply": 8400, "heartbeat": 8082}'
+
+Make sure that the 8300 and 8400 ports are set up in **controller_pull_url** and **controller_reply_url** in the configuration files.
+Port 9000 is the controller main port, which is arbitrary and can be changed.
+
+After starting the controller, access the WebUI at:
+
+http://localhost:9000/
+
+**Step 2: Start vLLM Engines with LMCache Workers**
+
+If the NIC supports RDMA:
+
+.. code-block:: bash
+
+    export UCX_TLS=rc
+
+If the NIC does not support RDMA:
+
+.. code-block:: bash
+
+    export UCX_TLS=tcp
+
+Start vLLM engine 1 at port 8010:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123  CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=/path/to/example1.yaml \
+    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+        --gpu-memory-utilization 0.8 \
+        --port 8010 \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Start vLLM engine 2 at port 8011:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123  CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=/path/to/example2.yaml \
+    vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+        --gpu-memory-utilization 0.8 \
+        --port 8011 \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+**Step 3: Test P2P Cache Sharing**
+
+Send a request to vLLM engine 1 to populate the cache:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8010/v1/completions \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
+            \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+            \"max_tokens\": 10
+        }"
+
+Send the same request to vLLM engine 2 to demonstrate cache retrieval from **engine 1**:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8011/v1/completions \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
+            \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+            \"max_tokens\": 10
+        }"
+
+Expected Output
+---------------
+
+When the second request successfully retrieves cache from the first instance, you should see logs similar to:
+
+.. code-block:: bash
+
+    (EngineCore_DP0 pid=2577584)[2025-09-21 00:00:11,706] LMCache INFO:[0m Established connection to peer_init_url localhost:8200. The peer_lookup_url: localhost:8201 (p2p_backend.py:278:lmcache.v1.storage_backend.p2p_backend)
+    (EngineCore_DP0 pid=2577584)[2025-09-21 00:00:11,792] LMCache INFO: Retrieved 1002 out of total 1002 out of total 1002 tokens. size: 0.1223 gb, cost 60.3595 ms, throughput: 2.0264 GB/s; (cache_engine.py:496:lmcache.v1.cache_engine)
+
+These logs indicate successful P2P connection establishment and high-throughput cache retrieval.
+
+
+
+**Step 4: Benchmarking P2P Cache Sharing**
+
+Send a request workload to instance 1 to populate the cache:
+
+.. code-block:: bash
+
+    python benchmarks/long_doc_qa/long_doc_qa.py \
+    --model meta-llama/Meta-Llama-3.1-8B-Instruct \
+    --num-documents 50 \
+    --document-length 10000 \
+    --output-len 100 \
+    --repeat-count 1 \
+    --repeat-mode tile \
+    --port 8010 \
+    --max-inflight-requests 4
+
+Send the same request workload to instance 2 to demonstrate cache retrieval from **instance 1**:
+
+.. code-block:: bash
+
+    python benchmarks/long_doc_qa/long_doc_qa.py \
+    --model meta-llama/Meta-Llama-3.1-8B-Instruct \
+    --num-documents 50 \
+    --document-length 10000 \
+    --output-len 100 \
+    --repeat-count 1 \
+    --repeat-mode tile \
+    --port 8011 \
+    --max-inflight-requests 4
+
+
+Benchmark Results
+-----------------
+
+First instance metrics:
+
+.. code-block:: text
+ 
+    Warmup round mean TTFT: 2.286s
+    Warmup round time: 37.957s
+    Warmup round prompt count: 50
+    Warmup round successful prompt count: 50
+    
+    === BENCHMARK RESULTS ===
+    Query round mean TTFT: 2.028s
+    Query round time: 38.323s
+    Query round prompt count: 50
+    Query round successful prompt count: 50
+
+Second instance metrics:
+
+.. code-block:: text
+ 
+    Warmup round mean TTFT: 1.036s
+    Warmup round time: 13.814s
+    Warmup round prompt count: 50
+    Warmup round successful prompt count: 50
+    
+    === BENCHMARK RESULTS ===
+    Query round mean TTFT: 0.490s
+    Query round time: 7.964s
+    Query round prompt count: 50
+    Query round successful prompt count: 50
+
+In this example, the warm-up round metric in long_doc_qa is used because no existing KV cache is reused within an instance to benefit solely from P2P sharing. With LMCache P2P sharing enabled, the time to first token (TTFT) is reduced by 54.7%, from 2.286 s to 1.036 s, with a 63.6% reduction in total inference time (37.957 s → 13.814 s).
+
diff --git a/docs/source/kv_cache/storage_backends/3fs.rst b/docs/source/kv_cache/storage_backends/3fs.rst
new file mode 100644
index 0000000..246ab0d
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/3fs.rst
@@ -0,0 +1,174 @@
+3FS
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _3FS-overview:
+
+Overview
+--------
+
+3FS (Fire-Flyer File System) is an AI native distributed file-system which provides high performance and 
+low latency. It is a supported option for KV Cache offloading in LMCache. Even though the FSConnector 
+backend can work with 3FS storage cluster, but it access data in 3FS storage cluster by FUSE interfaces.
+It can't leverage 3FS high performance. This particular backend uses 3FS native USRBIO(User Space Ring 
+Based IO) interfaces to access 3FS storage cluster which get high performance.
+
+Configure LMCache 3FS Offloading
+-----------------------------------------
+
+Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    local_cpu: False
+    
+    # Plugin name mode, obtain base_path in extra_config session
+    remote_storage_plugins: ["hf3fs.primary"]
+    
+    # URL mode, obtain base_path from the URL
+    #remote_url: "hf3fs:///3fs/stage/hello, /3fs/stage/world"
+
+    extra_config:
+
+        # base_path, for a plugin instance
+        remote_storage_plugin.hf3fs.primary.base_path: "/3fs/stage/dir1,/3fs/stage/dir2"
+        
+        # base_path, for all plugin instances 
+        #hf3fs_base_path: "/3fs/stage/dir1,/3fs/stage/dir2"
+
+        # Mount point of 3FS
+        hf3fs_mount_point: "/3fs/stage"
+
+        # Shared memory size for Iov in hf3fs client, 
+        # range in [104857600(100MB), 2147483648(2GB)], default:209715200
+        hf3fs_iov_size: 209715200 #200MB
+
+        # Max num of concurrent requests that can be submitted in Ior
+        # range in [128,1024], default: 256
+        hf3fs_ior_entries: 256
+
+        # Control with I/O depth. 0, no control
+        # >0, only when io_depth requests are in queue, and issue them in one batch
+        # <0, wait for at most -io_depth requests are in queue and issue them in one batch
+        # range in [-128, 128], default: 0
+        hf3fs_io_depth: 0
+
+        # NUMA ID for Ior shared memory, -1 for current process NUMA ID.
+        hf3fs_numa_id: -1
+
+        # Number of io thread
+        # range in [2,16], default: 4
+        hf3fs_io_thread_num: 4
+
+There are 2 methods to config hf3fs remote backend:
+ 1. Plugin name mode, uses the parameter remote_storage_plugins(Recommend)
+ 2. URL mode, uses the parameter remote_url(Deprecated, will be removed in a future)
+
+For URL mode, the base_path is contained in the url. For plugin name mode, there are 2 methods to set base_path:
+ 1. remote_storage_plugin.{plugin name}.base_path, it sets the base_path for a plugin instance.
+     e.g.:remote_storage_plugin.hf3fs.primary.base_path
+ 2. hf3fs_base_path, it set the base_path for all plugin instances
+
+Installation
+-------------
+
+.. _3FS-prerequisites:
+
+**Prerequisites:**
+
+- A Machine with at least one GPU. You can adjust the max model length of your vllm instance depending on your GPU memory.
+
+- vllm and lmcache installed
+
+**Step 1. Install 3FS hf3fs_py_usrbio package**
+
+    The inference server need install 3FS hf3fs_py_usrbio package, recommend to build the package from source:
+
+    .. code-block:: bash
+
+        git clone https://github.com/deepseek-ai/3fs
+        cd 3fs
+        git submodule update --init --recursive
+        ./patches/apply.sh
+        Install dependencies
+        pip install -e .
+
+    `3FS Build <https://github.com/deepseek-ai/3FS/blob/main/README.md#build-3fs>`_
+
+
+**Step 2. Setup 3FS storage cluster**
+
+    `3FS Setup <https://github.com/deepseek-ai/3FS/blob/main/deploy/README.md>`_
+
+
+**Step 3. Deploy 3FS FUSE client in inference server**
+
+    The inference server must deploy 3FS FUSE client(a fuse daemon process provided by 3FS), 
+    otherwise, it can't access 3FS storage cluster
+
+    `Setup 3FS FUSE Client <https://github.com/deepseek-ai/3FS/blob/main/deploy/README.md#step-8-fuse-client>`_
+
+
+**Step 4. Start a vLLM server with 3FS offloading enabled**
+
+    Create a lmcache configuration file called: ``3fs-offload.yaml``
+
+    .. code-block:: yaml
+
+        # 256 Tokens per KV Chunk
+        chunk_size: 256
+        local_cpu: False
+        # support multiple paths
+        remote_storage_plugins: ["hf3fs.primary"]
+
+        extra_config:
+            # base_path
+            remote_storage_plugin.hf3fs.primary.base_path: "/3fs/stage/dir1,/3fs/stage/dir2"
+
+            # Mount point of 3FS
+            hf3fs_mount_point: "/3fs/stage"
+
+            # Shared memory size for Iov in hf3fs client, 
+            # range in [104857600(100MB), 2147483648(2GB)], default:209715200 (200MB)
+            hf3fs_iov_size: 209715200 
+
+            # Max num of concurrent requests that can be submitted in Ior
+            # range in [128,1024], default: 256
+            hf3fs_ior_entries: 256
+
+            # Control with I/O depth. 0, no control
+            # >0, only when io_depth requests are in queue, and issue them in one batch
+            # <0, wait for at most -io_depth requests are in queue and issue them in one batch
+            # range in [-128, 128], default: 0
+            hf3fs_io_depth: 0
+
+            # NUMA ID for Ior shared memory, -1 for current process NUMA ID.
+            hf3fs_numa_id: -1
+
+            # Number of io thread
+            # range in [2,16], default: 4
+            hf3fs_io_thread_num: 4
+
+    Start vllm:
+
+    .. code-block:: bash
+
+        export VLLM_USE_V1=0
+        export LMCACHE_USE_EXPERIMENTAL=True
+        export LMCACHE_LOG_LEVEL=INFO
+        export VLLM_WORKER_MULTIPROC_METHOD=spawn
+        export VLLM_ENABLE_V1_MULTIPROCESSING=1
+        LMCACHE_CONFIG_FILE="3fs-offload.yaml" \
+        vllm serve \
+            meta-llama/Llama-3.1-8B-Instruct \
+            --max-model-len 65536 \
+            --kv-transfer-config \
+            '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
diff --git a/docs/source/kv_cache/storage_backends/azure.rst b/docs/source/kv_cache/storage_backends/azure.rst
new file mode 100644
index 0000000..86100bf
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/azure.rst
@@ -0,0 +1,78 @@
+Azure Blob Storage Backend
+==========================
+
+LMCache can offload KV cache to Azure Blob Storage via an async-native
+connector (parity with the S3 backend, no NIXL dependency). The connector is
+selected by an ``azure://`` ``remote_url``.
+
+Optional Packages
+-----------------
+
+The Azure SDKs are optional dependencies and are imported lazily, so install
+them only when you use this backend:
+
+.. code-block:: bash
+
+   pip install azure-storage-blob
+   # Only needed for the DefaultAzureCredential fallback (see Authentication):
+   pip install azure-identity
+
+URL Format
+----------
+
+.. code-block:: text
+
+   azure://<container_name>
+
+The container name is the only value carried in the URL. The storage account
+and credentials are supplied via ``extra_config``.
+
+Example Configuration
+---------------------
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: False
+   save_unfull_chunk: False
+   remote_url: "azure://my-container"
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+   extra_config:
+     azure_account_url: "https://myaccount.blob.core.windows.net"
+     azure_account_key: "your-account-key"
+
+Configuration Parameters (in extra_config)
+-----------------------------------------
+
+* **azure_account_url**: Storage account URL, e.g.
+  ``https://<account>.blob.core.windows.net``. Required unless
+  ``azure_connection_string`` is provided.
+* **azure_connection_string**: Full Azure Storage connection string. When set,
+  it is used on its own and the other fields are ignored.
+* **azure_account_key**: Storage account shared key (paired with
+  ``azure_account_url``).
+* **azure_sas_token**: Shared Access Signature token (paired with
+  ``azure_account_url``).
+
+Authentication
+--------------
+
+Exactly one credential path is resolved, most-explicit-first:
+
+1. **azure_connection_string** — if set, it wins.
+2. **azure_account_url + azure_account_key** — shared-key auth.
+3. **azure_account_url + azure_sas_token** — SAS-token auth.
+4. **azure_account_url** only — falls back to
+   ``DefaultAzureCredential`` (managed identity, environment variables, Azure
+   CLI login, etc.), which requires the ``azure-identity`` package.
+
+``azure_account_url`` is required for every path except the connection-string
+case.
+
+Notes
+-----
+
+* Only full chunks are stored; set ``save_unfull_chunk: False``.
+* Keys are flattened into one blob per chunk (same flat layout as the S3
+  backend).
diff --git a/docs/source/kv_cache/storage_backends/bigtable.rst b/docs/source/kv_cache/storage_backends/bigtable.rst
new file mode 100644
index 0000000..1f1ce43
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/bigtable.rst
@@ -0,0 +1,152 @@
+Google Cloud Bigtable
+=====================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _bigtable-overview:
+
+Overview
+--------
+
+Google Cloud Bigtable is a petabyte-scale, fully managed NoSQL database. Integrating Cloud Bigtable as a built-in remote storage connector inside LMCache bridges volatile high-cost in-memory tiers (Redis) and low-cost, high-latency archival object stores (S3). 
+
+For more information, see the `Cloud Bigtable Overview <https://cloud.google.com/bigtable/docs/overview>`_ and `Cloud Bigtable Pricing <https://cloud.google.com/bigtable/pricing>`_.
+
+Architecture & Payload Limits
+-----------------------------
+
+- **Chunk Size Optimization**: Set LMCache's logical ``chunk_size`` to **256 tokens**. This groups payloads to minimize sequential Point-Read gRPC calls, preventing Python event-loop (GIL) bottlenecks.
+- **MutateRow Limit**: Enforces a strict **90.0 MB request limit** for a single ``MutateRow`` gRPC request.
+- **Storage Tier Row Limits**: The **SSD Tier** ceiling is **100 MiB per cell/row**. The **Enterprise Plus In-Memory Tier** is limited to **1.0 MiB per row**.
+- **TTLCache Shielding**: Embeds a thread-safe ``TTLCache`` (10-second TTL default) to shield Bigtable nodes from concurrent prefetch lookup spikes.
+
+Infrastructure Setup
+--------------------
+
+**1. Enable GCP APIs**
+
+.. code-block:: bash
+
+gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com --project=your-gcp-project-id
+
+**2. Provision Bigtable Instance**
+
+Refer to the `gcloud beta bigtable Reference <https://cloud.google.com/sdk/gcloud/reference/beta/bigtable>`_ for additional parameter details.
+
+.. code-block:: bash
+
+gcloud beta bigtable instances create your-bigtable-instance-id \
+    --display-name="LMCache SSD Instance" \
+    --edition=ENTERPRISE \
+    --cluster-storage-type=ssd \
+    --cluster-config=id=your-cluster-id,zone=us-central1-a,nodes=1 \
+    --project=your-gcp-project-id
+
+**3. Create Database Table & Column Family**
+
+.. code-block:: bash
+
+gcloud bigtable instances tables create lmcache-benchmark-v1 \
+    --instance=your-bigtable-instance-id \
+    --column-families=cf \
+    --project=your-gcp-project-id
+
+**4. Install LMCache & Bigtable SDK**
+
+.. code-block:: bash
+
+export NO_NATIVE_EXT=1
+pip install --no-cache-dir lmcache google-cloud-bigtable
+
+Configuration
+-------------
+
+**Example A: Standard Bigtable SSD Integration (L2 Only)**
+
+.. code-block:: yaml
+
+chunk_size: 256
+
+local_cpu: true
+max_local_cpu_size: 10.0
+remote_url: "bigtable://your-gcp-project-id/your-bigtable-instance-id"
+
+remote_serde: "naive"
+
+extra_config:
+  bigtable_project_id: "your-gcp-project-id"
+  bigtable_instance_id: "your-bigtable-instance-id"
+  bigtable_table_name: "lmcache-benchmark-v1"
+
+.. note::
+   Alternatively, you can set the environment variables ``BT_PROJECT_ID``, ``BT_INSTANCE_ID``, and ``BT_TABLE_NAME`` instead of using ``extra_config``.
+
+**Example B: 3-Tier Multi-Connector Hybrid (Local CPU -> Redis L2 -> Bigtable SSD L3)**
+
+Deploy Redis for hot-cache loopbacks while offloading long-tail persistent storage to Bigtable SSD, using LMCache's dynamic OrderedDict routing.
+
+.. code-block:: yaml
+
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 15.0
+
+remote_storage_plugins:
+  - "redis"
+  - "bigtable"
+
+extra_config:
+  remote_storage_plugin.redis.redis_url: "redis://your-redis-host:6379"
+  
+  remote_storage_plugin.bigtable.bigtable_project_id: "your-gcp-project-id"
+  remote_storage_plugin.bigtable.bigtable_instance_id: "your-bigtable-instance-id"
+  remote_storage_plugin.bigtable.bigtable_table_name: "lmcache-benchmark-v1"
+  remote_storage_plugin.bigtable.bigtable_family_name: "cf"
+  remote_storage_plugin.bigtable.bigtable_column_name: "data"
+  
+  remote_storage_plugin.bigtable.credentials_path: "/etc/gcp/key.json"
+  
+  remote_storage_plugin.bigtable.bigtable_max_chunk_size_mb: 90.0
+  remote_storage_plugin.bigtable.exists_cache_ttl_seconds: 10.0
+  remote_storage_plugin.bigtable.exists_cache_size: 10000
+  
+  remote_storage_plugin.bigtable.bigtable_write_timeout_ms: 10000.0
+  remote_storage_plugin.bigtable.bigtable_read_timeout_ms: 5000.0
+
+Authentication
+--------------
+
+- **Application Default Credentials (ADC)**: If ``credentials_path`` is omitted or ``null``, the connector natively invokes ADC. Compatible with local development via ``gcloud auth application-default login`` or GKE Workload Identity Federation.
+- **Explicit Keys**: Pass the absolute filesystem path containing a mounted GCP Service Account JSON secret to ``credentials_path``.
+
+Verification
+------------
+
+Ensure you have installed the required dependencies:
+
+.. code-block:: bash
+
+pip install cachetools google-cloud-bigtable
+
+Run the unit tests:
+
+.. code-block:: bash
+
+pytest tests/v1/storage_backend/test_bigtable_connector.py
+
+Troubleshooting Large Payload Warnings
+--------------------------------------
+
+If you see a warning in the logs indicating that a chunk size exceeds the limit and is skipped (e.g. ``Bigtable chunk size ... MB exceeds threshold ... MB. Skipping write to prevent hard failures``), choose one of the following approaches:
+
+1. **Reduce the LMCache Chunk Size (Recommended)**:
+   The serialized chunk size depends on LMCache's logical ``chunk_size`` (number of tokens per chunk) and model shape. You can reduce ``chunk_size`` (e.g., from ``256`` to ``128``) in your configuration file to shrink individual chunk payloads.
+   
+2. **Increase the Max Chunk Size**:
+   If your Bigtable instance uses the SSD storage tier (which supports up to 100 MB per cell/row), you can raise the maximum allowed write threshold in the configuration up to ``99.0`` MB using the ``bigtable_max_chunk_size_mb`` config key (or the ``BT_MAX_CHUNK_SIZE_MB`` environment variable).
+   
+   .. warning::
+      Do not set ``bigtable_max_chunk_size_mb`` higher than ``100.0`` MB. While Cloud Bigtable supports up to ``256.0`` MB for a single row, a single cell value (which LMCache uses to store the chunk payload) has a hard limit of ``100.0`` MB. Exceeding this will trigger hard gRPC exceptions.
diff --git a/docs/source/kv_cache/storage_backends/cpu_ram.rst b/docs/source/kv_cache/storage_backends/cpu_ram.rst
new file mode 100644
index 0000000..cfbaaf4
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/cpu_ram.rst
@@ -0,0 +1,330 @@
+CPU RAM
+=======
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _cpu_ram-overview:
+
+Overview
+--------
+
+CPU RAM and Local Storage are the two ways of offloading KV cache onto non-GPU
+memory of the same machine that is running inference.
+
+Two ways to configure LMCache CPU Offloading:
+---------------------------------------------
+
+**1. Environment Variables:**
+
+.. code-block:: bash
+
+    # 256 Tokens per KV Chunk
+    export LMCACHE_CHUNK_SIZE=256
+    # Enable CPU memory backend
+    export LMCACHE_LOCAL_CPU=True # default
+    # 5GB of Pinned CPU memory
+    export LMCACHE_MAX_LOCAL_CPU_SIZE=5.0 # default
+
+**2. Configuration File**:
+
+Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    # Enable CPU memory backend
+    local_cpu: true # default
+    # 5GB of Pinned CPU memory
+    max_local_cpu_size: 5.0 # default
+
+CPU RAM Explanation:
+---------------------
+
+The ``LMCACHE_MAX_LOCAL_CPU_SIZE`` is the amount of page-locked (for fast GPU transfer)
+CPU memory that LMCache will reserve and must be set to a number greater than 0 since
+local and remote backends also use CPU RAM as an intermediate buffer when transferring KV caches
+with the GPU. This means it is possible to set ``LMCACHE_LOCAL_CPU=False`` even
+though ``LMCACHE_MAX_LOCAL_CPU_SIZE`` is set to a non-zero number.
+
+
+However, it is recommended to *always* set ``LMCACHE_LOCAL_CPU=True`` (the default is ``True`` so if you
+don't specify, CPU offloading will automatically be enabled) since this allows all currently unused pinned CPU RAM that
+LMCache has reserved to hold KV caches. When the pinned CPU RAM is required for any disk or remote transfers, the CPU KV caches will be LRU evicted to make
+space so there is no danger of running out of pinned CPU RAM.
+
+When ``LMCACHE_LOCAL_CPU=True`` is used in conjunction with the disk backend or
+a remote backend (:doc:`Redis <./redis>`, :doc:`Mooncake <./mooncake>`, :doc:`Valkey <./valkey>`,
+or :doc:`Infinistore <./infinistore>`), we can think of the CPU RAM as a "hot cache" that
+will contain the "hottest" (most recently accessed)subset of KV caches from Disk and Remote storage.
+
+Thus, the cache engine also has a **prefetch** mechanism to preload the KV caches for specified
+tokens into the pinned CPU RAM from the disk or remote storage (*if* the KV caches for these
+tokens are already stored there). This can preemptively avoid the latency of the disk and
+remote KV transfer if we predict these tokens will be requested soon (e.g. structured or agentic workflows).
+
+.. _cpu_ram-hugepage-support:
+
+Hugepage Support
+-----------------
+
+By default LMCache allocates CPU-pinned memory using regular 4 KiB pages.
+For large KV cache buffers (multiple gigabytes), enabling **Linux hugepages**
+(2 MiB pages) can reduce TLB (Translation Lookaside Buffer) pressure and
+improve memory access performance.
+
+**System prerequisite**
+
+Hugepages must be pre-allocated at the OS level before LMCache starts.
+TO find the number of pages needed, divide the desired buffer size by 2 MiB and round up.
+For example, 5 GB requires at least 2560 pages:
+
+.. code-block:: bash
+
+    # Allocate 2560 hugepages (5 GB)
+    sudo sysctl -w vm.nr_hugepages=2560
+
+    # Make persistent across reboots
+    echo 'vm.nr_hugepages=2560' | sudo tee -a /etc/sysctl.conf
+
+Verify that pages are available:
+
+.. code-block:: bash
+
+    grep HugePages /proc/meminfo
+    # HugePages_Total:    2560
+    # HugePages_Free:     2560
+
+**Configuration**
+
+.. code-block:: yaml
+
+    local_cpu_use_hugepages: true
+
+Or via environment variable:
+
+.. code-block:: bash
+
+    export LMCACHE_LOCAL_CPU_USE_HUGEPAGES=true
+
+**Restrictions**
+
+- Hugepages are **not compatible with P2P mode** (``enable_p2p: true``).
+- Hugepages are **not compatible with shared memory** (``shm_name`` is set).
+- On non-CUDA platforms, hugepages are not supported. Regular allocation will be used as fallback.
+
+.. _cpu_ram-online-inference-example:
+
+Online Inference Example
+------------------------
+
+Let's feel the TTFT (time to first token) differential!
+
+.. _cpu_ram-prerequisites:
+
+**Prerequisites:**
+
+- A Machine with at least one GPU. Adjust the max model length of your vllm instance depending on your GPU memory and the long context you want to use.
+
+- vllm and lmcache installed (:doc:`Installation Guide <../../getting_started/installation>`)
+
+- Hugging Face access to ``meta-llama/Meta-Llama-3.1-8B-Instruct``
+
+.. code-block:: bash
+
+    export HF_TOKEN=your_hugging_face_token
+
+- A few packages:
+
+.. code-block:: bash
+
+    pip install openai transformers
+
+**Step 0. Set up a directory for this example:**
+
+.. code-block:: bash
+
+    mkdir lmcache-cpu-ram-example
+    cd lmcache-cpu-ram-example
+
+**Step 1. Prepare a long context!**
+
+We want a context long enough that vllm's prefix caching will not be able to hold the KV caches in
+GPU memory and LMCache is necessary to keep KV caches in non-GPU memory:
+
+.. code-block:: bash
+
+    # 382757 bytes
+    man bash > man-bash.txt
+
+**Step 2. Start a vLLM server with CPU offloading enabled:**
+
+Create a an lmcache configuration file called: ``cpu-offload.yaml``
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    max_local_cpu_size: 5.0
+
+If you don't want to use a config file, uncomment the first three environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_LOCAL_CPU=True \
+    # LMCACHE_MAX_LOCAL_CPU_SIZE=5.0 \
+    LMCACHE_CONFIG_FILE="cpu-offload.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 16384 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+- ``--kv-transfer-config``: This is the parameter that actually tells vLLM to use LMCache for KV cache offloading.
+    - ``kv_connector``: Specifies the LMCache connector for vLLM V1
+    - ``kv_role``: Set to "kv_both" for both storing and loading KV cache (important because we will run two queries and the first will produce/store a KV cache while the second will consume/load that KV cache)
+
+**Step 3. Query TTFT improvements with LMCache:**
+
+Once the Open AI compatible server is running on default vllm port 8000, let's query it twice with the same long context!
+
+Create a script called ``query-twice.py`` and paste the following code:
+
+.. code-block:: python
+
+    import time
+    from openai import OpenAI
+    from transformers import AutoTokenizer
+
+    client = OpenAI(
+        api_key="dummy-key",  # required by OpenAI client even for local servers
+        base_url="http://localhost:8000/v1"
+    )
+
+    models = client.models.list()
+    model = models.data[0].id
+
+    # 119512 characters total
+    # 26054 tokens total
+    long_context = ""
+    with open("man-bash.txt", "r") as f:
+        long_context = f.read()
+
+    # a truncation of the long context for the --max-model-len 16384
+    # if you increase the --max-model-len, you can decrease the truncation i.e.
+    # use more of the long context
+    long_context = long_context[:70000]
+
+    tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3.1-8B-Instruct")
+    question = "Summarize bash in 2 sentences."
+
+    prompt = f"{long_context}\n\n{question}"
+
+    print(f"Number of tokens in prompt: {len(tokenizer.encode(prompt))}")
+
+    def query_and_measure_ttft():
+        start = time.perf_counter()
+        ttft = None
+
+        chat_completion = client.chat.completions.create(
+            messages=[{"role": "user", "content": prompt}],
+            model=model,
+            temperature=0.7,
+            stream=True,
+        )
+
+        for chunk in chat_completion:
+            chunk_message = chunk.choices[0].delta.content
+            if chunk_message is not None:
+                if ttft is None:
+                    ttft = time.perf_counter()
+                print(chunk_message, end="", flush=True)
+
+        print("\n")  # New line after streaming
+        return ttft - start
+
+    print("Querying vLLM server with cold LMCache CPU Offload")
+    cold_ttft = query_and_measure_ttft()
+    print(f"Cold TTFT: {cold_ttft:.3f} seconds")
+
+    print("\nQuerying vLLM server with warm LMCache CPU Offload")
+    warm_ttft = query_and_measure_ttft()
+    print(f"Warm TTFT: {warm_ttft:.3f} seconds")
+
+    print(f"\nTTFT Improvement: {(cold_ttft - warm_ttft):.3f} seconds \
+        ({(cold_ttft/warm_ttft):.1f}x faster)")
+
+Then run:
+
+.. code-block:: bash
+
+    python query-twice.py
+
+Since we're in streaming mode, you'll be able to feel the TTFT differential in
+real time!
+
+**Example Output:**
+
+.. code-block:: text
+
+    Number of tokens in prompt: 15376
+    Querying vLLM server with cold LMCache
+    Bash is a Unix shell and command-line interpreter that executes commands read
+    from the standard input or from a file, incorporating features from the Korn
+    and C shells. It is an sh-compatible command language interpreter that can be
+    configured to be POSIX-conformant by default and is intended to be a conformant
+    implementation of the Shell and Utilities portion of the IEEE POSIX specification.
+
+    Cold TTFT: 6.537 seconds
+
+    Querying vLLM server with warm LMCache
+    Bash is a Unix shell and command-line interpreter that eead from the standard
+    input or from a file, incorporatinhe Korn and C shells. It is intended to be a
+    conformant tation of the IEEE POSIX specification and can be configured to be
+    POSIX-conformant by default, with options for setting the shell's behavior and
+    interacting with the user.
+
+    Warm TTFT: 0.147 seconds
+
+    TTFT Improvement: 6.390 seconds (44.5x faster)
+
+If you look at the logs of your vLLM server, you should see (the logs are truncated for cleanliness):
+
+.. code-block:: text
+
+    # Cold LMCache Miss and then Store
+
+    LMCache INFO: Reqid: chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd, Total tokens 15410,
+    LMCache hit tokens: 0, need to load: 0
+
+    # you should see 8 of these storing logs total
+    # 2048 tokens is a multiple of the chunk size
+    LMCache INFO: Storing KV cache for 2048 out of 12288 tokens for request
+    chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd
+
+    LMCache INFO: Storing KV cache for 2048 out of 14336 tokens for request
+    chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd
+
+    LMCache INFO: Storing KV cache for 1074 out of 15410 tokens for request
+    chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd
+
+    # Warm LMCache Hit!!
+
+    LMCache INFO: Reqid: chatcmpl-136d9dac1ba94bd4b4ae85007e8ad437, Total tokens 15410,
+    LMCache hit tokens: 15409, need to load: 1
+
+.. _cpu_ram-tips:
+
+Tips:
+-----
+
+- If you want to run the ``query-twice.py`` script multiple times, you'll need to either restart the vLLM LMCache server or change the prefix of the context you pass in since you've already warmed LMCache.
+
+- The max model length here was decided by running an L4 with only 23GB of GPU memory. If you have more memory, you can increase the max model length and modify ``query-twice.py`` to use more of the long context. LMCache TTFT improvement becomes more pronounced as the context length increases!
diff --git a/docs/source/kv_cache/storage_backends/custom_backend.rst b/docs/source/kv_cache/storage_backends/custom_backend.rst
new file mode 100644
index 0000000..bc21a3f
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/custom_backend.rst
@@ -0,0 +1,6 @@
+Custom Storage Backends
+=======================
+
+LMCache supports integrating custom storage backends through dynamic loading or plug and play capability. This allows extending cache storage capabilities without modifying core code.
+
+See :doc:`Storage Plugins <../../developer_guide/extending_lmcache/storage_plugins>` for more details.
diff --git a/docs/source/kv_cache/storage_backends/dax.rst b/docs/source/kv_cache/storage_backends/dax.rst
new file mode 100644
index 0000000..1e8ce7b
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/dax.rst
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+
+Device-DAX (/dev/dax)
+=====================
+
+Overview
+--------
+
+The DAX storage plugin maps a ``/dev/dax`` device using ``mmap(MAP_SHARED)``
+and uses the mapped region as a fixed-size arena for KV cache chunks.
+Typical ``/dev/dax`` devices include persistent memory,
+CXL-attached memory, and other byte-addressable memory devices.
+
+Data stored on the DAX device may survive process restarts,
+but is not guaranteed to be durable.
+
+KV cache data is stored in the DAX region as part of the backend's storage flow.
+Reads copy data back into CPU-backed memory objects.
+
+
+Configuration
+-------------
+
+.. code-block:: yaml
+
+   local_cpu: true
+   max_local_cpu_size: 80
+
+   storage_plugins: ["dax"]
+   extra_config:
+     storage_plugin.dax.module_path: lmcache.v1.storage_backend.plugins.dax_backend
+     storage_plugin.dax.class_name: DaxBackend
+
+     dax.device_path: "/dev/dax1.0"
+     dax.max_dax_size: 100
+     dax.restore_workers: 8
+     dax.restore_max_regions: 8
+     dax.retrieve_staging_slab_bytes: 268435456
+
+
+Multiprocess Mode
+-----------------
+
+In LMCache multiprocess mode, Device-DAX is configured as a built-in L2
+adapter named ``dax``.  The MP adapter uses the normal L2 adapter
+``submit -> event fd -> query`` contract; no vLLM connector protocol changes
+are required.
+
+.. code-block:: bash
+
+   lmcache server \
+     --l1-size-gb 80 \
+     --eviction-policy LRU \
+     --l2-adapter '{
+       "type": "dax",
+       "device_path": "/dev/dax1.0",
+       "max_dax_size_gb": 100,
+       "slot_bytes": 268435456,
+       "num_store_workers": 1,
+       "num_lookup_workers": 1,
+       "num_load_workers": 4
+     }'
+
+The legacy single-device ``--l2-adapter`` JSON accepts these fields:
+
+- ``device_path``: required path to a readable and writable DAX device.
+- ``max_dax_size_gb``: required mapped size in GiB. The value must fit within
+  the device capacity when capacity can be determined with ``fstat``.
+- ``slot_bytes``: required fixed slot size in bytes. It must be large enough
+  for one full LMCache chunk.
+- ``num_store_workers``: optional store worker count, default ``1``.
+- ``num_lookup_workers``: optional lookup worker count, default ``1``.
+- ``num_load_workers``: optional load worker count, default
+  ``min(4, os.cpu_count())``.
+- ``persist_enabled``: accepted by common MP L2 parsing but ignored by
+  ``dax`` in this release.
+
+Runtime hotplug uses the multi-device form. The ``devices`` list may also be
+empty when ``hotplug_enabled`` is ``true``.
+
+.. code-block:: bash
+
+   lmcache server \
+     --l1-size-gb 80 \
+     --eviction-policy LRU \
+     --l2-adapter '{
+       "type": "dax",
+       "devices": [
+         {"device_path": "/dev/daxX.X", "max_dax_size_gb": 100},
+         {"device_path": "/dev/daxY.Y", "max_dax_size_gb": 100}
+       ],
+       "slot_bytes": 268435456,
+       "hotplug_enabled": true,
+       "num_store_workers": 1,
+       "num_lookup_workers": 1,
+       "num_load_workers": 4
+     }'
+
+MP DAX stores opaque ``ObjectKey`` values in memory and is volatile-only in
+this release.  Closing and reopening the server on the same DAX path starts
+with an empty index, so previously written bytes are not discoverable after
+restart.
+
+MP DAX uses one stable adapter facade per LMCache server.  The facade owns
+stable event fds and worker pools, and runtime add/remove/resize only changes
+the mapped DAX cores behind that facade.  It does not add kernel-level CXL or
+DAX reconfiguration, per-TP DAX partitions, on-device metadata, or restart
+recovery. Capacity accounting and eviction are slot-based: a stored object
+occupies one slot even if its payload is smaller than ``slot_bytes``.
+
+
+Runtime Hotplug API
+-------------------
+
+Runtime hotplug is disabled unless ``hotplug_enabled`` is ``true``. The API
+changes only LMCache runtime mappings and metadata; the ``/dev/dax*`` device
+must already exist and be readable and writable by the LMCache server process.
+The runtime endpoints are implemented through StorageManager's generic L2
+adapter reconfiguration interface, which routes backend, operation name, and
+adapter-specific payload to the selected adapter. DAX owns the path, mode,
+migration, and resize semantics; the generic interface is reusable by other
+adapters such as P2P.
+Use JSON bodies because DAX paths contain slashes:
+
+.. code-block:: bash
+
+   curl http://127.0.0.1:9000/reconfigure/dax/status
+   curl -X POST http://127.0.0.1:9000/reconfigure/dax/add \
+     -H 'Content-Type: application/json' \
+     -d '{"device_path": "/dev/daxX.X", "size": "100GiB"}'
+   curl -X POST http://127.0.0.1:9000/reconfigure/dax/remove \
+     -H 'Content-Type: application/json' \
+     -d '{"device_path": "/dev/daxX.X", "mode": "migrate"}'
+   curl -X POST http://127.0.0.1:9000/reconfigure/dax/resize \
+     -H 'Content-Type: application/json' \
+     -d '{"device_path": "/dev/daxX.X", "size": "200GiB"}'
+
+``size`` is required for add and resize. Use an integer byte count or a string
+such as ``"100GiB"``. ``remove`` supports these modes:
+
+- ``migrate``: move DAX-resident KV to other active DAX devices before closing
+  the source device.
+- ``evict``: delete DAX-resident KV on the source device. This is destructive
+  for the DAX tier.
+- ``drain``: stop new writes to the source device and leave existing KV
+  readable until it is evicted or the server closes.
+
+``resize`` supports ``migrate`` and ``evict`` modes. It does not support
+``drain`` because resize completes synchronously.
+
+Hotplug operations are lock-safe by default. A remove or shrink that would
+delete externally locked or borrowed slots returns ``409 Conflict`` unless
+``force`` is set. A migration that has no active destination capacity returns
+``507 Insufficient Storage``. Resize grow preserves the in-memory key index and
+does not move KV payloads. Resize shrink never silently drops keys; entries
+outside the new slot range must migrate first, or the request fails.
+
+
+Hardware Validation Flow
+------------------------
+
+Use the same Qwen 8B or 14B long-context workload before and after a runtime
+capacity change. Without hotplug support, ``/reconfigure/dax/status`` and
+``/reconfigure/dax/add`` are not available; changing the DAX device set
+requires restarting LMCache with a new ``--l2-adapter`` value, which drops the
+volatile DAX key index.
+
+.. code-block:: bash
+
+   export MODEL=Qwen/Qwen3-8B  # or a local Qwen 8B/14B checkpoint
+   curl http://127.0.0.1:9000/reconfigure/dax/status
+   python benchmarks/long_doc_qa/long_doc_qa.py \
+     --model "$MODEL" --num-documents 1 --document-length 1024 \
+     --output-len 16 --repeat-count 2 --repeat-mode tile \
+     --completions --host 127.0.0.1 --port 8000 --json-output
+   curl -X POST http://127.0.0.1:9000/reconfigure/dax/add \
+     -H 'Content-Type: application/json' \
+     -d '{"device_path": "/dev/daxX.X", "size": "100GiB"}'
+   curl http://127.0.0.1:9000/reconfigure/dax/status
+
+Record these fields for the comparison:
+
+- ``total_capacity_bytes`` before and after ``/reconfigure/dax/add``.
+- ``total_used_bytes`` while the Qwen workload is running.
+- Whether an LMCache restart was required.
+- Whether the same cached prompt remains retrievable after the capacity change.
+
+
+Using The Batched Restore Path
+------------------------------
+
+The current DAX optimization is a staged batched restore path for retrieval.
+It is enabled automatically whenever the DAX backend is configured. No extra
+feature flag is required.
+
+The retrieve flow is:
+
+1. Reserve a batched set of readable DAX chunks.
+2. Allocate CPU restore buffers from ``LocalCPUBackend``.
+3. Copy DAX data into a backend-owned pinned staging slab in coalesced regions.
+4. Copy from the staging slab into the final CPU ``MemoryObj`` outputs.
+5. Upload those CPU outputs through the normal GPU connector path.
+
+The store flow is unchanged: KV data is still staged through CPU memory before
+being written into the DAX arena.
+
+The new DAX tuning knobs control the batched restore path:
+
+- ``dax.restore_workers``: number of persistent worker threads used to execute
+  restore regions in parallel.
+- ``dax.restore_max_regions``: maximum number of restore regions in one wave.
+  Larger values increase parallelism but also increase slab space requirements.
+- ``dax.retrieve_staging_slab_bytes``: total size in bytes of the reusable
+  pinned retrieve slab. This must be large enough to hold one full chunk per
+  configured restore region.
+
+For a first pass, start with:
+
+- ``dax.restore_workers`` equal to the number of CPU workers you want devoted
+  to DAX restores
+- ``dax.restore_max_regions`` equal to ``dax.restore_workers``
+- ``dax.retrieve_staging_slab_bytes`` at least
+  ``dax.restore_max_regions * full_chunk_size``, then scale upward if larger
+  batched restores are common
+
+If retrieve throughput is low, increase the slab size first, then increase
+worker and region counts together. If CPU pressure is high, reduce
+``dax.restore_workers`` and ``dax.restore_max_regions``.
+
+
+Runtime Requirements
+--------------------
+
+- ``extra_config['dax.device_path']`` is required and must point to a readable
+  and writable DAX device.
+- The process must have read-write access to the DAX device
+  (e.g., via appropriate permissions or group membership).
+- ``LocalCPUBackend`` must be enabled because DAX reads return CPU-backed
+  memory objects.
+
+
+Validation and Current Limits
+-----------------------------
+
+- Tensor parallelism is currently limited to TP=1
+  (``metadata.world_size == 1``).
+- Only single-tensor chunk layouts are supported. Multi-tensor put
+  requests are rejected.
+- Batched restore uses a backend-owned retrieve staging slab and persistent
+  restore executors. The slab and region count can be tuned with
+  ``dax.restore_workers``, ``dax.restore_max_regions``, and
+  ``dax.retrieve_staging_slab_bytes``.
+- Blocking batched restore preserves positional output semantics, while
+  asynchronous batched restore returns only the consecutive hit prefix.
diff --git a/docs/source/kv_cache/storage_backends/eic.rst b/docs/source/kv_cache/storage_backends/eic.rst
new file mode 100644
index 0000000..6c03af5
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/eic.rst
@@ -0,0 +1,45 @@
+EIC
+===
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+EIC(Elastic Instant Cache) is a distributed database designed for LLM KV Cache. It supports RDMA, GDR and has the capabilities of distributed disaster tolerance and expansion.
+You can understand the principles and architecture of EIC through these articles: 
+
+* https://mp.weixin.qq.com/s/tasDqXf0Gxr3o_WCJ2IJUQ
+* https://mp.weixin.qq.com/s/b_4YhTa96Zeklh23lv8qBw
+
+Deploy EIC
+----------
+
+You can visit the official link https://console.volcengine.com/eic and deploy EIC KVCache on your compute cluster with web UI. In addition, we provide particular image in volcano engine, which integrates various optimizations based on the official image.
+You may use tests/v1/storage_backend/test_eic.py to detect the connectivity of EIC.
+
+Deploy Model With EIC
+---------------------
+
+You can enable EIC KVCache offload with the official interface, such as
+
+.. code-block:: bash
+
+   export LMCACHE_CONFIG_FILE=/workspace/config/remote-eic.yaml
+   export VLLM_USE_V1=1
+
+   python3 -m vllm.entrypoints.openai.api_server \
+     ... \
+     --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    remote_url: "eic://your-eic-endpoint"
+    eic_instance_id: "your-eic-instance-id"
+    eic_flag_file: "your-eic-config-path"
+
+
+For more details, you can see https://www.volcengine.com/docs/85848/1749188.
\ No newline at end of file
diff --git a/docs/source/kv_cache/storage_backends/fs.rst b/docs/source/kv_cache/storage_backends/fs.rst
new file mode 100644
index 0000000..aa1fd2d
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/fs.rst
@@ -0,0 +1,194 @@
+Filesystem Backend
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/fs`.
+
+
+The filesystem backend uses ``FSConnector`` to store LMCache remote chunks as
+files under one or more POSIX filesystem directories. It is useful when you want
+a simple persistent remote backend, or when multiple inference workers can see
+the same mounted directory through local disk, NFS, a parallel filesystem, or a
+container volume.
+
+This backend is different from :doc:`local_storage`. Local disk offloading is a
+per-process local tier configured through ``local_disk``. ``FSConnector`` is a
+remote backend configured through ``remote_storage_plugins`` or the legacy
+``remote_url`` field, so it participates in the same remote backend path as
+Redis, S3, Mooncake, and other remote connectors.
+
+When to use it
+--------------
+
+Use ``FSConnector`` when:
+
+* You need a lightweight persistent remote backend for development, examples,
+  or benchmark runs.
+* Multiple LMCache or vLLM processes share a mounted cache directory.
+* Your storage is already exposed as a filesystem and does not need a separate
+  object-store or key-value service.
+* You want to test remote-backend behavior before moving to a production
+  backend such as Redis, Valkey, S3, Mooncake, or InfiniStore.
+
+Avoid using it when:
+
+* The filesystem is not shared by every process that must read the cache.
+* You need object-store semantics, cross-region persistence, or service-level
+  access control.
+* The storage path is on a slow network filesystem and sits on the hot request
+  path.
+
+Recommended configuration
+-------------------------
+
+The recommended form is the built-in remote storage plugin configuration. The
+plugin name ``fs`` selects ``FSConnector`` and the base path is configured in
+``extra_config``.
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: false
+   max_local_cpu_size: 1
+   save_unfull_chunk: false
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+
+   remote_storage_plugins: ["fs"]
+   extra_config:
+     remote_storage_plugin.fs.base_path: "/tmp/lmcache-fs"
+     save_chunk_meta: false
+
+``FSConnector`` creates the base directory if it does not already exist. Each
+cache chunk is written as a ``.data`` file whose name is derived from the
+LMCache cache key.
+
+Multiple filesystem instances
+-----------------------------
+
+You can configure multiple named ``fs`` instances by appending an instance name
+after the connector type. The part before the first dot is still the connector
+type; the full plugin name becomes the ``extra_config`` prefix.
+
+.. code-block:: yaml
+
+   remote_storage_plugins: ["fs.primary", "fs.backup"]
+   extra_config:
+     remote_storage_plugin.fs.primary.base_path: "/mnt/cache-primary/lmcache"
+     remote_storage_plugin.fs.backup.base_path: "/mnt/cache-backup/lmcache"
+     save_chunk_meta: false
+
+This is useful when a deployment wants separate filesystem-backed remote stores
+for different cache policies, traffic classes, or experiments.
+
+Multiple base paths
+-------------------
+
+``remote_storage_plugin.<name>.base_path`` may contain a comma-separated list of
+directories. The connector chooses a directory by hashing the cache chunk key,
+which spreads files across the configured paths.
+
+.. code-block:: yaml
+
+   remote_storage_plugins: ["fs"]
+   extra_config:
+     remote_storage_plugin.fs.base_path: "/mnt/nvme0/lmcache,/mnt/nvme1/lmcache"
+     save_chunk_meta: false
+
+Use multiple paths when each path maps to an independent storage device or mount
+point. For best results, keep every path visible to the LMCache processes that
+need to retrieve the same chunks.
+
+Legacy ``remote_url`` configuration
+-----------------------------------
+
+The legacy ``remote_url`` form is still supported. The host and port are parsed
+for compatibility with other remote URL formats; ``FSConnector`` uses the path.
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: false
+   max_local_cpu_size: 1
+   save_unfull_chunk: false
+   remote_url: "fs://localhost:0/tmp/lmcache-fs"
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+   extra_config:
+     save_chunk_meta: false
+
+Prefer ``remote_storage_plugins`` for new deployments because it also supports
+named instances and keeps connector-specific settings grouped by plugin name.
+
+Optional settings
+-----------------
+
+The connector reads the following optional settings from ``extra_config``.
+
+``fs_connector_relative_tmp_dir``
+   Relative directory used for temporary files before an atomic rename into the
+   final chunk path. The value must be relative, not absolute. When omitted,
+   temporary files are created next to the final file with a ``.tmp`` suffix.
+
+``fs_connector_read_ahead_size``
+   Number of bytes to read first when loading a chunk. If the read fills that
+   window, the connector reads the remaining bytes. This can trigger filesystem
+   readahead on filesystems that support it.
+
+``fs_connector_use_odirect``
+   Enables ``O_DIRECT`` for aligned reads and writes on platforms that expose
+   it. The connector falls back to normal I/O when a chunk size is not aligned
+   to the filesystem block size. ``O_DIRECT`` is disabled automatically when
+   ``save_chunk_meta`` is enabled because the metadata prefix is not block
+   aligned.
+
+``fs_base_path``
+   Compatibility fallback for plugin mode. Prefer
+   ``remote_storage_plugin.<name>.base_path`` so the setting remains scoped to a
+   specific plugin instance.
+
+Example with optional settings:
+
+.. code-block:: yaml
+
+   remote_storage_plugins: ["fs"]
+   extra_config:
+     remote_storage_plugin.fs.base_path: "/data/lmcache-fs"
+     fs_connector_relative_tmp_dir: ".tmp"
+     fs_connector_read_ahead_size: 1048576
+     fs_connector_use_odirect: true
+     save_chunk_meta: false
+
+Operational notes
+-----------------
+
+* Ensure the LMCache process has permission to create directories and write
+  files under every configured base path.
+* Put the path on durable storage if cache reuse must survive process restarts.
+  Temporary directories such as ``/tmp`` are convenient for tests but may be
+  cleaned by the operating system.
+* Use the same mounted path for every process that should share cache chunks.
+  If one process writes to a private container path, other processes will miss
+  those chunks even if they use the same configuration text.
+* Leave ``save_chunk_meta`` enabled when workers may infer different metadata
+  for the same chunk. Disable it only when you need the lower overhead path and
+  the workers share compatible cache metadata.
+* For MP mode L2 storage, see :doc:`../../mp/l2_storage/index`, which documents the
+  ``fs`` and ``fs_native`` L2 adapters configured through ``--l2-adapter``.
+
+Minimal vLLM usage
+------------------
+
+After writing ``fs.yaml`` with one of the configurations above, start vLLM with
+LMCache enabled:
+
+.. code-block:: bash
+
+   LMCACHE_CONFIG_FILE=fs.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct \
+       --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+       --disable-log-requests
+
+Then send the same long-prefix request twice. The first request stores chunks in
+the filesystem backend. The second request should report LMCache hit tokens and
+load matching chunks from the configured filesystem path.
diff --git a/docs/source/kv_cache/storage_backends/gds.rst b/docs/source/kv_cache/storage_backends/gds.rst
new file mode 100644
index 0000000..160a990
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/gds.rst
@@ -0,0 +1,275 @@
+GDS Backend
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _gds-overview:
+
+Overview
+--------
+
+This backend will work with any file system, whether local, remote, and remote
+with GDS-based optimizations. Remote file systems allow for multiple LMCache
+instances to share data seamlessly. The GDS (GPU-Direct Storage) optimizations
+are used for zero-copy I/O from GPU memory to storage systems. Supports both
+NVIDIA cuFile and AMD hipFile for GPU-direct storage.
+
+
+Ways to configure LMCache GDS Backend
+-----------------------------------------
+
+**1. Environment Variables:**
+
+.. code-block:: bash
+
+    # 256 Tokens per KV Chunk
+    export LMCACHE_CHUNK_SIZE=256
+    # Path to store files
+    export LMCACHE_GDS_PATH="/mnt/gds/cache"
+    # GDS Buffer Size in MiB
+    export LMCACHE_GDS_BUFFER_SIZE="8192"
+    # Disabling CPU RAM offload is sometimes recommended as the
+    # CPU can get in the way of GPUDirect operations
+    export LMCACHE_LOCAL_CPU=False
+
+**2. Configuration File**:
+
+Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    # Disable local CPU
+    local_cpu: false
+    # Path to file system, local, remote or GDS-enabled mount
+    gds_path: "/mnt/gds/cache"
+    # GDS Buffer Size in MiB
+    gds_buffer_size: 8192
+
+
+Multi-Path (Multi-Device) Support
+---------------------------------
+
+When a system has multiple NVMe drives, you can distribute GDS I/O across them
+by specifying a comma-separated list of paths in ``gds_path``. The
+``gds_path_sharding`` option controls how each GPU worker selects its path.
+Currently only ``"by_gpu"`` is supported (the default), which selects a path
+based on the device index (``device_id % num_paths``), so traffic is spread
+evenly across the drives without any manual pinning.
+
+**Why this helps:** a single PCIe Gen 4 x4 NVMe tops out at ~7 GB/s. With four
+drives the aggregate bandwidth can reach ~28 GB/s, matching what multi-GPU
+systems need for KV cache eviction and prefetch.
+
+**Environment variables:**
+
+.. code-block:: bash
+
+    export LMCACHE_GDS_PATH="/mnt/nvme0/cache,/mnt/nvme1/cache,/mnt/nvme2/cache,/mnt/nvme3/cache"
+    export LMCACHE_GDS_PATH_SHARDING="by_gpu"
+
+**YAML config:**
+
+.. code-block:: yaml
+
+    gds_path: "/mnt/nvme0/cache,/mnt/nvme1/cache,/mnt/nvme2/cache,/mnt/nvme3/cache"
+    gds_path_sharding: "by_gpu"
+
+With the above configuration on a 4-GPU node:
+
+- ``cuda:0`` writes to ``/mnt/nvme0/cache``
+- ``cuda:1`` writes to ``/mnt/nvme1/cache``
+- ``cuda:2`` writes to ``/mnt/nvme2/cache``
+- ``cuda:3`` writes to ``/mnt/nvme3/cache``
+
+If there are more GPUs than paths, the assignment wraps around (e.g. ``cuda:4``
+maps back to ``/mnt/nvme0/cache``). A single path (no commas) works exactly as
+before.
+
+All directories are created automatically at startup. Every path in the list
+must reside on a filesystem that the rest of the GDS configuration expects
+(e.g., all paths on GDS-capable mounts when using cuFile).
+
+**Read behavior:** on startup the backend scans **all** configured paths for
+previously-stored KV cache entries, regardless of GPU affinity.  This means a
+``cuda:0`` worker whose write affinity is ``/mnt/nvme0/cache`` will still
+discover entries that were written to ``/mnt/nvme1/cache`` by ``cuda:1`` in a
+prior run.  Writes, however, always go to the single affinity-selected path.
+
+.. code-block:: text
+
+   Startup scan (read):   iterate ALL gds_paths → populate hot_cache
+   Runtime writes:        only the affinity path  (device_id % num_paths)
+   Runtime reads:         look up hot_cache first; on miss, check ALL
+                          gds_paths on disk → load from whichever path
+                          the entry lives on
+
+
+GDS Buffer Size Explanation
+---------------------------
+
+The backend currently pre-registers buffer space to speed up GDS operations. This buffer space
+is registered in VRAM so options like ``--gpu-memory-utilization`` from ``vllm`` should be considered
+when setting it. For example, a good rule of thumb for H100 which generally has 80GiBs of VRAM would
+be to start with 8GiB and set ``--gpu-memory-utilization 0.85`` and depending on your workflow fine-tune
+it from there.
+
+
+Using AMD hipFile
+-----------------
+
+.. note::
+
+   hipFile is alpha software and has been tested on limited hardware.
+   For full installation details, see the
+   `hipFile install guide <https://github.com/ROCm/rocm-systems/blob/develop/projects/hipfile/INSTALL.md>`__.
+
+**Prerequisites:**
+
+- **ROCm >= 7.2** with ``amdgpu-dkms >= 30.20.1``
+  (see the `ROCm quick start installation guide <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html>`__)
+- **Supported storage:** local NVMe drives only
+- **Supported filesystems:** ext4 (mounted with ``data=ordered``) and xfs
+- **Kernel:** ``CONFIG_PCI_P2PDMA`` must be enabled
+
+**Quick install (Ubuntu 24.04):**
+
+.. code-block:: bash
+
+    sudo apt install libmount-dev wget
+
+    # Install nightly hipFile packages
+    wget https://github.com/ROCm/hipFile/releases/download/nightly/hipfile_0.2.0.70200-nightly.9999.24.04_amd64.deb
+    wget https://github.com/ROCm/hipFile/releases/download/nightly/hipfile-dev_0.2.0.70200-nightly.9999.24.04_amd64.deb
+    sudo dpkg -i hipfile-dev_0.2.0.70200-nightly.9999.24.04_amd64.deb hipfile_0.2.0.70200-nightly.9999.24.04_amd64.deb
+
+You can verify that the HIP libraries and kernel support AIS (AMD Infinity Storage) by running:
+
+.. code-block:: bash
+
+    /opt/rocm/bin/ais-check
+
+Successful output will show ``True`` for ``Kernel P2PDMA support``, ``HIP runtime``, and ``amdgpu``.
+
+**LMCache configuration:**
+
+To use AMD hipFile instead of NVIDIA cuFile, set the GDS backend:
+
+**Environment Variables:**
+
+.. code-block:: bash
+
+    export LMCACHE_GDS_BACKEND=hipfile
+
+**Configuration File:**
+
+.. code-block:: yaml
+
+    gds_backend: "hipfile"
+
+Note: The ``gds_buffer_size`` configuration is used for both cuFile and hipFile buffers.
+
+
+Setup Example
+-------------
+
+.. _gds-prerequisites:
+
+**Prerequisites:**
+
+- A Machine with at least one GPU. You can adjust the max model length of your vllm instance depending on your GPU memory.
+
+- A mounted file system. A file system supportings GDS will work best.
+
+- vllm and lmcache installed (:doc:`Installation Guide <../../getting_started/installation>`)
+
+- Hugging Face access to ``meta-llama/Llama-3.1-8B-Instruct``
+
+.. code-block:: bash
+
+    export HF_TOKEN=your_hugging_face_token
+
+**Step 1. Create cache directory under your file system mount:**
+
+To find all the types of file systems supporting GDS in your system, use `gdscheck` from NVIDIA:
+
+.. code-block:: bash
+
+    sudo /usr/local/cuda-*/gds/tools/gdscheck -p
+
+Check with your storage vendor on how to mount the remote file system.
+
+(For example, if you want to use a GDS-enabled NFS driver, try the modified [NFS
+stack](https://vastnfs.vastdata.com/), which is an open source driver that
+works with any standard [NFS
+RDMA](https://datatracker.ietf.org/doc/html/rfc5532) server. More
+vendor-specific instructions will be added here in the future).
+
+Create a directory under the file systew mount (the name here is arbitrary):
+
+.. code-block:: bash
+
+    mkdir /mnt/gds/cache
+
+**Step 2. Start a vLLM server with file backend enabled:**
+
+Create a an lmcache configuration file called: ``gds-backend.yaml``
+
+.. code-block:: yaml
+
+    local_cpu: false
+    chunk_size: 256
+    gds_path: "/mnt/gds/cache"
+    gds_buffer_size: 8192
+
+If you don't want to use a config file, uncomment the first three environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # LMCACHE_LOCAL_CPU=False \
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_GDS_PATH="/mnt/gds/cache" \
+    # LMCACHE_GDS_BUFFER_SIZE=8192 \
+    LMCACHE_CONFIG_FILE="gds-backend.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 65536 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+
+POSIX fallback
+--------------
+
+In some cases, libcufile implements its own internal POSIX fallback without `GdsBackend` being aware.
+In others, an error such as `RuntimeError: cuFileHandleRegister failed (cuFile err=5030, cuda_err=0)` may be throwned.
+Thus, backend can be configured to fallback to its own POSIX implementation when the usage of the GDS APIs is not successful.
+
+To force `GdsBackend` not use GDS APIs for any reason, you can override its behavior via configuration:
+
+.. code-block:: yaml
+
+    use_gds: false
+
+Or via environment variable:
+
+.. code-block:: bash
+
+    LMCACHE_USE_GDS=False
+
+The ``gds_backend`` field (default: ``cufile``) selects which GDS library to use. Supported
+backends are ``cufile`` (NVIDIA cuFile) and ``hipfile`` (AMD hipFile):
+
+.. code-block:: yaml
+
+    use_gds: true
+    gds_backend: "cufile"   # or "hipfile"
+
+Note that under this mode it would still use CUDA APIs to map and do operations the pre-registered GPU memory.
diff --git a/docs/source/kv_cache/storage_backends/hfbucket.rst b/docs/source/kv_cache/storage_backends/hfbucket.rst
new file mode 100644
index 0000000..2f5dc46
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/hfbucket.rst
@@ -0,0 +1,183 @@
+Hugging Face Buckets Backend
+============================
+
+The Hugging Face Buckets backend stores LMCache chunks in a Hugging Face Bucket
+using LMCache's built-in remote storage plugin framework. This is a persistent
+remote backend that fits warm and cold KV cache persistence better than the
+hottest local tiers.
+
+When to use it
+--------------
+
+Use the HFBucket backend when you want:
+
+* A Hub-native persistent store for KV cache data.
+* A remote backend that can be configured through ``remote_storage_plugins``.
+* Multiple named bucket instances in one LMCache deployment.
+
+Avoid using it as the primary hot path for the lowest-latency cache lookups.
+Local CPU, local disk, and other lower-latency backends are a better fit for
+the hottest cache tier.
+
+
+Requirements and limitations
+----------------------------
+
+* LMCache uses ``huggingface_hub`` bucket APIs for uploads, downloads, listing,
+  and deletes.
+* The first built-in release is intentionally conservative:
+
+  * Only full chunks are supported.
+  * Partial chunk uploads are rejected.
+  * Downloads are rejected when the stored object size does not match the
+    expected full LMCache chunk size.
+  * Chunk metadata is not stored in the bucket objects.
+
+
+Minimal configuration
+---------------------
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: false
+   save_unfull_chunk: false
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+   remote_storage_plugins: ["hfbucket"]
+   extra_config:
+     remote_storage_plugin.hfbucket.bucket_handle: "hf://buckets/my-org/lmcache-kv/prod"
+     remote_storage_plugin.hfbucket.token_env: "HF_TOKEN"
+     remote_storage_plugin.hfbucket.create_bucket_if_missing: false
+     remote_storage_plugin.hfbucket.download_tmp_dir: "/tmp/lmcache-hfbucket"
+     remote_storage_plugin.hfbucket.metadata_cache_ttl_secs: 30
+
+
+Multiple instances
+------------------
+
+Use instance-qualified plugin names to configure more than one bucket-backed
+remote store in the same LMCache config.
+
+.. code-block:: yaml
+
+   remote_storage_plugins: ["hfbucket.us", "hfbucket.eu"]
+   extra_config:
+     remote_storage_plugin.hfbucket.us.bucket_handle: "hf://buckets/my-org/lmcache-kv/us"
+     remote_storage_plugin.hfbucket.us.token_env: "HF_US_TOKEN"
+     remote_storage_plugin.hfbucket.eu.bucket_handle: "hf://buckets/my-org/lmcache-kv/eu"
+     remote_storage_plugin.hfbucket.eu.token_env: "HF_EU_TOKEN"
+
+
+Configuration reference
+-----------------------
+
+All configuration keys live under
+``extra_config.remote_storage_plugin.<plugin_name>.*`` where ``plugin_name`` is
+either ``hfbucket`` or an instance-qualified name such as ``hfbucket.prod``.
+
+* ``bucket_handle`` (required): Hugging Face Bucket handle in
+  ``hf://buckets/<namespace>/<bucket>[/<prefix>]`` format.
+* ``token_env`` (optional, default ``HF_TOKEN``): Environment variable used to
+  resolve the Hugging Face access token.
+* ``token`` (optional): Direct token override. ``token_env`` takes precedence
+  when both are set.
+* ``create_bucket_if_missing`` (optional, default ``false``): Lazily create the
+  bucket on the first write path.
+* ``download_tmp_dir`` (optional): Root directory for connector-local download
+  scratch space. On Linux, pointing this at a tmpfs mount such as
+  ``/dev/shm/lmcache-hfbucket`` avoids the disk write on the download path.
+* ``metadata_cache_ttl_secs`` (optional, default ``30``): TTL for cached exact
+  existence and size metadata.
+
+
+MP Mode Configuration
+---------------------
+
+In multi-process (MP) mode, Hugging Face Buckets are configured as an L2
+adapter through a JSON spec passed to the LMCache server. This is separate from
+the non-MP ``remote_storage_plugins`` configuration above. Each
+``--l2-adapter`` argument takes a JSON object whose ``"type": "hfbucket"``
+field selects the HFBucket adapter.
+
+.. code-block:: json
+
+   {
+     "type": "hfbucket",
+     "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod",
+     "token_env": "HF_TOKEN",
+     "create_bucket_if_missing": false,
+     "download_tmp_dir": "/tmp/lmcache-hfbucket-mp",
+     "metadata_cache_ttl_secs": 30,
+     "num_workers": 4,
+     "max_capacity_gb": 500,
+     "eviction": {
+       "eviction_policy": "LRU",
+       "trigger_watermark": 0.85,
+       "eviction_ratio": 0.2
+     }
+   }
+
+HFBucket L2 Adapter Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* **type** (required): must be ``"hfbucket"``.
+* **bucket_handle** (required): Hugging Face Bucket handle in
+  ``hf://buckets/<namespace>/<bucket>[/<prefix>]`` format.
+* **token_env**: environment variable used to resolve the Hugging Face access
+  token (default ``"HF_TOKEN"``).
+* **token**: optional direct token fallback. ``token_env`` takes precedence
+  when the environment variable is set. Prefer ``token_env`` for production
+  deployments so secrets do not live in adapter JSON.
+* **create_bucket_if_missing**: lazily create the bucket on the first store
+  operation (default ``false``). This only helps when the bucket is missing and
+  the token has permission to create it; it does not fix invalid credentials,
+  invalid handles, or network failures.
+* **download_tmp_dir**: root directory for temporary load downloads (default
+  ``/tmp/lmcache-hfbucket-mp``). The MP adapter downloads bucket files into
+  per-task temporary files and then copies their bytes into the destination
+  ``MemoryObj`` buffers supplied by the MP controller.
+* **metadata_cache_ttl_secs**: TTL for cached exact path-size metadata (default
+  ``30``). Set this lower when another process may modify the same bucket
+  prefix outside LMCache and fresher metadata is more important than reducing
+  Hugging Face metadata calls.
+* **num_workers**: number of worker threads used for blocking Hugging Face Hub
+  bucket API calls (default ``4``). The HFBucket Python APIs are synchronous,
+  so MP mode runs upload, lookup, load, and delete work on a bounded thread
+  pool behind the adapter's eventfd-based completion interface.
+* **max_capacity_gb**: capacity used by ``get_usage()`` for watermark-based L2
+  eviction. Set to ``0`` (default) to disable aggregate capacity tracking;
+  ``get_usage()`` then reports the adapter as not providing an eviction signal.
+* **eviction**: optional sub-dict enabling the L2 eviction controller for this
+  adapter. When present, keys that are currently being loaded are protected by
+  the lookup-and-lock path and skipped by ``delete()`` until they are unlocked.
+
+Differences vs Non-MP HFBucket
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Hugging Face bucket operations are synchronous but the adapter makes submission
+  non-blocking by running the blocking calls on worker threads.
+* MP loads do not allocate and return new memory. The MP controller provides
+  destination ``MemoryObj`` buffers, and the adapter copies downloaded bytes
+  into those buffers.
+* Keys are identified by ``ObjectKey`` (``model_name`` + ``kv_rank`` +
+  ``chunk_hash`` + optional ``cache_salt``) rather than ``CacheEngineKey``.
+  The serialized MP object name is
+  ``<model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]`` and is then
+  encoded for the bucket path. This naming is not compatible with the non-MP
+  HFBucket connector's ``CacheEngineKey`` object names, so a bucket prefix
+  populated by non-MP LMCache cannot be read directly by MP LMCache and vice
+  versa.
+* Full object writes are batch based. Hugging Face batch writes are not
+  transactional, so a failed store task may still leave some objects in the
+  bucket. The MP adapter reconciles backend metadata after such failures so
+  any objects that actually landed are counted for usage and later deletion 
+  (submitted store task is still reported as failed).
+
+
+Notes
+-----
+
+* The backend stores objects under the configured bucket prefix using a
+  reversible encoding of LMCache keys, so ``list()`` returns LMCache key strings
+  instead of raw bucket object paths.
diff --git a/docs/source/kv_cache/storage_backends/index.rst b/docs/source/kv_cache/storage_backends/index.rst
new file mode 100644
index 0000000..748816c
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/index.rst
@@ -0,0 +1,41 @@
+Using Different Storage Backends
+================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+LMCache supports various storage backends to offload and share KV cache data.
+
+Supported Backends
+-------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   azure
+   cpu_ram
+   custom_backend
+   dax
+   eic
+   fs
+   gds
+   hfbucket
+   infinistore
+   local_storage
+   maru
+   mock
+   mooncake
+   nixl
+   redis
+   bigtable
+   resp
+   s3
+   sagemaker_hyperpod
+   valkey
+   weka
+   3fs
+   
+   
+  
diff --git a/docs/source/kv_cache/storage_backends/infinistore.rst b/docs/source/kv_cache/storage_backends/infinistore.rst
new file mode 100644
index 0000000..14828ee
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/infinistore.rst
@@ -0,0 +1,208 @@
+InfiniStore
+===========
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _infinistore-overview:
+
+Overview
+--------
+
+`InfiniStore <https://github.com/bytedance/InfiniStore>`_ is an open-source high-performance KV store. It's designed to support LLM Inference clusters, whether the cluster is in prefill-decoding disaggregation mode or not. InfiniStore provides high-performance and low-latency KV cache transfer and KV cache reuse among inference nodes in the cluster.
+
+There are two major scenarios how InfiniStore supports:
+
+* Prefill-Decoding disaggregation clusters: in such mode inference workloads are separated into two node pools: prefill nodes and decoding nodes. InfiniStore enables KV cache transfer among these two types of nodes, and also KV cache reuse.
+* Non-disaggregated clusters: in such mode prefill and decoding workloads are mixed on every node. InfiniStore serves as an extra large KV cache pool in addition to GPU cache and local CPU cache, and also enables cross-node KV cache reuse.
+
+.. image:: ../../assets/InfiniStore-usage.png
+    :alt: InfiniStore Usage Diagram
+
+For more details, please refer to the `InfiniStore Documentation <https://bytedance.github.io/InfiniStore/index.html>`_.
+
+InfiniStore supports both RDMA and TCP for transport. LMCache’s InfiniStore connector only uses the RDMA transport.
+
+
+Quick Start
+-----------
+
+Install InfiniStore via pip:
+
+.. code-block:: bash
+
+    pip install infinistore
+
+This package includes the InfiniStore server and the Python bindings.
+
+To build InfiniStore from source, follow the instructions in the `GitHub repository <https://github.com/bytedance/InfiniStore>`_. 
+
+Setup and Deployment
+~~~~~~~~~~~~~~~~~~~~
+
+**Prerequisites:**
+
+- Machine with at least one GPU for vLLM inference
+- RDMA-capable network hardware and drivers
+- Python 3.8+ with pip
+- vLLM and LMCache installed
+
+**Step 1: Start InfiniStore Server**
+
+For InfiniBand based RDMA:
+
+.. code-block:: bash
+
+    infinistore --service-port 12345 --dev-name mlx5_0 --link-type IB
+
+For RoCE based RDMA:
+
+.. code-block:: bash
+
+    infinistore --service-port 12345 --dev-name mlx5_0 --link-type Ethernet
+
+You can also specify the ``--hint-gid-index`` option to set the GID index for the InfiniStore server. This is useful when you are in a k8s managed environment.
+
+**Step 2: Create Configuration File**
+
+Create your ``infinistore-config.yaml``:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    remote_url: "infinistore://127.0.0.1:12345/?device=mlx5_1"
+    remote_serde: "naive"
+    local_cpu: False
+    max_local_cpu_size: 5
+
+**Step 3: Start vLLM with InfiniStore**
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE="infinistore-config.yaml" \
+    vllm serve \
+        Qwen/Qwen2.5-7B-Instruct \
+        --seed 42 \
+        --max-model-len 16384 \
+        --gpu-memory-utilization 0.8 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+**Step 4: Verify the Setup**
+
+Test the integration with a sample request:
+
+.. code-block:: bash
+
+    curl -X POST "http://localhost:8000/v1/completions" \
+         -H "Content-Type: application/json" \
+         -d '{
+           "model": "Qwen/Qwen2.5-7B-Instruct",
+           "prompt": "The future of AI is",
+           "max_tokens": 100,
+           "temperature": 0.7
+         }'
+
+**Debugging Tips:**
+
+1. **Enable verbose logging:**
+
+   .. code-block:: bash
+
+       infinistore --log-level=debug
+
+2. **Check server status:**
+
+   .. code-block:: bash
+
+       # Check if the server is running
+       ps aux | grep infinistore
+       netstat -tlnp | grep -E "12345"
+
+Query TTFT Improvement
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Once the OpenAI compatible server is running, let's query it twice and see the TTFT improvement.
+
+Run vLLM's serving benchmark twice with the following parameters:
+
+.. code-block:: bash
+
+    vllm bench serve \
+        --backend vllm \
+        --model Qwen/Qwen2.5-7B-Instruct \
+        --num-prompts 50 \
+        --port 8000 \
+        --host 127.0.0.1 \
+        --dataset-name random \
+        --random-input-len 8192 \
+        --random-output-len 128 \
+        --seed 42
+
+**Example Output:**
+
+For the first run, you might see:
+
+.. code-block:: text
+
+    ============ Serving Benchmark Result ============
+    Successful requests:                     50
+    Benchmark duration (s):                  80.97
+    Total input tokens:                      409544
+    Total generated tokens:                  6273
+    Request throughput (req/s):              0.62
+    Output token throughput (tok/s):         77.48
+    Total Token throughput (tok/s):          5135.74
+    ---------------Time to First Token----------------
+    Mean TTFT (ms):                          36203.54
+    Median TTFT (ms):                        34598.91
+    P99 TTFT (ms):                           76010.91
+    -----Time per Output Token (excl. 1st token)------
+    Mean TPOT (ms):                          290.30
+    Median TPOT (ms):                        346.25
+    P99 TPOT (ms):                           412.24
+    ---------------Inter-token Latency----------------
+    Mean ITL (ms):                           290.30
+    Median ITL (ms):                         386.78
+    P99 ITL (ms):                            449.83
+
+For the second run, you should see a significant reduction in TTFT:
+
+.. code-block:: text
+
+    ============ Serving Benchmark Result ============
+    Successful requests:                     50
+    Benchmark duration (s):                  15.14
+    Total input tokens:                      409544
+    Total generated tokens:                  6273
+    Request throughput (req/s):              3.30
+    Output token throughput (tok/s):         414.22
+    Total Token throughput (tok/s):          27457.55
+    ---------------Time to First Token----------------
+    Mean TTFT (ms):                          2880.53
+    Median TTFT (ms):                        3118.50
+    P99 TTFT (ms):                           12027.24
+    -----Time per Output Token (excl. 1st token)------
+    Mean TPOT (ms):                          73.81
+    Median TPOT (ms):                        71.12
+    P99 TPOT (ms):                           91.24
+    ---------------Inter-token Latency----------------
+    Mean ITL (ms):                           73.81
+    Median ITL (ms):                         63.86
+    P99 ITL (ms):                            565.44
+
+TTFT Improvement: 33.323 seconds (12.6x faster).
+
+**Tips:** 
+
+- If you want to run vLLM's serving benchmark multiple times, you'll need to either restart the vLLM LMCache server and the InfiniStore server, or change the ``--seed`` parameter to a different value each time, since you've already warmed up LMCache.
+- The benchmark result here was produced by running an L40 with 48GB of GPU memory with ``--gpu-memory-utilization 0.8``. You can adjust the GPU memory utilization and increase the max model length to use more of the long context. LMCache TTFT improvement becomes more pronounced as the context length increases!
+
+
+Additional Resources
+--------------------
+
+- `InfiniStore Documentation <https://bytedance.github.io/InfiniStore/index.html>`_
+- `GitHub Repository <https://github.com/bytedance/InfiniStore>`_
diff --git a/docs/source/kv_cache/storage_backends/local_storage.rst b/docs/source/kv_cache/storage_backends/local_storage.rst
new file mode 100644
index 0000000..52d2813
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/local_storage.rst
@@ -0,0 +1,464 @@
+Local storage
+=============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _local-storage-overview:
+
+Overview
+--------
+
+CPU RAM and Local Storage are the two ways of offloading KV cache onto non-GPU
+memory of the same machine that is running inference.
+
+
+Two ways to configure LMCache Disk Offloading:
+----------------------------------------------
+
+
+**1. Environment Variables:**
+
+.. code-block:: bash
+
+    # 256 Tokens per KV Chunk
+    export LMCACHE_CHUNK_SIZE=256
+    # None if disabled
+    # Otherwise, enable by setting the directory where LMCache will
+    # create files for each KV cache chunks
+    # (this directory does NOT need to exist beforehand)
+    export LMCACHE_LOCAL_DISK="file://$HOME/local/disk_test/local_disk/"
+    # 5GB of Disk
+    export LMCACHE_MAX_LOCAL_DISK_SIZE=5.0
+
+    # Disable page cache
+    # This should be turned on for better performance if most local CPU memory is used
+    # Optionally tune the number of I/O worker threads (default: 4)
+    export LMCACHE_EXTRA_CONFIG='{"use_odirect": true, "disk_io_threads": 8}'
+
+**2. Configuration File**:
+
+Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    # Enable Disk backend
+    local_disk: "file:///local/disk_test/local_disk/"
+    # 5GB of Disk memory
+    max_local_disk_size: 5.0
+
+    # Disable page cache
+    # This should be turned on for better performance if most local CPU memory is used
+    # Optionally tune the number of I/O worker threads (default: 4)
+    extra_config:
+      use_odirect: true
+      disk_io_threads: 8
+
+
+Multi-Path (Multi-Device) Disk Offloading
+-----------------------------------------
+
+If you have **multiple NVMe devices** (or any independent mount points), you can
+assign each GPU its own disk path so that each device writes to a dedicated drive.
+
+Specify a **comma-separated list** of paths in ``local_disk``.
+Each path can optionally use the ``file://`` prefix.  The
+``local_disk_path_sharding`` option controls how each GPU worker selects its
+path.  Currently only ``"by_gpu"`` is supported (the default), which selects a
+path based on the device index (``device_id % num_paths``), so all KV cache
+files from a given GPU land on the same NVMe.  This is especially useful when
+GPUs and NVMe devices share a PCIe switch or NUMA node.
+
+For example, with two GPUs and two paths:
+
+- ``cuda:0`` → ``/mnt/nvme0/kvcache/``
+- ``cuda:1`` → ``/mnt/nvme1/kvcache/``
+
+``max_local_disk_size`` is the **total budget** shared across all paths.
+
+**Environment variable example:**
+
+.. code-block:: bash
+
+    export LMCACHE_LOCAL_DISK="file:///mnt/nvme0/kvcache/,file:///mnt/nvme1/kvcache/"
+    export LMCACHE_LOCAL_DISK_PATH_SHARDING="by_gpu"
+    export LMCACHE_MAX_LOCAL_DISK_SIZE=20.0   # combined budget (GB)
+
+**YAML example:**
+
+.. code-block:: yaml
+
+    local_disk: "/mnt/nvme0/kvcache/,/mnt/nvme1/kvcache/"
+    local_disk_path_sharding: "by_gpu"
+    max_local_disk_size: 20.0
+
+.. note::
+
+    Each GPU worker uses only its assigned path, so O_DIRECT alignment
+    is determined by that path's filesystem block size.  Different
+    devices may have different block sizes without issue.
+
+.. tip::
+
+    If you are able to use kernel-level RAID 0 (e.g. ``mdadm --level=0``)
+    you will get true block-level striping (even a single large file can
+    use bandwidth from both devices simultaneously).  The multi-path
+    feature is most useful when you cannot or do not want to reconfigure
+    the block devices — for example, when they already have other data.
+
+Local Storage Explanation:
+--------------------------
+
+Unlike CPU RAM offloading, disk offloading is *disabled* by default (``local_disk`` is set to ``None``) and the
+max local disk size is set to 0GB instead of 5GB like the default max local cpu size
+since the disk space is not strictly necessary for LMCache to function.
+
+Furthermore, instead of greedily allocating the max space up front like the pinned CPU RAM, the disk backend will
+create one file per KV cache chunk as they are stored, evicting if capacity is exceeded (LRU currently).
+
+The disk and remote (see :doc:`Redis <./redis>`, :doc:`Mooncake <./mooncake>`, :doc:`Valkey <./valkey>`, :doc:`InfiniStore <./infinistore>`)
+backends have asynchronous put() operations so that the IO latency will not slow down inference in addition to blocking get() operations.
+The local disk backend also has a prefetch() operation that will preemptively move KV caches from the disk to CPU RAM offloading storage
+(i.e. ``LMCACHE_LOCAL_CPU=True`` should be set, see :doc:`CPU RAM <./cpu_ram>`) for specified tokens (these KV caches are also still kept in the disk).
+
+
+Architecture Overview
+---------------------
+
+The following diagram shows the overall architecture of the Local Disk Backend:
+
+.. mermaid::
+
+    %%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '18px', 'fontFamily': 'arial', 'primaryColor': '#e3f2fd', 'primaryTextColor': '#000', 'primaryBorderColor': '#1976d2', 'lineColor': '#424242', 'secondaryColor': '#f5f5f5', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#495057' }}}%%
+    flowchart TB
+        subgraph Engine["<b>LMCache Engine</b>"]
+            E["<b>Request Save/Load Operations</b>"]
+        end
+
+        subgraph LDB["<b>LocalDiskBackend</b>"]
+            subgraph Meta["<b>Metadata Dictionary</b>"]
+                Dict["<b>self.dict: CacheEngineKey → DiskCacheMetadata</b>
+                (path, size, shape, dtype, pinned, positions)"]
+            end
+            
+            subgraph Policy["<b>Cache Policy</b>"]
+                CP["<b>Configurable Policy</b>
+                (LRU, LFU, FIFO, MRU)
+                Decides what to evict"]
+            end
+            
+            subgraph Worker["<b>LocalDiskWorker</b>"]
+                PQ["<b>Priority Queue Executor (configurable workers, default 4)</b>"]
+                P0["<b>Priority 0: PREFETCH</b>"]
+                P1["<b>Priority 1: DELETE</b>"]
+                P2["<b>Priority 2: PUT</b>"]
+            end
+            
+            CPU["<b>LocalCPUBackend</b>
+            (memory allocator)"]
+        end
+
+        subgraph Disk["<b>Local Filesystem</b>"]
+            Files["/cache/vllm@model@...@abc.pt
+            /cache/vllm@model@...@def.pt
+            /cache/vllm@model@...@ghi.pt"]
+        end
+
+        E --> Dict
+        Dict --> CP
+        CP --> PQ
+        PQ --> P0
+        PQ --> P1
+        PQ --> P2
+        Worker --> Files
+        CPU -.-> Worker
+
+**Key Components:**
+
+- **Metadata Dictionary**: Maps each ``CacheEngineKey`` to its disk metadata (file path, size, shape, dtype, pin status)
+- **Cache Policy**: Configurable eviction policy (LRU, LFU, FIFO, or MRU) that tracks access patterns and decides which entries to evict when space is needed
+- **LocalDiskWorker**: Async task executor with priority queue - prefetch tasks run first (priority 0), then deletes (priority 1), then saves (priority 2). The number of I/O worker threads is configurable via ``extra_config.disk_io_threads`` (default: 4).
+- **Local Disk**: Filesystem where KV cache chunks are stored as individual ``.pt`` files
+
+
+Save Flow (PUT)
+~~~~~~~~~~~~~~~
+
+.. mermaid::
+
+    %%{init: {'theme': 'base', 'flowchart': {'useMaxWidth': false, 'htmlLabels': true, 'nodeSpacing': 30, 'rankSpacing': 30}, 'themeVariables': { 'fontSize': '18px', 'fontFamily': 'arial', 'primaryColor': '#e3f2fd', 'primaryTextColor': '#000', 'primaryBorderColor': '#1976d2', 'lineColor': '#424242', 'secondaryColor': '#f5f5f5', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#495057' }}}%%
+    flowchart LR
+        A["<b>MemoryObj</b><br/>(KV cache in CPU memory)"] --> B{<b>Disk space<br/>available?</b>}
+        B -->|"No"| C["<b>Evict via policy</b><br/>Delete .pt files"]
+        C --> B
+        B -->|"Yes"| D["<b>Track in put_tasks</b><br/>Queue async write<br/>(Priority 2 - lowest)"]
+        D --> E["<b>LocalDiskWorker</b><br/>write_file()"]
+        E --> F[("<b>Disk</b><br/>.pt file")]
+        F --> G["<b>Add to metadata dict</b>"]
+
+        style A fill:#e1f5fe
+        style F fill:#c8e6c9
+        style C fill:#ffcdd2
+
+Load Flow (GET)
+~~~~~~~~~~~~~~~
+
+.. mermaid::
+
+    %%{init: {'theme': 'base', 'flowchart': {'useMaxWidth': false, 'htmlLabels': true, 'nodeSpacing': 30, 'rankSpacing': 30}, 'themeVariables': { 'fontSize': '18px', 'fontFamily': 'arial', 'primaryColor': '#e3f2fd', 'primaryTextColor': '#000', 'primaryBorderColor': '#1976d2', 'lineColor': '#424242', 'secondaryColor': '#f5f5f5', 'tertiaryColor': '#ffffff', 'background': '#ffffff', 'clusterBkg': '#f8f9fa', 'clusterBorder': '#495057' }}}%%
+    flowchart LR
+        A["<b>Request</b><br/>(CacheEngineKey)"] --> B{<b>Key exists<br/>in dict?</b>}
+        B -->|"No"| C["<b>Return None</b><br/>(cache miss)"]
+        B -->|"Yes"| D["<b>Update policy</b><br/>Mark as accessed"]
+        D --> E["<b>Allocate buffer</b><br/>via LocalCPUBackend"]
+        E --> F["<b>Read from disk</b><br/>read_file()"]
+        F --> G[("<b>Disk</b><br/>.pt file")]
+        G --> F
+        F --> H["<b>MemoryObj</b><br/>(KV cache ready)"]
+
+        style A fill:#e1f5fe
+        style H fill:#c8e6c9
+        style C fill:#ffcdd2
+        
+.. _local-storage-online-inference-example:
+
+Online Inference Example
+------------------------
+
+This example is almost identical to the :doc:`CPU RAM <./cpu_ram>` example.
+
+Let's feel the TTFT (time to first token) differential!
+
+.. _local-storage-prerequisites:
+
+**Prerequisites:**
+
+- A Machine with at least one GPU. Adjust the max model length of your vllm instance depending on your GPU memory and the long context you want to use.
+
+- vllm and lmcache installed (:doc:`Installation Guide <../../getting_started/installation>`)
+
+- Hugging Face access to ``meta-llama/Meta-Llama-3.1-8B-Instruct``
+
+.. code-block:: bash
+
+    export HF_TOKEN=your_hugging_face_token
+
+- A few packages:
+
+.. code-block:: bash
+
+    pip install openai transformers
+
+
+
+**Step 0. Set up a directory for this example:**
+
+.. code-block:: bash
+
+    mkdir lmcache-local-disk-example
+    cd lmcache-local-disk-example
+
+**Step 1. Prepare a long context!**
+
+We want a context long enough that vllm's prefix caching will not be able to hold the KV caches in
+GPU memory and LMCache is necessary to keep KV caches in non-GPU memory:
+
+.. code-block:: bash
+
+    # 382757 bytes
+    man bash > man-bash.txt
+
+**Step 2. Start a vLLM server with Disk offloading enabled:**
+
+*Generally, it is not recommended but we will disable CPU offloading to feel just the disk offloading latency.*
+
+Create a an lmcache configuration file called: ``disk-offload.yaml``
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: false
+    max_local_cpu_size: 5.0
+    local_disk: "file:///local/disk_test/local_disk/"
+    max_local_disk_size: 5.0
+
+If you don't want to use a config file, uncomment the first five environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_LOCAL_CPU=False \
+    # LMCACHE_MAX_LOCAL_CPU_SIZE=5.0 \
+    # LMCACHE_LOCAL_DISK="file:///local/disk_test/local_disk/" \
+    # LMCACHE_MAX_LOCAL_DISK_SIZE=5.0 \
+    LMCACHE_CONFIG_FILE="disk-offload.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 16384 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+- ``--kv-transfer-config``: This is the parameter that actually tells vLLM to use LMCache for KV cache offloading.
+    - ``kv_connector``: Specifies the LMCache connector for vLLM V1
+    - ``kv_role``: Set to "kv_both" for both storing and loading KV cache (important because we will run two queries and the first will produce/store a KV cache while the second will consume/load that KV cache)
+
+
+**Step 3. Query TTFT improvements with LMCache:**
+
+Once the Open AI compatible server is running on default vllm port 8000, let's query it twice with the same long context!
+
+Create a script called ``query-twice.py`` and paste the following code:
+
+.. code-block:: python
+
+    import time
+    from openai import OpenAI
+    from transformers import AutoTokenizer
+
+    client = OpenAI(
+        api_key="dummy-key",  # required by OpenAI client even for local servers
+        base_url="http://localhost:8000/v1"
+    )
+
+    models = client.models.list()
+    model = models.data[0].id
+
+    # 119512 characters total
+    # 26054 tokens total
+    long_context = ""
+    with open("man-bash.txt", "r") as f:
+        long_context = f.read()
+
+    # a truncation of the long context for the --max-model-len 16384
+    # if you increase the --max-model-len, you can decrease the truncation i.e.
+    # use more of the long context
+    long_context = long_context[:70000]
+
+    tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3.1-8B-Instruct")
+    question = "Summarize bash in 2 sentences."
+
+    prompt = f"{long_context}\n\n{question}"
+
+    print(f"Number of tokens in prompt: {len(tokenizer.encode(prompt))}")
+
+    def query_and_measure_ttft():
+        start = time.perf_counter()
+        ttft = None
+
+        chat_completion = client.chat.completions.create(
+            messages=[{"role": "user", "content": prompt}],
+            model=model,
+            temperature=0.7,
+            stream=True,
+        )
+
+        for chunk in chat_completion:
+            chunk_message = chunk.choices[0].delta.content
+            if chunk_message is not None:
+                if ttft is None:
+                    ttft = time.perf_counter()
+                print(chunk_message, end="", flush=True)
+
+        print("\n")  # New line after streaming
+        return ttft - start
+
+    print("Querying vLLM server with cold LMCache Disk Offload")
+    cold_ttft = query_and_measure_ttft()
+    print(f"Cold TTFT: {cold_ttft:.3f} seconds")
+
+    print("\nQuerying vLLM server with warm LMCache Disk Offload")
+    warm_ttft = query_and_measure_ttft()
+    print(f"Warm TTFT: {warm_ttft:.3f} seconds")
+
+    print(f"\nTTFT Improvement: {(cold_ttft - warm_ttft):.3f} seconds \
+        ({(cold_ttft/warm_ttft):.1f}x faster)")
+
+Then run:
+
+.. code-block:: bash
+
+    python query-twice.py
+
+Since we're in streaming mode, you'll be able to feel the TTFT differential in
+real time!
+
+Note that if we were to enable ``LMCACHE_LOCAL_CPU=True``, we would just be using
+the same example from :doc:`CPU RAM <./cpu_ram>` since the CPU RAM is checked before
+the disk by LMCache. In practice, the disk will be capable of storing a larger
+quantity of KV caches so the CPU RAM offloading will only be able to store a
+subset of the disk's KV caches.
+
+**Example Output:**
+
+
+.. code-block:: text
+
+    Number of tokens in prompt: 15376
+    Querying vLLM server with cold LMCache Disk Offload
+    Bash is a Unix shell and command-line interpreter that reads and executes
+    commands from standard input or a file, incorporating features from the
+    Korn and C shells. It is a conformant implementation of the IEEE POSIX
+    specification and can be configure to be POSIX-conformant by default,
+    supporting a wide range of options, built-in commands,
+    and features for scripting, job control, and interactive use.
+
+    Cold TTFT: 6.314 seconds
+
+    Querying vLLM server with warm LMCache Disk Offload
+    Bash is a Unix shell and command-line interpreter that reads and
+    executes commands from the standard input or a file, and is designed
+    to be a conformant implementation of the IEEE POSIX specification. It
+    is a powerful tool for automating tasks, managing files and directories,
+    and interacting with other programs and services, with features such as
+    scripting, conditional statements, loops, and functions.
+
+    Warm TTFT: 0.148 seconds
+
+TTFT Improvement: 6.166 seconds     (42.6x faster)
+
+If you look at the logs of your vLLM server, you should see (the logs are truncated for cleanliness):
+
+.. code-block:: text
+
+    # Cold LMCache Miss and then Store
+
+    LMCache INFO: Reqid: chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd, Total tokens 15410,
+    LMCache hit tokens: 0, need to load: 0
+
+    # you should see 8 of these storing logs total
+    # 2048 tokens is a multiple of the chunk size
+    LMCache INFO: Storing KV cache for 2048 out of 12288 tokens for request
+    chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd
+
+    LMCache INFO: Storing KV cache for 2048 out of 14336 tokens for request
+    chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd
+
+    LMCache INFO: Storing KV cache for 1074 out of 15410 tokens for request
+    chatcmpl-8676f9b9ebf04c79a5d47b9ada7b65fd
+
+    # Warm LMCache Hit!!
+
+    LMCache INFO: Reqid: chatcmpl-136d9dac1ba94bd4b4ae85007e8ad437, Total tokens 15410,
+    LMCache hit tokens: 15409, need to load: 1
+
+Check out your KV Cache in your SSD:
+
+.. code-block:: bash
+
+    ls "$HOME/local/disk_test/local_disk/"
+
+.. _local-storage-tips:
+
+Tips:
+-----
+
+- If you want to run the ``query-twice.py`` script multiple times, you'll need to either restart the vLLM LMCache server or change the prefix of the context you pass in since you've already warmed LMCache.
+
+- The max model length here was decided by running an L4 with only 23GB of GPU memory. If you have more memory, you can increase the max model length and modify ``query-twice.py`` to use more of the long context. LMCache TTFT improvement becomes more pronounced as the context length increases!
diff --git a/docs/source/kv_cache/storage_backends/maru.rst b/docs/source/kv_cache/storage_backends/maru.rst
new file mode 100644
index 0000000..39a8243
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/maru.rst
@@ -0,0 +1,118 @@
+Maru
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _maru-overview:
+
+Overview
+--------
+
+`Maru <https://github.com/xcena-dev/maru>`_ is a high-performance KV cache storage engine built on CXL shared memory,
+designed for LLM inference scenarios where multiple instances need to share a KV cache with minimal latency.
+
+.. image:: ../../assets/maru-kvcache.png
+    :alt: KV Cache Sharing: Without vs With Maru
+
+For architecture details, see the `Maru documentation <https://xcena-dev.github.io/maru/>`_.
+
+Quick Start
+-----------
+
+Install Maru:
+
+.. code-block:: bash
+
+    git clone https://github.com/xcena-dev/maru.git
+    cd maru
+    ./install.sh
+
+This installs ``maru-server``, ``maru-resourced``, and the ``maru`` Python package.
+
+Deploy Model With Maru
+~~~~~~~~~~~~~~~~~~~~~~
+
+**Prerequisites:** CXL device (``/dev/dax*``), Python 3.12+, vLLM and LMCache installed.
+
+**1. Start the Maru Server**
+
+.. code-block:: bash
+
+    maru-server
+
+**2. Create configuration file** (``maru-config.yaml``):
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: False
+    max_local_cpu_size: 0
+    save_unfull_chunk: True
+
+    # Maru backend
+    maru_path: "maru://localhost:5555"
+    maru_pool_size: 4
+
+**3. Start vLLM with Maru**
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE="maru-config.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 65536 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Configuration
+-------------
+
+**LMCache Parameters:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``maru_path``
+     - Required
+     - Maru server URL (format: ``maru://host:port``)
+   * - ``maru_pool_size``
+     - ``4.0``
+     - CXL memory pool size per instance in GB (e.g., ``4``, ``0.5``)
+
+**Advanced Parameters (via extra_config):**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``maru_instance_id``
+     - auto UUID
+     - Unique client instance identifier
+   * - ``maru_timeout_ms``
+     - 5000
+     - ZMQ RPC socket timeout in milliseconds
+   * - ``maru_use_async_rpc``
+     - true
+     - Async DEALER-ROUTER RPC (``false`` for synchronous REQ-REP)
+   * - ``maru_max_inflight``
+     - 64
+     - Max concurrent async RPC requests
+   * - ``maru_eager_map``
+     - true
+     - Pre-map all shared regions on connect
+
+Additional Resources
+--------------------
+
+- `Maru GitHub Repository <https://github.com/xcena-dev/maru>`_
+- `Maru Documentation <https://xcena-dev.github.io/maru/>`_
diff --git a/docs/source/kv_cache/storage_backends/mock.rst b/docs/source/kv_cache/storage_backends/mock.rst
new file mode 100644
index 0000000..fa45bd0
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/mock.rst
@@ -0,0 +1,70 @@
+Mock
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+LMCache provides a mock remote connector that allows you to manually set the peeking latency, read throughput, and write throughput inside of the remote url. It will create copies of your KV cache in unmanaged local RAM.
+
+Configuration
+-------------
+
+Create a configuration file (e.g., ``mock.yaml``) with the following content:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: False
+    max_local_cpu_size: 10
+    remote_url: "mock://100/?peeking_latency=1&read_throughput=2&write_throughput=2"
+
+The ``remote_url`` format is ``mock://SIZE/?peeking_latency=LATENCY&read_throughput=READ_GBPS&write_throughput=WRITE_GBPS`` where:
+
+- ``SIZE``: Maximum storage size
+- ``peeking_latency``: Latency for peeking operations (in milliseconds)
+- ``read_throughput``: Read throughput (in GB/s)
+- ``write_throughput``: Write throughput (in GB/s)
+
+Usage
+-----
+
+Deploy a serving engine with the mock remote backend:
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE=mock.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+        --disable-log-requests \
+        --no-enable-prefix-caching
+
+Check the retrieval (storing is async so the throughput there is meaningless) logs on the second query to confirm that the throughput is slightly lower than 2 GB/s (the CPU <-> GPU allocation/transfer also has overhead).
+
+Example Query
+-------------
+
+Send a test request:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "meta-llama/Llama-3.1-8B-Instruct",
+        "prompt": "'"$(printf 'Elaborate the significance of KV cache in language models. %.0s' {1..1000})"'",
+        "max_tokens": 10
+      }'
+
+Expected Logs
+-------------
+
+You should see logs similar to the following:
+
+.. code-block:: text
+
+    (EngineCore_0 pid=586318) [2025-09-03 05:06:41,751] LMCache INFO: Reqid: cmpl-b34e7c5b2f3e46a592722db2c27f6fc0-0, Total tokens 12002, LMCache hit tokens: 12002, need to load: 12001 (vllm_v1_adapter.py:1049:lmcache.integration.vllm.vllm_v1_adapter)
+    (EngineCore_0 pid=586318) [2025-09-03 05:06:42,736] LMCache INFO: Retrieved 12002 out of total 12002 out of total 12002 tokens. size: 1.651 gb, cost 980.6983 ms, throughput: 1.8939 GB/s; (cache_engine.py:503:lmcache.v1.cache_engine)
+
+The logs confirm that the throughput is slightly lower than 2 GB/s due to CPU <-> GPU allocation/transfer overhead.
+
diff --git a/docs/source/kv_cache/storage_backends/mooncake.rst b/docs/source/kv_cache/storage_backends/mooncake.rst
new file mode 100644
index 0000000..8bd942e
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/mooncake.rst
@@ -0,0 +1,255 @@
+Mooncake
+========
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/mooncake_store`.
+
+
+.. _mooncake-overview:
+
+Overview
+--------
+
+`Mooncake <https://github.com/kvcache-ai/Mooncake>`_ is an open-source distributed KV cache storage system designed specifically for LLM inference scenarios. 
+The system creates a distributed memory pool by aggregating memory space contributed by various client nodes, enabling efficient resource utilization across clusters.
+
+By pooling underutilized DRAM and SSD resources from multiple nodes, the system forms a unified distributed storage service that maximizes resource efficiency.
+
+.. image:: ../../assets/mooncake-store-preview.png
+    :alt: Mooncake Architecture Diagram
+
+Key Features
+~~~~~~~~~~~~
+
+- **Distributed memory pooling**: Aggregates memory contributions from multiple client nodes into a unified storage pool
+- **High bandwidth utilization**: Supports striping and parallel I/O transfer of large objects, fully utilizing multi-NIC aggregated bandwidth
+- **RDMA optimization**: Built on Transfer Engine with support for TCP, RDMA (InfiniBand/RoCEv2/eRDMA/NVIDIA GPUDirect)
+- **Dynamic resource scaling**: Supports dynamically adding and removing nodes for elastic resource management
+
+For detailed architecture information, see the `Mooncake Architecture Guide <https://kvcache-ai.github.io/Mooncake/design/mooncake-store.html>`_.
+
+Quick Start
+-----------
+
+Install Mooncake via pip:
+
+.. code-block:: bash
+
+    pip install mooncake-transfer-engine
+
+This package includes all necessary components:
+
+- ``mooncake_master``: Master service that manages cluster metadata and coordinates distributed storage operations
+- ``mooncake_http_metadata_server``: HTTP-based metadata server used by the underlying transfer engine for connection establishment
+- Mooncake Python bindings
+
+For production deployments or custom builds, see the `Build Instructions <https://kvcache-ai.github.io/Mooncake/getting_started/build.html>`_.
+
+Setup and Deployment
+~~~~~~~~~~~~~~~~~~~~
+
+**Prerequisites:**
+
+- Machine with at least one GPU for vLLM inference
+- RDMA-capable network hardware and drivers (recommended) or TCP network
+- Python 3.8+ with pip
+- vLLM and LMCache installed
+
+**Step 1: Start Infrastructure Services**
+
+Start the Mooncake master service (with built‑in HTTP metadata server):
+
+.. code-block:: bash
+
+    # Master service (use -v=1 for verbose logging)
+    # The flag enables the integrated HTTP metadata server
+    mooncake_master --enable_http_metadata_server=1
+
+Expected output:
+
+.. code-block:: text
+
+    Master service started on port 50051
+    HTTP metrics server started on port 9003
+    Master Metrics: Storage: 0.00 B / 0.00 B | Keys: 0 | ...
+
+**Step 2: Create Configuration File**
+
+Create your ``mooncake-config.yaml``:
+
+.. code-block:: yaml
+
+    # LMCache Configuration
+    local_cpu: False
+    remote_url: "mooncakestore://localhost:50051/"
+    max_local_cpu_size: 2  # small local buffer
+    numa_mode: "auto"      # reduce tail latency with multi-NUMA/multi-NIC
+    pre_caching_hash_algorithm: sha256_cbor_64bit
+
+    # Mooncake Configuration (via extra_config)
+    extra_config:
+      use_exists_sync: true
+      save_chunk_meta: False  # Enable chunk metadata optimization
+      local_hostname: "localhost"
+      metadata_server: "http://localhost:8080/metadata"
+      protocol: "rdma"
+      device_name: ""        # leave empty; autodetect device(s)
+      global_segment_size: 21474836480   # 20 GiB per worker
+      master_server_address: "localhost:50051"
+      local_buffer_size: 0    # rely on LMCache local_cpu as the buffer
+      mooncake_prefer_local_alloc: true  # prefer local segment if available
+
+**Step 3: Start vLLM with Mooncake**
+
+.. code-block:: bash
+
+    # If you see persistent misses (no Mooncake hits), make sure
+    # PYTHONHASHSEED is fixed across processes (e.g., export PYTHONHASHSEED=0).
+    LMCACHE_CONFIG_FILE="mooncake-config.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 65536 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+**Step 4: Verify the Setup**
+
+Test the integration with a sample request:
+
+.. code-block:: bash
+
+    curl -X POST "http://localhost:8000/v1/completions" \
+         -H "Content-Type: application/json" \
+         -d '{
+           "model": "meta-llama/Llama-3.1-8B-Instruct",
+           "prompt": "The future of AI is",
+           "max_tokens": 100,
+           "temperature": 0.7
+         }'
+
+**Debugging Tips:**
+
+1. **Enable verbose logging:**
+
+   .. code-block:: bash
+
+       mooncake_master -v=1
+
+2. **Check service status:**
+
+   .. code-block:: bash
+
+       # Check if services are running
+       ps aux | grep mooncake
+       netstat -tlnp | grep -E "(8080|50051)"
+
+3. **Monitor metrics:**
+
+   Access metrics at ``http://localhost:9003`` when master service is running.
+
+Configuration
+-------------
+
+**LMCache Parameters:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``chunk_size``
+     - 256
+     - Number of tokens per KV chunk
+   * - ``remote_url``
+     - Required
+     - Mooncake store connection URL (format: ``mooncakestore://host:port/``).
+   * - ``remote_serde``
+     - "naive"
+     - Serialization method for remote storage
+   * - ``local_cpu``
+     - False
+     - Enable/disable local CPU caching (set to False for pure Mooncake evaluation)
+   * - ``max_local_cpu_size``
+     - Required
+     - Maximum local CPU cache size in GB (required even when local_cpu is False)
+   * - ``numa_mode``
+     - "auto"
+     - NUMA binding mode. "auto" is recommended on multi‑NIC/multi‑NUMA systems to reduce tail latency.
+   * - ``pre_caching_hash_algorithm``
+     - "sha256_cbor_64bit"
+     - Hash used for pre-caching keying. For cross‑process consistency, fix ``PYTHONHASHSEED`` (e.g., export ``PYTHONHASHSEED=0``).
+
+**Mooncake Parameters (via extra_config):**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``local_hostname``
+     - Required
+     - Hostname/IP of the local node for Mooncake client identification
+   * - ``metadata_server``
+     - Required
+     - HTTP metadata server address. When starting master with ``--enable_http_metadata_server=1``, it exposes this endpoint.
+   * - ``master_server_address``
+     - Required
+     - Mooncake master service address (host:port format)
+   * - ``protocol``
+     - "rdma"
+     - Communication protocol ("rdma" for high performance; "tcp" for compatibility)
+   * - ``device_name``
+     - ""
+     - RDMA device specification (e.g., "erdma_0,erdma_1" or "mlx5_0,mlx5_1"). Leave empty for autodetection in most setups.
+   * - ``global_segment_size``
+     - 21474836480
+     - **Memory size contributed by each vLLM worker** in bytes (e.g., 20 GiB recommended)
+   * - ``local_buffer_size``
+     - 0
+     - Local buffer size in bytes used by Mooncake. Behavior depends on ``save_chunk_meta``:
+       - When ``save_chunk_meta: False`` (recommended), LMCache uses its local CPU backend for zero‑copy RDMA, so Mooncake's ``local_buffer_size`` can be ``0``.
+       - When ``save_chunk_meta: True``, Mooncake uses its own local buffer; set this to a proper value (e.g., several GiB).
+       - Note: Some RDMA NICs have memory registration limits; registering LMCache's large CPU buffer can fail on constrained devices. In those cases, consider enabling ``save_chunk_meta: True`` and sizing ``local_buffer_size`` instead.
+   * - ``transfer_timeout``
+     - 1
+     - Timeout for transfer operations in seconds
+   * - ``storage_root_dir``
+     - ""
+     - The root directory for persistence (e.g., "/mnt/mooncake")
+   * - ``save_chunk_meta``
+     - False
+     - Whether to save chunk metadata alongside data. Set to ``False`` to enable the optimized zero‑copy path in LMCache.
+   * - ``use_exists_sync``
+     - False
+     - Use synchronous existence checks to avoid async scheduling overhead in hot paths.
+   * - ``mooncake_prefer_local_alloc``
+     - False
+     - Prefer allocating on the local segment when possible.
+
+.. important::
+   **Understanding global_segment_size**: This parameter defines the amount of memory each vLLM worker contributes to the distributed memory pool. 
+   The total cluster memory available for KV cache storage will be: ``number_of_vllm_workers × global_segment_size``.
+   
+   Adjust this value based on your available system memory and expected cache requirements.
+
+.. tip::
+   If you consistently get misses (no Mooncake hits), ensure all processes use the same hashing seed: ``export PYTHONHASHSEED=0``. This keeps pre‑caching keys consistent across processes.
+
+.. note::
+   RDMA device(s) usually do not need to be specified; leaving ``device_name`` empty works for most deployments.
+
+Additional Resources
+--------------------
+
+- `Mooncake Store Architecture <https://kvcache-ai.github.io/Mooncake/design/mooncake-store.html>`_
+- `Mooncake Store Deployment Guide <https://kvcache-ai.github.io/Mooncake/deployment/mooncake-store-deployment-guide.html>`_
+- `Mooncake Store Python API Reference <https://kvcache-ai.github.io/Mooncake/python-api-reference/mooncake-store.html>`_
+- `Transfer Engine Documentation <https://kvcache-ai.github.io/Mooncake/design/transfer-engine/index.html>`_
+- `Build Instructions <https://kvcache-ai.github.io/Mooncake/getting_started/build.html>`_
+- `GitHub Repository <https://github.com/kvcache-ai/Mooncake>`_
+- `LMCache Integration Guide <https://kvcache-ai.github.io/Mooncake/getting_started/examples/lmcache-integration.html>`_
diff --git a/docs/source/kv_cache/storage_backends/nixl.rst b/docs/source/kv_cache/storage_backends/nixl.rst
new file mode 100644
index 0000000..f4063fc
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/nixl.rst
@@ -0,0 +1,275 @@
+
+Nixl
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/nixl`.
+
+
+.. _nixl-overview:
+
+Overview
+--------
+
+NIXL (NVIDIA Inference Xfer Library) is a high-performance library designed for accelerating point to point communications in AI inference frameworks. It provides an abstraction over various types of memory (CPU and GPU) and storage through a modular plug-in architecture, enabling efficient data transfer and coordination between different components of the inference pipeline.
+
+LMCache supports using NIXL as a storage backend, allowing using NIXL to save either GPU or CPU memory into storage.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- **LMCache**: Install with ``pip install lmcache``
+- **NIXL**: Install from `NIXL GitHub repository <https://github.com/ai-dynamo/nixl>`_
+- **Model Access**: Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B Instruct
+
+Ways to configure LMCache NIXL Offloading
+-----------------------------------------
+
+**Configuration File**:
+
+Passed in through ``LMCACHE_CONFIG_FILE=lmcache-config.yaml``
+
+Example ``lmcache-config.yaml`` for POSIX backend:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    nixl_buffer_device: cpu
+    local_cpu_use_hugepages: true  # optional, requires pre-allocated hugepages
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: POSIX
+      nixl_pool_size: 64
+      nixl_path: /mnt/nixl/cache/
+      use_direct_io: true
+
+Key settings:
+
+- ``nixl_buffer_size``: buffer size for NIXL transfers. **GPU mode only** (``nixl_buffer_device: cuda``). Setting this with ``nixl_buffer_device: cpu`` is a configuration error and will be rejected — in CPU mode NIXL shares ``LocalCPUBackend``'s pinned pool, which is sized by ``max_local_cpu_size``.
+
+- ``max_local_cpu_size``: size of ``LocalCPUBackend``'s pinned pool in GiB. In CPU mode, this pool is shared with NIXL and must accommodate both the hot cache and concurrent NIXL I/O in flight. Must be > 0 when ``nixl_buffer_device: cpu``. Default: ``5.0``.
+
+- ``nixl_pool_size``: number of descriptors opened at init time for nixl backend. Set to 0 for dynamic mode.
+
+- ``nixl_path``: directory (or list of directories) under which the storage files will be saved (e.g. /mnt/nixl/). Needed for NIXL backends that store to file. When using a list of paths with ``path_sharding``, paths will be selected based on the sharding strategy.
+
+- ``nixl_buffer_device``: dictates where the memory managed by NIXL should be on. "cpu" or "cuda" is supported for "GDS", "GDS_MT", and "OBJ" backends - for "POSIX", "HF3FS", "AZURE_BLOB" & "DOCA_MEMOS", must be "cpu". In CPU mode, NIXL shares ``LocalCPUBackend``'s pinned buffer; ``LocalCPUBackend`` is always created when ``nixl_buffer_device: cpu``, regardless of the ``local_cpu`` setting. ``local_cpu: false`` still suppresses hot-cache promotions — the backend acts as a staging buffer only, mirroring how ``local_disk`` already uses ``LocalCPUBackend``.
+
+- ``nixl_backend``: configuration of which nixl backend to use for storage.
+
+- ``nixl_path_sharding``: strategy for selecting path when multiple paths are provided. Currently only "by_gpu" is supported, which selects paths based on GPU device ID.
+- ``local_cpu_use_hugepages``: whether to use Linux hugepages (2 MiB) for ``LocalCPUBackend``'s pinned pool (which NIXL shares in CPU mode). Requires pre-allocated hugepages (``sysctl vm.nr_hugepages``). Default: ``false``. **Deprecated alias:** ``extra_config.nixl_use_hugepages`` — accepted with a warning and copied into this field; will be removed in a future release.
+
+.. note::
+
+    In CPU mode, the shared paged allocator consumes one full page per object. With ``save_unfull_chunk: true`` (only valid in static mode — dynamic mode rejects it; see "Dynamic Mode" → "Restrictions" below), partial chunks still occupy a full page each, so effective capacity degrades proportionally to the fraction of unfull last chunks across active sequences.
+
+.. note::
+
+    ``enable_p2p: true`` is rejected together with ``nixl_buffer_device: cpu``. The combination is structurally supported — both backends share ``LocalCPUBackend``'s pinned pool, each runs its own NIXL agent over it, and allocations route through ``LocalCPUBackend.allocate()`` — but it has not been exercised end-to-end and has no CI coverage. Use ``enable_p2p: true`` with ``nixl_buffer_device: cuda`` instead, or disable ``enable_p2p`` when running the NIXL CPU shared pool.
+
+- ``nixl_presence_cache``: whether to keep an in-DRAM presence cache of keys known to exist, so repeated existence checks for the same key are answered locally instead of via a NIXL ``query_memory`` call. Applies to the dynamic backend (``nixl_pool_size: 0``). Default: ``false``.
+
+- ``nixl_presence_cache_only``: when ``true``, the dynamic NIXL backend treats the local presence cache (and in-progress put set) as authoritative for existence checks. If a key is not known locally, lookup reports a miss **without** issuing a NIXL ``query_memory`` check. This requires ``nixl_presence_cache: true`` and can intentionally produce **false negatives** for objects that exist in the underlying storage but are absent from local presence metadata — giving "DRAM-only metadata" semantics where a process restart always yields a logically empty cache. Default: ``false``.
+
+  .. note::
+
+     This is a **lookup/existence-check** mode, not a "never touch the underlying storage" policy. It gates ``contains`` / ``batched_contains`` (and the async variant); direct retrieval still reads from the underlying storage. In normal operation a retrieval is only issued for a key that lookup already reported as present, so locally-unknown keys are not fetched. The option is only consulted by the dynamic backend (``nixl_pool_size: 0``); it is accepted but unused for static configurations.
+
+.. note::
+
+    Supported backends are: ["GDS", "GDS_MT", "POSIX", "HF3FS", "OBJ", "AZURE_BLOB", "DOCA_MEMOS"].
+
+    Backend specific params should be provided via ``extra_config.nixl_backend_params``. Please refer to NIXL documentation for specifics.
+
+Example ``lmcache-config.yaml`` for POSIX backend with multipath support:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    nixl_buffer_size: 1073741824 # 1GB
+    nixl_buffer_device: cpu
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: POSIX
+      nixl_pool_size: 64
+      nixl_path: 
+        - /mnt/nixl/cache0/
+        - /mnt/nixl/cache1/
+        - /mnt/nixl/cache2/
+      nixl_path_sharding: by_gpu
+      use_direct_io: True
+
+Example ``lmcache-config.yaml`` for OBJ backend using S3 API:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    nixl_buffer_device: cpu
+    max_local_cpu_size: 1  # GiB
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: OBJ
+      nixl_pool_size: 64
+      nixl_path: /mnt/nixl/cache/
+      nixl_backend_params:
+        access_key: <your_access_key>
+        secret_key: <your_secret_key>
+        bucket: <your_bucket>
+        region: <your_region>
+
+Example ``lmcache-config.yaml`` for POSIX backend using liburing:
+
+.. note::
+
+    using POSIX backend with liburing requires NIXL to be built with liburing support.
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    nixl_buffer_device: cpu
+    max_local_cpu_size: 1  # GiB
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: POSIX
+      nixl_pool_size: 64
+      nixl_path: /mnt/nixl/cache/
+      use_direct_io: True
+      nixl_backend_params:
+        use_uring: "true"
+
+Example ``lmcache-config.yaml`` for AZURE_BLOB backend to offload using Azure Blob Storage API:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    nixl_buffer_device: cpu
+    max_local_cpu_size: 1  # GiB
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: AZURE_BLOB
+      nixl_pool_size: 64
+      nixl_path: /mnt/nixl/cache/
+      nixl_backend_params:
+        account_url: https://<your_azure_storage_account_name>.blob.core.windows.net
+        container_name: <your_container_name>
+
+Per-Worker Endpoint Distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When using the OBJ backend with multiple tensor-parallel (TP) workers, you can
+distribute workers across multiple object-storage endpoints by providing a list of
+endpoints via ``nixl_endpoint_list``. Each worker selects an endpoint in
+round-robin order based on its ``local_worker_id`` (the worker ID within its host).
+
+.. code-block:: yaml
+
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: OBJ
+      nixl_pool_size: 64
+      nixl_path: /mnt/nixl/cache/
+      nixl_endpoint_list:
+        - https://node-0.object-storage:9021
+        - https://node-1.object-storage:9021
+        - https://node-2.object-storage:9021
+      nixl_backend_params:
+        access_key: <your_access_key>
+        secret_key: <your_secret_key>
+        bucket: <your_bucket>
+        region: <your_region>
+
+.. note::
+
+    When ``nixl_endpoint_list`` is set, any ``endpoint_override`` value in
+    ``nixl_backend_params`` is ignored (a warning is logged).
+
+    ``nixl_endpoint_list`` is only honored for the OBJ backend; it is ignored
+    for all other backends (including DOCA_MEMOS, AZURE_BLOB, and the file
+    backends).
+
+Dynamic Mode
+~~~~~~~~~~~~~
+
+Nixl Storage Backend also supports a dynamic mode, which creates nixl storage descriptors on demand instead of at init time.
+
+In order to use dynamic mode, extra_config.nixl_pool_size should be set to 0.
+
+Restrictions
+^^^^^^^^^^^^
+
+- Dynamic mode is supported for object backends ("OBJ", "AZURE_BLOB", "DOCA_MEMOS") and file backends ("POSIX", "GDS", "GDS_MT", "HF3FS").
+- save_unfull_chunk must be set to False.
+
+Example ``lmcache-config.yaml`` for OBJ backend with dynamic mode:
+
+.. code-block:: yaml
+
+  chunk_size: 256
+  local_cpu: False
+  save_unfull_chunk: False
+  enable_async_loading: False # set to True to test async loading
+  nixl_buffer_device: cpu
+  max_local_cpu_size: 3  # GiB
+  extra_config:
+    enable_nixl_storage: true
+    nixl_backend: OBJ
+    nixl_pool_size: 0
+    nixl_presence_cache: False
+    nixl_async_put: False
+    nixl_backend_params:
+      access_key: <your_access_key>
+      secret_key: <your_secret_key>
+      bucket: <your_bucket>
+      region: <your_region>
+      endpoint_override: https://url-to-object-storage
+      ca_bundle: path to self-signed certificate # remove this line if not using self-signed certificate
+
+
+Example ``lmcache-config.yaml`` for AZURE_BLOB backend with dynamic mode:
+
+.. code-block:: yaml
+
+  chunk_size: 256
+  local_cpu: False
+  save_unfull_chunk: False
+  enable_async_loading: False # set to True to test async loading
+  nixl_buffer_device: cpu
+  max_local_cpu_size: 3  # GiB
+  extra_config:
+    enable_nixl_storage: true
+    nixl_backend: AZURE_BLOB
+    nixl_pool_size: 0
+    nixl_presence_cache: False
+    nixl_async_put: False
+    nixl_backend_params:
+      account_url: https://<your_azure_storage_account_name>.blob.core.windows.net
+      container_name: <your_container_name>
+
+DOCA_MEMOS Backend (NVIDIA CMX)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``DOCA_MEMOS`` stores KV cache on NVIDIA CMX (Context Memory Storage), a
+BlueField-4 context-memory tier accessed through NIXL. It is an object-style
+backend (like ``OBJ``), supported in both static (``nixl_pool_size`` > 0) and
+dynamic (``nixl_pool_size`` = 0) mode. ``nixl_buffer_device`` must be ``cpu``.
+``nixl_endpoint_list`` is not supported for DOCA_MEMOS.
+
+Object names are 128-bit lowercase-hex strings: the NIXL DOCA_MEMOS plugin
+passes object names as strings and hex-decodes them on the device side, so
+each name is exactly 32 hex characters. In dynamic mode this name is a
+truncated SHA-256 of the cache key, so names are opaque (they carry no
+model/chunk debug information) and uniqueness is probabilistic at 128 bits.
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    nixl_buffer_device: cpu
+    max_local_cpu_size: 1  # GiB
+    extra_config:
+      enable_nixl_storage: true
+      nixl_backend: DOCA_MEMOS
+      nixl_pool_size: 64
+      nixl_backend_params:
+        # refer to NIXL DOCA_MEMOS plugin docs for connection params
diff --git a/docs/source/kv_cache/storage_backends/redis.rst b/docs/source/kv_cache/storage_backends/redis.rst
new file mode 100644
index 0000000..b5abc72
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/redis.rst
@@ -0,0 +1,455 @@
+Redis
+=====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/resp`.
+
+
+.. _redis-overview:
+
+Overview
+--------
+
+Redis is an in-memory key-value store and is a supported option for remote KV Cache offloading in LMCache.
+Some other remote backends are :doc:`Mooncake <./mooncake>`, :doc:`Valkey <./valkey>`, and :doc:`InfiniStore <./infinistore>`.
+This guide will mainly focus on single-node Redis but also shows you how to set up Redis Sentinels and an LMCache Server.
+
+Two ways to configure LMCache Redis Offloading:
+-----------------------------------------------
+
+**1. Environment Variables:**
+
+.. code-block:: bash
+
+    # 256 Tokens per KV Chunk
+    export LMCACHE_CHUNK_SIZE=256
+    # Redis host
+    export LMCACHE_REMOTE_URL="redis://your-redis-host:6379"
+    # Redis Sentinel hosts (for high availability)
+    # export LMCACHE_REMOTE_URL="redis-sentinel://localhost:26379,localhost:26380,localhost:26381"
+    # LMCache Server host
+    # export LMCACHE_REMOTE_URL="lm://localhost:65432"
+
+    # How to serialize and deserialize KV cache on remote transmission
+    export LMCACHE_REMOTE_SERDE="naive" # "naive" (default) or "cachegen"
+
+**2. Configuration File**:
+
+Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    # Redis host
+    remote_url: "redis://your-redis-host:6379"
+    # Redis Sentinel hosts (for high availability)
+    # remote_url: "redis-sentinel://localhost:26379,localhost:26380,localhost:26381"
+    # LMCache Server host
+    # remote_url: "lm://localhost:65432"
+
+    # How to serialize and deserialize KV cache on remote transmission
+    remote_serde: "naive" # "naive" (default) or "cachegen"
+
+Dynamic Plugin Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    local_cpu: true
+
+    remote_storage_plugins:
+      - "redis"
+
+    extra_config:
+      remote_storage_plugin.redis.redis_url: "redis://your-redis-host:6379"
+
+Remote Storage Explanation:
+----------------------------
+
+LMCache's backend is obeys the natural memory hierarchy of prioritizing CPU RAM offloading, then Local Storage
+offloading, and finally remote offloading.
+
+For LMCache to know how to create a connector to a remote backend, you must specify in
+``remote_url`` a connector type followed by one or most host:port pairs (depending on what connector type is used).
+If ``remote_url`` is set to ``None``, LMCache will not use any remote storage.
+
+Examples of ``remote_url``'s:
+
+.. code-block:: yaml
+
+    remote_url: "redis://your-redis-host:6379"
+    remote_url: "redis-sentinel://localhost:26379,localhost:26380,localhost:26381"
+    remote_url: "lm://localhost:65432"
+    remote_url: "infinistore://127.0.0.1:12345"
+    remote_url: "mooncakestore://127.0.0.1:50051"
+
+Remote Storage Example
+-----------------------
+
+.. _redis-prerequisites:
+
+**Prerequisites:**
+
+- A Machine with at least one GPU. You can adjust the max model length of your vllm instance depending on your GPU memory.
+
+- vllm and lmcache installed (:doc:`Installation Guide <../../getting_started/installation>`)
+
+- Hugging Face access to ``meta-llama/Meta-Llama-3.1-8B-Instruct``
+
+.. code-block:: bash
+
+    export HF_TOKEN=your_hugging_face_token
+
+**Step 0. Set up a directory for this example:**
+
+.. code-block:: bash
+
+    mkdir lmcache-redis-offload-example
+    cd lmcache-redis-offload-example
+
+**Step 1. Start a Redis server:**
+
+.. code-block:: bash
+
+    # Ubuntu / Debian Installation
+    sudo apt-get install redis
+    redis-server # starts the server on default port 6379
+
+Check if Redis is running:
+
+.. code-block:: bash
+
+    redis-cli ping
+
+Expected Response:
+
+.. code-block:: text
+
+    PONG
+
+**Optional: Setting up Sentinels:**
+
+To enable high availability with Redis, you can configure Redis sentinels to
+monitor the master and automatically fail over to a replica if needed.
+
+**Step 1a. Start a Redis replica:**
+
+.. code-block:: bash
+
+    redis-server --port 6380 --replicaof 127.0.0.1 6379
+
+**Step 1b. Create Sentinel configuration files:**
+
+Create three files: ``sentinel-26379.conf``, ``sentinel-26380.conf``, and ``sentinel-26381.conf``, with contents like this:
+
+.. code-block:: ini
+
+    port 26379  # Use 26380 and 26381 in other files respectively
+    sentinel monitor mymaster 127.0.0.1 6379 1
+    sentinel down-after-milliseconds mymaster 5000
+    sentinel failover-timeout mymaster 10000
+    sentinel parallel-syncs mymaster 1
+
+**Step 1c. Start each Sentinel:**
+
+.. code-block:: bash
+
+    redis-server sentinel-26379.conf --sentinel
+    redis-server sentinel-26380.conf --sentinel
+    redis-server sentinel-26381.conf --sentinel
+
+**Step 1d. Make sure the Sentinels are tracking the master:**
+
+.. code-block:: bash
+
+    redis-cli -p 26379 sentinel master mymaster
+    redis-cli -p 26380 sentinel master mymaster
+    redis-cli -p 26381 sentinel master mymaster
+
+**Step 1e. Verify everything is running:**
+
+.. code-block:: bash
+
+    ps aux | grep redis
+
+You should see something like this (without the comments):
+
+.. code-block:: text
+
+    # Master (read-write)
+    user      60816  0.1  0.0  69804 11132 ?        Sl   04:11   0:00 redis-server *:6379
+    # Replica (read-only mirror of 6379)
+    user      60903  0.1  0.0  80048 10928 ?        Sl   04:12   0:00 redis-server *:6380
+    # Sentinels (monitor the master and hold quorums to decide when to failover)
+    user      61301  0.1  0.0  67244 10944 ?        Sl   04:14   0:00 redis-server *:26379 [sentinel]
+    user      61382  0.1  0.0  67244 10944 ?        Sl   04:14   0:00 redis-server *:26380 [sentinel]
+    user      61462  0.1  0.0  67244 10944 ?        Sl   04:15   0:00 redis-server *:26381 [sentinel]
+
+
+**Alternative: Starting an LMCache Server:**
+
+The ``lmcache_server`` CLI entrypoint starts a remote LMCache server and comes with
+the ``lmcache`` package.
+
+.. code-block:: bash
+
+    lmcache_server <host> <port> <device>
+
+    lmcache_server localhost 65432
+
+Currently, the only supported device is "cpu" (which is the default, so you don't need to specify it).
+
+
+**Step 2. Start a vLLM server with remote offloading enabled:**
+
+Create a an lmcache configuration file called: ``redis-offload.yaml``
+
+.. code-block:: yaml
+
+    # disabling CPU RAM offload not recommended (on by default) but
+    # if you want to confirm that the remote backend works by itself
+    # local_cpu: false
+    chunk_size: 256
+    remote_url: "redis://localhost:6379"
+    remote_serde: "naive"
+
+If you don't want to use a config file, uncomment the first three environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # disabling CPU RAM offload not recommended (on by default) but
+    # if you want to confirm that the remote backend works by itself
+    # LMCACHE_LOCAL_CPU=False \
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_REMOTE_URL="redis://localhost:6379" \
+    # LMCACHE_REMOTE_SERDE="naive"
+    LMCACHE_CONFIG_FILE="redis-offload.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 16384 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+**Optional: Sentinels**
+
+Create a an lmcache configuration file called: ``redis-sentinel-offload.yaml``
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    remote_url: "redis-sentinel://localhost:26379,localhost:26380,localhost:26381"
+    remote_serde: "naive"
+
+If you don't want to use a config file, uncomment the first three environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_REMOTE_URL="redis-sentinel://localhost:26379,localhost:26380,localhost:26381" \
+    # LMCACHE_REMOTE_SERDE="naive"
+    LMCACHE_CONFIG_FILE="redis-sentinel-offload.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 16384 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+**Alternative: LMCache Server**
+
+Create a an lmcache configuration file called: ``lmcache-server-offload.yaml``
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    remote_url: "lm://localhost:65432"
+    remote_serde: "naive"
+
+If you don't want to use a config file, uncomment the first three environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_REMOTE_URL="lm://localhost:65432" \
+    # LMCACHE_REMOTE_SERDE="naive"
+    LMCACHE_CONFIG_FILE="lmcache-server-offload.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 16384 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+**Step 3. Viewing and Managing LMCache Entries in Redis:**
+
+If you would like to feel the TTFT speed up with offloading and KV Cache reuse, feel free to use the same
+``query-twice.py`` script and ``man-bash.txt`` long context as in :doc:`CPU RAM <./cpu_ram>` and :doc:`Local Storage <./local_storage>`.
+
+Here, we are instead going to demonstrate how to search for and modify LMCache KV Chunk entries in Redis.
+
+Please note that the official LMCache way to achieve this redis-specific functionality of viewing and modifying LMCache KV Chunks is available in :doc:`LMCache Controller <../../kv_cache_management/index>`.
+
+Let's warm/populate LMCache first with ``curl`` this time:
+
+.. code-block:: bash
+
+    curl -X 'POST' \
+    'http://127.0.0.1:8000/v1/chat/completions' \
+    -H 'accept: application/json' \
+    -H 'Content-Type: application/json' \
+    -d '{
+        "model": "meta-llama/Llama-3.1-8B-Instruct",
+        "messages": [
+        {"role": "system", "content": "You are a helpful AI coding assistant."},
+        {"role": "user", "content": "Write a segment tree implementation in python"}
+        ],
+        "max_tokens": 150
+    }'
+
+LMCache stores data in Redis using a structured key format. Each key contains the following information in a delimited format:
+
+.. code-block:: text
+
+    model_name@world_size@worker_id@chunk_hash
+
+- `model_name`: Name of the language model
+- `world_size`: Total number of workers in distributed deployment
+- `worker_id`: ID of the worker that created this cache entry, in the range of [0, world_size - 1]
+- `chunk_hash`: Hash of the token chunk (SHA-256 based)
+
+For example, a typical key might look like:
+
+.. code-block:: text
+
+    vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@a1b2c3d4e5f6...
+
+**Using redis-cli to View LMCache Data**
+
+To inspect and manage LMCache entries in Redis:
+
+.. code-block:: bash
+
+    redis-cli -h localhost -p 6379
+
+**Optional: If you are using sentinels, first find the master port:**
+
+.. code-block:: bash
+
+    redis-cli -p 26379 sentinel get-master-addr-by-name mymaster
+    redis-cli -h localhost -p <master-port>
+
+
+**List LMCache keys:**
+
+Notice (from the suffixes of the keys) that each LMCache KV Chunk has two entries: ``kv_bytes`` and ``metadata``
+
+.. code-block:: bash
+
+    # Show all keys
+    localhost:6379> KEYS *
+    1) "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...kv_bytes"
+    2) "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...metadata"
+    # Show keys for a specific model
+    localhost:6379> KEYS *Llama-3.1-8B-Instruct*
+    1) "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...kv_bytes"
+    2) "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...metadata"
+
+**Delete LMCache entries:**
+
+.. code-block:: bash
+
+    localhost:6379> DEL *
+
+Delete a specific LMCache entry:
+
+.. code-block:: bash
+
+    localhost:6379> DEL "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...kv_bytes"
+    localhost:6379> KEYS *
+    1) "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...metadata"
+
+
+**Check if a key exists:**
+
+.. code-block:: bash
+
+    localhost:6379> EXISTS "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...kv_bytes"
+
+**View memory usage for a key:**
+
+Notice that the ``kv_bytes`` entry is what is exactly holding the KV Chunk and is much
+larger than the ``metadata`` entry.
+
+.. code-block:: bash
+
+    localhost:6379> MEMORY USAGE "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...metadata"
+    (integer) 198
+    localhost:6379> MEMORY USAGE "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...kv_bytes"
+    (integer) 7340200
+
+**Delete specific keys:**
+
+.. code-block:: bash
+
+    # Delete a single key
+    localhost:6379> DEL "vllm@meta-llama/Llama-3.1-8B-Instruct@1@0@02783dafec...kv_bytes"
+
+.. code-block:: bash
+
+    # Delete all keys matching a pattern
+    redis-cli -h localhost -p 6379 --scan --pattern "vllm@meta-llama/Llama-3.1-8B-Instruct*" \
+        | xargs redis-cli -h localhost -p 6379 DEL
+
+
+**Monitor Redis in real-time:**
+
+.. code-block:: bash
+
+    localhost:6379> MONITOR
+
+**Get Redis stats for LMCache:**
+
+.. code-block:: bash
+
+    # Get memory stats
+    localhost:6379> INFO memory
+
+    # Get statistics about operations
+    localhost:6379> INFO stats
+
+This tutorial utilized the ``redis-cli`` to directly peak into a remote backend and manipualte
+KV Chunks.
+
+Once again, please refer to the :doc:`LMCache Controller <../../kv_cache_management/index>`
+for the official LMCache way of controlling and routing your KV Caches in your LMCache instances.
+
+**Step 4. Clean up:**
+
+.. code-block:: bash
+
+    redis-cli shutdown
+
+    # Optional:
+
+    # Shut down the Redis replica (if started)
+    redis-cli -p 6380 shutdown
+
+    # Shut down all Redis Sentinels (if started)
+    redis-cli -p 26379 shutdown
+    redis-cli -p 26380 shutdown
+    redis-cli -p 26381 shutdown
+
+    # (Optional) Remove temporary files or configs
+    rm -f sentinel-26379.conf sentinel-26380.conf sentinel-26381.conf
+
+    # Confirm no Redis processes are still running
+    ps aux | grep redis
+
+
diff --git a/docs/source/kv_cache/storage_backends/resp.rst b/docs/source/kv_cache/storage_backends/resp.rst
new file mode 100644
index 0000000..3ac5b28
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/resp.rst
@@ -0,0 +1,456 @@
+RESP (Native Redis/Valkey)
+==========================
+
+.. _resp-overview:
+
+Overview
+--------
+
+The RESP backend is a high-performance native C++ storage connector for Redis and Valkey servers,
+using the RESP2 wire protocol over TCP. It is designed for maximum throughput on KV cache
+store and retrieval operations, achieving **6+ GB/s** on reads with optimal configuration.
+
+Key advantages over the standard Redis connector:
+
+- **Multi-threaded C++ I/O**: Worker threads operate in parallel with zero-copy buffer passing and full GIL release
+- **Batched tiling**: Large batch operations are automatically split across worker threads for maximum parallelism
+- **eventfd-based completions**: The kernel wakes Python on completion -- no polling overhead
+- **Dual-mode support**: The same C++ connector works in both non-MP mode (via ``ConnectorClientBase``) and MP mode (via ``NativeConnectorL2Adapter`` as an L2 adapter)
+
+The native C++ source lives in ``csrc/storage_backends/redis/``. See :doc:`Adding Native Connectors <../../developer_guide/extending_lmcache/native_connectors>` for the full architecture.
+
+
+Prerequisites
+-------------
+
+- LMCache installed from source (``pip install -e .``) to compile the C++ extension
+- A Redis 8.2+ or Valkey server (Redis 8.2 recommended for IO threads support)
+- A machine with at least one GPU for vLLM inference
+
+
+Redis Server Setup
+------------------
+
+.. important::
+   Redis version and server configuration have a **major** impact on throughput.
+   Using Redis 8.2 with IO threads yields ~6 GB/s reads vs ~1.5 GB/s with Redis 6.0 defaults.
+
+**Build Redis 8.2 from source (recommended):**
+
+.. code-block:: bash
+
+    git clone https://github.com/redis/redis.git
+    cd redis
+    git checkout 8.2
+    make -j
+
+**Start the server with IO threads enabled:**
+
+.. code-block:: bash
+
+    ./src/redis-server \
+        --protected-mode no \
+        --save '' \
+        --appendonly no \
+        --io-threads 4 \
+        --port 6379
+
+.. list-table:: Recommended Server Flags
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Flag
+     - Why
+   * - ``--protected-mode no``
+     - Allow connections from other hosts (use auth in production)
+   * - ``--save '' --appendonly no``
+     - Disable persistence -- KV cache is ephemeral, persistence wastes bandwidth
+   * - ``--io-threads 4``
+     - Enable multi-threaded I/O for parallel read/write handling
+   * - ``--port 6379``
+     - Default port (adjust if running multiple instances)
+
+.. tip::
+   The number of ``--io-threads`` should roughly match the number of physical cores
+   available to the Redis process. 4 is a good starting point; benchmark with your
+   hardware to find the optimum.
+
+
+Chunk Size Selection and Throughput Tuning
+------------------------------------------
+
+The chunk size (in tokens) determines how many bytes each Redis key-value pair holds.
+This is the **single most important parameter** for throughput.
+
+**The sweet spot is ~4 MB per chunk.** Both smaller and larger chunks degrade throughput:
+
+.. list-table:: Chunk Size vs Throughput (Redis 8.2, 8 workers)
+   :header-rows: 1
+   :widths: 20 20 20 20
+
+   * - Chunk Size
+     - Total Data
+     - SET Throughput
+     - GET Throughput
+   * - 1 MB (500 keys)
+     - 500 MB
+     - ~3.5 GB/s
+     - ~5.2 GB/s
+   * - **4 MB (500 keys)**
+     - **2 GB**
+     - **~4.4 GB/s**
+     - **~5.9 GB/s**
+   * - 8 MB (200 keys)
+     - 1.6 GB
+     - ~4.2 GB/s
+     - ~1.4 GB/s
+
+**Why 4 MB?**
+
+- Below ~2 MB, per-key overhead (RESP framing, TCP round-trips) dominates
+- Above ~4 MB, Redis server-side memory allocation and TCP window sizes become bottlenecks
+- At 4 MB, the balance between amortized overhead and memory pressure is optimal
+
+**Calculating chunk size in tokens:**
+
+The chunk size in bytes depends on the model's hidden dimension, number of KV heads,
+number of layers, and dtype:
+
+.. code-block:: text
+
+    bytes_per_token = 2 * num_kv_heads * head_dim * num_layers * dtype_bytes
+
+For ``meta-llama/Llama-3.1-8B-Instruct`` with BFloat16:
+
+.. code-block:: text
+
+    bytes_per_token = 2 * 8 * 128 * 32 * 2 = 131,072 bytes (~128 KB)
+    chunk_size_tokens = 4 MB / 128 KB = 32 tokens
+
+    # But typically chunk_size is set as token count in config:
+    chunk_size: 16   # ~2 MB per chunk (conservative)
+    chunk_size: 32   # ~4 MB per chunk (optimal for throughput)
+
+.. note::
+   The bytes-per-token calculation varies by model architecture. Larger models
+   (e.g., 70B) have more layers and larger hidden dimensions, so fewer tokens
+   are needed per chunk to reach the 4 MB sweet spot.
+
+
+Throughput Sweep
+~~~~~~~~~~~~~~~~
+
+To find the optimal configuration for your hardware, use the included benchmark:
+
+.. code-block:: bash
+
+    cd examples/kv_cache_reuse/remote_backends/resp
+
+    # Sweep chunk sizes
+    for mb in 0.5 1 2 4 8; do
+        echo "=== Chunk: ${mb} MB ==="
+        python benchmark_resp_client.py \
+            --host 127.0.0.1 --port 6379 \
+            --chunk-mb $mb --num-workers 8 --num-keys 500
+    done
+
+    # Sweep worker counts
+    for w in 1 2 4 8 16; do
+        echo "=== Workers: $w ==="
+        python benchmark_resp_client.py \
+            --host 127.0.0.1 --port 6379 \
+            --chunk-mb 4 --num-workers $w --num-keys 500
+    done
+
+Expected output:
+
+.. code-block:: text
+
+    Redis RESP Client Benchmark
+    Server: 127.0.0.1:6379, Workers: 8
+    Chunk size: 4096KB, Keys: 500
+    ------------------------------------------------------------
+    Batch SET:      4.36 GB/s  (1.95 GB written)
+    Batch GET:      5.91 GB/s  (1.95 GB read)
+    Batch EXISTS: 143528 ops/s  (500/500 hits)
+    ------------------------------------------------------------
+    All tests passed
+
+
+Environment Variable Configuration
+------------------------------------
+
+Sensitive credentials (and optionally host/port) can be provided via environment
+variables instead of config files or CLI arguments. This prevents secrets from
+appearing in logged configuration at startup.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Variable
+     - Description
+   * - ``LMCACHE_RESP_USERNAME``
+     - Redis ACL username. Used as default when ``username`` is not set in config/JSON.
+   * - ``LMCACHE_RESP_PASSWORD``
+     - Redis AUTH password. Used as default when ``password`` is not set in config/JSON.
+   * - ``LMCACHE_RESP_HOST``
+     - Redis hostname or IP. Used as default when ``host`` is not set in config/JSON/URL.
+   * - ``LMCACHE_RESP_PORT``
+     - Redis port. Used as default when ``port`` is not set in config/JSON/URL.
+
+Config files (non-MP) and ``--l2-adapter`` JSON (MP) take precedence over
+environment variables. Environment variables serve as defaults — they are used
+when the corresponding config value is empty or unset. They are read at adapter
+creation time inside the adapter itself, so they are **never stored in the
+config object** and **never printed in startup logs**.
+
+**Example — MP mode with env vars:**
+
+.. code-block:: bash
+
+    export LMCACHE_RESP_USERNAME="default"
+    export LMCACHE_RESP_PASSWORD="secret"
+
+    lmcache server \
+        --l1-size-gb 10 \
+        --eviction-policy LRU \
+        --chunk-size 16 \
+        --l2-adapter '{"type": "resp", "host": "localhost", "port": 6379, "num_workers": 8}' \
+        --port 6555
+
+**Example — Non-MP mode with env vars:**
+
+.. code-block:: bash
+
+    export LMCACHE_RESP_USERNAME="default"
+    export LMCACHE_RESP_PASSWORD="secret"
+
+    LMCACHE_CONFIG_FILE=resp-config.yaml \
+    vllm serve meta-llama/Llama-3.1-8B-Instruct \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+        --no-enable-prefix-caching \
+        --load-format dummy
+
+.. tip::
+   For production deployments, always use environment variables for credentials
+   rather than embedding them in config files or CLI arguments.
+
+
+Non-MP Mode (Single Process)
+-----------------------------
+
+In non-MP mode, the RESP connector is used directly as a remote storage backend
+via the ``RESPClient`` asyncio wrapper.
+
+**Configuration file** (``resp-config.yaml``):
+
+.. code-block:: yaml
+
+    chunk_size: 16
+    remote_url: "resp://localhost:6379"
+    remote_serde: "naive"
+
+Credentials can be set via environment variables (recommended) or in the config file
+under ``extra_config`` (see `Environment Variable Configuration`_ above).
+
+**Launch vLLM:**
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE=resp-config.yaml \
+    vllm serve meta-llama/Llama-3.1-8B-Instruct \
+        --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+        --no-enable-prefix-caching \
+        --load-format dummy
+
+.. note::
+   ``save_unfull_chunk`` must be off (default) and chunk metadata saving must be
+   disabled for optimal throughput with the native RESP connector.
+
+
+MP Mode (Multiprocess)
+-----------------------
+
+In MP mode, LMCache runs as a separate server process communicating with vLLM over
+ZMQ. The RESP connector serves as an L2 adapter with variable-size chunk support.
+
+**Step 1: Start Redis** (see `Redis Server Setup`_ above)
+
+**Step 2: Launch LMCache MP Server:**
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 10 \
+        --eviction-policy LRU \
+        --chunk-size 16 \
+        --l2-adapter '{"type": "resp", "host": "localhost", "port": 6379, "num_workers": 8}' \
+        --port 6555
+
+**Step 3: Launch vLLM with LMCache MP Connector:**
+
+.. code-block:: bash
+
+    PORT=8000
+    vllm serve meta-llama/Llama-3.1-8B-Instruct \
+        --kv-transfer-config '{
+            "kv_connector": "LMCacheMPConnector",
+            "kv_role": "kv_both",
+            "kv_connector_extra_config": {
+                "lmcache.mp.host": "tcp://localhost",
+                "lmcache.mp.port": 6555
+            }
+        }' \
+        --no-enable-prefix-caching \
+        --port $PORT \
+        --load-format dummy
+
+
+L2 Adapter Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``--l2-adapter`` JSON accepts these fields:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 10 10 60
+
+   * - Field
+     - Type
+     - Default
+     - Description
+   * - ``type``
+     - str
+     - (required)
+     - Must be ``"resp"``
+   * - ``host``
+     - str
+     - (required)
+     - Redis/Valkey hostname or IP
+   * - ``port``
+     - int
+     - (required)
+     - Redis/Valkey port
+   * - ``num_workers``
+     - int
+     - 8
+     - C++ worker threads for parallel I/O
+   * - ``username``
+     - str
+     - ``""``
+     - Redis ACL username (leave empty for no auth). Falls back to ``LMCACHE_RESP_USERNAME`` env var if empty.
+   * - ``password``
+     - str
+     - ``""``
+     - Redis AUTH password (leave empty for no auth). Falls back to ``LMCACHE_RESP_PASSWORD`` env var if empty.
+   * - ``max_capacity_gb``
+     - float
+     - 0
+     - Maximum L2 storage capacity in GB for client-side usage tracking. Required for L2 eviction. Set to 0 (default) to disable usage tracking.
+
+L2 Eviction
+~~~~~~~~~~~~
+
+To enable automatic eviction of least-recently-used keys when the Redis backend fills up,
+set ``max_capacity_gb`` and add an ``"eviction"`` block:
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 10 \
+        --eviction-policy LRU \
+        --chunk-size 16 \
+        --l2-adapter '{
+            "type": "resp",
+            "host": "localhost",
+            "port": 6379,
+            "num_workers": 8,
+            "max_capacity_gb": 10,
+            "eviction": {
+                "eviction_policy": "LRU",
+                "trigger_watermark": 0.8,
+                "eviction_ratio": 0.2
+            }
+        }' \
+        --port 6555
+
+This configures a 10 GB capacity limit. When usage exceeds 80% (``trigger_watermark``),
+the eviction controller will delete the least-recently-used ~20% of stored keys
+(``eviction_ratio``) using the Redis ``DEL`` command.
+
+.. note::
+   ``max_capacity_gb`` enables **client-side** size tracking. It does not configure
+   the Redis server's ``maxmemory`` setting. You should set ``max_capacity_gb`` to
+   match or be slightly below your Redis server's available memory.
+
+
+Testing the Setup
+------------------
+
+Send the same prompt twice. The first request stores KV cache to Redis; the second retrieves it.
+
+.. code-block:: bash
+
+    PORT=8000
+    PROMPT="$(printf 'Elaborate the significance of KV cache in language models. %.0s' {1..1000})"
+
+    # First request: store
+    curl -s -X POST http://localhost:${PORT}/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{"model":"meta-llama/Llama-3.1-8B-Instruct","prompt":"'"$PROMPT"'","max_tokens":10}'
+
+    # Second request with same prefix: retrieve from Redis
+    curl -s -X POST http://localhost:${PORT}/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{"model":"meta-llama/Llama-3.1-8B-Instruct","prompt":"'"$PROMPT"'","max_tokens":10}'
+
+Verify data was stored:
+
+.. code-block:: bash
+
+    redis-cli -p 6379 DBSIZE
+
+Clear state between runs:
+
+.. code-block:: bash
+
+    redis-cli -p 6379 FLUSHALL
+
+
+Best Practices
+--------------
+
+**Server deployment:**
+
+- Use Redis 8.2+ with ``--io-threads 4`` (or more, matching available cores)
+- Disable persistence (``--save '' --appendonly no``) for KV cache workloads
+- Pin Redis to its own NUMA node if running on multi-socket systems
+- For production, enable authentication with ``--requirepass`` and supply credentials via ``LMCACHE_RESP_USERNAME`` / ``LMCACHE_RESP_PASSWORD`` environment variables to keep them out of logs
+
+**Client tuning:**
+
+- Start with ``num_workers: 8`` and increase if the server has spare CPU and you're not saturating the network
+- More workers help when chunk sizes are smaller (more keys per batch = more parallelism needed)
+- On NUMA systems, ensure the LMCache process runs on the same NUMA node as the NIC
+
+**Chunk size:**
+
+- Target ~4 MB per chunk for maximum throughput
+- Calculate the token count using your model's per-token byte size (see formula above)
+- If unsure, run the benchmark sweep to find the optimum for your specific hardware
+
+**Network:**
+
+- Use localhost or loopback for single-machine deployments
+- For cross-machine setups, ensure low-latency networking (ideally <100 us RTT)
+- The RESP connector uses TCP; RDMA is not currently supported (consider :doc:`Mooncake <./mooncake>` for RDMA)
+
+
+Additional Resources
+--------------------
+
+- Benchmark script: ``examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py``
+- C++ source: ``csrc/storage_backends/redis/``
+- Native connector architecture: ``csrc/storage_backends/README.md``
+- Developer guide for adding new native connectors: :doc:`Adding Native Connectors <../../developer_guide/extending_lmcache/native_connectors>`
diff --git a/docs/source/kv_cache/storage_backends/s3.rst b/docs/source/kv_cache/storage_backends/s3.rst
new file mode 100644
index 0000000..12670dd
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/s3.rst
@@ -0,0 +1,155 @@
+S3 Backend
+==========
+
+Example Configurations
+----------------------
+
+Basic S3 Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: False
+   save_unfull_chunk: False
+   remote_url: "s3://your-bucket-name"
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+   extra_config:
+     s3_region: "us-east-1"
+     s3_num_io_threads: 64
+     save_chunk_meta: False
+
+S3 Express One Zone
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: False
+   save_unfull_chunk: False
+   remote_url: "s3://{BUCKET_NAME}.s3express-{AZ_ID}.{REGION}.amazonaws.com"
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+   extra_config:
+     save_chunk_meta: False
+     s3_num_io_threads: 64
+     s3_prefer_http2: True
+     s3_region: "{REGION}"
+     s3_enable_s3express: True
+
+CoreWeave (S3-compatible)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: False
+   max_local_cpu_size: 50
+   save_unfull_chunk: False
+   enable_async_loading: True
+   remote_url: "s3://test-127.cwlota.com"
+   remote_serde: "naive"
+   blocking_timeout_secs: 10
+   extra_config:
+     s3_num_io_threads: 320
+     s3_prefer_http2: False
+     s3_region: "US-WEST-04A"
+     s3_enable_s3express: False
+     save_chunk_meta: False
+     disable_tls: True
+     aws_access_key_id: "your-access-key-id"
+     aws_secret_access_key: "your-secret-access-key"
+
+**Note**: `cwlota.com` is CoreWeave's S3-compatible Cloud Storage that caches for GPU locality. You can set `disable_tls: True` for non-AWS services.
+
+Check out the blog post between LMCache, Cohere, and CoreWeave: https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/
+
+
+Configuration Parameters
+------------------------
+
+* **remote_url**: S3 bucket URL (`s3://bucket-name`)
+* **save_unfull_chunk**: Save partial chunks (default: False, **must be False for S3**)
+* **enable_async_loading**: Async loading (default: False)
+* **blocking_timeout_secs**: Timeout seconds (default: 10)
+
+S3-Specific (in extra_config)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* **s3_region**: AWS region for S3 client (required)
+* **s3_num_io_threads**: Number of IO threads for the AWS CRT client to spawn. Benefits taper out after exceeding the number of CPU cores. This is also a way to restrict the number of outgoing requests in case your S3-compatible object store has a rate-limiting gateway.
+* **s3_prefer_http2**: Enable HTTP/2 with ALPN negotiation (["h2", "http/1.1"])
+* **s3_enable_s3express**: Enable S3 Express One Zone support in AWS CRT client
+* **save_chunk_meta**: Whether to save chunk metadata in the object store along with your data (False required for S3)
+* **aws_access_key_id**: AWS access key ID (or log in with `aws configure` in your environment)
+* **aws_secret_access_key**: AWS secret access key (or log in with `aws configure` in your environment)
+
+**Tips:**::
+
+- Use same region for compute and S3
+
+- Consider S3 Express One Zone for less redundancy but better performance
+
+
+MP Mode Configuration
+---------------------
+
+In multi-process (MP) mode, S3 is configured as an L2 adapter via a JSON
+spec passed to the LMCache server, rather than through ``remote_url`` +
+``extra_config``. Each ``--l2-adapter`` argument takes a JSON object
+whose ``"type": "s3"`` field selects the S3 adapter.
+
+.. code-block:: json
+
+   {
+     "type": "s3",
+     "s3_endpoint": "s3://my-bucket",
+     "s3_region": "us-east-1",
+     "s3_num_io_threads": 64,
+     "s3_prefer_http2": true,
+     "s3_enable_s3express": false,
+     "disable_tls": false,
+     "max_capacity_gb": 500,
+     "eviction": {
+       "eviction_policy": "LRU",
+       "trigger_watermark": 0.85,
+       "eviction_ratio": 0.2
+     }
+   }
+
+S3 L2 Adapter Fields
+~~~~~~~~~~~~~~~~~~~~
+
+* **type** (required): must be ``"s3"``.
+* **s3_endpoint** (required): bucket URL. Accepts either ``s3://bucket`` or
+  the bare host form (e.g. ``bucket.s3.us-east-1.amazonaws.com``).
+* **s3_region** (required): AWS region for the S3 client.
+* **s3_num_io_threads**: number of CRT IO threads (default ``64``).
+* **s3_prefer_http2**: attempt HTTP/2 via ALPN negotiation (default ``true``).
+* **s3_enable_s3express**: enable S3 Express One Zone signing (default ``false``).
+* **disable_tls**: bypass TLS, for non-AWS HTTP endpoints (default ``false``).
+* **aws_access_key_id**, **aws_secret_access_key**: optional static credentials.
+  When omitted the adapter uses the AWS default credentials chain
+  (``aws configure``, environment variables, IRSA, etc.).
+* **max_capacity_gb**: capacity used by ``get_usage()`` for watermark-based
+  L2 eviction. Set to ``0`` (default) to disable usage tracking — ``get_usage()``
+  then returns ``(-1.0, -1.0)`` and no automatic eviction is triggered.
+* **eviction**: optional sub-dict enabling the L2 eviction controller for
+  this adapter. See :class:`L2AdapterConfigBase` ``_parse_eviction_config``
+  for the full schema. When present, keys that are currently being loaded
+  (reference-counted by the lookup-and-lock path) are skipped by
+  ``delete()``.
+
+Differences vs Non-MP S3
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* The MP adapter honors first-class eviction: it implements ``delete()``
+  (real S3 ``DeleteObject``), refcounted ``submit_unlock``, and
+  ``get_usage()`` driven by ``max_capacity_gb``.
+* Keys are identified by ``ObjectKey`` (``model_name`` + ``kv_rank`` +
+  ``chunk_hash``) rather than ``CacheEngineKey``. The wire-format object
+  name is ``<model>@<kv_rank_hex>@<chunk_hash_hex>``, which is **not**
+  compatible with the non-MP naming. A bucket populated by non-MP LMCache
+  cannot be read directly by MP LMCache and vice versa.
+* Unfull chunks are rejected (same constraint as non-MP).
\ No newline at end of file
diff --git a/docs/source/kv_cache/storage_backends/sagemaker_hyperpod.rst b/docs/source/kv_cache/storage_backends/sagemaker_hyperpod.rst
new file mode 100644
index 0000000..25098b4
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/sagemaker_hyperpod.rst
@@ -0,0 +1,76 @@
+SageMaker Hyperpod
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+Prerequisites
+-------------
+
+Create an Amazon SageMaker HyperPod cluster with tiered storage enabled by following the instructions at:
+
+https://docs.aws.amazon.com/sagemaker/latest/dg/managed-tier-checkpointing-setup.html
+
+This enables the ai-toolkit daemon that provides shared memory access for LMCache.
+
+Example Configuration
+---------------------
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: True
+   max_local_cpu_size: 5
+   remote_url: "sagemaker-hyperpod://$NODE_IP:9200"
+
+Configuration Parameters
+------------------------
+
+SageMaker Hyperpod-Specific (in extra_config)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* **sagemaker_hyperpod_bucket**: Bucket name for KV storage namespace (default: "lmcache")
+* **sagemaker_hyperpod_shared_memory_name**: Name of shared memory segment (default: "shared_memory"). Set to None to disable shared memory.
+* **sagemaker_hyperpod_max_concurrent_requests**: Maximum concurrent HTTP requests allowed in-flight at any moment (application-level throttling, default: 100, minimum: 1). This limit is per LMCache engine instance. With multiple workers (e.g., high TP), each worker creates its own engine with separate limits.
+* **sagemaker_hyperpod_max_connections**: Maximum total TCP connections in the connection pool per LMCache engine across all daemons (default: 256, minimum: 1). For typical single-daemon setups, this effectively limits connections from one engine to one daemon. With N workers per node, total connections to the daemon = N × this value.
+* **sagemaker_hyperpod_max_connections_per_host**: Maximum TCP connections per LMCache engine to a single daemon address (IP:port) (default: 128, minimum: 1). "Host" refers to the daemon's network address, not the client machine. For today's typical single-daemon setup, this has similar effect as max_connections. This parameter enables future multi-daemon configurations where one engine connects to multiple daemons for load balancing. With N workers per node connecting to the same daemon, total connections = N × this value. Reduce proportionally for high TP setups (e.g., set to 16 for 8 workers to achieve ~128 total connections).
+* **sagemaker_hyperpod_timeout_ms**: Timeout for lease acquisition requests in milliseconds (default: 5000, minimum: 100)
+* **sagemaker_hyperpod_lease_ttl_s**: Server-side lease timeout in seconds (default: 30.0)
+* **sagemaker_hyperpod_put_stream_chunk_bytes**: Chunk size for streaming PUT requests in bytes (default: 65536, minimum: 1024)
+* **sagemaker_hyperpod_use_https**: Enable HTTPS instead of HTTP (default: False). **Note**: Ignored if ``remote_url`` already contains ``http://`` or ``https://`` protocol.
+* **save_chunk_meta**: Whether to save chunk metadata with data (set False for performance)
+
+Kubernetes Deployment Requirements
+-----------------------------------
+
+Environment Variable for Node IP
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add the ``NODE_IP`` environment variable to resolve the local node's IP address:
+
+.. code-block:: yaml
+
+   env:
+     - name: NODE_IP
+       valueFrom:
+         fieldRef:
+           fieldPath: status.hostIP
+
+/dev/shm Volume Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SageMaker Hyperpod requires /dev/shm for high-performance shared memory operations:
+
+.. code-block:: yaml
+
+   volumeMounts:
+     - name: dshm
+       mountPath: /dev/shm/shared_memory
+       subPath: shared_memory
+
+   volumes:
+     - name: dshm
+       hostPath:
+         path: /dev/shm
diff --git a/docs/source/kv_cache/storage_backends/valkey.rst b/docs/source/kv_cache/storage_backends/valkey.rst
new file mode 100644
index 0000000..f1b23d9
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/valkey.rst
@@ -0,0 +1,205 @@
+Valkey
+======
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/resp`.
+
+
+Overview
+--------
+
+Valkey is an open source (BSD) high-performance key/value datastore and is a supported option for remote KV Cache offloading in LMCache.
+Some other remote backends are :doc:`Mooncake <./mooncake>`, :doc:`Redis <./redis>`, and :doc:`InfiniStore <./infinistore>`.
+
+Prerequisites
+-------------
+
+To use this connector, you need valkey-glide 2.0 or higher.
+
+.. code-block:: shell
+
+    # Install Valkey-GLIDE (Minimum 2.0.0 or higher)
+    $ pip install valkey-glide
+
+Configuration Reference
+-----------------------
+
+The following ``extra_config`` keys are supported:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Key
+     - Default
+     - Description
+   * - ``valkey_num_workers``
+     - ``8``
+     - Number of worker threads, each with its own GLIDE client connection.
+   * - ``valkey_mode``
+     - ``"standalone"``
+     - ``"standalone"`` or ``"cluster"``. Cluster mode auto-discovers topology from a seed node.
+   * - ``tls_enable``
+     - ``false``
+     - Enable TLS. Required for ElastiCache Serverless.
+   * - ``valkey_username``
+     - ``""``
+     - Authentication username.
+   * - ``valkey_password``
+     - ``""``
+     - Authentication password.
+   * - ``valkey_database``
+     - None
+     - Database ID (standalone mode only, ignored in cluster mode).
+   * - ``valkey_enable_ttl``
+     - ``false``
+     - Feature flag. When ``true``, every key is written with an expiry (see ``valkey_ttl_sec``) so Valkey/Redis ``volatile-*`` eviction policies can reclaim L2 cache keys once the node reaches ``maxmemory``. When ``false`` (default), keys are persisted without a TTL.
+   * - ``valkey_ttl_sec``
+     - ``86400``
+     - Key TTL in seconds, applied only when ``valkey_enable_ttl`` is ``true``. Must be a positive integer. If the flag is enabled but this key is omitted, it defaults to ``86400`` (24 hours).
+   * - ``request_timeout``
+     - ``5.0``
+     - GLIDE request timeout in seconds. Also used as the Python-side Future timeout.
+   * - ``connection_timeout``
+     - ``10.0``
+     - GLIDE connection timeout in seconds for initial client connections.
+
+Example Configurations
+----------------------
+
+Standalone-mode
+~~~~~~~~~~~~~~~~
+
+Basic Valkey Configuration (Standalone-mode)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host>:6379"
+   remote_serde: "naive"
+   extra_config:
+     valkey_username: "Your username"
+     valkey_password: "Your password"
+
+Standalone-mode Valkey Configuration with database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host>:6379"
+   remote_serde: "naive"
+   extra_config:
+     valkey_username: "Your username"
+     valkey_password: "Your password"
+     valkey_database: 0
+
+Standalone-mode Valkey Configuration with key TTL (volatile eviction)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enable a per-key TTL so a node configured with a ``volatile-lru`` /
+``volatile-lfu`` eviction policy can reclaim L2 cache keys once it reaches
+``maxmemory``. Without a TTL such policies never evict the KV cache keys,
+which can choke the remote cache.
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host>:6379"
+   remote_serde: "naive"
+   extra_config:
+     valkey_username: "Your username"
+     valkey_password: "Your password"
+     valkey_enable_ttl: true
+     valkey_ttl_sec: 3600   # keys expire after 1 hour
+
+Cluster-mode
+~~~~~~~~~~~~~~~~
+
+Cluster-mode Valkey Configuration (Endpoint)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For example, the configuration endpoint in ElastiCache is as follows:
+
+<cache-name>.<identifier>.clustercfg.<region>.cache.amazonaws.com
+
+You need to add this DNS name in the <your host>.
+
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host>:6379"
+   remote_serde: "naive"
+   extra_config:
+     valkey_mode: "cluster"
+     valkey_username: "Your username"
+     valkey_password: "Your password"
+
+
+Cluster-mode Valkey Configuration (Nodes)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Nodes are deployed directly and configured in cluster mode without connecting them via DNS names (CNAME).
+
+In this scenario, you simply input multiple IP hosts and ports.
+
+Example: 172.0.0.1:7001, 172.0.0.2:7002 ... 172.0.0.6:7006
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host 1>:<your port 1>, <your host 2>:<your port 2>, ... <your host N>:<your port N>"
+   remote_serde: "naive"
+   extra_config:
+     valkey_mode: "cluster"
+     valkey_username: "Your username"
+     valkey_password: "Your password"
+
+Cluster-mode Valkey Configuration with numbered databases (Valkey 9.0+ and Valkey-GLIDE 2.1+)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Valkey connector supports numbered databases in both the Endpoint using DNS and the Nodes method using IP and port pairs.
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host>:6379"
+   remote_serde: "naive"
+   extra_config:
+     valkey_mode: "cluster"
+     valkey_username: "Your username"
+     valkey_password: "Your password"
+     valkey_database: 1
+
+TLS / ElastiCache Serverless
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ElastiCache Serverless requires TLS. Set ``tls_enable: true``:
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<serverless-endpoint>:6379"
+   remote_serde: "naive"
+   extra_config:
+     valkey_mode: "cluster"
+     tls_enable: true
+     valkey_num_workers: 32
+
+Performance Tuning
+~~~~~~~~~~~~~~~~~~
+
+For large models (e.g., 70B with TP=8), increase the worker count for higher throughput:
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   remote_url: "valkey://<your host>:6379"
+   remote_serde: "naive"
+   pre_caching_hash_algorithm: sha256_cbor_64bit  # Required for TP>1
+   extra_config:
+     valkey_mode: "cluster"
+     valkey_num_workers: 32
\ No newline at end of file
diff --git a/docs/source/kv_cache/storage_backends/weka.rst b/docs/source/kv_cache/storage_backends/weka.rst
new file mode 100644
index 0000000..937dc6d
--- /dev/null
+++ b/docs/source/kv_cache/storage_backends/weka.rst
@@ -0,0 +1,137 @@
+Weka
+====
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/l2_storage/index`.
+
+
+.. _weka-overview:
+
+Overview
+--------
+
+WekaFS is a high-performance, distributed filesystem and is a supported option for KV Cache offloading in
+LMCache. Even though the local filesystem backend can work with a WekaFS mount, this particular backend is
+optimized for Weka's characteristics. It leverages GPUDirect Storage for I/O and it allows data-sharing
+between multiple LMCache instances.
+
+Ways to configure LMCache WEKA Offloading
+-----------------------------------------
+
+**1. Environment Variables:**
+
+.. code-block:: bash
+
+    # 256 Tokens per KV Chunk
+    export LMCACHE_CHUNK_SIZE=256
+    # Path to Weka Mount
+    export LMCACHE_GDS_PATH="/mnt/weka/cache"
+    # GDS Buffer Size in MiB
+    export LMCACHE_GDS_BUFFER_SIZE="8192"
+    # Disabling CPU RAM offload is sometimes recommended as the
+    # CPU can get in the way of GPUDirect operations
+    export LMCACHE_LOCAL_CPU=False
+    # GDS I/O Threads
+    export LMCACHE_EXTRA_CONFIG='{"disk_io_threads": 32}'
+
+**2. Configuration File**:
+
+Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``
+
+Example ``config.yaml``:
+
+.. code-block:: yaml
+
+    # 256 Tokens per KV Chunk
+    chunk_size: 256
+    # Disable local CPU
+    local_cpu: false
+    # Path to Weka Mount
+    gds_path: "/mnt/weka/cache"
+    # GDS Buffer Size in MiB
+    gds_buffer_size: 8192
+    # GDS I/O Threads
+    extra_config:
+      disk_io_threads: 32
+
+GDS Buffer Size Explanation
+---------------------------
+
+The backend currently pre-registers buffer space to speed up GDS operations. This buffer space
+is registered in VRAM so options like ``--gpu-memory-utilization`` from ``vllm`` should be considered
+when setting it. For example, a good rule of thumb for H100 which generally has 80GiBs of VRAM would
+be to start with 8GiB and set ``--gpu-memory-utilization 0.85`` and depending on your workflow fine-tune
+it from there.
+
+
+Setup Example
+-------------
+
+.. _weka-prerequisites:
+
+**Prerequisites:**
+
+- A Machine with at least one GPU. You can adjust the max model length of your vllm instance depending on your GPU memory.
+
+- Weka already installed and mounted.
+
+- vllm and lmcache installed (:doc:`Installation Guide <../../getting_started/installation>`)
+
+- Hugging Face access to ``meta-llama/Llama-3.1-8B-Instruct``
+
+.. code-block:: bash
+
+    export HF_TOKEN=your_hugging_face_token
+
+**Step 1. Create cache directory under your Weka mount:**
+
+To find all your WekaFS mounts run:
+
+.. code-block:: bash
+
+    mount -t wekafs
+
+For the sake of this example let's say that the above returns:
+
+.. code-block:: text
+
+    10.27.1.1/default on /mnt/weka type wekafs (rw,relatime,writecache,inode_bits=auto,readahead_kb=32768,dentry_max_age_positive=1000,dentry_max_age_negative=0,container_name=client)
+
+Then create a directory under it (the name here is arbitrary):
+
+.. code-block:: bash
+
+    mkdir /mnt/weka/cache
+
+**Step 2. Start a vLLM server with Weka offloading enabled:**
+
+Create a an lmcache configuration file called: ``weka-offload.yaml``
+
+.. code-block:: yaml
+
+    local_cpu: false
+    chunk_size: 256
+    gds_path: "/mnt/weka/cache"
+    gds_buffer_size: 8192
+    extra_config:
+      disk_io_threads: 32
+
+If you don't want to use a config file, uncomment the first three environment variables
+and then comment out the ``LMCACHE_CONFIG_FILE`` below:
+
+.. code-block:: bash
+
+    # LMCACHE_LOCAL_CPU=False \
+    # LMCACHE_CHUNK_SIZE=256 \
+    # LMCACHE_GDS_PATH="/mnt/weka/cache" \
+    # LMCACHE_GDS_BUFFER_SIZE=8192 \
+    # LMCACHE_EXTRA_CONFIG='{"disk_io_threads": 32}' \
+    LMCACHE_CONFIG_FILE="weka-offload.yaml" \
+    vllm serve \
+        meta-llama/Llama-3.1-8B-Instruct \
+        --max-model-len 65536 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+
diff --git a/docs/source/kv_cache_management/check_finish.rst b/docs/source/kv_cache_management/check_finish.rst
new file mode 100644
index 0000000..89de231
--- /dev/null
+++ b/docs/source/kv_cache_management/check_finish.rst
@@ -0,0 +1,11 @@
+.. _check_finish:
+
+Check finish of a control event
+=================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+Coming soon... 
diff --git a/docs/source/kv_cache_management/clear.rst b/docs/source/kv_cache_management/clear.rst
new file mode 100644
index 0000000..ac0f845
--- /dev/null
+++ b/docs/source/kv_cache_management/clear.rst
@@ -0,0 +1,97 @@
+.. _clear:
+
+Clear the KV cache
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``clear`` interface is defined as the following:
+
+.. code-block:: python
+
+    clear(instance_id: str, location: str) -> event_id: str, num_tokens: int
+
+The function removes the KV cache stored at ``location`` for the specified
+``instance_id``. It returns an ``event_id`` and the number of tokens scheduled
+for clearing.
+
+Example usage:
+---------------------------------------
+
+First, create a yaml file ``example.yaml`` to configure the lmcache instance:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 5
+
+    # cache controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_default_instance"
+    controller_pull_url: "localhost:9001"
+    lmcache_worker_ports: 8001
+
+    # Peer identifiers
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+
+Start the vllm/lmcache instance at port 8000:
+
+.. code-block:: bash
+
+    CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 \
+      --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    lmcache_controller --host localhost --port 9000 --monitor-port 9001
+
+Send a request to vllm:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models.",
+            "max_tokens": 10
+          }'
+
+Clear the KV cache in the system:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/clear \
+      -H "Content-Type: application/json" \
+      -d '{
+            "instance_id": "lmcache_default_instance",
+            "location": "LocalCPUBackend"
+          }'
+
+
+The controller responds with a message similar to:
+
+.. code-block:: text
+
+    {"event_id": "xxx", "num_tokens": 12}
+
+This indicates that the KV cache for 12 tokens has been scheduled for clearing.
+We can verify the cache has been cleared by performing a lookup:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/lookup \
+      -H "Content-Type: application/json" \
+      -d '{
+            "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+          }'
+
+The lookup should return an empty result, confirming that the KV cache has been
+cleared for the given tokens.
diff --git a/docs/source/kv_cache_management/compress.rst b/docs/source/kv_cache_management/compress.rst
new file mode 100644
index 0000000..10612c9
--- /dev/null
+++ b/docs/source/kv_cache_management/compress.rst
@@ -0,0 +1,124 @@
+.. _compress:
+
+Compress and Decompress the KV cache
+=====================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``compress`` interface is defined as the following:
+
+.. code-block:: python
+
+    compress(instance_id: str, method: str, location: str, tokens: list[int]) -> event_id: str, num_tokens: int
+    decompress(instance_id: str, method: str, location: str, tokens: list[int]) -> event_id: str, num_tokens: int
+
+These 2 functions compresses/decompresses the KV cache chunks specified by ``tokens`` using the
+given ``method`` in the storage ``location``. The controller returns an ``event_id`` and the number of tokens scheduled for compression or decompression.
+
+Example usage:
+---------------------------------------
+
+First, we need a yaml file ``example.yaml`` to properly configure the lmcache instance:
+
+.. code-block:: yaml
+
+      chunk_size: 256
+      local_cpu: True
+      max_local_cpu_size: 5
+
+      # cache controller configurations
+      enable_controller: True
+      lmcache_instance_id: "lmcache_default_instance"
+      controller_pull_url: "localhost:9001"
+      lmcache_worker_ports: 8001
+
+      # Peer identifiers
+      p2p_host: "localhost"
+      p2p_init_ports: 8200
+
+Second, we need to start the vllm/lmcache instance at port 8000:
+
+.. code-block:: bash
+
+    CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096  --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Third, we need to start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    lmcache_controller --host localhost --port 9000 --monitor-port 9001
+
+Then we can send a request to vllm to see if it works properly:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "meta-llama/Llama-3.1-8B-Instruct",
+        "prompt": "Explain the significance of KV cache in language models.",
+        "max_tokens": 10
+      }'
+
+Now we send a request to tokenize the prompt:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/tokenize \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "meta-llama/Llama-3.1-8B-Instruct",
+        "prompt": "Explain the significance of KV cache in language models."
+      }'
+
+We should be able to see token ids in response:
+
+.. code-block:: text
+
+    {"count":12,"max_model_len":4096,"tokens":[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],"token_strs":null}
+
+After all, we issue a ``compress`` request:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/compress \
+      -H "Content-Type: application/json" \
+      -d '{
+          "instance_id": "lmcache_default_instance",
+          "method": "cachegen",
+          "location": "LocalCPUBackend",
+          "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+      }'
+
+The controller responds with a message similar to:
+
+.. code-block:: text
+
+    {"event_id": "xxx", "num_tokens": 12}
+
+This indicates that 12 tokens are being compressed. The ``event_id`` can be used to query the status of the operation.
+
+Once the kv cache is compressed, we can use cachegen to decompress
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/decompress \
+      -H "Content-Type: application/json" \
+      -d '{
+          "instance_id": "lmcache_default_instance",
+          "method": "cachegen",
+          "location": "LocalCPUBackend",
+          "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+      }'
+
+The controller responds with a message similar to:
+
+.. code-block:: text
+
+    {"event_id": "xxx", "num_tokens": 12}
+
+This indicates that 12 tokens are being decompressed. The ``event_id`` can be used to query the status of the operation.
+
diff --git a/docs/source/kv_cache_management/health.rst b/docs/source/kv_cache_management/health.rst
new file mode 100644
index 0000000..72d8a62
--- /dev/null
+++ b/docs/source/kv_cache_management/health.rst
@@ -0,0 +1,45 @@
+.. _health:
+
+Check controller health
+=======================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``health`` interface is defined as the following:
+
+.. code-block:: python
+
+    health(instance_id: str) -> event_id: str, error_codes: Dict[int, int]
+
+The function returns an ``event_id`` and a dictionary mapping ``worker_id`` to
+``error_code``. A value of ``0`` indicates a healthy worker, while a non-zero
+value signals an error.
+
+Example usage:
+---------------------------------------
+
+First, start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-port 9001
+
+Then send a health check request:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/health \
+      -H "Content-Type: application/json" \
+      -d '{"instance_id": "lmcache_default_instance"}'
+
+The controller responds with a message similar to the following:
+
+.. code-block:: json
+
+    {"event_id": "health47ce328d-f27e-48ae-ab0c-c2218aabce95", "error_codes": {"0": 0, "1": 0}}
+
+Here ``error_codes`` lists each worker's ``error_code``. ``0`` represents a healthy
+worker, while non-zero values indicate an error.
diff --git a/docs/source/kv_cache_management/index.rst b/docs/source/kv_cache_management/index.rst
new file mode 100644
index 0000000..cd9238a
--- /dev/null
+++ b/docs/source/kv_cache_management/index.rst
@@ -0,0 +1,122 @@
+LMCache Controller
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+Overview
+--------
+The overall architecture of the LMCache Controller is shown in the figure,
+mainly consisting of two parts: the Controller Manager and LMCache Worker.
+
+The Controller Manager mainly consists of KV Controller, Reg Controller, and Cluster Executor.
+
+- KV Controller: The KV Controller handles the chunk information reported by LMCache Workers, and lookup requests query chunk information from the KV Controller.
+- Reg Controller: The Reg Controller is responsible for handling register/deregister/heartbeat requests from LMCache Workers.
+- Cluster Executor: When the Controller Manager receives user requests, such as Clear or Move, it sends the corresponding commands to LMCache Workers through the Cluster Executor.
+
+The LMCache Worker is a thread within a rank process, which is responsible for the following tasks:
+
+- sends register, deregister, heartbeat to the Reg Controller.
+- send chunk information to the KV Controller, which include admit and evict message.
+- listens on a port to receive commands from the Cluster Executor and performs corresponding processing.
+
+.. image:: /assets/lmcache-controller.png
+    :alt: LMCache Controller Architecture Diagram
+
+P2P Related
+^^^^^^^^^^^
+
+If ``enable_p2p`` is enabled, the LMCache Controller must also be enabled. The LMCache Controller serves as the central node
+and stores information for each chunk. The ``P2PBackend`` queries chunk information from the LMCache Controller and performs
+data transmission through NIXL.
+
+
+Key Features
+------------
+
+1. Exposes a set of APIs for users and orchestrators to manage the KV cache.
+
+Currently, the controller provides the following APIs:
+
+- :ref:`Clear <clear>`: Clear the KV caches.
+- :ref:`Compress <compress>`: Compress the KV cache.
+- :ref:`Health <health>`: Check the health status of cache workers.
+- :ref:`Lookup <lookup>`: Lookup the KV cache for a given list of tokens.
+- :ref:`Move <move>`: Move the KV cache to a different location.
+- :ref:`Pin <pin>`: Persist the KV cache to prevent it from being evicted.
+- :ref:`CheckFinish <check_finish>`: Check whether a (non-blocking) control event has finished or not.
+- :ref:`QueryWorkerInfo <query_worker_info>`: Query the worker info.
+
+2. Interacts with the LMCache worker.
+
+Currently, the LMCache worker supports the following functions:
+
+- register with the controller
+- deregister from the controller
+- heartbeat
+- admit or evict chunk information(LocalCPUBackend or LocalDiskBackend)
+
+
+Quick Start
+-----------
+
+**Start the Controller**
+
+.. code-block:: bash
+
+    python3 -m lmcache.v1.api_server
+
+Expected output:
+
+.. code-block:: text
+
+    [2025-11-11 11:15:35,277] LMCache WARNING: Argument --monitor-port will be deprecated soon. Please use --monitor-ports instead. (__main__.py:361:__main__)
+    INFO 11-11 11:15:36 [__init__.py:239] Automatically detected platform cuda.
+    /usr/local/lib/python3.12/dist-packages/pydantic/_internal/_fields.py:198: UserWarning: Field name "copy" in "create_app.<locals>.MoveRequest" shadows an attribute in parent "BaseModel"
+    warnings.warn(
+    [2025-11-11 11:15:37,956] LMCache INFO: Starting LMCache controller at 0.0.0.0:9000 (__main__.py:371:__main__)
+    [2025-11-11 11:15:37,956] LMCache INFO: Monitoring lmcache workers at ports None (__main__.py:372:__main__)
+    INFO:     Started server process [50664]
+    INFO:     Waiting for application startup.
+    INFO:     Application startup complete.
+    INFO:     Uvicorn running on http://0.0.0.0:9000 (Press CTRL+C to quit)
+
+**Controller Configuration**
+
+- --host: default is 0.0.0.0
+- --port: default is 9000, the externally exposed port through which interfaces like lookup can be accessed via this port.
+- --monitor-port: default is 9001,  the port through which LMCache Worker communicates with Controller Manager (deprecated, indicates the pull port in --monitor-ports, reply port is None).
+- --monitor-ports: default is None, if configured, requires a JSON format string input such as ``{"pull": 8300, "reply": 8400}``.
+
+**YAML Configuration**
+
+.. code-block:: yaml
+
+    enable_controller: True
+    lmcache_instance_id: "lmcache_instance_id"
+
+    controller_pull_url: ip:pull_port
+    # if controller reply port is None, no need to configure reply url
+    controller_reply_url: ip:reply_port
+    # the number of ports for LMCache Worker, must equal to the number of ranks
+    lmcache_worker_ports: [1, 2, 3]
+
+    # p2p configuration
+    p2p_host: localhost
+    p2p_init_ports: [11, 12, 13]
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   clear
+   compress
+   health
+   lookup
+   move
+   pin
+   check_finish
+   query_worker_info
diff --git a/docs/source/kv_cache_management/lookup.rst b/docs/source/kv_cache_management/lookup.rst
new file mode 100644
index 0000000..ab78443
--- /dev/null
+++ b/docs/source/kv_cache_management/lookup.rst
@@ -0,0 +1,98 @@
+.. _lookup:
+
+Lookup the KV cache
+===================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``lookup`` interface is defined as the following: 
+
+.. code-block:: python
+
+    lookup(tokens: List[int]) -> event_id: str, layout_info: Dict[str, Tuple[str, int]]
+
+The function takes a list of tokens as input and returns event_id and a dictionary containing the layout information for each token.
+The layout information is represented as a mapping between ``instance_id`` and a tuple of ``(location, matched_prefix_length)``.
+
+Example usage:
+---------------------------------------
+
+First, we need a yaml file ``example.yaml`` to properly configure the lmcache instance:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 5
+
+    # cache controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_default_instance"
+    controller_pull_url: "localhost:9001"
+    lmcache_worker_ports: 8001
+
+    # Peer identifiers
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+
+Second, we need to start the vllm/lmcache instance at port 8000:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096  --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Third, we need to start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-port 9001
+
+Then we can send a request to vllm to see if it works properly:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "meta-llama/Llama-3.1-8B-Instruct",
+        "prompt": "Explain the significance of KV cache in language models.",
+        "max_tokens": 10
+      }'
+
+Now we send a request to tokenize the prompt:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/tokenize \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "meta-llama/Llama-3.1-8B-Instruct",
+        "prompt": "Explain the significance of KV cache in language models."
+      }'
+
+We should be able to see token ids in response:
+
+.. code-block:: text
+
+    {"count":12,"max_model_len":4096,"tokens":[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],"token_strs":null}
+
+Finally, we can send a ``lookup`` request to the lmcache controller:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/lookup \
+      -H "Content-Type: application/json" \
+      -d '{
+        "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+      }'
+
+We should be able to see the response like this:
+
+.. code-block:: text
+
+    {"event_id": "xxx", "lmcache_default_instance": ("LocalCPUBackend", 12)}
+
+The field ``lmcache_default_instance`` shows the instance ID, followed by a tuple of ``(location, matched_prefix_length)`` indicating the cache location within that instance and matched prefix length. ``event_id`` is an identifier of the controller operation and can typically be ignored.
diff --git a/docs/source/kv_cache_management/move.rst b/docs/source/kv_cache_management/move.rst
new file mode 100644
index 0000000..e60e66b
--- /dev/null
+++ b/docs/source/kv_cache_management/move.rst
@@ -0,0 +1,135 @@
+.. _move:
+
+Move the KV cache
+=================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``move`` interface is defined as the following:
+
+.. code-block:: python
+
+    move(old_position: Tuple[str, str], new_position: Tuple[str, str],
+         tokens: Optional[List[int]] = [], copy: Optional[bool] = False) -> event_id: str, num_tokens: int
+
+The function moves the KV cache chunks identified by ``tokens`` from
+``old_position`` to ``new_position``. Each position is a tuple of
+``(instance_id, location)``. Setting ``copy`` to ``True`` copies the
+KV cache instead of moving it.
+
+Note that NIXL is required to  be installed for P2P transfer. 
+We'll support other transports later such as Python socket and Mooncake.
+
+Example usage:
+---------------------------------------
+
+First, prepare two yaml files ``instance1.yaml`` and ``instance2.yaml`` to
+configure two lmcache instances:
+
+.. code-block:: yaml
+
+    # instance1.yaml
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 5
+
+    # cache controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_instance_1"
+    controller_pull_url: "localhost:8300"
+    controller_reply_url: "localhost:8400"
+    lmcache_worker_ports: 8500
+
+    # P2P configurations
+    enable_p2p: True
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+    p2p_lookup_ports: 8201
+    transfer_channel: "nixl"
+
+
+.. code-block:: yaml
+
+    # instance2.yaml
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 5
+
+    # cache controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_instance_1"
+    controller_pull_url: "localhost:8300"
+    controller_reply_url: "localhost:8400"
+    lmcache_worker_ports: 8501
+
+    # P2P configurations
+    enable_p2p: True
+    p2p_host: "localhost"
+    p2p_init_ports: 8202
+    p2p_lookup_ports: 8203
+    transfer_channel: "nixl"
+
+Start two vllm engines:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=instance1.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 \
+      --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=instance2.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 \
+      --gpu-memory-utilization 0.8 --port 8001 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-ports '{"pull": 8300, "reply": 8400}'
+
+Send a request to vllm engine 1:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models.",
+            "max_tokens": 10
+          }'
+
+Tokenize the prompt to obtain token ids:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/tokenize \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models."
+          }'
+
+Move the KV cache from engine 1's CPU to engine 2's CPU using the token ids:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/move \
+      -H "Content-Type: application/json" \
+      -d '{
+            "old_position": ["lmcache_instance_1", "LocalCPUBackend"],
+            "new_position": ["lmcache_instance_2", "LocalCPUBackend"],
+            "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+          }'
+
+The controller responds with a message similar to:
+
+.. code-block:: text
+
+    {"num_tokens": 12, "event_id": "xxx"}
+
+``num_tokens`` indicates how many tokens' KV cache are being moved. The
+returned ``event_id`` can be used to query the status of the operation.
diff --git a/docs/source/kv_cache_management/pin.rst b/docs/source/kv_cache_management/pin.rst
new file mode 100644
index 0000000..704bb61
--- /dev/null
+++ b/docs/source/kv_cache_management/pin.rst
@@ -0,0 +1,98 @@
+.. _pin:
+
+Pin the KV cache
+================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``pin`` interface is defined as the following:
+
+.. code-block:: python
+
+    pin(instance_id: str, location: str, tokens: List[int]) -> event_id: str, num_tokens: int
+
+The function pins (persists) the KV cache chunks specified by ``tokens`` in the
+given ``location`` of the ``instance_id``. The controller returns an ``event_id``
+and the number of tokens scheduled for pinning.
+
+Example usage:
+---------------------------------------
+
+First, create a yaml file ``example.yaml`` to configure the lmcache instance:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 5
+
+    # cache controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_default_instance"
+    controller_pull_url: "localhost:9001"
+    lmcache_worker_ports: 8001
+
+    # Peer identifiers
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+
+
+Start the vllm/lmcache instance at port 8000:
+
+.. code-block:: bash
+
+    CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 \
+      --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    lmcache_controller --host localhost --port 9000 --monitor-port 9001
+
+Send a request to vllm:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models.",
+            "max_tokens": 10
+          }'
+
+Tokenize the prompt to obtain token ids:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:8000/tokenize \
+      -H "Content-Type: application/json" \
+      -d '{
+            "model": "meta-llama/Llama-3.1-8B-Instruct",
+            "prompt": "Explain the significance of KV cache in language models."
+          }'
+
+Pin the KV cache in the system:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/pin \
+      -H "Content-Type: application/json" \
+      -d '{
+            "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13],
+            "instance_id": "lmcache_default_instance",
+            "location": "LocalCPUBackend"
+          }'
+
+The controller responds with a message similar to:
+
+.. code-block:: text
+
+    {"event_id": "xxx", "num_tokens": 12}
+
+``num_tokens`` indicates how many tokens' KV cache are pinned. The
+returned ``event_id`` can be used to query the status of the operation.
diff --git a/docs/source/kv_cache_management/query_worker_info.rst b/docs/source/kv_cache_management/query_worker_info.rst
new file mode 100644
index 0000000..ca5a99d
--- /dev/null
+++ b/docs/source/kv_cache_management/query_worker_info.rst
@@ -0,0 +1,73 @@
+.. _query_worker_info:
+
+Query Worker Info
+=================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The ``query_worker_info`` interface is defined as the following:
+
+.. code-block:: python
+
+    query_worker_info(instance_id: str, worker_ids: List[int]) -> event_id: str, worker_infos: List[WorkerInfo]
+
+The function get the info of the workers which specified by ``instance_id`` and ``worker_ids``.
+The controller returns an ``event_id`` and the worker infos.
+
+Example usage:
+---------------------------------------
+
+First, create a yaml file ``example.yaml`` to configure the lmcache instance:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: True
+    max_local_cpu_size: 5
+
+    # cache controller configurations
+    enable_controller: True
+    lmcache_instance_id: "lmcache_default_instance"
+    controller_pull_url: "localhost:9001"
+    lmcache_worker_ports: 8001
+
+    # Peer identifiers
+    p2p_host: "localhost"
+    p2p_init_ports: 8200
+
+
+Start the vllm/lmcache instance at port 8000:
+
+.. code-block:: bash
+
+    CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096 \
+      --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+.. code-block:: bash
+
+    lmcache_controller --host localhost --port 9000 --monitor-port 9001
+
+Send a request to controller:
+
+.. code-block:: bash
+
+    curl -X POST http://localhost:9000/query_worker_info \
+      -H "Content-Type: application/json" \
+      -d '{
+            "instance_id": "lmcache_default_instance",
+            "worker_ids": [0]
+          }'
+
+The controller responds with a message similar to:
+
+.. code-block:: text
+
+    {"event_id": "xxx", "worker_infos": [{"instance_id": "lmcache_default_instance", "worker_id": 0, "ip": "127.0.0.1", "port": 8001, "peer_init_url": "127.0.0.1:8200", "registration_time": 123456, "last_heartbeat_time": 456789}]}
+
+``worker_infos`` contains the queried worker information.
+returned ``event_id`` can be used to query the status of the operation.
diff --git a/docs/source/kv_cache_optimizations/blending.rst b/docs/source/kv_cache_optimizations/blending.rst
new file mode 100644
index 0000000..6b679e1
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/blending.rst
@@ -0,0 +1,88 @@
+Blending
+================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+CacheBlend enables KV cache reuse for non-prefix positions by recomputing a subset of tokens at non-prefix positions.
+For example, CacheBlend can combine multiple (pre-)computed KV caches, when their corresponding texts are concatenated in the LLM input
+
+Configuring CacheBlend in RAG scenarios
+-------------------------------------------------
+
+Here, we will explain the code in our end-to-end `example <https://github.com/LMCache/LMCache/tree/dev/examples/blend_kv_v1/blend.py>`_>.
+
+Below are some blending-related configurations (and explanations):
+
+.. code-block:: python
+
+    # Enable blending in LMCache
+    os.environ["LMCACHE_ENABLE_BLENDING"] = "True"
+
+    # Separator string between different chunks
+    os.environ["LMCACHE_BLEND_SPECIAL_STR"] = " # # "
+
+    # Layerwise must be turned on when blending is enabled
+    os.environ["LMCACHE_USE_LAYERWISE"] = "True"
+
+    # Determining which tokens to recompute at layer 1
+    os.environ["LMCACHE_BLEND_CHECK_LAYERS"] = "1"
+
+    # Ratio of tokens to recompute
+    os.environ["LMCACHE_BLEND_RECOMPUTE_RATIOS"] = "0.15"
+
+    # Optionally, we can use sparse attention to improve generation quality
+    # by using more accurate attention mask
+    if enable_sparse:
+        os.environ["VLLM_ATTENTION_BACKEND"] = "FLASHINFER"
+        os.environ["LMCACHE_EXTRA_CONFIG"] = '{"enable_sparse": true}'
+
+Firstly, we preprocess texts into tokens, as tokenizing a concatenated string may produce different tokens than concatenating the results of tokenizing each string individually.
+For example, assume we have a system prompt and three text chunks. We need to preprocess them into tokens before sending to the LLM:
+
+.. code-block:: python
+
+    sys_prompt = tokenizer.encode("You are a very helpful assistant.")
+    chunk1_prompt = tokenizer.encode("Hello, how are you?" * 500)[1:]
+    chunk2_prompt = tokenizer.encode("Hello, what's up?" * 500)[1:]
+    chunk3_prompt = tokenizer.encode("Hi, what are you up to?" * 500)[1:]
+    blend_special_str = tokenizer.encode(os.getenv("LMCACHE_BLEND_SPECIAL_STR"))[1:]
+    first_prompt = (
+        sys_prompt
+        + blend_special_str
+        + chunk1_prompt
+        + blend_special_str
+        + chunk2_prompt
+        + blend_special_str
+        + chunk3_prompt
+        + blend_special_str
+        + tokenizer.encode("Hello, my name is")[1:]
+    )
+
+Then, we can send the tokenized prompt to vLLM. Meanwhile, LMCache will store the KV caches of different chunks according to the ``BLEND_SPECIAL_STR``.
+
+.. code-block:: python
+
+    llm.generate(prompts={"prompt_token_ids": first_prompt})
+
+Similarly, we build another prompt using the same chunks but with different orders.
+
+.. code-block:: python
+
+    second_prompt = (
+        sys_prompt
+        + blend_special_str
+        + chunk2_prompt
+        + blend_special_str
+        + chunk1_prompt
+        + blend_special_str
+        + chunk3_prompt
+        + blend_special_str
+        + tokenizer.encode("Hello, how are you?")[1:]
+    )
+    llm.generate(prompts={"prompt_token_ids": second_prompt})
+
+Even though the second prompt has a different order of chunks, LMCache can still reuse the KV caches of chunk1, chunk2, and chunk3.
+
diff --git a/docs/source/kv_cache_optimizations/cacheblend.rst b/docs/source/kv_cache_optimizations/cacheblend.rst
new file mode 100644
index 0000000..50a4934
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/cacheblend.rst
@@ -0,0 +1,26 @@
+CacheBlend
+==========
+
+CacheBlend lets LMCache reuse the KV cache of **any** repeated text chunk --
+not only a shared prefix -- by selectively recomputing a small fraction of
+tokens at chunk boundaries. This cuts time-to-first-token for RAG and
+multi-document workloads where the reusable context is not a clean prefix.
+
+Enabling CacheBlend (MP mode)
+-----------------------------
+
+Start the LMCache server with the blend engine:
+
+.. code-block:: bash
+
+   lmcache server --l1-size-gb 20 --eviction-policy LRU --engine-type blend
+
+The ``blend`` engine composes a ``BlendModule`` into the server and requires
+``--supported-transfer-mode`` to be ``lmcache_driven`` or ``auto`` (the default). See
+:doc:`/mp/configuration` for the related server flags.
+
+.. note::
+
+   The in-process CacheBlend documentation -- configuration knobs such as
+   ``LMCACHE_ENABLE_BLENDING`` and an end-to-end example -- is preserved in
+   the Legacy section: :doc:`/kv_cache_optimizations/blending`.
diff --git a/docs/source/kv_cache_optimizations/compression/cachegen.rst b/docs/source/kv_cache_optimizations/compression/cachegen.rst
new file mode 100644
index 0000000..b515d35
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/compression/cachegen.rst
@@ -0,0 +1,32 @@
+.. _cachegen:
+
+CacheGen
+===================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/cachegen`.
+
+
+Cachegen leverages KV cache's distributional properties to encode a KV cache into more compact bitstream representations with negligible decoding overhead.
+
+
+Configuring CacheGen in LMCache
+---------------------------------------
+
+The settings should be very similar to :ref:`naive KV cache sharing <share_kv_cache>`. 
+Only minor configurations need to be done to enable CacheGen. 
+
+To enable CacheGen in offline inference, we need to set:
+
+.. code-block:: python
+
+    # Enable cachgen compression in LMCache
+    os.environ["LMCACHE_REMOTE_SERDE"] = "cachegen"
+
+To enable CacheGen in online inference, we need to set the ``remote_serde`` in the configuration yaml:
+
+.. code-block:: yaml
+
+    # Enable cachgen compression in LMCache
+    remote_serde: "cachegen"
\ No newline at end of file
diff --git a/docs/source/kv_cache_optimizations/compression/index.rst b/docs/source/kv_cache_optimizations/compression/index.rst
new file mode 100644
index 0000000..a5a64aa
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/compression/index.rst
@@ -0,0 +1,13 @@
+Compression
+===========
+
+KV cache compression can greatly reduces the size of the cache, which can be beneficial for both storage/memory usage and loading speed.
+Currently, we support the following compression algorithms:
+
+- :ref:`CacheGen <cachegen>`: `CacheGen: KV Cache Compression and Streaming for Fast Large Language Model Serving <https://dl.acm.org/doi/10.1145/3651890.3672274>`_
+
+
+.. toctree::
+   :maxdepth: 1
+
+   cachegen
diff --git a/docs/source/kv_cache_optimizations/index.rst b/docs/source/kv_cache_optimizations/index.rst
new file mode 100644
index 0000000..e082cde
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/index.rst
@@ -0,0 +1,11 @@
+KV Cache Optimizations
+======================
+
+Techniques that improve KV cache reuse and efficiency beyond plain prefix
+caching.
+
+.. toctree::
+   :maxdepth: 1
+
+   cacheblend
+   segmented_prefill
diff --git a/docs/source/kv_cache_optimizations/layerwise.rst b/docs/source/kv_cache_optimizations/layerwise.rst
new file mode 100644
index 0000000..d8efe98
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/layerwise.rst
@@ -0,0 +1,116 @@
+Layerwise KV Transfer
+=====================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The storage and loading of KV Cache on a layer granularity is a key optimization that allows for forward pass to "stagger" through its computation as each layer's KV Cache is received instead of only waiting to begin after the entire loading
+
+CacheBlend is implemented on top of the layerwise codepath in order to pipeline recompute and loading to mask the latency of loading KV Cache.
+
+.. image:: /_static/basic_codepath.svg
+   :alt: Basic Codepath
+   :class: scalable
+
+.. raw:: html
+
+   <div style="text-align:center; margin:1em 0;">
+     <a href="/_static/full_layerwise_diagram.svg" target="_blank">
+       <img src="/_static/full_layerwise_diagram.svg"
+            style="display:block; margin:auto; max-width:100%; height:auto;"/>
+     </a>
+     <div style="font-size:0.9em; color:#555; margin-top:0.5em;">
+       Click to open full-size
+     </div>
+   </div>
+
+Architecture Overview
+---------------------
+
+**CacheEngine**
+  The main orchestrator containing two primary generators:
+  
+  * **Retrieval Generator** (N + 2 yields): Handles layer-by-layer KV cache loading with on-demand memory allocation
+  * **Storage Generator** (N + 1 yields): Manages layer-by-layer KV cache saving with upfront CPU memory allocation
+
+**LayerwiseGPUConnector** 
+  Manages GPU-CPU memory transfers with dedicated CUDA streams:
+  
+  * **Load GPU Buffer**: Temporary GPU memory for CPU→GPU transfers (``use_gpu: true``)
+  * **Store GPU Buffer**: Temporary GPU memory for GPU→CPU transfers (``use_gpu: true``)
+  * **Nested Generators**: ``batched_to_gpu()`` and ``batched_from_gpu()`` handle actual memory operations
+
+**StorageManager**
+  Handles persistent storage operations:
+  
+  * ``layerwise_batched_get()``: Asynchronous retrieval with ``.result()`` for request-level concurrency
+  * ``batched_put()``: Stores memory objects to persistent backends
+
+Execution Flow
+~~~~~~~~~~~~~~
+
+The layerwise pipeline follows a numbered execution sequence:
+
+**1. start_load_kv()**
+   * Initializes Retrieval Generator via ``lmcache_engine.retrieve_layer()``
+   * Performs setup (1st ``next()``) and loads layer 0 (2nd ``next()``)
+   * Creates ``layerwise_retrievers`` list for ongoing layer processing
+
+**2. wait_for_layer_load()** (repeated for each layer)
+   * Advances Retrieval Generator via ``next()`` to process layer i
+   * Triggers ``StorageManager.layerwise_batched_get()`` for async cache retrieval
+   * Calls GPU Load Generator's ``batched_to_gpu()`` to transfer memory objects to GPU
+   * **Last request in batch**: Synchronizes ``current_stream.wait_stream(load_stream)``
+
+**3. save_kv_layer()** (repeated for each layer)
+   * **First call only**: Creates Storage Generator with upfront CPU memory allocation
+   * Advances Storage Generator via ``next()`` to process layer i
+   * Calls GPU Store Generator's ``batched_from_gpu()`` to transfer GPU data to CPU
+   * **First request in batch**: Synchronizes ``store_stream.wait_stream(current_stream)``
+
+**4. wait_for_save()**
+   * Finalizes Storage Generator with last ``next()`` call
+   * Completes all ``StorageManager.batched_put()`` operations
+   * Performs GPU Store Generator cleanup
+
+Key Optimizations
+~~~~~~~~~~~~~~~~~
+
+**Pipelined Memory Operations**
+  The system overlaps layer N+1 computation with layer N storage.
+
+**Stream Synchronization**
+  Three CUDA streams coordinate operations:
+  
+  * ``current_stream``: vLLM's forward pass computation
+  * ``load_stream``: KV cache loading operations  
+  * ``store_stream``: KV cache storing operations
+
+**Batch-Level Coordination**
+  Multiple requests are processed together with specialized synchronization:
+  
+  * **First request**: Provides store stream synchronization to prevent GPU buffer corruption
+  * **Last request**: Provides load stream synchronization to ensure KV cache availability
+
+**Memory Allocation Strategies**
+  * **Retrieval**: Layer-by-layer allocation
+  * **Storage**: Upfront allocation for all layers
+
+**Cache Key Management**
+  Multi-layer cache engine keys use ``split_layers(N)`` to create per-layer kubernetes_deployment
+
+Configuration
+~~~~~~~~~~~~~
+
+Enable layerwise caching by setting:
+
+.. code-block:: yaml
+
+   use_layerwise: true
+
+The system automatically selects appropriate layerwise GPU connectors based on configuration:
+
+* ``VLLMPagedMemLayerwiseGPUConnector``: For standard layerwise operations  
+* ``VLLMBufferLayerwiseGPUConnector``: When blending is enabled
diff --git a/docs/source/kv_cache_optimizations/segmented_prefill.rst b/docs/source/kv_cache_optimizations/segmented_prefill.rst
new file mode 100644
index 0000000..e9d5f01
--- /dev/null
+++ b/docs/source/kv_cache_optimizations/segmented_prefill.rst
@@ -0,0 +1,6 @@
+Segmented Prefill
+=================
+
+.. note::
+
+   Documentation for segmented prefill is **coming soon**.
diff --git a/docs/source/legacy/index.rst b/docs/source/legacy/index.rst
new file mode 100644
index 0000000..0610f68
--- /dev/null
+++ b/docs/source/legacy/index.rst
@@ -0,0 +1,58 @@
+.. _legacy:
+
+Legacy (In-Process Mode)
+========================
+
+.. warning::
+
+   These pages document LMCache's original **in-process mode**, where LMCache
+   ran *inside* the inference engine process (e.g. via ``LMCacheConnectorV1`` on
+   vLLM). In-process mode is **deprecated**; new deployments should use
+   :doc:`Multiprocess (MP) mode <../mp/index>`.
+
+Background
+----------
+
+LMCache began as an in-process library embedded directly in the serving engine.
+The **multiprocess refactor** moved LMCache into a standalone ``lmcache server``
+and made an **asynchronous prefetching architecture** the default -- a
+``LOOKUP`` followed by background L2→L1 loads -- alongside process isolation,
+shared caching across engine instances, and multi-tier (L1/L2) storage.
+
+MP is now the recommended mode and is on track to support essentially
+everything in-process mode did. The pages below are kept for users still on
+in-process mode and as a historical reference while MP closes any remaining
+gaps; where a feature already has an MP equivalent, prefer the MP docs.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   /getting_started/quickstart/index
+   /kv_cache/storage_backends/index
+   /kv_cache/async_loading
+   /kv_cache/caching_policies
+   /kv_cache/p2p_sharing
+   /non_kv_cache/encoder_cache
+   /disaggregated_prefill/nixl/index
+   /disaggregated_prefill/shared_storage
+   /kv_cache_optimizations/compression/index
+   /kv_cache_optimizations/layerwise
+   /kv_cache_management/index
+   /kv_cache_optimizations/blending
+   /api_reference/multimodality
+   /api_reference/storage_backends
+   /api_reference/dynamic_connector
+   /api_reference/configurations
+   /internal_api_server/internal_api_server
+   /controller/index
+   /production/observability/index
+   /production/docker_deployment
+   /production/performance_tuning
+   /production/kv_cache_events
+   /developer_guide/architecture
+   /developer_guide/integration
+   /developer_guide/usage/index
+   /developer_guide/usage/basic_check
+   /developer_guide/extending_lmcache/storage_plugins
+   /developer_guide/extending_lmcache/remote_storage_plugins
diff --git a/docs/source/locale/README.md b/docs/source/locale/README.md
new file mode 100644
index 0000000..3346e9a
--- /dev/null
+++ b/docs/source/locale/README.md
@@ -0,0 +1,27 @@
+# Documentation Translations
+
+This directory stores Sphinx/gettext translation catalogs. English `.rst` files
+under `docs/source/` remain the source of truth.
+
+## Directory Layout
+
+- `zh_CN/`: Simplified Chinese translations.
+- `LC_MESSAGES/`: Standard gettext catalog directory.
+- `.po`: Reviewable translation files generated/updated by `sphinx-intl`.
+
+## Translation Flow
+
+1. `sphinx-build -b gettext` extracts English strings into `.pot` templates (throwaway).
+2. `sphinx-intl update` writes new strings as empty entries and changed strings as `fuzzy` in the committed `.po` files.
+3. `tools/translate_docs_zh.py` calls the model to fill in the empty and fuzzy entries.
+4. A PR is opened on `automation/update-chinese-docs` for human review.
+5. After merge, `build_doc.yml` rebuilds the site at `/zh_CN/`.
+
+Steps 1–4 run weekly in `translate_doc_zh.yml` (Monday 09:00 UTC, or manual
+dispatch). Step 5 runs automatically on push to `dev`.
+
+To change the translation prompt, edit the system message in
+`tools/translate_docs_zh.py`.
+
+This README is for maintainers only. It is not linked from the Sphinx toctree,
+so it should not appear on the public documentation website.
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/configurations.po b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/configurations.po
new file mode 100644
index 0000000..e8469fd
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/configurations.po
@@ -0,0 +1,1698 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/api_reference/configurations.rst:2
+msgid "Configuring LMCache"
+msgstr "配置 LMCache"
+
+#: ../../source/api_reference/configurations.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/configuration`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/configuration`。"
+
+#: ../../source/api_reference/configurations.rst:9
+msgid "LMCache supports two types of configurations:"
+msgstr "LMCache 支持两种类型的配置："
+
+#: ../../source/api_reference/configurations.rst:11
+msgid ""
+"**Configuration file**: a YAML (recommended) or JSON file that contains "
+"the configuration items."
+msgstr "**配置文件**\\ ：一个包含配置项的 YAML（推荐）或 JSON 文件。"
+
+#: ../../source/api_reference/configurations.rst:12
+msgid ""
+"**Environment variables**: environment variables that start with "
+"``LMCACHE_``."
+msgstr "**环境变量**\\ ：以 ``LMCACHE_`` 开头的环境变量。"
+
+#: ../../source/api_reference/configurations.rst:14
+msgid ""
+"To use a configuration file, you can set the ``LMCACHE_CONFIG_FILE`` "
+"environment variable to the path of the configuration file."
+msgstr "要使用配置文件，您可以将 ``LMCACHE_CONFIG_FILE`` 环境变量设置为配置文件的路径。"
+
+#: ../../source/api_reference/configurations.rst:18
+msgid ""
+"The environment variable configurations will be ignored if the "
+"configuration file is present."
+msgstr "如果配置文件存在，则环境变量配置将被忽略。"
+
+#: ../../source/api_reference/configurations.rst:22
+msgid "General Configurations"
+msgstr "通用配置"
+
+#: ../../source/api_reference/configurations.rst:24
+msgid "Basic cache settings that control the core functionality of LMCache."
+msgstr "控制 LMCache 核心功能的基本缓存设置。"
+
+#: ../../source/api_reference/configurations.rst:30
+#: ../../source/api_reference/configurations.rst:122
+#: ../../source/api_reference/configurations.rst:158
+#: ../../source/api_reference/configurations.rst:183
+#: ../../source/api_reference/configurations.rst:211
+#: ../../source/api_reference/configurations.rst:244
+#: ../../source/api_reference/configurations.rst:403
+#: ../../source/api_reference/configurations.rst:507
+#: ../../source/api_reference/configurations.rst:535
+#: ../../source/api_reference/configurations.rst:551
+msgid "YAML Config Name"
+msgstr "YAML 配置名称"
+
+#: ../../source/api_reference/configurations.rst:31
+#: ../../source/api_reference/configurations.rst:123
+#: ../../source/api_reference/configurations.rst:159
+#: ../../source/api_reference/configurations.rst:184
+#: ../../source/api_reference/configurations.rst:212
+#: ../../source/api_reference/configurations.rst:245
+#: ../../source/api_reference/configurations.rst:404
+#: ../../source/api_reference/configurations.rst:508
+#: ../../source/api_reference/configurations.rst:536
+#: ../../source/api_reference/configurations.rst:552
+msgid "Environment Variable"
+msgstr "环境变量"
+
+#: ../../source/api_reference/configurations.rst:32
+#: ../../source/api_reference/configurations.rst:124
+#: ../../source/api_reference/configurations.rst:160
+#: ../../source/api_reference/configurations.rst:185
+#: ../../source/api_reference/configurations.rst:213
+#: ../../source/api_reference/configurations.rst:246
+#: ../../source/api_reference/configurations.rst:322
+#: ../../source/api_reference/configurations.rst:347
+#: ../../source/api_reference/configurations.rst:379
+#: ../../source/api_reference/configurations.rst:405
+#: ../../source/api_reference/configurations.rst:442
+#: ../../source/api_reference/configurations.rst:509
+#: ../../source/api_reference/configurations.rst:537
+#: ../../source/api_reference/configurations.rst:553
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/api_reference/configurations.rst:33
+msgid "chunk_size"
+msgstr "chunk_size"
+
+#: ../../source/api_reference/configurations.rst:34
+msgid "LMCACHE_CHUNK_SIZE"
+msgstr "LMCACHE_CHUNK_SIZE"
+
+#: ../../source/api_reference/configurations.rst:35
+msgid "Size of cache chunks. Default: 256"
+msgstr "缓存块的大小。默认值：256"
+
+#: ../../source/api_reference/configurations.rst:36
+msgid "local_cpu"
+msgstr "local_cpu"
+
+#: ../../source/api_reference/configurations.rst:37
+msgid "LMCACHE_LOCAL_CPU"
+msgstr "LMCACHE_LOCAL_CPU"
+
+#: ../../source/api_reference/configurations.rst:38
+msgid "Whether to enable CPU caching. Values: true/false. Default: true"
+msgstr "是否启用 CPU 缓存。值：true/false。默认：true"
+
+#: ../../source/api_reference/configurations.rst:39
+msgid "max_local_cpu_size"
+msgstr "max_local_cpu_size"
+
+#: ../../source/api_reference/configurations.rst:40
+msgid "LMCACHE_MAX_LOCAL_CPU_SIZE"
+msgstr "LMCACHE_MAX_LOCAL_CPU_SIZE"
+
+#: ../../source/api_reference/configurations.rst:41
+msgid "Maximum CPU cache size in GB. Default: 5.0"
+msgstr "最大 CPU 缓存大小（以 GB 为单位）。默认值：5.0"
+
+#: ../../source/api_reference/configurations.rst:42
+msgid "local_cpu_use_hugepages"
+msgstr "local_cpu_use_hugepages"
+
+#: ../../source/api_reference/configurations.rst:43
+msgid "LMCACHE_LOCAL_CPU_USE_HUGEPAGES"
+msgstr "LMCACHE_LOCAL_CPU_USE_HUGEPAGES"
+
+#: ../../source/api_reference/configurations.rst:44
+msgid ""
+"Whether to use Linux hugepages (2 MB) for CPU-pinned KV cache memory. Not"
+" compatible with P2P mode or shared memory (multiprocess). Requires pre-"
+"allocated hugepages (``sysctl vm.nr_hugepages``). Values: true/false. "
+"Default: false"
+msgstr ""
+"是否使用 Linux 大页（2 MB）作为 CPU 固定的 KV Cache 内存。不兼容 P2P 模式或共享内存（多进程）。需要预分配大页（\\"
+" ``sysctl vm.nr_hugepages``\\ ）。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:45
+msgid "local_disk"
+msgstr "local_disk"
+
+#: ../../source/api_reference/configurations.rst:46
+msgid "LMCACHE_LOCAL_DISK"
+msgstr "LMCACHE_LOCAL_DISK"
+
+#: ../../source/api_reference/configurations.rst:47
+msgid ""
+"Path (or comma-separated paths) to local disk cache directories. Format: "
+"``\"file:///path/to/cache\"`` or ``\"/path/a,/path/b\"`` for multi-device"
+" I/O. See ``local_disk_path_sharding`` for how paths are assigned to "
+"GPUs."
+msgstr ""
+"本地磁盘缓存目录的路径（或以逗号分隔的路径）。格式：\\ ``\"file:///path/to/cache\"`` 或 "
+"``\"/path/a,/path/b\"`` 用于多设备 I/O。有关路径如何分配给 GPU，请参见 "
+"``local_disk_path_sharding``\\ 。"
+
+#: ../../source/api_reference/configurations.rst:48
+msgid "local_disk_path_sharding"
+msgstr "local_disk_path_sharding"
+
+#: ../../source/api_reference/configurations.rst:49
+msgid "LMCACHE_LOCAL_DISK_PATH_SHARDING"
+msgstr "LMCACHE_LOCAL_DISK_PATH_SHARDING"
+
+#: ../../source/api_reference/configurations.rst:50
+#: ../../source/api_reference/configurations.rst:411
+msgid ""
+"Strategy for selecting a path when multiple paths are provided. Currently"
+" only ``\"by_gpu\"`` is supported, which selects paths based on GPU "
+"device ID (default: \"by_gpu\")."
+msgstr ""
+"当提供多个路径时选择路径的策略。目前仅支持 ``\"by_gpu\"``\\ ，该策略根据 GPU 设备 ID "
+"选择路径（默认值：\\\"by_gpu\\\"）。"
+
+#: ../../source/api_reference/configurations.rst:51
+msgid "max_local_disk_size"
+msgstr "max_local_disk_size"
+
+#: ../../source/api_reference/configurations.rst:52
+msgid "LMCACHE_MAX_LOCAL_DISK_SIZE"
+msgstr "LMCACHE_MAX_LOCAL_DISK_SIZE"
+
+#: ../../source/api_reference/configurations.rst:53
+msgid "Maximum disk cache size in GB. Default: 0.0"
+msgstr "最大磁盘缓存大小（以 GB 为单位）。默认值：0.0"
+
+#: ../../source/api_reference/configurations.rst:54
+msgid "remote_url"
+msgstr "remote_url"
+
+#: ../../source/api_reference/configurations.rst:55
+msgid "LMCACHE_REMOTE_URL"
+msgstr "LMCACHE_REMOTE_URL"
+
+#: ../../source/api_reference/configurations.rst:56
+msgid "Remote storage URL. Format: \"protocol://host:port\"."
+msgstr "远程存储 URL。格式：\\\"protocol://host:port\\\"。"
+
+#: ../../source/api_reference/configurations.rst:57
+msgid "remote_serde"
+msgstr "remote_serde"
+
+#: ../../source/api_reference/configurations.rst:58
+msgid "LMCACHE_REMOTE_SERDE"
+msgstr "LMCACHE_REMOTE_SERDE"
+
+#: ../../source/api_reference/configurations.rst:59
+msgid ""
+"Serialization format. Values: \"naive\" or \"cachegen\". Default: "
+"\"naive\""
+msgstr "序列化格式。值：\\\"naive\\\" 或 \\\"cachegen\\\"。默认值：\\\"naive\\\""
+
+#: ../../source/api_reference/configurations.rst:60
+msgid "save_decode_cache"
+msgstr "save_decode_cache"
+
+#: ../../source/api_reference/configurations.rst:61
+msgid "LMCACHE_SAVE_DECODE_CACHE"
+msgstr "LMCACHE_SAVE_DECODE_CACHE"
+
+#: ../../source/api_reference/configurations.rst:62
+msgid "Whether to store decode KV cache. Values: true/false. Default: false"
+msgstr "是否存储解码 KV Cache。值：true/false。默认：false"
+
+#: ../../source/api_reference/configurations.rst:63
+msgid "use_layerwise"
+msgstr "use_layerwise"
+
+#: ../../source/api_reference/configurations.rst:64
+msgid "LMCACHE_USE_LAYERWISE"
+msgstr "LMCACHE_USE_LAYERWISE"
+
+#: ../../source/api_reference/configurations.rst:65
+msgid "Whether to enable layerwise pipelining. Values: true/false. Default: false"
+msgstr "是否启用逐层流水线。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:66
+msgid "pre_caching_hash_algorithm"
+msgstr "pre_caching_hash_algorithm"
+
+#: ../../source/api_reference/configurations.rst:67
+msgid "LMCACHE_PRE_CACHING_HASH_ALGORITHM"
+msgstr "LMCACHE_PRE_CACHING_HASH_ALGORITHM"
+
+#: ../../source/api_reference/configurations.rst:68
+msgid "Hash algorithm for prefix-caching. Default: \"builtin\""
+msgstr "前缀缓存的哈希算法。默认值：“builtin”"
+
+#: ../../source/api_reference/configurations.rst:69
+msgid "save_unfull_chunk"
+msgstr "save_unfull_chunk"
+
+#: ../../source/api_reference/configurations.rst:70
+msgid "LMCACHE_SAVE_UNFULL_CHUNK"
+msgstr "LMCACHE_SAVE_UNFULL_CHUNK"
+
+#: ../../source/api_reference/configurations.rst:71
+msgid "Whether to save unfull chunks. Values: true/false. Default: false"
+msgstr "是否保存未满块。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:72
+msgid "blocking_timeout_secs"
+msgstr "blocking_timeout_secs"
+
+#: ../../source/api_reference/configurations.rst:73
+msgid "LMCACHE_BLOCKING_TIMEOUT_SECS"
+msgstr "LMCACHE_BLOCKING_TIMEOUT_SECS"
+
+#: ../../source/api_reference/configurations.rst:74
+msgid "Timeout for blocking operations in seconds. Default: 10"
+msgstr "阻塞操作的超时时间（以秒为单位）。默认值：10"
+
+#: ../../source/api_reference/configurations.rst:75
+msgid "py_enable_gc"
+msgstr "py_enable_gc"
+
+#: ../../source/api_reference/configurations.rst:76
+msgid "LMCACHE_PY_ENABLE_GC"
+msgstr "LMCACHE_PY_ENABLE_GC"
+
+#: ../../source/api_reference/configurations.rst:77
+msgid ""
+"Whether to enable Python garbage collection. Values: true/false. Default:"
+" true"
+msgstr "是否启用 Python 垃圾回收。值：true/false。默认：true"
+
+#: ../../source/api_reference/configurations.rst:78
+msgid "cache_policy"
+msgstr "cache_policy"
+
+#: ../../source/api_reference/configurations.rst:79
+msgid "LMCACHE_CACHE_POLICY"
+msgstr "LMCACHE_CACHE_POLICY"
+
+#: ../../source/api_reference/configurations.rst:80
+msgid "Cache eviction policy (e.g. \"LRU\", \"LFU\", \"FIFO\"). Default: \"LRU\""
+msgstr "缓存逐出策略（例如“LRU”、“LFU”、“FIFO”）。默认值：“LRU”"
+
+#: ../../source/api_reference/configurations.rst:81
+msgid "numa_mode"
+msgstr "numa_mode"
+
+#: ../../source/api_reference/configurations.rst:82
+msgid "LMCACHE_NUMA_MODE"
+msgstr "LMCACHE_NUMA_MODE"
+
+#: ../../source/api_reference/configurations.rst:83
+msgid ""
+"NUMA-aware memory allocation mode. Values: \"auto\" (detect from system),"
+" \"manual\" (use extra_config mapping), null (disabled). When enabled, "
+"allocates pinned memory on specific NUMA nodes for better GPU-CPU memory "
+"bandwidth. Default: null"
+msgstr ""
+"NUMA 感知内存分配模式。值：\\\"auto\\\"（从系统检测）、\\\"manual\\\"（使用 extra_config "
+"映射）、null（禁用）。启用时，在特定的 NUMA 节点上分配固定内存，以提高 GPU-CPU 内存带宽。默认值：null"
+
+#: ../../source/api_reference/configurations.rst:84
+msgid "external_lookup_client"
+msgstr "external_lookup_client"
+
+#: ../../source/api_reference/configurations.rst:85
+msgid "LMCACHE_EXTERNAL_LOOKUP_CLIENT"
+msgstr "LMCACHE_EXTERNAL_LOOKUP_CLIENT"
+
+#: ../../source/api_reference/configurations.rst:86
+msgid ""
+"External KV lookup service URI (e.g., \"mooncakestore://address\"). If "
+"null, defaults to LMCache's internal lookup client. Default: null"
+msgstr ""
+"外部 KV 查找服务 URI（例如，\\\"mooncakestore://address\\\"）。如果为 null，则默认为 LMCache "
+"的内部查找客户端。默认值：null"
+
+#: ../../source/api_reference/configurations.rst:87
+msgid "priority_limit"
+msgstr "priority_limit"
+
+#: ../../source/api_reference/configurations.rst:88
+msgid "LMCACHE_PRIORITY_LIMIT"
+msgstr "LMCACHE_PRIORITY_LIMIT"
+
+#: ../../source/api_reference/configurations.rst:89
+msgid ""
+"Caches requests only if priority value ≤ limit. (**Not applicable for PD "
+"Disaggregation**) Type: int. Default: None"
+msgstr "仅在优先级值 ≤ 限制时缓存请求。（\\ **不适用于 PD 分离**\\ ）类型：int。默认值：无"
+
+#: ../../source/api_reference/configurations.rst:90
+msgid "min_retrieve_tokens"
+msgstr "min_retrieve_tokens"
+
+#: ../../source/api_reference/configurations.rst:91
+msgid "LMCACHE_MIN_RETRIEVE_TOKENS"
+msgstr "LMCACHE_MIN_RETRIEVE_TOKENS"
+
+#: ../../source/api_reference/configurations.rst:92
+msgid ""
+"Minimum number of hit tokens required to perform retrieve. If hit tokens "
+"< this value, skip retrieve but still record the hits to avoid re-storing"
+" existing chunks. See :ref:`performance_tuning` for a working example. "
+"Default: 0 (disabled)"
+msgstr ""
+"执行检索所需的最小命中令牌数。如果命中令牌少于此值，则跳过检索，但仍记录命中以避免重新存储现有块。有关工作示例，请参见 "
+":ref:`performance_tuning`。默认值：0（禁用）"
+
+#: ../../source/api_reference/configurations.rst:93
+msgid "store_location"
+msgstr "store_location"
+
+#: ../../source/api_reference/configurations.rst:94
+msgid "LMCACHE_STORE_LOCATION"
+msgstr "LMCACHE_STORE_LOCATION"
+
+#: ../../source/api_reference/configurations.rst:95
+msgid ""
+"A single storage backend name to store KV caches into. When specified, "
+"only the matching backend receives store operations. Valid values are the"
+" backend class names registered in the storage manager, including: "
+"``\"LocalCPUBackend\"``, ``\"LocalDiskBackend\"``, ``\"RemoteBackend\"``,"
+" ``\"PDBackend\"``, ``\"P2PBackend\"``, ``\"GdsBackend\"``, etc, and any "
+"storage plugin backends. Note: ``\"PDBackend\"`` cannot be used as a "
+"store location for a decoder instance in a PD setup, since PDBackend is "
+"one-way from prefiller to decoder only. Default: null (store to all "
+"active backends)"
+msgstr ""
+"一个存储后端名称，用于存储 KV 缓存。当指定时，只有匹配的后端接收存储操作。有效值是存储管理器中注册的后端类名称，包括：\\ "
+"``\\\"LocalCPUBackend\\\"``\\ 、\\ ``\\\"LocalDiskBackend\\\"``\\ 、\\ "
+"``\\\"RemoteBackend\\\"``\\ 、\\ ``\\\"PDBackend\\\"``\\ 、\\ "
+"``\\\"P2PBackend\\\"``\\ 、\\ ``\\\"GdsBackend\\\"`` 等，以及任何存储插件后端。注意：\\ "
+"``\\\"PDBackend\\\"`` 不能用作 PD 设置中解码器实例的存储位置，因为 PDBackend "
+"仅从预填充器到解码器是单向的。默认值：null（存储到所有活动后端）"
+
+#: ../../source/api_reference/configurations.rst:96
+msgid "retrieve_locations"
+msgstr "retrieve_locations"
+
+#: ../../source/api_reference/configurations.rst:97
+msgid "LMCACHE_RETRIEVE_LOCATIONS"
+msgstr "LMCACHE_RETRIEVE_LOCATIONS"
+
+#: ../../source/api_reference/configurations.rst:98
+msgid ""
+"List of storage backend names to search when retrieving or looking up KV "
+"caches. When specified, only the listed backends are searched. Valid "
+"values are the backend class names registered in the storage manager, "
+"including: ``\"LocalCPUBackend\"``, ``\"LocalDiskBackend\"``, "
+"``\"RemoteBackend\"``, ``\"PDBackend\"``, ``\"P2PBackend\"``, "
+"``\"GdsBackend\"``, etc, and any storage plugin backends. Default: null "
+"(search all active backends)"
+msgstr ""
+"检索或查找 KV Cache 时要搜索的存储后端名称列表。当指定时，仅搜索列出的后端。有效值为在存储管理器中注册的后端类名称，包括：\\ "
+"``\\\"LocalCPUBackend\\\"``\\ 、\\ ``\\\"LocalDiskBackend\\\"``\\ 、\\ "
+"``\\\"RemoteBackend\\\"``\\ 、\\ ``\\\"PDBackend\\\"``\\ 、\\ "
+"``\\\"P2PBackend\\\"``\\ 、\\ ``\\\"GdsBackend\\\"`` "
+"等，以及任何存储插件后端。默认值：null（搜索所有活动后端）"
+
+#: ../../source/api_reference/configurations.rst:99
+msgid "extra_config"
+msgstr "extra_config"
+
+#: ../../source/api_reference/configurations.rst:100
+#, python-brace-format
+msgid "LMCACHE_EXTRA_CONFIG={\"key\": value, ...}"
+msgstr "LMCACHE_EXTRA_CONFIG={\\\"key\\\": value, ...}"
+
+#: ../../source/api_reference/configurations.rst:101
+#, python-brace-format
+msgid ""
+"Additional configuration as JSON dict. For NUMA manual mode, include "
+"\"gpu_to_numa_mapping\": {gpu_id: numa_node, ...}. Default: {}"
+msgstr ""
+"额外的配置作为 JSON 字典。对于 NUMA 手动模式，包含 \\\"gpu_to_numa_mapping\\\": {gpu_id: "
+"numa_node, ...}。默认值：{}"
+
+#: ../../source/api_reference/configurations.rst:104
+msgid "Lazy Memory Allocator Configurations"
+msgstr "惰性内存分配器配置"
+
+#: ../../source/api_reference/configurations.rst:106
+msgid ""
+"Settings for the lazy memory allocator that enables gradual memory "
+"allocation to reduce startup time and initial memory footprint."
+msgstr "用于懒惰内存分配器的设置，允许逐步分配内存以减少启动时间和初始内存占用。"
+
+#: ../../source/api_reference/configurations.rst:110
+msgid ""
+"The lazy memory allocator is designed for scenarios with large CPU memory"
+" configurations. It starts with a small initial allocation and gradually "
+"expands as needed, reducing startup wait time and avoiding unnecessary "
+"memory consumption when the full capacity is not required."
+msgstr ""
+"懒惰内存分配器旨在处理大 CPU "
+"内存配置的场景。它从小的初始分配开始，并根据需要逐渐扩展，从而减少启动等待时间，并避免在不需要全部容量时的不必要内存消耗。"
+
+#: ../../source/api_reference/configurations.rst:112
+msgid "**Key characteristics:**"
+msgstr "**关键特性：**"
+
+#: ../../source/api_reference/configurations.rst:114
+msgid ""
+"**One-time expansion**: Memory expands until target size is reached, then"
+" stops"
+msgstr "**一次性扩展**\\ ：内存扩展直到达到目标大小，然后停止"
+
+#: ../../source/api_reference/configurations.rst:115
+msgid ""
+"**No shrinking**: Once allocated, memory is never released back to the "
+"system"
+msgstr "**不收缩**\\ ：一旦分配，内存将永远不会释放回系统"
+
+#: ../../source/api_reference/configurations.rst:116
+msgid ""
+"**Automatic activation**: Only activates when ``max_local_cpu_size`` "
+"exceeds ``lazy_memory_safe_size``"
+msgstr "**自动激活**\\ ：仅在 ``max_local_cpu_size`` 超过 ``lazy_memory_safe_size`` 时激活"
+
+#: ../../source/api_reference/configurations.rst:125
+msgid "enable_lazy_memory_allocator"
+msgstr "enable_lazy_memory_allocator"
+
+#: ../../source/api_reference/configurations.rst:126
+msgid "LMCACHE_ENABLE_LAZY_MEMORY_ALLOCATOR"
+msgstr "LMCACHE_ENABLE_LAZY_MEMORY_ALLOCATOR"
+
+#: ../../source/api_reference/configurations.rst:127
+msgid ""
+"Whether to enable lazy memory allocator. Values: true/false. Default: "
+"false"
+msgstr "是否启用延迟内存分配器。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:128
+msgid "lazy_memory_initial_ratio"
+msgstr "lazy_memory_initial_ratio"
+
+#: ../../source/api_reference/configurations.rst:129
+msgid "LMCACHE_LAZY_MEMORY_INITIAL_RATIO"
+msgstr "LMCACHE_LAZY_MEMORY_INITIAL_RATIO"
+
+#: ../../source/api_reference/configurations.rst:130
+msgid ""
+"Initial memory allocation ratio (0.0-1.0). Determines the fraction of "
+"max_local_cpu_size to allocate at startup. Default: 0.2 (20%)"
+msgstr "初始内存分配比例 (0.0-1.0)。决定在启动时分配的 max_local_cpu_size 的比例。默认值：0.2 (20%)"
+
+#: ../../source/api_reference/configurations.rst:131
+msgid "lazy_memory_expand_trigger_ratio"
+msgstr "lazy_memory_expand_trigger_ratio"
+
+#: ../../source/api_reference/configurations.rst:132
+msgid "LMCACHE_LAZY_MEMORY_EXPAND_TRIGGER_RATIO"
+msgstr "LMCACHE_LAZY_MEMORY_EXPAND_TRIGGER_RATIO"
+
+#: ../../source/api_reference/configurations.rst:133
+msgid ""
+"Memory usage ratio (0.0-1.0) that triggers expansion. When used memory "
+"exceeds this ratio of current capacity, expansion begins. Default: 0.5 "
+"(50%)"
+msgstr "触发扩展的内存使用比例（0.0-1.0）。当使用的内存超过当前容量的此比例时，扩展开始。默认值：0.5（50%）"
+
+#: ../../source/api_reference/configurations.rst:134
+msgid "lazy_memory_step_ratio"
+msgstr "lazy_memory_step_ratio"
+
+#: ../../source/api_reference/configurations.rst:135
+msgid "LMCACHE_LAZY_MEMORY_STEP_RATIO"
+msgstr "LMCACHE_LAZY_MEMORY_STEP_RATIO"
+
+#: ../../source/api_reference/configurations.rst:136
+msgid ""
+"Memory expansion step ratio (0.0-1.0). Each expansion adds this fraction "
+"of max_local_cpu_size. Default: 0.1 (10%)"
+msgstr "内存扩展步骤比例（0.0-1.0）。每次扩展增加此比例的 max_local_cpu_size。默认值：0.1（10%）"
+
+#: ../../source/api_reference/configurations.rst:137
+msgid "lazy_memory_safe_size"
+msgstr "lazy_memory_safe_size"
+
+#: ../../source/api_reference/configurations.rst:138
+msgid "LMCACHE_LAZY_MEMORY_SAFE_SIZE"
+msgstr "LMCACHE_LAZY_MEMORY_SAFE_SIZE"
+
+#: ../../source/api_reference/configurations.rst:139
+msgid ""
+"Threshold in GB above which lazy allocator activates. If "
+"max_local_cpu_size ≤ this value, lazy allocator is disabled regardless of"
+" enable_lazy_memory_allocator setting. Default: 0.0"
+msgstr ""
+"在 GB 中的阈值，超过该值后懒惰分配器激活。如果 max_local_cpu_size ≤ 此值，则无论 "
+"enable_lazy_memory_allocator 设置如何，懒惰分配器都将被禁用。默认值：0.0"
+
+#: ../../source/api_reference/configurations.rst:140
+msgid "reserve_local_cpu_size"
+msgstr "reserve_local_cpu_size"
+
+#: ../../source/api_reference/configurations.rst:141
+msgid "LMCACHE_RESERVE_LOCAL_CPU_SIZE"
+msgstr "LMCACHE_RESERVE_LOCAL_CPU_SIZE"
+
+#: ../../source/api_reference/configurations.rst:142
+msgid ""
+"Reserved system memory in GB that should not be allocated by LMCache. "
+"Used to prevent out-of-memory conditions. Default: 0.0"
+msgstr "保留的系统内存（以 GB 为单位），不应由 LMCache 分配。用于防止内存不足的情况。默认值：0.0"
+
+#: ../../source/api_reference/configurations.rst:145
+msgid "Cache Blending Configurations"
+msgstr "缓存混合配置"
+
+#: ../../source/api_reference/configurations.rst:147
+msgid "Settings related to cache blending functionality."
+msgstr "与缓存混合功能相关的设置。"
+
+#: ../../source/api_reference/configurations.rst:151
+msgid ""
+"We have an end-to-end `example "
+"<https://github.com/LMCache/LMCache/tree/dev/examples/blend_kv_v1>`_. We "
+"also have more :doc:`detailed documentation "
+"<../kv_cache_optimizations/blending>`."
+msgstr ""
+"我们有一个端到端的 `示例 "
+"<https://github.com/LMCache/LMCache/tree/dev/examples/blend_kv_v1>`_。我们还有更多的"
+" :doc:`详细文档 <../kv_cache_optimizations/blending>`。"
+
+#: ../../source/api_reference/configurations.rst:161
+msgid "enable_blending"
+msgstr "enable_blending"
+
+#: ../../source/api_reference/configurations.rst:162
+msgid "LMCACHE_ENABLE_BLENDING"
+msgstr "LMCACHE_ENABLE_BLENDING"
+
+#: ../../source/api_reference/configurations.rst:163
+msgid "Whether to enable blending. Values: true/false. Default: false"
+msgstr "是否启用混合。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:164
+msgid "blend_recompute_ratios"
+msgstr "blend_recompute_ratios"
+
+#: ../../source/api_reference/configurations.rst:165
+msgid "LMCACHE_BLEND_RECOMPUTE_RATIOS"
+msgstr "LMCACHE_BLEND_RECOMPUTE_RATIOS"
+
+#: ../../source/api_reference/configurations.rst:166
+msgid "Ratio of blending recompute. Default: 0.15"
+msgstr "混合重计算的比例。默认值：0.15"
+
+#: ../../source/api_reference/configurations.rst:167
+msgid "blend_check_layers"
+msgstr "blend_check_layers"
+
+#: ../../source/api_reference/configurations.rst:168
+msgid "LMCACHE_BLEND_CHECK_LAYERS"
+msgstr "LMCACHE_BLEND_CHECK_LAYERS"
+
+#: ../../source/api_reference/configurations.rst:169
+msgid "Layers to determine the recomputed tokens. Default: 1"
+msgstr "确定重计算令牌的层数。默认值：1"
+
+#: ../../source/api_reference/configurations.rst:170
+msgid "blend_special_str"
+msgstr "blend_special_str"
+
+#: ../../source/api_reference/configurations.rst:171
+msgid "LMCACHE_BLEND_SPECIAL_STR"
+msgstr "LMCACHE_BLEND_SPECIAL_STR"
+
+#: ../../source/api_reference/configurations.rst:172
+msgid "Separator string for blending. Default: \" # # \""
+msgstr "用于混合的分隔符字符串。默认值：\\\" # # \\\""
+
+#: ../../source/api_reference/configurations.rst:175
+msgid "Peer-to-Peer Sharing Configurations"
+msgstr "点对点共享配置"
+
+#: ../../source/api_reference/configurations.rst:177
+msgid ""
+"Settings for enabling and configuring peer-to-peer CPU KV cache sharing "
+"and global KV cache lookup."
+msgstr "用于启用和配置点对点 CPU KV Cache 共享及全局 KV Cache 查找的设置。"
+
+#: ../../source/api_reference/configurations.rst:186
+msgid "enable_p2p"
+msgstr "enable_p2p"
+
+#: ../../source/api_reference/configurations.rst:187
+msgid "LMCACHE_ENABLE_P2P"
+msgstr "LMCACHE_ENABLE_P2P"
+
+#: ../../source/api_reference/configurations.rst:188
+msgid "Whether to enable peer-to-peer sharing. Values: true/false. Default: false"
+msgstr "是否启用点对点共享。值：true/false。默认：false"
+
+#: ../../source/api_reference/configurations.rst:189
+msgid "p2p_host"
+msgstr "p2p_host"
+
+#: ../../source/api_reference/configurations.rst:190
+msgid "LMCACHE_P2P_HOST"
+msgstr "LMCACHE_P2P_HOST"
+
+#: ../../source/api_reference/configurations.rst:191
+msgid "Ip address. Required if enable_p2p is true"
+msgstr "IP 地址。如果 enable_p2p 为 true，则必需。"
+
+#: ../../source/api_reference/configurations.rst:192
+msgid "peer_init_ports"
+msgstr "peer_init_ports"
+
+#: ../../source/api_reference/configurations.rst:193
+msgid "LMCACHE_PEER_INIT_PORTS"
+msgstr "LMCACHE_PEER_INIT_PORTS"
+
+#: ../../source/api_reference/configurations.rst:194
+msgid "Ports for p2p peer init. Required if enable_p2p is true"
+msgstr "p2p 对等初始化的端口。如果 enable_p2p 为 true，则需要此项。"
+
+#: ../../source/api_reference/configurations.rst:195
+msgid "peer_lookup_ports"
+msgstr "peer_lookup_ports"
+
+#: ../../source/api_reference/configurations.rst:196
+msgid "LMCACHE_PEER_lookup_PORTS"
+msgstr "LMCACHE_PEER_lookup_PORTS"
+
+#: ../../source/api_reference/configurations.rst:197
+msgid "Ports for p2p peer lookup. Required if enable_p2p is true"
+msgstr "用于点对点（p2p）对等查找的端口。如果 enable_p2p 为 true，则必需。"
+
+#: ../../source/api_reference/configurations.rst:198
+#: ../../source/api_reference/configurations.rst:250
+msgid "transfer_channel"
+msgstr "transfer_channel"
+
+#: ../../source/api_reference/configurations.rst:199
+#: ../../source/api_reference/configurations.rst:251
+msgid "LMCACHE_TRANSFER_CHANNEL"
+msgstr "LMCACHE_TRANSFER_CHANNEL"
+
+#: ../../source/api_reference/configurations.rst:200
+msgid "Such as `nixl`. Required if enable_p2p is true"
+msgstr "例如 `nixl`。如果 enable_p2p 为 true，则必需。"
+
+#: ../../source/api_reference/configurations.rst:203
+msgid "Controller Configurations"
+msgstr "控制器配置"
+
+#: ../../source/api_reference/configurations.rst:205
+msgid "Settings for the KV cache controller functionality."
+msgstr "KV 缓存控制器功能的设置。"
+
+#: ../../source/api_reference/configurations.rst:214
+msgid "enable_controller"
+msgstr "enable_controller"
+
+#: ../../source/api_reference/configurations.rst:215
+msgid "LMCACHE_ENABLE_CONTROLLER"
+msgstr "LMCACHE_ENABLE_CONTROLLER"
+
+#: ../../source/api_reference/configurations.rst:216
+msgid "Whether to enable controller. Values: true/false. Default: false"
+msgstr "是否启用控制器。值：true/false。默认：false"
+
+#: ../../source/api_reference/configurations.rst:217
+msgid "lmcache_instance_id"
+msgstr "lmcache_instance_id"
+
+#: ../../source/api_reference/configurations.rst:218
+msgid "LMCACHE_LMCACHE_INSTANCE_ID"
+msgstr "LMCACHE_LMCACHE_INSTANCE_ID"
+
+#: ../../source/api_reference/configurations.rst:219
+msgid "ID of the LMCache instance. Default: \"lmcache_default_instance\""
+msgstr "LMCache 实例的 ID。默认值：\\\"lmcache_default_instance\\\""
+
+#: ../../source/api_reference/configurations.rst:220
+msgid "controller_url"
+msgstr "controller_url"
+
+#: ../../source/api_reference/configurations.rst:221
+msgid "LMCACHE_CONTROLLER_URL"
+msgstr "LMCACHE_CONTROLLER_URL"
+
+#: ../../source/api_reference/configurations.rst:222
+msgid "URL of the controller server"
+msgstr "控制器服务器的 URL"
+
+#: ../../source/api_reference/configurations.rst:223
+msgid "lmcache_worker_port"
+msgstr "lmcache_worker_port"
+
+#: ../../source/api_reference/configurations.rst:224
+msgid "LMCACHE_LMCACHE_WORKER_PORT"
+msgstr "LMCACHE_LMCACHE_WORKER_PORT"
+
+#: ../../source/api_reference/configurations.rst:225
+msgid "Port number for LMCache worker"
+msgstr "LMCache 工作进程的端口号"
+
+#: ../../source/api_reference/configurations.rst:228
+msgid "Disaggregated Prefill Configurations"
+msgstr "分离式 Prefill 配置"
+
+#: ../../source/api_reference/configurations.rst:230
+msgid ""
+"Settings for disaggregated prefill functionality. The latest/default PD "
+"is implemented inside of `lmcache/v1/storage_backend/pd_backend.py`."
+msgstr ""
+"分离式 Prefill 功能的设置。最新/默认的 PD 实现在 "
+"`lmcache/v1/storage_backend/pd_backend.py` 中。"
+
+#: ../../source/api_reference/configurations.rst:234
+msgid ""
+"When PD is enabled, the following restrictions apply (welcome "
+"contributions to remove these restrictions):"
+msgstr "启用 PD 时，以下限制适用（欢迎贡献以消除这些限制）："
+
+#: ../../source/api_reference/configurations.rst:236
+msgid "remote_url must be null"
+msgstr "remote_url 必须为 null"
+
+#: ../../source/api_reference/configurations.rst:237
+msgid "save_decode_cache must be false"
+msgstr "save_decode_cache 必须为 false"
+
+#: ../../source/api_reference/configurations.rst:238
+msgid "enable_p2p must be false"
+msgstr "enable_p2p 必须为 false"
+
+#: ../../source/api_reference/configurations.rst:247
+msgid "enable_pd"
+msgstr "enable_pd"
+
+#: ../../source/api_reference/configurations.rst:248
+msgid "LMCACHE_ENABLE_PD"
+msgstr "LMCACHE_ENABLE_PD"
+
+#: ../../source/api_reference/configurations.rst:249
+msgid "Whether to enable PD. Values: true/false. Default: false"
+msgstr "是否启用 PD。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:252
+msgid "Transfer channel used for PD. Values: \"nixl\". Default: none"
+msgstr "用于 PD 的传输通道。值：“nixl”。默认：无"
+
+#: ../../source/api_reference/configurations.rst:253
+msgid "pd_role"
+msgstr "pd_role"
+
+#: ../../source/api_reference/configurations.rst:254
+msgid "LMCACHE_PD_ROLE"
+msgstr "LMCACHE_PD_ROLE"
+
+#: ../../source/api_reference/configurations.rst:255
+msgid "PD role. Values: \"sender\" (prefiller) or \"receiver\" (decoder)."
+msgstr "PD 角色。值：\\\"sender\\\"（预填充器）或 \\\"receiver\\\"（解码器）。"
+
+#: ../../source/api_reference/configurations.rst:256
+msgid "pd_buffer_size"
+msgstr "pd_buffer_size"
+
+#: ../../source/api_reference/configurations.rst:257
+msgid "LMCACHE_PD_BUFFER_SIZE"
+msgstr "LMCACHE_PD_BUFFER_SIZE"
+
+#: ../../source/api_reference/configurations.rst:258
+msgid ""
+"Upper bound of PD transport buffer size (in bytes), aligned to chunk "
+"size. Required for both senders and receivers when enable_pd=true"
+msgstr "PD 传输缓冲区大小的上限（以字节为单位），与块大小对齐。当 enable_pd=true 时，发送方和接收方均需要此设置。"
+
+#: ../../source/api_reference/configurations.rst:259
+msgid "pd_buffer_device"
+msgstr "pd_buffer_device"
+
+#: ../../source/api_reference/configurations.rst:260
+msgid "LMCACHE_PD_BUFFER_DEVICE"
+msgstr "LMCACHE_PD_BUFFER_DEVICE"
+
+#: ../../source/api_reference/configurations.rst:261
+msgid ""
+"Device for PD buffer. Values: \"cpu\", \"cuda\". Required for both "
+"senders and receivers when enable_pd=true"
+msgstr "PD 缓冲区的设备。值：\\\"cpu\\\"，\\\"cuda\\\"。当 enable_pd=true 时，发送者和接收者都需要此项。"
+
+#: ../../source/api_reference/configurations.rst:262
+msgid "nixl_backends"
+msgstr "nixl_backends"
+
+#: ../../source/api_reference/configurations.rst:263
+msgid "LMCACHE_NIXL_BACKENDS"
+msgstr "LMCACHE_NIXL_BACKENDS"
+
+#: ../../source/api_reference/configurations.rst:264
+msgid ""
+"List of Nixl transport backends. Useful for non-disaggregated use case "
+"(see below). UCX default is sufficient for disagg use case. Default: "
+"[\"UCX\"]"
+msgstr "Nixl 传输后端列表。适用于非分离式用例（见下文）。UCX 默认设置足以满足分离式用例。默认值：[\\\"UCX\\\"]"
+
+#: ../../source/api_reference/configurations.rst:265
+msgid "pd_peer_host"
+msgstr "pd_peer_host"
+
+#: ../../source/api_reference/configurations.rst:266
+msgid "LMCACHE_PD_PEER_HOST"
+msgstr "LMCACHE_PD_PEER_HOST"
+
+#: ../../source/api_reference/configurations.rst:267
+msgid "Host for peer connections. Required for receivers to bind to"
+msgstr "对等连接的主机。接收方绑定所需。"
+
+#: ../../source/api_reference/configurations.rst:268
+msgid "pd_peer_init_port"
+msgstr "pd_peer_init_port"
+
+#: ../../source/api_reference/configurations.rst:269
+msgid "LMCACHE_PD_PEER_INIT_PORT"
+msgstr "LMCACHE_PD_PEER_INIT_PORT"
+
+#: ../../source/api_reference/configurations.rst:270
+msgid ""
+"Initialization port for peer connections. Required for receivers to bind "
+"to"
+msgstr "用于对等连接的初始化端口。接收方需要绑定到此端口。"
+
+#: ../../source/api_reference/configurations.rst:271
+msgid "pd_peer_alloc_port"
+msgstr "pd_peer_alloc_port"
+
+#: ../../source/api_reference/configurations.rst:272
+msgid "LMCACHE_PD_PEER_ALLOC_PORT"
+msgstr "LMCACHE_PD_PEER_ALLOC_PORT"
+
+#: ../../source/api_reference/configurations.rst:273
+msgid "Allocation port for peer connections. Required for receivers to bind to"
+msgstr "用于对等连接的分配端口。接收方需要绑定到此端口。"
+
+#: ../../source/api_reference/configurations.rst:274
+msgid "pd_proxy_host"
+msgstr "pd_proxy_host"
+
+#: ../../source/api_reference/configurations.rst:275
+msgid "LMCACHE_PD_PROXY_HOST"
+msgstr "LMCACHE_PD_PROXY_HOST"
+
+#: ../../source/api_reference/configurations.rst:276
+msgid ""
+"Host for proxy server. Required for senders to connect to inform the "
+"proxy when transfer to decoder has been completed"
+msgstr "代理服务器的主机。发送方连接以通知代理解码器传输完成时必需。"
+
+#: ../../source/api_reference/configurations.rst:277
+msgid "pd_proxy_port"
+msgstr "pd_proxy_port"
+
+#: ../../source/api_reference/configurations.rst:278
+msgid "LMCACHE_PD_PROXY_PORT"
+msgstr "LMCACHE_PD_PROXY_PORT"
+
+#: ../../source/api_reference/configurations.rst:279
+msgid ""
+"Port for proxy server. Required for senders to connect to inform the "
+"proxy when transfer to decoder has been completed"
+msgstr "代理服务器的端口。发送方需要连接以通知代理传输到解码器已完成。"
+
+#: ../../source/api_reference/configurations.rst:280
+msgid "pd_allocation_timeout_sec"
+msgstr "pd_allocation_timeout_sec"
+
+#: ../../source/api_reference/configurations.rst:281
+msgid "LMCACHE_PD_ALLOCATION_TIMEOUT_SEC"
+msgstr "LMCACHE_PD_ALLOCATION_TIMEOUT_SEC"
+
+#: ../../source/api_reference/configurations.rst:282
+msgid "Maximum seconds to retry memory allocation before giving up. Default: 5.0"
+msgstr "在放弃之前重试内存分配的最大秒数。默认值：5.0"
+
+#: ../../source/api_reference/configurations.rst:283
+msgid "pd_shutdown_timeout_sec"
+msgstr "pd_shutdown_timeout_sec"
+
+#: ../../source/api_reference/configurations.rst:284
+msgid "LMCACHE_PD_SHUTDOWN_TIMEOUT_SEC"
+msgstr "LMCACHE_PD_SHUTDOWN_TIMEOUT_SEC"
+
+#: ../../source/api_reference/configurations.rst:285
+msgid ""
+"Maximum seconds to wait for event loop shutdown and thread join. Default:"
+" 5.0"
+msgstr "事件循环关闭和线程加入的最大等待秒数。默认值：5.0"
+
+#: ../../source/api_reference/configurations.rst:286
+msgid "pd_condition_poll_interval_sec"
+msgstr "pd_condition_poll_interval_sec"
+
+#: ../../source/api_reference/configurations.rst:287
+msgid "LMCACHE_PD_CONDITION_POLL_INTERVAL_SEC"
+msgstr "LMCACHE_PD_CONDITION_POLL_INTERVAL_SEC"
+
+#: ../../source/api_reference/configurations.rst:288
+msgid ""
+"Polling interval in seconds when waiting on a threading/asyncio "
+"Condition. Small enough to be responsive, large enough not to spin-waste "
+"CPU. Default: 0.05"
+msgstr "在等待线程/asyncio Condition 时的轮询间隔（以秒为单位）。足够小以保持响应，足够大以避免浪费 CPU。默认值：0.05"
+
+#: ../../source/api_reference/configurations.rst:289
+msgid "pd_max_prefill_len"
+msgstr "pd_max_prefill_len"
+
+#: ../../source/api_reference/configurations.rst:290
+msgid "LMCACHE_PD_MAX_PREFILL_LEN"
+msgstr "LMCACHE_PD_MAX_PREFILL_LEN"
+
+#: ../../source/api_reference/configurations.rst:291
+msgid ""
+"Maximum prefill token length that the PD buffer must be able to hold. If "
+"> 0, initialization raises ValueError when the buffer capacity (in "
+"tokens) is smaller than this value. Set to 0 (default) to skip the check."
+msgstr ""
+"PD 缓冲区必须能够容纳的最大 Prefill 令牌长度。如果大于 0，当缓冲区容量（以令牌为单位）小于此值时，初始化将引发 "
+"ValueError。设置为 0（默认值）以跳过检查。"
+
+#: ../../source/api_reference/configurations.rst:292
+msgid "pd_backend_mode"
+msgstr "pd_backend_mode"
+
+#: ../../source/api_reference/configurations.rst:293
+msgid "LMCACHE_PD_BACKEND_MODE"
+msgstr "LMCACHE_PD_BACKEND_MODE"
+
+#: ../../source/api_reference/configurations.rst:294
+msgid ""
+"Select the PD backend implementation: 'async' (default) uses the asyncio-"
+"based implementation; 'sync' uses the original thread-based synchronous "
+"implementation. Default: \"async\""
+msgstr ""
+"选择 PD 后端实现：'async'（默认）使用基于 asyncio 的实现；'sync' "
+"使用原始的基于线程的同步实现。默认值：\\\"async\\\""
+
+#: ../../source/api_reference/configurations.rst:295
+msgid "pd_skip_proxy_notification"
+msgstr "pd_skip_proxy_notification"
+
+#: ../../source/api_reference/configurations.rst:296
+msgid "LMCACHE_PD_SKIP_PROXY_NOTIFICATION"
+msgstr "LMCACHE_PD_SKIP_PROXY_NOTIFICATION"
+
+#: ../../source/api_reference/configurations.rst:297
+msgid ""
+"When true, the sender skips ZMQ proxy notification after KV transfer and "
+"does not require pd_proxy_host/pd_proxy_port. This option is intended for"
+" external orchestrators only (e.g., vLLM Production Stack router) that "
+"manage the prefill-decode request flow via HTTP and do not rely on ZMQ "
+"notifications. It must not be used with LMCache's built-in disaggregation"
+" proxy (``disagg_proxy_server.py``), which depends on ZMQ notifications "
+"to know when KV transfer is complete before forwarding the decode "
+"request. Values: true/false. Default: false"
+msgstr ""
+"当为真时，发送方在 KV 传输后跳过 ZMQ 代理通知，并且不需要 pd_proxy_host/pd_proxy_port。此选项仅适用于管理通过"
+" HTTP 的分离式解码请求流的外部调度器（例如，vLLM 生产堆栈路由器），并且不依赖于 ZMQ 通知。它不得与 LMCache "
+"的内置分离代理（\\ ``disagg_proxy_server.py``\\ ）一起使用，因为该代理依赖于 ZMQ 通知来知道 KV "
+"传输何时完成，然后再转发解码请求。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:298
+msgid "pd_bidirectional"
+msgstr "pd_bidirectional"
+
+#: ../../source/api_reference/configurations.rst:299
+msgid "LMCACHE_PD_BIDIRECTIONAL"
+msgstr "LMCACHE_PD_BIDIRECTIONAL"
+
+#: ../../source/api_reference/configurations.rst:300
+msgid ""
+"When true, enables bidirectional NIXL cache probe. The prefiller queries "
+"the decoder for cached KV blocks before transfer, and reads cached blocks"
+" via NIXL RDMA instead of recomputing. Values: true/false. Default: false"
+msgstr ""
+"当为真时，启用双向 NIXL 缓存探测。Prefiller 在传输之前查询解码器以获取缓存的 KV 块，并通过 NIXL RDMA "
+"读取缓存的块，而不是重计算。值：true/false。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:301
+msgid "pd_peer_query_port"
+msgstr "pd_peer_query_port"
+
+#: ../../source/api_reference/configurations.rst:302
+msgid "LMCACHE_PD_PEER_QUERY_PORT"
+msgstr "LMCACHE_PD_PEER_QUERY_PORT"
+
+#: ../../source/api_reference/configurations.rst:303
+msgid ""
+"ZMQ ports for the bidirectional cache query channel (one per TP rank). "
+"Required on both prefiller and decoder when pd_bidirectional=true. "
+"Example: [7500, 7501, 7502, 7503]"
+msgstr ""
+"用于双向缓存查询通道的 ZMQ 端口（每个 TP 排名一个）。当 pd_bidirectional=true "
+"时，预填充器和解码器都需要此配置。示例：[7500, 7501, 7502, 7503]"
+
+#: ../../source/api_reference/configurations.rst:306
+msgid "P2P Backend Configurations"
+msgstr "P2P 后端配置"
+
+#: ../../source/api_reference/configurations.rst:308
+msgid ""
+"Settings for P2P (peer-to-peer) backend timeout behavior. These "
+"configurations are specified through ``extra_config``."
+msgstr "P2P（点对点）后端超时行为的设置。这些配置通过 ``extra_config`` 指定。"
+
+#: ../../source/api_reference/configurations.rst:320
+#: ../../source/api_reference/configurations.rst:345
+#: ../../source/api_reference/configurations.rst:378
+msgid "Configuration Key"
+msgstr "配置键"
+
+#: ../../source/api_reference/configurations.rst:321
+#: ../../source/api_reference/configurations.rst:346
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/api_reference/configurations.rst:323
+msgid "p2p_socket_recv_timeout_ms"
+msgstr "p2p_socket_recv_timeout_ms"
+
+#: ../../source/api_reference/configurations.rst:324
+msgid "30000"
+msgstr "30000"
+
+#: ../../source/api_reference/configurations.rst:325
+msgid "Timeout in milliseconds for socket receive operations"
+msgstr "套接字接收操作的超时时间（以毫秒为单位）"
+
+#: ../../source/api_reference/configurations.rst:326
+msgid "p2p_socket_send_timeout_ms"
+msgstr "p2p_socket_send_timeout_ms"
+
+#: ../../source/api_reference/configurations.rst:327
+msgid "10000"
+msgstr "10000"
+
+#: ../../source/api_reference/configurations.rst:328
+msgid "Timeout in milliseconds for socket send operations"
+msgstr "套接字发送操作的超时时间（以毫秒为单位）"
+
+#: ../../source/api_reference/configurations.rst:331
+msgid "Disk I/O Backend Configurations"
+msgstr "磁盘 I/O 后端配置"
+
+#: ../../source/api_reference/configurations.rst:333
+msgid ""
+"Settings shared by disk-based storage backends (local disk and GDS). "
+"These configurations are specified through ``extra_config``."
+msgstr "由基于磁盘的存储后端（本地磁盘和 GDS）共享的设置。这些配置通过 ``extra_config`` 指定。"
+
+#: ../../source/api_reference/configurations.rst:348
+msgid "use_odirect"
+msgstr "use_odirect"
+
+#: ../../source/api_reference/configurations.rst:349
+msgid "false"
+msgstr "假"
+
+#: ../../source/api_reference/configurations.rst:350
+msgid ""
+"Enable O_DIRECT for disk I/O, bypassing the kernel page cache. "
+"Recommended when most local CPU memory is already used for KV cache "
+"offloading."
+msgstr "启用 O_DIRECT 进行磁盘 I/O，绕过内核页面缓存。当大多数本地 CPU 内存已用于 KV Cache 卸载时，建议使用此选项。"
+
+#: ../../source/api_reference/configurations.rst:351
+msgid "disk_io_threads"
+msgstr "disk_io_threads"
+
+#: ../../source/api_reference/configurations.rst:352
+msgid "4"
+msgstr "4"
+
+#: ../../source/api_reference/configurations.rst:353
+msgid ""
+"Number of worker threads in the disk I/O thread pool. Applies to both the"
+" local disk backend and the GDS backend. Increase for higher parallelism "
+"on fast NVMe drives. (Replaces the deprecated ``gds_io_threads`` key.)"
+msgstr "磁盘 I/O 线程池中的工作线程数量。适用于本地磁盘后端和 GDS 后端。在快速 NVMe 驱动器上增加以提高并行性。（替代已弃用的 ``gds_io_threads`` 键。）"
+
+#: ../../source/api_reference/configurations.rst:356
+msgid "Nixl (as a storage backend) Configurations"
+msgstr "Nixl（作为存储后端）配置"
+
+#: ../../source/api_reference/configurations.rst:358
+msgid ""
+"Settings for using Nixl as a storage backend instead of disaggregated "
+"prefill. This mode requires additional configurations in "
+"``extra_config``."
+msgstr "将 Nixl 用作存储后端而不是分离式 Prefill 的设置。此模式需要在 ``extra_config`` 中进行额外配置。"
+
+#: ../../source/api_reference/configurations.rst:362
+msgid ""
+"This is a different mode from disaggregated prefill. When using Nixl as a"
+" storage backend, you need to configure it through ``extra_config``."
+msgstr "这是一种不同于分离式 Prefill 的模式。当使用 Nixl 作为存储后端时，您需要通过 ``extra_config`` 进行配置。"
+
+#: ../../source/api_reference/configurations.rst:380
+msgid "enable_nixl_storage"
+msgstr "enable_nixl_storage"
+
+#: ../../source/api_reference/configurations.rst:381
+msgid "Whether to enable Nixl storage backend. Values: true/false"
+msgstr "是否启用 Nixl 存储后端。值：true/false"
+
+#: ../../source/api_reference/configurations.rst:382
+msgid "nixl_backend"
+msgstr "nixl_backend"
+
+#: ../../source/api_reference/configurations.rst:383
+msgid ""
+"Storage backend type. Options: \"GDS\", \"GDS_MT\", \"POSIX\", \"HF3FS\","
+" \"OBJ\""
+msgstr "存储后端类型。选项：“GDS”、“GDS_MT”、“POSIX”、“HF3FS”、“OBJ”"
+
+#: ../../source/api_reference/configurations.rst:384
+msgid "nixl_path"
+msgstr "nixl_path"
+
+#: ../../source/api_reference/configurations.rst:385
+msgid "File system path for Nixl storage"
+msgstr "Nixl 存储的文件系统路径"
+
+#: ../../source/api_reference/configurations.rst:386
+msgid "nixl_pool_size"
+msgstr "nixl_pool_size"
+
+#: ../../source/api_reference/configurations.rst:387
+msgid "Number of files or objects in the storage pool"
+msgstr "存储池中的文件或对象数量"
+
+#: ../../source/api_reference/configurations.rst:388
+msgid "nixl_endpoint_list"
+msgstr "nixl_endpoint_list"
+
+#: ../../source/api_reference/configurations.rst:389
+msgid ""
+"List of object-storage endpoint URLs for per-worker distribution. Each TP"
+" worker selects an entry round-robin by ``local_worker_id``, overriding "
+"``nixl_backend_params.endpoint_override``. Only applied when "
+"``nixl_backend`` is ``\"OBJ\"`` (silently ignored otherwise). Each entry "
+"must start with ``http://`` or ``https://``; an empty list raises "
+"``ValueError`` at engine init."
+msgstr ""
+"每个工作节点的对象存储端点 URL 列表。每个 TP 工作节点通过 ``local_worker_id`` 轮询选择一个条目，覆盖 "
+"``nixl_backend_params.endpoint_override``\\ 。仅在 ``nixl_backend`` 为 "
+"``\"OBJ\"`` 时应用（否则静默忽略）。每个条目必须以 ``http://`` 或 ``https://`` "
+"开头；空列表在引擎初始化时会引发 ``ValueError``\\ 。"
+
+#: ../../source/api_reference/configurations.rst:390
+msgid "nixl_use_hugepages"
+msgstr "nixl_use_hugepages"
+
+#: ../../source/api_reference/configurations.rst:391
+msgid ""
+"**Deprecated.** Use ``local_cpu_use_hugepages`` instead. When set, the "
+"value is copied into ``local_cpu_use_hugepages`` (a warning is logged) "
+"and the key is dropped. Hugepages have never applied to GPU buffers; in "
+"CPU mode the NIXL pool is now owned by ``LocalCPUBackend``."
+msgstr ""
+"**已弃用。** 请改用 ``local_cpu_use_hugepages``\\ 。设置后，该值将被复制到 "
+"``local_cpu_use_hugepages``\\ （会记录警告），并且该键将被丢弃。大页从未应用于 GPU 缓冲区；在 CPU "
+"模式下，NIXL 池现在由 ``LocalCPUBackend`` 拥有。"
+
+#: ../../source/api_reference/configurations.rst:395
+msgid "Additional Storage Configurations"
+msgstr "附加存储配置"
+
+#: ../../source/api_reference/configurations.rst:397
+msgid "Settings for different storage backends and paths."
+msgstr "不同存储后端和路径的设置。"
+
+#: ../../source/api_reference/configurations.rst:406
+msgid "gds_path"
+msgstr "gds_path"
+
+#: ../../source/api_reference/configurations.rst:407
+msgid "LMCACHE_GDS_PATH"
+msgstr "LMCACHE_GDS_PATH"
+
+#: ../../source/api_reference/configurations.rst:408
+msgid ""
+"Path for GDS backend. Supports comma-separated paths for multi-device I/O"
+" (e.g. ``/mnt/nvme0/cache,/mnt/nvme1/cache``). See ``gds_path_sharding`` "
+"for how paths are assigned to GPUs."
+msgstr ""
+"GDS 后端的路径。支持以逗号分隔的多设备 I/O 路径（例如 ``/mnt/nvme0/cache,/mnt/nvme1/cache``\\ "
+"）。有关路径如何分配给 GPU，请参见 ``gds_path_sharding``\\ 。"
+
+#: ../../source/api_reference/configurations.rst:409
+msgid "gds_path_sharding"
+msgstr "gds_path_sharding"
+
+#: ../../source/api_reference/configurations.rst:410
+msgid "LMCACHE_GDS_PATH_SHARDING"
+msgstr "LMCACHE_GDS_PATH_SHARDING"
+
+#: ../../source/api_reference/configurations.rst:412
+msgid "gds_buffer_size"
+msgstr "gds_buffer_size"
+
+#: ../../source/api_reference/configurations.rst:413
+msgid "LMCACHE_GDS_BUFFER_SIZE"
+msgstr "LMCACHE_GDS_BUFFER_SIZE"
+
+#: ../../source/api_reference/configurations.rst:414
+msgid "Buffer size for GDS operations"
+msgstr "GDS 操作的缓冲区大小"
+
+#: ../../source/api_reference/configurations.rst:415
+msgid "use_gds"
+msgstr "use_gds"
+
+#: ../../source/api_reference/configurations.rst:416
+msgid "LMCACHE_USE_GDS"
+msgstr "LMCACHE_USE_GDS"
+
+#: ../../source/api_reference/configurations.rst:417
+msgid "Enable or disable GPU Direct Storage API usage (default: true)"
+msgstr "启用或禁用 GPU 直接存储 API 的使用（默认：true）"
+
+#: ../../source/api_reference/configurations.rst:418
+msgid "gds_backend"
+msgstr "gds_backend"
+
+#: ../../source/api_reference/configurations.rst:419
+msgid "LMCACHE_GDS_BACKEND"
+msgstr "LMCACHE_GDS_BACKEND"
+
+#: ../../source/api_reference/configurations.rst:420
+msgid "GDS library backend to use (default: \"cufile\")"
+msgstr "使用的 GDS 库后端（默认：\\\"cufile\\\"）"
+
+#: ../../source/api_reference/configurations.rst:423
+msgid "Custom Prometheus Histogram Buckets"
+msgstr "自定义 Prometheus 直方图桶"
+
+#: ../../source/api_reference/configurations.rst:425
+msgid ""
+"You can override the default bucket boundaries for any Prometheus "
+"histogram metric by adding a key ``histogram_bucket_<name>`` to "
+"``extra_config``, where ``<name>`` is the metric name **without** the "
+"``lmcache:`` prefix."
+msgstr ""
+"您可以通过向 ``extra_config`` 添加一个键 ``histogram_bucket_<name>`` 来覆盖任何 "
+"Prometheus 直方图度量的默认桶边界，其中 ``<name>`` 是度量名称 **不带** ``lmcache:`` 前缀。"
+
+#: ../../source/api_reference/configurations.rst:429
+msgid "The value must be a list of numeric boundaries (floats or ints)."
+msgstr "值必须是一个数字边界的列表（浮点数或整数）。"
+
+#: ../../source/api_reference/configurations.rst:441
+msgid "Available Histogram Names"
+msgstr "可用直方图名称"
+
+#: ../../source/api_reference/configurations.rst:443
+msgid "``time_to_retrieve``"
+msgstr "``time_to_retrieve``"
+
+#: ../../source/api_reference/configurations.rst:444
+msgid "Time to retrieve from cache (seconds)"
+msgstr "从缓存中检索所需时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:445
+msgid "``time_to_store``"
+msgstr "``time_to_store``"
+
+#: ../../source/api_reference/configurations.rst:446
+msgid "Time to store to cache (seconds)"
+msgstr "缓存存储时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:447
+msgid "``time_to_lookup``"
+msgstr "``time_to_lookup``"
+
+#: ../../source/api_reference/configurations.rst:448
+msgid "Time to lookup in cache (seconds)"
+msgstr "缓存查找时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:449
+msgid "``retrieve_process_tokens_time``"
+msgstr "``retrieve_process_tokens_time``"
+
+#: ../../source/api_reference/configurations.rst:450
+msgid "Time to process tokens in retrieve (seconds)"
+msgstr "在检索中处理令牌的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:451
+msgid "``retrieve_broadcast_time``"
+msgstr "``retrieve_broadcast_time``"
+
+#: ../../source/api_reference/configurations.rst:452
+msgid "Time to broadcast memory objects in retrieve (seconds)"
+msgstr "在检索中广播内存对象的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:453
+msgid "``retrieve_to_gpu_time``"
+msgstr "``retrieve_to_gpu_time``"
+
+#: ../../source/api_reference/configurations.rst:454
+msgid "Time to move data to GPU in retrieve (seconds)"
+msgstr "在检索中将数据移动到 GPU 的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:455
+msgid "``remote_backend_batched_get_blocking_time``"
+msgstr "``remote_backend_batched_get_blocking_time``"
+
+#: ../../source/api_reference/configurations.rst:456
+msgid "Time to get data from remote backend (seconds)"
+msgstr "从远程后端获取数据的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:457
+msgid "``instrumented_connector_batched_get_time``"
+msgstr "``instrumented_connector_batched_get_time``"
+
+#: ../../source/api_reference/configurations.rst:458
+msgid "Time used by the connector (seconds)"
+msgstr "连接器使用的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:459
+msgid "``store_process_tokens_time``"
+msgstr "``store_process_tokens_time``"
+
+#: ../../source/api_reference/configurations.rst:460
+msgid "Time to process tokens in store (seconds)"
+msgstr "存储中处理令牌的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:461
+msgid "``store_from_gpu_time``"
+msgstr "``store_from_gpu_time``"
+
+#: ../../source/api_reference/configurations.rst:462
+msgid "Time to move data from GPU in store (seconds)"
+msgstr "从 GPU 移动数据到存储的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:463
+msgid "``store_put_time``"
+msgstr "``store_put_time``"
+
+#: ../../source/api_reference/configurations.rst:464
+msgid "Time to put data to storage in store (seconds)"
+msgstr "将数据存储到存储中的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:465
+msgid "``retrieve_speed``"
+msgstr "``retrieve_speed``"
+
+#: ../../source/api_reference/configurations.rst:466
+msgid "Retrieve speed (tokens per second)"
+msgstr "检索速度（每秒令牌数）"
+
+#: ../../source/api_reference/configurations.rst:467
+msgid "``store_speed``"
+msgstr "``store_speed``"
+
+#: ../../source/api_reference/configurations.rst:468
+msgid "Store speed (tokens per second)"
+msgstr "存储速度（每秒令牌数）"
+
+#: ../../source/api_reference/configurations.rst:469
+msgid "``p2p_time_to_transfer``"
+msgstr "``p2p_time_to_transfer``"
+
+#: ../../source/api_reference/configurations.rst:470
+msgid "Time to transfer via P2P (seconds)"
+msgstr "通过 P2P 传输的时间（秒）"
+
+#: ../../source/api_reference/configurations.rst:471
+msgid "``p2p_transfer_speed``"
+msgstr "``p2p_transfer_speed``"
+
+#: ../../source/api_reference/configurations.rst:472
+msgid "P2P transfer speed (tokens per second)"
+msgstr "P2P 传输速度（每秒令牌数）"
+
+#: ../../source/api_reference/configurations.rst:473
+msgid "``remote_time_to_get``"
+msgstr "``remote_time_to_get``"
+
+#: ../../source/api_reference/configurations.rst:474
+msgid "Time to get from remote backends (ms)"
+msgstr "从远程后端获取的时间（毫秒）"
+
+#: ../../source/api_reference/configurations.rst:475
+msgid "``remote_time_to_put``"
+msgstr "``remote_time_to_put``"
+
+#: ../../source/api_reference/configurations.rst:476
+msgid "Time to put to remote backends (ms)"
+msgstr "远程后端的放置时间（毫秒）"
+
+#: ../../source/api_reference/configurations.rst:477
+msgid "``remote_time_to_get_sync``"
+msgstr "``remote_time_to_get_sync``"
+
+#: ../../source/api_reference/configurations.rst:478
+msgid "Time to get from remote backends synchronously (ms)"
+msgstr "从远程后端同步获取的时间（毫秒）"
+
+#: ../../source/api_reference/configurations.rst:479
+msgid "``request_cache_hit_rate``"
+msgstr "``request_cache_hit_rate``"
+
+#: ../../source/api_reference/configurations.rst:480
+msgid "Request cache hit rate (0.0 to 1.0)"
+msgstr "请求缓存命中率 (0.0 到 1.0)"
+
+#: ../../source/api_reference/configurations.rst:481
+msgid "``request_cache_lifespan``"
+msgstr "``request_cache_lifespan``"
+
+#: ../../source/api_reference/configurations.rst:482
+msgid "Request cache lifespan (minutes)"
+msgstr "请求缓存生命周期（分钟）"
+
+#: ../../source/api_reference/configurations.rst:485
+msgid "Internal API Server Configurations"
+msgstr "内部 API 服务器配置"
+
+#: ../../source/api_reference/configurations.rst:487
+msgid ""
+"Settings for the internal API server that provides management and "
+"debugging APIs for LMCache engines. The API server runs on each worker "
+"and scheduler, allowing you to inspect and control LMCache behavior at "
+"runtime."
+msgstr ""
+"用于内部 API 服务器的设置，该服务器为 LMCache 引擎提供管理和调试 API。API "
+"服务器在每个工作节点和调度器上运行，允许您在运行时检查和控制 LMCache 的行为。"
+
+#: ../../source/api_reference/configurations.rst:491
+msgid "The internal API server provides endpoints for:"
+msgstr "内部 API 服务器提供以下端点："
+
+#: ../../source/api_reference/configurations.rst:493
+msgid "**Metrics**: Performance and cache statistics"
+msgstr "**指标**\\ ：性能和缓存统计信息"
+
+#: ../../source/api_reference/configurations.rst:494
+msgid "**Configuration**: Runtime configuration inspection"
+msgstr "**配置**: 运行时配置检查"
+
+#: ../../source/api_reference/configurations.rst:495
+msgid "**Metadata**: Engine and model metadata"
+msgstr "**元数据**\\ ：引擎和模型元数据"
+
+#: ../../source/api_reference/configurations.rst:496
+msgid "**Threads**: Thread debugging information"
+msgstr "**线程**\\ ：线程调试信息"
+
+#: ../../source/api_reference/configurations.rst:497
+msgid "**Log Level**: Dynamic log level adjustment"
+msgstr "**日志级别**\\ ：动态日志级别调整"
+
+#: ../../source/api_reference/configurations.rst:498
+msgid ""
+"**Script Execution**: Run custom Python scripts with access to the "
+"LMCache engine"
+msgstr "**脚本执行**\\ ：运行自定义 Python 脚本，访问 LMCache 引擎"
+
+#: ../../source/api_reference/configurations.rst:501
+msgid "Configuration Options"
+msgstr "配置选项"
+
+#: ../../source/api_reference/configurations.rst:510
+msgid "internal_api_server_enabled"
+msgstr "internal_api_server_enabled"
+
+#: ../../source/api_reference/configurations.rst:511
+msgid "LMCACHE_INTERNAL_API_SERVER_ENABLED"
+msgstr "LMCACHE_INTERNAL_API_SERVER_ENABLED"
+
+#: ../../source/api_reference/configurations.rst:512
+msgid "Whether to enable internal API server. Default: false"
+msgstr "是否启用内部 API 服务器。默认值：false"
+
+#: ../../source/api_reference/configurations.rst:513
+msgid "internal_api_server_host"
+msgstr "internal_api_server_host"
+
+#: ../../source/api_reference/configurations.rst:514
+msgid "LMCACHE_INTERNAL_API_SERVER_HOST"
+msgstr "LMCACHE_INTERNAL_API_SERVER_HOST"
+
+#: ../../source/api_reference/configurations.rst:515
+msgid "Host for internal API server to bind to. Default: \"0.0.0.0\""
+msgstr "用于绑定内部 API 服务器的主机。默认值：“0.0.0.0”"
+
+#: ../../source/api_reference/configurations.rst:516
+msgid "internal_api_server_port_start"
+msgstr "internal_api_server_port_start"
+
+#: ../../source/api_reference/configurations.rst:517
+msgid "LMCACHE_INTERNAL_API_SERVER_PORT_START"
+msgstr "LMCACHE_INTERNAL_API_SERVER_PORT_START"
+
+#: ../../source/api_reference/configurations.rst:518
+msgid ""
+"Starting port for internal API server. Port assignment: Scheduler = "
+"port_start + 0, Worker i = port_start + i + 1. Example: If "
+"port_start=6999, then Scheduler=6999, Worker 0=7000, Worker 1=7001, etc. "
+"Default: 6999"
+msgstr ""
+"内部 API 服务器的起始端口。端口分配：调度器 = port_start + 0，工作者 i = port_start + i + "
+"1。示例：如果 port_start=6999，则调度器=6999，工作者 0=7000，工作者 1=7001，等等。默认值：6999"
+
+#: ../../source/api_reference/configurations.rst:519
+msgid "internal_api_server_include_index_list"
+msgstr "internal_api_server_include_index_list"
+
+#: ../../source/api_reference/configurations.rst:520
+msgid "LMCACHE_INTERNAL_API_SERVER_INCLUDE_INDEX_LIST"
+msgstr "LMCACHE_INTERNAL_API_SERVER_INCLUDE_INDEX_LIST"
+
+#: ../../source/api_reference/configurations.rst:521
+msgid ""
+"List of worker/scheduler indices to enable API server on. Use 0 for "
+"scheduler, 1 for worker 0, 2 for worker 1, etc. If null, enables on all "
+"workers/scheduler. Example: [0, 1] enables only on scheduler and worker "
+"0. Default: null"
+msgstr ""
+"启用 API 服务器的工作者/调度器索引列表。使用 0 表示调度器，1 表示工作者 0，2 表示工作者 1，依此类推。如果为 "
+"null，则在所有工作者/调度器上启用。示例：[0, 1] 仅在调度器和工作者 0 上启用。默认值：null"
+
+#: ../../source/api_reference/configurations.rst:522
+msgid "internal_api_server_socket_path_prefix"
+msgstr "internal_api_server_socket_path_prefix"
+
+#: ../../source/api_reference/configurations.rst:523
+msgid "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX"
+msgstr "LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX"
+
+#: ../../source/api_reference/configurations.rst:524
+#, python-brace-format
+msgid ""
+"If specified, use Unix domain sockets instead of TCP ports. Socket paths "
+"will be \"{prefix}_{port}\". Example: \"/tmp/lmcache_api_socket\" creates"
+" \"/tmp/lmcache_api_socket_6999\", \"/tmp/lmcache_api_socket_7000\", etc."
+" Default: null"
+msgstr ""
+"如果指定，则使用 Unix 域套接字而不是 TCP 端口。套接字路径将为 "
+"\\\"{prefix}_{port}\\\"。示例：\\\"/tmp/lmcache_api_socket\\\" 创建 "
+"\\\"/tmp/lmcache_api_socket_6999\\\"、\\\"/tmp/lmcache_api_socket_7000\\\""
+" 等。默认值：null"
+
+#: ../../source/api_reference/configurations.rst:527
+msgid "Plugin Configurations"
+msgstr "插件配置"
+
+#: ../../source/api_reference/configurations.rst:529
+msgid "Settings for plugin system."
+msgstr "插件系统的设置。"
+
+#: ../../source/api_reference/configurations.rst:538
+msgid "plugin_locations"
+msgstr "plugin_locations"
+
+#: ../../source/api_reference/configurations.rst:539
+msgid "LMCACHE_PLUGIN_LOCATIONS"
+msgstr "LMCACHE_PLUGIN_LOCATIONS"
+
+#: ../../source/api_reference/configurations.rst:540
+msgid "List of plugin locations. Default: []"
+msgstr "插件位置列表。默认值：[]"
+
+#: ../../source/api_reference/configurations.rst:543
+msgid "Deprecated Configurations"
+msgstr "已弃用的配置"
+
+#: ../../source/api_reference/configurations.rst:545
+msgid "These configurations are deprecated and may be removed in future versions."
+msgstr "这些配置已被弃用，可能会在未来的版本中被移除。"
+
+#: ../../source/api_reference/configurations.rst:554
+msgid "audit_actual_remote_url"
+msgstr "audit_actual_remote_url"
+
+#: ../../source/api_reference/configurations.rst:555
+msgid "LMCACHE_AUDIT_ACTUAL_REMOTE_URL"
+msgstr "LMCACHE_AUDIT_ACTUAL_REMOTE_URL"
+
+#: ../../source/api_reference/configurations.rst:556
+msgid ""
+"(Deprecated) URL of actual remote LMCache instance for auditing. Use "
+"extra_config['audit_actual_remote_url'] instead"
+msgstr ""
+"(已弃用) 用于审计的实际远程 LMCache 实例的 URL。请改用 "
+"extra_config['audit_actual_remote_url']。"
+
+#~ msgid ""
+#~ "List of object-storage endpoint URLs "
+#~ "for per-worker distribution. Overrides "
+#~ "``nixl_backend_params.endpoint_override`` when set."
+#~ msgstr ""
+#~ "每个工作节点分发的对象存储端点 URL 列表。当设置时，会覆盖 "
+#~ "``nixl_backend_params.endpoint_override``。"
+
+#~ msgid ""
+#~ "Whether to use Linux hugepages (2 "
+#~ "MiB) for the NIXL CPU buffer. "
+#~ "Requires pre-allocated hugepages (``sysctl "
+#~ "vm.nr_hugepages``). Values: true/false. Default: "
+#~ "false"
+#~ msgstr ""
+#~ "是否为 NIXL CPU 缓冲区使用 Linux 大页（2 "
+#~ "MiB）。需要预分配大页（``sysctl vm.nr_hugepages``）。值：true/false。默认值：false"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/dynamic_connector.po b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/dynamic_connector.po
new file mode 100644
index 0000000..11bc7d7
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/dynamic_connector.po
@@ -0,0 +1,108 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/api_reference/dynamic_connector.rst:2
+msgid "vLLM Dynamic Connector"
+msgstr "vLLM 动态连接器"
+
+#: ../../source/api_reference/dynamic_connector.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/api_reference/dynamic_connector.rst:10
+msgid "Upstream Integration:"
+msgstr "上游集成："
+
+#: ../../source/api_reference/dynamic_connector.rst:12
+msgid ""
+"LMCache integration with official upstream vLLM was introduced in `early "
+"February 2025 <https://github.com/vllm-project/vllm/pull/12953>`_."
+msgstr ""
+"LMCache 与官方上游 vLLM 的集成是在 `2025 年 2 月初 <https://github.com/vllm-"
+"project/vllm/pull/12953>`_ 中引入的。"
+
+#: ../../source/api_reference/dynamic_connector.rst:14
+msgid ""
+"vLLM imports the connector from the lmcache package and wraps it in "
+"`vllm/distributed/kv_transfer/kv_connector/v1/lmcache_connector.py "
+"<https://github.com/vllm-"
+"project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/lmcache_connector.py>`_:"
+msgstr ""
+"vLLM 从 lmcache 包导入连接器，并将其封装在 "
+"`vllm/distributed/kv_transfer/kv_connector/v1/lmcache_connector.py "
+"<https://github.com/vllm-"
+"project/vllm/blob/main/vllm/distributed/kv_transfer/kv_connector/v1/lmcache_connector.py>`_"
+" 中："
+
+#: ../../source/api_reference/dynamic_connector.rst:20
+msgid ""
+"This means that any updates to LMCache connector need to be "
+"synced/updated in the upstream vLLM."
+msgstr "这意味着对 LMCache 连接器的任何更新都需要在上游 vLLM 中同步/更新。"
+
+#: ../../source/api_reference/dynamic_connector.rst:22
+msgid "Example usage of vLLM upstream connector:"
+msgstr "vLLM 上游连接器的示例用法："
+
+#: ../../source/api_reference/dynamic_connector.rst:24
+#: ../../source/api_reference/dynamic_connector.rst:49
+msgid "**Pythonic Transfer Config:**"
+msgstr "**Pythonic Transfer Config:**"
+
+#: ../../source/api_reference/dynamic_connector.rst:34
+msgid "**Command Line Transfer Configs:**"
+msgstr "**命令行传输配置:**"
+
+#: ../../source/api_reference/dynamic_connector.rst:43
+msgid "Dynamic Connector:"
+msgstr "动态连接器："
+
+#: ../../source/api_reference/dynamic_connector.rst:45
+msgid ""
+"`In June 2025 <https://github.com/vllm-project/vllm/pull/18142>`_, vLLM "
+"supports dynamic loading of KV connector implementations so we can "
+"directly reference connectors from the LMCache package without having to "
+"update vLLM."
+msgstr "在 2025 年 6 月，vLLM 支持动态加载 KV 连接器实现，因此我们可以直接引用 LMCache 包中的连接器，而无需更新 vLLM。"
+
+#: ../../source/api_reference/dynamic_connector.rst:47
+msgid "Example usage of dynamic connector from LMCache:"
+msgstr "来自 LMCache 的动态连接器示例用法："
+
+#: ../../source/api_reference/dynamic_connector.rst:60
+msgid "**Command Line Transfer Config:**"
+msgstr "**命令行传输配置：**"
+
+#: ../../source/api_reference/dynamic_connector.rst:68
+msgid ""
+"This allows LMCache to modify/develop connectors and quickly plug-and-"
+"play."
+msgstr "这允许 LMCache 修改/开发连接器并快速插拔。"
+
+#: ../../source/api_reference/dynamic_connector.rst:70
+msgid ""
+"Any custom adapters will be documented here in the future as well as "
+"possible deprecations to the upstream connector."
+msgstr "未来任何自定义适配器将会在这里记录，以及可能对上游连接器的弃用。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/multimodality.po b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/multimodality.po
new file mode 100644
index 0000000..43b63a6
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/multimodality.po
@@ -0,0 +1,193 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/api_reference/multimodality.rst:2
+msgid "KV Caching for Multimodal Models with vLLM"
+msgstr "多模态模型的 KV Cache 与 vLLM"
+
+#: ../../source/api_reference/multimodality.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP mode </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/api_reference/multimodality.rst:10
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/api_reference/multimodality.rst:12
+msgid ""
+"vLLM is building on its multimodal capability and currently supports the "
+"following `List of Multimodal Language Models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#list-of-"
+"multimodal-language-models>`_."
+msgstr ""
+"vLLM 正在构建其多模态能力，目前支持以下 `多模态语言模型列表 "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#list-of-"
+"multimodal-language-models>`_。"
+
+#: ../../source/api_reference/multimodality.rst:14
+msgid ""
+"LMCache can therefore be used to speed up inference time for all "
+"multimodal models supported by vLLM. This document shows the speedup "
+"improvements using LMCache for KV caching in vLLM for multimodal models."
+msgstr ""
+"因此，LMCache 可用于加速 vLLM 支持的所有多模态模型的推理时间。本文档展示了在 vLLM 中使用 LMCache 进行 KV "
+"缓存的加速改进。"
+
+#: ../../source/api_reference/multimodality.rst:17
+msgid "Examples of TTFT speed up for different multimodal types"
+msgstr "不同多模态类型的 TTFT 加速示例"
+
+#: ../../source/api_reference/multimodality.rst:20
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/api_reference/multimodality.rst:22
+msgid ""
+"A Machine with at least one GPU. You can adjust the max model length of "
+"your vLLM instance depending on your GPU memory"
+msgstr "一台至少配备一块 GPU 的机器。您可以根据您的显存调整 vLLM 实例的最大模型长度。"
+
+#: ../../source/api_reference/multimodality.rst:23
+msgid ""
+"vLLM and LMCache installed (:doc:`Installation Guide "
+"<../getting_started/installation>`)"
+msgstr "vLLM 和 LMCache 已安装 (:doc:`安装指南 <../getting_started/installation>`)"
+
+#: ../../source/api_reference/multimodality.rst:24
+msgid "vLLM audio dependencies installed: ``pip install vllm[audio]``"
+msgstr "vLLM 音频依赖项已安装：``pip install vllm[audio]``"
+
+#: ../../source/api_reference/multimodality.rst:27
+msgid "Examples"
+msgstr "示例"
+
+#: ../../source/api_reference/multimodality.rst:31
+msgid ""
+"The examples below use a python script for inferencing multimodal models "
+"hosted by vLLM. The script is the "
+"`openai_chat_completion_client_for_multimodal python script in vLLM "
+"<https://github.com/vllm-"
+"project/vllm/blob/main/examples/online_serving/openai_chat_completion_client_for_multimodal.py>`_."
+" You will need to download it locally for running the examples below. The"
+" script is printed in the `reference section <#reference-inferencing-"
+"multimodal-models-in-vllm-example-python-script>`_ that follows for you "
+"perusal. Go to the `Example output <#example-output>`_ section to see the"
+" output in the vLLM logs that demonstrate the speedup improvements."
+msgstr ""
+"下面的示例使用 Python 脚本对托管在 vLLM 上的多模态模型进行推理。该脚本是 `vLLM 中的 "
+"openai_chat_completion_client_for_multimodal python 脚本 "
+"<https://github.com/vllm-"
+"project/vllm/blob/main/examples/online_serving/openai_chat_completion_client_for_multimodal.py>`_。您需要将其下载到本地以运行下面的示例。该脚本在后面的"
+" `参考部分 <#reference-inferencing-multimodal-models-in-vllm-example-python-"
+"script>`_ 中打印供您查阅。请转到 `示例输出 <#example-output>`_ 部分查看 vLLM 日志中的输出，以展示加速改进。"
+
+#: ../../source/api_reference/multimodality.rst:39
+msgid "Audio Inference with Ultravox:"
+msgstr "使用 Ultravox 进行音频推理："
+
+#: ../../source/api_reference/multimodality.rst:41
+msgid ""
+"Start vLLM server with ``fixie-ai/ultravox-v0_5-llama-3_2-1b`` model and "
+"LMCache KV caching:"
+msgstr "使用 ``fixie-ai/ultravox-v0_5-llama-3_2-1b`` 模型和 LMCache KV 缓存启动 vLLM 服务器："
+
+#: ../../source/api_reference/multimodality.rst:49
+#: ../../source/api_reference/multimodality.rst:66
+#: ../../source/api_reference/multimodality.rst:84
+#: ../../source/api_reference/multimodality.rst:101
+msgid ""
+"Run the python script twice to demonstrate TTFT speedup on the second "
+"turn because of the caching:"
+msgstr "运行 Python 脚本两次，以演示由于缓存导致的第二次推理的 TTFT 加速："
+
+#: ../../source/api_reference/multimodality.rst:57
+msgid "Single Image Inference with Llava:"
+msgstr "使用 Llava 进行单图像推理："
+
+#: ../../source/api_reference/multimodality.rst:59
+msgid ""
+"Start vLLM server with ``llava-hf/llava-1.5-7b-hf`` model and LMCache KV "
+"caching:"
+msgstr "使用 ``llava-hf/llava-1.5-7b-hf`` 模型和 LMCache KV 缓存启动 vLLM 服务器："
+
+#: ../../source/api_reference/multimodality.rst:74
+msgid "Multi-image Inference with Phi-3.5-vision-instruct:"
+msgstr "使用 Phi-3.5-vision-instruct 进行多图像推理："
+
+#: ../../source/api_reference/multimodality.rst:76
+msgid ""
+"Start vLLM server with ``microsoft/Phi-3.5-vision-instruct`` model and "
+"LMCache KV caching:"
+msgstr "使用 ``microsoft/Phi-3.5-vision-instruct`` 模型和 LMCache KV 缓存启动 vLLM 服务器："
+
+#: ../../source/api_reference/multimodality.rst:92
+msgid "Video Inference with Llava-OneVision:"
+msgstr "使用 Llava-OneVision 进行视频推理："
+
+#: ../../source/api_reference/multimodality.rst:94
+msgid ""
+"Start vLLM server with ``llava-hf/llava-onevision-qwen2-7b-ov-hf`` model "
+"and LMCache KV caching:"
+msgstr ""
+"使用 ``llava-hf/llava-onevision-qwen2-7b-ov-hf`` 模型和 LMCache KV 缓存启动 vLLM "
+"服务器："
+
+#: ../../source/api_reference/multimodality.rst:110
+msgid "Example output"
+msgstr "示例输出"
+
+#: ../../source/api_reference/multimodality.rst:112
+msgid ""
+"When running the examples above you will notice output in the vLLM logs "
+"similar to below."
+msgstr "在运行上述示例时，您会注意到 vLLM 日志中类似于以下的输出。"
+
+#: ../../source/api_reference/multimodality.rst:114
+msgid "This first output demonstrates the tokens being cached and loaded."
+msgstr "该第一个输出演示了令牌被缓存和加载的过程。"
+
+#: ../../source/api_reference/multimodality.rst:120
+msgid "This then shows the speedup between the first and second runs."
+msgstr "这显示了第一次和第二次运行之间的加速。"
+
+#: ../../source/api_reference/multimodality.rst:122
+msgid "First request:"
+msgstr "第一次请求："
+
+#: ../../source/api_reference/multimodality.rst:133
+msgid "Second request:"
+msgstr "第二个请求："
+
+#: ../../source/api_reference/multimodality.rst:144
+msgid "Reference: Inferencing multimodal models in vLLM example Python script"
+msgstr "参考：在 vLLM 示例 Python 脚本中推理多模态模型"
+
+#: ../../source/api_reference/multimodality.rst:146
+msgid ""
+"Source: https://github.com/vllm-"
+"project/vllm/blob/main/examples/online_serving/openai_chat_completion_client_for_multimodal.py"
+msgstr ""
+"源: https://github.com/vllm-"
+"project/vllm/blob/main/examples/online_serving/openai_chat_completion_client_for_multimodal.py"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/storage_backends.po b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/storage_backends.po
new file mode 100644
index 0000000..13a6f87
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/api_reference/storage_backends.po
@@ -0,0 +1,37 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/api_reference/storage_backends.rst:2
+msgid "Adding new storage backends"
+msgstr "添加新的存储后端"
+
+#: ../../source/api_reference/storage_backends.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/api_reference/storage_backends.rst:9
+msgid "Coming soon..."
+msgstr "敬请期待..."
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/bench.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/bench.po
new file mode 100644
index 0000000..5e9d0ef
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/bench.po
@@ -0,0 +1,1958 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/bench.rst:4
+msgid "lmcache bench"
+msgstr "lmcache bench"
+
+#: ../../source/cli/bench.rst:6
+msgid ""
+"The ``lmcache bench`` command runs sustained performance benchmarks. It "
+"has three sub-commands, each targeting a different layer of the stack:"
+msgstr "``lmcache bench`` 命令用于运行持续性能基准测试。它有三个子命令，分别针对不同的栈层级："
+
+#: ../../source/cli/bench.rst:13
+msgid "Sub-command"
+msgstr "子命令"
+
+#: ../../source/cli/bench.rst:14 ../../source/cli/bench.rst:126
+#: ../../source/cli/bench.rst:219 ../../source/cli/bench.rst:260
+#: ../../source/cli/bench.rst:311 ../../source/cli/bench.rst:398
+#: ../../source/cli/bench.rst:462 ../../source/cli/bench.rst:736
+#: ../../source/cli/bench.rst:1115
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/bench.rst:15
+msgid "``engine``"
+msgstr "``engine``"
+
+#: ../../source/cli/bench.rst:16
+msgid ""
+"Benchmark an inference engine (e.g. vLLM) with workloads that exercise "
+"different KV-cache reuse patterns."
+msgstr "使用多种 KV Cache 重用模式的工作负载对推理引擎（例如 vLLM）进行基准测试。"
+
+#: ../../source/cli/bench.rst:18
+msgid "``server``"
+msgstr "``server``"
+
+#: ../../source/cli/bench.rst:19
+msgid ""
+"End-to-end sanity test against a running LMCache MP cache server (ZMQ + "
+"HTTP). Requires the full ``lmcache`` install and a GPU."
+msgstr "针对正在运行的 LMCache MP 缓存服务器（ZMQ + HTTP）的端到端健全性测试。需要完整安装 ``lmcache`` 以及一块 GPU。"
+
+#: ../../source/cli/bench.rst:21
+msgid "``l2``"
+msgstr "``l2``"
+
+#: ../../source/cli/bench.rst:22
+msgid ""
+"Throughput / latency benchmark against an L2 cache adapter (store / "
+"lookup / load)."
+msgstr "针对 L2 缓存适配器的吞吐量／延迟基准测试（存储／查找／加载）。"
+
+#: ../../source/cli/bench.rst:33
+msgid "engine"
+msgstr "engine"
+
+#: ../../source/cli/bench.rst:35
+msgid ""
+"The ``lmcache bench engine`` command runs sustained performance "
+"benchmarks against an inference engine (e.g., vLLM). It supports multiple"
+" workload types that exercise different caching patterns and reports "
+"TTFT, decoding speed, and throughput metrics."
+msgstr ""
+"``lmcache bench engine`` 命令对推理引擎（例如 "
+"vLLM）执行持续性能基准测试。它支持多种工作负载类型，用于测试不同的缓存模式，并上报 TTFT、解码速度和吞吐量等指标。"
+
+#: ../../source/cli/bench.rst:44
+msgid "There are three ways to configure the benchmark:"
+msgstr "配置基准测试有三种方法："
+
+#: ../../source/cli/bench.rst:46
+msgid "**CLI arguments** -- pass all options on the command line."
+msgstr "**CLI 参数** -- 在命令行中传递所有选项。"
+
+#: ../../source/cli/bench.rst:47
+msgid ""
+"**Interactive mode** -- run ``lmcache bench engine`` without required "
+"args and follow the step-by-step prompts."
+msgstr "**交互模式** -- 在不传入必需参数的情况下运行 ``lmcache bench engine``\\ ，然后按照逐步提示进行操作。"
+
+#: ../../source/cli/bench.rst:49
+msgid ""
+"**Config file** -- save a configuration to JSON and replay it with "
+"``--config``."
+msgstr "**配置文件** -- 将配置保存为 JSON 并使用 ``--config`` 进行重放。"
+
+#: ../../source/cli/bench.rst:54
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/cli/bench.rst:56
+msgid "**Minimal (with all required arguments):**"
+msgstr "**最小示例（包含所有必需参数）：**"
+
+#: ../../source/cli/bench.rst:65
+msgid "**Interactive mode (guided setup):**"
+msgstr "**交互模式（引导设置）：**"
+
+#: ../../source/cli/bench.rst:71
+msgid ""
+"The interactive mode walks you through each required setting, then asks "
+"whether you want to configure general and workload-specific options or "
+"use defaults."
+msgstr "交互模式会引导您逐一完成每项必需设置，然后询问是否需要配置通用选项和工作负载专项选项，或者直接使用默认值。"
+
+#: ../../source/cli/bench.rst:75
+msgid "**From a saved config file:**"
+msgstr "**从保存的配置文件中：**"
+
+#: ../../source/cli/bench.rst:82
+msgid ""
+"Config files contain benchmark parameters (workload, KV cache settings, "
+"etc.) but not the engine URL, so you can reuse the same config against "
+"different engines."
+msgstr "配置文件包含基准测试参数（工作负载、KV Cache 设置等），但不包含引擎 URL，因此同一份配置可以在不同引擎上复用。"
+
+#: ../../source/cli/bench.rst:86
+msgid "**Export a config without running the benchmark:**"
+msgstr "**导出配置而不运行基准测试：**"
+
+#: ../../source/cli/bench.rst:96
+msgid ""
+"This resolves all auto-detected values (model name, tokens per GB) and "
+"saves them to a portable JSON file that works without an LMCache server."
+msgstr ""
+"此操作会解析所有自动检测到的值（模型名称、每 GB 的 token 数），并将其保存为可移植的 JSON 文件，无需 LMCache "
+"服务器即可使用。"
+
+#: ../../source/cli/bench.rst:99
+msgid "**Non-interactive mode (for scripts and CI):**"
+msgstr "**非交互模式（用于脚本和 CI）：**"
+
+#: ../../source/cli/bench.rst:109
+msgid ""
+"Errors immediately if any required argument is missing, instead of "
+"entering interactive mode. Useful in automated pipelines."
+msgstr "若缺少任何必需参数，立即报错而非进入交互模式，适用于自动化流水线。"
+
+#: ../../source/cli/bench.rst:112
+msgid ""
+"If you don't have an LMCache server, you can pass ``--tokens-per-gb-"
+"kvcache`` directly instead of ``--lmcache-url`` (see :ref:`bench-tokens-"
+"per-gb` for how to find this value)."
+msgstr ""
+"如果您没有 LMCache 服务器，可以直接传递 ``--tokens-per-gb-kvcache``\\ ，而不是 ``--lmcache-"
+"url``\\ （有关如何找到此值，请参见 :ref:`bench-tokens-per-gb`）。"
+
+#: ../../source/cli/bench.rst:118
+msgid "General Options"
+msgstr "常规选项"
+
+#: ../../source/cli/bench.rst:124 ../../source/cli/bench.rst:217
+#: ../../source/cli/bench.rst:258 ../../source/cli/bench.rst:309
+#: ../../source/cli/bench.rst:396 ../../source/cli/bench.rst:460
+#: ../../source/cli/bench.rst:734 ../../source/cli/bench.rst:1113
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/bench.rst:125
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/cli/bench.rst:127
+msgid "``--config FILE``"
+msgstr "``--config FILE``"
+
+#: ../../source/cli/bench.rst:128 ../../source/cli/bench.rst:133
+#: ../../source/cli/bench.rst:139 ../../source/cli/bench.rst:156
+#: ../../source/cli/bench.rst:160 ../../source/cli/bench.rst:163
+#: ../../source/cli/bench.rst:166 ../../source/cli/bench.rst:169
+#: ../../source/cli/bench.rst:172 ../../source/cli/bench.rst:175
+#: ../../source/cli/bench.rst:178
+msgid "No"
+msgstr "不"
+
+#: ../../source/cli/bench.rst:129
+msgid ""
+"Load configuration from a JSON file. Skips interactive mode. CLI flags "
+"override values in the file. The engine URL is not stored in config files"
+" and must be provided separately."
+msgstr "从 JSON 文件加载配置，跳过交互模式。命令行参数会覆盖文件中的值。引擎 URL 不存储于配置文件中，需单独提供。"
+
+#: ../../source/cli/bench.rst:132
+msgid "``--export-config FILE``"
+msgstr "``--export-config FILE``"
+
+#: ../../source/cli/bench.rst:134
+msgid ""
+"Export resolved configuration to a JSON file and exit. Does not run the "
+"benchmark. Auto-detected values (model, tokens per GB) are resolved and "
+"saved so the config is portable. Environment- specific values (engine "
+"URL, LMCache URL) are excluded."
+msgstr ""
+"将已解析的配置导出到 JSON 文件后退出，不会执行基准测试。自动检测的值（模型名称、每 GB 的 token "
+"数）会被解析并保存，使配置具有可移植性。特定于环境的值（引擎 URL、LMCache URL）不会被导出。"
+
+#: ../../source/cli/bench.rst:138
+msgid "``--no-interactive``"
+msgstr "``--no-interactive``"
+
+#: ../../source/cli/bench.rst:140
+msgid ""
+"Disable interactive mode. Errors if required arguments are missing "
+"instead of prompting. Useful for scripts and CI."
+msgstr "禁用交互模式。若缺少必需参数则立即报错，而非进行提示。适合在脚本和 CI 中使用。"
+
+#: ../../source/cli/bench.rst:142
+msgid "``--engine-url URL``"
+msgstr "``--engine-url URL``"
+
+#: ../../source/cli/bench.rst:143 ../../source/cli/bench.rst:147
+msgid "Yes"
+msgstr "是"
+
+#: ../../source/cli/bench.rst:144
+msgid ""
+"Inference engine URL (e.g., ``http://localhost:8000``). Set "
+"``OPENAI_API_KEY`` env var if authentication is needed."
+msgstr ""
+"推理引擎 URL（例如 ``http://localhost:8000``\\ ）。若需要身份验证，请设置 ``OPENAI_API_KEY`` "
+"环境变量。"
+
+#: ../../source/cli/bench.rst:146
+msgid "``--workload TYPE``"
+msgstr "``--workload TYPE``"
+
+#: ../../source/cli/bench.rst:148
+msgid ""
+"Workload type: ``long-doc-qa``, ``multi-round-chat``, ``long-doc-"
+"permutator``, ``prefix-suffix-tuner``, or ``random-prefill``."
+msgstr ""
+"工作负载类型：\\ ``long-doc-qa``\\ 、\\ ``multi-round-chat``\\ 、\\ ``long-doc-"
+"permutator``\\ 、\\ ``prefix-suffix-tuner`` 或 ``random-prefill``\\ 。"
+
+#: ../../source/cli/bench.rst:151
+msgid "``--tokens-per-gb-kvcache N``"
+msgstr "``--tokens-per-gb-kvcache N``"
+
+#: ../../source/cli/bench.rst:152
+msgid "\\*"
+msgstr "\\*"
+
+#: ../../source/cli/bench.rst:153
+msgid ""
+"Tokens per GB of KV cache. Required unless ``--lmcache-url`` is set. See "
+":ref:`bench-tokens-per-gb` for how to find this value."
+msgstr ""
+"每 GB KV Cache 的 token 数。除非已设置 ``--lmcache-url``\\ ，否则此参数为必填项。关于如何获取该值，请参见"
+" :ref:`bench-tokens-per-gb`。"
+
+#: ../../source/cli/bench.rst:155
+msgid "``--lmcache-url URL``"
+msgstr "``--lmcache-url URL``"
+
+#: ../../source/cli/bench.rst:157
+msgid ""
+"LMCache HTTP server URL. When provided, ``--tokens-per-gb-kvcache`` is "
+"auto-detected from the server."
+msgstr "LMCache HTTP 服务器 URL。若提供此参数，\\ ``--tokens-per-gb-kvcache`` 将自动从服务器检测。"
+
+#: ../../source/cli/bench.rst:159
+msgid "``--model NAME``"
+msgstr "``--model NAME``"
+
+#: ../../source/cli/bench.rst:161
+msgid "Model name. Auto-detected from the engine if omitted."
+msgstr "模型名称。若省略，将自动从引擎检测。"
+
+#: ../../source/cli/bench.rst:162
+msgid "``--kv-cache-volume GB``"
+msgstr "``--kv-cache-volume GB``"
+
+#: ../../source/cli/bench.rst:164
+msgid "Target active KV cache volume in GB (default: 100)."
+msgstr "目标活跃 KV Cache 容量，单位为 GB（默认值：100）。"
+
+#: ../../source/cli/bench.rst:165
+msgid "``--seed N``"
+msgstr "``--seed N``"
+
+#: ../../source/cli/bench.rst:167
+msgid "Random seed (default: 42)."
+msgstr "随机种子（默认值：42）。"
+
+#: ../../source/cli/bench.rst:168
+msgid "``--output-dir DIR``"
+msgstr "``--output-dir DIR``"
+
+#: ../../source/cli/bench.rst:170
+msgid "Directory for CSV and JSON output files (default: current directory)."
+msgstr "CSV 和 JSON 输出文件的保存目录（默认：当前目录）。"
+
+#: ../../source/cli/bench.rst:171
+msgid "``--no-csv``"
+msgstr "``--no-csv``"
+
+#: ../../source/cli/bench.rst:173
+msgid "Skip CSV export."
+msgstr "跳过 CSV 导出。"
+
+#: ../../source/cli/bench.rst:174
+msgid "``--json``"
+msgstr "``--json``"
+
+#: ../../source/cli/bench.rst:176
+msgid "Export a JSON summary file."
+msgstr "导出 JSON 摘要文件。"
+
+#: ../../source/cli/bench.rst:177 ../../source/cli/bench.rst:787
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/bench.rst:179
+msgid "Suppress the real-time progress display."
+msgstr "禁止显示实时进度。"
+
+#: ../../source/cli/bench.rst:185
+msgid "Finding ``--tokens-per-gb-kvcache``"
+msgstr "查找 ``--tokens-per-gb-kvcache``"
+
+#: ../../source/cli/bench.rst:187
+msgid ""
+"If you have an LMCache server running, the easiest approach is to pass "
+"``--lmcache-url`` and let the tool auto-detect the value."
+msgstr "如果已有正在运行的 LMCache 服务器，最简便的方法是传递 ``--lmcache-url``\\ ，让工具自动检测该值。"
+
+#: ../../source/cli/bench.rst:190
+msgid ""
+"If you are using **vLLM without LMCache**, look for these lines in vLLM's"
+" startup log:"
+msgstr "如果正在使用 **不带 LMCache 的 vLLM**\\ ，请在 vLLM 的启动日志中查找以下行："
+
+#: ../../source/cli/bench.rst:198
+msgid "Then compute::"
+msgstr "然后计算::"
+
+#: ../../source/cli/bench.rst:204
+msgid "Workloads"
+msgstr "工作负载"
+
+#: ../../source/cli/bench.rst:207
+msgid "long-doc-qa"
+msgstr "long-doc-qa"
+
+#: ../../source/cli/bench.rst:209
+msgid ""
+"Simulates repeated Q&A over long documents. Warmup sends each document "
+"once to populate the KV cache, then benchmark queries are dispatched with"
+" semaphore-controlled concurrency."
+msgstr "模拟对长文档的重复问答。预热阶段将每个文档发送一次以填充 KV Cache，然后以信号量控制的并发方式派发基准测试查询。"
+
+#: ../../source/cli/bench.rst:218 ../../source/cli/bench.rst:259
+#: ../../source/cli/bench.rst:310 ../../source/cli/bench.rst:397
+#: ../../source/cli/bench.rst:461 ../../source/cli/bench.rst:735
+#: ../../source/cli/bench.rst:1114
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/cli/bench.rst:220
+msgid "``--ldqa-document-length``"
+msgstr "``--ldqa-document-length``"
+
+#: ../../source/cli/bench.rst:221 ../../source/cli/bench.rst:265
+#: ../../source/cli/bench.rst:464
+msgid "10000"
+msgstr "10000"
+
+#: ../../source/cli/bench.rst:222
+msgid "Token length of each synthetic document."
+msgstr "每个合成文档的 token 长度。"
+
+#: ../../source/cli/bench.rst:223
+msgid "``--ldqa-query-per-document``"
+msgstr "``--ldqa-query-per-document``"
+
+#: ../../source/cli/bench.rst:224 ../../source/cli/bench.rst:362
+msgid "2"
+msgstr "2"
+
+#: ../../source/cli/bench.rst:225
+msgid "Number of questions asked per document."
+msgstr "每个文档的提问数量。"
+
+#: ../../source/cli/bench.rst:226
+msgid "``--ldqa-shuffle-policy``"
+msgstr "``--ldqa-shuffle-policy``"
+
+#: ../../source/cli/bench.rst:227
+msgid "random"
+msgstr "随机"
+
+#: ../../source/cli/bench.rst:228
+msgid "Request ordering: ``random`` (shuffled) or ``tile`` (round-by-round)."
+msgstr "请求排序方式：\\ ``random``\\ （随机打乱）或 ``tile``\\ （逐轮轮转）。"
+
+#: ../../source/cli/bench.rst:229
+msgid "``--ldqa-num-inflight-requests``"
+msgstr "``--ldqa-num-inflight-requests``"
+
+#: ../../source/cli/bench.rst:230 ../../source/cli/bench.rst:366
+msgid "3"
+msgstr "3"
+
+#: ../../source/cli/bench.rst:231 ../../source/cli/bench.rst:327
+msgid "Maximum concurrent in-flight requests."
+msgstr "最大并发在途请求数。"
+
+#: ../../source/cli/bench.rst:233 ../../source/cli/bench.rst:280
+#: ../../source/cli/bench.rst:329 ../../source/cli/bench.rst:420
+#: ../../source/cli/bench.rst:470
+msgid "**Example:**"
+msgstr "**示例：**"
+
+#: ../../source/cli/bench.rst:248
+msgid "multi-round-chat"
+msgstr "multi-round-chat"
+
+#: ../../source/cli/bench.rst:250
+msgid ""
+"Simulates multi-round chat with stateful sessions. Creates concurrent "
+"user sessions, dispatches requests at a fixed QPS rate, and records "
+"responses in session history so each subsequent query includes prior "
+"context."
+msgstr "模拟有状态的多轮聊天。创建并发用户会话，以固定 QPS 速率调度请求，并将响应记录到会话历史中，使每个后续查询都包含先前的上下文。"
+
+#: ../../source/cli/bench.rst:261
+msgid "``--mrc-shared-prompt-length``"
+msgstr "``--mrc-shared-prompt-length``"
+
+#: ../../source/cli/bench.rst:262
+msgid "2000"
+msgstr "2000"
+
+#: ../../source/cli/bench.rst:263
+msgid "System prompt token length per session."
+msgstr "每个会话的系统提示 token 长度。"
+
+#: ../../source/cli/bench.rst:264
+msgid "``--mrc-chat-history-length``"
+msgstr "``--mrc-chat-history-length``"
+
+#: ../../source/cli/bench.rst:266
+msgid "Pre-filled chat history token length."
+msgstr "预填充的聊天历史 token 长度。"
+
+#: ../../source/cli/bench.rst:267
+msgid "``--mrc-user-input-length``"
+msgstr "``--mrc-user-input-length``"
+
+#: ../../source/cli/bench.rst:268 ../../source/cli/bench.rst:467
+msgid "50"
+msgstr "50"
+
+#: ../../source/cli/bench.rst:269
+msgid "Tokens per user query."
+msgstr "每个用户查询的 token 数。"
+
+#: ../../source/cli/bench.rst:270
+msgid "``--mrc-output-length``"
+msgstr "``--mrc-output-length``"
+
+#: ../../source/cli/bench.rst:271
+msgid "200"
+msgstr "200"
+
+#: ../../source/cli/bench.rst:272
+msgid "Max tokens to generate per response."
+msgstr "每个响应最多生成的 token 数。"
+
+#: ../../source/cli/bench.rst:273
+msgid "``--mrc-qps``"
+msgstr "``--mrc-qps``"
+
+#: ../../source/cli/bench.rst:274
+msgid "1.0"
+msgstr "1.0"
+
+#: ../../source/cli/bench.rst:275
+msgid "Target queries per second."
+msgstr "每秒目标查询数。"
+
+#: ../../source/cli/bench.rst:276
+msgid "``--mrc-duration``"
+msgstr "``--mrc-duration``"
+
+#: ../../source/cli/bench.rst:277
+msgid "60.0"
+msgstr "60.0"
+
+#: ../../source/cli/bench.rst:278
+msgid "Benchmark duration in seconds."
+msgstr "基准测试持续时间，单位为秒。"
+
+#: ../../source/cli/bench.rst:293
+msgid "long-doc-permutator"
+msgstr "long-doc-permutator"
+
+#: ../../source/cli/bench.rst:295
+msgid ""
+"Stress-tests blended KV cache reuse by sending permutations of a set of "
+"context documents. Each request concatenates all context documents in a "
+"different order:"
+msgstr "通过发送一组上下文文档的不同排列，对混合 KV Cache 的重用进行压力测试。每个请求以不同顺序拼接所有上下文文档："
+
+#: ../../source/cli/bench.rst:302
+msgid ""
+"A single dummy warmup request is sent before the benchmark phase. "
+"Requests are dispatched with semaphore-controlled concurrency."
+msgstr "基准测试阶段开始前会发送一个虚拟预热请求。请求以信号量控制并发方式派发。"
+
+#: ../../source/cli/bench.rst:312
+msgid "``--ldp-num-contexts``"
+msgstr "``--ldp-num-contexts``"
+
+#: ../../source/cli/bench.rst:313
+msgid "5"
+msgstr "5"
+
+#: ../../source/cli/bench.rst:314
+msgid "Number of unique context documents."
+msgstr "独立上下文文档的数量。"
+
+#: ../../source/cli/bench.rst:315
+msgid "``--ldp-context-length``"
+msgstr "``--ldp-context-length``"
+
+#: ../../source/cli/bench.rst:316
+msgid "5000"
+msgstr "5000"
+
+#: ../../source/cli/bench.rst:317
+msgid "Token length of each context document."
+msgstr "每个上下文文档的 token 长度。"
+
+#: ../../source/cli/bench.rst:318
+msgid "``--ldp-system-prompt-length``"
+msgstr "``--ldp-system-prompt-length``"
+
+#: ../../source/cli/bench.rst:319
+msgid "1000"
+msgstr "1000"
+
+#: ../../source/cli/bench.rst:320
+msgid "Token length of the shared system prompt. Use ``0`` for no system prompt."
+msgstr "共享系统提示的 token 长度。使用 ``0`` 表示无系统提示。"
+
+#: ../../source/cli/bench.rst:321
+msgid "``--ldp-num-permutations``"
+msgstr "``--ldp-num-permutations``"
+
+#: ../../source/cli/bench.rst:322
+msgid "10"
+msgstr "10"
+
+#: ../../source/cli/bench.rst:323
+msgid ""
+"Number of distinct permutations to send. Capped at N! where N = ``--ldp-"
+"num-contexts``."
+msgstr "发送的不同排列数量，上限为 N!（其中 N = ``--ldp-num-contexts``\\ ）。"
+
+#: ../../source/cli/bench.rst:325
+msgid "``--ldp-num-inflight-requests``"
+msgstr "``--ldp-num-inflight-requests``"
+
+#: ../../source/cli/bench.rst:326 ../../source/cli/bench.rst:358
+msgid "1"
+msgstr "1"
+
+#: ../../source/cli/bench.rst:344
+msgid "prefix-suffix-tuner"
+msgstr "prefix-suffix-tuner"
+
+#: ../../source/cli/bench.rst:346
+msgid ""
+"A two-pass sequential workload designed to be run **unchanged** across "
+"three LMCache configurations to demonstrate the value of each cache tier "
+"(L0 HBM, L1 DRAM, L2 disk):"
+msgstr ""
+"一个两遍顺序工作负载，设计为在三种 LMCache 配置下 **不做任何修改** 地运行，以展示各缓存层级（L0 HBM、L1 DRAM、L2 "
+"磁盘）的价值："
+
+#: ../../source/cli/bench.rst:354
+msgid "Baseline"
+msgstr "基线"
+
+#: ../../source/cli/bench.rst:355
+msgid "LMCache config"
+msgstr "LMCache 配置"
+
+#: ../../source/cli/bench.rst:356
+msgid "Targeted overflow"
+msgstr "目标溢出"
+
+#: ../../source/cli/bench.rst:357
+msgid "Expected pass-2 hits"
+msgstr "预期的 pass-2 命中"
+
+#: ../../source/cli/bench.rst:359
+msgid "vanilla vLLM (L0 only)"
+msgstr "原生 vLLM (仅 L0)"
+
+#: ../../source/cli/bench.rst:360
+msgid "L0 (HBM)"
+msgstr "L0 (HBM)"
+
+#: ../../source/cli/bench.rst:361
+msgid "none -- every request a cold prefill"
+msgstr "无 —— 每个请求均为冷预填充"
+
+#: ../../source/cli/bench.rst:363
+msgid "vLLM + LMCache L1 + L2"
+msgstr "vLLM + LMCache L1 + L2"
+
+#: ../../source/cli/bench.rst:364 ../../source/cli/bench.rst:368
+msgid "L1 (DRAM)"
+msgstr "L1 (DRAM)"
+
+#: ../../source/cli/bench.rst:365
+msgid "L2 prefix hits (suffix recomputed)"
+msgstr "L2 前缀命中（后缀重计算）"
+
+#: ../../source/cli/bench.rst:367
+msgid "vLLM + LMCache L1 + L2 + CacheBlend"
+msgstr "vLLM + LMCache L1 + L2 + CacheBlend"
+
+#: ../../source/cli/bench.rst:369
+msgid "L2 prefix hits + CacheBlend suffix hits"
+msgstr "L2 前缀命中 + CacheBlend 后缀命中"
+
+#: ../../source/cli/bench.rst:371
+msgid ""
+"Set ``--kv-cache-volume`` to the size in GB of the tier you want to "
+"overflow (L0 size for Baseline 1, L1 size for Baselines 2 and 3). The "
+"workload itself is identical across baselines."
+msgstr ""
+"将 ``--kv-cache-volume`` 设置为希望发生溢出的层的大小（基线 1 对应 L0 大小，基线 2 和 3 对应 L1 "
+"大小）。各基线的工作负载本身完全相同。"
+
+#: ../../source/cli/bench.rst:375
+msgid "Each request has the layout::"
+msgstr "每个请求的布局::"
+
+#: ../../source/cli/bench.rst:379
+msgid ""
+"``num_prefixes`` distinct prefixes, each starting with ``PREFIX_<8-hex>``"
+" so the prefix's tokenized hash differs across the pool."
+msgstr ""
+"``num_prefixes`` 个不同的前缀，每个前缀以 ``PREFIX_<8-hex>`` 开头，以确保各前缀在池内的 token "
+"化哈希各不相同。"
+
+#: ../../source/cli/bench.rst:381
+msgid ""
+"A fresh random 32-token breaker per request, defeating ordinary prefix "
+"caching past the prefix boundary."
+msgstr "每个请求包含一段新的随机 32-token 分隔符，用于突破普通前缀缓存的前缀边界。"
+
+#: ../../source/cli/bench.rst:383
+msgid ""
+"A single shared suffix used by every request -- the only entry CacheBlend"
+" can reuse."
+msgstr "所有请求共享的单个后缀 —— 这是 CacheBlend 唯一能够重用的条目。"
+
+#: ../../source/cli/bench.rst:386
+msgid ""
+"Pass 1 (warmup) sends each prefix once to populate the cache; its stats "
+"are discarded. Pass 2 sends them again in identical order. Because LRU "
+"evicts the next-needed prefix on each pass-2 access, even a 1.05x "
+"overflow of the targeted tier is enough to make every pass-2 request miss"
+" that tier and fall through to the next one."
+msgstr ""
+"第 1 遍（预热）将每个前缀各发送一次以填充缓存，其统计数据被丢弃。第 2 遍以相同顺序再次发送。由于 LRU 在每次第 2 "
+"遍访问时会逐出下一个所需前缀，即使目标层仅溢出 1.05 倍，也足以使每个第 2 遍请求在该层未命中并降级到下一层。"
+
+#: ../../source/cli/bench.rst:399
+msgid "``--psf-context-length``"
+msgstr "``--psf-context-length``"
+
+#: ../../source/cli/bench.rst:400
+msgid "8000"
+msgstr "8000"
+
+#: ../../source/cli/bench.rst:401
+msgid "Total tokens per request (prefix + breaker + suffix)."
+msgstr "每个请求的总 token 数（前缀 + 分隔符 + 后缀）。"
+
+#: ../../source/cli/bench.rst:402
+msgid "``--psf-prefix-ratio``"
+msgstr "``--psf-prefix-ratio``"
+
+#: ../../source/cli/bench.rst:403
+msgid "0.8"
+msgstr "0.8"
+
+#: ../../source/cli/bench.rst:404
+msgid ""
+"Fraction of context-length used by the prefix. Must be in (0.0, 1.0). The"
+" remainder (minus a 32-token breaker) is the shared suffix."
+msgstr "前缀占上下文长度的比例，必须在 (0.0, 1.0) 区间内。剩余部分（减去 32 个 token 的分隔符）即为共享后缀。"
+
+#: ../../source/cli/bench.rst:406
+msgid "``--psf-thrash``"
+msgstr "``--psf-thrash``"
+
+#: ../../source/cli/bench.rst:407
+msgid "20.0"
+msgstr "20.0"
+
+#: ../../source/cli/bench.rst:408
+#, python-format
+msgid ""
+"**Size in GB of the KV-cache tier to overflow.** Use the L0 (HBM) size "
+"for vanilla vLLM, or the L1 (LMCache DRAM) size for tiered baselines. The"
+" workload sizes its prefix pool to slightly more than this (5% overflow "
+"internally), enough to drive every pass-2 request to a miss of that tier "
+"under sequential dispatch + LRU."
+msgstr ""
+"**要溢出的 KV Cache 层的大小（单位：GB）。** 原生 vLLM 请使用 L0（HBM）大小；分层基线请使用 L1（LMCache "
+"DRAM）大小。工作负载的前缀池大小略大于此值（内部溢出 5%），足以在顺序调度 + LRU 条件下使每个 pass-2 请求在该层发生未命中。"
+
+#: ../../source/cli/bench.rst:414
+msgid ""
+"The number of pass-2 (measured) requests equals the prefix pool size, "
+"computed as ``floor(psf_thrash * 1.05 * tokens_per_gb / prefix_tokens)``."
+" ``--kv-cache-volume`` is unused by this workload — sizing is driven "
+"solely by ``--psf-thrash``."
+msgstr ""
+"pass-2（测量阶段）的请求数等于前缀池大小，计算公式为 ``floor(psf_thrash * 1.05 * tokens_per_gb /"
+" prefix_tokens)``\\ 。此工作负载不使用 ``--kv-cache-volume``\\ ，规模完全由 ``--psf-"
+"thrash`` 决定。"
+
+#: ../../source/cli/bench.rst:433
+#, python-format
+msgid ""
+"For the analytical-model claim \"thrash ≈ L1 size → ~0% LMCache hit "
+"rate\" to hold empirically, the LMCache server must be started with "
+"``--eviction-ratio 0.99`` (default ``0.20`` only clears 20% per cycle, "
+"leaving ~60% of pass-1 content in cache through pass 2):"
+msgstr ""
+"为使分析模型的论断“thrash ≈ L1 大小 → ~0% LMCache 命中率”在实验中成立，LMCache 服务器必须以 "
+"``--eviction-ratio 0.99`` 启动（默认值 ``0.20`` 每个周期仅清除 20%，第 2 遍时约有 60% 的第 1 "
+"遍内容仍留存在缓存中）："
+
+#: ../../source/cli/bench.rst:444
+msgid ""
+"The workload itself sleeps 5 seconds between pass 1 (warmup) and pass 2 "
+"(measured), so LMCache's 1Hz batched-eviction polling thread has time to "
+"actually run.  Without that sleep, fast benchmarks complete before any "
+"eviction fires."
+msgstr ""
+"工作负载在第 1 遍（预热）和第 2 遍（测量）之间会休眠 5 秒，以便 LMCache 的 1Hz "
+"批量逐出轮询线程有机会实际运行。若没有这段休眠，快速基准测试会在任何逐出触发之前就已完成。"
+
+#: ../../source/cli/bench.rst:451
+msgid "random-prefill"
+msgstr "random-prefill"
+
+#: ../../source/cli/bench.rst:453
+msgid ""
+"Fires all requests simultaneously with ``max_tokens=1`` to measure pure "
+"prefill performance. No warmup phase."
+msgstr "以 ``max_tokens=1`` 同时发送所有请求，用于测量纯预填充性能，无预热阶段。"
+
+#: ../../source/cli/bench.rst:463
+msgid "``--rp-request-length``"
+msgstr "``--rp-request-length``"
+
+#: ../../source/cli/bench.rst:465
+msgid "Token length per prefill request."
+msgstr "每个预填充请求的 token 长度。"
+
+#: ../../source/cli/bench.rst:466
+msgid "``--rp-num-requests``"
+msgstr "``--rp-num-requests``"
+
+#: ../../source/cli/bench.rst:468
+msgid "Number of requests to fire."
+msgstr "发送的请求总数。"
+
+#: ../../source/cli/bench.rst:483
+msgid "Interactive Mode"
+msgstr "交互模式"
+
+#: ../../source/cli/bench.rst:485
+msgid "Interactive mode demo"
+msgstr "交互模式演示"
+
+#: ../../source/cli/bench.rst:489
+msgid ""
+"When ``--engine-url`` or ``--workload`` is not provided (and ``--no-"
+"interactive`` is not set), the tool enters interactive mode. It guides "
+"you through four phases:"
+msgstr ""
+"当未提供 ``--engine-url`` 或 ``--workload``\\ （且未设置 ``--no-interactive``\\ "
+"）时，工具将进入交互模式，引导您完成以下四个阶段："
+
+#: ../../source/cli/bench.rst:493
+msgid ""
+"**Required settings** -- engine URL, workload type, LMCache server (or "
+"tokens per GB)."
+msgstr "**必需设置** —— 引擎 URL、工作负载类型、LMCache 服务器（或每 GB 的 token 数）。"
+
+#: ../../source/cli/bench.rst:495
+msgid "**General settings** (optional gate) -- model name, KV cache volume."
+msgstr "**通用设置**\\ （可选）—— 模型名称、KV Cache 容量。"
+
+#: ../../source/cli/bench.rst:496
+msgid "**Workload settings** (optional gate) -- workload-specific parameters."
+msgstr "**工作负载设置**\\ （可选）—— 工作负载专项参数。"
+
+#: ../../source/cli/bench.rst:497
+msgid ""
+"**Summary and action** -- review configuration, then start the benchmark "
+"or export to a JSON file."
+msgstr "**摘要与操作** —— 审查配置，然后启动基准测试或将配置导出为 JSON 文件。"
+
+#: ../../source/cli/bench.rst:500
+msgid ""
+"Each prompt focuses on a single setting. Selection prompts use arrow "
+"keys; text and number prompts accept typed input with defaults shown in "
+"brackets."
+msgstr "每个提示聚焦于单一设置。选择类提示使用方向键操作；文本和数字类提示接受键入输入，默认值显示在括号中。"
+
+#: ../../source/cli/bench.rst:543
+msgid ""
+"When you choose \"Export configuration\", all auto-detected values (model"
+" name, tokens per GB) are resolved and saved to a portable JSON file."
+msgstr "当您选择“导出配置”时，所有自动检测到的值（模型名称、每 GB 的 token 数）将被解析并保存为可移植的 JSON 文件。"
+
+#: ../../source/cli/bench.rst:548
+msgid "Config File"
+msgstr "配置文件"
+
+#: ../../source/cli/bench.rst:550
+msgid ""
+"Config files store benchmark parameters but **not** environment-specific "
+"values like engine URL or LMCache URL. This lets you reuse the same "
+"config across different environments."
+msgstr ""
+"配置文件存储基准测试参数，但\\ **不**\\ 存储特定于环境的值（如引擎 URL 或 LMCache "
+"URL），以便同一份配置可在不同环境下复用。"
+
+#: ../../source/cli/bench.rst:554
+msgid "You can create a config file in three ways:"
+msgstr "您可以通过三种方式创建配置文件："
+
+#: ../../source/cli/bench.rst:556
+msgid ""
+"**Interactive mode** -- choose \"Export configuration\" at the summary "
+"step."
+msgstr "**交互模式** -- 在摘要步骤选择“导出配置”。"
+
+#: ../../source/cli/bench.rst:557
+msgid "**``--export-config``** -- resolve and export from CLI without running."
+msgstr "**``--export-config``** -- 从 CLI 解析并导出，而不运行。"
+
+#: ../../source/cli/bench.rst:558
+msgid ""
+"**Manually** -- write JSON with keys matching CLI arg names (dashes "
+"replaced by underscores)."
+msgstr "**手动编写** —— 编写 JSON，键名与 CLI 参数名称对应（将连字符替换为下划线）。"
+
+#: ../../source/cli/bench.rst:561
+msgid "Example config file:"
+msgstr "示例配置文件："
+
+#: ../../source/cli/bench.rst:576
+msgid "Load it with ``--config`` (engine URL must be provided separately):"
+msgstr "通过 ``--config`` 加载该配置文件（引擎 URL 需单独提供）："
+
+#: ../../source/cli/bench.rst:583
+msgid ""
+"CLI arguments override config file values, so you can use a base config "
+"and tweak individual settings:"
+msgstr "命令行参数会覆盖配置文件中的值，因此可以以基础配置为模板，按需调整个别设置："
+
+#: ../../source/cli/bench.rst:594 ../../source/cli/bench.rst:860
+msgid "Output"
+msgstr "输出"
+
+#: ../../source/cli/bench.rst:597
+msgid "Terminal (real-time progress)"
+msgstr "终端（实时进度）"
+
+#: ../../source/cli/bench.rst:599
+msgid ""
+"During the benchmark, a live progress display shows in-flight requests, "
+"average TTFT, decode speed, and throughput. Suppress it with ``-q``."
+msgstr "基准测试运行期间，实时进度面板会展示在途请求数、平均 TTFT、解码速度和吞吐量。可通过 ``-q`` 禁止显示。"
+
+#: ../../source/cli/bench.rst:603
+msgid "Terminal (final summary)"
+msgstr "终端（最终摘要）"
+
+#: ../../source/cli/bench.rst:605
+msgid "After completion, a summary table is printed:"
+msgstr "完成后，将打印一个摘要表："
+
+#: ../../source/cli/bench.rst:633
+msgid "CSV and JSON"
+msgstr "CSV 和 JSON"
+
+#: ../../source/cli/bench.rst:635
+msgid ""
+"``bench_results.csv`` -- per-request metrics (TTFT, latency, decode "
+"speed, token counts). Written by default; skip with ``--no-csv``."
+msgstr ""
+"``bench_results.csv`` —— 每个请求的指标（TTFT、延迟、解码速度、token 计数）。默认写入；可通过 ``--no-"
+"csv`` 跳过。"
+
+#: ../../source/cli/bench.rst:637
+msgid ""
+"``bench_summary.json`` -- aggregate statistics with percentiles and "
+"config metadata. Opt-in with ``--json``."
+msgstr "``bench_summary.json`` —— 聚合统计数据，包含百分位数和配置元数据。通过 ``--json`` 选项启用。"
+
+#: ../../source/cli/bench.rst:640
+msgid "Both files are written to ``--output-dir`` (default: current directory)."
+msgstr "两个文件均写入 ``--output-dir`` 指定的目录（默认：当前目录）。"
+
+#: ../../source/cli/bench.rst:644
+msgid "Exit Codes"
+msgstr "退出代码"
+
+#: ../../source/cli/bench.rst:650 ../../source/cli/bench.rst:949
+#: ../../source/cli/bench.rst:1370
+msgid "Code"
+msgstr "代码"
+
+#: ../../source/cli/bench.rst:651 ../../source/cli/bench.rst:950
+#: ../../source/cli/bench.rst:1371
+msgid "Meaning"
+msgstr "含义"
+
+#: ../../source/cli/bench.rst:652 ../../source/cli/bench.rst:767
+#: ../../source/cli/bench.rst:951 ../../source/cli/bench.rst:1372
+msgid "``0``"
+msgstr "``0``"
+
+#: ../../source/cli/bench.rst:653
+msgid "All requests succeeded."
+msgstr "所有请求均成功。"
+
+#: ../../source/cli/bench.rst:654 ../../source/cli/bench.rst:954
+#: ../../source/cli/bench.rst:1128 ../../source/cli/bench.rst:1136
+#: ../../source/cli/bench.rst:1143 ../../source/cli/bench.rst:1146
+#: ../../source/cli/bench.rst:1375
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/cli/bench.rst:655
+msgid "One or more requests failed."
+msgstr "一个或多个请求失败。"
+
+#: ../../source/cli/bench.rst:661
+msgid "server"
+msgstr "server"
+
+#: ../../source/cli/bench.rst:663
+msgid ""
+"The ``lmcache bench server`` command is an end-to-end sanity test for the"
+" LMCache Multi-Process (MP) cache server. It connects to a running server"
+" over ZMQ and exercises the full KV-cache data path for a sequence of "
+"synthetic requests, then optionally verifies per-chunk checksums through "
+"the HTTP API."
+msgstr ""
+"``lmcache bench server`` 命令是针对 LMCache MP 模式（多进程）缓存服务器的端到端健全性测试。它通过 ZMQ "
+"连接至正在运行的服务器，对一系列合成请求执行完整的 KV Cache 数据路径，并可选地通过 HTTP API 验证每个块的校验和。"
+
+#: ../../source/cli/bench.rst:673
+msgid ""
+"Unlike :ref:`lmcache bench engine <lmcache-bench-engine>`, this command "
+"does **not** require an inference engine. It only needs a running LMCache"
+" MP server (ZMQ + HTTP). GPU mode additionally requires a CUDA-capable "
+"device. It also requires the full ``lmcache`` install (not the "
+"lightweight ``lmcache-cli`` package)."
+msgstr ""
+"与 :ref:`lmcache bench engine <lmcache-bench-engine>` 不同，此命令\\ **不**\\ "
+"需要推理引擎，只需要一个正在运行的 LMCache MP 服务器（ZMQ + HTTP）。GPU 模式还额外需要支持 CUDA "
+"的设备，同时需要完整安装 ``lmcache``\\ （而非轻量级的 ``lmcache-cli`` 包）。"
+
+#: ../../source/cli/bench.rst:681 ../../source/cli/bench.rst:981
+msgid "What it does"
+msgstr "它的功能"
+
+#: ../../source/cli/bench.rst:683
+msgid "For each sequence in ``[--start, --end)``, the tool runs two passes:"
+msgstr "对于 ``[--start, --end)`` 范围内的每个序列，该工具执行两个阶段："
+
+#: ../../source/cli/bench.rst:685
+msgid ""
+"**Cold pass** -- ``LOOKUP`` is expected to miss, so the generated KV "
+"tensors are ``STORE``\\ d on the server."
+msgstr "**冷通道** —— ``LOOKUP`` 预计未命中，因此生成的 KV 张量将通过 ``STORE``\\\\ 写入服务器。"
+
+#: ../../source/cli/bench.rst:687
+msgid ""
+"**Warm pass** -- ``LOOKUP`` is expected to hit; the tool issues "
+"``RETRIEVE`` and compares the retrieved KV chunks' checksums to the "
+"originals."
+msgstr "**热通道** —— ``LOOKUP`` 预计命中；工具发出 ``RETRIEVE`` 并将检索到的 KV 块校验和与原始值进行比对。"
+
+#: ../../source/cli/bench.rst:691
+msgid "The full RPC path exercised is::"
+msgstr "完整的 RPC 路径是::"
+
+#: ../../source/cli/bench.rst:697
+msgid ""
+"When ``--url`` points to the server's HTTP endpoint, per-chunk checksums "
+"are additionally cross-checked against the server-side computation, so a "
+"mismatch between producer and consumer surfaces as a loud ``CHECKSUM "
+"MISMATCH`` log line."
+msgstr ""
+"当 ``--url`` 指向服务器的 HTTP 端点时，逐块校验和还会与服务器端的计算结果进行交叉核验，生产者与消费者之间的任何不一致都将以醒目的"
+" ``CHECKSUM MISMATCH`` 日志行呈现。"
+
+#: ../../source/cli/bench.rst:704 ../../source/cli/bench.rst:1038
+msgid "Quick start"
+msgstr "快速开始"
+
+#: ../../source/cli/bench.rst:706
+msgid "Start the MP server in one terminal:"
+msgstr "在一个终端中启动 MP 服务器："
+
+#: ../../source/cli/bench.rst:715
+msgid "Then in another terminal:"
+msgstr "然后在另一个终端中："
+
+#: ../../source/cli/bench.rst:723
+msgid ""
+"By default the tool runs forever (``--end`` unset); stop it with "
+"``Ctrl-C`` at any time. Pass ``--end N`` for a bounded run."
+msgstr ""
+"默认情况下该工具会持续运行（\\ ``--end`` 未设置）；可随时使用 ``Ctrl-C`` 停止。传递 ``--end N`` "
+"可限定运行次数。"
+
+#: ../../source/cli/bench.rst:728 ../../source/cli/bench.rst:1107
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/bench.rst:737
+msgid "``--rpc-url URL``"
+msgstr "``--rpc-url URL``"
+
+#: ../../source/cli/bench.rst:738
+msgid "``tcp://localhost:5555``"
+msgstr "``tcp://localhost:5555``"
+
+#: ../../source/cli/bench.rst:739
+msgid "ZMQ endpoint of the MP cache server."
+msgstr "MP 模式缓存服务器的 ZMQ 端点。"
+
+#: ../../source/cli/bench.rst:740
+msgid "``--url URL``"
+msgstr "``--url URL``"
+
+#: ../../source/cli/bench.rst:741
+msgid "``http://localhost:8080``"
+msgstr "``http://localhost:8080``"
+
+#: ../../source/cli/bench.rst:742
+msgid ""
+"HTTP base URL of the server's checksum API. Used to verify per-chunk "
+"checksums end-to-end."
+msgstr "服务器校验和 API 的 HTTP 基础 URL，用于端到端逐块校验和验证。"
+
+#: ../../source/cli/bench.rst:744
+#, python-brace-format
+msgid "``--mode {gpu,cpu}``"
+msgstr "``--mode {gpu,cpu}``"
+
+#: ../../source/cli/bench.rst:745
+msgid "``gpu``"
+msgstr "``gpu``"
+
+#: ../../source/cli/bench.rst:746
+msgid ""
+"Run mode. ``gpu`` allocates real CUDA tensors and uses CUDA IPC (lmcache-"
+"driven handle path). ``cpu`` allocates POSIX-SHM-backed tensors and uses "
+"the engine-driven (worker-side gather/scatter) path by default."
+msgstr ""
+"运行模式。``gpu`` 分配真实的 CUDA 张量并使用 CUDA IPC（基于 lmcache 的句柄路径）。``cpu`` 默认分配基于 "
+"POSIX-SHM 的张量并使用引擎驱动的（工作端聚集/散布）路径。"
+
+#: ../../source/cli/bench.rst:749
+#, python-brace-format
+msgid "``--transfer-mode {auto,engine_driven,lmcache_driven}``"
+msgstr "``--transfer-mode {auto,engine_driven,lmcache_driven}``"
+
+#: ../../source/cli/bench.rst:750
+msgid "``auto``"
+msgstr "``auto``"
+
+#: ../../source/cli/bench.rst:751
+msgid ""
+"Transport routing for STORE/RETRIEVE. ``lmcache_driven`` forces the "
+"single-shot handle path (``REGISTER_KV_CACHE`` + ``STORE``/``RETRIEVE``),"
+" which supports both CUDA IPC and CPU SHM zero-copy transfers. "
+"``engine_driven`` forces the worker-side gather/scatter path "
+"(``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT`` + ``PREPARE``/``COMMIT``). "
+"``auto`` maps gpu→lmcache_driven and cpu→engine_driven."
+msgstr ""
+"用于 STORE/RETRIEVE 的传输路由。``lmcache_driven`` 强制使用单次处理路径 "
+"(``REGISTER_KV_CACHE`` + ``STORE``/``RETRIEVE``)，支持 CUDA IPC 和 CPU SHM "
+"零拷贝传输。``engine_driven`` 强制使用工作端的聚集/分散路径 "
+"(``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT`` + "
+"``PREPARE``/``COMMIT``)。``auto`` 将 gpu 映射到 lmcache_driven，将 cpu 映射到 "
+"engine_driven。"
+
+#: ../../source/cli/bench.rst:757
+msgid "``--num-tokens N``"
+msgstr "``--num-tokens N``"
+
+#: ../../source/cli/bench.rst:758
+msgid "``512``"
+msgstr "``512``"
+
+#: ../../source/cli/bench.rst:759
+msgid "Tokens per synthetic request."
+msgstr "每个合成请求的 token 数。"
+
+#: ../../source/cli/bench.rst:760
+msgid "``--num-blocks N``"
+msgstr "``--num-blocks N``"
+
+#: ../../source/cli/bench.rst:761
+msgid "``1024``"
+msgstr "``1024``"
+
+#: ../../source/cli/bench.rst:762
+msgid "Number of paged blocks allocated on the GPU."
+msgstr "在 GPU 上分配的分页 KV 块数量。"
+
+#: ../../source/cli/bench.rst:763
+msgid "``--block-size N``"
+msgstr "``--block-size N``"
+
+#: ../../source/cli/bench.rst:764
+msgid "``16``"
+msgstr "``16``"
+
+#: ../../source/cli/bench.rst:765
+msgid "Tokens per paged block."
+msgstr "每个分页块的 token 数。"
+
+#: ../../source/cli/bench.rst:766
+msgid "``--start N``"
+msgstr "``--start N``"
+
+#: ../../source/cli/bench.rst:768
+msgid "First sequence number to run."
+msgstr "运行的第一个序列号。"
+
+#: ../../source/cli/bench.rst:769
+msgid "``--end N``"
+msgstr "``--end N``"
+
+#: ../../source/cli/bench.rst:770 ../../source/cli/bench.rst:784
+#: ../../source/cli/bench.rst:788 ../../source/cli/bench.rst:1117
+#: ../../source/cli/bench.rst:1164
+msgid "*(unset)*"
+msgstr "(未设置)"
+
+#: ../../source/cli/bench.rst:771
+msgid ""
+"Exclusive upper bound on sequence numbers. When omitted the loop runs "
+"forever."
+msgstr "序列号的独占上限，省略时循环将无限运行。"
+
+#: ../../source/cli/bench.rst:773
+msgid "``--interval SECS``"
+msgstr "``--interval SECS``"
+
+#: ../../source/cli/bench.rst:774
+msgid "``0.5``"
+msgstr "``0.5``"
+
+#: ../../source/cli/bench.rst:775
+msgid "Delay between successive sub-passes."
+msgstr "连续子通道之间的延迟。"
+
+#: ../../source/cli/bench.rst:776
+msgid "``--kvcache-shape-spec SPEC``"
+msgstr "``--kvcache-shape-spec SPEC``"
+
+#: ../../source/cli/bench.rst:777
+msgid "``(2,1024,16,8,128):float16:32``"
+msgstr "``(2,1024,16,8,128):float16:32``"
+
+#: ../../source/cli/bench.rst:778
+msgid "KV cache shape spec (see below)."
+msgstr "KV Cache 形状规格（见下文）。"
+
+#: ../../source/cli/bench.rst:779
+msgid "``--format FORMAT``"
+msgstr "``--format FORMAT``"
+
+#: ../../source/cli/bench.rst:780
+msgid "``terminal``"
+msgstr "``terminal``"
+
+#: ../../source/cli/bench.rst:781
+msgid ""
+"Stdout output format for the final metrics summary. Available: "
+"``terminal``, ``json``."
+msgstr "最终指标摘要的标准输出格式。可用格式：\\ ``terminal``\\ 、\\ ``json``\\ 。"
+
+#: ../../source/cli/bench.rst:783
+msgid "``--output PATH``"
+msgstr "``--output PATH``"
+
+#: ../../source/cli/bench.rst:785
+msgid ""
+"Save the final metrics summary to a file at PATH (format chosen by "
+"``--format``)."
+msgstr "将最终的指标摘要保存到 PATH 指定的文件中（格式由 ``--format`` 选择）。"
+
+#: ../../source/cli/bench.rst:789
+msgid ""
+"Suppress all progress messages during the run. Only the final structured "
+"metrics summary is emitted (unless also redirected via ``--output``)."
+msgstr "在运行期间抑制所有进度消息。仅输出最终的结构化指标摘要（除非也通过 ``--output`` 重定向）。"
+
+#: ../../source/cli/bench.rst:795
+msgid "CPU mode (no GPU)"
+msgstr "CPU 模式（无 GPU）"
+
+#: ../../source/cli/bench.rst:797
+msgid ""
+"``--mode cpu`` runs the same end-to-end path without a GPU. The server "
+"runs on a CPU-only host (``StubCPUDevice``); the bench tool allocates "
+"POSIX-SHM-backed KV tensors and exercises the full RPC path."
+msgstr ""
+"``--mode cpu`` 在没有 GPU 的情况下运行相同的端到端路径。服务器在仅有 CPU 的主机 (``StubCPUDevice``) "
+"上运行；基准工具分配基于 POSIX-SHM 的 KV 张量并执行完整的 RPC 路径。"
+
+#: ../../source/cli/bench.rst:801
+msgid ""
+"By default ``--mode cpu`` uses the engine-driven gather/scatter path "
+"(``auto`` → ``cpu→engine_driven``). To use the zero-copy SHM handle path "
+"instead, pass ``--transfer-mode lmcache_driven``:"
+msgstr ""
+"默认情况下，``--mode cpu`` 使用引擎驱动的收集/分发路径 (``auto`` → "
+"``cpu→engine_driven``)。要改用零拷贝 SHM 句柄路径，请传递 ``--transfer-mode "
+"lmcache_driven``："
+
+#: ../../source/cli/bench.rst:821
+msgid "KV cache shape spec"
+msgstr "KV 缓存形状规格"
+
+#: ../../source/cli/bench.rst:823
+msgid ""
+"The ``--kvcache-shape-spec`` flag describes how KV tensors are laid out "
+"on the GPU. A spec is one or more groups separated by ``;``:"
+msgstr "``--kvcache-shape-spec`` 参数描述 KV 张量在 GPU 上的布局，规格由一个或多个以 ``;`` 分隔的组构成："
+
+#: ../../source/cli/bench.rst:830
+msgid "Fields:"
+msgstr "字段："
+
+#: ../../source/cli/bench.rst:832
+msgid "``kv_size`` -- 2 for classical attention (separate K/V), 1 for MLA."
+msgstr "``kv_size`` —— 经典注意力机制（独立 K/V）为 2，MLA 为 1。"
+
+#: ../../source/cli/bench.rst:833
+msgid "``NB`` -- number of paged blocks."
+msgstr "``NB`` —— 分页块数量。"
+
+#: ../../source/cli/bench.rst:834
+msgid "``BS`` -- block size (tokens per block)."
+msgstr "``BS`` —— 块大小（每块的 token 数）。"
+
+#: ../../source/cli/bench.rst:835
+msgid "``NH`` -- number of attention heads per layer."
+msgstr "``NH`` —— 每层的注意力头数量。"
+
+#: ../../source/cli/bench.rst:836
+msgid "``HS`` -- head size (in elements)."
+msgstr "``HS`` —— 注意力头大小（以元素为单位）。"
+
+#: ../../source/cli/bench.rst:837
+msgid ""
+"``dtype`` -- element dtype (e.g. ``float16``, ``bfloat16``, ``float32``, "
+"``uint8``). The full set matches the keys of ``DTYPE_MAP`` in "
+"``lmcache/v1/kv_layer_groups.py``."
+msgstr ""
+"``dtype`` —— 元素数据类型（例如 ``float16``\\ 、\\ ``bfloat16``\\ 、\\ ``float32``\\"
+" 、\\ ``uint8``\\ ），完整集合与 ``lmcache/v1/kv_layer_groups.py`` 中 "
+"``DTYPE_MAP`` 的键一致。"
+
+#: ../../source/cli/bench.rst:840
+msgid "``layers`` -- number of layers in this group."
+msgstr "``layers`` —— 该组包含的层数。"
+
+#: ../../source/cli/bench.rst:842
+msgid ""
+"Multi-group specs let you model heterogeneous layers (for example, MLA "
+"layers + classical attention layers in the same model):"
+msgstr "多组规格支持对异构层建模（例如，同一模型中同时包含 MLA 层和经典注意力层）："
+
+#: ../../source/cli/bench.rst:851
+msgid ""
+"All groups must share the same ``NB`` and ``BS`` (this is a physical "
+"constraint of paged KV). Layer counts across groups sum to the total "
+"layer count registered with the server."
+msgstr "所有组必须共享相同的 ``NB`` 和 ``BS``\\ （这是分页 KV 的物理约束），各组层数之和等于向服务器注册的总层数。"
+
+#: ../../source/cli/bench.rst:855
+msgid ""
+"See ``parse_kvcache_shape_spec`` in ``lmcache/v1/kv_layer_groups.py`` for"
+" the authoritative parsing rules and validation errors."
+msgstr ""
+"完整的解析规则和验证错误说明请参阅 ``lmcache/v1/kv_layer_groups.py`` 中的 "
+"``parse_kvcache_shape_spec``\\ 。"
+
+#: ../../source/cli/bench.rst:862
+msgid ""
+"After the run completes (or is interrupted with ``Ctrl-C``), a structured"
+" metrics summary is printed. The summary includes:"
+msgstr "运行完成后（或被 ``Ctrl-C`` 中断后），将打印结构化的指标摘要，内容包括："
+
+#: ../../source/cli/bench.rst:865
+msgid ""
+"**Configuration** -- RPC URL, mode, transfer mode, tokens per request, "
+"interval."
+msgstr "**配置** —— RPC URL、模式、传输模式、每请求 token 数、间隔。"
+
+#: ../../source/cli/bench.rst:867
+msgid "**Results** -- total requests, checksum OK / FAIL counts, pass rate."
+msgstr "**结果** —— 总请求数、校验和 OK／FAIL 计数、通过率。"
+
+#: ../../source/cli/bench.rst:868
+msgid ""
+"**Latency sections** -- per-operation latency statistics (count, mean, "
+"min, max, p50, p99) for cold lookup, cold store, warm lookup, and warm "
+"retrieve."
+msgstr "**延迟部分** —— 每个操作的延迟统计信息（count、mean、min、max、p50、p99），涵盖冷查找、冷存储、热查找和热检索。"
+
+#: ../../source/cli/bench.rst:872
+msgid ""
+"Use ``--format json`` to get machine-readable output, or ``--output "
+"FILE`` to save the summary to a file."
+msgstr "使用 ``--format json`` 获取机器可读的输出，或使用 ``--output FILE`` 将摘要保存到文件中。"
+
+#: ../../source/cli/bench.rst:921
+msgid "Example output (progress)"
+msgstr "示例输出（进度）"
+
+#: ../../source/cli/bench.rst:923
+msgid ""
+"During the run, progress messages are printed to stdout (suppressed by "
+"``-q`` / ``--quiet``):"
+msgstr "运行期间，进度消息会打印到 stdout（可通过 ``-q`` / ``--quiet`` 禁止）："
+
+#: ../../source/cli/bench.rst:938
+msgid ""
+"Any ``CHECKSUM MISMATCH``, ``ERROR``, or Python traceback in the log "
+"indicates a real problem worth investigating."
+msgstr "日志中出现任何 ``CHECKSUM MISMATCH``\\ 、\\ ``ERROR`` 或 Python 回溯，均表明存在值得调查的真实问题。"
+
+#: ../../source/cli/bench.rst:943 ../../source/cli/bench.rst:1364
+msgid "Exit codes"
+msgstr "退出代码"
+
+#: ../../source/cli/bench.rst:952
+msgid ""
+"Test loop completed (or was interrupted cleanly with Ctrl-C) with no "
+"checksum mismatches."
+msgstr "测试循环正常完成（或通过 Ctrl-C 干净中断），无校验和不匹配。"
+
+#: ../../source/cli/bench.rst:955
+msgid ""
+"Fatal error (for example, CUDA unavailable in ``--mode gpu``, server "
+"unreachable, or a checksum mismatch)."
+msgstr "致命错误（例如，\\ ``--mode gpu`` 时 CUDA 不可用、服务器无法访问或校验和不匹配）。"
+
+#: ../../source/cli/bench.rst:961
+msgid "l2"
+msgstr "l2"
+
+#: ../../source/cli/bench.rst:963
+msgid ""
+"The ``lmcache bench l2`` command benchmarks an L2 cache adapter (e.g. the"
+" local-filesystem adapter) end-to-end through the same "
+"``parse_args_to_l2_adapters_config`` + ``create_l2_adapter`` pipeline "
+"that LMCache uses in production. Any registered adapter type can be "
+"tested without code changes: you describe the adapter with a single JSON "
+"spec and pick the operations to exercise."
+msgstr ""
+"``lmcache bench l2`` 命令通过与 LMCache 生产环境相同的 "
+"``parse_args_to_l2_adapters_config`` + ``create_l2_adapter`` 流水线，对 L2 "
+"缓存适配器（例如本地文件系统适配器）进行端到端基准测试。任何已注册的适配器类型均可在无需修改代码的情况下进行测试：只需用一个 JSON "
+"规范描述该适配器，并选择要执行的操作即可。"
+
+#: ../../source/cli/bench.rst:974
+msgid ""
+"Unlike :ref:`lmcache bench engine <lmcache-bench-engine>`, this command "
+"does **not** require an inference engine or an LMCache MP server. It only"
+" needs the adapter's own backing storage to be reachable (for the ``fs`` "
+"adapter, that simply means a writable directory)."
+msgstr ""
+"与 :ref:`lmcache bench engine <lmcache-bench-engine>` 不同，此命令 **不** 需要推理引擎或"
+" LMCache MP 服务器，只需适配器的后端存储可访问（对于 ``fs`` 适配器，只需一个可写目录）。"
+
+#: ../../source/cli/bench.rst:983
+msgid ""
+"For each measured operation the tool drives the adapter directly via its "
+"public submit/wait API:"
+msgstr "对于每个待测操作，该工具通过适配器的公共 submit/wait API 直接驱动适配器："
+
+#: ../../source/cli/bench.rst:986
+msgid ""
+"``Store``  -- ``submit_store_task`` writes ``num_keys`` MemoryObjs per "
+"submit and waits for the store eventfd."
+msgstr ""
+"``Store``  -- ``submit_store_task`` 每次提交写入 ``num_keys`` 个 MemoryObj，并等待存储"
+" eventfd。"
+
+#: ../../source/cli/bench.rst:988
+msgid ""
+"``Lookup`` -- ``submit_lookup_and_lock_task`` checks key existence (no "
+"payload transfer) and waits for the lookup eventfd."
+msgstr ""
+"``Lookup`` -- ``submit_lookup_and_lock_task`` 检查键是否存在（不传输负载），并等待查找 "
+"eventfd。"
+
+#: ../../source/cli/bench.rst:990
+msgid ""
+"``Load``   -- ``submit_load_task`` reads ``num_keys`` MemoryObjs per "
+"submit and waits for the load eventfd."
+msgstr ""
+"``Load``   -- ``submit_load_task`` 每次提交读取 ``num_keys`` 个 MemoryObj，并等待加载 "
+"eventfd。"
+
+#: ../../source/cli/bench.rst:993
+msgid ""
+"Each measured **round** issues ``--in-flight`` submits sequentially from "
+"a single producer thread and then waits for all of them to complete; the "
+"round duration is the wall-clock time from the first submit until the "
+"last completion. Warmup rounds run before measurement and their results "
+"are discarded from the final summary."
+msgstr ""
+"每个测量 **轮次** 从单个生产者线程顺序发出 ``--in-flight`` "
+"次提交，然后等待全部完成；轮次持续时间为从第一次提交到最后一次完成的墙钟时间。预热轮次在测量前运行，其结果不计入最终摘要。"
+
+#: ../../source/cli/bench.rst:999
+msgid ""
+"All three operations share the same key idx universe, so running ``--only"
+" store`` followed by ``--only load`` (or ``--only lookup``) with "
+"identical other flags hits exactly the same keys. This makes the "
+"benchmark useful as a quick regression test for adapters that should "
+"support a clean store -> load round-trip."
+msgstr ""
+"三种操作共享相同的键索引空间，因此在其他参数不变的情况下先运行 ``--only store`` 再运行 ``--only load``\\ （或"
+" ``--only lookup``\\ ）会访问完全相同的键。这使基准测试可作为适配器的快速回归测试，验证其是否支持完整的存储 -> 加载往返。"
+
+#: ../../source/cli/bench.rst:1007
+msgid ""
+"When ``--only`` is not given, the three operations are run **in a single "
+"process in the order** ``store -> lookup -> load``. For adapters whose "
+"backing storage sits behind an OS-level cache -- most notably the local-"
+"filesystem (``fs``) adapter, which is subject to the Linux **page cache**"
+" -- this means ``lookup`` and ``load`` will almost always observe the "
+"data that ``store`` just wrote still hot in RAM, and the reported numbers"
+" reflect page-cache throughput rather than the underlying device."
+msgstr ""
+"若未指定 ``--only``\\ ，三个操作将在 **单个进程中按顺序** 执行：\\ ``store -> lookup -> "
+"load``\\ 。对于后端存储位于操作系统级缓存之后的适配器——尤其是受 Linux **页面缓存** 影响的本地文件系统（\\ "
+"``fs``\\ ）适配器——``lookup`` 和 ``load`` 几乎总能观察到 ``store`` 刚写入的数据仍驻留在 RAM "
+"中，因此上报数字反映的是页面缓存吞吐量而非底层设备吞吐量。"
+
+#: ../../source/cli/bench.rst:1016
+msgid ""
+"To benchmark each operation against a cold cache, run them separately "
+"with ``--only`` and drop the OS caches in between, for example::"
+msgstr "若要在冷缓存条件下对各操作分别进行基准测试，请使用 ``--only`` 单独运行，并在两次运行之间清除操作系统缓存，例如::"
+
+#: ../../source/cli/bench.rst:1026
+msgid ""
+"For adapters that bypass the page cache (e.g. ``fs`` with "
+"``\"use_odirect\": true``) or that talk to a remote service without a "
+"local cache, the default combined run is usually fine."
+msgstr ""
+"对于绕过页面缓存的适配器（例如设置了 ``\"use_odirect\": true`` 的 ``fs`` "
+"适配器）或与无本地缓存的远程服务通信的适配器，直接使用默认的组合运行即可。"
+
+#: ../../source/cli/bench.rst:1030
+msgid ""
+"O_DIRECT adapters may also require the benchmark L1 buffer to satisfy the"
+" adapter's block alignment. Use ``--l1-align-bytes`` to set that "
+"alignment, commonly ``4096`` for local block devices. The payload size "
+"(``--data-size-kb * 1024``) must be a multiple of the selected alignment."
+msgstr ""
+"O_DIRECT 适配器可能还要求基准测试的 L1 缓冲区满足适配器的块对齐要求。可通过 ``--l1-align-bytes`` "
+"设置对齐值，本地块设备通常为 ``4096``\\ 。负载大小（\\ ``--data-size-kb * 1024``\\ "
+"）必须是该对齐值的整数倍。"
+
+#: ../../source/cli/bench.rst:1040
+msgid "Benchmark the local filesystem adapter with default parameters:"
+msgstr "使用默认参数对本地文件系统适配器进行基准测试："
+
+#: ../../source/cli/bench.rst:1047
+msgid ""
+"This runs all three operations (store, lookup, load) with one warmup "
+"round and one measurement round."
+msgstr "将运行全部三个操作（store、lookup、load），包括一次预热轮次和一次测量轮次。"
+
+#: ../../source/cli/bench.rst:1050
+msgid "Stress the adapter with more in-flight submits and larger payloads:"
+msgstr "使用更多并发提交和更大负载对适配器施压："
+
+#: ../../source/cli/bench.rst:1060
+msgid "Benchmark an O_DIRECT adapter with aligned L1 buffers:"
+msgstr "对使用对齐 L1 缓冲区的 O_DIRECT 适配器进行基准测试："
+
+#: ../../source/cli/bench.rst:1069
+msgid "Run only one operation (useful to isolate store vs. load throughput):"
+msgstr "仅运行单个操作（用于单独测量 store 与 load 的吞吐量）："
+
+#: ../../source/cli/bench.rst:1077
+msgid ""
+"Lookup with a controlled hit rate (the benchmark splits the lookup keys "
+"between a potentially-existing range and a guaranteed-non-existent "
+"range):"
+msgstr "使用受控命中率执行查找（基准测试将查找键拆分为可能存在的范围和保证不存在的范围）："
+
+#: ../../source/cli/bench.rst:1087
+msgid ""
+"Enable a store -> load round-trip data integrity check on the last "
+"measured round:"
+msgstr "在最后一轮测量中启用 store -> load 往返数据完整性校验："
+
+#: ../../source/cli/bench.rst:1096
+msgid ""
+"If you prefer to keep the JSON spec out of the command line, set the "
+"``L2_ADAPTER_JSON`` environment variable instead of passing "
+"``--l2-adapter``:"
+msgstr ""
+"如果希望不在命令行中暴露 JSON 规范，可设置 ``L2_ADAPTER_JSON`` 环境变量，而无需传递 "
+"``--l2-adapter``\\ ："
+
+#: ../../source/cli/bench.rst:1116
+msgid "``--l2-adapter JSON``"
+msgstr "``--l2-adapter JSON``"
+
+#: ../../source/cli/bench.rst:1118
+#, python-brace-format
+msgid ""
+"L2 adapter spec as JSON with a ``\"type\"`` field plus adapter-specific "
+"configs, e.g. ``'{\"type\":\"fs\",\"base_path\":\"/tmp/bench\"}'``. May "
+"be passed multiple times; only the first spec is benchmarked. If not "
+"provided, falls back to the ``L2_ADAPTER_JSON`` environment variable. "
+"Either the flag or the env var is **required**."
+msgstr ""
+"L2 适配器规范，以 JSON 格式提供，包含 ``\"type\"`` 字段及适配器专项配置，例如 "
+"``'{\\\"type\\\":\\\"fs\\\",\\\"base_path\\\":\\\"/tmp/bench\\\"}'``\\ "
+"。可多次传递；仅对第一个规范进行基准测试。若未提供，则退回到 ``L2_ADAPTER_JSON`` 环境变量。该参数或环境变量二者之一 "
+"**必须** 指定。"
+
+#: ../../source/cli/bench.rst:1124
+msgid "``--num-keys N``"
+msgstr "``--num-keys N``"
+
+#: ../../source/cli/bench.rst:1125
+msgid "``32``"
+msgstr "``32``"
+
+#: ../../source/cli/bench.rst:1126
+msgid "Number of keys per submit."
+msgstr "每次提交的键数。"
+
+#: ../../source/cli/bench.rst:1127
+msgid "``--in-flight N``"
+msgstr "``--in-flight N``"
+
+#: ../../source/cli/bench.rst:1129
+msgid ""
+"In-flight submits per round. Each round issues this many submits "
+"sequentially from a single producer thread, then waits for all of them."
+msgstr "每轮的在途提交数。每轮从单个生产者线程按序发出指定数量的提交，然后等待全部完成。"
+
+#: ../../source/cli/bench.rst:1132
+msgid "``--data-size-kb N``"
+msgstr "``--data-size-kb N``"
+
+#: ../../source/cli/bench.rst:1133
+msgid "``256``"
+msgstr "``256``"
+
+#: ../../source/cli/bench.rst:1134
+msgid "Data size per key, in KiB."
+msgstr "每个键的数据大小，单位为 KiB。"
+
+#: ../../source/cli/bench.rst:1135
+msgid "``--l1-align-bytes N``"
+msgstr "``--l1-align-bytes N``"
+
+#: ../../source/cli/bench.rst:1137
+msgid ""
+"Alignment in bytes for benchmark L1 buffers. Use a value at least as "
+"large as the adapter's block alignment when benchmarking O_DIRECT "
+"backends, for example ``4096`` for local block devices. ``--data-size-kb "
+"* 1024`` must be a multiple of this value."
+msgstr ""
+"基准测试 L1 缓冲区的对齐字节数。测试 O_DIRECT 后端时，该值应不小于适配器的块对齐要求，本地块设备通常为 ``4096``\\ 。\\"
+" ``--data-size-kb * 1024`` 必须是该值的整数倍。"
+
+#: ../../source/cli/bench.rst:1142
+msgid "``--rounds N``"
+msgstr "``--rounds N``"
+
+#: ../../source/cli/bench.rst:1144
+msgid "Measurement rounds per operation."
+msgstr "每个操作的测量轮数。"
+
+#: ../../source/cli/bench.rst:1145
+msgid "``--warmup-rounds N``"
+msgstr "``--warmup-rounds N``"
+
+#: ../../source/cli/bench.rst:1147
+msgid "Warmup rounds run before measurement; their results are discarded."
+msgstr "在测量前运行的预热轮次，其结果不计入统计。"
+
+#: ../../source/cli/bench.rst:1149
+msgid "``--lookup-max-hit-rate F``"
+msgstr "``--lookup-max-hit-rate F``"
+
+#: ../../source/cli/bench.rst:1150
+msgid "``0.0``"
+msgstr "``0.0``"
+
+#: ../../source/cli/bench.rst:1151
+msgid ""
+"Upper bound on the lookup hit rate, in ``[0, 1]``. The benchmark requests"
+" ``floor(N * rate)`` keys from the potentially-existing range and ``N - "
+"hit`` keys from a guaranteed-non-existent range, where ``N`` is the total"
+" number of lookup keys. The actual hit rate may be lower if those keys "
+"were never stored in this run."
+msgstr ""
+"查找命中率的上限，范围为 ``[0, 1]``\\ 。基准测试请求 ``floor(N * rate)`` 个来自可能存在范围的键，以及 ``N "
+"- hit`` 个来自保证不存在范围的键，其中 ``N`` 为查找键总数。若这些键在本次运行中从未被存储过，则实际命中率可能更低。"
+
+#: ../../source/cli/bench.rst:1157
+msgid "``--skip-verify`` / ``--no-skip-verify``"
+msgstr "``--skip-verify`` / ``--no-skip-verify``"
+
+#: ../../source/cli/bench.rst:1158
+msgid "``--skip-verify``"
+msgstr "``--skip-verify``"
+
+#: ../../source/cli/bench.rst:1159
+msgid ""
+"Skip the store -> load round-trip data integrity check (the default). "
+"Pass ``--no-skip-verify`` to enable verification on the last measured "
+"round; this requires both ``store`` and ``load`` to be exercised."
+msgstr ""
+"跳过 store -> load 往返数据完整性检查（默认行为）。传递 ``--no-skip-verify`` "
+"可在最后一轮测量中启用校验，此时要求同时执行 ``store`` 和 ``load``\\ 。"
+
+#: ../../source/cli/bench.rst:1163
+#, python-brace-format
+msgid "``--only {lookup,store,load}``"
+msgstr "``--only {lookup,store,load}``"
+
+#: ../../source/cli/bench.rst:1165
+msgid ""
+"Run only the specified operation. When omitted, all three operations are "
+"run in the order ``store -> lookup -> load``."
+msgstr "仅运行指定操作。省略时，按 ``store -> lookup -> load`` 顺序运行全部三个操作。"
+
+#: ../../source/cli/bench.rst:1167
+#, python-brace-format
+msgid "``--flamegraph {on,off}``"
+msgstr "``--flamegraph {开,关}``"
+
+#: ../../source/cli/bench.rst:1168
+msgid "``off``"
+msgstr "``关``"
+
+#: ../../source/cli/bench.rst:1169
+msgid ""
+"Capture a flame graph of the measured phases (``on``) or run the "
+"benchmark normally (``off``). When ``on``, the benchmark profiles itself "
+"and renders an SVG. Default ``off`` leaves benchmark behavior unchanged. "
+"See :ref:`Profiling / flame charts <lmcache-bench-l2-profiling>`."
+msgstr "捕获测量阶段的火焰图（``on``）或正常运行基准测试（``off``）。当设置为``on``时，基准测试会对自身进行分析并渲染 SVG。默认的``off``不会改变基准测试的行为。请参见 :ref:`Profiling / flame charts <lmcache-bench-l2-profiling>`。"
+
+#: ../../source/cli/bench.rst:1174
+#, python-brace-format
+msgid "``--flamegraph-mode {on-cpu,off-cpu}``"
+msgstr "``--flamegraph-mode {开启-CPU,关闭-CPU}``"
+
+#: ../../source/cli/bench.rst:1175
+msgid "``on-cpu``"
+msgstr "``on-cpu``"
+
+#: ../../source/cli/bench.rst:1176
+msgid ""
+"Flame-graph mode for ``--flamegraph on``. ``on-cpu`` shows where CPU time"
+" goes; ``off-cpu`` shows time blocked on I/O / locks (best for I/O-bound "
+"adapters)."
+msgstr "``--flamegraph on`` 的火焰图模式。 ``on-cpu`` 显示 CPU 时间的去向； ``off-cpu`` 显示在 I/O / 锁上被阻塞的时间（最适合 I/O 绑定的适配器）。"
+
+#: ../../source/cli/bench.rst:1179
+msgid "``--flamegraph-output PATH``"
+msgstr "``--flamegraph-output PATH``"
+
+#: ../../source/cli/bench.rst:1180
+msgid "*(auto)*"
+msgstr "*(自动)*"
+
+#: ../../source/cli/bench.rst:1181
+msgid ""
+"SVG output path. Default: "
+"``/tmp/lmcache_bench_flames/<adapter>.<mode>.svg``."
+msgstr "SVG 输出路径。默认: ``/tmp/lmcache_bench_flames/<adapter>.<mode>.svg``。"
+
+#: ../../source/cli/bench.rst:1183
+msgid "``--flamegraph-dir DIR``"
+msgstr "``--flamegraph-dir DIR``"
+
+#: ../../source/cli/bench.rst:1184
+msgid "*($FLAMEGRAPH_DIR or ~/FlameGraph)*"
+msgstr "*($FLAMEGRAPH_DIR 或 ~/FlameGraph)*"
+
+#: ../../source/cli/bench.rst:1185
+msgid ""
+"Directory with the FlameGraph scripts (``flamegraph.pl``, "
+"``stackcollapse-perf.pl``)."
+msgstr "包含 FlameGraph 脚本的目录（``flamegraph.pl``，``stackcollapse-perf.pl``）。"
+
+#: ../../source/cli/bench.rst:1190
+msgid "Adapter JSON spec"
+msgstr "适配器 JSON 规范"
+
+#: ../../source/cli/bench.rst:1192
+msgid ""
+"The ``--l2-adapter`` JSON is parsed by "
+"``lmcache.v1.distributed.l2_adapters.config.parse_args_to_l2_adapters_config``,"
+" the same entry point LMCache uses everywhere else. The minimum required "
+"field is ``type``; all remaining fields are forwarded to the adapter "
+"implementation as keyword arguments."
+msgstr ""
+"``--l2-adapter`` JSON 由 "
+"``lmcache.v1.distributed.l2_adapters.config.parse_args_to_l2_adapters_config``"
+" 解析，这也是 LMCache 在其他地方使用的同一入口点。最小必填字段为 ``type``\\ ，其余字段均以关键字参数形式转发给适配器实现。"
+
+#: ../../source/cli/bench.rst:1198
+msgid "Example for the local-filesystem adapter:"
+msgstr "本地文件系统适配器示例："
+
+#: ../../source/cli/bench.rst:1210
+msgid ""
+"See the source under ``lmcache/v1/distributed/l2_adapters/`` for the full"
+" list of adapter types and their accepted fields."
+msgstr "适配器类型及其支持字段的完整列表，请参阅 ``lmcache/v1/distributed/l2_adapters/`` 目录下的源代码。"
+
+#: ../../source/cli/bench.rst:1215
+msgid "Example output"
+msgstr "示例输出"
+
+#: ../../source/cli/bench.rst:1217
+msgid "Per-round progress (suppressed by ``-q``):"
+msgstr "每轮进度（可通过 ``-q`` 禁止）："
+
+#: ../../source/cli/bench.rst:1250
+msgid "Final summary (one section per exercised operation):"
+msgstr "最终摘要（每个操作对应一个部分）："
+
+#: ../../source/cli/bench.rst:1280
+msgid ""
+"Each operation section reports per-round duration statistics (avg / min /"
+" max / p50 / p99 / std), aggregate throughput (``avg_throughput_mbps`` --"
+" 0 for ``Lookup`` since it has no payload), average key-rate "
+"(``avg_ops_per_sec``), and a per-key latency."
+msgstr ""
+"每个操作部分报告每轮持续时间统计（avg / min / max / p50 / p99 / std）、汇总吞吐量（\\ "
+"``avg_throughput_mbps``\\ ，\\ ``Lookup`` 为 0，因其无负载传输）、平均键速率（\\ "
+"``avg_ops_per_sec``\\ ）及每键延迟。"
+
+#: ../../source/cli/bench.rst:1285
+msgid ""
+"For ``Lookup``, three additional fields are reported when ``--lookup-max-"
+"hit-rate`` is non-zero or some keys were found:"
+msgstr "对于 ``Lookup``\\ ，当 ``--lookup-max-hit-rate`` 非零或存在命中键时，还会上报以下三个额外字段："
+
+#: ../../source/cli/bench.rst:1288
+msgid "``Expected max hit rate`` -- the configured upper bound."
+msgstr "``Expected max hit rate`` —— 已配置的命中率上限。"
+
+#: ../../source/cli/bench.rst:1289
+msgid ""
+"``Expected hit keys`` -- ``floor(total_keys * rate)``, scaled for the "
+"measured rounds only."
+msgstr "``Expected hit keys`` —— ``floor(total_keys * rate)``\\ ，仅对测量轮次进行缩放。"
+
+#: ../../source/cli/bench.rst:1291
+msgid "``Actual hit rate`` -- the measured hit rate over the kept rounds."
+msgstr "``Actual hit rate`` —— 在有效测量轮次中实测的命中率。"
+
+#: ../../source/cli/bench.rst:1295
+msgid "Round-trip verification"
+msgstr "往返验证"
+
+#: ../../source/cli/bench.rst:1297
+msgid ""
+"When ``--no-skip-verify`` is passed and both ``store`` and ``load`` were "
+"run, the benchmark compares the load buffers from the last measured round"
+" against the byte pattern that ``store`` wrote (see "
+"``make_memory_objects`` in "
+"``lmcache/cli/commands/bench/l2_adapter_bench/data.py``):"
+msgstr ""
+"当传递 ``--no-skip-verify`` 且同时运行了 ``store`` 和 ``load`` "
+"时，基准测试会将最后一轮测量的加载缓冲区与 ``store`` 写入的字节模式进行比对（参见 "
+"``lmcache/cli/commands/bench/l2_adapter_bench/data.py`` 中的 "
+"``make_memory_objects``\\ ）："
+
+#: ../../source/cli/bench.rst:1308
+msgid ""
+"Verification is **off** by default because the stricter byte pattern "
+"requires both the store and load object batches to stay resident so the "
+"loaded data can be compared against the original store pattern."
+msgstr "默认情况下，验证是 **关闭** 的，因为更严格的字节模式要求存储和加载对象批次均保持常驻内存，以便将加载的数据与原始存储模式进行比对。"
+
+#: ../../source/cli/bench.rst:1316
+msgid "Profiling / flame charts"
+msgstr "性能分析 / 火焰图"
+
+#: ../../source/cli/bench.rst:1318
+msgid ""
+"When ``--flamegraph on`` is passed, the benchmark profiles the L2 "
+"adapter's performance and renders a flame graph of the measured phases:"
+msgstr "当传递 ``--flamegraph on`` 时，基准测试会对 L2 适配器的性能进行分析，并渲染出测量阶段的火焰图："
+
+#: ../../source/cli/bench.rst:1329
+msgid ""
+"The recorder samples every thread of the process (including native worker"
+" threads). Two modes are available via ``--flamegraph-mode``:"
+msgstr "记录器对进程的每个线程（包括本地工作线程）进行采样。可以通过 ``--flamegraph-mode`` 选择两种模式："
+
+#: ../../source/cli/bench.rst:1332
+msgid ""
+"**on-cpu** (default) -- ``perf record``; where CPU cycles go "
+"(serialization, copies, hashing)."
+msgstr "**在 CPU 上**（默认）-- ``perf record``；CPU 周期的去向（序列化、复制、哈希）。"
+
+#: ../../source/cli/bench.rst:1334
+msgid ""
+"**off-cpu** -- ``offcputime-bpfcc`` (bcc); time spent blocked (waiting on"
+" I/O, locks, eventfds). Often the more informative view for I/O-bound "
+"adapters such as ``fs`` and ``s3``."
+msgstr "**离线 CPU** -- ``offcputime-bpfcc`` (bcc); 被阻塞的时间（等待 I/O、锁、eventfds）。对于 I/O 绑定的适配器，如 ``fs`` 和 ``s3``，通常是更具信息量的视图。"
+
+#: ../../source/cli/bench.rst:1338
+msgid ""
+"Recording covers only the measured store/lookup/load work, so make the "
+"run long enough to collect samples (a few seconds is plenty -- use a "
+"large ``--rounds``). The SVG is written to ``--flamegraph-output`` "
+"(default ``/tmp/lmcache_bench_flames/<adapter>.<mode>.svg``)."
+msgstr "记录仅涵盖测量的存储/查找/加载工作，因此请确保运行时间足够长以收集样本（几秒钟就足够了——使用较大的 ``--rounds``）。SVG 文件写入 ``--flamegraph-output``（默认 ``/tmp/lmcache_bench_flames/<adapter>.<mode>.svg``）。"
+
+#: ../../source/cli/bench.rst:1343
+msgid ""
+"**Requirements.** Rendering needs Brendan Gregg's `FlameGraph "
+"<https://github.com/brendangregg/FlameGraph>`__ scripts (``--flamegraph-"
+"dir`` or ``FLAMEGRAPH_DIR``, default ``~/FlameGraph``; auto-cloned to a "
+"temp directory when absent). ``on-cpu`` needs ``perf`` (and "
+"``kernel.perf_event_paranoid`` low enough to profile non-root, or run as "
+"root); ``off-cpu`` needs ``bcc`` (``offcputime-bpfcc``) and ``sudo``. The"
+" required tools are checked up front: when ``--flamegraph on`` is "
+"requested but a tool is missing, the benchmark exits with a non-zero "
+"status and an actionable message naming the missing tool instead of "
+"running unprofiled. The default ``--flamegraph off`` skips all of this "
+"and leaves benchmark behavior unchanged."
+msgstr "**要求。** 渲染需要 Brendan Gregg 的 `FlameGraph <https://github.com/brendangregg/FlameGraph>`__ 脚本（``--flamegraph-dir`` 或 ``FLAMEGRAPH_DIR``，默认 ``~/FlameGraph``；缺失时会自动克隆到临时目录）。``on-cpu`` 需要 ``perf``（并且 ``kernel.perf_event_paranoid`` 需要足够低以便对非根用户进行分析，或者以根用户身份运行）；``off-cpu`` 需要 ``bcc``（``offcputime-bpfcc``）和 ``sudo``。所需工具会在前期检查：当请求 ``--flamegraph on`` 但缺少某个工具时，基准测试会以非零状态退出，并给出一个可操作的消息，指出缺失的工具，而不是运行未分析的测试。默认的 ``--flamegraph off`` 会跳过所有这些，并保持基准测试行为不变。"
+
+#: ../../source/cli/bench.rst:1357
+msgid ""
+"When comparing a change, profile each variant with the same ``--rounds`` "
+"and ``--flamegraph-mode`` and distinct ``--flamegraph-output`` paths "
+"(e.g. ``baseline.svg`` vs ``after.svg``) so the two flame graphs are "
+"directly comparable."
+msgstr "在比较更改时，使用相同的 ``--rounds`` 和 ``--flamegraph-mode`` 以及不同的 ``--flamegraph-output`` 路径（例如 ``baseline.svg`` 与 ``after.svg``）对每个变体进行分析，以便两个火焰图可以直接进行比较。"
+
+#: ../../source/cli/bench.rst:1373
+msgid ""
+"All requested operations completed and (when enabled) the round-trip "
+"verification passed."
+msgstr "所有请求操作均已完成，且（在启用时）往返验证通过。"
+
+#: ../../source/cli/bench.rst:1376
+msgid ""
+"Adapter creation failed, round-trip verification failed, or an operation "
+"hit a fatal error (e.g. all rounds timed out)."
+msgstr "适配器创建失败、往返验证失败，或某个操作遭遇致命错误（例如所有轮次均超时）。"
+
+#: ../../source/cli/bench.rst:1378
+msgid "``2``"
+msgstr "``2``"
+
+#: ../../source/cli/bench.rst:1379
+msgid ""
+"Invalid invocation: the ``--l2-adapter`` JSON / ``L2_ADAPTER_JSON`` env "
+"var was missing or could not be parsed, an option value was invalid, or "
+"``--flamegraph on`` was requested but the profiling toolchain is "
+"unavailable."
+msgstr "无效的调用：缺少或无法解析 ``--l2-adapter`` JSON / ``L2_ADAPTER_JSON`` 环境变量，某个选项值无效，或者请求了 ``--flamegraph on`` 但分析工具链不可用。"
+
+#~ msgid ""
+#~ "Run mode. Only ``gpu`` is supported "
+#~ "today; CPU mode is a planned "
+#~ "follow-up."
+#~ msgstr "运行模式。目前仅支持 ``gpu``；CPU 模式是计划中的后续功能。"
+
+#~ msgid ""
+#~ "``--transfer-mode handle`` on CPU mode"
+#~ " is not yet implemented and will "
+#~ "be added in a future release."
+#~ msgstr "``--transfer-mode handle`` 在 CPU 模式下尚未实现，将在未来的版本中添加。"
+
+#~ msgid ""
+#~ "Verification is **off** by default "
+#~ "because the stricter byte pattern also"
+#~ " forces every key to allocate its "
+#~ "own ``data_size`` buffer (otherwise the "
+#~ "runner is free to reuse a single"
+#~ " shared buffer across keys to keep"
+#~ " the memory footprint small)."
+#~ msgstr ""
+#~ "默认情况下，验证是 **关闭** 的，因为更严格的字节模式也迫使每个键分配其自己的 "
+#~ "``data_size`` 缓冲区（否则运行程序可以自由地在键之间重用一个共享缓冲区，以保持内存占用小）。"
+
+#~ msgid ""
+#~ "The ``--l2-adapter`` JSON / "
+#~ "``L2_ADAPTER_JSON`` env var was missing "
+#~ "or could not be parsed."
+#~ msgstr "``--l2-adapter`` JSON 或 ``L2_ADAPTER_JSON`` 环境变量缺失或无法解析。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/coordinator.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/coordinator.po
new file mode 100644
index 0000000..22e45c0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/coordinator.po
@@ -0,0 +1,208 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-29 10:44+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/coordinator.rst:2
+msgid "lmcache coordinator"
+msgstr "lmcache coordinator"
+
+#: ../../source/cli/coordinator.rst:4
+msgid ""
+"The ``lmcache coordinator`` command launches the LMCache MP "
+"**coordinator**, a standalone HTTP service that tracks the MP server "
+"instances in a deployment. MP servers register with it and send periodic "
+"heartbeats; the coordinator evicts any instance whose heartbeat lapses "
+"past ``--instance-timeout``."
+msgstr ""
+"``lmcache coordinator`` 命令启动 LMCache MP **协调器**\\ ，这是一个独立的 HTTP "
+"服务，用于跟踪部署中的 MP 服务器实例。MP 服务器向其注册并发送定期心跳；协调器会逐出任何心跳超时的实例，该超时时间由 "
+"``--instance-timeout`` 指定。"
+
+#: ../../source/cli/coordinator.rst:9
+msgid ""
+"It replaces ``python -m lmcache.v1.mp_coordinator``. The process runs in "
+"the foreground; stop it with ``Ctrl-C``."
+msgstr ""
+"它替代了 ``python -m lmcache.v1.mp_coordinator``\\ 。该进程在前台运行；使用 ``Ctrl-C`` "
+"停止它。"
+
+#: ../../source/cli/coordinator.rst:17
+msgid "Quick start"
+msgstr "快速开始"
+
+#: ../../source/cli/coordinator.rst:27
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/coordinator.rst:33
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/coordinator.rst:34
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/coordinator.rst:35
+msgid "``--host HOST``"
+msgstr "``--host HOST``"
+
+#: ../../source/cli/coordinator.rst:36
+msgid "Bind address for the coordinator's HTTP server (default: ``0.0.0.0``)."
+msgstr "协调器 HTTP 服务器的绑定地址（默认：\\ ``0.0.0.0``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:37
+msgid "``--port PORT``"
+msgstr "``--port PORT``"
+
+#: ../../source/cli/coordinator.rst:38
+msgid "HTTP port (default: ``9300``)."
+msgstr "HTTP 端口（默认值：\\ ``9300``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:39
+msgid "``--instance-timeout SECS``"
+msgstr "``--instance-timeout SECS``"
+
+#: ../../source/cli/coordinator.rst:40
+msgid ""
+"Seconds without a heartbeat after which an instance is evicted (default: "
+"``30``)."
+msgstr "在没有心跳的情况下，经过多少秒后实例被逐出（默认值：\\ ``30``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:42
+msgid "``--health-check-interval SECS``"
+msgstr "``--health-check-interval SECS``"
+
+#: ../../source/cli/coordinator.rst:43
+msgid ""
+"Seconds between health-check sweeps; ``0`` disables the loop (default: "
+"``10``)."
+msgstr "健康检查扫描之间的秒数；\\ ``0`` 禁用循环（默认值：\\ ``10``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:45
+msgid "``--eviction-check-interval SECS``"
+msgstr "``--eviction-check-interval SECS``"
+
+#: ../../source/cli/coordinator.rst:46
+msgid ""
+"Seconds between L2 eviction sweeps; ``0`` disables the loop (default: "
+"``5``)."
+msgstr "L2 逐出扫描之间的秒数；\\ ``0`` 禁用循环（默认值：\\ ``5``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:48
+msgid "``--eviction-ratio RATIO``"
+msgstr "``--eviction-ratio RATIO``"
+
+#: ../../source/cli/coordinator.rst:49
+msgid ""
+"Fraction of tracked keys (by count) to evict per cycle, ``0.0`` to "
+"``1.0`` (default: ``0.2``)."
+msgstr "每个周期逐出的跟踪键的比例（按计数），\\ ``0.0`` 到 ``1.0``\\ （默认值：\\ ``0.2``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:51
+msgid "``--trigger-watermark RATIO``"
+msgstr "``--trigger-watermark RATIO``"
+
+#: ../../source/cli/coordinator.rst:52
+msgid ""
+"Eviction fires when usage reaches this fraction of the quota, ``0.0`` "
+"(exclusive) to ``1.0`` (default: ``1.0``)."
+msgstr "当使用量达到配额的这个比例时会触发逐出，\\ ``0.0``\\ （不包括）到\\ ``1.0``\\ （默认值：\\ ``1.0``\\ ）。"
+
+#: ../../source/cli/coordinator.rst:54
+msgid "``--blend-chunk-size N``"
+msgstr "``--blend-chunk-size N``"
+
+#: ../../source/cli/coordinator.rst:55
+msgid ""
+"Tokens per chunk for the global CacheBlend directory; must equal the "
+"LMCache chunk size the blend servers use (default: ``256``)."
+msgstr "全局 CacheBlend 目录中每个块的令牌数；必须等于混合服务器使用的 LMCache 块大小（默认值：``256``）。"
+
+#: ../../source/cli/coordinator.rst:57
+msgid "``--blend-probe-stride N``"
+msgstr "``--blend-probe-stride N``"
+
+#: ../../source/cli/coordinator.rst:58
+msgid ""
+"Positions between CacheBlend match probes; ``1`` probes every offset for "
+"full recall (default: ``1``)."
+msgstr "在 CacheBlend 匹配探测之间的位置；``1`` 在每个偏移量处探测以实现完全回忆（默认值：``1``）。"
+
+#: ../../source/cli/coordinator.rst:60
+msgid "``--timeout-keep-alive SECS``"
+msgstr "``--timeout-keep-alive SECS``"
+
+#: ../../source/cli/coordinator.rst:61
+msgid ""
+"Seconds the HTTP server keeps idle connections open before closing them. "
+"Must be greater than the MP servers' heartbeat interval (default ``5``), "
+"otherwise heartbeat requests may hit a closing connection and fail with "
+"``Server disconnected without sending a response`` (default: ``10``)."
+msgstr "HTTP服务器在关闭空闲连接之前保持连接打开的秒数。必须大于MP服务器的心跳间隔（默认``5``），否则心跳请求可能会遇到关闭的连接并失败，错误信息为``服务器在未发送响应的情况下断开连接``（默认值：``10``）。"
+
+#: ../../source/cli/coordinator.rst:68
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/cli/coordinator.rst:70
+msgid ""
+"Every flag is optional. Unset flags fall back to the "
+"``LMCACHE_MP_COORDINATOR_*`` environment variables (``HOST``, ``PORT``, "
+"``INSTANCE_TIMEOUT``, ``HEALTH_CHECK_INTERVAL``, "
+"``EVICTION_CHECK_INTERVAL``, ``EVICTION_RATIO``, ``TRIGGER_WATERMARK``, "
+"``BLEND_CHUNK_SIZE``, ``BLEND_PROBE_STRIDE``, ``TIMEOUT_KEEP_ALIVE``), "
+"and then to the built-in defaults. A supplied flag always overrides the "
+"matching env-derived value, so env-only deployments keep working "
+"unchanged."
+msgstr "每个标志都是可选的。未设置的标志将回退到 ``LMCACHE_MP_COORDINATOR_*`` 环境变量（``HOST``、``PORT``、``INSTANCE_TIMEOUT``、``HEALTH_CHECK_INTERVAL``、``EVICTION_CHECK_INTERVAL``、``EVICTION_RATIO``、``TRIGGER_WATERMARK``、``BLEND_CHUNK_SIZE``、``BLEND_PROBE_STRIDE``、``TIMEOUT_KEEP_ALIVE``），然后再回退到内置默认值。提供的标志始终会覆盖匹配的环境派生值，因此仅使用环境的部署将保持不变。"
+
+#: ../../source/cli/coordinator.rst:78
+msgid ""
+"A second set of env-only knobs controls the startup L2 resync — "
+"``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC`` (default ``True``), "
+"``LMCACHE_MP_COORDINATOR_RESYNC_POLL_INTERVAL`` (``1``), "
+"``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT`` (``60``), and "
+"``LMCACHE_MP_COORDINATOR_RESYNC_PAGE_SIZE`` (``1000``). See "
+":doc:`/mp/coordinator` for the boot-time resync flow and the active "
+"eviction loop."
+msgstr ""
+"第二组仅环境的控制选项控制启动 L2 重新同步 — "
+"``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC``\\ （默认 "
+"``True``）、``LMCACHE_MP_COORDINATOR_RESYNC_POLL_INTERVAL``\\ "
+"（``1``）、``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT``\\ （``60``）和 "
+"``LMCACHE_MP_COORDINATOR_RESYNC_PAGE_SIZE``\\ "
+"（``1000``）。有关启动时重新同步流程和活动逐出循环，请参见 :doc:`/mp/coordinator`。"
+
+#: ../../source/cli/coordinator.rst:86
+msgid ""
+"The coordinator drives fleet-wide L2 eviction by calling each MP server's"
+" ``DELETE /l2`` endpoint, and resync paginates ``GET /l2/keys`` on a "
+"registered MP server. Both endpoints are documented at :ref:`mp-http-l2"
+"-keys-api`."
+msgstr ""
+"协调器通过调用每个 MP 服务器的 ``DELETE /l2`` 端点来驱动全队列的 L2 逐出，并且 resync 在注册的 MP 服务器上对 "
+"``GET /l2/keys`` 进行分页。这两个端点的文档见 :ref:`mp-http-l2-keys-api`。"
+
+#: ../../source/cli/coordinator.rst:91
+msgid ""
+"See :doc:`/mp/coordinator` for the coordinator's architecture, "
+"registration protocol, and HTTP API."
+msgstr "请参阅 :doc:`/mp/coordinator` 以了解协调器的架构、注册协议和 HTTP API。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/describe.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/describe.po
new file mode 100644
index 0000000..fd3fd52
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/describe.po
@@ -0,0 +1,244 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/describe.rst:2
+msgid "lmcache describe"
+msgstr "lmcache describe"
+
+#: ../../source/cli/describe.rst:4
+msgid ""
+"The ``lmcache describe`` command shows the detailed status of a running "
+"service. Two targets are supported:"
+msgstr "``lmcache describe`` 命令显示正在运行的服务的详细状态。支持两个目标："
+
+#: ../../source/cli/describe.rst:7
+msgid ""
+"``kvcache`` — the LMCache KV cache service (health, L1 storage, "
+"registered models, L2 adapters)."
+msgstr "``kvcache`` — LMCache KV Cache 服务（健康状况、L1 存储、注册的模型、L2 适配器）。"
+
+#: ../../source/cli/describe.rst:9
+msgid ""
+"``engine`` — the inference engine (vLLM) LMCache is paired with (model, "
+"context window, health, in-flight requests)."
+msgstr "``engine`` — 推理引擎 (vLLM) 与 LMCache 配对的 (模型、上下文窗口、健康状况、正在处理的请求)。"
+
+#: ../../source/cli/describe.rst:13
+msgid "KV Cache Service (``kvcache``)"
+msgstr "KV Cache 服务 (``kvcache``)"
+
+#: ../../source/cli/describe.rst:57 ../../source/cli/describe.rst:86
+msgid "The output shows:"
+msgstr "输出显示："
+
+#: ../../source/cli/describe.rst:59
+msgid "**Overview** — health status, engine type, chunk size."
+msgstr "**概述** — 健康状态、引擎类型、块大小。"
+
+#: ../../source/cli/describe.rst:60
+msgid "**L1 storage** — capacity, usage, eviction policy, cached object count."
+msgstr "**L1 存储** — 容量、使用情况、逐出策略、缓存对象数量。"
+
+#: ../../source/cli/describe.rst:61
+msgid ""
+"**Registered models** — per-model KV cache layout: a context-wide summary"
+" followed by one kernel group section per kernel group, each with the "
+"engine KV tensor shape (symbolic and concrete), attention backend, and "
+"group geometry."
+msgstr ""
+"**注册模型** — 每个模型的 KV Cache 布局：一个上下文范围的摘要，后面跟着每个内核组的一个内核组部分，每个部分都有引擎 KV "
+"张量形状（符号和具体）、注意力后端和组几何。"
+
+#: ../../source/cli/describe.rst:64
+msgid "**L2 adapters** — type, health, backend, stored objects, and utilization."
+msgstr "**L2 适配器** — 类型、健康状况、后端、存储对象和利用率。"
+
+#: ../../source/cli/describe.rst:67
+msgid "Inference Engine (``engine``)"
+msgstr "推理引擎 (``engine``)"
+
+#: ../../source/cli/describe.rst:69
+msgid ""
+"``describe engine`` inspects the vLLM inference engine instead of the "
+"LMCache service, reading only the engine's own HTTP endpoints "
+"(``/v1/models``, ``/health``, ``/metrics``)."
+msgstr "``describe engine`` 检查 vLLM 推理引擎，而不是 LMCache 服务，仅读取引擎自身的 HTTP 端点（``/v1/models``、``/health``、``/metrics``）。"
+
+#: ../../source/cli/describe.rst:88
+msgid ""
+"**Model** and **Max context** — the served model id and its maximum "
+"context length, from ``/v1/models``."
+msgstr "**模型** 和 **最大上下文** — 提供的模型 ID 及其最大上下文长度，来自 ``/v1/models``。"
+
+#: ../../source/cli/describe.rst:90
+msgid "**Status** — ``OK`` / ``UNHEALTHY`` from the engine's ``/health`` probe."
+msgstr "**状态** — ``OK`` / ``UNHEALTHY`` 来自引擎的 ``/health`` 探针。"
+
+#: ../../source/cli/describe.rst:91
+msgid ""
+"**Running requests** — in-flight requests, summed from the "
+"``vllm:num_requests_running`` metric. Shows ``N/A`` if metrics are "
+"disabled or unreachable."
+msgstr "**运行请求** — 正在进行的请求，从 ``vllm:num_requests_running`` 指标中汇总。如果指标被禁用或无法访问，则显示 ``N/A``。"
+
+#: ../../source/cli/describe.rst:95
+msgid ""
+"Only the ``/v1/models`` fetch is required: if ``/health`` or ``/metrics``"
+" is unavailable the command still reports what it can rather than "
+"failing."
+msgstr "仅需要 ``/v1/models`` 获取：如果 ``/health`` 或 ``/metrics`` 不可用，命令仍会报告它能提供的信息，而不是失败。"
+
+#: ../../source/cli/describe.rst:115
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/describe.rst:121
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/describe.rst:122
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/describe.rst:123
+msgid "``target``"
+msgstr "``target``"
+
+#: ../../source/cli/describe.rst:124
+msgid "What to describe (positional, required): ``kvcache`` or ``engine``."
+msgstr "描述内容（位置参数，必需）：``kvcache`` 或 ``engine``。"
+
+#: ../../source/cli/describe.rst:125
+msgid "``--url``"
+msgstr "``--url``"
+
+#: ../../source/cli/describe.rst:126
+msgid ""
+"Server URL. Defaults per target: ``http://localhost:8080`` for "
+"``kvcache``, ``http://localhost:8000`` for ``engine``."
+msgstr "服务器 URL。默认值根据目标而定：``kvcache`` 的默认值为 ``http://localhost:8080``，``engine`` 的默认值为 ``http://localhost:8000``。"
+
+#: ../../source/cli/describe.rst:128
+msgid "``--format``"
+msgstr "``--format``"
+
+#: ../../source/cli/describe.rst:129
+msgid "Output format: ``terminal`` (default) or ``json``."
+msgstr "输出格式：\\ ``terminal``\\ （默认）或\\ ``json``\\ 。"
+
+#: ../../source/cli/describe.rst:130
+msgid "``--output PATH``"
+msgstr "``--output PATH``"
+
+#: ../../source/cli/describe.rst:131
+msgid "Save metrics to a file (format follows ``--format``)."
+msgstr "将指标保存到文件中（格式遵循 ``--format``\\ ）。"
+
+#: ../../source/cli/describe.rst:132
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/describe.rst:133
+msgid "Suppress stdout output. Exit code only."
+msgstr "抑制标准输出。仅返回退出代码。"
+
+#: ../../source/cli/describe.rst:136
+msgid "JSON Output"
+msgstr "JSON 输出"
+
+#: ../../source/cli/describe.rst:138
+msgid ""
+"Use ``--format json`` for machine-readable output. Models, kernel groups,"
+" and L2 adapters are collected into lists for easy programmatic access:"
+msgstr "使用 ``--format json`` 以机器可读的输出格式。模型、内核组和 L2 适配器被收集到列表中，以便于程序化访问："
+
+#: ../../source/cli/describe.rst:197
+msgid "Engine KV Shape Abbreviations"
+msgstr "引擎 KV 形状缩写"
+
+#: ../../source/cli/describe.rst:199
+msgid ""
+"The ``engine_kv_shape`` field uses short names from the "
+"``EngineKVFormat`` enum:"
+msgstr "``engine_kv_shape`` 字段使用来自 ``EngineKVFormat`` 枚举的短名称："
+
+#: ../../source/cli/describe.rst:205
+msgid "Abbrev"
+msgstr "缩写"
+
+#: ../../source/cli/describe.rst:206
+msgid "Meaning"
+msgstr "含义"
+
+#: ../../source/cli/describe.rst:207
+msgid "NB"
+msgstr "注意事项"
+
+#: ../../source/cli/describe.rst:208
+msgid "num_blocks"
+msgstr "num_blocks"
+
+#: ../../source/cli/describe.rst:209
+msgid "NL"
+msgstr "NL"
+
+#: ../../source/cli/describe.rst:210
+msgid "num_layers"
+msgstr "num_layers"
+
+#: ../../source/cli/describe.rst:211
+msgid "BS"
+msgstr "批量大小"
+
+#: ../../source/cli/describe.rst:212
+msgid "block_size"
+msgstr "块大小"
+
+#: ../../source/cli/describe.rst:213
+msgid "NH"
+msgstr "NH"
+
+#: ../../source/cli/describe.rst:214
+msgid "num_heads"
+msgstr "头数"
+
+#: ../../source/cli/describe.rst:215
+msgid "HS"
+msgstr "HS"
+
+#: ../../source/cli/describe.rst:216
+msgid "head_size"
+msgstr "头部大小"
+
+#: ../../source/cli/describe.rst:217
+msgid "PBS"
+msgstr "PBS"
+
+#: ../../source/cli/describe.rst:218
+msgid "page_buffer_size (NB × BS)"
+msgstr "页面缓冲区大小 (NB × BS)"
+
+#~ msgid "``kvcache``"
+#~ msgstr "``kvcache``"
+
+#~ msgid "LMCache HTTP server URL (default: ``http://localhost:8080``)."
+#~ msgstr "LMCache HTTP 服务器 URL（默认：\\ ``http://localhost:8080``\\ ）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/index.po
new file mode 100644
index 0000000..573db24
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/index.po
@@ -0,0 +1,233 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-15 11:17+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/index.rst:2
+msgid "CLI Reference"
+msgstr "CLI 参考"
+
+#: ../../source/cli/index.rst:4
+msgid ""
+"The ``lmcache`` command-line interface provides tools for launching, "
+"managing, inspecting, and benchmarking LMCache servers and the inference "
+"engines in front of them."
+msgstr "``lmcache`` 命令行接口提供了启动、管理、检查和基准测试 LMCache 服务器及其前面的推理引擎的工具。"
+
+#: ../../source/cli/index.rst:12
+msgid ""
+"After installing LMCache, the ``lmcache`` command is available globally. "
+"Run ``lmcache -h`` to see all commands, or ``lmcache <command> -h`` for a"
+" specific command."
+msgstr "安装 LMCache 后，\\ ``lmcache`` 命令可以全局使用。运行 ``lmcache -h`` 查看所有命令，或运行 ``lmcache <command> -h`` 查看特定命令的帮助。"
+
+#: ../../source/cli/index.rst:17
+msgid "Installation"
+msgstr "安装"
+
+#: ../../source/cli/index.rst:19
+msgid "The ``lmcache`` CLI ships in two packages:"
+msgstr "``lmcache`` CLI 包含两个软件包："
+
+#: ../../source/cli/index.rst:25
+msgid "Package"
+msgstr "包"
+
+#: ../../source/cli/index.rst:26
+msgid "Install"
+msgstr "安装"
+
+#: ../../source/cli/index.rst:27
+msgid "When to use"
+msgstr "何时使用"
+
+#: ../../source/cli/index.rst:28
+msgid "``lmcache``"
+msgstr "``lmcache``"
+
+#: ../../source/cli/index.rst:29
+msgid "``pip install lmcache``"
+msgstr "``pip install lmcache``"
+
+#: ../../source/cli/index.rst:30
+msgid ""
+"Full install: server, CLI, and CUDA extensions. Required for ``server``, "
+"``bench server``, ``bench l2``, and ``trace``. Linux + GPU."
+msgstr "完整安装：服务器、CLI 和 CUDA 扩展。\\ ``server``\\ 、\\ ``bench server``\\ 、\\ ``bench l2`` 和 ``trace`` 所需。Linux + GPU。"
+
+#: ../../source/cli/index.rst:33
+msgid "``lmcache-cli``"
+msgstr "``lmcache-cli``"
+
+#: ../../source/cli/index.rst:34
+msgid "``pip install lmcache-cli``"
+msgstr "``pip install lmcache-cli``"
+
+#: ../../source/cli/index.rst:35
+msgid ""
+"CLI only: ``ping``, ``query``, ``describe``, ``kvcache``, ``quota``, "
+"``bench engine``. No GPU required, any OS."
+msgstr "仅限 CLI: ``ping``, ``query``, ``describe``, ``kvcache``, ``quota``, ``bench engine``\\ 。不需要 GPU，任何操作系统均可。"
+
+#: ../../source/cli/index.rst:40
+msgid ""
+"Do not install both packages in the same environment — they both provide "
+"the ``lmcache`` entry point."
+msgstr "请勿在同一环境中安装这两个软件包 — 它们都提供 ``lmcache`` 入口点。"
+
+#: ../../source/cli/index.rst:44
+msgid "Available Commands"
+msgstr "可用命令"
+
+#: ../../source/cli/index.rst:50
+msgid "Command"
+msgstr "命令"
+
+#: ../../source/cli/index.rst:51
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/index.rst:52
+msgid ":doc:`server`"
+msgstr ":doc:`server`"
+
+#: ../../source/cli/index.rst:53
+msgid "Launch the LMCache MP server (ZMQ + HTTP). Requires the full install."
+msgstr "启动 LMCache MP 服务器（ZMQ + HTTP）。需要完整安装。"
+
+#: ../../source/cli/index.rst:54
+msgid ":doc:`coordinator`"
+msgstr ":doc:`coordinator`"
+
+#: ../../source/cli/index.rst:55
+msgid "Launch the LMCache MP coordinator (HTTP instance registry)."
+msgstr "启动 LMCache MP 协调器（HTTP 实例注册表）。"
+
+#: ../../source/cli/index.rst:56
+msgid ":doc:`describe`"
+msgstr ":doc:`describe`"
+
+#: ../../source/cli/index.rst:57
+msgid "Show detailed status of a running LMCache service."
+msgstr "显示正在运行的 LMCache 服务的详细状态。"
+
+#: ../../source/cli/index.rst:58
+msgid ":doc:`ping`"
+msgstr ":doc:`ping`"
+
+#: ../../source/cli/index.rst:59
+msgid "Liveness check for LMCache or vLLM servers."
+msgstr "对 LMCache 或 vLLM 服务器的存活检查。"
+
+#: ../../source/cli/index.rst:60
+msgid ":doc:`query`"
+msgstr ":doc:`query`"
+
+#: ../../source/cli/index.rst:61
+msgid "Single-shot query interface for the serving engine."
+msgstr "服务引擎的单次查询接口。"
+
+#: ../../source/cli/index.rst:62
+msgid ":doc:`bench`"
+msgstr ":doc:`bench`"
+
+#: ../../source/cli/index.rst:63
+msgid ""
+"Run sustained benchmarks against an inference engine (``engine``), an "
+"LMCache MP server (``server``), or an L2 cache adapter (``l2``)."
+msgstr "对推理引擎（\\ ``engine``\\ ）、LMCache MP 服务器（\\ ``server``\\ ）或 L2 缓存适配器（\\ ``l2``\\ ）运行持续基准测试。"
+
+#: ../../source/cli/index.rst:66
+msgid ":doc:`kvcache`"
+msgstr ":doc:`kvcache`"
+
+#: ../../source/cli/index.rst:67
+msgid "Manage KV cache state (e.g. clear L1 cache) on a running server."
+msgstr "在运行的服务器上管理 KV Cache 状态（例如，清除 L1 缓存）。"
+
+#: ../../source/cli/index.rst:68
+msgid ":doc:`quota`"
+msgstr ":doc:`quota`"
+
+#: ../../source/cli/index.rst:69
+msgid "Manage per-salt cache quotas (set, get, list, delete)."
+msgstr "管理每个盐值的缓存配额（设置、获取、列出、删除）。"
+
+#: ../../source/cli/index.rst:70
+msgid ":doc:`trace`"
+msgstr ":doc:`trace`"
+
+#: ../../source/cli/index.rst:71
+msgid "Inspect and replay storage-level trace files."
+msgstr "检查和重放存储级跟踪文件。"
+
+#: ../../source/cli/index.rst:72
+msgid ":doc:`tool`"
+msgstr ":doc:`tool`"
+
+#: ../../source/cli/index.rst:73
+msgid "Run offline analysis tools (e.g. the cache simulator)."
+msgstr "运行离线分析工具（例如缓存模拟器）。"
+
+#: ../../source/cli/index.rst:76
+msgid "Output Formats"
+msgstr "输出格式"
+
+#: ../../source/cli/index.rst:78
+msgid "Commands that produce metrics share three common flags:"
+msgstr "产生指标的命令共享三个常见标志："
+
+#: ../../source/cli/index.rst:80
+#, python-brace-format
+msgid "``--format {terminal,json}`` — stdout format (default: ``terminal``)."
+msgstr "``--format {terminal,json}`` — 标准输出格式（默认：\\ ``terminal``\\ ）。"
+
+#: ../../source/cli/index.rst:81
+msgid "``--output PATH`` — also write metrics to a file (uses ``--format``)."
+msgstr "``--output PATH`` — 还将指标写入文件（使用 ``--format``\\ ）。"
+
+#: ../../source/cli/index.rst:82
+msgid "``-q`` / ``--quiet`` — suppress stdout; rely on the exit code."
+msgstr "``-q`` / ``--quiet`` — 抑制 stdout；依赖退出代码。"
+
+#: ../../source/cli/index.rst:84
+msgid ""
+"The terminal output uses human-readable labels (e.g. ``\"Round trip time "
+"(ms)\"``), while JSON uses machine-readable keys (e.g. "
+"``\"round_trip_time_ms\"``)."
+msgstr "终端输出使用人类可读的标签（例如 ``\"Round trip time (ms)\"``\\ ），而 JSON 使用机器可读的键（例如 ``\"round_trip_time_ms\"``\\ ）。"
+
+#: ../../source/cli/index.rst:89
+msgid "Adding New Commands"
+msgstr "添加新命令"
+
+#: ../../source/cli/index.rst:91
+msgid ""
+"New CLI subcommands are added by creating a ``BaseCommand`` subclass "
+"under ``lmcache/cli/commands/``; they are discovered and registered "
+"automatically. See :doc:`/developer_guide/cli` for details."
+msgstr ""
+"通过在 ``lmcache/cli/commands/`` 下创建 ``BaseCommand`` 子类来添加新的 CLI "
+"子命令；它们会被自动发现和注册。有关详细信息，请参见 :doc:`/developer_guide/cli`。"
+
+#~ msgid ""
+#~ "For a comprehensive guide with examples,"
+#~ " see :doc:`/getting_started/cli`."
+#~ msgstr "有关带有示例的全面指南，请参见 :doc:`/getting_started/cli`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/kvcache.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/kvcache.po
new file mode 100644
index 0000000..f2b8ad7
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/kvcache.po
@@ -0,0 +1,157 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/kvcache.rst:2
+msgid "lmcache kvcache"
+msgstr "lmcache kvcache"
+
+#: ../../source/cli/kvcache.rst:4
+msgid ""
+"The ``lmcache kvcache`` command manages KV cache state on a running "
+"LMCache server."
+msgstr "``lmcache kvcache`` 命令管理正在运行的 LMCache 服务器上的 KV Cache 状态。"
+
+#: ../../source/cli/kvcache.rst:28
+msgid "clear"
+msgstr "清除"
+
+#: ../../source/cli/kvcache.rst:30
+msgid ""
+"Clear all cached KV data in **L1 (CPU memory)** on the target LMCache "
+"server."
+msgstr "清除目标 LMCache 服务器上 **L1 (CPU 内存)** 中所有缓存的 KV 数据。"
+
+#: ../../source/cli/kvcache.rst:36
+msgid "**Example:**"
+msgstr "**示例：**"
+
+#: ../../source/cli/kvcache.rst:46
+msgid "**JSON output** (for scripting with ``jq``):"
+msgstr "**JSON 输出** (用于与 ``jq`` 脚本交互):"
+
+#: ../../source/cli/kvcache.rst:58
+msgid "**Quiet mode** (exit code only, no output):"
+msgstr "**静默模式**\\ （仅退出代码，无输出）："
+
+#: ../../source/cli/kvcache.rst:67
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/kvcache.rst:73
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/kvcache.rst:74
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/cli/kvcache.rst:75
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/kvcache.rst:76
+msgid "``--url``"
+msgstr "``--url``"
+
+#: ../../source/cli/kvcache.rst:77
+msgid "Yes"
+msgstr "是"
+
+#: ../../source/cli/kvcache.rst:78
+msgid "URL of the LMCache MP HTTP server (e.g. ``http://localhost:8000``)."
+msgstr "LMCache MP HTTP 服务器的 URL（例如 ``http://localhost:8000``\\ ）。"
+
+#: ../../source/cli/kvcache.rst:79
+msgid "``--format``"
+msgstr "``--format``"
+
+#: ../../source/cli/kvcache.rst:80 ../../source/cli/kvcache.rst:83
+#: ../../source/cli/kvcache.rst:86
+msgid "No"
+msgstr "不"
+
+#: ../../source/cli/kvcache.rst:81
+msgid "Output format: ``terminal`` (default) or ``json``."
+msgstr "输出格式：\\ ``terminal``\\ （默认）或\\ ``json``\\ 。"
+
+#: ../../source/cli/kvcache.rst:82
+msgid "``--output``"
+msgstr "``--output``"
+
+#: ../../source/cli/kvcache.rst:84
+msgid "Save output to a file (uses the format chosen by ``--format``)."
+msgstr "将输出保存到文件中（使用 ``--format`` 选择的格式）。"
+
+#: ../../source/cli/kvcache.rst:85
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/kvcache.rst:87
+msgid "Suppress stdout. Useful in scripts where you only need the exit code."
+msgstr "抑制标准输出。在只需要退出代码的脚本中很有用。"
+
+#: ../../source/cli/kvcache.rst:90
+msgid "Exit Codes"
+msgstr "退出代码"
+
+#: ../../source/cli/kvcache.rst:96
+msgid "Code"
+msgstr "代码"
+
+#: ../../source/cli/kvcache.rst:97
+msgid "Meaning"
+msgstr "含义"
+
+#: ../../source/cli/kvcache.rst:98
+msgid "``0``"
+msgstr "``0``"
+
+#: ../../source/cli/kvcache.rst:99
+msgid "Success."
+msgstr "成功。"
+
+#: ../../source/cli/kvcache.rst:100
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/cli/kvcache.rst:101
+msgid "Error (connection failure, server error, bad arguments)."
+msgstr "错误（连接失败、服务器错误、参数错误）。"
+
+#: ../../source/cli/kvcache.rst:104
+msgid "Common Patterns"
+msgstr "常见模式"
+
+#: ../../source/cli/kvcache.rst:106
+msgid "**Handle temporary server unavailability:**"
+msgstr "**处理临时服务器不可用:**"
+
+#: ../../source/cli/kvcache.rst:108
+msgid ""
+"If the server is temporarily unreachable (e.g. due to network issue), the"
+" command fails with exit code 1. For persistent connectivity issues, use "
+"``lmcache ping`` to diagnose."
+msgstr "如果服务器暂时无法访问（例如，由于网络问题），命令将以退出代码 1 失败。对于持续的连接问题，请使用 ``lmcache ping`` 进行诊断。"
+
+#: ../../source/cli/kvcache.rst:120
+msgid "**Clear cache and capture JSON result:**"
+msgstr "**清除缓存并捕获 JSON 结果：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/ping.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/ping.po
new file mode 100644
index 0000000..1639c1e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/ping.po
@@ -0,0 +1,123 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-01 10:55+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/ping.rst:2
+msgid "lmcache ping"
+msgstr "lmcache ping"
+
+#: ../../source/cli/ping.rst:4
+msgid ""
+"The ``lmcache ping`` command is a liveness check for an LMCache KV cache "
+"server or a vLLM serving engine."
+msgstr "``lmcache ping`` 命令用于检查 LMCache KV Cache 服务器或 vLLM 服务引擎的存活状态。"
+
+#: ../../source/cli/ping.rst:22
+msgid ""
+"``ping kvcache`` checks the ``/healthcheck`` endpoint; ``ping engine`` "
+"checks ``/health``."
+msgstr "``ping kvcache`` 检查 ``/healthcheck`` 端点； ``ping engine`` 检查 ``/health``\\ 。"
+
+#: ../../source/cli/ping.rst:26
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/ping.rst:32
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/ping.rst:33
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/ping.rst:34
+msgid "``kvcache`` | ``engine``"
+msgstr "``kvcache`` | ``engine``"
+
+#: ../../source/cli/ping.rst:35
+msgid "Target to ping (positional, required)."
+msgstr "要 ping 的目标（位置参数，必填）。"
+
+#: ../../source/cli/ping.rst:36
+msgid "``--url``"
+msgstr "``--url``"
+
+#: ../../source/cli/ping.rst:37
+msgid ""
+"Server URL. Defaults to ``http://localhost:8080`` for ``kvcache``, "
+"``http://localhost:8000`` for ``engine``."
+msgstr "服务器 URL。对于 ``kvcache`` 默认为 ``http://localhost:8080``\\ ，对于 ``engine`` 默认为 ``http://localhost:8000``\\ 。"
+
+#: ../../source/cli/ping.rst:39
+msgid "``--format``"
+msgstr "``--format``"
+
+#: ../../source/cli/ping.rst:40
+msgid "Output format: ``terminal`` (default) or ``json``."
+msgstr "输出格式：\\ ``terminal``\\ （默认）或\\ ``json``\\ 。"
+
+#: ../../source/cli/ping.rst:41
+msgid "``--output PATH``"
+msgstr "``--output PATH``"
+
+#: ../../source/cli/ping.rst:42
+msgid "Save metrics to a file (format follows ``--format``)."
+msgstr "将指标保存到文件中（格式遵循 ``--format``\\ ）。"
+
+#: ../../source/cli/ping.rst:43
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/ping.rst:44
+msgid "Suppress stdout output. Exit code only."
+msgstr "抑制标准输出。仅返回退出代码。"
+
+#: ../../source/cli/ping.rst:47
+msgid "JSON Output"
+msgstr "JSON 输出"
+
+#: ../../source/cli/ping.rst:64
+msgid "Exit Codes"
+msgstr "退出代码"
+
+#: ../../source/cli/ping.rst:70
+msgid "Code"
+msgstr "代码"
+
+#: ../../source/cli/ping.rst:71
+msgid "Meaning"
+msgstr "含义"
+
+#: ../../source/cli/ping.rst:72
+msgid "``0``"
+msgstr "``0``"
+
+#: ../../source/cli/ping.rst:73
+msgid "Server is reachable (HTTP 200)."
+msgstr "服务器可达（HTTP 200）。"
+
+#: ../../source/cli/ping.rst:74
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/cli/ping.rst:75
+msgid "Connection failure or non-200 response."
+msgstr "连接失败或非 200 响应。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/query.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/query.po
new file mode 100644
index 0000000..a8cb3f9
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/query.po
@@ -0,0 +1,178 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-01 10:55+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/query.rst:2
+msgid "lmcache query"
+msgstr "lmcache query"
+
+#: ../../source/cli/query.rst:4
+msgid ""
+"The ``lmcache query`` command sends a single OpenAI-compatible inference "
+"request and reports token and latency metrics. It has two targets:"
+msgstr "``lmcache query`` 命令发送一个单一的兼容 OpenAI 的推理请求，并报告令牌和延迟指标。它有两个目标："
+
+#: ../../source/cli/query.rst:11
+msgid "``engine`` — send one request to a serving engine's HTTP API."
+msgstr "``engine`` — 向服务引擎的 HTTP API 发送一个请求。"
+
+#: ../../source/cli/query.rst:12
+msgid "``kvcache`` — query KV-cache endpoints (not implemented yet)."
+msgstr "``kvcache`` — 查询 KV Cache 端点（尚未实现）。"
+
+#: ../../source/cli/query.rst:16
+msgid "query engine"
+msgstr "查询引擎"
+
+#: ../../source/cli/query.rst:18
+#, python-brace-format
+msgid ""
+"The ``query engine`` subcommand sends one request to the engine API and "
+"reports metrics. ``--prompt`` supports placeholders: ``{lmcache}`` loads "
+"``lmcache/cli/documents/lmcache.txt``, and custom documents can be passed"
+" with ``--documents NAME=PATH``. The prompt token count is taken directly"
+" from the usage data reported by the engine (``stream_options: "
+"{include_usage: true}``)."
+msgstr "``query engine`` 子命令向引擎 API 发送一个请求并报告指标。 ``--prompt`` 支持占位符： ``{lmcache}`` 加载 ``lmcache/cli/documents/lmcache.txt``\\ ，并且可以通过 ``--documents NAME=PATH`` 传递自定义文档。提示的令牌计数直接来自引擎报告的使用数据 (``stream_options: {include_usage: true}``)。"
+
+#: ../../source/cli/query.rst:45
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/query.rst:51
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/query.rst:52
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/cli/query.rst:53
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/query.rst:54
+msgid "``--url URL``"
+msgstr "``--url URL``"
+
+#: ../../source/cli/query.rst:55 ../../source/cli/query.rst:58
+msgid "Yes"
+msgstr "是"
+
+#: ../../source/cli/query.rst:56
+msgid "Serving engine base URL (e.g. ``http://localhost:8000/v1``)."
+msgstr "服务引擎基础 URL（例如 ``http://localhost:8000/v1``\\ ）。"
+
+#: ../../source/cli/query.rst:57
+msgid "``--prompt TEXT``"
+msgstr "``--prompt TEXT``"
+
+#: ../../source/cli/query.rst:59
+#, python-brace-format
+msgid ""
+"Prompt text with optional ``{name}`` placeholders. ``{lmcache}`` expands "
+"to the bundled sample document."
+msgstr "带有可选 ``{name}`` 占位符的提示文本。 ``{lmcache}`` 展开为捆绑的示例文档。"
+
+#: ../../source/cli/query.rst:61
+msgid "``--model ID``"
+msgstr "``--model ID``"
+
+#: ../../source/cli/query.rst:62 ../../source/cli/query.rst:66
+#: ../../source/cli/query.rst:69 ../../source/cli/query.rst:72
+#: ../../source/cli/query.rst:76 ../../source/cli/query.rst:79
+#: ../../source/cli/query.rst:83 ../../source/cli/query.rst:86
+#: ../../source/cli/query.rst:89
+msgid "No"
+msgstr "不"
+
+#: ../../source/cli/query.rst:63
+msgid ""
+"Model ID for the serving engine. Auto-detected from the engine's reported"
+" usage if omitted."
+msgstr "服务引擎的模型 ID。如果省略，将根据引擎报告的使用情况自动检测。"
+
+#: ../../source/cli/query.rst:65
+msgid "``--max-tokens N``"
+msgstr "``--max-tokens N``"
+
+#: ../../source/cli/query.rst:67
+msgid "Maximum completion tokens (default: 128)."
+msgstr "最大完成令牌数（默认：128）。"
+
+#: ../../source/cli/query.rst:68
+msgid "``--timeout SECS``"
+msgstr "``--timeout SECS``"
+
+#: ../../source/cli/query.rst:70
+msgid "HTTP timeout in seconds (default: 30)."
+msgstr "HTTP 超时（单位：秒，默认值：30）。"
+
+#: ../../source/cli/query.rst:71
+msgid "``--documents NAME=PATH``"
+msgstr "``--documents NAME=PATH``"
+
+#: ../../source/cli/query.rst:73
+#, python-brace-format
+msgid ""
+"Load file text for ``{NAME}`` in ``--prompt``. Accepts one or more "
+"``NAME=PATH`` values."
+msgstr "在 ``--prompt`` 中加载 ``{NAME}`` 的文件文本。接受一个或多个 ``NAME=PATH`` 值。"
+
+#: ../../source/cli/query.rst:75
+msgid "``--completions``"
+msgstr "``--completions``"
+
+#: ../../source/cli/query.rst:77
+msgid "Use ``POST /v1/completions`` only."
+msgstr "仅使用 ``POST /v1/completions``\\ 。"
+
+#: ../../source/cli/query.rst:78
+msgid "``--chat-first``"
+msgstr "``--chat-first``"
+
+#: ../../source/cli/query.rst:80
+msgid "Try ``/v1/chat/completions`` first, then fall back to ``/v1/completions``."
+msgstr "首先尝试 ``/v1/chat/completions``\\ ，然后回退到 ``/v1/completions``\\ 。"
+
+#: ../../source/cli/query.rst:82
+msgid "``--format``"
+msgstr "``--format``"
+
+#: ../../source/cli/query.rst:84
+msgid "Output format: ``terminal`` (default) or ``json``."
+msgstr "输出格式：\\ ``terminal``\\ （默认）或\\ ``json``\\ 。"
+
+#: ../../source/cli/query.rst:85
+msgid "``--output PATH``"
+msgstr "``--output PATH``"
+
+#: ../../source/cli/query.rst:87
+msgid "Save metrics to a file (format follows ``--format``)."
+msgstr "将指标保存到文件中（格式遵循 ``--format``\\ ）。"
+
+#: ../../source/cli/query.rst:88
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/query.rst:90
+msgid "Suppress stdout output. Exit code only."
+msgstr "抑制标准输出。仅返回退出代码。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/quota.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/quota.po
new file mode 100644
index 0000000..2b330ce
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/quota.po
@@ -0,0 +1,239 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-15 11:17+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/quota.rst:2
+msgid "lmcache quota"
+msgstr "lmcache quota"
+
+#: ../../source/cli/quota.rst:4
+msgid ""
+"The ``lmcache quota`` command manages per-salt cache quotas on a running "
+"LMCache server. Quotas are soft limits: exceeding a quota triggers "
+"eviction on the next cycle (~1 s) rather than rejecting writes."
+msgstr "``lmcache quota`` 命令管理运行中的 LMCache 服务器上的每个 salt 的缓存配额。配额是软限制：超过配额会在下一个周期（约 1 秒）触发逐出，而不是拒绝写入。"
+
+#: ../../source/cli/quota.rst:29
+msgid "set"
+msgstr "设置"
+
+#: ../../source/cli/quota.rst:31
+msgid "Create or update a quota for a given ``cache_salt``."
+msgstr "为给定的 ``cache_salt`` 创建或更新配额。"
+
+#: ../../source/cli/quota.rst:37 ../../source/cli/quota.rst:87
+#: ../../source/cli/quota.rst:134 ../../source/cli/quota.rst:211
+msgid "**Example:**"
+msgstr "**示例：**"
+
+#: ../../source/cli/quota.rst:49 ../../source/cli/quota.rst:100
+#: ../../source/cli/quota.rst:178 ../../source/cli/quota.rst:222
+msgid "**Options:**"
+msgstr "**选项:**"
+
+#: ../../source/cli/quota.rst:55 ../../source/cli/quota.rst:106
+#: ../../source/cli/quota.rst:184 ../../source/cli/quota.rst:228
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/quota.rst:56 ../../source/cli/quota.rst:107
+#: ../../source/cli/quota.rst:185 ../../source/cli/quota.rst:229
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/cli/quota.rst:57 ../../source/cli/quota.rst:108
+#: ../../source/cli/quota.rst:186 ../../source/cli/quota.rst:230
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/quota.rst:58 ../../source/cli/quota.rst:109
+#: ../../source/cli/quota.rst:231
+msgid "``<salt>``"
+msgstr "``<salt>``"
+
+#: ../../source/cli/quota.rst:59 ../../source/cli/quota.rst:63
+#: ../../source/cli/quota.rst:110 ../../source/cli/quota.rst:232
+msgid "Yes"
+msgstr "是"
+
+#: ../../source/cli/quota.rst:60
+msgid ""
+"The ``cache_salt`` identifier. Use ``_default`` for anonymous (un-salted)"
+" traffic."
+msgstr "``cache_salt`` 标识符。对于匿名（未加盐）流量，请使用 ``_default``\\ 。"
+
+#: ../../source/cli/quota.rst:62
+msgid "``--limit-gb``"
+msgstr "``--limit-gb``"
+
+#: ../../source/cli/quota.rst:64
+msgid "Quota limit in gigabytes (non-negative float)."
+msgstr "以千兆字节为单位的配额限制（非负浮点数）。"
+
+#: ../../source/cli/quota.rst:65 ../../source/cli/quota.rst:112
+#: ../../source/cli/quota.rst:187 ../../source/cli/quota.rst:234
+msgid "``--url``"
+msgstr "``--url``"
+
+#: ../../source/cli/quota.rst:66 ../../source/cli/quota.rst:69
+#: ../../source/cli/quota.rst:72 ../../source/cli/quota.rst:75
+#: ../../source/cli/quota.rst:113 ../../source/cli/quota.rst:116
+#: ../../source/cli/quota.rst:119 ../../source/cli/quota.rst:122
+#: ../../source/cli/quota.rst:188 ../../source/cli/quota.rst:191
+#: ../../source/cli/quota.rst:194 ../../source/cli/quota.rst:197
+#: ../../source/cli/quota.rst:235 ../../source/cli/quota.rst:238
+#: ../../source/cli/quota.rst:241 ../../source/cli/quota.rst:244
+msgid "No"
+msgstr "不"
+
+#: ../../source/cli/quota.rst:67 ../../source/cli/quota.rst:114
+#: ../../source/cli/quota.rst:189 ../../source/cli/quota.rst:236
+msgid "LMCache HTTP server URL (default: ``http://localhost:8080``)."
+msgstr "LMCache HTTP 服务器 URL（默认：\\ ``http://localhost:8080``\\ ）。"
+
+#: ../../source/cli/quota.rst:68 ../../source/cli/quota.rst:115
+#: ../../source/cli/quota.rst:190 ../../source/cli/quota.rst:237
+msgid "``--format``"
+msgstr "``--format``"
+
+#: ../../source/cli/quota.rst:70 ../../source/cli/quota.rst:117
+#: ../../source/cli/quota.rst:192 ../../source/cli/quota.rst:239
+msgid "Output format: ``terminal`` (default) or ``json``."
+msgstr "输出格式：\\ ``terminal``\\ （默认）或\\ ``json``\\ 。"
+
+#: ../../source/cli/quota.rst:71 ../../source/cli/quota.rst:118
+#: ../../source/cli/quota.rst:193 ../../source/cli/quota.rst:240
+msgid "``--output``"
+msgstr "``--output``"
+
+#: ../../source/cli/quota.rst:73
+msgid "Save output to a file (uses the format chosen by ``--format``)."
+msgstr "将输出保存到文件中（使用 ``--format`` 选择的格式）。"
+
+#: ../../source/cli/quota.rst:74 ../../source/cli/quota.rst:121
+#: ../../source/cli/quota.rst:196 ../../source/cli/quota.rst:243
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/quota.rst:76
+msgid "Suppress stdout output. Exit code only."
+msgstr "抑制标准输出。仅返回退出代码。"
+
+#: ../../source/cli/quota.rst:79
+msgid "get"
+msgstr "获取"
+
+#: ../../source/cli/quota.rst:81
+msgid "Show the current quota limit and live usage for a specific ``cache_salt``."
+msgstr "显示特定 ``cache_salt`` 的当前配额限制和实时使用情况。"
+
+#: ../../source/cli/quota.rst:111 ../../source/cli/quota.rst:233
+msgid "The ``cache_salt`` identifier."
+msgstr "``cache_salt`` 标识符。"
+
+#: ../../source/cli/quota.rst:120 ../../source/cli/quota.rst:195
+#: ../../source/cli/quota.rst:242
+msgid "Save output to a file."
+msgstr "将输出保存到文件。"
+
+#: ../../source/cli/quota.rst:123 ../../source/cli/quota.rst:198
+#: ../../source/cli/quota.rst:245
+msgid "Suppress stdout output."
+msgstr "抑制标准输出。"
+
+#: ../../source/cli/quota.rst:126
+msgid "list"
+msgstr "列表"
+
+#: ../../source/cli/quota.rst:128
+msgid "List all registered quotas along with their current usage."
+msgstr "列出所有注册的配额及其当前使用情况。"
+
+#: ../../source/cli/quota.rst:151
+msgid "**JSON output:**"
+msgstr "**JSON 输出：**"
+
+#: ../../source/cli/quota.rst:201
+msgid "delete"
+msgstr "删除"
+
+#: ../../source/cli/quota.rst:203
+msgid ""
+"Remove a quota entry for a given ``cache_salt``. Any bytes still cached "
+"under this salt become over-budget on the next eviction cycle and will be"
+" evicted (effective limit drops to 0)."
+msgstr "删除给定 ``cache_salt`` 的配额条目。此盐下仍然缓存的任何字节将在下一个逐出周期中超出预算，并将被逐出（有效限制降至 0）。"
+
+#: ../../source/cli/quota.rst:248
+msgid "Exit Codes"
+msgstr "退出代码"
+
+#: ../../source/cli/quota.rst:254
+msgid "Code"
+msgstr "代码"
+
+#: ../../source/cli/quota.rst:255
+msgid "Meaning"
+msgstr "含义"
+
+#: ../../source/cli/quota.rst:256
+msgid "``0``"
+msgstr "``0``"
+
+#: ../../source/cli/quota.rst:257
+msgid "Success."
+msgstr "成功。"
+
+#: ../../source/cli/quota.rst:258
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/cli/quota.rst:259
+msgid "Error (connection failure, server error, bad arguments)."
+msgstr "错误（连接失败、服务器错误、参数错误）。"
+
+#: ../../source/cli/quota.rst:262
+msgid "The ``_default`` Salt"
+msgstr "``_default`` 盐"
+
+#: ../../source/cli/quota.rst:264
+msgid ""
+"The LMCache server uses an empty string (``\"\"``) as the ``cache_salt`` "
+"for anonymous / un-salted traffic. Since empty strings cannot appear in "
+"URL path parameters, the HTTP API (and this CLI) uses the sentinel "
+"``_default`` in its place."
+msgstr "LMCache 服务器使用空字符串 (``\"\"``) 作为匿名 / 未加盐流量的 ``cache_salt``\\ 。由于空字符串不能出现在 URL 路径参数中，HTTP API（以及此 CLI）使用哨兵 ``_default`` 代替。"
+
+#: ../../source/cli/quota.rst:278
+msgid "Common Patterns"
+msgstr "常见模式"
+
+#: ../../source/cli/quota.rst:280
+msgid "**Provision quotas for multiple tenants:**"
+msgstr "**为多个租户配置配额：**"
+
+#: ../../source/cli/quota.rst:288
+msgid "**Monitor usage in a script:**"
+msgstr "**在脚本中监控使用情况：**"
+
+#: ../../source/cli/quota.rst:296
+msgid "**Revoke access (evict all cached data for a salt):**"
+msgstr "**撤销访问（逐出所有缓存数据以便于一个盐）：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/server.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/server.po
new file mode 100644
index 0000000..6328c6d
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/server.po
@@ -0,0 +1,258 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/server.rst:2
+msgid "lmcache server"
+msgstr "lmcache server"
+
+#: ../../source/cli/server.rst:4
+msgid ""
+"The ``lmcache server`` command launches the standalone LMCache Multi-"
+"Process (MP) server, which exposes a ZMQ control plane and an HTTP "
+"frontend (status, healthcheck, cache-clear, checksum APIs). It is the "
+"server that ``lmcache describe``, ``lmcache ping kvcache``, ``lmcache "
+"kvcache``, and ``lmcache bench server`` talk to."
+msgstr "``lmcache server`` 命令启动独立的 LMCache 多进程 (MP) 服务器，该服务器暴露 ZMQ 控制平面和 HTTP 前端 (状态、健康检查、清除缓存、校验和 API)。这是 ``lmcache describe``\\ 、\\ ``lmcache ping kvcache``\\ 、\\ ``lmcache kvcache`` 和 ``lmcache bench server`` 进行交互的服务器。"
+
+#: ../../source/cli/server.rst:12
+msgid ""
+"This command requires the full ``lmcache`` installation with CUDA "
+"extensions. It is **not** available in the lightweight ``lmcache-cli`` "
+"package."
+msgstr "此命令需要完整的 ``lmcache`` 安装，并带有 CUDA 扩展。它在轻量级的 ``lmcache-cli`` 包中 **不可用**\\ 。"
+
+#: ../../source/cli/server.rst:21
+msgid "Quick start"
+msgstr "快速开始"
+
+#: ../../source/cli/server.rst:31
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/server.rst:33
+msgid ""
+"The server composes its arguments from several configuration modules — "
+"the multiprocess server, the storage manager (L1 / L2 adapters / "
+"eviction), the HTTP frontend, and the Prometheus / telemetry "
+"observability layer. The full, authoritative list is large and evolves "
+"with the runtime, so consult:"
+msgstr ""
+"服务器从多个配置模块组合其参数——多进程服务器、存储管理器（L1 / L2 适配器 / 逐出）、HTTP 前端以及 Prometheus / "
+"监控可观察性层。完整的权威列表很大，并随着运行时而变化，因此请参考："
+
+#: ../../source/cli/server.rst:42
+msgid "Commonly used flags include:"
+msgstr "常用的标志包括："
+
+#: ../../source/cli/server.rst:48
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/server.rst:49
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/server.rst:50
+msgid "``--host HOST``"
+msgstr "``--host HOST``"
+
+#: ../../source/cli/server.rst:51
+msgid "Bind address for the server."
+msgstr "服务器的绑定地址。"
+
+#: ../../source/cli/server.rst:52
+msgid "``--port PORT``"
+msgstr "``--port PORT``"
+
+#: ../../source/cli/server.rst:53
+msgid "ZMQ control-plane port."
+msgstr "ZMQ 控制平面端口。"
+
+#: ../../source/cli/server.rst:54
+msgid "``--chunk-size N``"
+msgstr "``--chunk-size N``"
+
+#: ../../source/cli/server.rst:55
+msgid "KV cache chunk size in tokens."
+msgstr "KV Cache 块大小（以 token 为单位）。"
+
+#: ../../source/cli/server.rst:56
+msgid "``--l1-size-gb GB``"
+msgstr "``--l1-size-gb GB``"
+
+#: ../../source/cli/server.rst:57
+msgid "L1 (CPU/DRAM) cache capacity in GB."
+msgstr "L1 (CPU/DRAM) 缓存容量（以 GB 为单位）。"
+
+#: ../../source/cli/server.rst:58
+msgid "``--eviction-policy POLICY``"
+msgstr "``--eviction-policy POLICY``"
+
+#: ../../source/cli/server.rst:59
+msgid "L1 eviction policy (e.g. ``LRU``)."
+msgstr "L1 逐出策略（例如 ``LRU``\\ ）。"
+
+#: ../../source/cli/server.rst:60
+msgid "``--eviction-trigger-watermark RATIO``"
+msgstr "``--eviction-trigger-watermark RATIO``"
+
+#: ../../source/cli/server.rst:61
+msgid "L1 fill ratio at which eviction begins."
+msgstr "开始逐出的 L1 填充比率。"
+
+#: ../../source/cli/server.rst:62
+msgid "``--eviction-ratio RATIO``"
+msgstr "``--eviction-ratio RATIO``"
+
+#: ../../source/cli/server.rst:63
+msgid "Fraction of L1 cleared per eviction cycle."
+msgstr "每个逐出周期清除的 L1 分数。"
+
+#: ../../source/cli/server.rst:64
+msgid "``--max-workers N``"
+msgstr "``--max-workers N``"
+
+#: ../../source/cli/server.rst:65
+msgid "Number of server worker processes."
+msgstr "服务器工作进程的数量。"
+
+#: ../../source/cli/server.rst:66
+msgid "``--coordinator-url URL``"
+msgstr "``--coordinator-url URL``"
+
+#: ../../source/cli/server.rst:67
+msgid ""
+"Register with an MP coordinator at this base URL (e.g. "
+"``http://coordinator:9300``). Opt-in; enables fleet registration. See "
+":doc:`/mp/coordinator`."
+msgstr "在此基础 URL（例如 ``http://coordinator:9300``\\ ）注册 MP 协调器。可选；启用车队注册。请参见 :doc:`/mp/coordinator`。"
+
+#: ../../source/cli/server.rst:70
+msgid "``--coordinator-advertise-ip IP``"
+msgstr "``--coordinator-advertise-ip IP``"
+
+#: ../../source/cli/server.rst:71
+msgid ""
+"IP the coordinator should reach this server at (defaults to the outbound "
+"IP)."
+msgstr "协调器应通过此服务器访问的 IP（默认为出站 IP）。"
+
+#: ../../source/cli/server.rst:73
+msgid "``--coordinator-heartbeat-interval SECONDS``"
+msgstr "``--coordinator-heartbeat-interval SECONDS``"
+
+#: ../../source/cli/server.rst:74
+msgid ""
+"Seconds between heartbeats (``> 0``, default ``5``). Keep well below the "
+"coordinator's instance timeout."
+msgstr "心跳之间的秒数（\\ ``> 0``\\ ，默认值为 ``5``\\ ）。应远低于协调器的实例超时。"
+
+#: ../../source/cli/server.rst:76
+msgid "``--coordinator-l2-event-reporting``"
+msgstr "``--coordinator-l2-event-reporting``"
+
+#: ../../source/cli/server.rst:77
+msgid ""
+"Enable reporting L2 store/lookup events to the coordinator for fleet-wide"
+" usage tracking and quota-based eviction."
+msgstr "启用向协调器上报 L2 存储/查找事件，用于全集群使用量跟踪及基于配额的逐出。"
+
+#: ../../source/cli/server.rst:79
+msgid "``--coordinator-l2-event-flush-interval SECONDS``"
+msgstr "``--coordinator-l2-event-flush-interval SECONDS``"
+
+#: ../../source/cli/server.rst:80
+msgid "Seconds between L2 event batch flushes (``> 0``, default ``1``)."
+msgstr "L2 事件批量刷新之间的秒数（\\ ``> 0``\\ ，默认 ``1``\\ ）。"
+
+#: ../../source/cli/server.rst:81
+msgid "``--p2p-advertise-url HOST:PORT``"
+msgstr "``--p2p-advertise-url HOST:PORT``"
+
+#: ../../source/cli/server.rst:82
+msgid ""
+"Enable P2P KV cache sharing and advertise this server's transfer-channel "
+"endpoint to peers (e.g. ``10.0.0.1:8500``). Setting it turns P2P on; it "
+"additionally requires ``--coordinator-url`` for peer discovery. See "
+":doc:`/mp/p2p`."
+msgstr "启用 P2P KV Cache 共享，并将此服务器的传输通道端点广告给对等方（例如 ``10.0.0.1:8500``）。设置它会开启 P2P；此外还需要 ``--coordinator-url`` 进行对等发现。请参见 :doc:`/mp/p2p`。"
+
+#: ../../source/cli/server.rst:86
+msgid "``--p2p-listen-url HOST:PORT``"
+msgstr "``--p2p-listen-url 主机:端口``"
+
+#: ../../source/cli/server.rst:87
+msgid ""
+"Address the transfer-channel server binds to. Defaults to ``--p2p-"
+"advertise-url``. Set it when the advertised address differs from the bind"
+" address (e.g. bind ``0.0.0.0`` while advertising a routable IP)."
+msgstr "传输通道服务器绑定的地址。默认为 ``--p2p-advertise-url``。当广告地址与绑定地址不同（例如，绑定 ``0.0.0.0`` 而广告一个可路由的 IP）时，请设置它。"
+
+#: ../../source/cli/server.rst:90
+msgid "``--p2p-lookup-timeout SECONDS``"
+msgstr "``--p2p-lookup-timeout SECONDS``"
+
+#: ../../source/cli/server.rst:91
+msgid "Deadline for a peer lookup before it counts as a miss (default ``30``)."
+msgstr "对等查找的截止时间，超过该时间将视为未命中（默认 ``30``）。"
+
+#: ../../source/cli/server.rst:92
+msgid "``--p2p-load-timeout SECONDS``"
+msgstr "``--p2p-load-timeout SECONDS``"
+
+#: ../../source/cli/server.rst:93
+msgid ""
+"Deadline for a peer KV read before it counts as a failure (default "
+"``30``)."
+msgstr "对等 KV 读取的截止时间，超过该时间将视为失败（默认 ``30``）。"
+
+#: ../../source/cli/server.rst:95
+msgid "``--p2p-transfer-engine ENGINE``"
+msgstr "``--p2p-transfer-engine ENGINE``"
+
+#: ../../source/cli/server.rst:96
+msgid "Transfer-channel implementation for P2P reads (default ``nixl``)."
+msgstr "P2P 读取的传输通道实现（默认 ``nixl``）。"
+
+#: ../../source/cli/server.rst:97
+#, python-brace-format
+msgid "``--trace-level {storage}``"
+msgstr "``--trace-level {storage}``"
+
+#: ../../source/cli/server.rst:98
+msgid "Enable storage-level trace recording (see :doc:`trace`)."
+msgstr "启用存储级别的追踪记录（请参见 :doc:`trace`）。"
+
+#: ../../source/cli/server.rst:99
+msgid "``--trace-output PATH``"
+msgstr "``--trace-output PATH``"
+
+#: ../../source/cli/server.rst:100
+msgid "Destination for recorded ``.lct`` trace files."
+msgstr "记录的 ``.lct`` 跟踪文件的目标。"
+
+#: ../../source/cli/server.rst:102
+msgid ""
+"L2 adapters, observability, and Prometheus exporters are configured "
+"through their own flag groups; see ``lmcache server --help`` for the "
+"complete set."
+msgstr "L2 适配器、可观察性和 Prometheus 导出器通过各自的标志组进行配置；有关完整的设置，请参见 ``lmcache server --help``\\ 。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/tool.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/tool.po
new file mode 100644
index 0000000..9c06669
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/tool.po
@@ -0,0 +1,95 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-01 10:55+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/tool.rst:2
+msgid "lmcache tool"
+msgstr "lmcache tool"
+
+#: ../../source/cli/tool.rst:4
+msgid ""
+"The ``lmcache tool`` command groups offline analysis utilities bundled "
+"with LMCache."
+msgstr "``lmcache tool`` 命令将与 LMCache 捆绑在一起的离线分析工具进行分组。"
+
+#: ../../source/cli/tool.rst:11
+msgid "Currently one tool is available: ``cache-simulator``."
+msgstr "目前可用的工具有一个：\\ ``cache-simulator``\\ 。"
+
+#: ../../source/cli/tool.rst:15
+msgid ""
+"``cache-simulator`` depends on the optional ``plot`` extras "
+"(``sortedcontainers`` / ``matplotlib``). If they are not installed, the "
+"sub-command is silently omitted from the CLI. Install the extras to "
+"enable it."
+msgstr "``cache-simulator`` 依赖于可选的 ``plot`` 附加组件（\\ ``sortedcontainers`` / ``matplotlib``\\ ）。如果它们未安装，子命令将会在 CLI 中静默省略。安装附加组件以启用它。"
+
+#: ../../source/cli/tool.rst:22
+msgid "cache-simulator"
+msgstr "cache-simulator"
+
+#: ../../source/cli/tool.rst:24
+msgid ""
+"Replay LMCache lookup-hash JSONL logs through an LRU cache to measure the"
+" KV-cache token hit rate. It has three actions:"
+msgstr "通过 LRU 缓存重放 LMCache 查找哈希 JSONL 日志，以测量 KV Cache 的令牌命中率。它有三个操作："
+
+#: ../../source/cli/tool.rst:35
+msgid "Action"
+msgstr "操作"
+
+#: ../../source/cli/tool.rst:36
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/tool.rst:37
+msgid "``simulate``"
+msgstr "``simulate``"
+
+#: ../../source/cli/tool.rst:38
+msgid ""
+"Replay logs at a fixed cache capacity; print a text report and save a "
+"7-panel statistics PNG."
+msgstr "在固定的缓存容量下重放日志；打印文本报告并保存 7 面板的统计 PNG。"
+
+#: ../../source/cli/tool.rst:40
+msgid "``sweep``"
+msgstr "``sweep``"
+
+#: ../../source/cli/tool.rst:41
+msgid ""
+"Sweep across a range of cache capacities and save a hit-rate vs. capacity"
+" PNG."
+msgstr "在一系列缓存容量中进行扫描，并保存命中率与容量的 PNG 图像。"
+
+#: ../../source/cli/tool.rst:43
+msgid "``gen-dataset``"
+msgstr "``gen-dataset``"
+
+#: ../../source/cli/tool.rst:44
+msgid ""
+"Generate a ``vllm bench serve`` custom dataset (JSONL) from lookup-hash "
+"JSONL logs, preserving prefix-sharing structure."
+msgstr "从查找哈希 JSONL 日志生成一个 ``vllm bench serve`` 自定义数据集 (JSONL)，保留前缀共享结构。"
+
+#: ../../source/cli/tool.rst:47
+msgid "Each action has its own flags. Run the built-in help for the full list:"
+msgstr "每个操作都有其自己的标志。运行内置帮助以获取完整列表："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/cli/trace.po b/docs/source/locale/zh_CN/LC_MESSAGES/cli/trace.po
new file mode 100644
index 0000000..27aba68
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/cli/trace.po
@@ -0,0 +1,170 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-01 10:55+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/cli/trace.rst:2
+msgid "lmcache trace"
+msgstr "lmcache trace"
+
+#: ../../source/cli/trace.rst:4
+msgid ""
+"The ``lmcache trace`` command inspects and replays LMCache storage-level "
+"trace files (``.lct``). It has two sub-commands:"
+msgstr "``lmcache trace`` 命令用于检查和重放 LMCache 存储级别的跟踪文件 (``.lct``)。它有两个子命令："
+
+#: ../../source/cli/trace.rst:13
+msgid ""
+"``lmcache trace`` needs the full ``lmcache`` package (StorageManager, "
+"trace codecs, ``TraceReader``). It is not available in the lightweight "
+"``lmcache-cli`` install and exits with status ``2`` if those modules are "
+"missing."
+msgstr "``lmcache trace`` 需要完整的 ``lmcache`` 包（StorageManager、trace 编解码器、\\ ``TraceReader``\\ ）。在轻量级的 ``lmcache-cli`` 安装中不可用，如果缺少这些模块，则会以状态 ``2`` 退出。"
+
+#: ../../source/cli/trace.rst:18
+msgid ""
+"Trace *capture* is not a ``trace`` sub-command — recording is bound to a "
+"live server via ``lmcache server --trace-level storage [--trace-output "
+"...]`` (see :doc:`server`)."
+msgstr "Trace 捕获不是 ``trace`` 子命令 — 录制绑定到通过 ``lmcache server --trace-level storage [--trace-output ...]`` 的实时服务器（参见 :doc:`server`）。"
+
+#: ../../source/cli/trace.rst:24
+msgid "info"
+msgstr "信息"
+
+#: ../../source/cli/trace.rst:26
+msgid ""
+"Print a one-screen summary of a trace file: header metadata plus per-"
+"qualname record counts."
+msgstr "打印跟踪文件的一屏摘要：头部元数据加上每个 qualname 的记录计数。"
+
+#: ../../source/cli/trace.rst:46
+msgid ""
+"The only argument is the positional ``FILE`` (path to a ``.lct`` trace "
+"file)."
+msgstr "唯一的参数是位置参数 ``FILE``\\ （指向 ``.lct`` 跟踪文件的路径）。"
+
+#: ../../source/cli/trace.rst:50
+msgid "replay"
+msgstr "重放"
+
+#: ../../source/cli/trace.rst:52
+msgid ""
+"Reissue every recorded call against a fresh ``StorageManager``, honoring "
+"the recorded inter-call timings."
+msgstr "对新创建的 ``StorageManager`` 重新发出每个记录的调用，遵循记录的调用间隔时间。"
+
+#: ../../source/cli/trace.rst:60
+msgid ""
+"``replay`` accepts the standard storage-manager configuration flags "
+"(``--l1-size-gb``, ``--eviction-policy``, ``--l2-...``); see ``lmcache "
+"server --help`` for the full list. The replay-side config may differ from"
+" the config recorded in the trace, which can legitimately cause retrieve "
+"misses."
+msgstr "``replay`` 接受标准的存储管理器配置标志（\\ ``--l1-size-gb``, ``--eviction-policy``, ``--l2-...``\\ ）；有关完整列表，请参见 ``lmcache server --help``\\ 。重放侧的配置可能与记录在追踪中的配置不同，这可能会导致合法的查找未命中。"
+
+#: ../../source/cli/trace.rst:68
+msgid ""
+"A replay environment mismatch may cause retrieve misses. Replay uses the "
+"replay-side StorageManager config (which may differ from the recorded "
+"config), runs on a host whose performance may differ from the recording "
+"host, and StorageManager reads/writes are async. Treat retrieve-miss "
+"counts as a signal about the replay environment, not a defect in the "
+"trace."
+msgstr "重放环境不匹配可能导致查找未命中。重放使用重放端的 StorageManager 配置（可能与记录的配置不同），在性能可能与记录主机不同的主机上运行，并且 StorageManager 的读/写是异步的。将查找未命中计数视为重放环境的信号，而不是记录中的缺陷。"
+
+#: ../../source/cli/trace.rst:75
+msgid "Options"
+msgstr "选项"
+
+#: ../../source/cli/trace.rst:81
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/cli/trace.rst:82
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/cli/trace.rst:83
+msgid "``FILE``"
+msgstr "``FILE``"
+
+#: ../../source/cli/trace.rst:84
+msgid "Path to a ``.lct`` trace file (positional, required)."
+msgstr "```.lct``` 跟踪文件的路径（位置参数，必填）。"
+
+#: ../../source/cli/trace.rst:85
+msgid "``--verbose``"
+msgstr "``--verbose``"
+
+#: ../../source/cli/trace.rst:86
+msgid "Print one line per replayed record."
+msgstr "每个重放记录打印一行。"
+
+#: ../../source/cli/trace.rst:87
+msgid "``--jsonl-out PATH``"
+msgstr "``--jsonl-out PATH``"
+
+#: ../../source/cli/trace.rst:88
+msgid ""
+"Write one JSON object per replayed record to ``PATH`` (qualname, "
+"latency_ms, failed)."
+msgstr "将每个重放记录写入一个 JSON 对象到 ``PATH``\\ （qualname，延迟_ms，失败）。"
+
+#: ../../source/cli/trace.rst:90
+msgid "``--output-dir DIR``"
+msgstr "``--output-dir DIR``"
+
+#: ../../source/cli/trace.rst:91
+msgid ""
+"Directory for aggregated CSV / JSON summary output (default: current "
+"directory)."
+msgstr "聚合的 CSV / JSON 摘要输出目录（默认：当前目录）。"
+
+#: ../../source/cli/trace.rst:93
+msgid "``--no-csv``"
+msgstr "``--no-csv``"
+
+#: ../../source/cli/trace.rst:94
+msgid "Skip the aggregated CSV summary export."
+msgstr "跳过聚合的 CSV 摘要导出。"
+
+#: ../../source/cli/trace.rst:95
+msgid "``--json``"
+msgstr "``--json``"
+
+#: ../../source/cli/trace.rst:96
+msgid "Also export an aggregated JSON summary."
+msgstr "还可以导出一个汇总的 JSON。"
+
+#: ../../source/cli/trace.rst:97
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/cli/trace.rst:98
+msgid "Suppress the terminal metrics table (files are still written)."
+msgstr "抑制终端指标表（文件仍然会被写入）。"
+
+#: ../../source/cli/trace.rst:100
+msgid ""
+"The terminal summary reports overall replay stats (records replayed / "
+"skipped / failed, duration, config-digest match) and per-op latency "
+"percentiles. ``replay`` exits with status ``1`` if any record failed."
+msgstr "终端摘要报告整体重放统计信息（重放/跳过/失败的记录、持续时间、配置摘要匹配）和每个操作的延迟百分位数。如果任何记录失败，\\ ``replay`` 将以状态 ``1`` 退出。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/community/blogs.po b/docs/source/locale/zh_CN/LC_MESSAGES/community/blogs.po
new file mode 100644
index 0000000..3ac742a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/community/blogs.po
@@ -0,0 +1,36 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/community/blogs.rst:2
+msgid "Blogs"
+msgstr "博客"
+
+#: ../../source/community/blogs.rst:4
+msgid ""
+"LMCache is a community-driven open-source project and we publish regular "
+"blog posts to share updates, performance comparison and new features. You"
+" can find the latest blog posts below:"
+msgstr "LMCache 是一个由社区驱动的开源项目，我们定期发布博客文章以分享更新、性能比较和新功能。您可以在下面找到最新的博客文章："
+
+#: ../../source/community/blogs.rst:7
+msgid "`LMCache blogs <https://blog.lmcache.ai/>`_"
+msgstr "`LMCache blogs <https://blog.lmcache.ai/>`_"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/community/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/community/index.po
new file mode 100644
index 0000000..c021999
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/community/index.po
@@ -0,0 +1,31 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/community/index.rst:2
+msgid "Community"
+msgstr "社区"
+
+#: ../../source/community/index.rst:4
+msgid ""
+"Get involved with the LMCache community -- join our meetings and follow "
+"the blog."
+msgstr "欢迎参与 LMCache 社区：加入社区会议，关注最新博客动态。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/community/meetings.po b/docs/source/locale/zh_CN/LC_MESSAGES/community/meetings.po
new file mode 100644
index 0000000..3e522dd
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/community/meetings.po
@@ -0,0 +1,143 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-08 10:45+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/community/meetings.rst:2
+msgid "Community meetings"
+msgstr "社区会议"
+
+#: ../../source/community/meetings.rst:4
+msgid ""
+"LMCache hosts regular community meetings to discuss updates, address new "
+"feature requests, and feedback from the community. If you are interested "
+"in contributing to the LMCache projects (core LMCache or Production "
+"Stack), we encourage you to join the meetings. We also host a monthly "
+"\"Office Hour\" on select topics."
+msgstr ""
+"LMCache 定期举办社区会议，以讨论更新、处理新功能请求以及收集社区反馈。如果您有兴趣为 LMCache 项目（核心 LMCache "
+"或生产堆栈）做出贡献，我们鼓励您参加会议。我们还会就特定主题举办每月的“办公时间”。"
+
+#: ../../source/community/meetings.rst:10
+msgid "Meeting schedule"
+msgstr "会议日程"
+
+#: ../../source/community/meetings.rst:11
+msgid "The LMCache community meetings held separately for each project:"
+msgstr "LMCache 社区会议为每个项目单独举行："
+
+#: ../../source/community/meetings.rst:13
+msgid "LMCache - `Github <https://github.com/LMCache/LMCache/>`__"
+msgstr "LMCache - `Github <https://github.com/LMCache/LMCache/>`__"
+
+#: ../../source/community/meetings.rst:14
+msgid ""
+"Production Stack - `Github <https://github.com/vllm-project/production-"
+"stack>`__"
+msgstr "生产栈 - `Github <https://github.com/vllm-project/production-stack>`__"
+
+#: ../../source/community/meetings.rst:17
+msgid "LMCache Project"
+msgstr "LMCache 项目"
+
+#: ../../source/community/meetings.rst:19
+msgid ""
+"The LMCache community meeting is held bi-weekly on **Tuesdays** at "
+"**9:00-9:30 AM PT**."
+msgstr "LMCache 社区会议每两周在 **星期二** 的 **上午 9:00-9:30（太平洋时间）** 举行。"
+
+#: ../../source/community/meetings.rst:21
+msgid "Please find the meeting invite link below:"
+msgstr "请在下面找到会议邀请链接："
+
+#: ../../source/community/meetings.rst:23
+#: ../../source/community/meetings.rst:33
+msgid ""
+"**Meeting link**: `Zoom link "
+"<https://uchicago.zoom.us/j/6603596916?pwd=Z1E5MDRWUSt2am5XbEt4dTFkNGx6QT09>`_"
+msgstr ""
+"**会议链接**: `Zoom 链接 "
+"<https://uchicago.zoom.us/j/6603596916?pwd=Z1E5MDRWUSt2am5XbEt4dTFkNGx6QT09>`_"
+
+#: ../../source/community/meetings.rst:24
+msgid ""
+"**Calendar Invite**: `Google Calendar "
+"<https://drive.usercontent.google.com/u/0/uc?id=15Xz8-LtpBQ5QgR7KrorOOyfuohCFQmwn&export=download>`__"
+msgstr ""
+"**日历邀请**: `Google 日历 "
+"<https://drive.usercontent.google.com/u/0/uc?id=15Xz8-LtpBQ5QgR7KrorOOyfuohCFQmwn&export=download>`__"
+
+#: ../../source/community/meetings.rst:25
+msgid ""
+"**Slack Channel**: `#lmcache "
+"<https://join.slack.com/t/lmcacheworkspace/shared_invite/zt-"
+"3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA>`_"
+msgstr "**Slack 频道**: `#lmcache <https://join.slack.com/t/lmcacheworkspace/shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA>`_"
+
+#: ../../source/community/meetings.rst:28
+msgid "vLLM Production Stack Project"
+msgstr "vLLM 生产栈项目"
+
+#: ../../source/community/meetings.rst:30
+msgid ""
+"The Production Stack community meeting is held bi-weekly on **Tuesdays** "
+"at **5:30-6:00 PM PT**. Please find the meeting invite link below:"
+msgstr "生产堆栈社区会议每两周在\\ **星期二**\\ 的\\ **下午5:30-6:00（太平洋时间）**\\ 举行。请在下面找到会议邀请链接："
+
+#: ../../source/community/meetings.rst:34
+msgid ""
+"**Calendar Invite**: `Google Calendar "
+"<https://drive.usercontent.google.com/u/0/uc?id=1I3WuivUVAq1vZ2XSW4rmqgD5c0bQcxE0&export=download>`__"
+msgstr "**日历邀请**\\ ： `Google 日历 <https://drive.usercontent.google.com/u/0/uc?id=1I3WuivUVAq1vZ2XSW4rmqgD5c0bQcxE0&export=download>`__"
+
+#: ../../source/community/meetings.rst:35
+msgid ""
+"**Slack Channel**: `#production-stack <https://vllm-"
+"dev.slack.com/archives/C089SMEAKRA>`_"
+msgstr ""
+"**Slack 频道**: `#production-stack <https://vllm-"
+"dev.slack.com/archives/C089SMEAKRA>`_"
+
+#: ../../source/community/meetings.rst:39
+msgid ""
+"The Zoom meeting link is the same for both LMCache and Production Stack "
+"community meetings. Meeting notes are available here: `Meeting notes "
+"<https://docs.google.com/document/d/1vX0g2q3j4x5m7J6z8Q9Gk4Z5l7f3K8h0nqYwW1a2c4o/edit?usp=sharing>`_."
+msgstr ""
+"Zoom 会议链接对于 LMCache 和 Production Stack 社区会议是相同的。会议记录可以在这里查看：`会议记录 "
+"<https://docs.google.com/document/d/1vX0g2q3j4x5m7J6z8Q9Gk4Z5l7f3K8h0nqYwW1a2c4o/edit?usp=sharing>`_。"
+
+#: ../../source/community/meetings.rst:43
+msgid "LMCache Office Hours"
+msgstr "LMCache 办公时间"
+
+#: ../../source/community/meetings.rst:45
+msgid "Held monthly on the second Wednesday of the month at 2PM ET, 11AM PT."
+msgstr "每月在东部时间下午2点，太平洋时间上午11点的第二个星期三举行。"
+
+#: ../../source/community/meetings.rst:47
+msgid "Topic announced on the LMCache #office-hour Slack channel"
+msgstr "在 LMCache #office-hour Slack 频道上宣布主题"
+
+#: ../../source/community/meetings.rst:48
+msgid ""
+"Request a calendar invite via `this form <https://lmcache-"
+"officehours.zapier.app/>`_"
+msgstr "通过 `此表单 <https://lmcache-officehours.zapier.app/>`_ 请求日历邀请"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/controller/freeze_mode.po b/docs/source/locale/zh_CN/LC_MESSAGES/controller/freeze_mode.po
new file mode 100644
index 0000000..5f1d433
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/controller/freeze_mode.po
@@ -0,0 +1,203 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/controller/freeze_mode.rst:2
+msgid "Freeze Mode"
+msgstr "冻结模式"
+
+#: ../../source/controller/freeze_mode.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/coordinator`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/coordinator`。"
+
+#: ../../source/controller/freeze_mode.rst:10
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/controller/freeze_mode.rst:12
+msgid ""
+"Freeze Mode is a safety mechanism in LMCache Controller designed to "
+"prevent data inconsistency and potential data loss during critical system"
+" events. When the controller detects severe state inconsistencies or is "
+"undergoing restart/recovery, it can activate Freeze Mode to temporarily "
+"restrict certain operations."
+msgstr ""
+"冻结模式是 LMCache "
+"控制器中的一种安全机制，旨在防止在关键系统事件期间出现数据不一致和潜在的数据丢失。当控制器检测到严重的状态不一致或正在进行重启/恢复时，它可以激活冻结模式，以暂时限制某些操作。"
+
+#: ../../source/controller/freeze_mode.rst:15
+msgid "Motivation"
+msgstr "动机"
+
+#: ../../source/controller/freeze_mode.rst:17
+msgid "The primary motivations for Freeze Mode are:"
+msgstr "冻结模式的主要动机包括："
+
+#: ../../source/controller/freeze_mode.rst:19
+msgid ""
+"**Controller Failure Recovery** - When the controller crashes and "
+"restarts, it may need to perform a full synchronization with workers - "
+"During this sync period, the system state may be incomplete or "
+"inconsistent"
+msgstr "**控制器故障恢复** - 当控制器崩溃并重启时，它可能需要与工作节点进行完全同步 - 在此同步期间，系统状态可能不完整或不一致"
+
+#: ../../source/controller/freeze_mode.rst:23
+msgid ""
+"**State Inconsistency Detection** - When severe state mismatches are "
+"detected between the controller and workers - This could happen due to "
+"network issues, worker failures, or unexpected system behavior"
+msgstr "**状态不一致检测** - 当检测到控制器与工作节点之间存在严重的状态不匹配时 - 这可能是由于网络问题、工作节点故障或意外的系统行为导致的"
+
+#: ../../source/controller/freeze_mode.rst:27
+msgid ""
+"**Full Synchronization Safety** - During full sync operations triggered "
+"by the above events - To prevent operations that could cause eviction or "
+"admission events while state is being rebuilt"
+msgstr "**完全同步安全** - 在上述事件触发的完全同步操作期间 - 为了防止在状态重建时可能导致逐出或接纳事件的操作"
+
+#: ../../source/controller/freeze_mode.rst:32
+msgid "Purpose"
+msgstr "目的"
+
+#: ../../source/controller/freeze_mode.rst:34
+msgid "When Freeze Mode is activated:"
+msgstr "当冻结模式被激活时："
+
+#: ../../source/controller/freeze_mode.rst:36
+msgid "**All operations that could generate evict/admit events are disabled**"
+msgstr "**所有可能生成逐出/接纳事件的操作均被禁用**"
+
+#: ../../source/controller/freeze_mode.rst:37
+msgid "Only read operations and basic queries are allowed"
+msgstr "仅允许读取操作和基本查询"
+
+#: ../../source/controller/freeze_mode.rst:38
+msgid ""
+"The system essentially enters a \"read-only\" state for cache management "
+"operations"
+msgstr "系统本质上进入了一个“只读”状态，以进行缓存管理操作。"
+
+#: ../../source/controller/freeze_mode.rst:39
+msgid "This prevents data corruption or loss during the recovery/sync process"
+msgstr "这可以防止在恢复/同步过程中数据损坏或丢失。"
+
+#: ../../source/controller/freeze_mode.rst:42
+msgid "Current Implementation Status"
+msgstr "当前实现状态"
+
+#: ../../source/controller/freeze_mode.rst:44
+msgid "**Currently Implemented:**"
+msgstr "**当前实现：**"
+
+#: ../../source/controller/freeze_mode.rst:46
+msgid ""
+"**Freeze Mode Mechanism** - StorageManager supports freeze mode - When "
+"frozen, only LocalCPUBackend is used for retrieval operations - Other "
+"storage backends are temporarily excluded from active use"
+msgstr ""
+"**冻结模式机制** - StorageManager 支持冻结模式 - 当处于冻结状态时，仅使用 LocalCPUBackend 进行检索操作 "
+"- 其他存储后端暂时不参与活动使用"
+
+#: ../../source/controller/freeze_mode.rst:51
+msgid ""
+"**API Endpoints** - Freeze mode can be toggled via controller API - "
+"Status can be queried to check if system is in freeze mode"
+msgstr "**API 端点** - 冻结模式可以通过控制器 API 切换 - 可以查询状态以检查系统是否处于冻结模式"
+
+#: ../../source/controller/freeze_mode.rst:55
+msgid "**Not Yet Implemented:**"
+msgstr "**尚未实现：**"
+
+#: ../../source/controller/freeze_mode.rst:57
+msgid ""
+"**Automatic Triggering** - Controller does not yet automatically trigger "
+"freeze mode - Manual activation via API is currently required"
+msgstr "**自动触发** - 控制器尚未自动触发冻结模式 - 目前需要通过 API 手动激活"
+
+#: ../../source/controller/freeze_mode.rst:61
+msgid ""
+"**Full Sync Integration** - Full synchronization process that would "
+"trigger freeze mode is not implemented - Controller restart detection and"
+" automatic freeze mode activation not yet developed"
+msgstr "**完全同步集成** - 触发冻结模式的完整同步过程尚未实现 - 控制器重启检测和自动冻结模式激活尚未开发"
+
+#: ../../source/controller/freeze_mode.rst:65
+msgid ""
+"**Recovery Completion** - Automatic unfreeze after sync completion not "
+"yet implemented - Manual intervention currently required to exit freeze "
+"mode"
+msgstr "**恢复完成** - 同步完成后自动解冻尚未实现 - 目前需要手动干预以退出冻结模式"
+
+#: ../../source/controller/freeze_mode.rst:70
+msgid "Usage"
+msgstr "使用方法"
+
+#: ../../source/controller/freeze_mode.rst:72
+msgid "**Manual Activation/Deactivation:**"
+msgstr "**手动激活/停用：**"
+
+#: ../../source/controller/freeze_mode.rst:74
+msgid "Freeze mode can be manually controlled through the Controller API:"
+msgstr "冻结模式可以通过控制器 API 手动控制："
+
+#: ../../source/controller/freeze_mode.rst:87
+msgid "**System Behavior in Freeze Mode:**"
+msgstr "**冻结模式下的系统行为：**"
+
+#: ../../source/controller/freeze_mode.rst:89
+msgid "Cache retrieval operations continue to work"
+msgstr "缓存检索操作继续正常工作"
+
+#: ../../source/controller/freeze_mode.rst:90
+msgid "Only LocalCPUBackend is used for all retrievals"
+msgstr "仅使用 LocalCPUBackend 进行所有检索。"
+
+#: ../../source/controller/freeze_mode.rst:91
+msgid "Cache admission/eviction operations are blocked"
+msgstr "缓存接纳/逐出操作被阻止"
+
+#: ../../source/controller/freeze_mode.rst:92
+msgid "Write operations to storage backends are prevented"
+msgstr "对存储后端的写入操作被阻止"
+
+#: ../../source/controller/freeze_mode.rst:93
+msgid "Monitoring and health checks continue normally"
+msgstr "监控和健康检查正常进行"
+
+#: ../../source/controller/freeze_mode.rst:96
+msgid "Related Documentation"
+msgstr "相关文档"
+
+#: ../../source/controller/freeze_mode.rst:98
+msgid ":doc:`index` - Controller WebUI overview"
+msgstr ":doc:`index` - 控制器 WebUI 概述"
+
+#: ../../source/controller/freeze_mode.rst:99
+msgid ":doc:`../api_reference/configurations` - API and configuration reference"
+msgstr ":doc:`../api_reference/configurations` - API 和配置参考"
+
+#: ../../source/controller/freeze_mode.rst:100
+msgid ":doc:`../storage_backend/index` - Storage backend architecture"
+msgstr ":doc:`../storage_backend/index` - 存储后端架构"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/controller/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/controller/index.po
new file mode 100644
index 0000000..175737f
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/controller/index.po
@@ -0,0 +1,126 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/controller/index.rst:2
+msgid "Controller WebUI"
+msgstr "控制器 WebUI"
+
+#: ../../source/controller/index.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/coordinator`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/coordinator`。"
+
+#: ../../source/controller/index.rst:10
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/controller/index.rst:12
+msgid ""
+"The LMCache Controller provides a web-based dashboard for monitoring your"
+" LMCache instances. This web interface allows you to monitor system "
+"status, instances, workers, and performance metrics."
+msgstr "LMCache 控制器提供了一个基于网页的仪表板，用于监控您的 LMCache 实例。该网页界面允许您监控系统状态、实例、工作进程和性能指标。"
+
+#: ../../source/controller/index.rst:15
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/controller/index.rst:17
+msgid ""
+"To enable the Controller WebUI, start your LMCache instance with the "
+"following command:"
+msgstr "要启用 Controller WebUI，请使用以下命令启动您的 LMCache 实例："
+
+#: ../../source/controller/index.rst:28
+msgid "After starting the controller, access the WebUI at:"
+msgstr "启动控制器后，访问 WebUI："
+
+#: ../../source/controller/index.rst:35
+msgid "Configuration Options"
+msgstr "配置选项"
+
+#: ../../source/controller/index.rst:37
+msgid "``--host``: Bind address for the API server (default: 0.0.0.0)"
+msgstr "``--host``: API 服务器的绑定地址（默认: 0.0.0.0）"
+
+#: ../../source/controller/index.rst:38
+msgid "``--port``: Port for the API server (default: 9000)"
+msgstr "``--port``: API 服务器的端口（默认: 9000）"
+
+#: ../../source/controller/index.rst:39
+msgid "``--monitor-ports``: ZMQ ports for controller communication"
+msgstr "``--monitor-ports``: 控制器通信的 ZMQ 端口"
+
+#: ../../source/controller/index.rst:40
+msgid "``--lmcache-worker-timeout``: Worker timeout in seconds"
+msgstr "``--lmcache-worker-timeout``: 工作线程超时时间（秒）"
+
+#: ../../source/controller/index.rst:41
+msgid "``--health-check-interval``: Health check interval in seconds"
+msgstr "``--health-check-interval``: 健康检查间隔（秒）"
+
+#: ../../source/controller/index.rst:44
+msgid "Dashboard Features"
+msgstr "仪表板功能"
+
+#: ../../source/controller/index.rst:46
+msgid "The Controller Dashboard provides:"
+msgstr "控制器仪表板提供："
+
+#: ../../source/controller/index.rst:48
+msgid "System overview and health monitoring"
+msgstr "系统概览和健康监控"
+
+#: ../../source/controller/index.rst:49
+msgid "Instance and worker management"
+msgstr "实例和工作者管理"
+
+#: ../../source/controller/index.rst:50
+msgid "Performance metrics"
+msgstr "性能指标"
+
+#: ../../source/controller/index.rst:51
+msgid "Thread information"
+msgstr "线程信息"
+
+#: ../../source/controller/index.rst:52
+msgid "Environment variables inspection"
+msgstr "环境变量检查"
+
+#: ../../source/controller/index.rst:55
+msgid "Related Documentation"
+msgstr "相关文档"
+
+#: ../../source/controller/index.rst:57
+msgid ":doc:`../api_reference/configurations` - Complete configuration reference"
+msgstr ":doc:`../api_reference/configurations` - 完整的配置参考"
+
+#: ../../source/controller/index.rst:58
+msgid ":doc:`../kv_cache_management/index` - KV cache management guide"
+msgstr ":doc:`../kv_cache_management/index` - KV Cache 管理指南"
+
+#: ../../source/controller/index.rst:59
+msgid ":doc:`freeze_mode` - Freeze Mode safety mechanism guide"
+msgstr ":doc:`freeze_mode` - 冻结模式安全机制指南"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/architecture.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/architecture.po
new file mode 100644
index 0000000..0461323
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/architecture.po
@@ -0,0 +1,260 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/architecture.rst:2
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/developer_guide/architecture.rst:5
+msgid "High-Level System Architecture"
+msgstr "高层系统架构"
+
+#: ../../source/developer_guide/architecture.rst:8
+msgid ""
+"LMCache extends an LLM inference engine (e.g., vLLM) with a multi-tier KV"
+" cache storage system spanning GPU memory, CPU memory, and disk/remote "
+"backends. The diagram below illustrates how KV cache blocks move across "
+"these layers."
+msgstr "LMCache 扩展了一个 LLM 推理引擎（例如，vLLM），并配备了一个跨越显存、CPU 内存和磁盘/远程后端的多层 KV Cache 存储系统。下面的图示说明了 KV Cache 块如何在这些层之间移动。"
+
+#: ../../source/developer_guide/architecture.rst:10
+msgid "**Multi-Tier Storage Architecture**"
+msgstr "**多层存储架构**"
+
+#: ../../source/developer_guide/architecture.rst:12
+msgid ""
+"LMCache implements a hierarchical storage system with three distinct "
+"tiers:"
+msgstr "LMCache 实现了一个具有三个不同层次的分层存储系统："
+
+#: ../../source/developer_guide/architecture.rst:14
+msgid ""
+"**GPU Memory**: Holds the active working set of KV caches that are "
+"currently being used by the model"
+msgstr "**显存**\\ ：保存当前模型使用的 KV Cache 的活动工作集"
+
+#: ../../source/developer_guide/architecture.rst:15
+msgid ""
+"**CPU DRAM**: Acts as a \"hot cache\" for recently used KV chunks, using "
+"pinned memory for efficient GPU-CPU transfers"
+msgstr "**CPU DRAM**: 作为最近使用的 KV 块的“热缓存”，使用固定内存以实现高效的 GPU-CPU 传输"
+
+#: ../../source/developer_guide/architecture.rst:16
+msgid ""
+"**Local storage (e.g., local disk, NVMe GDS)**: Provides a large tier for"
+" local KV caching (e.g. for long documents)"
+msgstr "**本地存储（例如，本地磁盘、NVMe GDS）**\\ ：为本地 KV 缓存提供了一个大容量层（例如，用于长文档）。"
+
+#: ../../source/developer_guide/architecture.rst:17
+msgid ""
+"**Remote storage (e.g., Redis, Mooncake, InfiniStore)**: Persistent "
+"storage for KV caches. Reliable but not as performant as previous tiers."
+msgstr "**远程存储（例如，Redis、Mooncake、InfiniStore）**\\ ：KV 缓存的持久存储。可靠，但性能不如前面的层。"
+
+#: ../../source/developer_guide/architecture.rst:19
+msgid "**Data Flow and Operations**"
+msgstr "**数据流和操作**"
+
+#: ../../source/developer_guide/architecture.rst:21
+msgid ""
+"When the model generates new key-value (KV) cache chunks on the GPU, "
+"LMCache can:"
+msgstr "当模型在 GPU 上生成新的键值 (KV) 缓存块时，LMCache 可以："
+
+#: ../../source/developer_guide/architecture.rst:23
+msgid ""
+"**Offload overflow KV caches** from GPU to CPU DRAM, freeing precious GPU"
+" memory"
+msgstr "**将溢出的 KV 缓存** 从 GPU 卸载到 CPU DRAM，释放宝贵的显存"
+
+#: ../../source/developer_guide/architecture.rst:24
+msgid ""
+"**Asynchronously write** KV caches from CPU to disk or remote storage "
+"using LRU eviction policies"
+msgstr "**异步写入** KV Cache 从 CPU 到磁盘或远程存储，使用 LRU 逐出策略"
+
+#: ../../source/developer_guide/architecture.rst:25
+msgid ""
+"**Prefetch hot KV caches** from disk/remote storage back to CPU when "
+"needed"
+msgstr "**按需预取热 KV 缓存** 从磁盘/远程存储回到 CPU。"
+
+#: ../../source/developer_guide/architecture.rst:26
+msgid "**On-demand reuse** of cached segments by moving them from CPU back to GPU"
+msgstr "**按需重用** 缓存段，通过将它们从 CPU 移动回 GPU"
+
+#: ../../source/developer_guide/architecture.rst:28
+msgid ""
+"This architecture enables LMCache to significantly reduce prefill delays "
+"and GPU memory pressure while maintaining high performance through "
+"intelligent cache management."
+msgstr "这种架构使 LMCache 能够显著减少 Prefill 延迟和显存压力，同时通过智能缓存管理保持高性能。"
+
+#: ../../source/developer_guide/architecture.rst:49
+msgid "Two modes"
+msgstr "两种模式"
+
+#: ../../source/developer_guide/architecture.rst:51
+msgid "**Storage Mode (KV cache offloading)**"
+msgstr "**存储模式 (KV Cache 卸载)**"
+
+#: ../../source/developer_guide/architecture.rst:52
+msgid ""
+"LMCache acts as a persistent KV store, optimizing for high reuse across "
+"queries or sessions. It offloads infrequently used KV blocks from GPU "
+"memory and persists popular caches across sessions, boosting cache hit "
+"rates for \"hot\" content. KV caches survive beyond single inference "
+"calls and even process restarts when backed by disk or external storage."
+msgstr "LMCache 充当持久化的 KV 存储，优化查询或会话之间的高重用性。它将不常用的 KV 块从显存中卸载，并在会话之间持久化热门缓存，提高“热”内容的缓存命中率。KV 缓存超越单次推理调用，甚至在磁盘或外部存储支持下，能够在进程重启后继续存在。"
+
+#: ../../source/developer_guide/architecture.rst:73
+msgid "**Transport Mode (Prefill-decode disaggregation)**"
+msgstr "**传输模式（Prefill-解码分离）**"
+
+#: ../../source/developer_guide/architecture.rst:74
+msgid ""
+"Focuses on accelerating distributed inference by routing KV cache data "
+"between nodes in real-time. Enables prefill-decode disaggregation where "
+"one server computes KV for prompts and delivers them to another server "
+"for generation without recomputation. Uses peer-to-peer channels with "
+"communication libraries like NIXL for low-latency, high-bandwidth "
+"transfers."
+msgstr "专注于通过实时路由 KV Cache 数据在节点之间加速分布式推理。实现分离式 Prefill-解码，其中一台服务器为提示计算 KV，并将其传递给另一台服务器进行生成，而无需重计算。使用点对点通道和 NIXL 等通信库进行低延迟、高带宽的传输。"
+
+#: ../../source/developer_guide/architecture.rst:78
+msgid "Core Components"
+msgstr "核心组件"
+
+#: ../../source/developer_guide/architecture.rst:80
+msgid "**LLM Inference Engine Integration Module (Connector)**"
+msgstr "**LLM 推理引擎集成模块 (连接器)**"
+
+#: ../../source/developer_guide/architecture.rst:81
+msgid ""
+"Integrated into the LLM engine (vLLM), the Connector taps into the paged "
+"KV memory manager. During prompt processing, it checks if token sequences"
+" were seen before:"
+msgstr "集成到 LLM 引擎 (vLLM) 中，连接器利用分页 KV 内存管理器。在处理提示时，它检查令牌序列是否之前见过："
+
+#: ../../source/developer_guide/architecture.rst:83
+msgid ""
+"**Cache hit**: Fetches precomputed KV cache chunks from LMCache, "
+"bypassing computation"
+msgstr "**缓存命中**\\ ：从 LMCache 中获取预计算的 KV Cache 块，绕过计算"
+
+#: ../../source/developer_guide/architecture.rst:84
+msgid ""
+"**Cache miss**: Model computes KV as usual, then Connector hands newly-"
+"generated KV data to LMCache for storage"
+msgstr "**缓存未命中**\\ ：模型按常规计算 KV，然后连接器将新生成的 KV 数据交给 LMCache 进行存储"
+
+#: ../../source/developer_guide/architecture.rst:86
+msgid "**Cache Index (Token Database)**"
+msgstr "**缓存索引（令牌数据库）**"
+
+#: ../../source/developer_guide/architecture.rst:87
+msgid ""
+"Maintains an internal index mapping token sequences to cached KV entries "
+"and their locations. Enables cross-request and cross-instance cache "
+"lookups with configurable chunking strategy (default 256 tokens) and "
+"hashing scheme."
+msgstr "维护一个内部索引，将令牌序列映射到缓存的 KV 条目及其位置。支持跨请求和跨实例的缓存查找，具有可配置的块策略（默认 256 个令牌）和哈希方案。"
+
+#: ../../source/developer_guide/architecture.rst:89
+msgid "**Memory Object & Allocator**"
+msgstr "**内存对象与分配器**"
+
+#: ../../source/developer_guide/architecture.rst:90
+msgid ""
+"Manages KV cache entries as MemoryObj instances using a custom memory "
+"allocator within LocalCPUBackend. Ensures pinned memory for fast GPU↔CPU "
+"transfers, NUMA-aware allocation, and interfaces with eviction policies "
+"(LRU by default)."
+msgstr "在 LocalCPUBackend 中使用自定义内存分配器将 KV Cache 条目管理为 MemoryObj 实例。确保固定内存以实现快速的 GPU↔CPU 传输，支持 NUMA 感知分配，并与逐出策略（默认使用 LRU）接口。"
+
+#: ../../source/developer_guide/architecture.rst:92
+msgid "**Asynchronous Offloading**"
+msgstr "**异步卸载**"
+
+#: ../../source/developer_guide/architecture.rst:93
+msgid ""
+"Offloading / loading the KV cache chunks in an asynchronous manner to "
+"avoid blocking inference threads and GPU cycles."
+msgstr "以异步方式卸载/加载 KV Cache 块，以避免阻塞推理线程和 GPU 周期。"
+
+#: ../../source/developer_guide/architecture.rst:95
+msgid "**Remote Connectors**"
+msgstr "**远程连接器**"
+
+#: ../../source/developer_guide/architecture.rst:96
+msgid ""
+"Plugin-based system for remote backends (Redis, Mooncake, NiXL). Uses "
+"generic RemoteBackend wrapper that delegates operations to connector "
+"implementations, supporting dynamic loading of custom backends."
+msgstr "基于插件的远程后端系统（Redis、Mooncake、NiXL）。使用通用的 RemoteBackend 包装器，将操作委托给连接器实现，支持动态加载自定义后端。"
+
+#: ../../source/developer_guide/architecture.rst:99
+msgid "LMCache Controller"
+msgstr "LMCache 控制器"
+
+#: ../../source/developer_guide/architecture.rst:101
+msgid "The Controller provides a management API for runtime cache operations:"
+msgstr "控制器提供了一个用于运行时缓存操作的管理 API："
+
+#: ../../source/developer_guide/architecture.rst:103
+msgid ""
+"**Lookup**: Query cache entries for given token sequences and their "
+"locations"
+msgstr "**查找**\\ ：查询给定令牌序列及其位置的缓存条目"
+
+#: ../../source/developer_guide/architecture.rst:104
+msgid "**Clear**: Purge KV cache entirely or for specific entries"
+msgstr "**清除**: 完全清除 KV Cache 或特定条目"
+
+#: ../../source/developer_guide/architecture.rst:105
+msgid ""
+"**Compress/Decompress**: On-demand compression using CacheGen or "
+"decompression to full precision"
+msgstr "**压缩/解压缩**\\ ：按需使用 CacheGen 进行压缩或解压缩到全精度"
+
+#: ../../source/developer_guide/architecture.rst:106
+msgid ""
+"**Move**: Migrate caches to specified locations for cache warming or "
+"optimization"
+msgstr "**移动**\\ ：将缓存迁移到指定位置以进行缓存预热或优化"
+
+#: ../../source/developer_guide/architecture.rst:107
+msgid "**Pin/Unpin**: Mark cache entries as persistent to prevent eviction"
+msgstr "**固定/解固定**\\ ：将缓存条目标记为持久，以防止逐出"
+
+#: ../../source/developer_guide/architecture.rst:108
+msgid ""
+"**Health & Finish Checks**: Report worker health and confirm completion "
+"of async operations"
+msgstr "**健康与完成检查**\\ ：报告工作者健康状态并确认异步操作的完成"
+
+#: ../../source/developer_guide/architecture.rst:110
+msgid ""
+"The Controller coordinates with all LMCache workers in the system, "
+"providing centralized management for both single-instance and distributed"
+" deployments."
+msgstr "控制器与系统中的所有 LMCache 工作者协调，提供单实例和分布式部署的集中管理。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/cli.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/cli.po
new file mode 100644
index 0000000..444d21a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/cli.po
@@ -0,0 +1,517 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-29 10:44+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/cli.rst:2
+msgid "Extending the CLI"
+msgstr "扩展 CLI"
+
+#: ../../source/developer_guide/cli.rst:4
+msgid ""
+"LMCache's CLI is built on a plugin-style architecture that supports "
+"**N-level nested subcommands** with zero-registration auto-discovery. "
+"This guide explains how to add commands at each level."
+msgstr "LMCache 的 CLI 基于插件式架构构建，支持 **N 级嵌套子命令**，并具有零注册自动发现功能。本指南解释了如何在每个级别添加命令。"
+
+#: ../../source/developer_guide/cli.rst:9
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/developer_guide/cli.rst:11
+msgid ""
+"The CLI framework is composed of two core classes in "
+"``lmcache/cli/commands/base.py``:"
+msgstr "CLI 框架由两个核心类组成，位于 ``lmcache/cli/commands/base.py``："
+
+#: ../../source/developer_guide/cli.rst:14
+msgid ""
+"**BaseCommand** — Abstract base class for leaf commands (commands that "
+"perform actual work)."
+msgstr "**BaseCommand** — 叶命令的抽象基类（执行实际工作的命令）。"
+
+#: ../../source/developer_guide/cli.rst:16
+msgid ""
+"**CompositeCommand** — A ``BaseCommand`` subclass for commands that only "
+"group sub-subcommands. It auto-discovers child commands by scanning the "
+"package where it is defined."
+msgstr "**CompositeCommand** — 一个 ``BaseCommand`` 子类，用于仅将子子命令分组的命令。它通过扫描定义它的包自动发现子命令。"
+
+#: ../../source/developer_guide/cli.rst:20
+msgid ""
+"The discovery mechanism uses ``pkgutil.iter_modules`` to scan direct "
+"submodules of a package, then collects all concrete ``BaseCommand`` "
+"subclasses found in those modules. This means:"
+msgstr "发现机制使用 ``pkgutil.iter_modules`` 扫描包的直接子模块，然后收集在这些模块中找到的所有具体的 ``BaseCommand`` 子类。这意味着："
+
+#: ../../source/developer_guide/cli.rst:24
+msgid ""
+"Each command is a separate ``.py`` file (or a sub-package with an "
+"``__init__.py``)."
+msgstr "每个命令都是一个单独的 ``.py`` 文件（或带有 ``__init__.py`` 的子包）。"
+
+#: ../../source/developer_guide/cli.rst:26
+msgid ""
+"No manual registration is needed — just create the file and it is picked "
+"up automatically."
+msgstr "无需手动注册 — 只需创建文件，它会自动被识别。"
+
+#: ../../source/developer_guide/cli.rst:28
+msgid ""
+"Utility/helper modules should be prefixed with ``_`` (e.g. "
+"``_helpers.py``) so they are excluded from the scan."
+msgstr "工具/辅助模块应以 ``_`` 开头（例如 ``_helpers.py``），以便在扫描时将其排除。"
+
+#: ../../source/developer_guide/cli.rst:32
+msgid "Auto-Discovery Mechanism"
+msgstr "自动发现机制"
+
+#: ../../source/developer_guide/cli.rst:34
+msgid ""
+"The CLI uses a unified ``discover_subclasses()`` utility (defined in "
+"``lmcache/v1/utils/subclass_discovery.py``) to locate command classes at "
+"every level.  Understanding the two discovery entry points is key to "
+"extending the CLI."
+msgstr "CLI 使用统一的 ``discover_subclasses()`` 工具（定义在 ``lmcache/v1/utils/subclass_discovery.py`` 中）来定位每个级别的命令类。理解这两个发现入口是扩展 CLI 的关键。"
+
+#: ../../source/developer_guide/cli.rst:40
+msgid "Top-Level Command Discovery"
+msgstr "顶级命令发现"
+
+#: ../../source/developer_guide/cli.rst:42
+msgid ""
+"When the CLI starts, ``lmcache/cli/commands/__init__.py`` calls "
+"``discover_subclasses()`` on its own package (``lmcache.cli.commands``). "
+"This scans all **direct submodules** — both ``.py`` files and sub-"
+"packages (via their ``__init__.py``) — and collects every concrete "
+"``BaseCommand`` subclass found."
+msgstr "当 CLI 启动时，``lmcache/cli/commands/__init__.py`` 在其自身的包（``lmcache.cli.commands``）上调用 ``discover_subclasses()``。这会扫描所有 **直接子模块** — 包括 ``.py`` 文件和子包（通过它们的 ``__init__.py``） — 并收集找到的每个具体的 ``BaseCommand`` 子类。"
+
+#: ../../source/developer_guide/cli.rst:62
+msgid ""
+"The resulting ``ALL_COMMANDS`` list is then registered with the root "
+"``argparse`` parser in ``main.py``.  This means any new ``.py`` file (or "
+"sub-package) placed under ``lmcache/cli/commands/`` is automatically "
+"available as a top-level command — no manual imports or registration "
+"needed."
+msgstr "生成的 ``ALL_COMMANDS`` 列表随后在 ``main.py`` 中注册到根 ``argparse`` 解析器。这意味着放置在 ``lmcache/cli/commands/`` 下的任何新 ``.py`` 文件（或子包）会自动作为顶级命令可用 — 无需手动导入或注册。"
+
+#: ../../source/developer_guide/cli.rst:68
+msgid "**Filtering rules for top-level discovery:**"
+msgstr "**顶级发现的过滤规则：**"
+
+#: ../../source/developer_guide/cli.rst:70
+msgid ""
+"The module named ``base`` is explicitly excluded (it defines the abstract"
+" base classes, not a command)."
+msgstr "名为 ``base`` 的模块被明确排除（它定义了抽象基类，而不是一个命令）。"
+
+#: ../../source/developer_guide/cli.rst:72
+msgid ""
+"Modules whose name starts with ``_`` are excluded by the underlying "
+"``pkgutil.iter_modules`` convention (they are treated as private)."
+msgstr "以 ``_`` 开头的模块根据底层的 ``pkgutil.iter_modules`` 约定被排除（它们被视为私有）。"
+
+#: ../../source/developer_guide/cli.rst:74
+msgid "Only **concrete** subclasses are collected — abstract classes are skipped."
+msgstr "仅收集 **具体** 子类 — 抽象类会被跳过。"
+
+#: ../../source/developer_guide/cli.rst:76
+msgid ""
+"Only classes **defined in** the scanned module are collected (re-exports "
+"are ignored via ``require_defined_in_module=True``)."
+msgstr "仅收集在扫描模块中**定义的**类（通过 ``require_defined_in_module=True`` 忽略重新导出）。"
+
+#: ../../source/developer_guide/cli.rst:80
+msgid "Sub-Command Discovery (CompositeCommand)"
+msgstr "子命令发现（CompositeCommand）"
+
+#: ../../source/developer_guide/cli.rst:82
+msgid ""
+"When a ``CompositeCommand`` registers itself with the parser, its "
+"``register()`` method calls ``discover_subclasses()`` on the package "
+"where the ``CompositeCommand`` subclass is defined (i.e. its own "
+"``__init__.py``'s package)."
+msgstr "当 ``CompositeCommand`` 向解析器注册时，它的 ``register()`` 方法会在定义 ``CompositeCommand`` 子类的包上调用 ``discover_subclasses()``（即它自己的 ``__init__.py`` 所在的包）。"
+
+#: ../../source/developer_guide/cli.rst:103
+msgid "**Filtering rules for sub-command discovery:**"
+msgstr "**子命令发现的过滤规则：**"
+
+#: ../../source/developer_guide/cli.rst:105
+msgid ""
+"Modules starting with ``_`` are excluded (use this prefix for helper "
+"files like ``_utils.py``)."
+msgstr "以 ``_`` 开头的模块会被排除（使用这个前缀来命名像 ``_utils.py`` 这样的辅助文件）。"
+
+#: ../../source/developer_guide/cli.rst:107
+msgid ""
+"The ``CompositeCommand`` class itself is skipped to avoid infinite "
+"recursion."
+msgstr "``CompositeCommand`` 类本身被跳过以避免无限递归。"
+
+#: ../../source/developer_guide/cli.rst:109
+msgid ""
+"Only concrete ``BaseCommand`` subclasses **defined in** the scanned "
+"module are collected."
+msgstr "仅收集在扫描模块中**定义的**具体 ``BaseCommand`` 子类。"
+
+#: ../../source/developer_guide/cli.rst:111
+msgid ""
+"The scan is **non-recursive** (depth 1 only) — each ``CompositeCommand`` "
+"only sees its own package's direct children."
+msgstr "扫描是 **非递归** 的（仅深度 1）——每个 ``CompositeCommand`` 仅能看到其所在包的直接子项。"
+
+#: ../../source/developer_guide/cli.rst:114
+msgid ""
+"**How nesting works:** If a child is itself a ``CompositeCommand`` "
+"(defined in a sub-package's ``__init__.py``), its own ``register()`` "
+"method will in turn scan *its* package for further children.  This "
+"creates the recursive nesting without any special configuration."
+msgstr "**嵌套如何工作：** 如果一个子命令本身是一个 ``CompositeCommand``（在子包的 ``__init__.py`` 中定义），它自己的 ``register()`` 方法将反过来扫描 *它* 的包以查找更多子命令。这在没有任何特殊配置的情况下创建了递归嵌套。"
+
+#: ../../source/developer_guide/cli.rst:138
+msgid "Directory Layout"
+msgstr "目录结构"
+
+#: ../../source/developer_guide/cli.rst:161
+msgid "Key Rules"
+msgstr "关键规则"
+
+#: ../../source/developer_guide/cli.rst:163
+msgid ""
+"A ``CompositeCommand`` subclass **must** be defined in the "
+"``__init__.py`` of its package."
+msgstr "一个 ``CompositeCommand`` 子类 **必须** 在其包的 ``__init__.py`` 中定义。"
+
+#: ../../source/developer_guide/cli.rst:165
+msgid ""
+"Modules starting with ``_`` are **excluded** from auto-discovery (use "
+"this for helpers, utilities, internal logic)."
+msgstr "以 ``_`` 开头的模块会被 **排除** 在自动发现之外（用于帮助器、工具、内部逻辑）。"
+
+#: ../../source/developer_guide/cli.rst:167
+msgid ""
+"Each leaf command file should contain exactly one concrete "
+"``BaseCommand`` subclass."
+msgstr "每个叶命令文件应包含一个具体的 ``BaseCommand`` 子类。"
+
+#: ../../source/developer_guide/cli.rst:169
+msgid ""
+"The scan is **non-recursive** — each ``CompositeCommand`` only scans its "
+"own package's direct submodules."
+msgstr "扫描是 **非递归** 的——每个 ``CompositeCommand`` 仅扫描其自身包的直接子模块。"
+
+#: ../../source/developer_guide/cli.rst:173
+msgid "Level 1: Adding a Top-Level Command"
+msgstr "级别 1：添加顶级命令"
+
+#: ../../source/developer_guide/cli.rst:175
+msgid "A top-level command appears directly under ``lmcache <command>``."
+msgstr "一个顶级命令直接出现在 ``lmcache <command>`` 之下。"
+
+#: ../../source/developer_guide/cli.rst:177
+msgid "**Step 1**: Create a new file under ``lmcache/cli/commands/``:"
+msgstr "**步骤 1**：在 ``lmcache/cli/commands/`` 下创建一个新文件："
+
+#: ../../source/developer_guide/cli.rst:206
+msgid "**Step 2**: Done! The command is automatically discovered. Test it:"
+msgstr "**步骤 2**：完成！命令会自动被发现。测试一下："
+
+#: ../../source/developer_guide/cli.rst:214
+msgid ""
+"This works because the top-level ``lmcache/cli/commands/__init__.py`` "
+"calls ``discover_subclasses`` on its own package at import time. It uses "
+"``pkgutil.iter_modules`` to find all direct submodules (files and sub-"
+"packages), imports each one, and collects every concrete ``BaseCommand`` "
+"subclass. The resulting list is stored in ``ALL_COMMANDS`` and registered"
+" with the argument parser in ``main.py``. So adding a new ``.py`` file "
+"with a ``BaseCommand`` subclass is all that is needed — no edits to any "
+"other file."
+msgstr "这之所以有效，是因为顶层的 ``lmcache/cli/commands/__init__.py`` 在导入时调用了 ``discover_subclasses``。它使用 ``pkgutil.iter_modules`` 查找所有直接子模块（文件和子包），导入每一个，并收集每个具体的 ``BaseCommand`` 子类。结果列表存储在 ``ALL_COMMANDS`` 中，并在 ``main.py`` 中与参数解析器注册。因此，只需添加一个带有 ``BaseCommand`` 子类的新 ``.py`` 文件即可——不需要编辑其他任何文件。"
+
+#: ../../source/developer_guide/cli.rst:224
+msgid "Level 2: Adding a Subcommand Group"
+msgstr "级别 2：添加子命令组"
+
+#: ../../source/developer_guide/cli.rst:226
+msgid "A subcommand group appears as ``lmcache <group> <subcommand>``."
+msgstr "子命令组的形式为 ``lmcache <group> <subcommand>``。"
+
+#: ../../source/developer_guide/cli.rst:228
+msgid "**Step 1**: Create a package directory:"
+msgstr "**步骤 1**：创建一个包目录："
+
+#: ../../source/developer_guide/cli.rst:234
+msgid "**Step 2**: Define the ``CompositeCommand`` in ``__init__.py``:"
+msgstr "**第 2 步**：在 ``__init__.py`` 中定义 ``CompositeCommand``："
+
+#: ../../source/developer_guide/cli.rst:256
+msgid "**Step 3**: Add leaf subcommands as separate files:"
+msgstr "**第 3 步**：将叶子子命令作为单独的文件添加："
+
+#: ../../source/developer_guide/cli.rst:285
+msgid "**Step 4**: (Optional) Add helper modules with ``_`` prefix:"
+msgstr "**步骤 4**： （可选）添加以 ``_`` 前缀的辅助模块："
+
+#: ../../source/developer_guide/cli.rst:295
+#: ../../source/developer_guide/cli.rst:415
+msgid "**Result**:"
+msgstr "**结果**:"
+
+#: ../../source/developer_guide/cli.rst:302
+msgid "Level 2: Adding a Subcommand to an Existing Group"
+msgstr "级别 2：向现有组添加子命令"
+
+#: ../../source/developer_guide/cli.rst:304
+msgid ""
+"If a ``CompositeCommand`` group already exists (e.g. ``bench``, "
+"``quota``, ``trace``), you can extend it by simply adding **one new "
+"file** — no other changes are required."
+msgstr "如果已经存在一个 ``CompositeCommand`` 组（例如 ``bench``、``quota``、``trace``），您可以通过简单地添加 **一个新文件** 来扩展它 — 不需要其他更改。"
+
+#: ../../source/developer_guide/cli.rst:308
+msgid ""
+"For example, to add a new ``lmcache bench l2`` subcommand under the "
+"existing ``bench`` group:"
+msgstr "例如，要在现有的 ``bench`` 组下添加一个新的 ``lmcache bench l2`` 子命令："
+
+#: ../../source/developer_guide/cli.rst:311
+msgid ""
+"**Step 1**: Create a single file (or sub-package) in the existing group's"
+" package directory:"
+msgstr "**步骤 1**：在现有组的包目录中创建一个单文件（或子包）："
+
+#: ../../source/developer_guide/cli.rst:345
+msgid ""
+"**Step 2**: Done! The parent ``CompositeCommand`` (``BenchCommand``) "
+"auto-discovers the new subcommand at startup. No registration code, no "
+"imports to add, no ``__init__.py`` edits in the parent."
+msgstr "**步骤 2**：完成！父级 ``CompositeCommand`` (``BenchCommand``) 在启动时会自动发现新的子命令。无需注册代码，无需添加导入，无需在父级中编辑 ``__init__.py``。"
+
+#: ../../source/developer_guide/cli.rst:351
+msgid ""
+"This works because ``CompositeCommand.register()`` scans all direct "
+"submodules of its package each time the CLI starts. A new file (or sub-"
+"package) is automatically picked up as long as:"
+msgstr "这工作是因为 ``CompositeCommand.register()`` 每次 CLI 启动时都会扫描其包的所有直接子模块。只要满足以下条件，新文件（或子包）会被自动识别："
+
+#: ../../source/developer_guide/cli.rst:355
+msgid "It does **not** start with ``_``."
+msgstr "它**不**以``_``开头。"
+
+#: ../../source/developer_guide/cli.rst:356
+msgid "It contains a concrete ``BaseCommand`` subclass."
+msgstr "它包含一个具体的 ``BaseCommand`` 子类。"
+
+#: ../../source/developer_guide/cli.rst:359
+msgid "Level N: Arbitrary Nesting"
+msgstr "级别 N：任意嵌套"
+
+#: ../../source/developer_guide/cli.rst:361
+msgid ""
+"The framework supports **unlimited nesting depth**. Each level follows "
+"the same pattern: a ``CompositeCommand`` in a package's ``__init__.py`` "
+"auto-discovers its children."
+msgstr "该框架支持 **无限嵌套深度**。每个级别遵循相同的模式：包的 ``__init__.py`` 中的 ``CompositeCommand`` 自动发现其子命令。"
+
+#: ../../source/developer_guide/cli.rst:365
+msgid "**Example**: Adding a 3rd level under ``lmcache mygroup``:"
+msgstr "**示例**：在 ``lmcache mygroup`` 下添加第 3 级："
+
+#: ../../source/developer_guide/cli.rst:421
+msgid "You can continue nesting indefinitely by repeating this pattern."
+msgstr "您可以通过重复此模式无限制地继续嵌套。"
+
+#: ../../source/developer_guide/cli.rst:424
+msgid "Real-World Example"
+msgstr "现实世界示例"
+
+#: ../../source/developer_guide/cli.rst:426
+msgid ""
+"The existing ``lmcache tool cache-simulator simulate`` command "
+"demonstrates 3-level nesting:"
+msgstr "现有的 ``lmcache tool cache-simulator simulate`` 命令演示了 3 级嵌套："
+
+#: ../../source/developer_guide/cli.rst:438
+msgid "Using the Metrics System"
+msgstr "使用指标系统"
+
+#: ../../source/developer_guide/cli.rst:440
+msgid "The metrics system uses a **handler + formatter** architecture:"
+msgstr "指标系统使用 **处理器 + 格式化器** 架构："
+
+#: ../../source/developer_guide/cli.rst:442
+msgid "**Metrics** — the collector. Holds sections and entries."
+msgstr "**指标** — 收集器。包含部分和条目。"
+
+#: ../../source/developer_guide/cli.rst:443
+msgid "**Handler** — the destination (stdout, file, etc.)."
+msgstr "**处理器** — 目标（标准输出、文件等）。"
+
+#: ../../source/developer_guide/cli.rst:444
+msgid "**Formatter** — the rendering (ASCII table, JSON, etc.)."
+msgstr "**格式化器** — 渲染（ASCII 表格、JSON 等）。"
+
+#: ../../source/developer_guide/cli.rst:446
+msgid ""
+"``BaseCommand.create_metrics()`` sets up default handlers automatically, "
+"so command authors just build metrics and call ``emit()``:"
+msgstr ""
+"``BaseCommand.create_metrics()`` 会自动配置默认处理器，命令开发者只需构建指标数据并调用 ``emit()`` "
+"即可："
+
+#: ../../source/developer_guide/cli.rst:468
+msgid ""
+"The ``--format`` and ``--output`` flags are added automatically by "
+"``BaseCommand.register()`` — subcommands do not need to add them "
+"manually."
+msgstr ""
+"``--format`` 和 ``--output`` 标志由 ``BaseCommand.register()`` 自动添加 — "
+"子命令无需手动添加。"
+
+#: ../../source/developer_guide/cli.rst:472
+msgid "Summary"
+msgstr "摘要"
+
+#: ../../source/developer_guide/cli.rst:478
+msgid "Level"
+msgstr "级别"
+
+#: ../../source/developer_guide/cli.rst:479
+msgid "Pattern"
+msgstr "模式"
+
+#: ../../source/developer_guide/cli.rst:480
+msgid "How to add"
+msgstr "如何添加"
+
+#: ../../source/developer_guide/cli.rst:481
+msgid "1 (top)"
+msgstr "1 (顶部)"
+
+#: ../../source/developer_guide/cli.rst:482
+msgid "Single ``.py`` file"
+msgstr "单个 ``.py`` 文件"
+
+#: ../../source/developer_guide/cli.rst:483
+msgid "Create ``lmcache/cli/commands/<name>.py`` with a ``BaseCommand`` subclass."
+msgstr "创建 ``lmcache/cli/commands/<name>.py``，并使用 ``BaseCommand`` 子类。"
+
+#: ../../source/developer_guide/cli.rst:485
+msgid "2+"
+msgstr "2+"
+
+#: ../../source/developer_guide/cli.rst:486
+msgid "Package directory"
+msgstr "包目录"
+
+#: ../../source/developer_guide/cli.rst:487
+msgid ""
+"Create ``lmcache/cli/commands/<group>/__init__.py`` with a "
+"``CompositeCommand`` subclass, then add leaf commands as sibling ``.py`` "
+"files."
+msgstr "创建 ``lmcache/cli/commands/<group>/__init__.py``，并使用 ``CompositeCommand`` 子类，然后将叶命令作为同级 ``.py`` 文件添加。"
+
+#: ../../source/developer_guide/cli.rst:490
+msgid "N (any)"
+msgstr "N (任何)"
+
+#: ../../source/developer_guide/cli.rst:491
+msgid "Nested package"
+msgstr "嵌套包"
+
+#: ../../source/developer_guide/cli.rst:492
+msgid ""
+"Same as level 2, but inside an existing composite command's package. Each"
+" ``CompositeCommand`` scans only its own direct submodules."
+msgstr "与级别 2 相同，但在现有复合命令的包内。每个 ``CompositeCommand`` 仅扫描其直接子模块。"
+
+#: ../../source/developer_guide/cli.rst:498
+msgid ""
+"Prefix helper/utility modules with ``_`` to exclude them from auto-"
+"discovery."
+msgstr "将帮助/工具模块前缀加上 ``_`` 以将其排除在自动发现之外。"
+
+#: ../../source/developer_guide/cli.rst:500
+msgid ""
+"Each ``CompositeCommand`` must be defined in its package's "
+"``__init__.py``."
+msgstr "每个 ``CompositeCommand`` 必须在其包的 ``__init__.py`` 中定义。"
+
+#: ../../source/developer_guide/cli.rst:502
+msgid ""
+"The ``name()`` method determines the CLI token (e.g. ``\"foo\"`` becomes "
+"``lmcache ... foo``)."
+msgstr "``name()`` 方法确定 CLI 令牌（例如 ``\"foo\"`` 变为 ``lmcache ... foo``）。"
+
+#~ msgid "File Layout"
+#~ msgstr "文件布局"
+
+#~ msgid "**Step 1.** Create ``lmcache/cli/commands/describe.py``:"
+#~ msgstr "**第 1 步。** 创建 ``lmcache/cli/commands/describe.py``："
+
+#~ msgid "**Step 2.** Register it in ``lmcache/cli/commands/__init__.py``:"
+#~ msgstr "**步骤 2.** 在 ``lmcache/cli/commands/__init__.py`` 中注册它："
+
+#~ msgid "This guide explains how to add new subcommands to the ``lmcache`` CLI."
+#~ msgstr "本指南介绍如何为 ``lmcache`` CLI 添加新子命令。"
+
+#~ msgid "The CLI uses explicit command registration:"
+#~ msgstr "CLI 使用显式命令注册："
+
+#~ msgid "Each command is a class inheriting from ``BaseCommand``."
+#~ msgstr "每个命令都是一个继承自 ``BaseCommand`` 的类。"
+
+#~ msgid ""
+#~ "Commands are instantiated and listed in"
+#~ " a central ``ALL_COMMANDS`` registry."
+#~ msgstr "所有命令均在中央 ``ALL_COMMANDS`` 注册表中实例化并列出。"
+
+#~ msgid ""
+#~ "At startup, the entry point iterates "
+#~ "``ALL_COMMANDS`` and calls "
+#~ "``cmd.register(subparsers)`` to wire up "
+#~ "argparse."
+#~ msgstr ""
+#~ "启动时，入口点遍历 ``ALL_COMMANDS`` 并调用 "
+#~ "``cmd.register(subparsers)``，将各子命令注册到 argparse。"
+
+#~ msgid ""
+#~ "``BaseCommand`` is an abstract class "
+#~ "with a small set of required "
+#~ "methods (name, help, argument registration,"
+#~ " and execute). Forgetting any of them"
+#~ " raises ``TypeError`` at instantiation "
+#~ "time."
+#~ msgstr ""
+#~ "``BaseCommand`` 是一个抽象类，包含少量必需方法（名称、帮助、参数注册及执行）。若遗漏其中任一方法，实例化时将引发"
+#~ " ``TypeError``。"
+
+#~ msgid "**Step 1.** Create a new command class that subclasses ``BaseCommand``:"
+#~ msgstr "**步骤 1.** 创建一个继承自 ``BaseCommand`` 的新命令类："
+
+#~ msgid "**Step 2.** Add an instance of it to the ``ALL_COMMANDS`` registry:"
+#~ msgstr "**步骤 2.** 将其实例添加到 ``ALL_COMMANDS`` 注册表中："
+
+#~ msgid ""
+#~ "That's it --- ``lmcache describe --url"
+#~ " http://localhost:8000`` is now available."
+#~ msgstr "至此，``lmcache describe --url http://localhost:8000`` 即可正常使用。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/contributing.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/contributing.po
new file mode 100644
index 0000000..366ba73
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/contributing.po
@@ -0,0 +1,497 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/contributing.rst:2
+msgid "Contributing Guide"
+msgstr "贡献指南"
+
+#: ../../source/developer_guide/contributing.rst:4
+msgid ""
+"Thank you for your interest in contributing to LMCache! We welcome and "
+"accept all kinds of contributions, no matter how small or large. There "
+"are several ways you can contribute to the project:"
+msgstr "感谢您有兴趣为 LMCache 做出贡献！我们欢迎并接受各种形式的贡献，无论大小。您可以通过以下几种方式为项目做出贡献："
+
+#: ../../source/developer_guide/contributing.rst:6
+msgid "Identify and report any issues or bugs"
+msgstr "识别并报告任何问题或错误"
+
+#: ../../source/developer_guide/contributing.rst:7
+msgid "Request or add support for a new model"
+msgstr "请求或添加对新模型的支持"
+
+#: ../../source/developer_guide/contributing.rst:8
+msgid "Suggest or implement new features"
+msgstr "建议或实现新功能"
+
+#: ../../source/developer_guide/contributing.rst:9
+msgid "Improve documentation or contribute a how-to guide"
+msgstr "改进文档或贡献一份操作指南"
+
+#: ../../source/developer_guide/contributing.rst:11
+msgid ""
+"A comprehensive list of good first issues can be found in the issue "
+"`[Onboarding][Q4] Welcoming contributors with good first issues! "
+"<https://github.com/LMCache/LMCache/issues/1882>`_."
+msgstr "可以在 Issue `[Onboarding][Q4] Welcoming contributors with good first issues! <https://github.com/LMCache/LMCache/issues/1882>`_ 中找到完整的适合新手的 Issue 列表。"
+
+#: ../../source/developer_guide/contributing.rst:13
+msgid ""
+"If you'd like to support our community further, then answering queries, "
+"offering PR reviews, and assisting others are also impactful ways to "
+"contribute and take LMCache further."
+msgstr "如果您想进一步支持我们的社区，回答问题、提供 PR 评审和协助他人也是对 LMCache 产生影响的贡献方式。"
+
+#: ../../source/developer_guide/contributing.rst:15
+msgid ""
+"Finally, you can support us by raising awareness about LMCache. Feel free"
+" to share our blog posts, check out our handle on X at `LMCache "
+"<https://x.com/lmcache>`_ and see the latest of what we are up to. If "
+"using LMCache helped your project or product in any way, you can simply "
+"offer your appreciation by starring our repository!"
+msgstr "最后，您可以通过提高对 LMCache 的认识来支持我们。欢迎分享我们的博客文章，查看我们在 X 上的账号 `LMCache <https://x.com/lmcache>`_，了解我们最新的动态。如果使用 LMCache 在某种程度上帮助了您的项目或产品，您可以通过给我们的代码库加星来表达您的感谢！"
+
+#: ../../source/developer_guide/contributing.rst:18
+msgid "License"
+msgstr "许可证"
+
+#: ../../source/developer_guide/contributing.rst:20
+msgid ""
+"See the `LICENSE <https://github.com/LMCache/LMCache/blob/dev/LICENSE>`_ "
+"file for details."
+msgstr "请参阅 `LICENSE <https://github.com/LMCache/LMCache/blob/dev/LICENSE>`_ 文件以获取详细信息。"
+
+#: ../../source/developer_guide/contributing.rst:23
+msgid "Code of Conduct"
+msgstr "行为准则"
+
+#: ../../source/developer_guide/contributing.rst:25
+msgid ""
+"This project adheres to the `Code of Conduct "
+"<https://github.com/LMCache/LMCache/blob/dev/CODE_OF_CONDUCT.md>`_. By "
+"participating, you are expected to uphold this code."
+msgstr "本项目遵循 `行为准则 <https://github.com/LMCache/LMCache/blob/dev/CODE_OF_CONDUCT.md>`_。参与时，您需要遵守此准则。"
+
+#: ../../source/developer_guide/contributing.rst:28
+msgid "Contribution Guidelines"
+msgstr "贡献指南"
+
+#: ../../source/developer_guide/contributing.rst:30
+msgid ""
+"Help on open source projects is always welcome and there is always "
+"something that can be improved. For example, documentation (like the text"
+" you are reading now) can always use improvement, code can always be "
+"clarified, variables or functions can always be renamed or commented on, "
+"and there is always a need for more test coverage. If you see something "
+"that you think should be fixed, take ownership! Here is how you get "
+"started."
+msgstr "对开源项目的帮助总是受欢迎的，总有一些可以改进的地方。例如，文档（就像您现在正在阅读的文本）总是可以改进，代码总是可以更清晰，变量或函数总是可以重命名或添加注释，并且总是需要更多的测试覆盖率。如果您看到认为应该修复的内容，请主动承担责任！以下是入门指南。"
+
+#: ../../source/developer_guide/contributing.rst:33
+msgid "How Can I Contribute?"
+msgstr "我该如何贡献？"
+
+#: ../../source/developer_guide/contributing.rst:35
+msgid ""
+"When contributing, it's useful to start by looking at `issues "
+"<https://github.com/LMCache/LMCache/issues>`_. After picking up an issue,"
+" writing code, or updating a document, make a pull request and your work "
+"will be reviewed and merged. If you're adding a new feature or find a "
+"bug, it's best to `write an issue "
+"<https://github.com/LMCache/LMCache/issues/new>`_ first to discuss it "
+"with maintainers."
+msgstr "在贡献时，首先查看 `issues <https://github.com/LMCache/LMCache/issues>`_ 是很有帮助的。在选择一个问题后，编写代码或更新文档，然后提交一个拉取请求，你的工作将会被审查和合并。如果你要添加新功能或发现错误，最好先 `写一个问题 <https://github.com/LMCache/LMCache/issues/new>`_ 与维护者讨论。"
+
+#: ../../source/developer_guide/contributing.rst:37
+msgid ""
+"If you discover a security vulnerability, please follow the instructions "
+"in the `Security doc "
+"<https://github.com/LMCache/LMCache/blob/dev/SECURITY.md>`_."
+msgstr "如果您发现安全漏洞，请按照 `安全文档 <https://github.com/LMCache/LMCache/blob/dev/SECURITY.md>`_ 中的说明进行操作。"
+
+#: ../../source/developer_guide/contributing.rst:39
+msgid ""
+"To contribute to this repo, you'll use the Fork and Pull model common in "
+"many open source repositories. For details on this process, check out "
+"`The GitHub Workflow Guide "
+"<https://github.com/kubernetes/community/blob/master/contributors/guide"
+"/github-workflow.md>`_ from Kubernetes. In short:"
+msgstr "要为这个仓库贡献代码，您将使用许多开源仓库中常见的分叉和拉取模型。有关此过程的详细信息，请查看 Kubernetes 的 `GitHub 工作流程指南 <https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md>`_。简而言之："
+
+#: ../../source/developer_guide/contributing.rst:41
+msgid "Fork the repository"
+msgstr "分叉仓库"
+
+#: ../../source/developer_guide/contributing.rst:42
+msgid "Create a branch"
+msgstr "创建一个分支"
+
+#: ../../source/developer_guide/contributing.rst:43
+msgid "Run code style checks and fix any issues"
+msgstr "运行代码风格检查并修复任何问题"
+
+#: ../../source/developer_guide/contributing.rst:44
+msgid "Run unit tests and fix any broken tests"
+msgstr "运行单元测试并修复任何损坏的测试"
+
+#: ../../source/developer_guide/contributing.rst:45
+msgid "Submit a pull request with detailed descriptions"
+msgstr "提交包含详细描述的拉取请求"
+
+#: ../../source/developer_guide/contributing.rst:47
+msgid ""
+"When your contribution is ready, you can create a pull request. Pull "
+"requests are often referred to as \"PRs\". In general, we follow the "
+"standard `GitHub pull request <https://help.github.com/en/articles/about-"
+"pull-requests>`_ process. Follow the template to provide details about "
+"your pull request to the maintainers."
+msgstr "当您的贡献准备好后，您可以创建一个拉取请求。拉取请求通常被称为“PR”。一般来说，我们遵循标准的 `GitHub 拉取请求 <https://help.github.com/en/articles/about-pull-requests>`_ 流程。请按照模板提供有关您的拉取请求的详细信息给维护者。"
+
+#: ../../source/developer_guide/contributing.rst:49
+msgid ""
+"Please try to classify PRs for easy understanding of the type of changes."
+" The PR title is prefixed appropriately to indicate the type of change. "
+"Please use one of the following:"
+msgstr "请尽量对 PR 进行分类，以便于理解更改类型。PR 标题前缀应适当地指示更改类型。请使用以下之一："
+
+#: ../../source/developer_guide/contributing.rst:51
+msgid "[Bugfix] for bug fixes"
+msgstr "[Bugfix] 用于错误修复"
+
+#: ../../source/developer_guide/contributing.rst:52
+msgid "[Build] for build fixes and improvements"
+msgstr "[构建] 用于构建修复和改进"
+
+#: ../../source/developer_guide/contributing.rst:53
+msgid "[CI] for continuous integration fixes and iimprovements"
+msgstr "[CI] 用于持续集成的修复和改进"
+
+#: ../../source/developer_guide/contributing.rst:54
+msgid ""
+"[Core] for changes in the core LMCache logic (e.g., ``LMCacheEngine``, "
+"``Backend`` etc.)"
+msgstr "[核心] 用于核心 LMCache 逻辑的更改（例如，``LMCacheEngine``，``Backend`` 等）"
+
+#: ../../source/developer_guide/contributing.rst:55
+msgid "[Doc] for documentation fixes and improvements"
+msgstr "[文档] 用于文档修复和改进"
+
+#: ../../source/developer_guide/contributing.rst:56
+msgid ""
+"[Misc] for PRs that do not fit the above categories. Please use this "
+"sparingly"
+msgstr "[杂项] 用于不符合上述类别的 PR。请谨慎使用。"
+
+#: ../../source/developer_guide/contributing.rst:57
+msgid ""
+"[Model] for adding a new model or improving an existing model. Model name"
+" should appear in the title"
+msgstr "[模型] 用于添加新模型或改进现有模型。模型名称应出现在标题中"
+
+#: ../../source/developer_guide/contributing.rst:58
+msgid "[Test] for unit tests"
+msgstr "[Test] 用于单元测试"
+
+#: ../../source/developer_guide/contributing.rst:62
+msgid ""
+"If the PR spans more than one category, please include all relevant "
+"prefixes"
+msgstr "如果 PR 涉及多个类别，请包含所有相关的前缀。"
+
+#: ../../source/developer_guide/contributing.rst:64
+msgid ""
+"It's best to break your contribution into smaller PRs with incremental "
+"changes, and include a good description of the changes. We require new "
+"unit tests to be contributed with any new functionality added and docs if"
+" user facing changes."
+msgstr "最好将您的贡献分解为较小的 PR，进行增量更改，并包含对更改的良好描述。我们要求在添加任何新功能时提供新的单元测试，并在用户可见的更改时提供文档。"
+
+#: ../../source/developer_guide/contributing.rst:66
+msgid ""
+"Before sending pull requests, make sure your changes pass code quality "
+"checks and unit tests. These checks will run when the pull request "
+"builds. Alternatively, you can run the checks manually on your local "
+"machine `as specified in Development <#development>`_ ."
+msgstr "在发送拉取请求之前，请确保您的更改通过了代码质量检查和单元测试。这些检查将在拉取请求构建时运行。或者，您可以按照 `开发 <#development>`_ 中的说明在本地机器上手动运行检查。"
+
+#: ../../source/developer_guide/contributing.rst:69
+msgid "DCO and Signed-off-by"
+msgstr "DCO 和签署确认"
+
+#: ../../source/developer_guide/contributing.rst:71
+msgid ""
+"When contributing changes to the project, you must agree to the `DCO "
+"<https://github.com/LMCache/LMCache/blob/dev/DCO>`_. Commits must include"
+" a :code:`Signed-off-by` header which certifies agreement with the terms "
+"of the `DCO <https://github.com/LMCache/LMCache/blob/dev/DCO>`_."
+msgstr "在向项目贡献更改时，您必须同意 `DCO <https://github.com/LMCache/LMCache/blob/dev/DCO>`_。提交必须包含一个 :code:`Signed-off-by` 头部，以证明您同意 `DCO <https://github.com/LMCache/LMCache/blob/dev/DCO>`_ 的条款。"
+
+#: ../../source/developer_guide/contributing.rst:75
+msgid ""
+"Using :code:`-s` or :code:`--signoff` flag with :code:`git commit` will "
+"automatically add this header. The flags can also be used with "
+":code:`--amend` if you forget to sign your last commit."
+msgstr "使用 :code:`-s` 或 :code:`--signoff` 标志与 :code:`git commit` 一起将自动添加此标题。如果您忘记为上一个提交签名，这些标志也可以与 :code:`--amend` 一起使用。"
+
+#: ../../source/developer_guide/contributing.rst:78
+msgid "Code Review"
+msgstr "代码审查"
+
+#: ../../source/developer_guide/contributing.rst:80
+msgid ""
+"Once you've created a pull request, maintainers will review your code and"
+" may make suggestions to fix before merging. It will be easier for your "
+"pull request to receive reviews if you consider the criteria the "
+"reviewers follow while working. Remember to:"
+msgstr "一旦您创建了拉取请求，维护者将审查您的代码，并可能提出建议以在合并之前进行修复。如果您在工作时考虑审查者遵循的标准，您的拉取请求将更容易获得审查。请记住："
+
+#: ../../source/developer_guide/contributing.rst:82
+msgid "Document the code well to help future contributors and maintainers"
+msgstr "对代码进行良好的文档记录，以帮助未来的贡献者和维护者。"
+
+#: ../../source/developer_guide/contributing.rst:83
+msgid "Follow the project coding conventions for consistency and best practices"
+msgstr "遵循项目编码规范，以确保一致性和最佳实践"
+
+#: ../../source/developer_guide/contributing.rst:84
+msgid "Include sufficient tests to maintain robustness of the code"
+msgstr "包含足够的测试以保持代码的健壮性"
+
+#: ../../source/developer_guide/contributing.rst:85
+msgid ""
+"Add or update documentation in :code:`/docs` if PR modifies user facing "
+"behavior to help people using LMCache"
+msgstr "如果 PR 修改了面向用户的行为，请在 :code:`/docs` 中添加或更新文档，以帮助使用 LMCache 的人。"
+
+#: ../../source/developer_guide/contributing.rst:86
+msgid "Run coding style checks to ensure consistency and correctness"
+msgstr "运行编码风格检查以确保一致性和正确性"
+
+#: ../../source/developer_guide/contributing.rst:87
+msgid ""
+"Run tests locally and ensure they pass and don't break the existing code "
+"base"
+msgstr "在本地运行测试，确保它们通过并且不会破坏现有代码库。"
+
+#: ../../source/developer_guide/contributing.rst:88
+msgid "Write detailed commit messages to help future contributors and maintainers"
+msgstr "撰写详细的提交信息，以帮助未来的贡献者和维护者。"
+
+#: ../../source/developer_guide/contributing.rst:89
+msgid ""
+"Break large changes into a logical series of smaller patches, which are "
+"easy to understand individually and combine to solve a broader issue"
+msgstr "将大型更改拆分为一系列逻辑上较小的补丁，这些补丁单独易于理解，并结合起来解决更广泛的问题。"
+
+#: ../../source/developer_guide/contributing.rst:93
+msgid ""
+"Maintainers will perform \"squash and merge\" actions on PRs in this "
+"repo, so it doesn't matter how many commits your PR has, as they will end"
+" up being a single commit after merging."
+msgstr "维护者将在此仓库的 PR 上执行“压缩并合并”操作，因此您的 PR 有多少个提交并不重要，因为它们在合并后将变成一个单一的提交。"
+
+#: ../../source/developer_guide/contributing.rst:96
+msgid "Development"
+msgstr "开发"
+
+#: ../../source/developer_guide/contributing.rst:99
+msgid "Set up your dev environment"
+msgstr "设置您的开发环境"
+
+#: ../../source/developer_guide/contributing.rst:101
+msgid "The following prerequisites are required:"
+msgstr "以下先决条件是必需的："
+
+#: ../../source/developer_guide/contributing.rst:103
+msgid "OS: Linux"
+msgstr "操作系统：Linux"
+
+#: ../../source/developer_guide/contributing.rst:104
+msgid ""
+"GPU: NVIDIA compute capability 7.0+ (e.g., V100, T4, RTX20xx, A100, L4, "
+"H100, etc.)"
+msgstr "GPU: NVIDIA 计算能力 7.0+（例如，V100、T4、RTX20xx、A100、L4、H100 等）"
+
+#: ../../source/developer_guide/contributing.rst:105
+msgid "CUDA 12.8+"
+msgstr "CUDA 12.8+"
+
+#: ../../source/developer_guide/contributing.rst:107
+msgid "The following tools are required:"
+msgstr "以下工具是必需的："
+
+#: ../../source/developer_guide/contributing.rst:109
+msgid "`git <https://git-scm.com>`_"
+msgstr "`git <https://git-scm.com>`_"
+
+#: ../../source/developer_guide/contributing.rst:110
+msgid "`python <https://www.python.org>`_ (v3.10 -- v3.13)"
+msgstr "`python <https://www.python.org>`_ (v3.10 -- v3.13)"
+
+#: ../../source/developer_guide/contributing.rst:111
+msgid "`pip <https://pypi.org/project/pip/>`_ (v23.0+)"
+msgstr "`pip <https://pypi.org/project/pip/>`_ (v23.0+)"
+
+#: ../../source/developer_guide/contributing.rst:113
+msgid ""
+"The first step is to install the necessary Python packages required for "
+"development. The commands to do this are as follows:"
+msgstr "第一步是安装开发所需的必要 Python 包。执行此操作的命令如下："
+
+#: ../../source/developer_guide/contributing.rst:123
+msgid ""
+"Before pushing changes to GitHub, you need to run the coding style checks"
+" and unit tests as shown below."
+msgstr "在将更改推送到 GitHub 之前，您需要运行如下所示的编码风格检查和单元测试。"
+
+#: ../../source/developer_guide/contributing.rst:126
+msgid "Coding style"
+msgstr "编码风格"
+
+#: ../../source/developer_guide/contributing.rst:128
+msgid ""
+"LMCache follows the Python `pep8 <https://peps.python.org/pep-0008/>`_ "
+"coding style for Python and `Google C++ style guide "
+"<https://google.github.io/styleguide/cppguide.html>`_ for C++. We use the"
+" following tools to enforce the coding style:"
+msgstr "LMCache 遵循 Python 的 `pep8 <https://peps.python.org/pep-0008/>`_ 编码风格和 C++ 的 `Google C++ style guide <https://google.github.io/styleguide/cppguide.html>`_。我们使用以下工具来强制执行编码风格："
+
+#: ../../source/developer_guide/contributing.rst:130
+msgid ""
+"Python linting and formatting: `Ruff <https://docs.astral.sh/ruff/>`_, "
+"and `isort <https://pycqa.github.io/isort/>`_"
+msgstr "Python 代码检查和格式化： `Ruff <https://docs.astral.sh/ruff/>`_ 和 `isort <https://pycqa.github.io/isort/>`_"
+
+#: ../../source/developer_guide/contributing.rst:131
+msgid "Python static code checking: `mypy <https://github.com/python/mypy>`_"
+msgstr "Python 静态代码检查: `mypy <https://github.com/python/mypy>`_"
+
+#: ../../source/developer_guide/contributing.rst:132
+msgid ""
+"Spell checking: `codespell <https://github.com/codespell-"
+"project/codespell>`_"
+msgstr "拼写检查: `codespell <https://github.com/codespell-project/codespell>`_"
+
+#: ../../source/developer_guide/contributing.rst:133
+msgid ""
+"C++ formatting: `clang-format "
+"<https://clang.llvm.org/docs/ClangFormat.html>`_"
+msgstr "C++ 格式化: `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_"
+
+#: ../../source/developer_guide/contributing.rst:135
+msgid ""
+"The tools are managed by `pre-commit <https://pre-commit.com/>`_. It is "
+"installed as follows:"
+msgstr "这些工具由 `pre-commit <https://pre-commit.com/>`_ 管理。安装方法如下："
+
+#: ../../source/developer_guide/contributing.rst:142
+msgid ""
+"It will run automatically when you add a commit. You can also run it "
+"manually on all files with the following command:"
+msgstr "它将在您添加提交时自动运行。您也可以使用以下命令手动在所有文件上运行它："
+
+#: ../../source/developer_guide/contributing.rst:150
+msgid ""
+"For all new code added, please write docstrings in `sphinx-doc format "
+"<https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_."
+msgstr "对于所有新增的代码，请使用 `sphinx-doc 格式 <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_ 编写文档字符串。"
+
+#: ../../source/developer_guide/contributing.rst:153
+msgid "Unit tests"
+msgstr "单元测试"
+
+#: ../../source/developer_guide/contributing.rst:155
+msgid ""
+"When making changes, run the tests before pushing the changes. Running "
+"unit tests ensures your contributions do not break existing code. We use "
+"the `pytest <https://docs.pytest.org/>`_ framework to run unit tests. The"
+" framework is setup to run all files in the `tests "
+"<https://github.com/LMCache/LMCache/tree/dev/tests>`_ directory which "
+"have a prefix or posfix of \"test\"."
+msgstr "在进行更改时，请在推送更改之前运行测试。运行单元测试可以确保您的贡献不会破坏现有代码。我们使用 `pytest <https://docs.pytest.org/>`_ 框架来运行单元测试。该框架已设置为运行 `tests <https://github.com/LMCache/LMCache/tree/dev/tests>`_ 目录中所有以“test”开头或结尾的文件。"
+
+#: ../../source/developer_guide/contributing.rst:157
+msgid "Running unit tests is as simple as:"
+msgstr "运行单元测试非常简单："
+
+#: ../../source/developer_guide/contributing.rst:165
+msgid ""
+"``vLLM`` (``pip install vllm``) and the dependencies in "
+"``requirements/test.txt`` need to be installed prior to running unit "
+"tests."
+msgstr "在运行单元测试之前，需要安装 ``vLLM`` (``pip install vllm``) 及 ``requirements/test.txt`` 中的依赖项。"
+
+#: ../../source/developer_guide/contributing.rst:167
+msgid ""
+"By default, all tests found within the tests directory are run. However, "
+"specific unit tests can run by passing filenames, classes and/or methods "
+"to `pytest`. The following example invokes a single test method "
+"\"test_lm_connector\" that is declared in the \"tests/test_connector.py\""
+" file:"
+msgstr "默认情况下，将运行测试目录中找到的所有测试。然而，可以通过将文件名、类和/或方法传递给 `pytest` 来运行特定的单元测试。以下示例调用在 \\\"tests/test_connector.py\\\" 文件中声明的单个测试方法 \\\"test_lm_connector\\\"："
+
+#: ../../source/developer_guide/contributing.rst:175
+msgid ""
+"Some unit tests require a NVIDIA GPU. This means that on a non Linux "
+"NVIDIA GPU system, the full suite of tests will not be run (tests "
+"requiring CUDA will be skipped). The Buildkite continuous integration "
+"(CI)  system executes a full run of all the tests."
+msgstr "某些单元测试需要 NVIDIA GPU。这意味着在非 Linux NVIDIA GPU 系统上，所有测试将不会全部运行（需要 CUDA 的测试将被跳过）。Buildkite 持续集成（CI）系统会执行所有测试的完整运行。"
+
+#: ../../source/developer_guide/contributing.rst:179
+msgid ""
+"The `NVIDIA Inference Xfer Library (NIXL) <https://github.com/ai-"
+"dynamo/nixl>`_ unit tests require NIXL to be to be installed. This is not"
+" installed by LMCache by and therefore requires you to install it "
+"separately. Please follow the details in the NIXL GitHub repo to install."
+" If the NIXL package is not installed, the NIXL unit tests are skipped."
+msgstr "`NVIDIA Inference Xfer Library (NIXL) <https://github.com/ai-dynamo/nixl>`_ 单元测试需要安装 NIXL。LMCache 不会安装它，因此需要您单独安装。请按照 NIXL GitHub 仓库中的详细信息进行安装。如果未安装 NIXL 包，则会跳过 NIXL 单元测试。"
+
+#: ../../source/developer_guide/contributing.rst:183
+msgid "Building the docs"
+msgstr "构建文档"
+
+#: ../../source/developer_guide/contributing.rst:185
+msgid "Install the dependencies:"
+msgstr "安装依赖项："
+
+#: ../../source/developer_guide/contributing.rst:191
+msgid ""
+"After that, you can build the docs (from :code:`docs/` directory) using "
+"`make`:"
+msgstr "之后，您可以使用 `make` 从 :code:`docs/` 目录构建文档："
+
+#: ../../source/developer_guide/contributing.rst:198
+msgid ""
+"Serve docs page locally at http://localhost:8000: :code:`python -m "
+"http.server -d build/html/`"
+msgstr "在 http://localhost:8000 本地服务文档页面： :code:`python -m http.server -d build/html/`"
+
+#: ../../source/developer_guide/contributing.rst:201
+msgid "Thank You"
+msgstr "感谢"
+
+#: ../../source/developer_guide/contributing.rst:203
+msgid ""
+"Thank you for your contribution to LMCache and making it a better, and "
+"accessible framework for all."
+msgstr "感谢您为 LMCache 的贡献，使其成为一个更好、更易于访问的框架。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_http_api.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_http_api.po
new file mode 100644
index 0000000..2fd8983
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_http_api.po
@@ -0,0 +1,211 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/extending_http_api.rst:2
+msgid "Extending the HTTP API"
+msgstr "扩展 HTTP API"
+
+#: ../../source/developer_guide/extending_http_api.rst:4
+msgid ""
+"You can add new endpoints to the ``lmcache server`` HTTP frontend "
+"**without modifying any existing code**. An endpoint is just a Python "
+"module placed in ``lmcache/v1/multiprocess/http_apis/`` that exposes a "
+"FastAPI ``APIRouter``; ``HTTPAPIRegistry`` auto-discovers and mounts it "
+"at startup -- the same zero-modification pattern used by the :doc:`L2 "
+"adapters </mp/l2_storage/index>`."
+msgstr ""
+"您可以向 ``lmcache server`` HTTP 前端添加新端点，\\ **无需修改任何现有代码**\\ 。端点只需是放置在 "
+"``lmcache/v1/multiprocess/http_apis/`` 中的 Python 模块，并公开一个 FastAPI "
+"``APIRouter``\\ ；\\ ``HTTPAPIRegistry`` 会在启动时自动发现并挂载它——与 :doc:`L2 "
+"adapters </mp/l2_storage/index>` 所采用的零修改模式相同。"
+
+#: ../../source/developer_guide/extending_http_api.rst:12
+msgid "How discovery works"
+msgstr "自动发现机制"
+
+#: ../../source/developer_guide/extending_http_api.rst:14
+msgid ""
+"At startup, ``http_server.py`` hands the FastAPI app to "
+"``HTTPAPIRegistry`` (``lmcache/v1/multiprocess/http_api_registry.py``), "
+"which scans the ``http_apis/`` directory with ``pkgutil``, imports every "
+"module whose name ends with ``_api``, and includes any module-level "
+"``router``. The built-in modules follow this pattern:"
+msgstr ""
+"启动时，\\ ``http_server.py`` 将 FastAPI 应用实例传递给 ``HTTPAPIRegistry``\\ （\\ "
+"``lmcache/v1/multiprocess/http_api_registry.py``\\ ）。该注册器使用 ``pkgutil`` "
+"扫描 ``http_apis/`` 目录，导入所有名称以 ``_api`` 结尾的模块，并将其中定义的模块级 ``router`` "
+"注册到应用中。内置模块均遵循此模式："
+
+#: ../../source/developer_guide/extending_http_api.rst:24
+msgid "Module"
+msgstr "模块"
+
+#: ../../source/developer_guide/extending_http_api.rst:25
+msgid "Endpoint"
+msgstr "端点"
+
+#: ../../source/developer_guide/extending_http_api.rst:26
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/developer_guide/extending_http_api.rst:27
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/developer_guide/extending_http_api.rst:28
+#: ../../source/developer_guide/extending_http_api.rst:32
+#: ../../source/developer_guide/extending_http_api.rst:40
+msgid "``info_api.py``"
+msgstr "``info_api.py``"
+
+#: ../../source/developer_guide/extending_http_api.rst:29
+msgid "``/``"
+msgstr "``/``"
+
+#: ../../source/developer_guide/extending_http_api.rst:30
+#: ../../source/developer_guide/extending_http_api.rst:34
+#: ../../source/developer_guide/extending_http_api.rst:42
+msgid "GET"
+msgstr "GET"
+
+#: ../../source/developer_guide/extending_http_api.rst:31
+msgid "Basic liveness check"
+msgstr "基本存活检查"
+
+#: ../../source/developer_guide/extending_http_api.rst:33
+msgid "``/healthcheck``"
+msgstr "``/healthcheck``"
+
+#: ../../source/developer_guide/extending_http_api.rst:35
+msgid "Kubernetes probe endpoint"
+msgstr "Kubernetes 探针端点"
+
+#: ../../source/developer_guide/extending_http_api.rst:36
+msgid "``cache_api.py``"
+msgstr "``cache_api.py``"
+
+#: ../../source/developer_guide/extending_http_api.rst:37
+msgid "``/cache/clear``"
+msgstr "``/cache/clear``"
+
+#: ../../source/developer_guide/extending_http_api.rst:38
+msgid "POST"
+msgstr "POST"
+
+#: ../../source/developer_guide/extending_http_api.rst:39
+msgid "Force-clear the L1 cache"
+msgstr "强制清除 L1 缓存"
+
+#: ../../source/developer_guide/extending_http_api.rst:41
+msgid "``/status``"
+msgstr "``/status``"
+
+#: ../../source/developer_guide/extending_http_api.rst:43
+msgid "Internal status report"
+msgstr "内部状态报告"
+
+#: ../../source/developer_guide/extending_http_api.rst:46
+msgid "Adding an endpoint"
+msgstr "添加端点"
+
+#: ../../source/developer_guide/extending_http_api.rst:48
+msgid ""
+"Create a file in ``lmcache/v1/multiprocess/http_apis/`` whose name ends "
+"with ``_api.py`` and expose a ``router``:"
+msgstr ""
+"在 ``lmcache/v1/multiprocess/http_apis/`` 中创建一个文件，文件名以 ``_api.py`` "
+"结尾，并公开一个 ``router``\\ ："
+
+#: ../../source/developer_guide/extending_http_api.rst:72
+msgid ""
+"That's it -- ``HTTPAPIRegistry`` discovers and mounts it on the next "
+"server startup; no other file needs to change."
+msgstr "就这些 —— ``HTTPAPIRegistry`` 会在下次服务器启动时自动发现并挂载该模块，无需修改其他文件。"
+
+#: ../../source/developer_guide/extending_http_api.rst:76
+msgid "Module contract"
+msgstr "模块契约"
+
+#: ../../source/developer_guide/extending_http_api.rst:78
+msgid "An API module **must**:"
+msgstr "API 模块 **必须**\\ ："
+
+#: ../../source/developer_guide/extending_http_api.rst:80
+msgid ""
+"live in ``lmcache/v1/multiprocess/http_apis/`` with a filename ending in "
+"``_api.py``;"
+msgstr "位于 ``lmcache/v1/multiprocess/http_apis/`` 目录下，文件名以 ``_api.py`` 结尾；"
+
+#: ../../source/developer_guide/extending_http_api.rst:82
+msgid "expose a module-level ``router`` of type ``fastapi.APIRouter``."
+msgstr "公开一个模块级的 ``router``\\ ，类型为 ``fastapi.APIRouter``\\ 。"
+
+#: ../../source/developer_guide/extending_http_api.rst:84
+msgid "An API module **should**:"
+msgstr "API 模块 **应该**\\ ："
+
+#: ../../source/developer_guide/extending_http_api.rst:86
+msgid ""
+"guard against uninitialized state by checking "
+"``request.app.state.engine`` and returning ``503`` when it is ``None``;"
+msgstr ""
+"通过检查 ``request.app.state.engine`` 防范引擎未初始化的情况，并在其为 ``None`` 时返回 ``503``\\"
+" ；"
+
+#: ../../source/developer_guide/extending_http_api.rst:88
+msgid "use ``lmcache.logging.init_logger(__name__)`` for logging;"
+msgstr "使用 ``lmcache.logging.init_logger(__name__)`` 进行日志记录；"
+
+#: ../../source/developer_guide/extending_http_api.rst:89
+msgid "use ``async`` handlers and avoid blocking I/O."
+msgstr "使用 ``async`` 处理函数，避免阻塞式 I/O。"
+
+#: ../../source/developer_guide/extending_http_api.rst:91
+msgid ""
+"An API module **must not** import or mutate the ``app`` object from "
+"``http_server.py``."
+msgstr "API 模块 **不得** 导入或修改 ``http_server.py`` 中的 ``app`` 对象。"
+
+#: ../../source/developer_guide/extending_http_api.rst:95
+msgid "Accessing shared state"
+msgstr "访问共享状态"
+
+#: ../../source/developer_guide/extending_http_api.rst:97
+msgid ""
+"``app.state`` is the shared context populated during server startup. "
+"Reach it through the request object:"
+msgstr "``app.state`` 是服务器启动时填充的共享上下文，可通过请求对象访问："
+
+#: ../../source/developer_guide/extending_http_api.rst:108
+msgid ""
+"For the full design rationale see "
+"``docs/design/v1/multiprocess/http_api_extension.md`` in the source tree."
+msgstr "完整的设计说明请参见源码树中的 ``docs/design/v1/multiprocess/http_api_extension.md``\\ 。"
+
+#~ msgid "``healthcheck_api.py``"
+#~ msgstr "``healthcheck_api.py``"
+
+#~ msgid "``/clear-cache``"
+#~ msgstr "``/clear-cache``"
+
+#~ msgid "``status_api.py``"
+#~ msgstr "``status_api.py``"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/native_connectors.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/native_connectors.po
new file mode 100644
index 0000000..1d7b014
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/native_connectors.po
@@ -0,0 +1,786 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:2
+msgid "Adding Native Backends"
+msgstr "添加原生后端"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:7
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:9
+msgid ""
+"Native connectors are high-performance C++ storage backends that "
+"integrate with LMCache through pybind11. They work in **both** LMCache "
+"operating modes:"
+msgstr "原生连接器是高性能的 C++ 存储后端，通过 pybind11 与 LMCache 集成。它们在 **两种** LMCache 运行模式下均可工作："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:12
+msgid ""
+"**Non-MP mode** (single process): via ``ConnectorClientBase`` (asyncio "
+"integration)"
+msgstr "**非 MP 模式**\\ （单进程）：通过 ``ConnectorClientBase``\\ （asyncio 集成）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:13
+msgid ""
+"**MP mode** (multiprocess): via ``NativeConnectorL2Adapter`` (L2 adapter "
+"interface)"
+msgstr "**MP 模式**\\ （多进程）：通过 ``NativeConnectorL2Adapter``\\ （L2 适配器接口）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:15
+msgid "Write the connector once, get both modes for free."
+msgstr "连接器只需编写一次，即可同时支持两种模式。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:17
+msgid ""
+"The framework lives in ``csrc/storage_backends/`` with the Redis RESP "
+"connector as the reference implementation."
+msgstr "该框架位于 ``csrc/storage_backends/``\\ ，Redis RESP 连接器作为参考实现。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:21
+msgid "Architecture"
+msgstr "架构"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:41
+msgid "**Design principles:**"
+msgstr "**设计原则：**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:43
+msgid ""
+"**GIL release** at the pybind layer for true concurrency between native "
+"threads"
+msgstr "**在 pybind 层释放 GIL，实现原生线程间的真正并发**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:44
+msgid ""
+"**Batching with tiling**: work for a batched request is split evenly "
+"among threads"
+msgstr "**批处理与分片**\\ ：批量请求的工作量在各线程间均匀分配"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:45
+msgid "**eventfd-based completions**: the kernel wakes Python -- no polling"
+msgstr "**基于 eventfd 的完成**\\ ：内核唤醒 Python -- 无需轮询"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:46
+msgid ""
+"**Non-blocking submission**: submission queue / completion queue "
+"architecture"
+msgstr "**非阻塞提交**\\ ：提交队列 / 完成队列架构"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:50
+msgid "Step 1: C++ Connector"
+msgstr "步骤 1：C++ 连接器"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:52
+msgid ""
+"Create your connector directory (e.g., "
+"``csrc/storage_backends/mybackend/``) and inherit from "
+"``ConnectorBase<YourConnectionType>``. You need to override 4 required "
+"methods (and optionally ``do_single_delete`` to support eviction)."
+msgstr "创建您的连接器目录（例如，\\ ``csrc/storage_backends/mybackend/``\\ ），并从 ``ConnectorBase<YourConnectionType>`` 继承。您需要重写 4 个必需的方法（并可选地重写 ``do_single_delete`` 以支持逐出）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:56
+msgid "**connector.h:**"
+msgstr "**connector.h:**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:127
+msgid "**What ConnectorBase gives you for free:**"
+msgstr "**ConnectorBase 开箱即用为您提供的能力：**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:129
+msgid "Worker thread pool with per-thread connections"
+msgstr "工作线程池，每个线程持有独立连接"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:130
+msgid "Submission queue (lock-free enqueue) and completion queue"
+msgstr "提交队列（无锁入队）和完成队列"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:131
+msgid "Automatic tiling: batch operations are split across workers"
+msgstr "自动分片：批量操作拆分到各工作线程"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:132
+msgid "eventfd signaling on completion (kernel wakes Python)"
+msgstr "完成时的 eventfd 信号（内核唤醒 Python）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:133
+msgid "Graceful shutdown (stop flag, drain, join)"
+msgstr "优雅关闭（设置停止标志、排空队列、join 线程）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:136
+msgid ""
+"Always call ``start_workers()`` at the **end** of your derived "
+"constructor, after all member variables are initialized. Worker threads "
+"call ``create_connection()`` immediately, so the object must be fully "
+"constructed."
+msgstr "始终在派生构造函数的\\ **末尾**\\ 调用 ``start_workers()``\\ ，在所有成员变量初始化之后。工作线程会立即调用 ``create_connection()``\\ ，因此对象必须完全构造。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:140
+msgid ""
+"**Reference:** ``csrc/storage_backends/redis/connector.h`` and "
+"``connector.cpp``"
+msgstr "**参考:** ``csrc/storage_backends/redis/connector.h`` 和 ``connector.cpp``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:144
+msgid "Step 2: Pybind Module"
+msgstr "步骤 2：Pybind 模块"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:146
+msgid ""
+"Use the ``LMCACHE_BIND_CONNECTOR_METHODS`` macro, which binds all 7 "
+"methods (``event_fd``, ``submit_batch_get/set/exists/delete``, "
+"``drain_completions``, ``close``) with proper GIL release and Python "
+"buffer protocol handling."
+msgstr "使用 ``LMCACHE_BIND_CONNECTOR_METHODS`` 宏，该宏绑定所有 7 个方法（\\ ``event_fd``\\ 、\\ ``submit_batch_get/set/exists/delete``\\ 、\\ ``drain_completions``\\ 、\\ ``close``\\ ），并正确处理 GIL 释放和 Python 缓冲区协议。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:168
+msgid "The pybind utilities automatically:"
+msgstr "pybind 工具自动："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:170
+msgid "Extract buffer pointers from Python ``memoryview`` objects under the GIL"
+msgstr "在 GIL 下从 Python ``memoryview`` 对象中提取缓冲区指针"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:171
+msgid "Release the GIL before calling into C++"
+msgstr "在调用 C++ 之前释放 GIL"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:172
+msgid ""
+"Convert C++ ``Completion`` structs to Python tuples ``(future_id, ok, "
+"error, result_bools)``"
+msgstr ""
+"将 C++ ``Completion`` 结构转换为 Python 元组 ``(future_id, ok, error, "
+"result_bools)``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:174
+msgid "**Reference:** ``csrc/storage_backends/redis/pybind.cpp``"
+msgstr "**参考:** ``csrc/storage_backends/redis/pybind.cpp``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:178
+msgid "Step 3: Build System"
+msgstr "步骤 3：构建系统"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:180
+msgid ""
+"Register your C++ sources in ``setup.py`` alongside the existing Redis "
+"extension:"
+msgstr "在 ``setup.py`` 中注册您的 C++ 源文件，与现有的 Redis 扩展一起："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:201
+msgid "Then rebuild:"
+msgstr "然后重建："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:209
+msgid "Step 4: Python Client (Non-MP Mode)"
+msgstr "步骤 4：Python 客户端（非 MP 模式）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:211
+msgid ""
+"Inherit from ``ConnectorClientBase`` which provides asyncio event loop "
+"integration, future management, and both sync and async methods."
+msgstr "从 ``ConnectorClientBase`` 继承，该类提供 asyncio 事件循环集成、Future 管理，以及同步和异步方法。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:226
+msgid ""
+"This gives you ``batch_get``, ``batch_set``, ``batch_exists`` (async), "
+"and their synchronous variants, all with automatic eventfd-driven "
+"completion handling."
+msgstr "这为您提供了 ``batch_get``\\ 、\\ ``batch_set``\\ 、\\ ``batch_exists``\\ （异步）及其同步变体，所有这些都具有自动的基于 eventfd 的完成处理。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:229
+msgid ""
+"**Reference:** "
+"``lmcache/v1/storage_backend/native_clients/resp_client.py``"
+msgstr "**参考:** ``lmcache/v1/storage_backend/native_clients/resp_client.py``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:233
+msgid "Step 5: L2 Adapter (MP Mode)"
+msgstr "步骤 5：L2 适配器（MP 模式）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:235
+msgid ""
+"To use your connector as an L2 adapter in MP mode, create a single Python"
+" module that defines the config class, factory function, and self-"
+"registers both. The ``NativeConnectorL2Adapter`` bridge handles all the "
+"complexity (eventfd demuxing, key serialization, locking)."
+msgstr "要将您的连接器用作 MP 模式下的 L2 适配器，请创建一个单独的 Python 模块，该模块定义配置类、工厂函数，并自我注册这两者。\\ ``NativeConnectorL2Adapter`` 桥接处理所有复杂性（eventfd 解复用、键序列化、锁定）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:240
+msgid "Create a new file in the L2 adapters package:"
+msgstr "在 L2 适配器包中创建一个新文件："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:322
+msgid ""
+"The L2 adapter package uses ``pkgutil.iter_modules`` to auto-discover all"
+" modules in ``lmcache/v1/distributed/l2_adapters/``. Simply creating the "
+"file above is sufficient -- no changes to ``__init__.py`` or any other "
+"existing file are needed."
+msgstr ""
+"L2 适配器包使用 ``pkgutil.iter_modules`` 自动发现 "
+"``lmcache/v1/distributed/l2_adapters/`` 中的所有模块。仅仅创建上述文件就足够了——不需要对 "
+"``__init__.py`` 或任何其他现有文件进行更改。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:326
+msgid "**Usage from the command line:**"
+msgstr "**命令行使用：**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:336
+msgid "How NativeConnectorL2Adapter Bridges the Gap"
+msgstr "NativeConnectorL2Adapter 如何弥合差异"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:338
+msgid ""
+"The C++ connector has 1 eventfd and mixed completions. MP mode's "
+"``L2AdapterInterface`` requires 3 separate eventfds and typed results. "
+"The bridge handles this transparently:"
+msgstr ""
+"C++ 连接器有 1 个 eventfd 和混合完成。MP 模式的 ``L2AdapterInterface`` 需要 3 个独立的 "
+"eventfd 和类型化结果。桥接器对此进行了透明处理："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:345
+msgid "L2 Adapter Method"
+msgstr "L2 适配器方法"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:346
+msgid "Native Call"
+msgstr "原生调用"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:347
+msgid "Extra Logic"
+msgstr "额外逻辑"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:348
+msgid "``submit_store_task(keys, objs)``"
+msgstr "``submit_store_task(keys, objs)``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:349
+msgid "``submit_batch_set``"
+msgstr "``submit_batch_set``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:350
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:356
+msgid "ObjectKey to string, MemoryObj to memoryview"
+msgstr "ObjectKey 转换为字符串，MemoryObj 转换为 memoryview"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:351
+msgid "``submit_lookup_and_lock_task(keys)``"
+msgstr "``submit_lookup_and_lock_task(keys)``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:352
+msgid "``submit_batch_exists``"
+msgstr "``submit_batch_exists``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:353
+msgid "client-side lock refcount"
+msgstr "客户端锁引用计数"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:354
+msgid "``submit_load_task(keys, objs)``"
+msgstr "``submit_load_task(keys, objs)``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:355
+msgid "``submit_batch_get``"
+msgstr "``submit_batch_get``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:357
+msgid "``submit_unlock(keys)``"
+msgstr "``submit_unlock(keys)``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:358
+msgid "*(none)*"
+msgstr "(无)"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:359
+msgid "client-side lock decrement"
+msgstr "客户端锁减少"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:360
+msgid "``pop_completed_store_tasks()``"
+msgstr "``pop_completed_store_tasks()``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:361
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:364
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:367
+msgid "via ``drain_completions``"
+msgstr "通过 ``drain_completions``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:362
+msgid "demux by op type"
+msgstr "按操作类型解复用"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:363
+msgid "``query_lookup_and_lock_result()``"
+msgstr "``query_lookup_and_lock_result()``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:365
+msgid "exists results to Bitmap, apply locks"
+msgstr "存在结果到位图，应用锁定"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:366
+msgid "``query_load_result()``"
+msgstr "``query_load_result()``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:368
+msgid "ok/fail to Bitmap"
+msgstr "成功/失败到位图"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:370
+msgid ""
+"A background demux thread polls the native eventfd, calls "
+"``drain_completions()``, looks up each ``future_id`` to determine its "
+"operation type, routes the result to the correct completion dict, and "
+"signals the corresponding Python eventfd."
+msgstr "一个后台解复用线程轮询原生 eventfd，调用 ``drain_completions()``\\ ，查找每个 ``future_id`` 以确定其操作类型，将结果路由到正确的完成字典，并发出相应的 Python eventfd 信号。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:376
+msgid "Third-Party Native Connector Plugins (``native_plugin``)"
+msgstr "第三方原生连接器插件（\\ ``native_plugin``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:380
+msgid ""
+"The steps above describe how to add a native connector **inside** the "
+"LMCache source tree. If you want to ship a connector as a **separate, "
+"pip-installable package** (e.g. a proprietary storage backend), use the "
+"``native_plugin`` L2 adapter type instead. It dynamically loads your "
+"connector at runtime -- no LMCache source modifications required."
+msgstr "上述步骤描述了如何在 LMCache 源代码树中\\ **内部**\\ 添加一个原生连接器。如果您想将连接器作为\\ **单独的、可通过 pip 安装的包**\\ （例如，专有存储后端）进行发布，请改用 ``native_plugin`` L2 适配器类型。它在运行时动态加载您的连接器——无需修改 LMCache 源代码。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:386
+msgid "How It Works"
+msgstr "它是如何工作的"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:388
+msgid ""
+"The ``native_plugin`` adapter type loads a third-party **connector "
+"object** (pybind-wrapped C++ or pure Python) and wraps it with the built-"
+"in ``NativeConnectorL2Adapter`` bridge. This means you only need to "
+"implement the 6 connector methods -- the Python-side demux/lock bridging "
+"logic is reused from LMCache."
+msgstr "``native_plugin`` 适配器类型加载一个第三方 **连接器对象**\\ （pybind 封装的 C++ 或纯 Python），并用内置的 ``NativeConnectorL2Adapter`` 桥接器将其包装。这意味着您只需实现 6 个连接器方法——Python 端的解复用/锁定桥接逻辑是从 LMCache 重用的。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:393
+msgid "``plugin`` vs ``native_plugin``"
+msgstr "``plugin`` 与 ``native_plugin``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:397
+msgid "Aspect"
+msgstr "方面"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:398
+msgid "``plugin``"
+msgstr "``plugin``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:399
+msgid "``native_plugin``"
+msgstr "``native_plugin``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:400
+msgid "What is loaded"
+msgstr "加载内容"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:401
+msgid "A full ``L2AdapterInterface`` subclass"
+msgstr "一个完整的 ``L2AdapterInterface`` 子类"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:402
+msgid "A **connector** object (lower level)"
+msgstr "一个 **连接器** 对象（较低级别）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:403
+msgid "Bridging logic"
+msgstr "桥接逻辑"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:404
+msgid "Provided by the plugin itself"
+msgstr "由插件本身提供"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:405
+msgid "Reused from ``NativeConnectorL2Adapter``"
+msgstr "从 ``NativeConnectorL2Adapter`` 重用"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:406
+msgid "Third-party effort"
+msgstr "第三方工作量"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:407
+msgid "Must implement all abstract methods + 3 eventfds"
+msgstr "必须实现所有抽象方法 + 3 个 eventfds"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:408
+msgid "Only 6 connector methods"
+msgstr "仅需 6 个连接器方法"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:411
+msgid "Required Connector Interface"
+msgstr "必需的连接器接口"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:413
+msgid ""
+"The dynamically loaded connector instance must expose the following "
+"methods (identical to the pybind ``LMCACHE_BIND_CONNECTOR_METHODS`` "
+"contract):"
+msgstr "动态加载的连接器实例必须暴露以下方法（与 pybind ``LMCACHE_BIND_CONNECTOR_METHODS`` 的契约一致）："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:443
+msgid ""
+"The factory validates the first 6 methods at creation time and raises "
+"``TypeError`` if any are missing. ``submit_batch_delete`` is **optional**"
+" -- if absent, the adapter's ``delete()`` method will be a no-op "
+"(eviction will not remove keys from the backend)."
+msgstr "工厂在创建时验证前 6 个方法，如果缺少任何方法则引发 ``TypeError``\\ 。\\ ``submit_batch_delete`` 是 **可选** 的——如果缺失，适配器的 ``delete()`` 方法将不执行任何操作（逐出不会从后端移除键）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:448
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:462
+msgid "``NativePluginL2AdapterConfig`` fields"
+msgstr "``NativePluginL2AdapterConfig`` 字段"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:466
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:467
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:468
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:469
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:470
+msgid "``module_path``"
+msgstr "``module_path``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:471
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:475
+msgid "``str``"
+msgstr "``str``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:472
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:476
+msgid "yes"
+msgstr "是"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:473
+msgid "Dotted Python import path of the module containing the connector class."
+msgstr "连接器类所在模块的点分 Python 导入路径。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:474
+msgid "``class_name``"
+msgstr "``class_name``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:477
+msgid "Name of the connector class inside ``module_path``."
+msgstr "``module_path`` 中连接器类的名称。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:478
+msgid "``adapter_params``"
+msgstr "``adapter_params``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:479
+msgid "``dict``"
+msgstr "``dict``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:480
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:484
+msgid "no"
+msgstr "不"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:481
+msgid "Forwarded as ``**kwargs`` to the connector class constructor."
+msgstr "作为 ``**kwargs`` 转发给连接器类构造函数。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:482
+msgid "``max_capacity_gb``"
+msgstr "``max_capacity_gb``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:483
+msgid "``float``"
+msgstr "``float``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:485
+msgid ""
+"Maximum L2 storage capacity in GB for client-side usage tracking. "
+"Required for L2 eviction. Default 0 (disabled)."
+msgstr "客户端使用跟踪的最大 L2 存储容量（以 GB 为单位）。这是 L2 逐出的必要条件。默认值为 0（禁用）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:488
+msgid "Loading Flow"
+msgstr "加载流程"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:510
+msgid "Step-by-Step: Building an External Native Connector Plugin"
+msgstr "逐步：构建外部原生连接器插件"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:512
+msgid ""
+"**Create a Python package** with a C++ pybind11 extension that inherits "
+"from ``ConnectorBase<T>`` (same base class as built-in connectors)."
+msgstr "**创建一个 Python 包**\\ ，其中包含一个继承自 ``ConnectorBase<T>`` 的 C++ pybind11 扩展（与内置连接器相同的基类）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:515
+msgid "Project layout:"
+msgstr "项目布局："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:531
+msgid ""
+"**Implement the C++ connector** inheriting from ``ConnectorBase<T>`` and "
+"override the 4 required methods (``create_connection``, "
+"``do_single_get``, ``do_single_set``, ``do_single_exists``) and "
+"optionally ``do_single_delete`` for eviction support."
+msgstr "**实现 C++ 连接器**\\ ，继承自 ``ConnectorBase<T>``\\ ，并重写 4 个必需的方法（\\ ``create_connection``\\ 、\\ ``do_single_get``\\ 、\\ ``do_single_set``\\ 、\\ ``do_single_exists``\\ ），可选地重写 ``do_single_delete`` 以支持逐出。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:535
+msgid ""
+"**Create pybind11 bindings** using the ``LMCACHE_BIND_CONNECTOR_METHODS``"
+" macro:"
+msgstr "**使用 ``LMCACHE_BIND_CONNECTOR_METHODS`` 宏创建 pybind11 绑定：**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:553
+msgid ""
+"**Write a Python factory class** that selects the backend and returns the"
+" native connector instance:"
+msgstr "**编写一个 Python 工厂类**\\ ，选择后端并返回原生连接器实例："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:568
+msgid "**Build and install** the package:"
+msgstr "**构建和安装** 包："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:575
+msgid "**Configure LMCache** to use it:"
+msgstr "**配置 LMCache** 以使用它："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:590
+msgid "Reference Implementation"
+msgstr "参考实现"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:592
+msgid ""
+"See ``examples/lmc_external_native_connector/`` for a complete, pip-"
+"installable example connector plugin that demonstrates:"
+msgstr ""
+"请参阅 ``examples/lmc_external_native_connector/`` 以获取完整的、可通过 pip "
+"安装的示例连接器插件，该插件演示了："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:595
+msgid ""
+"C++ pybind11-wrapped connectors inheriting from ``ConnectorBase<T>`` "
+"(same as built-in Redis/FS)."
+msgstr "从 ``ConnectorBase<T>`` 继承的 C++ pybind11 封装连接器（与内置的 Redis/FS 相同）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:597
+msgid ""
+"Two backends: filesystem (``ExampleFSConnector``) and in-memory "
+"(``ExampleMemoryConnector``), both in C++."
+msgstr "两个后端：文件系统（\\ ``ExampleFSConnector``\\ ）和内存（\\ ``ExampleMemoryConnector``\\ ），均为 C++ 实现。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:599
+msgid ""
+"A thin Python factory class (``ExampleNativeConnector``) that selects the"
+" backend via a ``\"backend\"`` parameter."
+msgstr "一个轻量级 Python 工厂类（\\ ``ExampleNativeConnector``\\ ），通过 ``\"backend\"`` 参数选择后端。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:601
+msgid ""
+"Worker thread pool with eventfd notification (inherited from "
+"``ConnectorBase``)."
+msgstr "带有 eventfd 通知的工作线程池（继承自 ``ConnectorBase``\\ ）。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:602
+msgid "Build via ``pip install -e .`` using pybind11 + setuptools."
+msgstr "通过 ``pip install -e .`` 使用 pybind11 + setuptools 构建。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:606
+msgid "Checklist"
+msgstr "清单"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:608
+msgid "Use this checklist when adding a new native connector:"
+msgstr "在添加新的原生连接器时，请使用此检查清单："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:610
+msgid ""
+"C++ connector inheriting ``ConnectorBase<T>`` with 4 required + 1 "
+"optional (``do_single_delete``) method overrides"
+msgstr "继承 ``ConnectorBase<T>`` 的 C++ 连接器，具有 4 个必需的方法重写和 1 个可选的方法重写（\\ ``do_single_delete``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:611
+msgid "Pybind module using ``LMCACHE_BIND_CONNECTOR_METHODS``"
+msgstr "使用 ``LMCACHE_BIND_CONNECTOR_METHODS`` 的 Pybind 模块"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:612
+msgid "``setup.py`` entry for the new ``CppExtension``"
+msgstr "``setup.py`` 中用于新的 ``CppExtension`` 的条目"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:613
+msgid "Python client inheriting ``ConnectorClientBase`` (non-MP mode)"
+msgstr "继承 ``ConnectorClientBase`` 的 Python 客户端（非 MP 模式）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:614
+msgid "L2 adapter module with config class + factory self-registration (MP mode)"
+msgstr "带有配置类和工厂自注册的 L2 适配器模块（多进程模式）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:615
+msgid ""
+"Unit tests (see "
+"``tests/v1/distributed/test_native_connector_l2_adapter.py``)"
+msgstr "单元测试（请参见 ``tests/v1/distributed/test_native_connector_l2_adapter.py``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:616
+msgid "Rebuild with ``pip install -e .`` and verify both modes work"
+msgstr "使用 ``pip install -e .`` 重新构建并验证两种模式均正常工作"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:618
+msgid "For **external** native connector plugins (``native_plugin``):"
+msgstr "对于 **外部** 原生连接器插件 (``native_plugin``)："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:620
+msgid "Separate pip-installable package with C++ pybind11 extension"
+msgstr "带有 C++ pybind11 扩展的独立 pip 可安装包"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:621
+msgid ""
+"Connector class exposing the 6 required methods (+ optional "
+"``submit_batch_delete`` for eviction)"
+msgstr "连接器类，暴露 6 个必需的方法（+ 可选的 ``submit_batch_delete`` 用于逐出）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:622
+msgid "Python factory class for backend selection"
+msgstr "后端选择的 Python 工厂类"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:623
+msgid "``pip install -e .`` and configure via ``--l2-adapter`` JSON"
+msgstr "``pip install -e .`` 并通过 ``--l2-adapter`` JSON 进行配置"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:624
+msgid "Unit tests (see ``examples/lmc_external_native_connector/tests/``)"
+msgstr "单元测试（参见 ``examples/lmc_external_native_connector/tests/``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:628
+msgid "Built-in Aerospike backend (optional)"
+msgstr "内置的 Aerospike 后端（可选）"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:630
+msgid ""
+"LMCache ships an optional in-tree Aerospike native connector (same "
+"``ConnectorBase`` harness as Redis). It is compiled only when "
+"``BUILD_AEROSPIKE=1`` or ``AEROSPIKE_INCLUDE_DIR`` is set during ``pip "
+"install -e .``."
+msgstr "LMCache 提供一个可选的内置 Aerospike 原生连接器（与 Redis 使用相同的 ``ConnectorBase`` 框架）。仅当在 ``pip install -e .`` 时设置 ``BUILD_AEROSPIKE=1`` 或 ``AEROSPIKE_INCLUDE_DIR`` 时，它才会被编译。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:635
+msgid "**Build:**"
+msgstr "**构建：**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:643
+msgid ""
+"The ``aerospike-client-c.env`` file simply points the build at the C "
+"client headers and shared libraries you unpacked into ``.deps/``. Adjust "
+"the paths to match where the client was installed. Example:"
+msgstr "``aerospike-client-c.env`` 文件仅仅指向您解压到 ``.deps/`` 中的 C 客户端头文件和共享库。请调整路径以匹配客户端的安装位置。示例："
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:656
+msgid ""
+"Setting ``AEROSPIKE_INCLUDE_DIR`` is enough to enable the extension, so "
+"``BUILD_AEROSPIKE=1`` is optional once the env file is sourced. Multiple "
+"include or library directories can be passed as ``;``-separated lists."
+msgstr "设置 ``AEROSPIKE_INCLUDE_DIR`` 足以启用扩展，因此一旦加载了环境文件，\\ ``BUILD_AEROSPIKE=1`` 是可选的。可以将多个包含或库目录作为 ``;`` 分隔的列表传递。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:660
+msgid "**MP mode:**"
+msgstr "**MP 模式:**"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:666
+msgid ""
+"Implementation: ``csrc/storage_backends/aerospike/``, "
+"``lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py``."
+msgstr "实现：\\ ``csrc/storage_backends/aerospike/``, ``lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py``\\ 。"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:671
+msgid "Additional Resources"
+msgstr "附加资源"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:673
+msgid "Framework source: ``csrc/storage_backends/``"
+msgstr "框架源代码：\\ ``csrc/storage_backends/``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:674
+msgid "``ConnectorBase`` template: ``csrc/storage_backends/connector_base.h``"
+msgstr "``ConnectorBase`` 模板: ``csrc/storage_backends/connector_base.h``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:675
+msgid ""
+"``IStorageConnector`` interface: "
+"``csrc/storage_backends/connector_interface.h``"
+msgstr "``IStorageConnector`` 接口: ``csrc/storage_backends/connector_interface.h``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:676
+msgid "Pybind utilities: ``csrc/storage_backends/connector_pybind_utils.h``"
+msgstr "Pybind 工具: ``csrc/storage_backends/connector_pybind_utils.h``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:677
+msgid "Redis reference implementation: ``csrc/storage_backends/redis/``"
+msgstr "Redis 参考实现: ``csrc/storage_backends/redis/``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:678
+msgid "Aerospike implementation (optional): ``csrc/storage_backends/aerospike/``"
+msgstr "Aerospike 实现（可选）：\\ ``csrc/storage_backends/aerospike/``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:679
+msgid "Architecture README: ``csrc/storage_backends/README.md``"
+msgstr "架构自述文件: ``csrc/storage_backends/README.md``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:680
+msgid ""
+"External native connector example: "
+"``examples/lmc_external_native_connector/``"
+msgstr "外部原生连接器示例：\\ ``examples/lmc_external_native_connector/``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:682
+msgid ""
+"Native plugin adapter source: "
+"``lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py``"
+msgstr ""
+"原生插件适配器源: "
+"``lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:684
+msgid ""
+"Design document: "
+"``lmcache/v1/distributed/l2_adapters/design_docs/plugin.md``"
+msgstr "设计文档：\\ ``lmcache/v1/distributed/l2_adapters/design_docs/plugin.md``"
+
+#: ../../source/developer_guide/extending_lmcache/native_connectors.rst:686
+msgid ""
+"RESP backend user guide: :doc:`RESP (Native Redis/Valkey) "
+"<../../kv_cache/storage_backends/resp>`"
+msgstr ""
+"RESP 后端用户指南： :doc:`RESP (原生 Redis/Valkey) "
+"<../../kv_cache/storage_backends/resp>`"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/remote_storage_plugins.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/remote_storage_plugins.po
new file mode 100644
index 0000000..7485636
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/remote_storage_plugins.po
@@ -0,0 +1,291 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:2
+msgid "Remote Storage Plugins"
+msgstr "远程存储插件"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:9
+msgid ""
+"LMCache supports built-in remote storage connectors for Redis, "
+"InfiniStore, MooncakeStore, S3, Hugging Face Buckets, and more. The "
+"remote storage plugin system provides the ability to add custom storage "
+"connectors through dynamic loading. This enables extending remote storage"
+" capabilities without modifying core code."
+msgstr ""
+"LMCache 支持内置的远程存储连接器，包括 Redis、InfiniStore、MooncakeStore、S3、Hugging Face "
+"Buckets 等。远程存储插件系统提供了通过动态加载添加自定义存储连接器的能力。这使得在不修改核心代码的情况下扩展远程存储功能成为可能。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:15
+msgid ""
+"The ``remote_url`` configuration is **deprecated** and will be removed in"
+" a future release. Please use ``remote_storage_plugins`` instead."
+msgstr ""
+"``remote_url`` 配置已\\ **弃用**\\ ，并将在未来的版本中移除。请改用 "
+"``remote_storage_plugins``\\ 。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:19
+msgid "Connector Definition Requirements"
+msgstr "连接器定义要求"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:20
+msgid "A custom remote storage connector requires two classes:"
+msgstr "自定义远程存储连接器需要两个类："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:22
+msgid ""
+"**ConnectorAdapter**: Handles URL scheme matching and connector "
+"instantiation"
+msgstr "**ConnectorAdapter**: 处理 URL 方案匹配和连接器实例化"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:24
+msgid "Inherit from ``ConnectorAdapter``"
+msgstr "从 ``ConnectorAdapter`` 继承"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:25
+msgid "Set the URL scheme in the constructor (e.g., ``mystore://``)"
+msgstr "在构造函数中设置 URL 方案（例如，\\ ``mystore://``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:26
+msgid "Implement the ``create_connector`` method"
+msgstr "实现 ``create_connector`` 方法"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:28
+msgid "**RemoteConnector**: Implements the actual storage operations"
+msgstr "**RemoteConnector**: 实现实际的存储操作"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:30
+msgid "Inherit from ``RemoteConnector``"
+msgstr "从 ``RemoteConnector`` 继承"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:31
+msgid ""
+"Implement all abstract methods: ``exists``, ``exists_sync``, ``get``, "
+"``put``, ``list``, ``close``"
+msgstr ""
+"实现所有抽象方法：\\ ``exists``\\ 、\\ ``exists_sync``\\ 、\\ ``get``\\ 、\\ "
+"``put``\\ 、\\ ``list``\\ 、\\ ``close``"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:35
+msgid ""
+"The ``ConnectorAdapter`` constructor receives no arguments from LMCache. "
+"The scheme should be set by calling the parent constructor with the "
+"scheme string."
+msgstr "``ConnectorAdapter`` 构造函数不接收来自 LMCache 的任何参数。应通过调用父构造函数并传入方案字符串来设置方案。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:37
+msgid ""
+"The ``create_connector`` method receives a ``ConnectorContext`` object "
+"containing the URL, event loop, local CPU backend, config, metadata, and "
+"``plugin_name``."
+msgstr ""
+"``create_connector`` 方法接收一个 ``ConnectorContext`` 对象，其中包含 URL、事件循环、本地 CPU "
+"后端、配置、元数据和 ``plugin_name``\\ 。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:40
+msgid "Plugin Naming Convention"
+msgstr "插件命名约定"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:41
+#, python-brace-format
+msgid "Plugin names follow the format ``{type}`` or ``{type}.{instance}``:"
+msgstr "插件名称遵循格式 ``{type}`` 或 ``{type}.{instance}``\\ ："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:43
+#, python-brace-format
+msgid ""
+"``{type}`` — a single instance of that connector type (e.g. ``fs``, "
+"``mooncakestore``)"
+msgstr "``{type}`` — 该连接器类型的单个实例（例如 ``fs``, ``mooncakestore``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:44
+#, python-brace-format
+msgid ""
+"``{type}.{instance}`` — a named instance, allowing **multiple instances "
+"of the same type** (e.g. ``fs.primary``, ``fs.backup``)"
+msgstr ""
+"``{type}.{instance}`` — 一个命名实例，允许 **同类型的多个实例**\\ （例如 ``fs.primary``, "
+"``fs.backup``\\ ）"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:46
+msgid ""
+"The framework extracts the *type* portion (everything before the first "
+"``.``) to locate the matching ``ConnectorAdapter``. The full plugin name "
+"is used as the configuration key prefix."
+msgstr ""
+"框架提取 *type* 部分（在第一个 ``.`` 之前的所有内容）以定位匹配的 ``ConnectorAdapter``\\ "
+"。完整的插件名称用作配置键前缀。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:49
+msgid "Using Built-in Connectors via Plugins"
+msgstr "通过插件使用内置连接器"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:50
+msgid ""
+"Built-in connectors (``fs``, ``mooncakestore``, ``hfbucket``, etc.) can "
+"be used directly via ``remote_storage_plugins`` without specifying "
+"``module_path`` or ``class_name``. Their configuration is placed under "
+"``extra_config``:"
+msgstr ""
+"内置连接器（\\ ``fs``, ``mooncakestore``, ``hfbucket`` 等）可以通过 "
+"``remote_storage_plugins`` 直接使用，而无需指定 ``module_path`` 或 ``class_name``\\ "
+"。它们的配置放在 ``extra_config`` 下："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:63
+msgid "Multiple instances of the same connector type:"
+msgstr "同一连接器类型的多个实例："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:72
+msgid "Mixing different connector types:"
+msgstr "混合不同的连接器类型："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:81
+msgid "Built-in Hugging Face Buckets example:"
+msgstr "内置 Hugging Face Buckets 示例："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:91
+msgid "How to Integrate Custom Remote Storage with LMCache"
+msgstr "如何将自定义远程存储与 LMCache 集成"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:92
+msgid "Install your connector package in the LMCache environment"
+msgstr "在 LMCache 环境中安装您的连接器包"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:93
+msgid ""
+"Add ``remote_storage_plugins`` and its related ``module_path`` and "
+"``class_name`` to the ``extra_config`` section of LMCache configuration "
+"as follows:"
+msgstr ""
+"将 ``remote_storage_plugins`` 及其相关的 ``module_path`` 和 ``class_name`` 添加到 "
+"LMCache 配置的 ``extra_config`` 部分，如下所示："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:105
+msgid "An example configuration for a custom remote storage connector:"
+msgstr "自定义远程存储连接器的示例配置："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:117
+msgid "Multiple instances of a custom connector:"
+msgstr "多个自定义连接器的实例："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:130
+msgid "``remote_url`` is **deprecated**; use ``remote_storage_plugins`` instead"
+msgstr "``remote_url`` 已被 **弃用**\\ ；请改用 ``remote_storage_plugins``\\ 。"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:131
+msgid ""
+"``remote_storage_plugin.<plugin_name>`` uses the full plugin name "
+"(including instance suffix) as the key prefix"
+msgstr "``remote_storage_plugin.<plugin_name>`` 使用完整的插件名称（包括实例后缀）作为键前缀"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:132
+msgid "Multiple remote storage plugins can be loaded simultaneously"
+msgstr "可以同时加载多个远程存储插件"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:133
+msgid "Built-in connectors do not require ``module_path`` / ``class_name``"
+msgstr "内置连接器不需要 ``module_path`` / ``class_name``"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:136
+msgid "ConnectorAdapter Implementation"
+msgstr "连接器适配器实现"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:137
+msgid "The ``ConnectorAdapter`` class is responsible for:"
+msgstr "``ConnectorAdapter`` 类负责："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:139
+msgid "Defining the URL scheme it handles"
+msgstr "定义它处理的 URL 方案"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:140
+msgid "Creating the appropriate ``RemoteConnector`` instance"
+msgstr "创建适当的 ``RemoteConnector`` 实例"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:186
+msgid "RemoteConnector Implementation"
+msgstr "RemoteConnector 实现"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:187
+msgid ""
+"The ``RemoteConnector`` class defines the interface for remote storage "
+"operations. Your implementation must provide the following abstract "
+"methods:"
+msgstr "``RemoteConnector`` 类定义了远程存储操作的接口。您的实现必须提供以下抽象方法："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:234
+msgid "Optional Methods"
+msgstr "可选方法"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:235
+msgid ""
+"The ``RemoteConnector`` base class also provides optional methods that "
+"can be overridden for enhanced functionality:"
+msgstr "``RemoteConnector`` 基类还提供了可选的方法，可以被重写以增强功能："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:237
+msgid "``support_ping()`` / ``ping()``: Health check support"
+msgstr "``support_ping()`` / ``ping()``: 健康检查支持"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:238
+msgid "``support_batched_get()`` / ``batched_get()``: Batch retrieval operations"
+msgstr "``support_batched_get()`` / ``batched_get()``: 批量检索操作"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:239
+msgid "``support_batched_put()`` / ``batched_put()``: Batch storage operations"
+msgstr "``support_batched_put()`` / ``batched_put()``: 批量存储操作"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:240
+msgid ""
+"``support_batched_contains()`` / ``batched_contains()``: Batch existence "
+"checks"
+msgstr "``support_batched_contains()`` / ``batched_contains()``: 批量存在性检查"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:241
+msgid "``remove_sync()``: Synchronous key removal"
+msgstr "``remove_sync()``: 同步键移除"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:244
+msgid "Implementation Example"
+msgstr "实现示例"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:245
+msgid ""
+"A complete remote storage connector implementation would include both the"
+" adapter and connector classes in a single module or package. Here's a "
+"minimal working example structure:"
+msgstr "一个完整的远程存储连接器实现将包括适配器和连接器类在一个模块或包中。以下是一个最小的工作示例结构："
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:254
+msgid "The adapter module (``adapter.py``):"
+msgstr "适配器模块 (``adapter.py``):"
+
+#: ../../source/developer_guide/extending_lmcache/remote_storage_plugins.rst:287
+msgid "Configuration would then reference the adapter:"
+msgstr "配置将引用适配器："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/runtime_plugins.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/runtime_plugins.po
new file mode 100644
index 0000000..14375c0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/runtime_plugins.po
@@ -0,0 +1,185 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:2
+msgid "Runtime Plugins"
+msgstr "运行时插件"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:4
+msgid ""
+"The LMCache runtime plugin system provides the ability to extend "
+"functionality by running custom scripts alongside LMCache processes. "
+"Plugins can be written in Python and Bash for now, and are managed by the"
+" ``RuntimePluginLauncher`` class."
+msgstr "LMCache 运行时插件系统提供了通过在 LMCache 进程旁边运行自定义脚本来扩展功能的能力。目前，插件可以用 Python 和 Bash 编写，并由 ``RuntimePluginLauncher`` 类管理。"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:7
+msgid "Key Use Cases"
+msgstr "关键使用案例"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:8
+msgid "Start metric reporters for centralized monitoring"
+msgstr "启动度量报告器以进行集中监控"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:9
+msgid "Implement log reporters for log collection systems"
+msgstr "实现日志报告器以用于日志收集系统"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:10
+msgid "Report process-level metrics to alerting systems"
+msgstr "将进程级别的指标报告给警报系统"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:11
+msgid "Implement health checks and service discovery"
+msgstr "实现健康检查和服务发现"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:12
+msgid "Custom cache management operations"
+msgstr "自定义缓存管理操作"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:15
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:16
+msgid ""
+"Runtime plugins are configured through environment variables and "
+"configuration files:"
+msgstr "运行时插件通过环境变量和配置文件进行配置："
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:18
+msgid ""
+"Environment Variables: - ``LMCACHE_RUNTIME_PLUGIN_ROLE``: Process role "
+"(e.g., ``SCHEDULER``, ``WORKER``) - ``LMCACHE_RUNTIME_PLUGIN_CONFIG``: "
+"JSON string containing plugin configuration - "
+"``LMCACHE_RUNTIME_PLUGIN_WORKER_ID``: Current worker ID - "
+"``LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT``: Total worker count in cluster"
+msgstr "环境变量： - ``LMCACHE_RUNTIME_PLUGIN_ROLE``\\ ：进程角色（例如，\\ ``SCHEDULER``\\ ，\\ ``WORKER``\\ ） - ``LMCACHE_RUNTIME_PLUGIN_CONFIG``\\ ：包含插件配置的 JSON 字符串 - ``LMCACHE_RUNTIME_PLUGIN_WORKER_ID``\\ ：当前工作线程 ID - ``LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT``\\ ：集群中的总工作线程数"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:24
+msgid "Configuration File (``lmcache.yaml``):"
+msgstr "配置文件 (``lmcache.yaml``):"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:35
+msgid "Runtime Plugin Naming Convention"
+msgstr "运行时插件命名约定"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:36
+msgid "Plugin filenames determine execution targets:"
+msgstr "插件文件名决定执行目标："
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:38
+msgid ""
+"Role-Specific Plugins: - Format: "
+"``<ROLE>[_<WORKER_ID>][_<DESCRIPTION>].<EXTENSION>`` - Examples:"
+msgstr "角色特定插件： - 格式：\\ ``<ROLE>[_<WORKER_ID>][_<DESCRIPTION>].<EXTENSION>`` - 示例："
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:42
+msgid "``scheduler_foo_plugin.py``: Runs only on ``SCHEDULER``"
+msgstr "``scheduler_foo_plugin.py``\\ ：仅在 ``SCHEDULER`` 上运行"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:43
+msgid "``worker_0_test.sh``: Runs only on worker ID 0"
+msgstr "``worker_0_test.sh``: 仅在工作节点 ID 0 上运行"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:44
+msgid "``all_plugin.sh``: Runs on all workers"
+msgstr "``all_plugin.sh``: 在所有工作节点上运行"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:46
+msgid ""
+"Notes: - Role names are case-insensitive - Worker ID must be numeric when"
+" specified - To target a specific worker ID, the filename must have at "
+"least three parts separated by underscores (e.g., "
+"`worker_<ID>_<DESCRIPTION>.ext`). A file named `worker_<DESCRIPTION>.ext`"
+" will run on all workers."
+msgstr "注意：- 角色名称不区分大小写 - 指定时工作节点 ID 必须为数字 - 要针对特定的工作节点 ID，文件名必须至少包含三个由下划线分隔的部分（例如，`worker_<ID>_<DESCRIPTION>.ext`）。名为 `worker_<DESCRIPTION>.ext` 的文件将在所有工作节点上运行。"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:52
+msgid "Execution Model"
+msgstr "执行模型"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:53
+msgid ""
+"**Interpreter Detection**: - Uses shebang line (e.g., "
+"``#!/opt/venv/bin/python``) - Fallback interpreters:"
+msgstr "**解释器检测**\\ ： - 使用 shebang 行（例如，\\ ``#!/opt/venv/bin/python``\\ ） - 备用解释器："
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:57
+msgid "``.py`` → ``python``"
+msgstr "``.py`` → ``python``"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:58
+msgid "``.sh`` → ``bash``"
+msgstr "``.sh`` → ``bash``"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:60
+msgid ""
+"**Output Handling**: - Stdout/stderr captured continuously - Logged with "
+"plugin name prefix"
+msgstr "**输出处理**\\ ：- 持续捕获标准输出/标准错误 - 以插件名称前缀记录"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:64
+msgid ""
+"**Process Management**: - Launched as subprocesses - Terminated when "
+"parent process exits"
+msgstr "**进程管理**\\ ： - 作为子进程启动 - 当父进程退出时终止"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:69
+msgid "Example Runtime Plugins"
+msgstr "示例运行时插件"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:70
+msgid "Python Plugin (``scheduler_foo_plugin.py``):"
+msgstr "Python 插件 (``scheduler_foo_plugin.py``):"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:76
+msgid "Bash Plugin (``all_plugin.sh``):"
+msgstr "Bash 插件 (``all_plugin.sh``):"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:83
+msgid "Best Practices"
+msgstr "最佳实践"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:84
+msgid "Keep runtime plugins lightweight and efficient"
+msgstr "保持运行时插件轻量和高效"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:85
+msgid "Use descriptive naming conventions"
+msgstr "使用描述性命名约定"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:86
+msgid "Implement graceful error handling"
+msgstr "实现优雅的错误处理"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:87
+msgid "Include shebang for portability"
+msgstr "包含 shebang 以提高可移植性"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:88
+msgid "Validate configuration inputs"
+msgstr "验证配置输入"
+
+#: ../../source/developer_guide/extending_lmcache/runtime_plugins.rst:89
+msgid "Add timeout mechanisms for long operations"
+msgstr "为长时间操作添加超时机制"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/storage_plugins.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/storage_plugins.po
new file mode 100644
index 0000000..7c65110
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/extending_lmcache/storage_plugins.po
@@ -0,0 +1,379 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:2
+msgid "Storage Plugins"
+msgstr "存储插件"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:4
+msgid ""
+"LMCache supports out of the box storage backends like Mooncake, S3 and "
+"NIXL. The LMCache storage plugin system provides the ability to add "
+"custom storage backends through dynamic loading or plug and play "
+"capability. In other words, extending cache storage capabilities without "
+"modifying core code."
+msgstr "LMCache 支持开箱即用的存储后端，如 Mooncake、S3 和 NIXL。LMCache 存储插件系统提供通过动态加载或即插即用能力添加自定义存储后端的功能。换句话说，可以在不修改核心代码的情况下扩展缓存存储能力。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:8
+msgid "Backend Definition Requirements"
+msgstr "后端定义要求"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:9
+msgid "Inherit from ``StoragePluginInterface``"
+msgstr "继承自 ``StoragePluginInterface``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:10
+msgid ""
+"Implement all the abstract methods of the parent interface of "
+"``StoragePluginInterface``- ``StorageBackendInterface``"
+msgstr "实现 ``StoragePluginInterface`` 的父接口 ``StorageBackendInterface`` 的所有抽象方法。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:11
+msgid "Package as an installable Python module"
+msgstr "打包为可安装的 Python 模块"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:15
+msgid ""
+"The interface constructor is the instantiation contract that the LMCache "
+"loading system will use when loading custom storage backends. If you wish"
+" to implement a constructor, it should have the same parameter signature "
+"and call the interface constructor."
+msgstr "接口构造函数是 LMCache 加载系统在加载自定义存储后端时使用的实例化契约。如果您希望实现一个构造函数，它应该具有相同的参数签名并调用接口构造函数。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:19
+msgid "How to Integrate the Backend with LMCache"
+msgstr "如何将后端与 LMCache 集成"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:20
+msgid "Install your backend package in the LMCache environment"
+msgstr "在 LMCache 环境中安装您的后端包"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:21
+msgid ""
+"Add ``storage_plugins`` and its related ``module_path`` and "
+"``class_name`` to ``extra_config`` section of LMCache configuration as "
+"follows:"
+msgstr "将 ``storage_plugins`` 及其相关的 ``module_path`` 和 ``class_name`` 添加到 LMCache 配置的 ``extra_config`` 部分，如下所示："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:33
+msgid "An example configuration for a logging backend is as follows:"
+msgstr "日志后端的示例配置如下："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:47
+msgid ""
+"Storage backends are initialized in order during LMCache startup - "
+"earlier backends have higher priority during cache lookups"
+msgstr "存储后端在 LMCache 启动时按顺序初始化 - 较早的后端在缓存查找中具有更高的优先级"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:48
+msgid ""
+"``storage_plugin.<backend_name>`` distinguishes the different dynamic "
+"loaded backends"
+msgstr "``storage_plugin.<backend_name>`` 区分不同的动态加载后端"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:51
+msgid "Backend Implementation Example"
+msgstr "后端实现示例"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:52
+msgid ""
+"A sample custom backend implementation can be viewed at "
+"https://github.com/opendataio/lmc_external_log_backend/"
+msgstr "可以在 https://github.com/opendataio/lmc_external_log_backend/ 查看一个示例自定义后端实现。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:56
+msgid "MP-Mode L2 Adapter Plugins (``plugin``)"
+msgstr "MP-模式 L2 适配器插件 (``plugin``)"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:60
+msgid ""
+"The storage plugin system described above applies to **non-MP mode** "
+"(single-process). For **MP mode** (multiprocess), LMCache provides the "
+"``plugin`` L2 adapter type, which dynamically loads a third-party "
+"``L2AdapterInterface`` implementation at runtime."
+msgstr "上述描述的存储插件系统适用于 **非 MP 模式**\\ （单进程）。对于 **MP 模式**\\ （多进程），LMCache 提供了 ``plugin`` L2 适配器类型，该类型在运行时动态加载第三方 ``L2AdapterInterface`` 实现。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:65
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:67
+msgid ""
+"The ``plugin`` adapter type lets you ship a full L2 adapter as a "
+"**separate, pip-installable package**. At startup, LMCache imports your "
+"module, instantiates your adapter class, and uses it just like a built-in"
+" adapter -- no LMCache source modifications required."
+msgstr "``plugin`` 适配器类型允许您将完整的 L2 适配器作为 **单独的、可通过 pip 安装的包** 进行发布。在启动时，LMCache 导入您的模块，实例化您的适配器类，并像使用内置适配器一样使用它 -- 无需对 LMCache 源代码进行修改。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:73
+msgid ""
+"If your storage backend is a native C++ connector (pybind-wrapped), "
+"consider using the ``native_plugin`` type instead (see "
+":doc:`native_connectors`). It reuses the built-in bridging logic so you "
+"only need to implement 6 connector methods rather than the full "
+"``L2AdapterInterface``."
+msgstr "如果您的存储后端是一个原生的 C++ 连接器（使用 pybind 封装），请考虑使用 ``native_plugin`` 类型（请参见 :doc:`native_connectors`）。它重用了内置的桥接逻辑，因此您只需实现 6 个连接器方法，而不是完整的 ``L2AdapterInterface``\\ 。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:79
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:93
+msgid "``PluginL2AdapterConfig`` fields"
+msgstr "``PluginL2AdapterConfig`` 字段"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:97
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:98
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:99
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:100
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:101
+msgid "``module_path``"
+msgstr "``module_path``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:102
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:106
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:114
+msgid "``str``"
+msgstr "``str``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:103
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:107
+msgid "yes"
+msgstr "是"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:104
+msgid "Dotted Python import path of the module containing the adapter class."
+msgstr "适配器类所在模块的点分 Python 导入路径。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:105
+msgid "``class_name``"
+msgstr "``class_name``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:108
+msgid ""
+"Name of the class inside ``module_path`` that implements "
+"``L2AdapterInterface``."
+msgstr "``module_path`` 中实现 ``L2AdapterInterface`` 的类的名称。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:109
+msgid "``adapter_params``"
+msgstr "``adapter_params``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:110
+msgid "``dict``"
+msgstr "``dict``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:111
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:115
+msgid "no"
+msgstr "不"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:112
+msgid ""
+"Forwarded to the adapter class constructor (as a typed config or raw "
+"dict)."
+msgstr "转发到适配器类构造函数（作为类型化配置或原始字典）。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:113
+msgid "``config_class_name``"
+msgstr "``config_class_name``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:116
+msgid "Explicit config class name; when omitted the factory auto-discovers it."
+msgstr "显式配置类名称；当省略时，工厂会自动发现它。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:119
+msgid "Config Class Auto-Discovery"
+msgstr "配置类自动发现"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:121
+msgid ""
+"The factory automatically resolves the adapter's config class using the "
+"following priority chain (first match wins):"
+msgstr "工厂会自动使用以下优先级链解析适配器的配置类（第一个匹配的优先）："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:124
+msgid "**Explicit** ``config_class_name`` field in JSON config."
+msgstr "**显式** ``config_class_name`` 字段在 JSON 配置中。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:125
+msgid ""
+"**Convention**: adapter class name + ``\"Config\"`` suffix (e.g. "
+"``MyL2Adapter`` looks for ``MyL2AdapterConfig``)."
+msgstr "**约定**\\ ：适配器类名 + ``\"Config\"`` 后缀（例如 ``MyL2Adapter`` 查找 ``MyL2AdapterConfig``\\ ）。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:127
+msgid ""
+"**Attribute**: ``config_class_name`` attribute on the adapter class "
+"itself."
+msgstr "**属性**: ``config_class_name`` 属性在适配器类本身上。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:128
+msgid "**Fallback**: no config class found -- pass raw ``adapter_params`` dict."
+msgstr "**后备**: 未找到配置类 -- 传递原始 ``adapter_params`` 字典。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:130
+msgid ""
+"Each candidate is looked up in the loaded module and validated as an "
+"``L2AdapterConfigBase`` subclass. This means most plugins that follow the"
+" naming convention will **automatically** receive a typed config instance"
+" without any extra configuration."
+msgstr "每个候选项都会在加载的模块中查找，并验证为 ``L2AdapterConfigBase`` 子类。这意味着大多数遵循命名约定的插件将 **自动** 接收一个类型化的配置实例，而无需任何额外的配置。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:135
+msgid "Plugin Contract"
+msgstr "插件合同"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:137
+msgid "A plugin adapter class **must**:"
+msgstr "插件适配器类 **必须**\\ ："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:139
+msgid ""
+"Subclass ``L2AdapterInterface`` from "
+"``lmcache.v1.distributed.l2_adapters.base``."
+msgstr "从 ``lmcache.v1.distributed.l2_adapters.base`` 子类化 ``L2AdapterInterface``\\ 。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:140
+msgid ""
+"Implement all abstract methods: ``submit_store_task``, "
+"``pop_completed_store_tasks``, ``submit_lookup_and_lock_task``, "
+"``query_lookup_and_lock_result``, ``submit_unlock``, "
+"``submit_load_task``, ``query_load_result``, ``close``, and all three "
+"event-fd getters."
+msgstr "实现所有抽象方法：\\ ``submit_store_task``\\ 、\\ ``pop_completed_store_tasks``\\ 、\\ ``submit_lookup_and_lock_task``\\ 、\\ ``query_lookup_and_lock_result``\\ 、\\ ``submit_unlock``\\ 、\\ ``submit_load_task``\\ 、\\ ``query_load_result``\\ 、\\ ``close``\\ ，以及所有三个事件文件描述符获取器。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:143
+msgid ""
+"Provide **three distinct event fds** (store / lookup / load). The "
+"controllers build ``fd -> adapter`` maps; duplicates will misroute "
+"events."
+msgstr "提供 **三个不同的事件 fd**\\ （存储 / 查找 / 加载）。控制器构建 ``fd -> 适配器`` 映射；重复会导致事件错误路由。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:145
+msgid ""
+"Be **thread-safe**: ``StoreController`` and ``PrefetchController`` call "
+"adapter methods from different threads concurrently."
+msgstr "确保 **线程安全**\\ ：\\ ``StoreController`` 和 ``PrefetchController`` 从不同线程并发调用适配器方法。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:147
+msgid "Accept ``**kwargs`` in ``__init__`` to stay forward-compatible."
+msgstr "在\\ ``__init__``\\ 中接受\\ ``**kwargs``\\ 以保持向前兼容。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:149
+msgid "A plugin adapter class **should**:"
+msgstr "插件适配器类 **应该**\\ ："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:151
+msgid ""
+"Create its own asyncio event loop and background thread if it needs async"
+" I/O."
+msgstr "如果需要异步 I/O，则应创建自己的 asyncio 事件循环和后台线程。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:152
+msgid ""
+"Use ``create_event_notifier()`` from ``lmcache.v1.platform`` for the "
+"three event fds (cross-platform: ``os.eventfd`` on Linux, ``os.pipe`` "
+"fallback elsewhere)."
+msgstr "使用 ``lmcache.v1.platform`` 中的 ``create_event_notifier()`` 来处理三个事件文件描述符（跨平台：在 Linux 上使用 ``os.eventfd``\\ ，在其他地方使用 ``os.pipe`` 作为后备）。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:154
+msgid "Clean up all resources (event fds, threads, connections) in ``close()``."
+msgstr "在 ``close()`` 中清理所有资源（事件文件描述符、线程、连接）。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:157
+msgid "Loading Flow"
+msgstr "加载流程"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:190
+msgid "Minimal Example"
+msgstr "最小示例"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:220
+msgid "Launch via CLI:"
+msgstr "通过 CLI 启动："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:232
+msgid "Reference Implementation"
+msgstr "参考实现"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:234
+msgid ""
+"See ``examples/lmc_external_l2_adapter/`` for a complete, pip-installable"
+" example plugin (``InMemoryL2Adapter``) that demonstrates:"
+msgstr "请参阅 ``examples/lmc_external_l2_adapter/`` 以获取完整的、可通过 pip 安装的示例插件 (``InMemoryL2Adapter``)，该插件演示了："
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:237
+msgid "FIFO eviction with configurable capacity."
+msgstr "可配置容量的 FIFO 逐出。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:238
+msgid "Simulated bandwidth delay for realistic testing."
+msgstr "用于现实测试的模拟带宽延迟。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:239
+msgid "Background asyncio event loop with proper shutdown."
+msgstr "后台 asyncio 事件循环及其正确关闭。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:240
+msgid ""
+"Full test suite covering store, lookup, load, batch operations, and "
+"eviction behavior."
+msgstr "全面的测试套件，涵盖存储、查找、加载、批量操作和逐出行为。"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:243
+msgid "Additional Resources"
+msgstr "附加资源"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:245
+msgid ""
+"Plugin adapter source: "
+"``lmcache/v1/distributed/l2_adapters/plugin_l2_adapter.py``"
+msgstr "插件适配器源代码：\\ ``lmcache/v1/distributed/l2_adapters/plugin_l2_adapter.py``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:246
+msgid ""
+"Native plugin adapter: "
+"``lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py``"
+msgstr "原生插件适配器: ``lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:247
+msgid ""
+"Design document: "
+"``lmcache/v1/distributed/l2_adapters/design_docs/plugin.md``"
+msgstr "设计文档：\\ ``lmcache/v1/distributed/l2_adapters/design_docs/plugin.md``"
+
+#: ../../source/developer_guide/extending_lmcache/storage_plugins.rst:248
+msgid "L2 adapter base interface: ``lmcache/v1/distributed/l2_adapters/base.py``"
+msgstr "L2 适配器基础接口: ``lmcache/v1/distributed/l2_adapters/base.py``"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/index.po
new file mode 100644
index 0000000..3f76801
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/index.po
@@ -0,0 +1,31 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/index.rst:2
+msgid "Developer Guide"
+msgstr "开发者指南"
+
+#: ../../source/developer_guide/index.rst:4
+msgid ""
+"How to contribute to LMCache and extend it with new storage backends, CLI"
+" commands, and HTTP endpoints."
+msgstr "如何为 LMCache 贡献代码，并通过新的存储后端、CLI 命令和 HTTP 端点对其进行扩展。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/integration.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/integration.po
new file mode 100644
index 0000000..853ee72
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/integration.po
@@ -0,0 +1,114 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/integration.rst:2
+msgid "Integration"
+msgstr "集成"
+
+#: ../../source/developer_guide/integration.rst:4
+msgid ""
+"LMCache acts as a caching middleware that sits between LLM inference "
+"engines and storage systems, enabling:"
+msgstr "LMCache充当一个缓存中间件，位于LLM推理引擎和存储系统之间，支持："
+
+#: ../../source/developer_guide/integration.rst:6
+msgid ""
+"**Transparent Cache Reuse**: Automatic detection and reuse of previously "
+"computed KV caches"
+msgstr "**透明缓存重用**\\ ：自动检测和重用先前计算的 KV 缓存"
+
+#: ../../source/developer_guide/integration.rst:7
+msgid ""
+"**Performance Optimization**: 3×–10× reduction in time-to-first-token "
+"(TTFT) for multi-round conversation and RAG."
+msgstr "**性能优化**\\ ：在多轮对话和 RAG 中，首次令牌的时间（TTFT）减少 3 倍至 10 倍。"
+
+#: ../../source/developer_guide/integration.rst:8
+msgid "**Resource Efficiency**: Significant GPU cycle savings through cache reuse"
+msgstr "**资源效率**\\ ：通过缓存重用显著节省显存周期"
+
+#: ../../source/developer_guide/integration.rst:9
+msgid ""
+"**Scalable Architecture**: Support for single-node and multi-node "
+"deployments"
+msgstr "**可扩展架构**\\ ：支持单节点和多节点部署"
+
+#: ../../source/developer_guide/integration.rst:12
+msgid "Supported Engines"
+msgstr "支持的引擎"
+
+#: ../../source/developer_guide/integration.rst:14
+msgid "LMCache currently supports integration with:"
+msgstr "LMCache 目前支持与以下内容集成："
+
+#: ../../source/developer_guide/integration.rst:16
+msgid "**vLLM**"
+msgstr "**vLLM**"
+
+#: ../../source/developer_guide/integration.rst:17
+msgid "**SGLang**"
+msgstr "**SGLang**"
+
+#: ../../source/developer_guide/integration.rst:18
+msgid "**TRT-LLM** (coming soon)"
+msgstr "**TRT-LLM**\\ （即将推出）"
+
+#: ../../source/developer_guide/integration.rst:21
+msgid "Integration with vLLM"
+msgstr "与 vLLM 的集成"
+
+#: ../../source/developer_guide/integration.rst:23
+msgid ""
+"When LMCache is integrated with vLLM, the inference pipeline is augmented"
+" to lookup and inject cached KV chunks for any reused input content. The "
+"sequence diagram below shows how a prompt request flows through vLLM with"
+" LMCache:"
+msgstr "当 LMCache 与 vLLM 集成时，推理管道会增强以查找并注入缓存的 KV 块，以便处理任何重复使用的输入内容。下面的序列图展示了提示请求如何通过 vLLM 和 LMCache 流动："
+
+#: ../../source/developer_guide/integration.rst:44
+msgid ""
+"**Cache Lookup**: Upon receiving a new prompt, vLLM (via the LMCache "
+"connector) computes identifiers (e.g. hashes of token sequences) and "
+"queries LMCache for matching KV cache chunks. If a cache hit occurs, "
+"LMCache retrieves the KV chunk (potentially from CPU or disk) and returns"
+" it to vLLM. vLLM then injects these KV tensors into the model's "
+"attention cache instead of recomputing them from scratch."
+msgstr "**缓存查找**\\ ：在接收到新的提示后，vLLM（通过 LMCache 连接器）计算标识符（例如，令牌序列的哈希值）并查询 LMCache 以获取匹配的 KV 缓存块。如果发生缓存命中，LMCache 将检索 KV 块（可能来自 CPU 或磁盘）并将其返回给 vLLM。然后，vLLM 将这些 KV 张量注入到模型的注意力缓存中，而不是从头开始重新计算它们。"
+
+#: ../../source/developer_guide/integration.rst:46
+msgid ""
+"**Inference with Cache**: vLLM proceeds with inference. For any parts of "
+"the prompt where no cache was available (cache miss), the model computes "
+"new KV values as usual. Cached segments (e.g. previously seen text) are "
+"skipped in computation, significantly reducing the time-to-first-token "
+"(TTFT) and saving GPU cycles."
+msgstr "**使用缓存的推理**\\ ：vLLM 继续进行推理。对于没有可用缓存的提示部分（缓存未命中），模型会像往常一样计算新的 KV 值。缓存的片段（例如，之前见过的文本）在计算中被跳过，显著减少了首次令牌时间（TTFT），并节省了显存周期。"
+
+#: ../../source/developer_guide/integration.rst:48
+msgid ""
+"**Async Cache Write**: After processing the prompt, any newly generated "
+"KV cache chunks (corresponding to this prompt's content) are handed off "
+"to LMCache for storage. This put operation is done asynchronously (in the"
+" background) so it doesn't delay the response. The response is returned "
+"to the user promptly, and LMCache's background tasks will offload the new"
+" KV data to CPU, disk, or other backends for future reuse."
+msgstr "**异步缓存写入**\\ ：在处理完提示后，任何新生成的 KV 缓存块（对应于该提示的内容）都被交给 LMCache 进行存储。此放置操作是异步进行的（在后台），因此不会延迟响应。响应会及时返回给用户，而 LMCache 的后台任务将把新的 KV 数据卸载到 CPU、磁盘或其他后端以供将来重用。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/basic_check.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/basic_check.po
new file mode 100644
index 0000000..98241d7
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/basic_check.po
@@ -0,0 +1,218 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/usage/basic_check.rst:2
+msgid "Basic Check Tool"
+msgstr "基本检查工具"
+
+#: ../../source/developer_guide/usage/basic_check.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/developer_guide/usage/basic_check.rst:9
+msgid ""
+"The LMCache Basic Check Tool is a testing and validation utility that "
+"helps you verify your LMCache installation, configuration, and "
+"functionality. It provides multiple testing modes to validate different "
+"components of the LMCache system."
+msgstr ""
+"LMCache 基本检查工具是一个测试和验证工具，帮助您验证 LMCache 的安装、配置和功能。它提供多种测试模式以验证 LMCache "
+"系统的不同组件。"
+
+#: ../../source/developer_guide/usage/basic_check.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/developer_guide/usage/basic_check.rst:14
+msgid "The basic check tool (``lmcache.v1.basic_check``) is designed to:"
+msgstr "基本检查工具（``lmcache.v1.basic_check``）旨在："
+
+#: ../../source/developer_guide/usage/basic_check.rst:16
+msgid "Test remote backend connectivity and functionality"
+msgstr "测试远程后端的连接性和功能性"
+
+#: ../../source/developer_guide/usage/basic_check.rst:17
+msgid "Validate storage manager operations"
+msgstr "验证存储管理器操作"
+
+#: ../../source/developer_guide/usage/basic_check.rst:18
+msgid "Generate test keys for performance testing"
+msgstr "生成用于性能测试的测试键"
+
+#: ../../source/developer_guide/usage/basic_check.rst:19
+msgid "Verify configuration settings"
+msgstr "验证配置设置"
+
+#: ../../source/developer_guide/usage/basic_check.rst:20
+msgid "Provide diagnostic information for troubleshooting"
+msgstr "提供故障排除的诊断信息"
+
+#: ../../source/developer_guide/usage/basic_check.rst:23
+msgid "Available Check Modes"
+msgstr "可用检查模式"
+
+#: ../../source/developer_guide/usage/basic_check.rst:25
+msgid ""
+"The tool supports several check modes, each targeting specific "
+"functionality:"
+msgstr "该工具支持几种检查模式，每种模式针对特定功能："
+
+#: ../../source/developer_guide/usage/basic_check.rst:28
+msgid "test_remote"
+msgstr "test_remote"
+
+#: ../../source/developer_guide/usage/basic_check.rst:30
+msgid "Tests the remote backend functionality including:"
+msgstr "测试远程后端功能，包括："
+
+#: ../../source/developer_guide/usage/basic_check.rst:32
+msgid "Connection establishment to remote backends (fs, etc.)"
+msgstr "与远程后端（文件系统等）的连接建立"
+
+#: ../../source/developer_guide/usage/basic_check.rst:33
+msgid "put/get operations with data integrity validation"
+msgstr "带数据完整性验证的 put/get 操作"
+
+#: ../../source/developer_guide/usage/basic_check.rst:34
+msgid "put/get/exists operations with performance reports"
+msgstr "带性能报告的 put/get/exists 操作"
+
+#: ../../source/developer_guide/usage/basic_check.rst:36
+#: ../../source/developer_guide/usage/basic_check.rst:51
+#: ../../source/developer_guide/usage/basic_check.rst:67
+msgid "**Usage:**"
+msgstr "**用法：**"
+
+#: ../../source/developer_guide/usage/basic_check.rst:43
+msgid "test_storage_manager"
+msgstr "test_storage_manager"
+
+#: ../../source/developer_guide/usage/basic_check.rst:45
+msgid "Tests the storage manager operations including:"
+msgstr "测试存储管理器操作，包括："
+
+#: ../../source/developer_guide/usage/basic_check.rst:47
+msgid "Configuration validation"
+msgstr "配置验证"
+
+#: ../../source/developer_guide/usage/basic_check.rst:48
+msgid "batched_put/get operations with data integrity validation"
+msgstr "带数据完整性验证的批量放入/获取操作"
+
+#: ../../source/developer_guide/usage/basic_check.rst:49
+msgid "batched_put/get/contains operations with performance reports"
+msgstr "带批量放入/获取/包含操作的性能报告"
+
+#: ../../source/developer_guide/usage/basic_check.rst:58
+msgid "gen (Key Generation)"
+msgstr "键生成 (Key Generation)"
+
+#: ../../source/developer_guide/usage/basic_check.rst:60
+msgid "Generates test keys for performance testing and benchmarking:"
+msgstr "生成用于性能测试和基准测试的测试密钥："
+
+#: ../../source/developer_guide/usage/basic_check.rst:62
+msgid "Configurable number of keys and concurrency levels"
+msgstr "可配置的键数量和并发级别"
+
+#: ../../source/developer_guide/usage/basic_check.rst:63
+msgid "Memory-efficient batch processing"
+msgstr "内存高效的批处理"
+
+#: ../../source/developer_guide/usage/basic_check.rst:64
+msgid "Progress tracking and performance metrics"
+msgstr "进度跟踪和性能指标"
+
+#: ../../source/developer_guide/usage/basic_check.rst:65
+msgid "Offset support for distributed testing"
+msgstr "分布式测试的偏移支持"
+
+#: ../../source/developer_guide/usage/basic_check.rst:74
+msgid "Command Line Interface"
+msgstr "命令行接口"
+
+#: ../../source/developer_guide/usage/basic_check.rst:77
+msgid "Basic Usage"
+msgstr "基本用法"
+
+#: ../../source/developer_guide/usage/basic_check.rst:84
+msgid "List Available Modes"
+msgstr "列出可用模式"
+
+#: ../../source/developer_guide/usage/basic_check.rst:91
+msgid "Command Line Options"
+msgstr "命令行选项"
+
+#: ../../source/developer_guide/usage/basic_check.rst:95
+msgid "**Required.** Operation mode to run. Use ``list`` to see available modes."
+msgstr "**必需。** 操作模式。使用 ``list`` 查看可用模式。"
+
+#: ../../source/developer_guide/usage/basic_check.rst:99
+msgid ""
+"Model name for testing, just a part of key of persist kv-cache. Default: "
+"``/lmcache_test_model/``"
+msgstr "用于测试的模型名称，仅为持久 KV Cache 的键的一部分。默认值：``/lmcache_test_model/``"
+
+#: ../../source/developer_guide/usage/basic_check.rst:103
+msgid "Number of keys to generate (gen mode only). Default: 100"
+msgstr "生成的键的数量（仅限生成模式）。默认值：100"
+
+#: ../../source/developer_guide/usage/basic_check.rst:107
+msgid "Concurrency level for operations (gen mode only). Default: 16"
+msgstr "操作的并发级别（仅限生成模式）。默认值：16"
+
+#: ../../source/developer_guide/usage/basic_check.rst:111
+msgid "Offset for key generation (gen mode only). Default: 0"
+msgstr "密钥生成的偏移量（仅限生成模式）。默认值：0"
+
+#: ../../source/developer_guide/usage/basic_check.rst:114
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/developer_guide/usage/basic_check.rst:116
+msgid ""
+"The basic check tool uses your existing LMCache configuration. You can "
+"specify configuration in several ways:"
+msgstr "基本检查工具使用您现有的 LMCache 配置。您可以通过几种方式指定配置："
+
+#: ../../source/developer_guide/usage/basic_check.rst:119
+msgid "Environment Variable"
+msgstr "环境变量"
+
+#: ../../source/developer_guide/usage/basic_check.rst:127
+msgid "Example Configuration"
+msgstr "示例配置"
+
+#: ../../source/developer_guide/usage/basic_check.rst:129
+msgid "Here's an example configuration optimized for basic checks:"
+msgstr "这是一个针对基本检查优化的示例配置："
+
+#: ../../source/developer_guide/usage/basic_check.rst:142
+msgid "Examples"
+msgstr "示例"
+
+#: ../../source/developer_guide/usage/basic_check.rst:144
+msgid "The ``examples/basic_check/`` directory contains comprehensive examples:"
+msgstr "``examples/basic_check/`` 目录包含全面的示例："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/index.po
new file mode 100644
index 0000000..589b6ef
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/index.po
@@ -0,0 +1,25 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/usage/index.rst:2
+msgid "Usage Data Module"
+msgstr "使用数据模块"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/usage_stats_collection.po b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/usage_stats_collection.po
new file mode 100644
index 0000000..59924ef
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/developer_guide/usage/usage_stats_collection.po
@@ -0,0 +1,123 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:4
+msgid "Usage Stats Collection"
+msgstr "使用统计收集"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:6
+msgid ""
+"LMCache collects anonymous usage data by default to help the engineering "
+"team understand real-world workloads, prioritize optimizations, and "
+"improve reliability. All collected data is aggregated and contains no "
+"sensitive user information."
+msgstr "LMCache 默认收集匿名使用数据，以帮助工程团队了解实际工作负载，优先优化并提高可靠性。所有收集的数据都是汇总的，并不包含敏感用户信息。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:8
+msgid ""
+"A sanitized subset of the aggregated data may be publicly released for "
+"the community’s benefit (for example, see a daily usage report `here "
+"<https://github.com/Hanchenli/OSS_Growth_Toolkit/tree/main/usage_tracker/report>`_)."
+msgstr "聚合数据的一个经过清洗的子集可能会公开发布，以惠及社区（例如，查看每日使用报告 `here <https://github.com/Hanchenli/OSS_Growth_Toolkit/tree/main/usage_tracker/report>`_）。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:11
+msgid "What data is collected?"
+msgstr "收集了哪些数据？"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:13
+msgid ""
+"Usage stats are emitted as three message types, implemented in "
+"``usage_context.py``:"
+msgstr "使用统计信息以三种消息类型发出，具体实现位于 ``usage_context.py``\\ ："
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:15
+msgid ""
+"**EnvMessage** Captures environment details such as cloud provider, CPU "
+"info, total memory, architecture, GPU count/type, and execution source."
+msgstr "**EnvMessage** 捕获环境细节，例如云提供商、CPU 信息、总内存、架构、GPU 数量/类型和执行源。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:18
+msgid ""
+"**EngineMessage** Records engine configuration and metadata, including "
+"cache settings (chunk size, local device, cache limits), remote backend "
+"parameters, blending settings, model name, world size, and KV-cache "
+"dtype/shape."
+msgstr "**EngineMessage** 记录引擎配置和元数据，包括缓存设置（块大小、本地设备、缓存限制）、远程后端参数、混合设置、模型名称、全局大小，以及 KV Cache 的数据类型/形状。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:21
+msgid ""
+"**MetadataMessage** Reports execution metadata: the timestamp when the "
+"run started and total duration in seconds."
+msgstr "**MetadataMessage** 报告执行元数据：运行开始的时间戳和总持续时间（以秒为单位）。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:24
+msgid ""
+"These messages are serialized to JSON and POSTed to the LMCache usage "
+"server."
+msgstr "这些消息被序列化为 JSON 并通过 POST 发送到 LMCache 使用服务器。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:27
+msgid "Example JSON payload"
+msgstr "示例 JSON 有效负载"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:47
+msgid "Previewing collected data"
+msgstr "预览收集的数据"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:49
+msgid ""
+"If you enable **local logging**, usage messages are appended to your "
+"specified log file. To inspect the most recent entries:"
+msgstr "如果您启用 **本地日志记录**\\ ，使用消息将附加到您指定的日志文件中。要检查最近的条目："
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:56
+msgid "Configuration & Opt-out"
+msgstr "配置与选择退出"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:58
+msgid ""
+"By default, usage tracking is **enabled**. To disable all usage stats "
+"collection, set the environment variable:"
+msgstr "默认情况下，使用情况跟踪是 **启用** 的。要禁用所有使用统计信息收集，请设置环境变量："
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:64
+msgid ""
+"When ``LMCACHE_TRACK_USAGE`` is set to ``false``, "
+"``InitializeUsageContext`` will return ``None`` and no data will be sent "
+"or logged."
+msgstr "当 ``LMCACHE_TRACK_USAGE`` 设置为 ``false`` 时，\\ ``InitializeUsageContext`` 将返回 ``None``\\ ，并且不会发送或记录任何数据。"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:67
+msgid "Local logging"
+msgstr "本地日志记录"
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:69
+msgid ""
+"If you would like to log to a file in addition to (or instead of) sending"
+" data to the server, pass a local-log path when initializing:"
+msgstr "如果您希望在将数据发送到服务器的同时（或替代）记录到文件中，请在初始化时传递一个本地日志路径："
+
+#: ../../source/developer_guide/usage/usage_stats_collection.rst:81
+msgid ""
+"Omitting the ``local_log`` argument (or passing ``None``) disables local "
+"file logging."
+msgstr "省略 ``local_log`` 参数（或传递 ``None``\\ ）将禁用本地文件日志记录。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/1p1d.po b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/1p1d.po
new file mode 100644
index 0000000..8123210
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/1p1d.po
@@ -0,0 +1,362 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:2
+msgid "1p1d"
+msgstr "1p1d"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/disaggregated_prefill`."
+msgstr "此页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/disaggregated_prefill`。"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:10
+msgid "One Prefiller, One Decoder (1p1d) Example"
+msgstr "一个 Prefill 组件，一个解码器 (1p1d) 示例"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:12
+msgid ""
+"This example demonstrates how to run LMCache with disaggregated prefill "
+"using NIXL on a single node with a 1 prefiller + 1 decoder setup. This "
+"configuration separates the compute-intensive prefill operations from the"
+" decode operations, allowing for better resource utilization and "
+"performance optimization."
+msgstr ""
+"此示例演示了如何在单个节点上使用 NIXL 以分离式 Prefill 运行 LMCache，配置为 1 个 Prefiller + 1 个 "
+"Decoder。此配置将计算密集型的 Prefill 操作与解码操作分离，从而实现更好的资源利用和性能优化。"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:15
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:17
+msgid "The 1p1d setup consists of three main components:"
+msgstr "1p1d 设置由三个主要组件组成："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:19
+msgid ""
+"**Prefiller Server** - Handles the prefill phase of inference (initial "
+"prompt processing)"
+msgstr "**Prefill 服务器** - 处理推理的预填充阶段（初始提示处理）"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:20
+msgid ""
+"**Decoder Server** - Handles the decode phase of inference (token "
+"generation)"
+msgstr "**解码服务器** - 处理推理的解码阶段（令牌生成）"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:21
+msgid "**Proxy Server** - Coordinates requests between the prefiller and decoder"
+msgstr "**代理服务器** - 协调预填充器和解码器之间的请求"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:45
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:47
+msgid "**LMCache**: Install with ``pip install lmcache``"
+msgstr "**LMCache**: 使用 ``pip install lmcache`` 安装"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:48
+msgid ""
+"**NIXL**: Install from `NIXL GitHub repository <https://github.com/ai-"
+"dynamo/nixl>`_"
+msgstr ""
+"**NIXL**: 从 `NIXL GitHub repository <https://github.com/ai-dynamo/nixl>`_"
+" 安装"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:49
+msgid "**Hardware**: At least 2 GPUs"
+msgstr "**硬件**\\ ：至少需要 2 个 GPU"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:50
+msgid ""
+"**Model Access**: Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B "
+"Instruct"
+msgstr "**模型访问**\\ ：有效的 Hugging Face 令牌 (HF_TOKEN) 用于 Llama 3.1 8B Instruct"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:53
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:55
+msgid "**Set your Hugging Face token**:"
+msgstr "**设置你的 Hugging Face 令牌**\\ ："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:61
+msgid "**Navigate to the example directory**:"
+msgstr "**导航到示例目录**\\ ："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:67
+msgid "**Run the example**:"
+msgstr "**运行示例**:"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:73
+msgid "The script will automatically:"
+msgstr "该脚本将自动："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:75
+msgid "Launch a prefiller instance on port 7100 (GPU 0)"
+msgstr "在端口 7100（GPU 0）上启动一个 Prefill 实例"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:76
+msgid "Launch a decoder instance on port 7200 (GPU 1)"
+msgstr "在端口 7200 上启动解码器实例（GPU 1）"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:77
+msgid "Launch a proxy server on port 9100"
+msgstr "在 9100 端口启动一个代理服务器"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:78
+msgid "Wait for all servers to be ready"
+msgstr "等待所有服务器准备就绪"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:80
+msgid "Press ``Ctrl+C`` to stop all servers."
+msgstr "按 ``Ctrl+C`` 停止所有服务器。"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:83
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:85
+msgid ""
+"**Important**: For correct KV cache transfer, ensure all processes use "
+"the same ``PYTHONHASHSEED`` to keep the hash of the KV cache consistent "
+"across processes:"
+msgstr ""
+"**重要**\\ ：为了正确的 KV Cache 传输，确保所有进程使用相同的 ``PYTHONHASHSEED`` 以保持 KV Cache "
+"在进程间的一致性："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:92
+msgid "Prefiller Configuration"
+msgstr "分离式 Prefill 配置"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:94
+msgid "The prefiller is configured via ``configs/lmcache-prefiller-config.yaml``:"
+msgstr "预填充器通过 ``configs/lmcache-prefiller-config.yaml`` 进行配置："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:110
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:136
+msgid "Key settings:"
+msgstr "关键设置："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:112
+msgid "``pd_role: \"sender\"`` - Configures this instance to send KV cache data"
+msgstr "``pd_role: \"sender\"`` - 配置此实例以发送 KV Cache 数据"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:113
+msgid "``pd_buffer_size: 1073741824 # 1GB`` - Buffer size for transfers"
+msgstr "``pd_buffer_size: 1073741824 # 1GB`` - 传输的缓冲区大小"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:114
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:140
+msgid "``pd_buffer_device: \"cuda\"`` - Uses GPU memory for buffering"
+msgstr "``pd_buffer_device: \"cuda\"`` - 使用显存进行缓冲"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:117
+msgid "Decoder Configuration"
+msgstr "解码器配置"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:119
+msgid "The decoder is configured via ``configs/lmcache-decoder-config.yaml``:"
+msgstr "解码器通过 ``configs/lmcache-decoder-config.yaml`` 进行配置："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:138
+msgid ""
+"``pd_role: \"receiver\"`` - Configures this instance to receive KV cache "
+"data"
+msgstr "``pd_role: \"receiver\"`` - 配置此实例以接收 KV Cache 数据"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:139
+msgid "``pd_buffer_size: 2147483648 # 2GB`` - Buffer size for transfers"
+msgstr "``pd_buffer_size: 2147483648 # 2GB`` - 传输的缓冲区大小"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:143
+msgid "Components Deep Dive"
+msgstr "组件深入分析"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:146
+msgid "Proxy Server (disagg_proxy_server.py)"
+msgstr "代理服务器 (disagg_proxy_server.py)"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:148
+msgid "The proxy server coordinates the disaggregated prefill workflow:"
+msgstr "代理服务器协调分离式 Prefill 工作流："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:150
+msgid "**Request Handling**: Receives client requests on port 9100"
+msgstr "**请求处理**\\ ：在 9100 端口接收客户端请求"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:151
+msgid ""
+"**Prefill Coordination**: Sends requests to the prefiller with "
+"``max_tokens=1``"
+msgstr "**分离式 Prefill 协调**: 发送请求给 Prefill 模块，\\ ``max_tokens=1``"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:152
+msgid "**Prefill Response**: Receives prefiller that says nixl transfer is done"
+msgstr "**Prefill Response**: 接收预填充器，表示 nixl 转移已完成"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:153
+msgid "**Response Streaming**: Streams the full response from the decoder"
+msgstr "**响应流**\\ ：从解码器流式传输完整响应"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:154
+msgid "**Performance Monitoring**: Tracks Time-To-First-Token (TTFT) statistics"
+msgstr "**性能监控**: 跟踪首次令牌时间（TTFT）统计信息"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:156
+msgid "Supported endpoints:"
+msgstr "支持的端点："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:158
+msgid "``/v1/completions``"
+msgstr "``/v1/completions``"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:159
+msgid "``/v1/chat/completions``"
+msgstr "``/v1/chat/completions``"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:162
+msgid "vLLM Server Launcher (disagg_vllm_launcher.sh)"
+msgstr "vLLM 服务器启动器 (disagg_vllm_launcher.sh)"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:164
+msgid ""
+"This script launches individual vLLM servers with appropriate "
+"configurations:"
+msgstr "此脚本启动具有适当配置的单个 vLLM 服务器："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:166
+msgid "**Prefiller Launch Command**:"
+msgstr "**Prefill 启动命令**:"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:183
+msgid "**Decoder Launch Command**:"
+msgstr "**解码器启动命令**:"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:201
+msgid "Testing and Benchmarking"
+msgstr "测试与基准测试"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:204
+msgid "Basic Test"
+msgstr "基本测试"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:206
+msgid "Once all servers are running, you can test with a simple curl command:"
+msgstr "一旦所有服务器都在运行，您可以使用简单的 curl 命令进行测试："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:218
+msgid "Performance Benchmarking"
+msgstr "性能基准测试"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:220
+msgid "For comprehensive performance testing, use vLLM's benchmark tool:"
+msgstr "要进行全面的性能测试，请使用 vLLM 的基准测试工具："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:229
+msgid ""
+"This benchmark: - Sends requests to port 9100 (proxy server) - Uses "
+"random prompts with 7500 input tokens - Generates 200 output tokens per "
+"request - Tests with 30 total prompts at 1 request/second"
+msgstr ""
+"此基准测试： - 向 9100 端口（代理服务器）发送请求 - 使用 7500 个输入 token 的随机提示 - 每个请求生成 200 个输出 "
+"token - 使用 30 个总提示以 1 请求/秒的速度进行测试"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:236
+msgid "Log Files and Monitoring"
+msgstr "日志文件和监控"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:238
+msgid "The example generates three log files for monitoring:"
+msgstr "该示例生成三个用于监控的日志文件："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:240
+msgid "``prefiller.log`` - Prefiller server logs and errors"
+msgstr "``prefiller.log`` - Prefill 服务器日志和错误"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:241
+msgid "``decoder.log`` - Decoder server logs and errors"
+msgstr "``decoder.log`` - 解码器服务器日志和错误"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:242
+msgid "``proxy.log`` - Proxy server logs and TTFT statistics"
+msgstr "``proxy.log`` - 代理服务器日志和 TTFT 统计信息"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:244
+msgid ""
+"The proxy server automatically calculates and displays TTFT statistics "
+"every 5 seconds:"
+msgstr "代理服务器每 5 秒自动计算并显示 TTFT 统计信息："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:257
+msgid "Troubleshooting"
+msgstr "故障排除"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:260
+msgid "Common Issues"
+msgstr "常见问题"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:262
+msgid "**GPU Memory**: Ensure each GPU has sufficient memory for the model"
+msgstr "**显存**\\ ：确保每个 GPU 具有足够的内存以支持模型"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:263
+msgid "**NIXL Installation**: Verify NIXL is properly installed and accessible"
+msgstr "**NIXL 安装**: 验证 NIXL 是否正确安装并可访问"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:264
+msgid "**Port Conflicts**: Check that ports 7100, 7200, and 9000 are available"
+msgstr "**端口冲突**\\ ：检查端口 7100、7200 和 9000 是否可用"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:265
+msgid "**HF Token**: Ensure your Hugging Face token has access to Llama models"
+msgstr "**HF Token**: 确保您的 Hugging Face 令牌可以访问 Llama 模型"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:268
+msgid "Error Recovery"
+msgstr "错误恢复"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:270
+msgid "If any server fails to start:"
+msgstr "如果任何服务器无法启动："
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:272
+msgid "Check the corresponding log file for error details"
+msgstr "检查相应的日志文件以获取错误详情"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:273
+msgid "Verify GPU availability with ``nvidia-smi``"
+msgstr "使用 ``nvidia-smi`` 验证 GPU 可用性"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:274
+msgid "Ensure all dependencies are installed"
+msgstr "确保所有依赖项已安装"
+
+#: ../../source/disaggregated_prefill/nixl/1p1d.rst:275
+msgid "Try restarting with ``Ctrl+C`` followed by re-running the script"
+msgstr "尝试使用 ``Ctrl+C`` 重启，然后重新运行脚本。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/index.po
new file mode 100644
index 0000000..4ae1a0a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/index.po
@@ -0,0 +1,64 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/disaggregated_prefill/nixl/index.rst:2
+msgid "Using NIXL"
+msgstr "使用 NIXL"
+
+#: ../../source/disaggregated_prefill/nixl/index.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/disaggregated_prefill`."
+msgstr "此页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/disaggregated_prefill`。"
+
+#: ../../source/disaggregated_prefill/nixl/index.rst:9
+msgid ""
+"NIXL (NVIDIA Inference Xfer Library) is a high-performance library "
+"designed for accelerating point to point communications in AI inference "
+"frameworks. It provides an abstraction over various types of memory (CPU "
+"and GPU) and storage through a modular plug-in architecture, enabling "
+"efficient data transfer and coordination between different components of "
+"the inference pipeline."
+msgstr ""
+"NIXL（NVIDIA 推理传输库）是一个高性能库，旨在加速 AI 推理框架中的点对点通信。它通过模块化插件架构提供对各种类型内存（CPU 和 "
+"GPU）和存储的抽象，使得推理管道中不同组件之间的数据传输和协调更加高效。"
+
+#: ../../source/disaggregated_prefill/nixl/index.rst:12
+msgid ""
+"LMCache supports using NIXL as the underlying communication library for "
+"prefill-decode disaggregation."
+msgstr "LMCache 支持将 NIXL 作为分离式 Prefill-解码的底层通信库。"
+
+#: ../../source/disaggregated_prefill/nixl/index.rst:14
+msgid ""
+"For detailed installation instructions of LMCache with NIXL, please refer"
+" to our `installation guide "
+"<https://docs.google.com/document/d/1c93fANc2DPSUvR5ndCMysU2E29nYvjE2e3GLxHRWZls/edit?tab=t.0>`_."
+msgstr ""
+"有关使用 NIXL 安装 LMCache 的详细说明，请参阅我们的 `安装指南 "
+"<https://docs.google.com/document/d/1c93fANc2DPSUvR5ndCMysU2E29nYvjE2e3GLxHRWZls/edit?tab=t.0>`_。"
+
+#: ../../source/disaggregated_prefill/nixl/index.rst:17
+msgid "Examples"
+msgstr "示例"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/xpyd.po b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/xpyd.po
new file mode 100644
index 0000000..ebe9318
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/nixl/xpyd.po
@@ -0,0 +1,424 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:2
+msgid "XpYd"
+msgstr "XpYd"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/disaggregated_prefill`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/disaggregated_prefill`。"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:10
+msgid "X Prefiller, Y Decoder (XpYd) Example"
+msgstr "X 预填充器，Y 解码器 (XpYd) 示例"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:12
+msgid ""
+"This example demonstrates how to run LMCache with disaggregated prefill "
+"using NIXL on a single node with multiple prefiller and decoder "
+"instances. This configuration allows for horizontal scaling of both the "
+"compute-intensive prefill operations and the decode operations, enabling "
+"better resource utilization and higher throughput."
+msgstr ""
+"此示例演示了如何在单个节点上使用 NIXL 运行带有分离式 Prefill 的 LMCache，使用多个 Prefiller 和 Decoder "
+"实例。此配置允许对计算密集型的 Prefill 操作和解码操作进行横向扩展，从而实现更好的资源利用和更高的吞吐量。"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:15
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:17
+msgid ""
+"The XpYd setup consists of multiple components that can be scaled "
+"independently:"
+msgstr "XpYd 设置由多个可以独立扩展的组件组成："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:19
+msgid ""
+"**Multiple Prefiller Servers** - Handle the prefill phase of inference "
+"(initial prompt processing)"
+msgstr "**多个 Prefiller 服务器** - 处理推理的预填充阶段（初始提示处理）"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:20
+msgid ""
+"**Multiple Decoder Servers** - Handle the decode phase of inference "
+"(token generation)"
+msgstr "**多个解码器服务器** - 处理推理的解码阶段（令牌生成）"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:21
+msgid ""
+"**Proxy Server** - Coordinates requests between prefillers and decoders "
+"using round-robin load balancing"
+msgstr "**代理服务器** - 使用轮询负载均衡协调预填充器和解码器之间的请求"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:23
+msgid "Example 2p2d Architecture:"
+msgstr "示例 2p2d 架构："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:54
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:56
+msgid "**LMCache**: Install with ``pip install lmcache``"
+msgstr "**LMCache**: 使用 ``pip install lmcache`` 安装"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:57
+msgid ""
+"**NIXL**: Install from `NIXL GitHub repository <https://github.com/ai-"
+"dynamo/nixl>`_"
+msgstr ""
+"**NIXL**: 从 `NIXL GitHub repository <https://github.com/ai-dynamo/nixl>`_"
+" 安装"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:58
+msgid ""
+"**Hardware**: At least 4 GPUs (2 for prefillers + 2 for decoders in 2p2d "
+"setup)"
+msgstr "**硬件**\\ ：至少需要 4 个 GPU（2 个用于 Prefillers + 2 个用于 2p2d 设置中的解码器）"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:59
+msgid ""
+"**Model Access**: Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B "
+"Instruct"
+msgstr "**模型访问**\\ ：有效的 Hugging Face 令牌 (HF_TOKEN) 用于 Llama 3.1 8B Instruct"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:62
+msgid "Quick Start (2p2d Example)"
+msgstr "快速开始 (2p2d 示例)"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:64
+msgid "**Set your Hugging Face token**:"
+msgstr "**设置你的 Hugging Face 令牌**\\ ："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:70
+msgid "**Navigate to the example directory**:"
+msgstr "**导航到示例目录**\\ ："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:76
+msgid "**Run the example**:"
+msgstr "**运行示例**:"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:82
+msgid "The script will automatically:"
+msgstr "该脚本将自动："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:84
+msgid "Launch two decoder instances on port 8200 and 8201 (GPU 2 and GPU 3)"
+msgstr "在端口 8200 和 8201 启动两个解码器实例（GPU 2 和 GPU 3）"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:85
+msgid "Launch two prefiller instances on ports 7100 and 7101 (GPU 0 and GPU 1)"
+msgstr "在端口 7100 和 7101 上启动两个 Prefill 实例（GPU 0 和 GPU 1）"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:86
+msgid "Launch a proxy server on port 9100 with round-robin load balancing"
+msgstr "在9100端口启动一个代理服务器，并使用轮询负载均衡。"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:87
+msgid "Wait for all servers to be ready"
+msgstr "等待所有服务器准备就绪"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:89
+msgid "Press ``Ctrl+C`` to stop all servers."
+msgstr "按 ``Ctrl+C`` 停止所有服务器。"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:92
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:94
+msgid ""
+"**Important**: For correct KV cache transfer, ensure all processes use "
+"the same ``PYTHONHASHSEED`` to keep the hash of the KV cache consistent "
+"across processes:"
+msgstr ""
+"**重要**\\ ：为了正确的 KV Cache 传输，确保所有进程使用相同的 ``PYTHONHASHSEED`` 以保持 KV Cache "
+"在进程间的一致性："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:101
+msgid "Prefiller Configuration"
+msgstr "分离式 Prefill 配置"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:103
+msgid ""
+"All prefillers share the same configuration via ``configs/lmcache-"
+"prefiller-config.yaml``:"
+msgstr "所有 Prefiller 通过 ``configs/lmcache-prefiller-config.yaml`` 共享相同的配置："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:119
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:145
+msgid "Key settings:"
+msgstr "关键设置："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:121
+msgid "``pd_role: \"sender\"`` - Configures these instances to send KV cache data"
+msgstr "``pd_role: \"sender\"`` - 配置这些实例以发送 KV Cache 数据"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:122
+msgid ""
+"``pd_buffer_size: 1073741824 # 1GB`` - Upper bound of PD transport buffer"
+" size (in bytes), aligned to chunk size"
+msgstr "``pd_buffer_size: 1073741824 # 1GB`` - PD 传输缓冲区大小的上限（以字节为单位），与块大小对齐"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:123
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:149
+msgid "``pd_buffer_device: \"cuda\"`` - Uses GPU memory for buffering"
+msgstr "``pd_buffer_device: \"cuda\"`` - 使用显存进行缓冲"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:126
+msgid "Decoder Configuration"
+msgstr "解码器配置"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:128
+msgid ""
+"The decoder(s) are configured via ``configs/lmcache-"
+"decoder-x-config.yaml``:"
+msgstr "解码器通过 ``configs/lmcache-decoder-x-config.yaml`` 进行配置："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:147
+msgid ""
+"``pd_role: \"receiver\"`` - Configures these instances to receive KV "
+"cache data"
+msgstr "``pd_role: \"receiver\"`` - 配置这些实例以接收 KV Cache 数据"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:148
+msgid ""
+"``pd_buffer_size: 2147483648 # 2GB`` - Upper bound of PD transport buffer"
+" size (in bytes), aligned to chunk size"
+msgstr "``pd_buffer_size: 2147483648 # 2GB`` - PD 传输缓冲区大小的上限（以字节为单位），与块大小对齐"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:152
+msgid "Components Deep Dive"
+msgstr "组件深入分析"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:155
+msgid "Proxy Server (disagg_proxy_server.py)"
+msgstr "代理服务器 (disagg_proxy_server.py)"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:157
+msgid "The proxy server coordinates the multi-prefiller disaggregated workflow:"
+msgstr "代理服务器协调多预填充器的分离式工作流程："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:159
+msgid "**Request Handling**: Receives client requests on port 9000"
+msgstr "**请求处理**\\ ：在 9000 端口接收客户端请求"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:160
+msgid ""
+"**Load Balancing**: Distributes requests across multiple prefillers using"
+" round-robin"
+msgstr "**负载均衡**\\ ：使用轮询将请求分配到多个预填充器"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:161
+msgid ""
+"**Prefill Coordination**: Sends requests to prefillers with "
+"``max_tokens=1``"
+msgstr "**Prefill Coordination**: 将请求发送到使用 ``max_tokens=1`` 的 Prefill 处理器"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:162
+msgid "**Prefill Response**: Receives prefiller that says nixl transfer is done"
+msgstr "**Prefill Response**: 接收预填充器，表示 nixl 转移已完成"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:163
+msgid "**Response Streaming**: Streams the full response from the decoder"
+msgstr "**响应流**\\ ：从解码器流式传输完整响应"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:164
+msgid "**Performance Monitoring**: Tracks Time-To-First-Token (TTFT) statistics"
+msgstr "**性能监控**: 跟踪首次令牌时间（TTFT）统计信息"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:166
+msgid ""
+"Key features: - **Round-robin distribution**: Balances load across "
+"``--num-prefillers`` instances - **Fault tolerance**: Handles prefiller "
+"failures gracefully - **Monitoring**: Provides detailed TTFT statistics "
+"for each prefiller"
+msgstr ""
+"主要特性：- **轮询分配**\\ ：在 ``--num-prefillers`` 实例之间平衡负载 - **容错**\\ "
+"：优雅地处理预填充器故障 - **监控**\\ ：为每个预填充器提供详细的 TTFT 统计信息"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:171
+msgid "Supported endpoints: - ``/v1/completions`` - ``/v1/chat/completions``"
+msgstr "支持的端点： - ``/v1/completions`` - ``/v1/chat/completions``"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:176
+msgid "vLLM Server Launcher (disagg_vllm_launcher.sh)"
+msgstr "vLLM 服务器启动器 (disagg_vllm_launcher.sh)"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:178
+msgid ""
+"This script launches individual vLLM servers with appropriate "
+"configurations:"
+msgstr "此脚本启动具有适当配置的单个 vLLM 服务器："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:180
+msgid "**Prefiller1 Launch Command**:"
+msgstr "**Prefiller1 启动命令**:"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:197
+msgid "**Prefiller2 Launch Command**:"
+msgstr "**Prefiller2 启动命令**:"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:214
+msgid "**Decoder1 Launch Command**:"
+msgstr "**解码器1 启动命令**:"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:231
+msgid "**Decoder2 Launch Command**:"
+msgstr "**Decoder2 启动命令**:"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:248
+msgid ""
+"Key differences from 1p1d: - Each prefiller gets a unique "
+"``lmcache_rpc_port`` (producer1, producer2, etc.) - Each prefiller runs "
+"on a different GPU (CUDA_VISIBLE_DEVICES) - Different ports for each "
+"prefiller (7100, 7101, etc.) - Different ports for each decoder (7200, "
+"7201, etc.)"
+msgstr ""
+"与 1p1d 的主要区别： - 每个 Prefiller 获取一个唯一的 ``lmcache_rpc_port``\\ "
+"（producer1、producer2 等） - 每个 Prefiller 在不同的 GPU 上运行（CUDA_VISIBLE_DEVICES）"
+" - 每个 Prefiller 使用不同的端口（7100、7101 等） - 每个解码器使用不同的端口（7200、7201 等）"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:255
+msgid "Basic Test"
+msgstr "基本测试"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:257
+msgid "Once all servers are running, you can test with a simple curl command:"
+msgstr "一旦所有服务器都在运行，您可以使用简单的 curl 命令进行测试："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:269
+msgid "Performance Benchmarking"
+msgstr "性能基准测试"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:271
+msgid "For comprehensive performance testing, use vLLM's benchmark tool:"
+msgstr "要进行全面的性能测试，请使用 vLLM 的基准测试工具："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:280
+msgid ""
+"Expected performance improvements with 2p2d: - **Higher throughput**: "
+"Multiple prefillers can handle more concurrent requests - **Better "
+"TTFT**: Load balancing reduces queuing delays - **Improved utilization**:"
+" Better GPU utilization across multiple devices"
+msgstr ""
+"预期的性能提升与 2p2d 相关：- **更高的吞吐量**\\ ：多个预填充器可以处理更多的并发请求 - **更好的 TTFT**\\ "
+"：负载均衡减少排队延迟 - **更好的利用率**\\ ：多个设备之间更好的 GPU 利用率"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:285
+msgid "Sample benchmark results:"
+msgstr "示例基准测试结果："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:312
+msgid "Log Files and Monitoring"
+msgstr "日志文件和监控"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:314
+msgid "The example generates multiple log files for comprehensive monitoring:"
+msgstr "该示例生成多个日志文件以进行全面监控："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:316
+msgid "``prefiller1.log`` - First prefiller server logs and errors"
+msgstr "``prefiller1.log`` - 第一个 Prefill 服务器的日志和错误"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:317
+msgid "``prefiller2.log`` - Second prefiller server logs and errors"
+msgstr "``prefiller2.log`` - 第二个 Prefill 服务器日志和错误"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:318
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:319
+msgid "``decoder1.log`` - First decoder server logs and errors"
+msgstr "``decoder1.log`` - 第一个解码器服务器日志和错误"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:320
+msgid "``proxy.log`` - Proxy server logs and TTFT statistics"
+msgstr "``proxy.log`` - 代理服务器日志和 TTFT 统计信息"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:322
+msgid "The proxy server provides detailed statistics for each prefiller:"
+msgstr "代理服务器为每个 Prefiller 提供详细的统计信息："
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:338
+msgid ""
+"This helps identify performance differences between prefiller instances "
+"and optimize load balancing."
+msgstr "这有助于识别不同 Prefill 实例之间的性能差异并优化负载均衡。"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:341
+msgid "Troubleshooting"
+msgstr "故障排除"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:344
+msgid "Common Issues"
+msgstr "常见问题"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:346
+msgid "**GPU Memory**: Ensure each GPU has sufficient memory for the model"
+msgstr "**显存**\\ ：确保每个 GPU 具有足够的内存以支持模型"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:347
+msgid "**NIXL Installation**: Verify NIXL is properly installed and accessible"
+msgstr "**NIXL 安装**: 验证 NIXL 是否正确安装并可访问"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:348
+msgid "**Port Conflicts**: Check that all required ports are available"
+msgstr "**端口冲突**\\ ：检查所有必需的端口是否可用"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:349
+msgid "**HF Token**: Ensure your Hugging Face token has access to Llama models"
+msgstr "**HF Token**: 确保您的 Hugging Face 令牌可以访问 Llama 模型"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:350
+msgid "**GPU Assignment**: Verify CUDA_VISIBLE_DEVICES assignments don't conflict"
+msgstr "**GPU 分配**: 验证 CUDA_VISIBLE_DEVICES 的分配是否存在冲突"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:353
+msgid "Multi-Instance Specific Issues"
+msgstr "多实例特定问题"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:355
+msgid ""
+"**Uneven Load**: Monitor prefiller statistics to ensure balanced "
+"distribution"
+msgstr "**不均匀负载**\\ ：监控 Prefill 统计数据以确保负载均衡分配"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:356
+msgid ""
+"**Resource Contention**: Watch for GPU memory pressure with multiple "
+"instances"
+msgstr "**资源争用**\\ ：监控多个实例的显存压力"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:357
+msgid ""
+"**Network Bottlenecks**: Monitor NIXL transfer performance between "
+"instances"
+msgstr "**网络瓶颈**\\ ：监控实例之间的 NIXL 传输性能"
+
+#: ../../source/disaggregated_prefill/nixl/xpyd.rst:358
+msgid "**Startup Timing**: Stagger prefiller launches to avoid resource conflicts"
+msgstr "**启动时机**\\ ：错开 Prefill 启动以避免资源冲突"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/shared_storage.po b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/shared_storage.po
new file mode 100644
index 0000000..397aa6d
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/disaggregated_prefill/shared_storage.po
@@ -0,0 +1,29 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/disaggregated_prefill/shared_storage.rst:2
+msgid "Using shared storage"
+msgstr "使用共享存储"
+
+#: ../../source/disaggregated_prefill/shared_storage.rst:4
+msgid "Coming soon..."
+msgstr "敬请期待..."
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/distributed_kv_cache.po b/docs/source/locale/zh_CN/LC_MESSAGES/distributed_kv_cache.po
new file mode 100644
index 0000000..23a6ac9
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/distributed_kv_cache.po
@@ -0,0 +1,32 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/distributed_kv_cache.rst:2
+msgid "Distributed KV Cache"
+msgstr "分布式 KV Cache"
+
+#: ../../source/distributed_kv_cache.rst:4
+msgid ""
+"Sharing and coordinating KV cache across multiple LMCache servers and "
+"inference instances -- disaggregated prefill, peer-to-peer sharing, "
+"multi-server coordination, and cache management."
+msgstr "在多个 LMCache 服务器和推理实例之间共享和协调 KV Cache——分离式预填充、点对点共享、多服务器协调与缓存管理。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/benchmarking.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/benchmarking.po
new file mode 100644
index 0000000..9be6fd3
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/benchmarking.po
@@ -0,0 +1,267 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/benchmarking.rst:2
+msgid "Benchmarking"
+msgstr "基准测试"
+
+#: ../../source/getting_started/benchmarking.rst:4
+msgid ""
+"This is a simple tutorial on how to deploy and benchmark LMCache using "
+"the ``lmcache bench engine`` CLI."
+msgstr "这是一个关于如何使用 ``lmcache bench engine`` CLI 部署和基准测试 LMCache 的简单教程。"
+
+#: ../../source/getting_started/benchmarking.rst:7
+msgid ""
+"The ``lmcache bench engine`` command is a flexible traffic simulator that"
+" sends configurable workloads to your inference engine and reports TTFT, "
+"decoding speed, and throughput metrics. This tutorial walks through a "
+"long-document Q&A benchmark that exercises LMCache's CPU offloading path."
+msgstr ""
+"``lmcache bench engine`` 命令是一个灵活的流量模拟器，可以向您的推理引擎发送可配置的工作负载，并报告 "
+"TTFT、解码速度和吞吐量指标。本教程将介绍一个长文档问答基准测试，测试 LMCache 的 CPU 卸载路径。"
+
+#: ../../source/getting_started/benchmarking.rst:12
+msgid ""
+"For the full CLI reference -- including every flag, every workload type, "
+"and config-file usage -- see :doc:`/cli/bench`."
+msgstr "有关完整的 CLI 参考 -- 包括每个标志、每种工作负载类型和配置文件用法 -- 请参见 :doc:`/cli/bench`。"
+
+#: ../../source/getting_started/benchmarking.rst:16
+msgid "Long Doc QA workload"
+msgstr "长文档问答工作负载"
+
+#: ../../source/getting_started/benchmarking.rst:18
+msgid ""
+"The ``long-doc-qa`` workload simulates repeated Q&A over long synthetic "
+"documents: a warmup round primes the KV cache with each document, then a "
+"benchmark round dispatches the questions. The number of documents is "
+"derived from ``--kv-cache-volume`` and the model's tokens-per-GB rather "
+"than set directly. See :doc:`/cli/bench` for the full flag list."
+msgstr ""
+"``long-doc-qa`` 工作负载模拟对长的合成文档进行重复的问答：预热轮次用每个文档预热 KV "
+"Cache，然后基准轮次分发问题。文档的数量是根据 ``--kv-cache-volume`` 和模型的每 GB "
+"令牌数推导的，而不是直接设置的。有关完整的标志列表，请参见 :doc:`/cli/bench`。"
+
+#: ../../source/getting_started/benchmarking.rst:25
+msgid "Example"
+msgstr "示例"
+
+#: ../../source/getting_started/benchmarking.rst:27
+msgid ""
+"To measure the benefit of LMCache, run the **same benchmark against two "
+"setups** and compare the results:"
+msgstr "要衡量 LMCache 的收益，请对 **两种配置运行相同的基准测试** 并比较结果："
+
+#: ../../source/getting_started/benchmarking.rst:30
+msgid "**Setup A (baseline)** -- vLLM alone."
+msgstr "**配置 A（基准线）** -- 仅 vLLM。"
+
+#: ../../source/getting_started/benchmarking.rst:31
+msgid "**Setup B (with LMCache)** -- vLLM plus a standalone LMCache server."
+msgstr "**配置 B（使用 LMCache）** -- vLLM 加上独立的 LMCache 服务器。"
+
+#: ../../source/getting_started/benchmarking.rst:33
+msgid ""
+"The steps below reproduce both runs on ``Qwen/Qwen3-8B``. Adjust the "
+"sizes to match your hardware."
+msgstr "以下步骤将在 ``Qwen/Qwen3-8B`` 上重现上述两次运行。请根据您的硬件规格调整相应参数。"
+
+#: ../../source/getting_started/benchmarking.rst:37
+msgid "Setup A: vLLM alone (baseline)"
+msgstr "配置 A：仅 vLLM（基准线）"
+
+#: ../../source/getting_started/benchmarking.rst:44
+msgid "Setup B: vLLM with LMCache"
+msgstr "配置 B：vLLM 与 LMCache 配合使用"
+
+#: ../../source/getting_started/benchmarking.rst:46
+msgid ""
+"Run LMCache as a standalone service and point vLLM at it with the "
+"``LMCacheMPConnector``. See :doc:`/getting_started/quickstart` for the "
+"full MP-mode walkthrough."
+msgstr "将 LMCache 作为独立服务运行，并通过 ``LMCacheMPConnector`` 将 vLLM 指向它。有关完整的 MP 模式操作指南，请参见 :doc:`/getting_started/quickstart`。"
+
+#: ../../source/getting_started/benchmarking.rst:50
+msgid "**Start the LMCache server:**"
+msgstr "**启动 LMCache 服务器：**"
+
+#: ../../source/getting_started/benchmarking.rst:57
+msgid ""
+"The ZMQ port defaults to **5555** (used by vLLM) and the HTTP frontend "
+"defaults to **8080** (used by ``lmcache bench engine --lmcache-url``)."
+msgstr "ZMQ 端口默认为 **5555**\\ （由 vLLM 使用），HTTP 前端默认为 **8080**\\ （由 ``lmcache bench engine --lmcache-url`` 使用）。"
+
+#: ../../source/getting_started/benchmarking.rst:60
+msgid "**Start vLLM with the MP connector in a separate terminal:**"
+msgstr "**在另一个终端中使用 MP 连接器启动 vLLM：**"
+
+#: ../../source/getting_started/benchmarking.rst:69
+msgid "Run the benchmark"
+msgstr "运行基准测试"
+
+#: ../../source/getting_started/benchmarking.rst:71
+msgid ""
+"To make the comparison fair, capture the benchmark settings **once** in a"
+" config file, then replay the same config against both setups."
+msgstr "为确保比较公平，请将基准测试参数\\ **一次性**\\ 写入配置文件，再对两种配置分别重放相同的设置。"
+
+#: ../../source/getting_started/benchmarking.rst:74
+msgid ""
+"**Step 1 -- export a shared config.** With the LMCache server from Setup "
+"B still running, launch ``lmcache bench engine`` in interactive mode:"
+msgstr "**步骤 1 -- 导出共享配置。** 在 Setup B 的 LMCache 服务器仍在运行的情况下，以交互模式启动 ``lmcache bench engine``\\ ："
+
+#: ../../source/getting_started/benchmarking.rst:81
+msgid ""
+"Interactive mode triggers because ``--engine-url`` and ``--workload`` are"
+" missing, and ``--lmcache-url`` auto-detects ``tokens-per-gb-kvcache`` "
+"from the server. Walk through the prompts and pick:"
+msgstr "交互模式被触发，因为缺少 ``--engine-url`` 和 ``--workload``\\ ，而 ``--lmcache-url`` 从服务器自动检测 ``tokens-per-gb-kvcache``\\ 。按照提示进行操作并选择："
+
+#: ../../source/getting_started/benchmarking.rst:85
+msgid "Engine URL: ``http://localhost:8000``"
+msgstr "引擎 URL: ``http://localhost:8000``"
+
+#: ../../source/getting_started/benchmarking.rst:86
+msgid "Workload: ``long-doc-qa``"
+msgstr "工作负载: ``long-doc-qa``"
+
+#: ../../source/getting_started/benchmarking.rst:87
+msgid "Model: auto-detected from the engine (or type ``Qwen/Qwen3-8B``)"
+msgstr "模型：从引擎自动检测（或手动输入 ``Qwen/Qwen3-8B``\\ ）"
+
+#: ../../source/getting_started/benchmarking.rst:88
+msgid "KV cache volume (GB): ``10``"
+msgstr "KV cache volume (GB): ``10``"
+
+#: ../../source/getting_started/benchmarking.rst:89
+msgid "``ldqa-query-per-document``: ``1``"
+msgstr "``ldqa-query-per-document``: ``1``"
+
+#: ../../source/getting_started/benchmarking.rst:90
+msgid "``ldqa-shuffle-policy``: ``tile``"
+msgstr "``ldqa-shuffle-policy``: ``tile``"
+
+#: ../../source/getting_started/benchmarking.rst:91
+msgid "``ldqa-num-inflight-requests``: ``4``"
+msgstr "``ldqa-num-inflight-requests``: ``4``"
+
+#: ../../source/getting_started/benchmarking.rst:92
+msgid "Leave the rest at their defaults."
+msgstr "将其余选项保留为默认值。"
+
+#: ../../source/getting_started/benchmarking.rst:94
+msgid ""
+"At the **summary** step, choose **\"Export configuration for later use "
+"and exit\"** and save to ``bench_config.json``. The file looks like:"
+msgstr "在 **总结** 步骤中，选择 **“导出配置以供后用并退出”** 并保存为 ``bench_config.json``\\ 。该文件如下所示："
+
+#: ../../source/getting_started/benchmarking.rst:110
+msgid ""
+"Note that the exported config stores ``tokens_per_gb_kvcache`` (resolved "
+"from ``--lmcache-url``) but **not** the engine URL or the LMCache URL, so"
+" the same file is portable across environments."
+msgstr "请注意，导出的配置存储了 ``tokens_per_gb_kvcache``\\ （从 ``--lmcache-url`` 解析得出），但\\ **不**\\ 包括引擎 URL 或 LMCache URL，因此同一个文件可以在不同环境中使用。"
+
+#: ../../source/getting_started/benchmarking.rst:114
+msgid ""
+"**Step 2 -- replay against each setup.** Point ``--engine-url`` at "
+"whichever vLLM you want to benchmark and pass the shared config:"
+msgstr "**步骤 2 -- 针对每种配置重放。** 将 ``--engine-url`` 指向目标 vLLM 实例，并传入共享配置文件："
+
+#: ../../source/getting_started/benchmarking.rst:123
+msgid ""
+"Run this once against Setup A's vLLM and once against Setup B's vLLM-"
+"plus-LMCache, recording the metrics from each run."
+msgstr "分别对配置 A 的 vLLM 和配置 B 的 vLLM-plus-LMCache 各运行一次，记录每次的指标数据。"
+
+#: ../../source/getting_started/benchmarking.rst:127
+msgid "Results"
+msgstr "结果"
+
+#: ../../source/getting_started/benchmarking.rst:129
+msgid ""
+"Pull the headline numbers out of each run's ``Engine Benchmark Result "
+"(long-doc-qa)`` summary:"
+msgstr "从每次运行输出的 ``Engine Benchmark Result (long-doc-qa)`` 汇总中提取关键指标："
+
+#: ../../source/getting_started/benchmarking.rst:136
+msgid "Metric"
+msgstr "指标"
+
+#: ../../source/getting_started/benchmarking.rst:137
+msgid "Setup A (vLLM)"
+msgstr "配置 A (vLLM)"
+
+#: ../../source/getting_started/benchmarking.rst:138
+msgid "Setup B (+ LMCache)"
+msgstr "配置 B (+ LMCache)"
+
+#: ../../source/getting_started/benchmarking.rst:139
+msgid "Successful requests"
+msgstr "成功的请求"
+
+#: ../../source/getting_started/benchmarking.rst:140
+#: ../../source/getting_started/benchmarking.rst:141
+msgid "46"
+msgstr "46"
+
+#: ../../source/getting_started/benchmarking.rst:142
+msgid "Benchmark duration (s)"
+msgstr "基准测试持续时间（秒）"
+
+#: ../../source/getting_started/benchmarking.rst:143
+msgid "23.47"
+msgstr "23.47"
+
+#: ../../source/getting_started/benchmarking.rst:144
+msgid "13.79"
+msgstr "13.79"
+
+#: ../../source/getting_started/benchmarking.rst:145
+msgid "Mean TTFT (ms)"
+msgstr "平均 TTFT (毫秒)"
+
+#: ../../source/getting_started/benchmarking.rst:146
+msgid "757.00"
+msgstr "757.00"
+
+#: ../../source/getting_started/benchmarking.rst:147
+msgid "185.00"
+msgstr "185.00"
+
+#: ../../source/getting_started/benchmarking.rst:149
+msgid ""
+"That's a **75%** reduction in Mean TTFT (757 ms → 185 ms) and a **41%** "
+"reduction in benchmark duration (23.47 s → 13.79 s) from LMCache "
+"offloading."
+msgstr "在 LMCache CPU 卸载的加持下，平均 TTFT 降低了 **75%**\\ （757 毫秒 → 185 毫秒），基准测试总耗时缩短了 **41%**\\ （23.47 秒 → 13.79 秒）。"
+
+#: ../../source/getting_started/benchmarking.rst:153
+msgid ""
+"Without LMCache, once the benchmark's working set overflows the GPU KV "
+"cache the second round has to recompute every prefix, so TTFT and "
+"throughput don't improve even when content repeats. LMCache keeps the "
+"evicted blocks on CPU RAM and restores them on demand -- that's where the"
+" speedup comes from."
+msgstr "若不使用 LMCache，一旦基准测试的工作集超出 GPU KV 缓存容量，第二轮就必须重新计算每个前缀，导致即使内容重复，TTFT 和吞吐量也无法提升。LMCache 将被逐出的块保存在 CPU 内存中并按需恢复——这正是加速效果的来源。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/index.po
new file mode 100644
index 0000000..04b5d08
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/index.po
@@ -0,0 +1,32 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/index.rst:2
+msgid "Getting Started"
+msgstr "入门指南"
+
+#: ../../source/getting_started/index.rst:4
+msgid ""
+"New to LMCache? Start here -- an overview of multiprocess mode, "
+"installation, a quickstart, the configuration reference, and tools for "
+"benchmarking and sizing the cache."
+msgstr "对 LMCache 不熟悉？从这里开始——了解 MP 模式（多进程）、安装、快速入门、配置参考以及用于基准测试和缓存大小评估的工具。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/installation.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/installation.po
new file mode 100644
index 0000000..c9a73b1
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/installation.po
@@ -0,0 +1,240 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/installation.rst:4
+msgid "Installation"
+msgstr "安装"
+
+#: ../../source/getting_started/installation.rst:6
+msgid ""
+"**Prerequisites:** Linux · Python 3.9–3.13 · NVIDIA GPU (compute 7.0+) · "
+"CUDA 12.1+ · `uv <https://astral.sh/uv>`_"
+msgstr "**前提条件：** Linux · Python 3.9–3.13 · NVIDIA GPU（算力 7.0+）· CUDA 12.1+ · `uv <https://astral.sh/uv>`_"
+
+#: ../../source/getting_started/installation.rst:9
+msgid "Install LMCache"
+msgstr "安装 LMCache"
+
+#: ../../source/getting_started/installation.rst
+msgid "Python (pip / uv)"
+msgstr "Python (pip / uv)"
+
+#: ../../source/getting_started/installation.rst
+msgid "Stable"
+msgstr "稳定"
+
+#: ../../source/getting_started/installation.rst
+msgid "CUDA 13.0"
+msgstr "CUDA 13.0"
+
+#: ../../source/getting_started/installation.rst:31
+msgid ""
+"You're all set! You can now start using LMCache. For hands-on guides and "
+"more usage examples, see the :ref:`quickstart_examples` section."
+msgstr "一切准备就绪！您现在可以开始使用 LMCache。有关实践指南和更多使用示例，请参阅 :ref:`quickstart_examples` 部分。"
+
+#: ../../source/getting_started/installation.rst
+msgid "CUDA 12.9"
+msgstr "CUDA 12.9"
+
+#: ../../source/getting_started/installation.rst:36
+msgid ""
+"The CUDA 12.9 wheel is published to a dedicated `GitHub Release "
+"<https://github.com/LMCache/LMCache/releases>`__ rather than PyPI."
+msgstr ""
+"CUDA 12.9 的 wheel 发布在专用的 `GitHub Release "
+"<https://github.com/LMCache/LMCache/releases>`__ 上，而不是 PyPI。"
+
+#: ../../source/getting_started/installation.rst:51
+msgid ""
+"``--extra-index-url https://download.pytorch.org/whl/cu129`` ensures the "
+"CUDA 12.9 build of PyTorch is resolved. Without it, pip may select a "
+"mismatched CUDA variant."
+msgstr ""
+"``--extra-index-url https://download.pytorch.org/whl/cu129`` 确保解析 PyTorch"
+" 的 CUDA 12.9 构建。没有它，pip 可能会选择不匹配的 CUDA 变体。"
+
+#: ../../source/getting_started/installation.rst
+msgid "Nightly"
+msgstr "夜间版"
+
+#: ../../source/getting_started/installation.rst:56
+msgid ""
+"Nightly wheels are built from the latest ``dev`` branch each day at 07:30"
+" UTC and published to GitHub Releases. No version pinning required — "
+"``--pre`` picks the latest nightly automatically."
+msgstr "Nightly wheel 包每天 UTC 时间 07:30 从最新的 ``dev`` 分支构建并发布到 GitHub Releases。无需锁定版本 — ``--pre`` 会自动选取最新的 nightly 版本。"
+
+#: ../../source/getting_started/installation.rst
+msgid "From Source"
+msgstr "从源代码安装"
+
+#: ../../source/getting_started/installation.rst:86
+msgid ""
+"``--no-build-isolation`` ensures the kernels are compiled against the "
+"same torch already installed in your environment, preventing undefined "
+"symbol errors at runtime."
+msgstr "``--no-build-isolation`` 确保内核与您环境中已安装的相同 torch 进行编译，从而防止运行时出现未定义符号错误。"
+
+#: ../../source/getting_started/installation.rst
+msgid "ROCm"
+msgstr "ROCm"
+
+#: ../../source/getting_started/installation.rst
+msgid "Intel XPU"
+msgstr "英特尔 XPU"
+
+#: ../../source/getting_started/installation.rst
+msgid "Docker"
+msgstr "Docker"
+
+#: ../../source/getting_started/installation.rst:218
+msgid "See :ref:`docker_deployment` for running the container and ROCm images."
+msgstr "请参阅 :ref:`docker_deployment` 以获取运行容器和 ROCm 镜像的信息。"
+
+#: ../../source/getting_started/installation.rst
+msgid "CLI Only"
+msgstr "仅限 CLI"
+
+#: ../../source/getting_started/installation.rst:222
+msgid ""
+"Lightweight CLI-only package for querying or benchmarking a remote "
+"LMCache server. No CUDA required, works on any OS."
+msgstr "轻量级纯 CLI 软件包，用于查询或对远程 LMCache 服务器进行基准测试。无需 CUDA，支持任意操作系统。"
+
+#: ../../source/getting_started/installation.rst:231
+msgid ""
+"``lmcache-cli`` and ``lmcache`` ship the same ``lmcache`` CLI command. Do"
+" not install both in the same environment."
+msgstr "``lmcache-cli`` 和 ``lmcache`` 提供相同的 ``lmcache`` CLI 命令。请勿在同一环境中同时安装两者。"
+
+#: ../../source/getting_started/installation.rst:235
+msgid "Build the Docker Image"
+msgstr "构建 Docker 镜像"
+
+#: ../../source/getting_started/installation.rst:237
+msgid ""
+"Instead of pulling a prebuilt image, you can build the LMCache "
+"(integrated with vLLM) image yourself from the provided Dockerfile, "
+"located in `docker/ "
+"<https://github.com/LMCache/LMCache/tree/dev/docker>`_."
+msgstr "您也可以不拉取预构建镜像，而是直接使用仓库中提供的 Dockerfile 自行构建 LMCache（集成 vLLM）镜像，Dockerfile 位于 `docker/ <https://github.com/LMCache/LMCache/tree/dev/docker>`_。"
+
+#: ../../source/getting_started/installation.rst:241
+msgid "From the root of the LMCache repository:"
+msgstr "在 LMCache 仓库的根目录下："
+
+#: ../../source/getting_started/installation.rst:247
+msgid ""
+"Replace ``<IMAGE_NAME>`` and ``<TAG>`` with your desired image name and "
+"tag. See the example build file in `docker/ "
+"<https://github.com/LMCache/LMCache/tree/dev/docker>`_ for an explanation"
+" of all build arguments."
+msgstr "将 ``<IMAGE_NAME>`` 和 ``<TAG>`` 替换为所需的镜像名称和标签。各构建参数的说明请参阅 `docker/ <https://github.com/LMCache/LMCache/tree/dev/docker>`_ 中的示例构建文件。"
+
+#: ../../source/getting_started/installation.rst:252
+msgid "Verify Installation"
+msgstr "验证安装"
+
+#~ msgid "Compatibility Matrix"
+#~ msgstr "兼容性矩阵"
+
+#~ msgid ""
+#~ "✅ compatible · ❌ API incompatible "
+#~ "· 🕯 torch mismatch (use ``--no-"
+#~ "build-isolation``)"
+#~ msgstr "✅ 兼容 · ❌ API 不兼容 · 🕯 torch 不匹配 (使用 ``--no-build-isolation``)"
+
+#~ msgid "LMCache 0.4.2"
+#~ msgstr "LMCache 0.4.2"
+
+#~ msgid "LMCache 0.4.1"
+#~ msgstr "LMCache 0.4.1"
+
+#~ msgid "LMCache 0.3.15"
+#~ msgstr "LMCache 0.3.15"
+
+#~ msgid "LMCache 0.3.14"
+#~ msgstr "LMCache 0.3.14"
+
+#~ msgid "LMCache 0.3.13"
+#~ msgstr "LMCache 0.3.13"
+
+#~ msgid "LMCache 0.3.12"
+#~ msgstr "LMCache 0.3.12"
+
+#~ msgid "LMCache 0.3.11"
+#~ msgstr "LMCache 0.3.11"
+
+#~ msgid "LMCache 0.3.10"
+#~ msgstr "LMCache 0.3.10"
+
+#~ msgid "vLLM 0.18.0.x"
+#~ msgstr "vLLM 0.18.0.x"
+
+#~ msgid "✅"
+#~ msgstr "✅"
+
+#~ msgid "🕯️"
+#~ msgstr "🕯️"
+
+#~ msgid "vLLM 0.17.1.x"
+#~ msgstr "vLLM 0.17.1.x"
+
+#~ msgid "vLLM 0.17.0.x"
+#~ msgstr "vLLM 0.17.0.x"
+
+#~ msgid "vLLM 0.16.0.x"
+#~ msgstr "vLLM 0.16.0.x"
+
+#~ msgid "vLLM 0.15.1.x"
+#~ msgstr "vLLM 0.15.1.x"
+
+#~ msgid "vLLM 0.15.0.x"
+#~ msgstr "vLLM 0.15.0.x"
+
+#~ msgid "vLLM 0.14.1.x"
+#~ msgstr "vLLM 0.14.1.x"
+
+#~ msgid "vLLM 0.14.0.x"
+#~ msgstr "vLLM 0.14.0.x"
+
+#~ msgid "vLLM 0.13.0.x"
+#~ msgstr "vLLM 0.13.0.x"
+
+#~ msgid "vLLM 0.12.0.x"
+#~ msgstr "vLLM 0.12.0.x"
+
+#~ msgid "vLLM 0.11.2.x"
+#~ msgstr "vLLM 0.11.2.x"
+
+#~ msgid "vLLM 0.11.1.x"
+#~ msgstr "vLLM 0.11.1.x"
+
+#~ msgid "vLLM 0.11.0.x"
+#~ msgstr "vLLM 0.11.0.x"
+
+#~ msgid "vLLM 0.10.2.x"
+#~ msgstr "vLLM 0.10.2.x"
+
+#~ msgid "vLLM 0.10.1.x"
+#~ msgstr "vLLM 0.10.1.x"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/kv_cache_calculator.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/kv_cache_calculator.po
new file mode 100644
index 0000000..e57b74e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/kv_cache_calculator.po
@@ -0,0 +1,45 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/kv_cache_calculator.rst:2
+msgid "KV Cache Size Calculator"
+msgstr "KV Cache 大小计算器"
+
+#: ../../source/getting_started/kv_cache_calculator.rst:4
+msgid "Use this interactive calculator to:"
+msgstr "使用此交互式计算器来："
+
+#: ../../source/getting_started/kv_cache_calculator.rst:6
+msgid ""
+"**Calculate KV Cache Size**: Estimate the memory required for caching a "
+"specific number of tokens"
+msgstr "**计算 KV Cache 大小**\\ ：估算缓存特定数量的令牌所需的内存"
+
+#: ../../source/getting_started/kv_cache_calculator.rst:7
+msgid ""
+"**Calculate Maximum Tokens**: Find out how many tokens you can cache "
+"given your available GPU RAM"
+msgstr "**计算最大令牌数**\\ ：找出在可用的 GPU RAM 下可以缓存多少令牌"
+
+#: ../../source/getting_started/kv_cache_calculator.rst:9
+msgid "This helps you plan memory requirements for your LMCache deployment."
+msgstr "这可以帮助您规划 LMCache 部署的内存需求。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart.po
new file mode 100644
index 0000000..4dd3630
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart.po
@@ -0,0 +1,492 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart.rst:4
+msgid "Quickstart"
+msgstr "快速入门"
+
+#: ../../source/getting_started/quickstart.rst:6
+msgid ""
+"This guide helps you get LMCache running end-to-end in a couple of "
+"minutes. Use the tabs below to switch the engine. Steps are the same; "
+"only the libraries and launch commands change."
+msgstr "本指南帮助您在几分钟内完成 LMCache 的端到端运行。使用下面的选项卡切换引擎。步骤是相同的；只有库和启动命令有所不同。"
+
+#: ../../source/getting_started/quickstart.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/getting_started/quickstart.rst:13
+msgid "**Install LMCache**"
+msgstr "**安装 LMCache**"
+
+#: ../../source/getting_started/quickstart.rst:21
+msgid "LMCache supports two deployment modes with vLLM:"
+msgstr "LMCache 支持与 vLLM 的两种部署模式："
+
+#: ../../source/getting_started/quickstart.rst:23
+msgid ""
+"**Multiprocess (MP) mode** -- **recommended.** LMCache runs as a "
+"standalone service and vLLM attaches via ``LMCacheMPConnector``. Scales "
+"better, exposes management/observability endpoints, and supports sharing "
+"one cache across multiple engine instances."
+msgstr ""
+"**MP 模式（多进程）** -- **推荐。** LMCache 作为独立服务运行，vLLM 通过 ``LMCacheMPConnector``"
+" 连接。扩展性更好，提供管理与可观察性端点，并支持在多个引擎实例之间共享同一缓存。"
+
+#: ../../source/getting_started/quickstart.rst:27
+msgid ""
+"**In-process mode** -- LMCache runs inside the vLLM process via "
+"``LMCacheConnectorV1``. Single command, convenient for quick single-node "
+"experiments."
+msgstr ""
+"**进程内模式** -- LMCache 通过 ``LMCacheConnectorV1`` 在 vLLM "
+"进程内部运行。单个命令，方便进行快速的单节点实验。"
+
+#: ../../source/getting_started/quickstart.rst
+msgid "MP mode (recommended)"
+msgstr "MP 模式（推荐）"
+
+#: ../../source/getting_started/quickstart.rst:37
+msgid ""
+"Start the LMCache server. ``--host`` / ``--port`` set the ZMQ address "
+"vLLM connects to; they are spelled out here so the two commands line up "
+"(these are also the defaults):"
+msgstr "启动 LMCache 服务器。 ``--host`` / ``--port`` 设置 vLLM 连接的 ZMQ 地址；它们在这里列出以便两个命令对齐（这些也是默认值）："
+
+#: ../../source/getting_started/quickstart.rst:50
+msgid ""
+"The ZMQ port (``--port``, default **5555**) accepts connections from "
+"vLLM; the HTTP frontend (default **8080**) serves the management and "
+"metrics endpoints. See :doc:`../mp/configuration` for the full list of "
+"``lmcache server`` and connector options."
+msgstr "ZMQ 端口 (``--port``, 默认 **5555**) 接受来自 vLLM 的连接；HTTP 前端 (默认 **8080**) 提供管理和指标端点。有关 ``lmcache server`` 和连接器选项的完整列表，请参见 :doc:`../mp/configuration`。"
+
+#: ../../source/getting_started/quickstart.rst:55
+msgid ""
+"Start vLLM with the MP connector in a separate terminal. Point the "
+"connector at the server above via ``lmcache.mp.host`` / "
+"``lmcache.mp.port`` in ``kv_connector_extra_config`` -- the host **must**"
+" carry a ZMQ transport prefix such as ``tcp://``:"
+msgstr "在单独的终端中启动 vLLM 和 MP 连接器。通过 ``kv_connector_extra_config`` 中的 ``lmcache.mp.host`` / ``lmcache.mp.port`` 将连接器指向上述服务器——主机 **必须** 带有 ZMQ 传输前缀，例如 ``tcp://``："
+
+#: ../../source/getting_started/quickstart.rst:67
+msgid ""
+"**Where does** ``LMCacheMPConnector`` **resolve to?** This depends on "
+"your vLLM version:"
+msgstr "**``LMCacheMPConnector`` 解析到哪里？** 这取决于您的 vLLM 版本："
+
+#: ../../source/getting_started/quickstart.rst:69
+msgid ""
+"**vLLM < 0.20.0** -- ``\"kv_connector\":\"LMCacheMPConnector\"`` always "
+"resolves to vLLM's built-in "
+"``vllm.distributed.kv_transfer.kv_connector.v1.LMCacheMPConnector``; "
+"there is no way to redirect it to the LMCache-shipped implementation."
+msgstr ""
+"**vLLM < 0.20.0** -- ``\"kv_connector\":\"LMCacheMPConnector\"`` 始终解析为 "
+"vLLM 内置的 "
+"``vllm.distributed.kv_transfer.kv_connector.v1.LMCacheMPConnector``\\ "
+"；无法将其重定向到 LMCache 提供的实现。"
+
+#: ../../source/getting_started/quickstart.rst:74
+msgid ""
+"**vLLM >= 0.20.0** -- ``\"kv_connector\":\"LMCacheMPConnector\"`` still "
+"defaults to vLLM's built-in connector, but you can opt in to the LMCache-"
+"shipped implementation "
+"(:mod:`lmcache.integration.vllm.lmcache_mp_connector`) by adding "
+"``kv_connector_module_path``:"
+msgstr ""
+"**vLLM >= 0.20.0** -- ``\"kv_connector\":\"LMCacheMPConnector\"`` 仍然默认为 "
+"vLLM 的内置连接器，但您可以通过添加 ``kv_connector_module_path`` 选择使用 LMCache 提供的实现 "
+"(:mod:`lmcache.integration.vllm.lmcache_mp_connector`):"
+
+#: ../../source/getting_started/quickstart.rst:86
+msgid ""
+"The LMCache-shipped connector tracks the latest LMCache server protocol "
+"and ships fixes/features ahead of the version vendored into vLLM, so "
+"prefer it whenever you are on vLLM 0.20.0 or newer."
+msgstr ""
+"LMCache 提供的连接器跟踪最新的 LMCache 服务器协议，并在集成到 vLLM 的版本之前发布修复和功能，因此在使用 vLLM "
+"0.20.0 或更高版本时，建议优先使用它。"
+
+#: ../../source/getting_started/quickstart.rst:90
+#: ../../source/getting_started/quickstart.rst:176
+#: ../../source/getting_started/quickstart.rst:267
+msgid ""
+"**Test** -- open a new terminal and send two requests whose prompts share"
+" a prefix:"
+msgstr "**测试** -- 打开一个新终端并发送两个共享前缀的请求："
+
+#: ../../source/getting_started/quickstart.rst:93
+#: ../../source/getting_started/quickstart.rst:179
+#: ../../source/getting_started/quickstart.rst:270
+msgid "**First request**"
+msgstr "**第一次请求**"
+
+#: ../../source/getting_started/quickstart.rst:106
+#: ../../source/getting_started/quickstart.rst:192
+#: ../../source/getting_started/quickstart.rst:283
+msgid "**Second request**"
+msgstr "**第二个请求**"
+
+#: ../../source/getting_started/quickstart.rst:119
+msgid ""
+"**You should see LMCache logs like this** -- in MP mode the "
+"store/retrieve logs come from the standalone ``lmcache server`` process, "
+"one entry per chunk."
+msgstr ""
+"**您应该看到类似于这样的 LMCache 日志** -- 在 MP 模式下，存储/检索日志来自独立的 ``lmcache server`` "
+"进程，每个条目对应一个块。"
+
+#: ../../source/getting_started/quickstart.rst:123
+msgid "**First request** -- cache is empty, so every aligned chunk is offloaded:"
+msgstr "**第一次请求** -- 缓存为空，因此每个对齐的块都被卸载："
+
+#: ../../source/getting_started/quickstart.rst:133
+msgid ""
+"**Second request** -- the shared prefix is retrieved from CPU RAM; only "
+"the new tail is stored:"
+msgstr "**第二个请求** -- 共享前缀从 CPU 内存中检索；只有新的尾部被存储："
+
+#: ../../source/getting_started/quickstart.rst:143
+msgid ""
+"For request-level statistics (hit ratio, bytes transferred) see "
+":doc:`../mp/observability/index`."
+msgstr "有关请求级统计信息（命中率、传输字节数），请参见 :doc:`../mp/observability/index`。"
+
+#: ../../source/getting_started/quickstart.rst
+msgid "In-process mode"
+msgstr "进程内模式"
+
+#: ../../source/getting_started/quickstart.rst:149
+msgid "Start vLLM with LMCache embedded in the engine process:"
+msgstr "在引擎进程中启动嵌入了 LMCache 的 vLLM："
+
+#: ../../source/getting_started/quickstart.rst:160
+msgid ""
+"To customize further, create a config file. See "
+":doc:`../api_reference/configurations` for all options."
+msgstr "要进一步自定义，请创建一个配置文件。有关所有选项，请参见 :doc:`../api_reference/configurations`。"
+
+#: ../../source/getting_started/quickstart.rst:163
+msgid "**Alternative simpler command:**"
+msgstr "**替代的简单命令：**"
+
+#: ../../source/getting_started/quickstart.rst:172
+msgid ""
+"The ``--disable-hybrid-kv-cache-manager`` flag is mandatory. All "
+"configuration options from the :doc:`../api_reference/configurations` "
+"page still apply."
+msgstr ""
+"``--disable-hybrid-kv-cache-manager`` 标志是必需的。来自 "
+":doc:`../api_reference/configurations` 页面的所有配置选项仍然适用。"
+
+#: ../../source/getting_started/quickstart.rst:205
+msgid ""
+"**You should see LMCache logs like this** -- in-process mode emits the "
+"logs inline with the vLLM engine core."
+msgstr "**您应该看到类似这样的 LMCache 日志** -- 进程内模式会将日志与 vLLM 引擎核心内联输出。"
+
+#: ../../source/getting_started/quickstart.rst:208
+msgid "**First request** -- prompt is offloaded to LMCache:"
+msgstr "**第一次请求** -- 提示被卸载到 LMCache："
+
+#: ../../source/getting_started/quickstart.rst:214
+msgid "**Second request** -- hits the cache and stores the new tail:"
+msgstr "**第二个请求** -- 命中缓存并存储新的尾部："
+
+#: ../../source/getting_started/quickstart.rst:223
+msgid "**Total tokens 32**: The new prompt has 32 tokens after tokenization."
+msgstr "**总令牌 32**\\ ：新提示在分词后有 32 个令牌。"
+
+#: ../../source/getting_started/quickstart.rst:224
+msgid ""
+"**LMCache hit tokens: 24**: 24 tokens (full 8-token chunks) were found in"
+" the cache from the first request that stored 31 tokens."
+msgstr "**LMCache 命中令牌: 24**: 从第一个请求中找到 24 个令牌（完整的 8 令牌块），该请求存储了 31 个令牌。"
+
+#: ../../source/getting_started/quickstart.rst:225
+msgid ""
+"**Need to load: 8**: vLLM auto prefix caching uses block size 16; 16 "
+"tokens already sit in GPU RAM, so LMCache only loads 24-16=8."
+msgstr "**需要加载: 8**: vLLM 自动前缀缓存使用块大小 16；16 个令牌已经存储在显存中，因此 LMCache 只加载 24-16=8。"
+
+#: ../../source/getting_started/quickstart.rst:226
+msgid ""
+"**Why 24 hit tokens instead of 31?** LMCache hashes every 8 tokens (8, "
+"16, 24, 31). It matches page-aligned chunks, so it uses the 24-token "
+"hash."
+msgstr ""
+"**为什么是 24 个命中令牌而不是 31 个？** LMCache 每 8 个令牌（8、16、24、31）进行哈希。它匹配页面对齐的块，因此使用"
+" 24 令牌哈希。"
+
+#: ../../source/getting_started/quickstart.rst:227
+msgid ""
+"**Stored another 8 tokens**: The new 8 tokens form a full chunk and are "
+"stored for future reuse."
+msgstr "**存储另外 8 个令牌**\\ ：这 8 个新令牌形成一个完整的块，并被存储以供将来重用。"
+
+#: ../../source/getting_started/quickstart.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/getting_started/quickstart.rst:232
+msgid ""
+"The SGLang integration now defaults to MP (multi-process) mode. Please "
+"refer to `examples/sgl_integration/README.md`_ for the current setup "
+"instructions."
+msgstr "SGLang 集成现在默认使用 MP（多进程）模式。请参考 `examples/sgl_integration/README.md`_ 以获取当前的设置说明。"
+
+#: ../../source/getting_started/quickstart.rst:237
+msgid "**Install SGLang**"
+msgstr "**安装 SGLang**"
+
+#: ../../source/getting_started/quickstart.rst:245
+msgid "**Start SGLang with LMCache**"
+msgstr "**使用 LMCache 启动 SGLang**"
+
+#: ../../source/getting_started/quickstart.rst:265
+msgid ""
+"Configure LMCache via the config file. See "
+":doc:`../api_reference/configurations` for the full list."
+msgstr "通过配置文件配置 LMCache。有关完整列表，请参见 :doc:`../api_reference/configurations`。"
+
+#: ../../source/getting_started/quickstart.rst:296
+msgid "**You should see LMCache logs like this:**"
+msgstr "**您应该看到类似于以下的 LMCache 日志：**"
+
+#: ../../source/getting_started/quickstart.rst:298
+msgid "**First request** -- prompt plus generated tokens are stored:"
+msgstr "**第一次请求** -- 提示词和生成的令牌被存储："
+
+#: ../../source/getting_started/quickstart.rst:307
+msgid ""
+"**Second request** -- Radix Cache and LMCache share the prefix; only the "
+"new portion is stored:"
+msgstr "**第二个请求** -- Radix Cache 和 LMCache 共享前缀；仅存储新部分："
+
+#: ../../source/getting_started/quickstart.rst:317
+msgid ""
+"**Total tokens 140**: SGLang stores KV cache for both prefill and decode "
+"tokens together, so total = 40 prompt + 100 generated = 140 tokens."
+msgstr ""
+"**总令牌 140**\\ ：SGLang 将 KV Cache 存储用于 Prefill 和解码令牌，因此总计 = 40 提示 + 100 生成"
+" = 140 令牌。"
+
+#: ../../source/getting_started/quickstart.rst:318
+msgid ""
+"**Cached tokens: 30**: SGLang's Radix Attention Cache reused 30 tokens "
+"from the first request."
+msgstr "**缓存的令牌: 30**: SGLang 的 Radix Attention Cache 重用了来自第一次请求的 30 个令牌。"
+
+#: ../../source/getting_started/quickstart.rst:319
+msgid ""
+"**LMCache hit tokens: 24**: LMCache detected 24 tokens (3 full 8-token "
+"chunks) stored from the first request. Since Radix Cache already provides"
+" 30 tokens in GPU memory, these 24 tokens don't need to be loaded from "
+"LMCache or stored again."
+msgstr ""
+"**LMCache 命中令牌: 24**: LMCache 检测到从第一次请求中存储的 24 个令牌（3 个完整的 8 令牌块）。由于 Radix"
+" Cache 已经在显存中提供了 30 个令牌，因此这 24 个令牌不需要从 LMCache 加载或再次存储。"
+
+#: ../../source/getting_started/quickstart.rst:320
+msgid ""
+"**New tokens: 10**: Only 10 prompt tokens need prefill computation (40 "
+"prompt - 30 cached = 10)."
+msgstr "**新令牌：10**\\ ：只有 10 个提示令牌需要进行 Prefill 计算（40 个提示 - 30 个缓存 = 10）。"
+
+#: ../../source/getting_started/quickstart.rst:321
+msgid ""
+"**Stored 112 out of 140**: 24 tokens (3 full chunks) are already in "
+"LMCache and skipped. Of the remaining 116 tokens, 112 (14 full 8-token "
+"chunks) are stored."
+msgstr ""
+"**140 个中存储了 112 个**\\ ：24 个令牌（3 个完整块）已在 LMCache 中，予以跳过。在剩余的 116 个令牌中，112 "
+"个（14 个完整的 8 令牌块）被存储。"
+
+#: ../../source/getting_started/quickstart.rst
+msgid "TensorRT-LLM"
+msgstr "TensorRT-LLM"
+
+#: ../../source/getting_started/quickstart.rst:326
+msgid ""
+"This integration depends on the connector preset registry from `NVIDIA"
+"/TensorRT-LLM PR #12626 <https://github.com/NVIDIA/TensorRT-"
+"LLM/pull/12626>`_ and the matching LMCache adapter, neither of which has "
+"shipped in a stable release yet. Until they do, install both from source:"
+msgstr ""
+"此集成依赖于 `NVIDIA/TensorRT-LLM PR #12626 <https://github.com/NVIDIA"
+"/TensorRT-LLM/pull/12626>`_ 中的连接器预设注册表和匹配的 LMCache "
+"适配器，这两者尚未在稳定版本中发布。在它们发布之前，请从源代码安装这两者："
+
+#: ../../source/getting_started/quickstart.rst:343
+msgid "Once both ship in a stable release, the install command will be:"
+msgstr "一旦两者在稳定版本中发布，安装命令将是："
+
+#: ../../source/getting_started/quickstart.rst:350
+msgid ""
+"LMCache integrates with TensorRT-LLM via TRT-LLM's **KV Cache Connector**"
+" API and supports two deployment modes:"
+msgstr ""
+"LMCache 通过 TRT-LLM 的 **KV Cache Connector** API 与 TensorRT-LLM "
+"集成，并支持两种部署模式："
+
+#: ../../source/getting_started/quickstart.rst:353
+msgid ""
+"**In-process mode** (``connector: lmcache``) -- LMCache runs as a "
+"singleton inside the TRT-LLM process. Simplest setup; no extra service to"
+" manage."
+msgstr ""
+"**进程内模式** (``connector: lmcache``) -- LMCache 作为单例在 TRT-LLM "
+"进程内运行。最简单的设置；无需管理额外的服务。"
+
+#: ../../source/getting_started/quickstart.rst:356
+msgid ""
+"**MP mode** (``connector: lmcache-mp``) -- LMCache runs as a standalone "
+"server. Multiple TRT-LLM workers on the same node can share the cache, "
+"and the cache survives a TRT-LLM crash."
+msgstr ""
+"**MP 模式** (``connector: lmcache-mp``) -- LMCache 作为独立服务器运行。多个 TRT-LLM "
+"工作进程可以共享缓存，并且缓存在 TRT-LLM 崩溃后仍然存在。"
+
+#: ../../source/getting_started/quickstart.rst:366
+msgid "Configure LMCache via env vars:"
+msgstr "通过环境变量配置 LMCache："
+
+#: ../../source/getting_started/quickstart.rst:375
+msgid "Build the TRT-LLM ``LLM`` with ``connector: lmcache``:"
+msgstr "使用 ``connector: lmcache`` 构建 TRT-LLM ``LLM``\\ ："
+
+#: ../../source/getting_started/quickstart.rst
+msgid "MP mode"
+msgstr "MP 模式"
+
+#: ../../source/getting_started/quickstart.rst:397
+msgid ""
+"``PYTHONHASHSEED=0`` must be set in **both** terminals -- chunk hashing "
+"depends on a stable ``hash()``, and the server and client must agree on "
+"the seed."
+msgstr ""
+"``PYTHONHASHSEED=0`` 必须在 **两个** 终端中设置 -- 块哈希依赖于稳定的 ``hash()``\\ "
+"，服务器端与客户端必须使用相同的种子值。"
+
+#: ../../source/getting_started/quickstart.rst:401
+msgid "Start the LMCache server:"
+msgstr "启动 LMCache 服务器："
+
+#: ../../source/getting_started/quickstart.rst:409
+msgid "In a separate terminal, point TRT-LLM at the server via ``server_url``:"
+msgstr "在另一个终端中，通过 ``server_url`` 将 TRT-LLM 指向服务器："
+
+#: ../../source/getting_started/quickstart.rst:417
+msgid "where ``run_trtllm.py`` contains:"
+msgstr "其中 ``run_trtllm.py`` 包含："
+
+#: ../../source/getting_started/quickstart.rst:440
+msgid ""
+"The TRT-LLM adapter reads :class:`LMCacheEngineConfig` the same way the "
+"vLLM adapter does: ``LMCACHE_CONFIG_FILE`` for a YAML file, otherwise "
+"individual ``LMCACHE_*`` environment variables. See "
+":doc:`../api_reference/configurations` for all options."
+msgstr ""
+"TRT-LLM 适配器以与 vLLM 适配器相同的方式读取 :class:`LMCacheEngineConfig`：对于 YAML 文件使用 "
+"``LMCACHE_CONFIG_FILE``\\ ，否则使用单独的 ``LMCACHE_*`` 环境变量。有关所有选项，请参见 "
+":doc:`../api_reference/configurations`。"
+
+#: ../../source/getting_started/quickstart.rst:446
+msgid ""
+"🎉 **You now have LMCache caching and reusing KV caches across all three "
+"engines.**"
+msgstr "🎉 **您现在可以在所有三个引擎中使用 LMCache 缓存和重用 KV 缓存。**"
+
+#: ../../source/getting_started/quickstart.rst:449
+msgid "More MP server options"
+msgstr "更多 MP 服务器选项"
+
+#: ../../source/getting_started/quickstart.rst:451
+msgid ""
+"The vLLM MP example above runs ``lmcache server`` locally on the default "
+"ports. Common variations:"
+msgstr "上述的 vLLM MP 示例在默认端口上本地运行 ``lmcache server``\\ 。常见变体："
+
+#: ../../source/getting_started/quickstart.rst:454
+msgid ""
+"**Custom port or remote host** -- by default the connector talks to "
+"``localhost:5555``. To use a different port, or a server on another host,"
+" pass ``lmcache.mp.host`` / ``lmcache.mp.port`` in "
+"``kv_connector_extra_config``:"
+msgstr ""
+"**自定义端口或远程主机** -- 默认情况下，连接器与 ``localhost:5555`` 通信。要使用不同的端口或其他主机上的服务器，请在 "
+"``kv_connector_extra_config`` 中传递 ``lmcache.mp.host`` / "
+"``lmcache.mp.port``\\ ："
+
+#: ../../source/getting_started/quickstart.rst:464
+msgid ""
+"**CPU-only (no GPU)** -- the server runs with a ``StubCPUDevice`` and "
+"shares KV tensors with vLLM over POSIX shared memory. Start ``lmcache "
+"server`` normally, then set "
+"``lmcache.mp.mp_transfer_mode=lmcache_driven`` on the vLLM side to enable"
+" the zero-copy SHM handle path (the default ``auto`` routing maps non-"
+"CUDA devices to ``engine_driven``, which uses the worker-side "
+"gather/scatter copy path instead)."
+msgstr "**仅 CPU（无 GPU）** -- 服务器使用 ``StubCPUDevice`` 运行，并通过 POSIX 共享内存与 vLLM 共享 KV 张量。正常启动 ``lmcache server``，然后在 vLLM 端设置 ``lmcache.mp.mp_transfer_mode=lmcache_driven`` 以启用零拷贝 SHM 句柄路径（默认的 ``auto`` 路由将非 CUDA 设备映射到 ``engine_driven``，该模式使用工作端的聚集/分散拷贝路径）。"
+
+#: ../../source/getting_started/quickstart.rst:471
+msgid "**Docker** -- see :doc:`../production/docker_deployment`."
+msgstr "**Docker** -- 请参阅 :doc:`../production/docker_deployment`。"
+
+#: ../../source/getting_started/quickstart.rst:473
+msgid ""
+"**HTTP management endpoints** (health, clear-cache, status) -- see "
+":doc:`../mp/http_api`."
+msgstr "**HTTP 管理端点**\\ （健康检查、清除缓存、状态）-- 请参见 :doc:`../mp/http_api`。"
+
+#: ../../source/getting_started/quickstart.rst:477
+msgid "Next Steps"
+msgstr "下一步"
+
+#: ../../source/getting_started/quickstart.rst:479
+msgid ""
+"**Performance Testing**: Try the :doc:`benchmarking` section to "
+"experience LMCache's performance benefits with more comprehensive "
+"examples"
+msgstr "**性能测试**\\ ：尝试 :doc:`benchmarking` 部分，以体验 LMCache 的性能优势和更全面的示例。"
+
+#: ../../source/getting_started/quickstart.rst:480
+msgid ""
+"**Production**: Deploy LMCache with Docker or Kubernetes, plus "
+"observability and tuning -- see :doc:`../mp/deployment`"
+msgstr ""
+"**生产部署**\\ ：使用 Docker 或 Kubernetes 部署 LMCache，并启用可观察性与调优 -- 请参阅 "
+":doc:`../mp/deployment`。"
+
+#~ msgid ""
+#~ "**More Examples**: Explore the "
+#~ ":doc:`quickstart/index` section for detailed "
+#~ "examples including KV cache sharing "
+#~ "across instances and disaggregated prefill"
+#~ msgstr ""
+#~ "**更多示例**：查看 :doc:`quickstart/index` 部分以获取详细示例，包括跨实例的 "
+#~ "KV Cache 共享和分离式 Prefill。"
+
+#~ msgid "Start vLLM with the MP connector in a separate terminal:"
+#~ msgstr "在另一个终端中使用 MP 连接器启动 vLLM："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/disaggregated_prefill.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/disaggregated_prefill.po
new file mode 100644
index 0000000..1c28206
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/disaggregated_prefill.po
@@ -0,0 +1,293 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:4
+msgid "Example: Disaggregated prefill"
+msgstr "示例：分离式 Prefill"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/disaggregated_prefill`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/disaggregated_prefill`。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:11
+msgid ""
+"With LMCache as a KV cache transfer library, we can run disaggregated "
+"prefill with vLLM. Right now, LMCache uses NIXL as a transport layer to "
+"enable fast KV cache transfer via NVLink, RDMA, or TCP."
+msgstr ""
+"使用 LMCache 作为 KV Cache 传输库，我们可以使用 vLLM 运行分离式 Prefill。目前，LMCache 使用 NIXL "
+"作为传输层，通过 NVLink、RDMA 或 TCP 实现快速的 KV Cache 传输。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:14
+msgid ""
+"This guide demonstrates how to run LMCache with disaggregated prefill "
+"using a single prefiller and decoder setup (1P1D) on a single machine. "
+"The architecture splits the LLM inference into two stages: prefill and "
+"decode, running on separate GPUs for better resource utilization."
+msgstr ""
+"本指南演示如何在单台机器上使用单个预填充器和解码器设置（1P1D）运行带有分离式 Prefill 的 LMCache。该架构将 LLM "
+"推理分为两个阶段：预填充和解码，分别在不同的 GPU 上运行，以更好地利用资源。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:18
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:20
+msgid "Before you begin, ensure you have:"
+msgstr "在开始之前，请确保您具备："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:22
+msgid "At least 2 GPUs"
+msgstr "至少 2 个 GPU"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:23
+msgid "Python packages installed:"
+msgstr "已安装的 Python 包："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:24
+msgid "``lmcache`` (0.2.1 or above)"
+msgstr "``lmcache`` (0.2.1 或更高版本)"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:25
+msgid ""
+"``nixl`` (Install instructions `here <https://github.com/ai-"
+"dynamo/nixl>`_)"
+msgstr "``nixl`` (安装说明 `这里 <https://github.com/ai-dynamo/nixl>`_)"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:26
+msgid "``vllm`` (latest main branch)"
+msgstr "``vllm`` (最新主分支)"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:27
+msgid "``httpx``, ``fastapi``, and ``uvicorn``"
+msgstr "``httpx``, ``fastapi``, 和 ``uvicorn``"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:28
+msgid ""
+"A valid Hugging Face token (``HF_TOKEN``) with access to Llama 3.1 8B "
+"models"
+msgstr "一个有效的 Hugging Face 令牌 (``HF_TOKEN``)，具有访问 Llama 3.1 8B 模型的权限"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:30
+msgid "(Recommended) A machine with NVLink or RDMA enabled GPUs"
+msgstr "（推荐）一台启用 NVLink 或 RDMA 的 GPU 机器"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:34
+msgid ""
+"You can use ``ucx_perftest`` to check the GPU-GPU memory transfer and "
+"verify the NVLink or RDMA connection. Please refer to this link: `UCX "
+"Performance Test <https://ucx-py.readthedocs.io/en/latest/ucx-"
+"debug.html>`_."
+msgstr ""
+"您可以使用 ``ucx_perftest`` 来检查 GPU-GPU 内存传输并验证 NVLink 或 RDMA 连接。请参阅此链接： `UCX "
+"Performance Test <https://ucx-py.readthedocs.io/en/latest/ucx-"
+"debug.html>`_。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:38
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:40
+msgid "The disaggregated prefill setup consists of three main components:"
+msgstr "分离式 Prefill 设置由三个主要组件组成："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:42
+msgid ""
+"**Prefiller Server (Port 8100)**: Handles the prefill phase of LLM "
+"inference"
+msgstr "**Prefill 服务器 (端口 8100)**: 处理 LLM 推理的 Prefill 阶段"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:43
+msgid "**Decoder Server (Port 8200)**: Manages the decoding/generation phase"
+msgstr "**解码器服务器 (端口 8200)**: 管理解码/生成阶段"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:44
+msgid "**Proxy Server (Port 9000)**: Coordinates between prefiller and decoder"
+msgstr "**代理服务器 (端口 9000)**: 协调预填充器和解码器之间的关系"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:47
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:49
+msgid "**Prefiller Server Configuration** (``lmcache-prefiller-config.yaml``):"
+msgstr "**Prefiller Server Configuration** (``lmcache-prefiller-config.yaml``):"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:64
+msgid "**Decoder Server Configuration** (``lmcache-decoder-config.yaml``):"
+msgstr "**解码器服务器配置** (``lmcache-decoder-config.yaml``):"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:81
+msgid "Step-by-Step Setup"
+msgstr "逐步设置"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:83
+msgid "**Environment Setup**"
+msgstr "**环境设置**"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:85
+msgid "Set your Hugging Face token before running the vLLM servers."
+msgstr "在运行 vLLM 服务器之前，请设置您的 Hugging Face 令牌。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:91
+msgid "**Launch the vLLM + LMCache Inference Servers**"
+msgstr "**启动 vLLM + LMCache 推理服务器**"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:93
+msgid "You can launch the components individually:"
+msgstr "您可以单独启动各个组件："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:95
+msgid "Launch Decoder (on GPU 1):"
+msgstr "启动解码器（在 GPU 1 上）："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:108
+msgid "Launch Prefiller (on GPU 0):"
+msgstr "启动 Prefill（在 GPU 0 上）："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:121
+msgid "Launch a proxy server to coordinate between prefiller and decoder:"
+msgstr "启动一个代理服务器，以协调 Prefiller 和解码器："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:123
+msgid ""
+"The code for the proxy server is available `in vLLM repo "
+"<https://github.com/vllm-"
+"project/vllm/blob/main/examples/others/lmcache/disagg_prefill_lmcache_v1/disagg_proxy_server.py>`_."
+msgstr ""
+"代理服务器的代码可在 `vLLM 仓库 <https://github.com/vllm-"
+"project/vllm/blob/main/examples/others/lmcache/disagg_prefill_lmcache_v1/disagg_proxy_server.py>`_"
+" 中找到。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:143
+msgid ""
+"The ``UCX_TLS`` environment variable is used to specify the transport "
+"layer for UCX (the example uses NVLink) The ``CUDA_VISIBLE_DEVICES`` "
+"environment variable is used to specify the GPUs to use for the servers."
+msgstr ""
+"``UCX_TLS`` 环境变量用于指定 UCX 的传输层（示例使用 NVLink）。\\ ``CUDA_VISIBLE_DEVICES`` "
+"环境变量用于指定服务器使用的 GPU。"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:147
+msgid "**Verify Setup**"
+msgstr "**验证设置**"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:149
+msgid "The servers are ready when you can access:"
+msgstr "当您可以访问以下内容时，服务器已准备就绪："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:151
+msgid "Prefiller: ``http://localhost:7100/v1/completions``"
+msgstr "Prefill: ``http://localhost:7100/v1/completions``"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:152
+msgid "Decoder: ``http://localhost:7200/v1/completions``"
+msgstr "解码器: ``http://localhost:7200/v1/completions``"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:153
+msgid "Proxy: ``http://localhost:9100/v1/completions``"
+msgstr "代理: ``http://localhost:9100/v1/completions``"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:156
+msgid "Usage"
+msgstr "使用方法"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:158
+msgid ""
+"Send requests to the proxy server (port 9000) using either the "
+"completions or chat completions endpoint:"
+msgstr "通过 completions 或 chat completions 端点向代理服务器（端口 9000）发送请求："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:170
+msgid ""
+"You can also test the setup with the following command, which runs vLLM's"
+" serving benchmark:"
+msgstr "您还可以使用以下命令测试设置，该命令运行 vLLM 的服务基准测试："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:182
+msgid "Monitoring"
+msgstr "监控"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:184
+msgid "The prefiller instance will log the throughput of KV cache transfer:"
+msgstr "预填充实例将记录 KV Cache 传输的吞吐量："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:186
+msgid ""
+"LMCache INFO: Store 5271 tokens takes: 6.5000 ms, throughput: 98.9889 "
+"GB/s; offload_time: 2.6594 ms, put_time: 3.4539 ms "
+"(cache_engine.py:190:lmcache.v1.cache_engine)"
+msgstr ""
+"LMCache 信息：存储 5271 个 token 耗时：6.5000 毫秒，吞吐量：98.9889 GB/s；卸载时间：2.6594 "
+"毫秒，放置时间：3.4539 毫秒 (cache_engine.py:190:lmcache.v1.cache_engine)"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:188
+msgid ""
+"The decoder instance will log how many tokens are fetched from the "
+"LMCache:"
+msgstr "解码器实例将记录从 LMCache 中获取了多少个 token："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:190
+msgid ""
+"LMCache INFO: Reqid: cmpl-b8bf01cbe47e4d108732ceeb4158d310-0, Total "
+"tokens 5170, LMCache hit tokens: 5169, need to load: 5169 "
+"(vllm_v1_adapter.py:543:lmcache.integration.vllm.vllm_v1_adapter)"
+msgstr ""
+"LMCache 信息：请求 ID：cmpl-b8bf01cbe47e4d108732ceeb4158d310-0，总令牌数 "
+"5170，LMCache 命中令牌：5169，需要加载：5169 "
+"(vllm_v1_adapter.py:543:lmcache.integration.vllm.vllm_v1_adapter)"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:192
+msgid "The proxy server will log the TTFT of the prefiller node:"
+msgstr "代理服务器将记录预填充节点的 TTFT："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:206
+msgid "Troubleshooting"
+msgstr "故障排除"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:208
+msgid "Common issues and solutions:"
+msgstr "常见问题及解决方案："
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:210
+msgid "**GPU Requirements**: Ensure you have at least 2 GPUs available"
+msgstr "**GPU 要求**\\ ：确保您至少有 2 个可用的 GPU"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:211
+msgid "**Port Conflicts**: Check if ports used above are available"
+msgstr "**端口冲突**\\ ：检查上述使用的端口是否可用"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:212
+msgid ""
+"**HF Token**: Verify your token starts with ``hf_`` and has necessary "
+"model access"
+msgstr "**HF Token**: 验证您的令牌是否以 ``hf_`` 开头，并具有必要的模型访问权限"
+
+#: ../../source/getting_started/quickstart/disaggregated_prefill.rst:213
+msgid ""
+"**CUDA Errors**: Ensure CUDA_VISIBLE_DEVICES is set correctly for each "
+"server"
+msgstr "**CUDA 错误**\\ ：确保每个服务器的 CUDA_VISIBLE_DEVICES 设置正确"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/index.po
new file mode 100644
index 0000000..dc9d5b1
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/index.po
@@ -0,0 +1,168 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart/index.rst:4
+msgid "More Examples"
+msgstr "更多示例"
+
+#: ../../source/getting_started/quickstart/index.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/getting_started/quickstart/index.rst:11
+msgid ""
+"This section provides quick examples to help you get started with "
+"LMCache's key features."
+msgstr "本节提供快速示例，以帮助您开始使用 LMCache 的关键功能。"
+
+#: ../../source/getting_started/quickstart/index.rst:14
+msgid "KV Cache Offloading"
+msgstr "KV Cache 卸载"
+
+#: ../../source/getting_started/quickstart/index.rst:16
+msgid ""
+"KV cache offloading allows you to move KV caches from GPU memory to CPU "
+"memory or other storage devices. This feature is particularly useful "
+"when:"
+msgstr "KV Cache 卸载允许您将 KV 缓存从显存移动到 CPU 内存或其他存储设备。此功能在以下情况下特别有用："
+
+#: ../../source/getting_started/quickstart/index.rst:18
+msgid ""
+"There are requests shares the same prefix (e.g., long system prompt, "
+"reusing chat history in chat applications, or caching offline-processed "
+"data)."
+msgstr "存在共享相同前缀的请求（例如，长系统提示、在聊天应用中重用聊天历史或缓存离线处理的数据）。"
+
+#: ../../source/getting_started/quickstart/index.rst:19
+msgid "The GPU memory is limited to save all the KV caches."
+msgstr "显存有限，无法保存所有的 KV Cache。"
+
+#: ../../source/getting_started/quickstart/index.rst:21
+msgid ""
+"By offloading KV caches, LMCache can reduce both time-to-first-token "
+"(TTFT) and GPU cycles."
+msgstr "通过卸载 KV 缓存，LMCache 可以减少首次令牌时间 (TTFT) 和显存周期。"
+
+#: ../../source/getting_started/quickstart/index.rst:23
+msgid "See :ref:`offload_kv_cache` for more details."
+msgstr "有关更多详细信息，请参见 :ref:`offload_kv_cache`。"
+
+#: ../../source/getting_started/quickstart/index.rst:26
+msgid "KV Cache Sharing"
+msgstr "KV Cache 共享"
+
+#: ../../source/getting_started/quickstart/index.rst:28
+msgid ""
+"KV cache sharing enables sharing the KV cache across different LLM "
+"instances. This feature is beneficial when:"
+msgstr "KV Cache 共享允许在不同的 LLM 实例之间共享 KV Cache。当满足以下条件时，此功能非常有用："
+
+#: ../../source/getting_started/quickstart/index.rst:30
+msgid "There are multiple LLM instances running in the same system."
+msgstr "在同一系统中运行多个 LLM 实例。"
+
+#: ../../source/getting_started/quickstart/index.rst:31
+msgid "The requests that share the same prefix may go to different LLM instances."
+msgstr "具有相同前缀的请求可能会发送到不同的 LLM 实例。"
+
+#: ../../source/getting_started/quickstart/index.rst:33
+msgid ""
+"Sharing KV caches also reduces TTFT and GPU computation by eliminating "
+"redundant calculations across different LLM instances."
+msgstr "共享 KV Cache 还通过消除不同 LLM 实例之间的冗余计算来减少 TTFT 和 GPU 计算。"
+
+#: ../../source/getting_started/quickstart/index.rst:35
+msgid "See :ref:`share_kv_cache` for more details."
+msgstr "有关更多详细信息，请参阅 :ref:`share_kv_cache`。"
+
+#: ../../source/getting_started/quickstart/index.rst:38
+msgid "Disaggregated Prefill"
+msgstr "分离式预填充"
+
+#: ../../source/getting_started/quickstart/index.rst:40
+msgid ""
+"Disaggregated prefill separates the prefill and decode phases across "
+"different compute resources. This approach:"
+msgstr "分离式 Prefill 将预填充和解码阶段分开，使用不同的计算资源。此方法："
+
+#: ../../source/getting_started/quickstart/index.rst:42
+msgid "Allows specialized hardware allocation for each phase of inference"
+msgstr "允许为推理的每个阶段分配专用硬件"
+
+#: ../../source/getting_started/quickstart/index.rst:43
+msgid "Enables more efficient resource utilization in distributed settings"
+msgstr "在分布式环境中实现更高效的资源利用。"
+
+#: ../../source/getting_started/quickstart/index.rst:44
+msgid ""
+"Improves overall system throughput by optimizing for the different "
+"computational patterns of prefill vs. decode"
+msgstr "通过优化 Prefill 和解码的不同计算模式，提高整体系统吞吐量。"
+
+#: ../../source/getting_started/quickstart/index.rst:46
+msgid ""
+"This architecture is particularly valuable in large-scale deployment "
+"scenarios where maximizing resource efficiency and keeping a stable "
+"generation speed are both important."
+msgstr "这种架构在大规模部署场景中尤其有价值，在这些场景中，最大化资源效率和保持稳定的生成速度都很重要。"
+
+#: ../../source/getting_started/quickstart/index.rst:48
+msgid "See :ref:`disaggregated_prefill` for more details."
+msgstr "有关更多详细信息，请参见 :ref:`disaggregated_prefill`。"
+
+#: ../../source/getting_started/quickstart/index.rst:51
+msgid "Standalone Starter"
+msgstr "独立启动器"
+
+#: ../../source/getting_started/quickstart/index.rst:53
+msgid ""
+"The LMCache Standalone Starter allows you to run LMCacheEngine as a "
+"standalone service without vLLM or GPU dependencies. This is particularly"
+" useful for:"
+msgstr "LMCache 独立启动器允许您将 LMCacheEngine 作为独立服务运行，而无需 vLLM 或 GPU 依赖。这对于以下情况特别有用："
+
+#: ../../source/getting_started/quickstart/index.rst:55
+msgid "Testing and development environments"
+msgstr "测试和开发环境"
+
+#: ../../source/getting_started/quickstart/index.rst:56
+msgid "CPU-only deployments"
+msgstr "仅 CPU 部署"
+
+#: ../../source/getting_started/quickstart/index.rst:57
+msgid "Distributed cache scenarios"
+msgstr "分布式缓存场景"
+
+#: ../../source/getting_started/quickstart/index.rst:58
+msgid "Integration with custom applications"
+msgstr "与自定义应用程序集成"
+
+#: ../../source/getting_started/quickstart/index.rst:60
+msgid "See :ref:`standalone_starter` for more details."
+msgstr "有关更多详细信息，请参阅 :ref:`standalone_starter`。"
+
+#: ../../source/getting_started/quickstart/index.rst:63
+msgid "Detailed Examples"
+msgstr "详细示例"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/multimodality.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/multimodality.po
new file mode 100644
index 0000000..e2ff325
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/multimodality.po
@@ -0,0 +1,80 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:2
+msgid "Example: Multimodal KV Cache Support"
+msgstr "示例：多模态 KV Cache 支持"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:10
+msgid "Quick Start Example (Audio Model):"
+msgstr "快速入门示例（音频模型）："
+
+#: ../../source/getting_started/quickstart/multimodality.rst:12
+msgid ""
+"We  going to be running audio inference with "
+"``ultravox-v0_5-llama-3_2-1b`` and using LMCache to speed up the TTFT "
+"after the first request."
+msgstr "我们将使用 ``ultravox-v0_5-llama-3_2-1b`` 进行音频推理，并使用 LMCache 加速第一次请求后的 TTFT。"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:14
+msgid "**Install and Serve:**"
+msgstr "**安装和服务：**"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:16
+msgid "``pip install lmcache vllm[audio] openai``"
+msgstr "``pip install lmcache vllm[audio] openai``"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:25
+msgid "**Benchmark:**"
+msgstr "**基准测试：**"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:27
+msgid "Save as ``audio_query.py``"
+msgstr "保存为 ``audio_query.py``"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:174
+msgid "**Run and see TTFT speedup:**"
+msgstr "**运行并查看 TTFT 加速：**"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:185
+msgid "**Retrieval and speed up in logs:**"
+msgstr "**检索和日志中的加速：**"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:187
+msgid "After First Request:"
+msgstr "首次请求后："
+
+#: ../../source/getting_started/quickstart/multimodality.rst:196
+#: ../../source/getting_started/quickstart/multimodality.rst:218
+msgid "*Example Output:*"
+msgstr "示例输出:"
+
+#: ../../source/getting_started/quickstart/multimodality.rst:209
+msgid "After Second Request:"
+msgstr "第二次请求后："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/offload_kv_cache.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/offload_kv_cache.po
new file mode 100644
index 0000000..ef8ce0b
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/offload_kv_cache.po
@@ -0,0 +1,362 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:4
+msgid "Example: Offload KV cache to CPU"
+msgstr "示例：将 KV Cache 卸载到 CPU"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP mode </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:11
+msgid "In this example, we will show you how to offload KV cache to CPU memory."
+msgstr "在这个示例中，我们将向您展示如何将 KV Cache 卸载到 CPU 内存。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:14
+msgid ""
+"Besides CPU memory, LMCache also supports offloading KV cache to many "
+"different destinations. See "
+":ref:`getting_started/quickstart/offload_kv_cache:Supported offloading "
+"destinations` for more details."
+msgstr ""
+"除了 CPU 内存，LMCache 还支持将 KV Cache 卸载到许多不同的目标。有关更多详细信息，请参见 "
+":ref:`getting_started/quickstart/offload_kv_cache:Supported offloading "
+"destinations`。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:18
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:20
+msgid "Before you begin, make sure you have:"
+msgstr "在开始之前，请确保您具备："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:22
+msgid "vLLM v1 with LMCache installed (see :doc:`Installation <../installation>`)"
+msgstr "安装了 LMCache 的 vLLM v1（请参见 :doc:`安装 <../installation>`）"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:23
+msgid "A GPU that can run a LLM"
+msgstr "可以运行 LLM 的 GPU"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:27
+msgid "Use CPU offloading in offline inference"
+msgstr "在离线推理中使用 CPU 卸载"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:29
+msgid ""
+"This section demonstrates how to use CPU memory offloading in offline "
+"inference scenarios using LMCache with vLLM. The example script we use "
+"here is available in `vLLM examples <https://github.com/vllm-"
+"project/vllm/blob/main/examples/others/lmcache/cpu_offload_lmcache.py>`_."
+" See the `examples README <https://github.com/vllm-"
+"project/vllm/tree/main/examples/others/lmcache#2-cpu-offload-examples>`_ "
+"to understand how to run the script for vLLM v1."
+msgstr ""
+"本节演示如何在离线推理场景中使用 LMCache 和 vLLM 进行 CPU 内存卸载。我们在这里使用的示例脚本可以在 `vLLM "
+"examples <https://github.com/vllm-"
+"project/vllm/blob/main/examples/others/lmcache/cpu_offload_lmcache.py>`_ "
+"中找到。请参阅 `examples README <https://github.com/vllm-"
+"project/vllm/tree/main/examples/others/lmcache#2-cpu-offload-examples>`_ "
+"以了解如何运行 vLLM v1 的脚本。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:33
+msgid "First, set up the necessary environment variables for LMCache:"
+msgstr "首先，设置 LMCache 所需的环境变量："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:46
+msgid "Next, configure vLLM with LMCache integration:"
+msgstr "接下来，配置 vLLM 与 LMCache 集成："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:66
+msgid "Now you can run inference with automatic KV cache offloading:"
+msgstr "现在您可以通过自动卸载 KV Cache 来进行推理："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:85
+msgid "When the inference is complete, clean up the LMCache backend:"
+msgstr "推理完成后，清理 LMCache 后端："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:94
+msgid ""
+"During inference, LMCache will automatically handle storing and managing "
+"KV cache in CPU memory. You can monitor this through the logs, which will"
+" show messages like::"
+msgstr "在推理过程中，LMCache 将自动处理在 CPU 内存中存储和管理 KV Cache。您可以通过日志监控这一过程，日志中会显示类似于以下消息："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:98
+msgid ""
+"This indicates that the KV cache has been successfully offloaded to CPU "
+"memory."
+msgstr "这表明 KV Cache 已成功卸载到 CPU 内存。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:101
+msgid "Adjust ``gpu_memory_utilization`` based on your GPU's available memory"
+msgstr "根据您的 GPU 可用内存调整 ``gpu_memory_utilization``"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:102
+msgid ""
+"The CPU offloading buffer size can be adjusted through "
+"``LMCACHE_MAX_LOCAL_CPU_SIZE``"
+msgstr "可以通过 ``LMCACHE_MAX_LOCAL_CPU_SIZE`` 调整 CPU 卸载缓冲区大小。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:105
+msgid "Use CPU offloading in online inference"
+msgstr "在在线推理中使用 CPU 卸载"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:107
+msgid ""
+"This section demonstrates how to use CPU memory offloading in online "
+"serving scenarios."
+msgstr "本节演示如何在在线服务场景中使用 CPU 内存卸载。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:109
+msgid ""
+"First, create a configuration file named ``lmcache_config.yaml`` with the"
+" following content:"
+msgstr "首先，创建一个名为 ``lmcache_config.yaml`` 的配置文件，内容如下："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:118
+msgid ""
+"LMCache supports extensive configuration through a "
+"``lmcache_config.yaml`` file where you can customize chunk sizes, memory "
+"limits, storage backends, and more. We'll cover advanced configuration "
+"options in later examples. For now, let's run a minimal example with "
+"default configuration."
+msgstr ""
+"LMCache 支持通过 ``lmcache_config.yaml`` "
+"文件进行广泛的配置，您可以在其中自定义块大小、内存限制、存储后端等更多内容。我们将在后面的示例中介绍高级配置选项。现在，让我们运行一个使用默认配置的最小示例。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:120
+msgid ""
+"Launch the vLLM server with LMCache integration using environment "
+"variables. Here's an example command:"
+msgstr "使用环境变量启动集成了 LMCache 的 vLLM 服务器。以下是一个示例命令："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:132
+msgid "Key parameters explained:"
+msgstr "关键参数说明："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:134
+msgid "``LMCACHE_CONFIG_FILE``: Path to the LMCache configuration file."
+msgstr "``LMCACHE_CONFIG_FILE``: LMCache 配置文件的路径。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:135
+msgid "``--kv-transfer-config``: Configures LMCache integration"
+msgstr "``--kv-transfer-config``: 配置 LMCache 集成"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:136
+msgid "``kv_connector``: Specifies the LMCache connector"
+msgstr "``kv_connector``: 指定 LMCache 连接器"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:137
+msgid "``kv_role``: Set to \"kv_both\" for both storing and loading KV cache"
+msgstr "``kv_role``: 设置为 \\\"kv_both\\\" 以同时存储和加载 KV Cache"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:139
+msgid ""
+"Once the server is running, you can send requests to it using curl. "
+"Here's an example of how to send a request to the vLLM server with "
+"LMCache integration:"
+msgstr "一旦服务器运行起来，您可以使用 curl 向其发送请求。以下是如何向集成了 LMCache 的 vLLM 服务器发送请求的示例："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:152
+msgid "You should see the following logs:"
+msgstr "您应该看到以下日志："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:159
+msgid ""
+"Once you send the same curl request again, you should see the following "
+"logs:"
+msgstr "一旦您再次发送相同的 curl 请求，您应该会看到以下日志："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:168
+msgid "Example: CPU offloading benefits"
+msgstr "示例：CPU 卸载的好处"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:170
+msgid ""
+"This section demonstrates the performance benefits of using CPU "
+"offloading with LMCache. We'll use a script that generates multiple "
+"prompts and compare the performance with and without LMCache."
+msgstr "本节演示了使用 CPU 卸载与 LMCache 结合的性能优势。我们将使用一个生成多个提示的脚本，并比较使用和不使用 LMCache 的性能。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:173
+msgid "Prerequisites (Setup)"
+msgstr "前提条件（设置）"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:175
+msgid "A CUDA GPU. The example picks a model that fits the GPU automatically:"
+msgstr "一块 CUDA GPU。示例会自动选择适合该 GPU 的模型："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:177
+msgid ""
+"``Qwen/Qwen3-8B`` (bf16) when the GPU has ~36 GiB or more (e.g. A100-80G,"
+" H100)."
+msgstr "``Qwen/Qwen3-8B`` (bf16) 当显存大约为 36 GiB 或更多时（例如 A100-80G, H100）。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:178
+msgid ""
+"``Qwen/Qwen3-8B-FP8`` with ``kv_cache_dtype=\"fp8\"`` when the GPU has "
+"~24 GiB and supports native FP8 (Ada Lovelace / Hopper, ``sm_89+``; e.g. "
+"L4, L40, RTX 4090)."
+msgstr ""
+"``Qwen/Qwen3-8B-FP8`` 与 ``kv_cache_dtype=\"fp8\"`` 当 GPU 具有约 24 GiB 并支持原生"
+" FP8（Ada Lovelace / Hopper，``sm_89+``；例如 L4、L40、RTX 4090）。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:180
+msgid ""
+"``Qwen/Qwen3-1.7B`` as the fallback for smaller GPUs (~10 GiB and up), "
+"including Ampere 24 GiB cards (RTX A5000, RTX 3090) where FP8 is "
+"unsupported."
+msgstr ""
+"``Qwen/Qwen3-1.7B`` 作为较小显卡的后备选择（约 10 GiB 及以上），包括不支持 FP8 的安培 24 GiB 显卡（RTX"
+" A5000、RTX 3090）。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:183
+msgid ""
+"Sufficient CPU memory. The example clamps the LMCache pinned host buffer "
+"to fit your system RAM and ``RLIMIT_MEMLOCK`` (``ulimit -l``), so it also"
+" works on smaller hosts without manual tuning."
+msgstr ""
+"足够的 CPU 内存。该示例将 LMCache 固定主机缓冲区限制为适合您的系统 RAM 和 ``RLIMIT_MEMLOCK`` "
+"(``ulimit -l``)，因此它也可以在不进行手动调整的小型主机上运行。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:188
+msgid "Example script"
+msgstr "示例脚本"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:190
+msgid "Save the following script as ``cpu-offloading.py``:"
+msgstr "将以下脚本保存为 ``cpu-offloading.py``："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:410
+msgid "Running the Example"
+msgstr "运行示例"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:412
+msgid "First, run the script without LMCache:"
+msgstr "首先，运行不带 LMCache 的脚本："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:418
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:433
+msgid "You'll see output like:"
+msgstr "您将看到类似的输出："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:424
+msgid ""
+"Without LMCache, there's no speedup between runs even if vLLM has prefix "
+"caching enabled. This is because the KV cache exceeds GPU memory and "
+"can't be reused."
+msgstr "没有 LMCache，即使 vLLM 启用了前缀缓存，运行之间也没有加速。这是因为 KV Cache 超出了显存，无法被重用。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:427
+msgid "Now, run with LMCache enabled:"
+msgstr "现在，启用 LMCache 运行："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:439
+msgid ""
+"The significant speedup in the second case demonstrates how LMCache "
+"effectively manages KV cache offloading to CPU memory. When the total "
+"size of KV cache exceeds GPU memory, LMCache allows you to store and "
+"reuse the cache from CPU memory, resulting in much faster subsequent "
+"generations for prompts with shared prefixes."
+msgstr ""
+"第二种情况显著的加速展示了 LMCache 如何有效管理 KV Cache 卸载到 CPU 内存。当 KV Cache "
+"的总大小超过显存时，LMCache 允许您从 CPU 内存中存储和重用缓存，从而为具有共享前缀的提示生成更快的后续结果。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:445
+msgid "Supported offloading destinations"
+msgstr "支持的卸载目标"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:447
+msgid "LMCache now supports offloading KV cache to the following destinations:"
+msgstr "LMCache 现在支持将 KV Cache 卸载到以下目标："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:449
+msgid ":doc:`CPU memory <../../kv_cache/storage_backends/cpu_ram>`"
+msgstr ":doc:`CPU 内存 <../../kv_cache/storage_backends/cpu_ram>`"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:450
+msgid ":doc:`Local file system <../../kv_cache/storage_backends/local_storage>`"
+msgstr ":doc:`本地文件系统 <../../kv_cache/storage_backends/local_storage>`"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:451
+msgid ":doc:`Mooncake Storage <../../kv_cache/storage_backends/mooncake>`"
+msgstr ":doc:`Mooncake 存储 <../../kv_cache/storage_backends/mooncake>`"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:452
+msgid ":doc:`InfiniStore <../../kv_cache/storage_backends/infinistore>`"
+msgstr ":doc:`InfiniStore <../../kv_cache/storage_backends/infinistore>`"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:453
+msgid ":doc:`Redis <../../kv_cache/storage_backends/redis>`"
+msgstr "：doc:`Redis <../../kv_cache/storage_backends/redis>`"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:454
+msgid ":doc:`ValKey <../../kv_cache/storage_backends/valkey>`"
+msgstr ":doc:`ValKey <../../kv_cache/storage_backends/valkey>`"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:457
+msgid "Troubleshooting"
+msgstr "故障排除"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:459
+msgid "If you encounter the following error:"
+msgstr "如果您遇到以下错误："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:466
+msgid "You can resolve this issue using one of the following methods:"
+msgstr "您可以通过以下方法解决此问题："
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:468
+msgid "Set ``VLLM_WORKER_MULTIPROC_METHOD=spawn`` in the environment variables."
+msgstr "在环境变量中设置 ``VLLM_WORKER_MULTIPROC_METHOD=spawn``。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:469
+msgid ""
+"Or update the Python code to guard usage of vllm behind a if ``__name__ "
+"== '__main__':`` block."
+msgstr "或者更新 Python 代码，将 vllm 的使用放在 ``if __name__ == '__main__':`` 块中。"
+
+#: ../../source/getting_started/quickstart/offload_kv_cache.rst:480
+msgid ""
+"For details, please refer to the `vLLM Troubleshooting Guide: Python "
+"multiprocessing "
+"<https://docs.vllm.ai/en/latest/usage/troubleshooting.html#python-"
+"multiprocessing>`_."
+msgstr ""
+"有关详细信息，请参阅 `vLLM 故障排除指南：Python 多进程 "
+"<https://docs.vllm.ai/en/latest/usage/troubleshooting.html#python-"
+"multiprocessing>`_。"
+
+#~ msgid "At least 24GB GPU memory"
+#~ msgstr "至少 24GB 显存"
+
+#~ msgid ""
+#~ "Sufficient CPU memory (LMCache will use"
+#~ " 15 GB by default in this "
+#~ "example)."
+#~ msgstr "足够的 CPU 内存（在此示例中，LMCache 默认将使用 15 GB）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/share_kv_cache.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/share_kv_cache.po
new file mode 100644
index 0000000..17a20cb
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/share_kv_cache.po
@@ -0,0 +1,255 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:4
+msgid "Example: Share KV cache across multiple LLMs"
+msgstr "示例：在多个 LLM 之间共享 KV Cache"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:11
+msgid ""
+"LMCache should be able to reduce the generation time of the second and "
+"following calls."
+msgstr "LMCache 应该能够减少第二次及后续调用的生成时间。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:13
+msgid ""
+"We have examples for the following types of across-instance KV cache "
+"sharing:"
+msgstr "我们有以下类型的跨实例 KV Cache 共享的示例："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:15
+msgid ""
+"KV cache sharing through a centralized cache server: "
+"``centralized_sharing``"
+msgstr "通过集中式缓存服务器的 KV Cache 共享：\\ ``centralized_sharing``"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:16
+msgid "KV cache sharing through p2p cache transfer: ``p2p_sharing``"
+msgstr "通过点对点缓存传输共享 KV 缓存: ``p2p_sharing``"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:19
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:21
+msgid "Your server should have at least 2 GPUs."
+msgstr "您的服务器应至少配备 2 个 GPU。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:23
+msgid ""
+"For Centralized sharing, this will use the port 8000 and 8001 (for vLLM) "
+"and port 65432 (for LMCache)."
+msgstr "对于集中式共享，这将使用端口 8000 和 8001（用于 vLLM）以及端口 65432（用于 LMCache）。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:25
+msgid "For P2P sharing:"
+msgstr "对于 P2P 共享："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:27
+msgid "`NIXL <https://github.com/ai-dynamo/nixl>`_ installed on the host."
+msgstr "`NIXL <https://github.com/ai-dynamo/nixl>`_ 安装在主机上。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:28
+msgid "Port 8010 and 8011 for 2 vllms servers."
+msgstr "用于 2 个 vLLM 服务器的 8010 和 8011 端口。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:29
+msgid "Port 8200 and 8202 for 2 p2p initialization connections."
+msgstr "端口 8200 和 8202 用于 2 个 p2p 初始化连接。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:30
+msgid "Port 8201 and 8203 for 2 p2p lookup connections."
+msgstr "端口 8201 和 8203 用于 2 个 p2p 查找连接。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:31
+msgid "Port 8300 for controller pull requests."
+msgstr "端口 8300 用于控制器拉取请求。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:32
+msgid "Port 8400 for controller reply requests."
+msgstr "控制器回复请求的端口为 8400。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:33
+msgid "Port 8500 and 8501 for 2 LMCache workers."
+msgstr "8500 和 8501 端口用于 2 个 LMCache 工作线程。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:34
+msgid ""
+"Port 9000 for controller main port (arbitrary and can be changed) to "
+"start the controller."
+msgstr "端口 9000 用于控制器主端口（任意且可以更改），以启动控制器。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:37
+msgid "Centralized KV cache sharing"
+msgstr "集中式 KV Cache 共享"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:39
+msgid ""
+"This section demonstrates how to share KV cache across multiple vLLM "
+"instances using a centralized LMCache server."
+msgstr "本节演示如何通过集中式 LMCache 服务器在多个 vLLM 实例之间共享 KV Cache。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:41
+msgid ""
+"**Important**: For centralized cache sharing (which is cross-process "
+"cases), ensure all processes use the same `PYTHONHASHSEED` to keep the "
+"hash of the KV cache consistent across processes: ``export "
+"PYTHONHASHSEED=0``."
+msgstr ""
+"**重要**\\ ：对于集中式缓存共享（跨进程情况），确保所有进程使用相同的 `PYTHONHASHSEED` 以保持 KV "
+"缓存在进程之间的一致性：\\ ``export PYTHONHASHSEED=0``\\ 。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:44
+msgid "Setup centralized sharing"
+msgstr "设置集中式共享"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:46
+msgid ""
+"First, create a configuration file named ``lmcache_config.yaml`` with the"
+" following content:"
+msgstr "首先，创建一个名为 ``lmcache_config.yaml`` 的配置文件，内容如下："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:56
+msgid "Run centralized sharing example"
+msgstr "运行集中式共享示例"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:58
+msgid "Start the LMCache centralized server,"
+msgstr "启动 LMCache 中央服务器，"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:64
+msgid "In a different terminal,"
+msgstr "在另一个终端中，"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:76
+msgid "In another terminal,"
+msgstr "在另一个终端中，"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:89
+msgid "Wait until both engines are ready."
+msgstr "等待直到两个引擎都准备好。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:91
+msgid "Send one request to the engine at port 8000,"
+msgstr "向端口 8000 的引擎发送一个请求，"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:103
+msgid "Send the same request to the engine at port 8001,"
+msgstr "将相同的请求发送到端口 8001 的引擎。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:115
+msgid ""
+"The second request will automatically retrieve and reuse the KV cache "
+"from the first instance, significantly reducing generation time."
+msgstr "第二个请求将自动从第一个实例中检索并重用 KV Cache，显著减少生成时间。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:118
+msgid "P2P KV cache sharing"
+msgstr "P2P KV Cache 共享"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:120
+msgid ""
+"This section demonstrates how to share KV cache across multiple vLLM "
+"instances using peer-to-peer transfer."
+msgstr "本节演示如何通过点对点传输在多个 vLLM 实例之间共享 KV Cache。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:123
+msgid "Configure LMCache instances"
+msgstr "配置 LMCache 实例"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:125
+msgid ""
+"Create two configuration files for the P2P sharing setup. The values that"
+" differ between the files are the ``lmcache_instance_id`` and the "
+"P2P/controller port assignments."
+msgstr "为 P2P 共享设置创建两个配置文件。两个文件之间不同的值是 ``lmcache_instance_id`` 和 P2P/控制器端口分配。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:127
+msgid "Instance 1 configuration (``p2p_example1.yaml``):"
+msgstr "实例 1 配置 (``p2p_example1.yaml``):"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:153
+msgid "Instance 2 configuration (``p2p_example2.yaml``):"
+msgstr "实例 2 配置 (``p2p_example2.yaml``):"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:179
+msgid ""
+"Save both files in the directory that you will mount into the container "
+"(referenced later as ``$YAML_FILES``)."
+msgstr "将两个文件保存在您将挂载到容器中的目录中（稍后称为 ``$YAML_FILES``\\ ）。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:182
+msgid "Run the P2P sharing workflow"
+msgstr "运行 P2P 共享工作流"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:184
+msgid ""
+"Configure the environment on the host and open a shell inside the "
+"container:"
+msgstr "在主机上配置环境并在容器内打开一个 shell："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:204
+msgid "Start the LMCache controller and monitoring endpoints:"
+msgstr "启动 LMCache 控制器和监控端点："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:210
+msgid "Launch two vLLM engines, each with its own LMCache worker configuration."
+msgstr "启动两个 vLLM 引擎，每个引擎都有自己的 LMCache 工作配置。"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:212
+msgid "Start vLLM engine 1 on GPU 0:"
+msgstr "在 GPU 0 上启动 vLLM 引擎 1："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:222
+msgid "Start vLLM engine 2 on GPU 1:"
+msgstr "在 GPU 1 上启动 vLLM 引擎 2："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:232
+msgid "Populate the KV cache by sending a request to the first engine:"
+msgstr "通过向第一个引擎发送请求来填充 KV Cache："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:244
+msgid "Send the same request to the second engine to demonstrate cache retrieval:"
+msgstr "将相同的请求发送到第二个引擎以演示缓存检索："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:257
+msgid "Expected output"
+msgstr "预期输出"
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:259
+msgid ""
+"When the second request successfully retrieves the cache from the first "
+"instance, the logs should include entries similar to:"
+msgstr "当第二个请求成功从第一个实例检索到缓存时，日志应包含类似于以下内容的条目："
+
+#: ../../source/getting_started/quickstart/share_kv_cache.rst:270
+msgid ""
+"These logs indicate that the peer connection was established and the "
+"cache was transferred successfully."
+msgstr "这些日志表明对等连接已建立，并且缓存已成功传输。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/standalone_starter.po b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/standalone_starter.po
new file mode 100644
index 0000000..f6b2287
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/getting_started/quickstart/standalone_starter.po
@@ -0,0 +1,383 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:4
+msgid "Standalone Starter"
+msgstr "独立启动器"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP mode </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:11
+msgid ""
+"The LMCache Standalone Starter allows you to run LMCacheEngine as a "
+"standalone service without vLLM or GPU dependencies. This is particularly"
+" useful for:"
+msgstr "LMCache 独立启动器允许您将 LMCacheEngine 作为独立服务运行，而无需 vLLM 或 GPU 依赖。这对于以下情况特别有用："
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:13
+msgid "Testing and development environments"
+msgstr "测试和开发环境"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:14
+msgid "CPU-only or P2P backend deployments"
+msgstr "仅 CPU 或 P2P 后端部署"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:17
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:20
+msgid "Basic Usage"
+msgstr "基本用法"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:35
+msgid "CPU-Only Mode"
+msgstr "CPU-Only 模式"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:46
+msgid "Remote P2P Mode"
+msgstr "远程 P2P 模式"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:47
+msgid "TO be added"
+msgstr "待添加"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:50
+msgid "Configuration Section"
+msgstr "配置部分"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:52
+msgid ""
+"The standalone starter supports multiple configuration sources with the "
+"following priority order:"
+msgstr "独立启动器支持多个配置源，优先级顺序如下："
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:54
+msgid "**Command-line arguments** (highest priority)"
+msgstr "**命令行参数**\\ （最高优先级）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:55
+msgid ""
+"**Configuration file** (specified by ``--config`` or "
+"``LMCACHE_CONFIG_FILE``)"
+msgstr "**配置文件**\\ （由 ``--config`` 或 ``LMCACHE_CONFIG_FILE`` 指定）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:56
+msgid "**Environment variables** (e.g., ``LMCACHE_CHUNK_SIZE=512``)"
+msgstr "**环境变量**\\ （例如，\\ ``LMCACHE_CHUNK_SIZE=512``\\ ）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:57
+msgid "**Default values** (lowest priority)"
+msgstr "**默认值**\\ （最低优先级）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:60
+msgid "Parameter Details"
+msgstr "参数详细信息"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:62
+msgid "**KV Cache Shape Specification**"
+msgstr "**KV Cache 形状规范**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:64
+msgid ""
+"The ``--kvcache_shape_spec`` parameter supports multi-layer group "
+"configurations:"
+msgstr "``--kvcache_shape_spec`` 参数支持多层组配置："
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:66
+msgid "Format: ``(shape_string):dtype:layer_count;[...]``"
+msgstr "格式: ``(shape_string):dtype:layer_count;[...]``"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:67
+msgid "shape_string: comma-separated shape (e.g., '2,2,256,4,16')"
+msgstr "shape_string: 以逗号分隔的形状（例如，'2,2,256,4,16'）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:68
+msgid ""
+"Examples: - Single group: ``(2,2,256,4,16):float16:2`` - Multiple groups:"
+" ``(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3``"
+msgstr ""
+"示例： - 单个组：\\ ``(2,2,256,4,16):float16:2`` - 多个组：\\ "
+"``(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3``"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:72
+msgid "**Device Support**"
+msgstr "**设备支持**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:74
+msgid "``--device=cpu``: CPU-only mode (default)"
+msgstr "``--device=cpu``: 仅 CPU 模式（默认）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:75
+msgid "``--device=cuda``: CUDA GPU acceleration"
+msgstr "``--device=cuda``: CUDA GPU 加速"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:76
+msgid "``--device=xpu``: XPU GPU acceleration"
+msgstr "``--device=xpu``: XPU GPU 加速"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:78
+msgid "**MLA (Multi-Level Attention)**"
+msgstr "**多级注意力 (MLA)**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:80
+msgid "``--use_mla``: Enable MLA for improved attention performance"
+msgstr "``--use_mla``: 启用 MLA 以提高注意力性能"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:81
+msgid "Requires compatible model and configuration"
+msgstr "需要兼容的模型和配置"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:83
+msgid "**Cache Formats**"
+msgstr "**缓存格式**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:85
+msgid "``--fmt=vllm``: vLLM-compatible format (default)"
+msgstr "``--fmt=vllm``: vLLM 兼容格式（默认）"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:86
+msgid "Supports other formats for different inference engines"
+msgstr "支持其他格式以适应不同的推理引擎"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:89
+msgid "Command-Line Parameters"
+msgstr "命令行参数"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:92
+msgid "Basic Parameters"
+msgstr "基本参数"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:109
+msgid "Usage Examples"
+msgstr "使用示例"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:112
+msgid "Custom Configuration"
+msgstr "自定义配置"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:123
+msgid "Multi-Layer Group Configuration"
+msgstr "多层组配置"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:135
+msgid "GPU device"
+msgstr "GPU 设备"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:149
+msgid "MLA Configuration"
+msgstr "MLA 配置"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:162
+msgid "Internal API Server"
+msgstr "内部 API 服务器"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:164
+msgid ""
+"The standalone starter includes an internal API server for monitoring and"
+" management:"
+msgstr "独立启动器包括一个用于监控和管理的内部 API 服务器："
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:177
+msgid "Troubleshooting"
+msgstr "故障排除"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:180
+msgid "Common Issues"
+msgstr "常见问题"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:182
+msgid ""
+"**Issue**: \"No config file specified\" **Solution**: Set "
+"``LMCACHE_CONFIG_FILE`` or use ``--config`` parameter"
+msgstr "**问题**: “未指定配置文件” **解决方案**: 设置 ``LMCACHE_CONFIG_FILE`` 或使用 ``--config`` 参数"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:185
+msgid ""
+"**Issue**: \"Failed to connect to controller\" **Solution**: Start "
+"controller first: ``python -m lmcache.v1.api_server``"
+msgstr "**问题**: “无法连接到控制器” **解决方案**: 首先启动控制器: ``python -m lmcache.v1.api_server``"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:188
+msgid ""
+"**Issue**: \"Invalid KV shape specification\" **Solution**: Check format:"
+" ``(shape):dtype:layer_count``, e.g., ``(2,2,256,4,16):float16:2``"
+msgstr ""
+"**问题**: \\\"无效的 KV 形状规范\\\" **解决方案**: 检查格式: "
+"``(shape):dtype:layer_count``\\ ，例如，\\ ``(2,2,256,4,16):float16:2``"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:191
+msgid ""
+"**Issue**: \"Device not available\" **Solution**: Verify device support: "
+"use ``--device=cpu`` if GPU not available"
+msgstr "**问题**: \"设备不可用\" **解决方案**: 验证设备支持: 如果 GPU 不可用，请使用 ``--device=cpu``"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:194
+msgid ""
+"**Issue**: \"MLA configuration error\" **Solution**: Ensure compatible "
+"model and check ``--use_mla`` parameter"
+msgstr "**问题**: \"MLA 配置错误\" **解决方案**: 确保模型兼容并检查 ``--use_mla`` 参数"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:198
+msgid "Debug Mode"
+msgstr "调试模式"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:200
+msgid "Enable debug logging for troubleshooting:"
+msgstr "启用调试日志以进行故障排除："
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:208
+msgid "Advanced Debugging"
+msgstr "高级调试"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:210
+msgid "For detailed layer group information:"
+msgstr "有关详细的层组信息："
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:220
+msgid "Performance Tuning"
+msgstr "性能调优"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:223
+msgid "Memory Configuration"
+msgstr "内存配置"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:234
+msgid "Layer Group Optimization"
+msgstr "层组优化"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:245
+msgid "GPU Acceleration"
+msgstr "GPU 加速"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:256
+msgid "MLA Performance"
+msgstr "MLA 性能"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:268
+msgid "Best Practices"
+msgstr "最佳实践"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:270
+msgid "**Use configuration files** for production deployments"
+msgstr "**在生产环境中使用配置文件**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:271
+msgid "**Set appropriate cache sizes** based on available memory"
+msgstr "**根据可用内存设置适当的缓存大小**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:272
+msgid "**Enable internal API** for monitoring and management"
+msgstr "**启用内部 API** 以进行监控和管理"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:273
+msgid "**Monitor logs** for performance and error tracking"
+msgstr "**监控日志**\\ 以进行性能和错误跟踪"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:274
+msgid "**Use multi-layer group configurations** for complex model architectures"
+msgstr "**使用多层组配置** 以支持复杂的模型架构"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:275
+msgid "**Enable MLA** for improved attention performance on supported hardware"
+msgstr "**启用 MLA** 以在支持的硬件上提高注意力性能"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:276
+msgid "**Choose appropriate device** based on available resources (CPU/GPU/XPU)"
+msgstr "**根据可用资源（CPU/GPU/XPU）选择合适的设备**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:277
+msgid "**Validate KV shape specifications** before deployment"
+msgstr "**在部署之前** 验证 KV 形状规范"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:278
+msgid "**Test with debug logging** when configuring new layer groups"
+msgstr "**在配置新层组时**\\ 进行调试日志测试"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:279
+msgid "**Optimize chunk sizes** for specific hardware configurations"
+msgstr "**为特定硬件配置优化块大小**"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:282
+msgid "Multi-Layer Group Best Practices"
+msgstr "多层组最佳实践"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:284
+msgid "Use consistent chunk sizes across layer groups for optimal performance"
+msgstr "在层组之间使用一致的块大小以获得最佳性能"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:285
+msgid "Group layers with similar precision requirements together"
+msgstr "将具有相似精度要求的层分组在一起"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:286
+msgid "Validate shape specifications in development environment first"
+msgstr "首先在开发环境中验证形状规范"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:287
+msgid "Monitor memory usage when using multiple layer groups"
+msgstr "在使用多个层组时监控内存使用情况"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:290
+msgid "MLA Configuration Tips"
+msgstr "MLA 配置提示"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:292
+msgid "Enable MLA only on supported hardware configurations"
+msgstr "仅在支持的硬件配置上启用 MLA"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:293
+msgid "Use bfloat16 or float16 precision for best MLA performance"
+msgstr "使用 bfloat16 或 float16 精度以获得最佳 MLA 性能"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:294
+msgid "Test MLA performance impact before production deployment"
+msgstr "在生产部署之前测试 MLA 性能影响"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:295
+msgid "Monitor attention performance metrics with MLA enabled"
+msgstr "启用 MLA 后监控注意力性能指标"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:298
+msgid "Related Documentation"
+msgstr "相关文档"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:300
+msgid ":doc:`../quickstart`"
+msgstr ":doc:`../quickstart`"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:301
+msgid ":doc:`../../api_reference/configurations`"
+msgstr ":doc:`../../api_reference/configurations`"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:302
+msgid ":doc:`../../kv_cache/storage_backends/index`"
+msgstr ":doc:`../../kv_cache/storage_backends/index`"
+
+#: ../../source/getting_started/quickstart/standalone_starter.rst:303
+msgid ":doc:`../../kv_cache_management/index`"
+msgstr ":doc:`../../kv_cache_management/index`"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/index.po
new file mode 100644
index 0000000..5c38432
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/index.po
@@ -0,0 +1,437 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-26 17:26-0700\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: Jiayue Chen <joyce@tensormesh.ai>\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Language: zh_CN\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/index.rst:10
+msgid "Welcome to LMCache!"
+msgstr "欢迎使用 LMCache！"
+
+#: ../../source/index.rst:12
+msgid "LMCache"
+msgstr "LMCache"
+
+#: ../../source/index.rst:20
+msgid "**A KV Cache Management Layer for Scalable LLM Inference.**"
+msgstr "**面向 LLM 推理的 KV Cache 管理层**"
+
+#: ../../source/index.rst:23
+msgid ""
+"We are currently in the process of upgrading our documentation to provide "
+"better guidance and examples. Some sections may be under construction. Thank "
+"you for your patience!"
+msgstr ""
+"我们目前正在升级文档，以提供更好的指导和示例。某些章节可能仍在建设中，感谢您"
+"的耐心等待！"
+
+#: ../../source/index.rst:36
+msgid ""
+"LMCache is a **KV cache management layer** for LLM inference. It turns KV "
+"cache from a temporary state into reusable *AI-native knowledge* that can be "
+"*stored* persistently, *reused* across multiple serving engines, *monitored* "
+"with an observability stack, and *transformed* for better generation "
+"quality. As a result, LMCache **reduces TTFT** (time-to-first-token) and "
+"**improves throughput**, especially for long-context agentic, multi-turn "
+"conversation, and knowledge-augmented workloads (e.g., RAG)."
+msgstr ""
+"LMCache 是面向 LLM 推理的 **KV Cache 管理层**。它将 KV Cache 从临时状态转变为"
+"可复用的 AI 原生知识：可以持久存储、在多个服务引擎之间复用、通过可观测性栈进"
+"行监控，并可转换以获得更好的生成质量。因此，LMCache 能\\ **降低 TTFT**\\ "
+"（首 token 时间）并\\ **提升吞吐量**，尤其适用于长上下文智能体、多轮对话以及"
+"知识增强（如 RAG）等工作负载。"
+
+#: ../../source/index.rst:38
+msgid ""
+"LMCache is **vendor-neutral**. It can be used as a KV cache layer for a "
+"range of mainstream open-source serving engines, inference frameworks, "
+"hardware vendors, storage systems, and infrastructure providers. The vendor "
+"neutrality allows users to freely switch between serving engines and storage "
+"vendors, while reusing the stored KV caches."
+msgstr ""
+"LMCache 具有\\ **厂商中立性**\\。它可以作为 KV Cache 层，接入多种主流开源服务"
+"引擎、推理框架、硬件平台、存储系统和基础设施提供商。因此，用户可以在不同的服"
+"务引擎和存储厂商之间灵活切换，同时继续复用已存储的 KV Cache。"
+
+#: ../../source/index.rst:40 ../../source/index.rst:46
+msgid "LMCache Deployment Modes"
+msgstr "LMCache 部署模式"
+
+#: ../../source/index.rst:52 ../../source/index.rst:79
+#: ../../source/index.rst:101 ../../source/index.rst:114
+#: ../../source/index.rst:126 ../../source/index.rst:133
+#: ../../source/index.rst:140 ../../source/index.rst:147
+#: ../../source/index.rst:154 ../../source/index.rst:161
+#: ../../source/index.rst:168 ../../source/index.rst:175
+#: ../../source/index.rst:182 ../../source/index.rst:189
+#: ../../source/index.rst:196 ../../source/index.rst:203
+msgid ":raw-html:`<br />`"
+msgstr ":raw-html:`<br />`"
+
+#: ../../source/index.rst:55
+msgid "Key features"
+msgstr "主要特性"
+
+#: ../../source/index.rst:57
+msgid ""
+"**Engine-independent deployment**: LMCache, as a standalone daemon process, "
+"manages KV cache independently from the inference engine process, so that KV "
+"cache will not be lost even if the inference engine crashes (i.e., no fate-"
+"sharing with engines)."
+msgstr ""
+"**引擎独立部署**：LMCache 作为独立的守护进程运行，能够在推理引擎进程之外独立"
+"管理 KV cache。因此，即使推理引擎发生崩溃，KV cache 也不会随之丢失，避免了与"
+"推理引擎“同生共死”的问题。"
+
+#: ../../source/index.rst:59
+msgid ""
+"**Persistent, tiered KV cache offloading and reuse**: Move KV caches out of "
+"GPU memory into a tiered storage hierarchy spanning CPU memory, local "
+"storage, and remote backends, enabling reuse across requests, sessions, and "
+"engine instances to reduce repeated prefill computation and improve TTFT."
+msgstr ""
+"**持久化的分层 KV Cache 卸载与复用**：将 KV Cache 从显存卸载到跨越 CPU 内存、"
+"本地存储和远程后端的分层存储体系中，实现跨请求、跨会话和跨引擎实例的复用，从"
+"而减少重复的 Prefill 计算并降低 TTFT。"
+
+#: ../../source/index.rst:61
+msgid ""
+"**Production-level KV cache observability**: LMCache provides a rich set of "
+"KV cache observability metrics, including typical Kubernetes metrics (health "
+"monitoring, performance diagnostics), KV-cache-specific metrics (request-"
+"level and token-level prefix cache hits, lifecycle, request-level KV cache "
+"performance), management metrics (user-specific usage), and more."
+msgstr ""
+"**生产级 KV Cache 可观测性**：LMCache 提供丰富的 KV Cache 可观测性指标，包括"
+"典型的 Kubernetes 指标（健康监控、性能诊断）、KV Cache 专属指标（请求级和 "
+"token 级的前缀缓存命中、生命周期、请求级 KV Cache 性能）、管理指标（特定用户"
+"的使用情况）等。"
+
+#: ../../source/index.rst:63
+msgid ""
+"**Pluggable storage and transport backends**: Easily integrate remote "
+"storage and KV transfer backends through a unified interface, enabling KV "
+"cache offloading and sharing across storage providers. Through this "
+"interface, LMCache supports storage backends including CPU RAM, local disk "
+"(SSD), Redis/Valkey, Mooncake, InfiniStore, S3-compatible object storage, "
+"NIXL, and GDS."
+msgstr ""
+"**可插拔的存储与传输后端**：通过统一接口轻松集成远程存储和 KV 传输后端，实现"
+"跨存储提供商的 KV Cache 卸载与共享。通过该接口，LMCache 支持的存储后端包括 "
+"CPU RAM、本地磁盘（SSD）、Redis/Valkey、Mooncake、InfiniStore、兼容 S3 的对象"
+"存储、NIXL 和 GDS。"
+
+#: ../../source/index.rst:65
+msgid ""
+"**Non-prefix KV reuse**: Extend KV reuse beyond prefix caching by reusing "
+"cached KV blocks at any position in the prompt. This leverages CacheBlend to "
+"selectively recompute tokens for quality recovery."
+msgstr ""
+"**非前缀 KV 复用**：通过复用 prompt 中任意位置的已缓存 KV 块，将 KV 复用扩展"
+"到前缀缓存之外。它借助 CacheBlend 选择性地重新计算部分 token，从而恢复生成质"
+"量。"
+
+#: ../../source/index.rst:67
+msgid ""
+"**PD disaggregation and KV transfer**: Support KV cache transfer from "
+"prefill workers to decode workers over NVLink, RDMA, or TCP through "
+"transport layers such as NIXL."
+msgstr ""
+"**PD 分离与 KV 传输**：支持通过 NIXL 等传输层，经由 NVLink、RDMA 或 TCP 将 "
+"KV Cache 从 Prefill 工作节点传输到解码工作节点。"
+
+#: ../../source/index.rst:69
+msgid ""
+"**Pluggable KV transformation**: A simple interface for researchers to write "
+"compression, token dropping, and custom serialization through a flexible "
+"SERDE interface."
+msgstr ""
+"**可插拔的 KV 转换**：提供简洁的接口，让研究人员能够借助灵活的 SERDE 接口实现"
+"压缩、token 丢弃和自定义序列化。"
+
+#: ../../source/index.rst:71
+msgid ""
+"LMCache is becoming an integral layer in the LLM inference *ecosystem*, with "
+"*community*-driven integration with serving engines, inference frameworks, "
+"hardware vendors, storage systems, and infrastructure providers:"
+msgstr ""
+"LMCache 正在成为 LLM 推理生态系统中不可或缺的一层，并通过社区驱动的方式与服务"
+"引擎、推理框架、硬件厂商、存储系统和基础设施提供商集成："
+
+#: ../../source/index.rst:73
+msgid "LMCache ecosystem"
+msgstr "LMCache 生态系统"
+
+#: ../../source/index.rst:82
+msgid "Updates"
+msgstr "最新动态"
+
+#: ../../source/index.rst:84
+msgid ""
+"[2026/06] 🔥 LMCache multi-platform development support with no GPU required "
+"(`blog <https://blog.lmcache.ai/en/2026/06/23/vllm-lmcache-a-starter-guide-"
+"no-gpu-required/>`__, `blog <https://blog.lmcache.ai/en/2026/06/15/"
+"understanding-lmcache-mp-mode-transfer-paths-a-beginners-guide/>`__)."
+msgstr ""
+"[2026/06] 🔥 LMCache 多平台开发支持，无需 GPU（`博客 <https://"
+"blog.lmcache.ai/en/2026/06/23/vllm-lmcache-a-starter-guide-no-gpu-required/"
+">`__、`博客 <https://blog.lmcache.ai/en/2026/06/15/understanding-lmcache-mp-"
+"mode-transfer-paths-a-beginners-guide/>`__）。"
+
+#: ../../source/index.rst:85
+msgid ""
+"[2026/05] 🔥 Agentic workload benchmark on AMD MI300X (`blog <https://"
+"blog.lmcache.ai/en/2026/05/12/benchmarking-lmcache-for-multi-turn-agentic-"
+"workloads-on-amd-mi300x/>`__)."
+msgstr ""
+"[2026/05] 🔥 AMD MI300X 上的智能体工作负载基准测试（`博客 <https://"
+"blog.lmcache.ai/en/2026/05/12/benchmarking-lmcache-for-multi-turn-agentic-"
+"workloads-on-amd-mi300x/>`__）。"
+
+#: ../../source/index.rst:86
+msgid ""
+"[2026/04] 🔥 LMCache's new multiprocess (MP) architecture release (`blog "
+"<https://blog.lmcache.ai/en/2026/04/03/lmcaches-new-architecture-boosts-moe-"
+"inference-performance-by-10x/>`__)."
+msgstr ""
+"[2026/04] 🔥 LMCache 全新多进程（MP）架构发布（`博客 <https://"
+"blog.lmcache.ai/en/2026/04/03/lmcaches-new-architecture-boosts-moe-inference-"
+"performance-by-10x/>`__）。"
+
+#: ../../source/index.rst:87
+msgid ""
+"[2026/03] LMCache at GTC 2026 (`post <https://www.linkedin.com/posts/lmcache-"
+"lab_llm-opensource-nvidiagtc-activity-7442721875664826369-pMAu>`__)."
+msgstr ""
+"[2026/03] LMCache 亮相 GTC 2026（`帖子 <https://www.linkedin.com/posts/"
+"lmcache-lab_llm-opensource-nvidiagtc-activity-7442721875664826369-"
+"pMAu>`__）。"
+
+#: ../../source/index.rst:88
+msgid ""
+"[2026/01] LMCache multi-node P2P CPU memory sharing, from experimental "
+"feature to production (`blog <https://blog.lmcache.ai/en/2026/01/21/p2p-1/"
+">`__)."
+msgstr ""
+"[2026/01] LMCache 多节点 P2P CPU 内存共享，从实验性功能走向生产（`博客 "
+"<https://blog.lmcache.ai/en/2026/01/21/p2p-1/>`__）。"
+
+#: ../../source/index.rst:0
+msgid "More"
+msgstr "更多"
+
+#: ../../source/index.rst:92
+msgid ""
+"[2025/11] LMCache x CoreWeave accelerate efficient LLM inference for Cohere "
+"(`blog <https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-"
+"how-lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/>`__)."
+msgstr ""
+"[2025/11] LMCache 携手 CoreWeave 为 Cohere 加速高效 LLM 推理（`博客 <https://"
+"blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-lmcache-and-"
+"coreweave-power-efficient-llm-inference-for-cohere/>`__）。"
+
+#: ../../source/index.rst:93
+msgid ""
+"[2025/10] LMCache joins the PyTorch Foundation and Tensormesh unveiled "
+"(`blog <https://blog.lmcache.ai/en/2025/10/31/tensormesh-unveiled-and-"
+"lmcache-joins-the-pytorch-foundation/>`__, `PyTorch <https://pytorch.org/"
+"blog/lmcache-joins-pytorch-ecosystem/>`__)."
+msgstr ""
+"[2025/10] LMCache 加入 PyTorch 基金会，Tensormesh 正式亮相（`博客 <https://"
+"blog.lmcache.ai/en/2025/10/31/tensormesh-unveiled-and-lmcache-joins-the-"
+"pytorch-foundation/>`__，`PyTorch <https://pytorch.org/blog/lmcache-joins-"
+"pytorch-ecosystem/>`__）。"
+
+#: ../../source/index.rst:94
+msgid ""
+"[2025/09] NVIDIA Dynamo integrates LMCache, accelerating LLM inference "
+"(`blog <https://blog.lmcache.ai/en/2025/09/18/nvidia-dynamo-integrates-"
+"lmcache-accelerating-llm-inference/>`__)."
+msgstr ""
+"[2025/09] NVIDIA Dynamo 集成 LMCache，加速 LLM 推理（`博客 <https://"
+"blog.lmcache.ai/en/2025/09/18/nvidia-dynamo-integrates-lmcache-accelerating-"
+"llm-inference/>`__）。"
+
+#: ../../source/index.rst:95
+msgid ""
+"[2025/08] 🎉 LMCache hits 5,000+ GitHub stars (`blog <https://"
+"blog.lmcache.ai/en/2025/08/28/%f0%9f%8e%89-lmcache-hits-5000-github-stars-"
+"thank-you-community/>`__)."
+msgstr ""
+"[2025/08] 🎉 LMCache GitHub star 数突破 5,000+（`博客 <https://"
+"blog.lmcache.ai/en/2025/08/28/%f0%9f%8e%89-lmcache-hits-5000-github-stars-"
+"thank-you-community/>`__）。"
+
+#: ../../source/index.rst:96
+msgid ""
+"[2025/08] LMCache supports gpt-oss (20B/120B) on day 1 (`blog <https://"
+"blog.lmcache.ai/en/2025/08/05/lmcache-supports-gpt-oss-20b-120b-on-day-1/"
+">`__)."
+msgstr ""
+"[2025/08] LMCache 在首日即支持 gpt-oss（20B/120B）（`博客 <https://"
+"blog.lmcache.ai/en/2025/08/05/lmcache-supports-gpt-oss-20b-120b-on-day-1/"
+">`__）。"
+
+#: ../../source/index.rst:97
+msgid ""
+"[2025/07] Get faster LLM inference and cheaper responses with LMCache and "
+"Redis (`Redis blog <https://redis.io/blog/get-faster-llm-inference-and-"
+"cheaper-responses-with-lmcache-and-redis/>`__)."
+msgstr ""
+"[2025/07] 借助 LMCache 和 Redis 实现更快的 LLM 推理和更低的响应成本（`Redis "
+"博客 <https://redis.io/blog/get-faster-llm-inference-and-cheaper-responses-"
+"with-lmcache-and-redis/>`__）。"
+
+#: ../../source/index.rst:98
+msgid ""
+"[2025/07] LMCache extends its turbo-boost to multimodal models in vLLM V1 "
+"(`blog <https://blog.lmcache.ai/en/2025/07/03/lmcache-extends-its-turbo-"
+"boost-to-multimodal-models-in-vllm-v1/>`__)."
+msgstr ""
+"[2025/07] LMCache 将其加速能力扩展到 vLLM V1 中的多模态模型（`博客 <https://"
+"blog.lmcache.ai/en/2025/07/03/lmcache-extends-its-turbo-boost-to-multimodal-"
+"models-in-vllm-v1/>`__）。"
+
+#: ../../source/index.rst:99
+msgid ""
+"[2025/06] LLM Production Stack goes cross-hardware: AMD, Arm and Ascend "
+"(`blog <https://blog.lmcache.ai/en/2025/06/20/llm-production-stack-goes-"
+"cross-hardware-ascend-arm-and-amd-support-incoming/>`__)."
+msgstr ""
+"[2025/06] LLM Production Stack 实现跨硬件：AMD、Arm 和 Ascend（`博客 "
+"<https://blog.lmcache.ai/en/2025/06/20/llm-production-stack-goes-cross-"
+"hardware-ascend-arm-and-amd-support-incoming/>`__）。"
+
+#: ../../source/index.rst:104
+msgid "For more information, check out the following:"
+msgstr "有关更多信息，请查看以下内容："
+
+#: ../../source/index.rst:106
+msgid "`LMCache blogs <https://lmcache.github.io>`_"
+msgstr "`LMCache 博客 <https://lmcache.github.io>`_"
+
+#: ../../source/index.rst:107
+msgid ""
+"`Join LMCache slack workspace <https://join.slack.com/t/lmcacheworkspace/"
+"shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA>`_"
+msgstr ""
+"`加入我们的 Slack 社区 <https://join.slack.com/t/lmcacheworkspace/"
+"shared_invite/zt-3zxjao8h0-lRfBfnLqbALOtLsWn2ITxA>`_"
+
+#: ../../source/index.rst:108
+msgid "Our papers:"
+msgstr "我们的论文："
+
+#: ../../source/index.rst:110
+msgid ""
+"`CacheGen: KV Cache Compression and Streaming for Fast Large Language Model "
+"Serving <https://dl.acm.org/doi/10.1145/3651890.3672274>`_"
+msgstr ""
+"`CacheGen: KV Cache Compression and Streaming for Fast Large Language "
+"<https://dl.acm.org/doi/10.1145/3651890.3672274>`_"
+
+#: ../../source/index.rst:111
+msgid ""
+"`CacheBlend: Fast Large Language Model Serving with Cached Knowledge Fusion "
+"<https://arxiv.org/abs/2405.16444>`_"
+msgstr ""
+"`CacheBlend: Fast Large Language Model Serving with Cached Knowledge "
+"<https://arxiv.org/abs/2405.16444>`_"
+
+#: ../../source/index.rst:112
+msgid ""
+"`Do Large Language Models Need a Content Delivery Network? <https://"
+"arxiv.org/abs/2409.13761>`_"
+msgstr ""
+"`Do Large Language Models Need a Content Delivery Network? <https://"
+"arxiv.org/abs/2409.13761>`_"
+
+#: ../../source/index.rst:118
+msgid "Documentation"
+msgstr "文档"
+
+#~ msgid "**Supercharge Your LLM with the Fastest KV Cache Layer.**"
+#~ msgstr "**极速 KV Cache 层，让大模型告别重复计算，全面提升推理效率。**"
+
+#~ msgid ""
+#~ "LMCache lets LLMs prefill each text only once. By storing the KV caches "
+#~ "of all reusable texts, LMCache can reuse the KV caches of any reused text "
+#~ "(not necessarily prefix) in any serving engine instance. It thus reduces "
+#~ "prefill delay, i.e., time to first token (TTFT), as well as saves the "
+#~ "precious GPU cycles and memory."
+#~ msgstr ""
+#~ "LMCache 让 LLM 对每段文本只需预填充一次。通过存储所有可复用文本的 KV 缓"
+#~ "存，LMCache 能在任意推理引擎实例中复用任意可复用文本（不必是前缀）的 KV 缓"
+#~ "存。由此既降低了预填充延迟（即首 token 时间，TTFT），又节省了宝贵的 GPU 算"
+#~ "力与显存。"
+
+#~ msgid ""
+#~ "By combining LMCache with vLLM, LMCache achieves 3-10x delay savings and "
+#~ "GPU cycle reduction in many LLM use cases, including multi-round QA and "
+#~ "RAG."
+#~ msgstr ""
+#~ "将 LMCache 与 vLLM 结合后，在多轮问答、RAG 等众多 LLM 应用场景中，LMCache "
+#~ "可实现 3-10 倍的延迟节省并降低 GPU 算力消耗。"
+
+#~ msgid "Welcome to LMCache"
+#~ msgstr "欢迎使用 LMCache"
+
+#~ msgid "Getting Started"
+#~ msgstr "入门指南"
+
+#~ msgid "Recipes"
+#~ msgstr "使用指南"
+
+#~ msgid "KV Cache offloading and sharing"
+#~ msgstr "KV Cache 卸载和共享"
+
+#~ msgid "Non-KV caching"
+#~ msgstr "非 KV 缓存"
+
+#~ msgid "Multiprocess Mode"
+#~ msgstr "多进程模式"
+
+#~ msgid "Disaggregated prefill"
+#~ msgstr "分离式 Prefill"
+
+#~ msgid "KV Cache management"
+#~ msgstr "KV Cache 管理"
+
+#~ msgid "KV Cache Optimizations"
+#~ msgstr "KV Cache 优化"
+
+#~ msgid "Use LMCache in production"
+#~ msgstr "在生产中使用 LMCache"
+
+#~ msgid "CLI"
+#~ msgstr "命令行界面"
+
+#~ msgid "Internal API Server"
+#~ msgstr "内部 API 服务器"
+
+#~ msgid "Controller WebUI"
+#~ msgstr "控制器 WebUI"
+
+#~ msgid "Developer Guide"
+#~ msgstr "开发者指南"
+
+#~ msgid "API Reference"
+#~ msgstr "API 参考"
+
+#~ msgid "Community"
+#~ msgstr "社区"
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/interacting_with_server.po b/docs/source/locale/zh_CN/LC_MESSAGES/interacting_with_server.po
new file mode 100644
index 0000000..e411f96
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/interacting_with_server.po
@@ -0,0 +1,31 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/interacting_with_server.rst:2
+msgid "KV Cache Operations"
+msgstr "KV Cache 操作"
+
+#: ../../source/interacting_with_server.rst:4
+msgid ""
+"Ways to inspect, manage, and observe a running ``lmcache server`` -- from"
+" the command line, over HTTP, or through the web frontend."
+msgstr "检查、管理和观察正在运行的 ``lmcache server`` 的方法——通过命令行、HTTP 或 Web 前端。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/common_apis.po b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/common_apis.po
new file mode 100644
index 0000000..b8dbc57
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/common_apis.po
@@ -0,0 +1,415 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/internal_api_server/common_apis.rst:4
+msgid "Common APIs"
+msgstr "通用 API"
+
+#: ../../source/internal_api_server/common_apis.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/http_api`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP mode </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/http_api`。"
+
+#: ../../source/internal_api_server/common_apis.rst:11
+msgid ""
+"Common APIs are available across all components (scheduler, worker, "
+"controller)."
+msgstr "所有组件（调度器、工作者、控制器）都提供公共 API。"
+
+#: ../../source/internal_api_server/common_apis.rst:16
+msgid "Endpoints"
+msgstr "端点"
+
+#: ../../source/internal_api_server/common_apis.rst:19
+msgid "``GET /env`` — Environment Variables"
+msgstr "``GET /env`` — 环境变量"
+
+#: ../../source/internal_api_server/common_apis.rst:21
+msgid "Get all environment variables of the running process."
+msgstr "获取运行进程的所有环境变量。"
+
+#: ../../source/internal_api_server/common_apis.rst:23
+#: ../../source/internal_api_server/common_apis.rst:52
+#: ../../source/internal_api_server/common_apis.rst:108
+#: ../../source/internal_api_server/common_apis.rst:138
+#: ../../source/internal_api_server/common_apis.rst:168
+#: ../../source/internal_api_server/common_apis.rst:233
+#: ../../source/internal_api_server/common_apis.rst:264
+msgid "**Method**: ``GET``"
+msgstr "**方法**: ``GET``"
+
+#: ../../source/internal_api_server/common_apis.rst:24
+msgid "**Path**: ``/env``"
+msgstr "**路径**: ``/env``"
+
+#: ../../source/internal_api_server/common_apis.rst:25
+#: ../../source/internal_api_server/common_apis.rst:110
+#: ../../source/internal_api_server/common_apis.rst:125
+#: ../../source/internal_api_server/common_apis.rst:266
+msgid "**Parameters**: None"
+msgstr "**参数**: 无"
+
+#: ../../source/internal_api_server/common_apis.rst:26
+msgid ""
+"**Response**: ``application/json`` — JSON object of all environment "
+"variables (sorted by key)."
+msgstr "**响应**: ``application/json`` — 所有环境变量的 JSON 对象（按键排序）。"
+
+#: ../../source/internal_api_server/common_apis.rst:32
+#: ../../source/internal_api_server/common_apis.rst:193
+#: ../../source/internal_api_server/common_apis.rst:339
+msgid "**Example Response**:"
+msgstr "**示例响应**:"
+
+#: ../../source/internal_api_server/common_apis.rst:44
+msgid "``GET /loglevel`` — Log Level Management"
+msgstr "``GET /loglevel`` — 日志级别管理"
+
+#: ../../source/internal_api_server/common_apis.rst:46
+msgid ""
+"Get or set the log level for Python loggers. Behavior depends on query "
+"parameters:"
+msgstr "获取或设置 Python 日志记录器的日志级别。行为取决于查询参数："
+
+#: ../../source/internal_api_server/common_apis.rst:48
+msgid "**No parameters**: List all loggers and their levels."
+msgstr "**无参数**\\ ：列出所有记录器及其级别。"
+
+#: ../../source/internal_api_server/common_apis.rst:49
+msgid "**``logger_name`` only**: Get the level of the specified logger."
+msgstr "**``logger_name`` 仅**: 获取指定记录器的级别。"
+
+#: ../../source/internal_api_server/common_apis.rst:50
+msgid ""
+"**``logger_name`` and ``level``**: Set the level of the specified logger "
+"(including all its handlers)."
+msgstr "**``logger_name`` 和 ``level``**: 设置指定记录器（包括其所有处理程序）的级别。"
+
+#: ../../source/internal_api_server/common_apis.rst:53
+msgid "**Path**: ``/loglevel``"
+msgstr "**路径**: ``/loglevel``"
+
+#: ../../source/internal_api_server/common_apis.rst:54
+#: ../../source/internal_api_server/common_apis.rst:140
+#: ../../source/internal_api_server/common_apis.rst:170
+#: ../../source/internal_api_server/common_apis.rst:312
+msgid "**Parameters**:"
+msgstr "**参数**:"
+
+#: ../../source/internal_api_server/common_apis.rst:57
+#: ../../source/internal_api_server/common_apis.rst:143
+#: ../../source/internal_api_server/common_apis.rst:173
+#: ../../source/internal_api_server/common_apis.rst:238
+#: ../../source/internal_api_server/common_apis.rst:315
+msgid "Name"
+msgstr "名称"
+
+#: ../../source/internal_api_server/common_apis.rst:57
+#: ../../source/internal_api_server/common_apis.rst:143
+#: ../../source/internal_api_server/common_apis.rst:173
+#: ../../source/internal_api_server/common_apis.rst:238
+#: ../../source/internal_api_server/common_apis.rst:315
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/internal_api_server/common_apis.rst:57
+#: ../../source/internal_api_server/common_apis.rst:143
+#: ../../source/internal_api_server/common_apis.rst:173
+#: ../../source/internal_api_server/common_apis.rst:238
+#: ../../source/internal_api_server/common_apis.rst:315
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/internal_api_server/common_apis.rst:59
+msgid "``logger_name``"
+msgstr "``logger_name``"
+
+#: ../../source/internal_api_server/common_apis.rst:59
+#: ../../source/internal_api_server/common_apis.rst:60
+#: ../../source/internal_api_server/common_apis.rst:145
+#: ../../source/internal_api_server/common_apis.rst:175
+#: ../../source/internal_api_server/common_apis.rst:240
+msgid "str"
+msgstr "字符串"
+
+#: ../../source/internal_api_server/common_apis.rst:59
+msgid "(Optional) Logger name to query or set"
+msgstr "(可选) 查询或设置的日志记录器名称"
+
+#: ../../source/internal_api_server/common_apis.rst:60
+#: ../../source/internal_api_server/common_apis.rst:175
+msgid "``level``"
+msgstr "``level``"
+
+#: ../../source/internal_api_server/common_apis.rst:60
+msgid ""
+"(Optional) Log level to set (e.g. ``DEBUG``, ``INFO``, ``WARNING``, "
+"``ERROR``)"
+msgstr "(可选) 设置的日志级别 (例如 ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``)"
+
+#: ../../source/internal_api_server/common_apis.rst:63
+msgid "**Response**: ``text/plain``"
+msgstr "**响应**: ``text/plain``"
+
+#: ../../source/internal_api_server/common_apis.rst:76
+msgid "**Example Response** (list all):"
+msgstr "**示例响应**\\ （列出所有）："
+
+#: ../../source/internal_api_server/common_apis.rst:84
+msgid "**Example Response** (get):"
+msgstr "**示例响应**\\ （获取）："
+
+#: ../../source/internal_api_server/common_apis.rst:90
+msgid "**Example Response** (set):"
+msgstr "**示例响应** (设置):"
+
+#: ../../source/internal_api_server/common_apis.rst:96
+#: ../../source/internal_api_server/common_apis.rst:219
+msgid "**Error Response** (invalid level, HTTP 400):"
+msgstr "**错误响应**\\ （无效级别，HTTP 400）："
+
+#: ../../source/internal_api_server/common_apis.rst:104
+msgid "``GET /metrics`` — Prometheus Metrics"
+msgstr "``GET /metrics`` — Prometheus 指标"
+
+#: ../../source/internal_api_server/common_apis.rst:106
+msgid "Get Prometheus metrics data in the standard exposition format."
+msgstr "以标准展示格式获取 Prometheus 指标数据。"
+
+#: ../../source/internal_api_server/common_apis.rst:109
+msgid "**Path**: ``/metrics``"
+msgstr "**路径**: ``/metrics``"
+
+#: ../../source/internal_api_server/common_apis.rst:111
+msgid "**Response**: ``text/plain`` — Prometheus text-based exposition format."
+msgstr "**响应**: ``text/plain`` — Prometheus 文本格式的展示。"
+
+#: ../../source/internal_api_server/common_apis.rst:119
+msgid "``POST /metrics/reset`` — Reset Prometheus Metrics"
+msgstr "``POST /metrics/reset`` — 重置 Prometheus 指标"
+
+#: ../../source/internal_api_server/common_apis.rst:121
+msgid "Reset all Prometheus metrics to their initial state."
+msgstr "重置所有 Prometheus 指标为其初始状态。"
+
+#: ../../source/internal_api_server/common_apis.rst:123
+#: ../../source/internal_api_server/common_apis.rst:309
+msgid "**Method**: ``POST``"
+msgstr "**方法**: ``POST``"
+
+#: ../../source/internal_api_server/common_apis.rst:124
+msgid "**Path**: ``/metrics/reset``"
+msgstr "**路径**: ``/metrics/reset``"
+
+#: ../../source/internal_api_server/common_apis.rst:126
+msgid "**Response**: ``text/plain`` — ``\"ok\"`` on success."
+msgstr "**响应**: ``text/plain`` — ``\"ok\"`` 表示成功。"
+
+#: ../../source/internal_api_server/common_apis.rst:134
+msgid "``GET /threads`` — Thread Information"
+msgstr "``GET /threads`` — 线程信息"
+
+#: ../../source/internal_api_server/common_apis.rst:136
+msgid "Get information about active threads with optional filtering."
+msgstr "获取有关活动线程的信息，并可选择性地进行过滤。"
+
+#: ../../source/internal_api_server/common_apis.rst:139
+msgid "**Path**: ``/threads``"
+msgstr "**路径**: ``/threads``"
+
+#: ../../source/internal_api_server/common_apis.rst:145
+msgid "``name``"
+msgstr "``name``"
+
+#: ../../source/internal_api_server/common_apis.rst:145
+msgid "(Optional) Filter by thread name (fuzzy match, case-insensitive)"
+msgstr "(可选) 按线程名称过滤（模糊匹配，大小写不敏感）"
+
+#: ../../source/internal_api_server/common_apis.rst:146
+msgid "``thread_id``"
+msgstr "``thread_id``"
+
+#: ../../source/internal_api_server/common_apis.rst:146
+msgid "int"
+msgstr "整数"
+
+#: ../../source/internal_api_server/common_apis.rst:146
+msgid "(Optional) Filter by thread ID"
+msgstr "（可选）按线程 ID 过滤"
+
+#: ../../source/internal_api_server/common_apis.rst:149
+msgid "**Response**: ``text/plain`` — Thread info with stack traces and summary."
+msgstr "**响应**: ``text/plain`` — 包含堆栈跟踪和摘要的线程信息。"
+
+#: ../../source/internal_api_server/common_apis.rst:164
+msgid "``GET /periodic-threads`` — Periodic Thread Status"
+msgstr "``GET /periodic-threads`` — 周期性线程状态"
+
+#: ../../source/internal_api_server/common_apis.rst:166
+msgid "Get information about registered periodic threads."
+msgstr "获取有关注册的周期性线程的信息。"
+
+#: ../../source/internal_api_server/common_apis.rst:169
+msgid "**Path**: ``/periodic-threads``"
+msgstr "**路径**: ``/periodic-threads``"
+
+#: ../../source/internal_api_server/common_apis.rst:175
+msgid ""
+"(Optional) Filter by thread level: ``critical``, ``high``, ``medium``, "
+"``low``"
+msgstr "(可选) 按线程级别过滤：\\ ``critical``\\ 、\\ ``high``\\ 、\\ ``medium``\\ 、\\ ``low``"
+
+#: ../../source/internal_api_server/common_apis.rst:176
+msgid "``running_only``"
+msgstr "``running_only``"
+
+#: ../../source/internal_api_server/common_apis.rst:176
+#: ../../source/internal_api_server/common_apis.rst:177
+msgid "bool"
+msgstr "布尔值"
+
+#: ../../source/internal_api_server/common_apis.rst:176
+msgid "(Optional) Only show running threads (default: ``false``)"
+msgstr "(可选) 仅显示正在运行的线程（默认值：\\ ``false``\\ ）"
+
+#: ../../source/internal_api_server/common_apis.rst:177
+msgid "``active_only``"
+msgstr "``active_only``"
+
+#: ../../source/internal_api_server/common_apis.rst:177
+msgid "(Optional) Only show active threads (default: ``false``)"
+msgstr "(可选) 仅显示活动线程（默认值：\\ ``false``\\ ）"
+
+#: ../../source/internal_api_server/common_apis.rst:180
+#: ../../source/internal_api_server/common_apis.rst:243
+#: ../../source/internal_api_server/common_apis.rst:267
+msgid "**Response**: ``application/json``"
+msgstr "**响应**: ``application/json``"
+
+#: ../../source/internal_api_server/common_apis.rst:229
+#, python-brace-format
+msgid "``GET /periodic-threads/{thread_name}`` — Single Periodic Thread"
+msgstr "``GET /periodic-threads/{thread_name}`` — 单个周期线程"
+
+#: ../../source/internal_api_server/common_apis.rst:231
+msgid "Get detailed information about a specific periodic thread by name."
+msgstr "通过名称获取特定周期线程的详细信息。"
+
+#: ../../source/internal_api_server/common_apis.rst:234
+#, python-brace-format
+msgid "**Path**: ``/periodic-threads/{thread_name}``"
+msgstr "**路径**: ``/periodic-threads/{thread_name}``"
+
+#: ../../source/internal_api_server/common_apis.rst:235
+msgid "**Path Parameters**:"
+msgstr "**路径参数**\\ ："
+
+#: ../../source/internal_api_server/common_apis.rst:240
+msgid "``thread_name``"
+msgstr "``thread_name``"
+
+#: ../../source/internal_api_server/common_apis.rst:240
+msgid "Name of the periodic thread"
+msgstr "周期性线程的名称"
+
+#: ../../source/internal_api_server/common_apis.rst:249
+msgid "**Error Response** (not found, HTTP 404):"
+msgstr "**错误响应**\\ （未找到，HTTP 404）："
+
+#: ../../source/internal_api_server/common_apis.rst:259
+msgid "``GET /periodic-threads-health`` — Periodic Thread Health Check"
+msgstr "``GET /periodic-threads-health`` — 周期性线程健康检查"
+
+#: ../../source/internal_api_server/common_apis.rst:261
+msgid ""
+"Quick health check for periodic threads. Returns healthy status if all "
+"``critical`` and ``high`` level threads are active."
+msgstr "对周期性线程的快速健康检查。如果所有 ``critical`` 和 ``high`` 级别的线程都处于活动状态，则返回健康状态。"
+
+#: ../../source/internal_api_server/common_apis.rst:265
+msgid "**Path**: ``/periodic-threads-health``"
+msgstr "**路径**: ``/periodic-threads-health``"
+
+#: ../../source/internal_api_server/common_apis.rst:273
+msgid "**Example Response** (healthy):"
+msgstr "**示例响应**\\ （健康）："
+
+#: ../../source/internal_api_server/common_apis.rst:283
+msgid "**Example Response** (unhealthy):"
+msgstr "**示例响应**\\ （不健康）："
+
+#: ../../source/internal_api_server/common_apis.rst:302
+msgid "``POST /run_script`` — Run Script"
+msgstr "``POST /run_script`` — 运行脚本"
+
+#: ../../source/internal_api_server/common_apis.rst:304
+msgid ""
+"Upload and execute a Python script in a restricted sandbox environment. "
+"The script has access to ``app`` (the FastAPI application instance) and a"
+" limited set of builtins. Import is restricted to modules configured in "
+"``script_allowed_imports``."
+msgstr ""
+"在受限的沙箱环境中上传并执行 Python 脚本。该脚本可以访问 ``app``\\ （FastAPI 应用实例）和有限的内置函数。导入仅限于在 "
+"``script_allowed_imports`` 中配置的模块。"
+
+#: ../../source/internal_api_server/common_apis.rst:310
+msgid "**Path**: ``/run_script``"
+msgstr "**路径**: ``/run_script``"
+
+#: ../../source/internal_api_server/common_apis.rst:311
+msgid "**Content-Type**: ``multipart/form-data``"
+msgstr "**内容类型**: ``multipart/form-data``"
+
+#: ../../source/internal_api_server/common_apis.rst:317
+msgid "``script``"
+msgstr "``script``"
+
+#: ../../source/internal_api_server/common_apis.rst:317
+msgid "file"
+msgstr "文件"
+
+#: ../../source/internal_api_server/common_apis.rst:317
+msgid "Python script file to execute"
+msgstr "要执行的 Python 脚本文件"
+
+#: ../../source/internal_api_server/common_apis.rst:320
+msgid ""
+"**Response**: ``text/plain`` — The ``result`` variable from the script, "
+"or ``\"Script executed successfully\"`` if no ``result`` is set."
+msgstr ""
+"**响应**: ``text/plain`` — 脚本中的 ``result`` 变量，或者如果没有设置 ``result`` 则为 "
+"``\"脚本执行成功\"``\\ 。"
+
+#: ../../source/internal_api_server/common_apis.rst:328
+msgid "**Example Script** (``scratch.py``):"
+msgstr "**示例脚本** (``scratch.py``):"
+
+#: ../../source/internal_api_server/common_apis.rst:345
+msgid "**Error Response** (no script, HTTP 400):"
+msgstr "**错误响应**\\ （无脚本，HTTP 400）："
+
+#: ../../source/internal_api_server/common_apis.rst:351
+msgid "**Error Response** (execution error, HTTP 500):"
+msgstr "**错误响应**\\ （执行错误，HTTP 500）："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/controller_apis.po b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/controller_apis.po
new file mode 100644
index 0000000..83ae483
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/controller_apis.po
@@ -0,0 +1,317 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/internal_api_server/controller_apis.rst:4
+msgid "Controller APIs"
+msgstr "控制器 API"
+
+#: ../../source/internal_api_server/controller_apis.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/http_api`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/http_api`。"
+
+#: ../../source/internal_api_server/controller_apis.rst:11
+msgid ""
+"These APIs are specific to the LMCache Controller component. They provide"
+" visibility into registered instances, workers, and key statistics."
+msgstr "这些 API 是特定于 LMCache Controller 组件的。它们提供对注册实例、工作者和关键统计信息的可见性。"
+
+#: ../../source/internal_api_server/controller_apis.rst:17
+msgid "Endpoints"
+msgstr "端点"
+
+#: ../../source/internal_api_server/controller_apis.rst:20
+msgid "``GET /controller/key-stats`` — Key Statistics"
+msgstr "``GET /controller/key-stats`` — 关键统计信息"
+
+#: ../../source/internal_api_server/controller_apis.rst:22
+msgid "Get key statistics across all instances and workers."
+msgstr "获取所有实例和工作节点的关键统计信息。"
+
+#: ../../source/internal_api_server/controller_apis.rst:24
+#: ../../source/internal_api_server/controller_apis.rst:95
+msgid "**Method**: ``GET``"
+msgstr "**方法**: ``GET``"
+
+#: ../../source/internal_api_server/controller_apis.rst:25
+msgid "**Path**: ``/controller/key-stats``"
+msgstr "**路径**: ``/controller/key-stats``"
+
+#: ../../source/internal_api_server/controller_apis.rst:26
+msgid "**Parameters**: None"
+msgstr "**参数**: 无"
+
+#: ../../source/internal_api_server/controller_apis.rst:27
+#: ../../source/internal_api_server/controller_apis.rst:106
+msgid "**Response**: ``application/json``"
+msgstr "**响应**: ``application/json``"
+
+#: ../../source/internal_api_server/controller_apis.rst:33
+msgid "**Example Response** (HTTP 200):"
+msgstr "**示例响应** (HTTP 200):"
+
+#: ../../source/internal_api_server/controller_apis.rst:55
+#: ../../source/internal_api_server/controller_apis.rst:180
+msgid "**Error Response** (controller not available, HTTP 503):"
+msgstr "**错误响应**\\ （控制器不可用，HTTP 503）："
+
+#: ../../source/internal_api_server/controller_apis.rst:63
+msgid "**Response Schema**:"
+msgstr "**响应模式**:"
+
+#: ../../source/internal_api_server/controller_apis.rst:66
+#: ../../source/internal_api_server/controller_apis.rst:77
+#: ../../source/internal_api_server/controller_apis.rst:191
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/internal_api_server/controller_apis.rst:66
+#: ../../source/internal_api_server/controller_apis.rst:77
+#: ../../source/internal_api_server/controller_apis.rst:100
+#: ../../source/internal_api_server/controller_apis.rst:191
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/internal_api_server/controller_apis.rst:66
+#: ../../source/internal_api_server/controller_apis.rst:77
+#: ../../source/internal_api_server/controller_apis.rst:100
+#: ../../source/internal_api_server/controller_apis.rst:191
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/internal_api_server/controller_apis.rst:68
+msgid "``total_key_count``"
+msgstr "``total_key_count``"
+
+#: ../../source/internal_api_server/controller_apis.rst:68
+#: ../../source/internal_api_server/controller_apis.rst:69
+#: ../../source/internal_api_server/controller_apis.rst:70
+#: ../../source/internal_api_server/controller_apis.rst:80
+#: ../../source/internal_api_server/controller_apis.rst:81
+#: ../../source/internal_api_server/controller_apis.rst:103
+#: ../../source/internal_api_server/controller_apis.rst:194
+#: ../../source/internal_api_server/controller_apis.rst:196
+#: ../../source/internal_api_server/controller_apis.rst:200
+msgid "int"
+msgstr "整数"
+
+#: ../../source/internal_api_server/controller_apis.rst:68
+msgid "Total number of KV keys across all instances"
+msgstr "所有实例中 KV 键的总数"
+
+#: ../../source/internal_api_server/controller_apis.rst:69
+msgid "``total_instance_count``"
+msgstr "``total_instance_count``"
+
+#: ../../source/internal_api_server/controller_apis.rst:69
+msgid "Total number of registered instances"
+msgstr "注册实例的总数"
+
+#: ../../source/internal_api_server/controller_apis.rst:70
+msgid "``total_worker_count``"
+msgstr "``total_worker_count``"
+
+#: ../../source/internal_api_server/controller_apis.rst:70
+msgid "Total number of workers across all instances"
+msgstr "所有实例的工作线程总数"
+
+#: ../../source/internal_api_server/controller_apis.rst:71
+msgid "``instances``"
+msgstr "``instances``"
+
+#: ../../source/internal_api_server/controller_apis.rst:71
+msgid "list"
+msgstr "列表"
+
+#: ../../source/internal_api_server/controller_apis.rst:71
+msgid "Per-instance breakdown (see below)"
+msgstr "每个实例的详细信息（见下文）"
+
+#: ../../source/internal_api_server/controller_apis.rst:74
+msgid "**Instance Schema**:"
+msgstr "**实例架构**:"
+
+#: ../../source/internal_api_server/controller_apis.rst:79
+#: ../../source/internal_api_server/controller_apis.rst:102
+#: ../../source/internal_api_server/controller_apis.rst:193
+msgid "``instance_id``"
+msgstr "``instance_id``"
+
+#: ../../source/internal_api_server/controller_apis.rst:79
+#: ../../source/internal_api_server/controller_apis.rst:102
+#: ../../source/internal_api_server/controller_apis.rst:193
+#: ../../source/internal_api_server/controller_apis.rst:195
+#: ../../source/internal_api_server/controller_apis.rst:197
+msgid "str"
+msgstr "字符串"
+
+#: ../../source/internal_api_server/controller_apis.rst:79
+msgid "Unique identifier of the instance"
+msgstr "实例的唯一标识符"
+
+#: ../../source/internal_api_server/controller_apis.rst:80
+#: ../../source/internal_api_server/controller_apis.rst:200
+msgid "``key_count``"
+msgstr "``key_count``"
+
+#: ../../source/internal_api_server/controller_apis.rst:80
+msgid "Number of KV keys held by this instance"
+msgstr "此实例持有的 KV 键数量"
+
+#: ../../source/internal_api_server/controller_apis.rst:81
+msgid "``worker_count``"
+msgstr "``worker_count``"
+
+#: ../../source/internal_api_server/controller_apis.rst:81
+msgid "Number of workers in this instance"
+msgstr "此实例中的工作线程数量"
+
+#: ../../source/internal_api_server/controller_apis.rst:86
+msgid "``GET /controller/workers`` — Worker Information"
+msgstr "``GET /controller/workers`` — 工作信息"
+
+#: ../../source/internal_api_server/controller_apis.rst:88
+msgid ""
+"Get worker information with flexible query parameters. Behavior depends "
+"on the combination of parameters:"
+msgstr "使用灵活的查询参数获取工作信息。行为取决于参数的组合："
+
+#: ../../source/internal_api_server/controller_apis.rst:91
+msgid "**No parameters**: List all registered workers across all instances."
+msgstr "**无参数**\\ ：列出所有实例中注册的所有工作者。"
+
+#: ../../source/internal_api_server/controller_apis.rst:92
+msgid "**``instance_id`` only**: List all workers for a specific instance."
+msgstr "**``instance_id`` 仅**: 列出特定实例的所有工作者。"
+
+#: ../../source/internal_api_server/controller_apis.rst:93
+msgid ""
+"**``instance_id`` and ``worker_id``**: Get detailed info about a specific"
+" worker."
+msgstr "**``instance_id`` 和 ``worker_id``**: 获取特定工作者的详细信息。"
+
+#: ../../source/internal_api_server/controller_apis.rst:96
+msgid "**Path**: ``/controller/workers``"
+msgstr "**路径**: ``/controller/workers``"
+
+#: ../../source/internal_api_server/controller_apis.rst:97
+msgid "**Parameters**:"
+msgstr "**参数**:"
+
+#: ../../source/internal_api_server/controller_apis.rst:100
+msgid "Name"
+msgstr "名称"
+
+#: ../../source/internal_api_server/controller_apis.rst:102
+msgid "(Optional) Instance ID to filter workers"
+msgstr "（可选）用于过滤工作节点的实例 ID"
+
+#: ../../source/internal_api_server/controller_apis.rst:103
+#: ../../source/internal_api_server/controller_apis.rst:194
+msgid "``worker_id``"
+msgstr "``worker_id``"
+
+#: ../../source/internal_api_server/controller_apis.rst:103
+msgid ""
+"(Optional) Worker ID for specific worker details (requires "
+"``instance_id``)"
+msgstr "（可选）特定工作者详细信息的工作者 ID（需要 ``instance_id``\\ ）"
+
+#: ../../source/internal_api_server/controller_apis.rst:119
+msgid "**Example Response** (list workers):"
+msgstr "**示例响应**\\ （列出工作者）："
+
+#: ../../source/internal_api_server/controller_apis.rst:149
+msgid "**Example Response** (single worker):"
+msgstr "**示例响应**\\ （单个工作者）："
+
+#: ../../source/internal_api_server/controller_apis.rst:164
+msgid "**Error Response** (worker not found, HTTP 404):"
+msgstr "**错误响应**\\ （未找到工作者，HTTP 404）："
+
+#: ../../source/internal_api_server/controller_apis.rst:172
+msgid "**Error Response** (instance not found, HTTP 404):"
+msgstr "**错误响应**\\ （实例未找到，HTTP 404）："
+
+#: ../../source/internal_api_server/controller_apis.rst:188
+msgid "**Worker Response Schema**:"
+msgstr "**工作者响应模式**:"
+
+#: ../../source/internal_api_server/controller_apis.rst:193
+msgid "Instance this worker belongs to"
+msgstr "该工作者所属的实例"
+
+#: ../../source/internal_api_server/controller_apis.rst:194
+msgid "Worker index within the instance"
+msgstr "实例内的工作线程索引"
+
+#: ../../source/internal_api_server/controller_apis.rst:195
+msgid "``ip``"
+msgstr "``ip``"
+
+#: ../../source/internal_api_server/controller_apis.rst:195
+msgid "Worker IP address"
+msgstr "工作节点 IP 地址"
+
+#: ../../source/internal_api_server/controller_apis.rst:196
+msgid "``port``"
+msgstr "``port``"
+
+#: ../../source/internal_api_server/controller_apis.rst:196
+msgid "Worker port number"
+msgstr "工作端口号"
+
+#: ../../source/internal_api_server/controller_apis.rst:197
+msgid "``peer_init_url``"
+msgstr "``peer_init_url``"
+
+#: ../../source/internal_api_server/controller_apis.rst:197
+msgid "(Optional) Peer initialization URL"
+msgstr "(可选) 对等初始化 URL"
+
+#: ../../source/internal_api_server/controller_apis.rst:198
+msgid "``registration_time``"
+msgstr "``registration_time``"
+
+#: ../../source/internal_api_server/controller_apis.rst:198
+#: ../../source/internal_api_server/controller_apis.rst:199
+msgid "float"
+msgstr "浮点数"
+
+#: ../../source/internal_api_server/controller_apis.rst:198
+msgid "Unix timestamp of worker registration"
+msgstr "工作节点注册的 Unix 时间戳"
+
+#: ../../source/internal_api_server/controller_apis.rst:199
+msgid "``last_heartbeat_time``"
+msgstr "``last_heartbeat_time``"
+
+#: ../../source/internal_api_server/controller_apis.rst:199
+msgid "Unix timestamp of last heartbeat"
+msgstr "最后心跳的 Unix 时间戳"
+
+#: ../../source/internal_api_server/controller_apis.rst:200
+msgid "Number of KV keys held by this worker"
+msgstr "此工作线程持有的 KV 键数量"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/dynamic_backend_management.po b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/dynamic_backend_management.po
new file mode 100644
index 0000000..dcf316e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/dynamic_backend_management.po
@@ -0,0 +1,174 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:4
+msgid "Dynamic Backend Management"
+msgstr "动态后端管理"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/http_api`."
+msgstr "此页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/http_api`。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:11
+msgid ""
+"LMCache provides a set of internal API endpoints that allow you to "
+"**list**, **close**, and **create** storage backends at runtime without "
+"restarting the serving engine.  This is useful when you need to switch "
+"between different storage configurations on the fly — for example, "
+"migrating from a ``LocalDiskBackend`` to a ``GdsBackend``, or changing "
+"the remote connector from a filesystem connector to Redis."
+msgstr ""
+"LMCache 提供了一组内部 API 端点，允许您在运行时 **列出**\\ 、\\ **关闭** 和 **创建** "
+"存储后端，而无需重启服务引擎。当您需要动态切换不同的存储配置时，这非常有用——例如，从 ``LocalDiskBackend`` 迁移到 "
+"``GdsBackend``\\ ，或将远程连接器从文件系统连接器更改为 Redis。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:19
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:21
+msgid "The workflow for dynamically switching a storage backend is:"
+msgstr "动态切换存储后端的工作流程是："
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:23
+msgid "**Close** the backend you want to replace."
+msgstr "**关闭**\\ 您想要替换的后端。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:24
+msgid "**Update** the relevant configuration via the ``POST /conf`` API."
+msgstr "**更新**\\ 相关配置通过 ``POST /conf`` API。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:25
+msgid ""
+"**Create** new backends — only backends that are not already present will"
+" be created."
+msgstr "**创建** 新的后端 — 只有尚不存在的后端才会被创建。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:28
+msgid ""
+"Any backend that was **not** closed will be skipped during creation, so "
+"the operation is safe and idempotent."
+msgstr "任何\\ **未**\\ 关闭的后端在创建过程中将被跳过，因此该操作是安全且幂等的。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:32
+msgid "API Endpoints"
+msgstr "API 端点"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:35
+msgid "``GET /backends``"
+msgstr "``GET /backends``"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:37
+msgid "List all active storage backends."
+msgstr "列出所有活动的存储后端。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:43
+#: ../../source/internal_api_server/dynamic_backend_management.rst:63
+#: ../../source/internal_api_server/dynamic_backend_management.rst:85
+msgid "Response:"
+msgstr "响应："
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:53
+#, python-brace-format
+msgid "``DELETE /backends/{backend_name}``"
+msgstr "``DELETE /backends/{backend_name}``"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:55
+msgid ""
+"Close and remove a specific storage backend.  After this call the backend"
+" is fully shut down and removed from the internal dictionary, ensuring no"
+" stale references remain."
+msgstr "关闭并移除特定的存储后端。此调用后，后端将完全关闭并从内部字典中移除，确保没有过时的引用残留。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:76
+msgid "``POST /backends``"
+msgstr "``POST /backends``"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:78
+msgid ""
+"Create new storage backends based on the current ``LMCacheEngineConfig``."
+" Existing backends are skipped."
+msgstr "根据当前的 ``LMCacheEngineConfig`` 创建新的存储后端。现有的后端将被跳过。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:101
+msgid "Use-Case Examples"
+msgstr "用例示例"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:104
+msgid "Switching from ``LocalDiskBackend`` to ``GdsBackend``"
+msgstr "从 ``LocalDiskBackend`` 切换到 ``GdsBackend``"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:106
+msgid ""
+"If you originally configured a local-disk backend and want to migrate to "
+"NVIDIA GPUDirect Storage (GDS) at runtime:"
+msgstr "如果您最初配置了本地磁盘后端，并希望在运行时迁移到 NVIDIA GPUDirect Storage (GDS)："
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:129
+msgid "Switching ``RemoteBackend`` connector (FS → Redis)"
+msgstr "切换 ``RemoteBackend`` 连接器 (FS → Redis)"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:131
+msgid "To change the remote connector type without restarting:"
+msgstr "要在不重启的情况下更改远程连接器类型："
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:152
+msgid "Replacing only one backend while keeping others"
+msgstr "仅替换一个后端而保持其他后端不变"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:154
+msgid ""
+"If only the ``RemoteBackend`` needs to be updated but the "
+"``LocalCPUBackend`` should stay untouched:"
+msgstr "如果只需要更新 ``RemoteBackend`` 而 ``LocalCPUBackend`` 应保持不变："
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:171
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:173
+msgid ""
+"Closing the ``LocalCPUBackend`` is possible but should be done with "
+"caution since many other backends rely on it as an intermediate buffer."
+msgstr "关闭 ``LocalCPUBackend`` 是可能的，但应谨慎进行，因为许多其他后端依赖它作为中间缓冲区。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:175
+msgid ""
+"The ``POST /backends`` endpoint calls the same ``CreateStorageBackends`` "
+"factory that is used during engine initialization, so all backend types "
+"(local CPU, local disk, GDS, remote, P2P, plugins, etc.) are supported."
+msgstr ""
+"``POST /backends`` 端点调用与引擎初始化期间使用的相同 ``CreateStorageBackends`` "
+"工厂，因此支持所有后端类型（本地 CPU、本地磁盘、GDS、远程、P2P、插件等）。"
+
+#: ../../source/internal_api_server/dynamic_backend_management.rst:179
+msgid ""
+"After creating backends, the ``StorageManager`` automatically refreshes "
+"its internal references (``non_allocator_backends``, "
+"``local_cpu_backend``, etc.)."
+msgstr ""
+"创建后端后，\\ ``StorageManager`` 会自动刷新其内部引用（\\ ``non_allocator_backends``\\ "
+"、\\ ``local_cpu_backend`` 等）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/internal_api_server.po b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/internal_api_server.po
new file mode 100644
index 0000000..7962d16
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/internal_api_server.po
@@ -0,0 +1,128 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/internal_api_server/internal_api_server.rst:4
+msgid "Internal API Server"
+msgstr "内部 API 服务器"
+
+#: ../../source/internal_api_server/internal_api_server.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/http_api`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP mode </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/http_api`。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:11
+msgid ""
+"The ``internal_api_server`` provides HTTP APIs for managing and "
+"inspecting the LMCache engine at runtime. APIs are organized into three "
+"categories:"
+msgstr "``internal_api_server`` 提供用于在运行时管理和检查 LMCache 引擎的 HTTP API。API 被组织为三个类别："
+
+#: ../../source/internal_api_server/internal_api_server.rst:14
+msgid ""
+"**Common APIs** — Available across all components (scheduler, worker, "
+"controller)."
+msgstr "**通用 API** — 在所有组件（调度器、工作线程、控制器）中可用。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:15
+msgid "**vLLM / Inference APIs** — Specific to vLLM inference workers."
+msgstr "**vLLM / 推理 API** — 特定于 vLLM 推理工作节点。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:16
+msgid "**Controller APIs** — Specific to the LMCache Controller."
+msgstr "**控制器 API** — 特定于 LMCache 控制器。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:27
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/internal_api_server/internal_api_server.rst:29
+msgid "The following parameters can be configured in the YAML file:"
+msgstr "以下参数可以在 YAML 文件中配置："
+
+#: ../../source/internal_api_server/internal_api_server.rst:51
+msgid "Port Assignment"
+msgstr "端口分配"
+
+#: ../../source/internal_api_server/internal_api_server.rst:53
+msgid "The port for each component is computed as:"
+msgstr "每个组件的端口计算公式为："
+
+#: ../../source/internal_api_server/internal_api_server.rst:59
+msgid "Where ``port_offset`` is:"
+msgstr "``port_offset`` 是："
+
+#: ../../source/internal_api_server/internal_api_server.rst:61
+msgid "``0`` for the Scheduler"
+msgstr "``0`` 用于调度器"
+
+#: ../../source/internal_api_server/internal_api_server.rst:62
+msgid ""
+"``1 + worker_id`` for Workers (e.g., Worker 0 → offset 1, Worker 1 → "
+"offset 2)"
+msgstr "``1 + worker_id`` 用于工作进程（例如，工作进程 0 → 偏移 1，工作进程 1 → 偏移 2）"
+
+#: ../../source/internal_api_server/internal_api_server.rst:66
+msgid "API Category & Route Discovery"
+msgstr "API 类别与路由发现"
+
+#: ../../source/internal_api_server/internal_api_server.rst:68
+#, python-brace-format
+msgid ""
+"The server uses ``APIRegistry`` to automatically discover and register "
+"API endpoint modules. Any file named ``*_api.py`` under "
+"``lmcache/v1/internal_api_server/{common,vllm,controller}/`` that exports"
+" a ``router = APIRouter()`` will be automatically included."
+msgstr ""
+"服务器使用 ``APIRegistry`` 自动发现和注册 API 端点模块。任何位于 "
+"``lmcache/v1/internal_api_server/{common,vllm,controller}/`` 下并导出 "
+"``router = APIRouter()`` 的文件，名称以 ``*_api.py`` 结尾，将会被自动包含。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:75
+msgid "Extending the Server"
+msgstr "扩展服务器"
+
+#: ../../source/internal_api_server/internal_api_server.rst:77
+msgid "To add a new API endpoint:"
+msgstr "要添加一个新的 API 端点："
+
+#: ../../source/internal_api_server/internal_api_server.rst:79
+msgid ""
+"Create a new file in the appropriate category directory (``common/``, "
+"``vllm/``, or ``controller/``)."
+msgstr "在适当的类别目录中创建一个新文件（``common/``、``vllm/`` 或 ``controller/``）。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:81
+msgid "Name the file with ``_api.py`` suffix (e.g., ``my_feature_api.py``)."
+msgstr "将文件命名为 ``_api.py`` 后缀（例如，``my_feature_api.py``）。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:82
+msgid "Define ``router = APIRouter()`` and add your endpoints."
+msgstr "定义 ``router = APIRouter()`` 并添加你的端点。"
+
+#: ../../source/internal_api_server/internal_api_server.rst:84
+msgid ""
+"The endpoint will be automatically discovered and registered on the next "
+"server startup."
+msgstr "该端点将在下次服务器启动时自动发现并注册。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/vllm_apis.po b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/vllm_apis.po
new file mode 100644
index 0000000..5694e6a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/internal_api_server/vllm_apis.po
@@ -0,0 +1,1046 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/internal_api_server/vllm_apis.rst:4
+msgid "vLLM / Inference APIs"
+msgstr "vLLM / 推理 API"
+
+#: ../../source/internal_api_server/vllm_apis.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/http_api`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/http_api`。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:11
+msgid ""
+"These APIs are specific to vLLM inference workers and provide cache "
+"management, configuration, freeze control, chunk statistics, and version "
+"information."
+msgstr "这些 API 特定于 vLLM 推理工作者，提供缓存管理、配置、冻结控制、块统计和版本信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:17
+msgid "Endpoints"
+msgstr "端点"
+
+#: ../../source/internal_api_server/vllm_apis.rst:20
+msgid "Version & Info"
+msgstr "版本与信息"
+
+#: ../../source/internal_api_server/vllm_apis.rst:23
+msgid "``GET /lmc_version`` — LMCache Version"
+msgstr "``GET /lmc_version`` — LMCache 版本"
+
+#: ../../source/internal_api_server/vllm_apis.rst:25
+msgid "Get the LMCache library version string."
+msgstr "获取 LMCache 库版本字符串。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:27
+#: ../../source/internal_api_server/vllm_apis.rst:42
+#: ../../source/internal_api_server/vllm_apis.rst:57
+#: ../../source/internal_api_server/vllm_apis.rst:72
+#: ../../source/internal_api_server/vllm_apis.rst:103
+#: ../../source/internal_api_server/vllm_apis.rst:129
+#: ../../source/internal_api_server/vllm_apis.rst:210
+#: ../../source/internal_api_server/vllm_apis.rst:347
+#: ../../source/internal_api_server/vllm_apis.rst:443
+#: ../../source/internal_api_server/vllm_apis.rst:583
+#: ../../source/internal_api_server/vllm_apis.rst:666
+#: ../../source/internal_api_server/vllm_apis.rst:720
+#: ../../source/internal_api_server/vllm_apis.rst:968
+#: ../../source/internal_api_server/vllm_apis.rst:1008
+msgid "**Method**: ``GET``"
+msgstr "**方法**: ``GET``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:28
+msgid "**Path**: ``/lmc_version``"
+msgstr "**路径**: ``/lmc_version``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:29
+#: ../../source/internal_api_server/vllm_apis.rst:44
+#: ../../source/internal_api_server/vllm_apis.rst:59
+#: ../../source/internal_api_server/vllm_apis.rst:105
+#: ../../source/internal_api_server/vllm_apis.rst:445
+#: ../../source/internal_api_server/vllm_apis.rst:535
+#: ../../source/internal_api_server/vllm_apis.rst:560
+#: ../../source/internal_api_server/vllm_apis.rst:585
+#: ../../source/internal_api_server/vllm_apis.rst:617
+#: ../../source/internal_api_server/vllm_apis.rst:643
+#: ../../source/internal_api_server/vllm_apis.rst:668
+#: ../../source/internal_api_server/vllm_apis.rst:722
+#: ../../source/internal_api_server/vllm_apis.rst:757
+#: ../../source/internal_api_server/vllm_apis.rst:830
+#: ../../source/internal_api_server/vllm_apis.rst:889
+#: ../../source/internal_api_server/vllm_apis.rst:922
+#: ../../source/internal_api_server/vllm_apis.rst:946
+#: ../../source/internal_api_server/vllm_apis.rst:970
+#: ../../source/internal_api_server/vllm_apis.rst:1010
+msgid "**Parameters**: None"
+msgstr "**参数**: 无"
+
+#: ../../source/internal_api_server/vllm_apis.rst:30
+msgid "**Response**: Plain version string."
+msgstr "**响应**\\ ：纯文本版本字符串。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:38
+msgid "``GET /commit_id`` — LMCache Commit ID"
+msgstr "``GET /commit_id`` — LMCache 提交 ID"
+
+#: ../../source/internal_api_server/vllm_apis.rst:40
+msgid "Get the LMCache git commit ID."
+msgstr "获取 LMCache git 提交 ID。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:43
+msgid "**Path**: ``/commit_id``"
+msgstr "**路径**: ``/commit_id``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:45
+msgid "**Response**: Plain commit ID string."
+msgstr "**响应**: 纯文本提交 ID 字符串。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:53
+msgid "``GET /version`` — Full Version Info"
+msgstr "``GET /version`` — 完整版本信息"
+
+#: ../../source/internal_api_server/vllm_apis.rst:55
+msgid "Get full version info (version + commit ID)."
+msgstr "获取完整版本信息（版本 + 提交 ID）。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:58
+msgid "**Path**: ``/version``"
+msgstr "**路径**: ``/version``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:60
+msgid "**Response**: Combined version string."
+msgstr "**响应**: 组合版本字符串。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:68
+msgid "``GET /inference_info`` — Inference Information"
+msgstr "``GET /inference_info`` — 推理信息"
+
+#: ../../source/internal_api_server/vllm_apis.rst:70
+msgid "Get inference information including vLLM config and LMCache details."
+msgstr "获取推理信息，包括 vLLM 配置和 LMCache 详细信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:73
+msgid "**Path**: ``/inference_info``"
+msgstr "**路径**: ``/inference_info``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:74
+#: ../../source/internal_api_server/vllm_apis.rst:131
+#: ../../source/internal_api_server/vllm_apis.rst:212
+#: ../../source/internal_api_server/vllm_apis.rst:241
+#: ../../source/internal_api_server/vllm_apis.rst:276
+#: ../../source/internal_api_server/vllm_apis.rst:316
+#: ../../source/internal_api_server/vllm_apis.rst:349
+#: ../../source/internal_api_server/vllm_apis.rst:406
+#: ../../source/internal_api_server/vllm_apis.rst:781
+#: ../../source/internal_api_server/vllm_apis.rst:1036
+#: ../../source/internal_api_server/vllm_apis.rst:1079
+msgid "**Parameters**:"
+msgstr "**参数**:"
+
+#: ../../source/internal_api_server/vllm_apis.rst:77
+#: ../../source/internal_api_server/vllm_apis.rst:134
+#: ../../source/internal_api_server/vllm_apis.rst:215
+#: ../../source/internal_api_server/vllm_apis.rst:244
+#: ../../source/internal_api_server/vllm_apis.rst:279
+#: ../../source/internal_api_server/vllm_apis.rst:319
+#: ../../source/internal_api_server/vllm_apis.rst:352
+#: ../../source/internal_api_server/vllm_apis.rst:409
+#: ../../source/internal_api_server/vllm_apis.rst:784
+#: ../../source/internal_api_server/vllm_apis.rst:1039
+#: ../../source/internal_api_server/vllm_apis.rst:1082
+msgid "Name"
+msgstr "名称"
+
+#: ../../source/internal_api_server/vllm_apis.rst:77
+#: ../../source/internal_api_server/vllm_apis.rst:134
+#: ../../source/internal_api_server/vllm_apis.rst:215
+#: ../../source/internal_api_server/vllm_apis.rst:244
+#: ../../source/internal_api_server/vllm_apis.rst:279
+#: ../../source/internal_api_server/vllm_apis.rst:319
+#: ../../source/internal_api_server/vllm_apis.rst:352
+#: ../../source/internal_api_server/vllm_apis.rst:409
+#: ../../source/internal_api_server/vllm_apis.rst:480
+#: ../../source/internal_api_server/vllm_apis.rst:784
+#: ../../source/internal_api_server/vllm_apis.rst:1039
+#: ../../source/internal_api_server/vllm_apis.rst:1082
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/internal_api_server/vllm_apis.rst:77
+#: ../../source/internal_api_server/vllm_apis.rst:134
+#: ../../source/internal_api_server/vllm_apis.rst:215
+#: ../../source/internal_api_server/vllm_apis.rst:244
+#: ../../source/internal_api_server/vllm_apis.rst:279
+#: ../../source/internal_api_server/vllm_apis.rst:319
+#: ../../source/internal_api_server/vllm_apis.rst:352
+#: ../../source/internal_api_server/vllm_apis.rst:409
+#: ../../source/internal_api_server/vllm_apis.rst:480
+#: ../../source/internal_api_server/vllm_apis.rst:784
+#: ../../source/internal_api_server/vllm_apis.rst:1039
+#: ../../source/internal_api_server/vllm_apis.rst:1082
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/internal_api_server/vllm_apis.rst:79
+msgid "``format``"
+msgstr "``format``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:79
+#: ../../source/internal_api_server/vllm_apis.rst:136
+#: ../../source/internal_api_server/vllm_apis.rst:217
+#: ../../source/internal_api_server/vllm_apis.rst:281
+#: ../../source/internal_api_server/vllm_apis.rst:321
+#: ../../source/internal_api_server/vllm_apis.rst:354
+#: ../../source/internal_api_server/vllm_apis.rst:411
+#: ../../source/internal_api_server/vllm_apis.rst:482
+#: ../../source/internal_api_server/vllm_apis.rst:1041
+#: ../../source/internal_api_server/vllm_apis.rst:1084
+msgid "str"
+msgstr "字符串"
+
+#: ../../source/internal_api_server/vllm_apis.rst:79
+msgid "(Optional) Reserved for future use"
+msgstr "(可选) 保留以备将来使用"
+
+#: ../../source/internal_api_server/vllm_apis.rst:82
+#: ../../source/internal_api_server/vllm_apis.rst:106
+#: ../../source/internal_api_server/vllm_apis.rst:170
+#: ../../source/internal_api_server/vllm_apis.rst:249
+#: ../../source/internal_api_server/vllm_apis.rst:284
+#: ../../source/internal_api_server/vllm_apis.rst:324
+#: ../../source/internal_api_server/vllm_apis.rst:359
+#: ../../source/internal_api_server/vllm_apis.rst:414
+#: ../../source/internal_api_server/vllm_apis.rst:446
+#: ../../source/internal_api_server/vllm_apis.rst:487
+#: ../../source/internal_api_server/vllm_apis.rst:536
+#: ../../source/internal_api_server/vllm_apis.rst:561
+#: ../../source/internal_api_server/vllm_apis.rst:586
+#: ../../source/internal_api_server/vllm_apis.rst:618
+#: ../../source/internal_api_server/vllm_apis.rst:644
+#: ../../source/internal_api_server/vllm_apis.rst:669
+#: ../../source/internal_api_server/vllm_apis.rst:723
+#: ../../source/internal_api_server/vllm_apis.rst:758
+#: ../../source/internal_api_server/vllm_apis.rst:789
+#: ../../source/internal_api_server/vllm_apis.rst:831
+#: ../../source/internal_api_server/vllm_apis.rst:890
+#: ../../source/internal_api_server/vllm_apis.rst:923
+#: ../../source/internal_api_server/vllm_apis.rst:947
+#: ../../source/internal_api_server/vllm_apis.rst:971
+#: ../../source/internal_api_server/vllm_apis.rst:1011
+#: ../../source/internal_api_server/vllm_apis.rst:1044
+#: ../../source/internal_api_server/vllm_apis.rst:1087
+msgid "**Response**: ``application/json``"
+msgstr "**响应**: ``application/json``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:88
+msgid "**Error Response** (HTTP 500):"
+msgstr "**错误响应** (HTTP 500):"
+
+#: ../../source/internal_api_server/vllm_apis.rst:99
+msgid "``GET /inference_version`` — vLLM Version"
+msgstr "``GET /inference_version`` — vLLM 版本"
+
+#: ../../source/internal_api_server/vllm_apis.rst:101
+msgid "Get the vLLM version information."
+msgstr "获取 vLLM 版本信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:104
+msgid "**Path**: ``/inference_version``"
+msgstr "**路径**: ``/inference_version``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:112
+#: ../../source/internal_api_server/vllm_apis.rst:259
+#: ../../source/internal_api_server/vllm_apis.rst:290
+#: ../../source/internal_api_server/vllm_apis.rst:330
+#: ../../source/internal_api_server/vllm_apis.rst:427
+#: ../../source/internal_api_server/vllm_apis.rst:452
+#: ../../source/internal_api_server/vllm_apis.rst:542
+#: ../../source/internal_api_server/vllm_apis.rst:567
+#: ../../source/internal_api_server/vllm_apis.rst:592
+#: ../../source/internal_api_server/vllm_apis.rst:624
+#: ../../source/internal_api_server/vllm_apis.rst:650
+#: ../../source/internal_api_server/vllm_apis.rst:675
+#: ../../source/internal_api_server/vllm_apis.rst:764
+#: ../../source/internal_api_server/vllm_apis.rst:896
+#: ../../source/internal_api_server/vllm_apis.rst:929
+#: ../../source/internal_api_server/vllm_apis.rst:953
+#: ../../source/internal_api_server/vllm_apis.rst:977
+#: ../../source/internal_api_server/vllm_apis.rst:1017
+#: ../../source/internal_api_server/vllm_apis.rst:1050
+#: ../../source/internal_api_server/vllm_apis.rst:1093
+msgid "**Example Response**:"
+msgstr "**示例响应**:"
+
+#: ../../source/internal_api_server/vllm_apis.rst:122
+msgid "Configuration & Metadata"
+msgstr "配置与元数据"
+
+#: ../../source/internal_api_server/vllm_apis.rst:125
+msgid "``GET /conf`` — Get Configuration"
+msgstr "``GET /conf`` — 获取配置"
+
+#: ../../source/internal_api_server/vllm_apis.rst:127
+msgid "Get current LMCache engine configuration values."
+msgstr "获取当前 LMCache 引擎配置值。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:130
+#: ../../source/internal_api_server/vllm_apis.rst:167
+msgid "**Path**: ``/conf``"
+msgstr "**路径**: ``/conf``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:136
+#: ../../source/internal_api_server/vllm_apis.rst:217
+msgid "``names``"
+msgstr "``names``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:136
+msgid "(Optional) Comma-separated list of config names to filter"
+msgstr "（可选）以逗号分隔的配置名称列表，用于过滤。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:139
+msgid ""
+"**Response**: ``application/json`` — JSON object of configuration key-"
+"value pairs."
+msgstr "**响应**: ``application/json`` — 配置键值对的 JSON 对象。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:151
+msgid "``POST /conf`` — Update Configuration (Experimental)"
+msgstr "``POST /conf`` — 更新配置（实验性）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:153
+msgid "Update one or more configuration values at runtime."
+msgstr "在运行时更新一个或多个配置值。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:157
+msgid ""
+"This feature is currently **experimental**. All configuration keys are "
+"mutable at runtime by default unless explicitly marked as ``\"mutable\": "
+"False`` in ``_CONFIG_DEFINITIONS``. The default will be changed to "
+"**immutable** once the feature is stabilized."
+msgstr ""
+"此功能目前是 **实验性** 的。除非在 ``_CONFIG_DEFINITIONS`` 中明确标记为 ``\"mutable\": "
+"False``\\ ，否则所有配置键在运行时默认是可变的。一旦该功能稳定，默认值将更改为 **不可变**\\ 。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:162
+msgid ""
+"Updating a configuration only modifies the value in the "
+"``LMCacheEngineConfig`` object. If a component has already cached the "
+"value elsewhere, the change will **not** take effect for that component."
+msgstr ""
+"更新配置仅会修改 ``LMCacheEngineConfig`` 对象中的值。如果某个组件已经在其他地方缓存了该值，则该更改对该组件将\\ "
+"**无效**\\ 。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:166
+#: ../../source/internal_api_server/vllm_apis.rst:274
+#: ../../source/internal_api_server/vllm_apis.rst:314
+#: ../../source/internal_api_server/vllm_apis.rst:404
+#: ../../source/internal_api_server/vllm_apis.rst:474
+#: ../../source/internal_api_server/vllm_apis.rst:755
+#: ../../source/internal_api_server/vllm_apis.rst:779
+#: ../../source/internal_api_server/vllm_apis.rst:828
+#: ../../source/internal_api_server/vllm_apis.rst:887
+#: ../../source/internal_api_server/vllm_apis.rst:920
+#: ../../source/internal_api_server/vllm_apis.rst:944
+msgid "**Method**: ``POST``"
+msgstr "**方法**: ``POST``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:168
+#: ../../source/internal_api_server/vllm_apis.rst:476
+msgid "**Content-Type**: ``application/json``"
+msgstr "**Content-Type**: ``application/json``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:169
+msgid "**Request Body**: JSON object with config name-value pairs."
+msgstr "**请求体**: JSON 对象，包含配置的名称-值对。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:178
+#: ../../source/internal_api_server/vllm_apis.rst:496
+msgid "**Example Response** (HTTP 200):"
+msgstr "**示例响应** (HTTP 200):"
+
+#: ../../source/internal_api_server/vllm_apis.rst:189
+msgid "**Example Response** (partial failure, HTTP 400):"
+msgstr "**示例响应**\\ （部分失败，HTTP 400）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:198
+msgid "**Error Cases**:"
+msgstr "**错误案例**:"
+
+#: ../../source/internal_api_server/vllm_apis.rst:200
+msgid "Unknown config key → ``\"Unknown config\"``"
+msgstr "未知的配置键 → ``\"Unknown config\"``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:201
+msgid "Immutable config key → ``\"Config is not mutable at runtime\"``"
+msgstr "不可变配置键 → ``\"配置在运行时不可变\"``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:202
+msgid "Invalid JSON body → HTTP 400"
+msgstr "无效的 JSON 主体 → HTTP 400"
+
+#: ../../source/internal_api_server/vllm_apis.rst:206
+msgid "``GET /meta`` — Engine Metadata"
+msgstr "``GET /meta`` — 引擎元数据"
+
+#: ../../source/internal_api_server/vllm_apis.rst:208
+msgid ""
+"Get metadata of the LMCache engine (e.g., worker_id, model_name, "
+"kv_shape)."
+msgstr "获取 LMCache 引擎的元数据（例如，worker_id、model_name、kv_shape）。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:211
+msgid "**Path**: ``/meta``"
+msgstr "**路径**: ``/meta``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:217
+msgid "(Optional) Comma-separated list of attribute names to filter"
+msgstr "（可选）以逗号分隔的属性名称列表，用于过滤"
+
+#: ../../source/internal_api_server/vllm_apis.rst:220
+msgid "**Response**: ``application/json`` — JSON object of metadata attributes."
+msgstr "**响应**: ``application/json`` — 元数据属性的 JSON 对象。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:232
+msgid "Cache Operations"
+msgstr "缓存操作"
+
+#: ../../source/internal_api_server/vllm_apis.rst:235
+msgid "``DELETE /cache/clear`` — Clear Cache"
+msgstr "``DELETE /cache/clear`` — 清除缓存"
+
+#: ../../source/internal_api_server/vllm_apis.rst:237
+msgid "Clear cached KV data from the LMCache engine."
+msgstr "从 LMCache 引擎中清除缓存的 KV 数据。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:239
+msgid "**Method**: ``DELETE``"
+msgstr "**方法**: ``DELETE``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:240
+msgid "**Path**: ``/cache/clear``"
+msgstr "**路径**: ``/cache/clear``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:246
+msgid "``locations``"
+msgstr "``locations``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:246
+msgid "list[str]"
+msgstr "列表[str]"
+
+#: ../../source/internal_api_server/vllm_apis.rst:246
+msgid ""
+"(Optional) Storage backends to clear (e.g. ``LocalCPUBackend``, "
+"``LocalDiskBackend``). If not specified, clears all."
+msgstr ""
+"(可选) 要清除的存储后端（例如 ``LocalCPUBackend``\\ 、\\ ``LocalDiskBackend``\\ "
+"）。如果未指定，则清除所有。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:270
+msgid "``POST /cache/store`` — Store KV Cache"
+msgstr "``POST /cache/store`` — 存储 KV Cache"
+
+#: ../../source/internal_api_server/vllm_apis.rst:272
+msgid "Store KV cache data into the LMCache engine using mock tokens."
+msgstr "使用模拟令牌将 KV Cache 数据存储到 LMCache 引擎中。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:275
+msgid "**Path**: ``/cache/store``"
+msgstr "**路径**: ``/cache/store``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:281
+#: ../../source/internal_api_server/vllm_apis.rst:321
+msgid "``tokens_mock``"
+msgstr "``tokens_mock``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:281
+msgid ""
+"Two comma-separated numbers: ``\"start,end\"`` (e.g. ``\"0,100\"`` "
+"generates tokens [0..99])"
+msgstr "两个用逗号分隔的数字：\\ ``\"start,end\"``\\ （例如，\\ ``\"0,100\"`` 生成令牌 [0..99]）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:299
+msgid "**Error Response** (missing params, HTTP 400):"
+msgstr "**错误响应**\\ （缺少参数，HTTP 400）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:310
+msgid "``POST /cache/retrieve`` — Retrieve KV Cache"
+msgstr "``POST /cache/retrieve`` — 检索 KV Cache"
+
+#: ../../source/internal_api_server/vllm_apis.rst:312
+msgid "Retrieve KV cache data from the LMCache engine using mock tokens."
+msgstr "使用模拟令牌从 LMCache 引擎检索 KV Cache 数据。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:315
+msgid "**Path**: ``/cache/retrieve``"
+msgstr "**路径**: ``/cache/retrieve``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:321
+msgid "Two comma-separated numbers: ``\"start,end\"`` (e.g. ``\"0,100\"``)"
+msgstr "两个用逗号分隔的数字：\\ ``\"start,end\"``\\ （例如 ``\"0,100\"``\\ ）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:342
+msgid "``GET /cache/kvcache/check`` — KVCache Checksum"
+msgstr "``GET /cache/kvcache/check`` — KVCache 校验和"
+
+#: ../../source/internal_api_server/vllm_apis.rst:344
+msgid ""
+"Compute MD5 checksums for kvcaches at specified slot_mapping positions. "
+"Used for verifying that stored and retrieved kvcaches are identical."
+msgstr "计算指定 slot_mapping 位置的 KVCache 的 MD5 校验和。用于验证存储和检索的 KVCache 是否相同。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:348
+msgid "**Path**: ``/cache/kvcache/check``"
+msgstr "**路径**: ``/cache/kvcache/check``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:354
+msgid "``slot_mapping``"
+msgstr "``slot_mapping``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:354
+msgid ""
+"Slot indices, comma-separated. Supports ranges: ``\"0,1,2,3\"`` or "
+"``\"1,2,3,[9,12],17,19\"``"
+msgstr "槽索引，以逗号分隔。支持范围：\\ ``\"0,1,2,3\"`` 或 ``\"1,2,3,[9,12],17,19\"``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:355
+msgid "``chunk_size``"
+msgstr "``chunk_size``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:355
+#: ../../source/internal_api_server/vllm_apis.rst:483
+#: ../../source/internal_api_server/vllm_apis.rst:484
+msgid "int"
+msgstr "整数"
+
+#: ../../source/internal_api_server/vllm_apis.rst:355
+msgid "Chunk size for computing per-chunk checksums (required)"
+msgstr "每块计算每块校验和的块大小（必需）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:356
+msgid "``layerwise``"
+msgstr "``layerwise``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:356
+#: ../../source/internal_api_server/vllm_apis.rst:786
+msgid "bool"
+msgstr "布尔值"
+
+#: ../../source/internal_api_server/vllm_apis.rst:356
+msgid "If ``true``, output per-layer checksums per chunk (default: ``false``)"
+msgstr "如果 ``true``\\ ，则每个块输出每层的校验和（默认值：\\ ``false``\\ ）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:369
+msgid "**Example Response** (``layerwise=false``):"
+msgstr "**示例响应** (``layerwise=false``):"
+
+#: ../../source/internal_api_server/vllm_apis.rst:382
+msgid "**Example Response** (``layerwise=true``):"
+msgstr "**示例响应** (``layerwise=true``):"
+
+#: ../../source/internal_api_server/vllm_apis.rst:400
+msgid "``POST /cache/kvcache/record_slot`` — Toggle Slot Logging"
+msgstr "``POST /cache/kvcache/record_slot`` — 切换槽记录"
+
+#: ../../source/internal_api_server/vllm_apis.rst:402
+msgid ""
+"Enable or disable KVCache slot_mapping logging during store/retrieve "
+"operations."
+msgstr "在存储/检索操作期间启用或禁用 KVCache slot_mapping 日志记录。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:405
+msgid "**Path**: ``/cache/kvcache/record_slot``"
+msgstr "**路径**: ``/cache/kvcache/record_slot``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:411
+msgid "``enabled``"
+msgstr "``enabled``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:411
+msgid ""
+"``\"true\"`` to enable, ``\"false\"`` to disable. Omit to query current "
+"status."
+msgstr "``\"true\"`` 表示启用，\\ ``\"false\"`` 表示禁用。省略此项以查询当前状态。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:438
+msgid "``GET /cache/kvcache/info`` — KVCache Information"
+msgstr "``GET /cache/kvcache/info`` — KVCache 信息"
+
+#: ../../source/internal_api_server/vllm_apis.rst:440
+msgid ""
+"Get information about the current kvcaches structure including layer "
+"names, shapes, and device info."
+msgstr "获取当前 KVCache 结构的信息，包括层名称、形状和设备信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:444
+msgid "**Path**: ``/cache/kvcache/info``"
+msgstr "**路径**: ``/cache/kvcache/info``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:470
+msgid "``POST /cache/load-fs-chunks`` — Load FS Chunks"
+msgstr "``POST /cache/load-fs-chunks`` — 加载 FS 块"
+
+#: ../../source/internal_api_server/vllm_apis.rst:472
+msgid ""
+"Load chunk files from FSConnector storage into LocalCPUBackend's hot "
+"cache."
+msgstr "从 FSConnector 存储加载块文件到 LocalCPUBackend 的热缓存中。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:475
+msgid "**Path**: ``/cache/load-fs-chunks``"
+msgstr "**路径**: ``/cache/load-fs-chunks``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:477
+msgid "**Request Body**:"
+msgstr "**请求体**\\ ："
+
+#: ../../source/internal_api_server/vllm_apis.rst:480
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/internal_api_server/vllm_apis.rst:482
+msgid "``config_path``"
+msgstr "``config_path``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:482
+msgid "Path to LMCache engine configuration YAML file (required)"
+msgstr "LMCache 引擎配置 YAML 文件的路径（必填）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:483
+msgid "``max_chunks``"
+msgstr "``max_chunks``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:483
+msgid "(Optional) Maximum number of chunks to load"
+msgstr "(可选) 最大加载块数"
+
+#: ../../source/internal_api_server/vllm_apis.rst:484
+msgid "``max_failed_keys``"
+msgstr "``max_failed_keys``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:484
+msgid "Maximum failed keys to report (default: 10)"
+msgstr "报告的最大失败键数（默认：10）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:488
+msgid "**Tags**: ``cache-management``"
+msgstr "**标签**: ``cache-management``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:508
+msgid "**Error Response** (invalid config, HTTP 400):"
+msgstr "**错误响应**\\ （无效配置，HTTP 400）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:520
+msgid "Freeze Mode"
+msgstr "冻结模式"
+
+#: ../../source/internal_api_server/vllm_apis.rst:523
+msgid "``PUT /freeze/enable`` — Enable Freeze Mode"
+msgstr "``PUT /freeze/enable`` — 启用冻结模式"
+
+#: ../../source/internal_api_server/vllm_apis.rst:525
+msgid "Enable freeze mode for the LMCache engine. When enabled:"
+msgstr "为 LMCache 引擎启用冻结模式。启用后："
+
+#: ../../source/internal_api_server/vllm_apis.rst:527
+msgid "All store operations will be skipped (no new data stored)"
+msgstr "所有存储操作将被跳过（不存储新数据）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:528
+msgid "Only ``local_cpu`` backend will be used for retrieval"
+msgstr "仅使用 ``local_cpu`` 后端进行检索"
+
+#: ../../source/internal_api_server/vllm_apis.rst:529
+msgid "No admit/evict messages will be generated"
+msgstr "不会生成 admit/evict 消息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:531
+msgid "This protects the local_cpu hot cache from changes."
+msgstr "这可以保护本地 CPU 热缓存不受更改。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:533
+#: ../../source/internal_api_server/vllm_apis.rst:558
+#: ../../source/internal_api_server/vllm_apis.rst:615
+#: ../../source/internal_api_server/vllm_apis.rst:641
+#: ../../source/internal_api_server/vllm_apis.rst:1034
+#: ../../source/internal_api_server/vllm_apis.rst:1077
+msgid "**Method**: ``PUT``"
+msgstr "**方法**: ``PUT``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:534
+msgid "**Path**: ``/freeze/enable``"
+msgstr "**路径**: ``/freeze/enable``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:554
+msgid "``PUT /freeze/disable`` — Disable Freeze Mode"
+msgstr "``PUT /freeze/disable`` — 禁用冻结模式"
+
+#: ../../source/internal_api_server/vllm_apis.rst:556
+msgid "Disable freeze mode. Store operations will proceed normally."
+msgstr "禁用冻结模式。存储操作将正常进行。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:559
+msgid "**Path**: ``/freeze/disable``"
+msgstr "**路径**: ``/freeze/disable``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:579
+msgid "``GET /freeze/status`` — Freeze Status"
+msgstr "``GET /freeze/status`` — 冻结状态"
+
+#: ../../source/internal_api_server/vllm_apis.rst:581
+msgid "Get the current freeze mode status."
+msgstr "获取当前冻结模式状态。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:584
+msgid "**Path**: ``/freeze/status``"
+msgstr "**路径**: ``/freeze/status``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:604
+msgid "Hot Cache"
+msgstr "热缓存"
+
+#: ../../source/internal_api_server/vllm_apis.rst:606
+msgid ""
+"These endpoints control the hot cache feature of LocalCPUBackend. When "
+"hot cache is enabled, frequently accessed KV cache data will be kept in "
+"CPU memory for faster retrieval."
+msgstr ""
+"这些端点控制 LocalCPUBackend 的热缓存功能。当启用热缓存时，频繁访问的 KV Cache 数据将保留在 CPU "
+"内存中，以便更快地检索。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:611
+msgid "``PUT /hot_cache/enable`` — Enable Hot Cache"
+msgstr "``PUT /hot_cache/enable`` — 启用热缓存"
+
+#: ../../source/internal_api_server/vllm_apis.rst:613
+msgid "Enable hot cache for the LocalCPUBackend."
+msgstr "为 LocalCPUBackend 启用热缓存。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:616
+msgid "**Path**: ``/hot_cache/enable``"
+msgstr "**路径**: ``/hot_cache/enable``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:636
+msgid "``PUT /hot_cache/disable`` — Disable Hot Cache"
+msgstr "``PUT /hot_cache/disable`` — 禁用热缓存"
+
+#: ../../source/internal_api_server/vllm_apis.rst:638
+msgid ""
+"Disable hot cache for the LocalCPUBackend. Existing hot cache entries "
+"will be cleared and no new data will be written."
+msgstr "禁用 LocalCPUBackend 的热缓存。现有的热缓存条目将被清除，且不会写入新数据。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:642
+msgid "**Path**: ``/hot_cache/disable``"
+msgstr "**路径**: ``/hot_cache/disable``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:662
+msgid "``GET /hot_cache/status`` — Hot Cache Status"
+msgstr "``GET /hot_cache/status`` — 热缓存状态"
+
+#: ../../source/internal_api_server/vllm_apis.rst:664
+msgid "Get the current hot cache status of LocalCPUBackend."
+msgstr "获取 LocalCPUBackend 的当前热缓存状态。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:667
+msgid "**Path**: ``/hot_cache/status``"
+msgstr "**路径**: ``/hot_cache/status``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:687
+msgid "Chunk Statistics"
+msgstr "块统计"
+
+#: ../../source/internal_api_server/vllm_apis.rst:689
+msgid ""
+"These endpoints manage chunk-level statistics collection via "
+"``ChunkStatisticsLookupClient``. They are only available when the lookup "
+"client supports statistics."
+msgstr "这些端点通过 ``ChunkStatisticsLookupClient`` 管理块级统计信息的收集。只有在查找客户端支持统计信息时，它们才可用。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:695
+msgid "Lookup Client/Server Management"
+msgstr "查找客户端/服务器管理"
+
+#: ../../source/internal_api_server/vllm_apis.rst:697
+msgid ""
+"These endpoints allow runtime management of the lookup client and server."
+" They are useful for dynamically reconfiguring the lookup mechanism "
+"without restarting the service."
+msgstr "这些端点允许对查找客户端和服务器进行运行时管理。它们对于在不重启服务的情况下动态重新配置查找机制非常有用。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:703
+msgid "**Configuration Update Required First**"
+msgstr "**首先需要更新配置**"
+
+#: ../../source/internal_api_server/vllm_apis.rst:705
+msgid ""
+"Before calling ``/lookup/create`` or ``/lookup/recreate``, you **MUST** "
+"update the configuration via the ``/conf`` API first. The new lookup "
+"client/server will be created using ``LookupClientFactory``."
+msgstr ""
+"在调用 ``/lookup/create`` 或 ``/lookup/recreate`` 之前，您 **必须** 首先通过 ``/conf`` "
+"API 更新配置。新的查找客户端/服务器将使用 ``LookupClientFactory`` 创建。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:709
+msgid ""
+"For some configurations (e.g., switching "
+"``enable_scheduler_bypass_lookup``), you only need to update the "
+"**scheduler's** configuration and recreate its lookup client. The workers"
+" don't need changes in this case."
+msgstr ""
+"对于某些配置（例如，切换 ``enable_scheduler_bypass_lookup``\\ ），您只需更新 **调度器** "
+"的配置并重新创建其查找客户端。在这种情况下，工作节点无需更改。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:715
+msgid "``GET /lookup/info`` — Lookup Client/Server Information"
+msgstr "``GET /lookup/info`` — 查找客户端/服务器信息"
+
+#: ../../source/internal_api_server/vllm_apis.rst:717
+msgid ""
+"Get information about the current lookup client and server status. Shows "
+"wrapper chain if applicable (e.g., "
+"``HitLimitLookupClient(LMCacheLookupClient)``)."
+msgstr ""
+"获取当前查找客户端和服务器状态的信息。如果适用，显示包装链（例如，\\ "
+"``HitLimitLookupClient(LMCacheLookupClient)``\\ ）。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:721
+msgid "**Path**: ``/lookup/info``"
+msgstr "**路径**: ``/lookup/info``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:729
+#: ../../source/internal_api_server/vllm_apis.rst:853
+msgid "**Example Response** (scheduler):"
+msgstr "**示例响应**\\ （调度器）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:739
+#: ../../source/internal_api_server/vllm_apis.rst:863
+msgid "**Example Response** (worker):"
+msgstr "**示例响应** (工作者):"
+
+#: ../../source/internal_api_server/vllm_apis.rst:751
+msgid "``POST /lookup/close`` — Close Lookup Client/Server"
+msgstr "``POST /lookup/close`` — 关闭查找客户端/服务器"
+
+#: ../../source/internal_api_server/vllm_apis.rst:753
+msgid "Close the current lookup client (scheduler) or server (worker)."
+msgstr "关闭当前的查找客户端（调度器）或服务器（工作节点）。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:756
+msgid "**Path**: ``/lookup/close``"
+msgstr "**路径**: ``/lookup/close``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:775
+msgid "``POST /lookup/create`` — Create Lookup Client/Server"
+msgstr "``POST /lookup/create`` — 创建查找客户端/服务器"
+
+#: ../../source/internal_api_server/vllm_apis.rst:777
+msgid ""
+"Create a new lookup client (scheduler) or server (worker) using current "
+"config."
+msgstr "使用当前配置创建一个新的查找客户端（调度器）或服务器（工作进程）。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:780
+msgid "**Path**: ``/lookup/create``"
+msgstr "**路径**: ``/lookup/create``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:786
+msgid "``dryrun``"
+msgstr "``dryrun``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:786
+msgid "If ``true``, only show what would be created"
+msgstr "如果为 ``true``\\ ，则仅显示将要创建的内容。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:799
+msgid "**Example Response** (dryrun):"
+msgstr "**示例响应**\\ （干运行）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:809
+msgid "**Example Response** (actual create):"
+msgstr "**示例响应** (实际创建):"
+
+#: ../../source/internal_api_server/vllm_apis.rst:820
+msgid "``POST /lookup/recreate`` — Recreate Lookup Client/Server"
+msgstr "``POST /lookup/recreate`` — 重新创建查找客户端/服务器"
+
+#: ../../source/internal_api_server/vllm_apis.rst:822
+msgid ""
+"Recreate the lookup client or server (equivalent to close + create). The "
+"endpoint automatically determines which component based on role:"
+msgstr "重新创建查找客户端或服务器（相当于关闭 + 创建）。该端点会根据角色自动确定哪个组件："
+
+#: ../../source/internal_api_server/vllm_apis.rst:825
+msgid "**scheduler** role: recreates lookup client"
+msgstr "**scheduler** 角色：重新创建查找客户端"
+
+#: ../../source/internal_api_server/vllm_apis.rst:826
+msgid "**worker** role: recreates lookup server"
+msgstr "**worker** 角色：重新创建查找服务器"
+
+#: ../../source/internal_api_server/vllm_apis.rst:829
+msgid "**Path**: ``/lookup/recreate``"
+msgstr "**路径**: ``/lookup/recreate``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:833
+msgid "**Usage Flow**:"
+msgstr "**使用流程**:"
+
+#: ../../source/internal_api_server/vllm_apis.rst:875
+msgid "**Client-only Changes**"
+msgstr "**仅客户端更改**"
+
+#: ../../source/internal_api_server/vllm_apis.rst:877
+msgid ""
+"For some configuration changes (e.g., switching "
+"``enable_scheduler_bypass_lookup``), you only need to update the "
+"scheduler's configuration and recreate its lookup client. Worker-side "
+"lookup servers don't need to be recreated in this case."
+msgstr ""
+"对于某些配置更改（例如，切换 ``enable_scheduler_bypass_lookup``\\ "
+"），您只需更新调度器的配置并重新创建其查找客户端。在这种情况下，工作节点的查找服务器无需重新创建。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:883
+msgid "``POST /chunk_statistics/start`` — Start Statistics"
+msgstr "``POST /chunk_statistics/start`` — 开始统计"
+
+#: ../../source/internal_api_server/vllm_apis.rst:885
+msgid "Start collecting chunk statistics."
+msgstr "开始收集块统计信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:888
+msgid "**Path**: ``/chunk_statistics/start``"
+msgstr "**路径**: ``/chunk_statistics/start``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:905
+msgid "**Error Response** (not supported, HTTP 400):"
+msgstr "**错误响应**\\ （不支持，HTTP 400）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:916
+msgid "``POST /chunk_statistics/stop`` — Stop Statistics"
+msgstr "``POST /chunk_statistics/stop`` — 停止统计"
+
+#: ../../source/internal_api_server/vllm_apis.rst:918
+msgid "Stop collecting chunk statistics."
+msgstr "停止收集块统计信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:921
+msgid "**Path**: ``/chunk_statistics/stop``"
+msgstr "**路径**: ``/chunk_statistics/stop``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:940
+msgid "``POST /chunk_statistics/reset`` — Reset Statistics"
+msgstr "``POST /chunk_statistics/reset`` — 重置统计信息"
+
+#: ../../source/internal_api_server/vllm_apis.rst:942
+msgid "Reset all collected chunk statistics."
+msgstr "重置所有收集的块统计信息。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:945
+msgid "**Path**: ``/chunk_statistics/reset``"
+msgstr "**路径**: ``/chunk_statistics/reset``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:964
+msgid "``GET /chunk_statistics/status`` — Statistics Status"
+msgstr "``GET /chunk_statistics/status`` — 统计状态"
+
+#: ../../source/internal_api_server/vllm_apis.rst:966
+msgid "Get current chunk statistics and auto-exit configuration."
+msgstr "获取当前块统计信息和自动退出配置。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:969
+msgid "**Path**: ``/chunk_statistics/status``"
+msgstr "**路径**: ``/chunk_statistics/status``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:995
+msgid "Bypass Mode"
+msgstr "旁路模式"
+
+#: ../../source/internal_api_server/vllm_apis.rst:997
+msgid ""
+"Bypass mode allows dynamically skipping specific storage backends at "
+"runtime. Bypassed backends are excluded from ``contains``/``put``/``get``"
+" operations. This is useful for fault injection testing, isolating a "
+"problematic backend, or debugging without restarting the engine."
+msgstr ""
+"绕过模式允许在运行时动态跳过特定的存储后端。被绕过的后端将被排除在 ``contains``/``put``/``get`` "
+"操作之外。这对于故障注入测试、隔离有问题的后端或在不重启引擎的情况下进行调试非常有用。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1004
+msgid "``GET /bypass/list`` — List Bypassed Backends"
+msgstr "``GET /bypass/list`` — 列出被绕过的后端"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1006
+msgid "List all currently bypassed backends and all available backend names."
+msgstr "列出所有当前被绕过的后端和所有可用的后端名称。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1009
+msgid "**Path**: ``/bypass/list``"
+msgstr "**路径**: ``/bypass/list``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1029
+msgid "``PUT /bypass/add`` — Add a Backend to Bypass List"
+msgstr "``PUT /bypass/add`` — 将后端添加到绕过列表"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1031
+msgid ""
+"Add a backend to the bypass list. The bypassed backend will be excluded "
+"from ``contains``/``put``/``get`` operations."
+msgstr "将后端添加到绕过列表中。被绕过的后端将被排除在 ``contains``/``put``/``get`` 操作之外。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1035
+msgid "**Path**: ``/bypass/add``"
+msgstr "**路径**: ``/bypass/add``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1041
+#: ../../source/internal_api_server/vllm_apis.rst:1084
+msgid "``backend_name``"
+msgstr "``backend_name``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1041
+msgid "Name of the backend to bypass (required)"
+msgstr "要绕过的后端名称（必填）"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1062
+#: ../../source/internal_api_server/vllm_apis.rst:1105
+msgid "**Error Response** (unknown backend, HTTP 400):"
+msgstr "**错误响应**\\ （未知后端，HTTP 400）："
+
+#: ../../source/internal_api_server/vllm_apis.rst:1073
+msgid "``PUT /bypass/remove`` — Remove a Backend from Bypass List"
+msgstr "``PUT /bypass/remove`` — 从旁路列表中移除后端"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1075
+msgid "Remove a backend from the bypass list, restoring it to normal operation."
+msgstr "从旁路列表中移除后端，恢复其正常操作。"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1078
+msgid "**Path**: ``/bypass/remove``"
+msgstr "**路径**: ``/bypass/remove``"
+
+#: ../../source/internal_api_server/vllm_apis.rst:1084
+msgid "Name of the backend to restore (required)"
+msgstr "恢复的后端名称（必填）"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/async_loading.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/async_loading.po
new file mode 100644
index 0000000..cfd0bd6
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/async_loading.po
@@ -0,0 +1,232 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/async_loading.rst:2
+msgid "Async Loading"
+msgstr "异步加载"
+
+#: ../../source/kv_cache/async_loading.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache/async_loading.rst:11
+msgid "Table of Contents"
+msgstr "目录"
+
+#: ../../source/kv_cache/async_loading.rst:14
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/async_loading.rst:16
+msgid ""
+"This document explains the principle, benefits, differences from vLLM PR "
+"`19330 <https://github.com/vllm-project/vllm/pull/19330>`_, and "
+"limitations of the LMCache ``async_loading`` feature. It focuses on "
+"LMCache v1 integration with vLLM and the internal storage pipeline."
+msgstr ""
+"本文解释了 LMCache ``async_loading`` 功能的原理、优点、与 vLLM PR `19330 "
+"<https://github.com/vllm-project/vllm/pull/19330>`_ 的区别以及局限性。它重点介绍了 "
+"LMCache v1 与 vLLM 的集成以及内部存储管道。"
+
+#: ../../source/kv_cache/async_loading.rst:19
+msgid "Key change of components in this feature include:"
+msgstr "此功能中组件的主要变化包括："
+
+#: ../../source/kv_cache/async_loading.rst:21
+msgid "LMCache async lookup client/server (ZMQ-based)"
+msgstr "LMCache 异步查找客户端/服务器（基于 ZMQ）"
+
+#: ../../source/kv_cache/async_loading.rst:22
+msgid "Storage manager orchestrating backends and concurrency"
+msgstr "存储管理器协调后端和并发性"
+
+#: ../../source/kv_cache/async_loading.rst:23
+msgid "Cache engine async API entrypoints"
+msgstr "缓存引擎异步 API 入口点"
+
+#: ../../source/kv_cache/async_loading.rst:24
+msgid "vLLM adapter integration points"
+msgstr "vLLM 适配器集成点"
+
+#: ../../source/kv_cache/async_loading.rst:27
+msgid "Principle and Theory"
+msgstr "原理与理论"
+
+#: ../../source/kv_cache/async_loading.rst:29
+msgid ""
+"At a high level, ``async_loading`` decouples scheduler-side lookup from "
+"worker-side prefetch/retrieval, allowing overlap between I/O and "
+"computation while preserving prefix-based correctness."
+msgstr ""
+"从高层次来看，\\ ``async_loading`` 将调度器端的查找与工作端的预取/检索解耦，允许 I/O "
+"和计算之间的重叠，同时保持基于前缀的正确性。"
+
+#: ../../source/kv_cache/async_loading.rst:31
+msgid "The scheduler sends lookup requests with token chunk hashes and offsets."
+msgstr "调度器发送带有令牌块哈希和偏移量的查找请求。"
+
+#: ../../source/kv_cache/async_loading.rst:32
+msgid ""
+"Worker-side servers perform tiered ``batched_async_contains`` over "
+"available backends and eagerly launch non-blocking batched get operations"
+" for hit prefixes."
+msgstr "工作端服务器在可用后端上执行分层的 ``batched_async_contains``\\ ，并积极启动非阻塞的批量获取操作以处理命中前缀。"
+
+#: ../../source/kv_cache/async_loading.rst:33
+msgid ""
+"Completion is tracked via an ``EventManager`` to safely deliver loaded "
+"memory objects back to the requesting path."
+msgstr "完成情况通过 ``EventManager`` 进行跟踪，以安全地将加载的内存对象返回给请求路径。"
+
+#: ../../source/kv_cache/async_loading.rst:34
+msgid ""
+"A weighted semaphore with an ``AsyncSerializer`` prevents allocator "
+"deadlocks by shaping concurrency according to chunk budget."
+msgstr "带权信号量与 ``AsyncSerializer`` 结合使用，通过根据块预算调整并发性来防止分配器死锁。"
+
+#: ../../source/kv_cache/async_loading.rst:36
+msgid "The following Mermaid sequence diagram illustrates the end-to-end flow:"
+msgstr "以下的 Mermaid 序列图展示了端到端的流程："
+
+#: ../../source/kv_cache/async_loading.rst:68
+msgid "Architecture (Worker Side)"
+msgstr "架构（工作端）"
+
+#: ../../source/kv_cache/async_loading.rst:101
+msgid "Benefits"
+msgstr "好处"
+
+#: ../../source/kv_cache/async_loading.rst:103
+msgid "Performance overlap"
+msgstr "性能重叠"
+
+#: ../../source/kv_cache/async_loading.rst:104
+msgid ""
+"**I/O–Compute Overlap**: Decoupling lookup/prefetch from loading enables "
+"fetching KV chunks while vLLM continues scheduling/computation."
+msgstr "**I/O–计算重叠**\\ ：将查找/预取与加载解耦，使得在 vLLM 继续调度/计算的同时可以获取 KV 块。"
+
+#: ../../source/kv_cache/async_loading.rst:105
+msgid "Robustness and error handling"
+msgstr "鲁棒性和错误处理"
+
+#: ../../source/kv_cache/async_loading.rst:106
+msgid ""
+"**Event-driven Synchronization**: ``EventManager`` ensures safe hand-off "
+"of futures and avoids race conditions between threads and the async loop."
+msgstr "**事件驱动同步**\\ ：\\ ``EventManager`` 确保未来对象的安全交接，并避免线程与异步循环之间的竞争条件。"
+
+#: ../../source/kv_cache/async_loading.rst:107
+msgid ""
+"**Backpressure & Deadlock Avoidance**: ``AsyncSerializer`` with a "
+"weighted semaphore caps concurrent chunk retrievals based on allocator "
+"budget, preventing starvation or allocator lockups."
+msgstr "**背压与死锁避免**\\ ：\\ ``AsyncSerializer`` 使用加权信号量限制并发块检索，基于分配器预算，防止饥饿或分配器锁定。"
+
+#: ../../source/kv_cache/async_loading.rst:108
+msgid ""
+"**Graceful Miss Path**: Immediate response with ``None`` hit tokens when "
+"nothing is retrievable; worker returns quickly without stalling the "
+"scheduler."
+msgstr "**优雅未命中路径**\\ ：当无法检索到任何内容时，立即响应 ``None`` 命中令牌；工作线程快速返回，不会阻塞调度器。"
+
+#: ../../source/kv_cache/async_loading.rst:111
+msgid "Comparison with vLLM Load Failure Recovery feature"
+msgstr "与 vLLM 加载失败恢复功能的比较"
+
+#: ../../source/kv_cache/async_loading.rst:113
+msgid ""
+"The `VLLM_PR_19330 <https://github.com/vllm-project/vllm/pull/19330>`_ "
+"introduces a fault recovery mechanism for vLLM's KV connector "
+"infrastructure that enables graceful handling of KV cache load failures "
+"by automatically detecting failed block loads and rescheduling only "
+"affected requests for recomputation from a valid prefix. By contrast, "
+"LMCache’s ``async_loading`` is an externalized caching layer with its own"
+" client/server, storage backends, and concurrency control."
+msgstr ""
+"`VLLM_PR_19330 <https://github.com/vllm-project/vllm/pull/19330>`_ "
+"引入了一个故障恢复机制，用于 vLLM 的 KV 连接器基础设施，能够优雅地处理 KV "
+"缓存加载失败，通过自动检测失败的块加载并仅重新调度受影响的请求，从有效前缀中进行重计算。相比之下，LMCache 的 "
+"``async_loading`` 是一个外部缓存层，具有自己的客户端/服务器、存储后端和并发控制。"
+
+#: ../../source/kv_cache/async_loading.rst:117
+msgid "Limitations"
+msgstr "限制"
+
+#: ../../source/kv_cache/async_loading.rst:119
+msgid ""
+"Only works with vllm merged `VLLM_PR_23620 <https://github.com/vllm-"
+"project/vllm/pull/23620>`_"
+msgstr ""
+"仅适用于合并了 `VLLM_PR_23620 <https://github.com/vllm-"
+"project/vllm/pull/23620>`_ 的 vllm"
+
+#: ../../source/kv_cache/async_loading.rst:120
+msgid ""
+"Backend support constraint: This feature currently requires backends that"
+" implement ``batched_async_contains``; limited to a few backends, e.g.:"
+msgstr "后端支持限制：此功能当前需要实现 ``batched_async_contains`` 的后端；仅限于少数后端，例如："
+
+#: ../../source/kv_cache/async_loading.rst:121
+msgid "``LocalCpuBackend``"
+msgstr "``LocalCpuBackend``"
+
+#: ../../source/kv_cache/async_loading.rst:122
+msgid "``LocalDiskBackend``"
+msgstr "``LocalDiskBackend``"
+
+#: ../../source/kv_cache/async_loading.rst:123
+msgid "``S3Connector``"
+msgstr "``S3Connector``"
+
+#: ../../source/kv_cache/async_loading.rst:124
+msgid "``FSConnector``"
+msgstr "``FSConnector``"
+
+#: ../../source/kv_cache/async_loading.rst:125
+msgid "``RedisConnector/RedisClusterConnector``"
+msgstr "``RedisConnector/RedisClusterConnector``"
+
+#: ../../source/kv_cache/async_loading.rst:128
+msgid "Future Work"
+msgstr "未来工作"
+
+#: ../../source/kv_cache/async_loading.rst:130
+msgid ""
+"Introduce a default ``batched_async_contains`` implementation, so all "
+"backends can support ``async_loading``."
+msgstr "引入默认的 ``batched_async_contains`` 实现，以便所有后端都可以支持 ``async_loading``\\ 。"
+
+#: ../../source/kv_cache/async_loading.rst:131
+msgid ""
+"Add metrics and observability to track the number of asynchronous lookup "
+"requests and the number of occupied ``MemoryObj`` instances."
+msgstr "添加指标和可观察性，以跟踪异步查找请求的数量和占用的 ``MemoryObj`` 实例的数量。"
+
+#: ../../source/kv_cache/async_loading.rst:132
+msgid ""
+"Improve the lookup framework by passing vLLM prefix cache hit tokens so "
+"that async lookup can skip loading parts already hit in vLLM."
+msgstr "通过传递 vLLM 前缀缓存命中令牌来改进查找框架，以便异步查找可以跳过已在 vLLM 中命中的部分加载。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/caching_policies.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/caching_policies.po
new file mode 100644
index 0000000..7cb7175
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/caching_policies.po
@@ -0,0 +1,54 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/caching_policies.rst:2
+msgid "Using Different Caching Policies"
+msgstr "使用不同的缓存策略"
+
+#: ../../source/kv_cache/caching_policies.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache/caching_policies.rst:9
+msgid "LMCache supports multiple caching policies."
+msgstr "LMCache 支持多种缓存策略。"
+
+#: ../../source/kv_cache/caching_policies.rst:11
+msgid ""
+"For example, to use LRU, you can set the environment variable "
+"``LMCACHE_CACHE_POLICY=LRU`` or set it in the configuration file with "
+"``cache_policy=\"LRU\"``."
+msgstr ""
+"例如，要使用 LRU，您可以设置环境变量 ``LMCACHE_CACHE_POLICY=LRU`` 或在配置文件中设置 "
+"``cache_policy=\\\"LRU\\\"``。"
+
+#: ../../source/kv_cache/caching_policies.rst:13
+msgid ""
+"Currently, LMCache supports \"LRU\" (Least Recently Used), \"MRU\" (Most "
+"Recently Used), \"LFU\" (Least Frequently Used) and \"FIFO\" (First-In-"
+"First-Out) caching policies."
+msgstr ""
+"目前，LMCache 支持 \\\"LRU\\\"（最近最少使用）、\\\"MRU\\\"（最近最多使用）、\\\"LFU\\\"（最不常用）和 "
+"\\\"FIFO\\\"（先进先出）缓存策略。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/multiprocess_mode.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/multiprocess_mode.po
new file mode 100644
index 0000000..99a6aec
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/multiprocess_mode.po
@@ -0,0 +1,38 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/multiprocess_mode.rst:4
+msgid "Multiprocess Mode (Redirect)"
+msgstr "多进程模式（重定向）"
+
+#: ../../source/kv_cache/multiprocess_mode.rst:7
+msgid ""
+"This page has moved.  The multiprocess mode documentation is now at "
+":doc:`/mp/index`."
+msgstr "此页面已移动。多进程模式文档现在位于 :doc:`/mp/index`。"
+
+#: ../../source/kv_cache/multiprocess_mode.rst:10
+msgid ""
+"Please see the new :doc:`/mp/index` section for complete documentation "
+"including quick start, configuration reference, L2 storage, deployment, "
+"observability, and architecture guides."
+msgstr "请参阅新的 :doc:`/mp/index` 部分以获取完整的文档，包括快速入门、配置参考、L2 存储、部署、可观察性和架构指南。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/p2p_sharing.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/p2p_sharing.po
new file mode 100644
index 0000000..27207aa
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/p2p_sharing.po
@@ -0,0 +1,208 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/p2p_sharing.rst:4
+msgid "P2P KV Cache Sharing"
+msgstr "P2P KV 缓存共享"
+
+#: ../../source/kv_cache/p2p_sharing.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/p2p`."
+msgstr "此页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/p2p`。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:11
+msgid ""
+"P2P (Peer-to-Peer) KV cache sharing enables direct cache transfer between"
+" multiple serving engine instances without requiring a centralized cache "
+"server. This approach provides high-performance cache sharing with "
+"reduced latency and improved scalability, especially beneficial in "
+"distributed inference scenarios."
+msgstr ""
+"P2P（点对点）KV "
+"缓存共享允许多个服务引擎实例之间直接传输缓存，而无需集中式缓存服务器。这种方法提供了高性能的缓存共享，减少了延迟并提高了可扩展性，特别是在分布式推理场景中非常有利。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:13
+msgid ""
+"LMCache supports P2P sharing through a controller-based architecture "
+"using NIXL (NVIDIA Inference Xfer Library) for optimized data transfer "
+"between instances."
+msgstr "LMCache 支持通过基于控制器的架构进行 P2P 共享，使用 NIXL（NVIDIA 推理传输库）优化实例之间的数据传输。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:16
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/kv_cache/p2p_sharing.rst:18
+msgid "**Multi-GPU Setup**: Your server should have at least 2 GPUs"
+msgstr "**多 GPU 设置**\\ ：您的服务器应该至少有 2 个 GPU"
+
+#: ../../source/kv_cache/p2p_sharing.rst:19
+msgid "**NIC**: RDMA is recommended for more performance."
+msgstr "**网络接口卡**\\ ：建议使用 RDMA 以获得更好的性能。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:20
+msgid "**NIXL**: Install from `NIXL <https://github.com/ai-dynamo/nixl>`_"
+msgstr "**NIXL**: 从 `NIXL <https://github.com/ai-dynamo/nixl>`_ 安装"
+
+#: ../../source/kv_cache/p2p_sharing.rst:21
+msgid ""
+"**vLLM**: v1 version is required, refer to :ref:`installation_guide` for "
+"details."
+msgstr "**vLLM**: 需要 v1 版本，详细信息请参阅 :ref:`installation_guide`。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:22
+msgid "**LMCache**: Install from :ref:`installation_guide`"
+msgstr "**LMCache**: 从 :ref:`installation_guide` 安装"
+
+#: ../../source/kv_cache/p2p_sharing.rst:25
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache/p2p_sharing.rst:27
+msgid "Create two configuration files for the P2P sharing setup."
+msgstr "为 P2P 共享设置创建两个配置文件。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:30
+msgid "**Instance 1 Configuration (example1.yaml)**:"
+msgstr "**实例 1 配置 (example1.yaml)**:"
+
+#: ../../source/kv_cache/p2p_sharing.rst:56
+msgid "**Instance 2 Configuration (example2.yaml)**:"
+msgstr "**实例 2 配置 (example2.yaml)**:"
+
+#: ../../source/kv_cache/p2p_sharing.rst:83
+msgid "Setup and Usage"
+msgstr "设置和使用"
+
+#: ../../source/kv_cache/p2p_sharing.rst:85
+msgid "**Step 1: Start the LMCache Controller**"
+msgstr "**步骤 1：启动 LMCache 控制器**"
+
+#: ../../source/kv_cache/p2p_sharing.rst:91
+msgid ""
+"Make sure that the 8300 and 8400 ports are set up in "
+"**controller_pull_url** and **controller_reply_url** in the configuration"
+" files. Port 9000 is the controller main port, which is arbitrary and can"
+" be changed."
+msgstr ""
+"确保在配置文件中将 8300 和 8400 端口设置在 **controller_pull_url** 和 "
+"**controller_reply_url** 中。9000 端口是控制器主端口，可以任意更改。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:94
+msgid "After starting the controller, access the WebUI at:"
+msgstr "启动控制器后，访问 WebUI："
+
+#: ../../source/kv_cache/p2p_sharing.rst:96
+msgid "http://localhost:9000/"
+msgstr "http://localhost:9000/"
+
+#: ../../source/kv_cache/p2p_sharing.rst:98
+msgid "**Step 2: Start vLLM Engines with LMCache Workers**"
+msgstr "**步骤 2：使用 LMCache 工作线程启动 vLLM 引擎**"
+
+#: ../../source/kv_cache/p2p_sharing.rst:100
+msgid "If the NIC supports RDMA:"
+msgstr "如果网络接口卡支持 RDMA："
+
+#: ../../source/kv_cache/p2p_sharing.rst:106
+msgid "If the NIC does not support RDMA:"
+msgstr "如果网络接口卡不支持 RDMA："
+
+#: ../../source/kv_cache/p2p_sharing.rst:112
+msgid "Start vLLM engine 1 at port 8010:"
+msgstr "在端口 8010 启动 vLLM 引擎 1："
+
+#: ../../source/kv_cache/p2p_sharing.rst:122
+msgid "Start vLLM engine 2 at port 8011:"
+msgstr "在端口 8011 启动 vLLM 引擎 2："
+
+#: ../../source/kv_cache/p2p_sharing.rst:132
+msgid "**Step 3: Test P2P Cache Sharing**"
+msgstr "**步骤 3：测试 P2P 缓存共享**"
+
+#: ../../source/kv_cache/p2p_sharing.rst:134
+msgid "Send a request to vLLM engine 1 to populate the cache:"
+msgstr "向 vLLM 引擎 1 发送请求以填充缓存："
+
+#: ../../source/kv_cache/p2p_sharing.rst:146
+msgid ""
+"Send the same request to vLLM engine 2 to demonstrate cache retrieval "
+"from **engine 1**:"
+msgstr "将相同的请求发送到 vLLM 引擎 2，以演示从 **引擎 1** 中检索缓存："
+
+#: ../../source/kv_cache/p2p_sharing.rst:159
+msgid "Expected Output"
+msgstr "预期输出"
+
+#: ../../source/kv_cache/p2p_sharing.rst:161
+msgid ""
+"When the second request successfully retrieves cache from the first "
+"instance, you should see logs similar to:"
+msgstr "当第二个请求成功从第一个实例检索缓存时，您应该看到类似于以下的日志："
+
+#: ../../source/kv_cache/p2p_sharing.rst:168
+msgid ""
+"These logs indicate successful P2P connection establishment and high-"
+"throughput cache retrieval."
+msgstr "这些日志表明成功建立了 P2P 连接并高吞吐量地检索了缓存。"
+
+#: ../../source/kv_cache/p2p_sharing.rst:172
+msgid "**Step 4: Benchmarking P2P Cache Sharing**"
+msgstr "**步骤 4：基准测试 P2P 缓存共享**"
+
+#: ../../source/kv_cache/p2p_sharing.rst:174
+msgid "Send a request workload to instance 1 to populate the cache:"
+msgstr "向实例 1 发送请求工作负载以填充缓存："
+
+#: ../../source/kv_cache/p2p_sharing.rst:188
+msgid ""
+"Send the same request workload to instance 2 to demonstrate cache "
+"retrieval from **instance 1**:"
+msgstr "将相同的请求工作负载发送到实例 2，以演示从 **实例 1** 中检索缓存："
+
+#: ../../source/kv_cache/p2p_sharing.rst:204
+msgid "Benchmark Results"
+msgstr "基准测试结果"
+
+#: ../../source/kv_cache/p2p_sharing.rst:206
+msgid "First instance metrics:"
+msgstr "第一次实例指标："
+
+#: ../../source/kv_cache/p2p_sharing.rst:221
+msgid "Second instance metrics:"
+msgstr "第二个实例指标："
+
+#: ../../source/kv_cache/p2p_sharing.rst:236
+#, python-format
+msgid ""
+"In this example, the warm-up round metric in long_doc_qa is used because "
+"no existing KV cache is reused within an instance to benefit solely from "
+"P2P sharing. With LMCache P2P sharing enabled, the time to first token "
+"(TTFT) is reduced by 54.7%, from 2.286 s to 1.036 s, with a 63.6% "
+"reduction in total inference time (37.957 s → 13.814 s)."
+msgstr ""
+"在这个例子中，long_doc_qa 中的预热轮次指标被使用，因为在一个实例内没有重用现有的 KV Cache 以仅从 P2P 共享中受益。启用 "
+"LMCache P2P 共享后，首次令牌时间 (TTFT) 减少了 54.7%，从 2.286 秒降至 1.036 秒，总推理时间减少了 "
+"63.6%（37.957 秒 → 13.814 秒）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/3fs.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/3fs.po
new file mode 100644
index 0000000..8604821
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/3fs.po
@@ -0,0 +1,174 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:2
+msgid "3FS"
+msgstr "3FS"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:14
+msgid ""
+"3FS (Fire-Flyer File System) is an AI native distributed file-system "
+"which provides high performance and low latency. It is a supported option"
+" for KV Cache offloading in LMCache. Even though the FSConnector backend "
+"can work with 3FS storage cluster, but it access data in 3FS storage "
+"cluster by FUSE interfaces. It can't leverage 3FS high performance. This "
+"particular backend uses 3FS native USRBIO(User Space Ring Based IO) "
+"interfaces to access 3FS storage cluster which get high performance."
+msgstr ""
+"3FS（火飞文件系统）是一个 AI 原生的分布式文件系统，提供高性能和低延迟。它是 LMCache 卸载 KV Cache 的一个支持选项。尽管 "
+"FSConnector 后端可以与 3FS 存储集群一起工作，但它通过 FUSE 接口访问 3FS 存储集群，无法利用 3FS "
+"的高性能。这个特定的后端使用 3FS 原生的 USRBIO（用户空间环形 IO）接口访问 3FS 存储集群，从而获得高性能。"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:21
+msgid "Configure LMCache 3FS Offloading"
+msgstr "配置 LMCache 3FS 卸载"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:23
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:25
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:71
+msgid "There are 2 methods to config hf3fs remote backend:"
+msgstr "配置 hf3fs 远程后端有两种方法："
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:72
+msgid "Plugin name mode, uses the parameter remote_storage_plugins(Recommend)"
+msgstr "插件名称模式，使用参数 remote_storage_plugins（推荐）"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:73
+msgid ""
+"URL mode, uses the parameter remote_url(Deprecated, will be removed in a "
+"future)"
+msgstr "URL 模式，使用参数 remote_url（已弃用，将在未来删除）"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:75
+msgid ""
+"For URL mode, the base_path is contained in the url. For plugin name "
+"mode, there are 2 methods to set base_path:"
+msgstr "对于 URL 模式，base_path 包含在 url 中。对于插件名称模式，有两种方法可以设置 base_path："
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:76
+#, python-brace-format
+msgid ""
+"remote_storage_plugin.{plugin name}.base_path, it sets the base_path for "
+"a plugin instance."
+msgstr "remote_storage_plugin.{plugin name}.base_path，它为插件实例设置 base_path。"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:77
+msgid "e.g.:remote_storage_plugin.hf3fs.primary.base_path"
+msgstr "e.g.:remote_storage_plugin.hf3fs.primary.base_path"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:78
+msgid "hf3fs_base_path, it set the base_path for all plugin instances"
+msgstr "hf3fs_base_path，它为所有插件实例设置了 base_path"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:81
+msgid "Installation"
+msgstr "安装"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:85
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:87
+msgid ""
+"A Machine with at least one GPU. You can adjust the max model length of "
+"your vllm instance depending on your GPU memory."
+msgstr "一台至少配备一个 GPU 的机器。您可以根据您的显存调整 vllm 实例的最大模型长度。"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:89
+msgid "vllm and lmcache installed"
+msgstr "已安装 vllm 和 LMCache"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:91
+msgid "**Step 1. Install 3FS hf3fs_py_usrbio package**"
+msgstr "**步骤 1. 安装 3FS hf3fs_py_usrbio 包**"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:93
+msgid ""
+"The inference server need install 3FS hf3fs_py_usrbio package, recommend "
+"to build the package from source:"
+msgstr "推理服务器需要安装 3FS hf3fs_py_usrbio 包，建议从源代码构建该包："
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:104
+msgid ""
+"`3FS Build <https://github.com/deepseek-ai/3FS/blob/main/README.md#build-"
+"3fs>`_"
+msgstr ""
+"`3FS Build <https://github.com/deepseek-ai/3FS/blob/main/README.md#build-"
+"3fs>`_"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:107
+msgid "**Step 2. Setup 3FS storage cluster**"
+msgstr "**步骤 2. 设置 3FS 存储集群**"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:109
+msgid ""
+"`3FS Setup <https://github.com/deepseek-"
+"ai/3FS/blob/main/deploy/README.md>`_"
+msgstr "`3FS 设置 <https://github.com/deepseek-ai/3FS/blob/main/deploy/README.md>`_"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:112
+msgid "**Step 3. Deploy 3FS FUSE client in inference server**"
+msgstr "**步骤 3. 在推理服务器上部署 3FS FUSE 客户端**"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:114
+msgid ""
+"The inference server must deploy 3FS FUSE client(a fuse daemon process "
+"provided by 3FS), otherwise, it can't access 3FS storage cluster"
+msgstr "推理服务器必须部署 3FS FUSE 客户端（由 3FS 提供的 FUSE 守护进程），否则无法访问 3FS 存储集群。"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:117
+msgid ""
+"`Setup 3FS FUSE Client <https://github.com/deepseek-"
+"ai/3FS/blob/main/deploy/README.md#step-8-fuse-client>`_"
+msgstr ""
+"`设置 3FS FUSE 客户端 <https://github.com/deepseek-"
+"ai/3FS/blob/main/deploy/README.md#step-8-fuse-client>`_"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:120
+msgid "**Step 4. Start a vLLM server with 3FS offloading enabled**"
+msgstr "**步骤 4. 启动一个启用 3FS 卸载的 vLLM 服务器**"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:122
+msgid "Create a lmcache configuration file called: ``3fs-offload.yaml``"
+msgstr "创建一个名为 ``3fs-offload.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/3fs.rst:160
+msgid "Start vllm:"
+msgstr "启动 vLLM："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/bigtable.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/bigtable.po
new file mode 100644
index 0000000..9fc972a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/bigtable.po
@@ -0,0 +1,374 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:2
+msgid "Google Cloud Bigtable"
+msgstr "谷歌云 Bigtable"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:14
+msgid ""
+"Google Cloud Bigtable is a petabyte-scale, fully managed NoSQL database. "
+"Integrating Cloud Bigtable as a built-in remote storage connector inside "
+"LMCache bridges volatile high-cost in-memory tiers (Redis) and low-cost, "
+"high-latency archival object stores (S3)."
+msgstr ""
+"Google Cloud Bigtable 是一个 PB 级别的完全托管的 NoSQL 数据库。将 Cloud Bigtable 作为 "
+"LMCache 内置的远程存储连接器集成，可以桥接高成本的易失性内存层（Redis）和低成本、高延迟的归档对象存储（S3）。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:16
+msgid ""
+"For more information, see the `Cloud Bigtable Overview "
+"<https://cloud.google.com/bigtable/docs/overview>`_ and `Cloud Bigtable "
+"Pricing <https://cloud.google.com/bigtable/pricing>`_."
+msgstr ""
+"有关更多信息，请参阅 `Cloud Bigtable 概述 "
+"<https://cloud.google.com/bigtable/docs/overview>`_ 和 `Cloud Bigtable 定价 "
+"<https://cloud.google.com/bigtable/pricing>`_。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:19
+msgid "Architecture & Payload Limits"
+msgstr "架构与负载限制"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:21
+msgid ""
+"**Chunk Size Optimization**: Set LMCache's logical ``chunk_size`` to "
+"**256 tokens**. This groups payloads to minimize sequential Point-Read "
+"gRPC calls, preventing Python event-loop (GIL) bottlenecks."
+msgstr ""
+"**块大小优化**\\ ：将 LMCache 的逻辑 ``chunk_size`` 设置为 **256 个 token**\\ "
+"。这将对有效负载进行分组，以最小化顺序 Point-Read gRPC 调用，防止 Python 事件循环 (GIL) 瓶颈。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:22
+msgid ""
+"**MutateRow Limit**: Enforces a strict **90.0 MB request limit** for a "
+"single ``MutateRow`` gRPC request."
+msgstr "**MutateRow 限制**\\ ：对单个 ``MutateRow`` gRPC 请求强制执行严格的 **90.0 MB 请求限制**\\ 。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:23
+msgid ""
+"**Storage Tier Row Limits**: The **SSD Tier** ceiling is **100 MiB per "
+"cell/row**. The **Enterprise Plus In-Memory Tier** is limited to **1.0 "
+"MiB per row**."
+msgstr ""
+"**存储层行限制**\\ ：\\ **SSD 层**\\ 的上限为\\ **每个单元/行 100 MiB**\\ 。\\ "
+"**企业增强内存层**\\ 的限制为\\ **每行 1.0 MiB**\\ 。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:24
+msgid ""
+"**TTLCache Shielding**: Embeds a thread-safe ``TTLCache`` (10-second TTL "
+"default) to shield Bigtable nodes from concurrent prefetch lookup spikes."
+msgstr ""
+"**TTLCache 保护**: 嵌入一个线程安全的 ``TTLCache``\\ （默认 TTL 为 10 秒），以保护 Bigtable "
+"节点免受并发预取查找峰值的影响。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:27
+msgid "Infrastructure Setup"
+msgstr "基础设施设置"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:29
+msgid "**1. Enable GCP APIs**"
+msgstr "**1. 启用 GCP API**"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:33
+msgid ""
+"gcloud services enable bigtable.googleapis.com "
+"bigtableadmin.googleapis.com --project=your-gcp-project-id"
+msgstr ""
+"gcloud services enable bigtable.googleapis.com "
+"bigtableadmin.googleapis.com --project=your-gcp-project-id"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:35
+msgid "**2. Provision Bigtable Instance**"
+msgstr "**2. 配置 Bigtable 实例**"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:37
+msgid ""
+"Refer to the `gcloud beta bigtable Reference "
+"<https://cloud.google.com/sdk/gcloud/reference/beta/bigtable>`_ for "
+"additional parameter details."
+msgstr ""
+"请参阅 `gcloud beta bigtable Reference "
+"<https://cloud.google.com/sdk/gcloud/reference/beta/bigtable>`_ "
+"以获取更多参数详细信息。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:41
+msgid "gcloud beta bigtable instances create your-bigtable-instance-id \\"
+msgstr "gcloud beta bigtable instances create your-bigtable-instance-id \\\\"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:42
+msgid ""
+"--display-name=\"LMCache SSD Instance\" \\ --edition=ENTERPRISE \\ "
+"--cluster-storage-type=ssd \\ --cluster-config=id=your-cluster-id,zone"
+"=us-central1-a,nodes=1 \\ --project=your-gcp-project-id"
+msgstr ""
+"--display-name=\"LMCache SSD 实例\" \\\\ --edition=ENTERPRISE \\\\ "
+"--cluster-storage-type=ssd \\\\ --cluster-config=id=your-cluster-id,zone"
+"=us-central1-a,nodes=1 \\\\ --project=your-gcp-project-id"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:48
+msgid "**3. Create Database Table & Column Family**"
+msgstr "**3. 创建数据库表和列族**"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:52
+msgid "gcloud bigtable instances tables create lmcache-benchmark-v1 \\"
+msgstr "gcloud bigtable instances tables create lmcache-benchmark-v1 \\\\"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:53
+msgid ""
+"--instance=your-bigtable-instance-id \\ --column-families=cf \\ --project"
+"=your-gcp-project-id"
+msgstr ""
+"--instance=your-bigtable-instance-id \\\\ --column-families=cf \\\\ "
+"--project=your-gcp-project-id"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:57
+msgid "**4. Install LMCache & Bigtable SDK**"
+msgstr "**4. 安装 LMCache 和 Bigtable SDK**"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:61
+msgid ""
+"export NO_NATIVE_EXT=1 pip install --no-cache-dir lmcache google-cloud-"
+"bigtable"
+msgstr ""
+"export NO_NATIVE_EXT=1 pip install --no-cache-dir lmcache google-cloud-"
+"bigtable"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:65
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:67
+msgid "**Example A: Standard Bigtable SSD Integration (L2 Only)**"
+msgstr "**示例 A：标准 Bigtable SSD 集成（仅限 L2）**"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:71
+msgid "chunk_size: 256"
+msgstr "chunk_size: 256"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:73
+msgid ""
+"local_cpu: true max_local_cpu_size: 10.0 remote_url: \"bigtable://your-"
+"gcp-project-id/your-bigtable-instance-id\""
+msgstr ""
+"local_cpu: true max_local_cpu_size: 10.0 remote_url: \"bigtable://your-"
+"gcp-project-id/your-bigtable-instance-id\""
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:77
+msgid "remote_serde: \"naive\""
+msgstr "remote_serde: \"naive\""
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:79
+#: ../../source/kv_cache/storage_backends/bigtable.rst:101
+msgid "extra_config:"
+msgstr "额外配置："
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:80
+msgid ""
+"bigtable_project_id: \"your-gcp-project-id\" bigtable_instance_id: "
+"\"your-bigtable-instance-id\" bigtable_table_name: \"lmcache-"
+"benchmark-v1\""
+msgstr ""
+"bigtable_project_id: \"你的 GCP 项目 ID\" bigtable_instance_id: \"你的 Bigtable"
+" 实例 ID\" bigtable_table_name: \"lmcache-benchmark-v1\""
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:85
+msgid ""
+"Alternatively, you can set the environment variables ``BT_PROJECT_ID``, "
+"``BT_INSTANCE_ID``, and ``BT_TABLE_NAME`` instead of using "
+"``extra_config``."
+msgstr ""
+"或者，您可以设置环境变量 ``BT_PROJECT_ID``\\ 、\\ ``BT_INSTANCE_ID`` 和 "
+"``BT_TABLE_NAME``\\ ，而不是使用 ``extra_config``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:87
+msgid ""
+"**Example B: 3-Tier Multi-Connector Hybrid (Local CPU -> Redis L2 -> "
+"Bigtable SSD L3)**"
+msgstr "**示例 B：3 层多连接器混合（本地 CPU -> Redis L2 -> Bigtable SSD L3）**"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:89
+msgid ""
+"Deploy Redis for hot-cache loopbacks while offloading long-tail "
+"persistent storage to Bigtable SSD, using LMCache's dynamic OrderedDict "
+"routing."
+msgstr "在热缓存回路中部署 Redis，同时将长尾持久存储卸载到 Bigtable SSD，使用 LMCache 的动态有序字典路由。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:93
+msgid "chunk_size: 256 local_cpu: true max_local_cpu_size: 15.0"
+msgstr "chunk_size: 256 local_cpu: true max_local_cpu_size: 15.0"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:97
+msgid "remote_storage_plugins:"
+msgstr "远程存储插件："
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:98
+msgid "\"redis\""
+msgstr "redis"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:99
+msgid "\"bigtable\""
+msgstr "bigtable"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:102
+msgid "remote_storage_plugin.redis.redis_url: \"redis://your-redis-host:6379\""
+msgstr "remote_storage_plugin.redis.redis_url: \"redis://your-redis-host:6379\""
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:104
+msgid ""
+"remote_storage_plugin.bigtable.bigtable_project_id: \"your-gcp-project-"
+"id\" remote_storage_plugin.bigtable.bigtable_instance_id: \"your-"
+"bigtable-instance-id\" "
+"remote_storage_plugin.bigtable.bigtable_table_name: \"lmcache-"
+"benchmark-v1\" remote_storage_plugin.bigtable.bigtable_family_name: "
+"\"cf\" remote_storage_plugin.bigtable.bigtable_column_name: \"data\""
+msgstr ""
+"remote_storage_plugin.bigtable.bigtable_project_id: \\\"your-gcp-project-"
+"id\\\" remote_storage_plugin.bigtable.bigtable_instance_id: \\\"your-"
+"bigtable-instance-id\\\" "
+"remote_storage_plugin.bigtable.bigtable_table_name: \\\"lmcache-"
+"benchmark-v1\\\" remote_storage_plugin.bigtable.bigtable_family_name: "
+"\\\"cf\\\" remote_storage_plugin.bigtable.bigtable_column_name: "
+"\\\"data\\\""
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:110
+msgid "remote_storage_plugin.bigtable.credentials_path: \"/etc/gcp/key.json\""
+msgstr "remote_storage_plugin.bigtable.credentials_path: \"/etc/gcp/key.json\""
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:112
+msgid ""
+"remote_storage_plugin.bigtable.bigtable_max_chunk_size_mb: 90.0 "
+"remote_storage_plugin.bigtable.exists_cache_ttl_seconds: 10.0 "
+"remote_storage_plugin.bigtable.exists_cache_size: 10000"
+msgstr ""
+"remote_storage_plugin.bigtable.bigtable_max_chunk_size_mb: 90.0 "
+"remote_storage_plugin.bigtable.exists_cache_ttl_seconds: 10.0 "
+"remote_storage_plugin.bigtable.exists_cache_size: 10000"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:116
+msgid ""
+"remote_storage_plugin.bigtable.bigtable_write_timeout_ms: 10000.0 "
+"remote_storage_plugin.bigtable.bigtable_read_timeout_ms: 5000.0"
+msgstr ""
+"remote_storage_plugin.bigtable.bigtable_write_timeout_ms: 10000.0 "
+"remote_storage_plugin.bigtable.bigtable_read_timeout_ms: 5000.0"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:120
+msgid "Authentication"
+msgstr "身份验证"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:122
+msgid ""
+"**Application Default Credentials (ADC)**: If ``credentials_path`` is "
+"omitted or ``null``, the connector natively invokes ADC. Compatible with "
+"local development via ``gcloud auth application-default login`` or GKE "
+"Workload Identity Federation."
+msgstr ""
+"**应用默认凭据 (ADC)**\\ ：如果 ``credentials_path`` 被省略或为 ``null``\\ ，连接器将原生调用 "
+"ADC。支持通过 ``gcloud auth application-default login`` 进行本地开发或 GKE 工作负载身份联合。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:123
+msgid ""
+"**Explicit Keys**: Pass the absolute filesystem path containing a mounted"
+" GCP Service Account JSON secret to ``credentials_path``."
+msgstr "**显式密钥**\\ ：将包含挂载的 GCP 服务账户 JSON 密钥的绝对文件系统路径传递给 ``credentials_path``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:126
+msgid "Verification"
+msgstr "验证"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:128
+msgid "Ensure you have installed the required dependencies:"
+msgstr "确保您已安装所需的依赖项："
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:132
+msgid "pip install cachetools google-cloud-bigtable"
+msgstr "pip install cachetools google-cloud-bigtable"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:134
+msgid "Run the unit tests:"
+msgstr "运行单元测试："
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:138
+msgid "pytest tests/v1/storage_backend/test_bigtable_connector.py"
+msgstr "pytest tests/v1/storage_backend/test_bigtable_connector.py"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:141
+msgid "Troubleshooting Large Payload Warnings"
+msgstr "处理大负载警告"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:143
+msgid ""
+"If you see a warning in the logs indicating that a chunk size exceeds the"
+" limit and is skipped (e.g. ``Bigtable chunk size ... MB exceeds "
+"threshold ... MB. Skipping write to prevent hard failures``), choose one "
+"of the following approaches:"
+msgstr ""
+"如果您在日志中看到警告，指示块大小超过限制并被跳过（例如 ``Bigtable chunk size ... MB exceeds "
+"threshold ... MB. Skipping write to prevent hard failures``\\ "
+"），请选择以下方法之一："
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:145
+msgid ""
+"**Reduce the LMCache Chunk Size (Recommended)**: The serialized chunk "
+"size depends on LMCache's logical ``chunk_size`` (number of tokens per "
+"chunk) and model shape. You can reduce ``chunk_size`` (e.g., from ``256``"
+" to ``128``) in your configuration file to shrink individual chunk "
+"payloads."
+msgstr ""
+"**减少 LMCache 块大小（推荐）**\\ ：序列化块大小取决于 LMCache 的逻辑 ``chunk_size``\\ "
+"（每块的令牌数量）和模型形状。您可以在配置文件中将 ``chunk_size``\\ （例如，从 ``256`` 减少到 ``128``\\ "
+"）来缩小单个块的有效负载。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:148
+msgid ""
+"**Increase the Max Chunk Size**: If your Bigtable instance uses the SSD "
+"storage tier (which supports up to 100 MB per cell/row), you can raise "
+"the maximum allowed write threshold in the configuration up to ``99.0`` "
+"MB using the ``bigtable_max_chunk_size_mb`` config key (or the "
+"``BT_MAX_CHUNK_SIZE_MB`` environment variable)."
+msgstr ""
+"**增加最大块大小**\\ ：如果您的 Bigtable 实例使用 SSD 存储层（支持每个单元/行最多 100 "
+"MB），您可以在配置中将允许的最大写入阈值提高到 ``99.0`` MB，使用 ``bigtable_max_chunk_size_mb`` "
+"配置键（或 ``BT_MAX_CHUNK_SIZE_MB`` 环境变量）。"
+
+#: ../../source/kv_cache/storage_backends/bigtable.rst:152
+msgid ""
+"Do not set ``bigtable_max_chunk_size_mb`` higher than ``100.0`` MB. While"
+" Cloud Bigtable supports up to ``256.0`` MB for a single row, a single "
+"cell value (which LMCache uses to store the chunk payload) has a hard "
+"limit of ``100.0`` MB. Exceeding this will trigger hard gRPC exceptions."
+msgstr ""
+"请勿将 ``bigtable_max_chunk_size_mb`` 设置得高于 ``100.0`` MB。虽然 Cloud Bigtable "
+"支持单行高达 ``256.0`` MB，但单个单元格值（LMCache 用于存储块负载的值）有一个硬限制为 ``100.0`` "
+"MB。超过此限制将触发硬 gRPC 异常。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/cpu_ram.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/cpu_ram.po
new file mode 100644
index 0000000..63213b4
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/cpu_ram.po
@@ -0,0 +1,319 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:2
+msgid "CPU RAM"
+msgstr "CPU 内存"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:14
+msgid ""
+"CPU RAM and Local Storage are the two ways of offloading KV cache onto "
+"non-GPU memory of the same machine that is running inference."
+msgstr "CPU RAM 和本地存储是将 KV Cache 卸载到同一台运行推理的机器的非 GPU 内存的两种方式。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:18
+msgid "Two ways to configure LMCache CPU Offloading:"
+msgstr "配置 LMCache CPU 卸载的两种方式："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:20
+msgid "**1. Environment Variables:**"
+msgstr "**1. 环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:31
+msgid "**2. Configuration File**:"
+msgstr "**2. 配置文件**:"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:33
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:35
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:47
+msgid "CPU RAM Explanation:"
+msgstr "CPU RAM 说明："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:49
+msgid ""
+"The ``LMCACHE_MAX_LOCAL_CPU_SIZE`` is the amount of page-locked (for fast"
+" GPU transfer) CPU memory that LMCache will reserve and must be set to a "
+"number greater than 0 since local and remote backends also use CPU RAM as"
+" an intermediate buffer when transferring KV caches with the GPU. This "
+"means it is possible to set ``LMCACHE_LOCAL_CPU=False`` even though "
+"``LMCACHE_MAX_LOCAL_CPU_SIZE`` is set to a non-zero number."
+msgstr ""
+"``LMCACHE_MAX_LOCAL_CPU_SIZE`` 是 LMCache 将保留的页面锁定（用于快速 GPU 传输）CPU "
+"内存的数量，必须设置为大于 0 的数字，因为本地和远程后端在使用 GPU 传输 KV 缓存时也会使用 CPU 内存作为中间缓冲区。这意味着即使 "
+"``LMCACHE_MAX_LOCAL_CPU_SIZE`` 设置为非零数字，也可以将 ``LMCACHE_LOCAL_CPU=False``\\"
+" 。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:56
+msgid ""
+"However, it is recommended to *always* set ``LMCACHE_LOCAL_CPU=True`` "
+"(the default is ``True`` so if you don't specify, CPU offloading will "
+"automatically be enabled) since this allows all currently unused pinned "
+"CPU RAM that LMCache has reserved to hold KV caches. When the pinned CPU "
+"RAM is required for any disk or remote transfers, the CPU KV caches will "
+"be LRU evicted to make space so there is no danger of running out of "
+"pinned CPU RAM."
+msgstr ""
+"然而，建议始终将\\ ``LMCACHE_LOCAL_CPU=True``\\ 设置为真（默认值为\\ ``True``\\ "
+"，因此如果不指定，CPU 卸载将自动启用），因为这允许 LMCache 保留的所有当前未使用的固定 CPU 内存用于保存 KV 缓存。当固定 "
+"CPU 内存需要用于任何磁盘或远程传输时，CPU KV 缓存将被 LRU 逐出以腾出空间，因此不会出现固定 CPU 内存耗尽的危险。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:61
+msgid ""
+"When ``LMCACHE_LOCAL_CPU=True`` is used in conjunction with the disk "
+"backend or a remote backend (:doc:`Redis <./redis>`, :doc:`Mooncake "
+"<./mooncake>`, :doc:`Valkey <./valkey>`, or :doc:`Infinistore "
+"<./infinistore>`), we can think of the CPU RAM as a \"hot cache\" that "
+"will contain the \"hottest\" (most recently accessed)subset of KV caches "
+"from Disk and Remote storage."
+msgstr ""
+"当 ``LMCACHE_LOCAL_CPU=True`` 与磁盘后端或远程后端 (:doc:`Redis "
+"<./redis>`、:doc:`Mooncake <./mooncake>`、:doc:`Valkey <./valkey>` 或 "
+":doc:`Infinistore <./infinistore>`) 一起使用时，我们可以将 CPU "
+"内存视为一个“热缓存”，它将包含来自磁盘和远程存储的“最热”（最近访问过的）KV 缓存子集。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:66
+msgid ""
+"Thus, the cache engine also has a **prefetch** mechanism to preload the "
+"KV caches for specified tokens into the pinned CPU RAM from the disk or "
+"remote storage (*if* the KV caches for these tokens are already stored "
+"there). This can preemptively avoid the latency of the disk and remote KV"
+" transfer if we predict these tokens will be requested soon (e.g. "
+"structured or agentic workflows)."
+msgstr ""
+"因此，缓存引擎还具有一个 **预取** 机制，可以将指定令牌的 KV 缓存从磁盘或远程存储预加载到固定的 CPU RAM 中（前提是这些令牌的 "
+"KV 缓存已经存储在那里）。如果我们预测这些令牌将很快被请求（例如，结构化或自主工作流），这可以预先避免磁盘和远程 KV 传输的延迟。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:74
+msgid "Hugepage Support"
+msgstr "大页支持"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:76
+msgid ""
+"By default LMCache allocates CPU-pinned memory using regular 4 KiB pages."
+" For large KV cache buffers (multiple gigabytes), enabling **Linux "
+"hugepages** (2 MiB pages) can reduce TLB (Translation Lookaside Buffer) "
+"pressure and improve memory access performance."
+msgstr ""
+"默认情况下，LMCache 使用常规的 4 KiB 页面分配 CPU 固定内存。对于大型 KV Cache 缓冲区（多个千兆字节），启用 "
+"**Linux 大页**\\ （2 MiB 页面）可以减少 TLB（转换后备缓冲区）压力并提高内存访问性能。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:81
+msgid "**System prerequisite**"
+msgstr "**系统先决条件**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:83
+msgid ""
+"Hugepages must be pre-allocated at the OS level before LMCache starts. TO"
+" find the number of pages needed, divide the desired buffer size by 2 MiB"
+" and round up. For example, 5 GB requires at least 2560 pages:"
+msgstr ""
+"在 LMCache 启动之前，必须在操作系统级别预先分配大页面。要找到所需的页面数量，将所需的缓冲区大小除以 2 MiB 并向上取整。例如，5 "
+"GB 至少需要 2560 页："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:95
+msgid "Verify that pages are available:"
+msgstr "验证页面是否可用："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:103
+msgid "**Configuration**"
+msgstr "**配置**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:109
+msgid "Or via environment variable:"
+msgstr "或者通过环境变量："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:115
+msgid "**Restrictions**"
+msgstr "**限制**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:117
+msgid "Hugepages are **not compatible with P2P mode** (``enable_p2p: true``)."
+msgstr "大页 **与 P2P 模式不兼容** (``enable_p2p: true``)。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:118
+msgid "Hugepages are **not compatible with shared memory** (``shm_name`` is set)."
+msgstr "大页与 **共享内存** 不兼容（\\ ``shm_name`` 已设置）。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:119
+msgid ""
+"On non-CUDA platforms, hugepages are not supported. Regular allocation "
+"will be used as fallback."
+msgstr "在非CUDA平台上，不支持大页。将使用常规分配作为后备。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:124
+msgid "Online Inference Example"
+msgstr "在线推理示例"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:126
+msgid "Let's feel the TTFT (time to first token) differential!"
+msgstr "让我们感受一下 TTFT（首次令牌时间）差异！"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:130
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:132
+msgid ""
+"A Machine with at least one GPU. Adjust the max model length of your vllm"
+" instance depending on your GPU memory and the long context you want to "
+"use."
+msgstr "一台至少配备一块 GPU 的机器。根据您的显存和希望使用的长上下文调整 vllm 实例的最大模型长度。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:134
+msgid ""
+"vllm and lmcache installed (:doc:`Installation Guide "
+"<../../getting_started/installation>`)"
+msgstr "vllm 和 lmcache 已安装 (:doc:`安装指南 <../../getting_started/installation>`)"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:136
+msgid "Hugging Face access to ``meta-llama/Meta-Llama-3.1-8B-Instruct``"
+msgstr "Hugging Face 访问 ``meta-llama/Meta-Llama-3.1-8B-Instruct``"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:142
+msgid "A few packages:"
+msgstr "一些软件包："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:148
+msgid "**Step 0. Set up a directory for this example:**"
+msgstr "**第 0 步. 为此示例设置一个目录:**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:155
+msgid "**Step 1. Prepare a long context!**"
+msgstr "**步骤 1. 准备一个长上下文！**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:157
+msgid ""
+"We want a context long enough that vllm's prefix caching will not be able"
+" to hold the KV caches in GPU memory and LMCache is necessary to keep KV "
+"caches in non-GPU memory:"
+msgstr "我们希望上下文足够长，以至于 vLLM 的前缀缓存无法将 KV 缓存保留在显存中，因此需要 LMCache 将 KV 缓存保留在非显存中："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:165
+msgid "**Step 2. Start a vLLM server with CPU offloading enabled:**"
+msgstr "**步骤 2. 启动一个启用 CPU 卸载的 vLLM 服务器:**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:167
+msgid "Create a an lmcache configuration file called: ``cpu-offload.yaml``"
+msgstr "创建一个名为 ``cpu-offload.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:175
+msgid ""
+"If you don't want to use a config file, uncomment the first three "
+"environment variables and then comment out the ``LMCACHE_CONFIG_FILE`` "
+"below:"
+msgstr "如果您不想使用配置文件，请取消注释前面三个环境变量，然后注释掉下面的 ``LMCACHE_CONFIG_FILE``："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:190
+msgid ""
+"``--kv-transfer-config``: This is the parameter that actually tells vLLM "
+"to use LMCache for KV cache offloading."
+msgstr "``--kv-transfer-config``: 这是实际告诉 vLLM 使用 LMCache 进行 KV Cache 卸载的参数。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:191
+msgid "``kv_connector``: Specifies the LMCache connector for vLLM V1"
+msgstr "``kv_connector``: 指定 vLLM V1 的 LMCache 连接器"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:192
+msgid ""
+"``kv_role``: Set to \"kv_both\" for both storing and loading KV cache "
+"(important because we will run two queries and the first will "
+"produce/store a KV cache while the second will consume/load that KV "
+"cache)"
+msgstr ""
+"``kv_role``: 设置为 \\\"kv_both\\\" 以同时存储和加载 KV "
+"Cache（重要，因为我们将运行两个查询，第一个将生成/存储一个 KV Cache，而第二个将消费/加载该 KV Cache）"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:194
+msgid "**Step 3. Query TTFT improvements with LMCache:**"
+msgstr "**步骤 3. 使用 LMCache 查询 TTFT 改进：**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:196
+msgid ""
+"Once the Open AI compatible server is running on default vllm port 8000, "
+"let's query it twice with the same long context!"
+msgstr "一旦 Open AI 兼容的服务器在默认的 vllm 端口 8000 上运行，让我们用相同的长上下文查询两次！"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:198
+msgid "Create a script called ``query-twice.py`` and paste the following code:"
+msgstr "创建一个名为 ``query-twice.py`` 的脚本，并粘贴以下代码："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:264
+msgid "Then run:"
+msgstr "然后运行："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:270
+msgid ""
+"Since we're in streaming mode, you'll be able to feel the TTFT "
+"differential in real time!"
+msgstr "由于我们处于流式模式，您将能够实时感受到 TTFT 差异！"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:273
+msgid "**Example Output:**"
+msgstr "**示例输出：**"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:298
+msgid ""
+"If you look at the logs of your vLLM server, you should see (the logs are"
+" truncated for cleanliness):"
+msgstr "如果你查看 vLLM 服务器的日志，你应该会看到（日志已为整洁而截断）："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:326
+msgid "Tips:"
+msgstr "提示："
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:328
+msgid ""
+"If you want to run the ``query-twice.py`` script multiple times, you'll "
+"need to either restart the vLLM LMCache server or change the prefix of "
+"the context you pass in since you've already warmed LMCache."
+msgstr ""
+"如果您想多次运行 ``query-twice.py`` 脚本，您需要重启 vLLM LMCache "
+"服务器或更改您传入的上下文前缀，因为您已经预热了 LMCache。"
+
+#: ../../source/kv_cache/storage_backends/cpu_ram.rst:330
+msgid ""
+"The max model length here was decided by running an L4 with only 23GB of "
+"GPU memory. If you have more memory, you can increase the max model "
+"length and modify ``query-twice.py`` to use more of the long context. "
+"LMCache TTFT improvement becomes more pronounced as the context length "
+"increases!"
+msgstr ""
+"这里的最大模型长度是通过仅使用 23GB 显存的 L4 运行决定的。如果您有更多内存，可以增加最大模型长度并修改 ``query-"
+"twice.py`` 以使用更多的长上下文。随着上下文长度的增加，LMCache 的 TTFT 改进变得更加明显！"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/custom_backend.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/custom_backend.po
new file mode 100644
index 0000000..9e5359c
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/custom_backend.po
@@ -0,0 +1,39 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/custom_backend.rst:2
+msgid "Custom Storage Backends"
+msgstr "自定义存储后端"
+
+#: ../../source/kv_cache/storage_backends/custom_backend.rst:4
+msgid ""
+"LMCache supports integrating custom storage backends through dynamic "
+"loading or plug and play capability. This allows extending cache storage "
+"capabilities without modifying core code."
+msgstr "LMCache 支持通过动态加载或即插即用能力集成自定义存储后端。这允许在不修改核心代码的情况下扩展缓存存储能力。"
+
+#: ../../source/kv_cache/storage_backends/custom_backend.rst:6
+msgid ""
+"See :doc:`Storage Plugins "
+"<../../developer_guide/extending_lmcache/storage_plugins>` for more "
+"details."
+msgstr "有关更多详细信息，请参阅 :doc:`存储插件 <../../developer_guide/extending_lmcache/storage_plugins>`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/dax.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/dax.po
new file mode 100644
index 0000000..20a8349
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/dax.po
@@ -0,0 +1,383 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-15 11:17+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:1
+msgid "# SPDX-License-Identifier: Apache-2.0"
+msgstr "# SPDX-License-Identifier: Apache-2.0"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:4
+msgid "Device-DAX (/dev/dax)"
+msgstr "设备-DAX (/dev/dax)"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:7
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:9
+msgid ""
+"The DAX storage plugin maps a ``/dev/dax`` device using "
+"``mmap(MAP_SHARED)`` and uses the mapped region as a fixed-size arena for"
+" KV cache chunks. Typical ``/dev/dax`` devices include persistent memory,"
+" CXL-attached memory, and other byte-addressable memory devices."
+msgstr ""
+"DAX 存储插件通过 ``mmap(MAP_SHARED)`` 映射 ``/dev/dax`` 设备，并将映射区域用作 KV Cache "
+"块的固定大小区域。典型的 ``/dev/dax`` 设备包括持久内存、CXL 附加内存和其他字节可寻址内存设备。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:14
+msgid ""
+"Data stored on the DAX device may survive process restarts, but is not "
+"guaranteed to be durable."
+msgstr "存储在 DAX 设备上的数据可能在进程重启后仍然存在，但不保证其持久性。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:17
+msgid ""
+"KV cache data is stored in the DAX region as part of the backend's "
+"storage flow. Reads copy data back into CPU-backed memory objects."
+msgstr "KV Cache 数据作为后端存储流程的一部分存储在 DAX 区域。读取操作会将数据复制回 CPU 内存对象。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:22
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:42
+msgid "Multiprocess Mode"
+msgstr "多进程模式"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:44
+msgid ""
+"In LMCache multiprocess mode, Device-DAX is configured as a built-in L2 "
+"adapter named ``dax``.  The MP adapter uses the normal L2 adapter "
+"``submit -> event fd -> query`` contract; no vLLM connector protocol "
+"changes are required."
+msgstr ""
+"在 LMCache 多进程模式下，Device-DAX 被配置为名为 ``dax`` 的内置 L2 适配器。MP 适配器使用正常的 L2 适配器 "
+"``submit -> event fd -> query`` 合同；不需要 vLLM 连接器协议的更改。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:64
+msgid "The legacy single-device ``--l2-adapter`` JSON accepts these fields:"
+msgstr "旧版的单设备 ``--l2-adapter`` JSON 接受以下字段："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:66
+msgid "``device_path``: required path to a readable and writable DAX device."
+msgstr "``device_path``: 必须可读写的 DAX 设备路径。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:67
+msgid ""
+"``max_dax_size_gb``: required mapped size in GiB. The value must fit "
+"within the device capacity when capacity can be determined with "
+"``fstat``."
+msgstr "``max_dax_size_gb``: 必需的映射大小，以 GiB 为单位。当可以通过 ``fstat`` 确定容量时，值必须适合设备容量。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:69
+msgid ""
+"``slot_bytes``: required fixed slot size in bytes. It must be large "
+"enough for one full LMCache chunk."
+msgstr "``slot_bytes``: 所需的固定槽大小（以字节为单位）。它必须足够大，以容纳一个完整的 LMCache 块。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:71
+msgid "``num_store_workers``: optional store worker count, default ``1``."
+msgstr "``num_store_workers``: 可选的存储工作线程数量，默认值为 ``1``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:72
+msgid "``num_lookup_workers``: optional lookup worker count, default ``1``."
+msgstr "``num_lookup_workers``: 可选查找工作线程数量，默认为 ``1``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:73
+msgid ""
+"``num_load_workers``: optional load worker count, default ``min(4, "
+"os.cpu_count())``."
+msgstr "``num_load_workers``: 可选的加载工作线程数量，默认 ``min(4, os.cpu_count())``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:75
+msgid ""
+"``persist_enabled``: accepted by common MP L2 parsing but ignored by "
+"``dax`` in this release."
+msgstr "``persist_enabled``: 被通用 MP L2 解析接受，但在此版本中被 ``dax`` 忽略。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:78
+msgid ""
+"Runtime hotplug uses the multi-device form. The ``devices`` list may also"
+" be empty when ``hotplug_enabled`` is ``true``."
+msgstr "运行时热插拔使用多设备形式。当 ``hotplug_enabled`` 为 ``true`` 时，\\ ``devices`` 列表也可以为空。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:99
+msgid ""
+"MP DAX stores opaque ``ObjectKey`` values in memory and is volatile-only "
+"in this release.  Closing and reopening the server on the same DAX path "
+"starts with an empty index, so previously written bytes are not "
+"discoverable after restart."
+msgstr ""
+"MP DAX 在内存中存储不透明的 ``ObjectKey`` "
+"值，并且在此版本中仅为易失性。关闭并重新打开同一路径上的服务器时，索引将为空，因此之前写入的字节在重启后无法被发现。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:104
+msgid ""
+"MP DAX uses one stable adapter facade per LMCache server.  The facade "
+"owns stable event fds and worker pools, and runtime add/remove/resize "
+"only changes the mapped DAX cores behind that facade.  It does not add "
+"kernel-level CXL or DAX reconfiguration, per-TP DAX partitions, on-device"
+" metadata, or restart recovery. Capacity accounting and eviction are "
+"slot-based: a stored object occupies one slot even if its payload is "
+"smaller than ``slot_bytes``."
+msgstr "MP DAX 每个 LMCache 服务器使用一个稳定的适配器外观。该外观拥有稳定的事件文件描述符和工作池，运行时的添加/删除/调整大小仅更改该外观后面的映射 DAX 核心。它不添加内核级 CXL 或 DAX 重新配置、每个 TP 的 DAX 分区、设备上的元数据或重启恢复。容量核算和逐出基于插槽：即使存储对象的有效负载小于 ``slot_bytes``\\ ，它也占用一个插槽。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:113
+msgid "Runtime Hotplug API"
+msgstr "运行时热插拔 API"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:115
+msgid ""
+"Runtime hotplug is disabled unless ``hotplug_enabled`` is ``true``. The "
+"API changes only LMCache runtime mappings and metadata; the ``/dev/dax*``"
+" device must already exist and be readable and writable by the LMCache "
+"server process. The runtime endpoints are implemented through "
+"StorageManager's generic L2 adapter reconfiguration interface, which "
+"routes backend, operation name, and adapter-specific payload to the "
+"selected adapter. DAX owns the path, mode, migration, and resize "
+"semantics; the generic interface is reusable by other adapters such as "
+"P2P. Use JSON bodies because DAX paths contain slashes:"
+msgstr "运行时热插拔在 ``hotplug_enabled`` 为 ``true`` 时才会启用。该 API 仅更改 LMCache 的运行时映射和元数据；\\ ``/dev/dax*`` 设备必须已经存在，并且 LMCache 服务器进程必须具有可读写权限。运行时端点通过 StorageManager 的通用 L2 适配器重新配置接口实现，该接口将后端、操作名称和适配器特定有效负载路由到所选适配器。DAX 拥有路径、模式、迁移和调整大小的语义；通用接口可被其他适配器（如 P2P）重用。使用 JSON 主体，因为 DAX 路径包含斜杠："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:138
+msgid ""
+"``size`` is required for add and resize. Use an integer byte count or a "
+"string such as ``\"100GiB\"``. ``remove`` supports these modes:"
+msgstr "``size`` 是添加和调整大小所必需的。使用整数字节数或字符串，例如 ``\"100GiB\"``\\ 。\\ ``remove`` 支持以下模式："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:141
+msgid ""
+"``migrate``: move DAX-resident KV to other active DAX devices before "
+"closing the source device."
+msgstr "``migrate``: 在关闭源设备之前，将 DAX 驻留的 KV 移动到其他活动的 DAX 设备。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:143
+msgid ""
+"``evict``: delete DAX-resident KV on the source device. This is "
+"destructive for the DAX tier."
+msgstr "``evict``: 删除源设备上的 DAX 驻留 KV。这对 DAX 层是破坏性的。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:145
+msgid ""
+"``drain``: stop new writes to the source device and leave existing KV "
+"readable until it is evicted or the server closes."
+msgstr "``drain``: 停止对源设备的新写入，并保持现有的 KV 可读，直到被逐出或服务器关闭。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:148
+msgid ""
+"``resize`` supports ``migrate`` and ``evict`` modes. It does not support "
+"``drain`` because resize completes synchronously."
+msgstr "``resize`` 支持 ``migrate`` 和 ``evict`` 模式。它不支持 ``drain``\\ ，因为 resize 是同步完成的。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:151
+msgid ""
+"Hotplug operations are lock-safe by default. A remove or shrink that "
+"would delete externally locked or borrowed slots returns ``409 Conflict``"
+" unless ``force`` is set. A migration that has no active destination "
+"capacity returns ``507 Insufficient Storage``. Resize grow preserves the "
+"in-memory key index and does not move KV payloads. Resize shrink never "
+"silently drops keys; entries outside the new slot range must migrate "
+"first, or the request fails."
+msgstr "热插拔操作默认是安全的。删除或缩小会删除外部锁定或借用的槽位时，除非设置了 ``force``\\ ，否则返回 ``409 Conflict``\\ 。没有活动目标容量的迁移返回 ``507 Insufficient Storage``\\ 。扩展的调整大小保留内存中的键索引，并且不移动 KV 负载。缩小的调整大小绝不会静默丢弃键；新槽范围外的条目必须先迁移，否则请求将失败。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:160
+msgid "Hardware Validation Flow"
+msgstr "硬件验证流程"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:162
+msgid ""
+"Use the same Qwen 8B or 14B long-context workload before and after a "
+"runtime capacity change. Without hotplug support, "
+"``/reconfigure/dax/status`` and ``/reconfigure/dax/add`` are not "
+"available; changing the DAX device set requires restarting LMCache with a"
+" new ``--l2-adapter`` value, which drops the volatile DAX key index."
+msgstr "在运行时容量更改之前和之后使用相同的 Qwen 8B 或 14B 长上下文工作负载。如果没有热插拔支持，\\ ``/reconfigure/dax/status`` 和 ``/reconfigure/dax/add`` 将不可用；更改 DAX 设备集需要使用新的 ``--l2-adapter`` 值重新启动 LMCache，这将丢弃易失性的 DAX 密钥索引。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:181
+msgid "Record these fields for the comparison:"
+msgstr "记录这些字段以进行比较："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:183
+msgid "``total_capacity_bytes`` before and after ``/reconfigure/dax/add``."
+msgstr "``total_capacity_bytes`` 在 ``/reconfigure/dax/add`` 之前和之后。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:184
+msgid "``total_used_bytes`` while the Qwen workload is running."
+msgstr "``total_used_bytes`` 在 Qwen 工作负载运行时。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:185
+msgid "Whether an LMCache restart was required."
+msgstr "是否需要重启 LMCache。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:186
+msgid ""
+"Whether the same cached prompt remains retrievable after the capacity "
+"change."
+msgstr "在容量变化后，是否仍然可以检索到相同的缓存提示。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:190
+msgid "Using The Batched Restore Path"
+msgstr "使用批量恢复路径"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:192
+msgid ""
+"The current DAX optimization is a staged batched restore path for "
+"retrieval. It is enabled automatically whenever the DAX backend is "
+"configured. No extra feature flag is required."
+msgstr "当前的 DAX 优化是一个分阶段的批量恢复路径，用于检索。只要配置了 DAX 后端，它会自动启用。无需额外的功能标志。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:196
+msgid "The retrieve flow is:"
+msgstr "检索流程是："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:198
+msgid "Reserve a batched set of readable DAX chunks."
+msgstr "保留一组可读的 DAX 块。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:199
+msgid "Allocate CPU restore buffers from ``LocalCPUBackend``."
+msgstr "从 ``LocalCPUBackend`` 分配 CPU 恢复缓冲区。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:200
+msgid ""
+"Copy DAX data into a backend-owned pinned staging slab in coalesced "
+"regions."
+msgstr "将 DAX 数据复制到后端拥有的固定暂存块中的合并区域。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:201
+msgid "Copy from the staging slab into the final CPU ``MemoryObj`` outputs."
+msgstr "从暂存块复制到最终的 CPU ``MemoryObj`` 输出。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:202
+msgid "Upload those CPU outputs through the normal GPU connector path."
+msgstr "通过正常的 GPU 连接器路径上传这些 CPU 输出。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:204
+msgid ""
+"The store flow is unchanged: KV data is still staged through CPU memory "
+"before being written into the DAX arena."
+msgstr "存储流程保持不变：KV 数据仍然通过 CPU 内存进行暂存，然后写入 DAX 区域。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:207
+msgid "The new DAX tuning knobs control the batched restore path:"
+msgstr "新的 DAX 调优控制批量恢复路径的旋钮："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:209
+msgid ""
+"``dax.restore_workers``: number of persistent worker threads used to "
+"execute restore regions in parallel."
+msgstr "``dax.restore_workers``: 用于并行执行恢复区域的持久工作线程数量。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:211
+msgid ""
+"``dax.restore_max_regions``: maximum number of restore regions in one "
+"wave. Larger values increase parallelism but also increase slab space "
+"requirements."
+msgstr "``dax.restore_max_regions``: 一次波次中最大恢复区域的数量。较大的值会增加并行性，但也会增加 slab 空间的需求。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:213
+msgid ""
+"``dax.retrieve_staging_slab_bytes``: total size in bytes of the reusable "
+"pinned retrieve slab. This must be large enough to hold one full chunk "
+"per configured restore region."
+msgstr ""
+"``dax.retrieve_staging_slab_bytes``: "
+"可重用的固定检索块的总大小（以字节为单位）。这必须足够大，以容纳每个配置的恢复区域的一个完整块。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:217
+msgid "For a first pass, start with:"
+msgstr "对于第一次尝试，从以下开始："
+
+#: ../../source/kv_cache/storage_backends/dax.rst:219
+msgid ""
+"``dax.restore_workers`` equal to the number of CPU workers you want "
+"devoted to DAX restores"
+msgstr "``dax.restore_workers`` 等于您希望用于 DAX 恢复的 CPU 工作线程数量"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:221
+msgid "``dax.restore_max_regions`` equal to ``dax.restore_workers``"
+msgstr "``dax.restore_max_regions`` 等于 ``dax.restore_workers``"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:222
+msgid ""
+"``dax.retrieve_staging_slab_bytes`` at least ``dax.restore_max_regions * "
+"full_chunk_size``, then scale upward if larger batched restores are "
+"common"
+msgstr "``dax.retrieve_staging_slab_bytes`` 至少为 ``dax.restore_max_regions * full_chunk_size``\\ ，如果批量恢复较大，则向上调整。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:226
+msgid ""
+"If retrieve throughput is low, increase the slab size first, then "
+"increase worker and region counts together. If CPU pressure is high, "
+"reduce ``dax.restore_workers`` and ``dax.restore_max_regions``."
+msgstr "如果提取吞吐量较低，首先增加块大小，然后一起增加工作线程和区域数量。如果 CPU 压力较高，减少 ``dax.restore_workers`` 和 ``dax.restore_max_regions``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:232
+msgid "Runtime Requirements"
+msgstr "运行时要求"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:234
+msgid ""
+"``extra_config['dax.device_path']`` is required and must point to a "
+"readable and writable DAX device."
+msgstr "``extra_config['dax.device_path']`` 是必需的，并且必须指向一个可读写的 DAX 设备。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:236
+msgid ""
+"The process must have read-write access to the DAX device (e.g., via "
+"appropriate permissions or group membership)."
+msgstr "该进程必须对 DAX 设备具有读写访问权限（例如，通过适当的权限或组成员资格）。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:238
+msgid ""
+"``LocalCPUBackend`` must be enabled because DAX reads return CPU-backed "
+"memory objects."
+msgstr "``LocalCPUBackend`` 必须启用，因为 DAX 读取返回的是 CPU 支持的内存对象。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:243
+msgid "Validation and Current Limits"
+msgstr "验证和当前限制"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:245
+msgid ""
+"Tensor parallelism is currently limited to TP=1 (``metadata.world_size =="
+" 1``)."
+msgstr "当前张量并行性仅限于 TP=1 (``metadata.world_size == 1``)。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:247
+msgid ""
+"Only single-tensor chunk layouts are supported. Multi-tensor put requests"
+" are rejected."
+msgstr "仅支持单张量块布局。多张量放置请求将被拒绝。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:249
+msgid ""
+"Batched restore uses a backend-owned retrieve staging slab and persistent"
+" restore executors. The slab and region count can be tuned with "
+"``dax.restore_workers``, ``dax.restore_max_regions``, and "
+"``dax.retrieve_staging_slab_bytes``."
+msgstr "批量恢复使用后端拥有的检索暂存块和持久恢复执行器。可以通过 ``dax.restore_workers``\\ 、\\ ``dax.restore_max_regions`` 和 ``dax.retrieve_staging_slab_bytes`` 调整暂存块和区域数量。"
+
+#: ../../source/kv_cache/storage_backends/dax.rst:253
+msgid ""
+"Blocking batched restore preserves positional output semantics, while "
+"asynchronous batched restore returns only the consecutive hit prefix."
+msgstr "阻塞批量恢复保留了位置输出语义，而异步批量恢复仅返回连续的命中前缀。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/eic.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/eic.po
new file mode 100644
index 0000000..c3566d0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/eic.po
@@ -0,0 +1,85 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:2
+msgid "EIC"
+msgstr "EIC"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "此页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:9
+msgid ""
+"EIC(Elastic Instant Cache) is a distributed database designed for LLM KV "
+"Cache. It supports RDMA, GDR and has the capabilities of distributed "
+"disaster tolerance and expansion. You can understand the principles and "
+"architecture of EIC through these articles:"
+msgstr ""
+"EIC（弹性瞬时缓存）是为 LLM KV Cache 设计的分布式数据库。它支持 "
+"RDMA、GDR，并具备分布式灾难容忍和扩展能力。您可以通过这些文章了解 EIC 的原理和架构："
+
+#: ../../source/kv_cache/storage_backends/eic.rst:12
+msgid "https://mp.weixin.qq.com/s/tasDqXf0Gxr3o_WCJ2IJUQ"
+msgstr "https://mp.weixin.qq.com/s/tasDqXf0Gxr3o_WCJ2IJUQ"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:13
+msgid "https://mp.weixin.qq.com/s/b_4YhTa96Zeklh23lv8qBw"
+msgstr "https://mp.weixin.qq.com/s/b_4YhTa96Zeklh23lv8qBw"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:16
+msgid "Deploy EIC"
+msgstr "部署 EIC"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:18
+msgid ""
+"You can visit the official link https://console.volcengine.com/eic and "
+"deploy EIC KVCache on your compute cluster with web UI. In addition, we "
+"provide particular image in volcano engine, which integrates various "
+"optimizations based on the official image. You may use "
+"tests/v1/storage_backend/test_eic.py to detect the connectivity of EIC."
+msgstr ""
+"您可以访问官方链接 https://console.volcengine.com/eic 并通过 Web UI 在您的计算集群上部署 EIC "
+"KVCache。此外，我们在火山引擎中提供了特定的镜像，该镜像基于官方镜像集成了各种优化。您可以使用 "
+"tests/v1/storage_backend/test_eic.py 来检测 EIC 的连接性。"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:22
+msgid "Deploy Model With EIC"
+msgstr "使用 EIC 部署模型"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:24
+msgid "You can enable EIC KVCache offload with the official interface, such as"
+msgstr "您可以通过官方接口启用 EIC KVCache 卸载，例如"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:35
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/eic.rst:45
+msgid ""
+"For more details, you can see "
+"https://www.volcengine.com/docs/85848/1749188."
+msgstr "有关更多详细信息，请参见 https://www.volcengine.com/docs/85848/1749188。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/fs.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/fs.po
new file mode 100644
index 0000000..5145517
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/fs.po
@@ -0,0 +1,317 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:2
+msgid "Filesystem Backend"
+msgstr "文件系统后端"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/fs`."
+msgstr "此页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/l2_storage/fs`。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:9
+msgid ""
+"The filesystem backend uses ``FSConnector`` to store LMCache remote "
+"chunks as files under one or more POSIX filesystem directories. It is "
+"useful when you want a simple persistent remote backend, or when multiple"
+" inference workers can see the same mounted directory through local disk,"
+" NFS, a parallel filesystem, or a container volume."
+msgstr ""
+"文件系统后端使用 ``FSConnector`` 将 LMCache 远程缓存块存储为一个或多个 POSIX "
+"文件系统目录下的文件。当您需要一个简单的持久远程后端，或者当多个推理进程可以通过本地磁盘、NFS、并行文件系统或容器卷访问同一挂载目录时，它非常有用。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:15
+msgid ""
+"This backend is different from :doc:`local_storage`. Local disk "
+"offloading is a per-process local tier configured through ``local_disk``."
+" ``FSConnector`` is a remote backend configured through "
+"``remote_storage_plugins`` or the legacy ``remote_url`` field, so it "
+"participates in the same remote backend path as Redis, S3, Mooncake, and "
+"other remote connectors."
+msgstr ""
+"该后端与 :doc:`local_storage` 不同。本地磁盘卸载是通过 ``local_disk`` 配置的按进程本地层。\\ "
+"``FSConnector`` 是通过 ``remote_storage_plugins`` 或旧版 ``remote_url`` "
+"字段配置的远程后端，因此它与 Redis、S3、Mooncake 及其他远程连接器共用同一远程后端路径。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:22
+msgid "When to use it"
+msgstr "何时使用它"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:24
+msgid "Use ``FSConnector`` when:"
+msgstr "在以下情况下使用 ``FSConnector``\\ ："
+
+#: ../../source/kv_cache/storage_backends/fs.rst:26
+msgid ""
+"You need a lightweight persistent remote backend for development, "
+"examples, or benchmark runs."
+msgstr "您需要一个轻量级的持久远程后端，用于开发、示例或基准测试。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:28
+msgid "Multiple LMCache or vLLM processes share a mounted cache directory."
+msgstr "多个 LMCache 或 vLLM 进程共享一个挂载的缓存目录。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:29
+msgid ""
+"Your storage is already exposed as a filesystem and does not need a "
+"separate object-store or key-value service."
+msgstr "您的存储已以文件系统形式对外提供，无需额外的对象存储或键值服务。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:31
+msgid ""
+"You want to test remote-backend behavior before moving to a production "
+"backend such as Redis, Valkey, S3, Mooncake, or InfiniStore."
+msgstr "您希望在迁移到生产后端（如 Redis、Valkey、S3、Mooncake 或 InfiniStore）之前测试远程后端的行为。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:34
+msgid "Avoid using it when:"
+msgstr "在以下情况下请避免使用："
+
+#: ../../source/kv_cache/storage_backends/fs.rst:36
+msgid "The filesystem is not shared by every process that must read the cache."
+msgstr "文件系统未被所有需要读取缓存的进程共享。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:37
+msgid ""
+"You need object-store semantics, cross-region persistence, or service-"
+"level access control."
+msgstr "您需要对象存储语义、跨区域持久性或服务级访问控制。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:39
+msgid ""
+"The storage path is on a slow network filesystem and sits on the hot "
+"request path."
+msgstr "存储路径位于慢速网络文件系统上，且处于请求热路径中。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:43
+msgid "Recommended configuration"
+msgstr "推荐配置"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:45
+msgid ""
+"The recommended form is the built-in remote storage plugin configuration."
+" The plugin name ``fs`` selects ``FSConnector`` and the base path is "
+"configured in ``extra_config``."
+msgstr ""
+"推荐方式是使用内置远程存储插件配置。插件名称 ``fs`` 对应 ``FSConnector``\\ ，基础路径在 "
+"``extra_config`` 中配置。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:63
+msgid ""
+"``FSConnector`` creates the base directory if it does not already exist. "
+"Each cache chunk is written as a ``.data`` file whose name is derived "
+"from the LMCache cache key."
+msgstr "``FSConnector`` 会在目录不存在时创建基础目录。每个缓存块作为 ``.data`` 文件写入，其名称源自 LMCache 缓存键。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:68
+msgid "Multiple filesystem instances"
+msgstr "多个文件系统实例"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:70
+msgid ""
+"You can configure multiple named ``fs`` instances by appending an "
+"instance name after the connector type. The part before the first dot is "
+"still the connector type; the full plugin name becomes the "
+"``extra_config`` prefix."
+msgstr ""
+"您可以通过在连接器类型后附加实例名称来配置多个命名的 ``fs`` 实例。在第一个点之前的部分仍然是连接器类型；完整的插件名称成为 "
+"``extra_config`` 前缀。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:82
+msgid ""
+"This is useful when a deployment wants separate filesystem-backed remote "
+"stores for different cache policies, traffic classes, or experiments."
+msgstr "当一个部署希望为不同的缓存策略、流量类别或实验提供独立的基于文件系统的远程存储时，这非常有用。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:86
+msgid "Multiple base paths"
+msgstr "多个基础路径"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:88
+msgid ""
+"``remote_storage_plugin.<name>.base_path`` may contain a comma-separated "
+"list of directories. The connector chooses a directory by hashing the "
+"cache chunk key, which spreads files across the configured paths."
+msgstr ""
+"``remote_storage_plugin.<name>.base_path`` "
+"可以包含一个以逗号分隔的目录列表。连接器通过对缓存块键进行哈希来选择一个目录，从而将文件分散到配置的路径中。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:99
+msgid ""
+"Use multiple paths when each path maps to an independent storage device "
+"or mount point. For best results, keep every path visible to the LMCache "
+"processes that need to retrieve the same chunks."
+msgstr "当每个路径映射到独立的存储设备或挂载点时，请使用多个路径。为了获得最佳效果，请确保每个路径对需要检索相同块的 LMCache 进程可见。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:104
+msgid "Legacy ``remote_url`` configuration"
+msgstr "旧版 ``remote_url`` 配置"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:106
+msgid ""
+"The legacy ``remote_url`` form is still supported. The host and port are "
+"parsed for compatibility with other remote URL formats; ``FSConnector`` "
+"uses the path."
+msgstr ""
+"旧版 ``remote_url`` 形式仍受支持。主机和端口会被解析以兼容其他远程 URL 格式；\\ ``FSConnector`` "
+"实际只使用其中的路径部分。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:121
+msgid ""
+"Prefer ``remote_storage_plugins`` for new deployments because it also "
+"supports named instances and keeps connector-specific settings grouped by"
+" plugin name."
+msgstr ""
+"对于新部署，建议优先使用 ``remote_storage_plugins``\\ "
+"，因为它支持命名实例，并可按插件名称对连接器专属配置进行分组管理。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:125
+msgid "Optional settings"
+msgstr "可选设置"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:127
+msgid "The connector reads the following optional settings from ``extra_config``."
+msgstr "连接器从 ``extra_config`` 中读取以下可选设置。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:129
+msgid "``fs_connector_relative_tmp_dir``"
+msgstr "``fs_connector_relative_tmp_dir``"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:130
+msgid ""
+"Relative directory used for temporary files before an atomic rename into "
+"the final chunk path. The value must be relative, not absolute. When "
+"omitted, temporary files are created next to the final file with a "
+"``.tmp`` suffix."
+msgstr ""
+"用于在原子重命名到最终块路径之前存放临时文件的相对目录。该值必须是相对的，而不是绝对的。当省略时，临时文件会在最终文件旁边创建，并带有 "
+"``.tmp`` 后缀。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:134
+msgid "``fs_connector_read_ahead_size``"
+msgstr "``fs_connector_read_ahead_size``"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:135
+msgid ""
+"Number of bytes to read first when loading a chunk. If the read fills "
+"that window, the connector reads the remaining bytes. This can trigger "
+"filesystem readahead on filesystems that support it."
+msgstr "加载缓存块时首次读取的字节数。若读取填满了该窗口，连接器将继续读取剩余字节。在支持预读的文件系统上，此选项可触发文件系统级预读。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:139
+msgid "``fs_connector_use_odirect``"
+msgstr "``fs_connector_use_odirect``"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:140
+msgid ""
+"Enables ``O_DIRECT`` for aligned reads and writes on platforms that "
+"expose it. The connector falls back to normal I/O when a chunk size is "
+"not aligned to the filesystem block size. ``O_DIRECT`` is disabled "
+"automatically when ``save_chunk_meta`` is enabled because the metadata "
+"prefix is not block aligned."
+msgstr ""
+"在支持的平台上启用 ``O_DIRECT`` 以执行对齐读写。当缓存块大小未对齐到文件系统块大小时，连接器将回退到普通 I/O。启用 "
+"``save_chunk_meta`` 后，\\ ``O_DIRECT`` 会自动关闭，因为元数据前缀不满足块对齐要求。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:146
+msgid "``fs_base_path``"
+msgstr "``fs_base_path``"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:147
+msgid ""
+"Compatibility fallback for plugin mode. Prefer "
+"``remote_storage_plugin.<name>.base_path`` so the setting remains scoped "
+"to a specific plugin instance."
+msgstr ""
+"插件模式的兼容性回退选项。建议优先使用 ``remote_storage_plugin.<name>.base_path``\\ "
+"，以将配置范围限定到特定插件实例。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:151
+msgid "Example with optional settings:"
+msgstr "带可选设置的示例："
+
+#: ../../source/kv_cache/storage_backends/fs.rst:164
+msgid "Operational notes"
+msgstr "操作说明"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:166
+msgid ""
+"Ensure the LMCache process has permission to create directories and write"
+" files under every configured base path."
+msgstr "确保 LMCache 进程有权限在每个配置的基础路径下创建目录和写入文件。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:168
+msgid ""
+"Put the path on durable storage if cache reuse must survive process "
+"restarts. Temporary directories such as ``/tmp`` are convenient for tests"
+" but may be cleaned by the operating system."
+msgstr "若缓存需要在进程重启后仍可复用，请将路径配置在持久存储上。\\ ``/tmp`` 等临时目录便于测试使用，但可能会被操作系统自动清理。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:171
+msgid ""
+"Use the same mounted path for every process that should share cache "
+"chunks. If one process writes to a private container path, other "
+"processes will miss those chunks even if they use the same configuration "
+"text."
+msgstr "所有需要共享缓存块的进程必须使用相同的挂载路径。若某个进程写入的是私有容器路径，其他进程将无法命中这些缓存块，即使它们使用完全相同的配置。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:174
+msgid ""
+"Leave ``save_chunk_meta`` enabled when workers may infer different "
+"metadata for the same chunk. Disable it only when you need the lower "
+"overhead path and the workers share compatible cache metadata."
+msgstr ""
+"当工作进程可能对相同缓存块推断出不同元数据时，请保持 ``save_chunk_meta`` "
+"启用。仅当您需要降低额外开销且各工作进程共享兼容的缓存元数据时，才可将其禁用。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:177
+msgid ""
+"For MP mode L2 storage, see :doc:`../../mp/l2_storage/index`, which "
+"documents the ``fs`` and ``fs_native`` L2 adapters configured through "
+"``--l2-adapter``."
+msgstr ""
+"有关 MP 模式 L2 存储，请参见 :doc:`../../mp/l2_storage/index`，该文档介绍了通过 "
+"``--l2-adapter`` 配置的 ``fs`` 和 ``fs_native`` L2 适配器。"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:181
+msgid "Minimal vLLM usage"
+msgstr "最简 vLLM 使用示例"
+
+#: ../../source/kv_cache/storage_backends/fs.rst:183
+msgid ""
+"After writing ``fs.yaml`` with one of the configurations above, start "
+"vLLM with LMCache enabled:"
+msgstr "使用上述任一配置编写 ``fs.yaml`` 后，以 LMCache 模式启动 vLLM："
+
+#: ../../source/kv_cache/storage_backends/fs.rst:192
+msgid ""
+"Then send the same long-prefix request twice. The first request stores "
+"chunks in the filesystem backend. The second request should report "
+"LMCache hit tokens and load matching chunks from the configured "
+"filesystem path."
+msgstr ""
+"然后发送相同的长前缀请求两次。第一次请求会将缓存块写入文件系统后端。第二次请求应报告 LMCache 命中的 token "
+"数，并从配置的文件系统路径加载匹配的缓存块。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/gds.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/gds.po
new file mode 100644
index 0000000..bfeb299
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/gds.po
@@ -0,0 +1,369 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:2
+msgid "GDS Backend"
+msgstr "GDS 后端"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:14
+msgid ""
+"This backend will work with any file system, whether local, remote, and "
+"remote with GDS-based optimizations. Remote file systems allow for "
+"multiple LMCache instances to share data seamlessly. The GDS (GPU-Direct "
+"Storage) optimizations are used for zero-copy I/O from GPU memory to "
+"storage systems. Supports both NVIDIA cuFile and AMD hipFile for GPU-"
+"direct storage."
+msgstr ""
+"该后端可以与任何文件系统配合使用，无论是本地的、远程的，还是带有基于 GDS 的优化的远程文件系统。远程文件系统允许多个 LMCache "
+"实例无缝共享数据。GDS（GPU-Direct Storage）优化用于实现从显存到存储系统的零拷贝 I/O。支持 NVIDIA cuFile 和"
+" AMD hipFile 进行 GPU 直接存储。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:22
+msgid "Ways to configure LMCache GDS Backend"
+msgstr "配置 LMCache GDS 后端的方法"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:24
+msgid "**1. Environment Variables:**"
+msgstr "**1. 环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:38
+msgid "**2. Configuration File**:"
+msgstr "**2. 配置文件**:"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:40
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:42
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:57
+msgid "Multi-Path (Multi-Device) Support"
+msgstr "多路径（多设备）支持"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:59
+msgid ""
+"When a system has multiple NVMe drives, you can distribute GDS I/O across"
+" them by specifying a comma-separated list of paths in ``gds_path``. The "
+"``gds_path_sharding`` option controls how each GPU worker selects its "
+"path. Currently only ``\"by_gpu\"`` is supported (the default), which "
+"selects a path based on the device index (``device_id % num_paths``), so "
+"traffic is spread evenly across the drives without any manual pinning."
+msgstr ""
+"当系统有多个 NVMe 驱动器时，可以通过在 ``gds_path`` 中指定以逗号分隔的路径列表来分配 GDS I/O。\\ "
+"``gds_path_sharding`` 选项控制每个 GPU 工作线程如何选择其路径。目前仅支持 ``\"by_gpu\"``\\ "
+"（默认），该选项根据设备索引（\\ ``device_id % num_paths``\\ "
+"）选择路径，因此流量在驱动器之间均匀分配，无需手动固定。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:66
+msgid ""
+"**Why this helps:** a single PCIe Gen 4 x4 NVMe tops out at ~7 GB/s. With"
+" four drives the aggregate bandwidth can reach ~28 GB/s, matching what "
+"multi-GPU systems need for KV cache eviction and prefetch."
+msgstr ""
+"**为什么这有帮助：** 单个 PCIe Gen 4 x4 NVMe 的最大速度约为 7 GB/s。使用四个驱动器时，聚合带宽可以达到约 28 "
+"GB/s，满足多 GPU 系统对 KV Cache 逐出和预取的需求。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:70
+msgid "**Environment variables:**"
+msgstr "**环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:77
+msgid "**YAML config:**"
+msgstr "**YAML 配置：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:84
+msgid "With the above configuration on a 4-GPU node:"
+msgstr "在 4-GPU 节点上使用上述配置："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:86
+msgid "``cuda:0`` writes to ``/mnt/nvme0/cache``"
+msgstr "``cuda:0`` 写入 ``/mnt/nvme0/cache``"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:87
+msgid "``cuda:1`` writes to ``/mnt/nvme1/cache``"
+msgstr "``cuda:1`` 写入 ``/mnt/nvme1/cache``"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:88
+msgid "``cuda:2`` writes to ``/mnt/nvme2/cache``"
+msgstr "``cuda:2`` 写入 ``/mnt/nvme2/cache``"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:89
+msgid "``cuda:3`` writes to ``/mnt/nvme3/cache``"
+msgstr "``cuda:3`` 写入 ``/mnt/nvme3/cache``"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:91
+msgid ""
+"If there are more GPUs than paths, the assignment wraps around (e.g. "
+"``cuda:4`` maps back to ``/mnt/nvme0/cache``). A single path (no commas) "
+"works exactly as before."
+msgstr ""
+"如果 GPU 的数量超过路径数量，则分配会循环（例如，\\ ``cuda:4`` 映射回 ``/mnt/nvme0/cache``\\ "
+"）。单个路径（没有逗号）与之前的工作方式完全相同。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:95
+msgid ""
+"All directories are created automatically at startup. Every path in the "
+"list must reside on a filesystem that the rest of the GDS configuration "
+"expects (e.g., all paths on GDS-capable mounts when using cuFile)."
+msgstr ""
+"所有目录在启动时会自动创建。列表中的每个路径必须位于 GDS 配置所期望的文件系统上（例如，在使用 cuFile 时，所有路径都必须位于支持 "
+"GDS 的挂载点上）。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:99
+msgid ""
+"**Read behavior:** on startup the backend scans **all** configured paths "
+"for previously-stored KV cache entries, regardless of GPU affinity.  This"
+" means a ``cuda:0`` worker whose write affinity is ``/mnt/nvme0/cache`` "
+"will still discover entries that were written to ``/mnt/nvme1/cache`` by "
+"``cuda:1`` in a prior run.  Writes, however, always go to the single "
+"affinity-selected path."
+msgstr ""
+"**读取行为：** 在启动时，后端会扫描 **所有** 配置的路径以查找先前存储的 KV Cache 条目，而不考虑 GPU "
+"亲和性。这意味着一个写入亲和性为 ``/mnt/nvme0/cache`` 的 ``cuda:0`` 工作线程仍然会发现之前由 "
+"``cuda:1`` 写入到 ``/mnt/nvme1/cache`` 的条目。然而，写入始终会发送到单个亲和性选择的路径。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:115
+msgid "GDS Buffer Size Explanation"
+msgstr "GDS 缓冲区大小说明"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:117
+msgid ""
+"The backend currently pre-registers buffer space to speed up GDS "
+"operations. This buffer space is registered in VRAM so options like "
+"``--gpu-memory-utilization`` from ``vllm`` should be considered when "
+"setting it. For example, a good rule of thumb for H100 which generally "
+"has 80GiBs of VRAM would be to start with 8GiB and set ``--gpu-memory-"
+"utilization 0.85`` and depending on your workflow fine-tune it from "
+"there."
+msgstr ""
+"后端目前预先注册缓冲区空间以加速 GDS 操作。此缓冲区空间在显存中注册，因此在设置时应考虑 ``--gpu-memory-"
+"utilization`` 选项，例如来自 ``vllm`` 的选项。例如，对于通常具有 80GiB 显存的 H100，一个好的经验法则是从 "
+"8GiB 开始，并设置 ``--gpu-memory-utilization 0.85``，然后根据您的工作流程进行微调。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:125
+msgid "Using AMD hipFile"
+msgstr "使用 AMD hipFile"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:129
+msgid ""
+"hipFile is alpha software and has been tested on limited hardware. For "
+"full installation details, see the `hipFile install guide "
+"<https://github.com/ROCm/rocm-"
+"systems/blob/develop/projects/hipfile/INSTALL.md>`__."
+msgstr ""
+"hipFile 是 alpha 版软件，仅在有限的硬件上进行了测试。有关完整的安装细节，请参见 `hipFile 安装指南 "
+"<https://github.com/ROCm/rocm-"
+"systems/blob/develop/projects/hipfile/INSTALL.md>`__。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:133
+#: ../../source/kv_cache/storage_backends/gds.rst:184
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:135
+msgid ""
+"**ROCm >= 7.2** with ``amdgpu-dkms >= 30.20.1`` (see the `ROCm quick "
+"start installation guide <https://rocm.docs.amd.com/projects/install-on-"
+"linux/en/latest/install/quick-start.html>`__)"
+msgstr ""
+"**ROCm >= 7.2** 和 ``amdgpu-dkms >= 30.20.1`` （请参阅 `ROCm 快速安装指南 "
+"<https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install"
+"/quick-start.html>`__）"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:137
+msgid "**Supported storage:** local NVMe drives only"
+msgstr "**支持的存储：** 仅限本地 NVMe 驱动器"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:138
+msgid "**Supported filesystems:** ext4 (mounted with ``data=ordered``) and xfs"
+msgstr "**支持的文件系统：** ext4（以 ``data=ordered`` 挂载）和 xfs"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:139
+msgid "**Kernel:** ``CONFIG_PCI_P2PDMA`` must be enabled"
+msgstr "**内核：** ``CONFIG_PCI_P2PDMA`` 必须启用"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:141
+msgid "**Quick install (Ubuntu 24.04):**"
+msgstr "**快速安装（Ubuntu 24.04）：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:152
+msgid ""
+"You can verify that the HIP libraries and kernel support AIS (AMD "
+"Infinity Storage) by running:"
+msgstr "您可以通过运行以下命令来验证 HIP 库和内核是否支持 AIS（AMD Infinity Storage）："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:158
+msgid ""
+"Successful output will show ``True`` for ``Kernel P2PDMA support``, ``HIP"
+" runtime``, and ``amdgpu``."
+msgstr ""
+"成功的输出将显示 ``Kernel P2PDMA support``\\ 、\\ ``HIP runtime`` 和 ``amdgpu`` 的值为"
+" ``True``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:160
+msgid "**LMCache configuration:**"
+msgstr "**LMCache 配置：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:162
+msgid "To use AMD hipFile instead of NVIDIA cuFile, set the GDS backend:"
+msgstr "要使用 AMD hipFile 而不是 NVIDIA cuFile，请设置 GDS 后端："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:164
+msgid "**Environment Variables:**"
+msgstr "**环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:170
+msgid "**Configuration File:**"
+msgstr "**配置文件：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:176
+msgid ""
+"Note: The ``gds_buffer_size`` configuration is used for both cuFile and "
+"hipFile buffers."
+msgstr "注意：\\ ``gds_buffer_size`` 配置用于 cuFile 和 hipFile 缓冲区。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:180
+msgid "Setup Example"
+msgstr "设置示例"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:186
+msgid ""
+"A Machine with at least one GPU. You can adjust the max model length of "
+"your vllm instance depending on your GPU memory."
+msgstr "一台至少配备一个 GPU 的机器。您可以根据您的显存调整 vllm 实例的最大模型长度。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:188
+msgid "A mounted file system. A file system supportings GDS will work best."
+msgstr "一个挂载的文件系统。支持 GDS 的文件系统效果最佳。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:190
+msgid ""
+"vllm and lmcache installed (:doc:`Installation Guide "
+"<../../getting_started/installation>`)"
+msgstr "vllm 和 lmcache 已安装 (:doc:`安装指南 <../../getting_started/installation>`)"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:192
+msgid "Hugging Face access to ``meta-llama/Llama-3.1-8B-Instruct``"
+msgstr "Hugging Face 访问 ``meta-llama/Llama-3.1-8B-Instruct``"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:198
+msgid "**Step 1. Create cache directory under your file system mount:**"
+msgstr "**步骤 1. 在您的文件系统挂载下创建缓存目录：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:200
+msgid ""
+"To find all the types of file systems supporting GDS in your system, use "
+"`gdscheck` from NVIDIA:"
+msgstr "要查找系统中支持 GDS 的所有文件系统类型，请使用 NVIDIA 的 `gdscheck`："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:206
+msgid "Check with your storage vendor on how to mount the remote file system."
+msgstr "请向您的存储供应商咨询如何挂载远程文件系统。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:208
+msgid ""
+"(For example, if you want to use a GDS-enabled NFS driver, try the "
+"modified [NFS stack](https://vastnfs.vastdata.com/), which is an open "
+"source driver that works with any standard [NFS "
+"RDMA](https://datatracker.ietf.org/doc/html/rfc5532) server. More vendor-"
+"specific instructions will be added here in the future)."
+msgstr ""
+"（例如，如果您想使用支持 GDS 的 NFS 驱动程序，可以尝试修改过的 [NFS "
+"stack](https://vastnfs.vastdata.com/)，这是一个与任何标准 [NFS "
+"RDMA](https://datatracker.ietf.org/doc/html/rfc5532) "
+"服务器兼容的开源驱动程序。将来会在这里添加更多特定于供应商的说明。）"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:214
+msgid ""
+"Create a directory under the file systew mount (the name here is "
+"arbitrary):"
+msgstr "在文件系统挂载下创建一个目录（这里的名称是任意的）："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:220
+msgid "**Step 2. Start a vLLM server with file backend enabled:**"
+msgstr "**步骤 2. 启动一个启用文件后端的 vLLM 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:222
+msgid "Create a an lmcache configuration file called: ``gds-backend.yaml``"
+msgstr "创建一个名为 ``gds-backend.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:231
+msgid ""
+"If you don't want to use a config file, uncomment the first three "
+"environment variables and then comment out the ``LMCACHE_CONFIG_FILE`` "
+"below:"
+msgstr "如果您不想使用配置文件，请取消注释前面三个环境变量，然后注释掉下面的 ``LMCACHE_CONFIG_FILE``："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:249
+msgid "POSIX fallback"
+msgstr "POSIX 回退"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:251
+msgid ""
+"In some cases, libcufile implements its own internal POSIX fallback "
+"without `GdsBackend` being aware. In others, an error such as "
+"`RuntimeError: cuFileHandleRegister failed (cuFile err=5030, cuda_err=0)`"
+" may be throwned. Thus, backend can be configured to fallback to its own "
+"POSIX implementation when the usage of the GDS APIs is not successful."
+msgstr ""
+"在某些情况下，libcufile 实现了自己的内部 POSIX 回退，而 `GdsBackend` 并不知情。在其他情况下，可能会抛出类似 "
+"`RuntimeError: cuFileHandleRegister failed (cuFile err=5030, cuda_err=0)`"
+" 的错误。因此，当 GDS API 的使用不成功时，可以配置后端回退到其自己的 POSIX 实现。"
+
+#: ../../source/kv_cache/storage_backends/gds.rst:255
+msgid ""
+"To force `GdsBackend` not use GDS APIs for any reason, you can override "
+"its behavior via configuration:"
+msgstr "要强制 `GdsBackend` 在任何情况下都不使用 GDS API，您可以通过配置覆盖其行为："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:261
+msgid "Or via environment variable:"
+msgstr "或者通过环境变量："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:267
+msgid ""
+"The ``gds_backend`` field (default: ``cufile``) selects which GDS library"
+" to use. Supported backends are ``cufile`` (NVIDIA cuFile) and "
+"``hipfile`` (AMD hipFile):"
+msgstr ""
+"``gds_backend`` 字段（默认值：\\ ``cufile``\\ ）用于选择使用哪个 GDS 库。支持的后端有 "
+"``cufile``\\ （NVIDIA cuFile）和 ``hipfile``\\ （AMD hipFile）："
+
+#: ../../source/kv_cache/storage_backends/gds.rst:275
+msgid ""
+"Note that under this mode it would still use CUDA APIs to map and do "
+"operations the pre-registered GPU memory."
+msgstr "请注意，在此模式下，它仍将使用 CUDA API 来映射和操作预注册的显存。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/hfbucket.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/hfbucket.po
new file mode 100644
index 0000000..6ff6e3d
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/hfbucket.po
@@ -0,0 +1,297 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-15 11:17+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:2
+msgid "Hugging Face Buckets Backend"
+msgstr "Hugging Face Buckets 后端"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:4
+msgid ""
+"The Hugging Face Buckets backend stores LMCache chunks in a Hugging Face "
+"Bucket using LMCache's built-in remote storage plugin framework. This is "
+"a persistent remote backend that fits warm and cold KV cache persistence "
+"better than the hottest local tiers."
+msgstr ""
+"Hugging Face Buckets 后端使用 LMCache 内置的远程存储插件框架，将 LMCache 块存储在 Hugging Face"
+" Bucket 中。这是一个持久的远程后端，适合于温暖和冷却的 KV Cache 持久化，而不是最热的本地层。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:10
+msgid "When to use it"
+msgstr "何时使用它"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:12
+msgid "Use the HFBucket backend when you want:"
+msgstr "当您想要时，请使用 HFBucket 后端："
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:14
+msgid "A Hub-native persistent store for KV cache data."
+msgstr "一个 Hub 原生的持久存储，用于 KV Cache 数据。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:15
+msgid ""
+"A remote backend that can be configured through "
+"``remote_storage_plugins``."
+msgstr "一个可以通过 ``remote_storage_plugins`` 配置的远程后端。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:16
+msgid "Multiple named bucket instances in one LMCache deployment."
+msgstr "在一个 LMCache 部署中有多个命名的桶实例。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:18
+msgid ""
+"Avoid using it as the primary hot path for the lowest-latency cache "
+"lookups. Local CPU, local disk, and other lower-latency backends are a "
+"better fit for the hottest cache tier."
+msgstr "避免将其用作最低延迟缓存查找的主要热路径。本地 CPU、本地磁盘和其他低延迟后端更适合最热门的缓存层。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:24
+msgid "Requirements and limitations"
+msgstr "要求和限制"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:26
+msgid ""
+"LMCache uses ``huggingface_hub`` bucket APIs for uploads, downloads, "
+"listing, and deletes."
+msgstr "LMCache 使用 ``huggingface_hub`` 存储桶 API 进行上传、下载、列出和删除操作。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:28
+msgid "The first built-in release is intentionally conservative:"
+msgstr "首次内置版本故意采取保守态度："
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:30
+msgid "Only full chunks are supported."
+msgstr "仅支持完整块。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:31
+msgid "Partial chunk uploads are rejected."
+msgstr "部分块上传被拒绝。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:32
+msgid ""
+"Downloads are rejected when the stored object size does not match the "
+"expected full LMCache chunk size."
+msgstr "当存储的对象大小与预期的完整 LMCache 块大小不匹配时，下载将被拒绝。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:34
+msgid "Chunk metadata is not stored in the bucket objects."
+msgstr "块元数据未存储在桶对象中。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:38
+msgid "Minimal configuration"
+msgstr "最小配置"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:57
+msgid "Multiple instances"
+msgstr "多个实例"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:59
+msgid ""
+"Use instance-qualified plugin names to configure more than one bucket-"
+"backed remote store in the same LMCache config."
+msgstr "使用实例限定的插件名称来配置同一 LMCache 配置中的多个基于桶的远程存储。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:73
+msgid "Configuration reference"
+msgstr "配置参考"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:75
+msgid ""
+"All configuration keys live under "
+"``extra_config.remote_storage_plugin.<plugin_name>.*`` where "
+"``plugin_name`` is either ``hfbucket`` or an instance-qualified name such"
+" as ``hfbucket.prod``."
+msgstr "所有配置键都位于 ``extra_config.remote_storage_plugin.<plugin_name>.*`` 下，其中 ``plugin_name`` 可以是 ``hfbucket`` 或者实例限定名称，例如 ``hfbucket.prod``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:79
+msgid ""
+"``bucket_handle`` (required): Hugging Face Bucket handle in "
+"``hf://buckets/<namespace>/<bucket>[/<prefix>]`` format."
+msgstr "``bucket_handle``\\ （必需）：Hugging Face Bucket 句柄，格式为 ``hf://buckets/<namespace>/<bucket>[/<prefix>]``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:81
+msgid ""
+"``token_env`` (optional, default ``HF_TOKEN``): Environment variable used"
+" to resolve the Hugging Face access token."
+msgstr "``token_env``\\ （可选，默认 ``HF_TOKEN``\\ ）：用于解析 Hugging Face 访问令牌的环境变量。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:83
+msgid ""
+"``token`` (optional): Direct token override. ``token_env`` takes "
+"precedence when both are set."
+msgstr "``token``\\ （可选）：直接的令牌覆盖。当两者都设置时，\\ ``token_env`` 优先。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:85
+msgid ""
+"``create_bucket_if_missing`` (optional, default ``false``): Lazily create"
+" the bucket on the first write path."
+msgstr "``create_bucket_if_missing`` (可选，默认 ``false``)：在第一次写入路径时延迟创建存储桶。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:87
+msgid ""
+"``download_tmp_dir`` (optional): Root directory for connector-local "
+"download scratch space. On Linux, pointing this at a tmpfs mount such as "
+"``/dev/shm/lmcache-hfbucket`` avoids the disk write on the download path."
+msgstr "``download_tmp_dir`` (可选): 连接器本地下载临时空间的根目录。在 Linux 上，将其指向 tmpfs 挂载，例如 ``/dev/shm/lmcache-hfbucket``\\ ，可以避免下载路径上的磁盘写入。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:90
+msgid ""
+"``metadata_cache_ttl_secs`` (optional, default ``30``): TTL for cached "
+"exact existence and size metadata."
+msgstr "``metadata_cache_ttl_secs``\\ （可选，默认值为 ``30``\\ ）：缓存确切存在性和大小元数据的生存时间（TTL）。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:95
+msgid "MP Mode Configuration"
+msgstr "MP 模式配置"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:97
+msgid ""
+"In multi-process (MP) mode, Hugging Face Buckets are configured as an L2 "
+"adapter through a JSON spec passed to the LMCache server. This is "
+"separate from the non-MP ``remote_storage_plugins`` configuration above. "
+"Each ``--l2-adapter`` argument takes a JSON object whose ``\"type\": "
+"\"hfbucket\"`` field selects the HFBucket adapter."
+msgstr "在多进程（MP）模式下，Hugging Face Buckets 通过传递给 LMCache 服务器的 JSON 规范配置为 L2 适配器。这与上面的非 MP ``remote_storage_plugins`` 配置是分开的。每个 ``--l2-adapter`` 参数接受一个 JSON 对象，其 ``\\\"type\\\": \\\"hfbucket\\\"`` 字段选择 HFBucket 适配器。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:122
+msgid "HFBucket L2 Adapter Fields"
+msgstr "HFBucket L2 适配器字段"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:124
+msgid "**type** (required): must be ``\"hfbucket\"``."
+msgstr "**类型**\\ （必需）：必须是 ``\"hfbucket\"``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:125
+msgid ""
+"**bucket_handle** (required): Hugging Face Bucket handle in "
+"``hf://buckets/<namespace>/<bucket>[/<prefix>]`` format."
+msgstr "**bucket_handle**\\ （必需）：Hugging Face Bucket 句柄，格式为 ``hf://buckets/<namespace>/<bucket>[/<prefix>]``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:127
+msgid ""
+"**token_env**: environment variable used to resolve the Hugging Face "
+"access token (default ``\"HF_TOKEN\"``)."
+msgstr "``token_env``\\ ：用于解析 Hugging Face 访问令牌的环境变量（默认 ``\"HF_TOKEN\"``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:129
+msgid ""
+"**token**: optional direct token fallback. ``token_env`` takes precedence"
+" when the environment variable is set. Prefer ``token_env`` for "
+"production deployments so secrets do not live in adapter JSON."
+msgstr "``token``\\ （可选，直接的令牌回退。当环境变量设置时，\\ ``token_env`` 优先。对于生产部署，建议使用 ``token_env`` 以避免在适配器 JSON 中存储秘密。）"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:132
+msgid ""
+"**create_bucket_if_missing**: lazily create the bucket on the first store"
+" operation (default ``false``). This only helps when the bucket is "
+"missing and the token has permission to create it; it does not fix "
+"invalid credentials, invalid handles, or network failures."
+msgstr "**create_bucket_if_missing**: 在第一次存储操作时懒惰地创建存储桶（默认值为 ``false``\\ ）。这仅在存储桶缺失且令牌有权限创建时有效；它无法修复无效的凭据、无效的句柄或网络故障。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:136
+msgid ""
+"**download_tmp_dir**: root directory for temporary load downloads "
+"(default ``/tmp/lmcache-hfbucket-mp``). The MP adapter downloads bucket "
+"files into per-task temporary files and then copies their bytes into the "
+"destination ``MemoryObj`` buffers supplied by the MP controller."
+msgstr "**download_tmp_dir**: 临时加载下载的根目录（默认 ``/tmp/lmcache-hfbucket-mp``\\ ）。MP 适配器将桶文件下载到每个任务的临时文件中，然后将其字节复制到 MP 控制器提供的目标 ``MemoryObj`` 缓冲区中。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:140
+msgid ""
+"**metadata_cache_ttl_secs**: TTL for cached exact path-size metadata "
+"(default ``30``). Set this lower when another process may modify the same"
+" bucket prefix outside LMCache and fresher metadata is more important "
+"than reducing Hugging Face metadata calls."
+msgstr "**metadata_cache_ttl_secs**: 缓存的确切路径大小元数据的 TTL（默认 ``30``\\ ）。当其他进程可能在 LMCache 之外修改同一存储桶前缀时，将此值设置得更低，以便更新的元数据比减少 Hugging Face 元数据调用更为重要。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:144
+msgid ""
+"**num_workers**: number of worker threads used for blocking Hugging Face "
+"Hub bucket API calls (default ``4``). The HFBucket Python APIs are "
+"synchronous, so MP mode runs upload, lookup, load, and delete work on a "
+"bounded thread pool behind the adapter's eventfd-based completion "
+"interface."
+msgstr "**num_workers**: 用于阻塞 Hugging Face Hub 存储桶 API 调用的工作线程数量（默认 ``4``\\ ）。HFBucket Python API 是同步的，因此 MP 模式在适配器的基于 eventfd 的完成接口后面运行上传、查找、加载和删除工作，使用有限的线程池。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:148
+msgid ""
+"**max_capacity_gb**: capacity used by ``get_usage()`` for watermark-based"
+" L2 eviction. Set to ``0`` (default) to disable aggregate capacity "
+"tracking; ``get_usage()`` then reports the adapter as not providing an "
+"eviction signal."
+msgstr "**max_capacity_gb**: ``get_usage()`` 用于基于水印的 L2 逐出的容量。设置为 ``0``\\ （默认）以禁用聚合容量跟踪；此时 ``get_usage()`` 报告适配器未提供逐出信号。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:151
+msgid ""
+"**eviction**: optional sub-dict enabling the L2 eviction controller for "
+"this adapter. When present, keys that are currently being loaded are "
+"protected by the lookup-and-lock path and skipped by ``delete()`` until "
+"they are unlocked."
+msgstr "**逐出**: 可选的子字典，用于为此适配器启用 L2 逐出控制器。当存在时，当前正在加载的键会通过查找和锁定路径受到保护，并在解锁之前被 ``delete()`` 跳过。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:156
+msgid "Differences vs Non-MP HFBucket"
+msgstr "与非多租户 HFBucket 的区别"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:158
+msgid ""
+"Hugging Face bucket operations are synchronous but the adapter makes "
+"submission non-blocking by running the blocking calls on worker threads."
+msgstr "Hugging Face 桶操作是同步的，但适配器通过在工作线程上运行阻塞调用使提交变为非阻塞。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:160
+msgid ""
+"MP loads do not allocate and return new memory. The MP controller "
+"provides destination ``MemoryObj`` buffers, and the adapter copies "
+"downloaded bytes into those buffers."
+msgstr "MP 加载不会分配和返回新的内存。MP 控制器提供目标 ``MemoryObj`` 缓冲区，适配器将下载的字节复制到这些缓冲区中。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:163
+msgid ""
+"Keys are identified by ``ObjectKey`` (``model_name`` + ``kv_rank`` + "
+"``chunk_hash`` + optional ``cache_salt``) rather than ``CacheEngineKey``."
+" The serialized MP object name is "
+"``<model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]`` and is then "
+"encoded for the bucket path. This naming is not compatible with the non-"
+"MP HFBucket connector's ``CacheEngineKey`` object names, so a bucket "
+"prefix populated by non-MP LMCache cannot be read directly by MP LMCache "
+"and vice versa."
+msgstr "键通过 ``ObjectKey`` (``model_name`` + ``kv_rank`` + ``chunk_hash`` + 可选的 ``cache_salt``) 来识别，而不是 ``CacheEngineKey``\\ 。序列化的 MP 对象名称为 ``<model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]``\\ ，然后对其进行编码以形成桶路径。此命名与非 MP HFBucket 连接器的 ``CacheEngineKey`` 对象名称不兼容，因此由非 MP LMCache 填充的桶前缀不能被 MP LMCache 直接读取，反之亦然。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:171
+msgid ""
+"Full object writes are batch based. Hugging Face batch writes are not "
+"transactional, so a failed store task may still leave some objects in the"
+" bucket. The MP adapter reconciles backend metadata after such failures "
+"so any objects that actually landed are counted for usage and later "
+"deletion (submitted store task is still reported as failed)."
+msgstr "完整对象写入是基于批处理的。Hugging Face 的批量写入不是事务性的，因此失败的存储任务可能仍会在桶中留下某些对象。MP 适配器在此类失败后会协调后端元数据，因此实际写入的对象会被计入使用量并在后续删除（提交的存储任务仍会被报告为失败）。"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:179
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/kv_cache/storage_backends/hfbucket.rst:181
+msgid ""
+"The backend stores objects under the configured bucket prefix using a "
+"reversible encoding of LMCache keys, so ``list()`` returns LMCache key "
+"strings instead of raw bucket object paths."
+msgstr "后端在配置的桶前缀下存储对象，使用 LMCache 键的可逆编码，因此 ``list()`` 返回 LMCache 键字符串，而不是原始桶对象路径。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/index.po
new file mode 100644
index 0000000..9af5265
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/index.po
@@ -0,0 +1,43 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/index.rst:2
+msgid "Using Different Storage Backends"
+msgstr "使用不同的存储后端"
+
+#: ../../source/kv_cache/storage_backends/index.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/index.rst:9
+msgid ""
+"LMCache supports various storage backends to offload and share KV cache "
+"data."
+msgstr "LMCache 支持多种存储后端以卸载和共享 KV Cache 数据。"
+
+#: ../../source/kv_cache/storage_backends/index.rst:12
+msgid "Supported Backends"
+msgstr "支持的后端"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/infinistore.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/infinistore.po
new file mode 100644
index 0000000..2fdeeca
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/infinistore.po
@@ -0,0 +1,257 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:2
+msgid "InfiniStore"
+msgstr "InfiniStore"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:14
+msgid ""
+"`InfiniStore <https://github.com/bytedance/InfiniStore>`_ is an open-"
+"source high-performance KV store. It's designed to support LLM Inference "
+"clusters, whether the cluster is in prefill-decoding disaggregation mode "
+"or not. InfiniStore provides high-performance and low-latency KV cache "
+"transfer and KV cache reuse among inference nodes in the cluster."
+msgstr ""
+"`InfiniStore <https://github.com/bytedance/InfiniStore>`_ 是一个开源的高性能 KV "
+"存储。它旨在支持 LLM 推理集群，无论集群是否处于分离式 Prefill-解码模式。InfiniStore 提供高性能和低延迟的 KV "
+"Cache 传输以及集群中推理节点之间的 KV Cache 重用。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:16
+msgid "There are two major scenarios how InfiniStore supports:"
+msgstr "InfiniStore 支持的主要场景有两个："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:18
+msgid ""
+"Prefill-Decoding disaggregation clusters: in such mode inference "
+"workloads are separated into two node pools: prefill nodes and decoding "
+"nodes. InfiniStore enables KV cache transfer among these two types of "
+"nodes, and also KV cache reuse."
+msgstr ""
+"分离式 Prefill-解码集群：在这种模式下，推理工作负载被分为两个节点池：Prefill 节点和解码节点。InfiniStore "
+"允许这两种类型节点之间的 KV Cache 转移，并且支持 KV Cache 重用。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:19
+msgid ""
+"Non-disaggregated clusters: in such mode prefill and decoding workloads "
+"are mixed on every node. InfiniStore serves as an extra large KV cache "
+"pool in addition to GPU cache and local CPU cache, and also enables "
+"cross-node KV cache reuse."
+msgstr ""
+"非分离式集群：在这种模式下，Prefill 和解码工作负载在每个节点上混合。InfiniStore 作为一个额外的大型 KV Cache 池，除了"
+" GPU 缓存和本地 CPU 缓存外，还支持跨节点的 KV Cache 重用。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:21
+msgid "InfiniStore Usage Diagram"
+msgstr "InfiniStore 使用示意图"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:24
+msgid ""
+"For more details, please refer to the `InfiniStore Documentation "
+"<https://bytedance.github.io/InfiniStore/index.html>`_."
+msgstr ""
+"有关更多详细信息，请参阅 `InfiniStore 文档 "
+"<https://bytedance.github.io/InfiniStore/index.html>`_。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:26
+msgid ""
+"InfiniStore supports both RDMA and TCP for transport. LMCache’s "
+"InfiniStore connector only uses the RDMA transport."
+msgstr "InfiniStore 支持 RDMA 和 TCP 作为传输方式。LMCache 的 InfiniStore 连接器仅使用 RDMA 传输。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:30
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:32
+msgid "Install InfiniStore via pip:"
+msgstr "通过 pip 安装 InfiniStore："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:38
+msgid "This package includes the InfiniStore server and the Python bindings."
+msgstr "该软件包包括 InfiniStore 服务器和 Python 绑定。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:40
+msgid ""
+"To build InfiniStore from source, follow the instructions in the `GitHub "
+"repository <https://github.com/bytedance/InfiniStore>`_."
+msgstr ""
+"要从源代码构建 InfiniStore，请按照 `GitHub 仓库 "
+"<https://github.com/bytedance/InfiniStore>`_ 中的说明进行操作。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:43
+msgid "Setup and Deployment"
+msgstr "设置和部署"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:45
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:47
+msgid "Machine with at least one GPU for vLLM inference"
+msgstr "具有至少一个 GPU 的机器用于 vLLM 推理"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:48
+msgid "RDMA-capable network hardware and drivers"
+msgstr "支持 RDMA 的网络硬件和驱动程序"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:49
+msgid "Python 3.8+ with pip"
+msgstr "Python 3.8+ 和 pip"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:50
+msgid "vLLM and LMCache installed"
+msgstr "已安装 vLLM 和 LMCache"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:52
+msgid "**Step 1: Start InfiniStore Server**"
+msgstr "**步骤 1：启动 InfiniStore 服务器**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:54
+msgid "For InfiniBand based RDMA:"
+msgstr "对于基于 InfiniBand 的 RDMA："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:60
+msgid "For RoCE based RDMA:"
+msgstr "对于基于 RoCE 的 RDMA："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:66
+msgid ""
+"You can also specify the ``--hint-gid-index`` option to set the GID index"
+" for the InfiniStore server. This is useful when you are in a k8s managed"
+" environment."
+msgstr ""
+"您还可以指定 ``--hint-gid-index`` 选项来设置 InfiniStore 服务器的 GID 索引。当您处于 k8s "
+"管理的环境中时，这非常有用。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:68
+msgid "**Step 2: Create Configuration File**"
+msgstr "**步骤 2：创建配置文件**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:70
+msgid "Create your ``infinistore-config.yaml``:"
+msgstr "创建你的 ``infinistore-config.yaml``："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:80
+msgid "**Step 3: Start vLLM with InfiniStore**"
+msgstr "**步骤 3：使用 InfiniStore 启动 vLLM**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:93
+msgid "**Step 4: Verify the Setup**"
+msgstr "**步骤 4：验证设置**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:95
+msgid "Test the integration with a sample request:"
+msgstr "使用示例请求测试集成："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:108
+msgid "**Debugging Tips:**"
+msgstr "**调试提示：**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:110
+msgid "**Enable verbose logging:**"
+msgstr "**启用详细日志记录：**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:116
+msgid "**Check server status:**"
+msgstr "**检查服务器状态：**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:125
+msgid "Query TTFT Improvement"
+msgstr "查询 TTFT 改进"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:127
+msgid ""
+"Once the OpenAI compatible server is running, let's query it twice and "
+"see the TTFT improvement."
+msgstr "一旦 OpenAI 兼容的服务器运行起来，我们就可以查询两次，看看 TTFT 的改进。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:129
+msgid "Run vLLM's serving benchmark twice with the following parameters:"
+msgstr "使用以下参数运行 vLLM 的服务基准测试两次："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:144
+msgid "**Example Output:**"
+msgstr "**示例输出：**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:146
+msgid "For the first run, you might see:"
+msgstr "首次运行时，您可能会看到："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:171
+msgid "For the second run, you should see a significant reduction in TTFT:"
+msgstr "对于第二次运行，您应该看到 TTFT 有显著减少："
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:196
+msgid "TTFT Improvement: 33.323 seconds (12.6x faster)."
+msgstr "TTFT 改进：33.323 秒（快 12.6 倍）。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:198
+msgid "**Tips:**"
+msgstr "**提示：**"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:200
+msgid ""
+"If you want to run vLLM's serving benchmark multiple times, you'll need "
+"to either restart the vLLM LMCache server and the InfiniStore server, or "
+"change the ``--seed`` parameter to a different value each time, since "
+"you've already warmed up LMCache."
+msgstr ""
+"如果您想多次运行 vLLM 的服务基准测试，您需要重启 vLLM LMCache 服务器和 InfiniStore 服务器，或者每次将 "
+"``--seed`` 参数更改为不同的值，因为您已经预热了 LMCache。"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:201
+msgid ""
+"The benchmark result here was produced by running an L40 with 48GB of GPU"
+" memory with ``--gpu-memory-utilization 0.8``. You can adjust the GPU "
+"memory utilization and increase the max model length to use more of the "
+"long context. LMCache TTFT improvement becomes more pronounced as the "
+"context length increases!"
+msgstr ""
+"这里的基准测试结果是通过运行一个具有 48GB 显存的 L40，并使用 ``--gpu-memory-utilization 0.8`` "
+"生成的。您可以调整显存利用率并增加最大模型长度，以使用更多的长上下文。随着上下文长度的增加，LMCache 的 TTFT 改进变得更加明显！"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:205
+msgid "Additional Resources"
+msgstr "附加资源"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:207
+msgid ""
+"`InfiniStore Documentation "
+"<https://bytedance.github.io/InfiniStore/index.html>`_"
+msgstr "`InfiniStore 文档 <https://bytedance.github.io/InfiniStore/index.html>`_"
+
+#: ../../source/kv_cache/storage_backends/infinistore.rst:208
+msgid "`GitHub Repository <https://github.com/bytedance/InfiniStore>`_"
+msgstr "`GitHub 仓库 <https://github.com/bytedance/InfiniStore>`_"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/local_storage.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/local_storage.po
new file mode 100644
index 0000000..e573da2
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/local_storage.po
@@ -0,0 +1,398 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:2
+msgid "Local storage"
+msgstr "本地存储"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:14
+msgid ""
+"CPU RAM and Local Storage are the two ways of offloading KV cache onto "
+"non-GPU memory of the same machine that is running inference."
+msgstr "CPU RAM 和本地存储是将 KV Cache 卸载到同一台运行推理的机器的非 GPU 内存的两种方式。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:19
+msgid "Two ways to configure LMCache Disk Offloading:"
+msgstr "配置 LMCache 磁盘卸载的两种方式："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:22
+msgid "**1. Environment Variables:**"
+msgstr "**1. 环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:41
+msgid "**2. Configuration File**:"
+msgstr "**2. 配置文件**:"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:43
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:63
+msgid "Multi-Path (Multi-Device) Disk Offloading"
+msgstr "多路径（多设备）磁盘卸载"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:65
+msgid ""
+"If you have **multiple NVMe devices** (or any independent mount points), "
+"you can assign each GPU its own disk path so that each device writes to a"
+" dedicated drive."
+msgstr "如果您有 **多个 NVMe 设备**\\ （或任何独立的挂载点），您可以为每个 GPU 分配自己的磁盘路径，以便每个设备写入专用驱动器。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:68
+msgid ""
+"Specify a **comma-separated list** of paths in ``local_disk``. Each path "
+"can optionally use the ``file://`` prefix.  The "
+"``local_disk_path_sharding`` option controls how each GPU worker selects "
+"its path.  Currently only ``\"by_gpu\"`` is supported (the default), "
+"which selects a path based on the device index (``device_id % "
+"num_paths``), so all KV cache files from a given GPU land on the same "
+"NVMe.  This is especially useful when GPUs and NVMe devices share a PCIe "
+"switch or NUMA node."
+msgstr ""
+"在 ``local_disk`` 中指定一个 **以逗号分隔的路径列表**\\ 。每个路径可以选择性地使用 ``file://`` 前缀。 "
+"``local_disk_path_sharding`` 选项控制每个 GPU 工作线程如何选择其路径。目前仅支持 "
+"``\"by_gpu\"``\\ （默认），它根据设备索引（\\ ``device_id % num_paths``\\ ）选择路径，因此来自给定"
+" GPU 的所有 KV 缓存文件都会落在同一个 NVMe 上。当 GPU 和 NVMe 设备共享 PCIe 交换机或 NUMA "
+"节点时，这尤其有用。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:76
+msgid "For example, with two GPUs and two paths:"
+msgstr "例如，使用两个 GPU 和两个路径："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:78
+msgid "``cuda:0`` → ``/mnt/nvme0/kvcache/``"
+msgstr "``cuda:0`` → ``/mnt/nvme0/kvcache/``"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:79
+msgid "``cuda:1`` → ``/mnt/nvme1/kvcache/``"
+msgstr "``cuda:1`` → ``/mnt/nvme1/kvcache/``"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:81
+msgid "``max_local_disk_size`` is the **total budget** shared across all paths."
+msgstr "``max_local_disk_size`` 是所有路径共享的 **总预算**\\ 。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:83
+msgid "**Environment variable example:**"
+msgstr "**环境变量示例：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:91
+msgid "**YAML example:**"
+msgstr "**YAML 示例：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:101
+msgid ""
+"Each GPU worker uses only its assigned path, so O_DIRECT alignment is "
+"determined by that path's filesystem block size.  Different devices may "
+"have different block sizes without issue."
+msgstr "每个 GPU 工作节点仅使用其分配的路径，因此 O_DIRECT 对齐由该路径的文件系统块大小决定。不同设备可能具有不同的块大小而不会出现问题。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:107
+msgid ""
+"If you are able to use kernel-level RAID 0 (e.g. ``mdadm --level=0``) you"
+" will get true block-level striping (even a single large file can use "
+"bandwidth from both devices simultaneously).  The multi-path feature is "
+"most useful when you cannot or do not want to reconfigure the block "
+"devices — for example, when they already have other data."
+msgstr ""
+"如果您能够使用内核级 RAID 0（例如 ``mdadm --level=0``\\ "
+"），您将获得真正的块级条带化（即使是单个大文件也可以同时使用两个设备的带宽）。当您无法或不想重新配置块设备时，多路径功能最为有用——例如，当它们已经包含其他数据时。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:114
+msgid "Local Storage Explanation:"
+msgstr "本地存储说明："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:116
+msgid ""
+"Unlike CPU RAM offloading, disk offloading is *disabled* by default "
+"(``local_disk`` is set to ``None``) and the max local disk size is set to"
+" 0GB instead of 5GB like the default max local cpu size since the disk "
+"space is not strictly necessary for LMCache to function."
+msgstr ""
+"与 CPU RAM 卸载不同，磁盘卸载默认是禁用的（\\ ``local_disk`` 设置为 ``None``\\ ），最大本地磁盘大小设置为 "
+"0GB，而不是像默认最大本地 CPU 大小那样设置为 5GB，因为磁盘空间对于 LMCache 的功能并不是严格必要的。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:120
+msgid ""
+"Furthermore, instead of greedily allocating the max space up front like "
+"the pinned CPU RAM, the disk backend will create one file per KV cache "
+"chunk as they are stored, evicting if capacity is exceeded (LRU "
+"currently)."
+msgstr ""
+"此外，与固定的 CPU RAM 不同，磁盘后端不会贪婪地提前分配最大空间，而是会在存储时为每个 KV "
+"缓存块创建一个文件，如果超出容量则逐出（当前使用 LRU）。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:123
+msgid ""
+"The disk and remote (see :doc:`Redis <./redis>`, :doc:`Mooncake "
+"<./mooncake>`, :doc:`Valkey <./valkey>`, :doc:`InfiniStore "
+"<./infinistore>`) backends have asynchronous put() operations so that the"
+" IO latency will not slow down inference in addition to blocking get() "
+"operations. The local disk backend also has a prefetch() operation that "
+"will preemptively move KV caches from the disk to CPU RAM offloading "
+"storage (i.e. ``LMCACHE_LOCAL_CPU=True`` should be set, see :doc:`CPU RAM"
+" <./cpu_ram>`) for specified tokens (these KV caches are also still kept "
+"in the disk)."
+msgstr ""
+"磁盘和远程后端（参见 :doc:`Redis <./redis>`、:doc:`Mooncake "
+"<./mooncake>`、:doc:`Valkey <./valkey>`、:doc:`InfiniStore "
+"<./infinistore>`）具有异步 put() 操作，因此 IO 延迟不会在阻塞 get() 操作的同时减慢推理。 本地磁盘后端还具有 "
+"prefetch() 操作，该操作将主动将 KV 缓存从磁盘移动到 CPU 内存卸载存储（即应设置 "
+"``LMCACHE_LOCAL_CPU=True``\\ ，参见 :doc:`CPU RAM "
+"<./cpu_ram>`），以便为指定的令牌预取（这些 KV 缓存仍然保留在磁盘中）。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:130
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:132
+msgid ""
+"The following diagram shows the overall architecture of the Local Disk "
+"Backend:"
+msgstr "下图展示了本地磁盘后端的整体架构："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:180
+msgid "**Key Components:**"
+msgstr "**关键组件：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:182
+msgid ""
+"**Metadata Dictionary**: Maps each ``CacheEngineKey`` to its disk "
+"metadata (file path, size, shape, dtype, pin status)"
+msgstr "**元数据字典**\\ ：将每个 ``CacheEngineKey`` 映射到其磁盘元数据（文件路径、大小、形状、数据类型、固定状态）"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:183
+msgid ""
+"**Cache Policy**: Configurable eviction policy (LRU, LFU, FIFO, or MRU) "
+"that tracks access patterns and decides which entries to evict when space"
+" is needed"
+msgstr "**缓存策略**\\ ：可配置的逐出策略（LRU、LFU、FIFO 或 MRU），跟踪访问模式并决定在需要空间时逐出哪些条目"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:184
+msgid ""
+"**LocalDiskWorker**: Async task executor with priority queue - prefetch "
+"tasks run first (priority 0), then deletes (priority 1), then saves "
+"(priority 2). The number of I/O worker threads is configurable via "
+"``extra_config.disk_io_threads`` (default: 4)."
+msgstr "**LocalDiskWorker**\\\\ ：带有优先级队列的异步任务执行器 - 预取任务优先运行（优先级 0），然后是删除（优先级 1），最后是保存（优先级 2）。I/O 工作线程的数量可以通过 ``extra_config.disk_io_threads`` 配置（默认值：4）。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:185
+msgid ""
+"**Local Disk**: Filesystem where KV cache chunks are stored as individual"
+" ``.pt`` files"
+msgstr "**本地磁盘**\\ ：KV Cache 块作为单独的 ``.pt`` 文件存储的文件系统"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:189
+msgid "Save Flow (PUT)"
+msgstr "保存流程 (PUT)"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:208
+msgid "Load Flow (GET)"
+msgstr "加载流程 (GET)"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:230
+msgid "Online Inference Example"
+msgstr "在线推理示例"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:232
+msgid ""
+"This example is almost identical to the :doc:`CPU RAM <./cpu_ram>` "
+"example."
+msgstr "这个示例与 :doc:`CPU RAM <./cpu_ram>` 示例几乎相同。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:234
+msgid "Let's feel the TTFT (time to first token) differential!"
+msgstr "让我们感受一下 TTFT（首次令牌时间）差异！"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:238
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:240
+msgid ""
+"A Machine with at least one GPU. Adjust the max model length of your vllm"
+" instance depending on your GPU memory and the long context you want to "
+"use."
+msgstr "一台至少配备一块 GPU 的机器。根据您的显存和希望使用的长上下文调整 vllm 实例的最大模型长度。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:242
+msgid ""
+"vllm and lmcache installed (:doc:`Installation Guide "
+"<../../getting_started/installation>`)"
+msgstr "vllm 和 lmcache 已安装 (:doc:`安装指南 <../../getting_started/installation>`)"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:244
+msgid "Hugging Face access to ``meta-llama/Meta-Llama-3.1-8B-Instruct``"
+msgstr "Hugging Face 访问 ``meta-llama/Meta-Llama-3.1-8B-Instruct``"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:250
+msgid "A few packages:"
+msgstr "一些软件包："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:258
+msgid "**Step 0. Set up a directory for this example:**"
+msgstr "**第 0 步. 为此示例设置一个目录:**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:265
+msgid "**Step 1. Prepare a long context!**"
+msgstr "**步骤 1. 准备一个长上下文！**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:267
+msgid ""
+"We want a context long enough that vllm's prefix caching will not be able"
+" to hold the KV caches in GPU memory and LMCache is necessary to keep KV "
+"caches in non-GPU memory:"
+msgstr "我们希望上下文足够长，以至于 vLLM 的前缀缓存无法将 KV 缓存保留在显存中，因此需要 LMCache 将 KV 缓存保留在非显存中："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:275
+msgid "**Step 2. Start a vLLM server with Disk offloading enabled:**"
+msgstr "**步骤 2. 启动一个启用磁盘卸载的 vLLM 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:277
+msgid ""
+"*Generally, it is not recommended but we will disable CPU offloading to "
+"feel just the disk offloading latency.*"
+msgstr "通常不推荐这样做，但我们将禁用 CPU 卸载，以便仅感受磁盘卸载的延迟。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:279
+msgid "Create a an lmcache configuration file called: ``disk-offload.yaml``"
+msgstr "创建一个名为 ``disk-offload.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:281
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:291
+msgid ""
+"If you don't want to use a config file, uncomment the first five "
+"environment variables and then comment out the ``LMCACHE_CONFIG_FILE`` "
+"below:"
+msgstr "如果您不想使用配置文件，请取消注释前五个环境变量，然后注释掉下面的 ``LMCACHE_CONFIG_FILE``\\ ："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:308
+msgid ""
+"``--kv-transfer-config``: This is the parameter that actually tells vLLM "
+"to use LMCache for KV cache offloading."
+msgstr "``--kv-transfer-config``: 这是实际告诉 vLLM 使用 LMCache 进行 KV Cache 卸载的参数。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:309
+msgid "``kv_connector``: Specifies the LMCache connector for vLLM V1"
+msgstr "``kv_connector``: 指定 vLLM V1 的 LMCache 连接器"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:310
+msgid ""
+"``kv_role``: Set to \"kv_both\" for both storing and loading KV cache "
+"(important because we will run two queries and the first will "
+"produce/store a KV cache while the second will consume/load that KV "
+"cache)"
+msgstr ""
+"``kv_role``: 设置为 \\\"kv_both\\\" 以同时存储和加载 KV "
+"Cache（重要，因为我们将运行两个查询，第一个将生成/存储一个 KV Cache，而第二个将消费/加载该 KV Cache）"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:313
+msgid "**Step 3. Query TTFT improvements with LMCache:**"
+msgstr "**步骤 3. 使用 LMCache 查询 TTFT 改进：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:315
+msgid ""
+"Once the Open AI compatible server is running on default vllm port 8000, "
+"let's query it twice with the same long context!"
+msgstr "一旦 Open AI 兼容的服务器在默认的 vllm 端口 8000 上运行，让我们用相同的长上下文查询两次！"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:317
+msgid "Create a script called ``query-twice.py`` and paste the following code:"
+msgstr "创建一个名为 ``query-twice.py`` 的脚本，并粘贴以下代码："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:383
+msgid "Then run:"
+msgstr "然后运行："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:389
+msgid ""
+"Since we're in streaming mode, you'll be able to feel the TTFT "
+"differential in real time!"
+msgstr "由于我们处于流式模式，您将能够实时感受到 TTFT 差异！"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:392
+msgid ""
+"Note that if we were to enable ``LMCACHE_LOCAL_CPU=True``, we would just "
+"be using the same example from :doc:`CPU RAM <./cpu_ram>` since the CPU "
+"RAM is checked before the disk by LMCache. In practice, the disk will be "
+"capable of storing a larger quantity of KV caches so the CPU RAM "
+"offloading will only be able to store a subset of the disk's KV caches."
+msgstr ""
+"请注意，如果我们启用 ``LMCACHE_LOCAL_CPU=True``\\ ，我们将仅使用来自 :doc:`CPU RAM "
+"<./cpu_ram>` 的相同示例，因为 LMCache 在检查磁盘之前会先检查 CPU RAM。实际上，磁盘能够存储更多的 KV 缓存，因此 "
+"CPU RAM 的卸载只能存储磁盘 KV 缓存的一个子集。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:398
+msgid "**Example Output:**"
+msgstr "**示例输出：**"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:424
+msgid "TTFT Improvement: 6.166 seconds     (42.6x faster)"
+msgstr "TTFT 改进：6.166 秒（快 42.6 倍）"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:426
+msgid ""
+"If you look at the logs of your vLLM server, you should see (the logs are"
+" truncated for cleanliness):"
+msgstr "如果你查看 vLLM 服务器的日志，你应该会看到（日志已为整洁而截断）："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:451
+msgid "Check out your KV Cache in your SSD:"
+msgstr "查看您 SSD 中的 KV Cache："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:460
+msgid "Tips:"
+msgstr "提示："
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:462
+msgid ""
+"If you want to run the ``query-twice.py`` script multiple times, you'll "
+"need to either restart the vLLM LMCache server or change the prefix of "
+"the context you pass in since you've already warmed LMCache."
+msgstr ""
+"如果您想多次运行 ``query-twice.py`` 脚本，您需要重启 vLLM LMCache "
+"服务器或更改您传入的上下文前缀，因为您已经预热了 LMCache。"
+
+#: ../../source/kv_cache/storage_backends/local_storage.rst:464
+msgid ""
+"The max model length here was decided by running an L4 with only 23GB of "
+"GPU memory. If you have more memory, you can increase the max model "
+"length and modify ``query-twice.py`` to use more of the long context. "
+"LMCache TTFT improvement becomes more pronounced as the context length "
+"increases!"
+msgstr ""
+"这里的最大模型长度是通过仅使用 23GB 显存的 L4 运行决定的。如果您有更多内存，可以增加最大模型长度并修改 ``query-"
+"twice.py`` 以使用更多的长上下文。随着上下文长度的增加，LMCache 的 TTFT 改进变得更加明显！"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/maru.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/maru.po
new file mode 100644
index 0000000..e3b52bf
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/maru.po
@@ -0,0 +1,213 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:2
+msgid "Maru"
+msgstr "Maru"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:14
+msgid ""
+"`Maru <https://github.com/xcena-dev/maru>`_ is a high-performance KV "
+"cache storage engine built on CXL shared memory, designed for LLM "
+"inference scenarios where multiple instances need to share a KV cache "
+"with minimal latency."
+msgstr ""
+"`Maru <https://github.com/xcena-dev/maru>`_ 是一个高性能的 KV Cache 存储引擎，基于 CXL "
+"共享内存构建，旨在用于 LLM 推理场景，在这些场景中，多个实例需要以最小延迟共享 KV Cache。"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:17
+msgid "KV Cache Sharing: Without vs With Maru"
+msgstr "KV Cache 共享：没有 Maru 与有 Maru"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:20
+msgid ""
+"For architecture details, see the `Maru documentation <https://xcena-"
+"dev.github.io/maru/>`_."
+msgstr "有关架构的详细信息，请参阅 `Maru 文档 <https://xcena-dev.github.io/maru/>`_。"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:23
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:25
+msgid "Install Maru:"
+msgstr "安装 Maru："
+
+#: ../../source/kv_cache/storage_backends/maru.rst:33
+msgid ""
+"This installs ``maru-server``, ``maru-resourced``, and the ``maru`` "
+"Python package."
+msgstr "这将安装 ``maru-server``、``maru-resourced`` 和 ``maru`` Python 包。"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:36
+msgid "Deploy Model With Maru"
+msgstr "使用 Maru 部署模型"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:38
+msgid ""
+"**Prerequisites:** CXL device (``/dev/dax*``), Python 3.12+, vLLM and "
+"LMCache installed."
+msgstr "**前提条件：** CXL 设备（``/dev/dax*``），安装 Python 3.12+、vLLM 和 LMCache。"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:40
+msgid "**1. Start the Maru Server**"
+msgstr "**1. 启动 Maru 服务器**"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:46
+msgid "**2. Create configuration file** (``maru-config.yaml``):"
+msgstr "**2. 创建配置文件** (``maru-config.yaml``):"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:59
+msgid "**3. Start vLLM with Maru**"
+msgstr "**3. 使用 Maru 启动 vLLM**"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:71
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:73
+msgid "**LMCache Parameters:**"
+msgstr "**LMCache 参数：**"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:79
+#: ../../source/kv_cache/storage_backends/maru.rst:95
+msgid "Parameter"
+msgstr "参数"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:80
+#: ../../source/kv_cache/storage_backends/maru.rst:96
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:81
+#: ../../source/kv_cache/storage_backends/maru.rst:97
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:82
+msgid "``maru_path``"
+msgstr "``maru_path``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:83
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:84
+msgid "Maru server URL (format: ``maru://host:port``)"
+msgstr "Maru 服务器 URL（格式：``maru://host:port``）"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:85
+msgid "``maru_pool_size``"
+msgstr "``maru_pool_size``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:86
+msgid "``4.0``"
+msgstr "``4.0``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:87
+msgid "CXL memory pool size per instance in GB (e.g., ``4``, ``0.5``)"
+msgstr "每个实例的 CXL 内存池大小（单位：GB，例如 ``4``、``0.5``）"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:89
+msgid "**Advanced Parameters (via extra_config):**"
+msgstr "**高级参数（通过 extra_config）：**"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:98
+msgid "``maru_instance_id``"
+msgstr "``maru_instance_id``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:99
+msgid "auto UUID"
+msgstr "自动 UUID"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:100
+msgid "Unique client instance identifier"
+msgstr "唯一客户端实例标识符"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:101
+msgid "``maru_timeout_ms``"
+msgstr "``maru_timeout_ms``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:102
+msgid "5000"
+msgstr "5000"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:103
+msgid "ZMQ RPC socket timeout in milliseconds"
+msgstr "ZMQ RPC 套接字超时（毫秒）"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:104
+msgid "``maru_use_async_rpc``"
+msgstr "``maru_use_async_rpc``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:105
+#: ../../source/kv_cache/storage_backends/maru.rst:111
+msgid "true"
+msgstr "真"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:106
+msgid "Async DEALER-ROUTER RPC (``false`` for synchronous REQ-REP)"
+msgstr "异步 DEALER-ROUTER RPC (``false`` 表示同步 REQ-REP)"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:107
+msgid "``maru_max_inflight``"
+msgstr "``maru_max_inflight``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:108
+msgid "64"
+msgstr "64"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:109
+msgid "Max concurrent async RPC requests"
+msgstr "最大并发异步 RPC 请求数"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:110
+msgid "``maru_eager_map``"
+msgstr "``maru_eager_map``"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:112
+msgid "Pre-map all shared regions on connect"
+msgstr "在连接时预先映射所有共享区域"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:115
+msgid "Additional Resources"
+msgstr "附加资源"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:117
+msgid "`Maru GitHub Repository <https://github.com/xcena-dev/maru>`_"
+msgstr "`Maru GitHub Repository <https://github.com/xcena-dev/maru>`_"
+
+#: ../../source/kv_cache/storage_backends/maru.rst:118
+msgid "`Maru Documentation <https://xcena-dev.github.io/maru/>`_"
+msgstr "`Maru 文档 <https://xcena-dev.github.io/maru/>`_"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/mock.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/mock.po
new file mode 100644
index 0000000..c35db57
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/mock.po
@@ -0,0 +1,116 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:2
+msgid "Mock"
+msgstr "模拟"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效项，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:9
+msgid ""
+"LMCache provides a mock remote connector that allows you to manually set "
+"the peeking latency, read throughput, and write throughput inside of the "
+"remote url. It will create copies of your KV cache in unmanaged local "
+"RAM."
+msgstr ""
+"LMCache 提供了一个模拟远程连接器，允许您手动设置远程 URL 中的预查看延迟、读取吞吐量和写入吞吐量。它将在未管理的本地 RAM "
+"中创建您的 KV Cache 的副本。"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:12
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:14
+msgid ""
+"Create a configuration file (e.g., ``mock.yaml``) with the following "
+"content:"
+msgstr "创建一个配置文件（例如，``mock.yaml``），内容如下："
+
+#: ../../source/kv_cache/storage_backends/mock.rst:23
+msgid ""
+"The ``remote_url`` format is "
+"``mock://SIZE/?peeking_latency=LATENCY&read_throughput=READ_GBPS&write_throughput=WRITE_GBPS``"
+" where:"
+msgstr ""
+"``remote_url`` 的格式为 "
+"``mock://SIZE/?peeking_latency=LATENCY&read_throughput=READ_GBPS&write_throughput=WRITE_GBPS``，其中："
+
+#: ../../source/kv_cache/storage_backends/mock.rst:25
+msgid "``SIZE``: Maximum storage size"
+msgstr "``SIZE``: 最大存储大小"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:26
+msgid "``peeking_latency``: Latency for peeking operations (in milliseconds)"
+msgstr "``peeking_latency``: 预取操作的延迟（以毫秒为单位）"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:27
+msgid "``read_throughput``: Read throughput (in GB/s)"
+msgstr "``read_throughput``: 读取吞吐量（以 GB/s 为单位）"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:28
+msgid "``write_throughput``: Write throughput (in GB/s)"
+msgstr "``write_throughput``: 写入吞吐量 (以 GB/s 为单位)"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:31
+msgid "Usage"
+msgstr "使用方法"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:33
+msgid "Deploy a serving engine with the mock remote backend:"
+msgstr "使用模拟远程后端部署服务引擎："
+
+#: ../../source/kv_cache/storage_backends/mock.rst:42
+msgid ""
+"Check the retrieval (storing is async so the throughput there is "
+"meaningless) logs on the second query to confirm that the throughput is "
+"slightly lower than 2 GB/s (the CPU <-> GPU allocation/transfer also has "
+"overhead)."
+msgstr "检查第二个查询的检索（存储是异步的，因此吞吐量没有意义）日志，以确认吞吐量略低于 2 GB/s（CPU <-> GPU 分配/传输也有开销）。"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:45
+msgid "Example Query"
+msgstr "示例查询"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:47
+msgid "Send a test request:"
+msgstr "发送测试请求："
+
+#: ../../source/kv_cache/storage_backends/mock.rst:60
+msgid "Expected Logs"
+msgstr "预期日志"
+
+#: ../../source/kv_cache/storage_backends/mock.rst:62
+msgid "You should see logs similar to the following:"
+msgstr "您应该看到类似于以下的日志："
+
+#: ../../source/kv_cache/storage_backends/mock.rst:69
+msgid ""
+"The logs confirm that the throughput is slightly lower than 2 GB/s due to"
+" CPU <-> GPU allocation/transfer overhead."
+msgstr "日志确认吞吐量略低于 2 GB/s，原因是 CPU <-> GPU 分配/传输开销。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/mooncake.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/mooncake.po
new file mode 100644
index 0000000..bf24412
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/mooncake.po
@@ -0,0 +1,567 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:2
+msgid "Mooncake"
+msgstr "Mooncake"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/mooncake_store`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/mooncake_store`。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:14
+msgid ""
+"`Mooncake <https://github.com/kvcache-ai/Mooncake>`_ is an open-source "
+"distributed KV cache storage system designed specifically for LLM "
+"inference scenarios. The system creates a distributed memory pool by "
+"aggregating memory space contributed by various client nodes, enabling "
+"efficient resource utilization across clusters."
+msgstr ""
+"`Mooncake <https://github.com/kvcache-ai/Mooncake>`_ 是一个开源的分布式 KV Cache "
+"存储系统，专为 LLM 推理场景而设计。该系统通过聚合多个客户端节点贡献的内存空间，创建一个分布式内存池，从而实现跨集群的高效资源利用。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:17
+msgid ""
+"By pooling underutilized DRAM and SSD resources from multiple nodes, the "
+"system forms a unified distributed storage service that maximizes "
+"resource efficiency."
+msgstr "通过整合多个节点下的未充分利用的 DRAM 和 SSD 资源，该系统形成了一个统一的分布式存储服务，最大化资源效率。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:19
+msgid "Mooncake Architecture Diagram"
+msgstr "Mooncake 架构图"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:23
+msgid "Key Features"
+msgstr "关键特性"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:25
+msgid ""
+"**Distributed memory pooling**: Aggregates memory contributions from "
+"multiple client nodes into a unified storage pool"
+msgstr "**分布式内存池**\\ ：将多个客户端节点的内存贡献聚合到一个统一的存储池中"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:26
+msgid ""
+"**High bandwidth utilization**: Supports striping and parallel I/O "
+"transfer of large objects, fully utilizing multi-NIC aggregated bandwidth"
+msgstr "**高带宽利用率**\\ ：支持大对象的条带化和并行 I/O 传输，充分利用多 NIC 聚合带宽"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:27
+msgid ""
+"**RDMA optimization**: Built on Transfer Engine with support for TCP, "
+"RDMA (InfiniBand/RoCEv2/eRDMA/NVIDIA GPUDirect)"
+msgstr ""
+"**RDMA 优化**\\ ：基于传输引擎构建，支持 TCP、RDMA（InfiniBand/RoCEv2/eRDMA/NVIDIA "
+"GPUDirect）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:28
+msgid ""
+"**Dynamic resource scaling**: Supports dynamically adding and removing "
+"nodes for elastic resource management"
+msgstr "**动态资源扩展**\\ ：支持动态添加和移除节点以实现弹性资源管理"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:30
+msgid ""
+"For detailed architecture information, see the `Mooncake Architecture "
+"Guide <https://kvcache-ai.github.io/Mooncake/design/mooncake-"
+"store.html>`_."
+msgstr ""
+"有关详细的架构信息，请参阅 `Mooncake Architecture Guide <https://kvcache-"
+"ai.github.io/Mooncake/design/mooncake-store.html>`_。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:33
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:35
+msgid "Install Mooncake via pip:"
+msgstr "通过 pip 安装 Mooncake："
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:41
+msgid "This package includes all necessary components:"
+msgstr "此软件包包含所有必要的组件："
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:43
+msgid ""
+"``mooncake_master``: Master service that manages cluster metadata and "
+"coordinates distributed storage operations"
+msgstr "``mooncake_master``\\ ：管理集群元数据并协调分布式存储操作的主服务"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:44
+msgid ""
+"``mooncake_http_metadata_server``: HTTP-based metadata server used by the"
+" underlying transfer engine for connection establishment"
+msgstr "``mooncake_http_metadata_server``: 基于 HTTP 的元数据服务器，用于底层传输引擎的连接建立"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:45
+msgid "Mooncake Python bindings"
+msgstr "Mooncake Python 绑定"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:47
+msgid ""
+"For production deployments or custom builds, see the `Build Instructions "
+"<https://kvcache-ai.github.io/Mooncake/getting_started/build.html>`_."
+msgstr ""
+"对于生产部署或自定义构建，请参阅 `构建说明 <https://kvcache-"
+"ai.github.io/Mooncake/getting_started/build.html>`_。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:50
+msgid "Setup and Deployment"
+msgstr "设置和部署"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:52
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:54
+msgid "Machine with at least one GPU for vLLM inference"
+msgstr "具有至少一个 GPU 的机器用于 vLLM 推理"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:55
+msgid "RDMA-capable network hardware and drivers (recommended) or TCP network"
+msgstr "支持 RDMA 的网络硬件和驱动程序（推荐）或 TCP 网络"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:56
+msgid "Python 3.8+ with pip"
+msgstr "Python 3.8+ 和 pip"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:57
+msgid "vLLM and LMCache installed"
+msgstr "已安装 vLLM 和 LMCache"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:59
+msgid "**Step 1: Start Infrastructure Services**"
+msgstr "**步骤 1：启动基础设施服务**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:61
+msgid "Start the Mooncake master service (with built‑in HTTP metadata server):"
+msgstr "启动 Mooncake 主服务（带内置 HTTP 元数据服务器）："
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:69
+msgid "Expected output:"
+msgstr "预期输出："
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:77
+msgid "**Step 2: Create Configuration File**"
+msgstr "**步骤 2：创建配置文件**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:79
+msgid "Create your ``mooncake-config.yaml``:"
+msgstr "创建您的 ``mooncake-config.yaml``\\ ："
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:103
+msgid "**Step 3: Start vLLM with Mooncake**"
+msgstr "**步骤 3：使用 Mooncake 启动 vLLM**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:116
+msgid "**Step 4: Verify the Setup**"
+msgstr "**步骤 4：验证设置**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:118
+msgid "Test the integration with a sample request:"
+msgstr "使用示例请求测试集成："
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:131
+msgid "**Debugging Tips:**"
+msgstr "**调试提示：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:133
+msgid "**Enable verbose logging:**"
+msgstr "**启用详细日志记录：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:139
+msgid "**Check service status:**"
+msgstr "**检查服务状态：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:147
+msgid "**Monitor metrics:**"
+msgstr "**监控指标：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:149
+msgid ""
+"Access metrics at ``http://localhost:9003`` when master service is "
+"running."
+msgstr "当主服务运行时，可以在 ``http://localhost:9003`` 访问指标。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:152
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:154
+msgid "**LMCache Parameters:**"
+msgstr "**LMCache 参数：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:160
+#: ../../source/kv_cache/storage_backends/mooncake.rst:191
+msgid "Parameter"
+msgstr "参数"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:161
+#: ../../source/kv_cache/storage_backends/mooncake.rst:192
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:162
+#: ../../source/kv_cache/storage_backends/mooncake.rst:193
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:163
+msgid "``chunk_size``"
+msgstr "``chunk_size``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:164
+msgid "256"
+msgstr "256"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:165
+msgid "Number of tokens per KV chunk"
+msgstr "每个 KV 块的令牌数量"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:166
+msgid "``remote_url``"
+msgstr "``remote_url``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:167
+#: ../../source/kv_cache/storage_backends/mooncake.rst:176
+#: ../../source/kv_cache/storage_backends/mooncake.rst:195
+#: ../../source/kv_cache/storage_backends/mooncake.rst:198
+#: ../../source/kv_cache/storage_backends/mooncake.rst:201
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:168
+msgid "Mooncake store connection URL (format: ``mooncakestore://host:port/``)."
+msgstr "Mooncake 存储连接 URL（格式：\\ ``mooncakestore://host:port/``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:169
+msgid "``remote_serde``"
+msgstr "``remote_serde``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:170
+msgid "\"naive\""
+msgstr "“简单”"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:171
+msgid "Serialization method for remote storage"
+msgstr "远程存储的序列化方法"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:172
+msgid "``local_cpu``"
+msgstr "``local_cpu``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:173
+#: ../../source/kv_cache/storage_backends/mooncake.rst:225
+#: ../../source/kv_cache/storage_backends/mooncake.rst:228
+#: ../../source/kv_cache/storage_backends/mooncake.rst:231
+msgid "False"
+msgstr "假"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:174
+msgid ""
+"Enable/disable local CPU caching (set to False for pure Mooncake "
+"evaluation)"
+msgstr "启用/禁用本地 CPU 缓存（设置为 False 以进行纯 Mooncake 评估）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:175
+msgid "``max_local_cpu_size``"
+msgstr "``max_local_cpu_size``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:177
+msgid "Maximum local CPU cache size in GB (required even when local_cpu is False)"
+msgstr "本地 CPU 缓存的最大大小（以 GB 为单位）（即使 local_cpu 为 False 也需要）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:178
+msgid "``numa_mode``"
+msgstr "``numa_mode``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:179
+msgid "\"auto\""
+msgstr "自动"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:180
+msgid ""
+"NUMA binding mode. \"auto\" is recommended on multi‑NIC/multi‑NUMA "
+"systems to reduce tail latency."
+msgstr "NUMA 绑定模式。在多 NIC/多 NUMA 系统上，推荐使用 \\\"auto\\\" 以减少尾部延迟。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:181
+msgid "``pre_caching_hash_algorithm``"
+msgstr "``pre_caching_hash_algorithm``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:182
+msgid "\"sha256_cbor_64bit\""
+msgstr "sha256_cbor_64bit"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:183
+msgid ""
+"Hash used for pre-caching keying. For cross‑process consistency, fix "
+"``PYTHONHASHSEED`` (e.g., export ``PYTHONHASHSEED=0``)."
+msgstr ""
+"用于预缓存键的哈希。为了跨进程的一致性，固定 ``PYTHONHASHSEED``\\ （例如，导出 ``PYTHONHASHSEED=0``\\"
+" ）。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:185
+msgid "**Mooncake Parameters (via extra_config):**"
+msgstr "**Mooncake 参数（通过 extra_config）：**"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:194
+msgid "``local_hostname``"
+msgstr "``local_hostname``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:196
+msgid "Hostname/IP of the local node for Mooncake client identification"
+msgstr "Mooncake 客户端识别的本地节点的主机名/IP"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:197
+msgid "``metadata_server``"
+msgstr "``metadata_server``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:199
+msgid ""
+"HTTP metadata server address. When starting master with "
+"``--enable_http_metadata_server=1``, it exposes this endpoint."
+msgstr "HTTP 元数据服务器地址。当使用 ``--enable_http_metadata_server=1`` 启动主服务器时，它会公开此端点。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:200
+msgid "``master_server_address``"
+msgstr "``master_server_address``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:202
+msgid "Mooncake master service address (host:port format)"
+msgstr "Mooncake 主服务地址（主机:端口格式）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:203
+msgid "``protocol``"
+msgstr "``protocol``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:204
+msgid "\"rdma\""
+msgstr "rdma"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:205
+msgid ""
+"Communication protocol (\"rdma\" for high performance; \"tcp\" for "
+"compatibility)"
+msgstr "通信协议（“rdma”用于高性能；“tcp”用于兼容性）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:206
+msgid "``device_name``"
+msgstr "``device_name``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:207
+#: ../../source/kv_cache/storage_backends/mooncake.rst:222
+msgid "\"\""
+msgstr "\"\""
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:208
+msgid ""
+"RDMA device specification (e.g., \"erdma_0,erdma_1\" or "
+"\"mlx5_0,mlx5_1\"). Leave empty for autodetection in most setups."
+msgstr ""
+"RDMA 设备规格（例如，\\\"erdma_0,erdma_1\\\" 或 "
+"\\\"mlx5_0,mlx5_1\\\"）。在大多数设置中留空以进行自动检测。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:209
+msgid "``global_segment_size``"
+msgstr "``global_segment_size``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:210
+msgid "21474836480"
+msgstr "21474836480"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:211
+msgid ""
+"**Memory size contributed by each vLLM worker** in bytes (e.g., 20 GiB "
+"recommended)"
+msgstr "**每个 vLLM 工作线程贡献的内存大小**\\ （以字节为单位，例如，推荐 20 GiB）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:212
+msgid "``local_buffer_size``"
+msgstr "``local_buffer_size``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:213
+msgid "0"
+msgstr "0"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:214
+msgid ""
+"Local buffer size in bytes used by Mooncake. Behavior depends on "
+"``save_chunk_meta``: - When ``save_chunk_meta: False`` (recommended), "
+"LMCache uses its local CPU backend for zero‑copy RDMA, so Mooncake's "
+"``local_buffer_size`` can be ``0``. - When ``save_chunk_meta: True``, "
+"Mooncake uses its own local buffer; set this to a proper value (e.g., "
+"several GiB). - Note: Some RDMA NICs have memory registration limits; "
+"registering LMCache's large CPU buffer can fail on constrained devices. "
+"In those cases, consider enabling ``save_chunk_meta: True`` and sizing "
+"``local_buffer_size`` instead."
+msgstr ""
+"Mooncake 使用的本地缓冲区大小（以字节为单位）。行为取决于 ``save_chunk_meta``\\ ：- 当 "
+"``save_chunk_meta: False``\\ （推荐）时，LMCache 使用其本地 CPU 后端进行零拷贝 RDMA，因此 "
+"Mooncake 的 ``local_buffer_size`` 可以为 ``0``\\ 。- 当 ``save_chunk_meta: "
+"True`` 时，Mooncake 使用其自己的本地缓冲区；将其设置为合适的值（例如，几个 GiB）。- 注意：某些 RDMA NIC "
+"有内存注册限制；在受限设备上注册 LMCache 的大 CPU 缓冲区可能会失败。在这些情况下，请考虑启用 ``save_chunk_meta: "
+"True`` 并调整 ``local_buffer_size`` 的大小。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:218
+msgid "``transfer_timeout``"
+msgstr "``transfer_timeout``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:219
+msgid "1"
+msgstr "1"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:220
+msgid "Timeout for transfer operations in seconds"
+msgstr "传输操作的超时时间（以秒为单位）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:221
+msgid "``storage_root_dir``"
+msgstr "``storage_root_dir``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:223
+msgid "The root directory for persistence (e.g., \"/mnt/mooncake\")"
+msgstr "持久化的根目录（例如，\\\"/mnt/mooncake\\\"）"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:224
+msgid "``save_chunk_meta``"
+msgstr "``save_chunk_meta``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:226
+msgid ""
+"Whether to save chunk metadata alongside data. Set to ``False`` to enable"
+" the optimized zero‑copy path in LMCache."
+msgstr "是否在数据旁边保存块元数据。设置为 ``False`` 以启用 LMCache 中的优化零拷贝路径。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:227
+msgid "``use_exists_sync``"
+msgstr "``use_exists_sync``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:229
+msgid ""
+"Use synchronous existence checks to avoid async scheduling overhead in "
+"hot paths."
+msgstr "使用同步存在性检查以避免热路径中的异步调度开销。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:230
+msgid "``mooncake_prefer_local_alloc``"
+msgstr "``mooncake_prefer_local_alloc``"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:232
+msgid "Prefer allocating on the local segment when possible."
+msgstr "在可能的情况下，优先在本地段上分配。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:235
+msgid ""
+"**Understanding global_segment_size**: This parameter defines the amount "
+"of memory each vLLM worker contributes to the distributed memory pool. "
+"The total cluster memory available for KV cache storage will be: "
+"``number_of_vllm_workers × global_segment_size``."
+msgstr ""
+"**理解 global_segment_size**\\ ：该参数定义了每个 vLLM 工作线程为分布式内存池贡献的内存量。KV Cache "
+"存储可用的总集群内存将为：\\ ``number_of_vllm_workers × global_segment_size``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:238
+msgid ""
+"Adjust this value based on your available system memory and expected "
+"cache requirements."
+msgstr "根据您的可用系统内存和预期的缓存需求调整此值。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:241
+msgid ""
+"If you consistently get misses (no Mooncake hits), ensure all processes "
+"use the same hashing seed: ``export PYTHONHASHSEED=0``. This keeps "
+"pre‑caching keys consistent across processes."
+msgstr ""
+"如果您持续遇到未命中（没有 Mooncake 命中），请确保所有进程使用相同的哈希种子：\\ ``export "
+"PYTHONHASHSEED=0``\\ 。这可以保持跨进程的预缓存键一致。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:244
+msgid ""
+"RDMA device(s) usually do not need to be specified; leaving "
+"``device_name`` empty works for most deployments."
+msgstr "RDMA 设备通常不需要指定；将 ``device_name`` 留空适用于大多数部署。"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:247
+msgid "Additional Resources"
+msgstr "附加资源"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:249
+msgid ""
+"`Mooncake Store Architecture <https://kvcache-"
+"ai.github.io/Mooncake/design/mooncake-store.html>`_"
+msgstr ""
+"`Mooncake Store 架构 <https://kvcache-ai.github.io/Mooncake/design"
+"/mooncake-store.html>`_"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:250
+msgid ""
+"`Mooncake Store Deployment Guide <https://kvcache-"
+"ai.github.io/Mooncake/deployment/mooncake-store-deployment-guide.html>`_"
+msgstr ""
+"`Mooncake Store 部署指南 <https://kvcache-ai.github.io/Mooncake/deployment"
+"/mooncake-store-deployment-guide.html>`_"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:251
+msgid ""
+"`Mooncake Store Python API Reference <https://kvcache-"
+"ai.github.io/Mooncake/python-api-reference/mooncake-store.html>`_"
+msgstr ""
+"`Mooncake Store Python API 参考 <https://kvcache-ai.github.io/Mooncake"
+"/python-api-reference/mooncake-store.html>`_"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:252
+msgid ""
+"`Transfer Engine Documentation <https://kvcache-"
+"ai.github.io/Mooncake/design/transfer-engine/index.html>`_"
+msgstr ""
+"`传输引擎文档 <https://kvcache-ai.github.io/Mooncake/design/transfer-"
+"engine/index.html>`_"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:253
+msgid ""
+"`Build Instructions <https://kvcache-"
+"ai.github.io/Mooncake/getting_started/build.html>`_"
+msgstr "`构建说明 <https://kvcache-ai.github.io/Mooncake/getting_started/build.html>`_"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:254
+msgid "`GitHub Repository <https://github.com/kvcache-ai/Mooncake>`_"
+msgstr "`GitHub 仓库 <https://github.com/kvcache-ai/Mooncake>`_"
+
+#: ../../source/kv_cache/storage_backends/mooncake.rst:255
+msgid ""
+"`LMCache Integration Guide <https://kvcache-"
+"ai.github.io/Mooncake/getting_started/examples/lmcache-"
+"integration.html>`_"
+msgstr ""
+"`LMCache 集成指南 <https://kvcache-"
+"ai.github.io/Mooncake/getting_started/examples/lmcache-"
+"integration.html>`_"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/nixl.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/nixl.po
new file mode 100644
index 0000000..2938f41
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/nixl.po
@@ -0,0 +1,435 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:3
+msgid "Nixl"
+msgstr "Nixl"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:7
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/nixl`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/nixl`。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:13
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:15
+msgid ""
+"NIXL (NVIDIA Inference Xfer Library) is a high-performance library "
+"designed for accelerating point to point communications in AI inference "
+"frameworks. It provides an abstraction over various types of memory (CPU "
+"and GPU) and storage through a modular plug-in architecture, enabling "
+"efficient data transfer and coordination between different components of "
+"the inference pipeline."
+msgstr ""
+"NIXL（NVIDIA 推理传输库）是一个高性能库，旨在加速 AI 推理框架中的点对点通信。它通过模块化插件架构提供对各种类型内存（CPU 和 "
+"GPU）和存储的抽象，使得推理管道中不同组件之间的数据传输和协调更加高效。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:17
+msgid ""
+"LMCache supports using NIXL as a storage backend, allowing using NIXL to "
+"save either GPU or CPU memory into storage."
+msgstr "LMCache 支持将 NIXL 用作存储后端，允许将显存或 CPU 内存保存到存储中。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:20
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:22
+msgid "**LMCache**: Install with ``pip install lmcache``"
+msgstr "**LMCache**: 使用 ``pip install lmcache`` 安装"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:23
+msgid ""
+"**NIXL**: Install from `NIXL GitHub repository <https://github.com/ai-"
+"dynamo/nixl>`_"
+msgstr ""
+"**NIXL**: 从 `NIXL GitHub repository <https://github.com/ai-dynamo/nixl>`_"
+" 安装"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:24
+msgid ""
+"**Model Access**: Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B "
+"Instruct"
+msgstr "**模型访问**\\ ：有效的 Hugging Face 令牌 (HF_TOKEN) 用于 Llama 3.1 8B Instruct"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:27
+msgid "Ways to configure LMCache NIXL Offloading"
+msgstr "配置 LMCache NIXL 卸载的方法"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:29
+msgid "**Configuration File**:"
+msgstr "**配置文件**\\ ："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:31
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:33
+msgid "Example ``lmcache-config.yaml`` for POSIX backend:"
+msgstr "示例 ``lmcache-config.yaml`` 用于 POSIX 后端："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:47
+msgid "Key settings:"
+msgstr "关键设置："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:49
+msgid ""
+"``nixl_buffer_size``: buffer size for NIXL transfers. **GPU mode only** "
+"(``nixl_buffer_device: cuda``). Setting this with ``nixl_buffer_device: "
+"cpu`` is a configuration error and will be rejected — in CPU mode NIXL "
+"shares ``LocalCPUBackend``'s pinned pool, which is sized by "
+"``max_local_cpu_size``."
+msgstr ""
+"``nixl_buffer_size``\\ ：NIXL 传输的缓冲区大小。\\ **仅限 GPU 模式**\\ （\\ "
+"``nixl_buffer_device: cuda``\\ ）。将其设置为 ``nixl_buffer_device: cpu`` "
+"是配置错误，将被拒绝——在 CPU 模式下，NIXL 共享 ``LocalCPUBackend`` 的固定池，该池的大小由 "
+"``max_local_cpu_size`` 决定。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:51
+msgid ""
+"``max_local_cpu_size``: size of ``LocalCPUBackend``'s pinned pool in GiB."
+" In CPU mode, this pool is shared with NIXL and must accommodate both the"
+" hot cache and concurrent NIXL I/O in flight. Must be > 0 when "
+"``nixl_buffer_device: cpu``. Default: ``5.0``."
+msgstr ""
+"``max_local_cpu_size``: ``LocalCPUBackend`` 的固定池大小（以 GiB 为单位）。在 CPU "
+"模式下，该池与 NIXL 共享，必须能够容纳热缓存和并发的 NIXL I/O。设置为 ``nixl_buffer_device: cpu`` "
+"时必须大于 0。默认值：\\ ``5.0``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:53
+msgid ""
+"``nixl_pool_size``: number of descriptors opened at init time for nixl "
+"backend. Set to 0 for dynamic mode."
+msgstr "``nixl_pool_size``: 初始化时为 nixl 后端打开的描述符数量。设置为 0 以启用动态模式。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:55
+msgid ""
+"``nixl_path``: directory (or list of directories) under which the storage"
+" files will be saved (e.g. /mnt/nixl/). Needed for NIXL backends that "
+"store to file. When using a list of paths with ``path_sharding``, paths "
+"will be selected based on the sharding strategy."
+msgstr ""
+"``nixl_path``: 存储文件将保存的目录（或目录列表）（例如 /mnt/nixl/）。对于将数据存储到文件的 NIXL "
+"后端是必需的。当使用带有 ``path_sharding`` 的路径列表时，路径将根据分片策略进行选择。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:57
+msgid ""
+"``nixl_buffer_device``: dictates where the memory managed by NIXL should "
+"be on. \"cpu\" or \"cuda\" is supported for \"GDS\", \"GDS_MT\", and "
+"\"OBJ\" backends - for \"POSIX\", \"HF3FS\", \"AZURE_BLOB\" & "
+"\"DOCA_MEMOS\", must be \"cpu\". In CPU mode, NIXL shares "
+"``LocalCPUBackend``'s pinned buffer; ``LocalCPUBackend`` is always "
+"created when ``nixl_buffer_device: cpu``, regardless of the ``local_cpu``"
+" setting. ``local_cpu: false`` still suppresses hot-cache promotions — "
+"the backend acts as a staging buffer only, mirroring how ``local_disk`` "
+"already uses ``LocalCPUBackend``."
+msgstr ""
+"``nixl_buffer_device``: 指定 NIXL 管理的内存应位于何处。对于 ``GDS``\\ 、\\ ``GDS_MT`` 和 "
+"``OBJ`` 后端，支持 ``cpu`` 或 ``cuda``\\ ；对于 ``POSIX``\\ 、\\ ``HF3FS``\\ 、\\ "
+"``AZURE_BLOB`` 和 ``DOCA_MEMOS``\\ ，必须为 ``cpu``\\ 。在 CPU 模式下，NIXL 共享 "
+"``LocalCPUBackend`` 的固定缓冲区；当 ``nixl_buffer_device: cpu`` 时，\\ "
+"``LocalCPUBackend`` 始终会被创建，无论 ``local_cpu`` 设置如何。\\ ``local_cpu: false`` "
+"仍然会抑制热缓存提升——后端仅作为暂存缓冲区，镜像 ``local_disk`` 已经如何使用 ``LocalCPUBackend``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:59
+msgid "``nixl_backend``: configuration of which nixl backend to use for storage."
+msgstr "``nixl_backend``: 配置用于存储的 nixl 后端。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:61
+msgid ""
+"``nixl_path_sharding``: strategy for selecting path when multiple paths "
+"are provided. Currently only \"by_gpu\" is supported, which selects paths"
+" based on GPU device ID."
+msgstr ""
+"``nixl_path_sharding``: 当提供多个路径时选择路径的策略。目前仅支持“by_gpu”，该策略根据 GPU 设备 ID "
+"选择路径。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:62
+msgid ""
+"``local_cpu_use_hugepages``: whether to use Linux hugepages (2 MiB) for "
+"``LocalCPUBackend``'s pinned pool (which NIXL shares in CPU mode). "
+"Requires pre-allocated hugepages (``sysctl vm.nr_hugepages``). Default: "
+"``false``. **Deprecated alias:** ``extra_config.nixl_use_hugepages`` — "
+"accepted with a warning and copied into this field; will be removed in a "
+"future release."
+msgstr ""
+"``local_cpu_use_hugepages``: 是否为 ``LocalCPUBackend`` 的固定池使用 Linux 大页（2 "
+"MiB）（NIXL 在 CPU 模式下共享）。需要预分配的大页（\\ ``sysctl vm.nr_hugepages``\\ ）。默认值：\\ "
+"``false``\\ 。\\ **已弃用的别名：** ``extra_config.nixl_use_hugepages`` — "
+"接受时会发出警告并复制到此字段；将在未来的版本中移除。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:66
+msgid ""
+"In CPU mode, the shared paged allocator consumes one full page per "
+"object. With ``save_unfull_chunk: true`` (only valid in static mode — "
+"dynamic mode rejects it; see \"Dynamic Mode\" → \"Restrictions\" below), "
+"partial chunks still occupy a full page each, so effective capacity "
+"degrades proportionally to the fraction of unfull last chunks across "
+"active sequences."
+msgstr ""
+"在 CPU 模式下，共享分页分配器每个对象消耗一个完整的页面。使用 ``save_unfull_chunk: true``\\ "
+"（仅在静态模式下有效——动态模式会拒绝它；请参见“动态模式”→“限制”），部分块仍然占用一个完整的页面，因此有效容量与活动序列中未满最后块的比例成正比地下降。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:70
+msgid ""
+"``enable_p2p: true`` is rejected together with ``nixl_buffer_device: "
+"cpu``. The combination is structurally supported — both backends share "
+"``LocalCPUBackend``'s pinned pool, each runs its own NIXL agent over it, "
+"and allocations route through ``LocalCPUBackend.allocate()`` — but it has"
+" not been exercised end-to-end and has no CI coverage. Use ``enable_p2p: "
+"true`` with ``nixl_buffer_device: cuda`` instead, or disable "
+"``enable_p2p`` when running the NIXL CPU shared pool."
+msgstr ""
+"``enable_p2p: true`` 与 ``nixl_buffer_device: cpu`` "
+"一起被拒绝。这个组合在结构上是支持的——两个后端共享 ``LocalCPUBackend`` 的固定池，各自运行自己的 NIXL "
+"代理，并且分配通过 ``LocalCPUBackend.allocate()`` 路由——但尚未进行端到端的测试，也没有 CI 覆盖。在使用 "
+"NIXL CPU 共享池时，请改用 ``nixl_buffer_device: cuda`` 的 ``enable_p2p: true``\\ "
+"，或者在运行时禁用 ``enable_p2p``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:72
+msgid ""
+"``nixl_presence_cache``: whether to keep an in-DRAM presence cache of "
+"keys known to exist, so repeated existence checks for the same key are "
+"answered locally instead of via a NIXL ``query_memory`` call. Applies to "
+"the dynamic backend (``nixl_pool_size: 0``). Default: ``false``."
+msgstr ""
+"``nixl_presence_cache``：是否在 DRAM "
+"中保留已知存在的键的存在缓存，以便对同一键的重复存在检查可以在本地回答，而不是通过 NIXL ``query_memory`` "
+"调用。适用于动态后端（``nixl_pool_size: 0``）。默认值：``false``。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:74
+msgid ""
+"``nixl_presence_cache_only``: when ``true``, the dynamic NIXL backend "
+"treats the local presence cache (and in-progress put set) as "
+"authoritative for existence checks. If a key is not known locally, lookup"
+" reports a miss **without** issuing a NIXL ``query_memory`` check. This "
+"requires ``nixl_presence_cache: true`` and can intentionally produce "
+"**false negatives** for objects that exist in the underlying storage but "
+"are absent from local presence metadata — giving \"DRAM-only metadata\" "
+"semantics where a process restart always yields a logically empty cache. "
+"Default: ``false``."
+msgstr ""
+"``nixl_presence_cache_only``：当 ``true`` 时，动态 NIXL "
+"后端将本地存在缓存（和正在进行的放置集合）视为存在检查的权威。如果一个键在本地未知，查找将报告未命中 **而不** 发出 NIXL "
+"``query_memory`` 检查。这要求 ``nixl_presence_cache: true``，并且可能故意产生 "
+"**假阴性**，即在底层存储中存在但在本地存在元数据中缺失的对象——提供“仅 DRAM "
+"元数据”的语义，其中进程重启总是导致逻辑上空的缓存。默认值：``false``。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:78
+msgid ""
+"This is a **lookup/existence-check** mode, not a \"never touch the "
+"underlying storage\" policy. It gates ``contains`` / ``batched_contains``"
+" (and the async variant); direct retrieval still reads from the "
+"underlying storage. In normal operation a retrieval is only issued for a "
+"key that lookup already reported as present, so locally-unknown keys are "
+"not fetched. The option is only consulted by the dynamic backend "
+"(``nixl_pool_size: 0``); it is accepted but unused for static "
+"configurations."
+msgstr ""
+"这是一个 **查找/存在检查** 模式，而不是“永远不接触底层存储”的策略。它控制 ``contains`` / "
+"``batched_contains``\\ "
+"（以及异步变体）；直接检索仍然从底层存储读取。在正常操作中，仅对查找已报告为存在的键发出检索，因此本地未知的键不会被获取。该选项仅由动态后端（``nixl_pool_size:"
+" 0``）参考；对于静态配置，它被接受但未使用。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:82
+msgid ""
+"Supported backends are: [\"GDS\", \"GDS_MT\", \"POSIX\", \"HF3FS\", "
+"\"OBJ\", \"AZURE_BLOB\", \"DOCA_MEMOS\"]."
+msgstr ""
+"支持的后端包括：[\\\"GDS\\\", \\\"GDS_MT\\\", \\\"POSIX\\\", \\\"HF3FS\\\", "
+"\\\"OBJ\\\", \\\"AZURE_BLOB\\\", \\\"DOCA_MEMOS\\\"]."
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:84
+msgid ""
+"Backend specific params should be provided via "
+"``extra_config.nixl_backend_params``. Please refer to NIXL documentation "
+"for specifics."
+msgstr "后端特定参数应通过 ``extra_config.nixl_backend_params`` 提供。有关具体信息，请参阅 NIXL 文档。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:86
+msgid "Example ``lmcache-config.yaml`` for POSIX backend with multipath support:"
+msgstr "示例 ``lmcache-config.yaml`` 用于支持多路径的 POSIX 后端："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:104
+msgid "Example ``lmcache-config.yaml`` for OBJ backend using S3 API:"
+msgstr "示例 ``lmcache-config.yaml`` 用于使用 S3 API 的 OBJ 后端："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:122
+msgid "Example ``lmcache-config.yaml`` for POSIX backend using liburing:"
+msgstr "示例 ``lmcache-config.yaml`` 用于使用 liburing 的 POSIX 后端："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:126
+msgid ""
+"using POSIX backend with liburing requires NIXL to be built with liburing"
+" support."
+msgstr "使用带有 liburing 支持的 POSIX 后端需要将 NIXL 构建为支持 liburing。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:142
+msgid ""
+"Example ``lmcache-config.yaml`` for AZURE_BLOB backend to offload using "
+"Azure Blob Storage API:"
+msgstr ""
+"示例 ``lmcache-config.yaml`` 用于 AZURE_BLOB 后端，通过 Azure Blob Storage API "
+"进行卸载："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:159
+msgid "Per-Worker Endpoint Distribution"
+msgstr "每个工作节点的端点分配"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:161
+msgid ""
+"When using the OBJ backend with multiple tensor-parallel (TP) workers, "
+"you can distribute workers across multiple object-storage endpoints by "
+"providing a list of endpoints via ``nixl_endpoint_list``. Each worker "
+"selects an endpoint in round-robin order based on its ``local_worker_id``"
+" (the worker ID within its host)."
+msgstr ""
+"当使用 OBJ 后端与多个张量并行 (TP) 工作节点时，您可以通过提供一个端点列表来在多个对象存储端点之间分配工作节点，方法是使用 "
+"``nixl_endpoint_list``\\ 。每个工作节点根据其 ``local_worker_id``\\ （其主机内的工作节点 "
+"ID）以轮询方式选择一个端点。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:185
+msgid ""
+"When ``nixl_endpoint_list`` is set, any ``endpoint_override`` value in "
+"``nixl_backend_params`` is ignored (a warning is logged)."
+msgstr ""
+"当设置 ``nixl_endpoint_list`` 时，\\ ``nixl_backend_params`` 中的任何 "
+"``endpoint_override`` 值将被忽略（会记录警告）。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:188
+msgid ""
+"``nixl_endpoint_list`` is only honored for the OBJ backend; it is ignored"
+" for all other backends (including DOCA_MEMOS, AZURE_BLOB, and the file "
+"backends)."
+msgstr ""
+"``nixl_endpoint_list`` 仅对 OBJ 后端有效；对于所有其他后端（包括 DOCA_MEMOS、AZURE_BLOB "
+"和文件后端）将被忽略。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:193
+msgid "Dynamic Mode"
+msgstr "动态模式"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:195
+msgid ""
+"Nixl Storage Backend also supports a dynamic mode, which creates nixl "
+"storage descriptors on demand instead of at init time."
+msgstr "Nixl 存储后端还支持动态模式，该模式按需创建 nixl 存储描述符，而不是在初始化时创建。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:197
+msgid ""
+"In order to use dynamic mode, extra_config.nixl_pool_size should be set "
+"to 0."
+msgstr "为了使用动态模式，extra_config.nixl_pool_size 应设置为 0。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:200
+msgid "Restrictions"
+msgstr "限制"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:202
+msgid ""
+"Dynamic mode is supported for object backends (\"OBJ\", \"AZURE_BLOB\", "
+"\"DOCA_MEMOS\") and file backends (\"POSIX\", \"GDS\", \"GDS_MT\", "
+"\"HF3FS\")."
+msgstr "动态模式支持对象后端（“OBJ”，“AZURE_BLOB”，“DOCA_MEMOS”）和文件后端（“POSIX”，“GDS”，“GDS_MT”，“HF3FS”）。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:203
+msgid "save_unfull_chunk must be set to False."
+msgstr "save_unfull_chunk 必须设置为 False。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:205
+msgid "Example ``lmcache-config.yaml`` for OBJ backend with dynamic mode:"
+msgstr "示例 ``lmcache-config.yaml`` 用于动态模式的 OBJ 后端："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:230
+msgid "Example ``lmcache-config.yaml`` for AZURE_BLOB backend with dynamic mode:"
+msgstr "示例 ``lmcache-config.yaml`` 用于动态模式的 AZURE_BLOB 后端："
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:251
+msgid "DOCA_MEMOS Backend (NVIDIA CMX)"
+msgstr "DOCA_MEMOS 后端 (NVIDIA CMX)"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:253
+msgid ""
+"``DOCA_MEMOS`` stores KV cache on NVIDIA CMX (Context Memory Storage), a "
+"BlueField-4 context-memory tier accessed through NIXL. It is an object-"
+"style backend (like ``OBJ``), supported in both static "
+"(``nixl_pool_size`` > 0) and dynamic (``nixl_pool_size`` = 0) mode. "
+"``nixl_buffer_device`` must be ``cpu``. ``nixl_endpoint_list`` is not "
+"supported for DOCA_MEMOS."
+msgstr ""
+"``DOCA_MEMOS`` 将 KV Cache 存储在 NVIDIA CMX（上下文内存存储）上，这是一个通过 NIXL 访问的 "
+"BlueField-4 上下文内存层。它是一种对象风格的后端（类似于 ``OBJ``\\ ），支持静态模式（\\ "
+"``nixl_pool_size`` > 0）和动态模式（\\ ``nixl_pool_size`` = 0）。\\ "
+"``nixl_buffer_device`` 必须为 ``cpu``\\ 。\\ ``nixl_endpoint_list`` 不支持 "
+"DOCA_MEMOS。"
+
+#: ../../source/kv_cache/storage_backends/nixl.rst:259
+msgid ""
+"Object names are 128-bit lowercase-hex strings: the NIXL DOCA_MEMOS "
+"plugin passes object names as strings and hex-decodes them on the device "
+"side, so each name is exactly 32 hex characters. In dynamic mode this "
+"name is a truncated SHA-256 of the cache key, so names are opaque (they "
+"carry no model/chunk debug information) and uniqueness is probabilistic "
+"at 128 bits."
+msgstr ""
+"对象名称是 128 位小写十六进制字符串：NIXL DOCA_MEMOS "
+"插件将对象名称作为字符串传递，并在设备端进行十六进制解码，因此每个名称恰好是 32 个十六进制字符。在动态模式下，此名称是缓存键的截断 "
+"SHA-256，因此名称是不透明的（它们不携带任何模型/块调试信息），并且唯一性在 128 位上是概率性的。"
+
+#~ msgid "``nixl_buffer_size``: buffer size for NIXL transfers."
+#~ msgstr "``nixl_buffer_size``: NIXL 传输的缓冲区大小。"
+
+#~ msgid ""
+#~ "``nixl_buffer_device``: dictates where the "
+#~ "memory managed by NIXL should be "
+#~ "on. \"cpu\" or \"cuda\" is supported "
+#~ "for \"GDS\", \"GDS_MT\", and \"OBJ\" "
+#~ "backends - for \"POSIX\", \"HF3FS\" &"
+#~ " \"AZURE_BLOB\", must be \"cpu\"."
+#~ msgstr ""
+#~ "``nixl_buffer_device``: 指定 NIXL 管理的内存应该位于何处。对于 "
+#~ "\\\"GDS\\\"、\\\"GDS_MT\\\" 和 \\\"OBJ\\\" 后端，支持 "
+#~ "\\\"cpu\\\" 或 \\\"cuda\\\"；对于 "
+#~ "\\\"POSIX\\\"、\\\"HF3FS\\\" 和 \\\"AZURE_BLOB\\\"，必须为 "
+#~ "\\\"cpu\\\"。"
+
+#~ msgid ""
+#~ "``nixl_use_hugepages``: whether to use Linux"
+#~ " hugepages (2 MiB) for the NIXL "
+#~ "CPU buffer. Not supported for GPU "
+#~ "buffers. Requires pre-allocated hugepages "
+#~ "(``sysctl vm.nr_hugepages``). Default: ``false``."
+#~ msgstr ""
+#~ "``nixl_use_hugepages``: 是否为 NIXL CPU 缓冲区使用 "
+#~ "Linux 大页（2 MiB）。不支持 GPU 缓冲区。需要预分配的大页（``sysctl"
+#~ " vm.nr_hugepages``）。默认值：``false``。"
+
+#~ msgid ""
+#~ "Dynamic mode is currently only supported"
+#~ " for nixl OBJ and AZURE_BLOB "
+#~ "backends."
+#~ msgstr "动态模式目前仅支持 nixl OBJ 和 AZURE_BLOB 后端。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/redis.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/redis.po
new file mode 100644
index 0000000..ab4c754
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/redis.po
@@ -0,0 +1,375 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:2
+msgid "Redis"
+msgstr "Redis"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/resp`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/resp`。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:14
+msgid ""
+"Redis is an in-memory key-value store and is a supported option for "
+"remote KV Cache offloading in LMCache. Some other remote backends are "
+":doc:`Mooncake <./mooncake>`, :doc:`Valkey <./valkey>`, and "
+":doc:`InfiniStore <./infinistore>`. This guide will mainly focus on "
+"single-node Redis but also shows you how to set up Redis Sentinels and an"
+" LMCache Server."
+msgstr ""
+"Redis 是一个内存中的键值存储，是 LMCache 中支持的远程 KV Cache 卸载选项之一。其他一些远程后端包括 "
+":doc:`Mooncake <./mooncake>`、:doc:`Valkey <./valkey>` 和 :doc:`InfiniStore"
+" <./infinistore>`。本指南将主要集中于单节点 Redis，但也会向您展示如何设置 Redis Sentinel 和 LMCache"
+" 服务器。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:19
+msgid "Two ways to configure LMCache Redis Offloading:"
+msgstr "配置 LMCache Redis 卸载的两种方式："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:21
+msgid "**1. Environment Variables:**"
+msgstr "**1. 环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:37
+msgid "**2. Configuration File**:"
+msgstr "**2. 配置文件**:"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:39
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:41
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:58
+msgid "Dynamic Plugin Configuration"
+msgstr "动态插件配置"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:73
+msgid "Remote Storage Explanation:"
+msgstr "远程存储说明："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:75
+msgid ""
+"LMCache's backend is obeys the natural memory hierarchy of prioritizing "
+"CPU RAM offloading, then Local Storage offloading, and finally remote "
+"offloading."
+msgstr "LMCache 的后端遵循自然内存层次结构，优先考虑 CPU RAM 卸载，然后是本地存储卸载，最后是远程卸载。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:78
+msgid ""
+"For LMCache to know how to create a connector to a remote backend, you "
+"must specify in ``remote_url`` a connector type followed by one or most "
+"host:port pairs (depending on what connector type is used). If "
+"``remote_url`` is set to ``None``, LMCache will not use any remote "
+"storage."
+msgstr ""
+"为了让 LMCache 知道如何创建连接器以连接远程后端，您必须在 ``remote_url`` "
+"中指定一个连接器类型，后面跟着一个或多个主机:端口对（具体取决于使用的连接器类型）。如果 ``remote_url`` 设置为 "
+"``None``，LMCache 将不会使用任何远程存储。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:82
+msgid "Examples of ``remote_url``'s:"
+msgstr "``remote_url`` 的示例："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:93
+msgid "Remote Storage Example"
+msgstr "远程存储示例"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:97
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:99
+msgid ""
+"A Machine with at least one GPU. You can adjust the max model length of "
+"your vllm instance depending on your GPU memory."
+msgstr "一台至少配备一个 GPU 的机器。您可以根据您的显存调整 vllm 实例的最大模型长度。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:101
+msgid ""
+"vllm and lmcache installed (:doc:`Installation Guide "
+"<../../getting_started/installation>`)"
+msgstr "vllm 和 lmcache 已安装 (:doc:`安装指南 <../../getting_started/installation>`)"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:103
+msgid "Hugging Face access to ``meta-llama/Meta-Llama-3.1-8B-Instruct``"
+msgstr "Hugging Face 访问 ``meta-llama/Meta-Llama-3.1-8B-Instruct``"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:109
+msgid "**Step 0. Set up a directory for this example:**"
+msgstr "**第 0 步. 为此示例设置一个目录:**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:116
+msgid "**Step 1. Start a Redis server:**"
+msgstr "**步骤 1. 启动 Redis 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:124
+msgid "Check if Redis is running:"
+msgstr "检查 Redis 是否正在运行："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:130
+msgid "Expected Response:"
+msgstr "预期响应："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:136
+msgid "**Optional: Setting up Sentinels:**"
+msgstr "**可选：设置哨兵：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:138
+msgid ""
+"To enable high availability with Redis, you can configure Redis sentinels"
+" to monitor the master and automatically fail over to a replica if "
+"needed."
+msgstr "要通过 Redis 实现高可用性，您可以配置 Redis 哨兵来监控主节点，并在需要时自动切换到副本。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:141
+msgid "**Step 1a. Start a Redis replica:**"
+msgstr "**步骤 1a. 启动 Redis 副本：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:147
+msgid "**Step 1b. Create Sentinel configuration files:**"
+msgstr "**步骤 1b. 创建 Sentinel 配置文件：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:149
+msgid ""
+"Create three files: ``sentinel-26379.conf``, ``sentinel-26380.conf``, and"
+" ``sentinel-26381.conf``, with contents like this:"
+msgstr ""
+"创建三个文件：``sentinel-26379.conf``、``sentinel-26380.conf`` 和 "
+"``sentinel-26381.conf``，内容如下："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:159
+msgid "**Step 1c. Start each Sentinel:**"
+msgstr "**步骤 1c. 启动每个 Sentinel:**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:167
+msgid "**Step 1d. Make sure the Sentinels are tracking the master:**"
+msgstr "**步骤 1d. 确保哨兵正在跟踪主节点：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:175
+msgid "**Step 1e. Verify everything is running:**"
+msgstr "**步骤 1e. 验证一切是否正常运行:**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:181
+msgid "You should see something like this (without the comments):"
+msgstr "您应该看到类似这样的内容（不包括注释）："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:195
+msgid "**Alternative: Starting an LMCache Server:**"
+msgstr "**替代方案：启动 LMCache 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:197
+msgid ""
+"The ``lmcache_server`` CLI entrypoint starts a remote LMCache server and "
+"comes with the ``lmcache`` package."
+msgstr "``lmcache_server`` CLI 入口点启动一个远程 LMCache 服务器，并附带 ``lmcache`` 包。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:206
+msgid ""
+"Currently, the only supported device is \"cpu\" (which is the default, so"
+" you don't need to specify it)."
+msgstr "目前，唯一支持的设备是“cpu”（这是默认值，因此您无需指定它）。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:209
+msgid "**Step 2. Start a vLLM server with remote offloading enabled:**"
+msgstr "**步骤 2. 启动一个启用远程卸载的 vLLM 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:211
+msgid "Create a an lmcache configuration file called: ``redis-offload.yaml``"
+msgstr "创建一个名为 ``redis-offload.yaml`` 的 lmcache 配置文件。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:222
+#: ../../source/kv_cache/storage_backends/redis.rst:250
+#: ../../source/kv_cache/storage_backends/redis.rst:275
+msgid ""
+"If you don't want to use a config file, uncomment the first three "
+"environment variables and then comment out the ``LMCACHE_CONFIG_FILE`` "
+"below:"
+msgstr "如果您不想使用配置文件，请取消注释前面三个环境变量，然后注释掉下面的 ``LMCACHE_CONFIG_FILE``："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:240
+msgid "**Optional: Sentinels**"
+msgstr "**可选：哨兵**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:242
+msgid ""
+"Create a an lmcache configuration file called: ``redis-sentinel-"
+"offload.yaml``"
+msgstr "创建一个名为 ``redis-sentinel-offload.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:265
+msgid "**Alternative: LMCache Server**"
+msgstr "**替代方案：LMCache 服务器**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:267
+msgid ""
+"Create a an lmcache configuration file called: ``lmcache-server-"
+"offload.yaml``"
+msgstr "创建一个名为 ``lmcache-server-offload.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:290
+msgid "**Step 3. Viewing and Managing LMCache Entries in Redis:**"
+msgstr "**步骤 3. 在 Redis 中查看和管理 LMCache 条目:**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:292
+msgid ""
+"If you would like to feel the TTFT speed up with offloading and KV Cache "
+"reuse, feel free to use the same ``query-twice.py`` script and ``man-"
+"bash.txt`` long context as in :doc:`CPU RAM <./cpu_ram>` and :doc:`Local "
+"Storage <./local_storage>`."
+msgstr ""
+"如果您想体验通过卸载和 KV Cache 重用来加速 TTFT 的速度，可以随意使用与 :doc:`CPU RAM <./cpu_ram>` 和 "
+":doc:`Local Storage <./local_storage>` 中相同的 ``query-twice.py`` 脚本和 ``man-"
+"bash.txt`` 长上下文。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:295
+msgid ""
+"Here, we are instead going to demonstrate how to search for and modify "
+"LMCache KV Chunk entries in Redis."
+msgstr "在这里，我们将演示如何在 Redis 中查找和修改 LMCache KV 块条目。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:297
+msgid ""
+"Please note that the official LMCache way to achieve this redis-specific "
+"functionality of viewing and modifying LMCache KV Chunks is available in "
+":doc:`LMCache Controller <../../kv_cache_management/index>`."
+msgstr ""
+"请注意，官方的 LMCache 方法来实现此 Redis 特定功能以查看和修改 LMCache KV 块可在 :doc:`LMCache "
+"Controller <../../kv_cache_management/index>` 中找到。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:299
+msgid "Let's warm/populate LMCache first with ``curl`` this time:"
+msgstr "这次让我们先用 ``curl`` 预热/填充 LMCache："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:316
+msgid ""
+"LMCache stores data in Redis using a structured key format. Each key "
+"contains the following information in a delimited format:"
+msgstr "LMCache 使用结构化键格式在 Redis 中存储数据。每个键包含以下以分隔格式的信息："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:322
+msgid "`model_name`: Name of the language model"
+msgstr "`model_name`: 语言模型的名称"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:323
+msgid "`world_size`: Total number of workers in distributed deployment"
+msgstr "`world_size`: 分布式部署中工作节点的总数"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:324
+msgid ""
+"`worker_id`: ID of the worker that created this cache entry, in the range"
+" of [0, world_size - 1]"
+msgstr "`worker_id`: 创建此缓存条目的工作线程 ID，范围为 [0, world_size - 1]"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:325
+msgid "`chunk_hash`: Hash of the token chunk (SHA-256 based)"
+msgstr "`chunk_hash`: 令牌块的哈希值（基于 SHA-256）"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:327
+msgid "For example, a typical key might look like:"
+msgstr "例如，一个典型的键可能看起来像："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:333
+msgid "**Using redis-cli to View LMCache Data**"
+msgstr "**使用 redis-cli 查看 LMCache 数据**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:335
+msgid "To inspect and manage LMCache entries in Redis:"
+msgstr "要检查和管理 Redis 中的 LMCache 条目："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:341
+msgid "**Optional: If you are using sentinels, first find the master port:**"
+msgstr "**可选：如果您使用的是哨兵，首先找到主端口：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:349
+msgid "**List LMCache keys:**"
+msgstr "**列出 LMCache 键：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:351
+msgid ""
+"Notice (from the suffixes of the keys) that each LMCache KV Chunk has two"
+" entries: ``kv_bytes`` and ``metadata``"
+msgstr "注意（从键的后缀中）每个 LMCache KV 块有两个条目：``kv_bytes`` 和 ``metadata``"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:364
+msgid "**Delete LMCache entries:**"
+msgstr "**删除 LMCache 条目：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:370
+msgid "Delete a specific LMCache entry:"
+msgstr "删除特定的 LMCache 条目："
+
+#: ../../source/kv_cache/storage_backends/redis.rst:379
+msgid "**Check if a key exists:**"
+msgstr "**检查键是否存在：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:385
+msgid "**View memory usage for a key:**"
+msgstr "**查看键的内存使用情况：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:387
+msgid ""
+"Notice that the ``kv_bytes`` entry is what is exactly holding the KV "
+"Chunk and is much larger than the ``metadata`` entry."
+msgstr "请注意，``kv_bytes`` 条目正是持有 KV 块的内容，并且比 ``metadata`` 条目大得多。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:397
+msgid "**Delete specific keys:**"
+msgstr "**删除特定键:**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:411
+msgid "**Monitor Redis in real-time:**"
+msgstr "**实时监控 Redis:**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:417
+msgid "**Get Redis stats for LMCache:**"
+msgstr "**获取 LMCache 的 Redis 统计信息：**"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:427
+msgid ""
+"This tutorial utilized the ``redis-cli`` to directly peak into a remote "
+"backend and manipualte KV Chunks."
+msgstr "本教程使用 ``redis-cli`` 直接查看远程后端并操作 KV 块。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:430
+msgid ""
+"Once again, please refer to the :doc:`LMCache Controller "
+"<../../kv_cache_management/index>` for the official LMCache way of "
+"controlling and routing your KV Caches in your LMCache instances."
+msgstr ""
+"请再次参考 :doc:`LMCache Controller <../../kv_cache_management/index>` 以获取在您的 "
+"LMCache 实例中控制和路由 KV Cache 的官方 LMCache 方法。"
+
+#: ../../source/kv_cache/storage_backends/redis.rst:433
+msgid "**Step 4. Clean up:**"
+msgstr "**步骤 4. 清理：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/resp.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/resp.po
new file mode 100644
index 0000000..1a379aa
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/resp.po
@@ -0,0 +1,716 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:2
+msgid "RESP (Native Redis/Valkey)"
+msgstr "RESP (原生 Redis/Valkey)"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:7
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:9
+msgid ""
+"The RESP backend is a high-performance native C++ storage connector for "
+"Redis and Valkey servers, using the RESP2 wire protocol over TCP. It is "
+"designed for maximum throughput on KV cache store and retrieval "
+"operations, achieving **6+ GB/s** on reads with optimal configuration."
+msgstr "RESP 后端是一个高性能的原生 C++ 存储连接器，适用于 Redis 和 Valkey 服务器，使用 TCP 上的 RESP2 传输协议。它旨在实现 KV Cache 存储和检索操作的最大吞吐量，在最佳配置下读取速度可达到 **6+ GB/s**\\ 。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:13
+msgid "Key advantages over the standard Redis connector:"
+msgstr "相较于标准 Redis 连接器的主要优势："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:15
+msgid ""
+"**Multi-threaded C++ I/O**: Worker threads operate in parallel with zero-"
+"copy buffer passing and full GIL release"
+msgstr "**多线程 C++ I/O**\\ ：工作线程并行操作，采用零拷贝缓冲区传递和完全释放全局解释器锁（GIL）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:16
+msgid ""
+"**Batched tiling**: Large batch operations are automatically split across"
+" worker threads for maximum parallelism"
+msgstr "**批处理切片**\\ ：大型批处理操作会自动在工作线程之间拆分，以实现最大并行性"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:17
+msgid ""
+"**eventfd-based completions**: The kernel wakes Python on completion -- "
+"no polling overhead"
+msgstr "**基于 eventfd 的完成**\\ ：内核在完成时唤醒 Python——没有轮询开销"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:18
+msgid ""
+"**Dual-mode support**: The same C++ connector works in both non-MP mode "
+"(via ``ConnectorClientBase``) and MP mode (via "
+"``NativeConnectorL2Adapter`` as an L2 adapter)"
+msgstr "**双模式支持**\\ ：相同的 C++ 连接器在非 MP 模式（通过 ``ConnectorClientBase``\\ ）和 MP 模式（通过 ``NativeConnectorL2Adapter`` 作为 L2 适配器）下均可工作。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:20
+msgid ""
+"The native C++ source lives in ``csrc/storage_backends/redis/``. See "
+":doc:`Adding Native Connectors "
+"<../../developer_guide/extending_lmcache/native_connectors>` for the full"
+" architecture."
+msgstr "本地 C++ 源代码位于 ``csrc/storage_backends/redis/``\\ 。有关完整架构，请参见 :doc:`添加本地连接器 <../../developer_guide/extending_lmcache/native_connectors>`。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:24
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:26
+msgid ""
+"LMCache installed from source (``pip install -e .``) to compile the C++ "
+"extension"
+msgstr "从源代码安装的 LMCache (``pip install -e .``) 以编译 C++ 扩展"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:27
+msgid ""
+"A Redis 8.2+ or Valkey server (Redis 8.2 recommended for IO threads "
+"support)"
+msgstr "支持 IO 线程的 Redis 8.2+ 或 Valkey 服务器（推荐使用 Redis 8.2）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:28
+msgid "A machine with at least one GPU for vLLM inference"
+msgstr "一台至少配备一个 GPU 的机器用于 vLLM 推理"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:32
+msgid "Redis Server Setup"
+msgstr "Redis 服务器设置"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:35
+msgid ""
+"Redis version and server configuration have a **major** impact on "
+"throughput. Using Redis 8.2 with IO threads yields ~6 GB/s reads vs ~1.5 "
+"GB/s with Redis 6.0 defaults."
+msgstr "Redis 版本和服务器配置对吞吐量有 **重大** 影响。使用 IO 线程的 Redis 8.2 读取速度约为 6 GB/s，而使用 Redis 6.0 默认配置时约为 1.5 GB/s。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:38
+msgid "**Build Redis 8.2 from source (recommended):**"
+msgstr "**从源代码构建 Redis 8.2（推荐）：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:47
+msgid "**Start the server with IO threads enabled:**"
+msgstr "**启用 IO 线程启动服务器：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:58
+msgid "Recommended Server Flags"
+msgstr "推荐的服务器标志"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:62
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:63
+msgid "Why"
+msgstr "为什么"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:64
+msgid "``--protected-mode no``"
+msgstr "``--protected-mode no``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:65
+msgid "Allow connections from other hosts (use auth in production)"
+msgstr "允许来自其他主机的连接（在生产环境中使用认证）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:66
+msgid "``--save '' --appendonly no``"
+msgstr "``--save '' --appendonly no``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:67
+msgid "Disable persistence -- KV cache is ephemeral, persistence wastes bandwidth"
+msgstr "禁用持久性 -- KV Cache 是短暂的，持久性会浪费带宽"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:68
+msgid "``--io-threads 4``"
+msgstr "``--io-threads 4``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:69
+msgid "Enable multi-threaded I/O for parallel read/write handling"
+msgstr "启用多线程 I/O 以实现并行读/写处理"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:70
+msgid "``--port 6379``"
+msgstr "``--port 6379``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:71
+msgid "Default port (adjust if running multiple instances)"
+msgstr "默认端口（如果运行多个实例，请调整）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:74
+msgid ""
+"The number of ``--io-threads`` should roughly match the number of "
+"physical cores available to the Redis process. 4 is a good starting "
+"point; benchmark with your hardware to find the optimum."
+msgstr "``--io-threads`` 的数量应大致与 Redis 进程可用的物理核心数量相匹配。4 是一个不错的起点；请根据您的硬件进行基准测试以找到最佳值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:80
+msgid "Chunk Size Selection and Throughput Tuning"
+msgstr "块大小选择与吞吐量调优"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:82
+msgid ""
+"The chunk size (in tokens) determines how many bytes each Redis key-value"
+" pair holds. This is the **single most important parameter** for "
+"throughput."
+msgstr "块大小（以令牌为单位）决定了每个 Redis 键值对所占用的字节数。这是 **吞吐量最重要的参数**\\ 。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:85
+msgid ""
+"**The sweet spot is ~4 MB per chunk.** Both smaller and larger chunks "
+"degrade throughput:"
+msgstr "**最佳块大小约为 4 MB。** 较小或较大的块都会降低吞吐量："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:87
+msgid "Chunk Size vs Throughput (Redis 8.2, 8 workers)"
+msgstr "块大小与吞吐量（Redis 8.2，8 个工作线程）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:91
+msgid "Chunk Size"
+msgstr "块大小"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:92
+msgid "Total Data"
+msgstr "总数据"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:93
+msgid "SET Throughput"
+msgstr "设置吞吐量"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:94
+msgid "GET Throughput"
+msgstr "获取吞吐量"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:95
+msgid "1 MB (500 keys)"
+msgstr "1 MB (500 个键)"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:96
+msgid "500 MB"
+msgstr "500 MB"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:97
+msgid "~3.5 GB/s"
+msgstr "约 3.5 GB/s"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:98
+msgid "~5.2 GB/s"
+msgstr "~5.2 GB/s"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:99
+msgid "**4 MB (500 keys)**"
+msgstr "**4 MB (500 个键)**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:100
+msgid "**2 GB**"
+msgstr "**2 GB**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:101
+msgid "**~4.4 GB/s**"
+msgstr "**~4.4 GB/s**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:102
+msgid "**~5.9 GB/s**"
+msgstr "**~5.9 GB/s**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:103
+msgid "8 MB (200 keys)"
+msgstr "8 MB (200 个键)"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:104
+msgid "1.6 GB"
+msgstr "1.6 GB"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:105
+msgid "~4.2 GB/s"
+msgstr "约 4.2 GB/s"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:106
+msgid "~1.4 GB/s"
+msgstr "~1.4 GB/s"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:108
+msgid "**Why 4 MB?**"
+msgstr "**为什么是 4 MB？**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:110
+msgid "Below ~2 MB, per-key overhead (RESP framing, TCP round-trips) dominates"
+msgstr "在 ~2 MB 以下，每个键的开销（RESP 帧、TCP 往返时间）占主导地位"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:111
+msgid ""
+"Above ~4 MB, Redis server-side memory allocation and TCP window sizes "
+"become bottlenecks"
+msgstr "超过 ~4 MB 时，Redis 服务器端内存分配和 TCP 窗口大小成为瓶颈。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:112
+msgid ""
+"At 4 MB, the balance between amortized overhead and memory pressure is "
+"optimal"
+msgstr "在 4 MB 时，摊销开销与内存压力之间的平衡是最佳的。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:114
+msgid "**Calculating chunk size in tokens:**"
+msgstr "**计算块大小（以 token 为单位）：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:116
+msgid ""
+"The chunk size in bytes depends on the model's hidden dimension, number "
+"of KV heads, number of layers, and dtype:"
+msgstr "块大小（以字节为单位）取决于模型的隐藏维度、KV 头的数量、层数和数据类型："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:123
+msgid "For ``meta-llama/Llama-3.1-8B-Instruct`` with BFloat16:"
+msgstr "对于 ``meta-llama/Llama-3.1-8B-Instruct`` 使用 BFloat16："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:135
+msgid ""
+"The bytes-per-token calculation varies by model architecture. Larger "
+"models (e.g., 70B) have more layers and larger hidden dimensions, so "
+"fewer tokens are needed per chunk to reach the 4 MB sweet spot."
+msgstr "每个令牌的字节计算因模型架构而异。较大的模型（例如，70B）具有更多的层和更大的隐藏维度，因此每个块所需的令牌数量较少，以达到 4 MB 的最佳点。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:141
+msgid "Throughput Sweep"
+msgstr "吞吐量扫描"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:143
+msgid ""
+"To find the optimal configuration for your hardware, use the included "
+"benchmark:"
+msgstr "要找到适合您硬件的最佳配置，请使用随附的基准测试："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:165
+msgid "Expected output:"
+msgstr "预期输出："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:181
+msgid "Environment Variable Configuration"
+msgstr "环境变量配置"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:183
+msgid ""
+"Sensitive credentials (and optionally host/port) can be provided via "
+"environment variables instead of config files or CLI arguments. This "
+"prevents secrets from appearing in logged configuration at startup."
+msgstr "敏感凭据（可选的主机/端口）可以通过环境变量提供，而不是配置文件或 CLI 参数。这可以防止在启动时将秘密记录到配置日志中。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:191
+msgid "Variable"
+msgstr "变量"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:192
+#: ../../source/kv_cache/storage_backends/resp.rst:322
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:193
+msgid "``LMCACHE_RESP_USERNAME``"
+msgstr "``LMCACHE_RESP_USERNAME``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:194
+msgid ""
+"Redis ACL username. Used as default when ``username`` is not set in "
+"config/JSON."
+msgstr "Redis ACL 用户名。当 ``username`` 在 config/JSON 中未设置时使用该默认值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:195
+msgid "``LMCACHE_RESP_PASSWORD``"
+msgstr "``LMCACHE_RESP_PASSWORD``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:196
+msgid ""
+"Redis AUTH password. Used as default when ``password`` is not set in "
+"config/JSON."
+msgstr "Redis AUTH 密码。当 config/JSON 中未设置 ``password`` 时使用该密码作为默认值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:197
+msgid "``LMCACHE_RESP_HOST``"
+msgstr "``LMCACHE_RESP_HOST``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:198
+msgid ""
+"Redis hostname or IP. Used as default when ``host`` is not set in "
+"config/JSON/URL."
+msgstr "Redis 主机名或 IP。当配置/JSON/URL 中未设置 ``host`` 时使用此默认值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:199
+msgid "``LMCACHE_RESP_PORT``"
+msgstr "``LMCACHE_RESP_PORT``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:200
+msgid "Redis port. Used as default when ``port`` is not set in config/JSON/URL."
+msgstr "Redis 端口。当 ``port`` 在 config/JSON/URL 中未设置时使用此端口作为默认值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:202
+msgid ""
+"Config files (non-MP) and ``--l2-adapter`` JSON (MP) take precedence over"
+" environment variables. Environment variables serve as defaults — they "
+"are used when the corresponding config value is empty or unset. They are "
+"read at adapter creation time inside the adapter itself, so they are "
+"**never stored in the config object** and **never printed in startup "
+"logs**."
+msgstr "配置文件（非多租户）和 ``--l2-adapter`` JSON（多租户）优先于环境变量。环境变量作为默认值使用——当相应的配置值为空或未设置时使用。它们在适配器创建时被读取，因此\\ **从不存储在配置对象中**\\ ，并且\\ **从不在启动日志中打印**\\ 。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:208
+msgid "**Example — MP mode with env vars:**"
+msgstr "**示例 — MP 模式与环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:222
+msgid "**Example — Non-MP mode with env vars:**"
+msgstr "**示例 — 非 MP 模式与环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:236
+msgid ""
+"For production deployments, always use environment variables for "
+"credentials rather than embedding them in config files or CLI arguments."
+msgstr "在生产环境中，始终使用环境变量来存储凭据，而不是将其嵌入配置文件或命令行参数中。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:241
+msgid "Non-MP Mode (Single Process)"
+msgstr "非 MP 模式（单进程）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:243
+msgid ""
+"In non-MP mode, the RESP connector is used directly as a remote storage "
+"backend via the ``RESPClient`` asyncio wrapper."
+msgstr "在非多进程模式下，RESP 连接器通过 ``RESPClient`` asyncio 包装器直接用作远程存储后端。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:246
+msgid "**Configuration file** (``resp-config.yaml``):"
+msgstr "**配置文件** (``resp-config.yaml``):"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:254
+msgid ""
+"Credentials can be set via environment variables (recommended) or in the "
+"config file under ``extra_config`` (see `Environment Variable "
+"Configuration`_ above)."
+msgstr "凭据可以通过环境变量（推荐）或在配置文件的 ``extra_config`` 中设置（请参见上面的 `环境变量配置`_）。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:257
+msgid "**Launch vLLM:**"
+msgstr "**启动 vLLM:**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:268
+msgid ""
+"``save_unfull_chunk`` must be off (default) and chunk metadata saving "
+"must be disabled for optimal throughput with the native RESP connector."
+msgstr "``save_unfull_chunk`` 必须关闭（默认）并且必须禁用块元数据保存，以便在使用原生 RESP 连接器时实现最佳吞吐量。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:273
+msgid "MP Mode (Multiprocess)"
+msgstr "MP 模式（多进程）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:275
+msgid ""
+"In MP mode, LMCache runs as a separate server process communicating with "
+"vLLM over ZMQ. The RESP connector serves as an L2 adapter with variable-"
+"size chunk support."
+msgstr "在 MP 模式下，LMCache 作为一个独立的服务器进程运行，通过 ZMQ 与 vLLM 进行通信。RESP 连接器作为一个具有可变大小块支持的 L2 适配器。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:278
+msgid "**Step 1: Start Redis** (see `Redis Server Setup`_ above)"
+msgstr "**步骤 1：启动 Redis**\\ （请参见上面的 `Redis Server Setup`_）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:280
+msgid "**Step 2: Launch LMCache MP Server:**"
+msgstr "**步骤 2：启动 LMCache MP 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:291
+msgid "**Step 3: Launch vLLM with LMCache MP Connector:**"
+msgstr "**步骤 3：启动带有 LMCache MP 连接器的 vLLM：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:311
+msgid "L2 Adapter Configuration"
+msgstr "L2 适配器配置"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:313
+msgid "The ``--l2-adapter`` JSON accepts these fields:"
+msgstr "``--l2-adapter`` JSON 接受以下字段："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:319
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:320
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:321
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:323
+msgid "``type``"
+msgstr "``type``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:324
+#: ../../source/kv_cache/storage_backends/resp.rst:328
+#: ../../source/kv_cache/storage_backends/resp.rst:340
+#: ../../source/kv_cache/storage_backends/resp.rst:344
+msgid "str"
+msgstr "字符串"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:325
+#: ../../source/kv_cache/storage_backends/resp.rst:329
+#: ../../source/kv_cache/storage_backends/resp.rst:333
+msgid "(required)"
+msgstr "（必需）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:326
+msgid "Must be ``\"resp\"``"
+msgstr "必须是 ``\"resp\"``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:327
+msgid "``host``"
+msgstr "``host``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:330
+msgid "Redis/Valkey hostname or IP"
+msgstr "Redis/Valkey 主机名或 IP"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:331
+msgid "``port``"
+msgstr "``port``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:332
+#: ../../source/kv_cache/storage_backends/resp.rst:336
+msgid "int"
+msgstr "整数"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:334
+msgid "Redis/Valkey port"
+msgstr "Redis/Valkey 端口"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:335
+msgid "``num_workers``"
+msgstr "``num_workers``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:337
+msgid "8"
+msgstr "8"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:338
+msgid "C++ worker threads for parallel I/O"
+msgstr "用于并行 I/O 的 C++ 工作线程"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:339
+msgid "``username``"
+msgstr "``username``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:341
+#: ../../source/kv_cache/storage_backends/resp.rst:345
+msgid "``\"\"``"
+msgstr "``\"\"``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:342
+msgid ""
+"Redis ACL username (leave empty for no auth). Falls back to "
+"``LMCACHE_RESP_USERNAME`` env var if empty."
+msgstr "Redis ACL 用户名（留空以不进行身份验证）。如果为空，将回退到 ``LMCACHE_RESP_USERNAME`` 环境变量。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:343
+msgid "``password``"
+msgstr "``密码``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:346
+msgid ""
+"Redis AUTH password (leave empty for no auth). Falls back to "
+"``LMCACHE_RESP_PASSWORD`` env var if empty."
+msgstr "Redis AUTH 密码（留空表示不进行身份验证）。如果为空，将回退到 ``LMCACHE_RESP_PASSWORD`` 环境变量。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:347
+msgid "``max_capacity_gb``"
+msgstr "``max_capacity_gb``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:348
+msgid "float"
+msgstr "浮点数"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:349
+msgid "0"
+msgstr "0"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:350
+msgid ""
+"Maximum L2 storage capacity in GB for client-side usage tracking. "
+"Required for L2 eviction. Set to 0 (default) to disable usage tracking."
+msgstr "用于客户端使用跟踪的最大 L2 存储容量（以 GB 为单位）。这是 L2 逐出的必要条件。设置为 0（默认值）以禁用使用跟踪。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:353
+msgid "L2 Eviction"
+msgstr "L2 逐出"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:355
+msgid ""
+"To enable automatic eviction of least-recently-used keys when the Redis "
+"backend fills up, set ``max_capacity_gb`` and add an ``\"eviction\"`` "
+"block:"
+msgstr "要启用在 Redis 后端填满时自动逐出最近最少使用的键，请设置 ``max_capacity_gb`` 并添加一个 ``\"eviction\"`` 块："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:378
+#, python-format
+msgid ""
+"This configures a 10 GB capacity limit. When usage exceeds 80% "
+"(``trigger_watermark``), the eviction controller will delete the least-"
+"recently-used ~20% of stored keys (``eviction_ratio``) using the Redis "
+"``DEL`` command."
+msgstr "这配置了 10 GB 的容量限制。当使用量超过 80%（\\ ``trigger_watermark``\\ ）时，逐出控制器将使用 Redis ``DEL`` 命令删除最近最少使用的 ~20% 存储的键（\\ ``eviction_ratio``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:383
+msgid ""
+"``max_capacity_gb`` enables **client-side** size tracking. It does not "
+"configure the Redis server's ``maxmemory`` setting. You should set "
+"``max_capacity_gb`` to match or be slightly below your Redis server's "
+"available memory."
+msgstr "``max_capacity_gb`` 启用 **客户端** 大小跟踪。它并不配置 Redis 服务器的 ``maxmemory`` 设置。您应该将 ``max_capacity_gb`` 设置为与 Redis 服务器的可用内存相匹配或略低于该值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:389
+msgid "Testing the Setup"
+msgstr "测试设置"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:391
+msgid ""
+"Send the same prompt twice. The first request stores KV cache to Redis; "
+"the second retrieves it."
+msgstr "两次发送相同的提示。第一次请求将 KV Cache 存储到 Redis；第二次请求检索它。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:408
+msgid "Verify data was stored:"
+msgstr "验证数据是否已存储："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:414
+msgid "Clear state between runs:"
+msgstr "在运行之间清除状态："
+
+#: ../../source/kv_cache/storage_backends/resp.rst:422
+msgid "Best Practices"
+msgstr "最佳实践"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:424
+msgid "**Server deployment:**"
+msgstr "**服务器部署：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:426
+msgid "Use Redis 8.2+ with ``--io-threads 4`` (or more, matching available cores)"
+msgstr "使用 Redis 8.2+ 和 ``--io-threads 4``\\ （或更多，匹配可用核心）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:427
+msgid "Disable persistence (``--save '' --appendonly no``) for KV cache workloads"
+msgstr "禁用持久化（\\ ``--save '' --appendonly no``\\ ）以支持 KV Cache 工作负载"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:428
+msgid "Pin Redis to its own NUMA node if running on multi-socket systems"
+msgstr "在多插槽系统上将 Redis 固定到其自己的 NUMA 节点"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:429
+msgid ""
+"For production, enable authentication with ``--requirepass`` and supply "
+"credentials via ``LMCACHE_RESP_USERNAME`` / ``LMCACHE_RESP_PASSWORD`` "
+"environment variables to keep them out of logs"
+msgstr "在生产环境中，使用 ``--requirepass`` 启用身份验证，并通过 ``LMCACHE_RESP_USERNAME`` / ``LMCACHE_RESP_PASSWORD`` 环境变量提供凭据，以避免将其记录到日志中。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:431
+msgid "**Client tuning:**"
+msgstr "**客户端调优:**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:433
+msgid ""
+"Start with ``num_workers: 8`` and increase if the server has spare CPU "
+"and you're not saturating the network"
+msgstr "从 ``num_workers: 8`` 开始，如果服务器有多余的 CPU 并且网络没有饱和，则可以增加该值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:434
+msgid ""
+"More workers help when chunk sizes are smaller (more keys per batch = "
+"more parallelism needed)"
+msgstr "当块大小较小时，更多的工作线程会有所帮助（每批次更多的键 = 需要更多的并行性）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:435
+msgid ""
+"On NUMA systems, ensure the LMCache process runs on the same NUMA node as"
+" the NIC"
+msgstr "在 NUMA 系统上，确保 LMCache 进程与 NIC 运行在同一个 NUMA 节点上。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:437
+msgid "**Chunk size:**"
+msgstr "**块大小:**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:439
+msgid "Target ~4 MB per chunk for maximum throughput"
+msgstr "每个块目标约 4 MB，以实现最大吞吐量"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:440
+msgid ""
+"Calculate the token count using your model's per-token byte size (see "
+"formula above)"
+msgstr "使用模型的每个 token 字节大小计算 token 数量（请参见上面的公式）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:441
+msgid ""
+"If unsure, run the benchmark sweep to find the optimum for your specific "
+"hardware"
+msgstr "如果不确定，请运行基准测试以找到适合您特定硬件的最佳值。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:443
+msgid "**Network:**"
+msgstr "**网络：**"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:445
+msgid "Use localhost or loopback for single-machine deployments"
+msgstr "在单机部署中使用 localhost 或回环地址"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:446
+msgid ""
+"For cross-machine setups, ensure low-latency networking (ideally <100 us "
+"RTT)"
+msgstr "对于跨机器设置，确保低延迟网络（理想情况下 <100 微秒 RTT）"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:447
+msgid ""
+"The RESP connector uses TCP; RDMA is not currently supported (consider "
+":doc:`Mooncake <./mooncake>` for RDMA)"
+msgstr "RESP 连接器使用 TCP；目前不支持 RDMA（考虑使用 :doc:`Mooncake <./mooncake>` 进行 RDMA）。"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:451
+msgid "Additional Resources"
+msgstr "附加资源"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:453
+msgid ""
+"Benchmark script: "
+"``examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py``"
+msgstr "基准测试脚本：\\ ``examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:454
+msgid "C++ source: ``csrc/storage_backends/redis/``"
+msgstr "C++ 源码: ``csrc/storage_backends/redis/``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:455
+msgid "Native connector architecture: ``csrc/storage_backends/README.md``"
+msgstr "本地连接器架构: ``csrc/storage_backends/README.md``"
+
+#: ../../source/kv_cache/storage_backends/resp.rst:456
+msgid ""
+"Developer guide for adding new native connectors: :doc:`Adding Native "
+"Connectors <../../developer_guide/extending_lmcache/native_connectors>`"
+msgstr "添加新原生连接器的开发者指南： :doc:`添加原生连接器 <../../developer_guide/extending_lmcache/native_connectors>`"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/s3.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/s3.po
new file mode 100644
index 0000000..3dea72b
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/s3.po
@@ -0,0 +1,231 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:2
+msgid "S3 Backend"
+msgstr "S3 后端"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:5
+msgid "Example Configurations"
+msgstr "示例配置"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:8
+msgid "Basic S3 Configuration"
+msgstr "基本 S3 配置"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:24
+msgid "S3 Express One Zone"
+msgstr "S3 Express One Zone"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:42
+msgid "CoreWeave (S3-compatible)"
+msgstr "CoreWeave (S3 兼容)"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:64
+msgid ""
+"**Note**: `cwlota.com` is CoreWeave's S3-compatible Cloud Storage that "
+"caches for GPU locality. You can set `disable_tls: True` for non-AWS "
+"services."
+msgstr "**注意**\\ ：`cwlota.com` 是 CoreWeave 的 S3 兼容云存储，旨在为 GPU 本地性提供缓存。您可以将 `disable_tls: True` 设置为非 AWS 服务。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:66
+msgid ""
+"Check out the blog post between LMCache, Cohere, and CoreWeave: "
+"https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-"
+"lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/"
+msgstr "查看 LMCache、Cohere 和 CoreWeave 之间的博客文章：https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:70
+msgid "Configuration Parameters"
+msgstr "配置参数"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:72
+msgid "**remote_url**: S3 bucket URL (`s3://bucket-name`)"
+msgstr "**remote_url**: S3 存储桶 URL (`s3://bucket-name`)"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:73
+msgid ""
+"**save_unfull_chunk**: Save partial chunks (default: False, **must be "
+"False for S3**)"
+msgstr "**save_unfull_chunk**: 保存部分块（默认值：False，\\ **对于 S3 必须为 False**\\ ）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:74
+msgid "**enable_async_loading**: Async loading (default: False)"
+msgstr "**enable_async_loading**: 异步加载（默认值：False）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:75
+msgid "**blocking_timeout_secs**: Timeout seconds (default: 10)"
+msgstr "**blocking_timeout_secs**: 超时秒数（默认值：10）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:78
+msgid "S3-Specific (in extra_config)"
+msgstr "S3 特定（在 extra_config 中）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:80
+msgid "**s3_region**: AWS region for S3 client (required)"
+msgstr "**s3_region**: S3 客户端的 AWS 区域（必需）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:81
+msgid ""
+"**s3_num_io_threads**: Number of IO threads for the AWS CRT client to "
+"spawn. Benefits taper out after exceeding the number of CPU cores. This "
+"is also a way to restrict the number of outgoing requests in case your "
+"S3-compatible object store has a rate-limiting gateway."
+msgstr "**s3_num_io_threads**: AWS CRT 客户端生成的 IO 线程数量。超过 CPU 核心数量后，收益会逐渐减少。这也是限制外发请求数量的一种方式，以防您的 S3 兼容对象存储具有速率限制网关。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:82
+msgid ""
+"**s3_prefer_http2**: Enable HTTP/2 with ALPN negotiation ([\"h2\", "
+"\"http/1.1\"])"
+msgstr "**s3_prefer_http2**: 启用带有 ALPN 协商的 HTTP/2 ([\\\"h2\\\", \\\"http/1.1\\\"])"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:83
+msgid ""
+"**s3_enable_s3express**: Enable S3 Express One Zone support in AWS CRT "
+"client"
+msgstr "**s3_enable_s3express**: 在 AWS CRT 客户端中启用 S3 Express 单区支持"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:84
+msgid ""
+"**save_chunk_meta**: Whether to save chunk metadata in the object store "
+"along with your data (False required for S3)"
+msgstr "**save_chunk_meta**: 是否在对象存储中与您的数据一起保存块元数据（对于 S3，需设置为 False）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:85
+msgid ""
+"**aws_access_key_id**: AWS access key ID (or log in with `aws configure` "
+"in your environment)"
+msgstr "**aws_access_key_id**: AWS 访问密钥 ID（或在您的环境中使用 `aws configure` 登录）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:86
+msgid ""
+"**aws_secret_access_key**: AWS secret access key (or log in with `aws "
+"configure` in your environment)"
+msgstr "**aws_secret_access_key**: AWS 秘密访问密钥（或在您的环境中使用 `aws configure` 登录）"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:88
+msgid "**Tips:**::"
+msgstr "**提示:**::"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:92
+msgid "Consider S3 Express One Zone for less redundancy but better performance"
+msgstr "考虑使用 S3 Express One Zone，以获得更少的冗余但更好的性能。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:96
+msgid "MP Mode Configuration"
+msgstr "MP 模式配置"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:98
+msgid ""
+"In multi-process (MP) mode, S3 is configured as an L2 adapter via a JSON "
+"spec passed to the LMCache server, rather than through ``remote_url`` + "
+"``extra_config``. Each ``--l2-adapter`` argument takes a JSON object "
+"whose ``\"type\": \"s3\"`` field selects the S3 adapter."
+msgstr "在多进程（MP）模式下，S3 通过传递给 LMCache 服务器的 JSON 规范配置为 L2 适配器，而不是通过 ``remote_url`` + ``extra_config``\\ 。每个 ``--l2-adapter`` 参数接受一个 JSON 对象，其 ``\\\"type\\\": \\\"s3\\\"`` 字段选择 S3 适配器。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:122
+msgid "S3 L2 Adapter Fields"
+msgstr "S3 L2 适配器字段"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:124
+msgid "**type** (required): must be ``\"s3\"``."
+msgstr "**类型**\\ （必需）：必须是 ``\"s3\"``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:125
+msgid ""
+"**s3_endpoint** (required): bucket URL. Accepts either ``s3://bucket`` or"
+" the bare host form (e.g. ``bucket.s3.us-east-1.amazonaws.com``)."
+msgstr "**s3_endpoint** (必需): 存储桶 URL。接受 ``s3://bucket`` 或裸主机形式（例如 ``bucket.s3.us-east-1.amazonaws.com``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:127
+msgid "**s3_region** (required): AWS region for the S3 client."
+msgstr "**s3_region** (必需): S3 客户端的 AWS 区域。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:128
+msgid "**s3_num_io_threads**: number of CRT IO threads (default ``64``)."
+msgstr "**s3_num_io_threads**: CRT IO 线程的数量（默认 ``64``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:129
+msgid ""
+"**s3_prefer_http2**: attempt HTTP/2 via ALPN negotiation (default "
+"``true``)."
+msgstr "**s3_prefer_http2**: 通过 ALPN 协商尝试 HTTP/2（默认 ``true``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:130
+msgid ""
+"**s3_enable_s3express**: enable S3 Express One Zone signing (default "
+"``false``)."
+msgstr "**s3_enable_s3express**: 启用 S3 Express 单区域签名（默认 ``false``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:131
+msgid ""
+"**disable_tls**: bypass TLS, for non-AWS HTTP endpoints (default "
+"``false``)."
+msgstr "**disable_tls**: 跳过 TLS，用于非 AWS HTTP 端点（默认 ``false``\\ ）。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:132
+msgid ""
+"**aws_access_key_id**, **aws_secret_access_key**: optional static "
+"credentials. When omitted the adapter uses the AWS default credentials "
+"chain (``aws configure``, environment variables, IRSA, etc.)."
+msgstr "**aws_access_key_id**, **aws_secret_access_key**: 可选的静态凭证。当省略时，适配器使用 AWS 默认凭证链（\\ ``aws configure``\\ 、环境变量、IRSA 等）。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:135
+msgid ""
+"**max_capacity_gb**: capacity used by ``get_usage()`` for watermark-based"
+" L2 eviction. Set to ``0`` (default) to disable usage tracking — "
+"``get_usage()`` then returns ``(-1.0, -1.0)`` and no automatic eviction "
+"is triggered."
+msgstr "**max_capacity_gb**: ``get_usage()`` 用于基于水印的 L2 逐出所使用的容量。设置为 ``0``\\ （默认）以禁用使用跟踪 — ``get_usage()`` 将返回 ``(-1.0, -1.0)``\\ ，并且不会触发自动逐出。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:138
+msgid ""
+"**eviction**: optional sub-dict enabling the L2 eviction controller for "
+"this adapter. See :class:`L2AdapterConfigBase` ``_parse_eviction_config``"
+" for the full schema. When present, keys that are currently being loaded "
+"(reference-counted by the lookup-and-lock path) are skipped by "
+"``delete()``."
+msgstr "**逐出**\\ ：可选的子字典，启用此适配器的 L2 逐出控制器。有关完整的架构，请参见 :class:`L2AdapterConfigBase` ``_parse_eviction_config``\\ 。当存在时，当前正在加载的键（通过查找和锁定路径进行引用计数）将被 ``delete()`` 跳过。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:145
+msgid "Differences vs Non-MP S3"
+msgstr "与非多租户 S3 的区别"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:147
+msgid ""
+"The MP adapter honors first-class eviction: it implements ``delete()`` "
+"(real S3 ``DeleteObject``), refcounted ``submit_unlock``, and "
+"``get_usage()`` driven by ``max_capacity_gb``."
+msgstr "MP 适配器支持一流的逐出：它实现了 ``delete()``\\ （真实的 S3 ``DeleteObject``\\ ）、引用计数的 ``submit_unlock`` 和由 ``max_capacity_gb`` 驱动的 ``get_usage()``\\ 。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:150
+msgid ""
+"Keys are identified by ``ObjectKey`` (``model_name`` + ``kv_rank`` + "
+"``chunk_hash``) rather than ``CacheEngineKey``. The wire-format object "
+"name is ``<model>@<kv_rank_hex>@<chunk_hash_hex>``, which is **not** "
+"compatible with the non-MP naming. A bucket populated by non-MP LMCache "
+"cannot be read directly by MP LMCache and vice versa."
+msgstr "键通过 ``ObjectKey`` (``model_name`` + ``kv_rank`` + ``chunk_hash``) 而不是 ``CacheEngineKey`` 来识别。线格式对象名称为 ``<model>@<kv_rank_hex>@<chunk_hash_hex>``\\ ，这与非 MP 命名 **不** 兼容。由非 MP LMCache 填充的桶不能被 MP LMCache 直接读取，反之亦然。"
+
+#: ../../source/kv_cache/storage_backends/s3.rst:155
+msgid "Unfull chunks are rejected (same constraint as non-MP)."
+msgstr "未填充的块会被拒绝（与非 MP 的约束相同）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/sagemaker_hyperpod.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/sagemaker_hyperpod.po
new file mode 100644
index 0000000..3d0738c
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/sagemaker_hyperpod.po
@@ -0,0 +1,185 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:2
+msgid "SageMaker Hyperpod"
+msgstr "SageMaker Hyperpod"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:10
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:12
+msgid ""
+"Create an Amazon SageMaker HyperPod cluster with tiered storage enabled "
+"by following the instructions at:"
+msgstr "按照以下说明创建一个启用分层存储的 Amazon SageMaker HyperPod 集群："
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:14
+msgid ""
+"https://docs.aws.amazon.com/sagemaker/latest/dg/managed-tier-"
+"checkpointing-setup.html"
+msgstr ""
+"https://docs.aws.amazon.com/sagemaker/latest/dg/managed-tier-"
+"checkpointing-setup.html"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:16
+msgid ""
+"This enables the ai-toolkit daemon that provides shared memory access for"
+" LMCache."
+msgstr "这启用提供 LMCache 共享内存访问的 ai-toolkit 守护进程。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:19
+msgid "Example Configuration"
+msgstr "示例配置"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:29
+msgid "Configuration Parameters"
+msgstr "配置参数"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:32
+msgid "SageMaker Hyperpod-Specific (in extra_config)"
+msgstr "SageMaker Hyperpod 特定（在 extra_config 中）"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:34
+msgid ""
+"**sagemaker_hyperpod_bucket**: Bucket name for KV storage namespace "
+"(default: \"lmcache\")"
+msgstr "**sagemaker_hyperpod_bucket**: KV 存储命名空间的桶名称（默认: \"lmcache\"）"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:35
+msgid ""
+"**sagemaker_hyperpod_shared_memory_name**: Name of shared memory segment "
+"(default: \"shared_memory\"). Set to None to disable shared memory."
+msgstr ""
+"**sagemaker_hyperpod_shared_memory_name**: 共享内存段的名称（默认: "
+"\"shared_memory\"）。设置为 None 以禁用共享内存。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:36
+msgid ""
+"**sagemaker_hyperpod_max_concurrent_requests**: Maximum concurrent HTTP "
+"requests allowed in-flight at any moment (application-level throttling, "
+"default: 100, minimum: 1). This limit is per LMCache engine instance. "
+"With multiple workers (e.g., high TP), each worker creates its own engine"
+" with separate limits."
+msgstr ""
+"**sagemaker_hyperpod_max_concurrent_requests**: 每时每刻允许的最大并发 HTTP "
+"请求数（应用级限流，默认值：100，最小值：1）。此限制适用于每个 LMCache 引擎实例。对于多个工作进程（例如，高 "
+"TP），每个工作进程创建自己的引擎并具有独立的限制。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:37
+msgid ""
+"**sagemaker_hyperpod_max_connections**: Maximum total TCP connections in "
+"the connection pool per LMCache engine across all daemons (default: 256, "
+"minimum: 1). For typical single-daemon setups, this effectively limits "
+"connections from one engine to one daemon. With N workers per node, total"
+" connections to the daemon = N × this value."
+msgstr ""
+"**sagemaker_hyperpod_max_connections**: 每个 LMCache 引擎在所有守护进程中的连接池中允许的最大 "
+"TCP 连接总数（默认：256，最小：1）。对于典型的单守护进程设置，这实际上限制了一个引擎与一个守护进程之间的连接。每个节点的 N "
+"个工作线程与守护进程的总连接数 = N × 此值。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:38
+msgid ""
+"**sagemaker_hyperpod_max_connections_per_host**: Maximum TCP connections "
+"per LMCache engine to a single daemon address (IP:port) (default: 128, "
+"minimum: 1). \"Host\" refers to the daemon's network address, not the "
+"client machine. For today's typical single-daemon setup, this has similar"
+" effect as max_connections. This parameter enables future multi-daemon "
+"configurations where one engine connects to multiple daemons for load "
+"balancing. With N workers per node connecting to the same daemon, total "
+"connections = N × this value. Reduce proportionally for high TP setups "
+"(e.g., set to 16 for 8 workers to achieve ~128 total connections)."
+msgstr ""
+"**sagemaker_hyperpod_max_connections_per_host**: 每个 LMCache "
+"引擎到单个守护进程地址（IP:端口）的最大 TCP "
+"连接数（默认：128，最小：1）。“主机”指的是守护进程的网络地址，而不是客户端机器。对于今天典型的单守护进程设置，这与 "
+"max_connections "
+"的效果相似。此参数支持未来的多守护进程配置，其中一个引擎可以连接多个守护进程以实现负载均衡。对于每个节点连接到同一守护进程的 N "
+"个工作者，总连接数 = N × 此值。对于高吞吐量设置，按比例减少（例如，对于 8 个工作者设置为 16，以实现 ~128 个总连接）。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:39
+msgid ""
+"**sagemaker_hyperpod_timeout_ms**: Timeout for lease acquisition requests"
+" in milliseconds (default: 5000, minimum: 100)"
+msgstr "**sagemaker_hyperpod_timeout_ms**: 租约获取请求的超时时间（毫秒）（默认值：5000，最小值：100）"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:40
+msgid ""
+"**sagemaker_hyperpod_lease_ttl_s**: Server-side lease timeout in seconds "
+"(default: 30.0)"
+msgstr "**sagemaker_hyperpod_lease_ttl_s**: 服务器端租约超时时间（单位：秒，默认值：30.0）"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:41
+msgid ""
+"**sagemaker_hyperpod_put_stream_chunk_bytes**: Chunk size for streaming "
+"PUT requests in bytes (default: 65536, minimum: 1024)"
+msgstr ""
+"**sagemaker_hyperpod_put_stream_chunk_bytes**: 流式 PUT 请求的块大小（以字节为单位）（默认: "
+"65536，最小: 1024）"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:42
+msgid ""
+"**sagemaker_hyperpod_use_https**: Enable HTTPS instead of HTTP (default: "
+"False). **Note**: Ignored if ``remote_url`` already contains ``http://`` "
+"or ``https://`` protocol."
+msgstr ""
+"**sagemaker_hyperpod_use_https**: 启用 HTTPS 而不是 HTTP（默认: False）。\\ **注意**:"
+" 如果 ``remote_url`` 已经包含 ``http://`` 或 ``https://`` 协议，则忽略此设置。"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:43
+msgid ""
+"**save_chunk_meta**: Whether to save chunk metadata with data (set False "
+"for performance)"
+msgstr "**save_chunk_meta**: 是否将块元数据与数据一起保存（为提高性能设置为 False）"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:46
+msgid "Kubernetes Deployment Requirements"
+msgstr "Kubernetes 部署要求"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:49
+msgid "Environment Variable for Node IP"
+msgstr "节点 IP 的环境变量"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:51
+msgid ""
+"Add the ``NODE_IP`` environment variable to resolve the local node's IP "
+"address:"
+msgstr "添加 ``NODE_IP`` 环境变量以解析本地节点的 IP 地址："
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:62
+msgid "/dev/shm Volume Configuration"
+msgstr "/dev/shm 卷配置"
+
+#: ../../source/kv_cache/storage_backends/sagemaker_hyperpod.rst:64
+msgid ""
+"SageMaker Hyperpod requires /dev/shm for high-performance shared memory "
+"operations:"
+msgstr "SageMaker Hyperpod 需要 /dev/shm 以进行高性能共享内存操作："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/valkey.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/valkey.po
new file mode 100644
index 0000000..8f3fa88
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/valkey.po
@@ -0,0 +1,304 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:2
+msgid "Valkey"
+msgstr "Valkey"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/resp`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/resp`。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:10
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:12
+msgid ""
+"Valkey is an open source (BSD) high-performance key/value datastore and "
+"is a supported option for remote KV Cache offloading in LMCache. Some "
+"other remote backends are :doc:`Mooncake <./mooncake>`, :doc:`Redis "
+"<./redis>`, and :doc:`InfiniStore <./infinistore>`."
+msgstr ""
+"Valkey 是一个开源（BSD）高性能键值数据存储，并且是 LMCache 中支持的远程 KV Cache 卸载选项之一。其他一些远程后端包括 "
+":doc:`Mooncake <./mooncake>`、:doc:`Redis <./redis>` 和 :doc:`InfiniStore "
+"<./infinistore>`。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:16
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:18
+msgid "To use this connector, you need valkey-glide 2.0 or higher."
+msgstr "要使用此连接器，您需要 valkey-glide 2.0 或更高版本。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:26
+msgid "Configuration Reference"
+msgstr "配置参考"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:28
+msgid "The following ``extra_config`` keys are supported:"
+msgstr "支持以下 ``extra_config`` 键："
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:34
+msgid "Key"
+msgstr "键"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:35
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:36
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:37
+msgid "``valkey_num_workers``"
+msgstr "``valkey_num_workers``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:38
+msgid "``8``"
+msgstr "``8``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:39
+msgid "Number of worker threads, each with its own GLIDE client connection."
+msgstr "每个 GLIDE 客户端连接的工作线程数量。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:40
+msgid "``valkey_mode``"
+msgstr "``valkey_mode``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:41
+msgid "``\"standalone\"``"
+msgstr "``\"standalone\"``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:42
+msgid ""
+"``\"standalone\"`` or ``\"cluster\"``. Cluster mode auto-discovers "
+"topology from a seed node."
+msgstr "``\"standalone\"`` 或 ``\"cluster\"``。集群模式从种子节点自动发现拓扑。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:43
+msgid "``tls_enable``"
+msgstr "``tls_enable``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:44
+#: ../../source/kv_cache/storage_backends/valkey.rst:56
+msgid "``false``"
+msgstr "``false``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:45
+msgid "Enable TLS. Required for ElastiCache Serverless."
+msgstr "启用 TLS。ElastiCache Serverless 需要此项。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:46
+msgid "``valkey_username``"
+msgstr "``valkey_username``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:47
+#: ../../source/kv_cache/storage_backends/valkey.rst:50
+msgid "``\"\"``"
+msgstr "``\"\"``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:48
+msgid "Authentication username."
+msgstr "认证用户名。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:49
+msgid "``valkey_password``"
+msgstr "``valkey_password``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:51
+msgid "Authentication password."
+msgstr "认证密码。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:52
+msgid "``valkey_database``"
+msgstr "``valkey_database``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:53
+msgid "None"
+msgstr "无"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:54
+msgid "Database ID (standalone mode only, ignored in cluster mode)."
+msgstr "数据库 ID（仅在独立模式下使用，在集群模式下被忽略）。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:55
+msgid "``valkey_enable_ttl``"
+msgstr "``valkey_enable_ttl``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:57
+msgid ""
+"Feature flag. When ``true``, every key is written with an expiry (see "
+"``valkey_ttl_sec``) so Valkey/Redis ``volatile-*`` eviction policies can "
+"reclaim L2 cache keys once the node reaches ``maxmemory``. When ``false``"
+" (default), keys are persisted without a TTL."
+msgstr ""
+"特性标志。当为 ``true`` 时，每个键都带有过期时间（参见 ``valkey_ttl_sec``），因此 Valkey/Redis 的 "
+"``volatile-*`` 逐出策略可以在节点达到 ``maxmemory`` 时回收 L2 缓存键。当为 "
+"``false``（默认值）时，键会被持久化而不带 TTL。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:58
+msgid "``valkey_ttl_sec``"
+msgstr "``valkey_ttl_sec``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:59
+msgid "``86400``"
+msgstr "``86400``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:60
+msgid ""
+"Key TTL in seconds, applied only when ``valkey_enable_ttl`` is ``true``. "
+"Must be a positive integer. If the flag is enabled but this key is "
+"omitted, it defaults to ``86400`` (24 hours)."
+msgstr ""
+"键的 TTL（生存时间），仅在 ``valkey_enable_ttl`` 为 ``true`` "
+"时应用。必须是正整数。如果启用该标志但未提供此键，则默认为 ``86400``（24 小时）。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:61
+msgid "``request_timeout``"
+msgstr "``request_timeout``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:62
+msgid "``5.0``"
+msgstr "``5.0``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:63
+msgid ""
+"GLIDE request timeout in seconds. Also used as the Python-side Future "
+"timeout."
+msgstr "GLIDE 请求超时时间（以秒为单位）。也用于 Python 端的 Future 超时。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:64
+msgid "``connection_timeout``"
+msgstr "``connection_timeout``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:65
+msgid "``10.0``"
+msgstr "``10.0``"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:66
+msgid "GLIDE connection timeout in seconds for initial client connections."
+msgstr "初始客户端连接的 GLIDE 连接超时时间（以秒为单位）。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:69
+msgid "Example Configurations"
+msgstr "示例配置"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:72
+msgid "Standalone-mode"
+msgstr "独立模式"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:75
+msgid "Basic Valkey Configuration (Standalone-mode)"
+msgstr "基本 Valkey 配置（独立模式）"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:87
+msgid "Standalone-mode Valkey Configuration with database"
+msgstr "带数据库的独立模式 Valkey 配置"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:100
+msgid "Standalone-mode Valkey Configuration with key TTL (volatile eviction)"
+msgstr "带有键 TTL（易失性逐出）的独立模式 Valkey 配置"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:102
+msgid ""
+"Enable a per-key TTL so a node configured with a ``volatile-lru`` / "
+"``volatile-lfu`` eviction policy can reclaim L2 cache keys once it "
+"reaches ``maxmemory``. Without a TTL such policies never evict the KV "
+"cache keys, which can choke the remote cache."
+msgstr ""
+"启用每个键的 TTL，以便配置为 ``volatile-lru`` / ``volatile-lfu`` 逐出策略的节点在达到 "
+"``maxmemory`` 后可以回收 L2 缓存键。如果没有 TTL，这些策略将永远不会逐出 KV 缓存键，这可能会导致远程缓存阻塞。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:119
+msgid "Cluster-mode"
+msgstr "集群模式"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:122
+msgid "Cluster-mode Valkey Configuration (Endpoint)"
+msgstr "集群模式 Valkey 配置（端点）"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:124
+msgid "For example, the configuration endpoint in ElastiCache is as follows:"
+msgstr "例如，ElastiCache 中的配置端点如下："
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:126
+msgid "<cache-name>.<identifier>.clustercfg.<region>.cache.amazonaws.com"
+msgstr "<cache-name>.<identifier>.clustercfg.<region>.cache.amazonaws.com"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:128
+msgid "You need to add this DNS name in the <your host>."
+msgstr "您需要在 <your host> 中添加此 DNS 名称。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:143
+msgid "Cluster-mode Valkey Configuration (Nodes)"
+msgstr "集群模式 Valkey 配置（节点）"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:145
+msgid ""
+"Nodes are deployed directly and configured in cluster mode without "
+"connecting them via DNS names (CNAME)."
+msgstr "节点直接部署并配置为集群模式，而无需通过 DNS 名称 (CNAME) 连接它们。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:147
+msgid "In this scenario, you simply input multiple IP hosts and ports."
+msgstr "在这种情况下，您只需输入多个 IP 主机和端口。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:149
+msgid "Example: 172.0.0.1:7001, 172.0.0.2:7002 ... 172.0.0.6:7006"
+msgstr "示例：172.0.0.1:7001, 172.0.0.2:7002 ... 172.0.0.6:7006"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:162
+msgid ""
+"Cluster-mode Valkey Configuration with numbered databases (Valkey 9.0+ "
+"and Valkey-GLIDE 2.1+)"
+msgstr "带编号数据库的集群模式 Valkey 配置（Valkey 9.0+ 和 Valkey-GLIDE 2.1+）"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:164
+msgid ""
+"Valkey connector supports numbered databases in both the Endpoint using "
+"DNS and the Nodes method using IP and port pairs."
+msgstr "Valkey 连接器支持在使用 DNS 的端点和使用 IP 和端口对的节点方法中使用编号数据库。"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:178
+msgid "TLS / ElastiCache Serverless"
+msgstr "TLS / ElastiCache Serverless"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:180
+msgid "ElastiCache Serverless requires TLS. Set ``tls_enable: true``:"
+msgstr "ElastiCache Serverless 需要 TLS。设置 ``tls_enable: true``："
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:193
+msgid "Performance Tuning"
+msgstr "性能调优"
+
+#: ../../source/kv_cache/storage_backends/valkey.rst:195
+msgid ""
+"For large models (e.g., 70B with TP=8), increase the worker count for "
+"higher throughput:"
+msgstr "对于大型模型（例如，70B，TP=8），增加工作线程数量以提高吞吐量："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/weka.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/weka.po
new file mode 100644
index 0000000..01ae242
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache/storage_backends/weka.po
@@ -0,0 +1,146 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:2
+msgid "Weka"
+msgstr "Weka"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/l2_storage/index`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/l2_storage/index`。"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:12
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:14
+msgid ""
+"WekaFS is a high-performance, distributed filesystem and is a supported "
+"option for KV Cache offloading in LMCache. Even though the local "
+"filesystem backend can work with a WekaFS mount, this particular backend "
+"is optimized for Weka's characteristics. It leverages GPUDirect Storage "
+"for I/O and it allows data-sharing between multiple LMCache instances."
+msgstr ""
+"WekaFS 是一个高性能的分布式文件系统，是 LMCache 中 KV Cache 卸载的支持选项。尽管本地文件系统后端可以与 WekaFS "
+"挂载一起工作，但该后端针对 Weka 的特性进行了优化。它利用 GPUDirect Storage 进行 I/O，并允许多个 LMCache "
+"实例之间的数据共享。"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:20
+msgid "Ways to configure LMCache WEKA Offloading"
+msgstr "配置 LMCache WEKA 卸载的方法"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:22
+msgid "**1. Environment Variables:**"
+msgstr "**1. 环境变量：**"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:38
+msgid "**2. Configuration File**:"
+msgstr "**2. 配置文件**:"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:40
+msgid "Passed in through ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml``"
+msgstr "通过 ``LMCACHE_CONFIG_FILE=your-lmcache-config.yaml`` 传入"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:42
+msgid "Example ``config.yaml``:"
+msgstr "示例 ``config.yaml``:"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:59
+msgid "GDS Buffer Size Explanation"
+msgstr "GDS 缓冲区大小说明"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:61
+msgid ""
+"The backend currently pre-registers buffer space to speed up GDS "
+"operations. This buffer space is registered in VRAM so options like "
+"``--gpu-memory-utilization`` from ``vllm`` should be considered when "
+"setting it. For example, a good rule of thumb for H100 which generally "
+"has 80GiBs of VRAM would be to start with 8GiB and set ``--gpu-memory-"
+"utilization 0.85`` and depending on your workflow fine-tune it from "
+"there."
+msgstr ""
+"后端目前预先注册缓冲区空间以加速 GDS 操作。此缓冲区空间在显存中注册，因此在设置时应考虑 ``--gpu-memory-"
+"utilization`` 选项，例如来自 ``vllm`` 的选项。例如，对于通常具有 80GiB 显存的 H100，一个好的经验法则是从 "
+"8GiB 开始，并设置 ``--gpu-memory-utilization 0.85``，然后根据您的工作流程进行微调。"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:69
+msgid "Setup Example"
+msgstr "设置示例"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:73
+msgid "**Prerequisites:**"
+msgstr "**前提条件：**"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:75
+msgid ""
+"A Machine with at least one GPU. You can adjust the max model length of "
+"your vllm instance depending on your GPU memory."
+msgstr "一台至少配备一个 GPU 的机器。您可以根据您的显存调整 vllm 实例的最大模型长度。"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:77
+msgid "Weka already installed and mounted."
+msgstr "Weka 已经安装并挂载。"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:79
+msgid ""
+"vllm and lmcache installed (:doc:`Installation Guide "
+"<../../getting_started/installation>`)"
+msgstr "vllm 和 lmcache 已安装 (:doc:`安装指南 <../../getting_started/installation>`)"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:81
+msgid "Hugging Face access to ``meta-llama/Llama-3.1-8B-Instruct``"
+msgstr "Hugging Face 访问 ``meta-llama/Llama-3.1-8B-Instruct``"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:87
+msgid "**Step 1. Create cache directory under your Weka mount:**"
+msgstr "**步骤 1. 在您的 Weka 挂载下创建缓存目录：**"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:89
+msgid "To find all your WekaFS mounts run:"
+msgstr "要查找所有 WekaFS 挂载，请运行："
+
+#: ../../source/kv_cache/storage_backends/weka.rst:95
+msgid "For the sake of this example let's say that the above returns:"
+msgstr "为了这个例子，我们假设上面的返回结果是："
+
+#: ../../source/kv_cache/storage_backends/weka.rst:101
+msgid "Then create a directory under it (the name here is arbitrary):"
+msgstr "然后在其下创建一个目录（这里的名称是任意的）："
+
+#: ../../source/kv_cache/storage_backends/weka.rst:107
+msgid "**Step 2. Start a vLLM server with Weka offloading enabled:**"
+msgstr "**步骤 2. 启动一个启用 Weka 卸载的 vLLM 服务器：**"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:109
+msgid "Create a an lmcache configuration file called: ``weka-offload.yaml``"
+msgstr "创建一个名为 ``weka-offload.yaml`` 的 lmcache 配置文件"
+
+#: ../../source/kv_cache/storage_backends/weka.rst:120
+msgid ""
+"If you don't want to use a config file, uncomment the first three "
+"environment variables and then comment out the ``LMCACHE_CONFIG_FILE`` "
+"below:"
+msgstr "如果您不想使用配置文件，请取消注释前面三个环境变量，然后注释掉下面的 ``LMCACHE_CONFIG_FILE``："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/check_finish.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/check_finish.po
new file mode 100644
index 0000000..8990633
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/check_finish.po
@@ -0,0 +1,36 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/check_finish.rst:4
+msgid "Check finish of a control event"
+msgstr "检查控制事件的完成情况"
+
+#: ../../source/kv_cache_management/check_finish.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/check_finish.rst:11
+msgid "Coming soon..."
+msgstr "敬请期待..."
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/clear.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/clear.po
new file mode 100644
index 0000000..ff927e0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/clear.po
@@ -0,0 +1,88 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/clear.rst:4
+msgid "Clear the KV cache"
+msgstr "清除 KV Cache"
+
+#: ../../source/kv_cache_management/clear.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/clear.rst:11
+msgid "The ``clear`` interface is defined as the following:"
+msgstr "``clear`` 接口定义如下："
+
+#: ../../source/kv_cache_management/clear.rst:17
+msgid ""
+"The function removes the KV cache stored at ``location`` for the "
+"specified ``instance_id``. It returns an ``event_id`` and the number of "
+"tokens scheduled for clearing."
+msgstr ""
+"该函数会移除指定 ``instance_id`` 在 ``location`` 存储的 KV Cache。它返回一个 ``event_id`` "
+"和计划清除的令牌数量。"
+
+#: ../../source/kv_cache_management/clear.rst:22
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/clear.rst:24
+msgid ""
+"First, create a yaml file ``example.yaml`` to configure the lmcache "
+"instance:"
+msgstr "首先，创建一个 yaml 文件 ``example.yaml`` 来配置 lmcache 实例："
+
+#: ../../source/kv_cache_management/clear.rst:42
+msgid "Start the vllm/lmcache instance at port 8000:"
+msgstr "在端口 8000 启动 vllm/lmcache 实例："
+
+#: ../../source/kv_cache_management/clear.rst:49
+msgid "Start the lmcache controller at port 9000 and the monitor at port 9001:"
+msgstr "在9000端口启动lmcache控制器，在9001端口启动监视器："
+
+#: ../../source/kv_cache_management/clear.rst:55
+msgid "Send a request to vllm:"
+msgstr "发送请求到 vllm："
+
+#: ../../source/kv_cache_management/clear.rst:67
+msgid "Clear the KV cache in the system:"
+msgstr "清除系统中的 KV Cache："
+
+#: ../../source/kv_cache_management/clear.rst:79
+msgid "The controller responds with a message similar to:"
+msgstr "控制器会回复类似于以下内容的消息："
+
+#: ../../source/kv_cache_management/clear.rst:85
+msgid ""
+"This indicates that the KV cache for 12 tokens has been scheduled for "
+"clearing. We can verify the cache has been cleared by performing a "
+"lookup:"
+msgstr "这表明 12 个令牌的 KV Cache 已被安排清除。我们可以通过执行查找来验证缓存是否已被清除："
+
+#: ../../source/kv_cache_management/clear.rst:96
+msgid ""
+"The lookup should return an empty result, confirming that the KV cache "
+"has been cleared for the given tokens."
+msgstr "查找应该返回一个空结果，确认给定的令牌的 KV Cache 已被清除。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/compress.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/compress.po
new file mode 100644
index 0000000..902486f
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/compress.po
@@ -0,0 +1,103 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/compress.rst:4
+msgid "Compress and Decompress the KV cache"
+msgstr "压缩和解压缩 KV Cache"
+
+#: ../../source/kv_cache_management/compress.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP mode </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/compress.rst:11
+msgid "The ``compress`` interface is defined as the following:"
+msgstr "``compress`` 接口定义如下："
+
+#: ../../source/kv_cache_management/compress.rst:18
+msgid ""
+"These 2 functions compresses/decompresses the KV cache chunks specified "
+"by ``tokens`` using the given ``method`` in the storage ``location``. The"
+" controller returns an ``event_id`` and the number of tokens scheduled "
+"for compression or decompression."
+msgstr ""
+"这两个函数使用存储位置中的给定方法对由 ``tokens`` 指定的 KV Cache 块进行压缩/解压缩。控制器返回一个 "
+"``event_id`` 和计划进行压缩或解压缩的令牌数量。"
+
+#: ../../source/kv_cache_management/compress.rst:22
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/compress.rst:24
+msgid ""
+"First, we need a yaml file ``example.yaml`` to properly configure the "
+"lmcache instance:"
+msgstr "首先，我们需要一个 yaml 文件 ``example.yaml`` 来正确配置 lmcache 实例："
+
+#: ../../source/kv_cache_management/compress.rst:42
+msgid "Second, we need to start the vllm/lmcache instance at port 8000:"
+msgstr "第二，我们需要在 8000 端口启动 vllm/lmcache 实例："
+
+#: ../../source/kv_cache_management/compress.rst:48
+msgid ""
+"Third, we need to start the lmcache controller at port 9000 and the "
+"monitor at port 9001:"
+msgstr "第三，我们需要在 9000 端口启动 lmcache 控制器，在 9001 端口启动监视器："
+
+#: ../../source/kv_cache_management/compress.rst:54
+msgid "Then we can send a request to vllm to see if it works properly:"
+msgstr "然后我们可以向 vllm 发送请求，以查看它是否正常工作："
+
+#: ../../source/kv_cache_management/compress.rst:66
+msgid "Now we send a request to tokenize the prompt:"
+msgstr "现在我们发送请求以对提示进行标记化："
+
+#: ../../source/kv_cache_management/compress.rst:77
+msgid "We should be able to see token ids in response:"
+msgstr "我们应该能够在响应中看到令牌 ID："
+
+#: ../../source/kv_cache_management/compress.rst:83
+msgid "After all, we issue a ``compress`` request:"
+msgstr "毕竟，我们发出了一个 ``compress`` 请求："
+
+#: ../../source/kv_cache_management/compress.rst:96
+#: ../../source/kv_cache_management/compress.rst:117
+msgid "The controller responds with a message similar to:"
+msgstr "控制器会回复类似于以下内容的消息："
+
+#: ../../source/kv_cache_management/compress.rst:102
+msgid ""
+"This indicates that 12 tokens are being compressed. The ``event_id`` can "
+"be used to query the status of the operation."
+msgstr "这表明正在压缩 12 个 token。``event_id`` 可用于查询操作的状态。"
+
+#: ../../source/kv_cache_management/compress.rst:104
+msgid "Once the kv cache is compressed, we can use cachegen to decompress"
+msgstr "一旦 KV Cache 被压缩，我们可以使用 cachegen 进行解压。"
+
+#: ../../source/kv_cache_management/compress.rst:123
+msgid ""
+"This indicates that 12 tokens are being decompressed. The ``event_id`` "
+"can be used to query the status of the operation."
+msgstr "这表示正在解压缩 12 个令牌。``event_id`` 可用于查询操作的状态。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/health.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/health.po
new file mode 100644
index 0000000..c8a0752
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/health.po
@@ -0,0 +1,69 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/health.rst:4
+msgid "Check controller health"
+msgstr "检查控制器健康状态"
+
+#: ../../source/kv_cache_management/health.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/health.rst:11
+msgid "The ``health`` interface is defined as the following:"
+msgstr "``health`` 接口定义如下："
+
+#: ../../source/kv_cache_management/health.rst:17
+msgid ""
+"The function returns an ``event_id`` and a dictionary mapping "
+"``worker_id`` to ``error_code``. A value of ``0`` indicates a healthy "
+"worker, while a non-zero value signals an error."
+msgstr ""
+"该函数返回一个 ``event_id`` 和一个将 ``worker_id`` 映射到 ``error_code`` 的字典。值为 ``0`` "
+"表示工作正常，而非零值则表示出现错误。"
+
+#: ../../source/kv_cache_management/health.rst:22
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/health.rst:24
+msgid ""
+"First, start the lmcache controller at port 9000 and the monitor at port "
+"9001:"
+msgstr "首先，在 9000 端口启动 lmcache 控制器，在 9001 端口启动监视器："
+
+#: ../../source/kv_cache_management/health.rst:30
+msgid "Then send a health check request:"
+msgstr "然后发送健康检查请求："
+
+#: ../../source/kv_cache_management/health.rst:38
+msgid "The controller responds with a message similar to the following:"
+msgstr "控制器会返回类似于以下内容的消息："
+
+#: ../../source/kv_cache_management/health.rst:44
+msgid ""
+"Here ``error_codes`` lists each worker's ``error_code``. ``0`` represents"
+" a healthy worker, while non-zero values indicate an error."
+msgstr "这里 ``error_codes`` 列出了每个工作者的 ``error_code``。 ``0`` 表示工作者健康，而非零值则表示出现错误。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/index.po
new file mode 100644
index 0000000..89d02f8
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/index.po
@@ -0,0 +1,229 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/index.rst:2
+msgid "LMCache Controller"
+msgstr "LMCache 控制器"
+
+#: ../../source/kv_cache_management/index.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/index.rst:10
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/kv_cache_management/index.rst:11
+msgid ""
+"The overall architecture of the LMCache Controller is shown in the "
+"figure, mainly consisting of two parts: the Controller Manager and "
+"LMCache Worker."
+msgstr "LMCache 控制器的整体架构如图所示，主要由两个部分组成：控制器管理器和 LMCache 工作线程。"
+
+#: ../../source/kv_cache_management/index.rst:14
+msgid ""
+"The Controller Manager mainly consists of KV Controller, Reg Controller, "
+"and Cluster Executor."
+msgstr "控制器管理器主要由 KV 控制器、注册控制器和集群执行器组成。"
+
+#: ../../source/kv_cache_management/index.rst:16
+msgid ""
+"KV Controller: The KV Controller handles the chunk information reported "
+"by LMCache Workers, and lookup requests query chunk information from the "
+"KV Controller."
+msgstr ""
+"KV Controller：KV Controller 处理由 LMCache Workers 报告的块信息，并且查找请求从 KV "
+"Controller 查询块信息。"
+
+#: ../../source/kv_cache_management/index.rst:17
+msgid ""
+"Reg Controller: The Reg Controller is responsible for handling "
+"register/deregister/heartbeat requests from LMCache Workers."
+msgstr "Reg Controller: Reg Controller 负责处理来自 LMCache Workers 的注册/注销/心跳请求。"
+
+#: ../../source/kv_cache_management/index.rst:18
+msgid ""
+"Cluster Executor: When the Controller Manager receives user requests, "
+"such as Clear or Move, it sends the corresponding commands to LMCache "
+"Workers through the Cluster Executor."
+msgstr "集群执行器：当控制器管理器接收到用户请求，例如清除或移动时，它通过集群执行器将相应的命令发送给 LMCache 工作线程。"
+
+#: ../../source/kv_cache_management/index.rst:20
+msgid ""
+"The LMCache Worker is a thread within a rank process, which is "
+"responsible for the following tasks:"
+msgstr "LMCache Worker 是一个在排名进程中的线程，负责以下任务："
+
+#: ../../source/kv_cache_management/index.rst:22
+msgid "sends register, deregister, heartbeat to the Reg Controller."
+msgstr "向注册控制器发送注册、注销和心跳。"
+
+#: ../../source/kv_cache_management/index.rst:23
+msgid ""
+"send chunk information to the KV Controller, which include admit and "
+"evict message."
+msgstr "将块信息发送到 KV 控制器，包括接纳和逐出消息。"
+
+#: ../../source/kv_cache_management/index.rst:24
+msgid ""
+"listens on a port to receive commands from the Cluster Executor and "
+"performs corresponding processing."
+msgstr "在一个端口上监听以接收来自集群执行器的命令，并执行相应的处理。"
+
+#: ../../source/kv_cache_management/index.rst:26
+msgid "LMCache Controller Architecture Diagram"
+msgstr "LMCache 控制器架构图"
+
+#: ../../source/kv_cache_management/index.rst:30
+msgid "P2P Related"
+msgstr "P2P 相关"
+
+#: ../../source/kv_cache_management/index.rst:32
+msgid ""
+"If ``enable_p2p`` is enabled, the LMCache Controller must also be "
+"enabled. The LMCache Controller serves as the central node and stores "
+"information for each chunk. The ``P2PBackend`` queries chunk information "
+"from the LMCache Controller and performs data transmission through NIXL."
+msgstr ""
+"如果启用 ``enable_p2p``，则必须启用 LMCache 控制器。LMCache "
+"控制器作为中央节点，存储每个块的信息。``P2PBackend`` 从 LMCache 控制器查询块信息，并通过 NIXL 执行数据传输。"
+
+#: ../../source/kv_cache_management/index.rst:38
+msgid "Key Features"
+msgstr "关键特性"
+
+#: ../../source/kv_cache_management/index.rst:40
+msgid "Exposes a set of APIs for users and orchestrators to manage the KV cache."
+msgstr "暴露一组 API 供用户和调度器管理 KV Cache。"
+
+#: ../../source/kv_cache_management/index.rst:42
+msgid "Currently, the controller provides the following APIs:"
+msgstr "目前，控制器提供以下 API："
+
+#: ../../source/kv_cache_management/index.rst:44
+msgid ":ref:`Clear <clear>`: Clear the KV caches."
+msgstr ":ref:`清除 <clear>`: 清除 KV 缓存。"
+
+#: ../../source/kv_cache_management/index.rst:45
+msgid ":ref:`Compress <compress>`: Compress the KV cache."
+msgstr ":ref:`压缩 <compress>`: 压缩 KV Cache。"
+
+#: ../../source/kv_cache_management/index.rst:46
+msgid ":ref:`Health <health>`: Check the health status of cache workers."
+msgstr ":ref:`Health <health>`: 检查缓存工作线程的健康状态。"
+
+#: ../../source/kv_cache_management/index.rst:47
+msgid ":ref:`Lookup <lookup>`: Lookup the KV cache for a given list of tokens."
+msgstr ":ref:`查找 <lookup>`: 在 KV Cache 中查找给定的令牌列表。"
+
+#: ../../source/kv_cache_management/index.rst:48
+msgid ":ref:`Move <move>`: Move the KV cache to a different location."
+msgstr ":ref:`移动 <move>`: 将 KV Cache 移动到不同的位置。"
+
+#: ../../source/kv_cache_management/index.rst:49
+msgid ":ref:`Pin <pin>`: Persist the KV cache to prevent it from being evicted."
+msgstr ":ref:`Pin <pin>`: 持久化 KV Cache 以防止其被逐出。"
+
+#: ../../source/kv_cache_management/index.rst:50
+msgid ""
+":ref:`CheckFinish <check_finish>`: Check whether a (non-blocking) control"
+" event has finished or not."
+msgstr ":ref:`CheckFinish <check_finish>`: 检查一个（非阻塞）控制事件是否已经完成。"
+
+#: ../../source/kv_cache_management/index.rst:51
+msgid ":ref:`QueryWorkerInfo <query_worker_info>`: Query the worker info."
+msgstr ":ref:`QueryWorkerInfo <query_worker_info>`: 查询工作者信息。"
+
+#: ../../source/kv_cache_management/index.rst:53
+msgid "Interacts with the LMCache worker."
+msgstr "与 LMCache 工作线程交互。"
+
+#: ../../source/kv_cache_management/index.rst:55
+msgid "Currently, the LMCache worker supports the following functions:"
+msgstr "目前，LMCache 工作线程支持以下功能："
+
+#: ../../source/kv_cache_management/index.rst:57
+msgid "register with the controller"
+msgstr "向控制器注册"
+
+#: ../../source/kv_cache_management/index.rst:58
+msgid "deregister from the controller"
+msgstr "从控制器注销"
+
+#: ../../source/kv_cache_management/index.rst:59
+msgid "heartbeat"
+msgstr "心跳"
+
+#: ../../source/kv_cache_management/index.rst:60
+msgid "admit or evict chunk information(LocalCPUBackend or LocalDiskBackend)"
+msgstr "接受或逐出块信息（LocalCPUBackend 或 LocalDiskBackend）"
+
+#: ../../source/kv_cache_management/index.rst:64
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/kv_cache_management/index.rst:66
+msgid "**Start the Controller**"
+msgstr "**启动控制器**"
+
+#: ../../source/kv_cache_management/index.rst:72
+msgid "Expected output:"
+msgstr "预期输出："
+
+#: ../../source/kv_cache_management/index.rst:87
+msgid "**Controller Configuration**"
+msgstr "**控制器配置**"
+
+#: ../../source/kv_cache_management/index.rst:89
+msgid "--host: default is 0.0.0.0"
+msgstr "--host: 默认值为 0.0.0.0"
+
+#: ../../source/kv_cache_management/index.rst:90
+msgid ""
+"--port: default is 9000, the externally exposed port through which "
+"interfaces like lookup can be accessed via this port."
+msgstr "--port: 默认值为 9000，通过此端口可以访问诸如查找等接口。"
+
+#: ../../source/kv_cache_management/index.rst:91
+msgid ""
+"--monitor-port: default is 9001,  the port through which LMCache Worker "
+"communicates with Controller Manager (deprecated, indicates the pull port"
+" in --monitor-ports, reply port is None)."
+msgstr ""
+"--monitor-port: 默认值为 9001，LMCache Worker 与 Controller Manager "
+"通信的端口（已弃用，表示 --monitor-ports 中的拉取端口，回复端口为 None）。"
+
+#: ../../source/kv_cache_management/index.rst:92
+#, python-brace-format
+msgid ""
+"--monitor-ports: default is None, if configured, requires a JSON format "
+"string input such as ``{\"pull\": 8300, \"reply\": 8400}``."
+msgstr ""
+"--monitor-ports: 默认值为 None，如果配置，则需要输入 JSON 格式的字符串，例如 ``{\\\"pull\\\": "
+"8300, \\\"reply\\\": 8400}``。"
+
+#: ../../source/kv_cache_management/index.rst:94
+msgid "**YAML Configuration**"
+msgstr "**YAML 配置**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/lookup.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/lookup.po
new file mode 100644
index 0000000..338990f
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/lookup.po
@@ -0,0 +1,97 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/lookup.rst:4
+msgid "Lookup the KV cache"
+msgstr "查找 KV Cache"
+
+#: ../../source/kv_cache_management/lookup.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/lookup.rst:11
+msgid "The ``lookup`` interface is defined as the following:"
+msgstr "``lookup`` 接口定义如下："
+
+#: ../../source/kv_cache_management/lookup.rst:17
+msgid ""
+"The function takes a list of tokens as input and returns event_id and a "
+"dictionary containing the layout information for each token. The layout "
+"information is represented as a mapping between ``instance_id`` and a "
+"tuple of ``(location, matched_prefix_length)``."
+msgstr ""
+"该函数接受一个令牌列表作为输入，并返回 event_id 以及一个包含每个令牌布局信息的字典。布局信息表示为 ``instance_id`` 与 "
+"``(location, matched_prefix_length)`` 元组之间的映射。"
+
+#: ../../source/kv_cache_management/lookup.rst:21
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/lookup.rst:23
+msgid ""
+"First, we need a yaml file ``example.yaml`` to properly configure the "
+"lmcache instance:"
+msgstr "首先，我们需要一个 yaml 文件 ``example.yaml`` 来正确配置 lmcache 实例："
+
+#: ../../source/kv_cache_management/lookup.rst:41
+msgid "Second, we need to start the vllm/lmcache instance at port 8000:"
+msgstr "第二，我们需要在 8000 端口启动 vllm/lmcache 实例："
+
+#: ../../source/kv_cache_management/lookup.rst:47
+msgid ""
+"Third, we need to start the lmcache controller at port 9000 and the "
+"monitor at port 9001:"
+msgstr "第三，我们需要在 9000 端口启动 lmcache 控制器，在 9001 端口启动监视器："
+
+#: ../../source/kv_cache_management/lookup.rst:53
+msgid "Then we can send a request to vllm to see if it works properly:"
+msgstr "然后我们可以向 vllm 发送请求，以查看它是否正常工作："
+
+#: ../../source/kv_cache_management/lookup.rst:65
+msgid "Now we send a request to tokenize the prompt:"
+msgstr "现在我们发送请求以对提示进行标记化："
+
+#: ../../source/kv_cache_management/lookup.rst:76
+msgid "We should be able to see token ids in response:"
+msgstr "我们应该能够在响应中看到令牌 ID："
+
+#: ../../source/kv_cache_management/lookup.rst:82
+msgid "Finally, we can send a ``lookup`` request to the lmcache controller:"
+msgstr "最后，我们可以向 lmcache 控制器发送一个 ``lookup`` 请求："
+
+#: ../../source/kv_cache_management/lookup.rst:92
+msgid "We should be able to see the response like this:"
+msgstr "我们应该能够看到这样的响应："
+
+#: ../../source/kv_cache_management/lookup.rst:98
+msgid ""
+"The field ``lmcache_default_instance`` shows the instance ID, followed by"
+" a tuple of ``(location, matched_prefix_length)`` indicating the cache "
+"location within that instance and matched prefix length. ``event_id`` is "
+"an identifier of the controller operation and can typically be ignored."
+msgstr ""
+"字段 ``lmcache_default_instance`` 显示实例 ID，后面是一个元组 ``(location, "
+"matched_prefix_length)``，指示该实例内的缓存位置和匹配前缀长度。 ``event_id`` "
+"是控制器操作的标识符，通常可以忽略。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/move.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/move.po
new file mode 100644
index 0000000..1ef9b77
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/move.po
@@ -0,0 +1,95 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/move.rst:4
+msgid "Move the KV cache"
+msgstr "移动 KV Cache"
+
+#: ../../source/kv_cache_management/move.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/move.rst:11
+msgid "The ``move`` interface is defined as the following:"
+msgstr "``move`` 接口定义如下："
+
+#: ../../source/kv_cache_management/move.rst:18
+msgid ""
+"The function moves the KV cache chunks identified by ``tokens`` from "
+"``old_position`` to ``new_position``. Each position is a tuple of "
+"``(instance_id, location)``. Setting ``copy`` to ``True`` copies the KV "
+"cache instead of moving it."
+msgstr ""
+"该函数将由 ``tokens`` 标识的 KV Cache 块从 ``old_position`` 移动到 "
+"``new_position``。每个位置是一个 ``(instance_id, location)`` 的元组。将 ``copy`` 设置为 "
+"``True`` 会复制 KV Cache，而不是移动它。"
+
+#: ../../source/kv_cache_management/move.rst:23
+msgid ""
+"Note that NIXL is required to  be installed for P2P transfer. We'll "
+"support other transports later such as Python socket and Mooncake."
+msgstr "请注意，必须安装 NIXL 才能进行 P2P 传输。我们稍后将支持其他传输方式，例如 Python 套接字和 Mooncake。"
+
+#: ../../source/kv_cache_management/move.rst:27
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/move.rst:29
+msgid ""
+"First, prepare two yaml files ``instance1.yaml`` and ``instance2.yaml`` "
+"to configure two lmcache instances:"
+msgstr "首先，准备两个 yaml 文件 ``instance1.yaml`` 和 ``instance2.yaml`` 来配置两个 lmcache 实例："
+
+#: ../../source/kv_cache_management/move.rst:75
+msgid "Start two vllm engines:"
+msgstr "启动两个 vllm 引擎："
+
+#: ../../source/kv_cache_management/move.rst:87
+msgid "Start the lmcache controller at port 9000 and the monitor at port 9001:"
+msgstr "在9000端口启动lmcache控制器，在9001端口启动监视器："
+
+#: ../../source/kv_cache_management/move.rst:93
+msgid "Send a request to vllm engine 1:"
+msgstr "向 vllm 引擎 1 发送请求："
+
+#: ../../source/kv_cache_management/move.rst:105
+msgid "Tokenize the prompt to obtain token ids:"
+msgstr "将提示进行分词以获取令牌 ID："
+
+#: ../../source/kv_cache_management/move.rst:116
+msgid ""
+"Move the KV cache from engine 1's CPU to engine 2's CPU using the token "
+"ids:"
+msgstr "将 KV Cache 从引擎 1 的 CPU 移动到引擎 2 的 CPU，使用的 token ids 为："
+
+#: ../../source/kv_cache_management/move.rst:128
+msgid "The controller responds with a message similar to:"
+msgstr "控制器会回复类似于以下内容的消息："
+
+#: ../../source/kv_cache_management/move.rst:134
+msgid ""
+"``num_tokens`` indicates how many tokens' KV cache are being moved. The "
+"returned ``event_id`` can be used to query the status of the operation."
+msgstr "``num_tokens`` 表示正在移动多少个 token 的 KV Cache。返回的 ``event_id`` 可用于查询操作的状态。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/pin.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/pin.po
new file mode 100644
index 0000000..3840b5e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/pin.po
@@ -0,0 +1,85 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/pin.rst:4
+msgid "Pin the KV cache"
+msgstr "固定 KV Cache"
+
+#: ../../source/kv_cache_management/pin.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/pin.rst:11
+msgid "The ``pin`` interface is defined as the following:"
+msgstr "``pin`` 接口定义如下："
+
+#: ../../source/kv_cache_management/pin.rst:17
+msgid ""
+"The function pins (persists) the KV cache chunks specified by ``tokens`` "
+"in the given ``location`` of the ``instance_id``. The controller returns "
+"an ``event_id`` and the number of tokens scheduled for pinning."
+msgstr ""
+"该函数将指定的 ``tokens`` 在给定的 ``instance_id`` 的 ``location`` 中固定（持久化）KV Cache "
+"块。控制器返回一个 ``event_id`` 和计划固定的令牌数量。"
+
+#: ../../source/kv_cache_management/pin.rst:22
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/pin.rst:24
+msgid ""
+"First, create a yaml file ``example.yaml`` to configure the lmcache "
+"instance:"
+msgstr "首先，创建一个 yaml 文件 ``example.yaml`` 来配置 lmcache 实例："
+
+#: ../../source/kv_cache_management/pin.rst:43
+msgid "Start the vllm/lmcache instance at port 8000:"
+msgstr "在端口 8000 启动 vllm/lmcache 实例："
+
+#: ../../source/kv_cache_management/pin.rst:50
+msgid "Start the lmcache controller at port 9000 and the monitor at port 9001:"
+msgstr "在9000端口启动lmcache控制器，在9001端口启动监视器："
+
+#: ../../source/kv_cache_management/pin.rst:56
+msgid "Send a request to vllm:"
+msgstr "发送请求到 vllm："
+
+#: ../../source/kv_cache_management/pin.rst:68
+msgid "Tokenize the prompt to obtain token ids:"
+msgstr "将提示进行分词以获取令牌 ID："
+
+#: ../../source/kv_cache_management/pin.rst:79
+msgid "Pin the KV cache in the system:"
+msgstr "在系统中固定 KV Cache："
+
+#: ../../source/kv_cache_management/pin.rst:91
+msgid "The controller responds with a message similar to:"
+msgstr "控制器会回复类似于以下内容的消息："
+
+#: ../../source/kv_cache_management/pin.rst:97
+msgid ""
+"``num_tokens`` indicates how many tokens' KV cache are pinned. The "
+"returned ``event_id`` can be used to query the status of the operation."
+msgstr "``num_tokens`` 指示有多少个 token 的 KV Cache 被固定。返回的 ``event_id`` 可用于查询操作的状态。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/query_worker_info.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/query_worker_info.po
new file mode 100644
index 0000000..7029460
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_management/query_worker_info.po
@@ -0,0 +1,77 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_management/query_worker_info.rst:4
+msgid "Query Worker Info"
+msgstr "查询工作者信息"
+
+#: ../../source/kv_cache_management/query_worker_info.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_management/query_worker_info.rst:11
+msgid "The ``query_worker_info`` interface is defined as the following:"
+msgstr "``query_worker_info`` 接口定义如下："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:17
+msgid ""
+"The function get the info of the workers which specified by "
+"``instance_id`` and ``worker_ids``. The controller returns an "
+"``event_id`` and the worker infos."
+msgstr ""
+"该函数获取由 ``instance_id`` 和 ``worker_ids`` 指定的工作者的信息。控制器返回一个 ``event_id`` "
+"和工作者信息。"
+
+#: ../../source/kv_cache_management/query_worker_info.rst:21
+msgid "Example usage:"
+msgstr "示例用法："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:23
+msgid ""
+"First, create a yaml file ``example.yaml`` to configure the lmcache "
+"instance:"
+msgstr "首先，创建一个 yaml 文件 ``example.yaml`` 来配置 lmcache 实例："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:42
+msgid "Start the vllm/lmcache instance at port 8000:"
+msgstr "在端口 8000 启动 vllm/lmcache 实例："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:49
+msgid "Start the lmcache controller at port 9000 and the monitor at port 9001:"
+msgstr "在9000端口启动lmcache控制器，在9001端口启动监视器："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:55
+msgid "Send a request to controller:"
+msgstr "发送请求到控制器："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:66
+msgid "The controller responds with a message similar to:"
+msgstr "控制器会回复类似于以下内容的消息："
+
+#: ../../source/kv_cache_management/query_worker_info.rst:72
+msgid ""
+"``worker_infos`` contains the queried worker information. returned "
+"``event_id`` can be used to query the status of the operation."
+msgstr "``worker_infos`` 包含查询到的工作者信息。返回的 ``event_id`` 可用于查询操作的状态。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/blending.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/blending.po
new file mode 100644
index 0000000..0bd793f
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/blending.po
@@ -0,0 +1,89 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/blending.rst:2
+msgid "Blending"
+msgstr "混合"
+
+#: ../../source/kv_cache_optimizations/blending.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_optimizations/blending.rst:9
+msgid ""
+"CacheBlend enables KV cache reuse for non-prefix positions by recomputing"
+" a subset of tokens at non-prefix positions. For example, CacheBlend can "
+"combine multiple (pre-)computed KV caches, when their corresponding texts"
+" are concatenated in the LLM input"
+msgstr ""
+"CacheBlend 通过在非前缀位置重计算一部分令牌来实现 KV Cache 的重用。例如，当相应的文本在 LLM "
+"输入中连接时，CacheBlend 可以组合多个（预）计算的 KV Cache。"
+
+#: ../../source/kv_cache_optimizations/blending.rst:13
+msgid "Configuring CacheBlend in RAG scenarios"
+msgstr "在 RAG 场景中配置 CacheBlend"
+
+#: ../../source/kv_cache_optimizations/blending.rst:15
+msgid ""
+"Here, we will explain the code in our end-to-end `example "
+"<https://github.com/LMCache/LMCache/tree/dev/examples/blend_kv_v1/blend.py>`_>."
+msgstr ""
+"在这里，我们将解释我们端到端的 `example "
+"<https://github.com/LMCache/LMCache/tree/dev/examples/blend_kv_v1/blend.py>`_"
+" 中的代码。"
+
+#: ../../source/kv_cache_optimizations/blending.rst:17
+msgid "Below are some blending-related configurations (and explanations):"
+msgstr "以下是一些与混合相关的配置（及其解释）："
+
+#: ../../source/kv_cache_optimizations/blending.rst:42
+msgid ""
+"Firstly, we preprocess texts into tokens, as tokenizing a concatenated "
+"string may produce different tokens than concatenating the results of "
+"tokenizing each string individually. For example, assume we have a system"
+" prompt and three text chunks. We need to preprocess them into tokens "
+"before sending to the LLM:"
+msgstr ""
+"首先，我们将文本预处理为标记，因为将连接的字符串进行标记化可能会产生与分别对每个字符串进行标记化后再连接的结果不同的标记。例如，假设我们有一个系统提示和三个文本块。在将它们发送到"
+" LLM 之前，我们需要将它们预处理为标记："
+
+#: ../../source/kv_cache_optimizations/blending.rst:64
+msgid ""
+"Then, we can send the tokenized prompt to vLLM. Meanwhile, LMCache will "
+"store the KV caches of different chunks according to the "
+"``BLEND_SPECIAL_STR``."
+msgstr "然后，我们可以将标记化的提示发送到 vLLM。同时，LMCache 将根据 ``BLEND_SPECIAL_STR`` 存储不同块的 KV 缓存。"
+
+#: ../../source/kv_cache_optimizations/blending.rst:70
+msgid ""
+"Similarly, we build another prompt using the same chunks but with "
+"different orders."
+msgstr "同样，我们使用相同的块但以不同的顺序构建另一个提示。"
+
+#: ../../source/kv_cache_optimizations/blending.rst:87
+msgid ""
+"Even though the second prompt has a different order of chunks, LMCache "
+"can still reuse the KV caches of chunk1, chunk2, and chunk3."
+msgstr "尽管第二个提示的块顺序不同，LMCache 仍然可以重用 chunk1、chunk2 和 chunk3 的 KV 缓存。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/cacheblend.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/cacheblend.po
new file mode 100644
index 0000000..1f6bde4
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/cacheblend.po
@@ -0,0 +1,57 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/cacheblend.rst:2
+msgid "CacheBlend"
+msgstr "CacheBlend"
+
+#: ../../source/kv_cache_optimizations/cacheblend.rst:4
+msgid ""
+"CacheBlend lets LMCache reuse the KV cache of **any** repeated text chunk"
+" -- not only a shared prefix -- by selectively recomputing a small "
+"fraction of tokens at chunk boundaries. This cuts time-to-first-token for"
+" RAG and multi-document workloads where the reusable context is not a "
+"clean prefix."
+msgstr "CacheBlend 允许 LMCache 重用 **任何** 重复文本块的 KV 缓存，而不仅仅是共享前缀——通过在块边界有选择地对少量 token 进行重计算来实现。这可以降低 RAG 和多文档场景下的首 token 延迟（TTFT），适用于可复用上下文并非干净前缀的情况。"
+
+#: ../../source/kv_cache_optimizations/cacheblend.rst:10
+msgid "Enabling CacheBlend (MP mode)"
+msgstr "启用 CacheBlend（MP 模式（多进程））"
+
+#: ../../source/kv_cache_optimizations/cacheblend.rst:12
+msgid "Start the LMCache server with the blend engine:"
+msgstr "使用 blend 引擎启动 LMCache 服务器："
+
+#: ../../source/kv_cache_optimizations/cacheblend.rst:18
+msgid ""
+"The ``blend`` engine composes a ``BlendModule`` into the server and "
+"requires ``--supported-transfer-mode`` to be ``lmcache_driven`` or "
+"``auto`` (the default). See :doc:`/mp/configuration` for the related "
+"server flags."
+msgstr "``blend`` 引擎将 ``BlendModule`` 组合到服务器中，并要求 ``--supported-transfer-mode`` 设置为 ``lmcache_driven`` 或 ``auto``\\ （默认值）。有关相关服务器标志，请参见 :doc:`/mp/configuration`。"
+
+#: ../../source/kv_cache_optimizations/cacheblend.rst:24
+msgid ""
+"The in-process CacheBlend documentation -- configuration knobs such as "
+"``LMCACHE_ENABLE_BLENDING`` and an end-to-end example -- is preserved in "
+"the Legacy section: :doc:`/kv_cache_optimizations/blending`."
+msgstr "进程内 CacheBlend 文档——包括配置项（如 ``LMCACHE_ENABLE_BLENDING``\\ ）及端到端示例——已保留在旧版章节中： :doc:`/kv_cache_optimizations/blending`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/compression/cachegen.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/compression/cachegen.po
new file mode 100644
index 0000000..cc593ab
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/compression/cachegen.po
@@ -0,0 +1,63 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:4
+msgid "CacheGen"
+msgstr "CacheGen"
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/cachegen`."
+msgstr "本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 :doc:`/mp/cachegen`。"
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:11
+msgid ""
+"Cachegen leverages KV cache's distributional properties to encode a KV "
+"cache into more compact bitstream representations with negligible "
+"decoding overhead."
+msgstr "Cachegen 利用 KV Cache 的分布特性，将 KV Cache 编码为更紧凑的比特流表示，解码开销可以忽略不计。"
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:15
+msgid "Configuring CacheGen in LMCache"
+msgstr "在 LMCache 中配置 CacheGen"
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:17
+msgid ""
+"The settings should be very similar to :ref:`naive KV cache sharing "
+"<share_kv_cache>`. Only minor configurations need to be done to enable "
+"CacheGen."
+msgstr ""
+"设置应该与 :ref:`naive KV cache sharing <share_kv_cache>` 非常相似。只需进行少量配置即可启用 "
+"CacheGen。"
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:20
+msgid "To enable CacheGen in offline inference, we need to set:"
+msgstr "要在离线推理中启用 CacheGen，我们需要设置："
+
+#: ../../source/kv_cache_optimizations/compression/cachegen.rst:27
+msgid ""
+"To enable CacheGen in online inference, we need to set the "
+"``remote_serde`` in the configuration yaml:"
+msgstr "要在在线推理中启用 CacheGen，我们需要在配置 yaml 中设置 ``remote_serde``："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/compression/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/compression/index.po
new file mode 100644
index 0000000..66ebd05
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/compression/index.po
@@ -0,0 +1,39 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/compression/index.rst:2
+msgid "Compression"
+msgstr "压缩"
+
+#: ../../source/kv_cache_optimizations/compression/index.rst:4
+msgid ""
+"KV cache compression can greatly reduces the size of the cache, which can"
+" be beneficial for both storage/memory usage and loading speed. "
+"Currently, we support the following compression algorithms:"
+msgstr "KV Cache 压缩可以大大减少缓存的大小，这对存储/内存使用和加载速度都有好处。目前，我们支持以下压缩算法："
+
+#: ../../source/kv_cache_optimizations/compression/index.rst:7
+msgid ""
+":ref:`CacheGen <cachegen>`: `CacheGen: KV Cache Compression and Streaming"
+" for Fast Large Language Model Serving "
+"<https://dl.acm.org/doi/10.1145/3651890.3672274>`_"
+msgstr ":ref:`CacheGen <cachegen>`: `CacheGen: KV Cache 压缩与流式传输以快速服务大型语言模型 <https://dl.acm.org/doi/10.1145/3651890.3672274>`_"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/index.po
new file mode 100644
index 0000000..e2507de
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/index.po
@@ -0,0 +1,31 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/index.rst:2
+msgid "KV Cache Optimizations"
+msgstr "KV Cache 优化"
+
+#: ../../source/kv_cache_optimizations/index.rst:4
+msgid ""
+"Techniques that improve KV cache reuse and efficiency beyond plain prefix"
+" caching."
+msgstr "在普通前缀缓存基础之上，进一步提升 KV Cache 复用率与效率的技术。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/layerwise.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/layerwise.po
new file mode 100644
index 0000000..02b383e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/layerwise.po
@@ -0,0 +1,308 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:2
+msgid "Layerwise KV Transfer"
+msgstr "逐层 KV 传输"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr "本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 :doc:`LMCache MP 模式 </mp/index>` 以获得更好的功能支持和性能。"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:9
+msgid ""
+"The storage and loading of KV Cache on a layer granularity is a key "
+"optimization that allows for forward pass to \"stagger\" through its "
+"computation as each layer's KV Cache is received instead of only waiting "
+"to begin after the entire loading"
+msgstr ""
+"在逐层粒度上存储和加载 KV Cache 是一个关键优化，它允许前向传播在计算过程中“错开”，因为每一层的 KV Cache "
+"在接收后就可以开始，而不必等到整个加载完成后才开始。"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:11
+msgid ""
+"CacheBlend is implemented on top of the layerwise codepath in order to "
+"pipeline recompute and loading to mask the latency of loading KV Cache."
+msgstr "CacheBlend 是在逐层代码路径之上实现的，目的是将重计算和加载进行流水线处理，以掩盖加载 KV Cache 的延迟。"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:13
+msgid "Basic Codepath"
+msgstr "基本代码路径"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:30
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:32
+msgid "**CacheEngine**"
+msgstr "**CacheEngine**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:33
+msgid "The main orchestrator containing two primary generators:"
+msgstr "主要协调器，包含两个主要生成器："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:35
+msgid ""
+"**Retrieval Generator** (N + 2 yields): Handles layer-by-layer KV cache "
+"loading with on-demand memory allocation"
+msgstr "**检索生成器** (N + 2 生成): 处理逐层 KV Cache 加载，按需分配内存"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:36
+msgid ""
+"**Storage Generator** (N + 1 yields): Manages layer-by-layer KV cache "
+"saving with upfront CPU memory allocation"
+msgstr "**存储生成器** (N + 1 yields): 管理逐层 KV Cache 保存，并提前分配 CPU 内存"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:38
+msgid "**LayerwiseGPUConnector**"
+msgstr "**LayerwiseGPUConnector**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:39
+msgid "Manages GPU-CPU memory transfers with dedicated CUDA streams:"
+msgstr "管理使用专用 CUDA 流的 GPU-CPU 内存传输："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:41
+msgid ""
+"**Load GPU Buffer**: Temporary GPU memory for CPU→GPU transfers "
+"(``use_gpu: true``)"
+msgstr "**加载 GPU 缓冲区**\\ ：用于 CPU→GPU 传输的临时显存（\\ ``use_gpu: true``\\ ）"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:42
+msgid ""
+"**Store GPU Buffer**: Temporary GPU memory for GPU→CPU transfers "
+"(``use_gpu: true``)"
+msgstr "**存储 GPU 缓冲区**\\ ：用于 GPU→CPU 传输的临时显存（\\ ``use_gpu: true``\\ ）"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:43
+msgid ""
+"**Nested Generators**: ``batched_to_gpu()`` and ``batched_from_gpu()`` "
+"handle actual memory operations"
+msgstr "**嵌套生成器**: ``batched_to_gpu()`` 和 ``batched_from_gpu()`` 处理实际的内存操作"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:45
+msgid "**StorageManager**"
+msgstr "**存储管理器**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:46
+msgid "Handles persistent storage operations:"
+msgstr "处理持久存储操作："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:48
+msgid ""
+"``layerwise_batched_get()``: Asynchronous retrieval with ``.result()`` "
+"for request-level concurrency"
+msgstr "``layerwise_batched_get()``: 使用 ``.result()`` 进行请求级并发的异步检索"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:49
+msgid "``batched_put()``: Stores memory objects to persistent backends"
+msgstr "``batched_put()``: 将内存对象存储到持久后端"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:52
+msgid "Execution Flow"
+msgstr "执行流程"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:54
+msgid "The layerwise pipeline follows a numbered execution sequence:"
+msgstr "逐层管道遵循编号的执行顺序："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:56
+msgid "**1. start_load_kv()**"
+msgstr "**1. start_load_kv()**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:57
+msgid "Initializes Retrieval Generator via ``lmcache_engine.retrieve_layer()``"
+msgstr "通过 ``lmcache_engine.retrieve_layer()`` 初始化检索生成器"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:58
+msgid "Performs setup (1st ``next()``) and loads layer 0 (2nd ``next()``)"
+msgstr "执行设置（第一次 ``next()``\\ ）并加载第 0 层（第二次 ``next()``\\ ）"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:59
+msgid "Creates ``layerwise_retrievers`` list for ongoing layer processing"
+msgstr "创建 ``layerwise_retrievers`` 列表以进行持续的层处理"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:61
+msgid "**2. wait_for_layer_load()** (repeated for each layer)"
+msgstr "**2. wait_for_layer_load()** (对每一层重复执行)"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:62
+msgid "Advances Retrieval Generator via ``next()`` to process layer i"
+msgstr "通过 ``next()`` 使检索生成器向前推进以处理第 i 层"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:63
+msgid ""
+"Triggers ``StorageManager.layerwise_batched_get()`` for async cache "
+"retrieval"
+msgstr "触发 ``StorageManager.layerwise_batched_get()`` 进行异步缓存查找"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:64
+msgid ""
+"Calls GPU Load Generator's ``batched_to_gpu()`` to transfer memory "
+"objects to GPU"
+msgstr "调用 GPU Load Generator 的 ``batched_to_gpu()`` 将内存对象传输到 GPU"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:65
+msgid ""
+"**Last request in batch**: Synchronizes "
+"``current_stream.wait_stream(load_stream)``"
+msgstr "**批处理中的最后请求**\\ ：同步 ``current_stream.wait_stream(load_stream)``"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:67
+msgid "**3. save_kv_layer()** (repeated for each layer)"
+msgstr "**3. save_kv_layer()**\\ （对每一层重复执行）"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:68
+msgid ""
+"**First call only**: Creates Storage Generator with upfront CPU memory "
+"allocation"
+msgstr "**首次调用仅**\\ ：创建具有预先分配 CPU 内存的存储生成器"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:69
+msgid "Advances Storage Generator via ``next()`` to process layer i"
+msgstr "通过 ``next()`` 进展存储生成器以处理第 i 层"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:70
+msgid ""
+"Calls GPU Store Generator's ``batched_from_gpu()`` to transfer GPU data "
+"to CPU"
+msgstr "调用 GPU 存储生成器的 ``batched_from_gpu()`` 将 GPU 数据传输到 CPU"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:71
+msgid ""
+"**First request in batch**: Synchronizes "
+"``store_stream.wait_stream(current_stream)``"
+msgstr "**批处理中的第一个请求**\\ ：同步 ``store_stream.wait_stream(current_stream)``"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:73
+msgid "**4. wait_for_save()**"
+msgstr "**4. wait_for_save()**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:74
+msgid "Finalizes Storage Generator with last ``next()`` call"
+msgstr "通过最后一次 ``next()`` 调用来完成存储生成器"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:75
+msgid "Completes all ``StorageManager.batched_put()`` operations"
+msgstr "完成所有 ``StorageManager.batched_put()`` 操作"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:76
+msgid "Performs GPU Store Generator cleanup"
+msgstr "执行 GPU 存储生成器清理"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:79
+msgid "Key Optimizations"
+msgstr "关键优化"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:81
+msgid "**Pipelined Memory Operations**"
+msgstr "**流水线内存操作**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:82
+msgid "The system overlaps layer N+1 computation with layer N storage."
+msgstr "系统将第 N+1 层的计算与第 N 层的存储重叠。"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:84
+msgid "**Stream Synchronization**"
+msgstr "**流同步**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:85
+msgid "Three CUDA streams coordinate operations:"
+msgstr "三个 CUDA 流协调操作："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:87
+msgid "``current_stream``: vLLM's forward pass computation"
+msgstr "``current_stream``: vLLM 的前向传播计算"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:88
+msgid "``load_stream``: KV cache loading operations"
+msgstr "``load_stream``: KV Cache 加载操作"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:89
+msgid "``store_stream``: KV cache storing operations"
+msgstr "``store_stream``: KV Cache 存储操作"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:91
+msgid "**Batch-Level Coordination**"
+msgstr "**批量级协调**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:92
+msgid "Multiple requests are processed together with specialized synchronization:"
+msgstr "多个请求一起处理，并使用专门的同步机制："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:94
+msgid ""
+"**First request**: Provides store stream synchronization to prevent GPU "
+"buffer corruption"
+msgstr "**第一次请求**\\ ：提供存储流同步以防止 GPU 缓冲区损坏"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:95
+msgid ""
+"**Last request**: Provides load stream synchronization to ensure KV cache"
+" availability"
+msgstr "**最后请求**\\ ：提供加载流同步以确保 KV Cache 可用性"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:97
+msgid "**Memory Allocation Strategies**"
+msgstr "**内存分配策略**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:98
+msgid "**Retrieval**: Layer-by-layer allocation"
+msgstr "**检索**\\ ：逐层分配"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:99
+msgid "**Storage**: Upfront allocation for all layers"
+msgstr "**存储**\\ ：为所有层的预先分配"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:101
+msgid "**Cache Key Management**"
+msgstr "**缓存键管理**"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:102
+msgid ""
+"Multi-layer cache engine keys use ``split_layers(N)`` to create per-layer"
+" kubernetes_deployment"
+msgstr "多层缓存引擎密钥使用 ``split_layers(N)`` 来创建每层的 kubernetes_deployment"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:105
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:107
+msgid "Enable layerwise caching by setting:"
+msgstr "通过设置启用逐层缓存："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:113
+msgid ""
+"The system automatically selects appropriate layerwise GPU connectors "
+"based on configuration:"
+msgstr "系统会根据配置自动选择适当的逐层显卡连接器："
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:115
+msgid "``VLLMPagedMemLayerwiseGPUConnector``: For standard layerwise operations"
+msgstr "``VLLMPagedMemLayerwiseGPUConnector``: 用于标准逐层操作"
+
+#: ../../source/kv_cache_optimizations/layerwise.rst:116
+msgid "``VLLMBufferLayerwiseGPUConnector``: When blending is enabled"
+msgstr "``VLLMBufferLayerwiseGPUConnector``: 当启用混合时"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/segmented_prefill.po b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/segmented_prefill.po
new file mode 100644
index 0000000..e780c6d
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/kv_cache_optimizations/segmented_prefill.po
@@ -0,0 +1,29 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/kv_cache_optimizations/segmented_prefill.rst:2
+msgid "Segmented Prefill"
+msgstr "分段式预填充"
+
+#: ../../source/kv_cache_optimizations/segmented_prefill.rst:6
+msgid "Documentation for segmented prefill is **coming soon**."
+msgstr "分段式预填充的文档\\ **即将**\\ 发布。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/legacy/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/legacy/index.po
new file mode 100644
index 0000000..9fa84ec
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/legacy/index.po
@@ -0,0 +1,56 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/legacy/index.rst:4
+msgid "Legacy (In-Process Mode)"
+msgstr "旧版（进程内模式）"
+
+#: ../../source/legacy/index.rst:8
+msgid ""
+"These pages document LMCache's original **in-process mode**, where "
+"LMCache ran *inside* the inference engine process (e.g. via "
+"``LMCacheConnectorV1`` on vLLM). In-process mode is **deprecated**; new "
+"deployments should use :doc:`Multiprocess (MP) mode <../mp/index>`."
+msgstr "这些页面记录了 LMCache 的原始 **进程内模式**\\ ，即 LMCache 在推理引擎进程内部运行（例如通过 ``LMCacheConnectorV1`` 集成到 vLLM）。进程内模式已 **废弃**\\ ；新的部署应使用 :doc:`多进程（MP）模式 <../mp/index>`。"
+
+#: ../../source/legacy/index.rst:14
+msgid "Background"
+msgstr "背景"
+
+#: ../../source/legacy/index.rst:16
+msgid ""
+"LMCache began as an in-process library embedded directly in the serving "
+"engine. The **multiprocess refactor** moved LMCache into a standalone "
+"``lmcache server`` and made an **asynchronous prefetching architecture** "
+"the default -- a ``LOOKUP`` followed by background L2→L1 loads -- "
+"alongside process isolation, shared caching across engine instances, and "
+"multi-tier (L1/L2) storage."
+msgstr "LMCache 最初是一个直接嵌入推理引擎的进程内库。\\ **多进程重构**\\ 将 LMCache 迁移至独立的 ``lmcache server``\\ ，并将 **异步预取架构** 设为默认——即执行 ``LOOKUP`` 后在后台进行 L2→L1 加载——同时带来进程隔离、跨引擎实例的共享缓存以及多层（L1/L2）存储。"
+
+#: ../../source/legacy/index.rst:22
+msgid ""
+"MP is now the recommended mode and is on track to support essentially "
+"everything in-process mode did. The pages below are kept for users still "
+"on in-process mode and as a historical reference while MP closes any "
+"remaining gaps; where a feature already has an MP equivalent, prefer the "
+"MP docs."
+msgstr "MP 模式（多进程）现为推荐模式，并正持续完善以支持进程内模式的几乎全部功能。以下页面保留供仍在使用进程内模式的用户参考，也作为历史资料——待 MP 模式填补剩余空白期间可查阅；若某项功能已有对应的 MP 模式实现，请优先参考 MP 文档。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/cachegen.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/cachegen.po
new file mode 100644
index 0000000..65c8a0f
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/cachegen.po
@@ -0,0 +1,32 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/cachegen.rst:2
+msgid "CacheGen"
+msgstr "CacheGen"
+
+#: ../../source/mp/cachegen.rst:6
+msgid ""
+"CacheGen KV cache compression for multiprocess mode is **not implemented "
+"yet** (coming soon). The original in-process implementation is preserved "
+"in the Legacy section: :doc:`/kv_cache_optimizations/compression/index`."
+msgstr "CacheGen KV Cache 在 MP 模式（多进程）下的压缩功能\\ **尚未实现**\\ （即将推出）。原有的进程内实现保留在旧版章节中： :doc:`/kv_cache_optimizations/compression/index`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/configuration.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/configuration.po
new file mode 100644
index 0000000..0b9561d
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/configuration.po
@@ -0,0 +1,1377 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/configuration.rst:2
+msgid "Configuration Reference"
+msgstr "配置参考"
+
+#: ../../source/mp/configuration.rst:4
+msgid ""
+"This page documents every CLI argument accepted by the LMCache "
+"multiprocess server.  Arguments are grouped by the config module that "
+"defines them."
+msgstr "本页面记录了 LMCache 多进程服务器接受的每个 CLI 参数。参数按定义它们的配置模块进行分组。"
+
+#: ../../source/mp/configuration.rst:12
+msgid "MP Server"
+msgstr "MP 服务器"
+
+#: ../../source/mp/configuration.rst:14 ../../source/mp/configuration.rst:169
+#: ../../source/mp/configuration.rst:190
+msgid "Source: ``lmcache/v1/multiprocess/config.py``"
+msgstr "源: ``lmcache/v1/multiprocess/config.py``"
+
+#: ../../source/mp/configuration.rst:20 ../../source/mp/configuration.rst:147
+#: ../../source/mp/configuration.rst:177 ../../source/mp/configuration.rst:202
+#: ../../source/mp/configuration.rst:232 ../../source/mp/configuration.rst:288
+#: ../../source/mp/configuration.rst:310 ../../source/mp/configuration.rst:329
+#: ../../source/mp/configuration.rst:361 ../../source/mp/configuration.rst:435
+msgid "Argument"
+msgstr "参数"
+
+#: ../../source/mp/configuration.rst:21 ../../source/mp/configuration.rst:148
+#: ../../source/mp/configuration.rst:178 ../../source/mp/configuration.rst:203
+#: ../../source/mp/configuration.rst:233 ../../source/mp/configuration.rst:289
+#: ../../source/mp/configuration.rst:311 ../../source/mp/configuration.rst:330
+#: ../../source/mp/configuration.rst:362 ../../source/mp/configuration.rst:436
+#: ../../source/mp/configuration.rst:503
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/configuration.rst:22 ../../source/mp/configuration.rst:149
+#: ../../source/mp/configuration.rst:179 ../../source/mp/configuration.rst:204
+#: ../../source/mp/configuration.rst:234 ../../source/mp/configuration.rst:290
+#: ../../source/mp/configuration.rst:312 ../../source/mp/configuration.rst:331
+#: ../../source/mp/configuration.rst:363 ../../source/mp/configuration.rst:437
+#: ../../source/mp/configuration.rst:504 ../../source/mp/configuration.rst:551
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/configuration.rst:23
+msgid "``--instance-id``"
+msgstr "``--instance-id``"
+
+#: ../../source/mp/configuration.rst:24
+msgid "*(unset, default UUID v4)*"
+msgstr "(未设置，默认 UUID v4)"
+
+#: ../../source/mp/configuration.rst:25
+msgid ""
+"Stable identity of this MP server. Used as the coordinator membership key"
+" and projected onto the OTel ``service.instance.id`` resource attribute "
+"on every metric and span (so telemetry and coordinator membership share "
+"one id). When the flag is not passed, defaults to a random UUID v4 minted"
+" at startup."
+msgstr ""
+"此 MP 服务器的稳定标识。用作协调器成员身份键，并投影到每条指标和每个 Span 的 OTel ``service.instance.id`` "
+"资源属性（从而使遥测数据与协调器成员身份共享同一个 ID）。若未传递该参数，则默认为启动时生成的随机 UUID v4。"
+
+#: ../../source/mp/configuration.rst:31
+msgid "``--host``"
+msgstr "``--host``"
+
+#: ../../source/mp/configuration.rst:32
+msgid "``localhost``"
+msgstr "``localhost``"
+
+#: ../../source/mp/configuration.rst:33
+msgid "Host address to bind the ZMQ server."
+msgstr "绑定 ZMQ 服务器的主机地址。"
+
+#: ../../source/mp/configuration.rst:34
+msgid "``--port``"
+msgstr "``--port``"
+
+#: ../../source/mp/configuration.rst:35 ../../source/mp/configuration.rst:519
+msgid "``5555``"
+msgstr "``5555``"
+
+#: ../../source/mp/configuration.rst:36
+msgid "Port to bind the ZMQ server."
+msgstr "绑定 ZMQ 服务器的端口。"
+
+#: ../../source/mp/configuration.rst:37
+msgid "``--chunk-size``"
+msgstr "``--chunk-size``"
+
+#: ../../source/mp/configuration.rst:38
+msgid "``256``"
+msgstr "``256``"
+
+#: ../../source/mp/configuration.rst:39
+msgid "Chunk size for KV cache operations (in tokens)."
+msgstr "KV Cache 操作的块大小（以 token 为单位）。"
+
+#: ../../source/mp/configuration.rst:40
+msgid "``--max-workers``"
+msgstr "``--max-workers``"
+
+#: ../../source/mp/configuration.rst:41
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/mp/configuration.rst:42
+msgid ""
+"Base number of worker threads. Sets the default for both the GPU "
+"(affinity) pool and the CPU (normal) pool. Can be overridden per-pool "
+"with ``--max-gpu-workers`` and ``--max-cpu-workers``."
+msgstr ""
+"工作线程的基本数量。为 GPU（亲和性）池和 CPU（正常）池设置默认值。可以通过 ``--max-gpu-workers`` 和 "
+"``--max-cpu-workers`` 针对每个池进行覆盖。"
+
+#: ../../source/mp/configuration.rst:45
+msgid "``--max-gpu-workers``"
+msgstr "``--max-gpu-workers``"
+
+#: ../../source/mp/configuration.rst:46 ../../source/mp/configuration.rst:51
+msgid "(inherits ``--max-workers``)"
+msgstr "(继承 ``--max-workers``)"
+
+#: ../../source/mp/configuration.rst:47
+msgid ""
+"Worker threads for the GPU affinity pool (STORE/RETRIEVE). Requests from "
+"the same vLLM instance are always dispatched to the same thread, "
+"eliminating GPU transfer lock contention."
+msgstr "GPU 亲和性池（STORE/RETRIEVE）的工作线程。来自同一 vLLM 实例的请求始终分发到同一线程，从而消除 GPU 传输锁竞争。"
+
+#: ../../source/mp/configuration.rst:50
+msgid "``--max-cpu-workers``"
+msgstr "``--max-cpu-workers``"
+
+#: ../../source/mp/configuration.rst:52
+msgid "Worker threads for the normal CPU pool (LOOKUP, etc.)."
+msgstr "普通 CPU 池（LOOKUP 等）的工作线程。"
+
+#: ../../source/mp/configuration.rst:53
+msgid "``--hash-algorithm``"
+msgstr "``--hash-algorithm``"
+
+#: ../../source/mp/configuration.rst:54
+msgid "``blake3``"
+msgstr "``blake3``"
+
+#: ../../source/mp/configuration.rst:55
+msgid ""
+"Hash algorithm for token-based operations. Choices: ``builtin``, "
+"``sha256_cbor``, ``blake3``."
+msgstr ""
+"基于 token 的操作所使用的哈希算法。可选项：\\ ``builtin``\\ 、\\ ``sha256_cbor``\\ 、\\ "
+"``blake3``\\ 。"
+
+#: ../../source/mp/configuration.rst:57
+msgid "``--engine-type``"
+msgstr "``--engine-type``"
+
+#: ../../source/mp/configuration.rst:58 ../../source/mp/configuration.rst:365
+#: ../../source/mp/configuration.rst:373
+msgid "``default``"
+msgstr "``default``"
+
+#: ../../source/mp/configuration.rst:59
+msgid ""
+"Cache engine backend type. ``default`` uses standard prefix caching; "
+"``blend`` selects the current CacheBlend V3 implementation (composes a "
+"``BlendV3Module`` into the engine); ``blend_legacy`` selects the original"
+" CacheBlend (composes a ``BlendModule``). Both blend variants require "
+"``--supported-transfer-mode`` to be ``lmcache_driven`` or ``auto``. "
+"Choices: ``default``, ``blend``, ``blend_legacy``."
+msgstr ""
+"缓存引擎后端类型。\\ ``default`` 使用标准前缀缓存；\\ ``blend`` 选择当前的 CacheBlend V3 实现（将 "
+"``BlendV3Module`` 组合到引擎中）；\\ ``blend_legacy`` 选择原始的 CacheBlend（将 "
+"``BlendModule`` 组合到引擎中）。这两种 blend 变体都需要 ``--supported-transfer-mode`` 设置为"
+" ``lmcache_driven`` 或 ``auto``\\ 。可选项：\\ ``default``\\ 、\\ ``blend``\\ "
+"、\\ ``blend_legacy``\\ 。"
+
+#: ../../source/mp/configuration.rst:66
+msgid "``--supported-transfer-mode``"
+msgstr "``--supported-transfer-mode``"
+
+#: ../../source/mp/configuration.rst:67 ../../source/mp/configuration.rst:534
+msgid "``auto``"
+msgstr "``auto``"
+
+#: ../../source/mp/configuration.rst:68
+msgid ""
+"Which worker → server transfer paths the server loads. ``lmcache_driven``"
+" enables only the server-driven transfer path (STORE/RETRIEVE, supports "
+"both CUDA IPC and CPU SHM); ``engine_driven`` enables only the non-GPU "
+"(PREPARE/COMMIT) transfer path; ``auto`` (default) loads both so workers "
+"of either device type can connect without manual configuration. Choices: "
+"``lmcache_driven``, ``engine_driven``, ``auto``."
+msgstr ""
+"服务器加载的工作进程 → 服务器传输路径。\\ ``lmcache_driven`` "
+"仅启用服务器驱动的传输路径（STORE/RETRIEVE，支持 CUDA IPC 与 CPU SHM）；\\ ``engine_driven`` "
+"仅启用非 GPU（PREPARE/COMMIT）传输路径；\\ ``auto``\\ "
+"（默认）同时加载两者，使任意设备类型的工作进程无需手动配置即可连接。可选项：\\ ``lmcache_driven``\\ 、\\ "
+"``engine_driven``\\ 、\\ ``auto``\\ 。"
+
+#: ../../source/mp/configuration.rst:76
+msgid "``--runtime-plugin-locations``"
+msgstr "``--runtime-plugin-locations``"
+
+#: ../../source/mp/configuration.rst:77 ../../source/mp/configuration.rst:88
+msgid "``[]``"
+msgstr "``[]``"
+
+#: ../../source/mp/configuration.rst:78
+msgid ""
+"Zero or more paths to runtime plugin scripts or directories to launch "
+"alongside the server. Plugins are spawned by ``MPRuntimePluginLauncher`` "
+"and receive the full server config via the "
+"``LMCACHE_RUNTIME_PLUGIN_CONFIG`` environment variable."
+msgstr ""
+"零个或多个路径，用于运行时插件脚本或目录，以便与服务器一起启动。插件由 ``MPRuntimePluginLauncher`` 生成，并通过 "
+"``LMCACHE_RUNTIME_PLUGIN_CONFIG`` 环境变量接收完整的服务器配置。"
+
+#: ../../source/mp/configuration.rst:82
+msgid "``--runtime-plugin-config``"
+msgstr "``--runtime-plugin-config``"
+
+#: ../../source/mp/configuration.rst:83
+#, python-brace-format
+msgid "``\"{}\"``"
+msgstr "``\"{}\"``"
+
+#: ../../source/mp/configuration.rst:84
+#, python-brace-format
+msgid ""
+"JSON string of extra key-value config forwarded to runtime plugins via "
+"``LMCACHE_RUNTIME_PLUGIN_EXTRA_CONFIG``. Example: "
+"``'{\"plugin.frontend.heartbeat_url\": "
+"\"http://localhost:5000/heartbeat\"}'``."
+msgstr ""
+"通过 ``LMCACHE_RUNTIME_PLUGIN_EXTRA_CONFIG`` 转发到运行时插件的额外键值配置的 JSON "
+"字符串。示例：\\ ``'{\\\"plugin.frontend.heartbeat_url\\\": "
+"\\\"http://localhost:5000/heartbeat\\\"}'``\\ 。"
+
+#: ../../source/mp/configuration.rst:87
+msgid "``--script-allowed-imports``"
+msgstr "``--script-allowed-imports``"
+
+#: ../../source/mp/configuration.rst:89
+msgid ""
+"Space-separated list of Python module names that scripts posted to the "
+"HTTP ``/run_script`` endpoint are allowed to import. Example: ``--script-"
+"allowed-imports numpy pandas``."
+msgstr ""
+"允许在 HTTP ``/run_script`` 端点发布的脚本导入的以空格分隔的 Python 模块名称列表。示例：\\ ``--script-"
+"allowed-imports numpy pandas``\\ 。"
+
+#: ../../source/mp/configuration.rst:92
+msgid "``--shm-name``"
+msgstr "``--shm-name``"
+
+#: ../../source/mp/configuration.rst:93 ../../source/mp/configuration.rst:251
+msgid "*(not set)*"
+msgstr "(未设置)"
+
+#: ../../source/mp/configuration.rst:94
+msgid ""
+"SHM segment name for non-GPU KV transfer (only used when the non-GPU path"
+" is loaded, i.e. ``--supported-transfer-mode`` is ``auto`` or "
+"``engine_driven``). Not set (default): auto-allocate a shared-memory "
+"pool. ``\"\"`` (empty string): disable SHM and force the pickle transfer "
+"path.  Any other value: use that exact name for the SHM pool segment."
+msgstr ""
+"非 GPU KV 传输的 SHM 段名称（仅在加载非 GPU 路径时使用，即 ``--supported-transfer-mode`` 为 "
+"``auto`` 或 ``engine_driven``\\ ）。未设置（默认）：自动分配一个共享内存池。 ``\\\"\\\"``\\ "
+"（空字符串）：禁用 SHM 并强制使用 pickle 传输路径。 任何其他值：将该确切名称用于 SHM 池段。"
+
+#: ../../source/mp/configuration.rst:101
+msgid "``--worker-reap-timeout-seconds``"
+msgstr "``--worker-reap-timeout-seconds``"
+
+#: ../../source/mp/configuration.rst:102
+msgid "``120.0``"
+msgstr "``120.0``"
+
+#: ../../source/mp/configuration.rst:103
+msgid ""
+"Silence budget (seconds) after which a worker that has sent at least one "
+"heartbeat PING but then gone quiet has its KV cache registration reaped, "
+"freeing the leaked GPU context and CUDA IPC handles. ``0`` disables "
+"reaping. Keep this at least 3x the engine adapter's "
+"``lmcache.mp.heartbeat_interval`` (default 10s) so a few missed pings "
+"never reap a live worker; the adapter warns at startup if its interval is"
+" raised without raising this."
+msgstr ""
+"工作线程发送至少一个心跳 PING 后进入静默状态的最长容忍时间（秒），超时后将回收其 KV Cache 注册，并释放泄漏的 GPU 上下文和 "
+"CUDA IPC 句柄。\\ ``0`` 表示禁用回收。建议将此值保持在引擎适配器 "
+"``lmcache.mp.heartbeat_interval``\\ （默认 10 秒）的至少 3 "
+"倍，以免少量心跳丢失导致活跃工作线程被误回收；若未同步调大此值而单独调大心跳间隔，适配器将在启动时发出警告。"
+
+#: ../../source/mp/configuration.rst:110
+msgid "``--worker-registration-grace-seconds``"
+msgstr "``--worker-registration-grace-seconds``"
+
+#: ../../source/mp/configuration.rst:111
+msgid "``3600.0``"
+msgstr "``3600.0``"
+
+#: ../../source/mp/configuration.rst:112
+msgid ""
+"Silence budget (seconds) for a worker that registered but has never sent "
+"a PING (still warming up, or died before its first request). Must be >= "
+"``--worker-reap-timeout-seconds``. Generous by default so slow model "
+"warmup is never mistaken for a dead worker."
+msgstr ""
+"针对已注册但从未发送 PING 的工作线程（仍在预热或在首次请求前已崩溃）的静默容忍时间（秒）。必须大于或等于 ``--worker-reap-"
+"timeout-seconds``\\ 。默认值较宽松，以避免将缓慢的模型预热误判为工作线程已宕机。"
+
+#: ../../source/mp/configuration.rst:116
+msgid "``--enable-segmented-prefix``"
+msgstr "``--enable-segmented-prefix``"
+
+#: ../../source/mp/configuration.rst:117
+msgid "``False``"
+msgstr "``False``"
+
+#: ../../source/mp/configuration.rst:118
+msgid ""
+"CacheBlend (``--engine-type blend``) only: on a mid-prefix L2 retrieve "
+"failure, retain the gapped prefix so the post-gap chunks stay L1-resident"
+" and only the dropped gap is recomputed, instead of truncating the prefix"
+" at the gap. No effect for other engines. See "
+":doc:`/mp/l2_storage/fault_inject` for a way to exercise it."
+msgstr ""
+"CacheBlend (``--engine-type blend``) 仅适用：在中间前缀 L2 检索失败时，保留缺口前缀，以便缺口后的块保持在"
+" L1 中驻留，只有丢失的缺口被重计算，而不是在缺口处截断前缀。对其他引擎没有影响。有关如何使用它，请参见 "
+":doc:`/mp/l2_storage/fault_inject`。"
+
+#: ../../source/mp/configuration.rst:123
+msgid "``--separate-object-groups`` / ``--no-separate-object-groups``"
+msgstr "``--separate-object-groups`` / ``--no-separate-object-groups``"
+
+#: ../../source/mp/configuration.rst:124 ../../source/mp/configuration.rst:240
+#: ../../source/mp/configuration.rst:297
+msgid "``True``"
+msgstr "``True``"
+
+#: ../../source/mp/configuration.rst:125
+msgid ""
+"Split a hybrid model's kernel groups into one object group per cross-"
+"chunk attention window (full attention, each sliding-window size, "
+"mamba/GDN) at KV-cache registration. On by default; pass ``--no-separate-"
+"object-groups`` to keep all layers in a single full-attention object "
+"group. Transparent to correctness; a non-hybrid model always resolves to "
+"one object group. See :doc:`/mp/hybrid_models`."
+msgstr ""
+"在 KV-cache 注册时，将混合模型的内核组拆分为每个跨块注意窗口（全注意力、每个滑动窗口大小、mamba/GDN）一个对象组。默认开启；传递"
+" ``--no-separate-object-groups`` "
+"以将所有层保持在一个完整的注意力对象组中。对正确性透明；非混合模型始终解析为一个对象组。请参阅 :doc:`/mp/hybrid_models`。"
+
+#: ../../source/mp/configuration.rst:133
+msgid "Lookup Hash Logging"
+msgstr "查找哈希日志记录"
+
+#: ../../source/mp/configuration.rst:135
+msgid "Source: ``lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py``"
+msgstr "源: ``lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py``"
+
+#: ../../source/mp/configuration.rst:137
+msgid ""
+"When enabled, the server publishes chunk hashes computed during "
+"``lookup()`` as ``MP_LOOKUP`` events on the EventBus.  The "
+"``LookupHashLoggingSubscriber`` writes these to rotating JSONL files for "
+"offline analysis.  Disabled by default.  These arguments are part of the "
+"Observability group."
+msgstr ""
+"启用时，服务器将在 EventBus 上以 ``MP_LOOKUP`` 事件的形式发布 ``lookup()`` 期间计算的块哈希。\\ "
+"``LookupHashLoggingSubscriber`` 会将这些事件写入滚动 JSONL "
+"文件以供离线分析。默认禁用。这些参数属于可观察性配置组。"
+
+#: ../../source/mp/configuration.rst:150
+msgid "``--lookup-hash-log-dir``"
+msgstr "``--lookup-hash-log-dir``"
+
+#: ../../source/mp/configuration.rst:151
+msgid "``\"\"`` (disabled)"
+msgstr "``\"\"`` (禁用)"
+
+#: ../../source/mp/configuration.rst:152
+msgid ""
+"Directory to write lookup hash JSONL files. An empty string disables "
+"logging."
+msgstr "写入查找哈希 JSONL 文件的目录。空字符串将禁用日志记录。"
+
+#: ../../source/mp/configuration.rst:154
+msgid "``--lookup-hash-log-rotation-interval``"
+msgstr "``--lookup-hash-log-rotation-interval``"
+
+#: ../../source/mp/configuration.rst:155
+msgid "``21600`` (6 h)"
+msgstr "``21600`` (6 小时)"
+
+#: ../../source/mp/configuration.rst:156
+msgid "Time interval in seconds before rotating to a new log file."
+msgstr "滚动到新日志文件前的时间间隔（秒）。"
+
+#: ../../source/mp/configuration.rst:157
+msgid "``--lookup-hash-log-rotation-max-size``"
+msgstr "``--lookup-hash-log-rotation-max-size``"
+
+#: ../../source/mp/configuration.rst:158
+msgid "``104857600`` (100 MB)"
+msgstr "``104857600`` (100 MB)"
+
+#: ../../source/mp/configuration.rst:159
+msgid ""
+"Max file size in bytes before rotating even if the time interval has not "
+"elapsed."
+msgstr "即使时间间隔未到，触发滚动的最大文件大小（字节）。"
+
+#: ../../source/mp/configuration.rst:161
+msgid "``--lookup-hash-log-max-files``"
+msgstr "``--lookup-hash-log-max-files``"
+
+#: ../../source/mp/configuration.rst:162
+msgid "``100``"
+msgstr "``100``"
+
+#: ../../source/mp/configuration.rst:163
+msgid ""
+"Max number of log files to keep.  Oldest files are deleted when this "
+"limit is exceeded."
+msgstr "保留的最大日志文件数量。当超过此限制时，最旧的文件将被删除。"
+
+#: ../../source/mp/configuration.rst:167
+msgid "HTTP Frontend"
+msgstr "HTTP 前端"
+
+#: ../../source/mp/configuration.rst:171
+msgid "The HTTP frontend is included when running ``lmcache server``."
+msgstr "HTTP 前端在运行 ``lmcache server`` 时包含在内。"
+
+#: ../../source/mp/configuration.rst:180
+msgid "``--http-host``"
+msgstr "``--http-host``"
+
+#: ../../source/mp/configuration.rst:181
+msgid "``0.0.0.0``"
+msgstr "``0.0.0.0``"
+
+#: ../../source/mp/configuration.rst:182
+msgid "Host to bind the HTTP (FastAPI/uvicorn) server."
+msgstr "绑定 HTTP (FastAPI/uvicorn) 服务器的主机。"
+
+#: ../../source/mp/configuration.rst:183
+msgid "``--http-port``"
+msgstr "``--http-port``"
+
+#: ../../source/mp/configuration.rst:184
+msgid "``8080``"
+msgstr "``8080``"
+
+#: ../../source/mp/configuration.rst:185
+msgid "Port to bind the HTTP server."
+msgstr "绑定 HTTP 服务器的端口。"
+
+#: ../../source/mp/configuration.rst:188
+msgid "P2P"
+msgstr "P2P"
+
+#: ../../source/mp/configuration.rst:192
+msgid ""
+"These flags configure peer-to-peer KV cache sharing between MP servers "
+"(see :doc:`p2p`). They are registered by ``add_p2p_args()`` on the "
+"``lmcache server`` parser. P2P is enabled when ``--p2p-advertise-url`` is"
+" set, which additionally requires a coordinator URL via ``--coordinator-"
+"url`` (or ``LMCACHE_COORDINATOR_URL``)."
+msgstr "这些标志配置 MP 服务器之间的点对点 KV Cache 共享（请参见 :doc:`p2p`）。它们通过 ``add_p2p_args()`` 在 ``lmcache server`` 解析器中注册。当设置了 ``--p2p-advertise-url`` 时，P2P 被启用，这还需要通过 ``--coordinator-url``（或 ``LMCACHE_COORDINATOR_URL``）提供协调器 URL。"
+
+#: ../../source/mp/configuration.rst:205
+msgid "``--p2p-advertise-url``"
+msgstr "``--p2p-advertise-url``"
+
+#: ../../source/mp/configuration.rst:206
+msgid "``\"\"`` (P2P disabled)"
+msgstr "``\"\"`` (P2P 已禁用)"
+
+#: ../../source/mp/configuration.rst:207
+msgid ""
+"Transfer-channel server ``host:port`` this instance advertises to peers. "
+"Setting it enables P2P (also requires ``--coordinator-url``)."
+msgstr "传输通道服务器 ``host:port`` 该实例向对等方宣传。设置它可以启用 P2P（还需要 ``--coordinator-url``）。"
+
+#: ../../source/mp/configuration.rst:209
+msgid "``--p2p-listen-url``"
+msgstr "``--p2p-listen-url``"
+
+#: ../../source/mp/configuration.rst:210
+#, python-brace-format
+msgid "``\"\"``"
+msgstr "``\"\"``"
+
+#: ../../source/mp/configuration.rst:211
+msgid ""
+"Transfer-channel server ``host:port`` to bind. Defaults to ``--p2p-"
+"advertise-url``."
+msgstr "传输通道服务器 ``host:port`` 进行绑定。默认为 ``--p2p-advertise-url``。"
+
+#: ../../source/mp/configuration.rst:213
+msgid "``--p2p-lookup-timeout``"
+msgstr "``--p2p-lookup-timeout``"
+
+#: ../../source/mp/configuration.rst:214 ../../source/mp/configuration.rst:217
+msgid "``30.0``"
+msgstr "``30.0``"
+
+#: ../../source/mp/configuration.rst:215
+msgid "Seconds before a peer lookup result counts as a miss."
+msgstr "在查找结果被视为未命中之前的秒数。"
+
+#: ../../source/mp/configuration.rst:216
+msgid "``--p2p-load-timeout``"
+msgstr "``--p2p-load-timeout``"
+
+#: ../../source/mp/configuration.rst:218
+msgid "Seconds before a peer load counts as a failure."
+msgstr "在对等加载被视为失败之前的秒数。"
+
+#: ../../source/mp/configuration.rst:219
+msgid "``--p2p-transfer-engine``"
+msgstr "``--p2p-transfer-engine``"
+
+#: ../../source/mp/configuration.rst:220
+msgid "``nixl``"
+msgstr "``nixl``"
+
+#: ../../source/mp/configuration.rst:221
+msgid "Transfer-channel implementation to use."
+msgstr "使用的传输通道实现。"
+
+#: ../../source/mp/configuration.rst:224
+msgid "L1 Memory Manager"
+msgstr "L1 内存管理器"
+
+#: ../../source/mp/configuration.rst:226 ../../source/mp/configuration.rst:263
+#: ../../source/mp/configuration.rst:304 ../../source/mp/configuration.rst:323
+#: ../../source/mp/configuration.rst:355
+msgid "Source: ``lmcache/v1/distributed/config.py``"
+msgstr "来源: ``lmcache/v1/distributed/config.py``"
+
+#: ../../source/mp/configuration.rst:235
+msgid "``--l1-size-gb``"
+msgstr "``--l1-size-gb``"
+
+#: ../../source/mp/configuration.rst:236 ../../source/mp/configuration.rst:333
+msgid "*required*"
+msgstr "必需"
+
+#: ../../source/mp/configuration.rst:237
+msgid ""
+"Size of the L1 tier in GB. Sizes the pinned-DRAM L1 by default, or the "
+"GDS slab file when ``--gds-l1-path`` is set (see *GDS L1 Tier* below)."
+msgstr ""
+"L1 层的大小（以 GB 为单位）。默认情况下，设置固定 DRAM 的 L1 大小，或者在设置了 ``--gds-l1-path`` 时，设置 "
+"GDS 块文件（请参见下面的GDS L1 层）。"
+
+#: ../../source/mp/configuration.rst:239
+msgid "``--l1-use-lazy`` / ``--no-l1-use-lazy``"
+msgstr "``--l1-use-lazy`` / ``--no-l1-use-lazy``"
+
+#: ../../source/mp/configuration.rst:241
+msgid ""
+"Enable or disable lazy allocation for L1 memory. Pass ``--l1-use-lazy`` "
+"to enable (default) or ``--no-l1-use-lazy`` to explicitly disable."
+msgstr "启用或禁用 L1 内存的延迟分配。传递 ``--l1-use-lazy`` 以启用（默认）或 ``--no-l1-use-lazy`` 以显式禁用。"
+
+#: ../../source/mp/configuration.rst:244
+msgid "``--l1-init-size-gb``"
+msgstr "``--l1-init-size-gb``"
+
+#: ../../source/mp/configuration.rst:245
+msgid "``20``"
+msgstr "``20``"
+
+#: ../../source/mp/configuration.rst:246
+msgid "Initial allocation size (GB) when using lazy allocation."
+msgstr "使用延迟分配时的初始分配大小（GB）。"
+
+#: ../../source/mp/configuration.rst:247
+msgid "``--l1-align-bytes``"
+msgstr "``--l1-align-bytes``"
+
+#: ../../source/mp/configuration.rst:248
+msgid "``4096``"
+msgstr "``4096``"
+
+#: ../../source/mp/configuration.rst:249
+msgid "Alignment size in bytes (default 4 KB)."
+msgstr "对齐大小（以字节为单位，默认 4 KB）。"
+
+#: ../../source/mp/configuration.rst:250
+msgid "``--l1-devdax-path``"
+msgstr "``--l1-devdax-path``"
+
+#: ../../source/mp/configuration.rst:252
+msgid ""
+"Optional ``/dev/dax*`` device or mmap-able file to use as the L1 backing "
+"arena.  When set, disable lazy allocation with ``--no-l1-use-lazy`` and "
+"disable SHM transfer advertising with ``--shm-name \"\"`` because the L1 "
+"bytes live in the DAX mapping.  If a DAX L2 adapter with the same "
+"``device_path`` is registered, that adapter's ``max_dax_size_gb`` is used"
+" as the L1 Device-DAX overflow size."
+msgstr ""
+"可选的 ``/dev/dax*`` 设备或可 mmap 的文件，用作 L1 后备区域。当设置时，使用 ``--no-l1-use-lazy`` "
+"禁用延迟分配，并使用 ``--shm-name \\\"\\\"`` 禁用 SHM 传输广告，因为 L1 字节存在于 DAX "
+"映射中。如果注册了具有相同 ``device_path`` 的 DAX L2 适配器，则该适配器的 ``max_dax_size_gb`` 将用作"
+" L1 Device-DAX 溢出大小。"
+
+#: ../../source/mp/configuration.rst:261
+msgid "GDS L1 Tier"
+msgstr "GDS L1 层"
+
+#: ../../source/mp/configuration.rst:265
+msgid ""
+"Opt-in. Setting ``--gds-l1-path`` switches the L1 medium from pinned DRAM"
+" to an NVMe slab file accessed via GPUDirect Storage DMA. The CPU pinned-"
+"DRAM tier is then disabled, and ``--l1-size-gb`` sizes the slab. Disable "
+"byte-array L2 adapters when this is on (the GDS tier exposes no L1 memory"
+" buffer for them to register)."
+msgstr ""
+"选择加入。设置 ``--gds-l1-path`` 将 L1 媒介从固定 DRAM 切换到通过 GPUDirect Storage DMA 访问的"
+" NVMe 块文件。然后禁用 CPU 固定 DRAM 层，并且 ``--l1-size-gb`` 设置块的大小。当此选项开启时，禁用字节数组 L2"
+" 适配器（GDS 层不提供 L1 内存缓冲区供它们注册）。"
+
+#: ../../source/mp/configuration.rst:271
+msgid ""
+"The DMA path is selected automatically by platform: **cuFile** "
+"(``libcufile.so``) on NVIDIA and **hipFile** (``libhipfile.so``, "
+"`ROCm/hipFile <https://github.com/ROCm/hipFile>`_) on AMD ROCm. The same "
+"flags apply to both; no configuration change is needed to switch vendors."
+msgstr ""
+"DMA 路径由平台自动选择：NVIDIA 上使用 **cuFile** (``libcufile.so``)，而 AMD ROCm 上使用 "
+"**hipFile** (``libhipfile.so``，`ROCm/hipFile "
+"<https://github.com/ROCm/hipFile>`_)。这两个平台适用相同的标志；切换供应商无需更改配置。"
+
+#: ../../source/mp/configuration.rst:278
+msgid ""
+"AMD hipFile requires ROCm >= 7.2.0. The zero-copy GPUDirect fast path "
+"additionally needs a kernel built with ``CONFIG_PCI_P2PDMA``, ``amdgpu-"
+"dkms >= 30.20.1``, and the slab on a local NVMe ext4/xfs filesystem; "
+"where those are unavailable hipFile transparently falls back to a host-"
+"bounce compatibility path (correct, but not zero-copy)."
+msgstr ""
+"AMD hipFile 需要 ROCm >= 7.2.0。零拷贝 GPUDirect 快速路径还需要一个使用 "
+"``CONFIG_PCI_P2PDMA`` 构建的内核、``amdgpu-dkms >= 30.20.1``，以及在本地 NVMe "
+"ext4/xfs 文件系统上的 slab；如果这些不可用，hipFile 会透明地回退到主机跳跃兼容路径（正确，但不是零拷贝）。"
+
+#: ../../source/mp/configuration.rst:291
+msgid "``--gds-l1-path``"
+msgstr "``--gds-l1-path``"
+
+#: ../../source/mp/configuration.rst:292
+msgid "Not set"
+msgstr "未设置"
+
+#: ../../source/mp/configuration.rst:293
+msgid ""
+"NVMe directory for the GDS L1 slab. Setting this enables the GDS L1 tier;"
+" one shared slab per process lives at ``<path>/lmcache_gds_slab.bin``."
+msgstr ""
+"GDS L1 slab 的 NVMe 目录。设置此项将启用 GDS L1 层；每个进程共享一个位于 "
+"``<path>/lmcache_gds_slab.bin`` 的 slab。"
+
+#: ../../source/mp/configuration.rst:296
+msgid "``--gds-l1-use-direct-io`` / ``--no-gds-l1-use-direct-io``"
+msgstr "``--gds-l1-use-direct-io`` / ``--no-gds-l1-use-direct-io``"
+
+#: ../../source/mp/configuration.rst:298
+msgid ""
+"Open the slab with ``O_DIRECT`` (required for the GDS DMA fast path on "
+"ext4)."
+msgstr "使用 ``O_DIRECT`` 打开 slab（在 ext4 上的 GDS DMA 快速路径所需）。"
+
+#: ../../source/mp/configuration.rst:302
+msgid "L1 Manager TTLs"
+msgstr "L1 管理器 TTLs"
+
+#: ../../source/mp/configuration.rst:313
+msgid "``--l1-write-ttl-seconds``"
+msgstr "``--l1-write-ttl-seconds``"
+
+#: ../../source/mp/configuration.rst:314
+msgid "``600``"
+msgstr "``600``"
+
+#: ../../source/mp/configuration.rst:315
+msgid "Time-to-live for each object's write lock (seconds)."
+msgstr "每个对象的写锁的生存时间（秒）。"
+
+#: ../../source/mp/configuration.rst:316
+msgid "``--l1-read-ttl-seconds``"
+msgstr "``--l1-read-ttl-seconds``"
+
+#: ../../source/mp/configuration.rst:317
+msgid "``300``"
+msgstr "``300``"
+
+#: ../../source/mp/configuration.rst:318
+msgid "Time-to-live for each object's read lock (seconds)."
+msgstr "每个对象的读取锁的生存时间（秒）。"
+
+#: ../../source/mp/configuration.rst:321
+msgid "Eviction Policy"
+msgstr "逐出策略"
+
+#: ../../source/mp/configuration.rst:332
+msgid "``--eviction-policy``"
+msgstr "``--eviction-policy``"
+
+#: ../../source/mp/configuration.rst:334
+msgid ""
+"Eviction policy. Choices: ``LRU``, ``IsolatedLRU``, ``noop``. Use "
+"``noop`` for buffer-only mode where L1 acts as a pure write buffer (data "
+"is deleted from L1 after L2 store). ``IsolatedLRU`` maintains one LRU "
+"list per ``cache_salt`` and requires per-``cache_salt`` quotas to be "
+"configured at runtime via the ``/quota`` HTTP endpoints (see :ref:`mp-"
+"http-quota-api`); a ``cache_salt`` with no registered quota has an "
+"effective limit of ``0`` bytes, so its data is evicted at the next "
+"eviction cycle (allowlist semantics)."
+msgstr ""
+"逐出策略。可选项：\\ ``LRU``\\ 、\\ ``IsolatedLRU``\\ 、\\ ``noop``\\ 。\\ ``noop`` "
+"用于纯缓冲区模式，此时 L1 仅作为写缓冲区（数据写入 L2 后即从 L1 删除）。\\ ``IsolatedLRU`` 为每个 "
+"``cache_salt`` 维护独立的 LRU 列表，并要求在运行时通过 ``/quota`` HTTP 端点为每个 "
+"``cache_salt`` 配置配额（参见 :ref:`mp-http-quota-api`）；未注册配额的 ``cache_salt`` "
+"的有效上限为 ``0`` 字节，其数据将在下一个逐出周期被清除（白名单语义）。"
+
+#: ../../source/mp/configuration.rst:345
+msgid "``--eviction-trigger-watermark``"
+msgstr "``--eviction-trigger-watermark``"
+
+#: ../../source/mp/configuration.rst:346
+msgid "``0.8``"
+msgstr "``0.8``"
+
+#: ../../source/mp/configuration.rst:347
+msgid "Memory usage ratio (0.0--1.0) that triggers eviction."
+msgstr "触发逐出的内存使用比例 (0.0--1.0)。"
+
+#: ../../source/mp/configuration.rst:348
+msgid "``--eviction-ratio``"
+msgstr "``--eviction-ratio``"
+
+#: ../../source/mp/configuration.rst:349
+msgid "``0.2``"
+msgstr "``0.2``"
+
+#: ../../source/mp/configuration.rst:350
+msgid "Fraction of allocated memory to evict when triggered (0.0--1.0)."
+msgstr "触发时逐出的已分配内存比例 (0.0--1.0)。"
+
+#: ../../source/mp/configuration.rst:353
+msgid "L2 Policies"
+msgstr "L2 策略"
+
+#: ../../source/mp/configuration.rst:364
+msgid "``--l2-store-policy``"
+msgstr "``--l2-store-policy``"
+
+#: ../../source/mp/configuration.rst:366
+msgid ""
+"L2 store policy.  Determines which adapters receive each key and whether "
+"keys are deleted from L1 after L2 store. The ``default`` policy stores "
+"all keys to all adapters and keeps L1. The ``skip_l1`` policy stores all "
+"keys to all adapters and then deletes them from L1 (buffer-only mode). "
+"Choices: ``default``, ``skip_l1``."
+msgstr ""
+"L2 存储策略。决定每个键被写入哪些适配器，以及 L2 存储完成后是否从 L1 删除该键。\\ ``default`` "
+"策略将所有键写入全部适配器并保留 L1 中的数据。\\ ``skip_l1`` 策略将所有键写入全部适配器后从 L1 "
+"删除（纯缓冲区模式）。可选项：\\ ``default``\\ 、\\ ``skip_l1``\\ 。"
+
+#: ../../source/mp/configuration.rst:372
+msgid "``--l2-prefetch-policy``"
+msgstr "``--l2-prefetch-policy``"
+
+#: ../../source/mp/configuration.rst:374
+msgid ""
+"L2 prefetch policy.  Determines which adapter loads each key when "
+"multiple adapters have it. The ``default`` policy picks the first adapter"
+" (lowest index). Prefetched keys are temporary (deleted after the reader "
+"finishes). The ``retain`` policy uses the same load plan but keeps "
+"prefetched keys permanently in L1. Choices: ``default``, ``retain``."
+msgstr ""
+"L2 预取策略。当多个适配器均持有某个键时，决定由哪个适配器加载该键。\\ ``default`` "
+"策略选择第一个适配器（索引最小）。预取的键是临时的（读取完成后删除）。\\ ``retain`` 策略采用相同的加载计划，但将预取的键永久保留在 "
+"L1 中。可选项：\\ ``default``\\ 、\\ ``retain``\\ 。"
+
+#: ../../source/mp/configuration.rst:381
+msgid "``--l2-prefetch-max-in-flight``"
+msgstr "``--l2-prefetch-max-in-flight``"
+
+#: ../../source/mp/configuration.rst:382
+msgid "``8``"
+msgstr "``8``"
+
+#: ../../source/mp/configuration.rst:383
+msgid ""
+"Maximum number of concurrent prefetch (L2 load) requests. Limits how many"
+" in-flight loads the PrefetchController may issue at once, preventing "
+"excessive L1 memory pressure."
+msgstr "最大并发预取（L2 加载）请求数量。限制 PrefetchController 同时发起的在途加载数，防止 L1 内存压力过大。"
+
+#: ../../source/mp/configuration.rst:386
+msgid "``--periodic-notifier-interval-ms``"
+msgstr "``--periodic-notifier-interval-ms``"
+
+#: ../../source/mp/configuration.rst:387
+msgid "``5``"
+msgstr "``5``"
+
+#: ../../source/mp/configuration.rst:388
+msgid ""
+"Interval in milliseconds for the periodic event notifier heartbeat.  A "
+"native C++ background thread writes to all registered file descriptors at"
+" this interval, waking controller poll loops for L2 adapters that lack "
+"native async completion callbacks."
+msgstr ""
+"定期事件通知器心跳的间隔（毫秒）。一个原生 C++ 后台线程按此间隔向所有已注册的文件描述符写入数据，以唤醒缺少原生异步完成回调的 L2 "
+"适配器的控制器轮询循环。"
+
+#: ../../source/mp/configuration.rst:395
+msgid "L2 Adapters"
+msgstr "L2 适配器"
+
+#: ../../source/mp/configuration.rst:397
+msgid "Source: ``lmcache/v1/distributed/l2_adapters/config.py``"
+msgstr "源: ``lmcache/v1/distributed/l2_adapters/config.py``"
+
+#: ../../source/mp/configuration.rst:399
+msgid ""
+"L2 adapters are configured via repeatable ``--l2-adapter <JSON>`` "
+"arguments. Each JSON object must include a ``\"type\"`` field that "
+"selects the adapter type. The order of ``--l2-adapter`` arguments "
+"determines the adapter order (cascade)."
+msgstr ""
+"L2 适配器通过可重复的 ``--l2-adapter <JSON>`` 参数进行配置。每个 JSON 对象必须包含一个 ``\"type\"``"
+" 字段，用于选择适配器类型。\\ ``--l2-adapter`` 参数的顺序决定了适配器的顺序（级联）。"
+
+#: ../../source/mp/configuration.rst:403
+msgid ""
+"Registered adapter types: ``nixl_store``, ``nixl_store_dynamic``, ``fs``,"
+" ``fs_native``, ``mock``, ``mooncake_store``, ``aerospike``, ``s3``, "
+"``resp``, ``plugin``, ``native_plugin``, ``raw_block``, ``dax``."
+msgstr ""
+"注册的适配器类型：\\ ``nixl_store``, ``nixl_store_dynamic``, ``fs``, "
+"``fs_native``, ``mock``, ``mooncake_store``, ``aerospike``, ``s3``, "
+"``resp``, ``plugin``, ``native_plugin``, ``raw_block``, ``dax``\\ 。"
+
+#: ../../source/mp/configuration.rst:407
+msgid ""
+"Each adapter type's required and optional fields, plus per-backend "
+"examples, are documented on its own page under :doc:`Secondary KV Storage"
+" <l2_storage/index>` -- including the adapters not detailed inline here "
+"(``fs_native``, ``raw_block``, ``dax``, ``mooncake_store``, "
+"``aerospike``, ``hfbucket``, ``resp``)."
+msgstr ""
+"每种适配器类型的必需字段和可选字段，以及每个后端的示例，都在其自己的页面上记录，位于 :doc:`Secondary KV Storage "
+"<l2_storage/index>` 下 -- 包括此处未详细说明的适配器（``fs_native``, ``raw_block``, "
+"``dax``, ``mooncake_store``, ``aerospike``, ``hfbucket``, ``resp``）。"
+
+#: ../../source/mp/configuration.rst:414
+msgid "Multiple adapters (cascade)"
+msgstr "多个适配器（级联）"
+
+#: ../../source/mp/configuration.rst:416
+msgid ""
+"Pass ``--l2-adapter`` multiple times.  Adapters are used in the order "
+"given:"
+msgstr "多次传递 ``--l2-adapter``\\ 。适配器按给定顺序使用："
+
+#: ../../source/mp/configuration.rst:424
+msgid "Observability"
+msgstr "可观察性"
+
+#: ../../source/mp/configuration.rst:426
+msgid "Source: ``lmcache/v1/mp_observability/config.py``"
+msgstr "源: ``lmcache/v1/mp_observability/config.py``"
+
+#: ../../source/mp/configuration.rst:428
+msgid ""
+"See :doc:`observability/index` for full details on the three modes "
+"(metrics, logging, tracing)."
+msgstr "三种模式（指标、日志记录、链路追踪）的完整说明，请参见 :doc:`observability/index`。"
+
+#: ../../source/mp/configuration.rst:438
+msgid "``--disable-observability``"
+msgstr "``--disable-observability``"
+
+#: ../../source/mp/configuration.rst:439 ../../source/mp/configuration.rst:442
+#: ../../source/mp/configuration.rst:445 ../../source/mp/configuration.rst:448
+msgid "off"
+msgstr "关闭"
+
+#: ../../source/mp/configuration.rst:440
+msgid "Master switch: disable the EventBus entirely."
+msgstr "总开关：完全禁用 EventBus。"
+
+#: ../../source/mp/configuration.rst:441
+msgid "``--disable-metrics``"
+msgstr "``--disable-metrics``"
+
+#: ../../source/mp/configuration.rst:443
+msgid "Skip metrics subscribers (no Prometheus endpoint)."
+msgstr "跳过指标订阅者（不暴露 Prometheus 端点）。"
+
+#: ../../source/mp/configuration.rst:444
+msgid "``--disable-logging``"
+msgstr "``--disable-logging``"
+
+#: ../../source/mp/configuration.rst:446
+msgid "Skip logging subscribers."
+msgstr "跳过日志订阅者。"
+
+#: ../../source/mp/configuration.rst:447
+msgid "``--enable-tracing``"
+msgstr "``--enable-tracing``"
+
+#: ../../source/mp/configuration.rst:449
+msgid "Register tracing subscribers. Requires ``--otlp-endpoint``."
+msgstr "注册追踪订阅者。需要 ``--otlp-endpoint``\\ 。"
+
+#: ../../source/mp/configuration.rst:450
+msgid "``--event-bus-queue-size``"
+msgstr "``--event-bus-queue-size``"
+
+#: ../../source/mp/configuration.rst:451
+msgid "``10000``"
+msgstr "``10000``"
+
+#: ../../source/mp/configuration.rst:452
+msgid "Max events in the EventBus queue before tail-drop."
+msgstr "事件总线队列中最大事件数，超过后将进行尾部丢弃。"
+
+#: ../../source/mp/configuration.rst:453
+msgid "``--otlp-endpoint``"
+msgstr "``--otlp-endpoint``"
+
+#: ../../source/mp/configuration.rst:454
+msgid "*(none)*"
+msgstr "(无)"
+
+#: ../../source/mp/configuration.rst:455
+msgid "OTLP gRPC endpoint for exporting metrics and traces."
+msgstr "用于导出指标和链路追踪数据的 OTLP gRPC 端点。"
+
+#: ../../source/mp/configuration.rst:456
+msgid "``--prometheus-port``"
+msgstr "``--prometheus-port``"
+
+#: ../../source/mp/configuration.rst:457
+msgid "``9090``"
+msgstr "``9090``"
+
+#: ../../source/mp/configuration.rst:458
+msgid "Port for the Prometheus ``/metrics`` endpoint."
+msgstr "Prometheus ``/metrics`` 端点的端口。"
+
+#: ../../source/mp/configuration.rst:461
+msgid "vLLM Client Configuration"
+msgstr "vLLM 客户端配置"
+
+#: ../../source/mp/configuration.rst:463
+msgid ""
+"On the vLLM side, specify the LMCache server host and port via the "
+"``kv_connector_extra_config`` parameter:"
+msgstr "在 vLLM 端，通过 ``kv_connector_extra_config`` 参数指定 LMCache 服务器的主机和端口："
+
+#: ../../source/mp/configuration.rst:472
+msgid ""
+"To target multiple LMCache servers from a single vLLM deployment, pass a "
+"list (or comma-separated string) of server URLs via "
+"``lmcache.mp.server_urls``. When set, ``server_urls`` takes precedence "
+"over the single-server ``host`` / ``port`` keys; vLLM's world size must "
+"be divisible by the number of servers, and each worker connects only to "
+"its locally-assigned server (global ranks are sliced into contiguous "
+"blocks, one block per server). Multi-server mode currently supports "
+"tensor parallelism only -- pipeline parallelism (``pp_size > 1``) and "
+"data parallelism (``dp_size > 1``) are rejected with a clear error."
+msgstr "要从单个 vLLM 部署目标多个 LMCache 服务器，通过 ``lmcache.mp.server_urls`` 传递服务器 URL 的列表（或以逗号分隔的字符串）。设置后，``server_urls`` 优先于单服务器的 ``host`` / ``port`` 键；vLLM 的世界大小必须能被服务器数量整除，每个工作节点仅连接到其本地分配的服务器（全局排名被切分为连续块，每个服务器一个块）。多服务器模式目前仅支持张量并行 -- 管道并行（``pp_size > 1``）和数据并行（``dp_size > 1``）会被明确拒绝并报错。"
+
+#: ../../source/mp/configuration.rst:489
+msgid ""
+"``LMCacheMPConnector`` reads the following keys from "
+"``kv_connector_extra_config``:"
+msgstr "``LMCacheMPConnector`` 从 ``kv_connector_extra_config`` 中读取以下键："
+
+#: ../../source/mp/configuration.rst:493
+msgid "Connector ``extra_config`` Keys"
+msgstr "连接器 ``extra_config`` 键"
+
+#: ../../source/mp/configuration.rst:495
+msgid ""
+"All connector-level options are passed through "
+"``kv_connector_extra_config`` and use the ``lmcache.mp.`` prefix."
+msgstr "所有连接器级别的选项都通过 ``kv_connector_extra_config`` 传递，并使用 ``lmcache.mp.`` 前缀。"
+
+#: ../../source/mp/configuration.rst:502
+msgid "Key"
+msgstr "键"
+
+#: ../../source/mp/configuration.rst:505
+msgid "``lmcache.mp.server_urls``"
+msgstr "``lmcache.mp.server_urls``"
+
+#: ../../source/mp/configuration.rst:506
+msgid "*(unset)*"
+msgstr "*(未设置)*"
+
+#: ../../source/mp/configuration.rst:507
+msgid ""
+"Multi-server deployment: list (or comma-separated string) of "
+"``<transport>://<host>:<port>`` URLs, e.g. "
+"``\"tcp://host1:6667,tcp://host2:6667\"``. When set, takes precedence "
+"over ``lmcache.mp.host`` / ``lmcache.mp.port``; the vLLM world size must "
+"be divisible by the number of servers, and each worker connects to its "
+"locally-assigned server."
+msgstr "多服务器部署：``<transport>://<host>:<port>`` URL 的列表（或以逗号分隔的字符串），例如 ``\"tcp://host1:6667,tcp://host2:6667\"``。设置后，优先于 ``lmcache.mp.host`` / ``lmcache.mp.port``；vLLM 世界大小必须能被服务器数量整除，每个工作节点连接到其本地分配的服务器。"
+
+#: ../../source/mp/configuration.rst:513
+msgid "``lmcache.mp.host``"
+msgstr "``lmcache.mp.host``"
+
+#: ../../source/mp/configuration.rst:514
+msgid "``tcp://localhost``"
+msgstr "``tcp://localhost``"
+
+#: ../../source/mp/configuration.rst:515
+msgid ""
+"Single-server deployment: host (with ZMQ transport prefix) of the LMCache"
+" MP server. Ignored when ``lmcache.mp.server_urls`` is set."
+msgstr "单服务器部署：LMCache MP 服务器的主机（带有 ZMQ 传输前缀）。当 ``lmcache.mp.server_urls`` 被设置时将被忽略。"
+
+#: ../../source/mp/configuration.rst:518
+msgid "``lmcache.mp.port``"
+msgstr "``lmcache.mp.port``"
+
+#: ../../source/mp/configuration.rst:520
+msgid ""
+"Single-server deployment: port of the LMCache MP server. Must match the "
+"server's ``--port``. Ignored when ``lmcache.mp.server_urls`` is set."
+msgstr "单服务器部署：LMCache MP 服务器的端口。必须与服务器的 ``--port`` 匹配。当设置了 ``lmcache.mp.server_urls`` 时将被忽略。"
+
+#: ../../source/mp/configuration.rst:523
+msgid "``lmcache.mp.mq_timeout``"
+msgstr "``lmcache.mp.mq_timeout``"
+
+#: ../../source/mp/configuration.rst:524
+msgid "``300.0``"
+msgstr "``300.0``"
+
+#: ../../source/mp/configuration.rst:525
+msgid ""
+"Timeout (seconds) for blocking message-queue requests, including the "
+"initial chunk-size query and KV cache registration/unregistration. If the"
+" server does not respond within this window, the connector raises "
+"``ConnectionError`` on startup."
+msgstr ""
+"阻塞消息队列请求的超时时间（秒），包括初始块大小查询和 KV Cache 注册/注销。如果服务器在此时间窗口内未响应，连接器将在启动时引发 "
+"``ConnectionError``\\ 。"
+
+#: ../../source/mp/configuration.rst:529
+msgid "``lmcache.mp.heartbeat_interval``"
+msgstr "``lmcache.mp.heartbeat_interval``"
+
+#: ../../source/mp/configuration.rst:530
+msgid "``10.0``"
+msgstr "``10.0``"
+
+#: ../../source/mp/configuration.rst:531
+msgid ""
+"Interval (seconds) between periodic heartbeat pings sent from the "
+"connector to the server."
+msgstr "连接器向服务器发送周期性心跳 PING 的时间间隔（秒）。"
+
+#: ../../source/mp/configuration.rst:533
+msgid "``lmcache.mp.mp_transfer_mode``"
+msgstr "``lmcache.mp.mp_transfer_mode``"
+
+#: ../../source/mp/configuration.rst:535
+msgid ""
+"Routing mode for the worker -> server transfer context. One of ``auto`` "
+"(CUDA -> lmcache_driven, others -> engine_driven), ``lmcache_driven`` "
+"(force the IPC / SHM zero-copy handle path — LMCache server pulls data "
+"via device handles), or ``engine_driven`` (force the worker-side "
+"gather/scatter copy path). Overrides the ``LMCACHE_MP_TRANSFER_MODE`` env"
+" var when set."
+msgstr "工作进程与服务器传输上下文的路由模式。可以是 ``auto``（CUDA -> lmcache_driven，其他 -> engine_driven）、``lmcache_driven``（强制使用 IPC / SHM 零拷贝句柄路径 — LMCache 服务器通过设备句柄拉取数据）或 ``engine_driven``（强制使用工作进程端的收集/分散拷贝路径）。当设置时，会覆盖 ``LMCACHE_MP_TRANSFER_MODE`` 环境变量。"
+
+#: ../../source/mp/configuration.rst:544
+msgid "Environment Variables"
+msgstr "环境变量"
+
+#: ../../source/mp/configuration.rst:550
+msgid "Variable"
+msgstr "变量"
+
+#: ../../source/mp/configuration.rst:552
+msgid "``LMCACHE_LOG_LEVEL``"
+msgstr "``LMCACHE_LOG_LEVEL``"
+
+#: ../../source/mp/configuration.rst:553
+msgid ""
+"Log level for LMCache (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``). Set "
+"to ``DEBUG`` to see L2 store activity, prefetch results, etc."
+msgstr ""
+"LMCache 的日志级别（\\ ``DEBUG``\\ 、\\ ``INFO``\\ 、\\ ``WARNING``\\ 、\\ "
+"``ERROR``\\ ）。设置为 ``DEBUG`` 以查看 L2 存储活动、预取结果等。"
+
+#: ../../source/mp/configuration.rst:555
+msgid "``PYTHONHASHSEED``"
+msgstr "``PYTHONHASHSEED``"
+
+#: ../../source/mp/configuration.rst:556
+msgid ""
+"Set to a fixed value for reproducible hashing across processes (relevant "
+"when using ``--hash-algorithm builtin``)."
+msgstr "设置为固定值以实现跨进程的可重复哈希（在使用 ``--hash-algorithm builtin`` 时相关）。"
+
+#: ../../source/mp/configuration.rst:560
+msgid "Full Example"
+msgstr "完整示例"
+
+#~ msgid ""
+#~ "Enable or disable lazy allocation for"
+#~ " L1 memory. Pass ``--l1-use-lazy`` to"
+#~ " enable (default) or ``--no-l1-use-lazy``"
+#~ " to explicitly disable."
+#~ msgstr ""
+#~ "启用或禁用 L1 内存的延迟分配。传递 ``--l1-use-lazy`` "
+#~ "以启用（默认）或 ``--no-l1-use-lazy`` 以显式禁用。"
+
+#~ msgid ""
+#~ "Cache engine backend type. ``default`` "
+#~ "uses MPCacheEngine; ``blend`` uses "
+#~ "BlendEngineV2 for cross-request KV "
+#~ "reuse. Choices: ``default``, ``blend``."
+#~ msgstr ""
+#~ "缓存引擎后端类型。``default`` 使用 MPCacheEngine；``blend`` 使用"
+#~ " BlendEngineV2 进行跨请求的 KV "
+#~ "重用。可选项：``default``，``blend``。"
+
+#~ msgid "Size of L1 memory in GB."
+#~ msgstr "L1 内存的大小（以 GB 为单位）。"
+
+#~ msgid "``nixl_store`` -- NIXL-based persistent storage"
+#~ msgstr "``nixl_store`` -- 基于 NIXL 的持久存储"
+
+#~ msgid ""
+#~ "``backend`` *(required)*: One of ``POSIX``,"
+#~ " ``GDS``, ``GDS_MT``, ``HF3FS``, ``OBJ``, "
+#~ "``AZURE_BLOB``."
+#~ msgstr ""
+#~ "``backend`` *(必需)*: 选项包括 ``POSIX``, ``GDS``,"
+#~ " ``GDS_MT``, ``HF3FS``, ``OBJ``, ``AZURE_BLOB``。"
+
+#~ msgid ""
+#~ "``backend_params`` *(required for file-based"
+#~ " backends)*: Dict of string key-value"
+#~ " pairs.  File-based backends (``GDS``, "
+#~ "``GDS_MT``, ``POSIX``, ``HF3FS``) require "
+#~ "``file_path`` and ``use_direct_io``."
+#~ msgstr ""
+#~ "``backend_params`` *(文件基础后端必需)*：字符串键值对的字典。文件基础后端（``GDS``, "
+#~ "``GDS_MT``, ``POSIX``, ``HF3FS``）需要 ``file_path``"
+#~ " 和 ``use_direct_io``。"
+
+#~ msgid ""
+#~ "``pool_size`` *(required)*: Number of storage"
+#~ " descriptors to pre-allocate (> 0)."
+#~ msgstr "``pool_size`` *(必需)*: 预分配的存储描述符数量 (> 0)。"
+
+#~ msgid "Examples:"
+#~ msgstr "示例："
+
+#~ msgid "``fs`` -- File-system backed storage"
+#~ msgstr "``fs`` -- 文件系统支持的存储"
+
+#~ msgid "A pure file-system L2 adapter using async I/O."
+#~ msgstr "一个使用异步 I/O 的纯文件系统 L2 适配器。"
+
+#~ msgid "``base_path`` *(required)*: Directory for storing KV cache files."
+#~ msgstr "``base_path`` *(必需)*: 存储 KV Cache 文件的目录。"
+
+#~ msgid "``relative_tmp_dir`` *(optional)*: Relative sub-dir for temp files."
+#~ msgstr "``relative_tmp_dir`` *(可选)*: 临时文件的相对子目录。"
+
+#~ msgid ""
+#~ "``read_ahead_size`` *(optional)*: Trigger read-"
+#~ "ahead by reading this many bytes "
+#~ "first."
+#~ msgstr "``read_ahead_size`` *(可选)*: 通过首先读取这么多字节来触发预读。"
+
+#~ msgid ""
+#~ "``use_odirect`` *(optional)*: Bypass page "
+#~ "cache via ``O_DIRECT`` (default ``false``)."
+#~ msgstr "``use_odirect`` *(可选)*：通过 ``O_DIRECT`` 跳过页面缓存（默认 ``false``）。"
+
+#~ msgid "``mock`` -- Mock adapter for testing"
+#~ msgstr "``mock`` -- 测试用的模拟适配器"
+
+#~ msgid "``max_size_gb`` *(required)*: Maximum size of the adapter in GB (> 0)."
+#~ msgstr "``max_size_gb`` *(必需)*：适配器的最大大小（以 GB 为单位，> 0）。"
+
+#~ msgid ""
+#~ "``mock_bandwidth_gb`` *(required)*: Simulated "
+#~ "bandwidth in GB/sec (> 0)."
+#~ msgstr "``mock_bandwidth_gb`` *(必需)*: 模拟带宽，单位为 GB/秒 (> 0)。"
+
+#~ msgid "``s3`` -- S3-compatible object store"
+#~ msgstr "``s3`` -- 兼容 S3 的对象存储"
+
+#~ msgid ""
+#~ "S3-backed L2 adapter using the AWS "
+#~ "CRT (Common Runtime) for high-throughput"
+#~ " transfers to AWS S3 or any "
+#~ "S3-compatible endpoint. See :doc:`l2_storage` "
+#~ "for details."
+#~ msgstr ""
+#~ "使用 AWS CRT（通用运行时）的 S3 后端 L2 "
+#~ "适配器，以实现高吞吐量传输到 AWS S3 或任何 S3 "
+#~ "兼容的端点。有关详细信息，请参见 :doc:`l2_storage`。"
+
+#~ msgid ""
+#~ "``s3_endpoint`` *(required)*: Bucket URL, "
+#~ "either ``\"s3://<bucket>\"`` or the bare "
+#~ "host form."
+#~ msgstr "``s3_endpoint`` *(必需)*: 存储桶 URL，可以是 ``\"s3://<bucket>\"`` 或裸主机形式。"
+
+#~ msgid "``s3_region`` *(required)*: AWS region string."
+#~ msgstr "``s3_region`` *(必需)*: AWS 区域字符串。"
+
+#~ msgid ""
+#~ "``s3_enable_s3express`` *(optional, default "
+#~ "``false``)*: Enable S3 Express signing."
+#~ msgstr "``s3_enable_s3express`` *(可选，默认 ``false``)*: 启用 S3 Express 签名。"
+
+#~ msgid ""
+#~ "``disable_tls`` *(optional, default ``false``)*: "
+#~ "Bypass TLS (for non-AWS HTTP "
+#~ "endpoints)."
+#~ msgstr "``disable_tls`` *(可选，默认 ``false``)*: 跳过 TLS（用于非 AWS HTTP 端点）。"
+
+#~ msgid ""
+#~ "``aws_access_key_id`` / ``aws_secret_access_key`` "
+#~ "*(optional)*: Static credentials; omit to "
+#~ "use the default credential provider "
+#~ "chain."
+#~ msgstr ""
+#~ "``aws_access_key_id`` / ``aws_secret_access_key`` "
+#~ "*(可选)*: 静态凭证；省略以使用默认凭证提供程序链。"
+
+#~ msgid ""
+#~ "Identifier for this MP server instance,"
+#~ " attached as the OTel Resource "
+#~ "attribute ``service.instance.id`` on every "
+#~ "metric and span. When the flag is"
+#~ " not passed, defaults to a random "
+#~ "UUID v4. Pass ``--service-instance-"
+#~ "id=\"\"`` to force an empty value."
+#~ msgstr ""
+#~ "此 MP 服务器实例的标识符，作为 OTel 资源属性 "
+#~ "``service.instance.id`` 附加在每个指标和跨度上。当未传递该标志时，默认为随机 UUID"
+#~ " v4。传递 ``--service-instance-id=\\\"\\\"`` "
+#~ "以强制设置为空值。"
+
+#~ msgid "``aerospike`` -- Aerospike native connector"
+#~ msgstr "``aerospike`` -- Aerospike 原生连接器"
+
+#~ msgid ""
+#~ "Native C++ Aerospike L2 adapter "
+#~ "(optional; build with ``BUILD_AEROSPIKE=1``). "
+#~ "See :doc:`l2_storage/index` for build "
+#~ "prerequisites and the full field list."
+#~ msgstr ""
+#~ "原生 C++ Aerospike L2 适配器（可选；使用 "
+#~ "``BUILD_AEROSPIKE=1`` 构建）。有关构建前提条件和完整字段列表，请参见 "
+#~ ":doc:`l2_storage/index`。"
+
+#~ msgid "Fields:"
+#~ msgstr "字段："
+
+#~ msgid "``hosts`` *(required)*: Seed hosts ``host:port[,host:port...]``."
+#~ msgstr "``hosts`` *(必需)*: 种子主机 ``host:port[,host:port...]``。"
+
+#~ msgid ""
+#~ "``namespace`` *(optional, default ``\"lmcache\"``)*:"
+#~ " Aerospike namespace."
+#~ msgstr "``namespace`` *(可选，默认 ``\"lmcache\"``)*: Aerospike 命名空间。"
+
+#~ msgid ""
+#~ "``set_name`` / ``set`` *(optional, default "
+#~ "``\"kv_chunks\"``)*: Aerospike set."
+#~ msgstr "``set_name`` / ``set`` *(可选，默认 ``\\\"kv_chunks\\\"``)*: Aerospike 集。"
+
+#~ msgid "``num_workers`` *(optional, default ``8``)*: C++ I/O worker threads."
+#~ msgstr "``num_workers`` *(可选，默认 ``8``)*: C++ I/O 工作线程。"
+
+#~ msgid ""
+#~ "``read_timeout_ms`` / ``write_timeout_ms`` "
+#~ "*(optional)*: Client timeouts."
+#~ msgstr "``read_timeout_ms`` / ``write_timeout_ms`` *(可选)*: 客户端超时。"
+
+#~ msgid ""
+#~ "``default_ttl_seconds`` *(optional, default "
+#~ "``86400``)*: Record TTL (``0`` = "
+#~ "namespace default)."
+#~ msgstr "``default_ttl_seconds`` *(可选，默认 ``86400``)*: 记录的 TTL (``0`` = 命名空间默认)。"
+
+#~ msgid ""
+#~ "``target_segment_bytes`` / ``max_record_bytes`` "
+#~ "*(optional, default ``0``)*: Shard target "
+#~ "and record-cap override (``0`` = "
+#~ "auto-discover)."
+#~ msgstr ""
+#~ "``target_segment_bytes`` / ``max_record_bytes`` "
+#~ "*(可选，默认 ``0``)*: 分片目标和记录容量覆盖 (``0`` = "
+#~ "自动发现)。"
+
+#~ msgid "``username`` / ``password`` *(optional)*: Enterprise Edition auth."
+#~ msgstr "``username`` / ``password`` *(可选)*: 企业版认证。"
+
+#~ msgid ""
+#~ "``max_capacity_gb`` *(optional, default ``0``)*: "
+#~ "L2 capacity for eviction (``0`` disables"
+#~ " tracking)."
+#~ msgstr "``max_capacity_gb`` *(可选，默认 ``0``)*: L2 逐出容量 (``0`` 禁用跟踪)。"
+
+#~ msgid "Example:"
+#~ msgstr "示例："
+
+#~ msgid ""
+#~ "Enable or disable lazy allocation for"
+#~ " L1 memory. Pass ``--l1-use-lazy`` to"
+#~ " enable (default) or ``--no-l1-use-lazy``"
+#~ " to explicitly disable. Lazy allocation "
+#~ "relies on ``cudart`` host-pinned memory,"
+#~ " so on non-CUDA backends (where "
+#~ "``lmcache.torch_dev`` exposes no ``cudart`` "
+#~ "attribute) it is automatically downgraded "
+#~ "to eager allocation with a logged "
+#~ "warning, regardless of the flag value."
+#~ msgstr ""
+#~ "启用或禁用 L1 内存的延迟分配。传递 ``--l1-use-lazy`` "
+#~ "以启用（默认），或传递 ``--no-l1-use-lazy`` 以显式禁用。延迟分配依赖于 "
+#~ "``cudart`` 主机固定内存，因此在非 CUDA 后端（\\ "
+#~ "``lmcache.torch_dev`` 未暴露 ``cudart`` "
+#~ "属性）下，无论标志取值如何，都会自动降级为立即分配并记录警告。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/coordinator.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/coordinator.po
new file mode 100644
index 0000000..f596c45
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/coordinator.po
@@ -0,0 +1,1180 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/coordinator.rst:2
+msgid "Multi-Server Coordination"
+msgstr "多服务器协调"
+
+#: ../../source/mp/coordinator.rst:4
+msgid ""
+"When you run more than one LMCache multiprocess (MP) server, the **MP "
+"Coordinator** is a standalone service they register with, giving you a "
+"single, fleet-wide view of every running server. Each MP server caches "
+"independently; the coordinator ties them together into one coordinated "
+"fleet."
+msgstr ""
+"当您运行多个 LMCache 多进程（MP）服务器时，\\ **MP 协调器**\\ "
+"是一个独立服务，各服务器向其注册，从而为您提供覆盖所有运行中服务器的单一全局视图。每个 MP "
+"服务器独立缓存；协调器将它们整合为一个统一管理的集群。"
+
+#: ../../source/mp/coordinator.rst:14
+msgid "Running the coordinator"
+msgstr "运行协调器"
+
+#: ../../source/mp/coordinator.rst:16
+msgid "The coordinator is a FastAPI service. Start it with:"
+msgstr "协调器是一个 FastAPI 服务。使用以下命令启动它："
+
+#: ../../source/mp/coordinator.rst:22
+msgid "Expected log output:"
+msgstr "预期的日志输出："
+
+#: ../../source/mp/coordinator.rst:28
+msgid ""
+"The CLI accepts ``--host``, ``--port``, ``--instance-timeout``, "
+"``--health-check-interval``, ``--eviction-check-interval``, ``--eviction-"
+"ratio``, ``--trigger-watermark``, ``--blend-chunk-size``, ``--blend-"
+"probe-stride``, and ``--timeout-keep-alive``; any flag overrides the "
+"matching environment variable below. See :doc:`/cli/coordinator` for "
+"details. Equivalently, the coordinator can still be launched as a module "
+"with ``python3 -m lmcache.v1.mp_coordinator``."
+msgstr ""
+"CLI 接受 ``--host``、``--port``、``--instance-timeout``、``--health-check-"
+"interval``、``--eviction-check-interval``、``--eviction-ratio"
+"``、``--trigger-watermark``、``--blend-chunk-size``、``--blend-probe-"
+"stride`` 和 ``--timeout-keep-alive``；任何标志都会覆盖下面匹配的环境变量。有关详细信息，请参见 "
+":doc:`/cli/coordinator`。同样，协调器仍然可以通过 ``python3 -m "
+"lmcache.v1.mp_coordinator`` 作为模块启动。"
+
+#: ../../source/mp/coordinator.rst:37
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/mp/coordinator.rst:39
+msgid ""
+"The coordinator is configured through ``LMCACHE_MP_COORDINATOR_*`` "
+"environment variables:"
+msgstr "协调器通过 ``LMCACHE_MP_COORDINATOR_*`` 环境变量进行配置："
+
+#: ../../source/mp/coordinator.rst:46
+msgid "Environment variable"
+msgstr "环境变量"
+
+#: ../../source/mp/coordinator.rst:47
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/coordinator.rst:48 ../../source/mp/coordinator.rst:125
+#: ../../source/mp/coordinator.rst:192 ../../source/mp/coordinator.rst:404
+#: ../../source/mp/coordinator.rst:544 ../../source/mp/coordinator.rst:627
+#: ../../source/mp/coordinator.rst:705
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/coordinator.rst:49
+msgid "``LMCACHE_MP_COORDINATOR_HOST``"
+msgstr "``LMCACHE_MP_COORDINATOR_HOST``"
+
+#: ../../source/mp/coordinator.rst:50
+msgid "``0.0.0.0``"
+msgstr "``0.0.0.0``"
+
+#: ../../source/mp/coordinator.rst:51
+msgid "Host the HTTP server binds to."
+msgstr "HTTP服务器绑定的主机。"
+
+#: ../../source/mp/coordinator.rst:52
+msgid "``LMCACHE_MP_COORDINATOR_PORT``"
+msgstr "``LMCACHE_MP_COORDINATOR_PORT``"
+
+#: ../../source/mp/coordinator.rst:53
+msgid "``9300``"
+msgstr "``9300``"
+
+#: ../../source/mp/coordinator.rst:54
+msgid "Port the HTTP server binds to."
+msgstr "HTTP服务器绑定的端口。"
+
+#: ../../source/mp/coordinator.rst:55
+msgid "``LMCACHE_MP_COORDINATOR_INSTANCE_TIMEOUT``"
+msgstr "``LMCACHE_MP_COORDINATOR_INSTANCE_TIMEOUT``"
+
+#: ../../source/mp/coordinator.rst:56
+msgid "``30``"
+msgstr "``30``"
+
+#: ../../source/mp/coordinator.rst:57
+msgid ""
+"Seconds without a heartbeat after which a server is dropped from the "
+"fleet."
+msgstr "超过此秒数未收到心跳后，服务器将从集群中移除。"
+
+#: ../../source/mp/coordinator.rst:59
+msgid "``LMCACHE_MP_COORDINATOR_HEALTH_CHECK_INTERVAL``"
+msgstr "``LMCACHE_MP_COORDINATOR_HEALTH_CHECK_INTERVAL``"
+
+#: ../../source/mp/coordinator.rst:60 ../../source/mp/coordinator.rst:81
+msgid "``10``"
+msgstr "``10``"
+
+#: ../../source/mp/coordinator.rst:61
+msgid "Seconds between health-check sweeps. ``0`` disables eviction."
+msgstr "健康检查扫描之间的秒数。\\ ``0`` 禁用逐出。"
+
+#: ../../source/mp/coordinator.rst:62
+msgid "``LMCACHE_MP_COORDINATOR_EVICTION_CHECK_INTERVAL``"
+msgstr "``LMCACHE_MP_COORDINATOR_EVICTION_CHECK_INTERVAL``"
+
+#: ../../source/mp/coordinator.rst:63
+msgid "``5``"
+msgstr "``5``"
+
+#: ../../source/mp/coordinator.rst:64
+msgid "Seconds between L2 eviction sweeps. ``0`` disables the loop."
+msgstr "L2 逐出清扫之间的秒数。\\ ``0`` 禁用循环。"
+
+#: ../../source/mp/coordinator.rst:65
+msgid "``LMCACHE_MP_COORDINATOR_EVICTION_RATIO``"
+msgstr "``LMCACHE_MP_COORDINATOR_EVICTION_RATIO``"
+
+#: ../../source/mp/coordinator.rst:66
+msgid "``0.2``"
+msgstr "``0.2``"
+
+#: ../../source/mp/coordinator.rst:67
+msgid "Fraction of tracked keys (by count) to evict per cycle (0.0 to 1.0)."
+msgstr "每个周期逐出的跟踪键的比例（按计数，范围为 0.0 到 1.0）。"
+
+#: ../../source/mp/coordinator.rst:68
+msgid "``LMCACHE_MP_COORDINATOR_TRIGGER_WATERMARK``"
+msgstr "``LMCACHE_MP_COORDINATOR_TRIGGER_WATERMARK``"
+
+#: ../../source/mp/coordinator.rst:69
+msgid "``1.0``"
+msgstr "``1.0``"
+
+#: ../../source/mp/coordinator.rst:70
+msgid ""
+"Eviction fires when usage reaches this fraction of the quota (0.0 "
+"exclusive to 1.0)."
+msgstr "当使用量达到配额的该比例时触发逐出（取值范围为 (0.0, 1.0]，不含 0.0）。"
+
+#: ../../source/mp/coordinator.rst:72
+msgid "``LMCACHE_MP_COORDINATOR_BLEND_CHUNK_SIZE``"
+msgstr "``LMCACHE_MP_COORDINATOR_BLEND_CHUNK_SIZE``"
+
+#: ../../source/mp/coordinator.rst:73
+msgid "``256``"
+msgstr "``256``"
+
+#: ../../source/mp/coordinator.rst:74
+msgid ""
+"Tokens per chunk for the global CacheBlend directory. Must equal the "
+"LMCache chunk size the blend servers use."
+msgstr "全局 CacheBlend 目录每块的令牌数。必须等于混合服务器使用的 LMCache 块大小。"
+
+#: ../../source/mp/coordinator.rst:76
+msgid "``LMCACHE_MP_COORDINATOR_BLEND_PROBE_STRIDE``"
+msgstr "``LMCACHE_MP_COORDINATOR_BLEND_PROBE_STRIDE``"
+
+#: ../../source/mp/coordinator.rst:77 ../../source/mp/coordinator.rst:95
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/mp/coordinator.rst:78
+msgid ""
+"Positions between CacheBlend match probes. ``1`` probes every offset for "
+"full recall."
+msgstr "在 CacheBlend 匹配探针之间的位置。``1`` 在每个偏移量进行探测以实现完全回忆。"
+
+#: ../../source/mp/coordinator.rst:80
+msgid "``LMCACHE_MP_COORDINATOR_TIMEOUT_KEEP_ALIVE``"
+msgstr "``LMCACHE_MP_COORDINATOR_TIMEOUT_KEEP_ALIVE``"
+
+#: ../../source/mp/coordinator.rst:82
+msgid ""
+"Seconds the HTTP server keeps idle connections open before closing them. "
+"Must be greater than the MP servers' heartbeat interval (default ``5``), "
+"otherwise heartbeat requests may hit a closing connection and fail with "
+"``Server disconnected without sending a response``."
+msgstr ""
+"HTTP 服务器在关闭空闲连接之前保持打开的秒数。必须大于 MP 服务器的心跳间隔（默认 "
+"``5``），否则心跳请求可能会遇到关闭的连接并失败，出现 ``服务器在未发送响应的情况下断开连接``。"
+
+#: ../../source/mp/coordinator.rst:87
+msgid "``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC``"
+msgstr "``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC``"
+
+#: ../../source/mp/coordinator.rst:88
+msgid "``True``"
+msgstr "``True``"
+
+#: ../../source/mp/coordinator.rst:89
+msgid ""
+"When ``True``, the coordinator runs a one-shot L2 resync on startup that "
+"paginates an MP server's ``GET /cache/objects`` and backfills usage + "
+"eviction trackers from existing L2 contents. Disable to start from empty "
+"trackers (handy for tests, or deployments that start the coordinator "
+"before any MP server)."
+msgstr "当设置为 ``True`` 时，协调器在启动时会执行一次 L2 重新同步，分页 MP 服务器的 ``GET /cache/objects`` 并从现有的 L2 内容中填充使用情况和逐出跟踪器。禁用此选项可以从空跟踪器开始（适用于测试或在任何 MP 服务器之前启动协调器的部署）。"
+
+#: ../../source/mp/coordinator.rst:94
+msgid "``LMCACHE_MP_COORDINATOR_RESYNC_POLL_INTERVAL``"
+msgstr "``LMCACHE_MP_COORDINATOR_RESYNC_POLL_INTERVAL``"
+
+#: ../../source/mp/coordinator.rst:96
+msgid ""
+"Seconds between registry checks while waiting for the first MP server to "
+"register so startup resync can begin."
+msgstr "在等待第一个 MP 服务器注册以便启动重新同步可以开始时，注册检查之间的秒数。"
+
+#: ../../source/mp/coordinator.rst:98
+msgid "``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT``"
+msgstr "``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT``"
+
+#: ../../source/mp/coordinator.rst:99
+msgid "``60``"
+msgstr "``60``"
+
+#: ../../source/mp/coordinator.rst:100
+msgid ""
+"Maximum seconds startup resync waits for an MP server before giving up. "
+"The coordinator keeps running with empty trackers until normal usage "
+"events fill them in."
+msgstr "最大秒数启动重新同步等待 MP 服务器在放弃之前。协调器保持运行，使用空的跟踪器，直到正常使用事件填充它们。"
+
+#: ../../source/mp/coordinator.rst:103
+msgid "``LMCACHE_MP_COORDINATOR_RESYNC_PAGE_SIZE``"
+msgstr "``LMCACHE_MP_COORDINATOR_RESYNC_PAGE_SIZE``"
+
+#: ../../source/mp/coordinator.rst:104
+msgid "``1000``"
+msgstr "``1000``"
+
+#: ../../source/mp/coordinator.rst:105
+msgid ""
+"``page_size`` forwarded to the MP server's ``GET /cache/objects`` during "
+"resync. Larger values reduce RTT count; the server clamps to its own "
+"ceiling."
+msgstr "``page_size`` 在重新同步期间转发到 MP 服务器的 ``GET /cache/objects``。较大的值会减少 RTT 计数；服务器会限制在其自身的上限。"
+
+#: ../../source/mp/coordinator.rst:110
+msgid "Connecting MP servers"
+msgstr "连接 MP 服务器"
+
+#: ../../source/mp/coordinator.rst:112
+msgid ""
+"An MP server (``lmcache server``) joins the coordinator when you point it"
+" at one with ``--coordinator-url``. It registers on startup, heartbeats "
+"while running, and deregisters on shutdown -- all on the server's own "
+"event loop. This is opt-in: with no URL set, the server runs exactly as "
+"before. Each flag falls back to a matching ``LMCACHE_COORDINATOR_*`` "
+"environment variable (handy for the Kubernetes downward API); an explicit"
+" flag wins over the env var."
+msgstr ""
+"当您通过 ``--coordinator-url`` 为 MP 服务器（\\ ``lmcache server``\\ "
+"）指定协调器地址时，该服务器便会加入协调器。它在启动时注册、运行时持续发送心跳、关闭时注销——所有操作均在服务器自身的事件循环中完成。此功能为可选项：若未设置"
+" URL，服务器的行为与之前完全相同。每个标志均可回退到对应的 ``LMCACHE_COORDINATOR_*`` 环境变量（在使用 "
+"Kubernetes Downward API 时非常便捷）；显式标志优先于环境变量。"
+
+#: ../../source/mp/coordinator.rst:123
+msgid "Flag (on the MP server)"
+msgstr "标志（在 MP 服务器上）"
+
+#: ../../source/mp/coordinator.rst:124
+msgid "Env fallback"
+msgstr "环境回退"
+
+#: ../../source/mp/coordinator.rst:126
+msgid "``--coordinator-url``"
+msgstr "``--coordinator-url``"
+
+#: ../../source/mp/coordinator.rst:127
+msgid "``LMCACHE_COORDINATOR_URL``"
+msgstr "``LMCACHE_COORDINATOR_URL``"
+
+#: ../../source/mp/coordinator.rst:128
+msgid ""
+"Coordinator base URL, e.g. ``http://coordinator:9300``. Enables "
+"registration when set."
+msgstr "协调器基础 URL，例如 ``http://coordinator:9300``\\ 。设置后启用注册。"
+
+#: ../../source/mp/coordinator.rst:130
+msgid "``--coordinator-advertise-ip``"
+msgstr "``--coordinator-advertise-ip``"
+
+#: ../../source/mp/coordinator.rst:131
+msgid "``LMCACHE_COORDINATOR_ADVERTISE_IP``"
+msgstr "``LMCACHE_COORDINATOR_ADVERTISE_IP``"
+
+#: ../../source/mp/coordinator.rst:132
+msgid ""
+"IP the coordinator should reach this server at (defaults to the server's "
+"outbound IP)."
+msgstr "协调器应通过此服务器访问的 IP（默认为服务器的外部 IP）。"
+
+#: ../../source/mp/coordinator.rst:134
+msgid "``--coordinator-heartbeat-interval``"
+msgstr "``--coordinator-heartbeat-interval``"
+
+#: ../../source/mp/coordinator.rst:135
+msgid "``LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL``"
+msgstr "``LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL``"
+
+#: ../../source/mp/coordinator.rst:136
+msgid ""
+"Seconds between heartbeats (must be ``> 0``, default ``5``). Keep it well"
+" below the coordinator's ``INSTANCE_TIMEOUT``."
+msgstr "心跳之间的秒数（必须为 ``> 0``\\ ，默认值为 ``5``\\ ）。保持远低于协调器的 ``INSTANCE_TIMEOUT``\\ 。"
+
+#: ../../source/mp/coordinator.rst:138
+msgid "``--coordinator-l2-event-reporting``"
+msgstr "``--coordinator-l2-event-reporting``"
+
+#: ../../source/mp/coordinator.rst:139
+msgid "``LMCACHE_COORDINATOR_L2_EVENT_REPORTING``"
+msgstr "``LMCACHE_COORDINATOR_L2_EVENT_REPORTING``"
+
+#: ../../source/mp/coordinator.rst:140
+msgid ""
+"Enable reporting L2 store/lookup events to the coordinator for fleet-wide"
+" usage tracking and quota-based eviction."
+msgstr "启用向协调器上报 L2 存储/查找事件，用于全集群使用量跟踪及基于配额的逐出。"
+
+#: ../../source/mp/coordinator.rst:142
+msgid "``--coordinator-l2-event-flush-interval``"
+msgstr "``--coordinator-l2-event-flush-interval``"
+
+#: ../../source/mp/coordinator.rst:143
+msgid "``LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL``"
+msgstr "``LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL``"
+
+#: ../../source/mp/coordinator.rst:144
+msgid "Seconds between L2 event batch flushes (must be ``> 0``, default ``1``)."
+msgstr "L2 事件批量刷新之间的秒数（必须为 ``> 0``\\ ，默认值为 ``1``\\ ）。"
+
+#: ../../source/mp/coordinator.rst:146
+msgid ""
+"The server registers under its stable identity (``--instance-id`` / OTel "
+"``service.instance.id``); if the flag is not passed, the server mints a "
+"random UUID v4 at startup and registers under that."
+msgstr ""
+"服务器在其稳定身份下注册（\\ ``--instance-id`` / OTel ``service.instance.id``\\ "
+"）；如果未传递该标志，服务器将在启动时生成一个随机的 UUID v4 并在该 UUID 下注册。"
+
+#: ../../source/mp/coordinator.rst:150
+msgid ""
+"Registration is best-effort: if the coordinator is unreachable, the MP "
+"server logs a warning, keeps retrying, and continues serving. A malformed"
+" heartbeat-interval value is rejected at startup."
+msgstr "注册是尽力而为的：如果协调器无法访问，MP 服务器会记录警告，持续重试，并继续提供服务。启动时会拒绝格式错误的心跳间隔值。"
+
+#: ../../source/mp/coordinator.rst:155
+msgid "HTTP endpoints"
+msgstr "HTTP 端点"
+
+#: ../../source/mp/coordinator.rst:157
+msgid ""
+"The coordinator's HTTP surface (base URL ``http://localhost:9300``) "
+"groups into:"
+msgstr "协调器的 HTTP 接口（基础 URL ``http://localhost:9300``）分为："
+
+#: ../../source/mp/coordinator.rst:159
+msgid ""
+"**Fleet membership and health** -- registration and liveness "
+"(``/instances``, ``/healthz``)."
+msgstr "**车队成员资格和健康** -- 注册和存活 (``/instances``, ``/healthz``)。"
+
+#: ../../source/mp/coordinator.rst:161
+msgid ""
+"**Quota, usage, and eviction** -- the ``/quota`` group: per-tenant byte "
+"budgets, usage accounting, and the usage-event ingest that drives fleet-"
+"wide eviction."
+msgstr "**配额、使用情况和逐出** -- ``/quota`` 组：每个租户的字节预算、使用情况核算，以及驱动全队逐出的使用事件摄取。"
+
+#: ../../source/mp/coordinator.rst:164
+msgid ""
+"**Cache control** -- the ``/cache`` group: cache operations dispatched to"
+" a named server (currently warm prefetch, with more to come)."
+msgstr "**缓存控制** -- ``/cache`` 组：分派给命名服务器的缓存操作（目前是热预取，未来会有更多功能）。"
+
+#: ../../source/mp/coordinator.rst:167
+#, python-brace-format
+msgid ""
+"Each endpoint is documented below. Success is ``200`` unless noted, and "
+"``{cache_salt}`` uses the ``_default`` sentinel for the empty salt. The "
+"wire types live in ``lmcache/v1/mp_coordinator/schemas.py``."
+msgstr "每个端点的文档如下。成功状态为 ``200``，除非另有说明，``{cache_salt}`` 使用 ``_default`` 哨兵表示空盐。数据类型位于 ``lmcache/v1/mp_coordinator/schemas.py``。"
+
+#: ../../source/mp/coordinator.rst:172
+msgid "Fleet membership and health"
+msgstr "车队成员资格和健康状态"
+
+#: ../../source/mp/coordinator.rst:174
+msgid ""
+"MP servers register, heartbeat, and deregister automatically (see "
+"`Connecting MP servers`_); ``GET /instances`` and ``GET /healthz`` are "
+"read-only operator views."
+msgstr "MP 服务器自动注册、心跳和注销（参见 `Connecting MP servers`_）；``GET /instances`` 和 ``GET /healthz`` 是只读的操作员视图。"
+
+#: ../../source/mp/coordinator.rst:179
+msgid "``POST /instances``"
+msgstr "``POST /instances``"
+
+#: ../../source/mp/coordinator.rst:181
+msgid ""
+"Register (or re-register) an MP server. Called automatically by each "
+"server on startup."
+msgstr "注册（或重新注册）一个 MP 服务器。每个服务器在启动时会自动调用。"
+
+#: ../../source/mp/coordinator.rst:184 ../../source/mp/coordinator.rst:396
+#: ../../source/mp/coordinator.rst:536 ../../source/mp/coordinator.rst:619
+msgid "**Request body:**"
+msgstr "**请求体：**"
+
+#: ../../source/mp/coordinator.rst:190 ../../source/mp/coordinator.rst:402
+#: ../../source/mp/coordinator.rst:542 ../../source/mp/coordinator.rst:625
+#: ../../source/mp/coordinator.rst:703
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/mp/coordinator.rst:191 ../../source/mp/coordinator.rst:403
+#: ../../source/mp/coordinator.rst:543 ../../source/mp/coordinator.rst:626
+#: ../../source/mp/coordinator.rst:704
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/mp/coordinator.rst:193
+msgid "``ip``"
+msgstr "``ip``"
+
+#: ../../source/mp/coordinator.rst:194 ../../source/mp/coordinator.rst:201
+#: ../../source/mp/coordinator.rst:208 ../../source/mp/coordinator.rst:410
+#: ../../source/mp/coordinator.rst:546 ../../source/mp/coordinator.rst:553
+#: ../../source/mp/coordinator.rst:629 ../../source/mp/coordinator.rst:632
+#: ../../source/mp/coordinator.rst:644 ../../source/mp/coordinator.rst:707
+#: ../../source/mp/coordinator.rst:710
+msgid "string"
+msgstr "字符串"
+
+#: ../../source/mp/coordinator.rst:195
+msgid ""
+"IP/host of the server's HTTP API; the coordinator dials this address, so "
+"it must be non-empty."
+msgstr "服务器 HTTP API 的 IP/主机地址；协调器拨打此地址，因此必须非空。"
+
+#: ../../source/mp/coordinator.rst:197
+msgid "``http_port``"
+msgstr "``http_port``"
+
+#: ../../source/mp/coordinator.rst:198 ../../source/mp/coordinator.rst:212
+#: ../../source/mp/coordinator.rst:549 ../../source/mp/coordinator.rst:635
+msgid "int"
+msgstr "整数"
+
+#: ../../source/mp/coordinator.rst:199
+msgid "Port of the server's HTTP API."
+msgstr "服务器 HTTP API 的端口。"
+
+#: ../../source/mp/coordinator.rst:200 ../../source/mp/coordinator.rst:545
+#: ../../source/mp/coordinator.rst:628 ../../source/mp/coordinator.rst:706
+msgid "``instance_id``"
+msgstr "``instance_id``"
+
+#: ../../source/mp/coordinator.rst:202
+msgid ""
+"Optional. Server identifier; if omitted (or blank) the coordinator "
+"generates one and returns it."
+msgstr "可选。服务器标识符；如果省略（或留空），协调器将生成一个并返回。"
+
+#: ../../source/mp/coordinator.rst:204
+msgid "``metadata``"
+msgstr "``metadata``"
+
+#: ../../source/mp/coordinator.rst:205
+msgid "object"
+msgstr "对象"
+
+#: ../../source/mp/coordinator.rst:206
+msgid "Optional. Free-form ``string -> string`` registration hints."
+msgstr "可选。自由格式的 ``string -> string`` 注册提示。"
+
+#: ../../source/mp/coordinator.rst:207
+msgid "``p2p_advertised_url``"
+msgstr "``p2p_advertised_url``"
+
+#: ../../source/mp/coordinator.rst:209
+msgid ""
+"Optional. URL the server advertises for peer-to-peer transfers; empty "
+"when it is not in P2P."
+msgstr "可选。服务器为点对点传输宣传的 URL；在不处于 P2P 时为空。"
+
+#: ../../source/mp/coordinator.rst:211
+msgid "``mq_port``"
+msgstr "``mq_port``"
+
+#: ../../source/mp/coordinator.rst:213
+msgid ""
+"Optional (default ``0``). ZMQ message-queue port P2P peers send "
+"lookup/unlock RPCs to; ``0`` when P2P is disabled."
+msgstr "可选（默认 ``0``）。ZMQ 消息队列端口，P2P 对等体发送查找/解锁 RPC 的端口；当 P2P 被禁用时为 ``0``。"
+
+#: ../../source/mp/coordinator.rst:216 ../../source/mp/coordinator.rst:247
+#: ../../source/mp/coordinator.rst:292 ../../source/mp/coordinator.rst:330
+#: ../../source/mp/coordinator.rst:414 ../../source/mp/coordinator.rst:447
+#: ../../source/mp/coordinator.rst:477 ../../source/mp/coordinator.rst:505
+#: ../../source/mp/coordinator.rst:563 ../../source/mp/coordinator.rst:648
+msgid "**Response** (``200 OK``):"
+msgstr "**响应** (``200 OK``):"
+
+#: ../../source/mp/coordinator.rst:222
+msgid ""
+"``instance_id`` is the registered id (the generated one when the request "
+"omitted it); ``re_registered`` is ``true`` when this replaced an existing"
+" registration."
+msgstr "``instance_id`` 是注册的 ID（当请求省略时生成的 ID）；``re_registered`` 在替换现有注册时为 ``true``。"
+
+#: ../../source/mp/coordinator.rst:225 ../../source/mp/coordinator.rst:253
+#: ../../source/mp/coordinator.rst:276 ../../source/mp/coordinator.rst:315
+#: ../../source/mp/coordinator.rst:336 ../../source/mp/coordinator.rst:420
+#: ../../source/mp/coordinator.rst:456 ../../source/mp/coordinator.rst:487
+#: ../../source/mp/coordinator.rst:519 ../../source/mp/coordinator.rst:571
+#: ../../source/mp/coordinator.rst:664 ../../source/mp/coordinator.rst:727
+msgid "**HTTP status codes:**"
+msgstr "**HTTP 状态码:**"
+
+#: ../../source/mp/coordinator.rst:227
+msgid "``200``: registered."
+msgstr "``200``: 已注册。"
+
+#: ../../source/mp/coordinator.rst:228
+msgid ""
+"``422``: request body fails field-level validation (e.g. blank ``ip`` or "
+"out-of-range ``http_port``)."
+msgstr "``422``: 请求体未通过字段级验证（例如，空白的 ``ip`` 或超出范围的 ``http_port``）。"
+
+#: ../../source/mp/coordinator.rst:231 ../../source/mp/coordinator.rst:259
+#: ../../source/mp/coordinator.rst:280 ../../source/mp/coordinator.rst:319
+#: ../../source/mp/coordinator.rst:340 ../../source/mp/coordinator.rst:426
+#: ../../source/mp/coordinator.rst:460 ../../source/mp/coordinator.rst:491
+#: ../../source/mp/coordinator.rst:523 ../../source/mp/coordinator.rst:576
+#: ../../source/mp/coordinator.rst:676 ../../source/mp/coordinator.rst:734
+msgid "**Example:**"
+msgstr "**示例：**"
+
+#: ../../source/mp/coordinator.rst:241
+#, python-brace-format
+msgid "``PUT /instances/{instance_id}/heartbeat``"
+msgstr "``PUT /instances/{instance_id}/heartbeat``"
+
+#: ../../source/mp/coordinator.rst:243
+msgid "Record a liveness heartbeat. Called automatically while the server runs."
+msgstr "记录存活心跳。在服务器运行时自动调用。"
+
+#: ../../source/mp/coordinator.rst:245
+msgid ""
+"**Path parameters:** ``instance_id`` — the instance recording the "
+"heartbeat."
+msgstr "**路径参数:** ``instance_id`` — 记录心跳的实例。"
+
+#: ../../source/mp/coordinator.rst:255
+msgid "``200``: heartbeat recorded."
+msgstr "``200``: 心跳已记录。"
+
+#: ../../source/mp/coordinator.rst:256
+msgid ""
+"``404``: unknown instance — the caller should re-register via ``POST "
+"/instances``."
+msgstr "``404``: 未知实例 — 调用者应通过 ``POST /instances`` 重新注册。"
+
+#: ../../source/mp/coordinator.rst:267
+#, python-brace-format
+msgid "``DELETE /instances/{instance_id}``"
+msgstr "``DELETE /instances/{instance_id}``"
+
+#: ../../source/mp/coordinator.rst:269
+msgid "Deregister an MP server. Called automatically on shutdown."
+msgstr "注销一个 MP 服务器。在关闭时自动调用。"
+
+#: ../../source/mp/coordinator.rst:271
+msgid "**Path parameters:** ``instance_id`` — the server to deregister."
+msgstr "**路径参数:** ``instance_id`` — 要注销的服务器。"
+
+#: ../../source/mp/coordinator.rst:273
+msgid ""
+"**Response:** ``204 No Content`` with an empty body, returned whether or "
+"not the instance was registered (idempotent)."
+msgstr "**响应:** ``204 No Content``，返回一个空主体，无论实例是否已注册（幂等）。"
+
+#: ../../source/mp/coordinator.rst:278
+msgid "``204``: deregistered (also returned for an unknown instance)."
+msgstr "``204``: 已注销（对于未知实例也会返回此状态）。"
+
+#: ../../source/mp/coordinator.rst:288
+msgid "``GET /instances``"
+msgstr "``GET /instances``"
+
+#: ../../source/mp/coordinator.rst:290
+msgid "List every registered MP server."
+msgstr "列出每个注册的 MP 服务器。"
+
+#: ../../source/mp/coordinator.rst:310
+msgid ""
+"Each entry reports the server's ``instance_id``, the ``ip`` / "
+"``http_port`` the coordinator reaches it at, the wall-clock "
+"``registration_time`` (epoch seconds), any ``metadata`` supplied at "
+"registration, and the ``p2p_advertised_url`` / ``mq_port`` used for peer-"
+"to-peer transfers (empty / ``0`` when P2P is disabled)."
+msgstr "每个条目报告服务器的 ``instance_id``、协调器访问的 ``ip`` / ``http_port``、墙钟 ``registration_time``（纪元秒）、注册时提供的任何 ``metadata``，以及用于点对点传输的 ``p2p_advertised_url`` / ``mq_port``（当 P2P 被禁用时为空 / ``0``）。"
+
+#: ../../source/mp/coordinator.rst:317
+#, python-brace-format
+msgid "``200``: fleet listed (an empty fleet returns ``{\"instances\": []}``)."
+msgstr "``200``: 已列出舰队（空舰队返回 ``{\\\"instances\\\": []}``）。"
+
+#: ../../source/mp/coordinator.rst:326
+msgid "``GET /healthz``"
+msgstr "``GET /healthz``"
+
+#: ../../source/mp/coordinator.rst:328
+msgid "Coordinator liveness probe (for Kubernetes)."
+msgstr "协调器存活探测（用于 Kubernetes）。"
+
+#: ../../source/mp/coordinator.rst:338
+msgid "``200``: the coordinator is up."
+msgstr "``200``: 协调器正常运行。"
+
+#: ../../source/mp/coordinator.rst:348
+msgid "Quota, usage, and eviction"
+msgstr "配额、使用情况和逐出"
+
+#: ../../source/mp/coordinator.rst:350
+msgid ""
+"The ``/quota`` group owns per-``cache_salt`` byte budgets, the live usage"
+" accounting behind them, and the usage-event stream that drives fleet-"
+"wide eviction. (The MP server exposes a node-local ``/quota`` with the "
+"same shape; this is its fleet-wide counterpart.) Salts without a quota "
+"default to a 0-byte limit (allowlist semantics); use ``_default`` as the "
+"path parameter to target the empty-string salt."
+msgstr "``/quota`` 组拥有每个 ``cache_salt`` 的字节预算、其背后的实时使用情况核算，以及驱动全队逐出的使用事件流。（MP 服务器暴露一个节点本地的 ``/quota``，其形状相同；这是其全队的对应项。）没有配额的盐默认限制为 0 字节（白名单语义）；使用 ``_default`` 作为路径参数以针对空字符串盐。"
+
+#: ../../source/mp/coordinator.rst:357
+msgid ""
+"When MP servers enable ``--coordinator-l2-event-reporting``, they stream "
+"L2 ``store``, ``lookup``, and ``delete`` events to the coordinator, which"
+" aggregates per-``cache_salt`` usage, enforces quotas, and selects LRU "
+"keys to evict. Each batch carries the server's ``instance_id`` and a "
+"monotonically increasing sequence number (``seq``) scoped to that "
+"instance, enabling future gap detection."
+msgstr "当 MP 服务器启用 ``--coordinator-l2-event-reporting`` 时，它们将 L2 ``store``、``lookup`` 和 ``delete`` 事件流式传输到协调器，协调器汇总每个 ``cache_salt`` 的使用情况，强制执行配额，并选择 LRU 键进行逐出。每个批次携带服务器的 ``instance_id`` 和一个单调递增的序列号 (``seq``)，该序列号作用于该实例，从而实现未来的间隙检测。"
+
+#: ../../source/mp/coordinator.rst:363
+msgid ""
+"**Active eviction loop.** Every "
+"``LMCACHE_MP_COORDINATOR_EVICTION_CHECK_INTERVAL`` seconds, the "
+"coordinator inspects per-salt usage against the registered quotas and, "
+"for any salt over the trigger watermark, picks LRU victims and dispatches"
+" a single ``DELETE /cache/objects`` to a uniformly random registered MP "
+"server. Because all MP servers share the same backing L2 (e.g. one S3 "
+"bucket), one dispatch evicts the keys for the whole fleet. The MP "
+"server's L2 adapter fires ``on_l2_keys_deleted`` listeners after the "
+"delete completes; those listeners ship ``delete`` events back through "
+"``POST /quota/events``, which is what updates the coordinator's LRU + "
+"per-salt totals. Dispatch failures or no-instances-registered fall "
+"through to the next cycle — at-least-once semantics, safe because the S3 "
+"delete is idempotent."
+msgstr "**主动逐出循环。** 每 ``LMCACHE_MP_COORDINATOR_EVICTION_CHECK_INTERVAL`` 秒，协调器检查每个盐的使用情况与注册的配额，并对任何超过触发水位线的盐选择 LRU 牺牲品，并向一个均匀随机的注册 MP 服务器发送单个 ``DELETE /cache/objects``。由于所有 MP 服务器共享相同的后端 L2（例如，一个 S3 存储桶），一次调度会逐出整个集群的键。MP 服务器的 L2 适配器在删除完成后触发 ``on_l2_keys_deleted`` 监听器；这些监听器通过 ``POST /quota/events`` 发送 ``delete`` 事件，这就是更新协调器的 LRU + 每盐总数的方式。调度失败或没有注册实例将进入下一个周期——至少一次语义，安全，因为 S3 删除是幂等的。"
+
+#: ../../source/mp/coordinator.rst:377
+msgid ""
+"**Startup resync.** On boot, the coordinator waits up to "
+"``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT`` seconds for the first MP "
+"server to register, then paginates its ``GET /cache/objects`` and seeds "
+"the in-memory usage + eviction trackers with whatever is already resident"
+" in L2 — so a fresh coordinator does not start from zero usage. Set "
+"``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC=False`` to skip this "
+"phase. Best-effort: resync failures are logged and the manager gives up; "
+"the ongoing usage-event stream from MP servers eventually corrects any "
+"initial blind spots."
+msgstr "**启动重新同步。** 在启动时，协调器最多等待 ``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT`` 秒以注册第一个 MP 服务器，然后对其 ``GET /cache/objects`` 进行分页，并用 L2 中已经存在的内容填充内存中的使用情况和逐出跟踪器——因此一个新的协调器不会从零使用开始。设置 ``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC=False`` 以跳过此阶段。尽力而为：重新同步失败会被记录，管理器会放弃；来自 MP 服务器的持续使用事件流最终会纠正任何初始盲点。"
+
+#: ../../source/mp/coordinator.rst:389
+#, python-brace-format
+msgid "``PUT /quota/{cache_salt}``"
+msgstr "``PUT /quota/{cache_salt}``"
+
+#: ../../source/mp/coordinator.rst:391
+msgid "Create or update a tenant's byte budget."
+msgstr "创建或更新租户的字节预算。"
+
+#: ../../source/mp/coordinator.rst:393 ../../source/mp/coordinator.rst:441
+#: ../../source/mp/coordinator.rst:472
+msgid ""
+"**Path parameters:** ``cache_salt`` — tenant identifier (``_default`` for"
+" the empty salt)."
+msgstr "**路径参数:** ``cache_salt`` — 租户标识符 (``_default`` 表示空盐)。"
+
+#: ../../source/mp/coordinator.rst:405
+msgid "``limit_gb``"
+msgstr "``limit_gb``"
+
+#: ../../source/mp/coordinator.rst:406
+msgid "float"
+msgstr "浮点数"
+
+#: ../../source/mp/coordinator.rst:407
+msgid ""
+"Byte budget in GiB; must be ``>= 0`` (``0`` clears the tenant's data on "
+"the next eviction cycle)."
+msgstr "以 GiB 为单位的字节预算；必须为 ``>= 0``（``0`` 会在下一个逐出周期清除租户的数据）。"
+
+#: ../../source/mp/coordinator.rst:409 ../../source/mp/coordinator.rst:552
+msgid "``tier``"
+msgstr "``tier``"
+
+#: ../../source/mp/coordinator.rst:411
+msgid ""
+"Optional (default ``l2``). Cache tier the quota applies to; only ``l2`` "
+"is supported today."
+msgstr "可选（默认 ``l2``）。配额适用的缓存层级；目前仅支持 ``l2``。"
+
+#: ../../source/mp/coordinator.rst:422
+msgid "``200``: quota applied."
+msgstr "``200``: 已应用配额。"
+
+#: ../../source/mp/coordinator.rst:423
+msgid "``400``: invalid limit (negative or non-finite)."
+msgstr "``400``: 无效的限制（负值或非有限值）。"
+
+#: ../../source/mp/coordinator.rst:424 ../../source/mp/coordinator.rst:574
+#: ../../source/mp/coordinator.rst:669
+msgid "``422``: request body fails field-level validation."
+msgstr "``422``: 请求体未通过字段级验证。"
+
+#: ../../source/mp/coordinator.rst:436
+#, python-brace-format
+msgid "``DELETE /quota/{cache_salt}``"
+msgstr "``DELETE /quota/{cache_salt}``"
+
+#: ../../source/mp/coordinator.rst:438
+msgid ""
+"Remove a salt's quota entry. Any bytes still cached under it become over-"
+"budget on the next eviction cycle (effective limit drops to ``0``)."
+msgstr "删除盐的配额条目。任何仍然缓存的字节将在下一个逐出周期变为超出预算（有效限制降至 ``0``）。"
+
+#: ../../source/mp/coordinator.rst:444
+msgid ""
+"**Query parameters:** ``tier`` — optional (default ``l2``); cache tier "
+"the quota applies to."
+msgstr "**查询参数:** ``tier`` — 可选（默认 ``l2``）；配额适用的缓存层级。"
+
+#: ../../source/mp/coordinator.rst:453
+msgid ""
+"When no quota was registered for the salt, ``status`` is "
+"``\"not_found\"`` (still ``200 OK``)."
+msgstr "当未为盐注册配额时，``status`` 为 ``\"not_found\"``（仍然是 ``200 OK``）。"
+
+#: ../../source/mp/coordinator.rst:458
+msgid "``200``: removed, or ``not_found`` if no quota existed."
+msgstr "``200``: 已移除，或 ``not_found`` 如果不存在配额。"
+
+#: ../../source/mp/coordinator.rst:468
+#, python-brace-format
+msgid "``GET /quota/{cache_salt}``"
+msgstr "``GET /quota/{cache_salt}``"
+
+#: ../../source/mp/coordinator.rst:470
+msgid "Read the quota and live usage for a single salt."
+msgstr "读取单个盐的配额和实时使用情况。"
+
+#: ../../source/mp/coordinator.rst:475 ../../source/mp/coordinator.rst:503
+msgid "**Query parameters:** ``tier`` — optional (default ``l2``)."
+msgstr "**查询参数:** ``tier`` — 可选（默认 ``l2``）。"
+
+#: ../../source/mp/coordinator.rst:483
+msgid ""
+"``quota_limit_gb`` is the configured limit in GiB (``0.0`` when no quota "
+"is set), ``quota_exists`` whether an explicit quota is registered, and "
+"``usage_gb`` the current aggregate usage. This endpoint never returns "
+"``404`` for an unknown salt."
+msgstr "``quota_limit_gb`` 是以 GiB 为单位的配置限制（当未设置配额时为 ``0.0``），``quota_exists`` 表示是否注册了显式配额，``usage_gb`` 是当前的总使用量。此端点对于未知的 salt 永远不会返回 ``404``。"
+
+#: ../../source/mp/coordinator.rst:489
+msgid "``200``: quota and usage reported."
+msgstr "``200``: 报告配额和使用情况。"
+
+#: ../../source/mp/coordinator.rst:499
+msgid "``GET /quota``"
+msgstr "``GET /quota``"
+
+#: ../../source/mp/coordinator.rst:501
+msgid "List total usage and a per-salt breakdown."
+msgstr "列出总使用量和每个 salt 的详细信息。"
+
+#: ../../source/mp/coordinator.rst:516
+#, python-brace-format
+msgid ""
+"``total_gb`` is aggregate usage across all salts in GiB; each "
+"``by_cache_salt`` entry has the same fields as the ``GET "
+"/quota/{cache_salt}`` response."
+msgstr "``total_gb`` 是所有 salt 的总使用量（以 GiB 为单位）；每个 ``by_cache_salt`` 条目具有与 ``GET /quota/{cache_salt}`` 响应相同的字段。"
+
+#: ../../source/mp/coordinator.rst:521
+msgid "``200``: usage reported."
+msgstr "``200``: 报告的使用情况。"
+
+#: ../../source/mp/coordinator.rst:531
+msgid "``POST /quota/events``"
+msgstr "``POST /quota/events``"
+
+#: ../../source/mp/coordinator.rst:533
+msgid ""
+"Ingest a batch of usage events. Sent automatically by reporting MP "
+"servers; not usually called by hand."
+msgstr "摄取一批使用事件。由报告 MP 服务器自动发送；通常不手动调用。"
+
+#: ../../source/mp/coordinator.rst:547
+msgid "The MP server that produced this batch."
+msgstr "生成此批次的 MP 服务器。"
+
+#: ../../source/mp/coordinator.rst:548
+msgid "``seq``"
+msgstr "``seq``"
+
+#: ../../source/mp/coordinator.rst:550
+msgid ""
+"Monotonic per-instance sequence number (``>= 1``); supports future gap "
+"detection of lost batches."
+msgstr "每个实例的单调序列号（``>= 1``）；支持未来丢失批次的间隙检测。"
+
+#: ../../source/mp/coordinator.rst:554
+msgid "Optional (default ``l2``). Cache tier the events apply to."
+msgstr "可选（默认 ``l2``）。事件适用的缓存层。"
+
+#: ../../source/mp/coordinator.rst:555
+msgid "``events``"
+msgstr "``events``"
+
+#: ../../source/mp/coordinator.rst:556
+msgid "list[object]"
+msgstr "列表[对象]"
+
+#: ../../source/mp/coordinator.rst:557
+#, python-brace-format
+msgid ""
+"The events to record. Each is ``{\"type\", \"key\", \"bytes\"}``: "
+"``type`` is ``\"store\"``, ``\"lookup\"``, or ``\"delete\"``; ``key`` is "
+"the encoded object key; ``bytes`` (``>= 0``) is the stored size — counted"
+" for ``store`` and ignored for ``lookup`` / ``delete`` (a ``delete`` "
+"subtracts the size recorded at the original ``store``)."
+msgstr "要记录的事件。每个事件为 ``{\\\"type\\\", \\\"key\\\", \\\"bytes\\\"}``： ``type`` 为 ``\\\"store\\\"``、``\\\"lookup\\\"`` 或 ``\\\"delete\\\"``； ``key`` 是编码后的对象键； ``bytes`` (``>= 0``) 是存储的大小 — 对于 ``store`` 计入，对于 ``lookup`` / ``delete`` 忽略（``delete`` 会减去在原始 ``store`` 记录的大小）。"
+
+#: ../../source/mp/coordinator.rst:569
+msgid "``recorded`` is the number of events processed."
+msgstr "``recorded`` 是处理的事件数量。"
+
+#: ../../source/mp/coordinator.rst:573
+msgid "``200``: events processed."
+msgstr "``200``: 处理的事件数量。"
+
+#: ../../source/mp/coordinator.rst:594
+msgid "Cache control"
+msgstr "缓存控制"
+
+#: ../../source/mp/coordinator.rst:596
+msgid ""
+"The ``/cache`` group dispatches cache operations to a named MP server. "
+"Today it covers **warm prefetch**; further cache-control operations will "
+"be documented as endpoints here as they land."
+msgstr "``/cache`` 组将缓存操作分派给命名的 MP 服务器。今天它涵盖 **热预取**；进一步的缓存控制操作将在此处作为端点记录。"
+
+#: ../../source/mp/coordinator.rst:600
+msgid ""
+"**Warm prefetch (pre-loading L1 from L2).** Pre-warm one MP server's L1 "
+"with the KV for a known prompt **before** the requests arrive, so the "
+"first request hits L1 instead of paying the L2 fetch inline -- useful "
+"when you know a workload is about to be routed to a node (a traffic "
+"shift, a hot shared system prompt)."
+msgstr "**热预取（从 L2 预加载 L1）。** 在请求到达之前，用已知提示的 KV 预热一个 MP 服务器的 L1，以便第一个请求命中 L1，而不是支付 L2 内联获取的费用——当您知道工作负载即将路由到节点（流量转移、热共享系统提示）时，这非常有用。"
+
+#: ../../source/mp/coordinator.rst:605
+msgid ""
+"You describe the content by **token ids** -- the unit the cache speaks --"
+" never by internal cache keys, which you cannot construct (a key is a "
+"content hash plus a per-rank layout bitmap). The coordinator forwards the"
+" request to the named server, which hashes the tokens, expands them "
+"across the node's ranks, loads the chunks from L2 into L1, and "
+"**retains** them so a later lookup hits. The submit returns a "
+"``request_id``; poll the status endpoint until ``completed``. The warm "
+"acquires no lock -- the poll simply reports progress and clears the "
+"server-side job once the load finishes."
+msgstr "您通过 **token ids** 描述内容——缓存使用的单位——而不是通过内部缓存键，您无法构造这些键（键是内容哈希加上每个排名的布局位图）。协调器将请求转发到指定的服务器，该服务器对令牌进行哈希，将它们扩展到节点的各个排名，从 L2 加载块到 L1，并 **保留** 它们，以便后续查找命中。提交返回一个 ``request_id``；轮询状态端点直到 ``completed``。预热不需要获取锁——轮询仅报告进度，并在加载完成后清除服务器端作业。"
+
+#: ../../source/mp/coordinator.rst:615
+msgid "``POST /cache/prefetches``"
+msgstr "``POST /cache/prefetches``"
+
+#: ../../source/mp/coordinator.rst:617
+msgid "Submit a warm prefetch of a token sequence on one named server."
+msgstr "在一个指定的服务器上提交一个令牌序列的预热预取。"
+
+#: ../../source/mp/coordinator.rst:630
+msgid "Target MP server; must be registered."
+msgstr "目标 MP 服务器；必须已注册。"
+
+#: ../../source/mp/coordinator.rst:631
+msgid "``model_name``"
+msgstr "``model_name``"
+
+#: ../../source/mp/coordinator.rst:633
+msgid "Model whose layout sizes the target's L1 buffers."
+msgstr "目标的 L1 缓冲区布局大小的模型。"
+
+#: ../../source/mp/coordinator.rst:634
+msgid "``world_size``"
+msgstr "``world_size``"
+
+#: ../../source/mp/coordinator.rst:636
+msgid ""
+"World size (``>= 1``) selecting the KV layout and the per-rank fan-out "
+"(``1`` for a single-GPU, TP=1 deployment)."
+msgstr "世界大小（``>= 1``），选择 KV 布局和每个 rank 的扇出（对于单 GPU，TP=1 部署为 ``1``）。"
+
+#: ../../source/mp/coordinator.rst:638
+msgid "``token_ids``"
+msgstr "``token_ids``"
+
+#: ../../source/mp/coordinator.rst:639
+msgid "list[int]"
+msgstr "列表[int]"
+
+#: ../../source/mp/coordinator.rst:640
+msgid ""
+"Prompt tokens whose complete ``chunk_size`` chunks are warmed; must match"
+" what was stored (same tokenizer / special tokens). A sub-chunk sequence "
+"is a ``noop``."
+msgstr "完全 ``chunk_size`` 块的提示令牌已预热；必须与存储的内容匹配（相同的分词器/特殊令牌）。子块序列是 ``noop``。"
+
+#: ../../source/mp/coordinator.rst:643
+#, python-brace-format
+msgid "``cache_salt``"
+msgstr "``cache_salt``"
+
+#: ../../source/mp/coordinator.rst:645
+msgid ""
+"Optional (default ``\"\"``). Per-tenant isolation salt applied to the "
+"produced keys."
+msgstr "可选（默认 ``\"\"``）。应用于生成键的每个租户隔离盐。"
+
+#: ../../source/mp/coordinator.rst:654
+msgid ""
+"When the sequence is shorter than one chunk, nothing is submitted and "
+"``request_id`` is empty:"
+msgstr "当序列短于一个块时，什么都不会被提交，``request_id`` 为空："
+
+#: ../../source/mp/coordinator.rst:661
+msgid ""
+"``request_id`` is the id to poll; ``chunks`` is the number of whole "
+"chunks submitted to warm."
+msgstr "``request_id`` 是用于轮询的 ID；``chunks`` 是提交的完整块的数量。"
+
+#: ../../source/mp/coordinator.rst:666
+msgid "``200``: submitted (or a ``noop`` as above)."
+msgstr "``200``：已提交（或如上所述的 ``noop``）。"
+
+#: ../../source/mp/coordinator.rst:667
+msgid "``404``: unknown ``instance_id`` (not registered)."
+msgstr "``404``: 未知 ``instance_id``（未注册）。"
+
+#: ../../source/mp/coordinator.rst:668
+msgid "``502``: the target server was unreachable or rejected the submit."
+msgstr "``502``: 目标服务器无法访问或拒绝了提交。"
+
+#: ../../source/mp/coordinator.rst:673
+msgid ""
+"**Single-node scope:** one ``instance_id`` warms only that node's shards."
+" For a model sharded across multiple nodes, submit one request per node's"
+" instance."
+msgstr "**单节点范围：** 一个 ``instance_id`` 仅对该节点的分片进行预热。对于跨多个节点的模型，每个节点的实例需提交一个请求。"
+
+#: ../../source/mp/coordinator.rst:692
+#, python-brace-format
+msgid "``GET /cache/prefetches/{instance_id}/{request_id}``"
+msgstr "``GET /cache/prefetches/{instance_id}/{request_id}``"
+
+#: ../../source/mp/coordinator.rst:694
+msgid ""
+"Poll a submitted warm prefetch; the response relays the owning server's "
+"status verbatim with its code."
+msgstr "轮询已提交的预热预取；响应将拥有服务器的状态及其代码逐字传递。"
+
+#: ../../source/mp/coordinator.rst:697
+msgid "**Path parameters:**"
+msgstr "**路径参数：**"
+
+#: ../../source/mp/coordinator.rst:708
+msgid "The server the prefetch was submitted to."
+msgstr "提交预取的服务器。"
+
+#: ../../source/mp/coordinator.rst:709
+msgid "``request_id``"
+msgstr "``request_id``"
+
+#: ../../source/mp/coordinator.rst:711
+msgid "The id returned by ``POST /cache/prefetches``."
+msgstr "由 ``POST /cache/prefetches`` 返回的 id。"
+
+#: ../../source/mp/coordinator.rst:713
+msgid "**Response** (``200 OK``) while the load runs:"
+msgstr "**响应** (``200 OK``) 在加载运行时："
+
+#: ../../source/mp/coordinator.rst:719
+msgid "…and once complete:"
+msgstr "…并且一旦完成："
+
+#: ../../source/mp/coordinator.rst:725
+msgid "``found_keys`` of ``total_keys`` requested chunks were resident."
+msgstr "``found_keys`` 的 ``total_keys`` 请求块是常驻的。"
+
+#: ../../source/mp/coordinator.rst:729
+msgid "``200``: status reported (``pending`` or ``completed``)."
+msgstr "``200``: 状态报告（``pending`` 或 ``completed``）。"
+
+#: ../../source/mp/coordinator.rst:730
+msgid ""
+"``404``: unknown ``instance_id``, or unknown ``request_id`` relayed from "
+"the server."
+msgstr "``404``: 未知的 ``instance_id``，或来自服务器的未知 ``request_id``。"
+
+#: ../../source/mp/coordinator.rst:732
+msgid "``502``: the target server was unreachable."
+msgstr "``502``: 目标服务器无法访问。"
+
+#~ msgid ""
+#~ "**Event ingestion** -- MP servers POST"
+#~ " batched events; this is handled "
+#~ "automatically by the event listener and"
+#~ " is not typically called manually."
+#~ msgstr "**事件摄取** -- MP 服务器通过 POST 批量事件；这由事件监听器自动处理，通常不需要手动调用。"
+
+#~ msgid "Inspecting the fleet"
+#~ msgstr "检查集群"
+
+#~ msgid "Two read-only endpoints let you observe the coordinator:"
+#~ msgstr "以下两个只读端点可用于查看协调器状态："
+
+#~ msgid ""
+#~ "Each event batch carries the server's"
+#~ " ``instance_id`` and a monotonically "
+#~ "increasing sequence number (``seq``) scoped"
+#~ " to that instance. These fields "
+#~ "enable future gap detection to identify"
+#~ " lost batches."
+#~ msgstr ""
+#~ "每个事件批次携带服务器的 ``instance_id`` 和一个按实例范围单调递增的序列号 "
+#~ "(``seq``)。这些字段为未来实现缺口检测（识别丢失批次）提供了支持。"
+
+#~ msgid ""
+#~ "**Quota management** -- set per-``cache_salt``"
+#~ " byte budgets. Salts without a quota"
+#~ " default to a 0-byte limit (allowlist"
+#~ " semantics)."
+#~ msgstr "**配额管理** -- 为每个 ``cache_salt`` 设置字节预算。未设置配额的 salt 默认限额为 0 字节（白名单语义）。"
+
+#~ msgid "Use ``_default`` as the path parameter to target the empty-string salt."
+#~ msgstr "使用 ``_default`` 作为路径参数，以指向空字符串 salt。"
+
+#~ msgid ""
+#~ "**Event ingestion** -- MP servers POST"
+#~ " batched events; this is handled "
+#~ "automatically by the event listener and"
+#~ " is not typically called manually. "
+#~ "Supported event types are ``store``, "
+#~ "``lookup``, and ``delete``. A ``delete`` "
+#~ "event subtracts the key's previously-"
+#~ "recorded bytes from the per-salt "
+#~ "totals (the wire ``bytes`` field is "
+#~ "ignored for ``delete``; the coordinator "
+#~ "already knows the size from the "
+#~ "original ``store``)."
+#~ msgstr ""
+#~ "**事件摄取** -- MP 服务器以 POST "
+#~ "方式发送批量事件；这由事件监听器自动处理，通常不需要手动调用。支持的事件类型有 ``store``、``lookup`` "
+#~ "和 ``delete``。``delete`` 事件从每个盐的总数中减去该键之前记录的字节数（对于 "
+#~ "``delete``，网络 ``bytes`` 字段被忽略；协调器已经知道原始 ``store``"
+#~ " 的大小）。"
+
+#~ msgid "**Status queries** -- inspect usage and quota info."
+#~ msgstr "**状态查询** -- 检查使用情况和配额信息。"
+
+#~ msgid "Method"
+#~ msgstr "方法"
+
+#~ msgid "Path"
+#~ msgstr "路径"
+
+#~ msgid "Create or update a quota (body: ``{\"limit_gb\": N}``)."
+#~ msgstr "创建或更新配额（请求体：\\ ``{\\\"limit_gb\\\": N}``\\ ）。"
+
+#~ msgid "Remove a salt's quota entry."
+#~ msgstr "删除指定 salt 的配额条目。"
+
+#~ msgid "Ingest a batch of L2 ``store`` / ``lookup`` / ``delete`` events."
+#~ msgstr "摄取一批 L2 ``store`` / ``lookup`` / ``delete`` 事件。"
+
+#~ msgid "``/l2/status/{cache_salt}``"
+#~ msgstr "``/l2/status/{cache_salt}``"
+
+#~ msgid "``/l2/status``"
+#~ msgstr "``/l2/status``"
+
+#~ msgid "Poll a submitted warm prefetch (``pending`` / ``completed``)."
+#~ msgstr "轮询已提交的热预取（``待处理`` / ``已完成``）。"
+
+#~ msgid "Warm prefetch (pre-loading L1 from L2)"
+#~ msgstr "预加载 L1 从 L2 的温预取"
+
+#~ msgid ""
+#~ "The submit returns a ``request_id``; "
+#~ "poll the status endpoint until "
+#~ "``completed``. The warm acquires no lock"
+#~ " -- the poll simply reports progress"
+#~ " and clears the server-side job "
+#~ "once the load finishes."
+#~ msgstr ""
+#~ "提交返回一个 ``request_id``；轮询状态端点直到 "
+#~ "``completed``。预热不获取锁——轮询仅报告进度，并在加载完成后清除服务器端的任务。"
+
+#~ msgid "A few rules of thumb:"
+#~ msgstr "一些经验法则："
+
+#~ msgid ""
+#~ "``token_ids`` must match what was stored"
+#~ " (same tokenizer / special tokens) "
+#~ "and contain at least one full "
+#~ "``chunk_size`` of tokens -- only "
+#~ "complete chunks are warmed (a shorter"
+#~ " sequence returns ``status: \"noop\"``)."
+#~ msgstr ""
+#~ "``token_ids`` 必须与存储的内容匹配（相同的分词器/特殊标记），并且至少包含一个完整的 "
+#~ "``chunk_size`` 的标记——只有完整的块会被预热（较短的序列返回 ``status: "
+#~ "\\\"noop\\\"``）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/deployment.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/deployment.po
new file mode 100644
index 0000000..5272aed
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/deployment.po
@@ -0,0 +1,358 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/deployment.rst:2
+msgid "Deployment Guide"
+msgstr "部署指南"
+
+#: ../../source/mp/deployment.rst:4
+msgid ""
+"This page covers deploying LMCache multiprocess mode in Docker and "
+"Kubernetes environments, along with production best practices."
+msgstr "本页介绍如何在 Docker 和 Kubernetes 环境中部署 LMCache 多进程模式，并提供生产环境的最佳实践建议。"
+
+#: ../../source/mp/deployment.rst:12
+msgid "Docker"
+msgstr "Docker"
+
+#: ../../source/mp/deployment.rst:14
+msgid "**LMCache container:**"
+msgstr "**LMCache 容器：**"
+
+#: ../../source/mp/deployment.rst:25
+msgid "**vLLM container:**"
+msgstr "**vLLM 容器：**"
+
+#: ../../source/mp/deployment.rst:37
+msgid "Required Docker flags:"
+msgstr "所需的 Docker 标志："
+
+#: ../../source/mp/deployment.rst:39
+msgid ""
+"``--network host`` -- Allows the vLLM container to reach LMCache on "
+"localhost."
+msgstr "``--network host`` -- 允许 vLLM 容器访问本地主机上的 LMCache。"
+
+#: ../../source/mp/deployment.rst:40
+msgid ""
+"``--ipc host`` -- Required for CUDA IPC shared memory transfers between "
+"containers."
+msgstr "``--ipc host`` -- 容器间 CUDA IPC 共享内存传输所必需。"
+
+#: ../../source/mp/deployment.rst:42
+msgid ""
+"``--runtime nvidia --gpus all`` -- GPU access via the NVIDIA container "
+"runtime."
+msgstr "``--runtime nvidia --gpus all`` -- 通过 NVIDIA 容器运行时访问 GPU。"
+
+#: ../../source/mp/deployment.rst:45
+msgid "**HTTP server variant:**"
+msgstr "**HTTP 服务器变体：**"
+
+#: ../../source/mp/deployment.rst:47
+msgid ""
+"For health-check and cache management API support (useful with container "
+"orchestrators), use the HTTP server entry point:"
+msgstr "对于健康检查和缓存管理 API 支持（在容器编排器中非常有用），请使用 HTTP 服务器入口点："
+
+#: ../../source/mp/deployment.rst:60
+msgid "Kubernetes"
+msgstr "Kubernetes"
+
+#: ../../source/mp/deployment.rst:62
+msgid ""
+"LMCache is designed for a **DaemonSet + Deployment** pattern: one LMCache"
+" server per node (DaemonSet) shared by multiple vLLM pods (Deployment)."
+msgstr ""
+"LMCache 设计为 **DaemonSet + Deployment** 模式：每个节点一个 LMCache "
+"服务器（DaemonSet），由多个 vLLM pod（Deployment）共享。"
+
+#: ../../source/mp/deployment.rst:65
+msgid "Example YAML files are provided in ``examples/multi_process/``."
+msgstr "在 ``examples/multi_process/`` 中提供了示例 YAML 文件。"
+
+#: ../../source/mp/deployment.rst:68
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/mp/deployment.rst:70
+msgid "Kubernetes cluster with GPU support (NVIDIA GPU Operator installed)"
+msgstr "支持 GPU 的 Kubernetes 集群（安装了 NVIDIA GPU Operator）"
+
+#: ../../source/mp/deployment.rst:71
+msgid "At least 4 GPUs per node"
+msgstr "每个节点至少需要 4 个 GPU"
+
+#: ../../source/mp/deployment.rst:72
+msgid "``kubectl`` configured to access your cluster"
+msgstr "``kubectl`` 配置为访问您的集群"
+
+#: ../../source/mp/deployment.rst:75
+msgid "Step-by-Step"
+msgstr "逐步指南"
+
+#: ../../source/mp/deployment.rst:77
+msgid "**Step 1: Create namespace**"
+msgstr "**步骤 1：创建命名空间**"
+
+#: ../../source/mp/deployment.rst:83
+msgid "**Step 2: Deploy LMCache DaemonSet**"
+msgstr "**步骤 2：部署 LMCache DaemonSet**"
+
+#: ../../source/mp/deployment.rst:89
+msgid "**Step 3: Deploy vLLM**"
+msgstr "**步骤 3：部署 vLLM**"
+
+#: ../../source/mp/deployment.rst:96
+msgid ""
+"The default model is ``Qwen/Qwen3-14B``.  For gated models (e.g., Llama),"
+" create a Secret with your Hugging Face token:"
+msgstr "默认模型是 ``Qwen/Qwen3-14B``\\ 。对于受限模型（例如 Llama），请使用您的 Hugging Face Token 创建一个 Secret："
+
+#: ../../source/mp/deployment.rst:105
+msgid "Then add the ``HF_TOKEN`` environment variable to the vLLM container spec."
+msgstr "然后将 ``HF_TOKEN`` 环境变量添加到 vLLM 容器规格中。"
+
+#: ../../source/mp/deployment.rst:107
+msgid "**Step 4: Monitor deployment**"
+msgstr "**步骤 4：监控部署**"
+
+#: ../../source/mp/deployment.rst:126
+msgid "**Step 5: Send test requests**"
+msgstr "**步骤 5：发送测试请求**"
+
+#: ../../source/mp/deployment.rst:141
+msgid "Architecture Notes"
+msgstr "架构说明"
+
+#: ../../source/mp/deployment.rst:143
+msgid ""
+"**DaemonSet uses ``hostNetwork: true``** so vLLM pods discover the "
+"LMCache server via ``status.hostIP``."
+msgstr ""
+"**DaemonSet 使用 ``hostNetwork: true``** 以便 vLLM pod 通过 ``status.hostIP`` "
+"发现 LMCache 服务器。"
+
+#: ../../source/mp/deployment.rst:145
+msgid ""
+"**Both containers mount ``/dev/shm``** from the host to enable CUDA IPC "
+"memory sharing."
+msgstr "**两个容器从主机挂载 ``/dev/shm``** 以启用 CUDA IPC 内存共享。"
+
+#: ../../source/mp/deployment.rst:147
+msgid ""
+"**GPUs are NOT requested in the DaemonSet** -- this allows GPUs to remain"
+" exclusively allocated to vLLM pods.  The NVIDIA container runtime "
+"automatically provides GPU access for IPC-based memory transfers."
+msgstr "**DaemonSet 不申请 GPU 资源** -- 这样 GPU 可以完全专属分配给 vLLM pod。NVIDIA 容器运行时会自动为基于 IPC 的内存传输提供 GPU 访问权限。"
+
+#: ../../source/mp/deployment.rst:150
+msgid ""
+"**Multiple vLLM pods** on the same node automatically connect to the same"
+" LMCache DaemonSet instance."
+msgstr "**多个 vLLM pod** 在同一节点上会自动连接到同一个 LMCache DaemonSet 实例。"
+
+#: ../../source/mp/deployment.rst:154
+msgid ""
+"LMCache pods on nodes without GPUs will crash with CUDA initialization "
+"errors.  This is expected -- LMCache only needs to run on GPU nodes where"
+" vLLM pods are scheduled."
+msgstr ""
+"没有 GPU 的节点上的 LMCache pod 会因 CUDA 初始化错误而崩溃。这是预期的——LMCache 只需要在调度有 vLLM pod"
+" 的 GPU 节点上运行。"
+
+#: ../../source/mp/deployment.rst:159
+msgid "Health Checking (HTTP Server)"
+msgstr "健康检查 (HTTP 服务器)"
+
+#: ../../source/mp/deployment.rst:161
+msgid ""
+"For Kubernetes liveness/readiness probes, deploy the HTTP server variant "
+"instead.  Use the ``/healthcheck`` endpoint:"
+msgstr "若要配置 Kubernetes 存活探针/就绪探针，请部署 HTTP 服务器变体，并使用 ``/healthcheck`` 端点："
+
+#: ../../source/mp/deployment.rst:180
+msgid "Monitoring Integration"
+msgstr "监控集成"
+
+#: ../../source/mp/deployment.rst:182
+msgid ""
+"Prometheus metrics are enabled by default on port 9090.  Add a "
+"``ServiceMonitor`` or Prometheus scrape annotation to collect metrics "
+"from the LMCache DaemonSet pods.  See :doc:`observability/index` for "
+"metric details."
+msgstr "默认情况下，Prometheus 指标在 9090 端口启用。添加 ``ServiceMonitor`` 或 Prometheus 抓取注释以收集 LMCache DaemonSet Pod 的指标。有关指标详细信息，请参见 :doc:`observability/index`。"
+
+#: ../../source/mp/deployment.rst:187
+msgid "Cleanup"
+msgstr "清理"
+
+#: ../../source/mp/deployment.rst:196
+msgid "Production Best Practices"
+msgstr "生产最佳实践"
+
+#: ../../source/mp/deployment.rst:198
+msgid ""
+"**Worker count (``--max-workers``, ``--max-gpu-workers``, ``--max-cpu-"
+"workers``):** ``--max-workers`` sets both the GPU affinity pool and CPU "
+"normal pool sizes (default 1).  Use ``--max-gpu-workers`` to override the"
+" GPU pool independently --- set it to at least the number of vLLM "
+"instances sharing the cache server so each instance gets its own "
+"dedicated thread.  Use ``--max-cpu-workers`` to override the CPU pool for"
+" lookup and other non-GPU operations."
+msgstr "**工作线程数 (``--max-workers``, ``--max-gpu-workers``, ``--max-cpu-workers``):** ``--max-workers`` 同时设置 GPU 亲和性池和 CPU 普通池的大小（默认值为 1）。使用 ``--max-gpu-workers`` 可单独覆盖 GPU 池大小——建议将其设置为至少等于共享同一缓存服务器的 vLLM 实例数量，以便每个实例拥有专属的工作线程。使用 ``--max-cpu-workers`` 可覆盖用于查找及其他非 GPU 操作的 CPU 池大小。"
+
+#: ../../source/mp/deployment.rst:205
+msgid ""
+"**L1 memory sizing (``--l1-size-gb``):** Allocate as much CPU memory as "
+"available after accounting for the OS and vLLM. A larger L1 cache means "
+"fewer L2 round-trips."
+msgstr ""
+"**L1 内存大小 (``--l1-size-gb``):** 在考虑操作系统和 vLLM 后，分配尽可能多的 CPU 内存。更大的 L1 "
+"缓存意味着更少的 L2 往返。"
+
+#: ../../source/mp/deployment.rst:209
+msgid "**Eviction tuning:**"
+msgstr "**逐出调优:**"
+
+#: ../../source/mp/deployment.rst:211
+#, python-format
+msgid ""
+"``--eviction-trigger-watermark 0.8`` (default) triggers eviction when L1 "
+"is 80% full."
+msgstr "``--eviction-trigger-watermark 0.8``\\ （默认值）在 L1 达到 80% 满时触发逐出。"
+
+#: ../../source/mp/deployment.rst:213
+#, python-format
+msgid ""
+"``--eviction-ratio 0.2`` (default) frees 20% of allocated memory per "
+"eviction cycle."
+msgstr "``--eviction-ratio 0.2``\\ （默认值）在每个逐出周期释放 20% 的分配内存。"
+
+#: ../../source/mp/deployment.rst:215
+msgid ""
+"Lower the watermark or increase the ratio if you observe frequent "
+"evictions under steady load."
+msgstr "如果在稳定负载下观察到频繁的逐出，请降低水位线或增加比率。"
+
+#: ../../source/mp/deployment.rst:218
+msgid ""
+"**Logging:** Use ``LMCACHE_LOG_LEVEL=DEBUG`` during initial setup to "
+"verify L2 store/load activity.  Switch to ``INFO`` (default) for "
+"production to reduce log volume."
+msgstr "**日志记录:** 在初始设置期间使用 ``LMCACHE_LOG_LEVEL=DEBUG`` 来验证 L2 存储/加载活动。 在生产中切换到 ``INFO``\\ （默认）以减少日志量。"
+
+#: ../../source/mp/deployment.rst:223
+msgid "Transfer Mode (``--supported-transfer-mode``, ``--shm-name``)"
+msgstr "传输模式 (``--supported-transfer-mode``, ``--shm-name``)"
+
+#: ../../source/mp/deployment.rst:225
+msgid ""
+"LMCache supports two worker → server transfer paths: an **lmcache-"
+"driven** path (server pulls/pushes via CUDA IPC or CPU SHM, used for "
+"STORE/RETRIEVE) and an **engine-driven** path (PREPARE/COMMIT, used by "
+"CPU-only or non-CUDA accelerator workers). The server picks which paths "
+"to load via ``--supported-transfer-mode``:"
+msgstr "LMCache 支持两条工作节点 → 服务器传输路径：一种是 **lmcache 驱动** 路径（服务器通过 CUDA IPC 或 CPU SHM 拉取/推送，用于 STORE/RETRIEVE），另一种是 **引擎驱动** 路径（PREPARE/COMMIT，仅由 CPU 或非 CUDA 加速器工作节点使用）。服务器通过 ``--supported-transfer-mode`` 选择加载哪些路径："
+
+#: ../../source/mp/deployment.rst:231
+msgid ""
+"``auto`` *(default)* -- load both paths.  Workers of either device type "
+"can connect without manual configuration; the server has no upfront "
+"knowledge of the connecting worker's device."
+msgstr "``auto`` (默认) -- 同时加载两条路径。任意设备类型的工作节点均可直接连接，无需手动配置；服务器无需预先知晓所连接工作节点的设备类型。"
+
+#: ../../source/mp/deployment.rst:234
+msgid ""
+"``lmcache_driven`` -- load only the server-driven transfer path. Supports"
+" CUDA devices (IPC) and CPU devices (SHM).  Use to skip allocating the "
+"engine-driven prepare/commit resources (pickle codec)."
+msgstr "``lmcache_driven`` -- 仅加载服务器驱动的传输路径。支持 CUDA 设备（IPC）和 CPU 设备（SHM）。用于跳过分配引擎驱动的准备/提交资源（pickle 编解码器）。"
+
+#: ../../source/mp/deployment.rst:237
+msgid ""
+"``engine_driven`` -- load only the engine-driven path.  Use when serving "
+"CPU-only or non-CUDA accelerator workers."
+msgstr "``engine_driven`` -- 仅加载引擎驱动路径。适用于仅使用 CPU 或非 CUDA 加速器的工作节点场景。"
+
+#: ../../source/mp/deployment.rst:240
+msgid ""
+"When the engine-driven path is loaded (``auto`` or ``engine_driven``), "
+"LMCache by default creates a shared-memory (SHM) pool for KV transfers "
+"between the server and vLLM workers.  The ``--shm-name`` option lets you "
+"control this behavior:"
+msgstr "当加载引擎驱动路径（\\ ``auto`` 或 ``engine_driven``\\ ）时，LMCache 默认会为服务器与 vLLM 工作节点之间的 KV 传输创建一个共享内存（SHM）池。\\ ``--shm-name`` 选项让您可以控制此行为："
+
+#: ../../source/mp/deployment.rst:249
+msgid "Value"
+msgstr "值"
+
+#: ../../source/mp/deployment.rst:250
+msgid "Effect"
+msgstr "效果"
+
+#: ../../source/mp/deployment.rst:251
+msgid "*(not set)* (default)"
+msgstr "(未设置) (默认)"
+
+#: ../../source/mp/deployment.rst:252
+msgid "Auto-allocate a SHM pool (current default behavior)."
+msgstr "自动分配一个 SHM 池（当前默认行为）。"
+
+#: ../../source/mp/deployment.rst:253
+msgid "``\"\"`` (empty string)"
+msgstr "``\"\"`` (空字符串)"
+
+#: ../../source/mp/deployment.rst:254
+msgid ""
+"Disable the SHM pool entirely and fall back to the pickle-based transfer "
+"path.  Useful when ``/dev/shm`` is unavailable or when running without "
+"``--ipc host`` in Docker."
+msgstr ""
+"完全禁用 SHM 池并回退到基于 pickle 的传输路径。当 ``/dev/shm`` 不可用或在 Docker 中未使用 ``--ipc "
+"host`` 时非常有用。"
+
+#: ../../source/mp/deployment.rst:257
+msgid "``\"my_pool\"`` (any non-empty name)"
+msgstr "``\"my_pool\"``\\ （任何非空名称）"
+
+#: ../../source/mp/deployment.rst:258
+msgid ""
+"Use that exact name for the SHM segment instead of the auto-generated "
+"one.  Handy when you need a deterministic, human-readable segment name "
+"for monitoring or debugging."
+msgstr "将该名称用作 SHM 段名，而非自动生成的名称。当您需要使用固定且易读的段名称以方便监控或调试时，此选项非常实用。"
+
+#: ../../source/mp/deployment.rst:262
+msgid "**Examples:**"
+msgstr "**示例：**"
+
+#~ msgid ""
+#~ "``gpu`` -- load only the GPU IPC"
+#~ " path.  Use when every worker is "
+#~ "a CUDA device and you want to "
+#~ "skip allocating the non-GPU resources"
+#~ " (SHM pool, pickle codec)."
+#~ msgstr ""
+#~ "``gpu`` -- 仅加载 GPU IPC 路径。当每个工作节点都是 "
+#~ "CUDA 设备时使用，并且您希望跳过分配非 GPU 资源（SHM 池、pickle "
+#~ "编解码器）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/disaggregated_prefill.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/disaggregated_prefill.po
new file mode 100644
index 0000000..371cb6e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/disaggregated_prefill.po
@@ -0,0 +1,38 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/disaggregated_prefill.rst:4
+msgid "Disaggregated Prefill"
+msgstr "分离式预填充"
+
+#: ../../source/mp/disaggregated_prefill.rst:8
+msgid ""
+"The multiprocess (MP) implementation of disaggregated prefill is **coming"
+" soon**."
+msgstr "分离式预填充的 MP 模式（多进程）实现 **即将推出**\\ 。"
+
+#: ../../source/mp/disaggregated_prefill.rst:11
+msgid ""
+"Until it lands, the in-process implementation (NIXL and shared-storage "
+"transports) is documented in the :doc:`Legacy section <../legacy/index>`:"
+" :doc:`../disaggregated_prefill/nixl/index`."
+msgstr "在它发布之前，进程内实现（NIXL 和共享存储传输）已在 :doc:`旧版部分 <../legacy/index>` 中记录： :doc:`../disaggregated_prefill/nixl/index`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/frontend_dashboard.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/frontend_dashboard.po
new file mode 100644
index 0000000..254b099
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/frontend_dashboard.po
@@ -0,0 +1,354 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-08 10:45+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/frontend_dashboard.rst:2
+msgid "Frontend Dashboard"
+msgstr "前端仪表板"
+
+#: ../../source/mp/frontend_dashboard.rst:4
+msgid ""
+"The **LMCache Frontend Dashboard** is a lightweight web UI that lets you "
+"monitor and manage a fleet of LMCache multiprocess (MP) servers from a "
+"single browser tab.  It is shipped as part of the ``lmcache`` package and"
+" requires no extra infrastructure beyond a small discovery service."
+msgstr "**LMCache 前端仪表板**\\ 是一个轻量级的网页用户界面，允许您从一个浏览器标签页监控和管理一组 LMCache 多进程 (MP) 服务器。它作为 ``lmcache`` 包的一部分提供，不需要额外的基础设施，只需一个小型发现服务。"
+
+#: ../../source/mp/frontend_dashboard.rst:10
+msgid "Architecture Overview"
+msgstr "架构概述"
+
+#: ../../source/mp/frontend_dashboard.rst:12
+msgid "Architecture Diagram"
+msgstr "架构图"
+
+#: ../../source/mp/frontend_dashboard.rst:39
+msgid ""
+"Each LMCache MP server runs a **frontend plugin subprocess** that "
+"periodically sends a heartbeat to the discovery service.  The dashboard "
+"queries the discovery service to discover all live nodes and proxies "
+"their HTTP APIs through a built-in reverse proxy."
+msgstr "每个 LMCache MP 服务器运行一个 **前端插件子进程**\\ ，定期向发现服务发送心跳。仪表板查询发现服务以发现所有活动节点，并通过内置反向代理代理它们的 HTTP API。"
+
+#: ../../source/mp/frontend_dashboard.rst:45
+msgid "Components"
+msgstr "组件"
+
+#: ../../source/mp/frontend_dashboard.rst:51
+msgid "Component"
+msgstr "组件"
+
+#: ../../source/mp/frontend_dashboard.rst:52
+#: ../../source/mp/frontend_dashboard.rst:153
+#: ../../source/mp/frontend_dashboard.rst:193
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/frontend_dashboard.rst:53
+msgid "``lmcache.lmcache_frontend.app``"
+msgstr "``lmcache.lmcache_frontend.app``"
+
+#: ../../source/mp/frontend_dashboard.rst:54
+msgid ""
+"FastAPI application serving the web UI and a reverse proxy to every "
+"registered LMCache node.  Start with ``python -m "
+"lmcache.lmcache_frontend.app``."
+msgstr "FastAPI 应用程序提供 Web UI 和每个注册的 LMCache 节点的反向代理。使用 ``python -m lmcache.lmcache_frontend.app`` 启动。"
+
+#: ../../source/mp/frontend_dashboard.rst:57
+msgid "``lmcache_mp_frontend_plugin``"
+msgstr "``lmcache_mp_frontend_plugin``"
+
+#: ../../source/mp/frontend_dashboard.rst:58
+msgid ""
+"Runtime plugin subprocess launched by ``MPRuntimePluginLauncher``. Runs "
+"``HeartbeatService`` (``--no-http`` mode) to register the server with the"
+" discovery service."
+msgstr "由 ``MPRuntimePluginLauncher`` 启动的运行时插件子进程。运行 ``HeartbeatService``\\ （\\ ``--no-http`` 模式）以将服务器注册到发现服务。"
+
+#: ../../source/mp/frontend_dashboard.rst:61
+msgid "``lmcache.tools.simple_discover_service``"
+msgstr "``lmcache.tools.simple_discover_service``"
+
+#: ../../source/mp/frontend_dashboard.rst:62
+msgid ""
+"Reference Flask discovery service.  Accepts heartbeats at "
+"``/lmcache_heartbeat`` and exposes the node list at ``/lmcache_infos``.  "
+"Start with ``python -m lmcache.tools.simple_discover_service``."
+msgstr "参考 Flask 发现服务。接受 ``/lmcache_heartbeat`` 的心跳并在 ``/lmcache_infos`` 处公开节点列表。使用 ``python -m lmcache.tools.simple_discover_service`` 启动。"
+
+#: ../../source/mp/frontend_dashboard.rst:68
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/mp/frontend_dashboard.rst:70
+msgid "Install the extra dependencies used by the frontend and discovery service:"
+msgstr "安装前端和发现服务所需的额外依赖项："
+
+#: ../../source/mp/frontend_dashboard.rst:76
+msgid "These are not pulled in by the base ``lmcache`` install to keep it slim."
+msgstr "这些并不是通过基础的 ``lmcache`` 安装引入的，以保持其精简。"
+
+#: ../../source/mp/frontend_dashboard.rst:79
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/mp/frontend_dashboard.rst:81
+msgid "**Step 1 — Start the discovery service**"
+msgstr "**步骤 1 — 启动发现服务**"
+
+#: ../../source/mp/frontend_dashboard.rst:87
+msgid "The service listens on ``0.0.0.0:5000`` and exposes:"
+msgstr "该服务监听 ``0.0.0.0:5000`` 并暴露："
+
+#: ../../source/mp/frontend_dashboard.rst:89
+msgid "``GET /lmcache_heartbeat`` — record a heartbeat from an MP server."
+msgstr "``GET /lmcache_heartbeat`` — 记录来自 MP 服务器的心跳。"
+
+#: ../../source/mp/frontend_dashboard.rst:90
+msgid "``GET /lmcache_infos`` — return all registered nodes as JSON."
+msgstr "``GET /lmcache_infos`` — 以 JSON 格式返回所有注册的节点。"
+
+#: ../../source/mp/frontend_dashboard.rst:92
+msgid "**Step 2 — Start the LMCache MP server with the frontend plugin**"
+msgstr "**步骤 2 — 启动带有前端插件的 LMCache MP 服务器**"
+
+#: ../../source/mp/frontend_dashboard.rst:105
+msgid ""
+"The plugin subprocess will start sending heartbeats to the discovery "
+"service every 30 seconds (configurable via ``plugin.frontend.heartbeat-"
+"interval``)."
+msgstr "插件子进程将每 30 秒向发现服务发送一次心跳（可通过 ``plugin.frontend.heartbeat-interval`` 配置）。"
+
+#: ../../source/mp/frontend_dashboard.rst:109
+msgid "Alternatively, use the provided example script:"
+msgstr "或者，使用提供的示例脚本："
+
+#: ../../source/mp/frontend_dashboard.rst:115
+msgid "**Step 3 — Start the dashboard**"
+msgstr "**步骤 3 — 启动仪表板**"
+
+#: ../../source/mp/frontend_dashboard.rst:124
+msgid "Open ``http://localhost:8000`` in your browser."
+msgstr "在浏览器中打开 ``http://localhost:8000``\\ 。"
+
+#: ../../source/mp/frontend_dashboard.rst:127
+msgid ""
+"The dashboard auto-refreshes the node list from the supplier URL at most "
+"once every 30 seconds when the homepage is loaded."
+msgstr "仪表板在加载主页时，最多每 30 秒自动从供应商 URL 刷新一次节点列表。"
+
+#: ../../source/mp/frontend_dashboard.rst:131
+msgid "Dashboard Features"
+msgstr "仪表板功能"
+
+#: ../../source/mp/frontend_dashboard.rst:133
+msgid ""
+"**Node tree view** — shows all proxies and their child nodes in a "
+"collapsible tree."
+msgstr "**节点树视图** — 显示所有代理及其子节点，以可折叠的树形结构呈现。"
+
+#: ../../source/mp/frontend_dashboard.rst:135
+msgid ""
+"**Metrics aggregation** — ``GET /metrics`` on the dashboard aggregates "
+"Prometheus metrics from every leaf node."
+msgstr "**指标聚合** — ``GET /metrics`` 在仪表板上聚合来自每个叶节点的 Prometheus 指标。"
+
+#: ../../source/mp/frontend_dashboard.rst:137
+#, python-brace-format
+msgid ""
+"**Reverse proxy** — ``/proxy2/{node_name}/{path}`` forwards requests to "
+"the named node, enabling direct API access from the browser."
+msgstr "**反向代理** — ``/proxy2/{node_name}/{path}`` 将请求转发到指定节点，使浏览器能够直接访问 API。"
+
+#: ../../source/mp/frontend_dashboard.rst:139
+#, python-brace-format
+msgid ""
+"**Health endpoint** — ``GET /health`` returns ``{\"status\": "
+"\"healthy\"}``."
+msgstr "**健康端点** — ``GET /health`` 返回 ``{\"status\": \"healthy\"}``."
+
+#: ../../source/mp/frontend_dashboard.rst:142
+msgid "CLI Reference"
+msgstr "CLI 参考"
+
+#: ../../source/mp/frontend_dashboard.rst:145
+msgid "``python -m lmcache.lmcache_frontend.app``"
+msgstr "``python -m lmcache.lmcache_frontend.app``"
+
+#: ../../source/mp/frontend_dashboard.rst:151
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/mp/frontend_dashboard.rst:152
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/frontend_dashboard.rst:154
+msgid "``--host``"
+msgstr "``--host``"
+
+#: ../../source/mp/frontend_dashboard.rst:155
+msgid "``0.0.0.0``"
+msgstr "``0.0.0.0``"
+
+#: ../../source/mp/frontend_dashboard.rst:156
+msgid "Bind address for the dashboard HTTP server."
+msgstr "仪表板 HTTP 服务器的绑定地址。"
+
+#: ../../source/mp/frontend_dashboard.rst:157
+msgid "``--port``"
+msgstr "``--port``"
+
+#: ../../source/mp/frontend_dashboard.rst:158
+msgid "``8000``"
+msgstr "``8000``"
+
+#: ../../source/mp/frontend_dashboard.rst:159
+msgid "Port for the dashboard HTTP server."
+msgstr "仪表板 HTTP 服务器的端口。"
+
+#: ../../source/mp/frontend_dashboard.rst:160
+msgid "``--node-supplier-url``"
+msgstr "``--node-supplier-url``"
+
+#: ../../source/mp/frontend_dashboard.rst:161
+#: ../../source/mp/frontend_dashboard.rst:169
+#: ../../source/mp/frontend_dashboard.rst:173
+msgid "*(none)*"
+msgstr "(无)"
+
+#: ../../source/mp/frontend_dashboard.rst:162
+msgid ""
+"URL of the discovery service's node-list endpoint, e.g. "
+"``http://localhost:5000/lmcache_infos``."
+msgstr "发现服务的节点列表端点的 URL，例如 ``http://localhost:5000/lmcache_infos``\\ 。"
+
+#: ../../source/mp/frontend_dashboard.rst:164
+msgid "``--config``"
+msgstr "``--config``"
+
+#: ../../source/mp/frontend_dashboard.rst:165
+msgid "*(built-in)*"
+msgstr "(内置)"
+
+#: ../../source/mp/frontend_dashboard.rst:166
+msgid ""
+"Path to a JSON config file listing proxy nodes.  Used when ``--node-"
+"supplier-url`` is not set."
+msgstr "代理节点的 JSON 配置文件路径。当未设置 ``--node-supplier-url`` 时使用。"
+
+#: ../../source/mp/frontend_dashboard.rst:168
+msgid "``--nodes``"
+msgstr "``--nodes``"
+
+#: ../../source/mp/frontend_dashboard.rst:170
+#, python-brace-format
+msgid ""
+"Inline JSON array of node dicts, e.g. "
+"``'[{\"name\":\"n1\",\"host\":\"127.0.0.1\",\"port\":\"8085\"}]'``."
+msgstr "节点字典的内联 JSON 数组，例如 ``'[{\\\"name\\\":\\\"n1\\\",\\\"host\\\":\\\"127.0.0.1\\\",\\\"port\\\":\\\"8085\\\"}]'``\\ 。"
+
+#: ../../source/mp/frontend_dashboard.rst:172
+msgid "``--heartbeat-url``"
+msgstr "``--heartbeat-url``"
+
+#: ../../source/mp/frontend_dashboard.rst:174
+msgid "If set, the dashboard itself also sends heartbeats to this URL."
+msgstr "如果设置，仪表板本身也会向此 URL 发送心跳。"
+
+#: ../../source/mp/frontend_dashboard.rst:175
+msgid "``--log-level``"
+msgstr "``--log-level``"
+
+#: ../../source/mp/frontend_dashboard.rst:176
+msgid "``warning``"
+msgstr "``warning``"
+
+#: ../../source/mp/frontend_dashboard.rst:177
+msgid "Uvicorn log level (``debug``, ``info``, ``warning``, …)."
+msgstr "Uvicorn 日志级别 (``debug``, ``info``, ``warning``, …)。"
+
+#: ../../source/mp/frontend_dashboard.rst:178
+msgid "``--no-http``"
+msgstr "``--no-http``"
+
+#: ../../source/mp/frontend_dashboard.rst:179
+msgid "``false``"
+msgstr "``false``"
+
+#: ../../source/mp/frontend_dashboard.rst:180
+msgid ""
+"Disable the HTTP server; only the heartbeat loop runs.  Used internally "
+"by the MP plugin."
+msgstr "禁用 HTTP 服务器；仅运行心跳循环。由 MP 插件内部使用。"
+
+#: ../../source/mp/frontend_dashboard.rst:184
+msgid "Plugin Config Keys"
+msgstr "插件配置键"
+
+#: ../../source/mp/frontend_dashboard.rst:186
+msgid ""
+"Pass these inside ``--runtime-plugin-config`` when launching the MP "
+"server:"
+msgstr "在启动 MP 服务器时，将这些放在 ``--runtime-plugin-config`` 中："
+
+#: ../../source/mp/frontend_dashboard.rst:192
+msgid "Key"
+msgstr "键"
+
+#: ../../source/mp/frontend_dashboard.rst:194
+msgid "``plugin.frontend.heartbeat-url``"
+msgstr "``plugin.frontend.heartbeat-url``"
+
+#: ../../source/mp/frontend_dashboard.rst:195
+msgid "**(Required)** Heartbeat endpoint of the discovery service."
+msgstr "**（必需）** 发现服务的心跳端点。"
+
+#: ../../source/mp/frontend_dashboard.rst:196
+msgid "``plugin.frontend.heartbeat-interval``"
+msgstr "``plugin.frontend.heartbeat-interval``"
+
+#: ../../source/mp/frontend_dashboard.rst:197
+msgid "Heartbeat interval in seconds (default: ``30``)."
+msgstr "心跳间隔（单位：秒，默认值：\\ ``30``\\ ）。"
+
+#: ../../source/mp/frontend_dashboard.rst:198
+msgid "``plugin.frontend.heartbeat-initial-delay``"
+msgstr "``plugin.frontend.heartbeat-initial-delay``"
+
+#: ../../source/mp/frontend_dashboard.rst:199
+msgid "Seconds to wait before the first heartbeat (default: ``0``)."
+msgstr "在第一次心跳之前等待的秒数（默认值：\\ ``0``\\ ）。"
+
+#: ../../source/mp/frontend_dashboard.rst:202
+msgid "Using a Custom Discovery Service"
+msgstr "使用自定义发现服务"
+
+#: ../../source/mp/frontend_dashboard.rst:204
+msgid ""
+"The ``simple_discover_service`` is a reference implementation.  Any HTTP "
+"service that accepts the following GET request can be used:"
+msgstr "``simple_discover_service`` 是一个参考实现。任何接受以下 GET 请求的 HTTP 服务都可以使用："
+
+#: ../../source/mp/frontend_dashboard.rst:211
+msgid "And exposes a node-list endpoint that returns JSON in the shape:"
+msgstr "并暴露一个节点列表端点，该端点返回形状为 JSON 的数据："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/http_api.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/http_api.po
new file mode 100644
index 0000000..3b76379
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/http_api.po
@@ -0,0 +1,2411 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/http_api.rst:2
+msgid "HTTP API"
+msgstr "HTTP API"
+
+#: ../../source/mp/http_api.rst:4
+msgid ""
+"When the MP server is started via ``lmcache server`` (the recommended "
+"entry point), a FastAPI-based HTTP frontend is exposed alongside the ZMQ "
+"socket used by vLLM. This HTTP API is intended for operators, "
+"orchestrators (e.g. Kubernetes), and debugging tools — it is **not** on "
+"the inference data path."
+msgstr ""
+"当 MP 服务器通过 ``lmcache server`` 启动时（推荐入口点），会同时暴露一个基于 FastAPI 的 HTTP 前端和 "
+"vLLM 使用的 ZMQ 套接字。此 HTTP API 面向运维人员、编排工具（例如 Kubernetes）和调试工具——它\\ **不**\\ "
+"位于推理数据路径上。"
+
+#: ../../source/mp/http_api.rst:11
+msgid "Where the routes come from"
+msgstr "路由的来源"
+
+#: ../../source/mp/http_api.rst:13
+msgid ""
+"Routes are assembled from three sources, all merged into one FastAPI app "
+"by :class:`~lmcache.v1.multiprocess.http_api_registry.HTTPAPIRegistry` at"
+" startup:"
+msgstr ""
+"路由由三个来源组装而成，在启动时由 "
+":class:`~lmcache.v1.multiprocess.http_api_registry.HTTPAPIRegistry` 合并为一个"
+" FastAPI 应用："
+
+#: ../../source/mp/http_api.rst:16
+msgid ""
+"**MP-native routes** — any module named ``*_api.py`` under "
+"``lmcache/v1/multiprocess/http_apis/`` that exposes a module-level "
+"``router`` (a :class:`fastapi.APIRouter`) is auto-discovered. This covers"
+" the operational surface: status, cache control, L2 management, quota, "
+"and runtime reconfiguration."
+msgstr ""
+"**MP 原生路由** — 在 ``lmcache/v1/multiprocess/http_apis/`` 下任何名为 ``*_api.py``"
+" 的模块，如果暴露了模块级的 ``router``\\ （一个 "
+":class:`fastapi.APIRouter`），将会被自动发现。这涵盖了运维操作面：状态、缓存控制、L2 管理、配额和运行时重新配置。"
+
+#: ../../source/mp/http_api.rst:21
+msgid ""
+"**Shared \"common\" routes** — "
+"``lmcache/v1/multiprocess/http_apis/common_api.py`` aggregates every "
+"compatible router under ``lmcache/v1/internal_api_server/common/`` "
+"(skipping any module listed in ``_MP_INCOMPATIBLE_MODULES``, currently "
+"empty) and forwards them to the auto-discovery pipeline. These are the "
+"cross-server diagnostics shared with the vLLM-embedded API server "
+"(``/env``, ``/loglevel``, ``/metrics``, ``/threads``, ``/periodic-"
+"threads*``, ``/run_script``). Adding a new compatible module under "
+"``internal_api_server/common`` requires no wiring changes on the MP side."
+msgstr ""
+"**共享“公共”路由** — ``lmcache/v1/multiprocess/http_apis/common_api.py`` 聚合了 "
+"``lmcache/v1/internal_api_server/common/`` 下的每个兼容的 router（跳过任何列在 "
+"``_MP_INCOMPATIBLE_MODULES`` 中的模块，目前为空），并将它们转发到自动发现流水线。这些是与嵌入 vLLM 的 API "
+"服务器共享的跨服务器诊断（``/env``、``/loglevel``、``/metrics``、``/threads"
+"``、``/periodic-threads*``、``/run_script``）。在 "
+"``internal_api_server/common`` 下添加新的兼容模块无需在 MP 端进行任何改动。"
+
+#: ../../source/mp/http_api.rst:30
+msgid ""
+"**Re-exported version routes** — the basic-info group "
+"``lmcache/v1/multiprocess/http_apis/info_api.py`` includes the router "
+"from ``lmcache/v1/internal_api_server/vllm/version_api.py``, exposing "
+"``/version``, ``/lmc_version``, and ``/commit_id`` alongside ``/``, "
+"``/healthcheck`` and ``/status``."
+msgstr "**重新导出的版本路由** — 基本信息组 ``lmcache/v1/multiprocess/http_apis/info_api.py`` 包含来自 ``lmcache/v1/internal_api_server/vllm/version_api.py`` 的路由器，暴露 ``/version``、``/lmc_version`` 和 ``/commit_id``，以及 ``/``、``/healthcheck`` 和 ``/status``。"
+
+#: ../../source/mp/http_api.rst:41
+msgid "Server Configuration"
+msgstr "服务器配置"
+
+#: ../../source/mp/http_api.rst:47
+msgid "Argument"
+msgstr "参数"
+
+#: ../../source/mp/http_api.rst:48 ../../source/mp/http_api.rst:799
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/http_api.rst:49 ../../source/mp/http_api.rst:562
+#: ../../source/mp/http_api.rst:609 ../../source/mp/http_api.rst:722
+#: ../../source/mp/http_api.rst:800 ../../source/mp/http_api.rst:895
+#: ../../source/mp/http_api.rst:1029
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/http_api.rst:50
+msgid "``--http-host``"
+msgstr "``--http-host``"
+
+#: ../../source/mp/http_api.rst:51
+msgid "``0.0.0.0``"
+msgstr "``0.0.0.0``"
+
+#: ../../source/mp/http_api.rst:52
+msgid "Host to bind the HTTP server."
+msgstr "绑定 HTTP 服务器的主机。"
+
+#: ../../source/mp/http_api.rst:53
+msgid "``--http-port``"
+msgstr "``--http-port``"
+
+#: ../../source/mp/http_api.rst:54
+msgid "``8080``"
+msgstr "``8080``"
+
+#: ../../source/mp/http_api.rst:55
+msgid "Port to bind the HTTP server."
+msgstr "绑定 HTTP 服务器的端口。"
+
+#: ../../source/mp/http_api.rst:57
+msgid "Example:"
+msgstr "示例："
+
+#: ../../source/mp/http_api.rst:65
+msgid ""
+"All examples below assume the server is reachable at "
+"``http://localhost:8080``."
+msgstr "以下所有示例都假设服务器可以通过 ``http://localhost:8080`` 访问。"
+
+#: ../../source/mp/http_api.rst:69
+msgid "Endpoint Overview"
+msgstr "端点概述"
+
+#: ../../source/mp/http_api.rst:71
+msgid ""
+"The routes are grouped by purpose below. The operational surface (health,"
+" status, cache and storage control) lives at top-level paths; routes "
+"inherited from the shared ``internal_api_server`` package keep their "
+"original paths for compatibility with the vLLM-embedded API server."
+msgstr ""
+"下面的路由按目的分组。操作接口（健康检查、状态、缓存和存储控制）位于顶层路径；从共享的 ``internal_api_server`` "
+"包继承的路由保持其原始路径，以与嵌入的 vLLM API 服务器兼容。"
+
+#: ../../source/mp/http_api.rst:78
+msgid ""
+"Several handlers report failure in the response **body** rather than via "
+"a non-200 status code (e.g. ``DELETE /cache/objects`` returns ``200`` "
+"with ``ok=false``, and ``/periodic-threads-health`` returns ``200`` with "
+"``healthy=false``). The error-field name is also not uniform: "
+"``/healthcheck`` and ``/cache/clear`` use ``reason`` on failure, while "
+"``/status``, ``/config``, and ``/cache/checksums`` use ``error``. Per-"
+"endpoint details below are authoritative."
+msgstr "多个处理程序在响应 **主体** 中报告失败，而不是通过非 200 状态码（例如 ``DELETE /cache/objects`` 返回 ``200`` 和 ``ok=false``，而 ``/periodic-threads-health`` 返回 ``200`` 和 ``healthy=false``）。错误字段名称也不统一：``/healthcheck`` 和 ``/cache/clear`` 在失败时使用 ``reason``，而 ``/status``、``/config`` 和 ``/cache/checksums`` 使用 ``error``。每个端点的详细信息如下是权威的。"
+
+#: ../../source/mp/http_api.rst:86
+msgid "**Liveness and health**"
+msgstr "**存活性和健康**"
+
+#: ../../source/mp/http_api.rst:92 ../../source/mp/http_api.rst:108
+#: ../../source/mp/http_api.rst:139 ../../source/mp/http_api.rst:171
+#: ../../source/mp/http_api.rst:193 ../../source/mp/http_api.rst:211
+#: ../../source/mp/http_api.rst:227
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/mp/http_api.rst:93 ../../source/mp/http_api.rst:109
+#: ../../source/mp/http_api.rst:140 ../../source/mp/http_api.rst:172
+#: ../../source/mp/http_api.rst:194 ../../source/mp/http_api.rst:212
+#: ../../source/mp/http_api.rst:228
+msgid "Path"
+msgstr "路径"
+
+#: ../../source/mp/http_api.rst:94 ../../source/mp/http_api.rst:110
+#: ../../source/mp/http_api.rst:141 ../../source/mp/http_api.rst:173
+#: ../../source/mp/http_api.rst:195 ../../source/mp/http_api.rst:213
+#: ../../source/mp/http_api.rst:229
+msgid "Purpose"
+msgstr "目的"
+
+#: ../../source/mp/http_api.rst:95 ../../source/mp/http_api.rst:98
+#: ../../source/mp/http_api.rst:111 ../../source/mp/http_api.rst:115
+#: ../../source/mp/http_api.rst:119 ../../source/mp/http_api.rst:123
+#: ../../source/mp/http_api.rst:126 ../../source/mp/http_api.rst:129
+#: ../../source/mp/http_api.rst:142 ../../source/mp/http_api.rst:154
+#: ../../source/mp/http_api.rst:174 ../../source/mp/http_api.rst:180
+#: ../../source/mp/http_api.rst:196 ../../source/mp/http_api.rst:214
+#: ../../source/mp/http_api.rst:230 ../../source/mp/http_api.rst:233
+#: ../../source/mp/http_api.rst:236 ../../source/mp/http_api.rst:239
+#: ../../source/mp/http_api.rst:242 ../../source/mp/http_api.rst:245
+msgid "GET"
+msgstr "GET"
+
+#: ../../source/mp/http_api.rst:96
+msgid "``/``"
+msgstr "``/``"
+
+#: ../../source/mp/http_api.rst:97
+msgid "Static liveness ping (does not touch the engine)."
+msgstr "静态存活检测（不触及引擎）。"
+
+#: ../../source/mp/http_api.rst:99
+msgid "``/healthcheck``"
+msgstr "``/healthcheck``"
+
+#: ../../source/mp/http_api.rst:100
+msgid "K8s liveness/readiness probe; ``503`` until the engine is initialized."
+msgstr "K8s 存活/就绪探针；``503`` 直到引擎初始化完成。"
+
+#: ../../source/mp/http_api.rst:102
+msgid "**Inspection and status**"
+msgstr "**检查和状态**"
+
+#: ../../source/mp/http_api.rst:112
+msgid "``/status``"
+msgstr "``/status``"
+
+#: ../../source/mp/http_api.rst:113
+msgid ""
+"Detailed engine snapshot (L1, L2, registered contexts, sessions, prefetch"
+" jobs) for inspection and debugging."
+msgstr "用于检查和调试的详细引擎快照（L1、L2、注册的上下文、会话、预取作业）。"
+
+#: ../../source/mp/http_api.rst:116
+msgid "``/config``"
+msgstr "``/config``"
+
+#: ../../source/mp/http_api.rst:117
+msgid ""
+"Dump the merged server configuration objects (``mp``, "
+"``storage_manager``, ``observability``)."
+msgstr "转储合并的服务器配置对象（``mp``、``storage_manager``、``observability``）。"
+
+#: ../../source/mp/http_api.rst:120
+msgid "``/config/adapters``"
+msgstr "``/config/adapters``"
+
+#: ../../source/mp/http_api.rst:121
+msgid ""
+"Enumerate the live cache adapters (``type_name``, ``tier``, ``primary``, "
+"``reconfigurable``). Supersedes ``/reconfigure/backends``."
+msgstr "列出活动缓存适配器（``type_name``、``tier``、``primary``、``reconfigurable``）。取代 ``/reconfigure/backends``。"
+
+#: ../../source/mp/http_api.rst:124
+msgid "``/version``"
+msgstr "``/version``"
+
+#: ../../source/mp/http_api.rst:125
+msgid "Combined version string (``\"<version>-<commit_id>\"``)."
+msgstr "组合版本字符串 (``\\\"<version>-<commit_id>\\\"``)。"
+
+#: ../../source/mp/http_api.rst:127
+msgid "``/lmc_version``"
+msgstr "``/lmc_version``"
+
+#: ../../source/mp/http_api.rst:128
+msgid "LMCache package version string."
+msgstr "LMCache 包版本字符串。"
+
+#: ../../source/mp/http_api.rst:130
+msgid "``/commit_id``"
+msgstr "``/commit_id``"
+
+#: ../../source/mp/http_api.rst:131
+msgid "Build commit id."
+msgstr "构建提交 ID。"
+
+#: ../../source/mp/http_api.rst:133
+msgid "**Cache management**"
+msgstr "**缓存管理**"
+
+#: ../../source/mp/http_api.rst:143 ../../source/mp/http_api.rst:147
+msgid "``/cache/objects``"
+msgstr "``/cache/objects``"
+
+#: ../../source/mp/http_api.rst:144
+msgid ""
+"Paginate objects resident in a tier/adapter (query: ``tier``, "
+"``adapter``, ``model_name``, ``page_size``, ``page_token``)."
+msgstr "对驻留在某个层/适配器中的对象进行分页（查询：``tier``、``adapter``、``model_name``、``page_size``、``page_token``）。"
+
+#: ../../source/mp/http_api.rst:146 ../../source/mp/http_api.rst:183
+msgid "DELETE"
+msgstr "DELETE"
+
+#: ../../source/mp/http_api.rst:148
+msgid ""
+"Delete a caller-supplied list of object keys (body: ``tier``, "
+"``adapter``, ``keys``)."
+msgstr "删除调用者提供的对象键列表（主体：``tier``，``adapter``，``keys``）。"
+
+#: ../../source/mp/http_api.rst:150 ../../source/mp/http_api.rst:157
+#: ../../source/mp/http_api.rst:160 ../../source/mp/http_api.rst:201
+#: ../../source/mp/http_api.rst:217 ../../source/mp/http_api.rst:248
+msgid "POST"
+msgstr "POST"
+
+#: ../../source/mp/http_api.rst:151
+msgid "``/cache/prefetches``"
+msgstr "``/cache/prefetches``"
+
+#: ../../source/mp/http_api.rst:152
+msgid ""
+"Warm a node's L1 by loading a token sequence from L2 ahead of traffic; "
+"returns a ``request_id``."
+msgstr "通过从 L2 提前加载令牌序列来预热节点的 L1；返回 ``request_id``。"
+
+#: ../../source/mp/http_api.rst:155
+#, python-brace-format
+msgid "``/cache/prefetches/{request_id}``"
+msgstr "``/cache/prefetches/{request_id}``"
+
+#: ../../source/mp/http_api.rst:156
+msgid "Poll a submitted warm prefetch (``pending`` / ``completed``)."
+msgstr "轮询已提交的热预取（``待处理`` / ``已完成``）。"
+
+#: ../../source/mp/http_api.rst:158
+msgid "``/cache/clear``"
+msgstr "``/cache/clear``"
+
+#: ../../source/mp/http_api.rst:159
+msgid "Force-clear a tier's resident cache (body: ``tier`` = ``l1``, ``force``)."
+msgstr "强制清除某个层的常驻缓存（请求体：``tier`` = ``l1``，``force``）。"
+
+#: ../../source/mp/http_api.rst:161
+msgid "``/cache/checksums``"
+msgstr "``/cache/checksums``"
+
+#: ../../source/mp/http_api.rst:162
+msgid ""
+"Compute MD5 checksums over KV cache blocks (diagnostics / round-trip "
+"integrity checks)."
+msgstr "计算 KV Cache 块的 MD5 校验和（诊断 / 往返完整性检查）。"
+
+#: ../../source/mp/http_api.rst:165
+msgid "**Quota management**"
+msgstr "**配额管理**"
+
+#: ../../source/mp/http_api.rst:175
+msgid "``/quota``"
+msgstr "``/quota``"
+
+#: ../../source/mp/http_api.rst:176
+msgid "List every registered ``cache_salt`` quota with live usage."
+msgstr "列出每个注册的 ``cache_salt`` 配额及其实时使用情况。"
+
+#: ../../source/mp/http_api.rst:177
+msgid "PUT"
+msgstr "PUT"
+
+#: ../../source/mp/http_api.rst:178 ../../source/mp/http_api.rst:181
+#: ../../source/mp/http_api.rst:184
+#, python-brace-format
+msgid "``/quota/{cache_salt}``"
+msgstr "``/quota/{cache_salt}``"
+
+#: ../../source/mp/http_api.rst:179
+msgid "Set or update the quota (in GB) for a ``cache_salt``."
+msgstr "设置或更新 ``cache_salt`` 的配额（以 GB 为单位）。"
+
+#: ../../source/mp/http_api.rst:182
+msgid "Read the quota and live usage for a single ``cache_salt``."
+msgstr "读取单个 ``cache_salt`` 的配额和实时使用情况。"
+
+#: ../../source/mp/http_api.rst:185
+msgid "Remove a ``cache_salt``'s quota entry (its data is evicted next cycle)."
+msgstr "移除 ``cache_salt`` 的配额条目（其数据将在下一个周期被逐出）。"
+
+#: ../../source/mp/http_api.rst:187
+msgid "**Runtime L2 reconfiguration**"
+msgstr "**运行时 L2 重新配置**"
+
+#: ../../source/mp/http_api.rst:197
+#, python-brace-format
+msgid "``/reconfigure/{backend}/status``"
+msgstr "``/reconfigure/{backend}/status``"
+
+#: ../../source/mp/http_api.rst:198
+msgid ""
+"Report runtime-manageable L2 adapters for one backend type. (To discover "
+"reconfigurable backends, use ``GET /config/adapters`` and read the "
+"``reconfigurable`` flag.)"
+msgstr "报告一个后端类型的可运行管理 L2 适配器。 （要发现可重新配置的后端，请使用 ``GET /config/adapters`` 并读取 ``reconfigurable`` 标志。）"
+
+#: ../../source/mp/http_api.rst:202
+#, python-brace-format
+msgid "``/reconfigure/{backend}/{operation}``"
+msgstr "``/reconfigure/{backend}/{operation}``"
+
+#: ../../source/mp/http_api.rst:203
+msgid "Apply one runtime reconfiguration operation to a backend adapter."
+msgstr "对后端适配器应用一个运行时重新配置操作。"
+
+#: ../../source/mp/http_api.rst:205
+msgid "**Observability**"
+msgstr "**可观察性**"
+
+#: ../../source/mp/http_api.rst:215
+msgid "``/metrics``"
+msgstr "``/metrics``"
+
+#: ../../source/mp/http_api.rst:216
+msgid "Prometheus exposition format."
+msgstr "Prometheus 展示格式。"
+
+#: ../../source/mp/http_api.rst:218
+msgid "``/metrics/reset``"
+msgstr "``/metrics/reset``"
+
+#: ../../source/mp/http_api.rst:219
+msgid "Reset all observability metrics to their initial state."
+msgstr "将所有可观察性指标重置为初始状态。"
+
+#: ../../source/mp/http_api.rst:221
+msgid "**Diagnostics and debugging**"
+msgstr "**诊断与调试**"
+
+#: ../../source/mp/http_api.rst:231
+msgid "``/loglevel``"
+msgstr "``/loglevel``"
+
+#: ../../source/mp/http_api.rst:232
+msgid "List or inspect logger levels; also accepts ``level`` to mutate one."
+msgstr "列出或检查日志记录器级别；也接受 ``level`` 来修改一个。"
+
+#: ../../source/mp/http_api.rst:234
+msgid "``/threads``"
+msgstr "``/threads``"
+
+#: ../../source/mp/http_api.rst:235
+msgid "Enumerate active Python threads and their stack traces."
+msgstr "列出活动的 Python 线程及其堆栈跟踪。"
+
+#: ../../source/mp/http_api.rst:237
+msgid "``/periodic-threads``"
+msgstr "``/periodic-threads``"
+
+#: ../../source/mp/http_api.rst:238
+msgid "List registered periodic threads with summary counts."
+msgstr "列出注册的周期性线程及其摘要计数。"
+
+#: ../../source/mp/http_api.rst:240
+#, python-brace-format
+msgid "``/periodic-threads/{thread_name}``"
+msgstr "``/periodic-threads/{thread_name}``"
+
+#: ../../source/mp/http_api.rst:241
+msgid "Detailed status for a single periodic thread."
+msgstr "单个周期线程的详细状态。"
+
+#: ../../source/mp/http_api.rst:243
+msgid "``/periodic-threads-health``"
+msgstr "``/periodic-threads-health``"
+
+#: ../../source/mp/http_api.rst:244
+msgid "Quick health check for critical/high-level periodic threads."
+msgstr "对关键/高层周期线程的快速健康检查。"
+
+#: ../../source/mp/http_api.rst:246
+msgid "``/env``"
+msgstr "``/env``"
+
+#: ../../source/mp/http_api.rst:247
+msgid "Dump process environment variables (JSON body, ``text/plain``)."
+msgstr "转储进程环境变量（JSON主体，``text/plain``）。"
+
+#: ../../source/mp/http_api.rst:249
+msgid "``/run_script``"
+msgstr "``/run_script``"
+
+#: ../../source/mp/http_api.rst:250
+msgid "Execute an uploaded Python script in a restricted sandbox."
+msgstr "在受限的沙箱中执行上传的 Python 脚本。"
+
+#: ../../source/mp/http_api.rst:253
+msgid "Liveness and Health"
+msgstr "存活性和健康状态"
+
+#: ../../source/mp/http_api.rst:256
+msgid "``GET /``"
+msgstr "``GET /``"
+
+#: ../../source/mp/http_api.rst:258
+msgid ""
+"Basic liveness check. Returns a static payload indicating the HTTP server"
+" is running; it does **not** touch the cache engine. Use ``/healthcheck``"
+" instead for probes that also verify the engine is initialized."
+msgstr ""
+"基本的存活检查。返回一个静态负载，指示 HTTP 服务器正在运行；它\\ **不**\\ 会触及缓存引擎。对于还验证引擎是否已初始化的探测，请使用"
+" ``/healthcheck``。"
+
+#: ../../source/mp/http_api.rst:262 ../../source/mp/http_api.rst:291
+#: ../../source/mp/http_api.rst:351 ../../source/mp/http_api.rst:427
+#: ../../source/mp/http_api.rst:475 ../../source/mp/http_api.rst:522
+#: ../../source/mp/http_api.rst:573 ../../source/mp/http_api.rst:624
+#: ../../source/mp/http_api.rst:750 ../../source/mp/http_api.rst:824
+#: ../../source/mp/http_api.rst:1034 ../../source/mp/http_api.rst:1063
+#: ../../source/mp/http_api.rst:1102 ../../source/mp/http_api.rst:1128
+#: ../../source/mp/http_api.rst:1187 ../../source/mp/http_api.rst:1256
+#: ../../source/mp/http_api.rst:1444 ../../source/mp/http_api.rst:1495
+#: ../../source/mp/http_api.rst:1537
+msgid "**Response** (``200 OK``):"
+msgstr "**响应** (``200 OK``):"
+
+#: ../../source/mp/http_api.rst:271 ../../source/mp/http_api.rst:308
+#: ../../source/mp/http_api.rst:406 ../../source/mp/http_api.rst:454
+#: ../../source/mp/http_api.rst:493 ../../source/mp/http_api.rst:528
+#: ../../source/mp/http_api.rst:579 ../../source/mp/http_api.rst:640
+#: ../../source/mp/http_api.rst:763 ../../source/mp/http_api.rst:847
+#: ../../source/mp/http_api.rst:925 ../../source/mp/http_api.rst:973
+#: ../../source/mp/http_api.rst:1040 ../../source/mp/http_api.rst:1080
+#: ../../source/mp/http_api.rst:1111 ../../source/mp/http_api.rst:1142
+#: ../../source/mp/http_api.rst:1203 ../../source/mp/http_api.rst:1270
+#: ../../source/mp/http_api.rst:1305 ../../source/mp/http_api.rst:1328
+#: ../../source/mp/http_api.rst:1369 ../../source/mp/http_api.rst:1414
+#: ../../source/mp/http_api.rst:1476 ../../source/mp/http_api.rst:1518
+#: ../../source/mp/http_api.rst:1564 ../../source/mp/http_api.rst:1598
+#: ../../source/mp/http_api.rst:1634
+msgid "**HTTP status codes:**"
+msgstr "**HTTP 状态码:**"
+
+#: ../../source/mp/http_api.rst:273
+msgid "``200``: server is alive (unconditional; does not touch the engine)."
+msgstr "``200``: 服务器正常运行（无条件；不影响引擎）。"
+
+#: ../../source/mp/http_api.rst:275 ../../source/mp/http_api.rst:313
+#: ../../source/mp/http_api.rst:411 ../../source/mp/http_api.rst:459
+#: ../../source/mp/http_api.rst:498 ../../source/mp/http_api.rst:585
+#: ../../source/mp/http_api.rst:651 ../../source/mp/http_api.rst:774
+#: ../../source/mp/http_api.rst:935 ../../source/mp/http_api.rst:980
+#: ../../source/mp/http_api.rst:1047 ../../source/mp/http_api.rst:1086
+#: ../../source/mp/http_api.rst:1117 ../../source/mp/http_api.rst:1147
+#: ../../source/mp/http_api.rst:1209 ../../source/mp/http_api.rst:1280
+#: ../../source/mp/http_api.rst:1309 ../../source/mp/http_api.rst:1332
+#: ../../source/mp/http_api.rst:1418 ../../source/mp/http_api.rst:1481
+#: ../../source/mp/http_api.rst:1523 ../../source/mp/http_api.rst:1569
+#: ../../source/mp/http_api.rst:1602 ../../source/mp/http_api.rst:1641
+msgid "**Example:**"
+msgstr "**示例：**"
+
+#: ../../source/mp/http_api.rst:282
+msgid "``GET /healthcheck``"
+msgstr "``GET /healthcheck``"
+
+#: ../../source/mp/http_api.rst:284
+msgid ""
+"Health check endpoint suitable for Kubernetes liveness and readiness "
+"probes. A ``200`` response means the HTTP server is alive **and** the MP "
+"cache engine object is wired onto ``app.state``. A ``503`` response "
+"indicates the engine is not yet present (still initializing, or failed to"
+" initialize). The check verifies that the engine attribute is set; it "
+"does not call into the engine to assert deeper liveness."
+msgstr ""
+"健康检查端点适用于 Kubernetes 的存活和就绪探针。``200`` 响应意味着 HTTP 服务器处于活动状态 **并且** MP "
+"缓存引擎对象已连接到 ``app.state``。``503`` "
+"响应表示引擎尚未存在（仍在初始化中，或初始化失败）。该检查验证引擎属性是否已设置；它不会调用引擎以确认更深层次的存活状态。"
+
+#: ../../source/mp/http_api.rst:299
+msgid "**Response** (``503 Service Unavailable``):"
+msgstr "**响应** (``503 服务不可用``):"
+
+#: ../../source/mp/http_api.rst:310
+msgid "``200``: engine is wired onto ``app.state`` (healthy)."
+msgstr "``200``: 引擎已连接到 ``app.state`` (正常)。"
+
+#: ../../source/mp/http_api.rst:311
+msgid ""
+"``503``: engine not initialized (still starting up, or failed to "
+"initialize)."
+msgstr "``503``: 引擎未初始化（仍在启动中，或初始化失败）。"
+
+#: ../../source/mp/http_api.rst:319
+msgid "**Kubernetes probe snippet:**"
+msgstr "**Kubernetes 探针代码片段:**"
+
+#: ../../source/mp/http_api.rst:337
+msgid "Inspection and Status"
+msgstr "检查和状态"
+
+#: ../../source/mp/http_api.rst:340
+msgid "``GET /status``"
+msgstr "``GET /status``"
+
+#: ../../source/mp/http_api.rst:342
+msgid ""
+"Returns a detailed snapshot of the MP engine's internal state. The "
+"payload is assembled by ``MPCacheServer.report_status()``: a fixed set of"
+" engine-level fields, the full storage-manager status, plus whatever keys"
+" each loaded module contributes (so the exact key set depends on which "
+"modules are active — ``registered_gpu_ids`` / ``cache_context_meta`` come"
+" from the transfer module, ``active_prefetch_jobs`` from the lookup "
+"module, and blend modes add their own fields). Intended for operators and"
+" debugging, not for monitoring (use Prometheus metrics for time-series "
+"data — see :doc:`observability/index`)."
+msgstr ""
+"返回 MP 引擎内部状态的详细快照。有效负载由 ``MPCacheServer.report_status()`` "
+"组装：一组固定的引擎级字段、完整的存储管理器状态，以及每个加载模块贡献的键（因此确切的键集取决于哪些模块处于活动状态 — "
+"``registered_gpu_ids`` / ``cache_context_meta`` "
+"来自传输模块，``active_prefetch_jobs`` 来自查找模块，混合模式添加它们自己的字段）。旨在供操作员和调试使用，而非监控（使用"
+" Prometheus 指标获取时间序列数据 — 参见 :doc:`observability/index`）。"
+
+#: ../../source/mp/http_api.rst:397
+msgid ""
+"**Response** (``503 Service Unavailable``) when the engine has not yet "
+"been initialized:"
+msgstr "**响应** (``503 服务不可用``) 当引擎尚未初始化时："
+
+#: ../../source/mp/http_api.rst:408
+msgid "``200``: status snapshot returned."
+msgstr "``200``: 状态快照已返回。"
+
+#: ../../source/mp/http_api.rst:409 ../../source/mp/http_api.rst:649
+msgid "``503``: engine not yet initialized on ``app.state``."
+msgstr "``503``: 引擎尚未在 ``app.state`` 上初始化。"
+
+#: ../../source/mp/http_api.rst:418
+msgid "``GET /config``"
+msgstr "``GET /config``"
+
+#: ../../source/mp/http_api.rst:420
+msgid ""
+"Returns every server-side configuration object registered on "
+"``app.state.configs`` (typically ``mp``, ``storage_manager`` and "
+"``observability``) as a single indented JSON document. Dataclasses are "
+"serialized via ``safe_asdict``; other values go through "
+"``make_json_safe``. Useful for confirming what the process actually "
+"loaded — including environment overrides — without restarting."
+msgstr ""
+"以单一缩进 JSON 文档返回注册在 ``app.state.configs`` 上的全部服务器端配置对象（通常包括 ``mp``\\ 、\\ "
+"``storage_manager`` 和 ``observability``\\ ）。数据类通过 ``safe_asdict`` "
+"序列化；其他值通过 ``make_json_safe`` 处理。可用于确认进程实际加载的配置内容（含环境变量覆盖），无需重启服务。"
+
+#: ../../source/mp/http_api.rst:445
+msgid ""
+"**Response** (``503 Service Unavailable``) when configs are not wired "
+"onto ``app.state`` yet:"
+msgstr "**响应**\\ （\\ ``503 服务不可用``\\ ），当配置尚未连接到 ``app.state`` 时："
+
+#: ../../source/mp/http_api.rst:456
+msgid "``200``: configuration document returned."
+msgstr "``200``: 配置文档已返回。"
+
+#: ../../source/mp/http_api.rst:457
+msgid "``503``: configs not yet wired onto ``app.state``."
+msgstr "``503``: 配置尚未连接到 ``app.state``。"
+
+#: ../../source/mp/http_api.rst:466
+msgid "``GET /config/adapters``"
+msgstr "``GET /config/adapters``"
+
+#: ../../source/mp/http_api.rst:468
+msgid ""
+"Enumerate every L2 adapter the engine has loaded, in configuration order."
+" Which storage backends are loaded is a configuration-inspection concern,"
+" so this lives in the config group rather than under ``/cache``. This is "
+"the single live adapter listing; it supersedes the old ``GET "
+"/reconfigure/backends`` (the reconfigurable backends are the "
+"``type_name`` values whose ``reconfigurable`` flag is ``true``)."
+msgstr "列出引擎已加载的每个 L2 适配器，按配置顺序排列。加载了哪些存储后端是配置检查的内容，因此它位于配置组中，而不是在 ``/cache`` 下。这是唯一的活动适配器列表；它取代了旧的 ``GET /reconfigure/backends``（可重新配置的后端是 ``type_name`` 值，其 ``reconfigurable`` 标志为 ``true``）。"
+
+#: ../../source/mp/http_api.rst:486
+#, python-brace-format
+msgid ""
+"``primary`` is ``true`` only on the first entry. ``reconfigurable`` is "
+"``true`` for adapters that accept ``/reconfigure`` operations — pass that"
+" adapter's ``type_name`` as the ``{backend}`` path parameter to ``GET "
+"/reconfigure/{backend}/status`` and the reconfigure operations. An engine"
+" that has no L2 backends returns ``{\"adapters\": []}`` (still ``200`` — "
+"the engine is initialized, it just has no L2 storage)."
+msgstr "``primary`` 仅在第一个条目上为 ``true``。``reconfigurable`` 对于接受 ``/reconfigure`` 操作的适配器为 ``true`` — 将该适配器的 ``type_name`` 作为 ``{backend}`` 路径参数传递给 ``GET /reconfigure/{backend}/status`` 和重新配置操作。没有 L2 后端的引擎返回 ``{\\\"adapters\\\": []}``（仍然是 ``200`` — 引擎已初始化，只是没有 L2 存储）。"
+
+#: ../../source/mp/http_api.rst:495
+msgid "``200``: success (including the no-adapters case)."
+msgstr "``200``: 成功（包括无适配器的情况）。"
+
+#: ../../source/mp/http_api.rst:496 ../../source/mp/http_api.rst:933
+#: ../../source/mp/http_api.rst:978 ../../source/mp/http_api.rst:1045
+#: ../../source/mp/http_api.rst:1084 ../../source/mp/http_api.rst:1115
+#: ../../source/mp/http_api.rst:1145 ../../source/mp/http_api.rst:1207
+#: ../../source/mp/http_api.rst:1278
+msgid "``503``: engine not initialized."
+msgstr "``503``: 引擎未初始化。"
+
+#: ../../source/mp/http_api.rst:505
+msgid "``GET /version``, ``GET /lmc_version``, ``GET /commit_id``"
+msgstr "``GET /version``, ``GET /lmc_version``, ``GET /commit_id``"
+
+#: ../../source/mp/http_api.rst:507
+msgid "Version descriptors. Each returns a bare JSON **string** (not an object):"
+msgstr "版本描述符。每个返回一个裸 JSON **字符串**\\ （而不是对象）："
+
+#: ../../source/mp/http_api.rst:509
+msgid ""
+"``GET /version`` — the combined descriptor from "
+"``lmcache.utils.get_version()``, formatted ``\"<version>-<commit_id>\"`` "
+"(e.g. ``\"0.3.1-ca79ea33\"``). On a source checkout without build-time "
+"version metadata, each missing component falls back to the literal "
+"``\"NA\"`` (so a metadata-less build returns ``\"NA-NA\"``)."
+msgstr ""
+"``GET /version`` — 来自 ``lmcache.utils.get_version()`` 的组合描述符，格式为 "
+"``\\\"<version>-<commit_id>\\\"``\\ （例如 "
+"``\\\"0.3.1-ca79ea33\\\"``）。在没有构建时版本元数据的源代码检出中，每个缺失的组件将回退为字面值 "
+"``\\\"NA\\\"``\\ （因此没有元数据的构建返回 ``\\\"NA-NA\\\"``）。"
+
+#: ../../source/mp/http_api.rst:514
+msgid ""
+"``GET /lmc_version`` — the raw package version string "
+"(``lmcache.utils.VERSION``); empty string ``\"\"`` when the generated "
+"``lmcache._version`` module is absent."
+msgstr ""
+"``GET /lmc_version`` — 原始包版本字符串 (``lmcache.utils.VERSION``)；当生成的 "
+"``lmcache._version`` 模块缺失时返回空字符串 ``\\\"\\\"``。"
+
+#: ../../source/mp/http_api.rst:517
+msgid ""
+"``GET /commit_id`` — the git commit id baked into the build "
+"(``lmcache.utils.COMMIT_ID``); empty string ``\"\"`` when unavailable."
+msgstr ""
+"``GET /commit_id`` — 构建中嵌入的 git 提交 ID "
+"(``lmcache.utils.COMMIT_ID``)；当不可用时为空字符串 ``\\\"\\\"``。"
+
+#: ../../source/mp/http_api.rst:520
+msgid "All three are unconditional ``200 OK``."
+msgstr "这三者都是无条件的 ``200 OK``。"
+
+#: ../../source/mp/http_api.rst:530
+msgid "``200``: version string returned (unconditional for all three routes)."
+msgstr "``200``: 返回的版本字符串（对所有三个路由无条件）。"
+
+#: ../../source/mp/http_api.rst:532 ../../source/mp/http_api.rst:1374
+msgid "**Examples:**"
+msgstr "**示例：**"
+
+#: ../../source/mp/http_api.rst:541
+msgid "Cache Management"
+msgstr "缓存管理"
+
+#: ../../source/mp/http_api.rst:544
+msgid "``POST /cache/clear``"
+msgstr "``POST /cache/clear``"
+
+#: ../../source/mp/http_api.rst:546
+msgid ""
+"Force-clears **all** KV cache data currently held in a tier (today "
+"``l1``)."
+msgstr "强制清除当前在某个层级（今天为 ``l1``）中持有的 **所有** KV 缓存数据。"
+
+#: ../../source/mp/http_api.rst:550
+msgid ""
+"This endpoint is destructive and bypasses read/write locks. In-flight "
+"store or prefetch operations may be corrupted. Use only when the server "
+"is idle, or when recovering from a known-bad cache state."
+msgstr "此端点为破坏性操作，会绕过读/写锁。正在进行的存储或预取操作可能因此损坏。仅在服务器空闲时，或在已知缓存状态异常需要恢复时使用。"
+
+#: ../../source/mp/http_api.rst:554
+msgid ""
+"**Request body:** optional -- an absent (or empty) body uses the defaults"
+" below."
+msgstr "**请求体：** 可选 -- 缺失（或空）体将使用以下默认值。"
+
+#: ../../source/mp/http_api.rst:560 ../../source/mp/http_api.rst:607
+#: ../../source/mp/http_api.rst:720 ../../source/mp/http_api.rst:893
+#: ../../source/mp/http_api.rst:1027
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/mp/http_api.rst:561 ../../source/mp/http_api.rst:721
+#: ../../source/mp/http_api.rst:894 ../../source/mp/http_api.rst:1028
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/mp/http_api.rst:563 ../../source/mp/http_api.rst:727
+msgid "``tier``"
+msgstr "``tier``"
+
+#: ../../source/mp/http_api.rst:564 ../../source/mp/http_api.rst:728
+#: ../../source/mp/http_api.rst:731 ../../source/mp/http_api.rst:897
+#: ../../source/mp/http_api.rst:909
+msgid "string"
+msgstr "字符串"
+
+#: ../../source/mp/http_api.rst:565
+msgid ""
+"Optional (default ``l1``). Tier to clear; today only ``l1`` is supported."
+" Any other value returns ``400``."
+msgstr "可选（默认 ``l1``）。要清除的层级；目前仅支持 ``l1``。任何其他值将返回 ``400``。"
+
+#: ../../source/mp/http_api.rst:567
+msgid "``force``"
+msgstr "``force``"
+
+#: ../../source/mp/http_api.rst:568
+msgid "bool"
+msgstr "布尔值"
+
+#: ../../source/mp/http_api.rst:569
+msgid ""
+"Optional (default ``true``). Currently accepted but **not honored** -- "
+"the clear always force-clears (active locks are ignored) regardless of "
+"this value."
+msgstr "可选（默认 ``true``）。当前被接受但 **不被遵循** -- 清除操作始终强制清除（活动锁被忽略），无论该值如何。"
+
+#: ../../source/mp/http_api.rst:581
+msgid "``200``: tier cleared."
+msgstr "``200``: 层已清除。"
+
+#: ../../source/mp/http_api.rst:582
+msgid "``400``: unsupported ``tier`` (anything other than ``l1``)."
+msgstr "``400``: 不支持的 ``tier``（除了 ``l1`` 以外的任何内容）。"
+
+#: ../../source/mp/http_api.rst:583
+#, python-brace-format
+msgid ""
+"``503``: server not initialized (``{\"detail\": \"server not "
+"initialized\"}``)."
+msgstr "``503``: 服务器未初始化 (``{\\\"detail\\\": \\\"服务器未初始化\\\"}``)。"
+
+#: ../../source/mp/http_api.rst:593
+msgid "``POST /cache/checksums``"
+msgstr "``POST /cache/checksums``"
+
+#: ../../source/mp/http_api.rst:595
+msgid ""
+"Compute MD5 checksums over the engine KV cache, grouped ``chunk_size`` "
+"blocks per hashed chunk. MP mode addresses KV storage by block IDs "
+"natively (the same units used by ``STORE`` / ``RETRIEVE``), so the "
+"endpoint is fully block-centric. Intended for diagnostics and round-trip "
+"integrity checks from ``lmcache bench server`` -- not for the inference "
+"data path."
+msgstr "计算引擎 KV Cache 的 MD5 校验和，每个哈希块分组为 ``chunk_size`` 块。MP 模式通过块 ID 原生地访问 KV 存储（与 ``STORE`` / ``RETRIEVE`` 使用的单位相同），因此该端点完全以块为中心。旨在用于诊断和来自 ``lmcache bench server`` 的往返完整性检查——不用于推理数据路径。"
+
+#: ../../source/mp/http_api.rst:601 ../../source/mp/http_api.rst:714
+#: ../../source/mp/http_api.rst:887 ../../source/mp/http_api.rst:1021
+msgid "**Request body:**"
+msgstr "**请求主体：**"
+
+#: ../../source/mp/http_api.rst:608
+msgid "Required"
+msgstr "必需的"
+
+#: ../../source/mp/http_api.rst:610
+msgid "``block_ids``"
+msgstr "``block_ids``"
+
+#: ../../source/mp/http_api.rst:611 ../../source/mp/http_api.rst:614
+msgid "yes"
+msgstr "是"
+
+#: ../../source/mp/http_api.rst:612
+msgid "Engine block IDs as a JSON list of ints, e.g. ``[0, 1, 2, 3]``."
+msgstr "引擎块 ID 作为整数的 JSON 列表，例如 ``[0, 1, 2, 3]``。"
+
+#: ../../source/mp/http_api.rst:613
+msgid "``chunk_size``"
+msgstr "``chunk_size``"
+
+#: ../../source/mp/http_api.rst:615
+msgid "Positive integer — number of blocks per hashed chunk."
+msgstr "正整数 — 每个哈希块的块数。"
+
+#: ../../source/mp/http_api.rst:616
+msgid "``instance_id``"
+msgstr "``instance_id``"
+
+#: ../../source/mp/http_api.rst:617
+msgid "no (default ``0``)"
+msgstr "否（默认 ``0``\\ ）"
+
+#: ../../source/mp/http_api.rst:618
+msgid "Registered KV context ID on the engine."
+msgstr "引擎上注册的 KV 上下文 ID。"
+
+#: ../../source/mp/http_api.rst:619
+msgid "``layerwise``"
+msgstr "``layerwise``"
+
+#: ../../source/mp/http_api.rst:620
+msgid "no (default ``false``)"
+msgstr "否（默认 ``false``\\ ）"
+
+#: ../../source/mp/http_api.rst:621
+msgid ""
+"If ``true``, return per-layer checksums keyed by ``\"layer_<idx>\"``; "
+"otherwise a single aggregated digest per chunk over all layers."
+msgstr "如果为 ``true``\\ ，则返回按 ``\"layer_<idx>\"`` 键入的逐层校验和；否则返回每个块的所有层的单个聚合摘要。"
+
+#: ../../source/mp/http_api.rst:637
+msgid ""
+"When ``layerwise=true``, ``chunk_checksums`` is a dict keyed by "
+"``\"layer_<idx>\"`` whose values are per-layer lists."
+msgstr ""
+"当 ``layerwise=true`` 时，\\ ``chunk_checksums`` 是一个以 ``\"layer_<idx>\"`` "
+"为键的字典，其值是逐层列表。"
+
+#: ../../source/mp/http_api.rst:642 ../../source/mp/http_api.rst:849
+msgid "``200``: success."
+msgstr "``200``: 成功。"
+
+#: ../../source/mp/http_api.rst:643
+msgid "``400``: ``block_ids`` empty, or ``chunk_size`` missing or non-positive."
+msgstr "``400``: ``block_ids`` 为空，或者 ``chunk_size`` 缺失或非正数。"
+
+#: ../../source/mp/http_api.rst:644
+msgid ""
+"``404``: ``instance_id`` not registered, or the registered KV tensors are"
+" empty."
+msgstr "``404``: ``instance_id`` 未注册，或者注册的 KV 张量为空。"
+
+#: ../../source/mp/http_api.rst:646
+msgid ""
+"``501``: engine has no ``cache_contexts``, or the KV format is not "
+"supported by this endpoint (page-buffer-fused and cross-layer layouts are"
+" declined until a real need appears)."
+msgstr "``501``: 引擎没有 ``cache_contexts``\\ ，或者该端点不支持 KV 格式（页面缓冲融合和跨层布局在真正需要之前被拒绝）。"
+
+#: ../../source/mp/http_api.rst:662
+msgid "Cache Objects And Prefetch"
+msgstr "缓存对象和预取"
+
+#: ../../source/mp/http_api.rst:664
+msgid ""
+"Two endpoints — ``DELETE /cache/objects`` and ``GET /cache/objects`` — "
+"let operators purge keys from a configured cache backend and enumerate "
+"what is currently resident. (To enumerate the configured backends "
+"themselves, use ``GET /config/adapters`` in the config group.)"
+msgstr "两个端点 — ``DELETE /cache/objects`` 和 ``GET /cache/objects`` — 允许操作员从配置的缓存后端中清除键并列举当前驻留的内容。（要列举配置的后端本身，请在配置组中使用 ``GET /config/adapters``。）"
+
+#: ../../source/mp/http_api.rst:669
+#, python-brace-format
+msgid ""
+"A further pair — ``POST /cache/prefetches`` and ``GET "
+"/cache/prefetches/{request_id}`` — lets an operator (or the coordinator) "
+"**pre-warm** a node's L1 from L2 ahead of traffic and poll the load to "
+"completion; they are documented at the end of this section. The "
+"coordinator exposes an ``instance_id``-routed variant of both — see "
+":doc:`coordinator`."
+msgstr "另一对 — ``POST /cache/prefetches`` 和 ``GET /cache/prefetches/{request_id}`` — 允许操作员（或协调者）**预热**节点的 L1 以便在流量到来之前从 L2 加载，并轮询加载直到完成；它们在本节末尾有文档说明。协调者提供了一个基于 ``instance_id`` 的变体 — 参见 :doc:`coordinator`。"
+
+#: ../../source/mp/http_api.rst:676
+msgid ""
+"Both object endpoints take an optional ``adapter`` selector — a query "
+"parameter on ``GET /cache/objects`` (``?adapter=<type_name>``) and a body"
+" field on ``DELETE /cache/objects``. Omit it to target the **primary** "
+"(first-configured) adapter. When multiple adapters share a ``type_name``,"
+" the first match wins. Use ``GET /config/adapters`` to learn the valid "
+"selectors."
+msgstr "两个对象端点都接受一个可选的 ``adapter`` 选择器 — 在 ``GET /cache/objects`` 上的查询参数（``?adapter=<type_name>``）和在 ``DELETE /cache/objects`` 上的主体字段。省略它将针对 **主要**（首次配置的）适配器。当多个适配器共享同一个 ``type_name`` 时，第一个匹配的适配器将生效。使用 ``GET /config/adapters`` 来了解有效的选择器。"
+
+#: ../../source/mp/http_api.rst:683
+msgid ""
+"Both are intended for operator / admin workflows (\"purge this user's "
+"keys\", \"show me what's resident\", \"garbage-collect orphans after a "
+"rename\"). They are **not** on the inference data path."
+msgstr "这两个接口旨在用于操作员/管理员工作流程（“清除该用户的键”，“显示当前驻留的内容”，“在重命名后收集孤儿”）。它们**不**在推理数据路径上。"
+
+#: ../../source/mp/http_api.rst:687
+msgid ""
+"L1 is intentionally not touched. Keys deleted from L2 may still return "
+"from L1 until the L1 eviction controller expires them naturally; callers "
+"that need an L1+L2 purge should layer their own L1 invalidation or wait "
+"for natural L1 eviction."
+msgstr ""
+"L1 被故意不触及。从 L2 删除的键可能仍会从 L1 返回，直到 L1 逐出控制器自然过期；需要 L1+L2 清除的调用者应该自行分层 L1 "
+"失效或等待自然 L1 逐出。"
+
+#: ../../source/mp/http_api.rst:692
+msgid ""
+"The coordinator's eviction loop uses ``DELETE /cache/objects`` "
+"automatically (see :doc:`coordinator` — \"L2 usage tracking and "
+"eviction\"); the ``GET /cache/objects`` endpoint also powers the "
+"coordinator's startup resync. Manual ``curl`` usage is reserved for ad-"
+"hoc operator actions and debugging."
+msgstr "协调器的逐出循环自动使用 ``DELETE /cache/objects``（参见 :doc:`coordinator` — “L2 使用跟踪和逐出”）；``GET /cache/objects`` 端点也支持协调器的启动重新同步。手动使用 ``curl`` 保留给临时操作员操作和调试。"
+
+#: ../../source/mp/http_api.rst:699
+msgid "``DELETE /cache/objects``"
+msgstr "``DELETE /cache/objects``"
+
+#: ../../source/mp/http_api.rst:701
+msgid ""
+"Delete a caller-supplied list of keys from one tier/adapter. Idempotent: "
+"keys absent from the adapter are skipped silently; keys currently locked "
+"by in-flight store/load tasks are skipped so the delete never corrupts an"
+" active transfer. The blocking adapter call is run off the event loop."
+msgstr "从一个层/适配器中删除调用者提供的键列表。幂等：适配器中缺失的键会被静默跳过；当前被进行中的存储/加载任务锁定的键会被跳过，以确保删除操作不会破坏正在进行的传输。阻塞适配器调用在事件循环之外运行。"
+
+#: ../../source/mp/http_api.rst:707
+msgid ""
+"Per-key successful deletions fire ``on_l2_keys_deleted`` on the adapter's"
+" listeners — when the coordinator is wired (see ``--coordinator-l2-event-"
+"reporting``), the deletions show up at the coordinator's ``POST "
+"/quota/events`` as ``\"type\": \"delete\"`` events. The coordinator's "
+"eviction + usage trackers learn about the deletion from that event flow, "
+"not from the response of this call."
+msgstr "每个键成功删除时会在适配器的监听器上触发 ``on_l2_keys_deleted`` — 当协调器已连接时（参见 ``--coordinator-l2-event-reporting``），删除操作会以 ``\\\"type\\\": \\\"delete\\\"`` 事件的形式出现在协调器的 ``POST /quota/events`` 中。协调器的逐出和使用跟踪器通过该事件流了解删除情况，而不是通过此调用的响应。"
+
+#: ../../source/mp/http_api.rst:723
+msgid "``keys``"
+msgstr "``keys``"
+
+#: ../../source/mp/http_api.rst:724
+msgid "list[EncodedObjectKey]"
+msgstr "列表[编码对象键]"
+
+#: ../../source/mp/http_api.rst:725
+msgid ""
+"Required. The object keys to delete (schema below). The batch is capped "
+"at ``10000`` keys per request."
+msgstr "必填。要删除的对象键（见下方模式）。每个请求的批量限制为 ``10000`` 个键。"
+
+#: ../../source/mp/http_api.rst:729
+msgid "Optional (default ``l2``). The only supported value."
+msgstr "可选（默认 ``l2``）。唯一支持的值。"
+
+#: ../../source/mp/http_api.rst:730 ../../source/mp/http_api.rst:801
+msgid "``adapter``"
+msgstr "``adapter``"
+
+#: ../../source/mp/http_api.rst:732
+msgid ""
+"Optional (default: primary, first-configured adapter). The ``type_name`` "
+"of the target adapter (see ``GET /config/adapters``)."
+msgstr "可选（默认值：主适配器，首次配置的适配器）。目标适配器的 ``type_name``（参见 ``GET /config/adapters``）。"
+
+#: ../../source/mp/http_api.rst:735
+msgid "Each ``EncodedObjectKey`` is"
+msgstr "每个 ``EncodedObjectKey`` 是"
+
+#: ../../source/mp/http_api.rst:747
+msgid ""
+"``object_group_id`` (default ``0``) and ``cache_salt`` (default ``\"\"``)"
+" are optional for backward compatibility with older wire payloads."
+msgstr "``object_group_id``（默认 ``0``）和 ``cache_salt``（默认 ``\"\"``）是为了与旧的 wire 负载向后兼容而可选的。"
+
+#: ../../source/mp/http_api.rst:760
+msgid ""
+"On adapter-level failure the response is still ``200`` with ``ok=false`` "
+"and an ``error`` field carrying the reason."
+msgstr "在适配器级别失败时，响应仍然是 ``200``，并且 ``ok=false``，同时 ``error`` 字段包含原因。"
+
+#: ../../source/mp/http_api.rst:765
+msgid "``200``: request reached the adapter (check ``ok`` for outcome)."
+msgstr "``200``: 请求已到达适配器（检查 ``ok`` 以获取结果）。"
+
+#: ../../source/mp/http_api.rst:766
+msgid ""
+"``400``: batch exceeds the limit, or a key payload violates an "
+"``ObjectKey`` invariant (bad hex, ``@`` in ``model_name``, forbidden "
+"``cache_salt`` character)."
+msgstr ""
+"``400``: 批量超出限制，或者一个键负载违反了 ``ObjectKey`` 不变式（错误的十六进制，``model_name`` 中的 "
+"``@``，禁止的 ``cache_salt`` 字符）。"
+
+#: ../../source/mp/http_api.rst:769
+msgid "``404``: ``adapter`` (body) does not match any configured adapter."
+msgstr "``404``: ``adapter``（主体）与任何已配置的适配器不匹配。"
+
+#: ../../source/mp/http_api.rst:770
+msgid ""
+"``422``: Pydantic-level body-shape failure (missing ``keys``, wrong field"
+" types)."
+msgstr "``422``: Pydantic 级别的主体形状失败（缺少 ``keys``，字段类型错误）。"
+
+#: ../../source/mp/http_api.rst:772 ../../source/mp/http_api.rst:856
+msgid "``503``: engine not initialized, or no L2 adapters configured."
+msgstr "``503``: 引擎未初始化，或未配置 L2 适配器。"
+
+#: ../../source/mp/http_api.rst:788
+msgid "``GET /cache/objects``"
+msgstr "``GET /cache/objects``"
+
+#: ../../source/mp/http_api.rst:790
+msgid "Paginate keys currently resident in one L2 adapter."
+msgstr "分页当前驻留在一个 L2 适配器中的键。"
+
+#: ../../source/mp/http_api.rst:792
+msgid "**Query parameters:**"
+msgstr "**查询参数：**"
+
+#: ../../source/mp/http_api.rst:798
+msgid "Name"
+msgstr "名称"
+
+#: ../../source/mp/http_api.rst:802
+msgid "primary"
+msgstr "主适配器"
+
+#: ../../source/mp/http_api.rst:803
+msgid ""
+"``type_name`` of the target adapter (see ``GET /config/adapters``). Omit "
+"to target the primary (first-configured) adapter. First match wins when "
+"multiple adapters share a ``type_name``."
+msgstr "目标适配器的 ``type_name``（参见 ``GET /config/adapters``）。省略以目标主适配器（第一个配置的适配器）。当多个适配器共享同一 ``type_name`` 时，优先匹配第一个。"
+
+#: ../../source/mp/http_api.rst:806 ../../source/mp/http_api.rst:896
+msgid "``model_name``"
+msgstr "``model_name``"
+
+#: ../../source/mp/http_api.rst:807 ../../source/mp/http_api.rst:814
+msgid "none"
+msgstr "无"
+
+#: ../../source/mp/http_api.rst:808
+msgid "Restrict the result to keys whose ``model_name`` matches."
+msgstr "将结果限制为与 ``model_name`` 匹配的键。"
+
+#: ../../source/mp/http_api.rst:809
+msgid "``page_size``"
+msgstr "``page_size``"
+
+#: ../../source/mp/http_api.rst:810
+msgid "``500``"
+msgstr "``500``"
+
+#: ../../source/mp/http_api.rst:811
+msgid ""
+"Max entries per page. Must be in ``[1, 5000]``; an out-of-range value is "
+"rejected with ``422`` (it is not silently clamped)."
+msgstr "每页最大条目数。必须在 ``[1, 5000]`` 范围内；超出范围的值将被拒绝并返回 ``422``\\ （不会被静默限制）。"
+
+#: ../../source/mp/http_api.rst:813
+msgid "``page_token``"
+msgstr "``page_token``"
+
+#: ../../source/mp/http_api.rst:815
+msgid ""
+"Opaque cursor from the previous page's ``next_page_token``. Omit on the "
+"first call; pass back verbatim on subsequent calls."
+msgstr "来自上一页的 ``next_page_token`` 的不透明游标。在第一次调用时省略；在后续调用中逐字传回。"
+
+#: ../../source/mp/http_api.rst:818
+msgid ""
+"The page token is private to the adapter; do not parse or modify it. "
+"Adapters that support listing (currently only the S3 adapter via "
+"``ListObjectsV2``) guarantee best-effort consistency, not snapshot "
+"isolation — concurrent stores or deletes during a paginated walk may "
+"cause keys to appear, disappear, or shift between pages."
+msgstr ""
+"页面令牌是适配器私有的；请勿解析或修改它。支持列出功能的适配器（目前仅通过 ``ListObjectsV2`` 的 S3 "
+"适配器）保证尽力而为的一致性，而不是快照隔离——在分页遍历期间的并发存储或删除可能导致键出现、消失或在页面之间移动。"
+
+#: ../../source/mp/http_api.rst:845
+msgid "``next_page_token`` is ``null`` when the listing is exhausted."
+msgstr "``next_page_token`` 在列出内容耗尽时为 ``null``。"
+
+#: ../../source/mp/http_api.rst:850
+msgid "``400``: malformed ``page_token`` (adapter-level)."
+msgstr "``400``: 错误的 ``page_token``\\ （适配器级别）。"
+
+#: ../../source/mp/http_api.rst:851
+msgid "``404``: ``?adapter=<name>`` does not match any configured adapter."
+msgstr "``404``: ``?adapter=<name>`` 与任何已配置的适配器不匹配。"
+
+#: ../../source/mp/http_api.rst:852
+msgid "``422``: ``page_size`` outside ``[1, 5000]``."
+msgstr "``422``: ``page_size`` 超出 ``[1, 5000]`` 范围。"
+
+#: ../../source/mp/http_api.rst:853
+msgid ""
+"``501``: selected adapter does not implement listing. In v1 only "
+"``S3L2Adapter`` does; adapters wrapped by ``SerdeL2AdapterWrapper`` "
+"inherit the wrapped adapter's behavior."
+msgstr ""
+"``501``: 选定的适配器不支持列出。在 v1 中，只有 ``S3L2Adapter`` 支持；由 "
+"``SerdeL2AdapterWrapper`` 包装的适配器继承被包装适配器的行为。"
+
+#: ../../source/mp/http_api.rst:858
+msgid "**Example:** paginate every key for a model."
+msgstr "**示例：** 为模型分页每个键。"
+
+#: ../../source/mp/http_api.rst:871
+msgid "``POST /cache/prefetches``"
+msgstr "``POST /cache/prefetches``"
+
+#: ../../source/mp/http_api.rst:873
+msgid ""
+"Warm one node's L1 by loading a token sequence's chunks from L2 **ahead**"
+" of the requests that will use them, so the first request hits L1 instead"
+" of paying the L2 fetch inline. Useful when a workload is about to be "
+"routed to a node (a traffic shift, a hot shared system prompt)."
+msgstr ""
+"通过从 L2 **提前** 加载一个令牌序列的块来预热一个节点的 L1，以便使用它们的第一个请求命中 L1，而不是在线支付 L2 "
+"获取的费用。当工作负载即将路由到一个节点（流量转移、热共享系统提示）时，这非常有用。"
+
+#: ../../source/mp/http_api.rst:878
+msgid ""
+"The caller describes content by **token ids**, never by internal cache "
+"keys (a key is a content hash plus a per-rank layout bitmap, which "
+"callers cannot construct). The server hashes the tokens, expands each "
+"chunk across the node's ranks, and submits a *warm* prefetch: loaded "
+"chunks are **retained** (permanent) and left **unlocked** — there is no "
+"downstream reader to pin them for, so a later real lookup takes its own "
+"lock. The call returns immediately; the load runs in the storage "
+"manager's own thread. It coalesces across all configured L2 adapters, so "
+"there is no ``?adapter=`` selector."
+msgstr ""
+"调用者通过 **token ids** 描述内容，而不是通过内部缓存键（键是内容哈希加上每个排名的布局位图，调用者无法构造）。服务器对 "
+"tokens 进行哈希，将每个块扩展到节点的各个排名，并提交一个 *warm* 预取：加载的块被 **保留**（永久）并保持 **解锁** — "
+"没有下游读取器来固定它们，因此后续的真实查找会自行加锁。调用立即返回；加载在存储管理器自己的线程中运行。它在所有配置的 L2 "
+"适配器之间合并，因此没有 ``?adapter=`` 选择器。"
+
+#: ../../source/mp/http_api.rst:898
+msgid "The served model id, exactly as registered (e.g. ``Qwen/Qwen3-8B``)."
+msgstr "提供的模型 ID，完全按照注册的方式（例如 ``Qwen/Qwen3-8B``）。"
+
+#: ../../source/mp/http_api.rst:899
+msgid "``world_size``"
+msgstr "``world_size``"
+
+#: ../../source/mp/http_api.rst:900
+msgid "int"
+msgstr "整数"
+
+#: ../../source/mp/http_api.rst:901
+msgid ""
+"The value vLLM registered for the node's KV layout and rank fan-out "
+"(``1`` for a single-GPU, TP=1 deployment)."
+msgstr "节点的 KV 布局和排名分发中注册的值 vLLM（对于单 GPU，TP=1 部署为 ``1``）。"
+
+#: ../../source/mp/http_api.rst:903
+msgid "``token_ids``"
+msgstr "``token_ids``"
+
+#: ../../source/mp/http_api.rst:904
+msgid "list[int]"
+msgstr "列表[int]"
+
+#: ../../source/mp/http_api.rst:905
+msgid ""
+"The prompt token ids. Must use the same tokenizer / special-token "
+"settings as the store, and contain at least one full ``chunk_size`` of "
+"tokens — only complete chunks are warmed."
+msgstr "提示令牌 ID。必须使用与存储相同的分词器/特殊令牌设置，并且至少包含一个完整的 ``chunk_size`` 令牌——只有完整的块会被预热。"
+
+#: ../../source/mp/http_api.rst:908
+msgid "``cache_salt``"
+msgstr "``cache_salt``"
+
+#: ../../source/mp/http_api.rst:910
+msgid "Per-tenant key isolation; must match the store (default ``\"\"``)."
+msgstr "每个租户的密钥隔离；必须与存储匹配（默认 ``\"\"``）。"
+
+#: ../../source/mp/http_api.rst:912
+msgid "**Response** (``202 Accepted``):"
+msgstr "**响应** (``202 Accepted``):"
+
+#: ../../source/mp/http_api.rst:918
+msgid ""
+"When the sequence is shorter than one chunk, nothing is submitted and "
+"there is no ``request_id`` to poll:"
+msgstr "当序列短于一个块时，不会提交任何内容，也没有 ``request_id`` 可供轮询："
+
+#: ../../source/mp/http_api.rst:927
+msgid "``202``: submitted (or a ``noop`` as above)."
+msgstr "``202``: 已提交（或如上所述的 ``noop``）。"
+
+#: ../../source/mp/http_api.rst:928
+msgid ""
+"``400``: ``token_ids`` exceeds the per-request cap, or ``cache_salt`` "
+"violates its invariants."
+msgstr "``400``: ``token_ids`` 超过每个请求的上限，或 ``cache_salt`` 违反了其不变性。"
+
+#: ../../source/mp/http_api.rst:930
+msgid ""
+"``409``: no layout registered for ``(model_name, world_size)`` — the "
+"model has not allocated KV cache on this node yet (start vLLM first)."
+msgstr ""
+"``409``: 未为 ``(model_name, world_size)`` 注册布局 — 该模型尚未在此节点上分配 KV "
+"Cache（请先启动 vLLM）。"
+
+#: ../../source/mp/http_api.rst:932
+msgid "``422``: request body fails field-level validation."
+msgstr "``422``: 请求体未通过字段级验证。"
+
+#: ../../source/mp/http_api.rst:946
+#, python-brace-format
+msgid "``GET /cache/prefetches/{request_id}``"
+msgstr "``GET /cache/prefetches/{request_id}``"
+
+#: ../../source/mp/http_api.rst:948
+msgid ""
+"Poll a submitted warm prefetch. The warm holds no lock, so the poll only "
+"reports progress; the first poll that observes completion drops the job "
+"(exactly-once), so a later poll for the same id returns ``404``."
+msgstr ""
+"轮询已提交的热预取。热预取不持有锁，因此轮询仅报告进度；第一个观察到完成的轮询将删除作业（精确一次），因此对同一 ID 的后续轮询返回 "
+"``404``。"
+
+#: ../../source/mp/http_api.rst:952
+msgid "**Response** (``200 OK``) while the load runs:"
+msgstr "**响应** (``200 OK``) 当负载运行时："
+
+#: ../../source/mp/http_api.rst:958
+msgid "…and once complete:"
+msgstr "…并且一旦完成："
+
+#: ../../source/mp/http_api.rst:964
+msgid ""
+"``found_keys`` / ``total_keys`` count only chunks **loaded from L2** by "
+"this request; chunks already resident in L1 are skipped at "
+"``reserve_write`` and not counted, so a partially-resident warm "
+"undercounts by the resident chunk count (a cold request loads and counts "
+"everything). The warm uses the gap-tolerant ``SPARSE`` trim policy, so an"
+" already-resident chunk does not stop the rest from loading — it loads "
+"every not-yet-resident chunk and reports that count. Not counting the "
+"resident chunks is deliberate: an already-present entry may be a "
+"transient temporary from another lookup, so claiming it as warmed could "
+"mislead."
+msgstr ""
+"``found_keys`` / ``total_keys`` 计数仅包括由此请求 **从 L2 加载的** 块；已经驻留在 L1 的块在 "
+"``reserve_write`` 时被跳过且不计入，因此部分驻留的热请求会低估驻留块的数量（冷请求会加载并计算所有内容）。热请求使用间隙容忍的 "
+"``SPARSE`` "
+"剪裁策略，因此一个已经驻留的块不会阻止其他块的加载——它会加载每个尚未驻留的块并报告该数量。不计算驻留块是故意的：一个已经存在的条目可能是来自另一个查找的瞬态临时条目，因此将其视为热请求可能会误导。"
+
+#: ../../source/mp/http_api.rst:975
+msgid "``200``: status reported (``pending`` or ``completed``)."
+msgstr "``200``: 状态报告（``pending`` 或 ``completed``）。"
+
+#: ../../source/mp/http_api.rst:976
+msgid ""
+"``404``: unknown ``request_id`` — already completed-and-consumed, or "
+"never submitted."
+msgstr "``404``: 未知 ``request_id`` — 已经完成并消费，或从未提交。"
+
+#: ../../source/mp/http_api.rst:990
+msgid "Quota Management"
+msgstr "配额管理"
+
+#: ../../source/mp/http_api.rst:992
+msgid ""
+"These endpoints manage the per-``cache_salt`` storage budgets consumed by"
+" the ``IsolatedLRU`` eviction policy (selected via ``--eviction-policy "
+"IsolatedLRU``). Quotas are **soft**: setting a limit does not reject "
+"writes — any over-budget ``cache_salt`` is evicted at the next eviction "
+"cycle (~1 s). A ``cache_salt`` with no registered quota has an effective "
+"limit of ``0`` bytes, so its data is cleared next cycle (allowlist "
+"semantics)."
+msgstr ""
+"这些端点管理由 ``IsolatedLRU`` 逐出策略（通过 ``--eviction-policy IsolatedLRU`` "
+"选择）消耗的每个 ``cache_salt`` 存储预算。配额是 **软性** 的：设置限制并不会拒绝写入 — 任何超出预算的 "
+"``cache_salt`` 会在下一个逐出周期（约 1 秒）被逐出。没有注册配额的 ``cache_salt`` 有一个有效限制为 ``0`` "
+"字节，因此其数据将在下一个周期被清除（白名单语义）。"
+
+#: ../../source/mp/http_api.rst:1000
+msgid ""
+"These endpoints are no-ops on engines that did not start with "
+"``--eviction-policy IsolatedLRU``: the ``QuotaManager`` is still present,"
+" but the LRU policy ignores the registered quotas."
+msgstr ""
+"对于未使用 ``--eviction-policy IsolatedLRU`` 启动的引擎，这些端点为空操作：\\ "
+"``QuotaManager`` 仍然存在，但 LRU 策略会忽略已注册的配额。"
+
+#: ../../source/mp/http_api.rst:1004
+msgid ""
+"**URL escaping for the empty salt.** ``cache_salt=\"\"`` (un-salted / "
+"anonymous traffic) cannot appear in a URL path parameter, so the API "
+"accepts the sentinel ``_default`` in its place. ``PUT /quota/_default`` "
+"sets the quota for ``cache_salt=\"\"``, and ``_default`` is echoed back "
+"in responses for the empty salt. A user that legitimately stores data "
+"with ``cache_salt=\"_default\"`` cannot be managed via this HTTP API "
+"distinctly from anonymous traffic — both map to the same path parameter; "
+"pick any other value (e.g. ``\"default\"``) to disambiguate."
+msgstr ""
+"**空盐的 URL 转义。** ``cache_salt=\\\"\\\"``\\ （无盐/匿名流量）不能出现在 URL 路径参数中，因此 API"
+" 接受哨兵 ``_default`` 作为替代。``PUT /quota/_default`` 设置 "
+"``cache_salt=\\\"\\\"`` 的配额，``_default`` 在空盐的响应中被回显。合法存储数据的用户 "
+"``cache_salt=\\\"_default\\\"`` 不能通过此 HTTP API "
+"与匿名流量区分管理——两者映射到相同的路径参数；选择任何其他值（例如 ``\\\"default\\\"``）以消除歧义。"
+
+#: ../../source/mp/http_api.rst:1014
+#, python-brace-format
+msgid "``PUT /quota/{cache_salt}``"
+msgstr "``PUT /quota/{cache_salt}``"
+
+#: ../../source/mp/http_api.rst:1016
+msgid "Create or update a quota."
+msgstr "创建或更新配额。"
+
+#: ../../source/mp/http_api.rst:1018
+msgid ""
+"**Path parameters:** ``cache_salt`` — tenant identifier (use ``_default``"
+" for the empty salt; see the section intro)."
+msgstr "**路径参数:** ``cache_salt`` — 租户标识符（使用 ``_default`` 表示空盐；请参阅章节介绍）。"
+
+#: ../../source/mp/http_api.rst:1030
+msgid "``limit_gb``"
+msgstr "``limit_gb``"
+
+#: ../../source/mp/http_api.rst:1031
+msgid "float"
+msgstr "浮点数"
+
+#: ../../source/mp/http_api.rst:1032
+msgid "Required. The quota in GB. Must be finite and non-negative."
+msgstr "必需。配额以 GB 为单位。必须是有限的且非负的。"
+
+#: ../../source/mp/http_api.rst:1042
+msgid "``200``: quota set or updated."
+msgstr "``200``: 配额已设置或更新。"
+
+#: ../../source/mp/http_api.rst:1043
+msgid ""
+"``400``: malformed JSON, missing ``limit_gb``, non-numeric ``limit_gb``, "
+"``nan`` / ``inf``, or a negative value."
+msgstr "``400``: JSON 格式错误，缺少 ``limit_gb``，``limit_gb`` 非数字，``nan`` / ``inf``，或负值。"
+
+#: ../../source/mp/http_api.rst:1056
+#, python-brace-format
+msgid "``GET /quota/{cache_salt}``"
+msgstr "``GET /quota/{cache_salt}``"
+
+#: ../../source/mp/http_api.rst:1058
+msgid "Read the current quota and live usage for one ``cache_salt``."
+msgstr "读取当前配额和一个 ``cache_salt`` 的实时使用情况。"
+
+#: ../../source/mp/http_api.rst:1060 ../../source/mp/http_api.rst:1099
+msgid ""
+"**Path parameters:** ``cache_salt`` — tenant identifier (use ``_default``"
+" for the empty salt)."
+msgstr "**路径参数:** ``cache_salt`` — 租户标识符（使用 ``_default`` 表示空盐）。"
+
+#: ../../source/mp/http_api.rst:1074
+msgid ""
+"``exists`` is ``false`` when no quota was ever registered for this "
+"``cache_salt`` (``limit_gb`` is then ``0.0`` and ``current_usage_gb`` "
+"reflects whatever bytes are currently cached for that salt — those bytes "
+"will evict next cycle under ``IsolatedLRU``). This endpoint never returns"
+" ``404`` for an unknown salt."
+msgstr ""
+"``exists`` 为 ``false`` 当这个 ``cache_salt`` 从未注册过配额时（``limit_gb`` 此时为 "
+"``0.0``，而 ``current_usage_gb`` 反映当前为该盐缓存的字节数——这些字节将在下一个周期下逐出 "
+"``IsolatedLRU``）。这个端点对于未知的盐永远不会返回 ``404``。"
+
+#: ../../source/mp/http_api.rst:1082
+msgid ""
+"``200``: quota and usage returned (also when the salt has no registered "
+"quota — ``exists`` is then ``false``; never ``404``)."
+msgstr "``200``: 返回配额和使用情况（即使盐没有注册配额——此时 ``exists`` 为 ``false``；永远不会 ``404``）。"
+
+#: ../../source/mp/http_api.rst:1093
+#, python-brace-format
+msgid "``DELETE /quota/{cache_salt}``"
+msgstr "``DELETE /quota/{cache_salt}``"
+
+#: ../../source/mp/http_api.rst:1095
+msgid ""
+"Remove a ``cache_salt``'s quota entry. Any bytes still cached under this "
+"``cache_salt`` become over-budget on the next eviction cycle (effective "
+"limit drops to ``0``) and will be evicted."
+msgstr ""
+"删除 ``cache_salt`` 的配额条目。任何仍然缓存于此 ``cache_salt`` 下的字节将在下一个逐出周期中超出预算（有效限制降至"
+" ``0``\\ ），并将被逐出。"
+
+#: ../../source/mp/http_api.rst:1108
+#, python-brace-format
+msgid ""
+"When no quota was registered for the given ``cache_salt``, the response "
+"is ``{\"cache_salt\": \"...\", \"status\": \"not_found\"}`` (still ``200 "
+"OK``)."
+msgstr ""
+"当给定的 ``cache_salt`` 没有注册配额时，响应为 ``{\\\"cache_salt\\\": \\\"...\\\", "
+"\\\"status\\\": \\\"not_found\\\"}``\\ （仍然是 ``200 OK``\\ ）。"
+
+#: ../../source/mp/http_api.rst:1113
+msgid ""
+"``200``: quota entry removed (``\"removed\"``) or none existed "
+"(``\"not_found\"``); never ``404``."
+msgstr "``200``: 配额条目已移除 (``\"removed\"``) 或不存在 (``\"not_found\"``)；永远不会是 ``404``。"
+
+#: ../../source/mp/http_api.rst:1124
+msgid "``GET /quota``"
+msgstr "``GET /quota``"
+
+#: ../../source/mp/http_api.rst:1126
+msgid "List every registered quota alongside its live usage."
+msgstr "列出每个注册的配额及其实时使用情况。"
+
+#: ../../source/mp/http_api.rst:1139
+msgid ""
+"Only ``cache_salt`` values with a **registered** quota appear; the empty "
+"salt is reported under the ``_default`` key."
+msgstr "只有带有 **注册** 配额的 ``cache_salt`` 值会出现；空盐会在 ``_default`` 键下报告。"
+
+#: ../../source/mp/http_api.rst:1144
+#, python-brace-format
+msgid ""
+"``200``: quota listing returned (``{\"users\": {}}`` when none "
+"registered)."
+msgstr "``200``: 返回配额列表 (``{\\\"users\\\": {}}`` 当没有注册时)。"
+
+#: ../../source/mp/http_api.rst:1156
+msgid "Runtime L2 Reconfiguration"
+msgstr "运行时 L2 重新配置"
+
+#: ../../source/mp/http_api.rst:1158
+msgid ""
+"These endpoints are available when the server has a runtime-"
+"reconfigurable L2 adapter. They only change LMCache runtime mappings and "
+"metadata; backend resources such as DAX device paths must already exist "
+"and be readable and writable by the server. The endpoint routes "
+"``backend``, ``operation``, and the JSON request body into the generic L2"
+" adapter reconfiguration API, while backend-specific validation and "
+"migration semantics stay inside the adapter."
+msgstr ""
+"这些端点在服务器具有可运行时重新配置的 L2 适配器时可用。它们仅更改 LMCache 的运行时映射和元数据；后端资源如 DAX "
+"设备路径必须已经存在，并且服务器必须能够读取和写入。该端点将 ``backend``\\ 、\\ ``operation`` 和 JSON "
+"请求体路由到通用 L2 适配器重新配置 API，而后端特定的验证和迁移语义则保留在适配器内部。"
+
+#: ../../source/mp/http_api.rst:1165
+msgid ""
+"``backend`` and ``operation`` path segments are normalized (stripped and "
+"lower-cased). Within a request body, ``adapter_index`` (default ``0``) is"
+" **backend-local** — it indexes only the adapters of that backend, not "
+"the engine-wide adapter list. If an L2 adapter is wrapped by serde, the "
+"backend string is still the configured L2 adapter type, not the serde "
+"wrapper type."
+msgstr ""
+"``backend`` 和 ``operation`` 路径段被规范化（去除空格并转为小写）。在请求体内，``adapter_index``\\ "
+"（默认为 ``0``）是 **后端本地** 的——它仅索引该后端的适配器，而不是整个引擎的适配器列表。如果 L2 "
+"适配器被序列化/反序列化包装，后端字符串仍然是配置的 L2 适配器类型，而不是序列化/反序列化包装类型。"
+
+#: ../../source/mp/http_api.rst:1173
+msgid ""
+"The backend strings accepted here are discovered via ``GET "
+"/config/adapters``: each adapter whose ``reconfigurable`` flag is "
+"``true`` can be addressed by its ``type_name``."
+msgstr "这里接受的后端字符串通过 ``GET /config/adapters`` 发现：每个 ``reconfigurable`` 标志为 ``true`` 的适配器都可以通过其 ``type_name`` 进行访问。"
+
+#: ../../source/mp/http_api.rst:1178
+#, python-brace-format
+msgid "``GET /reconfigure/{backend}/status``"
+msgstr "``GET /reconfigure/{backend}/status``"
+
+#: ../../source/mp/http_api.rst:1180
+msgid ""
+"Report the runtime-manageable adapters for one backend type. Each adapter"
+" entry's ``adapter_index`` is rewritten to its **backend-local** 0-based "
+"index (the value to pass back in operation request bodies)."
+msgstr ""
+"报告一个后端类型的运行时可管理适配器。每个适配器条目的 ``adapter_index`` 被重写为其 **后端本地** 的 0 "
+"基索引（在操作请求体中传回的值）。"
+
+#: ../../source/mp/http_api.rst:1184
+msgid ""
+"**Path parameters:** ``backend`` — adapter ``type_name`` (normalized: "
+"stripped and lower-cased; discover valid values via ``GET "
+"/config/adapters``)."
+msgstr "**路径参数:** ``backend`` — 适配器 ``type_name``（标准化：去除空格并小写；通过 ``GET /config/adapters`` 发现有效值）。"
+
+#: ../../source/mp/http_api.rst:1200
+msgid ""
+"An unknown or empty backend returns ``enabled=false``, "
+"``num_adapters=0``, ``adapters=[]`` (it is **not** a ``404``)."
+msgstr ""
+"一个未知或空的后端返回 ``enabled=false``，``num_adapters=0``，``adapters=[]``\\ （这\\ "
+"**不是** ``404``）。"
+
+#: ../../source/mp/http_api.rst:1205
+msgid "``200``: status returned (including the unknown-backend case above)."
+msgstr "``200``：返回的状态（包括上述未知后端的情况）。"
+
+#: ../../source/mp/http_api.rst:1206
+msgid "``400``: ``backend`` is empty."
+msgstr "``400``: ``backend`` 为空。"
+
+#: ../../source/mp/http_api.rst:1216
+#, python-brace-format
+msgid "``POST /reconfigure/{backend}/{operation}``"
+msgstr "``POST /reconfigure/{backend}/{operation}``"
+
+#: ../../source/mp/http_api.rst:1218
+msgid ""
+"Apply one reconfiguration operation to a backend adapter. The request "
+"body is a JSON object whose accepted fields depend on the backend and "
+"operation. The ``200`` response is whatever the storage manager's "
+"``reconfigure_l2_adapter`` returns (a backend-defined dict)."
+msgstr ""
+"将一个重新配置操作应用于后端适配器。请求体是一个 JSON 对象，其接受的字段取决于后端和操作。``200`` 响应是存储管理器的 "
+"``reconfigure_l2_adapter`` 返回的内容（一个后端定义的字典）。"
+
+#: ../../source/mp/http_api.rst:1223
+msgid ""
+"**Path parameters:** ``backend`` (adapter ``type_name``) and "
+"``operation`` (e.g. ``add`` / ``remove`` / ``resize`` for ``dax``). Both "
+"are normalized (stripped and lower-cased)."
+msgstr "**路径参数:** ``backend``（适配器 ``type_name``）和 ``operation``（例如 ``add`` / ``remove`` / ``resize`` 用于 ``dax``）。两者都经过标准化（去除空格并转为小写）。"
+
+#: ../../source/mp/http_api.rst:1227
+msgid ""
+"For the **generic** path (any backend other than ``dax``), the body "
+"carries ``adapter_index`` plus any backend-specific fields, which are "
+"forwarded verbatim to the adapter."
+msgstr ""
+"对于 **通用** 路径（任何后端除了 ``dax``），请求体包含 ``adapter_index`` "
+"以及任何特定于后端的字段，这些字段会逐字转发给适配器。"
+
+#: ../../source/mp/http_api.rst:1231
+msgid ""
+"For **Device-DAX** (``backend=dax``), JSON request bodies are used "
+"because DAX paths contain slashes. The accepted operations and fields "
+"are:"
+msgstr "对于 **Device-DAX** (``backend=dax``)，使用 JSON 请求体，因为 DAX 路径包含斜杠。接受的操作和字段包括："
+
+#: ../../source/mp/http_api.rst:1238
+msgid "Operation"
+msgstr "操作"
+
+#: ../../source/mp/http_api.rst:1239
+msgid "Body fields"
+msgstr "主体字段"
+
+#: ../../source/mp/http_api.rst:1240
+msgid "``add``"
+msgstr "``add``"
+
+#: ../../source/mp/http_api.rst:1241
+msgid ""
+"``device_path`` (str, required), ``size`` (int byte count or string such "
+"as ``\"100GiB\"``, required), ``adapter_index`` (default ``0``)."
+msgstr ""
+"``device_path``\\ （str，必填），``size``\\ （字节数或字符串，例如\\ "
+"``\"100GiB\"``，必填），``adapter_index``\\ （默认\\ ``0``）。"
+
+#: ../../source/mp/http_api.rst:1243
+msgid "``remove``"
+msgstr "``remove``"
+
+#: ../../source/mp/http_api.rst:1244
+msgid ""
+"``device_path`` (str, required), ``mode`` (``migrate`` | ``evict`` | "
+"``drain``, default ``migrate``), ``force`` (bool, default ``false``), "
+"``adapter_index`` (default ``0``)."
+msgstr ""
+"``device_path`` (str, 必需), ``mode`` (``migrate`` | ``evict`` | ``drain``,"
+" 默认 ``migrate``), ``force`` (bool, 默认 ``false``), ``adapter_index`` (默认 "
+"``0``)。"
+
+#: ../../source/mp/http_api.rst:1247
+msgid "``resize``"
+msgstr "``resize``"
+
+#: ../../source/mp/http_api.rst:1248
+msgid ""
+"``device_path`` (str, required), ``size`` (int or string, required), "
+"``mode`` (``migrate`` | ``evict``, default ``migrate``), ``force`` (bool,"
+" default ``false``), ``adapter_index`` (default ``0``)."
+msgstr ""
+"``device_path``\\ （str，必需），``size``\\ （int 或 string，必需），``mode``\\ "
+"（``migrate`` | ``evict``，默认 ``migrate``），``force``\\ （bool，默认 "
+"``false``），``adapter_index``\\ （默认 ``0``）。"
+
+#: ../../source/mp/http_api.rst:1252
+msgid ""
+"``size`` accepts an integer byte count or a string with a base-1024 unit "
+"suffix (``b``, ``kib``, ``mib``, ``gib``, ``tib`` and the "
+"``k``/``m``/``g``/``t`` aliases), e.g. ``\"100GiB\"``; it must resolve to"
+" a positive value."
+msgstr ""
+"``size`` 接受一个整数字节数或带有基于 1024 "
+"的单位后缀的字符串（``b``、``kib``、``mib``、``gib``、``tib`` 及其 "
+"``k``/``m``/``g``/``t`` 别名），例如 ``\"100GiB\"``；它必须解析为一个正值。"
+
+#: ../../source/mp/http_api.rst:1258
+msgid ""
+"The body is the backend's ``reconfigure_l2_adapter`` result (a backend-"
+"defined dict). A successful DAX ``add`` looks like:"
+msgstr "主体是后端的 ``reconfigure_l2_adapter`` 结果（一个后端定义的字典）。成功的 DAX ``add`` 看起来像这样："
+
+#: ../../source/mp/http_api.rst:1272
+msgid "``200``: success (body is the storage manager's reconfigure result)."
+msgstr "``200``: 成功（主体是存储管理器的重新配置结果）。"
+
+#: ../../source/mp/http_api.rst:1273
+msgid ""
+"``400``: empty ``backend``/``operation``, an unsupported DAX operation, "
+"or an invalid ``size``."
+msgstr "``400``: 空的 ``backend``/``operation``，不支持的 DAX 操作，或无效的 ``size``。"
+
+#: ../../source/mp/http_api.rst:1275
+msgid "``404``: ``adapter_index`` is out of range for the backend."
+msgstr "``404``: ``adapter_index`` 超出后端范围。"
+
+#: ../../source/mp/http_api.rst:1276
+msgid ""
+"``422``: request body fails validation (e.g. a missing required field, or"
+" an unknown field in a DAX body — DAX bodies reject extras)."
+msgstr "``422``: 请求体验证失败（例如，缺少必填字段或 DAX 请求体中的未知字段——DAX 请求体会拒绝额外字段）。"
+
+#: ../../source/mp/http_api.rst:1288
+msgid ""
+"See :doc:`/kv_cache/storage_backends/dax` for detailed request examples, "
+"mode semantics, and validation guidance."
+msgstr "有关详细的请求示例、模式语义和验证指导，请参阅 :doc:`/kv_cache/storage_backends/dax`。"
+
+#: ../../source/mp/http_api.rst:1292
+msgid "Observability"
+msgstr "可观察性"
+
+#: ../../source/mp/http_api.rst:1295
+msgid "``GET /metrics``"
+msgstr "``GET /metrics``"
+
+#: ../../source/mp/http_api.rst:1297
+msgid ""
+"Prometheus exposition format for every metric registered on the default "
+"``prometheus_client`` registry (``Content-Type: text/plain``). Scrape "
+"this directly from Prometheus. See :doc:`observability/index` for the "
+"list of exported metrics."
+msgstr ""
+"默认 ``prometheus_client`` 注册表中注册的每个指标的 Prometheus 展示格式 (``Content-Type: "
+"text/plain``)。直接从 Prometheus 抓取此数据。有关导出指标的列表，请参见 "
+":doc:`observability/index`。"
+
+#: ../../source/mp/http_api.rst:1302
+msgid ""
+"**Response** (``200 OK``, ``text/plain``): the Prometheus exposition-"
+"format metrics body."
+msgstr "**响应** (``200 OK``, ``text/plain``): Prometheus 展示格式的指标主体。"
+
+#: ../../source/mp/http_api.rst:1307
+msgid "``200``: metrics returned."
+msgstr "``200``：返回的指标。"
+
+#: ../../source/mp/http_api.rst:1316
+msgid "``POST /metrics/reset``"
+msgstr "``POST /metrics/reset``"
+
+#: ../../source/mp/http_api.rst:1318
+msgid ""
+"Resets all LMCache observability metrics to their initial state "
+"(``reset_observability_metrics``). Intended for test harnesses and "
+"benchmarks — not for production."
+msgstr ""
+"将所有 LMCache 可观察性指标重置为初始状态（\\ ``reset_observability_metrics``\\ "
+"）。面向测试框架和基准测试，不适用于生产环境。"
+
+#: ../../source/mp/http_api.rst:1322 ../../source/mp/http_api.rst:1588
+msgid "**Response** (``200 OK``, ``text/plain``):"
+msgstr "**响应**\\ （``200 OK``, ``text/plain``）："
+
+#: ../../source/mp/http_api.rst:1330
+msgid "``200``: metrics reset."
+msgstr "``200``：指标已重置。"
+
+#: ../../source/mp/http_api.rst:1339
+msgid "Diagnostics and Debugging"
+msgstr "诊断与调试"
+
+#: ../../source/mp/http_api.rst:1342
+msgid "``GET /loglevel``"
+msgstr "``GET /loglevel``"
+
+#: ../../source/mp/http_api.rst:1344
+msgid ""
+"Inspect or mutate Python logger levels at runtime. All responses are "
+"``text/plain``. The endpoint has three modes driven by query parameters:"
+msgstr "在运行时检查或修改 Python 日志记录器级别。所有响应都是 ``text/plain``\\ 。该端点有三种模式，由查询参数驱动："
+
+#: ../../source/mp/http_api.rst:1351 ../../source/mp/http_api.rst:1398
+#: ../../source/mp/http_api.rst:1435
+msgid "Query"
+msgstr "查询"
+
+#: ../../source/mp/http_api.rst:1352 ../../source/mp/http_api.rst:1399
+#: ../../source/mp/http_api.rst:1436
+msgid "Behavior"
+msgstr "行为"
+
+#: ../../source/mp/http_api.rst:1353
+msgid "(no params)"
+msgstr "(无参数)"
+
+#: ../../source/mp/http_api.rst:1354
+msgid "List every logger registered with :mod:`logging` and its level."
+msgstr "列出所有在 :mod:`logging` 中注册的记录器及其级别。"
+
+#: ../../source/mp/http_api.rst:1355
+msgid "``?logger_name=<name>``"
+msgstr "``?logger_name=<name>``"
+
+#: ../../source/mp/http_api.rst:1356
+msgid "Return the effective level of the named logger."
+msgstr "返回指定记录器的有效级别。"
+
+#: ../../source/mp/http_api.rst:1357
+msgid "``?logger_name=<name>&level=<LEVEL>``"
+msgstr "``?logger_name=<name>&level=<LEVEL>``"
+
+#: ../../source/mp/http_api.rst:1358
+msgid ""
+"Set the named logger (and its handlers) to ``LEVEL`` "
+"(``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``; case-"
+"insensitive). Returns ``400`` on an unknown level."
+msgstr ""
+"将命名的日志记录器（及其处理程序）设置为 ``LEVEL``\\ "
+"（``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``；不区分大小写）。如果级别未知，则返回"
+" ``400``。"
+
+#: ../../source/mp/http_api.rst:1362
+msgid ""
+"Passing ``level`` without ``logger_name`` matches none of the modes and "
+"returns ``200`` with a ``null`` body."
+msgstr "传递 ``level`` 而不带 ``logger_name`` 不匹配任何模式，并返回 ``200`` 和一个 ``null`` 响应体。"
+
+#: ../../source/mp/http_api.rst:1365
+msgid ""
+"**Response** (``200 OK``, ``text/plain``): one ``<logger>: <LEVEL>`` line"
+" per registered logger (list mode), a single ``<logger>: <LEVEL>`` (read "
+"mode), or a confirmation of the updated level (set mode)."
+msgstr "**响应** (``200 OK``, ``text/plain``): 每个注册的日志记录器一行 ``<logger>: <LEVEL>``（列表模式），一个 ``<logger>: <LEVEL>``（读取模式），或更新级别的确认（设置模式）。"
+
+#: ../../source/mp/http_api.rst:1371
+msgid "``200``: levels listed, read, or set (also the ``null``-body case above)."
+msgstr "``200``: 列出、读取或设置的级别（也包括上述的 ``null``-body 情况）。"
+
+#: ../../source/mp/http_api.rst:1372
+msgid "``400``: ``level`` is not a known logging level."
+msgstr "``400``: ``level`` 不是已知的日志级别。"
+
+#: ../../source/mp/http_api.rst:1388
+msgid "``GET /threads``"
+msgstr "``GET /threads``"
+
+#: ../../source/mp/http_api.rst:1390
+msgid ""
+"Enumerate active Python threads in the server process along with their "
+"stack traces, plus a total-count summary (``Content-Type: text/plain``). "
+"Useful for live debugging of hangs or runaway workers."
+msgstr ""
+"列出服务器进程中活动的 Python 线程及其堆栈跟踪，并提供总计摘要（``Content-Type: "
+"text/plain``）。对于实时调试挂起或失控的工作线程非常有用。"
+
+#: ../../source/mp/http_api.rst:1400
+msgid "``?name=<substr>``"
+msgstr "``?name=<substr>``"
+
+#: ../../source/mp/http_api.rst:1401
+msgid "Keep only threads whose name contains ``<substr>`` (case-insensitive)."
+msgstr "仅保留名称包含 ``<substr>`` 的线程（不区分大小写）。"
+
+#: ../../source/mp/http_api.rst:1403
+msgid "``?thread_id=<int>``"
+msgstr "``?thread_id=<int>``"
+
+#: ../../source/mp/http_api.rst:1404
+msgid "Keep only the thread with the matching ``ident``."
+msgstr "仅保留 ``ident`` 匹配的线程。"
+
+#: ../../source/mp/http_api.rst:1408
+msgid ""
+"The response contains live stack traces and can disclose internal code "
+"paths and state. Restrict network access to this endpoint in production."
+msgstr "响应包含实时堆栈跟踪，并可能泄露内部代码路径和状态。在生产环境中限制对该端点的网络访问。"
+
+#: ../../source/mp/http_api.rst:1411
+msgid ""
+"**Response** (``200 OK``, ``text/plain``): a total-thread-count summary "
+"followed by each thread's name, ``ident``, and current stack trace."
+msgstr "**响应** (``200 OK``, ``text/plain``)：总线程数摘要，后面跟着每个线程的名称、``ident`` 和当前堆栈跟踪。"
+
+#: ../../source/mp/http_api.rst:1416
+msgid "``200``: thread listing returned."
+msgstr "``200``: 返回线程列表。"
+
+#: ../../source/mp/http_api.rst:1425
+msgid "``GET /periodic-threads``"
+msgstr "``GET /periodic-threads``"
+
+#: ../../source/mp/http_api.rst:1427
+msgid ""
+"Returns a JSON snapshot of the "
+":class:`~lmcache.v1.periodic_thread.PeriodicThreadRegistry`: counts by "
+"level plus per-thread status (last run timestamp, latest summary, etc.)."
+msgstr ""
+"返回 :class:`~lmcache.v1.periodic_thread.PeriodicThreadRegistry` 的 JSON "
+"快照：按级别统计以及每个线程的状态（上次运行时间戳、最新摘要等）。"
+
+#: ../../source/mp/http_api.rst:1437
+msgid "``?level=critical|high|medium|low``"
+msgstr "``?level=critical|high|medium|low``"
+
+#: ../../source/mp/http_api.rst:1438
+msgid "Only include threads at the given level. ``400`` on unknown."
+msgstr "仅包含给定级别的线程。对未知情况返回 ``400``\\ 。"
+
+#: ../../source/mp/http_api.rst:1439
+msgid "``?running_only=true``"
+msgstr "``?running_only=true``"
+
+#: ../../source/mp/http_api.rst:1440
+msgid "Only include threads currently running."
+msgstr "仅包含当前正在运行的线程。"
+
+#: ../../source/mp/http_api.rst:1441
+msgid "``?active_only=true``"
+msgstr "``?active_only=true``"
+
+#: ../../source/mp/http_api.rst:1442
+msgid "Only include threads considered active (recent tick)."
+msgstr "仅包括被视为活动的线程（最近的滴答）。"
+
+#: ../../source/mp/http_api.rst:1478
+msgid "``200``: snapshot returned."
+msgstr "``200``: 返回快照。"
+
+#: ../../source/mp/http_api.rst:1479
+msgid "``400``: unknown ``level`` filter."
+msgstr "``400``: 未知 ``level`` 过滤器。"
+
+#: ../../source/mp/http_api.rst:1488
+#, python-brace-format
+msgid "``GET /periodic-threads/{thread_name}``"
+msgstr "``GET /periodic-threads/{thread_name}``"
+
+#: ../../source/mp/http_api.rst:1490
+#, python-brace-format
+msgid ""
+"Detailed status for a single periodic thread (the same per-thread object "
+"shown in the ``threads`` list above)."
+msgstr "单个周期性线程的详细状态（与上面 ``threads`` 列表中显示的每个线程对象相同）。"
+
+#: ../../source/mp/http_api.rst:1493
+msgid ""
+"**Path parameters:** ``thread_name`` — the registered periodic thread "
+"name."
+msgstr "**路径参数:** ``thread_name`` — 注册的周期线程名称。"
+
+#: ../../source/mp/http_api.rst:1512
+msgid "**Response** (``404 Not Found``) when the name is unknown:"
+msgstr "**响应** (``404 Not Found``) 当名称未知时："
+
+#: ../../source/mp/http_api.rst:1520
+msgid "``200``: thread status returned."
+msgstr "``200``: 返回的线程状态。"
+
+#: ../../source/mp/http_api.rst:1521
+msgid "``404``: no periodic thread with that name."
+msgstr "``404``: 没有名为该名称的周期性线程。"
+
+#: ../../source/mp/http_api.rst:1530
+msgid "``GET /periodic-threads-health``"
+msgstr "``GET /periodic-threads-health``"
+
+#: ../../source/mp/http_api.rst:1532
+msgid ""
+"Fast health check covering only ``critical`` and ``high`` level periodic "
+"threads. A thread is flagged unhealthy when it is marked running but has "
+"not ticked within its expected interval. Always returns ``200`` — health "
+"is conveyed by the ``healthy`` boolean, not the HTTP status."
+msgstr ""
+"快速健康检查，仅涵盖 ``critical`` 和 ``high`` "
+"级别的周期性线程。当线程被标记为运行但在预期间隔内未进行计时时，它会被标记为不健康。始终返回 ``200`` — 健康状态通过 "
+"``healthy`` 布尔值传达，而不是通过 HTTP 状态。"
+
+#: ../../source/mp/http_api.rst:1547
+msgid "When something is lagging:"
+msgstr "当出现滞后时："
+
+#: ../../source/mp/http_api.rst:1566
+msgid ""
+"``200``: health reported — always ``200``, even when unhealthy (the "
+"``healthy`` boolean is ``false``)."
+msgstr "``200``：健康报告 — 始终为 ``200``，即使在不健康时（``healthy`` 布尔值为 ``false``）。"
+
+#: ../../source/mp/http_api.rst:1576
+msgid "``GET /env``"
+msgstr "``GET /env``"
+
+#: ../../source/mp/http_api.rst:1578
+msgid ""
+"Dumps the process environment variables as a sorted, pretty-printed JSON "
+"document. The response ``Content-Type`` is ``text/plain`` so it can be "
+"piped directly to a terminal."
+msgstr ""
+"将进程环境变量转储为排序后的美观打印 JSON 文档。响应的 ``Content-Type`` 为 "
+"``text/plain``，因此可以直接通过管道传输到终端。"
+
+#: ../../source/mp/http_api.rst:1584
+msgid ""
+"The payload contains **every** environment variable, including any "
+"secrets injected via the environment. There is no redaction or auth — "
+"restrict network access to this endpoint in production."
+msgstr "有效负载包含 **每个** 环境变量，包括通过环境注入的任何秘密。没有任何编辑或身份验证 — 在生产环境中限制对该端点的网络访问。"
+
+#: ../../source/mp/http_api.rst:1600
+msgid "``200``: environment dump returned."
+msgstr "``200``: 环境转储已返回。"
+
+#: ../../source/mp/http_api.rst:1609
+msgid "``POST /run_script``"
+msgstr "``POST /run_script``"
+
+#: ../../source/mp/http_api.rst:1611
+msgid ""
+"Execute an uploaded Python script inside the server process. The script "
+"is uploaded as multipart form data under the field name ``script`` and is"
+" ``exec``'d with a restricted ``__builtins__`` (only ``print``, ``str``, "
+"``int``, ``float``, ``list``, ``dict``, ``tuple``, ``set``, and a guarded"
+" ``__import__``). Only modules listed in ``--script-allowed-imports`` can"
+" be imported; the running FastAPI ``app`` is injected into the script "
+"globals. If the script assigns a variable named ``result``, its "
+"stringified value is returned; otherwise the body is ``\"Script executed "
+"successfully\"`` (``Content-Type: text/plain``)."
+msgstr ""
+"在服务器进程中执行上传的 Python 脚本。脚本作为多部分表单数据上传，字段名称为 ``script``，并在受限的 "
+"``__builtins__`` 下被 ``exec`` 执行（仅允许 "
+"``print``、``str``、``int``、``float``、``list``、``dict``、``tuple``、``set`` "
+"和受保护的 ``__import__``）。仅允许导入在 ``--script-allowed-imports`` 中列出的模块；运行的 "
+"FastAPI ``app`` 会注入到脚本的全局变量中。如果脚本赋值给名为 ``result`` 的变量，则返回其字符串化值；否则返回正文为 "
+"``\"脚本成功执行\"``\\ （``Content-Type: text/plain``）。"
+
+#: ../../source/mp/http_api.rst:1621
+msgid ""
+"**Request body:** multipart form data with a single ``script`` file field"
+" (the Python source to execute). Not a JSON body."
+msgstr "**请求体：** 多部分表单数据，包含一个 ``script`` 文件字段（要执行的 Python 源代码）。不是 JSON 格式的请求体。"
+
+#: ../../source/mp/http_api.rst:1626
+msgid ""
+"This endpoint runs caller-supplied code in-process. The restricted "
+"builtins are **not** a security sandbox — combined with the injected "
+"``app`` object and any allowed imports, treat it as full remote code "
+"execution. Never expose it on an untrusted network."
+msgstr ""
+"此端点在进程中运行调用者提供的代码。受限的内置函数\\ **不是**\\ 安全沙箱——结合注入的\\ ``app``\\ "
+"对象和任何允许的导入，将其视为完全的远程代码执行。切勿在不受信任的网络上公开它。"
+
+#: ../../source/mp/http_api.rst:1631
+msgid ""
+"**Response** (``200 OK``, ``text/plain``): the stringified ``result`` "
+"variable if the script assigns one, otherwise ``Script executed "
+"successfully``."
+msgstr "**响应** (``200 OK``, ``text/plain``): 如果脚本分配了字符串化的 ``result`` 变量，则返回该变量，否则返回 ``脚本成功执行``。"
+
+#: ../../source/mp/http_api.rst:1636
+msgid "``200``: script executed."
+msgstr "``200``: 脚本已执行。"
+
+#: ../../source/mp/http_api.rst:1637
+msgid "``400``: no ``script`` file provided."
+msgstr "``400``: 未提供 ``script`` 文件。"
+
+#: ../../source/mp/http_api.rst:1638
+msgid ""
+"``500``: an exception was raised during import setup or execution (body: "
+"``\"Error executing script: <reason>\"``)."
+msgstr "``500``: 在导入设置或执行期间引发了异常（主体：``\"执行脚本时出错：<reason>\"``）。"
+
+#: ../../source/mp/http_api.rst:1649
+msgid "Adding New Endpoints"
+msgstr "添加新端点"
+
+#: ../../source/mp/http_api.rst:1651
+msgid ""
+"Endpoints are auto-discovered from "
+"``lmcache/v1/multiprocess/http_apis/``. To add a new MP-only endpoint:"
+msgstr "端点会从 ``lmcache/v1/multiprocess/http_apis/`` 自动发现。要添加一个新的仅限 MP 的端点："
+
+#: ../../source/mp/http_api.rst:1654
+msgid "Create a new module in that directory named ``<name>_api.py``."
+msgstr "在该目录中创建一个名为 ``<name>_api.py`` 的新模块。"
+
+#: ../../source/mp/http_api.rst:1655
+msgid "Define a module-level ``router = APIRouter()``."
+msgstr "定义一个模块级的 ``router = APIRouter()``\\ 。"
+
+#: ../../source/mp/http_api.rst:1656
+msgid "Register handlers on ``router`` using FastAPI decorators."
+msgstr "使用 FastAPI 装饰器在 ``router`` 上注册处理程序。"
+
+#: ../../source/mp/http_api.rst:1657
+msgid ""
+"Access the engine via ``request.app.state.engine`` and guard for the "
+"``None`` case (engine not yet initialized)."
+msgstr "通过 ``request.app.state.engine`` 访问引擎，并检查 ``None`` 情况（引擎尚未初始化）。"
+
+#: ../../source/mp/http_api.rst:1660
+msgid ""
+"The :class:`~lmcache.v1.multiprocess.http_api_registry.HTTPAPIRegistry` "
+"will pick the module up automatically at startup — no central "
+"registration list to edit."
+msgstr ""
+":class:`~lmcache.v1.multiprocess.http_api_registry.HTTPAPIRegistry` "
+"将在启动时自动加载模块 — 无需编辑中央注册列表。"
+
+#: ../../source/mp/http_api.rst:1664
+msgid ""
+"If the route is generic enough to be shared with the vLLM-embedded API "
+"server, add it under ``lmcache/v1/internal_api_server/common/`` instead. "
+"It will be picked up on the MP side via ``common_api.py`` unless its "
+"module name is listed in ``_MP_INCOMPATIBLE_MODULES`` there (reserved for"
+" modules that require vLLM-specific ``app.state`` attributes; the list is"
+" currently empty). A handler that lives under "
+"``internal_api_server/vllm/`` can still be surfaced on the MP server by "
+"including its router from a group module under ``http_apis/`` (as "
+"``info_api.py`` does for the version endpoints)."
+msgstr "如果路由足够通用，可以与嵌入 vLLM 的 API 服务器共享，请将其添加到 ``lmcache/v1/internal_api_server/common/`` 下。它将在 MP 端通过 ``common_api.py`` 被加载，除非其模块名称在 ``_MP_INCOMPATIBLE_MODULES`` 中列出（该列表保留给需要 vLLM 特定 ``app.state`` 属性的模块；当前列表为空）。位于 ``internal_api_server/vllm/`` 下的处理程序仍然可以通过从 ``http_apis/`` 下的组模块中包含其路由器在 MP 服务器上显示（如 ``info_api.py`` 对版本端点所做的那样）。"
+
+#: ../../source/mp/http_api.rst:1674
+msgid ""
+"When adding a new endpoint, please also add a matching section to this "
+"page documenting the endpoint's purpose, request/response schema, and an "
+"example ``curl`` invocation."
+msgstr "添加新端点时，请在此页面上添加一个对应的章节，说明该端点的用途、请求/响应结构以及一个示例 ``curl`` 调用。"
+
+#~ msgid "\"engine_type\": \"MPCacheServer\","
+#~ msgstr "\"engine_type\": \"MPCacheServer\","
+
+#~ msgid ""
+#~ "\"chunk_size\": 256, \"hash_algorithm\": "
+#~ "\"builtin-hash\", \"registered_gpu_ids\": [0, 1],"
+#~ " \"gpu_context_meta\": {"
+#~ msgstr ""
+#~ "\"chunk_size\": 256, \"hash_algorithm\": "
+#~ "\"builtin-hash\", \"registered_gpu_ids\": [0, 1],"
+#~ " \"gpu_context_meta\": {"
+
+#~ msgid "\"0\": {"
+#~ msgstr "\\\"0\\\": {"
+
+#~ msgid ""
+#~ "\"model_name\": \"meta-llama/Llama-3.1-8B-"
+#~ "Instruct\", \"world_size\": 1, \"kv_cache_layout\":"
+#~ " {"
+#~ msgstr ""
+#~ "\\\"model_name\\\": \\\"meta-llama/Llama-3.1-8B-"
+#~ "Instruct\\\", \\\"world_size\\\": 1, "
+#~ "\\\"kv_cache_layout\\\": {"
+
+#~ msgid ""
+#~ "\"num_layers\": 32, \"num_blocks\": 12345, "
+#~ "\"cache_size_per_token\": 131072, \"kernel_groups\": "
+#~ "["
+#~ msgstr ""
+#~ "\\\"num_layers\\\": 32, \\\"num_blocks\\\": 12345,"
+#~ " \\\"cache_size_per_token\\\": 131072, "
+#~ "\\\"kernel_groups\\\": ["
+
+#~ msgid "{"
+#~ msgstr "{"
+
+#~ msgid ""
+#~ "\"kernel_group_idx\": 0, \"engine_group_idx\": 0,"
+#~ " \"object_group_idx\": 0, \"num_layers\": 32, "
+#~ "\"layer_indices\": [0, 1, \"...\"], "
+#~ "\"tokens_per_block\": 16, \"slots_per_block\": 16,"
+#~ " \"dtype\": \"torch.bfloat16\", "
+#~ "\"gpu_kv_concrete_shape\": \"...\", \"is_mla\": "
+#~ "false, \"gpu_kv_format\": \"...\", \"gpu_kv_shape\":"
+#~ " \"...\", \"attention_backend\": \"...\""
+#~ msgstr ""
+#~ "\\\"kernel_group_idx\\\": 0, \\\"engine_group_idx\\\": "
+#~ "0, \\\"object_group_idx\\\": 0, \\\"num_layers\\\":"
+#~ " 32, \\\"layer_indices\\\": [0, 1, "
+#~ "\\\"...\\\"], \\\"tokens_per_block\\\": 16, "
+#~ "\\\"slots_per_block\\\": 16, \\\"dtype\\\": "
+#~ "\\\"torch.bfloat16\\\", \\\"gpu_kv_concrete_shape\\\": "
+#~ "\\\"...\\\", \\\"is_mla\\\": false, "
+#~ "\\\"gpu_kv_format\\\": \\\"...\\\", \\\"gpu_kv_shape\\\":"
+#~ " \\\"...\\\", \\\"attention_backend\\\": \\\"...\\\""
+
+#~ msgid "}"
+#~ msgstr "}"
+
+#~ msgid "]"
+#~ msgstr "]"
+
+#~ msgid ""
+#~ "}, \"active_sessions\": 2, \"active_prefetch_jobs\":"
+#~ " 0, \"storage_manager\": {"
+#~ msgstr ""
+#~ "}, \\\"active_sessions\\\": 2, "
+#~ "\\\"active_prefetch_jobs\\\": 0, \\\"storage_manager\\\":"
+#~ " {"
+
+#~ msgid "\"is_healthy\": true, \"...\": \"backend-specific fields\""
+#~ msgstr "\\\"is_healthy\\\": true, \\\"...\\\": \\\"后端特定字段\\\""
+
+#~ msgid ""
+#~ "New endpoints are registered automatically "
+#~ "from ``lmcache/v1/multiprocess/http_apis/``: any "
+#~ "module named ``*_api.py`` that exposes a"
+#~ " module-level ``router`` (a "
+#~ ":class:`fastapi.APIRouter`) is discovered at "
+#~ "startup."
+#~ msgstr ""
+#~ "新的端点会自动从 ``lmcache/v1/multiprocess/http_apis/`` 注册：任何名为"
+#~ " ``*_api.py`` 的模块，只要暴露一个模块级的 ``router``（一个 "
+#~ ":class:`fastapi.APIRouter`），在启动时都会被发现。"
+
+#~ msgid "Basic liveness ping."
+#~ msgstr "基本存活探测。"
+
+#~ msgid "K8s liveness/readiness probe."
+#~ msgstr "K8s 存活/就绪探针。"
+
+#~ msgid "Full version descriptor (package version + commit id)."
+#~ msgstr "完整版本描述符（软件包版本 + 提交 ID）。"
+
+#~ msgid ""
+#~ "Returns a detailed snapshot of the "
+#~ "MP engine's internal state: L1 cache,"
+#~ " L2 adapters, registered GPU contexts, "
+#~ "active sessions, and in-flight prefetch"
+#~ " jobs. Intended for operators and "
+#~ "debugging, not for monitoring (use "
+#~ "Prometheus metrics for time-series data"
+#~ " — see :doc:`observability/index`)."
+#~ msgstr ""
+#~ "返回 MP 引擎内部状态的详细快照：L1 缓存、L2 适配器、注册的 GPU"
+#~ " 上下文、活动会话和正在进行的预取任务。旨在供操作员和调试使用，而非监控（使用 Prometheus "
+#~ "指标获取时间序列数据 — 参见 :doc:`observability/index`）。"
+
+#~ msgid "``/reconfigure/{backend}`` — runtime L2 adapter reconfiguration"
+#~ msgstr "``/reconfigure/{backend}`` — 运行时 L2 适配器重新配置"
+
+#~ msgid ""
+#~ "Use ``GET /reconfigure/backends`` to list "
+#~ "the backend strings that can be "
+#~ "used in ``/reconfigure/{backend}/status`` and "
+#~ "``/reconfigure/{backend}/{operation}``. If an L2 "
+#~ "adapter is wrapped by serde, the "
+#~ "backend string is still the configured"
+#~ " L2 adapter type, not the serde "
+#~ "wrapper type."
+#~ msgstr ""
+#~ "使用 ``GET /reconfigure/backends`` 列出可以在 "
+#~ "``/reconfigure/{backend}/status`` 和 "
+#~ "``/reconfigure/{backend}/{operation}`` 中使用的后端字符串。如果 L2 "
+#~ "适配器被 serde 包装，后端字符串仍然是配置的 L2 适配器类型，而不是 "
+#~ "serde 包装器类型。"
+
+#~ msgid ""
+#~ "For Device-DAX, use ``backend=dax``. DAX"
+#~ " operations use JSON request bodies "
+#~ "because DAX paths contain slashes. "
+#~ "``add`` and ``resize`` accept ``size`` "
+#~ "as an integer byte count or a "
+#~ "string such as ``\"100GiB\"``. ``remove`` "
+#~ "supports ``migrate``, ``evict``, and "
+#~ "``drain``; ``resize`` supports ``migrate`` and"
+#~ " ``evict``."
+#~ msgstr ""
+#~ "对于 Device-DAX，请使用 ``backend=dax``。DAX 操作使用 "
+#~ "JSON 请求体，因为 DAX 路径包含斜杠。``add`` 和 "
+#~ "``resize`` 接受 ``size`` 作为整数字节数或字符串，例如 "
+#~ "``\"100GiB\"``。``remove`` 支持 ``migrate``、``evict`` 和"
+#~ " ``drain``；``resize`` 支持 ``migrate`` 和 "
+#~ "``evict``。"
+
+#~ msgid "``/quota`` — per-``cache_salt`` quota management"
+#~ msgstr "``/quota`` — 每个``cache_salt``的配额管理"
+
+#~ msgid ""
+#~ "Returns the full version descriptor "
+#~ "(package version combined with the "
+#~ "current commit id), formatted by "
+#~ "``lmcache.utils.get_version()``."
+#~ msgstr "返回完整的版本描述符（软件包版本与当前提交 ID 的组合），格式由 ``lmcache.utils.get_version()`` 生成。"
+
+#~ msgid "``GET /lmc_version``"
+#~ msgstr "``GET /lmc_version``"
+
+#~ msgid ""
+#~ "Returns the raw LMCache package version"
+#~ " string (``lmcache.utils.VERSION``)."
+#~ msgstr "返回原始的 LMCache 包版本字符串 (``lmcache.utils.VERSION``)。"
+
+#~ msgid "``GET /commit_id``"
+#~ msgstr "``GET /commit_id``"
+
+#~ msgid "Detailed status for a single periodic thread (``404`` if not found)."
+#~ msgstr "单个周期性线程的详细状态（如果未找到则返回 ``404``）。"
+
+#~ msgid "**Cache control**"
+#~ msgstr "**缓存控制**"
+
+#~ msgid "``/clear-cache``"
+#~ msgstr "``/clear-cache``"
+
+#~ msgid "Force-clear all KV data in L1 (CPU) memory."
+#~ msgstr "强制清除 L1 (CPU) 内存中的所有 KV 数据。"
+
+#~ msgid "**L2 storage management**"
+#~ msgstr "**L2 存储管理**"
+
+#~ msgid ""
+#~ "Enumerate every configured L2 adapter "
+#~ "with its ``type_name`` and primary flag."
+#~ msgstr "列出每个配置的 L2 连接器及其 ``type_name`` 和主要标志。"
+
+#~ msgid "``/l2``"
+#~ msgstr "``/l2``"
+
+#~ msgid ""
+#~ "Delete a caller-supplied list of "
+#~ "keys from one L2 adapter (default: "
+#~ "primary; override with ``?adapter=<type_name>``)."
+#~ msgstr "从一个 L2 适配器中删除调用者提供的键列表（默认：主适配器；使用 ``?adapter=<type_name>`` 进行覆盖）。"
+
+#~ msgid ""
+#~ "Paginate keys currently resident in one"
+#~ " L2 adapter (optionally filtered by "
+#~ "``model_name``)."
+#~ msgstr "分页当前驻留在一个 L2 适配器中的键（可选按 ``model_name`` 过滤）。"
+
+#~ msgid "``/reconfigure/backends``"
+#~ msgstr "``/reconfigure/backends``"
+
+#~ msgid "List backend strings accepted by the reconfiguration routes."
+#~ msgstr "列出重新配置路由接受的后端字符串。"
+
+#~ msgid "Report runtime-manageable L2 adapters for one backend type."
+#~ msgstr "列出指定后端类型下可在运行时管理的 L2 适配器。"
+
+#~ msgid "Cache Control"
+#~ msgstr "缓存控制"
+
+#~ msgid "The request body is ignored."
+#~ msgstr "请求体将被忽略。"
+
+#~ msgid "L2 Storage Management"
+#~ msgstr "L2 存储管理"
+
+#~ msgid ""
+#~ "Three endpoints — ``GET /l2/adapters``, "
+#~ "``DELETE /l2``, and ``GET /l2/keys`` —"
+#~ " let operators enumerate the configured "
+#~ "L2 backends, purge keys from one, "
+#~ "and enumerate what is currently "
+#~ "resident."
+#~ msgstr ""
+#~ "三个端点 — ``GET /l2/adapters``、``DELETE /l2`` "
+#~ "和 ``GET /l2/keys`` — 允许操作员枚举配置的 L2 "
+#~ "后端，从一个后端清除键，并枚举当前驻留的内容。"
+
+#~ msgid ""
+#~ "For full request/response semantics, "
+#~ "pagination, error codes, and the event"
+#~ " flow back to the coordinator, see"
+#~ " the design doc at "
+#~ "``docs/design/v1/multiprocess/l2_apis.md``."
+#~ msgstr ""
+#~ "有关完整的请求/响应语义、分页、错误代码以及事件流回协调器的信息，请参阅设计文档 "
+#~ "``docs/design/v1/multiprocess/l2_apis.md``。"
+
+#~ msgid ""
+#~ "Enumerate every L2 adapter the engine"
+#~ " has loaded, in configuration order."
+#~ msgstr "列出引擎已加载的每个 L2 适配器，按配置顺序排列。"
+
+#~ msgid "``DELETE /l2``"
+#~ msgstr "``DELETE /l2``"
+
+#~ msgid ""
+#~ "**Body:** ``{\"keys\": [EncodedObjectKey, ...]}``"
+#~ " where each ``EncodedObjectKey`` is"
+#~ msgstr ""
+#~ "**主体:** ``{\\\"keys\\\": [EncodedObjectKey, ...]}``"
+#~ " 其中每个 ``EncodedObjectKey`` 是"
+
+#~ msgid "``GET /l2/keys``"
+#~ msgstr "``GET /l2/keys``"
+
+#~ msgid "**Body:** ``{\"limit_gb\": <float>}`` (required, finite, non-negative)."
+#~ msgstr "**主体:** ``{\\\"limit_gb\\\": <float>}`` （必需，有限，非负）。"
+
+#~ msgid "``GET /reconfigure/backends``"
+#~ msgstr "``GET /reconfigure/backends``"
+
+#~ msgid ""
+#~ "List the backend strings that can "
+#~ "be used in ``/reconfigure/{backend}/status`` "
+#~ "and ``/reconfigure/{backend}/{operation}``."
+#~ msgstr ""
+#~ "列出可以在 ``/reconfigure/{backend}/status`` 和 "
+#~ "``/reconfigure/{backend}/{operation}`` 中使用的后端字符串。"
+
+#~ msgid ""
+#~ "``enabled`` is ``false`` (and ``backends`` "
+#~ "empty) when no reconfigurable adapter is"
+#~ " present."
+#~ msgstr "``enabled`` 为 ``false``\\ （且 ``backends`` 为空）时表示没有可重新配置的适配器。"
+
+#~ msgid ""
+#~ "**HTTP status codes:** ``200`` on "
+#~ "success; ``503`` if the engine is "
+#~ "not initialized."
+#~ msgstr "**HTTP 状态码：** ``200`` 表示成功；``503`` 表示引擎未初始化。"
+
+#~ msgid ""
+#~ "**HTTP status codes:** ``200`` on "
+#~ "success; ``400`` if ``backend`` is "
+#~ "empty; ``503`` if the engine is "
+#~ "not initialized."
+#~ msgstr "**HTTP 状态码:** ``200`` 表示成功；``400`` 如果 ``backend`` 为空；``503`` 如果引擎未初始化。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/hybrid_models.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/hybrid_models.po
new file mode 100644
index 0000000..33fd5f0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/hybrid_models.po
@@ -0,0 +1,546 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-29 10:44+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/hybrid_models.rst:2
+msgid "Hybrid Attention Models"
+msgstr "Hybrid Attention 模型"
+
+#: ../../source/mp/hybrid_models.rst:4
+msgid ""
+"Some models interleave more than one attention type across their layers —"
+" most commonly **sliding-window attention** on most layers and **full "
+"attention** on a few. vLLM serves these with its *hybrid KV cache "
+"manager*, which splits the model's layers into multiple **KV cache "
+"groups** (one per attention behavior)."
+msgstr ""
+"一些模型在其层中交错使用多种注意力类型——最常见的是在大多数层上使用 **sliding-window attention**\\ "
+"，而在少数层上使用 **full attention**\\ 。vLLM 通过其混合 KV 缓存管理器来服务这些模型，该管理器将模型的层分成多个 "
+"**KV 缓存组**\\ （每种注意力行为一个）。"
+
+#: ../../source/mp/hybrid_models.rst:9
+msgid ""
+"The LMCache multiprocess connector (``LMCacheMPConnector``) supports "
+"these hybrid models: it stores and retrieves the KV cache for every "
+"group, so prefix caching and KV reuse work the same way they do for plain"
+" models."
+msgstr ""
+"LMCache 多进程连接器 (``LMCacheMPConnector``) 支持这些混合模型：它为每个组存储和检索 KV "
+"Cache，因此前缀缓存和 KV 重用的工作方式与普通模型相同。"
+
+#: ../../source/mp/hybrid_models.rst:18
+msgid "Validated hybrid models"
+msgstr "验证过的混合模型"
+
+#: ../../source/mp/hybrid_models.rst:20
+msgid "Recipe pages for the validated hybrid-attention architectures:"
+msgstr "经过验证的 hybrid attention 架构的配方页面："
+
+#: ../../source/mp/hybrid_models.rst:26 ../../source/mp/hybrid_models.rst:188
+msgid "Model"
+msgstr "模型"
+
+#: ../../source/mp/hybrid_models.rst:27 ../../source/mp/hybrid_models.rst:75
+msgid "Attention layout"
+msgstr "注意力布局"
+
+#: ../../source/mp/hybrid_models.rst:28
+msgid "Recipe"
+msgstr "配方"
+
+#: ../../source/mp/hybrid_models.rst:29
+msgid "Gemma 3"
+msgstr "Gemma 3"
+
+#: ../../source/mp/hybrid_models.rst:30 ../../source/mp/hybrid_models.rst:33
+#: ../../source/mp/hybrid_models.rst:36
+msgid "Sliding-window + full"
+msgstr "sliding window + full"
+
+#: ../../source/mp/hybrid_models.rst:31
+msgid ":doc:`/recipes/gemma3`"
+msgstr ":doc:`/recipes/gemma3`"
+
+#: ../../source/mp/hybrid_models.rst:32
+msgid "Gemma 4"
+msgstr "Gemma 4"
+
+#: ../../source/mp/hybrid_models.rst:34
+msgid ":doc:`/recipes/gemma4`"
+msgstr ":doc:`/recipes/gemma4`"
+
+#: ../../source/mp/hybrid_models.rst:35 ../../source/mp/hybrid_models.rst:80
+msgid "gpt-oss"
+msgstr "gpt-oss"
+
+#: ../../source/mp/hybrid_models.rst:37
+msgid ":doc:`/recipes/gpt_oss`"
+msgstr ":doc:`/recipes/gpt_oss`"
+
+#: ../../source/mp/hybrid_models.rst:38
+msgid "Qwen3.5 / Qwen3.6 series"
+msgstr "Qwen3.5 / Qwen3.6 系列"
+
+#: ../../source/mp/hybrid_models.rst:39
+msgid "Mamba / GDN + full"
+msgstr "Mamba / GDN + full"
+
+#: ../../source/mp/hybrid_models.rst:40
+msgid ":doc:`/recipes/qwen3_5`"
+msgstr ":doc:`/recipes/qwen3_5`"
+
+#: ../../source/mp/hybrid_models.rst:41
+msgid "DeepSeek-V4-Flash"
+msgstr "DeepSeek-V4-Flash"
+
+#: ../../source/mp/hybrid_models.rst:42
+msgid "Sparse-MLA (multiple KV groups)"
+msgstr "稀疏-MLA（多个 KV 组）"
+
+#: ../../source/mp/hybrid_models.rst:43
+msgid ":doc:`/recipes/deepseek_v4_flash`"
+msgstr ":doc:`/recipes/deepseek_v4_flash`"
+
+#: ../../source/mp/hybrid_models.rst:44
+msgid "GLM 5.1/5.2"
+msgstr "GLM 5.1/5.2"
+
+#: ../../source/mp/hybrid_models.rst:45
+msgid "Dynamic Sparse Attention (multiple KV groups)"
+msgstr "动态稀疏注意力（多个 KV 组）"
+
+#: ../../source/mp/hybrid_models.rst:46
+msgid ":doc:`/recipes/glm5_2`"
+msgstr ":doc:`/recipes/glm5_2`"
+
+#: ../../source/mp/hybrid_models.rst:47
+msgid "MiniMax-M3"
+msgstr "MiniMax-M3"
+
+#: ../../source/mp/hybrid_models.rst:48
+msgid "Sparse attention + lightning indexer (mixed KV formats in one group)"
+msgstr "稀疏注意力 + 闪电索引器（一个组中的混合 KV 格式）"
+
+#: ../../source/mp/hybrid_models.rst:49
+msgid ":doc:`/recipes/minimax_m3`"
+msgstr ":doc:`/recipes/minimax_m3`"
+
+#: ../../source/mp/hybrid_models.rst:64
+msgid "What Works"
+msgstr "已支持的内容"
+
+#: ../../source/mp/hybrid_models.rst:66
+msgid ""
+"Models whose layers all use **standard paged attention** — including "
+"hybrids that mix sliding-window and full attention — are supported with "
+"no special configuration. Examples:"
+msgstr ""
+"所有层均使用 **standard paged attention** 的模型——包括混合 sliding-window 和 full "
+"attention 的混合模型——在没有特殊配置的情况下得到支持。示例："
+
+#: ../../source/mp/hybrid_models.rst:74
+msgid "Model family"
+msgstr "模型系列"
+
+#: ../../source/mp/hybrid_models.rst:76
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/mp/hybrid_models.rst:77
+msgid "Gemma 2 / Gemma 3"
+msgstr "Gemma 2 / Gemma 3"
+
+#: ../../source/mp/hybrid_models.rst:78 ../../source/mp/hybrid_models.rst:81
+msgid "Interleaved sliding-window + full"
+msgstr "交错 sliding-window + full"
+
+#: ../../source/mp/hybrid_models.rst:79 ../../source/mp/hybrid_models.rst:82
+#: ../../source/mp/hybrid_models.rst:88
+msgid "Supported"
+msgstr "支持"
+
+#: ../../source/mp/hybrid_models.rst:83
+msgid "Qwen3.5 (and other Gated-DeltaNet hybrids)"
+msgstr "Qwen3.5（以及其他 Gated-DeltaNet 混合模型）"
+
+#: ../../source/mp/hybrid_models.rst:84
+msgid "Interleaved Mamba/GDN + full"
+msgstr "交错 Mamba/GDN + full"
+
+#: ../../source/mp/hybrid_models.rst:85
+msgid "Supported (see below)"
+msgstr "支持（见下文）"
+
+#: ../../source/mp/hybrid_models.rst:86
+msgid "Llama, Qwen2/Qwen3 (dense), Mistral, …"
+msgstr "Llama, Qwen2/Qwen3 (dense), Mistral, …"
+
+#: ../../source/mp/hybrid_models.rst:87
+msgid "Single attention type"
+msgstr "单一注意力类型"
+
+#: ../../source/mp/hybrid_models.rst:90
+msgid ""
+"Just point vLLM at the LMCache server as usual (see "
+":doc:`/getting_started/quickstart`); LMCache detects the model's KV cache"
+" groups automatically at registration time."
+msgstr ""
+"只需像往常一样将 vLLM 指向 LMCache 服务器（请参见 "
+":doc:`/getting_started/quickstart`）；LMCache 在注册时会自动检测模型的 KV 缓存组。"
+
+#: ../../source/mp/hybrid_models.rst:95
+msgid ""
+"Because ``LMCacheMPConnector`` advertises hybrid support to vLLM, vLLM "
+"keeps its hybrid KV cache manager **enabled** for these models (it does "
+"not fall back to a single unified group). You do not need ``--no-disable-"
+"hybrid-kv-cache-manager`` or any related flag."
+msgstr ""
+"因为 ``LMCacheMPConnector`` 向 vLLM 声明了混合支持，vLLM 为这些模型保持其混合 KV 缓存管理器 "
+"**启用**\\ （它不会回退到单一统一组）。您不需要 ``--no-disable-hybrid-kv-cache-manager`` "
+"或任何相关标志。"
+
+#: ../../source/mp/hybrid_models.rst:101
+msgid "Object-group separation"
+msgstr "对象组分离"
+
+#: ../../source/mp/hybrid_models.rst:103
+msgid ""
+"At KV-cache registration LMCache buckets a hybrid model's layers into "
+"**object groups** — the unit it stores and retrieves as one object. By "
+"default (``--separate-object-groups``, on) each distinct cross-chunk "
+"attention window becomes its own object group: full-attention layers form"
+" one group, and each sliding-window size (mamba / GDN included) forms "
+"another. Pass ``--no-separate-object-groups`` to keep every layer in a "
+"single full-attention object group instead (the previous behavior)."
+msgstr "在 KV-cache 注册时，LMCache 将混合模型的层分组为 **对象组** —— 它作为一个对象存储和检索的单位。默认情况下（``--separate-object-groups``，开启），每个不同的跨块注意力窗口会成为自己的对象组：全注意力层形成一个组，而每个滑动窗口大小（包括 mamba / GDN）形成另一个组。传递 ``--no-separate-object-groups`` 可以将每一层保留在一个单一的全注意力对象组中（之前的行为）。"
+
+#: ../../source/mp/hybrid_models.rst:119
+msgid ""
+"The flag is transparent to correctness — prefix caching and KV reuse "
+"behave the same either way, and a non-hybrid model (a single attention "
+"behavior) always resolves to one object group regardless of the setting. "
+"Separation organizes storage by attention window so that each group's "
+"cross-chunk window is tracked independently."
+msgstr "该标志对正确性是透明的——前缀缓存和 KV 重用在任何情况下的行为都是相同的，非混合模型（单一注意力行为）无论设置如何始终解析为一个对象组。分离通过注意力窗口组织存储，以便每个组的跨块窗口可以独立跟踪。"
+
+#: ../../source/mp/hybrid_models.rst:126
+msgid "Mamba / Linear-Attention Hybrids"
+msgstr "Mamba / Linear-Attention 混合模型"
+
+#: ../../source/mp/hybrid_models.rst:128
+msgid ""
+"Models that interleave **Mamba / Gated-DeltaNet (GDN) linear-attention "
+"layers** with full attention — the Qwen3.5 and Qwen3.6 series "
+"(``Qwen/Qwen3.5-0.8B``, ``Qwen/Qwen3.6-27B``, …), Qwen3-Next, and other "
+"GDN hybrids — are supported. Unlike a paged key/value cache, their "
+"linear-attention layers keep a recurrent **state cache** (a convolution +"
+" SSM state). LMCache reinterprets that state as an opaque page at "
+"registration time, so prefix caching and KV reuse work end to end without"
+" any model-specific transfer code."
+msgstr ""
+"将 **Mamba / Gated-DeltaNet (GDN) linear-attention layers** 与 full "
+"attention 交错的模型——Qwen3.5 和 Qwen3.6 系列（\\ ``Qwen/Qwen3.5-0.8B``, "
+"``Qwen/Qwen3.6-27B``, …）、Qwen3-Next 以及其他 GDN 混合模型——是受支持的。与分页键/值缓存不同，它们的 "
+"linear-attention layers 保持一个递归的 **状态缓存**\\ （一个卷积 + SSM 状态）。LMCache "
+"在注册时将该状态重新解释为一个不透明的页面，因此前缀缓存和 KV 重用可以端到端工作，而无需任何特定于模型的传输代码。"
+
+#: ../../source/mp/hybrid_models.rst:136
+msgid ""
+"This section is the **general procedure for any such model**. The only "
+"per-model variable is the *unified block size* ``N`` (step 1); everything"
+" else is identical across models."
+msgstr "本节是 **任何此类模型的一般过程**\\ 。唯一的每模型变量是统一块大小\\ ``N``\\ （步骤 1）；其他所有内容在模型之间是相同的。"
+
+#: ../../source/mp/hybrid_models.rst:143
+msgid "Step 1 — find the model's unified block size ``N``"
+msgstr "步骤 1 — 找到模型的统一块大小 ``N``"
+
+#: ../../source/mp/hybrid_models.rst:145
+msgid ""
+"``N`` is the **single number** that drives every other setting: the "
+"LMCache server's ``--chunk-size`` and vLLM's ``--max-num-batched-tokens``"
+" are both derived from it (step 2). Get it wrong and LMCache raises at "
+"engine startup."
+msgstr ""
+"``N`` 是驱动所有其他设置的 **单一数字**\\ ：LMCache 服务器的 ``--chunk-size`` 和 vLLM 的 "
+"``--max-num-batched-tokens`` 都源自它（步骤 2）。如果设置错误，LMCache 在引擎启动时会抛出错误。"
+
+#: ../../source/mp/hybrid_models.rst:149
+msgid ""
+"For a Mamba / GDN hybrid, vLLM forces **one** block size across all KV "
+"cache groups, chosen large enough that an attention page is at least as "
+"big as a Mamba state page. It depends on the model's head dimensions and "
+"GDN state size, so it is **model-specific — never assume a value, read it"
+" from the model**. vLLM prints it once at startup::"
+msgstr ""
+"对于 Mamba / GDN 混合模型，vLLM 强制所有 KV Cache 组使用 **一个** 块大小，选择足够大以确保注意力页面至少与 "
+"Mamba 状态页面一样大。它依赖于模型的头部维度和 GDN 状态大小，因此是 **模型特定的 — 切勿假设一个值，请从模型中读取**\\ "
+"。vLLM 在启动时打印一次："
+
+#: ../../source/mp/hybrid_models.rst:158
+msgid ""
+"You do not need LMCache, a full serving run, or the weights to be "
+"quantized to read it — just launch vLLM until the line appears, then "
+"stop. The snippet below does exactly that and prints ``N``:"
+msgstr ""
+"您不需要 LMCache、完整的服务运行或量化的权重来读取它——只需启动 vLLM，直到该行出现，然后停止。下面的代码片段正是这样做，并打印 "
+"``N``\\ ："
+
+#: ../../source/mp/hybrid_models.rst:181
+msgid ""
+"The number in ``to N tokens`` is your ``N``. Values grow with model size;"
+" for example:"
+msgstr "``to N tokens`` 中的数字就是您的 ``N``\\ 。随着模型大小的增加，值会增长；例如："
+
+#: ../../source/mp/hybrid_models.rst:189
+msgid "Unified block size ``N``"
+msgstr "统一块大小 ``N``"
+
+#: ../../source/mp/hybrid_models.rst:190
+msgid "GPUs"
+msgstr "GPU"
+
+#: ../../source/mp/hybrid_models.rst:191
+msgid "``Qwen/Qwen3.6-27B``"
+msgstr "``Qwen/Qwen3.6-27B``"
+
+#: ../../source/mp/hybrid_models.rst:192
+msgid "784"
+msgstr "784"
+
+#: ../../source/mp/hybrid_models.rst:193 ../../source/mp/hybrid_models.rst:196
+msgid "1"
+msgstr "1"
+
+#: ../../source/mp/hybrid_models.rst:194
+msgid "``Qwen/Qwen3.5-0.8B``"
+msgstr "``Qwen/Qwen3.5-0.8B``"
+
+#: ../../source/mp/hybrid_models.rst:195
+msgid "544"
+msgstr "544"
+
+#: ../../source/mp/hybrid_models.rst:199
+msgid "Step 2 — derive the three required flags from ``N``"
+msgstr "步骤 2 — 从 ``N`` 派生三个所需的标志"
+
+#: ../../source/mp/hybrid_models.rst:201
+msgid ""
+"**LMCache server** ``--chunk-size`` **= N** (or any multiple of ``N``). "
+"This is the rule the connector enforces: LMCache's chunk size must be a "
+"multiple of vLLM's unified block size, or registration fails::"
+msgstr ""
+"**LMCache 服务器** ``--chunk-size`` **= N**\\ （或任何 ``N`` "
+"的倍数）。这是连接器强制执行的规则：LMCache 的块大小必须是 vLLM 的统一块大小的倍数，否则注册将失败::"
+
+#: ../../source/mp/hybrid_models.rst:207
+msgid ""
+"**vLLM** ``--max-num-batched-tokens`` **in [N, 2·N)** — setting it equal "
+"to ``N`` is the simple, always-valid choice. Outside this range LMCache "
+"raises at engine startup. ``align`` mode snapshots the Mamba state only "
+"at the *end* of each scheduler step, so each prefill step must advance "
+"exactly one block; a larger budget would let a step skip block "
+"boundaries, leaving no snapshot for LMCache to store at those prefixes."
+msgstr ""
+"**vLLM** ``--max-num-batched-tokens`` **在 [N, 2·N)** — 将其设置为 ``N`` "
+"是简单且始终有效的选择。在此范围之外，LMCache 在引擎启动时会引发错误。\\ ``align`` 模式仅在每个调度器步骤的结束时快照 "
+"Mamba 状态，因此每个预填充步骤必须精确推进一个块；更大的预算将允许步骤跳过块边界，从而在这些前缀处没有快照可供 LMCache 存储。"
+
+#: ../../source/mp/hybrid_models.rst:214
+msgid ""
+"**vLLM** ``--mamba-cache-mode align --enable-prefix-caching`` — ``align``"
+" is mandatory (GDN backends do not support the ``all`` mode)::"
+msgstr ""
+"**vLLM** ``--mamba-cache-mode align --enable-prefix-caching`` — ``align``"
+" 是强制性的（GDN 后端不支持 ``all`` 模式）：:"
+
+#: ../../source/mp/hybrid_models.rst:223
+msgid ""
+"So for a freshly-probed model the whole derivation is just: read ``N`` "
+"(step 1), then pass ``--chunk-size N`` to the server and ``--max-num-"
+"batched-tokens N`` to vLLM."
+msgstr ""
+"因此，对于一个新探测的模型，整个推导过程就是：读取 ``N``\\ （步骤 1），然后将 ``--chunk-size N`` 传递给服务器，并将"
+" ``--max-num-batched-tokens N`` 传递给 vLLM。"
+
+#: ../../source/mp/hybrid_models.rst:227
+msgid ""
+"No ``--no-disable-hybrid-kv-cache-manager`` or attention-backend flag is "
+"needed; ``LMCacheMPConnector`` advertises hybrid support and vLLM auto-"
+"selects the GDN backend."
+msgstr ""
+"不需要 ``--no-disable-hybrid-kv-cache-manager`` 或 attention-backend 标志；\\ "
+"``LMCacheMPConnector`` 声明支持混合模型，vLLM 会自动选择 GDN 后端。"
+
+#: ../../source/mp/hybrid_models.rst:232
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/mp/hybrid_models.rst:234
+msgid ""
+"Generation is **not bit-exact** between a cached and a fresh run: GDN "
+"backends do not support vLLM's batch-invariant mode. Validate with a "
+"**score-level** comparison (see `Verifying Correctness`_), not a token-"
+"level diff."
+msgstr ""
+"生成在缓存和新运行之间\\ **不是位精确**\\ 的：GDN 后端不支持 vLLM 的批量不变模式。请使用\\ **分数级**\\ "
+"比较进行验证（参见 `验证正确性`_），而不是 token 级差异。"
+
+#: ../../source/mp/hybrid_models.rst:238
+msgid ""
+"The cached pages are **byte-opaque**, so content-aware features (CacheGen"
+" compression, CacheBlend) do not apply, and cache entries must not be "
+"shared across engines with different attention backends or kernel block "
+"sizes."
+msgstr ""
+"缓存页面是 **字节不透明** 的，因此内容感知特性（CacheGen "
+"压缩、CacheBlend）不适用，并且缓存条目不得在具有不同注意力后端或内核块大小的引擎之间共享。"
+
+#: ../../source/mp/hybrid_models.rst:241
+msgid ""
+"Several of these models are **vision-language** (they load a vision "
+"tower). The validated, supported path is **text** KV caching; image/video"
+" KV caching is not validated."
+msgstr ""
+"这些模型中的几个是 **视觉-语言** 模型（它们加载一个视觉塔）。经过验证的支持路径是 **文本** KV 缓存；图像/视频 KV "
+"缓存尚未经过验证。"
+
+#: ../../source/mp/hybrid_models.rst:244
+msgid ""
+"vLLM's Mamba prefix caching in ``align`` mode is marked experimental "
+"upstream."
+msgstr "vLLM 的 Mamba 前缀缓存在 ``align`` 模式下被标记为实验性。"
+
+#: ../../source/mp/hybrid_models.rst:246
+msgid ""
+"See the :doc:`Qwen3.5 / Qwen3.6 recipe <../recipes/qwen3_5>` for the "
+"validated end-to-end commands and the per-model block sizes."
+msgstr ""
+"请参阅 :doc:`Qwen3.5 / Qwen3.6 配方 <../recipes/qwen3_5>` "
+"以获取经过验证的端到端命令和每个模型的块大小。"
+
+#: ../../source/mp/hybrid_models.rst:250
+msgid "What Is Not Supported Yet"
+msgstr "尚未支持的内容"
+
+#: ../../source/mp/hybrid_models.rst:252
+msgid ""
+"**DeepSeek-V4-style compressed / indexer caches** are not yet handled by "
+"the multiprocess connector."
+msgstr "**DeepSeek-V4 风格的压缩 / 索引器缓存** 暂不被多进程连接器支持。"
+
+#: ../../source/mp/hybrid_models.rst:256
+msgid "Verifying Correctness"
+msgstr "验证正确性"
+
+#: ../../source/mp/hybrid_models.rst:258
+msgid ""
+"To convince yourself that a hybrid model's KV is being cached and reused "
+"correctly, you can compare a cold run against a run served from LMCache:"
+msgstr "为了确保混合模型的 KV 被正确缓存和重用，您可以将冷启动与从 LMCache 提供的运行进行比较："
+
+#: ../../source/mp/hybrid_models.rst:261
+msgid ""
+"Run an evaluation (e.g. ``lm_eval`` on ``gsm8k``) against vLLM + LMCache."
+" This computes the KV cache and **stores** it in LMCache."
+msgstr ""
+"对 vLLM + LMCache 运行评估（例如在 ``gsm8k`` 上使用 ``lm_eval``\\ ）。这会计算 KV Cache 并 "
+"**存储** 在 LMCache 中。"
+
+#: ../../source/mp/hybrid_models.rst:263
+msgid ""
+"Reset *only* vLLM's local prefix cache, leaving the LMCache-managed cache"
+" intact (requires launching vLLM with ``VLLM_SERVER_DEV_MODE=1``)::"
+msgstr ""
+"仅重置 vLLM 的本地前缀缓存，保持 LMCache 管理的缓存不变（需要以 ``VLLM_SERVER_DEV_MODE=1`` 启动 "
+"vLLM）::"
+
+#: ../../source/mp/hybrid_models.rst:268
+msgid ""
+"Omit the ``reset_external=true`` query parameter so the LMCache cache is "
+"preserved."
+msgstr "省略 ``reset_external=true`` 查询参数，以便保留 LMCache 缓存。"
+
+#: ../../source/mp/hybrid_models.rst:270
+msgid ""
+"Re-run the same evaluation. vLLM now misses in its local cache, so the "
+"prefix KV is **retrieved** from LMCache. The score should match the first"
+" run."
+msgstr "重新运行相同的评估。vLLM 现在在其本地缓存中未命中，因此前缀 KV 从 LMCache 中 **检索**\\ 。得分应与第一次运行匹配。"
+
+#: ../../source/mp/hybrid_models.rst:273
+msgid ""
+"The project ships this as the ``hma_lm_eval`` continuous-integration test"
+" (see ``.buildkite/k3_tests/multiprocess``)."
+msgstr ""
+"该项目以 ``hma_lm_eval`` 持续集成测试的形式提供此验证（参见 "
+"``.buildkite/k3_tests/multiprocess``\\ ）。"
+
+#: ../../source/mp/hybrid_models.rst:277
+msgid "See Also"
+msgstr "另请参阅"
+
+#: ../../source/mp/hybrid_models.rst:279
+msgid ""
+":doc:`/getting_started/quickstart` — launching the LMCache server and a "
+"vLLM client."
+msgstr ":doc:`/getting_started/quickstart` — 启动 LMCache 服务器和 vLLM 客户端。"
+
+#: ../../source/mp/hybrid_models.rst:280
+msgid ""
+"Design notes on how groups are detected and addressed: "
+"``docs/design/integration/vllm/hybrid-kv-cache-groups.md`` in the source "
+"tree."
+msgstr ""
+"关于如何检测和处理组的设计说明：\\ ``docs/design/integration/vllm/hybrid-kv-cache-"
+"groups.md`` 在源代码树中。"
+
+#~ msgid ""
+#~ "**Mamba / linear-attention hybrids** "
+#~ "(e.g. Qwen3-Next, Qwen3.5, and other "
+#~ "Gated-DeltaNet models). These layers keep"
+#~ " a recurrent *state cache* (a "
+#~ "convolution + SSM state) instead of "
+#~ "a paged key/value cache, which LMCache's"
+#~ " transfer path cannot represent today. "
+#~ "Such models will fail to register "
+#~ "with the LMCache server. Tracking "
+#~ "support is future work."
+#~ msgstr ""
+#~ "**Mamba / 线性注意力混合模型**（例如 Qwen3-Next、Qwen3.5 "
+#~ "和其他 Gated-DeltaNet 模型）。这些层保持一个递归的 *状态缓存*（一个卷积"
+#~ " + SSM 状态），而不是分页的键/值缓存，这在今天的 LMCache "
+#~ "传输路径中无法表示。这些模型将无法在 LMCache 服务器上注册。跟踪支持是未来的工作。"
+
+#~ msgid "Architecture"
+#~ msgstr "架构"
+
+#~ msgid "``Gemma3ForConditionalGeneration``"
+#~ msgstr "``Gemma3ForConditionalGeneration``"
+
+#~ msgid "``Gemma4ForConditionalGeneration``"
+#~ msgstr "``Gemma4ForConditionalGeneration``"
+
+#~ msgid "``GptOssForCausalLM``"
+#~ msgstr "``GptOssForCausalLM``"
+
+#~ msgid "``Qwen3_5ForConditionalGeneration``"
+#~ msgstr "``Qwen3_5ForConditionalGeneration``"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/index.po
new file mode 100644
index 0000000..b68b5b5
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/index.po
@@ -0,0 +1,1292 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/index.rst:2
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/mp/index.rst:4
+msgid ""
+"LMCache multiprocess (MP) mode runs LMCache as a **standalone service** "
+"that vLLM instances connect to over ZMQ.  One LMCache server per node can"
+" serve multiple vLLM pods, providing process isolation, shared caching, "
+"and independent resource scaling."
+msgstr ""
+"LMCache MP 模式（多进程）将 LMCache 作为一个 **独立服务** 运行，vLLM 实例通过 ZMQ 连接到该服务。每个节点的 "
+"LMCache 服务器可以为多个 vLLM Pod 提供服务，提供进程隔离、共享缓存和独立资源扩展。"
+
+#: ../../source/mp/index.rst:14
+msgid "Key Benefits"
+msgstr "主要优势"
+
+#: ../../source/mp/index.rst:16
+msgid ""
+"**Process isolation** -- LMCache and vLLM run in separate processes (or "
+"containers), so a cache-related issue does not crash the inference "
+"engine."
+msgstr "**进程隔离** -- LMCache 和 vLLM 在独立的进程（或容器）中运行，因此与缓存相关的问题不会导致推理引擎崩溃。"
+
+#: ../../source/mp/index.rst:18
+msgid ""
+"**No GIL contention or Python overhead on the inference path** -- By "
+"running LMCache in a separate process, its Python GIL and CPU work "
+"(hashing, memory management, L2 I/O) do not compete with vLLM's inference"
+" threads."
+msgstr ""
+"**推理路径上没有 GIL 争用或 Python 开销** -- 通过在单独的进程中运行 LMCache，它的 Python GIL 和 CPU "
+"工作（哈希、内存管理、L2 I/O）不会与 vLLM 的推理线程竞争。"
+
+#: ../../source/mp/index.rst:21
+msgid ""
+"**Shared caching across pods** -- Multiple vLLM instances on the same "
+"node share a single L1 cache, maximizing KV reuse."
+msgstr "**跨 Pod 共享缓存** -- 同一节点上的多个 vLLM 实例共享一个 L1 缓存，最大化 KV 重用。"
+
+#: ../../source/mp/index.rst:23
+msgid ""
+"**Independent resource scaling** -- Allocate CPU memory for caching "
+"independently of GPU memory for inference."
+msgstr "**独立资源扩展** -- 为缓存分配 CPU 内存，与用于推理的 GPU 显存独立。"
+
+#: ../../source/mp/index.rst:25
+msgid ""
+"**Multi-tier storage (L1 + L2)** -- An L1 cache (in CPU DRAM, or an NVMe "
+"slab via GPUDirect Storage) backed by persistent L2 storage via NIXL "
+"(GDS, POSIX, HF3FS, and more)."
+msgstr ""
+"**多层存储 (L1 + L2)** -- L1 缓存（在 CPU DRAM 中，或通过 GPUDirect Storage 的 NVMe "
+"块），由通过 NIXL（GDS、POSIX、HF3FS 等）的持久化 L2 存储提供支撑。"
+
+#: ../../source/mp/index.rst:28
+msgid ""
+"**Built-in observability** -- Prometheus metrics and a telemetry event "
+"system out of the box."
+msgstr "**内置可观察性** -- 开箱即用的 Prometheus 指标和遥测事件系统。"
+
+#: ../../source/mp/index.rst:32
+msgid "Prerequisites"
+msgstr "前提条件"
+
+#: ../../source/mp/index.rst:34
+msgid "**vLLM** latest version is recommended for best compatibility"
+msgstr "**vLLM** 建议使用最新版本以获得最佳兼容性"
+
+#: ../../source/mp/index.rst:35
+msgid "**LMCache** latest dev branch"
+msgstr "**LMCache** 最新开发分支"
+
+#: ../../source/mp/index.rst:38
+msgid "Server Variants"
+msgstr "服务器变体"
+
+#: ../../source/mp/index.rst:40
+msgid "LMCache ships two server entry points:"
+msgstr "LMCache 提供两个服务器入口点："
+
+#: ../../source/mp/index.rst:46
+msgid "Entry Point"
+msgstr "入口点"
+
+#: ../../source/mp/index.rst:47 ../../source/mp/index.rst:155
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/index.rst:48
+msgid "``lmcache server``"
+msgstr "``lmcache server``"
+
+#: ../../source/mp/index.rst:49
+msgid "**Recommended.** ZMQ + FastAPI HTTP frontend — see :doc:`http_api`."
+msgstr "**推荐。** ZMQ + FastAPI HTTP 前端 — 参见 :doc:`http_api`。"
+
+#: ../../source/mp/index.rst:50
+msgid "``python3 -m lmcache.v1.multiprocess.server``"
+msgstr "``python3 -m lmcache.v1.multiprocess.server``"
+
+#: ../../source/mp/index.rst:51
+msgid ""
+"(Legacy) ZMQ-only server with no HTTP endpoints; same ``--engine-type`` /"
+" ``--supported-transfer-mode`` flags as ``lmcache server``. Prefer "
+"``lmcache server``."
+msgstr ""
+"（旧版）仅支持 ZMQ 的服务器，没有 HTTP 端点；与 ``lmcache server`` 相同的 ``--engine-type`` / "
+"``--supported-transfer-mode`` 标志。建议使用 ``lmcache server``\\ 。"
+
+#: ../../source/mp/index.rst:55
+msgid ""
+"The sections below describe LMCache MP internals -- useful if you want to"
+" understand, debug, or extend the system."
+msgstr "以下部分介绍 LMCache MP 模式的内部实现，适合希望了解、调试或扩展该系统的读者。"
+
+#: ../../source/mp/index.rst:59
+msgid "High-Level Architecture"
+msgstr "高层架构"
+
+#: ../../source/mp/index.rst:91
+msgid "Engine and Modules"
+msgstr "引擎和模块"
+
+#: ../../source/mp/index.rst:93
+msgid ""
+"All server entry points share the same ``MPCacheServer`` and "
+"``StorageManager`` core. ``MPCacheServer`` is now a thin compositor: it "
+"holds an ``MPCacheServerContext`` and a list of ``EngineModule`` "
+"instances assembled by ``_build_modules()`` (in ``server.py``) based on "
+"``--engine-type`` and ``--supported-transfer-mode``."
+msgstr ""
+"所有服务器入口点共享相同的 ``MPCacheServer`` 和 ``StorageManager`` 核心。``MPCacheServer``"
+" 现在是一个轻量级合成器：它持有一个 ``MPCacheServerContext`` 和一个由 ``_build_modules()``\\ "
+"（在 ``server.py`` 中）基于 ``--engine-type`` 和 ``--supported-transfer-mode`` "
+"组装的 ``EngineModule`` 实例列表。"
+
+#: ../../source/mp/index.rst:99
+msgid ""
+"**``server.py``** -- The default ZMQ-only server.  Creates an "
+"``MPCacheServer``, assembles the engine modules (``LookupModule`` + "
+"``ManagementModule`` + ``LMCacheDrivenTransferModule`` and/or "
+"``EngineDrivenTransferModule`` depending on ``--supported-transfer-mode``"
+" — ``lmcache_driven`` or ``engine_driven`` loads just one, ``auto`` "
+"(default) loads both — plus a CacheBlend module when ``--engine-type`` is"
+" set: ``blend`` appends ``BlendV3Module`` (the current paged-aware "
+"implementation), and ``blend_legacy`` appends ``BlendModule`` (the "
+"original)). Starts a ``MessageQueueServer``, registers handlers for every"
+" ``RequestType`` exposed by the loaded modules, and blocks in a keep-"
+"alive loop."
+msgstr ""
+"**``server.py``** -- 默认的纯 ZMQ 服务器。创建 ``MPCacheServer``\\ ，组装引擎模块（\\ "
+"``LookupModule`` + ``ManagementModule`` + ``LMCacheDrivenTransferModule``"
+" 和/或 ``EngineDrivenTransferModule``\\ ，具体取决于 ``--supported-transfer-"
+"mode`` — ``lmcache_driven`` 或 ``engine_driven`` 仅加载其中一个，\\ ``auto``\\ "
+"（默认）两者均加载 — 当设置了 ``--engine-type`` 时，还会附加 CacheBlend 模块：\\ ``blend`` 附加 "
+"``BlendV3Module``\\ （当前的分页感知实现），\\ ``blend_legacy`` 附加 ``BlendModule``\\ "
+"（原始实现））。启动 ``MessageQueueServer``\\ ，为已加载模块暴露的每个 ``RequestType`` "
+"注册处理程序，并在保活循环中阻塞。"
+
+#: ../../source/mp/index.rst:112
+msgid ""
+"**``modules/blend.py``** -- Defines ``BlendModule`` and "
+"``BlendEngineV2``, which add the original CacheBlend operations "
+"(``CB_REGISTER_KV_CACHE``, ``CB_LOOKUP_PRE_COMPUTED``, "
+"``CB_STORE_PRE_COMPUTED``, ``CB_RETRIEVE_PRE_COMPUTED``, "
+"``CB_STORE_FINAL`` and their V2 variants). Enables non-prefix KV cache "
+"reuse across document paragraphs. Selected by passing ``--engine-type "
+"blend_legacy`` to ``lmcache server``."
+msgstr ""
+"**``modules/blend.py``** -- 定义了 ``BlendModule`` 和 ``BlendEngineV2``\\ "
+"，它们添加了原始的 CacheBlend 操作（\\ ``CB_REGISTER_KV_CACHE``, "
+"``CB_LOOKUP_PRE_COMPUTED``, ``CB_STORE_PRE_COMPUTED``, "
+"``CB_RETRIEVE_PRE_COMPUTED``, ``CB_STORE_FINAL`` 及其 V2 变体）。启用跨文档段落的非前缀 KV"
+" Cache 重用。通过将 ``--engine-type blend_legacy`` 传递给 ``lmcache server`` 进行选择。"
+
+#: ../../source/mp/index.rst:120
+msgid ""
+"**``modules/blend_v3.py``** -- Defines ``BlendV3Module``, the paged-aware"
+" CacheBlend V3 pipeline that runs on the sparse-prefetch path. Adds the "
+"V3 RPCs (``CB_REGISTER_ROPE_V3``, ``CB_UNREGISTER_ROPE_V3``, "
+"``CB_RETRIEVE_PRE_COMPUTED_V3``, ``CB_UNIFIED_LOOKUP``) and reuses the "
+"existing ``LMCacheDrivenTransferModule`` and ``LookupModule``. Selected "
+"by passing ``--engine-type blend`` to ``lmcache server``."
+msgstr ""
+"**``modules/blend_v3.py``** -- 定义了 ``BlendV3Module``\\ ，这是一个分页感知的 "
+"CacheBlend V3 流水线，运行在稀疏预取路径上。新增了 V3 RPC（\\ ``CB_REGISTER_ROPE_V3``\\ 、\\ "
+"``CB_UNREGISTER_ROPE_V3``\\ 、\\ ``CB_RETRIEVE_PRE_COMPUTED_V3``\\ 、\\ "
+"``CB_UNIFIED_LOOKUP``\\ ），并复用现有的 ``LMCacheDrivenTransferModule`` 和 "
+"``LookupModule``\\ 。通过向 ``lmcache server`` 传递 ``--engine-type blend`` "
+"来启用。"
+
+#: ../../source/mp/index.rst:129
+msgid ""
+"Both blend variants require ``--supported-transfer-mode`` to be "
+"``lmcache_driven`` or ``auto`` and will refuse to load when it is "
+"``engine_driven``."
+msgstr ""
+"两种 blend 变体都要求 ``--supported-transfer-mode`` 为 ``lmcache_driven`` 或 "
+"``auto``\\ ，当其为 ``engine_driven`` 时将拒绝加载。"
+
+#: ../../source/mp/index.rst:133
+msgid ""
+"**``http_server.py``** -- Wraps ``run_cache_server()`` (from "
+"``server.py``) inside a FastAPI application.  Endpoints are contributed "
+"by modules under ``http_apis/`` and auto-registered via "
+"``HTTPAPIRegistry``: ``GET /`` (basic liveness), ``GET /healthcheck`` for"
+" Kubernetes probes, ``POST /cache/clear`` for clearing all KV cache data "
+"in L1 (CPU) memory, and ``GET /status`` for inspecting detailed internal "
+"state.  The ZMQ server runs as part of the same process, and any "
+"configured runtime plugins are spawned by ``MPRuntimePluginLauncher`` "
+"during FastAPI startup."
+msgstr "**``http_server.py``** -- 将 ``run_cache_server()``（来自 ``server.py``）封装在 FastAPI 应用程序中。端点由 ``http_apis/`` 下的模块贡献，并通过 ``HTTPAPIRegistry`` 自动注册：``GET /``（基本存活检查）、``GET /healthcheck`` 用于 Kubernetes 探针、``POST /cache/clear`` 用于清除 L1（CPU）内存中的所有 KV Cache 数据，以及 ``GET /status`` 用于检查详细的内部状态。ZMQ 服务器作为同一进程的一部分运行，任何配置的运行时插件在 FastAPI 启动期间由 ``MPRuntimePluginLauncher`` 生成。"
+
+#: ../../source/mp/index.rst:143
+msgid "ZMQ Protocol"
+msgstr "ZMQ 协议"
+
+#: ../../source/mp/index.rst:145
+msgid "Communication between vLLM and LMCache uses ZMQ (DEALER/ROUTER pattern)."
+msgstr "vLLM 和 LMCache 之间的通信使用 ZMQ（DEALER/ROUTER 模式）。"
+
+#: ../../source/mp/index.rst:147
+msgid "**RequestType enum** (defined in ``protocols/base.py``):"
+msgstr "**RequestType 枚举**\\ （在 ``protocols/base.py`` 中定义）："
+
+#: ../../source/mp/index.rst:153
+msgid "Request Type"
+msgstr "请求类型"
+
+#: ../../source/mp/index.rst:154
+msgid "Handler Type"
+msgstr "处理程序类型"
+
+#: ../../source/mp/index.rst:156
+msgid "``REGISTER_KV_CACHE``"
+msgstr "``REGISTER_KV_CACHE``"
+
+#: ../../source/mp/index.rst:157 ../../source/mp/index.rst:160
+#: ../../source/mp/index.rst:163 ../../source/mp/index.rst:171
+#: ../../source/mp/index.rst:233 ../../source/mp/index.rst:243
+#: ../../source/mp/index.rst:246 ../../source/mp/index.rst:249
+#: ../../source/mp/index.rst:273 ../../source/mp/index.rst:277
+msgid "SYNC"
+msgstr "同步"
+
+#: ../../source/mp/index.rst:158
+msgid "Register GPU KV cache tensors for a vLLM instance."
+msgstr "为 vLLM 实例注册 GPU KV Cache 张量。"
+
+#: ../../source/mp/index.rst:159
+msgid "``UNREGISTER_KV_CACHE``"
+msgstr "``UNREGISTER_KV_CACHE``"
+
+#: ../../source/mp/index.rst:161
+msgid "Unregister KV cache tensors."
+msgstr "注销 KV Cache 张量。"
+
+#: ../../source/mp/index.rst:162
+msgid "``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``"
+msgstr "``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``"
+
+#: ../../source/mp/index.rst:164
+msgid ""
+"Register an engine-driven KV cache context (CPU/accelerator workers using"
+" the PREPARE/COMMIT transfer path). Loaded only when ``--supported-"
+"transfer-mode`` is ``engine_driven`` or ``auto``. Returns a "
+"``RegisterEngineDrivenContextResponse`` carrying the SHM segment name and"
+" pool size when the SHM path is in use (empty for the pickle path)."
+msgstr ""
+"注册一个引擎驱动的 KV Cache 上下文（使用 PREPARE/COMMIT 传输路径的 CPU/加速器工作线程）。仅在 "
+"``--supported-transfer-mode`` 为 ``engine_driven`` 或 ``auto`` 时加载。当使用 SHM "
+"路径时，返回一个 ``RegisterEngineDrivenContextResponse``\\ ，携带 SHM 段名称和池大小（对于 "
+"pickle 路径为空）。"
+
+#: ../../source/mp/index.rst:170
+msgid "``UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``"
+msgstr "``UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``"
+
+#: ../../source/mp/index.rst:172
+msgid "Unregister an engine-driven KV cache context."
+msgstr "注销引擎驱动的 KV Cache 上下文。"
+
+#: ../../source/mp/index.rst:173
+msgid "``STORE``"
+msgstr "``STORE``"
+
+#: ../../source/mp/index.rst:174 ../../source/mp/index.rst:179
+#: ../../source/mp/index.rst:184 ../../source/mp/index.rst:189
+#: ../../source/mp/index.rst:194 ../../source/mp/index.rst:200
+#: ../../source/mp/index.rst:205 ../../source/mp/index.rst:209
+#: ../../source/mp/index.rst:213 ../../source/mp/index.rst:218
+#: ../../source/mp/index.rst:223 ../../source/mp/index.rst:227
+#: ../../source/mp/index.rst:230 ../../source/mp/index.rst:236
+#: ../../source/mp/index.rst:239 ../../source/mp/index.rst:252
+#: ../../source/mp/index.rst:255 ../../source/mp/index.rst:258
+#: ../../source/mp/index.rst:261 ../../source/mp/index.rst:264
+#: ../../source/mp/index.rst:269 ../../source/mp/index.rst:281
+#: ../../source/mp/index.rst:285 ../../source/mp/index.rst:291
+#: ../../source/mp/index.rst:300 ../../source/mp/index.rst:306
+msgid "BLOCKING"
+msgstr "阻塞"
+
+#: ../../source/mp/index.rst:175
+msgid ""
+"Store KV cache chunks from GPU to L1 (CPU). LMCache-driven transfer path "
+"(CUDA IPC); loaded only when ``--supported-transfer-mode`` is "
+"``lmcache_driven`` or ``auto``."
+msgstr ""
+"将 KV Cache 块从 GPU 存储到 L1 (CPU)。基于 LMCache 的传输路径 (CUDA IPC)；仅在 "
+"``--supported-transfer-mode`` 为 ``lmcache_driven`` 或 ``auto`` 时加载。"
+
+#: ../../source/mp/index.rst:178
+msgid "``RETRIEVE``"
+msgstr "``RETRIEVE``"
+
+#: ../../source/mp/index.rst:180
+msgid ""
+"Copy KV cache chunks from L1 (CPU) back to GPU. LMCache-driven transfer "
+"path (CUDA IPC); loaded only when ``--supported-transfer-mode`` is "
+"``lmcache_driven`` or ``auto``."
+msgstr ""
+"将 KV Cache 块从 L1 (CPU) 复制回 GPU。由 LMCache 驱动的传输路径 (CUDA IPC)；仅在 "
+"``--supported-transfer-mode`` 为 ``lmcache_driven`` 或 ``auto`` 时加载。"
+
+#: ../../source/mp/index.rst:183
+msgid "``PREPARE_STORE``"
+msgstr "``PREPARE_STORE``"
+
+#: ../../source/mp/index.rst:185
+msgid ""
+"(Engine-driven path) Worker asks the server to prepare store-side "
+"transfer state for a key. Loaded when ``--supported-transfer-mode`` is "
+"``engine_driven`` or ``auto``."
+msgstr ""
+"（引擎驱动路径）工作线程请求服务器为一个键准备存储端传输状态。当 ``--supported-transfer-mode`` 设置为 "
+"``engine_driven`` 或 ``auto`` 时加载。"
+
+#: ../../source/mp/index.rst:188
+msgid "``COMMIT_STORE``"
+msgstr "``COMMIT_STORE``"
+
+#: ../../source/mp/index.rst:190
+msgid ""
+"(Engine-driven path) Worker commits the chunk's serialized bytes (pickle "
+"path) or releases the prepared SHM slot (SHM path) so the server can "
+"persist into L1 storage."
+msgstr "（引擎驱动路径）工作线程提交块的序列化字节（pickle 路径），或释放已准备好的共享内存槽（SHM 路径），以便服务器将数据持久化到 L1 存储。"
+
+#: ../../source/mp/index.rst:193
+msgid "``PREPARE_RETRIEVE``"
+msgstr "``PREPARE_RETRIEVE``"
+
+#: ../../source/mp/index.rst:195
+msgid ""
+"(Engine-driven path) Worker asks the server to prepare the retrieval "
+"payload for a key. The pickle path returns the bytes inline; the SHM path"
+" returns slot info so the worker can read from shared memory."
+msgstr "（引擎驱动路径）工作线程请求服务器为指定键准备检索负载。pickle 路径直接内联返回字节；SHM 路径返回槽位信息，供工作线程从共享内存中读取。"
+
+#: ../../source/mp/index.rst:199
+msgid "``COMMIT_RETRIEVE``"
+msgstr "``COMMIT_RETRIEVE``"
+
+#: ../../source/mp/index.rst:201
+msgid ""
+"(Engine-driven path) Worker acknowledges retrieval completion so the "
+"server can release the underlying read locks and reclaim any transport "
+"state."
+msgstr "（引擎驱动路径）工作线程确认检索完成，服务器随即释放底层读取锁并回收相关传输状态。"
+
+#: ../../source/mp/index.rst:204
+msgid "``LOOKUP``"
+msgstr "``LOOKUP``"
+
+#: ../../source/mp/index.rst:206
+msgid ""
+"Submit a prefix lookup; the prefetch job is tracked server-side by "
+"request_id."
+msgstr "提交前缀查找；预取任务由 request_id 在服务器端跟踪。"
+
+#: ../../source/mp/index.rst:208
+msgid "``QUERY_PREFETCH_STATUS``"
+msgstr "``QUERY_PREFETCH_STATUS``"
+
+#: ../../source/mp/index.rst:210
+msgid ""
+"Poll a prefetch job by request_id. Returns the loaded chunk count when "
+"done, or ``None`` while the prefetch is still in progress."
+msgstr "通过 request_id 查询预取作业。当完成时返回已加载的块数，预取仍在进行中时返回 ``None``\\ 。"
+
+#: ../../source/mp/index.rst:212
+msgid "``WAIT_PREFETCH_STATUS``"
+msgstr "``WAIT_PREFETCH_STATUS``"
+
+#: ../../source/mp/index.rst:214
+msgid ""
+"(SGLang only) Block until a prefetch job completes, then return its "
+"loaded chunk count, or ``None`` on timeout. The blocking alternative to "
+"polling ``QUERY_PREFETCH_STATUS``."
+msgstr ""
+"（仅限 SGLang）阻塞直到预取作业完成，然后返回其加载的块数，超时则返回 ``None``。这是轮询 "
+"``QUERY_PREFETCH_STATUS`` 的阻塞替代方案。"
+
+#: ../../source/mp/index.rst:217
+msgid "``QUERY_PREFETCH_LOOKUP_HITS``"
+msgstr "``QUERY_PREFETCH_LOOKUP_HITS``"
+
+#: ../../source/mp/index.rst:219
+msgid ""
+"Query the lookup-phase hit chunk count by request_id, before the prefetch"
+" finishes. Returns ``None`` while the lookup is still running."
+msgstr "在预取完成之前，通过 request_id 查询查找阶段的命中块计数。当查找仍在运行时返回 ``None``\\ 。"
+
+#: ../../source/mp/index.rst:222
+msgid "``FREE_LOOKUP_LOCKS``"
+msgstr "``FREE_LOOKUP_LOCKS``"
+
+#: ../../source/mp/index.rst:224
+msgid "Release read locks from a cancelled lookup without doing a full RETRIEVE."
+msgstr "从取消的查找中释放读取锁，而无需执行完整的检索。"
+
+#: ../../source/mp/index.rst:226
+msgid "``END_SESSION``"
+msgstr "``END_SESSION``"
+
+#: ../../source/mp/index.rst:228
+msgid "Remove session state for a finished request."
+msgstr "移除已完成请求的会话状态。"
+
+#: ../../source/mp/index.rst:229
+msgid "``CLEAR``"
+msgstr "``CLEAR``"
+
+#: ../../source/mp/index.rst:231
+msgid "Clear all cached data."
+msgstr "清除所有缓存数据。"
+
+#: ../../source/mp/index.rst:232
+msgid "``GET_CHUNK_SIZE``"
+msgstr "``GET_CHUNK_SIZE``"
+
+#: ../../source/mp/index.rst:234
+msgid "Return the server's chunk size."
+msgstr "返回服务器的块大小。"
+
+#: ../../source/mp/index.rst:235
+msgid "``PING``"
+msgstr "``PING``"
+
+#: ../../source/mp/index.rst:237
+msgid "Liveness ping; the handler always returns ``True``."
+msgstr "存活 ping；处理程序始终返回 ``True``\\ 。"
+
+#: ../../source/mp/index.rst:238
+msgid "``REPORT_BLOCK_ALLOCATION``"
+msgstr "``REPORT_BLOCK_ALLOCATION``"
+
+#: ../../source/mp/index.rst:240
+msgid ""
+"Fire-and-forget channel for the vLLM scheduler to report GPU block "
+"allocation events to the observability subsystem."
+msgstr "vLLM 调度器的即发即忘通道，用于向可观察性子系统上报 GPU 块分配事件。"
+
+#: ../../source/mp/index.rst:242
+msgid "``NOOP``"
+msgstr "``NOOP``"
+
+#: ../../source/mp/index.rst:244
+msgid "Debug heartbeat -- returns a confirmation string."
+msgstr "调试心跳 -- 返回确认字符串。"
+
+#: ../../source/mp/index.rst:245
+msgid "``CB_REGISTER_KV_CACHE``"
+msgstr "``CB_REGISTER_KV_CACHE``"
+
+#: ../../source/mp/index.rst:247
+msgid "(Blend) Register CacheBlend KV buffer."
+msgstr "(Blend) 注册 CacheBlend KV 缓冲区。"
+
+#: ../../source/mp/index.rst:248
+msgid "``CB_UNREGISTER_KV_CACHE``"
+msgstr "``CB_UNREGISTER_KV_CACHE``"
+
+#: ../../source/mp/index.rst:250
+msgid "(Blend) Unregister CacheBlend KV buffer."
+msgstr "(Blend) 取消注册 CacheBlend KV 缓冲区。"
+
+#: ../../source/mp/index.rst:251
+msgid "``CB_STORE_PRE_COMPUTED``"
+msgstr "``CB_STORE_PRE_COMPUTED``"
+
+#: ../../source/mp/index.rst:253
+msgid "(Blend) Store pre-computed paragraph chunks."
+msgstr "（Blend）存储预计算的段落块。"
+
+#: ../../source/mp/index.rst:254
+msgid "``CB_LOOKUP_PRE_COMPUTED``"
+msgstr "``CB_LOOKUP_PRE_COMPUTED``"
+
+#: ../../source/mp/index.rst:256
+msgid "(Blend) Lookup pre-computed paragraph chunks."
+msgstr "(Blend) 查找预计算段块。"
+
+#: ../../source/mp/index.rst:257
+msgid "``CB_RETRIEVE_PRE_COMPUTED``"
+msgstr "``CB_RETRIEVE_PRE_COMPUTED``"
+
+#: ../../source/mp/index.rst:259
+msgid "(Blend) Retrieve pre-computed paragraph chunks to GPU."
+msgstr "(Blend) 将预计算的段落块检索到 GPU。"
+
+#: ../../source/mp/index.rst:260
+msgid "``CB_STORE_FINAL``"
+msgstr "``CB_STORE_FINAL``"
+
+#: ../../source/mp/index.rst:262
+msgid "(Blend) Store final blended chunks."
+msgstr "(Blend) 存储最终混合块。"
+
+#: ../../source/mp/index.rst:263
+msgid "``CB_LOOKUP_PRE_COMPUTED_V2``"
+msgstr "``CB_LOOKUP_PRE_COMPUTED_V2``"
+
+#: ../../source/mp/index.rst:265
+msgid ""
+"(Blend V2) Lookup pre-computed chunks; returns ``CBMatchResult`` entries "
+"(with old/cur ranges and per-chunk hashes) so the retrieve step can skip "
+"re-hashing."
+msgstr "（Blend V2）查找预计算块；返回 ``CBMatchResult`` 条目（包含旧范围/当前范围和每块哈希），以便检索步骤可以跳过重新哈希。"
+
+#: ../../source/mp/index.rst:268
+msgid "``CB_RETRIEVE_PRE_COMPUTED_V2``"
+msgstr "``CB_RETRIEVE_PRE_COMPUTED_V2``"
+
+#: ../../source/mp/index.rst:270
+msgid ""
+"(Blend V2) Retrieve pre-computed chunks using the ``CBMatchResult`` list "
+"returned by ``CB_LOOKUP_PRE_COMPUTED_V2``."
+msgstr ""
+"（Blend V2）使用 ``CB_LOOKUP_PRE_COMPUTED_V2`` 返回的 ``CBMatchResult`` "
+"列表检索预计算的块。"
+
+#: ../../source/mp/index.rst:272
+msgid "``CB_REGISTER_ROPE_V3``"
+msgstr "``CB_REGISTER_ROPE_V3``"
+
+#: ../../source/mp/index.rst:274
+msgid ""
+"(Blend V3) Share the RoPE cos/sin cache onto a context already registered"
+" via ``REGISTER_KV_CACHE``."
+msgstr "(Blend V3) 将 RoPE cos/sin 缓存共享到已经通过 ``REGISTER_KV_CACHE`` 注册的上下文中。"
+
+#: ../../source/mp/index.rst:276
+msgid "``CB_UNREGISTER_ROPE_V3``"
+msgstr "``CB_UNREGISTER_ROPE_V3``"
+
+#: ../../source/mp/index.rst:278
+msgid ""
+"(Blend V3) Drop the RoPE state (paged KV cache lives on; use "
+"``UNREGISTER_KV_CACHE`` to release that)."
+msgstr "(Blend V3) 丢弃 RoPE 状态（分页 KV Cache 仍然存在；使用 ``UNREGISTER_KV_CACHE`` 来释放它）。"
+
+#: ../../source/mp/index.rst:280
+msgid "``CB_RETRIEVE_PRE_COMPUTED_V3``"
+msgstr "``CB_RETRIEVE_PRE_COMPUTED_V3``"
+
+#: ../../source/mp/index.rst:282
+msgid ""
+"(Blend V3) Scatter all matched chunks (prefix- and non-prefix-hit) into "
+"paged KV by per-token block ID; re-RoPE only the shifted subset."
+msgstr "（Blend V3）将所有匹配的块（前缀命中和非前缀命中）按各 token 块 ID 分散写入分页 KV；仅对发生偏移的子集重新应用 RoPE。"
+
+#: ../../source/mp/index.rst:284
+msgid "``CB_UNIFIED_LOOKUP``"
+msgstr "``CB_UNIFIED_LOOKUP``"
+
+#: ../../source/mp/index.rst:286
+msgid ""
+"(Blend V3) Sole live lookup path: one RPC runs prefix + non-prefix match,"
+" reconciles, issues one sparse-coalesced prefetch, and classifies per-TP-"
+"rank. Returns ``CBUnifiedLookupResult`` (or ``None`` while the prefetch "
+"is still in flight)."
+msgstr ""
+"（Blend V3）唯一的实时查找路径：单次 RPC 同时执行前缀匹配和非前缀匹配，完成协调后发起一次稀疏合并预取，并按 TP rank "
+"进行分类。返回 ``CBUnifiedLookupResult``\\ （预取仍在进行时返回 ``None``\\ ）。"
+
+#: ../../source/mp/index.rst:290
+msgid "``P2P_LOOKUP_AND_LOCK``"
+msgstr "``P2P_LOOKUP_AND_LOCK``"
+
+#: ../../source/mp/index.rst:292
+msgid ""
+"(P2P) Look up the given keys and read-lock the locally cached prefix. "
+"Returns a task id which the caller passes to ``P2P_QUERY_LOOKUP_RESULTS``"
+" to poll for the transfer addresses. Served by ``P2PController`` (loaded "
+"unconditionally by ``_build_modules()``); whether this server also acts "
+"as a P2P client is controlled by ``--p2p-advertise-url`` -- see "
+":doc:`p2p`."
+msgstr "（P2P）查找给定的键并对本地缓存的前缀进行读锁。返回一个任务 ID，调用者将其传递给 ``P2P_QUERY_LOOKUP_RESULTS`` 以轮询传输地址。由 ``P2PController`` 提供服务（由 ``_build_modules()`` 无条件加载）；该服务器是否还充当 P2P 客户端由 ``--p2p-advertise-url`` 控制 -- 参见 :doc:`p2p`。"
+
+#: ../../source/mp/index.rst:299
+msgid "``P2P_QUERY_LOOKUP_RESULTS``"
+msgstr "``P2P_QUERY_LOOKUP_RESULTS``"
+
+#: ../../source/mp/index.rst:301
+msgid ""
+"(P2P) Poll the transfer addresses for a lookup task. Returns a list of "
+"``TransferChannelAddress`` once the lookup is complete, or ``None`` while"
+" the lookup is still in progress or its results have already been "
+"consumed."
+msgstr ""
+"(P2P) 查询查找任务的传输地址。查找完成后返回一个 ``TransferChannelAddress`` "
+"列表，或者在查找仍在进行中或其结果已被消费时返回 ``None``。"
+
+#: ../../source/mp/index.rst:305
+msgid "``P2P_UNLOCK_OBJECTS``"
+msgstr "``P2P_UNLOCK_OBJECTS``"
+
+#: ../../source/mp/index.rst:307
+msgid ""
+"(P2P) Release the read locks previously taken by ``P2P_LOOKUP_AND_LOCK`` "
+"on the given keys."
+msgstr "(P2P) 释放之前由 ``P2P_LOOKUP_AND_LOCK`` 在给定键上获取的读锁。"
+
+#: ../../source/mp/index.rst:310
+msgid "**Handler types:**"
+msgstr "**处理程序类型:**"
+
+#: ../../source/mp/index.rst:312
+msgid "**SYNC** -- Runs directly in the ZMQ main loop (fast, non-blocking)."
+msgstr "**SYNC** -- 直接在 ZMQ 主循环中运行（快速，非阻塞）。"
+
+#: ../../source/mp/index.rst:313
+msgid ""
+"**BLOCKING** -- Dispatched to a thread pool (may involve GPU copies or "
+"I/O)."
+msgstr "**BLOCKING** -- 分发到线程池执行（可能涉及 GPU 拷贝或 I/O）。"
+
+#: ../../source/mp/index.rst:316
+msgid "Config System"
+msgstr "配置系统"
+
+#: ../../source/mp/index.rst:318
+msgid "Each config module exposes a composable triple:"
+msgstr "每个配置模块都暴露一个可组合的三元组："
+
+#: ../../source/mp/index.rst:324
+msgid "``server.py:parse_args()`` composes them:"
+msgstr "``server.py:parse_args()`` 组合它们："
+
+#: ../../source/mp/index.rst:337
+msgid ""
+"``http_server.py`` reuses this pattern, adding "
+"``add_http_frontend_args()`` and ``add_coordinator_args()`` for the "
+"``lmcache server`` CLI. CacheBlend is no longer a separate entry point — "
+"it is opted into at runtime by passing ``--engine-type`` to ``server.py``"
+" (or ``lmcache server``). ``--engine-type blend`` appends "
+"``BlendV3Module`` (the current paged-aware implementation), while "
+"``--engine-type blend_legacy`` appends ``BlendModule`` (the original)."
+msgstr ""
+"``http_server.py`` 复用该模式，为 ``lmcache server`` CLI 额外添加了 "
+"``add_http_frontend_args()`` 和 ``add_coordinator_args()``\\ 。CacheBlend "
+"不再作为独立入口点，而是在运行时通过向 ``server.py``\\ （或 ``lmcache server``\\ ）传递 "
+"``--engine-type`` 来启用：\\ ``--engine-type blend`` 附加 ``BlendV3Module``\\ "
+"（当前的分页感知实现），\\ ``--engine-type blend_legacy`` 附加 ``BlendModule``\\ "
+"（原始实现）。"
+
+#: ../../source/mp/index.rst:346
+msgid "Distributed Storage"
+msgstr "分布式存储"
+
+#: ../../source/mp/index.rst:349
+msgid "StorageManager"
+msgstr "StorageManager"
+
+#: ../../source/mp/index.rst:351 ../../source/mp/index.rst:615
+msgid "``lmcache/v1/distributed/storage_manager.py``"
+msgstr "``lmcache/v1/distributed/storage_manager.py``"
+
+#: ../../source/mp/index.rst:353
+msgid ""
+"The top-level manager that wires together L1, L2, and all controllers.  "
+"Key methods:"
+msgstr "将 L1、L2 和所有控制器连接在一起的顶级管理器。关键方法："
+
+#: ../../source/mp/index.rst:356
+msgid "``reserve_write()`` / ``finish_write()`` -- Two-phase write into L1."
+msgstr "``reserve_write()`` / ``finish_write()`` -- 对 L1 的两阶段写入。"
+
+#: ../../source/mp/index.rst:357
+msgid ""
+"``submit_prefetch_task()`` / ``query_prefetch_status()`` -- Async lookup "
+"+ L2 prefetch. ``query_prefetch_status()`` is non-blocking and returns "
+"``None`` while the L2 prefetch is still in flight."
+msgstr "``submit_prefetch_task()`` / ``query_prefetch_status()`` -- 异步查找 + L2 预取。 ``query_prefetch_status()`` 是非阻塞的，并在 L2 预取仍在进行时返回 ``None``。"
+
+#: ../../source/mp/index.rst:360
+msgid ""
+"``wait_prefetch_status()`` -- Blocking alternative to polling "
+"``query_prefetch_status()``: waits on a controller condition variable "
+"until the prefetch result is published (or a timeout expires). L1-only "
+"prefetches return immediately. Used by the ``WAIT_PREFETCH_STATUS`` RPC "
+"to avoid busy-polling on the load path."
+msgstr "``wait_prefetch_status()`` -- 轮询 ``query_prefetch_status()`` 的阻塞替代方案：在预取结果发布（或超时到期）之前，等待控制器条件变量。仅 L1 的预取会立即返回。由 ``WAIT_PREFETCH_STATUS`` RPC 使用，以避免在加载路径上进行忙等待。"
+
+#: ../../source/mp/index.rst:365
+msgid ""
+"``read_prefetched_results()`` / ``finish_read_prefetched()`` -- Read "
+"prefetched data from L1 with automatic lock management."
+msgstr ""
+"``read_prefetched_results()`` / ``finish_read_prefetched()`` -- 从 L1 "
+"读取预取的数据，并自动管理锁。"
+
+#: ../../source/mp/index.rst:369
+msgid "L1Manager"
+msgstr "L1Manager"
+
+#: ../../source/mp/index.rst:371 ../../source/mp/index.rst:619
+msgid "``lmcache/v1/distributed/l1_manager.py``"
+msgstr "``lmcache/v1/distributed/l1_manager.py``"
+
+#: ../../source/mp/index.rst:373
+msgid "Manages objects in CPU memory with a state machine:"
+msgstr "在 CPU 内存中使用状态机管理对象："
+
+#: ../../source/mp/index.rst:383
+msgid ""
+"Each object has two ``TTLLock`` instances (read and write) with "
+"configurable timeouts to prevent deadlocks from crashed clients."
+msgstr "每个对象都有两个 ``TTLLock`` 实例（读和写），并具有可配置的超时，以防止因崩溃的客户端导致的死锁。"
+
+#: ../../source/mp/index.rst:386
+msgid ""
+"The underlying memory allocation is handled by one of two interchangeable"
+" tiers selected at startup (both satisfy ``L1ManagerProtocol``):"
+msgstr "底层内存分配由在启动时选择的两个可互换层之一处理（两者都满足 ``L1ManagerProtocol``\\ ）："
+
+#: ../../source/mp/index.rst:389
+msgid ""
+"``L1MemoryManager`` (default) -- pinned CPU DRAM, with lazy growth up to "
+"``--l1-size-gb``."
+msgstr "``L1MemoryManager``\\ （默认）-- 固定 CPU DRAM，按需惰性增长至 ``--l1-size-gb``\\ 。"
+
+#: ../../source/mp/index.rst:391
+msgid ""
+"``GDSL1MemoryManager`` -- an NVMe slab file when ``--gds-l1-path`` is "
+"set. The bytes live on disk; reads/writes DMA directly between the GPU "
+"staging buffer and the slab, driven by the process-global ``GDSContext`` "
+"(``gpu_connector/gds_context.py``) and dispatched from ``gpu_ops``. The "
+"DMA backend is selected by platform via ``gpu_connector/_gds_async.py`` "
+"-- cuFile (``libcufile.so``) on NVIDIA and hipFile (``libhipfile.so``) on"
+" AMD ROCm; see the *GDS L1 Tier* section of :doc:`configuration` for the "
+"vendor-specific requirements. The CPU tier is disabled in this mode."
+msgstr "``GDSL1MemoryManager`` -- 当设置了 ``--gds-l1-path`` 时，使用 NVMe 块文件。字节存储在磁盘上；读/写通过 DMA 直接在 GPU 暂存缓冲区和块之间进行，由进程全局的 ``GDSContext``（``gpu_connector/gds_context.py``）驱动，并从 ``gpu_ops`` 派发。DMA 后端由平台通过 ``gpu_connector/_gds_async.py`` 选择 -- NVIDIA 使用 cuFile（``libcufile.so``），AMD ROCm 使用 hipFile（``libhipfile.so``）；有关特定于供应商的要求，请参见 :doc:`configuration` 的 *GDS L1 Tier* 部分。在此模式下，CPU 层被禁用。"
+
+#: ../../source/mp/index.rst:401
+msgid "L2 Adapters"
+msgstr "L2 适配器"
+
+#: ../../source/mp/index.rst:403
+msgid "``lmcache/v1/distributed/l2_adapters/``"
+msgstr "``lmcache/v1/distributed/l2_adapters/``"
+
+#: ../../source/mp/index.rst:405
+msgid ""
+"The ``L2AdapterInterface`` (in ``base.py``) defines three async task "
+"methods:"
+msgstr "``L2AdapterInterface``\\ （在 ``base.py`` 中）定义了三个异步任务方法："
+
+#: ../../source/mp/index.rst:407
+msgid "``submit_store_task(key, data)`` -- Push data to L2."
+msgstr "``submit_store_task(key, data)`` -- 将数据推送到 L2。"
+
+#: ../../source/mp/index.rst:408
+msgid "``submit_lookup_and_lock_task(keys)`` -- Check if keys exist in L2."
+msgstr "``submit_lookup_and_lock_task(keys)`` -- 检查键是否存在于 L2 中。"
+
+#: ../../source/mp/index.rst:409
+msgid "``submit_load_task(keys, layout_desc)`` -- Load data from L2 into L1."
+msgstr "``submit_load_task(keys, layout_desc)`` -- 从 L2 加载数据到 L1。"
+
+#: ../../source/mp/index.rst:411
+msgid ""
+"The factory function ``create_l2_adapter()`` (in ``__init__.py``) uses "
+"``isinstance()`` on the config type to instantiate the correct adapter."
+msgstr ""
+"工厂函数 ``create_l2_adapter()``\\ （位于 ``__init__.py``\\ ）通过对配置类型执行 "
+"``isinstance()`` 检查，实例化对应的适配器。"
+
+#: ../../source/mp/index.rst:414
+msgid ""
+"New adapter types are registered via ``register_l2_adapter_type()`` in "
+"``config.py``."
+msgstr "新适配器类型通过 ``register_l2_adapter_type()`` 在 ``config.py`` 中注册。"
+
+#: ../../source/mp/index.rst:418
+msgid "Controllers"
+msgstr "控制器"
+
+#: ../../source/mp/index.rst:420
+msgid ""
+"**StoreController** (``storage_controllers/store_controller.py``): Event-"
+"driven background thread that uses ``select.poll()`` on listener eventfd "
+"and adapter store eventfds.  When new objects appear in L1 (signaled via "
+"``StoreListener``), it submits async store tasks to each L2 adapter based"
+" on the ``StorePolicy``."
+msgstr ""
+"**StoreController** "
+"(``storage_controllers/store_controller.py``)：事件驱动的后台线程，使用 "
+"``select.poll()`` 监听 listener eventfd 和各适配器的存储 eventfd。当 L1 中出现新对象（通过 "
+"``StoreListener`` 发信号）时，根据 ``StorePolicy`` 向每个 L2 适配器提交异步存储任务。"
+
+#: ../../source/mp/index.rst:426
+msgid ""
+"**EvictionController** (``storage_controllers/eviction_controller.py``): "
+"Periodically checks L1 memory usage against the watermark threshold.  "
+"When triggered, evicts objects using the configured policy (``LRU``, "
+"``IsolatedLRU``, or ``noop``) until usage drops below the target. "
+"``IsolatedLRU`` evicts per ``cache_salt`` against limits registered "
+"through the ``/quota`` HTTP endpoints; see :ref:`mp-http-quota-api`."
+msgstr ""
+"**EvictionController** "
+"(``storage_controllers/eviction_controller.py``)：定期将 L1 "
+"内存用量与水位线阈值进行比较。触发后，使用配置的策略（\\ ``LRU``\\ 、\\ ``IsolatedLRU`` 或 ``noop``\\ "
+"）逐出对象，直至用量降到目标以下。\\ ``IsolatedLRU`` 按 ``cache_salt`` 维度逐出，配额上限由 "
+"``/quota`` HTTP 端点注册；参见 :ref:`mp-http-quota-api`。"
+
+#: ../../source/mp/index.rst:433
+msgid ""
+"**PrefetchController** (``storage_controllers/prefetch_controller.py``): "
+"Handles L2 lookup and load requests submitted by ``StorageManager`` "
+"during ``LOOKUP`` RPCs.  When keys are not in L1, it queries L2 adapters "
+"and loads found data back into L1."
+msgstr ""
+"**PrefetchController** "
+"(``storage_controllers/prefetch_controller.py``)：处理 ``StorageManager`` 在 "
+"``LOOKUP`` RPC 期间提交的 L2 查找和加载请求。当键不在 L1 中时，查询 L2 适配器并将命中的数据加载回 L1。"
+
+#: ../../source/mp/index.rst:439
+msgid "Request Flows"
+msgstr "请求流"
+
+#: ../../source/mp/index.rst:442
+msgid "LOOKUP Flow"
+msgstr "查找流程"
+
+#: ../../source/mp/index.rst:460
+msgid "STORE Flow"
+msgstr "存储流程"
+
+#: ../../source/mp/index.rst:479
+msgid "RETRIEVE Flow"
+msgstr "获取流程"
+
+#: ../../source/mp/index.rst:495
+msgid "Observability Internals"
+msgstr "可观察性内部实现"
+
+#: ../../source/mp/index.rst:497
+msgid ""
+"**EventBus** (``lmcache/v1/mp_observability/event_bus.py``) is a global "
+"singleton initialized at server startup by ``init_observability()``. "
+"Producers (L1Manager, StorageManager, MPCacheServer) publish ``Event`` "
+"objects to a bounded queue (``--event-bus-queue-size``, default 10000, "
+"tail-drop on overflow).  A background drain thread dispatches each event "
+"to all registered subscribers."
+msgstr ""
+"**EventBus** (``lmcache/v1/mp_observability/event_bus.py``) "
+"是一个全局单例，在服务器启动时由 ``init_observability()`` "
+"初始化。生产者（L1Manager、StorageManager、MPCacheServer）将 ``Event`` 对象发布到有界队列（\\ "
+"``--event-bus-queue-size``\\ ，默认 10000，溢出时尾部丢弃）。一个后台排空线程（drain "
+"thread）将每个事件分发给所有已注册的订阅者。"
+
+#: ../../source/mp/index.rst:504
+msgid ""
+"**Subscribers** live under ``lmcache/v1/mp_observability/subscribers/`` "
+"and are grouped by concern: ``metrics/`` (OTel counters and lifecycle "
+"histograms), ``logging/`` (Python logging handlers, lookup-hash JSONL), "
+"and ``tracing/`` (OTel spans built from START/END event pairs). "
+"``init_observability()`` registers the set selected by CLI flags "
+"(``--disable-metrics``, ``--disable-logging``, ``--enable-tracing``)."
+msgstr ""
+"**订阅者** 位于 ``lmcache/v1/mp_observability/subscribers/`` 下，按关注点分组：\\ "
+"``metrics/``\\ （OTel 计数器和生命周期直方图）、\\ ``logging/``\\ （Python 日志处理器、查找哈希 "
+"JSONL）以及 ``tracing/``\\ （由 START/END 事件对构建的 OTel span）。\\ "
+"``init_observability()`` 根据 CLI 标志（\\ ``--disable-metrics``\\ 、\\ "
+"``--disable-logging``\\ 、\\ ``--enable-tracing``\\ ）注册相应的订阅者集合。"
+
+#: ../../source/mp/index.rst:511
+msgid ""
+"**OTel providers** are set up via ``otel_init.py`` before subscribers are"
+" constructed, so module-level ``get_meter()`` / ``get_tracer()`` calls "
+"bind to the real provider. Metrics are exported both to an in-process "
+"Prometheus ``/metrics`` endpoint (``--prometheus-port``, default 9090) "
+"and, when ``--otlp-endpoint`` is set, pushed to an OTel collector."
+msgstr ""
+"**OTel 提供者**\\ 在构造订阅者之前通过 ``otel_init.py`` 完成初始化，确保模块级的 ``get_meter()`` /"
+" ``get_tracer()`` 调用绑定到真实的提供者。指标同时导出到进程内的 Prometheus ``/metrics`` 端点（\\ "
+"``--prometheus-port``\\ ，默认 9090），并在设置了 ``--otlp-endpoint`` 时推送到 OTel "
+"收集器。"
+
+#: ../../source/mp/index.rst:519
+msgid "How to Extend"
+msgstr "如何扩展"
+
+#: ../../source/mp/index.rst:522
+msgid "Adding a new L2 adapter"
+msgstr "添加新的 L2 适配器"
+
+#: ../../source/mp/index.rst:524
+msgid ""
+"Create a new ``*_l2_adapter.py`` module under "
+"``lmcache/v1/distributed/l2_adapters/`` — ``__init__.py`` auto-discovers "
+"modules matching that suffix via ``pkgutil`` and imports them lazily on "
+"first use, so no other files need to be modified."
+msgstr ""
+"在 ``lmcache/v1/distributed/l2_adapters/`` 下创建一个新的 ``*_l2_adapter.py`` 模块 "
+"— ``__init__.py`` 会通过 ``pkgutil`` 自动发现匹配该后缀的模块，并在首次使用时惰性导入，无需修改其他文件。"
+
+#: ../../source/mp/index.rst:529
+msgid ""
+"Create a config class subclassing ``L2AdapterConfigBase`` with "
+"``from_dict()`` and ``help()`` methods."
+msgstr ""
+"创建一个配置类，继承自 ``L2AdapterConfigBase``\\ ，并实现 ``from_dict()`` 和 ``help()`` "
+"方法。"
+
+#: ../../source/mp/index.rst:531
+msgid ""
+"Create an adapter class implementing ``L2AdapterInterface``, and a small "
+"factory function ``(config, l1_memory_desc) -> L2AdapterInterface``."
+msgstr ""
+"创建一个实现 ``L2AdapterInterface`` 的适配器类，以及一个小型工厂函数 ``(config, l1_memory_desc)"
+" -> L2AdapterInterface``\\ 。"
+
+#: ../../source/mp/index.rst:534
+msgid "At module level, self-register both the config and the factory:"
+msgstr "在模块级别，自注册配置和工厂："
+
+#: ../../source/mp/index.rst:541
+msgid ""
+"See ``mock_l2_adapter.py`` or ``s3_l2_adapter.py`` for reference "
+"implementations."
+msgstr "请参阅 ``mock_l2_adapter.py`` 或 ``s3_l2_adapter.py`` 以获取参考实现。"
+
+#: ../../source/mp/index.rst:545
+msgid "Adding an observability subscriber"
+msgstr "添加可观察性订阅者"
+
+#: ../../source/mp/index.rst:547
+#, python-brace-format
+msgid ""
+"Create a subscriber class subclassing ``EventSubscriber`` (defined in "
+"``lmcache/v1/mp_observability/event_bus.py``): implement "
+"``get_subscriptions()`` to return an ``{EventType: callback}`` mapping; "
+"optionally override ``shutdown()`` for cleanup."
+msgstr ""
+"创建一个继承自 ``EventSubscriber`` 的订阅者类（定义在 "
+"``lmcache/v1/mp_observability/event_bus.py`` 中）：实现 "
+"``get_subscriptions()`` 以返回 ``{EventType: callback}`` 映射；可选地重写 "
+"``shutdown()`` 以进行清理。"
+
+#: ../../source/mp/index.rst:551
+msgid ""
+"Place the class under the appropriate concern group "
+"(``subscribers/metrics/``, ``subscribers/logging/``, or "
+"``subscribers/tracing/``) and export it from that package's "
+"``__init__.py``."
+msgstr ""
+"将类放置在对应的关注组（\\ ``subscribers/metrics/``\\ 、\\ ``subscribers/logging/`` 或 "
+"``subscribers/tracing/``\\ ）下，并从该包的 ``__init__.py`` 中导出。"
+
+#: ../../source/mp/index.rst:555
+msgid ""
+"Register the subscriber in ``init_observability()`` "
+"(``lmcache/v1/mp_observability/config.py``) via "
+"``bus.register_subscriber(...)`` inside the branch matching its concern "
+"(metrics / logging / tracing), gated on the corresponding CLI flag if "
+"needed."
+msgstr ""
+"在 ``init_observability()``\\ （\\ "
+"``lmcache/v1/mp_observability/config.py``\\ ）中，通过 "
+"``bus.register_subscriber(...)`` 在与其关注点（metrics / logging / "
+"tracing）匹配的分支内注册订阅者，如有需要可受相应 CLI 标志控制。"
+
+#: ../../source/mp/index.rst:562
+msgid "Adding a new request type"
+msgstr "添加新的请求类型"
+
+#: ../../source/mp/index.rst:564
+msgid "Add a new member to ``RequestType`` in ``protocols/base.py``."
+msgstr "在 ``protocols/base.py`` 中向 ``RequestType`` 添加一个新成员。"
+
+#: ../../source/mp/index.rst:565
+msgid ""
+"Create a ``ProtocolDefinition`` in the appropriate ``protocols/*.py`` "
+"file (``engine``, ``controller``, ``observability``, ``debug``, "
+"``blend``, ``blend_v2``, ``blend_v3``, or ``p2p``) and add the request "
+"name to that module's ``REQUEST_NAMES``."
+msgstr "在适当的 ``protocols/*.py`` 文件（``engine``、``controller``、``observability``、``debug``、``blend``、``blend_v2``、``blend_v3`` 或 ``p2p``）中创建一个 ``ProtocolDefinition``，并将请求名称添加到该模块的 ``REQUEST_NAMES`` 中。"
+
+#: ../../source/mp/index.rst:569
+msgid ""
+"Implement the handler method on the appropriate ``EngineModule`` (e.g. "
+"``LookupModule``, ``LMCacheDrivenTransferModule``, ``BlendV3Module``) and"
+" expose it as a ``HandlerSpec`` from that module's ``get_handlers()``."
+msgstr ""
+"在适当的 ``EngineModule`` 上实现处理程序方法（例如 ``LookupModule``\\ 、\\ "
+"``LMCacheDrivenTransferModule``\\ 、\\ ``BlendV3Module``\\ ），并将其作为该模块的 "
+"``get_handlers()`` 中的 ``HandlerSpec`` 公开。"
+
+#: ../../source/mp/index.rst:572
+msgid ""
+"``run_cache_server()`` registers every ``HandlerSpec`` returned by the "
+"loaded modules via ``add_handler_helper()`` — no manual registration step"
+" is needed."
+msgstr ""
+"``run_cache_server()`` 通过 ``add_handler_helper()`` 注册各已加载模块返回的每一个 "
+"``HandlerSpec``\\ ，无需手动注册。"
+
+#: ../../source/mp/index.rst:577
+msgid "Key Source Files"
+msgstr "关键源文件"
+
+#: ../../source/mp/index.rst:583
+msgid "File"
+msgstr "文件"
+
+#: ../../source/mp/index.rst:584
+msgid "Purpose"
+msgstr "目的"
+
+#: ../../source/mp/index.rst:585
+msgid "``lmcache/v1/multiprocess/server.py``"
+msgstr "``lmcache/v1/multiprocess/server.py``"
+
+#: ../../source/mp/index.rst:586
+msgid "MPCacheServer + ZMQ server entry point"
+msgstr "MPCacheServer + ZMQ 服务器入口点"
+
+#: ../../source/mp/index.rst:587
+msgid "``lmcache/v1/multiprocess/config.py``"
+msgstr "``lmcache/v1/multiprocess/config.py``"
+
+#: ../../source/mp/index.rst:588
+msgid "MPServerConfig, HTTPFrontendConfig"
+msgstr "MPServerConfig, HTTPFrontendConfig"
+
+#: ../../source/mp/index.rst:589
+msgid "``lmcache/v1/multiprocess/engine_context.py``"
+msgstr "``lmcache/v1/multiprocess/engine_context.py``"
+
+#: ../../source/mp/index.rst:590
+msgid "MPCacheServerContext (shared state passed to every EngineModule)"
+msgstr "MPCacheServerContext（传递给每个 EngineModule 的共享状态）"
+
+#: ../../source/mp/index.rst:591
+msgid "``lmcache/v1/multiprocess/engine_module.py``"
+msgstr "``lmcache/v1/multiprocess/engine_module.py``"
+
+#: ../../source/mp/index.rst:592
+msgid ""
+"``EngineModule`` protocol, ``HandlerSpec``, ``ThreadPoolType`` (per-"
+"module handler registration)"
+msgstr ""
+"``EngineModule`` 协议， ``HandlerSpec``\\ ， ``ThreadPoolType``\\ "
+"（每个模块的处理程序注册）"
+
+#: ../../source/mp/index.rst:594
+msgid "``lmcache/v1/multiprocess/modules/``"
+msgstr "``lmcache/v1/multiprocess/modules/``"
+
+#: ../../source/mp/index.rst:595
+msgid ""
+"Engine module implementations: ``lookup.py`` (``LookupModule``), "
+"``management.py`` (``ManagementModule``), ``lmcache_driven_transfer.py`` "
+"(``LMCacheDrivenTransferModule``), ``engine_driven_transfer.py`` "
+"(``EngineDrivenTransferModule``), ``blend.py`` (``BlendModule`` / "
+"``BlendEngineV2``, selected by ``--engine-type blend_legacy``), and "
+"``blend_v3.py`` (``BlendV3Module``, the paged-aware CacheBlend V3 "
+"pipeline selected by ``--engine-type blend``)."
+msgstr ""
+"引擎模块实现：\\ ``lookup.py`` (``LookupModule``)、\\ ``management.py`` "
+"(``ManagementModule``)、\\ ``lmcache_driven_transfer.py`` "
+"(``LMCacheDrivenTransferModule``)、\\ ``engine_driven_transfer.py`` "
+"(``EngineDrivenTransferModule``)、\\ ``blend.py``\\ （\\ ``BlendModule`` / "
+"``BlendEngineV2``\\ ，由 ``--engine-type blend_legacy`` 选择），以及 "
+"``blend_v3.py``\\ （\\ ``BlendV3Module``\\ ，由 ``--engine-type blend`` "
+"选择的分页感知 CacheBlend V3 流水线）。"
+
+#: ../../source/mp/index.rst:603
+msgid "``lmcache/v1/multiprocess/http_server.py``"
+msgstr "``lmcache/v1/multiprocess/http_server.py``"
+
+#: ../../source/mp/index.rst:604
+msgid "FastAPI wrapper with health check and many other useful APIs"
+msgstr "带健康检查和许多其他有用 API 的 FastAPI 包装器"
+
+#: ../../source/mp/index.rst:605
+msgid "``lmcache/v1/multiprocess/http_api_registry.py``"
+msgstr "``lmcache/v1/multiprocess/http_api_registry.py``"
+
+#: ../../source/mp/index.rst:606
+msgid "``HTTPAPIRegistry`` that auto-discovers routers in ``http_apis/``"
+msgstr "``HTTPAPIRegistry`` 会自动发现 ``http_apis/`` 中的路由器"
+
+#: ../../source/mp/index.rst:607
+msgid "``lmcache/v1/multiprocess/http_apis/``"
+msgstr "``lmcache/v1/multiprocess/http_apis/``"
+
+#: ../../source/mp/index.rst:608
+msgid ""
+"Extensible HTTP endpoints (``/``, ``/healthcheck``, ``/cache/clear``, "
+"``/status``)"
+msgstr "可扩展的 HTTP 端点 (``/``, ``/healthcheck``, ``/cache/clear``, ``/status``)"
+
+#: ../../source/mp/index.rst:610
+msgid "``lmcache/v1/multiprocess/mp_runtime_plugin_launcher.py``"
+msgstr "``lmcache/v1/multiprocess/mp_runtime_plugin_launcher.py``"
+
+#: ../../source/mp/index.rst:611
+msgid ""
+"``MPRuntimePluginLauncher`` that spawns runtime plugins with the full "
+"server config serialized into environment variables"
+msgstr "``MPRuntimePluginLauncher`` 通过将完整的服务器配置序列化为环境变量来生成运行时插件"
+
+#: ../../source/mp/index.rst:613
+msgid "``lmcache/v1/multiprocess/protocols/base.py``"
+msgstr "``lmcache/v1/multiprocess/protocols/base.py``"
+
+#: ../../source/mp/index.rst:614
+msgid "RequestType, HandlerType, ProtocolDefinition"
+msgstr "请求类型，处理程序类型，协议定义"
+
+#: ../../source/mp/index.rst:616
+msgid "StorageManager (top-level manager)"
+msgstr "存储管理器（顶级管理器）"
+
+#: ../../source/mp/index.rst:617
+msgid "``lmcache/v1/distributed/config.py``"
+msgstr "``lmcache/v1/distributed/config.py``"
+
+#: ../../source/mp/index.rst:618
+msgid "StorageManagerConfig hierarchy"
+msgstr "StorageManagerConfig 层次结构"
+
+#: ../../source/mp/index.rst:620
+msgid "L1Manager (object state machine)"
+msgstr "L1Manager（对象状态机）"
+
+#: ../../source/mp/index.rst:621
+msgid "``lmcache/v1/distributed/l2_adapters/config.py``"
+msgstr "``lmcache/v1/distributed/l2_adapters/config.py``"
+
+#: ../../source/mp/index.rst:622
+msgid "L2 adapter config registry"
+msgstr "L2 适配器配置注册表"
+
+#: ../../source/mp/index.rst:623
+msgid "``lmcache/v1/distributed/l2_adapters/base.py``"
+msgstr "``lmcache/v1/distributed/l2_adapters/base.py``"
+
+#: ../../source/mp/index.rst:624
+msgid "L2AdapterInterface"
+msgstr "L2AdapterInterface"
+
+#: ../../source/mp/index.rst:625
+msgid "``lmcache/v1/distributed/storage_controllers/store_controller.py``"
+msgstr "``lmcache/v1/distributed/storage_controllers/store_controller.py``"
+
+#: ../../source/mp/index.rst:626
+msgid "StoreController (event-driven L1->L2)"
+msgstr "StoreController（事件驱动 L1->L2）"
+
+#: ../../source/mp/index.rst:627
+msgid "``lmcache/v1/distributed/storage_controllers/eviction_controller.py``"
+msgstr "``lmcache/v1/distributed/storage_controllers/eviction_controller.py``"
+
+#: ../../source/mp/index.rst:628
+msgid "EvictionController (watermark-triggered)"
+msgstr "逐出控制器（基于水印触发）"
+
+#: ../../source/mp/index.rst:629
+msgid "``lmcache/v1/distributed/storage_controllers/prefetch_controller.py``"
+msgstr "``lmcache/v1/distributed/storage_controllers/prefetch_controller.py``"
+
+#: ../../source/mp/index.rst:630
+msgid "PrefetchController (L2->L1 on miss)"
+msgstr "PrefetchController (L2->L1 未命中时)"
+
+#: ../../source/mp/index.rst:631
+msgid "``lmcache/v1/mp_observability/config.py``"
+msgstr "``lmcache/v1/mp_observability/config.py``"
+
+#: ../../source/mp/index.rst:632
+msgid "ObservabilityConfig + ``init_observability()`` entry point"
+msgstr "可观察性配置 + ``init_observability()`` 入口点"
+
+#: ../../source/mp/index.rst:633
+msgid "``lmcache/v1/mp_observability/event_bus.py``"
+msgstr "``lmcache/v1/mp_observability/event_bus.py``"
+
+#: ../../source/mp/index.rst:634
+msgid "EventBus singleton and ``EventSubscriber`` base class"
+msgstr "事件总线单例和 ``EventSubscriber`` 基类"
+
+#: ../../source/mp/index.rst:635
+msgid "``lmcache/v1/mp_observability/event.py``"
+msgstr "``lmcache/v1/mp_observability/event.py``"
+
+#: ../../source/mp/index.rst:636
+msgid "``Event`` / ``EventType`` definitions"
+msgstr "``Event`` / ``EventType`` 定义"
+
+#: ../../source/mp/index.rst:637
+msgid "``lmcache/v1/mp_observability/otel_init.py``"
+msgstr "``lmcache/v1/mp_observability/otel_init.py``"
+
+#: ../../source/mp/index.rst:638
+msgid "OTel metrics / tracing provider setup"
+msgstr "OTel 指标 / 跟踪提供程序设置"
+
+#: ../../source/mp/index.rst:639
+msgid "``lmcache/v1/mp_observability/subscribers/``"
+msgstr "``lmcache/v1/mp_observability/subscribers/``"
+
+#: ../../source/mp/index.rst:640
+msgid "Metrics, logging, and tracing subscribers"
+msgstr "指标、日志和追踪订阅者"
+
+#: ../../source/mp/index.rst:641
+msgid "``lmcache/v1/mp_observability/trace/``"
+msgstr "``lmcache/v1/mp_observability/trace/``"
+
+#: ../../source/mp/index.rst:642
+msgid "Trace recording (``--trace-level storage``) capture stack"
+msgstr "追踪记录 (``--trace-level storage``) 捕获堆栈"
+
+#~ msgid ""
+#~ "**Recommended.** ZMQ + FastAPI HTTP "
+#~ "frontend (adds ``/healthcheck`` for K8s "
+#~ "probes, ``/clear-cache``, ``/status`` — "
+#~ "see :doc:`http_api`). Use ``--engine-type "
+#~ "blend`` to enable BlendEngineV2 for "
+#~ "cross-request KV reuse."
+#~ msgstr ""
+#~ "**推荐。** ZMQ + FastAPI HTTP 前端（为 "
+#~ "K8s 探针添加 ``/healthcheck``、``/clear-"
+#~ "cache``、``/status`` — 参见 :doc:`http_api`）。使用 "
+#~ "``--engine-type blend`` 启用 BlendEngineV2 "
+#~ "以实现跨请求的 KV 重用。"
+
+#~ msgid ""
+#~ "(Legacy) ZMQ-only server using "
+#~ "MPCacheEngine (no HTTP endpoints). Prefer "
+#~ "``lmcache server``."
+#~ msgstr "(遗留) 仅使用 MPCacheEngine 的 ZMQ 服务器（没有 HTTP 端点）。请使用 ``lmcache server``。"
+
+#~ msgid "``python3 -m lmcache.v1.multiprocess.blend_server_v2``"
+#~ msgstr "``python3 -m lmcache.v1.multiprocess.blend_server_v2``"
+
+#~ msgid ""
+#~ "(Legacy) CacheBlend-enabled server. Prefer "
+#~ "``lmcache server --engine-type blend``."
+#~ msgstr "（遗留）启用 CacheBlend 的服务器。建议使用 ``lmcache server --engine-type blend``。"
+
+#~ msgid "Multiprocess Mode"
+#~ msgstr "多进程模式"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/kv_cache_management.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/kv_cache_management.po
new file mode 100644
index 0000000..5c6e9c6
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/kv_cache_management.po
@@ -0,0 +1,38 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/kv_cache_management.rst:4
+msgid "KV Cache Management"
+msgstr "KV Cache 管理"
+
+#: ../../source/mp/kv_cache_management.rst:8
+msgid ""
+"The multiprocess (MP) cache-management surface (operations such as "
+"``move``, ``pin``, and ``compress``) is **coming soon**."
+msgstr "MP（多进程）缓存管理接口层（如 ``move``\\ 、\\ ``pin`` 和 ``compress`` 等操作）即将 **推出**\\ 。"
+
+#: ../../source/mp/kv_cache_management.rst:11
+msgid ""
+"Until it lands, the in-process management commands are documented in the "
+":doc:`Legacy section <../legacy/index>`: "
+":doc:`../kv_cache_management/index`."
+msgstr "在此功能发布之前，进程内管理命令已记录于 :doc:`旧版章节 <../legacy/index>`： :doc:`../kv_cache_management/index`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/aerospike.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/aerospike.po
new file mode 100644
index 0000000..68db4b8
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/aerospike.po
@@ -0,0 +1,134 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/aerospike.rst:2
+msgid "Aerospike"
+msgstr "Aerospike"
+
+#: ../../source/mp/l2_storage/aerospike.rst:4
+msgid ""
+"An L2 adapter backed by the native C++ Aerospike connector (the same "
+"``ConnectorBase`` worker-pool harness used by ``fs_native``), wrapped "
+"with ``NativeConnectorL2Adapter``.  KV objects are stored under a meta "
+"record plus optional payload segments so values larger than the server "
+"record cap are transparently sharded."
+msgstr "一个由原生 C++ Aerospike 连接器支持的 L2 适配器（与 ``fs_native`` 使用的相同 ``ConnectorBase`` 工作池框架），由 ``NativeConnectorL2Adapter`` 封装。KV 对象以一条元记录加若干可选负载段的形式存储，超出服务器记录上限的值将被透明地拆分为多个分片。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:10
+msgid "**Prerequisites -- Building with Aerospike support:**"
+msgstr "**前提条件 -- 构建时启用 Aerospike 支持：**"
+
+#: ../../source/mp/l2_storage/aerospike.rst:12
+msgid ""
+"The Aerospike extension is **not** built by default.  Install the "
+"Aerospike C client, then build with ``BUILD_AEROSPIKE=1`` (or set "
+"``AEROSPIKE_INCLUDE_DIR``):"
+msgstr "Aerospike 扩展\\ **默认不**\\ 构建。请先安装 Aerospike C 客户端，然后使用 ``BUILD_AEROSPIKE=1`` 进行构建（或设置 ``AEROSPIKE_INCLUDE_DIR``\\ ）："
+
+#: ../../source/mp/l2_storage/aerospike.rst:19
+msgid ""
+"See :doc:`/developer_guide/extending_lmcache/native_connectors` (section "
+"\"Built-in Aerospike backend\") for installing the C client into "
+"``.deps/`` and the ``aerospike-client-c.env`` example."
+msgstr "请参阅 :doc:`/developer_guide/extending_lmcache/native_connectors`（章节“内置 Aerospike 后端”）以了解如何将 C 客户端安装到 ``.deps/`` 以及 ``aerospike-client-c.env`` 示例。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:23
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/aerospike.rst:25
+msgid "``hosts``: Seed hosts as ``host:port[,host:port...]``."
+msgstr "``hosts``: 种子主机格式为 ``host:port[,host:port...]``\\ 。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:27
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/aerospike.rst:29
+msgid ""
+"``namespace`` (str, default ``\"lmcache\"``): Aerospike namespace.  Must "
+"exist on the server and have ``nsup-period > 0`` if you rely on TTL "
+"expiry."
+msgstr "``namespace`` (str, default ``\"lmcache\"``): Aerospike 命名空间。该命名空间必须已在服务器上创建；若需依赖 TTL 自动过期，还须满足 ``nsup-period > 0``\\ 。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:31
+msgid ""
+"``set_name`` / ``set`` (str, default ``\"kv_chunks\"``): Aerospike set "
+"name."
+msgstr "``set_name`` / ``set`` (str, default ``\"kv_chunks\"``): Aerospike 集合名称。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:32
+msgid ""
+"``num_workers`` (int, default ``8``, > 0): C++ worker threads for I/O.  "
+"This is the real I/O queue depth -- raise it to push throughput."
+msgstr "``num_workers`` (int, default ``8``, > 0): 用于 I/O 的 C++ 工作线程数。这是实际的 I/O 队列深度——适当调高此值可提升吞吐量。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:34
+msgid "``read_timeout_ms`` (int, default ``1000``): Client read timeout."
+msgstr "``read_timeout_ms`` (int, default ``1000``): 客户端读取超时时间（毫秒）。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:35
+msgid "``write_timeout_ms`` (int, default ``2000``): Client write timeout."
+msgstr "``write_timeout_ms`` (int, default ``2000``): 客户端写入超时时间（毫秒）。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:36
+msgid ""
+"``default_ttl_seconds`` (int, default ``86400``): Record TTL.  ``0`` uses"
+" the namespace default TTL."
+msgstr "``default_ttl_seconds`` (int, default ``86400``): 记录的生存时间（TTL）。 ``0`` 使用命名空间的默认 TTL。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:38
+msgid ""
+"``target_segment_bytes`` (int, default ``0``): Target shard size.  ``0`` "
+"uses the discovered server record cap."
+msgstr "``target_segment_bytes`` (int, default ``0``): 目标分片大小。 ``0`` 使用发现的服务器记录上限。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:40
+msgid ""
+"``max_record_bytes`` (int, default ``0``): Override the server record "
+"cap. ``0`` discovers it at construction time."
+msgstr "``max_record_bytes`` (int, default ``0``): 覆盖服务器记录上限。 ``0`` 在构造时发现该上限。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:42
+msgid ""
+"``username`` / ``password`` (str, default ``\"\"``): Optional Enterprise "
+"Edition authentication."
+msgstr "``username`` / ``password`` (str, default ``\"\"``): 可选的企业版身份验证。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:44
+msgid ""
+"``max_capacity_gb`` (float, default ``0``): Maximum L2 capacity in GB for"
+" client-side usage tracking / eviction.  ``0`` disables tracking."
+msgstr "``max_capacity_gb`` (float, default ``0``): 客户端侧用量跟踪与逐出所使用的最大 L2 容量（GB）。\\ ``0`` 表示禁用跟踪。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:47
+msgid ""
+"**Environment variable fallbacks.**  When the corresponding config value "
+"is empty, these environment variables are used: "
+"``LMCACHE_AEROSPIKE_HOSTS``, ``LMCACHE_AEROSPIKE_NAMESPACE``, "
+"``LMCACHE_AEROSPIKE_SET``, ``LMCACHE_AEROSPIKE_USERNAME``, "
+"``LMCACHE_AEROSPIKE_PASSWORD``."
+msgstr "**环境变量回退。** 当相应的配置值为空时，将使用这些环境变量：\\ ``LMCACHE_AEROSPIKE_HOSTS``\\ 、\\ ``LMCACHE_AEROSPIKE_NAMESPACE``\\ 、\\ ``LMCACHE_AEROSPIKE_SET``\\ 、\\ ``LMCACHE_AEROSPIKE_USERNAME``\\ 、\\ ``LMCACHE_AEROSPIKE_PASSWORD``\\ 。"
+
+#: ../../source/mp/l2_storage/aerospike.rst:52
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/dax.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/dax.po
new file mode 100644
index 0000000..643e484
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/dax.po
@@ -0,0 +1,161 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/dax.rst:2
+msgid "DAX"
+msgstr "DAX"
+
+#: ../../source/mp/l2_storage/dax.rst:4
+msgid ""
+"An L2 adapter that maps Device-DAX paths, such as ``/dev/daxX.X`` and "
+"``/dev/daxY.Y``, and stores KV cache objects in fixed-size slots. This "
+"adapter is intended for byte-addressable memory devices such as "
+"persistent memory or CXL memory."
+msgstr "一个 L2 适配器，映射设备 DAX 路径，例如 ``/dev/daxX.X`` 和 ``/dev/daxY.Y``，并在固定大小的槽中存储 KV Cache 对象。该适配器旨在用于字节可寻址内存设备，例如持久内存或 CXL 内存。"
+
+#: ../../source/mp/l2_storage/dax.rst:9
+msgid ""
+"The MP ``dax`` adapter is volatile in this release.  It keeps the key "
+"index in server memory and rebuilds an empty index on restart.  Old bytes"
+" may remain on the DAX device, but they are unreachable after the LMCache"
+" server restarts."
+msgstr "在此版本中，MP ``dax`` 适配器是易失性的。它将键索引保存在服务器内存中，并在重启时重建一个空索引。旧字节可能仍保留在 DAX 设备上，但在 LMCache 服务器重启后无法访问。"
+
+#: ../../source/mp/l2_storage/dax.rst:13
+msgid "**Required fields for the legacy single-device form:**"
+msgstr "**旧版单设备形式的必填字段：**"
+
+#: ../../source/mp/l2_storage/dax.rst:15
+msgid "``device_path``: Path to the mmap-able DAX device or test file."
+msgstr "``device_path``: 可映射的 DAX 设备或测试文件的路径。"
+
+#: ../../source/mp/l2_storage/dax.rst:16
+msgid "``max_dax_size_gb``: Number of GiB to map from ``device_path``."
+msgstr "``max_dax_size_gb``: 从 ``device_path`` 映射的 GiB 数量。"
+
+#: ../../source/mp/l2_storage/dax.rst:17
+msgid ""
+"``slot_bytes``: Fixed slot size in bytes. This must be large enough for "
+"one full LMCache chunk because MP memory descriptors do not expose the "
+"non-MP full-chunk size."
+msgstr "``slot_bytes``: 固定槽大小（以字节为单位）。该值必须足够大，能够容纳一个完整的 LMCache 块，因为 MP 内存描述符不公开非 MP 模式下完整块的大小。"
+
+#: ../../source/mp/l2_storage/dax.rst:21
+msgid "**Required fields for the multi-device form:**"
+msgstr "**多设备形式的必填字段：**"
+
+#: ../../source/mp/l2_storage/dax.rst:23
+msgid ""
+"``devices``: List of objects with ``device_path`` and "
+"``max_dax_size_gb``. The list may be empty only when ``hotplug_enabled`` "
+"is ``true``."
+msgstr "``devices``：包含 ``device_path`` 和 ``max_dax_size_gb`` 的对象列表。只有在 ``hotplug_enabled`` 为 ``true`` 时，列表可以为空。"
+
+#: ../../source/mp/l2_storage/dax.rst:25
+msgid ""
+"``slot_bytes``: Fixed slot size in bytes shared by every DAX device in "
+"the adapter facade."
+msgstr "``slot_bytes``: 适配器门面中所有 DAX 设备共用的固定槽大小（以字节为单位）。"
+
+#: ../../source/mp/l2_storage/dax.rst:28
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/dax.rst:30
+msgid ""
+"``hotplug_enabled`` (bool, default ``false``): Enables runtime "
+"``/reconfigure/dax/status``, ``/reconfigure/dax/add``, "
+"``/reconfigure/dax/remove``, and ``/reconfigure/dax/resize``."
+msgstr "``hotplug_enabled`` (bool, 默认 ``false``): 启用运行时 ``/reconfigure/dax/status``、``/reconfigure/dax/add``、``/reconfigure/dax/remove`` 和 ``/reconfigure/dax/resize``。"
+
+#: ../../source/mp/l2_storage/dax.rst:33
+msgid "``num_store_workers`` (int, default ``1``): Store worker threads."
+msgstr "``num_store_workers`` (int, default ``1``): 存储工作线程数量。"
+
+#: ../../source/mp/l2_storage/dax.rst:34
+msgid "``num_lookup_workers`` (int, default ``1``): Lookup worker threads."
+msgstr "``num_lookup_workers`` (int, default ``1``): 查找工作线程数量。"
+
+#: ../../source/mp/l2_storage/dax.rst:35
+msgid ""
+"``num_load_workers`` (int, default ``min(4, os.cpu_count())``): Load "
+"worker threads."
+msgstr "``num_load_workers`` (int, default ``min(4, os.cpu_count())``): 加载工作线程数量。"
+
+#: ../../source/mp/l2_storage/dax.rst:37
+msgid ""
+"``persist_enabled`` (bool): Accepted by common L2 config parsing but has "
+"no effect for ``dax`` because restart recovery is not implemented."
+msgstr "``persist_enabled`` (bool): 通用 L2 配置解析会接受该字段，但对 ``dax`` 无效，因为重启恢复功能尚未实现。"
+
+#: ../../source/mp/l2_storage/dax.rst:40
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
+#: ../../source/mp/l2_storage/dax.rst:76
+msgid ""
+"Runtime management uses JSON bodies because DAX paths contain slashes. "
+"See the :doc:`Device-DAX backend guide </kv_cache/storage_backends/dax>` "
+"for complete examples. These routes use StorageManager's generic L2 "
+"adapter reconfiguration API; the HTTP path selects the backend and "
+"operation, the DAX adapter interprets the operation payload, and the same"
+" interface can be reused by future adapters such as P2P."
+msgstr "运行时管理使用 JSON 请求体，因为 DAX 路径包含斜杠。完整示例请参阅 :doc:`Device-DAX 后端指南 </kv_cache/storage_backends/dax>`。这些路由使用 StorageManager 的通用 L2 适配器重新配置 API：HTTP 路径用于选择后端和操作，DAX 适配器负责解析操作负载，未来的适配器（如 P2P）也可复用同一接口。"
+
+#: ../../source/mp/l2_storage/dax.rst:90
+msgid "**Current limits:**"
+msgstr "**当前限制：**"
+
+#: ../../source/mp/l2_storage/dax.rst:92
+msgid ""
+"Runtime hotplug changes only LMCache mappings and metadata. It does not "
+"create, destroy, or reconfigure kernel CXL or DAX devices."
+msgstr "运行时热插拔仅更改 LMCache 映射和元数据。它不会创建、销毁或重新配置内核 CXL 或 DAX 设备。"
+
+#: ../../source/mp/l2_storage/dax.rst:94
+msgid "Per-TP partitions and on-device restart metadata are not implemented."
+msgstr "每个 TP 的分区和设备重启元数据尚未实现。"
+
+#: ../../source/mp/l2_storage/dax.rst:95
+msgid ""
+"Only single-buffer objects are supported. Multi-tensor objects are "
+"rejected."
+msgstr "仅支持单缓冲区对象。多张量对象被拒绝。"
+
+#: ../../source/mp/l2_storage/dax.rst:96
+msgid ""
+"Capacity is slot-based, not payload-byte-based. L2 eviction and usage "
+"metrics count occupied slots."
+msgstr "容量以槽为单位计算，而非以负载字节计算。L2 逐出和使用量指标均基于已占用的槽数。"
+
+#: ../../source/mp/l2_storage/dax.rst:98
+msgid ""
+"Lookups acquire DAX-side external locks. ``submit_unlock`` releases those"
+" locks after load/retrieve completes, making entries evictable again."
+msgstr "查找操作会持有 DAX 侧的外部锁。``submit_unlock`` 在加载／检索完成后释放这些锁，使对应条目重新可被逐出。"
+
+#: ../../source/mp/l2_storage/dax.rst:100
+msgid ""
+"Remove ``mode=\"evict\"`` is destructive for the DAX tier. Remove "
+"``mode=\"migrate\"`` requires enough capacity on another active DAX "
+"device."
+msgstr "以 ``mode=\"evict\"`` 执行移除操作会破坏 DAX 层中的数据。以 ``mode=\"migrate\"`` 执行移除操作则要求另一个活跃 DAX 设备具有足够的剩余容量。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fault_inject.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fault_inject.po
new file mode 100644
index 0000000..07b76a3
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fault_inject.po
@@ -0,0 +1,127 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:2
+msgid "Fault Inject"
+msgstr "故障注入"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:4
+msgid ""
+"A **test/diagnostic-only** adapter that wraps a real inner adapter and "
+"deterministically drops keys on the load read, simulating partial L2 "
+"retrieve failures.  It exercises CacheBlend's **segmented-prefix** "
+"recovery path — a gapped found-set (hit … miss … hit) that a healthy "
+"cache never produces — without needing an actual faulty backend."
+msgstr "一个 **仅用于测试/诊断** 的适配器，它包装了一个真实的内部适配器，并在加载读取时确定性地丢弃键，模拟部分 L2 检索失败。它测试了 CacheBlend 的 **分段前缀** 恢复路径——一个健康缓存从未产生的间隙找到集（命中 … 未命中 … 命中）——而无需实际故障的后端。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:12
+msgid ""
+"Never enable in production.  It silently makes reads fail, so any KV it "
+"serves is intentionally incomplete."
+msgstr "切勿在生产环境中启用。它会悄无声息地使读取失败，因此它提供的任何 KV 都是故意不完整的。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:15
+msgid ""
+"The wrapped backend is given as a full adapter spec under ``inner`` (any "
+"registered ``type``), so it keeps its own configuration, eviction, "
+"persist, and serde settings.  Faulting applies to the load read only: a "
+"dropped key is reported *present at lookup* but its *load fails* (the "
+"faithful \"L2 retrieve error\"); the prefetch controller releases the "
+"load-failed locks via the trim mask.  Everything else (store, lookup, "
+"unlock, delete, usage) passes straight through to the inner adapter."
+msgstr "包装的后端作为完整的适配器规范在 ``inner`` 下提供（任何注册的 ``type``），因此它保留自己的配置、逐出、持久化和序列化设置。故障仅适用于加载读取：丢失的键在查找时被报告为存在，但其加载失败（忠实的“L2 检索错误”）；预取控制器通过修剪掩码释放加载失败的锁。其他所有操作（存储、查找、解锁、删除、使用）都直接传递给内部适配器。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:23
+msgid "**Fields:**"
+msgstr "**字段：**"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:25
+#, python-brace-format
+msgid ""
+"``inner`` (required): full adapter spec for the wrapped backend, e.g. "
+"``{\"type\": \"fs_native\", \"base_path\": \"/dev/shm/l2\"}``."
+msgstr "``inner``\\ （必需）：用于包装后端的完整适配器规范，例如 ``{\"type\": \"fs_native\", \"base_path\": \"/dev/shm/l2\"}``。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:27
+msgid ""
+"``gap_tail_ratios``: positions to always drop, given as distance-from-"
+"tail fractions of the load length in ``[0, 1]`` (``0.0`` = last chunk, "
+"``0.5`` = middle, ``1.0`` = first).  Workload-agnostic and self-scaling "
+"across context lengths.  Default ``[]``."
+msgstr "``gap_tail_ratios``: 始终丢弃的位置，以负载长度的尾部距离比例给出，范围在 ``[0, 1]`` 之间（``0.0`` = 最后一个块，``0.5`` = 中间，``1.0`` = 第一个）。与工作负载无关，并且在上下文长度上自我缩放。默认 ``[]``。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:31
+msgid ""
+"``gap_indices``: exact head-relative task-positions to always drop. "
+"Default ``[]``."
+msgstr "``gap_indices``: 始终丢弃的精确头相对任务位置。默认 ``[]``。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:33
+msgid ""
+"``rate``: per-key drop probability in ``[0, 1]`` via a stable seeded hash"
+" of the key.  Default ``0.0`` (pass-through)."
+msgstr "``rate``: 每个键的丢弃概率在 ``[0, 1]`` 范围内，通过键的稳定种子哈希计算。默认值为 ``0.0``\\ （直通）。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:35
+msgid ""
+"``seed``: seed for the ``rate`` hash (deterministic given the seed). "
+"Default ``0``."
+msgstr "``seed``: ``rate`` 哈希的种子（给定种子时是确定性的）。默认值为 ``0``。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:38
+msgid ""
+"Defaults are pass-through; set at least one of ``gap_tail_ratios``, "
+"``gap_indices``, or ``rate`` to drop anything."
+msgstr "默认值是直接传递的；至少设置 ``gap_tail_ratios``、``gap_indices`` 或 ``rate`` 之一以丢弃任何内容。"
+
+#: ../../source/mp/l2_storage/fault_inject.rst:41
+msgid ""
+"Drop a stable mid-prefix gap (the CacheBlend segmented-prefix repro), "
+"wrapping an ``fs_native`` backend:"
+msgstr "丢弃一个稳定的中间前缀间隙（CacheBlend 分段前缀重现），包装一个 ``fs_native`` 后端："
+
+#: ../../source/mp/l2_storage/fault_inject.rst:48
+msgid ""
+"To actually exercise CacheBlend's **segmented-prefix recovery**, pair the"
+" gap with the server flag ``--enable-segmented-prefix`` (CacheBlend only "
+"— ``--engine-type blend``). The dropped mid chunk produces a gapped "
+"found-set; with segmented-prefix enabled the prefix leg **retains the "
+"post-gap chunks** (loads prefix + tail) and recomputes **only the dropped"
+" gap**, instead of truncating the prefix at the gap:"
+msgstr "要实际测试 CacheBlend 的 **分段前缀恢复**，将间隙与服务器标志 ``--enable-segmented-prefix`` 配对（仅适用于 CacheBlend — ``--engine-type blend``）。丢弃的中间块会产生一个带间隙的查找集；启用分段前缀后，前缀部分 **保留间隙后的块**\\ （加载前缀 + 尾部）并仅重计算 **丢弃的间隙**，而不是在间隙处截断前缀："
+
+#: ../../source/mp/l2_storage/fault_inject.rst:61
+#, python-format
+msgid "Randomly drop ~10% of loads (deterministic given the seed):"
+msgstr "随机丢弃约 10% 的加载（根据种子确定）："
+
+#: ../../source/mp/l2_storage/fault_inject.rst:67
+msgid "Drop an exact load position (precise single-gap repro):"
+msgstr "丢弃一个确切的加载位置（精确的单缺口重现）："
+
+#: ../../source/mp/l2_storage/fault_inject.rst:73
+msgid ""
+"At startup the adapter logs ``FaultInjectL2Adapter ACTIVE (rate=… seed=… "
+"gap_indices=… gap_tail_ratios=[…]) wrapping <inner> -- test/diagnostic "
+"use only.``, and ``report_status()`` reports the active fault config "
+"under a ``fault_inject`` sub-dict."
+msgstr "在启动时，适配器记录 ``FaultInjectL2Adapter ACTIVE (rate=… seed=… gap_indices=… gap_tail_ratios=[…]) wrapping <inner> -- 仅用于测试/诊断。``，并且 ``report_status()`` 在 ``fault_inject`` 子字典下报告活动故障配置。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/file_and_block.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/file_and_block.po
new file mode 100644
index 0000000..bed4e06
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/file_and_block.po
@@ -0,0 +1,32 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/file_and_block.rst:2
+msgid "File & Block"
+msgstr "文件与块"
+
+#: ../../source/mp/l2_storage/file_and_block.rst:4
+msgid ""
+"File-system and block-device backends that persist KV cache to local or "
+"networked storage. These are conceptually similar -- they write KV "
+"objects to files or fixed-size slots on a disk or block device."
+msgstr "将 KV 缓存持久化到本地或网络存储的文件系统和块设备后端。二者在概念上相似——均将 KV 对象写入文件或磁盘、块设备上的固定大小槽位。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fs.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fs.po
new file mode 100644
index 0000000..f02094e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fs.po
@@ -0,0 +1,67 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/fs.rst:2
+msgid "FileSystem"
+msgstr "文件系统"
+
+#: ../../source/mp/l2_storage/fs.rst:4
+msgid ""
+"A pure file-system L2 adapter using async I/O (``aiofiles``).  Each KV "
+"cache object is stored as a raw ``.data`` file whose name encodes the "
+"full ``ObjectKey``.  Does **not** require NIXL -- works on any POSIX file"
+" system."
+msgstr "一个纯文件系统 L2 适配器，使用异步 I/O (``aiofiles``)。每个 KV 缓存对象以原始 ``.data`` 文件的形式存储，文件名编码了完整的 ``ObjectKey``\\ 。\\ **不**\\ 需要 NIXL——可在任何 POSIX 文件系统上运行。"
+
+#: ../../source/mp/l2_storage/fs.rst:8
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/fs.rst:10
+msgid "``base_path``: Directory for storing KV cache files."
+msgstr "``base_path``: 存储 KV Cache 文件的目录。"
+
+#: ../../source/mp/l2_storage/fs.rst:12
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/fs.rst:14
+msgid ""
+"``relative_tmp_dir``: Relative sub-directory for temporary files during "
+"writes (atomic rename on completion)."
+msgstr "``relative_tmp_dir``: 写入期间临时文件的相对子目录（完成时进行原子重命名）。"
+
+#: ../../source/mp/l2_storage/fs.rst:16
+msgid ""
+"``read_ahead_size``: Trigger file-system read-ahead by reading this many "
+"bytes first (positive integer, optional)."
+msgstr "``read_ahead_size``: 通过预先读取指定字节数来触发文件系统预读（正整数，可选）。"
+
+#: ../../source/mp/l2_storage/fs.rst:18
+msgid ""
+"``use_odirect``: ``true`` or ``false`` (default ``false``) -- bypass the "
+"page cache via ``O_DIRECT``."
+msgstr "``use_odirect``: ``true`` 或 ``false``\\ （默认 ``false``\\ ）-- 通过 ``O_DIRECT`` 绕过页面缓存。"
+
+#: ../../source/mp/l2_storage/fs.rst:21
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fs_native.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fs_native.po
new file mode 100644
index 0000000..2bff43d
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/fs_native.po
@@ -0,0 +1,125 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/fs_native.rst:2
+msgid "FS (native)"
+msgstr "FS（原生）"
+
+#: ../../source/mp/l2_storage/fs_native.rst:4
+msgid ""
+"A file-system L2 adapter backed by the native C++ ``LMCacheFSClient`` "
+"wrapped with ``NativeConnectorL2Adapter``.  I/O is dispatched through a "
+"C++ worker-thread pool with eventfd-driven completions, giving a true I/O"
+" queue depth on a single Python thread."
+msgstr "一个由原生 C++ ``LMCacheFSClient`` 支持的文件系统 L2 适配器，封装在 ``NativeConnectorL2Adapter`` 中。I/O 通过一个 C++ 工作线程池进行调度，使用 eventfd 驱动的完成机制，在单个 Python 线程上提供真实的 I/O 队列深度。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:9
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/fs_native.rst:11
+msgid "``base_path``: Directory for storing KV cache files."
+msgstr "``base_path``: 存储 KV Cache 文件的目录。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:13
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/fs_native.rst:15
+msgid ""
+"``num_workers`` (int, default ``4``, > 0): Number of C++ worker threads "
+"inside the connector.  This is the real I/O queue depth -- raise to push "
+"throughput on filesystems whose aggregate BW exceeds per-stream BW."
+msgstr "``num_workers``\\ （int，默认值 ``4``\\ ，> 0）：连接器内部的 C++ 工作线程数量。这是真正的 I/O 队列深度——提高此值以在总带宽超过每个流带宽的文件系统上提升吞吐量。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:19
+msgid ""
+"``relative_tmp_dir`` (str, default ``\"\"``): Relative sub-directory for "
+"temporary files during writes (atomic rename on completion)."
+msgstr "``relative_tmp_dir``\\ （str，默认值 ``\"\"``\\ ）：写入临时文件所使用的相对子目录，写入完成后执行原子重命名。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:21
+msgid ""
+"``use_odirect`` (bool, default ``false``): Bypass the page cache via "
+"``O_DIRECT``.  Required to measure real disk bandwidth.  See alignment "
+"caveat below."
+msgstr "``use_odirect``\\ （bool，默认值 ``false``\\ ）：通过 ``O_DIRECT`` 绕过页面缓存，启用后方可测量真实的磁盘带宽。请参阅下方的对齐注意事项。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:24
+msgid ""
+"``read_ahead_size`` (int, optional): Trigger filesystem readahead by "
+"issuing a warm-up read of this many bytes at open time."
+msgstr "``read_ahead_size``\\ （int，可选）：打开文件时预读指定字节数以触发文件系统的预读机制。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:26
+msgid ""
+"``max_capacity_gb`` (float, default ``0``): Maximum L2 capacity in GB for"
+" client-side usage tracking.  Default ``0`` disables tracking."
+msgstr "``max_capacity_gb``\\ （float，默认值 ``0``\\ ）：用于客户端使用量跟踪的最大 L2 容量（单位：GB）。默认值 ``0`` 表示禁用跟踪。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:31
+msgid "``O_DIRECT`` has two independent alignment requirements:"
+msgstr "``O_DIRECT`` 有两个独立的对齐要求："
+
+#: ../../source/mp/l2_storage/fs_native.rst:33
+#, python-format
+msgid ""
+"**Length alignment.**  The transfer length must be a multiple of the "
+"filesystem's block size.  The connector queries the disk block size at "
+"construction time and, on each operation, checks ``len % "
+"disk_block_size``.  If the length is **not** a multiple, the connector "
+"silently falls back to a buffered open (no ``O_DIRECT``) for that "
+"operation -- correctness is preserved but you do not get true direct I/O."
+"  To ensure ``O_DIRECT`` is actually used, choose ``--chunk-size`` so "
+"that the resulting per-chunk byte size is a multiple of the FS block "
+"size.  GPFS and similar parallel filesystems often use large blocks (e.g."
+" several MiB)."
+msgstr "**长度对齐。**  传输长度必须是文件系统块大小的倍数。连接器在构造时查询磁盘块大小，并在每次操作时检查 ``len % disk_block_size``\\ 。如果长度 **不是** 倍数，连接器会默默回退到缓冲打开（不使用 ``O_DIRECT``\\ ）进行该操作——正确性得以保留，但您无法获得真正的直接 I/O。为了确保实际使用 ``O_DIRECT``\\ ，选择 ``--chunk-size`` 使得每块的字节大小是文件系统块大小的倍数。GPFS 和类似的并行文件系统通常使用较大的块（例如几个 MiB）。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:45
+msgid ""
+"**Memory-buffer alignment.**  The I/O buffer pointer itself must also be "
+"aligned (typically to 4096 bytes on local disks, or to the FS block size "
+"on parallel filesystems).  This is controlled by ``--l1-align-bytes`` "
+"(default ``4096``) -- raise it to match the FS block size when running on"
+" a filesystem with larger blocks.  If the buffer is misaligned, the "
+"underlying ``read``/``write`` syscall returns ``EINVAL`` (this is **not**"
+" caught by the length-fallback path above and will surface as a runtime "
+"error)."
+msgstr "**内存缓冲区对齐。** I/O 缓冲区指针本身也必须对齐（本地磁盘通常要求对齐到 4096 字节，并行文件系统则要求对齐到 FS 块大小）。这由 ``--l1-align-bytes`` 控制（默认值为 ``4096``\\ ）——在块较大的文件系统上运行时，请相应调高此值以匹配 FS 块大小。若缓冲区未对齐，底层 ``read``/``write`` 系统调用将返回 ``EINVAL``\\ （该错误不会被上述长度回退路径捕获，会直接以运行时错误的形式抛出）。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:54
+msgid ""
+"If unsure, start with ``use_odirect: false`` and confirm correctness "
+"before enabling ``O_DIRECT``."
+msgstr "如果不确定，请先使用 ``use_odirect: false`` 并确认正确性，然后再启用 ``O_DIRECT``\\ 。"
+
+#: ../../source/mp/l2_storage/fs_native.rst:57
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
+#: ../../source/mp/l2_storage/fs_native.rst:70
+msgid ""
+"**Buffer-only mode example.**  L1 acts as a pure write buffer that "
+"absorbs the peak burst of in-flight chunks while the C++ worker pool "
+"drains them to disk; nothing is retained in L1 once a store completes:"
+msgstr "**仅缓冲区模式示例。** L1 充当纯写缓冲区，吸收待处理数据块的峰值突发，同时 C++ 工作线程池将其排空至磁盘；存储完成后 L1 中不保留任何内容："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/hfbucket.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/hfbucket.po
new file mode 100644
index 0000000..52a127b
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/hfbucket.po
@@ -0,0 +1,117 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:2
+msgid "HF Bucket"
+msgstr "HF Bucket"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:4
+msgid ""
+"An L2 adapter that stores KV cache objects in a `Hugging Face Bucket "
+"<https://huggingface.co/docs/hub/storage-backends>`_ using the "
+"``huggingface_hub`` bucket APIs.  Blocking Hub calls run on a bounded "
+"thread pool driven by an asyncio loop on a daemon thread, so the L2 "
+"controller thread is never blocked on network I/O."
+msgstr "一个 L2 适配器，通过 ``huggingface_hub`` 桶 API 将 KV Cache 对象存储在 `Hugging Face Bucket <https://huggingface.co/docs/hub/storage-backends>`_ 中。阻塞式 Hub 调用在一个由守护线程上的 asyncio 循环驱动的有界线程池中执行，因此 L2 控制器线程不会阻塞在网络 I/O 上。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:10
+msgid ""
+"Object names are derived from the MP ``ObjectKey`` as "
+"``<model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]`` and then "
+"encoded with the standard HFBucket object-name encoding plus the optional"
+" bucket prefix. Because Hugging Face batch writes are not transactional, "
+"a store task that partially fails reconciles backend metadata so that any"
+" objects that actually landed are still counted for usage accounting and "
+"later deletion."
+msgstr "对象名称源自 MP ``ObjectKey``，格式为 ``<model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]``，然后使用标准的 HFBucket 对象名称编码加上可选的桶前缀进行编码。由于 Hugging Face 的批量写入不是事务性的，因此部分失败的存储任务会协调后端元数据，以便实际落地的对象仍然计入使用量核算和后续删除。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:17
+msgid ""
+"This is a persistent remote backend best suited to warm and cold KV cache"
+" tiers; prefer a lower-latency local adapter for the hottest cache tier."
+msgstr "这是一个持久化远程后端，最适合温层和冷层 KV Cache 缓存；对于最热的缓存层，建议优先使用延迟更低的本地适配器。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:20
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:22
+msgid ""
+"``bucket_handle``: Bucket location in the form "
+"``hf://buckets/<namespace>/<bucket>[/<prefix>]``."
+msgstr "``bucket_handle``：桶的位置，格式为 ``hf://buckets/<namespace>/<bucket>[/<prefix>]``。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:25
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:27
+msgid ""
+"``token_env`` (string, default ``\"HF_TOKEN\"``): Environment variable "
+"used to resolve the Hugging Face access token."
+msgstr "``token_env`` (字符串，默认 ``\"HF_TOKEN\"``)：用于解析 Hugging Face 访问令牌的环境变量。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:29
+msgid ""
+"``token`` (string): Direct token fallback used when ``token_env`` is "
+"unset."
+msgstr "``token`` (字符串)：``token_env`` 未设置时直接使用的令牌备用值。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:30
+msgid ""
+"``create_bucket_if_missing`` (bool, default ``false``): Create the bucket"
+" lazily on the first store instead of requiring it to exist."
+msgstr "``create_bucket_if_missing`` (bool，默认 ``false``)：在首次存储时惰性创建桶，而非要求桶预先存在。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:32
+msgid ""
+"``download_tmp_dir`` (string): Root directory for temporary load "
+"downloads."
+msgstr "``download_tmp_dir`` (字符串)：加载时临时下载文件的根目录。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:33
+msgid ""
+"``metadata_cache_ttl_secs`` (float, default ``30.0``): TTL for the path-"
+"size metadata cache that backs lookups and usage accounting."
+msgstr "``metadata_cache_ttl_secs`` (float，默认 ``30.0``)：用于支持查找和用量统计的路径大小元数据缓存的 TTL。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:35
+msgid ""
+"``num_workers`` (int, default ``4``): Number of worker threads for "
+"blocking Hugging Face Hub API calls."
+msgstr "``num_workers`` (int，默认 ``4``)：用于执行阻塞式 Hugging Face Hub API 调用的工作线程数。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:37
+msgid ""
+"``max_capacity_gb`` (float, default ``0.0``): Aggregate capacity used by "
+"``get_usage()``.  A value of ``0`` disables aggregate eviction."
+msgstr "``max_capacity_gb`` (float，默认 ``0.0``)：``get_usage()`` 所使用的总容量上限。值为 ``0`` 时禁用整体逐出。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:39
+msgid ""
+"``eviction`` (dict): Optional eviction policy, see "
+"``L2AdapterConfigBase``."
+msgstr "``eviction`` (dict)：可选的逐出策略，参见 ``L2AdapterConfigBase``。"
+
+#: ../../source/mp/l2_storage/hfbucket.rst:41
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/index.po
new file mode 100644
index 0000000..f271468
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/index.po
@@ -0,0 +1,547 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/index.rst:2
+msgid "Secondary KV Storage"
+msgstr "二级 KV 存储"
+
+#: ../../source/mp/l2_storage/index.rst:4
+msgid "LMCache multiprocess mode supports a two-tier storage architecture:"
+msgstr "LMCache MP 模式（多进程）支持两级存储架构："
+
+#: ../../source/mp/l2_storage/index.rst:6
+msgid ""
+"**L1 (fast tier)** -- CPU memory by default, or an NVMe slab via "
+"GPUDirect Storage (cuFile) when ``--gds-l1-path`` is set, managed by the "
+"L1 Manager. All KV cache chunks live here during active use. (Byte-array "
+"L2 adapters are unsupported under the GDS L1 tier, which exposes no L1 "
+"memory buffer.)"
+msgstr "**L1 (快速层)** -- 默认情况下为 CPU 内存，或通过 GPUDirect Storage (cuFile) 的 NVMe 块，当设置 ``--gds-l1-path`` 时，由 L1 管理器管理。所有 KV Cache 块在活跃使用期间都存放在这里。（在 GDS L1 层下，不支持字节数组 L2 适配器，因为它不暴露任何 L1 内存缓冲区。）"
+
+#: ../../source/mp/l2_storage/index.rst:10
+msgid ""
+"**L2 (persistent)** -- Durable storage backends (NIXL-based or plain "
+"file-system/raw-block).  The StoreController asynchronously pushes data "
+"from L1 to L2, and the PrefetchController loads data from L2 back into L1"
+" on cache misses."
+msgstr "**L2 (持久性)** -- 持久存储后端（基于 NIXL 或普通文件系统/原始块）。StoreController 异步将数据从 L1 推送到 L2，而 PrefetchController 在缓存未命中时将数据从 L2 加载回 L1。"
+
+#: ../../source/mp/l2_storage/index.rst:20
+msgid "Data Flow"
+msgstr "数据流"
+
+#: ../../source/mp/l2_storage/index.rst:22
+msgid "**Write path (L1 -> L2):**"
+msgstr "**写入路径 (L1 -> L2):**"
+
+#: ../../source/mp/l2_storage/index.rst:24
+msgid "vLLM stores KV cache chunks into L1 via the ``STORE`` RPC."
+msgstr "vLLM 通过 ``STORE`` RPC 将 KV Cache 块存储到 L1。"
+
+#: ../../source/mp/l2_storage/index.rst:25
+msgid ""
+"The ``StoreController`` detects new objects (via eventfd) and "
+"asynchronously submits store tasks to each configured L2 adapter."
+msgstr "``StoreController`` 通过 eventfd 检测新对象，并异步将存储任务提交到每个已配置的 L2 适配器。"
+
+#: ../../source/mp/l2_storage/index.rst:27
+msgid "The L2 adapter writes the data to its backend (e.g., local SSD via GDS)."
+msgstr "L2 适配器将数据写入其后端（例如，通过 GDS 的本地 SSD）。"
+
+#: ../../source/mp/l2_storage/index.rst:29
+msgid "**Read path (L2 -> L1):**"
+msgstr "**读取路径 (L2 -> L1):**"
+
+#: ../../source/mp/l2_storage/index.rst:31
+msgid "A ``LOOKUP`` RPC checks L1 for prefix hits."
+msgstr "``LOOKUP`` RPC 检查 L1 中的前缀缓存命中情况。"
+
+#: ../../source/mp/l2_storage/index.rst:32
+msgid ""
+"For keys not found in L1, the ``PrefetchController`` submits lookup "
+"requests to L2 adapters."
+msgstr "对于在 L1 中未找到的键，\\ ``PrefetchController`` 向 L2 适配器提交查找请求。"
+
+#: ../../source/mp/l2_storage/index.rst:34
+msgid ""
+"If found in L2, the data is loaded back into L1 and read-locked for the "
+"pending ``RETRIEVE`` RPC."
+msgstr "如果在 L2 中找到，数据将被加载回 L1，并为待处理的 ``RETRIEVE`` RPC 加读锁。"
+
+#: ../../source/mp/l2_storage/index.rst:38
+msgid "Adapter Types"
+msgstr "适配器类型"
+
+#: ../../source/mp/l2_storage/index.rst:40
+msgid ""
+"LMCache ships several L2 storage backends, grouped by medium under "
+":doc:`Supported Backends <supported_storages>`. Select one or more with "
+"the ``--l2-adapter`` flag."
+msgstr "LMCache 提供了几种 L2 存储后端，按介质分组在 :doc:`支持的后端 <supported_storages>` 下。使用 ``--l2-adapter`` 标志选择一个或多个。"
+
+#: ../../source/mp/l2_storage/index.rst:50
+msgid "Multiple Adapters (Cascade)"
+msgstr "多个适配器（级联）"
+
+#: ../../source/mp/l2_storage/index.rst:52
+msgid ""
+"You can configure multiple L2 adapters by repeating the ``--l2-adapter`` "
+"argument.  Adapters are used in the order they are specified.  The "
+"``StoreController`` pushes data to all configured adapters, and the "
+"``PrefetchController`` queries adapters in order during lookups."
+msgstr "您可以通过重复 ``--l2-adapter`` 参数来配置多个 L2 适配器。适配器按指定的顺序使用。\\ ``StoreController`` 将数据推送到所有配置的适配器，而 ``PrefetchController`` 在查找期间按顺序查询适配器。"
+
+#: ../../source/mp/l2_storage/index.rst:64
+msgid "Store and Prefetch Policies"
+msgstr "存储和预取策略"
+
+#: ../../source/mp/l2_storage/index.rst:66
+msgid ""
+"The **store policy** controls how keys flow from L1 to L2: which adapters"
+" receive each key and whether keys are deleted from L1 after a successful"
+" L2 store.  The **prefetch policy** controls how keys flow from L2 back "
+"to L1: when multiple adapters have the same key, the policy decides which"
+" adapter loads it."
+msgstr "**存储策略** 控制键从 L1 流向 L2 的方式：哪些适配器接收每个键，以及在成功存储到 L2 后是否从 L1 删除键。 **预取策略** 控制键从 L2 流回 L1 的方式：当多个适配器具有相同的键时，策略决定哪个适配器加载它。"
+
+#: ../../source/mp/l2_storage/index.rst:72
+msgid "Select policies via CLI:"
+msgstr "通过 CLI 选择策略："
+
+#: ../../source/mp/l2_storage/index.rst:79
+msgid "**Built-in policies:**"
+msgstr "**内置策略：**"
+
+#: ../../source/mp/l2_storage/index.rst:85
+#: ../../source/mp/l2_storage/index.rst:118
+#: ../../source/mp/l2_storage/index.rst:177
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/mp/l2_storage/index.rst:86
+msgid "Name"
+msgstr "名称"
+
+#: ../../source/mp/l2_storage/index.rst:87
+msgid "Behaviour"
+msgstr "行为"
+
+#: ../../source/mp/l2_storage/index.rst:88
+#: ../../source/mp/l2_storage/index.rst:91
+msgid "``--l2-store-policy``"
+msgstr "``--l2-store-policy``"
+
+#: ../../source/mp/l2_storage/index.rst:89
+#: ../../source/mp/l2_storage/index.rst:97
+msgid "``default``"
+msgstr "``default``"
+
+#: ../../source/mp/l2_storage/index.rst:90
+msgid "Store all keys to all adapters.  Never delete from L1."
+msgstr "将所有键存储到所有适配器中。永不从 L1 中删除。"
+
+#: ../../source/mp/l2_storage/index.rst:92
+msgid "``skip_l1``"
+msgstr "``skip_l1``"
+
+#: ../../source/mp/l2_storage/index.rst:93
+msgid ""
+"Buffer-only mode.  Store all keys to all adapters, then **delete them "
+"from L1** immediately.  Pair with ``--eviction-policy noop`` to avoid "
+"useless LRU overhead."
+msgstr "仅缓冲区模式。将所有键存储到所有适配器，然后立即 **从 L1 中删除它们**\\ 。与 ``--eviction-policy noop`` 配对以避免无用的 LRU 开销。"
+
+#: ../../source/mp/l2_storage/index.rst:96
+#: ../../source/mp/l2_storage/index.rst:100
+msgid "``--l2-prefetch-policy``"
+msgstr "``--l2-prefetch-policy``"
+
+#: ../../source/mp/l2_storage/index.rst:98
+msgid ""
+"For each key, pick the first (lowest-indexed) adapter that has it. "
+"Prefetched keys are **temporary** (deleted after the reader finishes)."
+msgstr "对于每个键，选择第一个（索引最低的）拥有该键的适配器。预取的键是\\ **临时的**\\ （在读取完成后删除）。"
+
+#: ../../source/mp/l2_storage/index.rst:101
+msgid "``retain``"
+msgstr "``retain``"
+
+#: ../../source/mp/l2_storage/index.rst:102
+msgid ""
+"Same load plan as ``default``, but prefetched keys are **retained** "
+"permanently in L1.  Useful when prefetched data is likely reused by "
+"subsequent requests (e.g. shared system-prompt chunks)."
+msgstr "与 ``default`` 相同的加载计划，但预取的键将\\ **永久保留**\\ 在 L1 中。当预取的数据可能被后续请求重用时（例如，共享系统提示块），此策略非常有用。"
+
+#: ../../source/mp/l2_storage/index.rst:107
+msgid "Prefetch Concurrency"
+msgstr "预取并发性"
+
+#: ../../source/mp/l2_storage/index.rst:109
+msgid ""
+"The ``--l2-prefetch-max-in-flight`` flag limits the number of concurrent "
+"prefetch requests that the ``PrefetchController`` can have in flight at "
+"any time.  A higher value increases L2-to-L1 throughput but also "
+"increases L1 memory pressure from in-flight data."
+msgstr "``--l2-prefetch-max-in-flight`` 标志限制了 ``PrefetchController`` 在任意时刻可以并发进行的预取请求数量。较大的值会提升 L2 到 L1 的吞吐量，但也会增加在途数据对 L1 内存的压力。"
+
+#: ../../source/mp/l2_storage/index.rst:119
+#: ../../source/mp/l2_storage/index.rst:178
+#: ../../source/mp/l2_storage/index.rst:218
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/l2_storage/index.rst:120
+#: ../../source/mp/l2_storage/index.rst:179
+#: ../../source/mp/l2_storage/index.rst:219
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/l2_storage/index.rst:121
+msgid "``--l2-prefetch-max-in-flight``"
+msgstr "``--l2-prefetch-max-in-flight``"
+
+#: ../../source/mp/l2_storage/index.rst:122
+msgid "``8``"
+msgstr "``8``"
+
+#: ../../source/mp/l2_storage/index.rst:123
+msgid "Maximum number of concurrent prefetch requests."
+msgstr "最大并发预取请求数。"
+
+#: ../../source/mp/l2_storage/index.rst:126
+msgid "Buffer-Only Mode"
+msgstr "仅缓冲区模式"
+
+#: ../../source/mp/l2_storage/index.rst:128
+msgid ""
+"When L1 is used purely as a write buffer (all data lives in L2), use "
+"``--l2-store-policy skip_l1`` together with ``--eviction-policy noop``. "
+"This combination deletes keys from L1 as soon as they are stored to L2 "
+"and disables the LRU eviction tracker entirely, reducing memory and CPU "
+"overhead."
+msgstr "当 L1 仅作为写缓冲区使用（所有数据存储在 L2 中）时，使用 ``--l2-store-policy skip_l1`` 以及 ``--eviction-policy noop``\\ 。此组合会在数据存储到 L2 后立即从 L1 中删除键，并完全禁用 LRU 逐出跟踪器，从而减少内存和 CPU 开销。"
+
+#: ../../source/mp/l2_storage/index.rst:140
+msgid ""
+"Policies are extensible -- new policies can be added by creating a file "
+"in ``storage_controllers/`` and calling ``register_store_policy()`` or "
+"``register_prefetch_policy()`` at import time.  See the design doc "
+"``l2_adapters/design_docs/overall.md`` for details."
+msgstr "策略是可扩展的——可以通过在 ``storage_controllers/`` 中创建文件并在导入时调用 ``register_store_policy()`` 或 ``register_prefetch_policy()`` 来添加新策略。有关详细信息，请参阅设计文档 ``l2_adapters/design_docs/overall.md``\\ 。"
+
+#: ../../source/mp/l2_storage/index.rst:146
+msgid "Serde (compression / quantization)"
+msgstr "序列化与反序列化（压缩 / 量化）"
+
+#: ../../source/mp/l2_storage/index.rst:148
+msgid ""
+"Each adapter can optionally run a **serde** (serializer / deserializer) "
+"that transforms data on the way in and out of L2 — e.g. fp8 quantization "
+"for disk backends, or encryption for remote adapters. See :doc:`KV Cache "
+"Compression </mp/serde>` for details and configuration."
+msgstr "每个适配器可以选择性地运行一个 **serde**\\ （序列化器/反序列化器），在数据进出 L2 时进行转换——例如，针对磁盘后端的 fp8 量化，或针对远程适配器的加密。有关详细信息和配置，请参见 :doc:`KV Cache Compression </mp/serde>`。"
+
+#: ../../source/mp/l2_storage/index.rst:159
+msgid "Eviction"
+msgstr "逐出"
+
+#: ../../source/mp/l2_storage/index.rst:161
+msgid ""
+"LMCache supports eviction at both storage tiers so that each tier can "
+"operate within a fixed capacity budget."
+msgstr "LMCache 支持在两个存储层次上进行逐出，以便每个层次都可以在固定的容量预算内运行。"
+
+#: ../../source/mp/l2_storage/index.rst:165
+msgid "L1 Eviction"
+msgstr "L1 逐出"
+
+#: ../../source/mp/l2_storage/index.rst:167
+msgid ""
+"L1 eviction runs a single background thread that monitors overall L1 "
+"memory usage. When usage exceeds ``trigger_watermark``, the eviction "
+"policy evicts a fraction of the least-recently-used keys."
+msgstr "L1 逐出运行一个后台线程，监控整体 L1 内存使用情况。当使用量超过 ``trigger_watermark`` 时，逐出策略会逐出一部分最近最少使用的键。"
+
+#: ../../source/mp/l2_storage/index.rst:171
+msgid "**CLI flags:**"
+msgstr "**命令行标志:**"
+
+#: ../../source/mp/l2_storage/index.rst:180
+msgid "``--eviction-policy``"
+msgstr "``--eviction-policy``"
+
+#: ../../source/mp/l2_storage/index.rst:181
+#: ../../source/mp/l2_storage/index.rst:221
+msgid "*(required)*"
+msgstr "(必需)"
+
+#: ../../source/mp/l2_storage/index.rst:182
+msgid "Policy name: ``LRU`` or ``noop``."
+msgstr "策略名称：\\ ``LRU`` 或 ``noop``\\ 。"
+
+#: ../../source/mp/l2_storage/index.rst:183
+msgid "``--eviction-trigger-watermark``"
+msgstr "``--eviction-trigger-watermark``"
+
+#: ../../source/mp/l2_storage/index.rst:184
+#: ../../source/mp/l2_storage/index.rst:224
+msgid "``0.8``"
+msgstr "``0.8``"
+
+#: ../../source/mp/l2_storage/index.rst:185
+msgid "L1 usage fraction [0, 1] above which eviction is triggered."
+msgstr "触发逐出的 L1 使用比例 [0, 1]。"
+
+#: ../../source/mp/l2_storage/index.rst:186
+msgid "``--eviction-ratio``"
+msgstr "``--eviction-ratio``"
+
+#: ../../source/mp/l2_storage/index.rst:187
+#: ../../source/mp/l2_storage/index.rst:227
+msgid "``0.2``"
+msgstr "``0.2``"
+
+#: ../../source/mp/l2_storage/index.rst:188
+msgid "Fraction of currently allocated L1 memory to evict per cycle."
+msgstr "每个周期逐出的当前分配的 L1 内存的比例。"
+
+#: ../../source/mp/l2_storage/index.rst:190
+msgid "**Example:**"
+msgstr "**示例：**"
+
+#: ../../source/mp/l2_storage/index.rst:199
+msgid "L2 Eviction"
+msgstr "L2 逐出"
+
+#: ../../source/mp/l2_storage/index.rst:201
+msgid ""
+"L2 eviction is **per-adapter** and **opt-in**. Each adapter can "
+"independently declare an eviction policy by adding an ``\"eviction\"`` "
+"sub-object to its ``--l2-adapter`` JSON spec. Adapters without an "
+"``\"eviction\"`` key have no eviction controller."
+msgstr "L2 逐出是\\ **按适配器独立配置**\\ 且\\ **可选启用**\\ 的。每个适配器可以通过在其 ``--l2-adapter`` JSON 规范中添加 ``\"eviction\"`` 子对象来独立声明逐出策略。没有 ``\"eviction\"`` 键的适配器不启用逐出控制器。"
+
+#: ../../source/mp/l2_storage/index.rst:206
+msgid ""
+"When L2 eviction is enabled for an adapter, a dedicated background thread"
+" monitors that adapter's ``get_usage()`` value. Once usage exceeds "
+"``trigger_watermark``, the policy evicts keys until usage drops by "
+"``eviction_ratio``."
+msgstr "当为适配器启用 L2 逐出时，一个专用的后台线程会监控该适配器的 ``get_usage()`` 值。一旦使用量超过 ``trigger_watermark``\\ ，该策略将逐出键，直到使用量降低 ``eviction_ratio``\\ 。"
+
+#: ../../source/mp/l2_storage/index.rst:211
+msgid "**``\"eviction\"`` sub-object fields:**"
+msgstr "**``\"eviction\"`` 子对象字段:**"
+
+#: ../../source/mp/l2_storage/index.rst:217
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/mp/l2_storage/index.rst:220
+msgid "``eviction_policy``"
+msgstr "``eviction_policy``"
+
+#: ../../source/mp/l2_storage/index.rst:222
+msgid "Policy name: ``\"LRU\"`` or ``\"noop\"``."
+msgstr "策略名称：\\ ``\"LRU\"`` 或 ``\"noop\"``\\ 。"
+
+#: ../../source/mp/l2_storage/index.rst:223
+msgid "``trigger_watermark``"
+msgstr "``trigger_watermark``"
+
+#: ../../source/mp/l2_storage/index.rst:225
+msgid "Adapter usage fraction [0, 1] above which eviction is triggered."
+msgstr "触发逐出的适配器使用比例 [0, 1]。"
+
+#: ../../source/mp/l2_storage/index.rst:226
+msgid "``eviction_ratio``"
+msgstr "``eviction_ratio``"
+
+#: ../../source/mp/l2_storage/index.rst:228
+msgid "Fraction of used capacity to evict per cycle."
+msgstr "每个周期逐出的已用容量的比例。"
+
+#: ../../source/mp/l2_storage/index.rst:230
+msgid "**Example — nixl_store with LRU eviction:**"
+msgstr "**示例 — 使用 LRU 逐出的 nixl_store:**"
+
+#: ../../source/mp/l2_storage/index.rst:246
+msgid "**Adapter support:**"
+msgstr "**适配器支持：**"
+
+#: ../../source/mp/l2_storage/index.rst:252
+msgid "Adapter"
+msgstr "适配器"
+
+#: ../../source/mp/l2_storage/index.rst:253
+msgid "L2 Eviction Support"
+msgstr "L2 逐出支持"
+
+#: ../../source/mp/l2_storage/index.rst:254
+msgid "``nixl_store``"
+msgstr "``nixl_store``"
+
+#: ../../source/mp/l2_storage/index.rst:255
+msgid ""
+"Full support. ``delete`` frees pool slots; pinned keys (in-flight loads) "
+"are skipped and retried on the next cycle."
+msgstr "完全支持。\\ ``delete`` 释放池槽；固定的键（正在进行的加载）会被跳过，并在下一个周期重试。"
+
+#: ../../source/mp/l2_storage/index.rst:257
+msgid "``nixl_store_dynamic``"
+msgstr "``nixl_store_dynamic``"
+
+#: ../../source/mp/l2_storage/index.rst:258
+msgid ""
+"Full support. ``delete`` removes data files from disk; pinned keys are "
+"skipped. ``get_usage`` is byte-based (``_total_bytes / "
+"max_capacity_bytes``)."
+msgstr "完全支持。\\ ``delete`` 从磁盘中删除数据文件；被固定的键会被跳过。\\ ``get_usage`` 是基于字节的 (``_total_bytes / max_capacity_bytes``)。"
+
+#: ../../source/mp/l2_storage/index.rst:261
+msgid "``mock``"
+msgstr "``mock``"
+
+#: ../../source/mp/l2_storage/index.rst:262
+msgid ""
+"Full support. Useful for testing eviction behaviour without real storage "
+"hardware."
+msgstr "完全支持。适用于在无真实存储硬件的情况下测试逐出行为。"
+
+#: ../../source/mp/l2_storage/index.rst:264
+msgid "``raw_block``"
+msgstr "``raw_block``"
+
+#: ../../source/mp/l2_storage/index.rst:265
+msgid ""
+"Full shared/global eviction support. ``delete`` recycles raw-block slots;"
+" locked entries are skipped and retried on the next cycle."
+msgstr "完全支持共享/全局逐出。\\ ``delete`` 回收原始块槽；被锁定的条目会被跳过，并在下一个周期重试。"
+
+#: ../../source/mp/l2_storage/index.rst:267
+msgid "``s3``"
+msgstr "``s3``"
+
+#: ../../source/mp/l2_storage/index.rst:268
+msgid ""
+"``delete`` removes objects from the bucket and frees aggregate byte "
+"accounting. ``get_usage`` reports ``usage_fraction == -1.0`` when "
+"``max_capacity_gb`` is ``0`` (disabled); set a non-zero "
+"``max_capacity_gb`` to enable the watermark-triggered eviction "
+"controller."
+msgstr "``delete`` 从存储桶中移除对象并释放聚合字节计数。当 ``max_capacity_gb`` 为 ``0``\\ （禁用）时，\\ ``get_usage`` 报告 ``usage_fraction == -1.0``\\ ；设置非零的 ``max_capacity_gb`` 以启用基于水印的逐出控制器。"
+
+#: ../../source/mp/l2_storage/index.rst:273
+msgid "``hfbucket``"
+msgstr "``hfbucket``"
+
+#: ../../source/mp/l2_storage/index.rst:274
+msgid ""
+"``delete`` removes objects from the bucket and frees aggregate byte "
+"accounting. ``get_usage`` reports ``usage_fraction == -1.0`` when "
+"``max_capacity_gb`` is ``0`` (disabled); set a non-zero "
+"``max_capacity_gb`` to enable the watermark-triggered eviction "
+"controller. Locked keys (in-flight loads) are skipped."
+msgstr "``delete`` 从桶中移除对象并释放聚合字节计数。当 ``max_capacity_gb`` 为 ``0``\\ （禁用）时，\\ ``get_usage`` 报告 ``usage_fraction == -1.0``\\ ；设置非零的 ``max_capacity_gb`` 以启用基于水印的逐出控制器。锁定的键（正在加载的）会被跳过。"
+
+#: ../../source/mp/l2_storage/index.rst:279
+msgid "``dax``"
+msgstr "``dax``"
+
+#: ../../source/mp/l2_storage/index.rst:280
+msgid ""
+"Full support. ``delete`` removes unlocked keys from the in-memory index "
+"immediately and recycles fixed slots once active read borrows drain. "
+"Usage is slot-based."
+msgstr "完全支持。\\ ``delete`` 会立即从内存索引中移除未锁定的键，并在活跃读取借用排空后回收固定槽。使用量以槽数为单位计算。"
+
+#: ../../source/mp/l2_storage/index.rst:283
+msgid "``mooncake_store``"
+msgstr "``mooncake_store``"
+
+#: ../../source/mp/l2_storage/index.rst:284
+msgid "No eviction support (native connector adapter)."
+msgstr "不支持逐出（原生连接器适配器）。"
+
+#: ../../source/mp/l2_storage/index.rst:285
+msgid "``fs``"
+msgstr "``fs``"
+
+#: ../../source/mp/l2_storage/index.rst:286
+msgid "No eviction support (``delete`` and ``get_usage`` are no-ops)."
+msgstr "不支持逐出（\\ ``delete`` 和 ``get_usage`` 均为空操作）。"
+
+#: ../../source/mp/l2_storage/index.rst:287
+msgid "native connectors"
+msgstr "原生连接器"
+
+#: ../../source/mp/l2_storage/index.rst:288
+msgid "No eviction support."
+msgstr "不支持逐出。"
+
+#: ../../source/mp/l2_storage/index.rst:292
+msgid ""
+"Each L2 adapter instance gets its own independent eviction controller and"
+" policy.  Two adapters of the same type can have different watermarks or "
+"policies."
+msgstr "每个 L2 适配器实例都有自己独立的逐出控制器和策略。两个相同类型的适配器可以有不同的水位线或策略。"
+
+#: ../../source/mp/l2_storage/index.rst:297
+msgid "Combined L1 + L2 Eviction Example"
+msgstr "L1 + L2 逐出示例"
+
+#: ../../source/mp/l2_storage/index.rst:317
+msgid "In this setup:"
+msgstr "在此设置中："
+
+#: ../../source/mp/l2_storage/index.rst:319
+#, python-format
+msgid ""
+"L1 evicts from memory when it is 80 % full, reclaiming 20 % of allocated "
+"memory per cycle."
+msgstr "当 L1 的内存使用达到 80% 时，它会逐出内存，每个周期回收 20% 的分配内存。"
+
+#: ../../source/mp/l2_storage/index.rst:321
+#, python-format
+msgid ""
+"L2 (NIXL/GDS) evicts from the storage pool when 90 % of pool slots are "
+"occupied, reclaiming 10 % per cycle."
+msgstr "L2 (NIXL/GDS) 在存储池中当 90% 的池槽被占用时进行逐出，每个周期回收 10%。"
+
+#: ../../source/mp/l2_storage/index.rst:323
+msgid ""
+"Both tiers use independent LRU policies, so each evicts its own least-"
+"recently-used keys."
+msgstr "两个层级使用独立的 LRU 策略，因此每个层级逐出其自身的最近最少使用的键。"
+
+#: ../../source/mp/l2_storage/index.rst:327
+msgid "Verifying L2 Storage"
+msgstr "验证 L2 存储"
+
+#: ../../source/mp/l2_storage/index.rst:329
+msgid "Set ``LMCACHE_LOG_LEVEL=DEBUG`` to see L2 activity in the server logs:"
+msgstr "设置 ``LMCACHE_LOG_LEVEL=DEBUG`` 以在服务器日志中查看 L2 活动："
+
+#: ../../source/mp/l2_storage/index.rst:337
+msgid "Expected log messages when L2 is active:"
+msgstr "L2 运行时的预期日志消息："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/mock.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/mock.po
new file mode 100644
index 0000000..af80403
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/mock.po
@@ -0,0 +1,43 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/mock.rst:2
+msgid "Mock"
+msgstr "模拟"
+
+#: ../../source/mp/l2_storage/mock.rst:4
+msgid ""
+"Simulates L2 storage with configurable size and bandwidth.  Useful for "
+"testing the L2 pipeline without real storage hardware."
+msgstr "模拟具有可配置大小和带宽的 L2 存储。适用于在无真实存储硬件的情况下对 L2 流水线进行测试。"
+
+#: ../../source/mp/l2_storage/mock.rst:7
+msgid "**Fields:**"
+msgstr "**字段：**"
+
+#: ../../source/mp/l2_storage/mock.rst:9
+msgid "``max_size_gb``: Maximum size in GB (> 0)."
+msgstr "``max_size_gb``：最大容量（单位：GB，须大于 0）。"
+
+#: ../../source/mp/l2_storage/mock.rst:10
+msgid "``mock_bandwidth_gb``: Simulated bandwidth in GB/sec (> 0)."
+msgstr "``mock_bandwidth_gb``：模拟带宽（单位：GB/秒，须大于 0）。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/mooncake_store.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/mooncake_store.po
new file mode 100644
index 0000000..5a70d66
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/mooncake_store.po
@@ -0,0 +1,169 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:2
+msgid "Mooncake Store"
+msgstr "Mooncake Store"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:4
+msgid ""
+"An L2 adapter backed by the native C++ Mooncake Store connector.  Uses "
+"`Mooncake <https://github.com/kvcache-ai/Mooncake>`_ for high-performance"
+" distributed KV cache storage with RDMA support."
+msgstr "一个由原生 C++ Mooncake Store 连接器支持的 L2 适配器。使用 `Mooncake <https://github.com/kvcache-ai/Mooncake>`_ 进行高性能分布式 KV Cache 存储，并支持 RDMA。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:8
+msgid ""
+"When Mooncake is configured with ``\"protocol\": \"rdma\"``, LMCache must"
+" also have a valid contiguous L1 memory region available.  The "
+"distributed storage manager passes this L1 memory descriptor to the "
+"adapter factory automatically in MP mode.  If the descriptor is missing "
+"or invalid, adapter creation fails with ``ValueError`` instead of "
+"silently falling back to a non-RDMA path."
+msgstr "当 Mooncake 配置为 ``\"protocol\": \"rdma\"`` 时，LMCache 还必须有一个有效的连续 L1 内存区域可用。分布式存储管理器会在 MP 模式下自动将此 L1 内存描述符传递给适配器工厂。如果描述符缺失或无效，适配器创建将失败并抛出 ``ValueError``\\ ，而不是默默地回退到非 RDMA 路径。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:14
+msgid "**Prerequisites -- Building with Mooncake support:**"
+msgstr "**前提条件——启用 Mooncake 支持的构建：**"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:16
+msgid ""
+"The Mooncake extension is **not** built by default.  You must explicitly "
+"enable it:"
+msgstr "Mooncake 扩展\\ **默认不**\\ 构建。您必须显式启用它："
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:23
+msgid "The ``BUILD_MOONCAKE`` environment variable controls compilation:"
+msgstr "``BUILD_MOONCAKE`` 环境变量控制编译："
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:25
+msgid "``BUILD_MOONCAKE=1``: Enable the Mooncake C++ extension."
+msgstr "``BUILD_MOONCAKE=1``: 启用 Mooncake C++ 扩展。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:26
+msgid ""
+"``BUILD_MOONCAKE=0``: Force disable (highest priority), even if "
+"``MOONCAKE_INCLUDE_DIR`` is set."
+msgstr "``BUILD_MOONCAKE=0``: 强制禁用（优先级最高），即使 ``MOONCAKE_INCLUDE_DIR`` 已设置。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:28
+msgid ""
+"**Not set**: Falls back to checking ``MOONCAKE_INCLUDE_DIR`` for backward"
+" compatibility.  If ``MOONCAKE_INCLUDE_DIR`` is also unset, the extension"
+" is skipped."
+msgstr "**未设置**\\ ：回退到检查 ``MOONCAKE_INCLUDE_DIR`` 以保持向后兼容。如果 ``MOONCAKE_INCLUDE_DIR`` 也未设置，则跳过该扩展。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:32
+msgid ""
+"If the Mooncake headers are not installed in the system include path "
+"(e.g., ``/usr/local/include``), you must point to them explicitly:"
+msgstr "如果系统包含路径中未安装 Mooncake 头文件（例如，\\ ``/usr/local/include``\\ ），则必须显式指向它们："
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:42
+msgid "**LMCache-specific fields:**"
+msgstr "**LMCache 专有字段：**"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:44
+msgid ""
+"``num_workers``: Number of C++ worker threads for the shared pool "
+"(default ``4``, must be > 0)."
+msgstr "``num_workers``: 共享池的 C++ 工作线程数量（默认 ``4``\\ ，必须大于 0）。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:47
+msgid ""
+"``per_op_workers`` (``dict[str, int]``, optional): A dict mapping lane "
+"keys to dedicated worker thread counts.  Supported keys:"
+msgstr "``per_op_workers`` (``dict[str, int]``, 可选)：将操作类型键映射到专用工作线程数的字典。支持的键："
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:50
+msgid "``\"lookup\"`` — threads for ``EXISTS`` operations."
+msgstr "``\"lookup\"`` — 用于 ``EXISTS`` 操作的线程。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:51
+msgid "``\"retrieve\"`` — threads for ``GET`` / load operations."
+msgstr "``\"retrieve\"`` — 处理 ``GET`` / 加载操作的线程。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:52
+msgid "``\"store\"`` — threads for ``SET`` / put operations."
+msgstr "``\"store\"`` — 处理 ``SET`` / 放置操作的线程。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:53
+msgid "``\"delete\"`` — threads for ``DELETE`` operations."
+msgstr "``\"delete\"`` — 用于 ``DELETE`` 操作的线程。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:55
+msgid ""
+"Operations whose lane key is **not** present in the dict use the shared "
+"``num_workers`` pool.  There is no requirement to set all keys — you can "
+"configure only the lanes that need dedicated pools."
+msgstr "未在字典中列出的操作类型键将使用共享的 ``num_workers`` 池。无需设置所有键——您只需配置需要专用池的操作类型即可。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:59
+msgid "**Mooncake fields:**"
+msgstr "**Mooncake 字段：**"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:61
+msgid ""
+"All other keys in the JSON config (except ``type``, ``num_workers``, "
+"``per_op_workers``, and ``eviction``) are forwarded **as-is** to "
+"Mooncake's ``setup_internal(ConfigDict)``.  Refer to the `Mooncake "
+"documentation <https://github.com/kvcache-ai/Mooncake>`_ for available "
+"setup keys (e.g., ``local_hostname``, ``metadata_server``, "
+"``master_server_addr``, ``protocol``, ``rdma_devices``, "
+"``global_segment_size``)."
+msgstr "JSON 配置中的所有其他键（除了 ``type``, ``num_workers``, ``per_op_workers`` 和 ``eviction``\\ ）都将 **原样** 转发给 Mooncake 的 ``setup_internal(ConfigDict)``\\ 。有关可用的设置键（例如 ``local_hostname``, ``metadata_server``, ``master_server_addr``, ``protocol``, ``rdma_devices``, ``global_segment_size``\\ ），请参阅 `Mooncake 文档 <https://github.com/kvcache-ai/Mooncake>`_。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:69
+msgid "**Configuration example:**"
+msgstr "**配置示例：**"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:99
+msgid ""
+"For full Mooncake setup instructions (master service, metadata server, "
+"etc.), see `Mooncake <https://github.com/kvcache-ai/Mooncake>`_ ."
+msgstr "有关完整的 Mooncake 设置说明（主服务、元数据服务器等），请参阅 `Mooncake <https://github.com/kvcache-ai/Mooncake>`_ 。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:102
+msgid "**RDMA notes:**"
+msgstr "**RDMA 注意事项：**"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:104
+msgid "``protocol: \"rdma\"`` requires a valid LMCache L1 memory descriptor."
+msgstr "``protocol: \"rdma\"`` 需要一个有效的 LMCache L1 内存描述符。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:105
+msgid ""
+"When using ``protocol: \"rdma\"``, it is recommended to disable lazy L1 "
+"allocation with ``--no-l1-use-lazy`` so the L1 buffer is fully allocated "
+"before Mooncake registers it."
+msgstr "使用 ``protocol: \"rdma\"`` 时，建议通过 ``--no-l1-use-lazy`` 禁用延迟 L1 分配，以便在 Mooncake 注册前完整分配 L1 缓冲区。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:108
+msgid "``protocol: \"tcp\"`` does not require L1 preregistration."
+msgstr "``protocol: \"tcp\"`` 不需要 L1 预注册。"
+
+#: ../../source/mp/l2_storage/mooncake_store.rst:109
+msgid ""
+"If Mooncake RDMA initialization fails at adapter creation time, verify "
+"that LMCache L1 memory is enabled and that the descriptor has a non-zero "
+"pointer and size."
+msgstr "如果 Mooncake RDMA 初始化在适配器创建时失败，请验证 LMCache L1 内存是否已启用，并确保描述符具有非零指针和大小。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/nixl.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/nixl.po
new file mode 100644
index 0000000..9b09443
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/nixl.po
@@ -0,0 +1,248 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/nixl.rst:2
+msgid "NIXL"
+msgstr "NIXL"
+
+#: ../../source/mp/l2_storage/nixl.rst:4
+msgid ""
+"NIXL-based persistent storage — the primary production L2 backend, using "
+"NIXL (NVIDIA Interconnect Library) for high-performance storage I/O. Two "
+"adapter types share this backend:"
+msgstr "基于 NIXL 的持久存储 — 主要的生产 L2 后端，使用 NIXL（NVIDIA 互连库）进行高性能存储 I/O。两种适配器类型共享此后端："
+
+#: ../../source/mp/l2_storage/nixl.rst:8
+msgid ""
+"``nixl_store`` — a fixed pool of storage descriptors pre-allocated at "
+"init."
+msgstr "``nixl_store`` — 在初始化时预分配的固定存储描述符池。"
+
+#: ../../source/mp/l2_storage/nixl.rst:9
+msgid ""
+"``nixl_store_dynamic`` — opens and registers files per operation, adding "
+"persist/recover across restarts and removing the open-file-descriptor "
+"limit."
+msgstr "``nixl_store_dynamic`` — 每次操作时动态打开并注册文件，支持跨重启的持久化/恢复，并消除打开文件描述符数量的限制。"
+
+#: ../../source/mp/l2_storage/nixl.rst:13
+msgid "Static pool — ``nixl_store``"
+msgstr "静态池 — ``nixl_store``"
+
+#: ../../source/mp/l2_storage/nixl.rst:15
+msgid ""
+"The primary production adapter. Pre-allocates a pool of storage "
+"descriptors at initialization."
+msgstr "主要的生产适配器。在初始化时预分配一组存储描述符池。"
+
+#: ../../source/mp/l2_storage/nixl.rst:18
+#: ../../source/mp/l2_storage/nixl.rst:92
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/nixl.rst:20
+msgid ""
+"``backend``: Storage backend -- one of ``POSIX``, ``GDS``, ``GDS_MT``, "
+"``HF3FS``, ``OBJ``, ``AZURE_BLOB``."
+msgstr "``backend``: 存储后端 -- 以下之一：``POSIX``、``GDS``、``GDS_MT``、``HF3FS``、``OBJ``、``AZURE_BLOB``。"
+
+#: ../../source/mp/l2_storage/nixl.rst:22
+msgid ""
+"``pool_size``: Number of storage descriptors to pre-allocate (must be > "
+"0)."
+msgstr "``pool_size``: 预分配的存储描述符数量（必须大于 0）。"
+
+#: ../../source/mp/l2_storage/nixl.rst:24
+#: ../../source/mp/l2_storage/nixl.rst:97
+msgid "**Backend-specific parameters (``backend_params``):**"
+msgstr "**后端特定参数 (``backend_params``):**"
+
+#: ../../source/mp/l2_storage/nixl.rst:26
+msgid "File-based backends (``GDS``, ``GDS_MT``, ``POSIX``, ``HF3FS``) require:"
+msgstr "基于文件的后端（``GDS``, ``GDS_MT``, ``POSIX``, ``HF3FS``）需要："
+
+#: ../../source/mp/l2_storage/nixl.rst:28
+msgid "``file_path``: Directory path for storing L2 data."
+msgstr "``file_path``: 存储 L2 数据的目录路径。"
+
+#: ../../source/mp/l2_storage/nixl.rst:29
+msgid ""
+"``use_direct_io``: ``\"true\"`` or ``\"false\"`` -- whether to use direct"
+" I/O."
+msgstr "``use_direct_io``: ``\"true\"`` 或 ``\"false\"`` -- 是否使用直接 I/O。"
+
+#: ../../source/mp/l2_storage/nixl.rst:31
+msgid ""
+"The ``OBJ`` and ``AZURE_BLOB`` backends (object stores) do not require "
+"``file_path``."
+msgstr "``OBJ`` 和 ``AZURE_BLOB`` 后端（对象存储）不需要 ``file_path``。"
+
+#: ../../source/mp/l2_storage/nixl.rst:33
+msgid "**Backend descriptions:**"
+msgstr "**后端描述：**"
+
+#: ../../source/mp/l2_storage/nixl.rst:39
+msgid "Backend"
+msgstr "后端"
+
+#: ../../source/mp/l2_storage/nixl.rst:40
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/l2_storage/nixl.rst:41
+msgid "``POSIX``"
+msgstr "``POSIX``"
+
+#: ../../source/mp/l2_storage/nixl.rst:42
+msgid "Standard POSIX file I/O.  Works on any file system.  No direct I/O."
+msgstr "标准 POSIX 文件 I/O。适用于任何文件系统。无直接 I/O。"
+
+#: ../../source/mp/l2_storage/nixl.rst:43
+msgid "``GDS``"
+msgstr "``GDS``"
+
+#: ../../source/mp/l2_storage/nixl.rst:44
+msgid ""
+"NVIDIA GPU Direct Storage.  Enables direct GPU-to-storage transfers "
+"bypassing the CPU.  Requires NVMe SSDs with GDS support."
+msgstr "NVIDIA GPU 直接存储。启用直接的 GPU 到存储传输，绕过 CPU。需要支持 GDS 的 NVMe SSD。"
+
+#: ../../source/mp/l2_storage/nixl.rst:46
+msgid "``GDS_MT``"
+msgstr "``GDS_MT``"
+
+#: ../../source/mp/l2_storage/nixl.rst:47
+msgid "Multi-threaded variant of GDS for higher throughput."
+msgstr "GDS 的多线程变体，以提高吞吐量。"
+
+#: ../../source/mp/l2_storage/nixl.rst:48
+msgid "``HF3FS``"
+msgstr "``HF3FS``"
+
+#: ../../source/mp/l2_storage/nixl.rst:49
+msgid "Shared file system backend (e.g., for distributed/networked storage)."
+msgstr "共享文件系统后端（例如，用于分布式/网络存储）。"
+
+#: ../../source/mp/l2_storage/nixl.rst:50
+msgid "``OBJ``"
+msgstr "``OBJ``"
+
+#: ../../source/mp/l2_storage/nixl.rst:51
+msgid "Object store backend.  No local file path required."
+msgstr "对象存储后端。无需本地文件路径。"
+
+#: ../../source/mp/l2_storage/nixl.rst:52
+msgid "``AZURE_BLOB``"
+msgstr "``AZURE_BLOB``"
+
+#: ../../source/mp/l2_storage/nixl.rst:53
+msgid "Object store backend for Azure Blob Storage.  No local file path required."
+msgstr "Azure Blob Storage 的对象存储后端。无需本地文件路径。"
+
+#: ../../source/mp/l2_storage/nixl.rst:55
+#: ../../source/mp/l2_storage/nixl.rst:114
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
+#: ../../source/mp/l2_storage/nixl.rst:78
+msgid "Dynamic (persist / recover) — ``nixl_store_dynamic``"
+msgstr "动态（持久/恢复） — ``nixl_store_dynamic``"
+
+#: ../../source/mp/l2_storage/nixl.rst:80
+msgid ""
+"A dynamic variant of the NIXL adapter that opens and registers files per-"
+"operation instead of pre-allocating them at init. This enables:"
+msgstr "NIXL 适配器的动态变体，按操作打开和注册文件，而不是在初始化时预分配。该变体支持以下功能："
+
+#: ../../source/mp/l2_storage/nixl.rst:83
+msgid "**Persist/recover** -- cached KV metadata survives restarts."
+msgstr "**持久化/恢复** -- 缓存的 KV 元数据在重启后仍然存在。"
+
+#: ../../source/mp/l2_storage/nixl.rst:84
+msgid ""
+"**No fd limits** -- files are opened and closed per transfer, so the "
+"cache can grow beyond OS open-file-descriptor limits."
+msgstr "**无文件描述符限制** -- 文件在每次传输时打开和关闭，因此缓存可以超出操作系统的打开文件描述符限制。"
+
+#: ../../source/mp/l2_storage/nixl.rst:89
+msgid ""
+"Only file-based backends are supported (``POSIX``, ``GDS``, ``GDS_MT``, "
+"``HF3FS``). The ``OBJ`` and ``AZURE_BLOB`` backends are not supported "
+"yet."
+msgstr "仅支持基于文件的后端（``POSIX``, ``GDS``, ``GDS_MT``, ``HF3FS``）。``OBJ`` 和 ``AZURE_BLOB`` 后端尚不支持。"
+
+#: ../../source/mp/l2_storage/nixl.rst:94
+msgid ""
+"``backend``: Storage backend -- one of ``POSIX``, ``GDS``, ``GDS_MT``, "
+"``HF3FS``."
+msgstr "``backend``: 存储后端 -- 以下之一：``POSIX``、``GDS``、``GDS_MT``、``HF3FS``。"
+
+#: ../../source/mp/l2_storage/nixl.rst:99
+msgid "``file_path``: Directory path for storing L2 data files."
+msgstr "``file_path``: 存储 L2 数据文件的目录路径。"
+
+#: ../../source/mp/l2_storage/nixl.rst:100
+msgid "``use_direct_io``: ``\"true\"`` or ``\"false\"``."
+msgstr "``use_direct_io``: ``\"true\"`` 或 ``\"false\"``。"
+
+#: ../../source/mp/l2_storage/nixl.rst:101
+msgid ""
+"``max_capacity_gb``: Maximum storage capacity in GB. The adapter rejects "
+"stores when this limit is reached. Required for the eviction controller "
+"to compute usage."
+msgstr "``max_capacity_gb``: 最大存储容量（以 GB 为单位）。当达到此限制时，适配器会拒绝存储。此项是逐出控制器计算使用情况所必需的。"
+
+#: ../../source/mp/l2_storage/nixl.rst:105
+msgid "**Optional fields (for persist):**"
+msgstr "**可选字段（用于持久化）：**"
+
+#: ../../source/mp/l2_storage/nixl.rst:107
+msgid ""
+"``persist_enabled`` (bool, default ``true``): If ``true``, data files are"
+" kept on disk at shutdown. If ``false``, all data files are deleted on "
+"shutdown."
+msgstr "``persist_enabled`` (bool, 默认 ``true``): 若为 ``true``，关闭时数据文件将保留在磁盘上。若为 ``false``，关闭时所有数据文件将被删除。"
+
+#: ../../source/mp/l2_storage/nixl.rst:111
+msgid ""
+"Lookup always checks secondary storage (disk) on miss and lazily "
+"populates the in-memory index when a file is found."
+msgstr "查找时，若未命中则始终回退到二级存储（磁盘）进行检查；找到文件后，惰性填充内存索引。"
+
+#: ../../source/mp/l2_storage/nixl.rst:127
+msgid "**Persist / secondary lookup behaviour:**"
+msgstr "**持久化 / 二级查找行为:**"
+
+#: ../../source/mp/l2_storage/nixl.rst:129
+msgid ""
+"On **shutdown**, the adapter keeps data files on disk by default "
+"(``persist_enabled`` defaults to ``true``). If explicitly set to "
+"``false``, all data files are deleted to avoid orphaned storage."
+msgstr "在 **关闭** 时，适配器默认将数据文件保留在磁盘上（``persist_enabled`` 默认为 ``true``）。如果明确设置为 ``false``，则所有数据文件将被删除，以避免孤立存储。"
+
+#: ../../source/mp/l2_storage/nixl.rst:132
+msgid ""
+"On **startup**, the in-memory index is empty. Every lookup miss falls "
+"through to a secondary lookup on disk: if the deterministic file exists, "
+"it is treated as a hit and the in-memory index is populated lazily from "
+"the file size."
+msgstr "在 **启动** 时，内存索引为空。每次查找未命中都会回退到磁盘上的二级查找：若对应的确定性文件存在，则视为命中，并根据文件大小惰性填充内存索引。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/plugin.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/plugin.po
new file mode 100644
index 0000000..5cff742
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/plugin.po
@@ -0,0 +1,154 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/plugin.rst:2
+msgid "Plugin (Custom / External)"
+msgstr "插件（自定义 / 外部）"
+
+#: ../../source/mp/l2_storage/plugin.rst:4
+msgid ""
+"Two L2 adapter types load an adapter class from a *user-supplied* Python "
+"module at startup, so you can point LMCache at your own storage backend "
+"without modifying LMCache source.  This is the ``--l2-adapter`` analog of"
+" vLLM's ``kv_connector_module_path``."
+msgstr "两种 L2 适配器类型在启动时从 *用户提供* 的 Python 模块加载适配器类，因此您可以将 LMCache 指向您自己的存储后端，而无需修改 LMCache 源代码。这是 vLLM 的 ``kv_connector_module_path`` 的 ``--l2-adapter`` 类似项。"
+
+#: ../../source/mp/l2_storage/plugin.rst:9
+msgid ""
+"``plugin``: loads a pure-Python class that implements "
+"``L2AdapterInterface`` (the full L2 adapter contract)."
+msgstr "``plugin``: 加载一个实现 ``L2AdapterInterface``（完整的 L2 适配器契约）的纯 Python 类。"
+
+#: ../../source/mp/l2_storage/plugin.rst:11
+msgid ""
+"``native_plugin``: loads a pybind-wrapped C++ connector exposing a six-"
+"method async batch contract and wraps it in ``NativeConnectorL2Adapter``."
+"  Use this for native backends -- see also "
+":doc:`/developer_guide/extending_lmcache/native_connectors`."
+msgstr "``native_plugin``: 加载一个 pybind 封装的 C++ 连接器，暴露一个六方法异步批处理契约，并将其包装在 ``NativeConnectorL2Adapter`` 中。请将其用于本地后端 -- 另见 :doc:`/developer_guide/extending_lmcache/native_connectors`。"
+
+#: ../../source/mp/l2_storage/plugin.rst:17
+msgid "``plugin``"
+msgstr "``plugin``"
+
+#: ../../source/mp/l2_storage/plugin.rst:19
+msgid ""
+"Dynamically imports ``module_path`` and instantiates ``class_name``, "
+"which must be a subclass of ``L2AdapterInterface`` (validated at load "
+"time; a mismatch raises ``TypeError``)."
+msgstr "动态导入 ``module_path`` 并实例化 ``class_name``，该类必须是 ``L2AdapterInterface`` 的子类（在加载时进行验证；不匹配会引发 ``TypeError``）。"
+
+#: ../../source/mp/l2_storage/plugin.rst:23
+#: ../../source/mp/l2_storage/plugin.rst:67
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/plugin.rst:25
+msgid ""
+"``module_path`` (str): Dotted Python import path of the module containing"
+" the adapter class.  The module must be importable by the LMCache process"
+" (installed, or on ``PYTHONPATH``)."
+msgstr "``module_path`` (str): 包含适配器类的模块的点分 Python 导入路径。该模块必须可以被 LMCache 进程导入（已安装或在 ``PYTHONPATH`` 中）。"
+
+#: ../../source/mp/l2_storage/plugin.rst:28
+msgid ""
+"``class_name`` (str): Name of the class inside *module_path* that "
+"implements ``L2AdapterInterface``."
+msgstr "``class_name`` (str): *module_path* 中实现 ``L2AdapterInterface`` 的类的名称。"
+
+#: ../../source/mp/l2_storage/plugin.rst:31
+#: ../../source/mp/l2_storage/plugin.rst:73
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/plugin.rst:33
+#, python-brace-format
+msgid ""
+"``adapter_params`` (dict, default ``{}``): Arbitrary dict forwarded to "
+"the adapter constructor."
+msgstr "``adapter_params`` (字典，默认 ``{}``): 转发给适配器构造函数的任意字典。"
+
+#: ../../source/mp/l2_storage/plugin.rst:35
+msgid ""
+"``config_class_name`` (str): Name of a config class inside *module_path* "
+"that subclasses ``L2AdapterConfigBase``.  When set (or auto-discovered), "
+"the factory builds it via ``from_dict(adapter_params)`` and passes the "
+"config object -- instead of the raw ``adapter_params`` dict -- to the "
+"adapter constructor, matching the built-in adapter convention.  Discovery"
+" order when omitted: ``<class_name>Config`` in the module, then a "
+"``config_class_name`` attribute on the adapter class; otherwise the raw "
+"dict is passed."
+msgstr "``config_class_name`` (str): 在 *module_path* 中的配置类名称，该类是 ``L2AdapterConfigBase`` 的子类。当设置（或自动发现）时，工厂通过 ``from_dict(adapter_params)`` 构建它，并将配置对象（而不是原始的 ``adapter_params`` 字典）传递给适配器构造函数，以匹配内置适配器的约定。省略时的发现顺序：模块中的 ``<class_name>Config``，然后是适配器类上的 ``config_class_name`` 属性；否则传递原始字典。"
+
+#: ../../source/mp/l2_storage/plugin.rst:44
+#: ../../source/mp/l2_storage/plugin.rst:80
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
+#: ../../source/mp/l2_storage/plugin.rst:54
+msgid "See ``examples/lmc_external_l2_adapter/`` for a complete reference plugin."
+msgstr "请参阅 ``examples/lmc_external_l2_adapter/`` 以获取完整的参考插件。"
+
+#: ../../source/mp/l2_storage/plugin.rst:57
+msgid "``native_plugin``"
+msgstr "``native_plugin``"
+
+#: ../../source/mp/l2_storage/plugin.rst:59
+msgid ""
+"Dynamically imports ``module_path``, instantiates ``class_name`` with "
+"``adapter_params`` as constructor keyword arguments, verifies the "
+"instance exposes the required async batch methods (``event_fd``, "
+"``submit_batch_get``, ``submit_batch_set``, ``submit_batch_exists``, "
+"``drain_completions``, ``close``), and wraps it in "
+"``NativeConnectorL2Adapter``.  An optional ``submit_batch_delete`` "
+"enables L2 eviction deletes; without it, deletes are a no-op (logged as a"
+" warning)."
+msgstr "动态导入 ``module_path``，使用 ``adapter_params`` 作为构造函数关键字参数实例化 ``class_name``，验证实例是否暴露所需的异步批处理方法（``event_fd``、``submit_batch_get``、``submit_batch_set``、``submit_batch_exists``、``drain_completions``、``close``），并将其包装在 ``NativeConnectorL2Adapter`` 中。可选的 ``submit_batch_delete`` 允许 L2 逐出删除；如果没有它，删除操作将无效（记录为警告）。"
+
+#: ../../source/mp/l2_storage/plugin.rst:69
+msgid ""
+"``module_path`` (str): Dotted Python import path of the module containing"
+" the connector class."
+msgstr "``module_path`` (str): 包含连接器类的模块的点分 Python 导入路径。"
+
+#: ../../source/mp/l2_storage/plugin.rst:71
+msgid "``class_name`` (str): Name of the connector class inside *module_path*."
+msgstr "``class_name`` (str): *module_path* 中连接器类的名称。"
+
+#: ../../source/mp/l2_storage/plugin.rst:75
+#, python-brace-format
+msgid ""
+"``adapter_params`` (dict, default ``{}``): Forwarded as keyword arguments"
+" to the connector constructor."
+msgstr "``adapter_params`` (dict, default ``{}``): 作为关键字参数传递给连接器构造函数。"
+
+#: ../../source/mp/l2_storage/plugin.rst:77
+msgid ""
+"``max_capacity_gb`` (float, default ``0``): Aggregate L2 capacity in GB "
+"for usage tracking / eviction.  ``0`` disables aggregate eviction."
+msgstr "``max_capacity_gb`` (float, default ``0``): 用于使用跟踪/逐出的 GB 级别的 L2 总容量。 ``0`` 禁用总逐出。"
+
+#: ../../source/mp/l2_storage/plugin.rst:87
+msgid ""
+"See ``examples/lmc_external_native_connector/`` for a complete reference "
+"native connector."
+msgstr "请参阅 ``examples/lmc_external_native_connector/`` 以获取完整的参考本地连接器。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/raw_block.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/raw_block.po
new file mode 100644
index 0000000..0fdb4bf
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/raw_block.po
@@ -0,0 +1,185 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/raw_block.rst:2
+msgid "Raw Block (Rust)"
+msgstr "原始块（Rust）"
+
+#: ../../source/mp/l2_storage/raw_block.rst:4
+msgid ""
+"A built-in L2 adapter that stores KV objects in fixed-size slots on a raw"
+" block device or pre-sized file using the Rust raw-device I/O bindings. "
+"It reuses the existing raw-block metadata checkpoint model and writes "
+"directly into the caller-provided load buffers during prefetch."
+msgstr "一个内置的 L2 适配器，通过 Rust 原始设备 I/O 接口将 KV 对象存储在原始块设备或预设大小文件的固定大小槽位中。它复用现有的原始块元数据检查点模型，并在预取期间直接写入调用方提供的加载缓冲区。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:9
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/raw_block.rst:11
+msgid "``device_path``: Raw device path or pre-sized file path."
+msgstr "``device_path``: 原始设备路径或预设大小的文件路径。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:12
+msgid ""
+"``slot_bytes``: Fixed slot size in bytes. Must be aligned to "
+"``block_align``."
+msgstr "``slot_bytes``: 固定的槽大小（以字节为单位）。必须与 ``block_align`` 对齐。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:14
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/raw_block.rst:16
+msgid ""
+"``capacity_bytes``: Optional cap on the usable device bytes. Default "
+"``0`` means use the full device/file size."
+msgstr "``capacity_bytes``\\ ：可用设备字节的可选上限。默认值 ``0`` 表示使用完整的设备/文件大小。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:18
+msgid "``use_odirect``: ``true`` or ``false`` (default ``true``)."
+msgstr "``use_odirect``: ``true`` 或 ``false``\\ （默认 ``true``\\ ）。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:19
+msgid "``block_align``: Device alignment in bytes (default ``4096``)."
+msgstr "``block_align``: 设备对齐字节数（默认 ``4096``\\ ）。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:20
+msgid "``header_bytes``: Per-slot header reservation (default ``4096``)."
+msgstr "``header_bytes``: 每个槽位的头部预留大小（默认 ``4096``\\ ）。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:21
+msgid ""
+"``meta_total_bytes``: Reserved metadata checkpoint region (default "
+"``256MiB``)."
+msgstr "``meta_total_bytes``: 保留的元数据检查点区域（默认 ``256MiB``\\ ）。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:22
+msgid ""
+"``meta_magic`` / ``meta_version``: Metadata checkpoint identity/version "
+"knobs."
+msgstr "``meta_magic`` / ``meta_version``: 元数据检查点的标识符与版本号调节参数。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:23
+msgid ""
+"``meta_checkpoint_interval_sec`` / ``meta_idle_quiet_ms`` / "
+"``meta_enable_periodic`` / ``meta_verify_on_load``: Checkpoint and "
+"recovery controls carried over from the legacy raw-block backend."
+msgstr "``meta_checkpoint_interval_sec`` / ``meta_idle_quiet_ms`` / ``meta_enable_periodic`` / ``meta_verify_on_load``: 从旧版原始块后端沿用的检查点与恢复控制参数。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:26
+msgid ""
+"``load_checkpoint_on_init``: Load an existing on-device metadata "
+"checkpoint during startup (default ``true``). Set to ``false`` to start "
+"with an empty in-memory index instead."
+msgstr "``load_checkpoint_on_init``: 在启动时加载现有的设备元数据检查点（默认值为 ``true``\\ ）。设置为 ``false`` 以从空的内存索引开始。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:29
+msgid "``enable_zero_copy``: Try aligned direct-buffer I/O when possible."
+msgstr "``enable_zero_copy``: 尽可能尝试对齐的直接缓冲区 I/O。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:30
+msgid ""
+"``io_engine``: Rust raw-block I/O engine. Valid values are ``\"posix\"`` "
+"(default synchronous ``pread``/``pwrite`` path), ``\"io_uring\"`` (direct"
+" Rust io_uring syscall path)."
+msgstr "``io_engine``: Rust 原始块 I/O 引擎。有效值为 ``\"posix\"``\\ （默认同步 ``pread``/``pwrite`` 路径），\\ ``\"io_uring\"``\\ （直接 Rust io_uring 系统调用路径）。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:33
+msgid ""
+"``use_uring_cmd``: Enable NVMe passthrough via io_uring command interface"
+" for direct device access. Requires ``io_engine=\"io_uring\"`` and NVMe "
+"character device node (e.g., ``/dev/ng0n1``)."
+msgstr "``use_uring_cmd``: 通过 io_uring 命令接口启用 NVMe 直通以直接访问设备。需要 ``io_engine=\"io_uring\"`` 和 NVMe 字符设备节点（例如，\\ ``/dev/ng0n1``\\ ）。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:36
+msgid "``iouring_queue_depth``: Queue depth for ``io_engine=\"io_uring\"``."
+msgstr "``iouring_queue_depth``: ``io_engine=\"io_uring\"`` 的队列深度。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:37
+msgid ""
+"``max_data_transfer_size``: Maximum data transfer size for "
+"``use_uring_cmd=true``. Large transfers are split into smaller chunks "
+"that fit within device limits."
+msgstr "``max_data_transfer_size``: ``use_uring_cmd=true`` 的最大数据传输大小。大数据传输会被拆分成适合设备限制的小块。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:40
+msgid ""
+"``num_store_workers`` / ``num_lookup_workers`` / ``num_load_workers``: "
+"Worker-thread counts for each operation type."
+msgstr "``num_store_workers`` / ``num_lookup_workers`` / ``num_load_workers``: 每种操作类型的工作线程数量。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:43
+msgid "**Notes:**"
+msgstr "**注意：**"
+
+#: ../../source/mp/l2_storage/raw_block.rst:45
+msgid ""
+"``raw_block`` is a server-owned MP adapter. It does **not** support per-"
+"TP device-path mappings in MP mode."
+msgstr "``raw_block`` 是一个由服务端管理的 MP 适配器。它 **不** 支持 MP 模式下按 TP 粒度配置设备路径映射。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:47
+msgid ""
+"``raw_block`` remains ``\"type\": \"raw_block\"`` for all supported "
+"engines."
+msgstr "``raw_block`` 在所有支持的引擎中保持 ``\"type\": \"raw_block\"``\\ 。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:48
+msgid ""
+"``raw_block`` owns on-device slot allocation, checkpointing, and recovery"
+" through ``RawBlockCore``. Slot reclamation is driven by the "
+"shared/global L2 eviction controller or explicit ``delete()`` calls."
+msgstr "``raw_block`` 负责设备上的槽分配、检查点和通过 ``RawBlockCore`` 的恢复。槽回收由共享/全局 L2 逐出控制器或显式的 ``delete()`` 调用驱动。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:51
+msgid ""
+"If ``use_odirect`` is enabled, the server's ``--l1-align-bytes`` should "
+"be at least ``block_align``."
+msgstr "如果启用了 ``use_odirect``\\ ，则服务器的 ``--l1-align-bytes`` 应至少为 ``block_align``\\ 。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:53
+msgid "``persist_enabled`` must remain ``true`` for this adapter."
+msgstr "``persist_enabled`` 对此适配器必须保持为 ``true``\\ 。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:54
+msgid ""
+"For ``use_uring_cmd=true``, ``device_path`` must use the NVMe character "
+"device node (e.g., ``/dev/ng0n1``) instead of the block device node "
+"(``/dev/nvme0n1``). The character device provides direct NVMe command "
+"passthrough."
+msgstr "对于 ``use_uring_cmd=true``\\ ，\\ ``device_path`` 必须使用 NVMe 字符设备节点（例如，\\ ``/dev/ng0n1``\\ ），而不是块设备节点（\\ ``/dev/nvme0n1``\\ ）。字符设备提供直接的 NVMe 命令直通。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:58
+msgid "``use_uring_cmd`` requires ``io_engine=\"io_uring\"`` to be set."
+msgstr "``use_uring_cmd`` 需要设置 ``io_engine=\"io_uring\"``\\ 。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:59
+msgid ""
+"When ``use_uring_cmd=true``, ``use_odirect`` is ignored for NVMe "
+"namespace character devices."
+msgstr "当 ``use_uring_cmd=true`` 时，NVMe 命名空间字符设备将忽略 ``use_odirect``\\ 。"
+
+#: ../../source/mp/l2_storage/raw_block.rst:62
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/remote_and_distributed.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/remote_and_distributed.po
new file mode 100644
index 0000000..eb32c8a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/remote_and_distributed.po
@@ -0,0 +1,31 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/remote_and_distributed.rst:2
+msgid "Remote & Distributed"
+msgstr "远程与分布式"
+
+#: ../../source/mp/l2_storage/remote_and_distributed.rst:4
+msgid ""
+"Object stores and distributed KV stores -- suited to warm/cold cache "
+"tiers and sharing cache across nodes."
+msgstr "对象存储和分布式 KV 存储 -- 适用于温/冷缓存分层场景以及跨节点共享缓存。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/resp.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/resp.po
new file mode 100644
index 0000000..6cbab90
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/resp.po
@@ -0,0 +1,78 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/resp.rst:2
+msgid "RESP (Redis/Valkey)"
+msgstr "RESP (Redis/Valkey)"
+
+#: ../../source/mp/l2_storage/resp.rst:4
+msgid ""
+"An L2 adapter backed by a native RESP (Redis Serialization Protocol) "
+"connector, targeting **Redis** or **Valkey** servers. I/O is dispatched "
+"through a C++ worker-thread pool."
+msgstr "由原生 RESP（Redis 序列化协议）连接器驱动的 L2 适配器，面向 **Redis** 或 **Valkey** 服务器。I/O 通过 C++ 工作线程池进行调度。"
+
+#: ../../source/mp/l2_storage/resp.rst:8
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/resp.rst:10
+msgid "``host``: Redis/Valkey server hostname or IP."
+msgstr "``host``: Redis/Valkey 服务器主机名或 IP。"
+
+#: ../../source/mp/l2_storage/resp.rst:11
+msgid "``port``: Server port (positive integer)."
+msgstr "``port``: 服务器端口（正整数）。"
+
+#: ../../source/mp/l2_storage/resp.rst:13
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/resp.rst:15
+msgid "``num_workers`` (int, default ``8``): C++ worker threads for I/O (> 0)."
+msgstr "``num_workers`` (int, 默认 ``8``): 用于 I/O 的 C++ 工作线程 (> 0)。"
+
+#: ../../source/mp/l2_storage/resp.rst:16
+msgid "``username`` (string, default ``\"\"``): Auth username."
+msgstr "``username`` (字符串，默认 ``\"\"``)：认证用户名。"
+
+#: ../../source/mp/l2_storage/resp.rst:17
+msgid "``password`` (string, default ``\"\"``): Auth password."
+msgstr "``password`` (字符串，默认 ``\"\"``)：认证密码。"
+
+#: ../../source/mp/l2_storage/resp.rst:18
+msgid ""
+"``max_capacity_gb`` (float, default ``0``): Max L2 capacity in GB for "
+"usage tracking / aggregate eviction. ``0`` disables tracking."
+msgstr "``max_capacity_gb`` (float，默认 ``0``)：L2 存储的最大容量上限（GB），用于容量跟踪与聚合逐出。设为 ``0`` 则禁用跟踪。"
+
+#: ../../source/mp/l2_storage/resp.rst:21
+msgid ""
+"When ``host``, ``port``, ``username``, or ``password`` are left empty, "
+"the adapter falls back to the corresponding environment variables at "
+"creation time: ``LMCACHE_RESP_HOST``, ``LMCACHE_RESP_PORT``, "
+"``LMCACHE_RESP_USERNAME``, ``LMCACHE_RESP_PASSWORD``."
+msgstr "当 ``host``、``port``、``username`` 或 ``password`` 留空时，适配器在创建时会回退到相应的环境变量： ``LMCACHE_RESP_HOST``、``LMCACHE_RESP_PORT``、``LMCACHE_RESP_USERNAME``、``LMCACHE_RESP_PASSWORD``。"
+
+#: ../../source/mp/l2_storage/resp.rst:26
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/s3.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/s3.po
new file mode 100644
index 0000000..4c9faa0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/s3.po
@@ -0,0 +1,88 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/s3.rst:2
+msgid "S3"
+msgstr "S3"
+
+#: ../../source/mp/l2_storage/s3.rst:4
+msgid ""
+"An L2 adapter that stores KV cache objects as S3 objects using the AWS "
+"Common Runtime (CRT).  Works with AWS S3, S3 Express One Zone, and any "
+"S3-compatible endpoint (MinIO, Ceph RGW, etc.)."
+msgstr "一个 L2 适配器，使用 AWS 通用运行时 (CRT) 将 KV cache 对象存储为 S3 对象。支持 AWS S3、S3 Express One Zone 以及任何兼容 S3 的端点（MinIO、Ceph RGW 等）。"
+
+#: ../../source/mp/l2_storage/s3.rst:8
+msgid "**Required fields:**"
+msgstr "**必填字段：**"
+
+#: ../../source/mp/l2_storage/s3.rst:10
+msgid ""
+"``s3_endpoint``: Bucket URL -- either ``\"s3://<bucket>\"`` or the bare "
+"host form (used for non-AWS endpoints)."
+msgstr "``s3_endpoint``: 存储桶 URL -- 可以是 ``\"s3://<bucket>\"`` 或纯主机名形式（用于非 AWS 端点）。"
+
+#: ../../source/mp/l2_storage/s3.rst:12
+msgid "``s3_region``: AWS region string (e.g. ``\"us-west-2\"``)."
+msgstr "``s3_region``: AWS 区域字符串（例如 ``\"us-west-2\"``）。"
+
+#: ../../source/mp/l2_storage/s3.rst:14
+msgid "**Optional fields:**"
+msgstr "**可选字段：**"
+
+#: ../../source/mp/l2_storage/s3.rst:16
+msgid "``s3_num_io_threads`` (int, default ``64``): Number of CRT I/O threads."
+msgstr "``s3_num_io_threads`` (int, default ``64``): CRT I/O 线程数。"
+
+#: ../../source/mp/l2_storage/s3.rst:17
+msgid "``s3_prefer_http2`` (bool, default ``true``): Negotiate HTTP/2 via ALPN."
+msgstr "``s3_prefer_http2`` (bool, default ``true``): 通过 ALPN 协商 HTTP/2。"
+
+#: ../../source/mp/l2_storage/s3.rst:18
+msgid ""
+"``s3_enable_s3express`` (bool, default ``false``): Enable S3 Express "
+"signing for S3 Express One Zone buckets."
+msgstr "``s3_enable_s3express`` (bool, default ``false``): 为 S3 Express 单可用区存储桶启用 S3 Express 签名。"
+
+#: ../../source/mp/l2_storage/s3.rst:20
+msgid ""
+"``disable_tls`` (bool, default ``false``): Bypass TLS when pointing at a "
+"plain-HTTP endpoint (e.g. a local MinIO)."
+msgstr "``disable_tls`` (bool, default ``false``): 在指向普通 HTTP 端点时绕过 TLS（例如本地 MinIO）。"
+
+#: ../../source/mp/l2_storage/s3.rst:22
+msgid ""
+"``aws_access_key_id`` / ``aws_secret_access_key`` (string): Static "
+"credentials; omit both to use the AWS default credential provider chain "
+"(environment, EC2 instance profile, etc.)."
+msgstr "``aws_access_key_id`` / ``aws_secret_access_key`` （字符串）：静态凭证；若两者均省略，则使用 AWS 默认凭证提供链（环境变量、EC2 实例配置等）。"
+
+#: ../../source/mp/l2_storage/s3.rst:25
+msgid ""
+"``max_capacity_gb`` (float, default ``0.0``): Aggregate capacity used by "
+"``get_usage()``.  A value of ``0`` disables aggregate eviction "
+"(``usage_fraction == -1.0``)."
+msgstr "``max_capacity_gb`` (浮点数，默认 ``0.0``)：由 ``get_usage()`` 使用的总容量。值为 ``0`` 时禁用总逐出（``usage_fraction == -1.0``）。"
+
+#: ../../source/mp/l2_storage/s3.rst:29
+msgid "**Configuration examples:**"
+msgstr "**配置示例：**"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/supported_storages.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/supported_storages.po
new file mode 100644
index 0000000..355e644
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/l2_storage/supported_storages.po
@@ -0,0 +1,182 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:2
+msgid "Supported Backends"
+msgstr "支持的后端"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:4
+msgid ""
+"LMCache ships several L2 storage backends. Select one or more with the "
+"``--l2-adapter`` flag (each backend's ``\"type\"`` is shown below); every"
+" backend has its own configuration page. They are grouped by the kind of "
+"medium they target."
+msgstr ""
+"LMCache 提供了多个 L2 存储后端。使用 ``--l2-adapter`` 标志选择一个或多个（每个后端的 ``\"type\"`` "
+"如下所示）；每个后端均有其各自的配置页面。它们按目标介质的类型进行分组。"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:13
+msgid "Backend"
+msgstr "后端"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:14
+msgid "``--l2-adapter`` type"
+msgstr "``--l2-adapter`` 类型"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:15
+msgid "Group"
+msgstr "组"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:16
+msgid ":doc:`NIXL <nixl>`"
+msgstr ":doc:`NIXL <nixl>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:17
+msgid "``nixl_store`` / ``nixl_store_dynamic``"
+msgstr "``nixl_store`` / ``nixl_store_dynamic``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:18
+msgid "High-performance I/O"
+msgstr "高性能 I/O"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:19
+msgid ":doc:`FileSystem <fs>`"
+msgstr ":doc:`文件系统 <fs>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:20
+msgid "``fs``"
+msgstr "``fs``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:21
+#: ../../source/mp/l2_storage/supported_storages.rst:24
+#: ../../source/mp/l2_storage/supported_storages.rst:27
+msgid "File & Block"
+msgstr "文件与块"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:22
+msgid ":doc:`FS (native) <fs_native>`"
+msgstr ":doc:`FS（原生）<fs_native>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:23
+msgid "``fs_native``"
+msgstr "``fs_native``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:25
+msgid ":doc:`Raw Block (Rust) <raw_block>`"
+msgstr ":doc:`原始块 (Rust) <raw_block>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:26
+msgid "``raw_block``"
+msgstr "``raw_block``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:28
+msgid ":doc:`S3 <s3>`"
+msgstr ":doc:`S3 <s3>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:29
+msgid "``s3``"
+msgstr "``s3``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:30
+#: ../../source/mp/l2_storage/supported_storages.rst:33
+#: ../../source/mp/l2_storage/supported_storages.rst:36
+#: ../../source/mp/l2_storage/supported_storages.rst:39
+#: ../../source/mp/l2_storage/supported_storages.rst:42
+msgid "Remote & Distributed"
+msgstr "远程与分布式"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:31
+msgid ":doc:`HF Bucket <hfbucket>`"
+msgstr ":doc:`HF Bucket <hfbucket>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:32
+msgid "``hfbucket``"
+msgstr "``hfbucket``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:34
+msgid ":doc:`Mooncake Store <mooncake_store>`"
+msgstr ":doc:`Mooncake Store <mooncake_store>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:35
+msgid "``mooncake_store``"
+msgstr "``mooncake_store``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:37
+msgid ":doc:`RESP (Redis/Valkey) <resp>`"
+msgstr ":doc:`RESP (Redis/Valkey) <resp>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:38
+msgid "``resp``"
+msgstr "``resp``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:40
+msgid ":doc:`Aerospike <aerospike>`"
+msgstr ":doc:`Aerospike <aerospike>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:41
+msgid "``aerospike``"
+msgstr "``aerospike``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:43
+msgid ":doc:`DAX <dax>`"
+msgstr ":doc:`DAX <dax>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:44
+msgid "``dax``"
+msgstr "``dax``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:45
+msgid "Byte-addressable memory"
+msgstr "字节可寻址内存"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:46
+msgid ":doc:`Mock <mock>`"
+msgstr ":doc:`Mock <mock>`"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:47
+msgid "``mock``"
+msgstr "``mock``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:48
+#: ../../source/mp/l2_storage/supported_storages.rst:51
+msgid "Testing"
+msgstr "测试"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:49
+msgid ":doc:`Fault Inject <fault_inject>`"
+msgstr "`:doc:`故障注入 <fault_inject>` `"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:50
+msgid "``fault_inject``"
+msgstr "``fault_inject``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:52
+msgid ":doc:`Plugin <plugin>`"
+msgstr "`:doc:`插件 <plugin>` `"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:53
+msgid "``plugin`` / ``native_plugin``"
+msgstr "``plugin`` / ``native_plugin``"
+
+#: ../../source/mp/l2_storage/supported_storages.rst:54
+msgid "Custom / External"
+msgstr "自定义 / 外部"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/index.po
new file mode 100644
index 0000000..faf4087
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/index.po
@@ -0,0 +1,455 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/observability/index.rst:2
+msgid "Observability"
+msgstr "可观察性"
+
+#: ../../source/mp/observability/index.rst:4
+msgid ""
+"LMCache multiprocess mode provides three complementary observability "
+"modes: **metrics** (Prometheus counters via OTel), **logging** (Python "
+"logging with optional OTel log forwarding), and **tracing** (OTel spans "
+"for per-request latency)."
+msgstr ""
+"LMCache MP 模式（多进程）提供三种互补的可观察性模式：\\ **指标**\\ （通过 OTel 的 Prometheus 计数器）、\\"
+" **日志**\\ （带有可选 OTel 日志转发的 Python 日志记录）和 **追踪**\\ （OTel "
+"span，用于每个请求的延迟分析）。"
+
+#: ../../source/mp/observability/index.rst:9
+msgid ""
+"All three modes are powered by an internal **EventBus** that decouples "
+"producers (L1Manager, StorageManager, MPCacheServer) from subscribers."
+msgstr ""
+"这三种模式都由一个内部的 **EventBus** "
+"提供支持，该总线将生产者（L1Manager、StorageManager、MPCacheServer）与订阅者解耦。"
+
+#: ../../source/mp/observability/index.rst:17
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/mp/observability/index.rst:19
+msgid ""
+"By default, **metrics** and **logging** are enabled; **tracing** is "
+"disabled. No extra flags are needed:"
+msgstr "默认情况下，\\ **指标**\\ 和\\ **日志记录**\\ 是启用的；\\ **追踪**\\ 是禁用的。无需额外的标志："
+
+#: ../../source/mp/observability/index.rst:27
+msgid ""
+"The server then exposes Prometheus metrics at ``/metrics`` on its **HTTP "
+"frontend port** (``--http-port``, default ``8080``):"
+msgstr "服务器然后在其 **HTTP 前端端口** (``--http-port``, 默认 ``8080``) 上暴露 Prometheus 指标于 ``/metrics``："
+
+#: ../../source/mp/observability/index.rst:36
+msgid ""
+"For ``lmcache server``, ``/metrics`` lives on ``--http-port`` (default "
+"``8080``), **not** on ``--prometheus-port``: the HTTP frontend already "
+"serves ``/metrics``, so the standalone Prometheus server is disabled and "
+"``--prometheus-port`` has no effect under this command. ``--prometheus-"
+"port`` *is* the metrics endpoint for the frontend-less entrypoints "
+"(``python -m lmcache.v1.multiprocess.server`` and ``lmcache trace "
+"replay``) — see :ref:`mp-obs-metrics-endpoint`. Also note metrics are "
+"lazy: a series only appears *after* the first store/retrieve that "
+"produces it, so drive some traffic before scraping."
+msgstr "对于 ``lmcache server``，``/metrics`` 位于 ``--http-port``（默认 ``8080``），**而不是** ``--prometheus-port``：HTTP 前端已经提供了 ``/metrics``，因此独立的 Prometheus 服务器被禁用，``--prometheus-port`` 在此命令下没有效果。``--prometheus-port`` *是* 前端无入口点的指标端点（``python -m lmcache.v1.multiprocess.server`` 和 ``lmcache trace replay``）— 请参见 :ref:`mp-obs-metrics-endpoint`。还要注意，指标是惰性加载的：一个系列只有在第一次存储/检索产生它之后才会出现，因此在抓取之前请先驱动一些流量。"
+
+#: ../../source/mp/observability/index.rst:46
+msgid ""
+"To also see L2 (storage-tier) metrics, attach an L2 backend with "
+"``--l2-adapter``. The simplest is the local filesystem:"
+msgstr "要查看 L2（存储层）指标，请使用 ``--l2-adapter`` 附加一个 L2 后端。最简单的后端是本地文件系统："
+
+#: ../../source/mp/observability/index.rst:55
+msgid ""
+"To enable tracing instead of (or alongside) Prometheus pull, supply an "
+"OTLP endpoint — this switches metrics to **push mode** (see :ref:`mp-obs-"
+"grafana`):"
+msgstr "要启用追踪而不是（或与）Prometheus 拉取并行，请提供 OTLP 端点——这将切换指标到 **推送模式**（参见 :ref:`mp-obs-grafana`）："
+
+#: ../../source/mp/observability/index.rst:68
+msgid "Where ``/metrics`` lives"
+msgstr "``/metrics`` 的位置"
+
+#: ../../source/mp/observability/index.rst:70
+msgid ""
+"The pull-mode ``/metrics`` endpoint is served in one of two places "
+"depending on the entrypoint. Entrypoints that embed the uvicorn HTTP "
+"frontend serve it there (and disable the standalone Prometheus server); "
+"entrypoints with no HTTP frontend start the standalone server on "
+"``--prometheus-port`` instead."
+msgstr "拉模式的 ``/metrics`` 端点根据入口点的不同而服务于两个地方。嵌入 uvicorn HTTP 前端的入口点在此提供该端点（并禁用独立的 Prometheus 服务器）；没有 HTTP 前端的入口点则在 ``--prometheus-port`` 上启动独立服务器。"
+
+#: ../../source/mp/observability/index.rst:79
+msgid "Entrypoint"
+msgstr "入口点"
+
+#: ../../source/mp/observability/index.rst:80
+msgid "HTTP frontend?"
+msgstr "HTTP 前端？"
+
+#: ../../source/mp/observability/index.rst:81
+msgid "Pull-mode ``/metrics`` endpoint"
+msgstr "拉取模式 ``/metrics`` 端点"
+
+#: ../../source/mp/observability/index.rst:82
+msgid "``lmcache server``"
+msgstr "``lmcache server``"
+
+#: ../../source/mp/observability/index.rst:83
+msgid "yes"
+msgstr "是"
+
+#: ../../source/mp/observability/index.rst:84
+msgid "``--http-port`` (default ``8080``); ``--prometheus-port`` ignored"
+msgstr "``--http-port``（默认 ``8080``）；``--prometheus-port`` 被忽略"
+
+#: ../../source/mp/observability/index.rst:85
+msgid "``python -m lmcache.v1.multiprocess.server``"
+msgstr "``python -m lmcache.v1.multiprocess.server``"
+
+#: ../../source/mp/observability/index.rst:86
+#: ../../source/mp/observability/index.rst:89
+msgid "no"
+msgstr "不"
+
+#: ../../source/mp/observability/index.rst:87
+#: ../../source/mp/observability/index.rst:90
+msgid "``--prometheus-port`` (default ``9090``)"
+msgstr "``--prometheus-port`` (默认 ``9090``)"
+
+#: ../../source/mp/observability/index.rst:88
+msgid "``lmcache trace replay``"
+msgstr "``lmcache trace replay``"
+
+#: ../../source/mp/observability/index.rst:92
+msgid ""
+"In **push mode** (``--otlp-endpoint`` set) none of these serve "
+"``/metrics`` — metrics are pushed to the collector instead."
+msgstr "在 **推送模式** (``--otlp-endpoint`` 设置) 下，这些都不提供 ``/metrics`` — 指标被推送到收集器。"
+
+#: ../../source/mp/observability/index.rst:98
+msgid "Viewing Metrics in Grafana"
+msgstr "在 Grafana 中查看指标"
+
+#: ../../source/mp/observability/index.rst:100
+msgid ""
+"There are two ways to get LMCache metrics into Grafana. Pick based on "
+"whether you also want **traces**."
+msgstr "将 LMCache 指标导入 Grafana 有两种方法。根据您是否还想要 **跟踪** 进行选择。"
+
+#: ../../source/mp/observability/index.rst:107
+msgid "Path"
+msgstr "路径"
+
+#: ../../source/mp/observability/index.rst:108
+msgid "Server flags"
+msgstr "服务器标志"
+
+#: ../../source/mp/observability/index.rst:109
+msgid "What you run"
+msgstr "您运行的内容"
+
+#: ../../source/mp/observability/index.rst:110
+msgid "Gives you"
+msgstr "提供给你"
+
+#: ../../source/mp/observability/index.rst:111
+msgid "**A. Bundled stack**"
+msgstr "**A. 打包堆栈**"
+
+#: ../../source/mp/observability/index.rst:112
+msgid "``--otlp-endpoint`` (push)"
+msgstr "``--otlp-endpoint`` (推送)"
+
+#: ../../source/mp/observability/index.rst:113
+msgid "``docker compose up`` in ``examples/observability/``"
+msgstr "``docker compose up`` 在 ``examples/observability/``"
+
+#: ../../source/mp/observability/index.rst:114
+msgid "Metrics **+ traces**, Grafana with the LMCache dashboard auto-provisioned"
+msgstr "指标 **+ 跟踪**，Grafana 自动配置的 LMCache 仪表板"
+
+#: ../../source/mp/observability/index.rst:116
+msgid "**B. Pull mode**"
+msgstr "**B. 拉取模式**"
+
+#: ../../source/mp/observability/index.rst:117
+msgid "none (default)"
+msgstr "无 (默认)"
+
+#: ../../source/mp/observability/index.rst:118
+msgid "Your own Prometheus + Grafana scraping ``:8080``"
+msgstr "您自己的 Prometheus + Grafana 抓取 ``:8080``"
+
+#: ../../source/mp/observability/index.rst:119
+msgid "Metrics only, minimal moving parts, no collector"
+msgstr "仅限指标，最小的移动部件，无收集器"
+
+#: ../../source/mp/observability/index.rst:122
+msgid "Path A — bundled Prometheus + Tempo + Grafana"
+msgstr "路径 A — 打包的 Prometheus + Tempo + Grafana"
+
+#: ../../source/mp/observability/index.rst:124
+msgid ""
+"The repository ships a ready-to-run stack (OpenTelemetry Collector → "
+"Prometheus + Tempo → Grafana) under ``examples/observability/``. Grafana "
+"comes with the **LMCache dashboard and datasources pre-provisioned** and "
+"anonymous access enabled, so there is nothing to click to log in."
+msgstr "该存储库提供了一个可直接运行的堆栈（OpenTelemetry Collector → Prometheus + Tempo → Grafana），位于 ``examples/observability/`` 下。Grafana 配备了 **预配置的 LMCache 仪表板和数据源**，并启用了匿名访问，因此无需点击登录。"
+
+#: ../../source/mp/observability/index.rst:142
+msgid ""
+"In this path the server pushes to the Collector and **Prometheus scrapes "
+"the Collector**, so you do *not* scrape the server's ``:8080`` directly."
+msgstr "在这个路径中，服务器将数据推送到 Collector，**Prometheus 从 Collector 中抓取数据**，因此您*不*直接从服务器的 ``:8080`` 抓取数据。"
+
+#: ../../source/mp/observability/index.rst:146
+msgid "Path B — pull mode (metrics only, no collector)"
+msgstr "路径 B — 拉取模式（仅限指标，无收集器）"
+
+#: ../../source/mp/observability/index.rst:148
+msgid ""
+"If you only want metrics, skip the collector entirely and have Prometheus"
+" scrape the server's ``/metrics`` endpoint directly. Start the server "
+"**without** ``--otlp-endpoint`` (see Quick Start above), then:"
+msgstr "如果您只想要指标，可以完全跳过收集器，让 Prometheus 直接抓取服务器的 ``/metrics`` 端点。启动服务器时 **不** 使用 ``--otlp-endpoint``（请参见上面的快速开始），然后："
+
+#: ../../source/mp/observability/index.rst:175
+msgid "Then in Grafana (``http://localhost:3000``):"
+msgstr "然后在 Grafana (``http://localhost:3000``)："
+
+#: ../../source/mp/observability/index.rst:177
+msgid "**Add a datasource** → Prometheus → URL ``http://localhost:9090`` → Save."
+msgstr "**添加数据源** → Prometheus → URL ``http://localhost:9090`` → 保存。"
+
+#: ../../source/mp/observability/index.rst:178
+msgid ""
+"**Import the dashboard**: Dashboards → New → Import → upload "
+"``examples/observability/grafana/provisioning/dashboards/lmcache.json`` "
+"and select the Prometheus datasource. This is the same dashboard the "
+"bundled stack provisions (cache hit rate, L1/L2 cache ops, L1↔L2 "
+"throughput, eviction loop, EventBus health, and more)."
+msgstr "**导入仪表板**：仪表板 → 新建 → 导入 → 上传 ``examples/observability/grafana/provisioning/dashboards/lmcache.json`` 并选择 Prometheus 数据源。这是捆绑堆栈提供的相同仪表板（缓存命中率、L1/L2 缓存操作、L1↔L2 吞吐量、逐出循环、EventBus 健康状况等）。"
+
+#: ../../source/mp/observability/index.rst:184
+msgid "Verify the pipeline end to end:"
+msgstr "验证整个管道："
+
+#: ../../source/mp/observability/index.rst:196
+msgid "See :doc:`metrics` for the full metric catalog and more PromQL examples."
+msgstr "请参阅 :doc:`metrics` 以获取完整的指标目录和更多 PromQL 示例。"
+
+#: ../../source/mp/observability/index.rst:200
+msgid ""
+"``--network host`` (used above) is the simplest option on Linux. On "
+"Docker Desktop (macOS/Windows), drop ``--network host``, publish ports "
+"with ``-p 9090:9090`` / ``-p 3000:3000``, and set the scrape target to "
+"``host.docker.internal:8080`` and the Grafana datasource URL to "
+"``http://host.docker.internal:9090``."
+msgstr "``--network host``（如上所述）是在 Linux 上最简单的选项。在 Docker Desktop（macOS/Windows）上，去掉 ``--network host``，使用 ``-p 9090:9090`` / ``-p 3000:3000`` 发布端口，并将抓取目标设置为 ``host.docker.internal:8080``，Grafana 数据源 URL 设置为 ``http://host.docker.internal:9090``。"
+
+#: ../../source/mp/observability/index.rst:207
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/mp/observability/index.rst:213
+msgid "Argument"
+msgstr "参数"
+
+#: ../../source/mp/observability/index.rst:214
+#: ../../source/mp/observability/index.rst:271
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/observability/index.rst:215
+#: ../../source/mp/observability/index.rst:272
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/observability/index.rst:216
+msgid "``--disable-observability``"
+msgstr "``--disable-observability``"
+
+#: ../../source/mp/observability/index.rst:217
+#: ../../source/mp/observability/index.rst:221
+#: ../../source/mp/observability/index.rst:224
+#: ../../source/mp/observability/index.rst:227
+msgid "off"
+msgstr "关闭"
+
+#: ../../source/mp/observability/index.rst:218
+msgid ""
+"Master switch: disable the EventBus entirely (no metrics, logging, or "
+"tracing subscribers are registered)."
+msgstr "主开关：完全禁用 EventBus（不注册任何指标、日志记录或追踪订阅者）。"
+
+#: ../../source/mp/observability/index.rst:220
+msgid "``--disable-metrics``"
+msgstr "``--disable-metrics``"
+
+#: ../../source/mp/observability/index.rst:222
+msgid "Skip metrics subscribers (Prometheus endpoint is not started)."
+msgstr "跳过指标订阅者（Prometheus 端点未启动）。"
+
+#: ../../source/mp/observability/index.rst:223
+msgid "``--disable-logging``"
+msgstr "``--disable-logging``"
+
+#: ../../source/mp/observability/index.rst:225
+msgid "Skip logging subscribers."
+msgstr "跳过日志订阅者。"
+
+#: ../../source/mp/observability/index.rst:226
+msgid "``--enable-tracing``"
+msgstr "``--enable-tracing``"
+
+#: ../../source/mp/observability/index.rst:228
+msgid "Register tracing subscribers. Requires ``--otlp-endpoint``."
+msgstr "注册追踪订阅者。需要 ``--otlp-endpoint``\\ 。"
+
+#: ../../source/mp/observability/index.rst:229
+msgid "``--event-bus-queue-size``"
+msgstr "``--event-bus-queue-size``"
+
+#: ../../source/mp/observability/index.rst:230
+msgid "``10000``"
+msgstr "``10000``"
+
+#: ../../source/mp/observability/index.rst:231
+msgid "Maximum events in the EventBus queue before tail-drop."
+msgstr "事件总线队列中最大事件数，超过后将进行尾部丢弃。"
+
+#: ../../source/mp/observability/index.rst:232
+msgid "``--otlp-endpoint``"
+msgstr "``--otlp-endpoint``"
+
+#: ../../source/mp/observability/index.rst:233
+#: ../../source/mp/observability/index.rst:253
+#: ../../source/mp/observability/index.rst:259
+msgid "*(none)*"
+msgstr "(无)"
+
+#: ../../source/mp/observability/index.rst:234
+msgid ""
+"OTLP gRPC endpoint (e.g. ``http://localhost:4317``). Used for exporting "
+"metrics (push mode) and traces."
+msgstr "OTLP gRPC 端点（例如 ``http://localhost:4317``\\ ）。用于导出指标（推送模式）和追踪数据。"
+
+#: ../../source/mp/observability/index.rst:236
+msgid "``--prometheus-port``"
+msgstr "``--prometheus-port``"
+
+#: ../../source/mp/observability/index.rst:237
+msgid "``9090``"
+msgstr "``9090``"
+
+#: ../../source/mp/observability/index.rst:238
+msgid ""
+"Port of the standalone Prometheus ``/metrics`` server. Started only by "
+"frontend-less entrypoints (``python -m lmcache.v1.multiprocess.server``, "
+"``lmcache trace replay``). **Ignored by** ``lmcache server`` — there the "
+"HTTP frontend serves ``/metrics`` on ``--http-port`` instead, so the "
+"standalone server is disabled. See :ref:`mp-obs-metrics-endpoint`."
+msgstr "独立 Prometheus ``/metrics`` 服务器的端口。仅由无前端的入口点启动（``python -m lmcache.v1.multiprocess.server``，``lmcache trace replay``）。**在** ``lmcache server`` 中被忽略——在这里，HTTP 前端在 ``--http-port`` 上提供 ``/metrics``，因此独立服务器被禁用。请参见 :ref:`mp-obs-metrics-endpoint`。"
+
+#: ../../source/mp/observability/index.rst:243
+msgid "``--http-port``"
+msgstr "``--http-port``"
+
+#: ../../source/mp/observability/index.rst:244
+msgid "``8080``"
+msgstr "``8080``"
+
+#: ../../source/mp/observability/index.rst:245
+msgid ""
+"Port of the HTTP frontend, which serves the Prometheus ``/metrics`` "
+"endpoint in pull mode (when ``--otlp-endpoint`` is unset) for ``lmcache "
+"server``."
+msgstr "HTTP 前端的端口，用于在拉取模式下（当 ``--otlp-endpoint`` 未设置时）为 ``lmcache server`` 提供 Prometheus ``/metrics`` 端点。"
+
+#: ../../source/mp/observability/index.rst:248
+msgid "``--metrics-sample-rate``"
+msgstr "``--metrics-sample-rate``"
+
+#: ../../source/mp/observability/index.rst:249
+msgid "``0.01``"
+msgstr "``0.01``"
+
+#: ../../source/mp/observability/index.rst:250
+msgid ""
+"Fraction of chunks/blocks to track for lifecycle histograms (0, 1.0]. "
+"Counters always count all events. Default is 1%."
+msgstr "用于生命周期直方图的 chunk/block 采样比例 (0, 1.0]。计数器始终统计所有事件。默认值为 1%。"
+
+#: ../../source/mp/observability/index.rst:252
+msgid "``--trace-level``"
+msgstr "``--trace-level``"
+
+#: ../../source/mp/observability/index.rst:254
+msgid ""
+"Enable trace recording at the given level. Currently only ``storage`` is "
+"supported (records ``StorageManager`` public-API calls for offline "
+"replay). When unset, trace recording is off. See :ref:`trace-recording` "
+"for details."
+msgstr ""
+"在指定级别启用追踪录制。目前仅支持 ``storage``\\ （记录 ``StorageManager`` 公共 API "
+"调用以便离线回放）。未设置时，追踪录制关闭。详情请参见 :ref:`trace-recording`。"
+
+#: ../../source/mp/observability/index.rst:258
+msgid "``--trace-output``"
+msgstr "``--trace-output``"
+
+#: ../../source/mp/observability/index.rst:260
+msgid ""
+"Path to write the trace file. If omitted while ``--trace-level`` is set, "
+"a timestamped file under ``$TMPDIR`` is minted (``lmcache-"
+"trace-<pid>-<UTC>.lct``) and its path is logged at INFO."
+msgstr ""
+"追踪文件的写入路径。若设置了 ``--trace-level`` 但省略此项，将在 ``$TMPDIR`` 下自动生成一个带时间戳的文件（\\ "
+"``lmcache-trace-<pid>-<UTC>.lct``\\ ），并以 INFO 级别记录其路径。"
+
+#: ../../source/mp/observability/index.rst:264
+msgid "**Environment variables:**"
+msgstr "**环境变量：**"
+
+#: ../../source/mp/observability/index.rst:270
+msgid "Variable"
+msgstr "变量"
+
+#: ../../source/mp/observability/index.rst:273
+msgid "``LMCACHE_LOG_LEVEL``"
+msgstr "``LMCACHE_LOG_LEVEL``"
+
+#: ../../source/mp/observability/index.rst:274
+msgid "``INFO``"
+msgstr "``INFO``"
+
+#: ../../source/mp/observability/index.rst:275
+msgid ""
+"Controls the log level for all LMCache loggers. Valid values: ``DEBUG``, "
+"``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``."
+msgstr ""
+"控制所有 LMCache 日志记录器的日志级别。有效值：\\ ``DEBUG``\\ 、\\ ``INFO``\\ 、\\ "
+"``WARNING``\\ 、\\ ``ERROR``\\ 、\\ ``CRITICAL``\\ 。"
+
+#~ msgid "To enable tracing, supply an OTLP endpoint:"
+#~ msgstr "要启用追踪，请提供 OTLP 端点："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/logs.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/logs.po
new file mode 100644
index 0000000..0cb8326
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/logs.po
@@ -0,0 +1,83 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/observability/logs.rst:2
+msgid "Logging"
+msgstr "日志记录"
+
+#: ../../source/mp/observability/logs.rst:4
+msgid ""
+"Logging subscribers emit debug-level messages for store, retrieve, "
+"lookup, L1, and StorageManager events via Python's standard ``logging`` "
+"module."
+msgstr "日志订阅者通过 Python 的标准 ``logging`` 模块为存储、检索、查找、L1 和 StorageManager 事件发出调试级别的消息。"
+
+#: ../../source/mp/observability/logs.rst:7
+msgid ""
+"When OpenTelemetry is installed, ``init_logger`` automatically attaches "
+"an OTel ``LoggingHandler`` so that log records are forwarded to any "
+"configured OTel ``LoggerProvider``. The handler respects the "
+"``LMCACHE_LOG_LEVEL`` environment variable."
+msgstr "当安装 OpenTelemetry 时，``init_logger`` 会自动附加一个 OTel ``LoggingHandler``，以便将日志记录转发到任何配置的 OTel ``LoggerProvider``。该处理程序遵循 ``LMCACHE_LOG_LEVEL`` 环境变量。"
+
+#: ../../source/mp/observability/logs.rst:16
+msgid "Key log messages:"
+msgstr "关键日志消息："
+
+#: ../../source/mp/observability/logs.rst:22
+msgid "Level"
+msgstr "级别"
+
+#: ../../source/mp/observability/logs.rst:23
+msgid "Message"
+msgstr "消息"
+
+#: ../../source/mp/observability/logs.rst:24
+#: ../../source/mp/observability/logs.rst:26
+#: ../../source/mp/observability/logs.rst:28
+msgid "INFO"
+msgstr "INFO"
+
+#: ../../source/mp/observability/logs.rst:25
+msgid "``Stored N tokens in X seconds``"
+msgstr "``Stored N tokens in X seconds``"
+
+#: ../../source/mp/observability/logs.rst:27
+msgid "``Retrieved N tokens in X seconds``"
+msgstr "``Retrieved N tokens in X seconds``"
+
+#: ../../source/mp/observability/logs.rst:29
+msgid "``Prefetch request completed (L1+L2): N/M prefix hits``"
+msgstr "``Prefetch request completed (L1+L2): N/M prefix hits``"
+
+#: ../../source/mp/observability/logs.rst:30
+#: ../../source/mp/observability/logs.rst:32
+msgid "DEBUG"
+msgstr "DEBUG"
+
+#: ../../source/mp/observability/logs.rst:31
+msgid "``MP store start: session=... device=...``"
+msgstr "``MP store start: session=... device=...``"
+
+#: ../../source/mp/observability/logs.rst:33
+msgid "``MP retrieve end: session=... retrieved_count=...``"
+msgstr "``MP retrieve end: session=... retrieved_count=...``"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/metrics.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/metrics.po
new file mode 100644
index 0000000..dbd41e5
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/metrics.po
@@ -0,0 +1,1124 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/observability/metrics.rst:2
+msgid "Metrics"
+msgstr "指标"
+
+#: ../../source/mp/observability/metrics.rst:4
+msgid ""
+"Metrics are collected via OpenTelemetry and made available to Prometheus "
+"in one of two ways, depending on whether ``--otlp-endpoint`` is set:"
+msgstr "指标通过 OpenTelemetry 收集，并根据是否设置了 ``--otlp-endpoint`` 以两种方式之一提供给 Prometheus："
+
+#: ../../source/mp/observability/metrics.rst:7
+msgid ""
+"**Pull mode (default, no collector).** When ``--otlp-endpoint`` is *not* "
+"set, the server publishes a Prometheus ``/metrics`` endpoint that "
+"Prometheus scrapes directly."
+msgstr "**拉取模式（默认，无收集器）。** 当 ``--otlp-endpoint`` *未* 设置时，服务器会发布一个 Prometheus ``/metrics`` 端点，Prometheus 直接抓取该端点。"
+
+#: ../../source/mp/observability/metrics.rst:13
+msgid ""
+"For ``lmcache server``, ``/metrics`` is served by the **HTTP frontend** "
+"on ``--http-port`` (default **8080**), e.g. "
+"``http://<host>:8080/metrics`` — **not** on ``--prometheus-port``. "
+"``--prometheus-port`` is *ignored* by ``lmcache server``: the standalone "
+"Prometheus HTTP server is disabled because the HTTP frontend already "
+"serves ``/metrics``. The frontend-less entrypoints (``python -m "
+"lmcache.v1.multiprocess.server`` and ``lmcache trace replay``) have no "
+"HTTP frontend, so *they* serve ``/metrics`` on ``--prometheus-port`` "
+"(default 9090). See :ref:`mp-obs-metrics-endpoint` for the full "
+"breakdown. Either way, ``/metrics`` is empty until the first "
+"store/retrieve — drive some traffic before you go looking."
+msgstr "对于 ``lmcache server``，``/metrics`` 由 **HTTP 前端** 在 ``--http-port``（默认 **8080**）上提供，例如 ``http://<host>:8080/metrics`` — **不** 在 ``--prometheus-port`` 上。``--prometheus-port`` 被 ``lmcache server`` *忽略*：独立的 Prometheus HTTP 服务器被禁用，因为 HTTP 前端已经提供了 ``/metrics``。没有前端的入口点（``python -m lmcache.v1.multiprocess.server`` 和 ``lmcache trace replay``）没有 HTTP 前端，因此 *它们* 在 ``--prometheus-port``（默认 9090）上提供 ``/metrics``。有关详细信息，请参见 :ref:`mp-obs-metrics-endpoint`。无论如何，``/metrics`` 在第一次存储/检索之前是空的 — 在您查找之前先驱动一些流量。"
+
+#: ../../source/mp/observability/metrics.rst:26
+msgid ""
+"**Push mode (OTLP).** When ``--otlp-endpoint`` is set, metrics are pushed"
+" to an OpenTelemetry Collector, which re-exposes them for Prometheus to "
+"scrape. See :doc:`index` for the bundled Collector + Prometheus + Grafana"
+" stack."
+msgstr "**推送模式 (OTLP)。** 当设置 ``--otlp-endpoint`` 时，指标会被推送到 OpenTelemetry Collector，后者会重新暴露这些指标供 Prometheus 抓取。有关捆绑的 Collector + Prometheus + Grafana 堆栈，请参见 :doc:`index`。"
+
+#: ../../source/mp/observability/metrics.rst:30
+msgid ""
+"All metrics use the ``lmcache_mp.`` prefix (multiprocess). On Prometheus,"
+" dots are converted to underscores and counters get a ``_total`` suffix "
+"(e.g. ``lmcache_mp_l1_read_chunks_total``); histograms gain a unit suffix"
+" plus ``_sum`` / ``_count`` / ``_bucket`` (e.g. "
+"``lmcache_mp_l2_store_throughput_GB_per_second_sum``)."
+msgstr "所有指标使用 ``lmcache_mp.`` 前缀（多进程）。在 Prometheus 中，点被转换为下划线，计数器带有 ``_total`` 后缀（例如 ``lmcache_mp_l1_read_chunks_total``）；直方图增加单位后缀以及 ``_sum`` / ``_count`` / ``_bucket``（例如 ``lmcache_mp_l2_store_throughput_GB_per_second_sum``）。"
+
+#: ../../source/mp/observability/metrics.rst:39
+msgid "Global Resource Attributes"
+msgstr "全局资源属性"
+
+#: ../../source/mp/observability/metrics.rst:41
+msgid ""
+"Every metric and span exported by an MP server carries Resource-level "
+"attributes built at startup. These identify the process producing the "
+"telemetry and are orthogonal to per-metric attributes such as "
+"``cache_salt``."
+msgstr ""
+"每个由 MP 服务器导出的指标和跨度都携带在启动时构建的资源级属性。这些属性标识生成遥测的进程，并与每个指标的属性（如 "
+"``cache_salt``\\ ）正交。"
+
+#: ../../source/mp/observability/metrics.rst:50
+msgid "Attribute"
+msgstr "属性"
+
+#: ../../source/mp/observability/metrics.rst:51
+msgid "CLI flag / config"
+msgstr "命令行标志 / 配置"
+
+#: ../../source/mp/observability/metrics.rst:52
+msgid "Default when unset"
+msgstr "未设置时的默认值"
+
+#: ../../source/mp/observability/metrics.rst:53
+msgid "``service.instance.id``"
+msgstr "``service.instance.id``"
+
+#: ../../source/mp/observability/metrics.rst:54
+msgid "``--instance-id`` / ``MPServerConfig.instance_id``"
+msgstr "``--instance-id`` / ``MPServerConfig.instance_id``"
+
+#: ../../source/mp/observability/metrics.rst:55
+msgid "Random UUID v4 minted at startup."
+msgstr "在启动时生成的随机 UUID v4。"
+
+#: ../../source/mp/observability/metrics.rst:57
+msgid ""
+"Resource attributes attach to the ``MeterProvider`` / ``TracerProvider`` "
+"and propagate to every exported datapoint via OTLP. On Prometheus, SDK "
+"resource attributes surface on the ``target_info`` series rather than on "
+"each time-series — this is standard OTel behavior."
+msgstr ""
+"资源属性附加到 ``MeterProvider`` / ``TracerProvider`` 并通过 OTLP 传播到每个导出的数据点。在 "
+"Prometheus 中，SDK 资源属性出现在 ``target_info`` 系列上，而不是每个时间序列上——这是标准的 OTel 行为。"
+
+#: ../../source/mp/observability/metrics.rst:63
+msgid "L1 Metrics"
+msgstr "L1 指标"
+
+#: ../../source/mp/observability/metrics.rst:69
+#: ../../source/mp/observability/metrics.rst:107
+#: ../../source/mp/observability/metrics.rst:142
+#: ../../source/mp/observability/metrics.rst:164
+#: ../../source/mp/observability/metrics.rst:225
+#: ../../source/mp/observability/metrics.rst:271
+#: ../../source/mp/observability/metrics.rst:323
+#: ../../source/mp/observability/metrics.rst:357
+#: ../../source/mp/observability/metrics.rst:394
+#: ../../source/mp/observability/metrics.rst:439
+#: ../../source/mp/observability/metrics.rst:470
+#: ../../source/mp/observability/metrics.rst:540
+msgid "Metric"
+msgstr "指标"
+
+#: ../../source/mp/observability/metrics.rst:70
+#: ../../source/mp/observability/metrics.rst:108
+#: ../../source/mp/observability/metrics.rst:143
+#: ../../source/mp/observability/metrics.rst:165
+#: ../../source/mp/observability/metrics.rst:226
+#: ../../source/mp/observability/metrics.rst:272
+#: ../../source/mp/observability/metrics.rst:324
+#: ../../source/mp/observability/metrics.rst:358
+#: ../../source/mp/observability/metrics.rst:395
+#: ../../source/mp/observability/metrics.rst:440
+#: ../../source/mp/observability/metrics.rst:471
+#: ../../source/mp/observability/metrics.rst:541
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/mp/observability/metrics.rst:71
+#: ../../source/mp/observability/metrics.rst:109
+#: ../../source/mp/observability/metrics.rst:144
+#: ../../source/mp/observability/metrics.rst:166
+#: ../../source/mp/observability/metrics.rst:227
+#: ../../source/mp/observability/metrics.rst:273
+#: ../../source/mp/observability/metrics.rst:325
+#: ../../source/mp/observability/metrics.rst:359
+#: ../../source/mp/observability/metrics.rst:396
+#: ../../source/mp/observability/metrics.rst:441
+#: ../../source/mp/observability/metrics.rst:472
+#: ../../source/mp/observability/metrics.rst:542
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/observability/metrics.rst:72
+msgid "``lmcache_mp.l1_read``"
+msgstr "``lmcache_mp.l1_read``"
+
+#: ../../source/mp/observability/metrics.rst:73
+#: ../../source/mp/observability/metrics.rst:76
+#: ../../source/mp/observability/metrics.rst:79
+#: ../../source/mp/observability/metrics.rst:171
+#: ../../source/mp/observability/metrics.rst:177
+#: ../../source/mp/observability/metrics.rst:183
+#: ../../source/mp/observability/metrics.rst:193
+#: ../../source/mp/observability/metrics.rst:196
+#: ../../source/mp/observability/metrics.rst:202
+msgid "Counter (attr: ``cache_salt``)"
+msgstr "计数器（属性：\\ ``cache_salt``\\ ）"
+
+#: ../../source/mp/observability/metrics.rst:74
+msgid "Number of chunks read from L1, grouped by tenant."
+msgstr "按租户分组的从 L1 读取的块数。"
+
+#: ../../source/mp/observability/metrics.rst:75
+msgid "``lmcache_mp.l1_write``"
+msgstr "``lmcache_mp.l1_write``"
+
+#: ../../source/mp/observability/metrics.rst:77
+msgid "Number of chunks written to L1, grouped by tenant."
+msgstr "按租户分组写入 L1 的块数。"
+
+#: ../../source/mp/observability/metrics.rst:78
+msgid "``lmcache_mp.l1_evicted``"
+msgstr "``lmcache_mp.l1_evicted``"
+
+#: ../../source/mp/observability/metrics.rst:80
+msgid "Number of chunks evicted by the EvictionController, grouped by tenant."
+msgstr "按租户分组的被 EvictionController 逐出的块数。"
+
+#: ../../source/mp/observability/metrics.rst:82
+msgid "``lmcache_mp.l1_eviction_loop_ticks``"
+msgstr "``lmcache_mp.l1_eviction_loop_ticks``"
+
+#: ../../source/mp/observability/metrics.rst:83
+#: ../../source/mp/observability/metrics.rst:87
+#: ../../source/mp/observability/metrics.rst:168
+#: ../../source/mp/observability/metrics.rst:180
+#: ../../source/mp/observability/metrics.rst:187
+#: ../../source/mp/observability/metrics.rst:190
+#: ../../source/mp/observability/metrics.rst:229
+#: ../../source/mp/observability/metrics.rst:235
+#: ../../source/mp/observability/metrics.rst:244
+msgid "Counter"
+msgstr "计数器"
+
+#: ../../source/mp/observability/metrics.rst:84
+msgid ""
+"L1 eviction-loop iterations (every cycle, regardless of whether the "
+"watermark was crossed). Driven by ``L1_EVICTION_LOOP_TICK``."
+msgstr "L1 逐出循环迭代（每个周期，无论水位线是否被跨越）。由 ``L1_EVICTION_LOOP_TICK`` 驱动。"
+
+#: ../../source/mp/observability/metrics.rst:86
+msgid "``lmcache_mp.l1_eviction_loop_triggered``"
+msgstr "``lmcache_mp.l1_eviction_loop_triggered``"
+
+#: ../../source/mp/observability/metrics.rst:88
+msgid ""
+"L1 eviction-loop iterations where ``usage >= watermark`` and the eviction"
+" policy actually ran. The two counters distinguish \"loop is alive\" from"
+" \"eviction fired\" — important when debugging short-lived benchmarks "
+"that complete faster than the 1 Hz polling cycle."
+msgstr ""
+"L1 逐出循环迭代，其中 ``usage >= watermark`` "
+"且逐出策略实际运行。这两个计数器区分“循环仍在运行”和“逐出已触发”——在调试完成速度快于 1 Hz 轮询周期的短期基准测试时，这一点非常重要。"
+
+#: ../../source/mp/observability/metrics.rst:95
+msgid "L1 Chunk Lifecycle Histograms"
+msgstr "L1 块生命周期直方图"
+
+#: ../../source/mp/observability/metrics.rst:97
+msgid ""
+"Sampled (default 1%) chunk-level lifecycle tracking via "
+"``L1LifecycleSubscriber``. Only sampled chunks contribute to histograms; "
+"counters above always count all events. Sampling is deterministic (hash-"
+"based), so the same key always gets the same decision with zero memory "
+"overhead."
+msgstr ""
+"通过 ``L1LifecycleSubscriber`` 进行采样的（默认 "
+"1%）块级生命周期跟踪。只有采样的块会对直方图产生贡献；上述计数器始终计算所有事件。采样是确定性的（基于哈希），因此相同的键总是会得到相同的决策，且没有内存开销。"
+
+#: ../../source/mp/observability/metrics.rst:110
+msgid "``lmcache_mp.l1_chunk_lifetime``"
+msgstr "``lmcache_mp.l1_chunk_lifetime``"
+
+#: ../../source/mp/observability/metrics.rst:111
+#: ../../source/mp/observability/metrics.rst:114
+#: ../../source/mp/observability/metrics.rst:117
+#: ../../source/mp/observability/metrics.rst:120
+#: ../../source/mp/observability/metrics.rst:327
+#: ../../source/mp/observability/metrics.rst:330
+#: ../../source/mp/observability/metrics.rst:333
+#: ../../source/mp/observability/metrics.rst:361
+#: ../../source/mp/observability/metrics.rst:364
+#: ../../source/mp/observability/metrics.rst:398
+#: ../../source/mp/observability/metrics.rst:401
+msgid "Histogram"
+msgstr "直方图"
+
+#: ../../source/mp/observability/metrics.rst:112
+msgid "Time from allocation to eviction per sampled chunk."
+msgstr "每个采样块从分配到逐出的时间。"
+
+#: ../../source/mp/observability/metrics.rst:113
+msgid "``lmcache_mp.l1_chunk_idle_before_evict``"
+msgstr "``lmcache_mp.l1_chunk_idle_before_evict``"
+
+#: ../../source/mp/observability/metrics.rst:115
+msgid "Time from last access to eviction per sampled chunk."
+msgstr "每个采样块从最后访问到逐出的时间。"
+
+#: ../../source/mp/observability/metrics.rst:116
+msgid "``lmcache_mp.l1_chunk_reuse_gap``"
+msgstr "``lmcache_mp.l1_chunk_reuse_gap``"
+
+#: ../../source/mp/observability/metrics.rst:118
+msgid "Time gap between consecutive touches (read or write) of the same chunk."
+msgstr "同一块的连续访问（读取或写入）之间的时间间隔。"
+
+#: ../../source/mp/observability/metrics.rst:119
+msgid "``lmcache_mp.l1_chunk_evict_reuse_gap``"
+msgstr "``lmcache_mp.l1_chunk_evict_reuse_gap``"
+
+#: ../../source/mp/observability/metrics.rst:121
+msgid "Time from eviction to next reuse (capped at 300 s)."
+msgstr "逐出到下次重用的时间（上限为 300 秒）。"
+
+#: ../../source/mp/observability/metrics.rst:124
+msgid "StorageManager Real-Reuse Metrics"
+msgstr "存储管理器真实重用指标"
+
+#: ../../source/mp/observability/metrics.rst:126
+msgid ""
+"Workload-level reuse histograms emitted by ``SMLifecycleSubscriber``, "
+"driven by caller-facing StorageManager events "
+"(``SM_READ_PREFETCHED_FINISHED``, ``SM_WRITE_FINISHED``).  Internal read-"
+"lock releases by the store/prefetch controllers are excluded so the "
+"signal reflects user-driven access only."
+msgstr ""
+"由 ``SMLifecycleSubscriber`` 发出的工作负载级重用直方图，由面向调用者的 StorageManager 事件（\\ "
+"``SM_READ_PREFETCHED_FINISHED``\\ ，\\ ``SM_WRITE_FINISHED``\\ "
+"）驱动。存储/预取控制器的内部读取锁释放被排除在外，因此信号仅反映用户驱动的访问。"
+
+#: ../../source/mp/observability/metrics.rst:132
+msgid ""
+"Both histograms are tagged with ``cache_salt`` for per-tenant isolation."
+"  The per-salt access counter advances on every read and write of every "
+"chunk (regardless of sampling) so the chunks-gap reflects true storage "
+"volume; the histogram itself records gaps only for chunks that pass the "
+"(deterministic, hash-based) sampling gate."
+msgstr ""
+"这两个直方图都带有 ``cache_salt`` 标签，以实现租户隔离。每个块的每次读取和写入都会使对应 ``cache_salt`` "
+"的访问计数器递增（无论是否采样），因此块间隔反映了真实的存储量；直方图本身仅记录通过（确定性、基于哈希的）采样门控的块的间隔。"
+
+#: ../../source/mp/observability/metrics.rst:145
+msgid "``lmcache_mp.real_reuse_gap``"
+msgstr "``lmcache_mp.real_reuse_gap``"
+
+#: ../../source/mp/observability/metrics.rst:146
+#: ../../source/mp/observability/metrics.rst:151
+msgid "Histogram (tag: ``cache_salt``)"
+msgstr "直方图（标签：\\ ``cache_salt``\\ ）"
+
+#: ../../source/mp/observability/metrics.rst:147
+msgid ""
+"Time gap between a chunk's last access (read or write) and its next read."
+"  Captures storage cost — how long a stored chunk sat between accesses.  "
+"Emitted only on read events."
+msgstr "块的最后一次访问（读取或写入）与下一次读取之间的时间间隔。捕获存储成本——一个存储块在访问之间静止了多久。仅在读取事件中发出。"
+
+#: ../../source/mp/observability/metrics.rst:150
+msgid "``lmcache_mp.real_reuse_gap_objects``"
+msgstr "``lmcache_mp.real_reuse_gap_objects``"
+
+#: ../../source/mp/observability/metrics.rst:152
+msgid ""
+"Per-``cache_salt`` access-counter gap between two reads of the same "
+"chunk.  Captures storage volume — how many chunk-accesses occurred while "
+"this chunk waited for its next read.  Emitted on read events for sampled "
+"chunks."
+msgstr ""
+"同一块两次读取之间每 ``cache_salt`` "
+"访问计数器的增量。反映存储量——在该块等待下次读取期间发生了多少次块访问。仅对采样块的读取事件发出。"
+
+#: ../../source/mp/observability/metrics.rst:158
+msgid "L2 Metrics"
+msgstr "L2 指标"
+
+#: ../../source/mp/observability/metrics.rst:167
+msgid "``lmcache_mp.l2_store_submitted``"
+msgstr "``lmcache_mp.l2_store_submitted``"
+
+#: ../../source/mp/observability/metrics.rst:169
+msgid "Number of L2 store requests submitted."
+msgstr "提交的 L2 存储请求数量。"
+
+#: ../../source/mp/observability/metrics.rst:170
+msgid "``lmcache_mp.l2_store_submitted_objects``"
+msgstr "``lmcache_mp.l2_store_submitted_objects``"
+
+#: ../../source/mp/observability/metrics.rst:172
+msgid "Number of chunks submitted for L2 store, grouped by tenant."
+msgstr "按租户分组的提交到 L2 存储的块数量。"
+
+#: ../../source/mp/observability/metrics.rst:173
+msgid "``lmcache_mp.l2_store_completed``"
+msgstr "``lmcache_mp.l2_store_completed``"
+
+#: ../../source/mp/observability/metrics.rst:174
+#: ../../source/mp/observability/metrics.rst:199
+msgid "Counter (attr: ``l2_name``)"
+msgstr "计数器（属性：\\ ``l2_name``\\ ）"
+
+#: ../../source/mp/observability/metrics.rst:175
+msgid "Number of L2 store requests completed, labeled by adapter type."
+msgstr "按适配器类型标记的完成的 L2 存储请求数量。"
+
+#: ../../source/mp/observability/metrics.rst:176
+msgid "``lmcache_mp.l2_store_completed_objects``"
+msgstr "``lmcache_mp.l2_store_completed_objects``"
+
+#: ../../source/mp/observability/metrics.rst:178
+msgid "Number of chunks successfully stored to L2, grouped by tenant."
+msgstr "按租户分组成功存储到 L2 的块数。"
+
+#: ../../source/mp/observability/metrics.rst:179
+msgid "``lmcache_mp.l2_prefetch_lookup``"
+msgstr "``lmcache_mp.l2_prefetch_lookup``"
+
+#: ../../source/mp/observability/metrics.rst:181
+msgid "Number of L2 prefetch lookup requests."
+msgstr "L2 预取查找请求的数量。"
+
+#: ../../source/mp/observability/metrics.rst:182
+msgid "``lmcache_mp.l2_prefetch_lookup_objects``"
+msgstr "``lmcache_mp.l2_prefetch_lookup_objects``"
+
+#: ../../source/mp/observability/metrics.rst:184
+msgid "Number of chunks submitted for L2 prefetch lookup, grouped by tenant."
+msgstr "按租户分组的提交用于 L2 预取查找的块数量。"
+
+#: ../../source/mp/observability/metrics.rst:186
+msgid "``lmcache_mp.l2_prefetch_hit``"
+msgstr "``lmcache_mp.l2_prefetch_hit``"
+
+#: ../../source/mp/observability/metrics.rst:188
+msgid "Number of prefix chunks found in L2 lookup."
+msgstr "在 L2 查找中找到的前缀块数量。"
+
+#: ../../source/mp/observability/metrics.rst:189
+msgid "``lmcache_mp.l2_prefetch_load_submitted``"
+msgstr "``lmcache_mp.l2_prefetch_load_submitted``"
+
+#: ../../source/mp/observability/metrics.rst:191
+msgid "Number of L2 prefetch load requests submitted."
+msgstr "提交的 L2 预取加载请求数量。"
+
+#: ../../source/mp/observability/metrics.rst:192
+msgid "``lmcache_mp.l2_prefetch_load_submitted_objects``"
+msgstr "``lmcache_mp.l2_prefetch_load_submitted_objects``"
+
+#: ../../source/mp/observability/metrics.rst:194
+msgid "Number of chunks submitted for L2 load, grouped by tenant."
+msgstr "按租户分组的提交用于 L2 加载的块数量。"
+
+#: ../../source/mp/observability/metrics.rst:195
+msgid "``lmcache_mp.l2_prefetch_load_completed``"
+msgstr "``lmcache_mp.l2_prefetch_load_completed``"
+
+#: ../../source/mp/observability/metrics.rst:197
+msgid "Number of chunks successfully loaded from L2, grouped by tenant."
+msgstr "按租户分组成功从 L2 加载的块数。"
+
+#: ../../source/mp/observability/metrics.rst:198
+msgid "``lmcache_mp.l2_load_completed``"
+msgstr "``lmcache_mp.l2_load_completed``"
+
+#: ../../source/mp/observability/metrics.rst:200
+msgid "Number of per-adapter L2 load requests completed, labeled by adapter type."
+msgstr "按适配器类型标记的每个适配器完成的 L2 加载请求数量。"
+
+#: ../../source/mp/observability/metrics.rst:201
+msgid "``lmcache_mp.l2_evicted_objects``"
+msgstr "``lmcache_mp.l2_evicted_objects``"
+
+#: ../../source/mp/observability/metrics.rst:203
+msgid "Number of chunks evicted from L2, grouped by tenant."
+msgstr "按租户分组的从 L2 逐出的块数量。"
+
+#: ../../source/mp/observability/metrics.rst:205
+#, python-brace-format
+msgid ""
+"The ``l2_name``-labeled counters (``l2_store_completed`` and "
+"``l2_load_completed``) exist so dashboards can compute per-backend IOPS "
+"on demand via "
+"``rate(lmcache_mp_l2_store_completed_requests_total{l2_name=\"...\"}[1m])``"
+" (and the equivalent for loads).  No separate ``*_iops`` metric is "
+"exported; keeping the raw counter lets dashboard users pick their own "
+"window."
+msgstr ""
+"``l2_name`` 标签的计数器 (``l2_store_completed`` 和 ``l2_load_completed``) "
+"存在的目的是为了让仪表板能够通过 "
+"``rate(lmcache_mp_l2_store_completed_requests_total{l2_name=\\\"...\\\"}[1m])``"
+" 按需计算每个后端的 IOPS（加载的等效项也是如此）。没有单独导出 ``*_iops`` "
+"指标；保留原始计数器让仪表板用户可以选择自己的时间窗口。"
+
+#: ../../source/mp/observability/metrics.rst:212
+msgid "Failure & Health Counters"
+msgstr "失败与健康计数器"
+
+#: ../../source/mp/observability/metrics.rst:214
+msgid ""
+"Health-monitoring counters emitted on the dedicated ``lmcache_mp.health``"
+" OTel meter. Driven by the ``L1FailureMetricsSubscriber`` and "
+"``L2FailureMetricsSubscriber``, which are registered automatically when "
+"metrics are enabled. All three counters carry ``model_name`` (extracted "
+"from each ``ObjectKey``) so operators can slice per-model on the "
+"Prometheus ``/metrics`` endpoint."
+msgstr ""
+"在专用的 ``lmcache_mp.health`` OTel 计量器上发出的健康监测计数器。由 "
+"``L1FailureMetricsSubscriber`` 和 ``L2FailureMetricsSubscriber`` "
+"驱动，这两个订阅者在启用指标时会自动注册。所有三个计数器都携带 ``model_name``\\ （从每个 ``ObjectKey`` "
+"中提取），以便操作员可以在 Prometheus ``/metrics`` 端点上按模型进行切片。"
+
+#: ../../source/mp/observability/metrics.rst:228
+msgid "``lmcache_mp.l1_allocation_failure``"
+msgstr "``lmcache_mp.l1_allocation_failure``"
+
+#: ../../source/mp/observability/metrics.rst:230
+#, python-brace-format
+msgid ""
+"L1 memory allocation failures (OOM) during ``reserve_write``. Tagged by "
+"``during`` ∈ {``l1_store``, ``l2_prefetch``} to distinguish user-"
+"initiated stores from prefetch-triggered allocations, plus "
+"``model_name``."
+msgstr ""
+"在 ``reserve_write`` 期间的 L1 内存分配失败（OOM）。通过 ``during`` ∈ {``l1_store``, "
+"``l2_prefetch``} 标记，以区分用户发起的存储与预取触发的分配，以及 ``model_name``\\ 。"
+
+#: ../../source/mp/observability/metrics.rst:234
+msgid "``lmcache_mp.l1_read_failure``"
+msgstr "``lmcache_mp.l1_read_failure``"
+
+#: ../../source/mp/observability/metrics.rst:236
+#, python-brace-format
+msgid ""
+"L1 ``reserve_read`` failures. Tagged by ``during`` ∈ {``l2_store``, "
+"``l1_retrieve``}, ``reason`` ∈ {``not_found``, ``write_locked``}, plus "
+"``model_name``. **Post-lookup anomaly counter**, not a cache-miss counter"
+" — in MP mode ``reserve_read`` is only called after a successful lookup, "
+"so any non-zero value indicates a lookup/reserve race or unexpected "
+"eviction and should stay near zero in healthy operation."
+msgstr ""
+"L1 ``reserve_read`` 失败。标记为 ``during`` ∈ {``l2_store``, "
+"``l1_retrieve``}，\\ ``reason`` ∈ {``not_found``, ``write_locked``}，加上 "
+"``model_name``\\ 。\\ **后查找异常计数器**\\ ，而非缓存未命中计数器——在 MP 模式下，\\ "
+"``reserve_read`` 仅在查找成功后调用，因此任何非零值均表明存在查找/预留竞争或意外逐出，健康运行时该值应接近零。"
+
+#: ../../source/mp/observability/metrics.rst:243
+msgid "``lmcache_mp.l2_prefetch_failure``"
+msgstr "``lmcache_mp.l2_prefetch_failure``"
+
+#: ../../source/mp/observability/metrics.rst:245
+#, python-brace-format
+msgid ""
+"Chunks that L2 reported present at lookup but failed to land in L1. "
+"Tagged by ``reason`` ∈ {``l1_oom``, ``not_found``} plus ``model_name``. "
+"``l1_oom`` means L1 had no room to receive the prefetched object; "
+"``not_found`` means the adapter returned no data despite a positive "
+"lookup (e.g. concurrent delete)."
+msgstr ""
+"L2 报告在查找时存在但未能进入 L1 的块。标记为 ``reason`` ∈ {``l1_oom``, ``not_found``} 以及 "
+"``model_name``\\ 。\\ ``l1_oom`` 表示 L1 没有空间接收预取的对象；\\ ``not_found`` "
+"表示适配器在查找成功的情况下未返回数据（例如并发删除）。"
+
+#: ../../source/mp/observability/metrics.rst:251
+msgid ""
+"A ``reason=serde_failure`` value will be added to ``l2_prefetch_failure``"
+" as an additive, non-breaking extension once L2 adapters distinguish "
+"deserialization errors from missing objects — no dashboard migration "
+"needed when that lands."
+msgstr ""
+"一旦 L2 适配器区分反序列化错误和缺失对象，将会将 ``reason=serde_failure`` 值作为附加的、非破坏性的扩展添加到 "
+"``l2_prefetch_failure`` 中——当这项功能上线时，无需进行仪表板迁移。"
+
+#: ../../source/mp/observability/metrics.rst:256
+msgid ""
+"For the full design rationale (including which event types drive each "
+"counter and why ``lmcache_instance_id`` is deferred), see "
+"``docs/design/v1/mp_observability/METRICS.md`` in the source tree."
+msgstr ""
+"有关完整的设计原理（包括哪些事件类型驱动每个计数器以及为何推迟 ``lmcache_instance_id``\\ ），请参阅源树中的 "
+"``docs/design/v1/mp_observability/METRICS.md``\\ 。"
+
+#: ../../source/mp/observability/metrics.rst:261
+msgid "Lookup Hit-Rate Metrics"
+msgstr "查找命中率指标"
+
+#: ../../source/mp/observability/metrics.rst:263
+msgid ""
+"Token-level counters whose ratio gives the fraction of tokens requested "
+"by a lookup that were served from either L1 or L2. L0 (GPU prefix cache) "
+"is intentionally excluded — it is vLLM-owned and not observable from "
+"LMCache."
+msgstr ""
+"令牌级计数器，其比值表示通过查找请求的令牌中有多少比例是从 L1 或 L2 提供的。L0（GPU 前缀缓存）被有意排除在外——它由 vLLM "
+"管理，无法从 LMCache 中观察到。"
+
+#: ../../source/mp/observability/metrics.rst:274
+msgid "``lmcache_mp.lookup_requested``"
+msgstr "``lmcache_mp.lookup_requested``"
+
+#: ../../source/mp/observability/metrics.rst:275
+#: ../../source/mp/observability/metrics.rst:279
+msgid "Counter (attrs: ``model_name``, ``cache_salt``)"
+msgstr "计数器（属性：\\ ``model_name``, ``cache_salt``\\ ）"
+
+#: ../../source/mp/observability/metrics.rst:276
+msgid ""
+"Total tokens submitted for lookup (denominator of the L1+L2 token-level "
+"hit rate). Only chunk-aligned tokens are counted."
+msgstr "提交查找的总令牌数（L1+L2 令牌级命中率的分母）。仅计算与块对齐的令牌。"
+
+#: ../../source/mp/observability/metrics.rst:278
+msgid "``lmcache_mp.lookup_hit``"
+msgstr "``lmcache_mp.lookup_hit``"
+
+#: ../../source/mp/observability/metrics.rst:280
+msgid ""
+"Total tokens found in L1 or L2 during lookup (numerator of the L1+L2 "
+"token-level hit rate). Counts the contiguous prefix hit only."
+msgstr "在查找过程中在 L1 或 L2 中找到的总令牌数（L1+L2 令牌级命中率的分子）。仅计算连续前缀命中。"
+
+#: ../../source/mp/observability/metrics.rst:283
+msgid ""
+"Both counters are driven by the same event (``MP_LOOKUP_PREFETCH_END``), "
+"so they always advance together per completed lookup. Early-exit lookups "
+"contribute ``0`` to both, and abandoned lookups contribute to neither."
+msgstr ""
+"这两个计数器由同一事件（\\ ``MP_LOOKUP_PREFETCH_END``\\ "
+"）驱动，因此它们在每次完成查找时总是一起增加。提前退出的查找对两者都贡献 ``0``\\ ，而放弃的查找则不对两者贡献。"
+
+#: ../../source/mp/observability/metrics.rst:287
+msgid ""
+"The ``model_name`` and ``cache_salt`` attributes are captured at lookup "
+"time from ``IPCCacheServerKey`` so dashboards can compute per-model or "
+"per-tenant hit rate. ``cache_salt`` can be high-cardinality (one entry "
+"per tenant or isolation domain); drop it at scrape time with "
+"``metric_relabel_configs`` if storage cost matters."
+msgstr ""
+"``model_name`` 和 ``cache_salt`` 属性在查找时从 ``IPCCacheServerKey`` "
+"捕获，以便仪表板计算每个模型或每个租户的命中率。\\ ``cache_salt`` "
+"可能具有高基数（每个租户或隔离域一个条目）；若存储成本敏感，请在抓取时通过 ``metric_relabel_configs`` 丢弃它。"
+
+#: ../../source/mp/observability/metrics.rst:293
+msgid "**PromQL for hit rate:**"
+msgstr "**PromQL 查询命中率:**"
+
+#: ../../source/mp/observability/metrics.rst:306
+msgid "L0 (GPU) Block Lifecycle Histograms"
+msgstr "L0 (GPU) 块生命周期直方图"
+
+#: ../../source/mp/observability/metrics.rst:308
+msgid ""
+"Sampled (default 1%) GPU KV cache block lifecycle tracking via "
+"``L0LifecycleSubscriber``. Eviction is detected at reallocation time "
+"(when a block is assigned different tokens). Sampling uses random "
+"selection with a ``_skipped`` set (bounded by the finite number of "
+"physical GPU blocks)."
+msgstr ""
+"通过 ``L0LifecycleSubscriber`` 采样（默认 1%）GPU KV Cache "
+"块生命周期跟踪。在重新分配时检测逐出（当块被分配不同的令牌时）。采样使用带有 ``_skipped`` 集的随机选择（受限于有限数量的物理 GPU"
+" 块）。"
+
+#: ../../source/mp/observability/metrics.rst:314
+#, python-brace-format
+msgid ""
+"All L0 histograms are emitted with ``instance_id`` and ``model_name`` "
+"OTel attributes, enabling per-instance and per-model metric slicing in "
+"Prometheus (e.g. "
+"``lmcache_mp_l0_block_lifetime_seconds{instance_id=\"12345\",model_name"
+"=\"llama-7b\"}``)."
+msgstr ""
+"所有 L0 直方图都带有 ``instance_id`` 和 ``model_name`` OTel 属性，从而在 Prometheus "
+"中实现按实例和按模型的指标切片（例如 "
+"``lmcache_mp_l0_block_lifetime_seconds{instance_id=\\\"12345\\\",model_name"
+"=\\\"llama-7b\\\"}``\\ ）。"
+
+#: ../../source/mp/observability/metrics.rst:326
+msgid "``lmcache_mp.l0_block_lifetime``"
+msgstr "``lmcache_mp.l0_block_lifetime``"
+
+#: ../../source/mp/observability/metrics.rst:328
+msgid "Time from allocation to eviction per sampled GPU block."
+msgstr "每个采样的 GPU 块从分配到逐出的时间。"
+
+#: ../../source/mp/observability/metrics.rst:329
+msgid "``lmcache_mp.l0_block_idle_before_evict``"
+msgstr "``lmcache_mp.l0_block_idle_before_evict``"
+
+#: ../../source/mp/observability/metrics.rst:331
+msgid "Time from last access to eviction per sampled GPU block."
+msgstr "每个采样的 GPU 块从最后访问到逐出的时间。"
+
+#: ../../source/mp/observability/metrics.rst:332
+msgid "``lmcache_mp.l0_block_reuse_gap``"
+msgstr "``lmcache_mp.l0_block_reuse_gap``"
+
+#: ../../source/mp/observability/metrics.rst:334
+msgid "Time gaps between consecutive accesses of the same GPU block."
+msgstr "同一 GPU 块连续访问之间的时间间隔。"
+
+#: ../../source/mp/observability/metrics.rst:337
+msgid "L0 ↔ L1 Throughput Histograms"
+msgstr "L0 ↔ L1 吞吐量直方图"
+
+#: ../../source/mp/observability/metrics.rst:339
+#, python-brace-format
+msgid ""
+"Per-request throughput of GPU↔CPU copies via "
+"``L0L1ThroughputSubscriber``. Every store/retrieve request contributes "
+"one sample to the appropriate histogram: ``total_bytes / (end_ts - "
+"start_ts)`` in GB/s. Timestamps come from "
+"``MP_{STORE,RETRIEVE}_{START,END}`` events published on the GPU cupy "
+"stream, so they reflect true GPU-stream copy time — not Python/lock "
+"overhead."
+msgstr ""
+"每个请求的 GPU↔CPU 复制吞吐量通过 ``L0L1ThroughputSubscriber`` "
+"进行统计。每个存储/检索请求为相应的直方图贡献一个样本：\\ ``total_bytes / (end_ts - start_ts)`` 以 "
+"GB/s 为单位。时间戳来自在 GPU cupy 流上发布的 ``MP_{STORE,RETRIEVE}_{START,END}`` "
+"事件，因此它们反映了真实的 GPU 流复制时间——而不是 Python/锁的开销。"
+
+#: ../../source/mp/observability/metrics.rst:347
+#, python-brace-format
+msgid ""
+"All throughput histograms are emitted with ``engine_id`` (vLLM worker "
+"instance id), ``device`` (e.g. ``\"cuda:3\"``), and ``model_name`` OTel "
+"attributes, enabling per-worker, per-device, and per-model slicing in "
+"Prometheus (e.g. "
+"``lmcache_mp_l0_l1_store_throughput_GB_per_second{engine_id=\"0\",device=\"cuda:3\",model_name"
+"=\"meta-llama/Llama-3.1-8B\"}``)."
+msgstr ""
+"所有吞吐量直方图都带有 ``engine_id``\\ （vLLM 工作实例 ID）、\\ ``device``\\ （例如 "
+"``\"cuda:3\"``\\ ）和 ``model_name`` OTel 属性，从而支持在 Prometheus "
+"中按工作者、设备和模型进行切片（例如 "
+"``lmcache_mp_l0_l1_store_throughput_GB_per_second{engine_id=\"0\",device=\"cuda:3\",model_name"
+"=\"meta-llama/Llama-3.1-8B\"}``\\ ）。"
+
+#: ../../source/mp/observability/metrics.rst:360
+msgid "``lmcache_mp.l0_l1_store_throughput``"
+msgstr "``lmcache_mp.l0_l1_store_throughput``"
+
+#: ../../source/mp/observability/metrics.rst:362
+msgid "GPU→CPU (L0→L1) store throughput in GB/s per request."
+msgstr "每个请求的 GPU→CPU (L0→L1) 存储吞吐量（单位：GB/s）。"
+
+#: ../../source/mp/observability/metrics.rst:363
+msgid "``lmcache_mp.l0_l1_load_throughput``"
+msgstr "``lmcache_mp.l0_l1_load_throughput``"
+
+#: ../../source/mp/observability/metrics.rst:365
+msgid "CPU→GPU (L1→L0) load throughput in GB/s per request."
+msgstr "每个请求的 CPU→GPU (L1→L0) 加载吞吐量（GB/s）。"
+
+#: ../../source/mp/observability/metrics.rst:368
+msgid "L1 ↔ L2 Throughput Histograms"
+msgstr "L1 ↔ L2 吞吐量直方图"
+
+#: ../../source/mp/observability/metrics.rst:370
+msgid ""
+"Per-request throughput of L1↔L2 transfers via ``L2ThroughputSubscriber``."
+" The store path correlates ``L2_STORE_SUBMITTED`` → "
+"``L2_STORE_COMPLETED`` by ``(adapter_index, task_id)``. The load path "
+"correlates the per-adapter ``L2_LOAD_TASK_SUBMITTED`` → "
+"``L2_LOAD_TASK_COMPLETED`` events by ``(request_id, adapter_index)``; the"
+" request-level ``L2_PREFETCH_LOAD_*`` events used by the chunk-count "
+"counters aggregate across adapters and cannot be attributed to a specific"
+" ``l2_name``."
+msgstr ""
+"每个请求的 L1↔L2 传输吞吐量通过 ``L2ThroughputSubscriber`` 进行统计。存储路径通过 "
+"``(adapter_index, task_id)`` 关联 ``L2_STORE_SUBMITTED`` → "
+"``L2_STORE_COMPLETED``\\ 。加载路径通过 ``(request_id, adapter_index)`` 关联每个适配器的"
+" ``L2_LOAD_TASK_SUBMITTED`` → ``L2_LOAD_TASK_COMPLETED`` 事件；请求级别的 "
+"``L2_PREFETCH_LOAD_*`` 事件用于块计数器在适配器之间进行聚合，无法归因于特定的 ``l2_name``\\ 。"
+
+#: ../../source/mp/observability/metrics.rst:379
+msgid ""
+"Timestamps span **submit → complete**, so the duration includes adapter "
+"queue, network, and disk I/O — the value is *bytes / end-to-end latency*,"
+" not raw transfer rate. Use these histograms to compare adapter types and"
+" catch regressions; use the L0↔L1 histograms when you need pure copy-time"
+" throughput."
+msgstr ""
+"时间戳跨度为 **提交 → 完成**\\ ，因此持续时间包括适配器队列、网络和磁盘 I/O — 该值为字节 / "
+"端到端延迟，而非原始传输速率。使用这些直方图比较适配器类型并捕捉回归；当您需要纯粹的复制时间吞吐量时，请使用 L0↔L1 直方图。"
+
+#: ../../source/mp/observability/metrics.rst:385
+#, python-brace-format
+msgid ""
+"All L1↔L2 throughput histograms carry a single ``l2_name`` OTel attribute"
+" — the registered adapter type (e.g. ``\"fs\"``, ``\"nixl_store\"``, "
+"``\"mooncake_store\"``) — enabling per-backend slicing in Prometheus "
+"(e.g. "
+"``lmcache_mp_l2_store_throughput_GB_per_second{l2_name=\"nixl_store\"}``)."
+msgstr ""
+"所有 L1↔L2 吞吐量直方图都携带一个 ``l2_name`` OTel 属性——注册的适配器类型（例如 ``\\\"fs\\\"``, "
+"``\\\"nixl_store\\\"``, ``\\\"mooncake_store\\\"``\\ ）——使得在 Prometheus "
+"中能够按后端进行切片（例如 "
+"``lmcache_mp_l2_store_throughput_GB_per_second{l2_name=\\\"nixl_store\\\"}``\\"
+" ）。"
+
+#: ../../source/mp/observability/metrics.rst:397
+msgid "``lmcache_mp.l2_store_throughput``"
+msgstr "``lmcache_mp.l2_store_throughput``"
+
+#: ../../source/mp/observability/metrics.rst:399
+msgid "L1→L2 store throughput in GB/s per request."
+msgstr "每个请求的 L1→L2 存储吞吐量（GB/s）。"
+
+#: ../../source/mp/observability/metrics.rst:400
+msgid "``lmcache_mp.l2_load_throughput``"
+msgstr "``lmcache_mp.l2_load_throughput``"
+
+#: ../../source/mp/observability/metrics.rst:402
+msgid "L2→L1 load throughput in GB/s per (request, adapter) pair."
+msgstr "每对（请求，适配器）的 L2→L1 加载吞吐量（单位：GB/s）。"
+
+#: ../../source/mp/observability/metrics.rst:404
+msgid "**PromQL for average throughput (GB/s), per backend:**"
+msgstr "**每个后端的平均吞吐量（单位：GB/s）的 PromQL：**"
+
+#: ../../source/mp/observability/metrics.rst:418
+msgid ""
+"``l2_store_throughput`` populates whenever chunks are written to L2. "
+"``l2_load_throughput`` only populates when chunks are read **from L2 into"
+" L1** — i.e. on a prefetch load after the entry has aged out of L1. If "
+"your working set fits entirely in L1 (common with small models or a large"
+" ``--l1-size-gb``), lookups are served from L1 and the load histogram "
+"stays empty even though store throughput is non-zero. Drive enough "
+"distinct data to force L1 eviction, or restart the server between store "
+"and load passes, to exercise the L2 load path."
+msgstr "``l2_store_throughput`` 在写入块到 L2 时填充。 ``l2_load_throughput`` 仅在从 L2 读取块到 L1 时填充——即在条目从 L1 逐出后进行的预取加载。如果您的工作集完全适合 L1（在小模型或较大 ``--l1-size-gb`` 的情况下很常见），查找将从 L1 提供服务，尽管存储吞吐量非零，但加载直方图将保持为空。驱动足够不同的数据以强制 L1 逐出，或在存储和加载过程之间重启服务器，以测试 L2 加载路径。"
+
+#: ../../source/mp/observability/metrics.rst:428
+msgid "Engine Counters"
+msgstr "引擎计数器"
+
+#: ../../source/mp/observability/metrics.rst:430
+msgid ""
+"Worker-scoped counters tied to what the MP server delivers back to each "
+"vLLM worker via ``retrieve()``.  Labeled by ``worker_id`` (the vLLM "
+"worker instance id) — distinct from any scheduler-scoped id that may "
+"appear on other metrics."
+msgstr ""
+"与 MP 服务器通过 ``retrieve()`` 返回给每个 vLLM 工作线程相关的工作线程范围计数器。以 ``worker_id``\\ "
+"（vLLM 工作线程实例 ID）标记——与其他指标中可能出现的任何调度器范围 ID 不同。"
+
+#: ../../source/mp/observability/metrics.rst:442
+msgid "``lmcache_mp.num_chunks_loaded``"
+msgstr "``lmcache_mp.num_chunks_loaded``"
+
+#: ../../source/mp/observability/metrics.rst:443
+msgid "Counter (attrs: ``worker_id``, ``model_name``, ``cache_salt``)"
+msgstr "计数器（属性：\\ ``worker_id``, ``model_name``, ``cache_salt``\\ ）"
+
+#: ../../source/mp/observability/metrics.rst:444
+msgid ""
+"Total number of LMCache chunks loaded into the engine, summed over all "
+"``retrieve()`` completions.  Sliceable per worker, per model, and per "
+"tenant / isolation domain (``cache_salt``). ``cache_salt`` may be high-"
+"cardinality; drop it at scrape time with ``metric_relabel_configs`` if "
+"storage cost matters."
+msgstr ""
+"加载到引擎的 LMCache 块总数，汇总自所有 ``retrieve()`` 完成结果。可按工作者、模型及租户/隔离域（\\ "
+"``cache_salt``\\ ）进行切片。\\ ``cache_salt`` 可能具有高基数；若存储成本敏感，请在抓取时通过 "
+"``metric_relabel_configs`` 丢弃它。"
+
+#: ../../source/mp/observability/metrics.rst:451
+msgid "Observable Gauges"
+msgstr "可观察仪表"
+
+#: ../../source/mp/observability/metrics.rst:453
+msgid ""
+"Point-in-time state snapshots registered via ``register_gauge`` (pull-"
+"based OTel observable gauges)."
+msgstr "通过 ``register_gauge`` 注册的即时状态快照（基于拉取的 OTel 可观察仪表）。"
+
+#: ../../source/mp/observability/metrics.rst:456
+msgid ""
+"The three in-flight metrics carry two attributes that distinguish "
+"adapters even when more than one is registered with the same backend type"
+" — same shape as ``lmcache_mp.l2_store_completed``:"
+msgstr ""
+"这三个正在进行的指标携带两个属性，即使在与相同后端类型注册多个适配器时也能区分它们——与 "
+"``lmcache_mp.l2_store_completed`` 具有相同形状："
+
+#: ../../source/mp/observability/metrics.rst:460
+msgid ""
+"``l2_name`` — the registered adapter type (e.g. ``\"fs\"``, "
+"``\"nixl_store\"``, ``\"mooncake_store\"``)."
+msgstr ""
+"``l2_name`` — 注册的适配器类型（例如 ``\"fs\"``, ``\"nixl_store\"``, "
+"``\"mooncake_store\"``\\ ）。"
+
+#: ../../source/mp/observability/metrics.rst:462
+msgid "``adapter_index`` — position in the controller's adapter list."
+msgstr "``adapter_index`` — 控制器适配器列表中的位置。"
+
+#: ../../source/mp/observability/metrics.rst:464
+msgid "Adapters with no in-flight work emit no datapoint for that scrape."
+msgstr "没有正在进行的工作的适配器不会为该抓取发出数据点。"
+
+#: ../../source/mp/observability/metrics.rst:473
+msgid "``lmcache_mp.active_prefetch_jobs``"
+msgstr "``lmcache_mp.active_prefetch_jobs``"
+
+#: ../../source/mp/observability/metrics.rst:474
+#: ../../source/mp/observability/metrics.rst:478
+#: ../../source/mp/observability/metrics.rst:483
+#: ../../source/mp/observability/metrics.rst:544
+#: ../../source/mp/observability/metrics.rst:548
+msgid "ObservableGauge"
+msgstr "可观察仪表"
+
+#: ../../source/mp/observability/metrics.rst:475
+msgid ""
+"Number of prefetch jobs currently in-flight. A sustained high value may "
+"indicate slow L2 backends or polling delays."
+msgstr "当前正在进行的预取作业数量。持续的高值可能表示 L2 后端缓慢或轮询延迟。"
+
+#: ../../source/mp/observability/metrics.rst:477
+msgid "``lmcache_mp.l1_memory_usage_bytes``"
+msgstr "``lmcache_mp.l1_memory_usage_bytes``"
+
+#: ../../source/mp/observability/metrics.rst:479
+msgid ""
+"Bytes currently held in L1.  Rising without plateauing typically "
+"indicates a leak; saturating at the configured ``--l1-size-gb`` indicates"
+" working set exceeds capacity."
+msgstr "当前在 L1 中占用的字节数。持续上升而没有平台期通常表示存在泄漏；在配置的 ``--l1-size-gb`` 达到饱和时表示工作集超过了容量。"
+
+#: ../../source/mp/observability/metrics.rst:482
+msgid "``lmcache_mp.l1_usage_ratio``"
+msgstr "``lmcache_mp.l1_usage_ratio``"
+
+#: ../../source/mp/observability/metrics.rst:484
+msgid ""
+"L1 used/total ratio (``0.0``–``1.0``), sampled at scrape time from "
+"``L1Manager.get_memory_usage()``. Returns ``0.0`` when the gauge target "
+"is not yet wired up or ``total_bytes`` is zero, so the callback never "
+"raises during a scrape. Compare against the eviction watermark (default "
+"``0.8``) to read whether the eviction loop is below or above its trigger "
+"threshold."
+msgstr ""
+"L1 使用/总比率 (``0.0``–``1.0``)，在抓取时从 ``L1Manager.get_memory_usage()`` "
+"采样。当仪表目标尚未连接或 ``total_bytes`` 为零时返回 ``0.0``\\ ，因此在抓取期间回调不会触发。与逐出水位线 (默认 "
+"``0.8``) 进行比较，以判断逐出循环是否低于或高于触发阈值。"
+
+#: ../../source/mp/observability/metrics.rst:490
+msgid "``lmcache_mp.l2_usage_bytes``"
+msgstr "``lmcache_mp.l2_usage_bytes``"
+
+#: ../../source/mp/observability/metrics.rst:491
+msgid "ObservableGauge (attr: ``l2_name``)"
+msgstr "可观察仪表 (属性: ``l2_name``)"
+
+#: ../../source/mp/observability/metrics.rst:492
+msgid ""
+"Bytes currently held in each L2 adapter, sampled at scrape time from "
+"``adapter.get_usage()``.  One observation per configured adapter, tagged "
+"by ``l2_name`` (the adapter type, e.g. ``\"fs\"``, ``\"nixl_store\"``, "
+"``\"mooncake_store\"``).  Parallel to ``l1_memory_usage_bytes`` for the "
+"L2 tier — use it to see how much each L2 backend currently holds.  "
+"Adapters whose ``get_usage()`` raises are skipped silently rather than "
+"poisoning the observation, so a missing datapoint for one ``l2_name`` can"
+" mean either \"not configured\" or \"adapter errored on this scrape\" — "
+"cross-check with the L2 store/load counters."
+msgstr ""
+"每个 L2 适配器当前持有的字节数，在抓取时从 ``adapter.get_usage()`` 采样。每个已配置的适配器对应一个观测值，通过 "
+"``l2_name`` 标记（适配器类型，例如 ``\"fs\"``\\ 、\\ ``\"nixl_store\"``\\ 、\\ "
+"``\"mooncake_store\"``\\ ）。它是 L2 层中与 ``l1_memory_usage_bytes`` "
+"对应的指标——用于查看每个 L2 后端当前持有多少数据。\\ ``get_usage()`` "
+"抛出异常的适配器会被静默跳过，而不会污染观测结果，因此某个 ``l2_name`` "
+"缺失数据点可能意味着“未配置”或“该次抓取时适配器发生错误”——请与 L2 存储/加载计数器交叉核对。"
+
+#: ../../source/mp/observability/metrics.rst:502
+msgid "``lmcache_mp.num_inflight_l2_stores``"
+msgstr "``lmcache_mp.num_inflight_l2_stores``"
+
+#: ../../source/mp/observability/metrics.rst:503
+#: ../../source/mp/observability/metrics.rst:508
+#: ../../source/mp/observability/metrics.rst:513
+msgid "ObservableGauge (attrs: ``l2_name``, ``adapter_index``)"
+msgstr "ObservableGauge (attrs: ``l2_name``, ``adapter_index``)"
+
+#: ../../source/mp/observability/metrics.rst:504
+msgid ""
+"L2 store tasks currently executing, per adapter.  Sustained non-zero "
+"values indicate the adapter cannot keep up with the L1 → L2 write rate."
+msgstr "每个适配器当前正在执行的 L2 存储任务。 持续的非零值表明适配器无法跟上 L1 → L2 写入速率。"
+
+#: ../../source/mp/observability/metrics.rst:507
+msgid "``lmcache_mp.num_inflight_l2_loads``"
+msgstr "``lmcache_mp.num_inflight_l2_loads``"
+
+#: ../../source/mp/observability/metrics.rst:509
+msgid ""
+"L2 → L1 prefetch load tasks currently executing, per adapter. Pair with "
+"``num_inflight_l2_stores`` to see whether read or write traffic dominates"
+" a given backend."
+msgstr ""
+"每个适配器当前正在执行的 L2 → L1 预取加载任务。与 ``num_inflight_l2_stores`` "
+"配对，以查看给定后端是读流量还是写流量占主导。"
+
+#: ../../source/mp/observability/metrics.rst:512
+msgid "``lmcache_mp.inflight_load_memory_usage_bytes``"
+msgstr "``lmcache_mp.inflight_load_memory_usage_bytes``"
+
+#: ../../source/mp/observability/metrics.rst:514
+msgid ""
+"L1 bytes reserved by in-flight L2 → L1 prefetch loads, per adapter.  "
+"Rising in-flight bytes alongside rising ``l1_memory_usage_bytes`` is a "
+"signal that prefetch reservations are crowding out cacheable data.  Per-"
+"adapter byte attribution follows each request's ``load_plan`` bitmap, so "
+"summing across adapters never double-counts."
+msgstr ""
+"每个适配器由正在进行的 L2 → L1 预取加载所预留的 L1 字节数。若正在进行的字节数与 ``l1_memory_usage_bytes`` "
+"同步上升，则表明预取预留正在挤占可缓存数据的空间。每个适配器的字节归属遵循每个请求的 ``load_plan`` "
+"位图，因此跨适配器求和时不会重复计数。"
+
+#: ../../source/mp/observability/metrics.rst:522
+msgid "EventBus Self-Monitoring"
+msgstr "事件总线自我监控"
+
+#: ../../source/mp/observability/metrics.rst:524
+msgid ""
+"Health metrics for the EventBus itself, registered by "
+"``EventBusSelfMetricsSubscriber`` on the ``lmcache.event_bus`` OTel "
+"meter.  These metrics observe bus state directly via the ``EventBus`` "
+"accessors and report on every OTel scrape — they are not driven by "
+"events, so dropping or failing subscribers cannot silence them."
+msgstr ""
+"EventBus 本身的健康指标，由 ``EventBusSelfMetricsSubscriber`` 在 "
+"``lmcache.event_bus`` OTel 计量器上注册。这些指标通过 ``EventBus`` 访问器直接观察总线状态，并在每次 "
+"OTel 抓取时报告——它们不是由事件驱动的，因此丢弃或失败的订阅者无法使其静默。"
+
+#: ../../source/mp/observability/metrics.rst:530
+msgid ""
+"Use them to answer: is the EventBus keeping up with publishers, is "
+"anything being dropped, and are any subscriber callbacks raising? A non-"
+"zero ``dropped_events_total`` or a sustained non-zero "
+"``drain_lag_seconds`` indicates the bus is at ``--event-bus-queue-size`` "
+"and tail-dropping; raise that flag or investigate slow subscribers."
+msgstr ""
+"使用它们来回答：EventBus 是否能跟上发布者的速度，是否有事件被丢弃，是否有订阅者回调抛出异常？非零的 "
+"``dropped_events_total`` 或持续非零的 ``drain_lag_seconds`` 表明总线队列已达 ``--event-"
+"bus-queue-size`` 上限并正在进行尾部丢弃；请调大该参数值或排查慢速订阅者。"
+
+#: ../../source/mp/observability/metrics.rst:543
+msgid "``lmcache_mp.event_bus.queue_depth``"
+msgstr "``lmcache_mp.event_bus.queue_depth``"
+
+#: ../../source/mp/observability/metrics.rst:545
+msgid "Events currently queued in the EventBus (``len(_queue)`` at scrape time)."
+msgstr "事件总线中当前排队的事件（在抓取时的 ``len(_queue)``\\ ）。"
+
+#: ../../source/mp/observability/metrics.rst:547
+msgid "``lmcache_mp.event_bus.drain_lag_seconds``"
+msgstr "``lmcache_mp.event_bus.drain_lag_seconds``"
+
+#: ../../source/mp/observability/metrics.rst:549
+msgid ""
+"Seconds since the oldest queued event was published; ``0.0`` when empty."
+"  Rising values mean the drain thread is falling behind."
+msgstr "自最旧的排队事件发布以来的秒数；队列为空时为 ``0.0``\\ 。值持续上升意味着排空线程处理速度跟不上。"
+
+#: ../../source/mp/observability/metrics.rst:552
+msgid "``lmcache_mp.event_bus.dropped_events_total``"
+msgstr "``lmcache_mp.event_bus.dropped_events_total``"
+
+#: ../../source/mp/observability/metrics.rst:553
+msgid "ObservableCounter"
+msgstr "可观察计数器"
+
+#: ../../source/mp/observability/metrics.rst:554
+msgid ""
+"Cumulative events dropped because the EventBus queue was at ``--event-"
+"bus-queue-size``."
+msgstr "因 EventBus 队列达到 ``--event-bus-queue-size`` 而累计丢弃的事件。"
+
+#: ../../source/mp/observability/metrics.rst:556
+msgid "``lmcache_mp.event_bus.subscriber_exceptions``"
+msgstr "``lmcache_mp.event_bus.subscriber_exceptions``"
+
+#: ../../source/mp/observability/metrics.rst:557
+msgid "ObservableCounter (attr: ``subscriber_name``)"
+msgstr "可观察计数器 (属性: ``subscriber_name``)"
+
+#: ../../source/mp/observability/metrics.rst:558
+msgid ""
+"Cumulative exceptions raised by subscriber callbacks during EventBus "
+"dispatch, tagged by ``subscriber_name`` (the failing callback's owning "
+"class for bound methods, or ``__qualname__`` for free functions)."
+msgstr ""
+"由事件总线分发期间由订阅者回调引发的累计异常，按 ``subscriber_name`` 标记（对于绑定方法为失败回调的拥有类，对于自由函数为 "
+"``__qualname__``\\ ）。"
+
+#: ../../source/mp/observability/metrics.rst:563
+msgid ""
+"For the full design rationale and the in-process accessors that back each"
+" metric see ``docs/design/v1/mp_observability/METRICS.md`` and "
+"``docs/design/v1/mp_observability/event-bus.md`` in the source tree."
+msgstr ""
+"有关完整的设计原理以及支持每个指标的进程内访问器，请参阅源代码树中的 "
+"``docs/design/v1/mp_observability/METRICS.md`` 和 "
+"``docs/design/v1/mp_observability/event-bus.md``\\ 。"
+
+#: ../../source/mp/observability/metrics.rst:568
+msgid "Prometheus Scrape Configuration"
+msgstr "Prometheus 抓取配置"
+
+#: ../../source/mp/observability/metrics.rst:570
+msgid ""
+"In **pull mode** (no ``--otlp-endpoint``), point Prometheus at the "
+"server's HTTP-frontend port — ``--http-port``, default **8080** — not at "
+"``--prometheus-port``:"
+msgstr "在 **拉取模式**（没有 ``--otlp-endpoint``）下，将 Prometheus 指向服务器的 HTTP 前端端口 — ``--http-port``，默认 **8080** — 而不是 ``--prometheus-port``："
+
+#: ../../source/mp/observability/metrics.rst:581
+msgid ""
+"In **push mode** (``--otlp-endpoint`` set), the server does not expose "
+"``/metrics`` itself; scrape the OpenTelemetry Collector's Prometheus "
+"exporter instead. The bundled stack in ``examples/observability/`` wires "
+"this up for you — see :doc:`index`."
+msgstr "在 **推送模式** (设置了 ``--otlp-endpoint``) 下，服务器不会直接暴露 ``/metrics``；请改为抓取 OpenTelemetry Collector 的 Prometheus 导出器。``examples/observability/`` 中捆绑的堆栈为您配置了这一点 — 请参阅 :doc:`index`。"
+
+#~ msgid ""
+#~ "Metrics are collected via OpenTelemetry "
+#~ "counters and exported through an in-"
+#~ "process **Prometheus** ``/metrics`` HTTP "
+#~ "endpoint (default port 9090). When "
+#~ "``--otlp-endpoint`` is set, metrics are "
+#~ "also pushed to the OTel collector."
+#~ msgstr ""
+#~ "指标通过 OpenTelemetry 计数器收集，并通过进程内的 **Prometheus** "
+#~ "``/metrics`` HTTP 端点导出（默认端口 9090）。当设置 "
+#~ "``--otlp-endpoint`` 时，指标也会推送到 OTel 收集器。"
+
+#~ msgid "Add the LMCache server as a Prometheus scrape target:"
+#~ msgstr "将 LMCache 服务器添加为 Prometheus 抓取目标："
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/traces.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/traces.po
new file mode 100644
index 0000000..d299a37
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/observability/traces.po
@@ -0,0 +1,279 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/observability/traces.rst:2
+msgid "Tracing"
+msgstr "追踪"
+
+#: ../../source/mp/observability/traces.rst:6
+msgid ""
+"``--enable-tracing`` **requires** ``--otlp-endpoint`` to be set. The "
+"server will refuse to start if tracing is enabled without an OTLP "
+"endpoint, since there is no local fallback for trace export."
+msgstr "``--enable-tracing`` **要求** 设置 ``--otlp-endpoint``\\ 。如果启用追踪但没有 OTLP 端点，服务器将拒绝启动，因为没有本地回退用于追踪导出。"
+
+#: ../../source/mp/observability/traces.rst:10
+msgid ""
+"When tracing is enabled (``--enable-tracing --otlp-endpoint <URL>``), the"
+" tracing subscriber creates OTel spans from START/END event pairs:"
+msgstr "当启用追踪时（\\ ``--enable-tracing --otlp-endpoint <URL>``\\ ），追踪订阅者从 START/END 事件对创建 OTel spans："
+
+#: ../../source/mp/observability/traces.rst:13
+msgid "``mp.store`` — from ``MP_STORE_START`` to ``MP_STORE_END``"
+msgstr "``mp.store`` — 从 ``MP_STORE_START`` 到 ``MP_STORE_END``"
+
+#: ../../source/mp/observability/traces.rst:14
+msgid "``mp.retrieve`` — from ``MP_RETRIEVE_START`` to ``MP_RETRIEVE_END``"
+msgstr "``mp.retrieve`` — 从 ``MP_RETRIEVE_START`` 到 ``MP_RETRIEVE_END``"
+
+#: ../../source/mp/observability/traces.rst:15
+msgid ""
+"``mp.lookup_prefetch`` — from ``MP_LOOKUP_PREFETCH_START`` to "
+"``MP_LOOKUP_PREFETCH_END``"
+msgstr "``mp.lookup_prefetch`` — 从 ``MP_LOOKUP_PREFETCH_START`` 到 ``MP_LOOKUP_PREFETCH_END``"
+
+#: ../../source/mp/observability/traces.rst:17
+msgid ""
+"Each span carries event metadata as span attributes (e.g. ``device``, "
+"``stored_count``, ``found_count``)."
+msgstr "每个 span 携带事件元数据作为 span 属性（例如 ``device``\\ 、\\ ``stored_count``\\ 、\\ ``found_count``\\ ）。"
+
+#: ../../source/mp/observability/traces.rst:20
+msgid ""
+"View traces in any OTel-compatible backend such as **Jaeger** or "
+"**Grafana Tempo**."
+msgstr "在任何与 OTel 兼容的后端中查看追踪，例如 **Jaeger** 或 **Grafana Tempo**\\ 。"
+
+#: ../../source/mp/observability/traces.rst:36
+msgid "Per-Request Hit-Rate Attributes"
+msgstr "每个请求的命中率属性"
+
+#: ../../source/mp/observability/traces.rst:38
+msgid ""
+"Each session is wrapped in a per-request root span — ``request`` for the "
+"standard MP path and ``cb.request`` for the CacheBlend path — that nests "
+"all child spans (``mp.store``, ``mp.retrieve``, ``mp.lookup_prefetch``) "
+"beneath it.  When the lookup phase ends, the root span is annotated with "
+"three OTel attributes that summarise the request-level cache hit rate:"
+msgstr "每个会话都被封装在一个每请求根 span 中——标准 MP 路径对应 ``request``\\ ，CacheBlend 路径对应 ``cb.request``——该根 span 将所有子 span（\\ ``mp.store``\\ 、\\ ``mp.retrieve``\\ 、\\ ``mp.lookup_prefetch``\\ ）嵌套在其下。当查找阶段结束时，根 span 会被标注三个 OTel 属性，用以汇总请求级别的缓存命中率："
+
+#: ../../source/mp/observability/traces.rst:48
+msgid "Attribute"
+msgstr "属性"
+
+#: ../../source/mp/observability/traces.rst:49
+msgid "OTel type"
+msgstr "OTel 类型"
+
+#: ../../source/mp/observability/traces.rst:50
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/observability/traces.rst:51
+msgid "``hit_tokens``"
+msgstr "``hit_tokens``"
+
+#: ../../source/mp/observability/traces.rst:52
+#: ../../source/mp/observability/traces.rst:55
+msgid "``int``"
+msgstr "``int``"
+
+#: ../../source/mp/observability/traces.rst:53
+msgid "Tokens served from L1+L2 (numerator)."
+msgstr "从 L1+L2 命中并返回的 token 数（分子）。"
+
+#: ../../source/mp/observability/traces.rst:54
+msgid "``requested_tokens``"
+msgstr "``requested_tokens``"
+
+#: ../../source/mp/observability/traces.rst:56
+msgid "Chunk-aligned tokens submitted for lookup (denominator)."
+msgstr "提交查找的块对齐 token 数（分母）。"
+
+#: ../../source/mp/observability/traces.rst:57
+msgid "``hit_rate``"
+msgstr "``hit_rate``"
+
+#: ../../source/mp/observability/traces.rst:58
+msgid "``float``"
+msgstr "``float``"
+
+#: ../../source/mp/observability/traces.rst:59
+msgid ""
+"``hit_tokens / requested_tokens``; ``0.0`` when the denominator is zero."
+"  Stored as a precomputed float because trace UIs (Tempo, Jaeger) cannot "
+"derive it from two integer attributes at query time."
+msgstr "``hit_tokens / requested_tokens``\\ ；当分母为零时取 ``0.0``\\ 。以预计算浮点数形式存储，原因是追踪 UI（Tempo、Jaeger）无法在查询时从两个整数属性动态推导该值。"
+
+#: ../../source/mp/observability/traces.rst:63
+msgid ""
+"The attributes are written when ``MP_LOOKUP_PREFETCH_END`` (standard MP "
+"path) or ``CB_LOOKUP_END`` (CacheBlend path) is processed — while the "
+"root span is still open.  **Store-only requests** that never call "
+"``lookup_prefetch_start()`` emit no end event for the lookup phase, so "
+"their root span will not carry these attributes."
+msgstr "在处理 ``MP_LOOKUP_PREFETCH_END``\\ （标准 MP 路径）或 ``CB_LOOKUP_END``\\ （CacheBlend 路径）时写入这些属性——此时根 span 仍处于打开状态。\\ **纯存储请求**\\ 不会调用 ``lookup_prefetch_start()``\\ ，因此不会为查找阶段发出结束事件，其根 span 也不会携带这些属性。"
+
+#: ../../source/mp/observability/traces.rst:69
+msgid "Example TraceQL queries (Grafana Tempo):"
+msgstr "示例 TraceQL 查询（Grafana Tempo）："
+
+#: ../../source/mp/observability/traces.rst:82
+msgid ""
+"For the full event-to-span mapping and the registry pattern that links "
+"child spans back to the root see ``docs/design/observability/request-"
+"event-span.md`` in the source tree."
+msgstr "有关完整的事件到 span 映射以及将子 span 关联回根 span 的注册模式，请参阅源码树中的 ``docs/design/observability/request-event-span.md``\\ 。"
+
+#: ../../source/mp/observability/traces.rst:89
+msgid "Trace Recording"
+msgstr "追踪记录"
+
+#: ../../source/mp/observability/traces.rst:93
+msgid ""
+"Trace recording is **distinct from** ``--enable-tracing`` (OTel spans). "
+"Trace recording captures every ``StorageManager`` public-API call to a "
+"binary file so the same workload can be **replayed** later for testing, "
+"regression hunting, and benchmarking — without needing vLLM and "
+"(eventually) without a GPU. ``--enable-tracing`` exports live OTel spans "
+"to an OTLP endpoint for online observability. The two features are "
+"independent and can be used together."
+msgstr "追踪录制与 ``--enable-tracing``\\ （OTel span）是 **两个独立的功能**\\ 。追踪录制将每次 ``StorageManager`` 公共 API 调用记录到二进制文件，以便后续在无需 vLLM（最终也无需 GPU）的情况下 **重放** 相同的工作负载，用于测试、回归排查和基准测试。\\ ``--enable-tracing`` 则将实时 OTel span 导出到 OTLP 端点以实现在线可观测性。两者相互独立，可同时使用。"
+
+#: ../../source/mp/observability/traces.rst:101
+#, python-brace-format
+msgid ""
+"When ``--trace-level storage`` is set, LMCache records every call to "
+"``StorageManager.{reserve_write, finish_write, submit_prefetch_task, "
+"read_prefetched_results, finish_read_prefetched}`` to a binary file for "
+"later replay."
+msgstr "当设置 ``--trace-level storage`` 时，LMCache 会将每次对 ``StorageManager.{reserve_write, finish_write, submit_prefetch_task, read_prefetched_results, finish_read_prefetched}`` 的调用记录到一个二进制文件中，以便后续重放。"
+
+#: ../../source/mp/observability/traces.rst:106
+msgid ""
+"Recording is **off by default** and adds near-zero overhead when off (a "
+"single boolean check per ``StorageManager`` call). When on, recording "
+"happens on the EventBus drain thread, off the request path."
+msgstr "录制默认\\ **关闭**\\ ，关闭状态下开销几乎为零（每次 ``StorageManager`` 调用仅做一次布尔判断）。开启时，录制在 EventBus 排空线程上执行，不占用请求路径。"
+
+#: ../../source/mp/observability/traces.rst:111
+msgid "Capturing a trace"
+msgstr "捕获追踪"
+
+#: ../../source/mp/observability/traces.rst:113
+msgid "With an explicit output path:"
+msgstr "带有显式输出路径："
+
+#: ../../source/mp/observability/traces.rst:121
+msgid "With an implicit timestamped output path under ``$TMPDIR``:"
+msgstr "在 ``$TMPDIR`` 下使用隐式时间戳输出路径："
+
+#: ../../source/mp/observability/traces.rst:132
+msgid ""
+"The trace file is closed cleanly on shutdown (SIGTERM is handled by the "
+"EventBus stop path)."
+msgstr "关闭时（SIGTERM 由 EventBus 停止路径处理），追踪文件会被正常关闭。"
+
+#: ../../source/mp/observability/traces.rst:136
+msgid "Replay"
+msgstr "重放"
+
+#: ../../source/mp/observability/traces.rst:138
+msgid ""
+"Replaying a recorded trace, plus the full set of CLI flags for driving, "
+"monitoring, and exporting replay results, is covered in its own page: "
+":doc:`/mp/tracing_and_debugging`."
+msgstr "录制追踪的重放方式，以及驱动、监控和导出重放结果的完整 CLI 参数集，详见专属页面： :doc:`/mp/tracing_and_debugging`。"
+
+#: ../../source/mp/observability/traces.rst:143
+msgid "What is captured (and what is not)"
+msgstr "捕获了什么（以及未捕获的内容）"
+
+#: ../../source/mp/observability/traces.rst:145
+msgid "**Captured:**"
+msgstr "**捕获：**"
+
+#: ../../source/mp/observability/traces.rst:147
+msgid "The fully-qualified name of every decorated ``StorageManager`` call."
+msgstr "每个被装饰的 ``StorageManager`` 方法调用的完全限定名（qualname）。"
+
+#: ../../source/mp/observability/traces.rst:148
+msgid ""
+"Each call's input arguments (e.g. ``keys``, ``layout_desc``, ``mode``, "
+"``extra_count``, ``external_request_id``)."
+msgstr "每个调用的输入参数（例如 ``keys``, ``layout_desc``, ``mode``, ``extra_count``, ``external_request_id``\\ ）。"
+
+#: ../../source/mp/observability/traces.rst:150
+msgid "Wall-clock and monotonic timestamps of each call."
+msgstr "每个调用的墙钟时间和单调时间戳。"
+
+#: ../../source/mp/observability/traces.rst:151
+msgid ""
+"A header carrying a trace schema version, start times, and a SHA-256 "
+"digest of the active ``StorageManagerConfig`` so replay can detect "
+"mismatched configurations."
+msgstr "包含追踪 schema 版本、开始时间以及当前 ``StorageManagerConfig`` 的 SHA-256 摘要的文件头，供重放时检测配置不匹配。"
+
+#: ../../source/mp/observability/traces.rst:155
+msgid "**Not captured:**"
+msgstr "**未捕获：**"
+
+#: ../../source/mp/observability/traces.rst:157
+msgid ""
+"KV tensor bytes. Replay exercises bookkeeping and controller logic; "
+"payloads at replay time are zeros."
+msgstr "KV 张量的字节内容。重放仅演练状态记账与控制器逻辑；重放时的负载数据以零值填充。"
+
+#: ../../source/mp/observability/traces.rst:159
+msgid ""
+"Calls inside the ``MPCacheServer``, the message queue, or any GPU-copy "
+"code. These layers are **out of scope** for the storage trace level."
+msgstr "``MPCacheServer``\\ 、消息队列或任何 GPU 拷贝代码内部的调用。这些层 **不在存储追踪级别的采集范围内**\\ 。"
+
+#: ../../source/mp/observability/traces.rst:164
+msgid "File format"
+msgstr "文件格式"
+
+#: ../../source/mp/observability/traces.rst:166
+msgid "A length-prefixed `msgpack <https://msgpack.org/>`_ stream:"
+msgstr "一个长度前缀的 `msgpack <https://msgpack.org/>`_ 流："
+
+#: ../../source/mp/observability/traces.rst:175
+msgid ""
+"The ``Header`` carries a magic prefix (``LMCT``), a format version, the "
+"trace level (``storage`` today), a trace schema version, start "
+"timestamps, and the StorageManagerConfig digest. Each ``Record`` carries "
+"a relative timestamp, a wall-clock timestamp, the fully-qualified call "
+"site (``qualname``), and an argument dict."
+msgstr "``Header`` 包含魔数前缀（\\ ``LMCT``\\ ）、格式版本、追踪级别（当前为 ``storage``\\ ）、追踪 schema 版本、开始时间戳以及 StorageManagerConfig 摘要。每个 ``Record`` 包含相对时间戳、墙钟时间戳、完全限定调用位置（\\ ``qualname``\\ ）和参数字典。"
+
+#: ../../source/mp/observability/traces.rst:181
+msgid ""
+"The format is deliberately extensible: future trace **levels** (``mq``, "
+"``gpu``) will share this layout and use the ``level`` header field to "
+"discriminate. Additional captured ops add new ``qualname`` strings "
+"without bumping the format version."
+msgstr "该格式有意设计为可扩展：未来的追踪 **级别**\\ （\\ ``mq``\\ 、\\ ``gpu``\\ ）将共享此布局，并通过 ``level`` 头字段加以区分。新增捕获的操作只需添加新的 ``qualname`` 字符串，无需升级格式版本。"
+
+#: ../../source/mp/observability/traces.rst:186
+msgid "For the full design rationale see"
+msgstr "有关完整的设计原理，请参见"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/operator.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/operator.po
new file mode 100644
index 0000000..6b66a67
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/operator.po
@@ -0,0 +1,1830 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/operator.rst:2
+msgid "Kubernetes Operator"
+msgstr "Kubernetes Operator"
+
+#: ../../source/mp/operator.rst:4
+msgid ""
+"The LMCache Kubernetes operator automates the deployment and lifecycle "
+"management of LMCache multiprocess servers.  Instead of hand-writing "
+"DaemonSets, Services, and ConfigMaps (as described in the manual "
+":doc:`deployment` guide), you declare a single ``LMCacheEngine`` custom "
+"resource and the operator reconciles all underlying Kubernetes objects."
+msgstr ""
+"LMCache Kubernetes 操作符自动化了 LMCache 多进程服务器的部署和生命周期管理。您只需声明一个 "
+"``LMCacheEngine`` 自定义资源，操作符将协调所有底层的 Kubernetes 对象，而无需手动编写 "
+"DaemonSets、Services 和 ConfigMaps（如手册 :doc:`deployment` 指南中所述）。"
+
+#: ../../source/mp/operator.rst:15
+msgid "Why Use the Operator"
+msgstr "为什么使用 Operator"
+
+#: ../../source/mp/operator.rst:17
+msgid ""
+"The manual DaemonSet approach works, but it has sharp edges the operator "
+"eliminates:"
+msgstr "手动 DaemonSet 方式可以正常工作，但存在一些操作符已消除的陷阱："
+
+#: ../../source/mp/operator.rst:20
+msgid ""
+"**Auto-injected pod settings** -- The operator always sets ``hostIPC: "
+"true`` and ``--host 0.0.0.0``.  Forgetting ``hostIPC`` in a hand-written "
+"manifest causes silent CUDA IPC failures "
+"(``cudaErrorMapBufferObjectFailed``) that are hard to debug."
+msgstr ""
+"**自动注入的 Pod 设置** -- 操作符始终设置 ``hostIPC: true`` 和 ``--host 0.0.0.0``\\ "
+"。在手动编写的清单中忘记 ``hostIPC`` 会导致难以调试的静默 CUDA IPC 失败 （\\ "
+"``cudaErrorMapBufferObjectFailed``\\ ）。"
+
+#: ../../source/mp/operator.rst:24
+msgid ""
+"**Node-local service discovery** -- The operator creates a ClusterIP "
+"Service with ``internalTrafficPolicy=Local`` and a connection ConfigMap "
+"that vLLM pods simply mount.  No ``hostNetwork``, no Downward API, no "
+"shell variable substitution."
+msgstr ""
+"**节点本地服务发现** -- 操作符创建一个 ClusterIP 服务，并设置 "
+"``internalTrafficPolicy=Local``\\ ，同时生成一个连接用 ConfigMap，vLLM Pod 直接挂载即可。无需"
+" ``hostNetwork``\\ ，无需 Downward API，也无需 shell 变量替换。"
+
+#: ../../source/mp/operator.rst:28
+msgid ""
+"**Auto-computed resource sizing** -- Memory requests and limits are "
+"derived from ``l1.sizeGB``, avoiding OOM kills (under-provisioned) or "
+"wasted node capacity (over-provisioned)."
+msgstr "**自动计算资源规格** -- 内存请求和限制由 ``l1.sizeGB`` 推算得出，避免因资源不足导致 OOM 被杀或因资源过剩浪费节点容量。"
+
+#: ../../source/mp/operator.rst:31
+msgid ""
+"**Declarative Prometheus integration** -- Set "
+"``prometheus.serviceMonitor.enabled: true`` and the operator creates a "
+"``ServiceMonitor`` CR that the Prometheus Operator discovers "
+"automatically."
+msgstr ""
+"**声明式 Prometheus 集成** -- 设置 ``prometheus.serviceMonitor.enabled: true``\\"
+" ，操作符会创建一个 ``ServiceMonitor`` CR，Prometheus 操作符会自动发现它。"
+
+#: ../../source/mp/operator.rst:34
+msgid ""
+"**CRD validation** -- OpenAPI schema validation catches misconfigurations"
+" (e.g., ``l1.sizeGB <= 0``, invalid port range) at ``kubectl apply`` "
+"time, before any pods are created."
+msgstr ""
+"**CRD 验证** -- OpenAPI Schema 验证在 ``kubectl apply`` 阶段、Pod 创建之前捕获配置错误（例如 "
+"``l1.sizeGB <= 0``\\ 、端口范围无效等）。"
+
+#: ../../source/mp/operator.rst:39 ../../source/mp/operator.rst:202
+msgid "Prerequisites"
+msgstr "前提条件"
+
+#: ../../source/mp/operator.rst:41
+msgid "Kubernetes 1.20+"
+msgstr "Kubernetes 1.20+"
+
+#: ../../source/mp/operator.rst:42
+msgid "``kubectl`` configured to access your cluster"
+msgstr "``kubectl`` 配置为访问您的集群"
+
+#: ../../source/mp/operator.rst:43
+msgid ""
+"(Optional) `Prometheus Operator <https://github.com/prometheus-operator"
+"/prometheus-operator>`_ for ServiceMonitor support"
+msgstr ""
+"(可选) `Prometheus Operator <https://github.com/prometheus-operator"
+"/prometheus-operator>`_ 以支持 ServiceMonitor"
+
+#: ../../source/mp/operator.rst:47
+msgid "Installing the Operator"
+msgstr "安装 Operator"
+
+#: ../../source/mp/operator.rst:49
+msgid "**Option A: One-line install from release (recommended)**"
+msgstr "**选项 A：从发布版一行安装（推荐）**"
+
+#: ../../source/mp/operator.rst:59
+msgid "**Option B: Build from source**"
+msgstr "**选项 B：从源代码构建**"
+
+#: ../../source/mp/operator.rst:69
+msgid "Deploying an LMCacheEngine"
+msgstr "部署 LMCacheEngine"
+
+#: ../../source/mp/operator.rst:71
+msgid "A minimal CR deploys a DaemonSet with 60 GB L1 cache on every GPU node:"
+msgstr "一个最小的 CR 在每个 GPU 节点上部署一个具有 60 GB L1 缓存的 DaemonSet："
+
+#: ../../source/mp/operator.rst:87
+msgid "The operator automatically:"
+msgstr "操作符自动："
+
+#: ../../source/mp/operator.rst:89
+msgid "Creates a DaemonSet running one LMCache server pod per matched node"
+msgstr "在每个匹配的节点上创建一个运行 LMCache 服务器 Pod 的 DaemonSet"
+
+#: ../../source/mp/operator.rst:90
+msgid "Sets ``hostIPC: true`` and passes ``--host 0.0.0.0`` to the server"
+msgstr "设置 ``hostIPC: true`` 并将 ``--host 0.0.0.0`` 传递给服务器"
+
+#: ../../source/mp/operator.rst:91
+msgid "Creates a node-local ClusterIP Service for vLLM discovery"
+msgstr "为 vLLM 发现创建一个节点本地的 ClusterIP 服务"
+
+#: ../../source/mp/operator.rst:92
+msgid ""
+"Creates a connection ConfigMap (``my-cache-connection``) with the ``kv-"
+"transfer-config`` JSON that vLLM needs"
+msgstr ""
+"创建一个连接 ConfigMap (``my-cache-connection``)，其中包含 vLLM 所需的 ``kv-transfer-"
+"config`` JSON。"
+
+#: ../../source/mp/operator.rst:94
+msgid "Auto-computes resource requests/limits from the L1 cache size"
+msgstr "自动计算 L1 缓存大小的资源请求/限制"
+
+#: ../../source/mp/operator.rst:95
+msgid "Defaults ``nodeSelector`` to ``nvidia.com/gpu.present: \"true\"``"
+msgstr "默认将 ``nodeSelector`` 设置为 ``nvidia.com/gpu.present: \\\"true\\\"``"
+
+#: ../../source/mp/operator.rst:98
+msgid ""
+"The operator defaults the container image to ``lmcache/vllm-"
+"openai:latest``. Override with ``spec.image.repository`` and "
+"``spec.image.tag`` to pin a specific version."
+msgstr ""
+"该操作符将容器镜像默认设置为 ``lmcache/vllm-openai:latest``\\ 。可以通过 "
+"``spec.image.repository`` 和 ``spec.image.tag`` 来覆盖，以固定特定版本。"
+
+#: ../../source/mp/operator.rst:103
+msgid "Connecting vLLM"
+msgstr "连接 vLLM"
+
+#: ../../source/mp/operator.rst:105
+msgid ""
+"The operator creates a ConfigMap named ``<engine-name>-connection`` "
+"containing the ``kv-transfer-config`` JSON.  You can either let the "
+"operator's mutating webhook inject it for you (recommended -- keeps your "
+"vLLM manifest clean) or mount it by hand.  See :ref:`mp-operator-"
+"connection-injection` below for the webhook flow; the rest of this "
+"section describes the manual mount that is its equivalent."
+msgstr "操作符创建一个名为 ``<engine-name>-connection`` 的 ConfigMap，其中包含 ``kv-transfer-config`` JSON。您可以让操作符的变更 webhook 为您注入它（推荐 -- 这样可以保持您的 vLLM 清单整洁），或者手动挂载它。有关 webhook 流程，请参见下面的 :ref:`mp-operator-connection-injection`；本节的其余部分描述了其等效的手动挂载。"
+
+#: ../../source/mp/operator.rst:112
+msgid "Mount it in your vLLM Deployment:"
+msgstr "在你的 vLLM 部署中挂载它："
+
+#: ../../source/mp/operator.rst:162
+msgid "Key requirements for vLLM pods:"
+msgstr "vLLM Pod 的关键要求："
+
+#: ../../source/mp/operator.rst:164
+msgid ""
+"**hostIPC: true** -- CUDA IPC (``cudaIpcOpenMemHandle``) needs a shared "
+"IPC namespace between vLLM and LMCache."
+msgstr ""
+"**hostIPC: true** -- CUDA IPC (``cudaIpcOpenMemHandle``) 需要在 vLLM 和 "
+"LMCache 之间共享 IPC 命名空间。"
+
+#: ../../source/mp/operator.rst:166
+msgid ""
+"**PYTHONHASHSEED=0** -- Ensures deterministic token hashing so vLLM and "
+"LMCache produce consistent cache keys."
+msgstr "**PYTHONHASHSEED=0** -- 确保 Token 哈希的确定性，使 vLLM 与 LMCache 生成一致的缓存键。"
+
+#: ../../source/mp/operator.rst:168
+msgid ""
+"**ConfigMap mount** -- The ``$(cat ...)`` pattern reads the connection "
+"JSON inline.  The ConfigMap name is always ``<LMCacheEngine "
+"name>-connection``."
+msgstr ""
+"**ConfigMap 挂载** -- ``$(cat ...)`` 模式以内联方式读取连接 JSON。ConfigMap 名称始终为 "
+"``<LMCacheEngine name>-connection``\\ 。"
+
+#: ../../source/mp/operator.rst:170
+msgid ""
+"**No hostNetwork needed** -- The operator's node-local Service handles "
+"routing via ``internalTrafficPolicy=Local``."
+msgstr "**无需 hostNetwork** -- 操作符的节点本地服务通过 ``internalTrafficPolicy=Local`` 处理路由。"
+
+#: ../../source/mp/operator.rst:176
+msgid "Connection Injection (Webhook)"
+msgstr "连接注入（Webhook）"
+
+#: ../../source/mp/operator.rst:178
+msgid ""
+"Hand-wiring the ConfigMap mount and the ``$(cat ...)`` argument "
+"substitution above is repetitive across vLLM Deployments.  A **mutating "
+"admission webhook** shipped with the operator can do it for you so the "
+"vLLM manifest stays clean. It mirrors the CacheBlend webhook (see :ref"
+":`mp-operator-cacheblend`) with an ``lmcache-`` annotation/label "
+"discriminator so the two injectors never cross-fire on the same pod."
+msgstr "手动连接 ConfigMap 挂载和 ``$(cat ...)`` 参数替换在 vLLM 部署中是重复的。一个随操作员提供的 **变更入场 webhook** 可以为您完成此操作，从而保持 vLLM 清单的整洁。它镜像了 CacheBlend webhook（参见 :ref:`mp-operator-cacheblend`），并使用 ``lmcache-`` 注释/标签区分符，以便两个注入器不会在同一 pod 上相互干扰。"
+
+#: ../../source/mp/operator.rst:185
+msgid ""
+"When invoked on an opted-in pod whose ``<engine>-connection`` ConfigMap "
+"exists, the webhook mutates the pod at admission time to add:"
+msgstr "当在一个已选择的 pod 上调用且存在 ``<engine>-connection`` ConfigMap 时，webhook 会在入场时修改 pod 以添加："
+
+#: ../../source/mp/operator.rst:188
+msgid ""
+"``--kv-transfer-config <JSON>`` -- the ``LMCacheMPConnector`` config, "
+"read verbatim from the engine's ``<engine>-connection`` ConfigMap and "
+"inlined onto the vLLM container's ``args`` (no volume mount needed);"
+msgstr "``--kv-transfer-config <JSON>`` -- ``LMCacheMPConnector`` 配置，逐字读取自引擎的 ``<engine>-connection`` ConfigMap，并内联到 vLLM 容器的 ``args`` 中（无需卷挂载）；"
+
+#: ../../source/mp/operator.rst:191
+msgid "``hostIPC: true`` on the pod spec (CUDA IPC with the node-local server);"
+msgstr "``hostIPC: true`` 在 pod 规格中（与节点本地服务器的 CUDA IPC）；"
+
+#: ../../source/mp/operator.rst:192
+msgid ""
+"``PYTHONHASHSEED=0`` on the vLLM container env, **set-if-absent** -- it "
+"preserves a value you already set."
+msgstr "``PYTHONHASHSEED=0`` 在 vLLM 容器环境中，**仅在缺失时设置** -- 它保留您已经设置的值。"
+
+#: ../../source/mp/operator.rst:195
+msgid ""
+"Unlike the CacheBlend injector it does **not** consult the engine CR: the"
+" entire connector config lives in the connection ConfigMap, and "
+"``LMCacheEngine`` has no injection sub-spec.  It fails open "
+"(``failurePolicy: Ignore``) and is idempotent (re-admitted pods carrying "
+"the ``lmcache.ai/lmcache-injected`` stamp are allowed unchanged)."
+msgstr "与 CacheBlend 注入器不同，它**不**咨询引擎 CR：整个连接器配置位于连接 ConfigMap 中，``LMCacheEngine`` 没有注入子规范。它在失败时保持开放（``failurePolicy: Ignore``），并且是幂等的（携带 ``lmcache.ai/lmcache-injected`` 标记的重新接纳 Pod 允许保持不变）。"
+
+#: ../../source/mp/operator.rst:204
+msgid ""
+"**cert-manager** + ``make deploy`` (not ``make run``, which is "
+"controller-only and disables the webhook via ``ENABLE_WEBHOOKS=false``) "
+"-- same as the CacheBlend webhook; install once per cluster (see :ref"
+":`mp-operator-cacheblend` \"Additional Prerequisites\")."
+msgstr "**cert-manager** + ``make deploy``（不是 ``make run``，后者仅限控制器并通过 ``ENABLE_WEBHOOKS=false`` 禁用 webhook）-- 与 CacheBlend webhook 相同；每个集群安装一次（请参见 :ref:`mp-operator-cacheblend` \"附加先决条件\"）。"
+
+#: ../../source/mp/operator.rst:208
+msgid ""
+"**Pod Security Standards** -- the injected ``hostIPC`` is rejected by the"
+" ``baseline`` / ``restricted`` PSS profiles, so the vLLM pod's namespace "
+"must be labeled ``pod-security.kubernetes.io/enforce=privileged``."
+msgstr "**Pod 安全标准** -- 注入的 ``hostIPC`` 被 ``baseline`` / ``restricted`` PSS 配置文件拒绝，因此 vLLM pod 的命名空间必须标记为 ``pod-security.kubernetes.io/enforce=privileged``。"
+
+#: ../../source/mp/operator.rst:211
+msgid ""
+"**Engine reconciled in the same namespace** -- the webhook reads the "
+"``<engine>-connection`` ConfigMap directly, so the ``LMCacheEngine`` must"
+" already exist in the vLLM pod's namespace."
+msgstr "**引擎在同一命名空间中协调** -- webhook 直接读取 ``<engine>-connection`` ConfigMap，因此 ``LMCacheEngine`` 必须已经存在于 vLLM pod 的命名空间中。"
+
+#: ../../source/mp/operator.rst:216 ../../source/mp/operator.rst:822
+msgid "Opting a vLLM Pod In"
+msgstr "为 vLLM Pod 启用注入"
+
+#: ../../source/mp/operator.rst:218
+msgid ""
+"Add the opt-in label and the engine-binding annotation to the pod "
+"template, and launch vLLM via the image **ENTRYPOINT** (args only) -- a "
+"``command: [\"/bin/sh\", \"-c\", ...]`` wrapper is skipped (the webhook "
+"stamps ``lmcache.ai/lmcache-skip-reason=command-override`` because "
+"appended args would not reach ``vllm serve``):"
+msgstr "将 opt-in 标签和 engine-binding 注释添加到 pod 模板中，并通过镜像 **ENTRYPOINT** 启动 vLLM（仅参数）-- 跳过 ``command: [\\\"/bin/sh\\\", \\\"-c\\\", ...]`` 包装器（webhook 会标记 ``lmcache.ai/lmcache-skip-reason=command-override``，因为附加的参数不会到达 ``vllm serve``）："
+
+#: ../../source/mp/operator.rst:263
+msgid ""
+"A ready-to-edit manifest lives at "
+"``operator/config/samples/vllm_lmcache_deployment.yaml``."
+msgstr "可编辑的清单位于 ``operator/config/samples/vllm_lmcache_deployment.yaml``。"
+
+#: ../../source/mp/operator.rst:267 ../../source/mp/operator.rst:865
+msgid "Verifying Injection"
+msgstr "验证注入"
+
+#: ../../source/mp/operator.rst:269
+msgid ""
+"The webhook mutates **Pods**, not the Deployment, so inspect a pod (not "
+"the Deployment spec):"
+msgstr "该 webhook 修改的是 **Pods**，而不是 Deployment，因此请检查一个 pod（而不是 Deployment 规格）："
+
+#: ../../source/mp/operator.rst:277
+msgid ""
+"If nothing was injected, check the pod's ``lmcache.ai/lmcache-skip-"
+"reason`` annotation:"
+msgstr "如果没有任何内容被注入，请检查 Pod 的 ``lmcache.ai/lmcache-skip-reason`` 注解："
+
+#: ../../source/mp/operator.rst:280
+msgid ""
+"``command-override`` -- the pod uses a ``sh -c`` wrapper, so injected "
+"args would not reach ``vllm serve``."
+msgstr "``command-override`` -- pod 使用 ``sh -c`` 包装器，因此注入的参数无法到达 ``vllm serve``。"
+
+#: ../../source/mp/operator.rst:282
+msgid ""
+"``kv-transfer-config-present`` -- the user already supplied ``--kv-"
+"transfer-config``; the webhook does not clobber it."
+msgstr "``kv-transfer-config-present`` -- 用户已经提供了 ``--kv-transfer-config``；该 webhook 不会覆盖它。"
+
+#: ../../source/mp/operator.rst:284
+msgid ""
+"``engine-not-found`` -- the ``<engine>-connection`` ConfigMap is missing "
+"(engine not yet reconciled, or wrong namespace, or wrong name)."
+msgstr "``engine-not-found`` -- ``<engine>-connection`` ConfigMap 缺失（引擎尚未协调，或命名空间错误，或名称错误）。"
+
+#: ../../source/mp/operator.rst:286
+msgid ""
+"``target-container-not-found`` -- the ``lmcache.ai/lmcache-container`` "
+"annotation names a container the pod does not have."
+msgstr "``target-container-not-found`` -- ``lmcache.ai/lmcache-container`` 注解指定了一个 pod 中不存在的容器。"
+
+#: ../../source/mp/operator.rst:290
+msgid ""
+"With ``failurePolicy: Ignore`` a webhook / cert problem also leaves the "
+"pod un-mutated silently -- confirm the operator pod is ``Running`` and "
+"the ``MutatingWebhookConfiguration`` exists."
+msgstr "使用 ``failurePolicy: Ignore`` 时，webhook / 证书问题也会使 pod 静默未被修改 -- 确认操作员 pod 处于 ``Running`` 状态，并且 ``MutatingWebhookConfiguration`` 存在。"
+
+#: ../../source/mp/operator.rst:295
+msgid "Verifying the Deployment"
+msgstr "验证部署"
+
+#: ../../source/mp/operator.rst:302
+msgid "Expected output:"
+msgstr "预期输出："
+
+#: ../../source/mp/operator.rst:321
+msgid "CRD Spec Reference"
+msgstr "CRD 规格参考"
+
+#: ../../source/mp/operator.rst:324
+msgid "Image"
+msgstr "镜像"
+
+#: ../../source/mp/operator.rst:330 ../../source/mp/operator.rst:353
+#: ../../source/mp/operator.rst:379 ../../source/mp/operator.rst:393
+#: ../../source/mp/operator.rst:414 ../../source/mp/operator.rst:440
+#: ../../source/mp/operator.rst:455 ../../source/mp/operator.rst:479
+#: ../../source/mp/operator.rst:502 ../../source/mp/operator.rst:635
+#: ../../source/mp/operator.rst:895 ../../source/mp/operator.rst:978
+#: ../../source/mp/operator.rst:999 ../../source/mp/operator.rst:1016
+#: ../../source/mp/operator.rst:1034 ../../source/mp/operator.rst:1054
+#: ../../source/mp/operator.rst:1073 ../../source/mp/operator.rst:1161
+msgid "Field"
+msgstr "字段"
+
+#: ../../source/mp/operator.rst:331 ../../source/mp/operator.rst:354
+#: ../../source/mp/operator.rst:380 ../../source/mp/operator.rst:394
+#: ../../source/mp/operator.rst:415 ../../source/mp/operator.rst:441
+#: ../../source/mp/operator.rst:456 ../../source/mp/operator.rst:480
+#: ../../source/mp/operator.rst:503 ../../source/mp/operator.rst:896
+#: ../../source/mp/operator.rst:979 ../../source/mp/operator.rst:1000
+#: ../../source/mp/operator.rst:1017 ../../source/mp/operator.rst:1035
+#: ../../source/mp/operator.rst:1055 ../../source/mp/operator.rst:1074
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/mp/operator.rst:332 ../../source/mp/operator.rst:355
+#: ../../source/mp/operator.rst:381 ../../source/mp/operator.rst:395
+#: ../../source/mp/operator.rst:416 ../../source/mp/operator.rst:442
+#: ../../source/mp/operator.rst:457 ../../source/mp/operator.rst:481
+#: ../../source/mp/operator.rst:504 ../../source/mp/operator.rst:897
+#: ../../source/mp/operator.rst:980 ../../source/mp/operator.rst:1001
+#: ../../source/mp/operator.rst:1018 ../../source/mp/operator.rst:1036
+#: ../../source/mp/operator.rst:1056 ../../source/mp/operator.rst:1075
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/operator.rst:333
+msgid "``image.repository``"
+msgstr "``image.repository``"
+
+#: ../../source/mp/operator.rst:334
+msgid "``lmcache/vllm-openai``"
+msgstr "``lmcache/vllm-openai``"
+
+#: ../../source/mp/operator.rst:335
+msgid "Container image repository."
+msgstr "容器镜像仓库。"
+
+#: ../../source/mp/operator.rst:336
+msgid "``image.tag``"
+msgstr "``image.tag``"
+
+#: ../../source/mp/operator.rst:337
+msgid "``latest``"
+msgstr "``latest``"
+
+#: ../../source/mp/operator.rst:338
+msgid "Container image tag."
+msgstr "容器镜像标签。"
+
+#: ../../source/mp/operator.rst:339
+msgid "``image.pullPolicy``"
+msgstr "``image.pullPolicy``"
+
+#: ../../source/mp/operator.rst:340
+msgid "``IfNotPresent``"
+msgstr "``IfNotPresent``"
+
+#: ../../source/mp/operator.rst:341
+msgid "``Always``, ``Never``, or ``IfNotPresent``."
+msgstr "``Always``, ``Never``, 或 ``IfNotPresent``\\ 。"
+
+#: ../../source/mp/operator.rst:342 ../../source/mp/operator.rst:988
+msgid "``imagePullSecrets``"
+msgstr "``imagePullSecrets``"
+
+#: ../../source/mp/operator.rst:343 ../../source/mp/operator.rst:430
+#: ../../source/mp/operator.rst:444 ../../source/mp/operator.rst:486
+#: ../../source/mp/operator.rst:489 ../../source/mp/operator.rst:492
+#: ../../source/mp/operator.rst:509 ../../source/mp/operator.rst:512
+#: ../../source/mp/operator.rst:515 ../../source/mp/operator.rst:518
+#: ../../source/mp/operator.rst:521 ../../source/mp/operator.rst:524
+#: ../../source/mp/operator.rst:527 ../../source/mp/operator.rst:530
+#: ../../source/mp/operator.rst:910 ../../source/mp/operator.rst:989
+#: ../../source/mp/operator.rst:1092 ../../source/mp/operator.rst:1096
+#: ../../source/mp/operator.rst:1099 ../../source/mp/operator.rst:1102
+msgid "--"
+msgstr "--"
+
+#: ../../source/mp/operator.rst:344 ../../source/mp/operator.rst:990
+msgid "Image pull secret references."
+msgstr "镜像拉取密钥引用。"
+
+#: ../../source/mp/operator.rst:347
+msgid "Server"
+msgstr "服务器"
+
+#: ../../source/mp/operator.rst:356 ../../source/mp/operator.rst:645
+msgid "``server.port``"
+msgstr "``server.port``"
+
+#: ../../source/mp/operator.rst:357
+msgid "``5555``"
+msgstr "``5555``"
+
+#: ../../source/mp/operator.rst:358
+msgid "ZMQ listening port (1024--65535)."
+msgstr "ZMQ 监听端口 (1024--65535)。"
+
+#: ../../source/mp/operator.rst:359
+msgid "``server.chunkSize``"
+msgstr "``server.chunkSize``"
+
+#: ../../source/mp/operator.rst:360 ../../source/mp/operator.rst:1058
+msgid "``256``"
+msgstr "``256``"
+
+#: ../../source/mp/operator.rst:361
+msgid "Token chunk size."
+msgstr "Token 分块大小。"
+
+#: ../../source/mp/operator.rst:362
+msgid "``server.maxWorkers``"
+msgstr "``server.maxWorkers``"
+
+#: ../../source/mp/operator.rst:363 ../../source/mp/operator.rst:899
+#: ../../source/mp/operator.rst:982 ../../source/mp/operator.rst:1062
+msgid "``1``"
+msgstr "``1``"
+
+#: ../../source/mp/operator.rst:364
+msgid "Worker threads for ZMQ requests."
+msgstr "ZMQ 请求的工作线程。"
+
+#: ../../source/mp/operator.rst:365
+msgid "``server.hashAlgorithm``"
+msgstr "``server.hashAlgorithm``"
+
+#: ../../source/mp/operator.rst:366
+msgid "``blake3``"
+msgstr "``blake3``"
+
+#: ../../source/mp/operator.rst:367
+msgid "``builtin``, ``sha256_cbor``, or ``blake3``."
+msgstr "``builtin``, ``sha256_cbor``, 或 ``blake3``\\ 。"
+
+#: ../../source/mp/operator.rst:368
+msgid "``server.httpPort``"
+msgstr "``server.httpPort``"
+
+#: ../../source/mp/operator.rst:369
+msgid "``8080``"
+msgstr "``8080``"
+
+#: ../../source/mp/operator.rst:370
+msgid "HTTP frontend port for health checks and cache admin (1024--65535)."
+msgstr "健康检查和缓存管理的 HTTP 前端端口（1024--65535）。"
+
+#: ../../source/mp/operator.rst:373
+msgid "L1 Cache"
+msgstr "L1 缓存"
+
+#: ../../source/mp/operator.rst:382 ../../source/mp/operator.rst:637
+msgid "``l1.sizeGB``"
+msgstr "``l1.sizeGB``"
+
+#: ../../source/mp/operator.rst:383 ../../source/mp/operator.rst:905
+msgid "*required*"
+msgstr "必需"
+
+#: ../../source/mp/operator.rst:384
+msgid "L1 cache size in GB.  Must be > 0."
+msgstr "L1 缓存大小（以 GB 为单位）。必须大于 0。"
+
+#: ../../source/mp/operator.rst:387
+msgid "Eviction"
+msgstr "逐出"
+
+#: ../../source/mp/operator.rst:396 ../../source/mp/operator.rst:639
+msgid "``eviction.policy``"
+msgstr "``eviction.policy``"
+
+#: ../../source/mp/operator.rst:397
+msgid "``LRU``"
+msgstr "``LRU``"
+
+#: ../../source/mp/operator.rst:398
+msgid ""
+"``LRU`` or ``noop``.  Use ``noop`` with ``l2Backend.storePolicy: "
+"skip_l1`` for buffer-only mode."
+msgstr ""
+"``LRU`` 或 ``noop``。在仅缓冲模式下，使用 ``noop`` 和 ``l2Backend.storePolicy: "
+"skip_l1``。"
+
+#: ../../source/mp/operator.rst:400 ../../source/mp/operator.rst:641
+msgid "``eviction.triggerWatermark``"
+msgstr "``eviction.triggerWatermark``"
+
+#: ../../source/mp/operator.rst:401
+msgid "``0.8``"
+msgstr "``0.8``"
+
+#: ../../source/mp/operator.rst:402
+msgid "Usage ratio (0.0--1.0] to trigger eviction."
+msgstr "触发逐出的使用比例 (0.0--1.0]。"
+
+#: ../../source/mp/operator.rst:403 ../../source/mp/operator.rst:643
+msgid "``eviction.evictionRatio``"
+msgstr "``eviction.evictionRatio``"
+
+#: ../../source/mp/operator.rst:404 ../../source/mp/operator.rst:1041
+msgid "``0.2``"
+msgstr "``0.2``"
+
+#: ../../source/mp/operator.rst:405
+msgid "Fraction to evict (0.0--1.0]."
+msgstr "逐出比例 (0.0--1.0]。"
+
+#: ../../source/mp/operator.rst:408 ../../source/mp/operator.rst:1203
+msgid "Prometheus"
+msgstr "Prometheus"
+
+#: ../../source/mp/operator.rst:417 ../../source/mp/operator.rst:1076
+msgid "``prometheus.enabled``"
+msgstr "``prometheus.enabled``"
+
+#: ../../source/mp/operator.rst:418 ../../source/mp/operator.rst:1077
+msgid "``true``"
+msgstr "``true``"
+
+#: ../../source/mp/operator.rst:419
+msgid "Expose Prometheus metrics."
+msgstr "对外暴露 Prometheus 指标。"
+
+#: ../../source/mp/operator.rst:420 ../../source/mp/operator.rst:1079
+msgid "``prometheus.port``"
+msgstr "``prometheus.port``"
+
+#: ../../source/mp/operator.rst:421 ../../source/mp/operator.rst:1080
+msgid "``9090``"
+msgstr "``9090``"
+
+#: ../../source/mp/operator.rst:422
+msgid "``/metrics`` endpoint port."
+msgstr "``/metrics`` 端点端口。"
+
+#: ../../source/mp/operator.rst:423 ../../source/mp/operator.rst:1082
+msgid "``prometheus.serviceMonitor.enabled``"
+msgstr "``prometheus.serviceMonitor.enabled``"
+
+#: ../../source/mp/operator.rst:424 ../../source/mp/operator.rst:463
+#: ../../source/mp/operator.rst:1083
+msgid "``false``"
+msgstr "``false``"
+
+#: ../../source/mp/operator.rst:425
+msgid "Create a ServiceMonitor CR."
+msgstr "创建一个 ServiceMonitor CR。"
+
+#: ../../source/mp/operator.rst:426 ../../source/mp/operator.rst:1085
+msgid "``prometheus.serviceMonitor.interval``"
+msgstr "``prometheus.serviceMonitor.interval``"
+
+#: ../../source/mp/operator.rst:427 ../../source/mp/operator.rst:1086
+msgid "``30s``"
+msgstr "``30s``"
+
+#: ../../source/mp/operator.rst:428 ../../source/mp/operator.rst:1087
+msgid "Scrape interval."
+msgstr "抓取间隔。"
+
+#: ../../source/mp/operator.rst:429
+msgid "``prometheus.serviceMonitor.labels``"
+msgstr "``prometheus.serviceMonitor.labels``"
+
+#: ../../source/mp/operator.rst:431
+msgid "Extra labels on the ServiceMonitor."
+msgstr "ServiceMonitor 上的附加标签。"
+
+#: ../../source/mp/operator.rst:434
+msgid "L2 Storage"
+msgstr "L2 存储"
+
+#: ../../source/mp/operator.rst:443
+msgid "``l2Backend``"
+msgstr "``l2Backend``"
+
+#: ../../source/mp/operator.rst:445
+msgid "List of L2 backends (``type`` + ``config``). See :doc:`l2_storage/index`."
+msgstr "L2 后端列表 (``type`` + ``config``)。请参阅 :doc:`l2_storage/index`。"
+
+#: ../../source/mp/operator.rst:449
+msgid "GPU & Security"
+msgstr "GPU 和安全性"
+
+#: ../../source/mp/operator.rst:458
+msgid "``gpuVendor``"
+msgstr "``gpuVendor``"
+
+#: ../../source/mp/operator.rst:459
+msgid "``nvidia``"
+msgstr "``nvidia``"
+
+#: ../../source/mp/operator.rst:460
+msgid ""
+"GPU vendor: ``nvidia`` (uses the ``nvidia`` RuntimeClass) or ``amd`` "
+"(runs on the default runtime)."
+msgstr "GPU 供应商：``nvidia``（使用 ``nvidia`` RuntimeClass）或 ``amd``（在默认运行时上运行）。"
+
+#: ../../source/mp/operator.rst:462
+msgid "``privileged``"
+msgstr "``privileged``"
+
+#: ../../source/mp/operator.rst:464
+msgid ""
+"Run the engine container in privileged mode. On most clusters "
+"``runtimeClassName: nvidia`` + ``NVIDIA_VISIBLE_DEVICES=all`` already "
+"grant GPU visibility without it; set ``true`` only where the engine "
+"cannot otherwise see the GPUs. Required for ``gpuVendor: amd`` (no "
+"RuntimeClass device injection, so privileged is the only path to "
+"``/dev/kfd``/``/dev/dri``). Enabling it requires the namespace to allow "
+"the ``privileged`` Pod Security Standard."
+msgstr "在特权模式下运行引擎容器。在大多数集群中，``runtimeClassName: nvidia`` + ``NVIDIA_VISIBLE_DEVICES=all`` 已经可以在没有它的情况下授予 GPU 可见性；仅在引擎无法看到 GPU 的情况下设置为 ``true``。对于 ``gpuVendor: amd`` 是必需的（没有 RuntimeClass 设备注入，因此特权是访问 ``/dev/kfd``/``/dev/dri`` 的唯一途径）。启用它需要命名空间允许 ``privileged`` Pod 安全标准。"
+
+#: ../../source/mp/operator.rst:473
+msgid "Scheduling"
+msgstr "调度"
+
+#: ../../source/mp/operator.rst:482
+msgid "``nodeSelector``"
+msgstr "``nodeSelector``"
+
+#: ../../source/mp/operator.rst:483
+msgid "GPU nodes"
+msgstr "GPU 节点"
+
+#: ../../source/mp/operator.rst:484
+msgid "Defaults to ``nvidia.com/gpu.present: \"true\"``."
+msgstr "默认为 ``nvidia.com/gpu.present: \\\"true\\\"``\\ 。"
+
+#: ../../source/mp/operator.rst:485
+msgid "``affinity``"
+msgstr "``affinity``"
+
+#: ../../source/mp/operator.rst:487
+msgid "Pod affinity rules."
+msgstr "Pod 亲和性规则。"
+
+#: ../../source/mp/operator.rst:488
+msgid "``tolerations``"
+msgstr "``tolerations``"
+
+#: ../../source/mp/operator.rst:490
+msgid "Pod tolerations."
+msgstr "Pod 容忍度规则。"
+
+#: ../../source/mp/operator.rst:491
+msgid "``priorityClassName``"
+msgstr "``priorityClassName``"
+
+#: ../../source/mp/operator.rst:493
+msgid "Priority class for pods."
+msgstr "用于 Pods 的优先级类。"
+
+#: ../../source/mp/operator.rst:496
+msgid "Overrides & Extras"
+msgstr "覆盖与额外选项"
+
+#: ../../source/mp/operator.rst:505 ../../source/mp/operator.rst:1088
+msgid "``logLevel``"
+msgstr "``logLevel``"
+
+#: ../../source/mp/operator.rst:506 ../../source/mp/operator.rst:1089
+msgid "``INFO``"
+msgstr "``INFO``"
+
+#: ../../source/mp/operator.rst:507
+msgid "``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``."
+msgstr "``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``\\ 。"
+
+#: ../../source/mp/operator.rst:508 ../../source/mp/operator.rst:1091
+msgid "``resourceOverrides``"
+msgstr "``resourceOverrides``"
+
+#: ../../source/mp/operator.rst:510
+msgid "Override auto-computed resources."
+msgstr "覆盖自动计算的资源。"
+
+#: ../../source/mp/operator.rst:511
+msgid "``env``"
+msgstr "``env``"
+
+#: ../../source/mp/operator.rst:513
+msgid "Extra environment variables."
+msgstr "额外的环境变量。"
+
+#: ../../source/mp/operator.rst:514
+msgid "``volumes``"
+msgstr "``volumes``"
+
+#: ../../source/mp/operator.rst:516
+msgid "Extra volumes."
+msgstr "额外的卷。"
+
+#: ../../source/mp/operator.rst:517
+msgid "``volumeMounts``"
+msgstr "``volumeMounts``"
+
+#: ../../source/mp/operator.rst:519
+msgid "Extra volume mounts."
+msgstr "额外的卷挂载。"
+
+#: ../../source/mp/operator.rst:520
+msgid "``podAnnotations``"
+msgstr "``podAnnotations``"
+
+#: ../../source/mp/operator.rst:522
+msgid "Extra pod annotations."
+msgstr "额外的 Pod 注解。"
+
+#: ../../source/mp/operator.rst:523
+msgid "``podLabels``"
+msgstr "``podLabels``"
+
+#: ../../source/mp/operator.rst:525
+msgid "Extra pod labels."
+msgstr "额外的 Pod 标签。"
+
+#: ../../source/mp/operator.rst:526
+msgid "``serviceAccountName``"
+msgstr "``serviceAccountName``"
+
+#: ../../source/mp/operator.rst:528
+msgid "ServiceAccount for pods."
+msgstr "Pod 使用的 ServiceAccount。"
+
+#: ../../source/mp/operator.rst:529 ../../source/mp/operator.rst:1101
+msgid "``extraArgs``"
+msgstr "``extraArgs``"
+
+#: ../../source/mp/operator.rst:531
+msgid "Extra CLI flags (appended last, can override)."
+msgstr "额外的 CLI 标志（最后附加，可以覆盖）。"
+
+#: ../../source/mp/operator.rst:534
+msgid "Auto-Computed Resources"
+msgstr "自动计算资源"
+
+#: ../../source/mp/operator.rst:536
+msgid ""
+"When ``spec.resourceOverrides`` is not set, the operator derives "
+"resources from ``l1.sizeGB``:"
+msgstr "当 ``spec.resourceOverrides`` 未设置时，操作符从 ``l1.sizeGB`` 派生资源："
+
+#: ../../source/mp/operator.rst:539
+msgid "**CPU request**: ``4`` cores"
+msgstr "**CPU 请求**: ``4`` 核心"
+
+#: ../../source/mp/operator.rst:540
+msgid "**Memory request**: ``ceil(l1.sizeGB + 5)`` Gi"
+msgstr "**内存请求**: ``ceil(l1.sizeGB + 5)`` Gi"
+
+#: ../../source/mp/operator.rst:541
+msgid "**Memory limit**: ``ceil(memoryRequest * 1.5)`` Gi"
+msgstr "**内存限制**: ``ceil(memoryRequest * 1.5)`` Gi"
+
+#: ../../source/mp/operator.rst:543
+msgid "For example, ``l1.sizeGB: 60`` produces a 65 Gi request and 98 Gi limit."
+msgstr "例如，\\ ``l1.sizeGB: 60`` 会产生 65 Gi 的请求和 98 Gi 的限制。"
+
+#: ../../source/mp/operator.rst:546
+msgid "Auto-Injected Pod Settings"
+msgstr "自动注入的 Pod 设置"
+
+#: ../../source/mp/operator.rst:548
+msgid ""
+"The operator always injects these into the pod spec (they are not "
+"configurable via the CRD):"
+msgstr "操作符始终将这些注入到 Pod 规格中（它们无法通过 CRD 配置）："
+
+#: ../../source/mp/operator.rst:551
+msgid "**hostIPC: true** -- Required for CUDA IPC between LMCache and vLLM."
+msgstr "**hostIPC: true** -- 这是在 LMCache 和 vLLM 之间进行 CUDA IPC 所必需的。"
+
+#: ../../source/mp/operator.rst:552
+msgid ""
+"**--host 0.0.0.0** -- Binds the server to all interfaces so the node-"
+"local Service can route to it."
+msgstr "**--host 0.0.0.0** -- 将服务器绑定到所有接口，以便节点本地服务可以路由到它。"
+
+#: ../../source/mp/operator.rst:554
+msgid ""
+"**NVIDIA_VISIBLE_DEVICES=all** -- Ensures GPU access for IPC-based memory"
+" transfers."
+msgstr "**NVIDIA_VISIBLE_DEVICES=all** -- 确保 GPU 可用于基于 IPC 的内存传输。"
+
+#: ../../source/mp/operator.rst:556
+msgid ""
+"**NVIDIA_DRIVER_CAPABILITIES=all** -- Exposes all driver capabilities "
+"(compute, utility, etc.) to the container."
+msgstr "**NVIDIA_DRIVER_CAPABILITIES=all** -- 将所有驱动程序功能（计算、实用程序等）暴露给容器。"
+
+#: ../../source/mp/operator.rst:558
+msgid ""
+"**TCP socket probes** -- Startup (5s initial, 30 failures), liveness "
+"(10s), and readiness (5s) probes on the server port."
+msgstr "**TCP socket 探测** -- 启动（初始 5 秒，30 次失败）、存活（10 秒）和就绪（5 秒）探测在服务器端口上。"
+
+#: ../../source/mp/operator.rst:562
+msgid ""
+"The operator does **not** mount an emptyDir at ``/dev/shm``.  With "
+"``hostIPC: true``, the container sees the host's ``/dev/shm`` directly. "
+"Mounting an emptyDir would shadow it with a private tmpfs and break CUDA "
+"IPC."
+msgstr ""
+"操作符\\ **不**\\ 在 ``/dev/shm`` 挂载 emptyDir。使用 ``hostIPC: true`` 时，容器直接访问主机的"
+" ``/dev/shm``\\ 。挂载 emptyDir 会用私有 tmpfs 进行遮蔽，从而破坏 CUDA IPC。"
+
+#: ../../source/mp/operator.rst:567
+msgid "Resources Created"
+msgstr "创建的资源"
+
+#: ../../source/mp/operator.rst:569
+msgid "For an ``LMCacheEngine`` named ``my-cache``:"
+msgstr "对于名为 ``my-cache`` 的 ``LMCacheEngine``\\ ："
+
+#: ../../source/mp/operator.rst:575 ../../source/mp/operator.rst:1119
+msgid "Resource"
+msgstr "资源"
+
+#: ../../source/mp/operator.rst:576 ../../source/mp/operator.rst:1120
+msgid "Name"
+msgstr "名称"
+
+#: ../../source/mp/operator.rst:577 ../../source/mp/operator.rst:1121
+msgid "Purpose"
+msgstr "目的"
+
+#: ../../source/mp/operator.rst:578
+msgid "DaemonSet"
+msgstr "DaemonSet"
+
+#: ../../source/mp/operator.rst:579 ../../source/mp/operator.rst:582
+#: ../../source/mp/operator.rst:591
+msgid "``my-cache``"
+msgstr "``my-cache``"
+
+#: ../../source/mp/operator.rst:580
+msgid "Runs LMCache server pods."
+msgstr "运行 LMCache 服务器 Pod。"
+
+#: ../../source/mp/operator.rst:581 ../../source/mp/operator.rst:1125
+msgid "Service (ClusterIP)"
+msgstr "服务 (ClusterIP)"
+
+#: ../../source/mp/operator.rst:583
+msgid "Node-local discovery (``internalTrafficPolicy=Local``)."
+msgstr "节点本地发现（\\ ``internalTrafficPolicy=Local``\\ ）。"
+
+#: ../../source/mp/operator.rst:584 ../../source/mp/operator.rst:1128
+msgid "Service (headless)"
+msgstr "无头服务"
+
+#: ../../source/mp/operator.rst:585
+msgid "``my-cache-metrics``"
+msgstr "``my-cache-metrics``"
+
+#: ../../source/mp/operator.rst:586
+msgid "Prometheus scrape target."
+msgstr "Prometheus 抓取目标。"
+
+#: ../../source/mp/operator.rst:587
+msgid "ConfigMap"
+msgstr "ConfigMap"
+
+#: ../../source/mp/operator.rst:588
+msgid "``my-cache-connection``"
+msgstr "``my-cache-connection``"
+
+#: ../../source/mp/operator.rst:589
+msgid "``kv-transfer-config`` JSON for vLLM."
+msgstr "供 vLLM 使用的 ``kv-transfer-config`` JSON。"
+
+#: ../../source/mp/operator.rst:590 ../../source/mp/operator.rst:1131
+msgid "ServiceMonitor"
+msgstr "ServiceMonitor"
+
+#: ../../source/mp/operator.rst:592
+msgid "Prometheus Operator integration (when enabled)."
+msgstr "启用后由 Prometheus Operator 集成使用。"
+
+#: ../../source/mp/operator.rst:594
+msgid "The connection ConfigMap contains:"
+msgstr "连接 ConfigMap 包含："
+
+#: ../../source/mp/operator.rst:608
+msgid "Status & Conditions"
+msgstr "状态与条件"
+
+#: ../../source/mp/operator.rst:614 ../../source/mp/operator.rst:1142
+msgid "The status section includes:"
+msgstr "状态部分包括："
+
+#: ../../source/mp/operator.rst:616 ../../source/mp/operator.rst:1144
+msgid "**phase**: ``Pending``, ``Running``, ``Degraded``, or ``Failed``."
+msgstr ""
+"**phase**: ``Pending``\\ 、\\ ``Running``\\ 、\\ ``Degraded`` 或 "
+"``Failed``\\ 。"
+
+#: ../../source/mp/operator.rst:617
+msgid "**readyInstances** / **desiredInstances**: Instance counts."
+msgstr "**readyInstances** / **desiredInstances**: 实例计数。"
+
+#: ../../source/mp/operator.rst:618
+msgid ""
+"**endpoints**: Per-node connection info (node name, host IP, pod name, "
+"port, readiness)."
+msgstr "**endpoints**: 每个节点的连接信息（节点名称、主机 IP、Pod 名称、端口、就绪状态）。"
+
+#: ../../source/mp/operator.rst:620 ../../source/mp/operator.rst:1148
+msgid "**conditions**:"
+msgstr "**条件**\\ ："
+
+#: ../../source/mp/operator.rst:622
+msgid "``Available`` -- At least one instance is ready."
+msgstr "``Available`` -- 至少有一个实例已就绪。"
+
+#: ../../source/mp/operator.rst:623
+msgid "``AllInstancesReady`` -- All desired instances are ready."
+msgstr "``AllInstancesReady`` -- 所有预期实例均已就绪。"
+
+#: ../../source/mp/operator.rst:624 ../../source/mp/operator.rst:1152
+msgid "``ConfigValid`` -- Spec validation passed."
+msgstr "``ConfigValid`` -- Spec 验证通过。"
+
+#: ../../source/mp/operator.rst:627
+msgid "Validation Rules"
+msgstr "验证规则"
+
+#: ../../source/mp/operator.rst:629
+msgid "The operator validates the CR spec at apply time:"
+msgstr "操作符在 apply 时验证 CR 的 Spec："
+
+#: ../../source/mp/operator.rst:636 ../../source/mp/operator.rst:1162
+msgid "Rule"
+msgstr "规则"
+
+#: ../../source/mp/operator.rst:638
+msgid "Required, must be > 0."
+msgstr "必需，必须 > 0。"
+
+#: ../../source/mp/operator.rst:640
+msgid "Must be ``LRU`` or ``noop`` (if set)."
+msgstr "必须是 ``LRU`` 或 ``noop``（如果设置）。"
+
+#: ../../source/mp/operator.rst:642 ../../source/mp/operator.rst:644
+#: ../../source/mp/operator.rst:1174
+msgid "Must be in (0.0, 1.0]."
+msgstr "必须在 (0.0, 1.0] 之间。"
+
+#: ../../source/mp/operator.rst:646
+msgid "Must be in [1024, 65535]."
+msgstr "必须在 [1024, 65535] 之间。"
+
+#: ../../source/mp/operator.rst:649
+msgid "Examples"
+msgstr "示例"
+
+#: ../../source/mp/operator.rst:652
+msgid "Target Only GPU Nodes"
+msgstr "仅针对 GPU 节点"
+
+#: ../../source/mp/operator.rst:654
+msgid ""
+"Use ``nodeSelector`` to run LMCache only on GPU nodes.  New GPU nodes "
+"automatically get an LMCache pod:"
+msgstr ""
+"使用 ``nodeSelector`` 将 LMCache 限定在 GPU 节点上运行。新加入的 GPU 节点会自动获得一个 LMCache "
+"Pod："
+
+#: ../../source/mp/operator.rst:670
+msgid ""
+"The operator defaults ``nodeSelector`` to ``nvidia.com/gpu.present: "
+"\"true\"`` when not specified, so a minimal CR already targets GPU nodes."
+msgstr ""
+"当未指定时，操作符默认将 ``nodeSelector`` 设置为 ``nvidia.com/gpu.present: "
+"\\\"true\\\"``\\ ，因此最小化的 CR 默认已针对 GPU 节点。"
+
+#: ../../source/mp/operator.rst:674
+msgid "Custom Server Port"
+msgstr "自定义服务器端口"
+
+#: ../../source/mp/operator.rst:676
+msgid "If the default port (5555) conflicts with other services:"
+msgstr "如果默认端口（5555）与其他服务冲突："
+
+#: ../../source/mp/operator.rst:690
+msgid ""
+"The connection ConfigMap updates automatically -- vLLM pods pick up the "
+"new port on restart."
+msgstr "连接 ConfigMap 会自动更新 —— vLLM Pod 重启后即可使用新端口。"
+
+#: ../../source/mp/operator.rst:694
+msgid "Production with Prometheus Monitoring"
+msgstr "集成 Prometheus 监控的生产环境配置"
+
+#: ../../source/mp/operator.rst:730
+msgid "See :doc:`observability/index` for metric names and Grafana configuration."
+msgstr "请参阅 :doc:`observability/index` 以获取指标名称和 Grafana 配置。"
+
+#: ../../source/mp/operator.rst:733
+msgid "Override Auto-Computed Resources"
+msgstr "覆盖自动计算的资源"
+
+#: ../../source/mp/operator.rst:754
+msgid "CacheBlend"
+msgstr "CacheBlend"
+
+#: ../../source/mp/operator.rst:756
+msgid ""
+"CacheBlend reuses cached KV at shifted (non-prefix) positions by "
+"recomputing a small subset of tokens.  The operator manages it as a "
+"second CRD, ``CacheBlendEngine``, plus a **mutating admission webhook** "
+"that injects the pure-Python ``lmcache-cacheblend`` vLLM plugin into your"
+" serving pods -- so you do **not** rebuild the vLLM image.  See "
+":doc:`/kv_cache_optimizations/blending` for the technique itself."
+msgstr ""
+"CacheBlend 通过重新计算一小部分 Token 来复用偏移（非前缀）位置的缓存 KV。该操作符将其作为第二个 CRD "
+"``CacheBlendEngine`` 进行管理，并通过一个 **变更准入 Webhook** 将纯 Python 的 ``lmcache-"
+"cacheblend`` vLLM 插件注入到您的服务 Pod 中，因此您 **无需** 重新构建 vLLM 镜像。有关该技术的详细信息，请参见 "
+":doc:`/kv_cache_optimizations/blending`。"
+
+#: ../../source/mp/operator.rst:763
+msgid "It has two halves the operator runs together:"
+msgstr "它由两个部分组成，操作符同时管理它们："
+
+#: ../../source/mp/operator.rst:765
+msgid ""
+"a GPU-resident CacheBlend V3 engine (``lmcache server --engine-type "
+"blend``), deployed as a DaemonSet with the **same GPU model as** "
+"``LMCacheEngine`` (``runtimeClassName: nvidia`` + "
+"``NVIDIA_VISIBLE_DEVICES=all`` + ``hostIPC``, plus ``privileged`` when "
+"``spec.privileged`` is set, and **no** ``nvidia.com/gpu`` claim) so it "
+"shares the vLLM GPU for same-device CUDA IPC; and"
+msgstr "一个驻留在 GPU 上的 CacheBlend V3 引擎 (``lmcache server --engine-type blend``)，作为 DaemonSet 部署，**与** ``LMCacheEngine`` **相同的 GPU 型号** (``runtimeClassName: nvidia`` + ``NVIDIA_VISIBLE_DEVICES=all`` + ``hostIPC``，当设置了 ``spec.privileged`` 时加上 ``privileged``，并且**没有** ``nvidia.com/gpu`` 声明)，以便共享同设备的 CUDA IPC 的 vLLM GPU；并且"
+
+#: ../../source/mp/operator.rst:771
+msgid "the vLLM-side plugin, injected into opted-in pods by the webhook."
+msgstr "vLLM 侧插件，由 Webhook 注入到已选择启用的 Pod 中。"
+
+#: ../../source/mp/operator.rst:774
+msgid "Additional Prerequisites"
+msgstr "附加先决条件"
+
+#: ../../source/mp/operator.rst:776
+msgid "Beyond the operator prerequisites above:"
+msgstr "除上述操作符前提条件外，还需满足："
+
+#: ../../source/mp/operator.rst:778
+msgid ""
+"**cert-manager** -- the webhook's serving certificate is issued by a "
+"cert-manager ``Issuer`` + ``Certificate``.  Install it before ``make "
+"deploy``:"
+msgstr ""
+"**cert-manager** -- webhook 的服务证书由 cert-manager ``Issuer`` + "
+"``Certificate`` 颁发。在 ``make deploy`` 之前安装它："
+
+#: ../../source/mp/operator.rst:786
+msgid ""
+"**Deploy with the webhook** -- use ``make deploy`` (not ``make run``, "
+"which is controller-only and disables the webhook via "
+"``ENABLE_WEBHOOKS=false``)."
+msgstr ""
+"**使用 Webhook 部署** -- 使用 ``make deploy``\\ （而不是 ``make run``\\ ，后者仅为控制器并通过"
+" ``ENABLE_WEBHOOKS=false`` 禁用 Webhook）。"
+
+#: ../../source/mp/operator.rst:788
+msgid ""
+"**Pod Security Standards** -- the webhook injects "
+"``hostIPC``/``privileged``, which the ``baseline``/``restricted`` "
+"profiles reject, so label the engine's and the vLLM pod's namespaces "
+"``pod-security.kubernetes.io/enforce=privileged``."
+msgstr ""
+"**Pod 安全标准** -- webhook 注入 ``hostIPC``/``privileged``\\ ，而 "
+"``baseline``/``restricted`` 配置文件会拒绝这些，因此将引擎和 vLLM pod 的命名空间标记为 ``pod-"
+"security.kubernetes.io/enforce=privileged``\\ 。"
+
+#: ../../source/mp/operator.rst:793
+msgid "Deploying a CacheBlendEngine"
+msgstr "部署 CacheBlendEngine"
+
+#: ../../source/mp/operator.rst:816
+msgid ""
+"The engine runs ``lmcache server --engine-type blend`` as a DaemonSet and"
+" emits a ``my-cacheblend-connection`` ConfigMap with the "
+"``CBKVConnector`` ``kv-transfer-config`` (the operator wires the node-"
+"local Service host/port and the ``cb.*`` tunables)."
+msgstr ""
+"该引擎以 DaemonSet 方式运行 ``lmcache server --engine-type blend``\\ ，并生成一个包含 "
+"``CBKVConnector`` ``kv-transfer-config`` 的 ``my-cacheblend-connection`` "
+"ConfigMap（操作符将节点本地服务的主机/端口和 ``cb.*`` 可调参数连接起来）。"
+
+#: ../../source/mp/operator.rst:824
+msgid ""
+"Label the pod template for the webhook and bind it to an engine by name."
+"  Launch vLLM via the image **ENTRYPOINT** (args only) -- a ``command: "
+"[\"/bin/sh\", \"-c\", ...]`` wrapper is skipped, since appended args "
+"would not reach ``vllm serve``:"
+msgstr ""
+"为 Pod 模板打上 webhook 所需的标签，并按名称将其绑定到引擎。通过镜像 **ENTRYPOINT** 启动 "
+"vLLM（仅传参数）——应跳过 ``command: [\\\"/bin/sh\\\", \\\"-c\\\", ...]`` "
+"包装器，否则附加的参数无法传递给 ``vllm serve``\\ ："
+
+#: ../../source/mp/operator.rst:857
+msgid ""
+"The webhook injects the plugin init container, ``PYTHONPATH``, "
+"``hostIPC``, the private-image pull secret, and the required CacheBlend "
+"vLLM flags (``--attention-backend CUSTOM``, ``--kv-transfer-config`` from"
+" the engine's connection ConfigMap, ``--block-size 64``, ``--pipeline-"
+"parallel-size 1``, ``--no-enable-chunked-prefill``, ``--no-async-"
+"scheduling``, ``--enforce-eager``). You supply only the model and your "
+"non-CacheBlend flags."
+msgstr ""
+"Webhook 注入插件初始化容器、\\ ``PYTHONPATH``\\ 、\\ ``hostIPC``\\ 、私有镜像拉取密钥，以及所需的 "
+"CacheBlend vLLM 标志（\\ ``--attention-backend CUSTOM``\\ 、\\ ``--kv-"
+"transfer-config`` 来自引擎的连接 ConfigMap、\\ ``--block-size 64``\\ 、\\ "
+"``--pipeline-parallel-size 1``\\ 、\\ ``--no-enable-chunked-prefill``\\ "
+"、\\ ``--no-async-scheduling``\\ 、\\ ``--enforce-eager``\\ ）。您只需提供模型和非 "
+"CacheBlend 标志。"
+
+#: ../../source/mp/operator.rst:867
+msgid "The webhook mutates **Pods**, not the Deployment, so inspect a pod:"
+msgstr "该 Webhook 变更的是 **Pod**\\ ，而非 Deployment，因此请检查 Pod："
+
+#: ../../source/mp/operator.rst:874
+msgid ""
+"If nothing was injected, check the pod's ``lmcache.ai/cacheblend-skip-"
+"reason`` annotation: ``command-override`` (a ``sh -c`` wrapper was used),"
+" ``kv-transfer-config-present`` (you set your own), ``engine-not-found`` "
+"(the ``<name>-connection`` ConfigMap is missing), ``payload-image-unset``"
+" (the engine's ``injection.payloadImage`` has no repository), or "
+"``target-container-not-found`` (the requested ``targetContainer`` / "
+"``cacheblend-container`` annotation names a container the pod does not "
+"have). With ``failurePolicy: Ignore`` a webhook/cert problem also leaves "
+"the pod un-mutated silently -- confirm the operator pod is ``Running`` "
+"and the ``MutatingWebhookConfiguration`` exists."
+msgstr ""
+"若未注入任何内容，请检查 Pod 的 ``lmcache.ai/cacheblend-skip-reason`` 注解：\\ ``command-"
+"override``\\ （使用了 ``sh -c`` 包装器）、\\ ``kv-transfer-config-present``\\ "
+"（已自行设置了该配置）、\\ ``engine-not-found``\\ （缺少 ``<name>-connection`` "
+"ConfigMap）、\\ ``payload-image-unset``\\ （引擎的 ``injection.payloadImage`` "
+"未设置仓库），或 ``target-container-not-found``\\ （所请求的 ``targetContainer`` / "
+"``cacheblend-container`` 注解指向了 Pod 中不存在的容器）。在 ``failurePolicy: Ignore`` "
+"的情况下，Webhook 或证书问题也会使 Pod 静默地保持未变更 —— 请确认操作符 Pod 处于 ``Running`` 状态，且 "
+"``MutatingWebhookConfiguration`` 已存在。"
+
+#: ../../source/mp/operator.rst:886
+msgid "CacheBlendEngine Fields"
+msgstr "CacheBlendEngine 字段"
+
+#: ../../source/mp/operator.rst:888
+msgid ""
+"``CacheBlendEngineSpec`` mirrors ``LMCacheEngineSpec`` (every field in "
+"the CRD Spec Reference above) and adds:"
+msgstr ""
+"``CacheBlendEngineSpec`` 包含 ``LMCacheEngineSpec`` 的全部字段（见上方 CRD Spec "
+"参考），并新增了："
+
+#: ../../source/mp/operator.rst:898
+msgid "``blend.checkLayer``"
+msgstr "``blend.checkLayer``"
+
+#: ../../source/mp/operator.rst:900
+msgid "Layer at which token importance is scored (``cb.check_layer``)."
+msgstr "计算 Token 重要性评分所在的层（\\ ``cb.check_layer``\\ ）。"
+
+#: ../../source/mp/operator.rst:901
+msgid "``blend.recompRatio``"
+msgstr "``blend.recompRatio``"
+
+#: ../../source/mp/operator.rst:902
+msgid "``0.15``"
+msgstr "``0.15``"
+
+#: ../../source/mp/operator.rst:903
+msgid "Fraction of non-prefix-hit tokens recomputed (``cb.recomp_ratio``)."
+msgstr "非前缀命中 Token 被重新计算的比例（\\ ``cb.recomp_ratio``\\ ）。"
+
+#: ../../source/mp/operator.rst:904
+msgid "``injection.payloadImage``"
+msgstr "``injection.payloadImage``"
+
+#: ../../source/mp/operator.rst:906
+msgid ""
+"The (private) cacheblend-plugin init-container image (``repository`` / "
+"``tag`` / ``pullPolicy``).  Set ``repository`` -- the inherited engine-"
+"image default is not a valid payload."
+msgstr ""
+"（私有）cacheblend-plugin 初始化容器镜像（\\ ``repository`` / ``tag`` / "
+"``pullPolicy``\\ ）。必须设置 ``repository``——继承自引擎镜像的默认值并非有效的负载镜像。"
+
+#: ../../source/mp/operator.rst:909
+msgid "``injection.imagePullSecrets``"
+msgstr "``injection.imagePullSecrets``"
+
+#: ../../source/mp/operator.rst:911
+msgid "Pull secrets appended to the vLLM pod for the private payload image."
+msgstr "追加到 vLLM Pod 的私有负载镜像拉取密钥。"
+
+#: ../../source/mp/operator.rst:912
+msgid "``injection.targetContainer``"
+msgstr "``injection.targetContainer``"
+
+#: ../../source/mp/operator.rst:913
+msgid "first container"
+msgstr "第一个容器"
+
+#: ../../source/mp/operator.rst:914
+msgid "Name of the vLLM container to inject into."
+msgstr "要注入的 vLLM 容器的名称。"
+
+#: ../../source/mp/operator.rst:915
+msgid "``injection.cudagraph``"
+msgstr "``injection.cudagraph``"
+
+#: ../../source/mp/operator.rst:916
+msgid "``eager``"
+msgstr "``eager``"
+
+#: ../../source/mp/operator.rst:917
+msgid "``eager`` | ``piecewise`` | ``full_decode_only`` (never ``full``)."
+msgstr "``eager`` | ``piecewise`` | ``full_decode_only``\\ （不可使用 ``full``\\ ）。"
+
+#: ../../source/mp/operator.rst:919
+msgid ""
+"``server.chunkSize`` defaults to ``256`` and must equal 256 (the blend "
+"matcher requires ``chunk_size == vLLM --block-size * 4``)."
+msgstr ""
+"``server.chunkSize`` 的默认值为 ``256``\\ ，并且必须等于 256（混合匹配器要求 ``chunk_size == "
+"vLLM --block-size * 4``\\ ）。"
+
+#: ../../source/mp/operator.rst:923
+msgid "LMCacheCoordinator"
+msgstr "LMCacheCoordinator"
+
+#: ../../source/mp/operator.rst:925
+msgid ""
+"The ``LMCacheCoordinator`` CRD runs the **mp coordinator** -- a fleet-"
+"wide HTTP service that tracks mp server instances, evicts those whose "
+"heartbeats lapse, performs L2 quota eviction, and hosts the global "
+"CacheBlend fingerprint directory.  It is a plain (non-GPU) ``Deployment``"
+" exposed through a ClusterIP Service; engines reach it via "
+"``coordinator.ref`` or ``coordinator.url``."
+msgstr ""
+"``LMCacheCoordinator`` CRD 运行 **mp coordinator** -- 一个跨集群的 HTTP 服务，跟踪 mp "
+"服务器实例，逐出心跳超时的实例，执行 L2 配额逐出，并托管全局 CacheBlend 指纹目录。它是一个普通的 (非 GPU) "
+"``Deployment``，通过 ClusterIP 服务暴露；引擎通过 ``coordinator.ref`` 或 "
+"``coordinator.url`` 访问它。"
+
+#: ../../source/mp/operator.rst:932
+msgid "Deploying a Coordinator"
+msgstr "部署协调器"
+
+#: ../../source/mp/operator.rst:934
+msgid ""
+"A ready-to-edit manifest lives at "
+"``config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml`` in the "
+"operator repo.  A minimal coordinator:"
+msgstr ""
+"一个可以编辑的清单位于操作员仓库中的 "
+"``config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml``。一个最小的协调器："
+
+#: ../../source/mp/operator.rst:952
+msgid "Connecting an Engine"
+msgstr "连接引擎"
+
+#: ../../source/mp/operator.rst:954
+msgid ""
+"Point an ``LMCacheEngine`` / ``CacheBlendEngine`` at the coordinator "
+"through its ``coordinator`` block.  Use ``ref`` to name a coordinator in "
+"the same namespace (the operator resolves it to the in-cluster Service "
+"URL), or ``url`` for an explicit endpoint:"
+msgstr ""
+"通过其 ``coordinator`` 块将 ``LMCacheEngine`` / ``CacheBlendEngine`` 指向协调器。使用 "
+"``ref`` 在同一命名空间中命名协调器（操作符将其解析为集群内服务 URL），或使用 ``url`` 指定明确的端点："
+
+#: ../../source/mp/operator.rst:969
+msgid "Coordinator CRD Spec Reference"
+msgstr "协调器 CRD 规格参考"
+
+#: ../../source/mp/operator.rst:972
+msgid "Topology"
+msgstr "拓扑"
+
+#: ../../source/mp/operator.rst:981 ../../source/mp/operator.rst:1165
+msgid "``replicas``"
+msgstr "``replicas``"
+
+#: ../../source/mp/operator.rst:983
+msgid ""
+"Coordinator pods.  The registry is per-process in-memory, so >1 only "
+"makes sense behind a shared durable backend.  Must be >= 0."
+msgstr "协调器 Pod。注册表是每个进程的内存中，因此大于 1 仅在共享持久后端后面才有意义。必须大于或等于 0。"
+
+#: ../../source/mp/operator.rst:985
+msgid "``image.repository`` / ``image.tag`` / ``image.pullPolicy``"
+msgstr "``image.repository`` / ``image.tag`` / ``image.pullPolicy``"
+
+#: ../../source/mp/operator.rst:986
+msgid "shared engine image"
+msgstr "共享引擎镜像"
+
+#: ../../source/mp/operator.rst:987
+msgid "Runs the same lmcache binary as the engines."
+msgstr "运行与引擎相同的 lmcache 二进制文件。"
+
+#: ../../source/mp/operator.rst:993
+msgid "HTTP Server"
+msgstr "HTTP 服务器"
+
+#: ../../source/mp/operator.rst:1002
+msgid "``host``"
+msgstr "``host``"
+
+#: ../../source/mp/operator.rst:1003
+msgid "``0.0.0.0``"
+msgstr "``0.0.0.0``"
+
+#: ../../source/mp/operator.rst:1004
+msgid "Address the coordinator's HTTP server binds to."
+msgstr "协调器的 HTTP 服务器绑定的地址。"
+
+#: ../../source/mp/operator.rst:1005 ../../source/mp/operator.rst:1163
+msgid "``port``"
+msgstr "``port``"
+
+#: ../../source/mp/operator.rst:1006
+msgid "``9300``"
+msgstr "``9300``"
+
+#: ../../source/mp/operator.rst:1007
+msgid "HTTP port (1--65535)."
+msgstr "HTTP 端口 (1--65535)。"
+
+#: ../../source/mp/operator.rst:1010
+msgid "Membership & Health"
+msgstr "成员资格与健康"
+
+#: ../../source/mp/operator.rst:1019 ../../source/mp/operator.rst:1167
+msgid "``instanceTimeout``"
+msgstr "``instanceTimeout``"
+
+#: ../../source/mp/operator.rst:1020
+msgid "``30``"
+msgstr "``30``"
+
+#: ../../source/mp/operator.rst:1021
+msgid ""
+"Seconds without a heartbeat after which an instance is evicted.  Set "
+"comfortably above the engines' ``coordinator.heartbeatInterval``."
+msgstr "在没有心跳的情况下，经过的秒数后，实例将被逐出。设置应高于引擎的 ``coordinator.heartbeatInterval``。"
+
+#: ../../source/mp/operator.rst:1023
+msgid "``healthCheckInterval``"
+msgstr "``healthCheckInterval``"
+
+#: ../../source/mp/operator.rst:1024
+msgid "``10``"
+msgstr "``10``"
+
+#: ../../source/mp/operator.rst:1025
+msgid "Seconds between health-check sweeps; ``0`` disables the loop."
+msgstr "健康检查扫描之间的秒数；``0`` 禁用循环。"
+
+#: ../../source/mp/operator.rst:1028
+msgid "L2 Quota Eviction"
+msgstr "L2 配额逐出"
+
+#: ../../source/mp/operator.rst:1037
+msgid "``evictionCheckInterval``"
+msgstr "``evictionCheckInterval``"
+
+#: ../../source/mp/operator.rst:1038
+msgid "``5``"
+msgstr "``5``"
+
+#: ../../source/mp/operator.rst:1039
+msgid "Seconds between L2 eviction sweeps; ``0`` disables the loop."
+msgstr "L2 逐出清扫之间的秒数；``0`` 禁用循环。"
+
+#: ../../source/mp/operator.rst:1040 ../../source/mp/operator.rst:1171
+msgid "``evictionRatio``"
+msgstr "``evictionRatio``"
+
+#: ../../source/mp/operator.rst:1042
+msgid "Fraction of tracked keys (by count) to evict per cycle, [0.0, 1.0]."
+msgstr "每个周期逐出的跟踪键的比例（按数量计算），范围为 [0.0, 1.0]。"
+
+#: ../../source/mp/operator.rst:1043 ../../source/mp/operator.rst:1173
+msgid "``triggerWatermark``"
+msgstr "``triggerWatermark``"
+
+#: ../../source/mp/operator.rst:1044
+msgid "``1.0``"
+msgstr "``1.0``"
+
+#: ../../source/mp/operator.rst:1045
+msgid "Usage fraction of the quota that fires eviction, (0.0, 1.0]."
+msgstr "触发逐出的配额使用比例，(0.0, 1.0]。"
+
+#: ../../source/mp/operator.rst:1048
+msgid "Global CacheBlend Directory"
+msgstr "全局 CacheBlend 目录"
+
+#: ../../source/mp/operator.rst:1057
+msgid "``blendChunkSize``"
+msgstr "``blendChunkSize``"
+
+#: ../../source/mp/operator.rst:1059
+msgid ""
+"Tokens per chunk for the global CacheBlend directory (the match unit). "
+"**Must equal** the LMCache chunk size the blend servers use.  Must be > "
+"0."
+msgstr "全局 CacheBlend 目录中每个块的令牌数（匹配单位）。**必须等于** 混合服务器使用的 LMCache 块大小。必须大于 0。"
+
+#: ../../source/mp/operator.rst:1061
+msgid "``blendProbeStride``"
+msgstr "``blendProbeStride``"
+
+#: ../../source/mp/operator.rst:1063
+msgid ""
+"Positions between match probes.  ``1`` probes every offset for full "
+"recall; raise it to trade recall for coordinator CPU.  Must be > 0."
+msgstr "在匹配探针之间的位置。``1`` 在每个偏移量处探测以获得完整的召回；提高它以在召回和协调器 CPU 之间进行权衡。必须大于 0。"
+
+#: ../../source/mp/operator.rst:1067
+msgid "Prometheus, Scheduling & Overrides"
+msgstr "Prometheus、调度与覆盖"
+
+#: ../../source/mp/operator.rst:1078
+msgid "Expose the metrics container port.  See the note below."
+msgstr "暴露指标容器端口。请参见下面的说明。"
+
+#: ../../source/mp/operator.rst:1081
+msgid "Metrics port."
+msgstr "指标端口。"
+
+#: ../../source/mp/operator.rst:1084
+msgid "Create a ServiceMonitor CR (and headless metrics Service)."
+msgstr "创建一个 ServiceMonitor CR（和无头指标服务）。"
+
+#: ../../source/mp/operator.rst:1090
+msgid "``DEBUG`` | ``INFO`` | ``WARNING`` | ``ERROR``."
+msgstr "``DEBUG`` | ``INFO`` | ``WARNING`` | ``ERROR``."
+
+#: ../../source/mp/operator.rst:1093
+msgid ""
+"Pod resource requests/limits (no auto-compute; the coordinator is "
+"CPU/memory light)."
+msgstr "Pod 资源请求/限制（无自动计算；协调器轻量级 CPU/内存）。"
+
+#: ../../source/mp/operator.rst:1095
+msgid "``nodeSelector`` / ``affinity`` / ``tolerations`` / ``priorityClassName``"
+msgstr "``nodeSelector`` / ``affinity`` / ``tolerations`` / ``priorityClassName``"
+
+#: ../../source/mp/operator.rst:1097
+msgid "Pod scheduling controls."
+msgstr "Pod 调度控制。"
+
+#: ../../source/mp/operator.rst:1098
+msgid ""
+"``env`` / ``volumes`` / ``volumeMounts`` / ``podAnnotations`` / "
+"``podLabels`` / ``serviceAccountName``"
+msgstr ""
+"``env`` / ``volumes`` / ``volumeMounts`` / ``podAnnotations`` / "
+"``podLabels`` / ``serviceAccountName``"
+
+#: ../../source/mp/operator.rst:1100
+msgid "Standard pod-shaping fields."
+msgstr "标准的 Pod 形状字段。"
+
+#: ../../source/mp/operator.rst:1103
+msgid "Extra CLI flags (appended last, can override any auto-generated flag)."
+msgstr "额外的 CLI 标志（最后附加，可以覆盖任何自动生成的标志）。"
+
+#: ../../source/mp/operator.rst:1106
+msgid ""
+"The coordinator process does **not** yet expose a ``/metrics`` endpoint."
+"  The Prometheus wiring is present for parity but is only useful once "
+"metrics are added; ``serviceMonitor.enabled`` defaults to ``false``."
+msgstr ""
+"协调器进程\\ **尚未**\\ 暴露\\ ``/metrics``\\ "
+"端点。虽然存在Prometheus的连接，但只有在添加指标后才有用；``serviceMonitor.enabled``\\ 默认为\\ "
+"``false``。"
+
+#: ../../source/mp/operator.rst:1111
+msgid "Coordinator Resources Created"
+msgstr "创建协调器资源"
+
+#: ../../source/mp/operator.rst:1113
+msgid "For an ``LMCacheCoordinator`` named ``my-coordinator``:"
+msgstr "对于名为 ``my-coordinator`` 的 ``LMCacheCoordinator``："
+
+#: ../../source/mp/operator.rst:1122
+msgid "Deployment"
+msgstr "部署"
+
+#: ../../source/mp/operator.rst:1123 ../../source/mp/operator.rst:1126
+#: ../../source/mp/operator.rst:1132
+msgid "``my-coordinator``"
+msgstr "``my-coordinator``"
+
+#: ../../source/mp/operator.rst:1124
+msgid "Runs the coordinator HTTP server pods."
+msgstr "运行协调器 HTTP 服务器 Pod。"
+
+#: ../../source/mp/operator.rst:1127
+msgid "Fleet-wide discovery on the HTTP port."
+msgstr "在 HTTP 端口上进行全舰队发现。"
+
+#: ../../source/mp/operator.rst:1129
+msgid "``my-coordinator-metrics``"
+msgstr "``my-coordinator-metrics``"
+
+#: ../../source/mp/operator.rst:1130
+msgid "Prometheus scrape target (when ``serviceMonitor.enabled``)."
+msgstr "当 ``serviceMonitor.enabled`` 时的 Prometheus 抓取目标。"
+
+#: ../../source/mp/operator.rst:1133
+msgid "Prometheus Operator integration (when ``serviceMonitor.enabled``)."
+msgstr "Prometheus Operator 集成（当 ``serviceMonitor.enabled`` 时）。"
+
+#: ../../source/mp/operator.rst:1135
+msgid ""
+"The status ``endpoint`` other components use to reach the coordinator is "
+"``http://<name>.<namespace>.svc:<port>`` (e.g. ``http://my-"
+"coordinator.default.svc:9300``)."
+msgstr ""
+"其他组件用来访问协调器的状态 ``endpoint`` 是 ``http://<name>.<namespace>.svc:<port>``\\ "
+"（例如 ``http://my-coordinator.default.svc:9300``）。"
+
+#: ../../source/mp/operator.rst:1140
+msgid "Coordinator Status & Conditions"
+msgstr "协调器状态与条件"
+
+#: ../../source/mp/operator.rst:1145
+msgid "**replicas** / **readyReplicas**: Pod counts from the Deployment."
+msgstr "**副本** / **就绪副本**: 来自部署的 Pod 数量。"
+
+#: ../../source/mp/operator.rst:1146
+msgid "**endpoint**: In-cluster URL for reaching the coordinator."
+msgstr "**endpoint**: 集群内用于访问协调器的 URL。"
+
+#: ../../source/mp/operator.rst:1147
+msgid "**observedGeneration**: Most recent reconciled generation."
+msgstr "**observedGeneration**: 最近一次已调和的版本。"
+
+#: ../../source/mp/operator.rst:1150
+msgid "``Available`` -- At least one replica is ready."
+msgstr "``Available`` -- 至少一个副本已准备好。"
+
+#: ../../source/mp/operator.rst:1151
+msgid "``AllInstancesReady`` -- All desired replicas are ready."
+msgstr "``所有实例已准备好`` -- 所有期望的实例均已准备好。"
+
+#: ../../source/mp/operator.rst:1155
+msgid "Coordinator Validation Rules"
+msgstr "协调器验证规则"
+
+#: ../../source/mp/operator.rst:1164
+msgid "Must be in [1, 65535]."
+msgstr "必须在 [1, 65535] 之间。"
+
+#: ../../source/mp/operator.rst:1166 ../../source/mp/operator.rst:1170
+msgid "Must be >= 0."
+msgstr "必须 >= 0。"
+
+#: ../../source/mp/operator.rst:1168 ../../source/mp/operator.rst:1176
+msgid "Must be > 0."
+msgstr "必须 > 0。"
+
+#: ../../source/mp/operator.rst:1169
+msgid "``healthCheckInterval`` / ``evictionCheckInterval``"
+msgstr "``healthCheckInterval`` / ``evictionCheckInterval``"
+
+#: ../../source/mp/operator.rst:1172
+msgid "Must be in [0.0, 1.0]."
+msgstr "必须在 [0.0, 1.0] 之间。"
+
+#: ../../source/mp/operator.rst:1175
+msgid "``blendChunkSize`` / ``blendProbeStride``"
+msgstr "``blendChunkSize`` / ``blendProbeStride``"
+
+#: ../../source/mp/operator.rst:1179
+msgid "Operator vs Manual Deployment"
+msgstr "Operator 与手动部署对比"
+
+#: ../../source/mp/operator.rst:1185
+msgid "Concern"
+msgstr "对比项"
+
+#: ../../source/mp/operator.rst:1186
+msgid "Manual DaemonSet"
+msgstr "手动 DaemonSet"
+
+#: ../../source/mp/operator.rst:1187
+msgid "LMCacheEngine Operator"
+msgstr "LMCacheEngine Operator"
+
+#: ../../source/mp/operator.rst:1188
+msgid "hostIPC"
+msgstr "hostIPC"
+
+#: ../../source/mp/operator.rst:1189 ../../source/mp/operator.rst:1192
+msgid "Must set manually"
+msgstr "必须手动设置"
+
+#: ../../source/mp/operator.rst:1190 ../../source/mp/operator.rst:1193
+msgid "Auto-injected"
+msgstr "自动注入"
+
+#: ../../source/mp/operator.rst:1191
+msgid "``--host 0.0.0.0``"
+msgstr "``--host 0.0.0.0``"
+
+#: ../../source/mp/operator.rst:1194
+msgid "Service discovery"
+msgstr "服务发现"
+
+#: ../../source/mp/operator.rst:1195
+msgid "``hostNetwork`` + ``status.hostIP``"
+msgstr "``hostNetwork`` + ``status.hostIP``"
+
+#: ../../source/mp/operator.rst:1196
+msgid "Node-local ClusterIP Service + ConfigMap"
+msgstr "节点本地 ClusterIP 服务 + ConfigMap"
+
+#: ../../source/mp/operator.rst:1197
+msgid "vLLM config"
+msgstr "vLLM 配置"
+
+#: ../../source/mp/operator.rst:1198
+msgid "Copy JSON into Deployment"
+msgstr "将 JSON 复制到部署中"
+
+#: ../../source/mp/operator.rst:1199
+msgid "Mount ``<name>-connection`` ConfigMap"
+msgstr "挂载 ``<name>-connection`` ConfigMap"
+
+#: ../../source/mp/operator.rst:1200
+msgid "Resource sizing"
+msgstr "资源大小调整"
+
+#: ../../source/mp/operator.rst:1201
+msgid "Manual calculation"
+msgstr "手动计算"
+
+#: ../../source/mp/operator.rst:1202
+msgid "Auto-computed from ``l1.sizeGB``"
+msgstr "从 ``l1.sizeGB`` 自动计算"
+
+#: ../../source/mp/operator.rst:1204
+msgid "Manual ServiceMonitor"
+msgstr "手动 ServiceMonitor"
+
+#: ../../source/mp/operator.rst:1205
+msgid "``serviceMonitor.enabled: true``"
+msgstr "``serviceMonitor.enabled: true``"
+
+#: ../../source/mp/operator.rst:1206
+msgid "Validation"
+msgstr "验证"
+
+#: ../../source/mp/operator.rst:1207
+msgid "Runtime errors only"
+msgstr "仅限运行时错误"
+
+#: ../../source/mp/operator.rst:1208
+msgid "``kubectl apply`` rejects invalid specs"
+msgstr "``kubectl apply`` 拒绝无效的规格"
+
+#: ../../source/mp/operator.rst:1209
+msgid "New GPU nodes"
+msgstr "新的 GPU 节点"
+
+#: ../../source/mp/operator.rst:1210
+msgid "DaemonSet handles it"
+msgstr "DaemonSet 处理它"
+
+#: ../../source/mp/operator.rst:1211
+msgid "DaemonSet handles it (same)"
+msgstr "DaemonSet 处理它（相同）"
+
+#: ../../source/mp/operator.rst:1214
+msgid "Security Considerations"
+msgstr "安全注意事项"
+
+#: ../../source/mp/operator.rst:1216
+msgid ""
+"**hostIPC** exposes the host's IPC namespace (System V IPC, POSIX message"
+" queues) to the container.  Any process in the container can interact "
+"with IPC resources from other processes on the same host."
+msgstr ""
+"**hostIPC** 将主机的 IPC 命名空间（System V IPC，POSIX "
+"消息队列）暴露给容器。容器中的任何进程都可以与同一主机上其他进程的 IPC 资源进行交互。"
+
+#: ../../source/mp/operator.rst:1220
+msgid "Deploy only in trusted environments."
+msgstr "仅在受信任的环境中部署。"
+
+#: ../../source/mp/operator.rst:1221
+msgid ""
+"Clusters using Pod Security Standards must allow the ``privileged`` "
+"profile for the LMCache namespace -- the ``baseline`` and ``restricted`` "
+"profiles reject ``hostIPC``."
+msgstr ""
+"使用 Pod 安全标准的集群必须为 LMCache 命名空间开启 ``privileged`` 配置文件——``baseline`` 和 "
+"``restricted`` 配置文件均会拒绝 ``hostIPC``\\ 。"
+
+#: ../../source/mp/operator.rst:1224
+msgid ""
+"``spec.privileged`` defaults to ``false``. When enabled (required for "
+"``gpuVendor: amd``), the engine container additionally runs privileged, "
+"granting it full device access -- enable it only where GPU visibility "
+"requires it."
+msgstr "``spec.privileged`` 默认为 ``false``。启用后（对于 ``gpuVendor: amd`` 是必需的），引擎容器将以特权模式运行，授予其完全的设备访问权限——仅在 GPU 可见性需要时启用。"
+
+#: ../../source/mp/operator.rst:1230
+msgid "Development"
+msgstr "开发"
+
+#: ../../source/mp/operator.rst:1242
+msgid "Pushing a custom operator image:"
+msgstr "推送自定义 Operator 镜像："
+
+#: ../../source/mp/operator.rst:1253
+msgid "If your cluster needs pull credentials:"
+msgstr "如果您的集群需要拉取凭据："
+
+#~ msgid "Only ``LRU`` is supported."
+#~ msgstr "仅支持 ``LRU``\\ 。"
+
+#~ msgid ""
+#~ "The operator creates a ConfigMap named"
+#~ " ``<engine-name>-connection`` containing the "
+#~ "``kv-transfer-config`` JSON.  Mount it"
+#~ " in your vLLM Deployment:"
+#~ msgstr ""
+#~ "操作符创建一个名为 ``<engine-name>-connection`` 的 "
+#~ "ConfigMap，其中包含 ``kv-transfer-config`` "
+#~ "JSON。将其挂载到您的 vLLM 部署中："
+
+#~ msgid "GPU Vendor"
+#~ msgstr "GPU 供应商"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/p2p.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/p2p.po
new file mode 100644
index 0000000..db56c21
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/p2p.po
@@ -0,0 +1,373 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/p2p.rst:4
+msgid "P2P KV Cache Sharing"
+msgstr "P2P KV 缓存共享"
+
+#: ../../source/mp/p2p.rst:7
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/mp/p2p.rst:9
+msgid ""
+"In a multi-node deployment, every node runs its own LMCache server "
+"process, and each one caches the KV of the requests it has served in its "
+"local memory. Without sharing, a prefix that was computed on one node has"
+" to be recomputed from scratch when the same prefix arrives on a "
+"different node."
+msgstr "在多节点部署中，每个节点运行自己的 LMCache 服务器进程，每个节点在其本地内存中缓存它所服务请求的 KV。没有共享时，当相同的前缀到达不同节点时，必须从头开始重计算在一个节点上计算的前缀。"
+
+#: ../../source/mp/p2p.rst:14
+msgid ""
+"**Peer-to-peer (P2P) KV cache sharing turns the per-node caches into one "
+"logical cache.** When a node looks up a prefix that is not in its own "
+"memory, it can read that prefix's KV directly from the memory of the peer"
+" node that holds it, over the datacenter network using RDMA. The result "
+"is a much higher effective cache hit rate across the fleet, without any "
+"central storage tier in the hot path."
+msgstr "**点对点 (P2P) KV 缓存共享将每个节点的缓存转变为一个逻辑缓存。** 当一个节点查找不在其本地内存中的前缀时，它可以通过数据中心网络使用 RDMA 直接从持有该前缀的对等节点的内存中读取该前缀的 KV。结果是整个系统的有效缓存命中率大大提高，而无需在热路径中使用中央存储层。"
+
+#: ../../source/mp/p2p.rst:21
+msgid ""
+"The transfer is a one-sided RDMA read from the requesting node into its "
+"own L1 buffer; the node that owns the data is not interrupted to serve "
+"it. On an RDMA-capable network (InfiniBand / RoCE) this is dramatically "
+"faster than recomputing the prefix or round-tripping through a shared "
+"object store."
+msgstr "传输是从请求节点到其自身 L1 缓冲区的单向 RDMA 读取；拥有数据的节点不会被打断来提供数据。在支持 RDMA 的网络（如 InfiniBand / RoCE）上，这比重新计算前缀或通过共享对象存储进行往返要快得多。"
+
+#: ../../source/mp/p2p.rst:27
+msgid "How it works"
+msgstr "它是如何工作的"
+
+#: ../../source/mp/p2p.rst:29
+msgid "P2P involves three pieces:"
+msgstr "P2P 涉及三个部分："
+
+#: ../../source/mp/p2p.rst:31
+msgid ""
+"**Coordinator** — a small HTTP service (one per deployment) that tracks "
+"which LMCache servers are alive. Each server registers with it and "
+"heartbeats; the coordinator answers \"who are my live peers?\" queries. "
+"It only manages membership — it never sees KV data or participates in "
+"lookups. See :doc:`coordinator`."
+msgstr "**协调器** — 一个小型 HTTP 服务（每个部署一个），用于跟踪哪些 LMCache 服务器处于活动状态。每个服务器向其注册并发送心跳；协调器回答“我的活动对等体是谁？”的查询。它仅管理成员资格——它从不查看 KV 数据或参与查找。请参见 :doc:`coordinator`。"
+
+#: ../../source/mp/p2p.rst:36
+msgid ""
+"**LMCache server** — each server runs a P2P controller that periodically "
+"asks the coordinator for the current peer list and, for every live peer, "
+"opens a connection used to look up and read that peer's KV."
+msgstr "**LMCache 服务器** — 每个服务器运行一个 P2P 控制器，定期向协调器请求当前的对等体列表，并为每个活跃的对等体打开一个连接，用于查找和读取该对等体的 KV。"
+
+#: ../../source/mp/p2p.rst:39
+msgid ""
+"**Transfer channel** — the RDMA layer that performs the actual remote "
+"memory reads. Each server registers its L1 buffer once at startup so "
+"peers can read from it."
+msgstr "**传输通道** — 执行实际远程内存读取的 RDMA 层。每个服务器在启动时注册其 L1 缓冲区，以便对等体可以从中读取。"
+
+#: ../../source/mp/p2p.rst:43
+msgid ""
+"On a cache miss, a node asks the peer that owns the prefix to *lock and "
+"locate* it, receives the remote addresses, RDMA-reads the KV into its own"
+" L1, and serves the request from there. Peers are discovered and "
+"connected automatically as they join, and disconnected automatically as "
+"they leave — no static peer lists."
+msgstr "在缓存未命中时，一个节点请求拥有前缀的对等节点锁定并定位它，接收远程地址，将 KV 读取到自己的 L1 中，并从那里提供请求。对等节点在加入时会自动发现和连接，在离开时会自动断开 — 无需静态对等节点列表。"
+
+#: ../../source/mp/p2p.rst:49
+msgid "Requirements"
+msgstr "要求"
+
+#: ../../source/mp/p2p.rst:51
+msgid ""
+"**A coordinator.** P2P needs the coordinator for peer discovery. A server"
+" started with ``--p2p-advertise-url`` but no ``--coordinator-url`` "
+"refuses to start."
+msgstr "**一个协调者。** P2P 需要协调者进行对等发现。使用 ``--p2p-advertise-url`` 启动的服务器如果没有 ``--coordinator-url`` 则拒绝启动。"
+
+#: ../../source/mp/p2p.rst:54
+msgid ""
+"**An RDMA-capable network** (InfiniBand / RoCE) is strongly recommended "
+"for production performance. By default P2P uses the ``nixl`` transfer "
+"engine, which is shipped with LMCache, so there is nothing extra to "
+"install."
+msgstr "**强烈推荐使用支持 RDMA 的网络**\\ （InfiniBand / RoCE）以获得生产性能。默认情况下，P2P 使用与 LMCache 一起提供的 ``nixl`` 传输引擎，因此无需额外安装任何东西。"
+
+#: ../../source/mp/p2p.rst:57
+msgid ""
+"**A single, contiguous L1 region.** The transfer channel registers the "
+"whole L1 buffer for RDMA, so P2P is incompatible with the GDS L1 tier "
+"(``--gds-l1-path``) and the Device-DAX L1 tier (``--l1-devdax-path``); "
+"the server refuses to start in those configurations."
+msgstr "**一个单一的、连续的 L1 区域。** 传输通道为 RDMA 注册整个 L1 缓冲区，因此 P2P 与 GDS L1 层（``--gds-l1-path``）和 Device-DAX L1 层（``--l1-devdax-path``）不兼容；在这些配置下，服务器拒绝启动。"
+
+#: ../../source/mp/p2p.rst:63
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/mp/p2p.rst:65
+msgid ""
+"P2P is enabled per server by the ``--p2p-advertise-url`` flag. The "
+"relevant ``lmcache server`` flags are:"
+msgstr "P2P 通过 ``--p2p-advertise-url`` 标志在每个服务器上启用。相关的 ``lmcache server`` 标志包括："
+
+#: ../../source/mp/p2p.rst:72
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/mp/p2p.rst:73 ../../source/mp/p2p.rst:113
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/p2p.rst:74
+msgid "``--p2p-advertise-url HOST:PORT``"
+msgstr "``--p2p-advertise-url HOST:PORT``"
+
+#: ../../source/mp/p2p.rst:75
+msgid ""
+"Transfer-channel endpoint this server advertises to peers. Setting it "
+"enables P2P. Must be an address other nodes can reach."
+msgstr "此服务器向对等节点广告的传输通道端点。设置它可以启用 P2P。必须是其他节点可以访问的地址。"
+
+#: ../../source/mp/p2p.rst:77
+msgid "``--p2p-listen-url HOST:PORT``"
+msgstr "``--p2p-listen-url HOST:PORT``"
+
+#: ../../source/mp/p2p.rst:78
+msgid ""
+"Address the transfer-channel server binds to. Defaults to ``--p2p-"
+"advertise-url``; set it to bind ``0.0.0.0`` while advertising a routable "
+"IP."
+msgstr "传输通道服务器绑定的地址。默认为 ``--p2p-advertise-url``；在广告可路由 IP 时，将其设置为绑定 ``0.0.0.0``。"
+
+#: ../../source/mp/p2p.rst:81
+msgid "``--p2p-lookup-timeout SECONDS``"
+msgstr "``--p2p-lookup-timeout SECONDS``"
+
+#: ../../source/mp/p2p.rst:82
+msgid "Deadline for a peer lookup before it counts as a miss (default ``30``)."
+msgstr "对等查找的截止时间，超过该时间将视为未命中（默认 ``30``）。"
+
+#: ../../source/mp/p2p.rst:83
+msgid "``--p2p-load-timeout SECONDS``"
+msgstr "``--p2p-load-timeout SECONDS``"
+
+#: ../../source/mp/p2p.rst:84
+msgid ""
+"Deadline for a peer KV read before it counts as a failure (default "
+"``30``)."
+msgstr "对等 KV 读取的截止时间，超过该时间将视为失败（默认 ``30``）。"
+
+#: ../../source/mp/p2p.rst:86
+msgid "``--p2p-transfer-engine ENGINE``"
+msgstr "``--p2p-transfer-engine ENGINE``"
+
+#: ../../source/mp/p2p.rst:87
+msgid "Transfer-channel implementation (default ``nixl``)."
+msgstr "传输通道实现（默认 ``nixl``）。"
+
+#: ../../source/mp/p2p.rst:89
+msgid ""
+"P2P also reuses the coordinator connection flags (``--coordinator-url``, "
+"``--coordinator-advertise-ip``, ``--coordinator-heartbeat-interval``); "
+"the heartbeat interval doubles as the peer-discovery poll interval. See "
+":doc:`/cli/server` and :doc:`/cli/coordinator` for the full flag lists."
+msgstr "P2P 还重用协调器连接标志 (``--coordinator-url``, ``--coordinator-advertise-ip``, ``--coordinator-heartbeat-interval``)；心跳间隔同时作为对等发现轮询间隔。有关完整的标志列表，请参见 :doc:`/cli/server` 和 :doc:`/cli/coordinator`。"
+
+#: ../../source/mp/p2p.rst:96
+msgid ""
+"Increase the L1 buffer alignment to at least 64 KB (``--l1-align-bytes "
+"65536``) on servers that participate in P2P. A larger alignment lets the "
+"transfer channel issue bigger, better-aligned RDMA reads and noticeably "
+"improves transfer performance. The default (4 KB) is fine for non-P2P "
+"deployments."
+msgstr "在参与 P2P 的服务器上，将 L1 缓冲区对齐增加到至少 64 KB (``--l1-align-bytes 65536``)。更大的对齐可以让传输通道发出更大、更好对齐的 RDMA 读取，并显著提高传输性能。默认值（4 KB）对于非 P2P 部署是可以的。"
+
+#: ../../source/mp/p2p.rst:103
+msgid "Transfer engine backends"
+msgstr "传输引擎后端"
+
+#: ../../source/mp/p2p.rst:105
+msgid ""
+"The transfer engine is the component that performs the remote memory "
+"reads, selected per server with ``--p2p-transfer-engine``."
+msgstr "传输引擎是执行远程内存读取的组件，按服务器选择，使用 ``--p2p-transfer-engine``。"
+
+#: ../../source/mp/p2p.rst:112
+msgid "Engine"
+msgstr "引擎"
+
+#: ../../source/mp/p2p.rst:114
+msgid "``nixl`` (default)"
+msgstr "``nixl`` (默认)"
+
+#: ../../source/mp/p2p.rst:115
+msgid ""
+"RDMA-based transport, shipped with LMCache. Runs over InfiniBand / RoCE "
+"fabrics."
+msgstr "基于 RDMA 的传输，随 LMCache 一起提供。运行在 InfiniBand / RoCE 网络上。"
+
+#: ../../source/mp/p2p.rst:118
+msgid ""
+"``nixl`` is the only backend available today. The transfer engine is a "
+"pluggable abstraction, so additional backends can be added in the future "
+"without changing the rest of the P2P stack."
+msgstr "``nixl`` 是目前唯一可用的后端。传输引擎是一个可插拔的抽象，因此可以在未来添加其他后端，而无需更改 P2P 堆栈的其余部分。"
+
+#: ../../source/mp/p2p.rst:123
+msgid "Running a multi-node deployment"
+msgstr "运行多节点部署"
+
+#: ../../source/mp/p2p.rst:125
+msgid ""
+"The example below brings up a two-node fleet. Adding more nodes is just "
+"more copies of the per-node step, all pointing at the same coordinator."
+msgstr "下面的示例启动了一个两节点的集群。添加更多节点只需复制每个节点的步骤，所有节点都指向相同的协调器。"
+
+#: ../../source/mp/p2p.rst:128
+msgid ""
+"**Step 1 — start the coordinator** (on a host all nodes can reach, here "
+"``10.0.0.1``):"
+msgstr "**步骤 1 — 启动协调器**\\ （在所有节点都能访问的主机上，这里是 ``10.0.0.1``）："
+
+#: ../../source/mp/p2p.rst:135
+msgid ""
+"**Step 2 — on each node, start the LMCache server with P2P enabled.** "
+"Replace ``<NODE_IP>`` with that node's routable address (e.g. "
+"``10.0.0.2``, ``10.0.0.3``, ...):"
+msgstr "**步骤 2 — 在每个节点上启动启用 P2P 的 LMCache 服务器。** 将 ``<NODE_IP>`` 替换为该节点的可路由地址（例如 ``10.0.0.2``、``10.0.0.3`` 等）："
+
+#: ../../source/mp/p2p.rst:150
+msgid ""
+"``--coordinator-advertise-ip`` is the address peers use to reach this "
+"node's control plane, and ``--p2p-advertise-url`` is the RDMA transfer "
+"endpoint. Here the server binds ``0.0.0.0`` (all interfaces) and "
+"advertises ``<NODE_IP>``."
+msgstr "``--coordinator-advertise-ip`` 是对等节点用来访问该节点控制平面的地址，而 ``--p2p-advertise-url`` 是 RDMA 传输端点。这里服务器绑定 ``0.0.0.0``\\ （所有接口）并广播 ``<NODE_IP>``。"
+
+#: ../../source/mp/p2p.rst:154
+msgid ""
+"**Step 3 — on each node, start vLLM** pointed at the *local* LMCache "
+"server via the connector. vLLM never talks to peers directly — the "
+"LMCache server it connects to does P2P on its behalf:"
+msgstr "**步骤 3 — 在每个节点上，通过连接器启动指向本地 LMCache 服务器的 vLLM。vLLM 从不直接与对等节点通信 — 它连接的 LMCache 服务器代表它进行 P2P：**"
+
+#: ../../source/mp/p2p.rst:164
+msgid ""
+"Once both nodes have registered, a prefix first served on node 2 will be "
+"served from node 2's cache when the same prefix later arrives on node 3 —"
+" read over RDMA instead of recomputed."
+msgstr "一旦两个节点都已注册，当相同的前缀稍后到达节点 3 时，首先在节点 2 上提供的前缀将从节点 2 的缓存中提供——通过 RDMA 读取，而不是重计算。"
+
+#: ../../source/mp/p2p.rst:169
+msgid "Running on a single node (testing & debugging)"
+msgstr "在单个节点上运行（测试和调试）"
+
+#: ../../source/mp/p2p.rst:171
+msgid ""
+"You can exercise the entire P2P path on a single multi-GPU machine by "
+"running two LMCache servers and two vLLM servers over ``localhost``, plus"
+" one coordinator. This is the recommended way to develop and debug P2P."
+msgstr "您可以通过在 ``localhost`` 上运行两个 LMCache 服务器和两个 vLLM 服务器，以及一个协调器，在单个多 GPU 机器上执行整个 P2P 路径。这是开发和调试 P2P 的推荐方式。"
+
+#: ../../source/mp/p2p.rst:208
+msgid ""
+"The two servers must differ in **every** port: ZMQ (``--port``), HTTP "
+"(``--http-port``), and the P2P transfer endpoint (``--p2p-advertise-"
+"url``). Give each a distinct ``--instance-id`` so they are easy to tell "
+"apart."
+msgstr "这两个服务器必须在 **每个** 端口上有所不同：ZMQ (``--port``)、HTTP (``--http-port``) 和 P2P 传输端点 (``--p2p-advertise-url``)。为每个服务器指定一个独特的 ``--instance-id``，以便于区分。"
+
+#: ../../source/mp/p2p.rst:212
+msgid ""
+"To test the path, send a long prompt to vLLM **A** (port ``8000``) and "
+"then the *same* prompt to vLLM **B** (port ``8001``). B has never seen "
+"the prompt and its own cache is empty, so any LMCache hit on B must have "
+"been read from A over P2P."
+msgstr "要测试路径，向 vLLM **A**\\ （端口 ``8000``）发送一个长提示，然后向 vLLM **B**\\ （端口 ``8001``）发送相同的提示。B 从未见过该提示，并且它自己的缓存是空的，因此 B 上的任何 LMCache 命中必须是通过 P2P 从 A 读取的。"
+
+#: ../../source/mp/p2p.rst:218
+msgid ""
+"On a single host, ``localhost`` traffic typically uses the loopback/TCP "
+"path rather than RDMA, so latencies are not representative of a real RDMA"
+" fabric. Single-node mode is for **functional** testing and debugging; "
+"benchmark performance on a real multi-node RDMA deployment."
+msgstr "在单个主机上，``localhost`` 流量通常使用回环/TCP 路径而不是 RDMA，因此延迟并不能代表真实的 RDMA 结构。单节点模式用于 **功能** 测试和调试；在真实的多节点 RDMA 部署上进行基准性能测试。"
+
+#: ../../source/mp/p2p.rst:224
+msgid "Verifying P2P is working"
+msgstr "验证 P2P 是否正常工作"
+
+#: ../../source/mp/p2p.rst:226
+msgid ""
+"Query a server's status endpoint to see its P2P state and discovered "
+"peers:"
+msgstr "查询服务器的状态端点以查看其 P2P 状态和发现的对等节点："
+
+#: ../../source/mp/p2p.rst:232
+msgid ""
+"Look for ``p2p_state`` (``registered`` once it has joined the "
+"coordinator) and ``p2p_peer_count`` (the number of connected peers; ``1``"
+" in the two-node example). You can also list the fleet from the "
+"coordinator:"
+msgstr "查找 ``p2p_state`` （一旦加入协调器则为 ``registered``）和 ``p2p_peer_count`` （连接的对等节点数量；在两个节点的示例中为 ``1``）。您还可以从协调器列出整个集群："
+
+#: ../../source/mp/p2p.rst:240
+msgid ""
+"With ``LMCACHE_LOG_LEVEL=DEBUG``, each server logs ``Added P2P adapter "
+"... for peer <instance-id>`` when it connects to a peer, and ``Removed "
+"P2P adapter ...`` when a peer leaves."
+msgstr "在 ``LMCACHE_LOG_LEVEL=DEBUG`` 下，每个服务器在连接到对等体时记录 ``Added P2P adapter ... for peer <instance-id>``，在对等体离开时记录 ``Removed P2P adapter ...``。"
+
+#: ../../source/mp/p2p.rst:245
+msgid "Limitations"
+msgstr "限制"
+
+#: ../../source/mp/p2p.rst:247
+msgid ""
+"**Read-only.** A node reads KV from its peers; it never writes into a "
+"peer's memory. This keeps each node the sole owner of its L1."
+msgstr "**只读。** 节点从其对等节点读取 KV；它永远不会写入对等节点的内存。这使得每个节点都是其 L1 的唯一拥有者。"
+
+#: ../../source/mp/p2p.rst:249
+msgid ""
+"**One hop.** A node reads directly from the peer that holds the prefix; "
+"reads are not chained across multiple peers."
+msgstr "**单跳。** 节点直接从持有前缀的对等节点读取；读取不会跨多个对等节点链式进行。"
+
+#~ msgid ""
+#~ "The multiprocess (MP) implementation of "
+#~ "peer-to-peer (P2P) KV cache sharing"
+#~ " is **coming soon**."
+#~ msgstr "对等网络 (P2P) KV 缓存共享的多进程 (MP) 实现将于 **即将推出**。"
+
+#~ msgid ""
+#~ "Until it lands, the in-process "
+#~ "implementation is documented in the "
+#~ ":doc:`Legacy section <../legacy/index>`: "
+#~ ":doc:`../kv_cache/p2p_sharing`."
+#~ msgstr ""
+#~ "在它发布之前，进程内实现的文档记录在 :doc:`遗留部分 <../legacy/index>`： "
+#~ ":doc:`../kv_cache/p2p_sharing`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/sdk.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/sdk.po
new file mode 100644
index 0000000..96c6b74
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/sdk.po
@@ -0,0 +1,221 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/sdk.rst:2
+msgid "KV Cache SDK"
+msgstr ""
+
+#: ../../source/mp/sdk.rst:4
+msgid ""
+"The LMCache **SDK** lets you retrieve a request's KV cache from a LMCache"
+" server, transform it on the CPU, and store it back. This can be used for"
+" KV cache transformations, such as token dropping. In the example: we "
+"prefill a batch of long prompts, drop half of each request's KV chunks, "
+"and show the decode-throughput gain. The full runnable notebook lives at "
+"`examples/token_dropping/token_dropping.ipynb "
+"<https://github.com/LMCache/LMCache/tree/dev/examples/token_dropping>`_."
+msgstr ""
+
+#: ../../source/mp/sdk.rst:18
+msgid "Why KV Cache SDK"
+msgstr ""
+
+#: ../../source/mp/sdk.rst:20
+msgid ""
+"**Improving Decode Throughput** when shrinking KV cache using token "
+"dropping. Token dropping reduces the KV cache size, allowing more "
+"requests to fit in a batch, improving decode throughput."
+msgstr ""
+
+#: ../../source/mp/sdk.rst:24
+msgid ""
+"The SDK gives you the hooks to retrieve a request's KV, supply your own "
+"function to edit the KV, and store the edited KV back. The SDK also "
+"provides a batched-stream API to prefill, modify, and store the cache "
+"back before decoding continues."
+msgstr ""
+
+#: ../../source/mp/sdk.rst:31
+msgid "How it works"
+msgstr ""
+
+#: ../../source/mp/sdk.rst:33
+msgid "A request flows through three phases on the batched-stream API:"
+msgstr ""
+
+#: ../../source/mp/sdk.rst:35
+msgid ""
+"**prefill** — run each prompt through vLLM once (``max_tokens=1``); vLLM "
+"computes the KV cache and stores it in LMCache."
+msgstr ""
+
+#: ../../source/mp/sdk.rst:37
+msgid ""
+"**modify** — the SDK retrieves the cached KV to CPU, hands it to your "
+"edit function, and stores the result back."
+msgstr "**修改** — SDK 将缓存的 KV 取回到 CPU，交给你的编辑函数，并将结果存储回去。"
+
+#: ../../source/mp/sdk.rst:39
+msgid "**decode** — continue generation against the smaller, edited cache."
+msgstr "**解码** — 在更小的、编辑过的缓存上继续生成。"
+
+#: ../../source/mp/sdk.rst:41
+msgid ""
+"The SDK runs on **CPU** and hands you KV tensors in ``HND`` order with "
+"shape ``[2, L, T, D]`` (K/V, layers, chunk-aligned tokens, ``num_kv_heads"
+" * head_dim``)."
+msgstr "SDK 在 **CPU** 上运行，并以 ``HND`` 顺序提供形状为 ``[2, L, T, D]`` 的 KV 张量（K/V、层、块对齐的标记、``num_kv_heads * head_dim``）。"
+
+#: ../../source/mp/sdk.rst:46
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/mp/sdk.rst:48
+msgid ""
+"To start the LMCache server with shared-memory transfer enabled, pass "
+"``--shm-name`` and disable lazy L1 allocation with ``--no-l1-use-lazy``. "
+"If shared memory is unavailable and these flags are not specified, the "
+"SDK falls back to pickle."
+msgstr "要启动启用共享内存传输的 LMCache 服务器，请传递 ``--shm-name`` 并使用 ``--no-l1-use-lazy`` 禁用懒惰的 L1 分配。如果共享内存不可用且未指定这些标志，SDK 将回退到 pickle。"
+
+#: ../../source/mp/sdk.rst:64
+msgid "Then start vLLM with the LMCache MP connector."
+msgstr "然后使用 LMCache MP 连接器启动 vLLM。"
+
+#: ../../source/mp/sdk.rst:80
+msgid ""
+"The SDK keys the KV cache by token ids: ``create_request`` takes the "
+"prompt as token ids, and every ``post_completion`` must report a "
+"``token_id`` for each generated token. The example gets these ids "
+"straight from vLLM by passing ``--return-tokens-as-token-ids``. "
+"Otherwise, if vLLM returns only text, the ``post_completion`` must "
+"tokenize each generated token back into a token id."
+msgstr "SDK通过令牌 ID 对 KV Cache 进行键控：``create_request`` 将提示作为令牌 ID，且每个 ``post_completion`` 必须报告每个生成令牌的 ``token_id``。该示例通过传递 ``--return-tokens-as-token-ids`` 直接从 vLLM 获取这些 ID。否则，如果 vLLM 仅返回文本，则 ``post_completion`` 必须将每个生成的令牌重新标记为令牌 ID。"
+
+#: ../../source/mp/sdk.rst:101
+msgid "Writing a custom edit function"
+msgstr "编写自定义编辑函数"
+
+#: ../../source/mp/sdk.rst:103
+msgid ""
+"An edit function takes the retrieved KV tensor and its token ids and "
+"returns the edited ``(kv, tokens)``. ``batch.modify(fn)`` applies it to "
+"every stream."
+msgstr "编辑函数接受检索到的 KV 张量及其令牌 ID，并返回编辑后的 ``(kv, tokens)``。 ``batch.modify(fn)`` 将其应用于每个流。"
+
+#: ../../source/mp/sdk.rst:106
+msgid ""
+"``modify`` operates only on the **chunk-aligned** prefix. A trailing "
+"partial chunk is tracked by the SDK and re-sent on the next ``decode``, "
+"so ``tokens`` arrives already truncated to the cached length."
+msgstr "``modify`` 仅在 **块对齐** 前缀上操作。尾部的部分块由 SDK 跟踪，并在下一个 ``解码`` 时重新发送，因此 ``tokens`` 已经被截断到缓存的长度。"
+
+#: ../../source/mp/sdk.rst:112
+msgid "API reference"
+msgstr "API 参考"
+
+#: ../../source/mp/sdk.rst:118
+msgid "Function / method"
+msgstr "函数 / 方法"
+
+#: ../../source/mp/sdk.rst:119
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/sdk.rst:120
+msgid "``lmc_sdk.connect(url, http_url, model_name, timeout=60.0)``"
+msgstr "``lmc_sdk.connect(url, http_url, model_name, timeout=60.0)``"
+
+#: ../../source/mp/sdk.rst:121
+msgid ""
+"Create an SDK context and register the transfer context, pass it to every"
+" other call."
+msgstr "创建一个 SDK 上下文并注册传输上下文，将其传递给每个其他调用。"
+
+#: ../../source/mp/sdk.rst:123
+msgid "``lmc_sdk.close(ctx)``"
+msgstr "``lmc_sdk.close(ctx)``"
+
+#: ../../source/mp/sdk.rst:124
+msgid "Close the context and release resources. Called when done with the SDK."
+msgstr "关闭上下文并释放资源。在完成 SDK 的使用时调用。"
+
+#: ../../source/mp/sdk.rst:125
+msgid ""
+"``lmc_stream.create_request(ctx, post_completion, prompt_token_ids, "
+"cache_salt=\"\")``"
+msgstr "``lmc_stream.create_request(ctx, post_completion, prompt_token_ids, cache_salt=\"\")``"
+
+#: ../../source/mp/sdk.rst:127
+msgid "Create one request stream to add to a batch."
+msgstr "创建一个请求流以添加到批处理中。"
+
+#: ../../source/mp/sdk.rst:128
+msgid "``lmc_batch.LMCacheBatchedStream()``"
+msgstr "``lmc_batch.LMCacheBatchedStream()``"
+
+#: ../../source/mp/sdk.rst:129
+msgid "Create an empty batch."
+msgstr "创建一个空批次。"
+
+#: ../../source/mp/sdk.rst:130
+msgid "``batch.add(stream)``"
+msgstr "``batch.add(stream)``"
+
+#: ../../source/mp/sdk.rst:131
+msgid "Register a stream to the batch."
+msgstr "将流注册到批处理中。"
+
+#: ../../source/mp/sdk.rst:132
+msgid "``batch.prefill(sampling_params)``"
+msgstr "``batch.prefill(sampling_params)``"
+
+#: ../../source/mp/sdk.rst:133
+msgid ""
+"Prefill every stream once (``max_tokens`` forced to 1). Returns a "
+"``Metrics`` report."
+msgstr "一次 Prefill 每个流（``max_tokens`` 强制为 1）。返回一个 ``Metrics`` 报告。"
+
+#: ../../source/mp/sdk.rst:135
+msgid "``batch.modify(fn)``"
+msgstr "``batch.modify(fn)``"
+
+#: ../../source/mp/sdk.rst:136
+msgid ""
+"Apply the edit function ``fn`` to every stream's cached KV. Returns a "
+"``Metrics`` report."
+msgstr "将编辑函数 ``fn`` 应用到每个流的缓存 KV。返回一个 ``Metrics`` 报告。"
+
+#: ../../source/mp/sdk.rst:138
+msgid "``batch.decode(sampling_params)``"
+msgstr "``batch.decode(sampling_params)``"
+
+#: ../../source/mp/sdk.rst:139
+msgid "Decode every stream. Returns a ``Metrics`` report."
+msgstr "解码每个流。返回一个 ``Metrics`` 报告。"
+
+#: ../../source/mp/sdk.rst:141
+msgid ""
+"```Metrics`` returns ``input_tokens``, ``input_tput`` for prefill, "
+"``duration`` for modify, and ``output_tokens``, ``output_tput`` for "
+"decode."
+msgstr "```Metrics``` 返回 ``input_tokens``、``input_tput`` 用于 Prefill，``duration`` 用于修改，以及 ``output_tokens``、``output_tput`` 用于解码。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/serde.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/serde.po
new file mode 100644
index 0000000..9e85b48
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/serde.po
@@ -0,0 +1,275 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-29 10:44+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/serde.rst:2
+msgid "KV Cache Compression"
+msgstr "KV Cache 压缩"
+
+#: ../../source/mp/serde.rst:4
+msgid ""
+"LMCache supports a **per-adapter serde** that transforms KV cache data on"
+" its way to and from an L2 adapter. Typical uses: quantization (shrink "
+"storage footprint), compression, encryption."
+msgstr ""
+"LMCache 支持 **按适配器独立配置的 serde**\\ ，在 KV Cache 数据进出 L2 "
+"适配器时对其进行转换。典型用途：量化（缩小存储占用）、压缩、加密。"
+
+#: ../../source/mp/serde.rst:14
+msgid "When to use serde"
+msgstr "何时使用 serde"
+
+#: ../../source/mp/serde.rst:16
+msgid ""
+"**Save L2 storage or bandwidth.** fp8 quantization halves byte volume vs."
+" bf16 with minor accuracy loss — a good fit for disk / remote adapters."
+msgstr "**节省 L2 存储或带宽。** fp8 量化相比于 bf16 将字节体积减半，且准确度损失较小——非常适合磁盘/远程适配器。"
+
+#: ../../source/mp/serde.rst:19
+msgid ""
+"**Encrypt at rest.** Wrap the raw bytes with authenticated encryption "
+"before they land on disk."
+msgstr "**静态加密。** 在原始字节写入磁盘之前，使用经过身份验证的加密进行包装。"
+
+#: ../../source/mp/serde.rst:21
+msgid ""
+"**Custom compression.** Anything lossless (lz4/zstd) or lossy (CacheGen-"
+"style) can be plugged in via the ``Serializer`` / ``Deserializer`` ABCs."
+msgstr ""
+"**自定义压缩。** 任何无损（lz4/zstd）或有损（CacheGen 风格）都可以通过 ``Serializer`` / "
+"``Deserializer`` ABC 插入。"
+
+#: ../../source/mp/serde.rst:25
+msgid ""
+"Serde is **opt-in per adapter**: one ``--l2-adapter`` may use fp8 while "
+"another stores raw bytes. When omitted, the adapter behaves exactly as if"
+" serde did not exist (no extra allocations, no extra threads)."
+msgstr ""
+"Serde 是 **按适配器可选启用** 的：一个 ``--l2-adapter`` 可以使用 "
+"fp8，而另一个则存储原始字节。若省略，适配器行为与未使用 serde 时完全一致（无额外内存分配，无额外线程）。"
+
+#: ../../source/mp/serde.rst:31
+msgid "Configuring serde on an L2 adapter"
+msgstr "在 L2 适配器上配置 serde"
+
+#: ../../source/mp/serde.rst:33
+msgid ""
+"Add a ``\"serde\"`` sub-dict to any ``--l2-adapter`` JSON spec. The "
+"``type`` field selects a registered serde; remaining keys are forwarded "
+"to the serde factory."
+msgstr ""
+"向任何 ``--l2-adapter`` JSON 规范添加一个 ``\"serde\"`` 子字典。\\ ``type`` 字段选择一个已注册的"
+" serde；其余键将转发到 serde 工厂。"
+
+#: ../../source/mp/serde.rst:48
+msgid "Built-in serde types"
+msgstr "内置 serde 类型"
+
+#: ../../source/mp/serde.rst:52
+msgid "``type``"
+msgstr "``type``"
+
+#: ../../source/mp/serde.rst:53
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/mp/serde.rst:54
+msgid "Config fields"
+msgstr "配置字段"
+
+#: ../../source/mp/serde.rst:55
+msgid "``fp8``"
+msgstr "``fp8``"
+
+#: ../../source/mp/serde.rst:56
+msgid ""
+"Quantize each element to 8-bit float; dequantize on load. Lossy but "
+"highly compressible."
+msgstr "将每个元素量化为 8 位浮点数；在加载时反量化。虽然有损，但高度可压缩。"
+
+#: ../../source/mp/serde.rst:58
+msgid ""
+"``fp8_dtype`` (default ``float8_e4m3fn``; also accepts ``float8_e5m2``), "
+"``max_workers`` (thread pool size, default 1)"
+msgstr ""
+"``fp8_dtype``\\ （默认 ``float8_e4m3fn``\\ ；也接受 ``float8_e5m2``\\ ），\\ "
+"``max_workers``\\ （线程池大小，默认 1）"
+
+#: ../../source/mp/serde.rst:61
+msgid "``turboquant``"
+msgstr "``turboquant``"
+
+#: ../../source/mp/serde.rst:62
+msgid ""
+"Compress KV tensors with TurboQuant presets before L2 store and "
+"reconstruct them on load."
+msgstr "在 L2 存储之前使用 TurboQuant 预设压缩 KV 张量，并在加载时重构它们。"
+
+#: ../../source/mp/serde.rst:64
+msgid ""
+"``preset`` (default ``turboquant_k8v4``), ``head_dim`` (optional, default"
+" 128), ``block_size`` (default 16), ``max_workers`` (thread pool size, "
+"default 1)"
+msgstr "``preset``（默认 ``turboquant_k8v4``），``head_dim``（可选，默认 128），``block_size``（默认 16），``max_workers``（线程池大小，默认 1）"
+
+#: ../../source/mp/serde.rst:70
+msgid "TurboQuant serde"
+msgstr "TurboQuant 序列化与反序列化"
+
+#: ../../source/mp/serde.rst:72
+msgid ""
+"TurboQuant serde can be enabled by setting ``\"type\": \"turboquant\"`` "
+"in the adapter serde config. If ``preset`` is omitted, TurboQuant serde "
+"defaults to ``turboquant_k8v4``."
+msgstr "TurboQuant serde 可以通过在适配器 serde 配置中设置 ``\"type\": \"turboquant\"`` 来启用。如果省略 ``preset``，TurboQuant serde 默认使用 ``turboquant_k8v4``。"
+
+#: ../../source/mp/serde.rst:91
+msgid "Supported presets:"
+msgstr "支持的预设："
+
+#: ../../source/mp/serde.rst:97
+msgid "Preset"
+msgstr "预设"
+
+#: ../../source/mp/serde.rst:98
+msgid "Key path"
+msgstr "键路径"
+
+#: ../../source/mp/serde.rst:99
+msgid "Value path"
+msgstr "值路径"
+
+#: ../../source/mp/serde.rst:100
+msgid "``turboquant_k8v4``"
+msgstr "``turboquant_k8v4``"
+
+#: ../../source/mp/serde.rst:101
+msgid "FP8 key"
+msgstr "FP8 键"
+
+#: ../../source/mp/serde.rst:102 ../../source/mp/serde.rst:105
+#: ../../source/mp/serde.rst:108
+msgid "4-bit value quantization"
+msgstr "4位值量化"
+
+#: ../../source/mp/serde.rst:103
+msgid "``turboquant_4bit_nc``"
+msgstr "``turboquant_4bit_nc``"
+
+#: ../../source/mp/serde.rst:104
+msgid "4-bit MSE key with norm correction"
+msgstr "带有范数校正的 4 位 MSE 键"
+
+#: ../../source/mp/serde.rst:106
+msgid "``turboquant_k3v4_nc``"
+msgstr "``turboquant_k3v4_nc``"
+
+#: ../../source/mp/serde.rst:107 ../../source/mp/serde.rst:110
+msgid "3-bit MSE key with norm correction"
+msgstr "带有范数校正的 3 位 MSE 密钥"
+
+#: ../../source/mp/serde.rst:109
+msgid "``turboquant_3bit_nc``"
+msgstr "``turboquant_3bit_nc``"
+
+#: ../../source/mp/serde.rst:111
+msgid "3-bit value quantization"
+msgstr "3位值量化"
+
+#: ../../source/mp/serde.rst:115
+msgid "Writing a custom serde"
+msgstr "编写自定义 serde"
+
+#: ../../source/mp/serde.rst:117
+msgid ""
+"Implement the two sync ABCs (``Serializer``, ``Deserializer``) with your "
+"transform logic, then register a factory keyed on a name you pick:"
+msgstr ""
+"实现两个同步 ABC（\\ ``Serializer``\\ ，\\ ``Deserializer``\\ "
+"），并使用您的转换逻辑，然后注册一个以您选择的名称为键的工厂："
+
+#: ../../source/mp/serde.rst:149
+msgid "Reference it from your adapter config:"
+msgstr "从您的适配器配置中引用它："
+
+#: ../../source/mp/serde.rst:157
+msgid "Notes"
+msgstr "注意事项"
+
+#: ../../source/mp/serde.rst:159
+msgid ""
+"**Buffer size.** ``estimate_serialized_size(layout)`` must return an "
+"upper bound on the actual serialized output — include any safety margin "
+"directly in the estimate (e.g., the built-in fp8 serializer returns ``1.5"
+" * num_elements``)."
+msgstr ""
+"**缓冲区大小。** ``estimate_serialized_size(layout)`` "
+"必须返回实际序列化输出的上限——安全余量应直接计入估算值（例如，内置的 fp8 序列化器返回 ``1.5 * num_elements``\\ "
+"）。"
+
+#: ../../source/mp/serde.rst:163
+msgid ""
+"**Failure handling.** If any step fails (serialize, store, load, or "
+"deserialize), the whole submitted batch is reported as failed — partial "
+"success within one batch is not surfaced. Failed keys are cleaned up "
+"automatically."
+msgstr ""
+"**失败处理。** "
+"如果任何步骤失败（序列化、存储、加载或反序列化），整个提交的批次均报告为失败——批次内的部分成功不会对外呈现。失败的键会自动清理。"
+
+#: ../../source/mp/serde.rst:167
+msgid ""
+"**Thread pool.** ``AsyncSerdeProcessor(max_workers=N)`` controls the pool"
+" size. Transforms that release the GIL (e.g., torch ops) benefit from ``N"
+" > 1``; pure-Python transforms do not."
+msgstr ""
+"**线程池。** ``AsyncSerdeProcessor(max_workers=N)`` "
+"控制池的大小。释放全局解释器锁（GIL）的变换（例如，torch 操作）可以从 ``N > 1`` 中受益；纯 Python 变换则不然。"
+
+#: ../../source/mp/serde.rst:173
+msgid "Example"
+msgstr "示例"
+
+#: ../../source/mp/serde.rst:175
+msgid ""
+"An end-to-end script that starts an lmcache server with fp8 on a disk "
+"adapter, runs vLLM, clears L1, and re-runs the same request to trigger "
+"the L2 prefetch + fp8 deserialize path lives at "
+":file:`examples/serde/fp8/`. A pytest-based filesystem round-trip test "
+"(no vLLM required) is at "
+":file:`tests/v1/distributed/serde/test_serde_fs_e2e.py`."
+msgstr ""
+"一个端到端的脚本，它在磁盘适配器上启动一个带有 fp8 的 lmcache 服务器，运行 vLLM，清除 L1，然后重新运行相同的请求以触发 L2"
+" 预取 + fp8 反序列化路径，位于 :file:`examples/serde/fp8/`。一个基于 pytest 的文件系统往返测试（不需要"
+" vLLM）位于 :file:`tests/v1/distributed/serde/test_serde_fs_e2e.py`。"
+
+#: ../../source/mp/serde.rst:183
+msgid "Compression methods"
+msgstr "压缩方法"
+
+#: ../../source/mp/serde.rst:185
+msgid ""
+"Higher-level KV cache compression methods layered on top of the per-"
+"adapter serde mechanism:"
+msgstr "构建于按适配器 serde 机制之上的高阶 KV Cache 压缩方法："
+
+#~ msgid "L2 Serde (Serialization / Deserialization)"
+#~ msgstr "L2 序列化（Serialization / Deserialization）"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/mp/tracing_and_debugging.po b/docs/source/locale/zh_CN/LC_MESSAGES/mp/tracing_and_debugging.po
new file mode 100644
index 0000000..2d539eb
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/mp/tracing_and_debugging.po
@@ -0,0 +1,489 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-15 11:17+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/mp/tracing_and_debugging.rst:2
+msgid "Tracing and Debugging"
+msgstr "追踪和调试"
+
+#: ../../source/mp/tracing_and_debugging.rst:4
+msgid ""
+"LMCache MP mode can record every ``StorageManager`` public-API call to a "
+"binary **trace file** and reissue those calls later against a fresh "
+"server via ``lmcache trace replay``. The feature is designed for:"
+msgstr ""
+"LMCache MP 模式可以将每个 ``StorageManager`` 公共 API 调用记录到一个二进制 **跟踪文件** 中，并通过 "
+"``lmcache trace replay`` 在新服务器上重新发出这些调用。该功能旨在用于："
+
+#: ../../source/mp/tracing_and_debugging.rst:8
+msgid ""
+"**Regression hunting** — capture a production workload, then replay it "
+"against a build under investigation to reproduce a bug offline."
+msgstr "**回归排查** — 捕获生产工作负载，然后在调查中的构建上重放，以离线重现错误。"
+
+#: ../../source/mp/tracing_and_debugging.rst:10
+msgid ""
+"**Performance characterization** — measure L1/L2 latency distributions "
+"under a realistic storage-level access pattern, without needing vLLM or a"
+" GPU."
+msgstr "**性能特征化** — 在真实的存储级访问模式下测量 L1/L2 延迟分布，无需 vLLM 或 GPU。"
+
+#: ../../source/mp/tracing_and_debugging.rst:13
+msgid ""
+"**Configuration tuning** — replay the same trace against different L1 "
+"sizes, eviction policies, and L2 adapters to compare their behavior on "
+"identical input."
+msgstr "**配置调整** — 针对不同的 L1 大小、逐出策略和 L2 适配器重放相同的跟踪，以比较它们在相同输入下的行为。"
+
+#: ../../source/mp/tracing_and_debugging.rst:19
+msgid ""
+"Trace recording is **independent** from ``--enable-tracing`` (OTel "
+"spans). OTel tracing exports *live* spans to an OTLP endpoint for online "
+"observability; trace recording persists a replayable binary file for "
+"offline analysis. Both can be enabled simultaneously."
+msgstr "跟踪记录与 ``--enable-tracing``\\ （OTel spans）是 **独立** 的。OTel 跟踪将实时 spans 导出到 OTLP 端点以进行在线可观察性；跟踪记录则持久化一个可重放的二进制文件以供离线分析。两者可以同时启用。"
+
+#: ../../source/mp/tracing_and_debugging.rst:28
+msgid "Recording a Trace"
+msgstr "记录跟踪"
+
+#: ../../source/mp/tracing_and_debugging.rst:30
+msgid ""
+"Recording is **off by default**. Enable it by adding ``--trace-level "
+"storage`` to ``lmcache server``:"
+msgstr "记录默认是\\ **关闭的**\\ 。通过将\\ ``--trace-level storage``\\ 添加到\\ ``lmcache server``\\ 来启用它："
+
+#: ../../source/mp/tracing_and_debugging.rst:48
+msgid ""
+"Drive traffic through the server as usual (vLLM requests, benchmark "
+"scripts, etc.). The trace file is closed cleanly on ``SIGTERM`` via the "
+"EventBus stop path — no ``--stop-tracing`` command needed."
+msgstr ""
+"通过服务器正常驱动流量（vLLM 请求、基准测试脚本等）。在通过 EventBus 停止路径接收到 ``SIGTERM`` "
+"时，跟踪文件会被干净地关闭 — 不需要 ``--stop-tracing`` 命令。"
+
+#: ../../source/mp/tracing_and_debugging.rst:52
+msgid "**What is captured:**"
+msgstr "**捕获的内容：**"
+
+#: ../../source/mp/tracing_and_debugging.rst:54
+msgid ""
+"The fully-qualified name of every decorated ``StorageManager`` call (e.g."
+" ``StorageManager.reserve_write``, "
+"``StorageManager.submit_prefetch_task``)."
+msgstr "每个被装饰的 ``StorageManager`` 调用的完全限定名称（例如 ``StorageManager.reserve_write``\\ 、\\ ``StorageManager.submit_prefetch_task``\\ ）。"
+
+#: ../../source/mp/tracing_and_debugging.rst:57
+msgid ""
+"Each call's input arguments (``keys``, ``layout_desc``, ``mode``, "
+"``extra_count``, ``external_request_id``, …)."
+msgstr "每个调用的输入参数（\\ ``keys``, ``layout_desc``, ``mode``, ``extra_count``, ``external_request_id``, …）。"
+
+#: ../../source/mp/tracing_and_debugging.rst:59
+msgid "Wall-clock and monotonic timestamps per call."
+msgstr "每次调用的墙钟时间和单调时间戳。"
+
+#: ../../source/mp/tracing_and_debugging.rst:60
+msgid ""
+"A header with the file format version, trace schema version, start "
+"timestamps, and a SHA-256 digest of the active ``StorageManagerConfig`` "
+"so replay can flag mismatched configurations."
+msgstr ""
+"一个包含文件格式版本、跟踪模式版本、开始时间戳以及活动的 ``StorageManagerConfig`` 的 SHA-256 "
+"摘要的头部，以便重放可以标记不匹配的配置。"
+
+#: ../../source/mp/tracing_and_debugging.rst:65
+msgid "**What is not captured:**"
+msgstr "**未捕获的内容：**"
+
+#: ../../source/mp/tracing_and_debugging.rst:67
+msgid ""
+"**KV tensor bytes.** Replay exercises bookkeeping and controller logic; "
+"payloads at replay time are zeros. The trace file stays bounded even for "
+"long runs."
+msgstr "**KV 张量字节。** 重放练习的记账和控制逻辑；重放时的有效载荷为零。即使在长时间运行的情况下，跟踪文件也保持有限。"
+
+#: ../../source/mp/tracing_and_debugging.rst:70
+msgid ""
+"Calls inside ``MPCacheServer``, the message queue, or GPU-copy code. "
+"Those layers are out of scope for the ``storage`` trace level."
+msgstr "``MPCacheServer``\\ 、消息队列或显存复制代码中的调用。这些层超出了 ``storage`` 跟踪级别的范围。"
+
+#: ../../source/mp/tracing_and_debugging.rst:73
+msgid "**Overhead:**"
+msgstr "**开销：**"
+
+#: ../../source/mp/tracing_and_debugging.rst:75
+msgid "Off: a single boolean check per ``StorageManager`` call. Effectively free."
+msgstr "关闭：每次 ``StorageManager`` 调用进行一次布尔检查。实际上是免费的。"
+
+#: ../../source/mp/tracing_and_debugging.rst:76
+msgid ""
+"On: encoding and file I/O happen on the EventBus drain thread, off the "
+"request path. In practice this has no visible impact on request latency."
+msgstr "开启：编码和文件 I/O 在 EventBus 排水线程上进行，不在请求路径上。实际上，这对请求延迟没有明显影响。"
+
+#: ../../source/mp/tracing_and_debugging.rst:81
+msgid "Inspecting a Trace"
+msgstr "检查追踪"
+
+#: ../../source/mp/tracing_and_debugging.rst:83
+msgid "Before replaying, ``lmcache trace info`` prints a one-screen summary:"
+msgstr "在重放之前，\\ ``lmcache trace info`` 打印一个一屏的摘要："
+
+#: ../../source/mp/tracing_and_debugging.rst:106
+msgid ""
+"Use this to sanity-check that the trace you intend to replay covers the "
+"expected operation mix and duration."
+msgstr "使用此功能来检查您打算重放的跟踪是否涵盖了预期的操作组合和持续时间。"
+
+#: ../../source/mp/tracing_and_debugging.rst:110
+msgid "Replaying a Trace"
+msgstr "重放跟踪"
+
+#: ../../source/mp/tracing_and_debugging.rst:112
+msgid ""
+"``lmcache trace replay FILE`` reissues every recorded call against a "
+"**fresh** ``StorageManager`` built from CLI flags you supply. The replay-"
+"side config is **chosen by you**, not copied from the recording. This is "
+"the feature's main value — you can compare different L1/L2 setups on "
+"identical input."
+msgstr "``lmcache trace replay FILE`` 重新发出每个记录的调用，使用您提供的 CLI 标志构建的 **全新** ``StorageManager``\\ 。重放端的配置由 **您选择**\\ ，而不是从录音中复制。这是该功能的主要价值——您可以在相同的输入上比较不同的 L1/L2 设置。"
+
+#: ../../source/mp/tracing_and_debugging.rst:118
+msgid "Minimal invocation:"
+msgstr "最小调用："
+
+#: ../../source/mp/tracing_and_debugging.rst:125
+msgid ""
+"``--l1-size-gb`` and ``--eviction-policy`` are required, just like on "
+"``lmcache server``. Any storage-manager flag accepted by the server also "
+"works here (``--l2-adapter``, ``--l1-use-lazy``, ``--l2-store-policy``, "
+"…); run ``lmcache trace replay --help`` for the full list."
+msgstr "``--l1-size-gb`` 和 ``--eviction-policy`` 是必需的，就像在 ``lmcache server`` 上一样。服务器接受的任何存储管理器标志在这里也有效（\\ ``--l2-adapter``\\ 、\\ ``--l1-use-lazy``\\ 、\\ ``--l2-store-policy`` 等）；运行 ``lmcache trace replay --help`` 获取完整列表。"
+
+#: ../../source/mp/tracing_and_debugging.rst:131
+msgid ""
+"**Pacing.** The driver always honors the recorded inter-call timings by "
+"sleeping to align each dispatch with its recorded ``t_mono`` offset. "
+"There is **no** as-fast-as-possible mode: ``StorageManager`` reads and "
+"writes are asynchronous and carry cross-call dependencies (for example, a"
+" retrieve may depend on an earlier L2 load completing), so collapsing the"
+" recorded gaps races the internal queues and causes non-deterministic "
+"retrieve misses. If the replay host is slower than the recording host, "
+"the loop simply lags the recorded schedule."
+msgstr "**节奏控制。** 驱动程序始终遵循记录的调用间隔时间，通过休眠来使每次调度与其记录的 ``t_mono`` 偏移对齐。没有“尽可能快”的模式：\\ ``StorageManager`` 的读写是异步的，并且存在跨调用依赖关系（例如，检索可能依赖于先前的 L2 加载完成），因此压缩记录的间隔会导致内部队列竞争，从而导致非确定性的检索未命中。如果重放主机比记录主机慢，循环会简单地滞后于记录的时间表。"
+
+#: ../../source/mp/tracing_and_debugging.rst:140
+msgid ""
+"**Output.** Every replay prints a terminal metrics table and writes a "
+"per-qualname CSV by default:"
+msgstr "**输出。** 每次重放默认都会打印一个终端指标表，并写入每个 qualname 的 CSV："
+
+#: ../../source/mp/tracing_and_debugging.rst:160
+msgid "Additional per-record output is controlled by:"
+msgstr "每条记录的附加输出由以下内容控制："
+
+#: ../../source/mp/tracing_and_debugging.rst:166
+#: ../../source/mp/tracing_and_debugging.rst:215
+msgid "Flag"
+msgstr "标志"
+
+#: ../../source/mp/tracing_and_debugging.rst:167
+msgid "Purpose"
+msgstr "目的"
+
+#: ../../source/mp/tracing_and_debugging.rst:168
+msgid "``--output-dir DIR``"
+msgstr "``--output-dir DIR``"
+
+#: ../../source/mp/tracing_and_debugging.rst:169
+msgid "Directory for aggregated summary files. Default: current dir."
+msgstr "聚合摘要文件的目录。默认：当前目录。"
+
+#: ../../source/mp/tracing_and_debugging.rst:170
+msgid "``--no-csv``"
+msgstr "``--no-csv``"
+
+#: ../../source/mp/tracing_and_debugging.rst:171
+msgid "Skip the ``trace_replay_ops.csv`` export."
+msgstr "跳过 ``trace_replay_ops.csv`` 导出。"
+
+#: ../../source/mp/tracing_and_debugging.rst:172
+msgid "``--json``"
+msgstr "``--json``"
+
+#: ../../source/mp/tracing_and_debugging.rst:173
+msgid ""
+"Also write ``trace_replay_summary.json`` (per-qualname count / mean / p50"
+" / p90 / p99 / min / max, plus total duration)."
+msgstr "还会写入 ``trace_replay_summary.json``\\ （按资格名称的计数 / 平均值 / p50 / p90 / p99 / 最小值 / 最大值，以及总持续时间）。"
+
+#: ../../source/mp/tracing_and_debugging.rst:176
+msgid "``--verbose``"
+msgstr "``--verbose``"
+
+#: ../../source/mp/tracing_and_debugging.rst:177
+msgid ""
+"Print one ``[N/total] OK|FAIL <qualname> (Xms)`` line per record to "
+"stdout in addition to the INFO log."
+msgstr "除了 INFO 日志外，还将每条记录打印一行 ``[N/total] OK|FAIL <qualname> (Xms)`` 到 stdout。"
+
+#: ../../source/mp/tracing_and_debugging.rst:179
+msgid "``--jsonl-out PATH``"
+msgstr "``--jsonl-out PATH``"
+
+#: ../../source/mp/tracing_and_debugging.rst:180
+#, python-brace-format
+msgid ""
+"Write one JSON object per replayed record to ``PATH`` (``{qualname, "
+"latency_ms, failed}``) for post-hoc analysis."
+msgstr ""
+"将每个重放记录写入一个 JSON 对象到 ``PATH`` (``{qualname, latency_ms, "
+"failed}``)，以便进行事后分析。"
+
+#: ../../source/mp/tracing_and_debugging.rst:183
+msgid "``-q`` / ``--quiet``"
+msgstr "``-q`` / ``--quiet``"
+
+#: ../../source/mp/tracing_and_debugging.rst:184
+msgid ""
+"Suppress the terminal metrics table. The aggregated files are still "
+"written."
+msgstr "抑制终端指标表。聚合文件仍然会被写入。"
+
+#: ../../source/mp/tracing_and_debugging.rst:187
+msgid "Even without ``--verbose``, the driver logs each dispatch at INFO:"
+msgstr "即使没有 ``--verbose``\\ ，驱动程序也会在 INFO 级别记录每个调度。"
+
+#: ../../source/mp/tracing_and_debugging.rst:195
+msgid ""
+"Progress numbers come from a cheap pre-scan of the trace file, so you "
+"always see ``[N/total]`` rather than just a running counter."
+msgstr "进度数字来自对跟踪文件的廉价预扫描，因此您总是看到 ``[N/total]`` 而不仅仅是一个运行计数器。"
+
+#: ../../source/mp/tracing_and_debugging.rst:199
+msgid "Monitoring During Replay"
+msgstr "重放期间的监控"
+
+#: ../../source/mp/tracing_and_debugging.rst:201
+msgid ""
+"The replay driver initializes the full observability EventBus **before** "
+"constructing the replay-side ``StorageManager``. Internal events (L1/L2 "
+"lifecycle, eviction ticks, store/retrieve publishes, etc.) therefore flow"
+" through a live bus during replay and the standard subscribers — logging,"
+" metrics, OTel tracing — can attach to them."
+msgstr ""
+"重放驱动程序在构造重放端 ``StorageManager`` 之前初始化了完整可观察性 EventBus。因此，内部事件（L1/L2 "
+"生命周期、逐出时钟、存储/检索发布等）在重放期间通过一个实时总线流动，标准订阅者——日志记录、指标、OTel 跟踪——可以附加到这些事件上。"
+
+#: ../../source/mp/tracing_and_debugging.rst:208
+msgid ""
+"The same observability CLI flags that the server accepts are available on"
+" ``lmcache trace replay``:"
+msgstr "在 ``lmcache trace replay`` 上可用的与服务器接受的相同可观察性 CLI 标志："
+
+#: ../../source/mp/tracing_and_debugging.rst:216
+msgid "Effect"
+msgstr "效果"
+
+#: ../../source/mp/tracing_and_debugging.rst:217
+msgid "``--disable-observability``"
+msgstr "``--disable-observability``"
+
+#: ../../source/mp/tracing_and_debugging.rst:218
+msgid "Turn the EventBus off entirely. No subscribers fire."
+msgstr "完全关闭 EventBus。没有订阅者会触发。"
+
+#: ../../source/mp/tracing_and_debugging.rst:219
+msgid "``--disable-metrics``"
+msgstr "``--disable-metrics``"
+
+#: ../../source/mp/tracing_and_debugging.rst:220
+msgid ""
+"Skip OTel metrics init and metrics subscribers. Useful to avoid binding "
+"the Prometheus port when you only want logs."
+msgstr "跳过 OTel 指标初始化和指标订阅者。对于仅想要日志时，避免绑定 Prometheus 端口非常有用。"
+
+#: ../../source/mp/tracing_and_debugging.rst:222
+msgid "``--disable-logging``"
+msgstr "``--disable-logging``"
+
+#: ../../source/mp/tracing_and_debugging.rst:223
+msgid "Skip logging subscribers."
+msgstr "跳过日志订阅者。"
+
+#: ../../source/mp/tracing_and_debugging.rst:224
+msgid "``--enable-tracing``"
+msgstr "``--enable-tracing``"
+
+#: ../../source/mp/tracing_and_debugging.rst:225
+msgid "Enable OTel span subscribers. Requires ``--otlp-endpoint``."
+msgstr "启用 OTel span 订阅者。需要 ``--otlp-endpoint``\\ 。"
+
+#: ../../source/mp/tracing_and_debugging.rst:226
+msgid "``--otlp-endpoint URL``"
+msgstr "``--otlp-endpoint URL``"
+
+#: ../../source/mp/tracing_and_debugging.rst:227
+msgid ""
+"Export metrics/traces to an OTLP gRPC collector (e.g. "
+"``http://localhost:4317``). When unset, metrics fall back to the in-"
+"process Prometheus pull endpoint."
+msgstr "将指标/追踪导出到 OTLP gRPC 收集器（例如 ``http://localhost:4317``\\ ）。如果未设置，指标将回退到进程内的 Prometheus 拉取端点。"
+
+#: ../../source/mp/tracing_and_debugging.rst:230
+msgid "``--prometheus-port PORT``"
+msgstr "``--prometheus-port PORT``"
+
+#: ../../source/mp/tracing_and_debugging.rst:231
+msgid ""
+"Port for the Prometheus ``/metrics`` endpoint in pull mode. Default "
+"``9090``."
+msgstr "用于拉取模式下 Prometheus ``/metrics`` 端点的端口。默认值为 ``9090``\\ 。"
+
+#: ../../source/mp/tracing_and_debugging.rst:233
+msgid "``--metrics-sample-rate FLOAT``"
+msgstr "``--metrics-sample-rate FLOAT``"
+
+#: ../../source/mp/tracing_and_debugging.rst:234
+msgid "Sampling rate for lifecycle histograms. Counters always count all events."
+msgstr "生命周期直方图的采样率。计数器始终计算所有事件。"
+
+#: ../../source/mp/tracing_and_debugging.rst:237
+msgid "Typical monitoring setups:"
+msgstr "典型的监控设置："
+
+#: ../../source/mp/tracing_and_debugging.rst:239
+msgid "**Raw log trail (SM/L1/L2 events to stdout):**"
+msgstr "**原始日志轨迹（SM/L1/L2 事件到 stdout）：**"
+
+#: ../../source/mp/tracing_and_debugging.rst:247
+msgid "**Prometheus metrics in pull mode:**"
+msgstr "**以拉取模式的 Prometheus 指标：**"
+
+#: ../../source/mp/tracing_and_debugging.rst:256
+msgid "**OTel metrics + traces to a collector:**"
+msgstr "**OTel 指标 + 跟踪到收集器：**"
+
+#: ../../source/mp/tracing_and_debugging.rst:267
+msgid ""
+"The ``--trace-level`` and ``--trace-output`` flags are **recording-only**"
+" and are not accepted by ``lmcache trace replay``. A replay never writes "
+"a new trace file."
+msgstr ""
+"``--trace-level`` 和 ``--trace-output`` 标志是 **仅记录** 的，不被 ``lmcache trace "
+"replay`` 接受。重放不会写入新的追踪文件。"
+
+#: ../../source/mp/tracing_and_debugging.rst:272
+msgid "Notes, Hints, and Caveats"
+msgstr "注意、提示和注意事项"
+
+#: ../../source/mp/tracing_and_debugging.rst:274
+msgid ""
+"**Retrieve misses are expected when the replay environment differs.** At "
+"replay start, the CLI prints a visible warning banner:"
+msgstr "**当重放环境不同时，预期会出现未命中的情况。** 在重放开始时，CLI 会打印一个可见的警告横幅："
+
+#: ../../source/mp/tracing_and_debugging.rst:283
+msgid ""
+"Because KV payloads are not captured and the replay-side config and host "
+"speed may differ from recording, retrieve calls that hit at record time "
+"can miss at replay time — for instance, an async L2 load that had "
+"finished by the time the recorded retrieve was issued may still be in "
+"flight when the replayed retrieve fires. Treat retrieve-miss counts as a "
+"signal about the replay environment, **not** as a defect in the trace."
+msgstr "由于 KV 负载未被捕获，并且重放端的配置和主机速度可能与录制时不同，因此在录制时命中的检索调用在重放时可能会未命中——例如，在录制的检索发出时已完成的异步 L2 加载在重放的检索触发时可能仍在进行中。将未命中的检索计数视为重放环境的信号，\\ **而不是**\\ 跟踪中的缺陷。"
+
+#: ../../source/mp/tracing_and_debugging.rst:291
+msgid ""
+"**Config-digest mismatch is informational, not fatal.** The replay always"
+" runs whether the digests match or not. A mismatch simply tells you the "
+"replay-side ``StorageManagerConfig`` differs from what was recorded — "
+"often exactly what you intended (comparing two configs on the same "
+"trace)."
+msgstr ""
+"**配置摘要不匹配是信息性的，而不是致命的。** 无论摘要是否匹配，重放始终会运行。 不匹配仅告诉您重放端的 "
+"``StorageManagerConfig`` 与记录时不同——这通常正是您所期望的（在同一跟踪上比较两个配置）。"
+
+#: ../../source/mp/tracing_and_debugging.rst:297
+msgid ""
+"**Prometheus port binding.** The server's ``--prometheus-port`` defaults "
+"to ``9090``. Running ``lmcache trace replay`` concurrently with the "
+"server — or running two replays at once — on the same port will fail. "
+"Either pass a different ``--prometheus-port`` or ``--disable-metrics`` on"
+" the secondary runs."
+msgstr "**Prometheus 端口绑定。** 服务器的 ``--prometheus-port`` 默认值为 ``9090``\\ 。在同一端口上与服务器并发运行 ``lmcache trace replay`` 或同时运行两个重放将会失败。请在第二次运行时传递不同的 ``--prometheus-port`` 或 ``--disable-metrics``\\ 。"
+
+#: ../../source/mp/tracing_and_debugging.rst:303
+msgid ""
+"**Trace-recording overhead.** Recording happens on the EventBus drain "
+"thread, not the request-handling threads. The gate is a single boolean "
+"check when disabled (default), so production builds with recording off "
+"pay no measurable cost."
+msgstr ""
+"**跟踪记录开销。** 记录发生在 EventBus "
+"排出线程上，而不是请求处理线程上。当禁用时（默认），门控是一个单一的布尔检查，因此关闭记录的生产构建不会产生可测量的成本。"
+
+#: ../../source/mp/tracing_and_debugging.rst:308
+msgid ""
+"**Trace files are not encrypted.** Arguments such as ``ObjectKey`` chunk "
+"hashes are written in plaintext. Treat trace files with the same care as "
+"cache hash logs."
+msgstr "**跟踪文件未加密。** 参数如 ``ObjectKey`` 块哈希以明文形式写入。请像对待缓存哈希日志一样小心处理跟踪文件。"
+
+#: ../../source/mp/tracing_and_debugging.rst:312
+msgid ""
+"**Forward compatibility.** The header carries a format version and a "
+"trace schema version. Readers reject files with unknown versions rather "
+"than silently producing garbage. Captured API surface changes (new "
+"arguments on a traced method, new codec tags) bump the schema version; "
+"framing changes bump the format version."
+msgstr ""
+"**向前兼容性。** 头部携带格式版本和追踪模式版本。读取器会拒绝未知版本的文件，而不是默默地产生垃圾。捕获的 API "
+"表面变化（追踪方法上的新参数、新的编解码器标签）会提升模式版本；框架变化会提升格式版本。"
+
+#: ../../source/mp/tracing_and_debugging.rst:318
+msgid ""
+"**Extensibility.** The format is designed to accommodate future trace "
+"**levels** (``mq``, ``gpu``). Adding a new traced method in an existing "
+"level requires only decorating it on the recording side and registering a"
+" handler on the replay side — no format changes."
+msgstr "**可扩展性。** 该格式旨在适应未来的追踪 **级别**\\ （\\ ``mq``\\ 、\\ ``gpu``\\ ）。在现有级别中添加一个新的追踪方法只需在记录端进行装饰，并在重放端注册一个处理程序 — 无需格式更改。"
+
+#: ../../source/mp/tracing_and_debugging.rst:324
+msgid "See Also"
+msgstr "另请参阅"
+
+#: ../../source/mp/tracing_and_debugging.rst:326
+msgid ""
+":ref:`trace-recording` — the short ``Trace Recording`` section in the "
+"Observability page focuses on the recording-side flags."
+msgstr ":ref:`trace-recording` — 可观察性页面中的短小 ``Trace Recording`` 部分专注于记录端标志。"
+
+#: ../../source/mp/tracing_and_debugging.rst:328
+msgid ""
+"``docs/design/v1/mp_observability/trace.md`` in the source tree — full "
+"design doc: architecture, replay dispatcher, context-manager pairing, "
+"stats collector, and test matrix."
+msgstr ""
+"``docs/design/v1/mp_observability/trace.md`` 在源代码树中 — "
+"完整设计文档：架构、重放调度器、上下文管理器配对、统计收集器和测试矩阵。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/encoder_cache.po b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/encoder_cache.po
new file mode 100644
index 0000000..77b1da7
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/encoder_cache.po
@@ -0,0 +1,332 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:2
+msgid "Encoder caching"
+msgstr "编码器缓存"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:6
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr ""
+
+#: ../../source/non_kv_cache/encoder_cache.rst:9
+msgid ""
+"The **Encoder Cache (EC)** stores the output of a multimodal model's "
+"encoder stage, keyed by vLLM's per-input ``mm_hash``. When two requests "
+"share a multimodal input — the same image, video, or audio clip — the "
+"second request loads the encoder output from the cache and the encoder "
+"does not run."
+msgstr ""
+"**编码器缓存 (EC)** 存储多模态模型编码器阶段的输出，按 vLLM 的每个输入 ``mm_hash`` "
+"进行索引。当两个请求共享一个多模态输入——相同的图像、视频或音频片段——第二个请求将从缓存中加载编码器输出，而编码器不会运行。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:15
+msgid ""
+"This applies to any modality vLLM exposes through its encoder-cache "
+"extension point: vision encoders (CLIP / ViT-style towers used for images"
+" and sampled video frames), audio encoders (Whisper-style towers used for"
+" raw waveforms), and combined-modality encoders such as Qwen2.5-Omni. The"
+" connector is modality-agnostic — it caches a tensor of shape "
+"``[num_tokens, hidden_dim]`` keyed by ``mm_hash``, without knowing which "
+"encoder produced it."
+msgstr ""
+"这适用于 vLLM 通过其编码器缓存扩展点暴露的任何模态：视觉编码器（用于图像和采样视频帧的 CLIP / ViT "
+"风格塔）、音频编码器（用于原始波形的 Whisper 风格塔）以及诸如 Qwen2.5-Omni "
+"的组合模态编码器。连接器是模态无关的——它缓存一个形状为 ``[num_tokens, hidden_dim]`` 的张量，键为 "
+"``mm_hash``\\ ，而不知道是哪个编码器生成的。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:23
+msgid ""
+"vLLM exposes the encoder-cache extension point via ``ECConnectorBase`` "
+"(vLLM v1 only). LMCache provides an ``LMCacheECConnector`` shim on the "
+"vLLM side and an ``ECCacheEngine`` on the LMCache side; together they "
+"back the encoder cache with any of LMCache's storage backends (local CPU,"
+" local disk, remote, NIXL)."
+msgstr ""
+"vLLM 通过 ``ECConnectorBase``\\ （仅限 vLLM v1）暴露了编码器缓存扩展点。LMCache 在 vLLM "
+"端提供了一个 ``LMCacheECConnector`` 适配器，在 LMCache 端提供了一个 ``ECCacheEngine``\\ "
+"；它们共同支持使用 LMCache 的任何存储后端（本地 CPU、本地磁盘、远程、NIXL）来备份编码器缓存。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:30
+msgid "Enabling it"
+msgstr "启用它"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:32
+msgid "Pass ``--ec-transfer-config`` to ``vllm serve``:"
+msgstr "将 ``--ec-transfer-config`` 传递给 ``vllm serve``\\ ："
+
+#: ../../source/non_kv_cache/encoder_cache.rst:43
+msgid ""
+"``ec_role`` choices: ``ec_producer`` (saves only), ``ec_consumer`` (reads"
+" only), ``ec_both`` (single-instance default)."
+msgstr ""
+"``ec_role`` 选项： ``ec_producer``\\ （仅保存）， ``ec_consumer``\\ （仅读取）， "
+"``ec_both``\\ （单实例默认）。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:46
+msgid ""
+"Set ``LMCACHE_CONFIG_FILE`` to point at a YAML with at least one storage "
+"backend configured for EC:"
+msgstr "将 ``LMCACHE_CONFIG_FILE`` 设置为指向一个配置了至少一个 EC 存储后端的 YAML 文件："
+
+#: ../../source/non_kv_cache/encoder_cache.rst:57
+msgid ""
+"To size EC storage independently from the (separate) KV cache, prefix "
+"overrides with ``ec_`` in YAML or ``LMCACHE_EC_`` in the environment "
+"(e.g. ``ec_max_local_disk_size: 64`` or "
+"``LMCACHE_EC_MAX_LOCAL_DISK_SIZE=64``). EC and KV always run with "
+"**separate** ``StorageManager`` instances so one cannot evict the other."
+msgstr ""
+"要独立于（单独的）KV Cache 调整 EC 存储大小，请在 YAML 中使用 ``ec_`` 前缀覆盖，或在环境中使用 "
+"``LMCACHE_EC_`` 前缀（例如 ``ec_max_local_disk_size: 64`` 或 "
+"``LMCACHE_EC_MAX_LOCAL_DISK_SIZE=64``\\ ）。EC 和 KV 始终在 **独立** 的 "
+"``StorageManager`` 实例中运行，因此一个不能逐出另一个。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:64
+msgid ""
+"If you don't set ``local_disk`` (or its EC override) the engine still "
+"starts, but EC entries live in CPU memory only and do not survive process"
+" restart. Set ``local_disk`` (or ``ec_local_disk``) to a real path if you"
+" want cache persistence — there is no implicit on-disk default location."
+msgstr ""
+"如果您不设置 ``local_disk``\\ （或其 EC 覆盖），引擎仍然会启动，但 EC 条目仅存在于 CPU "
+"内存中，并且在进程重启时不会保留。如果您希望缓存持久化，请将 ``local_disk``\\ （或 ``ec_local_disk``\\ "
+"）设置为一个真实路径——没有隐式的磁盘默认位置。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:71
+msgid "Verifying it's working"
+msgstr "验证它是否正常工作"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:73
+msgid "Three independent signals:"
+msgstr "三个独立信号："
+
+#: ../../source/non_kv_cache/encoder_cache.rst:75
+msgid ""
+"**vLLM metric.** ``loggers.py`` reports ``MM cache hit rate: X%`` after "
+"warm requests."
+msgstr "**vLLM 指标。** ``loggers.py`` 在预热请求后报告 ``MM 缓存命中率：X%``\\ 。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:77
+msgid ""
+"**LMCache log line.** Cold (first-time) requests emit ``LMCache INFO: EC "
+"put: stored N bytes for mm_hash=H``. Warm requests emit no ``EC put``."
+msgstr ""
+"**LMCache 日志行。** 冷（首次）请求会发出 ``LMCache INFO: EC put: stored N bytes for "
+"mm_hash=H``\\ 。热请求不会发出 ``EC put``\\ 。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:80
+msgid ""
+"**On-disk file.** Under ``local_disk`` an entry of the form "
+"``<model>@1@0@<chunk_hash>@<dtype>.pt`` appears after the first request "
+"and is reused thereafter. The ``@1@0@`` prefix reflects sentinel "
+"``world_size=1, worker_id=0`` in the EC cache key, so all tensor-parallel"
+" ranks share one entry."
+msgstr ""
+"**磁盘文件。** 在 ``local_disk`` 下，形式为 ``<model>@1@0@<chunk_hash>@<dtype>.pt`` "
+"的条目在第一次请求后出现，并在此后被重用。\\ ``@1@0@`` 前缀反映了 EC 缓存键中的哨兵 ``world_size=1, "
+"worker_id=0``\\ ，因此所有张量并行的 rank 共享一个条目。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:87
+msgid "Design notes (user-visible)"
+msgstr "设计说明（用户可见）"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:89
+msgid ""
+"**Cache key uses sentinel TP shape.** Encoder outputs are replicated "
+"across TP ranks, so the EC key uses ``world_size=1, worker_id=0`` "
+"regardless of the deployment's actual TP. Concurrent puts from N ranks "
+"land on the same key with identical contents."
+msgstr ""
+"**缓存键使用哨兵 TP 形状。** 编码器输出在 TP 排中复制，因此 EC 键使用 ``world_size=1, "
+"worker_id=0``\\ ，而不管部署的实际 TP。来自 N 个排名的并发放置会落在相同的键上，内容相同。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:94
+msgid ""
+"**Dtype decoupled from KV quant.** The dtype field of the EC cache key is"
+" the encoder output dtype (``vllm_config.model_config.dtype``), not "
+"``metadata.kv_dtype``. Changing KV quantization does not invalidate EC "
+"entries."
+msgstr ""
+"**数据类型与 KV 量化解耦。** EC 缓存键的 dtype 字段是编码器输出的数据类型（\\ "
+"``vllm_config.model_config.dtype``\\ ），而不是 ``metadata.kv_dtype``\\ 。更改 KV"
+" 量化不会使 EC 条目失效。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:98
+msgid ""
+"**Separate StorageManager from KV.** KV and EC have very different access"
+" patterns (KV chunked / layerwise / high-volume; EC single-tensor / "
+"request-scoped). Sharing one allocator pool would let one cache evict the"
+" other in unpredictable ways. Per-cache sizing knobs (``ec_max_local_*``)"
+" are explicit instead."
+msgstr ""
+"**将 StorageManager 与 KV 分离。** KV 和 EC 的访问模式非常不同（KV 是分块/逐层/高吞吐量；EC "
+"是单张张量/请求范围）。共享一个分配器池会导致一个缓存以不可预测的方式逐出另一个缓存。因此，针对每个缓存的大小调整参数（\\ "
+"``ec_max_local_*``\\ ）是明确的。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:103
+msgid ""
+"**Connector role pinned to \"worker\".** vLLM's ``ECConnectorBase`` is "
+"dual-role (scheduler and worker). The LMCache connector calls "
+"``create_lmcache_metadata(..., role=\"worker\")`` regardless, because the"
+" scheduler-side ``has_cache_item`` needs a fully constructed "
+"``StorageManager`` and LMCache currently aborts disk-backend setup when "
+"``metadata.role == \"scheduler\"``."
+msgstr ""
+"**连接器角色固定为“worker”。** vLLM 的 ``ECConnectorBase`` 是双角色（调度器和工作者）。LMCache "
+"连接器无论如何都会调用 ``create_lmcache_metadata(..., role=\\\"worker\\\")``\\ "
+"，因为调度器端的 ``has_cache_item`` 需要一个完全构造的 ``StorageManager``\\ ，而 LMCache 当前在"
+" ``metadata.role == \\\"scheduler\\\"`` 时会中止磁盘后端的设置。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:110
+msgid ""
+"The full internal design (class layering, code paths, follow-up work) "
+"lives at :file:`docs/design/v1/encoder-cache.md` in the source tree."
+msgstr "完整的内部设计（类层次、代码路径、后续工作）位于源代码树中的 :file:`docs/design/v1/encoder-cache.md`。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:114
+msgid "Benchmark"
+msgstr "基准测试"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:116
+msgid ""
+"Live measurement on a single H100 80GB with ``Qwen/Qwen2.5-VL-7B-"
+"Instruct`` (bf16) and Big Buck Bunny (10:34, 720p, ≈ 60 MB MP4). Same "
+"chat-completion request sent 1 cold + N warm times against the same vLLM "
+"server."
+msgstr ""
+"在一台单个 H100 80GB 上进行实时测量，使用 ``Qwen/Qwen2.5-VL-7B-Instruct``\\ "
+"（bf16）和《大雄兔的故事》（10:34，720p，≈ 60 MB MP4）。对同一 vLLM 服务器发送相同的聊天完成请求，1 次冷启动 + "
+"N 次热启动。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:121
+msgid ""
+"Two configurations, varying only ``num_frames`` (how many frames vLLM "
+"samples from the video):"
+msgstr "两个配置，仅改变 ``num_frames``\\ （vLLM 从视频中采样的帧数）："
+
+#: ../../source/non_kv_cache/encoder_cache.rst:128
+msgid "num_frames"
+msgstr "num_frames"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:129
+msgid "EC entry"
+msgstr "EC 条目"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:130
+msgid "Cold TTFT (s)"
+msgstr "冷 TTFT (秒)"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:131
+msgid "Warm TTFT mean (s)"
+msgstr "温暖 TTFT 平均值 (秒)"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:132
+msgid "Saved"
+msgstr "已保存"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:133
+msgid "Speedup"
+msgstr "加速"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:134
+msgid "32 (vLLM default)"
+msgstr "32 (vLLM 默认)"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:135
+msgid "34.3 MB"
+msgstr "34.3 MB"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:136
+msgid "3.923"
+msgstr "3.923"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:137
+msgid "3.125"
+msgstr "3.125"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:138
+msgid "798 ms"
+msgstr "798 毫秒"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:139
+msgid "**1.26×**"
+msgstr "**1.26×**"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:140
+msgid "128"
+msgstr "128"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:141
+msgid "130.8 MB"
+msgstr "130.8 MB"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:142
+msgid "5.895"
+msgstr "5.895"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:143
+msgid "3.375"
+msgstr "3.375"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:144
+msgid "2.52 s"
+msgstr "2.52 秒"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:145
+msgid "**1.75×**"
+msgstr "**1.75×**"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:147
+msgid ""
+"Speedup grows with ``num_frames`` because the encoder workload scales "
+"linearly with frame count while the rest of prefill (LM forward over the "
+"resulting multimodal tokens + the short text prompt) scales sublinearly. "
+"The same principle applies to other modalities: the win is largest when "
+"the encoder is the dominant share of prefill (long videos at high frame "
+"counts, long audio clips, large images at high resolution) and smallest "
+"when text prefill dominates."
+msgstr ""
+"随着 ``num_frames`` 的增加，速度提升也会增加，因为编码器的工作负载与帧数呈线性扩展，而其余的 "
+"Prefill（对生成的多模态令牌和短文本提示的 LM 前向推理）则呈亚线性扩展。相同的原理适用于其他模态：当编码器占据 Prefill "
+"的主导份额时（高帧数的长视频、长音频片段、高分辨率的大图像），收益最大；而当文本 Prefill 占主导时，收益最小。"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:156
+msgid "Reproducing"
+msgstr "再现"
+
+#: ../../source/non_kv_cache/encoder_cache.rst:158
+msgid "Server (heavier-encoder configuration):"
+msgstr "服务器（重型编码器配置）："
+
+#: ../../source/non_kv_cache/encoder_cache.rst:174
+msgid ""
+"Client: any streaming OpenAI-compatible client that re-sends the same "
+"multimodal payload. The benchmark measures TTFT (time to first token) "
+"because the encoder runs during prefill — any encoder savings show up "
+"there. Decode tokens-per-second is unaffected by EC."
+msgstr ""
+"客户端：任何重新发送相同多模态负载的流式 OpenAI 兼容客户端。基准测试测量 TTFT（首次令牌时间），因为编码器在 Prefill "
+"期间运行——任何编码器节省都在此处显现。解码每秒令牌数不受 EC 影响。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/encodings.po b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/encodings.po
new file mode 100644
index 0000000..7100cef
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/encodings.po
@@ -0,0 +1,33 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/non_kv_cache/encodings.rst:2
+msgid "Encodings"
+msgstr "编码"
+
+#: ../../source/non_kv_cache/encodings.rst:6
+msgid ""
+"Multiprocess (MP) support for encoding (encoder / multimodal) caching is "
+"**coming soon**. The current in-process implementation is preserved in "
+"the Legacy section: :doc:`/non_kv_cache/encoder_cache` and "
+":doc:`/api_reference/multimodality`."
+msgstr "MP 模式（多进程）对编码（编码器／多模态）缓存的支持 **即将推出**\\ 。当前的进程内实现保留在旧版章节中：:doc:`/non_kv_cache/encoder_cache` 和 :doc:`/api_reference/multimodality`。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/hidden_states.po b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/hidden_states.po
new file mode 100644
index 0000000..3369bde
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/hidden_states.po
@@ -0,0 +1,175 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-25 19:26-0700\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Language: zh_CN\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/non_kv_cache/hidden_states.rst:2
+msgid "Hidden states"
+msgstr "隐藏状态"
+
+#: ../../source/non_kv_cache/hidden_states.rst:4
+msgid ""
+"The **HiddenStateStore** caches per-token *hidden-state* tensors "
+"(intermediate activations from an inference forward pass) alongside the KV "
+"cache, keyed by the same chunk keys. It exists to support any system where a "
+"downstream stage needs an upstream stage's intermediate activations for the "
+"cached prefix and cannot reconstruct them from KV alone — for example a vLLM-"
+"Omni ``thinker -> talker`` pipeline, where the talker consumes the thinker's "
+"hidden states for tokens whose KV the engine restored without re-running "
+"prefill."
+msgstr "**HiddenStateStore** 在 KV Cache 之外缓存每个 token 的隐藏状态张量（推理前向传播过程中的中间激活），并使用相同的块键作为索引。它的存在是为了支持这样一类系统：下游阶段需要上游阶段为已缓存前缀计算的中间激活，且无法仅凭 KV 重建这些激活——例如 vLLM-Omni 的 ``thinker -> talker`` 流水线，其中 talker 会消费 thinker 为某些 token 生成的隐藏状态，而引擎在恢复这些 token 的 KV 时并未重新运行 Prefill。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:14
+msgid ""
+"Without this store, restoring KV alone causes downstream stages to see "
+"truncated or wrong activations for the cached prefix. With it, the talker "
+"(or any equivalent consumer) gets a contiguous ``[num_cached_prefix_tokens, "
+"hidden_dim]`` tensor matching the KV prefix LMCache restored."
+msgstr "如果没有这个存储，仅恢复 KV 会导致下游阶段读到的已缓存前缀激活被截断或出错。有了它，talker（或任何等价的消费方）就能获得一个连续的 ``[num_cached_prefix_tokens, hidden_dim]`` 张量，与 LMCache 恢复的 KV 前缀相匹配。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:21
+msgid "Enabling it"
+msgstr "启用方法"
+
+#: ../../source/non_kv_cache/hidden_states.rst:23
+msgid "Set three keys in the LMCache YAML (``LMCACHE_CONFIG_FILE``):"
+msgstr "在 LMCache YAML（``LMCACHE_CONFIG_FILE``）中设置三个键："
+
+#: ../../source/non_kv_cache/hidden_states.rst:33
+msgid ""
+"``enable_hidden_state_cache`` — master switch. When ``false`` (the default), "
+"``engine.hidden_state_store`` is ``None`` and integrators must skip all HS "
+"APIs on that worker."
+msgstr "``enable_hidden_state_cache`` —— 总开关。当为 ``false``\\ （默认值）时，``engine.hidden_state_store`` 为 ``None``，集成方必须在该 worker 上跳过所有 HS API。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:36
+msgid ""
+"``max_hidden_state_cpu_size`` — pinned-CPU pool size in GiB, dedicated to "
+"hidden states. Must be ``> 0`` when the store is enabled. The pool is "
+"**independent** of the KV pool; HS allocator pressure never evicts KV."
+msgstr "``max_hidden_state_cpu_size`` —— 专用于隐藏状态的固定 CPU 内存池大小（单位 GiB）。启用该存储时必须 ``> 0``。该内存池\\ **独立**\\ 于 KV 内存池；HS 分配器的压力绝不会逐出 KV。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:40
+msgid ""
+"``hidden_state_layers`` — optional allowlist of ``layer_idx`` values "
+"accepted on ``store_hidden_states``. Leave unset to accept all layer "
+"indices. Use this only when you know exactly which hook indices the worker "
+"writes (e.g. matching a fork's hybrid multimodal hook list)."
+msgstr "``hidden_state_layers`` —— ``store_hidden_states`` 接受的 ``layer_idx`` 值的可选白名单。不设置则接受所有层索引。仅当您确切知道 worker 写入哪些 hook 索引时才使用它（例如匹配某个 fork 的混合多模态 hook 列表）。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:47
+msgid "Using it from a worker"
+msgstr "在 worker 中使用"
+
+#: ../../source/non_kv_cache/hidden_states.rst:49
+msgid "The store is exposed on the engine (not as engine-level methods):"
+msgstr "该存储暴露在引擎上（而非作为引擎级方法）："
+
+#: ../../source/non_kv_cache/hidden_states.rst:68
+msgid "Notes:"
+msgstr "注意事项："
+
+#: ../../source/non_kv_cache/hidden_states.rst:70
+msgid ""
+"``token_ids`` is always the **full** prefix so chunk keys align with KV "
+"exactly. ``token_offset`` lets incremental callers (such as vLLM-Omni) pass "
+"only the newly computed rows in ``hidden_states`` without zero-padding the "
+"already-cached prefix."
+msgstr "``token_ids`` 始终是\\ **完整**\\ 前缀，因此块键能与 KV 精确对齐。``token_offset`` 允许增量调用方（例如 vLLM-Omni）只传入 ``hidden_states`` 中新计算的行，而无需对已缓存的前缀进行零填充。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:74
+msgid ""
+"``layer_idx`` is the *storage* layer index. Callers that need several "
+"intermediate tensors per request (e.g. multimodal hook outputs *plus* the "
+"main text hidden state) call ``store_hidden_states`` once per distinct "
+"``layer_idx`` and retrieve per layer on restore."
+msgstr "``layer_idx`` 是存储层索引。每个请求需要多个中间张量的调用方（例如多模态 hook 输出加上主文本隐藏状态）会为每个不同的 ``layer_idx`` 各调用一次 ``store_hidden_states``，并在恢复时按层检索。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:79
+msgid ""
+"``retrieve_hidden_states`` is **prefix-strict**: it returns the longest "
+"contiguous CPU ``float32`` prefix where every chunk has both KV and HS for "
+"the requested ``layer_idx``, and stops at the first chunk where either is "
+"missing."
+msgstr "``retrieve_hidden_states`` 是\\ **前缀严格**\\ 的：它返回最长的连续 CPU ``float32`` 前缀，其中每个块对于所请求的 ``layer_idx`` 都同时具备 KV 和 HS，并在第一个缺少任一者的块处停止。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:85
+msgid "Eviction model"
+msgstr "逐出模型"
+
+#: ../../source/non_kv_cache/hidden_states.rst:87
+msgid "The store implements a **coupled-but-asymmetric** eviction rule:"
+msgstr "该存储实现了一种\\ **耦合但非对称**\\ 的逐出规则："
+
+#: ../../source/non_kv_cache/hidden_states.rst:89
+msgid ""
+"**KV evicted ⇒ HS evicted.** On every ``retrieve_hidden_states`` the store "
+"asks the KV ``StorageManager`` whether KV is still present for each chunk "
+"key. If KV is gone, the orphan HS entry is dropped and the returned prefix "
+"ends there."
+msgstr "**KV 被逐出 ⇒ HS 被逐出。** 在每次 ``retrieve_hidden_states`` 时，该存储会向 KV 的 ``StorageManager`` 查询每个块键对应的 KV 是否仍然存在。如果 KV 已不存在，则丢弃对应的孤立 HS 条目，返回的前缀到此结束。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:93
+msgid ""
+"**HS evicted ⇏ KV evicted.** Pressure on the HS pinned pool only evicts HS "
+"entries (its own LRU), never KV."
+msgstr "**HS 被逐出 ⇏ KV 被逐出。** HS 固定内存池的压力只会逐出 HS 条目（其自身的 LRU），绝不会逐出 KV。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:95
+msgid ""
+"**Restore stops at first missing HS or KV chunk** for the requested layer."
+msgstr "**对于所请求的层，恢复会在第一个缺失的 HS 或 KV 块处停止。**"
+
+#: ../../source/non_kv_cache/hidden_states.rst:99
+msgid "Design notes (user-visible)"
+msgstr "设计说明（用户可见）"
+
+#: ../../source/non_kv_cache/hidden_states.rst:101
+msgid ""
+"**Separate pinned pool from KV.** KV tensors and hidden-state tensors have "
+"heterogeneous shapes and dtypes, so they get independent allocators. "
+"``max_hidden_state_cpu_size`` sizes the HS pool only."
+msgstr "**与 KV 分离的固定内存池。** KV 张量和隐藏状态张量具有异构的形状和数据类型，因此它们使用各自独立的分配器。``max_hidden_state_cpu_size`` 仅设置 HS 内存池的大小。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:105
+msgid ""
+"**Same chunk keys as KV.** The store reuses the engine's ``TokenDatabase`` "
+"so HS chunks share the exact ``CacheEngineKey`` as the matching KV chunks. "
+"This is what enables the lazy coupled eviction check."
+msgstr "**与 KV 相同的块键。** 该存储复用引擎的 ``TokenDatabase``，因此 HS 块与匹配的 KV 块共享完全相同的 ``CacheEngineKey``。正是这一点使得惰性耦合逐出检查成为可能。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:109
+msgid ""
+"**Lazy coupled-eviction check.** No callbacks or shared indices are required "
+"between KV and HS — the store asks ``storage_manager.contains(key)`` per "
+"chunk on retrieve. Works uniformly for any backend that implements "
+"``contains()``."
+msgstr "**惰性耦合逐出检查。** KV 与 HS 之间不需要任何回调或共享索引——该存储在检索时为每个块调用 ``storage_manager.contains(key)``。对于任何实现了 ``contains()`` 的后端，其行为都完全一致。"
+
+#: ../../source/non_kv_cache/hidden_states.rst:114
+msgid ""
+"The full internal design (class layering, code paths, follow-up work) lives "
+"at :file:`docs/design/v1/hidden_state_store.md` in the source tree."
+msgstr "完整的内部设计（类的分层、代码路径、后续工作）位于源码树中的 :file:`docs/design/v1/hidden_state_store.md`。"
+
+#~ msgid "Hidden States"
+#~ msgstr "隐藏状态"
+
+#~ msgid "Hidden-state caching is **in progress**."
+#~ msgstr "隐藏状态缓存功能 **正在开发中**\\ 。"
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/index.po
new file mode 100644
index 0000000..bf6d99a
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/non_kv_cache/index.po
@@ -0,0 +1,29 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/non_kv_cache/index.rst:2
+msgid "Non-KV Caching"
+msgstr "非 KV 缓存"
+
+#: ../../source/non_kv_cache/index.rst:4
+msgid "Caching state beyond the attention KV cache."
+msgstr "缓存注意力 KV 缓存之外的模型状态。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/docker_deployment.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/docker_deployment.po
new file mode 100644
index 0000000..3f47fd3
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/docker_deployment.po
@@ -0,0 +1,107 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/docker_deployment.rst:4
+msgid "Docker deployment"
+msgstr "Docker 部署"
+
+#: ../../source/production/docker_deployment.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/deployment`."
+msgstr ""
+
+#: ../../source/production/docker_deployment.rst:11
+msgid "**Prerequisites:** Docker Engine 27.0+"
+msgstr "**前提条件：** Docker Engine 27.0+"
+
+#: ../../source/production/docker_deployment.rst:13
+msgid "See :ref:`installation_guide` for pulling images."
+msgstr "请参阅 :ref:`installation_guide` 以获取拉取镜像的信息。"
+
+#: ../../source/production/docker_deployment.rst:16
+msgid "Running the container"
+msgstr "运行容器"
+
+#: ../../source/production/docker_deployment.rst:32
+msgid ""
+"See the `docker run example "
+"<https://github.com/LMCache/LMCache/tree/dev/docker>`_ for more details."
+msgstr ""
+"有关更多详细信息，请参见 `docker run 示例 "
+"<https://github.com/LMCache/LMCache/tree/dev/docker>`_。"
+
+#: ../../source/production/docker_deployment.rst:35
+msgid "ROCm (AMD)"
+msgstr "ROCm (AMD)"
+
+#: ../../source/production/docker_deployment.rst:37
+msgid ""
+"The `AMD Infinity hub <https://hub.docker.com/r/rocm/vllm-dev>`__ for "
+"vLLM offers a prebuilt, optimized image for the AMD Instinct™ MI300X. See"
+" `LLM inference performance validation on AMD Instinct MI300X "
+"<https://rocm.docs.amd.com/en/latest/how-to/rocm-for-ai/inference"
+"/benchmark-docker/vllm.html?model=pyt_vllm_llama-3.1-8b>`__ for full "
+"instructions."
+msgstr ""
+"`AMD Infinity hub <https://hub.docker.com/r/rocm/vllm-dev>`__ 为 vLLM "
+"提供了一个预构建的、优化的镜像，适用于 AMD Instinct™ MI300X。有关完整说明，请参见 `LLM 推理性能验证在 AMD "
+"Instinct MI300X 上 <https://rocm.docs.amd.com/en/latest/how-to/rocm-for-"
+"ai/inference/benchmark-docker/vllm.html?model=pyt_vllm_llama-3.1-8b>`__。"
+
+#: ../../source/production/docker_deployment.rst:42
+msgid ""
+"Validated environment: ``rocm/vllm-"
+"dev:nightly_0624_rc2_0624_rc2_20250620``, MI300X, vLLM V1."
+msgstr ""
+"验证的环境：``rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620``, MI300X, vLLM "
+"V1."
+
+#: ../../source/production/docker_deployment.rst:61
+msgid "XPU (Intel)"
+msgstr "XPU（英特尔）"
+
+#: ../../source/production/docker_deployment.rst:63
+msgid ""
+"The `Intel vLLM XPU hub <https://hub.docker.com/r/intel/vllm>`__ offers a"
+" prebuilt, optimized docker image designed for validating inference "
+"performance on the Intel GPU accelerators like ARC770, B60/B70, and "
+"future products."
+msgstr ""
+"`Intel vLLM XPU hub <https://hub.docker.com/r/intel/vllm>`__ "
+"提供了一个预构建的、优化的 Docker 镜像，旨在验证在 Intel GPU 加速器（如 ARC770、B60/B70 "
+"及未来产品）上的推理性能。"
+
+#: ../../source/production/docker_deployment.rst:65
+msgid "Validated environment: ``intel/vllm:0.17.0-xpu``, Intel B60 GPU, vLLM V1."
+msgstr "验证环境：``intel/vllm:0.17.0-xpu``, Intel B60 GPU, vLLM V1。"
+
+#~ msgid ""
+#~ "The `Intel vLLM XPU "
+#~ "hub<https://hub.docker.com/r/intel/vllm>`__ offers a "
+#~ "prebuilt, optimized docker image designed "
+#~ "for validating inference performance on "
+#~ "the Intel GPU accelerators like ARC770,"
+#~ " B60/B70, and future products."
+#~ msgstr ""
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/dynamo_coordination.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/dynamo_coordination.po
new file mode 100644
index 0000000..1d808ee
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/dynamo_coordination.po
@@ -0,0 +1,31 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/dynamo_coordination.rst:2
+msgid "Dynamo Integration"
+msgstr "Dynamo 集成"
+
+#: ../../source/production/dynamo_coordination.rst:6
+msgid ""
+"Integration with `NVIDIA Dynamo <https://github.com/ai-dynamo/dynamo>`_ "
+"is **coming soon**."
+msgstr "与 `NVIDIA Dynamo <https://github.com/ai-dynamo/dynamo>`_ 的集成\\ **即将推出**\\ 。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/index.po
new file mode 100644
index 0000000..02b6e19
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/index.po
@@ -0,0 +1,29 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/index.rst:2
+msgid "Use LMCache in Production"
+msgstr "在生产环境中使用 LMCache"
+
+#: ../../source/production/index.rst:4
+msgid "Deploying, scaling, and operating LMCache in production."
+msgstr "在生产环境中部署、扩展和操作 LMCache。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/kubernetes_deployment.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/kubernetes_deployment.po
new file mode 100644
index 0000000..251ab80
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/kubernetes_deployment.po
@@ -0,0 +1,58 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/kubernetes_deployment.rst:2
+msgid "Kubernetes Deployment"
+msgstr "Kubernetes 部署"
+
+#: ../../source/production/kubernetes_deployment.rst:4
+msgid ""
+"For Kubernetes deployment of vLLM with LMCache integration, we recommend "
+"using the `vLLM Production Stack <https://github.com/vllm-project"
+"/production-stack>`_ project. This is a specialized production-ready "
+"implementation for K8S-native cluster-wide deployment for vllm & lmcache."
+msgstr "对于集成 LMCache 的 vLLM 的 Kubernetes 部署，我们建议使用 `vLLM Production Stack <https://github.com/vllm-project/production-stack>`_ 项目。这是一个专门为 vllm 和 lmcache 提供的 K8S 原生集群范围的生产就绪实现。"
+
+#: ../../source/production/kubernetes_deployment.rst:6
+msgid ""
+"For a quick start guide, please refer to the official `documentation "
+"<https://docs.vllm.ai/projects/production-"
+"stack/en/latest/getting_started/quickstart.html>`_"
+msgstr "有关快速入门指南，请参阅官方 `文档 <https://docs.vllm.ai/projects/production-stack/en/latest/getting_started/quickstart.html>`_。"
+
+#: ../../source/production/kubernetes_deployment.rst:8
+msgid ""
+"and replace the Helm values file with (`values-05-cpu-offloading.yaml "
+"<https://github.com/vllm-project/production-"
+"stack/blob/main/tutorials/assets/values-05-cpu-offloading.yaml>`_):"
+msgstr "并用 (`values-05-cpu-offloading.yaml <https://github.com/vllm-project/production-stack/blob/main/tutorials/assets/values-05-cpu-offloading.yaml>`_) 替换 Helm 值文件："
+
+#: ../../source/production/kubernetes_deployment.rst:35
+msgid "OR"
+msgstr "或"
+
+#: ../../source/production/kubernetes_deployment.rst:37
+msgid ""
+"refer to a detailed `step-by-step tutorial <https://github.com/vllm-"
+"project/production-stack/blob/main/tutorials/05-offload-kv-cache.md>`_ on"
+" how to offload KV cache with LMCache in the production stack."
+msgstr "请参阅有关如何在生产环境中使用 LMCache 卸载 KV Cache 的详细 `逐步教程 <https://github.com/vllm-project/production-stack/blob/main/tutorials/05-offload-kv-cache.md>`_。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/kv_cache_events.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/kv_cache_events.po
new file mode 100644
index 0000000..8427f25
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/kv_cache_events.po
@@ -0,0 +1,212 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/kv_cache_events.rst:4
+msgid "KV Cache Events"
+msgstr "KV Cache 事件"
+
+#: ../../source/production/kv_cache_events.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/observability/index`."
+msgstr ""
+
+#: ../../source/production/kv_cache_events.rst:11
+msgid ""
+"KV cache events are actions or lifecycle events that occur when managing "
+"the KV cache during inference. These events can be used for KV-cache-"
+"aware routing."
+msgstr "KV Cache 事件是在推理过程中管理 KV Cache 时发生的操作或生命周期事件。这些事件可用于 KV Cache 感知路由。"
+
+#: ../../source/production/kv_cache_events.rst:13
+msgid "LMCache supports KV cache events as follows:"
+msgstr "LMCache 支持以下 KV 缓存事件："
+
+#: ../../source/production/kv_cache_events.rst:15
+msgid "Generates storage KV cache events"
+msgstr "生成存储 KV Cache 事件"
+
+#: ../../source/production/kv_cache_events.rst:16
+msgid ""
+"The events format is defined as per the `BlockStored class "
+"<https://github.com/vllm-"
+"project/vllm/blob/main/vllm/distributed/kv_events.py>`_ in vLLM"
+msgstr ""
+"事件格式根据 vLLM 中的 `BlockStored class <https://github.com/vllm-"
+"project/vllm/blob/main/vllm/distributed/kv_events.py>`_ 定义。"
+
+#: ../../source/production/kv_cache_events.rst:17
+msgid ""
+"LMCache passes the events to SGLang or vLLM to publish them using their "
+"messaging system"
+msgstr "LMCache 将事件传递给 SGLang 或 vLLM，以通过它们的消息系统发布这些事件。"
+
+#: ../../source/production/kv_cache_events.rst:20
+msgid "Prerequisites"
+msgstr "先决条件"
+
+#: ../../source/production/kv_cache_events.rst:22
+msgid "The following prerequisites are required:"
+msgstr "以下先决条件是必需的："
+
+#: ../../source/production/kv_cache_events.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/production/kv_cache_events.rst:28
+msgid "vLLM v0.13.0+"
+msgstr "vLLM v0.13.0+"
+
+#: ../../source/production/kv_cache_events.rst:29
+msgid "LMCache v0.3.11+"
+msgstr "LMCache v0.3.11+"
+
+#: ../../source/production/kv_cache_events.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/production/kv_cache_events.rst:33
+msgid "SGLang vx.y.z+"
+msgstr "SGLang vx.y.z+"
+
+#: ../../source/production/kv_cache_events.rst:34
+msgid "LMCache vx.y.z+"
+msgstr "LMCache vx.y.z+"
+
+#: ../../source/production/kv_cache_events.rst:37
+msgid "How to Generate KV Cache events"
+msgstr "如何生成 KV Cache 事件"
+
+#: ../../source/production/kv_cache_events.rst:43
+#: ../../source/production/kv_cache_events.rst:94
+msgid ""
+"Before starting to generate KV events, you need to be aware of the "
+"following:"
+msgstr "在开始生成 KV 事件之前，您需要了解以下内容："
+
+#: ../../source/production/kv_cache_events.rst:45
+#: ../../source/production/kv_cache_events.rst:96
+msgid ""
+"You need to enable ``enable_kv_events`` for LMCache as events are not "
+"generated by default."
+msgstr "您需要为 LMCache 启用 ``enable_kv_events``，因为默认情况下不会生成事件。"
+
+#: ../../source/production/kv_cache_events.rst:46
+msgid ""
+"If running more than 1 worker in vLLM, you need to use a non-default "
+"hashing algorithm (set ``pre_caching_hash_algorithm`` in LMCache) so that"
+" hashes generated per worker are the same. If not then you will have "
+"duplicate events for the same operation as events are generated per "
+"worker."
+msgstr ""
+"如果在 vLLM 中运行多个工作进程，则需要使用非默认的哈希算法（在 LMCache 中设置 "
+"``pre_caching_hash_algorithm``），以确保每个工作进程生成的哈希相同。如果不这样做，则会为相同操作生成重复事件，因为事件是按工作进程生成的。"
+
+#: ../../source/production/kv_cache_events.rst:47
+msgid ""
+"LMCache sends the events to vLLM for publishing. To enable events to be "
+"published, you need to set the vLLM configuration setting ``--kv-events-"
+"config``. See `vLLM KV Events configuration "
+"<https://docs.vllm.ai/en/stable/api/vllm/config/kv_events/>`_ for more "
+"details."
+msgstr ""
+"LMCache 将事件发送到 vLLM 进行发布。要启用事件发布，您需要设置 vLLM 配置选项 ``--kv-events-"
+"config``。有关更多详细信息，请参见 `vLLM KV Events configuration "
+"<https://docs.vllm.ai/en/stable/api/vllm/config/kv_events/>`_。"
+
+#: ../../source/production/kv_cache_events.rst:49
+#: ../../source/production/kv_cache_events.rst:99
+msgid ""
+"The steps that follow give an example of how KV events can be generated, "
+"published and consumed:"
+msgstr "接下来的步骤给出了如何生成、发布和消费 KV 事件的示例："
+
+#: ../../source/production/kv_cache_events.rst:51
+msgid "Start vLLM with LMCache and model ``Qwen/Qwen3-0.6B`` as follows:"
+msgstr "以如下方式启动 vLLM，使用 LMCache 和模型 ``Qwen/Qwen3-0.6B``："
+
+#: ../../source/production/kv_cache_events.rst:59
+#: ../../source/production/kv_cache_events.rst:112
+msgid "Example of the LMCache configuration is as follows:"
+msgstr "LMCache 配置示例如下："
+
+#: ../../source/production/kv_cache_events.rst:68
+msgid ""
+"To be able to process the events that are published by vLLM, you need a "
+"client that subscribes to the publisher message channel and can consume "
+"the events. vLLM provides such a client example `KV Events Subscriber "
+"<https://docs.vllm.ai/en/stable/examples/online_serving/kv_events_subscriber/>`_."
+" Run this python script in a separate terminal."
+msgstr ""
+"要处理 vLLM 发布的事件，您需要一个订阅发布者消息通道并能够消费事件的客户端。vLLM 提供了这样的客户端示例 `KV Events "
+"Subscriber "
+"<https://docs.vllm.ai/en/stable/examples/online_serving/kv_events_subscriber/>`_。在单独的终端中运行此"
+" Python 脚本。"
+
+#: ../../source/production/kv_cache_events.rst:70
+#: ../../source/production/kv_cache_events.rst:124
+msgid "Prompt the model:"
+msgstr "提示模型："
+
+#: ../../source/production/kv_cache_events.rst:83
+#: ../../source/production/kv_cache_events.rst:138
+msgid ""
+"You should receive a message in the client (that you started in step 2.) "
+"window, similar to the following:"
+msgstr "您应该在客户端（您在第 2 步中启动的客户端）窗口中收到一条消息，类似于以下内容："
+
+#: ../../source/production/kv_cache_events.rst:90
+#: ../../source/production/kv_cache_events.rst:160
+msgid "This is the event generated after the cache store operation."
+msgstr "这是在缓存存储操作后生成的事件。"
+
+#: ../../source/production/kv_cache_events.rst:97
+msgid ""
+"LMCache sends the events to SGLang for publishing. To enable events to be"
+" published, you need to set the SGLang configuration setting ``--kv-"
+"events-config``."
+msgstr ""
+"LMCache 将事件发送到 SGLang 进行发布。要启用事件发布，您需要设置 SGLang 配置选项 ``--kv-events-"
+"config``。"
+
+#: ../../source/production/kv_cache_events.rst:101
+msgid "Start SGLang with LMCache and model ``Qwen/Qwen3-0.6B`` as follows:"
+msgstr "使用 LMCache 和模型 ``Qwen/Qwen3-0.6B`` 启动 SGLang，如下所示："
+
+#: ../../source/production/kv_cache_events.rst:122
+msgid ""
+"To be able to process the events that are published by SGLang, you need a"
+" client that subscribes to the publisher message channel and can consume "
+"the events. vLLM provides such a client example `KV Events Subscriber "
+"<https://docs.vllm.ai/en/stable/examples/online_serving/kv_events_subscriber/>`_."
+" To use this client for SGLang, you need to remove the properties "
+"``medium`` and ``lora_name`` from the ``BlockStored`` class definition "
+"and ``medium`` from ``BlockRemoved`` class definition. Save the changes "
+"and run this updated python script in a separate terminal."
+msgstr ""
+"要处理 SGLang 发布的事件，您需要一个订阅发布者消息通道并能够消费事件的客户端。vLLM 提供了这样一个客户端示例 `KV Events "
+"Subscriber "
+"<https://docs.vllm.ai/en/stable/examples/online_serving/kv_events_subscriber/>`_。要将此客户端用于"
+" SGLang，您需要从 ``BlockStored`` 类定义中删除属性 ``medium`` 和 ``lora_name``，并从 "
+"``BlockRemoved`` 类定义中删除 ``medium``。保存更改并在单独的终端中运行此更新的 Python 脚本。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/chunk_statistics.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/chunk_statistics.po
new file mode 100644
index 0000000..1bf85bc
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/chunk_statistics.po
@@ -0,0 +1,589 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/chunk_statistics.rst:4
+msgid "Chunk Statistics"
+msgstr "块统计"
+
+#: ../../source/production/observability/chunk_statistics.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr ""
+
+#: ../../source/production/observability/chunk_statistics.rst:11
+msgid ""
+"The chunk statistics feature provides insights into KV cache chunk reuse "
+"patterns, helping you understand cache efficiency and optimize your "
+"deployment."
+msgstr "块统计功能提供了对 KV Cache 块重用模式的洞察，帮助您理解缓存效率并优化您的部署。"
+
+#: ../../source/production/observability/chunk_statistics.rst:14
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/production/observability/chunk_statistics.rst:16
+msgid ""
+"Chunk statistics tracks and analyzes KV cache chunks to provide metrics "
+"on:"
+msgstr "块统计跟踪和分析 KV Cache 块，以提供以下指标："
+
+#: ../../source/production/observability/chunk_statistics.rst:18
+msgid ""
+"**Total chunks processed**: The total number of chunks that have been "
+"processed"
+msgstr "**处理的总块数**\\ ：已处理的块的总数"
+
+#: ../../source/production/observability/chunk_statistics.rst:19
+msgid "**Unique chunks**: The number of distinct chunks encountered"
+msgstr "**唯一块**\\ ：遇到的不同块的数量"
+
+#: ../../source/production/observability/chunk_statistics.rst:20
+msgid "**Duplicate chunks**: The number of repeated chunks"
+msgstr "**重复块**\\ ：重复块的数量"
+
+#: ../../source/production/observability/chunk_statistics.rst:21
+msgid ""
+"**Reuse rate**: The ratio of duplicate chunks to total chunks, indicating"
+" cache efficiency"
+msgstr "**重用率**\\ ：重复块与总块的比例，指示缓存效率"
+
+#: ../../source/production/observability/chunk_statistics.rst:23
+msgid "This information is valuable for:"
+msgstr "此信息对以下内容很有价值："
+
+#: ../../source/production/observability/chunk_statistics.rst:25
+msgid "Understanding cache hit patterns"
+msgstr "理解缓存命中模式"
+
+#: ../../source/production/observability/chunk_statistics.rst:26
+msgid "Optimizing cache size and eviction policies"
+msgstr "优化缓存大小和逐出策略"
+
+#: ../../source/production/observability/chunk_statistics.rst:27
+msgid "Analyzing workload characteristics"
+msgstr "分析工作负载特征"
+
+#: ../../source/production/observability/chunk_statistics.rst:28
+msgid "Capacity planning for production deployments"
+msgstr "生产部署的容量规划"
+
+#: ../../source/production/observability/chunk_statistics.rst:31
+msgid "Recording Strategies"
+msgstr "记录策略"
+
+#: ../../source/production/observability/chunk_statistics.rst:33
+msgid ""
+"LMCache supports multiple recording strategies, each optimized for "
+"different use cases:"
+msgstr "LMCache 支持多种记录策略，每种策略都针对不同的使用案例进行了优化："
+
+#: ../../source/production/observability/chunk_statistics.rst:36
+msgid "Memory Bloom Filter Strategy"
+msgstr "内存布隆过滤器策略"
+
+#: ../../source/production/observability/chunk_statistics.rst:38
+msgid ""
+"A memory-efficient strategy using Bloom filters for probabilistic "
+"duplicate detection."
+msgstr "一种使用布隆过滤器进行概率重复检测的内存高效策略。"
+
+#: ../../source/production/observability/chunk_statistics.rst:40
+#: ../../source/production/observability/chunk_statistics.rst:69
+msgid "**Advantages:**"
+msgstr "**优点：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:42
+msgid "Low memory footprint"
+msgstr "低内存占用"
+
+#: ../../source/production/observability/chunk_statistics.rst:43
+msgid "Fast lookup operations"
+msgstr "快速查找操作"
+
+#: ../../source/production/observability/chunk_statistics.rst:44
+msgid "Suitable for large-scale deployments"
+msgstr "适合大规模部署"
+
+#: ../../source/production/observability/chunk_statistics.rst:46
+#: ../../source/production/observability/chunk_statistics.rst:75
+msgid "**Configuration:**"
+msgstr "**配置：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:56
+#: ../../source/production/observability/chunk_statistics.rst:86
+msgid "**Environment Variables:**"
+msgstr "**环境变量：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:65
+msgid "File Hash Strategy"
+msgstr "文件哈希策略"
+
+#: ../../source/production/observability/chunk_statistics.rst:67
+msgid ""
+"A file-based strategy that writes chunk hashes to disk for exact tracking"
+" and offline analysis."
+msgstr "一种基于文件的策略，将块哈希写入磁盘，以便进行精确跟踪和离线分析。"
+
+#: ../../source/production/observability/chunk_statistics.rst:71
+msgid "Exact duplicate detection (no false positives)"
+msgstr "精确重复检测（无误报）"
+
+#: ../../source/production/observability/chunk_statistics.rst:72
+msgid "Persistent storage for offline analysis"
+msgstr "离线分析的持久存储"
+
+#: ../../source/production/observability/chunk_statistics.rst:73
+msgid "Automatic file rotation and cleanup"
+msgstr "自动文件轮换和清理"
+
+#: ../../source/production/observability/chunk_statistics.rst:95
+msgid "Quick Start Guide"
+msgstr "快速入门指南"
+
+#: ../../source/production/observability/chunk_statistics.rst:98
+msgid "Step 1: Enable Chunk Statistics"
+msgstr "步骤 1：启用块统计信息"
+
+#: ../../source/production/observability/chunk_statistics.rst:100
+msgid "Configure your LMCache instance with chunk statistics enabled:"
+msgstr "配置您的 LMCache 实例以启用块统计信息："
+
+#: ../../source/production/observability/chunk_statistics.rst:102
+msgid "**Using YAML Configuration:**"
+msgstr "**使用 YAML 配置：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:123
+msgid "**Using vLLM with LMCache:**"
+msgstr "**使用 vLLM 和 LMCache:**"
+
+#: ../../source/production/observability/chunk_statistics.rst:140
+msgid "Step 2: Access Statistics"
+msgstr "步骤 2：访问统计信息"
+
+#: ../../source/production/observability/chunk_statistics.rst:142
+msgid "Retrieve statistics through the internal API server:"
+msgstr "通过内部 API 服务器检索统计信息："
+
+#: ../../source/production/observability/chunk_statistics.rst:149
+msgid "**Example Response:**"
+msgstr "**示例响应：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:192
+msgid "Configuration Options"
+msgstr "配置选项"
+
+#: ../../source/production/observability/chunk_statistics.rst:195
+msgid "Basic Configuration"
+msgstr "基本配置"
+
+#: ../../source/production/observability/chunk_statistics.rst:197
+msgid "Basic Configuration Options"
+msgstr "基本配置选项"
+
+#: ../../source/production/observability/chunk_statistics.rst:201
+#: ../../source/production/observability/chunk_statistics.rst:229
+#: ../../source/production/observability/chunk_statistics.rst:248
+msgid "Configuration Key"
+msgstr "配置键"
+
+#: ../../source/production/observability/chunk_statistics.rst:202
+#: ../../source/production/observability/chunk_statistics.rst:230
+#: ../../source/production/observability/chunk_statistics.rst:249
+msgid "Default Value"
+msgstr "默认值"
+
+#: ../../source/production/observability/chunk_statistics.rst:203
+#: ../../source/production/observability/chunk_statistics.rst:231
+#: ../../source/production/observability/chunk_statistics.rst:250
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/chunk_statistics.rst:204
+msgid "``enable_chunk_statistics``"
+msgstr "``enable_chunk_statistics``"
+
+#: ../../source/production/observability/chunk_statistics.rst:205
+#: ../../source/production/observability/chunk_statistics.rst:211
+msgid "``false``"
+msgstr "``false``"
+
+#: ../../source/production/observability/chunk_statistics.rst:206
+msgid "Enable chunk statistics tracking"
+msgstr "启用块统计跟踪"
+
+#: ../../source/production/observability/chunk_statistics.rst:207
+msgid "``chunk_statistics_strategy``"
+msgstr "``chunk_statistics_strategy``"
+
+#: ../../source/production/observability/chunk_statistics.rst:208
+msgid "``memory_bloom_filter``"
+msgstr "``memory_bloom_filter``"
+
+#: ../../source/production/observability/chunk_statistics.rst:209
+msgid "Recording strategy: ``memory_bloom_filter`` or ``file_hash``"
+msgstr "记录策略：\\ ``memory_bloom_filter`` 或 ``file_hash``"
+
+#: ../../source/production/observability/chunk_statistics.rst:210
+msgid "``chunk_statistics_auto_start_statistics``"
+msgstr "``chunk_statistics_auto_start_statistics``"
+
+#: ../../source/production/observability/chunk_statistics.rst:212
+msgid "Automatically start statistics collection on initialization"
+msgstr "在初始化时自动开始统计收集"
+
+#: ../../source/production/observability/chunk_statistics.rst:213
+msgid "``chunk_statistics_auto_exit_timeout_hours``"
+msgstr "``chunk_statistics_auto_exit_timeout_hours``"
+
+#: ../../source/production/observability/chunk_statistics.rst:214
+msgid "``0.0``"
+msgstr "``0.0``"
+
+#: ../../source/production/observability/chunk_statistics.rst:215
+msgid "Auto-stop after specified hours (0 = disabled)"
+msgstr "在指定小时后自动停止（0 = 禁用）"
+
+#: ../../source/production/observability/chunk_statistics.rst:216
+msgid "``chunk_statistics_auto_exit_target_unique_chunks``"
+msgstr "``chunk_statistics_auto_exit_target_unique_chunks``"
+
+#: ../../source/production/observability/chunk_statistics.rst:217
+msgid "``0``"
+msgstr "``0``"
+
+#: ../../source/production/observability/chunk_statistics.rst:218
+msgid "Auto-stop after reaching target unique chunks (0 = disabled)"
+msgstr "达到目标唯一块后自动停止（0 = 禁用）"
+
+#: ../../source/production/observability/chunk_statistics.rst:221
+msgid "Memory Bloom Filter Options"
+msgstr "内存布隆过滤器选项"
+
+#: ../../source/production/observability/chunk_statistics.rst:223
+#: ../../source/production/observability/chunk_statistics.rst:242
+msgid "Configure these options in the ``extra_config`` section:"
+msgstr "在 ``extra_config`` 部分配置这些选项："
+
+#: ../../source/production/observability/chunk_statistics.rst:225
+msgid "Bloom Filter Configuration"
+msgstr "布隆过滤器配置"
+
+#: ../../source/production/observability/chunk_statistics.rst:232
+msgid "``chunk_statistics_mem_bf_expected_chunks``"
+msgstr "``chunk_statistics_mem_bf_expected_chunks``"
+
+#: ../../source/production/observability/chunk_statistics.rst:233
+msgid "``20000000``"
+msgstr "``20000000``"
+
+#: ../../source/production/observability/chunk_statistics.rst:234
+msgid "Expected number of chunks for capacity planning"
+msgstr "容量规划的预期块数"
+
+#: ../../source/production/observability/chunk_statistics.rst:235
+msgid "``chunk_statistics_mem_bf_false_positive_rate``"
+msgstr "``chunk_statistics_mem_bf_false_positive_rate``"
+
+#: ../../source/production/observability/chunk_statistics.rst:236
+msgid "``0.01``"
+msgstr "``0.01``"
+
+#: ../../source/production/observability/chunk_statistics.rst:237
+msgid "Target false positive rate (1%)"
+msgstr "目标假阳性率 (1%)"
+
+#: ../../source/production/observability/chunk_statistics.rst:240
+msgid "File Hash Options"
+msgstr "文件哈希选项"
+
+#: ../../source/production/observability/chunk_statistics.rst:244
+msgid "File Hash Configuration"
+msgstr "文件哈希配置"
+
+#: ../../source/production/observability/chunk_statistics.rst:251
+msgid "``chunk_statistics_file_output_dir``"
+msgstr "``chunk_statistics_file_output_dir``"
+
+#: ../../source/production/observability/chunk_statistics.rst:252
+msgid "``/tmp/lmcache_chunk_statistics``"
+msgstr "``/tmp/lmcache_chunk_statistics``"
+
+#: ../../source/production/observability/chunk_statistics.rst:253
+msgid "Directory for storing chunk hash files"
+msgstr "存储块哈希文件的目录"
+
+#: ../../source/production/observability/chunk_statistics.rst:254
+msgid "``chunk_statistics_file_rotation_size``"
+msgstr "``chunk_statistics_file_rotation_size``"
+
+#: ../../source/production/observability/chunk_statistics.rst:255
+msgid "``104857600``"
+msgstr "``104857600``"
+
+#: ../../source/production/observability/chunk_statistics.rst:256
+msgid "File size threshold for rotation (bytes, default 100MB)"
+msgstr "文件大小阈值用于轮换（字节，默认 100MB）"
+
+#: ../../source/production/observability/chunk_statistics.rst:257
+msgid "``chunk_statistics_file_max_count``"
+msgstr "``chunk_statistics_file_max_count``"
+
+#: ../../source/production/observability/chunk_statistics.rst:258
+msgid "``100``"
+msgstr "``100``"
+
+#: ../../source/production/observability/chunk_statistics.rst:259
+msgid "Maximum number of files to keep"
+msgstr "保留的最大文件数量"
+
+#: ../../source/production/observability/chunk_statistics.rst:262
+msgid "Advanced Usage"
+msgstr "高级用法"
+
+#: ../../source/production/observability/chunk_statistics.rst:265
+msgid "Programmatic Control"
+msgstr "程序化控制"
+
+#: ../../source/production/observability/chunk_statistics.rst:267
+msgid "Control statistics collection programmatically through the internal API:"
+msgstr "通过内部 API 以编程方式控制统计信息收集："
+
+#: ../../source/production/observability/chunk_statistics.rst:287
+msgid "Auto-Stop Configuration"
+msgstr "自动停止配置"
+
+#: ../../source/production/observability/chunk_statistics.rst:289
+msgid "Configure automatic stopping based on time or chunk count:"
+msgstr "根据时间或块数配置自动停止："
+
+#: ../../source/production/observability/chunk_statistics.rst:296
+msgid "Prometheus Metrics"
+msgstr "Prometheus 指标"
+
+#: ../../source/production/observability/chunk_statistics.rst:298
+msgid ""
+"When using the internal API server, chunk statistics are exposed as "
+"Prometheus metrics:"
+msgstr "当使用内部 API 服务器时，块统计信息作为 Prometheus 指标公开："
+
+#: ../../source/production/observability/chunk_statistics.rst:300
+msgid ""
+"``lmcache_chunk_statistics_total_chunks``: Total number of chunks "
+"processed"
+msgstr "``lmcache_chunk_statistics_total_chunks``: 处理的块的总数"
+
+#: ../../source/production/observability/chunk_statistics.rst:301
+msgid "``lmcache_chunk_statistics_unique_chunks``: Number of unique chunks"
+msgstr "``lmcache_chunk_statistics_unique_chunks``: 唯一块的数量"
+
+#: ../../source/production/observability/chunk_statistics.rst:302
+msgid "``lmcache_chunk_statistics_reuse_rate``: Cache reuse rate (0.0 to 1.0)"
+msgstr "``lmcache_chunk_statistics_reuse_rate``: 缓存重用率 (0.0 到 1.0)"
+
+#: ../../source/production/observability/chunk_statistics.rst:303
+msgid ""
+"``lmcache_chunk_statistics_bloom_filter_size_mb``: Bloom filter memory "
+"usage (MB)"
+msgstr "``lmcache_chunk_statistics_bloom_filter_size_mb``: 布隆过滤器内存使用量 (MB)"
+
+#: ../../source/production/observability/chunk_statistics.rst:304
+msgid ""
+"``lmcache_chunk_statistics_bloom_filter_fill_rate``: Bloom filter fill "
+"rate (0.0 to 1.0)"
+msgstr "``lmcache_chunk_statistics_bloom_filter_fill_rate``: 布隆过滤器填充率 (0.0 到 1.0)"
+
+#: ../../source/production/observability/chunk_statistics.rst:305
+msgid "``lmcache_chunk_statistics_file_count``: Number of hash files created"
+msgstr "``lmcache_chunk_statistics_file_count``: 创建的哈希文件数量"
+
+#: ../../source/production/observability/chunk_statistics.rst:306
+msgid "``lmcache_chunk_statistics_current_file_size``: Current file size (bytes)"
+msgstr "``lmcache_chunk_statistics_current_file_size``: 当前文件大小（字节）"
+
+#: ../../source/production/observability/chunk_statistics.rst:309
+msgid "Offline Analysis"
+msgstr "离线分析"
+
+#: ../../source/production/observability/chunk_statistics.rst:311
+msgid ""
+"For the file hash strategy, you can perform detailed offline analysis of "
+"collected chunk hash data."
+msgstr "对于文件哈希策略，您可以对收集到的块哈希数据进行详细的离线分析。"
+
+#: ../../source/production/observability/chunk_statistics.rst:314
+msgid "Using the Analysis Script"
+msgstr "使用分析脚本"
+
+#: ../../source/production/observability/chunk_statistics.rst:316
+msgid ""
+"LMCache provides a comprehensive analysis script at "
+"``examples/chunk_statistics/analyze_chunk_hashes.py`` that supports "
+"multiple analysis modes."
+msgstr ""
+"LMCache 提供了一个全面的分析脚本，位于 "
+"``examples/chunk_statistics/analyze_chunk_hashes.py``\\ ，支持多种分析模式。"
+
+#: ../../source/production/observability/chunk_statistics.rst:319
+msgid "Best Practices"
+msgstr "最佳实践"
+
+#: ../../source/production/observability/chunk_statistics.rst:321
+msgid "**Choose the Right Strategy:**"
+msgstr "**选择正确的策略：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:323
+msgid "Use **memory_bloom_filter** for real-time monitoring with minimal overhead"
+msgstr "使用 **memory_bloom_filter** 进行实时监控，且开销最小"
+
+#: ../../source/production/observability/chunk_statistics.rst:324
+msgid "Use **file_hash** when exact tracking is required or for offline analysis"
+msgstr "使用 **file_hash** 当需要精确跟踪或进行离线分析时。"
+
+#: ../../source/production/observability/chunk_statistics.rst:326
+msgid "**Tune Bloom Filter Parameters:**"
+msgstr "**调整布隆过滤器参数:**"
+
+#: ../../source/production/observability/chunk_statistics.rst:328
+msgid "Set ``expected_chunks`` based on your workload size"
+msgstr "根据您的工作负载大小设置 ``expected_chunks``"
+
+#: ../../source/production/observability/chunk_statistics.rst:329
+msgid "Lower ``false_positive_rate`` increases memory usage but improves accuracy"
+msgstr "降低 ``false_positive_rate`` 会增加内存使用，但提高准确性。"
+
+#: ../../source/production/observability/chunk_statistics.rst:331
+msgid "**Monitor Memory Usage:**"
+msgstr "**监控内存使用情况：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:333
+msgid ""
+"Track ``bloom_filter_size_mb`` metric to ensure it fits in available "
+"memory"
+msgstr "跟踪 ``bloom_filter_size_mb`` 指标以确保其适合可用内存"
+
+#: ../../source/production/observability/chunk_statistics.rst:334
+msgid "Adjust ``expected_chunks`` if memory usage is too high"
+msgstr "如果内存使用过高，请调整 ``expected_chunks``\\ 。"
+
+#: ../../source/production/observability/chunk_statistics.rst:336
+msgid "**File Rotation:**"
+msgstr "**文件轮换：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:338
+msgid ""
+"Configure appropriate ``file_rotation_size`` to balance file size and "
+"count"
+msgstr "配置适当的 ``file_rotation_size`` 以平衡文件大小和数量"
+
+#: ../../source/production/observability/chunk_statistics.rst:339
+msgid "Set ``file_max_count`` to prevent unlimited disk usage"
+msgstr "设置 ``file_max_count`` 以防止无限制的磁盘使用"
+
+#: ../../source/production/observability/chunk_statistics.rst:341
+msgid "**Production Deployment:**"
+msgstr "**生产部署：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:343
+msgid "Enable auto-stop to prevent indefinite data collection"
+msgstr "启用自动停止以防止无限期的数据收集"
+
+#: ../../source/production/observability/chunk_statistics.rst:344
+msgid "Use internal API server for centralized metrics collection"
+msgstr "使用内部 API 服务器进行集中式指标收集"
+
+#: ../../source/production/observability/chunk_statistics.rst:345
+msgid "Integrate with your monitoring stack (Prometheus, Grafana, etc.)"
+msgstr "与您的监控栈集成（Prometheus、Grafana 等）"
+
+#: ../../source/production/observability/chunk_statistics.rst:348
+msgid "Troubleshooting"
+msgstr "故障排除"
+
+#: ../../source/production/observability/chunk_statistics.rst:351
+msgid "Statistics Not Updating"
+msgstr "统计未更新"
+
+#: ../../source/production/observability/chunk_statistics.rst:353
+msgid "**Issue:** Statistics remain at zero or don't update."
+msgstr "**问题：** 统计数据保持为零或不更新。"
+
+#: ../../source/production/observability/chunk_statistics.rst:355
+#: ../../source/production/observability/chunk_statistics.rst:366
+#: ../../source/production/observability/chunk_statistics.rst:377
+msgid "**Solutions:**"
+msgstr "**解决方案：**"
+
+#: ../../source/production/observability/chunk_statistics.rst:357
+msgid "Verify ``enable_chunk_statistics`` is set to ``true``"
+msgstr "验证 ``enable_chunk_statistics`` 是否设置为 ``true``"
+
+#: ../../source/production/observability/chunk_statistics.rst:358
+msgid "Check that statistics collection is started (auto-start or manual start)"
+msgstr "检查统计收集是否已启动（自动启动或手动启动）"
+
+#: ../../source/production/observability/chunk_statistics.rst:359
+msgid "Ensure requests are being processed by the LMCache instance"
+msgstr "确保请求正在被 LMCache 实例处理"
+
+#: ../../source/production/observability/chunk_statistics.rst:362
+msgid "High Memory Usage"
+msgstr "高内存使用率"
+
+#: ../../source/production/observability/chunk_statistics.rst:364
+msgid "**Issue:** Bloom filter consuming too much memory."
+msgstr "**问题：** Bloom 过滤器消耗了过多的内存。"
+
+#: ../../source/production/observability/chunk_statistics.rst:368
+msgid "Reduce ``chunk_statistics_mem_bf_expected_chunks``"
+msgstr "减少 ``chunk_statistics_mem_bf_expected_chunks``"
+
+#: ../../source/production/observability/chunk_statistics.rst:369
+msgid ""
+"Increase ``chunk_statistics_mem_bf_false_positive_rate`` (trade accuracy "
+"for memory)"
+msgstr "增加 ``chunk_statistics_mem_bf_false_positive_rate`` （以牺牲准确性换取内存）"
+
+#: ../../source/production/observability/chunk_statistics.rst:370
+msgid "Consider switching to ``file_hash`` strategy"
+msgstr "考虑切换到 ``file_hash`` 策略"
+
+#: ../../source/production/observability/chunk_statistics.rst:373
+msgid "File System Full"
+msgstr "文件系统已满"
+
+#: ../../source/production/observability/chunk_statistics.rst:375
+msgid "**Issue:** Disk space exhausted with file hash strategy."
+msgstr "**问题：** 磁盘空间耗尽，使用文件哈希策略。"
+
+#: ../../source/production/observability/chunk_statistics.rst:379
+msgid "Reduce ``chunk_statistics_file_max_count``"
+msgstr "减少 ``chunk_statistics_file_max_count``"
+
+#: ../../source/production/observability/chunk_statistics.rst:380
+msgid "Decrease ``chunk_statistics_file_rotation_size``"
+msgstr "减少 ``chunk_statistics_file_rotation_size``"
+
+#: ../../source/production/observability/chunk_statistics.rst:381
+msgid "Implement external log rotation or archival"
+msgstr "实现外部日志轮换或归档"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/frontend.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/frontend.po
new file mode 100644
index 0000000..242c503
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/frontend.po
@@ -0,0 +1,234 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/frontend.rst:4
+msgid "LMCache Frontend"
+msgstr "LMCache 前端"
+
+#: ../../source/production/observability/frontend.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/frontend_dashboard`."
+msgstr ""
+
+#: ../../source/production/observability/frontend.rst:11
+msgid ""
+"LMCache Frontend is a monitoring and proxy service for LMCache clusters, "
+"providing a web interface for cluster management and HTTP request "
+"proxying to cluster nodes."
+msgstr ""
+"LMCache Frontend 是一个用于 LMCache 集群的监控和代理服务，提供集群管理的 Web 界面以及对集群节点的 HTTP "
+"请求代理。"
+
+#: ../../source/production/observability/frontend.rst:15
+msgid "LMCache Frontend Dashboard"
+msgstr "LMCache 前端仪表板"
+
+#: ../../source/production/observability/frontend.rst:21
+msgid "Features"
+msgstr "功能"
+
+#: ../../source/production/observability/frontend.rst:23
+msgid "**Cluster Monitoring**: Web-based dashboard for visualizing cluster status"
+msgstr "**集群监控**\\ ：基于网页的仪表板，用于可视化集群状态"
+
+#: ../../source/production/observability/frontend.rst:24
+msgid ""
+"**Request Proxying**: HTTP proxy service to forward requests to any "
+"cluster node"
+msgstr "**请求代理**\\ ：HTTP 代理服务，用于将请求转发到任何集群节点"
+
+#: ../../source/production/observability/frontend.rst:25
+msgid ""
+"**Flexible Configuration**: Support for both IP:port and Unix domain "
+"sockets"
+msgstr "**灵活配置**\\ ：支持 IP:端口 和 Unix 域套接字"
+
+#: ../../source/production/observability/frontend.rst:26
+msgid "**Plugin System**: Integration with LMCache plugin framework"
+msgstr "**插件系统**\\ ：与 LMCache 插件框架的集成"
+
+#: ../../source/production/observability/frontend.rst:30
+msgid "Installation"
+msgstr "安装"
+
+#: ../../source/production/observability/frontend.rst:32
+msgid "Install from PyPI:"
+msgstr "从 PyPI 安装："
+
+#: ../../source/production/observability/frontend.rst:38
+msgid "Or install from source:"
+msgstr "或从源代码安装："
+
+#: ../../source/production/observability/frontend.rst:48
+msgid "Quick Start"
+msgstr "快速开始"
+
+#: ../../source/production/observability/frontend.rst:51
+msgid "Starting the Service"
+msgstr "启动服务"
+
+#: ../../source/production/observability/frontend.rst:59
+msgid "Command Line Options"
+msgstr "命令行选项"
+
+#: ../../source/production/observability/frontend.rst:65
+msgid "Option"
+msgstr "选项"
+
+#: ../../source/production/observability/frontend.rst:66
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/frontend.rst:67
+msgid "``--port``"
+msgstr "``--port``"
+
+#: ../../source/production/observability/frontend.rst:68
+msgid "Service port (default: 8000)"
+msgstr "服务端口（默认：8000）"
+
+#: ../../source/production/observability/frontend.rst:69
+msgid "``--host``"
+msgstr "``--host``"
+
+#: ../../source/production/observability/frontend.rst:70
+msgid "Bind host address (default: 0.0.0.0)"
+msgstr "绑定主机地址（默认：0.0.0.0）"
+
+#: ../../source/production/observability/frontend.rst:71
+msgid "``--config``"
+msgstr "``--config``"
+
+#: ../../source/production/observability/frontend.rst:72
+msgid "Path to configuration file"
+msgstr "配置文件路径"
+
+#: ../../source/production/observability/frontend.rst:73
+msgid "``--nodes``"
+msgstr "``--nodes``"
+
+#: ../../source/production/observability/frontend.rst:74
+msgid "Direct node configuration (JSON string)"
+msgstr "直接节点配置（JSON 字符串）"
+
+#: ../../source/production/observability/frontend.rst:77
+msgid ""
+"After starting the service, access the dashboard at "
+"``http://localhost:8080/``."
+msgstr "启动服务后，可以通过访问 ``http://localhost:8080/`` 来查看仪表板。"
+
+#: ../../source/production/observability/frontend.rst:81
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/production/observability/frontend.rst:84
+msgid "Node Configuration"
+msgstr "节点配置"
+
+#: ../../source/production/observability/frontend.rst:86
+msgid "Create a ``config.json`` file with node definitions:"
+msgstr "创建一个 ``config.json`` 文件，包含节点定义："
+
+#: ../../source/production/observability/frontend.rst:103
+msgid ""
+"The ``port`` field can be configured as either an integer port number or "
+"a string path for Unix domain sockets."
+msgstr "``port`` 字段可以配置为整数端口号或 Unix 域套接字的字符串路径。"
+
+#: ../../source/production/observability/frontend.rst:108
+msgid "LMCache Plugin Integration"
+msgstr "LMCache 插件集成"
+
+#: ../../source/production/observability/frontend.rst:110
+msgid ""
+"To start the frontend via the LMCache plugin framework, add the following"
+" to your ``lmcache.yaml``:"
+msgstr "要通过 LMCache 插件框架启动前端，请将以下内容添加到您的 ``lmcache.yaml`` 中："
+
+#: ../../source/production/observability/frontend.rst:124
+msgid "Proxying Requests"
+msgstr "代理请求"
+
+#: ../../source/production/observability/frontend.rst:126
+msgid "Proxy requests using the format:"
+msgstr "使用以下格式代理请求："
+
+#: ../../source/production/observability/frontend.rst:132
+msgid "Examples:"
+msgstr "示例："
+
+#: ../../source/production/observability/frontend.rst:145
+msgid "Contributing"
+msgstr "贡献"
+
+#: ../../source/production/observability/frontend.rst:147
+msgid ""
+"LMCache Frontend is an open-source project and we welcome contributions "
+"from the community! Whether you want to fix bugs, add new features, "
+"improve documentation, or share ideas, your contributions are "
+"appreciated."
+msgstr "LMCache 前端是一个开源项目，我们欢迎社区的贡献！无论您想修复错误、添加新功能、改善文档还是分享想法，我们都非常感谢您的贡献。"
+
+#: ../../source/production/observability/frontend.rst:151
+msgid "Ways to contribute:"
+msgstr "贡献方式："
+
+#: ../../source/production/observability/frontend.rst:153
+msgid ""
+"**Report Issues**: Found a bug or have a feature request? Open an issue "
+"on GitHub."
+msgstr "**报告问题**\\ ：发现了一个错误或有功能请求？在 GitHub 上提交一个问题。"
+
+#: ../../source/production/observability/frontend.rst:155
+msgid ""
+"**Submit Pull Requests**: Fork the repository, make your changes, and "
+"submit a PR."
+msgstr "**提交拉取请求**\\ ：分叉仓库，进行更改，并提交 PR。"
+
+#: ../../source/production/observability/frontend.rst:157
+msgid "**Improve Documentation**: Help us make the docs clearer and more helpful."
+msgstr "**改善文档**\\ ：帮助我们使文档更清晰、更有帮助。"
+
+#: ../../source/production/observability/frontend.rst:158
+msgid ""
+"**Share Feedback**: Let us know how you're using LMCache Frontend and "
+"what could be improved."
+msgstr "**分享反馈**\\ ：让我们知道您如何使用 LMCache 前端以及可以改进的地方。"
+
+#: ../../source/production/observability/frontend.rst:161
+msgid "Join us in making LMCache Frontend better for everyone!"
+msgstr "加入我们，让 LMCache Frontend 变得更好！"
+
+#: ../../source/production/observability/frontend.rst:165
+msgid "More Information"
+msgstr "更多信息"
+
+#: ../../source/production/observability/frontend.rst:167
+msgid ""
+"For more details, visit the `LMCache Frontend GitHub repository "
+"<https://github.com/LMCache/lmcache_frontend>`_."
+msgstr ""
+"有关更多详细信息，请访问 `LMCache Frontend GitHub 仓库 "
+"<https://github.com/LMCache/lmcache_frontend>`_。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/health_monitor.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/health_monitor.po
new file mode 100644
index 0000000..b11e8b0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/health_monitor.po
@@ -0,0 +1,495 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/health_monitor.rst:4
+msgid "Health Monitor"
+msgstr "健康监控器"
+
+#: ../../source/production/observability/health_monitor.rst:6
+msgid ""
+"LMCache includes a comprehensive health monitoring framework that "
+"continuously monitors the health of the cache engine and its components. "
+"This feature is essential for production deployments to detect and "
+"respond to failures in remote storage backends."
+msgstr "LMCache 包含一个全面的健康监测框架，持续监测缓存引擎及其组件的健康状况。此功能对于生产环境的部署至关重要，可以检测并响应远程存储后端的故障。"
+
+#: ../../source/production/observability/health_monitor.rst:9
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/production/observability/health_monitor.rst:11
+msgid "The Health Monitor provides:"
+msgstr "健康监控器提供："
+
+#: ../../source/production/observability/health_monitor.rst:13
+msgid ""
+"**Automatic health checks**: Periodically monitors the health of all "
+"registered components"
+msgstr "**自动健康检查**\\ ：定期监控所有注册组件的健康状况"
+
+#: ../../source/production/observability/health_monitor.rst:14
+msgid ""
+"**Extensible framework**: Easily add custom health checks for new "
+"components"
+msgstr "**可扩展框架**\\ ：轻松为新组件添加自定义健康检查"
+
+#: ../../source/production/observability/health_monitor.rst:15
+msgid ""
+"**Remote backend monitoring**: Built-in support for monitoring remote "
+"storage backends via ping"
+msgstr "**远程后端监控**\\ ：内置支持通过 ping 监控远程存储后端"
+
+#: ../../source/production/observability/health_monitor.rst:16
+msgid ""
+"**Degraded mode support**: Automatically blocks operations when the "
+"system is unhealthy"
+msgstr "**降级模式支持**\\ ：当系统不健康时自动阻止操作"
+
+#: ../../source/production/observability/health_monitor.rst:17
+msgid ""
+"**Prometheus metrics integration**: Health status exposed via metrics "
+"endpoint"
+msgstr "**Prometheus 指标集成**\\ ：通过指标端点暴露健康状态"
+
+#: ../../source/production/observability/health_monitor.rst:20
+msgid "Architecture"
+msgstr "架构"
+
+#: ../../source/production/observability/health_monitor.rst:22
+msgid "The health monitoring system consists of three main components:"
+msgstr "健康监测系统由三个主要组件组成："
+
+#: ../../source/production/observability/health_monitor.rst:24
+msgid "**HealthCheck (Abstract Base Class)**"
+msgstr "**健康检查（抽象基类）**"
+
+#: ../../source/production/observability/health_monitor.rst:26
+msgid ""
+"Base class for individual health checks. Each health check represents one"
+" aspect of system health."
+msgstr "单个健康检查的基类。每个健康检查代表系统健康的一个方面。"
+
+#: ../../source/production/observability/health_monitor.rst:28
+msgid "**HealthMonitor**"
+msgstr "**健康监控器**"
+
+#: ../../source/production/observability/health_monitor.rst:30
+msgid ""
+"The central monitor that orchestrates all health checks. It runs in a "
+"background thread and periodically executes all registered health checks."
+msgstr "中央监控器，负责协调所有健康检查。它在后台线程中运行，并定期执行所有注册的健康检查。"
+
+#: ../../source/production/observability/health_monitor.rst:32
+msgid "**RemoteBackendHealthCheck**"
+msgstr "**RemoteBackendHealthCheck**"
+
+#: ../../source/production/observability/health_monitor.rst:34
+msgid ""
+"Built-in health check for remote storage backends. It pings the remote "
+"connector to verify connectivity."
+msgstr "内置的远程存储后端健康检查。它会向远程连接器发送请求以验证连接性。"
+
+#: ../../source/production/observability/health_monitor.rst:37
+msgid "Auto-Discovery"
+msgstr "自动发现"
+
+#: ../../source/production/observability/health_monitor.rst:39
+msgid ""
+"The Health Monitor uses an auto-discovery mechanism to find and "
+"instantiate health checks:"
+msgstr "健康监控器使用自动发现机制来查找和实例化健康检查："
+
+#: ../../source/production/observability/health_monitor.rst:41
+msgid ""
+"At startup, the monitor scans the ``lmcache.v1.health_monitor.checks`` "
+"package"
+msgstr "在启动时，监视器扫描 ``lmcache.v1.health_monitor.checks`` 包"
+
+#: ../../source/production/observability/health_monitor.rst:42
+msgid "All classes that inherit from ``HealthCheck`` are discovered"
+msgstr "所有继承自 ``HealthCheck`` 的类都会被发现"
+
+#: ../../source/production/observability/health_monitor.rst:43
+msgid "Each check's ``create_from_engine()`` method is called to create instances"
+msgstr "每个检查的 ``create_from_engine()`` 方法被调用以创建实例"
+
+#: ../../source/production/observability/health_monitor.rst:44
+msgid "The instances are registered with the monitor"
+msgstr "这些实例会被注册到监视器中。"
+
+#: ../../source/production/observability/health_monitor.rst:46
+msgid ""
+"This design allows you to add new health checks by simply creating a new "
+"module in the checks package."
+msgstr "此设计允许您通过在检查包中简单地创建一个新模块来添加新的健康检查。"
+
+#: ../../source/production/observability/health_monitor.rst:49
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/production/observability/health_monitor.rst:51
+msgid ""
+"Health monitor configuration is done through the ``extra_config`` section"
+" of your LMCache configuration:"
+msgstr "健康监控配置通过您的 LMCache 配置的 ``extra_config`` 部分完成："
+
+#: ../../source/production/observability/health_monitor.rst:53
+msgid "Health Monitor Configuration Options"
+msgstr "健康监控配置选项"
+
+#: ../../source/production/observability/health_monitor.rst:57
+msgid "Configuration Key"
+msgstr "配置键"
+
+#: ../../source/production/observability/health_monitor.rst:58
+msgid "Default Value"
+msgstr "默认值"
+
+#: ../../source/production/observability/health_monitor.rst:59
+#: ../../source/production/observability/health_monitor.rst:148
+#: ../../source/production/observability/health_monitor.rst:175
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/health_monitor.rst:60
+msgid "``ping_interval``"
+msgstr "``ping_interval``"
+
+#: ../../source/production/observability/health_monitor.rst:61
+msgid "``30.0``"
+msgstr "``30.0``"
+
+#: ../../source/production/observability/health_monitor.rst:62
+msgid "Interval (in seconds) between health check cycles"
+msgstr "健康检查周期之间的间隔（以秒为单位）"
+
+#: ../../source/production/observability/health_monitor.rst:63
+msgid "``ping_timeout``"
+msgstr "``ping_timeout``"
+
+#: ../../source/production/observability/health_monitor.rst:64
+msgid "``5.0``"
+msgstr "``5.0``"
+
+#: ../../source/production/observability/health_monitor.rst:65
+msgid "Timeout (in seconds) for each ping operation"
+msgstr "每次 ping 操作的超时时间（以秒为单位）"
+
+#: ../../source/production/observability/health_monitor.rst:66
+msgid "``get_blocking_failed_threshold``"
+msgstr "``get_blocking_failed_threshold``"
+
+#: ../../source/production/observability/health_monitor.rst:67
+msgid "``10``"
+msgstr "``10``"
+
+#: ../../source/production/observability/health_monitor.rst:68
+msgid "Max number of get_blocking failed count in check interval"
+msgstr "检查时间间隔内获取阻塞失败的最大次数"
+
+#: ../../source/production/observability/health_monitor.rst:69
+msgid "``waiting_time_for_recovery``"
+msgstr "``waiting_time_for_recovery``"
+
+#: ../../source/production/observability/health_monitor.rst:70
+msgid "``300.0``"
+msgstr "``300.0``"
+
+#: ../../source/production/observability/health_monitor.rst:71
+msgid "Waiting time (in seconds) for recovery if get_blocking failed"
+msgstr "如果 get_blocking 失败，恢复的等待时间（以秒为单位）"
+
+#: ../../source/production/observability/health_monitor.rst:75
+msgid "How It Works"
+msgstr "它是如何工作的"
+
+#: ../../source/production/observability/health_monitor.rst:78
+msgid "Runtime Behavior"
+msgstr "运行时行为"
+
+#: ../../source/production/observability/health_monitor.rst:80
+msgid "The health monitor runs in a background thread:"
+msgstr "健康监控在后台线程中运行："
+
+#: ../../source/production/observability/health_monitor.rst:82
+msgid "Every ``ping_interval`` seconds, all health checks are executed"
+msgstr "每 ``ping_interval`` 秒，所有健康检查都会执行"
+
+#: ../../source/production/observability/health_monitor.rst:83
+msgid "If any check fails, the system is marked as unhealthy"
+msgstr "如果任何检查失败，系统将被标记为不健康。"
+
+#: ../../source/production/observability/health_monitor.rst:84
+msgid "When unhealthy, store/retrieve operations are blocked with a warning log"
+msgstr "当系统不健康时，存储/检索操作会被阻止，并记录警告日志。"
+
+#: ../../source/production/observability/health_monitor.rst:85
+msgid ""
+"Once all checks pass again, the system is marked as healthy and "
+"operations resume"
+msgstr "一旦所有检查再次通过，系统将被标记为健康，操作将恢复。"
+
+#: ../../source/production/observability/health_monitor.rst:88
+msgid "Initialization Failure Handling"
+msgstr "初始化失败处理"
+
+#: ../../source/production/observability/health_monitor.rst:90
+msgid "When initialization or post-initialization fails irrecoverably:"
+msgstr "当初始化或后初始化不可恢复地失败时："
+
+#: ../../source/production/observability/health_monitor.rst:92
+msgid "The system is marked with ``_init_failed = True``"
+msgstr "系统被标记为 ``_init_failed = True``"
+
+#: ../../source/production/observability/health_monitor.rst:93
+msgid "``is_healthy()`` method returns ``False`` permanently"
+msgstr "``is_healthy()`` 方法永久返回 ``False``"
+
+#: ../../source/production/observability/health_monitor.rst:94
+msgid ""
+"Health monitoring thread will not start (if initialization fails before "
+"it starts)"
+msgstr "健康监控线程将不会启动（如果初始化在启动之前失败）"
+
+#: ../../source/production/observability/health_monitor.rst:95
+msgid "The system operates in degraded mode (recompute-only)"
+msgstr "系统以降级模式运行（仅重计算）"
+
+#: ../../source/production/observability/health_monitor.rst:97
+msgid ""
+"This ensures that irrecoverable initialization errors don't cause "
+"cascading failures and the system can gracefully fall back to "
+"recomputation."
+msgstr "这确保不可恢复的初始化错误不会导致级联故障，并且系统可以优雅地回退到重计算。"
+
+#: ../../source/production/observability/health_monitor.rst:101
+msgid "Graceful Degradation"
+msgstr "优雅降级"
+
+#: ../../source/production/observability/health_monitor.rst:103
+msgid "When the health monitor detects an unhealthy state:"
+msgstr "当健康监测器检测到不健康状态时："
+
+#: ../../source/production/observability/health_monitor.rst:105
+msgid "**Store operations**: Skipped with a warning message"
+msgstr "**存储操作**\\ ：跳过并显示警告信息"
+
+#: ../../source/production/observability/health_monitor.rst:106
+msgid "**Retrieve operations**: Return empty results with a warning message"
+msgstr "**检索操作**\\ ：返回空结果并带有警告信息"
+
+#: ../../source/production/observability/health_monitor.rst:107
+msgid "**Lookup operations**: Return 0 (no cache hits) with a warning message"
+msgstr "**查找操作**\\ ：返回 0（没有缓存命中）并附带警告信息"
+
+#: ../../source/production/observability/health_monitor.rst:109
+msgid "This prevents cascading failures when remote backends are unavailable."
+msgstr "这可以防止在远程后端不可用时发生级联故障。"
+
+#: ../../source/production/observability/health_monitor.rst:112
+msgid "Built-in Health Checks"
+msgstr "内置健康检查"
+
+#: ../../source/production/observability/health_monitor.rst:115
+msgid "RemoteBackendHealthCheck"
+msgstr "RemoteBackendHealthCheck"
+
+#: ../../source/production/observability/health_monitor.rst:117
+msgid ""
+"This check monitors the connectivity to remote storage backends (e.g., "
+"Redis, Valkey)."
+msgstr "此检查监控与远程存储后端（例如，Redis、Valkey）的连接性。"
+
+#: ../../source/production/observability/health_monitor.rst:119
+msgid "**What it checks:**"
+msgstr "**检查内容：**"
+
+#: ../../source/production/observability/health_monitor.rst:121
+msgid "Pings the remote connector to verify it's reachable"
+msgstr "对远程连接器进行 ping 测试以验证其可达性"
+
+#: ../../source/production/observability/health_monitor.rst:122
+msgid "Measures ping latency"
+msgstr "测量 ping 延迟"
+
+#: ../../source/production/observability/health_monitor.rst:123
+msgid "Reports error codes for failures"
+msgstr "报告失败的错误代码"
+
+#: ../../source/production/observability/health_monitor.rst:125
+msgid "**When it's active:**"
+msgstr "**当它处于活动状态时：**"
+
+#: ../../source/production/observability/health_monitor.rst:127
+msgid "Only when a remote backend is configured (``remote_url`` is set)"
+msgstr "仅在配置了远程后端时（\\ ``remote_url`` 已设置）"
+
+#: ../../source/production/observability/health_monitor.rst:128
+msgid "Only if the connector supports the ``ping()`` operation"
+msgstr "仅当连接器支持 ``ping()`` 操作时"
+
+#: ../../source/production/observability/health_monitor.rst:130
+msgid "**Metrics reported:**"
+msgstr "**报告的指标：**"
+
+#: ../../source/production/observability/health_monitor.rst:132
+msgid "``lmcache:remote_ping_latency``: Latest ping latency (milliseconds)"
+msgstr "``lmcache:remote_ping_latency``: 最新的 ping 延迟（毫秒）"
+
+#: ../../source/production/observability/health_monitor.rst:133
+msgid "``lmcache:remote_ping_error_code``: Latest error code (0 = success)"
+msgstr "``lmcache:remote_ping_error_code``: 最新错误代码 (0 = 成功)"
+
+#: ../../source/production/observability/health_monitor.rst:134
+msgid "``lmcache:remote_ping_errors``: Total number of ping errors"
+msgstr "``lmcache:remote_ping_errors``: 总的 ping 错误数量"
+
+#: ../../source/production/observability/health_monitor.rst:135
+msgid "``lmcache:remote_ping_successes``: Total number of successful pings"
+msgstr "``lmcache:remote_ping_successes``: 成功 ping 的总次数"
+
+#: ../../source/production/observability/health_monitor.rst:138
+msgid "Prometheus Metrics"
+msgstr "Prometheus 指标"
+
+#: ../../source/production/observability/health_monitor.rst:140
+msgid "The health monitor exposes metrics through the Prometheus endpoint:"
+msgstr "健康监控器通过 Prometheus 端点公开指标："
+
+#: ../../source/production/observability/health_monitor.rst:142
+msgid "Health Monitor Metrics"
+msgstr "健康监控指标"
+
+#: ../../source/production/observability/health_monitor.rst:146
+msgid "Metric Name"
+msgstr "指标名称"
+
+#: ../../source/production/observability/health_monitor.rst:147
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/production/observability/health_monitor.rst:149
+msgid "``lmcache:is_healthy``"
+msgstr "``lmcache:is_healthy``"
+
+#: ../../source/production/observability/health_monitor.rst:150
+#: ../../source/production/observability/health_monitor.rst:153
+#: ../../source/production/observability/health_monitor.rst:156
+msgid "Gauge"
+msgstr "仪表"
+
+#: ../../source/production/observability/health_monitor.rst:151
+msgid "Overall system health status (1 = healthy, 0 = unhealthy)"
+msgstr "整体系统健康状态（1 = 健康，0 = 不健康）"
+
+#: ../../source/production/observability/health_monitor.rst:152
+msgid "``lmcache:remote_ping_latency``"
+msgstr "``lmcache:remote_ping_latency``"
+
+#: ../../source/production/observability/health_monitor.rst:154
+msgid "Latest ping latency to remote backends (milliseconds)"
+msgstr "最新的远程后端 ping 延迟（毫秒）"
+
+#: ../../source/production/observability/health_monitor.rst:155
+msgid "``lmcache:remote_ping_error_code``"
+msgstr "``lmcache:remote_ping_error_code``"
+
+#: ../../source/production/observability/health_monitor.rst:157
+msgid "Latest ping error code (0 = success, -1 = timeout, -2 = generic error)"
+msgstr "最新的 ping 错误代码（0 = 成功，-1 = 超时，-2 = 通用错误）"
+
+#: ../../source/production/observability/health_monitor.rst:158
+msgid "``lmcache:remote_ping_errors``"
+msgstr "``lmcache:remote_ping_errors``"
+
+#: ../../source/production/observability/health_monitor.rst:159
+#: ../../source/production/observability/health_monitor.rst:162
+msgid "Counter"
+msgstr "计数器"
+
+#: ../../source/production/observability/health_monitor.rst:160
+msgid "Total number of ping errors to remote backends"
+msgstr "远程后端的总 ping 错误数量"
+
+#: ../../source/production/observability/health_monitor.rst:161
+msgid "``lmcache:remote_ping_successes``"
+msgstr "``lmcache:remote_ping_successes``"
+
+#: ../../source/production/observability/health_monitor.rst:163
+msgid "Total number of successful pings to remote backends"
+msgstr "成功 ping 远程后端的总次数"
+
+#: ../../source/production/observability/health_monitor.rst:166
+msgid "Error Codes"
+msgstr "错误代码"
+
+#: ../../source/production/observability/health_monitor.rst:168
+msgid "The health check system uses the following error codes:"
+msgstr "健康检查系统使用以下错误代码："
+
+#: ../../source/production/observability/health_monitor.rst:170
+msgid "Health Check Error Codes"
+msgstr "健康检查错误代码"
+
+#: ../../source/production/observability/health_monitor.rst:174
+msgid "Code"
+msgstr "代码"
+
+#: ../../source/production/observability/health_monitor.rst:176
+msgid "``0``"
+msgstr "``0``"
+
+#: ../../source/production/observability/health_monitor.rst:177
+msgid "Success - the health check passed"
+msgstr "成功 - 健康检查通过"
+
+#: ../../source/production/observability/health_monitor.rst:178
+msgid "``-1``"
+msgstr "``-1``"
+
+#: ../../source/production/observability/health_monitor.rst:179
+msgid "Timeout - the ping operation exceeded the configured timeout"
+msgstr "超时 - ping 操作超过了配置的超时时间"
+
+#: ../../source/production/observability/health_monitor.rst:180
+msgid "``-2``"
+msgstr "``-2``"
+
+#: ../../source/production/observability/health_monitor.rst:181
+msgid "Generic error - an unexpected error occurred during the health check"
+msgstr "通用错误 - 在健康检查期间发生了意外错误"
+
+#: ../../source/production/observability/health_monitor.rst:184
+msgid "Extending the Health Monitor"
+msgstr "扩展健康监控器"
+
+#: ../../source/production/observability/health_monitor.rst:186
+msgid ""
+"You can add custom health checks by creating a new module in the "
+"``lmcache/v1/health_monitor/checks/`` directory."
+msgstr "您可以通过在 ``lmcache/v1/health_monitor/checks/`` 目录中创建新模块来添加自定义健康检查。"
+
+#: ../../source/production/observability/health_monitor.rst:188
+msgid ""
+"The custom check will be automatically discovered and registered when "
+"LMCache starts."
+msgstr "当 LMCache 启动时，自定义检查将被自动发现并注册。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/index.po
new file mode 100644
index 0000000..8b7e433
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/index.po
@@ -0,0 +1,33 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/index.rst:4
+msgid "Observability"
+msgstr "可观察性"
+
+#: ../../source/production/observability/index.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance. For the MP mode equivalent of"
+" this page, see :doc:`/mp/observability/index`."
+msgstr ""
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/internal_api_server.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/internal_api_server.po
new file mode 100644
index 0000000..bb9d9cd
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/internal_api_server.po
@@ -0,0 +1,145 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/internal_api_server.rst:4
+msgid "Internal API Server Metrics"
+msgstr "内部 API 服务器指标"
+
+#: ../../source/production/observability/internal_api_server.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr ""
+
+#: ../../source/production/observability/internal_api_server.rst:11
+msgid ""
+"Another approach to retrieve LMCache metrics is to use the internal API "
+"server."
+msgstr "另一种获取 LMCache 指标的方法是使用内部 API 服务器。"
+
+#: ../../source/production/observability/internal_api_server.rst:14
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/production/observability/internal_api_server.rst:16
+msgid ""
+"The internal API server exposes Prometheus-compatible metrics endpoints "
+"in your LMCache deployment."
+msgstr "内部 API 服务器在您的 LMCache 部署中公开与 Prometheus 兼容的指标端点。"
+
+#: ../../source/production/observability/internal_api_server.rst:19
+msgid "Quick Start Guide"
+msgstr "快速入门指南"
+
+#: ../../source/production/observability/internal_api_server.rst:22
+msgid "Step 1: Enable Internal API Server"
+msgstr "步骤 1：启用内部 API 服务器"
+
+#: ../../source/production/observability/internal_api_server.rst:24
+msgid "Configure your vLLM instance to enable the internal API server:"
+msgstr "配置您的 vLLM 实例以启用内部 API 服务器："
+
+#: ../../source/production/observability/internal_api_server.rst:33
+msgid "Step 2: Access Metrics Endpoint"
+msgstr "步骤 2：访问指标端点"
+
+#: ../../source/production/observability/internal_api_server.rst:35
+msgid "Retrieve metrics from the worker's endpoint:"
+msgstr "从工作节点的端点检索指标："
+
+#: ../../source/production/observability/internal_api_server.rst:42
+msgid "Port Configuration"
+msgstr "端口配置"
+
+#: ../../source/production/observability/internal_api_server.rst:44
+msgid ""
+"The following environment variables are used implicitly with their "
+"default values:"
+msgstr "以下环境变量隐式使用其默认值："
+
+#: ../../source/production/observability/internal_api_server.rst:46
+msgid "Default Port Configuration"
+msgstr "默认端口配置"
+
+#: ../../source/production/observability/internal_api_server.rst:50
+msgid "Environment Variable"
+msgstr "环境变量"
+
+#: ../../source/production/observability/internal_api_server.rst:51
+msgid "Default Value"
+msgstr "默认值"
+
+#: ../../source/production/observability/internal_api_server.rst:52
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/internal_api_server.rst:53
+msgid "``LMCACHE_INTERNAL_API_SERVER_HOST``"
+msgstr "``LMCACHE_INTERNAL_API_SERVER_HOST``"
+
+#: ../../source/production/observability/internal_api_server.rst:54
+msgid "``0.0.0.0``"
+msgstr "``0.0.0.0``"
+
+#: ../../source/production/observability/internal_api_server.rst:55
+msgid "Host address for the internal API server to bind to."
+msgstr "内部 API 服务器绑定的主机地址。"
+
+#: ../../source/production/observability/internal_api_server.rst:56
+msgid "``LMCACHE_INTERNAL_API_SERVER_PORT_START``"
+msgstr "``LMCACHE_INTERNAL_API_SERVER_PORT_START``"
+
+#: ../../source/production/observability/internal_api_server.rst:57
+msgid "``6999``"
+msgstr "``6999``"
+
+#: ../../source/production/observability/internal_api_server.rst:58
+msgid "Starting port number, e.g.:"
+msgstr "起始端口号，例如："
+
+#: ../../source/production/observability/internal_api_server.rst:60
+msgid "Scheduler: port_start + 0 (6999)"
+msgstr "调度程序：port_start + 0 (6999)"
+
+#: ../../source/production/observability/internal_api_server.rst:61
+msgid "Worker 0: port_start + 1 (7000)"
+msgstr "工作线程 0: port_start + 1 (7000)"
+
+#: ../../source/production/observability/internal_api_server.rst:62
+msgid "Worker 1: port_start + 2 (7001)"
+msgstr "Worker 1: port_start + 2 (7001)"
+
+#: ../../source/production/observability/internal_api_server.rst:65
+msgid "Therefore, the metrics endpoint curl command above uses port 7000."
+msgstr "因此，上述指标端点的 curl 命令使用端口 7000。"
+
+#: ../../source/production/observability/internal_api_server.rst:68
+msgid "Advanced Usage"
+msgstr "高级用法"
+
+#: ../../source/production/observability/internal_api_server.rst:70
+msgid ""
+"For comprehensive testing and configuration options, refer to "
+":ref:`testing_internal_api_server` for detailed examples and best "
+"practices."
+msgstr "有关全面的测试和配置选项，请参阅 :ref:`testing_internal_api_server` 以获取详细示例和最佳实践。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/metrics.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/metrics.po
new file mode 100644
index 0000000..be20252
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/metrics.po
@@ -0,0 +1,899 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-05-18 17:25+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/metrics.rst:4
+msgid "Metrics Reference"
+msgstr "指标参考"
+
+#: ../../source/production/observability/metrics.rst:6
+msgid ""
+"LMCache provides comprehensive metrics via Prometheus to help you monitor"
+" performance, cache efficiency, and system health. These metrics are "
+"exposed via the vLLM ``/metrics`` endpoint when LMCache is integrated "
+"with vLLM, or via the LMCache internal API server."
+msgstr "LMCache 通过 Prometheus 提供全面的指标，以帮助您监控性能、缓存效率和系统健康。这些指标在 LMCache 与 vLLM 集成时通过 vLLM ``/metrics`` 端点公开，或者通过 LMCache 内部 API 服务器公开。"
+
+#: ../../source/production/observability/metrics.rst:9
+msgid "Available Metrics"
+msgstr "可用指标"
+
+#: ../../source/production/observability/metrics.rst:11
+msgid ""
+"The following tables list all available LMCache metrics organized by "
+"category."
+msgstr "以下表格列出了按类别组织的所有可用 LMCache 指标。"
+
+#: ../../source/production/observability/metrics.rst:14
+#: ../../source/production/observability/metrics.rst:16
+msgid "Core Request Metrics"
+msgstr "核心请求指标"
+
+#: ../../source/production/observability/metrics.rst:20
+#: ../../source/production/observability/metrics.rst:40
+#: ../../source/production/observability/metrics.rst:72
+#: ../../source/production/observability/metrics.rst:95
+#: ../../source/production/observability/metrics.rst:127
+#: ../../source/production/observability/metrics.rst:162
+#: ../../source/production/observability/metrics.rst:185
+#: ../../source/production/observability/metrics.rst:229
+#: ../../source/production/observability/metrics.rst:255
+#: ../../source/production/observability/metrics.rst:278
+#: ../../source/production/observability/metrics.rst:301
+#: ../../source/production/observability/metrics.rst:333
+#: ../../source/production/observability/metrics.rst:371
+msgid "Metric Name"
+msgstr "指标名称"
+
+#: ../../source/production/observability/metrics.rst:21
+#: ../../source/production/observability/metrics.rst:41
+#: ../../source/production/observability/metrics.rst:73
+#: ../../source/production/observability/metrics.rst:96
+#: ../../source/production/observability/metrics.rst:128
+#: ../../source/production/observability/metrics.rst:163
+#: ../../source/production/observability/metrics.rst:186
+#: ../../source/production/observability/metrics.rst:230
+#: ../../source/production/observability/metrics.rst:256
+#: ../../source/production/observability/metrics.rst:279
+#: ../../source/production/observability/metrics.rst:302
+#: ../../source/production/observability/metrics.rst:334
+#: ../../source/production/observability/metrics.rst:372
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/production/observability/metrics.rst:22
+#: ../../source/production/observability/metrics.rst:42
+#: ../../source/production/observability/metrics.rst:74
+#: ../../source/production/observability/metrics.rst:97
+#: ../../source/production/observability/metrics.rst:129
+#: ../../source/production/observability/metrics.rst:164
+#: ../../source/production/observability/metrics.rst:187
+#: ../../source/production/observability/metrics.rst:231
+#: ../../source/production/observability/metrics.rst:257
+#: ../../source/production/observability/metrics.rst:280
+#: ../../source/production/observability/metrics.rst:303
+#: ../../source/production/observability/metrics.rst:335
+#: ../../source/production/observability/metrics.rst:373
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/metrics.rst:23
+msgid "``lmcache:num_retrieve_requests``"
+msgstr "``lmcache:num_retrieve_requests``"
+
+#: ../../source/production/observability/metrics.rst:24
+#: ../../source/production/observability/metrics.rst:27
+#: ../../source/production/observability/metrics.rst:30
+#: ../../source/production/observability/metrics.rst:44
+#: ../../source/production/observability/metrics.rst:47
+#: ../../source/production/observability/metrics.rst:50
+#: ../../source/production/observability/metrics.rst:53
+#: ../../source/production/observability/metrics.rst:56
+#: ../../source/production/observability/metrics.rst:59
+#: ../../source/production/observability/metrics.rst:62
+#: ../../source/production/observability/metrics.rst:85
+#: ../../source/production/observability/metrics.rst:114
+#: ../../source/production/observability/metrics.rst:117
+#: ../../source/production/observability/metrics.rst:189
+#: ../../source/production/observability/metrics.rst:192
+#: ../../source/production/observability/metrics.rst:195
+#: ../../source/production/observability/metrics.rst:198
+#: ../../source/production/observability/metrics.rst:213
+#: ../../source/production/observability/metrics.rst:216
+#: ../../source/production/observability/metrics.rst:233
+#: ../../source/production/observability/metrics.rst:236
+#: ../../source/production/observability/metrics.rst:239
+#: ../../source/production/observability/metrics.rst:265
+#: ../../source/production/observability/metrics.rst:282
+#: ../../source/production/observability/metrics.rst:285
+msgid "Counter"
+msgstr "计数器"
+
+#: ../../source/production/observability/metrics.rst:25
+msgid "Total number of retrieve requests sent to LMCache."
+msgstr "发送到 LMCache 的检索请求总数。"
+
+#: ../../source/production/observability/metrics.rst:26
+msgid "``lmcache:num_store_requests``"
+msgstr "``lmcache:num_store_requests``"
+
+#: ../../source/production/observability/metrics.rst:28
+msgid "Total number of store requests sent to LMCache."
+msgstr "发送到 LMCache 的存储请求总数。"
+
+#: ../../source/production/observability/metrics.rst:29
+msgid "``lmcache:num_lookup_requests``"
+msgstr "``lmcache:num_lookup_requests``"
+
+#: ../../source/production/observability/metrics.rst:31
+msgid "Total number of lookup requests sent to LMCache."
+msgstr "发送到 LMCache 的查找请求总数。"
+
+#: ../../source/production/observability/metrics.rst:34
+#: ../../source/production/observability/metrics.rst:36
+msgid "Token Metrics"
+msgstr "令牌指标"
+
+#: ../../source/production/observability/metrics.rst:43
+msgid "``lmcache:num_requested_tokens``"
+msgstr "``lmcache:num_requested_tokens``"
+
+#: ../../source/production/observability/metrics.rst:45
+msgid "Total number of tokens requested for retrieval."
+msgstr "请求检索的总令牌数。"
+
+#: ../../source/production/observability/metrics.rst:46
+msgid "``lmcache:num_hit_tokens``"
+msgstr "``lmcache:num_hit_tokens``"
+
+#: ../../source/production/observability/metrics.rst:48
+msgid "Total number of tokens hit in LMCache during retrieval."
+msgstr "在检索过程中，LMCache 中命中的总令牌数。"
+
+#: ../../source/production/observability/metrics.rst:49
+msgid "``lmcache:num_stored_tokens``"
+msgstr "``lmcache:num_stored_tokens``"
+
+#: ../../source/production/observability/metrics.rst:51
+msgid "Total number of tokens stored in LMCache."
+msgstr "LMCache 中存储的令牌总数。"
+
+#: ../../source/production/observability/metrics.rst:52
+msgid "``lmcache:num_lookup_tokens``"
+msgstr "``lmcache:num_lookup_tokens``"
+
+#: ../../source/production/observability/metrics.rst:54
+msgid "Total number of tokens requested in lookup operations."
+msgstr "查找操作中请求的令牌总数。"
+
+#: ../../source/production/observability/metrics.rst:55
+msgid "``lmcache:num_lookup_hits``"
+msgstr "``lmcache:num_lookup_hits``"
+
+#: ../../source/production/observability/metrics.rst:57
+msgid "Total number of tokens hit in lookup operations."
+msgstr "查找操作中命中的总令牌数。"
+
+#: ../../source/production/observability/metrics.rst:58
+msgid "``lmcache:num_vllm_hit_tokens``"
+msgstr "``lmcache:num_vllm_hit_tokens``"
+
+#: ../../source/production/observability/metrics.rst:60
+msgid "Number of hit tokens in vLLM."
+msgstr "vLLM 中的命中令牌数量。"
+
+#: ../../source/production/observability/metrics.rst:61
+msgid "``lmcache:num_prompt_tokens``"
+msgstr "``lmcache:num_prompt_tokens``"
+
+#: ../../source/production/observability/metrics.rst:63
+msgid "Number of prompt tokens in LMCache."
+msgstr "LMCache 中的提示令牌数量。"
+
+#: ../../source/production/observability/metrics.rst:66
+#: ../../source/production/observability/metrics.rst:68
+msgid "Hit Rate Metrics"
+msgstr "命中率指标"
+
+#: ../../source/production/observability/metrics.rst:75
+msgid "``lmcache:retrieve_hit_rate``"
+msgstr "``lmcache:retrieve_hit_rate``"
+
+#: ../../source/production/observability/metrics.rst:76
+#: ../../source/production/observability/metrics.rst:79
+#: ../../source/production/observability/metrics.rst:166
+#: ../../source/production/observability/metrics.rst:169
+#: ../../source/production/observability/metrics.rst:172
+#: ../../source/production/observability/metrics.rst:210
+#: ../../source/production/observability/metrics.rst:219
+#: ../../source/production/observability/metrics.rst:242
+#: ../../source/production/observability/metrics.rst:245
+#: ../../source/production/observability/metrics.rst:259
+#: ../../source/production/observability/metrics.rst:262
+#: ../../source/production/observability/metrics.rst:268
+#: ../../source/production/observability/metrics.rst:305
+#: ../../source/production/observability/metrics.rst:308
+#: ../../source/production/observability/metrics.rst:311
+#: ../../source/production/observability/metrics.rst:314
+#: ../../source/production/observability/metrics.rst:317
+#: ../../source/production/observability/metrics.rst:320
+#: ../../source/production/observability/metrics.rst:323
+#: ../../source/production/observability/metrics.rst:337
+#: ../../source/production/observability/metrics.rst:340
+#: ../../source/production/observability/metrics.rst:343
+#: ../../source/production/observability/metrics.rst:346
+#: ../../source/production/observability/metrics.rst:349
+#: ../../source/production/observability/metrics.rst:352
+#: ../../source/production/observability/metrics.rst:355
+#: ../../source/production/observability/metrics.rst:358
+#: ../../source/production/observability/metrics.rst:361
+#: ../../source/production/observability/metrics.rst:375
+#: ../../source/production/observability/metrics.rst:378
+#: ../../source/production/observability/metrics.rst:381
+#: ../../source/production/observability/metrics.rst:384
+#: ../../source/production/observability/metrics.rst:387
+#: ../../source/production/observability/metrics.rst:390
+#: ../../source/production/observability/metrics.rst:393
+msgid "Gauge"
+msgstr "仪表"
+
+#: ../../source/production/observability/metrics.rst:77
+msgid "The hit rate for retrieve requests since last log."
+msgstr "自上次日志以来，检索请求的命中率。"
+
+#: ../../source/production/observability/metrics.rst:78
+msgid "``lmcache:lookup_hit_rate``"
+msgstr "``lmcache:lookup_hit_rate``"
+
+#: ../../source/production/observability/metrics.rst:80
+msgid "The hit rate for lookup requests since last log."
+msgstr "自上次日志以来查找请求的命中率。"
+
+#: ../../source/production/observability/metrics.rst:81
+msgid "``lmcache:request_cache_hit_rate``"
+msgstr "``lmcache:request_cache_hit_rate``"
+
+#: ../../source/production/observability/metrics.rst:82
+#: ../../source/production/observability/metrics.rst:99
+#: ../../source/production/observability/metrics.rst:102
+#: ../../source/production/observability/metrics.rst:105
+#: ../../source/production/observability/metrics.rst:108
+#: ../../source/production/observability/metrics.rst:111
+#: ../../source/production/observability/metrics.rst:131
+#: ../../source/production/observability/metrics.rst:134
+#: ../../source/production/observability/metrics.rst:137
+#: ../../source/production/observability/metrics.rst:140
+#: ../../source/production/observability/metrics.rst:143
+#: ../../source/production/observability/metrics.rst:146
+#: ../../source/production/observability/metrics.rst:149
+#: ../../source/production/observability/metrics.rst:152
+#: ../../source/production/observability/metrics.rst:175
+#: ../../source/production/observability/metrics.rst:201
+#: ../../source/production/observability/metrics.rst:204
+#: ../../source/production/observability/metrics.rst:207
+#: ../../source/production/observability/metrics.rst:288
+#: ../../source/production/observability/metrics.rst:291
+msgid "Histogram"
+msgstr "直方图"
+
+#: ../../source/production/observability/metrics.rst:83
+msgid "Distribution of hit rates per request."
+msgstr "每个请求的命中率分布。"
+
+#: ../../source/production/observability/metrics.rst:84
+msgid "``lmcache:lookup_0_hit_requests``"
+msgstr "``lmcache:lookup_0_hit_requests``"
+
+#: ../../source/production/observability/metrics.rst:86
+msgid "Total number of lookup requests with zero hits."
+msgstr "查找请求的总数，其中没有命中。"
+
+#: ../../source/production/observability/metrics.rst:89
+#: ../../source/production/observability/metrics.rst:91
+msgid "Performance & Latency Metrics"
+msgstr "性能与延迟指标"
+
+#: ../../source/production/observability/metrics.rst:98
+msgid "``lmcache:time_to_retrieve``"
+msgstr "``lmcache:time_to_retrieve``"
+
+#: ../../source/production/observability/metrics.rst:100
+msgid "Time taken to retrieve from the cache (seconds)."
+msgstr "从缓存中检索所花费的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:101
+msgid "``lmcache:time_to_store``"
+msgstr "``lmcache:time_to_store``"
+
+#: ../../source/production/observability/metrics.rst:103
+msgid "Time taken to store to the cache (seconds)."
+msgstr "存储到缓存所需的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:104
+msgid "``lmcache:time_to_lookup``"
+msgstr "``lmcache:time_to_lookup``"
+
+#: ../../source/production/observability/metrics.rst:106
+msgid "Time taken to perform a lookup in the cache (seconds)."
+msgstr "在缓存中执行查找所花费的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:107
+msgid "``lmcache:retrieve_speed``"
+msgstr "``lmcache:retrieve_speed``"
+
+#: ../../source/production/observability/metrics.rst:109
+msgid "Retrieval speed (tokens per second)."
+msgstr "检索速度（每秒令牌数）。"
+
+#: ../../source/production/observability/metrics.rst:110
+msgid "``lmcache:store_speed``"
+msgstr "``lmcache:store_speed``"
+
+#: ../../source/production/observability/metrics.rst:112
+msgid "Storage speed (tokens per second)."
+msgstr "存储速度（每秒令牌数）。"
+
+#: ../../source/production/observability/metrics.rst:113
+msgid "``lmcache:num_slow_retrieval_by_time``"
+msgstr "``lmcache:num_slow_retrieval_by_time``"
+
+#: ../../source/production/observability/metrics.rst:115
+msgid "Total number of slow retrievals exceeding the time threshold."
+msgstr "超过时间阈值的慢检索总数。"
+
+#: ../../source/production/observability/metrics.rst:116
+msgid "``lmcache:num_slow_retrieval_by_speed``"
+msgstr "``lmcache:num_slow_retrieval_by_speed``"
+
+#: ../../source/production/observability/metrics.rst:118
+msgid "Total number of slow retrievals below the speed threshold."
+msgstr "低于速度阈值的慢检索总数。"
+
+#: ../../source/production/observability/metrics.rst:121
+msgid "Detailed Profiling Metrics"
+msgstr "详细剖析指标"
+
+#: ../../source/production/observability/metrics.rst:123
+msgid "Profiling Metrics"
+msgstr "剖析指标"
+
+#: ../../source/production/observability/metrics.rst:130
+msgid "``lmcache:retrieve_process_tokens_time``"
+msgstr "``lmcache:retrieve_process_tokens_time``"
+
+#: ../../source/production/observability/metrics.rst:132
+msgid "Time to process tokens in retrieve (seconds)."
+msgstr "处理检索中令牌的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:133
+msgid "``lmcache:retrieve_broadcast_time``"
+msgstr "``lmcache:retrieve_broadcast_time``"
+
+#: ../../source/production/observability/metrics.rst:135
+msgid "Time to broadcast memory objects in retrieve (seconds)."
+msgstr "在检索中广播内存对象的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:136
+msgid "``lmcache:retrieve_to_gpu_time``"
+msgstr "``lmcache:retrieve_to_gpu_time``"
+
+#: ../../source/production/observability/metrics.rst:138
+msgid "Time to move data to GPU in retrieve (seconds)."
+msgstr "将数据移动到 GPU 的检索时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:139
+msgid "``lmcache:store_process_tokens_time``"
+msgstr "``lmcache:store_process_tokens_time``"
+
+#: ../../source/production/observability/metrics.rst:141
+msgid "Time to process tokens in store (seconds)."
+msgstr "存储中处理令牌的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:142
+msgid "``lmcache:store_from_gpu_time``"
+msgstr "``lmcache:store_from_gpu_time``"
+
+#: ../../source/production/observability/metrics.rst:144
+msgid "Time to move data from GPU in store (seconds)."
+msgstr "从 GPU 移动数据到存储的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:145
+msgid "``lmcache:store_put_time``"
+msgstr "``lmcache:store_put_time``"
+
+#: ../../source/production/observability/metrics.rst:147
+msgid "Time to put data to storage in store (seconds)."
+msgstr "将数据存储到存储中的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:148
+msgid "``lmcache:remote_backend_batched_get_blocking_time``"
+msgstr "``lmcache:remote_backend_batched_get_blocking_time``"
+
+#: ../../source/production/observability/metrics.rst:150
+msgid "Time spent waiting for data from remote backend (seconds)."
+msgstr "等待从远程后端获取数据的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:151
+msgid "``lmcache:instrumented_connector_batched_get_time``"
+msgstr "``lmcache:instrumented_connector_batched_get_time``"
+
+#: ../../source/production/observability/metrics.rst:153
+msgid "Time spent in the connector layer (seconds)."
+msgstr "连接器层花费的时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:156
+msgid "Cache Usage & Lifecycle Metrics"
+msgstr "缓存使用与生命周期指标"
+
+#: ../../source/production/observability/metrics.rst:158
+msgid "Cache Usage Metrics"
+msgstr "缓存使用指标"
+
+#: ../../source/production/observability/metrics.rst:165
+msgid "``lmcache:local_cache_usage``"
+msgstr "``lmcache:local_cache_usage``"
+
+#: ../../source/production/observability/metrics.rst:167
+msgid "Local cache usage in bytes."
+msgstr "本地缓存使用量（以字节为单位）。"
+
+#: ../../source/production/observability/metrics.rst:168
+msgid "``lmcache:remote_cache_usage``"
+msgstr "``lmcache:remote_cache_usage``"
+
+#: ../../source/production/observability/metrics.rst:170
+msgid "Remote cache usage in bytes."
+msgstr "远程缓存使用量（以字节为单位）。"
+
+#: ../../source/production/observability/metrics.rst:171
+msgid "``lmcache:local_storage_usage``"
+msgstr "``lmcache:local_storage_usage``"
+
+#: ../../source/production/observability/metrics.rst:173
+msgid "Local storage usage in bytes."
+msgstr "本地存储使用量（以字节为单位）。"
+
+#: ../../source/production/observability/metrics.rst:174
+msgid "``lmcache:request_cache_lifespan``"
+msgstr "``lmcache:request_cache_lifespan``"
+
+#: ../../source/production/observability/metrics.rst:176
+msgid "Distribution of request cache lifespan in minutes."
+msgstr "请求缓存生命周期的分布（以分钟为单位）。"
+
+#: ../../source/production/observability/metrics.rst:179
+msgid "Remote Backend & Network Metrics"
+msgstr "远程后端与网络指标"
+
+#: ../../source/production/observability/metrics.rst:181
+msgid "Remote Backend Metrics"
+msgstr "远程后端指标"
+
+#: ../../source/production/observability/metrics.rst:188
+msgid "``lmcache:num_remote_read_requests``"
+msgstr "``lmcache:num_remote_read_requests``"
+
+#: ../../source/production/observability/metrics.rst:190
+msgid "Total number of read requests to remote backends."
+msgstr "对远程后端的读取请求总数。"
+
+#: ../../source/production/observability/metrics.rst:191
+msgid "``lmcache:num_remote_read_bytes``"
+msgstr "``lmcache:num_remote_read_bytes``"
+
+#: ../../source/production/observability/metrics.rst:193
+msgid "Total number of bytes read from remote backends."
+msgstr "从远程后端读取的字节总数。"
+
+#: ../../source/production/observability/metrics.rst:194
+msgid "``lmcache:num_remote_write_requests``"
+msgstr "``lmcache:num_remote_write_requests``"
+
+#: ../../source/production/observability/metrics.rst:196
+msgid "Total number of write requests to remote backends."
+msgstr "对远程后端的写请求总数。"
+
+#: ../../source/production/observability/metrics.rst:197
+msgid "``lmcache:num_remote_write_bytes``"
+msgstr "``lmcache:num_remote_write_bytes``"
+
+#: ../../source/production/observability/metrics.rst:199
+msgid "Total number of bytes written to remote backends."
+msgstr "写入远程后端的字节总数。"
+
+#: ../../source/production/observability/metrics.rst:200
+msgid "``lmcache:remote_time_to_get``"
+msgstr "``lmcache:remote_time_to_get``"
+
+#: ../../source/production/observability/metrics.rst:202
+msgid "Time taken to get data from remote backends (ms)."
+msgstr "从远程后端获取数据所花费的时间（毫秒）。"
+
+#: ../../source/production/observability/metrics.rst:203
+msgid "``lmcache:remote_time_to_put``"
+msgstr "``lmcache:remote_time_to_put``"
+
+#: ../../source/production/observability/metrics.rst:205
+msgid "Time taken to put data to remote backends (ms)."
+msgstr "将数据放入远程后端所花费的时间（毫秒）。"
+
+#: ../../source/production/observability/metrics.rst:206
+msgid "``lmcache:remote_time_to_get_sync``"
+msgstr "``lmcache:remote_time_to_get_sync``"
+
+#: ../../source/production/observability/metrics.rst:208
+msgid "Time taken to get data from remote backends synchronously (ms)."
+msgstr "从远程后端同步获取数据所花费的时间（毫秒）。"
+
+#: ../../source/production/observability/metrics.rst:209
+msgid "``lmcache:remote_ping_latency``"
+msgstr "``lmcache:remote_ping_latency``"
+
+#: ../../source/production/observability/metrics.rst:211
+msgid "Latest ping latency to remote backends (ms)."
+msgstr "最新的远程后端 ping 延迟（毫秒）。"
+
+#: ../../source/production/observability/metrics.rst:212
+msgid "``lmcache:remote_ping_errors``"
+msgstr "``lmcache:remote_ping_errors``"
+
+#: ../../source/production/observability/metrics.rst:214
+msgid "Total number of ping errors to remote backends."
+msgstr "远程后端的总 ping 错误数量。"
+
+#: ../../source/production/observability/metrics.rst:215
+msgid "``lmcache:remote_ping_successes``"
+msgstr "``lmcache:remote_ping_successes``"
+
+#: ../../source/production/observability/metrics.rst:217
+msgid "Total number of successful pings to remote backends."
+msgstr "成功 ping 远程后端的总次数。"
+
+#: ../../source/production/observability/metrics.rst:218
+msgid "``lmcache:remote_ping_error_code``"
+msgstr "``lmcache:remote_ping_error_code``"
+
+#: ../../source/production/observability/metrics.rst:220
+msgid "Latest ping error code to remote backends."
+msgstr "远程后端的最新 ping 错误代码。"
+
+#: ../../source/production/observability/metrics.rst:223
+#: ../../source/production/observability/metrics.rst:225
+msgid "Local CPU Backend Metrics"
+msgstr "本地 CPU 后端指标"
+
+#: ../../source/production/observability/metrics.rst:232
+msgid "``lmcache:local_cpu_evict_count``"
+msgstr "``lmcache:local_cpu_evict_count``"
+
+#: ../../source/production/observability/metrics.rst:234
+msgid "Total number of evictions in local CPU backend."
+msgstr "本地 CPU 后端的总逐出次数。"
+
+#: ../../source/production/observability/metrics.rst:235
+msgid "``lmcache:local_cpu_evict_keys_count``"
+msgstr "``lmcache:local_cpu_evict_keys_count``"
+
+#: ../../source/production/observability/metrics.rst:237
+msgid "Total number of evicted keys in local CPU backend."
+msgstr "本地 CPU 后端中被逐出的键的总数。"
+
+#: ../../source/production/observability/metrics.rst:238
+msgid "``lmcache:local_cpu_evict_failed_count``"
+msgstr "``lmcache:local_cpu_evict_failed_count``"
+
+#: ../../source/production/observability/metrics.rst:240
+msgid "Total number of failed evictions in local CPU backend."
+msgstr "本地 CPU 后端中失败的逐出总数。"
+
+#: ../../source/production/observability/metrics.rst:241
+msgid "``lmcache:local_cpu_hot_cache_count``"
+msgstr "``lmcache:local_cpu_hot_cache_count``"
+
+#: ../../source/production/observability/metrics.rst:243
+msgid "Current number of items in the hot cache."
+msgstr "热缓存中当前项目的数量。"
+
+#: ../../source/production/observability/metrics.rst:244
+msgid "``lmcache:local_cpu_keys_in_request_count``"
+msgstr "``lmcache:local_cpu_keys_in_request_count``"
+
+#: ../../source/production/observability/metrics.rst:246
+msgid "Current number of keys being processed in requests."
+msgstr "当前正在处理的请求中的键的数量。"
+
+#: ../../source/production/observability/metrics.rst:249
+#: ../../source/production/observability/metrics.rst:251
+msgid "Memory Management Metrics"
+msgstr "内存管理指标"
+
+#: ../../source/production/observability/metrics.rst:258
+msgid "``lmcache:active_memory_objs_count``"
+msgstr "``lmcache:active_memory_objs_count``"
+
+#: ../../source/production/observability/metrics.rst:260
+msgid "The number of currently active memory objects."
+msgstr "当前活动内存对象的数量。"
+
+#: ../../source/production/observability/metrics.rst:261
+msgid "``lmcache:pinned_memory_objs_count``"
+msgstr "``lmcache:pinned_memory_objs_count``"
+
+#: ../../source/production/observability/metrics.rst:263
+msgid "The number of currently pinned memory objects."
+msgstr "当前固定内存对象的数量。"
+
+#: ../../source/production/observability/metrics.rst:264
+msgid "``lmcache:forced_unpin_count``"
+msgstr "``lmcache:forced_unpin_count``"
+
+#: ../../source/production/observability/metrics.rst:266
+msgid "Total number of forced unpins due to timeout."
+msgstr "由于超时而强制逐出的总数。"
+
+#: ../../source/production/observability/metrics.rst:267
+msgid "``lmcache:pin_monitor_pinned_objects_count``"
+msgstr "``lmcache:pin_monitor_pinned_objects_count``"
+
+#: ../../source/production/observability/metrics.rst:269
+msgid "The number of pinned objects tracked by the PinMonitor."
+msgstr "PinMonitor 追踪的固定对象数量。"
+
+#: ../../source/production/observability/metrics.rst:272
+#: ../../source/production/observability/metrics.rst:274
+msgid "P2P Transfer Metrics"
+msgstr "P2P 转移指标"
+
+#: ../../source/production/observability/metrics.rst:281
+msgid "``lmcache:num_p2p_requests``"
+msgstr "``lmcache:num_p2p_requests``"
+
+#: ../../source/production/observability/metrics.rst:283
+msgid "Total number of P2P transfer requests."
+msgstr "P2P 转移请求的总数。"
+
+#: ../../source/production/observability/metrics.rst:284
+msgid "``lmcache:num_p2p_transferred_tokens``"
+msgstr "``lmcache:num_p2p_transferred_tokens``"
+
+#: ../../source/production/observability/metrics.rst:286
+msgid "Total number of tokens transferred via P2P."
+msgstr "通过 P2P 传输的令牌总数。"
+
+#: ../../source/production/observability/metrics.rst:287
+msgid "``lmcache:p2p_time_to_transfer``"
+msgstr "``lmcache:p2p_time_to_transfer``"
+
+#: ../../source/production/observability/metrics.rst:289
+msgid "Time taken for P2P transfers (seconds)."
+msgstr "P2P 传输所需时间（秒）。"
+
+#: ../../source/production/observability/metrics.rst:290
+msgid "``lmcache:p2p_transfer_speed``"
+msgstr "``lmcache:p2p_transfer_speed``"
+
+#: ../../source/production/observability/metrics.rst:292
+msgid "P2P transfer speed (tokens per second)."
+msgstr "P2P 传输速度（每秒令牌数）。"
+
+#: ../../source/production/observability/metrics.rst:295
+msgid "Health & Internal System Metrics"
+msgstr "健康与内部系统指标"
+
+#: ../../source/production/observability/metrics.rst:297
+msgid "Health & Internal Metrics"
+msgstr "健康与内部指标"
+
+#: ../../source/production/observability/metrics.rst:304
+msgid "``lmcache:lmcache_is_healthy``"
+msgstr "``lmcache:lmcache_is_healthy``"
+
+#: ../../source/production/observability/metrics.rst:306
+msgid "Overall health status of LMCache (1 = healthy, 0 = unhealthy)."
+msgstr "LMCache 的整体健康状态（1 = 健康，0 = 不健康）。"
+
+#: ../../source/production/observability/metrics.rst:307
+msgid "``lmcache:interval_get_blocking_failed_count``"
+msgstr "``lmcache:interval_get_blocking_failed_count``"
+
+#: ../../source/production/observability/metrics.rst:309
+msgid "Number of failed blocking get operations in the current interval."
+msgstr "当前时间间隔内失败的阻塞获取操作数量。"
+
+#: ../../source/production/observability/metrics.rst:310
+msgid "``lmcache:kv_msg_queue_size``"
+msgstr "``lmcache:kv_msg_queue_size``"
+
+#: ../../source/production/observability/metrics.rst:312
+msgid "Size of the KV message queue in the BatchedMessageSender."
+msgstr "批量消息发送器中 KV 消息队列的大小。"
+
+#: ../../source/production/observability/metrics.rst:313
+msgid "``lmcache:remote_put_task_num``"
+msgstr "``lmcache:remote_put_task_num``"
+
+#: ../../source/production/observability/metrics.rst:315
+msgid "Number of pending remote put tasks."
+msgstr "待处理的远程放置任务数量。"
+
+#: ../../source/production/observability/metrics.rst:316
+msgid "``lmcache:storage_events_ongoing_count``"
+msgstr "``lmcache:storage_events_ongoing_count``"
+
+#: ../../source/production/observability/metrics.rst:318
+msgid "Number of storage events currently in progress."
+msgstr "当前进行中的存储事件数量。"
+
+#: ../../source/production/observability/metrics.rst:319
+msgid "``lmcache:storage_events_done_count``"
+msgstr "``lmcache:storage_events_done_count``"
+
+#: ../../source/production/observability/metrics.rst:321
+msgid "Number of storage events completed successfully."
+msgstr "成功完成的存储事件数量。"
+
+#: ../../source/production/observability/metrics.rst:322
+msgid "``lmcache:storage_events_not_found_count``"
+msgstr "``lmcache:storage_events_not_found_count``"
+
+#: ../../source/production/observability/metrics.rst:324
+msgid "Number of storage events where the requested data was not found."
+msgstr "未找到请求数据的存储事件数量。"
+
+#: ../../source/production/observability/metrics.rst:327
+#: ../../source/production/observability/metrics.rst:329
+msgid "Chunk Statistics Metrics"
+msgstr "块统计指标"
+
+#: ../../source/production/observability/metrics.rst:336
+msgid "``lmcache:chunk_statistics_enabled``"
+msgstr "``lmcache:chunk_statistics_enabled``"
+
+#: ../../source/production/observability/metrics.rst:338
+msgid ""
+"Whether chunk statistics collection is enabled (1 = enabled, 0 = "
+"disabled)."
+msgstr "是否启用块统计收集（1 = 启用，0 = 禁用）。"
+
+#: ../../source/production/observability/metrics.rst:339
+msgid "``lmcache:chunk_statistics_total_requests``"
+msgstr "``lmcache:chunk_statistics_total_requests``"
+
+#: ../../source/production/observability/metrics.rst:341
+msgid "Total number of requests processed by chunk statistics."
+msgstr "按块统计处理的请求总数。"
+
+#: ../../source/production/observability/metrics.rst:342
+msgid "``lmcache:chunk_statistics_total_chunks``"
+msgstr "``lmcache:chunk_statistics_total_chunks``"
+
+#: ../../source/production/observability/metrics.rst:344
+msgid "Total number of chunks processed."
+msgstr "处理的块总数。"
+
+#: ../../source/production/observability/metrics.rst:345
+msgid "``lmcache:chunk_statistics_unique_chunks``"
+msgstr "``lmcache:chunk_statistics_unique_chunks``"
+
+#: ../../source/production/observability/metrics.rst:347
+msgid "Estimated number of unique chunks encountered."
+msgstr "估计遇到的唯一块的数量。"
+
+#: ../../source/production/observability/metrics.rst:348
+msgid "``lmcache:chunk_statistics_reuse_rate``"
+msgstr "``lmcache:chunk_statistics_reuse_rate``"
+
+#: ../../source/production/observability/metrics.rst:350
+msgid "Chunk reuse rate (0.0 to 1.0)."
+msgstr "块重用率（0.0 到 1.0）。"
+
+#: ../../source/production/observability/metrics.rst:351
+msgid "``lmcache:chunk_statistics_bloom_filter_size_mb``"
+msgstr "``lmcache:chunk_statistics_bloom_filter_size_mb``"
+
+#: ../../source/production/observability/metrics.rst:353
+msgid "Memory usage of the Bloom filter in megabytes."
+msgstr "布隆过滤器的内存使用量（以兆字节为单位）。"
+
+#: ../../source/production/observability/metrics.rst:354
+msgid "``lmcache:chunk_statistics_bloom_filter_fill_rate``"
+msgstr "``lmcache:chunk_statistics_bloom_filter_fill_rate``"
+
+#: ../../source/production/observability/metrics.rst:356
+msgid "Fill rate of the Bloom filter (0.0 to 1.0)."
+msgstr "布隆过滤器的填充率（0.0 到 1.0）。"
+
+#: ../../source/production/observability/metrics.rst:357
+msgid "``lmcache:chunk_statistics_file_count``"
+msgstr "``lmcache:chunk_statistics_file_count``"
+
+#: ../../source/production/observability/metrics.rst:359
+msgid "Number of files created when using the ``file_hash`` strategy."
+msgstr "使用 ``file_hash`` 策略时创建的文件数量。"
+
+#: ../../source/production/observability/metrics.rst:360
+msgid "``lmcache:chunk_statistics_current_file_size``"
+msgstr "``lmcache:chunk_statistics_current_file_size``"
+
+#: ../../source/production/observability/metrics.rst:362
+msgid "Current size of the active statistics file in bytes."
+msgstr "活动统计文件的当前大小（以字节为单位）。"
+
+#: ../../source/production/observability/metrics.rst:365
+#: ../../source/production/observability/metrics.rst:367
+msgid "Connector Metrics"
+msgstr "连接器指标"
+
+#: ../../source/production/observability/metrics.rst:374
+msgid "``lmcache:scheduler_unfinished_requests_count``"
+msgstr "``lmcache:scheduler_unfinished_requests_count``"
+
+#: ../../source/production/observability/metrics.rst:376
+msgid "Current count of unfinished requests in the scheduler."
+msgstr "调度器中未完成请求的当前计数。"
+
+#: ../../source/production/observability/metrics.rst:377
+msgid "``lmcache:connector_load_specs_count``"
+msgstr "``lmcache:connector_load_specs_count``"
+
+#: ../../source/production/observability/metrics.rst:379
+msgid "Number of load specifications currently in the connector."
+msgstr "连接器中当前的加载规范数量。"
+
+#: ../../source/production/observability/metrics.rst:380
+msgid "``lmcache:connector_request_trackers_count``"
+msgstr "``lmcache:connector_request_trackers_count``"
+
+#: ../../source/production/observability/metrics.rst:382
+msgid "Number of active request trackers in the connector."
+msgstr "连接器中活动请求跟踪器的数量。"
+
+#: ../../source/production/observability/metrics.rst:383
+msgid "``lmcache:connector_kv_caches_count``"
+msgstr "``lmcache:connector_kv_caches_count``"
+
+#: ../../source/production/observability/metrics.rst:385
+msgid "Number of KV caches currently managed by the connector."
+msgstr "连接器当前管理的 KV Cache 数量。"
+
+#: ../../source/production/observability/metrics.rst:386
+msgid "``lmcache:connector_layerwise_retrievers_count``"
+msgstr "``lmcache:connector_layerwise_retrievers_count``"
+
+#: ../../source/production/observability/metrics.rst:388
+msgid "Number of layer-wise retrievers active in the connector."
+msgstr "连接器中活动的逐层检索器数量。"
+
+#: ../../source/production/observability/metrics.rst:389
+msgid "``lmcache:connector_invalid_block_ids_count``"
+msgstr "``lmcache:connector_invalid_block_ids_count``"
+
+#: ../../source/production/observability/metrics.rst:391
+msgid "Number of invalid block IDs encountered by the connector."
+msgstr "连接器遇到的无效块 ID 的数量。"
+
+#: ../../source/production/observability/metrics.rst:392
+msgid "``lmcache:connector_requests_priority_count``"
+msgstr "``lmcache:connector_requests_priority_count``"
+
+#: ../../source/production/observability/metrics.rst:394
+msgid "Number of requests prioritized by the connector."
+msgstr "连接器优先处理的请求数量。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/periodic_thread_api.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/periodic_thread_api.po
new file mode 100644
index 0000000..efc81e5
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/periodic_thread_api.po
@@ -0,0 +1,241 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/periodic_thread_api.rst:4
+msgid "Periodic Thread Monitoring API"
+msgstr "周期性线程监控 API"
+
+#: ../../source/production/observability/periodic_thread_api.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr ""
+
+#: ../../source/production/observability/periodic_thread_api.rst:11
+msgid ""
+"This document describes the Periodic Thread Monitoring API feature "
+"introduced in LMCache."
+msgstr "本文描述了在 LMCache 中引入的周期性线程监控 API 功能。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:15
+msgid "Overview"
+msgstr "概述"
+
+#: ../../source/production/observability/periodic_thread_api.rst:17
+msgid ""
+"The Periodic Thread Monitoring API provides HTTP endpoints to monitor and"
+" inspect the status of all periodic background threads running in the "
+"LMCache system. This is useful for debugging, health checking, and "
+"operational monitoring."
+msgstr ""
+"周期性线程监控 API 提供 HTTP 端点，以监控和检查在 LMCache "
+"系统中运行的所有周期性后台线程的状态。这对于调试、健康检查和操作监控非常有用。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:23
+msgid "API Endpoints"
+msgstr "API 端点"
+
+#: ../../source/production/observability/periodic_thread_api.rst:25
+msgid "Three API endpoints are available under the internal API server:"
+msgstr "在内部 API 服务器下提供三个 API 端点："
+
+#: ../../source/production/observability/periodic_thread_api.rst:28
+msgid "GET /periodic-threads"
+msgstr "GET /periodic-threads"
+
+#: ../../source/production/observability/periodic_thread_api.rst:30
+msgid "Returns information about all registered periodic threads."
+msgstr "返回所有注册的周期线程的信息。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:32
+msgid "**Query Parameters:**"
+msgstr "**查询参数：**"
+
+#: ../../source/production/observability/periodic_thread_api.rst:38
+msgid "Parameter"
+msgstr "参数"
+
+#: ../../source/production/observability/periodic_thread_api.rst:39
+msgid "Default"
+msgstr "默认"
+
+#: ../../source/production/observability/periodic_thread_api.rst:40
+#: ../../source/production/observability/periodic_thread_api.rst:126
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/periodic_thread_api.rst:41
+msgid "``level``"
+msgstr "``level``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:42
+msgid "(none)"
+msgstr "（无）"
+
+#: ../../source/production/observability/periodic_thread_api.rst:43
+msgid "Filter by thread level (``critical``, ``high``, ``medium``, ``low``)"
+msgstr "按线程级别过滤（``critical``, ``high``, ``medium``, ``low``）"
+
+#: ../../source/production/observability/periodic_thread_api.rst:44
+msgid "``running_only``"
+msgstr "``running_only``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:45
+#: ../../source/production/observability/periodic_thread_api.rst:48
+msgid "``false``"
+msgstr "``false``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:46
+msgid "Only show running threads"
+msgstr "仅显示正在运行的线程"
+
+#: ../../source/production/observability/periodic_thread_api.rst:47
+msgid "``active_only``"
+msgstr "``active_only``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:49
+msgid "Only show active threads"
+msgstr "仅显示活动线程"
+
+#: ../../source/production/observability/periodic_thread_api.rst:51
+#: ../../source/production/observability/periodic_thread_api.rst:84
+#: ../../source/production/observability/periodic_thread_api.rst:106
+msgid "**Response Example:**"
+msgstr "**响应示例：**"
+
+#: ../../source/production/observability/periodic_thread_api.rst:80
+#, python-brace-format
+msgid "GET /periodic-threads/{thread_name}"
+msgstr "GET /periodic-threads/{thread_name}"
+
+#: ../../source/production/observability/periodic_thread_api.rst:82
+msgid "Returns detailed information about a specific periodic thread."
+msgstr "返回有关特定周期线程的详细信息。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:101
+msgid "GET /periodic-threads-health"
+msgstr "GET /periodic-threads-health"
+
+#: ../../source/production/observability/periodic_thread_api.rst:103
+msgid ""
+"Quick health check for periodic threads. Returns whether all critical and"
+" high-level threads are active."
+msgstr "对周期性线程的快速健康检查。返回所有关键和高级线程是否处于活动状态。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:117
+msgid "Thread Levels"
+msgstr "线程级别"
+
+#: ../../source/production/observability/periodic_thread_api.rst:119
+msgid "Periodic threads are categorized by importance level:"
+msgstr "周期性线程按重要性级别分类："
+
+#: ../../source/production/observability/periodic_thread_api.rst:125
+msgid "Level"
+msgstr "级别"
+
+#: ../../source/production/observability/periodic_thread_api.rst:127
+msgid "``critical``"
+msgstr "``critical``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:128
+msgid "Essential for system operation"
+msgstr "系统运行所必需"
+
+#: ../../source/production/observability/periodic_thread_api.rst:129
+msgid "``high``"
+msgstr "``high``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:130
+msgid "Important for performance"
+msgstr "对性能很重要"
+
+#: ../../source/production/observability/periodic_thread_api.rst:131
+msgid "``medium``"
+msgstr "``medium``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:132
+msgid "Standard background tasks"
+msgstr "标准后台任务"
+
+#: ../../source/production/observability/periodic_thread_api.rst:133
+msgid "``low``"
+msgstr "``low``"
+
+#: ../../source/production/observability/periodic_thread_api.rst:134
+msgid "Optional/auxiliary tasks"
+msgstr "可选/辅助任务"
+
+#: ../../source/production/observability/periodic_thread_api.rst:136
+msgid ""
+"The health check endpoint specifically monitors ``critical`` and ``high``"
+" level threads to determine system health."
+msgstr "健康检查端点专门监控 ``critical`` 和 ``high`` 级别的线程以确定系统健康状况。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:140
+msgid "IrrecoverableException Handling"
+msgstr "不可恢复异常处理"
+
+#: ../../source/production/observability/periodic_thread_api.rst:142
+msgid ""
+"Periodic threads now properly handle ``IrrecoverableException``. When "
+"such an exception is raised during thread execution:"
+msgstr "周期性线程现在正确处理 ``IrrecoverableException``。当在线程执行期间引发此类异常时："
+
+#: ../../source/production/observability/periodic_thread_api.rst:145
+msgid "The exception is logged with full traceback"
+msgstr "该异常的完整回溯将被记录。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:146
+msgid "The thread run is marked as failed"
+msgstr "线程运行被标记为失败"
+
+#: ../../source/production/observability/periodic_thread_api.rst:147
+msgid "The thread **stops its execution loop** instead of continuing"
+msgstr "线程 **停止其执行循环** 而不是继续执行。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:149
+msgid ""
+"This prevents threads from endlessly retrying operations that cannot "
+"succeed."
+msgstr "这可以防止线程无休止地重试无法成功的操作。"
+
+#: ../../source/production/observability/periodic_thread_api.rst:152
+msgid "Usage Examples"
+msgstr "使用示例"
+
+#: ../../source/production/observability/periodic_thread_api.rst:155
+msgid "Check Overall Thread Health"
+msgstr "检查整体线程健康状况"
+
+#: ../../source/production/observability/periodic_thread_api.rst:162
+msgid "List All Running Threads"
+msgstr "列出所有正在运行的线程"
+
+#: ../../source/production/observability/periodic_thread_api.rst:169
+msgid "Get Critical Threads Only"
+msgstr "仅获取关键线程"
+
+#: ../../source/production/observability/periodic_thread_api.rst:176
+msgid "Check Specific Thread Status"
+msgstr "检查特定线程状态"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/vllm_endpoint.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/vllm_endpoint.po
new file mode 100644
index 0000000..02eadd2
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/observability/vllm_endpoint.po
@@ -0,0 +1,469 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/observability/vllm_endpoint.rst:4
+msgid "Metrics by vLLM API"
+msgstr "通过 vLLM API 的指标"
+
+#: ../../source/production/observability/vllm_endpoint.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr ""
+
+#: ../../source/production/observability/vllm_endpoint.rst:11
+msgid ""
+"LMCache provides detailed metrics via a Prometheus endpoint, allowing for"
+" in-depth monitoring of cache performance and behavior. This section "
+"outlines how to enable and configure observability from embedded vLLM "
+"``/metrics`` API endpoint."
+msgstr ""
+"LMCache 通过 Prometheus 端点提供详细的指标，允许对缓存性能和行为进行深入监控。本节概述了如何启用和配置来自嵌入式 vLLM "
+"``/metrics`` API 端点的可观察性。"
+
+#: ../../source/production/observability/vllm_endpoint.rst:16
+msgid "Quick Start Guide"
+msgstr "快速入门指南"
+
+#: ../../source/production/observability/vllm_endpoint.rst:19
+msgid "1) On vLLM/LMCache side"
+msgstr "1) 在 vLLM/LMCache 端"
+
+#: ../../source/production/observability/vllm_endpoint.rst:21
+msgid ""
+"In v1, vLLM and LMCache run in separate processes, so you have to use "
+"multi‑process Prometheus."
+msgstr "在 v1 中，vLLM 和 LMCache 运行在不同的进程中，因此您必须使用多进程 Prometheus。"
+
+#: ../../source/production/observability/vllm_endpoint.rst:23
+msgid ""
+"The ``PROMETHEUS_MULTIPROC_DIR`` environment variable must be the same in"
+" both processes, as a IPC directory."
+msgstr "``PROMETHEUS_MULTIPROC_DIR`` 环境变量在两个进程中必须相同，作为 IPC 目录。"
+
+#: ../../source/production/observability/vllm_endpoint.rst:31
+msgid ""
+"Once the HTTP server is running, you can access the LMCache metrics at "
+"the ``/metrics`` endpoint."
+msgstr "一旦 HTTP 服务器运行，您可以在 ``/metrics`` 端点访问 LMCache 指标。"
+
+#: ../../source/production/observability/vllm_endpoint.rst:40
+msgid ""
+"And you will also find some ``.db`` files in the "
+"``$PROMETHEUS_MULTIPROC_DIR`` directory."
+msgstr "您还会在 ``$PROMETHEUS_MULTIPROC_DIR`` 目录中找到一些 ``.db`` 文件。"
+
+#: ../../source/production/observability/vllm_endpoint.rst:44
+msgid "2) Prometheus Configuration"
+msgstr "2) Prometheus 配置"
+
+#: ../../source/production/observability/vllm_endpoint.rst:46
+msgid ""
+"To scrape the LMCache metrics with a Prometheus server, add the following"
+" job to your ``prometheus.yml`` configuration, or equivalent "
+"configuration to scrape the metrics endpoint:"
+msgstr ""
+"要使用 Prometheus 服务器抓取 LMCache 指标，请将以下作业添加到您的 ``prometheus.yml`` "
+"配置中，或等效配置以抓取指标端点："
+
+#: ../../source/production/observability/vllm_endpoint.rst:58
+msgid "Available Metrics"
+msgstr "可用指标"
+
+#: ../../source/production/observability/vllm_endpoint.rst:60
+msgid ""
+"LMCache exposes a variety of metrics to monitor its performance. The "
+"following table lists all available metrics organized by category:"
+msgstr "LMCache 提供多种指标以监控其性能。下表列出了按类别组织的所有可用指标："
+
+#: ../../source/production/observability/vllm_endpoint.rst:62
+msgid "LMCache Metrics"
+msgstr "LMCache 指标"
+
+#: ../../source/production/observability/vllm_endpoint.rst:66
+msgid "Metric Name"
+msgstr "指标名称"
+
+#: ../../source/production/observability/vllm_endpoint.rst:67
+msgid "Type"
+msgstr "类型"
+
+#: ../../source/production/observability/vllm_endpoint.rst:68
+msgid "Description"
+msgstr "描述"
+
+#: ../../source/production/observability/vllm_endpoint.rst:69
+msgid "**Core Request Metrics**"
+msgstr "**核心请求指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:72
+msgid "``lmcache:num_retrieve_requests``"
+msgstr "``lmcache:num_retrieve_requests``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:73
+#: ../../source/production/observability/vllm_endpoint.rst:76
+#: ../../source/production/observability/vllm_endpoint.rst:79
+#: ../../source/production/observability/vllm_endpoint.rst:82
+#: ../../source/production/observability/vllm_endpoint.rst:85
+#: ../../source/production/observability/vllm_endpoint.rst:88
+#: ../../source/production/observability/vllm_endpoint.rst:91
+#: ../../source/production/observability/vllm_endpoint.rst:94
+#: ../../source/production/observability/vllm_endpoint.rst:136
+#: ../../source/production/observability/vllm_endpoint.rst:139
+#: ../../source/production/observability/vllm_endpoint.rst:142
+#: ../../source/production/observability/vllm_endpoint.rst:145
+#: ../../source/production/observability/vllm_endpoint.rst:163
+#: ../../source/production/observability/vllm_endpoint.rst:166
+#: ../../source/production/observability/vllm_endpoint.rst:175
+#: ../../source/production/observability/vllm_endpoint.rst:178
+#: ../../source/production/observability/vllm_endpoint.rst:181
+msgid "Counter"
+msgstr "计数器"
+
+#: ../../source/production/observability/vllm_endpoint.rst:74
+msgid "Total number of retrieve requests"
+msgstr "检索请求的总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:75
+msgid "``lmcache:num_store_requests``"
+msgstr "``lmcache:num_store_requests``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:77
+msgid "Total number of store requests"
+msgstr "存储请求的总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:78
+msgid "``lmcache:num_lookup_requests``"
+msgstr "``lmcache:num_lookup_requests``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:80
+msgid "Total number of lookup requests"
+msgstr "查找请求的总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:81
+msgid "``lmcache:num_requested_tokens``"
+msgstr "``lmcache:num_requested_tokens``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:83
+msgid "Total number of tokens requested for retrieval"
+msgstr "检索请求的总令牌数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:84
+msgid "``lmcache:num_hit_tokens``"
+msgstr "``lmcache:num_hit_tokens``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:86
+msgid "Total number of cache hit tokens from retrieval"
+msgstr "从检索中获得的缓存命中令牌的总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:87
+msgid "``lmcache:num_lookup_tokens``"
+msgstr "``lmcache:num_lookup_tokens``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:89
+msgid "Total number of tokens requested in lookup operations"
+msgstr "查找操作中请求的令牌总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:90
+msgid "``lmcache:num_lookup_hits``"
+msgstr "``lmcache:num_lookup_hits``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:92
+msgid "Total number of tokens hit in lookup operations"
+msgstr "查找操作中命中的总令牌数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:93
+msgid "``lmcache:num_vllm_hit_tokens``"
+msgstr "``lmcache:num_vllm_hit_tokens``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:95
+msgid "Number of hit tokens in vLLM"
+msgstr "vLLM 中的命中令牌数量"
+
+#: ../../source/production/observability/vllm_endpoint.rst:96
+msgid "**Hit Rate Metrics**"
+msgstr "**命中率指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:99
+msgid "``lmcache:retrieve_hit_rate``"
+msgstr "``lmcache:retrieve_hit_rate``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:100
+#: ../../source/production/observability/vllm_endpoint.rst:103
+#: ../../source/production/observability/vllm_endpoint.rst:109
+#: ../../source/production/observability/vllm_endpoint.rst:112
+#: ../../source/production/observability/vllm_endpoint.rst:115
+#: ../../source/production/observability/vllm_endpoint.rst:160
+#: ../../source/production/observability/vllm_endpoint.rst:169
+#: ../../source/production/observability/vllm_endpoint.rst:184
+#: ../../source/production/observability/vllm_endpoint.rst:187
+#: ../../source/production/observability/vllm_endpoint.rst:193
+#: ../../source/production/observability/vllm_endpoint.rst:196
+msgid "Gauge"
+msgstr "仪表"
+
+#: ../../source/production/observability/vllm_endpoint.rst:101
+msgid "The hit rate for retrieve requests"
+msgstr "检索请求的命中率"
+
+#: ../../source/production/observability/vllm_endpoint.rst:102
+msgid "``lmcache:lookup_hit_rate``"
+msgstr "``lmcache:lookup_hit_rate``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:104
+msgid "The hit rate for lookup requests"
+msgstr "查找请求的命中率"
+
+#: ../../source/production/observability/vllm_endpoint.rst:105
+msgid "**Cache Usage Metrics**"
+msgstr "**缓存使用指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:108
+msgid "``lmcache:local_cache_usage``"
+msgstr "``lmcache:local_cache_usage``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:110
+msgid "Local cache usage in bytes"
+msgstr "本地缓存使用量（字节）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:111
+msgid "``lmcache:remote_cache_usage``"
+msgstr "``lmcache:remote_cache_usage``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:113
+msgid "Remote cache usage in bytes"
+msgstr "远程缓存使用量（字节）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:114
+msgid "``lmcache:local_storage_usage``"
+msgstr "``lmcache:local_storage_usage``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:116
+msgid "Local storage usage in bytes"
+msgstr "本地存储使用量（字节）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:117
+msgid "**Performance Metrics**"
+msgstr "**性能指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:120
+msgid "``lmcache:time_to_retrieve``"
+msgstr "``lmcache:time_to_retrieve``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:121
+#: ../../source/production/observability/vllm_endpoint.rst:124
+#: ../../source/production/observability/vllm_endpoint.rst:127
+#: ../../source/production/observability/vllm_endpoint.rst:130
+#: ../../source/production/observability/vllm_endpoint.rst:148
+#: ../../source/production/observability/vllm_endpoint.rst:151
+#: ../../source/production/observability/vllm_endpoint.rst:154
+msgid "Histogram"
+msgstr "直方图"
+
+#: ../../source/production/observability/vllm_endpoint.rst:122
+msgid "Time taken to retrieve from the cache (seconds)"
+msgstr "从缓存中检索所需的时间（秒）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:123
+msgid "``lmcache:time_to_store``"
+msgstr "``lmcache:time_to_store``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:125
+msgid "Time taken to store to the cache (seconds)"
+msgstr "存储到缓存所需的时间（秒）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:126
+msgid "``lmcache:retrieve_speed``"
+msgstr "``lmcache:retrieve_speed``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:128
+msgid "Retrieval speed (tokens per second)"
+msgstr "检索速度（每秒令牌数）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:129
+msgid "``lmcache:store_speed``"
+msgstr "``lmcache:store_speed``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:131
+msgid "Storage speed (tokens per second)"
+msgstr "存储速度（每秒令牌数）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:132
+msgid "**Remote Backend Metrics**"
+msgstr "**远程后端指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:135
+msgid "``lmcache:num_remote_read_requests``"
+msgstr "``lmcache:num_remote_read_requests``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:137
+msgid "Total number of read requests to remote backends"
+msgstr "对远程后端的读取请求总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:138
+msgid "``lmcache:num_remote_read_bytes``"
+msgstr "``lmcache:num_remote_read_bytes``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:140
+msgid "Total number of bytes read from remote backends"
+msgstr "从远程后端读取的字节总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:141
+msgid "``lmcache:num_remote_write_requests``"
+msgstr "``lmcache:num_remote_write_requests``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:143
+msgid "Total number of write requests to remote backends"
+msgstr "远程后端写请求的总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:144
+msgid "``lmcache:num_remote_write_bytes``"
+msgstr "``lmcache:num_remote_write_bytes``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:146
+msgid "Total number of bytes written to remote backends"
+msgstr "写入远程后端的字节总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:147
+msgid "``lmcache:remote_time_to_get``"
+msgstr "``lmcache:remote_time_to_get``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:149
+msgid "Time taken to get data from remote backends (milliseconds)"
+msgstr "从远程后端获取数据所花费的时间（毫秒）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:150
+msgid "``lmcache:remote_time_to_put``"
+msgstr "``lmcache:remote_time_to_put``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:152
+msgid "Time taken to put data to remote backends (milliseconds)"
+msgstr "将数据放入远程后端所需的时间（毫秒）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:153
+msgid "``lmcache:remote_time_to_get_sync``"
+msgstr "``lmcache:remote_time_to_get_sync``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:155
+msgid "Time taken to get data from remote backends synchronously (milliseconds)"
+msgstr "从远程后端同步获取数据所需的时间（毫秒）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:156
+msgid "**Network Monitoring Metrics**"
+msgstr "**网络监控指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:159
+msgid "``lmcache:remote_ping_latency``"
+msgstr "``lmcache:remote_ping_latency``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:161
+msgid "Latest ping latency to remote backends (milliseconds)"
+msgstr "最新的远程后端 ping 延迟（毫秒）"
+
+#: ../../source/production/observability/vllm_endpoint.rst:162
+msgid "``lmcache:remote_ping_errors``"
+msgstr "``lmcache:remote_ping_errors``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:164
+msgid "Number of ping errors to remote backends"
+msgstr "远程后端的 ping 错误数量"
+
+#: ../../source/production/observability/vllm_endpoint.rst:165
+msgid "``lmcache:remote_ping_successes``"
+msgstr "``lmcache:remote_ping_successes``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:167
+msgid "Number of ping successes to remote backends"
+msgstr "远程后端的 ping 成功次数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:168
+msgid "``lmcache:remote_ping_error_code``"
+msgstr "``lmcache:remote_ping_error_code``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:170
+msgid "Latest ping error code to remote backends"
+msgstr "最新的远程后端 ping 错误代码"
+
+#: ../../source/production/observability/vllm_endpoint.rst:171
+msgid "**Local CPU Backend Metrics**"
+msgstr "**本地 CPU 后端指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:174
+msgid "``lmcache:local_cpu_evict_count``"
+msgstr "``lmcache:local_cpu_evict_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:176
+msgid "Total number of evictions in local CPU backend"
+msgstr "本地 CPU 后端的总逐出次数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:177
+msgid "``lmcache:local_cpu_evict_keys_count``"
+msgstr "``lmcache:local_cpu_evict_keys_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:179
+msgid "Total number of evicted keys in local CPU backend"
+msgstr "本地 CPU 后端中被逐出的键的总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:180
+msgid "``lmcache:local_cpu_evict_failed_count``"
+msgstr "``lmcache:local_cpu_evict_failed_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:182
+msgid "Total number of failed evictions in local CPU backend"
+msgstr "本地 CPU 后端中失败的逐出总数"
+
+#: ../../source/production/observability/vllm_endpoint.rst:183
+msgid "``lmcache:local_cpu_hot_cache_count``"
+msgstr "``lmcache:local_cpu_hot_cache_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:185
+msgid "The size of the hot cache"
+msgstr "热缓存的大小"
+
+#: ../../source/production/observability/vllm_endpoint.rst:186
+msgid "``lmcache:local_cpu_keys_in_request_count``"
+msgstr "``lmcache:local_cpu_keys_in_request_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:188
+msgid "The size of the keys in request"
+msgstr "请求中键的大小"
+
+#: ../../source/production/observability/vllm_endpoint.rst:189
+msgid "**Memory Management Metrics**"
+msgstr "**内存管理指标**"
+
+#: ../../source/production/observability/vllm_endpoint.rst:192
+msgid "``lmcache:active_memory_objs_count``"
+msgstr "``lmcache:active_memory_objs_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:194
+msgid "The number of active memory objects"
+msgstr "活动内存对象的数量"
+
+#: ../../source/production/observability/vllm_endpoint.rst:195
+msgid "``lmcache:pinned_memory_objs_count``"
+msgstr "``lmcache:pinned_memory_objs_count``"
+
+#: ../../source/production/observability/vllm_endpoint.rst:197
+msgid "The number of pinned memory objects"
+msgstr "固定内存对象的数量"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/production/performance_tuning.po b/docs/source/locale/zh_CN/LC_MESSAGES/production/performance_tuning.po
new file mode 100644
index 0000000..a866074
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/production/performance_tuning.po
@@ -0,0 +1,140 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-07-06 10:41+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/production/performance_tuning.rst:4
+msgid "Performance Tuning"
+msgstr "性能调优"
+
+#: ../../source/production/performance_tuning.rst:8
+msgid ""
+"This page documents the behavior of LMCache's in-process mode "
+"(deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` "
+"for better feature support and performance."
+msgstr ""
+
+#: ../../source/production/performance_tuning.rst:11
+msgid ""
+"This guide covers key LMCache configuration options that can help you "
+"optimize performance in production deployments."
+msgstr "本指南涵盖了关键的 LMCache 配置选项，这些选项可以帮助您优化生产环境中的性能。"
+
+#: ../../source/production/performance_tuning.rst:15
+msgid "Minimum Retrieve Tokens"
+msgstr "最小检索令牌"
+
+#: ../../source/production/performance_tuning.rst:17
+msgid ""
+"When LMCache finds a partial KV cache hit, it loads the cached tokens "
+"into GPU memory to avoid recomputation. However, if only a small number "
+"of tokens are hit, the overhead of loading them from the cache may "
+"outweigh the benefit of skipping recomputation."
+msgstr ""
+"当 LMCache 找到部分 KV Cache "
+"命中时，它会将缓存的令牌加载到显存中，以避免重计算。然而，如果命中的令牌数量很少，从缓存中加载它们的开销可能会超过跳过重计算的好处。"
+
+#: ../../source/production/performance_tuning.rst:22
+msgid ""
+"The ``min_retrieve_tokens`` setting lets you set a threshold: if the "
+"number of tokens that need to be loaded is below this value, LMCache will"
+" skip the retrieve and let the inference engine recompute them instead."
+msgstr ""
+"``min_retrieve_tokens`` 设置允许您设置一个阈值：如果需要加载的令牌数量低于此值，LMCache "
+"将跳过检索，并让推理引擎重新计算它们。"
+
+#: ../../source/production/performance_tuning.rst:29
+msgid ""
+"Even when retrieve is skipped, LMCache still records the hit tokens "
+"internally so that it does **not** re-store chunks that already exist in "
+"the cache."
+msgstr "即使跳过了查找，LMCache 仍然在内部记录命中的令牌，以便它\\ **不**\\ 会重新存储已经存在于缓存中的块。"
+
+#: ../../source/production/performance_tuning.rst:34
+msgid "When to Use"
+msgstr "何时使用"
+
+#: ../../source/production/performance_tuning.rst:36
+msgid "Consider setting ``min_retrieve_tokens`` when:"
+msgstr "考虑在以下情况下设置 ``min_retrieve_tokens``\\ ："
+
+#: ../../source/production/performance_tuning.rst:38
+msgid ""
+"For the backend you are using, the transfer latency is noticeable for "
+"small payloads."
+msgstr "对于您使用的后端，小负载的传输延迟是显著的。"
+
+#: ../../source/production/performance_tuning.rst:40
+msgid ""
+"Your workload has many requests with **low cache hit ratios**, where "
+"recomputation is faster than cache loading."
+msgstr "您的工作负载有许多请求，\\ **缓存命中率低**\\ ，在这种情况下，重计算比缓存加载更快。"
+
+#: ../../source/production/performance_tuning.rst:42
+msgid "You want to reduce unnecessary I/O for marginal cache hits."
+msgstr "您希望减少边际缓存命中的不必要 I/O。"
+
+#: ../../source/production/performance_tuning.rst:44
+msgid "You can increase or decrease based on your latency observations."
+msgstr "您可以根据您的延迟观察来增加或减少。"
+
+#: ../../source/production/performance_tuning.rst:47
+msgid "Configuration"
+msgstr "配置"
+
+#: ../../source/production/performance_tuning.rst:49
+msgid "**YAML configuration file:**"
+msgstr "**YAML 配置文件：**"
+
+#: ../../source/production/performance_tuning.rst:57
+msgid "**Environment variable:**"
+msgstr "**环境变量：**"
+
+#: ../../source/production/performance_tuning.rst:64
+msgid "Working Example"
+msgstr "工作示例"
+
+#: ../../source/production/performance_tuning.rst:66
+msgid "Create an LMCache configuration file ``lmcache_config.yaml``:"
+msgstr "创建一个 LMCache 配置文件 ``lmcache_config.yaml``\\ ："
+
+#: ../../source/production/performance_tuning.rst:75
+msgid "Start vLLM with LMCache:"
+msgstr "使用 LMCache 启动 vLLM："
+
+#: ../../source/production/performance_tuning.rst:86
+msgid "Send a request to populate the cache:"
+msgstr "发送请求以填充缓存："
+
+#: ../../source/production/performance_tuning.rst:99
+msgid "Send a similar request that partially reuses the cached prefix:"
+msgstr "发送一个类似的请求，部分重用缓存的前缀："
+
+#: ../../source/production/performance_tuning.rst:112
+msgid ""
+"Check the server logs. If the number of loadable hit tokens is below "
+"1024, you will see a log message like:"
+msgstr "检查服务器日志。如果可加载的命中令牌数量低于 1024，您将看到类似于以下的日志消息："
+
+#: ../../source/production/performance_tuning.rst:120
+msgid ""
+"This confirms that the small cache hit was skipped in favor of "
+"recomputation, avoiding unnecessary transfer overhead."
+msgstr "这确认了小缓存命中被跳过，以便进行重计算，从而避免不必要的传输开销。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/deepseek_v4_flash.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/deepseek_v4_flash.po
new file mode 100644
index 0000000..5f9ee47
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/deepseek_v4_flash.po
@@ -0,0 +1,166 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:4
+msgid "DeepSeek-V4-Flash"
+msgstr "DeepSeek-V4-Flash"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:9
+msgid ""
+"`deepseek-ai/DeepSeek-V4-Flash <https://huggingface.co/deepseek-"
+"ai/DeepSeek-V4-Flash>`_"
+msgstr ""
+"`deepseek-ai/DeepSeek-V4-Flash <https://huggingface.co/deepseek-"
+"ai/DeepSeek-V4-Flash>`_"
+
+#: ../../source/recipes/deepseek_v4_flash.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:16
+msgid ""
+"**Engine documentation:** `DeepSeek-V4-Flash in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``DeepseekV4ForCausalLM``)."
+msgstr "**引擎文档：** `DeepSeek-V4-Flash 在 vLLM 支持的模型 <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_ （架构 ``DeepseekV4ForCausalLM``\\ ）。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:21
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:23
+msgid ""
+"**Installing vLLM:** DeepSeek-V4-Flash needs the sparse-MLA attention "
+"backends and the ``fp8_ds_mla`` KV cache kernels, so install vLLM by "
+"following its own recipe rather than a bare ``pip install vllm``: `vLLM "
+"DeepSeek-V4-Flash recipe "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ (also "
+"mirrored at https://recipes.vllm.ai/deepseek-ai/DeepSeek-V4-Flash)."
+msgstr "**安装 vLLM：** DeepSeek-V4-Flash 需要稀疏 MLA 注意力后端和 ``fp8_ds_mla`` KV Cache 内核，因此请按照其专属指南安装 vLLM，而非直接使用 ``pip install vllm``\\ ：\\ `vLLM DeepSeek-V4-Flash 指南 <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_\\ （也可在 https://recipes.vllm.ai/deepseek-ai/DeepSeek-V4-Flash 查看镜像）。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:32
+msgid ""
+"Use the **latest vLLM release**, not the ``main``/dev branch. The current"
+" vLLM development branch is broken for DeepSeek-V4-Flash (the ``fp4`` MoE"
+" experts are misdispatched and the real weights fail to load). Pin to the"
+" latest tagged release as the vLLM recipe instructs."
+msgstr "请使用 **最新的 vLLM 正式版本**\\ ，而非 ``main``/dev 分支。当前 vLLM 开发分支对 DeepSeek-V4-Flash 存在兼容性问题（\\ ``fp4`` MoE 专家路由有误，实际权重无法加载）。请按照 vLLM 指南的说明，锁定到最新的标签版本。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:37
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/deepseek_v4_flash.rst:45
+msgid "Start vLLM with the LMCache MP connector (8 GPUs):"
+msgstr "使用 LMCache MP 连接器（8 个 GPU）启动 vLLM："
+
+#: ../../source/recipes/deepseek_v4_flash.rst:60
+msgid ""
+"``--kv-cache-dtype fp8_ds_mla`` and ``--tokenizer-mode deepseek_v4`` are "
+"required for this model; ``--enable-expert-parallel`` distributes the MoE"
+" experts across the tensor-parallel ranks. Adjust ``--tensor-parallel-"
+"size`` to match your hardware. For the generic LMCache + vLLM wiring "
+"(ports, remote hosts), see :doc:`../getting_started/quickstart`."
+msgstr "``--kv-cache-dtype fp8_ds_mla`` 和 ``--tokenizer-mode deepseek_v4`` 是该模型的必选参数；\\ ``--enable-expert-parallel`` 将 MoE 专家分散到各张量并行 rank 上。请根据您的硬件调整 ``--tensor-parallel-size``\\ 。有关 LMCache + vLLM 的通用配置（端口、远程主机等），请参见 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:67
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr ""
+"如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:73
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:77
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:80
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:83
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:89
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:90
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:91
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:92
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:93
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:97
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:99
+msgid ""
+"**Requires the latest vLLM release.** The vLLM dev branch is currently "
+"broken for this model (see the warning above) -- use a tagged release "
+"installed via the vLLM recipe."
+msgstr "**需要最新的 vLLM 正式版本。** vLLM 开发分支目前对该模型存在兼容性问题（请参见上方警告）——请使用通过 vLLM 指南安装的标签版本。"
+
+#: ../../source/recipes/deepseek_v4_flash.rst:102
+msgid ""
+"**Sparse-MLA hybrid KV cache.** DeepSeek-V4-Flash interleaves several KV "
+"cache groups with different block geometries (the compressed MLA latents "
+"are stored as ``fp8``/``uint8`` while the sparse-attention indexer groups"
+" are ``float32``), so the groups do not share a single block size. "
+"LMCache stores and retrieves each group in its own block size; no extra "
+"flags are required beyond ``--kv-cache-dtype fp8_ds_mla``."
+msgstr "**稀疏 MLA 混合 KV Cache。** DeepSeek-V4-Flash 将多个具有不同块几何形状的 KV Cache 组交错排列（压缩的 MLA 潜变量以 ``fp8``/``uint8`` 格式存储，而稀疏注意力索引器组为 ``float32``\\ ），因此各组不共享统一的块大小。LMCache 会按各组自身的块大小分别进行存储和检索；除 ``--kv-cache-dtype fp8_ds_mla`` 外，无需设置额外标志。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/devstral.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/devstral.po
new file mode 100644
index 0000000..f77461b
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/devstral.po
@@ -0,0 +1,139 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/devstral.rst:4
+msgid "Mistral / Devstral"
+msgstr "Mistral / Devstral"
+
+#: ../../source/recipes/devstral.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/devstral.rst:9
+msgid ""
+"`mistralai/Devstral-2-123B-Instruct-2512 "
+"<https://huggingface.co/mistralai/Devstral-2-123B-Instruct-2512>`_"
+msgstr ""
+"`mistralai/Devstral-2-123B-Instruct-2512 "
+"<https://huggingface.co/mistralai/Devstral-2-123B-Instruct-2512>`_"
+
+#: ../../source/recipes/devstral.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/devstral.rst:16
+msgid ""
+"**Engine documentation:** `Mistral / Devstral in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``MistralForCausalLM``)."
+msgstr ""
+"**引擎文档：** `Mistral / Devstral 在 vLLM 支持的模型 "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ （架构 ``MistralForCausalLM``）。"
+
+#: ../../source/recipes/devstral.rst:21
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/devstral.rst:23
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/devstral.rst:31
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/devstral.rst:44
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/devstral.rst:48
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr "如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/devstral.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/devstral.rst:54
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/devstral.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/devstral.rst:58
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/devstral.rst:61
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/devstral.rst:64
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/devstral.rst:70
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/devstral.rst:71
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/devstral.rst:72
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/devstral.rst:73
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/devstral.rst:74
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/devstral.rst:78
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/devstral.rst:80
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "MistralForCausalLM"
+#~ msgstr "MistralForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gemma3.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gemma3.po
new file mode 100644
index 0000000..86775ec
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gemma3.po
@@ -0,0 +1,163 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/gemma3.rst:4
+msgid "Gemma 3"
+msgstr "Gemma 3"
+
+#: ../../source/recipes/gemma3.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/gemma3.rst:9
+msgid "`google/gemma-3-4b-it <https://huggingface.co/google/gemma-3-4b-it>`_"
+msgstr "`google/gemma-3-4b-it <https://huggingface.co/google/gemma-3-4b-it>`_"
+
+#: ../../source/recipes/gemma3.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/gemma3.rst:16
+msgid ""
+"**Engine documentation:** `Gemma 3 in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#multimodal-"
+"language-models>`_ (architecture ``Gemma3ForConditionalGeneration``)."
+msgstr ""
+"**引擎文档：** `Gemma 3 在 vLLM 支持的模型 "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#multimodal-"
+"language-models>`_ (架构 ``Gemma3ForConditionalGeneration``)。"
+
+#: ../../source/recipes/gemma3.rst:21
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/gemma3.rst:23
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/gemma3.rst:31
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/gemma3.rst:42
+msgid ""
+"Gemma 3 interleaves local (sliding-window) and global (full) attention "
+"layers, so vLLM keeps its **hybrid KV cache manager** on and exposes "
+"multiple KV cache groups. LMCache stores and retrieves all of them "
+"through its hybrid memory allocator support -- ``LMCacheMPConnector`` "
+"advertises ``SupportsHMA``, so vLLM does not auto-disable the hybrid "
+"manager and no extra configuration is required."
+msgstr "Gemma 3 交错使用 local (sliding-window) 和 global (full) attention 层，因此 vLLM 保持其 **混合 KV Cache 管理器** 开启，并公开多个 KV Cache 组。LMCache 通过其混合内存分配器支持存储和检索所有这些组——``LMCacheMPConnector`` 声明 ``SupportsHMA``\\ ，因此 vLLM 不会自动禁用混合管理器，也无需额外配置。"
+
+#: ../../source/recipes/gemma3.rst:49
+msgid ""
+"``google/gemma-3-4b-it`` is a gated model; authenticate with the Hugging "
+"Face Hub (e.g. set ``HF_TOKEN``) before serving. Adjust ``--tensor-"
+"parallel-size`` to match your hardware. For the generic LMCache + vLLM "
+"wiring (ports, remote hosts), see :doc:`../getting_started/quickstart`."
+msgstr "``google/gemma-3-4b-it`` 是一个 gated 模型；在启动服务之前，请通过 Hugging Face Hub 进行身份验证（例如，设置 ``HF_TOKEN``\\ ）。请根据您的硬件调整 ``--tensor-parallel-size``\\ 。有关通用 LMCache + vLLM 连接配置（端口、远程主机），请参见 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/gemma3.rst:55
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr ""
+"如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/gemma3.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/gemma3.rst:61
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/gemma3.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/gemma3.rst:65
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/gemma3.rst:68
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/gemma3.rst:70
+msgid "Not validated."
+msgstr "未验证。"
+
+#: ../../source/recipes/gemma3.rst:73
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/gemma3.rst:79
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/gemma3.rst:80
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/gemma3.rst:81
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/gemma3.rst:82
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/gemma3.rst:83
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/gemma3.rst:87
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/gemma3.rst:89
+msgid ""
+"**Gated model.** ``google/gemma-3-4b-it`` requires accepting the license "
+"on Hugging Face and authenticating (e.g. ``HF_TOKEN``) before it can be "
+"served."
+msgstr "**Gated 模型。** ``google/gemma-3-4b-it`` 需要在 Hugging Face 上接受许可并进行身份验证（例如 ``HF_TOKEN``\\ ），才能提供服务。"
+
+#: ../../source/recipes/gemma3.rst:91
+msgid ""
+"**Hybrid attention.** Gemma 3 is a hybrid (sliding-window + full-"
+"attention) model. LMCache transfers every KV cache group via its hybrid "
+"memory allocator support, so caching works transparently. This applies to"
+" the standard paged attention used by Gemma 3; Mamba / linear-attention "
+"hybrids (whose recurrent state caches LMCache cannot yet transfer) are "
+"not supported."
+msgstr "**hybrid attention。** Gemma 3 是一个混合（sliding window + full attention）模型。LMCache 通过其混合内存分配器支持传输每个 KV Cache 组，因此缓存可透明运作。这适用于 Gemma 3 使用的 standard paged attention；Mamba / linear attention 混合模型（其递归状态缓存 LMCache 目前尚无法传输）暂不支持。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "Gemma3ForConditionalGeneration"
+#~ msgstr "Gemma3ForConditionalGeneration"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gemma4.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gemma4.po
new file mode 100644
index 0000000..42d354c
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gemma4.po
@@ -0,0 +1,179 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/gemma4.rst:4
+msgid "Gemma 4"
+msgstr "Gemma 4"
+
+#: ../../source/recipes/gemma4.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/gemma4.rst:9
+msgid "`google/gemma-4-31B-it <https://huggingface.co/google/gemma-4-31B-it>`_"
+msgstr "`google/gemma-4-31B-it <https://huggingface.co/google/gemma-4-31B-it>`_"
+
+#: ../../source/recipes/gemma4.rst:10
+msgid "`google/gemma-4-12B-it <https://huggingface.co/google/gemma-4-12B-it>`_"
+msgstr "`google/gemma-4-12B-it <https://huggingface.co/google/gemma-4-12B-it>`_"
+
+#: ../../source/recipes/gemma4.rst:11
+msgid "`google/gemma-4-E4B-it <https://huggingface.co/google/gemma-4-E4B-it>`_"
+msgstr "`google/gemma-4-E4B-it <https://huggingface.co/google/gemma-4-E4B-it>`_"
+
+#: ../../source/recipes/gemma4.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/gemma4.rst:18
+msgid ""
+"**Engine documentation:** `Gemma 4 in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#multimodal-"
+"language-models>`_ (architectures ``Gemma4ForConditionalGeneration`` for "
+"31B/E4B and ``Gemma4UnifiedForConditionalGeneration`` for 12B)."
+msgstr "**引擎文档:** `vLLM 支持模型中的 Gemma 4 <https://docs.vllm.ai/en/latest/models/supported_models.html#multimodal-language-models>`_\\ （架构 ``Gemma4ForConditionalGeneration`` 适用于 31B/E4B，\\ ``Gemma4UnifiedForConditionalGeneration`` 适用于 12B）。"
+
+#: ../../source/recipes/gemma4.rst:24
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/gemma4.rst:26
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/gemma4.rst:34
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/gemma4.rst:45
+msgid ""
+"The smaller ``google/gemma-4-12B-it`` and ``google/gemma-4-E4B-it`` run "
+"on a single GPU:"
+msgstr "较小的 ``google/gemma-4-12B-it`` 和 ``google/gemma-4-E4B-it`` 在单个 GPU 上运行："
+
+#: ../../source/recipes/gemma4.rst:56
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr "调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/gemma4.rst:60
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr ""
+"如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/gemma4.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/gemma4.rst:66
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/gemma4.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/gemma4.rst:70
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/gemma4.rst:73
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/gemma4.rst:76
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/gemma4.rst:82
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/gemma4.rst:83
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/gemma4.rst:84
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/gemma4.rst:85
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/gemma4.rst:86
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/gemma4.rst:90
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/gemma4.rst:92
+msgid ""
+"**Hybrid KV cache with heterogeneous block sizes.** Gemma 4 interleaves "
+"sliding-window and full-attention layers whose head dimensions differ "
+"(sliding 256, full 512), so vLLM unifies the physical page size by giving"
+" the two attention types different ``block_size``\\ s (e.g. "
+"``google/gemma-4-E4B-it``: sliding 32, full 16). LMCache stores and "
+"retrieves each KV cache group in its own block size; no extra flags are "
+"required."
+msgstr "**混合 KV Cache，具有异构块大小。** Gemma 4 交错了 sliding window 和 full attention 层，两者的头维度不同（sliding window 层为 256，full attention 层为 512），因此 vLLM 通过为这两种注意力类型分配不同的 ``block_size``\\\\ s（例如 ``google/gemma-4-E4B-it``\\ ：sliding window 层为 32，full attention 层为 16）来统一物理页面大小。LMCache 按各自的块大小存储和检索每个 KV Cache 组，无需额外配置。"
+
+#: ../../source/recipes/gemma4.rst:98
+msgid ""
+"**Cross-layer KV sharing.** ``google/gemma-4-E4B-it`` reuses some layers'"
+" KV caches across layers. LMCache stores the cache-owning layers only; "
+"the sharing layers' KV lives in the same blocks and is restored "
+"automatically."
+msgstr ""
+"**跨层 KV 共享。** ``google/gemma-4-E4B-it`` 在层与层之间重用一些层的 KV 缓存。LMCache "
+"仅存储拥有缓存的层；共享层的 KV 存储在相同的块中，并会自动恢复。"
+
+#~ msgid "None known."
+#~ msgstr "没有已知的问题。"
+
+#~ msgid "Gemma4ForConditionalGeneration"
+#~ msgstr "Gemma4ForConditionalGeneration"
+
+#~ msgid ""
+#~ "**Determinism.** Gemma 4 runs on the "
+#~ "Triton attention backend, which is not"
+#~ " bit-exact under vLLM's batch-"
+#~ "invariant mode, so a retrieved result"
+#~ " may differ from a freshly computed"
+#~ " one by a small numerical margin "
+#~ "rather than being byte-identical."
+#~ msgstr ""
+#~ "**确定性。** Gemma 4 在 Triton 注意力后端上运行，该后端在"
+#~ " vLLM 的批量不变模式下不是位精确的，因此检索到的结果可能与新计算的结果存在小的数值差异，而不是字节完全相同。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/glm5_2.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/glm5_2.po
new file mode 100644
index 0000000..a3ae6d6
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/glm5_2.po
@@ -0,0 +1,150 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/glm5_2.rst:4
+msgid "GLM 5.1/5.2"
+msgstr "GLM 5.1/5.2"
+
+#: ../../source/recipes/glm5_2.rst:6
+msgid ""
+"A large Mixture-of-Experts model using **Dynamic Sparse Attention "
+"(DSA)**, shared by the **GLM-5.1 / GLM-5.2** series. Like "
+"DeepSeek-V4-Flash, the sparse-attention path splits the model's layers "
+"into more than one KV cache group; the ``LMCacheMPConnector`` stores and "
+"retrieves each group in its own block size, so KV reuse works without "
+"extra flags."
+msgstr "一个大型的专家混合模型，使用 **动态稀疏注意力 (DSA)**，由 **GLM-5.1 / GLM-5.2** 系列共享。与 DeepSeek-V4-Flash 类似，稀疏注意力路径将模型的层分成多个 KV Cache 组；``LMCacheMPConnector`` 在其自己的块大小中存储和检索每个组，因此 KV 重用在没有额外标志的情况下工作。"
+
+#: ../../source/recipes/glm5_2.rst:13
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/glm5_2.rst:15
+msgid ""
+"`zai-org/GLM-5.2-FP8 <https://huggingface.co/zai-org/GLM-5.2-FP8>`_ (8 "
+"GPUs)"
+msgstr "`zai-org/GLM-5.2-FP8 <https://huggingface.co/zai-org/GLM-5.2-FP8>`_ (8 GPUs)"
+
+#: ../../source/recipes/glm5_2.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/glm5_2.rst:22
+msgid ""
+"**Engine documentation:** `GLM-5.2 in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``GlmMoeDsaForCausalLM``). See also the `vLLM"
+" GLM-5.2 recipe <https://recipes.vllm.ai/zai-org/GLM-5.2>`_."
+msgstr "**引擎文档：** `GLM-5.2 在 vLLM 支持的模型 <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_ （架构 ``GlmMoeDsaForCausalLM``）。另见 `vLLM GLM-5.2 食谱 <https://recipes.vllm.ai/zai-org/GLM-5.2>`_。"
+
+#: ../../source/recipes/glm5_2.rst:28
+msgid "**Status:** Validated with LMCache (vLLM 0.23.0 + LMCache 0.4.7)."
+msgstr "**状态:** 已通过 LMCache (vLLM 0.23.0 + LMCache 0.4.7) 验证。"
+
+#: ../../source/recipes/glm5_2.rst:30
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/glm5_2.rst:43
+msgid "Start vLLM with the LMCache MP connector (8 GPUs):"
+msgstr "使用 LMCache MP 连接器（8 个 GPU）启动 vLLM："
+
+#: ../../source/recipes/glm5_2.rst:58
+msgid ""
+"``--tool-call-parser glm47``, ``--enable-auto-tool-choice``, and "
+"``--reasoning-parser glm45`` are GLM-5.2's serving requirements (see the "
+"vLLM recipe). ``--no-enable-prefix-caching`` routes all KV reuse through "
+"LMCache rather than vLLM's in-engine prefix cache. The server's ``--port "
+"6555`` must match ``lmcache.mp.port`` in the connector config; ``--max-"
+"workers`` is set to the tensor-parallel size. Adjust ``--tensor-parallel-"
+"size`` to match your hardware. For the generic LMCache + vLLM wiring "
+"(ports, remote hosts), see :doc:`../getting_started/quickstart`."
+msgstr "``--tool-call-parser glm47``、``--enable-auto-tool-choice`` 和 ``--reasoning-parser glm45`` 是 GLM-5.2 的服务要求（请参见 vLLM 配方）。``--no-enable-prefix-caching`` 将所有 KV 重用路由通过 LMCache，而不是 vLLM 的引擎内前缀缓存。服务器的 ``--port 6555`` 必须与连接器配置中的 ``lmcache.mp.port`` 匹配；``--max-workers`` 设置为张量并行大小。调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用的 LMCache + vLLM 连接（端口、远程主机），请参见 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/glm5_2.rst:68
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr "如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/glm5_2.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/glm5_2.rst:74
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/glm5_2.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/glm5_2.rst:78
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/glm5_2.rst:81
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/glm5_2.rst:83
+msgid "Not validated."
+msgstr "未验证。"
+
+#: ../../source/recipes/glm5_2.rst:86
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/glm5_2.rst:92
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/glm5_2.rst:93
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/glm5_2.rst:94
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/glm5_2.rst:95
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/glm5_2.rst:96
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/glm5_2.rst:100
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/glm5_2.rst:102
+msgid ""
+"**Dynamic Sparse Attention KV groups.** GLM-5.2's DSA path splits the "
+"model's layers into more than one KV cache group with different block "
+"geometries. LMCache stores and retrieves each group in its own block "
+"size; no extra flags are required beyond the launch commands above."
+msgstr "**动态稀疏注意力 KV 组。** GLM-5.2 的 DSA 路径将模型的层分成多个具有不同块几何形状的 KV 缓存组。LMCache 在其各自的块大小中存储和检索每个组；除了上述启动命令外，不需要额外的标志。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gpt_oss.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gpt_oss.po
new file mode 100644
index 0000000..5fd8499
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/gpt_oss.po
@@ -0,0 +1,145 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/gpt_oss.rst:4
+msgid "gpt-oss"
+msgstr "gpt-oss"
+
+#: ../../source/recipes/gpt_oss.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/gpt_oss.rst:9
+msgid "`openai/gpt-oss-120b <https://huggingface.co/openai/gpt-oss-120b>`_"
+msgstr "`openai/gpt-oss-120b <https://huggingface.co/openai/gpt-oss-120b>`_"
+
+#: ../../source/recipes/gpt_oss.rst:10
+msgid "`openai/gpt-oss-20b <https://huggingface.co/openai/gpt-oss-20b>`_"
+msgstr "`openai/gpt-oss-20b <https://huggingface.co/openai/gpt-oss-20b>`_"
+
+#: ../../source/recipes/gpt_oss.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/gpt_oss.rst:17
+msgid ""
+"**Engine documentation:** `GPT-OSS in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``GptOssForCausalLM``)."
+msgstr ""
+"**引擎文档：** `vLLM 支持的模型中的 GPT-OSS "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ （架构 ``GptOssForCausalLM``）。"
+
+#: ../../source/recipes/gpt_oss.rst:22
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/gpt_oss.rst:24
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/gpt_oss.rst:32
+msgid "**gpt-oss-120b** (2 GPUs):"
+msgstr "**gpt-oss-120b** (2 GPUs):"
+
+#: ../../source/recipes/gpt_oss.rst:45
+msgid "**gpt-oss-20b** (1 GPU):"
+msgstr "**gpt-oss-20b** (1 GPU):"
+
+#: ../../source/recipes/gpt_oss.rst:57
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/gpt_oss.rst:61
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr ""
+"如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/gpt_oss.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/gpt_oss.rst:67
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/gpt_oss.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/gpt_oss.rst:71
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/gpt_oss.rst:74
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/gpt_oss.rst:77
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/gpt_oss.rst:83
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/gpt_oss.rst:84
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/gpt_oss.rst:85
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/gpt_oss.rst:86
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/gpt_oss.rst:87
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/gpt_oss.rst:91
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/gpt_oss.rst:93
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "GptOssForCausalLM"
+#~ msgstr "GptOssForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/index.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/index.po
new file mode 100644
index 0000000..925fed0
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/index.po
@@ -0,0 +1,257 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-17 02:35+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/index.rst:4
+msgid "Recipes"
+msgstr "配置示例"
+
+#: ../../source/recipes/index.rst:6
+msgid ""
+"This section lists model architectures validated end-to-end with LMCache,"
+" with a recipe page per architecture covering only the LMCache-specific "
+"configuration that diverges from defaults. Engine-side documentation (how"
+" to serve the model itself) lives with the serving engine; recipe pages "
+"link out rather than duplicate."
+msgstr "本节列出了通过 LMCache 端到端验证的模型架构，每个架构均有一个对应的配置示例页面，仅涵盖与默认值不同的 LMCache 特定配置。引擎端文档（如何部署模型本身）随服务引擎维护；配置示例页面提供外部链接，不重复已有内容。"
+
+#: ../../source/recipes/index.rst:12
+msgid ""
+"For the generic LMCache + engine wiring (ports, remote hosts, sending a "
+"first request), see :doc:`../getting_started/quickstart` -- recipes "
+"assume that page as a prerequisite."
+msgstr "有关通用的 LMCache + 引擎连接配置（端口、远程主机、发送第一个请求），请参见 :doc:`../getting_started/quickstart` —— 各配置示例页面均以该文档为前提。"
+
+#: ../../source/recipes/index.rst:16
+msgid "Recipes are grouped by attention architecture:"
+msgstr "配置示例按注意力架构分组："
+
+#~ msgid ""
+#~ "Engine-side documentation (how to serve"
+#~ " the model itself) lives with the "
+#~ "serving engine. Recipe pages link out"
+#~ " rather than duplicate."
+#~ msgstr "引擎端文档（如何服务模型本身）随服务引擎一起维护。使用指南页面提供外部链接，不重复已有内容。"
+
+#~ msgid "Recipe page contents"
+#~ msgstr "使用指南页面内容"
+
+#~ msgid "Each recipe page is intentionally minimal:"
+#~ msgstr "每个使用指南页面都故意保持简约："
+
+#~ msgid "**Validated models** -- exact HF repo IDs that have been tested."
+#~ msgstr "**验证过的模型** -- 已测试的确切 HF 仓库 ID。"
+
+#~ msgid ""
+#~ "**Engine tabs** -- one tab per "
+#~ "serving engine (vLLM, SGLang, TRT-LLM)."
+#~ " Each tab links to the engine's "
+#~ "own documentation for the model and "
+#~ "shows the exact ``lmcache server`` and"
+#~ " engine launch commands. Tabs for "
+#~ "engines that are not yet validated "
+#~ "state so explicitly."
+#~ msgstr ""
+#~ "**引擎选项卡** -- 每个服务引擎 (vLLM, SGLang, "
+#~ "TRT-LLM) 一个选项卡。每个选项卡链接到该引擎的模型文档，并显示确切的 ``lmcache "
+#~ "server`` 和引擎启动命令。尚未验证的引擎的选项卡会明确说明。"
+
+#~ msgid "**CacheBlend support** -- validation status (may be empty)."
+#~ msgstr "**CacheBlend 支持** -- 验证状态（可能为空）。"
+
+#~ msgid ""
+#~ "**Compression support** -- table of "
+#~ "compression methods (CacheGen, etc.) with "
+#~ "per-method validation status. Extensible: "
+#~ "new methods get a row."
+#~ msgstr "**压缩支持** -- 压缩方法（CacheGen 等）的表格，包含每种方法的验证状态。可扩展：新方法将获得一行。"
+
+#~ msgid "**Caveats** -- known limitations, if any."
+#~ msgstr "**注意事项** -- 已知的限制（如果有的话）。"
+
+#~ msgid "Supported architectures"
+#~ msgstr "支持的架构"
+
+#~ msgid "Architecture"
+#~ msgstr "架构"
+
+#~ msgid "Example HF model"
+#~ msgstr "示例 HF 模型"
+
+#~ msgid "vLLM"
+#~ msgstr "vLLM"
+
+#~ msgid "SGLang"
+#~ msgstr "SGLang"
+
+#~ msgid "TRT-LLM"
+#~ msgstr "TRT-LLM"
+
+#~ msgid "Recipe"
+#~ msgstr "使用指南"
+
+#~ msgid "``DeepseekV4ForCausalLM``"
+#~ msgstr "``DeepseekV4ForCausalLM``"
+
+#~ msgid "``deepseek-ai/DeepSeek-V4-Flash``"
+#~ msgstr "``deepseek-ai/DeepSeek-V4-Flash``"
+
+#~ msgid "✓"
+#~ msgstr "✓"
+
+#~ msgid "—"
+#~ msgstr "—"
+
+#~ msgid ":doc:`deepseek_v4_flash`"
+#~ msgstr ":doc:`deepseek_v4_flash`"
+
+#~ msgid "``MiniMaxM2ForCausalLM``"
+#~ msgstr "``MiniMaxM2ForCausalLM``"
+
+#~ msgid "``MiniMaxAI/MiniMax-M2``"
+#~ msgstr "``MiniMaxAI/MiniMax-M2``"
+
+#~ msgid ":doc:`minimax_m2`"
+#~ msgstr ":doc:`minimax_m2`"
+
+#~ msgid "``Gemma4ForConditionalGeneration``"
+#~ msgstr "``Gemma4ForConditionalGeneration``"
+
+#~ msgid "``google/gemma-4-31B-it``"
+#~ msgstr "``google/gemma-4-31B-it``"
+
+#~ msgid "``google/gemma-4-E4B-it``"
+#~ msgstr "``google/gemma-4-E4B-it``"
+
+#~ msgid ":doc:`gemma4`"
+#~ msgstr ":doc:`gemma4`"
+
+#~ msgid "``Gemma4UnifiedForConditionalGeneration``"
+#~ msgstr "``Gemma4UnifiedForConditionalGeneration``"
+
+#~ msgid "``google/gemma-4-12B-it``"
+#~ msgstr "``google/gemma-4-12B-it``"
+
+#~ msgid "``Gemma3ForConditionalGeneration``"
+#~ msgstr "``Gemma3ForConditionalGeneration``"
+
+#~ msgid "``google/gemma-3-4b-it``"
+#~ msgstr "``google/gemma-3-4b-it``"
+
+#~ msgid ":doc:`gemma3`"
+#~ msgstr "`:doc:`gemma3``"
+
+#~ msgid "``MistralForCausalLM``"
+#~ msgstr "``MistralForCausalLM``"
+
+#~ msgid "``mistralai/Devstral-2-123B-Instruct-2512``"
+#~ msgstr "``mistralai/Devstral-2-123B-Instruct-2512``"
+
+#~ msgid ":doc:`devstral`"
+#~ msgstr ":doc:`devstral`"
+
+#~ msgid "``GptOssForCausalLM``"
+#~ msgstr "``GptOssForCausalLM``"
+
+#~ msgid "``openai/gpt-oss-120b``"
+#~ msgstr "``openai/gpt-oss-120b``"
+
+#~ msgid ":doc:`gpt_oss`"
+#~ msgstr ":gpt_oss:"
+
+#~ msgid "``Qwen3MoeForCausalLM``"
+#~ msgstr "``Qwen3MoeForCausalLM``"
+
+#~ msgid "``Qwen/Qwen3-235B-A22B``"
+#~ msgstr "``Qwen/Qwen3-235B-A22B``"
+
+#~ msgid ":doc:`qwen3`"
+#~ msgstr "：doc:`qwen3`"
+
+#~ msgid "``Qwen3_5ForConditionalGeneration``"
+#~ msgstr "``Qwen3_5ForConditionalGeneration``"
+
+#~ msgid "``Qwen/Qwen3.6-27B``"
+#~ msgstr "``Qwen/Qwen3.6-27B``"
+
+#~ msgid "``Qwen/Qwen3.5-0.8B``"
+#~ msgstr "``Qwen/Qwen3.5-0.8B``"
+
+#~ msgid ":doc:`qwen3_5`"
+#~ msgstr "`:doc:`qwen3_5``"
+
+#~ msgid "``LlamaForCausalLM``"
+#~ msgstr "``LlamaForCausalLM``"
+
+#~ msgid "``meta-llama/Meta-Llama-3.1-70B-Instruct``"
+#~ msgstr "``meta-llama/Meta-Llama-3.1-70B-Instruct``"
+
+#~ msgid ":doc:`llama`"
+#~ msgstr "`:doc:`llama`"
+
+#~ msgid "``Phi3ForCausalLM``"
+#~ msgstr "``Phi3ForCausalLM``"
+
+#~ msgid "``microsoft/Phi-4-mini-instruct``"
+#~ msgstr "``microsoft/Phi-4-mini-instruct``"
+
+#~ msgid ":doc:`phi3`"
+#~ msgstr ":doc:`phi3`"
+
+#~ msgid "``MixtralForCausalLM``"
+#~ msgstr "``MixtralForCausalLM``"
+
+#~ msgid "``mistralai/Mixtral-8x7B-Instruct-v0.1``"
+#~ msgstr "``mistralai/Mixtral-8x7B-Instruct-v0.1``"
+
+#~ msgid ":doc:`mixtral`"
+#~ msgstr ":doc:`mixtral`"
+
+#~ msgid "Legend: ``✓`` validated, ``—`` not validated."
+#~ msgstr "图例：``✓`` 已验证，``—`` 未验证。"
+
+#~ msgid "Contributing a recipe"
+#~ msgstr "贡献一个使用指南"
+
+#~ msgid "To add a new architecture:"
+#~ msgstr "要添加一个新架构："
+
+#~ msgid ""
+#~ "Copy an existing page (e.g. "
+#~ "``minimax_m2.rst``) to "
+#~ "``recipes/<architecture_snake_case>.rst``."
+#~ msgstr ""
+#~ "将现有页面（例如 ``minimax_m2.rst``）复制到 "
+#~ "``recipes/<architecture_snake_case>.rst``。"
+
+#~ msgid ""
+#~ "Fill in **Validated models**, **Engines**, "
+#~ "**LMCache configuration**, and **Caveats**. "
+#~ "Keep each section terse -- if a"
+#~ " field has nothing to say, say "
+#~ "so in one line rather than padding"
+#~ " it."
+#~ msgstr ""
+#~ "填写 **已验证模型**、**引擎**、**LMCache 配置** 和 "
+#~ "**注意事项**。保持每个部分简洁 -- 如果某个字段没有内容，请用一行说明，而不是填充内容。"
+
+#~ msgid "Add a row to the table above and an entry to the hidden toctree below."
+#~ msgstr "在上面的表格中添加一行，并在下面的隐藏 toctree 中添加一个条目。"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/llama.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/llama.po
new file mode 100644
index 0000000..c374dbc
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/llama.po
@@ -0,0 +1,188 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/llama.rst:4
+msgid "Llama"
+msgstr "Llama"
+
+#: ../../source/recipes/llama.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/llama.rst:9
+msgid ""
+"`meta-llama/Meta-Llama-3.1-8B <https://huggingface.co/meta-"
+"llama/Llama-3.1-8B>`_"
+msgstr ""
+"`meta-llama/Meta-Llama-3.1-8B <https://huggingface.co/meta-"
+"llama/Llama-3.1-8B>`_"
+
+#: ../../source/recipes/llama.rst:10
+msgid ""
+"`meta-llama/Meta-Llama-3.1-8B-Instruct <https://huggingface.co/meta-"
+"llama/Llama-3.1-8B-Instruct>`_"
+msgstr ""
+"`meta-llama/Meta-Llama-3.1-8B-Instruct <https://huggingface.co/meta-"
+"llama/Llama-3.1-8B-Instruct>`_"
+
+#: ../../source/recipes/llama.rst:11
+msgid ""
+"`meta-llama/Meta-Llama-3.1-70B <https://huggingface.co/meta-"
+"llama/Llama-3.1-70B>`_"
+msgstr ""
+"`meta-llama/Meta-Llama-3.1-70B <https://huggingface.co/meta-"
+"llama/Llama-3.1-70B>`_"
+
+#: ../../source/recipes/llama.rst:12
+msgid ""
+"`meta-llama/Meta-Llama-3.1-70B-Instruct <https://huggingface.co/meta-"
+"llama/Llama-3.1-70B-Instruct>`_"
+msgstr ""
+"`meta-llama/Meta-Llama-3.1-70B-Instruct <https://huggingface.co/meta-"
+"llama/Llama-3.1-70B-Instruct>`_"
+
+#: ../../source/recipes/llama.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/llama.rst:19
+msgid ""
+"**Engine documentation:** `LlamaForCausalLM in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture `LlamaForCausalLM`)."
+msgstr ""
+"**引擎文档：** `vLLM 支持的模型中的 LlamaForCausalLM "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ （架构 `LlamaForCausalLM`）。"
+
+#: ../../source/recipes/llama.rst:24
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/llama.rst:26
+msgid ""
+"Apply for access on the model card page and add your `huggingface token "
+"<https://huggingface.co/docs/hub/en/security-tokens>`_ as an environment "
+"variable:"
+msgstr ""
+"在模型卡页面申请访问权限，并将您的 `huggingface token <https://huggingface.co/docs/hub/en"
+"/security-tokens>`_ 添加为环境变量："
+
+#: ../../source/recipes/llama.rst:36
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/llama.rst:44
+msgid ""
+"Get the chat templates for tool calling by following the `Llama tool "
+"calling guide <https://docs.vllm.ai/en/latest/features/tool_calling"
+"/#llama-models-llama3_json>`_ from vLLM."
+msgstr "请参照 vLLM 的 `Llama 工具调用指南 <https://docs.vllm.ai/en/latest/features/tool_calling/#llama-models-llama3_json>`_ 获取工具调用所需的聊天模板。"
+
+#: ../../source/recipes/llama.rst:46
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/llama.rst:48
+msgid "**Meta-Llama-3.1-8B** (1 GPU):"
+msgstr "**Meta-Llama-3.1-8B** (1 GPU):"
+
+#: ../../source/recipes/llama.rst:59
+msgid "**Meta-Llama-3.1-8B-Instruct** (1 GPU):"
+msgstr "**Meta-Llama-3.1-8B-Instruct** (1 GPU):"
+
+#: ../../source/recipes/llama.rst:73
+msgid "**Meta-Llama-3.1-70B** (4 GPUs):"
+msgstr "**Meta-Llama-3.1-70B** (4 GPUs):"
+
+#: ../../source/recipes/llama.rst:85
+msgid "**Meta-Llama-3.1-70B-Instruct** (4 GPUs):"
+msgstr "**Meta-Llama-3.1-70B-Instruct** (4 GPUs):"
+
+#: ../../source/recipes/llama.rst:100
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/llama.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/llama.rst:106
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/llama.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/llama.rst:110
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/llama.rst:113
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/llama.rst:116
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/llama.rst:122
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/llama.rst:123
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/llama.rst:124
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/llama.rst:125
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/llama.rst:126
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/llama.rst:130
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/llama.rst:132
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "LlamaForCausalLM"
+#~ msgstr "LlamaForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/minimax_m2.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/minimax_m2.po
new file mode 100644
index 0000000..030e258
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/minimax_m2.po
@@ -0,0 +1,169 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/minimax_m2.rst:4
+msgid "MiniMax M2 series"
+msgstr "MiniMax M2 系列"
+
+#: ../../source/recipes/minimax_m2.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/minimax_m2.rst:9
+msgid "`MiniMaxAI/MiniMax-M2 <https://huggingface.co/MiniMaxAI/MiniMax-M2>`_"
+msgstr "`MiniMaxAI/MiniMax-M2 <https://huggingface.co/MiniMaxAI/MiniMax-M2>`_"
+
+#: ../../source/recipes/minimax_m2.rst:10
+msgid "`MiniMaxAI/MiniMax-M2.5 <https://huggingface.co/MiniMaxAI/MiniMax-M2.5>`_"
+msgstr "`MiniMaxAI/MiniMax-M2.5 <https://huggingface.co/MiniMaxAI/MiniMax-M2.5>`_"
+
+#: ../../source/recipes/minimax_m2.rst:11
+msgid "`MiniMaxAI/MiniMax-M2.7 <https://huggingface.co/MiniMaxAI/MiniMax-M2.7>`_"
+msgstr "`MiniMaxAI/MiniMax-M2.7 <https://huggingface.co/MiniMaxAI/MiniMax-M2.7>`_"
+
+#: ../../source/recipes/minimax_m2.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/minimax_m2.rst:18
+msgid ""
+"**Engine documentation:** `MiniMax-M2 in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``MiniMaxM2ForCausalLM``)."
+msgstr ""
+"**引擎文档：** `vLLM 支持的模型中的 MiniMax-M2 "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ （架构 ``MiniMaxM2ForCausalLM``）。"
+
+#: ../../source/recipes/minimax_m2.rst:23
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/minimax_m2.rst:25
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/minimax_m2.rst:33
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/minimax_m2.rst:35
+msgid "**MiniMax-M2** (8 GPUs):"
+msgstr "**MiniMax-M2** (8 GPUs):"
+
+#: ../../source/recipes/minimax_m2.rst:47
+msgid "**MiniMax-M2.5** (4 GPUs):"
+msgstr "**MiniMax-M2.5** (4 GPUs):"
+
+#: ../../source/recipes/minimax_m2.rst:62
+msgid "**MiniMax-M2.7** (4 GPUs):"
+msgstr "**MiniMax-M2.7** (4 GPUs):"
+
+#: ../../source/recipes/minimax_m2.rst:77
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/minimax_m2.rst:81
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr ""
+"如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/minimax_m2.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/minimax_m2.rst:87
+msgid ""
+"**Engine documentation:** `MiniMax-M2 SGLang cookbook "
+"<https://docs.sglang.io/cookbook/autoregressive/MiniMax/MiniMax-M2>`_, "
+"`MiniMax M2.5/M2.1/M2 usage guide "
+"<https://docs.sglang.io/docs/basic_usage/minimax_m2>`_."
+msgstr ""
+"**引擎文档：** `MiniMax-M2 SGLang 实战指南 "
+"<https://docs.sglang.io/cookbook/autoregressive/MiniMax/MiniMax-M2>`_，`MiniMax"
+" M2.5/M2.1/M2 使用指南 "
+"<https://docs.sglang.io/docs/basic_usage/minimax_m2>`_。"
+
+#: ../../source/recipes/minimax_m2.rst:93
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/minimax_m2.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/minimax_m2.rst:97
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/minimax_m2.rst:100
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/minimax_m2.rst:103
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/minimax_m2.rst:109
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/minimax_m2.rst:110
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/minimax_m2.rst:111
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/minimax_m2.rst:112
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/minimax_m2.rst:113
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/minimax_m2.rst:117
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/minimax_m2.rst:119
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "MiniMaxM2ForCausalLM"
+#~ msgstr "MiniMaxM2ForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/minimax_m3.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/minimax_m3.po
new file mode 100644
index 0000000..426ca32
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/minimax_m3.po
@@ -0,0 +1,140 @@
+# Chinese translations for LMCache package
+# LMCache 软件包的简体中文翻译.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# Automatically generated, 2026.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-25 19:26-0700\n"
+"PO-Revision-Date: 2026-06-25 19:26-0700\n"
+"Last-Translator: Automatically generated\n"
+"Language-Team: none\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Language: zh_CN\n"
+
+#: ../../source/recipes/minimax_m3.rst:4
+msgid "MiniMax M3"
+msgstr "MiniMax M3"
+
+#: ../../source/recipes/minimax_m3.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/minimax_m3.rst:9
+msgid "`MiniMaxAI/MiniMax-M3 <https://huggingface.co/MiniMaxAI/MiniMax-M3>`_"
+msgstr "`MiniMaxAI/MiniMax-M3 <https://huggingface.co/MiniMaxAI/MiniMax-M3>`_"
+
+#: ../../source/recipes/minimax_m3.rst:0
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/minimax_m3.rst:16
+msgid ""
+"**Engine documentation:** `MiniMax-M3 in vLLM supported models <https://"
+"docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_ "
+"(architecture ``MiniMaxM3SparseForConditionalGeneration``)."
+msgstr "**引擎文档：** `vLLM 支持模型中的 MiniMax-M3 <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_\\ （架构 ``MiniMaxM3SparseForConditionalGeneration``）。"
+
+#: ../../source/recipes/minimax_m3.rst:21
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/minimax_m3.rst:23
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/minimax_m3.rst:31
+msgid "Start vLLM with the LMCache MP connector (8 GPUs):"
+msgstr "使用 LMCache MP 连接器（8 个 GPU）启动 vLLM："
+
+#: ../../source/recipes/minimax_m3.rst:44
+msgid ""
+"``--block-size 128`` is **required** for this model (see Caveats); the "
+"smaller defaults fail vLLM's KV-cache init. ``--trust-remote-code`` loads "
+"M3's custom architecture. Adjust ``--tensor-parallel-size`` to your hardware "
+"— M3's weights need eight 140 GB-class GPUs. For the generic LMCache + vLLM "
+"wiring (ports, remote hosts), see :doc:`../getting_started/quickstart`."
+msgstr "对于该模型，``--block-size 128`` 是\\ **必需的**\\ （参见注意事项）；更小的默认值会导致 vLLM 的 KV Cache 初始化失败。``--trust-remote-code`` 用于加载 M3 的自定义架构。请根据您的硬件调整 ``--tensor-parallel-size`` —— M3 的权重需要八块 140 GB 级别的 GPU。有关 LMCache + vLLM 的通用连接配置（端口、远程主机），请参见 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/minimax_m3.rst:51
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ for more "
+"details."
+msgstr "如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/minimax_m3.rst:0
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/minimax_m3.rst:57
+#: ../../source/recipes/minimax_m3.rst:61
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/minimax_m3.rst:0
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/minimax_m3.rst:64
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/minimax_m3.rst:67
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/minimax_m3.rst:73
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/minimax_m3.rst:74
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/minimax_m3.rst:75
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/minimax_m3.rst:76
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/minimax_m3.rst:77
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/minimax_m3.rst:81
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/minimax_m3.rst:83
+msgid ""
+"**Sparse attention with a lightning indexer.** M3 runs grouped-query full "
+"attention plus a DeepSeek-style sparse-attention indexer. Each sparse layer "
+"owns two paged caches — the main K/V (rank-5) and a key-only indexer cache "
+"(rank-3) — which vLLM places in a single ``UniformTypeKVCacheSpecs`` engine "
+"group. LMCache detects both layouts and stores/retrieves each as its own "
+"group; the indexer keys travel with the K/V because they cannot be "
+"recomputed from the cached K/V on a hit."
+msgstr "**基于 lightning indexer 的稀疏注意力。** M3 运行分组查询（grouped-query）全注意力，外加 DeepSeek 风格的稀疏注意力索引器。每个稀疏层拥有两个分页缓存——主 K/V（rank-5）和仅含 key 的索引器缓存（rank-3）——vLLM 将它们放在单个 ``UniformTypeKVCacheSpecs`` 引擎组中。LMCache 会检测这两种布局，并将每一种作为独立的组进行存储/检索；索引器的 key 会随 K/V 一起传输，因为命中时无法从已缓存的 K/V 重新计算出它们。"
+
+#: ../../source/recipes/minimax_m3.rst:90
+msgid ""
+"**``--block-size 128`` is required.** M3's indexer uses ``sparse_block_size "
+"= 128``; vLLM cannot reconcile the default block size (16) or 64 across the "
+"full-attention and sparse kernels and aborts KV-cache init with ``No common "
+"block size``. Use 128."
+msgstr "**``--block-size 128`` 是必需的。** M3 的索引器使用 ``sparse_block_size = 128``；vLLM 无法在全注意力内核与稀疏内核之间协调默认块大小（16）或 64，并会以 ``No common block size`` 中止 KV Cache 初始化。请使用 128。"
+
+#: ../../source/recipes/minimax_m3.rst:94
+msgid ""
+"**LMCache chunk size must be a multiple of the block size.** The default "
+"chunk size (256) already satisfies 128, so no extra flag is needed; if you "
+"pass ``--chunk-size`` to the server, keep it a multiple of 128."
+msgstr "**LMCache 的 chunk 大小必须是 block 大小的整数倍。** 默认的 chunk 大小（256）已满足 128，因此无需额外的标志；如果您向服务器传入 ``--chunk-size``，请保持它是 128 的整数倍。"
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/mixtral.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/mixtral.po
new file mode 100644
index 0000000..c23ebb7
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/mixtral.po
@@ -0,0 +1,148 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/mixtral.rst:4
+msgid "Mixtral"
+msgstr "Mixtral"
+
+#: ../../source/recipes/mixtral.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/mixtral.rst:9
+msgid ""
+"`mistralai/Mixtral-8x7B-v0.1 <https://huggingface.co/mistralai/Mixtral-"
+"8x7B-v0.1>`_"
+msgstr ""
+"`mistralai/Mixtral-8x7B-v0.1 <https://huggingface.co/mistralai/Mixtral-"
+"8x7B-v0.1>`_"
+
+#: ../../source/recipes/mixtral.rst:10
+msgid ""
+"`mistralai/Mixtral-8x7B-Instruct-v0.1 <https://huggingface.co/mistralai"
+"/Mixtral-8x7B-Instruct-v0.1>`_"
+msgstr ""
+"`mistralai/Mixtral-8x7B-Instruct-v0.1 <https://huggingface.co/mistralai"
+"/Mixtral-8x7B-Instruct-v0.1>`_"
+
+#: ../../source/recipes/mixtral.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/mixtral.rst:17
+msgid ""
+"**Engine documentation:** `MixtralForCausalLM in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture `MixtralForCausalLM`)."
+msgstr ""
+"**引擎文档：** `vLLM 支持的模型中的 MixtralForCausalLM "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ （架构 `MixtralForCausalLM`）。"
+
+#: ../../source/recipes/mixtral.rst:22
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/mixtral.rst:24
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/mixtral.rst:32
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/mixtral.rst:34
+msgid "**Mixtral-8x7B-v0.1** (4 GPUs):"
+msgstr "**Mixtral-8x7B-v0.1** (4 GPUs):"
+
+#: ../../source/recipes/mixtral.rst:46
+msgid "**Mixtral-8x7B-Instruct-v0.1** (4 GPUs):"
+msgstr "**Mixtral-8x7B-Instruct-v0.1** (4 GPUs):"
+
+#: ../../source/recipes/mixtral.rst:60
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/mixtral.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/mixtral.rst:66
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/mixtral.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/mixtral.rst:70
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/mixtral.rst:73
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/mixtral.rst:76
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/mixtral.rst:82
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/mixtral.rst:83
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/mixtral.rst:84
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/mixtral.rst:85
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/mixtral.rst:86
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/mixtral.rst:90
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/mixtral.rst:92
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "MixtralForCausalLM"
+#~ msgstr "MixtralForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/phi3.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/phi3.po
new file mode 100644
index 0000000..8037f44
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/phi3.po
@@ -0,0 +1,148 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/phi3.rst:4
+msgid "Phi-3 / Phi-4"
+msgstr "Phi-3 / Phi-4"
+
+#: ../../source/recipes/phi3.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/phi3.rst:9
+msgid ""
+"`microsoft/Phi-4-mini-instruct <https://huggingface.co/microsoft/Phi-4"
+"-mini-instruct>`_"
+msgstr ""
+"`microsoft/Phi-4-mini-instruct <https://huggingface.co/microsoft/Phi-4"
+"-mini-instruct>`_"
+
+#: ../../source/recipes/phi3.rst:10
+msgid ""
+"`microsoft/Phi-3-medium-128k-instruct "
+"<https://huggingface.co/microsoft/Phi-3-medium-128k-instruct>`_"
+msgstr ""
+"`microsoft/Phi-3-medium-128k-instruct "
+"<https://huggingface.co/microsoft/Phi-3-medium-128k-instruct>`_"
+
+#: ../../source/recipes/phi3.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/phi3.rst:17
+msgid ""
+"**Engine documentation:** `Phi3ForCausalLM in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture `Phi3ForCausalLM`)."
+msgstr ""
+"**引擎文档：** `vLLM 支持的模型中的 Phi3ForCausalLM "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ （架构 `Phi3ForCausalLM`）。"
+
+#: ../../source/recipes/phi3.rst:22
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/phi3.rst:24
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/phi3.rst:32
+msgid "Start vLLM with the LMCache MP connector:"
+msgstr "使用 LMCache MP 连接器启动 vLLM："
+
+#: ../../source/recipes/phi3.rst:34
+msgid "**Phi-4-mini-instruct** (1 GPU):"
+msgstr "**Phi-4-mini-instruct** (1 GPU):"
+
+#: ../../source/recipes/phi3.rst:47
+msgid "**Phi-3-medium-128k-instruct** (1 GPU):"
+msgstr "**Phi-3-medium-128k-instruct** (1 GPU):"
+
+#: ../../source/recipes/phi3.rst:58
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/phi3.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/phi3.rst:64
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/phi3.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/phi3.rst:68
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/phi3.rst:71
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/phi3.rst:74
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/phi3.rst:80
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/phi3.rst:81
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/phi3.rst:82
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/phi3.rst:83
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/phi3.rst:84
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/phi3.rst:88
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/phi3.rst:90
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "Phi3ForCausalLM"
+#~ msgstr "Phi3ForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/qwen3.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/qwen3.po
new file mode 100644
index 0000000..11e5b08
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/qwen3.po
@@ -0,0 +1,169 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/qwen3.rst:4
+msgid "Qwen3 MoE"
+msgstr "Qwen3 MoE"
+
+#: ../../source/recipes/qwen3.rst:7
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/qwen3.rst:9
+msgid "`Qwen/Qwen3-235B-A22B <https://huggingface.co/Qwen/Qwen3-235B-A22B>`_"
+msgstr "`Qwen/Qwen3-235B-A22B <https://huggingface.co/Qwen/Qwen3-235B-A22B>`_"
+
+#: ../../source/recipes/qwen3.rst:10
+msgid "`Qwen/Qwen3-30B-A3B <https://huggingface.co/Qwen/Qwen3-30B-A3B>`_"
+msgstr "`Qwen/Qwen3-30B-A3B <https://huggingface.co/Qwen/Qwen3-30B-A3B>`_"
+
+#: ../../source/recipes/qwen3.rst:11
+msgid ""
+"`Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 "
+"<https://huggingface.co/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8>`_"
+msgstr ""
+"`Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 "
+"<https://huggingface.co/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8>`_"
+
+#: ../../source/recipes/qwen3.rst:12
+msgid ""
+"`Qwen/Qwen3-Coder-30B-A3B-Instruct <https://huggingface.co/Qwen/Qwen3"
+"-Coder-30B-A3B-Instruct>`_"
+msgstr ""
+"`Qwen/Qwen3-Coder-30B-A3B-Instruct <https://huggingface.co/Qwen/Qwen3"
+"-Coder-30B-A3B-Instruct>`_"
+
+#: ../../source/recipes/qwen3.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/qwen3.rst:19
+msgid ""
+"**Engine documentation:** `Qwen3 MoE in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``Qwen3MoeForCausalLM``)."
+msgstr ""
+"**引擎文档:** `vLLM 支持的 Qwen3 MoE 模型 "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (架构 ``Qwen3MoeForCausalLM``)。"
+
+#: ../../source/recipes/qwen3.rst:24
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/qwen3.rst:26
+msgid "Start the LMCache MP server:"
+msgstr "启动 LMCache MP 服务器："
+
+#: ../../source/recipes/qwen3.rst:34
+msgid "**Qwen3-235B-A22B** (4 GPUs, expert parallel):"
+msgstr "**Qwen3-235B-A22B**\\ （4 个 GPU，专家并行）："
+
+#: ../../source/recipes/qwen3.rst:49
+msgid "**Qwen3-30B-A3B** (1 GPU):"
+msgstr "**Qwen3-30B-A3B**\\ （1 个 GPU）："
+
+#: ../../source/recipes/qwen3.rst:62
+msgid "**Qwen3-Coder-480B-A35B-Instruct-FP8** (8 GPUs, expert parallel):"
+msgstr "**Qwen3-Coder-480B-A35B-Instruct-FP8**\\ （8 个 GPU，专家并行）："
+
+#: ../../source/recipes/qwen3.rst:76
+msgid "**Qwen3-Coder-30B-A3B-Instruct** (1 GPU):"
+msgstr "**Qwen3-Coder-30B-A3B-Instruct**\\ （1 个 GPU）："
+
+#: ../../source/recipes/qwen3.rst:88
+msgid ""
+"Adjust ``--tensor-parallel-size`` to match your hardware. For the generic"
+" LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr ""
+"调整 ``--tensor-parallel-size`` 以匹配您的硬件。有关通用 LMCache + vLLM 连接（端口、远程主机），请参见"
+" :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/qwen3.rst:92
+msgid ""
+"If there are any issues with vLLM setup, please refer to the `vLLM "
+"Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ "
+"for more details."
+msgstr ""
+"如果在 vLLM 设置中遇到任何问题，请参考 `vLLM Recipes "
+"<https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_ 以获取更多详细信息。"
+
+#: ../../source/recipes/qwen3.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/qwen3.rst:98
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/qwen3.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/qwen3.rst:102
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/qwen3.rst:105
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/qwen3.rst:108
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/qwen3.rst:114
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/qwen3.rst:115
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/qwen3.rst:116
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/qwen3.rst:117
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/qwen3.rst:118
+msgid "Not validated"
+msgstr "未验证"
+
+#: ../../source/recipes/qwen3.rst:122
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/qwen3.rst:124
+msgid "None known."
+msgstr "没有已知的问题。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "Qwen3MoeForCausalLM"
+#~ msgstr "Qwen3MoeForCausalLM"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/qwen3_5.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/qwen3_5.po
new file mode 100644
index 0000000..d08229e
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/qwen3_5.po
@@ -0,0 +1,262 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/qwen3_5.rst:4
+msgid "Qwen3.5 / Qwen3.6 series"
+msgstr "Qwen3.5 / Qwen3.6 系列"
+
+#: ../../source/recipes/qwen3_5.rst:6
+msgid ""
+"A hybrid architecture interleaving Mamba / Gated-DeltaNet (GDN) linear-"
+"attention layers with full-attention layers, shared by the **Qwen3.5 and "
+"Qwen3.6** series. LMCache reinterprets the recurrent state caches as "
+"opaque pages at registration time; see :doc:`../mp/hybrid_models` for the"
+" general handling of Mamba / linear-attention models."
+msgstr "一种混合架构，将 Mamba / Gated-DeltaNet (GDN) linear-attention 层与 full-attention 层交错，供 **Qwen3.5 和 Qwen3.6** 系列共享。LMCache 在注册时将递归状态缓存重新解释为不透明页面；有关 Mamba / linear-attention 模型的一般处理，请参见 :doc:`../mp/hybrid_models`。"
+
+#: ../../source/recipes/qwen3_5.rst:13
+msgid "Validated models"
+msgstr "验证过的模型"
+
+#: ../../source/recipes/qwen3_5.rst:15
+msgid "`Qwen/Qwen3.6-27B <https://huggingface.co/Qwen/Qwen3.6-27B>`_ (1 GPU)"
+msgstr "`Qwen/Qwen3.6-27B <https://huggingface.co/Qwen/Qwen3.6-27B>`_ (1 GPU)"
+
+#: ../../source/recipes/qwen3_5.rst:16
+msgid "`Qwen/Qwen3.5-0.8B <https://huggingface.co/Qwen/Qwen3.5-0.8B>`_ (1 GPU)"
+msgstr "`Qwen/Qwen3.5-0.8B <https://huggingface.co/Qwen/Qwen3.5-0.8B>`_ (1 GPU)"
+
+#: ../../source/recipes/qwen3_5.rst
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/qwen3_5.rst:23
+msgid ""
+"**Engine documentation:** `Qwen3.5 in vLLM supported models "
+"<https://docs.vllm.ai/en/latest/models/supported_models.html#text-"
+"generation>`_ (architecture ``Qwen3_5ForConditionalGeneration``)."
+msgstr "**引擎文档：** `vLLM 支持的模型中的 Qwen3.5 <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_\\ （架构 ``Qwen3_5ForConditionalGeneration``\\ ）。"
+
+#: ../../source/recipes/qwen3_5.rst:28
+msgid "**Status:** Validated with LMCache."
+msgstr "**状态:** 已通过 LMCache 验证。"
+
+#: ../../source/recipes/qwen3_5.rst:30
+msgid ""
+"Every model in this family needs the same three settings: the ``align`` "
+"Mamba cache mode, prefix caching, and a chunk size matched to vLLM's "
+"*unified block size*. That block size is model-specific — vLLM logs "
+"``Setting attention block size to N tokens`` at startup:"
+msgstr "该系列中的每个模型都需要相同的三项设置：\\ ``align`` Mamba 缓存模式、前缀缓存，以及与 vLLM 的统一块大小匹配的分块大小。该块大小因模型而异——vLLM 在启动时会输出 ``Setting attention block size to N tokens``\\ ："
+
+#: ../../source/recipes/qwen3_5.rst:39
+msgid "Model"
+msgstr "模型"
+
+#: ../../source/recipes/qwen3_5.rst:40
+msgid "Unified block size ``N``"
+msgstr "统一块大小 ``N``"
+
+#: ../../source/recipes/qwen3_5.rst:41
+msgid "GPUs"
+msgstr "GPU"
+
+#: ../../source/recipes/qwen3_5.rst:42
+msgid "``Qwen/Qwen3.6-27B``"
+msgstr "``Qwen/Qwen3.6-27B``"
+
+#: ../../source/recipes/qwen3_5.rst:43
+msgid "784"
+msgstr "784"
+
+#: ../../source/recipes/qwen3_5.rst:44 ../../source/recipes/qwen3_5.rst:47
+msgid "1"
+msgstr "1"
+
+#: ../../source/recipes/qwen3_5.rst:45
+msgid "``Qwen/Qwen3.5-0.8B``"
+msgstr "``Qwen/Qwen3.5-0.8B``"
+
+#: ../../source/recipes/qwen3_5.rst:46
+msgid "544"
+msgstr "544"
+
+#: ../../source/recipes/qwen3_5.rst:49
+msgid ""
+"Set the LMCache server's ``--chunk-size`` to that ``N`` (or a multiple of"
+" it), and vLLM's ``--max-num-batched-tokens`` to ``2N-1`` (the largest "
+"value below ``2N``). ``N`` is also valid but serializes prefill under "
+"load — see the note below."
+msgstr "将 LMCache 服务器的 ``--chunk-size`` 设置为 ``N``\\ （或其倍数），并将 vLLM 的 ``--max-num-batched-tokens`` 设置为 ``2N-1``\\ （小于 ``2N`` 的最大值）。\\ ``N`` 也有效，但在高负载下会使预填充串行化——请参阅下方说明。"
+
+#: ../../source/recipes/qwen3_5.rst:54
+msgid "**Qwen3.6-27B** (1 GPU, ``N = 784`` → ``2N-1 = 1567``):"
+msgstr "**Qwen3.6-27B** (1 GPU, ``N = 784`` → ``2N-1 = 1567``):"
+
+#: ../../source/recipes/qwen3_5.rst:71
+msgid ""
+"**Qwen3.5-0.8B** (1 GPU, ``N = 544`` → ``2N-1 = 1087``): identical to the"
+" above, with ``--chunk-size 544`` and ``--max-num-batched-tokens 1087``."
+msgstr "**Qwen3.5-0.8B** (1 GPU, ``N = 544`` → ``2N-1 = 1087``): 与上述相同，使用 ``--chunk-size 544`` 和 ``--max-num-batched-tokens 1087``\\ 。"
+
+#: ../../source/recipes/qwen3_5.rst:74
+#, python-format
+msgid ""
+"``--mamba-cache-mode align`` is required (GDN does not support the "
+"``all`` mode). ``--max-num-batched-tokens`` must be in ``[N, 2N)`` (at "
+"least the unified block size and below twice it) — LMCache raises at "
+"engine startup otherwise. ``align`` snapshots the Mamba state at "
+"scheduler-step ends on a block boundary, and the scheduler splits "
+"prefills into whole ``N``-token blocks. **Prefer the maximum, ``2N-1``:**"
+" a single request still advances exactly one block per step (``2N-1 < "
+"2N``), so the per-block snapshot LMCache stores is preserved, *and* the "
+"spare ``N-1`` budget lets decodes co-schedule with a prefill block. "
+"Setting it to exactly ``N`` makes the per-step budget equal to one block,"
+" so once any request is decoding (consuming ≥1 token of the budget) no "
+"new request can start prefill — execution serializes to one request at a "
+"time. (Benchmarked on Qwen3.6-27B: at ``N`` a cold / low-hit run ran ~7× "
+"slower with GPU batch stuck at 1; ``2N-1`` restored full batching. With a"
+" warm LMCache cache (~97 % hit) the gap is small since little prefill "
+"remains, but ``2N-1`` is the safe default.) If vLLM reports "
+"*\"max_num_seqs exceeds available Mamba cache blocks\"* at ``2N-1``, "
+"lower ``--max-num-seqs`` to ≤ that count (each decode sequence needs one "
+"Mamba block) or raise ``--gpu-memory-utilization``."
+msgstr "``--mamba-cache-mode align`` 是必需的（GDN 不支持 ``all`` 模式）。\\ ``--max-num-batched-tokens`` 必须在 ``[N, 2N)`` 范围内（至少为统一块大小，且不超过其两倍）——否则 LMCache 在引擎启动时会报错。\\ ``align`` 在调度器步骤结束时于块边界处快照 Mamba 状态，调度器将预填充拆分为完整的 ``N``-token 块。\\ **优先选择最大值 ``2N-1``\\ ：** 单个请求在每个步骤中仍会精确推进一个块（\\ ``2N-1 < 2N``\\ ），因此 LMCache 存储的逐块快照得以保留，同时剩余的 ``N-1`` 预算允许解码与预填充块并发调度。将其设置为恰好 ``N`` 会使每步预算等于一个块，因此一旦任何请求进入解码阶段（消耗 ≥1 个 token 的预算），就无法启动新的预填充请求——执行退化为每次只处理一个请求。（在 Qwen3.6-27B 上的基准测试：取值 ``N`` 时，冷启动 / 低命中率场景慢约 7 倍，GPU 批大小卡在 1；取 ``2N-1`` 后恢复完整批处理。在 LMCache 缓存已预热（约 97% 命中率）的情况下，差距较小，因为剩余的预填充量很少，但 ``2N-1`` 仍是推荐的安全默认值。）若 vLLM 在 ``2N-1`` 时报告 *\\\"max_num_seqs exceeds available Mamba cache blocks\\\"*，请将 ``--max-num-seqs`` 降低到 ≤ 该数量（每个解码序列需要一个 Mamba 块），或提高 ``--gpu-memory-utilization``\\ 。"
+
+#: ../../source/recipes/qwen3_5.rst:93
+msgid ""
+"For the generic LMCache + vLLM wiring (ports, remote hosts), see "
+":doc:`../getting_started/quickstart`."
+msgstr "有关通用 LMCache + vLLM 连接（端口、远程主机），请参见 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/qwen3_5.rst
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/qwen3_5.rst:98
+msgid "**Status:** Not validated with LMCache."
+msgstr "**状态：** 未通过 LMCache 验证。"
+
+#: ../../source/recipes/qwen3_5.rst
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/qwen3_5.rst:102
+msgid ""
+"**Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-"
+"LLM + LMCache setup."
+msgstr "**状态：** 支持。TRT-LLM + LMCache 的配置方式，请参阅 :doc:`../getting_started/quickstart`。"
+
+#: ../../source/recipes/qwen3_5.rst:105
+msgid "CacheBlend support"
+msgstr "CacheBlend 支持"
+
+#: ../../source/recipes/qwen3_5.rst:107
+msgid ""
+"Not supported: the hybrid groups' cached pages are byte-opaque (see "
+"Caveats)."
+msgstr "不支持：混合组的缓存页面是字节不透明的（请参见注意事项）。"
+
+#: ../../source/recipes/qwen3_5.rst:110
+msgid "Compression support"
+msgstr "压缩支持"
+
+#: ../../source/recipes/qwen3_5.rst:116
+msgid "Method"
+msgstr "方法"
+
+#: ../../source/recipes/qwen3_5.rst:117
+msgid "Status"
+msgstr "状态"
+
+#: ../../source/recipes/qwen3_5.rst:118
+msgid "Notes"
+msgstr "备注"
+
+#: ../../source/recipes/qwen3_5.rst:119
+msgid ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+msgstr ":doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`"
+
+#: ../../source/recipes/qwen3_5.rst:120
+msgid "Not supported"
+msgstr "不支持"
+
+#: ../../source/recipes/qwen3_5.rst:121
+msgid "Hybrid groups' cached pages are byte-opaque."
+msgstr "混合组的缓存页面是字节不透明的。"
+
+#: ../../source/recipes/qwen3_5.rst:124
+msgid "Caveats"
+msgstr "注意事项"
+
+#: ../../source/recipes/qwen3_5.rst:126
+msgid ""
+"Generation is **not bit-exact** between a cached and a fresh run: GDN "
+"backends do not support vLLM's batch-invariant mode. Expect score-level "
+"equivalence, not token-level (the CI gate is the ``hma_lm_eval_qwen3_5`` "
+"gsm8k store-vs-retrieve comparison)."
+msgstr "缓存运行与全新运行的生成结果\\ **不保证逐位一致**\\ ：GDN 后端不支持 vLLM 的批不变模式。预期结果在得分层面等价，而非 token 层面严格一致（CI 验证门为 ``hma_lm_eval_qwen3_5`` gsm8k 存储与检索对比）。"
+
+#: ../../source/recipes/qwen3_5.rst:130
+msgid ""
+"Cached pages for the Mamba and full-attention groups are byte-opaque "
+"views, so content-aware processing does not apply, and cache entries must"
+" not be shared across engines with different attention backends or kernel"
+" block sizes."
+msgstr "Mamba 和 full-attention 组的缓存页面是字节不透明视图，因此不适用内容感知处理，缓存条目不得在具有不同注意力后端或内核块大小的引擎之间共享。"
+
+#: ../../source/recipes/qwen3_5.rst:134
+msgid "vLLM's Mamba prefix caching in ``align`` mode is experimental."
+msgstr "vLLM 的 Mamba 前缀缓存在 ``align`` 模式下属于实验性功能。"
+
+#: ../../source/recipes/qwen3_5.rst:135
+msgid ""
+"``Qwen/Qwen3.6-27B`` is a vision-language model (it loads a vision "
+"tower); the LMCache validation covers **text** generation (the "
+"``hma_lm_eval_qwen3_5`` gsm8k store-vs-retrieve gate). Caching of "
+"image/video KV is not validated."
+msgstr "``Qwen/Qwen3.6-27B`` 是一个视觉语言模型（它加载一个视觉塔）；LMCache 验证涵盖 **文本** 生成（\\ ``hma_lm_eval_qwen3_5`` gsm8k 存取门）。图像/视频 KV 的缓存未经过验证。"
+
+#~ msgid ""
+#~ "``--mamba-cache-mode align`` is required"
+#~ " (GDN does not support the ``all``"
+#~ " mode). ``--max-num-batched-tokens`` "
+#~ "must be at least the unified block"
+#~ " size and below twice it — "
+#~ "LMCache raises at engine startup "
+#~ "otherwise. ``align`` snapshots the Mamba "
+#~ "state only at scheduler-step ends, "
+#~ "so each prefill step must advance "
+#~ "exactly one block for every block "
+#~ "boundary to hold a reusable snapshot."
+#~ msgstr ""
+#~ "``--mamba-cache-mode align`` 是必需的（GDN "
+#~ "不支持 ``all`` 模式）。``--max-num-batched-"
+#~ "tokens`` 必须至少等于统一块大小，并且小于其两倍——否则 LMCache "
+#~ "在引擎启动时会引发错误。``align`` 仅在调度器步骤结束时快照 Mamba 状态，因此每个 "
+#~ "Prefill 步骤必须精确推进一个块，以保持可重用的快照。"
+
+#~ msgid "**Status:** Not supported. LMCache TRT-LLM integration is in progress."
+#~ msgstr "**状态：** 不支持。LMCache TRT-LLM 集成正在进行中。"
+
+#~ msgid "Qwen3_5ForConditionalGeneration"
+#~ msgstr "Qwen3_5ForConditionalGeneration"
+
diff --git a/docs/source/locale/zh_CN/LC_MESSAGES/recipes/uniform_attention_models.po b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/uniform_attention_models.po
new file mode 100644
index 0000000..149ef76
--- /dev/null
+++ b/docs/source/locale/zh_CN/LC_MESSAGES/recipes/uniform_attention_models.po
@@ -0,0 +1,268 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2024, The LMCache Team
+# This file is distributed under the same license as the LMCache package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2026.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: LMCache \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-22 11:07+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: zh_CN\n"
+"Language-Team: zh_CN <LL@li.org>\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.18.0\n"
+
+#: ../../source/recipes/uniform_attention_models.rst:4
+msgid "Uniform Attention Models"
+msgstr "Uniform Attention 模型"
+
+#: ../../source/recipes/uniform_attention_models.rst:6
+msgid ""
+"Recipes for standard (uniform) attention transformer architectures "
+"validated end-to-end with LMCache, with a recipe page per architecture "
+"covering only the LMCache-specific configuration that diverges from "
+"defaults."
+msgstr "针对采用标准（uniform）attention 的 Transformer 架构的配方，均已通过 LMCache 端到端验证；每种架构对应一个配方页面，仅涵盖与默认配置不同的 LMCache 专项配置。"
+
+#: ../../source/recipes/uniform_attention_models.rst:10
+msgid ""
+"These models use a **single attention type** across all layers, so vLLM "
+"serves them with one KV cache group. Models that interleave multiple "
+"attention types (sliding-window + full, or Mamba / linear-attention + "
+"full) are covered under :doc:`/mp/hybrid_models`."
+msgstr "这些模型在所有层中使用 **单一注意力类型**\\ ，因此 vLLM 使用一个 KV 缓存组为其提供服务。交错使用多种注意力类型的模型（sliding window attention + full attention，或 Mamba / linear attention + full attention）请参见 :doc:`/mp/hybrid_models`。"
+
+#: ../../source/recipes/uniform_attention_models.rst:16
+msgid "Recipe page contents"
+msgstr "配方页面内容"
+
+#: ../../source/recipes/uniform_attention_models.rst:18
+msgid "Each recipe page is intentionally minimal:"
+msgstr "每个配方页面均刻意保持简洁："
+
+#: ../../source/recipes/uniform_attention_models.rst:20
+msgid "**Validated models** -- exact HF repo IDs that have been tested."
+msgstr "**验证过的模型** -- 已测试的确切 HF 仓库 ID。"
+
+#: ../../source/recipes/uniform_attention_models.rst:21
+msgid ""
+"**Engine tabs** -- one tab per serving engine (vLLM, SGLang, TRT-LLM). "
+"Each tab links to the engine's own documentation for the model and shows "
+"the exact ``lmcache server`` and engine launch commands. Tabs for engines"
+" that are not yet validated state so explicitly."
+msgstr "**引擎选项卡** -- 每个推理引擎（vLLM、SGLang、TRT-LLM）各对应一个选项卡。每个选项卡链接至该引擎的模型文档，并给出 ``lmcache server`` 和引擎启动命令的完整示例。尚未完成验证的引擎会在选项卡中明确说明。"
+
+#: ../../source/recipes/uniform_attention_models.rst:25
+msgid "**CacheBlend support** -- validation status (may be empty)."
+msgstr "**CacheBlend 支持** -- 验证状态（可能为空）。"
+
+#: ../../source/recipes/uniform_attention_models.rst:26
+msgid ""
+"**Compression support** -- table of compression methods (CacheGen, etc.) "
+"with per-method validation status. Extensible: new methods get a row."
+msgstr "**压缩支持** -- 列出各压缩方法（CacheGen 等）及其验证状态的表格，支持扩展：新方法可直接新增一行。"
+
+#: ../../source/recipes/uniform_attention_models.rst:28
+msgid "**Caveats** -- known limitations, if any."
+msgstr "**注意事项** -- 已知的限制（如果有的话）。"
+
+#: ../../source/recipes/uniform_attention_models.rst:30
+msgid ""
+"For the generic LMCache + engine wiring (ports, remote hosts, sending a "
+"first request), see :doc:`../getting_started/quickstart`. Recipes assume "
+"that page as a prerequisite."
+msgstr "有关 LMCache 与推理引擎的通用接入配置（端口、远程主机、发送首个请求），请参见 :doc:`../getting_started/quickstart`。本节配方均以该页面为前置阅读。"
+
+#: ../../source/recipes/uniform_attention_models.rst:35
+msgid "Supported architectures"
+msgstr "支持的架构"
+
+#: ../../source/recipes/uniform_attention_models.rst:41
+msgid "Model"
+msgstr "模型"
+
+#: ../../source/recipes/uniform_attention_models.rst:42
+msgid "Example HF model"
+msgstr "示例 HF 模型"
+
+#: ../../source/recipes/uniform_attention_models.rst:43
+msgid "vLLM"
+msgstr "vLLM"
+
+#: ../../source/recipes/uniform_attention_models.rst:44
+msgid "SGLang"
+msgstr "SGLang"
+
+#: ../../source/recipes/uniform_attention_models.rst:45
+msgid "TRT-LLM"
+msgstr "TRT-LLM"
+
+#: ../../source/recipes/uniform_attention_models.rst:46
+msgid "Recipe"
+msgstr "配方"
+
+#: ../../source/recipes/uniform_attention_models.rst:48
+msgid "MiniMax M2 series"
+msgstr "MiniMax M2 系列"
+
+#: ../../source/recipes/uniform_attention_models.rst:49
+msgid "``MiniMaxAI/MiniMax-M2``"
+msgstr "``MiniMaxAI/MiniMax-M2``"
+
+#: ../../source/recipes/uniform_attention_models.rst:50
+#: ../../source/recipes/uniform_attention_models.rst:57
+#: ../../source/recipes/uniform_attention_models.rst:64
+#: ../../source/recipes/uniform_attention_models.rst:71
+#: ../../source/recipes/uniform_attention_models.rst:78
+#: ../../source/recipes/uniform_attention_models.rst:85
+msgid "✓"
+msgstr "✓"
+
+#: ../../source/recipes/uniform_attention_models.rst:51
+#: ../../source/recipes/uniform_attention_models.rst:52
+#: ../../source/recipes/uniform_attention_models.rst:58
+#: ../../source/recipes/uniform_attention_models.rst:59
+#: ../../source/recipes/uniform_attention_models.rst:65
+#: ../../source/recipes/uniform_attention_models.rst:66
+#: ../../source/recipes/uniform_attention_models.rst:72
+#: ../../source/recipes/uniform_attention_models.rst:73
+#: ../../source/recipes/uniform_attention_models.rst:79
+#: ../../source/recipes/uniform_attention_models.rst:80
+#: ../../source/recipes/uniform_attention_models.rst:86
+#: ../../source/recipes/uniform_attention_models.rst:87
+msgid "—"
+msgstr "—"
+
+#: ../../source/recipes/uniform_attention_models.rst:53
+msgid ":doc:`minimax_m2`"
+msgstr ":doc:`minimax_m2`"
+
+#: ../../source/recipes/uniform_attention_models.rst:55
+msgid "Mistral / Devstral"
+msgstr "Mistral / Devstral"
+
+#: ../../source/recipes/uniform_attention_models.rst:56
+msgid "``mistralai/Devstral-2-123B-Instruct-2512``"
+msgstr "``mistralai/Devstral-2-123B-Instruct-2512``"
+
+#: ../../source/recipes/uniform_attention_models.rst:60
+msgid ":doc:`devstral`"
+msgstr ":doc:`devstral`"
+
+#: ../../source/recipes/uniform_attention_models.rst:62
+msgid "Qwen3 MoE"
+msgstr "Qwen3 MoE"
+
+#: ../../source/recipes/uniform_attention_models.rst:63
+msgid "``Qwen/Qwen3-235B-A22B``"
+msgstr "``Qwen/Qwen3-235B-A22B``"
+
+#: ../../source/recipes/uniform_attention_models.rst:67
+msgid ":doc:`qwen3`"
+msgstr ":doc:`qwen3`"
+
+#: ../../source/recipes/uniform_attention_models.rst:69
+msgid "Llama"
+msgstr "Llama"
+
+#: ../../source/recipes/uniform_attention_models.rst:70
+msgid "``meta-llama/Meta-Llama-3.1-70B-Instruct``"
+msgstr "``meta-llama/Meta-Llama-3.1-70B-Instruct``"
+
+#: ../../source/recipes/uniform_attention_models.rst:74
+msgid ":doc:`llama`"
+msgstr ":doc:`llama`"
+
+#: ../../source/recipes/uniform_attention_models.rst:76
+msgid "Phi-3 / Phi-4"
+msgstr "Phi-3 / Phi-4"
+
+#: ../../source/recipes/uniform_attention_models.rst:77
+msgid "``microsoft/Phi-4-mini-instruct``"
+msgstr "``microsoft/Phi-4-mini-instruct``"
+
+#: ../../source/recipes/uniform_attention_models.rst:81
+msgid ":doc:`phi3`"
+msgstr ":doc:`phi3`"
+
+#: ../../source/recipes/uniform_attention_models.rst:83
+msgid "Mixtral"
+msgstr "Mixtral"
+
+#: ../../source/recipes/uniform_attention_models.rst:84
+msgid "``mistralai/Mixtral-8x7B-Instruct-v0.1``"
+msgstr "``mistralai/Mixtral-8x7B-Instruct-v0.1``"
+
+#: ../../source/recipes/uniform_attention_models.rst:88
+msgid ":doc:`mixtral`"
+msgstr ":doc:`mixtral`"
+
+#: ../../source/recipes/uniform_attention_models.rst:90
+msgid ""
+"Legend: ``✓`` validated, ``—`` not validated. The **Model** column is the"
+" model family; each recipe page lists the exact vLLM architecture class "
+"it covers."
+msgstr "图例：``✓`` 已验证，``—`` 未验证。**模型**\\ 列是模型系列；每个食谱页面列出了它所涵盖的确切 vLLM 架构类。"
+
+#: ../../source/recipes/uniform_attention_models.rst:94
+msgid "Contributing a recipe"
+msgstr "贡献配方"
+
+#: ../../source/recipes/uniform_attention_models.rst:96
+msgid "To add a new uniform-attention architecture:"
+msgstr "要新增一种 uniform attention 架构的配方："
+
+#: ../../source/recipes/uniform_attention_models.rst:98
+msgid ""
+"Copy an existing page (e.g. ``minimax_m2.rst``) to "
+"``recipes/<architecture_snake_case>.rst``."
+msgstr "将现有页面（如 ``minimax_m2.rst``\\ ）复制为 ``recipes/<architecture_snake_case>.rst``\\ 。"
+
+#: ../../source/recipes/uniform_attention_models.rst:100
+msgid ""
+"Fill in **Validated models**, **Engines**, **LMCache configuration**, and"
+" **Caveats**. Keep each section terse -- if a field has nothing to say, "
+"say so in one line rather than padding it."
+msgstr "填写 **验证过的模型**\\ 、\\ **引擎**\\ 、\\ **LMCache 配置** 和 **注意事项**\\ 。各部分均应保持简洁——若某字段无内容可写，请用一行说明，不要填充无关内容。"
+
+#: ../../source/recipes/uniform_attention_models.rst:103
+msgid "Add a row to the table above and an entry to the hidden toctree below."
+msgstr "在上方表格中新增一行，并在下方隐藏的 toctree 中新增一个条目。"
+
+#: ../../source/recipes/uniform_attention_models.rst:105
+msgid ""
+"(For models that interleave attention types, add the page under "
+":doc:`/mp/hybrid_models` instead.)"
+msgstr "（对于交错多种注意力类型的模型，请将页面添加至 :doc:`/mp/hybrid_models` 下。）"
+
+#~ msgid "Architecture"
+#~ msgstr "架构"
+
+#~ msgid "``MiniMaxM2ForCausalLM``"
+#~ msgstr "``MiniMaxM2ForCausalLM``"
+
+#~ msgid "``MistralForCausalLM``"
+#~ msgstr "``MistralForCausalLM``"
+
+#~ msgid "``Qwen3MoeForCausalLM``"
+#~ msgstr "``Qwen3MoeForCausalLM``"
+
+#~ msgid "``LlamaForCausalLM``"
+#~ msgstr "``LlamaForCausalLM``"
+
+#~ msgid "``Phi3ForCausalLM``"
+#~ msgstr "``Phi3ForCausalLM``"
+
+#~ msgid "``MixtralForCausalLM``"
+#~ msgstr "``MixtralForCausalLM``"
+
+#~ msgid "Legend: ``✓`` validated, ``—`` not validated."
+#~ msgstr "图例：``✓`` 已验证，``—`` 未验证。"
+
diff --git a/docs/source/mp/architecture.png b/docs/source/mp/architecture.png
new file mode 100644
index 0000000..e90d738
Binary files /dev/null and b/docs/source/mp/architecture.png differ
diff --git a/docs/source/mp/cachegen.rst b/docs/source/mp/cachegen.rst
new file mode 100644
index 0000000..8548d9f
--- /dev/null
+++ b/docs/source/mp/cachegen.rst
@@ -0,0 +1,8 @@
+CacheGen
+========
+
+.. note::
+
+   CacheGen KV cache compression for multiprocess mode is **not implemented
+   yet** (coming soon). The original in-process implementation is preserved in
+   the Legacy section: :doc:`/kv_cache_optimizations/compression/index`.
diff --git a/docs/source/mp/configuration.rst b/docs/source/mp/configuration.rst
new file mode 100644
index 0000000..a3c2e7a
--- /dev/null
+++ b/docs/source/mp/configuration.rst
@@ -0,0 +1,614 @@
+Configuration Reference
+=======================
+
+This page documents every CLI argument accepted by the LMCache multiprocess
+server.  Arguments are grouped by the config module that defines them.
+
+.. contents::
+   :local:
+   :depth: 2
+
+MP Server
+---------
+
+Source: ``lmcache/v1/multiprocess/config.py``
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--instance-id``
+     - *(unset, default UUID v4)*
+     - Stable identity of this MP server. Used as the coordinator
+       membership key and projected onto the OTel
+       ``service.instance.id`` resource attribute on every metric and
+       span (so telemetry and coordinator membership share one id).
+       When the flag is not passed, defaults to a random UUID v4
+       minted at startup.
+   * - ``--host``
+     - ``localhost``
+     - Host address to bind the ZMQ server.
+   * - ``--port``
+     - ``5555``
+     - Port to bind the ZMQ server.
+   * - ``--chunk-size``
+     - ``256``
+     - Chunk size for KV cache operations (in tokens).
+   * - ``--max-workers``
+     - ``1``
+     - Base number of worker threads. Sets the default for both the GPU
+       (affinity) pool and the CPU (normal) pool. Can be overridden
+       per-pool with ``--max-gpu-workers`` and ``--max-cpu-workers``.
+   * - ``--max-gpu-workers``
+     - (inherits ``--max-workers``)
+     - Worker threads for the GPU affinity pool (STORE/RETRIEVE).
+       Requests from the same vLLM instance are always dispatched to the
+       same thread, eliminating GPU transfer lock contention.
+   * - ``--max-cpu-workers``
+     - (inherits ``--max-workers``)
+     - Worker threads for the normal CPU pool (LOOKUP, etc.).
+   * - ``--hash-algorithm``
+     - ``blake3``
+     - Hash algorithm for token-based operations.
+       Choices: ``builtin``, ``sha256_cbor``, ``blake3``.
+   * - ``--engine-type``
+     - ``default``
+     - Cache engine backend type. ``default`` uses standard prefix
+       caching; ``blend`` selects the current CacheBlend V3 implementation
+       (composes a ``BlendV3Module`` into the engine);
+       ``blend_legacy`` selects the original CacheBlend
+       (composes a ``BlendModule``). Both blend variants require
+       ``--supported-transfer-mode`` to be ``lmcache_driven`` or ``auto``.
+       Choices: ``default``, ``blend``, ``blend_legacy``.
+   * - ``--supported-transfer-mode``
+     - ``auto``
+     - Which worker → server transfer paths the server loads.
+       ``lmcache_driven`` enables only the server-driven transfer
+       path (STORE/RETRIEVE, supports both CUDA IPC and CPU SHM);
+       ``engine_driven`` enables only the non-GPU (PREPARE/COMMIT)
+       transfer path; ``auto`` (default) loads both
+       so workers of either device type can connect without manual
+       configuration.
+       Choices: ``lmcache_driven``, ``engine_driven``, ``auto``.
+   * - ``--runtime-plugin-locations``
+     - ``[]``
+     - Zero or more paths to runtime plugin scripts or directories to
+       launch alongside the server. Plugins are spawned by
+       ``MPRuntimePluginLauncher`` and receive the full server config
+       via the ``LMCACHE_RUNTIME_PLUGIN_CONFIG`` environment variable.
+   * - ``--runtime-plugin-config``
+     - ``"{}"``
+     - JSON string of extra key-value config forwarded to runtime
+       plugins via ``LMCACHE_RUNTIME_PLUGIN_EXTRA_CONFIG``. Example:
+       ``'{"plugin.frontend.heartbeat_url": "http://localhost:5000/heartbeat"}'``.
+   * - ``--script-allowed-imports``
+     - ``[]``
+     - Space-separated list of Python module names that scripts posted
+       to the HTTP ``/run_script`` endpoint are allowed to import.
+       Example: ``--script-allowed-imports numpy pandas``.
+   * - ``--shm-name``
+     - *(not set)*
+     - SHM segment name for non-GPU KV transfer (only used when the
+       non-GPU path is loaded, i.e. ``--supported-transfer-mode`` is
+       ``auto`` or ``engine_driven``).
+       Not set (default): auto-allocate a shared-memory pool.
+       ``""`` (empty string): disable SHM and force the pickle transfer
+       path.  Any other value: use that exact name for the SHM pool
+       segment.
+   * - ``--worker-reap-timeout-seconds``
+     - ``120.0``
+     - Silence budget (seconds) after which a worker that has sent at
+       least one heartbeat PING but then gone quiet has its KV cache
+       registration reaped, freeing the leaked GPU context and CUDA IPC
+       handles. ``0`` disables reaping. Keep this at least 3x the engine
+       adapter's ``lmcache.mp.heartbeat_interval`` (default 10s) so a few
+       missed pings never reap a live worker; the adapter warns at startup
+       if its interval is raised without raising this.
+   * - ``--worker-registration-grace-seconds``
+     - ``3600.0``
+     - Silence budget (seconds) for a worker that registered but has never
+       sent a PING (still warming up, or died before its first request).
+       Must be >= ``--worker-reap-timeout-seconds``. Generous by default so
+       slow model warmup is never mistaken for a dead worker.
+   * - ``--enable-segmented-prefix``
+     - ``False``
+     - CacheBlend (``--engine-type blend``) only: on a mid-prefix L2 retrieve
+       failure, retain the gapped prefix so the post-gap chunks stay
+       L1-resident and only the dropped gap is recomputed, instead of
+       truncating the prefix at the gap. No effect for other engines. See
+       :doc:`/mp/l2_storage/fault_inject` for a way to exercise it.
+   * - ``--separate-object-groups`` / ``--no-separate-object-groups``
+     - ``True``
+     - Split a hybrid model's kernel groups into one object group per
+       cross-chunk attention window (full attention, each sliding-window
+       size, mamba/GDN) at KV-cache registration. On by default; pass
+       ``--no-separate-object-groups`` to keep all layers in a single
+       full-attention object group. Transparent to correctness; a non-hybrid
+       model always resolves to one object group. See :doc:`/mp/hybrid_models`.
+
+Lookup Hash Logging
+-------------------
+
+Source: ``lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py``
+
+When enabled, the server publishes chunk hashes computed during ``lookup()``
+as ``MP_LOOKUP`` events on the EventBus.  The
+``LookupHashLoggingSubscriber`` writes these to rotating JSONL files for
+offline analysis.  Disabled by default.  These arguments are part of the
+Observability group.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--lookup-hash-log-dir``
+     - ``""`` (disabled)
+     - Directory to write lookup hash JSONL files.
+       An empty string disables logging.
+   * - ``--lookup-hash-log-rotation-interval``
+     - ``21600`` (6 h)
+     - Time interval in seconds before rotating to a new log file.
+   * - ``--lookup-hash-log-rotation-max-size``
+     - ``104857600`` (100 MB)
+     - Max file size in bytes before rotating even if the time
+       interval has not elapsed.
+   * - ``--lookup-hash-log-max-files``
+     - ``100``
+     - Max number of log files to keep.  Oldest files are deleted
+       when this limit is exceeded.
+
+HTTP Frontend
+-------------
+
+Source: ``lmcache/v1/multiprocess/config.py``
+
+The HTTP frontend is included when running ``lmcache server``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--http-host``
+     - ``0.0.0.0``
+     - Host to bind the HTTP (FastAPI/uvicorn) server.
+   * - ``--http-port``
+     - ``8080``
+     - Port to bind the HTTP server.
+
+P2P
+---
+
+Source: ``lmcache/v1/multiprocess/config.py``
+
+These flags configure peer-to-peer KV cache sharing between MP servers
+(see :doc:`p2p`). They are registered by ``add_p2p_args()`` on the
+``lmcache server`` parser. P2P is enabled when ``--p2p-advertise-url``
+is set, which additionally requires a coordinator URL via
+``--coordinator-url`` (or ``LMCACHE_COORDINATOR_URL``).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--p2p-advertise-url``
+     - ``""`` (P2P disabled)
+     - Transfer-channel server ``host:port`` this instance advertises to
+       peers. Setting it enables P2P (also requires ``--coordinator-url``).
+   * - ``--p2p-listen-url``
+     - ``""``
+     - Transfer-channel server ``host:port`` to bind. Defaults to
+       ``--p2p-advertise-url``.
+   * - ``--p2p-lookup-timeout``
+     - ``30.0``
+     - Seconds before a peer lookup result counts as a miss.
+   * - ``--p2p-load-timeout``
+     - ``30.0``
+     - Seconds before a peer load counts as a failure.
+   * - ``--p2p-transfer-engine``
+     - ``nixl``
+     - Transfer-channel implementation to use.
+
+L1 Memory Manager
+------------------
+
+Source: ``lmcache/v1/distributed/config.py``
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--l1-size-gb``
+     - *required*
+     - Size of the L1 tier in GB. Sizes the pinned-DRAM L1 by default, or the
+       GDS slab file when ``--gds-l1-path`` is set (see *GDS L1 Tier* below).
+   * - ``--l1-use-lazy`` / ``--no-l1-use-lazy``
+     - ``True``
+     - Enable or disable lazy allocation for L1 memory.
+       Pass ``--l1-use-lazy`` to enable (default) or
+       ``--no-l1-use-lazy`` to explicitly disable.
+   * - ``--l1-init-size-gb``
+     - ``20``
+     - Initial allocation size (GB) when using lazy allocation.
+   * - ``--l1-align-bytes``
+     - ``4096``
+     - Alignment size in bytes (default 4 KB).
+   * - ``--l1-devdax-path``
+     - *(not set)*
+     - Optional ``/dev/dax*`` device or mmap-able file to use as the L1
+       backing arena.  When set, disable lazy allocation with
+       ``--no-l1-use-lazy`` and disable SHM transfer advertising with
+       ``--shm-name ""`` because the L1 bytes live in the DAX mapping.  If a
+       DAX L2 adapter with the same ``device_path`` is registered, that
+       adapter's ``max_dax_size_gb`` is used as the L1 Device-DAX overflow
+       size.
+
+GDS L1 Tier
+-----------
+
+Source: ``lmcache/v1/distributed/config.py``
+
+Opt-in. Setting ``--gds-l1-path`` switches the L1 medium from pinned DRAM to
+an NVMe slab file accessed via GPUDirect Storage DMA. The CPU pinned-DRAM tier
+is then disabled, and ``--l1-size-gb`` sizes the slab. Disable byte-array L2
+adapters when this is on (the GDS tier exposes no L1 memory buffer for them to
+register).
+
+The DMA path is selected automatically by platform: **cuFile**
+(``libcufile.so``) on NVIDIA and **hipFile** (``libhipfile.so``,
+`ROCm/hipFile <https://github.com/ROCm/hipFile>`_) on AMD ROCm. The same
+flags apply to both; no configuration change is needed to switch vendors.
+
+.. note::
+
+   AMD hipFile requires ROCm >= 7.2.0. The zero-copy GPUDirect fast path
+   additionally needs a kernel built with ``CONFIG_PCI_P2PDMA``,
+   ``amdgpu-dkms >= 30.20.1``, and the slab on a local NVMe ext4/xfs
+   filesystem; where those are unavailable hipFile transparently falls back to
+   a host-bounce compatibility path (correct, but not zero-copy).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--gds-l1-path``
+     - Not set
+     - NVMe directory for the GDS L1 slab. Setting this enables the GDS L1
+       tier; one shared slab per process lives at
+       ``<path>/lmcache_gds_slab.bin``.
+   * - ``--gds-l1-use-direct-io`` / ``--no-gds-l1-use-direct-io``
+     - ``True``
+     - Open the slab with ``O_DIRECT`` (required for the GDS DMA fast path on
+       ext4).
+
+L1 Manager TTLs
+----------------
+
+Source: ``lmcache/v1/distributed/config.py``
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--l1-write-ttl-seconds``
+     - ``600``
+     - Time-to-live for each object's write lock (seconds).
+   * - ``--l1-read-ttl-seconds``
+     - ``300``
+     - Time-to-live for each object's read lock (seconds).
+
+Eviction Policy
+---------------
+
+Source: ``lmcache/v1/distributed/config.py``
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--eviction-policy``
+     - *required*
+     - Eviction policy.
+       Choices: ``LRU``, ``IsolatedLRU``, ``noop``.
+       Use ``noop`` for buffer-only mode where L1 acts as a pure
+       write buffer (data is deleted from L1 after L2 store).
+       ``IsolatedLRU`` maintains one LRU list per ``cache_salt``
+       and requires per-``cache_salt`` quotas to be configured at
+       runtime via the ``/quota`` HTTP endpoints
+       (see :ref:`mp-http-quota-api`); a ``cache_salt`` with no
+       registered quota has an effective limit of ``0`` bytes,
+       so its data is evicted at the next eviction cycle
+       (allowlist semantics).
+   * - ``--eviction-trigger-watermark``
+     - ``0.8``
+     - Memory usage ratio (0.0--1.0) that triggers eviction.
+   * - ``--eviction-ratio``
+     - ``0.2``
+     - Fraction of allocated memory to evict when triggered (0.0--1.0).
+
+L2 Policies
+-----------
+
+Source: ``lmcache/v1/distributed/config.py``
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--l2-store-policy``
+     - ``default``
+     - L2 store policy.  Determines which adapters receive each key
+       and whether keys are deleted from L1 after L2 store.
+       The ``default`` policy stores all keys to all adapters and keeps L1.
+       The ``skip_l1`` policy stores all keys to all adapters and then
+       deletes them from L1 (buffer-only mode).
+       Choices: ``default``, ``skip_l1``.
+   * - ``--l2-prefetch-policy``
+     - ``default``
+     - L2 prefetch policy.  Determines which adapter loads each key
+       when multiple adapters have it.
+       The ``default`` policy picks the first adapter (lowest index).
+       Prefetched keys are temporary (deleted after the reader finishes).
+       The ``retain`` policy uses the same load plan but keeps
+       prefetched keys permanently in L1.
+       Choices: ``default``, ``retain``.
+   * - ``--l2-prefetch-max-in-flight``
+     - ``8``
+     - Maximum number of concurrent prefetch (L2 load) requests.
+       Limits how many in-flight loads the PrefetchController may
+       issue at once, preventing excessive L1 memory pressure.
+   * - ``--periodic-notifier-interval-ms``
+     - ``5``
+     - Interval in milliseconds for the periodic event notifier
+       heartbeat.  A native C++ background thread writes to all
+       registered file descriptors at this interval, waking
+       controller poll loops for L2 adapters that lack native
+       async completion callbacks.
+
+L2 Adapters
+-----------
+
+Source: ``lmcache/v1/distributed/l2_adapters/config.py``
+
+L2 adapters are configured via repeatable ``--l2-adapter <JSON>`` arguments.
+Each JSON object must include a ``"type"`` field that selects the adapter type.
+The order of ``--l2-adapter`` arguments determines the adapter order (cascade).
+
+Registered adapter types: ``nixl_store``, ``nixl_store_dynamic``, ``fs``,
+``fs_native``, ``mock``, ``mooncake_store``, ``aerospike``, ``s3``, ``resp``,
+``plugin``, ``native_plugin``, ``raw_block``, ``dax``.
+
+Each adapter type's required and optional fields, plus per-backend examples, are
+documented on its own page under :doc:`Secondary KV Storage <l2_storage/index>`
+-- including the adapters not detailed inline here (``fs_native``,
+``raw_block``, ``dax``, ``mooncake_store``, ``aerospike``, ``hfbucket``,
+``resp``).
+
+Multiple adapters (cascade)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pass ``--l2-adapter`` multiple times.  Adapters are used in the order given:
+
+.. code-block:: bash
+
+    --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/ssd/l2", "use_direct_io": "false"}, "pool_size": 64}' \
+    --l2-adapter '{"type": "nixl_store", "backend": "GDS", "backend_params": {"file_path": "/data/nvme/l2", "use_direct_io": "true"}, "pool_size": 128}'
+
+Observability
+-------------
+
+Source: ``lmcache/v1/mp_observability/config.py``
+
+See :doc:`observability/index` for full details on the three modes (metrics,
+logging, tracing).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--disable-observability``
+     - off
+     - Master switch: disable the EventBus entirely.
+   * - ``--disable-metrics``
+     - off
+     - Skip metrics subscribers (no Prometheus endpoint).
+   * - ``--disable-logging``
+     - off
+     - Skip logging subscribers.
+   * - ``--enable-tracing``
+     - off
+     - Register tracing subscribers. Requires ``--otlp-endpoint``.
+   * - ``--event-bus-queue-size``
+     - ``10000``
+     - Max events in the EventBus queue before tail-drop.
+   * - ``--otlp-endpoint``
+     - *(none)*
+     - OTLP gRPC endpoint for exporting metrics and traces.
+   * - ``--prometheus-port``
+     - ``9090``
+     - Port for the Prometheus ``/metrics`` endpoint.
+
+vLLM Client Configuration
+--------------------------
+
+On the vLLM side, specify the LMCache server host and port via the
+``kv_connector_extra_config`` parameter:
+
+.. code-block:: bash
+
+    vllm serve Qwen/Qwen3-14B \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.host": "tcp://127.0.0.1", "lmcache.mp.port": 6000}}'
+
+To target multiple LMCache servers from a single vLLM deployment, pass a
+list (or comma-separated string) of server URLs via
+``lmcache.mp.server_urls``. When set, ``server_urls`` takes precedence
+over the single-server ``host`` / ``port`` keys; vLLM's world size must
+be divisible by the number of servers, and each worker connects only to
+its locally-assigned server (global ranks are sliced into contiguous
+blocks, one block per server). Multi-server mode currently supports
+tensor parallelism only -- pipeline parallelism (``pp_size > 1``) and
+data parallelism (``dp_size > 1``) are rejected with a clear error.
+
+.. code-block:: bash
+
+    vllm serve Qwen/Qwen3-14B \
+        --tensor-parallel-size 4 \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.server_urls": "tcp://host1:6667,tcp://host2:6667"}}'
+
+``LMCacheMPConnector`` reads the following keys from
+``kv_connector_extra_config``:
+
+Connector ``extra_config`` Keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All connector-level options are passed through
+``kv_connector_extra_config`` and use the ``lmcache.mp.`` prefix.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Key
+     - Default
+     - Description
+   * - ``lmcache.mp.server_urls``
+     - *(unset)*
+     - Multi-server deployment: list (or comma-separated string) of
+       ``<transport>://<host>:<port>`` URLs, e.g.
+       ``"tcp://host1:6667,tcp://host2:6667"``. When set, takes
+       precedence over ``lmcache.mp.host`` / ``lmcache.mp.port``; the
+       vLLM world size must be divisible by the number of servers, and
+       each worker connects to its locally-assigned server.
+   * - ``lmcache.mp.host``
+     - ``tcp://localhost``
+     - Single-server deployment: host (with ZMQ transport prefix) of
+       the LMCache MP server. Ignored when ``lmcache.mp.server_urls``
+       is set.
+   * - ``lmcache.mp.port``
+     - ``5555``
+     - Single-server deployment: port of the LMCache MP server. Must
+       match the server's ``--port``. Ignored when
+       ``lmcache.mp.server_urls`` is set.
+   * - ``lmcache.mp.mq_timeout``
+     - ``300.0``
+     - Timeout (seconds) for blocking message-queue requests, including
+       the initial chunk-size query and KV cache
+       registration/unregistration. If the server does not respond within
+       this window, the connector raises ``ConnectionError`` on startup.
+   * - ``lmcache.mp.heartbeat_interval``
+     - ``10.0``
+     - Interval (seconds) between periodic heartbeat pings sent from the
+       connector to the server.
+   * - ``lmcache.mp.mp_transfer_mode``
+     - ``auto``
+     - Routing mode for the worker -> server transfer context. One of
+       ``auto`` (CUDA -> lmcache_driven, others -> engine_driven),
+       ``lmcache_driven`` (force the IPC / SHM zero-copy handle path —
+       LMCache server pulls data via device handles), or
+       ``engine_driven`` (force the worker-side gather/scatter copy
+       path). Overrides the ``LMCACHE_MP_TRANSFER_MODE`` env var when
+       set.
+
+Environment Variables
+---------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Variable
+     - Description
+   * - ``LMCACHE_LOG_LEVEL``
+     - Log level for LMCache (``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``).
+       Set to ``DEBUG`` to see L2 store activity, prefetch results, etc.
+   * - ``PYTHONHASHSEED``
+     - Set to a fixed value for reproducible hashing across processes
+       (relevant when using ``--hash-algorithm builtin``).
+   * - ``LMCACHE_TRACK_USAGE``
+     - Set to ``false`` to disable anonymous usage statistics (see below).
+   * - ``DO_NOT_TRACK``
+     - Set to ``1`` to disable anonymous usage statistics (cross-tool
+       convention).
+
+Anonymous Usage Statistics
+--------------------------
+
+At startup the MP server sends a one-time anonymous usage report to the
+LMCache stats server: an environment snapshot (cloud provider, CPU/GPU,
+memory) and a configuration snapshot (chunk size, transfer mode, L1
+size/medium, L2 adapter types, policies). No prompts, keys, KV-cache data,
+model names, or the server's ``--instance-id`` are ever sent; reports are
+correlated only through random UUIDs. Reporting runs on a background
+thread, never delays startup, and a failure anywhere in reporting never
+affects serving.
+
+To opt out, set ``LMCACHE_TRACK_USAGE=false`` or ``DO_NOT_TRACK=1``. See
+:ref:`usage-stats-collection` for the full list of collected fields and
+configuration options.
+
+Full Example
+------------
+
+.. code-block:: bash
+
+    lmcache server \
+        --host 0.0.0.0 \
+        --port 6555 \
+        --chunk-size 512 \
+        --max-workers 4 \
+        --max-gpu-workers 2 \
+        --hash-algorithm blake3 \
+        --engine-type default \
+        --lookup-hash-log-dir /data/lmcache/lookup_hashes \
+        --lookup-hash-log-rotation-interval 21600 \
+        --lookup-hash-log-rotation-max-size 104857600 \
+        --lookup-hash-log-max-files 100 \
+        --l1-size-gb 100 \
+        --l1-use-lazy \
+        --l1-init-size-gb 20 \
+        --l1-align-bytes 4096 \
+        --l1-write-ttl-seconds 600 \
+        --l1-read-ttl-seconds 300 \
+        --eviction-policy noop \
+        --l2-store-policy skip_l1 \
+        --eviction-trigger-watermark 0.9 \
+        --eviction-ratio 0.1 \
+        --l2-prefetch-policy default \
+        --l2-prefetch-max-in-flight 8 \
+        --periodic-notifier-interval-ms 5 \
+        --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false"}, "pool_size": 64}' \
+        --prometheus-port 9090 \
+        --metrics-sample-rate 0.01 \
+        --enable-tracing \
+        --otlp-endpoint http://localhost:4317
diff --git a/docs/source/mp/coordinator.rst b/docs/source/mp/coordinator.rst
new file mode 100644
index 0000000..613d480
--- /dev/null
+++ b/docs/source/mp/coordinator.rst
@@ -0,0 +1,925 @@
+Multi-Server Coordination
+=========================
+
+When you run more than one LMCache multiprocess (MP) server, the **MP
+Coordinator** is a standalone service they register with, giving you a single,
+fleet-wide view of every running server. Each MP server caches independently;
+the coordinator ties them together into one coordinated fleet.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Running the coordinator
+-----------------------
+
+The coordinator is a FastAPI service. Start it with:
+
+.. code-block:: bash
+
+    lmcache coordinator
+
+Expected log output:
+
+.. code-block:: text
+
+    LMCache INFO: MP coordinator listening on http://0.0.0.0:9300
+
+The CLI accepts ``--host``, ``--port``, ``--instance-timeout``,
+``--health-check-interval``, ``--eviction-check-interval``,
+``--eviction-ratio``, ``--trigger-watermark``, ``--chunk-size``,
+``--hash-algorithm``, ``--blend-probe-stride``, and ``--timeout-keep-alive``;
+any flag overrides the matching environment variable below. See
+:doc:`/cli/coordinator` for details.
+Equivalently, the coordinator can still be launched as a module with
+``python3 -m lmcache.v1.mp_coordinator``.
+
+Configuration
+-------------
+
+The coordinator is configured through ``LMCACHE_MP_COORDINATOR_*`` environment
+variables:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 38 14 48
+
+   * - Environment variable
+     - Default
+     - Description
+   * - ``LMCACHE_MP_COORDINATOR_HOST``
+     - ``0.0.0.0``
+     - Host the HTTP server binds to.
+   * - ``LMCACHE_MP_COORDINATOR_PORT``
+     - ``9300``
+     - Port the HTTP server binds to.
+   * - ``LMCACHE_MP_COORDINATOR_INSTANCE_TIMEOUT``
+     - ``30``
+     - Seconds without a heartbeat after which a server is dropped from the
+       fleet.
+   * - ``LMCACHE_MP_COORDINATOR_HEALTH_CHECK_INTERVAL``
+     - ``10``
+     - Seconds between health-check sweeps. ``0`` disables eviction.
+   * - ``LMCACHE_MP_COORDINATOR_EVICTION_CHECK_INTERVAL``
+     - ``5``
+     - Seconds between L2 eviction sweeps. ``0`` disables the loop.
+   * - ``LMCACHE_MP_COORDINATOR_EVICTION_RATIO``
+     - ``0.2``
+     - Fraction of tracked keys (by count) to evict per cycle (0.0 to 1.0).
+   * - ``LMCACHE_MP_COORDINATOR_TRIGGER_WATERMARK``
+     - ``1.0``
+     - Eviction fires when usage reaches this fraction of the quota
+       (0.0 exclusive to 1.0).
+   * - ``LMCACHE_MP_COORDINATOR_CHUNK_SIZE``
+     - ``256``
+     - Tokens per KV chunk: the CacheBlend match unit and the unit used to
+       resolve pin ``token_ids`` to keys. Must equal the MP servers'
+       ``--chunk-size``.
+   * - ``LMCACHE_MP_COORDINATOR_HASH_ALGORITHM``
+     - ``blake3``
+     - Token hash algorithm for pin key resolution. Must equal the MP servers'
+       ``--hash-algorithm``. ``blake3`` is self-contained; other algorithms
+       require vLLM importable in the coordinator process.
+   * - ``LMCACHE_MP_COORDINATOR_BLEND_PROBE_STRIDE``
+     - ``1``
+     - Positions between CacheBlend match probes. ``1`` probes every offset
+       for full recall.
+   * - ``LMCACHE_MP_COORDINATOR_TIMEOUT_KEEP_ALIVE``
+     - ``10``
+     - Seconds the HTTP server keeps idle connections open before closing
+       them. Must be greater than the MP servers' heartbeat interval
+       (default ``5``), otherwise heartbeat requests may hit a closing
+       connection and fail with ``Server disconnected without sending a
+       response``.
+   * - ``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC``
+     - ``True``
+     - When ``True``, the coordinator runs a one-shot L2 resync on
+       startup that paginates an MP server's ``GET /cache/objects`` and
+       backfills usage + eviction trackers from existing L2 contents.
+       Disable to start from empty trackers (handy for tests, or
+       deployments that start the coordinator before any MP server).
+   * - ``LMCACHE_MP_COORDINATOR_RESYNC_POLL_INTERVAL``
+     - ``1``
+     - Seconds between registry checks while waiting for the first
+       MP server to register so startup resync can begin.
+   * - ``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT``
+     - ``60``
+     - Maximum seconds startup resync waits for an MP server before
+       giving up. The coordinator keeps running with empty trackers
+       until normal usage events fill them in.
+   * - ``LMCACHE_MP_COORDINATOR_RESYNC_PAGE_SIZE``
+     - ``1000``
+     - ``page_size`` forwarded to the MP server's ``GET /cache/objects``
+       during resync. Larger values reduce RTT count; the server
+       clamps to its own ceiling.
+
+Connecting MP servers
+---------------------
+
+An MP server (``lmcache server``) joins the coordinator when you point it at one
+with ``--coordinator-url``. It registers on startup, heartbeats while running,
+and deregisters on shutdown -- all on the server's own event loop. This is
+opt-in: with no URL set, the server runs exactly as before. Each flag falls back
+to a matching ``LMCACHE_COORDINATOR_*`` environment variable (handy for the
+Kubernetes downward API); an explicit flag wins over the env var.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 38 24 38
+
+   * - Flag (on the MP server)
+     - Env fallback
+     - Description
+   * - ``--coordinator-url``
+     - ``LMCACHE_COORDINATOR_URL``
+     - Coordinator base URL, e.g. ``http://coordinator:9300``. Enables
+       registration when set.
+   * - ``--coordinator-advertise-ip``
+     - ``LMCACHE_COORDINATOR_ADVERTISE_IP``
+     - IP the coordinator should reach this server at (defaults to the server's
+       outbound IP).
+   * - ``--coordinator-heartbeat-interval``
+     - ``LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL``
+     - Seconds between heartbeats (must be ``> 0``, default ``5``). Keep it well
+       below the coordinator's ``INSTANCE_TIMEOUT``.
+   * - ``--coordinator-l2-event-reporting``
+     - ``LMCACHE_COORDINATOR_L2_EVENT_REPORTING``
+     - Enable reporting L2 store/lookup events to the coordinator for
+       fleet-wide usage tracking and quota-based eviction.
+   * - ``--coordinator-l2-event-flush-interval``
+     - ``LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL``
+     - Seconds between L2 event batch flushes (must be ``> 0``, default ``1``).
+
+The server registers under its stable identity (``--instance-id`` / OTel
+``service.instance.id``); if the flag is not passed, the server mints a
+random UUID v4 at startup and registers under that.
+
+Registration is best-effort: if the coordinator is unreachable, the MP server
+logs a warning, keeps retrying, and continues serving. A malformed
+heartbeat-interval value is rejected at startup.
+
+HTTP endpoints
+--------------
+
+The coordinator's HTTP surface (base URL ``http://localhost:9300``) groups into:
+
+- **Fleet membership and health** -- registration and liveness
+  (``/instances``, ``/healthz``).
+- **Quota, usage, and eviction** -- the ``/quota`` group: per-tenant byte
+  budgets, usage accounting, and the usage-event ingest that drives fleet-wide
+  eviction.
+- **Cache control** -- the ``/cache`` group: cache operations dispatched to a
+  named server (warm prefetch and pin/unpin, with more to come).
+
+Each endpoint is documented below. Success is ``200`` unless noted, and
+``{cache_salt}`` uses the ``_default`` sentinel for the empty salt. The wire
+types live in ``lmcache/v1/mp_coordinator/schemas.py``.
+
+Fleet membership and health
+---------------------------
+
+MP servers register, heartbeat, and deregister automatically (see
+`Connecting MP servers`_); ``GET /instances`` and ``GET /healthz`` are read-only
+operator views.
+
+``POST /instances``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Register (or re-register) an MP server. Called automatically by each server on
+startup.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 14 64
+
+   * - Field
+     - Type
+     - Description
+   * - ``ip``
+     - string
+     - IP/host of the server's HTTP API; the coordinator dials this address, so
+       it must be non-empty.
+   * - ``http_port``
+     - int
+     - Port of the server's HTTP API.
+   * - ``instance_id``
+     - string
+     - Optional. Server identifier; if omitted (or blank) the coordinator
+       generates one and returns it.
+   * - ``metadata``
+     - object
+     - Optional. Free-form ``string -> string`` registration hints.
+   * - ``p2p_advertised_url``
+     - string
+     - Optional. URL the server advertises for peer-to-peer transfers; empty
+       when it is not in P2P.
+   * - ``mq_port``
+     - int
+     - Optional (default ``0``). ZMQ message-queue port P2P peers send
+       lookup/unlock RPCs to; ``0`` when P2P is disabled.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"instance_id": "server-1", "re_registered": false}
+
+``instance_id`` is the registered id (the generated one when the request omitted
+it); ``re_registered`` is ``true`` when this replaced an existing registration.
+
+**HTTP status codes:**
+
+- ``200``: registered.
+- ``422``: request body fails field-level validation (e.g. blank ``ip`` or
+  out-of-range ``http_port``).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:9300/instances \
+        -H 'Content-Type: application/json' \
+        -d '{"ip": "10.0.0.5", "http_port": 8080}'
+    # -> {"instance_id": "mp-3f2c9d...", "re_registered": false}
+
+``PUT /instances/{instance_id}/heartbeat``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Record a liveness heartbeat. Called automatically while the server runs.
+
+**Path parameters:** ``instance_id`` — the instance recording the heartbeat.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"instance_id": "server-1"}
+
+**HTTP status codes:**
+
+- ``200``: heartbeat recorded.
+- ``404``: unknown instance — the caller should re-register via
+  ``POST /instances``.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X PUT http://localhost:9300/instances/server-1/heartbeat
+    # -> {"instance_id": "server-1"}
+
+``DELETE /instances/{instance_id}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Deregister an MP server. Called automatically on shutdown.
+
+**Path parameters:** ``instance_id`` — the server to deregister.
+
+**Response:** ``204 No Content`` with an empty body, returned whether or not the
+instance was registered (idempotent).
+
+**HTTP status codes:**
+
+- ``204``: deregistered (also returned for an unknown instance).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X DELETE http://localhost:9300/instances/server-1 -o /dev/null -w '%{http_code}\n'
+    # -> 204
+
+``GET /instances``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+List every registered MP server.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "instances": [
+        {
+          "instance_id": "server-1",
+          "ip": "10.0.0.5",
+          "http_port": 8080,
+          "registration_time": 1719000000.0,
+          "metadata": {},
+          "p2p_advertised_url": "",
+          "mq_port": 0
+        }
+      ]
+    }
+
+Each entry reports the server's ``instance_id``, the ``ip`` / ``http_port`` the
+coordinator reaches it at, the wall-clock ``registration_time`` (epoch seconds),
+any ``metadata`` supplied at registration, and the ``p2p_advertised_url`` /
+``mq_port`` used for peer-to-peer transfers (empty / ``0`` when P2P is disabled).
+
+**HTTP status codes:**
+
+- ``200``: fleet listed (an empty fleet returns ``{"instances": []}``).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:9300/instances
+
+``GET /healthz``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Coordinator liveness probe (for Kubernetes).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"status": "healthy"}
+
+**HTTP status codes:**
+
+- ``200``: the coordinator is up.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:9300/healthz
+    # -> {"status": "healthy"}
+
+Quota, usage, and eviction
+--------------------------
+
+The ``/quota`` group owns per-``cache_salt`` byte budgets, the live usage
+accounting behind them, and the usage-event stream that drives fleet-wide
+eviction. (The MP server exposes a node-local ``/quota`` with the same shape;
+this is its fleet-wide counterpart.) Use ``_default`` as the path parameter to
+target the empty-string salt.
+
+.. warning::
+
+   Do **not** use the MP server's node-local ``/quota`` API together with the
+   coordinator's. The two are independent, unsynchronized quota registries
+   enforcing eviction on the **same shared L2**: the server-side enforcer
+   (active when the server runs a per-salt eviction policy) uses strict
+   allowlist semantics — any salt missing from *its own* table is fully
+   evicted — and it never sees quotas registered on the coordinator, and vice
+   versa. Mixing the two produces competing eviction decisions: the server can
+   wipe data the coordinator considers within quota (or still exempt before
+   the default limit is armed). Pick one owner per deployment — in
+   coordinator-managed deployments, register quotas **only** through the
+   coordinator's ``/quota`` API and leave the servers' node-local quota tables
+   untouched.
+
+Salts without an explicit quota are governed by the registry's **default
+limit** (``PUT /quota/config``). On boot the default is unset, and unquota'd
+salts are **exempt** from eviction — quotas live in memory, so a freshly
+(re)started coordinator has an empty quota table until the external quota
+controller re-syncs it, and the exempt default keeps that window from
+mass-evicting unknown tenants. After re-registering every per-salt quota, the
+controller sets the default to ``0`` — the signal that arms strict allowlist
+enforcement (all bytes under unquota'd salts become evictable on the next
+cycle):
+
+.. code-block:: bash
+
+    # 1. re-register every tenant quota
+    curl -s -X PUT http://localhost:9300/quota/user-a \
+        -H 'Content-Type: application/json' -d '{"limit_gb": 10.0}'
+    # ... one PUT per tenant ...
+
+    # 2. arm eviction of everything else
+    curl -s -X PUT http://localhost:9300/quota/config \
+        -H 'Content-Type: application/json' -d '{"default_limit_gb": 0}'
+    # -> {"default_limit_gb": 0.0}
+
+When MP servers enable ``--coordinator-l2-event-reporting``, they stream L2
+``store``, ``lookup``, and ``delete`` events to the coordinator, which aggregates
+per-``cache_salt`` usage, enforces quotas, and selects LRU keys to evict. Each
+batch carries the server's ``instance_id`` and a monotonically increasing
+sequence number (``seq``) scoped to that instance, enabling future gap detection.
+
+**Active eviction loop.** Every
+``LMCACHE_MP_COORDINATOR_EVICTION_CHECK_INTERVAL`` seconds, the
+coordinator inspects per-salt usage against the registered quotas and,
+for any salt over the trigger watermark, picks LRU victims and
+dispatches a single ``DELETE /cache/objects`` to a uniformly random registered MP
+server. Because all MP servers share the same backing L2 (e.g. one S3
+bucket), one dispatch evicts the keys for the whole fleet. The MP
+server's L2 adapter fires ``on_l2_keys_deleted`` listeners after the
+delete completes; those listeners ship ``delete`` events back through
+``POST /quota/events``, which is what updates the coordinator's LRU +
+per-salt totals. Dispatch failures or no-instances-registered fall
+through to the next cycle — at-least-once semantics, safe because the
+S3 delete is idempotent.
+
+**Startup resync.** On boot, the coordinator waits up to
+``LMCACHE_MP_COORDINATOR_RESYNC_MAX_WAIT`` seconds for the first MP
+server to register, then paginates its
+``GET /cache/objects`` and seeds the in-memory usage + eviction trackers
+with whatever is already resident in L2 — so a fresh coordinator
+does not start from zero usage. Set
+``LMCACHE_MP_COORDINATOR_ENABLE_STARTUP_RESYNC=False`` to skip this
+phase. Best-effort: resync failures are logged and the manager gives
+up; the ongoing usage-event stream from MP servers eventually corrects
+any initial blind spots.
+
+``PUT /quota/config`` / ``GET /quota/config``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Set / read the default limit applied to salts with no explicit quota entry.
+
+**Request body** (``PUT``):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 14 64
+
+   * - Field
+     - Type
+     - Description
+   * - ``default_limit_gb``
+     - float or null
+     - ``null`` (the boot default) exempts unquota'd salts from eviction;
+       ``0`` arms strict allowlist enforcement (all unquota'd bytes become
+       evictable next cycle); a positive value grants every unquota'd salt
+       that byte budget.
+   * - ``tier``
+     - string
+     - Optional (default ``l2``). Only ``l2`` is supported today.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"default_limit_gb": 0.0}
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:9300/quota/config
+    # -> {"default_limit_gb": null}          (boot state: unquota'd exempt)
+
+    curl -s -X PUT http://localhost:9300/quota/config \
+        -H 'Content-Type: application/json' -d '{"default_limit_gb": 0}'
+    # -> {"default_limit_gb": 0.0}           (allowlist enforcement armed)
+
+``PUT /quota/{cache_salt}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create or update a tenant's byte budget.
+
+**Path parameters:** ``cache_salt`` — tenant identifier (``_default`` for the
+empty salt).
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 14 68
+
+   * - Field
+     - Type
+     - Description
+   * - ``limit_gb``
+     - float
+     - Byte budget in GiB; must be ``>= 0`` (``0`` clears the tenant's data on
+       the next eviction cycle).
+   * - ``tier``
+     - string
+     - Optional (default ``l2``). Cache tier the quota applies to; only ``l2`` is
+       supported today.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"cache_salt": "user-a", "limit_gb": 10.0, "status": "ok"}
+
+**HTTP status codes:**
+
+- ``200``: quota applied.
+- ``400``: invalid limit (negative or non-finite).
+- ``422``: request body fails field-level validation.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X PUT http://localhost:9300/quota/user-a \
+        -H 'Content-Type: application/json' \
+        -d '{"limit_gb": 10.0}'
+    # -> {"cache_salt": "user-a", "limit_gb": 10.0, "status": "ok"}
+
+``DELETE /quota/{cache_salt}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Remove a salt's quota entry. Any bytes still cached under it become over-budget
+on the next eviction cycle (effective limit drops to ``0``).
+
+**Path parameters:** ``cache_salt`` — tenant identifier (``_default`` for the
+empty salt).
+
+**Query parameters:** ``tier`` — optional (default ``l2``); cache tier the quota
+applies to.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"cache_salt": "user-a", "limit_gb": 0.0, "status": "removed"}
+
+When no quota was registered for the salt, ``status`` is ``"not_found"`` (still
+``200 OK``).
+
+**HTTP status codes:**
+
+- ``200``: removed, or ``not_found`` if no quota existed.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X DELETE http://localhost:9300/quota/user-a
+    # -> {"cache_salt": "user-a", "limit_gb": 0.0, "status": "removed"}
+
+``GET /quota/{cache_salt}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Read the quota and live usage for a single salt.
+
+**Path parameters:** ``cache_salt`` — tenant identifier (``_default`` for the
+empty salt).
+
+**Query parameters:** ``tier`` — optional (default ``l2``).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"cache_salt": "user-a", "quota_limit_gb": 10.0, "quota_exists": true, "usage_gb": 0.001}
+
+``quota_limit_gb`` is the configured limit in GiB (``0.0`` when no quota is set),
+``quota_exists`` whether an explicit quota is registered, and ``usage_gb`` the
+current aggregate usage. This endpoint never returns ``404`` for an unknown salt.
+
+**HTTP status codes:**
+
+- ``200``: quota and usage reported.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:9300/quota/user-a
+    # -> {"cache_salt": "user-a", "quota_limit_gb": 10.0, "quota_exists": true, "usage_gb": 0.001}
+
+``GET /quota``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+List total usage and a per-salt breakdown.
+
+**Query parameters:** ``tier`` — optional (default ``l2``).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "total_gb": 0.005,
+      "by_cache_salt": [
+        {"cache_salt": "user-a", "quota_limit_gb": 10.0, "quota_exists": true, "usage_gb": 0.001}
+      ]
+    }
+
+``total_gb`` is aggregate usage across all salts in GiB; each ``by_cache_salt``
+entry has the same fields as the ``GET /quota/{cache_salt}`` response.
+
+**HTTP status codes:**
+
+- ``200``: usage reported.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:9300/quota
+    # -> {"total_gb": 0.005, "by_cache_salt": [...]}
+
+``POST /quota/events``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Ingest a batch of usage events. Sent automatically by reporting MP servers; not
+usually called by hand.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 16 66
+
+   * - Field
+     - Type
+     - Description
+   * - ``instance_id``
+     - string
+     - The MP server that produced this batch.
+   * - ``seq``
+     - int
+     - Monotonic per-instance sequence number (``>= 1``); supports future gap
+       detection of lost batches.
+   * - ``tier``
+     - string
+     - Optional (default ``l2``). Cache tier the events apply to.
+   * - ``events``
+     - list[object]
+     - The events to record. Each is ``{"type", "key", "bytes"}``: ``type`` is
+       ``"store"``, ``"lookup"``, or ``"delete"``; ``key`` is the encoded object
+       key; ``bytes`` (``>= 0``) is the stored size — counted for ``store`` and
+       ignored for ``lookup`` / ``delete`` (a ``delete`` subtracts the size
+       recorded at the original ``store``).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"recorded": 3}
+
+``recorded`` is the number of events processed.
+
+**HTTP status codes:**
+
+- ``200``: events processed.
+- ``422``: request body fails field-level validation.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:9300/quota/events \
+        -H 'Content-Type: application/json' \
+        -d '{
+            "instance_id": "server-1",
+            "seq": 1,
+            "events": [
+                {"type": "store",  "key": {"chunk_hash_hex": "aa", "model_name": "m", "kv_rank": 0, "cache_salt": "user-a"}, "bytes": 1024},
+                {"type": "lookup", "key": {"chunk_hash_hex": "aa", "model_name": "m", "kv_rank": 0, "cache_salt": "user-a"}, "bytes": 0},
+                {"type": "delete", "key": {"chunk_hash_hex": "aa", "model_name": "m", "kv_rank": 0, "cache_salt": "user-a"}, "bytes": 0}
+            ]
+        }'
+    # -> {"recorded": 3}
+
+Cache control
+-------------
+
+The ``/cache`` group dispatches cache operations to a named MP server. It covers
+**warm prefetch** and **pin/unpin**; further cache-control operations will be
+documented as endpoints here as they land.
+
+**Warm prefetch (pre-loading L1 from L2).** Pre-warm one MP server's L1 with the
+KV for a known prompt **before** the requests arrive, so the first request hits
+L1 instead of paying the L2 fetch inline -- useful when you know a workload is
+about to be routed to a node (a traffic shift, a hot shared system prompt).
+
+You describe the content by **token ids** -- the unit the cache speaks -- never
+by internal cache keys, which you cannot construct (a key is a content hash
+plus a per-rank layout bitmap). The coordinator forwards the request to the
+named server, which hashes the tokens, expands them across the node's ranks,
+loads the chunks from L2 into L1, and **retains** them so a later lookup hits.
+The submit returns a ``request_id``; poll the status endpoint until
+``completed``. The warm acquires no lock -- the poll simply reports progress and
+clears the server-side job once the load finishes.
+
+``POST /cache/prefetches``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Submit a warm prefetch of a token sequence on one named server.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 16 66
+
+   * - Field
+     - Type
+     - Description
+   * - ``instance_id``
+     - string
+     - Target MP server; must be registered.
+   * - ``model_name``
+     - string
+     - Model whose layout sizes the target's L1 buffers.
+   * - ``world_size``
+     - int
+     - World size (``>= 1``) selecting the KV layout and the per-rank fan-out
+       (``1`` for a single-GPU, TP=1 deployment).
+   * - ``token_ids``
+     - list[int]
+     - Prompt tokens whose complete ``chunk_size`` chunks are warmed; must match
+       what was stored (same tokenizer / special tokens). A sub-chunk sequence
+       is a ``noop``.
+   * - ``cache_salt``
+     - string
+     - Optional (default ``""``). Per-tenant isolation salt applied to the
+       produced keys.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"instance_id": "server-1", "request_id": "abc123", "chunks": 12, "status": "submitted"}
+
+When the sequence is shorter than one chunk, nothing is submitted and
+``request_id`` is empty:
+
+.. code-block:: json
+
+    {"instance_id": "server-1", "request_id": "", "chunks": 0, "status": "noop"}
+
+``request_id`` is the id to poll; ``chunks`` is the number of whole chunks
+submitted to warm.
+
+**HTTP status codes:**
+
+- ``200``: submitted (or a ``noop`` as above).
+- ``404``: unknown ``instance_id`` (not registered).
+- ``502``: the target server was unreachable or rejected the submit.
+- ``422``: request body fails field-level validation.
+
+.. note::
+
+   **Single-node scope:** one ``instance_id`` warms only that node's shards. For
+   a model sharded across multiple nodes, submit one request per node's instance.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:9300/cache/prefetches \
+        -H 'Content-Type: application/json' \
+        -d '{
+            "instance_id": "server-1",
+            "model_name": "Qwen/Qwen3-8B",
+            "world_size": 1,
+            "token_ids": [101, 102, 103, "..."],
+            "cache_salt": "user-a"
+        }'
+    # -> {"instance_id": "server-1", "request_id": "abc123", "chunks": 12, "status": "submitted"}
+
+``GET /cache/prefetches/{instance_id}/{request_id}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Poll a submitted warm prefetch; the response relays the owning server's status
+verbatim with its code.
+
+**Path parameters:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 14 64
+
+   * - Field
+     - Type
+     - Description
+   * - ``instance_id``
+     - string
+     - The server the prefetch was submitted to.
+   * - ``request_id``
+     - string
+     - The id returned by ``POST /cache/prefetches``.
+
+**Response** (``200 OK``) while the load runs:
+
+.. code-block:: json
+
+    {"status": "pending"}
+
+…and once complete:
+
+.. code-block:: json
+
+    {"status": "completed", "found_keys": 12, "total_keys": 12}
+
+``found_keys`` of ``total_keys`` requested chunks were resident.
+
+**HTTP status codes:**
+
+- ``200``: status reported (``pending`` or ``completed``).
+- ``404``: unknown ``instance_id``, or unknown ``request_id`` relayed from the
+  server.
+- ``502``: the target server was unreachable.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:9300/cache/prefetches/server-1/abc123
+    # -> {"status": "completed", "found_keys": 12, "total_keys": 12}
+
+**Pin/unpin (protecting cache from eviction).** Pin a token sequence's cache so
+it is not evicted from L2 until unpinned. The coordinator resolves the token
+sequence to its object keys **locally** (no MP-server round-trip) and records
+them in its L2 eviction plan (``POST``) or releases them (``DELETE``), excluding
+pinned keys from quota-based eviction. L2 pins are fleet-wide (per
+``cache_salt``), so no target instance is named.
+
+Local resolution requires the coordinator's ``chunk_size`` and
+``hash_algorithm`` (see `Configuration`_) to match the MP servers' ``--chunk-size``
+/ ``--hash-algorithm``; otherwise the resolved keys will not match what was
+stored and the pin protects nothing. It also requires the MP servers to be
+launched with ``--no-separate-object-groups`` (the coordinator resolves keys in
+a single object group).
+
+``POST /cache/pins``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pin a token sequence's keys in the L2 eviction plan.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 16 66
+
+   * - Field
+     - Type
+     - Description
+   * - ``model_name``
+     - string
+     - Model whose rank fan-out to use when resolving keys.
+   * - ``world_size``
+     - int
+     - World size (``>= 1``) selecting the per-rank fan-out.
+   * - ``token_ids``
+     - list[int]
+     - Prompt tokens whose complete chunks are pinned; must match what was
+       stored. A sub-chunk sequence pins nothing (``affected`` 0).
+   * - ``cache_salt``
+     - string
+     - Optional (default ``""``). Per-tenant isolation salt.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"requested": 12, "affected": 12, "status": "pinned"}
+
+``requested`` is the number of whole chunks resolved; ``affected`` is the number
+of L2 keys pinned (chunks times the per-rank fan-out).
+
+**HTTP status codes:**
+
+- ``200``: pinned.
+- ``400``: ``token_ids`` exceeds the per-request cap, or ``cache_salt`` violates
+  its invariants.
+- ``422``: request body fails field-level validation.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:9300/cache/pins \
+        -H 'Content-Type: application/json' \
+        -d '{
+            "model_name": "Qwen/Qwen3-8B",
+            "world_size": 1,
+            "token_ids": [101, 102, 103, "..."],
+            "cache_salt": "user-a"
+        }'
+    # -> {"requested": 12, "affected": 12, "status": "pinned"}
+
+.. note::
+
+   **Requires L2 event reporting.** The coordinator can only exclude keys from
+   eviction for a salt it is tracking, which requires the MP servers started with
+   ``--coordinator-l2-event-reporting`` (see `Connecting MP servers`_).
+
+``DELETE /cache/pins``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unpin a token sequence's keys from the L2 eviction plan. Same request body as
+``POST /cache/pins``. The response mirrors the pin (``affected`` is the number
+of keys unpinned), with ``status`` ``"unpinned"``. Pins are reference-counted: a
+chunk pinned *N* times needs *N* unpins before it can be evicted.
+
+**HTTP status codes:** same as ``POST /cache/pins``.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X DELETE http://localhost:9300/cache/pins \
+        -H 'Content-Type: application/json' \
+        -d '{
+            "model_name": "Qwen/Qwen3-8B",
+            "world_size": 1,
+            "token_ids": [101, 102, 103, "..."],
+            "cache_salt": "user-a"
+        }'
+    # -> {"requested": 12, "affected": 12, "status": "unpinned"}
diff --git a/docs/source/mp/deployment.rst b/docs/source/mp/deployment.rst
new file mode 100644
index 0000000..9bac52e
--- /dev/null
+++ b/docs/source/mp/deployment.rst
@@ -0,0 +1,270 @@
+Deployment Guide
+================
+
+This page covers deploying LMCache multiprocess mode in Docker and Kubernetes
+environments, along with production best practices.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Docker
+------
+
+**LMCache container:**
+
+.. code-block:: bash
+
+    docker run --runtime nvidia --gpus all \
+        --network host \
+        --ipc host \
+        lmcache/standalone:nightly \
+        /opt/venv/bin/lmcache server \
+        --l1-size-gb 60 --eviction-policy LRU --max-workers 4 --port 6555
+
+**vLLM container:**
+
+.. code-block:: bash
+
+    docker run --runtime nvidia --gpus all \
+        --network host \
+        --ipc host \
+        lmcache/vllm-openai:latest-nightly \
+        Qwen/Qwen3-14B \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.port": 6555}}'
+
+Required Docker flags:
+
+- ``--network host`` -- Allows the vLLM container to reach LMCache on localhost.
+- ``--ipc host`` -- Required for CUDA IPC shared memory transfers between
+  containers.
+- ``--runtime nvidia --gpus all`` -- GPU access via the NVIDIA container
+  runtime.
+
+**HTTP server variant:**
+
+For health-check and cache management API support (useful with container
+orchestrators), use the HTTP server entry point:
+
+.. code-block:: bash
+
+    docker run --runtime nvidia --gpus all \
+        --network host \
+        --ipc host \
+        lmcache/standalone:nightly \
+        /opt/venv/bin/lmcache server \
+        --l1-size-gb 60 --eviction-policy LRU --max-workers 4 --port 6555
+
+Kubernetes
+----------
+
+LMCache is designed for a **DaemonSet + Deployment** pattern: one LMCache
+server per node (DaemonSet) shared by multiple vLLM pods (Deployment).
+
+Example YAML files are provided in ``examples/multi_process/``.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- Kubernetes cluster with GPU support (NVIDIA GPU Operator installed)
+- At least 4 GPUs per node
+- ``kubectl`` configured to access your cluster
+
+Step-by-Step
+~~~~~~~~~~~~
+
+**Step 1: Create namespace**
+
+.. code-block:: bash
+
+    kubectl create namespace multi-process
+
+**Step 2: Deploy LMCache DaemonSet**
+
+.. code-block:: bash
+
+    kubectl apply -f examples/multi_process/lmcache-daemonset.yaml
+
+**Step 3: Deploy vLLM**
+
+.. code-block:: bash
+
+    kubectl apply -f examples/multi_process/vllm-deployment.yaml
+
+.. note::
+   The default model is ``Qwen/Qwen3-14B``.  For gated models (e.g., Llama),
+   create a Secret with your Hugging Face token:
+
+   .. code-block:: bash
+
+       kubectl create secret generic vllm-secrets \
+         --from-literal=hf_token=your_hf_token_here \
+         -n multi-process
+
+   Then add the ``HF_TOKEN`` environment variable to the vLLM container spec.
+
+**Step 4: Monitor deployment**
+
+.. code-block:: bash
+
+    # DaemonSet status
+    kubectl get daemonset -n multi-process
+    kubectl get pods -n multi-process -l app=lmcache-server
+
+    # vLLM status
+    kubectl get pods -n multi-process -l app=vllm-deployment -w
+
+    # LMCache logs (for a specific node)
+    VLLM_NODE=$(kubectl get pod -n multi-process -l app=vllm-deployment \
+        -o jsonpath='{.items[0].spec.nodeName}')
+    LMCACHE_POD=$(kubectl get pod -n multi-process -l app=lmcache-server \
+        --field-selector spec.nodeName=$VLLM_NODE \
+        -o jsonpath='{.items[0].metadata.name}')
+    kubectl logs -n multi-process $LMCACHE_POD -f
+
+**Step 5: Send test requests**
+
+.. code-block:: bash
+
+    kubectl port-forward -n multi-process deployment/vllm-deployment 8000:8000
+
+    curl -X POST http://localhost:8000/v1/completions \
+        -H "Content-Type: application/json" \
+        -d "{
+            \"model\": \"Qwen/Qwen3-14B\",
+            \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+            \"max_tokens\": 10
+        }"
+
+Architecture Notes
+~~~~~~~~~~~~~~~~~~
+
+- **DaemonSet uses ``hostNetwork: true``** so vLLM pods discover the LMCache
+  server via ``status.hostIP``.
+- **Both containers mount ``/dev/shm``** from the host to enable CUDA IPC
+  memory sharing.
+- **GPUs are NOT requested in the DaemonSet** -- this allows GPUs to remain
+  exclusively allocated to vLLM pods.  The NVIDIA container runtime
+  automatically provides GPU access for IPC-based memory transfers.
+- **Multiple vLLM pods** on the same node automatically connect to the same
+  LMCache DaemonSet instance.
+
+.. note::
+   LMCache pods on nodes without GPUs will crash with CUDA initialization
+   errors.  This is expected -- LMCache only needs to run on GPU nodes where
+   vLLM pods are scheduled.
+
+Health Checking (HTTP Server)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For Kubernetes liveness/readiness probes, deploy the HTTP server variant
+instead.  Use the ``/healthcheck`` endpoint:
+
+.. code-block:: yaml
+
+    livenessProbe:
+      httpGet:
+        path: /healthcheck
+        port: 8080
+      initialDelaySeconds: 10
+      periodSeconds: 30
+    readinessProbe:
+      httpGet:
+        path: /healthcheck
+        port: 8080
+      initialDelaySeconds: 5
+      periodSeconds: 10
+
+Monitoring Integration
+~~~~~~~~~~~~~~~~~~~~~~
+
+Prometheus metrics are enabled by default on port 9090.  Add a
+``ServiceMonitor`` or Prometheus scrape annotation to collect metrics from the
+LMCache DaemonSet pods.  See :doc:`observability/index` for metric details.
+
+Cleanup
+~~~~~~~
+
+.. code-block:: bash
+
+    kubectl delete -f examples/multi_process/vllm-deployment.yaml
+    kubectl delete -f examples/multi_process/lmcache-daemonset.yaml
+    kubectl delete namespace multi-process
+
+Production Best Practices
+-------------------------
+
+**Worker count (``--max-workers``, ``--max-gpu-workers``, ``--max-cpu-workers``):**
+``--max-workers`` sets both the GPU affinity pool and CPU normal pool sizes
+(default 1).  Use ``--max-gpu-workers`` to override the GPU pool independently
+--- set it to at least the number of vLLM instances sharing the cache server so
+each instance gets its own dedicated thread.  Use ``--max-cpu-workers`` to
+override the CPU pool for lookup and other non-GPU operations.
+
+**L1 memory sizing (``--l1-size-gb``):**
+Allocate as much CPU memory as available after accounting for the OS and vLLM.
+A larger L1 cache means fewer L2 round-trips.
+
+**Eviction tuning:**
+
+- ``--eviction-trigger-watermark 0.8`` (default) triggers eviction when L1 is
+  80% full.
+- ``--eviction-ratio 0.2`` (default) frees 20% of allocated memory per
+  eviction cycle.
+- Lower the watermark or increase the ratio if you observe frequent evictions
+  under steady load.
+
+**Logging:**
+Use ``LMCACHE_LOG_LEVEL=DEBUG`` during initial setup to verify L2 store/load
+activity.  Switch to ``INFO`` (default) for production to reduce log volume.
+
+Transfer Mode (``--supported-transfer-mode``, ``--shm-name``)
+-------------------------------------------------------------
+
+LMCache supports two worker → server transfer paths: an
+**lmcache-driven** path (server pulls/pushes via CUDA IPC or CPU SHM,
+used for STORE/RETRIEVE) and an **engine-driven** path
+(PREPARE/COMMIT, used by CPU-only or non-CUDA accelerator workers).
+The server picks which paths to load via ``--supported-transfer-mode``:
+
+- ``auto`` *(default)* -- load both paths.  Workers of either device
+  type can connect without manual configuration; the server has no
+  upfront knowledge of the connecting worker's device.
+- ``lmcache_driven`` -- load only the server-driven transfer path.
+  Supports CUDA devices (IPC) and CPU devices (SHM).  Use to skip
+  allocating the engine-driven prepare/commit resources (pickle codec).
+- ``engine_driven`` -- load only the engine-driven path.  Use when
+  serving CPU-only or non-CUDA accelerator workers.
+
+When the engine-driven path is loaded (``auto`` or ``engine_driven``),
+LMCache by default creates a shared-memory (SHM) pool for KV transfers
+between the server and vLLM workers.  The ``--shm-name`` option lets
+you control this behavior:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Value
+     - Effect
+   * - *(not set)* (default)
+     - Auto-allocate a SHM pool (current default behavior).
+   * - ``""`` (empty string)
+     - Disable the SHM pool entirely and fall back to the pickle-based
+       transfer path.  Useful when ``/dev/shm`` is unavailable or when
+       running without ``--ipc host`` in Docker.
+   * - ``"my_pool"`` (any non-empty name)
+     - Use that exact name for the SHM segment instead of the
+       auto-generated one.  Handy when you need a deterministic,
+       human-readable segment name for monitoring or debugging.
+
+**Examples:**
+
+.. code-block:: bash
+
+    # Force pickle (no SHM):
+    lmcache server --l1-size-gb 60 --eviction-policy LRU --shm-name ""
+
+    # Named SHM segment:
+    lmcache server --l1-size-gb 60 --eviction-policy LRU --shm-name "lmcache_pool"
diff --git a/docs/source/mp/disaggregated_prefill.rst b/docs/source/mp/disaggregated_prefill.rst
new file mode 100644
index 0000000..e1f1737
--- /dev/null
+++ b/docs/source/mp/disaggregated_prefill.rst
@@ -0,0 +1,225 @@
+.. _mp_disaggregated_prefill:
+
+Disaggregated Prefill
+=====================
+
+Overview
+--------
+
+Disaggregated prefill (P/D) runs prefill and decode on separate vLLM instances:
+a **prefill** instance computes the prompt's KV, hands it to a **decode**
+instance over NIXL, and the decoder generates tokens without recomputing the
+prompt. Prefill- and decode-heavy work then scale independently.
+
+**LMCache MP adds cross-request KV reuse on top.** Each vLLM instance also
+offloads its KV to a co-located LMCache server, so a recurring prefix — on a
+later request, or after eviction from GPU HBM — is loaded from LMCache instead
+of recomputed. KV-source order on the prefill path: local GPU cache → LMCache →
+recompute.
+
+Both are composed with vLLM's ``MultiConnector``, which runs two connectors per
+instance:
+
+* ``NixlConnector`` — the prefill→decode KV handoff for the current
+  request, over NIXL (UCX / RDMA).
+* ``LMCacheMPConnector`` — offload/load to the instance's LMCache
+  server for cross-request reuse.
+
+A vLLM **router** in P/D mode sends each request to a prefill then a decode
+instance and threads the NIXL handshake between them.
+
+How it works
+------------
+
+A minimal deployment is five processes:
+
+* **Prefill vLLM (producer)** — ``MultiConnector[NixlConnector (kv_producer),
+  LMCacheMPConnector]``; computes prompt KV, stores it to its LMCache server,
+  and exposes it for the decoder to pull over NIXL.
+* **Decode vLLM (consumer)** — ``MultiConnector[NixlConnector (kv_consumer),
+  LMCacheMPConnector]``; pulls prompt KV from the producer and generates output.
+* **Two LMCache servers** — one ``lmcache server`` per vLLM instance (they must
+  not share one).
+* **Router** — ``vllm-router --vllm-pd-disaggregation`` routes prefill then
+  decode.
+
+To share reuse across the prefill and decode pools too, layer
+:doc:`P2P KV cache sharing <p2p>` on top (give both servers a coordinator and
+``--p2p-advertise-url``).
+
+Requirements
+------------
+
+.. important::
+
+   `vllm-project/vllm#46865
+   <https://github.com/vllm-project/vllm/pull/46865>`_ (the MultiConnector
+   real-blocks fix) unblocks LMCache offload under ``MultiConnector``. Without
+   it, offload silently never triggers.
+
+* **NIXL** available in the vLLM environment (``lmcache[nixl]`` extra, which
+  pulls ``nixl>=1.3.0``).
+
+Configuration
+-------------
+
+Each vLLM instance takes a ``--kv-transfer-config`` selecting ``MultiConnector``
+with two sub-connectors:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Key
+     - Description
+   * - ``kv_connector`` = ``MultiConnector``
+     - Runs the ``kv_connector_extra_config.connectors`` side by side.
+   * - ``kv_role``
+     - ``kv_producer`` (prefill) or ``kv_consumer`` (decode), on both the
+       top-level ``MultiConnector`` and the nested ``NixlConnector``.
+   * - ``NixlConnector``
+     - The prefill→decode handoff. Set ``kv_load_failure_policy`` = ``fail`` so
+       a failed transfer surfaces instead of silently recomputing.
+   * - ``LMCacheMPConnector``
+     - Offload/load to the local LMCache server; use ``kv_role`` = ``kv_both``.
+   * - ``lmcache.mp.host`` / ``lmcache.mp.port``
+     - Transport+host and ZMQ ``--port`` of the instance's LMCache server
+       (distinct per instance).
+
+The NIXL transfer is tuned via environment variables on the vLLM instances:
+``VLLM_NIXL_SIDE_CHANNEL_HOST`` (host advertised for the handshake, reachable by
+the peer), ``VLLM_NIXL_SIDE_CHANNEL_PORT`` (**must differ between instances on
+the same host**; default ``5600``), plus ``UCX_NET_DEVICES=all`` and
+``NCCL_CUMEM_ENABLE=1``. See :doc:`/cli/server` for the full ``lmcache server``
+flag list.
+
+Running a deployment
+--------------------
+
+The example below places the prefill pool, the decode pool, and the router on
+separate hosts. Replace ``<PREFILL_IP>`` / ``<DECODE_IP>`` with routable
+addresses and ``<model>`` with the model path (identical on both instances).
+
+**Step 1 — prefill LMCache server** (on the prefill host):
+
+.. code-block:: bash
+
+   lmcache server \
+       --port 6555 --http-port 8090 \
+       --l1-size-gb 100 --eviction-policy LRU --chunk-size 256 \
+       --instance-id prefiller
+
+**Step 2 — prefill vLLM (producer)** (on the prefill host):
+
+.. code-block:: bash
+
+   VLLM_NIXL_SIDE_CHANNEL_HOST=<PREFILL_IP> VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
+   UCX_NET_DEVICES=all NCCL_CUMEM_ENABLE=1 \
+   vllm serve <model> \
+       --port 8001 --tensor-parallel-size 1 \
+       --kv-transfer-config '{"kv_connector":"MultiConnector","kv_role":"kv_producer","kv_connector_extra_config":{"connectors":[{"kv_connector":"NixlConnector","kv_role":"kv_producer","kv_load_failure_policy":"fail"},{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.host":"tcp://localhost","lmcache.mp.port":6555}}]}}'
+
+The producer advertises its NIXL side channel on ``<PREFILL_IP>:5600`` and
+offloads to the LMCache server on port ``6555``.
+
+**Step 3 — decode LMCache server** (on the decode host):
+
+.. code-block:: bash
+
+   lmcache server \
+       --port 6556 --http-port 8091 \
+       --l1-size-gb 100 --eviction-policy LRU --chunk-size 256 \
+       --instance-id decoder
+
+**Step 4 — decode vLLM (consumer)** (on the decode host):
+
+.. code-block:: bash
+
+   VLLM_NIXL_SIDE_CHANNEL_HOST=<DECODE_IP> VLLM_NIXL_SIDE_CHANNEL_PORT=5558 \
+   UCX_NET_DEVICES=all NCCL_CUMEM_ENABLE=1 \
+   vllm serve <model> \
+       --port 8002 --tensor-parallel-size 1 \
+       --kv-transfer-config '{"kv_connector":"MultiConnector","kv_role":"kv_consumer","kv_connector_extra_config":{"connectors":[{"kv_connector":"NixlConnector","kv_role":"kv_consumer","kv_load_failure_policy":"fail"},{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.host":"tcp://localhost","lmcache.mp.port":6556}}]}}'
+
+The consumer offloads to the LMCache server on port ``6556``; its side-channel
+port (``5558``) differs from the producer's so the two can share a host.
+
+**Step 5 — router** (on any host that can reach both vLLM instances):
+
+.. code-block:: bash
+
+   vllm-router \
+       --policy round_robin \
+       --vllm-pd-disaggregation \
+       --prefill http://<PREFILL_IP>:8001 \
+       --decode http://<DECODE_IP>:8002 \
+       --host 0.0.0.0 --port 30000
+
+Send requests to the router (``http://<ROUTER_IP>:30000/v1/...``); it handles
+the prefill→decode split transparently.
+
+Running on a single node (testing & debugging)
+----------------------------------------------
+
+Same five processes over ``localhost``, prefill on GPU 6 and decode on GPU 7.
+The instances must differ in **every** shared-host port: the LMCache ``--port``
+and ``--http-port``, the vLLM ``--port``, and ``VLLM_NIXL_SIDE_CHANNEL_PORT``.
+
+.. code-block:: bash
+
+   lmcache server --port 6555 --http-port 8090 \
+       --l1-size-gb 100 --eviction-policy LRU --chunk-size 256 --instance-id prefiller
+
+   CUDA_VISIBLE_DEVICES=6 VLLM_NIXL_SIDE_CHANNEL_HOST=127.0.0.1 VLLM_NIXL_SIDE_CHANNEL_PORT=5600 \
+   UCX_NET_DEVICES=all NCCL_CUMEM_ENABLE=1 \
+   vllm serve <model> --port 8001 --enforce-eager --max-model-len 16384 --gpu-memory-utilization 0.4 \
+       --kv-transfer-config '{"kv_connector":"MultiConnector","kv_role":"kv_producer","kv_connector_extra_config":{"connectors":[{"kv_connector":"NixlConnector","kv_role":"kv_producer","kv_load_failure_policy":"fail"},{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.host":"tcp://localhost","lmcache.mp.port":6555}}]}}'
+
+   lmcache server --port 6556 --http-port 8091 \
+       --l1-size-gb 100 --eviction-policy LRU --chunk-size 256 --instance-id decoder
+
+   CUDA_VISIBLE_DEVICES=7 VLLM_NIXL_SIDE_CHANNEL_HOST=127.0.0.1 VLLM_NIXL_SIDE_CHANNEL_PORT=5558 \
+   UCX_NET_DEVICES=all NCCL_CUMEM_ENABLE=1 \
+   vllm serve <model> --port 8002 --enforce-eager --max-model-len 16384 --gpu-memory-utilization 0.4 \
+       --kv-transfer-config '{"kv_connector":"MultiConnector","kv_role":"kv_consumer","kv_connector_extra_config":{"connectors":[{"kv_connector":"NixlConnector","kv_role":"kv_consumer","kv_load_failure_policy":"fail"},{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.host":"tcp://localhost","lmcache.mp.port":6556}}]}}'
+
+   vllm-router --policy round_robin --vllm-pd-disaggregation \
+       --prefill http://localhost:8001 --decode http://localhost:8002 --host 0.0.0.0 --port 30000
+
+Add ``--enable-tracing --otlp-endpoint http://localhost:4317`` to each
+``lmcache server`` to export traces/metrics to a local OpenTelemetry collector.
+
+.. note::
+
+   On a single host, NIXL over ``localhost`` uses loopback/TCP, not RDMA, so
+   latencies are not representative — single-node mode is for **functional**
+   testing only.
+
+Verifying it is working
+-----------------------
+
+.. code-block:: bash
+
+   curl -s http://localhost:30000/v1/completions -H "Content-Type: application/json" \
+       -d '{"model":"<model>","prompt":"The capital of France is","max_tokens":16}'
+
+* **P/D routing** — the response ``id`` is stamped with the workers, e.g.
+  ``cmpl-___prefill_addr_localhost:8001___decode_addr_localhost:8002_...``.
+* **NIXL transfer** — the decode vLLM logs ``KV Transfer metrics:
+  NixlConnector={'Num successful transfers': N, ...}``.
+* **LMCache offload** — ``storage_manager.l1_manager.total_object_count`` in
+  ``curl -s http://localhost:8090/status`` grows (prompts must be at least
+  ``--chunk-size`` tokens to store anything).
+* **LMCache hit rate** — read vLLM's **"External prefix cache hit rate"** log
+  line (the fraction of prefill tokens served from LMCache), *not* the LMCache
+  server ``/status``. It stays ``0`` while the working set fits in GPU HBM and
+  rises once reuse spills out of the GPU cache.
+
+Limitations and tuning
+----------------------
+
+* **Keep cold KV transfers bounded under high concurrency.** vLLM's native NIXL
+  P/D path is sensitive to many large *cold* transfers (full-prompt, nothing
+  cached) in flight at once. Keep the decode instance's GPU KV cache large
+  enough to hold the working set so transfers stay small and cache-served, or
+  reduce concurrency when per-request transfers are large.
diff --git a/docs/source/mp/frontend_dashboard.rst b/docs/source/mp/frontend_dashboard.rst
new file mode 100644
index 0000000..f5bb22e
--- /dev/null
+++ b/docs/source/mp/frontend_dashboard.rst
@@ -0,0 +1,223 @@
+Frontend Dashboard
+==================
+
+The **LMCache Frontend Dashboard** is a lightweight web UI that lets you
+monitor and manage a fleet of LMCache multiprocess (MP) servers from a
+single browser tab.  It is shipped as part of the ``lmcache`` package and
+requires no extra infrastructure beyond a small discovery service.
+
+Architecture Overview
+---------------------
+
+.. image:: architecture.png
+   :alt: Architecture Diagram
+   :align: center
+
+.. code-block:: text
+
+    +-----------------------------+
+    |  LMCache MP HTTP Server     |
+    |  (lmcache server)           |
+    |                             |
+    |  MPRuntimePluginLauncher    |                +---------------------------+
+    |    |                        |                |  simple_discover_service  |
+    |    +-> lmcache_mp_frontend  |   heartbeat    |  (lmcache.tools)          |
+    |        _plugin (subprocess) | -------------> |                           |
+    |        -> app.main()        |   (HTTP GET)   |  /lmcache_heartbeat       |
+    |           - HeartbeatService|                |  /lmcache_infos           |
+    |           - (--no-http)     |                +---------------------------+
+    +-----------------------------+                         |
+                                                            | node supplier
+                                                            v
+                                              +---------------------------+
+                                              |  Frontend Dashboard       |
+                                              |  python -m lmcache.       |
+                                              |  lmcache_frontend.app     |
+                                              |  --node-supplier-url ...  |
+                                              +---------------------------+
+
+Each LMCache MP server runs a **frontend plugin subprocess** that
+periodically sends a heartbeat to the discovery service.  The dashboard
+queries the discovery service to discover all live nodes and proxies
+their HTTP APIs through a built-in reverse proxy.
+
+Components
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Component
+     - Description
+   * - ``lmcache.lmcache_frontend.app``
+     - FastAPI application serving the web UI and a reverse proxy to
+       every registered LMCache node.  Start with
+       ``python -m lmcache.lmcache_frontend.app``.
+   * - ``lmcache_mp_frontend_plugin``
+     - Runtime plugin subprocess launched by ``MPRuntimePluginLauncher``.
+       Runs ``HeartbeatService`` (``--no-http`` mode) to register the
+       server with the discovery service.
+   * - ``lmcache.tools.simple_discover_service``
+     - Reference Flask discovery service.  Accepts heartbeats at
+       ``/lmcache_heartbeat`` and exposes the node list at
+       ``/lmcache_infos``.  Start with
+       ``python -m lmcache.tools.simple_discover_service``.
+
+Prerequisites
+-------------
+
+Install the extra dependencies used by the frontend and discovery service:
+
+.. code-block:: bash
+
+    pip install flask httpx fastapi uvicorn
+
+These are not pulled in by the base ``lmcache`` install to keep it slim.
+
+Quick Start
+-----------
+
+**Step 1 — Start the discovery service**
+
+.. code-block:: bash
+
+    python3 -m lmcache.tools.simple_discover_service
+
+The service listens on ``0.0.0.0:5000`` and exposes:
+
+- ``GET /lmcache_heartbeat`` — record a heartbeat from an MP server.
+- ``GET /lmcache_infos`` — return all registered nodes as JSON.
+
+**Step 2 — Start the LMCache MP server with the frontend plugin**
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 2 \
+        --eviction-policy LRU \
+        --http-host 0.0.0.0 --http-port 8085 \
+        --runtime-plugin-locations \
+            lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py \
+        --runtime-plugin-config \
+            '{"plugin.frontend.heartbeat-url": "http://localhost:5000/lmcache_heartbeat"}'
+
+The plugin subprocess will start sending heartbeats to the discovery
+service every 30 seconds (configurable via
+``plugin.frontend.heartbeat-interval``).
+
+Alternatively, use the provided example script:
+
+.. code-block:: bash
+
+    bash lmcache/lmcache_frontend/run_mp_server_with_frontend.sh
+
+**Step 3 — Start the dashboard**
+
+.. code-block:: bash
+
+    python3 -m lmcache.lmcache_frontend.app \
+        --port 8000 \
+        --host 0.0.0.0 \
+        --node-supplier-url http://localhost:5000/lmcache_infos
+
+Open ``http://localhost:8000`` in your browser.
+
+.. note::
+   The dashboard auto-refreshes the node list from the supplier URL
+   at most once every 30 seconds when the homepage is loaded.
+
+Dashboard Features
+------------------
+
+- **Node tree view** — shows all proxies and their child nodes in a
+  collapsible tree.
+- **Metrics aggregation** — ``GET /metrics`` on the dashboard aggregates
+  Prometheus metrics from every leaf node.
+- **Reverse proxy** — ``/proxy2/{node_name}/{path}`` forwards requests to
+  the named node, enabling direct API access from the browser.
+- **Health endpoint** — ``GET /health`` returns ``{"status": "healthy"}``.
+
+CLI Reference
+-------------
+
+``python -m lmcache.lmcache_frontend.app``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--host``
+     - ``0.0.0.0``
+     - Bind address for the dashboard HTTP server.
+   * - ``--port``
+     - ``8000``
+     - Port for the dashboard HTTP server.
+   * - ``--node-supplier-url``
+     - *(none)*
+     - URL of the discovery service's node-list endpoint, e.g.
+       ``http://localhost:5000/lmcache_infos``.
+   * - ``--config``
+     - *(built-in)*
+     - Path to a JSON config file listing proxy nodes.  Used when
+       ``--node-supplier-url`` is not set.
+   * - ``--nodes``
+     - *(none)*
+     - Inline JSON array of node dicts, e.g.
+       ``'[{"name":"n1","host":"127.0.0.1","port":"8085"}]'``.
+   * - ``--heartbeat-url``
+     - *(none)*
+     - If set, the dashboard itself also sends heartbeats to this URL.
+   * - ``--log-level``
+     - ``warning``
+     - Uvicorn log level (``debug``, ``info``, ``warning``, …).
+   * - ``--no-http``
+     - ``false``
+     - Disable the HTTP server; only the heartbeat loop runs.  Used
+       internally by the MP plugin.
+
+Plugin Config Keys
+------------------
+
+Pass these inside ``--runtime-plugin-config`` when launching the MP server:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Key
+     - Description
+   * - ``plugin.frontend.heartbeat-url``
+     - **(Required)** Heartbeat endpoint of the discovery service.
+   * - ``plugin.frontend.heartbeat-interval``
+     - Heartbeat interval in seconds (default: ``30``).
+   * - ``plugin.frontend.heartbeat-initial-delay``
+     - Seconds to wait before the first heartbeat (default: ``0``).
+
+Using a Custom Discovery Service
+---------------------------------
+
+The ``simple_discover_service`` is a reference implementation.  Any HTTP
+service that accepts the following GET request can be used:
+
+.. code-block:: text
+
+    GET <heartbeat_url>?api_address=<url>&pid=<int>&version=<str>&other_info=<json>
+
+And exposes a node-list endpoint that returns JSON in the shape:
+
+.. code-block:: json
+
+    {
+      "processInfos": {
+        "http://host:port": {
+          "lmCacheInfoEntities": [
+            {"apiAddress": "http://host:port", "version": "1.0.0"}
+          ]
+        }
+      }
+    }
diff --git a/docs/source/mp/http_api.rst b/docs/source/mp/http_api.rst
new file mode 100644
index 0000000..8b0ea00
--- /dev/null
+++ b/docs/source/mp/http_api.rst
@@ -0,0 +1,1676 @@
+HTTP API
+========
+
+When the MP server is started via ``lmcache server`` (the recommended entry
+point), a FastAPI-based HTTP frontend is exposed alongside the ZMQ socket
+used by vLLM. This HTTP API is intended for operators, orchestrators
+(e.g. Kubernetes), and debugging tools — it is **not** on the inference
+data path.
+
+Where the routes come from
+--------------------------
+
+Routes are assembled from three sources, all merged into one FastAPI app by
+:class:`~lmcache.v1.multiprocess.http_api_registry.HTTPAPIRegistry` at startup:
+
+- **MP-native routes** — any module named ``*_api.py`` under
+  ``lmcache/v1/multiprocess/http_apis/`` that exposes a module-level
+  ``router`` (a :class:`fastapi.APIRouter`) is auto-discovered. This covers
+  the operational surface: status, cache control, L2 management, quota, and
+  runtime reconfiguration.
+- **Shared "common" routes** —
+  ``lmcache/v1/multiprocess/http_apis/common_api.py`` aggregates every
+  compatible router under ``lmcache/v1/internal_api_server/common/`` (skipping
+  any module listed in ``_MP_INCOMPATIBLE_MODULES``, currently empty) and
+  forwards them to the auto-discovery pipeline. These are the cross-server
+  diagnostics shared with the vLLM-embedded API server (``/env``,
+  ``/loglevel``, ``/metrics``, ``/threads``, ``/periodic-threads*``,
+  ``/run_script``). Adding a new compatible module under
+  ``internal_api_server/common`` requires no wiring changes on the MP side.
+- **Re-exported version routes** — the basic-info group
+  ``lmcache/v1/multiprocess/http_apis/info_api.py`` includes the router
+  from ``lmcache/v1/internal_api_server/vllm/version_api.py``, exposing
+  ``/version``, ``/lmc_version``, and ``/commit_id`` alongside ``/``,
+  ``/healthcheck`` and ``/status``.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Server Configuration
+--------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--http-host``
+     - ``0.0.0.0``
+     - Host to bind the HTTP server.
+   * - ``--http-port``
+     - ``8080``
+     - Port to bind the HTTP server.
+
+Example:
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --http-host 0.0.0.0 --http-port 8080
+
+All examples below assume the server is reachable at
+``http://localhost:8080``.
+
+Endpoint Overview
+-----------------
+
+The routes are grouped by purpose below. The operational surface (health,
+status, cache and storage control) lives at top-level paths; routes inherited
+from the shared ``internal_api_server`` package keep their original paths for
+compatibility with the vLLM-embedded API server.
+
+.. note::
+
+   Several handlers report failure in the response **body** rather than via a
+   non-200 status code (e.g. ``DELETE /cache/objects`` returns ``200`` with ``ok=false``,
+   and ``/periodic-threads-health`` returns ``200`` with ``healthy=false``).
+   The error-field name is also not uniform: ``/healthcheck`` and
+   ``/cache/clear`` use ``reason`` on failure, while ``/status``, ``/config``,
+   and ``/cache/checksums`` use ``error``. Per-endpoint details below are
+   authoritative.
+
+**Liveness and health**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 35 55
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/``
+     - Static liveness ping (does not touch the engine).
+   * - GET
+     - ``/healthcheck``
+     - K8s liveness/readiness probe; ``503`` until the engine is initialized.
+
+**Inspection and status**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 35 55
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/status``
+     - Detailed engine snapshot (L1, L2, registered contexts, sessions,
+       prefetch jobs) for inspection and debugging.
+   * - GET
+     - ``/config``
+     - Dump the merged server configuration objects (``mp``,
+       ``storage_manager``, ``observability``).
+   * - GET
+     - ``/config/adapters``
+     - Enumerate the live cache adapters (``type_name``, ``tier``, ``primary``,
+       ``reconfigurable``). Supersedes ``/reconfigure/backends``.
+   * - GET
+     - ``/version``
+     - Combined version string (``"<version>-<commit_id>"``).
+   * - GET
+     - ``/lmc_version``
+     - LMCache package version string.
+   * - GET
+     - ``/commit_id``
+     - Build commit id.
+
+**Cache management**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 38 52
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/cache/objects``
+     - Paginate objects resident in a tier/adapter (query: ``tier``,
+       ``adapter``, ``model_name``, ``page_size``, ``page_token``).
+   * - DELETE
+     - ``/cache/objects``
+     - Delete a caller-supplied list of object keys (body: ``tier``,
+       ``adapter``, ``keys``).
+   * - POST
+     - ``/cache/prefetches``
+     - Warm a node's L1 by loading a token sequence from L2 ahead of traffic;
+       returns a ``request_id``.
+   * - GET
+     - ``/cache/prefetches/{request_id}``
+     - Poll a submitted warm prefetch (``pending`` / ``completed``).
+   * - POST
+     - ``/cache/clear``
+     - Force-clear a tier's resident cache (body: ``tier`` = ``l1``, ``force``).
+   * - POST
+     - ``/cache/checksums``
+     - Compute MD5 checksums over KV cache blocks (diagnostics / round-trip
+       integrity checks).
+
+**Quota management**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 35 55
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/quota``
+     - List every registered ``cache_salt`` quota with live usage.
+   * - PUT
+     - ``/quota/{cache_salt}``
+     - Set or update the quota (in GB) for a ``cache_salt``.
+   * - GET
+     - ``/quota/{cache_salt}``
+     - Read the quota and live usage for a single ``cache_salt``.
+   * - DELETE
+     - ``/quota/{cache_salt}``
+     - Remove a ``cache_salt``'s quota entry (its data is evicted next cycle).
+
+**Runtime L2 reconfiguration**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 35 55
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/reconfigure/{backend}/status``
+     - Report runtime-manageable L2 adapters for one backend type. (To discover
+       reconfigurable backends, use ``GET /config/adapters`` and read the
+       ``reconfigurable`` flag.)
+   * - POST
+     - ``/reconfigure/{backend}/{operation}``
+     - Apply one runtime reconfiguration operation to a backend adapter.
+
+**Observability**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 35 55
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/metrics``
+     - Prometheus exposition format.
+   * - POST
+     - ``/metrics/reset``
+     - Reset all observability metrics to their initial state.
+
+**Diagnostics and debugging**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 35 55
+
+   * - Method
+     - Path
+     - Purpose
+   * - GET
+     - ``/loglevel``
+     - List or inspect logger levels; also accepts ``level`` to mutate one.
+   * - GET
+     - ``/threads``
+     - Enumerate active Python threads and their stack traces.
+   * - GET
+     - ``/periodic-threads``
+     - List registered periodic threads with summary counts.
+   * - GET
+     - ``/periodic-threads/{thread_name}``
+     - Detailed status for a single periodic thread.
+   * - GET
+     - ``/periodic-threads-health``
+     - Quick health check for critical/high-level periodic threads.
+   * - GET
+     - ``/env``
+     - Dump process environment variables (JSON body, ``text/plain``).
+   * - POST
+     - ``/run_script``
+     - Execute an uploaded Python script in a restricted sandbox.
+
+Liveness and Health
+-------------------
+
+``GET /``
+~~~~~~~~~
+
+Basic liveness check. Returns a static payload indicating the HTTP server
+is running; it does **not** touch the cache engine. Use ``/healthcheck``
+instead for probes that also verify the engine is initialized.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "status": "ok",
+      "service": "LMCache HTTP API"
+    }
+
+**HTTP status codes:**
+
+- ``200``: server is alive (unconditional; does not touch the engine).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/
+
+``GET /healthcheck``
+~~~~~~~~~~~~~~~~~~~~
+
+Health check endpoint suitable for Kubernetes liveness and readiness
+probes. A ``200`` response means the HTTP server is alive **and** the MP
+cache engine object is wired onto ``app.state``. A ``503`` response
+indicates the engine is not yet present (still initializing, or failed to
+initialize). The check verifies that the engine attribute is set; it does
+not call into the engine to assert deeper liveness.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "status": "healthy"
+    }
+
+**Response** (``503 Service Unavailable``):
+
+.. code-block:: json
+
+    {
+      "status": "unhealthy",
+      "reason": "engine not initialized"
+    }
+
+**HTTP status codes:**
+
+- ``200``: engine is wired onto ``app.state`` (healthy).
+- ``503``: engine not initialized (still starting up, or failed to initialize).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/healthcheck
+
+**Kubernetes probe snippet:**
+
+.. code-block:: yaml
+
+    livenessProbe:
+      httpGet:
+        path: /healthcheck
+        port: 8080
+      initialDelaySeconds: 10
+      periodSeconds: 10
+    readinessProbe:
+      httpGet:
+        path: /healthcheck
+        port: 8080
+      initialDelaySeconds: 5
+      periodSeconds: 5
+
+Inspection and Status
+---------------------
+
+``GET /status``
+~~~~~~~~~~~~~~~
+
+Returns a detailed snapshot of the MP engine's internal state. The payload is
+assembled by ``MPCacheServer.report_status()``: a fixed set of engine-level
+fields, the full storage-manager status, plus whatever keys each loaded module
+contributes (so the exact key set depends on which modules are active —
+``registered_gpu_ids`` / ``cache_context_meta`` come from the transfer module,
+``active_prefetch_jobs`` from the lookup module, and blend modes add their own
+fields). Intended for operators and debugging, not for monitoring (use
+Prometheus metrics for time-series data — see :doc:`observability/index`).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "is_healthy": true,
+      "engine_type": "MPCacheServer",
+      "chunk_size": 256,
+      "hash_algorithm": "builtin-hash",
+      "active_sessions": 2,
+      "registered_gpu_ids": [0, 1],
+      "cache_context_meta": {
+        "0": {
+          "model_name": "meta-llama/Llama-3.1-8B-Instruct",
+          "world_size": 1,
+          "kv_cache_layout": {
+            "num_layers": 32,
+            "num_blocks": 12345,
+            "cache_size_per_token": 131072,
+            "kernel_groups": [
+              {
+                "kernel_group_idx": 0,
+                "engine_group_idx": 0,
+                "object_group_idx": 0,
+                "num_layers": 32,
+                "layer_indices": [0, 1, "..."],
+                "tokens_per_block": 16,
+                "slots_per_block": 16,
+                "dtype": "torch.bfloat16",
+                "engine_kv_concrete_shape": "...",
+                "is_mla": false,
+                "engine_kv_format": "...",
+                "engine_kv_shape": "...",
+                "attention_backend": "..."
+              }
+            ]
+          }
+        }
+      },
+      "active_prefetch_jobs": 0,
+      "storage_manager": {
+        "is_healthy": true,
+        "...": "backend-specific fields"
+      }
+    }
+
+**Response** (``503 Service Unavailable``) when the engine has not yet
+been initialized:
+
+.. code-block:: json
+
+    {
+      "error": "engine not initialized"
+    }
+
+**HTTP status codes:**
+
+- ``200``: status snapshot returned.
+- ``503``: engine not yet initialized on ``app.state``.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/status | jq
+
+``GET /config``
+~~~~~~~~~~~~~~~
+
+Returns every server-side configuration object registered on
+``app.state.configs`` (typically ``mp``, ``storage_manager`` and
+``observability``) as a single indented JSON document. Dataclasses are
+serialized via ``safe_asdict``; other values go through ``make_json_safe``.
+Useful for confirming what the process actually loaded — including
+environment overrides — without restarting.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "mp": {
+        "http_host": "0.0.0.0",
+        "http_port": 8080,
+        "...": "..."
+      },
+      "storage_manager": {
+        "...": "..."
+      },
+      "observability": {
+        "...": "..."
+      }
+    }
+
+**Response** (``503 Service Unavailable``) when configs are not wired
+onto ``app.state`` yet:
+
+.. code-block:: json
+
+    {
+      "error": "configs not initialized"
+    }
+
+**HTTP status codes:**
+
+- ``200``: configuration document returned.
+- ``503``: configs not yet wired onto ``app.state``.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/config | jq
+
+``GET /config/adapters``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enumerate every L2 adapter the engine has loaded, in configuration
+order. Which storage backends are loaded is a configuration-inspection
+concern, so this lives in the config group rather than under ``/cache``.
+This is the single live adapter listing; it supersedes the old
+``GET /reconfigure/backends`` (the reconfigurable backends are the
+``type_name`` values whose ``reconfigurable`` flag is ``true``).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "adapters": [
+        {"index": 0, "type_name": "S3L2Adapter", "tier": "l2", "primary": true, "reconfigurable": false},
+        {"index": 1, "type_name": "dax", "tier": "l2", "primary": false, "reconfigurable": true}
+      ]
+    }
+
+``primary`` is ``true`` only on the first entry. ``reconfigurable`` is
+``true`` for adapters that accept ``/reconfigure`` operations — pass that
+adapter's ``type_name`` as the ``{backend}`` path parameter to
+``GET /reconfigure/{backend}/status`` and the reconfigure operations. An
+engine that has no L2 backends returns ``{"adapters": []}`` (still ``200`` —
+the engine is initialized, it just has no L2 storage).
+
+**HTTP status codes:**
+
+- ``200``: success (including the no-adapters case).
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/config/adapters | jq
+
+``GET /version``, ``GET /lmc_version``, ``GET /commit_id``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Version descriptors. Each returns a bare JSON **string** (not an object):
+
+- ``GET /version`` — the combined descriptor from
+  ``lmcache.utils.get_version()``, formatted ``"<version>-<commit_id>"``
+  (e.g. ``"0.3.1-ca79ea33"``). On a source checkout without build-time
+  version metadata, each missing component falls back to the literal
+  ``"NA"`` (so a metadata-less build returns ``"NA-NA"``).
+- ``GET /lmc_version`` — the raw package version string
+  (``lmcache.utils.VERSION``); empty string ``""`` when the generated
+  ``lmcache._version`` module is absent.
+- ``GET /commit_id`` — the git commit id baked into the build
+  (``lmcache.utils.COMMIT_ID``); empty string ``""`` when unavailable.
+
+All three are unconditional ``200 OK``.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    "0.3.1-ca79ea33"
+
+**HTTP status codes:**
+
+- ``200``: version string returned (unconditional for all three routes).
+
+**Examples:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/version
+    curl -s http://localhost:8080/lmc_version
+    curl -s http://localhost:8080/commit_id
+
+Cache Management
+----------------
+
+``POST /cache/clear``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Force-clears **all** KV cache data currently held in a tier (today ``l1``).
+
+.. warning::
+
+   This endpoint is destructive and bypasses read/write locks. In-flight
+   store or prefetch operations may be corrupted. Use only when the
+   server is idle, or when recovering from a known-bad cache state.
+
+**Request body:** optional -- an absent (or empty) body uses the defaults below.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 14 68
+
+   * - Field
+     - Type
+     - Description
+   * - ``tier``
+     - string
+     - Optional (default ``l1``). Tier to clear; today only ``l1`` is
+       supported. Any other value returns ``400``.
+   * - ``force``
+     - bool
+     - Optional (default ``true``). Currently accepted but **not honored** --
+       the clear always force-clears (active locks are ignored) regardless of
+       this value.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"status": "ok", "cleared": {"tier": "l1"}}
+
+**HTTP status codes:**
+
+- ``200``: tier cleared.
+- ``400``: unsupported ``tier`` (anything other than ``l1``).
+- ``503``: server not initialized (``{"detail": "server not initialized"}``).
+
+**Example:**
+
+.. code-block:: bash
+
+    # the body is optional; this clears the default tier (l1)
+    curl -s -X POST http://localhost:8080/cache/clear
+
+``POST /cache/checksums``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Compute MD5 checksums over the engine KV cache, grouped ``chunk_size`` blocks
+per hashed chunk. MP mode addresses KV storage by block IDs natively (the
+same units used by ``STORE`` / ``RETRIEVE``), so the endpoint is fully
+block-centric. Intended for diagnostics and round-trip integrity checks from
+``lmcache bench server`` -- not for the inference data path.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Field
+     - Required
+     - Description
+   * - ``block_ids``
+     - yes
+     - Engine block IDs as a JSON list of ints, e.g. ``[0, 1, 2, 3]``.
+   * - ``chunk_size``
+     - yes
+     - Positive integer — number of blocks per hashed chunk.
+   * - ``instance_id``
+     - no (default ``0``)
+     - Registered KV context ID on the engine.
+   * - ``layerwise``
+     - no (default ``false``)
+     - If ``true``, return per-layer checksums keyed by ``"layer_<idx>"``;
+       otherwise a single aggregated digest per chunk over all layers.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "status": "success",
+      "chunk_size": 2,
+      "num_chunks": 2,
+      "chunk_checksums": ["<md5>", "<md5>"],
+      "layerwise": false,
+      "block_id_ranges": "0,[2,5],8"
+    }
+
+When ``layerwise=true``, ``chunk_checksums`` is a dict keyed by
+``"layer_<idx>"`` whose values are per-layer lists.
+
+**HTTP status codes:**
+
+- ``200``: success.
+- ``400``: ``block_ids`` empty, or ``chunk_size`` missing or non-positive.
+- ``404``: ``instance_id`` not registered, or the registered KV tensors
+  are empty.
+- ``501``: engine has no ``cache_contexts``, or the KV format is not
+  supported by this endpoint (page-buffer-fused and cross-layer layouts
+  are declined until a real need appears).
+- ``503``: engine not yet initialized on ``app.state``.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:8080/cache/checksums \
+        -H 'Content-Type: application/json' \
+        -d '{"block_ids": [0, 1, 2, 3], "chunk_size": 2}'
+
+.. _mp-http-l2-keys-api:
+
+Cache Objects And Prefetch
+--------------------------
+
+Two endpoints — ``DELETE /cache/objects`` and ``GET /cache/objects`` — let
+operators purge keys from a configured cache backend and enumerate what is
+currently resident. (To enumerate the configured backends themselves, use
+``GET /config/adapters`` in the config group.)
+
+A further pair — ``POST /cache/prefetches`` and
+``GET /cache/prefetches/{request_id}`` — lets an operator (or the
+coordinator) **pre-warm** a node's L1 from L2 ahead of traffic and poll
+the load to completion; they are documented at the end of this section.
+The coordinator exposes an ``instance_id``-routed variant of both — see
+:doc:`coordinator`.
+
+Both object endpoints take an optional ``adapter`` selector — a query
+parameter on ``GET /cache/objects`` (``?adapter=<type_name>``) and a body
+field on ``DELETE /cache/objects``. Omit it to target the **primary**
+(first-configured) adapter. When multiple adapters share a ``type_name``,
+the first match wins. Use ``GET /config/adapters`` to learn the valid
+selectors.
+
+Both are intended for operator / admin workflows ("purge this
+user's keys", "show me what's resident", "garbage-collect orphans
+after a rename"). They are **not** on the inference data path.
+
+L1 is intentionally not touched. Keys deleted from L2 may still return
+from L1 until the L1 eviction controller expires them naturally;
+callers that need an L1+L2 purge should layer their own L1
+invalidation or wait for natural L1 eviction.
+
+The coordinator's eviction loop uses ``DELETE /cache/objects`` automatically (see
+:doc:`coordinator` — "L2 usage tracking and eviction"); the
+``GET /cache/objects`` endpoint also powers the coordinator's startup
+resync. Manual ``curl`` usage is reserved for ad-hoc operator
+actions and debugging.
+
+``DELETE /cache/objects``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Delete a caller-supplied list of keys from one tier/adapter.
+Idempotent: keys absent from the adapter are skipped silently; keys
+currently locked by in-flight store/load tasks are skipped so the
+delete never corrupts an active transfer. The blocking adapter call is
+run off the event loop.
+
+Per-key successful deletions fire ``on_l2_keys_deleted`` on the
+adapter's listeners — when the coordinator is wired (see
+``--coordinator-l2-event-reporting``), the deletions show up at the
+coordinator's ``POST /quota/events`` as ``"type": "delete"`` events. The
+coordinator's eviction + usage trackers learn about the deletion from
+that event flow, not from the response of this call.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 14 68
+
+   * - Field
+     - Type
+     - Description
+   * - ``keys``
+     - list[EncodedObjectKey]
+     - Required. The object keys to delete (schema below). The batch is
+       capped at ``10000`` keys per request.
+   * - ``tier``
+     - string
+     - Optional (default ``l2``). The only supported value.
+   * - ``adapter``
+     - string
+     - Optional (default: primary, first-configured adapter). The
+       ``type_name`` of the target adapter (see ``GET /config/adapters``).
+
+Each ``EncodedObjectKey`` is
+
+.. code-block:: json
+
+    {
+      "chunk_hash_hex": "abc123...",
+      "model_name": "meta-llama/Llama-3-8B",
+      "kv_rank": 0,
+      "object_group_id": 0,
+      "cache_salt": "user-a"
+    }
+
+``object_group_id`` (default ``0``) and ``cache_salt`` (default ``""``)
+are optional for backward compatibility with older wire payloads.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "requested": 2,
+      "adapter": "S3L2Adapter",
+      "ok": true
+    }
+
+On adapter-level failure the response is still ``200`` with
+``ok=false`` and an ``error`` field carrying the reason.
+
+**HTTP status codes:**
+
+- ``200``: request reached the adapter (check ``ok`` for outcome).
+- ``400``: batch exceeds the limit, or a key payload violates an
+  ``ObjectKey`` invariant (bad hex, ``@`` in ``model_name``, forbidden
+  ``cache_salt`` character).
+- ``404``: ``adapter`` (body) does not match any configured adapter.
+- ``422``: Pydantic-level body-shape failure (missing ``keys``,
+  wrong field types).
+- ``503``: engine not initialized, or no L2 adapters configured.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X DELETE http://localhost:8080/cache/objects \
+        -H 'Content-Type: application/json' \
+        -d '{
+            "keys": [
+              {"chunk_hash_hex": "aa", "model_name": "m",
+               "kv_rank": 0, "object_group_id": 0, "cache_salt": "user-a"}
+            ]
+        }'
+
+``GET /cache/objects``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Paginate keys currently resident in one L2 adapter.
+
+**Query parameters:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 13 65
+
+   * - Name
+     - Default
+     - Description
+   * - ``adapter``
+     - primary
+     - ``type_name`` of the target adapter (see ``GET /config/adapters``).
+       Omit to target the primary (first-configured) adapter. First
+       match wins when multiple adapters share a ``type_name``.
+   * - ``model_name``
+     - none
+     - Restrict the result to keys whose ``model_name`` matches.
+   * - ``page_size``
+     - ``500``
+     - Max entries per page. Must be in ``[1, 5000]``; an out-of-range
+       value is rejected with ``422`` (it is not silently clamped).
+   * - ``page_token``
+     - none
+     - Opaque cursor from the previous page's ``next_page_token``.
+       Omit on the first call; pass back verbatim on subsequent calls.
+
+The page token is private to the adapter; do not parse or modify it.
+Adapters that support listing (currently only the S3 adapter via
+``ListObjectsV2``) guarantee best-effort consistency, not snapshot
+isolation — concurrent stores or deletes during a paginated walk may
+cause keys to appear, disappear, or shift between pages.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "adapter": "S3L2Adapter",
+      "entries": [
+        {
+          "key": {
+            "chunk_hash_hex": "abc123",
+            "model_name": "meta-llama/Llama-3-8B",
+            "kv_rank": 0,
+            "object_group_id": 0,
+            "cache_salt": "user-a"
+          },
+          "size_bytes": 4194304
+        }
+      ],
+      "next_page_token": "opaque-cursor-string"
+    }
+
+``next_page_token`` is ``null`` when the listing is exhausted.
+
+**HTTP status codes:**
+
+- ``200``: success.
+- ``400``: malformed ``page_token`` (adapter-level).
+- ``404``: ``?adapter=<name>`` does not match any configured adapter.
+- ``422``: ``page_size`` outside ``[1, 5000]``.
+- ``501``: selected adapter does not implement listing. In v1 only
+  ``S3L2Adapter`` does; adapters wrapped by ``SerdeL2AdapterWrapper``
+  inherit the wrapped adapter's behavior.
+- ``503``: engine not initialized, or no L2 adapters configured.
+
+**Example:** paginate every key for a model.
+
+.. code-block:: bash
+
+    next=""
+    while :; do
+      page=$(curl -s "http://localhost:8080/cache/objects?model_name=meta-llama/Llama-3-8B&page_size=500&page_token=$next")
+      echo "$page" | jq '.entries[]'
+      next=$(echo "$page" | jq -r '.next_page_token // empty')
+      [ -z "$next" ] && break
+    done
+
+``POST /cache/prefetches``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Warm one node's L1 by loading a token sequence's chunks from L2 **ahead** of
+the requests that will use them, so the first request hits L1 instead of
+paying the L2 fetch inline. Useful when a workload is about to be routed to a
+node (a traffic shift, a hot shared system prompt).
+
+The caller describes content by **token ids**, never by internal cache keys (a
+key is a content hash plus a per-rank layout bitmap, which callers cannot
+construct). The server hashes the tokens, expands each chunk across the node's
+ranks, and submits a *warm* prefetch: loaded chunks are **retained**
+(permanent) and left **unlocked** — there is no downstream reader to pin them
+for, so a later real lookup takes its own lock. The call returns immediately;
+the load runs in the storage manager's own thread. It coalesces across all
+configured L2 adapters, so there is no ``?adapter=`` selector.
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 12 68
+
+   * - Field
+     - Type
+     - Description
+   * - ``model_name``
+     - string
+     - The served model id, exactly as registered (e.g. ``Qwen/Qwen3-8B``).
+   * - ``world_size``
+     - int
+     - The value vLLM registered for the node's KV layout and rank fan-out
+       (``1`` for a single-GPU, TP=1 deployment).
+   * - ``token_ids``
+     - list[int]
+     - The prompt token ids. Must use the same tokenizer / special-token
+       settings as the store, and contain at least one full ``chunk_size`` of
+       tokens — only complete chunks are warmed.
+   * - ``cache_salt``
+     - string
+     - Per-tenant key isolation; must match the store (default ``""``).
+
+**Response** (``202 Accepted``):
+
+.. code-block:: json
+
+    {"request_id": "abc123", "chunks": 12, "status": "submitted"}
+
+When the sequence is shorter than one chunk, nothing is submitted and there is
+no ``request_id`` to poll:
+
+.. code-block:: json
+
+    {"chunks": 0, "status": "noop"}
+
+**HTTP status codes:**
+
+- ``202``: submitted (or a ``noop`` as above).
+- ``400``: ``token_ids`` exceeds the per-request cap, or ``cache_salt``
+  violates its invariants.
+- ``409``: no layout registered for ``(model_name, world_size)`` — the model
+  has not allocated KV cache on this node yet (start vLLM first).
+- ``422``: request body fails field-level validation.
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:8080/cache/prefetches \
+        -H 'Content-Type: application/json' \
+        -d '{"model_name": "Qwen/Qwen3-8B", "world_size": 1,
+             "token_ids": [101, 102, 103], "cache_salt": "user-a"}'
+    # -> {"request_id": "abc123", "chunks": 1, "status": "submitted"}
+
+``GET /cache/prefetches/{request_id}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Poll a submitted warm prefetch. The warm holds no lock, so the poll only
+reports progress; the first poll that observes completion drops the job
+(exactly-once), so a later poll for the same id returns ``404``.
+
+**Response** (``200 OK``) while the load runs:
+
+.. code-block:: json
+
+    {"status": "pending"}
+
+…and once complete:
+
+.. code-block:: json
+
+    {"status": "completed", "found_keys": 12, "total_keys": 12}
+
+``found_keys`` / ``total_keys`` count only chunks **loaded from L2** by this
+request; chunks already resident in L1 are skipped at ``reserve_write`` and not
+counted, so a partially-resident warm undercounts by the resident chunk count
+(a cold request loads and counts everything). The warm uses the gap-tolerant
+``SPARSE`` trim policy, so an already-resident chunk does not stop the rest from
+loading — it loads every not-yet-resident chunk and reports that count. Not
+counting the resident chunks is deliberate: an already-present entry may be a
+transient temporary from another lookup, so claiming it as warmed could mislead.
+
+**HTTP status codes:**
+
+- ``200``: status reported (``pending`` or ``completed``).
+- ``404``: unknown ``request_id`` — already completed-and-consumed, or never
+  submitted.
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/cache/prefetches/abc123
+    # -> {"status": "completed", "found_keys": 1, "total_keys": 1}
+
+.. _mp-http-quota-api:
+
+Quota Management
+----------------
+
+These endpoints manage the per-``cache_salt`` storage budgets consumed by
+the ``IsolatedLRU`` eviction policy (selected via
+``--eviction-policy IsolatedLRU``). Quotas are **soft**: setting a limit
+does not reject writes — any over-budget ``cache_salt`` is evicted at
+the next eviction cycle (~1 s).
+A ``cache_salt`` with no registered quota has an effective limit of
+``0`` bytes, so its data is cleared next cycle (allowlist semantics).
+
+These endpoints are no-ops on engines that did not start with
+``--eviction-policy IsolatedLRU``: the ``QuotaManager`` is still
+present, but the LRU policy ignores the registered quotas.
+
+**URL escaping for the empty salt.** ``cache_salt=""`` (un-salted /
+anonymous traffic) cannot appear in a URL path parameter, so the API
+accepts the sentinel ``_default`` in its place. ``PUT /quota/_default``
+sets the quota for ``cache_salt=""``, and ``_default`` is echoed back in
+responses for the empty salt. A user that legitimately stores data with
+``cache_salt="_default"`` cannot be managed via this HTTP API distinctly
+from anonymous traffic — both map to the same path parameter; pick any
+other value (e.g. ``"default"``) to disambiguate.
+
+``PUT /quota/{cache_salt}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create or update a quota.
+
+**Path parameters:** ``cache_salt`` — tenant identifier (use ``_default``
+for the empty salt; see the section intro).
+
+**Request body:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 14 68
+
+   * - Field
+     - Type
+     - Description
+   * - ``limit_gb``
+     - float
+     - Required. The quota in GB. Must be finite and non-negative.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"cache_salt": "alice", "limit_gb": 10.0, "status": "ok"}
+
+**HTTP status codes:**
+
+- ``200``: quota set or updated.
+- ``400``: malformed JSON, missing ``limit_gb``, non-numeric ``limit_gb``,
+  ``nan`` / ``inf``, or a negative value.
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X PUT http://localhost:8080/quota/alice \
+        -H 'Content-Type: application/json' \
+        -d '{"limit_gb": 10.0}'
+
+``GET /quota/{cache_salt}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Read the current quota and live usage for one ``cache_salt``.
+
+**Path parameters:** ``cache_salt`` — tenant identifier (use ``_default``
+for the empty salt).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "cache_salt": "alice",
+      "limit_gb": 10.0,
+      "current_usage_gb": 2.137,
+      "exists": true
+    }
+
+``exists`` is ``false`` when no quota was ever registered for this
+``cache_salt`` (``limit_gb`` is then ``0.0`` and ``current_usage_gb``
+reflects whatever bytes are currently cached for that salt — those bytes
+will evict next cycle under ``IsolatedLRU``). This endpoint never returns
+``404`` for an unknown salt.
+
+**HTTP status codes:**
+
+- ``200``: quota and usage returned (also when the salt has no registered
+  quota — ``exists`` is then ``false``; never ``404``).
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/quota/alice | jq
+
+``DELETE /quota/{cache_salt}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Remove a ``cache_salt``'s quota entry. Any bytes still cached under this
+``cache_salt`` become over-budget on the next eviction cycle (effective
+limit drops to ``0``) and will be evicted.
+
+**Path parameters:** ``cache_salt`` — tenant identifier (use ``_default``
+for the empty salt).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {"cache_salt": "alice", "status": "removed"}
+
+When no quota was registered for the given ``cache_salt``, the response
+is ``{"cache_salt": "...", "status": "not_found"}`` (still ``200 OK``).
+
+**HTTP status codes:**
+
+- ``200``: quota entry removed (``"removed"``) or none existed
+  (``"not_found"``); never ``404``.
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X DELETE http://localhost:8080/quota/alice
+
+``GET /quota``
+~~~~~~~~~~~~~~~~~~
+
+List every registered quota alongside its live usage.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "users": {
+        "alice": {"limit_gb": 10.0, "current_usage_gb": 2.137},
+        "bob":   {"limit_gb":  4.0, "current_usage_gb": 0.812}
+      }
+    }
+
+Only ``cache_salt`` values with a **registered** quota appear; the empty
+salt is reported under the ``_default`` key.
+
+**HTTP status codes:**
+
+- ``200``: quota listing returned (``{"users": {}}`` when none registered).
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/quota | jq
+
+.. _mp-http-dax-api:
+
+Runtime L2 Reconfiguration
+--------------------------
+
+These endpoints are available when the server has a runtime-reconfigurable L2
+adapter. They only change LMCache runtime mappings and metadata; backend
+resources such as DAX device paths must already exist and be readable and
+writable by the server. The endpoint routes ``backend``, ``operation``, and the
+JSON request body into the generic L2 adapter reconfiguration API, while
+backend-specific validation and migration semantics stay inside the adapter.
+
+``backend`` and ``operation`` path segments are normalized (stripped and
+lower-cased). Within a request body, ``adapter_index`` (default ``0``) is
+**backend-local** — it indexes only the adapters of that backend, not the
+engine-wide adapter list. If an L2 adapter is wrapped by serde, the backend
+string is still the configured L2 adapter type, not the serde wrapper type.
+
+.. note::
+
+   The backend strings accepted here are discovered via
+   ``GET /config/adapters``: each adapter whose ``reconfigurable`` flag is
+   ``true`` can be addressed by its ``type_name``.
+
+``GET /reconfigure/{backend}/status``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Report the runtime-manageable adapters for one backend type. Each adapter
+entry's ``adapter_index`` is rewritten to its **backend-local** 0-based index
+(the value to pass back in operation request bodies).
+
+**Path parameters:** ``backend`` — adapter ``type_name`` (normalized:
+stripped and lower-cased; discover valid values via ``GET /config/adapters``).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "enabled": true,
+      "backend": "dax",
+      "num_adapters": 1,
+      "adapters": [
+        {"adapter_index": 0, "...": "backend-specific adapter fields"}
+      ]
+    }
+
+An unknown or empty backend returns ``enabled=false``, ``num_adapters=0``,
+``adapters=[]`` (it is **not** a ``404``).
+
+**HTTP status codes:**
+
+- ``200``: status returned (including the unknown-backend case above).
+- ``400``: ``backend`` is empty.
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/reconfigure/dax/status | jq
+
+``POST /reconfigure/{backend}/{operation}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Apply one reconfiguration operation to a backend adapter. The request body is
+a JSON object whose accepted fields depend on the backend and operation. The
+``200`` response is whatever the storage manager's
+``reconfigure_l2_adapter`` returns (a backend-defined dict).
+
+**Path parameters:** ``backend`` (adapter ``type_name``) and ``operation``
+(e.g. ``add`` / ``remove`` / ``resize`` for ``dax``). Both are normalized
+(stripped and lower-cased).
+
+For the **generic** path (any backend other than ``dax``), the body carries
+``adapter_index`` plus any backend-specific fields, which are forwarded
+verbatim to the adapter.
+
+For **Device-DAX** (``backend=dax``), JSON request bodies are used because DAX
+paths contain slashes. The accepted operations and fields are:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Operation
+     - Body fields
+   * - ``add``
+     - ``device_path`` (str, required), ``size`` (int byte count or string
+       such as ``"100GiB"``, required), ``adapter_index`` (default ``0``).
+   * - ``remove``
+     - ``device_path`` (str, required), ``mode`` (``migrate`` | ``evict`` |
+       ``drain``, default ``migrate``), ``force`` (bool, default ``false``),
+       ``adapter_index`` (default ``0``).
+   * - ``resize``
+     - ``device_path`` (str, required), ``size`` (int or string, required),
+       ``mode`` (``migrate`` | ``evict``, default ``migrate``), ``force``
+       (bool, default ``false``), ``adapter_index`` (default ``0``).
+
+``size`` accepts an integer byte count or a string with a base-1024 unit
+suffix (``b``, ``kib``, ``mib``, ``gib``, ``tib`` and the ``k``/``m``/``g``/``t``
+aliases), e.g. ``"100GiB"``; it must resolve to a positive value.
+
+**Response** (``200 OK``):
+
+The body is the backend's ``reconfigure_l2_adapter`` result (a backend-defined
+dict). A successful DAX ``add`` looks like:
+
+.. code-block:: json
+
+    {
+      "status": "ok",
+      "operation": "add",
+      "adapter_index": 0,
+      "device": {"device_path": "/dev/dax0.0", "state": "active", "size_bytes": 107374182400}
+    }
+
+**HTTP status codes:**
+
+- ``200``: success (body is the storage manager's reconfigure result).
+- ``400``: empty ``backend``/``operation``, an unsupported DAX operation, or
+  an invalid ``size``.
+- ``404``: ``adapter_index`` is out of range for the backend.
+- ``422``: request body fails validation (e.g. a missing required field, or
+  an unknown field in a DAX body — DAX bodies reject extras).
+- ``503``: engine not initialized.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:8080/reconfigure/dax/add \
+        -H 'Content-Type: application/json' \
+        -d '{"device_path": "/dev/dax0.0", "size": "100GiB"}'
+
+See :doc:`/kv_cache/storage_backends/dax` for detailed request examples,
+mode semantics, and validation guidance.
+
+Observability
+-------------
+
+``GET /metrics``
+~~~~~~~~~~~~~~~~
+
+Prometheus exposition format for every metric registered on the default
+``prometheus_client`` registry (``Content-Type: text/plain``). Scrape this
+directly from Prometheus. See :doc:`observability/index` for the list of
+exported metrics.
+
+**Response** (``200 OK``, ``text/plain``): the Prometheus exposition-format
+metrics body.
+
+**HTTP status codes:**
+
+- ``200``: metrics returned.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/metrics
+
+``POST /metrics/reset``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Resets all LMCache observability metrics to their initial state
+(``reset_observability_metrics``). Intended for test harnesses and
+benchmarks — not for production.
+
+**Response** (``200 OK``, ``text/plain``):
+
+.. code-block:: text
+
+    ok
+
+**HTTP status codes:**
+
+- ``200``: metrics reset.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:8080/metrics/reset
+
+Diagnostics and Debugging
+-------------------------
+
+``GET /loglevel``
+~~~~~~~~~~~~~~~~~
+
+Inspect or mutate Python logger levels at runtime. All responses are
+``text/plain``. The endpoint has three modes driven by query parameters:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Query
+     - Behavior
+   * - (no params)
+     - List every logger registered with :mod:`logging` and its level.
+   * - ``?logger_name=<name>``
+     - Return the effective level of the named logger.
+   * - ``?logger_name=<name>&level=<LEVEL>``
+     - Set the named logger (and its handlers) to ``LEVEL``
+       (``DEBUG``/``INFO``/``WARNING``/``ERROR``/``CRITICAL``;
+       case-insensitive). Returns ``400`` on an unknown level.
+
+Passing ``level`` without ``logger_name`` matches none of the modes and
+returns ``200`` with a ``null`` body.
+
+**Response** (``200 OK``, ``text/plain``): one ``<logger>: <LEVEL>`` line per
+registered logger (list mode), a single ``<logger>: <LEVEL>`` (read mode), or a
+confirmation of the updated level (set mode).
+
+**HTTP status codes:**
+
+- ``200``: levels listed, read, or set (also the ``null``-body case above).
+- ``400``: ``level`` is not a known logging level.
+
+**Examples:**
+
+.. code-block:: bash
+
+    # list everything
+    curl -s http://localhost:8080/loglevel
+
+    # read one
+    curl -s 'http://localhost:8080/loglevel?logger_name=lmcache'
+
+    # elevate to DEBUG
+    curl -s 'http://localhost:8080/loglevel?logger_name=lmcache&level=DEBUG'
+
+``GET /threads``
+~~~~~~~~~~~~~~~~
+
+Enumerate active Python threads in the server process along with their
+stack traces, plus a total-count summary (``Content-Type: text/plain``).
+Useful for live debugging of hangs or runaway workers.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Query
+     - Behavior
+   * - ``?name=<substr>``
+     - Keep only threads whose name contains ``<substr>``
+       (case-insensitive).
+   * - ``?thread_id=<int>``
+     - Keep only the thread with the matching ``ident``.
+
+.. warning::
+
+   The response contains live stack traces and can disclose internal code
+   paths and state. Restrict network access to this endpoint in production.
+
+**Response** (``200 OK``, ``text/plain``): a total-thread-count summary followed
+by each thread's name, ``ident``, and current stack trace.
+
+**HTTP status codes:**
+
+- ``200``: thread listing returned.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s 'http://localhost:8080/threads?name=periodic'
+
+``GET /periodic-threads``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Returns a JSON snapshot of the
+:class:`~lmcache.v1.periodic_thread.PeriodicThreadRegistry`: counts by
+level plus per-thread status (last run timestamp, latest summary, etc.).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Query
+     - Behavior
+   * - ``?level=critical|high|medium|low``
+     - Only include threads at the given level. ``400`` on unknown.
+   * - ``?running_only=true``
+     - Only include threads currently running.
+   * - ``?active_only=true``
+     - Only include threads considered active (recent tick).
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "summary": {
+        "total_count": 4,
+        "running_count": 4,
+        "active_count": 4,
+        "by_level": {
+          "critical": {"total": 1, "running": 1, "active": 1},
+          "high":     {"total": 2, "running": 2, "active": 2},
+          "medium":   {"total": 1, "running": 1, "active": 1},
+          "low":      {"total": 0, "running": 0, "active": 0}
+        }
+      },
+      "threads": [
+        {
+          "name": "...",
+          "level": "high",
+          "interval": 5.0,
+          "is_running": true,
+          "is_active": true,
+          "last_run_ago": 1.2,
+          "total_runs": 120,
+          "failed_runs": 0,
+          "success_rate": 100.0,
+          "last_summary": {"...": "..."}
+        }
+      ]
+    }
+
+**HTTP status codes:**
+
+- ``200``: snapshot returned.
+- ``400``: unknown ``level`` filter.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s 'http://localhost:8080/periodic-threads?level=critical' | jq
+
+``GET /periodic-threads/{thread_name}``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Detailed status for a single periodic thread (the same per-thread object
+shown in the ``threads`` list above).
+
+**Path parameters:** ``thread_name`` — the registered periodic thread name.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "name": "storage-flush",
+      "level": "critical",
+      "interval": 5.0,
+      "is_running": true,
+      "is_active": true,
+      "last_run_ago": 1.2,
+      "total_runs": 120,
+      "failed_runs": 0,
+      "success_rate": 100.0,
+      "last_summary": {"...": "..."}
+    }
+
+**Response** (``404 Not Found``) when the name is unknown:
+
+.. code-block:: json
+
+    {"error": "Thread not found: <name>"}
+
+**HTTP status codes:**
+
+- ``200``: thread status returned.
+- ``404``: no periodic thread with that name.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/periodic-threads/storage-flush | jq
+
+``GET /periodic-threads-health``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Fast health check covering only ``critical`` and ``high`` level periodic
+threads. A thread is flagged unhealthy when it is marked running but has
+not ticked within its expected interval. Always returns ``200`` — health
+is conveyed by the ``healthy`` boolean, not the HTTP status.
+
+**Response** (``200 OK``):
+
+.. code-block:: json
+
+    {
+      "healthy": true,
+      "unhealthy_count": 0,
+      "unhealthy_threads": []
+    }
+
+When something is lagging:
+
+.. code-block:: json
+
+    {
+      "healthy": false,
+      "unhealthy_count": 1,
+      "unhealthy_threads": [
+        {
+          "name": "storage-flush",
+          "level": "critical",
+          "last_run_ago": 42.5,
+          "interval": 5.0
+        }
+      ]
+    }
+
+**HTTP status codes:**
+
+- ``200``: health reported — always ``200``, even when unhealthy
+  (the ``healthy`` boolean is ``false``).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/periodic-threads-health
+
+``GET /env``
+~~~~~~~~~~~~
+
+Dumps the process environment variables as a sorted, pretty-printed
+JSON document. The response ``Content-Type`` is ``text/plain`` so it can be
+piped directly to a terminal.
+
+.. warning::
+
+   The payload contains **every** environment variable, including any
+   secrets injected via the environment. There is no redaction or auth —
+   restrict network access to this endpoint in production.
+
+**Response** (``200 OK``, ``text/plain``):
+
+.. code-block:: json
+
+    {
+      "HOME": "/root",
+      "LMCACHE_LOG_LEVEL": "INFO",
+      "PATH": "/usr/local/bin:/usr/bin"
+    }
+
+**HTTP status codes:**
+
+- ``200``: environment dump returned.
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s http://localhost:8080/env
+
+``POST /run_script``
+~~~~~~~~~~~~~~~~~~~~
+
+Execute an uploaded Python script inside the server process. The script is
+uploaded as multipart form data under the field name ``script`` and is
+``exec``'d with a restricted ``__builtins__`` (only ``print``, ``str``,
+``int``, ``float``, ``list``, ``dict``, ``tuple``, ``set``, and a guarded
+``__import__``). Only modules listed in ``--script-allowed-imports`` can be
+imported; the running FastAPI ``app`` is injected into the script globals.
+If the script assigns a variable named ``result``, its stringified value is
+returned; otherwise the body is ``"Script executed successfully"``
+(``Content-Type: text/plain``).
+
+**Request body:** multipart form data with a single ``script`` file field
+(the Python source to execute). Not a JSON body.
+
+.. danger::
+
+   This endpoint runs caller-supplied code in-process. The restricted
+   builtins are **not** a security sandbox — combined with the injected
+   ``app`` object and any allowed imports, treat it as full remote code
+   execution. Never expose it on an untrusted network.
+
+**Response** (``200 OK``, ``text/plain``): the stringified ``result`` variable if
+the script assigns one, otherwise ``Script executed successfully``.
+
+**HTTP status codes:**
+
+- ``200``: script executed.
+- ``400``: no ``script`` file provided.
+- ``500``: an exception was raised during import setup or execution
+  (body: ``"Error executing script: <reason>"``).
+
+**Example:**
+
+.. code-block:: bash
+
+    curl -s -X POST http://localhost:8080/run_script \
+        -F 'script=@my_script.py'
+
+Adding New Endpoints
+--------------------
+
+Endpoints are auto-discovered from
+``lmcache/v1/multiprocess/http_apis/``. To add a new MP-only endpoint:
+
+1. Create a new module in that directory named ``<name>_api.py``.
+2. Define a module-level ``router = APIRouter()``.
+3. Register handlers on ``router`` using FastAPI decorators.
+4. Access the engine via ``request.app.state.engine`` and guard for the
+   ``None`` case (engine not yet initialized).
+
+The :class:`~lmcache.v1.multiprocess.http_api_registry.HTTPAPIRegistry`
+will pick the module up automatically at startup — no central
+registration list to edit.
+
+If the route is generic enough to be shared with the vLLM-embedded API
+server, add it under ``lmcache/v1/internal_api_server/common/`` instead.
+It will be picked up on the MP side via ``common_api.py`` unless its
+module name is listed in ``_MP_INCOMPATIBLE_MODULES`` there (reserved
+for modules that require vLLM-specific ``app.state`` attributes; the
+list is currently empty). A handler that lives under
+``internal_api_server/vllm/`` can still be surfaced on the MP server by
+including its router from a group module under ``http_apis/`` (as
+``info_api.py`` does for the version endpoints).
+
+When adding a new endpoint, please also add a matching section to this
+page documenting the endpoint's purpose, request/response schema, and
+an example ``curl`` invocation.
diff --git a/docs/source/mp/hybrid_models.rst b/docs/source/mp/hybrid_models.rst
new file mode 100644
index 0000000..78c880a
--- /dev/null
+++ b/docs/source/mp/hybrid_models.rst
@@ -0,0 +1,281 @@
+Hybrid Attention Models
+=======================
+
+Some models interleave more than one attention type across their layers — most
+commonly **sliding-window attention** on most layers and **full attention** on a
+few. vLLM serves these with its *hybrid KV cache manager*, which splits the
+model's layers into multiple **KV cache groups** (one per attention behavior).
+
+The LMCache multiprocess connector (``LMCacheMPConnector``) supports these
+hybrid models: it stores and retrieves the KV cache for every group, so prefix
+caching and KV reuse work the same way they do for plain models.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Validated hybrid models
+-----------------------
+
+Recipe pages for the validated hybrid-attention architectures:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 34 32
+
+   * - Model
+     - Attention layout
+     - Recipe
+   * - Gemma 3
+     - Sliding-window + full
+     - :doc:`/recipes/gemma3`
+   * - Gemma 4
+     - Sliding-window + full
+     - :doc:`/recipes/gemma4`
+   * - gpt-oss
+     - Sliding-window + full
+     - :doc:`/recipes/gpt_oss`
+   * - Qwen3.5 / Qwen3.6 series
+     - Mamba / GDN + full
+     - :doc:`/recipes/qwen3_5`
+   * - DeepSeek-V4-Flash
+     - Sparse-MLA (multiple KV groups)
+     - :doc:`/recipes/deepseek_v4_flash`
+   * - GLM 5.1/5.2
+     - Dynamic Sparse Attention (multiple KV groups)
+     - :doc:`/recipes/glm5_2`
+   * - MiniMax-M3
+     - Sparse attention + lightning indexer (mixed KV formats in one group)
+     - :doc:`/recipes/minimax_m3`
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   /recipes/gemma3
+   /recipes/gemma4
+   /recipes/gpt_oss
+   /recipes/qwen3_5
+   /recipes/deepseek_v4_flash
+   /recipes/glm5_2
+   /recipes/minimax_m3
+
+What Works
+----------
+
+Models whose layers all use **standard paged attention** — including hybrids
+that mix sliding-window and full attention — are supported with no special
+configuration. Examples:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 30 35
+
+   * - Model family
+     - Attention layout
+     - Status
+   * - Gemma 2 / Gemma 3
+     - Interleaved sliding-window + full
+     - Supported
+   * - gpt-oss
+     - Interleaved sliding-window + full
+     - Supported
+   * - Qwen3.5 (and other Gated-DeltaNet hybrids)
+     - Interleaved Mamba/GDN + full
+     - Supported (see below)
+   * - Llama, Qwen2/Qwen3 (dense), Mistral, …
+     - Single attention type
+     - Supported
+
+Just point vLLM at the LMCache server as usual (see :doc:`/getting_started/quickstart`); LMCache
+detects the model's KV cache groups automatically at registration time.
+
+.. note::
+
+   Because ``LMCacheMPConnector`` advertises hybrid support to vLLM, vLLM keeps
+   its hybrid KV cache manager **enabled** for these models (it does not fall
+   back to a single unified group). You do not need
+   ``--no-disable-hybrid-kv-cache-manager`` or any related flag.
+
+Object-group separation
+-----------------------
+
+At KV-cache registration LMCache buckets a hybrid model's layers into **object
+groups** — the unit it stores and retrieves as one object. By default
+(``--separate-object-groups``, on) each distinct cross-chunk attention window
+becomes its own object group: full-attention layers form one group, and each
+sliding-window size (mamba / GDN included) forms another. Pass
+``--no-separate-object-groups`` to keep every layer in a single full-attention
+object group instead (the previous behavior).
+
+.. code-block:: bash
+
+   # default: one object group per attention window
+   lmcache server --chunk-size 256 --l1-size-gb 100
+
+   # opt out: a single full-attention object group for all layers
+   lmcache server --chunk-size 256 --l1-size-gb 100 --no-separate-object-groups
+
+The flag is transparent to correctness — prefix caching and KV reuse behave the
+same either way, and a non-hybrid model (a single attention behavior) always
+resolves to one object group regardless of the setting. Separation organizes
+storage by attention window so that each group's cross-chunk window is tracked
+independently.
+
+Mamba / Linear-Attention Hybrids
+--------------------------------
+
+Models that interleave **Mamba / Gated-DeltaNet (GDN) linear-attention layers**
+with full attention — the Qwen3.5 and Qwen3.6 series (``Qwen/Qwen3.5-0.8B``,
+``Qwen/Qwen3.6-27B``, …), Qwen3-Next, and other GDN hybrids — are supported.
+Unlike a paged key/value cache, their linear-attention layers keep a recurrent
+**state cache** (a convolution + SSM state). LMCache reinterprets that state as
+an opaque page at registration time, so prefix caching and KV reuse work end to
+end without any model-specific transfer code.
+
+This section is the **general procedure for any such model**. The only
+per-model variable is the *unified block size* ``N`` (step 1); everything else
+is identical across models.
+
+.. _mamba-block-size:
+
+Step 1 — find the model's unified block size ``N``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``N`` is the **single number** that drives every other setting: the LMCache
+server's ``--chunk-size`` and vLLM's ``--max-num-batched-tokens`` are both
+derived from it (step 2). Get it wrong and LMCache raises at engine startup.
+
+For a Mamba / GDN hybrid, vLLM forces **one** block size across all KV cache
+groups, chosen large enough that an attention page is at least as big as a
+Mamba state page. It depends on the model's head dimensions and GDN state size,
+so it is **model-specific — never assume a value, read it from the model**.
+vLLM prints it once at startup::
+
+    INFO ... interface.py:670] Setting attention block size to 784 tokens to
+    ensure that attention page size is >= mamba page size.
+
+You do not need LMCache, a full serving run, or the weights to be quantized to
+read it — just launch vLLM until the line appears, then stop. The snippet below
+does exactly that and prints ``N``:
+
+.. code-block:: bash
+
+   MODEL=Qwen/Qwen3.6-27B
+   LOG=$(mktemp)
+
+   # Launch vLLM just far enough to size the KV cache; cheap settings only.
+   vllm serve "$MODEL" \
+       --mamba-cache-mode align --enable-prefix-caching \
+       --max-model-len 8192 --gpu-memory-utilization 0.5 \
+       --port 8011 > "$LOG" 2>&1 &
+   VLLM_PID=$!
+
+   # Wait for the block-size line (or a fatal error), then stop vLLM.
+   until grep -qiE "Setting attention block size|Error|Traceback" "$LOG"; do
+       sleep 3
+   done
+   grep -i "Setting attention block size" "$LOG"
+   kill "$VLLM_PID"
+
+The number in ``to N tokens`` is your ``N``. Values grow with model size; for
+example:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 25 25
+
+   * - Model
+     - Unified block size ``N``
+     - GPUs
+   * - ``Qwen/Qwen3.6-27B``
+     - 784
+     - 1
+   * - ``Qwen/Qwen3.5-0.8B``
+     - 544
+     - 1
+
+Step 2 — derive the three required flags from ``N``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. **LMCache server** ``--chunk-size`` **= N** (or any multiple of ``N``). This
+   is the rule the connector enforces: LMCache's chunk size must be a multiple
+   of vLLM's unified block size, or registration fails::
+
+       lmcache server --chunk-size 784 --l1-size-gb 100 --eviction-policy LRU
+
+#. **vLLM** ``--max-num-batched-tokens`` **in [N, 2·N)** — setting it equal to
+   ``N`` is the simple, always-valid choice. Outside this range LMCache raises
+   at engine startup. ``align`` mode snapshots the Mamba state only at the
+   *end* of each scheduler step, so each prefill step must advance exactly one
+   block; a larger budget would let a step skip block boundaries, leaving no
+   snapshot for LMCache to store at those prefixes.
+
+#. **vLLM** ``--mamba-cache-mode align --enable-prefix-caching`` — ``align`` is
+   mandatory (GDN backends do not support the ``all`` mode)::
+
+       vllm serve <model> \
+           --enable-prefix-caching --mamba-cache-mode align \
+           --max-num-batched-tokens 784 \
+           --kv-transfer-config \
+           '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+So for a freshly-probed model the whole derivation is just: read ``N`` (step 1),
+then pass ``--chunk-size N`` to the server and ``--max-num-batched-tokens N`` to
+vLLM.
+
+No ``--no-disable-hybrid-kv-cache-manager`` or attention-backend flag is needed;
+``LMCacheMPConnector`` advertises hybrid support and vLLM auto-selects the GDN
+backend.
+
+Caveats
+^^^^^^^
+
+- Generation is **not bit-exact** between a cached and a fresh run: GDN
+  backends do not support vLLM's batch-invariant mode. Validate with a
+  **score-level** comparison (see `Verifying Correctness`_), not a token-level
+  diff.
+- The cached pages are **byte-opaque**, so content-aware features (CacheGen
+  compression, CacheBlend) do not apply, and cache entries must not be shared
+  across engines with different attention backends or kernel block sizes.
+- Several of these models are **vision-language** (they load a vision tower).
+  The validated, supported path is **text** KV caching; image/video KV caching
+  is not validated.
+- vLLM's Mamba prefix caching in ``align`` mode is marked experimental upstream.
+
+See the :doc:`Qwen3.5 / Qwen3.6 recipe <../recipes/qwen3_5>` for the validated
+end-to-end commands and the per-model block sizes.
+
+What Is Not Supported Yet
+-------------------------
+
+- **DeepSeek-V4-style compressed / indexer caches** are not yet handled by the
+  multiprocess connector.
+
+Verifying Correctness
+---------------------
+
+To convince yourself that a hybrid model's KV is being cached and reused
+correctly, you can compare a cold run against a run served from LMCache:
+
+#. Run an evaluation (e.g. ``lm_eval`` on ``gsm8k``) against vLLM + LMCache.
+   This computes the KV cache and **stores** it in LMCache.
+#. Reset *only* vLLM's local prefix cache, leaving the LMCache-managed cache
+   intact (requires launching vLLM with ``VLLM_SERVER_DEV_MODE=1``)::
+
+       curl -X POST http://localhost:8000/reset_prefix_cache
+
+   Omit the ``reset_external=true`` query parameter so the LMCache cache is
+   preserved.
+#. Re-run the same evaluation. vLLM now misses in its local cache, so the prefix
+   KV is **retrieved** from LMCache. The score should match the first run.
+
+The project ships this as the ``hma_lm_eval`` continuous-integration test (see
+``.buildkite/k3_tests/multiprocess``).
+
+See Also
+--------
+
+- :doc:`/getting_started/quickstart` — launching the LMCache server and a vLLM client.
+- Design notes on how groups are detected and addressed:
+  ``docs/design/integration/vllm/hybrid-kv-cache-groups.md`` in the source tree.
diff --git a/docs/source/mp/index.rst b/docs/source/mp/index.rst
new file mode 100644
index 0000000..40e74df
--- /dev/null
+++ b/docs/source/mp/index.rst
@@ -0,0 +1,642 @@
+Overview
+========
+
+LMCache multiprocess (MP) mode runs LMCache as a **standalone service** that
+vLLM instances connect to over ZMQ.  One LMCache server per node can serve
+multiple vLLM pods, providing process isolation, shared caching, and
+independent resource scaling.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Key Benefits
+------------
+
+- **Process isolation** -- LMCache and vLLM run in separate processes (or
+  containers), so a cache-related issue does not crash the inference engine.
+- **No GIL contention or Python overhead on the inference path** -- By running
+  LMCache in a separate process, its Python GIL and CPU work (hashing,
+  memory management, L2 I/O) do not compete with vLLM's inference threads.
+- **Shared caching across pods** -- Multiple vLLM instances on the same node
+  share a single L1 cache, maximizing KV reuse.
+- **Independent resource scaling** -- Allocate CPU memory for caching
+  independently of GPU memory for inference.
+- **Multi-tier storage (L1 + L2)** -- An L1 cache (in CPU DRAM, or an NVMe
+  slab via GPUDirect Storage) backed by persistent L2 storage via NIXL (GDS,
+  POSIX, HF3FS, and more).
+- **Built-in observability** -- Prometheus metrics and a telemetry event system
+  out of the box.
+
+Prerequisites
+-------------
+
+- **vLLM** latest version is recommended for best compatibility
+- **LMCache** latest dev branch
+
+Server Variants
+---------------
+
+LMCache ships two server entry points:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Entry Point
+     - Description
+   * - ``lmcache server``
+     - **Recommended.** ZMQ + FastAPI HTTP frontend — see :doc:`http_api`.
+   * - ``python3 -m lmcache.v1.multiprocess.server``
+     - (Legacy) ZMQ-only server with no HTTP endpoints; same
+       ``--engine-type`` / ``--supported-transfer-mode`` flags as
+       ``lmcache server``. Prefer ``lmcache server``.
+
+The sections below describe LMCache MP internals -- useful if you want to
+understand, debug, or extend the system.
+
+High-Level Architecture
+-----------------------
+
+.. code-block:: text
+
+    vLLM Instance(s)
+         |
+         | ZMQ (tcp)
+         v
+    MessageQueueServer (mq.py)
+         |
+         | dispatch by RequestType
+         v
+    MPCacheServer (server.py)
+         |
+         |--- TokenHasher / SessionManager
+         |
+         v
+    StorageManager (distributed/storage_manager.py)
+         |
+         |--- L1Manager (l1_manager.py)
+         |       |--- L1MemoryManager (CPU DRAM) or
+         |       |    GDSL1MemoryManager (NVMe slab via cuFile / hipFile)
+         |       |--- TTLLock per object (read/write)
+         |
+         |--- StoreController  -----> L2 Adapter(s) (async L1->L2 push)
+         |--- PrefetchController ---> L2 Adapter(s) (async L2->L1 load)
+         |--- EvictionController ----> L1Manager (watermark-triggered eviction)
+         |
+         v
+    EventBus + OTel providers (observability)
+
+Engine and Modules
+------------------
+
+All server entry points share the same ``MPCacheServer`` and
+``StorageManager`` core. ``MPCacheServer`` is now a thin compositor:
+it holds an ``MPCacheServerContext`` and a list of ``EngineModule``
+instances assembled by ``_build_modules()`` (in ``server.py``)
+based on ``--engine-type`` and ``--supported-transfer-mode``.
+
+**``server.py``** -- The default ZMQ-only server.  Creates an
+``MPCacheServer``, assembles the engine modules
+(``LookupModule`` + ``ManagementModule`` + ``LMCacheDrivenTransferModule``
+and/or ``EngineDrivenTransferModule`` depending on
+``--supported-transfer-mode`` — ``lmcache_driven`` or ``engine_driven`` loads
+just one,
+``auto`` (default) loads both — plus a CacheBlend module when
+``--engine-type`` is set: ``blend`` appends ``BlendV3Module`` (the
+current paged-aware implementation), and ``blend_legacy`` appends
+``BlendModule`` (the original)). Starts a ``MessageQueueServer``,
+registers handlers for every ``RequestType`` exposed by the loaded
+modules, and blocks in a keep-alive loop.
+
+**``modules/blend.py``** -- Defines ``BlendModule`` and ``BlendEngineV2``,
+which add the original CacheBlend operations (``CB_REGISTER_KV_CACHE``,
+``CB_LOOKUP_PRE_COMPUTED``, ``CB_STORE_PRE_COMPUTED``,
+``CB_RETRIEVE_PRE_COMPUTED``, ``CB_STORE_FINAL`` and their V2
+variants). Enables non-prefix KV cache reuse across document
+paragraphs. Selected by passing ``--engine-type blend_legacy`` to
+``lmcache server``.
+
+**``modules/blend_v3.py``** -- Defines ``BlendV3Module``, the
+paged-aware CacheBlend V3 pipeline that runs on the sparse-prefetch
+path. Adds the V3 RPCs (``CB_REGISTER_ROPE_V3``,
+``CB_UNREGISTER_ROPE_V3``, ``CB_RETRIEVE_PRE_COMPUTED_V3``,
+``CB_UNIFIED_LOOKUP``) and reuses the existing
+``LMCacheDrivenTransferModule`` and ``LookupModule``. Selected by
+passing ``--engine-type blend`` to
+``lmcache server``.
+
+Both blend variants require ``--supported-transfer-mode`` to be
+``lmcache_driven`` or ``auto`` and will refuse to load when it is
+``engine_driven``.
+
+**``http_server.py``** -- Wraps ``run_cache_server()`` (from ``server.py``)
+inside a FastAPI application.  Endpoints are contributed by modules under
+``http_apis/`` and auto-registered via ``HTTPAPIRegistry``: ``GET /`` (basic
+liveness), ``GET /healthcheck`` for Kubernetes probes, ``POST /cache/clear``
+for clearing all KV cache data in L1 (CPU) memory, and ``GET /status``
+for inspecting detailed internal state.  The ZMQ server runs as part of the
+same process, and any configured runtime plugins are spawned by
+``MPRuntimePluginLauncher`` during FastAPI startup.
+
+ZMQ Protocol
+------------
+
+Communication between vLLM and LMCache uses ZMQ (DEALER/ROUTER pattern).
+
+**RequestType enum** (defined in ``protocols/base.py``):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Request Type
+     - Handler Type
+     - Description
+   * - ``REGISTER_KV_CACHE``
+     - SYNC
+     - Register GPU KV cache tensors for a vLLM instance.
+   * - ``UNREGISTER_KV_CACHE``
+     - SYNC
+     - Unregister KV cache tensors.
+   * - ``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``
+     - SYNC
+     - Register an engine-driven KV cache context (CPU/accelerator
+       workers using the PREPARE/COMMIT transfer path). Loaded only when
+       ``--supported-transfer-mode`` is ``engine_driven`` or ``auto``.
+       Returns a ``RegisterEngineDrivenContextResponse`` carrying the
+       SHM segment name and pool size when the SHM path is in use
+       (empty for the pickle path).
+   * - ``UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``
+     - SYNC
+     - Unregister an engine-driven KV cache context.
+   * - ``STORE``
+     - BLOCKING
+     - Store KV cache chunks from GPU to L1 (CPU). LMCache-driven
+       transfer path (CUDA IPC); loaded only when
+       ``--supported-transfer-mode`` is ``lmcache_driven`` or ``auto``.
+   * - ``RETRIEVE``
+     - BLOCKING
+     - Copy KV cache chunks from L1 (CPU) back to GPU. LMCache-driven
+       transfer path (CUDA IPC); loaded only when
+       ``--supported-transfer-mode`` is ``lmcache_driven`` or ``auto``.
+   * - ``PREPARE_STORE``
+     - BLOCKING
+     - (Engine-driven path) Worker asks the server to prepare store-side
+       transfer state for a key. Loaded when ``--supported-transfer-mode``
+       is ``engine_driven`` or ``auto``.
+   * - ``COMMIT_STORE``
+     - BLOCKING
+     - (Engine-driven path) Worker commits the chunk's serialized bytes
+       (pickle path) or releases the prepared SHM slot (SHM path) so the
+       server can persist into L1 storage.
+   * - ``PREPARE_RETRIEVE``
+     - BLOCKING
+     - (Engine-driven path) Worker asks the server to prepare the
+       retrieval payload for a key. The pickle path returns the bytes
+       inline; the SHM path returns slot info so the worker can read
+       from shared memory.
+   * - ``COMMIT_RETRIEVE``
+     - BLOCKING
+     - (Engine-driven path) Worker acknowledges retrieval completion so
+       the server can release the underlying read locks and reclaim any
+       transport state.
+   * - ``LOOKUP``
+     - BLOCKING
+     - Submit a prefix lookup; the prefetch job is tracked server-side by
+       request_id.
+   * - ``QUERY_PREFETCH_STATUS``
+     - BLOCKING
+     - Poll a prefetch job by request_id. Returns the loaded chunk count
+       when done, or ``None`` while the prefetch is still in progress.
+   * - ``WAIT_PREFETCH_STATUS``
+     - BLOCKING
+     - (SGLang only) Block until a prefetch job completes, then return its
+       loaded chunk count, or ``None`` on timeout. The blocking alternative
+       to polling ``QUERY_PREFETCH_STATUS``.
+   * - ``QUERY_PREFETCH_LOOKUP_HITS``
+     - BLOCKING
+     - Query the lookup-phase hit chunk count by request_id, before the
+       prefetch finishes. Returns ``None`` while the lookup is still
+       running.
+   * - ``FREE_LOOKUP_LOCKS``
+     - BLOCKING
+     - Release read locks from a cancelled lookup without doing a full
+       RETRIEVE.
+   * - ``END_SESSION``
+     - BLOCKING
+     - Remove session state for a finished request.
+   * - ``CLEAR``
+     - BLOCKING
+     - Clear all cached data.
+   * - ``GET_CHUNK_SIZE``
+     - SYNC
+     - Return the server's chunk size.
+   * - ``PING``
+     - BLOCKING
+     - Liveness ping; the handler always returns ``True``.
+   * - ``REPORT_BLOCK_ALLOCATION``
+     - BLOCKING
+     - Fire-and-forget channel for the vLLM scheduler to report GPU block
+       allocation events to the observability subsystem.
+   * - ``NOOP``
+     - SYNC
+     - Debug heartbeat -- returns a confirmation string.
+   * - ``CB_REGISTER_KV_CACHE``
+     - SYNC
+     - (Blend) Register CacheBlend KV buffer.
+   * - ``CB_UNREGISTER_KV_CACHE``
+     - SYNC
+     - (Blend) Unregister CacheBlend KV buffer.
+   * - ``CB_STORE_PRE_COMPUTED``
+     - BLOCKING
+     - (Blend) Store pre-computed paragraph chunks.
+   * - ``CB_LOOKUP_PRE_COMPUTED``
+     - BLOCKING
+     - (Blend) Lookup pre-computed paragraph chunks.
+   * - ``CB_RETRIEVE_PRE_COMPUTED``
+     - BLOCKING
+     - (Blend) Retrieve pre-computed paragraph chunks to GPU.
+   * - ``CB_STORE_FINAL``
+     - BLOCKING
+     - (Blend) Store final blended chunks.
+   * - ``CB_LOOKUP_PRE_COMPUTED_V2``
+     - BLOCKING
+     - (Blend V2) Lookup pre-computed chunks; returns
+       ``CBMatchResult`` entries (with old/cur ranges and per-chunk hashes)
+       so the retrieve step can skip re-hashing.
+   * - ``CB_RETRIEVE_PRE_COMPUTED_V2``
+     - BLOCKING
+     - (Blend V2) Retrieve pre-computed chunks using the
+       ``CBMatchResult`` list returned by ``CB_LOOKUP_PRE_COMPUTED_V2``.
+   * - ``CB_REGISTER_ROPE_V3``
+     - SYNC
+     - (Blend V3) Share the RoPE cos/sin cache onto a context already
+       registered via ``REGISTER_KV_CACHE``.
+   * - ``CB_UNREGISTER_ROPE_V3``
+     - SYNC
+     - (Blend V3) Drop the RoPE state (paged KV cache lives on; use
+       ``UNREGISTER_KV_CACHE`` to release that).
+   * - ``CB_RETRIEVE_PRE_COMPUTED_V3``
+     - BLOCKING
+     - (Blend V3) Scatter all matched chunks (prefix- and non-prefix-hit)
+       into paged KV by per-token block ID; re-RoPE only the shifted subset.
+   * - ``CB_UNIFIED_LOOKUP``
+     - BLOCKING
+     - (Blend V3) Sole live lookup path: one RPC runs prefix + non-prefix
+       match, reconciles, issues one sparse-coalesced prefetch, and
+       classifies per-TP-rank. Returns ``CBUnifiedLookupResult`` (or
+       ``None`` while the prefetch is still in flight).
+   * - ``P2P_LOOKUP_AND_LOCK``
+     - BLOCKING
+     - (P2P) Look up the given keys and read-lock the locally cached
+       prefix. Returns a task id which the caller passes to
+       ``P2P_QUERY_LOOKUP_RESULTS`` to poll for the transfer addresses.
+       Served by ``P2PController`` (loaded unconditionally by
+       ``_build_modules()``); whether this server also acts as a P2P
+       client is controlled by ``--p2p-advertise-url`` -- see
+       :doc:`p2p`.
+   * - ``P2P_QUERY_LOOKUP_RESULTS``
+     - BLOCKING
+     - (P2P) Poll the transfer addresses for a lookup task. Returns a
+       list of ``TransferChannelAddress`` once the lookup is complete,
+       or ``None`` while the lookup is still in progress or its
+       results have already been consumed.
+   * - ``P2P_UNLOCK_OBJECTS``
+     - BLOCKING
+     - (P2P) Release the read locks previously taken by
+       ``P2P_LOOKUP_AND_LOCK`` on the given keys.
+
+**Handler types:**
+
+- **SYNC** -- Runs directly in the ZMQ main loop (fast, non-blocking).
+- **BLOCKING** -- Dispatched to a thread pool (may involve GPU copies or I/O).
+
+Config System
+-------------
+
+Each config module exposes a composable triple:
+
+.. code-block:: text
+
+    (DataclassConfig, add_*_args(parser), parse_args_to_*_config(args))
+
+``server.py:parse_args()`` composes them:
+
+.. code-block:: python
+
+    parser = argparse.ArgumentParser(...)
+    add_mp_server_args(parser)        # from multiprocess/config.py
+                                      # includes runtime-plugin args
+                                      # (--runtime-plugin-locations,
+                                      #  --runtime-plugin-config)
+    add_storage_manager_args(parser)  # from distributed/config.py
+      # which internally calls add_l2_adapters_args(parser)
+    add_observability_args(parser)    # from mp_observability/config.py
+
+``http_server.py`` reuses this pattern, adding
+``add_http_frontend_args()`` and ``add_coordinator_args()`` for the
+``lmcache server`` CLI. CacheBlend is no longer a separate entry point —
+it is opted into at runtime by passing ``--engine-type`` to
+``server.py`` (or ``lmcache server``). ``--engine-type blend`` appends
+``BlendV3Module`` (the current paged-aware implementation), while
+``--engine-type blend_legacy`` appends ``BlendModule`` (the original).
+
+Distributed Storage
+-------------------
+
+StorageManager
+~~~~~~~~~~~~~~
+
+``lmcache/v1/distributed/storage_manager.py``
+
+The top-level manager that wires together L1, L2, and all controllers.  Key
+methods:
+
+- ``reserve_write()`` / ``finish_write()`` -- Two-phase write into L1.
+- ``submit_prefetch_task()`` / ``query_prefetch_status()`` -- Async lookup +
+  L2 prefetch. ``query_prefetch_status()`` is non-blocking and returns
+  ``None`` while the L2 prefetch is still in flight.
+- ``wait_prefetch_status()`` -- Blocking alternative to polling
+  ``query_prefetch_status()``: waits on a controller condition variable
+  until the prefetch result is published (or a timeout expires).
+  L1-only prefetches return immediately. Used by the
+  ``WAIT_PREFETCH_STATUS`` RPC to avoid busy-polling on the load path.
+- ``read_prefetched_results()`` / ``finish_read_prefetched()`` -- Read
+  prefetched data from L1 with automatic lock management.
+
+L1Manager
+~~~~~~~~~
+
+``lmcache/v1/distributed/l1_manager.py``
+
+Manages objects in CPU memory with a state machine:
+
+.. code-block:: text
+
+    None --> write_locked --> ready --> read_locked
+              (reserve_write)  (finish_write)  (reserve_read)
+                                  |                |
+                                  v                v
+                               evictable      finish_read -> ready
+
+Each object has two ``TTLLock`` instances (read and write) with configurable
+timeouts to prevent deadlocks from crashed clients.
+
+The underlying memory allocation is handled by one of two interchangeable
+tiers selected at startup (both satisfy ``L1ManagerProtocol``):
+
+- ``L1MemoryManager`` (default) -- pinned CPU DRAM, with lazy growth up to
+  ``--l1-size-gb``.
+- ``GDSL1MemoryManager`` -- an NVMe slab file when ``--gds-l1-path`` is set.
+  The bytes live on disk; reads/writes DMA directly between the GPU staging
+  buffer and the slab, driven by the process-global ``GDSContext``
+  (``gpu_connector/gds_context.py``) and dispatched from ``gpu_ops``. The DMA
+  backend is selected by platform via ``gpu_connector/_gds_async.py`` --
+  cuFile (``libcufile.so``) on NVIDIA and hipFile (``libhipfile.so``) on AMD
+  ROCm; see the *GDS L1 Tier* section of :doc:`configuration` for the
+  vendor-specific requirements. The CPU tier is disabled in this mode.
+
+L2 Adapters
+~~~~~~~~~~~
+
+``lmcache/v1/distributed/l2_adapters/``
+
+The ``L2AdapterInterface`` (in ``base.py``) defines three async task methods:
+
+- ``submit_store_task(key, data)`` -- Push data to L2.
+- ``submit_lookup_and_lock_task(keys)`` -- Check if keys exist in L2.
+- ``submit_load_task(keys, layout_desc)`` -- Load data from L2 into L1.
+
+The factory function ``create_l2_adapter()`` (in ``__init__.py``) uses
+``isinstance()`` on the config type to instantiate the correct adapter.
+
+New adapter types are registered via ``register_l2_adapter_type()`` in
+``config.py``.
+
+Controllers
+~~~~~~~~~~~
+
+**StoreController** (``storage_controllers/store_controller.py``):
+Event-driven background thread that uses ``select.poll()`` on listener eventfd
+and adapter store eventfds.  When new objects appear in L1 (signaled via
+``StoreListener``), it submits async store tasks to each L2 adapter based on
+the ``StorePolicy``.
+
+**EvictionController** (``storage_controllers/eviction_controller.py``):
+Periodically checks L1 memory usage against the watermark threshold.  When
+triggered, evicts objects using the configured policy (``LRU``,
+``IsolatedLRU``, or ``noop``) until usage drops below the target.
+``IsolatedLRU`` evicts per ``cache_salt`` against limits registered through
+the ``/quota`` HTTP endpoints; see :ref:`mp-http-quota-api`.
+
+**PrefetchController** (``storage_controllers/prefetch_controller.py``):
+Handles L2 lookup and load requests submitted by ``StorageManager`` during
+``LOOKUP`` RPCs.  When keys are not in L1, it queries L2 adapters and loads
+found data back into L1.
+
+Request Flows
+-------------
+
+LOOKUP Flow
+~~~~~~~~~~~
+
+.. code-block:: text
+
+    vLLM                MPCacheServer          StorageManager         L1Manager       L2 (PrefetchController)
+     |                       |                       |                    |                    |
+     |---LOOKUP(key)-------->|                       |                    |                    |
+     |                       |--submit_prefetch------>|                    |                    |
+     |                       |                       |--reserve_read----->|                    |
+     |                       |                       |<--hit_count--------|                    |
+     |                       |                       |--submit_prefetch_request--------------->|
+     |                       |                       |    (remaining keys)                     |
+     |                       |--query_prefetch------->|                    |                    |
+     |                       |                       |--query_prefetch_result----------------->|
+     |                       |<--found_count----------|                    |                    |
+     |<--found_count---------|                       |                    |                    |
+
+STORE Flow
+~~~~~~~~~~
+
+.. code-block:: text
+
+    vLLM                MPCacheServer          StorageManager         L1Manager
+     |                       |                       |                    |
+     |---STORE(key,blocks)-->|                       |                    |
+     |                       |--reserve_write-------->|                    |
+     |                       |                       |--reserve_write---->|
+     |                       |                       |<--memory_objs------|
+     |                       |  (GPU->CPU copy)      |                    |
+     |                       |--finish_write--------->|                    |
+     |                       |                       |--finish_write----->|
+     |                       |                       |                    |
+     |                       |                       |  [StoreController detects new objects]
+     |                       |                       |  [async L1->L2 push via adapters]
+     |<--event_handle--------|                       |                    |
+
+RETRIEVE Flow
+~~~~~~~~~~~~~
+
+.. code-block:: text
+
+    vLLM                MPCacheServer          StorageManager         L1Manager
+     |                       |                       |                    |
+     |---RETRIEVE(key)------>|                       |                    |
+     |                       |--read_prefetched------>|                    |
+     |                       |                       |--unsafe_read------>|
+     |                       |                       |<--memory_objs------|
+     |                       |  (CPU->GPU copy)      |                    |
+     |                       |--finish_read_prefetch->|                    |
+     |                       |                       |--finish_read------>|
+     |<--event_handle--------|                       |                    |
+
+Observability Internals
+-----------------------
+
+**EventBus** (``lmcache/v1/mp_observability/event_bus.py``) is a global
+singleton initialized at server startup by ``init_observability()``.
+Producers (L1Manager, StorageManager, MPCacheServer) publish ``Event``
+objects to a bounded queue (``--event-bus-queue-size``, default 10000,
+tail-drop on overflow).  A background drain thread dispatches each
+event to all registered subscribers.
+
+**Subscribers** live under ``lmcache/v1/mp_observability/subscribers/``
+and are grouped by concern: ``metrics/`` (OTel counters and lifecycle
+histograms), ``logging/`` (Python logging handlers, lookup-hash JSONL),
+and ``tracing/`` (OTel spans built from START/END event pairs).
+``init_observability()`` registers the set selected by CLI flags
+(``--disable-metrics``, ``--disable-logging``, ``--enable-tracing``).
+
+**OTel providers** are set up via ``otel_init.py`` before subscribers
+are constructed, so module-level ``get_meter()`` / ``get_tracer()``
+calls bind to the real provider. Metrics are exported both to an
+in-process Prometheus ``/metrics`` endpoint (``--prometheus-port``,
+default 9090) and, when ``--otlp-endpoint`` is set, pushed to an OTel
+collector.
+
+How to Extend
+-------------
+
+Adding a new L2 adapter
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a new ``*_l2_adapter.py`` module under
+``lmcache/v1/distributed/l2_adapters/`` — ``__init__.py`` auto-discovers
+modules matching that suffix via ``pkgutil`` and imports them lazily on
+first use, so no other files need to be modified.
+
+1. Create a config class subclassing ``L2AdapterConfigBase`` with
+   ``from_dict()`` and ``help()`` methods.
+2. Create an adapter class implementing ``L2AdapterInterface``, and
+   a small factory function
+   ``(config, l1_memory_desc) -> L2AdapterInterface``.
+3. At module level, self-register both the config and the factory:
+
+   .. code-block:: python
+
+       register_l2_adapter_type("my_adapter", MyAdapterConfig)
+       register_l2_adapter_factory("my_adapter", _create_my_adapter)
+
+See ``mock_l2_adapter.py`` or ``s3_l2_adapter.py`` for reference
+implementations.
+
+Adding an observability subscriber
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Create a subscriber class subclassing ``EventSubscriber`` (defined
+   in ``lmcache/v1/mp_observability/event_bus.py``): implement
+   ``get_subscriptions()`` to return an ``{EventType: callback}``
+   mapping; optionally override ``shutdown()`` for cleanup.
+2. Place the class under the appropriate concern group
+   (``subscribers/metrics/``, ``subscribers/logging/``, or
+   ``subscribers/tracing/``) and export it from that package's
+   ``__init__.py``.
+3. Register the subscriber in ``init_observability()``
+   (``lmcache/v1/mp_observability/config.py``) via
+   ``bus.register_subscriber(...)`` inside the branch matching its
+   concern (metrics / logging / tracing), gated on the corresponding
+   CLI flag if needed.
+
+Adding a new request type
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Add a new member to ``RequestType`` in ``protocols/base.py``.
+2. Create a ``ProtocolDefinition`` in the appropriate ``protocols/*.py`` file
+   (``engine``, ``controller``, ``observability``, ``debug``, ``blend``,
+   ``blend_v2``, ``blend_v3``, or ``p2p``) and add the request name to that
+   module's ``REQUEST_NAMES``.
+3. Implement the handler method on the appropriate ``EngineModule``
+   (e.g. ``LookupModule``, ``LMCacheDrivenTransferModule``, ``BlendV3Module``) and
+   expose it as a ``HandlerSpec`` from that module's ``get_handlers()``.
+4. ``run_cache_server()`` registers every ``HandlerSpec`` returned by the
+   loaded modules via ``add_handler_helper()`` — no manual registration
+   step is needed.
+
+Key Source Files
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - File
+     - Purpose
+   * - ``lmcache/v1/multiprocess/server.py``
+     - MPCacheServer + ZMQ server entry point
+   * - ``lmcache/v1/multiprocess/config.py``
+     - MPServerConfig, HTTPFrontendConfig
+   * - ``lmcache/v1/multiprocess/engine_context.py``
+     - MPCacheServerContext (shared state passed to every EngineModule)
+   * - ``lmcache/v1/multiprocess/engine_module.py``
+     - ``EngineModule`` protocol, ``HandlerSpec``, ``ThreadPoolType``
+       (per-module handler registration)
+   * - ``lmcache/v1/multiprocess/modules/``
+     - Engine module implementations: ``lookup.py`` (``LookupModule``),
+       ``management.py`` (``ManagementModule``), ``lmcache_driven_transfer.py``
+       (``LMCacheDrivenTransferModule``), ``engine_driven_transfer.py``
+       (``EngineDrivenTransferModule``), ``blend.py``
+       (``BlendModule`` / ``BlendEngineV2``, selected by
+       ``--engine-type blend_legacy``), and ``blend_v3.py``
+       (``BlendV3Module``, the paged-aware CacheBlend V3 pipeline
+       selected by ``--engine-type blend``).
+   * - ``lmcache/v1/multiprocess/http_server.py``
+     - FastAPI wrapper with health check and many other useful APIs
+   * - ``lmcache/v1/multiprocess/http_api_registry.py``
+     - ``HTTPAPIRegistry`` that auto-discovers routers in ``http_apis/``
+   * - ``lmcache/v1/multiprocess/http_apis/``
+     - Extensible HTTP endpoints (``/``, ``/healthcheck``,
+       ``/cache/clear``, ``/status``)
+   * - ``lmcache/v1/multiprocess/mp_runtime_plugin_launcher.py``
+     - ``MPRuntimePluginLauncher`` that spawns runtime plugins with the
+       full server config serialized into environment variables
+   * - ``lmcache/v1/multiprocess/protocols/base.py``
+     - RequestType, HandlerType, ProtocolDefinition
+   * - ``lmcache/v1/distributed/storage_manager.py``
+     - StorageManager (top-level manager)
+   * - ``lmcache/v1/distributed/config.py``
+     - StorageManagerConfig hierarchy
+   * - ``lmcache/v1/distributed/l1_manager.py``
+     - L1Manager (object state machine)
+   * - ``lmcache/v1/distributed/l2_adapters/config.py``
+     - L2 adapter config registry
+   * - ``lmcache/v1/distributed/l2_adapters/base.py``
+     - L2AdapterInterface
+   * - ``lmcache/v1/distributed/storage_controllers/store_controller.py``
+     - StoreController (event-driven L1->L2)
+   * - ``lmcache/v1/distributed/storage_controllers/eviction_controller.py``
+     - EvictionController (watermark-triggered)
+   * - ``lmcache/v1/distributed/storage_controllers/prefetch_controller.py``
+     - PrefetchController (L2->L1 on miss)
+   * - ``lmcache/v1/mp_observability/config.py``
+     - ObservabilityConfig + ``init_observability()`` entry point
+   * - ``lmcache/v1/mp_observability/event_bus.py``
+     - EventBus singleton and ``EventSubscriber`` base class
+   * - ``lmcache/v1/mp_observability/event.py``
+     - ``Event`` / ``EventType`` definitions
+   * - ``lmcache/v1/mp_observability/otel_init.py``
+     - OTel metrics / tracing provider setup
+   * - ``lmcache/v1/mp_observability/subscribers/``
+     - Metrics, logging, and tracing subscribers
+   * - ``lmcache/v1/mp_observability/trace/``
+     - Trace recording (``--trace-level storage``) capture stack
diff --git a/docs/source/mp/kv_cache_management.rst b/docs/source/mp/kv_cache_management.rst
new file mode 100644
index 0000000..578c280
--- /dev/null
+++ b/docs/source/mp/kv_cache_management.rst
@@ -0,0 +1,13 @@
+.. _mp_kv_cache_management:
+
+KV Cache Management
+===================
+
+.. note::
+
+   The multiprocess (MP) cache-management surface (operations such as
+   ``move``, ``pin``, and ``compress``) is **coming soon**.
+
+   Until it lands, the in-process management commands are documented in the
+   :doc:`Legacy section <../legacy/index>`:
+   :doc:`../kv_cache_management/index`.
diff --git a/docs/source/mp/l2_storage/aerospike.rst b/docs/source/mp/l2_storage/aerospike.rst
new file mode 100644
index 0000000..9cd6329
--- /dev/null
+++ b/docs/source/mp/l2_storage/aerospike.rst
@@ -0,0 +1,63 @@
+Aerospike
+=========
+
+An L2 adapter backed by the native C++ Aerospike connector (the same
+``ConnectorBase`` worker-pool harness used by ``fs_native``), wrapped with
+``NativeConnectorL2Adapter``.  KV objects are stored under a meta record plus
+optional payload segments so values larger than the server record cap are
+transparently sharded.
+
+**Prerequisites -- Building with Aerospike support:**
+
+The Aerospike extension is **not** built by default.  Install the Aerospike C
+client, then build with ``BUILD_AEROSPIKE=1`` (or set ``AEROSPIKE_INCLUDE_DIR``):
+
+.. code-block:: bash
+
+    BUILD_AEROSPIKE=1 pip install -e .
+
+See :doc:`/developer_guide/extending_lmcache/native_connectors` (section
+"Built-in Aerospike backend") for installing the C client into ``.deps/`` and
+the ``aerospike-client-c.env`` example.
+
+**Required fields:**
+
+- ``hosts``: Seed hosts as ``host:port[,host:port...]``.
+
+**Optional fields:**
+
+- ``namespace`` (str, default ``"lmcache"``): Aerospike namespace.  Must exist
+  on the server and have ``nsup-period > 0`` if you rely on TTL expiry.
+- ``set_name`` / ``set`` (str, default ``"kv_chunks"``): Aerospike set name.
+- ``num_workers`` (int, default ``8``, > 0): C++ worker threads for I/O.  This
+  is the real I/O queue depth -- raise it to push throughput.
+- ``read_timeout_ms`` (int, default ``1000``): Client read timeout.
+- ``write_timeout_ms`` (int, default ``2000``): Client write timeout.
+- ``default_ttl_seconds`` (int, default ``86400``): Record TTL.  ``0`` uses the
+  namespace default TTL.
+- ``target_segment_bytes`` (int, default ``0``): Target shard size.  ``0`` uses
+  the discovered server record cap.
+- ``max_record_bytes`` (int, default ``0``): Override the server record cap.
+  ``0`` discovers it at construction time.
+- ``username`` / ``password`` (str, default ``""``): Optional Enterprise
+  Edition authentication.
+- ``max_capacity_gb`` (float, default ``0``): Maximum L2 capacity in GB for
+  client-side usage tracking / eviction.  ``0`` disables tracking.
+
+**Environment variable fallbacks.**  When the corresponding config value is
+empty, these environment variables are used: ``LMCACHE_AEROSPIKE_HOSTS``,
+``LMCACHE_AEROSPIKE_NAMESPACE``, ``LMCACHE_AEROSPIKE_SET``,
+``LMCACHE_AEROSPIKE_USERNAME``, ``LMCACHE_AEROSPIKE_PASSWORD``.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Basic single-node Community Edition
+    --l2-adapter '{"type": "aerospike", "hosts": "127.0.0.1:3000", "namespace": "lmcache", "set_name": "kv_chunks", "num_workers": 8}'
+
+    # Multi-node seed list with capacity tracking for eviction
+    --l2-adapter '{"type": "aerospike", "hosts": "10.0.0.1:3000,10.0.0.2:3000", "namespace": "lmcache", "num_workers": 16, "max_capacity_gb": 512}'
+
+    # Enterprise Edition with authentication
+    --l2-adapter '{"type": "aerospike", "hosts": "as.internal:3000", "namespace": "lmcache", "username": "lmcache", "password": "secret"}'
diff --git a/docs/source/mp/l2_storage/dax.rst b/docs/source/mp/l2_storage/dax.rst
new file mode 100644
index 0000000..efcdced
--- /dev/null
+++ b/docs/source/mp/l2_storage/dax.rst
@@ -0,0 +1,101 @@
+DAX
+===
+
+An L2 adapter that maps Device-DAX paths, such as ``/dev/daxX.X`` and
+``/dev/daxY.Y``, and stores KV cache objects in fixed-size slots. This adapter
+is intended for byte-addressable memory devices such as persistent memory or
+CXL memory.
+
+The MP ``dax`` adapter is volatile in this release.  It keeps the key index in
+server memory and rebuilds an empty index on restart.  Old bytes may remain on
+the DAX device, but they are unreachable after the LMCache server restarts.
+
+**Required fields for the legacy single-device form:**
+
+- ``device_path``: Path to the mmap-able DAX device or test file.
+- ``max_dax_size_gb``: Number of GiB to map from ``device_path``.
+- ``slot_bytes``: Fixed slot size in bytes. This must be large enough for one
+  full LMCache chunk because MP memory descriptors do not expose the
+  non-MP full-chunk size.
+
+**Required fields for the multi-device form:**
+
+- ``devices``: List of objects with ``device_path`` and ``max_dax_size_gb``.
+  The list may be empty only when ``hotplug_enabled`` is ``true``.
+- ``slot_bytes``: Fixed slot size in bytes shared by every DAX device in the
+  adapter facade.
+
+**Optional fields:**
+
+- ``hotplug_enabled`` (bool, default ``false``): Enables runtime
+  ``/reconfigure/dax/status``, ``/reconfigure/dax/add``,
+  ``/reconfigure/dax/remove``, and ``/reconfigure/dax/resize``.
+- ``num_store_workers`` (int, default ``1``): Store worker threads.
+- ``num_lookup_workers`` (int, default ``1``): Lookup worker threads.
+- ``num_load_workers`` (int, default ``min(4, os.cpu_count())``): Load worker
+  threads.
+- ``persist_enabled`` (bool): Accepted by common L2 config parsing but has no
+  effect for ``dax`` because restart recovery is not implemented.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Backward-compatible single-device form.
+    --l2-adapter '{
+      "type": "dax",
+      "device_path": "/dev/dax1.0",
+      "max_dax_size_gb": 100,
+      "slot_bytes": 268435456,
+      "num_store_workers": 1,
+      "num_lookup_workers": 1,
+      "num_load_workers": 4,
+      "eviction": {
+        "eviction_policy": "LRU",
+        "trigger_watermark": 0.9,
+        "eviction_ratio": 0.1
+      }
+    }'
+
+.. code-block:: bash
+
+    # Multi-device hotplug-ready form.
+    --l2-adapter '{
+      "type": "dax",
+      "devices": [
+        {"device_path": "/dev/daxX.X", "max_dax_size_gb": 100},
+        {"device_path": "/dev/daxY.Y", "max_dax_size_gb": 100}
+      ],
+      "slot_bytes": 268435456,
+      "hotplug_enabled": true,
+      "num_store_workers": 1,
+      "num_lookup_workers": 1,
+      "num_load_workers": 4
+    }'
+
+Runtime management uses JSON bodies because DAX paths contain slashes. See the
+:doc:`Device-DAX backend guide </kv_cache/storage_backends/dax>` for complete
+examples. These routes use StorageManager's generic L2 adapter reconfiguration
+API; the HTTP path selects the backend and operation, the DAX adapter
+interprets the operation payload, and the same interface can be reused by
+future adapters such as P2P.
+
+.. code-block:: bash
+
+    curl http://127.0.0.1:9000/reconfigure/dax/status
+    curl -X POST http://127.0.0.1:9000/reconfigure/dax/add \
+      -H 'Content-Type: application/json' \
+      -d '{"device_path": "/dev/daxX.X", "size": "100GiB"}'
+
+**Current limits:**
+
+- Runtime hotplug changes only LMCache mappings and metadata. It does not
+  create, destroy, or reconfigure kernel CXL or DAX devices.
+- Per-TP partitions and on-device restart metadata are not implemented.
+- Only single-buffer objects are supported. Multi-tensor objects are rejected.
+- Capacity is slot-based, not payload-byte-based. L2 eviction and usage
+  metrics count occupied slots.
+- Lookups acquire DAX-side external locks. ``submit_unlock`` releases those
+  locks after load/retrieve completes, making entries evictable again.
+- Remove ``mode="evict"`` is destructive for the DAX tier. Remove
+  ``mode="migrate"`` requires enough capacity on another active DAX device.
diff --git a/docs/source/mp/l2_storage/fault_inject.rst b/docs/source/mp/l2_storage/fault_inject.rst
new file mode 100644
index 0000000..e1a1879
--- /dev/null
+++ b/docs/source/mp/l2_storage/fault_inject.rst
@@ -0,0 +1,76 @@
+Fault Inject
+============
+
+A **test/diagnostic-only** adapter that wraps a real inner adapter and
+deterministically drops keys on the load read, simulating partial L2 retrieve
+failures.  It exercises CacheBlend's **segmented-prefix** recovery path — a
+gapped found-set (hit … miss … hit) that a healthy cache never produces —
+without needing an actual faulty backend.
+
+.. warning::
+
+   Never enable in production.  It silently makes reads fail, so any KV it
+   serves is intentionally incomplete.
+
+The wrapped backend is given as a full adapter spec under ``inner`` (any
+registered ``type``), so it keeps its own configuration, eviction, persist, and
+serde settings.  Faulting applies to the load read only: a dropped key is
+reported *present at lookup* but its *load fails* (the faithful "L2 retrieve
+error"); the prefetch controller releases the load-failed locks via the trim
+mask.  Everything else (store, lookup, unlock, delete, usage) passes straight
+through to the inner adapter.
+
+**Fields:**
+
+- ``inner`` (required): full adapter spec for the wrapped backend, e.g.
+  ``{"type": "fs_native", "base_path": "/dev/shm/l2"}``.
+- ``gap_tail_ratios``: positions to always drop, given as distance-from-tail
+  fractions of the load length in ``[0, 1]`` (``0.0`` = last chunk, ``0.5`` =
+  middle, ``1.0`` = first).  Workload-agnostic and self-scaling across context
+  lengths.  Default ``[]``.
+- ``gap_indices``: exact head-relative task-positions to always drop.
+  Default ``[]``.
+- ``rate``: per-key drop probability in ``[0, 1]`` via a stable seeded hash of
+  the key.  Default ``0.0`` (pass-through).
+- ``seed``: seed for the ``rate`` hash (deterministic given the seed).
+  Default ``0``.
+
+Defaults are pass-through; set at least one of ``gap_tail_ratios``,
+``gap_indices``, or ``rate`` to drop anything.
+
+Drop a stable mid-prefix gap (the CacheBlend segmented-prefix repro), wrapping
+an ``fs_native`` backend:
+
+.. code-block:: bash
+
+    --l2-adapter '{"type": "fault_inject", "inner": {"type": "fs_native", "base_path": "/dev/shm/cb_l2"}, "gap_tail_ratios": [0.5]}'
+
+To actually exercise CacheBlend's **segmented-prefix recovery**, pair the gap
+with the server flag ``--enable-segmented-prefix`` (CacheBlend only —
+``--engine-type blend``). The dropped mid chunk produces a gapped found-set;
+with segmented-prefix enabled the prefix leg **retains the post-gap chunks**
+(loads prefix + tail) and recomputes **only the dropped gap**, instead of
+truncating the prefix at the gap:
+
+.. code-block:: bash
+
+    lmcache server … \
+        --l2-adapter '{"type": "fault_inject", "inner": {"type": "fs_native", "base_path": "/dev/shm/cb_l2"}, "gap_tail_ratios": [0.5]}' \
+        --enable-segmented-prefix
+
+Randomly drop ~10% of loads (deterministic given the seed):
+
+.. code-block:: bash
+
+    --l2-adapter '{"type": "fault_inject", "inner": {"type": "fs", "base_path": "/data/l2"}, "rate": 0.1, "seed": 7}'
+
+Drop an exact load position (precise single-gap repro):
+
+.. code-block:: bash
+
+    --l2-adapter '{"type": "fault_inject", "inner": {"type": "fs_native", "base_path": "/dev/shm/cb_l2"}, "gap_indices": [12]}'
+
+At startup the adapter logs ``FaultInjectL2Adapter ACTIVE (rate=… seed=…
+gap_indices=… gap_tail_ratios=[…]) wrapping <inner> -- test/diagnostic use
+only.``, and ``report_status()`` reports the active fault config under a
+``fault_inject`` sub-dict.
diff --git a/docs/source/mp/l2_storage/file_and_block.rst b/docs/source/mp/l2_storage/file_and_block.rst
new file mode 100644
index 0000000..77800df
--- /dev/null
+++ b/docs/source/mp/l2_storage/file_and_block.rst
@@ -0,0 +1,13 @@
+File & Block
+============
+
+File-system and block-device backends that persist KV cache to local or
+networked storage. These are conceptually similar -- they write KV objects to
+files or fixed-size slots on a disk or block device.
+
+.. toctree::
+   :maxdepth: 1
+
+   fs
+   fs_native
+   raw_block
diff --git a/docs/source/mp/l2_storage/fs.rst b/docs/source/mp/l2_storage/fs.rst
new file mode 100644
index 0000000..047265c
--- /dev/null
+++ b/docs/source/mp/l2_storage/fs.rst
@@ -0,0 +1,32 @@
+FileSystem
+==========
+
+A pure file-system L2 adapter using async I/O (``aiofiles``).  Each KV cache
+object is stored as a raw ``.data`` file whose name encodes the full
+``ObjectKey``.  Does **not** require NIXL -- works on any POSIX file system.
+
+**Required fields:**
+
+- ``base_path``: Directory for storing KV cache files.
+
+**Optional fields:**
+
+- ``relative_tmp_dir``: Relative sub-directory for temporary files during
+  writes (atomic rename on completion).
+- ``read_ahead_size``: Trigger file-system read-ahead by reading this many
+  bytes first (positive integer, optional).
+- ``use_odirect``: ``true`` or ``false`` (default ``false``) -- bypass the
+  page cache via ``O_DIRECT``.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Basic FS adapter
+    --l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2"}'
+
+    # With temp directory
+    --l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2", "relative_tmp_dir": ".tmp"}'
+
+    # With O_DIRECT for bypassing page cache
+    --l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2", "use_odirect": true}'
diff --git a/docs/source/mp/l2_storage/fs_native.rst b/docs/source/mp/l2_storage/fs_native.rst
new file mode 100644
index 0000000..9db698a
--- /dev/null
+++ b/docs/source/mp/l2_storage/fs_native.rst
@@ -0,0 +1,82 @@
+FS (native)
+===========
+
+A file-system L2 adapter backed by the native C++ ``LMCacheFSClient``
+wrapped with ``NativeConnectorL2Adapter``.  I/O is dispatched through a
+C++ worker-thread pool with eventfd-driven completions, giving a true
+I/O queue depth on a single Python thread.
+
+**Required fields:**
+
+- ``base_path``: Directory for storing KV cache files.
+
+**Optional fields:**
+
+- ``num_workers`` (int, default ``4``, > 0): Number of C++ worker threads
+  inside the connector.  This is the real I/O queue depth -- raise to
+  push throughput on filesystems whose aggregate BW exceeds per-stream
+  BW.
+- ``relative_tmp_dir`` (str, default ``""``): Relative sub-directory for
+  temporary files during writes (atomic rename on completion).
+- ``use_odirect`` (bool, default ``false``): Bypass the page cache via
+  ``O_DIRECT``.  Required to measure real disk bandwidth.  See alignment
+  caveat below.
+- ``read_ahead_size`` (int, optional): Trigger filesystem readahead by
+  issuing a warm-up read of this many bytes at open time.
+- ``max_capacity_gb`` (float, default ``0``): Maximum L2 capacity in GB
+  for client-side usage tracking.  Default ``0`` disables tracking.
+
+.. important::
+
+   ``O_DIRECT`` has two independent alignment requirements:
+
+   1. **Length alignment.**  The transfer length must be a multiple of
+      the filesystem's block size.  The connector queries the disk block
+      size at construction time and, on each operation, checks
+      ``len % disk_block_size``.  If the length is **not** a multiple,
+      the connector silently falls back to a buffered open (no
+      ``O_DIRECT``) for that operation -- correctness is preserved but
+      you do not get true direct I/O.  To ensure ``O_DIRECT`` is
+      actually used, choose ``--chunk-size`` so that the resulting
+      per-chunk byte size is a multiple of the FS block size.  GPFS and
+      similar parallel filesystems often use large blocks (e.g. several
+      MiB).
+
+   2. **Memory-buffer alignment.**  The I/O buffer pointer itself must
+      also be aligned (typically to 4096 bytes on local disks, or to the
+      FS block size on parallel filesystems).  This is controlled by
+      ``--l1-align-bytes`` (default ``4096``) -- raise it to match the
+      FS block size when running on a filesystem with larger blocks.  If
+      the buffer is misaligned, the underlying ``read``/``write`` syscall
+      returns ``EINVAL`` (this is **not** caught by the length-fallback
+      path above and will surface as a runtime error).
+
+   If unsure, start with ``use_odirect: false`` and confirm correctness
+   before enabling ``O_DIRECT``.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Basic native FS adapter
+    --l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2"}'
+
+    # Many worker threads for a parallel filesystem (e.g. GPFS, Lustre)
+    --l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2", "num_workers": 32}'
+
+    # O_DIRECT for real-disk benchmarking
+    --l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2", "num_workers": 32, "use_odirect": true}'
+
+**Buffer-only mode example.**  L1 acts as a pure write buffer that
+absorbs the peak burst of in-flight chunks while the C++ worker pool
+drains them to disk; nothing is retained in L1 once a store completes:
+
+.. code-block:: bash
+
+    lmcache server \
+        --host 0.0.0.0 --port 5555 \
+        --max-workers 32 \
+        --l1-size-gb 32 --l1-use-lazy \
+        --eviction-policy noop \
+        --l2-store-policy skip_l1 \
+        --l2-adapter '{"type": "fs_native", "base_path": "/data/lmcache/l2", "num_workers": 32, "use_odirect": true}'
diff --git a/docs/source/mp/l2_storage/hfbucket.rst b/docs/source/mp/l2_storage/hfbucket.rst
new file mode 100644
index 0000000..499ce38
--- /dev/null
+++ b/docs/source/mp/l2_storage/hfbucket.rst
@@ -0,0 +1,52 @@
+HF Bucket
+=========
+
+An L2 adapter that stores KV cache objects in a `Hugging Face Bucket
+<https://huggingface.co/docs/hub/storage-backends>`_ using the
+``huggingface_hub`` bucket APIs.  Blocking Hub calls run on a bounded thread
+pool driven by an asyncio loop on a daemon thread, so the L2 controller thread
+is never blocked on network I/O.
+
+Object names are derived from the MP ``ObjectKey`` as
+``<model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]`` and then encoded with
+the standard HFBucket object-name encoding plus the optional bucket prefix.
+Because Hugging Face batch writes are not transactional, a store task that
+partially fails reconciles backend metadata so that any objects that actually
+landed are still counted for usage accounting and later deletion.
+
+This is a persistent remote backend best suited to warm and cold KV cache
+tiers; prefer a lower-latency local adapter for the hottest cache tier.
+
+**Required fields:**
+
+- ``bucket_handle``: Bucket location in the form
+  ``hf://buckets/<namespace>/<bucket>[/<prefix>]``.
+
+**Optional fields:**
+
+- ``token_env`` (string, default ``"HF_TOKEN"``): Environment variable used to
+  resolve the Hugging Face access token.
+- ``token`` (string): Direct token fallback used when ``token_env`` is unset.
+- ``create_bucket_if_missing`` (bool, default ``false``): Create the bucket
+  lazily on the first store instead of requiring it to exist.
+- ``download_tmp_dir`` (string): Root directory for temporary load downloads.
+- ``metadata_cache_ttl_secs`` (float, default ``30.0``): TTL for the
+  path-size metadata cache that backs lookups and usage accounting.
+- ``num_workers`` (int, default ``4``): Number of worker threads for blocking
+  Hugging Face Hub API calls.
+- ``max_capacity_gb`` (float, default ``0.0``): Aggregate capacity used by
+  ``get_usage()``.  A value of ``0`` disables aggregate eviction.
+- ``eviction`` (dict): Optional eviction policy, see ``L2AdapterConfigBase``.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Minimal: use an existing bucket with a token from $HF_TOKEN
+    --l2-adapter '{"type": "hfbucket", "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod"}'
+
+    # Create the bucket on first store and bound the worker pool
+    --l2-adapter '{"type": "hfbucket", "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod", "create_bucket_if_missing": true, "num_workers": 8}'
+
+    # Enable aggregate eviction with a capacity cap
+    --l2-adapter '{"type": "hfbucket", "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod", "max_capacity_gb": 50, "eviction": {"eviction_policy": "LRU", "trigger_watermark": 0.9, "eviction_ratio": 0.1}}'
diff --git a/docs/source/mp/l2_storage/index.rst b/docs/source/mp/l2_storage/index.rst
new file mode 100644
index 0000000..029dc71
--- /dev/null
+++ b/docs/source/mp/l2_storage/index.rst
@@ -0,0 +1,343 @@
+Secondary KV Storage
+====================
+
+LMCache multiprocess mode supports a two-tier storage architecture:
+
+- **L1 (fast tier)** -- CPU memory by default, or an NVMe slab via GPUDirect
+  Storage (cuFile) when ``--gds-l1-path`` is set, managed by the L1 Manager.
+  All KV cache chunks live here during active use. (Byte-array L2 adapters are
+  unsupported under the GDS L1 tier, which exposes no L1 memory buffer.)
+- **L2 (persistent)** -- Durable storage backends (NIXL-based or plain
+  file-system/raw-block).  The StoreController asynchronously pushes data from L1
+  to L2, and the PrefetchController loads data from L2 back into L1 on
+  cache misses.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Data Flow
+---------
+
+**Write path (L1 -> L2):**
+
+1. vLLM stores KV cache chunks into L1 via the ``STORE`` RPC.
+2. The ``StoreController`` detects new objects (via eventfd) and
+   asynchronously submits store tasks to each configured L2 adapter.
+3. The L2 adapter writes the data to its backend (e.g., local SSD via GDS).
+
+**Read path (L2 -> L1):**
+
+1. A ``LOOKUP`` RPC checks L1 for prefix hits.
+2. For keys not found in L1, the ``PrefetchController`` submits lookup
+   requests to L2 adapters.
+3. If found in L2, the data is loaded back into L1 and read-locked for the
+   pending ``RETRIEVE`` RPC.
+
+Adapter Types
+-------------
+
+LMCache ships several L2 storage backends, grouped by medium under
+:doc:`Supported Backends <supported_storages>`. Select one or more with the
+``--l2-adapter`` flag.
+
+.. toctree::
+   :maxdepth: 2
+
+   supported_storages
+
+Multiple Adapters (Cascade)
+---------------------------
+
+You can configure multiple L2 adapters by repeating the ``--l2-adapter``
+argument.  Adapters are used in the order they are specified.  The
+``StoreController`` pushes data to all configured adapters, and the
+``PrefetchController`` queries adapters in order during lookups.
+
+.. code-block:: bash
+
+    # SSD (fast, smaller) + NVMe GDS (larger capacity)
+    --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/ssd/l2", "use_direct_io": "false"}, "pool_size": 64}' \
+    --l2-adapter '{"type": "nixl_store", "backend": "GDS", "backend_params": {"file_path": "/data/nvme/l2", "use_direct_io": "true"}, "pool_size": 128}'
+
+Store and Prefetch Policies
+----------------------------
+
+The **store policy** controls how keys flow from L1 to L2: which adapters
+receive each key and whether keys are deleted from L1 after a successful
+L2 store.  The **prefetch policy** controls how keys flow from L2 back to
+L1: when multiple adapters have the same key, the policy decides which
+adapter loads it.
+
+Select policies via CLI:
+
+.. code-block:: bash
+
+    --l2-store-policy default \
+    --l2-prefetch-policy default
+
+**Built-in policies:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 15 70
+
+   * - Flag
+     - Name
+     - Behaviour
+   * - ``--l2-store-policy``
+     - ``default``
+     - Store all keys to all adapters.  Never delete from L1.
+   * - ``--l2-store-policy``
+     - ``skip_l1``
+     - Buffer-only mode.  Store all keys to all adapters, then
+       **delete them from L1** immediately.  Pair with
+       ``--eviction-policy noop`` to avoid useless LRU overhead.
+   * - ``--l2-prefetch-policy``
+     - ``default``
+     - For each key, pick the first (lowest-indexed) adapter that has it.
+       Prefetched keys are **temporary** (deleted after the reader finishes).
+   * - ``--l2-prefetch-policy``
+     - ``retain``
+     - Same load plan as ``default``, but prefetched keys are **retained**
+       permanently in L1.  Useful when prefetched data is likely reused
+       by subsequent requests (e.g. shared system-prompt chunks).
+
+Prefetch Concurrency
+~~~~~~~~~~~~~~~~~~~~~
+
+The ``--l2-prefetch-max-in-flight`` flag limits the number of concurrent
+prefetch requests that the ``PrefetchController`` can have in flight at
+any time.  A higher value increases L2-to-L1 throughput but also
+increases L1 memory pressure from in-flight data.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--l2-prefetch-max-in-flight``
+     - ``8``
+     - Maximum number of concurrent prefetch requests.
+
+Buffer-Only Mode
+~~~~~~~~~~~~~~~~~
+
+When L1 is used purely as a write buffer (all data lives in L2), use
+``--l2-store-policy skip_l1`` together with ``--eviction-policy noop``.
+This combination deletes keys from L1 as soon as they are stored to L2
+and disables the LRU eviction tracker entirely, reducing memory and CPU
+overhead.
+
+.. code-block:: bash
+
+    --eviction-policy noop \
+    --l2-store-policy skip_l1 \
+    --l2-prefetch-policy default
+
+Policies are extensible -- new policies can be added by creating a file
+in ``storage_controllers/`` and calling ``register_store_policy()`` or
+``register_prefetch_policy()`` at import time.  See the design doc
+``l2_adapters/design_docs/overall.md`` for details.
+
+Serde (compression / quantization)
+----------------------------------
+
+Each adapter can optionally run a **serde** (serializer / deserializer)
+that transforms data on the way in and out of L2 — e.g. fp8 quantization
+for disk backends, or encryption for remote adapters. See
+:doc:`KV Cache Compression </mp/serde>` for details and configuration.
+
+.. toctree::
+   :maxdepth: 1
+
+   /mp/serde
+
+Eviction
+--------
+
+LMCache supports eviction at both storage tiers so that each tier
+can operate within a fixed capacity budget.
+
+L1 Eviction
+~~~~~~~~~~~
+
+L1 eviction runs a single background thread that monitors overall L1
+memory usage. When usage exceeds ``trigger_watermark``, the eviction
+policy evicts a fraction of the least-recently-used keys.
+
+**CLI flags:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--eviction-policy``
+     - *(required)*
+     - Policy name: ``LRU`` or ``noop``.
+   * - ``--eviction-trigger-watermark``
+     - ``0.8``
+     - L1 usage fraction [0, 1] above which eviction is triggered.
+   * - ``--eviction-ratio``
+     - ``0.2``
+     - Fraction of currently allocated L1 memory to evict per cycle.
+
+**Example:**
+
+.. code-block:: bash
+
+    --eviction-policy LRU \
+    --eviction-trigger-watermark 0.8 \
+    --eviction-ratio 0.2
+
+L2 Eviction
+~~~~~~~~~~~
+
+L2 eviction is **per-adapter** and **opt-in**. Each adapter can
+independently declare an eviction policy by adding an ``"eviction"``
+sub-object to its ``--l2-adapter`` JSON spec. Adapters without an
+``"eviction"`` key have no eviction controller.
+
+When L2 eviction is enabled for an adapter, a dedicated background
+thread monitors that adapter's ``get_usage()`` value. Once usage
+exceeds ``trigger_watermark``, the policy evicts keys until usage
+drops by ``eviction_ratio``.
+
+**``"eviction"`` sub-object fields:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Field
+     - Default
+     - Description
+   * - ``eviction_policy``
+     - *(required)*
+     - Policy name: ``"LRU"`` or ``"noop"``.
+   * - ``trigger_watermark``
+     - ``0.8``
+     - Adapter usage fraction [0, 1] above which eviction is triggered.
+   * - ``eviction_ratio``
+     - ``0.2``
+     - Fraction of used capacity to evict per cycle.
+
+**Example — nixl_store with LRU eviction:**
+
+.. code-block:: bash
+
+    --l2-adapter '{
+      "type": "nixl_store",
+      "backend": "POSIX",
+      "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false"},
+      "pool_size": 128,
+      "eviction": {
+        "eviction_policy": "LRU",
+        "trigger_watermark": 0.8,
+        "eviction_ratio": 0.2
+      }
+    }'
+
+**Adapter support:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Adapter
+     - L2 Eviction Support
+   * - ``nixl_store``
+     - Full support. ``delete`` frees pool slots; pinned keys (in-flight
+       loads) are skipped and retried on the next cycle.
+   * - ``nixl_store_dynamic``
+     - Full support. ``delete`` removes data files from disk; pinned
+       keys are skipped. ``get_usage`` is byte-based
+       (``_total_bytes / max_capacity_bytes``).
+   * - ``mock``
+     - Full support. Useful for testing eviction behaviour without
+       real storage hardware.
+   * - ``raw_block``
+     - Full shared/global eviction support. ``delete`` recycles raw-block
+       slots; locked entries are skipped and retried on the next cycle.
+   * - ``s3``
+     - ``delete`` removes objects from the bucket and frees aggregate
+       byte accounting. ``get_usage`` reports ``usage_fraction == -1.0``
+       when ``max_capacity_gb`` is ``0`` (disabled); set a non-zero
+       ``max_capacity_gb`` to enable the watermark-triggered eviction
+       controller.
+   * - ``hfbucket``
+     - ``delete`` removes objects from the bucket and frees aggregate
+       byte accounting. ``get_usage`` reports ``usage_fraction == -1.0``
+       when ``max_capacity_gb`` is ``0`` (disabled); set a non-zero
+       ``max_capacity_gb`` to enable the watermark-triggered eviction
+       controller. Locked keys (in-flight loads) are skipped.
+   * - ``dax``
+     - Full support. ``delete`` removes unlocked keys from the in-memory
+       index immediately and recycles fixed slots once active read borrows
+       drain. Usage is slot-based.
+   * - ``mooncake_store``
+     - No eviction support (native connector adapter).
+   * - ``fs``
+     - No eviction support (``delete`` and ``get_usage`` are no-ops).
+   * - native connectors
+     - No eviction support.
+
+.. note::
+
+   Each L2 adapter instance gets its own independent eviction
+   controller and policy.  Two adapters of the same type can have
+   different watermarks or policies.
+
+Combined L1 + L2 Eviction Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    --l1-size-gb 100 \
+    --eviction-policy LRU \
+    --eviction-trigger-watermark 0.8 \
+    --eviction-ratio 0.2 \
+    --l2-adapter '{
+      "type": "nixl_store",
+      "backend": "GDS",
+      "backend_params": {"file_path": "/data/nvme/l2", "use_direct_io": "true"},
+      "pool_size": 256,
+      "eviction": {
+        "eviction_policy": "LRU",
+        "trigger_watermark": 0.9,
+        "eviction_ratio": 0.1
+      }
+    }'
+
+In this setup:
+
+- L1 evicts from memory when it is 80 % full, reclaiming 20 % of
+  allocated memory per cycle.
+- L2 (NIXL/GDS) evicts from the storage pool when 90 % of pool slots
+  are occupied, reclaiming 10 % per cycle.
+- Both tiers use independent LRU policies, so each evicts its own
+  least-recently-used keys.
+
+Verifying L2 Storage
+--------------------
+
+Set ``LMCACHE_LOG_LEVEL=DEBUG`` to see L2 activity in the server logs:
+
+.. code-block:: bash
+
+    LMCACHE_LOG_LEVEL=DEBUG lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false"}, "pool_size": 64}'
+
+Expected log messages when L2 is active:
+
+.. code-block:: text
+
+    LMCache DEBUG: Submitted store task ...
+    LMCache DEBUG: L2 store task N completed ...
+    LMCache DEBUG: Prefetch request submitted: X total keys, Y L1 prefix hits, Z remaining for L2
diff --git a/docs/source/mp/l2_storage/mock.rst b/docs/source/mp/l2_storage/mock.rst
new file mode 100644
index 0000000..9a86845
--- /dev/null
+++ b/docs/source/mp/l2_storage/mock.rst
@@ -0,0 +1,14 @@
+Mock
+====
+
+Simulates L2 storage with configurable size and bandwidth.  Useful for testing
+the L2 pipeline without real storage hardware.
+
+**Fields:**
+
+- ``max_size_gb``: Maximum size in GB (> 0).
+- ``mock_bandwidth_gb``: Simulated bandwidth in GB/sec (> 0).
+
+.. code-block:: bash
+
+    --l2-adapter '{"type": "mock", "max_size_gb": 256, "mock_bandwidth_gb": 10}'
diff --git a/docs/source/mp/l2_storage/mooncake_store.rst b/docs/source/mp/l2_storage/mooncake_store.rst
new file mode 100644
index 0000000..01ff1c6
--- /dev/null
+++ b/docs/source/mp/l2_storage/mooncake_store.rst
@@ -0,0 +1,111 @@
+Mooncake Store
+==============
+
+An L2 adapter backed by the native C++ Mooncake Store connector.  Uses
+`Mooncake <https://github.com/kvcache-ai/Mooncake>`_ for high-performance
+distributed KV cache storage with RDMA support.
+
+When Mooncake is configured with ``"protocol": "rdma"``, LMCache must also
+have a valid contiguous L1 memory region available.  The distributed storage
+manager passes this L1 memory descriptor to the adapter factory automatically
+in MP mode.  If the descriptor is missing or invalid, adapter creation fails
+with ``ValueError`` instead of silently falling back to a non-RDMA path.
+
+**Prerequisites -- Building with Mooncake support:**
+
+The Mooncake extension is **not** built by default.  You must explicitly
+enable it:
+
+.. code-block:: bash
+
+    BUILD_MOONCAKE=1 pip install -e . --verbose
+
+The ``BUILD_MOONCAKE`` environment variable controls compilation:
+
+- ``BUILD_MOONCAKE=1``: Enable the Mooncake C++ extension.
+- ``BUILD_MOONCAKE=0``: Force disable (highest priority), even if
+  ``MOONCAKE_INCLUDE_DIR`` is set.
+- **Not set**: Falls back to checking ``MOONCAKE_INCLUDE_DIR`` for
+  backward compatibility.  If ``MOONCAKE_INCLUDE_DIR`` is also unset,
+  the extension is skipped.
+
+If the Mooncake headers are not installed in the system include path
+(e.g., ``/usr/local/include``), you must point to them explicitly:
+
+.. code-block:: bash
+
+    BUILD_MOONCAKE=1 \
+    MOONCAKE_INCLUDE_DIR=/path/to/mooncake/include \
+    MOONCAKE_LIB_DIR=/path/to/mooncake/lib \
+    pip install -e . --verbose
+
+**LMCache-specific fields:**
+
+- ``num_workers``: Number of C++ worker threads for the shared pool
+  (default ``4``, must be > 0).
+
+- ``per_op_workers`` (``dict[str, int]``, optional): A dict mapping lane keys
+  to dedicated worker thread counts.  Supported keys:
+
+  - ``"lookup"`` — threads for ``EXISTS`` operations.
+  - ``"retrieve"`` — threads for ``GET`` / load operations.
+  - ``"store"`` — threads for ``SET`` / put operations.
+  - ``"delete"`` — threads for ``DELETE`` operations.
+
+  Operations whose lane key is **not** present in the dict use the
+  shared ``num_workers`` pool.  There is no requirement to set all
+  keys — you can configure only the lanes that need dedicated pools.
+
+**Mooncake fields:**
+
+All other keys in the JSON config (except ``type``, ``num_workers``,
+``per_op_workers``, and ``eviction``) are forwarded **as-is** to Mooncake's
+``setup_internal(ConfigDict)``.  Refer to the
+`Mooncake documentation <https://github.com/kvcache-ai/Mooncake>`_
+for available setup keys (e.g., ``local_hostname``,
+``metadata_server``, ``master_server_addr``, ``protocol``,
+``rdma_devices``, ``global_segment_size``).
+
+**Configuration example:**
+
+.. code-block:: bash
+
+    # Shared pool (default)
+    --l2-adapter '{
+      "type": "mooncake_store",
+      "num_workers": 4,
+      "local_hostname": "node01",
+      "metadata_server": "http://localhost:8080/metadata",
+      "master_server_addr": "localhost:50051",
+      "protocol": "tcp",
+      "local_buffer_size": "3221225472",
+      "global_segment_size": "3221225472"
+    }'
+
+    # Per-operation pools (GET-heavy workload)
+    --l2-adapter '{
+      "type": "mooncake_store",
+      "per_op_workers": {
+        "lookup": 2,
+        "retrieve": 16,
+        "store": 4
+      },
+      "local_hostname": "node01",
+      "metadata_server": "http://localhost:8080/metadata",
+      "master_server_addr": "localhost:50051",
+      "protocol": "tcp"
+    }'
+
+For full Mooncake setup instructions (master service, metadata server,
+etc.), see `Mooncake <https://github.com/kvcache-ai/Mooncake>`_ .
+
+**RDMA notes:**
+
+- ``protocol: "rdma"`` requires a valid LMCache L1 memory descriptor.
+- When using ``protocol: "rdma"``, it is recommended to disable lazy L1
+  allocation with ``--no-l1-use-lazy`` so the L1 buffer is fully allocated
+  before Mooncake registers it.
+- ``protocol: "tcp"`` does not require L1 preregistration.
+- If Mooncake RDMA initialization fails at adapter creation time, verify that
+  LMCache L1 memory is enabled and that the descriptor has a non-zero pointer
+  and size.
diff --git a/docs/source/mp/l2_storage/nixl.rst b/docs/source/mp/l2_storage/nixl.rst
new file mode 100644
index 0000000..120542c
--- /dev/null
+++ b/docs/source/mp/l2_storage/nixl.rst
@@ -0,0 +1,135 @@
+NIXL
+====
+
+NIXL-based persistent storage — the primary production L2 backend, using NIXL
+(NVIDIA Interconnect Library) for high-performance storage I/O. Two adapter
+types share this backend:
+
+- ``nixl_store`` — a fixed pool of storage descriptors pre-allocated at init.
+- ``nixl_store_dynamic`` — opens and registers files per operation, adding
+  persist/recover across restarts and removing the open-file-descriptor limit.
+
+Static pool — ``nixl_store``
+----------------------------
+
+The primary production adapter. Pre-allocates a pool of storage descriptors at
+initialization.
+
+**Required fields:**
+
+- ``backend``: Storage backend -- one of ``POSIX``, ``GDS``, ``GDS_MT``,
+  ``HF3FS``, ``OBJ``, ``AZURE_BLOB``.
+- ``pool_size``: Number of storage descriptors to pre-allocate (must be > 0).
+
+**Backend-specific parameters (``backend_params``):**
+
+File-based backends (``GDS``, ``GDS_MT``, ``POSIX``, ``HF3FS``) require:
+
+- ``file_path``: Directory path for storing L2 data.
+- ``use_direct_io``: ``"true"`` or ``"false"`` -- whether to use direct I/O.
+
+The ``OBJ`` and ``AZURE_BLOB`` backends (object stores) do not require ``file_path``.
+
+**Backend descriptions:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 85
+
+   * - Backend
+     - Description
+   * - ``POSIX``
+     - Standard POSIX file I/O.  Works on any file system.  No direct I/O.
+   * - ``GDS``
+     - NVIDIA GPU Direct Storage.  Enables direct GPU-to-storage transfers
+       bypassing the CPU.  Requires NVMe SSDs with GDS support.
+   * - ``GDS_MT``
+     - Multi-threaded variant of GDS for higher throughput.
+   * - ``HF3FS``
+     - Shared file system backend (e.g., for distributed/networked storage).
+   * - ``OBJ``
+     - Object store backend.  No local file path required.
+   * - ``AZURE_BLOB``
+     - Object store backend for Azure Blob Storage.  No local file path required.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # POSIX backend
+    --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false"}, "pool_size": 64}'
+
+    # GDS backend
+    --l2-adapter '{"type": "nixl_store", "backend": "GDS", "backend_params": {"file_path": "/data/nvme/lmcache", "use_direct_io": "true"}, "pool_size": 128}'
+
+    # GDS_MT backend
+    --l2-adapter '{"type": "nixl_store", "backend": "GDS_MT", "backend_params": {"file_path": "/data/nvme/lmcache", "use_direct_io": "true"}, "pool_size": 128}'
+
+    # HF3FS backend
+    --l2-adapter '{"type": "nixl_store", "backend": "HF3FS", "backend_params": {"file_path": "/mnt/hf3fs/lmcache", "use_direct_io": "false"}, "pool_size": 64}'
+
+    # OBJ backend
+    --l2-adapter '{"type": "nixl_store", "backend": "OBJ", "backend_params": {}, "pool_size": 32}'
+
+    # AZURE_BLOB backend
+    --l2-adapter '{"type": "nixl_store", "backend": "AZURE_BLOB", "backend_params": {"account_url": "https://<account_name>.blob.core.windows.net", "container_name": "<container_name>"}, "pool_size": 32}'
+
+Dynamic (persist / recover) — ``nixl_store_dynamic``
+----------------------------------------------------
+
+A dynamic variant of the NIXL adapter that opens and registers files
+per-operation instead of pre-allocating them at init. This enables:
+
+- **Persist/recover** -- cached KV metadata survives restarts.
+- **No fd limits** -- files are opened and closed per transfer, so the
+  cache can grow beyond OS open-file-descriptor limits.
+
+.. note::
+
+   Only file-based backends are supported (``POSIX``, ``GDS``, ``GDS_MT``,
+   ``HF3FS``). The ``OBJ`` and ``AZURE_BLOB`` backends are not supported yet.
+
+**Required fields:**
+
+- ``backend``: Storage backend -- one of ``POSIX``, ``GDS``, ``GDS_MT``,
+  ``HF3FS``.
+
+**Backend-specific parameters (``backend_params``):**
+
+- ``file_path``: Directory path for storing L2 data files.
+- ``use_direct_io``: ``"true"`` or ``"false"``.
+- ``max_capacity_gb``: Maximum storage capacity in GB. The adapter
+  rejects stores when this limit is reached. Required for the eviction
+  controller to compute usage.
+
+**Optional fields (for persist):**
+
+- ``persist_enabled`` (bool, default ``true``): If ``true``, data files
+  are kept on disk at shutdown. If ``false``, all data files are deleted
+  on shutdown.
+
+Lookup always checks secondary storage (disk) on miss and lazily
+populates the in-memory index when a file is found.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Basic dynamic POSIX backend (persist enabled by default)
+    --l2-adapter '{"type": "nixl_store_dynamic", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false", "max_capacity_gb": "10"}}'
+
+    # Explicitly disable persist
+    --l2-adapter '{"type": "nixl_store_dynamic", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false", "max_capacity_gb": "10"}, "persist_enabled": false}'
+
+    # With eviction
+    --l2-adapter '{"type": "nixl_store_dynamic", "backend": "GDS", "backend_params": {"file_path": "/data/nvme/l2", "use_direct_io": "true", "max_capacity_gb": "50"}, "eviction": {"eviction_policy": "LRU", "trigger_watermark": 0.9, "eviction_ratio": 0.1}}'
+
+**Persist / secondary lookup behaviour:**
+
+- On **shutdown**, the adapter keeps data files on disk by default
+  (``persist_enabled`` defaults to ``true``). If explicitly set to
+  ``false``, all data files are deleted to avoid orphaned storage.
+- On **startup**, the in-memory index is empty. Every lookup miss falls
+  through to a secondary lookup on disk: if the deterministic file
+  exists, it is treated as a hit and the in-memory index is populated
+  lazily from the file size.
diff --git a/docs/source/mp/l2_storage/plugin.rst b/docs/source/mp/l2_storage/plugin.rst
new file mode 100644
index 0000000..34b2250
--- /dev/null
+++ b/docs/source/mp/l2_storage/plugin.rst
@@ -0,0 +1,88 @@
+Plugin (Custom / External)
+==========================
+
+Two L2 adapter types load an adapter class from a *user-supplied* Python
+module at startup, so you can point LMCache at your own storage backend
+without modifying LMCache source.  This is the ``--l2-adapter`` analog of
+vLLM's ``kv_connector_module_path``.
+
+- ``plugin``: loads a pure-Python class that implements
+  ``L2AdapterInterface`` (the full L2 adapter contract).
+- ``native_plugin``: loads a pybind-wrapped C++ connector exposing a
+  six-method async batch contract and wraps it in
+  ``NativeConnectorL2Adapter``.  Use this for native backends -- see also
+  :doc:`/developer_guide/extending_lmcache/native_connectors`.
+
+``plugin``
+----------
+
+Dynamically imports ``module_path`` and instantiates ``class_name``, which
+must be a subclass of ``L2AdapterInterface`` (validated at load time; a
+mismatch raises ``TypeError``).
+
+**Required fields:**
+
+- ``module_path`` (str): Dotted Python import path of the module containing
+  the adapter class.  The module must be importable by the LMCache process
+  (installed, or on ``PYTHONPATH``).
+- ``class_name`` (str): Name of the class inside *module_path* that
+  implements ``L2AdapterInterface``.
+
+**Optional fields:**
+
+- ``adapter_params`` (dict, default ``{}``): Arbitrary dict forwarded to the
+  adapter constructor.
+- ``config_class_name`` (str): Name of a config class inside *module_path*
+  that subclasses ``L2AdapterConfigBase``.  When set (or auto-discovered),
+  the factory builds it via ``from_dict(adapter_params)`` and passes the
+  config object -- instead of the raw ``adapter_params`` dict -- to the
+  adapter constructor, matching the built-in adapter convention.  Discovery
+  order when omitted: ``<class_name>Config`` in the module, then a
+  ``config_class_name`` attribute on the adapter class; otherwise the raw
+  dict is passed.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Raw-dict mode: adapter_params is passed straight to the constructor
+    --l2-adapter '{"type": "plugin", "module_path": "my_plugin.l2", "class_name": "MyL2Adapter", "adapter_params": {"host": "localhost"}}'
+
+    # Config-class mode: my_plugin.l2.MyL2AdapterConfig.from_dict(adapter_params) is built and passed
+    --l2-adapter '{"type": "plugin", "module_path": "my_plugin.l2", "class_name": "MyL2Adapter", "config_class_name": "MyL2AdapterConfig", "adapter_params": {"host": "localhost"}}'
+
+See ``examples/lmc_external_l2_adapter/`` for a complete reference plugin.
+
+``native_plugin``
+-----------------
+
+Dynamically imports ``module_path``, instantiates ``class_name`` with
+``adapter_params`` as constructor keyword arguments, verifies the instance
+exposes the required async batch methods (``event_fd``, ``submit_batch_get``,
+``submit_batch_set``, ``submit_batch_exists``, ``drain_completions``,
+``close``), and wraps it in ``NativeConnectorL2Adapter``.  An optional
+``submit_batch_delete`` enables L2 eviction deletes; without it, deletes are
+a no-op (logged as a warning).
+
+**Required fields:**
+
+- ``module_path`` (str): Dotted Python import path of the module containing
+  the connector class.
+- ``class_name`` (str): Name of the connector class inside *module_path*.
+
+**Optional fields:**
+
+- ``adapter_params`` (dict, default ``{}``): Forwarded as keyword arguments
+  to the connector constructor.
+- ``max_capacity_gb`` (float, default ``0``): Aggregate L2 capacity in GB for
+  usage tracking / eviction.  ``0`` disables aggregate eviction.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Native pybind connector with constructor kwargs
+    --l2-adapter '{"type": "native_plugin", "module_path": "my_ext.connector", "class_name": "MyConnectorClient", "adapter_params": {"host": "localhost", "port": 1234}}'
+
+See ``examples/lmc_external_native_connector/`` for a complete reference
+native connector.
diff --git a/docs/source/mp/l2_storage/raw_block.rst b/docs/source/mp/l2_storage/raw_block.rst
new file mode 100644
index 0000000..422bdb9
--- /dev/null
+++ b/docs/source/mp/l2_storage/raw_block.rst
@@ -0,0 +1,76 @@
+Raw Block (Rust)
+================
+
+A built-in L2 adapter that stores KV objects in fixed-size slots on a raw block
+device or pre-sized file using the Rust raw-device I/O bindings. It reuses the
+existing raw-block metadata checkpoint model and writes directly into the
+caller-provided load buffers during prefetch.
+
+**Required fields:**
+
+- ``device_path``: Raw device path or pre-sized file path.
+- ``slot_bytes``: Fixed slot size in bytes. Must be aligned to ``block_align``.
+
+**Optional fields:**
+
+- ``capacity_bytes``: Optional cap on the usable device bytes. Default ``0``
+  means use the full device/file size.
+- ``use_odirect``: ``true`` or ``false`` (default ``true``).
+- ``block_align``: Device alignment in bytes (default ``4096``).
+- ``header_bytes``: Per-slot header reservation (default ``4096``).
+- ``meta_total_bytes``: Reserved metadata checkpoint region (default ``256MiB``).
+- ``meta_magic`` / ``meta_version``: Metadata checkpoint identity/version knobs.
+- ``meta_checkpoint_interval_sec`` / ``meta_idle_quiet_ms`` /
+  ``meta_enable_periodic`` / ``meta_verify_on_load``: Checkpoint and recovery
+  controls carried over from the legacy raw-block backend.
+- ``load_checkpoint_on_init``: Load an existing on-device metadata checkpoint
+  during startup (default ``true``). Set to ``false`` to start with an empty
+  in-memory index instead.
+- ``enable_zero_copy``: Try aligned direct-buffer I/O when possible.
+- ``io_engine``: Rust raw-block I/O engine. Valid values are ``"posix"``
+  (default synchronous ``pread``/``pwrite`` path), ``"io_uring"`` (direct Rust
+  io_uring syscall path).
+- ``use_uring_cmd``: Enable NVMe passthrough via io_uring command interface
+  for direct device access. Requires ``io_engine="io_uring"`` and NVMe
+  character device node (e.g., ``/dev/ng0n1``).
+- ``iouring_queue_depth``: Queue depth for ``io_engine="io_uring"``.
+- ``max_data_transfer_size``: Maximum data transfer size for
+  ``use_uring_cmd=true``. Large transfers are split into smaller chunks
+  that fit within device limits.
+- ``num_store_workers`` / ``num_lookup_workers`` / ``num_load_workers``:
+  Worker-thread counts for each operation type.
+
+**Notes:**
+
+- ``raw_block`` is a server-owned MP adapter. It does **not** support
+  per-TP device-path mappings in MP mode.
+- ``raw_block`` remains ``"type": "raw_block"`` for all supported engines.
+- ``raw_block`` owns on-device slot allocation, checkpointing, and recovery
+  through ``RawBlockCore``. Slot reclamation is driven by the shared/global
+  L2 eviction controller or explicit ``delete()`` calls.
+- If ``use_odirect`` is enabled, the server's ``--l1-align-bytes`` should be
+  at least ``block_align``.
+- ``persist_enabled`` must remain ``true`` for this adapter.
+- For ``use_uring_cmd=true``, ``device_path`` must use the NVMe character
+  device node (e.g., ``/dev/ng0n1``) instead of the block device node
+  (``/dev/nvme0n1``). The character device provides direct NVMe
+  command passthrough.
+- ``use_uring_cmd`` requires ``io_engine="io_uring"`` to be set.
+- When ``use_uring_cmd=true``, ``use_odirect`` is ignored for NVMe namespace
+  character devices.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Basic raw_block with posix I/O
+    --l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "block_align": 4096, "header_bytes": 4096, "meta_total_bytes": 268435456, "use_odirect": true, "num_store_workers": 2, "num_lookup_workers": 1, "num_load_workers": 4}'
+
+    # With io_uring
+    --l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "io_engine": "io_uring", "iouring_queue_depth": 256, "use_odirect": true}'
+
+    # With io_uring_cmd (NVMe passthrough)
+    --l2-adapter '{"type": "raw_block", "device_path": "/dev/ng0n1", "slot_bytes": 1048576, "io_engine": "io_uring", "use_uring_cmd": true, "iouring_queue_depth": 256, "max_data_transfer_size": 131072, "use_odirect": false}'
+
+    # With eviction
+    --l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "load_checkpoint_on_init": false, "eviction": {"eviction_policy": "LRU", "trigger_watermark": 0.9, "eviction_ratio": 0.1}}'
diff --git a/docs/source/mp/l2_storage/remote_and_distributed.rst b/docs/source/mp/l2_storage/remote_and_distributed.rst
new file mode 100644
index 0000000..fd97047
--- /dev/null
+++ b/docs/source/mp/l2_storage/remote_and_distributed.rst
@@ -0,0 +1,14 @@
+Remote & Distributed
+====================
+
+Object stores and distributed KV stores -- suited to warm/cold cache tiers and
+sharing cache across nodes.
+
+.. toctree::
+   :maxdepth: 1
+
+   s3
+   hfbucket
+   mooncake_store
+   resp
+   aerospike
diff --git a/docs/source/mp/l2_storage/resp.rst b/docs/source/mp/l2_storage/resp.rst
new file mode 100644
index 0000000..41c6c57
--- /dev/null
+++ b/docs/source/mp/l2_storage/resp.rst
@@ -0,0 +1,34 @@
+RESP (Redis/Valkey)
+===================
+
+An L2 adapter backed by a native RESP (Redis Serialization Protocol)
+connector, targeting **Redis** or **Valkey** servers. I/O is dispatched
+through a C++ worker-thread pool.
+
+**Required fields:**
+
+- ``host``: Redis/Valkey server hostname or IP.
+- ``port``: Server port (positive integer).
+
+**Optional fields:**
+
+- ``num_workers`` (int, default ``8``): C++ worker threads for I/O (> 0).
+- ``username`` (string, default ``""``): Auth username.
+- ``password`` (string, default ``""``): Auth password.
+- ``max_capacity_gb`` (float, default ``0``): Max L2 capacity in GB for usage
+  tracking / aggregate eviction. ``0`` disables tracking.
+
+When ``host``, ``port``, ``username``, or ``password`` are left empty, the
+adapter falls back to the corresponding environment variables at creation
+time: ``LMCACHE_RESP_HOST``, ``LMCACHE_RESP_PORT``, ``LMCACHE_RESP_USERNAME``,
+``LMCACHE_RESP_PASSWORD``.
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # Basic Redis/Valkey
+    --l2-adapter '{"type": "resp", "host": "127.0.0.1", "port": 6379}'
+
+    # With auth, more workers, and a capacity cap
+    --l2-adapter '{"type": "resp", "host": "redis.internal", "port": 6379, "username": "lmcache", "password": "secret", "num_workers": 16, "max_capacity_gb": 50}'
diff --git a/docs/source/mp/l2_storage/s3.rst b/docs/source/mp/l2_storage/s3.rst
new file mode 100644
index 0000000..b8a4d1a
--- /dev/null
+++ b/docs/source/mp/l2_storage/s3.rst
@@ -0,0 +1,40 @@
+S3
+==
+
+An L2 adapter that stores KV cache objects as S3 objects using the AWS
+Common Runtime (CRT).  Works with AWS S3, S3 Express One Zone, and any
+S3-compatible endpoint (MinIO, Ceph RGW, etc.).
+
+**Required fields:**
+
+- ``s3_endpoint``: Bucket URL -- either ``"s3://<bucket>"`` or the bare host form
+  (used for non-AWS endpoints).
+- ``s3_region``: AWS region string (e.g. ``"us-west-2"``).
+
+**Optional fields:**
+
+- ``s3_num_io_threads`` (int, default ``64``): Number of CRT I/O threads.
+- ``s3_prefer_http2`` (bool, default ``true``): Negotiate HTTP/2 via ALPN.
+- ``s3_enable_s3express`` (bool, default ``false``): Enable S3 Express signing
+  for S3 Express One Zone buckets.
+- ``disable_tls`` (bool, default ``false``): Bypass TLS when pointing at a
+  plain-HTTP endpoint (e.g. a local MinIO).
+- ``aws_access_key_id`` / ``aws_secret_access_key`` (string): Static
+  credentials; omit both to use the AWS default credential provider chain
+  (environment, EC2 instance profile, etc.).
+- ``max_capacity_gb`` (float, default ``0.0``): Aggregate capacity used by
+  ``get_usage()``.  A value of ``0`` disables aggregate eviction
+  (``usage_fraction == -1.0``).
+
+**Configuration examples:**
+
+.. code-block:: bash
+
+    # AWS S3 with default credentials
+    --l2-adapter '{"type": "s3", "s3_endpoint": "s3://my-bucket", "s3_region": "us-west-2"}'
+
+    # Static credentials, HTTP/2 disabled
+    --l2-adapter '{"type": "s3", "s3_endpoint": "s3://my-bucket", "s3_region": "us-west-2", "s3_prefer_http2": false, "aws_access_key_id": "AKIA...", "aws_secret_access_key": "..."}'
+
+    # Local MinIO over plain HTTP
+    --l2-adapter '{"type": "s3", "s3_endpoint": "minio.local:9000", "s3_region": "us-east-1", "disable_tls": true, "aws_access_key_id": "minio", "aws_secret_access_key": "minio123"}'
diff --git a/docs/source/mp/l2_storage/supported_storages.rst b/docs/source/mp/l2_storage/supported_storages.rst
new file mode 100644
index 0000000..06f7540
--- /dev/null
+++ b/docs/source/mp/l2_storage/supported_storages.rst
@@ -0,0 +1,65 @@
+Supported Backends
+==================
+
+LMCache ships several L2 storage backends. Select one or more with the
+``--l2-adapter`` flag (each backend's ``"type"`` is shown below); every backend
+has its own configuration page. They are grouped by the kind of medium they
+target.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 28 42
+
+   * - Backend
+     - ``--l2-adapter`` type
+     - Group
+   * - :doc:`NIXL <nixl>`
+     - ``nixl_store`` / ``nixl_store_dynamic``
+     - High-performance I/O
+   * - :doc:`FileSystem <fs>`
+     - ``fs``
+     - File & Block
+   * - :doc:`FS (native) <fs_native>`
+     - ``fs_native``
+     - File & Block
+   * - :doc:`Raw Block (Rust) <raw_block>`
+     - ``raw_block``
+     - File & Block
+   * - :doc:`S3 <s3>`
+     - ``s3``
+     - Remote & Distributed
+   * - :doc:`HF Bucket <hfbucket>`
+     - ``hfbucket``
+     - Remote & Distributed
+   * - :doc:`Mooncake Store <mooncake_store>`
+     - ``mooncake_store``
+     - Remote & Distributed
+   * - :doc:`RESP (Redis/Valkey) <resp>`
+     - ``resp``
+     - Remote & Distributed
+   * - :doc:`Aerospike <aerospike>`
+     - ``aerospike``
+     - Remote & Distributed
+   * - :doc:`DAX <dax>`
+     - ``dax``
+     - Byte-addressable memory
+   * - :doc:`Mock <mock>`
+     - ``mock``
+     - Testing
+   * - :doc:`Fault Inject <fault_inject>`
+     - ``fault_inject``
+     - Testing
+   * - :doc:`Plugin <plugin>`
+     - ``plugin`` / ``native_plugin``
+     - Custom / External
+
+.. toctree::
+   :maxdepth: 1
+
+   nixl
+   file_and_block
+   remote_and_distributed
+   dax
+   mock
+   fault_inject
+   plugin
diff --git a/docs/source/mp/observability/index.rst b/docs/source/mp/observability/index.rst
new file mode 100644
index 0000000..34989bf
--- /dev/null
+++ b/docs/source/mp/observability/index.rst
@@ -0,0 +1,284 @@
+Observability
+=============
+
+LMCache multiprocess mode provides three complementary observability modes:
+**metrics** (Prometheus counters via OTel), **logging** (Python logging with
+optional OTel log forwarding), and **tracing** (OTel spans for per-request
+latency).
+
+All three modes are powered by an internal **EventBus** that decouples
+producers (L1Manager, StorageManager, MPCacheServer) from subscribers.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Quick Start
+-----------
+
+By default, **metrics** and **logging** are enabled; **tracing** is disabled.
+No extra flags are needed:
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU
+
+The server then exposes Prometheus metrics at ``/metrics`` on its **HTTP
+frontend port** (``--http-port``, default ``8080``):
+
+.. code-block:: bash
+
+    curl http://localhost:8080/metrics | grep lmcache_mp_
+
+.. important::
+
+   For ``lmcache server``, ``/metrics`` lives on ``--http-port`` (default
+   ``8080``), **not** on ``--prometheus-port``: the HTTP frontend already
+   serves ``/metrics``, so the standalone Prometheus server is disabled and
+   ``--prometheus-port`` has no effect under this command. ``--prometheus-port``
+   *is* the metrics endpoint for the frontend-less entrypoints
+   (``python -m lmcache.v1.multiprocess.server`` and ``lmcache trace replay``)
+   — see :ref:`mp-obs-metrics-endpoint`. Also note metrics are lazy: a series
+   only appears *after* the first store/retrieve that produces it, so drive
+   some traffic before scraping.
+
+To also see L2 (storage-tier) metrics, attach an L2 backend with
+``--l2-adapter``. The simplest is the local filesystem:
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2"}'
+
+To enable tracing instead of (or alongside) Prometheus pull, supply an OTLP
+endpoint — this switches metrics to **push mode** (see
+:ref:`mp-obs-grafana`):
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --enable-tracing --otlp-endpoint http://localhost:4317
+
+.. _mp-obs-metrics-endpoint:
+
+Where ``/metrics`` lives
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The pull-mode ``/metrics`` endpoint is served in one of two places depending
+on the entrypoint. Entrypoints that embed the uvicorn HTTP frontend serve it
+there (and disable the standalone Prometheus server); entrypoints with no
+HTTP frontend start the standalone server on ``--prometheus-port`` instead.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 20 40
+
+   * - Entrypoint
+     - HTTP frontend?
+     - Pull-mode ``/metrics`` endpoint
+   * - ``lmcache server``
+     - yes
+     - ``--http-port`` (default ``8080``); ``--prometheus-port`` ignored
+   * - ``python -m lmcache.v1.multiprocess.server``
+     - no
+     - ``--prometheus-port`` (default ``9090``)
+   * - ``lmcache trace replay``
+     - no
+     - ``--prometheus-port`` (default ``9090``)
+
+In **push mode** (``--otlp-endpoint`` set) none of these serve ``/metrics`` —
+metrics are pushed to the collector instead.
+
+.. _mp-obs-grafana:
+
+Viewing Metrics in Grafana
+--------------------------
+
+There are two ways to get LMCache metrics into Grafana. Pick based on whether
+you also want **traces**.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 20 30 28
+
+   * - Path
+     - Server flags
+     - What you run
+     - Gives you
+   * - **A. Bundled stack**
+     - ``--otlp-endpoint`` (push)
+     - ``docker compose up`` in ``examples/observability/``
+     - Metrics **+ traces**, Grafana with the LMCache dashboard
+       auto-provisioned
+   * - **B. Pull mode**
+     - none (default)
+     - Your own Prometheus + Grafana scraping ``:8080``
+     - Metrics only, minimal moving parts, no collector
+
+Path A — bundled Prometheus + Tempo + Grafana
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The repository ships a ready-to-run stack (OpenTelemetry Collector →
+Prometheus + Tempo → Grafana) under ``examples/observability/``. Grafana comes
+with the **LMCache dashboard and datasources pre-provisioned** and anonymous
+access enabled, so there is nothing to click to log in.
+
+.. code-block:: bash
+
+    # 1. Start the observability stack (Collector :4320, Prometheus, Tempo,
+    #    Grafana :3000)
+    cd examples/observability
+    docker compose up -d
+
+    # 2. Start the LMCache server (+ vLLM) pushing OTLP to the collector
+    MODEL=/path/to/model bash start-server.sh
+
+    # 3. Generate traffic, then open Grafana
+    #    http://localhost:3000  ->  Dashboards  ->  "LMCache"
+
+In this path the server pushes to the Collector and **Prometheus scrapes the
+Collector**, so you do *not* scrape the server's ``:8080`` directly.
+
+Path B — pull mode (metrics only, no collector)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you only want metrics, skip the collector entirely and have Prometheus
+scrape the server's ``/metrics`` endpoint directly. Start the server **without**
+``--otlp-endpoint`` (see Quick Start above), then:
+
+.. code-block:: bash
+
+    # 1. Prometheus config: scrape the server's HTTP-frontend port (8080)
+    cat > prometheus.yml <<'YAML'
+    global:
+      scrape_interval: 5s
+    scrape_configs:
+      - job_name: lmcache
+        static_configs:
+          - targets: ["localhost:8080"]   # --http-port, NOT --prometheus-port
+    YAML
+
+    # 2. Run Prometheus (:9090) and Grafana (:3000) on the host network so
+    #    they can reach localhost:8080 and each other.
+    docker run -d --name lmcache-prom --network host \
+        -v "$PWD/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \
+        prom/prometheus
+
+    docker run -d --name lmcache-grafana --network host \
+        -e GF_AUTH_ANONYMOUS_ENABLED=true \
+        -e GF_AUTH_ANONYMOUS_ORG_ROLE=Admin \
+        grafana/grafana
+
+Then in Grafana (``http://localhost:3000``):
+
+1. **Add a datasource** → Prometheus → URL ``http://localhost:9090`` → Save.
+2. **Import the dashboard**: Dashboards → New → Import → upload
+   ``examples/observability/grafana/provisioning/dashboards/lmcache.json``
+   and select the Prometheus datasource. This is the same dashboard the
+   bundled stack provisions (cache hit rate, L1/L2 cache ops, L1↔L2
+   throughput, eviction loop, EventBus health, and more).
+
+Verify the pipeline end to end:
+
+.. code-block:: bash
+
+    # target should be "up"
+    curl -s localhost:9090/api/v1/targets | grep -o '"health":"[a-z]*"'
+
+    # after driving traffic, L2 store throughput (GB/s) per backend:
+    curl -s localhost:9090/api/v1/query --data-urlencode \
+      'query=sum by (l2_name) (rate(lmcache_mp_l2_store_throughput_GB_per_second_sum[1m]))
+             / sum by (l2_name) (rate(lmcache_mp_l2_store_throughput_GB_per_second_count[1m]))'
+
+See :doc:`metrics` for the full metric catalog and more PromQL examples.
+
+.. note::
+
+   ``--network host`` (used above) is the simplest option on Linux. On Docker
+   Desktop (macOS/Windows), drop ``--network host``, publish ports with
+   ``-p 9090:9090`` / ``-p 3000:3000``, and set the scrape target to
+   ``host.docker.internal:8080`` and the Grafana datasource URL to
+   ``http://host.docker.internal:9090``.
+
+Configuration
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Argument
+     - Default
+     - Description
+   * - ``--disable-observability``
+     - off
+     - Master switch: disable the EventBus entirely (no metrics, logging, or
+       tracing subscribers are registered).
+   * - ``--disable-metrics``
+     - off
+     - Skip metrics subscribers (Prometheus endpoint is not started).
+   * - ``--disable-logging``
+     - off
+     - Skip logging subscribers.
+   * - ``--enable-tracing``
+     - off
+     - Register tracing subscribers. Requires ``--otlp-endpoint``.
+   * - ``--event-bus-queue-size``
+     - ``10000``
+     - Maximum events in the EventBus queue before tail-drop.
+   * - ``--otlp-endpoint``
+     - *(none)*
+     - OTLP gRPC endpoint (e.g. ``http://localhost:4317``). Used for
+       exporting metrics (push mode) and traces.
+   * - ``--prometheus-port``
+     - ``9090``
+     - Port of the standalone Prometheus ``/metrics`` server. Started only by
+       frontend-less entrypoints (``python -m lmcache.v1.multiprocess.server``,
+       ``lmcache trace replay``). **Ignored by** ``lmcache server`` — there the
+       HTTP frontend serves ``/metrics`` on ``--http-port`` instead, so the
+       standalone server is disabled. See :ref:`mp-obs-metrics-endpoint`.
+   * - ``--http-port``
+     - ``8080``
+     - Port of the HTTP frontend, which serves the Prometheus ``/metrics``
+       endpoint in pull mode (when ``--otlp-endpoint`` is unset) for
+       ``lmcache server``.
+   * - ``--metrics-sample-rate``
+     - ``0.01``
+     - Fraction of chunks/blocks to track for lifecycle histograms
+       (0, 1.0]. Counters always count all events. Default is 1%.
+   * - ``--trace-level``
+     - *(none)*
+     - Enable trace recording at the given level. Currently only
+       ``storage`` is supported (records ``StorageManager`` public-API
+       calls for offline replay). When unset, trace recording is off.
+       See :ref:`trace-recording` for details.
+   * - ``--trace-output``
+     - *(none)*
+     - Path to write the trace file. If omitted while ``--trace-level``
+       is set, a timestamped file under ``$TMPDIR`` is minted
+       (``lmcache-trace-<pid>-<UTC>.lct``) and its path is logged at INFO.
+
+**Environment variables:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Variable
+     - Default
+     - Description
+   * - ``LMCACHE_LOG_LEVEL``
+     - ``INFO``
+     - Controls the log level for all LMCache loggers. Valid values:
+       ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   metrics
+   logs
+   traces
diff --git a/docs/source/mp/observability/logs.rst b/docs/source/mp/observability/logs.rst
new file mode 100644
index 0000000..fc12b77
--- /dev/null
+++ b/docs/source/mp/observability/logs.rst
@@ -0,0 +1,34 @@
+Logging
+=======
+
+Logging subscribers emit debug-level messages for store, retrieve, lookup,
+L1, and StorageManager events via Python's standard ``logging`` module.
+
+When OpenTelemetry is installed, ``init_logger`` automatically attaches an
+OTel ``LoggingHandler`` so that log records are forwarded to any configured
+OTel ``LoggerProvider``. The handler respects the ``LMCACHE_LOG_LEVEL``
+environment variable.
+
+.. code-block:: bash
+
+    LMCACHE_LOG_LEVEL=DEBUG lmcache server ...
+
+Key log messages:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Level
+     - Message
+   * - INFO
+     - ``Stored N tokens in X seconds``
+   * - INFO
+     - ``Retrieved N tokens in X seconds``
+   * - INFO
+     - ``Prefetch request completed (L1+L2): N/M prefix hits``
+   * - DEBUG
+     - ``MP store start: session=... device=...``
+   * - DEBUG
+     - ``MP retrieve end: session=... retrieved_count=...``
+
diff --git a/docs/source/mp/observability/metrics.rst b/docs/source/mp/observability/metrics.rst
new file mode 100644
index 0000000..7aadf62
--- /dev/null
+++ b/docs/source/mp/observability/metrics.rst
@@ -0,0 +1,585 @@
+Metrics
+=======
+
+Metrics are collected via OpenTelemetry and made available to Prometheus in
+one of two ways, depending on whether ``--otlp-endpoint`` is set:
+
+- **Pull mode (default, no collector).** When ``--otlp-endpoint`` is *not*
+  set, the server publishes a Prometheus ``/metrics`` endpoint that Prometheus
+  scrapes directly.
+
+  .. important::
+
+     For ``lmcache server``, ``/metrics`` is served by the **HTTP frontend**
+     on ``--http-port`` (default **8080**), e.g.
+     ``http://<host>:8080/metrics`` — **not** on ``--prometheus-port``.
+     ``--prometheus-port`` is *ignored* by ``lmcache server``: the standalone
+     Prometheus HTTP server is disabled because the HTTP frontend already
+     serves ``/metrics``. The frontend-less entrypoints
+     (``python -m lmcache.v1.multiprocess.server`` and ``lmcache trace
+     replay``) have no HTTP frontend, so *they* serve ``/metrics`` on
+     ``--prometheus-port`` (default 9090). See
+     :ref:`mp-obs-metrics-endpoint` for the full breakdown. Either way,
+     ``/metrics`` is empty until the first store/retrieve — drive some
+     traffic before you go looking.
+
+- **Push mode (OTLP).** When ``--otlp-endpoint`` is set, metrics are pushed to
+  an OpenTelemetry Collector, which re-exposes them for Prometheus to scrape.
+  See :doc:`index` for the bundled Collector + Prometheus + Grafana stack.
+
+All metrics use the ``lmcache_mp.`` prefix (multiprocess). On Prometheus,
+dots are converted to underscores and counters get a ``_total`` suffix
+(e.g. ``lmcache_mp_l1_read_chunks_total``); histograms gain a unit suffix
+plus ``_sum`` / ``_count`` / ``_bucket`` (e.g.
+``lmcache_mp_l2_store_throughput_GB_per_second_sum``).
+
+.. _mp-observability-resource:
+
+Global Resource Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every metric and span exported by an MP server carries Resource-level
+attributes built at startup. These identify the process producing the
+telemetry and are orthogonal to per-metric attributes such as
+``cache_salt``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 25 45
+
+   * - Attribute
+     - CLI flag / config
+     - Default when unset
+   * - ``service.instance.id``
+     - ``--instance-id`` / ``MPServerConfig.instance_id``
+     - Random UUID v4 minted at startup.
+
+Resource attributes attach to the ``MeterProvider`` / ``TracerProvider``
+and propagate to every exported datapoint via OTLP. On Prometheus, SDK
+resource attributes surface on the ``target_info`` series rather than
+on each time-series — this is standard OTel behavior.
+
+L1 Metrics
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l1_read``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks read from L1, grouped by tenant.
+   * - ``lmcache_mp.l1_write``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks written to L1, grouped by tenant.
+   * - ``lmcache_mp.l1_evicted``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks evicted by the EvictionController, grouped by
+       tenant.
+   * - ``lmcache_mp.l1_eviction_loop_ticks``
+     - Counter
+     - L1 eviction-loop iterations (every cycle, regardless of whether
+       the watermark was crossed). Driven by ``L1_EVICTION_LOOP_TICK``.
+   * - ``lmcache_mp.l1_eviction_loop_triggered``
+     - Counter
+     - L1 eviction-loop iterations where ``usage >= watermark`` and the
+       eviction policy actually ran. The two counters distinguish "loop
+       is alive" from "eviction fired" — important when debugging
+       short-lived benchmarks that complete faster than the 1 Hz
+       polling cycle.
+
+L1 Chunk Lifecycle Histograms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sampled (default 1%) chunk-level lifecycle tracking via
+``L1LifecycleSubscriber``. Only sampled chunks contribute to histograms;
+counters above always count all events. Sampling is deterministic
+(hash-based), so the same key always gets the same decision with zero
+memory overhead.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l1_chunk_lifetime``
+     - Histogram
+     - Time from allocation to eviction per sampled chunk.
+   * - ``lmcache_mp.l1_chunk_idle_before_evict``
+     - Histogram
+     - Time from last access to eviction per sampled chunk.
+   * - ``lmcache_mp.l1_chunk_reuse_gap``
+     - Histogram
+     - Time gap between consecutive touches (read or write) of the same chunk.
+   * - ``lmcache_mp.l1_chunk_evict_reuse_gap``
+     - Histogram
+     - Time from eviction to next reuse (capped at 300 s).
+
+StorageManager Real-Reuse Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Workload-level reuse histograms emitted by ``SMLifecycleSubscriber``,
+driven by caller-facing StorageManager events
+(``SM_READ_PREFETCHED_FINISHED``, ``SM_WRITE_FINISHED``).  Internal
+read-lock releases by the store/prefetch controllers are excluded so
+the signal reflects user-driven access only.
+
+Both histograms are tagged with ``cache_salt`` for per-tenant
+isolation.  The per-salt access counter advances on every read and
+write of every chunk (regardless of sampling) so the chunks-gap
+reflects true storage volume; the histogram itself records gaps only
+for chunks that pass the (deterministic, hash-based) sampling gate.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.real_reuse_gap``
+     - Histogram (tag: ``cache_salt``)
+     - Time gap between a chunk's last access (read or write) and its
+       next read.  Captures storage cost — how long a stored chunk sat
+       between accesses.  Emitted only on read events.
+   * - ``lmcache_mp.real_reuse_gap_objects``
+     - Histogram (tag: ``cache_salt``)
+     - Per-``cache_salt`` access-counter gap between two reads of the
+       same chunk.  Captures storage volume — how many chunk-accesses
+       occurred while this chunk waited for its next read.  Emitted on
+       read events for sampled chunks.
+
+L2 Metrics
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l2_store_submitted``
+     - Counter
+     - Number of L2 store requests submitted.
+   * - ``lmcache_mp.l2_store_submitted_objects``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks submitted for L2 store, grouped by tenant.
+   * - ``lmcache_mp.l2_store_completed``
+     - Counter (attr: ``l2_name``)
+     - Number of L2 store requests completed, labeled by adapter type.
+   * - ``lmcache_mp.l2_store_completed_objects``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks successfully stored to L2, grouped by tenant.
+   * - ``lmcache_mp.l2_prefetch_lookup``
+     - Counter
+     - Number of L2 prefetch lookup requests.
+   * - ``lmcache_mp.l2_prefetch_lookup_objects``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks submitted for L2 prefetch lookup, grouped by
+       tenant.
+   * - ``lmcache_mp.l2_prefetch_hit``
+     - Counter
+     - Number of prefix chunks found in L2 lookup.
+   * - ``lmcache_mp.l2_prefetch_load_submitted``
+     - Counter
+     - Number of L2 prefetch load requests submitted.
+   * - ``lmcache_mp.l2_prefetch_load_submitted_objects``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks submitted for L2 load, grouped by tenant.
+   * - ``lmcache_mp.l2_prefetch_load_completed``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks successfully loaded from L2, grouped by tenant.
+   * - ``lmcache_mp.l2_load_completed``
+     - Counter (attr: ``l2_name``)
+     - Number of per-adapter L2 load requests completed, labeled by adapter type.
+   * - ``lmcache_mp.l2_evicted_objects``
+     - Counter (attr: ``cache_salt``)
+     - Number of chunks evicted from L2, grouped by tenant.
+
+The ``l2_name``-labeled counters (``l2_store_completed`` and
+``l2_load_completed``) exist so dashboards can compute per-backend IOPS on
+demand via ``rate(lmcache_mp_l2_store_completed_requests_total{l2_name="..."}[1m])``
+(and the equivalent for loads).  No separate ``*_iops`` metric is exported;
+keeping the raw counter lets dashboard users pick their own window.
+
+Failure & Health Counters
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Health-monitoring counters emitted on the dedicated ``lmcache_mp.health``
+OTel meter. Driven by the ``L1FailureMetricsSubscriber`` and
+``L2FailureMetricsSubscriber``, which are registered automatically when
+metrics are enabled. All three counters carry ``model_name`` (extracted
+from each ``ObjectKey``) so operators can slice per-model on the
+Prometheus ``/metrics`` endpoint.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 15 50
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l1_allocation_failure``
+     - Counter
+     - L1 memory allocation failures (OOM) during ``reserve_write``.
+       Tagged by ``during`` ∈ {``l1_store``, ``l2_prefetch``} to
+       distinguish user-initiated stores from prefetch-triggered
+       allocations, plus ``model_name``.
+   * - ``lmcache_mp.l1_read_failure``
+     - Counter
+     - L1 ``reserve_read`` failures. Tagged by ``during`` ∈
+       {``l2_store``, ``l1_retrieve``}, ``reason`` ∈ {``not_found``,
+       ``write_locked``}, plus ``model_name``. **Post-lookup anomaly
+       counter**, not a cache-miss counter — in MP mode ``reserve_read``
+       is only called after a successful lookup, so any non-zero value
+       indicates a lookup/reserve race or unexpected eviction and should
+       stay near zero in healthy operation.
+   * - ``lmcache_mp.l2_prefetch_failure``
+     - Counter
+     - Chunks that L2 reported present at lookup but failed to land in L1.
+       Tagged by ``reason`` ∈ {``l1_oom``, ``not_found``} plus
+       ``model_name``. ``l1_oom`` means L1 had no room to receive the
+       prefetched object; ``not_found`` means the adapter returned no
+       data despite a positive lookup (e.g. concurrent delete).
+
+A ``reason=serde_failure`` value will be added to ``l2_prefetch_failure``
+as an additive, non-breaking extension once L2 adapters distinguish
+deserialization errors from missing objects — no dashboard migration
+needed when that lands.
+
+For the full design rationale (including which event types drive each
+counter and why ``lmcache_instance_id`` is deferred), see
+``docs/design/v1/mp_observability/METRICS.md`` in the source tree.
+
+Lookup Hit-Rate Metrics
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Token-level counters whose ratio gives the fraction of tokens requested by
+a lookup that were served from either L1 or L2. L0 (GPU prefix cache) is
+intentionally excluded — it is vLLM-owned and not observable from LMCache.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.lookup_requested``
+     - Counter (attrs: ``model_name``, ``cache_salt``)
+     - Total tokens submitted for lookup (denominator of the L1+L2
+       token-level hit rate). Only chunk-aligned tokens are counted.
+   * - ``lmcache_mp.lookup_hit``
+     - Counter (attrs: ``model_name``, ``cache_salt``)
+     - Total tokens found in L1 or L2 during lookup (numerator of the
+       L1+L2 token-level hit rate). Counts the contiguous prefix hit only.
+
+Both counters are driven by the same event (``MP_LOOKUP_PREFETCH_END``),
+so they always advance together per completed lookup. Early-exit lookups
+contribute ``0`` to both, and abandoned lookups contribute to neither.
+
+The ``model_name`` and ``cache_salt`` attributes are captured at lookup
+time from ``IPCCacheServerKey`` so dashboards can compute per-model or
+per-tenant hit rate. ``cache_salt`` can be high-cardinality (one entry
+per tenant or isolation domain); drop it at scrape time with
+``metric_relabel_configs`` if storage cost matters.
+
+**PromQL for hit rate:**
+
+.. code-block:: promql
+
+    # Aggregate (all models, all salts):
+    rate(lmcache_mp_lookup_hit_tokens_total[5m])
+    / rate(lmcache_mp_lookup_requested_tokens_total[5m])
+
+    # Per-model:
+    sum(rate(lmcache_mp_lookup_hit_tokens_total[5m])) by (model_name)
+    / sum(rate(lmcache_mp_lookup_requested_tokens_total[5m])) by (model_name)
+
+L0 (GPU) Block Lifecycle Histograms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sampled (default 1%) GPU KV cache block lifecycle tracking via
+``L0LifecycleSubscriber``. Eviction is detected at reallocation time
+(when a block is assigned different tokens). Sampling uses random
+selection with a ``_skipped`` set (bounded by the finite number of
+physical GPU blocks).
+
+All L0 histograms are emitted with ``instance_id`` and ``model_name``
+OTel attributes, enabling per-instance and per-model metric slicing
+in Prometheus (e.g.
+``lmcache_mp_l0_block_lifetime_seconds{instance_id="12345",model_name="llama-7b"}``).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l0_block_lifetime``
+     - Histogram
+     - Time from allocation to eviction per sampled GPU block.
+   * - ``lmcache_mp.l0_block_idle_before_evict``
+     - Histogram
+     - Time from last access to eviction per sampled GPU block.
+   * - ``lmcache_mp.l0_block_reuse_gap``
+     - Histogram
+     - Time gaps between consecutive accesses of the same GPU block.
+
+L0 ↔ L1 Throughput Histograms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Per-request throughput of GPU↔CPU copies via
+``L0L1ThroughputSubscriber``. Every store/retrieve request contributes
+one sample to the appropriate histogram:
+``total_bytes / (end_ts - start_ts)`` in GB/s. Timestamps come from
+``MP_{STORE,RETRIEVE}_{START,END}`` events published on the GPU cupy
+stream, so they reflect true GPU-stream copy time — not Python/lock
+overhead.
+
+All throughput histograms are emitted with ``engine_id`` (vLLM worker
+instance id), ``device`` (e.g. ``"cuda:3"``), and ``model_name`` OTel
+attributes, enabling per-worker, per-device, and per-model slicing in
+Prometheus (e.g.
+``lmcache_mp_l0_l1_store_throughput_GB_per_second{engine_id="0",device="cuda:3",model_name="meta-llama/Llama-3.1-8B"}``).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l0_l1_store_throughput``
+     - Histogram
+     - GPU→CPU (L0→L1) store throughput in GB/s per request.
+   * - ``lmcache_mp.l0_l1_load_throughput``
+     - Histogram
+     - CPU→GPU (L1→L0) load throughput in GB/s per request.
+
+L1 ↔ L2 Throughput Histograms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Per-request throughput of L1↔L2 transfers via
+``L2ThroughputSubscriber``. The store path correlates
+``L2_STORE_SUBMITTED`` → ``L2_STORE_COMPLETED`` by
+``(adapter_index, task_id)``. The load path correlates the per-adapter
+``L2_LOAD_TASK_SUBMITTED`` → ``L2_LOAD_TASK_COMPLETED`` events by
+``(request_id, adapter_index)``; the request-level
+``L2_PREFETCH_LOAD_*`` events used by the chunk-count counters aggregate
+across adapters and cannot be attributed to a specific ``l2_name``.
+
+Timestamps span **submit → complete**, so the duration includes adapter
+queue, network, and disk I/O — the value is *bytes / end-to-end
+latency*, not raw transfer rate. Use these histograms to compare
+adapter types and catch regressions; use the L0↔L1 histograms when you
+need pure copy-time throughput.
+
+All L1↔L2 throughput histograms carry a single ``l2_name`` OTel
+attribute — the registered adapter type (e.g. ``"fs"``, ``"nixl_store"``,
+``"mooncake_store"``) — enabling per-backend slicing in Prometheus (e.g.
+``lmcache_mp_l2_store_throughput_GB_per_second{l2_name="nixl_store"}``).
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.l2_store_throughput``
+     - Histogram
+     - L1→L2 store throughput in GB/s per request.
+   * - ``lmcache_mp.l2_load_throughput``
+     - Histogram
+     - L2→L1 load throughput in GB/s per (request, adapter) pair.
+
+**PromQL for average throughput (GB/s), per backend:**
+
+.. code-block:: promql
+
+    # L1 -> L2 store throughput, averaged over the last minute, per l2_name:
+    sum by (l2_name) (rate(lmcache_mp_l2_store_throughput_GB_per_second_sum[1m]))
+    / sum by (l2_name) (rate(lmcache_mp_l2_store_throughput_GB_per_second_count[1m]))
+
+    # L2 -> L1 load throughput (same shape):
+    sum by (l2_name) (rate(lmcache_mp_l2_load_throughput_GB_per_second_sum[1m]))
+    / sum by (l2_name) (rate(lmcache_mp_l2_load_throughput_GB_per_second_count[1m]))
+
+.. note::
+
+   ``l2_store_throughput`` populates whenever chunks are written to L2.
+   ``l2_load_throughput`` only populates when chunks are read **from L2 into
+   L1** — i.e. on a prefetch load after the entry has aged out of L1. If your
+   working set fits entirely in L1 (common with small models or a large
+   ``--l1-size-gb``), lookups are served from L1 and the load histogram stays
+   empty even though store throughput is non-zero. Drive enough distinct data
+   to force L1 eviction, or restart the server between store and load passes,
+   to exercise the L2 load path.
+
+Engine Counters
+~~~~~~~~~~~~~~~
+
+Worker-scoped counters tied to what the MP server delivers back to each
+vLLM worker via ``retrieve()``.  Labeled by ``worker_id`` (the vLLM
+worker instance id) — distinct from any scheduler-scoped id that may
+appear on other metrics.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 25 35
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.num_chunks_loaded``
+     - Counter (attrs: ``worker_id``, ``model_name``, ``cache_salt``)
+     - Total number of LMCache chunks loaded into the engine, summed
+       over all ``retrieve()`` completions.  Sliceable per worker, per
+       model, and per tenant / isolation domain (``cache_salt``).
+       ``cache_salt`` may be high-cardinality; drop it at scrape time
+       with ``metric_relabel_configs`` if storage cost matters.
+
+Observable Gauges
+~~~~~~~~~~~~~~~~~
+
+Point-in-time state snapshots registered via ``register_gauge``
+(pull-based OTel observable gauges).
+
+The three in-flight metrics carry two attributes that distinguish
+adapters even when more than one is registered with the same backend
+type — same shape as ``lmcache_mp.l2_store_completed``:
+
+- ``l2_name`` — the registered adapter type (e.g. ``"fs"``,
+  ``"nixl_store"``, ``"mooncake_store"``).
+- ``adapter_index`` — position in the controller's adapter list.
+
+Adapters with no in-flight work emit no datapoint for that scrape.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.active_prefetch_jobs``
+     - ObservableGauge
+     - Number of prefetch jobs currently in-flight. A sustained high
+       value may indicate slow L2 backends or polling delays.
+   * - ``lmcache_mp.l1_memory_usage_bytes``
+     - ObservableGauge
+     - Bytes currently held in L1.  Rising without plateauing typically
+       indicates a leak; saturating at the configured ``--l1-size-gb``
+       indicates working set exceeds capacity.
+   * - ``lmcache_mp.l1_usage_ratio``
+     - ObservableGauge
+     - L1 used/total ratio (``0.0``–``1.0``), sampled at scrape time
+       from ``L1Manager.get_memory_usage()``. Returns ``0.0`` when the
+       gauge target is not yet wired up or ``total_bytes`` is zero, so
+       the callback never raises during a scrape. Compare against the
+       eviction watermark (default ``0.8``) to read whether the
+       eviction loop is below or above its trigger threshold.
+   * - ``lmcache_mp.l2_usage_bytes``
+     - ObservableGauge (attr: ``l2_name``)
+     - Bytes currently held in each L2 adapter, sampled at scrape time
+       from ``adapter.get_usage()``.  One observation per configured
+       adapter, tagged by ``l2_name`` (the adapter type, e.g. ``"fs"``,
+       ``"nixl_store"``, ``"mooncake_store"``).  Parallel to
+       ``l1_memory_usage_bytes`` for the L2 tier — use it to see how
+       much each L2 backend currently holds.  Adapters whose
+       ``get_usage()`` raises are skipped silently rather than poisoning
+       the observation, so a missing datapoint for one ``l2_name`` can
+       mean either "not configured" or "adapter errored on this
+       scrape" — cross-check with the L2 store/load counters.
+   * - ``lmcache_mp.num_inflight_l2_stores``
+     - ObservableGauge (attrs: ``l2_name``, ``adapter_index``)
+     - L2 store tasks currently executing, per adapter.  Sustained
+       non-zero values indicate the adapter cannot keep up with the
+       L1 → L2 write rate.
+   * - ``lmcache_mp.num_inflight_l2_loads``
+     - ObservableGauge (attrs: ``l2_name``, ``adapter_index``)
+     - L2 → L1 prefetch load tasks currently executing, per adapter.
+       Pair with ``num_inflight_l2_stores`` to see whether read or write
+       traffic dominates a given backend.
+   * - ``lmcache_mp.inflight_load_memory_usage_bytes``
+     - ObservableGauge (attrs: ``l2_name``, ``adapter_index``)
+     - L1 bytes reserved by in-flight L2 → L1 prefetch loads, per
+       adapter.  Rising in-flight bytes alongside rising
+       ``l1_memory_usage_bytes`` is a signal that prefetch reservations
+       are crowding out cacheable data.  Per-adapter byte attribution
+       follows each request's ``load_plan`` bitmap, so summing across
+       adapters never double-counts.
+
+EventBus Self-Monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Health metrics for the EventBus itself, registered by
+``EventBusSelfMetricsSubscriber`` on the ``lmcache.event_bus`` OTel
+meter.  These metrics observe bus state directly via the ``EventBus``
+accessors and report on every OTel scrape — they are not driven by
+events, so dropping or failing subscribers cannot silence them.
+
+Use them to answer: is the EventBus keeping up with publishers, is
+anything being dropped, and are any subscriber callbacks raising?
+A non-zero ``dropped_events_total`` or a sustained non-zero
+``drain_lag_seconds`` indicates the bus is at ``--event-bus-queue-size``
+and tail-dropping; raise that flag or investigate slow subscribers.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric
+     - Type
+     - Description
+   * - ``lmcache_mp.event_bus.queue_depth``
+     - ObservableGauge
+     - Events currently queued in the EventBus (``len(_queue)`` at
+       scrape time).
+   * - ``lmcache_mp.event_bus.drain_lag_seconds``
+     - ObservableGauge
+     - Seconds since the oldest queued event was published; ``0.0``
+       when empty.  Rising values mean the drain thread is falling
+       behind.
+   * - ``lmcache_mp.event_bus.dropped_events_total``
+     - ObservableCounter
+     - Cumulative events dropped because the EventBus queue was at
+       ``--event-bus-queue-size``.
+   * - ``lmcache_mp.event_bus.subscriber_exceptions``
+     - ObservableCounter (attr: ``subscriber_name``)
+     - Cumulative exceptions raised by subscriber callbacks during
+       EventBus dispatch, tagged by ``subscriber_name`` (the failing
+       callback's owning class for bound methods, or ``__qualname__``
+       for free functions).
+
+For the full design rationale and the in-process accessors that back
+each metric see ``docs/design/v1/mp_observability/METRICS.md`` and
+``docs/design/v1/mp_observability/event-bus.md`` in the source tree.
+
+Prometheus Scrape Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In **pull mode** (no ``--otlp-endpoint``), point Prometheus at the server's
+HTTP-frontend port — ``--http-port``, default **8080** — not at
+``--prometheus-port``:
+
+.. code-block:: yaml
+
+    scrape_configs:
+      - job_name: "lmcache-mp"
+        static_configs:
+          - targets: ["<lmcache-host>:8080"]   # --http-port, NOT --prometheus-port
+
+In **push mode** (``--otlp-endpoint`` set), the server does not expose
+``/metrics`` itself; scrape the OpenTelemetry Collector's Prometheus exporter
+instead. The bundled stack in ``examples/observability/`` wires this up for
+you — see :doc:`index`.
+
diff --git a/docs/source/mp/observability/traces.rst b/docs/source/mp/observability/traces.rst
new file mode 100644
index 0000000..a0ee414
--- /dev/null
+++ b/docs/source/mp/observability/traces.rst
@@ -0,0 +1,192 @@
+Tracing
+=======
+
+.. note::
+
+   ``--enable-tracing`` **requires** ``--otlp-endpoint`` to be set.
+   The server will refuse to start if tracing is enabled without an
+   OTLP endpoint, since there is no local fallback for trace export.
+
+When tracing is enabled (``--enable-tracing --otlp-endpoint <URL>``),
+the tracing subscriber creates OTel spans from START/END event pairs:
+
+- ``mp.store`` — from ``MP_STORE_START`` to ``MP_STORE_END``
+- ``mp.retrieve`` — from ``MP_RETRIEVE_START`` to ``MP_RETRIEVE_END``
+- ``mp.lookup_prefetch`` — from ``MP_LOOKUP_PREFETCH_START`` to ``MP_LOOKUP_PREFETCH_END``
+
+Each span carries event metadata as span attributes (e.g. ``device``,
+``stored_count``, ``found_count``).
+
+View traces in any OTel-compatible backend such as **Jaeger** or
+**Grafana Tempo**.
+
+.. code-block:: bash
+
+    # Start Jaeger all-in-one (OTLP gRPC on 4317)
+    docker run -d --name jaeger \
+        -p 16686:16686 -p 4317:4317 \
+        jaegertracing/all-in-one:latest
+
+    # Start LMCache with tracing
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --enable-tracing --otlp-endpoint http://localhost:4317
+
+Per-Request Hit-Rate Attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each session is wrapped in a per-request root span — ``request`` for the
+standard MP path and ``cb.request`` for the CacheBlend path — that nests
+all child spans (``mp.store``, ``mp.retrieve``, ``mp.lookup_prefetch``)
+beneath it.  When the lookup phase ends, the root span is annotated with
+three OTel attributes that summarise the request-level cache hit rate:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 15 60
+
+   * - Attribute
+     - OTel type
+     - Description
+   * - ``hit_tokens``
+     - ``int``
+     - Tokens served from L1+L2 (numerator).
+   * - ``requested_tokens``
+     - ``int``
+     - Chunk-aligned tokens submitted for lookup (denominator).
+   * - ``hit_rate``
+     - ``float``
+     - ``hit_tokens / requested_tokens``; ``0.0`` when the denominator is
+       zero.  Stored as a precomputed float because trace UIs (Tempo,
+       Jaeger) cannot derive it from two integer attributes at query time.
+
+The attributes are written when ``MP_LOOKUP_PREFETCH_END`` (standard MP
+path) or ``CB_LOOKUP_END`` (CacheBlend path) is processed — while the
+root span is still open.  **Store-only requests** that never call
+``lookup_prefetch_start()`` emit no end event for the lookup phase, so
+their root span will not carry these attributes.
+
+Example TraceQL queries (Grafana Tempo):
+
+.. code-block:: text
+
+    # Requests with less than 50% cache hit rate
+    { name = "request" && span.hit_rate < 0.5 }
+
+    # Full cache hits only
+    { name = "request" && span.hit_rate = 1.0 }
+
+    # Complete misses (lookup ran but nothing was cached)
+    { name = "request" && span.requested_tokens > 0 && span.hit_tokens = 0 }
+
+For the full event-to-span mapping and the registry pattern that links
+child spans back to the root see
+``docs/design/observability/request-event-span.md`` in the source tree.
+
+.. _trace-recording:
+
+Trace Recording
+~~~~~~~~~~~~~~~
+
+.. note::
+
+   Trace recording is **distinct from** ``--enable-tracing`` (OTel
+   spans). Trace recording captures every ``StorageManager`` public-API
+   call to a binary file so the same workload can be **replayed** later
+   for testing, regression hunting, and benchmarking — without needing
+   vLLM and (eventually) without a GPU. ``--enable-tracing`` exports
+   live OTel spans to an OTLP endpoint for online observability.
+   The two features are independent and can be used together.
+
+When ``--trace-level storage`` is set, LMCache records every call to
+``StorageManager.{reserve_write, finish_write, submit_prefetch_task,
+read_prefetched_results, finish_read_prefetched}`` to a binary file
+for later replay.
+
+Recording is **off by default** and adds near-zero overhead when off
+(a single boolean check per ``StorageManager`` call). When on,
+recording happens on the EventBus drain thread, off the request path.
+
+Capturing a trace
+^^^^^^^^^^^^^^^^^
+
+With an explicit output path:
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --trace-level storage --trace-output /tmp/run.lct
+
+With an implicit timestamped output path under ``$TMPDIR``:
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --trace-level storage
+    # → INFO log: "trace recording enabled (level=storage); no
+    #   --trace-output given, writing to
+    #   /tmp/lmcache-trace-<pid>-<UTC>.lct"
+
+The trace file is closed cleanly on shutdown (SIGTERM is handled by
+the EventBus stop path).
+
+Replay
+^^^^^^
+
+Replaying a recorded trace, plus the full set of CLI flags for
+driving, monitoring, and exporting replay results, is covered in
+its own page: :doc:`/mp/tracing_and_debugging`.
+
+What is captured (and what is not)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Captured:**
+
+- The fully-qualified name of every decorated ``StorageManager`` call.
+- Each call's input arguments (e.g. ``keys``, ``layout_desc``,
+  ``mode``, ``extra_count``, ``external_request_id``).
+- Wall-clock and monotonic timestamps of each call.
+- A header carrying a trace schema version, start times, and a
+  SHA-256 digest of the active ``StorageManagerConfig`` so replay can
+  detect mismatched configurations.
+
+**Not captured:**
+
+- KV tensor bytes. Replay exercises bookkeeping and controller logic;
+  payloads at replay time are zeros.
+- Calls inside the ``MPCacheServer``, the message queue, or any
+  GPU-copy code. These layers are **out of scope** for the storage
+  trace level.
+
+File format
+^^^^^^^^^^^
+
+A length-prefixed `msgpack <https://msgpack.org/>`_ stream:
+
+::
+
+    [4-byte big-endian length][msgpack Header]
+    [4-byte big-endian length][msgpack Record]
+    [4-byte big-endian length][msgpack Record]
+    ...
+
+The ``Header`` carries a magic prefix (``LMCT``), a format version,
+the trace level (``storage`` today), a trace schema version, start
+timestamps, and the StorageManagerConfig digest. Each ``Record``
+carries a relative timestamp, a wall-clock timestamp, the
+fully-qualified call site (``qualname``), and an argument dict.
+
+The format is deliberately extensible: future trace **levels**
+(``mq``, ``gpu``) will share this layout and use the ``level`` header
+field to discriminate. Additional captured ops add new ``qualname``
+strings without bumping the format version.
+
+For the full design rationale see
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   /mp/tracing_and_debugging
diff --git a/docs/source/mp/operator.rst b/docs/source/mp/operator.rst
new file mode 100644
index 0000000..568fce5
--- /dev/null
+++ b/docs/source/mp/operator.rst
@@ -0,0 +1,1336 @@
+Kubernetes Operator
+===================
+
+The LMCache Kubernetes operator automates the deployment and lifecycle
+management of LMCache multiprocess servers.  Instead of hand-writing
+DaemonSets, Services, and ConfigMaps (as described in the manual
+:doc:`deployment` guide), you declare a single ``LMCacheEngine`` custom
+resource and the operator reconciles all underlying Kubernetes objects.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Why Use the Operator
+--------------------
+
+The manual DaemonSet approach works, but it has sharp edges the operator
+eliminates:
+
+- **Auto-injected pod settings** -- The operator always sets ``hostIPC: true``
+  and ``--host 0.0.0.0``.  Forgetting ``hostIPC`` in a hand-written manifest
+  causes silent CUDA IPC failures (``cudaErrorMapBufferObjectFailed``) that are
+  hard to debug.
+- **Node-local service discovery** -- The operator creates a ClusterIP Service
+  with ``internalTrafficPolicy=Local`` and a connection ConfigMap that vLLM
+  pods simply mount.  No ``hostNetwork``, no Downward API, no shell variable
+  substitution.
+- **Auto-computed resource sizing** -- Memory requests and limits are derived
+  from ``l1.sizeGB``, avoiding OOM kills (under-provisioned) or wasted node
+  capacity (over-provisioned).
+- **Declarative Prometheus integration** -- Set
+  ``prometheus.serviceMonitor.enabled: true`` and the operator creates a
+  ``ServiceMonitor`` CR that the Prometheus Operator discovers automatically.
+- **CRD validation** -- OpenAPI schema validation catches misconfigurations
+  (e.g., ``l1.sizeGB <= 0``, invalid port range) at ``kubectl apply`` time,
+  before any pods are created.
+
+Prerequisites
+-------------
+
+- Kubernetes 1.20+
+- ``kubectl`` configured to access your cluster
+- (Optional) `Prometheus Operator <https://github.com/prometheus-operator/prometheus-operator>`_
+  for ServiceMonitor support
+
+Installing the Operator
+-----------------------
+
+**Option A: One-line install from release (recommended)**
+
+.. code-block:: bash
+
+    # Latest stable release
+    kubectl apply -f https://github.com/LMCache/LMCache/releases/download/operator-latest/install.yaml
+
+    # Or nightly build from the dev branch
+    kubectl apply -f https://github.com/LMCache/LMCache/releases/download/operator-nightly-latest/install.yaml
+
+**Option B: Build from source**
+
+.. code-block:: bash
+
+    cd operator
+    make build
+    make install
+    make deploy IMG=<your-registry>/lmcache-operator:latest
+
+Deploying an LMCacheEngine
+---------------------------
+
+A minimal CR deploys a DaemonSet with 60 GB L1 cache on every GPU node:
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheEngine
+    metadata:
+      name: my-cache
+    spec:
+      l1:
+        sizeGB: 60
+
+.. code-block:: bash
+
+    kubectl apply -f lmcache-engine.yaml
+
+The operator automatically:
+
+- Creates a DaemonSet running one LMCache server pod per matched node
+- Sets ``hostIPC: true`` and passes ``--host 0.0.0.0`` to the server
+- Creates a node-local ClusterIP Service for vLLM discovery
+- Creates a connection ConfigMap (``my-cache-connection``) with the
+  ``kv-transfer-config`` JSON that vLLM needs
+- Auto-computes resource requests/limits from the L1 cache size
+- Defaults ``nodeSelector`` to ``nvidia.com/gpu.present: "true"``
+
+.. note::
+   The operator defaults the container image to ``lmcache/vllm-openai:latest``.
+   Override with ``spec.image.repository`` and ``spec.image.tag`` to pin a
+   specific version.
+
+Connecting vLLM
+---------------
+
+The operator creates a ConfigMap named ``<engine-name>-connection`` containing
+the ``kv-transfer-config`` JSON.  You can either let the operator's mutating
+webhook inject it for you (recommended -- keeps your vLLM manifest clean) or
+mount it by hand.  See :ref:`mp-operator-connection-injection` below for the
+webhook flow; the rest of this section describes the manual mount that is its
+equivalent.
+
+Mount it in your vLLM Deployment:
+
+.. code-block:: yaml
+
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+      name: vllm
+    spec:
+      replicas: 1
+      selector:
+        matchLabels:
+          app: vllm
+      template:
+        metadata:
+          labels:
+            app: vllm
+        spec:
+          # Required for CUDA IPC between vLLM and LMCache
+          hostIPC: true
+          containers:
+            - name: vllm
+              image: lmcache/vllm-openai:latest
+              env:
+                # Deterministic hashing required by LMCache
+                - name: PYTHONHASHSEED
+                  value: "0"
+              command: ["/bin/sh", "-c"]
+              args:
+                - |
+                  exec python3 -m vllm.entrypoints.openai.api_server \
+                    --model <your-model> \
+                    --port 8000 \
+                    --gpu-memory-utilization 0.8 \
+                    --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"
+              ports:
+                - name: http
+                  containerPort: 8000
+              volumeMounts:
+                - name: kv-transfer-config
+                  mountPath: /etc/lmcache
+                  readOnly: true
+              resources:
+                limits:
+                  nvidia.com/gpu: "1"
+          volumes:
+            - name: kv-transfer-config
+              configMap:
+                name: my-cache-connection  # <engine-name>-connection
+
+Key requirements for vLLM pods:
+
+- **hostIPC: true** -- CUDA IPC (``cudaIpcOpenMemHandle``) needs a shared IPC
+  namespace between vLLM and LMCache.
+- **PYTHONHASHSEED=0** -- Ensures deterministic token hashing so vLLM and
+  LMCache produce consistent cache keys.
+- **ConfigMap mount** -- The ``$(cat ...)`` pattern reads the connection JSON
+  inline.  The ConfigMap name is always ``<LMCacheEngine name>-connection``.
+- **No hostNetwork needed** -- The operator's node-local Service handles
+  routing via ``internalTrafficPolicy=Local``.
+
+.. _mp-operator-connection-injection:
+
+Connection Injection (Webhook)
+-------------------------------
+
+Hand-wiring the ConfigMap mount and the ``$(cat ...)`` argument substitution
+above is repetitive across vLLM Deployments.  A **mutating admission webhook**
+shipped with the operator can do it for you so the vLLM manifest stays clean.
+It mirrors the CacheBlend webhook (see :ref:`mp-operator-cacheblend`) with an
+``lmcache-`` annotation/label discriminator so the two injectors never
+cross-fire on the same pod.
+
+When invoked on an opted-in pod whose ``<engine>-connection`` ConfigMap exists,
+the webhook mutates the pod at admission time to add:
+
+- ``--kv-transfer-config <JSON>`` -- the ``LMCacheMPConnector`` config, read
+  verbatim from the engine's ``<engine>-connection`` ConfigMap and inlined onto
+  the vLLM container's ``args`` (no volume mount needed);
+- ``hostIPC: true`` on the pod spec (CUDA IPC with the node-local server);
+- ``PYTHONHASHSEED=0`` on the vLLM container env, **set-if-absent** -- it
+  preserves a value you already set.
+
+Unlike the CacheBlend injector it does **not** consult the engine CR: the
+entire connector config lives in the connection ConfigMap, and
+``LMCacheEngine`` has no injection sub-spec.  It fails open
+(``failurePolicy: Ignore``) and is idempotent (re-admitted pods carrying the
+``lmcache.ai/lmcache-injected`` stamp are allowed unchanged).
+
+Prerequisites
+~~~~~~~~~~~~~
+
+- **cert-manager** + ``make deploy`` (not ``make run``, which is
+  controller-only and disables the webhook via ``ENABLE_WEBHOOKS=false``) --
+  same as the CacheBlend webhook; install once per cluster (see
+  :ref:`mp-operator-cacheblend` "Additional Prerequisites").
+- **Pod Security Standards** -- the injected ``hostIPC`` is rejected by the
+  ``baseline`` / ``restricted`` PSS profiles, so the vLLM pod's namespace must
+  be labeled ``pod-security.kubernetes.io/enforce=privileged``.
+- **Engine reconciled in the same namespace** -- the webhook reads the
+  ``<engine>-connection`` ConfigMap directly, so the ``LMCacheEngine`` must
+  already exist in the vLLM pod's namespace.
+
+Opting a vLLM Pod In
+~~~~~~~~~~~~~~~~~~~~
+
+Add the opt-in label and the engine-binding annotation to the pod template, and
+launch vLLM via the image **ENTRYPOINT** (args only) -- a
+``command: ["/bin/sh", "-c", ...]`` wrapper is skipped (the webhook stamps
+``lmcache.ai/lmcache-skip-reason=command-override`` because appended args would
+not reach ``vllm serve``):
+
+.. code-block:: yaml
+
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+      name: vllm-lmcache
+    spec:
+      replicas: 1
+      selector:
+        matchLabels:
+          app: vllm-lmcache
+      template:
+        metadata:
+          labels:
+            app: vllm-lmcache
+            lmcache.ai/lmcache-inject: "true"        # opt-in (webhook objectSelector)
+          annotations:
+            lmcache.ai/lmcache-engine: "my-cache"    # bind to the engine (same namespace)
+            # Optional -- name the vLLM container if it is not the first one:
+            # lmcache.ai/lmcache-container: "vllm"
+        spec:
+          runtimeClassName: nvidia
+          # Do NOT set hostIPC here or mount an emptyDir at /dev/shm -- the
+          # webhook injects hostIPC=true; an emptyDir would shadow the host's
+          # /dev/shm and break cudaIpcOpenMemHandle.
+          containers:
+            - name: vllm
+              image: lmcache/vllm-openai:latest
+              # Args-only launch (image ENTRYPOINT is ["vllm", "serve"]). The
+              # webhook appends --kv-transfer-config; do NOT add it yourself
+              # (a user-supplied one stamps skip-reason=kv-transfer-config-present).
+              args: ["<your-model>", "--port", "8000", "--gpu-memory-utilization", "0.8"]
+              ports:
+                - name: http
+                  containerPort: 8000
+              resources:
+                limits:
+                  nvidia.com/gpu: "1"
+
+A ready-to-edit manifest lives at
+``operator/config/samples/vllm_lmcache_deployment.yaml``.
+
+Verifying Injection
+~~~~~~~~~~~~~~~~~~~
+
+The webhook mutates **Pods**, not the Deployment, so inspect a pod (not the
+Deployment spec):
+
+.. code-block:: bash
+
+    kubectl get pod -l app=vllm-lmcache -o yaml | \
+      grep -E "hostIPC|kv-transfer-config|lmcache-injected|lmcache-skip-reason"
+
+If nothing was injected, check the pod's ``lmcache.ai/lmcache-skip-reason``
+annotation:
+
+- ``command-override`` -- the pod uses a ``sh -c`` wrapper, so injected args
+  would not reach ``vllm serve``.
+- ``kv-transfer-config-present`` -- the user already supplied
+  ``--kv-transfer-config``; the webhook does not clobber it.
+- ``engine-not-found`` -- the ``<engine>-connection`` ConfigMap is missing
+  (engine not yet reconciled, or wrong namespace, or wrong name).
+- ``target-container-not-found`` -- the
+  ``lmcache.ai/lmcache-container`` annotation names a container the pod does
+  not have.
+
+With ``failurePolicy: Ignore`` a webhook / cert problem also leaves the pod
+un-mutated silently -- confirm the operator pod is ``Running`` and the
+``MutatingWebhookConfiguration`` exists.
+
+Using the Latest (or a Pinned) lmcache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default a vLLM pod runs whatever ``lmcache`` is baked into its image.  To run
+a **different** lmcache build instead -- e.g. ship the latest lmcache onto an
+older, stable vLLM image, or keep the vLLM client on the exact build its
+``LMCacheEngine`` server runs -- set ``spec.injection.payloadImage`` on the
+engine.  The webhook then additionally stages that image's ``lmcache`` tree into
+each opted-in pod: an ``emptyDir`` + an init container that copies the tree in, a
+read-only mount, and ``PYTHONPATH=/lmcache-payload`` so vLLM imports the staged
+``lmcache`` instead of the baked-in one.  No vLLM image rebuild.
+
+**1. Build the payload image.** It ships the unpacked ``lmcache`` tree under
+``/payload`` and copies it to ``$SHARED_DIR`` on start.  ``docker/Dockerfile.payload``
+builds it by extracting an ABI-matched ``lmcache`` from an lmcache image (the
+``SOURCE_IMAGE`` build-arg selects the version):
+
+.. code-block:: bash
+
+    docker build -f docker/Dockerfile.payload \
+      --build-arg SOURCE_IMAGE=lmcache/vllm-openai:latest-nightly \
+      -t <registry>/lmcache-payload:latest .
+    docker push <registry>/lmcache-payload:latest
+
+**2. Point the engine at it.** ``payloadImage.repository`` has no valid default
+(the inherited image default is not a payload), so set it explicitly; leaving
+``injection`` unset keeps connection-only wiring.
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheEngine
+    metadata:
+      name: my-cache-versioned
+    spec:
+      l1:
+        sizeGB: 60
+      injection:
+        payloadImage:
+          repository: <registry>/lmcache-payload
+          tag: latest
+          pullPolicy: Always          # :latest moves -- re-pull for the current build
+        # imagePullSecrets:            # private payload registry only
+        #   - name: my-registry-secret
+
+Opted-in pods bound to this engine (label + annotation as above) need no
+changes -- the webhook stages the payload automatically.  Ready-to-apply
+samples: ``config/samples/lmcache_v1alpha1_lmcacheengine_injection.yaml`` and
+``config/samples/vllm_lmcache_injection_deployment.yaml``.
+
+.. note::
+   The payload's ``lmcache`` must be **ABI-compatible** (same Python minor
+   version and a compatible torch) with the vLLM image that imports it -- it
+   ships compiled extensions.  If they differ, ``import lmcache`` fails with an
+   ``undefined symbol`` error in the vLLM pod.  Building the payload from an
+   lmcache image close to your vLLM image keeps them compatible.
+
+**3. Verify the swap** on a running pod -- contrast the normal import with one
+that ignores the injected ``PYTHONPATH``:
+
+.. code-block:: bash
+
+    POD=$(kubectl get pod -l app=vllm-lmcache-versioned -o name | head -1)
+
+    # imports the STAGED build (from /lmcache-payload):
+    kubectl exec $POD -c vllm -- python3 -c \
+      "import lmcache; print(lmcache.__version__, lmcache.__file__)"
+
+    # PYTHONPATH stripped -> the image's baked-in build (site-packages):
+    kubectl exec $POD -c vllm -- env -u PYTHONPATH python3 -c \
+      "import lmcache; print(lmcache.__version__, lmcache.__file__)"
+
+Two different sources for the same module confirms the swap.  If nothing was
+staged, check ``lmcache.ai/lmcache-skip-reason`` on the pod.
+
+Verifying the Deployment
+------------------------
+
+.. code-block:: bash
+
+    # Check LMCacheEngine status
+    kubectl get lmc
+
+Expected output:
+
+.. code-block:: text
+
+    NAME       PHASE     READY   DESIRED   AGE
+    my-cache   Running   3       3         5m
+
+.. code-block:: bash
+
+    # Check the connection ConfigMap
+    kubectl get configmap my-cache-connection -o yaml
+
+    # Check LMCache pods
+    kubectl get pods -l app.kubernetes.io/managed-by=lmcache-operator
+
+    # Check detailed status with endpoints
+    kubectl describe lmc my-cache
+
+CRD Spec Reference
+-------------------
+
+Image
+~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``image.repository``
+     - ``lmcache/vllm-openai``
+     - Container image repository.
+   * - ``image.tag``
+     - ``latest``
+     - Container image tag.
+   * - ``image.pullPolicy``
+     - ``IfNotPresent``
+     - ``Always``, ``Never``, or ``IfNotPresent``.
+   * - ``imagePullSecrets``
+     - --
+     - Image pull secret references.
+
+Server
+~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``server.port``
+     - ``5555``
+     - ZMQ listening port (1024--65535).
+   * - ``server.chunkSize``
+     - ``256``
+     - Token chunk size.
+   * - ``server.maxWorkers``
+     - ``1``
+     - Worker threads for ZMQ requests.
+   * - ``server.hashAlgorithm``
+     - ``blake3``
+     - ``builtin``, ``sha256_cbor``, or ``blake3``.
+   * - ``server.httpPort``
+     - ``8080``
+     - HTTP frontend port for health checks and cache admin (1024--65535).
+
+L1 Cache
+~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``l1.sizeGB``
+     - *required*
+     - L1 cache size in GB.  Must be > 0.
+
+Eviction
+~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``eviction.policy``
+     - ``LRU``
+     - ``LRU`` or ``noop``.  Use ``noop`` with ``l2Backend.storePolicy: skip_l1``
+       for buffer-only mode.
+   * - ``eviction.triggerWatermark``
+     - ``0.8``
+     - Usage ratio (0.0--1.0] to trigger eviction.
+   * - ``eviction.evictionRatio``
+     - ``0.2``
+     - Fraction to evict (0.0--1.0].
+
+Prometheus
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``prometheus.enabled``
+     - ``true``
+     - Expose Prometheus metrics.
+   * - ``prometheus.port``
+     - ``9090``
+     - ``/metrics`` endpoint port.
+   * - ``prometheus.serviceMonitor.enabled``
+     - ``false``
+     - Create a ServiceMonitor CR.
+   * - ``prometheus.serviceMonitor.interval``
+     - ``30s``
+     - Scrape interval.
+   * - ``prometheus.serviceMonitor.labels``
+     - --
+     - Extra labels on the ServiceMonitor.
+
+L2 Storage
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``l2Backend``
+     - --
+     - List of L2 backends (``type`` + ``config``).
+       See :doc:`l2_storage/index`.
+
+GPU & Security
+~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``gpuVendor``
+     - ``nvidia``
+     - GPU vendor: ``nvidia`` (uses the ``nvidia`` RuntimeClass) or ``amd``
+       (runs on the default runtime).
+   * - ``privileged``
+     - ``false``
+     - Run the engine container in privileged mode. On most clusters
+       ``runtimeClassName: nvidia`` + ``NVIDIA_VISIBLE_DEVICES=all`` already
+       grant GPU visibility without it; set ``true`` only where the engine
+       cannot otherwise see the GPUs. Required for ``gpuVendor: amd`` (no
+       RuntimeClass device injection, so privileged is the only path to
+       ``/dev/kfd``/``/dev/dri``). Enabling it requires the namespace to allow
+       the ``privileged`` Pod Security Standard.
+
+Scheduling
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``nodeSelector``
+     - GPU nodes
+     - Defaults to ``nvidia.com/gpu.present: "true"``.
+   * - ``affinity``
+     - --
+     - Pod affinity rules.
+   * - ``tolerations``
+     - --
+     - Pod tolerations.
+   * - ``priorityClassName``
+     - --
+     - Priority class for pods.
+
+Overrides & Extras
+~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``logLevel``
+     - ``INFO``
+     - ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``.
+   * - ``resourceOverrides``
+     - --
+     - Override auto-computed resources.
+   * - ``env``
+     - --
+     - Extra environment variables.
+   * - ``volumes``
+     - --
+     - Extra volumes.
+   * - ``volumeMounts``
+     - --
+     - Extra volume mounts.
+   * - ``podAnnotations``
+     - --
+     - Extra pod annotations.
+   * - ``podLabels``
+     - --
+     - Extra pod labels.
+   * - ``serviceAccountName``
+     - --
+     - ServiceAccount for pods.
+   * - ``extraArgs``
+     - --
+     - Extra CLI flags (appended last, can override).
+
+Auto-Computed Resources
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``spec.resourceOverrides`` is not set, the operator derives resources from
+``l1.sizeGB``:
+
+- **CPU request**: ``4`` cores
+- **Memory request**: ``ceil(l1.sizeGB + 5)`` Gi
+- **Memory limit**: ``ceil(memoryRequest * 1.5)`` Gi
+
+For example, ``l1.sizeGB: 60`` produces a 65 Gi request and 98 Gi limit.
+
+Auto-Injected Pod Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The operator always injects these into the pod spec (they are not configurable
+via the CRD):
+
+- **hostIPC: true** -- Required for CUDA IPC between LMCache and vLLM.
+- **--host 0.0.0.0** -- Binds the server to all interfaces so the node-local
+  Service can route to it.
+- **NVIDIA_VISIBLE_DEVICES=all** -- Ensures GPU access for IPC-based memory
+  transfers.
+- **NVIDIA_DRIVER_CAPABILITIES=all** -- Exposes all driver capabilities
+  (compute, utility, etc.) to the container.
+- **TCP socket probes** -- Startup (5s initial, 30 failures), liveness (10s),
+  and readiness (5s) probes on the server port.
+
+.. note::
+   The operator does **not** mount an emptyDir at ``/dev/shm``.  With
+   ``hostIPC: true``, the container sees the host's ``/dev/shm`` directly.
+   Mounting an emptyDir would shadow it with a private tmpfs and break CUDA IPC.
+
+Resources Created
+~~~~~~~~~~~~~~~~~
+
+For an ``LMCacheEngine`` named ``my-cache``:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 25 50
+
+   * - Resource
+     - Name
+     - Purpose
+   * - DaemonSet
+     - ``my-cache``
+     - Runs LMCache server pods.
+   * - Service (ClusterIP)
+     - ``my-cache``
+     - Node-local discovery (``internalTrafficPolicy=Local``).
+   * - Service (headless)
+     - ``my-cache-metrics``
+     - Prometheus scrape target.
+   * - ConfigMap
+     - ``my-cache-connection``
+     - ``kv-transfer-config`` JSON for vLLM.
+   * - ServiceMonitor
+     - ``my-cache``
+     - Prometheus Operator integration (when enabled).
+
+The connection ConfigMap contains:
+
+.. code-block:: json
+
+    {
+      "kv_connector": "LMCacheMPConnector",
+      "kv_role": "kv_both",
+      "kv_connector_extra_config": {
+        "lmcache.mp.host": "tcp://my-cache.default.svc.cluster.local",
+        "lmcache.mp.port": "5555"
+      }
+    }
+
+Status & Conditions
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    kubectl describe lmc my-cache
+
+The status section includes:
+
+- **phase**: ``Pending``, ``Running``, ``Degraded``, or ``Failed``.
+- **readyInstances** / **desiredInstances**: Instance counts.
+- **endpoints**: Per-node connection info (node name, host IP, pod name, port,
+  readiness).
+- **conditions**:
+
+  - ``Available`` -- At least one instance is ready.
+  - ``AllInstancesReady`` -- All desired instances are ready.
+  - ``ConfigValid`` -- Spec validation passed.
+
+Validation Rules
+~~~~~~~~~~~~~~~~
+
+The operator validates the CR spec at apply time:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Field
+     - Rule
+   * - ``l1.sizeGB``
+     - Required, must be > 0.
+   * - ``eviction.policy``
+     - Must be ``LRU`` or ``noop`` (if set).
+   * - ``eviction.triggerWatermark``
+     - Must be in (0.0, 1.0].
+   * - ``eviction.evictionRatio``
+     - Must be in (0.0, 1.0].
+   * - ``server.port``
+     - Must be in [1024, 65535].
+
+Examples
+--------
+
+Target Only GPU Nodes
+~~~~~~~~~~~~~~~~~~~~~
+
+Use ``nodeSelector`` to run LMCache only on GPU nodes.  New GPU nodes
+automatically get an LMCache pod:
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheEngine
+    metadata:
+      name: my-cache
+    spec:
+      nodeSelector:
+        nvidia.com/gpu.present: "true"
+      l1:
+        sizeGB: 60
+
+.. note::
+   The operator defaults ``nodeSelector`` to ``nvidia.com/gpu.present: "true"``
+   when not specified, so a minimal CR already targets GPU nodes.
+
+Custom Server Port
+~~~~~~~~~~~~~~~~~~
+
+If the default port (5555) conflicts with other services:
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheEngine
+    metadata:
+      name: my-cache
+    spec:
+      server:
+        port: 6555
+      l1:
+        sizeGB: 60
+
+The connection ConfigMap updates automatically -- vLLM pods pick up the new
+port on restart.
+
+Production with Prometheus Monitoring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheEngine
+    metadata:
+      name: production-cache
+      namespace: llm-serving
+    spec:
+      nodeSelector:
+        nvidia.com/gpu.present: "true"
+      image:
+        repository: lmcache/standalone
+        tag: v0.1.0
+      server:
+        port: 6555
+        chunkSize: 256
+        maxWorkers: 4
+      l1:
+        sizeGB: 60
+      eviction:
+        triggerWatermark: 0.8
+        evictionRatio: 0.2
+      prometheus:
+        enabled: true
+        port: 9090
+        serviceMonitor:
+          enabled: true
+          labels:
+            release: kube-prometheus-stack
+      podAnnotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: "9090"
+      priorityClassName: system-node-critical
+
+See :doc:`observability/index` for metric names and Grafana configuration.
+
+Override Auto-Computed Resources
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheEngine
+    metadata:
+      name: my-cache
+    spec:
+      l1:
+        sizeGB: 60
+      resourceOverrides:
+        requests:
+          memory: "70Gi"
+          cpu: "8"
+        limits:
+          memory: "100Gi"
+
+.. _mp-operator-cacheblend:
+
+CacheBlend
+----------
+
+CacheBlend reuses cached KV at shifted (non-prefix) positions by recomputing a
+small subset of tokens.  The operator manages it as a second CRD,
+``CacheBlendEngine``, plus a **mutating admission webhook** that injects the
+pure-Python ``lmcache-cacheblend`` vLLM plugin into your serving pods -- so you
+do **not** rebuild the vLLM image.  See :doc:`/kv_cache_optimizations/blending`
+for the technique itself.
+
+It has two halves the operator runs together:
+
+- a GPU-resident CacheBlend V3 engine (``lmcache server --engine-type blend``),
+  deployed as a DaemonSet with the **same GPU model as** ``LMCacheEngine``
+  (``runtimeClassName: nvidia`` + ``NVIDIA_VISIBLE_DEVICES=all`` + ``hostIPC``,
+  plus ``privileged`` when ``spec.privileged`` is set, and **no**
+  ``nvidia.com/gpu`` claim) so it shares the vLLM GPU for same-device CUDA IPC;
+  and
+- the vLLM-side plugin, injected into opted-in pods by the webhook.
+
+Additional Prerequisites
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Beyond the operator prerequisites above:
+
+- **cert-manager** -- the webhook's serving certificate is issued by a
+  cert-manager ``Issuer`` + ``Certificate``.  Install it before ``make deploy``:
+
+  .. code-block:: bash
+
+      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
+      kubectl -n cert-manager wait --for=condition=Available deploy --all --timeout=180s
+
+- **Deploy with the webhook** -- use ``make deploy`` (not ``make run``, which is
+  controller-only and disables the webhook via ``ENABLE_WEBHOOKS=false``).
+- **Pod Security Standards** -- the webhook injects ``hostIPC``/``privileged``,
+  which the ``baseline``/``restricted`` profiles reject, so label the engine's
+  and the vLLM pod's namespaces ``pod-security.kubernetes.io/enforce=privileged``.
+
+Deploying a CacheBlendEngine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: CacheBlendEngine
+    metadata:
+      name: my-cacheblend
+    spec:
+      l1:
+        sizeGB: 60
+      injection:
+        # The (private) cacheblend-plugin init-container image -- repository/tag/
+        # pullPolicy, like spec.image.  Set repository to YOUR image; the
+        # inherited engine-image default is not a valid payload.
+        payloadImage:
+          repository: <registry>/cacheblend-plugin
+          tag: <tag>
+        # Appended to the vLLM pod so the private payload image can pull; the
+        # Secret must exist in the vLLM pod's namespace.
+        imagePullSecrets:
+          - name: my-registry-secret
+
+The engine runs ``lmcache server --engine-type blend`` as a DaemonSet and
+emits a ``my-cacheblend-connection`` ConfigMap with the ``CBKVConnector``
+``kv-transfer-config`` (the operator wires the node-local Service host/port and
+the ``cb.*`` tunables).
+
+Opting a vLLM Pod In
+~~~~~~~~~~~~~~~~~~~~~
+
+Label the pod template for the webhook and bind it to an engine by name.  Launch
+vLLM via the image **ENTRYPOINT** (args only) -- a
+``command: ["/bin/sh", "-c", ...]`` wrapper is skipped, since appended args would
+not reach ``vllm serve``:
+
+.. code-block:: yaml
+
+    apiVersion: apps/v1
+    kind: Deployment
+    metadata:
+      name: vllm-cacheblend
+    spec:
+      replicas: 1
+      selector:
+        matchLabels:
+          app: vllm-cacheblend
+      template:
+        metadata:
+          labels:
+            app: vllm-cacheblend
+            lmcache.ai/cacheblend-inject: "true"          # opt-in (webhook objectSelector)
+          annotations:
+            lmcache.ai/cacheblend-engine: "my-cacheblend" # bind to the engine
+        spec:
+          runtimeClassName: nvidia
+          containers:
+            - name: vllm
+              image: lmcache/vllm-openai:<pinned-tag>
+              args: ["<your-model>", "--port", "8000", "--gpu-memory-utilization", "0.8"]
+              resources:
+                limits:
+                  nvidia.com/gpu: "1"
+
+The webhook injects the plugin init container, ``PYTHONPATH``, ``hostIPC``, the
+private-image pull secret, and the required CacheBlend vLLM flags
+(``--attention-backend CUSTOM``, ``--kv-transfer-config`` from the engine's
+connection ConfigMap, ``--block-size 64``, ``--pipeline-parallel-size 1``,
+``--no-enable-chunked-prefill``, ``--no-async-scheduling``, ``--enforce-eager``).
+You supply only the model and your non-CacheBlend flags.
+
+Verifying Injection
+~~~~~~~~~~~~~~~~~~~~~
+
+The webhook mutates **Pods**, not the Deployment, so inspect a pod:
+
+.. code-block:: bash
+
+    kubectl get pod -l app=vllm-cacheblend -o yaml | \
+      grep -E "initContainers|cb-plugin|PYTHONPATH|attention-backend|cacheblend-injected|skip-reason"
+
+If nothing was injected, check the pod's ``lmcache.ai/cacheblend-skip-reason``
+annotation: ``command-override`` (a ``sh -c`` wrapper was used),
+``kv-transfer-config-present`` (you set your own), ``engine-not-found`` (the
+``<name>-connection`` ConfigMap is missing), ``payload-image-unset`` (the
+engine's ``injection.payloadImage`` has no repository), or
+``target-container-not-found`` (the requested ``targetContainer`` /
+``cacheblend-container`` annotation names a container the pod does not have).
+With ``failurePolicy: Ignore`` a
+webhook/cert problem also leaves the pod un-mutated silently -- confirm the
+operator pod is ``Running`` and the ``MutatingWebhookConfiguration`` exists.
+
+CacheBlendEngine Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``CacheBlendEngineSpec`` mirrors ``LMCacheEngineSpec`` (every field in the CRD
+Spec Reference above) and adds:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``blend.checkLayer``
+     - ``1``
+     - Layer at which token importance is scored (``cb.check_layer``).
+   * - ``blend.recompRatio``
+     - ``0.15``
+     - Fraction of non-prefix-hit tokens recomputed (``cb.recomp_ratio``).
+   * - ``injection.payloadImage``
+     - *required*
+     - The (private) cacheblend-plugin init-container image
+       (``repository`` / ``tag`` / ``pullPolicy``).  Set ``repository`` -- the
+       inherited engine-image default is not a valid payload.
+   * - ``injection.imagePullSecrets``
+     - --
+     - Pull secrets appended to the vLLM pod for the private payload image.
+   * - ``injection.targetContainer``
+     - first container
+     - Name of the vLLM container to inject into.
+   * - ``injection.cudagraph``
+     - ``eager``
+     - ``eager`` | ``piecewise`` | ``full_decode_only`` (never ``full``).
+
+``server.chunkSize`` defaults to ``256`` and must equal 256 (the blend matcher
+requires ``chunk_size == vLLM --block-size * 4``).
+
+LMCacheCoordinator
+------------------
+
+The ``LMCacheCoordinator`` CRD runs the **mp coordinator** -- a fleet-wide HTTP
+service that tracks mp server instances, evicts those whose heartbeats lapse,
+performs L2 quota eviction, and hosts the global CacheBlend fingerprint
+directory.  It is a plain (non-GPU) ``Deployment`` exposed through a ClusterIP
+Service; engines reach it via ``coordinator.ref`` or ``coordinator.url``.
+
+Deploying a Coordinator
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A ready-to-edit manifest lives at
+``config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml`` in the operator
+repo.  A minimal coordinator:
+
+.. code-block:: yaml
+
+    apiVersion: lmcache.lmcache.ai/v1alpha1
+    kind: LMCacheCoordinator
+    metadata:
+      name: my-coordinator
+    spec:
+      port: 9300
+
+.. code-block:: bash
+
+    kubectl get lmcc my-coordinator   # shortName: lmcc
+
+Connecting an Engine
+~~~~~~~~~~~~~~~~~~~~~
+
+Point an ``LMCacheEngine`` / ``CacheBlendEngine`` at the coordinator through its
+``coordinator`` block.  Use ``ref`` to name a coordinator in the same namespace
+(the operator resolves it to the in-cluster Service URL), or ``url`` for an
+explicit endpoint:
+
+.. code-block:: yaml
+
+    spec:
+      coordinator:
+        ref:
+          name: my-coordinator       # or: url: http://my-coordinator.default.svc:9300
+        heartbeatInterval: 5          # seconds; must be > 0
+        l2EventReporting: false       # report L2 store/lookup events for fleet eviction
+
+Coordinator CRD Spec Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Topology
+^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``replicas``
+     - ``1``
+     - Coordinator pods.  The registry is per-process in-memory, so >1 only
+       makes sense behind a shared durable backend.  Must be >= 0.
+   * - ``image.repository`` / ``image.tag`` / ``image.pullPolicy``
+     - shared engine image
+     - Runs the same lmcache binary as the engines.
+   * - ``imagePullSecrets``
+     - --
+     - Image pull secret references.
+
+HTTP Server
+^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``host``
+     - ``0.0.0.0``
+     - Address the coordinator's HTTP server binds to.
+   * - ``port``
+     - ``9300``
+     - HTTP port (1--65535).
+
+Membership & Health
+^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``instanceTimeout``
+     - ``30``
+     - Seconds without a heartbeat after which an instance is evicted.  Set
+       comfortably above the engines' ``coordinator.heartbeatInterval``.
+   * - ``healthCheckInterval``
+     - ``10``
+     - Seconds between health-check sweeps; ``0`` disables the loop.
+
+L2 Quota Eviction
+^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``evictionCheckInterval``
+     - ``5``
+     - Seconds between L2 eviction sweeps; ``0`` disables the loop.
+   * - ``evictionRatio``
+     - ``0.2``
+     - Fraction of tracked keys (by count) to evict per cycle, [0.0, 1.0].
+   * - ``triggerWatermark``
+     - ``1.0``
+     - Usage fraction of the quota that fires eviction, (0.0, 1.0].
+
+Global CacheBlend Directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``blendChunkSize``
+     - ``256``
+     - Tokens per chunk for the global CacheBlend directory (the match unit).
+       **Must equal** the LMCache chunk size the blend servers use.  Must be > 0.
+   * - ``blendProbeStride``
+     - ``1``
+     - Positions between match probes.  ``1`` probes every offset for full
+       recall; raise it to trade recall for coordinator CPU.  Must be > 0.
+
+Prometheus, Scheduling & Overrides
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 45
+
+   * - Field
+     - Default
+     - Description
+   * - ``prometheus.enabled``
+     - ``true``
+     - Expose the metrics container port.  See the note below.
+   * - ``prometheus.port``
+     - ``9090``
+     - Metrics port.
+   * - ``prometheus.serviceMonitor.enabled``
+     - ``false``
+     - Create a ServiceMonitor CR (and headless metrics Service).
+   * - ``prometheus.serviceMonitor.interval``
+     - ``30s``
+     - Scrape interval.
+   * - ``logLevel``
+     - ``INFO``
+     - ``DEBUG`` | ``INFO`` | ``WARNING`` | ``ERROR``.
+   * - ``resourceOverrides``
+     - --
+     - Pod resource requests/limits (no auto-compute; the coordinator is
+       CPU/memory light).
+   * - ``nodeSelector`` / ``affinity`` / ``tolerations`` / ``priorityClassName``
+     - --
+     - Pod scheduling controls.
+   * - ``env`` / ``volumes`` / ``volumeMounts`` / ``podAnnotations`` / ``podLabels`` / ``serviceAccountName``
+     - --
+     - Standard pod-shaping fields.
+   * - ``extraArgs``
+     - --
+     - Extra CLI flags (appended last, can override any auto-generated flag).
+
+.. note::
+   The coordinator process does **not** yet expose a ``/metrics`` endpoint.  The
+   Prometheus wiring is present for parity but is only useful once metrics are
+   added; ``serviceMonitor.enabled`` defaults to ``false``.
+
+Coordinator Resources Created
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For an ``LMCacheCoordinator`` named ``my-coordinator``:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 25 50
+
+   * - Resource
+     - Name
+     - Purpose
+   * - Deployment
+     - ``my-coordinator``
+     - Runs the coordinator HTTP server pods.
+   * - Service (ClusterIP)
+     - ``my-coordinator``
+     - Fleet-wide discovery on the HTTP port.
+   * - Service (headless)
+     - ``my-coordinator-metrics``
+     - Prometheus scrape target (when ``serviceMonitor.enabled``).
+   * - ServiceMonitor
+     - ``my-coordinator``
+     - Prometheus Operator integration (when ``serviceMonitor.enabled``).
+
+The status ``endpoint`` other components use to reach the coordinator is
+``http://<name>.<namespace>.svc:<port>`` (e.g.
+``http://my-coordinator.default.svc:9300``).
+
+Coordinator Status & Conditions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The status section includes:
+
+- **phase**: ``Pending``, ``Running``, ``Degraded``, or ``Failed``.
+- **replicas** / **readyReplicas**: Pod counts from the Deployment.
+- **endpoint**: In-cluster URL for reaching the coordinator.
+- **observedGeneration**: Most recent reconciled generation.
+- **conditions**:
+
+  - ``Available`` -- At least one replica is ready.
+  - ``AllInstancesReady`` -- All desired replicas are ready.
+  - ``ConfigValid`` -- Spec validation passed.
+
+Coordinator Validation Rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Field
+     - Rule
+   * - ``port``
+     - Must be in [1, 65535].
+   * - ``replicas``
+     - Must be >= 0.
+   * - ``instanceTimeout``
+     - Must be > 0.
+   * - ``healthCheckInterval`` / ``evictionCheckInterval``
+     - Must be >= 0.
+   * - ``evictionRatio``
+     - Must be in [0.0, 1.0].
+   * - ``triggerWatermark``
+     - Must be in (0.0, 1.0].
+   * - ``blendChunkSize`` / ``blendProbeStride``
+     - Must be > 0.
+
+Operator vs Manual Deployment
+-----------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - Concern
+     - Manual DaemonSet
+     - LMCacheEngine Operator
+   * - hostIPC
+     - Must set manually
+     - Auto-injected
+   * - ``--host 0.0.0.0``
+     - Must set manually
+     - Auto-injected
+   * - Service discovery
+     - ``hostNetwork`` + ``status.hostIP``
+     - Node-local ClusterIP Service + ConfigMap
+   * - vLLM config
+     - Copy JSON into Deployment
+     - Mount ``<name>-connection`` ConfigMap
+   * - Resource sizing
+     - Manual calculation
+     - Auto-computed from ``l1.sizeGB``
+   * - Prometheus
+     - Manual ServiceMonitor
+     - ``serviceMonitor.enabled: true``
+   * - Validation
+     - Runtime errors only
+     - ``kubectl apply`` rejects invalid specs
+   * - New GPU nodes
+     - DaemonSet handles it
+     - DaemonSet handles it (same)
+
+Security Considerations
+-----------------------
+
+**hostIPC** exposes the host's IPC namespace (System V IPC, POSIX message
+queues) to the container.  Any process in the container can interact with IPC
+resources from other processes on the same host.
+
+- Deploy only in trusted environments.
+- Clusters using Pod Security Standards must allow the ``privileged`` profile
+  for the LMCache namespace -- the ``baseline`` and ``restricted`` profiles
+  reject ``hostIPC``.
+- ``spec.privileged`` defaults to ``false``. When enabled (required for
+  ``gpuVendor: amd``), the engine container additionally runs privileged,
+  granting it full device access -- enable it only where GPU visibility
+  requires it.
+
+Development
+-----------
+
+.. code-block:: bash
+
+    make generate     # Generate DeepCopy methods
+    make manifests    # Generate CRD YAML + RBAC
+    make build        # Compile operator binary
+    make fmt          # go fmt
+    make vet          # go vet
+    make test         # Run unit tests
+    make lint         # Run golangci-lint
+
+Pushing a custom operator image:
+
+.. code-block:: bash
+
+    # Docker Hub
+    make docker-build docker-push IMG=docker.io/<your-user>/lmcache-operator:latest
+    make deploy IMG=docker.io/<your-user>/lmcache-operator:latest
+
+    # Multi-platform (amd64 + arm64)
+    make docker-buildx IMG=<your-registry>/lmcache-operator:latest
+
+If your cluster needs pull credentials:
+
+.. code-block:: bash
+
+    kubectl create secret docker-registry regcred \
+      --docker-server=<your-registry> \
+      --docker-username=<username> \
+      --docker-password=<password> \
+      -n lmcache-operator-system
diff --git a/docs/source/mp/p2p.rst b/docs/source/mp/p2p.rst
new file mode 100644
index 0000000..4865521
--- /dev/null
+++ b/docs/source/mp/p2p.rst
@@ -0,0 +1,250 @@
+.. _mp_p2p:
+
+P2P KV Cache Sharing
+====================
+
+Overview
+--------
+
+In a multi-node deployment, every node runs its own LMCache server process,
+and each one caches the KV of the requests it has served in its local memory.
+Without sharing, a prefix that was computed on one node has to be recomputed
+from scratch when the same prefix arrives on a different node.
+
+**Peer-to-peer (P2P) KV cache sharing turns the per-node caches into one
+logical cache.** When a node looks up a prefix that is not in its own memory,
+it can read that prefix's KV directly from the memory of the peer node that
+holds it, over the datacenter network using RDMA. The result is a much higher
+effective cache hit rate across the fleet, without any central storage tier in
+the hot path.
+
+The transfer is a one-sided RDMA read from the requesting node into its own L1
+buffer; the node that owns the data is not interrupted to serve it. On an
+RDMA-capable network (InfiniBand / RoCE) this is dramatically faster than
+recomputing the prefix or round-tripping through a shared object store.
+
+How it works
+------------
+
+P2P involves three pieces:
+
+* **Coordinator** — a small HTTP service (one per deployment) that tracks which
+  LMCache servers are alive. Each server registers with it and heartbeats; the
+  coordinator answers "who are my live peers?" queries. It only manages
+  membership — it never sees KV data or participates in lookups. See
+  :doc:`coordinator`.
+* **LMCache server** — each server runs a P2P controller that periodically asks
+  the coordinator for the current peer list and, for every live peer, opens a
+  connection used to look up and read that peer's KV.
+* **Transfer channel** — the RDMA layer that performs the actual remote memory
+  reads. Each server registers its L1 buffer once at startup so peers can read
+  from it.
+
+On a cache miss, a node asks the peer that owns the prefix to *lock and locate*
+it, receives the remote addresses, RDMA-reads the KV into its own L1, and serves
+the request from there. Peers are discovered and connected automatically as
+they join, and disconnected automatically as they leave — no static peer lists.
+
+Requirements
+------------
+
+* **A coordinator.** P2P needs the coordinator for peer discovery. A server
+  started with ``--p2p-advertise-url`` but no ``--coordinator-url`` refuses to
+  start.
+* **An RDMA-capable network** (InfiniBand / RoCE) is strongly recommended for
+  production performance. By default P2P uses the ``nixl`` transfer engine,
+  which is shipped with LMCache, so there is nothing extra to install.
+* **A single, contiguous L1 region.** The transfer channel registers the whole
+  L1 buffer for RDMA, so P2P is incompatible with the GDS L1 tier
+  (``--gds-l1-path``) and the Device-DAX L1 tier (``--l1-devdax-path``); the
+  server refuses to start in those configurations.
+
+Configuration
+-------------
+
+P2P is enabled per server by the ``--p2p-advertise-url`` flag. The relevant
+``lmcache server`` flags are:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Flag
+     - Description
+   * - ``--p2p-advertise-url HOST:PORT``
+     - Transfer-channel endpoint this server advertises to peers. Setting it
+       enables P2P. Must be an address other nodes can reach.
+   * - ``--p2p-listen-url HOST:PORT``
+     - Address the transfer-channel server binds to. Defaults to
+       ``--p2p-advertise-url``; set it to bind ``0.0.0.0`` while advertising a
+       routable IP.
+   * - ``--p2p-lookup-timeout SECONDS``
+     - Deadline for a peer lookup before it counts as a miss (default ``30``).
+   * - ``--p2p-load-timeout SECONDS``
+     - Deadline for a peer KV read before it counts as a failure
+       (default ``30``).
+   * - ``--p2p-transfer-engine ENGINE``
+     - Transfer-channel implementation (default ``nixl``).
+
+P2P also reuses the coordinator connection flags (``--coordinator-url``,
+``--coordinator-advertise-ip``, ``--coordinator-heartbeat-interval``); the
+heartbeat interval doubles as the peer-discovery poll interval. See
+:doc:`/cli/server` and :doc:`/cli/coordinator` for the full flag lists.
+
+.. tip::
+
+   Increase the L1 buffer alignment to at least 64 KB
+   (``--l1-align-bytes 65536``) on servers that participate in P2P. A larger
+   alignment lets the transfer channel issue bigger, better-aligned RDMA reads
+   and noticeably improves transfer performance. The default (4 KB) is fine for
+   non-P2P deployments.
+
+Transfer engine backends
+------------------------
+
+The transfer engine is the component that performs the remote memory reads,
+selected per server with ``--p2p-transfer-engine``.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Engine
+     - Description
+   * - ``nixl`` (default)
+     - RDMA-based transport, shipped with LMCache. Runs over InfiniBand / RoCE
+       fabrics.
+
+``nixl`` is the only backend available today. The transfer engine is a
+pluggable abstraction, so additional backends can be added in the future
+without changing the rest of the P2P stack.
+
+Running a multi-node deployment
+-------------------------------
+
+The example below brings up a two-node fleet. Adding more nodes is just more
+copies of the per-node step, all pointing at the same coordinator.
+
+**Step 1 — start the coordinator** (on a host all nodes can reach, here
+``10.0.0.1``):
+
+.. code-block:: bash
+
+   lmcache coordinator --host 0.0.0.0 --port 9300
+
+**Step 2 — on each node, start the LMCache server with P2P enabled.** Replace
+``<NODE_IP>`` with that node's routable address (e.g. ``10.0.0.2``,
+``10.0.0.3``, ...):
+
+.. code-block:: bash
+
+   lmcache server \
+       --host 0.0.0.0 --port 5555 \
+       --http-port 8080 \
+       --l1-size-gb 100 --eviction-policy LRU \
+       --l1-align-bytes 65536 \
+       --coordinator-url http://10.0.0.1:9300 \
+       --coordinator-advertise-ip <NODE_IP> \
+       --p2p-advertise-url <NODE_IP>:8500
+
+``--coordinator-advertise-ip`` is the address peers use to reach this node's
+control plane, and ``--p2p-advertise-url`` is the RDMA transfer endpoint. Here
+the server binds ``0.0.0.0`` (all interfaces) and advertises ``<NODE_IP>``.
+
+**Step 3 — on each node, start vLLM** pointed at the *local* LMCache server via
+the connector. vLLM never talks to peers directly — the LMCache server it
+connects to does P2P on its behalf:
+
+.. code-block:: bash
+
+   vllm serve <model> \
+       --port 8000 \
+       --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_load_failure_policy":"recompute","kv_connector_extra_config":{"lmcache.mp.port":5555}}'
+
+Once both nodes have registered, a prefix first served on node 2 will be served
+from node 2's cache when the same prefix later arrives on node 3 — read over
+RDMA instead of recomputed.
+
+Running on a single node (testing & debugging)
+----------------------------------------------
+
+You can exercise the entire P2P path on a single multi-GPU machine by running
+two LMCache servers and two vLLM servers over ``localhost``, plus one
+coordinator. This is the recommended way to develop and debug P2P.
+
+.. code-block:: bash
+
+   # Terminal 1 — coordinator
+   lmcache coordinator --host 0.0.0.0 --port 9300
+
+   # Terminal 2 — node "A": LMCache server
+   lmcache server \
+       --host 127.0.0.1 --port 6555 --http-port 7555 \
+       --l1-size-gb 50 --eviction-policy LRU \
+       --l1-align-bytes 65536 \
+       --instance-id node-a \
+       --coordinator-url http://127.0.0.1:9300 \
+       --coordinator-advertise-ip 127.0.0.1 \
+       --p2p-advertise-url 127.0.0.1:8555
+
+   # Terminal 3 — node "A": vLLM on GPU 0
+   CUDA_VISIBLE_DEVICES=0 vllm serve <model> --port 8000 \
+       --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_load_failure_policy":"recompute","kv_connector_extra_config":{"lmcache.mp.port":6555}}'
+
+   # Terminal 4 — node "B": LMCache server
+   lmcache server \
+       --host 127.0.0.1 --port 6556 --http-port 7556 \
+       --l1-size-gb 50 --eviction-policy LRU \
+       --l1-align-bytes 65536 \
+       --instance-id node-b \
+       --coordinator-url http://127.0.0.1:9300 \
+       --coordinator-advertise-ip 127.0.0.1 \
+       --p2p-advertise-url 127.0.0.1:8556
+
+   # Terminal 5 — node "B": vLLM on GPU 1
+   CUDA_VISIBLE_DEVICES=1 vllm serve <model> --port 8001 \
+       --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_load_failure_policy":"recompute","kv_connector_extra_config":{"lmcache.mp.port":6556}}'
+
+The two servers must differ in **every** port: ZMQ (``--port``), HTTP
+(``--http-port``), and the P2P transfer endpoint (``--p2p-advertise-url``).
+Give each a distinct ``--instance-id`` so they are easy to tell apart.
+
+To test the path, send a long prompt to vLLM **A** (port ``8000``) and then the
+*same* prompt to vLLM **B** (port ``8001``). B has never seen the prompt and its
+own cache is empty, so any LMCache hit on B must have been read from A over P2P.
+
+.. note::
+
+   On a single host, ``localhost`` traffic typically uses the loopback/TCP path
+   rather than RDMA, so latencies are not representative of a real RDMA fabric.
+   Single-node mode is for **functional** testing and debugging; benchmark
+   performance on a real multi-node RDMA deployment.
+
+Verifying P2P is working
+------------------------
+
+Query a server's status endpoint to see its P2P state and discovered peers:
+
+.. code-block:: bash
+
+   curl -s http://127.0.0.1:7555/status | python3 -m json.tool
+
+Look for ``p2p_state`` (``registered`` once it has joined the coordinator) and
+``p2p_peer_count`` (the number of connected peers; ``1`` in the two-node
+example). You can also list the fleet from the coordinator:
+
+.. code-block:: bash
+
+   curl -s http://127.0.0.1:9300/instances | python3 -m json.tool
+
+With ``LMCACHE_LOG_LEVEL=DEBUG``, each server logs ``Added P2P adapter ... for
+peer <instance-id>`` when it connects to a peer, and ``Removed P2P adapter ...``
+when a peer leaves.
+
+Limitations
+-----------
+
+* **Read-only.** A node reads KV from its peers; it never writes into a peer's
+  memory. This keeps each node the sole owner of its L1.
+* **One hop.** A node reads directly from the peer that holds the prefix; reads
+  are not chained across multiple peers.
diff --git a/docs/source/mp/sdk.rst b/docs/source/mp/sdk.rst
new file mode 100644
index 0000000..18f49c5
--- /dev/null
+++ b/docs/source/mp/sdk.rst
@@ -0,0 +1,142 @@
+KV Cache SDK
+====================
+
+The LMCache **SDK** lets you retrieve a request's KV cache from a LMCache
+server, transform it on the CPU, and store it back. This can be used for KV
+cache transformations, such as token dropping. In the example: we prefill a
+batch of long prompts, drop half of each request's KV chunks, and show the
+decode-throughput gain. The full runnable notebook lives at
+`examples/token_dropping/token_dropping.ipynb
+<https://github.com/LMCache/LMCache/tree/dev/examples/token_dropping>`_.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+Why KV Cache SDK
+----------------
+
+- **Improving Decode Throughput** when shrinking KV cache using token dropping.
+  Token dropping reduces the KV cache size, allowing more requests to fit in a
+  batch, improving decode throughput.
+
+The SDK gives you the hooks to retrieve a request's KV, supply your own 
+function to edit the KV, and store the edited KV back. The SDK also provides a
+batched-stream API to prefill, modify, and store the cache back before
+decoding continues.
+
+
+How it works
+------------
+
+A request flows through three phases on the batched-stream API:
+
+- **prefill** — run each prompt through vLLM once (``max_tokens=1``); vLLM
+  computes the KV cache and stores it in LMCache.
+- **modify** — the SDK retrieves the cached KV to CPU, hands it to your edit
+  function, and stores the result back.
+- **decode** — continue generation against the smaller, edited cache.
+
+The SDK runs on **CPU** and hands you KV tensors in ``HND`` order with shape
+``[2, L, T, D]`` (K/V, layers, chunk-aligned tokens, ``num_kv_heads * head_dim``).
+
+
+Configuration
+-------------
+
+To start the LMCache server with shared-memory transfer enabled, pass
+``--shm-name`` and disable lazy L1 allocation with ``--no-l1-use-lazy``. If
+shared memory is unavailable and these flags are not specified, the SDK falls 
+back to pickle.
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 150 \
+        --eviction-policy LRU \
+        --chunk-size 256 \
+        --port 6555 \
+        --http-port 8080 \
+        --shm-name lmcache_kvcache_sdk \
+        --no-l1-use-lazy
+
+Then start vLLM with the LMCache MP connector.
+
+.. code-block:: bash
+
+    vllm serve Qwen/Qwen3-8B \
+        --port 8000 \
+        --enforce-eager \
+        --gpu-memory-utilization 0.65 \
+        --kv-transfer-config '{
+            "kv_connector":"LMCacheMPConnector",
+            "kv_role":"kv_both",
+            "kv_connector_extra_config":{"lmcache.mp.port":6555}
+        }' \
+        --trust-remote-code \
+        --return-tokens-as-token-ids
+
+The SDK keys the KV cache by token ids: ``create_request`` takes the prompt as
+token ids, and every ``post_completion`` must report a ``token_id`` for each
+generated token. The example gets these ids straight from vLLM by passing
+``--return-tokens-as-token-ids``. Otherwise, if vLLM returns only text, the
+``post_completion`` must tokenize each generated token back into a token id.
+
+.. code-block:: python
+
+    import lmcache.sdk.kvcache as lmc_sdk
+
+    ctx = lmc_sdk.connect(
+        url="tcp://localhost:6555",         # must match --port
+        http_url="http://localhost:8080",   # must match --http-port
+        model_name="Qwen/Qwen3-8B",
+        timeout=60,
+    )
+    ...
+    lmc_sdk.close(ctx)
+
+
+Writing a custom edit function
+------------------------------
+
+An edit function takes the retrieved KV tensor and its token ids and returns the
+edited ``(kv, tokens)``. ``batch.modify(fn)`` applies it to every stream.
+
+``modify`` operates only on the **chunk-aligned** prefix. A trailing partial
+chunk is tracked by the SDK and re-sent on the next ``decode``, so
+``tokens`` arrives already truncated to the cached length.
+
+
+API reference
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - Function / method
+     - Description
+   * - ``lmc_sdk.connect(url, http_url, model_name, timeout=60.0)``
+     - Create an SDK context and register the transfer context, pass it to
+       every other call.
+   * - ``lmc_sdk.close(ctx)``
+     - Close the context and release resources. Called when done with the SDK.
+   * - ``lmc_stream.create_request(ctx, post_completion,
+       prompt_token_ids, cache_salt="")``
+     - Create one request stream to add to a batch.
+   * - ``lmc_batch.LMCacheBatchedStream()``
+     - Create an empty batch.
+   * - ``batch.add(stream)``
+     - Register a stream to the batch.
+   * - ``batch.prefill(sampling_params)``
+     - Prefill every stream once (``max_tokens`` forced to 1). Returns a
+       ``Metrics`` report.
+   * - ``batch.modify(fn)``
+     - Apply the edit function ``fn`` to every stream's cached KV. Returns a
+       ``Metrics`` report.
+   * - ``batch.decode(sampling_params)``
+     - Decode every stream. Returns a ``Metrics`` report.
+
+```Metrics`` returns ``input_tokens``, ``input_tput`` for prefill, ``duration``
+for modify, and ``output_tokens``, ``output_tput`` for decode.
diff --git a/docs/source/mp/serde.rst b/docs/source/mp/serde.rst
new file mode 100644
index 0000000..cb7fb4e
--- /dev/null
+++ b/docs/source/mp/serde.rst
@@ -0,0 +1,191 @@
+KV Cache Compression
+====================
+
+LMCache supports a **per-adapter serde** that transforms KV cache data on
+its way to and from an L2 adapter. Typical uses: quantization (shrink
+storage footprint), compression, encryption.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+When to use serde
+-----------------
+
+- **Save L2 storage or bandwidth.** fp8 quantization halves byte volume
+  vs. bf16 with minor accuracy loss — a good fit for disk / remote
+  adapters.
+- **Encrypt at rest.** Wrap the raw bytes with authenticated encryption
+  before they land on disk.
+- **Custom compression.** Anything lossless (lz4/zstd) or lossy
+  (CacheGen-style) can be plugged in via the ``Serializer`` /
+  ``Deserializer`` ABCs.
+
+Serde is **opt-in per adapter**: one ``--l2-adapter`` may use fp8 while
+another stores raw bytes. When omitted, the adapter behaves exactly as
+if serde did not exist (no extra allocations, no extra threads).
+
+
+Configuring serde on an L2 adapter
+----------------------------------
+
+Add a ``"serde"`` sub-dict to any ``--l2-adapter`` JSON spec. The ``type``
+field selects a registered serde; remaining keys are forwarded to the
+serde factory.
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 \
+        --eviction-policy LRU \
+        --l2-adapter '{
+            "type": "fs",
+            "base_path": "/data/lmcache/l2",
+            "serde": {"type": "fp8", "fp8_dtype": "float8_e4m3fn"}
+        }'
+
+.. list-table:: Built-in serde types
+   :header-rows: 1
+   :widths: 15 40 45
+
+   * - ``type``
+     - Description
+     - Config fields
+   * - ``fp8``
+     - Quantize each element to 8-bit float; dequantize on load.
+       Lossy but highly compressible.
+     - ``fp8_dtype`` (default ``float8_e4m3fn``; also accepts
+       ``float8_e5m2``), ``max_workers`` (thread pool size,
+       default 1)
+   * - ``turboquant``
+     - Compress KV tensors with TurboQuant presets before L2 store and
+       reconstruct them on load.
+     - ``preset`` (default ``turboquant_k8v4``), ``head_dim`` (optional,
+       default 128), ``block_size`` (default 16), ``max_workers`` (thread
+       pool size, default 1)
+
+
+TurboQuant serde
+----------------
+
+TurboQuant serde can be enabled by setting ``"type": "turboquant"`` in the
+adapter serde config. If ``preset`` is omitted, TurboQuant serde defaults to
+``turboquant_k8v4``.
+
+.. code-block:: bash
+
+    lmcache server \
+        --l1-size-gb 100 \
+        --eviction-policy LRU \
+        --l2-adapter '{
+            "type": "fs",
+            "base_path": "/data/lmcache/l2",
+            "serde": {
+                "type": "turboquant",
+                "preset": "turboquant_k8v4",
+                "block_size": 16
+            }
+        }'
+
+Supported presets:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 35 35
+
+   * - Preset
+     - Key path
+     - Value path
+   * - ``turboquant_k8v4``
+     - FP8 key
+     - 4-bit value quantization
+   * - ``turboquant_4bit_nc``
+     - 4-bit MSE key with norm correction
+     - 4-bit value quantization
+   * - ``turboquant_k3v4_nc``
+     - 3-bit MSE key with norm correction
+     - 4-bit value quantization
+   * - ``turboquant_3bit_nc``
+     - 3-bit MSE key with norm correction
+     - 3-bit value quantization
+
+
+Writing a custom serde
+----------------------
+
+Implement the two sync ABCs (``Serializer``, ``Deserializer``) with your
+transform logic, then register a factory keyed on a name you pick:
+
+.. code-block:: python
+
+    # my_project/my_serde.py
+    from lmcache.v1.distributed.serde import (
+        AsyncSerdeProcessor,
+        Deserializer,
+        Serializer,
+        register_serde_factory,
+    )
+
+    class MySerializer(Serializer):
+        def serialize(self, src, dst) -> int:
+            # Write serialized bytes into dst; return bytes written.
+            ...
+
+        def estimate_serialized_size(self, layout_desc) -> int:
+            # Upper bound on serialized byte size for this layout.
+            ...
+
+    class MyDeserializer(Deserializer):
+        def deserialize(self, src, dst) -> None:
+            # Read serialized bytes from src, write into dst (KV-shaped).
+            ...
+
+    def _create_mine(config: dict):
+        return AsyncSerdeProcessor(MySerializer(), MyDeserializer())
+
+    register_serde_factory("mine", _create_mine)
+
+Reference it from your adapter config:
+
+.. code-block:: json
+
+    {"type": "fs", "base_path": "/data", "serde": {"type": "mine"}}
+
+
+Notes
+-----
+
+- **Buffer size.** ``estimate_serialized_size(layout)`` must return an
+  upper bound on the actual serialized output — include any safety
+  margin directly in the estimate (e.g., the built-in fp8 serializer
+  returns ``1.5 * num_elements``).
+- **Failure handling.** If any step fails (serialize, store, load, or
+  deserialize), the whole submitted batch is reported as failed —
+  partial success within one batch is not surfaced. Failed keys are
+  cleaned up automatically.
+- **Thread pool.** ``AsyncSerdeProcessor(max_workers=N)`` controls the
+  pool size. Transforms that release the GIL (e.g., torch ops)
+  benefit from ``N > 1``; pure-Python transforms do not.
+
+
+Example
+-------
+
+An end-to-end script that starts an lmcache server with fp8 on a disk
+adapter, runs vLLM, clears L1, and re-runs the same request to trigger
+the L2 prefetch + fp8 deserialize path lives at
+:file:`examples/serde/fp8/`. A pytest-based filesystem round-trip test
+(no vLLM required) is at
+:file:`tests/v1/distributed/serde/test_serde_fs_e2e.py`.
+
+Compression methods
+-------------------
+
+Higher-level KV cache compression methods layered on top of the per-adapter
+serde mechanism:
+
+.. toctree::
+   :maxdepth: 1
+
+   cachegen
diff --git a/docs/source/mp/tracing_and_debugging.rst b/docs/source/mp/tracing_and_debugging.rst
new file mode 100644
index 0000000..141b51e
--- /dev/null
+++ b/docs/source/mp/tracing_and_debugging.rst
@@ -0,0 +1,330 @@
+Tracing and Debugging
+=====================
+
+LMCache MP mode can record every ``StorageManager`` public-API call to a
+binary **trace file** and reissue those calls later against a fresh
+server via ``lmcache trace replay``. The feature is designed for:
+
+- **Regression hunting** — capture a production workload, then replay it
+  against a build under investigation to reproduce a bug offline.
+- **Performance characterization** — measure L1/L2 latency distributions
+  under a realistic storage-level access pattern, without needing vLLM
+  or a GPU.
+- **Configuration tuning** — replay the same trace against different
+  L1 sizes, eviction policies, and L2 adapters to compare their
+  behavior on identical input.
+
+.. note::
+
+   Trace recording is **independent** from ``--enable-tracing``
+   (OTel spans). OTel tracing exports *live* spans to an OTLP
+   endpoint for online observability; trace recording persists a
+   replayable binary file for offline analysis. Both can be enabled
+   simultaneously.
+
+.. _trace-recording-guide:
+
+Recording a Trace
+-----------------
+
+Recording is **off by default**. Enable it by adding
+``--trace-level storage`` to ``lmcache server``:
+
+.. code-block:: bash
+
+    # Explicit output path
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --trace-level storage --trace-output /tmp/run.lct
+
+    # Implicit timestamped path under $TMPDIR
+    lmcache server \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --trace-level storage
+    # → INFO log: "trace recording enabled (level=storage); no
+    #   --trace-output given, writing to
+    #   /tmp/lmcache-trace-<pid>-<UTC>.lct"
+
+Drive traffic through the server as usual (vLLM requests, benchmark
+scripts, etc.). The trace file is closed cleanly on ``SIGTERM`` via
+the EventBus stop path — no ``--stop-tracing`` command needed.
+
+**What is captured:**
+
+- The fully-qualified name of every decorated ``StorageManager`` call
+  (e.g. ``StorageManager.reserve_write``,
+  ``StorageManager.submit_prefetch_task``).
+- Each call's input arguments (``keys``, ``layout_desc``, ``mode``,
+  ``extra_count``, ``external_request_id``, …).
+- Wall-clock and monotonic timestamps per call.
+- A header with the file format version, trace schema version, start
+  timestamps, and a SHA-256 digest of the active
+  ``StorageManagerConfig`` so replay can flag mismatched
+  configurations.
+
+**What is not captured:**
+
+- **KV tensor bytes.** Replay exercises bookkeeping and controller
+  logic; payloads at replay time are zeros. The trace file stays
+  bounded even for long runs.
+- Calls inside ``MPCacheServer``, the message queue, or GPU-copy code.
+  Those layers are out of scope for the ``storage`` trace level.
+
+**Overhead:**
+
+- Off: a single boolean check per ``StorageManager`` call. Effectively free.
+- On: encoding and file I/O happen on the EventBus drain thread, off
+  the request path. In practice this has no visible impact on
+  request latency.
+
+Inspecting a Trace
+------------------
+
+Before replaying, ``lmcache trace info`` prints a one-screen summary:
+
+.. code-block:: bash
+
+    lmcache trace info /tmp/run.lct
+
+.. code-block:: text
+
+    Trace file: /tmp/run.lct
+      level:                storage
+      format_version:       1
+      trace_schema_version: 1
+      duration:             226.691s
+      sm_config_digest:     0f685d8a...
+      total_records:        1318
+      ops:
+        lmcache.v1.distributed.storage_manager.StorageManager.finish_read_prefetched: 133
+        lmcache.v1.distributed.storage_manager.StorageManager.finish_write: 349
+        lmcache.v1.distributed.storage_manager.StorageManager.read_prefetched_results.__enter__: 96
+        lmcache.v1.distributed.storage_manager.StorageManager.read_prefetched_results.__exit__: 96
+        lmcache.v1.distributed.storage_manager.StorageManager.reserve_write: 349
+        lmcache.v1.distributed.storage_manager.StorageManager.submit_prefetch_task: 295
+
+Use this to sanity-check that the trace you intend to replay covers
+the expected operation mix and duration.
+
+Replaying a Trace
+-----------------
+
+``lmcache trace replay FILE`` reissues every recorded call against a
+**fresh** ``StorageManager`` built from CLI flags you supply. The
+replay-side config is **chosen by you**, not copied from the
+recording. This is the feature's main value — you can compare
+different L1/L2 setups on identical input.
+
+Minimal invocation:
+
+.. code-block:: bash
+
+    lmcache trace replay /tmp/run.lct \
+        --l1-size-gb 100 --eviction-policy LRU
+
+``--l1-size-gb`` and ``--eviction-policy`` are required, just like on
+``lmcache server``. Any storage-manager flag accepted by the server
+also works here (``--l2-adapter``, ``--l1-use-lazy``,
+``--l2-store-policy``, …); run ``lmcache trace replay --help`` for the
+full list.
+
+**Pacing.** The driver always honors the recorded inter-call timings
+by sleeping to align each dispatch with its recorded ``t_mono``
+offset. There is **no** as-fast-as-possible mode: ``StorageManager``
+reads and writes are asynchronous and carry cross-call dependencies
+(for example, a retrieve may depend on an earlier L2 load completing),
+so collapsing the recorded gaps races the internal queues and causes
+non-deterministic retrieve misses. If the replay host is slower than
+the recording host, the loop simply lags the recorded schedule.
+
+**Output.** Every replay prints a terminal metrics table and writes
+a per-qualname CSV by default:
+
+.. code-block:: text
+
+    =================== Trace Replay Result ======================
+    --------------------------- Overall --------------------------
+    Trace level:                                         storage
+    Records replayed:                                       1318
+    Records skipped:                                           0
+    Records failed:                                            0
+    Replay duration (s):                                  226.69
+    Config digest:                          match (0f685d8a)
+    --------------------- Per-Op Latency (ms) --------------------
+    reserve_write count:                                     349
+    reserve_write mean:                                     0.16
+    reserve_write p50:                                      0.13
+    reserve_write p99:                                      0.93
+    ...
+
+Additional per-record output is controlled by:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Flag
+     - Purpose
+   * - ``--output-dir DIR``
+     - Directory for aggregated summary files. Default: current dir.
+   * - ``--no-csv``
+     - Skip the ``trace_replay_ops.csv`` export.
+   * - ``--json``
+     - Also write ``trace_replay_summary.json`` (per-qualname
+       count / mean / p50 / p90 / p99 / min / max, plus total
+       duration).
+   * - ``--verbose``
+     - Print one ``[N/total] OK|FAIL <qualname> (Xms)`` line per
+       record to stdout in addition to the INFO log.
+   * - ``--jsonl-out PATH``
+     - Write one JSON object per replayed record to ``PATH``
+       (``{qualname, latency_ms, failed}``) for post-hoc
+       analysis.
+   * - ``-q`` / ``--quiet``
+     - Suppress the terminal metrics table. The aggregated
+       files are still written.
+
+Even without ``--verbose``, the driver logs each dispatch at INFO:
+
+.. code-block:: text
+
+    [1/1318] OK lmcache...StorageManager.reserve_write (0.252ms)
+    [2/1318] OK lmcache...StorageManager.finish_write (0.032ms)
+    ...
+
+Progress numbers come from a cheap pre-scan of the trace file, so you
+always see ``[N/total]`` rather than just a running counter.
+
+Monitoring During Replay
+------------------------
+
+The replay driver initializes the full observability EventBus
+**before** constructing the replay-side ``StorageManager``. Internal
+events (L1/L2 lifecycle, eviction ticks, store/retrieve publishes,
+etc.) therefore flow through a live bus during replay and the
+standard subscribers — logging, metrics, OTel tracing — can attach
+to them.
+
+The same observability CLI flags that the server accepts are
+available on ``lmcache trace replay``:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Flag
+     - Effect
+   * - ``--disable-observability``
+     - Turn the EventBus off entirely. No subscribers fire.
+   * - ``--disable-metrics``
+     - Skip OTel metrics init and metrics subscribers. Useful to
+       avoid binding the Prometheus port when you only want logs.
+   * - ``--disable-logging``
+     - Skip logging subscribers.
+   * - ``--enable-tracing``
+     - Enable OTel span subscribers. Requires ``--otlp-endpoint``.
+   * - ``--otlp-endpoint URL``
+     - Export metrics/traces to an OTLP gRPC collector (e.g.
+       ``http://localhost:4317``). When unset, metrics fall back
+       to the in-process Prometheus pull endpoint.
+   * - ``--prometheus-port PORT``
+     - Port for the Prometheus ``/metrics`` endpoint in pull mode.
+       Default ``9090``.
+   * - ``--metrics-sample-rate FLOAT``
+     - Sampling rate for lifecycle histograms. Counters always
+       count all events.
+
+Typical monitoring setups:
+
+**Raw log trail (SM/L1/L2 events to stdout):**
+
+.. code-block:: bash
+
+    LMCACHE_LOG_LEVEL=DEBUG lmcache trace replay /tmp/run.lct \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --disable-metrics
+
+**Prometheus metrics in pull mode:**
+
+.. code-block:: bash
+
+    lmcache trace replay /tmp/run.lct \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --prometheus-port 9095
+    # scrape http://localhost:9095/metrics from another terminal
+
+**OTel metrics + traces to a collector:**
+
+.. code-block:: bash
+
+    lmcache trace replay /tmp/run.lct \
+        --l1-size-gb 100 --eviction-policy LRU \
+        --otlp-endpoint http://localhost:4317 \
+        --enable-tracing
+
+.. note::
+
+   The ``--trace-level`` and ``--trace-output`` flags are **recording-only**
+   and are not accepted by ``lmcache trace replay``. A replay never
+   writes a new trace file.
+
+Notes, Hints, and Caveats
+-------------------------
+
+**Retrieve misses are expected when the replay environment differs.**
+At replay start, the CLI prints a visible warning banner:
+
+.. code-block:: text
+
+    ==============================================================================
+      !! REPLAY ENVIRONMENT MISMATCH MAY CAUSE RETRIEVE MISSES !!
+    ==============================================================================
+
+Because KV payloads are not captured and the replay-side config and
+host speed may differ from recording, retrieve calls that hit at
+record time can miss at replay time — for instance, an async L2 load
+that had finished by the time the recorded retrieve was issued may
+still be in flight when the replayed retrieve fires. Treat
+retrieve-miss counts as a signal about the replay environment, **not**
+as a defect in the trace.
+
+**Config-digest mismatch is informational, not fatal.** The replay
+always runs whether the digests match or not. A mismatch simply tells
+you the replay-side ``StorageManagerConfig`` differs from what was
+recorded — often exactly what you intended (comparing two configs
+on the same trace).
+
+**Prometheus port binding.** The server's ``--prometheus-port``
+defaults to ``9090``. Running ``lmcache trace replay`` concurrently
+with the server — or running two replays at once — on the same port
+will fail. Either pass a different ``--prometheus-port`` or
+``--disable-metrics`` on the secondary runs.
+
+**Trace-recording overhead.** Recording happens on the EventBus drain
+thread, not the request-handling threads. The gate is a single
+boolean check when disabled (default), so production builds with
+recording off pay no measurable cost.
+
+**Trace files are not encrypted.** Arguments such as ``ObjectKey``
+chunk hashes are written in plaintext. Treat trace files with the
+same care as cache hash logs.
+
+**Forward compatibility.** The header carries a format version and a
+trace schema version. Readers reject files with unknown versions
+rather than silently producing garbage. Captured API surface
+changes (new arguments on a traced method, new codec tags) bump the
+schema version; framing changes bump the format version.
+
+**Extensibility.** The format is designed to accommodate future
+trace **levels** (``mq``, ``gpu``). Adding a new traced method in an
+existing level requires only decorating it on the recording side and
+registering a handler on the replay side — no format changes.
+
+See Also
+--------
+
+- :ref:`trace-recording` — the short ``Trace Recording`` section in
+  the Observability page focuses on the recording-side flags.
+- ``docs/design/v1/mp_observability/trace.md`` in the source tree —
+  full design doc: architecture, replay dispatcher, context-manager
+  pairing, stats collector, and test matrix.
diff --git a/docs/source/non_kv_cache/encoder_cache.rst b/docs/source/non_kv_cache/encoder_cache.rst
new file mode 100644
index 0000000..e3da25d
--- /dev/null
+++ b/docs/source/non_kv_cache/encoder_cache.rst
@@ -0,0 +1,177 @@
+Encoder caching
+===============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The **Encoder Cache (EC)** stores the output of a multimodal model's
+encoder stage, keyed by vLLM's per-input ``mm_hash``. When two
+requests share a multimodal input — the same image, video, or audio
+clip — the second request loads the encoder output from the cache
+and the encoder does not run.
+
+This applies to any modality vLLM exposes through its encoder-cache
+extension point: vision encoders (CLIP / ViT-style towers used for
+images and sampled video frames), audio encoders (Whisper-style
+towers used for raw waveforms), and combined-modality encoders such
+as Qwen2.5-Omni. The connector is modality-agnostic — it caches a
+tensor of shape ``[num_tokens, hidden_dim]`` keyed by ``mm_hash``,
+without knowing which encoder produced it.
+
+vLLM exposes the encoder-cache extension point via
+``ECConnectorBase`` (vLLM v1 only). LMCache provides an
+``LMCacheECConnector`` shim on the vLLM side and an ``ECCacheEngine``
+on the LMCache side; together they back the encoder cache with any of
+LMCache's storage backends (local CPU, local disk, remote, NIXL).
+
+Enabling it
+-----------
+
+Pass ``--ec-transfer-config`` to ``vllm serve``:
+
+.. code-block:: bash
+
+   vllm serve <model> \
+       --ec-transfer-config '{
+         "ec_connector": "LMCacheECConnector",
+         "ec_role": "ec_both",
+         "ec_connector_module_path": "vllm.distributed.ec_transfer.ec_connector.lmcache_connector"
+       }'
+
+``ec_role`` choices: ``ec_producer`` (saves only), ``ec_consumer``
+(reads only), ``ec_both`` (single-instance default).
+
+Set ``LMCACHE_CONFIG_FILE`` to point at a YAML with at least one
+storage backend configured for EC:
+
+.. code-block:: yaml
+
+   chunk_size: 256
+   local_cpu: true
+   max_local_cpu_size: 2          # GiB
+   local_disk: "file:///var/lmcache/ec"
+   max_local_disk_size: 16        # GiB
+
+To size EC storage independently from the (separate) KV cache, prefix
+overrides with ``ec_`` in YAML or ``LMCACHE_EC_`` in the environment
+(e.g. ``ec_max_local_disk_size: 64`` or
+``LMCACHE_EC_MAX_LOCAL_DISK_SIZE=64``). EC and KV always run with
+**separate** ``StorageManager`` instances so one cannot evict the
+other.
+
+If you don't set ``local_disk`` (or its EC override) the engine still
+starts, but EC entries live in CPU memory only and do not survive
+process restart. Set ``local_disk`` (or ``ec_local_disk``) to a real
+path if you want cache persistence — there is no implicit on-disk
+default location.
+
+Verifying it's working
+----------------------
+
+Three independent signals:
+
+1. **vLLM metric.** ``loggers.py`` reports
+   ``MM cache hit rate: X%`` after warm requests.
+2. **LMCache log line.** Cold (first-time) requests emit
+   ``LMCache INFO: EC put: stored N bytes for mm_hash=H``. Warm
+   requests emit no ``EC put``.
+3. **On-disk file.** Under ``local_disk`` an entry of the form
+   ``<model>@1@0@<chunk_hash>@<dtype>.pt`` appears after the first
+   request and is reused thereafter. The ``@1@0@`` prefix reflects
+   sentinel ``world_size=1, worker_id=0`` in the EC cache key, so all
+   tensor-parallel ranks share one entry.
+
+Design notes (user-visible)
+---------------------------
+
+- **Cache key uses sentinel TP shape.** Encoder outputs are
+  replicated across TP ranks, so the EC key uses
+  ``world_size=1, worker_id=0`` regardless of the deployment's actual
+  TP. Concurrent puts from N ranks land on the same key with
+  identical contents.
+- **Dtype decoupled from KV quant.** The dtype field of the EC cache
+  key is the encoder output dtype (``vllm_config.model_config.dtype``),
+  not ``metadata.kv_dtype``. Changing KV quantization does not
+  invalidate EC entries.
+- **Separate StorageManager from KV.** KV and EC have very different
+  access patterns (KV chunked / layerwise / high-volume; EC
+  single-tensor / request-scoped). Sharing one allocator pool would
+  let one cache evict the other in unpredictable ways. Per-cache
+  sizing knobs (``ec_max_local_*``) are explicit instead.
+- **Connector role pinned to "worker".** vLLM's ``ECConnectorBase``
+  is dual-role (scheduler and worker). The LMCache connector calls
+  ``create_lmcache_metadata(..., role="worker")`` regardless, because
+  the scheduler-side ``has_cache_item`` needs a fully constructed
+  ``StorageManager`` and LMCache currently aborts disk-backend setup
+  when ``metadata.role == "scheduler"``.
+
+The full internal design (class layering, code paths, follow-up work)
+lives at :file:`docs/design/v1/encoder-cache.md` in the source tree.
+
+Benchmark
+---------
+
+Live measurement on a single H100 80GB with
+``Qwen/Qwen2.5-VL-7B-Instruct`` (bf16) and Big Buck Bunny (10:34,
+720p, ≈ 60 MB MP4). Same chat-completion request sent 1 cold + N
+warm times against the same vLLM server.
+
+Two configurations, varying only ``num_frames`` (how many frames vLLM
+samples from the video):
+
+.. list-table::
+   :header-rows: 1
+   :widths: 22 14 18 18 14 14
+
+   * - num_frames
+     - EC entry
+     - Cold TTFT (s)
+     - Warm TTFT mean (s)
+     - Saved
+     - Speedup
+   * - 32 (vLLM default)
+     - 34.3 MB
+     - 3.923
+     - 3.125
+     - 798 ms
+     - **1.26×**
+   * - 128
+     - 130.8 MB
+     - 5.895
+     - 3.375
+     - 2.52 s
+     - **1.75×**
+
+Speedup grows with ``num_frames`` because the encoder workload
+scales linearly with frame count while the rest of prefill (LM
+forward over the resulting multimodal tokens + the short text prompt)
+scales sublinearly. The same principle applies to other modalities:
+the win is largest when the encoder is the dominant share of prefill
+(long videos at high frame counts, long audio clips, large images at
+high resolution) and smallest when text prefill dominates.
+
+Reproducing
+~~~~~~~~~~~
+
+Server (heavier-encoder configuration):
+
+.. code-block:: bash
+
+   vllm serve <Qwen2.5-VL-7B-Instruct path> \
+       --port 8000 \
+       --gpu-memory-utilization 0.85 \
+       --max-model-len 32768 \
+       --max-num-seqs 8 \
+       --limit-mm-per-prompt '{"video": 1}' \
+       --media-io-kwargs '{"video": {"num_frames": 128}}' \
+       --enforce-eager \
+       --ec-transfer-config '{"ec_connector": "LMCacheECConnector",
+                              "ec_role": "ec_both",
+                              "ec_connector_module_path": "vllm.distributed.ec_transfer.ec_connector.lmcache_connector"}'
+
+Client: any streaming OpenAI-compatible client that re-sends the same
+multimodal payload. The benchmark measures TTFT (time to first
+token) because the encoder runs during prefill — any encoder savings
+show up there. Decode tokens-per-second is unaffected by EC.
diff --git a/docs/source/non_kv_cache/encodings.rst b/docs/source/non_kv_cache/encodings.rst
new file mode 100644
index 0000000..10de950
--- /dev/null
+++ b/docs/source/non_kv_cache/encodings.rst
@@ -0,0 +1,9 @@
+Encodings
+=========
+
+.. note::
+
+   Multiprocess (MP) support for encoding (encoder / multimodal) caching is
+   **coming soon**. The current in-process implementation is preserved in the
+   Legacy section: :doc:`/non_kv_cache/encoder_cache` and
+   :doc:`/api_reference/multimodality`.
diff --git a/docs/source/non_kv_cache/hidden_states.rst b/docs/source/non_kv_cache/hidden_states.rst
new file mode 100644
index 0000000..3360ace
--- /dev/null
+++ b/docs/source/non_kv_cache/hidden_states.rst
@@ -0,0 +1,116 @@
+Hidden states
+=============
+
+The **HiddenStateStore** caches per-token *hidden-state* tensors
+(intermediate activations from an inference forward pass) alongside
+the KV cache, keyed by the same chunk keys. It exists to support any
+system where a downstream stage needs an upstream stage's
+intermediate activations for the cached prefix and cannot
+reconstruct them from KV alone — for example a vLLM-Omni
+``thinker -> talker`` pipeline, where the talker consumes the
+thinker's hidden states for tokens whose KV the engine restored
+without re-running prefill.
+
+Without this store, restoring KV alone causes downstream stages to
+see truncated or wrong activations for the cached prefix. With it,
+the talker (or any equivalent consumer) gets a contiguous
+``[num_cached_prefix_tokens, hidden_dim]`` tensor matching the KV
+prefix LMCache restored.
+
+Enabling it
+-----------
+
+Set three keys in the LMCache YAML (``LMCACHE_CONFIG_FILE``):
+
+.. code-block:: yaml
+
+   chunk_size: 256
+
+   enable_hidden_state_cache: true
+   max_hidden_state_cpu_size: 4          # GiB, pinned CPU pool size
+   # hidden_state_layers: [0, 1]         # optional allowlist (see below)
+
+- ``enable_hidden_state_cache`` — master switch. When ``false`` (the
+  default), ``engine.hidden_state_store`` is ``None`` and integrators
+  must skip all HS APIs on that worker.
+- ``max_hidden_state_cpu_size`` — pinned-CPU pool size in GiB,
+  dedicated to hidden states. Must be ``> 0`` when the store is
+  enabled. The pool is **independent** of the KV pool; HS allocator
+  pressure never evicts KV.
+- ``hidden_state_layers`` — optional allowlist of ``layer_idx``
+  values accepted on ``store_hidden_states``. Leave unset to accept
+  all layer indices. Use this only when you know exactly which
+  hook indices the worker writes (e.g. matching a fork's hybrid
+  multimodal hook list).
+
+Using it from a worker
+----------------------
+
+The store is exposed on the engine (not as engine-level methods):
+
+.. code-block:: python
+
+   hs = engine.hidden_state_store
+   if hs is None:
+       return  # HS caching disabled; nothing to do
+
+   # Store: hidden_states corresponds to token_ids[token_offset:]
+   hs.store_hidden_states(
+       token_ids,                # full prefix (same as used for KV)
+       hidden_states,            # [len(token_ids) - token_offset, hidden_dim]
+       layer_idx=0,
+       token_offset=num_computed,  # 0 for non-incremental callers
+   )
+
+   # Retrieve: contiguous prefix tensor or None on full miss
+   restored = hs.retrieve_hidden_states(token_ids, layer_idx=0)
+
+Notes:
+
+- ``token_ids`` is always the **full** prefix so chunk keys align
+  with KV exactly. ``token_offset`` lets incremental callers (such
+  as vLLM-Omni) pass only the newly computed rows in
+  ``hidden_states`` without zero-padding the already-cached prefix.
+- ``layer_idx`` is the *storage* layer index. Callers that need
+  several intermediate tensors per request (e.g. multimodal hook
+  outputs *plus* the main text hidden state) call
+  ``store_hidden_states`` once per distinct ``layer_idx`` and
+  retrieve per layer on restore.
+- ``retrieve_hidden_states`` is **prefix-strict**: it returns the
+  longest contiguous CPU ``float32`` prefix where every chunk has
+  both KV and HS for the requested ``layer_idx``, and stops at the
+  first chunk where either is missing.
+
+Eviction model
+--------------
+
+The store implements a **coupled-but-asymmetric** eviction rule:
+
+- **KV evicted ⇒ HS evicted.** On every ``retrieve_hidden_states``
+  the store asks the KV ``StorageManager`` whether KV is still
+  present for each chunk key. If KV is gone, the orphan HS entry
+  is dropped and the returned prefix ends there.
+- **HS evicted ⇏ KV evicted.** Pressure on the HS pinned pool only
+  evicts HS entries (its own LRU), never KV.
+- **Restore stops at first missing HS or KV chunk** for the
+  requested layer.
+
+Design notes (user-visible)
+---------------------------
+
+- **Separate pinned pool from KV.** KV tensors and hidden-state
+  tensors have heterogeneous shapes and dtypes, so they get
+  independent allocators. ``max_hidden_state_cpu_size`` sizes the
+  HS pool only.
+- **Same chunk keys as KV.** The store reuses the engine's
+  ``TokenDatabase`` so HS chunks share the exact ``CacheEngineKey``
+  as the matching KV chunks. This is what enables the lazy coupled
+  eviction check.
+- **Lazy coupled-eviction check.** No callbacks or shared indices
+  are required between KV and HS — the store asks
+  ``storage_manager.contains(key)`` per chunk on retrieve. Works
+  uniformly for any backend that implements ``contains()``.
+
+The full internal design (class layering, code paths, follow-up
+work) lives at :file:`docs/design/v1/hidden_state_store.md` in the
+source tree.
diff --git a/docs/source/non_kv_cache/index.rst b/docs/source/non_kv_cache/index.rst
new file mode 100644
index 0000000..e8823a3
--- /dev/null
+++ b/docs/source/non_kv_cache/index.rst
@@ -0,0 +1,10 @@
+Non-KV Caching
+==============
+
+Caching state beyond the attention KV cache.
+
+.. toctree::
+   :maxdepth: 1
+
+   encodings
+   hidden_states
diff --git a/docs/source/production/docker_deployment.rst b/docs/source/production/docker_deployment.rst
new file mode 100644
index 0000000..738a107
--- /dev/null
+++ b/docs/source/production/docker_deployment.rst
@@ -0,0 +1,76 @@
+.. _docker_deployment:
+
+Docker deployment
+=================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/deployment`.
+
+
+**Prerequisites:** Docker Engine 27.0+
+
+See :ref:`installation_guide` for pulling images.
+
+Running the container
+---------------------
+
+.. code-block:: bash
+
+    IMAGE=<IMAGE_NAME>:<TAG>
+    docker run --runtime nvidia --gpus all \
+        --env "HF_TOKEN=<REPLACE_WITH_YOUR_HF_TOKEN>" \
+        --env "LMCACHE_CHUNK_SIZE=256" \
+        --env "LMCACHE_LOCAL_CPU=True" \
+        --env "LMCACHE_MAX_LOCAL_CPU_SIZE=5" \
+        --volume ~/.cache/huggingface:/root/.cache/huggingface \
+        --network host \
+        $IMAGE \
+        meta-llama/Llama-3.1-8B-Instruct --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+See the `docker run example <https://github.com/LMCache/LMCache/tree/dev/docker>`_ for more details.
+
+ROCm (AMD)
+----------
+
+The `AMD Infinity hub <https://hub.docker.com/r/rocm/vllm-dev>`__ for vLLM offers a prebuilt,
+optimized image for the AMD Instinct™ MI300X. See
+`LLM inference performance validation on AMD Instinct MI300X <https://rocm.docs.amd.com/en/latest/how-to/rocm-for-ai/inference/benchmark-docker/vllm.html?model=pyt_vllm_llama-3.1-8b>`__
+for full instructions.
+
+Validated environment: ``rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620``, MI300X, vLLM V1.
+
+.. code-block:: bash
+
+    docker run -it \
+        --network=host \
+        --group-add=video \
+        --ipc=host \
+        --cap-add=SYS_PTRACE \
+        --security-opt seccomp=unconfined \
+        --device /dev/kfd \
+        --device /dev/dri \
+        -v <path_to_your_models>:/app/model \
+        -e HF_HOME="/app/model" \
+        --name lmcache_rocm \
+        rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620 \
+        bash
+
+XPU (Intel)
+-----------
+
+The `Intel vLLM XPU hub <https://hub.docker.com/r/intel/vllm>`__ offers a prebuilt, optimized docker image designed for validating inference performance on the Intel GPU accelerators like ARC770, B60/B70, and future products.
+
+Validated environment: ``intel/vllm:0.17.0-xpu``, Intel B60 GPU, vLLM V1.
+
+.. code-block:: bash
+
+    docker run --privileged \
+        -it --rm --name vllm-xpu \
+        -u root \
+        --ipc=host --net=host \
+        --cap-add=ALL \
+        --device /dev/dri:/dev/dri \
+        -v /dev/dri/by-path:/dev/dri/by-path \
+        --entrypoint /bin/bash intel/vllm:0.17.0-xpu
diff --git a/docs/source/production/dynamo_coordination.rst b/docs/source/production/dynamo_coordination.rst
new file mode 100644
index 0000000..32a12bc
--- /dev/null
+++ b/docs/source/production/dynamo_coordination.rst
@@ -0,0 +1,7 @@
+Dynamo Integration
+==================
+
+.. note::
+
+   Integration with `NVIDIA Dynamo <https://github.com/ai-dynamo/dynamo>`_
+   is **coming soon**.
diff --git a/docs/source/production/index.rst b/docs/source/production/index.rst
new file mode 100644
index 0000000..9a784aa
--- /dev/null
+++ b/docs/source/production/index.rst
@@ -0,0 +1,13 @@
+Use LMCache in Production
+=========================
+
+Deploying, scaling, and operating LMCache in production.
+
+.. toctree::
+   :maxdepth: 2
+
+   /mp/deployment
+   /production/kubernetes_deployment
+   /mp/operator
+   /developer_guide/extending_lmcache/runtime_plugins
+   /production/dynamo_coordination
diff --git a/docs/source/production/kubernetes_deployment.rst b/docs/source/production/kubernetes_deployment.rst
new file mode 100644
index 0000000..cdf9c56
--- /dev/null
+++ b/docs/source/production/kubernetes_deployment.rst
@@ -0,0 +1,37 @@
+Kubernetes Deployment
+=====================
+
+For Kubernetes deployment of vLLM with LMCache integration, we recommend using the `vLLM Production Stack <https://github.com/vllm-project/production-stack>`_ project. This is a specialized production-ready implementation for K8S-native cluster-wide deployment for vllm & lmcache.
+
+For a quick start guide, please refer to the official `documentation <https://docs.vllm.ai/projects/production-stack/en/latest/getting_started/quickstart.html>`_
+
+and replace the Helm values file with (`values-05-cpu-offloading.yaml <https://github.com/vllm-project/production-stack/blob/main/tutorials/assets/values-05-cpu-offloading.yaml>`_):
+
+.. code-block:: yaml
+
+    servingEngineSpec:
+      runtimeClassName: ""
+      modelSpec:
+      - name: "mistral"
+        repository: "lmcache/vllm-openai"
+        tag: "latest"
+        modelURL: "mistralai/Mistral-7B-Instruct-v0.2"
+        replicaCount: 1
+        requestCPU: 10
+        requestMemory: "40Gi"
+        requestGPU: 1
+        pvcStorage: "50Gi"
+        pvcAccessMode:
+          - ReadWriteOnce
+        vllmConfig:
+          maxModelLen: 32000
+
+        lmcacheConfig:
+          enabled: true
+          cpuOffloadingBufferSize: "20"
+
+        hf_token: <hf-token>
+
+OR 
+
+refer to a detailed `step-by-step tutorial <https://github.com/vllm-project/production-stack/blob/main/tutorials/05-offload-kv-cache.md>`_ on how to offload KV cache with LMCache in the production stack.
diff --git a/docs/source/production/kv_cache_events.rst b/docs/source/production/kv_cache_events.rst
new file mode 100644
index 0000000..f1fed90
--- /dev/null
+++ b/docs/source/production/kv_cache_events.rst
@@ -0,0 +1,160 @@
+.. _kv_cache_events:
+
+KV Cache Events
+===============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/observability/index`.
+
+
+KV cache events are actions or lifecycle events that occur when managing the KV cache during inference. These events can be used for KV-cache-aware routing.
+
+LMCache supports KV cache events as follows:
+
+- Generates storage KV cache events
+- The events format is defined as per the `BlockStored class <https://github.com/vllm-project/vllm/blob/main/vllm/distributed/kv_events.py>`_ in vLLM
+- LMCache passes the events to SGLang or vLLM to publish them using their messaging system
+
+Prerequisites
+-------------
+
+The following prerequisites are required:
+
+.. tab-set::
+
+   .. tab-item:: vLLM
+
+      - vLLM v0.13.0+
+      - LMCache v0.3.11+
+
+   .. tab-item:: SGLang
+
+      - SGLang vx.y.z+
+      - LMCache vx.y.z+
+
+How to Generate KV Cache events
+-------------------------------
+
+.. tab-set::
+
+   .. tab-item:: vLLM
+
+      Before starting to generate KV events, you need to be aware of the following:
+
+      - You need to enable ``enable_kv_events`` for LMCache as events are not generated by default.
+      - If running more than 1 worker in vLLM, you need to use a non-default hashing algorithm (set ``pre_caching_hash_algorithm`` in LMCache) so that hashes generated per worker are the same. If not then you will have duplicate events for the same operation as events are generated per worker.
+      - LMCache sends the events to vLLM for publishing. To enable events to be published, you need to set the vLLM configuration setting ``--kv-events-config``. See `vLLM KV Events configuration <https://docs.vllm.ai/en/stable/api/vllm/config/kv_events/>`_ for more details.
+      
+      The steps that follow give an example of how KV events can be generated, published and consumed:
+
+      1. Start vLLM with LMCache and model ``Qwen/Qwen3-0.6B`` as follows:
+
+      .. code-block:: bash
+
+          LMCACHE_CONFIG_FILE=lmcache_config.yaml \
+              vllm serve Qwen/Qwen3-0.6B --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+              --disable-log-requests --no-enable-prefix-caching --kv-events-config '{"enable_kv_cache_events": "True", "publisher": "zmq", "topic": "kv-events"}'
+      
+      Example of the LMCache configuration is as follows:
+      
+      .. code-block:: yaml
+
+        chunk_size: 8  # demo only; use 256 for production
+        local_cpu: true
+        enable_kv_events: true
+        pre_caching_hash_algorithm: sha256_cbor_64bit
+
+      2. To be able to process the events that are published by vLLM, you need a client that subscribes to the publisher message channel and can consume the events. vLLM provides such a client example `KV Events Subscriber <https://docs.vllm.ai/en/stable/examples/online_serving/kv_events_subscriber/>`_. Run this python script in a separate terminal.
+
+      3. Prompt the model:
+
+      .. code-block:: bash
+
+          curl http://localhost:8000/v1/completions \
+        -H "Content-Type: application/json" \
+        -d '{
+          "model": "Qwen/Qwen3-0.6B",
+          "prompt": "<|begin_of_text|><|system|>\nYou are a helpful AI assistant.\n<|user|>\nWhat is the capital of France?\n<|assistant|>",
+          "max_tokens": 100,
+          "temperature": 0.7
+        }'
+
+      4. You should receive a message in the client (that you started in step 2.) window, similar to the following:
+
+      .. code-block:: bash
+
+          Received event batch at 1765529395.2132685:
+        - BlockStored(block_hashes=[b'\x96\x95[h6\x1dE$v\x03\xe8\xf0\xc20\xcd\xe8\xa7#\x9cS\xe0\x16\xba\xab7\xf7z\x10P]\xfaT'], parent_block_hash=None, token_ids=[27, 91, 7265, 3575, 4326, 91, 1784, 91, 8948, 91, 397, 2610, 525, 264, 10950, 15235, 17847, 624, 27, 91, 872, 91, 397, 3838, 374, 279, 16158, 1685, 1370, 276, 5267, 27, 91, 77091, 91, 29], block_size=36, lora_id=None, medium='cpu')
+
+      This is the event generated after the cache store operation.
+
+   .. tab-item:: SGLang
+
+      Before starting to generate KV events, you need to be aware of the following:
+
+      - You need to enable ``enable_kv_events`` for LMCache as events are not generated by default.
+      - LMCache sends the events to SGLang for publishing. To enable events to be published, you need to set the SGLang configuration setting ``--kv-events-config``.
+      
+      The steps that follow give an example of how KV events can be generated, published and consumed:
+      
+      1. Start SGLang with LMCache and model ``Qwen/Qwen3-0.6B`` as follows:
+
+      .. code-block:: bash
+
+          export LMCACHE_CONFIG_FILE=lmcache_config.yaml
+
+          python -m sglang.launch_server \
+          --model-path Qwen/Qwen3-0.6B \
+          --enable-lmcache \
+          --kv-events-config '{"publisher": "zmq", "topic": "kv-events"}'
+
+      Example of the LMCache configuration is as follows:
+      
+      .. code-block:: yaml
+
+        chunk_size: 8  # demo only; use 256 for production
+        local_cpu: true
+        use_layerwise: true
+        max_local_cpu_size: 10  # GB
+        enable_kv_events: true
+
+      2. To be able to process the events that are published by SGLang, you need a client that subscribes to the publisher message channel and can consume the events. vLLM provides such a client example `KV Events Subscriber <https://docs.vllm.ai/en/stable/examples/online_serving/kv_events_subscriber/>`_. To use this client for SGLang, you need to remove the properties ``medium`` and ``lora_name`` from the ``BlockStored`` class definition and ``medium`` from ``BlockRemoved`` class definition. Save the changes and run this updated python script in a separate terminal.
+
+      3. Prompt the model:
+
+      .. code-block:: bash
+
+          curl http://localhost:30000/v1/chat/completions \
+          -H "Content-Type: application/json" \
+          -d '{
+            "model": "Qwen/Qwen3-0.6B",
+            "messages": [{"role": "user", "content": "Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts"}],
+            "max_tokens": 100,
+            "temperature": 0.7
+          }'
+
+
+      4. You should receive a message in the client (that you started in step 2.) window, similar to the following:
+
+      .. code-block:: bash
+
+          Received event batch at 1769014811.9058058:
+            - BlockStored(block_hashes=[-7651984371600085018], parent_block_hash=None, token_ids=[151644, 872, 198, 48, 16948, 18, 374, 279, 5535], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[1717827842932260036], parent_block_hash=-7651984371600085018, token_ids=[5535, 9471, 315, 3460, 4128, 4119, 304, 1207, 16948], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-6563676647234339623], parent_block_hash=1717827842932260036, token_ids=[16948, 4013, 11, 10004, 264, 15817, 16182, 315, 27950], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-5164197595219155465], parent_block_hash=-6563676647234339623, token_ids=[27950, 323, 20980, 8668, 18376, 15546, 151645, 198, 151644], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[8690007828157426740], parent_block_hash=-5164197595219155465, token_ids=[151644, 77091, 198, 151667, 198, 32313, 11, 279, 1196], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[5720773965762948853], parent_block_hash=8690007828157426740, token_ids=[1196, 9733, 1207, 16948, 18, 438, 279, 5535, 9471], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-4465594513801548703], parent_block_hash=5720773965762948853, token_ids=[9471, 315, 3460, 4128, 4119, 304, 279, 1207, 16948], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[4010782427232237897], parent_block_hash=-4465594513801548703, token_ids=[16948, 4013, 323, 429, 432, 5707, 264, 15817, 16182], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[8472258105533326837], parent_block_hash=4010782427232237897, token_ids=[16182, 315, 27950, 323, 20980, 8668, 18376, 15546, 4119], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-3602322156693524155], parent_block_hash=8472258105533326837, token_ids=[4119, 13, 6771, 752, 1191, 553, 48996, 279, 1207], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-6413316389463734553], parent_block_hash=-3602322156693524155, token_ids=[1207, 16948, 4013, 13, 1207, 16948, 374, 264, 4013], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-4080340760183068020], parent_block_hash=-6413316389463734553, token_ids=[4013, 315, 15235, 4119, 7881, 553, 54364, 13, 576], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[1557368444906237766], parent_block_hash=-4080340760183068020, token_ids=[576, 5535, 825, 11, 1207, 16948, 18, 11, 374], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-2282733302929094006], parent_block_hash=1557368444906237766, token_ids=[374, 12824, 279, 5535, 11, 773, 429, 594, 4396], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[8695562889830890067], parent_block_hash=-2282733302929094006, token_ids=[4396, 382, 7039, 11, 279, 1196, 6801, 311, 1414], block_size=8, lora_id=None)
+            - BlockStored(block_hashes=[-6034740625096789744], parent_block_hash=8695562889830890067, token_ids=[1414, 911, 279, 15817, 16182, 315, 27950, 323, 20980], block_size=8, lora_id=None)
+
+      This is the event generated after the cache store operation. 
\ No newline at end of file
diff --git a/docs/source/production/observability/chunk_statistics.rst b/docs/source/production/observability/chunk_statistics.rst
new file mode 100644
index 0000000..8e6b226
--- /dev/null
+++ b/docs/source/production/observability/chunk_statistics.rst
@@ -0,0 +1,381 @@
+.. _observability_chunk_statistics:
+
+Chunk Statistics
+================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+The chunk statistics feature provides insights into KV cache chunk reuse patterns, helping you understand cache efficiency and optimize your deployment.
+
+Overview
+--------
+
+Chunk statistics tracks and analyzes KV cache chunks to provide metrics on:
+
+- **Total chunks processed**: The total number of chunks that have been processed
+- **Unique chunks**: The number of distinct chunks encountered
+- **Duplicate chunks**: The number of repeated chunks
+- **Reuse rate**: The ratio of duplicate chunks to total chunks, indicating cache efficiency
+
+This information is valuable for:
+
+- Understanding cache hit patterns
+- Optimizing cache size and eviction policies
+- Analyzing workload characteristics
+- Capacity planning for production deployments
+
+Recording Strategies
+--------------------
+
+LMCache supports multiple recording strategies, each optimized for different use cases:
+
+Memory Bloom Filter Strategy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A memory-efficient strategy using Bloom filters for probabilistic duplicate detection.
+
+**Advantages:**
+
+- Low memory footprint
+- Fast lookup operations
+- Suitable for large-scale deployments
+
+**Configuration:**
+
+.. code-block:: yaml
+
+    enable_chunk_statistics: true
+    chunk_statistics_strategy: "memory_bloom_filter"
+    extra_config:
+      chunk_statistics_mem_bf_expected_chunks: 20000000  # Expected number of chunks
+      chunk_statistics_mem_bf_false_positive_rate: 0.01  # Target false positive rate
+
+**Environment Variables:**
+
+.. code-block:: bash
+
+    LMCACHE_ENABLE_CHUNK_STATISTICS=true
+    LMCACHE_CHUNK_STATISTICS_STRATEGY=memory_bloom_filter
+    LMCACHE_EXTRA_CONFIG='{"chunk_statistics_mem_bf_expected_chunks": 20000000, "chunk_statistics_mem_bf_false_positive_rate": 0.01}'
+
+File Hash Strategy
+~~~~~~~~~~~~~~~~~~
+
+A file-based strategy that writes chunk hashes to disk for exact tracking and offline analysis.
+
+**Advantages:**
+
+- Exact duplicate detection (no false positives)
+- Persistent storage for offline analysis
+- Automatic file rotation and cleanup
+
+**Configuration:**
+
+.. code-block:: yaml
+
+    enable_chunk_statistics: true
+    chunk_statistics_strategy: "file_hash"
+    extra_config:
+      chunk_statistics_file_output_dir: "/tmp/lmcache_chunk_statistics"
+      chunk_statistics_file_rotation_size: 104857600      # 100MB rotation size
+      chunk_statistics_file_max_count: 100                # Maximum number of files
+
+**Environment Variables:**
+
+.. code-block:: bash
+
+    LMCACHE_ENABLE_CHUNK_STATISTICS=true
+    LMCACHE_CHUNK_STATISTICS_STRATEGY=file_hash
+    LMCACHE_EXTRA_CONFIG='{"chunk_statistics_file_output_dir": "/tmp/lmcache_chunk_statistics", "chunk_statistics_file_rotation_size": 104857600, "chunk_statistics_file_max_count": 100}'
+
+Quick Start Guide
+-----------------
+
+Step 1: Enable Chunk Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Configure your LMCache instance with chunk statistics enabled:
+
+**Using YAML Configuration:**
+
+.. code-block:: yaml
+
+    # Enable internal API server for interacting with the chunk statistics API
+    internal_api_server_enabled: True
+    # Base port for the API server
+    # actual_port = internal_api_server_port_start + index
+    # Scheduler → 6999 + 0 = 6999
+    # Worker 0 → 6999 + 1 = 7000
+    internal_api_server_port_start: 6999
+    # Enable chunk statistics with memory bloom filter strategy
+    enable_chunk_statistics: true
+    chunk_statistics_strategy: "memory_bloom_filter"
+    chunk_statistics_auto_start_statistics: true
+
+    # Bloom filter configuration
+    extra_config:
+      chunk_statistics_mem_bf_expected_chunks: 20000000
+      chunk_statistics_mem_bf_false_positive_rate: 0.01
+
+**Using vLLM with LMCache:**
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE=lmcache.yaml \
+    PYTHONHASHSEED=0 \
+    python3 -m vllm.entrypoints.cli.main serve <model_path> \
+    --load-format dummy \
+    -tp 2 \
+    --trust-remote-code \
+    --served-model-name vllm_cpu_offload \
+    --gpu-memory-utilization 0.5 \
+    --max-num-seqs 64 \
+    --no-enable-prefix-caching \
+    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+
+Step 2: Access Statistics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieve statistics through the internal API server:
+
+.. code-block:: bash
+
+    # Get current statistics (default port: 6999 for scheduler)
+    curl http://localhost:6999/chunk_statistics/status
+
+**Example Response:**
+
+.. code-block:: json
+
+    {
+      "enabled": true,
+      "total_requests": 3,
+      "timing": {
+        "lookup_time_seconds": 0.044486284255981445,
+        "record_statistics_time_seconds": 6.246566772460938e-05,
+        "check_exit_conditions_time_seconds": 5.7220458984375e-06,
+        "total_time_seconds": 0.04455447196960449,
+        "overhead_time_seconds": 6.818771362304688e-05,
+        "overhead_percentage": 0.1530434782608696
+      },
+      "total_chunks": 12,
+      "unique_chunks": 9,
+      "duplicate_chunks": 3,
+      "reuse_rate": 0.25,
+      "async_queue": {
+        "enabled": true,
+        "capacity": 100000,
+        "current_size": 0,
+        "max_size_reached": 0,
+        "full_blocks": 0,
+        "utilization": 0.0
+      },
+      "bloom_filter": {
+        "size_mb": 11.426279067993164,
+        "hash_count": 6,
+        "item_count": 9,
+        "bits_set": 54,
+        "fill_rate": 5.633768549952377e-07,
+        "expected_elements": 10000000,
+        "false_positive_rate": 0.01
+      },
+      "timestamp": 1763026696.7670634,
+      "auto_exit_enabled": false,
+      "auto_exit_timeout_hours": 0.0,
+      "auto_exit_target_unique_chunks": null
+    }
+
+Configuration Options
+---------------------
+
+Basic Configuration
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Basic Configuration Options
+   :header-rows: 1
+   :widths: 40 20 100
+
+   * - Configuration Key
+     - Default Value
+     - Description
+   * - ``enable_chunk_statistics``
+     - ``false``
+     - Enable chunk statistics tracking
+   * - ``chunk_statistics_strategy``
+     - ``memory_bloom_filter``
+     - Recording strategy: ``memory_bloom_filter`` or ``file_hash``
+   * - ``chunk_statistics_auto_start_statistics``
+     - ``false``
+     - Automatically start statistics collection on initialization
+   * - ``chunk_statistics_auto_exit_timeout_hours``
+     - ``0.0``
+     - Auto-stop after specified hours (0 = disabled)
+   * - ``chunk_statistics_auto_exit_target_unique_chunks``
+     - ``0``
+     - Auto-stop after reaching target unique chunks (0 = disabled)
+
+Memory Bloom Filter Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Configure these options in the ``extra_config`` section:
+
+.. list-table:: Bloom Filter Configuration
+   :header-rows: 1
+   :widths: 40 20 100
+
+   * - Configuration Key
+     - Default Value
+     - Description
+   * - ``chunk_statistics_mem_bf_expected_chunks``
+     - ``20000000``
+     - Expected number of chunks for capacity planning
+   * - ``chunk_statistics_mem_bf_false_positive_rate``
+     - ``0.01``
+     - Target false positive rate (1%)
+
+File Hash Options
+~~~~~~~~~~~~~~~~~
+
+Configure these options in the ``extra_config`` section:
+
+.. list-table:: File Hash Configuration
+   :header-rows: 1
+   :widths: 40 20 100
+
+   * - Configuration Key
+     - Default Value
+     - Description
+   * - ``chunk_statistics_file_output_dir``
+     - ``/tmp/lmcache_chunk_statistics``
+     - Directory for storing chunk hash files
+   * - ``chunk_statistics_file_rotation_size``
+     - ``104857600``
+     - File size threshold for rotation (bytes, default 100MB)
+   * - ``chunk_statistics_file_max_count``
+     - ``100``
+     - Maximum number of files to keep
+
+Advanced Usage
+--------------
+
+Programmatic Control
+~~~~~~~~~~~~~~~~~~~~
+
+Control statistics collection programmatically through the internal API:
+
+.. code-block:: bash
+
+    # Get current statistics (default port: 6999 for scheduler)
+    curl http://localhost:6999/chunk_statistics/status
+
+    # Pretty print JSON output
+    curl http://localhost:6999/chunk_statistics/status | jq .
+
+    # Start statistics collection (if not auto-started)
+    curl -X POST http://localhost:6999/chunk_statistics/start
+
+    # Stop statistics collection
+    curl -X POST http://localhost:6999/chunk_statistics/stop
+
+    # Reset statistics
+    curl -X POST http://localhost:6999/chunk_statistics/reset
+
+Auto-Stop Configuration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Configure automatic stopping based on time or chunk count:
+
+.. code-block:: yaml
+    chunk_statistics_auto_exit_timeout_hours: 1.0  # Stop after 1 hour
+    chunk_statistics_auto_exit_target_unique_chunks: 100000  # Stop after 100K unique chunks
+
+Prometheus Metrics
+~~~~~~~~~~~~~~~~~~
+
+When using the internal API server, chunk statistics are exposed as Prometheus metrics:
+
+- ``lmcache_chunk_statistics_total_chunks``: Total number of chunks processed
+- ``lmcache_chunk_statistics_unique_chunks``: Number of unique chunks
+- ``lmcache_chunk_statistics_reuse_rate``: Cache reuse rate (0.0 to 1.0)
+- ``lmcache_chunk_statistics_bloom_filter_size_mb``: Bloom filter memory usage (MB)
+- ``lmcache_chunk_statistics_bloom_filter_fill_rate``: Bloom filter fill rate (0.0 to 1.0)
+- ``lmcache_chunk_statistics_file_count``: Number of hash files created
+- ``lmcache_chunk_statistics_current_file_size``: Current file size (bytes)
+
+Offline Analysis
+~~~~~~~~~~~~~~~~
+
+For the file hash strategy, you can perform detailed offline analysis of collected chunk hash data.
+
+Using the Analysis Script
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LMCache provides a comprehensive analysis script at ``examples/chunk_statistics/analyze_chunk_hashes.py`` that supports multiple analysis modes.
+
+Best Practices
+--------------
+
+1. **Choose the Right Strategy:**
+   
+   - Use **memory_bloom_filter** for real-time monitoring with minimal overhead
+   - Use **file_hash** when exact tracking is required or for offline analysis
+
+2. **Tune Bloom Filter Parameters:**
+   
+   - Set ``expected_chunks`` based on your workload size
+   - Lower ``false_positive_rate`` increases memory usage but improves accuracy
+
+3. **Monitor Memory Usage:**
+   
+   - Track ``bloom_filter_size_mb`` metric to ensure it fits in available memory
+   - Adjust ``expected_chunks`` if memory usage is too high
+
+4. **File Rotation:**
+   
+   - Configure appropriate ``file_rotation_size`` to balance file size and count
+   - Set ``file_max_count`` to prevent unlimited disk usage
+
+5. **Production Deployment:**
+   
+   - Enable auto-stop to prevent indefinite data collection
+   - Use internal API server for centralized metrics collection
+   - Integrate with your monitoring stack (Prometheus, Grafana, etc.)
+
+Troubleshooting
+---------------
+
+Statistics Not Updating
+~~~~~~~~~~~~~~~~~~~~~~~
+
+**Issue:** Statistics remain at zero or don't update.
+
+**Solutions:**
+
+- Verify ``enable_chunk_statistics`` is set to ``true``
+- Check that statistics collection is started (auto-start or manual start)
+- Ensure requests are being processed by the LMCache instance
+
+High Memory Usage
+~~~~~~~~~~~~~~~~~
+
+**Issue:** Bloom filter consuming too much memory.
+
+**Solutions:**
+
+- Reduce ``chunk_statistics_mem_bf_expected_chunks``
+- Increase ``chunk_statistics_mem_bf_false_positive_rate`` (trade accuracy for memory)
+- Consider switching to ``file_hash`` strategy
+
+File System Full
+~~~~~~~~~~~~~~~~
+
+**Issue:** Disk space exhausted with file hash strategy.
+
+**Solutions:**
+
+- Reduce ``chunk_statistics_file_max_count``
+- Decrease ``chunk_statistics_file_rotation_size``
+- Implement external log rotation or archival
diff --git a/docs/source/production/observability/frontend.rst b/docs/source/production/observability/frontend.rst
new file mode 100644
index 0000000..2a25408
--- /dev/null
+++ b/docs/source/production/observability/frontend.rst
@@ -0,0 +1,168 @@
+.. _observability_frontend:
+
+LMCache Frontend
+================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/frontend_dashboard`.
+
+
+LMCache Frontend is a monitoring and proxy service for LMCache clusters,
+providing a web interface for cluster management and HTTP request proxying
+to cluster nodes.
+
+.. image:: https://raw.githubusercontent.com/LMCache/lmcache_frontend/main/res/img.png
+   :alt: LMCache Frontend Dashboard
+   :align: center
+
+
+Features
+--------
+
+- **Cluster Monitoring**: Web-based dashboard for visualizing cluster status
+- **Request Proxying**: HTTP proxy service to forward requests to any cluster node
+- **Flexible Configuration**: Support for both IP:port and Unix domain sockets
+- **Plugin System**: Integration with LMCache plugin framework
+
+
+Installation
+------------
+
+Install from PyPI:
+
+.. code-block:: bash
+
+   pip install lmcache_frontend
+
+Or install from source:
+
+.. code-block:: bash
+
+   git clone https://github.com/LMCache/lmcache_frontend.git
+   cd lmcache_frontend
+   pip install -e .
+
+
+Quick Start
+-----------
+
+Starting the Service
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   lmcache-frontend --port 8080 --host 0.0.0.0
+
+
+Command Line Options
+^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Option
+     - Description
+   * - ``--port``
+     - Service port (default: 8000)
+   * - ``--host``
+     - Bind host address (default: 0.0.0.0)
+   * - ``--config``
+     - Path to configuration file
+   * - ``--nodes``
+     - Direct node configuration (JSON string)
+
+
+After starting the service, access the dashboard at ``http://localhost:8080/``.
+
+
+Configuration
+-------------
+
+Node Configuration
+^^^^^^^^^^^^^^^^^^
+
+Create a ``config.json`` file with node definitions:
+
+.. code-block:: json
+
+   [
+     {
+       "name": "node1",
+       "host": "127.0.0.1",
+       "port": "/tmp/lmcache_internal_api_server/socket/9090"
+     },
+     {
+       "name": "node2",
+       "host": "127.0.0.1",
+       "port": "/tmp/lmcache_internal_api_server/socket/9091"
+     }
+   ]
+
+The ``port`` field can be configured as either an integer port number or
+a string path for Unix domain sockets.
+
+
+LMCache Plugin Integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To start the frontend via the LMCache plugin framework,
+add the following to your ``lmcache.yaml``:
+
+.. code-block:: yaml
+
+   extra_config:
+     plugin.frontend.port: 8080
+   internal_api_server_enabled: True
+   internal_api_server_port_start: 9090
+   plugin_locations: ["/scripts/scheduler_lmc_frontend_plugin.py"]
+   internal_api_server_socket_path_prefix: "/tmp/lmcache_internal_api_server/socket"
+
+
+Proxying Requests
+-----------------
+
+Proxy requests using the format:
+
+.. code-block:: text
+
+   /proxy/{target_host}/{target_port_or_socket}/{path}
+
+Examples:
+
+.. code-block:: bash
+
+   # Proxy to a Unix socket
+   curl "http://localhost:8080/proxy/localhost/%252Ftmp%252Flmcache_internal_api_server%252Fsocket_8081/metrics"
+
+   # Proxy a POST request
+   curl -X POST http://localhost:9090/proxy/localhost/8081/run_script \
+       -F "script=@/root/scratch.py"
+
+
+Contributing
+------------
+
+LMCache Frontend is an open-source project and we welcome contributions
+from the community! Whether you want to fix bugs, add new features,
+improve documentation, or share ideas, your contributions are appreciated.
+
+Ways to contribute:
+
+- **Report Issues**: Found a bug or have a feature request?
+  Open an issue on GitHub.
+- **Submit Pull Requests**: Fork the repository, make your changes,
+  and submit a PR.
+- **Improve Documentation**: Help us make the docs clearer and more helpful.
+- **Share Feedback**: Let us know how you're using LMCache Frontend
+  and what could be improved.
+
+Join us in making LMCache Frontend better for everyone!
+
+
+More Information
+----------------
+
+For more details, visit the
+`LMCache Frontend GitHub repository <https://github.com/LMCache/lmcache_frontend>`_.
diff --git a/docs/source/production/observability/health_monitor.rst b/docs/source/production/observability/health_monitor.rst
new file mode 100644
index 0000000..0ac4b85
--- /dev/null
+++ b/docs/source/production/observability/health_monitor.rst
@@ -0,0 +1,188 @@
+.. _observability_health_monitor:
+
+Health Monitor
+==============
+
+LMCache includes a comprehensive health monitoring framework that continuously monitors the health of the cache engine and its components. This feature is essential for production deployments to detect and respond to failures in remote storage backends.
+
+Overview
+--------
+
+The Health Monitor provides:
+
+- **Automatic health checks**: Periodically monitors the health of all registered components
+- **Extensible framework**: Easily add custom health checks for new components
+- **Remote backend monitoring**: Built-in support for monitoring remote storage backends via ping
+- **Degraded mode support**: Automatically blocks operations when the system is unhealthy
+- **Prometheus metrics integration**: Health status exposed via metrics endpoint
+
+Architecture
+------------
+
+The health monitoring system consists of three main components:
+
+1. **HealthCheck (Abstract Base Class)**
+   
+   Base class for individual health checks. Each health check represents one aspect of system health.
+
+2. **HealthMonitor**
+   
+   The central monitor that orchestrates all health checks. It runs in a background thread and periodically executes all registered health checks.
+
+3. **RemoteBackendHealthCheck**
+   
+   Built-in health check for remote storage backends. It pings the remote connector to verify connectivity.
+
+Auto-Discovery
+--------------
+
+The Health Monitor uses an auto-discovery mechanism to find and instantiate health checks:
+
+1. At startup, the monitor scans the ``lmcache.v1.health_monitor.checks`` package
+2. All classes that inherit from ``HealthCheck`` are discovered
+3. Each check's ``create_from_engine()`` method is called to create instances
+4. The instances are registered with the monitor
+
+This design allows you to add new health checks by simply creating a new module in the checks package.
+
+Configuration
+-------------
+
+Health monitor configuration is done through the ``extra_config`` section of your LMCache configuration:
+
+.. list-table:: Health Monitor Configuration Options
+   :header-rows: 1
+   :widths: 40 20 100
+
+   * - Configuration Key
+     - Default Value
+     - Description
+   * - ``ping_interval``
+     - ``30.0``
+     - Interval (in seconds) between health check cycles
+   * - ``ping_timeout``
+     - ``5.0``
+     - Timeout (in seconds) for each ping operation
+   * - ``get_blocking_failed_threshold``
+     - ``10``
+     - Max number of get_blocking failed count in check interval
+   * - ``waiting_time_for_recovery``
+     - ``300.0``
+     - Waiting time (in seconds) for recovery if get_blocking failed
+
+
+How It Works
+------------
+
+Runtime Behavior
+~~~~~~~~~~~~~~~~
+
+The health monitor runs in a background thread:
+
+1. Every ``ping_interval`` seconds, all health checks are executed
+2. If any check fails, the system is marked as unhealthy
+3. When unhealthy, store/retrieve operations are blocked with a warning log
+4. Once all checks pass again, the system is marked as healthy and operations resume
+
+Initialization Failure Handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When initialization or post-initialization fails irrecoverably:
+
+1. The system is marked with ``_init_failed = True``
+2. ``is_healthy()`` method returns ``False`` permanently
+3. Health monitoring thread will not start (if initialization fails before it starts)
+4. The system operates in degraded mode (recompute-only)
+
+This ensures that irrecoverable initialization errors don't cause cascading failures
+and the system can gracefully fall back to recomputation.
+
+Graceful Degradation
+~~~~~~~~~~~~~~~~~~~~
+
+When the health monitor detects an unhealthy state:
+
+- **Store operations**: Skipped with a warning message
+- **Retrieve operations**: Return empty results with a warning message
+- **Lookup operations**: Return 0 (no cache hits) with a warning message
+
+This prevents cascading failures when remote backends are unavailable.
+
+Built-in Health Checks
+----------------------
+
+RemoteBackendHealthCheck
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This check monitors the connectivity to remote storage backends (e.g., Redis, Valkey).
+
+**What it checks:**
+
+- Pings the remote connector to verify it's reachable
+- Measures ping latency
+- Reports error codes for failures
+
+**When it's active:**
+
+- Only when a remote backend is configured (``remote_url`` is set)
+- Only if the connector supports the ``ping()`` operation
+
+**Metrics reported:**
+
+- ``lmcache:remote_ping_latency``: Latest ping latency (milliseconds)
+- ``lmcache:remote_ping_error_code``: Latest error code (0 = success)
+- ``lmcache:remote_ping_errors``: Total number of ping errors
+- ``lmcache:remote_ping_successes``: Total number of successful pings
+
+Prometheus Metrics
+------------------
+
+The health monitor exposes metrics through the Prometheus endpoint:
+
+.. list-table:: Health Monitor Metrics
+   :header-rows: 1
+   :widths: 40 15 55
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:is_healthy``
+     - Gauge
+     - Overall system health status (1 = healthy, 0 = unhealthy)
+   * - ``lmcache:remote_ping_latency``
+     - Gauge
+     - Latest ping latency to remote backends (milliseconds)
+   * - ``lmcache:remote_ping_error_code``
+     - Gauge
+     - Latest ping error code (0 = success, -1 = timeout, -2 = generic error)
+   * - ``lmcache:remote_ping_errors``
+     - Counter
+     - Total number of ping errors to remote backends
+   * - ``lmcache:remote_ping_successes``
+     - Counter
+     - Total number of successful pings to remote backends
+
+Error Codes
+-----------
+
+The health check system uses the following error codes:
+
+.. list-table:: Health Check Error Codes
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Code
+     - Description
+   * - ``0``
+     - Success - the health check passed
+   * - ``-1``
+     - Timeout - the ping operation exceeded the configured timeout
+   * - ``-2``
+     - Generic error - an unexpected error occurred during the health check
+
+Extending the Health Monitor
+----------------------------
+
+You can add custom health checks by creating a new module in the ``lmcache/v1/health_monitor/checks/`` directory.
+
+The custom check will be automatically discovered and registered when LMCache starts.
diff --git a/docs/source/production/observability/index.rst b/docs/source/production/observability/index.rst
new file mode 100644
index 0000000..e546ac5
--- /dev/null
+++ b/docs/source/production/observability/index.rst
@@ -0,0 +1,20 @@
+.. _observability:
+
+Observability
+=============
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance. For the MP mode equivalent of this page, see :doc:`/mp/observability/index`.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   vllm_endpoint
+   internal_api_server
+   metrics
+   chunk_statistics
+   health_monitor
+   periodic_thread_api
+   frontend
diff --git a/docs/source/production/observability/internal_api_server.rst b/docs/source/production/observability/internal_api_server.rst
new file mode 100644
index 0000000..10c51e4
--- /dev/null
+++ b/docs/source/production/observability/internal_api_server.rst
@@ -0,0 +1,70 @@
+.. _observability_internal_api_server:
+
+Internal API Server Metrics
+====================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+Another approach to retrieve LMCache metrics is to use the internal API server.
+
+Overview
+--------
+
+The internal API server exposes Prometheus-compatible metrics endpoints in your LMCache deployment.
+
+Quick Start Guide
+-----------------
+
+Step 1: Enable Internal API Server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Configure your vLLM instance to enable the internal API server:
+
+.. code-block:: bash
+
+    LMCACHE_INTERNAL_API_SERVER_ENABLED=true \
+    vllm serve $model \
+    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+
+Step 2: Access Metrics Endpoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Retrieve metrics from the worker's endpoint:
+
+.. code-block:: bash
+
+    curl http://$IP:7000/metrics
+
+Port Configuration
+------------------
+
+The following environment variables are used implicitly with their default values:
+
+.. list-table:: Default Port Configuration
+   :header-rows: 1
+   :widths: 40 20 100
+
+   * - Environment Variable
+     - Default Value
+     - Description
+   * - ``LMCACHE_INTERNAL_API_SERVER_HOST``
+     - ``0.0.0.0``
+     - Host address for the internal API server to bind to.
+   * - ``LMCACHE_INTERNAL_API_SERVER_PORT_START``
+     - ``6999``
+     - Starting port number, e.g.:
+
+       - Scheduler: port_start + 0 (6999)
+       - Worker 0: port_start + 1 (7000)
+       - Worker 1: port_start + 2 (7001)
+
+
+Therefore, the metrics endpoint curl command above uses port 7000. 
+
+Advanced Usage
+--------------
+
+For comprehensive testing and configuration options, refer to :ref:`testing_internal_api_server` for detailed examples and best practices.
diff --git a/docs/source/production/observability/metrics.rst b/docs/source/production/observability/metrics.rst
new file mode 100644
index 0000000..69de5f9
--- /dev/null
+++ b/docs/source/production/observability/metrics.rst
@@ -0,0 +1,394 @@
+.. _observability_metrics:
+
+Metrics Reference
+=================
+
+LMCache provides comprehensive metrics via Prometheus to help you monitor performance, cache efficiency, and system health. These metrics are exposed via the vLLM ``/metrics`` endpoint when LMCache is integrated with vLLM, or via the LMCache internal API server.
+
+Available Metrics
+-----------------
+
+The following tables list all available LMCache metrics organized by category.
+
+Core Request Metrics
+~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Core Request Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:num_retrieve_requests``
+     - Counter
+     - Total number of retrieve requests sent to LMCache.
+   * - ``lmcache:num_store_requests``
+     - Counter
+     - Total number of store requests sent to LMCache.
+   * - ``lmcache:num_lookup_requests``
+     - Counter
+     - Total number of lookup requests sent to LMCache.
+
+Token Metrics
+~~~~~~~~~~~~~
+
+.. list-table:: Token Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:num_requested_tokens``
+     - Counter
+     - Total number of tokens requested for retrieval.
+   * - ``lmcache:num_hit_tokens``
+     - Counter
+     - Total number of tokens hit in LMCache during retrieval.
+   * - ``lmcache:num_stored_tokens``
+     - Counter
+     - Total number of tokens stored in LMCache.
+   * - ``lmcache:num_lookup_tokens``
+     - Counter
+     - Total number of tokens requested in lookup operations.
+   * - ``lmcache:num_lookup_hits``
+     - Counter
+     - Total number of tokens hit in lookup operations.
+   * - ``lmcache:num_vllm_hit_tokens``
+     - Counter
+     - Number of hit tokens in vLLM.
+   * - ``lmcache:num_prompt_tokens``
+     - Counter
+     - Number of prompt tokens in LMCache.
+
+Hit Rate Metrics
+~~~~~~~~~~~~~~~~
+
+.. list-table:: Hit Rate Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:retrieve_hit_rate``
+     - Gauge
+     - The hit rate for retrieve requests since last log.
+   * - ``lmcache:lookup_hit_rate``
+     - Gauge
+     - The hit rate for lookup requests since last log.
+   * - ``lmcache:request_cache_hit_rate``
+     - Histogram
+     - Distribution of hit rates per request.
+   * - ``lmcache:lookup_0_hit_requests``
+     - Counter
+     - Total number of lookup requests with zero hits.
+
+Performance & Latency Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Performance & Latency Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:time_to_retrieve``
+     - Histogram
+     - Time taken to retrieve from the cache (seconds).
+   * - ``lmcache:time_to_store``
+     - Histogram
+     - Time taken to store to the cache (seconds).
+   * - ``lmcache:time_to_lookup``
+     - Histogram
+     - Time taken to perform a lookup in the cache (seconds).
+   * - ``lmcache:retrieve_speed``
+     - Histogram
+     - Retrieval speed (tokens per second).
+   * - ``lmcache:store_speed``
+     - Histogram
+     - Storage speed (tokens per second).
+   * - ``lmcache:num_slow_retrieval_by_time``
+     - Counter
+     - Total number of slow retrievals exceeding the time threshold.
+   * - ``lmcache:num_slow_retrieval_by_speed``
+     - Counter
+     - Total number of slow retrievals below the speed threshold.
+
+Detailed Profiling Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Profiling Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:retrieve_process_tokens_time``
+     - Histogram
+     - Time to process tokens in retrieve (seconds).
+   * - ``lmcache:retrieve_broadcast_time``
+     - Histogram
+     - Time to broadcast memory objects in retrieve (seconds).
+   * - ``lmcache:retrieve_to_gpu_time``
+     - Histogram
+     - Time to move data to GPU in retrieve (seconds).
+   * - ``lmcache:store_process_tokens_time``
+     - Histogram
+     - Time to process tokens in store (seconds).
+   * - ``lmcache:store_from_gpu_time``
+     - Histogram
+     - Time to move data from GPU in store (seconds).
+   * - ``lmcache:store_put_time``
+     - Histogram
+     - Time to put data to storage in store (seconds).
+   * - ``lmcache:remote_backend_batched_get_blocking_time``
+     - Histogram
+     - Time spent waiting for data from remote backend (seconds).
+   * - ``lmcache:instrumented_connector_batched_get_time``
+     - Histogram
+     - Time spent in the connector layer (seconds).
+
+Cache Usage & Lifecycle Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Cache Usage Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:local_cache_usage``
+     - Gauge
+     - Local cache usage in bytes.
+   * - ``lmcache:remote_cache_usage``
+     - Gauge
+     - Remote cache usage in bytes.
+   * - ``lmcache:local_storage_usage``
+     - Gauge
+     - Local storage usage in bytes.
+   * - ``lmcache:request_cache_lifespan``
+     - Histogram
+     - Distribution of request cache lifespan in minutes.
+
+Remote Backend & Network Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Remote Backend Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:num_remote_read_requests``
+     - Counter
+     - Total number of read requests to remote backends.
+   * - ``lmcache:num_remote_read_bytes``
+     - Counter
+     - Total number of bytes read from remote backends.
+   * - ``lmcache:num_remote_write_requests``
+     - Counter
+     - Total number of write requests to remote backends.
+   * - ``lmcache:num_remote_write_bytes``
+     - Counter
+     - Total number of bytes written to remote backends.
+   * - ``lmcache:remote_time_to_get``
+     - Histogram
+     - Time taken to get data from remote backends (ms).
+   * - ``lmcache:remote_time_to_put``
+     - Histogram
+     - Time taken to put data to remote backends (ms).
+   * - ``lmcache:remote_time_to_get_sync``
+     - Histogram
+     - Time taken to get data from remote backends synchronously (ms).
+   * - ``lmcache:remote_ping_latency``
+     - Gauge
+     - Latest ping latency to remote backends (ms).
+   * - ``lmcache:remote_ping_errors``
+     - Counter
+     - Total number of ping errors to remote backends.
+   * - ``lmcache:remote_ping_successes``
+     - Counter
+     - Total number of successful pings to remote backends.
+   * - ``lmcache:remote_ping_error_code``
+     - Gauge
+     - Latest ping error code to remote backends.
+
+Local CPU Backend Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Local CPU Backend Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:local_cpu_evict_count``
+     - Counter
+     - Total number of evictions in local CPU backend.
+   * - ``lmcache:local_cpu_evict_keys_count``
+     - Counter
+     - Total number of evicted keys in local CPU backend.
+   * - ``lmcache:local_cpu_evict_failed_count``
+     - Counter
+     - Total number of failed evictions in local CPU backend.
+   * - ``lmcache:local_cpu_hot_cache_count``
+     - Gauge
+     - Current number of items in the hot cache.
+   * - ``lmcache:local_cpu_keys_in_request_count``
+     - Gauge
+     - Current number of keys being processed in requests.
+
+Memory Management Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Memory Management Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:active_memory_objs_count``
+     - Gauge
+     - The number of currently active memory objects.
+   * - ``lmcache:pinned_memory_objs_count``
+     - Gauge
+     - The number of currently pinned memory objects.
+   * - ``lmcache:forced_unpin_count``
+     - Counter
+     - Total number of forced unpins due to timeout.
+   * - ``lmcache:pin_monitor_pinned_objects_count``
+     - Gauge
+     - The number of pinned objects tracked by the PinMonitor.
+
+P2P Transfer Metrics
+~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: P2P Transfer Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:num_p2p_requests``
+     - Counter
+     - Total number of P2P transfer requests.
+   * - ``lmcache:num_p2p_transferred_tokens``
+     - Counter
+     - Total number of tokens transferred via P2P.
+   * - ``lmcache:p2p_time_to_transfer``
+     - Histogram
+     - Time taken for P2P transfers (seconds).
+   * - ``lmcache:p2p_transfer_speed``
+     - Histogram
+     - P2P transfer speed (tokens per second).
+
+Health & Internal System Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Health & Internal Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:lmcache_is_healthy``
+     - Gauge
+     - Overall health status of LMCache (1 = healthy, 0 = unhealthy).
+   * - ``lmcache:interval_get_blocking_failed_count``
+     - Gauge
+     - Number of failed blocking get operations in the current interval.
+   * - ``lmcache:kv_msg_queue_size``
+     - Gauge
+     - Size of the KV message queue in the BatchedMessageSender.
+   * - ``lmcache:remote_put_task_num``
+     - Gauge
+     - Number of pending remote put tasks.
+   * - ``lmcache:storage_events_ongoing_count``
+     - Gauge
+     - Number of storage events currently in progress.
+   * - ``lmcache:storage_events_done_count``
+     - Gauge
+     - Number of storage events completed successfully.
+   * - ``lmcache:storage_events_not_found_count``
+     - Gauge
+     - Number of storage events where the requested data was not found.
+
+Chunk Statistics Metrics
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table:: Chunk Statistics Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:chunk_statistics_enabled``
+     - Gauge
+     - Whether chunk statistics collection is enabled (1 = enabled, 0 = disabled).
+   * - ``lmcache:chunk_statistics_total_requests``
+     - Gauge
+     - Total number of requests processed by chunk statistics.
+   * - ``lmcache:chunk_statistics_total_chunks``
+     - Gauge
+     - Total number of chunks processed.
+   * - ``lmcache:chunk_statistics_unique_chunks``
+     - Gauge
+     - Estimated number of unique chunks encountered.
+   * - ``lmcache:chunk_statistics_reuse_rate``
+     - Gauge
+     - Chunk reuse rate (0.0 to 1.0).
+   * - ``lmcache:chunk_statistics_bloom_filter_size_mb``
+     - Gauge
+     - Memory usage of the Bloom filter in megabytes.
+   * - ``lmcache:chunk_statistics_bloom_filter_fill_rate``
+     - Gauge
+     - Fill rate of the Bloom filter (0.0 to 1.0).
+   * - ``lmcache:chunk_statistics_file_count``
+     - Gauge
+     - Number of files created when using the ``file_hash`` strategy.
+   * - ``lmcache:chunk_statistics_current_file_size``
+     - Gauge
+     - Current size of the active statistics file in bytes.
+
+Connector Metrics
+~~~~~~~~~~~~~~~~~
+
+.. list-table:: Connector Metrics
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Metric Name
+     - Type
+     - Description
+   * - ``lmcache:scheduler_unfinished_requests_count``
+     - Gauge
+     - Current count of unfinished requests in the scheduler.
+   * - ``lmcache:connector_load_specs_count``
+     - Gauge
+     - Number of load specifications currently in the connector.
+   * - ``lmcache:connector_request_trackers_count``
+     - Gauge
+     - Number of active request trackers in the connector.
+   * - ``lmcache:connector_kv_caches_count``
+     - Gauge
+     - Number of KV caches currently managed by the connector.
+   * - ``lmcache:connector_layerwise_retrievers_count``
+     - Gauge
+     - Number of layer-wise retrievers active in the connector.
+   * - ``lmcache:connector_invalid_block_ids_count``
+     - Gauge
+     - Number of invalid block IDs encountered by the connector.
+   * - ``lmcache:connector_requests_priority_count``
+     - Gauge
+     - Number of requests prioritized by the connector.
diff --git a/docs/source/production/observability/periodic_thread_api.rst b/docs/source/production/observability/periodic_thread_api.rst
new file mode 100644
index 0000000..5a4957b
--- /dev/null
+++ b/docs/source/production/observability/periodic_thread_api.rst
@@ -0,0 +1,180 @@
+.. _observability_periodic_thread_api:
+
+Periodic Thread Monitoring API
+==============================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+This document describes the Periodic Thread Monitoring API feature introduced
+in LMCache.
+
+Overview
+--------
+
+The Periodic Thread Monitoring API provides HTTP endpoints to monitor and
+inspect the status of all periodic background threads running in the LMCache
+system. This is useful for debugging, health checking, and operational
+monitoring.
+
+API Endpoints
+-------------
+
+Three API endpoints are available under the internal API server:
+
+GET /periodic-threads
+~~~~~~~~~~~~~~~~~~~~~
+
+Returns information about all registered periodic threads.
+
+**Query Parameters:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 15 65
+
+   * - Parameter
+     - Default
+     - Description
+   * - ``level``
+     - (none)
+     - Filter by thread level (``critical``, ``high``, ``medium``, ``low``)
+   * - ``running_only``
+     - ``false``
+     - Only show running threads
+   * - ``active_only``
+     - ``false``
+     - Only show active threads
+
+**Response Example:**
+
+.. code-block:: json
+
+    {
+      "summary": {
+        "total_count": 5,
+        "running_count": 3,
+        "active_count": 3,
+        "by_level": {
+          "critical": {"total": 1, "running": 1, "active": 1},
+          "high": {"total": 2, "running": 1, "active": 1},
+          "medium": {"total": 1, "running": 1, "active": 1},
+          "low": {"total": 1, "running": 0, "active": 0}
+        }
+      },
+      "threads": [
+        {
+          "name": "pin_monitor",
+          "level": "high",
+          "is_running": true,
+          "is_active": true,
+          "last_run_time": 1706000000.0,
+          "last_run_ago": "2.5s"
+        }
+      ]
+    }
+
+GET /periodic-threads/{thread_name}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Returns detailed information about a specific periodic thread.
+
+**Response Example:**
+
+.. code-block:: json
+
+    {
+      "name": "pin_monitor",
+      "level": "high",
+      "is_running": true,
+      "is_active": true,
+      "last_run_time": 1706000000.0,
+      "last_run_ago": "2.5s",
+      "interval": 1.0,
+      "total_runs": 100,
+      "failed_runs": 0
+    }
+
+GET /periodic-threads-health
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Quick health check for periodic threads. Returns whether all critical
+and high-level threads are active.
+
+**Response Example:**
+
+.. code-block:: json
+
+    {
+      "healthy": true,
+      "unhealthy_count": 0,
+      "unhealthy_threads": []
+    }
+
+Thread Levels
+-------------
+
+Periodic threads are categorized by importance level:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Level
+     - Description
+   * - ``critical``
+     - Essential for system operation
+   * - ``high``
+     - Important for performance
+   * - ``medium``
+     - Standard background tasks
+   * - ``low``
+     - Optional/auxiliary tasks
+
+The health check endpoint specifically monitors ``critical`` and ``high``
+level threads to determine system health.
+
+IrrecoverableException Handling
+-------------------------------
+
+Periodic threads now properly handle ``IrrecoverableException``. When such an
+exception is raised during thread execution:
+
+- The exception is logged with full traceback
+- The thread run is marked as failed
+- The thread **stops its execution loop** instead of continuing
+
+This prevents threads from endlessly retrying operations that cannot succeed.
+
+Usage Examples
+--------------
+
+Check Overall Thread Health
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    curl http://localhost:8080/periodic-threads-health
+
+List All Running Threads
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    curl "http://localhost:8080/periodic-threads?running_only=true"
+
+Get Critical Threads Only
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    curl "http://localhost:8080/periodic-threads?level=critical"
+
+Check Specific Thread Status
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    curl http://localhost:8080/periodic-threads/pin_monitor
diff --git a/docs/source/production/observability/vllm_endpoint.rst b/docs/source/production/observability/vllm_endpoint.rst
new file mode 100644
index 0000000..3f091c5
--- /dev/null
+++ b/docs/source/production/observability/vllm_endpoint.rst
@@ -0,0 +1,199 @@
+.. _observability_vllm_endpoint:
+
+Metrics by vLLM API
+==========================================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+LMCache provides detailed metrics via a Prometheus endpoint, allowing for in-depth monitoring of cache performance and behavior.
+This section outlines how to enable and configure observability from embedded vLLM ``/metrics`` API endpoint.
+
+
+Quick Start Guide
+-----------------
+
+1) On vLLM/LMCache side
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In v1, vLLM and LMCache run in separate processes, so you have to use multi‑process Prometheus.
+
+The ``PROMETHEUS_MULTIPROC_DIR`` environment variable must be the same in both processes, as a IPC directory.
+
+.. code-block:: bash
+
+   PROMETHEUS_MULTIPROC_DIR=/tmp/lmcache_prometheus \
+   #.. other environment variables \
+   vllm serve $MODEL -port 8000 ...
+
+Once the HTTP server is running, you can access the LMCache metrics at the ``/metrics`` endpoint.
+
+.. code-block:: bash
+
+   curl http://$<vllm-worker-ip>:8000/metrics | grep lmcache
+
+   # Replace $IP with the IP address of a vLLM worker
+
+
+And you will also find some ``.db`` files in the ``$PROMETHEUS_MULTIPROC_DIR`` directory.
+
+
+2) Prometheus Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To scrape the LMCache metrics with a Prometheus server, add the following job to your ``prometheus.yml`` configuration,
+or equivalent configuration to scrape the metrics endpoint:
+
+.. code-block:: yaml
+
+   scrape_configs:
+     - job_name: 'lmcache'
+       static_configs:
+         - targets: ['<vllm-worker-ip>:8000']
+       scrape_interval: 15s
+
+Available Metrics
+-----------------
+
+LMCache exposes a variety of metrics to monitor its performance. The following table lists all available metrics organized by category:
+
+.. list-table:: LMCache Metrics
+   :header-rows: 1
+   :widths: 30 15 55
+
+   * - Metric Name
+     - Type
+     - Description
+   * - **Core Request Metrics**
+     - 
+     - 
+   * - ``lmcache:num_retrieve_requests``
+     - Counter
+     - Total number of retrieve requests
+   * - ``lmcache:num_store_requests``
+     - Counter
+     - Total number of store requests
+   * - ``lmcache:num_lookup_requests``
+     - Counter
+     - Total number of lookup requests
+   * - ``lmcache:num_requested_tokens``
+     - Counter
+     - Total number of tokens requested for retrieval
+   * - ``lmcache:num_hit_tokens``
+     - Counter
+     - Total number of cache hit tokens from retrieval
+   * - ``lmcache:num_lookup_tokens``
+     - Counter
+     - Total number of tokens requested in lookup operations
+   * - ``lmcache:num_lookup_hits``
+     - Counter
+     - Total number of tokens hit in lookup operations
+   * - ``lmcache:num_vllm_hit_tokens``
+     - Counter
+     - Number of hit tokens in vLLM
+   * - **Hit Rate Metrics**
+     - 
+     - 
+   * - ``lmcache:retrieve_hit_rate``
+     - Gauge
+     - The hit rate for retrieve requests
+   * - ``lmcache:lookup_hit_rate``
+     - Gauge
+     - The hit rate for lookup requests
+   * - **Cache Usage Metrics**
+     - 
+     - 
+   * - ``lmcache:local_cache_usage``
+     - Gauge
+     - Local cache usage in bytes
+   * - ``lmcache:remote_cache_usage``
+     - Gauge
+     - Remote cache usage in bytes
+   * - ``lmcache:local_storage_usage``
+     - Gauge
+     - Local storage usage in bytes
+   * - **Performance Metrics**
+     - 
+     - 
+   * - ``lmcache:time_to_retrieve``
+     - Histogram
+     - Time taken to retrieve from the cache (seconds)
+   * - ``lmcache:time_to_store``
+     - Histogram
+     - Time taken to store to the cache (seconds)
+   * - ``lmcache:retrieve_speed``
+     - Histogram
+     - Retrieval speed (tokens per second)
+   * - ``lmcache:store_speed``
+     - Histogram
+     - Storage speed (tokens per second)
+   * - **Remote Backend Metrics**
+     - 
+     - 
+   * - ``lmcache:num_remote_read_requests``
+     - Counter
+     - Total number of read requests to remote backends
+   * - ``lmcache:num_remote_read_bytes``
+     - Counter
+     - Total number of bytes read from remote backends
+   * - ``lmcache:num_remote_write_requests``
+     - Counter
+     - Total number of write requests to remote backends
+   * - ``lmcache:num_remote_write_bytes``
+     - Counter
+     - Total number of bytes written to remote backends
+   * - ``lmcache:remote_time_to_get``
+     - Histogram
+     - Time taken to get data from remote backends (milliseconds)
+   * - ``lmcache:remote_time_to_put``
+     - Histogram
+     - Time taken to put data to remote backends (milliseconds)
+   * - ``lmcache:remote_time_to_get_sync``
+     - Histogram
+     - Time taken to get data from remote backends synchronously (milliseconds)
+   * - **Network Monitoring Metrics**
+     - 
+     - 
+   * - ``lmcache:remote_ping_latency``
+     - Gauge
+     - Latest ping latency to remote backends (milliseconds)
+   * - ``lmcache:remote_ping_errors``
+     - Counter
+     - Number of ping errors to remote backends
+   * - ``lmcache:remote_ping_successes``
+     - Counter
+     - Number of ping successes to remote backends
+   * - ``lmcache:remote_ping_error_code``
+     - Gauge
+     - Latest ping error code to remote backends
+   * - **Local CPU Backend Metrics**
+     - 
+     - 
+   * - ``lmcache:local_cpu_evict_count``
+     - Counter
+     - Total number of evictions in local CPU backend
+   * - ``lmcache:local_cpu_evict_keys_count``
+     - Counter
+     - Total number of evicted keys in local CPU backend
+   * - ``lmcache:local_cpu_evict_failed_count``
+     - Counter
+     - Total number of failed evictions in local CPU backend
+   * - ``lmcache:local_cpu_hot_cache_count``
+     - Gauge
+     - The size of the hot cache
+   * - ``lmcache:local_cpu_keys_in_request_count``
+     - Gauge
+     - The size of the keys in request
+   * - **Memory Management Metrics**
+     - 
+     - 
+   * - ``lmcache:active_memory_objs_count``
+     - Gauge
+     - The number of active memory objects
+   * - ``lmcache:pinned_memory_objs_count``
+     - Gauge
+     - The number of pinned memory objects
+
+
diff --git a/docs/source/production/performance_tuning.rst b/docs/source/production/performance_tuning.rst
new file mode 100644
index 0000000..ed456e1
--- /dev/null
+++ b/docs/source/production/performance_tuning.rst
@@ -0,0 +1,121 @@
+.. _performance_tuning:
+
+Performance Tuning
+==================
+
+.. warning::
+
+   This page documents the behavior of LMCache's in-process mode (deprecated). Please consider using :doc:`LMCache MP mode </mp/index>` for better feature support and performance.
+
+
+This guide covers key LMCache configuration options that can help
+you optimize performance in production deployments.
+
+Minimum Retrieve Tokens
+------------------------
+
+When LMCache finds a partial KV cache hit, it loads the cached tokens
+into GPU memory to avoid recomputation. However, if only a small
+number of tokens are hit, the overhead of loading them from the
+cache may outweigh the benefit of skipping recomputation.
+
+The ``min_retrieve_tokens`` setting lets you set a threshold: if the
+number of tokens that need to be loaded is below this value, LMCache
+will skip the retrieve and let the inference engine recompute them
+instead.
+
+.. note::
+
+    Even when retrieve is skipped, LMCache still records the hit
+    tokens internally so that it does **not** re-store chunks that
+    already exist in the cache.
+
+When to Use
+~~~~~~~~~~~
+
+Consider setting ``min_retrieve_tokens`` when:
+
+- For the backend you are using, the transfer latency is noticeable
+  for small payloads.
+- Your workload has many requests with **low cache hit ratios**,
+  where recomputation is faster than cache loading.
+- You want to reduce unnecessary I/O for marginal cache hits.
+
+You can increase or decrease based on your latency observations.
+
+Configuration
+~~~~~~~~~~~~~
+
+**YAML configuration file:**
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    min_retrieve_tokens: 1024
+
+**Environment variable:**
+
+.. code-block:: bash
+
+    export LMCACHE_MIN_RETRIEVE_TOKENS=1024
+
+Working Example
+~~~~~~~~~~~~~~~
+
+1. Create an LMCache configuration file ``lmcache_config.yaml``:
+
+.. code-block:: yaml
+
+    chunk_size: 256
+    local_cpu: true
+    max_local_cpu_size: 5.0
+    min_retrieve_tokens: 1024
+
+2. Start vLLM with LMCache:
+
+.. code-block:: bash
+
+    LMCACHE_CONFIG_FILE=lmcache_config.yaml \
+        vllm serve Qwen/Qwen3-0.6B \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+        --disable-log-requests \
+        --no-enable-prefix-caching
+
+3. Send a request to populate the cache:
+
+.. code-block:: bash
+
+    curl http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "Qwen/Qwen3-0.6B",
+        "prompt": "Explain the theory of relativity.",
+        "max_tokens": 50,
+        "temperature": 0.7
+      }'
+
+4. Send a similar request that partially reuses the cached prefix:
+
+.. code-block:: bash
+
+    curl http://localhost:8000/v1/completions \
+      -H "Content-Type: application/json" \
+      -d '{
+        "model": "Qwen/Qwen3-0.6B",
+        "prompt": "Explain the theory of relativity in simple terms....",
+        "max_tokens": 50,
+        "temperature": 0.7
+      }'
+
+5. Check the server logs. If the number of loadable hit tokens is
+   below 1024, you will see a log message like:
+
+.. code-block:: text
+
+    LMCache hit tokens: 762, but need to load: 762 < min_retrieve 1024,
+    skip retrieve but record for save skip
+
+This confirms that the small cache hit was skipped in favor of
+recomputation, avoiding unnecessary transfer overhead.
diff --git a/docs/source/recipes/deepseek_v4_flash.rst b/docs/source/recipes/deepseek_v4_flash.rst
new file mode 100644
index 0000000..1b641c3
--- /dev/null
+++ b/docs/source/recipes/deepseek_v4_flash.rst
@@ -0,0 +1,107 @@
+.. _recipe_deepseek_v4_flash:
+
+DeepSeek-V4-Flash
+=================
+
+Validated models
+----------------
+
+- `deepseek-ai/DeepSeek-V4-Flash <https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `DeepSeek-V4-Flash in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``DeepseekV4ForCausalLM``).
+
+      **Status:** Validated with LMCache.
+
+      **Installing vLLM:** DeepSeek-V4-Flash needs the sparse-MLA attention
+      backends and the ``fp8_ds_mla`` KV cache kernels, so install vLLM by
+      following its own recipe rather than a bare ``pip install vllm``:
+      `vLLM DeepSeek-V4-Flash recipe
+      <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      (also mirrored at https://recipes.vllm.ai/deepseek-ai/DeepSeek-V4-Flash).
+
+      .. warning::
+
+         Use the **latest vLLM release**, not the ``main``/dev branch. The
+         current vLLM development branch is broken for DeepSeek-V4-Flash (the
+         ``fp4`` MoE experts are misdispatched and the real weights fail to
+         load). Pin to the latest tagged release as the vLLM recipe instructs.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector (8 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve deepseek-ai/DeepSeek-V4-Flash \
+             --tensor-parallel-size 8 \
+             --enable-expert-parallel \
+             --kv-cache-dtype fp8_ds_mla \
+             --trust-remote-code \
+             --tokenizer-mode deepseek_v4 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      ``--kv-cache-dtype fp8_ds_mla`` and ``--tokenizer-mode deepseek_v4`` are
+      required for this model; ``--enable-expert-parallel`` distributes the MoE
+      experts across the tensor-parallel ranks. Adjust
+      ``--tensor-parallel-size`` to match your hardware. For the generic
+      LMCache + vLLM wiring (ports, remote hosts), see
+      :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+- **Requires the latest vLLM release.** The vLLM dev branch is currently broken
+  for this model (see the warning above) -- use a tagged release installed via
+  the vLLM recipe.
+- **Sparse-MLA hybrid KV cache.** DeepSeek-V4-Flash interleaves several KV
+  cache groups with different block geometries (the compressed MLA latents are
+  stored as ``fp8``/``uint8`` while the sparse-attention indexer groups are
+  ``float32``), so the groups do not share a single block size. LMCache stores
+  and retrieves each group in its own block size; no extra flags are required
+  beyond ``--kv-cache-dtype fp8_ds_mla``.
diff --git a/docs/source/recipes/devstral.rst b/docs/source/recipes/devstral.rst
new file mode 100644
index 0000000..2479495
--- /dev/null
+++ b/docs/source/recipes/devstral.rst
@@ -0,0 +1,80 @@
+.. _recipe_devstral:
+
+Mistral / Devstral
+==================
+
+Validated models
+----------------
+
+- `mistralai/Devstral-2-123B-Instruct-2512 <https://huggingface.co/mistralai/Devstral-2-123B-Instruct-2512>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `Mistral / Devstral in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``MistralForCausalLM``).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector:
+
+      .. code-block:: bash
+
+         vllm serve mistralai/Devstral-2-123B-Instruct-2512 \
+             --tensor-parallel-size 2 \
+             --enable-auto-tool-choice \
+             --tool-call-parser mistral \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
diff --git a/docs/source/recipes/gemma3.rst b/docs/source/recipes/gemma3.rst
new file mode 100644
index 0000000..0d81550
--- /dev/null
+++ b/docs/source/recipes/gemma3.rst
@@ -0,0 +1,95 @@
+.. _recipe_gemma3:
+
+Gemma 3
+=======
+
+Validated models
+----------------
+
+- `google/gemma-3-4b-it <https://huggingface.co/google/gemma-3-4b-it>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `Gemma 3 in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#multimodal-language-models>`_
+      (architecture ``Gemma3ForConditionalGeneration``).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector:
+
+      .. code-block:: bash
+
+         vllm serve google/gemma-3-4b-it \
+             --tensor-parallel-size 1 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Gemma 3 interleaves local (sliding-window) and global (full) attention
+      layers, so vLLM keeps its **hybrid KV cache manager** on and exposes
+      multiple KV cache groups. LMCache stores and retrieves all of them through
+      its hybrid memory allocator support -- ``LMCacheMPConnector`` advertises
+      ``SupportsHMA``, so vLLM does not auto-disable the hybrid manager and no
+      extra configuration is required.
+
+      ``google/gemma-3-4b-it`` is a gated model; authenticate with the Hugging
+      Face Hub (e.g. set ``HF_TOKEN``) before serving. Adjust
+      ``--tensor-parallel-size`` to match your hardware. For the generic LMCache
+      + vLLM wiring (ports, remote hosts), see
+      :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Not validated.
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+- **Gated model.** ``google/gemma-3-4b-it`` requires accepting the license on
+  Hugging Face and authenticating (e.g. ``HF_TOKEN``) before it can be served.
+- **Hybrid attention.** Gemma 3 is a hybrid (sliding-window + full-attention)
+  model. LMCache transfers every KV cache group via its hybrid memory allocator
+  support, so caching works transparently. This applies to the standard paged
+  attention used by Gemma 3; Mamba / linear-attention hybrids (whose recurrent
+  state caches LMCache cannot yet transfer) are not supported.
diff --git a/docs/source/recipes/gemma4.rst b/docs/source/recipes/gemma4.rst
new file mode 100644
index 0000000..3147e94
--- /dev/null
+++ b/docs/source/recipes/gemma4.rst
@@ -0,0 +1,100 @@
+.. _recipe_gemma4:
+
+Gemma 4
+=======
+
+Validated models
+----------------
+
+- `google/gemma-4-31B-it <https://huggingface.co/google/gemma-4-31B-it>`_
+- `google/gemma-4-12B-it <https://huggingface.co/google/gemma-4-12B-it>`_
+- `google/gemma-4-E4B-it <https://huggingface.co/google/gemma-4-E4B-it>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `Gemma 4 in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#multimodal-language-models>`_
+      (architectures ``Gemma4ForConditionalGeneration`` for 31B/E4B and
+      ``Gemma4UnifiedForConditionalGeneration`` for 12B).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector:
+
+      .. code-block:: bash
+
+         vllm serve google/gemma-4-31B-it \
+             --tensor-parallel-size 2 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      The smaller ``google/gemma-4-12B-it`` and ``google/gemma-4-E4B-it`` run on
+      a single GPU:
+
+      .. code-block:: bash
+
+         vllm serve google/gemma-4-12B-it \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+- **Hybrid KV cache with heterogeneous block sizes.** Gemma 4 interleaves
+  sliding-window and full-attention layers whose head dimensions differ
+  (sliding 256, full 512), so vLLM unifies the physical page size by giving the
+  two attention types different ``block_size``\ s (e.g. ``google/gemma-4-E4B-it``:
+  sliding 32, full 16). LMCache stores and retrieves each KV cache group in its
+  own block size; no extra flags are required.
+- **Cross-layer KV sharing.** ``google/gemma-4-E4B-it`` reuses some layers' KV
+  caches across layers. LMCache stores the cache-owning layers only; the sharing
+  layers' KV lives in the same blocks and is restored automatically.
diff --git a/docs/source/recipes/glm5_2.rst b/docs/source/recipes/glm5_2.rst
new file mode 100644
index 0000000..3b45c6e
--- /dev/null
+++ b/docs/source/recipes/glm5_2.rst
@@ -0,0 +1,105 @@
+.. _recipe_glm5_2:
+
+GLM 5.1/5.2
+===========
+
+A large Mixture-of-Experts model using **Dynamic Sparse Attention (DSA)**, shared
+by the **GLM-5.1 / GLM-5.2** series. Like DeepSeek-V4-Flash, the sparse-attention path
+splits the model's layers into more than one KV cache group; the
+``LMCacheMPConnector`` stores and retrieves each group in its own block size, so
+KV reuse works without extra flags.
+
+Validated models
+----------------
+
+- `zai-org/GLM-5.2-FP8 <https://huggingface.co/zai-org/GLM-5.2-FP8>`_ (8 GPUs)
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `GLM-5.2 in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``GlmMoeDsaForCausalLM``). See also the
+      `vLLM GLM-5.2 recipe <https://recipes.vllm.ai/zai-org/GLM-5.2>`_.
+
+      **Status:** Validated with LMCache (vLLM 0.23.0 + LMCache 0.4.7).
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server \
+             --port 6555 \
+             --max-workers 8 \
+             --l1-size-gb 100 \
+             --eviction-policy LRU \
+             --chunk-size 1024
+
+      |
+
+      Start vLLM with the LMCache MP connector (8 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve zai-org/GLM-5.2-FP8 \
+             --tensor-parallel-size 8 \
+             --tool-call-parser glm47 \
+             --enable-auto-tool-choice \
+             --reasoning-parser glm45 \
+             --no-enable-prefix-caching \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_connector_extra_config":{"lmcache.mp.port":6555}}'
+
+      |
+
+      ``--tool-call-parser glm47``, ``--enable-auto-tool-choice``, and
+      ``--reasoning-parser glm45`` are GLM-5.2's serving requirements (see the
+      vLLM recipe). ``--no-enable-prefix-caching`` routes all KV reuse through
+      LMCache rather than vLLM's in-engine prefix cache. The server's
+      ``--port 6555`` must match ``lmcache.mp.port`` in the connector config;
+      ``--max-workers`` is set to the tensor-parallel size. Adjust
+      ``--tensor-parallel-size`` to match your hardware. For the generic
+      LMCache + vLLM wiring (ports, remote hosts), see
+      :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Not validated.
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+- **Dynamic Sparse Attention KV groups.** GLM-5.2's DSA path splits the model's
+  layers into more than one KV cache group with different block geometries.
+  LMCache stores and retrieves each group in its own block size; no extra flags
+  are required beyond the launch commands above.
diff --git a/docs/source/recipes/gpt_oss.rst b/docs/source/recipes/gpt_oss.rst
new file mode 100644
index 0000000..373fcdf
--- /dev/null
+++ b/docs/source/recipes/gpt_oss.rst
@@ -0,0 +1,93 @@
+.. _recipe_gpt_oss:
+
+gpt-oss
+=======
+
+Validated models
+----------------
+
+- `openai/gpt-oss-120b <https://huggingface.co/openai/gpt-oss-120b>`_
+- `openai/gpt-oss-20b <https://huggingface.co/openai/gpt-oss-20b>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `GPT-OSS in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``GptOssForCausalLM``).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      **gpt-oss-120b** (2 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve openai/gpt-oss-120b \
+             --tensor-parallel-size 2 \
+             --enable-auto-tool-choice \
+             --tool-call-parser openai \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **gpt-oss-20b** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve openai/gpt-oss-20b \
+             --enable-auto-tool-choice \
+             --tool-call-parser openai \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
diff --git a/docs/source/recipes/index.rst b/docs/source/recipes/index.rst
new file mode 100644
index 0000000..f7f5fab
--- /dev/null
+++ b/docs/source/recipes/index.rst
@@ -0,0 +1,22 @@
+.. _recipes:
+
+Recipes
+=======
+
+This section lists model architectures validated end-to-end with LMCache, with a
+recipe page per architecture covering only the LMCache-specific configuration
+that diverges from defaults. Engine-side documentation (how to serve the model
+itself) lives with the serving engine; recipe pages link out rather than
+duplicate.
+
+For the generic LMCache + engine wiring (ports, remote hosts, sending a first
+request), see :doc:`../getting_started/quickstart` -- recipes assume that page
+as a prerequisite.
+
+Recipes are grouped by attention architecture:
+
+.. toctree::
+   :maxdepth: 1
+
+   uniform_attention_models
+   /mp/hybrid_models
diff --git a/docs/source/recipes/llama.rst b/docs/source/recipes/llama.rst
new file mode 100644
index 0000000..bebd255
--- /dev/null
+++ b/docs/source/recipes/llama.rst
@@ -0,0 +1,132 @@
+.. _recipe_llama:
+
+Llama
+=====
+
+Validated models
+----------------
+
+- `meta-llama/Meta-Llama-3.1-8B <https://huggingface.co/meta-llama/Llama-3.1-8B>`_
+- `meta-llama/Meta-Llama-3.1-8B-Instruct <https://huggingface.co/meta-llama/Llama-3.1-8B-Instruct>`_
+- `meta-llama/Meta-Llama-3.1-70B <https://huggingface.co/meta-llama/Llama-3.1-70B>`_
+- `meta-llama/Meta-Llama-3.1-70B-Instruct <https://huggingface.co/meta-llama/Llama-3.1-70B-Instruct>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `LlamaForCausalLM in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture `LlamaForCausalLM`).
+
+      **Status:** Validated with LMCache.
+
+      Apply for access on the model card page and add your
+      `huggingface token <https://huggingface.co/docs/hub/en/security-tokens>`_
+      as an environment variable:
+
+      .. code-block:: bash 
+
+         export HUGGING_FACE_HUB_TOKEN=hf_xxxxxxxxxxxxxxxxx
+      
+      |
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Get the chat templates for tool calling by following the `Llama tool calling guide <https://docs.vllm.ai/en/latest/features/tool_calling/#llama-models-llama3_json>`_ from vLLM.
+
+      Start vLLM with the LMCache MP connector:
+
+      **Meta-Llama-3.1-8B** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve meta-llama/Meta-Llama-3.1-8B \
+             --trust-remote-code \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+      
+      **Meta-Llama-3.1-8B-Instruct** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
+             --trust-remote-code \
+             --enable-auto-tool-choice \
+             --tool-call-parser llama3_json \
+             --chat-template <path_to_llama3.1_json_template> \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Meta-Llama-3.1-70B** (4 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve meta-llama/Meta-Llama-3.1-70B \
+             --tensor-parallel-size 4 \
+             --trust-remote-code \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Meta-Llama-3.1-70B-Instruct** (4 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve meta-llama/Meta-Llama-3.1-70B-Instruct \
+             --tensor-parallel-size 4 \
+             --trust-remote-code \
+             --enable-auto-tool-choice \
+             --tool-call-parser llama3_json \
+             --chat-template <path_to_llama3.1_json_template> \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
\ No newline at end of file
diff --git a/docs/source/recipes/minimax_m2.rst b/docs/source/recipes/minimax_m2.rst
new file mode 100644
index 0000000..fbda5e0
--- /dev/null
+++ b/docs/source/recipes/minimax_m2.rst
@@ -0,0 +1,119 @@
+.. _recipe_minimax_m2:
+
+MiniMax M2 series
+=================
+
+Validated models
+----------------
+
+- `MiniMaxAI/MiniMax-M2 <https://huggingface.co/MiniMaxAI/MiniMax-M2>`_
+- `MiniMaxAI/MiniMax-M2.5 <https://huggingface.co/MiniMaxAI/MiniMax-M2.5>`_
+- `MiniMaxAI/MiniMax-M2.7 <https://huggingface.co/MiniMaxAI/MiniMax-M2.7>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `MiniMax-M2 in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``MiniMaxM2ForCausalLM``).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector:
+
+      **MiniMax-M2** (8 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve MiniMaxAI/MiniMax-M2 \
+             --tensor-parallel-size 8 \
+             --trust-remote-code \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **MiniMax-M2.5** (4 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve MiniMaxAI/MiniMax-M2.5 \
+             --tensor-parallel-size 4 \
+             --trust-remote-code \
+             --enable-auto-tool-choice \
+             --tool-call-parser minimax_m2 \
+             --reasoning-parser minimax_m2 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **MiniMax-M2.7** (4 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve MiniMaxAI/MiniMax-M2.7 \
+             --tensor-parallel-size 4 \
+             --trust-remote-code \
+             --enable-auto-tool-choice \
+             --tool-call-parser minimax_m2 \
+             --reasoning-parser minimax_m2 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Engine documentation:**
+      `MiniMax-M2 SGLang cookbook
+      <https://docs.sglang.io/cookbook/autoregressive/MiniMax/MiniMax-M2>`_,
+      `MiniMax M2.5/M2.1/M2 usage guide
+      <https://docs.sglang.io/docs/basic_usage/minimax_m2>`_.
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
diff --git a/docs/source/recipes/minimax_m3.rst b/docs/source/recipes/minimax_m3.rst
new file mode 100644
index 0000000..cc10969
--- /dev/null
+++ b/docs/source/recipes/minimax_m3.rst
@@ -0,0 +1,96 @@
+.. _recipe_minimax_m3:
+
+MiniMax M3
+==========
+
+Validated models
+----------------
+
+- `MiniMaxAI/MiniMax-M3 <https://huggingface.co/MiniMaxAI/MiniMax-M3>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `MiniMax-M3 in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``MiniMaxM3SparseForConditionalGeneration``).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector (8 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve MiniMaxAI/MiniMax-M3 \
+             --tensor-parallel-size 8 \
+             --trust-remote-code \
+             --block-size 128 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      ``--block-size 128`` is **required** for this model (see Caveats); the
+      smaller defaults fail vLLM's KV-cache init. ``--trust-remote-code`` loads
+      M3's custom architecture. Adjust ``--tensor-parallel-size`` to your
+      hardware — M3's weights need eight 140 GB-class GPUs. For the generic
+      LMCache + vLLM wiring (ports, remote hosts), see
+      :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Not validated with LMCache.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+- **Sparse attention with a lightning indexer.** M3 runs grouped-query full
+  attention plus a DeepSeek-style sparse-attention indexer. Each sparse layer
+  owns two paged caches — the main K/V (rank-5) and a key-only indexer cache
+  (rank-3) — which vLLM places in a single ``UniformTypeKVCacheSpecs`` engine
+  group. LMCache detects both layouts and stores/retrieves each as its own
+  group; the indexer keys travel with the K/V because they cannot be recomputed
+  from the cached K/V on a hit.
+- **``--block-size 128`` is required.** M3's indexer uses ``sparse_block_size =
+  128``; vLLM cannot reconcile the default block size (16) or 64 across the
+  full-attention and sparse kernels and aborts KV-cache init with
+  ``No common block size``. Use 128.
+- **LMCache chunk size must be a multiple of the block size.** The default
+  chunk size (256) already satisfies 128, so no extra flag is needed; if you
+  pass ``--chunk-size`` to the server, keep it a multiple of 128.
diff --git a/docs/source/recipes/mixtral.rst b/docs/source/recipes/mixtral.rst
new file mode 100644
index 0000000..126cd27
--- /dev/null
+++ b/docs/source/recipes/mixtral.rst
@@ -0,0 +1,92 @@
+.. _recipe_mixtral:
+
+Mixtral
+=======
+
+Validated models
+----------------
+
+- `mistralai/Mixtral-8x7B-v0.1 <https://huggingface.co/mistralai/Mixtral-8x7B-v0.1>`_
+- `mistralai/Mixtral-8x7B-Instruct-v0.1 <https://huggingface.co/mistralai/Mixtral-8x7B-Instruct-v0.1>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `MixtralForCausalLM in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture `MixtralForCausalLM`).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector:
+
+      **Mixtral-8x7B-v0.1** (4 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve mistralai/Mixtral-8x7B-v0.1 \
+             --tensor-parallel-size 4 \
+             --trust-remote-code \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+   
+      **Mixtral-8x7B-Instruct-v0.1** (4 GPUs):
+
+      .. code-block:: bash
+
+         vllm serve mistralai/Mixtral-8x7B-Instruct-v0.1 \
+             --tensor-parallel-size 4 \
+             --trust-remote-code \
+             --enable-auto-tool-choice \
+             --tool-call-parser mistral \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+      
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
\ No newline at end of file
diff --git a/docs/source/recipes/phi3.rst b/docs/source/recipes/phi3.rst
new file mode 100644
index 0000000..ca8c268
--- /dev/null
+++ b/docs/source/recipes/phi3.rst
@@ -0,0 +1,90 @@
+.. _recipe_phi3:
+
+Phi-3 / Phi-4
+=============
+
+Validated models
+----------------
+
+- `microsoft/Phi-4-mini-instruct <https://huggingface.co/microsoft/Phi-4-mini-instruct>`_
+- `microsoft/Phi-3-medium-128k-instruct <https://huggingface.co/microsoft/Phi-3-medium-128k-instruct>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `Phi3ForCausalLM in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture `Phi3ForCausalLM`).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      Start vLLM with the LMCache MP connector:
+
+      **Phi-4-mini-instruct** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve microsoft/Phi-4-mini-instruct \
+             --trust-remote-code \
+             --enable-auto-tool-choice \
+             --tool-call-parser phi4_mini_json \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Phi-3-medium-128k-instruct** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve microsoft/Phi-3-medium-128k-instruct \
+             --trust-remote-code \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+             
+      |
+      
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+   .. tab-item:: SGLang
+      
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
\ No newline at end of file
diff --git a/docs/source/recipes/qwen3.rst b/docs/source/recipes/qwen3.rst
new file mode 100644
index 0000000..02dd491
--- /dev/null
+++ b/docs/source/recipes/qwen3.rst
@@ -0,0 +1,124 @@
+.. _recipe_qwen3:
+
+Qwen3 MoE
+=========
+
+Validated models
+----------------
+
+- `Qwen/Qwen3-235B-A22B <https://huggingface.co/Qwen/Qwen3-235B-A22B>`_
+- `Qwen/Qwen3-30B-A3B <https://huggingface.co/Qwen/Qwen3-30B-A3B>`_
+- `Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 <https://huggingface.co/Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8>`_
+- `Qwen/Qwen3-Coder-30B-A3B-Instruct <https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct>`_
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `Qwen3 MoE in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``Qwen3MoeForCausalLM``).
+
+      **Status:** Validated with LMCache.
+
+      Start the LMCache MP server:
+
+      .. code-block:: bash
+
+         lmcache server --l1-size-gb 100 --eviction-policy LRU
+
+      |
+
+      **Qwen3-235B-A22B** (4 GPUs, expert parallel):
+
+      .. code-block:: bash
+
+         vllm serve Qwen/Qwen3-235B-A22B \
+             --tensor-parallel-size 4 \
+             --enable-expert-parallel \
+             --enable-auto-tool-choice \
+             --tool-call-parser hermes \
+             --reasoning-parser qwen3 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Qwen3-30B-A3B** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve Qwen/Qwen3-30B-A3B \
+             --enable-auto-tool-choice \
+             --tool-call-parser hermes \
+             --reasoning-parser qwen3 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Qwen3-Coder-480B-A35B-Instruct-FP8** (8 GPUs, expert parallel):
+
+      .. code-block:: bash
+
+         vllm serve Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 \
+             --tensor-parallel-size 8 \
+             --enable-expert-parallel \
+             --enable-auto-tool-choice \
+             --tool-call-parser qwen3_coder \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Qwen3-Coder-30B-A3B-Instruct** (1 GPU):
+
+      .. code-block:: bash
+
+         vllm serve Qwen/Qwen3-Coder-30B-A3B-Instruct \
+             --enable-auto-tool-choice \
+             --tool-call-parser qwen3_coder \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      Adjust ``--tensor-parallel-size`` to match your hardware. For the
+      generic LMCache + vLLM wiring (ports, remote hosts),
+      see :doc:`../getting_started/quickstart`.
+
+      If there are any issues with vLLM setup, please refer to the
+      `vLLM Recipes <https://docs.vllm.ai/projects/recipes/en/latest/index.html>`_
+      for more details.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not validated
+     -
+
+Caveats
+-------
+
+None known.
diff --git a/docs/source/recipes/qwen3_5.rst b/docs/source/recipes/qwen3_5.rst
new file mode 100644
index 0000000..900e486
--- /dev/null
+++ b/docs/source/recipes/qwen3_5.rst
@@ -0,0 +1,137 @@
+.. _recipe_qwen3_5:
+
+Qwen3.5 / Qwen3.6 series
+========================
+
+A hybrid architecture interleaving Mamba / Gated-DeltaNet (GDN) linear-attention
+layers with full-attention layers, shared by the **Qwen3.5 and Qwen3.6**
+series. LMCache reinterprets the recurrent state caches as opaque pages at
+registration time; see :doc:`../mp/hybrid_models` for the general handling of
+Mamba / linear-attention models.
+
+Validated models
+----------------
+
+- `Qwen/Qwen3.6-27B <https://huggingface.co/Qwen/Qwen3.6-27B>`_ (1 GPU)
+- `Qwen/Qwen3.5-0.8B <https://huggingface.co/Qwen/Qwen3.5-0.8B>`_ (1 GPU)
+
+.. tab-set::
+   :sync-group: engine
+
+   .. tab-item:: vLLM
+
+      **Engine documentation:**
+      `Qwen3.5 in vLLM supported models
+      <https://docs.vllm.ai/en/latest/models/supported_models.html#text-generation>`_
+      (architecture ``Qwen3_5ForConditionalGeneration``).
+
+      **Status:** Validated with LMCache.
+
+      Every model in this family needs the same three settings: the ``align``
+      Mamba cache mode, prefix caching, and a chunk size matched to vLLM's
+      *unified block size*. That block size is model-specific — vLLM logs
+      ``Setting attention block size to N tokens`` at startup:
+
+      .. list-table::
+         :header-rows: 1
+         :widths: 50 25 25
+
+         * - Model
+           - Unified block size ``N``
+           - GPUs
+         * - ``Qwen/Qwen3.6-27B``
+           - 784
+           - 1
+         * - ``Qwen/Qwen3.5-0.8B``
+           - 544
+           - 1
+
+      Set the LMCache server's ``--chunk-size`` to that ``N`` (or a multiple of
+      it), and vLLM's ``--max-num-batched-tokens`` to ``2N-1`` (the largest value
+      below ``2N``). ``N`` is also valid but serializes prefill under load — see
+      the note below.
+
+      **Qwen3.6-27B** (1 GPU, ``N = 784`` → ``2N-1 = 1567``):
+
+      .. code-block:: bash
+
+         lmcache server --chunk-size 784 --l1-size-gb 100 --eviction-policy LRU
+
+      .. code-block:: bash
+
+         vllm serve Qwen/Qwen3.6-27B \
+             --enable-prefix-caching \
+             --mamba-cache-mode align \
+             --max-num-batched-tokens 1567 \
+             --kv-transfer-config \
+             '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}'
+
+      |
+
+      **Qwen3.5-0.8B** (1 GPU, ``N = 544`` → ``2N-1 = 1087``): identical to the
+      above, with ``--chunk-size 544`` and ``--max-num-batched-tokens 1087``.
+
+      ``--mamba-cache-mode align`` is required (GDN does not support the
+      ``all`` mode). ``--max-num-batched-tokens`` must be in ``[N, 2N)`` (at
+      least the unified block size and below twice it) — LMCache raises at
+      engine startup otherwise. ``align`` snapshots the Mamba state at
+      scheduler-step ends on a block boundary, and the scheduler splits prefills
+      into whole ``N``-token blocks. **Prefer the maximum, ``2N-1``:** a single
+      request still advances exactly one block per step (``2N-1 < 2N``), so the
+      per-block snapshot LMCache stores is preserved, *and* the spare ``N-1``
+      budget lets decodes co-schedule with a prefill block. Setting it to exactly
+      ``N`` makes the per-step budget equal to one block, so once any request is
+      decoding (consuming ≥1 token of the budget) no new request can start
+      prefill — execution serializes to one request at a time. (Benchmarked on
+      Qwen3.6-27B: at ``N`` a cold / low-hit run ran ~7× slower with GPU batch
+      stuck at 1; ``2N-1`` restored full batching. With a warm LMCache cache
+      (~97 % hit) the gap is small since little prefill remains, but ``2N-1`` is
+      the safe default.) If vLLM reports *"max_num_seqs exceeds available Mamba
+      cache blocks"* at ``2N-1``, lower ``--max-num-seqs`` to ≤ that count (each
+      decode sequence needs one Mamba block) or raise ``--gpu-memory-utilization``.
+
+      For the generic LMCache + vLLM wiring (ports, remote hosts), see
+      :doc:`../getting_started/quickstart`.
+
+   .. tab-item:: SGLang
+
+      **Status:** Not validated with LMCache.
+
+   .. tab-item:: TRT-LLM
+
+      **Status:** Supported. See :doc:`../getting_started/quickstart` for TRT-LLM + LMCache setup.
+
+CacheBlend support
+------------------
+
+Not supported: the hybrid groups' cached pages are byte-opaque (see Caveats).
+
+Compression support
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Method
+     - Status
+     - Notes
+   * - :doc:`CacheGen <../kv_cache_optimizations/compression/cachegen>`
+     - Not supported
+     - Hybrid groups' cached pages are byte-opaque.
+
+Caveats
+-------
+
+- Generation is **not bit-exact** between a cached and a fresh run: GDN
+  backends do not support vLLM's batch-invariant mode. Expect score-level
+  equivalence, not token-level (the CI gate is the ``hma_lm_eval_qwen3_5``
+  gsm8k store-vs-retrieve comparison).
+- Cached pages for the Mamba and full-attention groups are byte-opaque views,
+  so content-aware processing does not apply, and cache entries must not be
+  shared across engines with different attention backends or kernel block
+  sizes.
+- vLLM's Mamba prefix caching in ``align`` mode is experimental.
+- ``Qwen/Qwen3.6-27B`` is a vision-language model (it loads a vision tower);
+  the LMCache validation covers **text** generation (the ``hma_lm_eval_qwen3_5``
+  gsm8k store-vs-retrieve gate). Caching of image/video KV is not validated.
diff --git a/docs/source/recipes/uniform_attention_models.rst b/docs/source/recipes/uniform_attention_models.rst
new file mode 100644
index 0000000..36f4688
--- /dev/null
+++ b/docs/source/recipes/uniform_attention_models.rst
@@ -0,0 +1,117 @@
+.. _uniform_attention_models:
+
+Uniform Attention Models
+========================
+
+Recipes for standard (uniform) attention transformer architectures validated
+end-to-end with LMCache, with a recipe page per architecture covering only the
+LMCache-specific configuration that diverges from defaults.
+
+These models use a **single attention type** across all layers, so vLLM serves
+them with one KV cache group. Models that interleave multiple attention types
+(sliding-window + full, or Mamba / linear-attention + full) are covered under
+:doc:`/mp/hybrid_models`.
+
+Recipe page contents
+--------------------
+
+Each recipe page is intentionally minimal:
+
+- **Validated models** -- exact HF repo IDs that have been tested.
+- **Engine tabs** -- one tab per serving engine (vLLM, SGLang, TRT-LLM). Each
+  tab links to the engine's own documentation for the model and shows the
+  exact ``lmcache server`` and engine launch commands. Tabs for engines that
+  are not yet validated state so explicitly.
+- **CacheBlend support** -- validation status (may be empty).
+- **Compression support** -- table of compression methods (CacheGen, etc.)
+  with per-method validation status. Extensible: new methods get a row.
+- **Caveats** -- known limitations, if any.
+
+For the generic LMCache + engine wiring (ports, remote hosts,
+sending a first request), see :doc:`../getting_started/quickstart`. Recipes assume that
+page as a prerequisite.
+
+Supported architectures
+-----------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 30 10 10 10 12
+
+   * - Model
+     - Example HF model
+     - vLLM
+     - SGLang
+     - TRT-LLM
+     - Recipe
+
+   * - MiniMax M2 series
+     - ``MiniMaxAI/MiniMax-M2``
+     - ✓
+     - —
+     - —
+     - :doc:`minimax_m2`
+
+   * - Mistral / Devstral
+     - ``mistralai/Devstral-2-123B-Instruct-2512``
+     - ✓
+     - —
+     - —
+     - :doc:`devstral`
+
+   * - Qwen3 MoE
+     - ``Qwen/Qwen3-235B-A22B``
+     - ✓
+     - —
+     - —
+     - :doc:`qwen3`
+
+   * - Llama
+     - ``meta-llama/Meta-Llama-3.1-70B-Instruct``
+     - ✓
+     - —
+     - —
+     - :doc:`llama`
+
+   * - Phi-3 / Phi-4
+     - ``microsoft/Phi-4-mini-instruct``
+     - ✓
+     - —
+     - —
+     - :doc:`phi3`
+
+   * - Mixtral
+     - ``mistralai/Mixtral-8x7B-Instruct-v0.1``
+     - ✓
+     - —
+     - —
+     - :doc:`mixtral`
+
+Legend: ``✓`` validated, ``—`` not validated. The **Model** column is the model
+family; each recipe page lists the exact vLLM architecture class it covers.
+
+Contributing a recipe
+---------------------
+
+To add a new uniform-attention architecture:
+
+1. Copy an existing page (e.g. ``minimax_m2.rst``) to
+   ``recipes/<architecture_snake_case>.rst``.
+2. Fill in **Validated models**, **Engines**, **LMCache configuration**, and
+   **Caveats**. Keep each section terse -- if a field has nothing to say, say
+   so in one line rather than padding it.
+3. Add a row to the table above and an entry to the hidden toctree below.
+
+(For models that interleave attention types, add the page under
+:doc:`/mp/hybrid_models` instead.)
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   minimax_m2
+   devstral
+   qwen3
+   llama
+   phi3
+   mixtral
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..1111263
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,94 @@
+# LMCache Examples
+
+This directory contains runnable examples organized by use case. The table below describes what each example does, its hardware requirements, and a recommended learning order for infrastructure engineers getting started with LMCache.
+
+> **Single-node vs. multi-node:** Examples marked with NIXL or UCX require a
+> high-bandwidth interconnect (NVLink or PCIe Gen4/5). Running them on a
+> single machine with two GPUs is simpler than a true multi-node setup, but
+> cross-node deployments add network configuration complexity — don't start
+> there if you're still learning the basics.
+
+---
+
+## Before You Start
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`kv_cache_calculator/`](kv_cache_calculator/) | Web UI for calculating KV cache size (GB) given model architecture, dtype, and token count. Start here to size GPU memory and cache tiers before running anything. | None (browser) |
+
+---
+
+## Tier 1 — Core Concepts (Single-Node)
+
+Focus: local caching within a single machine. No cross-node networking required.
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`kv_cache_reuse/local_backends/`](kv_cache_reuse/local_backends/) | Offload KV cache from GPU to CPU memory or local disk. Repeated requests with identical prefixes skip prefill entirely. Includes a Rust-based NVMe backend with `io_uring` support (Linux kernel 5.10+ required for `io_uring`). | 1 GPU; optional NVMe for disk path |
+| [`online_session/`](online_session/) | Measure TTFT (time-to-first-token) for cold vs. cache-hit requests. Outputs JSONL for plotting. Includes a sweep script across context lengths. | 1 GPU |
+
+---
+
+## Tier 2 — Disaggregated Prefill and Multi-Instance Sharing
+
+Focus: separating prefill from decode, and sharing KV cache across vLLM instances.
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`disagg_prefill_mp/`](disagg_prefill_mp/) | PD disaggregation via the LMCache multiprocess server. P and D exchange KV through the LMCache MP service — no direct NIXL connection required. **Recommended starting point for PD disaggregation.** | 2 GPUs |
+| [`disagg_prefill/1p1d/`](disagg_prefill/1p1d/) | PD disaggregation with direct NIXL transfer: 1 prefill server + 1 decode server + a FastAPI proxy. Includes a benchmark script with expected latency numbers. High-bandwidth interconnect (NVLink or PCIe Gen4/5) is strongly recommended — without it, KV transfer overhead may negate the gains. | 2 GPUs + [NIXL](https://github.com/ai-dynamo/nixl) |
+| [`kv_cache_reuse/share_across_instances/centralized_sharing/`](kv_cache_reuse/share_across_instances/centralized_sharing/) | Two vLLM instances share one LMCache server. A prefix computed by instance A is reused by instance B. ⚠️ Requires `PYTHONHASHSEED=0` in all processes — without this, hashes differ across processes and cache lookups silently miss. | 2 GPUs (same node) |
+| [`kv_cache_reuse/share_across_instances/p2p_sharing/`](kv_cache_reuse/share_across_instances/p2p_sharing/) | Two vLLM instances transfer KV directly peer-to-peer using NIXL and UCX RDMA (`UCX_TLS=rc`). | 2 GPUs + NIXL + UCX |
+| [`p2p/`](p2p/) | P2P KV cache sharing in multiprocess mode: each node runs an LMCache server, and a server reads a prefix it lacks directly from the peer that holds it over RDMA. A coordinator handles peer discovery. Includes single-node (debug) and multi-node setups and the logs to expect. | 2+ GPUs (single- or multi-node) + RDMA fabric |
+
+---
+
+## Tier 3 — Production Operations and Observability
+
+Focus: deploying, monitoring, and operating LMCache in production.
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`observability/`](observability/) | Full observability stack: OTel → Prometheus + Tempo → Grafana. Pre-provisioned dashboard shows cache hit rate, read/write throughput, and per-request trace waterfalls. Started with `docker compose up`. | 1 GPU + Docker |
+| [`multi_process/`](multi_process/) | Kubernetes DaemonSet YAML for deploying the LMCache server as a per-node sidecar (60 GB L1, 4 workers). Includes resource `requests`/`limits` calibrated to the L1 size. | Kubernetes cluster with GPU nodes |
+| [`kubernetes/`](kubernetes/) | `health_probe.py`: readiness/liveness probe script for LMCache in Kubernetes. Complements the DaemonSet config in `multi_process/`. | None |
+| [`chunk_statistics/`](chunk_statistics/) | Track chunk reuse rate using a memory Bloom filter or an on-disk hash log. Query via REST (`/chunk_statistics/status`). Use this to answer "does my workload benefit from caching?" before committing to a full deployment. | 1+ GPUs |
+| [`cache_controller/`](cache_controller/) | REST APIs for cache orchestration: `lookup` (which instance holds a key), `move` (migrate a hot context between instances), `pin` (prevent eviction), `clear`, and `compress`. | 1 GPU |
+| [`cache_with_configs/`](cache_with_configs/) and [`cache_interface/`](cache_interface/) | Per-request control: attach tags (`lmcache.tag.*`), set TTL (`lmcache.ttl`), or skip caching entirely (`lmcache.skip_save: true`). Essential for multi-tenant deployments. | 1 GPU |
+| [`remote_config_server/`](remote_config_server/) | Flask reference server for centralised LMCache configuration. Workers POST their current config on startup and receive overrides — useful for managing settings across a large fleet. | None |
+
+---
+
+## Tier 4 — Advanced Features and Ecosystem
+
+### Framework Integrations
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`sgl_integration/`](sgl_integration/) | Using LMCache with SGLang instead of vLLM. | 1 GPU |
+| [`frontend/`](frontend/) | Streamlit chat UI demo backed by vLLM + LMCache. Uses the ffmpeg man page as a long shared context to demonstrate TTFT reduction across turns. | 1 GPU |
+| [`disagg_prefill/xpyd/`](disagg_prefill/xpyd/) | xP + yD topology: multiple prefill servers feeding multiple decode servers. | 3+ GPUs + NIXL |
+
+### Storage Backends and Serialization
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`kv_cache_reuse/remote_backends/`](kv_cache_reuse/remote_backends/) | Remote storage backends: InfiniStore, Mooncake, S3, Valkey, Redis. Each subdirectory has its own README with backend-specific setup. | 1 GPU + respective backend |
+| [`serde/fp8/`](serde/fp8/) | Quantize KV cache to fp8 before writing to disk (L2 adapter), then dequantize on prefetch. Halves disk storage requirements. | Hopper / Ada GPU (H100, RTX 40-series) |
+| [`redis_lookup/`](redis_lookup/) | Shows the Redis key schema used by LMCache (`model@world_size@worker_id@chunk_hash`) and `redis-cli` commands for inspecting live cache entries. | Redis + 1 GPU |
+
+### Non-Prefix KV Reuse (CacheBlend)
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`blend_kv_v1/`](blend_kv_v1/) | CacheBlend v1: reuse KV cache even when the new prompt is not a prefix of the cached one (e.g., RAG with swapped documents). Requires a small patch to vLLM source. | 1 GPU (experimental) |
+| [`blend_kv/`](blend_kv/) | CacheBlend v0 (legacy): same concept using the old `lmcache_vllm` integration. Kept for reference. | 1+ GPUs (legacy) |
+
+### Developer Extensibility
+
+| Example | What it does | Hardware |
+|---------|-------------|----------|
+| [`lmc_external_l2_adapter/`](lmc_external_l2_adapter/) and [`lmc_external_native_connector/`](lmc_external_native_connector/) | Templates for writing a custom L2 storage adapter (Python) or a native C++ GPU connector plugin. | Depends on implementation |
+| [`runtime_plugins/`](runtime_plugins/) and [`mp_runtime_plugins/`](mp_runtime_plugins/) | Sidecar scripts (Python or shell) that run alongside LMCache workers: heartbeats, metric reporters, alert hooks. Filename prefix controls which role (`scheduler`, `worker_0`, `all`) runs the script. | None |
+| [`basic_check/`](basic_check/) | CLI tool for verifying storage backend health and generating test keys. Useful in CI and for on-call diagnostics. | Optional GPU |
+| [`agents/`](agents/) | Script for analyzing prefix-hash distribution of a prompt dataset. Useful for estimating cache efficiency before deployment. | None |
diff --git a/examples/agents/prefix_analysis.py b/examples/agents/prefix_analysis.py
new file mode 100644
index 0000000..6bc1f4a
--- /dev/null
+++ b/examples/agents/prefix_analysis.py
@@ -0,0 +1,471 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from collections import OrderedDict
+from typing import List, Optional, Tuple, Union
+import argparse
+import json
+
+# Third Party
+from tqdm import tqdm
+from transformers import AutoTokenizer
+import matplotlib.pyplot as plt
+import torch
+
+# Constants
+DEFAULT_TOKENIZER = "meta-llama/Llama-3.1-8B"
+DEFAULT_TOKENS_PER_GB = 8200  # Default for Llama-3.1; More details here: https://docs.lmcache.ai/getting_started/kv_cache_calculator.html
+DEFAULT_POOL_SIZES_GB: List[Union[int, float, str]] = [
+    1,
+    2,
+    4,
+    8,
+    16,
+    32,
+    50,
+    100,
+    200,
+    500,
+    "unlimited",
+]
+
+
+class LRUTokenPool:
+    """
+    Token pool with LRU eviction policy based on token count limit.
+    """
+
+    def __init__(self, max_tokens: float) -> None:
+        self.max_tokens = max_tokens
+        self.current_tokens = 0
+        self.requests: OrderedDict[int, List[int]] = OrderedDict()
+
+    def longest_prefix_len(self, tokens: List[int]) -> Tuple[int, int]:
+        """
+        Find longest prefix match and update LRU ordering.
+        For request i (1-indexed):
+        y[i] = y[i-1] + (len(tokens[i]) - max_shared_prefix(tokens[i], any previous))
+        """
+        best_len = 0
+        best_id = -1
+
+        for req_id, req_tokens in self.requests.items():
+            common_len = 0
+            for i in range(min(len(tokens), len(req_tokens))):
+                if tokens[i] == req_tokens[i]:
+                    common_len += 1
+                else:
+                    break
+
+            if common_len > best_len:
+                best_len = common_len
+                best_id = req_id
+
+        # Update LRU ordering
+        if best_id != -1:
+            self.requests.move_to_end(best_id)
+
+        return best_len, best_id
+
+    def longest_common_substring(
+        self,
+        request_id: int,
+        token_tensor: torch.Tensor,
+        tokens: List[int],
+        *,
+        chunk_len: int = 4,
+        stride_r: int = 4,
+        chunk_batch: int = 512,
+    ) -> Tuple[int, float]:
+        """
+        For token_tensor[request_id], chunk it and check whether each chunk
+        appears contiguously in any previous request (token_tensor[:request_id]).
+        Returns (total_tokens_matched, elapsed_seconds).
+        """
+        assert token_tensor.ndim == 2, "Expected [N, T] tensor"
+        N, T = token_tensor.shape
+        assert 0 <= request_id < N, "request_id out of range"
+
+        if request_id == 0 or T < chunk_len:
+            return 0, 0
+
+        r = token_tensor[request_id]  # [T]
+        r = r[: len(tokens)]
+        Xprev = token_tensor[:request_id]  # [request_id, T]
+
+        # Sliding windows for previous rows
+        Xw = Xprev.unfold(dimension=1, size=chunk_len, step=1)  # [R, W, L]
+        # Chunks of r
+        r_chunks = r.unfold(dimension=0, size=chunk_len, step=stride_r)  # [C, L]
+        if r_chunks.numel() == 0:
+            return 0, 0
+
+        total_matched_chunks = 0
+
+        # Process in mini-batches to control memory
+        for b in range(0, r_chunks.size(0), chunk_batch):
+            rc = r_chunks[b : b + chunk_batch]  # [B, L]
+            eq = Xw[:, :, None, :] == rc[None, None, :, :]
+            full = eq.all(dim=-1)  # [R, W, B]
+            # Count how many unique chunks matched (across all previous rows)
+            matched_chunk_indices = torch.unique(full.nonzero(as_tuple=True)[2])
+            total_matched_chunks += matched_chunk_indices.numel()
+
+        total_tokens_matched = total_matched_chunks * chunk_len
+
+        return total_tokens_matched, 0
+
+    def add_request(
+        self,
+        request_id: int,
+        tokens: List[int],
+        token_tensor: Optional[torch.Tensor] = None,
+    ) -> None:
+        """
+        Add a request to the pool, evicting LRU entries if necessary.
+        """
+        # Evict until we have space
+        while self.current_tokens + len(tokens) > self.max_tokens and self.requests:
+            old_id, old_tokens = self.requests.popitem(last=False)
+            self.current_tokens -= len(old_tokens)
+
+            # substring matching case
+            if token_tensor is not None:
+                token_tensor[old_id, :] = 0
+
+        # Add new request
+        self.requests[request_id] = tokens
+        self.current_tokens += len(tokens)
+
+
+def load_and_tokenize_inputs(
+    jsonl_path: str, tokenizer_name: str = DEFAULT_TOKENIZER
+) -> Tuple[List[List[int]], torch.Tensor]:
+    """
+    Load and tokenize inputs from a JSONL file.
+
+    Returns:
+        Tuple of (tokenized_sequences_list, tokenized_sequences_tensor)
+        - tokenized_sequences_list: List of token lists
+        - tokenized_sequences_tensor: Padded 2D tensor (sequences, tokens)
+          Sequences are padded with 0s to match the longest sequence.
+    """
+    print(f"Loading tokenizer: {tokenizer_name}")
+    tokenizer = AutoTokenizer.from_pretrained(tokenizer_name)
+
+    print(f"Reading and tokenizing inputs from: {jsonl_path}")
+    tokenized_sequences = []
+
+    with open(jsonl_path, "r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    for line in tqdm(lines, desc="Tokenizing"):
+        try:
+            data = json.loads(line.strip())
+            input_text = data.get("input", "")
+            tokens = tokenizer.encode(input_text)
+            tokenized_sequences.append(tokens)
+        except Exception as e:
+            print(f"Warning: Failed to process line: {e}")
+            tokenized_sequences.append([])
+
+    if tokenized_sequences:
+        max_length = max(len(seq) for seq in tokenized_sequences)
+        num_sequences = len(tokenized_sequences)
+
+        # Create padded tensor (pad with 0s)
+        tokenized_tensor = torch.zeros((num_sequences, max_length), dtype=torch.long)
+        for i, seq in enumerate(tokenized_sequences):
+            if seq:
+                tokenized_tensor[i, : len(seq)] = torch.tensor(seq, dtype=torch.long)
+    else:
+        tokenized_tensor = torch.tensor([], dtype=torch.long)
+
+    return tokenized_sequences, tokenized_tensor
+
+
+def calculate_hit_rate(
+    token_sequences: List[List[int]],
+    pool_size: Optional[int] = None,
+    token_tensor: Optional[torch.Tensor] = None,
+    method: str = "prefix",
+) -> float:
+    # Use float('inf') for unlimited case to avoid eviction
+    max_tokens = float("inf") if pool_size is None else pool_size
+    pool = LRUTokenPool(max_tokens)
+
+    total_tokens = 0
+    hit_tokens = 0
+
+    total_lcs_time_s = 0.0
+    lcs_calls = 0
+
+    for idx, tokens in tqdm(list(enumerate(token_sequences))):
+        total_tokens += len(tokens)
+
+        if method == "prefix":
+            if idx > 0:
+                common, _ = pool.longest_prefix_len(tokens)
+                hit_tokens += common
+            pool.add_request(idx, tokens)
+        elif method == "substring" and token_tensor is not None:
+            if idx > 0:
+                common, elapsed = pool.longest_common_substring(
+                    idx, token_tensor, tokens
+                )
+                hit_tokens += common
+                total_lcs_time_s += elapsed
+                lcs_calls += 1
+            pool.add_request(idx, tokens, token_tensor)
+        else:
+            raise ValueError(f"Invalid method: {method}")
+
+    if method == "substring":
+        avg_ms = (total_lcs_time_s / lcs_calls * 1000.0) if lcs_calls > 0 else 0.0
+        print(
+            f"  [Timing] longest_common_substring: total {total_lcs_time_s:.3f}s, "
+            f"calls {lcs_calls}, avg {avg_ms:.2f} ms"
+        )
+
+    return hit_tokens / total_tokens if total_tokens > 0 else 0.0
+
+
+def analyze_hit_rates_across_pool_sizes(
+    token_sequences: List[List[int]],
+    pool_sizes_gb: List[Union[int, float, str]],
+    tokens_per_gb: int,
+    token_tensor: Optional[torch.Tensor] = None,
+) -> Tuple[List[float], List[float], List[str]]:
+    print("\nAnalyzing hit rates across pool sizes...")
+    print("=" * 60)
+
+    prefix_hit_rates = []
+    substring_hit_rates = []
+    x_labels = []
+
+    for size_gb in pool_sizes_gb:
+        if size_gb == "unlimited":
+            size_tokens = None
+            x_labels.append("∞")
+            pool_desc = "unlimited"
+            token_desc = ""
+        else:
+            size_tokens = int(size_gb * tokens_per_gb)
+            x_labels.append(str(int(size_gb)))
+            pool_desc = f"{size_gb}GB"
+            token_desc = f" ({size_tokens:,} tokens)"
+
+        print(f"Testing pool size: {pool_desc}{token_desc}")
+
+        # For every pool size round, we should start from fresh
+        tensor_copy = token_tensor.clone() if token_tensor is not None else None
+
+        prefix_hit_rate = calculate_hit_rate(
+            token_sequences, size_tokens, tensor_copy, method="prefix"
+        )
+        prefix_hit_rates.append(prefix_hit_rate)
+        print(f"  Prefix: {prefix_hit_rate:.4f} ({prefix_hit_rate * 100:.2f}%)")
+
+        substring_hit_rate = calculate_hit_rate(
+            token_sequences, size_tokens, tensor_copy, method="substring"
+        )
+        substring_hit_rates.append(substring_hit_rate)
+        print(
+            f"  Substring: {substring_hit_rate:.4f} ({substring_hit_rate * 100:.2f}%)\n"
+        )
+
+    print("=" * 60)
+    return prefix_hit_rates, substring_hit_rates, x_labels
+
+
+def plot_hit_rates(
+    prefix_hit_rates: List[float],
+    substring_hit_rates: List[float],
+    x_labels: List[str],
+    output_path: str,
+) -> None:
+    """
+    Generate and save the hit rate vs pool size plot comparing both methods.
+    """
+    plt.figure(figsize=(12, 7))
+
+    # Plot prefix
+    plt.plot(
+        range(len(prefix_hit_rates)),
+        prefix_hit_rates,
+        marker="o",
+        linewidth=2,
+        markersize=8,
+        color="#2E86AB",
+        label="Prefix Matching",
+    )
+
+    # Plot substring
+    plt.plot(
+        range(len(substring_hit_rates)),
+        substring_hit_rates,
+        marker="s",
+        linewidth=2,
+        markersize=8,
+        color="#A23B72",
+        label="Substring Matching",
+    )
+
+    plt.xlabel("Pool Size (GB)", fontsize=12, fontweight="bold")
+    plt.ylabel("Hit Rate", fontsize=12, fontweight="bold")
+    plt.title(
+        "Cache Hit Rate vs Pool Size: Prefix vs Substring Matching",
+        fontsize=14,
+        fontweight="bold",
+    )
+    plt.xticks(range(len(x_labels)), x_labels, rotation=45)
+    plt.grid(True, alpha=0.3, linestyle="--")
+
+    # Set y-axis limit based on max of both methods
+    max_rate = max(max(prefix_hit_rates), max(substring_hit_rates))
+    plt.ylim(0, min(1.0, max_rate * 1.1))
+    plt.legend(loc="best", fontsize=10)
+
+    # Annotate prefix matching rates
+    for i, (rate, label) in enumerate(zip(prefix_hit_rates, x_labels, strict=False)):
+        plt.annotate(
+            f"{rate * 100:.1f}%",
+            xy=(i, rate),
+            xytext=(0, 8),
+            textcoords="offset points",
+            ha="center",
+            fontsize=8,
+            color="#2E86AB",
+        )
+
+    # Annotate substring matching rates
+    for i, (rate, label) in enumerate(zip(substring_hit_rates, x_labels, strict=False)):
+        plt.annotate(
+            f"{rate * 100:.1f}%",
+            xy=(i, rate),
+            xytext=(0, -15),
+            textcoords="offset points",
+            ha="center",
+            fontsize=8,
+            color="#A23B72",
+        )
+
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150, bbox_inches="tight")
+    print(f"Plot saved to: {output_path}")
+
+
+def parse_arguments() -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Analyze prefix cache hit rates across different pool sizes",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s -i trace.jsonl
+  %(prog)s -i trace.jsonl -o custom_output.png
+  %(prog)s -i trace.jsonl --pool-sizes 1 2 4 8 16 unlimited
+        """,
+    )
+
+    parser.add_argument(
+        "-i",
+        "--input",
+        type=str,
+        required=True,
+        help="Path to input JSONL file (trace.jsonl)",
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default="prefix_cache_hit_rate.png",
+        help="Path to output plot file (PNG) (default: prefix_cache_hit_rate.png)",
+    )
+
+    parser.add_argument(
+        "--tokenizer",
+        type=str,
+        default=DEFAULT_TOKENIZER,
+        help=f"HuggingFace tokenizer model name (default: {DEFAULT_TOKENIZER})",
+    )
+
+    parser.add_argument(
+        "--tokens-per-gb",
+        type=int,
+        default=DEFAULT_TOKENS_PER_GB,
+        help=f"Conversion factor from GB to tokens "
+        f"(default: {DEFAULT_TOKENS_PER_GB}). "
+        "This should be adjusted when using a different tokenizer.",
+    )
+
+    parser.add_argument(
+        "--pool-sizes",
+        nargs="+",
+        default=None,
+        help='Pool sizes in GB to test (space-separated, can include "unlimited"). '
+        f"Default: {' '.join(map(str, DEFAULT_POOL_SIZES_GB))}",
+    )
+
+    return parser.parse_args()
+
+
+def parse_pool_sizes(
+    pool_sizes_input: Optional[List[str]],
+) -> List[Union[int, float, str]]:
+    if pool_sizes_input is None:
+        return DEFAULT_POOL_SIZES_GB
+
+    parsed_sizes: List[Union[int, float, str]] = []
+    for size in pool_sizes_input:
+        if size.lower() == "unlimited":
+            parsed_sizes.append("unlimited")
+        else:
+            try:
+                parsed_sizes.append(float(size))
+            except ValueError:
+                raise ValueError(
+                    f"Invalid pool size: {size}. Must be a number or 'unlimited'"
+                ) from None
+
+    return parsed_sizes
+
+
+def main() -> None:
+    args = parse_arguments()
+
+    # Parse pool sizes
+    pool_sizes_gb = parse_pool_sizes(args.pool_sizes)
+
+    print("Configuration:")
+    print(f"  Input: {args.input}")
+    print(f"  Output: {args.output}")
+    print(f"  Tokenizer: {args.tokenizer}")
+    print(f"  Tokens per GB: {args.tokens_per_gb}")
+    print(f"  Pool sizes: {pool_sizes_gb}\n")
+
+    # Load and tokenize inputs
+    token_sequences, token_tensor = load_and_tokenize_inputs(args.input, args.tokenizer)
+    print(f"Loaded {len(token_sequences)} requests")
+    print(f"Token tensor shape: {token_tensor.shape} (padded with 0s)")
+    print(f"First sequence: {token_tensor[0]}")
+
+    # Analyze hit rates using both methods
+    prefix_hit_rates, substring_hit_rates, x_labels = (
+        analyze_hit_rates_across_pool_sizes(
+            token_sequences,
+            pool_sizes_gb,
+            args.tokens_per_gb,
+            token_tensor,
+        )
+    )
+
+    # Generate comparison plot
+    plot_hit_rates(prefix_hit_rates, substring_hit_rates, x_labels, args.output)
+    print("\nAnalysis complete!")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/agents/requirements.txt b/examples/agents/requirements.txt
new file mode 100644
index 0000000..3c231c6
--- /dev/null
+++ b/examples/agents/requirements.txt
@@ -0,0 +1,4 @@
+transformers
+matplotlib
+tqdm
+torch
\ No newline at end of file
diff --git a/examples/basic_check/README.md b/examples/basic_check/README.md
new file mode 100644
index 0000000..4595818
--- /dev/null
+++ b/examples/basic_check/README.md
@@ -0,0 +1,47 @@
+# LMCache Basic Check Examples
+
+This is an introduce of examples for the LMCache Basic Check Tool.
+
+## Example Usage Patterns
+
+### Testing Storage Manager
+```bash
+# Basic test
+python -m lmcache.v1.basic_check --mode test_storage_manager
+
+# With custom model
+python -m lmcache.v1.basic_check --mode test_storage_manager --model /my_model/
+```
+
+### Testing Remote Backend
+```bash
+# Basic remote test
+python -m lmcache.v1.basic_check --mode test_remote
+
+```
+
+### Key Generation
+```bash
+# Generate 100 keys with 8 concurrent workers
+python -m lmcache.v1.basic_check --mode gen --num-keys 100 --concurrency 8
+
+# Generate keys with offset (useful for distributed testing)
+python -m lmcache.v1.basic_check --mode gen --num-keys 100 --concurrency 8 --offset 1000
+```
+
+## Configuration
+
+Use the provided example configuration:
+
+```bash
+# Copy to default location
+cp example_config.yaml ~/.lmcache/config.yaml
+
+# Or set environment variable
+export LMCACHE_CONFIG_PATH=$(pwd)/example_config.yaml
+```
+
+## Documentation
+
+For comprehensive documentation, see:
+- [Detailed Usage Documentation](../../docs/source/developer_guide/usage/basic_check.rst)
diff --git a/examples/basic_check/example_config.yaml b/examples/basic_check/example_config.yaml
new file mode 100644
index 0000000..c242476
--- /dev/null
+++ b/examples/basic_check/example_config.yaml
@@ -0,0 +1,13 @@
+# LMCache Basic Check Example Configuration
+# This configuration file provides settings optimized for basic check operations
+
+# Basic cache settings
+chunk_size: 256
+local_cpu: False
+max_local_cpu_size: 1
+save_unfull_chunk: False
+
+remote_url: "fs://host:0/tmp/lmcache_fs_test"
+
+extra_config:
+  save_chunk_meta: False
\ No newline at end of file
diff --git a/examples/blend_kv/README.md b/examples/blend_kv/README.md
new file mode 100644
index 0000000..8dfe4cc
--- /dev/null
+++ b/examples/blend_kv/README.md
@@ -0,0 +1,38 @@
+# KV blending example
+This is a minimal example demonstrating the KV blending functionality of LMCache.
+
+The KV blending functionality is enabled by setting `enable_blending: True` in the configuration yaml.
+
+In `blend_kv.py`, the following code will first calculate the KV cache of two text chunks.
+```python
+offline_precompute = OfflineKVPreCompute(llm)
+for chunk in chunks:
+    offline_precompute.precompute_kv(chunk)
+```
+
+Then, the text chunks are concatenated together, prepended with a system prompt, and appended with a user's quest.
+```python
+user_prompt= [sys_prompt, chunks[0], chunks[1], question]
+user_prompt = combine_input_prompt_chunks(user_prompt)
+```
+
+Finally, the prompt will be sent to the serving engine and the KV blending module will blend the KV for the text chunks.
+
+
+## How to run
+### Offline
+```
+LMCACHE_CONFIG_FILE=example_blending.yaml LMCACHE_USE_EXPERIMENTAL=False python3 blend_kv.py
+LMCACHE_CONFIG_FILE=example_blending.yaml LMCACHE_USE_EXPERIMENTAL=False python3 batched_kv.py
+LMCACHE_CONFIG_FILE=example_blending.yaml LMCACHE_USE_EXPERIMENTAL=False VLLM_WORKER_MULTIPROC_METHOD=spawn python3 tp_kv.py
+LMCACHE_CONFIG_FILE=example_blending.yaml VLLM_WORKER_MULTIPROC_METHOD=spawn LMCACHE_USE_EXPERIMENTAL=False python3 batched_tp_kv.py
+```
+### Online
+```
+LMCACHE_CONFIG_FILE=example_blending.yaml LMCACHE_USE_EXPERIMENTAL=False CUDA_VISIBLE_DEVICES=0 python3 -m lmcache_vllm.vllm.entrypoints.openai.api_server --model mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000
+python3 online_kv.py 8000
+```
+```
+LMCACHE_CONFIG_FILE=example_blending.yaml LMCACHE_USE_EXPERIMENTAL=False CUDA_VISIBLE_DEVICES=0,1 VLLM_WORKER_MULTIPROC_METHOD=spawn python3 -m lmcache_vllm.vllm.entrypoints.openai.api_server --model mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000 --tensor-parallel-size 2
+python3 online_kv.py 8000
+```
diff --git a/examples/blend_kv/batched_kv.py b/examples/blend_kv/batched_kv.py
new file mode 100644
index 0000000..08e212f
--- /dev/null
+++ b/examples/blend_kv/batched_kv.py
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import time
+
+# Third Party
+from lmcache_vllm.blend_adapter import (
+    OfflineKVPreCompute,
+    combine_input_prompt_chunks,
+)
+from lmcache_vllm.vllm import LLM, SamplingParams
+import lmcache_vllm
+
+context_files = ["chunk1.txt", "chunk2.txt"]
+chunks = []
+
+for context_file in context_files:
+    with open(context_file, "r") as fin:
+        context = fin.read()
+    chunks.append(context)
+
+sys_prompt = "Here's a document from the user: "
+question = "Question: What does this document mainly talks about? Answer: "
+
+llm = LLM(
+    model="mistralai/Mistral-7B-Instruct-v0.2",
+    gpu_memory_utilization=0.7,
+    tensor_parallel_size=1,
+)
+sampling_params_generation = SamplingParams(temperature=0.0, top_p=0.95, max_tokens=30)
+
+print("-------------- Pre-computing KV cache for chunks -------------------")
+offline_precompute = OfflineKVPreCompute(llm)
+for chunk in chunks:
+    offline_precompute.precompute_kv(chunk)
+
+time.sleep(3)
+print("Running the real query here!")
+
+user_prompt_one = [sys_prompt, chunks[0], question]
+user_prompt_two = [sys_prompt, chunks[1], question]
+user_prompt_one = combine_input_prompt_chunks(user_prompt_one)
+user_prompt_two = combine_input_prompt_chunks(user_prompt_two)
+outputs = llm.generate([user_prompt_one, user_prompt_two], sampling_params_generation)
+for output in outputs:
+    generated_text = output.outputs[0].text
+    print(f"Newly generated text: {generated_text!r}")
+    ttft = output.metrics.first_token_time - output.metrics.first_scheduled_time
+    print(f"Time to first token: {ttft:.3f} seconds")
+
+# Graceful exit
+lmcache_vllm.close_lmcache_engine()
diff --git a/examples/blend_kv/batched_tp_kv.py b/examples/blend_kv/batched_tp_kv.py
new file mode 100644
index 0000000..8e811c3
--- /dev/null
+++ b/examples/blend_kv/batched_tp_kv.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import time
+
+# Third Party
+from lmcache_vllm.blend_adapter import (
+    OfflineKVPreCompute,
+    combine_input_prompt_chunks,
+)
+from lmcache_vllm.vllm import LLM, SamplingParams
+import lmcache_vllm
+
+if __name__ == "__main__":
+    context_files = ["chunk1.txt", "chunk2.txt"]
+    chunks = []
+
+    for context_file in context_files:
+        with open(context_file, "r") as fin:
+            context = fin.read()
+        chunks.append(context)
+
+    sys_prompt = "Here's a document from the user: "
+    question = "Question: What does this document mainly talks about? Answer: "
+
+    llm = LLM(
+        model="mistralai/Mistral-7B-Instruct-v0.2",
+        gpu_memory_utilization=0.7,
+        tensor_parallel_size=2,
+    )
+    sampling_params_generation = SamplingParams(
+        temperature=0.0, top_p=0.95, max_tokens=30
+    )
+
+    print("-------------- Pre-computing KV cache for chunks -------------------")
+    offline_precompute = OfflineKVPreCompute(llm)
+    for chunk in chunks:
+        offline_precompute.precompute_kv(chunk)
+
+    time.sleep(3)
+    print("Running the real query here!")
+
+    user_prompt_one = [sys_prompt, chunks[0], question]
+    user_prompt_two = [sys_prompt, chunks[1], question]
+    user_prompt_one = combine_input_prompt_chunks(user_prompt_one)
+    user_prompt_two = combine_input_prompt_chunks(user_prompt_two)
+    outputs = llm.generate(
+        [user_prompt_one, user_prompt_two], sampling_params_generation
+    )
+    for output in outputs:
+        generated_text = output.outputs[0].text
+        print(f"Newly generated text: {generated_text!r}")
+        ttft = output.metrics.first_token_time - output.metrics.first_scheduled_time
+        print(f"Time to first token: {ttft:.3f} seconds")
+
+    # Graceful exit
+    lmcache_vllm.close_lmcache_engine()
diff --git a/examples/blend_kv/blend_kv.py b/examples/blend_kv/blend_kv.py
new file mode 100644
index 0000000..26022b1
--- /dev/null
+++ b/examples/blend_kv/blend_kv.py
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import time
+
+# Third Party
+from lmcache_vllm.blend_adapter import (
+    OfflineKVPreCompute,
+    combine_input_prompt_chunks,
+)
+from lmcache_vllm.vllm import LLM, SamplingParams
+import lmcache_vllm
+
+context_files = ["chunk1.txt", "chunk2.txt"]
+chunks = []
+
+for context_file in context_files:
+    with open(context_file, "r") as fin:
+        context = fin.read()
+    chunks.append(context)
+
+sys_prompt = "Here's a document from the user: "
+question = "Question: What does this document mainly talks about? Answer: "
+
+llm = LLM(
+    model="mistralai/Mistral-7B-Instruct-v0.2",
+    gpu_memory_utilization=0.7,
+    tensor_parallel_size=1,
+)
+sampling_params_generation = SamplingParams(temperature=0.0, top_p=0.95, max_tokens=30)
+
+print("-------------- Pre-computing KV cache for chunks -------------------")
+offline_precompute = OfflineKVPreCompute(llm)
+for chunk in chunks:
+    offline_precompute.precompute_kv(chunk)
+
+time.sleep(3)
+print("Running the real query here!")
+
+user_prompt = [sys_prompt, chunks[0], chunks[1], question]
+user_prompt = combine_input_prompt_chunks(user_prompt)
+outputs = llm.generate(user_prompt, sampling_params_generation)
+for output in outputs:
+    generated_text = output.outputs[0].text
+    print(f"Newly generated text: {generated_text!r}")
+    ttft = output.metrics.first_token_time - output.metrics.first_scheduled_time
+    print(f"Time to first token: {ttft:.3f} seconds")
+
+# Graceful exit
+lmcache_vllm.close_lmcache_engine()
diff --git a/examples/blend_kv/chunk1.txt b/examples/blend_kv/chunk1.txt
new file mode 100644
index 0000000..2edcee3
--- /dev/null
+++ b/examples/blend_kv/chunk1.txt
@@ -0,0 +1,62 @@
+FFMPEG(1)						FFMPEG(1)
+
+NAME
+       ffmpeg - ffmpeg video converter
+
+SYNOPSIS
+       ffmpeg [global_options] {[input_file_options] -i input_url} ... 
+       {[output_file_options] output_url} ...
+
+DESCRIPTION
+       ffmpeg is a very fast video and audio converter that can also 
+       grab from a live audio/video source. It can also convert between 
+       arbitrary sample rates and resize video on the fly with a high 
+       quality polyphase filter.
+
+       ffmpeg reads from an arbitrary number of input "files" (which 
+       can be regular files, pipes, network streams, grabbing devices, 
+       etc.), specified by the "-i" option, and writes to an arbitrary 
+       number of output "files", which are specified by a plain output
+       url. Anything found on the command line which cannot be inter-
+       preted as an option is considered to be an output url.
+
+       Each input or output url can, in principle, contain any number of 
+       streams of different types (video/audio/subtitle/attachment/data). 
+       The allowed number and/or types of streams may be limited by the 
+       container format. Selecting which streams from which inputs will 
+       go into which output is either done automatically or with the 
+       "-map" option (see the Stream selection chapter).
+
+       To refer to input files in options, you must use their indices 
+       (0-based). E.g.  the first input file is 0, the second is 1, etc. 
+       Similarly, streams within a file are referred to by their indices. 
+       E.g. "2:3" refers to the fourth stream in the third input file. 
+       Also see the Stream specifiers chapter.
+
+       As a general rule, options are applied to the next specified file. 
+       Therefore, order is important, and you can have the same option on 
+       the command line multiple times. Each occurrence is then applied 
+       to the next input or output file.  Exceptions from this rule are 
+       the global options (e.g. verbosity level), which should be specified 
+       first.
+
+       Do not mix input and output files -- first specify all input files, 
+       then all output files. Also do not mix options which belong to 
+       different files. All options apply ONLY to the next input or output 
+       file and are reset between files.
+
+       •   To set the video bitrate of the output file to 64 kbit/s:
+
+		   ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi
+
+       •   To force the frame rate of the output file to 24 fps:
+
+		   ffmpeg -i input.avi -r 24 output.avi
+
+       •   To force the frame rate of the input file (valid for raw formats only) to 1 fps and the frame
+	   rate of the output file to 24 fps:
+
+		   ffmpeg -r 1 -i input.m2v -r 24 output.avi
+
+       The format option may be needed for raw input files.
+
diff --git a/examples/blend_kv/chunk2.txt b/examples/blend_kv/chunk2.txt
new file mode 100644
index 0000000..0ff3bda
--- /dev/null
+++ b/examples/blend_kv/chunk2.txt
@@ -0,0 +1,114 @@
+DETAILED DESCRIPTION
+       The transcoding process in ffmpeg for each output can be described by the following diagram:
+
+		_______ 	     ______________
+	       |       |	    |		   |
+	       | input |  demuxer   | encoded data |   decoder
+	       | file  | ---------> | packets	   | -----+
+	       |_______|	    |______________|	  |
+							  v
+						      _________
+						     |	       |
+						     | decoded |
+						     | frames  |
+						     |_________|
+		________	     ______________	  |
+	       |	|	    |		   |	  |
+	       | output | <-------- | encoded data | <----+
+	       | file	|   muxer   | packets	   |   encoder
+	       |________|	    |______________|
+
+       ffmpeg calls the libavformat library (containing demuxers) to read input files and get packets
+       containing encoded data from them. When there are multiple input files, ffmpeg tries to keep them
+       synchronized by tracking lowest timestamp on any active input stream.
+
+       Encoded packets are then passed to the decoder (unless streamcopy is selected for the stream, see
+       further for a description). The decoder produces uncompressed frames (raw video/PCM audio/...)
+       which can be processed further by filtering (see next section). After filtering, the frames are
+       passed to the encoder, which encodes them and outputs encoded packets. Finally those are passed to
+       the muxer, which writes the encoded packets to the output file.
+
+   Filtering
+       Before encoding, ffmpeg can process raw audio and video frames using filters from the libavfilter
+       library. Several chained filters form a filter graph. ffmpeg distinguishes between two types of
+       filtergraphs: simple and complex.
+
+       Simple filtergraphs
+
+       Simple filtergraphs are those that have exactly one input and output, both of the same type. In
+       the above diagram they can be represented by simply inserting an additional step between decoding
+       and encoding:
+
+		_________			 ______________
+	       |	 |			|	       |
+	       | decoded |			| encoded data |
+	       | frames  |\		      _ | packets      |
+	       |_________| \		      /||______________|
+			    \	__________   /
+		 simple     _\||	  | /  encoder
+		 filtergraph   | filtered |/
+			       | frames   |
+			       |__________|
+
+       Simple filtergraphs are configured with the per-stream -filter option (with -vf and -af aliases
+       for video and audio respectively).  A simple filtergraph for video can look for example like this:
+
+		_______        _____________	    _______	   ________
+	       |       |      | 	    |	   |	   |	  |	   |
+	       | input | ---> | deinterlace | ---> | scale | ---> | output |
+	       |_______|      |_____________|	   |_______|	  |________|
+
+       Note that some filters change frame properties but not frame contents. E.g. the "fps" filter in
+       the example above changes number of frames, but does not touch the frame contents. Another example
+       is the "setpts" filter, which only sets timestamps and otherwise passes the frames unchanged.
+
+       Complex filtergraphs
+
+       Complex filtergraphs are those which cannot be described as simply a linear processing chain
+       applied to one stream. This is the case, for example, when the graph has more than one input
+       and/or output, or when output stream type is different from input. They can be represented with
+       the following diagram:
+
+		_________
+	       |	 |
+	       | input 0 |\		       __________
+	       |_________| \		      | 	 |
+			    \	_________    /| output 0 |
+			     \ |	 |  / |__________|
+		_________     \| complex | /
+	       |	 |     |	 |/
+	       | input 1 |---->| filter  |\
+	       |_________|     |	 | \   __________
+			      /| graph	 |  \ | 	 |
+			     / |	 |   \| output 1 |
+		_________   /  |_________|    |__________|
+	       |	 | /
+	       | input 2 |/
+	       |_________|
+
+       Complex filtergraphs are configured with the -filter_complex option.  Note that this option is
+       global, since a complex filtergraph, by its nature, cannot be unambiguously associated with a
+       single stream or file.
+
+       The -lavfi option is equivalent to -filter_complex.
+
+       A trivial example of a complex filtergraph is the "overlay" filter, which has two video inputs and
+       one video output, containing one video overlaid on top of the other. Its audio counterpart is the
+       "amix" filter.
+
+   Stream copy
+       Stream copy is a mode selected by supplying the "copy" parameter to the -codec option. It makes
+       ffmpeg omit the decoding and encoding step for the specified stream, so it does only demuxing and
+       muxing. It is useful for changing the container format or modifying container-level metadata. The
+       diagram above will, in this case, simplify to this:
+
+		_______ 	     ______________	       ________
+	       |       |	    |		   |	      |        |
+	       | input |  demuxer   | encoded data |  muxer   | output |
+	       | file  | ---------> | packets	   | -------> | file   |
+	       |_______|	    |______________|	      |________|
+
+       Since there is no decoding or encoding, it is very fast and there is no quality loss. However, it
+       might not work in some cases because of many factors. Applying filters is obviously also
+       impossible, since filters work on uncompressed data.
+
diff --git a/examples/blend_kv/example_blending.yaml b/examples/blend_kv/example_blending.yaml
new file mode 100644
index 0000000..a6364ba
--- /dev/null
+++ b/examples/blend_kv/example_blending.yaml
@@ -0,0 +1,5 @@
+chunk_size: 256
+local_device: "cpu"
+
+# Enables KV blending
+enable_blending: True
diff --git a/examples/blend_kv/online_kv.py b/examples/blend_kv/online_kv.py
new file mode 100644
index 0000000..4b56ae3
--- /dev/null
+++ b/examples/blend_kv/online_kv.py
@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from io import StringIO
+import sys
+import threading
+import time
+
+# Third Party
+from lmcache_vllm.blend_adapter import (
+    OnlineKVPreCompute,
+    combine_input_prompt_chunks,
+)
+from openai import OpenAI
+from transformers import AutoTokenizer
+
+if len(sys.argv) != 2:
+    print(f"Usage: {sys.argv[0]} <port>")
+    exit(1)
+
+port = sys.argv[1]
+
+# Modify OpenAI's API key and API base to use vLLM's API server.
+openai_api_key = "EMPTY"
+openai_api_base = f"http://localhost:{port}/v1"
+
+context_files = ["chunk1.txt", "chunk2.txt"]
+tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-Instruct-v0.2")
+precompute_kv = OnlineKVPreCompute(openai_api_key, openai_api_base, tokenizer)
+print("-------------- Pre-computing KV cache for chunks -------------------")
+context_chunks = []
+for context_file in context_files:
+    with open(context_file, "r") as fin:
+        context = fin.read()
+        precompute_kv.precompute_kv(context)
+        context_chunks.append(context)
+
+
+class Printer:
+    def __init__(self):
+        self._thread = None
+        self._stop_event = threading.Event()
+
+    def _print(self):
+        idx = 0
+        while not self._stop_event.is_set():
+            arrows = ">" * (idx % 6)
+            string = "{:6s}".format(arrows)
+            print("\033[31m\r" + string + "\033[0m", end="", flush=True)
+            idx += 1
+            time.sleep(0.2)
+
+    def start(self):
+        if self._thread is None:
+            self._stop_event.clear()
+            self._thread = threading.Thread(target=self._print)
+            self._thread.start()
+
+    def stop(self):
+        if self._thread is not None:
+            self._stop_event.set()
+            self._thread.join()
+            self._thread = None
+            print("\033[31m\r>>>>> \033[0m", end="", flush=True)
+
+
+class ChatSession:
+    def __init__(self, context_chunks):
+        self.client = client = OpenAI(
+            # defaults to os.environ.get("OPENAI_API_KEY")
+            api_key=openai_api_key,
+            base_url=openai_api_base,
+        )
+
+        models = client.models.list()
+        self.model = models.data[0].id
+
+        self.context_chunks = context_chunks
+        self.sys_prompt = "I've got a document, here's the content:```\n"
+        user_prompt = combine_input_prompt_chunks(
+            [self.sys_prompt, *context_chunks, "\n```."]
+        )
+        self.messages = [
+            {
+                "role": "user",
+                "content": user_prompt,
+            },
+            {"role": "assistant", "content": "I've got your document"},
+        ]
+
+        self.printer = Printer()
+
+    def on_user_message(self, message):
+        self.messages.append({"role": "user", "content": message})
+
+    def on_server_message(self, message):
+        self.messages.append({"role": "assistant", "content": message})
+
+    def chat(self):
+        user_prompt = input("User: ")
+        self.on_user_message(user_prompt)
+
+        self.printer.start()
+        start = time.perf_counter()
+        end = None
+
+        chat_completion = self.client.chat.completions.create(
+            messages=self.messages, model=self.model, temperature=0, stream=True
+        )
+
+        output_buffer = StringIO()
+        for chunk in chat_completion:
+            chunk_message = chunk.choices[0].delta.content
+            if chunk_message is not None:
+                self.printer.stop()
+                print(chunk_message, end="", flush=True)
+                output_buffer.write(chunk_message)
+                if end is None:
+                    end = time.perf_counter()
+        self.on_server_message(output_buffer.getvalue())
+        print("")
+        print("\033[33mTTFT:", end - start, "\033[0m")
+        print("Total time:", time.perf_counter() - start)
+
+
+chat_session = ChatSession(context_chunks)
+
+while True:
+    chat_session.chat()
+    print("")
diff --git a/examples/blend_kv/tp_kv.py b/examples/blend_kv/tp_kv.py
new file mode 100644
index 0000000..e343091
--- /dev/null
+++ b/examples/blend_kv/tp_kv.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import time
+
+# Third Party
+from lmcache_vllm.blend_adapter import (
+    OfflineKVPreCompute,
+    combine_input_prompt_chunks,
+)
+from lmcache_vllm.vllm import LLM, SamplingParams
+import lmcache_vllm
+
+if __name__ == "__main__":
+    context_files = ["chunk1.txt", "chunk2.txt"]
+    chunks = []
+
+    for context_file in context_files:
+        with open(context_file, "r") as fin:
+            context = fin.read()
+        chunks.append(context)
+
+    sys_prompt = "Here's a document from the user: "
+    question = "Question: What does this document mainly talks about? Answer: "
+
+    llm = LLM(
+        model="mistralai/Mistral-7B-Instruct-v0.2",
+        gpu_memory_utilization=0.7,
+        tensor_parallel_size=2,
+    )
+    sampling_params_generation = SamplingParams(
+        temperature=0.0, top_p=0.95, max_tokens=30
+    )
+
+    print("-------------- Pre-computing KV cache for chunks -------------------")
+    offline_precompute = OfflineKVPreCompute(llm)
+    for chunk in chunks:
+        offline_precompute.precompute_kv(chunk)
+
+    time.sleep(3)
+    print("Running the real query here!")
+
+    user_prompt = [sys_prompt, chunks[0], chunks[1], question]
+    user_prompt = combine_input_prompt_chunks(user_prompt)
+    outputs = llm.generate(user_prompt, sampling_params_generation)
+    for output in outputs:
+        generated_text = output.outputs[0].text
+        print(f"Newly generated text: {generated_text!r}")
+        ttft = output.metrics.first_token_time - output.metrics.first_scheduled_time
+        print(f"Time to first token: {ttft:.3f} seconds")
+
+    # Graceful exit
+    lmcache_vllm.close_lmcache_engine()
diff --git a/examples/blend_kv_v1/README.md b/examples/blend_kv_v1/README.md
new file mode 100644
index 0000000..d038a4d
--- /dev/null
+++ b/examples/blend_kv_v1/README.md
@@ -0,0 +1,19 @@
+# Examples vLLM + LMCache w. CacheBlend
+LMCache should be able to reduce the generation time of the second and following calls (even though the reused KV cache is not a prefix).
+
+## Some ad-hoc changes needed in vLLM
+- In `vllm/vllm/v1/worker/gpu_worker.py`, comment out `ensure_kv_transfer_initialized(vllm_config)` in function `def init_worker_distributed_environment`.
+- In the same file, add 
+```
+from lmcache.v1.compute.models.utils import VLLMModelTracker
+from lmcache.integration.vllm.utils import ENGINE_NAME
+        
+VLLMModelTracker.register_model(ENGINE_NAME, self.model_runner.model)
+ensure_kv_transfer_initialized(self.vllm_config)
+```
+at the end of the function `def load_model`.
+
+## CPU offloading
+- `python blend.py` - CacheBlend with CPU as backend
+## Disk offloading
+- `python blend.py --use-disk` - CachBlend with local disk as backend
\ No newline at end of file
diff --git a/examples/blend_kv_v1/blend.py b/examples/blend_kv_v1/blend.py
new file mode 100644
index 0000000..720efff
--- /dev/null
+++ b/examples/blend_kv_v1/blend.py
@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import asdict
+import argparse
+import contextlib
+import os
+import time
+
+# Third Party
+from transformers import AutoTokenizer
+from vllm import LLM, SamplingParams
+from vllm.config import KVTransferConfig
+from vllm.engine.arg_utils import EngineArgs
+
+# First Party
+from lmcache.integration.vllm.utils import ENGINE_NAME
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+
+
+def setup_environment_variables(
+    use_disk: bool = False,
+    blend_special_str: str = " # # ",
+    enable_sparse: bool = False,
+):
+    # LMCache-related environment variables
+
+    # LMCache is set to use 256 tokens per chunk
+    os.environ["LMCACHE_CHUNK_SIZE"] = "256"
+
+    # Blending related config
+    os.environ["LMCACHE_ENABLE_BLENDING"] = "True"
+    os.environ["LMCACHE_BLEND_SPECIAL_STR"] = blend_special_str
+    os.environ["LMCACHE_USE_LAYERWISE"] = "True"
+    os.environ["LMCACHE_BLEND_CHECK_LAYERS"] = "1"
+    os.environ["LMCACHE_BLEND_RECOMPUTE_RATIOS"] = "0.15"
+
+    if enable_sparse:
+        os.environ["VLLM_ATTENTION_BACKEND"] = "FLASHINFER"
+        os.environ["LMCACHE_EXTRA_CONFIG"] = '{"enable_sparse": true}'
+
+    if use_disk:
+        # Disable local CPU backend in LMCache
+        os.environ["LMCACHE_LOCAL_CPU"] = "False"
+
+        # Set the maximum size of the local CPU buffer size to 5GB
+        os.environ["LMCACHE_MAX_LOCAL_CPU_SIZE"] = "5"
+
+        # Enable local disk backend in LMCache
+        os.environ["LMCACHE_LOCAL_DISK"] = "file://local_disk/"
+
+        # Set the maximum size of the local disk size to 10GB
+        os.environ["LMCACHE_MAX_LOCAL_DISK_SIZE"] = "10"
+    else:
+        # Enable local CPU backend in LMCache
+        os.environ["LMCACHE_LOCAL_CPU"] = "True"
+
+        # Set the maximum size of the local CPU size to 5GB
+        os.environ["LMCACHE_MAX_LOCAL_CPU_SIZE"] = "5"
+
+
+@contextlib.contextmanager
+def build_llm_with_lmcache(lmcache_connector: str, model: str):
+    ktc = KVTransferConfig(
+        kv_connector=lmcache_connector,
+        kv_role="kv_both",
+    )
+
+    llm_args = EngineArgs(
+        model=model,
+        kv_transfer_config=ktc,
+        max_model_len=32648,
+        gpu_memory_utilization=0.7,
+        enable_prefix_caching=False,
+        enforce_eager=True,
+    )
+
+    llm = LLM(**asdict(llm_args))
+    try:
+        yield llm
+    finally:
+        # Clean up lmcache backend
+        LMCacheEngineBuilder.destroy(ENGINE_NAME)
+
+
+def print_output(
+    llm: LLM,
+    prompt: list[int],
+    sampling_params: SamplingParams,
+    req_str: str,
+):
+    start = time.time()
+    outputs = llm.generate(
+        prompts={"prompt_token_ids": prompt}, sampling_params=sampling_params
+    )
+    print("-" * 50)
+    for output in outputs:
+        generated_text = output.outputs[0].text
+        print(f"Generated text: {generated_text!r}")
+    print(f"Generation took {time.time() - start:.2f} seconds, {req_str} request done.")
+    print("-" * 50)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-d",
+        "--use-disk",
+        action="store_true",
+        help="Specify whether to use disk as backend (default: False)",
+    )
+
+    parser.add_argument(
+        "-b",
+        "--blend-special-str",
+        default="# #",
+        help="Specify the special separators to separate chunks (default: '# #')",
+    )
+
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="mistralai/Mistral-7B-Instruct-v0.2",
+    )
+
+    parser.add_argument(
+        "--enable-sparse",
+        action="store_true",
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    lmcache_connector = "LMCacheConnectorV1"
+    model = args.model
+
+    setup_environment_variables(
+        args.use_disk, args.blend_special_str, args.enable_sparse
+    )
+
+    tokenizer = AutoTokenizer.from_pretrained(model)
+
+    with build_llm_with_lmcache(lmcache_connector, model) as llm:
+        # Define the shared prompt and specific prompts
+        warmup_prompt = tokenizer.encode("Nice to meet you" * 500)[1:]
+        sys_prompt = [1, 733, 16289, 28793] + tokenizer.encode(
+            "You are a very helpful assistant. "
+            "Please answer the question with instructions."
+        )
+        chunk1_prompt = tokenizer.encode("Hello, how are you?" * 500)[1:]
+        chunk2_prompt = tokenizer.encode("Hello, what's up?" * 500)[1:]
+        chunk3_prompt = tokenizer.encode("Hi, what are you up to?" * 500)[1:]
+        blend_special_str = tokenizer.encode(os.getenv("LMCACHE_BLEND_SPECIAL_STR"))[1:]
+
+        first_prompt = (
+            sys_prompt
+            + blend_special_str
+            + chunk1_prompt
+            + blend_special_str
+            + chunk2_prompt
+            + blend_special_str
+            + chunk3_prompt
+            + blend_special_str
+            + tokenizer.encode("Hello, my name is")[1:]
+            + [733, 28748, 16289, 28793]
+        )
+
+        second_prompt = (
+            sys_prompt
+            + blend_special_str
+            + chunk2_prompt
+            + blend_special_str
+            + chunk1_prompt
+            + blend_special_str
+            + chunk3_prompt
+            + blend_special_str
+            + tokenizer.encode("Hello, how are you?")[1:]
+            + [733, 28748, 16289, 28793]
+        )
+
+        third_prompt = (
+            sys_prompt
+            + blend_special_str
+            + chunk2_prompt
+            + blend_special_str
+            + chunk1_prompt
+            + blend_special_str
+            + chunk3_prompt
+            + blend_special_str
+            + tokenizer.encode("Hello, what's up?")[1:]
+            + [733, 28748, 16289, 28793]
+        )
+
+        sampling_params = SamplingParams(temperature=0, top_p=0.95, max_tokens=1)
+
+        print_output(llm, warmup_prompt, sampling_params, "warmup")
+
+        # Print the first output
+        print_output(llm, first_prompt, sampling_params, "first")
+
+        time.sleep(1)
+
+        # print the second output
+        print_output(
+            llm, second_prompt, sampling_params, "second (warming up blend code path)"
+        )
+
+        time.sleep(1)
+
+        # print the third output
+        print_output(llm, third_prompt, sampling_params, "third")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/cache_controller/README.md b/examples/cache_controller/README.md
new file mode 100644
index 0000000..6e1deaa
--- /dev/null
+++ b/examples/cache_controller/README.md
@@ -0,0 +1,15 @@
+# Examples of Cache Controller APIs
+
+LMCache offers various ochestration APIs which can be used for routing (e.g., KV cache lookup) or hot context migration (e.g., KV cache move/migration).
+
+Here are a few examples:
+
+- [KV cache clear](clear/)
+- [KV cache compress](compress/)
+- [KV cache lookup](lookup/)
+- [KV cache move](move/)
+- [KV cache pin](pin/)
+
+Unsupported APIs (WIP):
+- [KV cache decompress](decompress/)
+- [KV cache unpin](unpin/)
\ No newline at end of file
diff --git a/examples/cache_controller/clear/README.md b/examples/cache_controller/clear/README.md
new file mode 100644
index 0000000..b2b5517
--- /dev/null
+++ b/examples/cache_controller/clear/README.md
@@ -0,0 +1,46 @@
+# LMCache Clear
+This is an example to demonstrate how to clear KV cache in an LMCacheEngine externally.
+
+## Prerequisites
+Your server should have at least 1 GPU.  
+
+This will use port 8000 for 1 vllm and port 8001 for LMCache. The controller occupies ports 9000 and 9001.
+
+## Steps
+1. Start the vllm engine at port 8000:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --max-model-len 4096  --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+2. Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+```bash
+lmcache_controller --host localhost --port 9000 --monitor-port 9001
+```
+
+3. Send a request to vllm engine:  
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+
+4. Clear the KV cache in the system:
+```bash
+curl -X POST http://localhost:9000/clear \
+  -H "Content-Type: application/json" \
+  -d '{
+    "instance_id": "lmcache_default_instance",
+    "location": "LocalCPUBackend"
+  }'
+```
+You should be able to see a return message indicating the number of tokens' KV cache that has been successfully cleared in the system:
+
+```plaintext
+{"event_id": "xxx", "num_tokens": 12}
+```
diff --git a/examples/cache_controller/clear/example.yaml b/examples/cache_controller/clear/example.yaml
new file mode 100644
index 0000000..8e4f972
--- /dev/null
+++ b/examples/cache_controller/clear/example.yaml
@@ -0,0 +1,13 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_default_instance"
+controller_pull_url: "localhost:9001"
+lmcache_worker_ports: 8001
+
+# Peer identifiers
+p2p_host: "localhost"
+p2p_init_ports: 8200
diff --git a/examples/cache_controller/compress/README.md b/examples/cache_controller/compress/README.md
new file mode 100644
index 0000000..4e9558b
--- /dev/null
+++ b/examples/cache_controller/compress/README.md
@@ -0,0 +1,86 @@
+# LMCache Compress
+This is an example to demonstrate how to compress or decompress a request's KV cache externally.
+
+## Prerequisites
+Your server should have at least 1 GPU.
+
+This will use port 8000 for vllm and port 8001 for the LMCache worker. The controller itself occupies port 9000 and 9001.
+
+## Steps
+1. Start vllm engine at port 8000
+
+```bash
+CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+2. Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+```bash
+lmcache_controller --host localhost --port 9000 --monitor-port 9001
+```
+
+3. Send a request to vllm engine:  
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+
+LMCache will automatically offloads the KV cache to CPU.
+
+4. Tokenize the prompt:  
+```bash
+curl -X POST http://localhost:8000/tokenize \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models."
+  }'
+```
+
+You should be able to see the returned token ids as:
+```plaintext
+{"count":12,"max_model_len":4096,"tokens":[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],"token_strs":null}
+```
+
+5. Using Cachegen to compress request's KV cache:
+```bash
+curl -X POST http://localhost:9000/compress \
+  -H "Content-Type: application/json" \
+  -d '{
+    "instance_id": "lmcache_default_instance",
+    "method": "cachegen",
+    "location": "LocalCPUBackend",
+    "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+  }'
+```
+You should be able to see a return message indicating the KV cache has started to be compressed
+
+```plaintext
+{"num_tokens": 12, "event_id": "xxx"}
+```
+
+`num_tokens: 12` means that there are 12 tokens's KV cache are being compressed in the system. The returned `event_id` can be used to check the status of the compress operation (this functionality is coming soon).
+
+6. Using Cachegen to decompress request's KV cache:
+```bash
+curl -X POST http://localhost:9000/decompress \
+  -H "Content-Type: application/json" \
+  -d '{
+    "instance_id": "lmcache_default_instance",
+    "method": "cachegen",
+    "location": "LocalCPUBackend",
+    "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+  }'
+```
+You should be able to see a return message indicating the KV cache has started to be decompressed
+
+```plaintext
+{"num_tokens": 12, "event_id": "xxx"}
+```
+
+`num_tokens: 12` means that there are 12 tokens's KV cache are being decompressed in the system. The returned `event_id` can be used to check the status of the decompress operation .
diff --git a/examples/cache_controller/compress/example.yaml b/examples/cache_controller/compress/example.yaml
new file mode 100644
index 0000000..1267361
--- /dev/null
+++ b/examples/cache_controller/compress/example.yaml
@@ -0,0 +1,13 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_default_instance"
+controller_pull_url: "localhost:9001"
+lmcache_worker_ports: 8001
+
+# Peer identifiers
+p2p_host: "localhost"
+p2p_init_ports: 8200
\ No newline at end of file
diff --git a/examples/cache_controller/health/README.md b/examples/cache_controller/health/README.md
new file mode 100644
index 0000000..f60d94f
--- /dev/null
+++ b/examples/cache_controller/health/README.md
@@ -0,0 +1,26 @@
+# LMCache Health Check
+This example demonstrates how to check the health status of the LMCache controller.
+
+## Prerequisites
+- The LMCache controller must be running.
+
+## Steps
+1. Start the LMCache controller (if not already running):
+```bash
+PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-port 9001
+```
+
+2. Send a health check request to the controller's monitor port (9001 in this example):
+```bash
+curl -X POST http://localhost:9000/health -H "Content-Type: application/json" -d '{"instance_id":"lmcache_default_instance"}'
+```
+`lmcache_default_instance` indicates the `instance_id`. 
+
+3. The expected response is a JSON object indicating the error_codes:
+```json
+{"event_id":"health47ce328d-f27e-48ae-ab0c-c2218aabce95","error_codes":{"0":0,"1":0}}
+```
+
+`event_id` is an identifier of the controller operation, which can be ignored in this functionality.
+error_codes formatted to worker_id to error_code pair, and error_code
+`0` stand for health, `non zero` means error occurred.
\ No newline at end of file
diff --git a/examples/cache_controller/health/example.yaml b/examples/cache_controller/health/example.yaml
new file mode 100644
index 0000000..8e4f972
--- /dev/null
+++ b/examples/cache_controller/health/example.yaml
@@ -0,0 +1,13 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_default_instance"
+controller_pull_url: "localhost:9001"
+lmcache_worker_ports: 8001
+
+# Peer identifiers
+p2p_host: "localhost"
+p2p_init_ports: 8200
diff --git a/examples/cache_controller/lookup/README.md b/examples/cache_controller/lookup/README.md
new file mode 100644
index 0000000..24dce5b
--- /dev/null
+++ b/examples/cache_controller/lookup/README.md
@@ -0,0 +1,64 @@
+# LMCache Lookup
+This is an example to demonstrate how to check the existence of a request's KV cache in an LMCacheEngine externally.
+
+## Prerequisites
+Your server should have at least 1 GPU.  
+
+This will use port 8000 for 1 vllm and port 8001 for LMCache. The controller occupies ports 9000 and 9001.
+
+## Steps
+1. Start the vllm engine at port 8000:
+
+```bash
+PYTHONHASHSEED=123 CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+2. Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+```bash
+PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-port 9001
+```
+
+3. Send a request to vllm engine:  
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+
+4. Tokenize the prompt:  
+```bash
+curl -X POST http://localhost:8000/tokenize \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models."
+  }'
+```
+
+You should be able to see the returned token ids as:
+```plaintext
+{"count":12,"tokens":[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],"token_strs":null}
+```
+
+5. Send a lookup request to lmcache controller:  
+```bash
+curl -X POST http://localhost:9000/lookup \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+  }'
+```
+The above request returns the cache information.
+
+You should be able to see a return message:
+
+```plaintext
+{"event_id": "xxx", "lmcache_default_instance": ("LocalCPUBackend", 12)}
+```
+
+`lmcache_default_instance` indicates the `instance_id` and `("LocalCPUBackend", 12)` indicates the cache location within that instance and matched prefix length. `event_id` is an identifier of the controller operation, which can be ignored in this functionality.
\ No newline at end of file
diff --git a/examples/cache_controller/lookup/example.yaml b/examples/cache_controller/lookup/example.yaml
new file mode 100644
index 0000000..8e4f972
--- /dev/null
+++ b/examples/cache_controller/lookup/example.yaml
@@ -0,0 +1,13 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_default_instance"
+controller_pull_url: "localhost:9001"
+lmcache_worker_ports: 8001
+
+# Peer identifiers
+p2p_host: "localhost"
+p2p_init_ports: 8200
diff --git a/examples/cache_controller/move/README.md b/examples/cache_controller/move/README.md
new file mode 100644
index 0000000..e0101fa
--- /dev/null
+++ b/examples/cache_controller/move/README.md
@@ -0,0 +1,68 @@
+# LMCache Move/Migrate
+This is an example to demonstrate how to move/migrate a request's KV cache across LMCacheEngines externally.
+
+## Prerequisites
+Your server should have at least 2 GPUs. [NIXL](https://github.com/ai-dynamo/nixl) is required to be installed.
+
+This will use port 8000 and 8001 for 2 vllms and port 8500 and 8501 for the corresponding LMCache workers. Also, ports 8200, 8201, 8202 and 8203 are used for p2p KV cache transfer. The controller itself occupies port 9000, 8300 and 9400.
+
+## Steps
+1. Start two vllm engines at port 8000 and port 8001:
+
+```bash
+PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=instance1.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+```bash
+PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=instance2.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8001 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+2. Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+```bash
+PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-ports '{"pull": 8300, "reply": 8400}'
+```
+
+3. Send a request to vllm engine 1:  
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+
+4. Tokenize the prompt:  
+```bash
+curl -X POST http://localhost:8000/tokenize \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models."
+  }'
+```
+
+You should be able to see the returned token ids as:
+```plaintext
+{"count":12,"tokens":[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],"token_strs":null}
+```
+
+5. Move the request's KV cache from vllm engine 1's CPU to vllm engine 2's CPU using request's token ids:
+```bash
+curl -X POST http://localhost:9000/move \
+  -H "Content-Type: application/json" \
+  -d '{
+    "old_position": ["lmcache_instance_1", "LocalCPUBackend"],
+    "new_position": ["lmcache_instance_2", "LocalCPUBackend"],
+    "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13]
+  }'
+```
+You should be able to see a return message indicating the KV cache has started to be moved in the system:
+
+```plaintext
+{"num_tokens": 12, "event_id": "xxx"}
+```
+
+`num_tokens: 12` means that there are 12 tokens's KV cache are stored in the system. The returned `event_id` can be used to check the status of the move operation (this functionality is coming soon).
diff --git a/examples/cache_controller/move/instance1.yaml b/examples/cache_controller/move/instance1.yaml
new file mode 100644
index 0000000..57b2a1f
--- /dev/null
+++ b/examples/cache_controller/move/instance1.yaml
@@ -0,0 +1,17 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# P2P configurations
+enable_p2p: True
+p2p_host: "localhost"
+p2p_init_ports: 8200
+p2p_lookup_ports: 8201
+transfer_channel: "nixl"
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_instance_1"
+controller_pull_url: "localhost:8300"
+controller_reply_url: "localhost:8400"
+lmcache_worker_ports: 8500
\ No newline at end of file
diff --git a/examples/cache_controller/move/instance2.yaml b/examples/cache_controller/move/instance2.yaml
new file mode 100644
index 0000000..f949e67
--- /dev/null
+++ b/examples/cache_controller/move/instance2.yaml
@@ -0,0 +1,17 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# P2P configurations
+enable_p2p: True
+p2p_host: "localhost"
+p2p_init_ports: 8202
+p2p_lookup_ports: 8203
+transfer_channel: "nixl"
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_instance_2"
+controller_pull_url: "localhost:8300"
+controller_reply_url: "localhost:8400"
+lmcache_worker_ports: 8501
\ No newline at end of file
diff --git a/examples/cache_controller/pin/README.md b/examples/cache_controller/pin/README.md
new file mode 100644
index 0000000..afc1aad
--- /dev/null
+++ b/examples/cache_controller/pin/README.md
@@ -0,0 +1,62 @@
+# LMCache Pin/Persistence
+This is an example to demonstrate how to pin/persist a request's KV cache in an LMCacheEngine externally.
+
+## Prerequisites
+Your server should have at least 1 GPU.  
+
+This will use port 8000 for 1 vllm and port 8001 for LMCache. The controller occupies ports 9000 and 9001.
+
+## Steps
+1. Start the vllm engine at port 8000:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+
+2. Start the lmcache controller at port 9000 and the monitor at port 9001:
+
+```bash
+lmcache_controller --host localhost --port 9000 --monitor-port 9001
+```
+
+3. Send a request to vllm engine:  
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+
+4. Tokenize the prompt:  
+```bash
+curl -X POST http://localhost:8000/tokenize \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models."
+  }'
+```
+
+You should be able to see the returned token ids as:
+```plaintext
+{"count":12,"max_model_len":4096,"tokens":[128000,849,21435,279,26431,315,85748,6636,304,4221,4211,13],"token_strs":null}
+```
+
+5. Pin a request's KV cache in the system:
+```bash
+curl -X POST http://localhost:9000/pin \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tokens": [128000, 849, 21435, 279, 26431, 315, 85748, 6636, 304, 4221, 4211, 13],
+    "instance_id": "lmcache_default_instance",
+    "location": "LocalCPUBackend"
+  }'
+```
+You should be able to see a return message indicating the number of tokens' KV cache that has been successfully pinned in the system:
+
+```plaintext
+{"event_id": "xxx", "num_tokens": 12}
+```
diff --git a/examples/cache_controller/pin/example.yaml b/examples/cache_controller/pin/example.yaml
new file mode 100644
index 0000000..1267361
--- /dev/null
+++ b/examples/cache_controller/pin/example.yaml
@@ -0,0 +1,13 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# cache controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_default_instance"
+controller_pull_url: "localhost:9001"
+lmcache_worker_ports: 8001
+
+# Peer identifiers
+p2p_host: "localhost"
+p2p_init_ports: 8200
\ No newline at end of file
diff --git a/examples/cache_interface/README.md b/examples/cache_interface/README.md
new file mode 100644
index 0000000..cf177c9
--- /dev/null
+++ b/examples/cache_interface/README.md
@@ -0,0 +1,89 @@
+# User Controllable Caching
+This is an example to demonstrate user controllable caching (e.g., specify whether to cache a request or not).
+
+## Prerequisites
+Your server should have at least 1 GPU.  
+
+This will use the port 8000 for 1 vllm.
+
+## Steps
+1. Start the vllm engine at port 8000:
+
+```bash
+vllm serve meta-llama/Llama-3.1-8B-Instruct \
+  --kv-transfer-config '{"kv_connector": "LMCacheConnectorV1","kv_role": "kv_both"}'
+```
+
+2. Send a request to vllm engine with caching enabled (default behavior):  
+
+**Using `/v1/completions`:**
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+
+**Using `/v1/chat/completions`:**
+```bash
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "messages": [
+      {"role": "user", "content": "Explain the significance of KV cache in language models."}
+    ],
+    "max_tokens": 10
+  }'
+```
+
+You should be able to see logs indicating the KV cache is stored:
+
+```plaintext
+INFO: Storing KV cache for 13 out of 13 tokens (skip_leading_tokens=0)
+```
+
+3. Send a request with caching disabled:
+
+**Using `/v1/completions`:**
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "What is the weather today in Chicago?",
+    "max_tokens": 10,
+    "kv_transfer_params": {
+      "lmcache.skip_save": true
+    }
+  }'
+```
+
+**Using `/v1/chat/completions`:**
+```bash
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "messages": [
+      {"role": "user", "content": "What'"'"'s the weather today in Chicago?"}
+    ],
+    "max_tokens": 10,
+    "kv_transfer_params": {
+      "lmcache.skip_save": true
+    }
+  }'
+```
+
+You should be able to see logs indicating the KV cache is NOT stored:
+
+```plaintext
+INFO: User has specified not to store the cache (store_cache: false)
+```
+
+Note that cache is stored by default. 
+To disable caching, pass `"kv_transfer_params": {"lmcache.skip_save": true}` in your request. 
+This works for both `/v1/completions` and `/v1/chat/completions` endpoints.
\ No newline at end of file
diff --git a/examples/cache_interface/example.yaml b/examples/cache_interface/example.yaml
new file mode 100644
index 0000000..7d5b081
--- /dev/null
+++ b/examples/cache_interface/example.yaml
@@ -0,0 +1,3 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
\ No newline at end of file
diff --git a/examples/cache_with_configs/README.md b/examples/cache_with_configs/README.md
new file mode 100644
index 0000000..65ec302
--- /dev/null
+++ b/examples/cache_with_configs/README.md
@@ -0,0 +1,42 @@
+# Cache with configs
+This is an example to cache with configs, includes tags and the other configs.
+- tags will be used to generate the key
+- configs will be used to interact with the backends, such as set the ttl
+
+## Prerequisites
+Your server should have at least 1 GPU.
+
+This will use the port 8000 for 1 vllm.
+
+## Steps
+1. Start the vllm engine at port 8000:
+
+```bash
+VLLM_USE_V1=1 \
+LMCACHE_TRACK_USAGE=false \
+LMCACHE_CONFIG_FILE=example.yaml \
+vllm serve /disc/f/models/opt-125m/ \
+           --served-model-name "facebook/opt-125m" \
+           --enforce-eager  \
+           --port 8000 \
+           --gpu-memory-utilization 0.8 \
+           --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}' \
+           --trust-remote-code
+```
+
+2. Send a request to vllm engine with tags and configs by `kv_transfer_params: {}`:
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "facebook/opt-125m",
+    "prompt": "Explain the significance of KV cache in language models." * 100,
+    "max_tokens": 10,
+	"kv_transfer_params": {
+	  "lmcache.tag.user": "example_user_1",
+	  "lmcache.ttl": 60
+	}
+  }'
+```
+- set tags: use `lmcache.tag.xxx`
+- set configs: use `lmcache.xxx`
diff --git a/examples/cache_with_configs/example.yaml b/examples/cache_with_configs/example.yaml
new file mode 100644
index 0000000..89cb704
--- /dev/null
+++ b/examples/cache_with_configs/example.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_device: "cpu"
+local_cpu: True
+max_local_cpu_size: 10
diff --git a/examples/chunk_statistics/README.md b/examples/chunk_statistics/README.md
new file mode 100644
index 0000000..5b2e90b
--- /dev/null
+++ b/examples/chunk_statistics/README.md
@@ -0,0 +1,258 @@
+# Chunk Statistics Example
+
+This example demonstrates how to use LMCache's chunk statistics feature to track and analyze KV cache chunk reuse patterns.
+
+## Overview
+
+Chunk statistics provides insights into cache efficiency by tracking:
+- Total chunks processed
+- Unique chunks encountered
+- Duplicate chunks (cache hits)
+- Reuse rate (duplicate/total ratio)
+
+## Prerequisites
+
+- LMCache installed with vLLM integration
+- A model for testing (e.g., `/data1/deepseek/DeepSeek-V2-Lite-Chat`)
+
+## Examples
+
+### Example 1: Memory Bloom Filter Strategy
+
+The memory bloom filter strategy uses a probabilistic data structure for efficient duplicate detection with minimal memory overhead.
+
+#### Configuration
+
+See `memory_bloom_filter.yaml` for the configuration file.
+
+#### Running the Example
+
+```bash
+# Start vLLM with chunk statistics enabled
+LMCACHE_CONFIG_FILE=memory_bloom_filter.yaml \
+PYTHONHASHSEED=0 \
+python3 -m vllm.entrypoints.cli.main serve <model_path> \
+--load-format dummy \
+-tp 2 \
+--trust-remote-code \
+--served-model-name vllm_cpu_offload \
+--gpu-memory-utilization 0.5 \
+--max-num-seqs 64 \
+--no-enable-prefix-caching \
+--kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+```
+
+#### Query Statistics
+
+```bash
+# Get current statistics (default port: 6999 for scheduler)
+curl http://localhost:6999/chunk_statistics/status
+
+# Pretty print JSON output
+curl http://localhost:6999/chunk_statistics/status | jq .
+
+# Start statistics collection (if not auto-started)
+curl -X POST http://localhost:6999/chunk_statistics/start
+
+# Stop statistics collection
+curl -X POST http://localhost:6999/chunk_statistics/stop
+
+# Reset statistics
+curl -X POST http://localhost:6999/chunk_statistics/reset
+```
+
+#### Expected Output
+
+```json
+{
+  "enabled": true,
+  "total_requests": 3,
+  "timing": {
+    "lookup_time_seconds": 0.044486284255981445,
+    "record_statistics_time_seconds": 6.246566772460938e-05,
+    "check_exit_conditions_time_seconds": 5.7220458984375e-06,
+    "total_time_seconds": 0.04455447196960449,
+    "overhead_time_seconds": 6.818771362304688e-05,
+    "overhead_percentage": 0.1530434782608696
+  },
+  "total_chunks": 12,
+  "unique_chunks": 9,
+  "duplicate_chunks": 3,
+  "reuse_rate": 0.25,
+  "async_queue": {
+    "enabled": true,
+    "capacity": 100000,
+    "current_size": 0,
+    "max_size_reached": 0,
+    "full_blocks": 0,
+    "utilization": 0.0
+  },
+  "bloom_filter": {
+    "size_mb": 11.426279067993164,
+    "hash_count": 6,
+    "item_count": 9,
+    "bits_set": 54,
+    "fill_rate": 5.633768549952377e-07,
+    "expected_elements": 10000000,
+    "false_positive_rate": 0.01
+  },
+  "timestamp": 1763026696.7670634,
+  "auto_exit_enabled": false,
+  "auto_exit_timeout_hours": 0.0,
+  "auto_exit_target_unique_chunks": null
+}
+```
+
+### Example 2: File Hash Strategy
+
+The file hash strategy writes chunk hashes to disk for exact tracking and offline analysis.
+
+#### Configuration
+
+See `file_hash.yaml` for the configuration file.
+
+#### Running the Example
+
+```bash
+# Start vLLM with file hash strategy
+LMCACHE_CONFIG_FILE=file_hash.yaml \
+PYTHONHASHSEED=0 \
+python3 -m vllm.entrypoints.cli.main serve <model_path> \
+--load-format dummy \
+-tp 2 \
+--trust-remote-code \
+--served-model-name vllm_cpu_offload \
+--gpu-memory-utilization 0.5 \
+--max-num-seqs 64 \
+--no-enable-prefix-caching \
+--kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+```
+
+#### Analyze Collected Data
+
+Use the provided Python script to analyze the collected chunk hashes:
+
+```bash
+# Analyze chunk hashes from default directory
+python analyze_chunk_hashes.py --input-dir /tmp/lmcache_chunk_statistics
+
+# Export results to JSON file
+python analyze_chunk_hashes.py --input-dir /tmp/lmcache_chunk_statistics --output analysis_results.json
+```
+
+### Example 3: Auto-Stop Configuration
+
+This example demonstrates automatic stopping based on time or chunk count.
+
+#### Configuration
+
+See `auto_stop.yaml` for the configuration file.
+
+#### Running the Example
+
+```bash
+# Statistics will automatically stop after configured time or chunk count
+LMCACHE_CONFIG_FILE=auto_stop.yaml \
+PYTHONHASHSEED=0 \
+python3 -m vllm.entrypoints.cli.main serve <model_path> \
+--load-format dummy \
+-tp 2 \
+--trust-remote-code \
+--served-model-name vllm_cpu_offload \
+--gpu-memory-utilization 0.5 \
+--max-num-seqs 64 \
+--no-enable-prefix-caching \
+--kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+```
+
+## Configuration Options
+
+### Memory Bloom Filter Strategy
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `chunk_statistics_mem_bf_expected_chunks` | 20000000 | Expected number of chunks for capacity planning |
+| `chunk_statistics_mem_bf_false_positive_rate` | 0.01 | Target false positive rate (1%) |
+
+### File Hash Strategy
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `chunk_statistics_file_output_dir` | `/tmp/lmcache_chunk_statistics` | Directory for storing chunk hash files |
+| `chunk_statistics_file_rotation_size` | 104857600 | File size threshold for rotation (100MB) |
+| `chunk_statistics_file_max_count` | 100 | Maximum number of files to keep |
+
+## Understanding the Metrics
+
+### Reuse Rate
+
+The reuse rate indicates cache efficiency:
+- **0.0**: No cache reuse (all chunks are unique)
+- **0.5**: 50% of chunks are duplicates
+- **0.9**: 90% of chunks are duplicates (high cache efficiency)
+
+### Bloom Filter Metrics
+
+- **size_mb**: Memory used by the bloom filter
+- **fill_rate**: Percentage of bits set in the bloom filter (0.0 to 1.0)
+- **false_positive_rate**: Configured target false positive rate
+
+### Async Queue Metrics
+
+- **capacity**: Maximum queue size
+- **current_size**: Current number of items in queue
+- **max_size_reached**: Peak queue size observed
+- **full_blocks**: Number of times the queue was full
+- **utilization**: Current queue utilization (0.0 to 1.0)
+
+## Best Practices
+
+1. **Choose the Right Strategy:**
+   - Use `memory_bloom_filter` for real-time monitoring with minimal overhead
+   - Use `file_hash` for exact tracking and offline analysis
+
+2. **Tune Bloom Filter Parameters:**
+   - Set `expected_chunks` based on your workload size
+   - Lower `false_positive_rate` increases memory usage but improves accuracy
+
+3. **Monitor Memory Usage:**
+   - Track `bloom_filter_size_mb` to ensure it fits in available memory
+   - Adjust `expected_chunks` if memory usage is too high
+
+4. **File Rotation:**
+   - Configure appropriate `file_rotation_size` to balance file size and count
+   - Set `file_max_count` to prevent unlimited disk usage
+
+## Troubleshooting
+
+### Statistics Not Updating
+
+**Problem:** Statistics remain at zero or don't update.
+
+**Solution:**
+- Verify `enable_chunk_statistics` is set to `true`
+- Check that statistics collection is started
+- Ensure requests are being processed
+
+### High Memory Usage
+
+**Problem:** Bloom filter consuming too much memory.
+
+**Solution:**
+- Reduce `chunk_statistics_mem_bf_expected_chunks`
+- Increase `chunk_statistics_mem_bf_false_positive_rate`
+- Consider switching to `file_hash` strategy
+
+### File System Full
+
+**Problem:** Disk space exhausted with file hash strategy.
+
+**Solution:**
+- Reduce `chunk_statistics_file_max_count`
+- Decrease `chunk_statistics_file_rotation_size`
+- Implement external log rotation
+
+## Additional Resources
+
+- [Chunk Statistics Documentation](../../docs/source/production/observability/chunk_statistics.rst)
+- [Internal API Server Documentation](../../docs/source/production/observability/internal_api_server.rst)
diff --git a/examples/chunk_statistics/analyze_chunk_hashes.py b/examples/chunk_statistics/analyze_chunk_hashes.py
new file mode 100644
index 0000000..828b8f3
--- /dev/null
+++ b/examples/chunk_statistics/analyze_chunk_hashes.py
@@ -0,0 +1,423 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+
+"""Analyze chunk hash files generated by the file_hash strategy.
+
+This script reads chunk hash files and provides statistics about chunk reuse patterns.
+"""
+
+# Standard
+from collections import Counter, defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+import argparse
+import json
+import sys
+
+
+def load_chunk_hashes(input_dir: Path) -> List[Dict]:
+    """Load all chunk hash records from JSONL files.
+
+    Args:
+        input_dir: Directory containing chunk hash JSONL files
+
+    Returns:
+        List of chunk hash records
+    """
+    records: List[Dict] = []
+    hash_files = sorted(input_dir.glob("chunk_hashes_*.jsonl"))
+
+    if not hash_files:
+        print(f"No chunk hash files found in {input_dir}")
+        return records
+
+    print(f"Found {len(hash_files)} chunk hash files")
+
+    for hash_file in hash_files:
+        print(f"Reading {hash_file.name}...")
+        with open(hash_file) as f:
+            for line in f:
+                try:
+                    data = json.loads(line)
+                    records.append(data)
+                except json.JSONDecodeError as e:
+                    print(f"Warning: Failed to parse line in {hash_file}: {e}")
+                    continue
+
+    return records
+
+
+def analyze_chunk_hashes(records: List[Dict], top_n: int = 10) -> Dict:
+    """Analyze chunk hash records and compute statistics.
+
+    Args:
+        records: List of chunk hash records
+        top_n: Number of top reused chunks to include
+
+    Returns:
+        Dictionary containing analysis results
+    """
+    all_hashes: List[str] = []
+    unique_hashes: Set[str] = set()
+    lookup_ids: Set[str] = set()
+    hash_frequency: Counter = Counter()
+    request_stats: Dict[str, Dict] = {}
+
+    for record in records:
+        lookup_id = record.get("lookup_id", "unknown")
+        chunk_hashes = record.get("chunk_hashes", [])
+
+        lookup_ids.add(lookup_id)
+        all_hashes.extend(chunk_hashes)
+        unique_hashes.update(chunk_hashes)
+        hash_frequency.update(chunk_hashes)
+
+        if lookup_id not in request_stats:
+            request_stats[lookup_id] = {
+                "chunk_count": len(chunk_hashes),
+                "timestamp": record.get("timestamp", 0),
+            }
+
+    total_chunks = len(all_hashes)
+    unique_chunks = len(unique_hashes)
+    duplicate_chunks = total_chunks - unique_chunks
+    reuse_rate = duplicate_chunks / total_chunks if total_chunks > 0 else 0.0
+
+    # Find most frequently reused chunks
+    top_reused = hash_frequency.most_common(top_n)
+
+    # Per-request statistics
+    chunk_counts = [stats["chunk_count"] for stats in request_stats.values()]
+    avg_chunks = sum(chunk_counts) / len(chunk_counts) if chunk_counts else 0
+    max_chunks = max(chunk_counts) if chunk_counts else 0
+    min_chunks = min(chunk_counts) if chunk_counts else 0
+
+    # Frequency distribution
+    reuse_counts = list(hash_frequency.values())
+    single_use = sum(1 for c in reuse_counts if c == 1)
+    multi_use = len(reuse_counts) - single_use
+
+    return {
+        "total_records": len(records),
+        "total_chunks": total_chunks,
+        "unique_chunks": unique_chunks,
+        "duplicate_chunks": duplicate_chunks,
+        "reuse_rate": reuse_rate,
+        "unique_lookup_ids": len(lookup_ids),
+        "top_reused_chunks": top_reused,
+        "request_stats": {
+            "total_requests": len(request_stats),
+            "avg_chunks_per_request": avg_chunks,
+            "max_chunks_per_request": max_chunks,
+            "min_chunks_per_request": min_chunks,
+        },
+        "frequency_distribution": {
+            "single_use_chunks": single_use,
+            "multi_use_chunks": multi_use,
+            "single_use_percentage": single_use / len(reuse_counts)
+            if reuse_counts
+            else 0,
+            "multi_use_percentage": multi_use / len(reuse_counts)
+            if reuse_counts
+            else 0,
+        },
+    }
+
+
+def print_analysis(analysis: Dict, verbose: bool = False) -> None:
+    """Print analysis results in a readable format.
+
+    Args:
+        analysis: Analysis results dictionary
+        verbose: Whether to print detailed statistics
+    """
+    print("\n" + "=" * 60)
+    print("Chunk Hash Analysis Results")
+    print("=" * 60)
+
+    print("\nBasic Statistics:")
+    print(f"  Total records:        {analysis['total_records']:,}")
+    print(f"  Unique lookup IDs:    {analysis['unique_lookup_ids']:,}")
+    print(f"  Total chunks:         {analysis['total_chunks']:,}")
+    print(f"  Unique chunks:        {analysis['unique_chunks']:,}")
+    print(f"  Duplicate chunks:     {analysis['duplicate_chunks']:,}")
+    print(f"  Reuse rate:           {analysis['reuse_rate']:.2%}")
+
+    if verbose:
+        req_stats = analysis["request_stats"]
+        print("\nPer-Request Statistics:")
+        print(f"  Total requests:       {req_stats['total_requests']:,}")
+        print(f"  Avg chunks/request:   {req_stats['avg_chunks_per_request']:.2f}")
+        print(f"  Max chunks/request:   {req_stats['max_chunks_per_request']:,}")
+        print(f"  Min chunks/request:   {req_stats['min_chunks_per_request']:,}")
+
+        freq_dist = analysis["frequency_distribution"]
+        print("\nFrequency Distribution:")
+        single_pct = freq_dist["single_use_percentage"]
+        multi_pct = freq_dist["multi_use_percentage"]
+        print(
+            f"  Single-use chunks:    "
+            f"{freq_dist['single_use_chunks']:,} ({single_pct:.2%})"
+        )
+        print(
+            f"  Multi-use chunks:     "
+            f"{freq_dist['multi_use_chunks']:,} ({multi_pct:.2%})"
+        )
+
+    top_n = len(analysis["top_reused_chunks"])
+    print(f"\nTop {top_n} Most Reused Chunks:")
+    for i, (chunk_hash, count) in enumerate(analysis["top_reused_chunks"], 1):
+        print(f"  {i:2d}. {chunk_hash[:16]}... (reused {count:,} times)")
+
+    print("\n" + "=" * 60)
+
+
+def analyze_time_series(records: List[Dict]) -> Dict:
+    """Analyze chunk distribution over time.
+
+    Args:
+        records: List of chunk hash records
+
+    Returns:
+        Dictionary containing time-series statistics
+    """
+    hourly_stats: Dict = defaultdict(lambda: {"total": 0, "unique": set()})
+
+    for record in records:
+        timestamp = record.get("timestamp", 0)
+        if timestamp > 0:
+            hour = datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:00")
+            chunk_hashes = record.get("chunk_hashes", [])
+            hourly_stats[hour]["total"] += len(chunk_hashes)
+            hourly_stats[hour]["unique"].update(chunk_hashes)
+
+    # Convert sets to counts for JSON serialization
+    time_series = {}
+    for hour, stats in sorted(hourly_stats.items()):
+        total = stats["total"]
+        unique = len(stats["unique"])
+        reuse_rate = (total - unique) / total if total > 0 else 0.0
+        time_series[hour] = {
+            "total_chunks": total,
+            "unique_chunks": unique,
+            "reuse_rate": reuse_rate,
+        }
+
+    return time_series
+
+
+def estimate_memory(
+    unique_chunks: int, chunk_size: int = 256, bytes_per_token: int = 2
+) -> Dict:
+    """Estimate memory requirements for caching.
+
+    Args:
+        unique_chunks: Number of unique chunks
+        chunk_size: Number of tokens per chunk
+        bytes_per_token: Bytes per token
+
+    Returns:
+        Dictionary containing memory estimates
+    """
+    bytes_per_chunk = chunk_size * bytes_per_token
+    total_memory_bytes = unique_chunks * bytes_per_chunk
+    total_memory_mb = total_memory_bytes / (1024 * 1024)
+    total_memory_gb = total_memory_mb / 1024
+
+    return {
+        "unique_chunks": unique_chunks,
+        "chunk_size_tokens": chunk_size,
+        "bytes_per_token": bytes_per_token,
+        "bytes_per_chunk": bytes_per_chunk,
+        "total_memory_bytes": total_memory_bytes,
+        "total_memory_mb": total_memory_mb,
+        "total_memory_gb": total_memory_gb,
+    }
+
+
+def export_results(
+    analysis: Dict,
+    output_file: Path,
+    include_time_series: bool = False,
+    records: Optional[List[Dict]] = None,
+) -> None:
+    """Export analysis results to a JSON file.
+
+    Args:
+        analysis: Analysis results dictionary
+        output_file: Output file path
+        include_time_series: Whether to include time-series analysis
+        records: Original records (needed for time-series analysis)
+    """
+    # Convert Counter objects to lists for JSON serialization
+    export_data = analysis.copy()
+    export_data["top_reused_chunks"] = [
+        {"hash": h, "count": c} for h, c in analysis["top_reused_chunks"]
+    ]
+
+    # Add memory estimation
+    export_data["memory_estimation"] = estimate_memory(analysis["unique_chunks"])
+
+    # Add time-series analysis if requested
+    if include_time_series and records:
+        export_data["time_series"] = analyze_time_series(records)
+
+    with open(output_file, "w") as f:
+        json.dump(export_data, f, indent=2)
+
+    print(f"\nResults exported to {output_file}")
+
+
+def print_time_series(time_series: Dict) -> None:
+    """Print time-series analysis results.
+
+    Args:
+        time_series: Time-series statistics dictionary
+    """
+    if not time_series:
+        print("\nNo time-series data available")
+        return
+
+    print("\n" + "=" * 70)
+    print("Time-Series Analysis")
+    print("=" * 70)
+    header = (
+        f"\n{'Hour':<20} | {'Total Chunks':>12} | "
+        f"{'Unique Chunks':>13} | {'Reuse Rate':>10}"
+    )
+    print(header)
+    print("-" * 70)
+
+    for hour, stats in sorted(time_series.items()):
+        row = (
+            f"{hour:<20} | {stats['total_chunks']:>12,} | "
+            f"{stats['unique_chunks']:>13,} | {stats['reuse_rate']:>9.2%}"
+        )
+        print(row)
+
+    print("=" * 70)
+
+
+def print_memory_estimation(memory_est: Dict) -> None:
+    """Print memory estimation results.
+
+    Args:
+        memory_est: Memory estimation dictionary
+    """
+    print("\n" + "=" * 60)
+    print("Memory Estimation")
+    print("=" * 60)
+    print(f"\n  Unique chunks:        {memory_est['unique_chunks']:,}")
+    print(f"  Chunk size:           {memory_est['chunk_size_tokens']} tokens")
+    print(f"  Bytes per token:      {memory_est['bytes_per_token']} bytes")
+    print(f"  Bytes per chunk:      {memory_est['bytes_per_chunk']:,} bytes")
+    mem_mb = memory_est["total_memory_mb"]
+    mem_gb = memory_est["total_memory_gb"]
+    print(f"  Total memory:         {mem_mb:.2f} MB ({mem_gb:.2f} GB)")
+    print("=" * 60)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Analyze chunk hash files from LMCache file_hash strategy"
+    )
+    parser.add_argument(
+        "--input-dir",
+        type=Path,
+        default=Path("./chunk_hashes"),
+        help=("Directory containing chunk hash JSONL files (default: ./chunk_hashes)"),
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Output JSON file for analysis results (optional)",
+    )
+    parser.add_argument(
+        "--top-n",
+        type=int,
+        default=10,
+        help="Number of top reused chunks to display (default: 10)",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help=(
+            "Show detailed statistics including per-request and frequency distribution"
+        ),
+    )
+    parser.add_argument(
+        "--time-series",
+        action="store_true",
+        help="Include time-series analysis (hourly breakdown)",
+    )
+    parser.add_argument(
+        "--memory-estimation",
+        action="store_true",
+        help="Show memory estimation for caching unique chunks",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=256,
+        help=("Chunk size in tokens for memory estimation (default: 256)"),
+    )
+    parser.add_argument(
+        "--bytes-per-token",
+        type=int,
+        default=2,
+        help="Bytes per token for memory estimation (default: 2)",
+    )
+
+    args = parser.parse_args()
+
+    if not args.input_dir.exists():
+        print(f"Error: Input directory {args.input_dir} does not exist")
+        return 1
+
+    if not args.input_dir.is_dir():
+        print(f"Error: {args.input_dir} is not a directory")
+        return 1
+
+    # Load and analyze chunk hashes
+    print(f"Loading chunk hashes from {args.input_dir}...")
+    records = load_chunk_hashes(args.input_dir)
+
+    if not records:
+        print("No records found to analyze")
+        return 1
+
+    print(f"Analyzing {len(records)} records...")
+    analysis = analyze_chunk_hashes(records, top_n=args.top_n)
+
+    # Print results
+    print_analysis(analysis, verbose=args.verbose)
+
+    # Time-series analysis
+    if args.time_series:
+        time_series = analyze_time_series(records)
+        print_time_series(time_series)
+
+    # Memory estimation
+    if args.memory_estimation:
+        memory_est = estimate_memory(
+            analysis["unique_chunks"],
+            chunk_size=args.chunk_size,
+            bytes_per_token=args.bytes_per_token,
+        )
+        print_memory_estimation(memory_est)
+
+    # Export results if requested
+    if args.output:
+        export_results(
+            analysis,
+            args.output,
+            include_time_series=args.time_series,
+            records=records if args.time_series else None,
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/examples/chunk_statistics/auto_stop.yaml b/examples/chunk_statistics/auto_stop.yaml
new file mode 100644
index 0000000..0c3dd45
--- /dev/null
+++ b/examples/chunk_statistics/auto_stop.yaml
@@ -0,0 +1,20 @@
+# Enable internal API server for interacting with the chunk statistics API
+internal_api_server_enabled: True
+# Base port for the API server
+# actual_port = internal_api_server_port_start + index
+# Scheduler → 6999 + 0 = 6999
+# Worker 0 → 6999 + 1 = 7000
+internal_api_server_port_start: 6999
+
+# Enable chunk statistics with auto-stop configuration
+enable_chunk_statistics: true
+chunk_statistics_strategy: "file_hash"
+chunk_statistics_auto_start_statistics: true
+extra_config:
+  chunk_statistics_file_output_dir: "/tmp/lmcache_chunk_statistics"
+  chunk_statistics_file_max_count: 10
+  chunk_statistics_file_rotation_size: 10485760  # 10MB for testing
+
+# Auto-stop configuration (small values for testing)
+chunk_statistics_auto_exit_timeout_hours: 0.1  # Stop after 6 minutes
+chunk_statistics_auto_exit_target_unique_chunks: 10000  # Stop after 10K unique chunks
diff --git a/examples/chunk_statistics/file_hash.yaml b/examples/chunk_statistics/file_hash.yaml
new file mode 100644
index 0000000..eba4315
--- /dev/null
+++ b/examples/chunk_statistics/file_hash.yaml
@@ -0,0 +1,15 @@
+# Enable internal API server for interacting with the chunk statistics API
+internal_api_server_enabled: True
+# Base port for the API server
+# actual_port = internal_api_server_port_start + index
+# Scheduler → 6999 + 0 = 6999
+# Worker 0 → 6999 + 1 = 7000
+internal_api_server_port_start: 6999
+# Enable chunk statistics with file hash strategy
+enable_chunk_statistics: true
+chunk_statistics_strategy: "file_hash"
+chunk_statistics_auto_start_statistics: true
+extra_config:
+  chunk_statistics_file_output_dir: "/tmp/lmcache_chunk_statistics"
+  chunk_statistics_file_rotation_size: 104857600  # 100MB
+  chunk_statistics_file_max_count: 100
diff --git a/examples/chunk_statistics/memory_bloom_filter.yaml b/examples/chunk_statistics/memory_bloom_filter.yaml
new file mode 100644
index 0000000..e989212
--- /dev/null
+++ b/examples/chunk_statistics/memory_bloom_filter.yaml
@@ -0,0 +1,16 @@
+# Enable internal API server for interacting with the chunk statistics API
+internal_api_server_enabled: True
+# Base port for the API server
+# actual_port = internal_api_server_port_start + index
+# Scheduler → 6999 + 0 = 6999
+# Worker 0 → 6999 + 1 = 7000
+internal_api_server_port_start: 6999
+# Enable chunk statistics with memory bloom filter strategy
+enable_chunk_statistics: true
+chunk_statistics_strategy: "memory_bloom_filter"
+chunk_statistics_auto_start_statistics: true
+
+# Bloom filter configuration
+extra_config:
+  chunk_statistics_mem_bf_expected_chunks: 20000000
+  chunk_statistics_mem_bf_false_positive_rate: 0.01
diff --git a/examples/disagg_prefill/1p1d/README.md b/examples/disagg_prefill/1p1d/README.md
new file mode 100644
index 0000000..78ebdc3
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/README.md
@@ -0,0 +1,89 @@
+## Example of Disaggregated Prefill in vLLM v1
+
+This example demonstrates how to run LMCache with disaggregated prefill using NIXL on a single node.
+
+### Prerequisites
+
+- Install [LMCache](https://github.com/LMCache/LMCache). You can simply run `pip install lmcache`.
+- Install [NIXL](https://github.com/ai-dynamo/nixl).
+- At least 2 GPUs
+- Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B Instruct.
+
+### Usage
+
+Optionally set the visible devices for prefill and decoder instances through environment variable.
+By default they are set to 0 and 1 respectively.
+
+```bash
+export PREFILLER_DEVICE_ID="1"
+export DECODER_DEVICE_ID="0"
+```
+
+Run
+```bash
+bash disagg_example_1p1d.sh
+```
+
+to start disaggregated prefill and benchmark the performance.
+
+The script will:
+
+1. Launch 1 decoder instances listening on port 7200.
+2. Launch 1 prefill instances listening on ports 7100.
+3. Launch a proxy server, listening on port 9100
+
+Press `Ctrl+C` to stop the servers.
+
+#### Example benchmark command
+
+If you have vLLM's serving benchmark tool, you can run the following command to benchmark the serving performance of the disaggregated prefill setup:
+
+```bash
+vllm bench serve --port 9100 --seed $(date +%s) \
+    --model meta-llama/Llama-3.1-8B-Instruct \
+    --dataset-name random --random-input-len 7500 --random-output-len 200 \
+    --num-prompts 30 --burstiness 100 --request-rate 1 --ignore-eos
+```
+
+Expected output from the benchmark script:
+
+```plaintext
+============ Serving Benchmark Result ============
+Successful requests:                     30
+Benchmark duration (s):                  31.34
+Total input tokens:                      224970
+Total generated tokens:                  6000
+Request throughput (req/s):              0.96
+Output token throughput (tok/s):         191.44
+Total Token throughput (tok/s):          7369.36
+---------------Time to First Token----------------
+Mean TTFT (ms):                          313.41
+Median TTFT (ms):                        272.83
+P99 TTFT (ms):                           837.32
+-----Time per Output Token (excl. 1st token)------
+Mean TPOT (ms):                          8.84
+Median TPOT (ms):                        8.72
+P99 TPOT (ms):                           11.35
+---------------Inter-token Latency----------------
+Mean ITL (ms):                           8.84
+Median ITL (ms):                         8.61
+P99 ITL (ms):                            11.43
+==================================================
+```
+
+### Components
+
+#### Server Scripts
+- `disagg_vllm_launcher.sh` - Launches individual vLLM servers for prefill/decode, and also launches the proxy server.
+- `disagg_proxy_server.py` - FastAPI proxy server that coordinates between prefiller and decoder
+- `disagg_example_1p1d.sh` - Main script to run the example
+
+#### Configuration
+- `configs/lmcache-prefiller-config.yaml` - Configuration for prefiller server
+- `configs/lmcache-decoder-config.yaml` - Configuration for decoder server
+
+#### Log Files
+The main script generates several log files:
+- `prefiller.log` - Logs from the prefill server
+- `decoder.log` - Logs from the decode server
+- `proxy.log` - Logs from the proxy server
diff --git a/examples/disagg_prefill/1p1d/configs/lmcache-decoder-config.yaml b/examples/disagg_prefill/1p1d/configs/lmcache-decoder-config.yaml
new file mode 100644
index 0000000..5130822
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/configs/lmcache-decoder-config.yaml
@@ -0,0 +1,49 @@
+local_cpu: False
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7300
+pd_peer_alloc_port: 7400
+pd_buffer_size: 2147483648 # 2GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
+
diff --git a/examples/disagg_prefill/1p1d/configs/lmcache-decoder-pd-with-remote-config.yaml b/examples/disagg_prefill/1p1d/configs/lmcache-decoder-pd-with-remote-config.yaml
new file mode 100644
index 0000000..339c439
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/configs/lmcache-decoder-pd-with-remote-config.yaml
@@ -0,0 +1,58 @@
+local_cpu: True
+max_local_cpu_size: 5
+
+remote_url: "lm://localhost:6800"
+remote_serde: "cachegen"
+
+retrieve_locations: ["PDBackend"]
+store_location: "RemoteBackend"
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7300
+pd_peer_alloc_port: 7400
+pd_buffer_size: 2147483648 # 2GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+save_decode_cache: true
+save_unfull_chunk: true
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/1p1d/configs/lmcache-prefiller-config.yaml b/examples/disagg_prefill/1p1d/configs/lmcache-prefiller-config.yaml
new file mode 100644
index 0000000..f63e16e
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/configs/lmcache-prefiller-config.yaml
@@ -0,0 +1,47 @@
+local_cpu: False
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "sender"
+pd_proxy_host: "localhost"
+pd_proxy_port: 7500
+pd_buffer_size: 1073741824 # 1GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally 
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/1p1d/configs/lmcache-prefiller-pd-with-remote-config.yaml b/examples/disagg_prefill/1p1d/configs/lmcache-prefiller-pd-with-remote-config.yaml
new file mode 100644
index 0000000..d24fb9b
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/configs/lmcache-prefiller-pd-with-remote-config.yaml
@@ -0,0 +1,55 @@
+local_cpu: True
+max_local_cpu_size: 5
+
+remote_url: "lm://localhost:6800"
+remote_serde: "cachegen"
+
+retrieve_locations: ["LocalCPUBackend", "RemoteBackend"]
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "sender"
+pd_proxy_host: "localhost"
+pd_proxy_port: 7500
+pd_buffer_size: 1073741824 # 1GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+save_unfull_chunk: true
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/1p1d/disagg_example_1p1d.sh b/examples/disagg_prefill/1p1d/disagg_example_1p1d.sh
new file mode 100644
index 0000000..c0ca5e9
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/disagg_example_1p1d.sh
@@ -0,0 +1,176 @@
+#!/bin/bash
+
+echo "Warning: LMCache disaggregated prefill support for vLLM v1 is experimental and subject to change."
+
+
+PIDS=()
+
+# Switch to the directory of the current script
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+check_hf_token() {
+    if [ -z "$HF_TOKEN" ]; then
+        echo "HF_TOKEN is not set. Please set it to your Hugging Face token."
+        exit 1
+    fi
+    if [[ "$HF_TOKEN" != hf_* ]]; then
+        echo "HF_TOKEN is not a valid Hugging Face token. Please set it to your Hugging Face token."
+        exit 1
+    fi
+    echo "HF_TOKEN is set and valid."
+}
+
+check_num_gpus() {
+    # can you check if the number of GPUs are >=2 via nvidia-smi?
+    num_gpus=$(nvidia-smi --query-gpu=name --format=csv,noheader | wc -l)
+    if [ "$num_gpus" -lt 2 ]; then
+        echo "You need at least 2 GPUs to run disaggregated prefill."
+        exit 1
+    else
+        echo "Found $num_gpus GPUs."
+    fi
+}
+
+ensure_python_library_installed() {
+    echo "Checking if $1 is installed..."
+    python -c "import $1" > /dev/null 2>&1
+    if [ $? -ne 0 ]; then
+        if [ "$1" == "nixl" ]; then
+            echo "$1 is not installed. Please refer to https://github.com/ai-dynamo/nixl for installation."
+        else
+            echo "$1 is not installed. Please install it via pip install $1."
+        fi
+        exit 1
+    else
+        echo "$1 is installed."
+    fi
+}
+
+cleanup() {
+    echo "Stopping everything…"
+    trap - INT TERM USR1   # prevent re-entrancy
+    
+    # Kill all tracked PIDs
+    for pid in "${PIDS[@]}"; do
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "Killing process $pid"
+            kill "$pid" 2>/dev/null
+        fi
+    done
+    
+    # Wait a moment for graceful shutdown
+    sleep 2
+    
+    # Force kill any remaining processes
+    for pid in "${PIDS[@]}"; do
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "Force killing process $pid"
+            kill -9 "$pid" 2>/dev/null
+        fi
+    done
+    
+    # Kill the entire process group as backup
+    kill -- -$$ 2>/dev/null
+    
+    echo "All processes stopped."
+    exit 0
+}
+
+wait_for_server() {
+  local port=$1
+  local timeout_seconds=1200
+  local start_time=$(date +%s)
+
+  echo "Waiting for server on port $port..."
+
+  while true; do
+    if curl -s "localhost:${port}/v1/completions" > /dev/null; then
+      return 0
+    fi
+
+    local now=$(date +%s)
+    if (( now - start_time >= timeout_seconds )); then
+      echo "Timeout waiting for server"
+      return 1
+    fi
+
+    sleep 1
+  done
+}
+
+
+main() {
+    # Usage: main [model] [pd_buffer_size_bytes]
+    # Defaults: meta-llama/Llama-3.1-8B-Instruct, 2147483648 (2 GB)
+    MODEL=${1:-meta-llama/Llama-3.1-8B-Instruct}
+    PD_BUFFER_SIZE=${2:-2147483648}
+
+    check_hf_token
+    check_num_gpus
+    ensure_python_library_installed lmcache
+    ensure_python_library_installed nixl
+    ensure_python_library_installed pandas
+    ensure_python_library_installed datasets
+    ensure_python_library_installed vllm
+
+    trap cleanup INT
+    trap cleanup USR1
+    trap cleanup TERM
+
+    echo "Model: $MODEL"
+    echo "PD buffer size: $PD_BUFFER_SIZE bytes"
+    echo "Launching prefiller, decoder and proxy..."
+    echo "Please check prefiller.log, decoder.log and proxy.log for logs."
+
+    # Launch the proxy first
+    python3 ../disagg_proxy_server.py \
+        --host localhost \
+        --port 9100 \
+        --prefiller-host localhost \
+        --prefiller-port 7100 \
+        --num-prefillers 1 \
+        --decoder-host localhost \
+        --decoder-port 7200  \
+        --decoder-init-port 7300 \
+        --decoder-alloc-port 7400 \
+        --proxy-host localhost \
+        --proxy-port 7500 \
+        --num-decoders 1 \
+        --model "$MODEL" \
+        --pd-buffer-size "$PD_BUFFER_SIZE" \
+        > >(tee proxy.log)    2>&1 &
+    proxy_pid=$!
+    PIDS+=($proxy_pid)
+
+
+    # Launch the decoder
+    bash disagg_vllm_launcher.sh decoder "$MODEL" \
+        > >(tee decoder.log)  2>&1 &
+    decoder_pid=$!
+    PIDS+=($decoder_pid)
+
+
+    # Launch the prefiller next
+    bash disagg_vllm_launcher.sh prefiller "$MODEL" \
+        > >(tee prefiller.log) 2>&1 &
+    prefiller_pid=$!
+    PIDS+=($prefiller_pid)
+
+    wait_for_server 7200
+    wait_for_server 7100
+    wait_for_server 9100
+
+    echo "==================================================="
+    echo "All servers are up. You can send request now..."
+    echo "Press Ctrl-C to terminate all instances."
+
+    # Keep the script running until interrupted
+    echo "Script is running. Waiting for termination signal..."
+    echo "==================================================="
+
+    while true; do
+        sleep 1
+    done
+}
+
+main "$@"
diff --git a/examples/disagg_prefill/1p1d/disagg_vllm_launcher.sh b/examples/disagg_prefill/1p1d/disagg_vllm_launcher.sh
new file mode 100644
index 0000000..14a4527
--- /dev/null
+++ b/examples/disagg_prefill/1p1d/disagg_vllm_launcher.sh
@@ -0,0 +1,62 @@
+#!/bin/bash
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# NOTE: For correct KV cache transfer, ensure all processes use the same PYTHONHASHSEED to keep the hash of the KV cache consistent across processes.
+export PYTHONHASHSEED=0
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <prefiller | decoder> [model]"
+    exit 1
+fi
+
+if [[ $# -eq 1 ]]; then
+    echo "Using default model: meta-llama/Llama-3.1-8B-Instruct"
+    MODEL="meta-llama/Llama-3.1-8B-Instruct"
+else
+    echo "Using model: $2"
+    MODEL=$2
+fi
+
+
+if [[ $1 == "prefiller" ]]; then
+    # Prefiller listens on port 7100
+    prefill_config_file=$SCRIPT_DIR/configs/lmcache-prefiller-config.yaml
+
+    UCX_TLS=cuda_ipc,cuda_copy,tcp \
+        LMCACHE_CONFIG_FILE=$prefill_config_file \
+        VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+        VLLM_WORKER_MULTIPROC_METHOD=spawn \
+        CUDA_VISIBLE_DEVICES=${PREFILLER_DEVICE_ID:-0} \
+        vllm serve $MODEL \
+        --port 7100 \
+        --enforce-eager \
+        --no-enable-prefix-caching \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer1"}}'
+
+
+
+
+elif [[ $1 == "decoder" ]]; then
+    # Decoder listens on port 7200
+    decode_config_file=$SCRIPT_DIR/configs/lmcache-decoder-config.yaml
+
+    UCX_TLS=cuda_ipc,cuda_copy,tcp \
+        LMCACHE_CONFIG_FILE=$decode_config_file \
+        VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+        VLLM_WORKER_MULTIPROC_METHOD=spawn \
+        CUDA_VISIBLE_DEVICES=${DECODER_DEVICE_ID:-1} \
+        vllm serve $MODEL \
+        --port 7200 \
+        --enforce-eager \
+        --no-enable-prefix-caching \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer1", "skip_last_n_tokens": 1}}'
+
+
+else
+    echo "Invalid role: $1"
+    echo "Should be either prefill, decode"
+    exit 1
+fi
diff --git a/examples/disagg_prefill/README.md b/examples/disagg_prefill/README.md
new file mode 100644
index 0000000..3f54beb
--- /dev/null
+++ b/examples/disagg_prefill/README.md
@@ -0,0 +1,81 @@
+# Disaggregated Prefill Examples for LMCache with vLLM v1
+
+This directory contains examples demonstrating how to run LMCache with disaggregated prefill using NIXL. Disaggregated prefill allows you to separate the prefill (prompt processing) and decode (token generation) phases of LLM inference across different GPU instances, enabling better resource utilization and scalability.
+
+## Overview
+
+Disaggregated prefill architecture separates the compute-intensive prefill phase from the memory-intensive decode phase:
+
+- **Prefill servers**: Handle prompt processing and KV cache generation
+- **Decode server**: Handles token generation using cached KV states
+- **Proxy server**: Coordinates requests between prefill and decode servers
+
+This architecture provides several benefits:
+- Better GPU utilization by matching workload characteristics to hardware
+- Improved scalability by independently scaling prefill and decode capacity
+- Reduced latency through parallel processing
+- Cost optimization by using different instance types for different phases
+
+## Available Examples
+
+### 1p1d - Single Prefill, Single Decode
+Directory: [`1p1d/`](./1p1d/)
+
+**Requirements**: At least 2 GPUs
+
+This is the simplest configuration to get started with disaggregated prefill.
+
+### xpyd - Multiple Prefill, Multiple Decode
+Directory: [`xpyd/`](./xpyd/)
+
+**Requirements**: At least 3 GPUs
+
+This configuration demonstrates multiple prefills and multiple decodes.
+
+## Prerequisites
+
+Before running any example, ensure you have:
+
+- [LMCache](https://github.com/LMCache/LMCache) installed: `pip install lmcache`
+- [NIXL](https://github.com/ai-dynamo/nixl) installed
+- Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B Instruct
+- Sufficient GPU resources (see individual example requirements)
+
+## Quick Start & Benchmarking
+
+1. Choose the appropriate example based on your GPU resources:
+   - For 2 GPUs: Use [`1p1d/`](./1p1d/)
+   - For 3+ GPUs: Use [`xpyd/`](./xpyd/)
+
+2. Navigate to the chosen directory:
+   ```bash
+   cd 1p1d/  # or cd xpyd/
+   ```
+
+3. Follow the specific README instructions in that directory
+
+
+## Architecture Components
+
+Each example includes:
+
+- **Main script**: `disagg_example_*.sh` - Main entry point to run the example
+- **Launcher script**: `disagg_vllm_launcher.sh` - Launches vLLM servers and proxy
+- **Proxy server**: `disagg_proxy_server.py` - FastAPI server coordinating requests
+- **Configuration files**: YAML configs for prefill and decode servers
+- **Log files**: Generated during execution for debugging
+
+## Troubleshooting
+
+- **GPU Memory Issues**: Ensure you have sufficient VRAM for the model on each GPU
+- **Port Conflicts**: Check that ports 8100, 8101, 8200, and 9000 are available
+- **HF Token**: Verify your Hugging Face token has access to Llama 3.1 models
+- **Dependencies**: Ensure both LMCache and NIXL are properly installed
+
+For detailed troubleshooting, check the log files generated in each example directory.
+
+## Further Reading
+
+- [LMCache Documentation](https://github.com/LMCache/LMCache)
+- [NIXL Documentation](https://github.com/ai-dynamo/nixl)
+- [vLLM Documentation](https://docs.vllm.ai/) 
\ No newline at end of file
diff --git a/examples/disagg_prefill/disagg_proxy_server.py b/examples/disagg_prefill/disagg_proxy_server.py
new file mode 100644
index 0000000..0aa035e
--- /dev/null
+++ b/examples/disagg_prefill/disagg_proxy_server.py
@@ -0,0 +1,785 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import defaultdict
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Optional
+import argparse
+import asyncio
+import itertools
+import json
+import math
+import os
+import time
+
+# Third Party
+from fastapi import FastAPI, Request
+from fastapi.responses import StreamingResponse
+import httpx
+import msgspec
+import numpy as np
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.pd_backend import (
+    PDMsg,
+    ProxyNotif,
+)
+
+logger = init_logger(__name__)
+
+
+class WeightedSemaphore:
+    """Async semaphore with variable-weight acquire.
+
+    Limits in-flight PD token usage: each request holds ceil(L/chunk_size)
+    slots until decoding starts, preventing decoder buffer exhaustion deadlocks.
+    """
+
+    def __init__(self, capacity: int) -> None:
+        self._capacity = capacity
+        self._available = capacity
+        self._lock = asyncio.Condition()
+
+    async def acquire(self, slots: int) -> None:
+        """Acquire *slots* from the semaphore, blocking until available.
+
+        Args:
+            slots: Number of slots to acquire (must be <= capacity).
+
+        Raises:
+            ValueError: If slots exceeds total capacity (would block forever).
+        """
+        if slots > self._capacity:
+            raise ValueError(
+                f"Requested {slots} slots exceeds total capacity {self._capacity}"
+            )
+        async with self._lock:
+            await self._lock.wait_for(lambda: self._available >= slots)
+            self._available -= slots
+
+    async def release(self, slots: int) -> None:
+        """Return *slots* to the semaphore and wake waiting acquirers.
+
+        Args:
+            slots: Number of slots to release. No-op if <= 0.
+        """
+        if slots <= 0:
+            return
+        async with self._lock:
+            self._available += slots
+            self._lock.notify_all()
+
+    @property
+    def available(self) -> int:
+        """Number of slots currently available."""
+        return self._available
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lifespan context manager to handle startup and shutdown events.
+    """
+    # Startup: Initialize clients
+
+    # Build prefill clients with CSV-based broadcast pairing
+    pref_hosts = global_args.prefiller_host
+    pref_ports = global_args.prefiller_port
+
+    def pair_hosts_and_ports(hosts, ports, count=None):
+        """
+        Flexible host-port pairing with expansion strategies.
+
+        Multiple pairing strategies:
+        1. Single host + single port + count: Generate incremental ports on same host
+        2. Single host + multiple ports: Pair the host with each port
+        3. Multiple hosts + single port: Pair each host with the same port
+        4. Multiple hosts + multiple ports: Strict one-to-one pairing
+           (must have same length)
+        """
+        # Ensure lists
+        if not isinstance(hosts, list):
+            hosts = [hosts]
+        if not isinstance(ports, list):
+            ports = [ports]
+        # Single host/port with count -> incremental ports
+        if len(hosts) == 1 and len(ports) == 1:
+            if count is None or count <= 1:
+                return [(hosts[0], ports[0])]
+            else:
+                return [(hosts[0], ports[0] + i) for i in range(count)]
+        # Expand single host to multiple ports
+        if len(hosts) == 1:
+            return [(hosts[0], p) for p in ports]
+        # Expand single port to multiple hosts
+        if len(ports) == 1:
+            return [(h, ports[0]) for h in hosts]
+        # Strict one-to-one pairing when both lists are provided
+        if len(hosts) != len(ports):
+            raise ValueError(
+                "Length mismatch between hosts and ports lists for pairing"
+            )
+        return list(zip(hosts, ports, strict=False))
+
+    prefill_pairs = pair_hosts_and_ports(
+        pref_hosts, pref_ports, global_args.num_prefillers
+    )
+    for host, port in prefill_pairs:
+        prefiller_base_url = f"http://{host}:{int(port)}"
+        prefill_client = httpx.AsyncClient(timeout=None, base_url=prefiller_base_url)
+        app.state.prefill_clients.append(
+            ClientInfo(
+                prefill_client,
+            )
+        )
+
+    # Build decoder clients with CSV-based broadcast pairing
+    dec_hosts = global_args.decoder_host
+    dec_ports = global_args.decoder_port
+
+    decoder_pairs = pair_hosts_and_ports(dec_hosts, dec_ports, global_args.num_decoders)
+
+    # Whether the ports increase per instances
+    # (only when using single host/port with num_decoders > 1)
+    incremental_mode = (
+        len(dec_hosts) == 1 and len(dec_ports) == 1 and global_args.num_decoders > 1
+    )
+
+    for i, (host, port) in enumerate(decoder_pairs):
+        decoder_base_url = f"http://{host}:{int(port)}"
+        decode_client = httpx.AsyncClient(timeout=None, base_url=decoder_base_url)
+        if incremental_mode:
+            init_ports = [p + i for p in global_args.decoder_init_port]
+            alloc_ports = [p + i for p in global_args.decoder_alloc_port]
+        else:
+            # Use the provided ports as-is
+            # (suitable when different hosts can reuse same port numbers)
+            init_ports = list(global_args.decoder_init_port)
+            alloc_ports = list(global_args.decoder_alloc_port)
+
+        app.state.decode_clients.append(
+            ClientInfo(
+                decode_client,
+                host,
+                init_ports,
+                alloc_ports,
+            )
+        )
+
+    app.state.total_clients = app.state.prefill_clients + app.state.decode_clients
+
+    app.state.zmq_task = asyncio.create_task(zmq_pull_server())
+
+    global pd_buffer_semaphore
+    kv_bytes_per_token = compute_kv_bytes_per_token(global_args.model)
+    capacity_slots = global_args.pd_buffer_size // (
+        kv_bytes_per_token * global_args.chunk_size
+    )
+    pd_buffer_semaphore = WeightedSemaphore(capacity_slots)
+    logger.info(
+        "PD buffer semaphore: capacity=%d slots"
+        " (%d bytes / (%d bytes/tok * %d chunk_size)) for model %s.",
+        capacity_slots,
+        global_args.pd_buffer_size,
+        kv_bytes_per_token,
+        global_args.chunk_size,
+        global_args.model,
+    )
+
+    yield
+
+    # Shutdown: Close clients
+    for client in app.state.prefill_clients:
+        await client.aclose()
+    for client in app.state.decode_clients:
+        await client.aclose()
+
+    global run_proxy
+    run_proxy = False
+    await app.state.zmq_task  # Wait for background task to finish
+
+
+# Update FastAPI app initialization to use lifespan
+app = FastAPI(lifespan=lifespan)
+
+
+class StatsCalculator:
+    def __init__(self):
+        self._stats = []
+        self._last_log_time = time.time()
+
+    def add(self, value):
+        self._stats.append(value)
+        if time.time() - self._last_log_time > 5:
+            self._log_stats()
+            self._last_log_time = time.time()
+
+    def _log_stats(self):
+        # Print average, median, and 99th percentile
+        np_arr = np.array(self._stats) * 1000
+        output_str = (
+            f"\nNum requests: {len(self._stats)}"
+            + "\nPrefill node TTFT stats:"
+            + f"\n - Average (ms): {np.mean(np_arr)}"
+            + f"\n - Median (ms): {np.median(np_arr)}"
+            + f"\n - 99th Percentile (ms): {np.percentile(np_arr, 99)}\n"
+        )
+        print(
+            "===============================",
+            output_str,
+            "===============================",
+        )
+
+
+stats_calculator = StatsCalculator()
+counter = 0
+
+
+def csv_ints(s):
+    return [int(x) for x in s.split(",")]
+
+
+def csv_strs(s):
+    return [x.strip() for x in s.split(",")]
+
+
+def compute_kv_bytes_per_token(model_name: str) -> int:
+    """Return the number of KV cache bytes per token for *model_name*.
+
+    Reads num_hidden_layers, num_key_value_heads, head_dim, and torch_dtype
+    from the HuggingFace config without downloading model weights.
+
+    Args:
+        model_name: HuggingFace model id or local path.
+
+    Returns:
+        Bytes per token across all layers and both K/V tensors.
+    """
+    # Third Party
+    from transformers import AutoConfig
+
+    cfg = AutoConfig.from_pretrained(model_name)
+    num_layers: int = cfg.num_hidden_layers
+    num_kv_heads: int = getattr(cfg, "num_key_value_heads", cfg.num_attention_heads)
+    head_dim: int = getattr(cfg, "head_dim", cfg.hidden_size // cfg.num_attention_heads)
+    # 4 bytes for float32, 2 bytes for float16/bfloat16 (the common default)
+    torch_dtype = str(getattr(cfg, "torch_dtype", "bfloat16"))
+    dtype_bytes = 4 if "float32" in torch_dtype else 2
+    return 2 * num_layers * num_kv_heads * head_dim * dtype_bytes
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--host", type=str, default="localhost")
+    parser.add_argument("--prefiller-host", type=csv_strs, default=["localhost"])
+    parser.add_argument("--prefiller-port", type=csv_ints, default=[8100])
+    parser.add_argument("--num-prefillers", type=int, default=1)
+    parser.add_argument("--decoder-host", type=csv_strs, default=["localhost"])
+    parser.add_argument("--decoder-port", type=csv_ints, default=[8200])
+    parser.add_argument("--decoder-init-port", type=csv_ints, default=[8300])
+    parser.add_argument("--decoder-alloc-port", type=csv_ints, default=[8400])
+
+    parser.add_argument("--num-decoders", type=int, default=1)
+    parser.add_argument("--proxy-host", type=str, default="localhost")
+    parser.add_argument("--proxy-port", type=int, default=8500)
+
+    # PD buffer concurrency limiting. A weighted semaphore caps in-flight
+    # chunk slots to prevent decoder buffer exhaustion deadlocks.
+    # capacity_slots = pd_buffer_size // (kv_bytes_per_token * chunk_size)
+    # kv_bytes_per_token is derived from the model config automatically.
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="meta-llama/Llama-3.1-8B-Instruct",
+        help=(
+            "HuggingFace model name or local path. Used to derive"
+            " kv_bytes_per_token for the PD buffer semaphore capacity."
+        ),
+    )
+    parser.add_argument(
+        "--pd-buffer-size",
+        type=int,
+        default=2 * 1024 * 1024 * 1024,  # 2 GB
+        help=(
+            "PD transfer buffer size in bytes (must match the decoder's"
+            " LMCache config). Used to derive the in-flight slot capacity."
+            " Default: 2 GB."
+        ),
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=256,
+        help="LMCache chunk size in tokens (must match the LMCache config).",
+    )
+
+    args = parser.parse_args()
+    return args
+
+
+@dataclass
+class ClientInfo:
+    client: httpx.AsyncClient
+    host: Optional[str] = None
+    init_port: Optional[list[int]] = None
+    alloc_port: Optional[list[int]] = None
+
+
+# Initialize variables to hold the persistent clients
+app.state.prefill_clients = []
+app.state.decode_clients = []
+app.state.total_clients = []
+
+"""
+client_request and prefill/decode map
+key:   str    - unique id for requests across same conversation
+value: tuple  - (tokenization_client, prefiller_client, decoder_client)
+"""
+app.state.bound_clients = {}
+
+# Keep finished reqs
+app.state.finished_reqs = defaultdict(int)
+
+pd_buffer_semaphore: Optional[WeightedSemaphore] = None
+
+
+zmq_ctx = zmq.asyncio.Context()
+run_proxy = True  # Shutdown flag
+
+
+async def zmq_pull_server():
+    socket = zmq_ctx.socket(zmq.PULL)
+    proxy_url = f"{global_args.proxy_host}:{global_args.proxy_port}"
+    try:
+        socket.bind(f"tcp://{proxy_url}")
+    except zmq.ZMQError:
+        logger.exception("ZMQ proxy server failed to bind on %s", proxy_url)
+        return
+    logger.info("ZMQ proxy server started on %s", proxy_url)
+
+    while run_proxy:
+        try:
+            msg_bytes = await socket.recv()
+        except zmq.Again:
+            await asyncio.sleep(0.01)  # Avoid busy loop
+            continue
+        except zmq.ZMQError as exc:
+            if exc.errno in (zmq.ETERM, zmq.ENOTSOCK):
+                break
+            logger.warning("ZMQ recv error: %s", exc)
+            await asyncio.sleep(0.05)
+            continue
+
+        try:
+            msg = msgspec.msgpack.decode(msg_bytes, type=PDMsg)
+        except msgspec.DecodeError as exc:
+            logger.warning("ZMQ received non-PD message: %s", exc)
+            continue
+        except Exception as exc:
+            logger.exception("ZMQ message decode failed: %s", exc)
+            continue
+
+        if not isinstance(msg, ProxyNotif):
+            logger.debug("ZMQ ignored message type: %s", type(msg).__name__)
+            continue
+
+        req_id = msg.req_id
+        app.state.finished_reqs[req_id] += 1
+        logger.debug("Prefill of req %s done.", req_id)
+
+    socket.close()
+    logger.info("ZMQ PULL server stopped.")
+
+
+async def send_request_to_service(
+    client: httpx.AsyncClient, endpoint: str, req_data: dict
+):
+    """
+    Send a request to a service using a persistent client.
+    """
+
+    headers = {"Authorization": f"Bearer {os.environ.get('OPENAI_API_KEY')}"}
+    response = await client.post(endpoint, json=req_data, headers=headers)
+    response.raise_for_status()
+    return response
+
+
+async def stream_service_response(
+    client: httpx.AsyncClient, endpoint: str, req_data: dict
+):
+    """
+    Asynchronously stream the response from a service using a persistent client.
+    """
+    headers = {"Authorization": f"Bearer {os.environ.get('OPENAI_API_KEY')}"}
+    async with client.stream(
+        "POST", endpoint, json=req_data, headers=headers
+    ) as response:
+        response.raise_for_status()
+        async for chunk in response.aiter_bytes():
+            yield chunk
+
+
+def round_robin_pick_client(clients, idx):
+    return clients[idx % len(clients)]
+
+
+round_robin_counter = itertools.count()
+
+
+def round_robin_pick_clients() -> tuple[ClientInfo, ClientInfo, ClientInfo]:
+    idx = next(round_robin_counter)
+    tokenization_client = round_robin_pick_client(app.state.total_clients, idx)
+    prefill_client = round_robin_pick_client(app.state.prefill_clients, idx)
+    decode_client = round_robin_pick_client(app.state.decode_clients, idx)
+    return tokenization_client, prefill_client, decode_client
+
+
+async def wait_decode_kv_ready(req_id: str, num_tp_rank: int):
+    while app.state.finished_reqs[req_id] < num_tp_rank:
+        await asyncio.sleep(0.0001)  # sleep for 0.1 ms
+    logger.debug(f"Prefill node signaled kv ready for req {req_id}")
+    app.state.finished_reqs.pop(req_id)
+
+
+BOUND_CLIENTS_MAX_NUM = 1024 * 1024
+
+
+def pick_up_bound_clients(client_id: str) -> tuple[ClientInfo, ClientInfo, ClientInfo]:
+    if client_id not in app.state.bound_clients:
+        if len(app.state.bound_clients) >= BOUND_CLIENTS_MAX_NUM:
+            # Here simply clear the bound_clients if full
+            app.state.bound_clients.clear()
+        app.state.bound_clients[client_id] = round_robin_pick_clients()
+    return app.state.bound_clients[client_id]
+
+
+BOUND_CLIENT = os.getenv("CLIENT_BOUND", "false").lower() == "true"
+# CLIENT_BOUND_KEY, the field name of the client uid in http request
+CLIENT_BOUND_KEY = os.getenv("CLIENT_BOUND_KEY", "session-id")
+
+
+def pick_up_clients(request: Request) -> tuple[ClientInfo, ClientInfo, ClientInfo]:
+    bound_client_id = request.headers.get(CLIENT_BOUND_KEY) if BOUND_CLIENT else None
+    if bound_client_id:
+        # Use or create a persistent set of clients for the session.
+        return pick_up_bound_clients(bound_client_id)
+    return round_robin_pick_clients()
+
+
+@app.post("/v1/completions")
+async def handle_completions(request: Request):
+    global counter, stats_calculator
+    counter += 1
+    req_id = str(counter)  # we use counter as req_id
+
+    st = time.time()
+    slots = 0  # slots to release on error; set after successful acquire only
+    acquired = False
+    try:
+        req_data = await request.json()
+
+        # Pick tokenization, prefill and decode client
+        tokenization_client, prefill_client, decode_client = pick_up_clients(request)
+
+        tokenize_output = await send_request_to_service(
+            tokenization_client.client, "/tokenize", {"prompt": req_data["prompt"]}
+        )
+        tokenize_output = tokenize_output.json()
+
+        org_max_tokens = req_data["max_tokens"]
+        req_data["prompt"] = tokenize_output["tokens"]
+        req_data["max_tokens"] = 1
+
+        # Acquire ceil(L/chunk_size) PD buffer slots before prefill.
+        slots = math.ceil(len(tokenize_output["tokens"]) / global_args.chunk_size)
+        if pd_buffer_semaphore is not None:
+            await pd_buffer_semaphore.acquire(slots)
+            acquired = True
+
+        disagg_spec = {
+            "req_id": req_id,
+            "receiver_host": decode_client.host,
+            "receiver_init_port": decode_client.init_port,
+            "receiver_alloc_port": decode_client.alloc_port,
+        }
+        num_tp_rank = len(decode_client.init_port or [])
+
+        req_data["kv_transfer_params"] = {
+            "ret_first_tok": True,
+            "disagg_spec": disagg_spec,
+        }
+
+        req_data["stream"] = False
+        stream_options = req_data.pop("stream_options", None)
+
+        # Send request to prefill service, ignore the response
+        prefill_output = await send_request_to_service(
+            prefill_client.client, "/v1/completions", req_data
+        )
+
+        prefill_output = prefill_output.json()
+
+        et = time.time()
+        stats_calculator.add(et - st)
+
+        req_data["max_tokens"] = org_max_tokens - 1
+        req_data["prompt"].append(prefill_output["kv_transfer_params"]["first_tok"])
+        req_data.pop("kv_transfer_params")
+        req_data["stream"] = True
+        if stream_options is not None:
+            req_data["stream_options"] = stream_options
+
+        # Stream response from decode service
+        async def generate_stream():
+            head_chunk = {
+                "id": prefill_output["id"],
+                "object": "text_completion",
+                "created": prefill_output["created"],
+                "model": prefill_output["model"],
+                "choices": [
+                    {
+                        "index": 0,
+                        "text": prefill_output["choices"][0]["text"],
+                        "logprobs": None,
+                        "finish_reason": None,
+                        "stop_reason": None,
+                    }
+                ],
+                "usage": None,
+            }
+            yield (
+                "data: " + json.dumps(head_chunk, separators=(",", ":")) + "\n\n"
+            ).encode()
+
+            try:
+                await wait_decode_kv_ready(req_id, num_tp_rank)
+            finally:
+                if pd_buffer_semaphore is not None:
+                    await pd_buffer_semaphore.release(slots)
+
+            async for chunk in stream_service_response(
+                decode_client.client, "/v1/completions", req_data
+            ):
+                yield chunk
+
+        return StreamingResponse(generate_stream(), media_type="application/json")
+
+    except Exception as e:
+        if pd_buffer_semaphore is not None and acquired:
+            await pd_buffer_semaphore.release(slots)
+        # Standard
+        import sys
+        import traceback
+
+        exc_info = sys.exc_info()
+        print("Error occurred in disagg prefill proxy server - completions endpoint")
+        print(e)
+        print("".join(traceback.format_exception(*exc_info)))
+        raise
+
+
+@app.post("/v1/chat/completions")
+async def handle_chat_completions(request: Request):
+    global counter, stats_calculator
+    counter += 1
+    req_id = str(counter)
+
+    st = time.time()
+    slots = 0  # slots to release on error; set after successful acquire only
+    acquired = False
+    try:
+        req_data = await request.json()
+
+        # Pick tokenization, prefill and decode client
+        tokenization_client, prefill_client, decode_client = pick_up_clients(request)
+
+        # For chat completions, we need to tokenize the messages
+        tokenize_output = await send_request_to_service(
+            tokenization_client.client, "/tokenize", {"messages": req_data["messages"]}
+        )
+        tokenize_output = tokenize_output.json()
+
+        org_max_tokens = req_data["max_tokens"]
+        req_data["prompt"] = tokenize_output["tokens"]
+        req_data["max_tokens"] = 1
+
+        org_max_completion_tokens = None
+        if "max_completion_tokens" in req_data:
+            org_max_completion_tokens = req_data["max_completion_tokens"]
+            req_data["max_completion_tokens"] = 1
+
+        # Acquire ceil(L/chunk_size) PD buffer slots before prefill.
+        slots = math.ceil(len(tokenize_output["tokens"]) / global_args.chunk_size)
+        if pd_buffer_semaphore is not None:
+            await pd_buffer_semaphore.acquire(slots)
+            acquired = True
+
+        disagg_spec = {
+            "req_id": req_id,
+            "receiver_host": decode_client.host,
+            "receiver_init_port": decode_client.init_port,
+            "receiver_alloc_port": decode_client.alloc_port,
+        }
+
+        num_tp_rank = len(decode_client.init_port or [])
+
+        req_data["kv_transfer_params"] = {
+            "ret_first_tok": True,
+            "disagg_spec": disagg_spec,
+        }
+
+        req_data["stream"] = False
+        stream_options = req_data.pop("stream_options", None)
+
+        # Send request to prefill service, get the response
+        prefill_output = await send_request_to_service(
+            prefill_client.client, "/v1/completions", req_data
+        )
+
+        prefill_output = prefill_output.json()
+
+        et = time.time()
+        stats_calculator.add(et - st)
+
+        req_data["max_tokens"] = org_max_tokens - 1
+        if org_max_completion_tokens is not None:
+            req_data["max_completion_tokens"] = org_max_completion_tokens - 1
+
+        # Add the first token from prefill to the tokenized messages for decode
+        req_data["prompt"].append(prefill_output["kv_transfer_params"]["first_tok"])
+
+        req_data.pop("kv_transfer_params")
+        req_data["stream"] = True
+        if stream_options is not None:
+            req_data["stream_options"] = stream_options
+
+        # Stream response from decode service
+        async def generate_stream():
+            initial_chunk = {
+                "id": prefill_output["id"],
+                "object": "chat.completion.chunk",
+                "created": prefill_output["created"],
+                "model": prefill_output["model"],
+                "choices": [
+                    {
+                        "index": 0,
+                        "delta": {"role": "assistant", "content": ""},
+                        "logprobs": None,
+                        "finish_reason": None,
+                    }
+                ],
+            }
+            yield (
+                "data: " + json.dumps(initial_chunk, separators=(",", ":")) + "\n\n"
+            ).encode()
+
+            head_chunk = {
+                "id": prefill_output["id"],
+                "object": "chat.completion.chunk",
+                "created": prefill_output["created"],
+                "model": prefill_output["model"],
+                "choices": [
+                    {
+                        "index": 0,
+                        "delta": {"content": prefill_output["choices"][0]["text"]},
+                        "logprobs": None,
+                        "finish_reason": None,
+                    }
+                ],
+            }
+            yield (
+                "data: " + json.dumps(head_chunk, separators=(",", ":")) + "\n\n"
+            ).encode()
+
+            try:
+                await wait_decode_kv_ready(req_id, num_tp_rank)
+            finally:
+                if pd_buffer_semaphore is not None:
+                    await pd_buffer_semaphore.release(slots)
+
+            # Stream and convert completion format chunks to chat completion format
+            async for chunk in stream_service_response(
+                decode_client.client, "/v1/completions", req_data
+            ):
+                chunk_str = chunk.decode("utf-8")
+                if chunk_str.startswith("data: ") and not chunk_str.startswith(
+                    "data: [DONE]"
+                ):
+                    try:
+                        json_str = chunk_str[6:].strip()  # Remove 'data: ' prefix
+                        if json_str:
+                            completion_data = json.loads(json_str)
+                            # Decoder can emit non-token chunks (usage, final
+                            # metadata, keepalives) with an empty choices list.
+                            # Those aren't chat-completion deltas, so pass the
+                            # original chunk through unchanged instead of
+                            # indexing into an empty list.
+                            if not completion_data.get("choices"):
+                                yield chunk
+                                continue
+                            chat_completion_data = {
+                                "id": completion_data["id"],
+                                "object": "chat.completion.chunk",
+                                "created": completion_data["created"],
+                                "model": completion_data["model"],
+                                "choices": [
+                                    {
+                                        "index": 0,
+                                        "delta": {
+                                            "content": completion_data["choices"][0][
+                                                "text"
+                                            ]
+                                        },
+                                        "logprobs": completion_data["choices"][0].get(
+                                            "logprobs"
+                                        ),
+                                        "finish_reason": completion_data["choices"][
+                                            0
+                                        ].get("finish_reason"),
+                                    }
+                                ],
+                            }
+                            converted_chunk = (
+                                "data: "
+                                + json.dumps(
+                                    chat_completion_data, separators=(",", ":")
+                                )
+                                + "\n\n"
+                            ).encode()
+                            yield converted_chunk
+                    except (json.JSONDecodeError, KeyError):
+                        yield chunk
+                else:
+                    yield chunk
+
+        return StreamingResponse(generate_stream(), media_type="application/json")
+
+    except Exception as e:
+        if pd_buffer_semaphore is not None and acquired:
+            await pd_buffer_semaphore.release(slots)
+        # Standard
+        import sys
+        import traceback
+
+        exc_info = sys.exc_info()
+        print(
+            "Error occurred in disagg prefill proxy server  - chat completions endpoint"
+        )
+        print(e)
+        print("".join(traceback.format_exception(*exc_info)))
+        raise
+
+
+if __name__ == "__main__":
+    global global_args
+    global_args = parse_args()
+
+    # Third Party
+    import uvicorn
+
+    uvicorn.run(app, host=global_args.host, port=global_args.port)
diff --git a/examples/disagg_prefill/xpyd/README.md b/examples/disagg_prefill/xpyd/README.md
new file mode 100644
index 0000000..f5fe607
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/README.md
@@ -0,0 +1,157 @@
+## Example of Disaggregated Prefill in vLLM v1
+
+This example demonstrates how to run LMCache with disaggregated prefill using NIXL on a single node.
+
+### Prerequisites
+
+- Install [LMCache](https://github.com/LMCache/LMCache). You can simply run `pip install lmcache`.
+- Install [NIXL](https://github.com/ai-dynamo/nixl).
+- At least 4 GPUs
+- Valid Hugging Face token (HF_TOKEN) for Llama 3.1 8B Instruct.
+
+### Usage
+
+Run
+```bash
+bash disagg_example_xpyd.sh
+```
+
+to start disaggregated prefill and benchmark the performance.
+
+The script will:
+
+1. Launch 2 decoder instances listening on port 7200 and 7201, respectively
+2. Launch 2 prefill instances listening on ports 7100 and 7101, respectively
+3. Launch a proxy server that uses round-robin to distribute requests between the prefill instances and decode instances, listening on port 9100
+
+Press `Ctrl+C` to stop the servers.
+
+### Advanced Configuration
+
+#### Multi-Host Support
+
+The proxy server supports CSV format for specifying multiple hosts and ports for both prefillers and decoders. This enables flexible deployment across multiple machines:
+
+```bash
+# Multi-machine deployment
+python disagg_proxy_server.py \
+    --prefiller-host "${host1-IP},${host2-IP}" \
+    --prefiller-port "8000" \
+    --decoder-host "${host3-IP},${host4-IP}" \
+    --decoder-port "8000,8001"
+
+# Above example `--prefiller-port "8000"` means the host1 and host2 vLLM instances both use port 8000 for model serving.
+# Above example `--decoder-port "8000,8001"` means host3 uses port 8000 and host4 uses 8001 for model serving. (Using different ports on different hosts is not required, but demonstrates argument flexibility)
+```
+
+#### To support Tensor-Parallel
+
+In Decoder's lmcache configuration file, different ports are required for different TP ranks. The below example shows a TP=8 case with 8 ports (to support vLLM instance with `--tensor-parallel-size 8`)
+
+```yaml
+nixl_peer_init_port:  [7300,7301,7302,7303,7304,7305,7306,7307]
+nixl_peer_alloc_port: [7400,7401,7402,7403,7404,7405,7406,7407]
+```
+
+Accordingly, the `disagg_proxy_server.py` should use the same ports aligning with decoder configuration:
+```bash
+python disagg_proxy_server.py \
+    .... \ # other arguments
+    --decoder-init-port  "7300,7301,7302,7303,7304,7305,7306,7307" \
+    --decoder-alloc-port "7400,7401,7402,7403,7404,7405,7406,7407"
+```
+
+#### To support bound prefiller and decoder for the same session
+
+For xPyD multi-round QA scenario, disagg_proxy_server can provide the clients with bound prefiller/decoder during the same session, in addition to round-robin.
+
+http requests can provide a header (e.g., 'session-id: \<unique-id\>') for the disagg_proxy_server to select bound prefiller/decoder during the same session:
+- **Header Value**: A unique identifier (e.g., \<unique-id\>) for the session. All requests within the same multi-round conversation must use the same identifier.
+- **Header Name**: The name of the header field (e.g., 'session-id') for disagg_proxy_server to find the \<unique-id\>. \
+                   This **Header Name** must match the value of the '$CLIENT_BOUND_KEY' environment variable set on the proxy server.
+
+```
+export CLIENT_BOUND="true"
+
+# The proxy uses the value of $CLIENT_BOUND_KEY as the header name to find the session ID.
+# For example, if CLIENT_BOUND_KEY="session-id", the proxy looks for the "session-id" header.
+# Requests with the same session ID are routed to the same services.
+# If $CLIENT_BOUND_KEY is not set, it defaults to "session-id".
+
+export CLIENT_BOUND_KEY="session-id"  # optional, configure a constant string name.
+python disagg_proxy_server.py \
+    .... \ # other arguments
+```
+
+```
+# client side, set the kv pair, such as (session-id: uid) in header
+# openai python sdk, put the kv pair in extra_headers param
+import uuid
+uid = str(uuid.uuid4()) # the uid can be changed to any other unique identifier string for a session
+extra_headers = {"session-id" : uid}
+response = await self.client.chat.completions.create(
+    messages=messages,
+    model=self.model,
+    temperature=0,
+    stream=True,
+    max_tokens=max_tokens,
+    stream_options={"include_usage": True},
+    extra_headers=extra_headers,
+    extra_body=extra_body
+)
+```
+
+#### Example benchmark command
+
+If you have vLLM's serving benchmark tool, you can run the following command to benchmark the serving performance of the disaggregated prefill setup:
+
+```bash
+vllm bench serve --port 9100 --seed $(date +%s) \
+    --model meta-llama/Llama-3.1-8B-Instruct \
+    --dataset-name random --random-input-len 7500 --random-output-len 200 \
+    --num-prompts 30 --burstiness 100 --request-rate 1 --ignore-eos
+```
+
+Expected output from the benchmark script:
+
+```plaintext
+============ Serving Benchmark Result ============
+Successful requests:                     30
+Benchmark duration (s):                  31.34
+Total input tokens:                      224970
+Total generated tokens:                  6000
+Request throughput (req/s):              0.96
+Output token throughput (tok/s):         191.44
+Total Token throughput (tok/s):          7369.36
+---------------Time to First Token----------------
+Mean TTFT (ms):                          313.41
+Median TTFT (ms):                        272.83
+P99 TTFT (ms):                           837.32
+-----Time per Output Token (excl. 1st token)------
+Mean TPOT (ms):                          8.84
+Median TPOT (ms):                        8.72
+P99 TPOT (ms):                           11.35
+---------------Inter-token Latency----------------
+Mean ITL (ms):                           8.84
+Median ITL (ms):                         8.61
+P99 ITL (ms):                            11.43
+==================================================
+```
+
+### Components
+
+#### Server Scripts
+- `disagg_vllm_launcher.sh` - Launches individual vLLM servers for prefill/decode, and also launches the proxy server.
+- `disagg_proxy_server.py` - FastAPI proxy server that coordinates between prefiller and decoder
+- `disagg_example_xpyd.sh` - Main script to run the example
+
+#### Configuration
+- `configs/lmcache-prefiller-config.yaml` - Configuration for prefiller server
+- `configs/lmcache-decoder-1-config.yaml` - Configuration for decoder server 1
+- `configs/lmcache-decoder-2-config.yaml` - Configuration for decoder server 2
+
+#### Log Files
+The main script generates several log files:
+- `prefiller1.log` and `prefiller2.log` - Logs from the prefill servers
+- `decoder1.log` and `decoder2.log` - Logs from the decode server
+- `proxy.log` - Logs from the proxy server
diff --git a/examples/disagg_prefill/xpyd/configs/lmcache-decoder-1-config.yaml b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-1-config.yaml
new file mode 100644
index 0000000..640b4a8
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-1-config.yaml
@@ -0,0 +1,49 @@
+local_cpu: False
+max_local_cpu_size: 0
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7300
+pd_peer_alloc_port: 7400
+pd_buffer_size: 2147483648 # 2GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/xpyd/configs/lmcache-decoder-1-pd-with-remote-config.yaml b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-1-pd-with-remote-config.yaml
new file mode 100644
index 0000000..2cea02b
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-1-pd-with-remote-config.yaml
@@ -0,0 +1,58 @@
+local_cpu: True
+max_local_cpu_size: 5
+
+remote_url: "lm://<your remote server IP>:<port>"
+remote_serde: "cachegen"
+
+retrieve_locations: ["PDBackend"]
+store_location: "RemoteBackend"
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7300
+pd_peer_alloc_port: 7400
+pd_buffer_size: 2147483648 # 2GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+save_decode_cache: true
+save_unfull_chunk: true
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/xpyd/configs/lmcache-decoder-2-config.yaml b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-2-config.yaml
new file mode 100644
index 0000000..c6a0d6c
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-2-config.yaml
@@ -0,0 +1,49 @@
+local_cpu: False
+max_local_cpu_size: 0
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7301
+pd_peer_alloc_port: 7401
+pd_buffer_size: 2147483648 # 2GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/xpyd/configs/lmcache-decoder-2-pd-with-remote-config.yaml b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-2-pd-with-remote-config.yaml
new file mode 100644
index 0000000..292c378
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/configs/lmcache-decoder-2-pd-with-remote-config.yaml
@@ -0,0 +1,58 @@
+local_cpu: True
+max_local_cpu_size: 5
+
+remote_url: "lm://<your remote server IP>:<port>"
+remote_serde: "cachegen"
+
+retrieve_locations: ["PDBackend"]
+store_location: "RemoteBackend"
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7301
+pd_peer_alloc_port: 7401
+pd_buffer_size: 2147483648 # 2GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+save_decode_cache: true
+save_unfull_chunk: true
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/xpyd/configs/lmcache-prefiller-config.yaml b/examples/disagg_prefill/xpyd/configs/lmcache-prefiller-config.yaml
new file mode 100644
index 0000000..439fab4
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/configs/lmcache-prefiller-config.yaml
@@ -0,0 +1,50 @@
+local_cpu: False
+max_local_cpu_size: 0
+max_local_disk_size: 0
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "sender"
+pd_proxy_host: "localhost"
+pd_proxy_port: 7500
+pd_buffer_size: 1073741824 # 1GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
+
diff --git a/examples/disagg_prefill/xpyd/configs/lmcache-prefiller-pd-with-remote-config.yaml b/examples/disagg_prefill/xpyd/configs/lmcache-prefiller-pd-with-remote-config.yaml
new file mode 100644
index 0000000..d24fb9b
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/configs/lmcache-prefiller-pd-with-remote-config.yaml
@@ -0,0 +1,55 @@
+local_cpu: True
+max_local_cpu_size: 5
+
+remote_url: "lm://localhost:6800"
+remote_serde: "cachegen"
+
+retrieve_locations: ["LocalCPUBackend", "RemoteBackend"]
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "sender"
+pd_proxy_host: "localhost"
+pd_proxy_port: 7500
+pd_buffer_size: 1073741824 # 1GB
+pd_buffer_device: "cuda"
+nixl_backends: [UCX]
+
+save_unfull_chunk: true
+
+# ==============================================================================
+# Async PD Backend Configuration
+# ==============================================================================
+
+# Defines the backend execution mode.
+# Options: "async" (default), "sync"
+pd_backend_mode: "async"
+
+# ------------------------------------------------------------------------------
+# Async Mode Settings
+# Note: The following configurations are valid ONLY when pd_backend_mode: "async"
+# ------------------------------------------------------------------------------
+
+# Maximum length for the prefill phase.
+# Default: 0 (skips buffer size check for backward compatibility).
+# Recommendation: Set a specific limit to prevent resource exhaustion.
+# Dependency: `pd_buffer_size` must accommodate the prefill chunks and KV size.
+# Formula: pd_buffer_size >= (pd_max_prefill_len // chunk_size + 1) * kv_size.
+pd_max_prefill_len: 16384
+
+# Timeout for resource allocation in seconds.
+# Default: 5.
+# Note: Adjust this value based on system load. Higher concurrency generally
+# requires a larger timeout.
+pd_allocation_timeout_sec: 10
+
+# Timeout for system shutdown in seconds.
+# Default: 5.
+# Note: This applies only during system shutdown and has no impact on runtime 
+# performance.
+pd_shutdown_timeout_sec: 5
+
+# Interval for condition polling in seconds.
+# Default: 0.05. (often implicitly understood, but good to state if changed)
+# Note: Decrease this value for more timely responses.
+pd_condition_poll_interval_sec: 0.05
diff --git a/examples/disagg_prefill/xpyd/disagg_example_xpyd.sh b/examples/disagg_prefill/xpyd/disagg_example_xpyd.sh
new file mode 100644
index 0000000..e28b180
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/disagg_example_xpyd.sh
@@ -0,0 +1,181 @@
+#!/bin/bash
+
+echo "Warning: LMCache disaggregated prefill support for vLLM v1 is experimental and subject to change."
+
+
+PIDS=()
+
+# Switch to the directory of the current script
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+check_hf_token() {
+    if [ -z "$HF_TOKEN" ]; then
+        echo "HF_TOKEN is not set. Please set it to your Hugging Face token."
+        exit 1
+    fi
+    if [[ "$HF_TOKEN" != hf_* ]]; then
+        echo "HF_TOKEN is not a valid Hugging Face token. Please set it to your Hugging Face token."
+        exit 1
+    fi
+    echo "HF_TOKEN is set and valid."
+}
+
+check_num_gpus() {
+    # can you check if the number of GPUs are >=2 via nvidia-smi?
+    num_gpus=$(nvidia-smi --query-gpu=name --format=csv,noheader | wc -l)
+    if [ "$num_gpus" -lt 2 ]; then
+        echo "You need at least 2 GPUs to run disaggregated prefill."
+        exit 1
+    else
+        echo "Found $num_gpus GPUs."
+    fi
+}
+
+ensure_python_library_installed() {
+    echo "Checking if $1 is installed..."
+    python -c "import $1" > /dev/null 2>&1
+    if [ $? -ne 0 ]; then
+        if [ "$1" == "nixl" ]; then
+            echo "$1 is not installed. Please refer to https://github.com/ai-dynamo/nixl for installation."
+        else
+            echo "$1 is not installed. Please install it via pip install $1."
+        fi
+        exit 1
+    else
+        echo "$1 is installed."
+    fi
+}
+
+cleanup() {
+    echo "Stopping everything…"
+    trap - INT TERM USR1   # prevent re-entrancy
+    
+    # Kill all tracked PIDs
+    for pid in "${PIDS[@]}"; do
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "Killing process $pid"
+            kill "$pid" 2>/dev/null
+        fi
+    done
+    
+    # Wait a moment for graceful shutdown
+    sleep 2
+    
+    # Force kill any remaining processes
+    for pid in "${PIDS[@]}"; do
+        if kill -0 "$pid" 2>/dev/null; then
+            echo "Force killing process $pid"
+            kill -9 "$pid" 2>/dev/null
+        fi
+    done
+    
+    # Kill the entire process group as backup
+    kill -- -$$ 2>/dev/null
+    
+    echo "All processes stopped."
+    exit 0
+}
+
+wait_for_server() {
+  local port=$1
+  local timeout_seconds=1200
+  local start_time=$(date +%s)
+
+  echo "Waiting for server on port $port..."
+
+  while true; do
+    if curl -s "localhost:${port}/v1/completions" > /dev/null; then
+      return 0
+    fi
+
+    local now=$(date +%s)
+    if (( now - start_time >= timeout_seconds )); then
+      echo "Timeout waiting for server"
+      return 1
+    fi
+
+    sleep 1
+  done
+}
+
+
+main() {
+    check_hf_token
+    check_num_gpus
+    ensure_python_library_installed lmcache
+    ensure_python_library_installed nixl
+    ensure_python_library_installed pandas
+    ensure_python_library_installed datasets
+    ensure_python_library_installed vllm
+
+    trap cleanup INT
+    trap cleanup USR1
+    trap cleanup TERM
+
+    echo "Launching prefiller, decoder and proxy..."
+    echo "Please check prefiller.log, decoder.log and proxy.log for logs."
+
+    # Launch the proxy first
+    python3 ../disagg_proxy_server.py \
+        --host localhost \
+        --port 9100 \
+        --prefiller-host localhost \
+        --prefiller-port 7100 \
+        --num-prefillers 2 \
+        --decoder-host localhost \
+        --decoder-port 7200  \
+        --decoder-init-port 7300 \
+        --decoder-alloc-port 7400 \
+        --proxy-host localhost \
+        --proxy-port 7500 \
+        --num-decoders 2 \
+        > >(tee proxy.log)    2>&1 &
+    proxy_pid=$!
+    PIDS+=($proxy_pid)
+
+    # Launch the decoder
+    bash disagg_vllm_launcher.sh decoder1  \
+        > >(tee decoder1.log)  2>&1 &
+    decoder_pid=$!
+    PIDS+=($decoder_pid)
+
+    sleep 5
+    # Launch the second decoder 
+    bash disagg_vllm_launcher.sh decoder2  \
+        > >(tee decoder2.log)  2>&1 &
+    decoder_pid=$!
+    PIDS+=($decoder_pid)
+    wait_for_server 7200
+    wait_for_server 7201
+
+
+    # Launch the prefillers next
+    bash disagg_vllm_launcher.sh prefiller1 \
+        > >(tee prefiller1.log) 2>&1 &
+    prefiller_pid=$!
+    PIDS+=($prefiller_pid)
+
+    sleep 5  # Don't launch the second prefiller too quickly
+    bash disagg_vllm_launcher.sh prefiller2 \
+        > >(tee prefiller2.log) 2>&1 &
+    prefiller2_pid=$!
+    PIDS+=($prefiller2_pid)
+
+    wait_for_server 7100
+    wait_for_server 7101
+    wait_for_server 9100
+
+    echo "==================================================="
+    echo "All servers are up. You can send request now..."
+    echo "Press Ctrl-C to terminate all instances."
+
+    # Keep the script running until interrupted
+    echo "Script is running. Waiting for termination signal..."
+    echo "==================================================="
+
+    while true; do
+        sleep 1
+    done
+}
+
+main
diff --git a/examples/disagg_prefill/xpyd/disagg_vllm_launcher.sh b/examples/disagg_prefill/xpyd/disagg_vllm_launcher.sh
new file mode 100644
index 0000000..7b97678
--- /dev/null
+++ b/examples/disagg_prefill/xpyd/disagg_vllm_launcher.sh
@@ -0,0 +1,96 @@
+#!/bin/bash
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# NOTE: For correct KV cache transfer, ensure all processes use the same PYTHONHASHSEED to keep the hash of the KV cache consistent across processes.
+export PYTHONHASHSEED=0
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <prefiller | decoder> [model]"
+    exit 1
+fi
+
+if [[ $# -eq 1 ]]; then
+    echo "Using default model: meta-llama/Llama-3.1-8B-Instruct"
+    MODEL="meta-llama/Llama-3.1-8B-Instruct"
+else
+    echo "Using model: $2"
+    MODEL=$2
+fi
+
+
+if [[ $1 == "prefiller1" ]]; then
+    # Prefiller 1 listens on port 7100
+    prefill_config_file=$SCRIPT_DIR/configs/lmcache-prefiller-config.yaml
+
+    UCX_TLS=cuda_ipc,cuda_copy,tcp \
+        LMCACHE_CONFIG_FILE=$prefill_config_file \
+        VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+        VLLM_WORKER_MULTIPROC_METHOD=spawn \
+        CUDA_VISIBLE_DEVICES=0 \
+        vllm serve $MODEL \
+        --port 7100 \
+        --disable-log-requests \
+        --enforce-eager \
+        --no-enable-prefix-caching \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer1"}}'
+
+elif [[ $1 == "prefiller2" ]]; then
+    # Prefiller 2 listens on port 7101
+    prefill_config_file=$SCRIPT_DIR/configs/lmcache-prefiller-config.yaml
+
+    UCX_TLS=cuda_ipc,cuda_copy,tcp \
+        LMCACHE_CONFIG_FILE=$prefill_config_file \
+        VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+        VLLM_WORKER_MULTIPROC_METHOD=spawn \
+        CUDA_VISIBLE_DEVICES=1 \
+        vllm serve $MODEL \
+        --port 7101 \
+        --disable-log-requests \
+        --enforce-eager \
+        --no-enable-prefix-caching \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_producer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "producer2"}}'
+
+
+
+elif [[ $1 == "decoder1" ]]; then
+    # Decoder 1 listens on port 7200
+    decode_config_file=$SCRIPT_DIR/configs/lmcache-decoder-1-config.yaml
+
+    UCX_TLS=cuda_ipc,cuda_copy,tcp \
+        LMCACHE_CONFIG_FILE=$decode_config_file \
+        VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+        VLLM_WORKER_MULTIPROC_METHOD=spawn \
+        CUDA_VISIBLE_DEVICES=2 \
+        vllm serve $MODEL \
+        --port 7200 \
+        --disable-log-requests \
+        --enforce-eager \
+        --no-enable-prefix-caching \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer1", "skip_last_n_tokens": 1}}'
+
+elif [[ $1 == "decoder2" ]]; then
+    # Decoder 2 listens on port 7201
+    decode_config_file=$SCRIPT_DIR/configs/lmcache-decoder-2-config.yaml
+
+    UCX_TLS=cuda_ipc,cuda_copy,tcp \
+        LMCACHE_CONFIG_FILE=$decode_config_file \
+        VLLM_ENABLE_V1_MULTIPROCESSING=1 \
+        VLLM_WORKER_MULTIPROC_METHOD=spawn \
+        CUDA_VISIBLE_DEVICES=3 \
+        vllm serve $MODEL \
+        --port 7201 \
+        --disable-log-requests \
+        --enforce-eager \
+        --no-enable-prefix-caching \
+        --kv-transfer-config \
+        '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_consumer","kv_connector_extra_config": {"discard_partial_chunks": false, "lmcache_rpc_port": "consumer2", "skip_last_n_tokens": 1}}'
+
+else
+    echo "Invalid role: $1"
+    echo "Should be either prefill, decode"
+    exit 1
+fi
diff --git a/examples/disagg_prefill_mp/README.md b/examples/disagg_prefill_mp/README.md
new file mode 100644
index 0000000..f6fb4e0
--- /dev/null
+++ b/examples/disagg_prefill_mp/README.md
@@ -0,0 +1,65 @@
+
+## PD disaggregation in LMCache multiprocess mode
+
+![Architecture](architecture.png)
+
+The figure above shows the PD architecture. The workflow goes as:
+
+- The router sends one request to prefill instance with `max_token=1` and then wait for an event.
+- The prefill instance finishes storing all the KV caches.
+- The `request_telemetry` class reports the finished store event back to the router
+- The router then send the request to decode instance.
+
+
+**NOTE:** the current code only support 1p1d for now.
+**NOTE:** the current code is not optimized for perf.
+
+## How to run
+
+Launch the following in 4 different terminal windows
+
+```bash
+# LMCache multi-process server
+lmcache server --l1-size-gb 100 --eviction-policy LRU
+# Prefill instance, enforce_eager for faster startup
+LMCACHE_REQUEST_TELEMETRY_TYPE=fastapi LMCACHE_REQUEST_TELEMETRY_ENDPOINT=http://localhost:5768/api/v1/telemetry vllm serve Qwen/Qwen3-14B --kv-transfer-config '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}' --gpu-memory-utilization 0.7 --no-enable-prefix-caching --enforce-eager --port 8100
+# Decode instance, enforce_eager for faster startup
+CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-14B --kv-transfer-config '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both"}' --gpu-memory-utilization 0.7 --no-enable-prefix-caching --enforce-eager --port 8200
+# proxy server
+python disagg_proxy_server
+```
+
+And then you can test the implementation with example curl request
+
+```
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -N \
+  -d '{
+    "model": "Qwen/Qwen3-14B",
+    "messages": [
+      {
+        "role": "user",
+        "content": "1Hello, how are you? I am fine, thank you. But I am not sure about you. Can you tell me more about yourself? I am a human."
+      }
+    ],
+    "max_tokens": 100,
+    "temperature": 0.7
+  }'
+```
+
+Or run some benchmark
+
+```
+vllm bench serve \
+    --dataset-name random \
+    --random-input-len 5000 \
+    --random-output-len 100 \
+    --request-rate 0.25 \
+    --num-prompts 10 \
+    --random-range-ratio 0.0 \
+    --ignore-eos \
+    --backend vllm \
+    --model Qwen/Qwen3-14B \
+    --port 8000
+```
\ No newline at end of file
diff --git a/examples/disagg_prefill_mp/architecture.png b/examples/disagg_prefill_mp/architecture.png
new file mode 100644
index 0000000..4ef70be
Binary files /dev/null and b/examples/disagg_prefill_mp/architecture.png differ
diff --git a/examples/disagg_prefill_mp/disagg_proxy_server.py b/examples/disagg_prefill_mp/disagg_proxy_server.py
new file mode 100644
index 0000000..dc76228
--- /dev/null
+++ b/examples/disagg_prefill_mp/disagg_proxy_server.py
@@ -0,0 +1,461 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Optional
+import argparse
+import asyncio
+import itertools
+import os
+import threading
+import time
+import uuid
+
+# Third Party
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse, StreamingResponse
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# Global dictionary to store asyncio.Events indexed by request ID.
+# This is shared between the main proxy app and the telemetry app.
+pending_requests: dict[str, asyncio.Event] = {}
+pending_requests_lock = threading.Lock()
+
+# Reference to the main event loop (set at startup)
+main_event_loop: Optional[asyncio.AbstractEventLoop] = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Lifespan context manager to handle startup and shutdown events.
+    """
+    global main_event_loop
+    main_event_loop = asyncio.get_running_loop()
+
+    # Startup: Initialize clients
+    pref_hosts = global_args.prefiller_host
+    pref_ports = global_args.prefiller_port
+
+    def pair_hosts_and_ports(hosts, ports, count=None):
+        """
+        Flexible host-port pairing with expansion strategies.
+        """
+        if not isinstance(hosts, list):
+            hosts = [hosts]
+        if not isinstance(ports, list):
+            ports = [ports]
+        if len(hosts) == 1 and len(ports) == 1:
+            if count is None or count <= 1:
+                return [(hosts[0], ports[0])]
+            else:
+                return [(hosts[0], ports[0] + i) for i in range(count)]
+        if len(hosts) == 1:
+            return [(hosts[0], p) for p in ports]
+        if len(ports) == 1:
+            return [(h, ports[0]) for h in hosts]
+        if len(hosts) != len(ports):
+            raise ValueError(
+                "Length mismatch between hosts and ports lists for pairing"
+            )
+        return list(zip(hosts, ports, strict=False))
+
+    prefill_pairs = pair_hosts_and_ports(
+        pref_hosts, pref_ports, global_args.num_prefillers
+    )
+    for host, port in prefill_pairs:
+        prefiller_base_url = f"http://{host}:{int(port)}"
+        prefill_client = httpx.AsyncClient(timeout=None, base_url=prefiller_base_url)
+        app.state.prefill_clients.append(ClientInfo(prefill_client))
+
+    # Build decoder clients
+    dec_hosts = global_args.decoder_host
+    dec_ports = global_args.decoder_port
+
+    decoder_pairs = pair_hosts_and_ports(dec_hosts, dec_ports, global_args.num_decoders)
+
+    for host, port in decoder_pairs:
+        decoder_base_url = f"http://{host}:{int(port)}"
+        decode_client = httpx.AsyncClient(timeout=None, base_url=decoder_base_url)
+        app.state.decode_clients.append(ClientInfo(decode_client))
+
+    app.state.total_clients = app.state.prefill_clients + app.state.decode_clients
+
+    yield
+
+    # Shutdown: Close clients
+    for client in app.state.prefill_clients:
+        await client.aclose()
+    for client in app.state.decode_clients:
+        await client.aclose()
+
+
+# Main proxy FastAPI app
+app = FastAPI(lifespan=lifespan)
+
+
+def csv_ints(s):
+    return [int(x) for x in s.split(",")]
+
+
+def csv_strs(s):
+    return [x.strip() for x in s.split(",")]
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--host", type=str, default="localhost")
+    parser.add_argument("--prefiller-host", type=csv_strs, default=["localhost"])
+    parser.add_argument("--prefiller-port", type=csv_ints, default=[8100])
+    parser.add_argument("--num-prefillers", type=int, default=1)
+    parser.add_argument("--decoder-host", type=csv_strs, default=["localhost"])
+    parser.add_argument("--decoder-port", type=csv_ints, default=[8200])
+    parser.add_argument("--num-decoders", type=int, default=1)
+    parser.add_argument("--telemetry-port", type=int, default=5768)
+
+    args = parser.parse_args()
+    return args
+
+
+@dataclass
+class ClientInfo:
+    client: httpx.AsyncClient
+    host: Optional[str] = None
+
+    async def aclose(self):
+        await self.client.aclose()
+
+
+# Initialize state
+app.state.prefill_clients = []
+app.state.decode_clients = []
+app.state.total_clients = []
+
+
+def round_robin_pick_client(clients, idx):
+    return clients[idx % len(clients)]
+
+
+round_robin_counter = itertools.count()
+
+
+def round_robin_pick_clients() -> tuple[ClientInfo, ClientInfo]:
+    idx = next(round_robin_counter)
+    prefill_client = round_robin_pick_client(app.state.prefill_clients, idx)
+    decode_client = round_robin_pick_client(app.state.decode_clients, idx)
+    return prefill_client, decode_client
+
+
+def _build_headers(**extra: str) -> dict[str, str]:
+    """Build common HTTP headers, including auth if OPENAI_API_KEY is set."""
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    api_key = os.environ.get("OPENAI_API_KEY", "").strip()
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    headers.update(extra)
+    return headers
+
+
+async def send_request_to_prefiller(
+    client: httpx.AsyncClient,
+    endpoint: str,
+    req_data: dict,
+    request_id: str,
+):
+    """
+    Send a request to prefiller with request-id header.
+    """
+    headers = _build_headers(**{"X-Request-Id": request_id})
+    response = await client.post(endpoint, json=req_data, headers=headers)
+    response.raise_for_status()
+    return response
+
+
+async def send_request_to_decoder(
+    client: httpx.AsyncClient,
+    endpoint: str,
+    req_data: dict,
+):
+    """
+    Send a request to decoder service.
+    """
+    headers = _build_headers()
+    response = await client.post(endpoint, json=req_data, headers=headers)
+    response.raise_for_status()
+    return response
+
+
+async def stream_service_response(
+    client: httpx.AsyncClient, endpoint: str, req_data: dict
+):
+    """
+    Asynchronously stream the response from a service.
+    """
+    headers = _build_headers()
+    async with client.stream(
+        "POST", endpoint, json=req_data, headers=headers
+    ) as response:
+        response.raise_for_status()
+        async for chunk in response.aiter_bytes():
+            yield chunk
+
+
+def generate_request_id() -> str:
+    """Generate a unique request ID."""
+    return str(uuid.uuid4())[:16]
+
+
+def create_pending_request(request_id: str) -> asyncio.Event:
+    """Create an asyncio.Event for a request and store it."""
+    event = asyncio.Event()
+    with pending_requests_lock:
+        pending_requests[request_id] = event
+    return event
+
+
+def remove_pending_request(request_id: str):
+    """Remove a pending request from the dictionary."""
+    with pending_requests_lock:
+        pending_requests.pop(request_id, None)
+
+
+def notify_request(chatcmpl_request_id: str) -> bool:
+    """
+    Notify a pending request that the KV store is complete.
+    Returns True if the request was found and notified.
+    """
+    with pending_requests_lock:
+        # vLLM wraps the request ID as "chatcmpl-{uuid}-{suffix}",
+        # so strip the first and last segments to recover the original UUID.
+        request_id = "-".join(chatcmpl_request_id.split("-")[1:])
+        request_id = request_id[:16]
+        event = pending_requests.get(request_id, None)
+        if event:
+            # Schedule the event.set() on the main event loop
+            if main_event_loop is not None:
+                main_event_loop.call_soon_threadsafe(event.set)
+            return True
+    return False
+
+
+async def _handle_disagg_request(request: Request, endpoint: str):
+    """
+    Common handler for disaggregated prefill/decode requests.
+
+    Works for both /v1/completions and /v1/chat/completions — the only
+    difference is the *endpoint* path forwarded to the prefiller and decoder.
+    """
+    try:
+        req_data = await request.json()
+
+        # Generate a random request ID
+        request_id = generate_request_id()
+        logger.info(f"Received {endpoint} request with generated ID: {request_id}")
+
+        # Pick prefill and decode clients
+        prefill_client, decode_client = round_robin_pick_clients()
+
+        # Create event for this request (signaled when KV store finishes)
+        event = create_pending_request(request_id)
+
+        try:
+            # Modify request for prefiller: set max_tokens=1
+            prefill_req_data = req_data.copy()
+            prefill_req_data["max_tokens"] = 1
+            if "max_completion_tokens" in prefill_req_data:
+                prefill_req_data["max_completion_tokens"] = 1
+            prefill_req_data["stream"] = False
+            prefill_req_data.pop("stream_options", None)
+
+            # Send to prefiller with X-Request-Id header (ignore output)
+            prefill_send_time = time.monotonic()
+            await send_request_to_prefiller(
+                prefill_client.client,
+                endpoint,
+                prefill_req_data,
+                request_id,
+            )
+            prefill_first_response_time = time.monotonic()
+            prefill_duration = prefill_first_response_time - prefill_send_time
+            logger.info(
+                f"Request {request_id}: prefill request"
+                f" duration = {prefill_duration:.4f}s"
+            )
+
+            # Wait for the event to be signaled (KV store finished)
+            await event.wait()
+            notify_time = time.monotonic()
+            notify_wait_duration = notify_time - prefill_first_response_time
+            logger.info(
+                f"Request {request_id}: finished saving KV caches after prefill"
+                f" response = {notify_wait_duration * 1000:.2f}ms"
+            )
+            logger.debug(f"Event signaled for {request_id}, forwarding to decoder")
+
+        finally:
+            # Clean up the pending request
+            remove_pending_request(request_id)
+
+        # Forward original request to decoder
+        is_stream = req_data.get("stream", False)
+
+        if is_stream:
+
+            async def generate_stream():
+                first_chunk = True
+                async for chunk in stream_service_response(
+                    decode_client.client, endpoint, req_data
+                ):
+                    if first_chunk:
+                        decode_first_response_time = time.monotonic()
+                        latency = (
+                            decode_first_response_time - prefill_first_response_time
+                        )
+                        logger.info(
+                            f"Request {request_id}: latency between prefill first "
+                            f"response and decode first response = "
+                            f"{latency * 1000:.2f}ms"
+                        )
+                        first_chunk = False
+                    yield chunk
+
+            return StreamingResponse(generate_stream(), media_type="application/json")
+        else:
+            response = await send_request_to_decoder(
+                decode_client.client, endpoint, req_data
+            )
+            return JSONResponse(content=response.json())
+
+    except Exception as e:
+        # Standard
+        import sys
+        import traceback
+
+        exc_info = sys.exc_info()
+        logger.error(f"Error in {endpoint} endpoint")
+        logger.error(str(e))
+        logger.error("".join(traceback.format_exception(*exc_info)))
+        raise
+
+
+@app.post("/v1/completions")
+async def handle_completions(request: Request):
+    """Handle /v1/completions requests."""
+    return await _handle_disagg_request(request, "/v1/completions")
+
+
+@app.post("/v1/chat/completions")
+async def handle_chat_completions(request: Request):
+    """Handle /v1/chat/completions requests."""
+    return await _handle_disagg_request(request, "/v1/chat/completions")
+
+
+@app.get("/v1/models")
+async def handle_models():
+    """Handle /v1/models requests by forwarding to the first prefiller."""
+    try:
+        prefill_client = app.state.prefill_clients[0]
+        headers = _build_headers()
+        response = await prefill_client.client.get("/v1/models", headers=headers)
+        response.raise_for_status()
+        return JSONResponse(content=response.json())
+    except Exception as e:
+        logger.error(f"Error in /v1/models endpoint: {e}")
+        return JSONResponse(
+            content={"error": str(e)},
+            status_code=500,
+        )
+
+
+# ============================================================================
+# Telemetry FastAPI app (runs on separate port)
+# ============================================================================
+
+telemetry_app = FastAPI()
+
+
+@telemetry_app.post("/api/v1/telemetry")
+async def handle_telemetry(request: Request):
+    """
+    Handle telemetry POST requests.
+
+    Expected payload format (from FastAPIRequestTelemetry):
+    {
+        "event": "request_store_finished",
+        "request_ids_set": ["id1", "id2", ...],
+        "model_name": "...",
+        "world_size": N,
+        "kv_rank": K,
+    }
+
+    For each request ID in request_ids_set, signal the corresponding
+    event if it exists.
+    """
+    try:
+        payload = await request.json()
+
+        event_type = payload.get("event")
+        request_ids = payload.get("request_ids_set", [])
+
+        for request_id in request_ids:
+            logger.info(
+                f"Received telemetry event: {event_type} for request: {request_id}"
+            )
+
+        notified_count = 0
+        for request_id in request_ids:
+            if notify_request(request_id):
+                notified_count += 1
+                logger.info(f"Notified request: {request_id}")
+
+        return JSONResponse(
+            content={
+                "status": "ok",
+                "notified": notified_count,
+                "total": len(request_ids),
+            }
+        )
+
+    except Exception as e:
+        logger.error(f"Error processing telemetry: {e}")
+        return JSONResponse(
+            content={"status": "error", "message": str(e)},
+            status_code=500,
+        )
+
+
+def run_telemetry_server(host: str, port: int):
+    """Run the telemetry server in a separate thread."""
+    # Third Party
+    import uvicorn
+
+    uvicorn.run(telemetry_app, host=host, port=port, log_level="info")
+
+
+if __name__ == "__main__":
+    global global_args
+    global_args = parse_args()
+
+    # Third Party
+    import uvicorn
+
+    # Start telemetry server in a background thread
+    telemetry_thread = threading.Thread(
+        target=run_telemetry_server,
+        args=(global_args.host, global_args.telemetry_port),
+        daemon=True,
+    )
+    telemetry_thread.start()
+    logger.info(
+        f"Telemetry server started on {global_args.host}:{global_args.telemetry_port}"
+    )
+
+    # Run main proxy server
+    uvicorn.run(app, host=global_args.host, port=global_args.port)
diff --git a/examples/dynamo_integration/README.md b/examples/dynamo_integration/README.md
new file mode 100644
index 0000000..03ac85b
--- /dev/null
+++ b/examples/dynamo_integration/README.md
@@ -0,0 +1,65 @@
+# Dynamo + LMCache MP integration
+
+Recipes for running [NVIDIA Dynamo](https://github.com/ai-dynamo/dynamo) vLLM
+serving with KV cache offloaded to an **LMCache multiprocess (mp) server**, in
+both **aggregated** and **disaggregated** modes.
+
+In mp mode LMCache runs as an out-of-process cache engine. vLLM workers attach
+to it through the `LMCacheMPConnector` and share KV tensors over CUDA IPC, so
+`sharedMemory` is disabled (LMCache owns `/dev/shm`) and `hostIPC` is enabled.
+
+## Layout
+
+| Path | What it is |
+|------|------------|
+| [`deploy/lmcache_engine.yaml`](deploy/lmcache_engine.yaml) | `LMCacheEngine` CR for the shared MP server. Apply **before** the workers. |
+| [`deploy/agg_lmcache_mp.yaml`](deploy/agg_lmcache_mp.yaml) | Kubernetes `DynamoGraphDeployment`, aggregated (single worker). |
+| [`deploy/disagg_lmcache_mp.yaml`](deploy/disagg_lmcache_mp.yaml) | Kubernetes `DynamoGraphDeployment`, disaggregated (prefill + decode workers). |
+| [`launch/agg_lmcache_mp.sh`](launch/agg_lmcache_mp.sh) | Local single-node launch script, aggregated (1 GPU). |
+| [`launch/disagg_lmcache_mp.sh`](launch/disagg_lmcache_mp.sh) | Local single-node launch script, disaggregated (2 GPUs). |
+
+## The LMCacheEngine (shared prerequisite)
+
+[`deploy/lmcache_engine.yaml`](deploy/lmcache_engine.yaml) declares the MP
+server that both the aggregated and disaggregated workers attach to. The
+LMCache operator reconciles the CR into:
+
+- a per-node **manager DaemonSet** pod (the LMCache server that holds the CPU
+  KV pool), and
+- a **ConfigMap** named `<metadata.name>-connection` (i.e. `lmcache-mp-connection`),
+  which the vLLM workers mount at `/etc/lmcache` and read as
+  `--kv-transfer-config`.
+
+It must live in the **same namespace** as the workers (`default`) so the
+connection ConfigMap is created where the workers can mount it.
+
+**Version pinning**: the server's bundled lmcache must be wire-compatible with
+the worker's. The worker image `vllm-runtime:1.2.0-deepseek-v4-cuda13-dev.3`
+ships lmcache `0.4.4` (vLLM `0.20.1`), and the recipe pairs it with the
+guide-validated server build `nightly-2026-04-25` (lmcache `0.4.5.dev31`, a
+pre-stable build wire-compatible with that worker). Replace `my-tag` in each
+manifest accordingly.
+
+## Usage
+
+The `deploy/` manifests are applied with `kubectl` against a cluster that
+already has the Dynamo platform and the LMCache operator installed. Apply the
+`LMCacheEngine` first, then one of the worker manifests:
+
+```bash
+kubectl apply -n default -f deploy/lmcache_engine.yaml
+kubectl apply -n default -f deploy/disagg_lmcache_mp.yaml   # or agg_lmcache_mp.yaml
+```
+
+See the [Kubernetes deployment guide](../../docs/source/mp/deployment.rst) for
+the full step-by-step (platform install, operator, namespace, HF token Secret,
+then `kubectl apply`).
+
+The `launch/` scripts are the single-node local equivalents. They run **inside
+the Dynamo `vllm-runtime` container** and source Dynamo's
+`examples/common/{gpu_utils,launch_utils}.sh` helpers, so run them from a Dynamo
+checkout (or copy them into `examples/backends/vllm/launch/`).
+
+> The deploy manifests pin the worker image to `my-tag` and the
+> `LMCacheEngine` image separately; keep the two wire-compatible (see the
+> validated pairings in the deployment guide).
diff --git a/examples/dynamo_integration/deploy/agg_lmcache_mp.yaml b/examples/dynamo_integration/deploy/agg_lmcache_mp.yaml
new file mode 100644
index 0000000..339eef0
--- /dev/null
+++ b/examples/dynamo_integration/deploy/agg_lmcache_mp.yaml
@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+apiVersion: nvidia.com/v1alpha1
+kind: DynamoGraphDeployment
+metadata:
+  name: vllm-agg-lmcache
+spec:
+  services:
+    Frontend:
+      envFromSecret: hf-token-secret
+      componentType: frontend
+      replicas: 1
+      extraPodSpec:
+        mainContainer:
+          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:my-tag
+    VllmDecodeWorker:
+      envFromSecret: hf-token-secret
+      componentType: worker
+      replicas: 1
+      sharedMemory:
+        disabled: true
+      resources:
+        limits:
+          gpu: "1"
+        requests:
+          custom:
+            # Increase this value for larger models
+            ephemeral-storage: "2Gi"
+      extraPodSpec:
+        mainContainer:
+          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:my-tag
+          workingDir: /workspace/examples/backends/vllm
+          env:
+            - name: PYTHONHASHSEED
+              value: "0"
+          volumeMounts:
+            - name: kv-transfer-config
+              mountPath: /etc/lmcache
+              readOnly: true
+          command:
+            - /bin/sh
+            - -c
+            - exec python3 -m dynamo.vllm "$@" --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"
+            - --
+          args:
+            - --model
+            - Qwen/Qwen3-0.6B
+            - --disable-hybrid-kv-cache-manager
+        volumes:
+          - name: kv-transfer-config
+            configMap:
+              name: lmcache-mp-connection   # = <LMCacheEngine.metadata.name>-connection
+
+        # Required for CUDA IPC between vLLM and LMCache
+        hostIPC: true
diff --git a/examples/dynamo_integration/deploy/disagg_lmcache_mp.yaml b/examples/dynamo_integration/deploy/disagg_lmcache_mp.yaml
new file mode 100644
index 0000000..6928c42
--- /dev/null
+++ b/examples/dynamo_integration/deploy/disagg_lmcache_mp.yaml
@@ -0,0 +1,97 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+apiVersion: nvidia.com/v1alpha1
+kind: DynamoGraphDeployment
+metadata:
+  name: vllm-disagg-lmcache
+spec:
+  services:
+    Frontend:
+      envFromSecret: hf-token-secret
+      componentType: frontend
+      replicas: 1
+      extraPodSpec:
+        mainContainer:
+          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:my-tag
+    VllmDecodeWorker:
+      envFromSecret: hf-token-secret
+      componentType: worker
+      replicas: 1
+      # mp mode: LMCache owns /dev/shm
+      sharedMemory:
+        disabled: true
+      resources:
+        limits:
+          gpu: "1"
+        requests:
+          custom:
+            # Increase this value for larger models
+            ephemeral-storage: "2Gi"
+      extraPodSpec:
+        # mp mode: CUDA IPC between vLLM and the LMCache process
+        hostIPC: true
+        mainContainer:
+          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:my-tag
+          workingDir: /workspace/examples/backends/vllm
+          env:
+            - name: PYTHONHASHSEED
+              value: "0"
+          volumeMounts:
+            - name: kv-transfer-config
+              mountPath: /etc/lmcache
+              readOnly: true
+          command:
+            - /bin/sh
+            - -c
+            - exec python3 -m dynamo.vllm "$@" --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"
+            - --
+          args:
+            - --model
+            - Qwen/Qwen3-0.6B
+            - --disaggregation-mode
+            - decode
+            - --disable-hybrid-kv-cache-manager
+        volumes:
+          - name: kv-transfer-config
+            configMap:
+              name: lmcache-mp-connection   # = <LMCacheEngine.metadata.name>-connection
+    VllmPrefillWorker:
+      envFromSecret: hf-token-secret
+      componentType: worker
+      replicas: 1
+      sharedMemory:
+        disabled: true
+      resources:
+        limits:
+          gpu: "1"
+        requests:
+          custom:
+            ephemeral-storage: "2Gi"
+      extraPodSpec:
+        hostIPC: true
+        mainContainer:
+          image: nvcr.io/nvidia/ai-dynamo/vllm-runtime:my-tag
+          workingDir: /workspace/examples/backends/vllm
+          env:
+            - name: PYTHONHASHSEED
+              value: "0"
+          volumeMounts:
+            - name: kv-transfer-config
+              mountPath: /etc/lmcache
+              readOnly: true
+          command:
+            - /bin/sh
+            - -c
+            - exec python3 -m dynamo.vllm "$@" --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"
+            - --
+          args:
+            - --model
+            - Qwen/Qwen3-0.6B
+            - --disaggregation-mode
+            - prefill
+            - --disable-hybrid-kv-cache-manager
+        volumes:
+          - name: kv-transfer-config
+            configMap:
+              name: lmcache-mp-connection   # = <LMCacheEngine.metadata.name>-connection
diff --git a/examples/dynamo_integration/deploy/lmcache_engine.yaml b/examples/dynamo_integration/deploy/lmcache_engine.yaml
new file mode 100644
index 0000000..5599a6b
--- /dev/null
+++ b/examples/dynamo_integration/deploy/lmcache_engine.yaml
@@ -0,0 +1,13 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: lmcache-mp   # produces the "lmcache-mp-connection" ConfigMap the workers mount
+  namespace: default   # must match the namespace the workers are deployed into
+spec:
+  image:
+    repository: lmcache/vllm-openai
+    tag: my-tag
+    pullPolicy: IfNotPresent
+  # L1 (CPU RAM) cache size -- bump for production workloads.
+  l1:
+    sizeGB: 16
diff --git a/examples/dynamo_integration/launch/agg_lmcache_mp.sh b/examples/dynamo_integration/launch/agg_lmcache_mp.sh
new file mode 100755
index 0000000..c8ed72e
--- /dev/null
+++ b/examples/dynamo_integration/launch/agg_lmcache_mp.sh
@@ -0,0 +1,62 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+set -e
+trap 'echo Cleaning up...; kill 0' EXIT
+
+# Explicitly unset PROMETHEUS_MULTIPROC_DIR to let Dynamo manage it internally
+unset PROMETHEUS_MULTIPROC_DIR
+
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
+source "$SCRIPT_DIR/../../../common/gpu_utils.sh"
+source "$SCRIPT_DIR/../../../common/launch_utils.sh"
+
+MODEL="Qwen/Qwen3-0.6B"
+
+# ---- Tunable (override via env vars) ----
+MAX_MODEL_LEN="${MAX_MODEL_LEN:-4096}"
+MAX_CONCURRENT_SEQS="${MAX_CONCURRENT_SEQS:-2}"
+
+# Default KV cache cap from profiling (2x safety over min=560 MiB); ~3.8 GiB peak VRAM
+# Profiler/test framework overrides via env
+: "${_PROFILE_OVERRIDE_VLLM_KV_CACHE_BYTES:=1119388000}"
+GPU_MEM_ARGS=$(build_vllm_gpu_mem_args)
+
+HTTP_PORT="${DYN_HTTP_PORT:-8000}"
+LMCACHE_PORT="${LMCACHE_PORT:-5555}"
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-8080}"
+
+print_launch_banner "Launching Aggregated Serving (1 GPU) + LMCache" "$MODEL" "$HTTP_PORT"
+
+# Start the LMCache MP server (out-of-process cache engine).
+lmcache server \
+  --l1-size-gb "${LMCACHE_L1_SIZE_GB:-16}" --eviction-policy LRU \
+  --port "$LMCACHE_PORT" --http-port "$LMCACHE_HTTP_PORT" &
+SERVER_PID=$!
+
+# Wait until the server's HTTP admin endpoint is healthy before launching workers.
+for _ in $(seq 1 60); do
+  if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+    echo "LMCache server process died unexpectedly" >&2
+    exit 1
+  fi
+  curl -sf "http://localhost:$LMCACHE_HTTP_PORT/healthcheck" >/dev/null 2>&1 && break
+  sleep 1
+done
+curl -sf "http://localhost:$LMCACHE_HTTP_PORT/healthcheck" >/dev/null 2>&1 || {
+  echo "lmcache server failed to become healthy on :$LMCACHE_HTTP_PORT" >&2
+  exit 1
+}
+
+python3 -m dynamo.frontend &
+
+DYN_SYSTEM_PORT=${DYN_SYSTEM_PORT:-8081} \
+  python3 -m dynamo.vllm --model "$MODEL" --enforce-eager \
+  --max-model-len "$MAX_MODEL_LEN" \
+  --max-num-seqs "$MAX_CONCURRENT_SEQS" \
+  $GPU_MEM_ARGS \
+  --disable-hybrid-kv-cache-manager \
+  --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\",\"kv_role\":\"kv_both\",\"kv_connector_extra_config\":{\"lmcache.mp.port\":$LMCACHE_PORT}}" &
+
+# Exit on first worker failure; kill 0 in the EXIT trap tears down the rest
+wait_any_exit
diff --git a/examples/dynamo_integration/launch/disagg_lmcache_mp.sh b/examples/dynamo_integration/launch/disagg_lmcache_mp.sh
new file mode 100755
index 0000000..d6fb294
--- /dev/null
+++ b/examples/dynamo_integration/launch/disagg_lmcache_mp.sh
@@ -0,0 +1,80 @@
+#!/bin/bash
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+set -e
+trap 'echo Cleaning up...; kill 0' EXIT
+
+# Explicitly unset PROMETHEUS_MULTIPROC_DIR to let Dynamo manage it internally
+unset PROMETHEUS_MULTIPROC_DIR
+
+SCRIPT_DIR="$(dirname "$(readlink -f "$0")")"
+source "$SCRIPT_DIR/../../../common/gpu_utils.sh"
+source "$SCRIPT_DIR/../../../common/launch_utils.sh"
+
+MODEL="Qwen/Qwen3-0.6B"
+
+# ---- Tunable (override via env vars) ----
+MAX_MODEL_LEN="${MAX_MODEL_LEN:-4096}"
+MAX_CONCURRENT_SEQS="${MAX_CONCURRENT_SEQS:-2}"
+
+# KV cache cap for predictable launches; profiler/test framework overrides via
+# env. Applied per worker process (prefill and decode each get the same value,
+# on their own GPU).
+: "${_PROFILE_OVERRIDE_VLLM_KV_CACHE_BYTES:=1119388000}"
+GPU_MEM_ARGS=$(build_vllm_gpu_mem_args)
+
+HTTP_PORT="${DYN_HTTP_PORT:-8000}"
+LMCACHE_PORT="${LMCACHE_PORT:-5555}"
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-8080}"
+
+print_launch_banner "Launching Disaggregated Serving (2 GPUs) + LMCache" "$MODEL" "$HTTP_PORT"
+
+# Start the single LMCache mp server (out-of-process cache engine) shared by the
+# prefill and decode workers.
+lmcache server \
+  --l1-size-gb "${LMCACHE_L1_SIZE_GB:-16}" --eviction-policy LRU \
+  --port "$LMCACHE_PORT" --http-port "$LMCACHE_HTTP_PORT" &
+SERVER_PID=$!
+
+# Wait until the server's HTTP admin endpoint is healthy before launching workers.
+for _ in $(seq 1 60); do
+  if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+    echo "LMCache server process died unexpectedly" >&2
+    exit 1
+  fi
+  curl -sf "http://localhost:$LMCACHE_HTTP_PORT/healthcheck" >/dev/null 2>&1 && break
+  sleep 1
+done
+curl -sf "http://localhost:$LMCACHE_HTTP_PORT/healthcheck" >/dev/null 2>&1 || {
+  echo "lmcache server failed to become healthy on :$LMCACHE_HTTP_PORT" >&2
+  exit 1
+}
+
+# run ingress
+# dynamo.frontend accepts either --http-port flag or DYN_HTTP_PORT env var (defaults to 8000)
+python3 -m dynamo.frontend &
+
+# run decode worker on GPU 0
+DYN_SYSTEM_PORT=${DYN_SYSTEM_PORT1:-8081} \
+CUDA_VISIBLE_DEVICES=0 python3 -m dynamo.vllm \
+  --model "$MODEL" --enforce-eager \
+  --max-model-len "$MAX_MODEL_LEN" \
+  --max-num-seqs "$MAX_CONCURRENT_SEQS" \
+  $GPU_MEM_ARGS \
+  --disaggregation-mode decode \
+  --disable-hybrid-kv-cache-manager \
+  --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\",\"kv_role\":\"kv_both\",\"kv_connector_extra_config\":{\"lmcache.mp.port\":$LMCACHE_PORT}}" &
+
+# run prefill worker on GPU 1
+DYN_SYSTEM_PORT=${DYN_SYSTEM_PORT2:-8082} \
+CUDA_VISIBLE_DEVICES=1 python3 -m dynamo.vllm \
+  --model "$MODEL" --enforce-eager \
+  --max-model-len "$MAX_MODEL_LEN" \
+  --max-num-seqs "$MAX_CONCURRENT_SEQS" \
+  $GPU_MEM_ARGS \
+  --disaggregation-mode prefill \
+  --disable-hybrid-kv-cache-manager \
+  --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\",\"kv_role\":\"kv_both\",\"kv_connector_extra_config\":{\"lmcache.mp.port\":$LMCACHE_PORT}}" &
+
+# Exit on first worker failure; kill 0 in the EXIT trap tears down the rest
+wait_any_exit
diff --git a/examples/frontend/README.md b/examples/frontend/README.md
new file mode 100644
index 0000000..a37ab7d
--- /dev/null
+++ b/examples/frontend/README.md
@@ -0,0 +1,19 @@
+# Online chat with frontend and context
+This will help you set up vLLM + LMCache and a QA frontend.  
+The default context is a ffmpeg man page.  
+## Prerequisites
+Your server should have at least 1 GPU.  
+
+This will use the port 8000 (for vLLM), 8501 (for the frontend) and port 65432(for LMCache).  
+## Steps
+1.  ```lmcache_server localhost 65432```  
+And wait until it's ready.  
+2. In one terminal,  
+```LMCACHE_CONFIG_FILE=example.yaml CUDA_VISIBLE_DEVICES=0 vllm serve mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'```  
+Wait until it's ready.  
+3. Launch frontend.  
+```pip install openai streamlit```  
+```streamlit run frontend.py```  
+Then open that URL of Streamlit app in browser.  
+## What to expect
+LMCache should be able to reduce the response delay since the second question.  
\ No newline at end of file
diff --git a/examples/frontend/chat_session.py b/examples/frontend/chat_session.py
new file mode 100644
index 0000000..f545314
--- /dev/null
+++ b/examples/frontend/chat_session.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import time
+
+# Third Party
+from openai import OpenAI
+
+
+class ChatSession:
+    def __init__(self, port, context_separator="###"):
+        openai_api_key = "EMPTY"
+        openai_api_base = f"http://localhost:{port}/v1"
+
+        self.client = client = OpenAI(
+            # defaults to os.environ.get("OPENAI_API_KEY")
+            api_key=openai_api_key,
+            base_url=openai_api_base,
+        )
+
+        models = client.models.list()
+        self.model = models.data[0].id
+
+        self.messages = []
+
+        self.final_context = ""
+        self.context_separator = context_separator
+
+    def set_context(self, context_strings):
+        contexts = []
+        for context in context_strings:
+            contexts.append(context)
+
+        self.final_context = self.context_separator.join(contexts)
+        self.on_user_message(self.final_context, display=False)
+        self.on_server_message("Got it!", display=False)
+
+    def get_context(self):
+        return self.final_context
+
+    def on_user_message(self, message, display=True):
+        if display:
+            print("User message:", message)
+        self.messages.append({"role": "user", "content": message})
+
+    def on_server_message(self, message, display=True):
+        if display:
+            print("Server message:", message)
+        self.messages.append({"role": "assistant", "content": message})
+
+    def chat(self, question):
+        self.on_user_message(question)
+
+        start = time.perf_counter()
+        end = None
+        chat_completion = self.client.chat.completions.create(
+            messages=self.messages, model=self.model, temperature=0, stream=True
+        )
+
+        server_message = []
+        for chunk in chat_completion:
+            chunk_message = chunk.choices[0].delta.content
+            if chunk_message is not None:
+                if end is None:
+                    end = time.perf_counter()
+                yield chunk_message
+                server_message.append(chunk_message)
+
+        self.on_server_message("".join(server_message))
+        yield f"\n\n(Response delay: {end - start:.2f} seconds)"
diff --git a/examples/frontend/example.yaml b/examples/frontend/example.yaml
new file mode 100644
index 0000000..cd8935d
--- /dev/null
+++ b/examples/frontend/example.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_cpu: True
+remote_url: "lm://localhost:65432"
+remote_serde: "cachegen"
diff --git a/examples/frontend/ffmpeg.txt b/examples/frontend/ffmpeg.txt
new file mode 100644
index 0000000..940b0a8
--- /dev/null
+++ b/examples/frontend/ffmpeg.txt
@@ -0,0 +1,2069 @@
+FFMPEG(1)						FFMPEG(1)
+
+NAME
+       ffmpeg - ffmpeg video converter
+
+SYNOPSIS
+       ffmpeg [global_options] {[input_file_options] -i input_url} ... 
+       {[output_file_options] output_url} ...
+
+DESCRIPTION
+       ffmpeg is a very fast video and audio converter that can also 
+       grab from a live audio/video source. It can also convert between 
+       arbitrary sample rates and resize video on the fly with a high 
+       quality polyphase filter.
+
+       ffmpeg reads from an arbitrary number of input "files" (which 
+       can be regular files, pipes, network streams, grabbing devices, 
+       etc.), specified by the "-i" option, and writes to an arbitrary 
+       number of output "files", which are specified by a plain output
+       url. Anything found on the command line which cannot be inter-
+       preted as an option is considered to be an output url.
+
+       Each input or output url can, in principle, contain any number of 
+       streams of different types (video/audio/subtitle/attachment/data). 
+       The allowed number and/or types of streams may be limited by the 
+       container format. Selecting which streams from which inputs will 
+       go into which output is either done automatically or with the 
+       "-map" option (see the Stream selection chapter).
+
+       To refer to input files in options, you must use their indices 
+       (0-based). E.g.  the first input file is 0, the second is 1, etc. 
+       Similarly, streams within a file are referred to by their indices. 
+       E.g. "2:3" refers to the fourth stream in the third input file. 
+       Also see the Stream specifiers chapter.
+
+       As a general rule, options are applied to the next specified file. 
+       Therefore, order is important, and you can have the same option on 
+       the command line multiple times. Each occurrence is then applied 
+       to the next input or output file.  Exceptions from this rule are 
+       the global options (e.g. verbosity level), which should be specified 
+       first.
+
+       Do not mix input and output files -- first specify all input files, 
+       then all output files. Also do not mix options which belong to 
+       different files. All options apply ONLY to the next input or output 
+       file and are reset between files.
+
+       •   To set the video bitrate of the output file to 64 kbit/s:
+
+		   ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi
+
+       •   To force the frame rate of the output file to 24 fps:
+
+		   ffmpeg -i input.avi -r 24 output.avi
+
+       •   To force the frame rate of the input file (valid for raw formats only) to 1 fps and the frame
+	   rate of the output file to 24 fps:
+
+		   ffmpeg -r 1 -i input.m2v -r 24 output.avi
+
+       The format option may be needed for raw input files.
+
+DETAILED DESCRIPTION
+       The transcoding process in ffmpeg for each output can be described by the following diagram:
+
+		_______ 	     ______________
+	       |       |	    |		   |
+	       | input |  demuxer   | encoded data |   decoder
+	       | file  | ---------> | packets	   | -----+
+	       |_______|	    |______________|	  |
+							  v
+						      _________
+						     |	       |
+						     | decoded |
+						     | frames  |
+						     |_________|
+		________	     ______________	  |
+	       |	|	    |		   |	  |
+	       | output | <-------- | encoded data | <----+
+	       | file	|   muxer   | packets	   |   encoder
+	       |________|	    |______________|
+
+       ffmpeg calls the libavformat library (containing demuxers) to read input files and get packets
+       containing encoded data from them. When there are multiple input files, ffmpeg tries to keep them
+       synchronized by tracking lowest timestamp on any active input stream.
+
+       Encoded packets are then passed to the decoder (unless streamcopy is selected for the stream, see
+       further for a description). The decoder produces uncompressed frames (raw video/PCM audio/...)
+       which can be processed further by filtering (see next section). After filtering, the frames are
+       passed to the encoder, which encodes them and outputs encoded packets. Finally those are passed to
+       the muxer, which writes the encoded packets to the output file.
+
+   Filtering
+       Before encoding, ffmpeg can process raw audio and video frames using filters from the libavfilter
+       library. Several chained filters form a filter graph. ffmpeg distinguishes between two types of
+       filtergraphs: simple and complex.
+
+       Simple filtergraphs
+
+       Simple filtergraphs are those that have exactly one input and output, both of the same type. In
+       the above diagram they can be represented by simply inserting an additional step between decoding
+       and encoding:
+
+		_________			 ______________
+	       |	 |			|	       |
+	       | decoded |			| encoded data |
+	       | frames  |\		      _ | packets      |
+	       |_________| \		      /||______________|
+			    \	__________   /
+		 simple     _\||	  | /  encoder
+		 filtergraph   | filtered |/
+			       | frames   |
+			       |__________|
+
+       Simple filtergraphs are configured with the per-stream -filter option (with -vf and -af aliases
+       for video and audio respectively).  A simple filtergraph for video can look for example like this:
+
+		_______        _____________	    _______	   ________
+	       |       |      | 	    |	   |	   |	  |	   |
+	       | input | ---> | deinterlace | ---> | scale | ---> | output |
+	       |_______|      |_____________|	   |_______|	  |________|
+
+       Note that some filters change frame properties but not frame contents. E.g. the "fps" filter in
+       the example above changes number of frames, but does not touch the frame contents. Another example
+       is the "setpts" filter, which only sets timestamps and otherwise passes the frames unchanged.
+
+       Complex filtergraphs
+
+       Complex filtergraphs are those which cannot be described as simply a linear processing chain
+       applied to one stream. This is the case, for example, when the graph has more than one input
+       and/or output, or when output stream type is different from input. They can be represented with
+       the following diagram:
+
+		_________
+	       |	 |
+	       | input 0 |\		       __________
+	       |_________| \		      | 	 |
+			    \	_________    /| output 0 |
+			     \ |	 |  / |__________|
+		_________     \| complex | /
+	       |	 |     |	 |/
+	       | input 1 |---->| filter  |\
+	       |_________|     |	 | \   __________
+			      /| graph	 |  \ | 	 |
+			     / |	 |   \| output 1 |
+		_________   /  |_________|    |__________|
+	       |	 | /
+	       | input 2 |/
+	       |_________|
+
+       Complex filtergraphs are configured with the -filter_complex option.  Note that this option is
+       global, since a complex filtergraph, by its nature, cannot be unambiguously associated with a
+       single stream or file.
+
+       The -lavfi option is equivalent to -filter_complex.
+
+       A trivial example of a complex filtergraph is the "overlay" filter, which has two video inputs and
+       one video output, containing one video overlaid on top of the other. Its audio counterpart is the
+       "amix" filter.
+
+   Stream copy
+       Stream copy is a mode selected by supplying the "copy" parameter to the -codec option. It makes
+       ffmpeg omit the decoding and encoding step for the specified stream, so it does only demuxing and
+       muxing. It is useful for changing the container format or modifying container-level metadata. The
+       diagram above will, in this case, simplify to this:
+
+		_______ 	     ______________	       ________
+	       |       |	    |		   |	      |        |
+	       | input |  demuxer   | encoded data |  muxer   | output |
+	       | file  | ---------> | packets	   | -------> | file   |
+	       |_______|	    |______________|	      |________|
+
+       Since there is no decoding or encoding, it is very fast and there is no quality loss. However, it
+       might not work in some cases because of many factors. Applying filters is obviously also
+       impossible, since filters work on uncompressed data.
+
+STREAM SELECTION
+       ffmpeg provides the "-map" option for manual control of stream selection in each output file.
+       Users can skip "-map" and let ffmpeg perform automatic stream selection as described below. The
+       "-vn / -an / -sn / -dn" options can be used to skip inclusion of video, audio, subtitle and data
+       streams respectively, whether manually mapped or automatically selected, except for those streams
+       which are outputs of complex filtergraphs.
+
+   Description
+       The sub-sections that follow describe the various rules that are involved in stream selection.
+       The examples that follow next show how these rules are applied in practice.
+
+       While every effort is made to accurately reflect the behavior of the program, FFmpeg is under
+       continuous development and the code may have changed since the time of this writing.
+
+       Automatic stream selection
+
+       In the absence of any map options for a particular output file, ffmpeg inspects the output format
+       to check which type of streams can be included in it, viz. video, audio and/or subtitles. For each
+       acceptable stream type, ffmpeg will pick one stream, when available, from among all the inputs.
+
+       It will select that stream based upon the following criteria:
+
+       •   for video, it is the stream with the highest resolution,
+
+       •   for audio, it is the stream with the most channels,
+
+       •   for subtitles, it is the first subtitle stream found but there's a caveat.  The output
+	   format's default subtitle encoder can be either text-based or image-based, and only a subtitle
+	   stream of the same type will be chosen.
+
+       In the case where several streams of the same type rate equally, the stream with the lowest index
+       is chosen.
+
+       Data or attachment streams are not automatically selected and can only be included using "-map".
+
+       Manual stream selection
+
+       When "-map" is used, only user-mapped streams are included in that output file, with one possible
+       exception for filtergraph outputs described below.
+
+       Complex filtergraphs
+
+       If there are any complex filtergraph output streams with unlabeled pads, they will be added to the
+       first output file. This will lead to a fatal error if the stream type is not supported by the
+       output format. In the absence of the map option, the inclusion of these streams leads to the
+       automatic stream selection of their types being skipped. If map options are present, these
+       filtergraph streams are included in addition to the mapped streams.
+
+       Complex filtergraph output streams with labeled pads must be mapped once and exactly once.
+
+       Stream handling
+
+       Stream handling is independent of stream selection, with an exception for subtitles described
+       below. Stream handling is set via the "-codec" option addressed to streams within a specific
+       output file. In particular, codec options are applied by ffmpeg after the stream selection process
+       and thus do not influence the latter. If no "-codec" option is specified for a stream type, ffmpeg
+       will select the default encoder registered by the output file muxer.
+
+       An exception exists for subtitles. If a subtitle encoder is specified for an output file, the
+       first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate
+       if the specified encoder can convert the selected stream or if the converted stream is acceptable
+       within the output format. This applies generally as well: when the user sets an encoder manually,
+       the stream selection process cannot check if the encoded stream can be muxed into the output file.
+       If it cannot, ffmpeg will abort and all output files will fail to be processed.
+
+   Examples
+       The following examples illustrate the behavior, quirks and limitations of ffmpeg's stream
+       selection methods.
+
+       They assume the following three input files.
+
+	       input file 'A.avi'
+		     stream 0: video 640x360
+		     stream 1: audio 2 channels
+
+	       input file 'B.mp4'
+		     stream 0: video 1920x1080
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (text)
+		     stream 3: audio 5.1 channels
+		     stream 4: subtitles (text)
+
+	       input file 'C.mkv'
+		     stream 0: video 1280x720
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (image)
+
+       Example: automatic stream selection
+
+	       ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
+
+       There are three output files specified, and for the first two, no "-map" options are set, so
+       ffmpeg will select streams for these two files automatically.
+
+       out1.mkv is a Matroska container file and accepts video, audio and subtitle streams, so ffmpeg
+       will try to select one of each type.For video, it will select "stream 0" from B.mp4, which has the
+       highest resolution among all the input video streams.For audio, it will select "stream 3" from
+       B.mp4, since it has the greatest number of channels.For subtitles, it will select "stream 2" from
+       B.mp4, which is the first subtitle stream from among A.avi and B.mp4.
+
+       out2.wav accepts only audio streams, so only "stream 3" from B.mp4 is selected.
+
+       For out3.mov, since a "-map" option is set, no automatic stream selection will occur. The "-map
+       1:a" option will select all audio streams from the second input B.mp4. No other streams will be
+       included in this output file.
+
+       For the first two outputs, all included streams will be transcoded. The encoders chosen will be
+       the default ones registered by each output format, which may not match the codec of the selected
+       input streams.
+
+       For the third output, codec option for audio streams has been set to "copy", so no decoding-
+       filtering-encoding operations will occur, or can occur.	Packets of selected streams shall be
+       conveyed from the input file and muxed within the output file.
+
+       Example: automatic subtitles selection
+
+	       ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
+
+       Although out1.mkv is a Matroska container file which accepts subtitle streams, only a video and
+       audio stream shall be selected. The subtitle stream of C.mkv is image-based and the default
+       subtitle encoder of the Matroska muxer is text-based, so a transcode operation for the subtitles
+       is expected to fail and hence the stream isn't selected. However, in out2.mkv, a subtitle encoder
+       is specified in the command and so, the subtitle stream is selected, in addition to the video
+       stream. The presence of "-an" disables audio stream selection for out2.mkv.
+
+       Example: unlabeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
+
+       A filtergraph is setup here using the "-filter_complex" option and consists of a single video
+       filter. The "overlay" filter requires exactly two video inputs, but none are specified, so the
+       first two available video streams are used, those of A.avi and C.mkv. The output pad of the filter
+       has no label and so is sent to the first output file out1.mp4. Due to this, automatic selection of
+       the video stream is skipped, which would have selected the stream in B.mp4. The audio stream with
+       most channels viz. "stream 3" in B.mp4, is chosen automatically. No subtitle stream is chosen
+       however, since the MP4 format has no default subtitle encoder registered, and the user hasn't
+       specified a subtitle encoder.
+
+       The 2nd output file, out2.srt, only accepts text-based subtitle streams. So, even though the first
+       subtitle stream available belongs to C.mkv, it is image-based and hence skipped.  The selected
+       stream, "stream 2" in B.mp4, is the first text-based subtitle stream.
+
+       Example: labeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -map '[outv]' -an        out1.mp4 \
+					       out2.mkv \
+		      -map '[outv]' -map 1:a:0 out3.mkv
+
+       The above command will fail, as the output pad labelled "[outv]" has been mapped twice.	None of
+       the output files shall be processed.
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -an	 out1.mp4 \
+				 out2.mkv \
+		      -map 1:a:0 out3.mkv
+
+       This command above will also fail as the hue filter output has a label, "[outv]", and hasn't been
+       mapped anywhere.
+
+       The command should be modified as follows,
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
+		       -map '[outv1]' -an	 out1.mp4 \
+						 out2.mkv \
+		       -map '[outv2]' -map 1:a:0 out3.mkv
+
+       The video stream from B.mp4 is sent to the hue filter, whose output is cloned once using the split
+       filter, and both outputs labelled. Then a copy each is mapped to the first and third output files.
+
+       The overlay filter, requiring two video inputs, uses the first two unused video streams. Those are
+       the streams from A.avi and C.mkv. The overlay output isn't labelled, so it is sent to the first
+       output file out1.mp4, regardless of the presence of the "-map" option.
+
+       The aresample filter is sent the first unused audio stream, that of A.avi. Since this filter
+       output is also unlabelled, it too is mapped to the first output file. The presence of "-an" only
+       suppresses automatic or manual stream selection of audio streams, not outputs sent from
+       filtergraphs. Both these mapped streams shall be ordered before the mapped stream in out1.mp4.
+
+       The video, audio and subtitle streams mapped to "out2.mkv" are entirely determined by automatic
+       stream selection.
+
+       out3.mkv consists of the cloned video output from the hue filter and the first audio stream from
+       B.mp4.
+
+OPTIONS
+       All the numerical options, if not specified otherwise, accept a string representing a number as
+       input, which may be followed by one of the SI unit prefixes, for example: 'K', 'M', or 'G'.
+
+       If 'i' is appended to the SI unit prefix, the complete prefix will be interpreted as a unit prefix
+       for binary multiples, which are based on powers of 1024 instead of powers of 1000. Appending 'B'
+       to the SI unit prefix multiplies the value by 8. This allows using, for example: 'KB', 'MiB', 'G'
+       and 'B' as number suffixes.
+
+       Options which do not take arguments are boolean options, and set the corresponding value to true.
+       They can be set to false by prefixing the option name with "no". For example using "-nofoo" will
+       set the boolean option with name "foo" to false.
+
+   Stream specifiers
+       Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers are used to
+       precisely specify which stream(s) a given option belongs to.
+
+       A stream specifier is a string generally appended to the option name and separated from it by a
+       colon. E.g. "-codec:a:1 ac3" contains the "a:1" stream specifier, which matches the second audio
+       stream. Therefore, it would select the ac3 codec for the second audio stream.
+
+       A stream specifier can match several streams, so that the option is applied to all of them. E.g.
+       the stream specifier in "-b:a 128k" matches all audio streams.
+
+       An empty stream specifier matches all streams. For example, "-codec copy" or "-codec: copy" would
+       copy all the streams without reencoding.
+
+       Possible forms of stream specifiers are:
+
+       stream_index
+	   Matches the stream with this index. E.g. "-threads:1 4" would set the thread count for the
+	   second stream to 4. If stream_index is used as an additional stream specifier (see below),
+	   then it selects stream number stream_index from the matching streams. Stream numbering is
+	   based on the order of the streams as detected by libavformat except when a program ID is also
+	   specified. In this case it is based on the ordering of the streams in the program.
+
+       stream_type[:additional_stream_specifier]
+	   stream_type is one of following: 'v' or 'V' for video, 'a' for audio, 's' for subtitle, 'd'
+	   for data, and 't' for attachments. 'v' matches all video streams, 'V' only matches video
+	   streams which are not attached pictures, video thumbnails or cover arts. If
+	   additional_stream_specifier is used, then it matches streams which both have this type and
+	   match the additional_stream_specifier. Otherwise, it matches all streams of the specified
+	   type.
+
+       p:program_id[:additional_stream_specifier]
+	   Matches streams which are in the program with the id program_id. If
+	   additional_stream_specifier is used, then it matches streams which both are part of the
+	   program and match the additional_stream_specifier.
+
+       #stream_id or i:stream_id
+	   Match the stream by stream id (e.g. PID in MPEG-TS container).
+
+       m:key[:value]
+	   Matches streams with the metadata tag key having the specified value. If value is not given,
+	   matches streams that contain the given tag with any value.
+
+       u   Matches streams with usable configuration, the codec must be defined and the essential
+	   information such as video dimension or audio sample rate must be present.
+
+	   Note that in ffmpeg, matching by metadata will only work properly for input files.
+
+   Generic options
+       These options are shared amongst the ff* tools.
+
+       -L  Show license.
+
+       -h, -?, -help, --help [arg]
+	   Show help. An optional parameter may be specified to print help about a specific item. If no
+	   argument is specified, only basic (non advanced) tool options are shown.
+
+	   Possible values of arg are:
+
+	   long
+	       Print advanced tool options in addition to the basic tool options.
+
+	   full
+	       Print complete list of options, including shared and private options for encoders,
+	       decoders, demuxers, muxers, filters, etc.
+
+	   decoder=decoder_name
+	       Print detailed information about the decoder named decoder_name. Use the -decoders option
+	       to get a list of all decoders.
+
+	   encoder=encoder_name
+	       Print detailed information about the encoder named encoder_name. Use the -encoders option
+	       to get a list of all encoders.
+
+	   demuxer=demuxer_name
+	       Print detailed information about the demuxer named demuxer_name. Use the -formats option
+	       to get a list of all demuxers and muxers.
+
+	   muxer=muxer_name
+	       Print detailed information about the muxer named muxer_name. Use the -formats option to
+	       get a list of all muxers and demuxers.
+
+	   filter=filter_name
+	       Print detailed information about the filter name filter_name. Use the -filters option to
+	       get a list of all filters.
+
+	   bsf=bitstream_filter_name
+	       Print detailed information about the bitstream filter name bitstream_filter_name.  Use the
+	       -bsfs option to get a list of all bitstream filters.
+
+       -version
+	   Show version.
+
+       -formats
+	   Show available formats (including devices).
+
+       -demuxers
+	   Show available demuxers.
+
+       -muxers
+	   Show available muxers.
+
+       -devices
+	   Show available devices.
+
+       -codecs
+	   Show all codecs known to libavcodec.
+
+	   Note that the term 'codec' is used throughout this documentation as a shortcut for what is
+	   more correctly called a media bitstream format.
+
+       -decoders
+	   Show available decoders.
+
+       -encoders
+	   Show all available encoders.
+
+       -bsfs
+	   Show available bitstream filters.
+
+       -protocols
+	   Show available protocols.
+
+       -filters
+	   Show available libavfilter filters.
+
+       -pix_fmts
+	   Show available pixel formats.
+
+       -sample_fmts
+	   Show available sample formats.
+
+       -layouts
+	   Show channel names and standard channel layouts.
+
+       -colors
+	   Show recognized color names.
+
+       -sources device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sources of the input device.  Some devices may provide system-dependent
+	   source names that cannot be autodetected.  The returned list cannot be assumed to be always
+	   complete.
+
+		   ffmpeg -sources pulse,server=192.168.0.4
+
+       -sinks device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sinks of the output device.  Some devices may provide system-dependent sink
+	   names that cannot be autodetected.  The returned list cannot be assumed to be always complete.
+
+		   ffmpeg -sinks pulse,server=192.168.0.4
+
+       -loglevel [flags+]loglevel | -v [flags+]loglevel
+	   Set logging level and flags used by the library.
+
+	   The optional flags prefix can consist of the following values:
+
+	   repeat
+	       Indicates that repeated log output should not be compressed to the first line and the
+	       "Last message repeated n times" line will be omitted.
+
+	   level
+	       Indicates that log output should add a "[level]" prefix to each message line. This can be
+	       used as an alternative to log coloring, e.g. when dumping the log to file.
+
+	   Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single flag without
+	   affecting other flags or changing loglevel. When setting both flags and loglevel, a '+'
+	   separator is expected between the last flags value and before loglevel.
+
+	   loglevel is a string or a number containing one of the following values:
+
+	   quiet, -8
+	       Show nothing at all; be silent.
+
+	   panic, 0
+	       Only show fatal errors which could lead the process to crash, such as an assertion
+	       failure. This is not currently used for anything.
+
+	   fatal, 8
+	       Only show fatal errors. These are errors after which the process absolutely cannot
+	       continue.
+
+	   error, 16
+	       Show all errors, including ones which can be recovered from.
+
+	   warning, 24
+	       Show all warnings and errors. Any message related to possibly incorrect or unexpected
+	       events will be shown.
+
+	   info, 32
+	       Show informative messages during processing. This is in addition to warnings and errors.
+	       This is the default value.
+
+	   verbose, 40
+	       Same as "info", except more verbose.
+
+	   debug, 48
+	       Show everything, including debugging information.
+
+	   trace, 56
+
+	   For example to enable repeated log output, add the "level" prefix, and set loglevel to
+	   "verbose":
+
+		   ffmpeg -loglevel repeat+level+verbose -i input output
+
+	   Another example that enables repeated log output without affecting current state of "level"
+	   prefix flag or loglevel:
+
+		   ffmpeg [...] -loglevel +repeat
+
+	   By default the program logs to stderr. If coloring is supported by the terminal, colors are
+	   used to mark errors and warnings. Log coloring can be disabled setting the environment
+	   variable AV_LOG_FORCE_NOCOLOR or NO_COLOR, or can be forced setting the environment variable
+	   AV_LOG_FORCE_COLOR.	The use of the environment variable NO_COLOR is deprecated and will be
+	   dropped in a future FFmpeg version.
+
+       -report
+	   Dump full command line and console output to a file named "program-YYYYMMDD-HHMMSS.log" in the
+	   current directory.  This file can be useful for bug reports.  It also implies "-loglevel
+	   debug".
+
+	   Setting the environment variable FFREPORT to any value has the same effect. If the value is a
+	   ':'-separated key=value sequence, these options will affect the report; option values must be
+	   escaped if they contain special characters or the options delimiter ':' (see the ``Quoting and
+	   escaping'' section in the ffmpeg-utils manual).
+
+	   The following options are recognized:
+
+	   file
+	       set the file name to use for the report; %p is expanded to the name of the program, %t is
+	       expanded to a timestamp, "%%" is expanded to a plain "%"
+
+	   level
+	       set the log verbosity level using a numerical value (see "-loglevel").
+
+	   For example, to output a report to a file named ffreport.log using a log level of 32 (alias
+	   for log level "info"):
+
+		   FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+	   Errors in parsing the environment variable are not fatal, and will not appear in the report.
+
+       -hide_banner
+	   Suppress printing banner.
+
+	   All FFmpeg tools will normally show a copyright notice, build options and library versions.
+	   This option can be used to suppress printing this information.
+
+       -cpuflags flags (global)
+	   Allows setting and clearing cpu flags. This option is intended for testing. Do not use it
+	   unless you know what you're doing.
+
+		   ffmpeg -cpuflags -sse+mmx ...
+		   ffmpeg -cpuflags mmx ...
+		   ffmpeg -cpuflags 0 ...
+
+	   Possible flags for this option are:
+
+	   x86
+	       mmx
+	       mmxext
+	       sse
+	       sse2
+	       sse2slow
+	       sse3
+	       sse3slow
+	       ssse3
+	       atom
+	       sse4.1
+	       sse4.2
+	       avx
+	       avx2
+	       xop
+	       fma3
+	       fma4
+	       3dnow
+	       3dnowext
+	       bmi1
+	       bmi2
+	       cmov
+	   ARM
+	       armv5te
+	       armv6
+	       armv6t2
+	       vfp
+	       vfpv3
+	       neon
+	       setend
+	   AArch64
+	       armv8
+	       vfp
+	       neon
+	   PowerPC
+	       altivec
+	   Specific Processors
+	       pentium2
+	       pentium3
+	       pentium4
+	       k6
+	       k62
+	       athlon
+	       athlonxp
+	       k8
+
+   AVOptions
+       These options are provided directly by the libavformat, libavdevice and libavcodec libraries. To
+       see the list of available AVOptions, use the -help option. They are separated into two categories:
+
+       generic
+	   These options can be set for any container, codec or device. Generic options are listed under
+	   AVFormatContext options for containers/devices and under AVCodecContext options for codecs.
+
+       private
+	   These options are specific to the given container, device or codec. Private options are listed
+	   under their corresponding containers/devices/codecs.
+
+       For example to write an ID3v2.3 header instead of a default ID3v2.4 to an MP3 file, use the
+       id3v2_version private option of the MP3 muxer:
+
+	       ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+       All codec AVOptions are per-stream, and thus a stream specifier should be attached to them:
+
+	       ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+       In the above example, a multichannel audio stream is mapped twice for output.  The first instance
+       is encoded with codec ac3 and bitrate 640k.  The second instance is downmixed to 2 channels and
+       encoded with codec aac. A bitrate of 128k is specified for it using absolute index of the output
+       stream.
+
+       Note: the -nooption syntax cannot be used for boolean AVOptions, use -option 0/-option 1.
+
+       Note: the old undocumented way of specifying per-stream AVOptions by prepending v/a/s to the
+       options name is now obsolete and will be removed soon.
+
+   Main options
+       -f fmt (input/output)
+	   Force input or output file format. The format is normally auto detected for input files and
+	   guessed from the file extension for output files, so this option is not needed in most cases.
+
+       -i url (input)
+	   input file url
+
+       -y (global)
+	   Overwrite output files without asking.
+
+       -n (global)
+	   Do not overwrite output files, and exit immediately if a specified output file already exists.
+
+       -stream_loop number (input)
+	   Set number of times input stream shall be looped. Loop 0 means no loop, loop -1 means infinite
+	   loop.
+
+       -c[:stream_specifier] codec (input/output,per-stream)
+       -codec[:stream_specifier] codec (input/output,per-stream)
+	   Select an encoder (when used before an output file) or a decoder (when used before an input
+	   file) for one or more streams. codec is the name of a decoder/encoder or a special value
+	   "copy" (output only) to indicate that the stream is not to be re-encoded.
+
+	   For example
+
+		   ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+
+	   encodes all video streams with libx264 and copies all audio streams.
+
+	   For each stream, the last matching "c" option is applied, so
+
+		   ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+
+	   will copy all the streams except the second video, which will be encoded with libx264, and the
+	   138th audio, which will be encoded with libvorbis.
+
+       -t duration (input/output)
+	   When used as an input option (before "-i"), limit the duration of data read from the input
+	   file.
+
+	   When used as an output option (before an output url), stop writing the output after its
+	   duration reaches duration.
+
+	   duration must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -to position (input/output)
+	   Stop writing the output or reading the input at position.  position must be a time duration
+	   specification, see the Time duration section in the ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -fs limit_size (output)
+	   Set the file size limit, expressed in bytes. No further chunk of bytes is written after the
+	   limit is exceeded. The size of the output file is slightly more than the requested file size.
+
+       -ss position (input/output)
+	   When used as an input option (before "-i"), seeks in this input file to position. Note that in
+	   most formats it is not possible to seek exactly, so ffmpeg will seek to the closest seek point
+	   before position.  When transcoding and -accurate_seek is enabled (the default), this extra
+	   segment between the seek point and position will be decoded and discarded. When doing stream
+	   copy or when -noaccurate_seek is used, it will be preserved.
+
+	   When used as an output option (before an output url), decodes but discards input until the
+	   timestamps reach position.
+
+	   position must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+       -sseof position (input)
+	   Like the "-ss" option but relative to the "end of file". That is negative values are earlier
+	   in the file, 0 is at EOF.
+
+       -itsoffset offset (input)
+	   Set the input time offset.
+
+	   offset must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   The offset is added to the timestamps of the input files. Specifying a positive offset means
+	   that the corresponding streams are delayed by the time duration specified in offset.
+
+       -itsscale scale (input,per-stream)
+	   Rescale input timestamps. scale should be a floating point number.
+
+       -timestamp date (output)
+	   Set the recording timestamp in the container.
+
+	   date must be a date specification, see the Date section in the ffmpeg-utils(1) manual.
+
+       -metadata[:metadata_specifier] key=value (output,per-metadata)
+	   Set a metadata key/value pair.
+
+	   An optional metadata_specifier may be given to set metadata on streams, chapters or programs.
+	   See "-map_metadata" documentation for details.
+
+	   This option overrides metadata set with "-map_metadata". It is also possible to delete
+	   metadata by using an empty value.
+
+	   For example, for setting the title in the output file:
+
+		   ffmpeg -i in.avi -metadata title="my title" out.flv
+
+	   To set the language of the first audio stream:
+
+		   ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
+
+       -disposition[:stream_specifier] value (output,per-stream)
+	   Sets the disposition for a stream.
+
+	   This option overrides the disposition copied from the input stream. It is also possible to
+	   delete the disposition by setting it to 0.
+
+	   The following dispositions are recognized:
+
+	   default
+	   dub
+	   original
+	   comment
+	   lyrics
+	   karaoke
+	   forced
+	   hearing_impaired
+	   visual_impaired
+	   clean_effects
+	   attached_pic
+	   captions
+	   descriptions
+	   dependent
+	   metadata
+
+	   For example, to make the second audio stream the default stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
+
+	   To make the second subtitle stream the default stream and remove the default disposition from
+	   the first subtitle stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
+
+	   To add an embedded cover/thumbnail:
+
+		   ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
+
+	   Not all muxers support embedded thumbnails, and those who do, only support a few formats, like
+	   JPEG or PNG.
+
+       -program [title=title:][program_num=program_num:]st=stream[:st=stream...] (output)
+	   Creates a program with the specified title, program_num and adds the specified stream(s) to
+	   it.
+
+       -target type (output)
+	   Specify target file type ("vcd", "svcd", "dvd", "dv", "dv50"). type may be prefixed with
+	   "pal-", "ntsc-" or "film-" to use the corresponding standard. All the format options (bitrate,
+	   codecs, buffer sizes) are then set automatically. You can just type:
+
+		   ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
+
+	   Nevertheless you can specify additional options as long as you know they do not conflict with
+	   the standard, as in:
+
+		   ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+
+       -dn (input/output)
+	   As an input option, blocks all data streams of a file from being filtered or being
+	   automatically selected or mapped for any output. See "-discard" option to disable streams
+	   individually.
+
+	   As an output option, disables data recording i.e. automatic selection or mapping of any data
+	   stream. For full manual control see the "-map" option.
+
+       -dframes number (output)
+	   Set the number of data frames to output. This is an obsolete alias for "-frames:d", which you
+	   should use instead.
+
+       -frames[:stream_specifier] framecount (output,per-stream)
+	   Stop writing to the stream after framecount frames.
+
+       -q[:stream_specifier] q (output,per-stream)
+       -qscale[:stream_specifier] q (output,per-stream)
+	   Use fixed quality scale (VBR). The meaning of q/qscale is codec-dependent.  If qscale is used
+	   without a stream_specifier then it applies only to the video stream, this is to maintain
+	   compatibility with previous behavior and as specifying the same codec specific value to 2
+	   different codecs that is audio and video generally is not what is intended when no
+	   stream_specifier is used.
+
+       -filter[:stream_specifier] filtergraph (output,per-stream)
+	   Create the filtergraph specified by filtergraph and use it to filter the stream.
+
+	   filtergraph is a description of the filtergraph to apply to the stream, and must have a single
+	   input and a single output of the same type of the stream. In the filtergraph, the input is
+	   associated to the label "in", and the output to the label "out". See the ffmpeg-filters manual
+	   for more information about the filtergraph syntax.
+
+	   See the -filter_complex option if you want to create filtergraphs with multiple inputs and/or
+	   outputs.
+
+       -filter_script[:stream_specifier] filename (output,per-stream)
+	   This option is similar to -filter, the only difference is that its argument is the name of the
+	   file from which a filtergraph description is to be read.
+
+       -filter_threads nb_threads (global)
+	   Defines how many threads are used to process a filter pipeline. Each pipeline will produce a
+	   thread pool with this many threads available for parallel processing.  The default is the
+	   number of available CPUs.
+
+       -pre[:stream_specifier] preset_name (output,per-stream)
+	   Specify the preset for matching stream(s).
+
+       -stats (global)
+	   Print encoding progress/statistics. It is on by default, to explicitly disable it you need to
+	   specify "-nostats".
+
+       -progress url (global)
+	   Send program-friendly progress information to url.
+
+	   Progress information is written approximately every second and at the end of the encoding
+	   process. It is made of "key=value" lines. key consists of only alphanumeric characters. The
+	   last key of a sequence of progress information is always "progress".
+
+       -stdin
+	   Enable interaction on standard input. On by default unless standard input is used as an input.
+	   To explicitly disable interaction you need to specify "-nostdin".
+
+	   Disabling interaction on standard input is useful, for example, if ffmpeg is in the background
+	   process group. Roughly the same result can be achieved with "ffmpeg ... < /dev/null" but it
+	   requires a shell.
+
+       -debug_ts (global)
+	   Print timestamp information. It is off by default. This option is mostly useful for testing
+	   and debugging purposes, and the output format may change from one version to another, so it
+	   should not be employed by portable scripts.
+
+	   See also the option "-fdebug ts".
+
+       -attach filename (output)
+	   Add an attachment to the output file. This is supported by a few formats like Matroska for
+	   e.g. fonts used in rendering subtitles. Attachments are implemented as a specific type of
+	   stream, so this option will add a new stream to the file. It is then possible to use per-
+	   stream options on this stream in the usual way. Attachment streams created with this option
+	   will be created after all the other streams (i.e. those created with "-map" or automatic
+	   mappings).
+
+	   Note that for Matroska you also have to set the mimetype metadata tag:
+
+		   ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
+
+	   (assuming that the attachment stream will be third in the output file).
+
+       -dump_attachment[:stream_specifier] filename (input,per-stream)
+	   Extract the matching attachment stream into a file named filename. If filename is empty, then
+	   the value of the "filename" metadata tag will be used.
+
+	   E.g. to extract the first attachment to a file named 'out.ttf':
+
+		   ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
+
+	   To extract all attachments to files determined by the "filename" tag:
+
+		   ffmpeg -dump_attachment:t "" -i INPUT
+
+	   Technical note -- attachments are implemented as codec extradata, so this option can actually
+	   be used to extract extradata from any stream, not just attachments.
+
+       -noautorotate
+	   Disable automatically rotating video based on file metadata.
+
+   Video Options
+       -vframes number (output)
+	   Set the number of video frames to output. This is an obsolete alias for "-frames:v", which you
+	   should use instead.
+
+       -r[:stream_specifier] fps (input/output,per-stream)
+	   Set frame rate (Hz value, fraction or abbreviation).
+
+	   As an input option, ignore any timestamps stored in the file and instead generate timestamps
+	   assuming constant frame rate fps.  This is not the same as the -framerate option used for some
+	   input formats like image2 or v4l2 (it used to be the same in older versions of FFmpeg).  If in
+	   doubt use -framerate instead of the input option -r.
+
+	   As an output option, duplicate or drop input frames to achieve constant output frame rate fps.
+
+       -s[:stream_specifier] size (input/output,per-stream)
+	   Set frame size.
+
+	   As an input option, this is a shortcut for the video_size private option, recognized by some
+	   demuxers for which the frame size is either not stored in the file or is configurable -- e.g.
+	   raw video or video grabbers.
+
+	   As an output option, this inserts the "scale" video filter to the end of the corresponding
+	   filtergraph. Please use the "scale" filter directly to insert it at the beginning or some
+	   other place.
+
+	   The format is wxh (default - same as source).
+
+       -aspect[:stream_specifier] aspect (output,per-stream)
+	   Set the video display aspect ratio specified by aspect.
+
+	   aspect can be a floating point number string, or a string of the form num:den, where num and
+	   den are the numerator and denominator of the aspect ratio. For example "4:3", "16:9",
+	   "1.3333", and "1.7777" are valid argument values.
+
+	   If used together with -vcodec copy, it will affect the aspect ratio stored at container level,
+	   but not the aspect ratio stored in encoded frames, if it exists.
+
+       -vn (input/output)
+	   As an input option, blocks all video streams of a file from being filtered or being
+	   automatically selected or mapped for any output. See "-discard" option to disable streams
+	   individually.
+
+	   As an output option, disables video recording i.e. automatic selection or mapping of any video
+	   stream. For full manual control see the "-map" option.
+
+       -vcodec codec (output)
+	   Set the video codec. This is an alias for "-codec:v".
+
+       -pass[:stream_specifier] n (output,per-stream)
+	   Select the pass number (1 or 2). It is used to do two-pass video encoding. The statistics of
+	   the video are recorded in the first pass into a log file (see also the option -passlogfile),
+	   and in the second pass that log file is used to generate the video at the exact requested
+	   bitrate.  On pass 1, you may just deactivate audio and set output to null, examples for
+	   Windows and Unix:
+
+		   ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
+		   ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
+
+       -passlogfile[:stream_specifier] prefix (output,per-stream)
+	   Set two-pass log file name prefix to prefix, the default file name prefix is ``ffmpeg2pass''.
+	   The complete file name will be PREFIX-N.log, where N is a number specific to the output stream
+
+       -vf filtergraph (output)
+	   Create the filtergraph specified by filtergraph and use it to filter the stream.
+
+	   This is an alias for "-filter:v", see the -filter option.
+
+===============================================================================
+===============================================================================
+
+FFMPEG(1)						FFMPEG(1)
+
+NAME
+       ffmpeg - ffmpeg video converter
+
+SYNOPSIS
+       ffmpeg [global_options] {[input_file_options] -i input_url} ... 
+       {[output_file_options] output_url} ...
+
+DESCRIPTION
+       ffmpeg is a very fast video and audio converter that can also 
+       grab from a live audio/video source. It can also convert between 
+       arbitrary sample rates and resize video on the fly with a high 
+       quality polyphase filter.
+
+       ffmpeg reads from an arbitrary number of input "files" (which 
+       can be regular files, pipes, network streams, grabbing devices, 
+       etc.), specified by the "-i" option, and writes to an arbitrary 
+       number of output "files", which are specified by a plain output
+       url. Anything found on the command line which cannot be inter-
+       preted as an option is considered to be an output url.
+
+       Each input or output url can, in principle, contain any number of 
+       streams of different types (video/audio/subtitle/attachment/data). 
+       The allowed number and/or types of streams may be limited by the 
+       container format. Selecting which streams from which inputs will 
+       go into which output is either done automatically or with the 
+       "-map" option (see the Stream selection chapter).
+
+       To refer to input files in options, you must use their indices 
+       (0-based). E.g.  the first input file is 0, the second is 1, etc. 
+       Similarly, streams within a file are referred to by their indices. 
+       E.g. "2:3" refers to the fourth stream in the third input file. 
+       Also see the Stream specifiers chapter.
+
+       As a general rule, options are applied to the next specified file. 
+       Therefore, order is important, and you can have the same option on 
+       the command line multiple times. Each occurrence is then applied 
+       to the next input or output file.  Exceptions from this rule are 
+       the global options (e.g. verbosity level), which should be specified 
+       first.
+
+       Do not mix input and output files -- first specify all input files, 
+       then all output files. Also do not mix options which belong to 
+       different files. All options apply ONLY to the next input or output 
+       file and are reset between files.
+
+       •   To set the video bitrate of the output file to 64 kbit/s:
+
+		   ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi
+
+       •   To force the frame rate of the output file to 24 fps:
+
+		   ffmpeg -i input.avi -r 24 output.avi
+
+       •   To force the frame rate of the input file (valid for raw formats only) to 1 fps and the frame
+	   rate of the output file to 24 fps:
+
+		   ffmpeg -r 1 -i input.m2v -r 24 output.avi
+
+       The format option may be needed for raw input files.
+
+DETAILED DESCRIPTION
+       The transcoding process in ffmpeg for each output can be described by the following diagram:
+
+		_______ 	     ______________
+	       |       |	    |		   |
+	       | input |  demuxer   | encoded data |   decoder
+	       | file  | ---------> | packets	   | -----+
+	       |_______|	    |______________|	  |
+							  v
+						      _________
+						     |	       |
+						     | decoded |
+						     | frames  |
+						     |_________|
+		________	     ______________	  |
+	       |	|	    |		   |	  |
+	       | output | <-------- | encoded data | <----+
+	       | file	|   muxer   | packets	   |   encoder
+	       |________|	    |______________|
+
+       ffmpeg calls the libavformat library (containing demuxers) to read input files and get packets
+       containing encoded data from them. When there are multiple input files, ffmpeg tries to keep them
+       synchronized by tracking lowest timestamp on any active input stream.
+
+       Encoded packets are then passed to the decoder (unless streamcopy is selected for the stream, see
+       further for a description). The decoder produces uncompressed frames (raw video/PCM audio/...)
+       which can be processed further by filtering (see next section). After filtering, the frames are
+       passed to the encoder, which encodes them and outputs encoded packets. Finally those are passed to
+       the muxer, which writes the encoded packets to the output file.
+
+   Filtering
+       Before encoding, ffmpeg can process raw audio and video frames using filters from the libavfilter
+       library. Several chained filters form a filter graph. ffmpeg distinguishes between two types of
+       filtergraphs: simple and complex.
+
+       Simple filtergraphs
+
+       Simple filtergraphs are those that have exactly one input and output, both of the same type. In
+       the above diagram they can be represented by simply inserting an additional step between decoding
+       and encoding:
+
+		_________			 ______________
+	       |	 |			|	       |
+	       | decoded |			| encoded data |
+	       | frames  |\		      _ | packets      |
+	       |_________| \		      /||______________|
+			    \	__________   /
+		 simple     _\||	  | /  encoder
+		 filtergraph   | filtered |/
+			       | frames   |
+			       |__________|
+
+       Simple filtergraphs are configured with the per-stream -filter option (with -vf and -af aliases
+       for video and audio respectively).  A simple filtergraph for video can look for example like this:
+
+		_______        _____________	    _______	   ________
+	       |       |      | 	    |	   |	   |	  |	   |
+	       | input | ---> | deinterlace | ---> | scale | ---> | output |
+	       |_______|      |_____________|	   |_______|	  |________|
+
+       Note that some filters change frame properties but not frame contents. E.g. the "fps" filter in
+       the example above changes number of frames, but does not touch the frame contents. Another example
+       is the "setpts" filter, which only sets timestamps and otherwise passes the frames unchanged.
+
+       Complex filtergraphs
+
+       Complex filtergraphs are those which cannot be described as simply a linear processing chain
+       applied to one stream. This is the case, for example, when the graph has more than one input
+       and/or output, or when output stream type is different from input. They can be represented with
+       the following diagram:
+
+		_________
+	       |	 |
+	       | input 0 |\		       __________
+	       |_________| \		      | 	 |
+			    \	_________    /| output 0 |
+			     \ |	 |  / |__________|
+		_________     \| complex | /
+	       |	 |     |	 |/
+	       | input 1 |---->| filter  |\
+	       |_________|     |	 | \   __________
+			      /| graph	 |  \ | 	 |
+			     / |	 |   \| output 1 |
+		_________   /  |_________|    |__________|
+	       |	 | /
+	       | input 2 |/
+	       |_________|
+
+       Complex filtergraphs are configured with the -filter_complex option.  Note that this option is
+       global, since a complex filtergraph, by its nature, cannot be unambiguously associated with a
+       single stream or file.
+
+       The -lavfi option is equivalent to -filter_complex.
+
+       A trivial example of a complex filtergraph is the "overlay" filter, which has two video inputs and
+       one video output, containing one video overlaid on top of the other. Its audio counterpart is the
+       "amix" filter.
+
+   Stream copy
+       Stream copy is a mode selected by supplying the "copy" parameter to the -codec option. It makes
+       ffmpeg omit the decoding and encoding step for the specified stream, so it does only demuxing and
+       muxing. It is useful for changing the container format or modifying container-level metadata. The
+       diagram above will, in this case, simplify to this:
+
+		_______ 	     ______________	       ________
+	       |       |	    |		   |	      |        |
+	       | input |  demuxer   | encoded data |  muxer   | output |
+	       | file  | ---------> | packets	   | -------> | file   |
+	       |_______|	    |______________|	      |________|
+
+       Since there is no decoding or encoding, it is very fast and there is no quality loss. However, it
+       might not work in some cases because of many factors. Applying filters is obviously also
+       impossible, since filters work on uncompressed data.
+
+STREAM SELECTION
+       ffmpeg provides the "-map" option for manual control of stream selection in each output file.
+       Users can skip "-map" and let ffmpeg perform automatic stream selection as described below. The
+       "-vn / -an / -sn / -dn" options can be used to skip inclusion of video, audio, subtitle and data
+       streams respectively, whether manually mapped or automatically selected, except for those streams
+       which are outputs of complex filtergraphs.
+
+   Description
+       The sub-sections that follow describe the various rules that are involved in stream selection.
+       The examples that follow next show how these rules are applied in practice.
+
+       While every effort is made to accurately reflect the behavior of the program, FFmpeg is under
+       continuous development and the code may have changed since the time of this writing.
+
+       Automatic stream selection
+
+       In the absence of any map options for a particular output file, ffmpeg inspects the output format
+       to check which type of streams can be included in it, viz. video, audio and/or subtitles. For each
+       acceptable stream type, ffmpeg will pick one stream, when available, from among all the inputs.
+
+       It will select that stream based upon the following criteria:
+
+       •   for video, it is the stream with the highest resolution,
+
+       •   for audio, it is the stream with the most channels,
+
+       •   for subtitles, it is the first subtitle stream found but there's a caveat.  The output
+	   format's default subtitle encoder can be either text-based or image-based, and only a subtitle
+	   stream of the same type will be chosen.
+
+       In the case where several streams of the same type rate equally, the stream with the lowest index
+       is chosen.
+
+       Data or attachment streams are not automatically selected and can only be included using "-map".
+
+       Manual stream selection
+
+       When "-map" is used, only user-mapped streams are included in that output file, with one possible
+       exception for filtergraph outputs described below.
+
+       Complex filtergraphs
+
+       If there are any complex filtergraph output streams with unlabeled pads, they will be added to the
+       first output file. This will lead to a fatal error if the stream type is not supported by the
+       output format. In the absence of the map option, the inclusion of these streams leads to the
+       automatic stream selection of their types being skipped. If map options are present, these
+       filtergraph streams are included in addition to the mapped streams.
+
+       Complex filtergraph output streams with labeled pads must be mapped once and exactly once.
+
+       Stream handling
+
+       Stream handling is independent of stream selection, with an exception for subtitles described
+       below. Stream handling is set via the "-codec" option addressed to streams within a specific
+       output file. In particular, codec options are applied by ffmpeg after the stream selection process
+       and thus do not influence the latter. If no "-codec" option is specified for a stream type, ffmpeg
+       will select the default encoder registered by the output file muxer.
+
+       An exception exists for subtitles. If a subtitle encoder is specified for an output file, the
+       first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate
+       if the specified encoder can convert the selected stream or if the converted stream is acceptable
+       within the output format. This applies generally as well: when the user sets an encoder manually,
+       the stream selection process cannot check if the encoded stream can be muxed into the output file.
+       If it cannot, ffmpeg will abort and all output files will fail to be processed.
+
+   Examples
+       The following examples illustrate the behavior, quirks and limitations of ffmpeg's stream
+       selection methods.
+
+       They assume the following three input files.
+
+	       input file 'A.avi'
+		     stream 0: video 640x360
+		     stream 1: audio 2 channels
+
+	       input file 'B.mp4'
+		     stream 0: video 1920x1080
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (text)
+		     stream 3: audio 5.1 channels
+		     stream 4: subtitles (text)
+
+	       input file 'C.mkv'
+		     stream 0: video 1280x720
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (image)
+
+       Example: automatic stream selection
+
+	       ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
+
+       There are three output files specified, and for the first two, no "-map" options are set, so
+       ffmpeg will select streams for these two files automatically.
+
+       out1.mkv is a Matroska container file and accepts video, audio and subtitle streams, so ffmpeg
+       will try to select one of each type.For video, it will select "stream 0" from B.mp4, which has the
+       highest resolution among all the input video streams.For audio, it will select "stream 3" from
+       B.mp4, since it has the greatest number of channels.For subtitles, it will select "stream 2" from
+       B.mp4, which is the first subtitle stream from among A.avi and B.mp4.
+
+       out2.wav accepts only audio streams, so only "stream 3" from B.mp4 is selected.
+
+       For out3.mov, since a "-map" option is set, no automatic stream selection will occur. The "-map
+       1:a" option will select all audio streams from the second input B.mp4. No other streams will be
+       included in this output file.
+
+       For the first two outputs, all included streams will be transcoded. The encoders chosen will be
+       the default ones registered by each output format, which may not match the codec of the selected
+       input streams.
+
+       For the third output, codec option for audio streams has been set to "copy", so no decoding-
+       filtering-encoding operations will occur, or can occur.	Packets of selected streams shall be
+       conveyed from the input file and muxed within the output file.
+
+       Example: automatic subtitles selection
+
+	       ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
+
+       Although out1.mkv is a Matroska container file which accepts subtitle streams, only a video and
+       audio stream shall be selected. The subtitle stream of C.mkv is image-based and the default
+       subtitle encoder of the Matroska muxer is text-based, so a transcode operation for the subtitles
+       is expected to fail and hence the stream isn't selected. However, in out2.mkv, a subtitle encoder
+       is specified in the command and so, the subtitle stream is selected, in addition to the video
+       stream. The presence of "-an" disables audio stream selection for out2.mkv.
+
+       Example: unlabeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
+
+       A filtergraph is setup here using the "-filter_complex" option and consists of a single video
+       filter. The "overlay" filter requires exactly two video inputs, but none are specified, so the
+       first two available video streams are used, those of A.avi and C.mkv. The output pad of the filter
+       has no label and so is sent to the first output file out1.mp4. Due to this, automatic selection of
+       the video stream is skipped, which would have selected the stream in B.mp4. The audio stream with
+       most channels viz. "stream 3" in B.mp4, is chosen automatically. No subtitle stream is chosen
+       however, since the MP4 format has no default subtitle encoder registered, and the user hasn't
+       specified a subtitle encoder.
+
+       The 2nd output file, out2.srt, only accepts text-based subtitle streams. So, even though the first
+       subtitle stream available belongs to C.mkv, it is image-based and hence skipped.  The selected
+       stream, "stream 2" in B.mp4, is the first text-based subtitle stream.
+
+       Example: labeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -map '[outv]' -an        out1.mp4 \
+					       out2.mkv \
+		      -map '[outv]' -map 1:a:0 out3.mkv
+
+       The above command will fail, as the output pad labelled "[outv]" has been mapped twice.	None of
+       the output files shall be processed.
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -an	 out1.mp4 \
+				 out2.mkv \
+		      -map 1:a:0 out3.mkv
+
+       This command above will also fail as the hue filter output has a label, "[outv]", and hasn't been
+       mapped anywhere.
+
+       The command should be modified as follows,
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
+		       -map '[outv1]' -an	 out1.mp4 \
+						 out2.mkv \
+		       -map '[outv2]' -map 1:a:0 out3.mkv
+
+       The video stream from B.mp4 is sent to the hue filter, whose output is cloned once using the split
+       filter, and both outputs labelled. Then a copy each is mapped to the first and third output files.
+
+       The overlay filter, requiring two video inputs, uses the first two unused video streams. Those are
+       the streams from A.avi and C.mkv. The overlay output isn't labelled, so it is sent to the first
+       output file out1.mp4, regardless of the presence of the "-map" option.
+
+       The aresample filter is sent the first unused audio stream, that of A.avi. Since this filter
+       output is also unlabelled, it too is mapped to the first output file. The presence of "-an" only
+       suppresses automatic or manual stream selection of audio streams, not outputs sent from
+       filtergraphs. Both these mapped streams shall be ordered before the mapped stream in out1.mp4.
+
+       The video, audio and subtitle streams mapped to "out2.mkv" are entirely determined by automatic
+       stream selection.
+
+       out3.mkv consists of the cloned video output from the hue filter and the first audio stream from
+       B.mp4.
+
+OPTIONS
+       All the numerical options, if not specified otherwise, accept a string representing a number as
+       input, which may be followed by one of the SI unit prefixes, for example: 'K', 'M', or 'G'.
+
+       If 'i' is appended to the SI unit prefix, the complete prefix will be interpreted as a unit prefix
+       for binary multiples, which are based on powers of 1024 instead of powers of 1000. Appending 'B'
+       to the SI unit prefix multiplies the value by 8. This allows using, for example: 'KB', 'MiB', 'G'
+       and 'B' as number suffixes.
+
+       Options which do not take arguments are boolean options, and set the corresponding value to true.
+       They can be set to false by prefixing the option name with "no". For example using "-nofoo" will
+       set the boolean option with name "foo" to false.
+
+   Stream specifiers
+       Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers are used to
+       precisely specify which stream(s) a given option belongs to.
+
+       A stream specifier is a string generally appended to the option name and separated from it by a
+       colon. E.g. "-codec:a:1 ac3" contains the "a:1" stream specifier, which matches the second audio
+       stream. Therefore, it would select the ac3 codec for the second audio stream.
+
+       A stream specifier can match several streams, so that the option is applied to all of them. E.g.
+       the stream specifier in "-b:a 128k" matches all audio streams.
+
+       An empty stream specifier matches all streams. For example, "-codec copy" or "-codec: copy" would
+       copy all the streams without reencoding.
+
+       Possible forms of stream specifiers are:
+
+       stream_index
+	   Matches the stream with this index. E.g. "-threads:1 4" would set the thread count for the
+	   second stream to 4. If stream_index is used as an additional stream specifier (see below),
+	   then it selects stream number stream_index from the matching streams. Stream numbering is
+	   based on the order of the streams as detected by libavformat except when a program ID is also
+	   specified. In this case it is based on the ordering of the streams in the program.
+
+       stream_type[:additional_stream_specifier]
+	   stream_type is one of following: 'v' or 'V' for video, 'a' for audio, 's' for subtitle, 'd'
+	   for data, and 't' for attachments. 'v' matches all video streams, 'V' only matches video
+	   streams which are not attached pictures, video thumbnails or cover arts. If
+	   additional_stream_specifier is used, then it matches streams which both have this type and
+	   match the additional_stream_specifier. Otherwise, it matches all streams of the specified
+	   type.
+
+       p:program_id[:additional_stream_specifier]
+	   Matches streams which are in the program with the id program_id. If
+	   additional_stream_specifier is used, then it matches streams which both are part of the
+	   program and match the additional_stream_specifier.
+
+       #stream_id or i:stream_id
+	   Match the stream by stream id (e.g. PID in MPEG-TS container).
+
+       m:key[:value]
+	   Matches streams with the metadata tag key having the specified value. If value is not given,
+	   matches streams that contain the given tag with any value.
+
+       u   Matches streams with usable configuration, the codec must be defined and the essential
+	   information such as video dimension or audio sample rate must be present.
+
+	   Note that in ffmpeg, matching by metadata will only work properly for input files.
+
+   Generic options
+       These options are shared amongst the ff* tools.
+
+       -L  Show license.
+
+       -h, -?, -help, --help [arg]
+	   Show help. An optional parameter may be specified to print help about a specific item. If no
+	   argument is specified, only basic (non advanced) tool options are shown.
+
+	   Possible values of arg are:
+
+	   long
+	       Print advanced tool options in addition to the basic tool options.
+
+	   full
+	       Print complete list of options, including shared and private options for encoders,
+	       decoders, demuxers, muxers, filters, etc.
+
+	   decoder=decoder_name
+	       Print detailed information about the decoder named decoder_name. Use the -decoders option
+	       to get a list of all decoders.
+
+	   encoder=encoder_name
+	       Print detailed information about the encoder named encoder_name. Use the -encoders option
+	       to get a list of all encoders.
+
+	   demuxer=demuxer_name
+	       Print detailed information about the demuxer named demuxer_name. Use the -formats option
+	       to get a list of all demuxers and muxers.
+
+	   muxer=muxer_name
+	       Print detailed information about the muxer named muxer_name. Use the -formats option to
+	       get a list of all muxers and demuxers.
+
+	   filter=filter_name
+	       Print detailed information about the filter name filter_name. Use the -filters option to
+	       get a list of all filters.
+
+	   bsf=bitstream_filter_name
+	       Print detailed information about the bitstream filter name bitstream_filter_name.  Use the
+	       -bsfs option to get a list of all bitstream filters.
+
+       -version
+	   Show version.
+
+       -formats
+	   Show available formats (including devices).
+
+       -demuxers
+	   Show available demuxers.
+
+       -muxers
+	   Show available muxers.
+
+       -devices
+	   Show available devices.
+
+       -codecs
+	   Show all codecs known to libavcodec.
+
+	   Note that the term 'codec' is used throughout this documentation as a shortcut for what is
+	   more correctly called a media bitstream format.
+
+       -decoders
+	   Show available decoders.
+
+       -encoders
+	   Show all available encoders.
+
+       -bsfs
+	   Show available bitstream filters.
+
+       -protocols
+	   Show available protocols.
+
+       -filters
+	   Show available libavfilter filters.
+
+       -pix_fmts
+	   Show available pixel formats.
+
+       -sample_fmts
+	   Show available sample formats.
+
+       -layouts
+	   Show channel names and standard channel layouts.
+
+       -colors
+	   Show recognized color names.
+
+       -sources device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sources of the input device.  Some devices may provide system-dependent
+	   source names that cannot be autodetected.  The returned list cannot be assumed to be always
+	   complete.
+
+		   ffmpeg -sources pulse,server=192.168.0.4
+
+       -sinks device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sinks of the output device.  Some devices may provide system-dependent sink
+	   names that cannot be autodetected.  The returned list cannot be assumed to be always complete.
+
+		   ffmpeg -sinks pulse,server=192.168.0.4
+
+       -loglevel [flags+]loglevel | -v [flags+]loglevel
+	   Set logging level and flags used by the library.
+
+	   The optional flags prefix can consist of the following values:
+
+	   repeat
+	       Indicates that repeated log output should not be compressed to the first line and the
+	       "Last message repeated n times" line will be omitted.
+
+	   level
+	       Indicates that log output should add a "[level]" prefix to each message line. This can be
+	       used as an alternative to log coloring, e.g. when dumping the log to file.
+
+	   Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single flag without
+	   affecting other flags or changing loglevel. When setting both flags and loglevel, a '+'
+	   separator is expected between the last flags value and before loglevel.
+
+	   loglevel is a string or a number containing one of the following values:
+
+	   quiet, -8
+	       Show nothing at all; be silent.
+
+	   panic, 0
+	       Only show fatal errors which could lead the process to crash, such as an assertion
+	       failure. This is not currently used for anything.
+
+	   fatal, 8
+	       Only show fatal errors. These are errors after which the process absolutely cannot
+	       continue.
+
+	   error, 16
+	       Show all errors, including ones which can be recovered from.
+
+	   warning, 24
+	       Show all warnings and errors. Any message related to possibly incorrect or unexpected
+	       events will be shown.
+
+	   info, 32
+	       Show informative messages during processing. This is in addition to warnings and errors.
+	       This is the default value.
+
+	   verbose, 40
+	       Same as "info", except more verbose.
+
+	   debug, 48
+	       Show everything, including debugging information.
+
+	   trace, 56
+
+	   For example to enable repeated log output, add the "level" prefix, and set loglevel to
+	   "verbose":
+
+		   ffmpeg -loglevel repeat+level+verbose -i input output
+
+	   Another example that enables repeated log output without affecting current state of "level"
+	   prefix flag or loglevel:
+
+		   ffmpeg [...] -loglevel +repeat
+
+	   By default the program logs to stderr. If coloring is supported by the terminal, colors are
+	   used to mark errors and warnings. Log coloring can be disabled setting the environment
+	   variable AV_LOG_FORCE_NOCOLOR or NO_COLOR, or can be forced setting the environment variable
+	   AV_LOG_FORCE_COLOR.	The use of the environment variable NO_COLOR is deprecated and will be
+	   dropped in a future FFmpeg version.
+
+       -report
+	   Dump full command line and console output to a file named "program-YYYYMMDD-HHMMSS.log" in the
+	   current directory.  This file can be useful for bug reports.  It also implies "-loglevel
+	   debug".
+
+	   Setting the environment variable FFREPORT to any value has the same effect. If the value is a
+	   ':'-separated key=value sequence, these options will affect the report; option values must be
+	   escaped if they contain special characters or the options delimiter ':' (see the ``Quoting and
+	   escaping'' section in the ffmpeg-utils manual).
+
+	   The following options are recognized:
+
+	   file
+	       set the file name to use for the report; %p is expanded to the name of the program, %t is
+	       expanded to a timestamp, "%%" is expanded to a plain "%"
+
+	   level
+	       set the log verbosity level using a numerical value (see "-loglevel").
+
+	   For example, to output a report to a file named ffreport.log using a log level of 32 (alias
+	   for log level "info"):
+
+		   FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+	   Errors in parsing the environment variable are not fatal, and will not appear in the report.
+
+       -hide_banner
+	   Suppress printing banner.
+
+	   All FFmpeg tools will normally show a copyright notice, build options and library versions.
+	   This option can be used to suppress printing this information.
+
+       -cpuflags flags (global)
+	   Allows setting and clearing cpu flags. This option is intended for testing. Do not use it
+	   unless you know what you're doing.
+
+		   ffmpeg -cpuflags -sse+mmx ...
+		   ffmpeg -cpuflags mmx ...
+		   ffmpeg -cpuflags 0 ...
+
+	   Possible flags for this option are:
+
+	   x86
+	       mmx
+	       mmxext
+	       sse
+	       sse2
+	       sse2slow
+	       sse3
+	       sse3slow
+	       ssse3
+	       atom
+	       sse4.1
+	       sse4.2
+	       avx
+	       avx2
+	       xop
+	       fma3
+	       fma4
+	       3dnow
+	       3dnowext
+	       bmi1
+	       bmi2
+	       cmov
+	   ARM
+	       armv5te
+	       armv6
+	       armv6t2
+	       vfp
+	       vfpv3
+	       neon
+	       setend
+	   AArch64
+	       armv8
+	       vfp
+	       neon
+	   PowerPC
+	       altivec
+	   Specific Processors
+	       pentium2
+	       pentium3
+	       pentium4
+	       k6
+	       k62
+	       athlon
+	       athlonxp
+	       k8
+
+   AVOptions
+       These options are provided directly by the libavformat, libavdevice and libavcodec libraries. To
+       see the list of available AVOptions, use the -help option. They are separated into two categories:
+
+       generic
+	   These options can be set for any container, codec or device. Generic options are listed under
+	   AVFormatContext options for containers/devices and under AVCodecContext options for codecs.
+
+       private
+	   These options are specific to the given container, device or codec. Private options are listed
+	   under their corresponding containers/devices/codecs.
+
+       For example to write an ID3v2.3 header instead of a default ID3v2.4 to an MP3 file, use the
+       id3v2_version private option of the MP3 muxer:
+
+	       ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+       All codec AVOptions are per-stream, and thus a stream specifier should be attached to them:
+
+	       ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+       In the above example, a multichannel audio stream is mapped twice for output.  The first instance
+       is encoded with codec ac3 and bitrate 640k.  The second instance is downmixed to 2 channels and
+       encoded with codec aac. A bitrate of 128k is specified for it using absolute index of the output
+       stream.
+
+       Note: the -nooption syntax cannot be used for boolean AVOptions, use -option 0/-option 1.
+
+       Note: the old undocumented way of specifying per-stream AVOptions by prepending v/a/s to the
+       options name is now obsolete and will be removed soon.
+
+   Main options
+       -f fmt (input/output)
+	   Force input or output file format. The format is normally auto detected for input files and
+	   guessed from the file extension for output files, so this option is not needed in most cases.
+
+       -i url (input)
+	   input file url
+
+       -y (global)
+	   Overwrite output files without asking.
+
+       -n (global)
+	   Do not overwrite output files, and exit immediately if a specified output file already exists.
+
+       -stream_loop number (input)
+	   Set number of times input stream shall be looped. Loop 0 means no loop, loop -1 means infinite
+	   loop.
+
+       -c[:stream_specifier] codec (input/output,per-stream)
+       -codec[:stream_specifier] codec (input/output,per-stream)
+	   Select an encoder (when used before an output file) or a decoder (when used before an input
+	   file) for one or more streams. codec is the name of a decoder/encoder or a special value
+	   "copy" (output only) to indicate that the stream is not to be re-encoded.
+
+	   For example
+
+		   ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+
+	   encodes all video streams with libx264 and copies all audio streams.
+
+	   For each stream, the last matching "c" option is applied, so
+
+		   ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+
+	   will copy all the streams except the second video, which will be encoded with libx264, and the
+	   138th audio, which will be encoded with libvorbis.
+
+       -t duration (input/output)
+	   When used as an input option (before "-i"), limit the duration of data read from the input
+	   file.
+
+	   When used as an output option (before an output url), stop writing the output after its
+	   duration reaches duration.
+
+	   duration must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -to position (input/output)
+	   Stop writing the output or reading the input at position.  position must be a time duration
+	   specification, see the Time duration section in the ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -fs limit_size (output)
+	   Set the file size limit, expressed in bytes. No further chunk of bytes is written after the
+	   limit is exceeded. The size of the output file is slightly more than the requested file size.
+
+       -ss position (input/output)
+	   When used as an input option (before "-i"), seeks in this input file to position. Note that in
+	   most formats it is not possible to seek exactly, so ffmpeg will seek to the closest seek point
+	   before position.  When transcoding and -accurate_seek is enabled (the default), this extra
+	   segment between the seek point and position will be decoded and discarded. When doing stream
+	   copy or when -noaccurate_seek is used, it will be preserved.
+
+	   When used as an output option (before an output url), decodes but discards input until the
+	   timestamps reach position.
+
+	   position must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+       -sseof position (input)
+	   Like the "-ss" option but relative to the "end of file". That is negative values are earlier
+	   in the file, 0 is at EOF.
+
+       -itsoffset offset (input)
+	   Set the input time offset.
+
+	   offset must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   The offset is added to the timestamps of the input files. Specifying a positive offset means
+	   that the corresponding streams are delayed by the time duration specified in offset.
+
+       -itsscale scale (input,per-stream)
+	   Rescale input timestamps. scale should be a floating point number.
+
+       -timestamp date (output)
+	   Set the recording timestamp in the container.
+
+	   date must be a date specification, see the Date section in the ffmpeg-utils(1) manual.
+
+       -metadata[:metadata_specifier] key=value (output,per-metadata)
+	   Set a metadata key/value pair.
+
+	   An optional metadata_specifier may be given to set metadata on streams, chapters or programs.
+	   See "-map_metadata" documentation for details.
+
+	   This option overrides metadata set with "-map_metadata". It is also possible to delete
+	   metadata by using an empty value.
+
+	   For example, for setting the title in the output file:
+
+		   ffmpeg -i in.avi -metadata title="my title" out.flv
+
+	   To set the language of the first audio stream:
+
+		   ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
+
+       -disposition[:stream_specifier] value (output,per-stream)
+	   Sets the disposition for a stream.
+
+	   This option overrides the disposition copied from the input stream. It is also possible to
+	   delete the disposition by setting it to 0.
+
+	   The following dispositions are recognized:
+
+	   default
+	   dub
+	   original
+	   comment
+	   lyrics
+	   karaoke
+	   forced
+	   hearing_impaired
+	   visual_impaired
+	   clean_effects
+	   attached_pic
+	   captions
+	   descriptions
+	   dependent
+	   metadata
+
+	   For example, to make the second audio stream the default stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
+
+	   To make the second subtitle stream the default stream and remove the default disposition from
+	   the first subtitle stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
+
+	   To add an embedded cover/thumbnail:
+
+		   ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
+
+	   Not all muxers support embedded thumbnails, and those who do, only support a few formats, like
+	   JPEG or PNG.
+
+       -program [title=title:][program_num=program_num:]st=stream[:st=stream...] (output)
+	   Creates a program with the specified title, program_num and adds the specified stream(s) to
+	   it.
+
+       -target type (output)
+	   Specify target file type ("vcd", "svcd", "dvd", "dv", "dv50"). type may be prefixed with
+	   "pal-", "ntsc-" or "film-" to use the corresponding standard. All the format options (bitrate,
+	   codecs, buffer sizes) are then set automatically. You can just type:
+
+		   ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
+
+	   Nevertheless you can specify additional options as long as you know they do not conflict with
+	   the standard, as in:
+
+		   ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+
+       -dn (input/output)
+	   As an input option, blocks all data streams of a file from being filtered or being
+	   automatically selected or mapped for any output. See "-discard" option to disable streams
+	   individually.
+
+	   As an output option, disables data recording i.e. automatic selection or mapping of any data
+	   stream. For full manual control see the "-map" option.
+
+       -dframes number (output)
+	   Set the number of data frames to output. This is an obsolete alias for "-frames:d", which you
+	   should use instead.
+
+       -frames[:stream_specifier] framecount (output,per-stream)
+	   Stop writing to the stream after framecount frames.
+
+       -q[:stream_specifier] q (output,per-stream)
+       -qscale[:stream_specifier] q (output,per-stream)
+	   Use fixed quality scale (VBR). The meaning of q/qscale is codec-dependent.  If qscale is used
+	   without a stream_specifier then it applies only to the video stream, this is to maintain
+	   compatibility with previous behavior and as specifying the same codec specific value to 2
+	   different codecs that is audio and video generally is not what is intended when no
+	   stream_specifier is used.
+
+       -filter[:stream_specifier] filtergraph (output,per-stream)
+	   Create the filtergraph specified by filtergraph and use it to filter the stream.
+
+	   filtergraph is a description of the filtergraph to apply to the stream, and must have a single
+	   input and a single output of the same type of the stream. In the filtergraph, the input is
+	   associated to the label "in", and the output to the label "out". See the ffmpeg-filters manual
+	   for more information about the filtergraph syntax.
+
+	   See the -filter_complex option if you want to create filtergraphs with multiple inputs and/or
+	   outputs.
+
+       -filter_script[:stream_specifier] filename (output,per-stream)
+	   This option is similar to -filter, the only difference is that its argument is the name of the
+	   file from which a filtergraph description is to be read.
+
+       -filter_threads nb_threads (global)
+	   Defines how many threads are used to process a filter pipeline. Each pipeline will produce a
+	   thread pool with this many threads available for parallel processing.  The default is the
+	   number of available CPUs.
+
+       -pre[:stream_specifier] preset_name (output,per-stream)
+	   Specify the preset for matching stream(s).
+
+       -stats (global)
+	   Print encoding progress/statistics. It is on by default, to explicitly disable it you need to
+	   specify "-nostats".
+
+       -progress url (global)
+	   Send program-friendly progress information to url.
+
+	   Progress information is written approximately every second and at the end of the encoding
+	   process. It is made of "key=value" lines. key consists of only alphanumeric characters. The
+	   last key of a sequence of progress information is always "progress".
+
+       -stdin
+	   Enable interaction on standard input. On by default unless standard input is used as an input.
+	   To explicitly disable interaction you need to specify "-nostdin".
+
+	   Disabling interaction on standard input is useful, for example, if ffmpeg is in the background
+	   process group. Roughly the same result can be achieved with "ffmpeg ... < /dev/null" but it
+	   requires a shell.
+
+       -debug_ts (global)
+	   Print timestamp information. It is off by default. This option is mostly useful for testing
+	   and debugging purposes, and the output format may change from one version to another, so it
+	   should not be employed by portable scripts.
+
+	   See also the option "-fdebug ts".
+
+       -attach filename (output)
+	   Add an attachment to the output file. This is supported by a few formats like Matroska for
+	   e.g. fonts used in rendering subtitles. Attachments are implemented as a specific type of
+	   stream, so this option will add a new stream to the file. It is then possible to use per-
+	   stream options on this stream in the usual way. Attachment streams created with this option
+	   will be created after all the other streams (i.e. those created with "-map" or automatic
+	   mappings).
+
+	   Note that for Matroska you also have to set the mimetype metadata tag:
+
+		   ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
+
+	   (assuming that the attachment stream will be third in the output file).
+
+       -dump_attachment[:stream_specifier] filename (input,per-stream)
+	   Extract the matching attachment stream into a file named filename. If filename is empty, then
+	   the value of the "filename" metadata tag will be used.
+
+	   E.g. to extract the first attachment to a file named 'out.ttf':
+
+		   ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
+
+	   To extract all attachments to files determined by the "filename" tag:
+
+		   ffmpeg -dump_attachment:t "" -i INPUT
+
+	   Technical note -- attachments are implemented as codec extradata, so this option can actually
+	   be used to extract extradata from any stream, not just attachments.
+
+       -noautorotate
+	   Disable automatically rotating video based on file metadata.
+
+   Video Options
+       -vframes number (output)
+	   Set the number of video frames to output. This is an obsolete alias for "-frames:v", which you
+	   should use instead.
+
+       -r[:stream_specifier] fps (input/output,per-stream)
+	   Set frame rate (Hz value, fraction or abbreviation).
+
+	   As an input option, ignore any timestamps stored in the file and instead generate timestamps
+	   assuming constant frame rate fps.  This is not the same as the -framerate option used for some
+	   input formats like image2 or v4l2 (it used to be the same in older versions of FFmpeg).  If in
+	   doubt use -framerate instead of the input option -r.
+
+	   As an output option, duplicate or drop input frames to achieve constant output frame rate fps.
+
+       -s[:stream_specifier] size (input/output,per-stream)
+	   Set frame size.
+
+	   As an input option, this is a shortcut for the video_size private option, recognized by some
+	   demuxers for which the frame size is either not stored in the file or is configurable -- e.g.
+	   raw video or video grabbers.
+
+	   As an output option, this inserts the "scale" video filter to the end of the corresponding
+	   filtergraph. Please use the "scale" filter directly to insert it at the beginning or some
+	   other place.
+
+	   The format is wxh (default - same as source).
+
+       -aspect[:stream_specifier] aspect (output,per-stream)
+	   Set the video display aspect ratio specified by aspect.
+
+	   aspect can be a floating point number string, or a string of the form num:den, where num and
+	   den are the numerator and denominator of the aspect ratio. For example "4:3", "16:9",
+	   "1.3333", and "1.7777" are valid argument values.
+
+	   If used together with -vcodec copy, it will affect the aspect ratio stored at container level,
+	   but not the aspect ratio stored in encoded frames, if it exists.
+
+===============================================================================
+===============================================================================
\ No newline at end of file
diff --git a/examples/frontend/frontend.py b/examples/frontend/frontend.py
new file mode 100644
index 0000000..fcbf126
--- /dev/null
+++ b/examples/frontend/frontend.py
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+from transformers import AutoTokenizer
+import chat_session
+import streamlit as st
+
+# Change the following variables as needed
+
+MODEL_NAME = "mistralai/Mistral-7B-Instruct-v0.2"
+PORT = 8000
+
+
+@st.cache_resource
+def get_tokenizer():
+    global MODEL_NAME
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME)
+    return tokenizer
+
+
+tokenizer = get_tokenizer()
+
+
+@st.cache_data
+def read_context() -> str:
+    context_file = "ffmpeg.txt"
+    with open(context_file, "r") as f:
+        context_text = f.read()
+    return context_text
+
+
+context = read_context()
+
+container = st.container(border=True)
+
+with st.sidebar:
+    session = chat_session.ChatSession(PORT)
+
+    system_prompt = st.text_area(
+        "System prompt:",
+        "You are a helpful assistant. I will now give you a document and "
+        "please answer my question afterwards based on the content in document",
+    )
+
+    session.set_context([system_prompt] + [context])
+    num_tokens = tokenizer.encode(session.get_context())
+    container.header(
+        f"The context given to LLM: ({len(num_tokens)} tokens)", divider="grey"
+    )
+    container.text(session.get_context())
+
+    messages = st.container(height=400)
+    if prompt := st.chat_input("Type the question here"):
+        messages.chat_message("user").write(prompt)
+        messages.chat_message("assistant").write_stream(session.chat(prompt))
diff --git a/examples/kubernetes/health_probe.py b/examples/kubernetes/health_probe.py
new file mode 100644
index 0000000..153a389
--- /dev/null
+++ b/examples/kubernetes/health_probe.py
@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+
+# This script implements a health check probe for the LMCache server.
+# It performs the following functions:
+# 1. Sends a health check request to the LMCache server
+# 2. Verifies the server's response indicates successful operation
+# 3. Serves as a Kubernetes liveness probe to monitor server health
+# 4. Helps ensure the server is running and responsive
+
+# Standard
+import socket
+import sys
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.protocol import (
+    CacheEngineKey,
+    ClientCommand,
+    ClientMetaMessage,
+    MemoryFormat,
+    ServerMetaMessage,
+    ServerReturnCode,
+)
+
+
+def main():
+    if len(sys.argv) != 3:
+        print("Usage: health_probe.py <host> <port>", file=sys.stderr)
+        sys.exit(1)
+
+    host = sys.argv[1]
+    port = int(sys.argv[2])
+    try:
+        # Create connection with timeout and ensure proper cleanup with context manager
+        with socket.create_connection((host, port), timeout=5) as s:
+            # Create and send health check message
+            msg = ClientMetaMessage(
+                ClientCommand.HEALTH,
+                key=CacheEngineKey(
+                    model_name="",
+                    world_size=0,
+                    worker_id=0,
+                    chunk_hash=0,
+                    dtype=torch.float16,
+                ),
+                length=0,
+                fmt=MemoryFormat(1),
+                dtype=torch.float16,
+                shape=torch.Size((0, 0, 0, 0)),
+            )
+            s.sendall(msg.serialize())
+
+            # Receive and parse response
+            resp = s.recv(ServerMetaMessage.packlength())
+            if not resp:
+                print("No response received from server", file=sys.stderr)
+                sys.exit(1)
+
+            # Parse the response message
+            meta = ServerMetaMessage.deserialize(resp)
+
+            # Check if server responded with success
+            if meta.code == ServerReturnCode.SUCCESS:
+                sys.exit(0)
+            else:
+                print(f"Server returned error code: {meta.code}", file=sys.stderr)
+                sys.exit(1)
+
+    except socket.timeout:
+        print("Connection timed out", file=sys.stderr)
+        sys.exit(1)
+    except ConnectionRefusedError:
+        print("Connection refused - server may not be running", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error during health check: {str(e)}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/kv_cache_calculator/README.md b/examples/kv_cache_calculator/README.md
new file mode 100644
index 0000000..f9c6ecf
--- /dev/null
+++ b/examples/kv_cache_calculator/README.md
@@ -0,0 +1,109 @@
+# KV Cache Size Calculator
+
+## Introduction
+
+The KV Cache Size Calculator provides a web interface for calculating the size of the key-value cache required by large language models (LLMs). Users can select a model, specify the data type, and enter the number of tokens to calculate the KV cache size in gigabytes. The web interface includes a form where users can input these parameters and view the results immediately, making it simple and efficient to estimate cache requirements.
+
+This document also provides an overview of the JSON format for model configurations and explains how to use the `generate_config.py` script to generate model configurations using the `transformers` library's `AutoConfig` feature.
+
+## JSON Configuration Format
+
+The JSON configuration file produced by `generate_config.py` or manually maintained should adhere to the following format:
+
+```json
+{
+    "hidden_size": 4096,
+    "num_attention_heads": 32,
+    "num_hidden_layers": 32,
+    "num_key_value_heads": 8
+}
+```
+
+### Fields Description
+- **hidden_size**: The size of the hidden layers within the model.
+- **num_attention_heads**: The number of attention heads used in each transformer block.
+- **num_hidden_layers**: The total number of hidden layers in the model.
+- **num_key_value_heads**: (Optional) The number of key-value heads used in certain transformer architectures.
+
+> Note: If an attribute is not applicable to a particular model, it may be set to `null` or omitted altogether.
+
+## How to Use `generate_config.py`
+
+The `generate_config.py` script is used to generate a configuration JSON for a specific model using the Hugging Face `transformers` library. It fetches the model configuration and outputs it in a JSON format to the console.
+
+### Requirements
+
+- **Python 3.6+**
+- **transformers library** from Hugging Face
+- Install dependencies using:
+  ```sh
+  pip install transformers
+  ```
+
+### Usage
+
+To use the script, run the following command in your terminal:
+
+```sh
+python generate_config.py --model <model-name>
+```
+
+Replace `<model-name>` with the name or path of the model whose configuration you wish to generate. The `<model-name>` can be any model available on the Hugging Face Hub or a local path containing the model files.
+
+#### Example
+
+```sh
+python generate_config.py --model meta-llama/Llama-3.1-8B-Instruct
+```
+
+### Output
+
+The script will output the model configuration in JSON format. For example:
+
+```json
+{
+    "hidden_size": 8192,
+    "num_attention_heads": 64,
+    "num_hidden_layers": 80,
+    "num_key_value_heads": 8
+}
+```
+
+### Handling Errors
+
+In case the model name is incorrect or the configuration cannot be fetched, the script will print an error message in JSON format:
+
+```json
+{
+    "error": "Can't load config for '<model-name>'. Make sure that '<model-name>' is the correct path to a directory containing a config.json file"
+}
+```
+
+### Modifying the Script
+
+You can easily modify the script to save the JSON output to a file instead of printing it to the console. To do so, redirect the output using:
+
+```sh
+python generate_config.py --model <model-name> > model_config.json
+```
+
+This will save the configuration to a file named `model_config.json` in the current directory.
+
+## Notes
+- The script relies on the internet to fetch model configurations unless the model is available locally.
+- If certain fields are not available in a model's configuration, they will be set to `null` or excluded from the JSON.
+
+Feel free to modify `generate_config.py` as needed to add more fields or adjust the output format to better suit your requirements.
+
+## How to Contribute
+
+We welcome contributions to improve the KV Cache Size Calculator and related scripts.
+
+### Contribution Guidelines
+- Fork the repository and create a new branch for your feature or bug fix.
+- Make your changes, ensuring the code is well-documented and adheres to the existing style.
+- Submit a pull request describing your changes and the motivation behind them.
+
+If you have any suggestions or find any issues, feel free to open an issue on GitHub. Your contributions are greatly appreciated!
+
+
diff --git a/examples/kv_cache_calculator/generate_config.py b/examples/kv_cache_calculator/generate_config.py
new file mode 100644
index 0000000..dac6652
--- /dev/null
+++ b/examples/kv_cache_calculator/generate_config.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import json
+
+# Third Party
+from transformers import AutoConfig
+
+
+def main():
+    # Set up argument parser
+    parser = argparse.ArgumentParser(
+        description="Fetch model configuration using AutoConfig."
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        required=True,
+        help="The name of the model to fetch configuration for.",
+    )
+
+    # Parse arguments
+    args = parser.parse_args()
+
+    # Load model configuration using AutoConfig
+    try:
+        config = AutoConfig.from_pretrained(args.model)
+
+        # Prepare configuration data in a dictionary format
+        config_data = {
+            "hidden_size": getattr(config, "hidden_size", None),
+            "num_attention_heads": getattr(config, "num_attention_heads", None),
+            "num_hidden_layers": getattr(config, "num_hidden_layers", None),
+            "num_key_value_heads": getattr(config, "num_key_value_heads", None),
+        }
+
+        # DeepSeek MLA models (V3, V3.1, V3.2, … and R1) store
+        # KV in latent space
+        if (
+            args.model.lower().startswith("deepseek-ai/deepseek-v3")
+            or args.model == "deepseek-ai/DeepSeek-R1"
+        ):
+            config_data["kv_lora_rank"] = getattr(config, "kv_lora_rank", None)
+            config_data["qk_rope_head_dim"] = getattr(config, "qk_rope_head_dim", None)
+
+        # Models whose head_dim is explicit in config and may
+        # differ from hidden_size / num_heads:
+        # Qwen3, GLM4, and Hunyuan dense variants.
+        if (
+            "qwen/qwen3-" in args.model.lower()
+            or "zai-org/glm-4." in args.model.lower()
+            or (
+                args.model.lower().startswith("tencent/hunyuan-")
+                and args.model.lower() != "tencent/hunyuan-large"
+            )
+        ):
+            config_data["head_dim"] = getattr(config, "head_dim", None)
+
+        # Hunyuan-Large uses CLA (Cross-Layer Attention):
+        # KV layers = num_hidden_layers / cla_share_factor
+        if args.model.lower() == "tencent/hunyuan-large":
+            config_data["cla_share_factor"] = getattr(config, "cla_share_factor", None)
+
+        # Convert to JSON and print
+        string = json.dumps(config_data, indent=4)
+
+        print("\033[32m" + "Model configuration for " + args.model + ":\n" + "\033[0m")
+
+        print(f'"{args.model}": {string}\n')
+
+        print(
+            "\033[32mPlease copy the above JSON to the 'modelconfig.json'"
+            "and create a new PR\033[0m"
+        )
+
+    except Exception as e:
+        # Print error message in JSON format
+        error_data = {"error": str(e)}
+        print(json.dumps(error_data, indent=4))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/kv_cache_calculator/kv_cache_calculator.html b/examples/kv_cache_calculator/kv_cache_calculator.html
new file mode 100644
index 0000000..92ed0c7
--- /dev/null
+++ b/examples/kv_cache_calculator/kv_cache_calculator.html
@@ -0,0 +1,526 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>KV Cache Size Calculator</title>
+    <style>
+        *, *::before, *::after { box-sizing: border-box; }
+
+        body {
+            margin: 0;
+            min-height: 100vh;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: flex-start;
+            background-color: #f9f9f9;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif;
+            padding: 24px 12px 48px;
+        }
+
+        .lang-bar {
+            width: 100%;
+            max-width: 480px;
+            display: flex;
+            justify-content: flex-end;
+            margin-bottom: 8px;
+            gap: 6px;
+        }
+
+        .lang-btn {
+            padding: 4px 12px;
+            font-size: 13px;
+            border: 1px solid #b0c4de;
+            border-radius: 20px;
+            background: #fff;
+            color: #3898ec;
+            cursor: pointer;
+            transition: background 0.15s, color 0.15s;
+        }
+        .lang-btn.active, .lang-btn:hover {
+            background: #3898ec;
+            color: #fff;
+            border-color: #3898ec;
+        }
+
+        .card {
+            width: 100%;
+            max-width: 480px;
+            background: #fff;
+            border-radius: 14px;
+            box-shadow: 0 4px 24px rgba(56, 152, 236, 0.10), 0 1px 4px rgba(0,0,0,0.06);
+            padding: 32px 28px 24px;
+        }
+
+        .card h1 {
+            margin: 0 0 24px;
+            font-size: 22px;
+            font-weight: 700;
+            color: #1a2e4a;
+            letter-spacing: -0.3px;
+        }
+
+        .field {
+            margin-bottom: 18px;
+        }
+
+        .field label {
+            display: block;
+            font-size: 13px;
+            font-weight: 600;
+            color: #4a5568;
+            margin-bottom: 6px;
+            letter-spacing: 0.1px;
+        }
+
+        .field select, .field input {
+            width: 100%;
+            padding: 9px 12px;
+            font-size: 15px;
+            border: 1.5px solid #d0d9e8;
+            border-radius: 8px;
+            background: #f7faff;
+            color: #1a2e4a;
+            outline: none;
+            transition: border-color 0.15s, box-shadow 0.15s;
+            appearance: none;
+            -webkit-appearance: none;
+        }
+        .select-wrap {
+            position: relative;
+        }
+        .select-wrap::after {
+            content: "▾";
+            position: absolute;
+            right: 12px;
+            top: 50%;
+            transform: translateY(-50%);
+            pointer-events: none;
+            color: #8aa4c8;
+            font-size: 14px;
+        }
+        .field select:focus, .field input:focus {
+            border-color: #3898ec;
+            box-shadow: 0 0 0 3px rgba(56,152,236,0.12);
+            background: #fff;
+        }
+
+        .calc-btn {
+            display: block;
+            width: 100%;
+            padding: 11px;
+            font-size: 15px;
+            font-weight: 600;
+            background: #3898ec;
+            color: #fff;
+            border: none;
+            border-radius: 8px;
+            cursor: pointer;
+            transition: background 0.15s, transform 0.1s;
+            margin-top: 4px;
+        }
+        .calc-btn:hover { background: #1a7fd4; }
+        .calc-btn:active { transform: scale(0.98); }
+
+        #result {
+            margin-top: 20px;
+            padding: 14px 16px;
+            background: linear-gradient(90deg, #e8f4fd, #f0f8ff);
+            border-left: 4px solid #3898ec;
+            border-radius: 6px;
+            font-size: 20px;
+            font-weight: 700;
+            color: #1a5fa8;
+            display: none;
+        }
+
+        #calculation-steps {
+            margin-top: 14px;
+            padding: 14px 16px;
+            background: #f7faff;
+            border: 1px solid #d8e8f8;
+            border-radius: 8px;
+            font-size: 12.5px;
+            line-height: 1.8;
+            color: #4a5568;
+            display: none;
+        }
+
+        .github-btn {
+            display: block;
+            width: 100%;
+            padding: 9px;
+            margin-top: 18px;
+            font-size: 13px;
+            font-weight: 500;
+            background: #f0f4fa;
+            color: #4a5568;
+            border: 1.5px solid #d0d9e8;
+            border-radius: 8px;
+            cursor: pointer;
+            text-align: center;
+            transition: background 0.15s;
+        }
+        .github-btn:hover { background: #e2eaf6; }
+
+        footer {
+            margin-top: 24px;
+            font-size: 12px;
+            color: #8aa4c8;
+        }
+    </style>
+</head>
+<body>
+    <div class="lang-bar">
+        <button class="lang-btn active" onclick="setLang('en')" id="btn-en">English</button>
+        <button class="lang-btn" onclick="setLang('zh')" id="btn-zh">中文</button>
+    </div>
+    <div class="card">
+        <h1 id="title">KV Cache Size Calculator</h1>
+
+        <div class="field">
+            <label id="lbl-model" for="model">Select LLM Model</label>
+            <div class="select-wrap">
+                <select id="model"></select>
+            </div>
+        </div>
+
+        <div class="field">
+            <label id="lbl-dtype" for="dtype">Data Type</label>
+            <div class="select-wrap">
+                <select id="dtype">
+                    <option value="float16">float16</option>
+                    <option value="bfloat16">bfloat16</option>
+                    <option value="float32">float32</option>
+                    <option value="int8">int8</option>
+                </select>
+            </div>
+        </div>
+
+        <div class="field">
+            <label id="lbl-tokens" for="tokens">Number of Tokens</label>
+            <input type="number" id="tokens" placeholder="e.g. 4096">
+        </div>
+
+        <button class="calc-btn" onclick="calculateKVCache()" id="btn-calc">Calculate</button>
+
+        <div id="result"></div>
+        <div id="calculation-steps"></div>
+
+        <button class="github-btn" onclick="openGitHubRepo()" id="btn-github">
+            ➕ Contribute new models on GitHub
+        </button>
+    </div>
+    <footer id="footer">Developed by Zhuohan Gu @ LMCache team</footer>
+
+    <script>
+        let modelConfigs = {};
+        let currentLang = 'en';
+
+        const i18n = {
+            en: {
+                title: 'KV Cache Size Calculator',
+                lblModel: 'Select LLM Model',
+                lblDtype: 'Data Type',
+                lblTokens: 'Number of Tokens',
+                tokenPlaceholder: 'e.g. 4096',
+                btnCalc: 'Calculate',
+                btnGithub: '➕ Contribute new models on GitHub',
+                footer: 'Developed by Zhuohan Gu @ LMCache team',
+                errTokens: 'Please enter a valid number of tokens.',
+                errModel: 'Model not recognized.',
+                errDtype: 'Invalid data type selected.',
+                errLoad: 'Failed to load model configurations. Please try again later.',
+                detailsTitle: 'Calculation Details',
+                fldModel: 'Selected Model',
+                fldLayers: 'Number of Hidden Layers',
+                fldKvLoraRank: 'KV-LoRA Rank (latent dim)',
+                fldQkRopeHeadDim: 'QK-Rope Head Dim',
+                fldDtypeSize: 'Data Type Size',
+                fldTotalElem: 'Total Elements',
+                fldTotalBytes: 'Total Bytes',
+                fldKvSize: 'KV Cache Size',
+                fldKvHeads: 'Number of Key-Value Heads',
+                fldHeadDim: 'Head Dim',
+                fldClaFactor: 'CLA Share Factor',
+                fldEffLayers: 'Effective KV Layers',
+                fldHeadSize: 'Head Size',
+                fldHiddenSize: 'Hidden Size',
+                fldAttnHeads: 'Number of Attention Heads',
+                claNote: (f) => `every ${f} layers share one KV cache`,
+                headSizeNote: 'Hidden Size / Attention Heads',
+                bytes: 'bytes',
+                result: (gb) => `KV Cache Size: ${gb} GB`,
+            },
+            zh: {
+                title: 'KV Cache 大小计算器',
+                lblModel: '选择 LLM 模型',
+                lblDtype: '数据类型',
+                lblTokens: 'Token 数量',
+                tokenPlaceholder: '例如：4096',
+                btnCalc: '开始计算',
+                btnGithub: '➕ 在 GitHub 上贡献新模型',
+                footer: '由 LMCache 团队 Zhuohan Gu 开发',
+                errTokens: '请输入有效的 Token 数量。',
+                errModel: '未识别的模型。',
+                errDtype: '无效的数据类型。',
+                errLoad: '模型配置加载失败，请稍后重试。',
+                detailsTitle: '计算详情',
+                fldModel: '所选模型',
+                fldLayers: '隐藏层数',
+                fldKvLoraRank: 'KV-LoRA 秩（隐空间维度）',
+                fldQkRopeHeadDim: 'QK-RoPE Head Dim',
+                fldDtypeSize: '数据类型大小',
+                fldTotalElem: '总元素数',
+                fldTotalBytes: '总字节数',
+                fldKvSize: 'KV Cache 大小',
+                fldKvHeads: 'KV 头数',
+                fldHeadDim: 'Head Dim',
+                fldClaFactor: 'CLA 共享因子',
+                fldEffLayers: '有效 KV 层数',
+                fldHeadSize: 'Head Size',
+                fldHiddenSize: '隐藏层维度',
+                fldAttnHeads: '注意力头数',
+                claNote: (f) => `每 ${f} 层共享一份 KV Cache`,
+                headSizeNote: '隐藏层维度 / 注意力头数',
+                bytes: '字节',
+                result: (gb) => `KV Cache 大小：${gb} GB`,
+            }
+        };
+
+        function t(key, ...args) {
+            const v = i18n[currentLang][key];
+            return typeof v === 'function' ? v(...args) : v;
+        }
+
+        function setLang(lang) {
+            currentLang = lang;
+            document.getElementById('btn-en').classList.toggle('active', lang === 'en');
+            document.getElementById('btn-zh').classList.toggle('active', lang === 'zh');
+            document.getElementById('title').textContent = t('title');
+            document.getElementById('lbl-model').textContent = t('lblModel');
+            document.getElementById('lbl-dtype').textContent = t('lblDtype');
+            document.getElementById('lbl-tokens').textContent = t('lblTokens');
+            document.getElementById('tokens').placeholder = t('tokenPlaceholder');
+            document.getElementById('btn-calc').textContent = t('btnCalc');
+            document.getElementById('btn-github').textContent = t('btnGithub');
+            document.getElementById('footer').textContent = t('footer');
+            // Re-render result if visible
+            if (document.getElementById('result').style.display !== 'none') {
+                calculateKVCache();
+            }
+        }
+
+        function openGitHubRepo() {
+            const githubUrl = 'https://github.com/LMCache/LMCache/issues/244#:~:text=https%3A//github.com/LMCache/LMCache/tree/dev/examples/kv_cache_calculator';
+            window.open(githubUrl, '_blank');
+        }
+
+        // Load model configurations: prefer local file, fallback to GitHub
+        async function loadModelConfigs() {
+            const localUrl = './modelconfig.json';
+            const remoteUrl = 'https://raw.githubusercontent.com/LMCache/LMCache/refs/heads/dev/examples/kv_cache_calculator/modelconfig.json';
+            // Try local first
+            try {
+                let response = await fetch(localUrl);
+                if (response.ok) {
+                    modelConfigs = await response.json();
+                    populateModelDropdown();
+                    return;
+                }
+            } catch (e) {
+                // ignore local fetch errors and fallback
+                console.debug('Local modelconfig.json not available locally, falling back to remote.');
+            }
+
+            // Fallback to remote
+            try {
+                const response = await fetch(remoteUrl);
+                if (!response.ok) throw new Error(`HTTP error! Status: ${response.status}`);
+                modelConfigs = await response.json();
+                populateModelDropdown();
+            } catch (error) {
+                console.error('Failed to load model configurations:', error);
+                showResult(t('errLoad'), true);
+            }
+        }
+
+        // Populate the model dropdown dynamically
+        function populateModelDropdown() {
+            const modelSelect = document.getElementById('model');
+            modelSelect.innerHTML = "";
+            const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+            const sortedModelNames = Object.keys(modelConfigs).sort(collator.compare);
+            for (const modelName of sortedModelNames) {
+                const option = document.createElement('option');
+                option.value = modelName;
+                option.textContent = modelName;
+                modelSelect.appendChild(option);
+            }
+        }
+
+        function showResult(html, isError = false) {
+            const el = document.getElementById('result');
+            el.innerHTML = html;
+            el.style.display = 'block';
+            el.style.borderLeftColor = isError ? '#e05252' : '#3898ec';
+            el.style.color = isError ? '#a02020' : '#1a5fa8';
+        }
+
+        async function calculateKVCache() {
+            if (Object.keys(modelConfigs).length === 0) await loadModelConfigs();
+
+            const model = document.getElementById('model').value;
+            const tokens = parseInt(document.getElementById('tokens').value);
+            const dtype = document.getElementById('dtype').value;
+
+            if (isNaN(tokens) || tokens <= 0) {
+                showResult(t('errTokens'), true);
+                document.getElementById('calculation-steps').style.display = 'none';
+                return;
+            }
+
+            const config = modelConfigs[model];
+            if (!config) {
+                showResult(t('errModel'), true);
+                document.getElementById('calculation-steps').style.display = 'none';
+                return;
+            }
+
+            let hidden_size, num_attention_heads, num_hidden_layers, num_key_value_heads;
+            let kv_lora_rank, qk_rope_head_dim;
+            let head_dim, head_size;
+
+            // Check for DeepSeek MLA models (prefix match covers V3, V3.1, V3.2, … ; plus R1)
+            const isDeepSeekModel = model.startsWith("deepseek-ai/DeepSeek-V3") || model === "deepseek-ai/DeepSeek-R1";
+
+            // Check for Qwen3 models (fuzzy matching)
+            const isQwen3Model = model.toLowerCase().includes("qwen/qwen3-");
+
+            // Check for GLM4 models (prefix matching)
+            const isGLM4Model = model.startsWith("zai-org/GLM-4.");
+
+            // Check for Hunyuan dense models (explicit head_dim, may differ from hidden/heads)
+            const isHunyuanDenseModel = model.toLowerCase().startsWith("tencent/hunyuan-") && model.toLowerCase() !== "tencent/hunyuan-large";
+
+            // Check for Hunyuan-Large (CLA: cross-layer attention sharing)
+            const isHunyuanLargeModel = model.toLowerCase() === "tencent/hunyuan-large";
+
+            const isGQAWithHeadDimModel = isQwen3Model || isGLM4Model || isHunyuanDenseModel;
+
+            if (isDeepSeekModel) {
+                ({ hidden_size, num_attention_heads, num_hidden_layers, num_key_value_heads, kv_lora_rank, qk_rope_head_dim } = config);
+            } else if (isHunyuanLargeModel) {
+                // Hunyuan-Large uses CLA (Cross-Layer Attention): every cla_share_factor layers share one KV cache.
+                ({ hidden_size, num_attention_heads, num_hidden_layers, num_key_value_heads } = config);
+                head_size = hidden_size / num_attention_heads;
+            } else if (isGQAWithHeadDimModel) {
+                // Qwen3, GLM4, and Hunyuan dense models all have an explicit head_dim in their configs.
+                ({ hidden_size, num_attention_heads, num_hidden_layers, num_key_value_heads, head_dim } = config);
+            } else {
+                ({ hidden_size, num_attention_heads, num_hidden_layers, num_key_value_heads } = config);
+                head_size = hidden_size / num_attention_heads;
+            }
+
+            // Determine dtype size in bytes
+            let dtype_size;
+            if (dtype === 'float32') dtype_size = 4;
+            else if (dtype === 'float16' || dtype === 'bfloat16') dtype_size = 2;
+            else if (dtype === 'int8') dtype_size = 1;
+            else {
+                showResult(t('errDtype'), true);
+                document.getElementById('calculation-steps').style.display = 'none';
+                return;
+            }
+
+            // Calculate KV cache size
+            let total_elements;
+            let effective_layers;
+            if (isDeepSeekModel) {
+                total_elements = num_hidden_layers * tokens * (kv_lora_rank + qk_rope_head_dim);
+            } else if (isHunyuanLargeModel) {
+                const cla_share_factor = config.cla_share_factor;
+                effective_layers = num_hidden_layers / cla_share_factor;
+                total_elements = 2 * effective_layers * tokens * num_key_value_heads * head_size;
+            } else if (isGQAWithHeadDimModel) {
+                total_elements = 2 * num_hidden_layers * tokens * num_key_value_heads * head_dim;
+            } else {
+                total_elements = 2 * num_hidden_layers * tokens * num_key_value_heads * head_size;
+            }
+            const total_bytes = total_elements * dtype_size;
+            const kvCacheSizeGB = total_bytes / (1024 ** 3);
+
+            showResult(t('result', kvCacheSizeGB.toFixed(4)));
+
+            // Prepare calculation steps
+            const B = (s) => `<b>${s}</b>`;
+            let rows;
+            if (isDeepSeekModel) {
+                rows = [
+                    [B(t('fldModel')), model],
+                    [B(t('fldLayers')), num_hidden_layers],
+                    [B(t('fldKvLoraRank')), kv_lora_rank],
+                    [B(t('fldQkRopeHeadDim')), qk_rope_head_dim],
+                    [B(t('fldDtypeSize')), `${dtype_size} ${t('bytes')}`],
+                    [B(t('fldTotalElem')), `${num_hidden_layers} × ${tokens} × (${kv_lora_rank} + ${qk_rope_head_dim}) = ${total_elements}`],
+                    [B(t('fldTotalBytes')), `${total_elements} × ${dtype_size} = ${total_bytes} ${t('bytes')}`],
+                    [B(t('fldKvSize')), `${total_bytes} / 1024³ ≈ ${kvCacheSizeGB.toFixed(4)} GB`],
+                ];
+            } else if (isHunyuanLargeModel) {
+                const cla_share_factor = config.cla_share_factor;
+                rows = [
+                    [B(t('fldModel')), model],
+                    [B(t('fldLayers')), num_hidden_layers],
+                    [B(t('fldClaFactor')), `${cla_share_factor} (${t('claNote', cla_share_factor)})`],
+                    [B(t('fldEffLayers')), `${num_hidden_layers} / ${cla_share_factor} = ${effective_layers}`],
+                    [B(t('fldKvHeads')), num_key_value_heads],
+                    [B(t('fldHeadSize')), `${head_size} (${t('headSizeNote')})`],
+                    [B(t('fldDtypeSize')), `${dtype_size} ${t('bytes')}`],
+                    [B(t('fldTotalElem')), `2 × ${effective_layers} × ${tokens} × ${num_key_value_heads} × ${head_size} = ${total_elements}`],
+                    [B(t('fldTotalBytes')), `${total_elements} × ${dtype_size} = ${total_bytes} ${t('bytes')}`],
+                    [B(t('fldKvSize')), `${total_bytes} / 1024³ ≈ ${kvCacheSizeGB.toFixed(4)} GB`],
+                ];
+            } else if (isGQAWithHeadDimModel) {
+                rows = [
+                    [B(t('fldModel')), model],
+                    [B(t('fldLayers')), num_hidden_layers],
+                    [B(t('fldKvHeads')), num_key_value_heads],
+                    [B(t('fldHeadDim')), head_dim],
+                    [B(t('fldDtypeSize')), `${dtype_size} ${t('bytes')}`],
+                    [B(t('fldTotalElem')), `2 × ${num_hidden_layers} × ${tokens} × ${num_key_value_heads} × ${head_dim} = ${total_elements}`],
+                    [B(t('fldTotalBytes')), `${total_elements} × ${dtype_size} = ${total_bytes} ${t('bytes')}`],
+                    [B(t('fldKvSize')), `${total_bytes} / 1024³ ≈ ${kvCacheSizeGB.toFixed(4)} GB`],
+                ];
+            } else {
+                rows = [
+                    [B(t('fldModel')), model],
+                    [B(t('fldHiddenSize')), hidden_size],
+                    [B(t('fldAttnHeads')), num_attention_heads],
+                    [B(t('fldLayers')), num_hidden_layers],
+                    [B(t('fldKvHeads')), num_key_value_heads],
+                    [B(t('fldHeadSize')), `${head_size} (${t('headSizeNote')})`],
+                    [B(t('fldDtypeSize')), `${dtype_size} ${t('bytes')}`],
+                    [B(t('fldTotalElem')), `2 × ${num_hidden_layers} × ${tokens} × ${num_key_value_heads} × ${head_size} = ${total_elements}`],
+                    [B(t('fldTotalBytes')), `${total_elements} × ${dtype_size} = ${total_bytes} ${t('bytes')}`],
+                    [B(t('fldKvSize')), `${total_bytes} / 1024³ ≈ ${kvCacheSizeGB.toFixed(4)} GB`],
+                ];
+            }
+
+            const stepsEl = document.getElementById('calculation-steps');
+            stepsEl.innerHTML = `<b>${t('detailsTitle')}</b><br><br>` +
+                rows.map(([k, v]) => `${k}: ${v}`).join('<br>');
+            stepsEl.style.display = 'block';
+        }
+
+        document.getElementById('tokens').addEventListener('keydown', function(event) {
+            if (event.key === 'Enter') calculateKVCache();
+        });
+
+        window.onload = function() {
+            loadModelConfigs();
+        };
+
+    </script>
+</body>
+</html>
diff --git a/examples/kv_cache_calculator/modelconfig.json b/examples/kv_cache_calculator/modelconfig.json
new file mode 100644
index 0000000..6892175
--- /dev/null
+++ b/examples/kv_cache_calculator/modelconfig.json
@@ -0,0 +1,201 @@
+{
+    "meta-llama/Llama-3.1-8B-Instruct": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8
+    },
+    "meta-llama/Llama-3.1-70B-Instruct": {
+        "hidden_size": 8192,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 80,
+        "num_key_value_heads": 8
+    },
+    "mistralai/Mistral-7B-Instruct-v0.2": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8
+    },
+    "mistralai/Mistral-Large-Instruct-2407": {
+        "hidden_size": 12288,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 88,
+        "num_key_value_heads": 8
+    },
+    "lmsys/longchat-7b-16k": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 32
+    },
+    "Sao10K/L3-8B-Lunaris-v1": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8
+    },
+    "meta-llama/Llama-3.2-3B-Instruct": {
+        "hidden_size": 3072,
+        "num_attention_heads": 24,
+        "num_hidden_layers": 28,
+        "num_key_value_heads": 8
+    },
+    "deepseek-ai/DeepSeek-V3": {
+        "hidden_size": 7168,
+        "num_attention_heads": 128,
+        "num_hidden_layers": 61,
+        "num_key_value_heads": 128,
+        "kv_lora_rank": 512,
+        "qk_rope_head_dim": 64
+    },
+    "deepseek-ai/DeepSeek-R1": {
+        "hidden_size": 7168,
+        "num_attention_heads": 128,
+        "num_hidden_layers": 61,
+        "num_key_value_heads": 128,
+        "kv_lora_rank": 512,
+        "qk_rope_head_dim": 64
+    },
+    "meta-llama/Llama-3.1-405B": {
+        "hidden_size": 16384,
+        "num_attention_heads": 128,
+        "num_hidden_layers": 126,
+        "num_key_value_heads": 8
+    },
+    "meta-llama/Llama-3.2-1B-Instruct": {
+        "hidden_size": 2048,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 16,
+        "num_key_value_heads": 8
+    },
+    "Qwen/Qwen3-32B": {
+        "hidden_size": 5120,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 64,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-14B": {
+        "hidden_size": 5120,
+        "num_attention_heads": 40,
+        "num_hidden_layers": 40,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-8B": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-4B": {
+        "hidden_size": 2560,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-0.6B": {
+        "hidden_size": 1024,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 28,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen2.5-7B-Instruct": {
+        "hidden_size": 3584,
+        "num_attention_heads": 28,
+        "num_hidden_layers": 28,
+        "num_key_value_heads": 4
+    },
+    "Qwen/Qwen2.5-3B-Instruct": {
+        "hidden_size": 2048,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 2
+    },
+    "Qwen/Qwen2.5-0.5B": {
+        "hidden_size": 896,
+        "num_attention_heads": 14,
+        "num_hidden_layers": 24,
+        "num_key_value_heads": 2
+    },
+    "Qwen/Qwen-7B": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 32
+    },
+    "zai-org/GLM-4.5": {
+        "hidden_size": 5120,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 92,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "zai-org/GLM-4.6": {
+        "hidden_size": 5120,
+        "num_attention_heads": 96,
+        "num_hidden_layers": 92,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-30B-A3B-Instruct-2507": {
+        "hidden_size": 2048,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 48,
+        "num_key_value_heads": 4,
+        "head_dim": 128
+    },
+    "Qwen/Qwen3-235B-A22B-Thinking-2507": {
+        "hidden_size": 4096,
+        "num_attention_heads": 64,
+        "num_hidden_layers": 94,
+        "num_key_value_heads": 4,
+        "head_dim": 128
+    },
+    "tencent/Hunyuan-0.5B-Instruct": {
+        "hidden_size": 1024,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 24,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "tencent/Hunyuan-1.8B-Instruct": {
+        "hidden_size": 2048,
+        "num_attention_heads": 16,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 4,
+        "head_dim": 128
+    },
+    "tencent/Hunyuan-4B-Instruct": {
+        "hidden_size": 3072,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 36,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "tencent/Hunyuan-7B-Instruct": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "tencent/Hunyuan-A13B-Instruct": {
+        "hidden_size": 4096,
+        "num_attention_heads": 32,
+        "num_hidden_layers": 32,
+        "num_key_value_heads": 8,
+        "head_dim": 128
+    },
+    "tencent/Hunyuan-Large": {
+        "hidden_size": 6400,
+        "num_attention_heads": 80,
+        "num_hidden_layers": 64,
+        "num_key_value_heads": 8,
+        "cla_share_factor": 2
+    }
+}
diff --git a/examples/kv_cache_calculator/requirement.txt b/examples/kv_cache_calculator/requirement.txt
new file mode 100644
index 0000000..976a2b1
--- /dev/null
+++ b/examples/kv_cache_calculator/requirement.txt
@@ -0,0 +1 @@
+transformers
diff --git a/examples/kv_cache_reuse/README.md b/examples/kv_cache_reuse/README.md
new file mode 100644
index 0000000..4ee2775
--- /dev/null
+++ b/examples/kv_cache_reuse/README.md
@@ -0,0 +1,8 @@
+# Examples of KV cache reusing and sharing with vLLM + LMCache
+LMCache should be able to reduce the generation time of the second and following calls.
+
+We have examples for the following types of KV cache sharing and reusing:
+
+- KV cache reusing with local storage backends: `local_backends/`
+- KV cache reusing with remote storage backends: `remote_backends/`
+- KV cache sharing across different vLLM instances: `share_across_instances/`
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/local_backends/README.md b/examples/kv_cache_reuse/local_backends/README.md
new file mode 100644
index 0000000..f1b36e3
--- /dev/null
+++ b/examples/kv_cache_reuse/local_backends/README.md
@@ -0,0 +1,14 @@
+# Examples vLLM + LMCache w. local backends
+LMCache should be able to reduce the generation time of the second and following calls.
+## CPU offloading
+- `python offload.py -v v0` - CPU offloading implementation for vLLM v0
+- `python offload.py -v v1` - CPU offloading implementation for vLLM v1
+## Disk offloading
+- `python offload.py -v v0 --use-disk` - Disk offloading implementation for vLLM v0
+- `python offload.py -v v1 --use-disk` - Disk offloading implementation for vLLM v1
+
+## RUST raw block based Disk offloading
+
+   # WARNING: This will erase the content of target device.
+- `python rust_backend_offload.py --disk_path=/dev/nvme0n1` - posix disk offloading
+- `python rust_backend_offload.py --disk_path=/dev/nvme0n1 --use_uring` - io_uring disk offloading
diff --git a/examples/kv_cache_reuse/local_backends/offload.py b/examples/kv_cache_reuse/local_backends/offload.py
new file mode 100644
index 0000000..b01522c
--- /dev/null
+++ b/examples/kv_cache_reuse/local_backends/offload.py
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import contextlib
+import os
+import time
+
+# Third Party
+from vllm import LLM, SamplingParams
+from vllm.config import KVTransferConfig
+
+# First Party
+from lmcache.integration.vllm.utils import ENGINE_NAME
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+
+
+def setup_environment_variables(vllm_version: str, use_disk: bool = False):
+    # LMCache-related environment variables
+
+    # LMCache is set to use 256 tokens per chunk
+    os.environ["LMCACHE_CHUNK_SIZE"] = "256"
+
+    if use_disk:
+        # Disable local CPU backend in LMCache
+        os.environ["LMCACHE_LOCAL_CPU"] = "False"
+
+        # Set the maximum size of the local CPU buffer size to 5GB
+        os.environ["LMCACHE_MAX_LOCAL_CPU_SIZE"] = "5"
+
+        # Enable local disk backend in LMCache
+        os.environ["LMCACHE_LOCAL_DISK"] = "file://local_disk/"
+
+        # Set the maximum size of the local disk size to 10GB
+        os.environ["LMCACHE_MAX_LOCAL_DISK_SIZE"] = "10"
+    else:
+        # Enable local CPU backend in LMCache
+        os.environ["LMCACHE_LOCAL_CPU"] = "True"
+
+        # Set the maximum size of the local CPU size to 5GB
+        os.environ["LMCACHE_MAX_LOCAL_CPU_SIZE"] = "5"
+
+    if vllm_version == "v0":
+        os.environ["VLLM_USE_V1"] = "0"
+
+
+@contextlib.contextmanager
+def build_llm_with_lmcache(lmcache_connector: str, model: str, vllm_version: str):
+    ktc = KVTransferConfig(
+        kv_connector=lmcache_connector,
+        kv_role="kv_both",
+    )
+    # Set GPU memory utilization to 0.8 for an A40 GPU with 40GB
+    # memory. Reduce the value if your GPU has less memory.
+    # Note: LMCache supports chunked prefill (see vLLM#14505, LMCache#392).
+    #
+    # Pass kwargs directly to LLM() instead of routing through
+    # EngineArgs + asdict(). asdict() emits None for every unset EngineArgs
+    # field, and vLLM >= 0.20 / pydantic v2 rejects None for
+    # CompilationConfig fields like cudagraph_capture_sizes (list) and
+    # pass_config.fuse_minimax_qk_norm (bool). See issue #3438.
+    llm_kwargs = {
+        "model": model,
+        "kv_transfer_config": ktc,
+        "max_model_len": 8000,
+        "gpu_memory_utilization": 0.8,
+    }
+    if vllm_version == "v0":
+        llm_kwargs["enable_chunked_prefill"] = True  # Only in v0
+    llm = LLM(**llm_kwargs)
+    try:
+        yield llm
+    finally:
+        # Clean up lmcache backend
+        LMCacheEngineBuilder.destroy(ENGINE_NAME)
+
+
+def print_output(
+    llm: LLM,
+    prompt: list[str],
+    sampling_params: SamplingParams,
+    req_str: str,
+):
+    # Should be able to see logs like the following:
+    # `LMCache INFO: Storing KV cache for 6006 out of 6006 tokens for request 0`
+    # This indicates that the KV cache has been stored in LMCache.
+    start = time.time()
+    outputs = llm.generate(prompt, sampling_params)
+    print("-" * 50)
+    for output in outputs:
+        generated_text = output.outputs[0].text
+        print(f"Generated text: {generated_text!r}")
+    print(f"Generation took {time.time() - start:.2f} seconds, {req_str} request done.")
+    print("-" * 50)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-v",
+        "--version",
+        choices=["v0", "v1"],
+        default="v1",
+        help=(
+            "Specify vLLM version (default: v1). "
+            "v0 requires vLLM <= 0.10.x; vLLM 0.11.0+ removed the V0 engine."
+        ),
+    )
+    parser.add_argument(
+        "-d",
+        "--use-disk",
+        action="store_true",
+        help="Specify whether to use disk as backend (default: False)",
+    )
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+
+    if args.version == "v0":
+        lmcache_connector = "LMCacheConnector"
+        model = "mistralai/Mistral-7B-Instruct-v0.2"
+    else:
+        lmcache_connector = "LMCacheConnectorV1"
+        model = "mistralai/Mistral-7B-Instruct-v0.2"
+
+    setup_environment_variables(args.version, args.use_disk)
+
+    with build_llm_with_lmcache(lmcache_connector, model, args.version) as llm:
+        # This example script runs two requests with a shared prefix.
+        # Define the shared prompt and specific prompts
+        shared_prompt = "Hello, how are you?" * 1000
+        first_prompt = [
+            shared_prompt + "Hello, my name is",
+        ]
+        second_prompt = [
+            shared_prompt + "Tell me a very long story",
+        ]
+
+        sampling_params = SamplingParams(temperature=0, top_p=0.95, max_tokens=10)
+
+        # Print the first output
+        print_output(llm, first_prompt, sampling_params, "first")
+
+        time.sleep(1)
+
+        # print the second output
+        print_output(llm, second_prompt, sampling_params, "second")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/kv_cache_reuse/local_backends/rust_backend_offload.py b/examples/kv_cache_reuse/local_backends/rust_backend_offload.py
new file mode 100644
index 0000000..864c1e5
--- /dev/null
+++ b/examples/kv_cache_reuse/local_backends/rust_backend_offload.py
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from dataclasses import asdict
+import argparse
+import contextlib
+import json
+import os
+import time
+
+# Third Party
+from vllm import LLM, SamplingParams
+from vllm.config import KVTransferConfig
+from vllm.engine.arg_utils import EngineArgs
+
+# First Party
+from lmcache.integration.vllm.utils import ENGINE_NAME
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+
+
+def setup_environment_variables(raw_block_path: str, use_uring: bool = False) -> None:
+    """Set up LMCache-related environment variables for the Rust raw block backend.
+
+    Configures environment variables for LMCache including chunk size, storage
+    plugins, and Rust raw block backend specific settings.
+
+    Args:
+        raw_block_path: Path to the raw block device for storage.
+        use_uring: Whether to enable io_uring path
+
+    Returns:
+        None
+    """
+    # LMCache-related environment variables
+
+    # LMCache is set to use 256 tokens per chunk
+    os.environ["LMCACHE_CHUNK_SIZE"] = "256"
+
+    # Disable local CPU backend in LMCache
+    os.environ["LMCACHE_LOCAL_CPU"] = "False"
+
+    # Set the maximum size of the local disk size to 5GB
+    os.environ["LMCACHE_MAX_LOCAL_DISK_SIZE"] = "5"
+
+    os.environ["LMCACHE_STORAGE_PLUGINS"] = "raw_block"
+
+    # Raw block specific extra config
+    os.environ["LMCACHE_EXTRA_CONFIG"] = json.dumps(
+        {
+            "storage_plugin.raw_block.module_path": "lmcache.v1.storage_backend.plugins.rust_raw_block_backend",  # noqa: E501
+            "storage_plugin.raw_block.class_name": "RustRawBlockBackend",
+            "rust_raw_block.device_path": raw_block_path,
+            "rust_raw_block.use_odirect": True,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+            "rust_raw_block.use_uring": use_uring,
+        }
+    )
+
+
+@contextlib.contextmanager
+def build_llm_with_lmcache(lmcache_connector: str, model: str):
+    """Build a vLLM LLM instance with LMCache integration.
+
+    Creates a context manager that builds a vLLM LLM instance configured with
+    LMCache for KV cache management. The LLM is yielded and cleaned up on exit.
+
+    Args:
+        lmcache_connector: The LMCache connector name to use
+        model: The model name.
+    """
+    ktc = KVTransferConfig(
+        kv_connector=lmcache_connector,
+        kv_role="kv_both",
+    )
+    # Set GPU memory utilization to 0.5 for an A100 GPU with 40GB
+    # memory. Update it accordingly for different GPU.
+    llm_args = EngineArgs(
+        model=model,
+        kv_transfer_config=ktc,
+        max_model_len=8000,
+        gpu_memory_utilization=0.5,
+    )
+    llm = LLM(**asdict(llm_args))
+    try:
+        yield llm
+    finally:
+        # Clean up the LMCache backend
+        LMCacheEngineBuilder.destroy(ENGINE_NAME)
+
+
+def print_output(
+    llm: LLM,
+    prompt: list[str],
+    sampling_params: SamplingParams,
+    req_str: str,
+) -> None:
+    """Generate text using the LLM and print the output with timing information.
+
+    Args:
+        llm: The vLLM LLM instance to use for generation.
+        prompt: The input prompt(s) as a list of strings.
+        sampling_params: Sampling parameters for generation.
+        req_str: A string identifier for the request.
+
+    Returns:
+        None
+    """
+    start = time.time()
+    outputs = llm.generate(prompt, sampling_params)
+    print("-" * 50)
+    for output in outputs:
+        generated_text = output.outputs[0].text
+        print(f"Generated text: {generated_text!r}")
+    print(f"Generation took {time.time() - start:.2f} seconds, {req_str} request done.")
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments for the script.
+
+    Returns:
+        argparse.Namespace: Parsed arguments containing:
+            - disk_path: Path to the raw block device for storage.
+            - use_uring: Whether to enable io_uring path.
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--disk_path",
+        type=str,
+    )
+    parser.add_argument(
+        "--use_uring",
+        action="store_true",
+        help="Enable io_uring path (requires Linux kernel >= 5.1)",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    """Main entry point for the Rust backend offload example.
+
+    Sets up environment variables, builds an LLM with LMCache integration,
+    and runs two requests with a shared prefix to demonstrate KV cache reuse.
+
+    Returns:
+        None
+    """
+    args = parse_args()
+
+    connector = "LMCacheConnectorV1"
+    model = "Qwen/Qwen3-8B"
+
+    setup_environment_variables(args.disk_path, args.use_uring)
+
+    with build_llm_with_lmcache(connector, model) as llm:
+        # This example script runs two requests with a shared prefix.
+        # Define the shared prompt and specific prompts
+        shared_prompt = "Hello, how are you?" * 1000
+        first_prompt = [
+            shared_prompt + "Hello, my name is",
+        ]
+        second_prompt = [
+            shared_prompt + "Tell me a very long story",
+        ]
+
+        sampling_params = SamplingParams(temperature=0, top_p=0.95, max_tokens=10)
+
+        # Print the first output
+        print_output(llm, first_prompt, sampling_params, "first")
+
+        time.sleep(1)
+
+        # print the second output
+        print_output(llm, second_prompt, sampling_params, "second")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/kv_cache_reuse/remote_backends/README.md b/examples/kv_cache_reuse/remote_backends/README.md
new file mode 100644
index 0000000..26479ff
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/README.md
@@ -0,0 +1,8 @@
+# Examples vLLM + LMCache w. remote backends
+LMCache should be able to reduce the generation time of the second and following calls.
+
+We have examples for the following backends:
+
+- Infinistore: `infinistore/`
+- Mooncake: `mooncakestore/`
+- External: `external/`
diff --git a/examples/kv_cache_reuse/remote_backends/external/README.md b/examples/kv_cache_reuse/remote_backends/external/README.md
new file mode 100644
index 0000000..bf169b4
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/external/README.md
@@ -0,0 +1,41 @@
+# External Connector for LMCache
+
+LMCache supports custom external storage backends via Python modules. This connector type allows integrating any key-value store with LMCache.
+
+## Requirements
+
+1. Implement a connector class inheriting from `BaseConnector` (see `base_connector.py`)
+2. Place your module in Python import path
+
+## Configuration
+
+Specify module and class name by `remote_url` in `backend_type.yaml`, and the remote_url should contain
+- **Module Path**: Specify the Python module path (e.g., `external_log_connector.lmc_external_log_connector`)
+- **Connector Name**: Provide the class name of the connector (e.g., `ExternalLogConnector`)
+
+## Example YAML Configuration
+
+This example use lmc_external_log_connector as an example which is an internal lmcache remote connector. Reference [lmc_exernal_log_connector](https://github.com/opendataio/lmc_exernal_log_connector)
+
+```yaml
+remote_url: "external://host:0/external_log_connector.lmc_external_log_connector/?connector_name=ExternalLogConnector"
+extra_config:
+  ext_log_connector_support_ping: True
+  ext_log_connector_health_interval: 10.0
+  ext_log_connector_stuck_time: 6.0
+```
+
+## Start vLLM with the lmc_external_log_connector as an external connector
+
+```shell
+VLLM_USE_V1=0 \
+LMCACHE_TRACK_USAGE=false \
+LMCACHE_CONFIG_FILE=backend_type.yaml \
+vllm serve /disc/f/models/opt-125m/ \
+           --served-model-name "facebook/opt-125m" \
+           --enforce-eager  \
+           --port 8000 \
+           --gpu-memory-utilization 0.8 \
+           --kv-transfer-config '{"kv_connector":"LMCacheConnector","kv_role":"kv_both"}' \
+           --trust-remote-code
+```
diff --git a/examples/kv_cache_reuse/remote_backends/external/backend_type.yaml b/examples/kv_cache_reuse/remote_backends/external/backend_type.yaml
new file mode 100644
index 0000000..1b67939
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/external/backend_type.yaml
@@ -0,0 +1,11 @@
+# lmcache.yaml
+chunk_size: 256
+local_device: "cpu"
+local_cpu: False
+max_local_cpu_size: 5
+remote_url: "external://host:0/external_log_connector.lmc_external_log_connector/?connector_name=ExternalLogConnector"
+remote_serde: "naive"
+extra_config:
+  ext_log_connector_support_ping: True
+  ext_log_connector_health_interval: 10.0
+  ext_log_connector_stuck_time: 6.0
diff --git a/examples/kv_cache_reuse/remote_backends/fs/example.yaml b/examples/kv_cache_reuse/remote_backends/fs/example.yaml
new file mode 100644
index 0000000..07bf562
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/fs/example.yaml
@@ -0,0 +1,9 @@
+chunk_size: 256
+local_cpu: False
+max_local_cpu_size: 1
+save_unfull_chunk: False
+
+remote_url: "fs://host:0/tmp/lmcache_fs_test"
+
+extra_config:
+  save_chunk_meta: False
diff --git a/examples/kv_cache_reuse/remote_backends/infinistore/README.md b/examples/kv_cache_reuse/remote_backends/infinistore/README.md
new file mode 100644
index 0000000..a099c74
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/infinistore/README.md
@@ -0,0 +1,45 @@
+lmcache could use [infinistore](https://github.com/bd-iaas-us/InfiniStore) as a backend storage.
+
+Infinistore is a memory storage which support RDMA and NVLINK. lmcache's infinistore connector is using RDMA transport for now.
+
+This is a simple instruction how to use lmcache with infinistore
+
+# install infistore
+
+1. make sure RDMA driver is installed.
+
+use ibverbs-utils to find active NIC. In this example we assume NIC:mlx5_0 is the active NIC.
+
+```
+ibv_devinfo
+```
+
+2. install infinistore 
+
+```
+pip install infinistore
+```
+
+now, infinistore support python3.10, python3.11, python3.12
+
+# start infinistore and lmcache
+
+1. start infinistore
+
+mlx5_0 is an active RDMA NIC
+
+```
+python -m infinistore.server --service-port 12345 --dev-name mlx5_0 --link-type Ethernet  --manage-port 8080
+```
+
+2. start lmcache
+```
+LMCACHE_CONFIG_FILE=backend_type.yaml python -m lmcache_vllm.vllm.entrypoints.openai.api_server --model mistralai/Mistral-7B-Instruct-v0.2  --max-model-len 8192
+```
+
+
+# RDMA/infinistore troubleshooting
+
+1. infinistore's log could reveal many details. if lmcache read/write cache, you will find corresponding PUT/GET requests.
+2. you could use [perftest](https://github.com/linux-rdma/perftes) utils to check connectivity and bandwidth.
+3. infinistore itself has client [examples](https://github.com/bd-iaas-us/InfiniStore/tree/main/infinistore/example) to check if RDMA connection works.
diff --git a/examples/kv_cache_reuse/remote_backends/infinistore/backend_type.yaml b/examples/kv_cache_reuse/remote_backends/infinistore/backend_type.yaml
new file mode 100644
index 0000000..2fca32b
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/infinistore/backend_type.yaml
@@ -0,0 +1,2 @@
+chunk_size: 256
+remote_url: "infinistore://127.0.0.1:12345"
diff --git a/examples/kv_cache_reuse/remote_backends/mock/README.md b/examples/kv_cache_reuse/remote_backends/mock/README.md
new file mode 100644
index 0000000..8491a0b
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/mock/README.md
@@ -0,0 +1,25 @@
+# Mock Remote Connector
+
+LMCache provides a mock remote connector that allows you to manually set the peeking latency, read throughput, and write throughput inside of the remote url. It will create copies of your KV cache in unmanaged local RAM.
+
+
+Deploy a serving engine with the mock remote backend: 
+```bash
+LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' --disable-log-requests --no-enable-prefix-caching
+```
+
+Check the retrieval (storing is async so the throughput there is meaningless) logs on the second query to confirm that the throughput is slightly lower than 2 GB / s (the CPU <-> GPU allocation / transfer also has overhead).
+
+```bash
+curl -X POST http://localhost:8000/v1/completions   -H "Content-Type: application/json"   -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "'"$(printf 'Elaborate the significance of KV cache in language models. %.0s' {1..1000})"'",
+    "max_tokens": 10
+  }'
+```
+
+Logs: 
+```text
+(EngineCore_0 pid=586318) [2025-09-03 05:06:41,751] LMCache INFO: Reqid: cmpl-b34e7c5b2f3e46a592722db2c27f6fc0-0, Total tokens 12002, LMCache hit tokens: 12002, need to load: 12001 (vllm_v1_adapter.py:1049:lmcache.integration.vllm.vllm_v1_adapter)
+(EngineCore_0 pid=586318) [2025-09-03 05:06:42,736] LMCache INFO: Retrieved 12002 out of total 12002 out of total 12002 tokens. size: 1.4651 gb, cost 980.6983 ms, throughput: 1.4939 GB/s; (cache_engine.py:503:lmcache.v1.cache_engine)
+```
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/remote_backends/mock/example.yaml b/examples/kv_cache_reuse/remote_backends/mock/example.yaml
new file mode 100644
index 0000000..b3b0770
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/mock/example.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_cpu: False
+max_local_cpu_size: 10
+remote_url: "mock://100/?peeking_latency=1&read_throughput=2&write_throughput=2"
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/remote_backends/mooncakestore/README.md b/examples/kv_cache_reuse/remote_backends/mooncakestore/README.md
new file mode 100644
index 0000000..95439a1
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/mooncakestore/README.md
@@ -0,0 +1,29 @@
+lmcache could use [mooncakestore](https://github.com/kvcache-ai/Mooncake) as a backend storage.
+
+Mooncakestore is a memory storage which support RDMA and TCP. lmcache's mooncakestore connector can use TCP/RDMA transport for now.
+
+This is a simple instruction how to use lmcache with mooncakestore
+
+# install mooncakestore
+
+```
+pip install mooncake-transfer-engine
+```
+
+# start mooncake store and lmcache
+
+1. start mooncake store
+
+```
+mooncake_master -v=1
+mooncake_http_metadata_server --port 8005
+```
+
+2. start vllm with lmcache connector
+```
+LMCACHE_CONFIG_FILE="mooncake.yaml" \
+vllm serve meta-llama/Llama-3.1-8B-Instruct
+           --port 8000 \
+           --gpu-memory-utilization 0.8 \
+           --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}' \
+```
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/remote_backends/mooncakestore/mooncake.yaml b/examples/kv_cache_reuse/remote_backends/mooncakestore/mooncake.yaml
new file mode 100644
index 0000000..279f007
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/mooncakestore/mooncake.yaml
@@ -0,0 +1,15 @@
+chunk_size: 256
+remote_url: "mooncakestore://127.0.0.1:50051/"
+remote_serde: "naive"
+local_cpu: False
+max_local_cpu_size: 5
+
+extra_config:
+  save_chunk_meta: false
+  local_hostname: "localhost"
+  metadata_server: "http://127.0.0.1:8005/metadata"
+  protocol: "tcp"
+  master_server_address: "localhost:50051"
+  global_segment_size: 13958643712 # 13GB
+  local_buffer_size: 5368709120 # 5GB
+  transfer_timeout: 1
diff --git a/examples/kv_cache_reuse/remote_backends/resp/README.md b/examples/kv_cache_reuse/remote_backends/resp/README.md
new file mode 100644
index 0000000..89532f1
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/resp/README.md
@@ -0,0 +1,137 @@
+# LMCacheRedis KV Connector
+
+The cpp binding is in `csrc/redis/*`.
+
+The key optimization is multi-threading and batching on the C layer and the python side being awoken through the eventfd API where a callback consumes the completion belonging to a non-blocking submission. 
+
+An GET / SET benchmark is in `examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py`. The python client lives inside of `lmcache/v1/storage_backend/resp_client.py`.
+
+Install lmcache from source, then run a sanity check:
+
+```bash
+# Run with defaults: host=127.0.0.1, port=6379, chunk-mb=4.0, num-workers=8, num-keys=500
+python benchmark_resp_client.py
+
+# Or customize parameters:
+python benchmark_resp_client.py \
+    --host localhost \
+    --port 6379 \
+    --chunk-mb 1.0 \
+    --num-workers 8 \
+    --num-keys 1280 \
+    --username default \
+    --password YOUR_PASSWORD
+```
+
+## Quickstart
+
+Start up redis with multiple io threads: 
+```bash
+git clone https://github.com/redis/redis.git
+cd redis
+git checkout 8.2
+make -j
+./src/redis-server --protected-mode no --save '' --appendonly no --io-threads 4
+```
+
+Clear the state between queries
+```bash
+sudo apt install redis-cli
+redis-cli -p 6379 FLUSHALL
+redis-cli -p 6379 DBSIZE
+```
+
+Deploy LMCache with the custom LMCacheRedis KV Connector
+
+`save_unfull_chunk` must be off (default is off) and also we must not save the chunk metadata. 
+
+The "golden spot" for high throughput transfers for redis is ~4 MB (any higher or lower will cause performance degradation, for a model like meta-llama/Llama-3.1-8B-Instruct, this is around 16 tokens
+```bash
+LMCACHE_CONFIG_FILE=resp.yaml \
+vllm serve meta-llama/Llama-3.1-8B-Instruct \
+    --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' \
+    --no-enable-prefix-caching \
+    --load-format dummy
+```
+
+## MP Mode (Multiprocess)
+
+MP mode runs LMCache as a separate server process, communicating with vLLM over
+ZMQ. The RESP connector serves as an L2 adapter, supporting variable-size
+chunks. See [`csrc/storage_backends/README.md`](../../../../csrc/storage_backends/README.md)
+for the full native backend architecture.
+
+### Launch Redis
+
+```bash
+# Build Redis 8.2 with IO threads
+git clone https://github.com/redis/redis.git && cd redis
+git checkout 8.2 && make -j
+./src/redis-server --protected-mode no --save '' --appendonly no --io-threads 4 --port 6379
+```
+
+### Launch LMCache MP Server
+
+```bash
+lmcache server \
+    --l1-size-gb 10 \
+    --eviction-policy LRU \
+    --chunk-size 16 \
+    --l2-adapter '{"type": "resp", "host": "localhost", "port": 6379, "num_workers": 8}' \
+    --port 6555
+```
+
+The `--l2-adapter` JSON accepts these fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | str | (required) | Must be `"resp"` |
+| `host` | str | (required) | Redis hostname |
+| `port` | int | (required) | Redis port |
+| `num_workers` | int | 8 | C++ worker threads for parallel I/O |
+| `username` | str | `""` | Redis ACL username |
+| `password` | str | `""` | Redis AUTH password |
+| `max_capacity_gb` | float | 0 | Max L2 capacity in GB for usage tracking (required for L2 eviction) |
+
+### Launch vLLM with LMCache MP Connector
+
+```bash
+PORT=8000
+vllm serve meta-llama/Llama-3.1-8B-Instruct \
+    --kv-transfer-config '{
+        "kv_connector": "LMCacheMPConnector",
+        "kv_role": "kv_both",
+        "kv_connector_extra_config": {
+            "lmcache.mp.host": "tcp://localhost",
+            "lmcache.mp.port": 6555
+        }
+    }' \
+    --no-enable-prefix-caching \
+    --port $PORT \
+    --load-format dummy
+```
+
+### Test (MP and non-MP mode)
+
+Send the same prompt twice. The first request stores KV cache to Redis via the
+MP server; the second retrieves it.
+
+```bash
+PORT=8000
+PROMPT="$(printf 'Elaborate the significance of KV cache in language models. %.0s' {1..1000})"
+
+# First request: store
+curl -s -X POST http://localhost:${PORT}/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"meta-llama/Llama-3.1-8B-Instruct","prompt":"'"$PROMPT"'","max_tokens":10}'
+
+# Second request with same prefix: retrieve from Redis
+curl -s -X POST http://localhost:${PORT}/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model":"meta-llama/Llama-3.1-8B-Instruct","prompt":"'"$PROMPT"'","max_tokens":10}'
+```
+
+Check Redis to verify data was stored:
+```bash
+redis-cli -p 6379 DBSIZE
+```
diff --git a/examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py b/examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py
new file mode 100644
index 0000000..59c049c
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/resp/benchmark_resp_client.py
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Benchmark and example usage of the RESPClient.
+
+This script demonstrates how to use the RESPClient for high-throughput
+batch operations with Redis using the RESP protocol.
+"""
+
+# Standard
+import argparse
+import asyncio
+import time
+
+# First Party
+from lmcache.v1.storage_backend.native_clients.resp_client import RESPClient
+
+
+async def run_benchmark(
+    host: str,
+    port: int,
+    chunk_mb: float,
+    num_workers: int,
+    num_keys: int,
+    username: str = "",
+    password: str = "",
+):
+    batch_chunk_num_bytes = int(chunk_mb * 1024 * 1024)
+
+    client = RESPClient(host, port, num_workers, username=username, password=password)
+
+    try:
+        print("Redis RESP Client Benchmark")
+        print(f"Server: {host}:{port}, Workers: {num_workers}")
+        print(f"Chunk size: {batch_chunk_num_bytes / 1024:.0f}KB, Keys: {num_keys}")
+        print("-" * 60)
+
+        # Prepare test data
+        print("starting buffer initialization (this might take a while)")
+        keys = [f"bench:key:{i}" for i in range(num_keys)]
+        buffers = [bytearray(batch_chunk_num_bytes) for _ in range(num_keys)]
+        for i, buf in enumerate(buffers):
+            for j in range(batch_chunk_num_bytes):
+                buf[j] = (i + j) % 256
+
+        print("buffer initialization complete")
+        print("starting throughput benchmarks")
+
+        # Batch SET
+        t0 = time.perf_counter()
+        await client.batch_set(keys, [memoryview(b) for b in buffers])
+        t1 = time.perf_counter()
+        elapsed_set = t1 - t0
+        total_bytes_set = num_keys * batch_chunk_num_bytes
+        throughput_set = total_bytes_set / elapsed_set / (1024**3)
+        print(
+            f"Batch SET:    {throughput_set:6.2f} GB/s  "
+            f"({total_bytes_set / (1024**3):.2f} GB written)"
+        )
+
+        # Batch GET
+        read_bufs = [bytearray(batch_chunk_num_bytes) for _ in range(num_keys)]
+        t0 = time.perf_counter()
+        await client.batch_get(keys, [memoryview(b) for b in read_bufs])
+        t1 = time.perf_counter()
+        elapsed_get = t1 - t0
+        total_bytes_get = num_keys * batch_chunk_num_bytes
+        throughput_get = total_bytes_get / elapsed_get / (1024**3)
+        print(
+            f"Batch GET:    {throughput_get:6.2f} GB/s  "
+            f"({total_bytes_get / (1024**3):.2f} GB read)"
+        )
+
+        # Verify data
+        assert all(read_bufs[i] == buffers[i] for i in range(num_keys)), "Data mismatch"
+
+        # Batch EXISTS
+        t0 = time.perf_counter()
+        exists_results = await client.batch_exists(keys)
+        t1 = time.perf_counter()
+        elapsed_exists = t1 - t0
+        ops_per_sec = num_keys / elapsed_exists
+        hits = sum(exists_results)
+        print(f"Batch EXISTS: {ops_per_sec:6.0f} ops/s  ({hits}/{num_keys} hits)")
+
+        # Test batched_exists alias
+        results = await client.batched_exists(keys[:10])
+        assert results == exists_results[:10], "batched_exists mismatch"
+
+        print("-" * 60)
+        print("All tests passed")
+
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Benchmark RESPClient with configurable parameters"
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Redis server host (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=6379,
+        help="Redis server port (default: 6379)",
+    )
+    parser.add_argument(
+        "--chunk-mb",
+        type=float,
+        default=4.0,
+        help="Chunk size in MB (default: 4.0)",
+    )
+    parser.add_argument(
+        "--num-workers",
+        type=int,
+        default=8,
+        help="Number of worker threads (default: 8)",
+    )
+    parser.add_argument(
+        "--num-keys",
+        type=int,
+        default=500,
+        help="Number of keys to benchmark (default: 500)",
+    )
+    parser.add_argument(
+        "--username",
+        type=str,
+        default="",
+        help="Redis username for authentication (default: empty, no auth)",
+    )
+    parser.add_argument(
+        "--password",
+        type=str,
+        default="",
+        help="Redis password for authentication (default: empty, no auth)",
+    )
+
+    args = parser.parse_args()
+    asyncio.run(
+        run_benchmark(
+            host=args.host,
+            port=args.port,
+            chunk_mb=args.chunk_mb,
+            num_workers=args.num_workers,
+            num_keys=args.num_keys,
+            username=args.username,
+            password=args.password,
+        )
+    )
diff --git a/examples/kv_cache_reuse/remote_backends/resp/resp.yaml b/examples/kv_cache_reuse/remote_backends/resp/resp.yaml
new file mode 100644
index 0000000..6b8ebfe
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/resp/resp.yaml
@@ -0,0 +1,16 @@
+chunk_size: 16 # the "golden spot" for high throughput transfers for redis is ~4 MB (any higher or lower will cause performance degradation, for a model like meta-llama/Llama-3.1-8B-Instruct, this is around 16 tokens)
+local_cpu: false
+max_local_cpu_size: 20.0
+remote_url: "resp://localhost:6379"
+async_loading: false # LMCache RESP also support async loading
+remote_serde: "naive"
+blocking_timeout_secs: 120
+extra_config:
+  resp_num_threads: 8 # default is 8 if not specified
+  save_chunk_meta: False # make sure we have fixed size payloads
+  # Authentication: prefer environment variables to keep secrets out of logs.
+  #   export LMCACHE_RESP_USERNAME="default"
+  #   export LMCACHE_RESP_PASSWORD="YOUR_REDIS_PASSWORD"
+  # Alternatively, set them here (they will appear in logged config):
+  # username: "default"
+  # password: "YOUR_REDIS_PASSWORD"
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/remote_backends/s3/README.md b/examples/kv_cache_reuse/remote_backends/s3/README.md
new file mode 100644
index 0000000..bc16bbb
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/s3/README.md
@@ -0,0 +1,34 @@
+## LMCache can use [Amazon S3](https://aws.amazon.com/s3/) as a backend storage.
+
+Amazon Simple Storage Service (Amazon S3) is an object storage service offering industry-leading scalability, data availability, security, and performance.
+
+To maximize S3 performance, it's recommended to use [Amazon S3 Express One Zone storage class](https://aws.amazon.com/s3/storage-classes/express-one-zone/) and colocate your S3 bucket and [Amazon EC2 compute instance](https://aws.amazon.com/ec2/) in the same availability zone. 
+
+## Step 1: Configure your S3 bucket and (optional) EC2 compute instance
+
+See https://aws.amazon.com/s3/storage-classes/express-one-zone/ for configuring your S3 express-one-zone bucket. Normal S3 bucket is functional but gives worse performance.
+
+See https://aws.amazon.com/ec2/ for configuring your own EC2 compute instance. Your own server or other cloud servers also work but give worse performance.
+
+
+## Step 2: Fill out `example.yaml`
+
+Please fill out the `BUCKET_NAME`, `AZ_ID`, and `REGION` in the `example.yaml`. 
+
+## Step 3: Start an vLLM engine with LMCache
+
+```bash
+PYTHONHASHSEED=0 LMCACHE_CONFIG_FILE=example.yaml vllm serve meta-llama/Llama-3.1-8B-Instruct --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}' --disable-log-requests --no-enable-prefix-caching
+```
+
+## Step 4: Sending requests
+
+You should be able to see cache hit on the second time by sending the following request twice:
+
+```bash
+curl -X POST http://localhost:8000/v1/completions   -H "Content-Type: application/json"   -d '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "prompt": "'"$(printf 'Elaborate the significance of KV cache in language models. %.0s' {1..1000})"'",
+    "max_tokens": 10
+  }'
+```
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/remote_backends/s3/example.yaml b/examples/kv_cache_reuse/remote_backends/s3/example.yaml
new file mode 100644
index 0000000..1d193c4
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/s3/example.yaml
@@ -0,0 +1,18 @@
+chunk_size: 256
+local_cpu: False
+max_local_cpu_size: 10
+save_unfull_chunk: False
+
+remote_url: "s3://{BUCKET_NAME}.s3express-{AZ_ID}.{REGION}.amazonaws.com"
+remote_serde: "naive"
+
+blocking_timeout_secs: 100
+
+extra_config:
+  save_chunk_meta: False
+  s3_num_io_threads: 64
+  s3_prefer_http2: True
+  s3_region: "{REGION}"
+  s3_enable_s3express: True
+  aws_access_key_id: "{AWS_ACCESS_KEY_ID}"
+  aws_secret_access_key: "{AWS_SECRET_ACCESS_KEY}"
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/remote_backends/valkey/VALKEY_CONNECTOR_BENCHMARKING.md b/examples/kv_cache_reuse/remote_backends/valkey/VALKEY_CONNECTOR_BENCHMARKING.md
new file mode 100644
index 0000000..0f3b035
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/valkey/VALKEY_CONNECTOR_BENCHMARKING.md
@@ -0,0 +1,293 @@
+# ValkeyConnector Benchmarking
+
+## Executive Summary
+
+This document benchmarks the `ValkeyConnector` after adding cluster mode, TLS support, and optimized large-value handling, using [valkey-glide](https://github.com/valkey-io/valkey-glide) as the underlying client.
+
+The motivation for this benchmarking is to validate the performance impact of three key changes:
+
+- **GLIDE sync client with optimized large-value handling** — leverages two upstream GLIDE contributions that reduce memory copies on large KV cache chunks: [zero-copy SET via `bytearray`/`memoryview` args](https://github.com/valkey-io/valkey-glide/commit/d4139c3) and [buffer GET to read directly into pre-allocated memory](https://github.com/valkey-io/valkey-glide/commit/3e44f33). These eliminate intermediate allocations when transferring multi-MB chunks.
+- **TLS support** — enables connections to TLS-enabled clusters, including ElastiCache Serverless (which requires TLS). This was not possible with `RedisClusterConnector`. TLS adds only 7–8% overhead at 64k context.
+- **Cluster and standalone modes** — a single `valkey_mode` config switches between `GlideClusterClient` (auto-discovers topology from a seed node) and `GlideClient` (single node with optional `database_id`).
+
+We benchmarked `ValkeyConnector` against `RedisClusterConnector` on the same Valkey clusters (provisioned and serverless) using Llama 3.1 70B (TP=8) and 8B (TP=1) with context lengths from 8k to 64k tokens. `ValkeyConnector` delivers **1.6–1.8× faster L2 retrieval** than `RedisClusterConnector` across all configurations, achieving up to **4.8× speedup over cold compute** at 64k context (3.2s vs 15.6s).
+
+| | ValkeyConnector | RedisClusterConnector |
+|---|---|---|
+| 70B 64k L2 TTFT | **3,216ms (4.8×)** | 5,794ms (2.7×) |
+| 70B 8k L2 TTFT | **505ms (4.4×)** | 796ms (3.0×) |
+| 8B 64k L2 TTFT | **2,527ms (4.5×)** | 15,600ms (0.8×) |
+| Aggregate throughput (70B 64k) | ~7.5 GB/s | ~4.0 GB/s |
+| Cluster mode | ✅ | ✅ |
+| TLS / Serverless ElastiCache | ✅ | ❌ Not supported |
+
+## Hardware & Software Setup
+
+| Component | Details |
+|---|---|
+| Instance | `p4de.24xlarge` — 8× A100-SXM4-80GB, 96 vCPUs, 1.1 TB RAM |
+| Models | `meta-llama/Llama-3.1-70B-Instruct` (bf16, TP=8) and `Llama-3.1-8B-Instruct` (bf16, TP=1) |
+| vLLM | 0.17.0 with `LMCacheConnectorV1` |
+| LMCache | 0.1.dev1240 |
+| valkey-glide | Built from `valkey-io/valkey-glide` main (`5327ebc`) |
+| Hash algorithm | `sha256_cbor_64bit` (required for TP>1 — Python's `hash()` is non-deterministic across vLLM's subprocess boundary) |
+
+### Cluster Backends
+
+All tests used the same Valkey cluster backends — both connectors talk to the same infrastructure.
+
+| Type | Nodes | TLS | Instance Type |
+|---|---|---|---|
+| ElastiCache Provisioned | 10 primaries | No | `cache.r7g.16xlarge` |
+| ElastiCache Serverless | auto-scaling | Yes | managed |
+
+### Connectors Under Test
+
+| Connector | Client Library | Storage Format | GETs per Chunk |
+|---|---|---|---|
+| **ValkeyConnector** | GLIDE sync (Rust FFI) | Single-key (raw bytes) | 1 |
+| RedisClusterConnector | `redis-py` (async) | 2-key (metadata + kv_bytes) | 2 |
+
+### Chunk Sizes
+
+The KV cache chunk size in bytes depends on the model architecture:
+
+| Model | Layers | chunk_size (tokens) | Chunk Bytes | Formula |
+|---|---|---|---|---|
+| 70B (TP=8) | 80 | 256 | ~10 MB | 2 × 80 × 256 × 1 head × 128 dim × 2 bytes (bf16) |
+| 8B (TP=1) | 32 | 256 | ~4 MB | 2 × 32 × 256 × 8 heads × 128 dim × 2 bytes (bf16) |
+
+## How We Measured TTFT
+
+TTFT (Time To First Token) is measured end-to-end from the client side using `curl` against vLLM's `/v1/completions` endpoint:
+
+```bash
+START=$(date +%s%N)
+curl -s -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d @prompt_64k_70b.json > /dev/null
+END=$(date +%s%N)
+echo "TTFT: $(( (END-START)/1000000 ))ms"
+```
+
+This captures the full request latency including network, tokenization, KV cache retrieval (or compute), and first-token generation. We report three TTFT variants:
+
+- **Cold TTFT** — No cached data anywhere. vLLM computes KV cache from scratch, then stores to L1 (CPU) + L2 (Valkey). This is the baseline.
+- **L1 TTFT** — Data in CPU pinned memory. ~5 GB/s per rank. Not what we're benchmarking, but useful as a reference.
+- **L2 TTFT** — Data evicted from L1, retrieved from Valkey. This is the target metric. Speedup = Cold TTFT / L2 TTFT.
+
+### Per-Rank Throughput
+
+vLLM logs per-rank retrieval stats for each request:
+
+```
+Retrieved 65024 out of 65024 required tokens (from 65024 total tokens).
+  size: 2.4805 gb, cost 2558.0752 ms, throughput: 0.9697 GB/s
+```
+
+This is the internal LMCache measurement — the time from `batched_get` start to all chunks received, per TP rank. Aggregate throughput = per-rank × number of ranks.
+
+## Why L2 Benchmarking Is Hard
+
+LMCache has two cache tiers. On a hit, L1 is checked first. To measure L2 performance, we must force L1 misses by evicting the test data before the retrieval request.
+
+### The Prefix Hash Problem
+
+LMCache uses rolling prefix hashes for chunk keys:
+
+```
+chunk_hash[i] = hash(chunk_hash[i-1], tokens[i*256 : (i+1)*256])
+```
+
+If two prompts share a token prefix, all chunks within that prefix produce identical hashes. LRU sees them as the same entries and never evicts them. Sending "different" prompts that happen to share a prefix with the test prompt does not evict the test data.
+
+### Solution: Zero-Overlap Flood Prompts
+
+We created `benchmark_l2.py` which generates flood prompts from completely disjoint random text using different random seeds. This guarantees zero token-level prefix overlap, so every chunk hash is unique from the very first chunk.
+
+```bash
+python3 benchmark_l2.py generate \
+    --model meta-llama/Llama-3.1-70B-Instruct \
+    --context-tokens 65024 \
+    --num-floods 3 \
+    --output-dir /home/ubuntu/bench_prompts
+```
+
+The script verifies zero overlap:
+```
+Flood 1: 65024 tokens
+Token prefix overlap with test: 0 (< chunk_size=256 → OK, different chunk hashes)
+```
+
+### L1 Sizing
+
+`max_local_cpu_size` must be large enough to hold retrieval buffers (otherwise: `No eviction candidates found in local cpu backend`) but small enough that floods can evict the test data:
+
+| Model | Context | Data per Rank | Recommended L1 | Floods Needed |
+|---|---|---|---|---|
+| 70B TP=8 | 8k | 320 MB | 1 GiB | 3 |
+| 70B TP=8 | 64k | 2.48 GB | 5 GiB | 3 |
+| 8B TP=1 | 8k | 128 MB | 1 GiB | 3 |
+| 8B TP=1 | 64k | 1.02 GB | 10 GiB | 5 |
+
+## Benchmark Workflow
+
+Each benchmark run follows this exact sequence:
+
+1. **Restart vLLM** — clears L1 (CPU pinned memory is per-process)
+2. **FLUSHALL** — clears all Valkey cluster nodes
+3. **Cold request** — sends test prompt; vLLM computes KV cache from scratch, stores to L1 + L2
+4. **Flood L1** — sends 3–5 disjoint prompts to fill L1 and evict the test data via LRU
+5. **Record `keyspace_hits`** on all cluster primaries (before L2 request)
+6. **L2 request** — sends the same test prompt again; L1 miss forces L2 retrieval from Valkey
+7. **Record `keyspace_hits`** on all cluster primaries (after L2 request)
+8. **Verify** — `keyspace_hits` delta confirms actual cluster GETs occurred
+
+### L2 Verification
+
+Every L2 result is verified through two independent methods:
+
+**`keyspace_hits` delta** (provisioned clusters):
+```bash
+for node in $NODES; do
+  redis-cli -h $node INFO stats | grep keyspace_hits
+done
+```
+- ValkeyConnector: expected delta = chunks × ranks (1 GET per chunk)
+- RedisClusterConnector: expected delta = chunks × ranks × 1.5 (2 GETs per chunk)
+- Delta = 0 means L1 hit — the test is invalid
+
+**vLLM log**:
+```
+Retrieved 65024 out of 65024 required tokens ... throughput: 0.95 GB/s
+```
+- "Retrieved" with sub-1 GB/s throughput = L2 hit
+- "Retrieved" with ~5 GB/s throughput = L1 hit (not an L2 test)
+- "Stored" only = no retrieval happened
+
+## Results
+
+### Full Comparison Matrix — 70B Model (TP=8, 10 MB chunks)
+
+| Connector | Backend | TLS | Context | Cold TTFT | L2 TTFT | Speedup | Per-rank | Aggregate |
+|---|---|---|---|---|---|---|---|---|
+| **ValkeyConnector** (32 workers) | Provisioned | No | 64k | 15,555ms | **3,216ms** | **4.8×** | 0.89–0.98 GB/s | ~7.5 GB/s |
+| **ValkeyConnector** (32 workers) | Serverless | Yes | 64k | 15,987ms | **3,425ms** | **4.7×** | 0.85–0.89 GB/s | ~6.9 GB/s |
+| **ValkeyConnector** (32 workers) | Provisioned | No | 8k | 2,224ms | **505ms** | **4.4×** | — | — |
+| **ValkeyConnector** (32 workers) | Serverless | Yes | 8k | 2,274ms | **656ms** | **3.5×** | — | — |
+| RedisClusterConnector | Provisioned | No | 64k | 15,612ms | 5,794ms | 2.7× | 0.47–0.52 GB/s | ~4.0 GB/s |
+| RedisClusterConnector | Provisioned | No | 8k | 2,361ms | 796ms | 3.0× | — | — |
+
+### 70B Model — 4 MB Chunks (chunk_size=96)
+
+| Connector | Backend | TLS | Context | L2 TTFT | Speedup | Per-rank | Aggregate |
+|---|---|---|---|---|---|---|---|
+| **ValkeyConnector** (32 workers) | Provisioned | No | 64k | 3,644ms | 4.5× | 0.87–0.93 GB/s | ~7.1 GB/s |
+| **ValkeyConnector** (32 workers) | Serverless | Yes | 64k | 3,884ms | 4.3× | 0.87–0.93 GB/s | ~6.9 GB/s |
+| **ValkeyConnector** (64 workers) | Provisioned | No | 64k | 4,134ms | 3.9× | 0.74–0.92 GB/s | ~6.6 GB/s |
+| RedisClusterConnector | Provisioned | No | 64k | 6,392ms | 2.3× | 0.46–0.58 GB/s | ~4.1 GB/s |
+
+### 8B Model (TP=1, Provisioned, 4 MB chunks)
+
+| Connector | Context | Cold TTFT | L2 TTFT | Speedup | keyspace_hits Δ |
+|---|---|---|---|---|---|
+| **ValkeyConnector** (32 workers) | 8k | 803ms | **421ms** | **1.9×** | +64 |
+| **ValkeyConnector** (32 workers) | 64k | 11,487ms | **2,527ms** | **4.5×** | +508 |
+| RedisClusterConnector | 8k | 1,789ms | 1,859ms | 1.0× | +96 |
+| RedisClusterConnector | 64k | 13,189ms | 15,600ms | **0.8×** ❌ | +762 |
+
+## Analysis
+
+### Why ValkeyConnector Is Faster Than RedisClusterConnector
+
+1. **1 GET vs 2 GETs per chunk.** ValkeyConnector stores each chunk as a single key. RedisClusterConnector splits into `metadata` + `kv_bytes`, requiring two round-trips. Confirmed by `keyspace_hits`: +508 (ValkeyConnector) vs +762 (RedisClusterConnector) for 8B 64k — exactly 1.5× more GETs.
+
+2. **32 parallel worker threads with independent clients.** Each worker thread has its own GLIDE client with its own connection pool. The GIL is released during Rust FFI calls, enabling true parallel I/O. RedisClusterConnector uses `redis-py`'s async client behind an asyncio semaphore.
+
+3. **Zero-copy buffer GET.** GLIDE writes directly into pinned CPU memory via `buffer=memoryview`, avoiding an intermediate allocation + copy. RedisClusterConnector receives bytes from `redis-py` and copies into the memory object.
+
+4. **Cluster-native slot routing.** GLIDE's cluster client maintains persistent connections to all cluster nodes and routes commands by slot internally. No client-side hash slot computation or redirect handling.
+
+### TLS Overhead
+
+| Context | Provisioned (no TLS) | Serverless (TLS) | Overhead |
+|---|---|---|---|
+| 64k | 3,216ms | 3,425ms | **+6.5%** |
+| 8k | 505ms | 656ms | **+30%** |
+
+TLS overhead is negligible at 64k because the data transfer dominates. At 8k the fixed TLS handshake/encryption cost is a larger fraction of the smaller transfer.
+
+### Chunk Size Impact
+
+| Chunk Size | L2 TTFT (provisioned, 64k) | Speedup |
+|---|---|---|
+| 10 MB (chunk_size=256) | 3,216ms | 4.8× |
+| 4 MB (chunk_size=96) | 3,644ms | 4.5× |
+
+10 MB chunks are only **13% faster** than 4 MB. Fewer chunks means fewer round-trips, but the difference is modest with low per-request overhead.
+
+### Worker Count
+
+| Workers | L2 TTFT (4 MB chunks, provisioned, 64k) | Per-rank |
+|---|---|---|
+| 32 | 3,644ms | 0.87–0.93 GB/s |
+| 64 | 4,134ms | 0.74–0.92 GB/s |
+
+32 workers is the sweet spot for 70B TP=8. 64 workers adds contention without improving throughput.
+
+### 8B Model: RedisClusterConnector Overhead
+
+On 8B at 64k, RedisClusterConnector's L2 TTFT (15,600ms) exceeds cold compute time (13,189ms), meaning the 2-key storage overhead outweighs the caching benefit at this model size. The `keyspace_hits` delta confirms the cause: 762 GETs (RedisClusterConnector) vs 508 GETs (ValkeyConnector) for the same data — 1.5× more round-trips. ValkeyConnector's single-key storage avoids this and delivers a 4.5× speedup on the same workload.
+
+## Key Takeaways
+
+1. **ValkeyConnector is 1.6–1.8× faster than RedisClusterConnector** across all models and context lengths, due to single-key storage and parallel worker threads.
+2. **TLS overhead is 7–8%** at 64k — serverless ElastiCache is viable for production.
+3. **Chunk size matters less than expected** — 10 MB is only 13% faster than 4 MB.
+4. **32 workers is optimal** for 70B TP=8; more threads add contention.
+5. **RedisClusterConnector's 2-key storage becomes a bottleneck on smaller models** — the extra round-trips per chunk can negate the benefit of caching entirely.
+
+## LMCache Configs Used
+
+```yaml
+# ValkeyConnector — provisioned cluster
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 5.0
+remote_url: "valkey://<cluster-endpoint>:6379"
+remote_serde: "naive"
+blocking_timeout_secs: 120
+pre_caching_hash_algorithm: sha256_cbor_64bit
+extra_config:
+  valkey_num_workers: 32
+  valkey_mode: "cluster"
+```
+
+```yaml
+# ValkeyConnector — serverless TLS
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 5.0
+remote_url: "valkey://<serverless-endpoint>:6379"
+remote_serde: "naive"
+blocking_timeout_secs: 120
+pre_caching_hash_algorithm: sha256_cbor_64bit
+extra_config:
+  valkey_num_workers: 32
+  valkey_mode: "cluster"
+  tls_enable: true
+```
+
+### vLLM Launch Command
+
+```bash
+export LMCACHE_CONFIG_FILE=/home/ubuntu/valkey_cluster.yaml
+
+vllm serve meta-llama/Llama-3.1-70B-Instruct \
+  --tensor-parallel-size 8 \
+  --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}' \
+  --no-enable-log-requests \
+  --no-enable-prefix-caching \
+  --gpu-memory-utilization 0.90 \
+  --max-model-len 65536
+```
diff --git a/examples/kv_cache_reuse/remote_backends/valkey/benchmark_l2.py b/examples/kv_cache_reuse/remote_backends/valkey/benchmark_l2.py
new file mode 100644
index 0000000..e002c14
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/valkey/benchmark_l2.py
@@ -0,0 +1,304 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+End-to-end L2 benchmark for LMCache with vLLM.
+
+Solves the 64k L2 eviction problem from the 12-March benchmark session:
+flood prompts that share a prefix with the test prompt produce identical
+chunk hashes (rolling prefix hashes), so LRU never evicts the overlapping
+chunks.  This script generates flood prompts with **completely disjoint
+token content** to guarantee different chunk hashes and full L1 eviction.
+
+Usage (run from the benchmark EC2 instance):
+
+    # Generate prompts + flood files (one-time)
+    python benchmark_l2.py generate \
+        --model meta-llama/Llama-3.1-70B-Instruct \
+        --context-tokens 65536 \
+        --num-floods 3 \
+        --output-dir /home/ubuntu/bench_prompts
+
+    # Run the full benchmark (cold → flood → L2)
+    python benchmark_l2.py run \
+        --prompt-dir /home/ubuntu/bench_prompts \
+        --vllm-url http://localhost:8000 \
+        --valkey-nodes <node1>,<node2>,<node3> \
+        --valkey-port 6379
+
+Requirements:
+    - vLLM running with LMCacheConnectorV1
+    - transformers (for tokenizer)
+    - redis-py (for keyspace_hits checking)
+"""
+
+# Standard
+from pathlib import Path
+import argparse
+import json
+import random
+import string
+import sys
+import time
+
+# Third Party
+import requests
+
+
+def _random_text(num_chars: int, seed: int) -> str:
+    """Generate random ASCII text that tokenizes to unique tokens.
+
+    Uses distinct vocabulary per seed so that no two generated texts
+    share a token-level prefix, which would produce identical rolling
+    chunk hashes in LMCache.
+    """
+    rng = random.Random(seed)
+    # Mix words of varying length to get dense, unique tokenization.
+    # Each "word" is 3-10 random lowercase chars followed by a space.
+    parts = []
+    written = 0
+    while written < num_chars:
+        word_len = rng.randint(3, 10)
+        word = "".join(rng.choices(string.ascii_lowercase, k=word_len))
+        parts.append(word)
+        written += word_len + 1  # +1 for space
+    return " ".join(parts)[:num_chars]
+
+
+def _make_prompt_payload(
+    text: str,
+    model: str,
+    max_tokens: int = 1,
+) -> dict:
+    """Build an OpenAI-compatible /v1/completions payload."""
+    return {
+        "model": model,
+        "prompt": text,
+        "max_tokens": max_tokens,
+        "temperature": 0,
+    }
+
+
+def cmd_generate(args):
+    """Generate test prompt and disjoint flood prompts."""
+    # Third Party
+    from transformers import AutoTokenizer
+
+    out = Path(args.output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    print(f"Loading tokenizer for {args.model}...")
+    tokenizer = AutoTokenizer.from_pretrained(args.model)
+
+    target_tokens = args.context_tokens
+
+    # We over-generate text and then truncate to exactly target_tokens
+    # after tokenization.  Factor of 6 chars/token is conservative.
+    chars_estimate = target_tokens * 6
+
+    # ── Test prompt ──
+    print(f"Generating test prompt (~{target_tokens} tokens)...")
+    test_text = _random_text(chars_estimate, seed=42)
+    test_ids = tokenizer.encode(test_text, add_special_tokens=False)
+    test_ids = test_ids[:target_tokens]
+    test_text_truncated = tokenizer.decode(test_ids)
+    actual_tokens = len(tokenizer.encode(test_text_truncated, add_special_tokens=False))
+    print(f"  Test prompt: {actual_tokens} tokens")
+
+    payload = _make_prompt_payload(test_text_truncated, args.model)
+    test_path = out / "prompt.json"
+    test_path.write_text(json.dumps(payload, ensure_ascii=False))
+    print(f"  Saved: {test_path}")
+
+    # ── Flood prompts (completely disjoint content) ──
+    for i in range(args.num_floods):
+        # Use seeds far apart from test (42) and from each other
+        seed = 1000 + i * 1000
+        print(f"Generating flood prompt {i + 1}/{args.num_floods} (seed={seed})...")
+        flood_text = _random_text(chars_estimate, seed=seed)
+        flood_ids = tokenizer.encode(flood_text, add_special_tokens=False)
+        flood_ids = flood_ids[:target_tokens]
+        flood_text_truncated = tokenizer.decode(flood_ids)
+        flood_tokens = len(
+            tokenizer.encode(flood_text_truncated, add_special_tokens=False)
+        )
+        print(f"  Flood {i + 1}: {flood_tokens} tokens")
+
+        # Verify zero prefix overlap at the token level
+        test_first_chunk = test_ids[:256]
+        flood_first_chunk = flood_ids[:256]
+        if test_first_chunk == flood_first_chunk:
+            print(
+                "  WARNING: first chunk matches test prompt! Retrying with "
+                "different seed would be needed."
+            )
+        else:
+            overlap = 0
+            for a, b in zip(test_ids, flood_ids, strict=False):
+                if a != b:
+                    break
+                overlap += 1
+            print(
+                f"  Token prefix overlap with test: {overlap} "
+                f"(< chunk_size=256 → OK, different chunk hashes)"
+            )
+
+        flood_payload = _make_prompt_payload(flood_text_truncated, args.model)
+        flood_path = out / f"flood_{i + 1}.json"
+        flood_path.write_text(json.dumps(flood_payload, ensure_ascii=False))
+        print(f"  Saved: {flood_path}")
+
+    print(f"\nAll prompts saved to {out}/")
+    print(f"  prompt.json        — test prompt ({actual_tokens} tokens)")
+    for i in range(args.num_floods):
+        print(f"  flood_{i + 1}.json      — flood prompt (disjoint content)")
+
+
+def _get_keyspace_hits(nodes: list[str], port: int) -> tuple[int, list[int]]:
+    """Query keyspace_hits from all Valkey/Redis cluster nodes."""
+    # Third Party
+    import redis
+
+    per_node = []
+    for node in nodes:
+        try:
+            r = redis.Redis(host=node, port=port, socket_timeout=5)
+            info = r.info("stats")
+            hits = info.get("keyspace_hits", 0)
+            per_node.append(hits)
+            r.close()
+        except Exception as e:
+            print(f"  WARNING: could not reach {node}:{port} — {e}")
+            per_node.append(-1)
+    total = sum(h for h in per_node if h >= 0)
+    return total, per_node
+
+
+def _send_request(url: str, payload_path: Path, timeout: int = 600) -> float:
+    """Send a completion request and return wall-clock time in ms."""
+    payload = json.loads(payload_path.read_text())
+    t0 = time.perf_counter()
+    resp = requests.post(
+        f"{url}/v1/completions",
+        json=payload,
+        timeout=timeout,
+    )
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    resp.raise_for_status()
+    return elapsed_ms
+
+
+def cmd_run(args):
+    """Run the full L2 benchmark: cold → flood → L2 retrieval."""
+    prompt_dir = Path(args.prompt_dir)
+    prompt_path = prompt_dir / "prompt.json"
+    if not prompt_path.exists():
+        print(f"ERROR: {prompt_path} not found. Run 'generate' first.")
+        sys.exit(1)
+
+    flood_paths = sorted(prompt_dir.glob("flood_*.json"))
+    if not flood_paths:
+        print(f"ERROR: no flood_*.json found in {prompt_dir}. Run 'generate' first.")
+        sys.exit(1)
+
+    nodes = [n.strip() for n in args.valkey_nodes.split(",") if n.strip()]
+    url = args.vllm_url.rstrip("/")
+
+    print(f"Prompt: {prompt_path}")
+    print(f"Floods: {[p.name for p in flood_paths]}")
+    print(f"Valkey nodes: {nodes}")
+    print(f"vLLM: {url}")
+    print()
+
+    # ── Step 1: Cold request (compute + store to L1 + L2) ──
+    print("=== Step 1: Cold request (store to L1 + L2) ===")
+    cold_ms = _send_request(url, prompt_path)
+    print(f"  Cold TTFT: {cold_ms:.0f}ms")
+    time.sleep(3)
+
+    # ── Step 2: Flood L1 with disjoint prompts ──
+    print(f"\n=== Step 2: Flood L1 ({len(flood_paths)} disjoint prompts) ===")
+    for fp in flood_paths:
+        print(f"  Sending {fp.name}...", end="", flush=True)
+        flood_ms = _send_request(url, fp)
+        print(f" {flood_ms:.0f}ms")
+        time.sleep(1)
+    time.sleep(3)
+
+    # ── Step 3: Record keyspace_hits before L2 ──
+    print("\n=== Step 3: Check keyspace_hits (before L2) ===")
+    before_total, before_per_node = _get_keyspace_hits(nodes, args.valkey_port)
+    print(f"  TOTAL hits: {before_total}  per-node: {before_per_node}")
+
+    # ── Step 4: L2 retrieval ──
+    print("\n=== Step 4: L2 retrieval (same prompt, L1 should be evicted) ===")
+    l2_ms = _send_request(url, prompt_path)
+    print(f"  L2 Hit TTFT: {l2_ms:.0f}ms")
+    time.sleep(1)
+
+    # ── Step 5: Record keyspace_hits after L2 ──
+    print("\n=== Step 5: Check keyspace_hits (after L2) ===")
+    after_total, after_per_node = _get_keyspace_hits(nodes, args.valkey_port)
+    print(f"  TOTAL hits: {after_total}  per-node: {after_per_node}")
+
+    delta = after_total - before_total
+    delta_per_node = [
+        a - b
+        for a, b in zip(after_per_node, before_per_node, strict=True)
+        if a >= 0 and b >= 0
+    ]
+    print(f"\n  keyspace_hits Δ: +{delta} (per-node: {delta_per_node})")
+
+    # ── Verdict ──
+    print("\n" + "=" * 60)
+    if delta > 0:
+        print("✓ L2 RETRIEVAL CONFIRMED")
+        print(f"  Cold TTFT:   {cold_ms:.0f}ms")
+        print(f"  L2 Hit TTFT: {l2_ms:.0f}ms")
+        print(f"  Speedup:     {cold_ms / l2_ms:.1f}x")
+        print(f"  keyspace_hits Δ: +{delta}")
+    else:
+        print("✗ L2 RETRIEVAL NOT DETECTED (keyspace_hits unchanged)")
+        print("  The L1 cache was likely not fully evicted.")
+        print("  Possible causes:")
+        print("    - max_local_cpu_size too large (floods fit alongside test data)")
+        print("    - Not enough flood prompts to fill L1")
+        print("    - Flood prompts share prefix with test prompt")
+    print("=" * 60)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="End-to-end L2 benchmark for LMCache + vLLM"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ── generate ──
+    gen = sub.add_parser("generate", help="Generate test + flood prompts")
+    gen.add_argument("--model", required=True, help="HF model name for tokenizer")
+    gen.add_argument("--context-tokens", type=int, default=65536)
+    gen.add_argument(
+        "--num-floods", type=int, default=3, help="Number of disjoint flood prompts"
+    )
+    gen.add_argument("--output-dir", required=True)
+
+    # ── run ──
+    run = sub.add_parser("run", help="Run the L2 benchmark")
+    run.add_argument(
+        "--prompt-dir",
+        required=True,
+        help="Directory with prompt.json and flood_*.json",
+    )
+    run.add_argument("--vllm-url", default="http://localhost:8000")
+    run.add_argument(
+        "--valkey-nodes", required=True, help="Comma-separated Valkey cluster node IPs"
+    )
+    run.add_argument("--valkey-port", type=int, default=6379)
+
+    args = parser.parse_args()
+    if args.command == "generate":
+        cmd_generate(args)
+    elif args.command == "run":
+        cmd_run(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/kv_cache_reuse/remote_backends/valkey/valkey.yaml b/examples/kv_cache_reuse/remote_backends/valkey/valkey.yaml
new file mode 100644
index 0000000..586ddba
--- /dev/null
+++ b/examples/kv_cache_reuse/remote_backends/valkey/valkey.yaml
@@ -0,0 +1,9 @@
+chunk_size: 256
+local_cpu: true
+max_local_cpu_size: 5.0
+remote_url: "valkey://<cluster-endpoint>:6379"
+remote_serde: "naive"
+pre_caching_hash_algorithm: sha256_cbor_64bit
+extra_config:
+  valkey_num_workers: 32
+  valkey_mode: "cluster"
diff --git a/examples/kv_cache_reuse/share_across_instances/README.md b/examples/kv_cache_reuse/share_across_instances/README.md
new file mode 100644
index 0000000..82b4a53
--- /dev/null
+++ b/examples/kv_cache_reuse/share_across_instances/README.md
@@ -0,0 +1,7 @@
+# Examples of across-instance KV cache sharing with vLLM + LMCache
+LMCache should be able to reduce the generation time of the second and following calls.
+
+We have examples for the following types of across-instance KV cache sharing:
+
+- KV cache sharing through a centralized cache server: `centralized_sharing/`
+- KV cache sharing through p2p cache transfer: `p2p_sharing/`
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/share_across_instances/centralized_sharing/README.md b/examples/kv_cache_reuse/share_across_instances/centralized_sharing/README.md
new file mode 100644
index 0000000..8648ff4
--- /dev/null
+++ b/examples/kv_cache_reuse/share_across_instances/centralized_sharing/README.md
@@ -0,0 +1,51 @@
+# Sharing KV cache across multiple vLLM instances
+This shows how to share KV across different vLLM instances using LMCache.  
+## Prerequisites
+Your server should have at least 2 GPUs.  
+
+This will use the port 8000 and 8001 (for vLLM) and port 65432 (for LMCache).  
+
+**Important**: For centralized cache sharing (which is cross-process cases), ensure all processes use the same `PYTHONHASHSEED` to keep the hash of the KV cache consistent across processes.:
+```bash
+export PYTHONHASHSEED=0
+```
+
+## Steps
+1.  Start the lmcache centralized server,
+```bash
+lmcache_server localhost 65432
+```  
+2. In a different terminal,  
+```bash
+export PYTHONHASHSEED=0
+
+LMCACHE_CONFIG_FILE=example.yaml CUDA_VISIBLE_DEVICES=0 vllm serve mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8000 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```  
+In another terminal,   
+```bash
+export PYTHONHASHSEED=0
+
+LMCACHE_CONFIG_FILE=example.yaml CUDA_VISIBLE_DEVICES=1 vllm serve mistralai/Mistral-7B-Instruct-v0.2 --gpu-memory-utilization 0.8 --port 8001 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```  
+Wait until both of the engines are ready.
+
+3.  Send one request to the engine at port 8000,
+```bash
+curl -X POST http://localhost:8000/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
+4. Send the same request to the engine at port 8001,
+```bash
+curl -X POST http://localhost:8001/v1/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "meta-llama/Meta-Llama-3.1-8B-Instruct",
+    "prompt": "Explain the significance of KV cache in language models.",
+    "max_tokens": 10
+  }'
+```
\ No newline at end of file
diff --git a/examples/kv_cache_reuse/share_across_instances/centralized_sharing/example.yaml b/examples/kv_cache_reuse/share_across_instances/centralized_sharing/example.yaml
new file mode 100644
index 0000000..cd8935d
--- /dev/null
+++ b/examples/kv_cache_reuse/share_across_instances/centralized_sharing/example.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_cpu: True
+remote_url: "lm://localhost:65432"
+remote_serde: "cachegen"
diff --git a/examples/kv_cache_reuse/share_across_instances/p2p_sharing/README.md b/examples/kv_cache_reuse/share_across_instances/p2p_sharing/README.md
new file mode 100644
index 0000000..4859b9d
--- /dev/null
+++ b/examples/kv_cache_reuse/share_across_instances/p2p_sharing/README.md
@@ -0,0 +1,55 @@
+# P2P KV Cache Sharing
+This is an example to demonstrate P2P KV cache sharing.
+## Prerequisites
+Your server should have at least 2 GPUs.
+[NIXL](https://github.com/ai-dynamo/nixl) should be installed as well. 
+
+The LMCache controller will use port 8300 to pull messages from LMCache workers and port 8400 to reply requests to LMCache workers.
+
+The two LMCache workers will use the port 8010 and 8011 for 2 vllms, port 8200 and 8202 for p2p initializations, and port 8201 and 8203 for p2p lookups.
+
+## Steps
+1. Start the LMCache controller:
+```bash
+PYTHONHASHSEED=123 lmcache_controller --host localhost --port 9000 --monitor-ports '{"pull": 8300, "reply": 8400}'
+``` 
+
+2. Start two vllm engines (each with an LMCache worker):
+
+Start vllm engine 1 at port 8010:
+```bash
+PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=0 LMCACHE_CONFIG_FILE=example1.yaml vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct --gpu-memory-utilization 0.8 --port 8010 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'
+```
+Start vllm engine 2 at port 8011:
+```bash
+PYTHONHASHSEED=123 UCX_TLS=rc CUDA_VISIBLE_DEVICES=1 LMCACHE_CONFIG_FILE=example2.yaml vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct  --gpu-memory-utilization 0.8 --port 8011 --kv-transfer-config '{"kv_connector":"LMCacheConnectorV1", "kv_role":"kv_both"}'  
+```
+
+
+3. Send request to vllm engine 1:  
+```bash
+curl -X POST http://localhost:8010/v1/completions \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
+    \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+    \"max_tokens\": 10
+  }"
+```
+
+4. Send request to vllm engine 2:  
+```bash
+curl -X POST http://localhost:8011/v1/completions \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"model\": \"meta-llama/Meta-Llama-3.1-8B-Instruct\",
+    \"prompt\": \"$(printf 'Explain the significance of KV cache in language models.%.0s' {1..100})\",
+    \"max_tokens\": 10
+  }"
+```
+The cache will be automatically retrieved from vllm engine 1.
+You should be able to see logs (from vllm engine 2) like the following:
+```bash
+(EngineCore_DP0 pid=2577584)[2025-09-21 00:00:11,706] LMCache INFO: Established connection to peer_init_url localhost:8200. The peer_lookup_url: localhost:8201 (p2p_backend.py:278:lmcache.v1.storage_backend.p2p_backend)
+(EngineCore_DP0 pid=2577584)[2025-09-21 00:00:11,792] LMCache INFO: Retrieved 1002 out of total 1002 out of total 1002 tokens. size: 0.1223 gb, cost 60.3595 ms, throughput: 2.0264 GB/s; (cache_engine.py:496:lmcache.v1.cache_engine)
+```
diff --git a/examples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml b/examples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml
new file mode 100644
index 0000000..b20fe18
--- /dev/null
+++ b/examples/kv_cache_reuse/share_across_instances/p2p_sharing/example1.yaml
@@ -0,0 +1,24 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+enable_async_loading: True
+
+# P2P configurations
+enable_p2p: True
+p2p_host: "localhost"
+p2p_init_ports: 8200
+p2p_lookup_ports: 8201
+transfer_channel: "nixl"
+
+# Controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_instance_1"
+controller_pull_url: "localhost:8300"
+controller_reply_url: "localhost:8400"
+lmcache_worker_ports: 8500
+
+extra_config:
+  lookup_backoff_time: 0.001
+  # P2P backend timeout configurations (optional, defaults shown)
+  p2p_socket_recv_timeout_ms: 30000  # Socket receive timeout in milliseconds
+  p2p_socket_send_timeout_ms: 10000  # Socket send timeout in milliseconds
diff --git a/examples/kv_cache_reuse/share_across_instances/p2p_sharing/example2.yaml b/examples/kv_cache_reuse/share_across_instances/p2p_sharing/example2.yaml
new file mode 100644
index 0000000..99d71a8
--- /dev/null
+++ b/examples/kv_cache_reuse/share_across_instances/p2p_sharing/example2.yaml
@@ -0,0 +1,21 @@
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+enable_async_loading: True
+
+# P2P configurations
+enable_p2p: True
+p2p_host: "localhost"
+p2p_init_ports: 8202
+p2p_lookup_ports: 8203
+transfer_channel: "nixl"
+
+# Controller configurations
+enable_controller: True
+lmcache_instance_id: "lmcache_instance_2"
+controller_pull_url: "localhost:8300"
+controller_reply_url: "localhost:8400"
+lmcache_worker_ports: 8501
+
+extra_config:
+  lookup_backoff_time: 0.001
\ No newline at end of file
diff --git a/examples/kvcache_sdk/README.md b/examples/kvcache_sdk/README.md
new file mode 100644
index 0000000..2120b56
--- /dev/null
+++ b/examples/kvcache_sdk/README.md
@@ -0,0 +1,56 @@
+# KV Cache SDK Examples
+
+These examples show how to use the Python SDK to store and retrieve
+KV cache tensors through the LMCache MP HTTP API. The SDK path is memory-first:
+applications can retrieve a tensor, pair it with new token metadata, and store
+it again without writing the tensor through a local storage format. Store will
+return False if LMCache already have the KV Cache with the same token sequence.
+
+## End-to-end vLLM flow
+
+First, start up the vLLM and LMCache server by running commands listed in the
+first cell of `e2e_kv_edit.ipynb`.
+
+Then, starting from cell 2 of `e2e_kv_edit.ipynb`, it is doing below experiment
+flow:
+1. Send a source prompt to vLLM so the normal connector stores KV in LMCache.
+2. Retrieve the source KV cache into an in-memory tensor with `retrieve()`.
+3. Build a target token-ID prompt: the same length as the source prompt and
+   identical apart from a few different synthetic leading tokens.
+4. Store the source KV under the target prefix with `store()`.
+5. Send the target token IDs to vLLM so the target prefix hits the remapped KV.
+6. Print retrieve counts, latencies, response previews, and whether the source
+   and target outputs match.
+
+The target prompt starts with different token IDs, so it does not rely on a
+serving-engine local prefix match. Because the prompts are identical apart from
+those leading tokens, reusing the source KV reconstructs the same final context
+for the target request, which should produce the same deterministic output.
+
+The core SDK pattern used by the end-to-end example is:
+
+```python
+import lmcache.sdk.kvcache as lmc_sdk
+
+ctx = lmc_sdk.connect(
+    url="tcp://localhost:6555",        # ZMQ message queue
+    http_url="http://localhost:8080",  # HTTP config / status
+    model_name="...",
+)
+
+kv = lmc_sdk.retrieve(ctx, tokens=source_tokens)
+if kv is not None:
+    lmc_sdk.store(ctx, kv=kv, tokens=target_tokens)
+
+lmc_sdk.close(ctx)
+```
+
+### Requirements
+
+- An LMCache MP server running with HTTP enabled.
+- A model already registered with that server. Check `/status` for the
+  registered `model_name`, `chunk_size`, layer count, dtype, and hidden dim.
+- A homogeneous `KV_2LTD` layout.
+
+Use `--cache-salt` on all commands when storing and retrieving from a
+non-default namespace.
diff --git a/examples/kvcache_sdk/e2e_kv_edit.ipynb b/examples/kvcache_sdk/e2e_kv_edit.ipynb
new file mode 100644
index 0000000..6ffbed0
--- /dev/null
+++ b/examples/kvcache_sdk/e2e_kv_edit.ipynb
@@ -0,0 +1,423 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1cd06b97",
+   "metadata": {},
+   "source": [
+    "## Setup vLLM and LMCache server\n",
+    "Follow below instructions (1-4), then proceed to below Python cell.\n",
+    "1. Start LMCache server first\n",
+    "```sh\n",
+    "lmcache server \\\n",
+    "    --l1-size-gb 8 \\\n",
+    "    --eviction-policy LRU \\\n",
+    "    --chunk-size 256 \\\n",
+    "    --port 6555 \\\n",
+    "    --http-port 8080 \\\n",
+    "    --shm-name lmcache_kvcache_sdk_e2e \\\n",
+    "    --no-l1-use-lazy\n",
+    "```\n",
+    "2. Wait until LMCache server is ready\n",
+    "```sh\n",
+    "curl -sf http://localhost:8080/healthcheck && echo \" LMCache ready\"\n",
+    "```\n",
+    "3. Start vLLM once LMCache server is ready\n",
+    "```sh\n",
+    "env -u VLLM_PORT \\\n",
+    "    CUDA_VISIBLE_DEVICES=0 \\\n",
+    "    VLLM_ENABLE_V1_MULTIPROCESSING=0 \\\n",
+    "    VLLM_BATCH_INVARIANT=1 \\\n",
+    "    PYTHONHASHSEED=0 \\\n",
+    "    vllm serve Qwen/Qwen3-8B \\\n",
+    "    --port 8000 \\\n",
+    "    --served-model-name Qwen/Qwen3-8B \\\n",
+    "    --no-enable-prefix-caching \\\n",
+    "    --enforce-eager \\\n",
+    "    --max-model-len 4096 \\\n",
+    "    --gpu-memory-utilization 0.6 \\\n",
+    "    --kv-transfer-config '{\"kv_connector\":\"LMCacheMPConnector\",\"kv_role\":\"kv_both\",\"kv_load_failure_policy\":\"recompute\",\"kv_connector_extra_config\":{\"lmcache.mp.host\":\"tcp://localhost\",\"lmcache.mp.port\":6555,\"lmcache.mp.mq_timeout\":10}}' \\\n",
+    "    --override-generation-config '{\"temperature\": 0}' \\\n",
+    "    --trust-remote-code\n",
+    "```\n",
+    "4. Wait until vLLM is ready\n",
+    "```sh\n",
+    "curl -sf http://localhost:8000/v1/models && echo \" vLLM ready\"\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c2d81202",
+   "metadata": {},
+   "source": [
+    "## Run E2E KV Edit Example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "aa87a653",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/home/rani/LMCache/.venv/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+      "  from .autonotebook import tqdm as notebook_tqdm\n",
+      "\u001b[32;20m[2026-06-23 23:26:41,202] LMCache INFO:\u001b[0m  torch_dev=<module 'torch.cuda' from '/home/rani/LMCache/.venv/lib/python3.12/site-packages/torch/cuda/__init__.py'>, torch_device_type=cuda \u001b[3m(__init__.py:62:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:41,267] LMCache INFO:\u001b[0m Skipping backend lmcache.v1.platform.musa.ops: predicate returned False \u001b[3m(__init__.py:102:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:41,268] LMCache INFO:\u001b[0m Skipping backend lmcache.xpu_ops: predicate returned False \u001b[3m(__init__.py:102:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:41,269] LMCache INFO:\u001b[0m Using backend: lmcache.c_ops \u001b[3m(__init__.py:120:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:41,604] LMCache INFO:\u001b[0m multi_layer_block_kv_transfer mode: ptr \u001b[3m(base.py:94:lmcache.v1.multiprocess.transfer_context.base)\u001b[0m\n"
+     ]
+    }
+   ],
+   "source": [
+    "# SPDX-License-Identifier: Apache-2.0\n",
+    "\"\"\"End-to-end KV cache remapping driver for the SDK example.\"\"\"\n",
+    "\n",
+    "# Standard\n",
+    "from dataclasses import dataclass\n",
+    "from itertools import islice\n",
+    "import json\n",
+    "import time\n",
+    "from typing import cast\n",
+    "\n",
+    "# Third Party\n",
+    "import httpx\n",
+    "from transformers import AutoTokenizer, PreTrainedTokenizerBase\n",
+    "\n",
+    "# First Party\n",
+    "import lmcache.sdk.kvcache as lmc_sdk"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "8f1065b0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_name = \"Qwen/Qwen3-8B\"\n",
+    "vllm_url = \"http://localhost:8000\"\n",
+    "lmcache_url = \"http://localhost:8080\"\n",
+    "lmcache_mq_url = \"tcp://localhost:6555\"\n",
+    "chunk_size = 256\n",
+    "min_prompt_tokens = chunk_size * 2\n",
+    "fake_prefix_tokens = 32\n",
+    "max_tokens = 32\n",
+    "timeout = 60  # seconds\n",
+    "trust_remote_code = True"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "f894f55b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@dataclass(frozen=True)\n",
+    "class CompletionResult:\n",
+    "    \"\"\"Text and latency returned by one OpenAI-compatible completion call.\"\"\"\n",
+    "\n",
+    "    text: str\n",
+    "    elapsed_seconds: float\n",
+    "\n",
+    "\n",
+    "def _post_completion(\n",
+    "    *,\n",
+    "    vllm_url: str,\n",
+    "    model_name: str,\n",
+    "    prompt: str | list[int],\n",
+    "    max_tokens: int,\n",
+    "    timeout: float,\n",
+    ") -> CompletionResult:\n",
+    "    \"\"\"Send one non-streaming completion request to vLLM.\"\"\"\n",
+    "    payload = {\n",
+    "        \"model\": model_name,\n",
+    "        \"prompt\": prompt,\n",
+    "        \"max_tokens\": max_tokens,\n",
+    "        \"min_tokens\": max_tokens,\n",
+    "        \"temperature\": 0,\n",
+    "        \"seed\": 0,\n",
+    "        \"ignore_eos\": True,\n",
+    "    }\n",
+    "    start = time.perf_counter()\n",
+    "    response = httpx.post(\n",
+    "        f\"{vllm_url.rstrip('/')}/v1/completions\",\n",
+    "        json=payload,\n",
+    "        timeout=timeout,\n",
+    "    )\n",
+    "    elapsed = time.perf_counter() - start\n",
+    "    response.raise_for_status()\n",
+    "    body = response.json()\n",
+    "    choices = body.get(\"choices\")\n",
+    "    if not isinstance(choices, list) or not choices:\n",
+    "        raise RuntimeError(f\"completion response missing choices: {body}\")\n",
+    "    first_choice = choices[0]\n",
+    "    if not isinstance(first_choice, dict) or not isinstance(\n",
+    "        first_choice.get(\"text\"), str\n",
+    "    ):\n",
+    "        raise RuntimeError(f\"completion response has invalid choice: {body}\")\n",
+    "    return CompletionResult(text=first_choice[\"text\"], elapsed_seconds=elapsed)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4cd588ce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "SOURCE_PARAGRAPH = (\n",
+    "    \"A systems researcher is studying how an inference cache changes the \"\n",
+    "    \"latency profile of a long language model prompt. The notes discuss \"\n",
+    "    \"attention keys, attention values, memory tiers, token chunks, and the \"\n",
+    "    \"careful measurement of cold and warm requests.\"\n",
+    ")\n",
+    "\n",
+    "\n",
+    "def _build_prompts(\n",
+    "    tokenizer: PreTrainedTokenizerBase,\n",
+    "    *,\n",
+    "    min_prompt_tokens: int,\n",
+    "    chunk_size: int,\n",
+    "    fake_prefix_tokens: int,\n",
+    ") -> tuple[list[int], list[int], int]:\n",
+    "    \"\"\"Build equal-length source/target prompts and the cached-prefix length.\n",
+    "    The prompts differ only in ``fake_prefix_tokens`` synthetic leading token IDs.\"\"\"\n",
+    "    if not 0 < fake_prefix_tokens < chunk_size:\n",
+    "        raise ValueError(\n",
+    "            f\"fake_prefix_tokens must be in (0, {chunk_size}), got {fake_prefix_tokens}\"\n",
+    "        )\n",
+    "    min_cache = max(1, min_prompt_tokens - fake_prefix_tokens)\n",
+    "    cache_tokens = ((min_cache + chunk_size - 1) // chunk_size) * chunk_size\n",
+    "\n",
+    "    # Two distinct, non-special lead IDs for the source/target prefixes.\n",
+    "    special = {int(t) for t in tokenizer.all_special_ids}\n",
+    "    candidates = (t for t in range(1000, int(tokenizer.vocab_size)) if t not in special)\n",
+    "    leads = list(islice(candidates, 2))\n",
+    "    if len(leads) < 2:\n",
+    "        raise ValueError(\"could not find two usable non-special token IDs\")\n",
+    "    source_lead, target_lead = leads\n",
+    "\n",
+    "    # Repeat the paragraph until it covers the suffix, then take the trailing slice.\n",
+    "    suffix_len = cache_tokens - fake_prefix_tokens\n",
+    "    text = SOURCE_PARAGRAPH\n",
+    "    suffix = tokenizer.encode(text, add_special_tokens=False)\n",
+    "    while len(suffix) < suffix_len:\n",
+    "        text = f\"{text}\\n\\n{SOURCE_PARAGRAPH}\"\n",
+    "        suffix = tokenizer.encode(text, add_special_tokens=False)\n",
+    "    suffix = [int(t) for t in suffix[-suffix_len:]]\n",
+    "\n",
+    "    source = [source_lead] * fake_prefix_tokens + suffix\n",
+    "    target = [target_lead] * fake_prefix_tokens + suffix\n",
+    "    return source, target, cache_tokens"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "030145fc",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "\u001b[32;20m[2026-06-23 23:26:52,200] LMCache INFO:\u001b[0m Initialized LMCacheKVCacheContext with instance_id=3403760, model_name=Qwen/Qwen3-8B, chunk_size=256, shm_name=lmcache_l1_pool_lmcache_kvcache_sdk_e2e \u001b[3m(kvcache.py:104:lmcache.sdk.kvcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:52,206] LMCache INFO:\u001b[0m Creating transfer context (device_type=cpu, mode=auto) \u001b[3m(worker_transfer.py:551:lmcache.v1.multiprocess.transfer_context.worker_transfer)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:52,206] LMCache INFO:\u001b[0m Engine KV Format: EngineKVFormat.NL_X_NB_TWO_NH_BS_HS NL x [NB, 2, NH, BS, HS] \u001b[3m(detection.py:44:lmcache.v1.gpu_connector.kv_format.detection)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:52,208] LMCache INFO:\u001b[0m Creating EngineDrivenContextShm (shm_name=lmcache_l1_pool_lmcache_kvcache_sdk_e2e, pool_size=150323855360) \u001b[3m(base.py:235:lmcache.v1.multiprocess.transfer_context.base)\u001b[0m\n",
+      "\u001b[32;20m[2026-06-23 23:26:52,209] LMCache INFO:\u001b[0m Worker non-GPU transfer context registered (instance_id=3403760, mode=SHM) \u001b[3m(worker_transfer.py:420:lmcache.v1.multiprocess.transfer_context.worker_transfer)\u001b[0m\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Only create one LMCacheKVCacheContext, reuse for retrieve() and store()\n",
+    "# multiple times. Only close() once at the end.\n",
+    "ctx = lmc_sdk.connect(\n",
+    "    url=lmcache_mq_url,\n",
+    "    http_url=lmcache_url,\n",
+    "    model_name=model_name,\n",
+    "    timeout=timeout,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "2f1c8d9a",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "== Step 1: source inference stores KV under source token IDs ==\n",
+      "== Step 2: retrieve source KV into memory through lmcache.sdk ==\n",
+      "== Step 3: store source KV under different target token IDs ==\n",
+      "== Step 4: target inference reuses the remapped token IDs ==\n",
+      "== Evaluation ==\n",
+      "{\n",
+      "  \"vllm_model_name\": \"Qwen/Qwen3-8B\",\n",
+      "  \"cache_tokens\": 512,\n",
+      "  \"source_prompt_tokens\": 512,\n",
+      "  \"target_prompt_tokens\": 512,\n",
+      "  \"retrieved_hit_tokens\": 512,\n",
+      "  \"retrieved_hit_chunks\": 2,\n",
+      "  \"source_target_same_length\": true,\n",
+      "  \"source_target_last_hit_tokens_match\": false,\n",
+      "  \"target_prefix_ids_differ_from_source\": true,\n",
+      "  \"outputs_match\": true,\n",
+      "  \"store_result\": true,\n",
+      "  \"source_retrieve_after_inference\": {\n",
+      "    \"shape\": [\n",
+      "      2,\n",
+      "      36,\n",
+      "      512,\n",
+      "      1024\n",
+      "    ],\n",
+      "    \"dtype\": \"torch.bfloat16\",\n",
+      "    \"hit_tokens\": 512,\n",
+      "    \"hit_chunks\": 2\n",
+      "  },\n",
+      "  \"source_latency_seconds\": 1.2143411422148347,\n",
+      "  \"target_latency_seconds\": 1.1793114291504025,\n",
+      "  \"source_output_preview\": \"Okay, I need to understand what the user is asking for. They provided a series of repeated sentences about a systems researcher studying how an inference cache affects the\",\n",
+      "  \"target_output_preview\": \"Okay, I need to understand what the user is asking for. They provided a series of repeated sentences about a systems researcher studying how an inference cache affects the\"\n",
+      "}\n"
+     ]
+    }
+   ],
+   "source": [
+    "tokenizer = AutoTokenizer.from_pretrained(\n",
+    "    model_name,\n",
+    "    trust_remote_code=trust_remote_code,\n",
+    ")\n",
+    "source_tokens, target_tokens, cache_tokens = _build_prompts(\n",
+    "    tokenizer,\n",
+    "    min_prompt_tokens=min_prompt_tokens,\n",
+    "    chunk_size=chunk_size,\n",
+    "    fake_prefix_tokens=fake_prefix_tokens,\n",
+    ")\n",
+    "\n",
+    "print(\"== Step 1: source inference stores KV under source token IDs ==\")\n",
+    "source_completion = _post_completion(\n",
+    "    vllm_url=vllm_url,\n",
+    "    model_name=model_name,\n",
+    "    prompt=source_tokens,\n",
+    "    max_tokens=max_tokens,\n",
+    "    timeout=timeout,\n",
+    ")\n",
+    "\n",
+    "print(\"== Step 2: retrieve source KV into memory through lmcache.sdk ==\")\n",
+    "retrieved_kv = lmc_sdk.retrieve(\n",
+    "    ctx=ctx,\n",
+    "    tokens=source_tokens,\n",
+    ")\n",
+    "if retrieved_kv is None:\n",
+    "    raise RuntimeError(\"source retrieve missed the expected cached prefix\")\n",
+    "retrieved_hit_tokens = int(retrieved_kv.shape[2])\n",
+    "retrieved_hit_chunks = retrieved_hit_tokens // chunk_size\n",
+    "if retrieved_hit_tokens < cache_tokens:\n",
+    "    raise RuntimeError(\n",
+    "        \"source retrieve did not return the expected cached prefix: \"\n",
+    "        f\"{retrieved_hit_tokens} < {cache_tokens}\"\n",
+    "    )\n",
+    "\n",
+    "target_prefix_tokens = target_tokens[:retrieved_hit_tokens]\n",
+    "source_prefix_tokens = source_tokens[:retrieved_hit_tokens]\n",
+    "if source_prefix_tokens == target_prefix_tokens:\n",
+    "    raise RuntimeError(\"source and target token prefixes unexpectedly match\")\n",
+    "\n",
+    "print(\"== Step 3: store source KV under different target token IDs ==\")\n",
+    "store_result = lmc_sdk.store(\n",
+    "    ctx=ctx,\n",
+    "    kv=retrieved_kv,\n",
+    "    tokens=target_prefix_tokens,\n",
+    ")\n",
+    "if not store_result:\n",
+    "    raise RuntimeError(\n",
+    "        f\"Failed to store {len(target_prefix_tokens)} target prefix tokens. \"\n",
+    "        f\"Might be because LMCache already has the KV cache.\"\n",
+    "    )\n",
+    "\n",
+    "print(\"== Step 4: target inference reuses the remapped token IDs ==\")\n",
+    "target_completion = _post_completion(\n",
+    "    vllm_url=vllm_url,\n",
+    "    model_name=model_name,\n",
+    "    prompt=target_tokens,\n",
+    "    max_tokens=max_tokens,\n",
+    "    timeout=timeout,\n",
+    ")\n",
+    "outputs_match = source_completion.text == target_completion.text\n",
+    "\n",
+    "evaluation = {\n",
+    "    \"vllm_model_name\": model_name,\n",
+    "    \"cache_tokens\": cache_tokens,\n",
+    "    \"source_prompt_tokens\": len(source_tokens),\n",
+    "    \"target_prompt_tokens\": len(target_tokens),\n",
+    "    \"retrieved_hit_tokens\": retrieved_hit_tokens,\n",
+    "    \"retrieved_hit_chunks\": retrieved_hit_chunks,\n",
+    "    \"source_target_same_length\": len(source_tokens) == len(target_tokens),\n",
+    "    \"source_target_last_hit_tokens_match\": source_tokens[-retrieved_hit_tokens:]\n",
+    "    == target_tokens[-retrieved_hit_tokens:],\n",
+    "    \"target_prefix_ids_differ_from_source\": source_prefix_tokens\n",
+    "    != target_prefix_tokens,\n",
+    "    \"outputs_match\": outputs_match,\n",
+    "    \"store_result\": store_result,\n",
+    "    \"source_retrieve_after_inference\": {\n",
+    "        \"shape\": tuple(retrieved_kv.shape),\n",
+    "        \"dtype\": str(retrieved_kv.dtype),\n",
+    "        \"hit_tokens\": retrieved_hit_tokens,\n",
+    "        \"hit_chunks\": retrieved_hit_chunks,\n",
+    "    },\n",
+    "    \"source_latency_seconds\": source_completion.elapsed_seconds,\n",
+    "    \"target_latency_seconds\": target_completion.elapsed_seconds,\n",
+    "    \"source_output_preview\": \" \".join(source_completion.text.split()[:max_tokens]),\n",
+    "    \"target_output_preview\": \" \".join(target_completion.text.split()[:max_tokens]),\n",
+    "}\n",
+    "print(\"== Evaluation ==\")\n",
+    "print(json.dumps(cast(dict[str, object], evaluation), indent=2, default=str))\n",
+    "if not outputs_match:\n",
+    "    raise RuntimeError(\"Target output did not match source output after KV remap.\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "f83db925",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Only close the context when done.\n",
+    "lmc_sdk.close(ctx)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "LMCache (3.12.3.final.0)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/lmc_external_l2_adapter/pyproject.toml b/examples/lmc_external_l2_adapter/pyproject.toml
new file mode 100644
index 0000000..f6f46c6
--- /dev/null
+++ b/examples/lmc_external_l2_adapter/pyproject.toml
@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lmc-external-l2-adapter"
+version = "0.1.0"
+description = "Example external L2 adapter plugin for LMCache"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "lmcache",
+]
+
+[project.urls]
+homepage = "https://github.com/LMCache/LMCache"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["lmc_external_l2_adapter*"]
+
+[tool.ruff]
+line-length = 88
diff --git a/examples/lmc_external_l2_adapter/scripts/install_and_test.sh b/examples/lmc_external_l2_adapter/scripts/install_and_test.sh
new file mode 100755
index 0000000..a3666f3
--- /dev/null
+++ b/examples/lmc_external_l2_adapter/scripts/install_and_test.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Quick-start script for the lmc_external_l2_adapter
+# example plugin.
+#
+# Usage:
+#   cd examples/lmc_external_l2_adapter
+#   bash scripts/install_and_test.sh
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+echo "=== Step 1: Install the plugin in editable mode ==="
+pip install -e "$PROJECT_DIR" --quiet
+
+echo ""
+echo "=== Step 2: Verify the module is importable ==="
+python -c "
+from lmc_external_l2_adapter import InMemoryL2Adapter
+print('  OK: InMemoryL2Adapter imported successfully')
+print('  Class:', InMemoryL2Adapter)
+"
+
+echo ""
+echo "=== Step 3: Verify LMCache recognises 'external' type ==="
+python -c "
+from lmcache.v1.distributed.l2_adapters.config import (
+    get_registered_l2_adapter_types,
+)
+types = get_registered_l2_adapter_types()
+assert 'plugin' in types, f'plugin not in {types}'
+print('  OK: registered adapter types:', types)
+"
+
+echo ""
+echo "=== Step 4: Run the plugin unit tests ==="
+python -m pytest "$PROJECT_DIR/tests/" -v
+
+echo ""
+echo "=== All checks passed! ==="
+echo ""
+echo "To use this adapter with LMCache, pass:"
+echo '  --l2-adapter '"'"'{"type":"plugin","module_path":"lmc_external_l2_adapter","class_name":"InMemoryL2Adapter","adapter_params":{"max_size_gb":1.0,"mock_bandwidth_gb":20.0}}'"'"''
diff --git a/examples/lmc_external_l2_adapter/src/lmc_external_l2_adapter/__init__.py b/examples/lmc_external_l2_adapter/src/lmc_external_l2_adapter/__init__.py
new file mode 100644
index 0000000..7bddc62
--- /dev/null
+++ b/examples/lmc_external_l2_adapter/src/lmc_external_l2_adapter/__init__.py
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+lmc_external_l2_adapter - Example external L2 adapter
+plugin for LMCache.
+
+This package provides a simple in-memory L2 adapter that
+demonstrates how to build an external plugin loaded via
+the ``PluginL2AdapterConfig`` mechanism.
+"""
+
+# Third Party
+from lmc_external_l2_adapter.adapter import (
+    InMemoryL2Adapter,
+    InMemoryL2AdapterConfig,
+)
+
+__all__ = ["InMemoryL2Adapter", "InMemoryL2AdapterConfig"]
diff --git a/examples/lmc_external_l2_adapter/src/lmc_external_l2_adapter/adapter.py b/examples/lmc_external_l2_adapter/src/lmc_external_l2_adapter/adapter.py
new file mode 100644
index 0000000..371e5d3
--- /dev/null
+++ b/examples/lmc_external_l2_adapter/src/lmc_external_l2_adapter/adapter.py
@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+In-memory L2 adapter plugin for LMCache.
+
+A minimal but fully functional L2 adapter that stores KV
+cache objects in plain Python dicts.  Intended as a
+reference implementation for third-party plugin authors.
+"""
+
+# Standard
+from collections import defaultdict
+from typing import Any, Union
+import asyncio
+import copy
+import threading
+import time
+
+# Third Party
+import torch  # noqa: F401  # must precede native_storage_ops
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+)
+from lmcache.v1.memory_management import (
+    MemoryObj,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+
+def _clone_tensor_memory_obj(
+    obj: MemoryObj,
+) -> TensorMemoryObj:
+    """Deep-clone a TensorMemoryObj."""
+    assert isinstance(obj, TensorMemoryObj), "Only TensorMemoryObj is supported"
+    raw = obj.raw_tensor
+    assert raw is not None, "tensor data cannot be None"
+    return TensorMemoryObj(
+        raw_data=raw.detach().clone(),
+        metadata=copy.deepcopy(obj.metadata),
+        parent_allocator=None,
+    )
+
+
+class InMemoryL2AdapterConfig(L2AdapterConfigBase):
+    """Config for the in-memory L2 adapter.
+
+    Fields:
+    - max_size_gb: Maximum cache size in GiB.
+    - mock_bandwidth_gb: Simulated bandwidth in GiB/s.
+    """
+
+    def __init__(
+        self,
+        max_size_gb: float = 0.5,
+        mock_bandwidth_gb: float = 10.0,
+    ):
+        self.max_size_gb = max_size_gb
+        self.mock_bandwidth_gb = mock_bandwidth_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "InMemoryL2AdapterConfig":
+        return cls(
+            max_size_gb=float(d.get("max_size_gb", 0.5)),
+            mock_bandwidth_gb=float(d.get("mock_bandwidth_gb", 10.0)),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "InMemoryL2Adapter config fields:\n"
+            "- max_size_gb (float): max cache size "
+            "in GiB (default 0.5)\n"
+            "- mock_bandwidth_gb (float): simulated "
+            "bandwidth in GiB/s (default 10.0)\n"
+        )
+
+
+class InMemoryL2Adapter(L2AdapterInterface):
+    """In-memory L2 adapter loaded as an external plugin.
+
+    Constructor accepts either an
+    ``InMemoryL2AdapterConfig`` instance (when the
+    framework auto-discovers the config class) **or**
+    a plain dict (raw-dict mode, when no config class
+    is registered).
+
+    Any extra ``**kwargs`` forwarded by the framework
+    (e.g. ``l1_memory_desc``) are accepted but not used
+    by this simple example adapter.
+    """
+
+    def __init__(
+        self,
+        config: Union[
+            InMemoryL2AdapterConfig,
+            dict[str, Any],
+        ],
+        **_kwargs: object,
+    ):
+        if isinstance(config, dict):
+            config = InMemoryL2AdapterConfig.from_dict(config)
+        max_size_gb = config.max_size_gb
+        mock_bandwidth_gb = config.mock_bandwidth_gb
+        cap = int(max_size_gb * (1024**3))
+        bw = int(mock_bandwidth_gb * (1024**3))
+
+        self._max_cap = cap
+        self._bw_bps = bw
+        self._cur_size = 0
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        self._objects: dict[ObjectKey, MemoryObj] = {}
+        self._key_queue: list[ObjectKey] = []
+        self._locked: dict[ObjectKey, int] = defaultdict(int)
+
+        self._next_id: L2TaskId = 0
+        self._done_store: dict[L2TaskId, L2StoreResult] = {}
+        self._done_lookup: dict[L2TaskId, Bitmap] = {}
+        self._done_load: dict[L2TaskId, Bitmap] = {}
+        self._lock = threading.Lock()
+
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._run_loop, daemon=True)
+        self._thread.start()
+
+        logger.info(
+            "InMemoryL2Adapter created: max_size_gb=%s, mock_bandwidth_gb=%s",
+            max_size_gb,
+            mock_bandwidth_gb,
+        )
+
+    # ---- event fd ------------------------------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    # ---- store ---------------------------------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            tid = self._alloc_id()
+        asyncio.run_coroutine_threadsafe(
+            self._do_store(keys, objects, tid),
+            self._loop,
+        )
+        return tid
+
+    def pop_completed_store_tasks(
+        self,
+    ) -> dict[L2TaskId, L2StoreResult]:
+        with self._lock:
+            done = self._done_store
+            self._done_store = {}
+        return done
+
+    # ---- lookup & lock -------------------------------------
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        # TODO: this example ignores layout_desc; a real adapter may need it (the hint is forwarded by the P2P adapter).
+        with self._lock:
+            tid = self._alloc_id()
+        self._loop.call_soon_threadsafe(self._do_lookup, keys, tid)
+        return tid
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._done_lookup.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        def _unlock(ks: list[ObjectKey]) -> None:
+            for k in ks:
+                if k not in self._locked:
+                    continue
+                if self._locked[k] <= 1:
+                    del self._locked[k]
+                else:
+                    self._locked[k] -= 1
+
+        self._loop.call_soon_threadsafe(_unlock, keys)
+
+    # ---- load ----------------------------------------------
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            tid = self._alloc_id()
+        asyncio.run_coroutine_threadsafe(
+            self._do_load(keys, objects, tid),
+            self._loop,
+        )
+        return tid
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._done_load.pop(task_id, None)
+
+    # ---- close ---------------------------------------------
+
+    def close(self) -> None:
+        async def _cancel() -> None:
+            tasks = [
+                t
+                for t in asyncio.all_tasks(self._loop)
+                if t is not asyncio.current_task()
+            ]
+            for t in tasks:
+                t.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            fut = asyncio.run_coroutine_threadsafe(_cancel(), self._loop)
+            try:
+                fut.result(timeout=5)
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._thread.join()
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+    # ---- helpers -------------------------------------------
+
+    def _run_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _alloc_id(self) -> L2TaskId:
+        tid = self._next_id
+        self._next_id += 1
+        return tid
+
+    def _evict(self, needed: int) -> None:
+        tries = len(self._key_queue)
+        while self._cur_size + needed > self._max_cap and tries > 0:
+            tries -= 1
+            k = self._key_queue.pop(0)
+            if self._locked.get(k, 0) > 0:
+                self._key_queue.append(k)
+                continue
+            if k in self._objects:
+                self._cur_size -= self._objects.pop(k).get_size()
+
+    async def _do_store(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        tid: L2TaskId,
+    ) -> None:
+        total = 0
+        ok = True
+        t0 = time.perf_counter()
+        try:
+            for key, obj in zip(keys, objects, strict=False):
+                sz = obj.get_size()
+                if sz > self._max_cap:
+                    continue
+                if key in self._objects:
+                    continue
+                self._evict(sz)
+                clone = _clone_tensor_memory_obj(obj)
+                self._objects[key] = clone
+                self._key_queue.append(key)
+                self._cur_size += sz
+                total += sz
+        except Exception:
+            ok = False
+
+        delay = total / self._bw_bps if self._bw_bps > 0 else 0
+        delay -= time.perf_counter() - t0
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+        with self._lock:
+            self._done_store[tid] = L2StoreResult(ok, total)
+        self._store_efd.notify()
+
+    def _do_lookup(
+        self,
+        keys: list[ObjectKey],
+        tid: L2TaskId,
+    ) -> None:
+        bm = Bitmap(len(keys))
+        for i, k in enumerate(keys):
+            if k not in self._objects:
+                continue
+            bm.set(i)
+            self._locked[k] += 1
+        with self._lock:
+            self._done_lookup[tid] = bm
+        self._lookup_efd.notify()
+
+    async def _do_load(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        tid: L2TaskId,
+    ) -> None:
+        bm = Bitmap(len(keys))
+        total = 0
+        t0 = time.perf_counter()
+        for i, k in enumerate(keys):
+            if k not in self._objects:
+                continue
+            src = self._objects[k].tensor
+            dst = objects[i].tensor
+            assert src is not None and dst is not None
+            dst.copy_(src)
+            bm.set(i)
+            total += self._objects[k].get_size()
+
+        delay = total / self._bw_bps if self._bw_bps > 0 else 0
+        delay -= time.perf_counter() - t0
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+        with self._lock:
+            self._done_load[tid] = bm
+        self._load_efd.notify()
diff --git a/examples/lmc_external_l2_adapter/tests/test_plugin.py b/examples/lmc_external_l2_adapter/tests/test_plugin.py
new file mode 100644
index 0000000..ef06bb9
--- /dev/null
+++ b/examples/lmc_external_l2_adapter/tests/test_plugin.py
@@ -0,0 +1,415 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the lmc_external_l2_adapter plugin.
+
+Validates that:
+1. The adapter class is importable and recognised by the
+   LMCache external adapter factory.
+2. PluginL2AdapterConfig can parse the plugin's JSON.
+3. On Linux the adapter can be fully instantiated and
+   performs store / lookup / load round-trips with
+   realistic tensor sizes (~4 KB+ per object).
+4. FIFO eviction works when the cache is full.
+"""
+
+# Standard
+from typing import TYPE_CHECKING
+import json
+import platform
+import select
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.l2_adapters.config import (
+    parse_args_to_l2_adapters_config,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    create_l2_adapter_from_registry,
+)
+from lmcache.v1.distributed.l2_adapters.plugin_l2_adapter import PluginL2AdapterConfig
+from lmcache.v1.memory_management import TensorMemoryObj
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+if TYPE_CHECKING:
+    pass
+
+try:
+    # Third Party
+    import lmc_external_l2_adapter  # noqa: F401
+
+    _HAS_PLUGIN = True
+except ModuleNotFoundError:
+    _HAS_PLUGIN = False
+
+_skip_unless_plugin = pytest.mark.skipif(
+    not _HAS_PLUGIN,
+    reason="lmc_external_l2_adapter is not installed",
+)
+
+# -- helpers --------------------------------------------------
+
+# Default object size: 1024 float32 = 4 KB
+OBJ_SIZE = 1024
+
+
+def _make_key(tag: int) -> ObjectKey:
+    """Create an ObjectKey compatible with both old
+    and new API signatures."""
+    # Standard
+    import inspect
+
+    sig = inspect.signature(ObjectKey)
+    params = list(sig.parameters)
+    if "chunk_hash" in params and "kv_rank" in params:
+        # New API: (chunk_hash: bytes, model_name, kv_rank)
+        return ObjectKey(
+            chunk_hash=tag.to_bytes(8, "big"),
+            model_name="test",
+            kv_rank=0,
+        )
+    # Old API: (model_name, world_size, worker_id, chunk_hash)
+    return ObjectKey(  # type: ignore[call-arg]
+        model_name="test",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=tag,  # type: ignore[arg-type]
+    )
+
+
+def _make_tensor_obj(
+    tensor: torch.Tensor,
+) -> TensorMemoryObj:
+    """Create a TensorMemoryObj compatible with both
+    old and new API."""
+    # Standard
+    import inspect
+
+    sig = inspect.signature(TensorMemoryObj)
+    params = list(sig.parameters)
+
+    # New API requires MemoryObjMetadata
+    if "metadata" in params:
+        try:
+            # First Party
+            from lmcache.v1.memory_management import (
+                MemoryObjMetadata,
+            )
+
+            meta = MemoryObjMetadata(
+                shape=tensor.shape,
+                dtype=tensor.dtype,
+                address=tensor.data_ptr(),
+                phy_size=(tensor.nelement() * tensor.element_size()),
+                ref_count=1,
+            )
+            return TensorMemoryObj(
+                raw_data=tensor,
+                metadata=meta,
+                parent_allocator=None,
+            )
+        except Exception:
+            pass
+
+    # Old API: metadata=None is fine
+    return TensorMemoryObj(
+        raw_data=tensor,
+        metadata=None,  # type: ignore[arg-type]
+        parent_allocator=None,
+    )
+
+
+def _create_obj(
+    size: int = OBJ_SIZE,
+    fill: float = 1.0,
+) -> TensorMemoryObj:
+    """Create a test TensorMemoryObj filled with *fill*."""
+    t = torch.empty(size, dtype=torch.float32)
+    t.fill_(fill)
+    return _make_tensor_obj(t)
+
+
+def _wait_event_fd(fd: int, timeout: float = 5.0) -> bool:
+    """Wait for an eventfd to be signaled."""
+    poll = select.poll()
+    poll.register(fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+# -- constants ------------------------------------------------
+
+ADAPTER_JSON = json.dumps(
+    {
+        "type": "plugin",
+        "module_path": "lmc_external_l2_adapter",
+        "class_name": "InMemoryL2Adapter",
+        "adapter_params": {
+            # ~10 KB capacity: fits 2x 4KB objects
+            "max_size_gb": 10240 / (1024**3),
+            "mock_bandwidth_gb": 10.0,
+        },
+    }
+)
+
+# Config-class mode: adapter receives a real config object
+ADAPTER_JSON_CFG = json.dumps(
+    {
+        "type": "plugin",
+        "module_path": "lmc_external_l2_adapter",
+        "class_name": "InMemoryL2Adapter",
+        "config_class_name": "InMemoryL2AdapterConfig",
+        "adapter_params": {
+            "max_size_gb": 10240 / (1024**3),
+            "mock_bandwidth_gb": 10.0,
+        },
+    }
+)
+
+_LINUX = platform.system() == "Linux"
+_skip_unless_linux = pytest.mark.skipif(
+    not _LINUX,
+    reason="eventfd requires Linux",
+)
+
+
+# -- config parsing tests ------------------------------------
+
+
+class TestPluginConfigParsing:
+    """Config-only tests (no instantiation)."""
+
+    def test_from_dict(self):
+        cfg = PluginL2AdapterConfig.from_dict(json.loads(ADAPTER_JSON))
+        assert cfg.module_path == "lmc_external_l2_adapter"
+        assert cfg.class_name == "InMemoryL2Adapter"
+        assert cfg.config_class_name is None
+
+    def test_from_dict_with_config_class(self):
+        cfg = PluginL2AdapterConfig.from_dict(json.loads(ADAPTER_JSON_CFG))
+        assert cfg.module_path == "lmc_external_l2_adapter"
+        assert cfg.class_name == "InMemoryL2Adapter"
+        assert cfg.config_class_name == "InMemoryL2AdapterConfig"
+
+    def test_parse_args(self):
+        """Simulate --l2-adapter CLI argument."""
+        # Standard
+        import argparse
+
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.config import (
+            add_l2_adapters_args,
+        )
+
+        parser = argparse.ArgumentParser()
+        add_l2_adapters_args(parser)
+        args = parser.parse_args(["--l2-adapter", ADAPTER_JSON])
+        config = parse_args_to_l2_adapters_config(args)
+        assert len(config.adapters) == 1
+        cfg = config.adapters[0]
+        assert isinstance(cfg, PluginL2AdapterConfig)
+        assert cfg.class_name == "InMemoryL2Adapter"
+
+
+# -- import / subclass tests ---------------------------------
+
+
+@_skip_unless_plugin
+class TestPluginImport:
+    """Verify the class is importable and correct."""
+
+    def test_import(self):
+        # Third Party
+        from lmc_external_l2_adapter import (
+            InMemoryL2Adapter,
+        )
+
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.base import (
+            L2AdapterInterface,
+        )
+
+        assert issubclass(InMemoryL2Adapter, L2AdapterInterface)
+
+
+# -- full round-trip tests (Linux only) ----------------------
+
+
+@_skip_unless_plugin
+@_skip_unless_linux
+class TestPluginRoundTrip:
+    """End-to-end tests that create the adapter via the
+    external factory and exercise store/lookup/load with
+    realistic 4 KB objects."""
+
+    @pytest.fixture(params=["dict", "config_class"])
+    def adapter(self, request):
+        spec = ADAPTER_JSON if request.param == "dict" else ADAPTER_JSON_CFG
+        cfg = PluginL2AdapterConfig.from_dict(json.loads(spec))
+        inst = create_l2_adapter_from_registry(cfg)
+        yield inst
+        inst.close()
+
+    # -- basic interface tests --
+
+    def test_create_via_registry(self, adapter):
+        # Third Party
+        from lmc_external_l2_adapter import (
+            InMemoryL2Adapter,
+        )
+
+        assert isinstance(adapter, InMemoryL2Adapter)
+
+    def test_event_fds_are_distinct(self, adapter):
+        fds = {
+            adapter.get_store_event_fd(),
+            adapter.get_lookup_and_lock_event_fd(),
+            adapter.get_load_event_fd(),
+        }
+        assert len(fds) == 3
+
+    # -- store & lookup with 4 KB objects --
+
+    def test_store_and_lookup(self, adapter):
+        """Store a 4 KB object then look it up."""
+        key = _make_key(42)
+        obj = _create_obj(OBJ_SIZE, fill=3.14)
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        tid = adapter.submit_store_task([key], [obj])
+        assert _wait_event_fd(store_fd)
+        done = adapter.pop_completed_store_tasks()
+        assert done.get(tid) is not None
+        assert done[tid].is_successful()
+
+        ltid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert _wait_event_fd(lookup_fd)
+        bm = adapter.query_lookup_and_lock_result(ltid)
+        assert bm is not None
+        assert bm.test(0) is True
+        adapter.submit_unlock([key])
+
+    # -- store & load with 4 KB objects --
+
+    def test_store_and_load(self, adapter):
+        """Store 4 KB then load back and compare."""
+        key = _make_key(99)
+        src = torch.arange(OBJ_SIZE, dtype=torch.float32)
+        obj = _make_tensor_obj(src.clone())
+        store_fd = adapter.get_store_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        tid = adapter.submit_store_task([key], [obj])
+        assert _wait_event_fd(store_fd)
+        done = adapter.pop_completed_store_tasks()
+        assert done.get(tid) is not None
+        assert done[tid].is_successful()
+
+        dst = torch.zeros_like(src)
+        load_obj = _make_tensor_obj(dst)
+        ltid = adapter.submit_load_task([key], [load_obj])
+        assert _wait_event_fd(load_fd)
+        bm = adapter.query_load_result(ltid)
+        assert bm is not None
+        assert bm.test(0) is True
+        assert torch.equal(dst, src)
+
+    # -- batch store --
+
+    def test_batch_store_and_lookup(self, adapter):
+        """Store a batch of 2 objects then lookup both."""
+        keys = [_make_key(i) for i in range(2)]
+        objs = [_create_obj(OBJ_SIZE, fill=float(i)) for i in range(2)]
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        tid = adapter.submit_store_task(keys, objs)
+        assert _wait_event_fd(store_fd)
+        done = adapter.pop_completed_store_tasks()
+        assert done.get(tid) is not None
+        assert done[tid].is_successful()
+
+        ltid = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert _wait_event_fd(lookup_fd)
+        bm = adapter.query_lookup_and_lock_result(ltid)
+        assert bm is not None
+        for i in range(2):
+            assert bm.test(i) is True
+        adapter.submit_unlock(keys)
+
+    # -- mixed lookup (existing + non-existing) --
+
+    def test_lookup_mixed_keys(self, adapter):
+        """Lookup of existing + non-existing keys."""
+        stored_key = _make_key(200)
+        missing_key = _make_key(999)
+        obj = _create_obj(OBJ_SIZE)
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        adapter.submit_store_task([stored_key], [obj])
+        assert _wait_event_fd(store_fd)
+        adapter.pop_completed_store_tasks()
+
+        ltid = adapter.submit_lookup_and_lock_task(
+            [stored_key, missing_key], _EMPTY_LAYOUT
+        )
+        assert _wait_event_fd(lookup_fd)
+        bm = adapter.query_lookup_and_lock_result(ltid)
+        assert bm is not None
+        assert bm.test(0) is True  # stored
+        assert bm.test(1) is False  # missing
+        adapter.submit_unlock([stored_key])
+
+    # -- eviction test --
+
+    def test_fifo_eviction(self, adapter):
+        """When the cache is full, FIFO eviction should
+        remove the oldest entry.
+
+        Config gives ~10 KB capacity; each object is
+        4 KB (1024 * 4 bytes).  Storing 3 objects
+        should evict the first one.
+        """
+        k1 = _make_key(301)
+        k2 = _make_key(302)
+        k3 = _make_key(303)
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # Store k1, k2 (fits within 10 KB)
+        for k in [k1, k2]:
+            tid = adapter.submit_store_task([k], [_create_obj(OBJ_SIZE)])
+            assert _wait_event_fd(store_fd)
+            done = adapter.pop_completed_store_tasks()
+            assert done.get(tid) is not None
+            assert done[tid].is_successful()
+
+        # Store k3 -- should evict k1
+        tid = adapter.submit_store_task([k3], [_create_obj(OBJ_SIZE)])
+        assert _wait_event_fd(store_fd)
+        done = adapter.pop_completed_store_tasks()
+        assert done.get(tid) is not None
+        assert done[tid].is_successful()
+
+        # Lookup all three
+        ltid = adapter.submit_lookup_and_lock_task([k1, k2, k3], _EMPTY_LAYOUT)
+        assert _wait_event_fd(lookup_fd)
+        bm = adapter.query_lookup_and_lock_result(ltid)
+        assert bm is not None
+        assert bm.test(0) is False  # k1 evicted
+        assert bm.test(1) is True  # k2 present
+        assert bm.test(2) is True  # k3 present
+        adapter.submit_unlock([k2, k3])
diff --git a/examples/lmc_external_native_connector/csrc/connector.cpp b/examples/lmc_external_native_connector/csrc/connector.cpp
new file mode 100644
index 0000000..1e4c76f
--- /dev/null
+++ b/examples/lmc_external_native_connector/csrc/connector.cpp
@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: Apache-2.0
+
+#include "connector.h"
+#include <fcntl.h>
+#include <cerrno>
+#include <cstdio>
+#include <stdexcept>
+#include <string>
+
+namespace example_connector {
+
+// ---------------------------------------------------------------
+// Shared I/O helpers
+// ---------------------------------------------------------------
+
+static void write_all(int fd, const void* data, size_t len) {
+  size_t written = 0;
+  const char* ptr = static_cast<const char*>(data);
+  while (written < len) {
+    ssize_t n = ::write(fd, ptr + written, len - written);
+    if (n < 0) {
+      if (errno == EINTR) continue;
+      throw std::runtime_error("write failed: " + std::string(strerror(errno)));
+    }
+    if (n == 0) throw std::runtime_error("write returned 0");
+    written += static_cast<size_t>(n);
+  }
+}
+
+static size_t read_all(int fd, void* buf, size_t len) {
+  size_t total = 0;
+  char* ptr = static_cast<char*>(buf);
+  while (total < len) {
+    ssize_t n = ::read(fd, ptr + total, len - total);
+    if (n < 0) {
+      if (errno == EINTR) continue;
+      throw std::runtime_error("read failed: " + std::string(strerror(errno)));
+    }
+    if (n == 0) break;
+    total += static_cast<size_t>(n);
+  }
+  return total;
+}
+
+// ---------------------------------------------------------------
+// ExampleFSConnector
+// ---------------------------------------------------------------
+
+// Key encoding constants — must match fs_l2_adapter.py
+static constexpr char KEY_SEP = '@';
+static constexpr const char* PATH_SLASH_REPLACEMENT = "-SEP-";
+static constexpr const char* FILE_EXT = ".data";
+
+std::string ExampleFSConnector::replace_all(const std::string& str,
+                                            const std::string& from,
+                                            const std::string& to) {
+  std::string result = str;
+  size_t pos = 0;
+  while ((pos = result.find(from, pos)) != std::string::npos) {
+    result.replace(pos, from.size(), to);
+    pos += to.size();
+  }
+  return result;
+}
+
+std::string ExampleFSConnector::safe_filename(const std::string& key) {
+  // Input key format (from _object_key_to_string):
+  //   Unsalted: <model_name>@<kv_rank_hex>@<chunk_hash_hex>
+  //   Salted  : <model_name>@<kv_rank_hex>@<chunk_hash_hex>@<cache_salt>
+  //
+  // Output filename:
+  //   Unsalted: <model_name_safe>@0x<kv_rank_hex>@<chunk_hash_hex>.data
+  //   Salted  :
+  //   <model_name_safe>@0x<kv_rank_hex>@<chunk_hash_hex>@<cache_salt>.data
+  //
+  // Both model_name and cache_salt are forbidden from containing '@'
+  // (invariant enforced on the Python side), so splitting on '@' is
+  // unambiguous.
+
+  std::vector<std::string> parts;
+  size_t start = 0;
+  for (size_t pos = 0; pos <= key.size(); ++pos) {
+    if (pos == key.size() || key[pos] == KEY_SEP) {
+      parts.emplace_back(key.substr(start, pos - start));
+      start = pos + 1;
+    }
+  }
+  if (parts.size() != 3 && parts.size() != 4) {
+    throw std::runtime_error(
+        "ExampleFSConnector: malformed key "
+        "(expected 3 or 4 '@'-separated fields): " +
+        key);
+  }
+
+  const std::string& model = parts[0];
+  const std::string& kv_rank_hex = parts[1];
+  const std::string& chunk_hash = parts[2];
+  const std::string cache_salt = parts.size() == 4 ? parts[3] : std::string();
+
+  // Replace '/' with '-SEP-' for filesystem safety
+  std::string safe_model = replace_all(model, "/", PATH_SLASH_REPLACEMENT);
+
+  std::string result;
+  result.reserve(safe_model.size() + kv_rank_hex.size() + chunk_hash.size() +
+                 cache_salt.size() + 32);
+  result += safe_model;
+  result += KEY_SEP;
+  result += "0x";
+  result += kv_rank_hex;
+  result += KEY_SEP;
+  result += chunk_hash;
+  if (!cache_salt.empty()) {
+    result += KEY_SEP;
+    result += cache_salt;
+  }
+  result += FILE_EXT;
+  return result;
+}
+
+ExampleFSConnector::ExampleFSConnector(std::string base_path, int num_workers)
+    : ConnectorBase(num_workers), base_path_(std::move(base_path)) {
+  std::filesystem::create_directories(base_path_);
+  start_workers();
+}
+
+ExampleFSConnector::~ExampleFSConnector() { close(); }
+
+WorkerFSConn ExampleFSConnector::create_connection() {
+  WorkerFSConn conn;
+  conn.base_path = base_path_;
+  return conn;
+}
+
+void ExampleFSConnector::do_single_get(WorkerFSConn& conn,
+                                       const std::string& key, void* buf,
+                                       size_t len, size_t /*chunk_size*/) {
+  auto path = conn.base_path / safe_filename(key);
+  int fd = ::open(path.c_str(), O_RDONLY);
+  if (fd < 0) {
+    throw std::runtime_error("open for read failed: " + path.string() + ": " +
+                             strerror(errno));
+  }
+  size_t n = read_all(fd, buf, len);
+  ::close(fd);
+  if (n != len) {
+    throw std::runtime_error("incomplete read for " + path.string());
+  }
+}
+
+void ExampleFSConnector::do_single_set(WorkerFSConn& conn,
+                                       const std::string& key, const void* buf,
+                                       size_t len, size_t /*chunk_size*/) {
+  auto file_path = conn.base_path / safe_filename(key);
+  if (std::filesystem::exists(file_path)) return;
+
+  auto tmp_path = file_path;
+  tmp_path.replace_extension(".tmp");
+
+  int fd = ::open(tmp_path.c_str(), O_CREAT | O_WRONLY | O_TRUNC, 0644);
+  if (fd < 0) {
+    throw std::runtime_error("open for write failed: " + tmp_path.string() +
+                             ": " + strerror(errno));
+  }
+  try {
+    write_all(fd, buf, len);
+  } catch (...) {
+    ::close(fd);
+    std::filesystem::remove(tmp_path);
+    throw;
+  }
+  ::close(fd);
+
+  std::error_code ec;
+  std::filesystem::rename(tmp_path, file_path, ec);
+  if (ec) {
+    std::error_code remove_ec;
+    std::filesystem::remove(tmp_path, remove_ec);
+    throw std::runtime_error("rename failed: " + ec.message());
+  }
+}
+
+bool ExampleFSConnector::do_single_exists(WorkerFSConn& conn,
+                                          const std::string& key) {
+  auto path = conn.base_path / safe_filename(key);
+  return std::filesystem::exists(path);
+}
+
+bool ExampleFSConnector::do_single_delete(WorkerFSConn& conn,
+                                          const std::string& key) {
+  auto path = conn.base_path / safe_filename(key);
+  std::error_code ec;
+  return std::filesystem::remove(path, ec);
+}
+
+// ---------------------------------------------------------------
+// ExampleMemoryConnector
+// ---------------------------------------------------------------
+
+ExampleMemoryConnector::ExampleMemoryConnector(int num_workers)
+    : ConnectorBase(num_workers),
+      store_(std::make_shared<SharedMemoryStore>()) {
+  start_workers();
+}
+
+ExampleMemoryConnector::~ExampleMemoryConnector() { close(); }
+
+WorkerMemConn ExampleMemoryConnector::create_connection() {
+  WorkerMemConn conn;
+  conn.store = store_;
+  return conn;
+}
+
+void ExampleMemoryConnector::do_single_get(WorkerMemConn& conn,
+                                           const std::string& key, void* buf,
+                                           size_t len, size_t /*chunk_size*/) {
+  std::lock_guard<std::mutex> lk(conn.store->mu);
+  auto it = conn.store->data.find(key);
+  if (it == conn.store->data.end()) {
+    throw std::runtime_error("key not found: " + key);
+  }
+  if (it->second.size() != len) {
+    throw std::runtime_error("size mismatch for key: " + key);
+  }
+  std::memcpy(buf, it->second.data(), len);
+}
+
+void ExampleMemoryConnector::do_single_set(WorkerMemConn& conn,
+                                           const std::string& key,
+                                           const void* buf, size_t len,
+                                           size_t /*chunk_size*/) {
+  std::lock_guard<std::mutex> lk(conn.store->mu);
+  auto& vec = conn.store->data[key];
+  vec.resize(len);
+  std::memcpy(vec.data(), buf, len);
+}
+
+bool ExampleMemoryConnector::do_single_exists(WorkerMemConn& conn,
+                                              const std::string& key) {
+  std::lock_guard<std::mutex> lk(conn.store->mu);
+  return conn.store->data.count(key) > 0;
+}
+
+bool ExampleMemoryConnector::do_single_delete(WorkerMemConn& conn,
+                                              const std::string& key) {
+  std::lock_guard<std::mutex> lk(conn.store->mu);
+  return conn.store->data.erase(key) > 0;
+}
+
+}  // namespace example_connector
diff --git a/examples/lmc_external_native_connector/csrc/connector.h b/examples/lmc_external_native_connector/csrc/connector.h
new file mode 100644
index 0000000..75702ea
--- /dev/null
+++ b/examples/lmc_external_native_connector/csrc/connector.h
@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "connector_base.h"
+#include <unistd.h>
+#include <cstring>
+#include <filesystem>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace example_connector {
+
+// ---------------------------------------------------------------
+// FS strategy: per-worker connection state
+// ---------------------------------------------------------------
+
+struct WorkerFSConn {
+  std::filesystem::path base_path;
+};
+
+class ExampleFSConnector
+    : public lmcache::connector::ConnectorBase<WorkerFSConn> {
+ public:
+  ExampleFSConnector(std::string base_path, int num_workers);
+  ~ExampleFSConnector() override;
+
+ protected:
+  WorkerFSConn create_connection() override;
+  void do_single_get(WorkerFSConn& conn, const std::string& key, void* buf,
+                     size_t len, size_t chunk_size) override;
+  void do_single_set(WorkerFSConn& conn, const std::string& key,
+                     const void* buf, size_t len, size_t chunk_size) override;
+  bool do_single_exists(WorkerFSConn& conn, const std::string& key) override;
+  bool do_single_delete(WorkerFSConn& conn, const std::string& key) override;
+
+ private:
+  static std::string safe_filename(const std::string& key);
+  static std::string replace_all(const std::string& str,
+                                 const std::string& from,
+                                 const std::string& to);
+  std::string base_path_;
+};
+
+// ---------------------------------------------------------------
+// Memory strategy: per-worker connection state (shared store)
+// ---------------------------------------------------------------
+
+// Shared in-memory store protected by a mutex.
+// All workers share a single instance via shared_ptr.
+struct SharedMemoryStore {
+  std::mutex mu;
+  std::unordered_map<std::string, std::vector<char>> data;
+};
+
+// Each worker holds a shared_ptr to the same store.
+struct WorkerMemConn {
+  std::shared_ptr<SharedMemoryStore> store;
+};
+
+class ExampleMemoryConnector
+    : public lmcache::connector::ConnectorBase<WorkerMemConn> {
+ public:
+  ExampleMemoryConnector(int num_workers);
+  ~ExampleMemoryConnector() override;
+
+ protected:
+  WorkerMemConn create_connection() override;
+  void do_single_get(WorkerMemConn& conn, const std::string& key, void* buf,
+                     size_t len, size_t chunk_size) override;
+  void do_single_set(WorkerMemConn& conn, const std::string& key,
+                     const void* buf, size_t len, size_t chunk_size) override;
+  bool do_single_exists(WorkerMemConn& conn, const std::string& key) override;
+  bool do_single_delete(WorkerMemConn& conn, const std::string& key) override;
+
+ private:
+  std::shared_ptr<SharedMemoryStore> store_;
+};
+
+}  // namespace example_connector
diff --git a/examples/lmc_external_native_connector/csrc/pybind.cpp b/examples/lmc_external_native_connector/csrc/pybind.cpp
new file mode 100644
index 0000000..6397460
--- /dev/null
+++ b/examples/lmc_external_native_connector/csrc/pybind.cpp
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <pybind11/pybind11.h>
+#include "connector_pybind_utils.h"
+#include "connector.h"
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(_native, m) {
+  m.doc() = "Example native connector plugin for LMCache";
+
+  py::class_<example_connector::ExampleFSConnector>(m, "ExampleFSConnector")
+      .def(py::init<std::string, int>(), py::arg("base_path"),
+           py::arg("num_workers"))
+          LMCACHE_BIND_CONNECTOR_METHODS(example_connector::ExampleFSConnector);
+
+  py::class_<example_connector::ExampleMemoryConnector>(
+      m, "ExampleMemoryConnector")
+      .def(py::init<int>(), py::arg("num_workers"))
+          LMCACHE_BIND_CONNECTOR_METHODS(
+              example_connector::ExampleMemoryConnector);
+}
diff --git a/examples/lmc_external_native_connector/pyproject.toml b/examples/lmc_external_native_connector/pyproject.toml
new file mode 100644
index 0000000..26ba064
--- /dev/null
+++ b/examples/lmc_external_native_connector/pyproject.toml
@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel", "pybind11>=2.11"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lmc-external-native-connector"
+version = "0.1.0"
+description = "Example external C++ native connector plugin for LMCache"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "lmcache",
+    "pybind11>=2.11",
+]
+
+[project.urls]
+homepage = "https://github.com/LMCache/LMCache"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["lmc_external_native_connector*"]
+
+[tool.ruff]
+line-length = 88
diff --git a/examples/lmc_external_native_connector/setup.py b/examples/lmc_external_native_connector/setup.py
new file mode 100644
index 0000000..2653b5b
--- /dev/null
+++ b/examples/lmc_external_native_connector/setup.py
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Build script for the example native connector plugin.
+
+Compiles the C++ pybind11 extension that implements
+ExampleFSConnector and ExampleMemoryConnector.  The
+LMCache connector_base.h headers are resolved from the
+LMCache source tree, assuming this example is located
+within the repository.
+
+NOTE: The C++ extension requires Linux (eventfd).  On
+other platforms the extension is skipped and only the
+Python wrapper module is installed.
+"""
+
+# Standard
+from pathlib import Path
+import os
+import platform
+
+# Third Party
+from setuptools import Extension, find_packages, setup
+import pybind11
+
+ROOT_DIR = Path(__file__).resolve().parent
+
+# Use relative paths -- setuptools forbids absolute ones.
+CSRC_REL = os.path.join("csrc")
+
+# Resolve LMCache csrc headers (connector_base.h, etc.)
+# Walk up from this example to the repo root.
+LMCACHE_ROOT = ROOT_DIR.parent.parent
+LMCACHE_CSRC = str(LMCACHE_ROOT / "csrc" / "storage_backends")
+
+ext_modules = []
+if platform.system() == "Linux":
+    ext_modules = [
+        Extension(
+            "lmc_external_native_connector._native",
+            sources=[
+                os.path.join(CSRC_REL, "pybind.cpp"),
+                os.path.join(CSRC_REL, "connector.cpp"),
+            ],
+            include_dirs=[
+                str(ROOT_DIR / "csrc"),
+                LMCACHE_CSRC,
+                pybind11.get_include(),
+            ],
+            language="c++",
+            extra_compile_args=["-O3", "-std=c++17"],
+        ),
+    ]
+
+setup(
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    ext_modules=ext_modules,
+)
diff --git a/examples/lmc_external_native_connector/src/lmc_external_native_connector/__init__.py b/examples/lmc_external_native_connector/src/lmc_external_native_connector/__init__.py
new file mode 100644
index 0000000..27d8da5
--- /dev/null
+++ b/examples/lmc_external_native_connector/src/lmc_external_native_connector/__init__.py
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+lmc_external_native_connector - Example external C++
+native connector plugin for LMCache.
+
+This package provides pybind11-wrapped C++ connectors
+that implement the same interface as the built-in
+LMCache connectors (event_fd, submit_batch_get/set/exists,
+drain_completions, close).  It can be loaded via the
+``native_plugin`` L2 adapter type.
+
+Two storage backends are supported:
+- "fs" (default): stores data as files on disk.
+- "memory": stores data in a C++ unordered_map.
+
+Low-level access to individual backends:
+- ExampleFSConnector: C++ filesystem connector.
+- ExampleMemoryConnector: C++ in-memory connector.
+"""
+
+# Third Party
+from lmc_external_native_connector.connector import (
+    ExampleNativeConnector,
+)
+
+__all__ = [
+    "ExampleNativeConnector",
+]
diff --git a/examples/lmc_external_native_connector/src/lmc_external_native_connector/connector.py b/examples/lmc_external_native_connector/src/lmc_external_native_connector/connector.py
new file mode 100644
index 0000000..698c93e
--- /dev/null
+++ b/examples/lmc_external_native_connector/src/lmc_external_native_connector/connector.py
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Example native connector plugin for LMCache.
+
+This module provides a factory function that creates a
+C++ pybind11-wrapped connector instance.  Two storage
+backends are available:
+
+- ``"fs"`` (default): persists data as files under a
+  configurable directory.
+- ``"memory"``: stores data in a C++ unordered_map
+  (in-process, lost on restart).
+
+Usage via ``native_plugin`` L2 adapter type::
+
+    --l2-adapter '{
+      "type": "native_plugin",
+      "module_path": "lmc_external_native_connector",
+      "class_name": "ExampleNativeConnector",
+      "adapter_params": {
+        "backend": "fs",
+        "base_path": "/tmp/lmcache_ext",
+        "num_workers": 2
+      }
+    }'
+"""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from lmc_external_native_connector._native import (
+    ExampleFSConnector,
+    ExampleMemoryConnector,
+)
+
+
+class ExampleNativeConnector:
+    """Factory-style wrapper that delegates to the
+    appropriate C++ connector backend.
+
+    Constructor keyword arguments:
+    - backend (str): ``"fs"`` or ``"memory"``
+      (default ``"fs"``).
+    - base_path (str): directory for fs backend
+      (default ``"/tmp/lmcache_ext"``).
+    - num_workers (int): number of C++ I/O worker
+      threads (default 2).
+
+    The returned instance is itself a native connector
+    exposing the full pybind interface (event_fd,
+    submit_batch_get/set/exists, drain_completions,
+    close).
+    """
+
+    def __new__(
+        cls,
+        backend: str = "fs",
+        base_path: str = "/tmp/lmcache_ext",
+        num_workers: int = 2,
+    ):
+        if backend == "fs":
+            return ExampleFSConnector(base_path, num_workers)
+        if backend == "memory":
+            return ExampleMemoryConnector(num_workers)
+        raise ValueError("Unknown backend %r, choose 'fs' or 'memory'" % backend)
diff --git a/examples/mp_runtime_plugins/README.md b/examples/mp_runtime_plugins/README.md
new file mode 100644
index 0000000..ee08b32
--- /dev/null
+++ b/examples/mp_runtime_plugins/README.md
@@ -0,0 +1,93 @@
+# LMCache MP Runtime Plugin Examples
+
+## Overview
+
+This directory contains example runtime plugins designed for the
+**multiprocess (MP / ZMQ) server** mode of LMCache.
+
+> **Key difference from non-MP plugins:**
+> In MP mode the `LMCACHE_RUNTIME_PLUGIN_CONFIG` environment variable
+> carries an **aggregated JSON dict** with sections like `mp_config`,
+> `storage_manager_config`, and `obs_config` — rather than a single
+> `LMCacheEngineConfig` JSON.
+
+## Design
+
+For architecture details, component diagrams, and data flow, see
+[docs/design/v1/multiprocess/mp_runtime_plugin.md](../../docs/design/v1/multiprocess/mp_runtime_plugin.md).
+
+## Files
+
+| File | Language | Description |
+|------|----------|-------------|
+| `mp_plugin.py` | Python | Parses the aggregated MP config and runs a periodic status reporter |
+| `mp_heartbeat.sh` | Bash | Extracts config fields via `jq` and runs a heartbeat loop |
+
+## Environment Variables
+
+Plugins receive the following environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `LMCACHE_RUNTIME_PLUGIN_CONFIG` | Aggregated JSON config (see below) |
+
+> **Note:** Unlike the non-MP (vLLM integration) mode, the MP server
+> does **not** have multiple roles (e.g. `SCHEDULER`, `WORKER`).
+> All plugins run in the single MP server process. The filename
+> prefix-based role filtering has no effect in MP mode.
+
+### Config JSON Structure (MP mode)
+
+```json
+{
+  "mp_config": {
+    "host": "localhost",
+    "port": 5555,
+    "chunk_size": 256,
+    "max_workers": 1,
+    "hash_algorithm": "blake3",
+    "engine_type": "default",
+    "runtime_plugin_locations": ["examples/mp_runtime_plugins/"]
+  },
+  "storage_manager_config": {
+    "l1_manager_config": {
+      "memory_config": {
+        "size_in_bytes": 10737418240,
+        "use_lazy": true
+      }
+    },
+    "eviction_config": {
+      "eviction_policy": "LRU",
+      "trigger_watermark": 0.8,
+      "eviction_ratio": 0.2
+    }
+  },
+  "obs_config": {
+    "enabled": true,
+    "metrics_enabled": true,
+    "logging_enabled": true,
+    "tracing_enabled": false
+  }
+}
+```
+
+## Quick Start
+
+Launch the LMCache MP server with the plugin directory:
+
+```bash
+python -m lmcache.v1.multiprocess.server \
+    --host localhost --port 5555 \
+    --l1-size-gb 10 \
+    --eviction-policy LRU \
+    --runtime-plugin-locations examples/mp_runtime_plugins/
+```
+
+You should see plugin output in the server logs:
+
+```
+[mp_plugin] Started
+[mp_plugin] MP server: host=localhost  port=5555  chunk_size=256
+[mp_plugin] Storage: L1=10.0GB  eviction=LRU  watermark=0.8
+[mp_plugin] heartbeat #0
+```
diff --git a/examples/mp_runtime_plugins/mp_heartbeat.sh b/examples/mp_runtime_plugins/mp_heartbeat.sh
new file mode 100755
index 0000000..23a4e0a
--- /dev/null
+++ b/examples/mp_runtime_plugins/mp_heartbeat.sh
@@ -0,0 +1,37 @@
+#!/bin/bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Example MP runtime plugin (Bash) for LMCache multiprocess server.
+#
+# In MP mode the config JSON contains aggregated sections:
+#   mp_config, storage_manager_config, obs_config
+#
+# This script demonstrates:
+#   1. Reading the MP-mode environment variables.
+#   2. Extracting fields from the aggregated JSON via jq.
+#   3. Running a periodic heartbeat loop.
+#
+# Requires: jq (optional, falls back to raw echo)
+
+# Graceful shutdown
+trap "echo '[mp_heartbeat] Received termination signal, exiting...'; exit 0" SIGTERM SIGINT
+
+config="${LMCACHE_RUNTIME_PLUGIN_CONFIG}"
+
+echo "[mp_heartbeat] Started"
+
+# Dump config as compact single-line JSON.
+# The parent captures stdout line-by-line, so avoid multi-line output.
+if command -v jq &>/dev/null && [ -n "${config}" ]; then
+    echo "[mp_heartbeat] config: $(echo "${config}" | jq -c .)"
+else
+    echo "[mp_heartbeat] config: ${config}"
+fi
+
+# Heartbeat loop
+loop_count=0
+while true; do
+    echo "[mp_heartbeat] heartbeat #${loop_count}"
+    loop_count=$((loop_count + 1))
+    sleep 30
+done
diff --git a/examples/mp_runtime_plugins/mp_plugin.py b/examples/mp_runtime_plugins/mp_plugin.py
new file mode 100644
index 0000000..317c0b2
--- /dev/null
+++ b/examples/mp_runtime_plugins/mp_plugin.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Example MP runtime plugin for LMCache multiprocess server.
+
+In MP (multiprocess / ZMQ) mode the config passed via
+``LMCACHE_RUNTIME_PLUGIN_CONFIG`` is an **aggregated JSON dict**
+containing ``mp_config``, ``storage_manager_config``, and
+``obs_config`` sections -- NOT a single ``LMCacheEngineConfig``.
+
+Unlike the non-MP (vLLM-integrated) mode, the MP server has
+no role/worker concept -- there is only a single server process.
+The config is an aggregated dict of dataclass configs rather
+than a single ``LMCacheEngineConfig``.
+
+This plugin demonstrates:
+  1. How to parse the MP-mode aggregated config.
+  2. How to run a periodic background task (e.g. status reporter).
+  3. How to handle graceful shutdown via SIGTERM.
+
+Usage:
+  Launch the LMCache MP server with:
+
+    python -m lmcache.v1.multiprocess.server \
+        --host localhost --port 5555 \
+        --l1-size-gb 10 --eviction-policy LRU \
+        --runtime-plugin-locations \
+            examples/mp_runtime_plugins/
+"""
+
+# Standard
+import json
+import os
+import signal
+import sys
+import time
+
+
+def handle_exit(signum, frame):
+    """Graceful exit on SIGTERM / SIGINT."""
+    print("[mp_plugin] Received termination signal, exiting...")
+    sys.exit(0)
+
+
+signal.signal(signal.SIGTERM, handle_exit)
+signal.signal(signal.SIGINT, handle_exit)
+
+
+def parse_mp_config() -> dict:
+    """Parse the aggregated MP config from the environment.
+
+    Returns:
+        A dict with keys like ``mp_config``,
+        ``storage_manager_config``, ``obs_config``, etc.
+        Returns an empty dict if the env var is missing or
+        cannot be parsed.
+    """
+    raw = os.getenv("LMCACHE_RUNTIME_PLUGIN_CONFIG", "")
+    if not raw:
+        print("[mp_plugin] WARNING: LMCACHE_RUNTIME_PLUGIN_CONFIG is empty")
+        return {}
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print("[mp_plugin] ERROR: failed to parse config: %s" % exc)
+        return {}
+
+
+def dump_parsed_config(config: dict) -> None:
+    """Dump the parsed aggregated config as compact JSON.
+
+    The parent process captures stdout line-by-line and logs each
+    line separately, so we emit a single-line JSON to keep the
+    output in one log entry.
+    """
+    print("[mp_plugin] config: %s" % json.dumps(config, default=str))
+
+
+def main() -> None:
+    config = parse_mp_config()
+
+    print("[mp_plugin] Started")
+
+    dump_parsed_config(config)
+
+    # --- Periodic status reporter loop ---
+    loop_count = 0
+    while True:
+        print("[mp_plugin] heartbeat #%d" % loop_count)
+        loop_count += 1
+        time.sleep(30)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/multi_process/lmcache-daemonset.yaml b/examples/multi_process/lmcache-daemonset.yaml
new file mode 100644
index 0000000..42ce03d
--- /dev/null
+++ b/examples/multi_process/lmcache-daemonset.yaml
@@ -0,0 +1,52 @@
+---
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: lmcache-server
+  namespace: multi-process
+spec:
+  selector:
+    matchLabels:
+      app: lmcache-server
+  template:
+    metadata:
+      labels:
+        app: lmcache-server
+    spec:
+      hostNetwork: true
+      volumes:
+        - name: dev-shm
+          hostPath:
+            path: /dev/shm
+            type: Directory
+      containers:
+        - name: lmcache-server
+          image: lmcache/standalone:nightly
+          command:
+            - /opt/venv/bin/python3
+            - -m
+            - lmcache.v1.multiprocess.server
+            - --host
+            - "0.0.0.0"
+            - --port
+            - "6555"
+            - --l1-size-gb
+            - "60"
+            - --eviction-policy
+            - LRU
+            - --max-workers
+            - "4"
+          volumeMounts:
+            - name: dev-shm
+              mountPath: /dev/shm
+          resources:
+            requests:
+              # 65Gi = 60GB l1-size-gb + ~5GB overhead for Python runtime and server operations
+              memory: "65Gi"
+              cpu: "4"
+            limits:
+              memory: "120Gi"
+              cpu: "8"
+          env:
+            - name: LMCACHE_LOG_LEVEL
+              value: "DEBUG"
diff --git a/examples/multi_process/vllm-deployment.yaml b/examples/multi_process/vllm-deployment.yaml
new file mode 100644
index 0000000..a1ee85b
--- /dev/null
+++ b/examples/multi_process/vllm-deployment.yaml
@@ -0,0 +1,63 @@
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-deployment
+  namespace: multi-process
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-deployment
+  template:
+    metadata:
+      labels:
+        app: vllm-deployment
+    spec:
+      volumes:
+        - name: dshm
+          hostPath:
+            path: /dev/shm
+            type: Directory
+      containers:
+        - name: vllm
+          volumeMounts:
+            - name: dshm
+              mountPath: /dev/shm
+          image: lmcache/vllm-openai:latest-nightly
+          command:
+            - /bin/bash
+            - -c
+            - |
+              vllm serve Qwen/Qwen3-14B \
+                --host 0.0.0.0 \
+                --port 8000 \
+                --no-enable-prefix-caching \
+                --max-model-len 32768 \
+                --gpu-memory-utilization 0.85 \
+                --tensor-parallel-size 4 \
+                --kv-transfer-config "{\"kv_connector\":\"LMCacheMPConnector\", \"kv_role\":\"kv_both\", \"kv_connector_extra_config\": {\"lmcache.mp.host\": \"tcp://${HOST_IP}\", \"lmcache.mp.port\": 6555}}"
+          env:
+            - name: HOST_IP
+              valueFrom:
+                fieldRef:
+                  fieldPath: status.hostIP
+            - name: PYTHONHASHSEED
+              value: "0"
+            - name: PROMETHEUS_MULTIPROC_DIR
+              value: "/tmp"
+          resources:
+            limits:
+              nvidia.com/gpu: "4"
+            requests:
+              nvidia.com/gpu: "4"
+          startupProbe:
+            failureThreshold: 60
+            httpGet:
+              path: /health
+              port: 8000
+              scheme: HTTP
+            initialDelaySeconds: 30
+            periodSeconds: 10
+            successThreshold: 1
+            timeoutSeconds: 1
diff --git a/examples/observability/README.md b/examples/observability/README.md
new file mode 100644
index 0000000..f422b37
--- /dev/null
+++ b/examples/observability/README.md
@@ -0,0 +1,152 @@
+# LMCache Observability Example
+
+Minimal example showing per-request OTel tracing and metrics for LMCache + vLLM,
+visualized in Grafana.
+
+## Stack
+
+```
+LMCache / vLLM
+  └─ OTLP gRPC → OTel Collector (:4320)
+                   ├─ traces  → Tempo (:3200)
+                   └─ metrics → Prometheus (:9091)
+                                  └─ Grafana (:3000)
+```
+
+## Step 1 — Start the observability stack
+
+```bash
+cd examples/observability
+docker compose up -d
+```
+
+## Step 2 — Start LMCache + vLLM
+
+```bash
+MODEL=/your/model/path bash start-server.sh
+```
+ 
+
+## Step 3 — Send requests to populate traces
+
+```bash
+# Run a short long-doc-qa benchmark: first query is a miss, subsequent
+# queries against the same document are cache hits.
+lmcache bench engine \
+  --engine-url http://localhost:8100 \
+  --workload long-doc-qa \
+  --kv-cache-volume 1 \
+  --ldqa-query-per-document 10
+```
+
+## Step 4 — Visualize in Grafana
+
+Open **http://localhost:3000** → **Explore** → datasource **Tempo**.
+
+```
+# All request root spans
+{ name = "request" }
+
+# Filter to a specific session
+{ name = "request" && span.session_id = "<request_id>" }
+
+# Only cache-hit requests (had a retrieve)
+{ name = "request" } >> { name = "mp.retrieve" }
+
+# Requests with less than 50 % cache hit rate
+{ name = "request" && span.hit_rate < 0.5 }
+
+# Full cache hits only
+{ name = "request" && span.hit_rate = 1.0 }
+
+# Complete misses (lookup ran but nothing was cached)
+{ name = "request" && span.requested_tokens > 0 && span.hit_tokens = 0 }
+```
+
+Click any trace to open the waterfall. Each root `request` span carries three
+per-request cache hit rate attributes:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `hit_tokens` | int | tokens served from L1+L2 cache |
+| `requested_tokens` | int | total chunk-aligned tokens submitted for lookup |
+| `hit_rate` | float | `hit_tokens / requested_tokens` (0.0 on a total miss) |
+
+```
+request  [══════════════════════════════════════]  hit_rate=0.75
+  mp.lookup_prefetch  [════]
+  mp.retrieve               [════════]
+  mp.store                            [══════]
+```
+
+Store-only requests (no lookup phase) do not carry these attributes.
+
+The pre-provisioned **LMCache** dashboard under **Dashboards** shows cache hit
+rate, StorageManager read/write rates, and the live trace panel. The collapsed
+**CacheBlend** row adds blend-server panels (see below).
+
+## CacheBlend (blend server) traces
+
+When LMCache runs the **blend** engine (`lmcache server --engine-type blend`),
+CacheBlend V3 emits its own span tree to Tempo alongside the standard spans.
+Expand the collapsed **CacheBlend** row on the dashboard, or query Tempo:
+
+```
+# All CacheBlend request traces
+{ name = "cb.request" }
+
+# Requests that actually blended non-prefix (shifted) KV
+{ name = "cb.request" && span.non_prefix_hit_tokens > 0 }
+
+# The token-scatter GPU step
+{ name = "cb.scatter" }
+```
+
+Click a `cb.request` row to open the waterfall:
+
+```
+cb.request
+  cb.lookup                (attr prefix_chunks; prefix timing is in mp.lookup_prefetch)
+    cb.fingerprint_match   match probe hashes vs stored fingerprints
+    cb.sparse_prefetch     non-prefix (shifted) chunks, sparse L2->L1
+                           (emitted only on an actual L2 load; carries l2_keys)
+  cb.retrieve
+    cb.scatter             L1 -> paged KV per-token slot-scatter + re-RoPE
+  cb.store_pre_computed
+  cb.store_final
+```
+
+The root `cb.request` span carries the V3 hit-rate breakdown
+(`hit_rate = prefix + non-prefix`):
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `prefix_hit_tokens` | int | tokens reused from the prefix (L1+L2) |
+| `non_prefix_hit_tokens` | int | tokens reused from sparse non-prefix chunks |
+| `hit_tokens` | int | `prefix_hit_tokens + non_prefix_hit_tokens` |
+| `requested_tokens` | int | total chunk-aligned tokens submitted |
+| `hit_rate` | float | `hit_tokens / requested_tokens` |
+| `prefix_hit_rate` | float | `prefix_hit_tokens / requested_tokens` |
+| `non_prefix_hit_rate` | float | `non_prefix_hit_tokens / requested_tokens` (sums to `hit_rate`) |
+
+The **CacheBlend Hit Rate & Chunks** panel overlays the overall token hit rate
+(Prometheus) with the per-request prefix/non-prefix breakdown via
+[TraceQL metrics](https://grafana.com/docs/tempo/latest/metrics-from-traces/),
+served by Tempo's `local-blocks` metrics generator (enabled in `tempo.yml`):
+
+```
+# prefix vs non-prefix hit rate over time
+{ name = "cb.request" } | avg_over_time(span.prefix_hit_rate)
+{ name = "cb.request" } | avg_over_time(span.non_prefix_hit_rate)
+```
+
+## Files
+
+```
+docker-compose.yml          — 4-service stack (collector, tempo, prometheus, grafana)
+otel-collector.yml          — OTLP receiver → Tempo + Prometheus fan-out
+tempo.yml                   — local trace storage + local-blocks TraceQL metrics
+prometheus.yml              — scrapes lmcache metrics from collector
+grafana/provisioning/       — auto-provisioned datasources + dashboard
+start-server.sh             — launches LMCache server + vLLM with OTLP enabled
+```
diff --git a/examples/observability/docker-compose.yml b/examples/observability/docker-compose.yml
new file mode 100644
index 0000000..c5a5f76
--- /dev/null
+++ b/examples/observability/docker-compose.yml
@@ -0,0 +1,70 @@
+services:
+
+  # OTel Collector — receives OTLP from LMCache, fans out to Tempo + Prometheus
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    container_name: obs_otel_collector
+    volumes:
+      - ./otel-collector.yml:/etc/otel-collector.yml:ro
+    command: ["--config=/etc/otel-collector.yml"]
+    ports:
+      - "4320:4317"   # OTLP gRPC (LMCache sends here)
+      - "8889:8889"   # Prometheus scrape endpoint
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      - tempo
+    restart: unless-stopped
+
+  # Tempo — trace storage
+  tempo:
+    image: grafana/tempo:2.7.2
+    container_name: obs_tempo
+    volumes:
+      - ./tempo.yml:/etc/tempo.yml:ro
+      - tempo_data:/var/tempo
+    command: ["-config.file=/etc/tempo.yml"]
+    ports:
+      - "3200:3200"
+    restart: unless-stopped
+
+  # Prometheus — metrics storage
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: obs_prometheus
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus_data:/prometheus
+    ports:
+      - "9091:9090"
+    command:
+      - "--config.file=/etc/prometheus/prometheus.yml"
+      - "--storage.tsdb.retention.time=7d"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      - otel-collector
+    restart: unless-stopped
+
+  # Grafana — UI (anonymous access, no login required)
+  grafana:
+    image: grafana/grafana:latest
+    container_name: obs_grafana
+    volumes:
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+      - grafana_data:/var/lib/grafana
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_AUTH_DISABLE_LOGIN_FORM=true
+    depends_on:
+      - prometheus
+      - tempo
+    restart: unless-stopped
+
+volumes:
+  tempo_data:
+  prometheus_data:
+  grafana_data:
diff --git a/examples/observability/grafana/provisioning/dashboards/dashboards.yml b/examples/observability/grafana/provisioning/dashboards/dashboards.yml
new file mode 100644
index 0000000..9984de5
--- /dev/null
+++ b/examples/observability/grafana/provisioning/dashboards/dashboards.yml
@@ -0,0 +1,9 @@
+apiVersion: 1
+
+providers:
+  - name: lmcache
+    type: file
+    disableDeletion: false
+    updateIntervalSeconds: 10
+    options:
+      path: /etc/grafana/provisioning/dashboards
diff --git a/examples/observability/grafana/provisioning/dashboards/lmcache.json b/examples/observability/grafana/provisioning/dashboards/lmcache.json
new file mode 100644
index 0000000..c77db8d
--- /dev/null
+++ b/examples/observability/grafana/provisioning/dashboards/lmcache.json
@@ -0,0 +1,2791 @@
+{
+  "annotations": {
+    "list": [
+      {
+        "builtIn": 1,
+        "datasource": {
+          "type": "grafana",
+          "uid": "-- Grafana --"
+        },
+        "enable": true,
+        "hide": true,
+        "iconColor": "rgba(0, 211, 255, 1)",
+        "name": "Annotations & Alerts",
+        "type": "dashboard"
+      }
+    ]
+  },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "links": [],
+  "panels": [
+    {
+      "collapsed": false,
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 0
+      },
+      "id": 100,
+      "title": "System Health",
+      "type": "row"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Rate of L1 allocation failures (OOM), L1 read failures, and L2 prefetch failures. Non-zero values indicate unhealthy cache operations.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "red",
+                "value": 1
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 1
+      },
+      "id": 1,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": true,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "sum by (service_instance_id) (rate(lmcache_mp_l1_allocation_failure_chunks_total[$__rate_interval])) or vector(0)",
+          "legendFormat": "L1 alloc failure [{{service_instance_id}}]",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "sum by (service_instance_id) (rate(lmcache_mp_l1_read_failure_chunks_total[$__rate_interval])) or vector(0)",
+          "legendFormat": "L1 read failure [{{service_instance_id}}]",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "sum by (service_instance_id) (rate(lmcache_mp_l2_prefetch_failure_chunks_total[$__rate_interval])) or vector(0)",
+          "legendFormat": "L2 prefetch failure [{{service_instance_id}}]",
+          "refId": "C"
+        }
+      ],
+      "title": "Failure Rates",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L1 eviction loop iterations and triggered runs per second.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 1
+      },
+      "id": 9,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_eviction_loop_ticks_total[$__rate_interval])",
+          "legendFormat": "eviction loop ticks/s",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_eviction_loop_triggered_total[$__rate_interval])",
+          "legendFormat": "eviction loop triggered/s",
+          "refId": "B"
+        }
+      ],
+      "title": "L1 Eviction Loop",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L1 cache memory consumption in bytes and usage ratio (0\u20131).",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              },
+              {
+                "color": "red",
+                "value": 0.9
+              }
+            ]
+          }
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/L1 memory bytes/"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "bytes"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "left"
+              }
+            ]
+          },
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/L1 usage ratio/"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "percentunit"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              },
+              {
+                "id": "min",
+                "value": 0
+              },
+              {
+                "id": "max",
+                "value": 1
+              }
+            ]
+          }
+        ]
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 9
+      },
+      "id": 2,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_l1_memory_usage_bytes",
+          "legendFormat": "L1 memory bytes [{{service_instance_id}}]",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_l1_usage_ratio",
+          "legendFormat": "L1 usage ratio [{{service_instance_id}}]",
+          "refId": "B"
+        }
+      ],
+      "title": "L1 Memory Usage",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L1 cache key-level operations: reads, writes, and evictions per second.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 9
+      },
+      "id": 7,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_read_chunks_total[$__rate_interval])",
+          "legendFormat": "L1 reads/s [{{service_instance_id}}]",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_write_chunks_total[$__rate_interval])",
+          "legendFormat": "L1 writes/s [{{service_instance_id}}]",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_evicted_chunks_total[$__rate_interval])",
+          "legendFormat": "L1 evictions/s [{{service_instance_id}}]",
+          "refId": "C"
+        }
+      ],
+      "title": "L1 Cache Operations",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L2 store pipeline: tasks submitted vs completed, and keys succeeded vs failed.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "failed keys/s"
+            },
+            "properties": [
+              {
+                "id": "color",
+                "value": {
+                  "fixedColor": "red",
+                  "mode": "fixed"
+                }
+              }
+            ]
+          }
+        ]
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 17
+      },
+      "id": 3,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": true,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_store_submitted_requests_total[$__rate_interval])",
+          "legendFormat": "tasks submitted/s",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_store_completed_requests_total[$__rate_interval])",
+          "legendFormat": "tasks completed/s ({{l2_name}})",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_store_submitted_objects_chunks_total[$__rate_interval])",
+          "legendFormat": "keys submitted/s",
+          "refId": "C"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_store_completed_objects_chunks_total[$__rate_interval])",
+          "legendFormat": "succeeded keys/s",
+          "refId": "D"
+        }
+      ],
+      "title": "L2 Store Pipeline",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L2 prefetch pipeline: lookups submitted, keys looked up vs hit, load tasks, keys loaded vs failed.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byName",
+              "options": "failed keys/s"
+            },
+            "properties": [
+              {
+                "id": "color",
+                "value": {
+                  "fixedColor": "red",
+                  "mode": "fixed"
+                }
+              }
+            ]
+          }
+        ]
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 17
+      },
+      "id": 4,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": true,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_prefetch_lookup_requests_total[$__rate_interval])",
+          "legendFormat": "lookups/s",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_prefetch_lookup_objects_chunks_total[$__rate_interval])",
+          "legendFormat": "lookup keys/s",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_prefetch_hit_chunks_total[$__rate_interval])",
+          "legendFormat": "hit keys/s",
+          "refId": "C"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_prefetch_load_submitted_requests_total[$__rate_interval])",
+          "legendFormat": "load tasks/s",
+          "refId": "D"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_prefetch_load_submitted_objects_chunks_total[$__rate_interval])",
+          "legendFormat": "load keys submitted/s",
+          "refId": "E"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_prefetch_load_completed_chunks_total[$__rate_interval])",
+          "legendFormat": "loaded keys/s",
+          "refId": "F"
+        },
+        {
+          "editorMode": "code",
+          "expr": "sum(rate(lmcache_mp_l2_prefetch_failure_chunks_total[$__rate_interval]))",
+          "legendFormat": "failed keys/s",
+          "refId": "G"
+        }
+      ],
+      "title": "L2 Prefetch Pipeline",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Current in-flight L2 store tasks, L2 load tasks, active prefetch jobs, and reserved memory for in-flight loads.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/inflight load memory/"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "bytes"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              }
+            ]
+          }
+        ]
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 25
+      },
+      "id": 5,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_num_inflight_l2_stores",
+          "legendFormat": "inflight L2 stores ({{l2_name}}) [{{service_instance_id}}]",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_num_inflight_l2_loads",
+          "legendFormat": "inflight L2 loads ({{l2_name}}) [{{service_instance_id}}]",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_active_prefetch_jobs",
+          "legendFormat": "active prefetch jobs [{{service_instance_id}}]",
+          "refId": "C"
+        },
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_inflight_load_memory_usage_bytes",
+          "legendFormat": "inflight load memory [{{service_instance_id}}]",
+          "refId": "D"
+        }
+      ],
+      "title": "Inflight Operations",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "EventBus queue depth, drain lag, dropped events, and subscriber exceptions.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 1,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/drain lag/"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "s"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              }
+            ]
+          }
+        ]
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 25
+      },
+      "id": 6,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_event_bus_queue_depth",
+          "legendFormat": "event bus queue depth",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_event_bus_drain_lag_seconds",
+          "legendFormat": "drain lag",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_event_bus_dropped_events_total[$__rate_interval])",
+          "legendFormat": "dropped events/s",
+          "refId": "C"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_event_bus_subscriber_exceptions_total[$__rate_interval])",
+          "legendFormat": "subscriber exceptions/s ({{subscriber_name}})",
+          "refId": "D"
+        }
+      ],
+      "title": "Event Bus",
+      "type": "timeseries"
+    },
+    {
+      "collapsed": false,
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 33
+      },
+      "id": 200,
+      "title": "Performance",
+      "type": "row"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Average L0 (GPU) to L1 (CPU) transfer throughput per request, measured on the GPU cupy stream.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "GB/s",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "GBs"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 34
+      },
+      "id": 10,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l0_l1_store_throughput_GB_per_second_sum[$__rate_interval]) / rate(lmcache_mp_l0_l1_store_throughput_GB_per_second_count[$__rate_interval])",
+          "legendFormat": "L0\u2192L1 store ({{device}})",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l0_l1_load_throughput_GB_per_second_sum[$__rate_interval]) / rate(lmcache_mp_l0_l1_load_throughput_GB_per_second_count[$__rate_interval])",
+          "legendFormat": "L1\u2192L0 load ({{device}})",
+          "refId": "B"
+        }
+      ],
+      "title": "L0 \u2194 L1 Throughput (GB/s)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Average L1 (CPU) to L2 (remote/disk) transfer throughput per task. Includes adapter queue wait + network/disk I/O.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "GB/s",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "GBs"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 34
+      },
+      "id": 11,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_store_throughput_GB_per_second_sum[$__rate_interval]) / rate(lmcache_mp_l2_store_throughput_GB_per_second_count[$__rate_interval])",
+          "legendFormat": "L1\u2192L2 store ({{l2_name}})",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_load_throughput_GB_per_second_sum[$__rate_interval]) / rate(lmcache_mp_l2_load_throughput_GB_per_second_count[$__rate_interval])",
+          "legendFormat": "L2\u2192L1 load ({{l2_name}})",
+          "refId": "B"
+        }
+      ],
+      "title": "L1 \u2194 L2 Throughput (GB/s)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Chunks loaded into the engine, and lookup token counts (requested vs hit).",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "ops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 42
+      },
+      "id": 8,
+      "options": {
+        "legend": {
+          "calcs": [
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_lookup_requested_tokens_total[$__rate_interval])",
+          "legendFormat": "lookup requested tokens/s [{{service_instance_id}}]",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_lookup_hit_tokens_total[$__rate_interval])",
+          "legendFormat": "lookup hit tokens/s [{{service_instance_id}}]",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_num_chunks_loaded_total[$__rate_interval])",
+          "legendFormat": "chunks loaded/s [{{service_instance_id}}]",
+          "refId": "C"
+        }
+      ],
+      "title": "Lookup & Engine Activity",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Token-level cache hit rate: fraction of requested tokens found in L1+L2 during lookup (contiguous prefix hits only).",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "min": 0,
+          "max": 1,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "red",
+                "value": null
+              },
+              {
+                "color": "yellow",
+                "value": 0.5
+              },
+              {
+                "color": "green",
+                "value": 0.8
+              }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 42
+      },
+      "id": 14,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_lookup_hit_tokens_total[$__rate_interval]) / rate(lmcache_mp_lookup_requested_tokens_total[$__rate_interval])",
+          "legendFormat": "L1+L2 token hit rate [{{service_instance_id}}]",
+          "refId": "A"
+        }
+      ],
+      "title": "Cache Hit Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L1 key-level I/O operations per second (reads and writes).",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "iops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 50
+      },
+      "id": 12,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_read_chunks_total[$__rate_interval])",
+          "legendFormat": "L1 read IOPS [{{service_instance_id}}]",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_write_chunks_total[$__rate_interval])",
+          "legendFormat": "L1 write IOPS [{{service_instance_id}}]",
+          "refId": "B"
+        }
+      ],
+      "title": "L1 IOPS",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "L2 adapter-level I/O operations per second (store and load task completions).",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "iops"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 50
+      },
+      "id": 13,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_store_completed_requests_total[$__rate_interval])",
+          "legendFormat": "L2 store IOPS ({{l2_name}})",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l2_load_completed_requests_total[$__rate_interval])",
+          "legendFormat": "L2 load IOPS ({{l2_name}})",
+          "refId": "B"
+        }
+      ],
+      "title": "L2 IOPS",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Current bytes held in each L2 adapter, sampled live from adapter.get_usage(). One line per adapter, tagged by ``l2_name``. Parallel to the L1 ``lmcache_mp_l1_memory_usage_bytes`` gauge.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "bytes"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 58
+      },
+      "id": 16,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "desc"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "lmcache_mp_l2_usage_bytes",
+          "legendFormat": "{{l2_name}}",
+          "refId": "A"
+        }
+      ],
+      "title": "L2 Usage (current)",
+      "type": "timeseries"
+    },
+    {
+      "collapsed": false,
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 66
+      },
+      "id": 300,
+      "title": "Production Insights",
+      "type": "row"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Average GPU KV cache block lifetime, idle time before eviction, and time gap between consecutive accesses.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 67
+      },
+      "id": 20,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l0_block_lifetime_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l0_block_lifetime_seconds_count[$__rate_interval])",
+          "legendFormat": "avg block lifetime",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l0_block_idle_before_evict_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l0_block_idle_before_evict_seconds_count[$__rate_interval])",
+          "legendFormat": "avg idle before evict",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l0_block_reuse_gap_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l0_block_reuse_gap_seconds_count[$__rate_interval])",
+          "legendFormat": "avg reuse gap",
+          "refId": "C"
+        }
+      ],
+      "title": "L0 (GPU) Block Lifecycle",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Average L1 chunk lifetime, idle time before eviction, and time gap between consecutive touches.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 67
+      },
+      "id": 21,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_chunk_lifetime_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l1_chunk_lifetime_seconds_count[$__rate_interval])",
+          "legendFormat": "avg chunk lifetime",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_chunk_idle_before_evict_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l1_chunk_idle_before_evict_seconds_count[$__rate_interval])",
+          "legendFormat": "avg idle before evict",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_chunk_reuse_gap_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l1_chunk_reuse_gap_seconds_count[$__rate_interval])",
+          "legendFormat": "avg reuse gap",
+          "refId": "C"
+        }
+      ],
+      "title": "L1 Chunk Lifecycle",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Time from L1 chunk eviction to next reuse of the same slot. Capped at max_evict_reuse_wait. Helps size the L1 cache: if this is consistently low, more L1 capacity would improve hit rates.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 0,
+        "y": 75
+      },
+      "id": 22,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_l1_chunk_evict_reuse_gap_seconds_sum[$__rate_interval]) / rate(lmcache_mp_l1_chunk_evict_reuse_gap_seconds_count[$__rate_interval])",
+          "legendFormat": "avg evict-to-reuse gap",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "histogram_quantile(0.50, rate(lmcache_mp_l1_chunk_evict_reuse_gap_seconds_bucket[$__rate_interval]))",
+          "legendFormat": "p50 evict-to-reuse gap",
+          "refId": "B"
+        },
+        {
+          "editorMode": "code",
+          "expr": "histogram_quantile(0.95, rate(lmcache_mp_l1_chunk_evict_reuse_gap_seconds_bucket[$__rate_interval]))",
+          "legendFormat": "p95 evict-to-reuse gap",
+          "refId": "C"
+        }
+      ],
+      "title": "L1 Evict-to-Reuse Gap",
+      "type": "timeseries"
+    },
+    {
+      "datasource": {
+        "type": "prometheus",
+        "uid": "prometheus"
+      },
+      "description": "Time and access-count gaps between consecutive reads of the same chunk at the StorageManager level. Tagged by cache_salt. Helps evaluate cache retention effectiveness.",
+      "fieldConfig": {
+        "defaults": {
+          "color": {
+            "mode": "palette-classic"
+          },
+          "custom": {
+            "axisBorderShow": false,
+            "axisCenteredZero": false,
+            "axisColorMode": "text",
+            "axisLabel": "",
+            "axisPlacement": "auto",
+            "barAlignment": 0,
+            "barWidthFactor": 0.6,
+            "drawStyle": "line",
+            "fillOpacity": 10,
+            "gradientMode": "none",
+            "hideFrom": {
+              "legend": false,
+              "tooltip": false,
+              "viz": false
+            },
+            "insertNulls": false,
+            "lineInterpolation": "linear",
+            "lineWidth": 2,
+            "pointSize": 5,
+            "scaleDistribution": {
+              "type": "linear"
+            },
+            "showPoints": "auto",
+            "showValues": false,
+            "spanNulls": false,
+            "stacking": {
+              "group": "A",
+              "mode": "none"
+            },
+            "thresholdsStyle": {
+              "mode": "off"
+            }
+          },
+          "mappings": [],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              {
+                "color": "green",
+                "value": null
+              }
+            ]
+          },
+          "unit": "s"
+        },
+        "overrides": [
+          {
+            "matcher": {
+              "id": "byRegexp",
+              "options": "/chunks/"
+            },
+            "properties": [
+              {
+                "id": "unit",
+                "value": "short"
+              },
+              {
+                "id": "custom.axisPlacement",
+                "value": "right"
+              },
+              {
+                "id": "custom.axisLabel",
+                "value": "chunks"
+              }
+            ]
+          }
+        ]
+      },
+      "gridPos": {
+        "h": 8,
+        "w": 12,
+        "x": 12,
+        "y": 75
+      },
+      "id": 23,
+      "options": {
+        "legend": {
+          "calcs": [
+            "mean",
+            "lastNotNull"
+          ],
+          "displayMode": "table",
+          "placement": "bottom",
+          "showLegend": true
+        },
+        "tooltip": {
+          "hideZeros": false,
+          "mode": "multi",
+          "sort": "none"
+        }
+      },
+      "targets": [
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_real_reuse_gap_seconds_sum[$__rate_interval]) / rate(lmcache_mp_real_reuse_gap_seconds_count[$__rate_interval])",
+          "legendFormat": "avg reuse gap seconds ({{cache_salt}})",
+          "refId": "A"
+        },
+        {
+          "editorMode": "code",
+          "expr": "rate(lmcache_mp_real_reuse_gap_objects_chunks_sum[$__rate_interval]) / rate(lmcache_mp_real_reuse_gap_objects_chunks_count[$__rate_interval])",
+          "legendFormat": "avg reuse gap chunks ({{cache_salt}})",
+          "refId": "B"
+        }
+      ],
+      "title": "SM Real Reuse Gap",
+      "type": "timeseries"
+    },
+    {
+      "collapsed": true,
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 83
+      },
+      "id": 400,
+      "title": "CacheBlend (expand if using blend_server)",
+      "type": "row",
+      "panels": [
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prometheus"
+          },
+          "description": "CacheBlend lookup, retrieve, and store operation rates including success, failure, and hit metrics.",
+          "fieldConfig": {
+            "defaults": {
+              "color": {
+                "mode": "palette-classic"
+              },
+              "custom": {
+                "axisBorderShow": false,
+                "axisCenteredZero": false,
+                "axisColorMode": "text",
+                "axisLabel": "",
+                "axisPlacement": "auto",
+                "barAlignment": 0,
+                "barWidthFactor": 0.6,
+                "drawStyle": "line",
+                "fillOpacity": 10,
+                "gradientMode": "none",
+                "hideFrom": {
+                  "legend": false,
+                  "tooltip": false,
+                  "viz": false
+                },
+                "insertNulls": false,
+                "lineInterpolation": "linear",
+                "lineWidth": 1,
+                "pointSize": 5,
+                "scaleDistribution": {
+                  "type": "linear"
+                },
+                "showPoints": "auto",
+                "showValues": false,
+                "spanNulls": false,
+                "stacking": {
+                  "group": "A",
+                  "mode": "none"
+                },
+                "thresholdsStyle": {
+                  "mode": "off"
+                }
+              },
+              "mappings": [],
+              "thresholds": {
+                "mode": "absolute",
+                "steps": [
+                  {
+                    "color": "green",
+                    "value": null
+                  }
+                ]
+              },
+              "unit": "ops"
+            },
+            "overrides": [
+              {
+                "matcher": {
+                  "id": "byRegexp",
+                  "options": "/failure/"
+                },
+                "properties": [
+                  {
+                    "id": "color",
+                    "value": {
+                      "fixedColor": "red",
+                      "mode": "fixed"
+                    }
+                  }
+                ]
+              }
+            ]
+          },
+          "gridPos": {
+            "h": 8,
+            "w": 12,
+            "x": 0,
+            "y": 84
+          },
+          "id": 30,
+          "options": {
+            "legend": {
+              "calcs": [
+                "lastNotNull"
+              ],
+              "displayMode": "table",
+              "placement": "bottom",
+              "showLegend": true
+            },
+            "tooltip": {
+              "hideZeros": true,
+              "mode": "multi",
+              "sort": "desc"
+            }
+          },
+          "targets": [
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_lookup_requests_total[$__rate_interval])",
+              "legendFormat": "lookup requests/s",
+              "refId": "A"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_lookup_fingerprint_hits_total[$__rate_interval])",
+              "legendFormat": "fingerprint hits/s",
+              "refId": "B"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_lookup_storage_hits_total[$__rate_interval])",
+              "legendFormat": "storage hits/s",
+              "refId": "C"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_lookup_stale_chunks_total[$__rate_interval])",
+              "legendFormat": "stale chunks/s",
+              "refId": "D"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_store_pre_computed_requests_total[$__rate_interval])",
+              "legendFormat": "store_pre_computed requests/s",
+              "refId": "E"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_store_final_requests_total[$__rate_interval])",
+              "legendFormat": "store_final requests/s",
+              "refId": "F"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_retrieve_requests_total[$__rate_interval])",
+              "legendFormat": "retrieve requests/s",
+              "refId": "G"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_retrieve_failures_total[$__rate_interval])",
+              "legendFormat": "retrieve failure/s",
+              "refId": "H"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_store_pre_computed_failures_total[$__rate_interval])",
+              "legendFormat": "store_pre_computed failure/s",
+              "refId": "I"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_store_final_failures_total[$__rate_interval])",
+              "legendFormat": "store_final failure/s",
+              "refId": "J"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_lookup_no_gpu_context_errors_total[$__rate_interval])",
+              "legendFormat": "no GPU context errors/s",
+              "refId": "K"
+            }
+          ],
+          "title": "CacheBlend Operations",
+          "type": "timeseries"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prometheus"
+          },
+          "description": "Overall blend token hit rate (left, %) and chunk throughput (right, ops/s). Prometheus.",
+          "fieldConfig": {
+            "defaults": {
+              "color": {
+                "mode": "palette-classic"
+              },
+              "custom": {
+                "axisBorderShow": false,
+                "axisCenteredZero": false,
+                "axisColorMode": "text",
+                "axisLabel": "",
+                "axisPlacement": "auto",
+                "barAlignment": 0,
+                "barWidthFactor": 0.6,
+                "drawStyle": "line",
+                "fillOpacity": 10,
+                "gradientMode": "none",
+                "hideFrom": {
+                  "legend": false,
+                  "tooltip": false,
+                  "viz": false
+                },
+                "insertNulls": false,
+                "lineInterpolation": "linear",
+                "lineWidth": 2,
+                "pointSize": 5,
+                "scaleDistribution": {
+                  "type": "linear"
+                },
+                "showPoints": "auto",
+                "showValues": false,
+                "spanNulls": false,
+                "stacking": {
+                  "group": "A",
+                  "mode": "none"
+                },
+                "thresholdsStyle": {
+                  "mode": "off"
+                }
+              },
+              "mappings": [],
+              "min": 0,
+              "unit": "percentunit",
+              "thresholds": {
+                "mode": "absolute",
+                "steps": [
+                  {
+                    "color": "green",
+                    "value": null
+                  }
+                ]
+              }
+            },
+            "overrides": [
+              {
+                "matcher": {
+                  "id": "byFrameRefID",
+                  "options": "B"
+                },
+                "properties": [
+                  {
+                    "id": "unit",
+                    "value": "ops"
+                  },
+                  {
+                    "id": "custom.axisPlacement",
+                    "value": "right"
+                  },
+                  {
+                    "id": "custom.axisLabel",
+                    "value": "chunks/s"
+                  }
+                ]
+              },
+              {
+                "matcher": {
+                  "id": "byFrameRefID",
+                  "options": "C"
+                },
+                "properties": [
+                  {
+                    "id": "unit",
+                    "value": "ops"
+                  },
+                  {
+                    "id": "custom.axisPlacement",
+                    "value": "right"
+                  },
+                  {
+                    "id": "custom.axisLabel",
+                    "value": "chunks/s"
+                  }
+                ]
+              },
+              {
+                "matcher": {
+                  "id": "byFrameRefID",
+                  "options": "D"
+                },
+                "properties": [
+                  {
+                    "id": "unit",
+                    "value": "ops"
+                  },
+                  {
+                    "id": "custom.axisPlacement",
+                    "value": "right"
+                  },
+                  {
+                    "id": "custom.axisLabel",
+                    "value": "chunks/s"
+                  }
+                ]
+              },
+              {
+                "matcher": {
+                  "id": "byFrameRefID",
+                  "options": "E"
+                },
+                "properties": [
+                  {
+                    "id": "unit",
+                    "value": "ops"
+                  },
+                  {
+                    "id": "custom.axisPlacement",
+                    "value": "right"
+                  },
+                  {
+                    "id": "custom.axisLabel",
+                    "value": "chunks/s"
+                  }
+                ]
+              },
+              {
+                "matcher": {
+                  "id": "byFrameRefID",
+                  "options": "F"
+                },
+                "properties": [
+                  {
+                    "id": "unit",
+                    "value": "ops"
+                  },
+                  {
+                    "id": "custom.axisPlacement",
+                    "value": "right"
+                  },
+                  {
+                    "id": "custom.axisLabel",
+                    "value": "chunks/s"
+                  }
+                ]
+              }
+            ]
+          },
+          "gridPos": {
+            "h": 8,
+            "w": 12,
+            "x": 12,
+            "y": 84
+          },
+          "id": 31,
+          "options": {
+            "legend": {
+              "calcs": [
+                "mean",
+                "lastNotNull"
+              ],
+              "displayMode": "table",
+              "placement": "bottom",
+              "showLegend": true
+            },
+            "tooltip": {
+              "hideZeros": false,
+              "mode": "multi",
+              "sort": "none"
+            }
+          },
+          "targets": [
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_lookup_hit_tokens_total[$__rate_interval]) / rate(lmcache_blend_lookup_requested_tokens_total[$__rate_interval])",
+              "legendFormat": "blend token hit rate",
+              "refId": "A"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_retrieve_chunks_total[$__rate_interval])",
+              "legendFormat": "retrieve chunks/s",
+              "refId": "B"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_store_pre_computed_chunks_total[$__rate_interval])",
+              "legendFormat": "store_pre_computed chunks/s",
+              "refId": "C"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_store_final_chunks_total[$__rate_interval])",
+              "legendFormat": "store_final chunks/s",
+              "refId": "D"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_fingerprints_registered_total[$__rate_interval])",
+              "legendFormat": "fingerprints registered chunks/s",
+              "refId": "E"
+            },
+            {
+              "editorMode": "code",
+              "expr": "rate(lmcache_blend_chunks_evicted_total[$__rate_interval])",
+              "legendFormat": "evicted chunks/s",
+              "refId": "F"
+            }
+          ],
+          "title": "CacheBlend Hit Rate & Chunks",
+          "type": "timeseries"
+        },
+        {
+          "datasource": {
+            "type": "prometheus",
+            "uid": "prometheus"
+          },
+          "description": "Prefix vs non-prefix token hit rate (each / requested tokens; they sum to the overall hit rate). Prometheus.",
+          "fieldConfig": {
+            "defaults": {
+              "color": {
+                "mode": "palette-classic"
+              },
+              "custom": {
+                "axisBorderShow": false,
+                "axisCenteredZero": false,
+                "axisColorMode": "text",
+                "axisLabel": "",
+                "axisPlacement": "auto",
+                "barAlignment": 0,
+                "barWidthFactor": 0.6,
+                "drawStyle": "line",
+                "fillOpacity": 10,
+                "gradientMode": "none",
+                "hideFrom": {
+                  "legend": false,
+                  "tooltip": false,
+                  "viz": false
+                },
+                "insertNulls": false,
+                "lineInterpolation": "linear",
+                "lineWidth": 2,
+                "pointSize": 5,
+                "scaleDistribution": {
+                  "type": "linear"
+                },
+                "showPoints": "auto",
+                "showValues": false,
+                "spanNulls": false,
+                "stacking": {
+                  "group": "A",
+                  "mode": "none"
+                },
+                "thresholdsStyle": {
+                  "mode": "off"
+                }
+              },
+              "mappings": [],
+              "min": 0,
+              "unit": "percentunit",
+              "thresholds": {
+                "mode": "absolute",
+                "steps": [
+                  {
+                    "color": "green",
+                    "value": null
+                  }
+                ]
+              }
+            },
+            "overrides": []
+          },
+          "gridPos": {
+            "h": 8,
+            "w": 24,
+            "x": 0,
+            "y": 92
+          },
+          "id": 34,
+          "options": {
+            "legend": {
+              "calcs": [
+                "mean",
+                "lastNotNull"
+              ],
+              "displayMode": "table",
+              "placement": "bottom",
+              "showLegend": true
+            },
+            "tooltip": {
+              "hideZeros": false,
+              "mode": "multi",
+              "sort": "none"
+            }
+          },
+          "targets": [
+            {
+              "datasource": {
+                "type": "prometheus",
+                "uid": "prometheus"
+              },
+              "editorMode": "code",
+              "refId": "A",
+              "expr": "rate(lmcache_blend_lookup_prefix_hit_tokens_total[$__rate_interval]) / rate(lmcache_blend_lookup_requested_tokens_total[$__rate_interval])",
+              "legendFormat": "prefix hit rate"
+            },
+            {
+              "datasource": {
+                "type": "prometheus",
+                "uid": "prometheus"
+              },
+              "editorMode": "code",
+              "refId": "B",
+              "expr": "rate(lmcache_blend_lookup_non_prefix_hit_tokens_total[$__rate_interval]) / rate(lmcache_blend_lookup_requested_tokens_total[$__rate_interval])",
+              "legendFormat": "non-prefix hit rate"
+            }
+          ],
+          "title": "CacheBlend prefix vs non-prefix hit rate",
+          "type": "timeseries"
+        },
+        {
+          "datasource": {
+            "uid": "tempo"
+          },
+          "description": "Waterfall of CacheBlend (blend server) request spans: cb.request \u2192 cb.lookup {cb.fingerprint_match, cb.sparse_prefetch}, cb.retrieve {cb.scatter}, cb.store_pre_computed, cb.store_final. Click a row for the full Tempo waterfall.",
+          "fieldConfig": {
+            "defaults": {},
+            "overrides": []
+          },
+          "gridPos": {
+            "h": 12,
+            "w": 24,
+            "x": 0,
+            "y": 100
+          },
+          "id": 51,
+          "options": {
+            "dedupStrategy": "none",
+            "sortBy": [
+              {
+                "desc": true,
+                "displayName": "Start time"
+              }
+            ],
+            "spanFilters": {
+              "criticalPathOnly": false,
+              "matchesOnly": false
+            }
+          },
+          "targets": [
+            {
+              "limit": 20,
+              "query": "{ name = \"cb.request\" }",
+              "queryType": "traceql",
+              "refId": "A"
+            }
+          ],
+          "title": "CacheBlend Request Traces",
+          "type": "traces"
+        }
+      ]
+    },
+    {
+      "collapsed": false,
+      "gridPos": {
+        "h": 1,
+        "w": 24,
+        "x": 0,
+        "y": 84
+      },
+      "id": 500,
+      "title": "Request Traces",
+      "type": "row"
+    },
+    {
+      "datasource": {
+        "uid": "tempo"
+      },
+      "description": "Waterfall view of per-request spans. Each trace shows the root 'request' span with child spans: mp.lookup_prefetch, mp.retrieve, mp.store. Click a row to open the full waterfall in Tempo.",
+      "fieldConfig": {
+        "defaults": {},
+        "overrides": []
+      },
+      "gridPos": {
+        "h": 12,
+        "w": 24,
+        "x": 0,
+        "y": 85
+      },
+      "id": 50,
+      "options": {
+        "dedupStrategy": "none",
+        "sortBy": [
+          {
+            "desc": true,
+            "displayName": "Start time"
+          }
+        ],
+        "spanFilters": {
+          "criticalPathOnly": false,
+          "matchesOnly": false
+        }
+      },
+      "targets": [
+        {
+          "limit": 20,
+          "query": "{ name = \"request\" }",
+          "queryType": "traceql",
+          "refId": "A"
+        }
+      ],
+      "title": "Request Traces",
+      "type": "traces"
+    }
+  ],
+  "preload": false,
+  "refresh": "5s",
+  "schemaVersion": 42,
+  "tags": [],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-1h",
+    "to": "now"
+  },
+  "timepicker": {},
+  "timezone": "browser",
+  "title": "LMCache",
+  "uid": "lmcache-standard",
+  "version": 8,
+  "weekStart": ""
+}
diff --git a/examples/observability/grafana/provisioning/datasources/datasources.yml b/examples/observability/grafana/provisioning/datasources/datasources.yml
new file mode 100644
index 0000000..5df0ad9
--- /dev/null
+++ b/examples/observability/grafana/provisioning/datasources/datasources.yml
@@ -0,0 +1,20 @@
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    uid: prometheus
+    url: http://prometheus:9090
+    isDefault: true
+    jsonData:
+      timeInterval: "5s"
+
+  - name: Tempo
+    type: tempo
+    uid: tempo
+    url: http://tempo:3200
+    jsonData:
+      serviceMap:
+        datasourceUid: prometheus
+      nodeGraph:
+        enabled: true
diff --git a/examples/observability/otel-collector.yml b/examples/observability/otel-collector.yml
new file mode 100644
index 0000000..7f5cf8d
--- /dev/null
+++ b/examples/observability/otel-collector.yml
@@ -0,0 +1,25 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317   # LMCache connects here (host port 4320 → 4317)
+
+exporters:
+  otlp/tempo:
+    endpoint: tempo:4317
+    tls:
+      insecure: true
+
+  prometheus:
+    endpoint: 0.0.0.0:8889
+    resource_to_telemetry_conversion:
+      enabled: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [otlp/tempo]
+    metrics:
+      receivers: [otlp]
+      exporters: [prometheus]
diff --git a/examples/observability/prometheus.yml b/examples/observability/prometheus.yml
new file mode 100644
index 0000000..8ec62e6
--- /dev/null
+++ b/examples/observability/prometheus.yml
@@ -0,0 +1,8 @@
+global:
+  scrape_interval: 5s
+
+scrape_configs:
+  # LMCache metrics re-exposed by the OTel Collector
+  - job_name: lmcache
+    static_configs:
+      - targets: ["otel-collector:8889"]
diff --git a/examples/observability/start-server.sh b/examples/observability/start-server.sh
new file mode 100644
index 0000000..ca346da
--- /dev/null
+++ b/examples/observability/start-server.sh
@@ -0,0 +1,78 @@
+#!/bin/bash
+# Start LMCache MP server + vLLM with OTLP tracing enabled.
+#
+# Overridable env vars:
+#   MODEL            model path
+#   GPU              CUDA device id       (default: 0)
+#   VLLM_PORT        vLLM serve port      (default: 8100)
+#   LMCACHE_MP_PORT  LMCache server port  (default: 6567)
+#   MAX_MODEL_LEN                         (default: 131072)
+#   GPU_MEM_UTIL                          (default: 0.5)
+#   TENSOR_PARALLEL                       (default: 1)
+#   OTLP_ENDPOINT    OTel collector gRPC  (default: http://localhost:4320)
+
+set -euo pipefail
+
+BGPIDS=()
+cleanup() {
+  echo "Shutting down..."
+  for pid in "${BGPIDS[@]}"; do kill "$pid" 2>/dev/null; done
+  wait 2>/dev/null
+}
+trap cleanup INT TERM EXIT
+
+MODEL="${MODEL:-/.cache/huggingface/hub/model}"
+GPU="${GPU:-0}"
+VLLM_PORT="${VLLM_PORT:-8100}"
+LMCACHE_MP_PORT="${LMCACHE_MP_PORT:-6567}"
+TENSOR_PARALLEL="${TENSOR_PARALLEL:-1}"
+MAX_MODEL_LEN="${MAX_MODEL_LEN:-131072}"
+GPU_MEM_UTIL="${GPU_MEM_UTIL:-0.5}"
+OTLP_ENDPOINT="${OTLP_ENDPOINT:-http://localhost:4320}"
+ 
+
+echo "=== LMCache + vLLM with OTLP tracing ==="
+echo "  Model:          ${MODEL}"
+echo "  GPU:            ${GPU}  vLLM port: ${VLLM_PORT}"
+echo "  LMCache port:   ${LMCACHE_MP_PORT}"
+echo "  OTLP endpoint:  ${OTLP_ENDPOINT}"
+
+# ---------------------------------------------------------------------------
+# 1. LMCache server
+# ---------------------------------------------------------------------------
+OTEL_SERVICE_NAME=lmcache \
+  lmcache server \
+  --port "${LMCACHE_MP_PORT}" \
+  --l1-size 20 \
+  --eviction-policy LRU \
+  --chunk-size 256 \
+  --otlp-endpoint "${OTLP_ENDPOINT}" \
+  --enable-tracing \
+  2>&1 | sed 's/^/[lmcache] /' &
+BGPIDS+=($!)
+sleep 5
+
+# ---------------------------------------------------------------------------
+# 2. vLLM
+# ---------------------------------------------------------------------------
+CUDA_VISIBLE_DEVICES="${GPU}" \
+  vllm serve "${MODEL}" \
+  --trust-remote-code \
+  --tensor-parallel-size "${TENSOR_PARALLEL}" \
+  --enforce-eager \
+  --max-model-len "${MAX_MODEL_LEN}" \
+  --port "${VLLM_PORT}" \
+  --gpu-memory-utilization "${GPU_MEM_UTIL}" \
+  --no-enable-prefix-caching \
+  --kv-transfer-config \
+    "{\"kv_connector\":\"LMCacheMPConnector\",\"kv_role\":\"kv_both\",\"kv_connector_extra_config\":{\"lmcache.mp.port\":${LMCACHE_MP_PORT}}}" \
+  2>&1 | sed 's/^/[vllm] /' &
+BGPIDS+=($!)
+
+echo ""
+echo "=== Ready ==="
+echo "  vLLM:    http://localhost:${VLLM_PORT}"
+echo "  Grafana: http://localhost:3000"
+echo "  Press Ctrl+C to shut down."
+
+wait
diff --git a/examples/observability/tempo.yml b/examples/observability/tempo.yml
new file mode 100644
index 0000000..a7fe8d4
--- /dev/null
+++ b/examples/observability/tempo.yml
@@ -0,0 +1,42 @@
+server:
+  http_listen_port: 3200
+
+distributor:
+  receivers:
+    otlp:
+      protocols:
+        grpc:
+          endpoint: 0.0.0.0:4317
+        http:
+          endpoint: 0.0.0.0:4318
+
+# Keep recent traces in the local-blocks processor so Grafana can compute
+# TraceQL metrics (span latency / rate graphs) without a separate backend.
+metrics_generator:
+  processor:
+    local_blocks:
+      flush_to_storage: true
+      # Cut/complete blocks quickly so TraceQL-metrics see recent traces within
+      # seconds (sparse demo traffic otherwise sits in an open block for minutes).
+      trace_idle_period: 5s
+      flush_check_period: 5s
+      max_block_duration: 30s
+      complete_block_timeout: 1h
+  storage:
+    path: /var/tempo/generator/wal
+  traces_storage:
+    path: /var/tempo/generator/traces
+
+storage:
+  trace:
+    backend: local
+    local:
+      path: /var/tempo/blocks
+    wal:
+      path: /var/tempo/wal
+
+# Turn on the local-blocks processor for the (single, default) tenant.
+overrides:
+  defaults:
+    metrics_generator:
+      processors: [local-blocks]
diff --git a/examples/online_session/README.md b/examples/online_session/README.md
new file mode 100644
index 0000000..bfcf9eb
--- /dev/null
+++ b/examples/online_session/README.md
@@ -0,0 +1,157 @@
+# OpenAI Chat‑Completion TTFT Benchmark  
+
+Measure **time‑to‑first‑token (TTFT)** — and optional cache‑hit latency — from **any
+server that speaks the OpenAI `/v1` API** (vLLM, llama.cpp with `--api`,
+OpenAI‑proxy, etc.).
+
+> **Why run it?**  
+> • Compare *cold* latency vs. *cache‑hit* latency.  
+> • Verify whether a KV‑cache (VRAM, SSD, LMCache, …) actually helps.  
+> • Collect JSONL you can plot 
+
+---
+
+## 1 · Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **Running endpoint** | Must expose the OpenAI REST interface (default URL `http://localhost:8000/v1`). |
+
+For more information on how to serve an endpoint using vllm and LMCache, 
+
+---
+
+## 2 · Command‑line flags
+
+| Flag / shorthand | Default | Meaning |
+|------------------|---------|---------|
+| `--api_base`     | `http://localhost:8000/v1` | URL of the OpenAI‑style endpoint. |
+| `--api_key`      | `EMPTY` | Any string (ignored by most local servers). |
+| `--model`        | *first model from* `/models` | Explicit model ID. |
+| `-C`, `--context_file` | *see table below* | Document inserted before the prompt. |
+| `--max_ctx_tokens` | **131 072** | Upper bound *after* truncation. |
+| `--prompt`       | `"Summarize this text"` | Prompt appended after the document. |
+| `--num_following`| **1** | Extra TTFT‑measured requests after the baseline. |
+| `-F`, `--flush_cache` | off | Flush GPU KV‑cache **once** after run 1. |
+| `--out`          | `benchmark.jsonl` | JSONL log (cleared at start). |
+
+### Behaviour of `--context_file`
+
+| Invocation | Document used |
+|------------|---------------|
+| *(flag omitted)* | Synthetic ASCII filler based on max ctx length input|
+| `--context_file` *(no path)* | Bundled `ffmpeg.txt` (one dir up) |
+| `--context_file /path/doc.txt` | Exact file you specify |
+
+> **Legacy shorthand** – you may also run  
+> `python openai_chat_completion_client.py <PORT>`  
+> and every other option remains default.
+
+---
+
+## 3 · Quick start
+
+Cold + warm measurement (two requests total):
+
+```bash
+python openai_chat_completion_client.py --num_following 1
+```
+
+Example console output
+
+```
+=== Run 1: baseline TTFT ===
+TTFT_1 = 0.429s
+(no KV‑cache flush requested)
+
+=== Run 2: TTFT continued ===
+TTFT_2 = 0.081s
+```
+
+`benchmark.jsonl`
+
+```json
+{"run_index":1,"context_tokens":120938,"ttft_seconds":0.429}
+{"run_index":2,"context_tokens":120938,"ttft_seconds":0.081}
+```
+
+---
+
+## 4 · Advanced use
+
+### 4.1 · Benchmark after cache eviction
+
+```bash
+python openai_chat_completion_client.py \
+  -C war_and_peace.txt        \
+  --num_following 3           \
+  --flush_cache               \
+  --prompt "Give me a concise outline." \
+  --out warpeace_flush.jsonl
+```
+
+* Run 1 – cold  
+* Cache flushed  
+* Run 2 – cold again (miss)  
+* Runs 3‑4 – warm (hits)
+
+### 4.2 · Stress maximum context
+
+```bash
+python openai_chat_completion_client.py \
+  --max_ctx_tokens 131072 \
+  --num_following 1 -F
+```
+
+Generates a k‑char filler, truncates to fit
+`≤ max_ctx ` tokens (keeps a **2 048‑token safety margin**), then
+measures cold vs. warm TTFT.
+
+---
+
+## 5 · Output schema
+
+Each JSONL line contains:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `run_index`      | int   | 1 = baseline, 2… = follow‑ups |
+| `context_tokens` | int   | Tokens after truncation |
+| `ttft_seconds`   | float | Wall‑clock seconds to **first** streamed token |
+
+Concatenate multiple logs with `cat` and plot as you like.
+
+---
+
+## 6 · Implementation notes
+
+* **Safety margin** – `SAFETY_MARGIN = 2048` tokens so the request never
+  overruns model context even on tokenizer quirks.
+* **Spinner** – Red arrows animate while waiting for token #1, stop instantly
+  on arrival for visual TTFT confirmation.
+* **Tokenizer fallback** – If the matching tokenizer can’t load, the script
+  degrades to the heuristic “≈ 4 chars = 1 token”.
+* **Cache‑flush routine** – Sends ten *1‑token* completions built on a
+  100 k‑char filler doc to evict KV blocks from VRAM.
+
+## 7 · Batch driver script (`bench_ttft_sweep.sh`)
+
+This is an example basic bash script you might use to do a sweep across different context lengths, combining results to one file for easy comparison of caching methods.
+
+
+
+### What the script does
+
+| Step | Detail |
+|------|--------|
+| **1.  Configure variables** | `BENCH` points to the Python benchmark, `MASTER_OUT` is the cumulative log, and `CONTEXT_SIZES` lists the target document lengths (in **tokens**). |
+| **2.  Per‑size run** | For each length the script launches the benchmark with:<br>• custom `--max_ctx_tokens` (see above)<br>• one cache‑hit follow‑up (`--num_following 1`)<br>• an explicit **70 B** Llama 3 checkpoint via `--model` |
+| **3.  Log collation** | Each invocation writes its own JSONL (`ttft_<N>.jsonl`). Those lines are immediately concatenated into **`all_ttft_results.jsonl`**, producing a tidy file like: <br>`{"run_index":1,"context_tokens":32000,"ttft_seconds":0.45}` |
+| **4.  Done banner** | After the loop finishes you get a green check‑mark and the path to the merged log. |
+
+#### Customising
+
+* **Change the model** — edit `--model …` to point at any endpoint‑visible name.  
+* **Different sizes** — just tweak the `CONTEXT_SIZES` array.  
+* **More follow‑ups** — bump `--num_following` if you want deeper cache‑hit sampling.  
+
diff --git a/examples/online_session/bench_ttft_sweep.sh b/examples/online_session/bench_ttft_sweep.sh
new file mode 100644
index 0000000..5aa1748
--- /dev/null
+++ b/examples/online_session/bench_ttft_sweep.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Run the TTFT benchmark at several context sizes and collate the results.
+# ---------------------------------------------------------------
+BENCH="openai_chat_completion_client.py"   # path to your benchmark script
+MASTER_OUT="all_ttft_results.jsonl"        # final merged log
+CONTEXT_SIZES=(50 1000 2000 8000 16000 24000 32000 64000 96000 128000)
+
+: > "$MASTER_OUT"               # truncate / create the final log file
+
+for TOKENS in "${CONTEXT_SIZES[@]}"; do
+  MAX_CTX=$((TOKENS))
+  OUTFILE="ttft_${TOKENS}.jsonl"
+
+  echo -e "\n▶︎ Running ${TOKENS}-token test (max_ctx_tokens=${MAX_CTX})"
+  python "$BENCH" --max_ctx_tokens "$MAX_CTX" \
+                  --num_following 1 \
+                  --out "$OUTFILE" \
+		  --model meta-llama/Llama-3.3-70B-Instruct \
+
+  cat "$OUTFILE" >> "$MASTER_OUT"          # append to the master log
+done
+
+echo -e "\n✅  All done – combined results in $MASTER_OUT"
+
diff --git a/examples/online_session/example.yaml b/examples/online_session/example.yaml
new file mode 100644
index 0000000..ccbc559
--- /dev/null
+++ b/examples/online_session/example.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_device: "cpu"
+remote_url: "lm://localhost:65432"
+remote_serde: "cachegen"
diff --git a/examples/online_session/ffmpeg.txt b/examples/online_session/ffmpeg.txt
new file mode 100644
index 0000000..940b0a8
--- /dev/null
+++ b/examples/online_session/ffmpeg.txt
@@ -0,0 +1,2069 @@
+FFMPEG(1)						FFMPEG(1)
+
+NAME
+       ffmpeg - ffmpeg video converter
+
+SYNOPSIS
+       ffmpeg [global_options] {[input_file_options] -i input_url} ... 
+       {[output_file_options] output_url} ...
+
+DESCRIPTION
+       ffmpeg is a very fast video and audio converter that can also 
+       grab from a live audio/video source. It can also convert between 
+       arbitrary sample rates and resize video on the fly with a high 
+       quality polyphase filter.
+
+       ffmpeg reads from an arbitrary number of input "files" (which 
+       can be regular files, pipes, network streams, grabbing devices, 
+       etc.), specified by the "-i" option, and writes to an arbitrary 
+       number of output "files", which are specified by a plain output
+       url. Anything found on the command line which cannot be inter-
+       preted as an option is considered to be an output url.
+
+       Each input or output url can, in principle, contain any number of 
+       streams of different types (video/audio/subtitle/attachment/data). 
+       The allowed number and/or types of streams may be limited by the 
+       container format. Selecting which streams from which inputs will 
+       go into which output is either done automatically or with the 
+       "-map" option (see the Stream selection chapter).
+
+       To refer to input files in options, you must use their indices 
+       (0-based). E.g.  the first input file is 0, the second is 1, etc. 
+       Similarly, streams within a file are referred to by their indices. 
+       E.g. "2:3" refers to the fourth stream in the third input file. 
+       Also see the Stream specifiers chapter.
+
+       As a general rule, options are applied to the next specified file. 
+       Therefore, order is important, and you can have the same option on 
+       the command line multiple times. Each occurrence is then applied 
+       to the next input or output file.  Exceptions from this rule are 
+       the global options (e.g. verbosity level), which should be specified 
+       first.
+
+       Do not mix input and output files -- first specify all input files, 
+       then all output files. Also do not mix options which belong to 
+       different files. All options apply ONLY to the next input or output 
+       file and are reset between files.
+
+       •   To set the video bitrate of the output file to 64 kbit/s:
+
+		   ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi
+
+       •   To force the frame rate of the output file to 24 fps:
+
+		   ffmpeg -i input.avi -r 24 output.avi
+
+       •   To force the frame rate of the input file (valid for raw formats only) to 1 fps and the frame
+	   rate of the output file to 24 fps:
+
+		   ffmpeg -r 1 -i input.m2v -r 24 output.avi
+
+       The format option may be needed for raw input files.
+
+DETAILED DESCRIPTION
+       The transcoding process in ffmpeg for each output can be described by the following diagram:
+
+		_______ 	     ______________
+	       |       |	    |		   |
+	       | input |  demuxer   | encoded data |   decoder
+	       | file  | ---------> | packets	   | -----+
+	       |_______|	    |______________|	  |
+							  v
+						      _________
+						     |	       |
+						     | decoded |
+						     | frames  |
+						     |_________|
+		________	     ______________	  |
+	       |	|	    |		   |	  |
+	       | output | <-------- | encoded data | <----+
+	       | file	|   muxer   | packets	   |   encoder
+	       |________|	    |______________|
+
+       ffmpeg calls the libavformat library (containing demuxers) to read input files and get packets
+       containing encoded data from them. When there are multiple input files, ffmpeg tries to keep them
+       synchronized by tracking lowest timestamp on any active input stream.
+
+       Encoded packets are then passed to the decoder (unless streamcopy is selected for the stream, see
+       further for a description). The decoder produces uncompressed frames (raw video/PCM audio/...)
+       which can be processed further by filtering (see next section). After filtering, the frames are
+       passed to the encoder, which encodes them and outputs encoded packets. Finally those are passed to
+       the muxer, which writes the encoded packets to the output file.
+
+   Filtering
+       Before encoding, ffmpeg can process raw audio and video frames using filters from the libavfilter
+       library. Several chained filters form a filter graph. ffmpeg distinguishes between two types of
+       filtergraphs: simple and complex.
+
+       Simple filtergraphs
+
+       Simple filtergraphs are those that have exactly one input and output, both of the same type. In
+       the above diagram they can be represented by simply inserting an additional step between decoding
+       and encoding:
+
+		_________			 ______________
+	       |	 |			|	       |
+	       | decoded |			| encoded data |
+	       | frames  |\		      _ | packets      |
+	       |_________| \		      /||______________|
+			    \	__________   /
+		 simple     _\||	  | /  encoder
+		 filtergraph   | filtered |/
+			       | frames   |
+			       |__________|
+
+       Simple filtergraphs are configured with the per-stream -filter option (with -vf and -af aliases
+       for video and audio respectively).  A simple filtergraph for video can look for example like this:
+
+		_______        _____________	    _______	   ________
+	       |       |      | 	    |	   |	   |	  |	   |
+	       | input | ---> | deinterlace | ---> | scale | ---> | output |
+	       |_______|      |_____________|	   |_______|	  |________|
+
+       Note that some filters change frame properties but not frame contents. E.g. the "fps" filter in
+       the example above changes number of frames, but does not touch the frame contents. Another example
+       is the "setpts" filter, which only sets timestamps and otherwise passes the frames unchanged.
+
+       Complex filtergraphs
+
+       Complex filtergraphs are those which cannot be described as simply a linear processing chain
+       applied to one stream. This is the case, for example, when the graph has more than one input
+       and/or output, or when output stream type is different from input. They can be represented with
+       the following diagram:
+
+		_________
+	       |	 |
+	       | input 0 |\		       __________
+	       |_________| \		      | 	 |
+			    \	_________    /| output 0 |
+			     \ |	 |  / |__________|
+		_________     \| complex | /
+	       |	 |     |	 |/
+	       | input 1 |---->| filter  |\
+	       |_________|     |	 | \   __________
+			      /| graph	 |  \ | 	 |
+			     / |	 |   \| output 1 |
+		_________   /  |_________|    |__________|
+	       |	 | /
+	       | input 2 |/
+	       |_________|
+
+       Complex filtergraphs are configured with the -filter_complex option.  Note that this option is
+       global, since a complex filtergraph, by its nature, cannot be unambiguously associated with a
+       single stream or file.
+
+       The -lavfi option is equivalent to -filter_complex.
+
+       A trivial example of a complex filtergraph is the "overlay" filter, which has two video inputs and
+       one video output, containing one video overlaid on top of the other. Its audio counterpart is the
+       "amix" filter.
+
+   Stream copy
+       Stream copy is a mode selected by supplying the "copy" parameter to the -codec option. It makes
+       ffmpeg omit the decoding and encoding step for the specified stream, so it does only demuxing and
+       muxing. It is useful for changing the container format or modifying container-level metadata. The
+       diagram above will, in this case, simplify to this:
+
+		_______ 	     ______________	       ________
+	       |       |	    |		   |	      |        |
+	       | input |  demuxer   | encoded data |  muxer   | output |
+	       | file  | ---------> | packets	   | -------> | file   |
+	       |_______|	    |______________|	      |________|
+
+       Since there is no decoding or encoding, it is very fast and there is no quality loss. However, it
+       might not work in some cases because of many factors. Applying filters is obviously also
+       impossible, since filters work on uncompressed data.
+
+STREAM SELECTION
+       ffmpeg provides the "-map" option for manual control of stream selection in each output file.
+       Users can skip "-map" and let ffmpeg perform automatic stream selection as described below. The
+       "-vn / -an / -sn / -dn" options can be used to skip inclusion of video, audio, subtitle and data
+       streams respectively, whether manually mapped or automatically selected, except for those streams
+       which are outputs of complex filtergraphs.
+
+   Description
+       The sub-sections that follow describe the various rules that are involved in stream selection.
+       The examples that follow next show how these rules are applied in practice.
+
+       While every effort is made to accurately reflect the behavior of the program, FFmpeg is under
+       continuous development and the code may have changed since the time of this writing.
+
+       Automatic stream selection
+
+       In the absence of any map options for a particular output file, ffmpeg inspects the output format
+       to check which type of streams can be included in it, viz. video, audio and/or subtitles. For each
+       acceptable stream type, ffmpeg will pick one stream, when available, from among all the inputs.
+
+       It will select that stream based upon the following criteria:
+
+       •   for video, it is the stream with the highest resolution,
+
+       •   for audio, it is the stream with the most channels,
+
+       •   for subtitles, it is the first subtitle stream found but there's a caveat.  The output
+	   format's default subtitle encoder can be either text-based or image-based, and only a subtitle
+	   stream of the same type will be chosen.
+
+       In the case where several streams of the same type rate equally, the stream with the lowest index
+       is chosen.
+
+       Data or attachment streams are not automatically selected and can only be included using "-map".
+
+       Manual stream selection
+
+       When "-map" is used, only user-mapped streams are included in that output file, with one possible
+       exception for filtergraph outputs described below.
+
+       Complex filtergraphs
+
+       If there are any complex filtergraph output streams with unlabeled pads, they will be added to the
+       first output file. This will lead to a fatal error if the stream type is not supported by the
+       output format. In the absence of the map option, the inclusion of these streams leads to the
+       automatic stream selection of their types being skipped. If map options are present, these
+       filtergraph streams are included in addition to the mapped streams.
+
+       Complex filtergraph output streams with labeled pads must be mapped once and exactly once.
+
+       Stream handling
+
+       Stream handling is independent of stream selection, with an exception for subtitles described
+       below. Stream handling is set via the "-codec" option addressed to streams within a specific
+       output file. In particular, codec options are applied by ffmpeg after the stream selection process
+       and thus do not influence the latter. If no "-codec" option is specified for a stream type, ffmpeg
+       will select the default encoder registered by the output file muxer.
+
+       An exception exists for subtitles. If a subtitle encoder is specified for an output file, the
+       first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate
+       if the specified encoder can convert the selected stream or if the converted stream is acceptable
+       within the output format. This applies generally as well: when the user sets an encoder manually,
+       the stream selection process cannot check if the encoded stream can be muxed into the output file.
+       If it cannot, ffmpeg will abort and all output files will fail to be processed.
+
+   Examples
+       The following examples illustrate the behavior, quirks and limitations of ffmpeg's stream
+       selection methods.
+
+       They assume the following three input files.
+
+	       input file 'A.avi'
+		     stream 0: video 640x360
+		     stream 1: audio 2 channels
+
+	       input file 'B.mp4'
+		     stream 0: video 1920x1080
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (text)
+		     stream 3: audio 5.1 channels
+		     stream 4: subtitles (text)
+
+	       input file 'C.mkv'
+		     stream 0: video 1280x720
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (image)
+
+       Example: automatic stream selection
+
+	       ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
+
+       There are three output files specified, and for the first two, no "-map" options are set, so
+       ffmpeg will select streams for these two files automatically.
+
+       out1.mkv is a Matroska container file and accepts video, audio and subtitle streams, so ffmpeg
+       will try to select one of each type.For video, it will select "stream 0" from B.mp4, which has the
+       highest resolution among all the input video streams.For audio, it will select "stream 3" from
+       B.mp4, since it has the greatest number of channels.For subtitles, it will select "stream 2" from
+       B.mp4, which is the first subtitle stream from among A.avi and B.mp4.
+
+       out2.wav accepts only audio streams, so only "stream 3" from B.mp4 is selected.
+
+       For out3.mov, since a "-map" option is set, no automatic stream selection will occur. The "-map
+       1:a" option will select all audio streams from the second input B.mp4. No other streams will be
+       included in this output file.
+
+       For the first two outputs, all included streams will be transcoded. The encoders chosen will be
+       the default ones registered by each output format, which may not match the codec of the selected
+       input streams.
+
+       For the third output, codec option for audio streams has been set to "copy", so no decoding-
+       filtering-encoding operations will occur, or can occur.	Packets of selected streams shall be
+       conveyed from the input file and muxed within the output file.
+
+       Example: automatic subtitles selection
+
+	       ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
+
+       Although out1.mkv is a Matroska container file which accepts subtitle streams, only a video and
+       audio stream shall be selected. The subtitle stream of C.mkv is image-based and the default
+       subtitle encoder of the Matroska muxer is text-based, so a transcode operation for the subtitles
+       is expected to fail and hence the stream isn't selected. However, in out2.mkv, a subtitle encoder
+       is specified in the command and so, the subtitle stream is selected, in addition to the video
+       stream. The presence of "-an" disables audio stream selection for out2.mkv.
+
+       Example: unlabeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
+
+       A filtergraph is setup here using the "-filter_complex" option and consists of a single video
+       filter. The "overlay" filter requires exactly two video inputs, but none are specified, so the
+       first two available video streams are used, those of A.avi and C.mkv. The output pad of the filter
+       has no label and so is sent to the first output file out1.mp4. Due to this, automatic selection of
+       the video stream is skipped, which would have selected the stream in B.mp4. The audio stream with
+       most channels viz. "stream 3" in B.mp4, is chosen automatically. No subtitle stream is chosen
+       however, since the MP4 format has no default subtitle encoder registered, and the user hasn't
+       specified a subtitle encoder.
+
+       The 2nd output file, out2.srt, only accepts text-based subtitle streams. So, even though the first
+       subtitle stream available belongs to C.mkv, it is image-based and hence skipped.  The selected
+       stream, "stream 2" in B.mp4, is the first text-based subtitle stream.
+
+       Example: labeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -map '[outv]' -an        out1.mp4 \
+					       out2.mkv \
+		      -map '[outv]' -map 1:a:0 out3.mkv
+
+       The above command will fail, as the output pad labelled "[outv]" has been mapped twice.	None of
+       the output files shall be processed.
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -an	 out1.mp4 \
+				 out2.mkv \
+		      -map 1:a:0 out3.mkv
+
+       This command above will also fail as the hue filter output has a label, "[outv]", and hasn't been
+       mapped anywhere.
+
+       The command should be modified as follows,
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
+		       -map '[outv1]' -an	 out1.mp4 \
+						 out2.mkv \
+		       -map '[outv2]' -map 1:a:0 out3.mkv
+
+       The video stream from B.mp4 is sent to the hue filter, whose output is cloned once using the split
+       filter, and both outputs labelled. Then a copy each is mapped to the first and third output files.
+
+       The overlay filter, requiring two video inputs, uses the first two unused video streams. Those are
+       the streams from A.avi and C.mkv. The overlay output isn't labelled, so it is sent to the first
+       output file out1.mp4, regardless of the presence of the "-map" option.
+
+       The aresample filter is sent the first unused audio stream, that of A.avi. Since this filter
+       output is also unlabelled, it too is mapped to the first output file. The presence of "-an" only
+       suppresses automatic or manual stream selection of audio streams, not outputs sent from
+       filtergraphs. Both these mapped streams shall be ordered before the mapped stream in out1.mp4.
+
+       The video, audio and subtitle streams mapped to "out2.mkv" are entirely determined by automatic
+       stream selection.
+
+       out3.mkv consists of the cloned video output from the hue filter and the first audio stream from
+       B.mp4.
+
+OPTIONS
+       All the numerical options, if not specified otherwise, accept a string representing a number as
+       input, which may be followed by one of the SI unit prefixes, for example: 'K', 'M', or 'G'.
+
+       If 'i' is appended to the SI unit prefix, the complete prefix will be interpreted as a unit prefix
+       for binary multiples, which are based on powers of 1024 instead of powers of 1000. Appending 'B'
+       to the SI unit prefix multiplies the value by 8. This allows using, for example: 'KB', 'MiB', 'G'
+       and 'B' as number suffixes.
+
+       Options which do not take arguments are boolean options, and set the corresponding value to true.
+       They can be set to false by prefixing the option name with "no". For example using "-nofoo" will
+       set the boolean option with name "foo" to false.
+
+   Stream specifiers
+       Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers are used to
+       precisely specify which stream(s) a given option belongs to.
+
+       A stream specifier is a string generally appended to the option name and separated from it by a
+       colon. E.g. "-codec:a:1 ac3" contains the "a:1" stream specifier, which matches the second audio
+       stream. Therefore, it would select the ac3 codec for the second audio stream.
+
+       A stream specifier can match several streams, so that the option is applied to all of them. E.g.
+       the stream specifier in "-b:a 128k" matches all audio streams.
+
+       An empty stream specifier matches all streams. For example, "-codec copy" or "-codec: copy" would
+       copy all the streams without reencoding.
+
+       Possible forms of stream specifiers are:
+
+       stream_index
+	   Matches the stream with this index. E.g. "-threads:1 4" would set the thread count for the
+	   second stream to 4. If stream_index is used as an additional stream specifier (see below),
+	   then it selects stream number stream_index from the matching streams. Stream numbering is
+	   based on the order of the streams as detected by libavformat except when a program ID is also
+	   specified. In this case it is based on the ordering of the streams in the program.
+
+       stream_type[:additional_stream_specifier]
+	   stream_type is one of following: 'v' or 'V' for video, 'a' for audio, 's' for subtitle, 'd'
+	   for data, and 't' for attachments. 'v' matches all video streams, 'V' only matches video
+	   streams which are not attached pictures, video thumbnails or cover arts. If
+	   additional_stream_specifier is used, then it matches streams which both have this type and
+	   match the additional_stream_specifier. Otherwise, it matches all streams of the specified
+	   type.
+
+       p:program_id[:additional_stream_specifier]
+	   Matches streams which are in the program with the id program_id. If
+	   additional_stream_specifier is used, then it matches streams which both are part of the
+	   program and match the additional_stream_specifier.
+
+       #stream_id or i:stream_id
+	   Match the stream by stream id (e.g. PID in MPEG-TS container).
+
+       m:key[:value]
+	   Matches streams with the metadata tag key having the specified value. If value is not given,
+	   matches streams that contain the given tag with any value.
+
+       u   Matches streams with usable configuration, the codec must be defined and the essential
+	   information such as video dimension or audio sample rate must be present.
+
+	   Note that in ffmpeg, matching by metadata will only work properly for input files.
+
+   Generic options
+       These options are shared amongst the ff* tools.
+
+       -L  Show license.
+
+       -h, -?, -help, --help [arg]
+	   Show help. An optional parameter may be specified to print help about a specific item. If no
+	   argument is specified, only basic (non advanced) tool options are shown.
+
+	   Possible values of arg are:
+
+	   long
+	       Print advanced tool options in addition to the basic tool options.
+
+	   full
+	       Print complete list of options, including shared and private options for encoders,
+	       decoders, demuxers, muxers, filters, etc.
+
+	   decoder=decoder_name
+	       Print detailed information about the decoder named decoder_name. Use the -decoders option
+	       to get a list of all decoders.
+
+	   encoder=encoder_name
+	       Print detailed information about the encoder named encoder_name. Use the -encoders option
+	       to get a list of all encoders.
+
+	   demuxer=demuxer_name
+	       Print detailed information about the demuxer named demuxer_name. Use the -formats option
+	       to get a list of all demuxers and muxers.
+
+	   muxer=muxer_name
+	       Print detailed information about the muxer named muxer_name. Use the -formats option to
+	       get a list of all muxers and demuxers.
+
+	   filter=filter_name
+	       Print detailed information about the filter name filter_name. Use the -filters option to
+	       get a list of all filters.
+
+	   bsf=bitstream_filter_name
+	       Print detailed information about the bitstream filter name bitstream_filter_name.  Use the
+	       -bsfs option to get a list of all bitstream filters.
+
+       -version
+	   Show version.
+
+       -formats
+	   Show available formats (including devices).
+
+       -demuxers
+	   Show available demuxers.
+
+       -muxers
+	   Show available muxers.
+
+       -devices
+	   Show available devices.
+
+       -codecs
+	   Show all codecs known to libavcodec.
+
+	   Note that the term 'codec' is used throughout this documentation as a shortcut for what is
+	   more correctly called a media bitstream format.
+
+       -decoders
+	   Show available decoders.
+
+       -encoders
+	   Show all available encoders.
+
+       -bsfs
+	   Show available bitstream filters.
+
+       -protocols
+	   Show available protocols.
+
+       -filters
+	   Show available libavfilter filters.
+
+       -pix_fmts
+	   Show available pixel formats.
+
+       -sample_fmts
+	   Show available sample formats.
+
+       -layouts
+	   Show channel names and standard channel layouts.
+
+       -colors
+	   Show recognized color names.
+
+       -sources device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sources of the input device.  Some devices may provide system-dependent
+	   source names that cannot be autodetected.  The returned list cannot be assumed to be always
+	   complete.
+
+		   ffmpeg -sources pulse,server=192.168.0.4
+
+       -sinks device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sinks of the output device.  Some devices may provide system-dependent sink
+	   names that cannot be autodetected.  The returned list cannot be assumed to be always complete.
+
+		   ffmpeg -sinks pulse,server=192.168.0.4
+
+       -loglevel [flags+]loglevel | -v [flags+]loglevel
+	   Set logging level and flags used by the library.
+
+	   The optional flags prefix can consist of the following values:
+
+	   repeat
+	       Indicates that repeated log output should not be compressed to the first line and the
+	       "Last message repeated n times" line will be omitted.
+
+	   level
+	       Indicates that log output should add a "[level]" prefix to each message line. This can be
+	       used as an alternative to log coloring, e.g. when dumping the log to file.
+
+	   Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single flag without
+	   affecting other flags or changing loglevel. When setting both flags and loglevel, a '+'
+	   separator is expected between the last flags value and before loglevel.
+
+	   loglevel is a string or a number containing one of the following values:
+
+	   quiet, -8
+	       Show nothing at all; be silent.
+
+	   panic, 0
+	       Only show fatal errors which could lead the process to crash, such as an assertion
+	       failure. This is not currently used for anything.
+
+	   fatal, 8
+	       Only show fatal errors. These are errors after which the process absolutely cannot
+	       continue.
+
+	   error, 16
+	       Show all errors, including ones which can be recovered from.
+
+	   warning, 24
+	       Show all warnings and errors. Any message related to possibly incorrect or unexpected
+	       events will be shown.
+
+	   info, 32
+	       Show informative messages during processing. This is in addition to warnings and errors.
+	       This is the default value.
+
+	   verbose, 40
+	       Same as "info", except more verbose.
+
+	   debug, 48
+	       Show everything, including debugging information.
+
+	   trace, 56
+
+	   For example to enable repeated log output, add the "level" prefix, and set loglevel to
+	   "verbose":
+
+		   ffmpeg -loglevel repeat+level+verbose -i input output
+
+	   Another example that enables repeated log output without affecting current state of "level"
+	   prefix flag or loglevel:
+
+		   ffmpeg [...] -loglevel +repeat
+
+	   By default the program logs to stderr. If coloring is supported by the terminal, colors are
+	   used to mark errors and warnings. Log coloring can be disabled setting the environment
+	   variable AV_LOG_FORCE_NOCOLOR or NO_COLOR, or can be forced setting the environment variable
+	   AV_LOG_FORCE_COLOR.	The use of the environment variable NO_COLOR is deprecated and will be
+	   dropped in a future FFmpeg version.
+
+       -report
+	   Dump full command line and console output to a file named "program-YYYYMMDD-HHMMSS.log" in the
+	   current directory.  This file can be useful for bug reports.  It also implies "-loglevel
+	   debug".
+
+	   Setting the environment variable FFREPORT to any value has the same effect. If the value is a
+	   ':'-separated key=value sequence, these options will affect the report; option values must be
+	   escaped if they contain special characters or the options delimiter ':' (see the ``Quoting and
+	   escaping'' section in the ffmpeg-utils manual).
+
+	   The following options are recognized:
+
+	   file
+	       set the file name to use for the report; %p is expanded to the name of the program, %t is
+	       expanded to a timestamp, "%%" is expanded to a plain "%"
+
+	   level
+	       set the log verbosity level using a numerical value (see "-loglevel").
+
+	   For example, to output a report to a file named ffreport.log using a log level of 32 (alias
+	   for log level "info"):
+
+		   FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+	   Errors in parsing the environment variable are not fatal, and will not appear in the report.
+
+       -hide_banner
+	   Suppress printing banner.
+
+	   All FFmpeg tools will normally show a copyright notice, build options and library versions.
+	   This option can be used to suppress printing this information.
+
+       -cpuflags flags (global)
+	   Allows setting and clearing cpu flags. This option is intended for testing. Do not use it
+	   unless you know what you're doing.
+
+		   ffmpeg -cpuflags -sse+mmx ...
+		   ffmpeg -cpuflags mmx ...
+		   ffmpeg -cpuflags 0 ...
+
+	   Possible flags for this option are:
+
+	   x86
+	       mmx
+	       mmxext
+	       sse
+	       sse2
+	       sse2slow
+	       sse3
+	       sse3slow
+	       ssse3
+	       atom
+	       sse4.1
+	       sse4.2
+	       avx
+	       avx2
+	       xop
+	       fma3
+	       fma4
+	       3dnow
+	       3dnowext
+	       bmi1
+	       bmi2
+	       cmov
+	   ARM
+	       armv5te
+	       armv6
+	       armv6t2
+	       vfp
+	       vfpv3
+	       neon
+	       setend
+	   AArch64
+	       armv8
+	       vfp
+	       neon
+	   PowerPC
+	       altivec
+	   Specific Processors
+	       pentium2
+	       pentium3
+	       pentium4
+	       k6
+	       k62
+	       athlon
+	       athlonxp
+	       k8
+
+   AVOptions
+       These options are provided directly by the libavformat, libavdevice and libavcodec libraries. To
+       see the list of available AVOptions, use the -help option. They are separated into two categories:
+
+       generic
+	   These options can be set for any container, codec or device. Generic options are listed under
+	   AVFormatContext options for containers/devices and under AVCodecContext options for codecs.
+
+       private
+	   These options are specific to the given container, device or codec. Private options are listed
+	   under their corresponding containers/devices/codecs.
+
+       For example to write an ID3v2.3 header instead of a default ID3v2.4 to an MP3 file, use the
+       id3v2_version private option of the MP3 muxer:
+
+	       ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+       All codec AVOptions are per-stream, and thus a stream specifier should be attached to them:
+
+	       ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+       In the above example, a multichannel audio stream is mapped twice for output.  The first instance
+       is encoded with codec ac3 and bitrate 640k.  The second instance is downmixed to 2 channels and
+       encoded with codec aac. A bitrate of 128k is specified for it using absolute index of the output
+       stream.
+
+       Note: the -nooption syntax cannot be used for boolean AVOptions, use -option 0/-option 1.
+
+       Note: the old undocumented way of specifying per-stream AVOptions by prepending v/a/s to the
+       options name is now obsolete and will be removed soon.
+
+   Main options
+       -f fmt (input/output)
+	   Force input or output file format. The format is normally auto detected for input files and
+	   guessed from the file extension for output files, so this option is not needed in most cases.
+
+       -i url (input)
+	   input file url
+
+       -y (global)
+	   Overwrite output files without asking.
+
+       -n (global)
+	   Do not overwrite output files, and exit immediately if a specified output file already exists.
+
+       -stream_loop number (input)
+	   Set number of times input stream shall be looped. Loop 0 means no loop, loop -1 means infinite
+	   loop.
+
+       -c[:stream_specifier] codec (input/output,per-stream)
+       -codec[:stream_specifier] codec (input/output,per-stream)
+	   Select an encoder (when used before an output file) or a decoder (when used before an input
+	   file) for one or more streams. codec is the name of a decoder/encoder or a special value
+	   "copy" (output only) to indicate that the stream is not to be re-encoded.
+
+	   For example
+
+		   ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+
+	   encodes all video streams with libx264 and copies all audio streams.
+
+	   For each stream, the last matching "c" option is applied, so
+
+		   ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+
+	   will copy all the streams except the second video, which will be encoded with libx264, and the
+	   138th audio, which will be encoded with libvorbis.
+
+       -t duration (input/output)
+	   When used as an input option (before "-i"), limit the duration of data read from the input
+	   file.
+
+	   When used as an output option (before an output url), stop writing the output after its
+	   duration reaches duration.
+
+	   duration must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -to position (input/output)
+	   Stop writing the output or reading the input at position.  position must be a time duration
+	   specification, see the Time duration section in the ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -fs limit_size (output)
+	   Set the file size limit, expressed in bytes. No further chunk of bytes is written after the
+	   limit is exceeded. The size of the output file is slightly more than the requested file size.
+
+       -ss position (input/output)
+	   When used as an input option (before "-i"), seeks in this input file to position. Note that in
+	   most formats it is not possible to seek exactly, so ffmpeg will seek to the closest seek point
+	   before position.  When transcoding and -accurate_seek is enabled (the default), this extra
+	   segment between the seek point and position will be decoded and discarded. When doing stream
+	   copy or when -noaccurate_seek is used, it will be preserved.
+
+	   When used as an output option (before an output url), decodes but discards input until the
+	   timestamps reach position.
+
+	   position must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+       -sseof position (input)
+	   Like the "-ss" option but relative to the "end of file". That is negative values are earlier
+	   in the file, 0 is at EOF.
+
+       -itsoffset offset (input)
+	   Set the input time offset.
+
+	   offset must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   The offset is added to the timestamps of the input files. Specifying a positive offset means
+	   that the corresponding streams are delayed by the time duration specified in offset.
+
+       -itsscale scale (input,per-stream)
+	   Rescale input timestamps. scale should be a floating point number.
+
+       -timestamp date (output)
+	   Set the recording timestamp in the container.
+
+	   date must be a date specification, see the Date section in the ffmpeg-utils(1) manual.
+
+       -metadata[:metadata_specifier] key=value (output,per-metadata)
+	   Set a metadata key/value pair.
+
+	   An optional metadata_specifier may be given to set metadata on streams, chapters or programs.
+	   See "-map_metadata" documentation for details.
+
+	   This option overrides metadata set with "-map_metadata". It is also possible to delete
+	   metadata by using an empty value.
+
+	   For example, for setting the title in the output file:
+
+		   ffmpeg -i in.avi -metadata title="my title" out.flv
+
+	   To set the language of the first audio stream:
+
+		   ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
+
+       -disposition[:stream_specifier] value (output,per-stream)
+	   Sets the disposition for a stream.
+
+	   This option overrides the disposition copied from the input stream. It is also possible to
+	   delete the disposition by setting it to 0.
+
+	   The following dispositions are recognized:
+
+	   default
+	   dub
+	   original
+	   comment
+	   lyrics
+	   karaoke
+	   forced
+	   hearing_impaired
+	   visual_impaired
+	   clean_effects
+	   attached_pic
+	   captions
+	   descriptions
+	   dependent
+	   metadata
+
+	   For example, to make the second audio stream the default stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
+
+	   To make the second subtitle stream the default stream and remove the default disposition from
+	   the first subtitle stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
+
+	   To add an embedded cover/thumbnail:
+
+		   ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
+
+	   Not all muxers support embedded thumbnails, and those who do, only support a few formats, like
+	   JPEG or PNG.
+
+       -program [title=title:][program_num=program_num:]st=stream[:st=stream...] (output)
+	   Creates a program with the specified title, program_num and adds the specified stream(s) to
+	   it.
+
+       -target type (output)
+	   Specify target file type ("vcd", "svcd", "dvd", "dv", "dv50"). type may be prefixed with
+	   "pal-", "ntsc-" or "film-" to use the corresponding standard. All the format options (bitrate,
+	   codecs, buffer sizes) are then set automatically. You can just type:
+
+		   ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
+
+	   Nevertheless you can specify additional options as long as you know they do not conflict with
+	   the standard, as in:
+
+		   ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+
+       -dn (input/output)
+	   As an input option, blocks all data streams of a file from being filtered or being
+	   automatically selected or mapped for any output. See "-discard" option to disable streams
+	   individually.
+
+	   As an output option, disables data recording i.e. automatic selection or mapping of any data
+	   stream. For full manual control see the "-map" option.
+
+       -dframes number (output)
+	   Set the number of data frames to output. This is an obsolete alias for "-frames:d", which you
+	   should use instead.
+
+       -frames[:stream_specifier] framecount (output,per-stream)
+	   Stop writing to the stream after framecount frames.
+
+       -q[:stream_specifier] q (output,per-stream)
+       -qscale[:stream_specifier] q (output,per-stream)
+	   Use fixed quality scale (VBR). The meaning of q/qscale is codec-dependent.  If qscale is used
+	   without a stream_specifier then it applies only to the video stream, this is to maintain
+	   compatibility with previous behavior and as specifying the same codec specific value to 2
+	   different codecs that is audio and video generally is not what is intended when no
+	   stream_specifier is used.
+
+       -filter[:stream_specifier] filtergraph (output,per-stream)
+	   Create the filtergraph specified by filtergraph and use it to filter the stream.
+
+	   filtergraph is a description of the filtergraph to apply to the stream, and must have a single
+	   input and a single output of the same type of the stream. In the filtergraph, the input is
+	   associated to the label "in", and the output to the label "out". See the ffmpeg-filters manual
+	   for more information about the filtergraph syntax.
+
+	   See the -filter_complex option if you want to create filtergraphs with multiple inputs and/or
+	   outputs.
+
+       -filter_script[:stream_specifier] filename (output,per-stream)
+	   This option is similar to -filter, the only difference is that its argument is the name of the
+	   file from which a filtergraph description is to be read.
+
+       -filter_threads nb_threads (global)
+	   Defines how many threads are used to process a filter pipeline. Each pipeline will produce a
+	   thread pool with this many threads available for parallel processing.  The default is the
+	   number of available CPUs.
+
+       -pre[:stream_specifier] preset_name (output,per-stream)
+	   Specify the preset for matching stream(s).
+
+       -stats (global)
+	   Print encoding progress/statistics. It is on by default, to explicitly disable it you need to
+	   specify "-nostats".
+
+       -progress url (global)
+	   Send program-friendly progress information to url.
+
+	   Progress information is written approximately every second and at the end of the encoding
+	   process. It is made of "key=value" lines. key consists of only alphanumeric characters. The
+	   last key of a sequence of progress information is always "progress".
+
+       -stdin
+	   Enable interaction on standard input. On by default unless standard input is used as an input.
+	   To explicitly disable interaction you need to specify "-nostdin".
+
+	   Disabling interaction on standard input is useful, for example, if ffmpeg is in the background
+	   process group. Roughly the same result can be achieved with "ffmpeg ... < /dev/null" but it
+	   requires a shell.
+
+       -debug_ts (global)
+	   Print timestamp information. It is off by default. This option is mostly useful for testing
+	   and debugging purposes, and the output format may change from one version to another, so it
+	   should not be employed by portable scripts.
+
+	   See also the option "-fdebug ts".
+
+       -attach filename (output)
+	   Add an attachment to the output file. This is supported by a few formats like Matroska for
+	   e.g. fonts used in rendering subtitles. Attachments are implemented as a specific type of
+	   stream, so this option will add a new stream to the file. It is then possible to use per-
+	   stream options on this stream in the usual way. Attachment streams created with this option
+	   will be created after all the other streams (i.e. those created with "-map" or automatic
+	   mappings).
+
+	   Note that for Matroska you also have to set the mimetype metadata tag:
+
+		   ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
+
+	   (assuming that the attachment stream will be third in the output file).
+
+       -dump_attachment[:stream_specifier] filename (input,per-stream)
+	   Extract the matching attachment stream into a file named filename. If filename is empty, then
+	   the value of the "filename" metadata tag will be used.
+
+	   E.g. to extract the first attachment to a file named 'out.ttf':
+
+		   ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
+
+	   To extract all attachments to files determined by the "filename" tag:
+
+		   ffmpeg -dump_attachment:t "" -i INPUT
+
+	   Technical note -- attachments are implemented as codec extradata, so this option can actually
+	   be used to extract extradata from any stream, not just attachments.
+
+       -noautorotate
+	   Disable automatically rotating video based on file metadata.
+
+   Video Options
+       -vframes number (output)
+	   Set the number of video frames to output. This is an obsolete alias for "-frames:v", which you
+	   should use instead.
+
+       -r[:stream_specifier] fps (input/output,per-stream)
+	   Set frame rate (Hz value, fraction or abbreviation).
+
+	   As an input option, ignore any timestamps stored in the file and instead generate timestamps
+	   assuming constant frame rate fps.  This is not the same as the -framerate option used for some
+	   input formats like image2 or v4l2 (it used to be the same in older versions of FFmpeg).  If in
+	   doubt use -framerate instead of the input option -r.
+
+	   As an output option, duplicate or drop input frames to achieve constant output frame rate fps.
+
+       -s[:stream_specifier] size (input/output,per-stream)
+	   Set frame size.
+
+	   As an input option, this is a shortcut for the video_size private option, recognized by some
+	   demuxers for which the frame size is either not stored in the file or is configurable -- e.g.
+	   raw video or video grabbers.
+
+	   As an output option, this inserts the "scale" video filter to the end of the corresponding
+	   filtergraph. Please use the "scale" filter directly to insert it at the beginning or some
+	   other place.
+
+	   The format is wxh (default - same as source).
+
+       -aspect[:stream_specifier] aspect (output,per-stream)
+	   Set the video display aspect ratio specified by aspect.
+
+	   aspect can be a floating point number string, or a string of the form num:den, where num and
+	   den are the numerator and denominator of the aspect ratio. For example "4:3", "16:9",
+	   "1.3333", and "1.7777" are valid argument values.
+
+	   If used together with -vcodec copy, it will affect the aspect ratio stored at container level,
+	   but not the aspect ratio stored in encoded frames, if it exists.
+
+       -vn (input/output)
+	   As an input option, blocks all video streams of a file from being filtered or being
+	   automatically selected or mapped for any output. See "-discard" option to disable streams
+	   individually.
+
+	   As an output option, disables video recording i.e. automatic selection or mapping of any video
+	   stream. For full manual control see the "-map" option.
+
+       -vcodec codec (output)
+	   Set the video codec. This is an alias for "-codec:v".
+
+       -pass[:stream_specifier] n (output,per-stream)
+	   Select the pass number (1 or 2). It is used to do two-pass video encoding. The statistics of
+	   the video are recorded in the first pass into a log file (see also the option -passlogfile),
+	   and in the second pass that log file is used to generate the video at the exact requested
+	   bitrate.  On pass 1, you may just deactivate audio and set output to null, examples for
+	   Windows and Unix:
+
+		   ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
+		   ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
+
+       -passlogfile[:stream_specifier] prefix (output,per-stream)
+	   Set two-pass log file name prefix to prefix, the default file name prefix is ``ffmpeg2pass''.
+	   The complete file name will be PREFIX-N.log, where N is a number specific to the output stream
+
+       -vf filtergraph (output)
+	   Create the filtergraph specified by filtergraph and use it to filter the stream.
+
+	   This is an alias for "-filter:v", see the -filter option.
+
+===============================================================================
+===============================================================================
+
+FFMPEG(1)						FFMPEG(1)
+
+NAME
+       ffmpeg - ffmpeg video converter
+
+SYNOPSIS
+       ffmpeg [global_options] {[input_file_options] -i input_url} ... 
+       {[output_file_options] output_url} ...
+
+DESCRIPTION
+       ffmpeg is a very fast video and audio converter that can also 
+       grab from a live audio/video source. It can also convert between 
+       arbitrary sample rates and resize video on the fly with a high 
+       quality polyphase filter.
+
+       ffmpeg reads from an arbitrary number of input "files" (which 
+       can be regular files, pipes, network streams, grabbing devices, 
+       etc.), specified by the "-i" option, and writes to an arbitrary 
+       number of output "files", which are specified by a plain output
+       url. Anything found on the command line which cannot be inter-
+       preted as an option is considered to be an output url.
+
+       Each input or output url can, in principle, contain any number of 
+       streams of different types (video/audio/subtitle/attachment/data). 
+       The allowed number and/or types of streams may be limited by the 
+       container format. Selecting which streams from which inputs will 
+       go into which output is either done automatically or with the 
+       "-map" option (see the Stream selection chapter).
+
+       To refer to input files in options, you must use their indices 
+       (0-based). E.g.  the first input file is 0, the second is 1, etc. 
+       Similarly, streams within a file are referred to by their indices. 
+       E.g. "2:3" refers to the fourth stream in the third input file. 
+       Also see the Stream specifiers chapter.
+
+       As a general rule, options are applied to the next specified file. 
+       Therefore, order is important, and you can have the same option on 
+       the command line multiple times. Each occurrence is then applied 
+       to the next input or output file.  Exceptions from this rule are 
+       the global options (e.g. verbosity level), which should be specified 
+       first.
+
+       Do not mix input and output files -- first specify all input files, 
+       then all output files. Also do not mix options which belong to 
+       different files. All options apply ONLY to the next input or output 
+       file and are reset between files.
+
+       •   To set the video bitrate of the output file to 64 kbit/s:
+
+		   ffmpeg -i input.avi -b:v 64k -bufsize 64k output.avi
+
+       •   To force the frame rate of the output file to 24 fps:
+
+		   ffmpeg -i input.avi -r 24 output.avi
+
+       •   To force the frame rate of the input file (valid for raw formats only) to 1 fps and the frame
+	   rate of the output file to 24 fps:
+
+		   ffmpeg -r 1 -i input.m2v -r 24 output.avi
+
+       The format option may be needed for raw input files.
+
+DETAILED DESCRIPTION
+       The transcoding process in ffmpeg for each output can be described by the following diagram:
+
+		_______ 	     ______________
+	       |       |	    |		   |
+	       | input |  demuxer   | encoded data |   decoder
+	       | file  | ---------> | packets	   | -----+
+	       |_______|	    |______________|	  |
+							  v
+						      _________
+						     |	       |
+						     | decoded |
+						     | frames  |
+						     |_________|
+		________	     ______________	  |
+	       |	|	    |		   |	  |
+	       | output | <-------- | encoded data | <----+
+	       | file	|   muxer   | packets	   |   encoder
+	       |________|	    |______________|
+
+       ffmpeg calls the libavformat library (containing demuxers) to read input files and get packets
+       containing encoded data from them. When there are multiple input files, ffmpeg tries to keep them
+       synchronized by tracking lowest timestamp on any active input stream.
+
+       Encoded packets are then passed to the decoder (unless streamcopy is selected for the stream, see
+       further for a description). The decoder produces uncompressed frames (raw video/PCM audio/...)
+       which can be processed further by filtering (see next section). After filtering, the frames are
+       passed to the encoder, which encodes them and outputs encoded packets. Finally those are passed to
+       the muxer, which writes the encoded packets to the output file.
+
+   Filtering
+       Before encoding, ffmpeg can process raw audio and video frames using filters from the libavfilter
+       library. Several chained filters form a filter graph. ffmpeg distinguishes between two types of
+       filtergraphs: simple and complex.
+
+       Simple filtergraphs
+
+       Simple filtergraphs are those that have exactly one input and output, both of the same type. In
+       the above diagram they can be represented by simply inserting an additional step between decoding
+       and encoding:
+
+		_________			 ______________
+	       |	 |			|	       |
+	       | decoded |			| encoded data |
+	       | frames  |\		      _ | packets      |
+	       |_________| \		      /||______________|
+			    \	__________   /
+		 simple     _\||	  | /  encoder
+		 filtergraph   | filtered |/
+			       | frames   |
+			       |__________|
+
+       Simple filtergraphs are configured with the per-stream -filter option (with -vf and -af aliases
+       for video and audio respectively).  A simple filtergraph for video can look for example like this:
+
+		_______        _____________	    _______	   ________
+	       |       |      | 	    |	   |	   |	  |	   |
+	       | input | ---> | deinterlace | ---> | scale | ---> | output |
+	       |_______|      |_____________|	   |_______|	  |________|
+
+       Note that some filters change frame properties but not frame contents. E.g. the "fps" filter in
+       the example above changes number of frames, but does not touch the frame contents. Another example
+       is the "setpts" filter, which only sets timestamps and otherwise passes the frames unchanged.
+
+       Complex filtergraphs
+
+       Complex filtergraphs are those which cannot be described as simply a linear processing chain
+       applied to one stream. This is the case, for example, when the graph has more than one input
+       and/or output, or when output stream type is different from input. They can be represented with
+       the following diagram:
+
+		_________
+	       |	 |
+	       | input 0 |\		       __________
+	       |_________| \		      | 	 |
+			    \	_________    /| output 0 |
+			     \ |	 |  / |__________|
+		_________     \| complex | /
+	       |	 |     |	 |/
+	       | input 1 |---->| filter  |\
+	       |_________|     |	 | \   __________
+			      /| graph	 |  \ | 	 |
+			     / |	 |   \| output 1 |
+		_________   /  |_________|    |__________|
+	       |	 | /
+	       | input 2 |/
+	       |_________|
+
+       Complex filtergraphs are configured with the -filter_complex option.  Note that this option is
+       global, since a complex filtergraph, by its nature, cannot be unambiguously associated with a
+       single stream or file.
+
+       The -lavfi option is equivalent to -filter_complex.
+
+       A trivial example of a complex filtergraph is the "overlay" filter, which has two video inputs and
+       one video output, containing one video overlaid on top of the other. Its audio counterpart is the
+       "amix" filter.
+
+   Stream copy
+       Stream copy is a mode selected by supplying the "copy" parameter to the -codec option. It makes
+       ffmpeg omit the decoding and encoding step for the specified stream, so it does only demuxing and
+       muxing. It is useful for changing the container format or modifying container-level metadata. The
+       diagram above will, in this case, simplify to this:
+
+		_______ 	     ______________	       ________
+	       |       |	    |		   |	      |        |
+	       | input |  demuxer   | encoded data |  muxer   | output |
+	       | file  | ---------> | packets	   | -------> | file   |
+	       |_______|	    |______________|	      |________|
+
+       Since there is no decoding or encoding, it is very fast and there is no quality loss. However, it
+       might not work in some cases because of many factors. Applying filters is obviously also
+       impossible, since filters work on uncompressed data.
+
+STREAM SELECTION
+       ffmpeg provides the "-map" option for manual control of stream selection in each output file.
+       Users can skip "-map" and let ffmpeg perform automatic stream selection as described below. The
+       "-vn / -an / -sn / -dn" options can be used to skip inclusion of video, audio, subtitle and data
+       streams respectively, whether manually mapped or automatically selected, except for those streams
+       which are outputs of complex filtergraphs.
+
+   Description
+       The sub-sections that follow describe the various rules that are involved in stream selection.
+       The examples that follow next show how these rules are applied in practice.
+
+       While every effort is made to accurately reflect the behavior of the program, FFmpeg is under
+       continuous development and the code may have changed since the time of this writing.
+
+       Automatic stream selection
+
+       In the absence of any map options for a particular output file, ffmpeg inspects the output format
+       to check which type of streams can be included in it, viz. video, audio and/or subtitles. For each
+       acceptable stream type, ffmpeg will pick one stream, when available, from among all the inputs.
+
+       It will select that stream based upon the following criteria:
+
+       •   for video, it is the stream with the highest resolution,
+
+       •   for audio, it is the stream with the most channels,
+
+       •   for subtitles, it is the first subtitle stream found but there's a caveat.  The output
+	   format's default subtitle encoder can be either text-based or image-based, and only a subtitle
+	   stream of the same type will be chosen.
+
+       In the case where several streams of the same type rate equally, the stream with the lowest index
+       is chosen.
+
+       Data or attachment streams are not automatically selected and can only be included using "-map".
+
+       Manual stream selection
+
+       When "-map" is used, only user-mapped streams are included in that output file, with one possible
+       exception for filtergraph outputs described below.
+
+       Complex filtergraphs
+
+       If there are any complex filtergraph output streams with unlabeled pads, they will be added to the
+       first output file. This will lead to a fatal error if the stream type is not supported by the
+       output format. In the absence of the map option, the inclusion of these streams leads to the
+       automatic stream selection of their types being skipped. If map options are present, these
+       filtergraph streams are included in addition to the mapped streams.
+
+       Complex filtergraph output streams with labeled pads must be mapped once and exactly once.
+
+       Stream handling
+
+       Stream handling is independent of stream selection, with an exception for subtitles described
+       below. Stream handling is set via the "-codec" option addressed to streams within a specific
+       output file. In particular, codec options are applied by ffmpeg after the stream selection process
+       and thus do not influence the latter. If no "-codec" option is specified for a stream type, ffmpeg
+       will select the default encoder registered by the output file muxer.
+
+       An exception exists for subtitles. If a subtitle encoder is specified for an output file, the
+       first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate
+       if the specified encoder can convert the selected stream or if the converted stream is acceptable
+       within the output format. This applies generally as well: when the user sets an encoder manually,
+       the stream selection process cannot check if the encoded stream can be muxed into the output file.
+       If it cannot, ffmpeg will abort and all output files will fail to be processed.
+
+   Examples
+       The following examples illustrate the behavior, quirks and limitations of ffmpeg's stream
+       selection methods.
+
+       They assume the following three input files.
+
+	       input file 'A.avi'
+		     stream 0: video 640x360
+		     stream 1: audio 2 channels
+
+	       input file 'B.mp4'
+		     stream 0: video 1920x1080
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (text)
+		     stream 3: audio 5.1 channels
+		     stream 4: subtitles (text)
+
+	       input file 'C.mkv'
+		     stream 0: video 1280x720
+		     stream 1: audio 2 channels
+		     stream 2: subtitles (image)
+
+       Example: automatic stream selection
+
+	       ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
+
+       There are three output files specified, and for the first two, no "-map" options are set, so
+       ffmpeg will select streams for these two files automatically.
+
+       out1.mkv is a Matroska container file and accepts video, audio and subtitle streams, so ffmpeg
+       will try to select one of each type.For video, it will select "stream 0" from B.mp4, which has the
+       highest resolution among all the input video streams.For audio, it will select "stream 3" from
+       B.mp4, since it has the greatest number of channels.For subtitles, it will select "stream 2" from
+       B.mp4, which is the first subtitle stream from among A.avi and B.mp4.
+
+       out2.wav accepts only audio streams, so only "stream 3" from B.mp4 is selected.
+
+       For out3.mov, since a "-map" option is set, no automatic stream selection will occur. The "-map
+       1:a" option will select all audio streams from the second input B.mp4. No other streams will be
+       included in this output file.
+
+       For the first two outputs, all included streams will be transcoded. The encoders chosen will be
+       the default ones registered by each output format, which may not match the codec of the selected
+       input streams.
+
+       For the third output, codec option for audio streams has been set to "copy", so no decoding-
+       filtering-encoding operations will occur, or can occur.	Packets of selected streams shall be
+       conveyed from the input file and muxed within the output file.
+
+       Example: automatic subtitles selection
+
+	       ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
+
+       Although out1.mkv is a Matroska container file which accepts subtitle streams, only a video and
+       audio stream shall be selected. The subtitle stream of C.mkv is image-based and the default
+       subtitle encoder of the Matroska muxer is text-based, so a transcode operation for the subtitles
+       is expected to fail and hence the stream isn't selected. However, in out2.mkv, a subtitle encoder
+       is specified in the command and so, the subtitle stream is selected, in addition to the video
+       stream. The presence of "-an" disables audio stream selection for out2.mkv.
+
+       Example: unlabeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
+
+       A filtergraph is setup here using the "-filter_complex" option and consists of a single video
+       filter. The "overlay" filter requires exactly two video inputs, but none are specified, so the
+       first two available video streams are used, those of A.avi and C.mkv. The output pad of the filter
+       has no label and so is sent to the first output file out1.mp4. Due to this, automatic selection of
+       the video stream is skipped, which would have selected the stream in B.mp4. The audio stream with
+       most channels viz. "stream 3" in B.mp4, is chosen automatically. No subtitle stream is chosen
+       however, since the MP4 format has no default subtitle encoder registered, and the user hasn't
+       specified a subtitle encoder.
+
+       The 2nd output file, out2.srt, only accepts text-based subtitle streams. So, even though the first
+       subtitle stream available belongs to C.mkv, it is image-based and hence skipped.  The selected
+       stream, "stream 2" in B.mp4, is the first text-based subtitle stream.
+
+       Example: labeled filtergraph outputs
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -map '[outv]' -an        out1.mp4 \
+					       out2.mkv \
+		      -map '[outv]' -map 1:a:0 out3.mkv
+
+       The above command will fail, as the output pad labelled "[outv]" has been mapped twice.	None of
+       the output files shall be processed.
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
+		      -an	 out1.mp4 \
+				 out2.mkv \
+		      -map 1:a:0 out3.mkv
+
+       This command above will also fail as the hue filter output has a label, "[outv]", and hasn't been
+       mapped anywhere.
+
+       The command should be modified as follows,
+
+	       ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
+		       -map '[outv1]' -an	 out1.mp4 \
+						 out2.mkv \
+		       -map '[outv2]' -map 1:a:0 out3.mkv
+
+       The video stream from B.mp4 is sent to the hue filter, whose output is cloned once using the split
+       filter, and both outputs labelled. Then a copy each is mapped to the first and third output files.
+
+       The overlay filter, requiring two video inputs, uses the first two unused video streams. Those are
+       the streams from A.avi and C.mkv. The overlay output isn't labelled, so it is sent to the first
+       output file out1.mp4, regardless of the presence of the "-map" option.
+
+       The aresample filter is sent the first unused audio stream, that of A.avi. Since this filter
+       output is also unlabelled, it too is mapped to the first output file. The presence of "-an" only
+       suppresses automatic or manual stream selection of audio streams, not outputs sent from
+       filtergraphs. Both these mapped streams shall be ordered before the mapped stream in out1.mp4.
+
+       The video, audio and subtitle streams mapped to "out2.mkv" are entirely determined by automatic
+       stream selection.
+
+       out3.mkv consists of the cloned video output from the hue filter and the first audio stream from
+       B.mp4.
+
+OPTIONS
+       All the numerical options, if not specified otherwise, accept a string representing a number as
+       input, which may be followed by one of the SI unit prefixes, for example: 'K', 'M', or 'G'.
+
+       If 'i' is appended to the SI unit prefix, the complete prefix will be interpreted as a unit prefix
+       for binary multiples, which are based on powers of 1024 instead of powers of 1000. Appending 'B'
+       to the SI unit prefix multiplies the value by 8. This allows using, for example: 'KB', 'MiB', 'G'
+       and 'B' as number suffixes.
+
+       Options which do not take arguments are boolean options, and set the corresponding value to true.
+       They can be set to false by prefixing the option name with "no". For example using "-nofoo" will
+       set the boolean option with name "foo" to false.
+
+   Stream specifiers
+       Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers are used to
+       precisely specify which stream(s) a given option belongs to.
+
+       A stream specifier is a string generally appended to the option name and separated from it by a
+       colon. E.g. "-codec:a:1 ac3" contains the "a:1" stream specifier, which matches the second audio
+       stream. Therefore, it would select the ac3 codec for the second audio stream.
+
+       A stream specifier can match several streams, so that the option is applied to all of them. E.g.
+       the stream specifier in "-b:a 128k" matches all audio streams.
+
+       An empty stream specifier matches all streams. For example, "-codec copy" or "-codec: copy" would
+       copy all the streams without reencoding.
+
+       Possible forms of stream specifiers are:
+
+       stream_index
+	   Matches the stream with this index. E.g. "-threads:1 4" would set the thread count for the
+	   second stream to 4. If stream_index is used as an additional stream specifier (see below),
+	   then it selects stream number stream_index from the matching streams. Stream numbering is
+	   based on the order of the streams as detected by libavformat except when a program ID is also
+	   specified. In this case it is based on the ordering of the streams in the program.
+
+       stream_type[:additional_stream_specifier]
+	   stream_type is one of following: 'v' or 'V' for video, 'a' for audio, 's' for subtitle, 'd'
+	   for data, and 't' for attachments. 'v' matches all video streams, 'V' only matches video
+	   streams which are not attached pictures, video thumbnails or cover arts. If
+	   additional_stream_specifier is used, then it matches streams which both have this type and
+	   match the additional_stream_specifier. Otherwise, it matches all streams of the specified
+	   type.
+
+       p:program_id[:additional_stream_specifier]
+	   Matches streams which are in the program with the id program_id. If
+	   additional_stream_specifier is used, then it matches streams which both are part of the
+	   program and match the additional_stream_specifier.
+
+       #stream_id or i:stream_id
+	   Match the stream by stream id (e.g. PID in MPEG-TS container).
+
+       m:key[:value]
+	   Matches streams with the metadata tag key having the specified value. If value is not given,
+	   matches streams that contain the given tag with any value.
+
+       u   Matches streams with usable configuration, the codec must be defined and the essential
+	   information such as video dimension or audio sample rate must be present.
+
+	   Note that in ffmpeg, matching by metadata will only work properly for input files.
+
+   Generic options
+       These options are shared amongst the ff* tools.
+
+       -L  Show license.
+
+       -h, -?, -help, --help [arg]
+	   Show help. An optional parameter may be specified to print help about a specific item. If no
+	   argument is specified, only basic (non advanced) tool options are shown.
+
+	   Possible values of arg are:
+
+	   long
+	       Print advanced tool options in addition to the basic tool options.
+
+	   full
+	       Print complete list of options, including shared and private options for encoders,
+	       decoders, demuxers, muxers, filters, etc.
+
+	   decoder=decoder_name
+	       Print detailed information about the decoder named decoder_name. Use the -decoders option
+	       to get a list of all decoders.
+
+	   encoder=encoder_name
+	       Print detailed information about the encoder named encoder_name. Use the -encoders option
+	       to get a list of all encoders.
+
+	   demuxer=demuxer_name
+	       Print detailed information about the demuxer named demuxer_name. Use the -formats option
+	       to get a list of all demuxers and muxers.
+
+	   muxer=muxer_name
+	       Print detailed information about the muxer named muxer_name. Use the -formats option to
+	       get a list of all muxers and demuxers.
+
+	   filter=filter_name
+	       Print detailed information about the filter name filter_name. Use the -filters option to
+	       get a list of all filters.
+
+	   bsf=bitstream_filter_name
+	       Print detailed information about the bitstream filter name bitstream_filter_name.  Use the
+	       -bsfs option to get a list of all bitstream filters.
+
+       -version
+	   Show version.
+
+       -formats
+	   Show available formats (including devices).
+
+       -demuxers
+	   Show available demuxers.
+
+       -muxers
+	   Show available muxers.
+
+       -devices
+	   Show available devices.
+
+       -codecs
+	   Show all codecs known to libavcodec.
+
+	   Note that the term 'codec' is used throughout this documentation as a shortcut for what is
+	   more correctly called a media bitstream format.
+
+       -decoders
+	   Show available decoders.
+
+       -encoders
+	   Show all available encoders.
+
+       -bsfs
+	   Show available bitstream filters.
+
+       -protocols
+	   Show available protocols.
+
+       -filters
+	   Show available libavfilter filters.
+
+       -pix_fmts
+	   Show available pixel formats.
+
+       -sample_fmts
+	   Show available sample formats.
+
+       -layouts
+	   Show channel names and standard channel layouts.
+
+       -colors
+	   Show recognized color names.
+
+       -sources device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sources of the input device.  Some devices may provide system-dependent
+	   source names that cannot be autodetected.  The returned list cannot be assumed to be always
+	   complete.
+
+		   ffmpeg -sources pulse,server=192.168.0.4
+
+       -sinks device[,opt1=val1[,opt2=val2]...]
+	   Show autodetected sinks of the output device.  Some devices may provide system-dependent sink
+	   names that cannot be autodetected.  The returned list cannot be assumed to be always complete.
+
+		   ffmpeg -sinks pulse,server=192.168.0.4
+
+       -loglevel [flags+]loglevel | -v [flags+]loglevel
+	   Set logging level and flags used by the library.
+
+	   The optional flags prefix can consist of the following values:
+
+	   repeat
+	       Indicates that repeated log output should not be compressed to the first line and the
+	       "Last message repeated n times" line will be omitted.
+
+	   level
+	       Indicates that log output should add a "[level]" prefix to each message line. This can be
+	       used as an alternative to log coloring, e.g. when dumping the log to file.
+
+	   Flags can also be used alone by adding a '+'/'-' prefix to set/reset a single flag without
+	   affecting other flags or changing loglevel. When setting both flags and loglevel, a '+'
+	   separator is expected between the last flags value and before loglevel.
+
+	   loglevel is a string or a number containing one of the following values:
+
+	   quiet, -8
+	       Show nothing at all; be silent.
+
+	   panic, 0
+	       Only show fatal errors which could lead the process to crash, such as an assertion
+	       failure. This is not currently used for anything.
+
+	   fatal, 8
+	       Only show fatal errors. These are errors after which the process absolutely cannot
+	       continue.
+
+	   error, 16
+	       Show all errors, including ones which can be recovered from.
+
+	   warning, 24
+	       Show all warnings and errors. Any message related to possibly incorrect or unexpected
+	       events will be shown.
+
+	   info, 32
+	       Show informative messages during processing. This is in addition to warnings and errors.
+	       This is the default value.
+
+	   verbose, 40
+	       Same as "info", except more verbose.
+
+	   debug, 48
+	       Show everything, including debugging information.
+
+	   trace, 56
+
+	   For example to enable repeated log output, add the "level" prefix, and set loglevel to
+	   "verbose":
+
+		   ffmpeg -loglevel repeat+level+verbose -i input output
+
+	   Another example that enables repeated log output without affecting current state of "level"
+	   prefix flag or loglevel:
+
+		   ffmpeg [...] -loglevel +repeat
+
+	   By default the program logs to stderr. If coloring is supported by the terminal, colors are
+	   used to mark errors and warnings. Log coloring can be disabled setting the environment
+	   variable AV_LOG_FORCE_NOCOLOR or NO_COLOR, or can be forced setting the environment variable
+	   AV_LOG_FORCE_COLOR.	The use of the environment variable NO_COLOR is deprecated and will be
+	   dropped in a future FFmpeg version.
+
+       -report
+	   Dump full command line and console output to a file named "program-YYYYMMDD-HHMMSS.log" in the
+	   current directory.  This file can be useful for bug reports.  It also implies "-loglevel
+	   debug".
+
+	   Setting the environment variable FFREPORT to any value has the same effect. If the value is a
+	   ':'-separated key=value sequence, these options will affect the report; option values must be
+	   escaped if they contain special characters or the options delimiter ':' (see the ``Quoting and
+	   escaping'' section in the ffmpeg-utils manual).
+
+	   The following options are recognized:
+
+	   file
+	       set the file name to use for the report; %p is expanded to the name of the program, %t is
+	       expanded to a timestamp, "%%" is expanded to a plain "%"
+
+	   level
+	       set the log verbosity level using a numerical value (see "-loglevel").
+
+	   For example, to output a report to a file named ffreport.log using a log level of 32 (alias
+	   for log level "info"):
+
+		   FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output
+
+	   Errors in parsing the environment variable are not fatal, and will not appear in the report.
+
+       -hide_banner
+	   Suppress printing banner.
+
+	   All FFmpeg tools will normally show a copyright notice, build options and library versions.
+	   This option can be used to suppress printing this information.
+
+       -cpuflags flags (global)
+	   Allows setting and clearing cpu flags. This option is intended for testing. Do not use it
+	   unless you know what you're doing.
+
+		   ffmpeg -cpuflags -sse+mmx ...
+		   ffmpeg -cpuflags mmx ...
+		   ffmpeg -cpuflags 0 ...
+
+	   Possible flags for this option are:
+
+	   x86
+	       mmx
+	       mmxext
+	       sse
+	       sse2
+	       sse2slow
+	       sse3
+	       sse3slow
+	       ssse3
+	       atom
+	       sse4.1
+	       sse4.2
+	       avx
+	       avx2
+	       xop
+	       fma3
+	       fma4
+	       3dnow
+	       3dnowext
+	       bmi1
+	       bmi2
+	       cmov
+	   ARM
+	       armv5te
+	       armv6
+	       armv6t2
+	       vfp
+	       vfpv3
+	       neon
+	       setend
+	   AArch64
+	       armv8
+	       vfp
+	       neon
+	   PowerPC
+	       altivec
+	   Specific Processors
+	       pentium2
+	       pentium3
+	       pentium4
+	       k6
+	       k62
+	       athlon
+	       athlonxp
+	       k8
+
+   AVOptions
+       These options are provided directly by the libavformat, libavdevice and libavcodec libraries. To
+       see the list of available AVOptions, use the -help option. They are separated into two categories:
+
+       generic
+	   These options can be set for any container, codec or device. Generic options are listed under
+	   AVFormatContext options for containers/devices and under AVCodecContext options for codecs.
+
+       private
+	   These options are specific to the given container, device or codec. Private options are listed
+	   under their corresponding containers/devices/codecs.
+
+       For example to write an ID3v2.3 header instead of a default ID3v2.4 to an MP3 file, use the
+       id3v2_version private option of the MP3 muxer:
+
+	       ffmpeg -i input.flac -id3v2_version 3 out.mp3
+
+       All codec AVOptions are per-stream, and thus a stream specifier should be attached to them:
+
+	       ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4
+
+       In the above example, a multichannel audio stream is mapped twice for output.  The first instance
+       is encoded with codec ac3 and bitrate 640k.  The second instance is downmixed to 2 channels and
+       encoded with codec aac. A bitrate of 128k is specified for it using absolute index of the output
+       stream.
+
+       Note: the -nooption syntax cannot be used for boolean AVOptions, use -option 0/-option 1.
+
+       Note: the old undocumented way of specifying per-stream AVOptions by prepending v/a/s to the
+       options name is now obsolete and will be removed soon.
+
+   Main options
+       -f fmt (input/output)
+	   Force input or output file format. The format is normally auto detected for input files and
+	   guessed from the file extension for output files, so this option is not needed in most cases.
+
+       -i url (input)
+	   input file url
+
+       -y (global)
+	   Overwrite output files without asking.
+
+       -n (global)
+	   Do not overwrite output files, and exit immediately if a specified output file already exists.
+
+       -stream_loop number (input)
+	   Set number of times input stream shall be looped. Loop 0 means no loop, loop -1 means infinite
+	   loop.
+
+       -c[:stream_specifier] codec (input/output,per-stream)
+       -codec[:stream_specifier] codec (input/output,per-stream)
+	   Select an encoder (when used before an output file) or a decoder (when used before an input
+	   file) for one or more streams. codec is the name of a decoder/encoder or a special value
+	   "copy" (output only) to indicate that the stream is not to be re-encoded.
+
+	   For example
+
+		   ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
+
+	   encodes all video streams with libx264 and copies all audio streams.
+
+	   For each stream, the last matching "c" option is applied, so
+
+		   ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
+
+	   will copy all the streams except the second video, which will be encoded with libx264, and the
+	   138th audio, which will be encoded with libvorbis.
+
+       -t duration (input/output)
+	   When used as an input option (before "-i"), limit the duration of data read from the input
+	   file.
+
+	   When used as an output option (before an output url), stop writing the output after its
+	   duration reaches duration.
+
+	   duration must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -to position (input/output)
+	   Stop writing the output or reading the input at position.  position must be a time duration
+	   specification, see the Time duration section in the ffmpeg-utils(1) manual.
+
+	   -to and -t are mutually exclusive and -t has priority.
+
+       -fs limit_size (output)
+	   Set the file size limit, expressed in bytes. No further chunk of bytes is written after the
+	   limit is exceeded. The size of the output file is slightly more than the requested file size.
+
+       -ss position (input/output)
+	   When used as an input option (before "-i"), seeks in this input file to position. Note that in
+	   most formats it is not possible to seek exactly, so ffmpeg will seek to the closest seek point
+	   before position.  When transcoding and -accurate_seek is enabled (the default), this extra
+	   segment between the seek point and position will be decoded and discarded. When doing stream
+	   copy or when -noaccurate_seek is used, it will be preserved.
+
+	   When used as an output option (before an output url), decodes but discards input until the
+	   timestamps reach position.
+
+	   position must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+       -sseof position (input)
+	   Like the "-ss" option but relative to the "end of file". That is negative values are earlier
+	   in the file, 0 is at EOF.
+
+       -itsoffset offset (input)
+	   Set the input time offset.
+
+	   offset must be a time duration specification, see the Time duration section in the
+	   ffmpeg-utils(1) manual.
+
+	   The offset is added to the timestamps of the input files. Specifying a positive offset means
+	   that the corresponding streams are delayed by the time duration specified in offset.
+
+       -itsscale scale (input,per-stream)
+	   Rescale input timestamps. scale should be a floating point number.
+
+       -timestamp date (output)
+	   Set the recording timestamp in the container.
+
+	   date must be a date specification, see the Date section in the ffmpeg-utils(1) manual.
+
+       -metadata[:metadata_specifier] key=value (output,per-metadata)
+	   Set a metadata key/value pair.
+
+	   An optional metadata_specifier may be given to set metadata on streams, chapters or programs.
+	   See "-map_metadata" documentation for details.
+
+	   This option overrides metadata set with "-map_metadata". It is also possible to delete
+	   metadata by using an empty value.
+
+	   For example, for setting the title in the output file:
+
+		   ffmpeg -i in.avi -metadata title="my title" out.flv
+
+	   To set the language of the first audio stream:
+
+		   ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
+
+       -disposition[:stream_specifier] value (output,per-stream)
+	   Sets the disposition for a stream.
+
+	   This option overrides the disposition copied from the input stream. It is also possible to
+	   delete the disposition by setting it to 0.
+
+	   The following dispositions are recognized:
+
+	   default
+	   dub
+	   original
+	   comment
+	   lyrics
+	   karaoke
+	   forced
+	   hearing_impaired
+	   visual_impaired
+	   clean_effects
+	   attached_pic
+	   captions
+	   descriptions
+	   dependent
+	   metadata
+
+	   For example, to make the second audio stream the default stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
+
+	   To make the second subtitle stream the default stream and remove the default disposition from
+	   the first subtitle stream:
+
+		   ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
+
+	   To add an embedded cover/thumbnail:
+
+		   ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
+
+	   Not all muxers support embedded thumbnails, and those who do, only support a few formats, like
+	   JPEG or PNG.
+
+       -program [title=title:][program_num=program_num:]st=stream[:st=stream...] (output)
+	   Creates a program with the specified title, program_num and adds the specified stream(s) to
+	   it.
+
+       -target type (output)
+	   Specify target file type ("vcd", "svcd", "dvd", "dv", "dv50"). type may be prefixed with
+	   "pal-", "ntsc-" or "film-" to use the corresponding standard. All the format options (bitrate,
+	   codecs, buffer sizes) are then set automatically. You can just type:
+
+		   ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
+
+	   Nevertheless you can specify additional options as long as you know they do not conflict with
+	   the standard, as in:
+
+		   ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
+
+       -dn (input/output)
+	   As an input option, blocks all data streams of a file from being filtered or being
+	   automatically selected or mapped for any output. See "-discard" option to disable streams
+	   individually.
+
+	   As an output option, disables data recording i.e. automatic selection or mapping of any data
+	   stream. For full manual control see the "-map" option.
+
+       -dframes number (output)
+	   Set the number of data frames to output. This is an obsolete alias for "-frames:d", which you
+	   should use instead.
+
+       -frames[:stream_specifier] framecount (output,per-stream)
+	   Stop writing to the stream after framecount frames.
+
+       -q[:stream_specifier] q (output,per-stream)
+       -qscale[:stream_specifier] q (output,per-stream)
+	   Use fixed quality scale (VBR). The meaning of q/qscale is codec-dependent.  If qscale is used
+	   without a stream_specifier then it applies only to the video stream, this is to maintain
+	   compatibility with previous behavior and as specifying the same codec specific value to 2
+	   different codecs that is audio and video generally is not what is intended when no
+	   stream_specifier is used.
+
+       -filter[:stream_specifier] filtergraph (output,per-stream)
+	   Create the filtergraph specified by filtergraph and use it to filter the stream.
+
+	   filtergraph is a description of the filtergraph to apply to the stream, and must have a single
+	   input and a single output of the same type of the stream. In the filtergraph, the input is
+	   associated to the label "in", and the output to the label "out". See the ffmpeg-filters manual
+	   for more information about the filtergraph syntax.
+
+	   See the -filter_complex option if you want to create filtergraphs with multiple inputs and/or
+	   outputs.
+
+       -filter_script[:stream_specifier] filename (output,per-stream)
+	   This option is similar to -filter, the only difference is that its argument is the name of the
+	   file from which a filtergraph description is to be read.
+
+       -filter_threads nb_threads (global)
+	   Defines how many threads are used to process a filter pipeline. Each pipeline will produce a
+	   thread pool with this many threads available for parallel processing.  The default is the
+	   number of available CPUs.
+
+       -pre[:stream_specifier] preset_name (output,per-stream)
+	   Specify the preset for matching stream(s).
+
+       -stats (global)
+	   Print encoding progress/statistics. It is on by default, to explicitly disable it you need to
+	   specify "-nostats".
+
+       -progress url (global)
+	   Send program-friendly progress information to url.
+
+	   Progress information is written approximately every second and at the end of the encoding
+	   process. It is made of "key=value" lines. key consists of only alphanumeric characters. The
+	   last key of a sequence of progress information is always "progress".
+
+       -stdin
+	   Enable interaction on standard input. On by default unless standard input is used as an input.
+	   To explicitly disable interaction you need to specify "-nostdin".
+
+	   Disabling interaction on standard input is useful, for example, if ffmpeg is in the background
+	   process group. Roughly the same result can be achieved with "ffmpeg ... < /dev/null" but it
+	   requires a shell.
+
+       -debug_ts (global)
+	   Print timestamp information. It is off by default. This option is mostly useful for testing
+	   and debugging purposes, and the output format may change from one version to another, so it
+	   should not be employed by portable scripts.
+
+	   See also the option "-fdebug ts".
+
+       -attach filename (output)
+	   Add an attachment to the output file. This is supported by a few formats like Matroska for
+	   e.g. fonts used in rendering subtitles. Attachments are implemented as a specific type of
+	   stream, so this option will add a new stream to the file. It is then possible to use per-
+	   stream options on this stream in the usual way. Attachment streams created with this option
+	   will be created after all the other streams (i.e. those created with "-map" or automatic
+	   mappings).
+
+	   Note that for Matroska you also have to set the mimetype metadata tag:
+
+		   ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
+
+	   (assuming that the attachment stream will be third in the output file).
+
+       -dump_attachment[:stream_specifier] filename (input,per-stream)
+	   Extract the matching attachment stream into a file named filename. If filename is empty, then
+	   the value of the "filename" metadata tag will be used.
+
+	   E.g. to extract the first attachment to a file named 'out.ttf':
+
+		   ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
+
+	   To extract all attachments to files determined by the "filename" tag:
+
+		   ffmpeg -dump_attachment:t "" -i INPUT
+
+	   Technical note -- attachments are implemented as codec extradata, so this option can actually
+	   be used to extract extradata from any stream, not just attachments.
+
+       -noautorotate
+	   Disable automatically rotating video based on file metadata.
+
+   Video Options
+       -vframes number (output)
+	   Set the number of video frames to output. This is an obsolete alias for "-frames:v", which you
+	   should use instead.
+
+       -r[:stream_specifier] fps (input/output,per-stream)
+	   Set frame rate (Hz value, fraction or abbreviation).
+
+	   As an input option, ignore any timestamps stored in the file and instead generate timestamps
+	   assuming constant frame rate fps.  This is not the same as the -framerate option used for some
+	   input formats like image2 or v4l2 (it used to be the same in older versions of FFmpeg).  If in
+	   doubt use -framerate instead of the input option -r.
+
+	   As an output option, duplicate or drop input frames to achieve constant output frame rate fps.
+
+       -s[:stream_specifier] size (input/output,per-stream)
+	   Set frame size.
+
+	   As an input option, this is a shortcut for the video_size private option, recognized by some
+	   demuxers for which the frame size is either not stored in the file or is configurable -- e.g.
+	   raw video or video grabbers.
+
+	   As an output option, this inserts the "scale" video filter to the end of the corresponding
+	   filtergraph. Please use the "scale" filter directly to insert it at the beginning or some
+	   other place.
+
+	   The format is wxh (default - same as source).
+
+       -aspect[:stream_specifier] aspect (output,per-stream)
+	   Set the video display aspect ratio specified by aspect.
+
+	   aspect can be a floating point number string, or a string of the form num:den, where num and
+	   den are the numerator and denominator of the aspect ratio. For example "4:3", "16:9",
+	   "1.3333", and "1.7777" are valid argument values.
+
+	   If used together with -vcodec copy, it will affect the aspect ratio stored at container level,
+	   but not the aspect ratio stored in encoded frames, if it exists.
+
+===============================================================================
+===============================================================================
\ No newline at end of file
diff --git a/examples/online_session/openai_chat_completion_client.py b/examples/online_session/openai_chat_completion_client.py
new file mode 100644
index 0000000..173b9e0
--- /dev/null
+++ b/examples/online_session/openai_chat_completion_client.py
@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""
+Interactive TTFT‑benchmark with optional (opt‑in) KV‑cache flush + repeats.
+
+Context‑file precedence
+-----------------------
+1. --context_file FILE      → read FILE
+2. --context_file (no FILE) → ../ffmpeg.txt
+3. (flag omitted)           → generate random ASCII filler
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from io import StringIO
+from pathlib import Path
+from typing import List
+import argparse
+import json
+import random
+import string
+import sys
+import threading
+import time
+
+# Third Party
+from openai import OpenAI
+from transformers import AutoTokenizer, PreTrainedTokenizerBase
+
+# ----------------------------------------------------------------------
+SAFETY_MARGIN = 2048  # tokens kept free below model ctx limit
+FILLER_LEN_CHARS = 100_000  # ≈ length of each cache‑filler prompt
+NUM_FILLER_PROMPTS = 10  # how many fillers to send for eviction
+DEFAULT_FFMPEG = "ffmpeg.txt"
+# ----------------------------------------------------------------------
+
+
+# ---------------- helper utilities ------------------------------------
+def rand_ascii(n: int) -> str:
+    return "".join(random.choices(string.ascii_letters + string.digits, k=n))
+
+
+def truncate_to_tokens(
+    text: str,
+    max_tokens: int,
+    tok: PreTrainedTokenizerBase,
+) -> str:
+    ids = tok.encode(
+        text, add_special_tokens=False, truncation=True, max_length=max_tokens
+    )
+    return tok.decode(ids, skip_special_tokens=True)
+
+
+def log_jsonl(path: Path, rec: dict) -> None:
+    with path.open("a", encoding="utf-8") as fh:
+        json.dump(rec, fh)
+        fh.write("\n")
+
+
+# ---------------- tiny CLI spinner ------------------------------------
+class Printer:
+    def __init__(self) -> None:
+        self._thread: threading.Thread | None = None
+        self._stop_event = threading.Event()
+
+    def _spin(self) -> None:
+        idx = 0
+        while not self._stop_event.is_set():
+            print(f"\033[31m\r{'>' * (idx % 6):<6}\033[0m", end="", flush=True)
+            idx += 1
+            time.sleep(0.2)
+
+    def start(self) -> None:
+        if self._thread is None:
+            self._stop_event.clear()
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+
+    def stop(self) -> None:
+        if self._thread is not None:
+            self._stop_event.set()
+            self._thread.join()
+            self._thread = None
+            print("\033[31m\r>>>>> \033[0m", end="", flush=True)
+
+
+# ---------------- benchmark helpers -----------------------------------
+def build_chat(system_doc: str, user_prompt: str) -> List[dict]:
+    return [
+        {"role": "user", "content": f"I've got a document:\n```\n{system_doc}\n```"},
+        {"role": "assistant", "content": "I've got your document."},
+        {"role": "user", "content": user_prompt},
+    ]
+
+
+def ttft_stream(
+    client: OpenAI,
+    model: str,
+    messages: list[dict],
+    printer: Printer | None = None,
+) -> tuple[float, str]:
+    start = time.perf_counter()
+    stream = client.chat.completions.create(
+        model=model,
+        messages=messages,
+        temperature=0.0,
+        stream=True,
+        max_tokens=1024,
+    )
+    first_tok_t: float | None = None
+    buf = StringIO()
+    if printer:
+        printer.start()
+
+    for chunk in stream:
+        delta = chunk.choices[0].delta
+        if delta.content:
+            if first_tok_t is None:
+                first_tok_t = time.perf_counter()
+                if printer:
+                    printer.stop()
+            print(delta.content, end="", flush=True)
+            buf.write(delta.content)
+
+    print()  # newline after streaming
+    if first_tok_t is None:
+        raise RuntimeError("no tokens returned")
+    return first_tok_t - start, buf.getvalue()
+
+
+def flush_kv_cache(client: OpenAI, model: str) -> None:
+    filler_chat = build_chat(rand_ascii(FILLER_LEN_CHARS), "noop")
+    for _ in range(NUM_FILLER_PROMPTS):
+        client.chat.completions.create(
+            model=model,
+            messages=filler_chat,
+            temperature=0.0,
+            max_tokens=1,
+            stream=False,
+        )
+
+
+# ---------------- command‑line parsing --------------------------------
+def parse_args() -> argparse.Namespace:
+    # legacy single‑positional <port> usage
+    if len(sys.argv) == 2 and sys.argv[1].isdigit():
+        port = sys.argv[1]
+        sys.argv = [sys.argv[0], "--api_base", f"http://localhost:{port}/v1"]
+
+    ap = argparse.ArgumentParser(
+        prog=Path(sys.argv[0]).name,
+        description="Interactive TTFT benchmark; \
+        flush cache only with -F/--flush_cache.",
+    )
+    ap.add_argument("--api_base", default="http://localhost:8000/v1")
+    ap.add_argument("--api_key", default="EMPTY")
+    ap.add_argument(
+        "--model", help="Model name/ID; default = first entry from /models."
+    )
+    # nargs='?' lets the flag appear without a path
+    ap.add_argument(
+        "-C",
+        "--context_file",
+        nargs="?",
+        const="",
+        default=None,
+        help="FILE → use document, flag‑only → ffmpeg.txt, "
+        "omit flag → synthetic filler",
+    )
+    ap.add_argument(
+        "--max_ctx_tokens",
+        type=int,
+        default=131_072,
+        help="Max tokens kept from the document after truncation.",
+    )
+    ap.add_argument(
+        "--prompt",
+        default="Summarize this text",
+        help="User prompt appended after the document.",
+    )
+    ap.add_argument(
+        "--num_following",
+        type=int,
+        default=1,
+        help="Extra measured requests after run 1 to test cache retrieval.",
+    )
+    ap.add_argument(
+        "--flush_cache",
+        "-F",
+        action="store_true",
+        help="Evict GPU KV‑cache between run 1 and follow‑ups.",
+    )
+    ap.add_argument(
+        "--out",
+        default="benchmark.jsonl",
+        help="JSONL file for results (overwritten each run).",
+    )
+    return ap.parse_args()
+
+
+# ---------------- main routine ----------------------------------------
+def main() -> None:
+    args = parse_args()
+
+    client = OpenAI(api_key=args.api_key, base_url=args.api_base)
+
+    # pick model (fallback = first listed on the server)
+    model_id = args.model or client.models.list().data[0].id
+
+    # ---------- choose / build the document ---------------------------
+    if args.context_file is None:
+        # flag omitted → synthetic filler
+        # here we will generate a random ASCII string based on the max ctx tokens,
+        raw_doc = rand_ascii(args.max_ctx_tokens * 4)  # ≈4 chars/token
+        # make the synthetic filler longer and truncate it later after tokenization
+    elif args.context_file == "":
+        # flag present w/o file → bundled ffmpeg.txt
+        raw_doc = Path(DEFAULT_FFMPEG).read_text(encoding="utf-8")
+    else:
+        raw_doc = Path(args.context_file).read_text(encoding="utf-8")
+
+    # ---------- truncate ------------------------------------------------
+    try:
+        tok = AutoTokenizer.from_pretrained(model_id, use_fast=True)
+        model_ctx = (
+            tok.model_max_length if tok.model_max_length > 0 else args.max_ctx_tokens
+        )
+        doc = truncate_to_tokens(
+            raw_doc, min(model_ctx - SAFETY_MARGIN, args.max_ctx_tokens), tok
+        )
+    except Exception:
+        char_limit = (args.max_ctx_tokens - SAFETY_MARGIN) * 4  # ≈4 chars/token
+        doc = raw_doc[:char_limit]
+
+    out_path = Path(args.out)
+    out_path.write_text("", encoding="utf-8")  # clear file
+    printer = Printer()
+
+    # ---------------- RUN 1 ----------------
+    print("\n=== Run 1: baseline TTFT ===")
+    base_chat = build_chat(doc, args.prompt)
+    ttft1, gen1 = ttft_stream(client, model_id, base_chat, printer)
+    print(f"\033[33mTTFT_1 = {ttft1:.3f}s\033")
+    log_jsonl(
+        out_path,
+        {
+            "run_index": 1,
+            "context_tokens": len(tok.encode(doc, add_special_tokens=False)),
+            "ttft_seconds": ttft1,
+        },
+    )
+
+    # -------------- optional follow‑ups --------------
+    if args.num_following > 0:
+        if args.flush_cache:
+            print(f"\nFlushing KV‑cache with {NUM_FILLER_PROMPTS} prompts …")
+            flush_kv_cache(client, model_id)
+        else:
+            print("\n(no KV‑cache flush requested)")
+
+        for run in range(2, 2 + args.num_following):
+            label = "post‑flush" if args.flush_cache else "continued"
+            print(f"\n=== Run {run}: TTFT {label} ===")
+            ttft, gen = ttft_stream(client, model_id, base_chat, printer)
+            print(f"\033[33mTTFT_{run} = {ttft:.3f}s\033[0m • ")
+            log_jsonl(
+                out_path,
+                {
+                    "run_index": run,
+                    "context_tokens": len(tok.encode(doc, add_special_tokens=False)),
+                    "ttft_seconds": ttft,
+                },
+            )
+            time.sleep(5)  # brief idle gap
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/p2p/README.md b/examples/p2p/README.md
new file mode 100644
index 0000000..101e3f1
--- /dev/null
+++ b/examples/p2p/README.md
@@ -0,0 +1,210 @@
+# P2P KV Cache Sharing (multiprocess mode)
+
+In a multi-node deployment, every node runs its own LMCache server, and each
+one only caches the KV of the requests it served. **P2P KV cache sharing turns
+those per-node caches into one logical cache:** when a node looks up a prefix
+it does not have locally, it reads that prefix's KV directly from the memory of
+the peer that holds it, over the datacenter network using RDMA — instead of
+recomputing the prefix.
+
+This example shows how to run it both on a single node (for testing/debugging)
+and across multiple nodes, and what logs to expect.
+
+> See also the full reference: [`docs/source/mp/p2p.rst`](../../docs/source/mp/p2p.rst).
+
+## How it works
+
+- **Coordinator** — one small HTTP service per deployment that tracks which
+  LMCache servers are alive. It only manages membership; it never sees KV data.
+- **LMCache server** — each server polls the coordinator for live peers and, for
+  every peer, opens a connection used to look up and RDMA-read that peer's KV.
+- **vLLM** talks only to its **local** LMCache server (via `LMCacheMPConnector`).
+  The P2P fetch happens inside the LMCache server, transparently to vLLM.
+
+## Requirements
+
+- LMCache (full install, with CUDA) + vLLM, on every node.
+- A **coordinator** URL reachable by all nodes (P2P refuses to start without
+  `--coordinator-url`).
+- An **RDMA-capable network** (InfiniBand / RoCE) for production performance.
+- A **single, contiguous L1 region** — P2P is incompatible with the GDS
+  (`--gds-l1-path`) and Device-DAX (`--l1-devdax-path`) L1 tiers; the server
+  refuses to start in those configurations.
+- Recommended: `--l1-align-bytes 65536` (64 KB) on P2P servers for larger,
+  better-aligned RDMA reads.
+
+---
+
+## Single-node setup (testing & debugging)
+
+Run two LMCache servers and two vLLM servers over `localhost`, plus one
+coordinator, on a 2-GPU machine. This exercises the entire P2P path without a
+real network.
+
+Open five terminals:
+
+```bash
+# Terminal 1 — coordinator
+lmcache coordinator --host 0.0.0.0 --port 9300
+
+# Terminal 2 — node A: LMCache server
+lmcache server \
+    --host 127.0.0.1 --port 6555 --http-port 7555 \
+    --l1-size-gb 50 --eviction-policy LRU \
+    --l1-align-bytes 65536 \
+    --instance-id node-a \
+    --coordinator-url http://127.0.0.1:9300 \
+    --coordinator-advertise-ip 127.0.0.1 \
+    --p2p-advertise-url 127.0.0.1:8555
+
+# Terminal 3 — node A: vLLM on GPU 0, connector -> local LMCache (port 6555)
+CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen3-14B --port 8000 \
+    --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_load_failure_policy":"recompute","kv_connector_extra_config":{"lmcache.mp.port":6555}}'
+
+# Terminal 4 — node B: LMCache server
+lmcache server \
+    --host 127.0.0.1 --port 6556 --http-port 7556 \
+    --l1-size-gb 50 --eviction-policy LRU \
+    --l1-align-bytes 65536 \
+    --instance-id node-b \
+    --coordinator-url http://127.0.0.1:9300 \
+    --coordinator-advertise-ip 127.0.0.1 \
+    --p2p-advertise-url 127.0.0.1:8556
+
+# Terminal 5 — node B: vLLM on GPU 1, connector -> local LMCache (port 6556)
+CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-14B --port 8001 \
+    --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_load_failure_policy":"recompute","kv_connector_extra_config":{"lmcache.mp.port":6556}}'
+```
+
+The two LMCache servers must differ in **every** port: ZMQ (`--port`), HTTP
+(`--http-port`), and the P2P transfer endpoint (`--p2p-advertise-url`). Give
+each a distinct `--instance-id`.
+
+> **Note:** on a single host, `localhost` traffic uses the loopback/TCP path,
+> not RDMA, so latencies are not representative of a real fabric. Single-node
+> mode is for **functional** testing — benchmark on a real multi-node RDMA
+> deployment.
+
+### Test it
+
+```bash
+# 1. Populate node A's cache (cold — expect ~0 LMCache hits).
+python send_request.py --port 8000
+
+# 2. Send the SAME prompt to node B. B never served it and its cache is empty,
+#    so any LMCache hit must have been read from A over P2P.
+python send_request.py --port 8001
+```
+
+The second call should print a non-zero `num_lmcache_cached_tokens`.
+
+---
+
+## Multi-node setup
+
+Start the coordinator on a host all nodes can reach (here `10.0.0.1`), then run
+one LMCache server + one vLLM per node. Adding more nodes is just more copies of
+the per-node block, all pointing at the same coordinator.
+
+```bash
+# Coordinator host (10.0.0.1)
+lmcache coordinator --host 0.0.0.0 --port 9300
+```
+
+On **each** node, set `NODE_IP` to that node's routable address and run:
+
+```bash
+NODE_IP=10.0.0.2          # this node's address (change per node)
+COORDINATOR=10.0.0.1
+
+# RDMA tuning for UCX (adjust transports/rails to your fabric).
+export UCX_TLS=rc,sm,self
+export UCX_MAX_RMA_RAILS=8
+
+# 1. LMCache server with P2P enabled. Bind 0.0.0.0, advertise NODE_IP.
+lmcache server \
+    --host 0.0.0.0 --port 6555 --http-port 7555 \
+    --l1-size-gb 100 --eviction-policy LRU \
+    --l1-align-bytes 65536 \
+    --instance-id "lmcache-${NODE_IP}" \
+    --coordinator-url "http://${COORDINATOR}:9300" \
+    --coordinator-advertise-ip "${NODE_IP}" \
+    --p2p-advertise-url "${NODE_IP}:8555" \
+    --p2p-listen-url 0.0.0.0:8555
+
+# 2. vLLM, connector pointed at the LOCAL LMCache server (port 6555).
+vllm serve Qwen/Qwen3-14B --port 8000 \
+    --kv-transfer-config '{"kv_connector":"LMCacheMPConnector","kv_role":"kv_both","kv_load_failure_policy":"recompute","kv_connector_extra_config":{"lmcache.mp.port":6555}}'
+```
+
+`--coordinator-advertise-ip` is the address peers reach this node's control
+plane at; `--p2p-advertise-url` is its RDMA transfer endpoint. Binding `0.0.0.0`
+while advertising `NODE_IP` (via `--p2p-listen-url`) is the usual pattern when a
+node has multiple interfaces.
+
+Once two nodes are up, send a long prompt to one node and the same prompt to
+another — the second serves it from the first over RDMA:
+
+```bash
+python send_request.py --host 10.0.0.2 --port 8000
+python send_request.py --host 10.0.0.3 --port 8000
+```
+
+---
+
+## What logs to expect
+
+**Coordinator** logs each instance as it registers:
+
+```
+Registered instance node-a at 127.0.0.1:7555
+Registered instance node-b at 127.0.0.1:7556
+```
+
+**Each LMCache server** at startup and as it discovers its peer (INFO level):
+
+```
+Started PeriodicThread: p2p-controller-thread (level=medium, interval=5.0s, init_wait=0.0s)
+Registered with coordinator as node-a
+Added L2 adapter 0 (p2p)          # created when the peer is discovered
+```
+
+With `LMCACHE_LOG_LEVEL=DEBUG`, the P2P controller also names the peer:
+
+```
+Added P2P adapter 0 for peer node-b (127.0.0.1:8556)
+```
+
+When a peer leaves (or after ~3 missed discovery polls), you'll see the adapter
+torn down:
+
+```
+Deleted L2 adapter 0
+Removed P2P adapter for peer node-b   # DEBUG
+```
+
+## Verifying P2P is working
+
+Query a server's status endpoint for its P2P state and connected peers:
+
+```bash
+curl -s http://127.0.0.1:7555/status | python3 -m json.tool
+# look for: "p2p_state": "registered", "p2p_peer_count": 1, "p2p_peers": ["node-b"]
+```
+
+List the fleet from the coordinator:
+
+```bash
+curl -s http://127.0.0.1:9300/instances | python3 -m json.tool
+```
+
+A successful P2P read shows up as a non-zero `num_lmcache_cached_tokens` from
+`send_request.py` on a node that never served the prompt (see the test steps
+above).
+
+## Notes
+
+- **Read-only:** a node reads KV from its peers; it never writes into a peer's
+  memory.
+- **One hop:** a node reads directly from the peer that holds the prefix; reads
+  are not chained across multiple peers.
diff --git a/examples/p2p/send_request.py b/examples/p2p/send_request.py
new file mode 100644
index 0000000..4f1ab99
--- /dev/null
+++ b/examples/p2p/send_request.py
@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Send a long prompt to a vLLM + LMCache server and print its cache-hit stats.
+
+Used to demonstrate P2P KV cache sharing: send the prompt to node A first
+(populates A's cache), then send the *same* prompt to node B. Because B never
+served the prompt and its only remote cache source is its P2P peer (A), a
+non-zero ``num_lmcache_cached_tokens`` on B proves the KV was read from A over
+P2P.
+
+Usage:
+    python send_request.py --port 8000                 # node A (cold)
+    python send_request.py --port 8001                 # node B (P2P hit)
+    python send_request.py --host 10.0.0.3 --port 8000 # a remote node
+"""
+
+# Standard
+import argparse
+import json
+import urllib.request
+
+# A prompt long enough to span several LMCache chunks (default 256 tokens each).
+LONG_PROMPT = "Explain the history of computer science in great detail. " + (
+    "The Turing machine is a fundamental concept in theoretical computer "
+    "science that defines an abstract machine capable of manipulating "
+    "symbols on a strip of tape according to a table of rules. " * 20
+)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="localhost")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--model", default="Qwen/Qwen3-14B")
+    args = parser.parse_args()
+
+    body = {
+        "model": args.model,
+        "messages": [{"role": "user", "content": LONG_PROMPT}],
+        "max_tokens": 1,
+        # Opt in to per-request cache-hit accounting in the response.
+        "kv_transfer_params": {"cached_token_stats": True},
+    }
+    request = urllib.request.Request(
+        f"http://{args.host}:{args.port}/v1/chat/completions",
+        data=json.dumps(body).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(request) as response:
+        data = json.loads(response.read())
+
+    stats = (data.get("kv_transfer_params") or {}).get("cached_token_stats")
+    if stats is None:
+        print("No cached_token_stats in response (is LMCache enabled?):")
+        print(json.dumps(data, indent=2))
+        return
+
+    print(json.dumps(stats, indent=2))
+    print(f"\nnum_lmcache_cached_tokens = {stats['num_lmcache_cached_tokens']}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/redis_lookup/README.md b/examples/redis_lookup/README.md
new file mode 100644
index 0000000..955d86f
--- /dev/null
+++ b/examples/redis_lookup/README.md
@@ -0,0 +1,152 @@
+# Search LMCache KV Entry in Redis
+
+This example shows how to search the LMCache KV entry in Redis.
+
+## Installing Redis
+
+### Ubuntu Installation
+
+```bash
+sudo apt update
+sudo apt install redis-server
+sudo systemctl start redis-server
+sudo systemctl status redis-server
+```
+
+### RHEL/CentOS Installation
+
+```bash
+sudo yum install redis
+sudo systemctl start redis
+sudo systemctl enable redis
+sudo systemctl status redis
+```
+
+## Configuration Steps
+
+### Create a LMCache Configuration File
+
+Create a file `/tmp/lmcache-config.yaml` with Redis configuration:
+
+```yaml
+# Basic LMCache settings
+chunk_size: 256
+local_cpu: True
+max_local_cpu_size: 5
+
+# Redis connection
+remote_url: "redis://your-redis-host:6379"
+```
+
+### Run the Container with Redis Support
+
+```bash
+docker run --runtime nvidia --gpus all \
+    -v /tmp/lmcache-config.yaml:/config/lmcache-config.yaml \
+    --env "LMCACHE_CONFIG_FILE=/config/lmcache-config.yaml" \
+    --env "HF_TOKEN=<YOUR_HUGGINGFACE_TOKEN>" \
+    --env "LMCACHE_CHUNK_SIZE=256" \
+    --env "LMCACHE_LOCAL_CPU=True" \
+    --env "LMCACHE_MAX_LOCAL_CPU_SIZE=5" \
+    -v ~/.cache/huggingface:/home/ubuntu/.cache/huggingface \
+    --network host \
+    lmcache/vllm-openai:latest \
+    mistralai/Mistral-7B-Instruct-v0.2 --port 8001 --kv-transfer-config \
+    '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
+```
+
+  Then run the following command to query vLLM to populate the LMCache:
+  ```bash
+  curl -X 'POST' \
+   'http://127.0.0.1:8001/v1/chat/completions' \
+   -H 'accept: application/json' \
+   -H 'Content-Type: application/json' \
+   -d '{
+      "model": "mistralai/Mistral-7B-Instruct-v0.2",
+      "messages": [
+      {"role": "system", "content": "You are a helpful AI coding assistant."},
+      {"role": "user", "content": "Write a segment tree implementation in python"}
+      ],
+      "max_tokens": 150
+   }'
+  ```
+
+## Viewing and Managing LMCache Entries in Redis
+
+### LMCache Redis Keys
+
+LMCache stores data in Redis using a structured key format. Each key contains the following information in a delimited format:
+
+```
+model_name@world_size@worker_id@chunk_hash
+```
+
+Where:
+- `model_name`: Name of the language model
+- `world_size`: Total number of workers in distributed deployment
+- `worker_id`: ID of the worker that created this cache entry
+- `chunk_hash`: Hash of the token chunk (SHA-256 based)
+
+For example, a typical key might look like:
+```
+vllm@mistralai/Mistral-7B-Instruct-v0.2@1@0@a1b2c3d4e5f6...
+```
+
+### Using redis-cli to View LMCache Data
+
+To inspect and manage LMCache entries in Redis:
+
+#### Connect to Redis
+   ```bash
+   redis-cli -h localhost -p 6379
+   ```
+
+#### List all LMCache keys
+   ```bash
+   # Show all keys
+   KEYS *
+
+   # Show keys for a specific model
+   KEYS *Mistral-7B*
+   ```
+
+  For example, to check if a key exists:
+  ```console
+  localhost:6379> KEYS *
+  1) "vllm@mistralai/Mistral-7B-Instruct-v0.2@1@0@2aea46f4fa38170e8425a6e6ee3c5173a1fa97917bc1a583888c87ad4f9a9a20metadata"
+  2) "vllm@mistralai/Mistral-7B-Instruct-v0.2@1@0@2aea46f4fa38170e8425a6e6ee3c5173a1fa97917bc1a583888c87ad4f9a9a20kv_bytes"
+  ```
+
+#### Check if a key exists
+   ```bash
+   EXISTS "vllm@model_name@1@0@hash_value"
+   ```
+
+#### View memory usage for a key
+   ```bash
+   MEMORY USAGE "vllm@model_name@1@0@hash_value"
+   ```
+
+#### Delete specific keys
+   ```bash
+   # Delete a single key
+   DEL "vllm@model_name@1@0@hash_value"
+   
+   # Delete all keys matching a pattern
+   redis-cli -h <host> -p <port> --scan --pattern "vllm@model_name*" | xargs redis-cli -h <host> -p <port> DEL
+   ```
+
+#### Monitor Redis in real-time
+   ```bash
+   MONITOR
+   ```
+
+#### Get Redis stats for LMCache
+   ```bash
+   # Get memory stats
+   INFO memory
+   
+   # Get statistics about operations
+   INFO stats
+   ```
+
diff --git a/examples/remote_config_server/README.md b/examples/remote_config_server/README.md
new file mode 100644
index 0000000..c7b40e7
--- /dev/null
+++ b/examples/remote_config_server/README.md
@@ -0,0 +1,123 @@
+# Remote Config Server Example
+
+This example provides a reference implementation of a remote config server
+that can be used with LMCache's dynamic configuration feature.
+
+## Overview
+
+LMCache supports fetching configuration from a remote config service at startup.
+This allows centralized management of LMCache configurations across multiple workers.
+
+## Configuration Fields
+
+To enable remote configuration, add these fields to your LMCache config file:
+
+```yaml
+# URL of the remote config service
+remote_config_url: "http://localhost:8088/config"
+
+# Optional: Application ID for identifying different applications
+app_id: "my-app-001"
+```
+
+## Protocol Specification
+
+### Request
+
+The LMCache worker sends a **POST** request to the `remote_config_url`:
+
+- **Method**: POST
+- **Query Parameters**: `?appId=<app_id>` (if `app_id` is configured)
+- **Headers**: `Content-Type: application/json`
+- **Body**:
+```json
+{
+    "current_config": {
+        "chunk_size": 256,
+        "local_device": "cpu",
+        ...
+    },
+    "env_variables": {
+        "LMCACHE_CONFIG_FILE": "/path/to/config.yaml",
+        "HOME": "/home/user",
+        ...
+    }
+}
+```
+
+### Response
+
+The config server should return a JSON response:
+
+```json
+{
+  "configs": [
+    {
+      "key": "chunk_size",
+      "override": false,
+      "value": 1024
+    },
+    {
+      "key": "max_local_cpu_size",
+      "override": false,
+      "value": 2
+    },
+    {
+      "key": "lmcache_worker_heartbeat_time",
+      "override": true,
+      "value": "14"
+    },
+    {
+      "key": "extra_config",
+      "override": true,
+      "value": "{\"internal_api_server_access_log\": true, \"internal_api_server_log_level\":\"info\", \"save_only_first_rank\": true, \"first_rank_max_local_cpu_size\": 1.1}"
+    }
+  ]
+}
+```
+
+#### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `configs` | array | List of configuration items to apply |
+| `configs[].key` | string | Configuration key name (must match LMCache config fields) |
+| `configs[].value` | any | Value to set for this configuration |
+| `configs[].override` | boolean | If `true`, always override. If `false`, only apply when current value is `None` |
+
+## Running the Example
+
+1. Install dependencies:
+```bash
+pip install flask
+```
+
+2. Start the config server:
+```bash
+python config_server.py
+```
+
+3. Configure LMCache to use this server:
+```yaml
+# example.yaml
+chunk_size: 256
+local_device: "cpu"
+remote_config_url: "http://localhost:8088/config"
+app_id: "test-app"
+```
+
+4. Start your LMCache-enabled application with the config file.
+
+## Customization
+
+You can customize the `config_server.py` to:
+- Fetch configurations from a database
+- Apply different configs based on `app_id`
+- Implement access control based on environment variables
+- Add logging and monitoring
+
+5. How to test
+
+Start standalone LMCache server to check if the config server and remote config are working properly.
+
+See the document of `standalone_starter` for more details.
diff --git a/examples/remote_config_server/config_server.py b/examples/remote_config_server/config_server.py
new file mode 100644
index 0000000..73dde32
--- /dev/null
+++ b/examples/remote_config_server/config_server.py
@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""
+Reference implementation of a remote config server for LMCache.
+
+This is a simple Flask-based config server that demonstrates the protocol
+between LMCache workers and a centralized configuration service.
+
+Usage:
+    python config_server.py [--port PORT] [--host HOST]
+
+The server exposes a single endpoint:
+    POST /config?appId=<app_id>
+
+See README.md for the full protocol specification.
+"""
+
+# Standard
+from typing import Any
+import argparse
+import logging
+
+# Third Party
+from flask import Flask, jsonify, request
+
+app = Flask(__name__)
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Example configuration database
+# In production, this could be fetched from a database, config file, or other service
+CONFIG_DATABASE: dict[str, list[dict[str, Any]]] = {
+    # Default configs applied to all apps
+    "default": [
+        {"key": "chunk_size", "value": 512, "override": False},
+        {"key": "max_local_cpu_size", "value": 1, "override": False},
+    ],
+    # App-specific configs
+    "test-app": [
+        {"key": "chunk_size", "value": 1024, "override": False},
+        {"key": "max_local_cpu_size", "value": 2, "override": False},
+        {"key": "lmcache_worker_heartbeat_time", "value": "14", "override": True},
+        {
+            "key": "extra_config",
+            "value": '{"internal_api_server_access_log": true, '
+            '"internal_api_server_log_level":"info", '
+            '"save_only_first_rank": true, '
+            '"first_rank_max_local_cpu_size": 1.1}',
+            "override": True,
+        },
+    ],
+    "production-app": [
+        {"key": "chunk_size", "value": 2048, "override": True},
+        {"key": "max_local_cpu_size", "value": 100, "override": True},
+    ],
+}
+
+
+def get_configs_for_app(
+    app_id: str | None,
+    current_config: dict[str, Any],
+    env_variables: dict[str, str],
+) -> list[dict[str, Any]]:
+    """
+    Determine which configs to return based on app_id and current state.
+
+    This is where you would implement your custom logic, such as:
+    - Looking up configs from a database
+    - Applying rules based on environment variables
+    - A/B testing different configurations
+    """
+    # Use dict to deduplicate by key, later entries override earlier ones
+    config_map: dict[str, dict[str, Any]] = {}
+
+    # Start with default configs
+    if "default" in CONFIG_DATABASE:
+        for item in CONFIG_DATABASE["default"]:
+            config_map[item["key"]] = item
+
+    # Add app-specific configs (override defaults with same keys)
+    if app_id and app_id in CONFIG_DATABASE:
+        for item in CONFIG_DATABASE[app_id]:
+            config_map[item["key"]] = item
+
+    return list(config_map.values())
+
+
+@app.route("/config", methods=["GET", "POST"])
+def get_config():
+    """
+    Handle config requests from LMCache workers.
+
+    Expected request body:
+    {
+        "current_config": {...},
+        "env_variables": {...}
+    }
+
+    Query parameters:
+    - appId: Optional application identifier
+    """
+    try:
+        # Parse request - supports both JSON body and form data
+        data = request.get_json(silent=True)
+        if data is None:
+            # Fallback to form data or query parameters
+            data = request.form.to_dict() or request.args.to_dict()
+
+        current_config = data.get("current_config", {})
+        env_variables = data.get("env_variables", {})
+        app_id = request.args.get("appId") or data.get("appId")
+
+        logger.info(
+            "Config request received - app_id: %s, current_config keys: %s",
+            app_id,
+            list(current_config.keys()),
+        )
+
+        # Get configs for this app
+        configs = get_configs_for_app(app_id, current_config, env_variables)
+
+        response = {"configs": configs}
+
+        logger.info("Returning %d config items for app_id: %s", len(configs), app_id)
+        return jsonify(response)
+
+    except Exception as e:
+        logger.exception("Error processing config request")
+        return jsonify({"error": str(e)}), 500
+
+
+@app.route("/health", methods=["GET"])
+def health_check():
+    """Health check endpoint."""
+    return jsonify({"status": "healthy"})
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="LMCache Remote Config Server Reference Implementation"
+    )
+    parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")
+    parser.add_argument("--port", type=int, default=8088, help="Port to listen on")
+    parser.add_argument("--debug", action="store_true", help="Enable debug mode")
+
+    args = parser.parse_args()
+
+    logger.info("Starting config server on %s:%d", args.host, args.port)
+    logger.info("Available app configs: %s", list(CONFIG_DATABASE.keys()))
+
+    app.run(host=args.host, port=args.port, debug=args.debug)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/remote_config_server/example.yaml b/examples/remote_config_server/example.yaml
new file mode 100644
index 0000000..4ac23cc
--- /dev/null
+++ b/examples/remote_config_server/example.yaml
@@ -0,0 +1,15 @@
+# Example LMCache configuration with remote config server
+# See README.md for more details
+
+chunk_size: 256
+local_device: "cpu"
+local_cpu: true
+max_local_cpu_size: 10
+internal_api_server_enabled: true
+internal_api_server_port_start: 9899
+
+# Remote configuration settings
+# The remote config server URL - LMCache will fetch additional configs from here
+remote_config_url: "http://localhost:8088/config"
+# Application ID to identify this LMCache instance
+app_id: "test-app"
diff --git a/examples/runtime_plugins/README.md b/examples/runtime_plugins/README.md
new file mode 100644
index 0000000..4f35d95
--- /dev/null
+++ b/examples/runtime_plugins/README.md
@@ -0,0 +1,73 @@
+# LMCache Runtime Plugin System Documentation
+
+## Overview
+
+The LMCache runtime plugin system allows users to extend functionality by running custom scripts or programs during cache operations. Plugins can be written in any language (Python, Bash, etc.) and are managed by the `RuntimePluginLauncher` class.
+
+Based on this, we hope users in our community can contribute more runtime plugins, e.g.
+- Start metric reporter to centralized metric system.
+- Start log reporter to centralized log collect and query system.
+- Report customized process level metrics to the alert system.
+- Heartbeat to a health monitor system or a service discover system.
+- ...
+
+## Configuration
+Runtime plugins are configured through the following methods:
+
+1. **Environment Variables**:
+   - `LMCACHE_RUNTIME_PLUGIN_ROLE`: The role of the current process (e.g., `SCHEDULER`, `WORKER`)
+   - `LMCACHE_RUNTIME_PLUGIN_CONFIG`: JSON string containing the plugin configuration
+   - `LMCACHE_RUNTIME_PLUGIN_WORKER_ID`: The worker id of current process
+   - `LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT`: The total worker count of this cluster
+
+2. **Configuration File**:
+   Runtime plugins can be specified in the `lmcache.yaml` file under the `runtime_plugin_locations` field:
+   ```yaml
+   runtime_plugin_locations: ["/path/to/plugins"]
+   ```
+3. **Pass more parameters via lmcache extra_config**
+   You can Pass more parameters via specify extra_config within `lmcache.yaml`.
+
+## Plugin Naming Rules
+Runtime plugin filenames determine which roles/worker_id they run on:
+
+**Role-Specific Plugins**:
+   - Format: `<ROLE>[_<WORKER_ID>][_<DESCRIPTION>].<EXTENSION>`
+   - Examples:
+     - `scheduler_foo_plugin.py`: Runs only on `SCHEDULER` role
+     - `worker_0_test.sh`: Runs only on `WORKER` with `worker_id=0`
+     - `all_plugin.sh`: Runs on all nodes
+
+Notes:
+- Role names are case-insensitive (e.g., `worker` = `WORKER`)
+- Worker ID must be a numeric value if specified
+
+## Plugin Execution
+Runtime plugins are executed as follows:
+
+1. **Interpreter Detection**:
+   - The first line (shebang) determines the interpreter:
+     ```python
+     #!/opt/venv/bin/python
+     ```
+   - Fallback interpreters:
+     - `.py` files: `python`
+     - `.sh` files: `bash`
+
+2. **Output Capture**:
+   - Runtime plugin stdout/stderr is captured continuously
+   - Output is logged with the plugin name as prefix
+
+3. **Process Management**:
+   - Runtime plugins are launched as subprocesses
+   - All runtime plugins are terminated when the parent process exits
+
+## Example Plugins
+1. Python Plugin (`scheduler_foo_plugin.py`)
+2. Bash Plugin (`all_plugin.sh`)
+
+## Best Practices
+1. Keep runtime plugins lightweight
+2. Use descriptive names
+3. Handle errors gracefully
+4. Include shebang for portability
diff --git a/examples/runtime_plugins/all_plugin.sh b/examples/runtime_plugins/all_plugin.sh
new file mode 100644
index 0000000..f88c8be
--- /dev/null
+++ b/examples/runtime_plugins/all_plugin.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+# Example plugin for LMCache system
+# This plugin runs continuously and exits when parent process terminates
+
+# Handle termination signal
+trap "echo 'Received termination signal, exiting...'; exit 0" SIGTERM
+
+role="$LMCACHE_RUNTIME_PLUGIN_ROLE"
+worker_id="$LMCACHE_RUNTIME_PLUGIN_WORKER_ID"
+worker_count="$LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT"
+config="$LMCACHE_RUNTIME_PLUGIN_CONFIG"
+
+echo "All plugin started for role: $role, worker ID: $worker_id, worker count: $worker_count"
+echo "All plugin accept LMCache Config: $config"
+
+loop_count=0
+while true; do
+    echo "All plugin is running for ${role} ${worker_id}...(loop_count: ${loop_count})"
+    loop_count=$((loop_count + 1))
+    sleep 10
+done
\ No newline at end of file
diff --git a/examples/runtime_plugins/scheduler_foo_plugin.py b/examples/runtime_plugins/scheduler_foo_plugin.py
new file mode 100644
index 0000000..325cb3e
--- /dev/null
+++ b/examples/runtime_plugins/scheduler_foo_plugin.py
@@ -0,0 +1,46 @@
+#!/opt/venv/bin/python
+# SPDX-License-Identifier: Apache-2.0
+"""Example plugin for LMCache system
+This plugin runs continuously and exits when parent process terminates"""
+
+# Standard
+import json
+import os
+import signal
+import time
+
+# First Party
+from lmcache.integration.vllm.utils import lmcache_get_or_create_config
+from lmcache.v1.config import LMCacheEngineConfig
+
+
+# Graceful exit handler
+def handle_exit(signum, frame):
+    print("Received termination signal, exiting...")
+    exit(0)
+
+
+signal.signal(signal.SIGTERM, handle_exit)
+
+role = os.getenv("LMCACHE_RUNTIME_PLUGIN_ROLE")
+worker_id = os.getenv("LMCACHE_RUNTIME_PLUGIN_WORKER_ID")
+worker_count = os.getenv("LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT")
+config_str = os.getenv("LMCACHE_RUNTIME_PLUGIN_CONFIG")
+try:
+    config = LMCacheEngineConfig.from_json(config_str)
+except json.JSONDecodeError as e:
+    print(f"Error parsing LMCACHE_RUNTIME_PLUGIN_CONFIG: {e}")
+    config = lmcache_get_or_create_config()
+
+print(
+    f"Python plugin running with role: {role}, worker_id: {worker_id}, "
+    f"worker_count: {worker_count}"
+)
+print(f"Config: {config}")
+
+# Main loop
+loop_count = 0
+while True:
+    print(f"Scheduler plugin is running... (loop_count: {loop_count})")
+    loop_count += 1
+    time.sleep(10)
diff --git a/examples/runtime_plugins/worker_0_test.sh b/examples/runtime_plugins/worker_0_test.sh
new file mode 100644
index 0000000..779b329
--- /dev/null
+++ b/examples/runtime_plugins/worker_0_test.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+# Example plugin for LMCache system
+# This plugin runs continuously and exits when parent process terminates
+
+# Handle termination signal
+trap "echo 'Received termination signal, exiting...'; exit 0" SIGTERM
+
+role="$LMCACHE_RUNTIME_PLUGIN_ROLE"
+worker_id="$LMCACHE_RUNTIME_PLUGIN_WORKER_ID"
+worker_count="$LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT"
+config="$LMCACHE_RUNTIME_PLUGIN_CONFIG"
+
+echo "Worker plugin started for role: $role, worker ID: $worker_id, worker count: $worker_count"
+echo "Config: $config"
+
+loop_count=0
+while true; do
+    echo "Worker plugin is running for worker ${worker_id}...(loop_count: ${loop_count})"
+    loop_count=$((loop_count + 1))
+    sleep 10
+done
\ No newline at end of file
diff --git a/examples/serde/fp8/README.md b/examples/serde/fp8/README.md
new file mode 100644
index 0000000..1351f3e
--- /dev/null
+++ b/examples/serde/fp8/README.md
@@ -0,0 +1,94 @@
+# Fp8 Serde End-to-End Example
+
+This example demonstrates the per-adapter serde feature: the L2 disk adapter
+quantizes KV cache to **fp8** before writing to disk, and dequantizes back to
+the original dtype on prefetch.
+
+## What it does
+
+1. Starts an `lmcache server` with:
+   - **L1**: 20 GB CPU memory cache, LRU eviction
+   - **L2**: filesystem (disk) adapter at `/tmp/lmcache_serde_disk`
+   - **Serde**: `fp8` (`torch.float8_e4m3fn`) attached to the L2 adapter
+2. Starts vLLM connected via `LMCacheMPConnector`
+3. Sends an inference request — KV is computed, written to L1, then asynchronously
+   serialized (fp8) and stored to L2 disk
+4. Calls the lmcache HTTP API to **force-clear L1** (CPU cache)
+5. Re-sends the same request — L1 misses, L2 prefetch fires, the serialized
+   bytes are loaded from disk and **deserialized** back into KV-shaped buffers,
+   then vLLM resumes from cache
+
+## Files
+
+- `run_serde_fp8_example.sh` — full end-to-end: `lmcache server` + `vllm serve` + real inference, then clear L1 and re-infer to hit the L2 path.
+
+## Quick sanity check (no vLLM required)
+
+The pytest suite includes a filesystem-backed serde test that exercises
+the same L1 -> disk -> L1 round-trip without needing vLLM:
+
+```bash
+pytest tests/v1/distributed/serde/test_serde_fs_e2e.py -xvs
+```
+
+## Requirements
+
+- vLLM installed (`vllm serve` works)
+- `lmcache` CLI installed (`lmcache server --help` works)
+- 1 GPU (default `CUDA_VISIBLE_DEVICES=0`)
+- A GPU with fp8 support (Hopper / Ada / RTX 40+) and PyTorch built with fp8
+
+## Run
+
+```bash
+./run_serde_fp8_example.sh
+```
+
+You can override defaults via environment variables:
+
+```bash
+MODEL="meta-llama/Llama-3.1-8B-Instruct" \
+GPU_DEVICE=0 \
+L1_SIZE_GB=20 \
+LMCACHE_PORT=6555 \
+VLLM_PORT=8000 \
+./run_serde_fp8_example.sh
+```
+
+Server output is streamed to stdout. Logs are also saved under
+`/tmp/lmcache_serde_example/{lmcache,vllm}.log` (override with `TMP_DIR`).
+
+## L2 adapter config syntax
+
+The serde is attached per-adapter via a `serde` sub-dict in the `--l2-adapter`
+JSON. Each adapter independently decides whether to use serde.
+
+```json
+{
+  "type": "fs",
+  "base_path": "/tmp/lmcache_serde_disk",
+  "serde": {"type": "fp8", "fp8_dtype": "float8_e4m3fn"}
+}
+```
+
+To disable serde for an adapter, omit the `serde` field.
+
+## Adding a custom serde
+
+1. Implement `Serializer` and `Deserializer` from
+   `lmcache.v1.distributed.serde`
+2. Register a factory:
+
+   ```python
+   from lmcache.v1.distributed.serde import (
+       AsyncSerdeProcessor,
+       register_serde_factory,
+   )
+
+   def _create_my_serde(config: dict):
+       return AsyncSerdeProcessor(MySerializer(), MyDeserializer())
+
+   register_serde_factory("mine", _create_my_serde)
+   ```
+
+3. Reference it in the adapter config: `"serde": {"type": "mine", ...}`
diff --git a/examples/serde/fp8/run_serde_fp8_example.sh b/examples/serde/fp8/run_serde_fp8_example.sh
new file mode 100755
index 0000000..d112b77
--- /dev/null
+++ b/examples/serde/fp8/run_serde_fp8_example.sh
@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+#
+# End-to-end example: LMCache MP server + disk L2 adapter + fp8 serde + vLLM.
+#
+# Flow:
+#   1. Start `lmcache server` with:
+#        - L1 (CPU) cache enabled
+#        - L2 disk (fs) adapter
+#        - fp8 quantization serde on the L2 adapter
+#   2. Start vLLM connected via LMCacheMPConnector
+#   3. Send an inference request (cold path: data flows L1 -> L2 with serialize)
+#   4. Force-clear L1 (CPU) cache via the lmcache HTTP API
+#   5. Re-send the same request — L1 misses, L2 prefetch triggers deserialize
+#
+# Requirements:
+#   - vLLM installed and runnable (`vllm serve`)
+#   - lmcache CLI installed (`lmcache server --help`)
+#   - 1 GPU available
+#   - GPU + PyTorch with fp8 support (Hopper / Ada / RTX 40+ recommended)
+set -e
+set -o pipefail
+
+# Prefer the LMCache repo's uv venv if present, so `lmcache` and `vllm` on PATH
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+if [ -d "${REPO_ROOT}/.venv/bin" ]; then
+    export PATH="${REPO_ROOT}/.venv/bin:${PATH}"
+fi
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+MODEL="${MODEL:-meta-llama/Llama-3.1-8B-Instruct}"
+GPU_DEVICE="${GPU_DEVICE:-0}"
+
+LMCACHE_PORT="${LMCACHE_PORT:-6555}"        # ZMQ port (vLLM <-> lmcache)
+LMCACHE_HTTP_PORT="${LMCACHE_HTTP_PORT:-8080}"  # HTTP port (clear-cache, status)
+VLLM_PORT="${VLLM_PORT:-8000}"
+
+L1_SIZE_GB="${L1_SIZE_GB:-20}"              # CPU cache size
+
+TMP_DIR="${TMP_DIR:-/tmp/lmcache_serde_example}"
+L2_DISK_PATH="${L2_DISK_PATH:-${TMP_DIR}/disk}"
+mkdir -p "$TMP_DIR"
+mkdir -p "$L2_DISK_PATH"
+
+# L2 adapter JSON: disk (fs) backend with fp8 serde enabled
+L2_ADAPTER_JSON=$(cat <<EOF
+{
+  "type": "fs",
+  "base_path": "${L2_DISK_PATH}",
+  "serde": {"type": "fp8", "fp8_dtype": "float8_e4m3fn"}
+}
+EOF
+)
+
+# ---------------------------------------------------------------------------
+# Cleanup helpers
+# ---------------------------------------------------------------------------
+LMCACHE_PID=""
+VLLM_PID=""
+cleanup() {
+    echo "--- Cleaning up ---"
+    [ -n "$VLLM_PID" ] && kill "$VLLM_PID" 2>/dev/null || true
+    [ -n "$LMCACHE_PID" ] && kill "$LMCACHE_PID" 2>/dev/null || true
+    wait 2>/dev/null || true
+}
+trap cleanup EXIT
+
+wait_for_url() {
+    local url="$1"
+    local timeout="${2:-300}"
+    local elapsed=0
+    while ! curl -sf "$url" > /dev/null 2>&1; do
+        sleep 2
+        elapsed=$((elapsed + 2))
+        if [ "$elapsed" -ge "$timeout" ]; then
+            echo "Timeout waiting for $url"
+            return 1
+        fi
+    done
+}
+
+# ---------------------------------------------------------------------------
+# Step 1: Launch lmcache MP server (CPU L1 + disk L2 with fp8 serde)
+# ---------------------------------------------------------------------------
+echo "============================================"
+echo "=== Step 1: Starting LMCache MP server ==="
+echo "============================================"
+echo "L1 (CPU): ${L1_SIZE_GB} GB"
+echo "L2 (disk): ${L2_DISK_PATH}"
+echo "Serde: fp8 (float8_e4m3fn)"
+
+lmcache server \
+    --l1-size-gb "$L1_SIZE_GB" \
+    --eviction-policy LRU \
+    --l2-store-policy default \
+    --l2-prefetch-policy default \
+    --l2-adapter "$L2_ADAPTER_JSON" \
+    --port "$LMCACHE_PORT" \
+    --http-port "$LMCACHE_HTTP_PORT" \
+    2>&1 | tee "$TMP_DIR/lmcache.log" &
+LMCACHE_PID=$!
+echo "lmcache server PID=$LMCACHE_PID"
+
+echo "Waiting for lmcache HTTP health..."
+wait_for_url "http://localhost:${LMCACHE_HTTP_PORT}/healthcheck" 60 || {
+    echo "lmcache failed to start. Last 50 lines of log:"
+    tail -50 "$TMP_DIR/lmcache.log" || true
+    exit 1
+}
+echo "lmcache server ready."
+
+# ---------------------------------------------------------------------------
+# Step 2: Launch vLLM with LMCacheMPConnector
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "=== Step 2: Starting vLLM ==="
+echo "============================================"
+echo "Model: $MODEL"
+
+KV_TRANSFER_CONFIG=$(cat <<EOF
+{
+  "kv_connector": "LMCacheMPConnector",
+  "kv_role": "kv_both",
+  "kv_load_failure_policy": "recompute",
+  "kv_connector_extra_config": {
+    "lmcache.mp.port": ${LMCACHE_PORT},
+    "lmcache.mp.mq_timeout": 10
+  }
+}
+EOF
+)
+
+env -u VLLM_PORT \
+    CUDA_VISIBLE_DEVICES="${GPU_DEVICE}" \
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 \
+    PYTHONHASHSEED=0 \
+vllm serve "$MODEL" \
+    --port "$VLLM_PORT" \
+    --no-enable-prefix-caching \
+    --enforce-eager \
+    --gpu-memory-utilization "${GPU_MEM_UTIL:-0.6}" \
+    --kv-transfer-config "$KV_TRANSFER_CONFIG" \
+    2>&1 | tee "$TMP_DIR/vllm.log" &
+VLLM_PID=$!
+echo "vLLM PID=$VLLM_PID"
+
+echo "Waiting for vLLM /v1/models (this can take a few minutes)..."
+wait_for_url "http://localhost:${VLLM_PORT}/v1/models" 600 || {
+    echo "vLLM failed to start. Last 50 lines:"
+    tail -50 "$TMP_DIR/vllm.log" || true
+    exit 1
+}
+echo "vLLM ready."
+
+# ---------------------------------------------------------------------------
+# Step 3: First inference — cold path (L1 -> L2 store with fp8 serialize)
+# ---------------------------------------------------------------------------
+# Prompt must be long enough to fill at least one 256-token LMCache chunk
+# so KV actually gets stored to L2. We generate a ~1000+ token prompt.
+PROMPT=""
+for i in $(seq 1 8); do
+    PROMPT+="The history and significance of the Roman empire spans more than a thousand years and profoundly shaped Western civilization. "
+    PROMPT+="Its legal, architectural, linguistic, and political legacies persist to this day, influencing modern governments, languages, art, engineering, and law. "
+    PROMPT+="The empire's trajectory from the founding of Rome through the Republic, the transition to the Principate under Augustus, the Pax Romana, the crisis of the third century, "
+    PROMPT+="the Dominate under Diocletian, the adoption of Christianity under Constantine, the splitting into Western and Eastern halves, and the eventual collapse of the West "
+    PROMPT+="is one of history's great narratives. Key figures include Julius Caesar, Augustus, Marcus Aurelius, Diocletian, Constantine, Justinian, and many others. "
+done
+PROMPT+="Tell me a long, detailed story about the rise, peak, and eventual fall of Rome, naming important figures and events."
+
+echo ""
+echo "============================================"
+echo "=== Step 3: First inference (cold) ==="
+echo "============================================"
+echo "Expected: KV is computed, written to L1, then async-stored to L2 disk via fp8 serialize"
+
+curl -s -X POST "http://localhost:${VLLM_PORT}/v1/completions" \
+    -H "Content-Type: application/json" \
+    -d "{
+        \"model\": \"$MODEL\",
+        \"prompt\": \"$PROMPT\",
+        \"max_tokens\": 32,
+        \"temperature\": 0
+    }" | python3 -c "import sys, json; d=json.load(sys.stdin); print('Response:', d['choices'][0]['text'][:200], '...')"
+
+# Give the store controller a couple seconds to flush to disk
+echo "Waiting 5s for L2 store to flush..."
+sleep 5
+
+# Sanity check: disk path should now contain some files
+echo "Disk L2 contents:"
+ls -lh "$L2_DISK_PATH" | head -10 || true
+
+# ---------------------------------------------------------------------------
+# Step 4: Clear L1 (CPU) cache
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "=== Step 4: Force-clearing L1 (CPU) cache ==="
+echo "============================================"
+curl -s -X POST "http://localhost:${LMCACHE_HTTP_PORT}/cache/clear" | python3 -m json.tool
+echo "L1 cleared. Next request will miss L1 and trigger L2 prefetch."
+
+# ---------------------------------------------------------------------------
+# Step 5: Re-run the same request — triggers L2 prefetch + fp8 deserialize
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "=== Step 5: Second inference (L1 miss -> L2 prefetch) ==="
+echo "============================================"
+echo "Expected: L1 miss, L2 lookup hit, prefetch loads serialized bytes,"
+echo "          fp8 deserialize back into KV, vLLM resumes from cache."
+
+curl -s -X POST "http://localhost:${VLLM_PORT}/v1/completions" \
+    -H "Content-Type: application/json" \
+    -d "{
+        \"model\": \"$MODEL\",
+        \"prompt\": \"$PROMPT\",
+        \"max_tokens\": 32,
+        \"temperature\": 0
+    }" | python3 -c "import sys, json; d=json.load(sys.stdin); print('Response:', d['choices'][0]['text'][:200], '...')"
+
+# ---------------------------------------------------------------------------
+# Step 6: Show metrics / status
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "=== Step 6: LMCache status ==="
+echo "============================================"
+curl -s "http://localhost:${LMCACHE_HTTP_PORT}/status" \
+    | python3 -m json.tool | head -80
+
+echo ""
+echo "============================================"
+echo "Done. Logs are under: $TMP_DIR"
+echo "============================================"
diff --git a/examples/serde/turboquant/README.md b/examples/serde/turboquant/README.md
new file mode 100644
index 0000000..418a009
--- /dev/null
+++ b/examples/serde/turboquant/README.md
@@ -0,0 +1,99 @@
+# TurboQuant Serde End-to-End Example
+
+This example demonstrates the per-adapter serde feature: the L2 disk adapter
+quantizes KV cache to **TurboQuant** before writing to disk, and dequantizes back to
+the original dtype on prefetch.
+
+## What it does
+
+1. Starts an `lmcache server` with:
+   - **L1**: 20 GB CPU memory cache, LRU eviction
+   - **L2**: filesystem (disk) adapter at `/tmp/lmcache_turboquant_serde_disk`
+   - **Serde**: `TurboQuant` (`TurboQuant preset`) attached to the L2 adapter
+2. Starts vLLM connected via `LMCacheMPConnector`
+3. Sends an inference request — KV is computed, written to L1, then asynchronously
+   serialized (TurboQuant) and stored to L2 disk
+4. Calls the lmcache HTTP API to **force-clear L1** (CPU cache)
+5. Re-sends the same request — L1 misses, L2 prefetch fires, the serialized
+   bytes are loaded from disk and **deserialized** back into KV-shaped buffers,
+   then vLLM resumes from cache
+
+## Files
+
+- `run_serde_turboquant_example.sh` — full end-to-end: `lmcache server` + `vllm serve` + real inference, then clear L1 and re-infer to hit the L2 path.
+
+## Quick sanity check (no vLLM required)
+
+The pytest suite includes TurboQuant serde tests that exercise direct CUDA, MockL2, and filesystem-backed L2 round-trips without needing vLLM:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 python -m pytest tests/v1/distributed/serde/test_turboquant.py -q -s
+```
+
+## Requirements
+
+- vLLM installed (`vllm serve` works)
+- `lmcache` CLI installed (`lmcache server --help` works)
+- 1 GPU (default `CUDA_VISIBLE_DEVICES=0`)
+- PyTorch + Triton CUDA environment
+
+## Run
+
+```bash
+./run_serde_turboquant_example.sh
+```
+
+You can override defaults via environment variables:
+
+```bash
+MODEL="meta-llama/Llama-3.1-8B-Instruct" \
+GPU_DEVICE=0 \
+L1_SIZE_GB=20 \
+LMCACHE_PORT=6555 \
+VLLM_PORT=8000 \
+TQ_PRESET=turboquant_k8v4 \
+TQ_BLOCK_SIZE=16 \
+./run_serde_turboquant_example.sh
+```
+
+Server output is streamed to stdout. Logs are also saved under
+`/tmp/lmcache_turboquant_serde_example/{lmcache,vllm}.log` (override with `TMP_DIR`).
+
+## L2 adapter config syntax
+
+The serde is attached per-adapter via a `serde` sub-dict in the `--l2-adapter`
+JSON. Each adapter independently decides whether to use serde.
+
+```json
+{
+  "type": "fs",
+  "base_path": "/tmp/lmcache_turboquant_serde_disk",
+  "serde": {
+    "type": "turboquant",
+    "preset": "turboquant_k8v4",
+    "block_size": 16
+  }
+}
+```
+
+To disable serde for an adapter, omit the `serde` field.
+
+## Adding a custom serde
+
+1. Implement `Serializer` and `Deserializer` from
+   `lmcache.v1.distributed.serde`
+2. Register a factory:
+
+   ```python
+   from lmcache.v1.distributed.serde import (
+       AsyncSerdeProcessor,
+       register_serde_factory,
+   )
+
+   def _create_my_serde(config: dict):
+       return AsyncSerdeProcessor(MySerializer(), MyDeserializer())
+
+   register_serde_factory("mine", _create_my_serde)
+   ```
+
+3. Reference it in the adapter config: `"serde": {"type": "mine", ...}`
diff --git a/examples/serde/turboquant/bench_serde_baselines.py b/examples/serde/turboquant/bench_serde_baselines.py
new file mode 100644
index 0000000..8aedd60
--- /dev/null
+++ b/examples/serde/turboquant/bench_serde_baselines.py
@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the LMCache project
+
+"""Microbenchmark fp8 and TurboQuant serde backends on synthetic KV tensors."""
+
+# Standard
+from dataclasses import dataclass
+from typing import Any
+import argparse
+import json
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.fp8 import (
+    Fp8QuantizationDeserializer,
+    Fp8QuantizationSerializer,
+)
+from lmcache.v1.distributed.serde.turboquant import (
+    TurboQuantDeserializer,
+    TurboQuantSerdeConfig,
+    TurboQuantSerializer,
+)
+
+
+@dataclass
+class _FakeMemoryObj:
+    tensor: torch.Tensor
+
+
+def sync() -> None:
+    if torch.cuda.is_available():
+        torch.cuda.synchronize()
+
+
+def corrcoef(a: torch.Tensor, b: torch.Tensor) -> float:
+    a = a.float().flatten()
+    b = b.float().flatten()
+    a = a - a.mean()
+    b = b - b.mean()
+    denom = torch.linalg.norm(a) * torch.linalg.norm(b)
+    if denom.item() == 0:
+        return float("nan")
+    return ((a @ b) / denom).item()
+
+
+def make_serde(
+    name: str, preset: str | None, fp8_dtype: str, head_dim: int, block_size: int
+):
+    if name == "fp8":
+        dtype = getattr(torch, fp8_dtype)
+        return (
+            Fp8QuantizationSerializer(dtype),
+            Fp8QuantizationDeserializer(dtype),
+        )
+
+    if name == "turboquant":
+        assert preset is not None
+        cfg = TurboQuantSerdeConfig(
+            preset=preset,
+            head_dim=head_dim,
+            block_size=block_size,
+        )
+        return TurboQuantSerializer(cfg), TurboQuantDeserializer(cfg)
+
+    raise ValueError(f"unknown serde: {name}")
+
+
+def benchmark_one(
+    serde_name: str,
+    preset: str | None,
+    shape: torch.Size,
+    dtype: torch.dtype,
+    device: torch.device,
+    warmup: int,
+    iters: int,
+    head_dim: int,
+    block_size: int,
+    fp8_dtype: str,
+) -> dict[str, Any]:
+    torch.manual_seed(2026)
+    original = torch.randn(shape, dtype=dtype, device=device)
+
+    serializer, deserializer = make_serde(
+        serde_name,
+        preset,
+        fp8_dtype,
+        head_dim,
+        block_size,
+    )
+
+    layout = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+    n_bytes = serializer.estimate_serialized_size(layout)
+
+    compressed = torch.empty(n_bytes, dtype=torch.uint8, device=device)
+    recovered = torch.empty_like(original)
+
+    src = _FakeMemoryObj(original)
+    enc = _FakeMemoryObj(compressed)
+    dec = _FakeMemoryObj(recovered)
+
+    for _ in range(warmup):
+        written = serializer.serialize(src, enc)
+        if written != n_bytes:
+            raise RuntimeError(f"written={written}, expected={n_bytes}")
+        deserializer.deserialize(enc, dec)
+    sync()
+
+    encode_times = []
+    decode_times = []
+
+    for _ in range(iters):
+        sync()
+        t0 = time.perf_counter()
+        written = serializer.serialize(src, enc)
+        sync()
+        t1 = time.perf_counter()
+
+        if written != n_bytes:
+            raise RuntimeError(f"written={written}, expected={n_bytes}")
+
+        deserializer.deserialize(enc, dec)
+        sync()
+        t2 = time.perf_counter()
+
+        encode_times.append((t1 - t0) * 1000)
+        decode_times.append((t2 - t1) * 1000)
+
+    raw_bytes = original.numel() * original.element_size()
+    orig_f = original.float()
+    rec_f = recovered.float()
+
+    return {
+        "serde": serde_name,
+        "preset": preset or fp8_dtype,
+        "shape": "x".join(map(str, shape)),
+        "dtype": str(dtype).replace("torch.", ""),
+        "raw_MB": raw_bytes / 1024 / 1024,
+        "serialized_MB": n_bytes / 1024 / 1024,
+        "compression_ratio": raw_bytes / n_bytes,
+        "encode_ms": sum(encode_times) / len(encode_times),
+        "decode_ms": sum(decode_times) / len(decode_times),
+        "corr": corrcoef(orig_f, rec_f),
+        "mean_abs_err": torch.mean(torch.abs(orig_f - rec_f)).item(),
+        "max_abs_err": torch.max(torch.abs(orig_f - rec_f)).item(),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument(
+        "--dtype", default="bfloat16", choices=["float16", "bfloat16", "float32"]
+    )
+    parser.add_argument("--layers", type=int, default=24)
+    parser.add_argument("--blocks", type=int, default=4096)
+    parser.add_argument("--block-size", type=int, default=16)
+    parser.add_argument("--kv-heads", type=int, default=2)
+    parser.add_argument("--head-dim", type=int, default=64)
+    parser.add_argument("--warmup", type=int, default=3)
+    parser.add_argument("--iters", type=int, default=10)
+    parser.add_argument("--fp8-dtype", default="float8_e4m3fn")
+    parser.add_argument(
+        "--turboquant-presets",
+        nargs="+",
+        default=[
+            "turboquant_k8v4",
+            "turboquant_4bit_nc",
+            "turboquant_k3v4_nc",
+            "turboquant_3bit_nc",
+        ],
+    )
+    args = parser.parse_args()
+
+    if args.device == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is not available")
+
+    dtype = {
+        "float16": torch.float16,
+        "bfloat16": torch.bfloat16,
+        "float32": torch.float32,
+    }[args.dtype]
+
+    device = torch.device(args.device)
+    num_tokens = args.blocks * args.block_size
+    hidden_dim = args.kv_heads * args.head_dim
+    shape = torch.Size([2, args.layers, num_tokens, hidden_dim])
+
+    configs: list[tuple[str, str | None]] = [("fp8", None)]
+    configs += [("turboquant", p) for p in args.turboquant_presets]
+
+    rows = [
+        benchmark_one(
+            serde_name=serde_name,
+            preset=preset,
+            shape=shape,
+            dtype=dtype,
+            device=device,
+            warmup=args.warmup,
+            iters=args.iters,
+            head_dim=args.head_dim,
+            block_size=args.block_size,
+            fp8_dtype=args.fp8_dtype,
+        )
+        for serde_name, preset in configs
+    ]
+
+    print(json.dumps(rows, indent=2))
+    print()
+
+    headers = [
+        "serde",
+        "preset",
+        "raw_MB",
+        "serialized_MB",
+        "compression_ratio",
+        "encode_ms",
+        "decode_ms",
+        "corr",
+        "mean_abs_err",
+        "max_abs_err",
+    ]
+    print(" | ".join(headers))
+    print(" | ".join(["---"] * len(headers)))
+    for r in rows:
+        print(
+            " | ".join(
+                [
+                    str(r["serde"]),
+                    str(r["preset"]),
+                    f"{r['raw_MB']:.2f}",
+                    f"{r['serialized_MB']:.2f}",
+                    f"{r['compression_ratio']:.2f}",
+                    f"{r['encode_ms']:.3f}",
+                    f"{r['decode_ms']:.3f}",
+                    f"{r['corr']:.6f}",
+                    f"{r['mean_abs_err']:.6f}",
+                    f"{r['max_abs_err']:.6f}",
+                ]
+            )
+        )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/serde/turboquant/bench_turboquant.py b/examples/serde/turboquant/bench_turboquant.py
new file mode 100644
index 0000000..c3db3af
--- /dev/null
+++ b/examples/serde/turboquant/bench_turboquant.py
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import cast
+import argparse
+import json
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.turboquant import (
+    TurboQuantDeserializer,
+    TurboQuantSerdeConfig,
+    TurboQuantSerializer,
+)
+from lmcache.v1.memory_management import MemoryObj
+
+
+@dataclass
+class _FakeMemoryObj:
+    tensor: torch.Tensor
+
+
+def sync() -> None:
+    if torch.cuda.is_available():
+        torch.cuda.synchronize()
+
+
+def corrcoef(a: torch.Tensor, b: torch.Tensor) -> float:
+    a = a.float().flatten()
+    b = b.float().flatten()
+    a = a - a.mean()
+    b = b - b.mean()
+    denom = torch.linalg.norm(a) * torch.linalg.norm(b)
+    if denom.item() == 0:
+        return float("nan")
+    return ((a @ b) / denom).item()
+
+
+def benchmark_one(
+    preset: str,
+    shape: torch.Size,
+    dtype: torch.dtype,
+    device: torch.device,
+    warmup: int,
+    iters: int,
+    head_dim: int,
+    block_size: int,
+) -> dict[str, float | str]:
+    cfg = TurboQuantSerdeConfig(
+        preset=preset,
+        head_dim=head_dim,
+        block_size=block_size,
+    )
+
+    torch.manual_seed(2026)
+    original = torch.randn(shape, dtype=dtype, device=device)
+
+    serializer = TurboQuantSerializer(cfg)
+    deserializer = TurboQuantDeserializer(cfg)
+
+    layout = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+    n_bytes = serializer.estimate_serialized_size(layout)
+
+    compressed = torch.empty(n_bytes, dtype=torch.uint8, device=device)
+    recovered = torch.empty_like(original)
+
+    src = _FakeMemoryObj(original)
+    enc = _FakeMemoryObj(compressed)
+    dec = _FakeMemoryObj(recovered)
+
+    for _ in range(warmup):
+        written = serializer.serialize(cast(MemoryObj, src), cast(MemoryObj, enc))
+        if written != n_bytes:
+            raise RuntimeError(f"written={written}, expected={n_bytes}")
+        deserializer.deserialize(cast(MemoryObj, enc), cast(MemoryObj, dec))
+    sync()
+
+    encode_times = []
+    decode_times = []
+
+    for _ in range(iters):
+        sync()
+        t0 = time.perf_counter()
+        written = serializer.serialize(cast(MemoryObj, src), cast(MemoryObj, enc))
+        sync()
+        t1 = time.perf_counter()
+
+        if written != n_bytes:
+            raise RuntimeError(f"written={written}, expected={n_bytes}")
+
+        deserializer.deserialize(cast(MemoryObj, enc), cast(MemoryObj, dec))
+        sync()
+        t2 = time.perf_counter()
+
+        encode_times.append((t1 - t0) * 1000)
+        decode_times.append((t2 - t1) * 1000)
+
+    raw_bytes = original.numel() * original.element_size()
+
+    orig_f = original.float()
+    rec_f = recovered.float()
+
+    return {
+        "preset": preset,
+        "shape": "x".join(map(str, shape)),
+        "dtype": str(dtype).replace("torch.", ""),
+        "raw_MB": raw_bytes / 1024 / 1024,
+        "compressed_MB": n_bytes / 1024 / 1024,
+        "compression_ratio": raw_bytes / n_bytes,
+        "encode_ms": sum(encode_times) / len(encode_times),
+        "decode_ms": sum(decode_times) / len(decode_times),
+        "corr": corrcoef(orig_f, rec_f),
+        "mean_abs_err": torch.mean(torch.abs(orig_f - rec_f)).item(),
+        "max_abs_err": torch.max(torch.abs(orig_f - rec_f)).item(),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument(
+        "--dtype", default="bfloat16", choices=["float16", "bfloat16", "float32"]
+    )
+    parser.add_argument("--layers", type=int, default=24)
+    parser.add_argument("--blocks", type=int, default=4096)
+    parser.add_argument("--block-size", type=int, default=16)
+    parser.add_argument("--kv-heads", type=int, default=2)
+    parser.add_argument("--head-dim", type=int, default=64)
+    parser.add_argument("--warmup", type=int, default=3)
+    parser.add_argument("--iters", type=int, default=10)
+    parser.add_argument(
+        "--presets",
+        nargs="+",
+        default=[
+            "turboquant_k8v4",
+            "turboquant_4bit_nc",
+            "turboquant_k3v4_nc",
+            "turboquant_3bit_nc",
+        ],
+    )
+    args = parser.parse_args()
+
+    if args.device == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA is not available")
+
+    dtype = {
+        "float16": torch.float16,
+        "bfloat16": torch.bfloat16,
+        "float32": torch.float32,
+    }[args.dtype]
+
+    device = torch.device(args.device)
+    num_tokens = args.blocks * args.block_size
+    hidden_dim = args.kv_heads * args.head_dim
+
+    # Direct serde layout used by tests:
+    # [2, num_layers, num_tokens, hidden_dim]
+    shape = torch.Size([2, args.layers, num_tokens, hidden_dim])
+
+    rows = [
+        benchmark_one(
+            preset=preset,
+            shape=shape,
+            dtype=dtype,
+            device=device,
+            warmup=args.warmup,
+            iters=args.iters,
+            head_dim=args.head_dim,
+            block_size=args.block_size,
+        )
+        for preset in args.presets
+    ]
+
+    print(json.dumps(rows, indent=2))
+    print()
+
+    headers = [
+        "preset",
+        "raw_MB",
+        "compressed_MB",
+        "compression_ratio",
+        "encode_ms",
+        "decode_ms",
+        "corr",
+        "mean_abs_err",
+        "max_abs_err",
+    ]
+    print(" | ".join(headers))
+    print(" | ".join(["---"] * len(headers)))
+    for r in rows:
+        print(
+            " | ".join(
+                [
+                    str(r["preset"]),
+                    f"{r['raw_MB']:.2f}",
+                    f"{r['compressed_MB']:.2f}",
+                    f"{r['compression_ratio']:.2f}",
+                    f"{r['encode_ms']:.3f}",
+                    f"{r['decode_ms']:.3f}",
+                    f"{r['corr']:.6f}",
+                    f"{r['mean_abs_err']:.6f}",
+                    f"{r['max_abs_err']:.6f}",
+                ]
+            )
+        )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/sgl_integration/README.md b/examples/sgl_integration/README.md
new file mode 100644
index 0000000..6e276b8
--- /dev/null
+++ b/examples/sgl_integration/README.md
@@ -0,0 +1,35 @@
+# SGLang & LMCache Integration
+
+This example shows how to use SGLang & LMCache Integration.
+
+## Install
+```bash
+pip install --upgrade pip
+pip install sglang lmcache
+```
+
+## Run
+
+LMCache's MP (multi-process) connector is the default. SGLang dials a
+standalone `lmcache server` daemon over ZMQ at the host/port from the YAML.
+
+Create `lmcache_config.yaml` with:
+```yaml
+# MP mode: SGLang dials the standalone `lmcache server` at this host/port.
+mp_host: 127.0.0.1
+mp_port: 5556
+```
+
+Terminal 1 — start the LMCache daemon (host/port must match
+`mp_host` / `mp_port` in `lmcache_config.yaml`):
+```bash
+lmcache server --host 127.0.0.1 --port 5556 --l1-size-gb 4 --eviction-policy LRU
+```
+
+Terminal 2 — start SGLang with LMCache enabled:
+```bash
+python -m sglang.launch_server --model-path Qwen/Qwen2.5-14B-Instruct --port 30000 --tp 2 --page-size 32 --enable-lmcache --lmcache-config-file lmcache_config.yaml
+```
+
+If you hope to run the benchmark, please refer to `https://github.com/sgl-project/sglang/tree/main/benchmark/hicache`
+
diff --git a/examples/token_dropping/token_dropping.ipynb b/examples/token_dropping/token_dropping.ipynb
new file mode 100644
index 0000000..d28d14b
--- /dev/null
+++ b/examples/token_dropping/token_dropping.ipynb
@@ -0,0 +1,595 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "211cffab",
+   "metadata": {},
+   "source": [
+    "# Token Dropping Example\n",
+    "---\n",
+    "\n",
+    "Long prompts create large KV caches that eat up GPU memory and limit how many \n",
+    "requests fit in a batch, and a smaller batch means lower decode throughput. \n",
+    "Token dropping shrinks each request's KV cache (in this example by half), so more\n",
+    "requests fits in a batch. This notebook shows improvement in decode \n",
+    "throughput by 1.5-1.7x by using LMCache's SDK API that enables ML engineers get\n",
+    "a requests' KV, do optimizations such as token dropping, and put it back to use\n",
+    "during LLM serving.\n",
+    "\n",
+    "Requirements:\n",
+    "* This experiment requires a GPU. To demonstrate how token dropping increases \n",
+    "  the decoding batch size, adjust the GPU memory utilization together with the \n",
+    "  number of requests. This example uses one RTX 6000 PRO.\n",
+    "* This example uses shared memory for data transfer between LMCache server and\n",
+    "  the SDK. If shared memory is unavailable, the SDK automatically falls back to pickle."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1cd06b97",
+   "metadata": {},
+   "source": [
+    "## Setup vLLM and LMCache server\n",
+    "Follow below instructions (1-4), then proceed to below Python cell.\n",
+    "\n",
+    "**1. Start LMCache server first**\n",
+    "\n",
+    "To use shared memory, specify the `--shm-name` and `--no-l1-use-lazy`\n",
+    "\n",
+    "```sh\n",
+    "lmcache server \\\n",
+    "    --l1-size-gb 150 \\\n",
+    "    --eviction-policy LRU \\\n",
+    "    --chunk-size 256 \\\n",
+    "    --port 6555 \\\n",
+    "    --http-port 8080 \\\n",
+    "    --shm-name lmcache_kvcache_sdk_e2e \\\n",
+    "    --no-l1-use-lazy\n",
+    "```\n",
+    "\n",
+    "**2. Wait until LMCache server is ready**\n",
+    "\n",
+    "```sh\n",
+    "curl -sf http://localhost:8080/healthcheck && echo \" LMCache ready\"\n",
+    "```\n",
+    "\n",
+    "**3. Start vLLM once LMCache server is ready**\n",
+    "\n",
+    "We pass --no-enable-prefix-caching to disable vLLM's built-in prefix caching. \n",
+    "This ensures the prefilled KV cache is always served from LMCache rather than \n",
+    "vLLM, so the decoding throughput improvement can be attributed entirely to the \n",
+    "tokens dropped through LMCache.\n",
+    "\n",
+    "```sh\n",
+    "vllm serve Qwen/Qwen3-8B \\\n",
+    "    --port 8000 \\\n",
+    "    --served-model-name Qwen/Qwen3-8B \\\n",
+    "    --no-enable-prefix-caching \\\n",
+    "    --enforce-eager \\\n",
+    "    --gpu-memory-utilization 0.65 \\\n",
+    "    --kv-transfer-config '{\"kv_connector\":\"LMCacheMPConnector\",\"kv_role\":\"kv_both\",\"kv_connector_extra_config\":{\"lmcache.mp.port\":6555}}' \\\n",
+    "    --trust-remote-code \\\n",
+    "    --return-tokens-as-token-ids\n",
+    "```\n",
+    "\n",
+    "**4. Wait until vLLM is ready**\n",
+    "\n",
+    "```sh\n",
+    "curl -sf http://localhost:8000/v1/models && echo \" vLLM ready\"\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c2d81202",
+   "metadata": {},
+   "source": [
+    "## Run E2E KV Edit Example"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "aa87a653",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/home/rani/LMCache/.venv/lib/python3.12/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+      "  from .autonotebook import tqdm as notebook_tqdm\n",
+      "\u001b[32;20m[2026-07-04 06:19:57,388] LMCache INFO:\u001b[0m  torch_dev=<module 'torch.cuda' from '/home/rani/LMCache/.venv/lib/python3.12/site-packages/torch/cuda/__init__.py'>, torch_device_type=cuda \u001b[3m(__init__.py:63:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:57,485] LMCache INFO:\u001b[0m CudaPinMemoryBackend: using torch cudart \u001b[3m(pin_memory.py:89:lmcache.v1.platform.cuda.pin_memory)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:57,873] LMCache INFO:\u001b[0m Skipping backend lmcache.v1.platform.musa.ops: predicate returned False \u001b[3m(__init__.py:114:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:57,874] LMCache INFO:\u001b[0m Skipping backend lmcache.xpu_ops: predicate returned False \u001b[3m(__init__.py:114:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:57,876] LMCache INFO:\u001b[0m Using backend: lmcache.c_ops \u001b[3m(__init__.py:132:lmcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:57,929] LMCache INFO:\u001b[0m multi_layer_block_kv_transfer mode: ptr \u001b[3m(base.py:94:lmcache.v1.multiprocess.transfer_context.base)\u001b[0m\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      " _     __  __    ____           _          \n",
+      "| |   |  \\/  |  / ___|__ _  ___| |__   ___      LMCache v0.4.8rc5.dev14 (geb5dfeb9)\n",
+      "| |   | |\\/| | | |   / _` |/ __| '_ \\ / _ \\     Website:  https://lmcache.ai/\n",
+      "| |___| |  | | | |__| (_| | (__| | | |  __/     Recipes:  https://docs.lmcache.ai/recipes\n",
+      "|_____|_|  |_|  \\____\\__,_|\\___|_| |_|\\___|     LinkedIn: https://www.linkedin.com/company/lmcache-lab\n",
+      "Set LMCACHE_DISABLE_BANNER=1 to hide this banner.\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "# SPDX-License-Identifier: Apache-2.0\n",
+    "\"\"\"End-to-end KV cache remapping driver for the SDK example.\"\"\"\n",
+    "\n",
+    "# Standard\n",
+    "from datasets import load_dataset\n",
+    "from matplotlib import pyplot as plt\n",
+    "import sys\n",
+    "from transformers import AutoTokenizer, AutoConfig\n",
+    "\n",
+    "# Third Party\n",
+    "import torch\n",
+    "\n",
+    "# First Party\n",
+    "from lmcache.logging import init_logger\n",
+    "import lmcache.sdk.kvcache as lmc_sdk\n",
+    "import lmcache.sdk.stream as lmc_stream\n",
+    "import lmcache.sdk.batch as lmc_batch\n",
+    "from lmcache.banner import print_banner_once\n",
+    "from utils import rerotate_k_cache, make_post_completion\n",
+    "\n",
+    "print_banner_once(sys.stdout)\n",
+    "logger = init_logger(__name__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5342c6c6",
+   "metadata": {},
+   "source": [
+    "## Setting up hyperparameters"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "8f1065b0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_name = \"Qwen/Qwen3-8B\"\n",
+    "vllm_url = \"http://localhost:8000\"\n",
+    "lmcache_url = \"http://localhost:8081\"\n",
+    "lmcache_mq_url = \"tcp://localhost:6555\"\n",
+    "chunk_size = 256\n",
+    "max_tokens = 5120\n",
+    "timeout = 60  # timeout for context retrieval (seconds)\n",
+    "trust_remote_code = True"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "34eb19b4",
+   "metadata": {},
+   "source": [
+    "## Configuring the model and LMCache endpoint"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "eac8beea",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "\u001b[32;20m[2026-07-04 06:19:59,379] LMCache INFO:\u001b[0m Initialized LMCacheKVCacheContext with instance_id=3193593, model_name=Qwen/Qwen3-8B, chunk_size=256, shm_name=lmcache_l1_pool_lmcache_kvcache_sdk_e2e \u001b[3m(kvcache.py:114:lmcache.sdk.kvcache)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:59,381] LMCache INFO:\u001b[0m Creating transfer context (device_type=cpu, mode=auto) \u001b[3m(worker_transfer.py:551:lmcache.v1.multiprocess.transfer_context.worker_transfer)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:59,382] LMCache INFO:\u001b[0m Engine KV Format: EngineKVFormat.NL_X_NB_TWO_NH_BS_HS NL x [NB, 2, NH, BS, HS] \u001b[3m(detection.py:44:lmcache.v1.gpu_connector.kv_format.detection)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:19:59,383] LMCache INFO:\u001b[0m Creating EngineDrivenContextShm (shm_name=lmcache_l1_pool_lmcache_kvcache_sdk_e2e, pool_size=161061273600) \u001b[3m(base.py:235:lmcache.v1.multiprocess.transfer_context.base)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:20:24,553] LMCache INFO:\u001b[0m SHM pinned=True for shm_name=lmcache_l1_pool_lmcache_kvcache_sdk_e2e \u001b[3m(shm.py:116:lmcache.v1.multiprocess.transfer_context.shm)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:20:24,557] LMCache INFO:\u001b[0m Worker non-GPU transfer context registered (instance_id=3193593, mode=SHM) \u001b[3m(worker_transfer.py:420:lmcache.v1.multiprocess.transfer_context.worker_transfer)\u001b[0m\n"
+     ]
+    }
+   ],
+   "source": [
+    "tokenizer = AutoTokenizer.from_pretrained(\n",
+    "    model_name, trust_remote_code=trust_remote_code\n",
+    ")\n",
+    "config = AutoConfig.from_pretrained(model_name, trust_remote_code=trust_remote_code)\n",
+    "head_size = getattr(\n",
+    "    config, \"head_dim\", config.hidden_size // config.num_attention_heads\n",
+    ")\n",
+    "work_device = torch.device(\"cpu\")\n",
+    "post_completion = make_post_completion(vllm_url, model_name, timeout)\n",
+    "ctx = lmc_sdk.connect(\n",
+    "    url=lmcache_mq_url,\n",
+    "    http_url=lmcache_url,\n",
+    "    model_name=model_name,\n",
+    "    timeout=timeout,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c2aaffa7",
+   "metadata": {},
+   "source": [
+    "## Constructing Prompt"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "030145fc",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Loaded 30 prompts from the dataset.\n",
+      "Total prompts length: 418566 tokens.\n",
+      "Mean prompt length: 13952.20 tokens.\n",
+      "Max prompt length: 16630 tokens.\n",
+      "Min prompt length: 10007 tokens.\n"
+     ]
+    }
+   ],
+   "source": [
+    "prompts = []\n",
+    "ds = load_dataset(\"raniayu/token-dropping-demo\", split=\"train\")\n",
+    "for i, example in enumerate(ds):\n",
+    "    prompt = tokenizer.encode(ds[i][\"prompt\"], return_tensors=\"pt\").squeeze(0).tolist()\n",
+    "    prompts.append(prompt)\n",
+    "\n",
+    "print(f\"Loaded {len(prompts)} prompts from the dataset.\")\n",
+    "print(f\"Total prompts length: {sum(len(p) for p in prompts)} tokens.\")\n",
+    "print(f\"Mean prompt length: {sum(len(p) for p in prompts) / len(prompts):.2f} tokens.\")\n",
+    "print(f\"Max prompt length: {max(len(p) for p in prompts)} tokens.\")\n",
+    "print(f\"Min prompt length: {min(len(p) for p in prompts)} tokens.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "23c992fa",
+   "metadata": {},
+   "source": [
+    "## Baseline (without token dropping)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "b49aecc9",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "======================= Batched Stream Metrics (prefill) =======================\n",
+      "-------------------------------- Configuration ---------------------------------\n",
+      "Number of Streams:                                                            30\n",
+      "----------------------------------- Results ------------------------------------\n",
+      "Total Duration (s):                                                        26.45\n",
+      "Total Input Tokens:                                                       418566\n",
+      "Input Throughput (tokens/s):                                            15824.59\n",
+      "================================================================================\n",
+      "\n",
+      "\n",
+      "\n",
+      "======================= Batched Stream Metrics (decode) ========================\n",
+      "-------------------------------- Configuration ---------------------------------\n",
+      "Number of Streams:                                                            30\n",
+      "----------------------------------- Results ------------------------------------\n",
+      "Total Duration (s):                                                       649.28\n",
+      "Total Output Tokens:                                                      153600\n",
+      "Decode Throughput (tokens/s):                                             236.57\n",
+      "================================================================================\n"
+     ]
+    }
+   ],
+   "source": [
+    "batch = lmc_batch.LMCacheBatchedStream()\n",
+    "for i, prompt in enumerate(prompts):\n",
+    "    stream = lmc_stream.create_request(\n",
+    "        ctx=ctx,\n",
+    "        post_completion=post_completion,\n",
+    "        prompt_token_ids=prompt,\n",
+    "    )\n",
+    "    batch.add(stream)\n",
+    "results = batch.prefill(\n",
+    "    sampling_params={\"max_tokens\": 1, \"temperature\": 1.0, \"ignore_eos\": True}\n",
+    ")\n",
+    "results.emit()\n",
+    "\n",
+    "print(\"\\n\\n\")\n",
+    "\n",
+    "results = batch.decode(\n",
+    "    sampling_params={\"max_tokens\": max_tokens, \"temperature\": 1.0, \"ignore_eos\": True}\n",
+    ")\n",
+    "results.emit()\n",
+    "before_drop_data = results.to_dict()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f164ce86",
+   "metadata": {},
+   "source": [
+    "## Clear LMCache"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "a9c1dc14",
+   "metadata": {
+    "vscode": {
+     "languageId": "shellscript"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "{\"status\":\"ok\"}"
+     ]
+    }
+   ],
+   "source": [
+    "!curl -X POST {lmcache_url}/clear-cache"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b7fb3744",
+   "metadata": {},
+   "source": [
+    "## With Token Dropping"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "a495be98",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def drop_tokens_fn(\n",
+    "    kv_tensor: torch.Tensor, token_source: list[int]\n",
+    ") -> tuple[torch.Tensor, list[int]]:\n",
+    "    \"\"\"Drop the middle half of the chunks, keeping the first and last intact.\n",
+    "\n",
+    "    Args:\n",
+    "        kv_tensor: KV cache with shape [2, L, T, D]\n",
+    "        token_source: Token ids\n",
+    "    Returns:\n",
+    "        A tuple of the compacted KV tensor (on CPU) and the token ids.\n",
+    "    Raises:\n",
+    "        ValueError: If there are fewer than 3 chunks.\n",
+    "    \"\"\"\n",
+    "    h = kv_tensor.shape[2]\n",
+    "\n",
+    "    num_chunks = (h + chunk_size - 1) // chunk_size\n",
+    "    drop_count = num_chunks // 2\n",
+    "    if num_chunks < 3:\n",
+    "        raise ValueError(\"Not enough chunks to drop.\")\n",
+    "\n",
+    "    drop_start = (num_chunks - drop_count) // 2\n",
+    "    drop_start = max(1, min(drop_start, num_chunks - 1 - drop_count))\n",
+    "\n",
+    "    lo = drop_start * chunk_size\n",
+    "    hi = (drop_start + drop_count) * chunk_size\n",
+    "    keep_idx = torch.cat([torch.arange(lo), torch.arange(hi, h)])\n",
+    "    kept_ids = token_source[:lo] + token_source[hi:]\n",
+    "    logger.info(f\"compacting {drop_count}/{num_chunks} chunks\")\n",
+    "\n",
+    "    e_kv = rerotate_k_cache(\n",
+    "        kv_tensor[:, :, keep_idx, :].clone().to(work_device),\n",
+    "        old_positions=keep_idx.to(work_device),\n",
+    "        new_positions=torch.arange(\n",
+    "            keep_idx.numel(), device=work_device, dtype=torch.long\n",
+    "        ),\n",
+    "        model_config=config,\n",
+    "    )\n",
+    "\n",
+    "    assert keep_idx[0].item() == 0 and keep_idx[-1].item() == h - 1\n",
+    "    return e_kv.cpu(), kept_ids"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "e0675ef4",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "======================= Batched Stream Metrics (prefill) =======================\n",
+      "-------------------------------- Configuration ---------------------------------\n",
+      "Number of Streams:                                                            30\n",
+      "----------------------------------- Results ------------------------------------\n",
+      "Total Duration (s):                                                        26.96\n",
+      "Total Input Tokens:                                                       418566\n",
+      "Input Throughput (tokens/s):                                            15523.32\n",
+      "================================================================================\n",
+      "\n",
+      "\n",
+      "\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "\u001b[32;20m[2026-07-04 06:32:10,001] LMCache INFO:\u001b[0m compacting 19/39 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,183] LMCache INFO:\u001b[0m compacting 19/39 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,298] LMCache INFO:\u001b[0m compacting 21/42 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,299] LMCache INFO:\u001b[0m compacting 31/62 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,303] LMCache INFO:\u001b[0m compacting 31/62 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,310] LMCache INFO:\u001b[0m compacting 31/62 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,390] LMCache INFO:\u001b[0m compacting 22/44 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,405] LMCache INFO:\u001b[0m compacting 21/42 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,417] LMCache INFO:\u001b[0m compacting 21/43 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,515] LMCache INFO:\u001b[0m compacting 29/58 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,572] LMCache INFO:\u001b[0m compacting 21/42 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,658] LMCache INFO:\u001b[0m compacting 24/49 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,692] LMCache INFO:\u001b[0m compacting 28/57 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,696] LMCache INFO:\u001b[0m compacting 25/50 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,721] LMCache INFO:\u001b[0m compacting 23/47 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,758] LMCache INFO:\u001b[0m compacting 25/50 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,848] LMCache INFO:\u001b[0m compacting 29/59 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,897] LMCache INFO:\u001b[0m compacting 27/54 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,936] LMCache INFO:\u001b[0m compacting 32/64 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,938] LMCache INFO:\u001b[0m compacting 26/53 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,941] LMCache INFO:\u001b[0m compacting 30/61 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,965] LMCache INFO:\u001b[0m compacting 30/60 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,971] LMCache INFO:\u001b[0m compacting 25/51 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,974] LMCache INFO:\u001b[0m compacting 29/59 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,986] LMCache INFO:\u001b[0m compacting 30/61 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,988] LMCache INFO:\u001b[0m compacting 29/59 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,989] LMCache INFO:\u001b[0m compacting 32/64 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,991] LMCache INFO:\u001b[0m compacting 31/63 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:10,993] LMCache INFO:\u001b[0m compacting 31/62 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n",
+      "\u001b[32;20m[2026-07-04 06:32:11,234] LMCache INFO:\u001b[0m compacting 32/64 chunks \u001b[3m(3563635992.py:28:__main__)\u001b[0m\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "======================== Batched Stream Modify Metrics =========================\n",
+      "----------------------------------- Results ------------------------------------\n",
+      "Total Duration (s):                                                        11.46\n",
+      "================================================================================\n",
+      "\n",
+      "\n",
+      "\n",
+      "======================= Batched Stream Metrics (decode) ========================\n",
+      "-------------------------------- Configuration ---------------------------------\n",
+      "Number of Streams:                                                            30\n",
+      "----------------------------------- Results ------------------------------------\n",
+      "Total Duration (s):                                                       406.73\n",
+      "Total Output Tokens:                                                      153542\n",
+      "Decode Throughput (tokens/s):                                             377.50\n",
+      "================================================================================\n"
+     ]
+    }
+   ],
+   "source": [
+    "batch = lmc_batch.LMCacheBatchedStream()\n",
+    "for i, prompt in enumerate(prompts):\n",
+    "    stream = lmc_stream.create_request(\n",
+    "        ctx=ctx,\n",
+    "        post_completion=post_completion,\n",
+    "        prompt_token_ids=prompt,\n",
+    "    )\n",
+    "    batch.add(stream)\n",
+    "\n",
+    "results = batch.prefill(\n",
+    "    sampling_params={\"max_tokens\": 1, \"temperature\": 1.0, \"ignore_eos\": True}\n",
+    ")\n",
+    "results.emit()\n",
+    "\n",
+    "print(\"\\n\\n\")\n",
+    "\n",
+    "results = batch.modify(drop_tokens_fn)\n",
+    "results.emit()\n",
+    "\n",
+    "print(\"\\n\\n\")\n",
+    "\n",
+    "results = batch.decode(\n",
+    "    sampling_params={\"max_tokens\": max_tokens, \"temperature\": 1.0, \"ignore_eos\": True}\n",
+    ")\n",
+    "results.emit()\n",
+    "after_drop_data = results.to_dict()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "26ac7108",
+   "metadata": {},
+   "source": [
+    "## Result Plot"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "f6316471",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEiCAYAAAAWFgxbAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjExLjAsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvlcelbwAAAAlwSFlzAAAPYQAAD2EBqD+naQAAQcNJREFUeJzt3XlYE1f7N/AvEIgIyCJuIOICgghSiqjgBoorLhVEUKtVH7uitm5Fu1Dt09a1VX8uj7W11h0Bxa0o4kK1KoqiFVEoorKIICKyGyC53z94MyUmYDKE/XyuK9dFTs5M7hmSOzNnzpyjQUQEhmFaJM2GDoBhmIbDEgDDtGAsATBMC8YSAMO0YCwBMEwLxhIAw7RgLAEwTAvGEgDDtGAsATBMC8YSAMO0YCwBvOb27ds4evRoQ4fRLCUlJSEsLAxisbihQ2ky0tPTERERgbCwMOTm5uLevXsICwuDRCJRy/oFallLA8vIyEBMTIxSdceMGQM9Pb1qX//111/x+++/o6ioSF3h8SYWixEeHs4919LSgoGBASwsLGBtbQ1NzaaVv8PDw7F8+XIUFhZCX1+/3t//4cOHiIuL455raGjAxMQEVlZWsLCwqPd43mTz5s34/PPPMXToUOjr68Pe3h4hISFYuXIlSktL0apVKwDAvXv3cO/ePXh7e6v8mWgWCSA1NRXBwcEyZUePHkXbtm0xePBgmfJBgwbVmAAak9LSUvj6+sLS0hJ9+/YFEaGwsBD37t1DcXExpk+fjhUrVsDU1LShQ1WKra0tfHx8IBA0zMfuzJkz+PjjjzF48GC0b98eRITs7Gxcu3YNY8aMwW+//dZo9mVxcTGWLVuGr776Cl9++SVXbmdnBx8fH2hpaXFlipKC0qiZ0tPTo+HDh6u8XEBAAOnp6dVBRKorLCwkAPTee+/JvXb27Fnq0qULmZub0+PHj+s/uCbof//7HwGgqKgomfIrV66Qpqamwv3cUO7cuUMAKDQ09I11v/nmGwJApaWlKr9PszgCUMWzZ89w69YtiMVi2Nvbo0uXLkotFxMTg4yMDAwePBgdOnTgyhMSEvDw4UMYGBigX79+aN26NfdaQUEBzpw5g379+qFLly6Ij49HamoqbGxsYG1tXavtGD58OCIiIuDo6IiAgACcPHlS4XvevXsXDx48gJubG9q3bw8AyM3NRVxcHMrKymBnZ4du3brJrPvu3btITEzE5MmTUVJSgitXroCI4OrqKnforkrdpKQkxMfHY9KkSdwvWNXlRSIRrly5grKyMri6uqJNmzYKtz0lJQX379+Hubk5nJyckJaWhuvXr2PkyJHVLlMTV1dXdOvWDTdu3FD4emlpKW7cuIG8vDxYWlqiT58+0NDQULgPlN2GmtZ59epVnDt3DgAQGxurcHnp4f6NGzdw7949AJWnWNra2gCAESNGwNDQ8M0br3puahpePwKoqKigBQsWkLa2Njk7O9PAgQNJR0eHpkyZQoWFhVw9RUcAa9asIU1NTfrmm2+4svj4eHJ0dCRjY2Py9PQkBwcHMjY2puDgYJk6AGjnzp3k7+9Prq6u5OrqShoaGrR06dI3bkNNRwBSXl5eBICys7Nl3nPHjh3k7e1N/fv3p549e1JUVBSJxWIKDAwkHR0dcnJyoiFDhpBQKKSJEydSXl4et87AwEACQLGxsWRnZ0cjRoygLl26kLGxMR0/flzm/VWpu2rVKgIgs7+ly9+9e5feeustbnlDQ0O6ePGizPLl5eX0n//8h7S0tKhfv37k5uZGEyZMoB07dhAAio+Pr3F/VncEkJ+fT3p6ejR+/Hi5ZbZt20aGhobUs2dPGjVqFLVv35769u1LqampvLZBmXWuWbOG3N3dCQC5urqSj48P9+jVq5fMr/2WLVu4skmTJnH1Hj16VOO+kGoxCUB6mFT1kOrq1avUunVrmjZtGldWNQGUlZXRnDlzSCgU0v79+7k62dnZ1L59e/Lw8JD54vzwww8kEAgoLi6OiP79Mjo4OMh8EL777jvS0NCg27dv17gNyiSAlStXEgA6deqUzHv26tWLzp8/T0REIpGIUlNTad26dQSAfv/9d275uLg4MjQ0pAkTJnBl0g/0lClTKDc3l4gqv3xTpkwhXV1dSklJ4VW3pgQwY8YMevHiBRERlZSU0Ntvv019+vQhiUQit99OnDjBlV28eJH7AiibAIKCgig0NJRCQ0Np69at5OzsTFZWVnT37l2Z+vv27SMAtH79eq4sPz+fXF1dycnJiYtNlW1Qdp2XLl0iABQeHi4Tk6LD/dqcArSIBFBRUUFGRkY0atQouXrz588nDQ0NevLkCRH9mwBevHhBHh4e1K5dO7p8+bLMMitWrCAAlJSUJFMuFoupc+fONHfuXCL698s4e/ZsmXp5eXkEgFavXl3jNiiTADZv3kwAuAQlfU9/f3+5umZmZjRw4EC58uXLlxMA+ueff4jo3w+0NKlIPXnyhLS0tOjzzz/nylSpW1MCOHfunMLtysjI4Mo6duxIo0ePlov/3XffVSkBDB48mPul9PDwIGNjY5o1axY9e/ZMpr61tTW5uLjIrefcuXMEgKKjo1XeBmXXWV8JoEW0ATx+/BgvX75E//795V4bMGAANm/ejNu3b8PMzAwAUF5ejgEDBkAikSAmJgbdu3eXWebq1avQ09PjLr9QZSIFEcHY2Bh37tyRqe/s7Czz3MjICAYGBkhPT6/1tpWWlgKA3JUNFxcXmefZ2dnIzMyEv7+/3DoGDBgAALh165ZM20Tfvn1l6pmZmcHc3By3bt2SW4cqdRV5fR9J22bS09Nhbm6OrKwsZGVlyb2PdNl9+/Yp9T4AEBQUBE9PT+75s2fPMGDAAAwfPhy3bt2ClpYWnj9/juTkZHh5eeHo0aOg/z9yHhHhxYsXAIA7d+5g6NChSm8Dn3XWtRaRAMrKygDIf0mqlolEIq5MU1MTHTt2xK1bt5CWliaXAEpLS6GhoaHwQ9ezZ0+5hkVFjTE6Ojp49eqV6hvzmsTERO59q2rXrp3Mc1X3AQCZBs2qZa/XU7WuIq/vIx0dHQDg9pE0fl1dXaXeWxXt27fH7NmzERQUhIsXL8LDw4NLrI8ePVL4f/bx8ZHrO/CmbeCzzrrWIhKAhYUFtLS0kJycLPeatKxqS7iWlhZOnz4NX19fjBkzBiEhIRg/fjz3eo8ePXD9+nUcOHCA+yc3hJKSEhw/fhzW1tbo1auXzGtVW6kBoEOHDmjVqpXS+wCobG13cHDgnpeXlyMtLU3hkZQqdfno2LEjhEIhHj58KPeaojJVSa9YPHv2jHs/PT09ODs7Y8+ePbVef12tE5D/X6uiaXUl40lfXx9jxozBoUOHkJ2dzZWXlpbi559/hq2tLRwdHWWW0dXVxdGjR+Ht7Q1vb2+ZjP2f//wHIpEIP/30k9x7icViZGZm1t3G/H8ikQizZ8/GixcvFMbxOh0dHbzzzjs4evQo0tLSuPKysjJs27YNlpaW3KmA1G+//Sb3vKSkBFOmTJFbvyp1+dDR0cHEiRMRGhqK58+fc+XFxcUIDQ2t9fqjoqKgoaEBJycnAIC2tjbee+89HD58GElJSXL1nz9/zv2iK6su1gkAbdu2BQDk5+ervGyLOAIAgK1bt2Lo0KEYMGAA5s2bh1atWmHnzp148eIFIiMjFWZRgUCAffv2wdjYGDNnzkR+fj4CAgIwcOBA/N///R8WLlyIa9euYcSIEdyv65EjR7B8+XLMmjVLbbGnpqYiLCwMAFBYWIiEhAQcOnQIYrEYYWFhGDdunFLr2bBhA+Li4uDm5oZPP/0UBgYG+P3335Gamoo//vhDroeehYUFpk+fDk9PTyQkJGDTpk2YPXs2xo4dK7duVery9eOPP+Lq1atwc3PDJ598AoFAgMOHD2P69On473//q/Qv4aVLl/Dy5UsAQF5eHv744w9ERkYiKChI5lRq3bp1ePDgAfr164cPPvgA9vb2yM/Px+3bt3H+/Hlcv35d4SlJTepincOGDYOWlhYWL16McePGQSAQKN0PoNkmgEmTJsk0aHXp0gV37tzBnj17EBsbC7FYDD8/P8yePZvrIAMATk5OMplUQ0MDW7ZsQZcuXRAdHY1+/frBxcUF8+bNw5gxYxAcHIyrV6+iVatW6NmzJ86cOQNLS0sAleeEPj4+3POqJkyYoLBBqyqBQAAfHx8AQHBwMLS0tKCvrw8LCwvs2LEDnp6eXMcPqZreU9qusXfvXsTExKC8vBwTJkzAkSNHuAbQqhYtWoQTJ07g2LFjkEgkOHDgACZPnqwwVmXqKuoK7ODgwG3j67H6+PjItGV07twZt27dwvbt2xEbG4vOnTvjt99+wx9//AFAcftGVT169ICPjw8SEhKQkJAAAGjTpg3efvttrF69Gra2tjL1W7dujdOnT+PMmTOIjIxEZGQkOnToAHd3d2zbto3rdqvKNii7TlNTU/j4+MDc3FxmnYq6AtvZ2eHs2bMIDQ3FkSNHIJFI0Ldv35bdEYjhT3pZS91168qnn35KQqGQysrKGjSOpqhFtAEwzQNVuVwmlZubi71798LLy0vuaIh5s2Z7CsA0P0SEgQMHYvz48ejduzcyMzOxfft26OrqYv369Q0dXpPEjgAYOdWd09a2bm1pamrir7/+gpmZGS5duoSkpCQsXLgQ8fHxcpcwGeVoELHJQRmmpWJHAAzTgrEEwDAtWLNLAESEb7/9Fj169IBQKJTr3cbIGjBgAEaNGlXv76uvr4/FixfX+/uq05EjRyAQCHDz5s2GDoW3ZpcAQkND8c0332DLli0oLCzE5cuX6/T97O3tIRAIIBAIoKOjAxMTE/Tq1QtTp07F4cOH1TZ6a12pqKhQyyi9ixcv5vZDTY+OHTuq9X0bkkQigVgsRkM2o0VEREAgEPD+nDe7BBAdHY127dphzJgx0NHRkekxVRcqKipga2uLV69eoaSkBI8ePcKBAwfQs2dPzJw5E4MGDZK7dt0crVu3Dq9eveIeN2/ehFgsRmBgoEz5kydPGjrUZqW2SajZ9QPIycmp9e2hfEi7txoaGsLJyQlOTk4YO3YshgwZgunTp+PUqVP1HlN90tTUlBmSWpp4NTQ0GmwUYObNms0RQGpqKndziPRvgUDA3aVWUVGB1atXo3fv3tDT00OnTp0wc+ZMpKamyqxHem56+fJlDBo0CPr6+li7di2vmPr3749p06bh9OnT+Pvvv2Ve27dvHzdopLGxMcaOHSszZr3UgQMHMGjQIBgZGaFjx46YPHky7t+/z72u7HaJRCIsXboUnTt3hpGREcaNGydzV+DrlI2vtmJjY7n93LNnT+zatUuuTk3/k9TUVMycOROdOnWCnp4eevfujdWrV8ucXvzf//0fBAKBzJ2gQOWArgKBAAcOHJArHzNmDNq0aQNzc3MEBQXh/v37EAgE1d7Gu3HjRnTr1g0GBgYYPny4zP8I+Le94MaNG/jhhx/QpUsXtGnTBiNHjkR8fLxMXWXj3bZtGyZOnAgAcHd3l/vMK6UBuyGrXXl5OXl7e5OlpSWVl5dTeXk5N8aav78/6erq0m+//UbPnz+n69evk6OjI3Xo0EFmyCahUEhjx46lCRMm0N27dyklJYWOHTtW7Xva2NhQ7969q3394MGDBIA2bNjAlUkH5vzxxx8pIyODUlNT6YMPPqDWrVvLjBO4ePFiEggE9O2339LDhw/p2bNndPjwYZkhxpTdrkmTJlGbNm3o0KFDlJubS3/++SeNHj2a7O3t5YZPVza+mkiHJvvyyy8Vvi4UCmn8+PHk6+tLCQkJlJ2dTQsWLCAAFBMTI1dX0f/kyZMn1KFDB+rTpw9du3aNnj9/Trt27SJdXV2ZIdE2bNhAAOjp06cKY9y7dy9XlpqaSsbGxjRw4EC6c+cOPXv2jDZv3kz+/v4EgHbt2sXVDQ0N5cYCXLt2LWVlZdHdu3epd+/eZGNjQ2KxWK6ur68vrVmzhqs7dOhQMjQ0lBk7Udl4JRIJHTt2jBtK7PXPvDKaVQIgIvLx8SFLS0uZsqtXrxIA+u6772TKU1JSSCAQ0Mcff8yVCYVCMjAwoPz8fKXe700JQDq2m3QU4ISEBNLQ0KCvv/5app5YLCYHBwduZNq///6bAFBgYGC161Z2u65cuUIAaNOmTTL1Ll68SABkEoCy8b2JMgnA1NRUZnxAkUhEJiYmNGfOHLm6iv4nAQEBpKWlRQ8ePJAp//777wkAN5ajKgng448/JqFQKFc3ICCg2gQgHQNSKjw8nABwg7JWrTtz5kyZujk5OaSnp0ezZs3iylSJ98SJEwSALl26RHw0m1OAmpw9exYA5Lqsdu/eHc7OztzrUsOGDeM1vnxNpPeqnzhxAkQkN1CGpqYmhg0bhgsXLgAAd4vrjBkzql2nstslHWP+nXfekak3ePBguZlwlI1PHTw8PGTmDtDR0YGNjY3CEX4U/U/Onj2Lt956Cz169JApl8b++v9VGefPn0e/fv24qxVSEyZMqHaZqqNFAUCfPn0AKB6pSHrILmVqaorBgwfzilUdWkTrTG5uLgCgU6dOcq917NhRbnSW1+/Brg1pq7f0fvusrCwA/w6iSf9/MFGgcjQhiUSCsrIybmiqmmJRdrukI+hUndCkar2qlI1PHUOhKYq7TZs2cue+gOL9kJubq3CCFek25eTk1Pj+pKDl/Pnz5zJDm0kp2ndSr2+HNFFJBx1503o6duyI6OjoGmMFFMdbWy3iCMDExAQAFH6wsrOzuSGVpNR5W2lUVBQAcCO9St/r3r17KCoqQnFxMUpKSlBSUgKRSITy8nLo6Ohwg0jUNLyYstslrSdNKq/Xq0rZ+NShuhF8FH3QFf1PTExMqt124N9tkQ6M8fqEr4r2rYmJicL9pKhMSpXtqO5/UPUzqEq8tdUiEoCHhwcA4NixYzLlaWlpuHnzJoYNG1Yn7xsXF4d9+/Zh5MiReOuttwAAXl5eACqncaquswwAbiitgwcPVrt+ZbdLWk86fZhUTEyM3K+ksvE1Bh4eHrh9+7bc1QzpjMrS7ZeO6nz37l2ZetLTrNfXGRsbKzPuYHV1+Xj9f5CXl4e//vqL+x+pGq90FCTpqMkq49Vy0IgpagQkIpo4cSIZGBjQoUOHqKioiOLj46lfv35kYmIiM7mmUCikTz/9VOn3e70RUCQS0f3792nVqlVkYGBALi4ulJOTI7PMwoULqVWrVvTTTz/RkydPSCQSUWJiIm3YsIEWLFjA1Zs3bx7p6OjQunXr6OnTp1RQUEARERH00UcfqbxdY8aMIRMTEzpx4gQVFxfT9evXacyYMWRnZyd3FUDZ+GqiTCOgov08atQocnR0VKru48ePycTEhPr160fx8fFUVFREhw4dIgMDA5o4cSJXTywWk42NDTk6OlJycjK9fPmStm3bRtOmTZNrVEtJSaE2bdrQ8OHDKTk5mQoKCmjnzp00efLkahsBY2NjZeLKyckhALRu3Tq5upMmTaLNmzdTfn4+paSk0KhRo0hPT48SExN5xfvkyRMSCAT0+eef8xoRqcUkAJFIRF9//TV17dqVNDU1ydDQkHx8fLjZcKT4JAAApKWlRVpaWtSqVSuytLSkd955h/bv308VFRUKl9u3bx+5ubmRrq4uCYVCsrW1pSVLllBaWppMvZ9//pkcHR1JW1ubTExMaPz48TKX4pTdrqKiIvrkk0/I2NiYhEIheXh4UHJyMjk7OyucRVnZ+KpTHwmAiCgpKYl8fHzI0NCQNDU1qWvXrvT111+TSCSSqXfnzh0aNGgQCQQCateuHa1YsYKbgbfqF4qocrq0oUOHcvt86dKldPPmTQJABw4c4OrxSQDXrl2j5cuXk6mpKWlra9OgQYPo+vXrctulSrybN28mCwsL0tDQIC0tLdq5c6fCfaVIsxsPQCKRgIh4dwEWi8XQ0NCQ6dX2pvrSXfh6b7imQNXtVUVFRUW1+6S691X0/6vrGLW0tN44onBERAS8vLxw/vx57nCdiCAWixWeFr2+3rCwMPj6+iI2NvaNg8HyjVcajzLbI9V4TujUpLYfElUTR13fa1DX6jL+mtoLqntfRf+/hoqxqiNHjkBXV1fmy1tTN+e6aiupab18ul03rZ8rhqkH8+bNw/nz51FUVISsrCysWbMGu3fvxuLFi2FgYNDQ4amVymmqpKQEp0+fxsWLF5GRkQGgclKIIUOGYNSoUQ1yIw7DqNO0adOwcuVK3Lx5E/n5+bC2tsb69euxYMGChg5N7ZRuAygoKMAPP/yAn3/+GWKxGE5OTlynhuzsbMTFxUFbWxsffvghli9frvaedAzTlNXUXtCQlI6mV69eGDJkCA4fPoyhQ4fKnZeJxWJER0fj119/Ra9evdh93wxTRWO9LVrpI4CEhAT07t1bqZWqUpdhmIajtsuAFRUVjTLDKUsikSAzMxMGBga1mm6ZYWqLiFBYWAgzM7O6v6ysdI+BKpKTk2VuF12+fDkJBALq0aMHJSQk8Fllg0tPTycA7MEejeaRnp5e5597XkcA48ePxyeffIIxY8YgJSUFDg4O2LVrFy5cuID09HS19ZuuT/n5+TAyMkJ6ejprwGQaVEFBASwsLPDy5UvlZvitBV4JwMjICBkZGdDX18e2bdtw8eJFBAcH48WLF7CysmqSg2AWFBTA0NAQ+fn5LAEwDao+P4u8TjC0tbW5u6VOnz7N3XUlkUiafM84hmlJeLXajRo1Cv7+/ujXrx/Onz+Pn3/+GUDlkNx1dWstwzDqx+sIYOvWrXB1dUVGRgZCQ0O5EVFOnTqFFStWqDM+hmHqkEptAEVFRTJjuDUnrA2AaSwabRuAqakpRo0ahc2bN+PRo0d1FRPDMPVEpQRw7949jB07FsePH4etrS169+6NwMBAXLp0qcnP88YwLRHvnoCFhYU4c+YMTp48iVOnTqG8vByjR4/GuHHjMHr0aBgbG6s71jrFTgEav9zcXOzYsQOxsbFo3bo1PDw8MGPGDG6Q0hs3bmDZsmUKl12zZg2cnZ2VqqOIj48P8vPzZcpmzpyJmTNn1mKLFKvPz6JaugITEa5fv46TJ0/i5MmTuHv3Ltzc3PDnn3+qI8Z6wRJA41ZUVAQXFxf4+fnByckJWVlZ+P7779G3b18cOXIEQGWCuHXrlsxyv/76K44fP46nT5/C0NBQqTqKmJqa4qOPPoK7uztX1r17d24AT3Wq18+iuroUlpeXc39nZGTQ9u3bVVo+MTGR1q1bJzObilRxcTGFhITQ5s2bKTo6WuHyytSpSX5+PgFQekYgpn5VVFRQUVGRTFlwcDBpaGhQQUGBwmUkEgl1796d3nvvvWrXq0wdIqK2bdvSwYMHVQ2bl/r8LDaKewFKSkqod+/epKenJzf4Y2ZmJllZWZGjoyPNmjWL2rVrR9OnT1e5zpuwBND0fP7552RpaSkzB19V586dIwD0119/VbsOZeoQVSaAwYMHk5eXF33yySd08eLFWsVek0afAMaNG0cRERFERPTgwQPS1dWl4OBg+vDDD2ns2LEqr2/u3Lm0YMECcnR0lEsAM2bMICcnJ3r16hURVY42q6mpSeHh4SrVeROWAJqGH3/8kYYNG0ZWVlbUt29fuXkBq5o2bRr16tWrxvUpU4eI6O2336Z169ZReHg4LVq0iHR0dGjLli0qx6+MRp8ADA0NuUkdt27dSn5+fkRElJubS8bGxiqt69ChQ2Rvb0+lpaVyCaCiooL09PRo48aNMssMGTKEpk6dqnQdZbAE0DTcu3ePIiMjacuWLdSlSxe5yTal8vLyuLkNqqNMHanXTz++++470tXVpeLiYtU2QAn1+Vls0HsBHj16hPnz52P//v1o1aqV3Ovp6ekoLi6GjY2NTLmtrS03/7oydRQRiUQoKCiQeTCNX69evTBy5EgEBAQgJCQEe/bswfXr1+Xq7d+/H0RUYyu9MnWkpDPwSI0dOxalpaVITExUfSMaEV4JQHovwIIFC3D+/HludlRV7gUoLy/H1KlTsWzZMm421dcVFhYCqLz7sCojIyPuNWXqKLJq1SoYGhpyDwsLC6XiZhoPS0tLAP9OaFrVzp074e3tLTfvo6p1qiP9AVT0w9WUNNi9APv27UNiYiIqKiqwfv16rF+/Hjk5OYiLi8P69etBRNwIw6//Oufn53MZWZk6iixfvhz5+fncIz09Xam4mYZx+fJlXLt2jXsuFouxfv166OnpwdXVVaburVu3cOvWLbz//vvVru9Ndd555x3s2bMHAHD16lVcuXKFe+3Fixf45ptvYGdnh169etVmsxocr7sBDQ0NsWHDBrnynTt3Kr2Onj17Yu7cuTKzu5aXl6O4uBhZWVkgIlhaWkIoFCIlJUVm2ZSUFG5aaGXqKCIUCiEUCpWOl2lYHTt2xIcffoiUlBSYm5sjJSUFRkZGCA8P52ZSltq5cyesrKxkrtm/7k11oqOjuQldO3bsiA8++ADJycno1KkTEhIS4OzsjGPHjjX94eNq04CQm5tLycnJcg++FF0F8Pb2poEDB3KXeh49ekTa2tq0b98+leq8CWsEbBoyMjLo8uXLlJKSUu3lv6tXr9K9e/dqXM+b6kRHR1NKSopMWXp6Ol25coWePHmieuAqqM/PIq+egDdv3sS7775bbQMIj1UCAN566y24u7tj48aNXFlKSgrc3Nzg4OCAfv36ITg4GNbW1oiIiOAaHJWp8yasJyDTWDT6rsAuLi6wtbXFokWLFPb579q1K69gNmzYgB49emDChAky5Tk5OTh48CCys7Ph4OAAX19fuS+2MnVqwhIA01g0+gSgp6eHzMzMOh+wsD6xBMA0Fo12PACpbt26IS8vT92xMAxTz3glgMDAQHz00UdsUBCGaeJ4nQIIBAJuABBNTU25SyEVFRXqia4esVMAprGoz88ir34AJ0+eVHccDMM0AF4JYPTo0eqOg2lJDjTxzjPqMq3WY/HUGu+ZByUSCf7++2+Eh4dzZSKRSC1BMQxTP3glgKdPn8LV1RVvv/02vL29uXJvb29ERkaqLTiGYeoWrwSwcOFC9OzZU26QxGXLluGHH35QS2AMw9Q9Xm0A586dQ0JCgtwkIY6OjgrvzWYYpnHidQRQUlLCDcVc9RJgTk5Ok78/mmFaEl4JYNCgQdi1axeAfxNAWVkZvvjiixpvwWQYpnHhdQqwbt06uLu7IzIyEkSE2bNn48KFCygoKJAZOIFhmMaN1xFAnz598Pfff8PR0REeHh54/PgxfHx8cPv2bdja2qo7RoZh6givI4DDhw/Dx8cHa9askXvtq6++wnfffVfrwBiGqXu8jgBmz56Nc+fOyZV/9dVX2LZtW62DYhimfvBKANLRVGNjY7myL7/8Ev/73/8UJgaGYRonXqcAvr6+yM3NxdixY3Hx4kXs3bsXP//8M86dO8cNpMgwTOPHKwEAwEcffYTnz5/DxcUFrVq1Yl9+hmmClE4A1TXsGRsbw9XVlZsaHKhsC2AYpvFTOgFUNwaAubk50tLSkJaWxpWxBMAwTYPSCSAmJqYu42AYpgHwHg+AYZimj3cj4NOnT7F161bcv38fRAQ7OzsEBARw8wQyDNP48ToCuHz5MqytrRESEgJdXV3o6ekhNDQU1tbWuHz5srpjZBimjvA6AliyZAkCAgKwevVq7m5AIkJgYCCWLFmCq1evqjVIhmHqBq9hwYVCIbKysuSmBXvx4gXMzMzw6tUrtQVYX9iw4PWIDQpaqZpBQRv9zECGhoZ4/PixXPnjx4/Zl4dhmhBeCcDf3x9+fn44evQoMjMzkZmZifDwcEyZMgX+/v7qjpFhmDrCqw1g7dq1qKiogK+vLzcLkEAgwPvvv4+1a9eqNUCGYeoOrwTw/PlzbNu2DT/88AOSkpKgoaGBnj17wsjICBkZGejcubO642QYpg7wSgAWFhYgIhgZGaF///4KX2MYpvFTa0/AkpIS6OrqqnOVDMPUIZWOAKre5PP6DT8SiQRxcXHslmCGaUJUSgB//fWXwr8BQFtbG127dsXSpUvVExnDMHVOpQQQHR0NAJg8eTLCwsLqIh6GYeqR0m0AOTk53N9v+vJXrVuTsrIy7NixAz4+Phg1ahQWLVqER48eydW7ePEi/Pz84O7ujvnz5+Pp06e86jAMI0vpBGBvb4+vv/5aZuCP1z169AhffvklevfurdQ6Z8+ejXv37mHWrFn47LPP8OjRI7i4uCA9PZ2rc+HCBQwfPhzW1tZYunQpkpOTMXDgQBQWFqpUh2EYeUrfC/D48WMEBgYiPDwc9vb2cHZ2RocOHUBEyMrKQmxsLO7fvw9vb2+sWbMGXbt2feM6S0pK0Lp1a+55WVkZ9PT08Msvv2DWrFkAgIEDB8LCwgLBwcHcMp06dUJQUBAWL16sdJ03YfcC1CN2L0ClpnQvQNeuXXHo0CH8888/8Pf3x7NnzxAREYHTp0/j+fPnmDFjBh48eIBDhw4p9eUHIPPlB4CrV69CLBbDwcEBQOUXOSYmBuPHj5dZxtPTE2fPnlW6DsMwiqncEahr1674/PPP1RZATEwMPvvsMxQUFCArKwtHjx6Fs7MzACA9PR0SiQRmZmYyy5iZmXHzDyhTRxGRSASRSMQ9LygoUNcmMUyT0eBDgvXq1QsbN27E2rVrMWTIEMyfP59rZygvLwdQeftxVbq6utxrytRRZNWqVTA0NOQeFhYWatsmhmkqGjwBGBoaYsCAARg3bhwOHz4MHR0dbNq0CQBgYmICoHKcgapyc3PRtm1bpesosnz5cuTn53OPqg2PDNNSNHgCqEpLSwvt2rXD8+fPAVQexnfs2FFmCjIAuHbtGpycnJSuo4hQKESbNm1kHgzT0vBKABkZGbxeq6q0tBQ//vijzGH68ePHERsbizFjxnBlc+bMwa+//oonT54AqJyZ+N69e5gzZ45KdRiGkVeruwFVfa0qoVCIvLw8mJmZoVOnTnj58iVKS0uxZs0amUFFgoKCkJycDCsrK1hYWCAjIwNbtmyBi4uLSnUYhpHHa0xADQ0NhV/ykpISmJqaoqSkROl1lZeX459//oGenh46d+4MgUBxTsrMzER2djasrKxgYGDAu051WD+AesT6AVRqBP0AGvxuQG1tbaV6DpqZmcld6uNTh2GYf7G7ARmmBWN3AzJMC8brKgD78jNM88DrKsBnn31W4+sbN27ks1qGYeoZrwTw4MEDmecSiQQPHjxAcnIyPD091RIYwzB1j9cpwMmTJ2UeERERSEpKwrJly9iYgK9JSkrC3Llz0b17d3Tq1Anjxo1DXFycTJ28vDx89dVX6N27N0xNTdG/f3/s379fbl25ubkICAhAly5dYG5ujoULF6K4uLjG9+ezDNNyqK0rsIaGBpYuXYqQkBB1rbJZWLx4Mdzc3HD27FncvHkT5ubm8PDwkJlabfPmzWjbti3Cw8ORmJiIuXPn4r333sPx48e5OsXFxRg6dCju3buHiIgIxMfHw8rKCuHh4dW+N59lmJaFV0eg6qSkpMDZ2RkvX75U1yrrTX11vhCLxTA0NMSaNWsQEBBQbT07Ozt4eXlh3bp1AIDvv/8e69evx6NHj2BkZKTUe/FZpl6wjkCVmlpHIKnt27fLleXl5WH37t0YNWpUrYNqzoqKilBeXg59fX2Fr1dUVCAiIgKpqanw8vLiysPDw+Hl5aXSF5nPMkzLwisBrF+/Xq7M2NgYY8eORVBQUK2Das4CAwPRpk0bmRGMACA1NRU2NjYoLy+HQCDA1q1b4e7uzr2ekpKC4cOHw9/fH2fOnEHbtm0xceJErFixotpkwmcZpmVRy1UARjk//fQTfv/9d0RERHDjGEh16dIFL1++REFBAY4ePYqAgAAYGxvDx8cHQOWpw08//YQtW7Zg69at+OeffzB9+nRkZ2dj7969Ct+PzzJMy1LrNgDp7bza2tpqCaih1PV51+bNm7F06VIcOXIEY8eOfWP9adOm4cmTJ/jzzz8BAD179oSZmRnXGxOoPBVbuHAhioqKoKWlJbcOPsvUC9YGUKkRtAHwugpARNi+fTtsbGygq6sLXV1d2NraYseOHWxiUAW2bt2KpUuXIiwsTKkvP1C5j6vuy4EDB8p9YbW0tOTqVcVnGaZl4ZUAgoKCsHz5ckydOhXHjh3DsWPH4O/vj8DAQKxYsULNITZt27dvx+LFi3H48GGMGzdOYZ3Zs2cjJiYGr169QlFREXbt2oWwsDDMmDGDq/PZZ5/hypUrOHToECoqKpCYmIgff/wRPj4+3C3UGzdulDm3V2YZpmXjdQpgamqKgwcPYsSIETLlZ86cwfTp05WeGagxqavDrnbt2iE3Nxc6Ojoy5QsXLsSqVasAAJcuXcLKlStx7do1EBFsbW2xcOFCTJ8+XWaZU6dOYcmSJUhKSkLbtm3h6+uLVatWcWMfrF+/HsuWLUNFRYXSyzQIdgpQqRGcAvBOAA8fPpQLLj8/Hz169ODG9GtK6mqni0QihYfbAoFA7leYiKCh8eYvh0Qigaam/MGbWCxGRUWF3AjJNS3TIFgCqNQIEgCvT8TgwYOxZ88eufI9e/ZgyJAhtQ6qOREKhWjVqpXcQ9EhuDJffgDVfpG1tLQUfvlrWoZp2XidCJqZmWH+/Pk4cuQIXFxcQES4ceMGLly4gE8++QTfffcdV/f1kYMYhmk8eJ0CDBgwQOm6MTExqq6+QbAxAesROwWo1AhOAXgdATSVLzXDMDVjJ4YM04LxOgIgIoSEhODy5ctyU3IBwL59+2odGMMwdY/XEcCSJUswZ84cpKamcpezqj4YhmkaeH1b9+7di6ioKLi5uak7nkZLySt0zR7rQdy88L4XwNHRUd2xMAxTz3glgGHDhuGPP/5QdywMw9QzpU8BqnbuadeuHWbMmIE//vgDVlZWcj3YWOcfhmkalO4I1Bw7/1T1ps4XrA2gklraAFhHoEpNqSNQU/xSMwxTM9YRiGFaMLVPDSYUCtG9e3dMmjQJ7du35xsXwzD1gFcCuH//Ps6cOYN27dqhd+/e0NDQQHx8PJ4/f44hQ4bgwIEDCAwMxKVLl+Dg4KDumBmGURNeCcDKygpWVlbYsGEDN9KNSCTCZ599Bi0tLZw/fx7z5s3D4sWLcebMGbUGzDCM+vC6Hbhz5874+++/0bZtW5ny58+fw8nJCenp6cjMzISDgwNyc3PVFmxdYlcBlMOuAqhRI7gKwKsRMC8vD9nZ2XLlWVlZyMvLA1A5TLiurq5S6ysoKEBJSUmNdV69eoWsrCxIJJJa1WEY5l+8EsDEiRMxZcoUnDp1Cjk5OXj27BlOnToFPz8/TJgwAUDltFQTJ06scT27d++Gg4MDunTpgnbt2sHZ2VnucqNEIsGnn34KIyMj2NjYwMzMDGFhYSrXYRhGHq8EsH37dvTt2xfjx49H+/bt0aFDB4wfPx4uLi7cvIHm5uZYs2ZNtesQi8W4cOECgoOD8fLlS+Tl5aFfv37w8vKSucV43bp12L9/P27cuIGXL18iKCgIU6dORUJCgkp1GIaRV6uZgV68eIF//vkHGhoasLa2lpvuSlWZmZkwNzfHqVOnMHr0aACApaUlpk6ditWrV3P1rK2t4eXlhY0bNypd501YG4ByWBuAGjWCNoBa3bxvYmKiUhfhN0lOTgZQOegoADx79gxpaWlytx0PHDgQsbGxStdhGEYxtXcEAqD0r25VxcXFmD9/Pjw9PdGnTx8A4CYYef1qg6mpKa5cuaJ0HUVEIhFEIhH3vKCgQOWYGaapU8vswBKJBA8ePEBycjI8PT1VXp9IJIK3tzfKysqwf/9+rlw6ln3VmW6AyglJpXPeKVNHkVWrVmHlypUqx8owzQmvBHDy5Em5MiLCF198IfdFfJOysjJ4e3vj0aNHiI6Oluk+3LlzZwCVlxerysrKgrm5udJ1FFm+fDkWLVrEPS8oKICFhYVKsTNMU6e2m4E0NDSwdOlShISEKL2M9MufnJyM6Oho7txfysDAAG+//TYiIyO5svLycpw7dw5Dhw5Vuo4iQqEQbdq0kXkwTEuj1hE88/LykJ+fr1RdsVgMX19fxMbGIjw8HGVlZXj8+DGAyvN36Sy3QUFBmDx5MpydneHq6ooff/wRWlpa+Pjjj7l1KVOHYRh5vC4DSq/1V5WXl4fdu3fD0dERhw4deuM68vLy4OTkpPC1NWvWwM/Pj3t++PBhbNq0CdnZ2XBwcMD3338PGxsbmWWUqVMTdhlQOewyoBo1gsuAvBKAlZWVXJmxsTEGDx6MoKAgGBkZqSO2esUSgHJYAlCjRpAA1HIVgGGYpomNCMQwLRjvRsCnT59i69atuH//PogIdnZ2CAgIQKdOndQZH8MwdYjXEcDly5dhbW2NkJAQ6OrqQk9PD6GhobC2tsbly5fVHSPDMHWE1xHAkiVLEBAQgNWrV3NzAhARAgMDsWTJEly9elWtQTIMUzd4XQUQCoXIysqCsbGxTPmLFy9gZmaGV69eqS3A+sKuAiiHXQVQo0ZwFYDXKYChoSHXaaeqx48fsx51DNOE8EoA/v7+8PPzw9GjR5GZmYnMzEyEh4djypQp8Pf3V3eMDMPUEV5tAGvXrkVFRQV8fX25m38EAgHef/99rF27Vq0BMgxTd3i1AVRUVEAgEODly5dISkqChoYGevbs2SR7AEqxNgDlsDYANWoEbQC8jgB0dHQgkUhgZGSE/v37qzsmhmHqCa82gPbt2yscFpxhmKaFVwL48MMP8cUXX6C0tFTd8TAMU494nQIcP34ct2/fRkhICLp168ZNDyZ148YNtQTHMEzd4pUA/Pz8ZO7XZximaeKVAJYtW6buOBiGaQDsdmCGacF4JYAnT55g6tSp6NKlC/T19eUeDMM0DbxOAf7zn/8gPz8fK1eulLshiGGYpoNXArh8+TKSkpLkhvFmGKZp4d0RSFtbW92xMAxTz3glgFmzZmHFihUqzwLEMEzjovQpQN++fbm/xWIxbt++jUOHDsHS0pIbFUiKdQRimKZB6QQwefJkmeesIxDDNH1KJwDW+Ydhmh+V2gAUzQjEMEzTpVICSElJqas4GIZpAKwrMMO0YCp3BPrrr7/eWGfQoEG8gmEYpn6pnAAGDx78xjo8hhlkGKYBqJwA7t+/XxdxMAzTAFROALa2tnURB8MwDYA1AjJMC6ZSAmBDgDNM86JSAoiJiamrOBiGaQC8xgNQJ7FYjFOnTiExMRF+fn6wsLCQq1NSUoI//vgD2dnZcHBwwNChQ3nVYRhGVoO2AYSFhcHKygpr167F0qVLFfY0fPr0KRwdHfH999/j5s2b8PX1xbvvvqtyHYZh5DXoEUC7du0QHR0NLS0thb/8ABAYGAgDAwNcvXoVQqEQd+/ehaOjIyZPnox33nlH6ToMw8ir1RFARUUFHj16xHv5oUOHwtLSstrXxWIxjhw5gvfeew9CoRAAYG9vj0GDBiEkJETpOgzDKMYrAZSUlGDu3Llo3bo1unfvzpVPnz4dt2/fVldsSE9PR3FxMWxsbGTKbW1tuQ5JytRRRCQSoaCgQObBMC0NrwTw5ZdfIjExEdHR0TLl/v7+WLlypTriAgAUFhYCgNy040ZGRtxrytRRZNWqVTA0NOQe1Z2CMExzxisBhIWF4ffff4ebm5tMuZubG86dO6eWwACgdevWACD365yfnw89PT2l6yiyfPly5Ofnc4/09HS1xc0wTQWvRsCcnBx06tQJAGTGAxSJRBCLxeqJDIClpSWEQqHc1YGUlBRYW1srXUcRoVDItRkwTEvF6wigT58+iIyMBCCbALZt2wYXFxf1RAZAIBDAy8sL+/fvh0QiAQA8fvwYf/75JyZNmqR0HYZhFON1BPDtt9/Cz88P169fBwBs2rQJp0+fRlRUFKKiopReT0JCAk6dOoX8/HwAwKFDh3Djxg24ublxpxdr166Fm5sbRo4ciX79+iE4OBgeHh7w9/fn1qNMHYZh5PE6Ahg9ejSOHTuGW7duwcjICCtWrEBZWRnOnj0LDw8PpddTWlqKrKwslJaWYvHixdDT00NWVhaKioq4Oj169MDdu3cxYcIEaGho4IcffkBERAS0tLRUqsMwjDwNYqN3AKhsRDQ0NER+fj7atGkj9/prUx+0WGr5tBxgOxMAME3xznzTZ1Gd2O3ADNOCKd0G0LVrV6VX+vjxYx6hMAxT35ROACtWrOD+Tk5Oxrp16zBlyhSu1T82NhYhISFYunSp2oNkGKZuKJ0AZs2axf09YsQI7Nq1C9OnT5epM2bMGOzevVttwTEMU7d4tQHExsZi/PjxcuXjx4/nLg0yDNP48UoArVu35joCVRUZGVlj91uGYRoXXh2BPv/8c8ycORNRUVFwcXEBEeHGjRvYu3cv1q5dq+4YGYapI7wSwGeffQYrKyts2LABJ06cAADY2dkhLCwMXl5eag2QYZi6w3tEoHHjxmHcuHHqjIVhmHpW645AYrFYrXcAMgxTf3gngL1798Le3h66urrQ1dWFvb099u7dq87YGIapY7wSwKZNm/Dxxx9j9OjROHDgAA4ePIjRo0fjo48+wqZNm9QdI8MwdYTXzUDdunXDxo0bMXHiRJnyo0ePYtGiRXj48KHaAqwv7GYg5bCbgdSoqd4M9OTJEwwbNkyufNiwYcjIyKh1UAzD1A9eCaBbt244fvy4XPmxY8fQrVu3WgfFMEz94HUZ8IsvvsCcOXMQFRWFfv36AQCuXbuGgwcP4pdfflFrgAzD1B1eCeC9995Dp06dsHbtWkRGRkJDQwN2dnY4efIkRo4cqe4YGYapI7w7Ao0cOZJ92RmmiePdDyA7O1upMoZhGi9eCeB///ufwhmAVq5cie3bt9c6KIZh6gevfgA9evTA2bNn5Vr8Hz58iNGjR+Off/5RW4D1hfUDUA7rB6BGTbUfQGZmJgwMDOTKDQwM2BRbDNOE8EoAjo6OCof+2rVrFxwcHGodFMMw9YPXVYAVK1Zg3LhxuHbtGoYMGQIiwsWLFxEeHs6ND8AwTOPHe2agyMhI5Obm4uuvv8Y333yDFy9eIDIyEmPGjFF3jAzD1BHe/QCGDx+O4cOHqzMWhmHqWa0GBKmoqMCjR4/UFQvDMPWMVwIoKSnB3Llz0bp1a3Tv3p0rnz59Om7fvq2u2BiGqWO8EsCXX36JxMREREdHy5T7+/sr7CDEMEzjxKsNICwsDBcuXICVlZVMuZubm9xsQQzDNF68jgBycnLQqVMnAIBGlS5yIpGIDRDKME0IrwTQp08fbmagqglg27Zt3GShDMM0frxOAb799lv4+flx8wBu2rQJp0+fRlRUFKKiotQaIMMwdYd3R6Bjx47h1q1bMDIywooVK1BWVoazZ8/Cw8ND3TEyDFNHeHcEcnd3h7u7uxpDYRimvvHuCPTy5UvcuXMH8fHxyM/PV2dMvFy8eBF+fn5wd3fH/Pnz8fTp04YOiWEaPZUTQFJSEkaMGIG2bdvC0dERffr0gYmJCUaNGoXk5OS6iPGNLly4gOHDh8Pa2hpLly5FcnIyBg4ciMLCwgaJh2GaCpUGBMnOzoaDgwPMzc0xd+5c2NjYAAASExPxyy+/IDs7G/Hx8WjXrl2dBazIwIEDYWFhgeDgYACVPRU7deqEoKAgLF68WKl1sAFBlMMGBFGjpjYgyMaNG2Fvb4/r168jICAAnp6e8PT0xLx58xAbGwsbG5t6nxqspKQEMTExGD9+PFfWunVreHp64uzZs/UaC8M0NSo1AkZGRmL9+vXQ1taWe01HRwdBQUEIDAzEd999p7YA3yQ9PR0SiQRmZmYy5WZmZjh37ly1y4lEIohEIu65tB2joKCgbgJtJtSye0rUsI7moJqdKf0M8hitT2UqJYCUlBT07du32tf79u2LBw8e1DooVZSXlwMAhEKhTLmuri73miKrVq1SeN+ChYWFegNsZgwNGzqCZuT9mndmYWEhDOt4h6uUAAoLC2s8JzE0NKz3hjcTExMAwIsXL2TKc3Nz0bZt22qXW758ORYtWsQ9l0gkePHiBdq2bSvTu7GxKCgogIWFBdLT0+v8vLC5a+z7kohQWFgod1RbF1RKAESEioqKGutIJJJaBaQqMzMzdOzYEbGxsRg3bhxXfu3aNQwePLja5YRCodxRg5GRUV2FqTZt2rRplB/apqgx78u6/uWXUvkyoLa2do2PhjBnzhz8+uuvePLkCQDg8OHDuHfvHubMmdMg8TBMU6HSEcDevXvrKo5aCQoKQnJyMqysrGBhYYGMjAxs2bKF3ZjEMG+gUgJ499136yqOWhEKhQgJCUFmZiays7NhZWWlcN6CpkwoFOKbb76RO21hVMf25b94zQzEMEzzUKtBQRmGadpYAmCYFowlgAaSmZmJ0NDQGuukpaUhPDy8niJqGbKyshASElJjnYyMDBw5cqSeImpYLAHUUlRUFGJjY2XK8vLyEBwcjKSkJJny1NRUBAcHo6KiAnFxcZgxYwb32pMnT3D48GGZ+leuXMH7779fd8FXoej9G7Nz585xI1JJvXz5EsHBwUhMTJQpT0tLQ3BwMMrLy3H79m1MmzaNe01RIo6JiWk5l5CJqZU5c+aQq6urTNnvv/9OAGj27Nky5cuWLSNLS0siIoqLi6MZM2Zwr4WHh5Oenp5M/YMHD1Lbtm3rJvDXKHr/xuyDDz4gFxcXmbJ9+/YRAJn9SkT01Vdfkbm5ORER3b59m6ZNm8a9duLECRIKhTL1Q0NDydDQsG4Cb2R4jwjEVPLw8MCePXtQXFwMPT09AP+OT3DhwgWZuhcuXMCwYcMAAB06dODuYHz+/Dn++usvVFRUcLc029racstJJBLcvXsXaWlpsLe3R9euXeXiSExMxP3792FqagpXV1cIBP/+a5OTk5GcnIyxY8dyZdnZ2bhw4QL8/f2rff+33nqr9juojnh4eGDnzp0oKCjgevMpu98nTpwIoLK7+KVLlyCRSLjtlt7iDlT2fI2Pj0daWhp69+6Nbt261cem1a+GzkBNXUZGBgGg06dPc2WWlpYUGRlJrVu3psePHxMRUWFhIQkEAtqzZw8Ryf7yJCYm0qBBg0ggEJCfnx/5+fnRvn376ODBg6Svr08eHh7k5uZGnp6epKOjQ7t375aJYfbs2WRgYECjRo2ibt26ka2tLaWmpnKvb968mWxsbGSWiYqKIum/v7r3b8yysrIIAJ08eZIr69GjB0VERJC+vj49ePCAiIiKi4tJR0eHfvvtNyIiOnXqFGlpaRERUXJyMg0ePJg0NTW57d69ezeFhoZS69atydPTk1xdXWnEiBEy62hOWAJQg549e1JgYCARET18+JCEQiGVlpbS8OHDadeuXUREFBERQQAoIyODiOQPPas7BQBA27dv58pWr15NZmZm3PPg4GDS1dWl+/fvExHRq1evaNCgQTRp0iSuzpsSQHXv39jZ2dnR4sWLiYgoLS2NtLW1qaioiEaNGkW//PILERGdOXOGAHCJuGoCIKr+FAAAbdmyhStbv349tW/fvq43qd6xRkA18PDw4A47L1y4gP79+6NVq1YYOnSoTLm1tTXMzc1VWre2tjbmzp3LPXd3d0dmZiaKiooAAMHBwZg0aRJ3yiAUCrFkyRIcPXoUr169UsfmNVqv73cXFxfo6enJ7fdu3brB0tJSpXVraWnhgw8+4J67u7vj2bNnePnypdribwxYAlADDw8P3Lx5EwUFBbhw4QI3WvLrH0Tpeagq2rRpAy0tLe65tPuq9MudmpoqM0ErAPTo0QNEhPT0dD6b02R4eHjg9u3byMvLU/t+19fXl7m57fX93lywBKAGHh4eEIvFuHTpEqKjo7kPYv/+/ZGTk4O4uDjcunWL1wfxTUxNTeXGQpA+NzU1BQBoamrK3abdHD7I7u7uICJcvHhRJgG4uLggPz8fN27cwI0bN+pkvzcXLAGoQfv27WFnZ4cdO3YgJycHrq6uACp/Nfr374+VK1dCIpHUOI+Cvr4+RCKRysNADRo0CCdPnkRZWRlXFhoaCjs7OxgbGwMAzM3NkZmZidLSUq7O6y3lfN+/IbVt2xYODg747bffkJmZCTc3NwCVp02urq7473//i4qKihonq9HX10d5eXm9j2PRWLDLgGoybNgwbNmyBUOGDEGrVq248qFDh+Lbb7+Fvb092rdvX+3yDg4O0NLSwrJly+Dk5CRzGbAmixYtwu7duzF8+HC8++67uHPnDn755RecPHmSq+Pp6QlDQ0P4+vrC29sbcXFxcj3dFL1/Y74MKDVs2DBs3LgRbm5u3GVYoHK/BwUFwdbWlpvIVpHevXtDR0cHgYGBcHZ2lrkM2BKwIwA1mTJlCvz8/OR67k2cOBF+fn6YN2+eTLm5uTmmTJnCPe/QoQOioqJQWlqKY8eOISEhAZaWlvD29pZZztjYGH5+ftw5qb6+Pm7cuAEvLy9cvnwZQqEQ165dw8iRI7ll9PT0cO3aNfTp0wcxMTGwt7fHyZMn4efnV+P7NwW+vr7w8/PDhx9+KFM+YcIE+Pn5YcGCBTLlnTp1ktnudu3a4ezZsxCJRDh27Bji4+NhYWEBHx8fmeWMjIzg5+cHXV3dutuYBsBuB2aYFowdATBMC8YSAMO0YCwBMEwLxhIAw7RgLAEwTAvGEgDDtGAsATBMC8YSAMO0YCwBMEwLxhIAw7RgLAEwTAvGEgDDtGD/D1udNk89koLuAAAAAElFTkSuQmCC",
+      "text/plain": [
+       "<Figure size 250x300 with 1 Axes>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "labels = [\"Without\", \"With\"]\n",
+    "data = [\n",
+    "    before_drop_data[\"metrics\"][\"results\"][\"output_tput\"],\n",
+    "    after_drop_data[\"metrics\"][\"results\"][\"output_tput\"],\n",
+    "]\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(2.5, 3))\n",
+    "bars = ax.bar(labels, data, color=[\"blue\", \"orange\"])\n",
+    "ax.bar_label(bars, fmt=\"%.1f\", padding=3)\n",
+    "ax.set_ylabel(\"Decode Throughput (tokens/s)\")\n",
+    "ax.set_title(\"Token Dropping Benefit\\nfor Decode Throughput\")\n",
+    "ax.margins(y=0.15)\n",
+    "plt.tight_layout()\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "f83db925",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Only close the context when done.\n",
+    "lmc_sdk.close(ctx)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "LMCache (3.12.3)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/token_dropping/utils.py b/examples/token_dropping/utils.py
new file mode 100644
index 0000000..eda8e14
--- /dev/null
+++ b/examples/token_dropping/utils.py
@@ -0,0 +1,240 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Helpers for the token dropping example."""
+
+# Standard
+import json
+
+# Third Party
+from transformers import AutoConfig
+from transformers.modeling_rope_utils import ROPE_INIT_FUNCTIONS
+import httpx
+import torch
+
+# First Party
+import lmcache.sdk.stream as lmc_stream
+
+
+def _rotate_half_neox(x: torch.Tensor) -> torch.Tensor:
+    """Rotate pairs using GPT-NeoX/Llama-style half layout."""
+    x1, x2 = x.chunk(2, dim=-1)
+    return torch.cat((-x2, x1), dim=-1)
+
+
+def _rotate_half_interleaved(x: torch.Tensor) -> torch.Tensor:
+    """Rotate pairs using interleaved layout."""
+    x_even = x[..., ::2]
+    x_odd = x[..., 1::2]
+    return torch.stack((-x_odd, x_even), dim=-1).flatten(-2)
+
+
+def _rope_cos_sin(
+    *,
+    config: AutoConfig,
+    positions: torch.Tensor,
+    rotary_dim: int,
+    device: torch.device,
+    dtype: torch.dtype,
+) -> tuple[torch.Tensor, torch.Tensor, float]:
+    """Build RoPE cos/sin for the model config, including HF rope_scaling."""
+    rope_scaling = getattr(config, "rope_scaling", None)
+    rope_type = None
+    if rope_scaling is not None:
+        rope_type = rope_scaling.get("rope_type", rope_scaling.get("type"))
+
+    if rope_scaling is None or rope_type == "default":
+        rope_theta = getattr(config, "rope_theta", 10000.0)
+        inv_freq = 1.0 / (
+            rope_theta
+            ** (
+                torch.arange(0, rotary_dim, 2, device=device, dtype=torch.float32)
+                / rotary_dim
+            )
+        )
+        attention_scaling = 1.0
+    else:
+        rope_type = rope_scaling.get("rope_type", rope_scaling.get("type"))
+        if rope_type is None:
+            raise ValueError(f"rope_scaling is missing rope_type/type: {rope_scaling}")
+
+        if rope_type == "default":
+            rope_theta = getattr(config, "rope_theta", 1000000)  # Qwen3
+            inv_freq = 1.0 / (
+                rope_theta
+                ** (
+                    torch.arange(0, rotary_dim, 2, device=device, dtype=torch.float32)
+                    / rotary_dim
+                )
+            )
+            attention_scaling = 1.0
+        else:
+            inv_freq, attention_scaling = ROPE_INIT_FUNCTIONS[rope_type](
+                config=config,
+                device=device,
+                seq_len=int(positions.max().item()) + 1,
+            )
+
+    inv_freq = inv_freq[: rotary_dim // 2].to(device=device, dtype=torch.float32)
+    positions = positions.to(device=device, dtype=torch.float32)
+    freqs = torch.outer(positions, inv_freq)
+
+    emb = torch.cat((freqs, freqs), dim=-1)
+    cos = emb.cos().to(dtype=dtype)
+    sin = emb.sin().to(dtype=dtype)
+    return cos[:, None, :], sin[:, None, :], float(attention_scaling)
+
+
+def _rerotate_k_cache(
+    *,
+    k_flat: torch.Tensor,
+    old_positions: torch.Tensor,
+    new_positions: torch.Tensor,
+    config: AutoConfig,
+    head_size: int,
+    is_neox_style: bool,
+) -> torch.Tensor:
+    """Move key cache RoPE from old positions to new positions."""
+    num_tokens = k_flat.shape[0]
+    k = k_flat.view(num_tokens, -1, head_size)
+
+    partial_factor = getattr(config, "partial_rotary_factor", 1.0)
+    rotary_dim = int(head_size * partial_factor)
+    if rotary_dim % 2 != 0:
+        raise ValueError(f"rotary_dim must be even, got {rotary_dim}")
+
+    k_rot = k[..., :rotary_dim]
+    k_pass = k[..., rotary_dim:]
+
+    old_cos, old_sin, old_scale = _rope_cos_sin(
+        config=config,
+        positions=old_positions,
+        rotary_dim=rotary_dim,
+        device=k.device,
+        dtype=k.dtype,
+    )
+    new_cos, new_sin, new_scale = _rope_cos_sin(
+        config=config,
+        positions=new_positions,
+        rotary_dim=rotary_dim,
+        device=k.device,
+        dtype=k.dtype,
+    )
+
+    rotate_half = _rotate_half_neox if is_neox_style else _rotate_half_interleaved
+
+    # Detach old RoPE: inverse rotation
+    k_unscaled = k_rot / old_scale
+    k_plain = (k_unscaled * old_cos) - (rotate_half(k_unscaled) * old_sin)
+
+    # Attach new RoPE.
+    k_new = new_scale * ((k_plain * new_cos) + (rotate_half(k_plain) * new_sin))
+
+    return torch.cat((k_new, k_pass), dim=-1).reshape_as(k_flat)
+
+
+def rerotate_k_cache(
+    kv_tensor: torch.Tensor,
+    old_positions: torch.Tensor,
+    new_positions: torch.Tensor,
+    model_config: AutoConfig,
+) -> torch.Tensor:
+    """Move key cache RoPE from old positions to new positions.
+    Args:
+        kv_tensor: The KV cache tensor of shape [2, L, T, D].
+        old_positions: The old token positions.
+        new_positions: The new token positions.
+        model_config: The model configuration.
+    Returns:
+        The rerotated KV cache tensor.
+    Raises:
+        ValueError: If the input tensor shape or dimensions are invalid.
+    """
+    if kv_tensor.ndim != 4:
+        raise ValueError(f"kv_tensor must be 4D [2, L, T, D], got {kv_tensor.ndim}D")
+
+    head_size = getattr(
+        model_config,
+        "head_dim",
+        model_config.hidden_size // model_config.num_attention_heads,
+    )
+    if kv_tensor.shape[3] % head_size != 0:
+        raise ValueError(
+            f"hidden dim {kv_tensor.shape[3]} not divisible by head_size {head_size}"
+        )
+
+    is_neox_style = True
+    for layer in range(kv_tensor.shape[1]):
+        kv_tensor[0, layer] = _rerotate_k_cache(
+            k_flat=kv_tensor[0, layer],
+            old_positions=old_positions,
+            new_positions=new_positions,
+            config=model_config,
+            head_size=head_size,
+            is_neox_style=is_neox_style,
+        )
+    return kv_tensor
+
+
+def _extract_token_id(choice: dict) -> int:
+    """Pull the generated token id from a streaming choice.
+
+    Requires the vLLM server to be started with --return-tokens-as-token-ids,
+    so logprobs token strings look like "token_id:123".
+    """
+    logprobs = choice.get("logprobs") or {}
+    toks = logprobs.get("tokens") or []
+    if not toks:
+        return -1
+    last = toks[-1]
+    return int(last.split(":")[-1]) if ":" in last else -1
+
+
+def make_post_completion(
+    vllm_url: str, model_name: str, timeout: float
+) -> lmc_stream.PostCompletion:
+    """Build a streaming post_completion callable for lmcache.sdk.stream.
+
+    Args:
+        vllm_url: The URL of the vLLM server.
+        model_name: The name of the model.
+        timeout: Timeout in seconds for HTTP requests.
+
+    Returns:
+        A streaming post_completion callable.
+    """
+
+    def post_completion(prompt_token_ids, sampling_params, cache_salt):
+        payload = {
+            **sampling_params,
+            "model": model_name,
+            "prompt": list(prompt_token_ids),
+            "stream": True,
+            "logprobs": 0,
+        }
+        if cache_salt:
+            payload["cache_salt"] = cache_salt
+        timeout_http = httpx.Timeout(
+            connect=timeout, read=None, write=timeout, pool=timeout
+        )
+        with httpx.stream(
+            "POST",
+            f"{vllm_url.rstrip('/')}/v1/completions",
+            json=payload,
+            timeout=timeout_http,
+        ) as response:
+            response.raise_for_status()
+            for line in response.iter_lines():
+                if not line or not line.startswith("data: "):
+                    continue
+                if line == "data: [DONE]":
+                    break
+                body = json.loads(line.removeprefix("data: "))
+                choices = body.get("choices") or []
+                if not choices:
+                    continue
+                choice = choices[0]
+                yield lmc_stream.TokenEvent(
+                    token_id=_extract_token_id(choice),
+                    text=choice.get("text", ""),
+                )
+
+    return post_completion
diff --git a/format.sh b/format.sh
new file mode 100755
index 0000000..e055ccc
--- /dev/null
+++ b/format.sh
@@ -0,0 +1,7 @@
+#!/bin/bash
+
+echo "LMCache code quality tools (lining, formatting, spelling and static checks) are now managed by pre-commit hooks."
+echo "Please run 'pip install -r requirements/lint.txt', followed by"
+echo "'pre-commit install' to install the pre-commit hooks."
+echo "Then code quality checks will run automatically before each commit."
+echo "Check out https://pre-commit.com/ for more details."
\ No newline at end of file
diff --git a/lmcache/__init__.py b/lmcache/__init__.py
new file mode 100644
index 0000000..cce87ca
--- /dev/null
+++ b/lmcache/__init__.py
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+import sys
+
+# First Party
+from lmcache.logging import init_logger
+
+# --------------------------
+# Backend instance & Device detection
+# --------------------------
+from lmcache.v1.platform import get_backend
+from lmcache.v1.platform import torch_dev as torch_dev
+from lmcache.v1.platform import torch_device_type as torch_device_type
+
+try:
+    # First Party
+    from lmcache._version import __version__
+except ImportError:
+    __version__ = "unknown"
+
+logger = init_logger(__name__)
+
+__all__ = ["__version__", "torch_dev", "torch_device_type"]
+
+_ops = get_backend(torch_device_type)
+if _ops is not None:
+    # Override lmcache.c_ops with merged module,
+    # in which:
+    #     python_ops_fallback as base,
+    #     use backend implementation if exists
+    sys.modules["lmcache.c_ops"] = _ops
+else:
+    logger.warning(
+        "No compute backend loaded; CLI-only mode (torch/numba not installed)"
+    )
diff --git a/lmcache/banner.py b/lmcache/banner.py
new file mode 100644
index 0000000..25de6dd
--- /dev/null
+++ b/lmcache/banner.py
@@ -0,0 +1,123 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Startup banner shown when LMCache starts serving.
+
+The banner is printed at most once per process, to ``stderr``, by the
+``lmcache`` CLI and by the vLLM connector integrations (scheduler role
+only, so tensor-parallel deployments print a single banner). Setting the
+``LMCACHE_DISABLE_BANNER=1`` environment variable suppresses it.
+"""
+
+# Standard
+from typing import TYPE_CHECKING
+import os
+
+if TYPE_CHECKING:
+    # Standard
+    from typing import TextIO
+
+try:
+    # First Party
+    from lmcache import _version
+
+    _LMCACHE_VERSION = getattr(_version, "__version__", "unknown")
+    _LMCACHE_COMMIT = getattr(_version, "__commit_id__", "")
+except ImportError:  # pragma: no cover - version file is generated at build time
+    _LMCACHE_VERSION = "unknown"
+    _LMCACHE_COMMIT = ""
+
+DISABLE_BANNER_ENV = "LMCACHE_DISABLE_BANNER"
+
+LMCACHE_WEBSITE = "https://lmcache.ai/"
+LMCACHE_RECIPES = "https://docs.lmcache.ai/recipes"
+LMCACHE_LINKEDIN = "https://www.linkedin.com/company/lmcache-lab"
+
+# Solarized palette, 24-bit ANSI escapes (TTY only): "LM" in bold italic
+# orange (#cb4b16), "Cache" in cyan (#2aa198).
+_LM_STYLE = "\x1b[1;3;38;2;203;75;22m"
+_CACHE_STYLE = "\x1b[38;2;42;161;152m"
+_DIM_STYLE = "\x1b[2m"
+_RESET = "\x1b[0m"
+
+# Figlet "standard" font, split into the two color groups.
+_LM_ART = (
+    " _     __  __ ",
+    "| |   |  \\/  |",
+    "| |   | |\\/| |",
+    "| |___| |  | |",
+    "|_____|_|  |_|",
+)
+_CACHE_ART = (
+    "  ____           _          ",
+    " / ___|__ _  ___| |__   ___ ",
+    "| |   / _` |/ __| '_ \\ / _ \\",
+    "| |__| (_| | (__| | | |  __/",
+    " \\____\\__,_|\\___|_| |_|\\___|",
+)
+_RIGHT_TEXT_GAP = "     "
+
+_banner_printed = False
+
+
+def _banner_disabled() -> bool:
+    """Return whether ``LMCACHE_DISABLE_BANNER`` is set to a truthy value."""
+    return os.getenv(DISABLE_BANNER_ENV, "").strip().lower() in ("1", "true", "yes")
+
+
+def _render_banner(colored: bool) -> str:
+    """Render the banner text.
+
+    Args:
+        colored: Whether to wrap the logo in ANSI color escapes.
+
+    Returns:
+        The multi-line banner: the LMCache logo with the version (and
+        commit id when available), website, recipes, and LinkedIn links
+        on its right, and a final line describing the
+        ``LMCACHE_DISABLE_BANNER`` opt-out. A blank line surrounds the
+        banner on each side to set it apart from adjacent log output.
+    """
+    lm_style = _LM_STYLE if colored else ""
+    cache_style = _CACHE_STYLE if colored else ""
+    dim_style = _DIM_STYLE if colored else ""
+    reset = _RESET if colored else ""
+
+    version = f"LMCache v{_LMCACHE_VERSION}"
+    if _LMCACHE_COMMIT:
+        version += f" ({_LMCACHE_COMMIT[:9]})"
+    right_text = {
+        1: version,
+        2: f"Website:  {LMCACHE_WEBSITE}",
+        3: f"Recipes:  {LMCACHE_RECIPES}",
+        4: f"LinkedIn: {LMCACHE_LINKEDIN}",
+    }
+    lines = [""]
+    for row, (lm_part, cache_part) in enumerate(zip(_LM_ART, _CACHE_ART, strict=True)):
+        line = f"{lm_style}{lm_part}{reset} {cache_style}{cache_part}{reset}"
+        if row in right_text:
+            line += _RIGHT_TEXT_GAP + right_text[row]
+        lines.append(line)
+    lines.append(f"{dim_style}Set {DISABLE_BANNER_ENV}=1 to hide this banner.{reset}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def print_banner_once(stream: "TextIO") -> None:
+    """Print the LMCache startup banner to ``stream`` at most once.
+
+    The banner shows the LMCache logo, version, and website, followed by
+    a hint describing the ``LMCACHE_DISABLE_BANNER`` opt-out. ANSI colors
+    are used only when ``stream`` is a TTY. Subsequent calls in the same
+    process are no-ops, as are all calls when ``LMCACHE_DISABLE_BANNER``
+    is set to ``1``/``true``/``yes``.
+
+    Args:
+        stream: Destination text stream. Callers should pass
+            ``sys.stderr`` so the banner never interferes with
+            machine-readable stdout output.
+    """
+    global _banner_printed
+    if _banner_printed or _banner_disabled():
+        return
+    _banner_printed = True
+    stream.write(_render_banner(stream.isatty()) + "\n")
+    stream.flush()
diff --git a/lmcache/cli/__init__.py b/lmcache/cli/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/cli/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/cli/commands/__init__.py b/lmcache/cli/commands/__init__.py
new file mode 100644
index 0000000..e29e3f5
--- /dev/null
+++ b/lmcache/cli/commands/__init__.py
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CLI subcommand package.
+
+To add a new top-level command, simply create a new module (or sub-package
+with an ``__init__.py``) under this package that defines a concrete
+:class:`BaseCommand` subclass.  It will be discovered and registered
+automatically — no edits to this file are required.
+"""
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand, CompositeCommand
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+
+def _discover_commands() -> list[BaseCommand]:
+    """Scan direct submodules of this package and collect all concrete
+    :class:`BaseCommand` subclasses, returning one instance per class.
+
+    Import errors are intentionally re-raised: a broken CLI command
+    module should fail loudly rather than silently disappear from the
+    CLI.
+    """
+
+    def _raise(module_name: str, exc: Exception) -> None:
+        raise exc
+
+    return [
+        cls()
+        for cls in discover_subclasses(
+            __name__,
+            BaseCommand,  # type: ignore[type-abstract]
+            module_filter=lambda name: name != "base",
+            on_import_error=_raise,
+        )
+    ]
+
+
+ALL_COMMANDS: list[BaseCommand] = _discover_commands()
+
+__all__ = ["ALL_COMMANDS", "BaseCommand", "CompositeCommand"]
diff --git a/lmcache/cli/commands/base.py b/lmcache/cli/commands/base.py
new file mode 100644
index 0000000..65812d5
--- /dev/null
+++ b/lmcache/cli/commands/base.py
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract base class and shared helpers for CLI subcommands."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import abc
+import argparse
+import sys
+
+# First Party
+from lmcache.cli.metrics import (
+    FileHandler,
+    Metrics,
+    StreamHandler,
+    get_formatter,
+)
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class BaseCommand(abc.ABC):
+    """Abstract base class that all CLI subcommands must inherit from.
+
+    Subclasses must implement :meth:`name`, :meth:`help`,
+    :meth:`add_arguments`, and :meth:`execute`.  The :meth:`register`
+    method wires everything together automatically.
+
+    Example::
+
+        class PingCommand(BaseCommand):
+            def name(self) -> str:
+                return "ping"
+
+            def help(self) -> str:
+                return "Ping the KV cache server."
+
+            def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+                parser.add_argument("--url", required=True)
+
+            def execute(self, args: argparse.Namespace) -> None:
+                metrics = self.create_metrics("Ping Result", args)
+                metrics.add("status", "Status", "OK")
+                metrics.emit()
+    """
+
+    @abc.abstractmethod
+    def name(self) -> str:
+        """Return the subcommand name (e.g. ``"mock"``)."""
+
+    @abc.abstractmethod
+    def help(self) -> str:
+        """Return short help text shown by ``lmcache -h``."""
+
+    @abc.abstractmethod
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add command-specific arguments to *parser*.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+
+    @abc.abstractmethod
+    def execute(self, args: argparse.Namespace) -> None:
+        """Execute the subcommand.
+
+        Called by the CLI dispatcher in ``main.py`` via
+        ``args.func(args)`` after argument parsing.  The
+        :meth:`register` method binds this as the dispatch target
+        using ``parser.set_defaults(func=self.execute)``.
+
+        Args:
+            args: Parsed CLI arguments.
+        """
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        """Register this command with the CLI argument parser.
+
+        This method is not typically overridden.  It calls
+        :meth:`name`, :meth:`help`, and :meth:`add_arguments`, then
+        binds :meth:`execute` as the dispatch target.
+
+        Args:
+            subparsers: The subparsers action from the root parser.
+        """
+        parser = subparsers.add_parser(self.name(), help=self.help())
+        self.add_arguments(parser)
+        _add_output_args(parser)
+        parser.set_defaults(func=self.execute)
+
+    def create_metrics(
+        self,
+        title: str,
+        args: argparse.Namespace,
+        width: int = 48,
+    ) -> Metrics:
+        """Create a :class:`Metrics` with default handlers pre-registered.
+
+        Handlers are configured from ``args.format``, ``args.output``,
+        and ``args.quiet``:
+
+        * A :class:`StreamHandler` writing to stdout, unless ``--quiet``
+          is set. The formatter is determined by ``--format``
+          (default: ``terminal``).
+        * A :class:`FileHandler` if ``--output`` is set (uses the same
+          formatter chosen by ``--format``).
+
+        Args:
+            title: Report title.
+            args: Parsed CLI arguments (inspects ``format`` and ``output``).
+            width: Character width for terminal rendering (only used by
+                formatters that support it, e.g. ``TerminalFormatter``).
+
+        Returns:
+            A ready-to-use ``Metrics`` instance.
+        """
+        metrics = Metrics(title=title)
+
+        quiet = getattr(args, "quiet", False)
+        fmt_name = getattr(args, "format", None) or "terminal"
+        if not quiet:
+            metrics.add_handler(StreamHandler(get_formatter(fmt_name, width=width)))
+
+        output = getattr(args, "output", None)
+        if output:
+            metrics.add_handler(
+                FileHandler(output, get_formatter(fmt_name, width=width))
+            )
+
+        return metrics
+
+
+class CompositeCommand(BaseCommand):
+    """Base class for commands that contain auto-discovered sub-subcommands.
+
+    Subclasses only need to implement :meth:`name` and :meth:`help`.
+    Sub-subcommands are discovered automatically by scanning the package
+    for concrete :class:`BaseCommand` subclasses.
+
+    Example::
+
+        class QueryCommand(CompositeCommand):
+            def name(self) -> str:
+                return "query"
+
+            def help(self) -> str:
+                return "Run one inference request and report metrics."
+    """
+
+    def add_arguments(self, _parser: argparse.ArgumentParser) -> None:
+        """No top-level arguments; all args are registered by subcommands."""
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        """Register this command and auto-discover all sub-subcommands.
+
+        Scans the package where this class is defined for concrete
+        :class:`BaseCommand` subclasses and registers each one as a
+        nested subcommand.
+
+        Args:
+            subparsers: The subparsers action from the root parser.
+        """
+        # Deferred import to avoid circular dependency
+        # First Party
+        from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+        parser = subparsers.add_parser(
+            self.name(),
+            help=self.help(),
+            description=self.help(),
+        )
+        inner = parser.add_subparsers(
+            dest=f"{self.name()}_target",
+            required=True,
+        )
+
+        # Discover subcommands in the package where the concrete
+        # CompositeCommand subclass is defined. Exclude the module
+        # that defines the composite command itself (the __init__.py).
+        package = self.__class__.__module__
+
+        def _raise(module_name: str, exc: Exception) -> None:
+            raise exc
+
+        self._subcmds: dict[str, BaseCommand] = {}
+        for cls in discover_subclasses(
+            package,
+            BaseCommand,  # type: ignore[type-abstract]
+            module_filter=lambda name: not name.startswith("_"),
+            require_defined_in_module=True,
+            on_import_error=_raise,
+        ):
+            # Skip the composite command class itself
+            if cls is self.__class__:
+                continue
+            inst = cls()
+            self._subcmds[inst.name()] = inst
+            inst.register(inner)
+
+        logger.debug(
+            "CompositeCommand[%s] discovered subcommands: %s",
+            self.name(),
+            list(self._subcmds.keys()),
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        """Dispatch to the appropriate sub-subcommand.
+
+        Args:
+            args: Parsed CLI arguments.
+        """
+        target = getattr(args, f"{self.name()}_target", None)
+        subcmd = self._subcmds.get(target) if target else None
+        if subcmd is None:
+            print(
+                f"Unknown {self.name()} target: {target}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        subcmd.execute(args)
+
+
+def _add_output_args(parser: argparse.ArgumentParser) -> None:
+    """Add the common ``--format`` and ``--output`` flags.
+
+    Called automatically by :meth:`BaseCommand.register` — subcommands
+    do not need to call this themselves.
+
+    Args:
+        parser: The ``ArgumentParser`` to add the flags to.
+    """
+    parser.add_argument(
+        "--format",
+        type=str,
+        default=None,
+        metavar="FORMAT",
+        help=("Stdout output format (default: terminal). Available: terminal, json."),
+    )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        metavar="PATH",
+        help="Save metrics to a file at PATH (format chosen by --format).",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        default=False,
+        help="Suppress stdout output. Exit code only.",
+    )
diff --git a/lmcache/cli/commands/bench/__init__.py b/lmcache/cli/commands/bench/__init__.py
new file mode 100644
index 0000000..59c4bbc
--- /dev/null
+++ b/lmcache/cli/commands/bench/__init__.py
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench`` command — sustained performance benchmarking.
+
+Sub-subcommands are auto-discovered from sub-packages in this package.
+To add a new benchmark, create a sub-package with a concrete
+:class:`BaseCommand` subclass in its ``__init__.py`` — no edits to
+this file are required.
+"""
+
+# First Party
+from lmcache.cli.commands.base import CompositeCommand
+
+
+class BenchCommand(CompositeCommand):
+    """CLI command for sustained performance benchmarking."""
+
+    def name(self) -> str:
+        return "bench"
+
+    def help(self) -> str:
+        return "Run sustained performance benchmarks."
diff --git a/lmcache/cli/commands/bench/engine_bench/__init__.py b/lmcache/cli/commands/bench/engine_bench/__init__.py
new file mode 100644
index 0000000..405a86c
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/__init__.py
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench engine`` subpackage.
+
+Exposes :class:`EngineBenchCommand` for auto-discovery by
+:class:`~lmcache.cli.commands.base.CompositeCommand`.
+"""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class EngineBenchCommand(BaseCommand):
+    """Benchmark an inference engine."""
+
+    def name(self) -> str:
+        return "engine"
+
+    def help(self) -> str:
+        return "Benchmark an inference engine."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # First Party
+        from lmcache.cli.commands.bench.engine_bench.command import (
+            add_engine_arguments,
+        )
+
+        add_engine_arguments(parser)
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        """Register without the common output args (--format/--output).
+
+        The engine bench manages its own output lifecycle (CSV/JSON export,
+        --quiet) so the generic _add_output_args flags are not applicable
+        and would only clutter ``-h`` output.
+        """
+        parser = subparsers.add_parser(self.name(), help=self.help())
+        self.add_arguments(parser)
+        parser.set_defaults(func=self.execute)
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.cli.commands.bench.engine_bench.command import (
+            run_engine_bench,
+        )
+
+        run_engine_bench(self, args)
diff --git a/lmcache/cli/commands/bench/engine_bench/command.py b/lmcache/cli/commands/bench/engine_bench/command.py
new file mode 100644
index 0000000..6b20ed0
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/command.py
@@ -0,0 +1,617 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench engine`` subcommand implementation.
+
+This module provides argument registration via :func:`add_engine_arguments`
+and the execution orchestrator :func:`run_engine_bench` for the inference
+engine benchmark.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import argparse
+import os
+import sys
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.config import (
+    EngineBenchConfig,
+    parse_args_to_config,
+)
+from lmcache.cli.commands.bench.engine_bench.interactive import run_interactive
+from lmcache.cli.commands.bench.engine_bench.interactive.state import (
+    InteractiveState,
+)
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import (
+    RequestSender,
+)
+from lmcache.cli.commands.bench.engine_bench.stats import (
+    FinalStats,
+    StatsCollector,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads import (
+    create_workload,
+    validate_max_output_length_supported,
+)
+from lmcache.logging import init_logger
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.cli.commands.base import BaseCommand
+
+logger = init_logger(__name__)
+
+# Default for --ldqa-max-output-length; centralized so the "max output length
+# explicitly set" check stays in sync with the parser.
+_LDQA_MAX_OUTPUT_LENGTH_DEFAULT = 128
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+
+def add_engine_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add ``lmcache bench engine`` arguments to *parser*.
+
+    Args:
+        parser: The ``ArgumentParser`` for the engine bench subcommand.
+    """
+
+    # --- Config file ---
+    parser.add_argument(
+        "--config",
+        default=None,
+        metavar="FILE",
+        help="Load configuration from a JSON file (skips interactive mode).",
+    )
+
+    # --- General args ---
+    parser.add_argument(
+        "--engine-url",
+        default=None,
+        help=(
+            "Inference engine URL (e.g., http://localhost:8000). "
+            "Set OPENAI_API_KEY env var if authentication is needed."
+        ),
+    )
+    parser.add_argument(
+        "--lmcache-url",
+        default=None,
+        help="LMCache MP server URL for auto-detecting tokens per GB.",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        help="Model name (auto-detected from engine if omitted).",
+    )
+    parser.add_argument(
+        "--workload",
+        default=None,
+        choices=[
+            "long-doc-permutator",
+            "long-doc-qa",
+            "multi-round-chat",
+            "prefix-suffix-tuner",
+            "random-prefill",
+        ],
+        help="Workload type.",
+    )
+    parser.add_argument(
+        "--kv-cache-volume",
+        type=float,
+        default=100.0,
+        help="Target active KV cache in GB (default: 100).",
+    )
+    parser.add_argument(
+        "--tokens-per-gb-kvcache",
+        type=int,
+        default=None,
+        help=("Tokens per GB of KV cache (required if --lmcache-url is not set)."),
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=42,
+        help="Random seed (default: 42).",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help="Directory for output files (default: current).",
+    )
+    parser.add_argument(
+        "--no-csv",
+        action="store_true",
+        help="Skip CSV export.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Export JSON summary.",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Suppress real-time progress display.",
+    )
+    parser.add_argument(
+        "--ignore-eos",
+        action="store_true",
+        help=(
+            "Force generation to run for the full output length by ignoring "
+            "the model's EOS token (vLLM sampling extension). Makes decode "
+            "throughput reproducible regardless of when the model would stop."
+        ),
+    )
+    parser.add_argument(
+        "--no-interactive",
+        action="store_true",
+        help=("Disable interactive mode. Errors if required arguments are missing."),
+    )
+    parser.add_argument(
+        "--export-config",
+        default=None,
+        metavar="FILE",
+        help=(
+            "Export resolved configuration to a JSON file and exit. "
+            "Does not run the benchmark or enter interactive mode."
+        ),
+    )
+
+    # --- Long-doc-permutator workload args ---
+    ldp_group = parser.add_argument_group("long-doc-permutator workload options")
+    ldp_group.add_argument(
+        "--ldp-num-contexts",
+        type=int,
+        default=5,
+        help="Number of unique context documents (default: 5).",
+    )
+    ldp_group.add_argument(
+        "--ldp-context-length",
+        type=int,
+        default=5000,
+        help="Token length of each context (default: 5000).",
+    )
+    ldp_group.add_argument(
+        "--ldp-system-prompt-length",
+        type=int,
+        default=1000,
+        help="Token length of the shared system prompt (default: 1000). "
+        "Use 0 for no system prompt.",
+    )
+    ldp_group.add_argument(
+        "--ldp-num-permutations",
+        type=int,
+        default=10,
+        help="Number of distinct permutations to send (default: 10). "
+        "Capped at N! where N = --ldp-num-contexts.",
+    )
+    ldp_group.add_argument(
+        "--ldp-num-inflight-requests",
+        type=int,
+        default=1,
+        help="Max concurrent in-flight requests (default: 1).",
+    )
+
+    # --- Long-doc-qa workload args ---
+    group = parser.add_argument_group("long-doc-qa workload options")
+    group.add_argument(
+        "--ldqa-document-length",
+        type=int,
+        default=10000,
+        help="Token length per document (default: 10000).",
+    )
+    group.add_argument(
+        "--ldqa-query-per-document",
+        type=int,
+        default=2,
+        help="Questions per document (default: 2).",
+    )
+    group.add_argument(
+        "--ldqa-shuffle-policy",
+        default="random",
+        choices=["random", "tile"],
+        help="Request ordering (default: random).",
+    )
+    group.add_argument(
+        "--ldqa-num-inflight-requests",
+        type=int,
+        default=3,
+        help="Max concurrent in-flight requests (default: 3).",
+    )
+    group.add_argument(
+        "--ldqa-max-output-length",
+        type=int,
+        default=_LDQA_MAX_OUTPUT_LENGTH_DEFAULT,
+        help=(
+            f"Max tokens to generate per benchmark query "
+            f"(default: {_LDQA_MAX_OUTPUT_LENGTH_DEFAULT}). Combine with "
+            "--ignore-eos for a reproducible decode phase."
+        ),
+    )
+
+    # --- Multi-round-chat workload args ---
+    mrc_group = parser.add_argument_group(
+        "multi-round-chat workload options",
+    )
+    mrc_group.add_argument(
+        "--mrc-shared-prompt-length",
+        type=int,
+        default=2000,
+        help="System prompt token length (default: 2000).",
+    )
+    mrc_group.add_argument(
+        "--mrc-chat-history-length",
+        type=int,
+        default=10000,
+        help="Pre-filled chat history token length (default: 10000).",
+    )
+    mrc_group.add_argument(
+        "--mrc-user-input-length",
+        type=int,
+        default=50,
+        help="Tokens per user query (default: 50).",
+    )
+    mrc_group.add_argument(
+        "--mrc-output-length",
+        type=int,
+        default=200,
+        help="Max tokens to generate per response (default: 200).",
+    )
+    mrc_group.add_argument(
+        "--mrc-qps",
+        type=float,
+        default=1.0,
+        help="Queries per second (default: 1.0).",
+    )
+    mrc_group.add_argument(
+        "--mrc-duration",
+        type=float,
+        default=60.0,
+        help="Benchmark duration in seconds (default: 60).",
+    )
+
+    # --- Prefix-suffix-tuner workload args ---
+    psf_group = parser.add_argument_group(
+        "prefix-suffix-tuner workload options",
+    )
+    psf_group.add_argument(
+        "--psf-context-length",
+        type=int,
+        default=8000,
+        help="Total tokens per request (prefix + breaker + suffix) (default: 8000).",
+    )
+    psf_group.add_argument(
+        "--psf-prefix-ratio",
+        type=float,
+        default=0.8,
+        help="Fraction of context-length used by the prefix (default: 0.8). "
+        "Must be in (0.0, 1.0). The remainder (minus a 32-token breaker) is "
+        "the shared suffix.",
+    )
+    psf_group.add_argument(
+        "--psf-thrash",
+        type=float,
+        default=20.0,
+        help="Size in GB of the KV-cache tier to overflow (default: 20.0). "
+        "The workload sizes its prefix pool to slightly more than this, "
+        "so every pass-2 request misses that tier and falls through to "
+        "the next one. Use the L0 (HBM) size for vanilla vLLM baselines, "
+        "or the L1 (LMCache DRAM) size for tiered baselines.",
+    )
+
+    # --- Random-prefill workload args ---
+    rp_group = parser.add_argument_group(
+        "random-prefill workload options",
+    )
+    rp_group.add_argument(
+        "--rp-request-length",
+        type=int,
+        default=10000,
+        help="Token length per request (default: 10000).",
+    )
+    rp_group.add_argument(
+        "--rp-num-requests",
+        type=int,
+        default=50,
+        help="Number of requests to send (default: 50).",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Argument resolution helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_missing_args(args: argparse.Namespace) -> list[str]:
+    """Return list of missing required CLI flags."""
+    missing: list[str] = []
+    if args.engine_url is None:
+        missing.append("--engine-url")
+    if args.workload is None:
+        missing.append("--workload")
+    if (
+        args.tokens_per_gb_kvcache is None
+        and getattr(args, "lmcache_url", None) is None
+    ):
+        missing.append("--tokens-per-gb-kvcache or --lmcache-url")
+    return missing
+
+
+def _needs_interactive(args: argparse.Namespace) -> bool:
+    """Check whether interactive mode should be triggered."""
+    if getattr(args, "config", None):
+        return False
+    return len(_get_missing_args(args)) > 0
+
+
+def _resolve_args(args: argparse.Namespace) -> argparse.Namespace:
+    """Resolve args via config file, interactive mode, or pass through."""
+    # Case 1: --config file
+    config_path = getattr(args, "config", None)
+    if config_path:
+        state = InteractiveState.load_json(config_path)
+        state.merge_cli_args(args)
+        resolved = state.to_namespace()
+        # Carry over output flags from CLI
+        for attr in (
+            "output_dir",
+            "seed",
+            "no_csv",
+            "json",
+            "quiet",
+            "format",
+            "output",
+        ):
+            cli_val = getattr(args, attr, None)
+            if cli_val is not None:
+                setattr(resolved, attr, cli_val)
+        return resolved
+
+    # Case 2: --no-interactive or --export-config — error if missing
+    no_interactive = getattr(args, "no_interactive", False)
+    export_config = getattr(args, "export_config", None)
+    if no_interactive or export_config:
+        missing = _get_missing_args(args)
+        if missing:
+            flag = "--export-config" if export_config else "--no-interactive"
+            raise SystemExit(
+                "Missing required arguments: "
+                + ", ".join(missing)
+                + f". Provide them or remove {flag} "
+                "for guided setup."
+            )
+        return args
+
+    # Case 3: Interactive mode
+    if _needs_interactive(args):
+        return run_interactive(args)
+
+    # Case 4: All required args present — run directly
+    return args
+
+
+def _export_config(
+    config: EngineBenchConfig,
+    args: argparse.Namespace,
+    path: str,
+) -> None:
+    """Export resolved config to JSON and exit.
+
+    Builds a standalone config dict from the resolved
+    ``EngineBenchConfig`` and workload-specific CLI args.
+    Environment-specific keys (``engine_url``, ``lmcache_url``)
+    are excluded by ``InteractiveState.to_json()`` so the exported
+    config is portable.
+    """
+    # Standard
+    import json as json_mod
+
+    state = InteractiveState()
+    state.set("engine_url", config.engine_url)
+    state.set("model", config.model)
+    state.set("workload", config.workload)
+    state.set("kv_cache_volume", config.kv_cache_volume_gb)
+    state.set("tokens_per_gb_kvcache", config.tokens_per_gb_kvcache)
+    state.set("ignore_eos", config.ignore_eos)
+
+    # Workload-specific args from namespace
+    for item in state.get_workload_items():
+        value = getattr(args, item.key, item.default)
+        if value is not None:
+            state.set(item.key, value)
+
+    # to_json() handles filtering out engine_url, lmcache_url, etc.
+    data = state.to_json()
+
+    with open(path, "w") as f:
+        json_mod.dump(data, f, indent=2)
+        f.write("\n")
+
+    print(f"Configuration exported to {path}")
+    print(
+        f"\033[1mReplay with:\033[0m \033[96mlmcache bench engine "
+        f"--engine-url <URL> --config {path}\033[0m"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Final metrics emission
+# ---------------------------------------------------------------------------
+
+
+def _emit_final_metrics(
+    command: "BaseCommand",
+    config: EngineBenchConfig,
+    final: FinalStats,
+    args: argparse.Namespace,
+) -> None:
+    """Emit final benchmark summary using the CLI metrics system."""
+    title = f"Engine Benchmark Result ({config.workload})"
+    metrics = command.create_metrics(title, args, width=56)
+
+    cfg_section = metrics.add_section("config", "Configuration")
+    cfg_section.add("engine_url", "Engine URL", config.engine_url)
+    cfg_section.add("model", "Model", config.model)
+    cfg_section.add("workload", "Workload", config.workload)
+
+    results = metrics.add_section("results", "Results")
+    results.add(
+        "successful",
+        "Successful requests",
+        final.successful_requests,
+    )
+    results.add("failed", "Failed requests", final.failed_requests)
+    results.add(
+        "duration",
+        "Benchmark duration (s)",
+        round(final.elapsed_time, 2),
+    )
+    results.add(
+        "input_tokens",
+        "Total input tokens",
+        final.total_input_tokens,
+    )
+    results.add(
+        "output_tokens",
+        "Total output tokens",
+        final.total_output_tokens,
+    )
+    results.add(
+        "input_tput",
+        "Input throughput (tok/s)",
+        round(final.input_throughput, 2),
+    )
+    results.add(
+        "output_tput",
+        "Output throughput (tok/s)",
+        round(final.output_throughput, 2),
+    )
+
+    ttft = metrics.add_section("ttft", "Time to First Token")
+    ttft.add("mean", "Mean TTFT (ms)", round(final.mean_ttft_ms, 2))
+    ttft.add("p50", "P50 TTFT (ms)", round(final.p50_ttft_ms, 2))
+    ttft.add("p90", "P90 TTFT (ms)", round(final.p90_ttft_ms, 2))
+    ttft.add("p99", "P99 TTFT (ms)", round(final.p99_ttft_ms, 2))
+
+    decode = metrics.add_section("decode", "Decoding Speed")
+    decode.add(
+        "mean",
+        "Mean decode (tok/s)",
+        round(final.mean_decode_speed, 2),
+    )
+    decode.add(
+        "p99",
+        "P99 decode (tok/s)",
+        round(final.p99_decode_speed, 2),
+    )
+
+    metrics.emit()
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def run_engine_bench(command: "BaseCommand", args: argparse.Namespace) -> None:
+    """Centralized orchestrator: create all modules and run the engine bench.
+
+    Args:
+        command: The outer ``BenchCommand`` instance, used for
+            ``create_metrics`` (inherited from ``BaseCommand``).
+        args: Parsed CLI arguments for ``lmcache bench engine``.
+    """
+    # 0. Resolve args (config file / interactive / pass-through)
+    args = _resolve_args(args)
+
+    # 1. Parse config
+    config = parse_args_to_config(args)
+
+    # 1a. A max output length can only be set for workloads that have a
+    # max-output-length parameter; reject it for any other workload.
+    if args.ldqa_max_output_length != _LDQA_MAX_OUTPUT_LENGTH_DEFAULT:
+        validate_max_output_length_supported(config.workload)
+
+    # 1b. --export-config: save resolved config and exit
+    export_path = getattr(args, "export_config", None)
+    if export_path:
+        _export_config(config, args, export_path)
+        return
+
+    logger.info(
+        "Benchmark config: workload=%s, model=%s, kv_cache=%.1f GB, tokens_per_gb=%d",
+        config.workload,
+        config.model,
+        config.kv_cache_volume_gb,
+        config.tokens_per_gb_kvcache,
+    )
+
+    # 2. Create shared modules
+    stats_collector = StatsCollector()
+    progress_monitor = ProgressMonitor(
+        stats_collector,
+        quiet=config.quiet,
+    )
+
+    # 3. Create request sender (callbacks wired after workload creation)
+    request_sender = RequestSender(
+        config.engine_url,
+        config.model,
+        ignore_eos=config.ignore_eos,
+    )
+
+    # 4. Create workload
+    workload = create_workload(
+        config,
+        args,
+        request_sender,
+        stats_collector,
+        progress_monitor,
+    )
+
+    # 5. Wire callbacks on sender
+    request_sender.add_on_finished_callback(
+        lambda result, _text: stats_collector.on_request_finished(result),
+    )
+    request_sender.add_on_finished_callback(
+        lambda result, _text: progress_monitor.on_request_finished(
+            result.request_id,
+            result.successful,
+        ),
+    )
+    request_sender.add_on_finished_callback(workload.request_finished)
+
+    # 6. Log config and run benchmark
+    workload.log_config()
+    progress_monitor.start()
+    try:
+        workload.run()
+    finally:
+        progress_monitor.stop()
+
+    # 7. Final metrics
+    final = stats_collector.get_final_stats()
+    _emit_final_metrics(command, config, final, args)
+
+    # 8. Export
+    if config.export_csv:
+        csv_path = os.path.join(config.output_dir, "bench_results.csv")
+        stats_collector.export_csv(csv_path)
+        logger.info("CSV results written to %s", csv_path)
+    if config.export_json:
+        json_path = os.path.join(
+            config.output_dir,
+            "bench_summary.json",
+        )
+        stats_collector.export_json(json_path, config)
+        logger.info("JSON summary written to %s", json_path)
+
+    # 9. Exit code
+    if final.failed_requests > 0:
+        sys.exit(1)
diff --git a/lmcache/cli/commands/bench/engine_bench/config.py b/lmcache/cli/commands/bench/engine_bench/config.py
new file mode 100644
index 0000000..c27e535
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/config.py
@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Configuration dataclasses and CLI-arg parsing for ``lmcache bench engine``."""
+
+# Standard
+from dataclasses import dataclass
+import argparse
+import json
+import os
+import urllib.error
+import urllib.request
+
+# Third Party
+from openai import OpenAI
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+_GB = 1024**3
+
+
+@dataclass
+class EngineBenchConfig:
+    """Top-level config produced from CLI args, interactive mode, or saved config.
+
+    Contains only general benchmark parameters. Workload-specific configs
+    (e.g., ``LongDocQAConfig``) live in their respective workload modules
+    and are resolved by the workload factory.
+    """
+
+    engine_url: str
+    model: str
+    workload: str
+    kv_cache_volume_gb: float
+    tokens_per_gb_kvcache: int
+    seed: int
+    output_dir: str
+    export_csv: bool
+    export_json: bool
+    quiet: bool
+    ignore_eos: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.engine_url:
+            raise ValueError("engine_url must be non-empty")
+        if self.kv_cache_volume_gb <= 0:
+            raise ValueError(
+                f"kv_cache_volume_gb must be positive, got {self.kv_cache_volume_gb}"
+            )
+        if self.tokens_per_gb_kvcache <= 0:
+            raise ValueError(
+                f"tokens_per_gb_kvcache must be positive, "
+                f"got {self.tokens_per_gb_kvcache}"
+            )
+
+
+def auto_detect_model(engine_url: str) -> str:
+    """Fetch the first model ID from the engine's ``/v1/models`` endpoint.
+
+    Args:
+        engine_url: Base URL of the inference engine (e.g.,
+            ``http://localhost:8000``).
+
+    Returns:
+        The model ID string.
+
+    Raises:
+        RuntimeError: If the engine is unreachable or returns no models.
+    """
+    base_url = engine_url.rstrip("/")
+    if not base_url.startswith(("http://", "https://")):
+        base_url = f"http://{base_url}"
+    if not base_url.endswith("/v1"):
+        base_url += "/v1"
+
+    api_key = os.getenv("OPENAI_API_KEY", "sk-dummy")
+    logger.debug("Auto-detecting model from %s/models", base_url)
+
+    try:
+        client = OpenAI(base_url=base_url, api_key=api_key)
+        models = client.models.list()
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch models from {base_url}/models: {e}") from e
+
+    if not models.data:
+        raise RuntimeError(
+            f"No models returned by {base_url}/models; pass --model explicitly."
+        )
+
+    model_id = models.data[0].id
+    logger.debug("Auto-detected model: %s", model_id)
+    return model_id
+
+
+def _fetch_lmcache_status(lmcache_url: str) -> dict:
+    """Fetch ``/status`` from the LMCache HTTP server.
+
+    Returns:
+        Parsed JSON response.
+
+    Raises:
+        RuntimeError: If the server is unreachable.
+    """
+    url = lmcache_url.rstrip("/")
+    if not url.startswith(("http://", "https://")):
+        url = f"http://{url}"
+    status_url = f"{url}/status"
+
+    logger.debug("Fetching LMCache status from %s", status_url)
+
+    try:
+        req = urllib.request.Request(status_url)
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return json.loads(resp.read().decode())
+    except (urllib.error.URLError, OSError) as e:
+        raise RuntimeError(
+            f"Cannot connect to LMCache server at {status_url}: {e}"
+        ) from e
+
+
+def _find_model_meta(
+    gpu_meta: dict,
+    model_name: str,
+) -> dict:
+    """Find the GPU metadata entry matching *model_name*.
+
+    Args:
+        gpu_meta: The ``cache_context_meta`` dict from ``/status``.
+        model_name: Model name to match.
+
+    Returns:
+        The matching GPU metadata dict.
+
+    Raises:
+        RuntimeError: If no entry matches *model_name*.
+    """
+    for meta in gpu_meta.values():
+        if meta.get("model_name") == model_name:
+            return meta
+
+    available = sorted({m.get("model_name", "?") for m in gpu_meta.values()})
+    raise RuntimeError(
+        f"Model {model_name!r} not found on LMCache server. "
+        f"Available: {', '.join(available)}"
+    )
+
+
+def resolve_tokens_per_gb(lmcache_url: str, model_name: str) -> int:
+    """Query the LMCache server and compute tokens per GB of KV cache.
+
+    Fetches ``/status``, finds the model entry matching
+    *model_name*, and computes::
+
+        global_bytes_per_token = cache_size_per_token * world_size
+        tokens_per_gb = (1024**3) // global_bytes_per_token
+
+    ``cache_size_per_token`` is rank-local, so it must be multiplied
+    by ``world_size`` for tensor-parallel models.
+
+    Args:
+        lmcache_url: URL of the LMCache HTTP server.
+        model_name: Model name to look up (must match a model served
+            by the LMCache server).
+
+    Returns:
+        tokens_per_gb_kvcache value.
+
+    Raises:
+        RuntimeError: If the server is unreachable, the model is not
+            found, or the layout is missing required fields.
+    """
+    data = _fetch_lmcache_status(lmcache_url)
+
+    gpu_meta = data.get("cache_context_meta", {})
+    if not gpu_meta:
+        # CB-only deployments (engine_type="blend") populate
+        # cb_gpu_context_meta instead of cache_context_meta.
+        gpu_meta = data.get("cb_gpu_context_meta", {})
+    if not gpu_meta:
+        raise RuntimeError(
+            "No model info returned by LMCache server; "
+            "is the server running with a model loaded?"
+        )
+
+    meta = _find_model_meta(gpu_meta, model_name)
+    layout = meta.get("kv_cache_layout")
+    if not layout:
+        raise RuntimeError(f"No kv_cache_layout for model {model_name!r}")
+
+    cache_size_per_token = layout.get("cache_size_per_token")
+    if cache_size_per_token is None:
+        raise RuntimeError(
+            f"cache_size_per_token not available for model "
+            f"{model_name!r}; is the LMCache server up to date?"
+        )
+
+    world_size = meta.get("world_size", 1)
+    global_bytes_per_token = cache_size_per_token * world_size
+    tokens_per_gb = _GB // global_bytes_per_token
+
+    logger.info(
+        "Resolved from LMCache: model=%s, "
+        "cache_size_per_token=%d bytes (rank-local), "
+        "world_size=%d -> %d bytes/token (global) -> %d tokens/GB",
+        model_name,
+        cache_size_per_token,
+        world_size,
+        global_bytes_per_token,
+        tokens_per_gb,
+    )
+    return tokens_per_gb
+
+
+def parse_args_to_config(args: argparse.Namespace) -> EngineBenchConfig:
+    """Convert parsed CLI arguments into a fully-resolved EngineBenchConfig.
+
+    Handles model auto-detection and tokens-per-GB resolution from the
+    LMCache server when ``--lmcache-url`` is provided.
+
+    Args:
+        args: Parsed argparse Namespace from the bench engine subcommand.
+
+    Returns:
+        A fully-resolved EngineBenchConfig.
+    """
+    model = args.model if args.model else auto_detect_model(args.engine_url)
+
+    tokens_per_gb = args.tokens_per_gb_kvcache
+    if tokens_per_gb is None:
+        lmcache_url = getattr(args, "lmcache_url", None)
+        if lmcache_url is not None:
+            tokens_per_gb = resolve_tokens_per_gb(lmcache_url, model)
+        else:
+            raise ValueError(
+                "--tokens-per-gb-kvcache is required when --lmcache-url is not set"
+            )
+
+    return EngineBenchConfig(
+        engine_url=args.engine_url,
+        model=model,
+        workload=args.workload,
+        kv_cache_volume_gb=args.kv_cache_volume,
+        tokens_per_gb_kvcache=tokens_per_gb,
+        seed=args.seed,
+        output_dir=args.output_dir,
+        export_csv=not args.no_csv,
+        export_json=args.json,
+        quiet=args.quiet,
+        ignore_eos=args.ignore_eos,
+    )
diff --git a/lmcache/cli/commands/bench/engine_bench/interactive/__init__.py b/lmcache/cli/commands/bench/engine_bench/interactive/__init__.py
new file mode 100644
index 0000000..291bf38
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/interactive/__init__.py
@@ -0,0 +1,381 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Interactive configuration flow for ``lmcache bench engine``.
+
+Entry point: ``run_interactive(args)`` — walks the user through
+missing configuration, offers gates for optional settings, and
+returns a complete ``argparse.Namespace`` ready for the orchestrator.
+"""
+
+# Standard
+from typing import cast
+import argparse
+import sys
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.interactive.schema import (
+    ConfigItem,
+)
+from lmcache.cli.commands.bench.engine_bench.interactive.state import (
+    InteractiveState,
+)
+from lmcache.cli.commands.bench.engine_bench.interactive.terminal import (
+    BOLD,
+    CYAN,
+    GO_BACK,
+    RESET,
+    YELLOW,
+    prompt_bool,
+    prompt_choice,
+    prompt_number,
+    prompt_text,
+)
+
+__all__ = ["run_interactive"]
+
+
+# Config items whose text input is a URL and accepts port/host shorthand.
+_URL_KEYS = {"engine_url", "lmcache_url"}
+
+
+def _normalize_url(value: str) -> str:
+    """Expand shorthand URL input into a fully-qualified URL.
+
+    A bare port (``8000``) becomes ``http://localhost:8000``; a bare host or
+    ``host:port`` (``localhost:8000``) gains an ``http://`` scheme.  Values
+    that already carry a scheme (``://``) and the empty string are returned
+    unchanged.
+    """
+    value = value.strip()
+    if not value or "://" in value:
+        return value
+    if value.isdigit():
+        return f"http://localhost:{value}"
+    return f"http://{value}"
+
+
+# ---------------------------------------------------------------------------
+# Prompt dispatcher
+# ---------------------------------------------------------------------------
+
+
+def _prompt_for_item(item: ConfigItem, allow_back: bool) -> object:
+    """Prompt the user for a single config item based on its type.
+
+    Returns the entered value, or :data:`GO_BACK` when ``allow_back`` is True
+    and the user asks to step back to the previous question.
+    """
+    if item.input_type == "text":
+        return prompt_text(
+            item.display_name,
+            item.description,
+            default=item.default if item.default is not None else "",
+            allow_back=allow_back,
+        )
+    if item.input_type == "int":
+        return prompt_number(
+            item.display_name,
+            item.description,
+            default=item.default,
+            number_type=int,
+            allow_back=allow_back,
+        )
+    if item.input_type == "float":
+        return prompt_number(
+            item.display_name,
+            item.description,
+            default=item.default,
+            number_type=float,
+            allow_back=allow_back,
+        )
+    if item.input_type == "bool":
+        return prompt_bool(
+            item.display_name,
+            item.description,
+            default=bool(item.default) if item.default is not None else True,
+            allow_back=allow_back,
+        )
+    if item.input_type == "choice":
+        return prompt_choice(
+            item.display_name,
+            item.description,
+            choices=item.choices,
+            default=item.default if item.default is not None else "",
+            allow_back=allow_back,
+        )
+    raise ValueError(f"Unknown input_type {item.input_type!r} for {item.key}")
+
+
+# ---------------------------------------------------------------------------
+# Gate prompt
+# ---------------------------------------------------------------------------
+
+
+def _prompt_gate(section_name: str, detail: str, allow_back: bool) -> object:
+    """Ask the user whether to configure a section or skip with defaults.
+
+    Returns ``"configure"``, ``"use defaults"``, or :data:`GO_BACK`.
+    """
+    return prompt_choice(
+        section_name,
+        f"Would you like to configure {detail}?\n  Defaults will be used if you skip.",
+        choices=[
+            ("use defaults", "Skip, use defaults"),
+            ("configure", "Yes, configure"),
+        ],
+        default="use defaults",
+        allow_back=allow_back,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+
+def _print_summary(state: InteractiveState) -> None:
+    """Print a formatted configuration summary."""
+    print()
+    print(f"{BOLD}{'─' * 50}{RESET}")
+    print(f"{BOLD} Configuration Summary{RESET}")
+    print(f"{BOLD}{'─' * 50}{RESET}")
+    for label, value in state.summary_lines():
+        padding = max(0, 26 - len(label))
+        print(f"  {label}:{' ' * padding}{CYAN}{value}{RESET}")
+    print(f"{BOLD}{'─' * 50}{RESET}")
+
+
+# ---------------------------------------------------------------------------
+# Action prompt
+# ---------------------------------------------------------------------------
+
+
+def _prompt_action(allow_back: bool) -> object:
+    """Ask the user to start the benchmark, export config, or quit.
+
+    Returns ``"start"``, ``"export"``, ``"quit"``, or :data:`GO_BACK`.
+    """
+    return prompt_choice(
+        "What would you like to do?",
+        "",
+        choices=[
+            ("start", "Start benchmark"),
+            ("export", "Export configuration for later use and exit"),
+            ("quit", "Quit without running"),
+        ],
+        default="start",
+        allow_back=allow_back,
+    )
+
+
+def _resolve_before_export(state: InteractiveState) -> None:
+    """Resolve tokens_per_gb_kvcache and model before exporting.
+
+    If the user provided an LMCache URL, query the server to get
+    ``tokens_per_gb_kvcache`` so the exported config is standalone.
+    If the model is empty and an engine URL is available, auto-detect it.
+    """
+    # First Party
+    from lmcache.cli.commands.bench.engine_bench.config import (
+        auto_detect_model,
+        resolve_tokens_per_gb,
+    )
+
+    engine_url = state.get("engine_url", "")
+    model = state.get("model", "")
+
+    # Auto-detect model if empty
+    if not model and engine_url:
+        try:
+            model = auto_detect_model(engine_url)
+            state.set("model", model)
+        except RuntimeError as e:
+            print(f"  {YELLOW}Warning: could not auto-detect model: {e}{RESET}")
+
+    # Resolve tokens_per_gb from LMCache if needed
+    lmcache_url = state.get("lmcache_url", "")
+    if lmcache_url and not state.is_set("tokens_per_gb_kvcache"):
+        try:
+            tokens = resolve_tokens_per_gb(lmcache_url, model)
+            state.set("tokens_per_gb_kvcache", tokens)
+        except RuntimeError as e:
+            print(
+                f"  {YELLOW}Warning: could not resolve "
+                f"tokens_per_gb from LMCache: {e}{RESET}"
+            )
+
+
+def _handle_export(state: InteractiveState) -> None:
+    """Prompt for filename, resolve values, save JSON, and exit."""
+    _resolve_before_export(state)
+    # No allow_back here, so the return is always a plain string.
+    filename = cast(
+        str,
+        prompt_text(
+            "Export filename",
+            "",
+            default="bench_config.json",
+        ),
+    )
+    state.save_json(filename)
+    print()
+    print(f"  {CYAN}Saved to {filename}{RESET}")
+    print(
+        f"  {BOLD}Replay with:{RESET} "
+        f"{CYAN}lmcache bench engine "
+        f"--engine-url <URL> --config {filename}{RESET}"
+    )
+    print()
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+# Heading text for each section gate, keyed by section name.
+_GATE_TEXT = {
+    "general": ("General settings", "general settings (model, KV cache volume, etc.)"),
+}
+
+
+def _next_question(
+    state: InteractiveState, gates: dict[str, str]
+) -> ConfigItem | str | None:
+    """Determine the next question to ask.
+
+    Returns a ``ConfigItem`` to prompt for a value, a section name
+    (``"general"`` / ``"workload"``) to prompt the section gate, or None when
+    configuration is complete.  The result is derived purely from current
+    state plus the gate decisions already made, so stepping back (which
+    un-sets the most recent answer) naturally re-presents the question that
+    produced it.
+    """
+    missing = state.get_missing_required()
+    if missing:
+        return missing[0]
+
+    if state.has_unconfigured_general() and "general" not in gates:
+        return "general"
+    if gates.get("general") == "configure":
+        general = state.get_general_items()
+        if general:
+            return general[0]
+
+    workload = [i for i in state.get_workload_items() if not state.is_set(i.key)]
+    if workload and "workload" not in gates:
+        return "workload"
+    if gates.get("workload") == "configure" and workload:
+        return workload[0]
+
+    return None
+
+
+def _gate_text(section: str, state: InteractiveState) -> tuple[str, str]:
+    """Return the ``(section_name, detail)`` heading for a gate prompt."""
+    if section == "workload":
+        return (
+            f"Workload settings ({state.get('workload', 'workload')})",
+            "workload-specific settings",
+        )
+    return _GATE_TEXT[section]
+
+
+def _gather_config(state: InteractiveState) -> bool:
+    """Drive the question loop until the user starts, exports, or quits.
+
+    Walks required items, the general/workload gates, and the summary, while
+    letting the user step back to revise any earlier answer.  Gate decisions
+    are tracked outside ``state`` so they never leak into the exported config.
+
+    Returns True to start the benchmark, False to quit.  Exits the process
+    directly on export.
+    """
+    gates: dict[str, str] = {}
+    # Trail of committed answers, for stepping back.  Item keys are stored as
+    # the key itself; gate decisions as ``"gate:<section>"``.
+    trail: list[str] = []
+
+    def step_back() -> None:
+        marker = trail.pop()
+        if marker.startswith("gate:"):
+            gates.pop(marker[len("gate:") :], None)
+        else:
+            state.unset(marker)
+
+    while True:
+        question = _next_question(state, gates)
+
+        if question is None:
+            _print_summary(state)
+            action = _prompt_action(allow_back=bool(trail))
+            if action is GO_BACK:
+                step_back()
+                continue
+            if action == "export":
+                _handle_export(state)  # exits
+            return action == "start"
+
+        if isinstance(question, ConfigItem):
+            value = _prompt_for_item(question, allow_back=bool(trail))
+            if value is GO_BACK:
+                step_back()
+                continue
+            if question.key in _URL_KEYS and isinstance(value, str):
+                value = _normalize_url(value)
+            state.set(question.key, value)
+            trail.append(question.key)
+        else:
+            name, detail = _gate_text(question, state)
+            choice = _prompt_gate(name, detail, allow_back=bool(trail))
+            if choice is GO_BACK:
+                step_back()
+                continue
+            gates[question] = str(choice)
+            trail.append(f"gate:{question}")
+
+
+def run_interactive(args: argparse.Namespace) -> argparse.Namespace:
+    """Run the interactive configuration flow.
+
+    Walks the user through missing required items, offers gates for
+    general and workload-specific settings, shows a summary, and
+    returns a complete ``argparse.Namespace``.  At any prompt the user can
+    step back to the previous question (``<``) or exit (Ctrl-C / Ctrl-D, or
+    the Quit action).
+
+    Args:
+        args: Partially-populated CLI args (some may be None).
+
+    Returns:
+        A fully-populated ``argparse.Namespace`` ready for the
+        benchmark orchestrator.
+    """
+    state = InteractiveState.from_cli_args(args)
+
+    print()
+    print(f"{BOLD}{'═' * 50}{RESET}")
+    print(f"{BOLD} lmcache bench engine — Interactive Setup{RESET}")
+    print(f"{BOLD}{'═' * 50}{RESET}")
+    print(f"  {YELLOW}Type < to go back · Ctrl-C to exit{RESET}")
+
+    try:
+        start = _gather_config(state)
+    except (KeyboardInterrupt, EOFError):
+        print()
+        print(f"  {YELLOW}Setup cancelled.{RESET}")
+        sys.exit(0)
+
+    if not start:
+        print()
+        print(f"  {YELLOW}Quit without running.{RESET}")
+        sys.exit(0)
+
+    # Carry over output settings from original CLI args
+    ns = state.to_namespace()
+    for attr in ("output_dir", "seed", "no_csv", "json", "quiet", "format", "output"):
+        cli_val = getattr(args, attr, None)
+        if cli_val is not None:
+            setattr(ns, attr, cli_val)
+
+    return ns
diff --git a/lmcache/cli/commands/bench/engine_bench/interactive/config.json b/lmcache/cli/commands/bench/engine_bench/interactive/config.json
new file mode 100644
index 0000000..5f6a227
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/interactive/config.json
@@ -0,0 +1,10 @@
+{
+  "model": "Qwen/Qwen3-14B",
+  "workload": "long-doc-qa",
+  "kv_cache_volume": 100.0,
+  "tokens_per_gb_kvcache": 6553,
+  "ldqa_document_length": 10000,
+  "ldqa_query_per_document": 2,
+  "ldqa_shuffle_policy": "random",
+  "ldqa_num_inflight_requests": 3
+}
diff --git a/lmcache/cli/commands/bench/engine_bench/interactive/schema.py b/lmcache/cli/commands/bench/engine_bench/interactive/schema.py
new file mode 100644
index 0000000..9149dc3
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/interactive/schema.py
@@ -0,0 +1,418 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Centralized config item definitions for interactive configuration.
+
+Each ``ConfigItem`` declaratively describes one configurable parameter:
+its key, display name, description, input type, default, and when it
+should be shown.  The ``ALL_ITEMS`` list is the single source of truth
+for descriptions, ordering, and defaults.
+"""
+
+# Standard
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Phases
+# ---------------------------------------------------------------------------
+
+PHASE_REQUIRED = 1
+PHASE_GENERAL = 2
+PHASE_WORKLOAD = 3
+
+
+# ---------------------------------------------------------------------------
+# ConfigItem
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ConfigItem:
+    """Declarative description of a single configurable parameter.
+
+    Attributes:
+        key: State dict key (matches argparse attr name, e.g., ``"engine_url"``).
+        display_name: Heading shown in the prompt.
+        description: One-sentence explanation shown below the heading.
+        input_type: One of ``"text"``, ``"int"``, ``"float"``, ``"bool"``,
+            ``"choice"``.
+        default: Default value.  ``None`` means required (no default).
+        required: If True, this item must have a value before the benchmark
+            can start.
+        choices: For ``"choice"`` type — list of ``(value, description)`` tuples.
+        condition: Callable ``(state_dict) -> bool`` that determines whether
+            this item should be shown.  ``None`` means always shown.
+        phase: Which interactive phase this item belongs to.
+    """
+
+    key: str
+    display_name: str
+    description: str
+    input_type: str  # "text", "int", "float", "bool", "choice"
+    default: Any = None
+    required: bool = False
+    choices: list[tuple[str, str]] = field(default_factory=list)
+    condition: Callable[[dict[str, Any]], bool] | None = None
+    phase: int = PHASE_GENERAL
+
+
+# ---------------------------------------------------------------------------
+# Condition helpers
+# ---------------------------------------------------------------------------
+
+
+def _has_lmcache(state: dict[str, Any]) -> bool:
+    """Show this item only when the user said they have LMCache."""
+    return bool(state.get("has_lmcache"))
+
+
+def _no_lmcache_url(state: dict[str, Any]) -> bool:
+    """Show this item only when lmcache_url is not set."""
+    return not state.get("lmcache_url")
+
+
+def _workload_is(name: str) -> Callable[[dict[str, Any]], bool]:
+    """Return a condition that checks the workload value."""
+
+    def check(state: dict[str, Any]) -> bool:
+        return state.get("workload") == name
+
+    return check
+
+
+# ---------------------------------------------------------------------------
+# ALL_ITEMS — the centralized registry
+# ---------------------------------------------------------------------------
+
+ALL_ITEMS: list[ConfigItem] = [
+    # ── Phase 1: Required ─────────────────────────────────────────────
+    ConfigItem(
+        key="engine_url",
+        display_name="Engine URL",
+        description=(
+            "URL of the inference engine. Enter just a port (e.g. 8000) to "
+            "use http://localhost:8000. "
+            "Set OPENAI_API_KEY env var if authentication is needed."
+        ),
+        input_type="text",
+        default="http://localhost:8000",
+        required=True,
+        phase=PHASE_REQUIRED,
+    ),
+    ConfigItem(
+        key="workload",
+        display_name="Workload",
+        description="The type of benchmark workload to run.",
+        input_type="choice",
+        default=None,
+        required=True,
+        choices=[
+            (
+                "long-doc-permutator",
+                "Query the same set of long documents with different orders",
+            ),
+            ("long-doc-qa", "Repeated Q&A over long documents (tests KV cache reuse)"),
+            ("multi-round-chat", "Multi-turn chat with stateful sessions"),
+            (
+                "prefix-suffix-tuner",
+                "Two-pass sequential workload demonstrating tiered KV cache reuse",
+            ),
+            ("random-prefill", "Prefill-only requests fired simultaneously"),
+        ],
+        phase=PHASE_REQUIRED,
+    ),
+    ConfigItem(
+        key="has_lmcache",
+        display_name="LMCache Server",
+        description=(
+            "Do you have a running LMCache server? "
+            "It can auto-detect KV cache size information."
+        ),
+        input_type="bool",
+        default=True,
+        required=False,
+        phase=PHASE_REQUIRED,
+    ),
+    ConfigItem(
+        key="lmcache_url",
+        display_name="LMCache Server URL",
+        description=(
+            "URL of the running LMCache HTTP server. Enter just a port "
+            "(e.g. 8080) to use http://localhost:8080."
+        ),
+        input_type="text",
+        default="http://localhost:8080",
+        required=False,
+        condition=_has_lmcache,
+        phase=PHASE_REQUIRED,
+    ),
+    ConfigItem(
+        key="tokens_per_gb_kvcache",
+        display_name="Tokens per GB KV cache",
+        description=(
+            "How many tokens fit in 1 GB of KV cache for your model.\n"
+            "  If using vLLM, look for these lines in the startup log:\n"
+            '    "Available KV cache memory: XX.XX GiB"\n'
+            '    "GPU KV cache size: XXX,XXX tokens"\n'
+            "  Then compute: tokens_per_gb = "
+            "GPU_KV_cache_tokens / Available_KV_cache_GiB"
+        ),
+        input_type="int",
+        default=None,
+        required=True,
+        condition=_no_lmcache_url,
+        phase=PHASE_REQUIRED,
+    ),
+    # ── Phase 2: General ──────────────────────────────────────────────
+    ConfigItem(
+        key="model",
+        display_name="Model name",
+        description=(
+            "The model served by the engine. "
+            "Leave empty to auto-detect from the engine."
+        ),
+        input_type="text",
+        default="",
+        phase=PHASE_GENERAL,
+    ),
+    ConfigItem(
+        key="kv_cache_volume",
+        display_name="KV cache volume (GB)",
+        description="Target active KV cache size for the benchmark.",
+        input_type="float",
+        default=100.0,
+        phase=PHASE_GENERAL,
+    ),
+    ConfigItem(
+        key="ignore_eos",
+        display_name="Ignore EOS",
+        description=(
+            "Force generation to run for the full output length by ignoring "
+            "the model's EOS token (vLLM extension). Makes decode throughput "
+            "reproducible."
+        ),
+        input_type="bool",
+        default=False,
+        phase=PHASE_GENERAL,
+    ),
+    # ── Phase 3: long-doc-permutator ─────────────────────────────────
+    ConfigItem(
+        key="ldp_num_contexts",
+        display_name="Number of contexts",
+        description="Number of unique context documents to generate.",
+        input_type="int",
+        default=5,
+        condition=_workload_is("long-doc-permutator"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldp_context_length",
+        display_name="Context length (tokens)",
+        description="Token length of each context document.",
+        input_type="int",
+        default=5000,
+        condition=_workload_is("long-doc-permutator"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldp_system_prompt_length",
+        display_name="System prompt length (tokens)",
+        description="Token length of the shared system prompt. Use 0 for none.",
+        input_type="int",
+        default=1000,
+        condition=_workload_is("long-doc-permutator"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldp_num_permutations",
+        display_name="Number of permutations",
+        description="Distinct permutations to send. Capped at N! (N = num_contexts).",
+        input_type="int",
+        default=10,
+        condition=_workload_is("long-doc-permutator"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldp_num_inflight_requests",
+        display_name="Max inflight requests",
+        description="Maximum concurrent in-flight requests.",
+        input_type="int",
+        default=1,
+        condition=_workload_is("long-doc-permutator"),
+        phase=PHASE_WORKLOAD,
+    ),
+    # ── Phase 3: long-doc-qa ──────────────────────────────────────────
+    ConfigItem(
+        key="ldqa_document_length",
+        display_name="Document length (tokens)",
+        description="Token length of each synthetic document.",
+        input_type="int",
+        default=10000,
+        condition=_workload_is("long-doc-qa"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldqa_query_per_document",
+        display_name="Queries per document",
+        description="Number of questions asked per document.",
+        input_type="int",
+        default=2,
+        condition=_workload_is("long-doc-qa"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldqa_shuffle_policy",
+        display_name="Shuffle policy",
+        description="How benchmark requests are ordered.",
+        input_type="choice",
+        default="random",
+        choices=[
+            ("random", "Shuffle all (doc, query) pairs randomly"),
+            ("tile", "Process queries round by round across all documents"),
+        ],
+        condition=_workload_is("long-doc-qa"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldqa_num_inflight_requests",
+        display_name="Max inflight requests",
+        description="Maximum concurrent in-flight requests.",
+        input_type="int",
+        default=3,
+        condition=_workload_is("long-doc-qa"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="ldqa_max_output_length",
+        display_name="Max output length (tokens)",
+        description="Max tokens to generate per benchmark query.",
+        input_type="int",
+        default=128,
+        condition=_workload_is("long-doc-qa"),
+        phase=PHASE_WORKLOAD,
+    ),
+    # ── Phase 3: multi-round-chat ─────────────────────────────────────
+    ConfigItem(
+        key="mrc_shared_prompt_length",
+        display_name="System prompt length (tokens)",
+        description="Token length of the system prompt per session.",
+        input_type="int",
+        default=2000,
+        condition=_workload_is("multi-round-chat"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="mrc_chat_history_length",
+        display_name="Chat history length (tokens)",
+        description="Token length of pre-filled conversation history.",
+        input_type="int",
+        default=10000,
+        condition=_workload_is("multi-round-chat"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="mrc_user_input_length",
+        display_name="User input length (tokens)",
+        description="Tokens per user query in each round.",
+        input_type="int",
+        default=50,
+        condition=_workload_is("multi-round-chat"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="mrc_output_length",
+        display_name="Output length (tokens)",
+        description="Max tokens to generate per response.",
+        input_type="int",
+        default=200,
+        condition=_workload_is("multi-round-chat"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="mrc_qps",
+        display_name="Queries per second",
+        description="Target request dispatch rate.",
+        input_type="float",
+        default=1.0,
+        condition=_workload_is("multi-round-chat"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="mrc_duration",
+        display_name="Duration (seconds)",
+        description="How long the benchmark runs.",
+        input_type="float",
+        default=60.0,
+        condition=_workload_is("multi-round-chat"),
+        phase=PHASE_WORKLOAD,
+    ),
+    # ── Phase 3: prefix-suffix-tuner ──────────────────────────────────
+    ConfigItem(
+        key="psf_context_length",
+        display_name="Context length (tokens)",
+        description="Total tokens per request (prefix + breaker + suffix).",
+        input_type="int",
+        default=8000,
+        condition=_workload_is("prefix-suffix-tuner"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="psf_prefix_ratio",
+        display_name="Prefix ratio",
+        description=(
+            "Fraction of context-length used by the prefix. Must be in "
+            "(0.0, 1.0). The remainder (minus a 32-token breaker) is the "
+            "shared suffix."
+        ),
+        input_type="float",
+        default=0.8,
+        condition=_workload_is("prefix-suffix-tuner"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="psf_thrash",
+        display_name="Target tier size (GB)",
+        description=(
+            "Size in GB of the KV-cache tier to overflow. The prefix pool "
+            "is sized to slightly more than this, so every pass-2 request "
+            "misses the targeted tier. Use the L0 (HBM) size for vanilla "
+            "vLLM, or the L1 (LMCache DRAM) size for tiered baselines."
+        ),
+        input_type="float",
+        default=20.0,
+        condition=_workload_is("prefix-suffix-tuner"),
+        phase=PHASE_WORKLOAD,
+    ),
+    # ── Phase 3: random-prefill ───────────────────────────────────────
+    ConfigItem(
+        key="rp_request_length",
+        display_name="Request length (tokens)",
+        description="Token length of each prefill request.",
+        input_type="int",
+        default=10000,
+        condition=_workload_is("random-prefill"),
+        phase=PHASE_WORKLOAD,
+    ),
+    ConfigItem(
+        key="rp_num_requests",
+        display_name="Number of requests",
+        description="Total prefill requests to fire simultaneously.",
+        input_type="int",
+        default=50,
+        condition=_workload_is("random-prefill"),
+        phase=PHASE_WORKLOAD,
+    ),
+]
+
+
+def get_items_by_phase(phase: int) -> list[ConfigItem]:
+    """Return all items belonging to a given phase."""
+    return [item for item in ALL_ITEMS if item.phase == phase]
+
+
+def get_item(key: str) -> ConfigItem:
+    """Look up a ConfigItem by key.  Raises KeyError if not found."""
+    for item in ALL_ITEMS:
+        if item.key == key:
+            return item
+    raise KeyError(f"No ConfigItem with key {key!r}")
diff --git a/lmcache/cli/commands/bench/engine_bench/interactive/state.py b/lmcache/cli/commands/bench/engine_bench/interactive/state.py
new file mode 100644
index 0000000..5e8cf4d
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/interactive/state.py
@@ -0,0 +1,331 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Intermediate state tracker for interactive configuration.
+
+``InteractiveState`` holds the partially-configured benchmark parameters,
+can be initialized from CLI args or a saved JSON file, and can be
+converted to the ``argparse.Namespace`` that ``run_engine_bench()`` expects.
+"""
+
+# Standard
+from typing import Any
+import argparse
+import json
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.interactive.schema import (
+    ALL_ITEMS,
+    PHASE_GENERAL,
+    PHASE_REQUIRED,
+    PHASE_WORKLOAD,
+    ConfigItem,
+)
+
+# Keys that exist on argparse.Namespace but are NOT part of the interactive
+# config item registry (operational flags, handled separately).
+_OUTPUT_KEYS = ("output_dir", "seed", "no_csv", "export_csv", "json", "quiet")
+
+# Keys used only during the interactive flow, never serialized or
+# passed to the orchestrator.
+_INTERACTIVE_ONLY_KEYS = {"has_lmcache"}
+
+# Keys excluded from exported JSON configs.  These are either
+# environment-specific (engine_url, lmcache_url) or interactive-only.
+_EXPORT_EXCLUDED_KEYS = _INTERACTIVE_ONLY_KEYS | {"engine_url", "lmcache_url"}
+
+# Mapping from ConfigItem.key to the argparse attribute name when they differ.
+# Most keys match directly; these are the exceptions.
+_KEY_TO_ATTR: dict[str, str] = {
+    "kv_cache_volume": "kv_cache_volume",
+    "tokens_per_gb_kvcache": "tokens_per_gb_kvcache",
+}
+
+# argparse attribute names where the CLI default is None (meaning "not set"),
+# versus attributes where a non-None argparse default is the real default
+# (e.g., kv_cache_volume defaults to 100.0).
+_ARGPARSE_NONE_MEANS_UNSET = {
+    "engine_url",
+    "workload",
+    "model",
+    "lmcache_url",
+    "tokens_per_gb_kvcache",
+}
+
+
+class InteractiveState:
+    """Tracks which config items have been set and their values.
+
+    Keys present in ``_values`` are considered "set".  Missing keys are
+    "unset" and will either be prompted for or filled with defaults.
+    """
+
+    def __init__(self) -> None:
+        self._values: dict[str, Any] = {}
+
+    # ------------------------------------------------------------------
+    # Basic accessors
+    # ------------------------------------------------------------------
+
+    def is_set(self, key: str) -> bool:
+        return key in self._values
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._values.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self._values[key] = value
+
+    def unset(self, key: str) -> None:
+        """Remove a key so it counts as unset again (used when stepping back)."""
+        self._values.pop(key, None)
+
+    @property
+    def values(self) -> dict[str, Any]:
+        return dict(self._values)
+
+    # ------------------------------------------------------------------
+    # Readiness checks
+    # ------------------------------------------------------------------
+
+    def is_ready(self) -> bool:
+        """True when all required items (whose conditions are met) have values."""
+        for item in ALL_ITEMS:
+            if not item.required:
+                continue
+            if not self._condition_met(item):
+                continue
+            if not self.is_set(item.key):
+                return False
+        return True
+
+    def get_missing_required(self) -> list[ConfigItem]:
+        """Return phase-1 items that still need user input.
+
+        Includes both required items that are unset, and non-required
+        phase-1 items (like ``lmcache_url``) that are relevant because
+        a downstream required item (``tokens_per_gb_kvcache``) is unset.
+        """
+        missing: list[ConfigItem] = []
+        for item in ALL_ITEMS:
+            if item.phase != PHASE_REQUIRED:
+                continue
+            if not self._condition_met(item):
+                continue
+            if self.is_set(item.key):
+                continue
+            if item.required:
+                missing.append(item)
+            elif item.key in ("has_lmcache", "lmcache_url") and not self.is_set(
+                "tokens_per_gb_kvcache"
+            ):
+                # Only ask about LMCache when tokens_per_gb is needed
+                missing.append(item)
+        return missing
+
+    def get_general_items(self) -> list[ConfigItem]:
+        """Return phase-2 (general) items that are not yet set."""
+        return [
+            item
+            for item in ALL_ITEMS
+            if item.phase == PHASE_GENERAL
+            and not self.is_set(item.key)
+            and self._condition_met(item)
+        ]
+
+    def get_workload_items(self) -> list[ConfigItem]:
+        """Return phase-3 (workload-specific) items whose conditions are met."""
+        return [
+            item
+            for item in ALL_ITEMS
+            if item.phase == PHASE_WORKLOAD and self._condition_met(item)
+        ]
+
+    def has_unconfigured_general(self) -> bool:
+        """True if there are general items the user hasn't explicitly set."""
+        return len(self.get_general_items()) > 0
+
+    def has_workload_items(self) -> bool:
+        """True if there are workload-specific items to configure."""
+        return len(self.get_workload_items()) > 0
+
+    def workload_items_all_default(self) -> bool:
+        """True if no workload-specific items have been explicitly set."""
+        for item in ALL_ITEMS:
+            if item.phase != PHASE_WORKLOAD:
+                continue
+            if not self._condition_met(item):
+                continue
+            if self.is_set(item.key):
+                return False
+        return True
+
+    # ------------------------------------------------------------------
+    # Defaults
+    # ------------------------------------------------------------------
+
+    def fill_defaults(self) -> None:
+        """Set all unset items (whose conditions are met) to their defaults."""
+        for item in ALL_ITEMS:
+            if self.is_set(item.key):
+                continue
+            if not self._condition_met(item):
+                continue
+            if item.default is not None:
+                self._values[item.key] = item.default
+
+    # ------------------------------------------------------------------
+    # Conversion: CLI args ↔ InteractiveState
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_cli_args(cls, args: argparse.Namespace) -> "InteractiveState":
+        """Build state from parsed CLI arguments.
+
+        Only sets values that the user explicitly provided (i.e., not the
+        argparse default).  This lets us distinguish "user set
+        ``--kv-cache-volume 100``" from "user didn't touch it".
+        """
+        state = cls()
+        for item in ALL_ITEMS:
+            if item.key in _INTERACTIVE_ONLY_KEYS:
+                continue
+            attr = _KEY_TO_ATTR.get(item.key, item.key)
+            value = getattr(args, attr, None)
+            if value is None:
+                continue
+            # For keys where argparse default is None, any non-None value
+            # means the user set it.
+            if attr in _ARGPARSE_NONE_MEANS_UNSET:
+                state._values[item.key] = value
+                continue
+            # For keys with real argparse defaults, we can't easily tell
+            # if the user typed --kv-cache-volume 100 vs it being the
+            # default.  We mark it as "set" only if it differs from the
+            # schema default.  This is imperfect but good enough — the
+            # worst case is we re-prompt for a value the user explicitly
+            # set to the default.
+            if item.default is not None and value == item.default:
+                continue
+            state._values[item.key] = value
+
+        # Derive has_lmcache from lmcache_url if provided via CLI
+        if state.is_set("lmcache_url"):
+            state._values["has_lmcache"] = True
+
+        return state
+
+    def to_namespace(self) -> argparse.Namespace:
+        """Convert to ``argparse.Namespace`` compatible with ``run_engine_bench``.
+
+        Fills defaults for any unset items, then builds the namespace
+        with the attribute names that ``parse_args_to_config()`` and
+        ``create_workload()`` expect.
+        """
+        self.fill_defaults()
+        ns = argparse.Namespace()
+
+        # Map state keys to namespace attributes
+        for item in ALL_ITEMS:
+            if item.key in _INTERACTIVE_ONLY_KEYS:
+                continue
+            attr = _KEY_TO_ATTR.get(item.key, item.key)
+            # Only fall back to schema default if the item's condition is met.
+            # This prevents lmcache_url's default from leaking when
+            # has_lmcache is not set.
+            if item.key in self._values:
+                value = self._values[item.key]
+            elif self._condition_met(item):
+                value = item.default
+            else:
+                value = None
+            setattr(ns, attr, value)
+
+        # Output settings (not in the interactive registry)
+        ns.output_dir = self._values.get("output_dir", ".")
+        ns.seed = self._values.get("seed", 42)
+        ns.no_csv = self._values.get("no_csv", False)
+        ns.json = self._values.get("export_json", False)
+        ns.quiet = self._values.get("quiet", False)
+        ns.bench_target = "engine"
+
+        # Ensure format/output attrs exist for create_metrics
+        if not hasattr(ns, "format"):
+            ns.format = None
+        if not hasattr(ns, "output"):
+            ns.output = None
+
+        return ns
+
+    # ------------------------------------------------------------------
+    # Conversion: JSON ↔ InteractiveState
+    # ------------------------------------------------------------------
+
+    def to_json(self) -> dict[str, Any]:
+        """Serialize to a JSON-compatible dict for config export.
+
+        Excludes environment-specific keys (``engine_url``,
+        ``lmcache_url``) and interactive-only keys so the exported
+        config is portable and works without an LMCache server.
+        """
+        self.fill_defaults()
+        return {k: v for k, v in self._values.items() if k not in _EXPORT_EXCLUDED_KEYS}
+
+    @classmethod
+    def from_json(cls, data: dict[str, Any]) -> "InteractiveState":
+        """Load from a saved config JSON dict."""
+        state = cls()
+        for key, value in data.items():
+            state._values[key] = value
+        return state
+
+    def save_json(self, path: str) -> None:
+        """Export the current state to a JSON file."""
+        with open(path, "w") as f:
+            json.dump(self.to_json(), f, indent=2)
+            f.write("\n")
+
+    @classmethod
+    def load_json(cls, path: str) -> "InteractiveState":
+        """Load state from a JSON config file."""
+        with open(path) as f:
+            data = json.load(f)
+        return cls.from_json(data)
+
+    def merge_cli_args(self, args: argparse.Namespace) -> None:
+        """Merge CLI args on top of existing state (CLI args win)."""
+        cli_state = InteractiveState.from_cli_args(args)
+        self._values.update(cli_state._values)
+
+    # ------------------------------------------------------------------
+    # Summary
+    # ------------------------------------------------------------------
+
+    def summary_lines(self) -> list[tuple[str, str]]:
+        """Return ``(label, value_str)`` pairs for the config summary."""
+        lines: list[tuple[str, str]] = []
+        for item in ALL_ITEMS:
+            if item.key in _INTERACTIVE_ONLY_KEYS:
+                continue
+            if not self._condition_met(item):
+                continue
+            value = self._values.get(item.key, item.default)
+            if value is None or value == "":
+                if item.key == "model":
+                    display = "(auto-detect)"
+                elif item.key == "lmcache_url":
+                    continue  # skip empty lmcache_url
+                else:
+                    display = "(not set)"
+            else:
+                display = str(value)
+            lines.append((item.display_name, display))
+        return lines
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _condition_met(self, item: ConfigItem) -> bool:
+        """Check whether an item's condition is satisfied."""
+        if item.condition is None:
+            return True
+        return item.condition(self._values)
diff --git a/lmcache/cli/commands/bench/engine_bench/interactive/terminal.py b/lmcache/cli/commands/bench/engine_bench/interactive/terminal.py
new file mode 100644
index 0000000..25c6066
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/interactive/terminal.py
@@ -0,0 +1,349 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Terminal UI primitives for interactive configuration.
+
+Provides simple prompt functions for collecting user input:
+
+- ``prompt_text`` — free-form text with optional default
+- ``prompt_number`` — numeric input with type validation
+- ``prompt_bool`` — Y/N confirmation
+- ``prompt_choice`` — arrow-key selection (falls back to numbered list on non-TTY)
+
+Every prompt accepts ``allow_back``.  When enabled, the user steps back to the
+previous question by typing ``<`` — in every prompt, typed or arrow-key — in
+which case the prompt returns the :data:`GO_BACK` sentinel instead of a value.
+"""
+
+# Standard
+import sys
+
+
+class _GoBack:
+    """Sentinel type returned by prompts when the user asks to step back."""
+
+
+# Returned by any prompt (when ``allow_back=True``) to mean "go to the
+# previous question".  Compare with ``is`` — there is only one instance.
+GO_BACK = _GoBack()
+
+# Token the user types to go back, in any text/number/bool prompt and in the
+# non-TTY choice fallback.
+BACK_TOKEN = "<"
+
+# ---------------------------------------------------------------------------
+# ANSI helpers
+# ---------------------------------------------------------------------------
+
+BOLD = "\033[1m"
+CYAN = "\033[96m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+CLEAR_LINE = "\033[2K"
+CURSOR_UP = "\033[A"
+
+
+def _is_tty() -> bool:
+    return hasattr(sys.stdin, "fileno") and sys.stdin.isatty()
+
+
+def _print_back_hint() -> None:
+    """Print the dim 'type < to go back' hint used by typed prompts."""
+    print(f"  {DIM}(type {BACK_TOKEN} to go back){RESET}")
+
+
+# ---------------------------------------------------------------------------
+# prompt_text
+# ---------------------------------------------------------------------------
+
+
+def prompt_text(
+    label: str,
+    description: str = "",
+    default: str = "",
+    allow_back: bool = False,
+) -> str | _GoBack:
+    """Prompt for free-form text input.
+
+    Args:
+        label: The config item name shown as a heading.
+        description: One-line explanation shown below the label.
+        default: Default value; shown in brackets, returned on empty Enter.
+        allow_back: If True, typing ``<`` returns :data:`GO_BACK`.
+
+    Returns:
+        The user's input, the default if they pressed Enter, or
+        :data:`GO_BACK` if they asked to step back.
+    """
+    print()
+    print(f"{BOLD}{label}{RESET}")
+    if description:
+        print(f"  {description}")
+    if allow_back:
+        _print_back_hint()
+    if default:
+        prompt = f"  {DIM}[default: {default}]{RESET} {GREEN}>{RESET} "
+    else:
+        prompt = f"  {GREEN}>{RESET} "
+    value = input(prompt).strip()
+    if allow_back and value == BACK_TOKEN:
+        return GO_BACK
+    return value if value else default
+
+
+# ---------------------------------------------------------------------------
+# prompt_number
+# ---------------------------------------------------------------------------
+
+
+def prompt_number(
+    label: str,
+    description: str = "",
+    default: float | int | None = None,
+    number_type: type = int,
+    allow_back: bool = False,
+) -> float | int | _GoBack:
+    """Prompt for a numeric value with validation.
+
+    Args:
+        label: The config item name.
+        description: One-line explanation.
+        default: Default value; returned on empty Enter.  None means required.
+        number_type: ``int`` or ``float``.
+        allow_back: If True, typing ``<`` returns :data:`GO_BACK`.
+
+    Returns:
+        The parsed number, or :data:`GO_BACK` if the user asked to step back.
+    """
+    print()
+    print(f"{BOLD}{label}{RESET}")
+    if description:
+        print(f"  {description}")
+    if allow_back:
+        _print_back_hint()
+
+    while True:
+        if default is not None:
+            prompt = f"  {DIM}[default: {default}]{RESET} {GREEN}>{RESET} "
+        else:
+            prompt = f"  {GREEN}>{RESET} "
+        raw = input(prompt).strip()
+        if allow_back and raw == BACK_TOKEN:
+            return GO_BACK
+        if not raw and default is not None:
+            return default
+        try:
+            return number_type(raw)
+        except (ValueError, TypeError):
+            type_name = "integer" if number_type is int else "number"
+            print(f"  {YELLOW}Please enter a valid {type_name}.{RESET}")
+
+
+# ---------------------------------------------------------------------------
+# prompt_bool
+# ---------------------------------------------------------------------------
+
+
+def prompt_bool(
+    label: str,
+    description: str = "",
+    default: bool = True,
+    allow_back: bool = False,
+) -> bool | _GoBack:
+    """Prompt for a yes/no confirmation.
+
+    Shows ``[Y/n]`` or ``[y/N]`` depending on the default.
+    Enter alone accepts the default.
+
+    Args:
+        label: The config item name.
+        description: One-line explanation.
+        default: Default value when user presses Enter.
+        allow_back: If True, typing ``<`` returns :data:`GO_BACK`.
+
+    Returns:
+        True for yes, False for no, or :data:`GO_BACK` if the user asked to
+        step back.
+    """
+    print()
+    print(f"{BOLD}{label}{RESET}")
+    if description:
+        print(f"  {description}")
+    if allow_back:
+        _print_back_hint()
+
+    hint = "[default: Y] (Y/n)" if default else "[default: N] (y/N)"
+    while True:
+        raw = input(f"  {DIM}{hint}{RESET} {GREEN}>{RESET} ").strip().lower()
+        if allow_back and raw == BACK_TOKEN:
+            return GO_BACK
+        if not raw:
+            return default
+        if raw in ("y", "yes"):
+            return True
+        if raw in ("n", "no"):
+            return False
+        print(f"  {YELLOW}Please enter Y or N.{RESET}")
+
+
+# ---------------------------------------------------------------------------
+# prompt_choice — arrow-key selection
+# ---------------------------------------------------------------------------
+
+
+def _read_key() -> str:
+    """Read a single keypress from stdin in raw mode.
+
+    Returns:
+        ``"up"``, ``"down"``, ``"enter"``, or the literal character.
+    """
+    # Standard
+    import termios
+    import tty
+
+    fd = sys.stdin.fileno()
+    old_settings = termios.tcgetattr(fd)
+    try:
+        tty.setraw(fd)
+        ch = sys.stdin.read(1)
+        # Raw mode disables signal generation, so translate Ctrl-C / Ctrl-D
+        # into the usual exceptions the caller already expects.
+        if ch == "\x03":
+            raise KeyboardInterrupt
+        if ch == "\x04":
+            raise EOFError
+        if ch == "\r" or ch == "\n":
+            return "enter"
+        if ch == "\x1b":
+            seq = sys.stdin.read(2)
+            if seq == "[A":
+                return "up"
+            if seq == "[B":
+                return "down"
+            return "escape"
+        return ch
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+
+def _render_choices(
+    choices: list[tuple[str, str]],
+    selected: int,
+) -> list[str]:
+    """Build display lines for the choice selector."""
+    lines: list[str] = []
+    for i, (value, desc) in enumerate(choices):
+        if i == selected:
+            marker = f"{CYAN}● {value}{RESET}"
+        else:
+            marker = f"  {value}"
+        # Pad value to align descriptions
+        padding = max(0, 18 - len(value))
+        line = f"  {marker}{' ' * padding} {DIM}{desc}{RESET}"
+        lines.append(line)
+    return lines
+
+
+def prompt_choice(
+    label: str,
+    description: str = "",
+    choices: list[tuple[str, str]] = [],  # noqa: B006
+    default: str = "",
+    allow_back: bool = False,
+) -> str | _GoBack:
+    """Prompt user to select from a list using arrow keys.
+
+    Each choice is a ``(value, description)`` tuple.  The description is
+    shown next to the value as a brief explanation.
+
+    Falls back to numbered input on non-TTY stdin.
+
+    Args:
+        label: The config item name.
+        description: One-line explanation.
+        choices: List of ``(value, one_line_description)`` tuples.
+        default: Pre-selected value.  Defaults to the first choice.
+        allow_back: If True, pressing ``<`` returns :data:`GO_BACK`.
+
+    Returns:
+        The selected value string, or :data:`GO_BACK` if the user asked to
+        step back.
+    """
+    if not choices:
+        raise ValueError("choices must not be empty")
+
+    # Find default index
+    selected = 0
+    for i, (val, _desc) in enumerate(choices):
+        if val == default:
+            selected = i
+            break
+
+    print()
+    print(f"{BOLD}{label}{RESET}")
+    if description:
+        print(f"  {description}")
+
+    # Non-TTY fallback: numbered list
+    if not _is_tty():
+        return _prompt_choice_fallback(choices, selected, allow_back)
+
+    nav = "Use ↑↓ to navigate, Enter to select"
+    nav += f", {BACK_TOKEN} to go back." if allow_back else "."
+    print(f"  {DIM}{nav}{RESET}")
+    print()
+
+    # Initial render
+    lines = _render_choices(choices, selected)
+    for line in lines:
+        print(line)
+
+    while True:
+        key = _read_key()
+        if key == "up":
+            selected = (selected - 1) % len(choices)
+        elif key == "down":
+            selected = (selected + 1) % len(choices)
+        elif key == "enter" or (key == BACK_TOKEN and allow_back):
+            # Clear and re-render final state
+            num_lines = len(choices)
+            sys.stdout.write(f"\r{CURSOR_UP * num_lines}")
+            lines = _render_choices(choices, selected)
+            for line in lines:
+                print(f"{CLEAR_LINE}{line}")
+            return GO_BACK if key == BACK_TOKEN else choices[selected][0]
+        else:
+            continue
+
+        # Redraw
+        num_lines = len(choices)
+        sys.stdout.write(f"\r{CURSOR_UP * num_lines}")
+        lines = _render_choices(choices, selected)
+        for line in lines:
+            print(f"{CLEAR_LINE}{line}")
+
+
+def _prompt_choice_fallback(
+    choices: list[tuple[str, str]],
+    default_index: int,
+    allow_back: bool = False,
+) -> str | _GoBack:
+    """Numbered fallback for non-TTY environments."""
+    for i, (val, desc) in enumerate(choices):
+        marker = "*" if i == default_index else " "
+        print(f"  {marker} {i + 1}) {val}  — {desc}")
+    if allow_back:
+        _print_back_hint()
+    while True:
+        raw = input(f"  [default: {default_index + 1}] {GREEN}>{RESET} ").strip()
+        if allow_back and raw == BACK_TOKEN:
+            return GO_BACK
+        if not raw:
+            return choices[default_index][0]
+        try:
+            idx = int(raw) - 1
+            if 0 <= idx < len(choices):
+                return choices[idx][0]
+        except ValueError:
+            pass
+        print(f"  {YELLOW}Enter a number 1-{len(choices)}.{RESET}")
diff --git a/lmcache/cli/commands/bench/engine_bench/progress.py b/lmcache/cli/commands/bench/engine_bench/progress.py
new file mode 100644
index 0000000..7bdac91
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/progress.py
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Real-time terminal display for ``lmcache bench engine``."""
+
+# Standard
+import threading
+import time
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+
+# ANSI escape codes
+CLEAR_LINE = "\033[2K"
+CURSOR_UP = "\033[A"
+BOLD = "\033[1m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+RED = "\033[91m"
+RESET = "\033[0m"
+
+
+class ProgressMonitor:
+    """Real-time terminal display for benchmark progress.
+
+    Runs a daemon thread that redraws stats every second using ANSI
+    cursor control for in-place updates.  Reads aggregated metrics
+    from a ``StatsCollector`` and tracks in-flight count internally.
+    """
+
+    LOG_LINES = 5
+    DISPLAY_LINES = 9 + LOG_LINES  # stats block + log lines
+
+    def __init__(
+        self,
+        stats_collector: StatsCollector,
+        quiet: bool = False,
+    ) -> None:
+        self._stats_collector = stats_collector
+        self._quiet = quiet
+
+        self._lock = threading.Lock()
+        self._in_flight: int = 0
+        self._log_messages: list[str] = []
+
+        self._running: bool = False
+        self._thread: threading.Thread = None  # type: ignore[assignment]
+        self._first_draw: bool = True
+        self._start_time: float = time.monotonic()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the display daemon thread."""
+        if self._quiet:
+            return
+        self._start_time = time.monotonic()
+        self._running = True
+        self._first_draw = True
+        self._thread = threading.Thread(target=self._display_loop, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the display thread and print final state."""
+        self._running = False
+        if self._thread is not None:
+            self._thread.join(timeout=3)
+        if not self._quiet:
+            self._draw()
+            print()  # final newline
+
+    def on_request_sent(self, request_id: str) -> None:
+        """Called when a request is dispatched. Increments in-flight."""
+        with self._lock:
+            self._in_flight += 1
+
+    def on_request_finished(self, request_id: str, successful: bool) -> None:
+        """Called when a request completes. Decrements in-flight."""
+        with self._lock:
+            self._in_flight = max(self._in_flight - 1, 0)
+
+    def log_message(self, message: str) -> None:
+        """Add a log line to the display. Thread-safe."""
+        with self._lock:
+            self._log_messages.append(message)
+            if len(self._log_messages) > self.LOG_LINES:
+                self._log_messages = self._log_messages[-self.LOG_LINES :]
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _display_loop(self) -> None:
+        """Background loop: redraw every second."""
+        while self._running:
+            self._draw()
+            time.sleep(1.0)
+
+    def _draw(self) -> None:
+        """Render the real-time stats display."""
+        # Read stats from collector (already thread-safe)
+        stats = self._stats_collector.get_current_stats()
+
+        # Read local state under lock
+        with self._lock:
+            in_flight = self._in_flight
+            log_messages = list(self._log_messages)
+
+        elapsed = time.monotonic() - self._start_time
+
+        # Move cursor up to overwrite previous display
+        if not self._first_draw:
+            print(f"\r{CURSOR_UP * self.DISPLAY_LINES}", end="")
+        self._first_draw = False
+
+        lines = [
+            f"{BOLD}{'─' * 50}{RESET}",
+            (f"{BOLD} Engine Benchmark{RESET}   elapsed: {CYAN}{elapsed:.0f}s{RESET}"),
+            (
+                f"  {GREEN}{stats.successful_requests}{RESET} successful"
+                f"   {CYAN}{in_flight}{RESET} in-flight"
+                f"   {RED}{stats.failed_requests}{RESET} failed"
+            ),
+            f"  Avg TTFT:       {YELLOW}{stats.mean_ttft_ms:.1f} ms{RESET}",
+            (f"  Avg decode:     {YELLOW}{stats.mean_decode_speed:.1f} tok/s{RESET}"),
+            f"  Input tokens:   {stats.total_input_tokens:,}",
+            f"  Output tokens:  {stats.total_output_tokens:,}",
+            (
+                f"  Throughput:     "
+                f"{stats.input_throughput:.1f} in "
+                f"/ {stats.output_throughput:.1f} out tok/s"
+            ),
+            f"{BOLD}{'─' * 50}{RESET}",
+        ]
+
+        # Pad log lines to fixed count
+        for i in range(self.LOG_LINES):
+            if i < len(log_messages):
+                lines.append(f"  {YELLOW}[log] {log_messages[i]}{RESET}")
+            else:
+                lines.append("")
+
+        for line in lines:
+            print(f"{CLEAR_LINE}{line}")
diff --git a/lmcache/cli/commands/bench/engine_bench/request_sender.py b/lmcache/cli/commands/bench/engine_bench/request_sender.py
new file mode 100644
index 0000000..71f031d
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/request_sender.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Async streaming request sender for ``lmcache bench engine``."""
+
+# Standard
+from collections.abc import Callable
+import collections.abc
+import os
+import time
+
+# Third Party
+from openai import AsyncOpenAI
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# Callback signature: (result, response_text) -> None
+OnFinishedCallback = Callable[[RequestResult, str], None]
+
+
+def _normalize_url(engine_url: str) -> str:
+    """Ensure *engine_url* has a scheme and ends with ``/v1``."""
+    url = engine_url.rstrip("/")
+    if not url.startswith(("http://", "https://")):
+        url = f"http://{url}"
+    if not url.endswith("/v1"):
+        url += "/v1"
+    return url
+
+
+def _extract_content(chunk: object, completions_mode: bool) -> str:
+    """Return text content from a streaming chunk, or ``""`` if none.
+
+    Ported from Tensormesh-Benchmark ``streaming_utils.py``.
+    """
+    choices = getattr(chunk, "choices", None)
+    if not choices:
+        return ""
+
+    choice = choices[0]
+
+    if completions_mode:
+        text = getattr(choice, "text", None)
+        return text if text is not None else ""
+
+    # Chat mode: delta.content, with fallback for reasoning_content
+    delta = getattr(choice, "delta", None)
+    if delta is None:
+        return ""
+    content = getattr(delta, "content", None)
+    if content is not None:
+        return content
+    # Fallback for reasoning models
+    for attr in ("reasoning_content", "reasoning"):
+        fallback = getattr(delta, attr, None)
+        if fallback is not None:
+            return fallback
+    return ""
+
+
+class RequestSender:
+    """Async streaming request sender for inference engines.
+
+    Each ``send_request`` call is a self-contained coroutine.
+    Concurrency is controlled externally by the workload module.
+    """
+
+    def __init__(
+        self,
+        engine_url: str,
+        model: str,
+        completions_mode: bool = False,
+        on_finished: list[OnFinishedCallback] = [],  # noqa: B006
+        ignore_eos: bool = False,
+    ) -> None:
+        self._model = model
+        self._completions_mode = completions_mode
+        self._on_finished = list(on_finished)
+        self._ignore_eos = ignore_eos
+
+        base_url = _normalize_url(engine_url)
+        api_key = os.getenv("OPENAI_API_KEY", "")
+        if not api_key:
+            api_key = "sk-dummy"
+            logger.debug("API key source: default dummy key")
+        else:
+            logger.debug("API key source: OPENAI_API_KEY env var")
+
+        self._client = AsyncOpenAI(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=None,
+        )
+
+    def add_on_finished_callback(self, callback: OnFinishedCallback) -> None:
+        """Register a callback to be invoked when a request finishes."""
+        self._on_finished.append(callback)
+
+    async def send_request(
+        self,
+        request_id: str,
+        messages: list[dict[str, str]],
+        max_tokens: int = 128,
+    ) -> RequestResult:
+        """Send a single streaming request and return the result.
+
+        Streams the response via SSE, measures TTFT, decode speed, and
+        total latency.  Extracts token counts from server usage reports.
+        After collecting the result, invokes all registered
+        ``on_finished`` callbacks.
+        """
+        submit_time = time.time()
+        first_token_time = 0.0
+        first_chunk_time = 0.0
+        tokens: list[str] = []
+        num_input_tokens = 0
+        num_output_tokens = 0
+
+        try:
+            response = await self._create_stream(messages, max_tokens)
+
+            async for chunk in response:
+                if not first_chunk_time:
+                    first_chunk_time = time.time()
+
+                # Extract usage from final chunk
+                usage = getattr(chunk, "usage", None)
+                if usage is not None:
+                    pt = getattr(usage, "prompt_tokens", 0)
+                    ct = getattr(usage, "completion_tokens", 0)
+                    if pt:
+                        num_input_tokens = pt
+                    if ct:
+                        num_output_tokens = ct
+
+                content = _extract_content(chunk, self._completions_mode)
+                if content:
+                    if not first_token_time:
+                        first_token_time = time.time()
+                    tokens.append(content)
+
+            finish_time = time.time()
+            if first_token_time == 0.0 and num_output_tokens > 0:
+                # Empty-content stream (common with max_tokens=1, e.g. the
+                # single token is EOS): use first chunk arrival as TTFT —
+                # closer to engine prefill completion than finish_time.
+                first_token_time = first_chunk_time or finish_time
+            successful = first_token_time > 0.0
+            ttft = (first_token_time - submit_time) if successful else -1.0
+            request_latency = finish_time - submit_time
+            decode_time = (finish_time - first_token_time) if successful else 0.0
+            num_output = num_output_tokens if num_output_tokens > 0 else len(tokens)
+            decode_speed = (num_output / decode_time) if decode_time > 0 else 0.0
+
+            result = RequestResult(
+                request_id=request_id,
+                successful=successful,
+                ttft=ttft,
+                request_latency=request_latency,
+                num_input_tokens=num_input_tokens,
+                num_output_tokens=num_output,
+                decode_speed=decode_speed,
+                submit_time=submit_time,
+                first_token_time=first_token_time,
+                finish_time=finish_time,
+                error="",
+            )
+            response_text = "".join(tokens)
+
+        except Exception as e:
+            finish_time = time.time()
+            result = RequestResult(
+                request_id=request_id,
+                successful=False,
+                ttft=-1.0,
+                request_latency=finish_time - submit_time,
+                num_input_tokens=0,
+                num_output_tokens=0,
+                decode_speed=0.0,
+                submit_time=submit_time,
+                first_token_time=0.0,
+                finish_time=finish_time,
+                error=str(e),
+            )
+            response_text = ""
+            logger.debug(
+                "Request %s failed: %s",
+                request_id,
+                e,
+            )
+
+        for cb in self._on_finished:
+            cb(result, response_text)
+
+        return result
+
+    async def send_warmup_request(
+        self,
+        request_id: str,
+        messages: list[dict[str, str]],
+        max_tokens: int = 1,
+    ) -> RequestResult:
+        """Send a warmup request (``max_tokens=1`` by default)."""
+        return await self.send_request(
+            request_id,
+            messages,
+            max_tokens=max_tokens,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.close()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    async def _create_stream(
+        self,
+        messages: list[dict[str, str]],
+        max_tokens: int,
+    ) -> collections.abc.AsyncIterator:
+        """Dispatch the streaming API call (chat or completions).
+
+        When ``ignore_eos`` is set on the sender, ``{"ignore_eos": true}`` is
+        added to the request body (a vLLM sampling extension) so generation
+        always runs for the full ``max_tokens`` instead of stopping at the
+        model's EOS token. This makes decode-throughput numbers reproducible.
+        """
+        # Attach extra_body only when ignore_eos is set; otherwise send the
+        # plain request so no vLLM-specific field reaches non-vLLM backends.
+        extra: dict[str, dict[str, bool]] = {}
+        if self._ignore_eos:
+            extra["extra_body"] = {"ignore_eos": True}
+        if self._completions_mode:
+            prompt = messages[0]["content"] if messages else ""
+            return await self._client.completions.create(
+                model=self._model,
+                prompt=prompt,
+                stream=True,
+                max_tokens=max_tokens,
+                temperature=0.0,
+                stream_options={"include_usage": True},
+                **extra,
+            )
+        return await self._client.chat.completions.create(
+            model=self._model,
+            messages=messages,
+            stream=True,
+            max_tokens=max_tokens,
+            temperature=0.0,
+            stream_options={"include_usage": True},
+            **extra,
+        )
diff --git a/lmcache/cli/commands/bench/engine_bench/stats.py b/lmcache/cli/commands/bench/engine_bench/stats.py
new file mode 100644
index 0000000..9424f51
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/stats.py
@@ -0,0 +1,275 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Stats collection, aggregation, and export for ``lmcache bench engine``."""
+
+# Standard
+from dataclasses import asdict, dataclass
+from pathlib import Path
+import csv
+import json
+import threading
+import time
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.config import EngineBenchConfig
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class RequestResult:
+    """Raw per-request result collected by the request sender."""
+
+    request_id: str
+    successful: bool
+    ttft: float  # time to first token (seconds)
+    request_latency: float  # total request time (seconds)
+    num_input_tokens: int  # from server usage report
+    num_output_tokens: int  # tokens generated
+    decode_speed: float  # output tokens / decode time (tok/s)
+    submit_time: float  # absolute timestamp
+    first_token_time: float  # absolute timestamp
+    finish_time: float  # absolute timestamp
+    error: str  # empty string if successful
+
+
+@dataclass
+class AggregatedStats:
+    """Snapshot of aggregated statistics (running totals)."""
+
+    total_requests: int
+    successful_requests: int
+    failed_requests: int
+    elapsed_time: float  # seconds since benchmark start
+
+    mean_ttft_ms: float
+    mean_decode_speed: float  # tok/s
+    mean_request_latency_ms: float
+
+    input_throughput: float  # total input tokens / elapsed time
+    output_throughput: float  # total output tokens / elapsed time
+
+    total_input_tokens: int
+    total_output_tokens: int
+
+
+@dataclass
+class FinalStats(AggregatedStats):
+    """Final statistics with percentiles. Extends AggregatedStats."""
+
+    p50_ttft_ms: float = 0.0
+    p90_ttft_ms: float = 0.0
+    p99_ttft_ms: float = 0.0
+    p50_decode_speed: float = 0.0
+    p90_decode_speed: float = 0.0
+    p99_decode_speed: float = 0.0
+    p50_request_latency_ms: float = 0.0
+    p90_request_latency_ms: float = 0.0
+    p99_request_latency_ms: float = 0.0
+
+
+class StatsCollector:
+    """Thread-safe stats aggregation for benchmark results.
+
+    Receives ``RequestResult`` objects from the request sender,
+    maintains running totals, and produces final summaries.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._results: list[RequestResult] = []
+        self._start_time: float = time.monotonic()
+
+        # Running accumulators (updated under lock)
+        self._successful: int = 0
+        self._failed: int = 0
+        self._sum_ttft: float = 0.0
+        self._sum_decode_speed: float = 0.0
+        self._sum_request_latency: float = 0.0
+        self._total_input_tokens: int = 0
+        self._total_output_tokens: int = 0
+
+    def on_request_finished(self, result: RequestResult) -> None:
+        """Record a completed request. Thread-safe."""
+        with self._lock:
+            self._results.append(result)
+            if result.successful:
+                self._successful += 1
+                self._sum_ttft += result.ttft
+                self._sum_decode_speed += result.decode_speed
+                self._sum_request_latency += result.request_latency
+            else:
+                self._failed += 1
+            self._total_input_tokens += result.num_input_tokens
+            self._total_output_tokens += result.num_output_tokens
+        logger.debug(
+            "Recorded result for %s (successful=%s)",
+            result.request_id,
+            result.successful,
+        )
+
+    def reset(self) -> None:
+        """Clear all accumulated results and restart the timer.
+
+        Used between warmup and benchmark phases so warmup stats
+        don't pollute benchmark results. Thread-safe.
+        """
+        with self._lock:
+            self._results.clear()
+            self._start_time = time.monotonic()
+            self._successful = 0
+            self._failed = 0
+            self._sum_ttft = 0.0
+            self._sum_decode_speed = 0.0
+            self._sum_request_latency = 0.0
+            self._total_input_tokens = 0
+            self._total_output_tokens = 0
+        logger.debug("Stats collector reset")
+
+    def get_current_stats(self) -> AggregatedStats:
+        """Return current aggregated stats snapshot. Thread-safe."""
+        with self._lock:
+            successful = self._successful
+            failed = self._failed
+            elapsed = time.monotonic() - self._start_time
+            sum_ttft = self._sum_ttft
+            sum_decode = self._sum_decode_speed
+            sum_latency = self._sum_request_latency
+            total_in = self._total_input_tokens
+            total_out = self._total_output_tokens
+
+        safe_successful = max(successful, 1)
+
+        return AggregatedStats(
+            total_requests=successful + failed,
+            successful_requests=successful,
+            failed_requests=failed,
+            elapsed_time=elapsed,
+            mean_ttft_ms=(sum_ttft / safe_successful) * 1000.0,
+            mean_decode_speed=sum_decode / safe_successful,
+            mean_request_latency_ms=(sum_latency / safe_successful) * 1000.0,
+            input_throughput=total_in / max(elapsed, 1e-9),
+            output_throughput=total_out / max(elapsed, 1e-9),
+            total_input_tokens=total_in,
+            total_output_tokens=total_out,
+        )
+
+    def get_final_stats(self) -> FinalStats:
+        """Compute and return final stats with percentiles.
+
+        Should be called once after the benchmark completes.
+        """
+        with self._lock:
+            results = list(self._results)
+
+        successful_results = [r for r in results if r.successful]
+        current = self.get_current_stats()
+
+        if not successful_results:
+            return FinalStats(
+                total_requests=current.total_requests,
+                successful_requests=current.successful_requests,
+                failed_requests=current.failed_requests,
+                elapsed_time=current.elapsed_time,
+                mean_ttft_ms=current.mean_ttft_ms,
+                mean_decode_speed=current.mean_decode_speed,
+                mean_request_latency_ms=current.mean_request_latency_ms,
+                input_throughput=current.input_throughput,
+                output_throughput=current.output_throughput,
+                total_input_tokens=current.total_input_tokens,
+                total_output_tokens=current.total_output_tokens,
+            )
+
+        ttfts = sorted(r.ttft * 1000.0 for r in successful_results)
+        decode_speeds = sorted(r.decode_speed for r in successful_results)
+        latencies = sorted(r.request_latency * 1000.0 for r in successful_results)
+
+        return FinalStats(
+            total_requests=current.total_requests,
+            successful_requests=current.successful_requests,
+            failed_requests=current.failed_requests,
+            elapsed_time=current.elapsed_time,
+            mean_ttft_ms=current.mean_ttft_ms,
+            mean_decode_speed=current.mean_decode_speed,
+            mean_request_latency_ms=current.mean_request_latency_ms,
+            input_throughput=current.input_throughput,
+            output_throughput=current.output_throughput,
+            total_input_tokens=current.total_input_tokens,
+            total_output_tokens=current.total_output_tokens,
+            p50_ttft_ms=_percentile(ttfts, 50),
+            p90_ttft_ms=_percentile(ttfts, 90),
+            p99_ttft_ms=_percentile(ttfts, 99),
+            p50_decode_speed=_percentile(decode_speeds, 50),
+            p90_decode_speed=_percentile(decode_speeds, 90),
+            p99_decode_speed=_percentile(decode_speeds, 99),
+            p50_request_latency_ms=_percentile(latencies, 50),
+            p90_request_latency_ms=_percentile(latencies, 90),
+            p99_request_latency_ms=_percentile(latencies, 99),
+        )
+
+    def get_all_results(self) -> list[RequestResult]:
+        """Return all raw results for CSV export."""
+        with self._lock:
+            return list(self._results)
+
+    def export_csv(self, path: str) -> None:
+        """Write per-request results to a CSV file."""
+        results = self.get_all_results()
+        fieldnames = [
+            "request_id",
+            "successful",
+            "ttft",
+            "request_latency",
+            "num_input_tokens",
+            "num_output_tokens",
+            "decode_speed",
+            "submit_time",
+            "first_token_time",
+            "finish_time",
+            "error",
+        ]
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", newline="") as f:
+            writer = csv.DictWriter(f, fieldnames=fieldnames)
+            writer.writeheader()
+            for result in results:
+                writer.writerow(asdict(result))
+        logger.debug("Exported %d results to CSV: %s", len(results), path)
+
+    def export_json(self, path: str, config: EngineBenchConfig) -> None:
+        """Write summary JSON with config and aggregated metrics."""
+        final = self.get_final_stats()
+        output = {
+            "config": asdict(config),
+            "results": asdict(final),
+        }
+        with open(path, "w") as f:
+            json.dump(output, f, indent=2)
+        logger.debug("Exported JSON summary to: %s", path)
+
+
+def _percentile(sorted_data: list[float], p: float) -> float:
+    """Compute the p-th percentile using linear interpolation.
+
+    Uses the Tensormesh-Benchmark V1 method:
+    ``k = (len(sorted_data) - 1) * p / 100``
+
+    Args:
+        sorted_data: Pre-sorted list of values.
+        p: Percentile value (0-100).
+
+    Returns:
+        Interpolated percentile value. Returns 0.0 for empty data.
+    """
+    if not sorted_data:
+        return 0.0
+    n = len(sorted_data)
+    if n == 1:
+        return sorted_data[0]
+    k = (n - 1) * p / 100.0
+    floor_k = int(k)
+    ceil_k = min(floor_k + 1, n - 1)
+    fraction = k - floor_k
+    return sorted_data[floor_k] + fraction * (
+        sorted_data[ceil_k] - sorted_data[floor_k]
+    )
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/__init__.py b/lmcache/cli/commands/bench/engine_bench/workloads/__init__.py
new file mode 100644
index 0000000..fd2c9d0
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/__init__.py
@@ -0,0 +1,206 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Workload definitions and factory for ``lmcache bench engine``.
+
+Each workload module defines its own config dataclass and workload
+class. The ``create_workload`` factory selects the right workload
+based on ``EngineBenchConfig.workload``, resolves the workload-specific
+config from CLI args, and returns the workload instance.
+"""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.config import EngineBenchConfig
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import (
+    RequestSender,
+)
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+from lmcache.cli.commands.bench.engine_bench.workloads.long_doc_permutator import (
+    LongDocPermutatorConfig,
+    LongDocPermutatorWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.long_doc_qa import (
+    LongDocQAConfig,
+    LongDocQAWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.multi_round_chat import (
+    MultiRoundChatConfig,
+    MultiRoundChatWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.prefix_suffix_tuner import (
+    PrefixSuffixTunerConfig,
+    PrefixSuffixTunerWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.random_prefill import (
+    RandomPrefillConfig,
+    RandomPrefillWorkload,
+)
+
+__all__ = [
+    "BaseWorkload",
+    "LongDocPermutatorConfig",
+    "LongDocPermutatorWorkload",
+    "LongDocQAConfig",
+    "LongDocQAWorkload",
+    "MultiRoundChatConfig",
+    "MultiRoundChatWorkload",
+    "PrefixSuffixTunerConfig",
+    "PrefixSuffixTunerWorkload",
+    "RandomPrefillConfig",
+    "RandomPrefillWorkload",
+    "create_workload",
+    "validate_max_output_length_supported",
+]
+
+_WORKLOAD_NAMES = (
+    "long-doc-permutator",
+    "long-doc-qa",
+    "multi-round-chat",
+    "prefix-suffix-tuner",
+    "random-prefill",
+)
+
+# Workloads that expose a user-configurable max output length, via a
+# ``max_output_length`` arg (``--ldqa-max-output-length`` / ``--mrc-output-length``).
+_WORKLOADS_WITH_MAX_OUTPUT_LENGTH: frozenset[str] = frozenset(
+    {"long-doc-qa", "multi-round-chat"}
+)
+
+
+def validate_max_output_length_supported(workload: str) -> None:
+    """Validate that a max output length can be specified for ``workload``.
+
+    Only workloads with a max-output-length parameter (``long-doc-qa``,
+    ``multi-round-chat``) support setting it; every other workload fixes its
+    generation length internally, so requesting one is rejected.
+
+    Args:
+        workload: The selected workload name (``EngineBenchConfig.workload``).
+
+    Raises:
+        ValueError: If ``workload`` has no max-output-length parameter.
+    """
+    if workload in _WORKLOADS_WITH_MAX_OUTPUT_LENGTH:
+        return
+    supported = ", ".join(sorted(_WORKLOADS_WITH_MAX_OUTPUT_LENGTH))
+    raise ValueError(
+        f"max output length cannot be specified for the {workload!r} workload: "
+        f"it has no max-output-length parameter. Supported workloads: {supported}."
+    )
+
+
+def create_workload(
+    config: EngineBenchConfig,
+    args: argparse.Namespace,
+    request_sender: RequestSender,
+    stats_collector: StatsCollector,
+    progress_monitor: ProgressMonitor,
+) -> BaseWorkload:
+    """Resolve workload-specific config and create the workload instance.
+
+    Dispatches on ``config.workload`` to the appropriate workload module,
+    resolves the workload-specific config from ``args`` and ``config``,
+    and returns the workload instance ready to ``run()``.
+
+    Args:
+        config: Fully-resolved general benchmark config.
+        args: Raw CLI args namespace (contains workload-specific flags).
+        request_sender: Shared request sender instance.
+        stats_collector: Shared stats collector instance.
+        progress_monitor: Shared progress monitor instance.
+
+    Returns:
+        A concrete BaseWorkload instance.
+
+    Raises:
+        ValueError: If the workload name is not recognized.
+    """
+    if config.workload == "long-doc-permutator":
+        ldp_workload_config = LongDocPermutatorConfig.resolve(
+            num_contexts=args.ldp_num_contexts,
+            context_length=args.ldp_context_length,
+            system_prompt_length=args.ldp_system_prompt_length,
+            num_permutations=args.ldp_num_permutations,
+            vocab_size=8000,
+            num_inflight_requests=args.ldp_num_inflight_requests,
+        )
+        return LongDocPermutatorWorkload(
+            config=ldp_workload_config,
+            request_sender=request_sender,
+            stats_collector=stats_collector,
+            progress_monitor=progress_monitor,
+            seed=config.seed,
+        )
+
+    if config.workload == "long-doc-qa":
+        ld_workload_config = LongDocQAConfig.resolve(
+            kv_cache_volume_gb=config.kv_cache_volume_gb,
+            tokens_per_gb_kvcache=config.tokens_per_gb_kvcache,
+            document_length=args.ldqa_document_length,
+            query_per_document=args.ldqa_query_per_document,
+            shuffle_policy=args.ldqa_shuffle_policy,
+            num_inflight_requests=args.ldqa_num_inflight_requests,
+            max_output_length=args.ldqa_max_output_length,
+        )
+        return LongDocQAWorkload(
+            config=ld_workload_config,
+            request_sender=request_sender,
+            stats_collector=stats_collector,
+            progress_monitor=progress_monitor,
+            seed=config.seed,
+        )
+
+    if config.workload == "multi-round-chat":
+        mr_workload_config = MultiRoundChatConfig.resolve(
+            kv_cache_volume_gb=config.kv_cache_volume_gb,
+            tokens_per_gb_kvcache=config.tokens_per_gb_kvcache,
+            shared_prompt_length=args.mrc_shared_prompt_length,
+            chat_history_length=args.mrc_chat_history_length,
+            user_input_length=args.mrc_user_input_length,
+            output_length=args.mrc_output_length,
+            qps=args.mrc_qps,
+            duration=args.mrc_duration,
+        )
+        return MultiRoundChatWorkload(
+            config=mr_workload_config,
+            request_sender=request_sender,
+            stats_collector=stats_collector,
+            progress_monitor=progress_monitor,
+            seed=config.seed,
+        )
+
+    if config.workload == "prefix-suffix-tuner":
+        psf_workload_config = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=config.tokens_per_gb_kvcache,
+            context_length=args.psf_context_length,
+            prefix_ratio=args.psf_prefix_ratio,
+            thrash=args.psf_thrash,
+        )
+        return PrefixSuffixTunerWorkload(
+            config=psf_workload_config,
+            request_sender=request_sender,
+            stats_collector=stats_collector,
+            progress_monitor=progress_monitor,
+            seed=config.seed,
+            model_name=config.model,
+        )
+
+    if config.workload == "random-prefill":
+        rp_workload_config = RandomPrefillConfig.resolve(
+            request_length=args.rp_request_length,
+            num_requests=args.rp_num_requests,
+        )
+        return RandomPrefillWorkload(
+            config=rp_workload_config,
+            request_sender=request_sender,
+            stats_collector=stats_collector,
+            progress_monitor=progress_monitor,
+            seed=config.seed,
+        )
+
+    raise ValueError(
+        f"Unknown workload {config.workload!r}. Available: {', '.join(_WORKLOAD_NAMES)}"
+    )
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/base.py b/lmcache/cli/commands/bench/engine_bench/workloads/base.py
new file mode 100644
index 0000000..866cc46
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/base.py
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract base class for engine benchmark workloads."""
+
+# Standard
+from abc import ABC, abstractmethod
+import asyncio
+import queue
+import time
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import RequestSender
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class BaseWorkload(ABC):
+    """Abstract base class for all engine benchmark workloads.
+
+    Owns the internal dispatch loop that calls ``step()`` on the
+    concrete workload.  Provides a thread-safe ``request_finished``
+    callback that enqueues completed requests for the loop to drain.
+    """
+
+    def __init__(
+        self,
+        request_sender: RequestSender,
+        stats_collector: StatsCollector,
+        progress_monitor: ProgressMonitor,
+    ) -> None:
+        self._request_sender = request_sender
+        self._stats_collector = stats_collector
+        self._progress_monitor = progress_monitor
+        self._finished_queue: queue.Queue[tuple[str, str]] = queue.Queue()
+
+    # ------------------------------------------------------------------
+    # Abstract methods
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def warmup(self) -> None:
+        """Run warmup requests.  Blocks until all warmup is done."""
+
+    @abstractmethod
+    async def step(self, time_offset: float) -> float:
+        """Execute one step of the workload.
+
+        Args:
+            time_offset: seconds since benchmark start.
+
+        Returns:
+            Next wakeup time offset (absolute, from benchmark start).
+            Return a negative value to signal that the workload is done.
+        """
+
+    @abstractmethod
+    def log_config(self) -> None:
+        """Log key workload config before the benchmark starts."""
+
+    @abstractmethod
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """Called when a request finishes (from the loop thread).
+
+        Stateless workloads can implement this as a no-op.
+        Stateful workloads use it to record responses in session history.
+        """
+
+    # ------------------------------------------------------------------
+    # Concrete methods
+    # ------------------------------------------------------------------
+
+    def run(self) -> None:
+        """Run warmup + benchmark, closing the HTTP client in the same loop.
+
+        Blocks until the workload is complete. The ``RequestSender``'s
+        httpx transports are bound to this loop, so they must be closed
+        before ``asyncio.run`` destroys it — otherwise a later close
+        from a fresh loop raises ``RuntimeError: Event loop is closed``.
+        """
+
+        async def _run_and_close() -> None:
+            try:
+                await self._run_async()
+            finally:
+                await self._request_sender.close()
+
+        asyncio.run(_run_and_close())
+
+    async def _run_async(self) -> None:
+        """Internal async implementation of the run loop."""
+        self._progress_monitor.log_message("Starting warmup phase")
+        await self.warmup()
+
+        self._progress_monitor.log_message(
+            "Warmup complete, starting benchmark",
+        )
+        self._stats_collector.reset()
+        self._drain_finished_queue()  # discard warmup completions
+
+        start_time = time.monotonic()
+
+        while True:
+            self._drain_finished_queue()
+            time_offset = time.monotonic() - start_time
+            next_wakeup = await self.step(time_offset)
+            if next_wakeup < 0:
+                break
+            sleep_duration = max(0.0, next_wakeup - (time.monotonic() - start_time))
+            if sleep_duration > 0:
+                await asyncio.sleep(sleep_duration)
+
+        self._drain_finished_queue()  # final drain
+        self._progress_monitor.log_message("Benchmark complete")
+
+    def request_finished(self, result, response_text: str) -> None:
+        """Thread-safe callback matching ``OnFinishedCallback`` signature.
+
+        Enqueues ``(request_id, response_text)`` for the loop to drain.
+        Registered on ``RequestSender.on_finished`` by the orchestrator.
+        """
+        self._finished_queue.put((result.request_id, response_text))
+
+    def _drain_finished_queue(self) -> None:
+        """Drain all completed requests and call ``on_request_finished``."""
+        while True:
+            try:
+                request_id, output = self._finished_queue.get_nowait()
+            except queue.Empty:
+                break
+            self.on_request_finished(request_id, output)
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/long_doc_permutator.py b/lmcache/cli/commands/bench/engine_bench/workloads/long_doc_permutator.py
new file mode 100644
index 0000000..0a127c9
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/long_doc_permutator.py
@@ -0,0 +1,415 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Long-document permutator workload for ``lmcache bench engine``.
+
+Stress-tests blended KV cache reuse by sending permutations of a set of
+context documents.  Each request is:
+
+    [System Prompt] + [Doc_i1] + [Doc_i2] + ... + [Doc_iN]
+
+where (i1, ..., iN) is one permutation of the N contexts.
+
+Stress axes (controlled by config):
+    1. Blended Context Boundaries  -> num_contexts
+    2. Eviction                    -> num_permutations
+    3. Chunk Homogeneity           -> vocab_size
+    4. Prefix Domination           -> system_prompt_length
+    5. Concurrency                 -> num_inflight_requests
+"""
+
+# Standard
+from dataclasses import dataclass
+import asyncio
+import itertools
+import math
+import random
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import RequestSender
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class LongDocPermutatorConfig:
+    """Workload-specific config for the long-doc-permutator workload."""
+
+    num_contexts: int = 5
+    context_length: int = 5000
+    system_prompt_length: int = 1000
+    num_permutations: int = 10
+    vocab_size: int = 8000
+    num_inflight_requests: int = 1
+
+    def __post_init__(self) -> None:
+        if self.num_contexts < 1:
+            raise ValueError(f"num_contexts must be >= 1, got {self.num_contexts}")
+        if self.context_length <= 0:
+            raise ValueError(
+                f"context_length must be positive, got {self.context_length}"
+            )
+        if self.num_permutations < 1:
+            raise ValueError(
+                f"num_permutations must be >= 1, got {self.num_permutations}"
+            )
+        if self.vocab_size < 1:
+            raise ValueError(f"vocab_size must be >= 1, got {self.vocab_size}")
+        if self.num_inflight_requests < 1:
+            raise ValueError(
+                f"num_inflight_requests must be >= 1, got {self.num_inflight_requests}"
+            )
+
+    @classmethod
+    def resolve(
+        cls,
+        num_contexts: int = 5,
+        context_length: int = 5000,
+        system_prompt_length: int = 1000,
+        num_permutations: int = 10,
+        vocab_size: int = 8000,
+        num_inflight_requests: int = 1,
+    ) -> "LongDocPermutatorConfig":
+        """Create a config directly from the provided parameters.
+
+        Args:
+            num_contexts: Number of unique context documents.
+            context_length: Token length of each context.
+            system_prompt_length: Token length of the shared system prompt.
+                Use 0 for no system prompt.
+            num_permutations: Number of distinct permutations to send.
+                Capped at N! where N = num_contexts.
+            vocab_size: Vocabulary pool size for context generation.
+                Smaller values increase chunk hash collision risk.
+            num_inflight_requests: Max concurrent in-flight requests.
+
+        Returns:
+            A fully-resolved LongDocPermutatorConfig.
+        """
+        return cls(
+            num_contexts=num_contexts,
+            context_length=context_length,
+            system_prompt_length=system_prompt_length,
+            num_permutations=num_permutations,
+            vocab_size=vocab_size,
+            num_inflight_requests=num_inflight_requests,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Prompt generation helpers (module-level, before classes)
+# ---------------------------------------------------------------------------
+
+
+def _generate_vocab_pool(size: int, seed: int = 42) -> list[str]:
+    """Generate a vocabulary pool of ``size`` unique pseudo-words.
+
+    Deterministically generates synthetic words so every token is unique.
+
+    Args:
+        size: Number of unique words to generate.
+        seed: Random seed for reproducibility.
+
+    Returns:
+        Sorted list of unique pseudo-words.
+    """
+    rng = random.Random(seed)
+    vowels = "aeiou"
+    consonants = "bcdfghjklmnpqrstvwxyz"
+    pool: set[str] = set()
+    while len(pool) < size:
+        length = rng.randint(3, 7)
+        word = ""
+        for j in range(length):
+            if j % 2 == 0:
+                word += rng.choice(consonants)
+            else:
+                word += rng.choice(vowels)
+        word = f"{word}{len(pool)}"
+        pool.add(word)
+    return sorted(pool)
+
+
+def _generate_system_prompt(length: int, seed: int = 42) -> str:
+    """Generate a deterministic shared system prompt of ~``length`` tokens.
+
+    Args:
+        length: Approximate token length of the system prompt.
+        seed: Random seed for reproducibility.
+
+    Returns:
+        A string of ``length`` space-separated words.
+    """
+    if length == 0:
+        return ""
+    rng = random.Random(seed)
+    words = [
+        "the",
+        "system",
+        "will",
+        "process",
+        "your",
+        "request",
+        "and",
+        "provide",
+        "an",
+        "answer",
+        "based",
+        "on",
+        "context",
+    ]
+    return " ".join(rng.choices(words, k=length))
+
+
+def _generate_contexts(
+    num_contexts: int,
+    length: int,
+    vocab_pool: list[str],
+    seed: int = 123,
+) -> list[str]:
+    """Generate ``num_contexts`` unique context blocks of ~``length`` tokens.
+
+    Each context draws from ``vocab_pool`` with a per-context seed so the
+    token sequences genuinely diverge.
+
+    Args:
+        num_contexts: Number of context documents to generate.
+        length: Approximate token length of each context.
+        vocab_pool: Pool of words to sample from.
+        seed: Base random seed; each context uses seed + i.
+
+    Returns:
+        List of context strings.
+    """
+    contexts = []
+    for i in range(num_contexts):
+        rng = random.Random(seed + i)
+        body = " ".join(rng.choices(vocab_pool, k=length))
+        contexts.append(body)
+    return contexts
+
+
+def _enumerate_permutations(
+    num_contexts: int,
+    num_permutations: int,
+    seed: int = 0,
+) -> list[tuple[int, ...]]:
+    """Enumerate up to ``num_permutations`` distinct permutations.
+
+    Returns all N! permutations when num_permutations >= N!.  For large N
+    uses random sampling to avoid iterating an enormous search space.
+
+    Args:
+        num_contexts: Number of contexts (N).
+        num_permutations: Maximum number of permutations to return.
+        seed: Random seed used when sampling is needed.
+
+    Returns:
+        List of permutation tuples.
+    """
+    total_possible = math.factorial(num_contexts)
+    if num_permutations >= total_possible:
+        return list(itertools.permutations(range(num_contexts)))
+
+    if total_possible > num_permutations * 10:
+        rng = random.Random(seed)
+        seen: set[tuple[int, ...]] = set()
+        indices = list(range(num_contexts))
+        while len(seen) < num_permutations:
+            perm = tuple(rng.sample(indices, len(indices)))
+            seen.add(perm)
+        return sorted(seen)
+
+    result = []
+    for perm in itertools.permutations(range(num_contexts)):
+        result.append(perm)
+        if len(result) >= num_permutations:
+            break
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Workload class
+# ---------------------------------------------------------------------------
+
+
+class LongDocPermutatorWorkload(BaseWorkload):
+    """Workload that sends permutations of context documents.
+
+    Generates synthetic contexts from a vocab pool, enumerates permutations,
+    and dispatches requests with semaphore-controlled concurrency.  Includes
+    a single dummy warmup request to prime the engine.
+    """
+
+    def __init__(
+        self,
+        config: LongDocPermutatorConfig,
+        request_sender: RequestSender,
+        stats_collector: StatsCollector,
+        progress_monitor: ProgressMonitor,
+        seed: int = 42,
+    ) -> None:
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self._config = config
+        self._seed = seed
+
+        vocab_pool = _generate_vocab_pool(config.vocab_size, seed=seed)
+        self._system_prompt = _generate_system_prompt(
+            config.system_prompt_length, seed=seed
+        )
+        self._contexts = _generate_contexts(
+            config.num_contexts, config.context_length, vocab_pool, seed=seed + 1
+        )
+        self._permutations = _enumerate_permutations(
+            config.num_contexts, config.num_permutations, seed=seed
+        )
+        self._request_list = self._build_request_list()
+        self._request_index = 0
+
+        self._semaphore = asyncio.Semaphore(config.num_inflight_requests)
+        self._pending_tasks: set[asyncio.Task] = set()
+
+        logger.debug(
+            "LongDocPermutator: %d contexts x %d permutations = %d requests",
+            config.num_contexts,
+            len(self._permutations),
+            len(self._request_list),
+        )
+
+    def log_config(self) -> None:
+        """Log key workload config before the benchmark starts."""
+        c = self._config
+        B = "\033[1m"
+        C = "\033[96m"
+        Y = "\033[93m"
+        R = "\033[0m"
+        total = len(self._request_list)
+        actual_perms = len(self._permutations)
+        print(
+            f"{B}{'═' * 50}{R}\n"
+            f"{B} Workload: {C}long-doc-permutator{R}\n"
+            f"{B}{'─' * 50}{R}\n"
+            f"  Contexts:            {Y}{c.num_contexts}{R}\n"
+            f"  Context length:      {Y}{c.context_length}{R} tokens\n"
+            f"  System prompt:       {Y}{c.system_prompt_length}{R} tokens\n"
+            f"  Permutations:        {Y}{actual_perms}{R} "
+            f"(of {math.factorial(c.num_contexts)} possible)\n"
+            f"  Total requests:      {Y}{total}{R}\n"
+            f"  Vocab size:          {Y}{c.vocab_size}{R}\n"
+            f"  Max inflight:        {Y}{c.num_inflight_requests}{R}\n"
+            f"{B}{'═' * 50}{R}"
+        )
+
+    # ------------------------------------------------------------------
+    # Data generation
+    # ------------------------------------------------------------------
+
+    def _build_request_list(self) -> list[tuple[list[dict[str, str]], int]]:
+        """Build the full request list from the enumerated permutations.
+
+        Each entry is ``(messages, permutation_index)`` where messages
+        concatenates all contexts in permutation order into a single user
+        message, preceded by the system prompt.
+
+        Returns:
+            List of (messages, permutation_index) tuples.
+        """
+        requests: list[tuple[list[dict[str, str]], int]] = []
+        for perm_idx, perm in enumerate(self._permutations):
+            concatenated = "\n\n".join(self._contexts[i] for i in perm)
+            messages: list[dict[str, str]] = []
+            if self._system_prompt:
+                messages.append({"role": "system", "content": self._system_prompt})
+            messages.append({"role": "user", "content": concatenated})
+            requests.append((messages, perm_idx))
+        return requests
+
+    # ------------------------------------------------------------------
+    # Warmup
+    # ------------------------------------------------------------------
+
+    async def warmup(self) -> None:
+        """Send a single dummy warmup request to prime the engine."""
+        request_id = "warmup_0"
+        dummy_content = " ".join(["warmup"] * 500)
+        messages: list[dict[str, str]] = [
+            {"role": "system", "content": "You are a helpful assistant."},
+            {"role": "user", "content": dummy_content},
+        ]
+        self._progress_monitor.log_message("Warmup (1 dummy request)")
+        self._progress_monitor.on_request_sent(request_id)
+        result = await self._request_sender.send_warmup_request(request_id, messages)
+        if not result.successful:
+            self._progress_monitor.log_message(f"Warmup request failed: {result.error}")
+        self._progress_monitor.log_message("Warmup complete")
+
+    # ------------------------------------------------------------------
+    # Benchmark dispatch
+    # ------------------------------------------------------------------
+
+    async def step(self, time_offset: float) -> float:
+        """Dispatch the next permutation request if semaphore allows.
+
+        Args:
+            time_offset: Seconds since benchmark start (unused).
+
+        Returns:
+            0.0 to request an immediate re-call, or -1.0 when all done.
+        """
+        if self._request_index < len(self._request_list):
+            await self._semaphore.acquire()
+            req_idx = self._request_index
+            messages, perm_idx = self._request_list[req_idx]
+            self._request_index += 1
+
+            task = asyncio.create_task(self._dispatch(messages, perm_idx, req_idx))
+            self._pending_tasks.add(task)
+            task.add_done_callback(self._on_task_done)
+            return 0.0
+
+        if self._pending_tasks:
+            await asyncio.wait(
+                self._pending_tasks,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            return 0.0
+
+        return -1.0
+
+    async def _dispatch(
+        self,
+        messages: list[dict[str, str]],
+        perm_idx: int,
+        req_idx: int,
+    ) -> None:
+        """Send a single benchmark request, then release the semaphore.
+
+        Args:
+            messages: Chat messages for the request.
+            perm_idx: Index of the permutation (used for request ID).
+            req_idx: The request index captured before incrementing the counter.
+        """
+        request_id = f"perm{perm_idx}_req{req_idx}"
+        self._progress_monitor.on_request_sent(request_id)
+        self._progress_monitor.log_message(f"Dispatched permutation {perm_idx}")
+        try:
+            await self._request_sender.send_request(request_id, messages)
+        finally:
+            self._semaphore.release()
+
+    def _on_task_done(self, task: asyncio.Task) -> None:
+        """Clean up completed tasks and log unexpected errors.
+
+        Args:
+            task: The completed asyncio Task.
+        """
+        self._pending_tasks.discard(task)
+        if not task.cancelled():
+            exc = task.exception()
+            if exc is not None:
+                self._progress_monitor.log_message(f"Dispatch task failed: {exc}")
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """No-op — this workload is stateless."""
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/long_doc_qa.py b/lmcache/cli/commands/bench/engine_bench/workloads/long_doc_qa.py
new file mode 100644
index 0000000..4d6e38a
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/long_doc_qa.py
@@ -0,0 +1,290 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Long-document Q&A workload for ``lmcache bench engine``."""
+
+# Standard
+from dataclasses import dataclass
+import asyncio
+import random
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import (
+    RequestSender,
+)
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class LongDocQAConfig:
+    """Workload-specific config for the long-doc-qa workload."""
+
+    document_length: int = 10000
+    query_per_document: int = 2
+    num_documents: int = 1
+    shuffle_policy: str = "random"
+    num_inflight_requests: int = 3
+    max_output_length: int = 128
+
+    def __post_init__(self) -> None:
+        if self.document_length <= 0:
+            raise ValueError(
+                f"document_length must be positive, got {self.document_length}"
+            )
+        if self.query_per_document < 1:
+            raise ValueError(
+                f"query_per_document must be >= 1, got {self.query_per_document}"
+            )
+        if self.max_output_length < 1:
+            raise ValueError(
+                f"max_output_length must be >= 1, got {self.max_output_length}"
+            )
+        if self.num_inflight_requests < 1:
+            raise ValueError(
+                f"num_inflight_requests must be >= 1, got {self.num_inflight_requests}"
+            )
+        if self.shuffle_policy not in ("random", "tile"):
+            raise ValueError(
+                f"shuffle_policy must be 'random' or 'tile', "
+                f"got {self.shuffle_policy!r}"
+            )
+
+    @classmethod
+    def resolve(
+        cls,
+        kv_cache_volume_gb: float,
+        tokens_per_gb_kvcache: int,
+        document_length: int = 10000,
+        query_per_document: int = 2,
+        shuffle_policy: str = "random",
+        num_inflight_requests: int = 3,
+        max_output_length: int = 128,
+    ) -> "LongDocQAConfig":
+        """Create a config with ``num_documents`` computed from KV cache budget.
+
+        Args:
+            kv_cache_volume_gb: Target active KV cache volume in GB.
+            tokens_per_gb_kvcache: Tokens fitting in 1 GB of KV cache.
+            document_length: Token length of each document.
+            query_per_document: Number of questions per document.
+            shuffle_policy: Request ordering — ``"random"`` or ``"tile"``.
+            num_inflight_requests: Max concurrent in-flight requests.
+            max_output_length: Max tokens to generate per benchmark query.
+
+        Returns:
+            A fully-resolved LongDocQAConfig with computed num_documents.
+        """
+        num_documents = max(
+            int(kv_cache_volume_gb * tokens_per_gb_kvcache / document_length),
+            1,
+        )
+        logger.debug(
+            "Computed num_documents=%d from kv_cache_volume_gb=%.1f, "
+            "tokens_per_gb_kvcache=%d, document_length=%d",
+            num_documents,
+            kv_cache_volume_gb,
+            tokens_per_gb_kvcache,
+            document_length,
+        )
+        return cls(
+            document_length=document_length,
+            query_per_document=query_per_document,
+            num_documents=num_documents,
+            shuffle_policy=shuffle_policy,
+            num_inflight_requests=num_inflight_requests,
+            max_output_length=max_output_length,
+        )
+
+
+_QUESTIONS = [
+    "What is this document about?",
+    "Summarize the key points.",
+    "What is the main topic discussed?",
+    "Provide a brief overview.",
+]
+
+
+class LongDocQAWorkload(BaseWorkload):
+    """Workload that simulates repeated Q&A over long documents.
+
+    Generates synthetic documents, builds a request schedule, warms up
+    the KV cache by sending each document once, then dispatches benchmark
+    requests with semaphore-controlled concurrency.
+    """
+
+    def __init__(
+        self,
+        config: LongDocQAConfig,
+        request_sender: RequestSender,
+        stats_collector: StatsCollector,
+        progress_monitor: ProgressMonitor,
+        seed: int = 42,
+    ) -> None:
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self._config = config
+        self._seed = seed
+
+        self._documents = self._generate_documents()
+        self._schedule = self._build_schedule()
+        self._schedule_index = 0
+
+        self._semaphore = asyncio.Semaphore(config.num_inflight_requests)
+        self._pending_tasks: set[asyncio.Task] = set()
+
+    def log_config(self) -> None:
+        """Log key workload config before the benchmark starts."""
+        c = self._config
+        B = "\033[1m"  # bold
+        C = "\033[96m"  # cyan
+        Y = "\033[93m"  # yellow
+        R = "\033[0m"  # reset
+        total = c.num_documents * c.query_per_document
+        print(
+            f"{B}{'═' * 50}{R}\n"
+            f"{B} Workload: {C}long-doc-qa{R}\n"
+            f"{B}{'─' * 50}{R}\n"
+            f"  Documents:        {Y}{c.num_documents}{R}\n"
+            f"  Queries/doc:      {Y}{c.query_per_document}{R}\n"
+            f"  Total requests:   {Y}{total}{R}\n"
+            f"  Document length:  {Y}{c.document_length}{R} tokens\n"
+            f"  Max inflight:     {Y}{c.num_inflight_requests}{R}\n"
+            f"  Shuffle policy:   {Y}{c.shuffle_policy}{R}\n"
+            f"{B}{'═' * 50}{R}"
+        )
+
+    # ------------------------------------------------------------------
+    # Data generation
+    # ------------------------------------------------------------------
+
+    def _generate_documents(self) -> list[str]:
+        """Generate synthetic documents of approximately ``document_length`` tokens."""
+        documents = []
+        for doc_id in range(self._config.num_documents):
+            prefix = f"Document {doc_id}: "
+            body = " ".join(["hi"] * max(self._config.document_length - 10, 1))
+            documents.append(prefix + body)
+        logger.debug(
+            "Generated %d documents of ~%d tokens each",
+            len(documents),
+            self._config.document_length,
+        )
+        return documents
+
+    def _build_schedule(self) -> list[tuple[int, int]]:
+        """Build the request schedule as ``(doc_index, query_index)`` pairs.
+
+        Tile policy uses query-major order: all documents for query 0,
+        then all documents for query 1, etc.  Random policy shuffles
+        the same pairs with a seeded RNG.
+        """
+        schedule: list[tuple[int, int]] = []
+        for q_idx in range(self._config.query_per_document):
+            for doc_idx in range(self._config.num_documents):
+                schedule.append((doc_idx, q_idx))
+
+        if self._config.shuffle_policy == "random":
+            rng = random.Random(self._seed)
+            rng.shuffle(schedule)
+
+        logger.debug(
+            "Built schedule with %d requests (policy=%s)",
+            len(schedule),
+            self._config.shuffle_policy,
+        )
+        return schedule
+
+    def _build_messages(
+        self,
+        doc_index: int,
+        query_index: int,
+    ) -> list[dict[str, str]]:
+        """Build chat messages for a benchmark request."""
+        document = self._documents[doc_index]
+        question = _QUESTIONS[query_index % len(_QUESTIONS)]
+        content = f"{document}\n\nQuestion {query_index}: {question}"
+        return [{"role": "user", "content": content}]
+
+    # ------------------------------------------------------------------
+    # Warmup
+    # ------------------------------------------------------------------
+
+    async def warmup(self) -> None:
+        """Send each document once with ``max_tokens=1`` to populate KV cache."""
+        num_docs = self._config.num_documents
+        for doc_idx in range(num_docs):
+            request_id = f"warmup_doc{doc_idx}"
+            messages = [{"role": "user", "content": self._documents[doc_idx]}]
+            self._progress_monitor.log_message(f"Warmup {doc_idx + 1}/{num_docs}")
+            self._progress_monitor.on_request_sent(request_id)
+            result = await self._request_sender.send_warmup_request(
+                request_id,
+                messages,
+            )
+            if not result.successful:
+                self._progress_monitor.log_message(
+                    f"Warmup {request_id} failed: {result.error}"
+                )
+        self._progress_monitor.log_message(
+            f"Warmup complete: {num_docs} documents sent",
+        )
+
+    # ------------------------------------------------------------------
+    # Benchmark dispatch
+    # ------------------------------------------------------------------
+
+    async def step(self, time_offset: float) -> float:
+        """Dispatch the next request if semaphore allows."""
+        if self._schedule_index < len(self._schedule):
+            await self._semaphore.acquire()
+            doc_idx, q_idx = self._schedule[self._schedule_index]
+            self._schedule_index += 1
+
+            task = asyncio.create_task(self._dispatch(doc_idx, q_idx))
+            self._pending_tasks.add(task)
+            task.add_done_callback(self._on_task_done)
+            return 0.0  # immediate re-call
+
+        # All dispatched — wait for pending tasks.
+        if self._pending_tasks:
+            await asyncio.wait(
+                self._pending_tasks,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            return 0.0
+
+        return -1.0  # all done
+
+    async def _dispatch(
+        self,
+        doc_index: int,
+        query_index: int,
+    ) -> None:
+        """Send a single benchmark request, then release the semaphore."""
+        request_id = f"doc{doc_index}_q{query_index}"
+        messages = self._build_messages(doc_index, query_index)
+        self._progress_monitor.on_request_sent(request_id)
+        self._progress_monitor.log_message(
+            f"Dispatched request {request_id} (doc {doc_index}, query {query_index})"
+        )
+        try:
+            await self._request_sender.send_request(
+                request_id,
+                messages,
+                max_tokens=self._config.max_output_length,
+            )
+        finally:
+            self._semaphore.release()
+
+    def _on_task_done(self, task: asyncio.Task) -> None:
+        """Clean up completed tasks and log unexpected errors."""
+        self._pending_tasks.discard(task)
+        if not task.cancelled():
+            exc = task.exception()
+            if exc is not None:
+                self._progress_monitor.log_message(f"Dispatch task failed: {exc}")
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """No-op — this workload is stateless."""
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/multi_round_chat.py b/lmcache/cli/commands/bench/engine_bench/workloads/multi_round_chat.py
new file mode 100644
index 0000000..0df48cf
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/multi_round_chat.py
@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Multi-round chat workload for ``lmcache bench engine``."""
+
+# Standard
+from dataclasses import dataclass, field
+import asyncio
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import (
+    RequestSender,
+)
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class MultiRoundChatConfig:
+    """Workload-specific config for the multi-round-chat workload."""
+
+    shared_prompt_length: int = 2000
+    chat_history_length: int = 10000
+    user_input_length: int = 50
+    output_length: int = 200
+    qps: float = 1.0
+    duration: float = 60.0
+    num_concurrent_users: int = 1
+
+    def __post_init__(self) -> None:
+        if self.shared_prompt_length <= 0:
+            raise ValueError(
+                f"shared_prompt_length must be positive, "
+                f"got {self.shared_prompt_length}"
+            )
+        if self.chat_history_length <= 0:
+            raise ValueError(
+                f"chat_history_length must be positive, got {self.chat_history_length}"
+            )
+        if self.user_input_length < 1:
+            raise ValueError(
+                f"user_input_length must be >= 1, got {self.user_input_length}"
+            )
+        if self.output_length < 1:
+            raise ValueError(f"output_length must be >= 1, got {self.output_length}")
+        if self.qps <= 0:
+            raise ValueError(f"qps must be positive, got {self.qps}")
+        if self.duration <= 0:
+            raise ValueError(f"duration must be positive, got {self.duration}")
+        if self.num_concurrent_users < 1:
+            raise ValueError(
+                f"num_concurrent_users must be >= 1, got {self.num_concurrent_users}"
+            )
+
+    @classmethod
+    def resolve(
+        cls,
+        kv_cache_volume_gb: float,
+        tokens_per_gb_kvcache: int,
+        shared_prompt_length: int = 2000,
+        chat_history_length: int = 10000,
+        user_input_length: int = 50,
+        output_length: int = 200,
+        qps: float = 1.0,
+        duration: float = 60.0,
+    ) -> "MultiRoundChatConfig":
+        """Create a config with ``num_concurrent_users`` computed from KV cache budget.
+
+        Args:
+            kv_cache_volume_gb: Target active KV cache volume in GB.
+            tokens_per_gb_kvcache: Tokens fitting in 1 GB of KV cache.
+            shared_prompt_length: Token length of the system prompt.
+            chat_history_length: Token length of pre-filled history.
+            user_input_length: Token length per user query.
+            output_length: Max tokens to generate per response.
+            qps: Queries per second.
+            duration: Benchmark duration in seconds.
+
+        Returns:
+            A fully-resolved MultiRoundChatConfig.
+        """
+        tokens_per_session = shared_prompt_length + chat_history_length
+        total_tokens = kv_cache_volume_gb * tokens_per_gb_kvcache
+        num_users = max(1, int(total_tokens / tokens_per_session))
+        logger.debug(
+            "Computed num_concurrent_users=%d from kv_cache_volume_gb=%.1f, "
+            "tokens_per_gb_kvcache=%d, tokens_per_session=%d",
+            num_users,
+            kv_cache_volume_gb,
+            tokens_per_gb_kvcache,
+            tokens_per_session,
+        )
+        return cls(
+            shared_prompt_length=shared_prompt_length,
+            chat_history_length=chat_history_length,
+            user_input_length=user_input_length,
+            output_length=output_length,
+            qps=qps,
+            duration=duration,
+            num_concurrent_users=num_users,
+        )
+
+
+@dataclass
+class Session:
+    """A single stateful chat session.
+
+    Maintains a system prompt, pre-filled history, and accumulated
+    Q&A exchanges.  The ``in_flight`` flag tracks whether a request
+    is currently pending for this session.
+    """
+
+    session_id: int
+    system_prompt: str
+    history_text: str
+    exchanges: list[tuple[str, str]] = field(default_factory=list)
+    in_flight: bool = False
+
+    def build_messages(self, query: str) -> list[dict[str, str]]:
+        """Construct OpenAI-format messages for a request."""
+        messages: list[dict[str, str]] = [
+            {"role": "system", "content": self.system_prompt},
+        ]
+        if self.history_text:
+            messages.append(
+                {"role": "user", "content": self.history_text},
+            )
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": "Understood, I have read the context above.",
+                },
+            )
+        for q, a in self.exchanges:
+            messages.append({"role": "user", "content": q})
+            messages.append({"role": "assistant", "content": a})
+        messages.append({"role": "user", "content": query})
+        return messages
+
+    def record_answer(self, query: str, answer: str) -> None:
+        """Record a completed exchange and mark session as ready."""
+        self.exchanges.append((query, answer))
+        self.in_flight = False
+
+
+class MultiRoundChatWorkload(BaseWorkload):
+    """Workload that simulates multi-round chat with stateful sessions.
+
+    Creates multiple concurrent user sessions, dispatches requests at a
+    fixed QPS rate using round-robin scheduling, and records responses
+    in session history so subsequent queries include prior context.
+    """
+
+    def __init__(
+        self,
+        config: MultiRoundChatConfig,
+        request_sender: RequestSender,
+        stats_collector: StatsCollector,
+        progress_monitor: ProgressMonitor,
+        seed: int = 42,
+    ) -> None:
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self._config = config
+        self._seed = seed
+
+        self._sessions = self._create_sessions()
+        self._global_index = 0
+        self._interval = 1.0 / config.qps
+        self._pending_info: dict[str, tuple[int, str]] = {}
+        self._pending_tasks: set[asyncio.Task] = set()
+
+    def log_config(self) -> None:
+        """Log key workload config before the benchmark starts."""
+        c = self._config
+        B = "\033[1m"  # bold
+        C = "\033[96m"  # cyan
+        Y = "\033[93m"  # yellow
+        R = "\033[0m"  # reset
+        print(
+            f"{B}{'═' * 50}{R}\n"
+            f"{B} Workload: {C}multi-round-chat{R}\n"
+            f"{B}{'─' * 50}{R}\n"
+            f"  Concurrent users: {Y}{c.num_concurrent_users}{R}\n"
+            f"  Prompt length:    {Y}{c.shared_prompt_length}{R} tokens\n"
+            f"  History length:   {Y}{c.chat_history_length}{R} tokens\n"
+            f"  Query length:     {Y}{c.user_input_length}{R} tokens\n"
+            f"  Output length:    {Y}{c.output_length}{R} tokens\n"
+            f"  QPS:              {Y}{c.qps}{R}\n"
+            f"  Duration:         {Y}{c.duration}s{R}\n"
+            f"{B}{'═' * 50}{R}"
+        )
+
+    # ------------------------------------------------------------------
+    # Session creation
+    # ------------------------------------------------------------------
+
+    def _create_sessions(self) -> list[Session]:
+        """Create sessions with synthetic prompts and history."""
+        sessions: list[Session] = []
+        for i in range(self._config.num_concurrent_users):
+            system_prompt = self._generate_system_prompt(i)
+            history = self._generate_history(i)
+            sessions.append(
+                Session(
+                    session_id=i,
+                    system_prompt=system_prompt,
+                    history_text=history,
+                )
+            )
+        logger.debug(
+            "Created %d sessions (prompt=%d, history=%d tokens each)",
+            len(sessions),
+            self._config.shared_prompt_length,
+            self._config.chat_history_length,
+        )
+        return sessions
+
+    def _generate_system_prompt(self, session_id: int) -> str:
+        """Generate a system prompt of approximately ``shared_prompt_length`` tokens."""
+        prefix = f"Session {session_id}. You are a helpful assistant. "
+        remaining = max(0, self._config.shared_prompt_length - len(prefix.split()))
+        return prefix + " ".join(["help"] * remaining)
+
+    def _generate_history(self, session_id: int) -> str:
+        """
+        Generate pre-filled history of approximately ``chat_history_length`` tokens.
+        """
+        prefix = f"[Session {session_id} history] "
+        remaining = max(0, self._config.chat_history_length - len(prefix.split()))
+        return prefix + " ".join(["hi"] * remaining)
+
+    def _generate_query(self) -> str:
+        """Generate a user query of approximately ``user_input_length`` tokens."""
+        return " ".join(["tell"] * self._config.user_input_length)
+
+    # ------------------------------------------------------------------
+    # Warmup
+    # ------------------------------------------------------------------
+
+    async def warmup(self) -> None:
+        """Send one warmup request per session with ``max_tokens=1``."""
+        num_sessions = len(self._sessions)
+        for session in self._sessions:
+            request_id = f"warmup_s{session.session_id}"
+            messages = session.build_messages("Hello")
+            self._progress_monitor.log_message(
+                f"Warmup {session.session_id + 1}/{num_sessions}"
+            )
+            self._progress_monitor.on_request_sent(request_id)
+            result = await self._request_sender.send_warmup_request(
+                request_id,
+                messages,
+            )
+            if not result.successful:
+                self._progress_monitor.log_message(
+                    f"Warmup session {session.session_id} failed: {result.error}"
+                )
+        self._progress_monitor.log_message(f"Warmup complete: {num_sessions} sessions")
+
+    # ------------------------------------------------------------------
+    # Benchmark dispatch
+    # ------------------------------------------------------------------
+
+    async def step(self, time_offset: float) -> float:
+        """Dispatch the next request at the QPS-controlled rate.
+
+        Returns:
+            Next wakeup time offset, or negative when done.
+        """
+        # Check duration — stop dispatching new requests
+        if time_offset >= self._config.duration:
+            if self._pending_tasks:
+                await asyncio.wait(
+                    self._pending_tasks,
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                return 0.0
+            return -1.0
+
+        # Find ready session via round-robin
+        target_idx = self._global_index % len(self._sessions)
+        session = self._sessions[target_idx]
+
+        if session.in_flight:
+            # Session busy — sleep briefly, let loop drain queue
+            return time_offset + 0.01
+
+        # Dispatch request
+        query = self._generate_query()
+        request_id = f"s{session.session_id}_r{self._global_index}"
+        messages = session.build_messages(query)
+
+        session.in_flight = True
+        self._pending_info[request_id] = (session.session_id, query)
+        self._progress_monitor.on_request_sent(request_id)
+        self._progress_monitor.log_message(
+            f"Session {session.session_id} dispatched request {self._global_index}"
+        )
+
+        task = asyncio.create_task(
+            self._dispatch(request_id, messages),
+        )
+        self._pending_tasks.add(task)
+        task.add_done_callback(self._on_task_done)
+
+        self._global_index += 1
+        return self._global_index * self._interval
+
+    async def _dispatch(
+        self,
+        request_id: str,
+        messages: list[dict[str, str]],
+    ) -> None:
+        """Send a single benchmark request."""
+        await self._request_sender.send_request(
+            request_id,
+            messages,
+            max_tokens=self._config.output_length,
+        )
+
+    def _on_task_done(self, task: asyncio.Task) -> None:
+        """Clean up completed tasks and log unexpected errors."""
+        self._pending_tasks.discard(task)
+        if not task.cancelled():
+            exc = task.exception()
+            if exc is not None:
+                self._progress_monitor.log_message(f"Dispatch task failed: {exc}")
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """Record the response in the session's conversation history."""
+        info = self._pending_info.pop(request_id, None)
+        if info is None:
+            return  # warmup request or already processed
+        session_id, query = info
+        self._sessions[session_id].record_answer(query, output)
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/prefix_suffix_tuner.py b/lmcache/cli/commands/bench/engine_bench/workloads/prefix_suffix_tuner.py
new file mode 100644
index 0000000..f8d95e2
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/prefix_suffix_tuner.py
@@ -0,0 +1,637 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Prefix-suffix tuner workload for ``lmcache bench engine``.
+
+Exercises the tiered KV-cache hierarchy (L0 HBM / L1 DRAM / L2 disk) with a
+single sequential workload that can be run unchanged across three baselines:
+
+  Baseline 1 — vanilla vLLM (L0 only).  ``--kv-cache-volume`` set to L0 size,
+      ``--psf-thrash`` slightly > 1 forces every pass-2 request to miss L0.
+
+  Baseline 2 — vLLM + LMCache L1 + L2.  ``--kv-cache-volume`` set to L1 size,
+      so pass-2 requests miss L1 and hit L2 (prefix only — vanilla prefix
+      caching cannot reuse the suffix because it sits behind a random
+      breaker).
+
+  Baseline 3 — vLLM + LMCache L1 + L2 + CacheBlend.  Same sizing as Baseline
+      2; CacheBlend additionally allows the shared suffix's KV chunks to be
+      reused, so both the prefix and the suffix hit cache.
+
+Each request is::
+
+    [prefix_i][random breaker][shared suffix]
+
+with::
+
+  - ``num_prefixes`` distinct prefixes, each starting with a unique ID so
+    the prefix hash differs even if the random body collides.
+  - A fresh random breaker per request, defeating ordinary prefix caching
+    past the prefix boundary and preventing non-CacheBlend reuse of the
+    suffix.
+  - One shared suffix used by every request.
+
+Two passes run sequentially, one request at a time, in identical order:
+
+  - Engine warmup (single throwaway request, before pass 1): amortizes
+    first-request torch.compile / CUDA-graph / connector-handshake cost.
+    Stats discarded; the prompt is too small to occupy a chunk-aligned
+    region so it does not pollute LMCache hit-rate metrics.
+  - Pass 1 (warmup): populates the cache.  Stats discarded.
+  - Pass 2 (measured): repeats the same prefix order.  Because LRU evicts
+    the next-needed prefix on each pass-2 access, even a 1.05× overflow of
+    the targeted tier is enough to ensure every pass-2 request misses that
+    tier and falls through to the next one.
+
+Debug Guide
+-----------
+
+When per-pass-2 hit rates don't match the analytical model, work through
+this checklist in order — the failure modes I hit while debugging this
+workload are listed in the order they actually surfaced.
+
+**1. Disable vLLM L0 prefix caching during the measurement run.**
+   With ``--enable-prefix-caching`` on vLLM, vLLM serves chunks from its
+   own HBM cache without asking LMCache, dropping
+   ``lmcache_mp_lookup_requested_tokens_total`` for the chunks vLLM
+   already had.  This makes the LMCache hit-rate metric look artificially
+   low and obscures the actual L1 behavior.  For *measuring LMCache*,
+   start vLLM with ``--no-enable-prefix-caching``.  Re-enable it for end-
+   to-end latency runs.
+
+**2. Restart LMCache between every comparison run.**
+   Prefixes are deterministic by index (``PREFIX_<8-hex-digits>``).  If a
+   previous run stored ``prefix_0``, the next run finds it already in L1
+   at pass-1 — pass 1 hits cache instead of cold-storing, biasing the
+   pass-2 hit rate upward.  Always restart the LMCache server with a
+   fresh L1 between back-to-back runs.
+
+**3. Configure LMCache eviction aggressively for thrash tests.**
+   LMCache's L1 eviction is a 1Hz polling background thread that fires
+   only when ``usage >= --eviction-trigger-watermark`` and clears
+   ``--eviction-ratio`` of contents per cycle.  Defaults
+   (``watermark=0.80``, ``ratio=0.20``) only drop usage from 80 % to 60 %
+   per fire — leaving 60 % of pass-1 content surviving into pass 2.  For
+   tests that expect ``thrash → ~0% hit rate``, start the server with::
+
+       lmcache server --l1-size-gb <SIZE> --eviction-policy LRU \\
+           --eviction-trigger-watermark 0.80 \\
+           --eviction-ratio 0.99
+
+   The 0.99 ratio means each fire clears nearly the whole cache; combined
+   with the workload's built-in 5-second pass-1→pass-2 settle delay, this
+   approximates a strict-LRU sequential thrash.
+
+**4. Watch the right metrics.**
+   ``GET <lmcache-url>/metrics`` exposes Prometheus counters.  Snapshot
+   before and after the run, take the delta::
+
+       lmcache_mp_lookup_requested_tokens_total   # both passes
+       lmcache_mp_lookup_hit_tokens_total          # both passes (L1+L2)
+       lmcache_mp_l1_eviction_loop_ticks_total     # 1 per loop cycle
+       lmcache_mp_l1_eviction_loop_triggered_total # only when above watermark
+
+   ``triggered/ticks`` should be > 0 for any thrash test.  If it's 0, the
+   benchmark completed before any eviction fired — see (3).  For blend
+   tests, also pull ``lmcache_blend_lookup_{requested,hit}_tokens_total``.
+
+**5. Convert aggregate metrics to per-pass-2 hit rate.**
+   The Prometheus counters tally pass-1 *and* pass-2 lookups, so
+   ``hit_tokens_total / requested_tokens_total`` is roughly *half* the
+   per-pass-2 hit rate (pass 1 contributes cold misses).  The right
+   conversion is::
+
+       per_pass2_hit_rate = hit_tokens_total / (requested_tokens_total / 2)
+
+   when pass 1 has ~0 hits (the typical case for a fresh LMCache).  Use
+   ``num_prefixes`` from the workload's ``log_config`` output to verify
+   the lookup count: ``ticks_total ≈ run_duration_seconds`` and
+   ``requested_tokens_total / chunks_per_request / chunk_size_tokens
+   == 2 * num_prefixes``.
+
+**6. Check pool sizing matches L1 capacity.**
+   The workload sizes ``num_prefixes`` so the pool's *full* per-request
+   KV footprint (``num_prefixes * context_length * tokens_per_gb_kvcache``)
+   equals ``thrash * 1.05`` GB.  If this doesn't match the L1 size you
+   started LMCache with, the test is over- or under-provisioned.  Hit
+   ``GET <lmcache-url>/api/status`` and verify
+   ``storage_manager.l1_manager.memory_total_bytes / 2**30`` matches your
+   ``--psf-thrash`` value.
+
+**7. Per-request CSV breakdown.**
+   ``--output-dir <DIR>`` writes ``bench_results.csv`` with TTFT per
+   pass-2 request.  Sort by request index — under sequential thrash,
+   *early* prefix indices should miss (slow TTFT) and *late* indices
+   should hit (fast TTFT).  Uniform TTFT across all requests means the
+   pool doesn't actually thrash — usually a sign that pass 1 finished
+   before any eviction fired (see step 3 again).
+"""
+
+# Standard
+from dataclasses import dataclass
+import random
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import RequestSender
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+_BREAKER_TOKENS = 32
+_MIN_SUFFIX_TOKENS = 100
+_UNIQUE_ID_TOKENS = 4  # rough token count for ``PREFIX_<8-hex-digits>``
+_MAX_OUTPUT_TOKENS = 1
+
+# Internal multiplier on ``thrash`` GB to size the prefix pool.  Set to 1.05
+# (a 5% overflow) because — with sequential pass-1/pass-2 dispatch and LRU
+# eviction — even a 5% overflow is sufficient to evict the next-needed
+# prefix on every pass-2 access, ensuring all pass-2 requests miss the
+# targeted tier.  See ``docs/design/cli/commands/bench/engine_bench/
+# bench-engine.md`` §4.5 for the analysis.
+_OVERFLOW_FACTOR = 1.05
+
+# Seconds to sleep between pass 1 (warmup) and pass 2 (measured).  LMCache's
+# L1 eviction is a 1Hz polling thread that fires only when usage > watermark
+# (default 0.80) — meaning a fast warmup that overflows L1 by a few percent
+# may complete before any eviction has actually run.  Without this settle
+# delay, pass 2 would find all of pass 1's data still in cache, and the
+# user's analytical-model claim "thrash → 0% hit rate" would not hold.
+# 5 seconds covers several eviction polls (each evicts ``--eviction-ratio``
+# fraction of contents), letting the cache reach steady state under the
+# overflow before pass 2 measures.
+_EVICTION_SETTLE_SECONDS = 5.0
+
+# Range of token-IDs to sample when generating random body content.  Skip
+# the low region (byte fallback / special tokens) and the high tail
+# (reserved / added tokens, which are rarely 1-token-clean on round-trip).
+# 256–50000 is safe across Llama, Qwen, MiniMax tokenizers.
+_TOKEN_ID_LO = 256
+_TOKEN_ID_HI = 50000
+
+
+@dataclass
+class PrefixSuffixTunerConfig:
+    """Workload-specific config for the prefix-suffix-tuner workload.
+
+    Attributes:
+        context_length: Total tokens per request (prefix + breaker + suffix).
+        prefix_ratio: Fraction of ``context_length`` allocated to the prefix.
+        thrash: Size in GB of the KV-cache tier the workload should overflow
+            (L0 / vLLM HBM for Baseline 1; L1 / LMCache DRAM for Baselines
+            2 and 3).  The prefix pool is sized to ``thrash *
+            _OVERFLOW_FACTOR`` GB internally — i.e., just barely larger than
+            the targeted tier — which is sufficient under sequential
+            dispatch and LRU to ensure every pass-2 request misses that
+            tier.
+        num_prefixes: Number of distinct prefixes generated (computed by
+            :meth:`resolve` from the cache budget).
+        prefix_tokens: Token length of each prefix (computed).
+        suffix_tokens: Token length of the shared suffix (computed).
+        breaker_tokens: Token length of the random breaker between prefix
+            and suffix.
+    """
+
+    context_length: int = 8000
+    prefix_ratio: float = 0.8
+    thrash: float = 20.0
+    num_prefixes: int = 1
+    prefix_tokens: int = 1
+    suffix_tokens: int = 1
+    breaker_tokens: int = _BREAKER_TOKENS
+
+    def __post_init__(self) -> None:
+        if self.context_length <= 0:
+            raise ValueError(
+                f"context_length must be positive, got {self.context_length}"
+            )
+        if not 0.0 < self.prefix_ratio < 1.0:
+            raise ValueError(
+                f"prefix_ratio must be in (0.0, 1.0), got {self.prefix_ratio}"
+            )
+        if self.thrash <= 0.0:
+            raise ValueError(f"thrash (GB) must be positive, got {self.thrash}")
+        if self.num_prefixes < 1:
+            raise ValueError(f"num_prefixes must be >= 1, got {self.num_prefixes}")
+        if self.prefix_tokens < 1:
+            raise ValueError(f"prefix_tokens must be >= 1, got {self.prefix_tokens}")
+        if self.suffix_tokens < 1:
+            raise ValueError(f"suffix_tokens must be >= 1, got {self.suffix_tokens}")
+        if self.breaker_tokens < 1:
+            raise ValueError(f"breaker_tokens must be >= 1, got {self.breaker_tokens}")
+
+    @classmethod
+    def resolve(
+        cls,
+        tokens_per_gb_kvcache: int,
+        context_length: int = 8000,
+        prefix_ratio: float = 0.8,
+        thrash: float = 20.0,
+        breaker_tokens: int = _BREAKER_TOKENS,
+    ) -> "PrefixSuffixTunerConfig":
+        """Compute ``num_prefixes`` and token splits from the target tier size.
+
+        ``num_prefixes`` is sized so that the total prefix-pool footprint
+        in tokens equals
+        ``thrash * _OVERFLOW_FACTOR * tokens_per_gb_kvcache``.  ``thrash``
+        is the **size of the targeted KV-cache tier in GB**; the internal
+        :data:`_OVERFLOW_FACTOR` (1.05) provides the small overflow needed
+        for the LRU invariant to drive every pass-2 access to a miss of
+        that tier.
+
+        Args:
+            tokens_per_gb_kvcache: Tokens fitting in 1 GB of KV cache for
+                the served model (auto-detected from the engine in
+                ``parse_args_to_config``; user need not supply directly).
+            context_length: Total tokens per request.
+            prefix_ratio: Fraction of ``context_length`` allocated to the
+                prefix.  Must be strictly between 0 and 1.
+            thrash: Size of the targeted KV-cache tier in GB.  Defaults
+                to 20.0 GB (typical L0 size for a single H100 with low
+                ``--gpu-memory-utilization``).
+            breaker_tokens: Token length of the random breaker between
+                prefix and suffix.  Defaults to 32.
+
+        Returns:
+            A fully-resolved PrefixSuffixTunerConfig.
+
+        Raises:
+            ValueError: If ``prefix_ratio`` leaves fewer than
+                :data:`_MIN_SUFFIX_TOKENS` for the suffix, or if any field
+                fails validation.
+        """
+        prefix_tokens = max(round(context_length * prefix_ratio), 1)
+        suffix_tokens = context_length - prefix_tokens - breaker_tokens
+        if suffix_tokens < _MIN_SUFFIX_TOKENS:
+            raise ValueError(
+                f"suffix_tokens={suffix_tokens} is below minimum "
+                f"{_MIN_SUFFIX_TOKENS}; reduce prefix_ratio or "
+                f"increase context_length"
+            )
+
+        # Size by full context_length, not prefix_tokens: each request
+        # stores ``context_length`` tokens worth of KV cache (prefix +
+        # breaker + suffix), so the pool's L1 footprint is
+        # ``num_prefixes * context_length``, not ``num_prefixes *
+        # prefix_tokens``.  Earlier versions divided by prefix_tokens,
+        # which made the actual pool footprint exceed the requested target
+        # by ``1 / prefix_ratio`` — at ``prefix_ratio=0.5`` the pool was
+        # 2x the user's intended target.
+        pool_gb = thrash * _OVERFLOW_FACTOR
+        num_prefixes = max(
+            int(pool_gb * tokens_per_gb_kvcache / context_length),
+            1,
+        )
+        logger.debug(
+            "Computed num_prefixes=%d from thrash=%.2f GB (target tier), "
+            "_OVERFLOW_FACTOR=%.3f -> pool=%.2f GB, "
+            "tokens_per_gb_kvcache=%d, context_length=%d",
+            num_prefixes,
+            thrash,
+            _OVERFLOW_FACTOR,
+            pool_gb,
+            tokens_per_gb_kvcache,
+            context_length,
+        )
+        return cls(
+            context_length=context_length,
+            prefix_ratio=prefix_ratio,
+            thrash=thrash,
+            num_prefixes=num_prefixes,
+            prefix_tokens=prefix_tokens,
+            suffix_tokens=suffix_tokens,
+            breaker_tokens=breaker_tokens,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Synthetic data generation (module-level helpers)
+# ---------------------------------------------------------------------------
+
+
+def _try_load_tokenizer(model_name: str | None):
+    """Best-effort load of the model's tokenizer.
+
+    Used to generate body content as random valid token-IDs, then decoded
+    back to text — guaranteeing both (a) configured token counts ≈ actual
+    tokens at the model and (b) different content per call site, so chunk
+    content-hashes don't collide across prefixes (which would inflate the
+    LMCache hit rate even in non-blend mode).
+
+    Returns ``None`` if ``transformers`` isn't installed or the tokenizer
+    can't be loaded; callers fall back to the deterministic ``"hi"``
+    filler in that case.
+    """
+    if model_name is None:
+        return None
+    try:
+        # Third Party
+        from transformers import AutoTokenizer
+    except ImportError:
+        logger.warning("transformers not available; falling back to 'hi' body filler")
+        return None
+    try:
+        return AutoTokenizer.from_pretrained(model_name)
+    except Exception as e:  # noqa: BLE001
+        logger.warning(
+            "Could not load tokenizer for %s (%s); falling back to 'hi' filler",
+            model_name,
+            e,
+        )
+        return None
+
+
+def _generate_random_body(num_tokens: int, tokenizer, rng: random.Random) -> str:
+    """Build a body of ``num_tokens`` BPE tokens of unique random content.
+
+    Samples random token-IDs in the safe range and decodes them.  The
+    decoded text re-tokenizes to (≈) ``num_tokens`` tokens (small drift
+    from BPE merge boundaries) and is *content-unique* per call because
+    the IDs are independent draws from ``rng``.
+
+    Falls back to ``"hi"`` filler when ``tokenizer`` is None.
+    """
+    if tokenizer is None:
+        return " ".join(["hi"] * num_tokens)
+    ids = [rng.randrange(_TOKEN_ID_LO, _TOKEN_ID_HI) for _ in range(num_tokens)]
+    return tokenizer.decode(ids, skip_special_tokens=True)
+
+
+def _generate_prefix(
+    index: int,
+    num_tokens: int,
+    tokenizer,
+    rng: random.Random,
+) -> str:
+    """Generate a prefix with unique-ID header + per-prefix random body.
+
+    The unique-ID header makes the prefix's chained block hash unique per
+    ``index`` (so vLLM's chain-hashed prefix cache distinguishes prefixes).
+    The random body uses different token-IDs per ``index`` because
+    ``rng`` is a per-prefix state, so chunk content-hashes don't collide
+    across prefixes — required for non-blend cache hit-rate metrics to be
+    meaningful.
+
+    Args:
+        index: Zero-based prefix index; encoded into the unique ID.
+        num_tokens: Approximate target token length of the full prefix.
+        tokenizer: The model's tokenizer, or None for fallback.
+        rng: Per-prefix seeded random source.
+
+    Returns:
+        Prefix text starting with ``"PREFIX_<8-hex-digits>"``.
+    """
+    unique_id = f"PREFIX_{index:08x}"
+    body_words = max(num_tokens - _UNIQUE_ID_TOKENS, 1)
+    body = _generate_random_body(body_words, tokenizer, rng)
+    return f"{unique_id} {body}"
+
+
+def _generate_suffix(num_tokens: int, tokenizer, rng: random.Random) -> str:
+    """Generate the single shared suffix used by every request.
+
+    The suffix is bit-identical across all requests by design — its
+    content-hash fingerprints are the only ones CacheBlend can reuse
+    across the full pool, which is exactly what Baseline 3 measures.
+
+    Args:
+        num_tokens: Approximate target token length.
+        tokenizer: The model's tokenizer, or None for fallback.
+        rng: Seeded random source (deterministic seed → reproducible).
+
+    Returns:
+        Suffix text starting with ``"SUFFIX"``.
+    """
+    body_words = max(num_tokens - 1, 1)
+    body = _generate_random_body(body_words, tokenizer, rng)
+    return f"SUFFIX {body}"
+
+
+def _generate_breaker(num_tokens: int, tokenizer, rng: random.Random) -> str:
+    """Generate a per-request breaker of fresh random tokens.
+
+    Sampled fresh per request: each request's breaker tokens differ both
+    in IDs (defeats chained prefix cache past the prefix boundary) and in
+    chunk content-hash (so non-blend caches don't carry breaker hits over
+    from earlier requests).
+
+    Args:
+        num_tokens: Approximate target token length.
+        tokenizer: The model's tokenizer, or None for fallback.
+        rng: Seeded random source.  Each call advances state.
+
+    Returns:
+        A breaker string with header + random body.
+    """
+    unique_id = f"BR_{rng.randrange(2**32):08x}"
+    body_words = max(num_tokens - _UNIQUE_ID_TOKENS, 1)
+    body = _generate_random_body(body_words, tokenizer, rng)
+    return f"{unique_id} {body}"
+
+
+# ---------------------------------------------------------------------------
+# Workload class
+# ---------------------------------------------------------------------------
+
+
+class PrefixSuffixTunerWorkload(BaseWorkload):
+    """Sequential two-pass workload demonstrating tiered KV-cache reuse.
+
+    Pass 1 (executed in :meth:`warmup`) populates the cache by sending each
+    prefix once.  Stats from pass 1 are discarded.  Pass 2 (executed via
+    :meth:`step`) repeats the same prefix order one request at a time;
+    these are the measured requests.
+    """
+
+    def __init__(
+        self,
+        config: PrefixSuffixTunerConfig,
+        request_sender: RequestSender,
+        stats_collector: StatsCollector,
+        progress_monitor: ProgressMonitor,
+        seed: int = 42,
+        model_name: str | None = None,
+    ) -> None:
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self._config = config
+        self._seed = seed
+
+        # Best-effort tokenizer load: when available, body content is
+        # generated as random valid token-IDs decoded back to text — that
+        # gives both (a) ~exact configured token count at the model (no
+        # tokenizer-expansion factor) and (b) content uniqueness per
+        # prefix so non-blend cache hit-rate metrics are not inflated by
+        # chunk content-hash collisions across prefixes.  Falls back to
+        # ``"hi"`` filler if transformers / the tokenizer isn't loadable.
+        self._tokenizer = _try_load_tokenizer(model_name)
+
+        # Each prefix gets its own RNG state so per-prefix bodies differ.
+        # Constant offsets keep reproducibility while leaving room for the
+        # suffix (seed + 1) and breaker (seed + 2) RNGs.
+        self._prefixes: list[str] = [
+            _generate_prefix(
+                i,
+                config.prefix_tokens,
+                self._tokenizer,
+                random.Random(seed + 1000 + i),
+            )
+            for i in range(config.num_prefixes)
+        ]
+        self._suffix: str = _generate_suffix(
+            config.suffix_tokens, self._tokenizer, random.Random(seed + 1)
+        )
+        self._breaker_rng = random.Random(seed + 2)
+
+        self._pass2_index = 0
+
+    def log_config(self) -> None:
+        """Log key workload config before the benchmark starts."""
+        c = self._config
+        B = "\033[1m"
+        C = "\033[96m"
+        Y = "\033[93m"
+        R = "\033[0m"
+        pool_tokens_millions = c.num_prefixes * c.prefix_tokens / 1_000_000
+        print(
+            f"{B}{'═' * 50}{R}\n"
+            f"{B} Workload: {C}prefix-suffix-tuner{R}\n"
+            f"{B}{'─' * 50}{R}\n"
+            f"  Context length:    {Y}{c.context_length}{R} tokens\n"
+            f"  Prefix tokens:     {Y}{c.prefix_tokens}{R} (ratio={c.prefix_ratio})\n"
+            f"  Breaker tokens:    {Y}{c.breaker_tokens}{R} (random per request)\n"
+            f"  Suffix tokens:     {Y}{c.suffix_tokens}{R} (shared, deterministic)\n"
+            f"  Target tier:       {Y}{c.thrash:.2f} GB{R}"
+            f" (overflow x{_OVERFLOW_FACTOR:.2f} = "
+            f"{c.thrash * _OVERFLOW_FACTOR:.2f} GB)\n"
+            f"  Prefix pool size:  {Y}{c.num_prefixes}{R}\n"
+            f"  Pool tokens:       {Y}{pool_tokens_millions:.2f}M{R}\n"
+            f"  Total measured:    {Y}{c.num_prefixes}{R} requests "
+            f"(pass 2 of 2)\n"
+            f"{B}{'═' * 50}{R}"
+        )
+
+    # ------------------------------------------------------------------
+    # Message construction
+    # ------------------------------------------------------------------
+
+    def _build_messages(self, prefix_index: int) -> list[dict[str, str]]:
+        """Build chat messages for one request.
+
+        The breaker is freshly randomized on every call, so two requests
+        for the same prefix produce different prompts past the prefix
+        boundary.  Pass 1 and pass 2 therefore use different breakers
+        per prefix even though the prefix order is identical.
+
+        Args:
+            prefix_index: Index into the generated prefix pool.
+
+        Returns:
+            A single-message chat list.
+        """
+        prefix = self._prefixes[prefix_index]
+        breaker = _generate_breaker(
+            self._config.breaker_tokens, self._tokenizer, self._breaker_rng
+        )
+        content = f"{prefix} {breaker} {self._suffix}"
+        return [{"role": "user", "content": content}]
+
+    # ------------------------------------------------------------------
+    # Pass 1 — warmup
+    # ------------------------------------------------------------------
+
+    async def warmup(self) -> None:
+        """Run pass 1: send each prefix once sequentially to populate cache.
+
+        Before pass 1 starts, sends a single short throwaway request to
+        amortize first-request engine overhead (torch.compile JIT-fallback
+        paths, CUDA-graph capture for novel batch shapes, vLLM/LMCache
+        connector handshake, tokenizer lazy initialization).  This keeps
+        the first request of pass 1 on a fully-warmed engine, so that the
+        cache-population pass does not include outlier latency from
+        first-request overhead.  The throwaway prompt is ~5 tokens — too
+        small to occupy a chunk-aligned region — so it does not pollute
+        the LMCache hit-rate metrics.
+
+        After dispatching all warmup requests, sleeps for
+        :data:`_EVICTION_SETTLE_SECONDS` so LMCache's batched-eviction LRU
+        (1Hz background poll, evicts only when usage > watermark) has time
+        to actually run.  Without this delay, a fast warmup that overflows
+        L1 by a few percent may complete before any eviction fires, and
+        pass 2 would then find all of pass 1's data still in cache.
+        """
+        # Engine warmup: amortize first-request torch.compile / CUDA-graph
+        # / connector-handshake cost onto a throwaway request.
+        self._progress_monitor.log_message(
+            "Engine warmup (1 throwaway request before pass 1)"
+        )
+        warmup_result = await self._request_sender.send_warmup_request(
+            "engine_warmup",
+            [{"role": "user", "content": "Hello"}],
+        )
+        if not warmup_result.successful:
+            self._progress_monitor.log_message(
+                f"Engine warmup failed: {warmup_result.error}"
+            )
+
+        n = self._config.num_prefixes
+        self._progress_monitor.log_message(f"Pass 1 (warmup): {n} requests")
+        for i in range(n):
+            request_id = f"pass1_p{i}"
+            messages = self._build_messages(i)
+            self._progress_monitor.on_request_sent(request_id)
+            self._progress_monitor.log_message(f"Pass 1 dispatched {i + 1}/{n}")
+            result = await self._request_sender.send_warmup_request(
+                request_id,
+                messages,
+            )
+            if not result.successful:
+                self._progress_monitor.log_message(
+                    f"Pass 1 {request_id} failed: {result.error}"
+                )
+        self._progress_monitor.log_message(
+            f"Pass 1 complete: {n} prefixes populated; "
+            f"settling {_EVICTION_SETTLE_SECONDS:.1f}s for LMCache LRU eviction",
+        )
+        # Standard
+        import asyncio as _asyncio
+
+        await _asyncio.sleep(_EVICTION_SETTLE_SECONDS)
+
+    # ------------------------------------------------------------------
+    # Pass 2 — measured benchmark
+    # ------------------------------------------------------------------
+
+    async def step(self, time_offset: float) -> float:
+        """Send one pass-2 request inline, sequentially.
+
+        Awaiting the request inside ``step`` enforces strict
+        one-request-at-a-time dispatch.  Returns ``0.0`` for an immediate
+        re-call until the prefix list is exhausted, then ``-1.0``.
+
+        Args:
+            time_offset: Seconds since pass 2 started (unused).
+
+        Returns:
+            ``0.0`` if more requests remain, ``-1.0`` when pass 2 is
+            complete.
+        """
+        if self._pass2_index >= self._config.num_prefixes:
+            return -1.0
+
+        i = self._pass2_index
+        self._pass2_index += 1
+        request_id = f"pass2_p{i}"
+        messages = self._build_messages(i)
+        self._progress_monitor.on_request_sent(request_id)
+        self._progress_monitor.log_message(
+            f"Pass 2 {i + 1}/{self._config.num_prefixes}"
+        )
+        await self._request_sender.send_request(
+            request_id,
+            messages,
+            max_tokens=_MAX_OUTPUT_TOKENS,
+        )
+        return 0.0
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """No-op — this workload is stateless."""
diff --git a/lmcache/cli/commands/bench/engine_bench/workloads/random_prefill.py b/lmcache/cli/commands/bench/engine_bench/workloads/random_prefill.py
new file mode 100644
index 0000000..6944ec4
--- /dev/null
+++ b/lmcache/cli/commands/bench/engine_bench/workloads/random_prefill.py
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Random-prefill workload for ``lmcache bench engine``."""
+
+# Standard
+from dataclasses import dataclass
+import asyncio
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import ProgressMonitor
+from lmcache.cli.commands.bench.engine_bench.request_sender import (
+    RequestSender,
+)
+from lmcache.cli.commands.bench.engine_bench.stats import StatsCollector
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class RandomPrefillConfig:
+    """Workload-specific config for the random-prefill workload."""
+
+    request_length: int = 10000
+    num_requests: int = 50
+
+    def __post_init__(self) -> None:
+        if self.request_length <= 0:
+            raise ValueError(
+                f"request_length must be positive, got {self.request_length}"
+            )
+        if self.num_requests < 1:
+            raise ValueError(f"num_requests must be >= 1, got {self.num_requests}")
+
+    @classmethod
+    def resolve(
+        cls,
+        request_length: int = 10000,
+        num_requests: int = 50,
+    ) -> "RandomPrefillConfig":
+        """Create a config from CLI args.
+
+        Unlike other workloads, random-prefill does not use the KV cache
+        budget to compute request count — the user specifies it directly.
+        """
+        return cls(
+            request_length=request_length,
+            num_requests=num_requests,
+        )
+
+
+class RandomPrefillWorkload(BaseWorkload):
+    """Workload that tests prefill speed by firing all requests at once.
+
+    Generates synthetic prompts of ``request_length`` tokens and dispatches
+    all ``num_requests`` simultaneously with ``max_tokens=1``.  There is
+    no warmup phase.
+    """
+
+    def __init__(
+        self,
+        config: RandomPrefillConfig,
+        request_sender: RequestSender,
+        stats_collector: StatsCollector,
+        progress_monitor: ProgressMonitor,
+        seed: int = 42,
+    ) -> None:
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self._config = config
+        self._seed = seed
+
+        self._prompts = self._generate_prompts()
+        self._dispatched = False
+        self._pending_tasks: set[asyncio.Task] = set()
+
+    def log_config(self) -> None:
+        """Log key workload config before the benchmark starts."""
+        c = self._config
+        B = "\033[1m"  # bold
+        C = "\033[96m"  # cyan
+        Y = "\033[93m"  # yellow
+        R = "\033[0m"  # reset
+        print(
+            f"{B}{'═' * 50}{R}\n"
+            f"{B} Workload: {C}random-prefill{R}\n"
+            f"{B}{'─' * 50}{R}\n"
+            f"  Requests:         {Y}{c.num_requests}{R}\n"
+            f"  Request length:   {Y}{c.request_length}{R} tokens\n"
+            f"  Max output:       {Y}1{R} token\n"
+            f"{B}{'═' * 50}{R}"
+        )
+
+    # ------------------------------------------------------------------
+    # Prompt generation
+    # ------------------------------------------------------------------
+
+    def _generate_prompts(self) -> list[str]:
+        """Generate synthetic prompts of approximately ``request_length`` tokens."""
+        prompts: list[str] = []
+        for i in range(self._config.num_requests):
+            prefix = f"Request {i}: "
+            body = " ".join(["hi"] * max(self._config.request_length - 10, 1))
+            prompts.append(prefix + body)
+        logger.debug(
+            "Generated %d prompts of ~%d tokens each",
+            len(prompts),
+            self._config.request_length,
+        )
+        return prompts
+
+    # ------------------------------------------------------------------
+    # Warmup
+    # ------------------------------------------------------------------
+
+    async def warmup(self) -> None:
+        """No warmup for random-prefill."""
+
+    # ------------------------------------------------------------------
+    # Benchmark dispatch
+    # ------------------------------------------------------------------
+
+    async def step(self, time_offset: float) -> float:
+        """Dispatch all requests at once on the first call.
+
+        Returns:
+            0.0 while tasks are pending, -1.0 when all done.
+        """
+        if not self._dispatched:
+            self._dispatched = True
+            for i, prompt in enumerate(self._prompts):
+                request_id = f"prefill_{i}"
+                messages = [{"role": "user", "content": prompt}]
+                self._progress_monitor.on_request_sent(request_id)
+
+                task = asyncio.create_task(
+                    self._dispatch(request_id, messages),
+                )
+                self._pending_tasks.add(task)
+                task.add_done_callback(self._on_task_done)
+
+            self._progress_monitor.log_message(
+                f"Dispatched all {self._config.num_requests} requests"
+            )
+            return 0.0
+
+        # Wait for pending tasks
+        if self._pending_tasks:
+            await asyncio.wait(
+                self._pending_tasks,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            return 0.0
+
+        return -1.0
+
+    async def _dispatch(
+        self,
+        request_id: str,
+        messages: list[dict[str, str]],
+    ) -> None:
+        """Send a single prefill request with max_tokens=1."""
+        await self._request_sender.send_request(
+            request_id,
+            messages,
+            max_tokens=1,
+        )
+
+    def _on_task_done(self, task: asyncio.Task) -> None:
+        """Clean up completed tasks and log unexpected errors."""
+        self._pending_tasks.discard(task)
+        if not task.cancelled():
+            exc = task.exception()
+            if exc is not None:
+                self._progress_monitor.log_message(f"Dispatch task failed: {exc}")
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        """No-op — this workload is stateless."""
+        self._progress_monitor.log_message(f"Request {request_id} finished")
diff --git a/lmcache/cli/commands/bench/l2_adapter_bench/__init__.py b/lmcache/cli/commands/bench/l2_adapter_bench/__init__.py
new file mode 100644
index 0000000..d8da61d
--- /dev/null
+++ b/lmcache/cli/commands/bench/l2_adapter_bench/__init__.py
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench l2`` subpackage.
+
+Exposes :class:`L2AdapterBenchCommand` for auto-discovery by
+:class:`~lmcache.cli.commands.base.CompositeCommand`.
+"""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class L2AdapterBenchCommand(BaseCommand):
+    """Benchmark an L2 adapter (store / lookup / load)."""
+
+    def name(self) -> str:
+        return "l2"
+
+    def help(self) -> str:
+        return "Benchmark an L2 adapter (store / lookup / load)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # First Party
+        from lmcache.cli.commands.bench.l2_adapter_bench.command import (
+            add_l2_arguments,
+        )
+
+        add_l2_arguments(parser)
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.cli.commands.bench.l2_adapter_bench.command import (
+            run_l2_adapter_bench,
+        )
+
+        run_l2_adapter_bench(self, args)
diff --git a/lmcache/cli/commands/bench/l2_adapter_bench/command.py b/lmcache/cli/commands/bench/l2_adapter_bench/command.py
new file mode 100644
index 0000000..2d1d2f1
--- /dev/null
+++ b/lmcache/cli/commands/bench/l2_adapter_bench/command.py
@@ -0,0 +1,711 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench l2`` subcommand implementation.
+
+This module provides argument registration via :func:`add_l2_arguments`
+and the execution orchestrator :func:`run_l2_adapter_bench` for the L2
+adapter benchmark.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import argparse
+import os
+import sys
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.cli.commands.base import BaseCommand
+    from lmcache.cli.commands.bench.l2_adapter_bench.result import BenchResult
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+
+def add_l2_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add ``lmcache bench l2`` arguments to *parser*.
+
+    Args:
+        parser: The ``ArgumentParser`` for the L2 bench subcommand.
+    """
+
+    parser.add_argument(
+        "--l2-adapter",
+        dest="l2_adapter",
+        action="append",
+        default=None,
+        type=str,
+        metavar="JSON",
+        help=(
+            'L2 adapter spec as JSON with a "type" field and adapter-'
+            'specific configs, e.g. \'{"type":"fs","base_path":"/tmp/'
+            "bench\"}'. If not provided, falls back to L2_ADAPTER_JSON "
+            "environment variable."
+        ),
+    )
+    parser.add_argument(
+        "--num-keys",
+        type=int,
+        default=32,
+        help="Keys per submit (default: 32).",
+    )
+    parser.add_argument(
+        "--in-flight",
+        type=int,
+        default=1,
+        help=(
+            "In-flight submits per round. Each round issues this many "
+            "submits sequentially from a single producer thread, then "
+            "waits for all of them (default: 1)."
+        ),
+    )
+    parser.add_argument(
+        "--data-size-kb",
+        type=int,
+        default=256,
+        help="Data size per key in KB (default: 256).",
+    )
+    parser.add_argument(
+        "--l1-align-bytes",
+        type=int,
+        default=1,
+        help=(
+            "Alignment in bytes for benchmark L1 buffers. "
+            "Use 4096 when benchmarking O_DIRECT backends. Default: 1."
+        ),
+    )
+    parser.add_argument(
+        "--rounds",
+        type=int,
+        default=1,
+        help="Measurement rounds per operation (default: 1).",
+    )
+    parser.add_argument(
+        "--warmup-rounds",
+        type=int,
+        default=1,
+        help="Warmup rounds before measurement (default: 1).",
+    )
+    parser.add_argument(
+        "--lookup-max-hit-rate",
+        type=float,
+        default=0.0,
+        help=(
+            "Upper bound on the lookup hit rate, in [0, 1]. The "
+            "benchmark will request floor(N * rate) keys from the "
+            "potentially-existing range and (N - hit) keys from a "
+            "guaranteed-non-existent range, where N is the total "
+            "number of lookup keys (rounds * in_flight * num_keys). "
+            "The actual hit rate may be lower if those keys were "
+            "never stored. Default: 0.0."
+        ),
+    )
+    # Round-trip verification is OFF by default because it needs both
+    # store and load object batches resident at the same time.
+    # Use --no-skip-verify to enable verification.
+    parser.add_argument(
+        "--skip-verify",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Skip round-trip data verification (default). "
+            "Pass --no-skip-verify to enable verification."
+        ),
+    )
+    parser.add_argument(
+        "--only",
+        choices=["lookup", "store", "load"],
+        default=None,
+        help="Run only the specified operation (default: run all).",
+    )
+    parser.add_argument(
+        "--flamegraph",
+        choices=["on", "off"],
+        default="off",
+        help=(
+            "Capture a flame graph of the measured phases if turned on. The benchmark "
+            "profiles itself and renders an SVG"
+        ),
+    )
+    parser.add_argument(
+        "--flamegraph-mode",
+        choices=["on-cpu", "off-cpu"],
+        default="on-cpu",
+        help=(
+            "Flame-graph mode if enabled flame graph profiling. 'on-cpu' (perf "
+            "record) shows where CPU time goes; 'off-cpu' (perf off-CPU "
+            "via offcputime-bpfcc) shows time blocked on I/O / locks and "
+            "is best for I/O-bound adapters. Default: on-cpu."
+        ),
+    )
+    parser.add_argument(
+        "--flamegraph-output",
+        default="",
+        metavar="PATH",
+        help=(
+            "SVG output path for '--flamegraph on'. Default: "
+            "/tmp/lmcache_bench_flames/<adapter>.<mode>.svg."
+        ),
+    )
+    parser.add_argument(
+        "--flamegraph-dir",
+        default="",
+        metavar="DIR",
+        help=(
+            "Directory with the FlameGraph scripts (flamegraph.pl, "
+            "stackcollapse-perf.pl). Default: $FLAMEGRAPH_DIR or "
+            "~/FlameGraph, else auto-cloned into a temp directory."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Core benchmark runner
+# ---------------------------------------------------------------------------
+
+
+def run_l2_adapter_bench(command: "BaseCommand", args: argparse.Namespace) -> None:
+    """Run the L2 adapter benchmark.
+
+    Args:
+        command: The owning :class:`BaseCommand` instance, used only
+            to obtain a configured :class:`Metrics` object via
+            ``command.create_metrics``.
+        args: Parsed CLI arguments from the ``bench l2`` subparser.
+    """
+    # Lazy imports: keep CLI loadable without torch / native deps.
+    # First Party
+    from lmcache.cli.commands.bench.l2_adapter_bench.data import (
+        create_l1_memory_desc,
+        make_aligned_tensor,
+        make_memory_objects,
+        make_object_keys,
+        verify_round_trip,
+    )
+    from lmcache.cli.commands.bench.l2_adapter_bench.profiling import (
+        FlameProfiler,
+        ProfileError,
+        check_profiling_deps,
+        default_output_path,
+        resolve_flamegraph_dir,
+    )
+    from lmcache.cli.commands.bench.l2_adapter_bench.runner import (
+        bench_load,
+        bench_lookup,
+        bench_store,
+    )
+    from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+    from lmcache.v1.distributed.l2_adapters.config import (
+        parse_args_to_l2_adapters_config,
+    )
+
+    kb = 1024
+    mb = 1024 * 1024
+    data_size = args.data_size_kb * kb
+    l1_align_bytes = int(args.l1_align_bytes)
+    if l1_align_bytes <= 0:
+        print("Error: --l1-align-bytes must be positive", file=sys.stderr)
+        sys.exit(2)
+    if data_size % l1_align_bytes != 0:
+        print(
+            "Error: --data-size-kb must produce a payload size that is "
+            "a multiple of --l1-align-bytes",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    in_flight = args.in_flight
+    num_keys = args.num_keys
+    rounds = args.rounds
+    warmup = args.warmup_rounds
+    total_rounds = warmup + rounds
+    max_hit_rate = max(0.0, min(1.0, args.lookup_max_hit_rate))
+    quiet = getattr(args, "quiet", False)
+
+    # Keys per round (one in-flight wave) and total measured keys per
+    # operation. Warmup rounds extend the consumed idx range.
+    keys_per_round = in_flight * num_keys
+    total_run_keys = total_rounds * keys_per_round  # warmup + measured
+
+    def log(msg: str) -> None:
+        # Per-round progress log; suppressed by --quiet.
+        if not quiet:
+            print(msg)
+
+    # Resolve L2 adapter JSON: CLI arg takes priority, then env var
+    l2_adapter_specs = args.l2_adapter
+    if not l2_adapter_specs:
+        env_json = os.environ.get("L2_ADAPTER_JSON")
+        if env_json:
+            l2_adapter_specs = [env_json]
+        else:
+            print(
+                "Error: No L2 adapter configuration provided.\n"
+                "Use --l2-adapter JSON or set L2_ADAPTER_JSON "
+                "environment variable.",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+
+    # Parse adapter config using the standard LMCache mechanism
+    ns = argparse.Namespace(l2_adapter=l2_adapter_specs)
+    try:
+        l2_cfg = parse_args_to_l2_adapters_config(ns)
+    except (ValueError, KeyError) as e:
+        print(f"Error parsing L2 adapter config: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    if not l2_cfg.adapters:
+        print("Error: no L2 adapter configs parsed", file=sys.stderr)
+        sys.exit(2)
+
+    # Use the first adapter config for benchmarking
+    adapter_cfg = l2_cfg.adapters[0]
+
+    # Backing L1 memory buffer for adapters that need an L1 desc.
+    # Sized for one in-flight wave of store + load buffers.
+    l1_buffer = make_aligned_tensor(2 * keys_per_round * data_size, l1_align_bytes)
+    l1_memory_desc = create_l1_memory_desc(l1_buffer, align_bytes=l1_align_bytes)
+
+    # Resolve and validate the flame-graph toolchain up front, before any
+    # adapter (and its worker threads) is created. A user who explicitly
+    # passes ``--flamegraph on`` gets a fast, actionable failure if a
+    # required tool is missing, rather than a benchmark that silently runs
+    # unprofiled. When ``--flamegraph`` is off (default), none of this runs
+    # and the benchmark behaves exactly as before.
+    flamegraph_on = getattr(args, "flamegraph", "off") == "on"
+    flamegraph_dir = ""
+    if flamegraph_on:
+        try:
+            check_profiling_deps(args.flamegraph_mode)
+            flamegraph_dir = resolve_flamegraph_dir(args.flamegraph_dir, log)
+        except ProfileError as e:
+            print(
+                "Error: --flamegraph on was requested but the profiling "
+                f"toolchain is unavailable:\n  {e}",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+
+    log("\n[Init] Creating adapter...")
+    try:
+        adapter = create_l2_adapter(adapter_cfg, l1_memory_desc=l1_memory_desc)
+        log(f"[Init] Adapter created successfully ({type(adapter).__name__}).\n")
+    except Exception as e:
+        print(f"[Init] Failed to create adapter: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Optional self-profiling: record a flame graph of the measured
+    # phases. Built here, after the adapter (and its worker threads)
+    # exist, so the recorder attaches to a fully-started process. The
+    # toolchain was already validated above, so a ProfileError here is a
+    # late failure (e.g. the output directory is not writable); since the
+    # user explicitly requested a flame graph we fail loudly rather than
+    # downgrade, closing the adapter we just opened first.
+    profiler: FlameProfiler | None = None
+    if flamegraph_on:
+        adapter_name = type(adapter).__name__
+        try:
+            profiler = FlameProfiler(
+                mode=args.flamegraph_mode,
+                output=(
+                    args.flamegraph_output
+                    or default_output_path(adapter_name, args.flamegraph_mode)
+                ),
+                flamegraph_dir=flamegraph_dir,
+                pid=os.getpid(),
+                title=f"{args.flamegraph_mode} ({adapter_name})",
+            )
+        except ProfileError as e:
+            print(
+                f"Error: cannot start flame-graph profiling: {e}",
+                file=sys.stderr,
+            )
+            try:
+                adapter.close()
+            except Exception:
+                pass
+            sys.exit(2)
+
+    # ------------------------------------------------------------------
+    # Idx layout
+    # ------------------------------------------------------------------
+    # All ops live in the same idx universe so that ``--only store``
+    # followed by ``--only load`` (or lookup) with the same flags hits
+    # the exact same keys.
+    #
+    # Round r (0-indexed, warmup rounds first) consumes the idx slice
+    #   [r * keys_per_round, (r+1) * keys_per_round)
+    # split into ``in_flight`` contiguous batches of ``num_keys`` each.
+    #
+    # Lookup additionally splits each round into a hit-portion (drawn
+    # from the same idx range as store/load) and a miss-portion drawn
+    # from a guaranteed-non-existent range starting at
+    # ``total_run_keys``.
+    # ------------------------------------------------------------------
+
+    def _build_round_keys(r: int) -> list[list]:
+        """Build per-submit key batches for round *r* (store/load)."""
+        base = r * keys_per_round
+        return [
+            make_object_keys(num_keys, key_offset=base + i * num_keys)
+            for i in range(in_flight)
+        ]
+
+    def _build_round_objs(base_offset: int, fill_offset: int = 0) -> list[list]:
+        """Build per-submit object batches backed by the registered L1 buffer.
+
+        Some adapters register the L1 buffer passed through ``L1MemoryDesc``
+        during initialization. The benchmark objects must therefore be views
+        into that same buffer rather than independent tensors allocated
+        elsewhere.
+
+        ``fill_offset`` lets load buffers start with a pattern that differs
+        from store buffers, so round-trip verification catches silent no-op
+        loads that nevertheless report success.
+        """
+        return [
+            make_memory_objects(
+                l1_buffer,
+                num_keys,
+                data_size,
+                base_offset + i * num_keys * data_size,
+                fill_offset=fill_offset,
+            )
+            for i in range(in_flight)
+        ]
+
+    # Lookup hit/miss split per round.
+    per_round_hit = int(keys_per_round * max_hit_rate)
+    per_round_miss = keys_per_round - per_round_hit
+    # Total expected hit count over measured rounds only.
+    expected_hit_count = per_round_hit * rounds
+    # Origin of the guaranteed-miss idx range.
+    miss_origin = total_run_keys
+
+    def _build_lookup_round_keys(r: int) -> list[list]:
+        """Build per-submit lookup key batches for round *r*.
+
+        Hit slice for round r:
+          [r * per_round_hit, (r+1) * per_round_hit)
+        Miss slice for round r (disjoint from any store/load idx):
+          [miss_origin + r * per_round_miss,
+           miss_origin + (r+1) * per_round_miss)
+
+        The combined ``keys_per_round`` keys are concatenated then
+        split into ``in_flight`` chunks of ``num_keys`` each.
+        """
+        hit_base = r * per_round_hit
+        miss_base = miss_origin + r * per_round_miss
+        keys_round: list = []
+        keys_round.extend(make_object_keys(per_round_hit, key_offset=hit_base))
+        keys_round.extend(make_object_keys(per_round_miss, key_offset=miss_base))
+        # Split into in_flight equal-sized batches of num_keys.
+        return [keys_round[i * num_keys : (i + 1) * num_keys] for i in range(in_flight)]
+
+    # Per-direction object batches for store / load.
+    #
+    # Allocation strategy:
+    # * Lazy: only allocate when the corresponding direction is
+    #   actually exercised. With ``--only store`` we never touch
+    #   load buffers (and vice versa), saving
+    #   ``in_flight * num_keys * data_size`` bytes of host memory.
+    # * Cross-round reuse: once allocated, the same batches are
+    #   fed into every round; only the keys change per round. The
+    #   L2 adapter does not care about object identity across
+    #   rounds, and re-allocating these buffers each round would
+    #   just be wasted work.
+    store_obj_batches: list[list] | None = None
+    load_obj_batches: list[list] | None = None
+
+    def _store_objs(_r: int) -> list[list]:
+        nonlocal store_obj_batches
+        if store_obj_batches is None:
+            store_obj_batches = _build_round_objs(0)
+        return store_obj_batches
+
+    def _load_objs(_r: int) -> list[list]:
+        nonlocal load_obj_batches
+        if load_obj_batches is None:
+            load_obj_batches = _build_round_objs(
+                keys_per_round * data_size,
+                fill_offset=1,
+            )
+        return load_obj_batches
+
+    results: list = []
+    failed = False
+
+    # Track the very last measured store round so we can verify it
+    # against the matching load round (round-trip integrity check).
+    last_store_round_keys: list[list] | None = None
+    last_load_round_keys: list[list] | None = None
+
+    try:
+        if profiler is not None:
+            # Pre-build the payload buffers before the recorder starts so
+            # the one-time tensor allocation + fill (benchmark harness work,
+            # not the adapter) is kept out of the flame graph. The batches
+            # are reused across rounds, so this is the only build; warming
+            # it here keeps the recording focused on adapter I/O.
+            if args.only is None or args.only == "store":
+                _store_objs(0)
+            if args.only is None or args.only == "load":
+                _load_objs(0)
+            profiler.start(log)
+
+        # ---- Store ----
+        if args.only is None or args.only == "store":
+            log(f"[Store] Running {warmup} warmup + {rounds} measurement rounds...")
+            all_store = bench_store(
+                adapter,
+                in_flight=in_flight,
+                num_keys=num_keys,
+                data_size=data_size,
+                rounds=total_rounds,
+                keys_for_round=_build_round_keys,
+                objs_for_round=_store_objs,
+                log=log,
+            )
+            results.append(_strip_warmup(all_store, warmup))
+            # Last measured store round is total_rounds - 1.
+            last_store_round_keys = _build_round_keys(total_rounds - 1)
+            log("")
+
+        # ---- Lookup ----
+        if args.only is None or args.only == "lookup":
+            log(f"[Lookup] Running {warmup} warmup + {rounds} measurement rounds...")
+            all_lookup = bench_lookup(
+                adapter,
+                in_flight=in_flight,
+                num_keys=num_keys,
+                rounds=total_rounds,
+                keys_for_round=_build_lookup_round_keys,
+                log=log,
+                expected_max_hit_rate=max_hit_rate,
+                expected_hit_count=expected_hit_count,
+            )
+            results.append(_strip_warmup(all_lookup, warmup))
+            log("")
+
+        # ---- Load ----
+        if args.only is None or args.only == "load":
+            log(f"[Load] Running {warmup} warmup + {rounds} measurement rounds...")
+            all_load = bench_load(
+                adapter,
+                in_flight=in_flight,
+                num_keys=num_keys,
+                data_size=data_size,
+                rounds=total_rounds,
+                keys_for_round=_build_round_keys,
+                objs_for_round=_load_objs,
+                log=log,
+            )
+            results.append(_strip_warmup(all_load, warmup))
+            last_load_round_keys = _build_round_keys(total_rounds - 1)
+            log("")
+
+        # Stop profiling before verification / summary so the flame
+        # graph reflects only the measured store/lookup/load work.
+        if profiler is not None:
+            profiler.stop(log)
+
+        # ---- Round-trip verification (last measured round only) ----
+        if (
+            not args.skip_verify
+            and store_obj_batches is not None
+            and load_obj_batches is not None
+            and last_store_round_keys is not None
+            and last_load_round_keys is not None
+        ):
+            # Sanity: store and load used the same key idx range for
+            # the last measured round, and load buffers now hold what
+            # the adapter returned. Compare against the byte pattern
+            # written by the store object batch (i & 0xFF, where i is
+            # position within the batch).
+            log(
+                "[Verify] Checking store -> load data integrity for last "
+                "measured round..."
+            )
+            flat_keys = [k for kl in last_load_round_keys for k in kl]
+            flat_store = [o for ol in store_obj_batches for o in ol]
+            flat_load = [o for ol in load_obj_batches for o in ol]
+            ok = verify_round_trip(flat_keys, flat_store, flat_load, log)
+            if not ok:
+                failed = True
+            log("")
+
+        # ---- Summary via metrics system ----
+        _emit_l2_adapter_metrics(
+            command=command,
+            args=args,
+            l2_adapter_json=l2_adapter_specs[0],
+            keys_per_round=keys_per_round,
+            data_per_round_mb=(keys_per_round * data_size) / mb,
+            results=results,
+        )
+    finally:
+        # Idempotent: a no-op if profiling already stopped on the normal
+        # path; tears the recorder down if a phase raised.
+        if profiler is not None:
+            profiler.stop(log)
+        log("[Cleanup] Closing adapter...")
+        try:
+            adapter.close()
+        except Exception as e:
+            print(f"[Cleanup] adapter.close() failed: {e}", file=sys.stderr)
+        log("[Cleanup] Done.")
+
+    if failed:
+        sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _strip_warmup(result: "BenchResult", warmup: int) -> "BenchResult":
+    """Drop the leading *warmup* rounds from a BenchResult."""
+    # First Party
+    from lmcache.cli.commands.bench.l2_adapter_bench.result import BenchResult
+
+    # Adjust the expected hit count proportionally for the kept rounds.
+    kept_rounds = max(0, len(result.round_durations) - warmup)
+    total_rounds = max(1, len(result.round_durations))
+    scaled_expected_hit = int(result.expected_hit_count * kept_rounds / total_rounds)
+
+    return BenchResult(
+        operation=result.operation,
+        in_flight=result.in_flight,
+        num_keys=result.num_keys,
+        data_size_bytes=result.data_size_bytes,
+        round_durations=result.round_durations[warmup:],
+        success_counts=result.success_counts[warmup:],
+        expected_max_hit_rate=result.expected_max_hit_rate,
+        expected_hit_count=scaled_expected_hit,
+    )
+
+
+def _emit_l2_adapter_metrics(
+    command: "BaseCommand",
+    args: argparse.Namespace,
+    l2_adapter_json: str,
+    keys_per_round: int,
+    data_per_round_mb: float,
+    results: list,
+) -> None:
+    """Emit L2 adapter benchmark summary using the CLI metrics system."""
+    title = "L2 Adapter Benchmark Result"
+    metrics = command.create_metrics(title, args, width=64)
+
+    cfg_section = metrics.add_section("config", "Configuration")
+    cfg_section.add("l2_adapter_json", "L2 adapter JSON", l2_adapter_json)
+    cfg_section.add("num_keys", "Keys / submit", args.num_keys)
+    cfg_section.add("in_flight", "In-flight / round", args.in_flight)
+    cfg_section.add("keys_per_round", "Keys / round", keys_per_round)
+    cfg_section.add(
+        "data_size_kb",
+        "Data size / key (KB)",
+        args.data_size_kb,
+    )
+    cfg_section.add(
+        "data_per_round_mb",
+        "Data / round (MB)",
+        round(data_per_round_mb, 2),
+    )
+    cfg_section.add("measurement_rounds", "Measurement rounds", args.rounds)
+    cfg_section.add("warmup_rounds", "Warmup rounds", args.warmup_rounds)
+    # Only meaningful when lookup is actually executed; matches the
+    # original banner log behaviour.
+    if args.only is None or args.only == "lookup":
+        cfg_section.add(
+            "lookup_max_hit_rate",
+            "Lookup max hit rate",
+            round(args.lookup_max_hit_rate, 4),
+        )
+
+    for idx, r in enumerate(results):
+        section_id = f"op_{idx}"
+        section = metrics.add_section(section_id, r.operation)
+        section.add("operation", "Operation", r.operation)
+        section.add("rounds", "Rounds", len(r.round_durations))
+        section.add("keys_per_round", "Keys / round", r.keys_per_round)
+        section.add("total_keys", "Total keys", r.total_keys)
+        section.add("total_success", "Total success", r.total_success)
+        section.add(
+            "duration_avg_ms",
+            "Duration avg (ms)",
+            round(r.avg_duration * 1000, 2),
+        )
+        section.add(
+            "duration_min_ms",
+            "Duration min (ms)",
+            round(r.min_duration * 1000, 2),
+        )
+        section.add(
+            "duration_max_ms",
+            "Duration max (ms)",
+            round(r.max_duration * 1000, 2),
+        )
+        section.add(
+            "duration_p50_ms",
+            "Duration p50 (ms)",
+            round(r.p50_duration * 1000, 2),
+        )
+        section.add(
+            "duration_p99_ms",
+            "Duration p99 (ms)",
+            round(r.p99_duration * 1000, 2),
+        )
+        section.add(
+            "duration_std_ms",
+            "Duration std (ms)",
+            round(r.std_duration * 1000, 2),
+        )
+        section.add(
+            "throughput_avg_mbps",
+            "Throughput avg (MB/s)",
+            round(r.avg_throughput_mbps, 2),
+        )
+        section.add(
+            "throughput_min_mbps",
+            "Throughput min (MB/s)",
+            round(r.min_throughput_mbps, 2),
+        )
+        section.add(
+            "throughput_max_mbps",
+            "Throughput max (MB/s)",
+            round(r.max_throughput_mbps, 2),
+        )
+        section.add(
+            "ops_per_sec_avg",
+            "Avg ops/s",
+            round(r.avg_ops_per_sec, 2),
+        )
+        section.add(
+            "latency_per_key_ms",
+            "Avg latency / key (ms)",
+            round(r.avg_latency_per_key_ms, 3),
+        )
+        if r.expected_max_hit_rate > 0 or r.expected_hit_count > 0:
+            section.add(
+                "expected_max_hit_rate",
+                "Expected max hit rate",
+                round(r.expected_max_hit_rate, 4),
+            )
+            section.add(
+                "expected_hit_count",
+                "Expected hit keys",
+                r.expected_hit_count,
+            )
+            section.add(
+                "actual_hit_rate",
+                "Actual hit rate",
+                round(r.actual_hit_rate, 4),
+            )
+
+    metrics.emit()
diff --git a/lmcache/cli/commands/bench/l2_adapter_bench/data.py b/lmcache/cli/commands/bench/l2_adapter_bench/data.py
new file mode 100644
index 0000000..6224a8f
--- /dev/null
+++ b/lmcache/cli/commands/bench/l2_adapter_bench/data.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Test data construction helpers for L2 adapter benchmarks."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import select
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_KB = 1024
+
+
+def make_aligned_tensor(num_bytes: int, align_bytes: int = 1) -> torch.Tensor:
+    """Create a 1-D uint8 tensor whose data pointer is aligned.
+
+    Args:
+        num_bytes: Number of bytes in the returned tensor.
+        align_bytes: Required data pointer alignment in bytes.
+
+    Returns:
+        A 1-D ``torch.uint8`` tensor with ``num_bytes`` elements.
+
+    Raises:
+        ValueError: If ``num_bytes`` is negative or ``align_bytes`` is
+            not positive.
+        RuntimeError: If the allocated tensor cannot be aligned.
+    """
+    if num_bytes < 0:
+        raise ValueError("num_bytes must be non-negative")
+    if align_bytes <= 0:
+        raise ValueError("align_bytes must be positive")
+    if align_bytes == 1:
+        return torch.empty(num_bytes, dtype=torch.uint8)
+
+    backing = torch.empty(num_bytes + align_bytes - 1, dtype=torch.uint8)
+    offset = (-backing.data_ptr()) % align_bytes
+    aligned = backing[offset : offset + num_bytes]
+    if aligned.data_ptr() % align_bytes != 0:
+        raise RuntimeError(
+            f"failed to allocate {align_bytes}-byte aligned benchmark buffer"
+        )
+    return aligned
+
+
+def make_object_keys(
+    num_keys: int, model_name: str = "bench-model", key_offset: int = 0
+) -> list[ObjectKey]:
+    """Generate *num_keys* unique ``ObjectKey`` instances for benchmarking.
+
+    ``ObjectKey`` is a frozen dataclass with field order:
+    (chunk_hash, model_name, kv_rank).
+
+    Args:
+        num_keys: Number of keys to generate.
+        model_name: Model name embedded in each key.
+        key_offset: Starting index offset to ensure uniqueness across threads.
+    """
+    keys: list[ObjectKey] = []
+    for i in range(num_keys):
+        idx = key_offset + i
+        # chunk_hash: 16 bytes derived from index to guarantee uniqueness
+        chunk_hash = idx.to_bytes(16, "big")
+        keys.append(
+            ObjectKey(
+                chunk_hash=chunk_hash,
+                model_name=model_name,
+                kv_rank=idx,
+            )
+        )
+    return keys
+
+
+def make_memory_objects(
+    buffer: torch.Tensor,
+    num_keys: int,
+    data_size: int,
+    base_offset: int,
+    fill_offset: int = 0,
+) -> list[MemoryObj]:
+    """Create MemoryObj views backed by a shared L1 benchmark buffer.
+
+    Each returned object is a ``data_size``-byte slice of ``buffer``,
+    pre-filled with a distinguishing byte pattern
+    ``(key_index + fill_offset) mod 256`` so that ``verify_round_trip``
+    can detect cross-key corruption after a store -> load cycle.
+
+    Args:
+        buffer: Contiguous benchmark L1 buffer that backs all objects.
+        num_keys: Number of memory objects to create.
+        data_size: Size of each memory object in bytes.
+        base_offset: Byte offset of the first object within ``buffer``.
+        fill_offset: Offset added to each key index before generating the
+            byte fill pattern.
+
+    Returns:
+        ``TensorMemoryObj`` instances whose ``raw_data`` tensors are views
+        into ``buffer``.
+
+    Raises:
+        ValueError: If the requested object range falls outside ``buffer``.
+    """
+    flat_buffer = buffer.view(-1)
+    objects: list[MemoryObj] = []
+    for i in range(num_keys):
+        start = base_offset + i * data_size
+        end = start + data_size
+        if start < 0 or end > flat_buffer.numel():
+            raise ValueError(
+                f"L1 benchmark buffer too small for object {i}: "
+                f"[{start}, {end}) > {flat_buffer.numel()}"
+            )
+        raw_tensor = flat_buffer[start:end]
+        raw_tensor.fill_((i + fill_offset) & 0xFF)
+        metadata = MemoryObjMetadata(
+            shape=torch.Size([data_size]),
+            dtype=torch.uint8,
+            address=raw_tensor.data_ptr(),
+            phy_size=data_size * raw_tensor.element_size(),
+            fmt=MemoryFormat.KV_2LTD,
+            ref_count=1,
+        )
+        objects.append(
+            TensorMemoryObj(
+                raw_data=raw_tensor,
+                metadata=metadata,
+                parent_allocator=None,
+            )
+        )
+    return objects
+
+
+def create_l1_memory_desc(
+    buffer: torch.Tensor,
+    align_bytes: int = 1,
+) -> L1MemoryDesc:
+    """Create an L1 memory descriptor for a contiguous test buffer."""
+    flat_buffer = buffer.view(-1)
+    return L1MemoryDesc(
+        ptr=flat_buffer.data_ptr(),
+        size=flat_buffer.numel() * flat_buffer.element_size(),
+        align_bytes=align_bytes,
+    )
+
+
+def wait_eventfd(efd: int, timeout: float = 60.0) -> bool:
+    """Block until the eventfd is signalled or *timeout* seconds elapse.
+
+    Uses ``select.poll`` + ``consume_fd`` for cross-platform compatibility.
+
+    Returns True if the fd was signalled, False on timeout.
+    """
+    poller = select.poll()
+    poller.register(efd, select.POLLIN)
+    # poll() expects timeout in milliseconds
+    events = poller.poll(timeout * 1000)
+    if events:
+        consume_fd(efd)
+        return True
+    return False
+
+
+def verify_round_trip(keys, store_objects, load_objects, log) -> bool:
+    """Verify that loaded data matches what was stored.
+
+    Compares the underlying ``raw_data`` tensors directly (more efficient
+    than converting via ``byte_array``).
+    """
+    mismatches = 0
+    for i, (s_obj, l_obj) in enumerate(zip(store_objects, load_objects, strict=True)):
+        if not torch.equal(s_obj.raw_data, l_obj.raw_data):
+            mismatches += 1
+            log(
+                f"  [Verify] Key {i}: MISMATCH "
+                f"(store {s_obj.get_physical_size()} bytes "
+                f"vs load {l_obj.get_physical_size()} bytes)"
+            )
+    if mismatches == 0:
+        log(f"  [Verify] All {len(keys)} keys data verified OK.")
+        return True
+    log(f"  [Verify] {mismatches}/{len(keys)} keys have data mismatches!")
+    return False
diff --git a/lmcache/cli/commands/bench/l2_adapter_bench/profiling.py b/lmcache/cli/commands/bench/l2_adapter_bench/profiling.py
new file mode 100644
index 0000000..f7c1257
--- /dev/null
+++ b/lmcache/cli/commands/bench/l2_adapter_bench/profiling.py
@@ -0,0 +1,359 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Profiling tools for benchmarking lmcache performance.
+
+When ``--flamegraph on`` is set, the benchmark records a flame graph of
+its own measured phases and renders it to an SVG, so no second terminal
+or externally attached profiler is needed.
+
+Two modes are supported:
+
+* ``on-cpu``  -- ``perf record`` sampling; shows where CPU time goes
+  (serialization, copies, hashing).
+* ``off-cpu`` -- ``offcputime-bpfcc`` (bcc); shows time spent blocked
+  off-CPU (waiting on I/O, locks, eventfds), usually the more
+  informative view for I/O-bound L2 adapters.
+
+Rendering uses Brendan Gregg's FlameGraph scripts (``flamegraph.pl`` and,
+for on-CPU, ``stackcollapse-perf.pl``). ``off-cpu`` additionally requires
+``sudo`` because ``offcputime-bpfcc`` loads a BPF program.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Callable
+import os
+import shutil
+import signal
+import subprocess
+import time
+
+# Sampling frequency for ``perf record`` (on-CPU), in Hz.
+_PERF_FREQ_HZ = 999
+# Seconds to wait for a recorder to flush and exit after SIGINT.
+_STOP_TIMEOUT_SEC = 60
+# Seconds to let the off-CPU BPF program load before the work starts.
+_OFFCPU_SETTLE_SEC = 1.0
+# Rendered flame-graph width, in pixels.
+_FLAME_WIDTH_PX = 1600
+
+# Per-mode tag used in default output filenames.
+_MODE_TAG = {"on-cpu": "oncpu", "off-cpu": "offcpu"}
+
+
+class ProfileError(RuntimeError):
+    """Raised when the profiling toolchain is missing or misconfigured."""
+
+
+def check_profiling_deps(mode: str) -> None:
+    """Validate that the external tools required for *mode* are present.
+
+    This is a runtime check meant to run *before* the benchmark spins up
+    any adapter, so a missing dependency fails fast with an actionable
+    message instead of producing an empty flame graph midway through a
+    run.
+
+    Args:
+        mode: ``"on-cpu"`` or ``"off-cpu"``.
+
+    Raises:
+        ProfileError: If ``mode`` is invalid or a required tool is
+            missing. The message names the missing tool and how to
+            install it or which mode to use instead.
+    """
+    if mode not in _MODE_TAG:
+        raise ProfileError(
+            f"invalid flame-graph mode: {mode!r} (expected 'on-cpu' or 'off-cpu')"
+        )
+    if mode == "on-cpu" and shutil.which("perf") is None:
+        raise ProfileError(
+            "perf not found on PATH (needed for on-cpu flame graphs). "
+            "Install it (e.g. 'apt install linux-perf' or the linux-tools "
+            "package matching your kernel) or use --flamegraph-mode off-cpu."
+        )
+    if mode == "off-cpu":
+        if shutil.which("sudo") is None:
+            raise ProfileError(
+                "sudo not found on PATH (needed for off-cpu flame graphs, "
+                "which load a BPF program). Install sudo or use "
+                "--flamegraph-mode on-cpu."
+            )
+        # offcputime-bpfcc usually lives in /usr/sbin, which is not on the
+        # user's PATH but is reachable under sudo; check both so a missing
+        # tool surfaces here instead of as an empty flame graph.
+        if shutil.which("offcputime-bpfcc") is None and not os.path.exists(
+            "/usr/sbin/offcputime-bpfcc"
+        ):
+            raise ProfileError(
+                "offcputime-bpfcc not found (needed for off-cpu flame "
+                "graphs). Install bcc / bpfcc-tools (e.g. 'apt install "
+                "bpfcc-tools') or use --flamegraph-mode on-cpu."
+            )
+
+
+# Upstream FlameGraph repo, shallow-cloned on demand when the scripts
+# are not already present locally.
+_FLAMEGRAPH_REPO = "https://github.com/brendangregg/FlameGraph"
+
+
+def _managed_flamegraph_dir() -> str:
+    """Return the temp path where FlameGraph is auto-cloned."""
+    return "/tmp/lmcache_flamegraph/FlameGraph"
+
+
+def _has_flamegraph(flamegraph_dir: str) -> bool:
+    """Return True if ``flamegraph.pl`` exists under *flamegraph_dir*."""
+    return os.path.isfile(os.path.join(flamegraph_dir, "flamegraph.pl"))
+
+
+def _clone_flamegraph(dest: str, log: Callable[[str], None]) -> None:
+    """Shallow-clone the FlameGraph repo into *dest*."""
+    if shutil.which("git") is None:
+        raise ProfileError(
+            "git not found; cannot auto-clone FlameGraph. Clone "
+            f"{_FLAMEGRAPH_REPO} manually and pass --flamegraph-dir "
+            "or set FLAMEGRAPH_DIR."
+        )
+    os.makedirs(os.path.dirname(dest), exist_ok=True)
+    log(f"[Profile] FlameGraph not found; cloning {_FLAMEGRAPH_REPO} -> {dest}")
+    try:
+        subprocess.run(
+            ["git", "clone", "--depth", "1", _FLAMEGRAPH_REPO, dest],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+        )
+    except subprocess.CalledProcessError as e:
+        detail = e.stderr.decode(errors="replace").strip() if e.stderr else str(e)
+        raise ProfileError(f"git clone of FlameGraph failed: {detail}") from e
+    if not _has_flamegraph(dest):
+        raise ProfileError(f"clone completed but flamegraph.pl missing in {dest}")
+
+
+def resolve_flamegraph_dir(explicit: str, log: Callable[[str], None]) -> str:
+    """Resolve the FlameGraph scripts directory, auto-cloning if needed.
+
+    Resolution order: the explicit ``--flamegraph-dir`` value,
+    then ``$FLAMEGRAPH_DIR``, then ``~/FlameGraph``, then the managed temp
+    clone under ``/tmp/lmcache_flamegraph/FlameGraph``. When none of these
+    contains ``flamegraph.pl`` and no directory was given explicitly, the
+    repo is shallow-cloned into the managed temp location.
+
+    Args:
+        explicit: Directory passed via ``--flamegraph-dir``; may
+            be an empty string when the flag was not given.
+        log: Progress logger (suppressed under ``--quiet``).
+
+    Returns:
+        A directory that contains ``flamegraph.pl``.
+
+    Raises:
+        ProfileError: If an explicit directory lacks the scripts, or the
+            scripts are missing and the auto-clone fails.
+    """
+    if explicit:
+        if not _has_flamegraph(explicit):
+            raise ProfileError(
+                f"flamegraph.pl not found under --flamegraph-dir {explicit}"
+            )
+        return explicit
+
+    for candidate in (
+        os.environ.get("FLAMEGRAPH_DIR", ""),
+        os.path.expanduser("~/FlameGraph"),
+        _managed_flamegraph_dir(),
+    ):
+        if candidate and _has_flamegraph(candidate):
+            return candidate
+
+    # Not found anywhere: auto-clone into the managed cache location.
+    dest = _managed_flamegraph_dir()
+    _clone_flamegraph(dest, log)
+    return dest
+
+
+def default_output_path(adapter_name: str, mode: str) -> str:
+    """Build the default SVG output path for a profiling run.
+
+    Args:
+        adapter_name: Adapter class name, used in the filename.
+        mode: ``"on-cpu"`` or ``"off-cpu"``.
+
+    Returns:
+        An absolute path under ``/tmp/lmcache_bench_flames``.
+    """
+    tag = _MODE_TAG.get(mode, mode)
+    return f"/tmp/lmcache_bench_flames/{adapter_name}.{tag}.svg"
+
+
+class FlameProfiler:
+    """Struct wrapper for managing flame-chart profiling.
+
+    It starts a separate process to profile the target process, and
+    renders the captured data to a flame chart.
+    """
+
+    def __init__(
+        self,
+        *,
+        mode: str,
+        output: str,
+        flamegraph_dir: str,
+        pid: int,
+        title: str,
+    ) -> None:
+        """Validate the toolchain and prepare output paths.
+
+        Args:
+            mode: ``"on-cpu"`` or ``"off-cpu"``.
+            output: SVG output path.
+            flamegraph_dir: Directory holding the FlameGraph scripts.
+            pid: Process id to profile (the benchmark process itself).
+            title: Flame-graph title.
+
+        Raises:
+            ProfileError: If ``mode`` is invalid or a required tool is
+                unavailable.
+        """
+        check_profiling_deps(mode)
+
+        self._mode = mode
+        self._output = output
+        self._flamegraph_dir = flamegraph_dir
+        self._pid = pid
+        self._title = title
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._raw_fh: object = None
+        # Intermediate capture file (perf.data for on-cpu, folded
+        # stacks for off-cpu); removed after a successful render.
+        suffix = ".perf.data" if mode == "on-cpu" else ".folded"
+        self._raw_path = output + suffix
+        self._stopped = False
+
+        out_dir = os.path.dirname(os.path.abspath(output))
+        os.makedirs(out_dir, exist_ok=True)
+
+    def start(self, log: Callable[[str], None]) -> None:
+        """Start the background recorder targeting the profiled process."""
+        if self._mode == "on-cpu":
+            self._proc = subprocess.Popen(
+                [
+                    "perf",
+                    "record",
+                    "-F",
+                    str(_PERF_FREQ_HZ),
+                    "-g",
+                    "-p",
+                    str(self._pid),
+                    "-o",
+                    self._raw_path,
+                ],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        else:
+            self._raw_fh = open(self._raw_path, "wb")
+            self._proc = subprocess.Popen(
+                ["sudo", "offcputime-bpfcc", "-df", "-p", str(self._pid)],
+                stdout=self._raw_fh,  # type: ignore[arg-type]
+                stderr=subprocess.DEVNULL,
+            )
+            # The BPF program takes a moment to load; give it time so the
+            # first stretch of the measured phase is not missed.
+            time.sleep(_OFFCPU_SETTLE_SEC)
+        log(
+            f"[Profile] {self._mode} recording started (pid={self._pid}) "
+            f"-> {self._output}"
+        )
+
+    def stop(self, log: Callable[[str], None]) -> None:
+        """Stop the recorder and render the SVG. Idempotent."""
+        if self._stopped:
+            return
+        self._stopped = True
+        if self._proc is None:
+            return
+
+        # SIGINT makes both perf and offcputime-bpfcc flush their output
+        # and exit cleanly (sudo forwards the signal to offcputime).
+        try:
+            self._proc.send_signal(signal.SIGINT)
+        except ProcessLookupError:
+            pass
+        try:
+            self._proc.wait(timeout=_STOP_TIMEOUT_SEC)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+            self._proc.wait()
+        if self._raw_fh is not None:
+            self._raw_fh.close()  # type: ignore[attr-defined]
+            self._raw_fh = None
+
+        log("[Profile] rendering flame graph...")
+        try:
+            self._render()
+        except ProfileError as e:
+            log(f"[Profile] render failed: {e}")
+            return
+        for leftover in (self._raw_path, self._raw_path + ".old"):
+            try:
+                os.remove(leftover)
+            except OSError:
+                pass
+        log(f"[Profile] wrote {self._output}")
+
+    def _render(self) -> None:
+        """Render the captured stacks into viewable flamechart at path at self._path"""
+        flamegraph_pl = os.path.join(self._flamegraph_dir, "flamegraph.pl")
+        try:
+            with open(self._output, "wb") as svg:
+                if self._mode == "on-cpu":
+                    collapse_pl = os.path.join(
+                        self._flamegraph_dir, "stackcollapse-perf.pl"
+                    )
+                    script = subprocess.Popen(
+                        ["perf", "script", "-i", self._raw_path],
+                        stdout=subprocess.PIPE,
+                        stderr=subprocess.DEVNULL,
+                    )
+                    collapse = subprocess.Popen(
+                        [collapse_pl],
+                        stdin=script.stdout,
+                        stdout=subprocess.PIPE,
+                    )
+                    flame = subprocess.Popen(
+                        [
+                            flamegraph_pl,
+                            "--title",
+                            self._title,
+                            "--width",
+                            str(_FLAME_WIDTH_PX),
+                        ],
+                        stdin=collapse.stdout,
+                        stdout=svg,
+                    )
+                    flame.communicate()
+                    rc = flame.returncode
+                else:
+                    with open(self._raw_path, "rb") as folded:
+                        flame = subprocess.Popen(
+                            [
+                                flamegraph_pl,
+                                "--color=io",
+                                "--countname",
+                                "us",
+                                "--title",
+                                self._title,
+                                "--width",
+                                str(_FLAME_WIDTH_PX),
+                            ],
+                            stdin=folded,
+                            stdout=svg,
+                        )
+                        flame.communicate()
+                        rc = flame.returncode
+        except OSError as e:
+            raise ProfileError(str(e)) from e
+        if rc != 0:
+            raise ProfileError(f"flamegraph.pl exited with code {rc}")
diff --git a/lmcache/cli/commands/bench/l2_adapter_bench/result.py b/lmcache/cli/commands/bench/l2_adapter_bench/result.py
new file mode 100644
index 0000000..eaadec0
--- /dev/null
+++ b/lmcache/cli/commands/bench/l2_adapter_bench/result.py
@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Aggregated benchmark statistics for L2 adapter operations."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+import statistics
+
+_KB = 1024
+_MB = 1024 * 1024
+
+
+def _percentile(values: list[float], pct: float) -> float:
+    """Return the percentile *pct* (0..100) using nearest-rank.
+
+    Returns 0.0 for an empty list.
+    """
+    if not values:
+        return 0.0
+    if len(values) == 1:
+        return values[0]
+    sorted_vals = sorted(values)
+    # Nearest-rank method: rank = ceil(pct/100 * N)
+    rank = max(1, int((pct / 100.0) * len(sorted_vals) + 0.999999))
+    rank = min(rank, len(sorted_vals))
+    return sorted_vals[rank - 1]
+
+
+@dataclass
+class BenchResult:
+    """Aggregated benchmark statistics for one operation type.
+
+    Each measured *round* issues ``in_flight`` submits, where each submit
+    carries ``num_keys`` keys. ``round_durations[r]`` is the wall-clock
+    elapsed for the whole round (from issuing the first submit to all
+    submits of that round completing).
+    """
+
+    operation: str
+    in_flight: int
+    num_keys: int
+    data_size_bytes: int
+    round_durations: list[float] = field(default_factory=list)
+    success_counts: list[int] = field(default_factory=list)
+    # Lookup-specific metadata (left as defaults for store/load).
+    expected_max_hit_rate: float = 0.0
+    expected_hit_count: int = 0
+
+    # ------------------------------------------------------------------
+    # Derived counts
+    # ------------------------------------------------------------------
+
+    @property
+    def keys_per_round(self) -> int:
+        return self.in_flight * self.num_keys
+
+    @property
+    def total_keys(self) -> int:
+        return self.keys_per_round * len(self.round_durations)
+
+    @property
+    def total_data_bytes_per_round(self) -> int:
+        return self.keys_per_round * self.data_size_bytes
+
+    @property
+    def total_data_bytes(self) -> int:
+        return self.total_keys * self.data_size_bytes
+
+    @property
+    def total_success(self) -> int:
+        return sum(self.success_counts)
+
+    # ------------------------------------------------------------------
+    # Duration stats (seconds)
+    # ------------------------------------------------------------------
+
+    @property
+    def avg_duration(self) -> float:
+        return statistics.mean(self.round_durations) if self.round_durations else 0.0
+
+    @property
+    def min_duration(self) -> float:
+        return min(self.round_durations) if self.round_durations else 0.0
+
+    @property
+    def max_duration(self) -> float:
+        return max(self.round_durations) if self.round_durations else 0.0
+
+    @property
+    def std_duration(self) -> float:
+        if len(self.round_durations) > 1:
+            return statistics.stdev(self.round_durations)
+        return 0.0
+
+    @property
+    def p50_duration(self) -> float:
+        return _percentile(self.round_durations, 50.0)
+
+    @property
+    def p99_duration(self) -> float:
+        return _percentile(self.round_durations, 99.0)
+
+    # ------------------------------------------------------------------
+    # Throughput stats (per-round, MB/s)
+    # ------------------------------------------------------------------
+
+    @property
+    def per_round_throughput_mbps(self) -> list[float]:
+        if self.data_size_bytes <= 0:
+            return []
+        bytes_per_round = self.total_data_bytes_per_round
+        out: list[float] = []
+        for d in self.round_durations:
+            if d <= 0:
+                out.append(float("inf"))
+            else:
+                out.append((bytes_per_round / _MB) / d)
+        return out
+
+    @property
+    def avg_throughput_mbps(self) -> float:
+        vals = self.per_round_throughput_mbps
+        return statistics.mean(vals) if vals else 0.0
+
+    @property
+    def min_throughput_mbps(self) -> float:
+        vals = self.per_round_throughput_mbps
+        return min(vals) if vals else 0.0
+
+    @property
+    def max_throughput_mbps(self) -> float:
+        vals = self.per_round_throughput_mbps
+        return max(vals) if vals else 0.0
+
+    # ------------------------------------------------------------------
+    # Ops/sec (key-rate) stats — useful for lookup which has no payload
+    # ------------------------------------------------------------------
+
+    @property
+    def per_round_ops_per_sec(self) -> list[float]:
+        out: list[float] = []
+        for d in self.round_durations:
+            if d <= 0:
+                out.append(float("inf"))
+            else:
+                out.append(self.keys_per_round / d)
+        return out
+
+    @property
+    def avg_ops_per_sec(self) -> float:
+        vals = self.per_round_ops_per_sec
+        return statistics.mean(vals) if vals else 0.0
+
+    # ------------------------------------------------------------------
+    # Misc
+    # ------------------------------------------------------------------
+
+    @property
+    def avg_success_per_round(self) -> float:
+        return statistics.mean(self.success_counts) if self.success_counts else 0.0
+
+    @property
+    def avg_latency_per_key_ms(self) -> float:
+        if self.keys_per_round <= 0:
+            return 0.0
+        return (self.avg_duration / self.keys_per_round) * 1000
+
+    @property
+    def actual_hit_rate(self) -> float:
+        if self.total_keys <= 0:
+            return 0.0
+        return self.total_success / self.total_keys
diff --git a/lmcache/cli/commands/bench/l2_adapter_bench/runner.py b/lmcache/cli/commands/bench/l2_adapter_bench/runner.py
new file mode 100644
index 0000000..4408d76
--- /dev/null
+++ b/lmcache/cli/commands/bench/l2_adapter_bench/runner.py
@@ -0,0 +1,332 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Benchmark runners for L2 adapter ops.
+
+Each round issues ``in_flight`` submits sequentially from the calling
+thread, then waits for ``in_flight`` eventfd notifications before
+recording the round duration. This matches the real-world usage pattern
+where multiple producers submit tasks and the L2 adapter's worker
+coroutine processes them.
+
+The benchmark itself is single-threaded on the producer side; the
+adapter internally is free to use threads / coroutines / async I/O.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Callable
+import time
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.memory_management import MemoryObj
+
+# Local
+from .data import wait_eventfd
+from .result import BenchResult
+
+# Logger callable type: takes a single string and prints / logs it.
+LogFn = Callable[[str], None]
+
+# Provider callable signatures used by the runners. They are invoked at
+# the start of every round and must return ``in_flight`` lists, one per
+# in-flight submit, of length ``num_keys`` each.
+KeyProvider = Callable[[int], list[list[ObjectKey]]]
+ObjProvider = Callable[[int], list[list[MemoryObj]]]
+
+# TODO: bench passes a placeholder layout_desc; a real layout may be
+# required here in the future (e.g. when benchmarking the P2P adapter).
+_PLACEHOLDER_LAYOUT_DESC = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+
+def _bitmap_count(bitmap: Bitmap | None) -> int:
+    """Count how many bits are set in *bitmap*. Returns 0 when None."""
+    if bitmap is None:
+        return 0
+    return bitmap.popcount()
+
+
+def _wait_store_finished(
+    adapter, task_ids: list[int], timeout: float
+) -> dict[int, L2StoreResult]:
+    """Wait for all store tasks to finish.
+
+    Returns the accumulated ``{task_id: L2StoreResult}`` dict.
+    ``pop_completed_store_tasks`` consumes the adapter's completion
+    dict, so we must accumulate the results here for the caller to
+    use. On timeout, returns whatever was harvested so far (possibly
+    empty or partial); the caller can detect timeout by comparing
+    ``len(returned_dict)`` against ``len(task_ids)``.
+    """
+    unfinished = len(task_ids)
+    efd = adapter.get_store_event_fd()
+    completed: dict[int, L2StoreResult] = {}
+    while unfinished > 0:
+        if not wait_eventfd(efd, timeout=timeout):
+            return completed
+        batch = adapter.pop_completed_store_tasks()
+        completed.update(batch)
+        unfinished -= len(batch)
+    return completed
+
+
+def _wait_load_finished(
+    adapter, task_ids: list[int], timeout: float
+) -> dict[int, Bitmap]:
+    """Wait for all load tasks to finish.
+
+    Returns ``{task_id: bitmap}``. ``query_load_result`` consumes the
+    per-task result, so we cache the bitmaps here for the caller.
+    Already-finished tasks are removed from the pending set so
+    subsequent wakeups don't re-query them. On timeout, returns
+    whatever was harvested so far; the caller can detect timeout by
+    comparing ``len(returned_dict)`` against ``len(task_ids)``.
+    """
+    pending = set(task_ids)
+    efd = adapter.get_load_event_fd()
+    results: dict[int, Bitmap] = {}
+    while pending:
+        if not wait_eventfd(efd, timeout=timeout):
+            return results
+        for task_id in list(pending):
+            bitmap = adapter.query_load_result(task_id)
+            if bitmap is not None:
+                results[task_id] = bitmap
+                pending.remove(task_id)
+    return results
+
+
+def _wait_lookup_finished(
+    adapter, task_ids: list[int], timeout: float
+) -> dict[int, Bitmap]:
+    """Wait for all lookup-and-lock tasks to finish.
+
+    Returns ``{task_id: bitmap}``. ``query_lookup_and_lock_result``
+    consumes the per-task result, so we cache the bitmaps here for
+    the caller. Already-finished tasks are removed from the pending
+    set so subsequent wakeups don't re-query them. On timeout,
+    returns whatever was harvested so far; the caller can detect
+    timeout by comparing ``len(returned_dict)`` against
+    ``len(task_ids)``.
+    """
+    pending = set(task_ids)
+    efd = adapter.get_lookup_and_lock_event_fd()
+    results: dict[int, Bitmap] = {}
+    while pending:
+        if not wait_eventfd(efd, timeout=timeout):
+            return results
+        for task_id in list(pending):
+            bitmap = adapter.query_lookup_and_lock_result(task_id)
+            if bitmap is not None:
+                results[task_id] = bitmap
+                pending.remove(task_id)
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Store
+# ---------------------------------------------------------------------------
+
+
+def bench_store(
+    adapter,
+    in_flight: int,
+    num_keys: int,
+    data_size: int,
+    rounds: int,
+    keys_for_round: KeyProvider,
+    objs_for_round: ObjProvider,
+    log: LogFn,
+) -> BenchResult:
+    """Benchmark ``submit_store_task``.
+
+    For each round, ``in_flight`` independent submits are issued; the
+    round duration is the wall-clock time from the first submit until
+    every submit of that round has completed.
+    """
+    result = BenchResult(
+        operation="Store",
+        in_flight=in_flight,
+        num_keys=num_keys,
+        data_size_bytes=data_size,
+    )
+
+    for r in range(rounds):
+        keys_batches = keys_for_round(r)
+        obj_batches = objs_for_round(r)
+        assert len(keys_batches) == in_flight
+        assert len(obj_batches) == in_flight
+
+        t0 = time.perf_counter()
+        task_ids: list[int] = []
+        for i in range(in_flight):
+            task_ids.append(adapter.submit_store_task(keys_batches[i], obj_batches[i]))
+
+        completed = _wait_store_finished(adapter, task_ids, 120.0)
+        t1 = time.perf_counter()
+        elapsed = t1 - t0
+        timed_out = len(completed) < len(task_ids)
+
+        success_keys = sum(
+            len(keys_batches[i])
+            for i, tid in enumerate(task_ids)
+            if completed.get(tid, L2StoreResult(False, 0)).is_successful()
+        )
+
+        if timed_out:
+            log(
+                f"  [Store] Round {r + 1}: TIMEOUT "
+                f"({len(completed)}/{len(task_ids)} tasks completed, "
+                f"success_keys={success_keys}/{in_flight * num_keys})"
+            )
+            result.round_durations.append(float("inf"))
+            result.success_counts.append(success_keys)
+            continue
+
+        result.round_durations.append(elapsed)
+        result.success_counts.append(success_keys)
+        log(
+            f"  [Store] Round {r + 1}: {elapsed * 1000:.2f} ms, "
+            f"success_keys={success_keys}/{in_flight * num_keys}"
+        )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Lookup
+# ---------------------------------------------------------------------------
+
+
+def bench_lookup(
+    adapter,
+    in_flight: int,
+    num_keys: int,
+    rounds: int,
+    keys_for_round: KeyProvider,
+    log: LogFn,
+    expected_max_hit_rate: float = 0.0,
+    expected_hit_count: int = 0,
+) -> BenchResult:
+    """Benchmark ``submit_lookup_and_lock_task``."""
+    result = BenchResult(
+        operation="Lookup",
+        in_flight=in_flight,
+        num_keys=num_keys,
+        data_size_bytes=0,  # lookup transfers no payload
+        expected_max_hit_rate=expected_max_hit_rate,
+        expected_hit_count=expected_hit_count,
+    )
+
+    log(
+        "bench_lookup uses a placeholder MemoryLayoutDesc; this may need a "
+        "real layout for layout-sensitive adapters"
+    )
+
+    for r in range(rounds):
+        keys_batches = keys_for_round(r)
+        assert len(keys_batches) == in_flight
+
+        t0 = time.perf_counter()
+        task_ids: list[int] = []
+        for i in range(in_flight):
+            task_ids.append(
+                adapter.submit_lookup_and_lock_task(
+                    keys_batches[i], _PLACEHOLDER_LAYOUT_DESC
+                )
+            )
+
+        results = _wait_lookup_finished(adapter, task_ids, 60.0)
+        t1 = time.perf_counter()
+        elapsed = t1 - t0
+        timed_out = len(results) < len(task_ids)
+
+        total_found = sum(_bitmap_count(results.get(tid)) for tid in task_ids)
+
+        if timed_out:
+            log(
+                f"  [Lookup] Round {r + 1}: TIMEOUT "
+                f"({len(results)}/{len(task_ids)} tasks completed, "
+                f"found={total_found}/{in_flight * num_keys})"
+            )
+            result.round_durations.append(float("inf"))
+            result.success_counts.append(total_found)
+            continue
+
+        result.round_durations.append(elapsed)
+        result.success_counts.append(total_found)
+        log(
+            f"  [Lookup] Round {r + 1}: {elapsed * 1000:.2f} ms, "
+            f"found={total_found}/{in_flight * num_keys}"
+        )
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Load
+# ---------------------------------------------------------------------------
+
+
+def bench_load(
+    adapter,
+    in_flight: int,
+    num_keys: int,
+    data_size: int,
+    rounds: int,
+    keys_for_round: KeyProvider,
+    objs_for_round: ObjProvider,
+    log: LogFn,
+) -> BenchResult:
+    """Benchmark ``submit_load_task``."""
+    result = BenchResult(
+        operation="Load",
+        in_flight=in_flight,
+        num_keys=num_keys,
+        data_size_bytes=data_size,
+    )
+
+    for r in range(rounds):
+        keys_batches = keys_for_round(r)
+        obj_batches = objs_for_round(r)
+        assert len(keys_batches) == in_flight
+        assert len(obj_batches) == in_flight
+
+        # Reset all load buffers before each round to ensure fresh reads.
+        for objs in obj_batches:
+            for obj in objs:
+                obj.raw_data.zero_()
+
+        t0 = time.perf_counter()
+        task_ids: list[int] = []
+        for i in range(in_flight):
+            task_ids.append(adapter.submit_load_task(keys_batches[i], obj_batches[i]))
+
+        results = _wait_load_finished(adapter, task_ids, 120.0)
+        t1 = time.perf_counter()
+        elapsed = t1 - t0
+        timed_out = len(results) < len(task_ids)
+
+        total_loaded = sum(_bitmap_count(results.get(tid)) for tid in task_ids)
+
+        if timed_out:
+            log(
+                f"  [Load] Round {r + 1}: TIMEOUT "
+                f"({len(results)}/{len(task_ids)} tasks completed, "
+                f"loaded={total_loaded}/{in_flight * num_keys})"
+            )
+            result.round_durations.append(float("inf"))
+            result.success_counts.append(total_loaded)
+            continue
+
+        result.round_durations.append(elapsed)
+        result.success_counts.append(total_loaded)
+        log(
+            f"  [Load] Round {r + 1}: {elapsed * 1000:.2f} ms, "
+            f"loaded={total_loaded}/{in_flight * num_keys}"
+        )
+
+    return result
diff --git a/lmcache/cli/commands/bench/server_bench/__init__.py b/lmcache/cli/commands/bench/server_bench/__init__.py
new file mode 100644
index 0000000..5877009
--- /dev/null
+++ b/lmcache/cli/commands/bench/server_bench/__init__.py
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench server`` subpackage.
+
+Exposes :class:`ServerBenchCommand` for auto-discovery by
+:class:`~lmcache.cli.commands.base.CompositeCommand`.
+"""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class ServerBenchCommand(BaseCommand):
+    """End-to-end test for LMCache MP cache server."""
+
+    def name(self) -> str:
+        return "server"
+
+    def help(self) -> str:
+        return "End-to-end test for LMCache MP cache server (GPU mode)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # First Party
+        from lmcache.cli.commands.bench.server_bench.command import (
+            add_server_arguments,
+        )
+
+        add_server_arguments(parser)
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.cli.commands.bench.server_bench.command import (
+            run_server_bench,
+        )
+
+        run_server_bench(self, args)
diff --git a/lmcache/cli/commands/bench/server_bench/command.py b/lmcache/cli/commands/bench/server_bench/command.py
new file mode 100644
index 0000000..6ca959e
--- /dev/null
+++ b/lmcache/cli/commands/bench/server_bench/command.py
@@ -0,0 +1,700 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache bench server`` subcommand implementation.
+
+This module provides argument registration via :func:`add_server_arguments`
+and the execution orchestrator :func:`run_server_bench` for the end-to-end
+LMCache MP cache-server sanity test.
+
+The command exercises the full store / retrieve data path:
+
+    For each request:
+      1. LOOKUP   — submit prefix lookup (void reply)
+      2. QUERY_PREFETCH_STATUS — poll by request_id until done
+      3. RETRIEVE — for the hit portion (if any)
+      4. STORE    — for the miss portion
+      5. CHECKSUM — verify KV cache integrity via HTTP API
+
+Usage examples::
+
+    # GPU mode: real CUDA tensors + IPC
+    lmcache bench server --rpc-url tcp://localhost:5555 \\
+        --num-tokens 512 --start 0 --end 3
+
+    # Custom KV cache shape (multi-group spec)
+    lmcache bench server --rpc-url tcp://localhost:5555 \\
+        --kvcache-shape-spec '(2,32,1024,8,128):float16:32'
+
+    # Run forever starting from sequence 0
+    lmcache bench server --rpc-url tcp://localhost:5555
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import argparse
+import itertools
+import math
+import mmap
+import os
+import sys
+import time
+
+# First Party
+from lmcache import torch_dev
+
+# Heavy imports reused by the orchestrator. ``DTYPE_MAP`` is required
+# for the ``--kvcache-shape-spec`` help string at parser-registration
+# time. On a slim install these symbols are placeholders; the
+# ``_require_full_install`` guard inside the helpers module keeps
+# orchestration safe.
+from lmcache.cli.commands.bench.server_bench.helpers import (
+    _DEFAULT_SHAPE_SPEC,
+    DTYPE_MAP,
+    _allocate_cpu_shm_kv_cache,
+    _allocate_gpu_kv_cache,
+    _get_chunk_size,
+    _process_request,
+    _require_full_install,
+    _send_register_kv_cache,
+    _send_unregister_kv_cache,
+    shm_open_pool_as_mmap,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.cli.commands.base import BaseCommand
+    from lmcache.v1.multiprocess.custom_types import KVCache
+
+
+# Stash the original (full-install) ImportError so the parser-stub
+# branch and the orchestrator branch can both surface it verbatim.
+__all__ = (
+    "add_server_arguments",
+    "run_server_bench",
+)
+
+
+# ---------------------------------------------------------------------------
+# Parser registration
+# ---------------------------------------------------------------------------
+
+
+def add_server_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add ``lmcache bench server`` arguments to *parser*.
+
+    Requires the full LMCache install (torch, zmq, etc.).
+    Callers should check ``_IMPORT_ERROR`` before calling this.
+
+    Args:
+        parser: The ``ArgumentParser`` for the server bench subcommand.
+    """
+
+    parser.add_argument(
+        "--rpc-url",
+        default="tcp://localhost:5555",
+        help=("ZMQ endpoint of the MP server (default: tcp://localhost:5555)"),
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["cpu", "gpu"],
+        default="gpu",
+        help=(
+            "Run mode (default: gpu). In cpu mode the client allocates "
+            "POSIX-SHM-backed KV cache tensors and the server maps the "
+            "same physical pages."
+        ),
+    )
+    parser.add_argument(
+        "--transfer-mode",
+        choices=["auto", "engine_driven", "lmcache_driven"],
+        default="auto",
+        help=(
+            "Transport routing for STORE/RETRIEVE (default: auto). "
+            "`lmcache_driven` forces the server-driven handle path "
+            "(REGISTER_KV_CACHE + STORE/RETRIEVE), which supports "
+            "both CUDA IPC and CPU SHM for zero-copy transfers. "
+            "`engine_driven` forces the worker-side gather/scatter "
+            "data path (REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT + "
+            "PREPARE/COMMIT). "
+            "`auto` keeps the historical mapping: "
+            "gpu->lmcache_driven, cpu->engine_driven."
+        ),
+    )
+    parser.add_argument(
+        "--num-tokens",
+        type=int,
+        default=512,
+        help="Tokens per request (default: 512)",
+    )
+
+    # -- KV cache shape --
+    kv = parser.add_argument_group("KV cache shape")
+    kv.add_argument(
+        "--kvcache-shape-spec",
+        type=str,
+        default=_DEFAULT_SHAPE_SPEC,
+        help=(
+            "KV shape spec. Describes one or more KV layer groups "
+            "separated by ';'. "
+            "Grammar: "
+            "'(kv_size,NB,BS,NH,HS):dtype:layers[;(...):dtype:layers...]'. "
+            "Fields: kv_size=2 for classical K/V or 1 for MLA, "
+            "NB=num_blocks, BS=block_size (tokens/block), "
+            "NH=num_heads, HS=head_size (elements). "
+            "dtype is the element dtype (supported: %s); 'uint8' "
+            "is used for FP8-quantized KV. 'layers' is the number "
+            "of consecutive layers sharing this group's geometry. "
+            "Multi-group example (MLA + classical attention): "
+            "'(1,1024,16,1,128):float16:4;"
+            "(2,1024,16,8,128):float16:28'. "
+            "All groups must share the same NB and BS. "
+            "See lmcache.v1.kv_layer_groups.parse_kvcache_shape_spec "
+            "for the authoritative parser. Default: '%s'"
+            % (", ".join(DTYPE_MAP.keys()), _DEFAULT_SHAPE_SPEC)
+        ),
+    )
+    kv.add_argument(
+        "--num-blocks",
+        type=int,
+        default=1024,
+        help="Paged blocks (default: 1024)",
+    )
+    kv.add_argument(
+        "--block-size",
+        type=int,
+        default=16,
+        help="Tokens per block (default: 16)",
+    )
+
+    parser.add_argument(
+        "--start",
+        type=int,
+        default=0,
+        help="Starting sequence number (default: 0)",
+    )
+    parser.add_argument(
+        "--end",
+        type=int,
+        default=None,
+        help=("Ending sequence number (exclusive). If not set, runs forever."),
+    )
+    parser.add_argument(
+        "--interval",
+        type=float,
+        default=0.5,
+        help=("Seconds between requests (default: 0.5)"),
+    )
+    parser.add_argument(
+        "--url",
+        default="http://localhost:8080",
+        help=("HTTP base URL for checksum API (default: http://localhost:8080)"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def run_server_bench(
+    command: "BaseCommand",
+    args: argparse.Namespace,
+) -> None:
+    """Centralized orchestrator: run the server bench loop.
+
+    Args:
+        command: The owning :class:`BaseCommand` instance, used to
+            obtain a configured :class:`Metrics` object via
+            ``command.create_metrics``.
+        args: Parsed CLI arguments for ``lmcache bench server``.
+    """
+    _require_full_install()
+
+    # Heavy imports — safe now that _require_full_install passed.
+    # Third Party
+    import zmq
+
+    # First Party
+    from lmcache.v1.kv_layer_groups import (
+        format_kvcache_shape_spec,
+        parse_kvcache_shape_spec,
+    )
+    from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+    from lmcache.v1.multiprocess.mq import MessageQueueClient
+
+    quiet = getattr(args, "quiet", False)
+
+    def log(msg: str) -> None:
+        """Print progress messages; suppressed by --quiet."""
+        if not quiet:
+            print(msg)
+
+    use_gpu = args.mode == "gpu"
+    if use_gpu and not torch_dev.is_available():
+        print("ERROR: --mode gpu requires CUDA")
+        sys.exit(1)
+
+    # Resolve transfer mode. ``auto`` reproduces the historical
+    # behaviour: gpu -> lmcache_driven path, cpu -> engine_driven path.
+    # ``lmcache_driven`` / ``engine_driven`` are explicit overrides.
+    transfer_mode = getattr(args, "transfer_mode", "auto")
+    if transfer_mode == "auto":
+        use_handle = use_gpu
+    elif transfer_mode == "lmcache_driven":
+        use_handle = True
+    else:
+        use_handle = False
+    if use_handle and not use_gpu:
+        log(
+            "  [info] --transfer-mode=lmcache_driven on cpu mode: "
+            "using REGISTER_KV_CACHE + STORE/RETRIEVE over POSIX SHM"
+        )
+
+    total_requests = 0
+    total_checksum_ok = 0
+    total_checksum_fail = 0
+
+    # Latency collectors: keyed by (pass_label, op_type).
+    # Each entry is a list of latency values in ms.
+    cold_lookup_ms: list[float] = []
+    cold_store_ms: list[float] = []
+    warm_lookup_ms: list[float] = []
+    warm_retrieve_ms: list[float] = []
+
+    url = args.rpc_url
+    log(
+        "Connecting to LMCache MP Server at %s (mode=%s) ..." % (url, args.mode),
+    )
+
+    ctx = zmq.Context()
+    client = MessageQueueClient(url, ctx)
+
+    # Tracks whether REGISTER_KV_CACHE succeeded so the ``finally`` block
+    # only deregisters a context that was actually registered.
+    registered = False
+
+    try:
+        # Query chunk size from server
+        chunk_size = _get_chunk_size(client)
+        log("Server chunk_size = %d" % chunk_size)
+
+        # Parse KV shape spec
+        layer_groups = parse_kvcache_shape_spec(args.kvcache_shape_spec)
+        # One block-id list is sent per LMCache KV group; each shape-spec
+        # group becomes its own group server-side.
+        num_engine_group_infos = len(layer_groups) or 1
+        # Echo the resolved spec so operators can verify that their
+        # input was interpreted as intended. The echoed string is a
+        # valid ``--kvcache-shape-spec`` itself.
+        log(
+            "Resolved KV shape spec: %s" % format_kvcache_shape_spec(layer_groups),
+        )
+        # Paged KV demands identical ``NB`` / ``BS`` across all groups
+        # (block_id -> slot maths is shared), but ``kv_size`` / ``NH`` /
+        # ``HS`` / ``dtype`` may vary per group. ``_allocate_gpu_kv_cache(
+        # groups=...)`` honours each group's own shape; ``_process_request``
+        # only needs a single ``block_size`` / ``total_blocks``.
+        first = layer_groups[0]
+        nb_vals = {g.shape_desc.nb for g in layer_groups}
+        bs_vals = {g.shape_desc.bs for g in layer_groups}
+        if len(nb_vals) > 1 or len(bs_vals) > 1:
+            raise ValueError(
+                "All groups must share NB and BS (paged KV "
+                "requires uniform block geometry). Got NB=%s BS=%s"
+                % (sorted(nb_vals), sorted(bs_vals))
+            )
+        num_layers = sum(g.num_layers for g in layer_groups)
+        spec_nb = getattr(first.shape_desc, "nb", 0) or 0
+        spec_bs = getattr(first.shape_desc, "bs", 0) or 0
+        num_blocks = spec_nb if spec_nb > 0 else args.num_blocks
+        block_size = spec_bs if spec_bs > 0 else args.block_size
+        if spec_nb and spec_nb != args.num_blocks:
+            log(
+                "  [info] spec nb=%d overrides --num-blocks=%d"
+                % (spec_nb, args.num_blocks)
+            )
+        if spec_bs and spec_bs != args.block_size:
+            log(
+                "  [info] spec bs=%d overrides --block-size=%d"
+                % (spec_bs, args.block_size)
+            )
+        # For display / legacy hint fields only: collapse to the first
+        # group when homogeneous, otherwise report "mixed".
+        heads_set = {g.shape_desc.nh for g in layer_groups}
+        hs_set = {g.shape_desc.hs for g in layer_groups}
+        kv_size_set = {g.shape_desc.kv_size for g in layer_groups}
+        dtype_set = {g.dtype for g in layer_groups}
+        num_heads_disp: int | str = (
+            first.shape_desc.nh if len(heads_set) == 1 else "mixed"
+        )
+        head_size_disp: int | str = first.shape_desc.hs if len(hs_set) == 1 else "mixed"
+        kv_size_disp: int | str = (
+            first.shape_desc.kv_size if len(kv_size_set) == 1 else "mixed"
+        )
+        if len(dtype_set) == 1:
+            dtype_str = next(
+                (k for k, v in DTYPE_MAP.items() if v == first.dtype),
+                "float16",
+            )
+        else:
+            dtype_str = "mixed"
+
+        # Build layout_hints. dtype is sent as a string ("float16")
+        # because torch.dtype is not msgpack-serializable. For
+        # heterogeneous multi-group specs, per-layer fields (heads /
+        # head_size / dtype / kv_size) are reported as "mixed" —
+        # ``layout_hints`` is only consumed by the server to pick a
+        # ``kv_layout``; the real per-layer shape is discovered from
+        # the tensors themselves.
+        layout_hints = {
+            "num_layers": num_layers,
+            "num_heads": num_heads_disp,
+            "head_size": head_size_disp,
+            "num_blocks": num_blocks,
+            "block_size": block_size,
+            "dtype": dtype_str,
+        }
+        # Tell the server each group's true tokens-per-paged-chunk
+        # explicitly. Otherwise the server falls back to the block size
+        # discovered from the tensors (``shape_desc.bs``), which on the
+        # CPU/HND path can be the per-block ``num_heads`` value instead
+        # of the real ``block_size`` (HND swaps NH and BS in the tensor
+        # shape), and STORE/RETRIEVE would then expect twice as many
+        # block IDs as the bench client actually sends.
+        engine_group_infos = [
+            EngineGroupInfo(
+                engine_group_id=group_idx,
+                layer_indices=tuple(group.layer_indices),
+                tokens_per_block=block_size,
+            )
+            for group_idx, group in enumerate(layer_groups)
+        ]
+
+        num_tokens = args.num_tokens
+        log(
+            "Each request: %d tokens (%d full chunks)"
+            % (
+                num_tokens + 1,
+                (num_tokens + 1) // chunk_size,
+            )
+        )
+        log(
+            "KV shape: %d layers, %s heads x %s, "
+            "dtype=%s, blocks=%dx%d, kv=%s"
+            % (
+                num_layers,
+                num_heads_disp,
+                head_size_disp,
+                dtype_str,
+                num_blocks,
+                block_size,
+                kv_size_disp,
+            )
+        )
+
+        # Allocate KV tensors. GPU mode wraps real CUDA tensors
+        # via CUDA IPC; CPU mode allocates POSIX-SHM-backed
+        # tensors so the server can map the same physical pages.
+        # shm_names tracks per-layer SHM segment names allocated
+        # on demand (one per layer) so we can shm_unlink on exit.
+        shm_names: list[str] = []
+        if use_gpu:
+            # First Party
+            from lmcache.v1.platform.cuda.ipc_wrapper import CudaIPCWrapper
+
+            allocated = _allocate_gpu_kv_cache(groups=layer_groups)
+            log(
+                "Allocated %d GPU tensors on %s" % (len(allocated), allocated[0].device)
+            )
+            kv_wrappers: KVCache = [CudaIPCWrapper(t) for t in allocated]
+            # Keep the CUDA tensors alive for the lifetime of the
+            # bench process -- storage may be reclaimed otherwise --
+            # and reuse the same list as the client-side data-mode
+            # source/sink for the round-trip self-check.
+            client_kv_tensors = allocated
+        else:
+            # First Party
+            from lmcache.v1.platform.cpu.shm import CpuShmTensorWrapper
+
+            shm_prefix = CpuShmTensorWrapper.SHM_NAME_PREFIX + str(os.getpid())
+            cpu_tensors, cpu_wrappers, shm_names = _allocate_cpu_shm_kv_cache(
+                groups=layer_groups, shm_prefix=shm_prefix
+            )
+            log(
+                "Allocated %d CPU SHM tensors (prefix=%s)"
+                % (len(cpu_tensors), shm_prefix)
+            )
+            kv_wrappers = list(cpu_wrappers)
+            client_kv_tensors = cpu_tensors
+
+        # Register KV cache before any store/retrieve. In handle mode
+        # both GPU (CUDA-IPC) and CPU (POSIX-SHM) paths share the same
+        # ``REGISTER_KV_CACHE`` protocol since ``CpuShmTensorWrapper``
+        # is a ``DeviceIPCWrapper`` subclass on the wire. In data mode
+        # we fall through to the non-GPU registration protocol.
+        register_result = _send_register_kv_cache(
+            client,
+            layout_hints=layout_hints,
+            kv_caches=kv_wrappers if use_handle else None,
+            use_gpu=use_gpu,
+            use_handle=use_handle,
+            engine_group_infos=engine_group_infos,
+        )
+        log("REGISTER_KV_CACHE: %s" % ("OK" if register_result else "FAIL"))
+        log("")
+        # Mark the registration so the ``finally`` block knows to send the
+        # matching UNREGISTER. The data-mode register returns a response
+        # object (truthy) and the handle-mode register returns a bool;
+        # either way a truthy result means the server holds our context.
+        registered = bool(register_result)
+
+        # In data mode the server reply carries the SHM pool name
+        # and size; the bench mmaps the same pool so STORE/RETRIEVE
+        # can exchange tensor data via slot descriptors instead of
+        # round-tripping pickle through the RPC layer.
+        server_pool: "mmap.mmap | None" = None
+        if not use_handle and not isinstance(register_result, bool):
+            shm_name = getattr(register_result, "shm_name", "")
+            pool_size = getattr(register_result, "pool_size", 0)
+            if shm_name and pool_size > 0:
+                server_pool = shm_open_pool_as_mmap(shm_name, pool_size)
+
+        if args.end is not None:
+            seq_iter: itertools.count | range = range(args.start, args.end)
+        else:
+            seq_iter = itertools.count(args.start)
+
+        http_base = args.url.rstrip("/")
+
+        # In data mode the server has no paged ``kv_tensors`` view to
+        # hash, so we self-check on the client: cold pass captures
+        # ground truth, warm pass zero-fills + re-hashes after
+        # RETRIEVE. Handle mode keeps the legacy server-side
+        # ``/cache/checksums`` path.
+        client_tensors = None if use_handle else client_kv_tensors
+
+        for seq_no in seq_iter:
+            log("=== Request seq=%d ===" % seq_no)
+
+            # Pass 1: cold (miss -> store)
+            cold_result = _process_request(
+                client,
+                seq_no,
+                num_tokens,
+                chunk_size,
+                "cold",
+                http_base=http_base,
+                block_size=block_size,
+                total_blocks=num_blocks,
+                num_engine_group_infos=num_engine_group_infos,
+                use_gpu=use_gpu,
+                use_handle=use_handle,
+                client_tensors=client_tensors,
+                server_pool=server_pool,
+            )
+            if cold_result is not None:
+                if cold_result.lookup_ms is not None:
+                    cold_lookup_ms.append(cold_result.lookup_ms)
+                if cold_result.store_ms is not None:
+                    cold_store_ms.append(cold_result.store_ms)
+
+            time.sleep(args.interval)
+
+            # Pass 2: warm (hit -> retrieve)
+            warm_result = _process_request(
+                client,
+                seq_no,
+                num_tokens,
+                chunk_size,
+                "warm",
+                http_base=http_base,
+                block_size=block_size,
+                total_blocks=num_blocks,
+                num_engine_group_infos=num_engine_group_infos,
+                use_gpu=use_gpu,
+                use_handle=use_handle,
+                client_tensors=client_tensors,
+                server_pool=server_pool,
+            )
+            if warm_result is not None:
+                if warm_result.lookup_ms is not None:
+                    warm_lookup_ms.append(warm_result.lookup_ms)
+                if warm_result.retrieve_ms is not None:
+                    warm_retrieve_ms.append(warm_result.retrieve_ms)
+
+            # Compare checksums
+            total_requests += 1
+            cold_checksums = cold_result.checksums if cold_result else None
+            warm_checksums = warm_result.checksums if warm_result else None
+            if cold_checksums and warm_checksums:
+                if cold_checksums == warm_checksums:
+                    total_checksum_ok += 1
+                    log("  [seq %d] CHECKSUM MATCH OK" % seq_no)
+                else:
+                    total_checksum_fail += 1
+                    log("  [seq %d] CHECKSUM MISMATCH!" % seq_no)
+                    for i, (c, w) in enumerate(
+                        zip(
+                            cold_checksums,
+                            warm_checksums,
+                            strict=False,
+                        )
+                    ):
+                        log(
+                            "    chunk %d: cold=%s warm=%s %s"
+                            % (
+                                i,
+                                c[:12],
+                                w[:12],
+                                ("OK" if c == w else "FAIL"),
+                            )
+                        )
+
+            log("")
+            time.sleep(args.interval)
+    except KeyboardInterrupt:
+        log("\nStopping...")
+    finally:
+        # Deregister our context from the server before tearing down the
+        # client. Otherwise the server keeps the registration (and the
+        # CUDA-IPC / POSIX-SHM mappings it holds) alive forever, leaking
+        # one context entry per bench run. Must run while the client is
+        # still connected, hence before ``client.close()``.
+        if registered:
+            try:
+                ok = _send_unregister_kv_cache(
+                    client,
+                    instance_id=0,
+                    use_handle=use_handle,
+                )
+                log("UNREGISTER_KV_CACHE: %s" % ("OK" if ok else "FAIL"))
+            except zmq.ZMQError as exc:
+                log("  [warning] UNREGISTER_KV_CACHE failed: %s" % exc)
+        # Release the bench-side mmap of the server SHM pool first
+        # (data mode only; ``server_pool`` stays ``None`` otherwise).
+        if "server_pool" in locals() and server_pool is not None:
+            try:
+                server_pool.close()
+            except (BufferError, ValueError):
+                pass
+        client.close()
+        ctx.term()
+        # Best-effort SHM cleanup so segments don't linger.
+        for _name in shm_names if "shm_names" in locals() else []:
+            try:
+                # First Party
+                from lmcache.v1.platform.cpu.shm import shm_unlink
+
+                shm_unlink(_name)
+            except OSError:
+                pass
+
+    # Emit structured metrics summary.
+    _emit_server_bench_metrics(
+        command=command,
+        args=args,
+        total_requests=total_requests,
+        total_checksum_ok=total_checksum_ok,
+        total_checksum_fail=total_checksum_fail,
+        cold_lookup_ms=cold_lookup_ms,
+        cold_store_ms=cold_store_ms,
+        warm_lookup_ms=warm_lookup_ms,
+        warm_retrieve_ms=warm_retrieve_ms,
+    )
+    log("Done.")
+
+
+def _emit_server_bench_metrics(
+    command: "BaseCommand",
+    args: argparse.Namespace,
+    total_requests: int,
+    total_checksum_ok: int,
+    total_checksum_fail: int,
+    cold_lookup_ms: list[float] | None = None,
+    cold_store_ms: list[float] | None = None,
+    warm_lookup_ms: list[float] | None = None,
+    warm_retrieve_ms: list[float] | None = None,
+) -> None:
+    """Emit server bench summary using the CLI metrics system.
+
+    Args:
+        command: The owning :class:`BaseCommand` instance.
+        args: Parsed CLI arguments.
+        total_requests: Total number of request pairs processed.
+        total_checksum_ok: Number of requests with matching checksums.
+        total_checksum_fail: Number of requests with mismatched checksums.
+        cold_lookup_ms: Per-request cold lookup latencies (ms).
+        cold_store_ms: Per-request cold store latencies (ms).
+        warm_lookup_ms: Per-request warm lookup latencies (ms).
+        warm_retrieve_ms: Per-request warm retrieve latencies (ms).
+    """
+    if total_requests == 0:
+        return
+
+    metrics = command.create_metrics("Server Bench Result", args, width=64)
+
+    cfg_section = metrics.add_section("config", "Configuration")
+    cfg_section.add("rpc_url", "RPC URL", args.rpc_url)
+    cfg_section.add("mode", "Mode", args.mode)
+    cfg_section.add(
+        "transfer_mode", "Transfer mode", getattr(args, "transfer_mode", "auto")
+    )
+    cfg_section.add("num_tokens", "Tokens / request", args.num_tokens)
+    cfg_section.add("interval", "Interval (s)", args.interval)
+
+    result_section = metrics.add_section("results", "Results")
+    result_section.add("total_requests", "Total requests", total_requests)
+    result_section.add("checksum_ok", "Checksum OK", total_checksum_ok)
+    result_section.add("checksum_fail", "Checksum FAIL", total_checksum_fail)
+    if total_requests > 0:
+        pass_rate = total_checksum_ok / total_requests * 100
+        result_section.add("pass_rate", "Pass rate (%)", round(pass_rate, 2))
+
+    # Per-operation latency summary (cold pass).
+    _add_latency_section(metrics, "cold_lookup", "Cold Lookup (ms)", cold_lookup_ms)
+    _add_latency_section(metrics, "cold_store", "Cold Store (ms)", cold_store_ms)
+
+    # Per-operation latency summary (warm pass).
+    _add_latency_section(metrics, "warm_lookup", "Warm Lookup (ms)", warm_lookup_ms)
+    _add_latency_section(
+        metrics, "warm_retrieve", "Warm Retrieve (ms)", warm_retrieve_ms
+    )
+
+    metrics.emit()
+
+
+def _add_latency_section(
+    metrics,
+    section_id: str,
+    section_title: str,
+    latencies: list[float] | None,
+) -> None:
+    """Add a latency summary section to the metrics report.
+
+    Computes count, mean, min, max, p50, and p99 from the raw
+    latency list. Skipped if the list is empty or None.
+
+    Args:
+        metrics: The :class:`Metrics` instance.
+        section_id: Unique section identifier.
+        section_title: Human-readable section title.
+        latencies: Raw latency values in milliseconds.
+    """
+    if not latencies:
+        return
+
+    sorted_lat = sorted(latencies)
+    count = len(sorted_lat)
+    mean = sum(sorted_lat) / count
+    p50_idx = max(0, math.ceil(count * 0.50) - 1)
+    p99_idx = max(0, math.ceil(count * 0.99) - 1)
+
+    section = metrics.add_section(section_id, section_title)
+    section.add(f"{section_id}_count", "count", count)
+    section.add(f"{section_id}_mean", "mean", round(mean, 3))
+    section.add(f"{section_id}_min", "min", round(sorted_lat[0], 3))
+    section.add(f"{section_id}_max", "max", round(sorted_lat[-1], 3))
+    section.add(f"{section_id}_p50", "p50", round(sorted_lat[p50_idx], 3))
+    section.add(f"{section_id}_p99", "p99", round(sorted_lat[p99_idx], 3))
diff --git a/lmcache/cli/commands/bench/server_bench/helpers.py b/lmcache/cli/commands/bench/server_bench/helpers.py
new file mode 100644
index 0000000..77a5d41
--- /dev/null
+++ b/lmcache/cli/commands/bench/server_bench/helpers.py
@@ -0,0 +1,1158 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Internal helpers for ``lmcache bench server``.
+
+This module owns the heavy runtime imports (``torch`` / ``zmq`` /
+``lmcache.v1.*``) and all pure / low-level helper functions used by
+the ``server`` bench target. The CLI registration and execute
+orchestration live in :mod:`lmcache.cli.commands.bench.server_bench.command`.
+
+Splitting the module this way keeps the public command surface in line
+with the ``engine_bench`` and ``l2_adapter_bench`` siblings, while
+still quarantining the heavy imports behind a single guarded block so
+the slim ``lmcache-cli`` install can load the bench parser without
+torch / zmq.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import Any
+import ctypes
+import hashlib
+import json
+import mmap
+import sys
+import time
+import urllib.error
+import urllib.request
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+
+# ``lmcache bench server`` allocates real CUDA tensors and talks to
+# the MP server via ZMQ, both of which are absent from the thin
+# ``lmcache-cli`` distribution (no torch, no zmq, no lmcache.v1.*).
+# Importing them unconditionally would kill the *entire* ``lmcache``
+# CLI at registry load time with an opaque ImportError. Wrap the
+# heavy imports and remember the error so ``add_arguments`` /
+# ``execute`` can bail out with an actionable install hint.
+_IMPORT_ERROR: ImportError | None = None
+try:
+    # Third Party
+    import torch
+    import zmq  # noqa: F401  # availability probe; used by command.py
+
+    # First Party
+    from lmcache.utils import (
+        EngineType,
+        check_interprocess_event_support,
+    )
+    from lmcache.v1.kv_layer_groups import (
+        DTYPE_MAP,
+        KVLayerGroupInfo,
+    )
+    from lmcache.v1.multiprocess.custom_types import (
+        IPCCacheServerKey,
+        KVCache,
+        RegisterEngineDrivenContextPayload,
+    )
+    from lmcache.v1.multiprocess.futures import MessagingFuture
+    from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+    from lmcache.v1.multiprocess.mq import MessageQueueClient
+    from lmcache.v1.multiprocess.posix_shm import shm_open_pool_as_mmap
+    from lmcache.v1.multiprocess.protocols.base import RequestType
+    from lmcache.v1.multiprocess.protocols.engine import (
+        RegisterEngineDrivenContextResponse,
+    )
+    from lmcache.v1.multiprocess.transfer_context.shm import ShmSlotDescriptor
+    from lmcache.v1.platform.cpu.shm import (
+        CpuShmTensorWrapper,
+        shm_create_readwrite,
+    )
+except ImportError as _exc:
+    _IMPORT_ERROR = _exc
+    # Fallback placeholder so ``add_arguments`` can still build its
+    # help text without crashing on a CLI-only install.
+    DTYPE_MAP = {}  # type: ignore[assignment]
+
+    # Stubs so other modules (notably ``command.py``) can still import
+    # the SHM helpers on a slim install; ``_require_full_install`` is
+    # the gate that prevents them from ever being invoked there.
+    def shm_open_pool_as_mmap(name: str, nbytes: int) -> Any:  # type: ignore[misc]
+        raise RuntimeError(
+            "shm_open_pool_as_mmap unavailable on slim lmcache-cli install"
+        )
+
+
+def _require_full_install() -> None:
+    """Exit with an install hint if the full LMCache runtime is missing.
+
+    ``lmcache bench server`` needs torch, zmq and ``lmcache.v1.*``
+    (MP client, KV layer-group parser). When those imports failed at
+    module load — almost always because the user installed
+    ``lmcache-cli`` instead of the full package — print the shortest
+    actionable message to stderr and exit with status ``2`` so
+    scripts can detect the install gap programmatically.
+    """
+    if _IMPORT_ERROR is None:
+        return
+    print(
+        "ERROR: `lmcache bench server` needs the full LMCache package "
+        "(torch, zmq, MP runtime), but only the `lmcache-cli` shell "
+        "appears to be installed.\n"
+        "  Install the full package with `pip install lmcache` and try "
+        "again.\n"
+        f"  Original import error: {_IMPORT_ERROR}",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+
+# ------------------------------------------------------------------ #
+#  Constants                                                           #
+# ------------------------------------------------------------------ #
+
+_HELLO_TOKEN_ID = 9906
+_MODEL_NAME = "test-model"
+_WORLD_SIZE = 1
+_INSTANCE_ID = 0
+
+# Default KV shape spec matching the original defaults:
+# 32 layers, (2, num_blocks=1024, block_size=16, 8 heads, 128 head_size)
+_DEFAULT_SHAPE_SPEC = "(2,1024,16,8,128):float16:32"
+
+# ------------------------------------------------------------------ #
+#  Low-level helpers                                                   #
+# ------------------------------------------------------------------ #
+
+# Default RPC call timeout (seconds) for blocking request/reply
+# round-trips.
+_DEFAULT_RPC_TIMEOUT_S = 10.0
+
+# Unique sentinel returned by :func:`_call` on RPC timeout so callers
+# can disambiguate it from a legitimate ``None`` (void) reply.
+_TIMEOUT = object()
+
+
+def _call(
+    client: MessageQueueClient,
+    request_type: RequestType,
+    payloads: list,
+    timeout_s: float = _DEFAULT_RPC_TIMEOUT_S,
+) -> Any:
+    """Submit a request through ``MessageQueueClient`` and block.
+
+    Returns the decoded response (possibly ``None`` for void replies)
+    on success, or the sentinel ``_TIMEOUT`` on RPC timeout.
+    """
+    future: MessagingFuture[Any] = client.submit_request(request_type, payloads)
+    try:
+        return future.result(timeout=timeout_s)
+    except TimeoutError:
+        return _TIMEOUT
+
+
+# ------------------------------------------------------------------ #
+#  Token / key helpers                                                 #
+# ------------------------------------------------------------------ #
+
+
+def _build_token_ids(
+    seq_no: int,
+    num_tokens: int,
+) -> tuple[int, ...]:
+    """Build token sequence: ``(seq_no, hello, hello, ...)``."""
+    return (seq_no,) + (_HELLO_TOKEN_ID,) * num_tokens
+
+
+def _make_key(
+    token_ids: tuple[int, ...],
+    request_id: str,
+    start: int = 0,
+    end: int = 0,
+    worker_id: int | None = None,
+) -> IPCCacheServerKey:
+    """Build an IPCCacheServerKey."""
+    return IPCCacheServerKey(
+        model_name=_MODEL_NAME,
+        world_size=_WORLD_SIZE,
+        worker_id=worker_id,
+        token_ids=token_ids,
+        start=start,
+        end=end if end > 0 else len(token_ids),
+        request_id=request_id,
+    )
+
+
+# ------------------------------------------------------------------ #
+#  Protocol operations                                                 #
+# ------------------------------------------------------------------ #
+
+
+# ------------------------------------------------------------------ #
+#  GPU KV cache allocation                                             #
+# ------------------------------------------------------------------ #
+
+
+def _allocate_gpu_kv_cache(
+    num_layers: int = 32,
+    num_heads: int = 8,
+    head_size: int = 128,
+    num_blocks: int = 1024,
+    block_size: int = 16,
+    dtype: torch.dtype | None = None,
+    device: str | torch.device | None = None,
+    kv_size: int = 2,
+    groups: list[KVLayerGroupInfo] | None = None,
+) -> list[torch.Tensor]:
+    """Allocate paged GPU KV cache tensors.
+
+    Each layer is a tensor of shape
+    ``(kv_size, num_blocks, block_size, num_heads, head_size)``
+    matching the vLLM NHD layout. ``kv_size`` is 2 for standard
+    K/V attention; override via the ``--kvcache-shape-spec``
+    first dimension for architectures that need a different
+    leading dimension (e.g. MLA).
+
+    When ``groups`` is provided, tensors are allocated per-group
+    using each group's own ``(kv_size, NB, BS, NH, HS)`` / ``dtype``
+    (for heterogeneous multi-group specs). In that mode the flat
+    ``num_heads`` / ``head_size`` / ``dtype`` / ``kv_size`` kwargs
+    are ignored, and ``num_layers`` is derived from the groups.
+    """
+    # ``torch.float16`` cannot be used as a default value because the
+    # module must load on ``lmcache-cli`` (no torch) installs.
+    if dtype is None:
+        dtype = torch.float16
+    torch.random.manual_seed(42)
+    dev = (
+        torch.device(device)
+        if device
+        else torch.device(torch_device_type, torch_dev.current_device())
+    )
+
+    def _alloc(
+        shape: tuple[int, ...],
+        a_dtype: torch.dtype,
+    ) -> torch.Tensor:
+        if a_dtype.is_floating_point:
+            return torch.randn(shape, dtype=a_dtype, device=dev)
+        # ``torch.randn`` only supports floating-point dtypes; fall
+        # back to ``randint`` for integer dtypes (e.g. ``uint8``
+        # used by FP8 quantized KV cache layouts).
+        iinfo = torch.iinfo(a_dtype)
+        return torch.randint(iinfo.min, iinfo.max + 1, shape, dtype=a_dtype, device=dev)
+
+    if groups:
+        tensors: list[torch.Tensor] = []
+        for g in groups:
+            sd = g.shape_desc
+            g_shape = (sd.kv_size, sd.nb, sd.bs, sd.nh, sd.hs)
+            tensors.extend(_alloc(g_shape, g.dtype) for _ in range(sd.nl))
+        return tensors
+
+    shape = (kv_size, num_blocks, block_size, num_heads, head_size)
+    return [_alloc(shape, dtype) for _ in range(num_layers)]
+
+
+# Backward-compatible alias used by tests and older callers.
+_allocate_kv_cache = _allocate_gpu_kv_cache
+
+
+def _allocate_cpu_shm_kv_cache(
+    groups: list[KVLayerGroupInfo],
+    shm_prefix: str,
+) -> tuple[list[torch.Tensor], list[CpuShmTensorWrapper], list[str]]:
+    """Allocate paged CPU KV cache tensors backed by POSIX SHM.
+
+    For each (group, layer) we ``shm_open`` a fresh segment and
+    ``mmap`` it into the client process. The returned tensors share
+    storage with the SHM mapping, and the matching
+    :class:`CpuShmTensorWrapper` instances tell the LMCache mp
+    server how to map the very same physical pages -- i.e. true
+    zero-copy across processes (matching the GPU CUDA-IPC path).
+
+    Returns:
+        ``(tensors, wrappers, shm_names)``. ``shm_names`` is kept
+        so the caller can ``shm_unlink`` on shutdown.
+    """
+    # Fixed seed so the deterministic random fill below produces
+    # reproducible checksums across cold/warm bench iterations.
+    torch.random.manual_seed(42)
+    tensors: list[torch.Tensor] = []
+    wrappers: list[CpuShmTensorWrapper] = []
+    shm_names: list[str] = []
+    layer_idx = 0
+    for g_idx, g in enumerate(groups):
+        sd = g.shape_desc
+        g_shape = (sd.kv_size, sd.nb, sd.bs, sd.nh, sd.hs)
+        for _ in range(sd.nl):
+            n_elems = 1
+            for d in g_shape:
+                n_elems *= d
+            nbytes = n_elems * g.dtype.itemsize
+            name = "%s_%d_%d" % (shm_prefix, g_idx, layer_idx)
+            addr = shm_create_readwrite(name, nbytes)
+            buf_type = ctypes.c_uint8 * nbytes
+            buf = buf_type.from_address(addr)
+            flat = torch.frombuffer(buf, dtype=torch.uint8)
+            t = flat.view(g.dtype).reshape(g_shape)
+            # Initialise with deterministic random data so the
+            # cold/warm checksum compare in the bench loop is
+            # meaningful.
+            if g.dtype.is_floating_point:
+                t.copy_(torch.randn(g_shape, dtype=g.dtype))
+            else:
+                iinfo = torch.iinfo(g.dtype)
+                t.copy_(torch.randint(iinfo.min, iinfo.max + 1, g_shape, dtype=g.dtype))
+            tensors.append(t)
+            wrappers.append(CpuShmTensorWrapper(t, name))
+            shm_names.append(name)
+            layer_idx += 1
+    return tensors, wrappers, shm_names
+
+
+def _send_register_kv_cache(
+    client: MessageQueueClient,
+    instance_id: int = 0,
+    model_name: str = _MODEL_NAME,
+    world_size: int = _WORLD_SIZE,
+    layout_hints: dict | None = None,
+    kv_caches: KVCache | None = None,
+    use_gpu: bool = True,
+    use_handle: bool | None = None,
+    engine_group_infos: "list[EngineGroupInfo] | None" = None,
+) -> "bool | RegisterEngineDrivenContextResponse":
+    """Register a KV cache context with the MP server.
+
+    Dispatches to the correct protocol based on ``use_handle``:
+
+    * Handle mode: ``REGISTER_KV_CACHE`` with a wrapper list
+      (``CudaIPCWrapper`` for GPU, ``CpuShmTensorWrapper`` for CPU).
+    * Data mode: ``REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT`` with a
+      ``RegisterEngineDrivenContextPayload`` derived from ``layout_hints``.
+
+    ``use_handle`` defaults to ``use_gpu`` for backwards compatibility:
+    GPU always goes through the handle path, CPU defaults to data.
+
+    ``engine_group_infos`` (handle mode only) carries the per-group
+    metadata — including each group's true ``tokens_per_block`` — so the
+    server does not have to trust the block size discovered from the
+    tensors (which the HND layout can swap with ``num_heads``). ``None``
+    sends an empty list (single non-hybrid group, geometry discovered
+    from the tensors).
+    """
+    if use_handle is None:
+        use_handle = use_gpu
+    if use_handle:
+        if not kv_caches:
+            raise ValueError(
+                "kv_caches must be a non-empty list of wrappers "
+                "(CudaIPCWrapper for GPU, CpuShmTensorWrapper for CPU)"
+            )
+        hints: dict = {"kv_layout": "NHD"}
+        if layout_hints:
+            hints.update(layout_hints)
+        # TODO(maobaolong): Make the engine type configurable
+        payloads = [
+            instance_id,
+            kv_caches,
+            model_name,
+            world_size,
+            EngineType.VLLM,
+            hints,
+            list(engine_group_infos or ()),
+        ]
+        result = _call(client, RequestType.REGISTER_KV_CACHE, payloads)
+        return result is not _TIMEOUT
+
+    # CPU mode: use the non-GPU context registration protocol.
+    # layout_hints carries num_layers, num_heads, head_size, block_size,
+    # dtype.  hidden_dim_size = num_heads * head_size (NHD layout).
+    hints_d: dict = layout_hints or {}
+    num_layers = int(hints_d.get("num_layers", 32))
+    num_heads = hints_d.get("num_heads", 8)
+    head_size = hints_d.get("head_size", 128)
+    block_size = int(hints_d.get("block_size", 16))
+    dtype_str = str(hints_d.get("dtype", "float16"))
+    # "mixed" can appear for heterogeneous specs; fall back to first group.
+    if not isinstance(num_heads, int):
+        num_heads = 8
+    if not isinstance(head_size, int):
+        head_size = 128
+    hidden_dim_size = int(num_heads) * int(head_size)
+    payload = RegisterEngineDrivenContextPayload(
+        instance_id=instance_id,
+        model_name=model_name,
+        world_size=world_size,
+        block_size=block_size,
+        num_layers=num_layers,
+        hidden_dim_size=hidden_dim_size,
+        dtype_str=dtype_str,
+        use_mla=False,
+    )
+    result = _call(
+        client, RequestType.REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT, [payload]
+    )
+    if result is _TIMEOUT:
+        return False
+    # The data-mode register reply carries the server's SHM pool name
+    # and size; the bench keeps it on the side so STORE / RETRIEVE
+    # can mmap the same pool and exchange tensor data without going
+    # through pickle.
+    return result
+
+
+def _send_unregister_kv_cache(
+    client: MessageQueueClient,
+    instance_id: int = 0,
+    use_handle: bool = True,
+) -> bool:
+    """Deregister a KV cache context from the MP server.
+
+    The inverse of :func:`_send_register_kv_cache`. Without this call
+    the server keeps the bench's registration (and the CUDA-IPC / POSIX
+    SHM mappings it holds) alive forever, leaking one context entry per
+    bench run.
+
+    Dispatches to the correct protocol based on ``use_handle``, mirroring
+    the register path:
+
+    * Handle mode: ``UNREGISTER_KV_CACHE``.
+    * Data mode: ``UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT``.
+
+    Both protocols take a single ``instance_id`` payload and return a void
+    reply, so success is distinguished from an RPC timeout only.
+
+    Args:
+        client: The MP message-queue client.
+        instance_id: The instance ID used at registration time. Must match
+            the ``instance_id`` passed to :func:`_send_register_kv_cache`.
+        use_handle: ``True`` for the handle path (GPU CUDA-IPC / CPU SHM),
+            ``False`` for the engine-driven data path.
+
+    Returns:
+        ``True`` if the server acknowledged the call, ``False`` on RPC
+        timeout.
+    """
+    request_type = (
+        RequestType.UNREGISTER_KV_CACHE
+        if use_handle
+        else RequestType.UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT
+    )
+    result = _call(client, request_type, [instance_id])
+    return result is not _TIMEOUT
+
+
+def _send_lookup(
+    client: MessageQueueClient,
+    key: IPCCacheServerKey,
+) -> bool:
+    """LOOKUP — submit a prefix lookup.
+
+    The server-side handler returns ``None`` (void) on success, so
+    we only distinguish RPC timeout from a completed call.
+    """
+    result = _call(client, RequestType.LOOKUP, [key, 1])
+    return result is not _TIMEOUT
+
+
+def _poll_prefetch_status(
+    client: MessageQueueClient,
+    request_id: str,
+    max_polls: int = 50,
+    poll_interval: float = 0.05,
+) -> int | None:
+    """QUERY_PREFETCH_STATUS — poll until done.
+
+    Returns the hit chunk count, or ``None`` if the polling budget
+    is exhausted. The server keys prefetch jobs by ``request_id``
+    (str), not an integer job handle.
+    """
+    for _ in range(max_polls):
+        result = _call(
+            client,
+            RequestType.QUERY_PREFETCH_STATUS,
+            [request_id],
+        )
+        if result is _TIMEOUT:
+            # RPC timeout — treat as giving up on this poll cycle.
+            return None
+        if result is not None:
+            return result
+        time.sleep(poll_interval)
+    return None
+
+
+def _make_event_handle(use_gpu: bool = True) -> bytes:
+    """Create a CUDA event IPC handle for GPU mode.
+
+    CPU mode does not need a cross-process event (SHM mappings are
+    coherent without device-side sync), so an empty handle is
+    returned and the server treats it as a no-op.
+    """
+    if not use_gpu:
+        return b""
+    check_interprocess_event_support()
+    event = torch_dev.Event(interprocess=True)
+    event.record()
+    return event.ipc_handle()
+
+
+def _build_server_slot_views(
+    server_pool: "mmap.mmap",
+    slots: list[dict[str, Any]],
+) -> list["torch.Tensor"]:
+    """Build zero-copy tensor views over server SHM slot descriptors.
+
+    Each ``ShmSlotDescriptor`` carries the ``(offset, length, shape,
+    dtype)`` of one chunk inside the server-owned SHM pool; we wrap
+    them with ``torch.frombuffer`` so the bench can read or overwrite
+    that chunk without going through pickle.
+    """
+    views: list[torch.Tensor] = []
+    for raw in slots:
+        desc = ShmSlotDescriptor.from_dict(raw)
+        dtype = getattr(torch, desc.dtype, None)
+        if not isinstance(dtype, torch.dtype):
+            raise ValueError("invalid torch dtype string: %s" % desc.dtype)
+        itemsize = torch.empty((), dtype=dtype).element_size()
+        if itemsize <= 0:
+            raise ValueError("invalid dtype size for %s" % desc.dtype)
+        count = desc.length // itemsize
+        flat = torch.frombuffer(
+            server_pool, dtype=dtype, count=count, offset=desc.offset
+        )
+        views.append(flat.view(torch.Size(desc.shape)))
+    return views
+
+
+def _gather_paged_to_flat_chunks(
+    tensors: list["torch.Tensor"],
+    block_offset: int,
+    num_blocks: int,
+    block_size: int,
+    chunk_size: int,
+) -> list["torch.Tensor"]:
+    """Gather paged client tensors into flat per-chunk CPU tensors.
+
+    Output layout matches the server's expected ``commit_store``
+    payload (set up at register time by
+    ``register_kv_cache_engine_driven_context``):
+    each chunk is ``[2, num_layers, chunk_size, hidden_dim]``,
+    where ``hidden_dim = NH * HS``. Assumes a homogeneous group
+    (same NH/HS/dtype across all layers); heterogeneous specs
+    fall outside the bench scope.
+    """
+    if chunk_size % block_size != 0:
+        raise ValueError(
+            "chunk_size %d must be a multiple of block_size %d"
+            % (chunk_size, block_size)
+        )
+    blocks_per_chunk = chunk_size // block_size
+    num_chunks = num_blocks // blocks_per_chunk
+    num_layers = len(tensors)
+    chunks: list[torch.Tensor] = []
+    for c in range(num_chunks):
+        start_b = block_offset + c * blocks_per_chunk
+        per_layer: list[torch.Tensor] = []
+        for t in tensors:
+            # paged: (2, NB, BS, NH, HS) -> slice block range ->
+            # (2, blocks_per_chunk, BS, NH, HS) -> flatten to
+            # (2, chunk_size, NH*HS).
+            sliced = t.narrow(1, start_b, blocks_per_chunk)
+            kv, _, bs, nh, hs = sliced.shape
+            flat = sliced.contiguous().view(kv, blocks_per_chunk * bs, nh * hs)
+            per_layer.append(flat)
+        # Stack along a new layer dim -> (2, NL, chunk_size, hidden).
+        chunk = torch.stack(per_layer, dim=1).contiguous()
+        if chunk.shape[1] != num_layers:
+            raise RuntimeError(
+                "unexpected chunk shape %s (NL mismatch)" % (chunk.shape,)
+            )
+        chunks.append(chunk)
+    return chunks
+
+
+def _scatter_flat_chunks_to_paged(
+    tensors: list["torch.Tensor"],
+    chunks: list["torch.Tensor"],
+    block_offset: int,
+    block_size: int,
+    chunk_size: int,
+) -> None:
+    """Inverse of :func:`_gather_paged_to_flat_chunks`.
+
+    Writes each ``[2, NL, chunk_size, hidden]`` flat chunk back into
+    the paged client tensors at the matching block range. Used by
+    the data-mode RETRIEVE path so the bench's client-side checksum
+    can compare cold ground truth with what the server returned.
+    """
+    if chunk_size % block_size != 0:
+        raise ValueError(
+            "chunk_size %d must be a multiple of block_size %d"
+            % (chunk_size, block_size)
+        )
+    blocks_per_chunk = chunk_size // block_size
+    for c, chunk in enumerate(chunks):
+        start_b = block_offset + c * blocks_per_chunk
+        for layer_idx, t in enumerate(tensors):
+            kv, _, bs, nh, hs = t.shape
+            target = t.narrow(1, start_b, blocks_per_chunk)
+            # chunk[:, layer_idx] is (chunk_size, hidden); reshape
+            # back to (2, blocks_per_chunk, BS, NH, HS).
+            flat = chunk[:, layer_idx]
+            reshaped = flat.reshape(kv, blocks_per_chunk, bs, nh, hs)
+            target.copy_(reshaped)
+
+
+# ------------------------------------------------------------------ #
+#  Client-side checksum / zero-fill (data-mode self-check)             #
+# ------------------------------------------------------------------ #
+
+
+def _compute_client_checksums(
+    tensors: list["torch.Tensor"],
+    block_offset: int,
+    num_blocks: int,
+    block_size: int,
+    chunk_size: int,
+) -> list[str]:
+    """Hash a paged block range from client-side KV tensors.
+
+    For each chunk (``chunk_size // block_size`` consecutive blocks),
+    feed every layer's bytes for that block range into a single MD5
+    digest. The returned list maps 1:1 to the chunks the bench loop
+    expects, so a cold-pass digest can be compared with a warm-pass
+    digest to verify that ``RETRIEVE`` actually wrote back the data
+    we wrote during ``STORE`` -- without relying on a server-side
+    ``/cache/checksums`` endpoint (which only exists in handle mode).
+    """
+    if chunk_size % block_size != 0:
+        raise ValueError(
+            "chunk_size %d must be a multiple of block_size %d"
+            % (chunk_size, block_size)
+        )
+    blocks_per_chunk = chunk_size // block_size
+    num_chunks = num_blocks // blocks_per_chunk
+    checksums: list[str] = []
+    for c in range(num_chunks):
+        start_b = block_offset + c * blocks_per_chunk
+        end_b = start_b + blocks_per_chunk
+        h = hashlib.md5()
+        for t in tensors:
+            # Paged layout: dim 1 is the block dim for both kv-major
+            # ``(kv, NB, BS, NH, HS)`` and MLA ``(NB, BS, NH, HS)``
+            # tensors. ``contiguous().numpy().tobytes()`` survives
+            # non-contiguous slices and dtype quirks (bfloat16 has no
+            # numpy view, but uint8 reinterpret works after slice).
+            view = t.narrow(1, start_b, end_b - start_b).contiguous()
+            h.update(view.view(torch.uint8).numpy().tobytes())
+        checksums.append(h.hexdigest())
+    return checksums
+
+
+def _zero_fill_client_blocks(
+    tensors: list["torch.Tensor"],
+    block_offset: int,
+    num_blocks: int,
+) -> None:
+    """Zero out a paged block range across all client tensors.
+
+    Used right before a warm-pass ``RETRIEVE`` so that any non-zero
+    bytes observed afterwards must have been written by the server.
+    Without this, a warm checksum equal to the cold checksum could
+    still happen even if ``RETRIEVE`` was a silent no-op (the SHM
+    pages were never overwritten in the first place).
+    """
+    for t in tensors:
+        t.narrow(1, block_offset, num_blocks).zero_()
+
+
+def _send_store(
+    client: MessageQueueClient,
+    key: IPCCacheServerKey,
+    block_offset: int = 0,
+    block_size: int = 16,
+    num_engine_group_infos: int = 1,
+    use_gpu: bool = True,
+    use_handle: bool | None = None,
+    client_tensors: list["torch.Tensor"] | None = None,
+    chunk_size: int = 0,
+    server_pool: "mmap.mmap | None" = None,
+) -> str:
+    """Store KV cache blocks. Returns status string.
+
+    Handle mode uses the single-shot ``STORE`` RPC (GPU CUDA-IPC, or
+    CPU SHM with an empty event handle).
+    Data mode uses the two-phase ``PREPARE_STORE`` + ``COMMIT_STORE``.
+    When ``server_pool`` and ``client_tensors`` are both supplied the
+    bench gathers the paged block range into flat per-chunk CPU
+    tensors and writes them straight into the server-owned SHM pool
+    via the slot descriptors returned by ``PREPARE_STORE``, so the
+    follow-up ``COMMIT_STORE`` carries an empty payload and the
+    server stays on its zero-copy SHM path.
+    """
+    if use_handle is None:
+        use_handle = use_gpu
+    if use_handle:
+        num_tokens = key.end - key.start
+        num_blocks = num_tokens // block_size
+        block_ids = list(range(block_offset, block_offset + num_blocks))
+        payloads = [
+            key,
+            _INSTANCE_ID,
+            [block_ids] * num_engine_group_infos,
+            _make_event_handle(),
+        ]
+        result = _call(client, RequestType.STORE, payloads)
+        if result is _TIMEOUT:
+            return "timeout"
+        return "stored" if result[1] else "store_failed"
+
+    # CPU mode: PREPARE_STORE -> COMMIT_STORE
+    prep = _call(client, RequestType.PREPARE_STORE, [key, _INSTANCE_ID])
+    if prep is _TIMEOUT:
+        return "timeout"
+    if server_pool is not None and client_tensors is not None and chunk_size > 0:
+        ctx = prep.context if isinstance(prep.context, dict) else {}
+        slots = ctx.get("slots", []) or []
+        chunk_indices = ctx.get("chunk_indices", []) or []
+        if slots and chunk_indices:
+            num_blocks = (key.end - key.start) // block_size
+            full_chunks = _gather_paged_to_flat_chunks(
+                client_tensors,
+                block_offset,
+                num_blocks,
+                block_size,
+                chunk_size,
+            )
+            slot_views = _build_server_slot_views(server_pool, slots)
+            for slot_view, chunk_idx in zip(slot_views, chunk_indices, strict=False):
+                if 0 <= chunk_idx < len(full_chunks):
+                    slot_view.copy_(full_chunks[chunk_idx].view(slot_view.shape))
+    commit = _call(client, RequestType.COMMIT_STORE, [key, _INSTANCE_ID, b""])
+    if commit is _TIMEOUT:
+        return "timeout"
+    return "stored" if commit else "store_failed"
+
+
+def _send_retrieve(
+    client: MessageQueueClient,
+    key: IPCCacheServerKey,
+    chunk_size: int,
+    hit_chunks: int,
+    block_offset: int = 0,
+    block_size: int = 16,
+    num_engine_group_infos: int = 1,
+    use_gpu: bool = True,
+    use_handle: bool | None = None,
+    client_tensors: list["torch.Tensor"] | None = None,
+    server_pool: "mmap.mmap | None" = None,
+) -> str:
+    """Retrieve KV cache blocks. Returns status.
+
+    Handle mode uses the single-shot ``RETRIEVE`` RPC (GPU CUDA-IPC, or
+    CPU SHM with an empty event handle).
+    Data mode uses the two-phase ``PREPARE_RETRIEVE`` +
+    ``COMMIT_RETRIEVE``. When ``server_pool`` and ``client_tensors``
+    are both supplied the bench builds zero-copy tensor views over
+    the slot descriptors returned by ``PREPARE_RETRIEVE`` and
+    scatters them back into the paged client SHM, so the round-trip
+    self-check can run without ``PREPARE_RETRIEVE`` having to ship a
+    pickled copy of the chunks.
+    """
+    if use_handle is None:
+        use_handle = use_gpu
+    if use_handle:
+        hit_tokens = hit_chunks * chunk_size
+        num_blocks = hit_tokens // block_size
+        block_ids = list(range(block_offset, block_offset + num_blocks))
+        payloads = [
+            key,
+            _INSTANCE_ID,
+            [block_ids] * num_engine_group_infos,
+            _make_event_handle(),
+            0,  # skip_first_n_tokens
+        ]
+        result = _call(client, RequestType.RETRIEVE, payloads)
+        if result is _TIMEOUT:
+            return "timeout"
+        return "retrieved" if result[1] else "retrieve_failed"
+
+    # CPU mode: PREPARE_RETRIEVE -> COMMIT_RETRIEVE
+    prep = _call(client, RequestType.PREPARE_RETRIEVE, [key, _INSTANCE_ID])
+    if prep is _TIMEOUT:
+        return "timeout"
+    if not prep.success:
+        return "retrieve_failed"
+    if server_pool is not None and client_tensors is not None:
+        ctx = prep.context if isinstance(prep.context, dict) else {}
+        slots = ctx.get("slots", []) or []
+        if slots:
+            try:
+                slot_views = _build_server_slot_views(server_pool, slots)
+                _scatter_flat_chunks_to_paged(
+                    client_tensors,
+                    slot_views,
+                    block_offset,
+                    block_size,
+                    chunk_size,
+                )
+            except (RuntimeError, ValueError) as exc:
+                print("  [WARNING] retrieve scatter failed: %s" % exc)
+    commit = _call(client, RequestType.COMMIT_RETRIEVE, [key, _INSTANCE_ID])
+    if commit is _TIMEOUT:
+        return "timeout"
+    return "retrieved" if commit else "retrieve_failed"
+
+
+def _send_end_session(
+    client: MessageQueueClient,
+    request_id: str,
+) -> None:
+    """END_SESSION — clean up server-side session state."""
+    _call(client, RequestType.END_SESSION, [request_id])
+
+
+# ------------------------------------------------------------------ #
+#  Checksum query                                                      #
+# ------------------------------------------------------------------ #
+
+
+def _query_checksum(
+    http_base: str,
+    block_offset: int,
+    num_blocks: int,
+    block_size: int,
+    chunk_size: int,
+) -> list[str] | None:
+    """Query KV cache checksums via the HTTP API.
+
+    Uses the MP-native ``block_ids`` + ``block_size`` addressing
+    scheme so the query matches the same block-level semantics
+    as ``STORE`` / ``RETRIEVE``. This CLI pins ``layerwise=false``
+    so the server always returns ``chunk_checksums`` as a flat
+    ``list[str]``. We still defensively validate the response
+    type — if a future endpoint variant returns a per-layer
+    ``dict`` we log and skip the comparison rather than letting
+    ``str.join`` crash.
+    """
+    blocks = list(range(block_offset, block_offset + num_blocks))
+    # The MP /cache/checksums endpoint is block-native: its chunk_size counts
+    # blocks per chunk, while our caller passes in the server-side token-level
+    # chunk_size. Convert here.
+    if chunk_size % block_size != 0:
+        print(
+            "  [WARNING] chunk_size %d not a multiple of block_size %d; "
+            "skipping checksum query" % (chunk_size, block_size)
+        )
+        return None
+    chunk_size_blocks = chunk_size // block_size
+    url = "%s/cache/checksums" % http_base
+    payload = json.dumps(
+        {"block_ids": blocks, "chunk_size": chunk_size_blocks, "layerwise": False}
+    ).encode()
+    try:
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode())
+            if data.get("status") != "success":
+                return None
+            checksums = data.get("chunk_checksums", [])
+            if not isinstance(checksums, list) or not all(
+                isinstance(c, str) for c in checksums
+            ):
+                print(
+                    "  [WARNING] unexpected chunk_checksums "
+                    "type=%s; expected list[str]" % type(checksums).__name__
+                )
+                return None
+            return checksums
+    except (urllib.error.URLError, OSError) as exc:
+        print("  [WARNING] Checksum query failed: %s" % exc)
+    return None
+
+
+# ------------------------------------------------------------------ #
+#  Per-request flow                                                    #
+# ------------------------------------------------------------------ #
+
+
+@dataclass
+class RequestResult:
+    """Result of a single request pass (cold or warm).
+
+    Carries both the checksum list (for correctness verification) and
+    per-operation latency measurements (for metrics aggregation).
+    """
+
+    checksums: list[str] | None = None
+    lookup_ms: float | None = None
+    retrieve_ms: float | None = None
+    store_ms: float | None = None
+    hit_chunks: int = 0
+    total_chunks: int = 0
+    store_tokens: int = 0
+    retrieve_tokens: int = 0
+
+
+def _process_request(
+    client: MessageQueueClient,
+    seq_no: int,
+    num_tokens: int,
+    chunk_size: int,
+    pass_label: str,
+    http_base: str = "",
+    block_size: int = 16,
+    total_blocks: int = 1024,
+    num_engine_group_infos: int = 1,
+    use_gpu: bool = True,
+    use_handle: bool | None = None,
+    client_tensors: list["torch.Tensor"] | None = None,
+    server_pool: "mmap.mmap | None" = None,
+) -> RequestResult | None:
+    """Run the full lookup -> retrieve/store flow.
+
+    When ``client_tensors`` is provided (data-mode self-check), the
+    flow gains two extra steps:
+
+    * cold pass: hash the paged block range *before* ``STORE``, so
+      the digest captures the ground-truth KV bytes.
+    * warm pass: zero-fill the same block range *before*
+      ``RETRIEVE``, then hash *after* ``RETRIEVE``. cold == warm
+      proves the server returned the exact bytes we sent.
+
+    Handle mode keeps the historical server-side
+    ``/cache/checksums`` path; client tensors are not consulted (in
+    handle mode the client and server share the same SHM/IPC
+    pages, so a client-side hash equals itself by construction).
+    """
+    token_ids = _build_token_ids(seq_no, num_tokens)
+    request_id = "req-%d-%s" % (seq_no, pass_label)
+
+    # Align end to chunk_size (only full chunks)
+    num_full_tokens = (len(token_ids) // chunk_size) * chunk_size
+    if num_full_tokens == 0:
+        print(
+            "  [seq %d/%s] SKIP: %d tokens < chunk_size %d"
+            % (seq_no, pass_label, len(token_ids), chunk_size)
+        )
+        return None
+
+    # Key for lookup (worker_id=None)
+    lookup_key = _make_key(
+        token_ids,
+        request_id,
+        start=0,
+        end=num_full_tokens,
+    )
+
+    # 1. LOOKUP
+    t0 = time.monotonic()
+    if not _send_lookup(client, lookup_key):
+        print("  [seq %d/%s] LOOKUP timeout" % (seq_no, pass_label))
+        return None
+
+    # 2. QUERY_PREFETCH_STATUS (poll by request_id)
+    hit_chunks = _poll_prefetch_status(client, lookup_key.request_id)
+    if hit_chunks is None:
+        hit_chunks = 0
+
+    total_chunks = num_full_tokens // chunk_size
+    miss_chunks = total_chunks - hit_chunks
+    hit_tokens = hit_chunks * chunk_size
+    lookup_ms = (time.monotonic() - t0) * 1000
+
+    print(
+        "  [seq %d/%s] LOOKUP: %d/%d chunks hit "
+        "(%.1f ms)"
+        % (
+            seq_no,
+            pass_label,
+            hit_chunks,
+            total_chunks,
+            lookup_ms,
+        )
+    )
+
+    # Block offset: each request uses a different block
+    # range so that different requests touch different data.
+    # Wrap with modulo and clamp so the entire range
+    # [block_offset, block_offset + num_blocks) stays
+    # within [0, total_blocks).
+    num_blocks = num_full_tokens // block_size
+    usable = max(total_blocks - num_blocks, 1)
+    block_offset = (seq_no * num_blocks) % usable
+
+    # Client-side self-check (data mode only). cold pass: snapshot
+    # ground truth before STORE. warm pass: zero out the slice so
+    # a successful RETRIEVE must overwrite every byte.
+    cold_ground_truth: list[str] | None = None
+    if client_tensors is not None:
+        if pass_label == "cold" and miss_chunks > 0:
+            store_block_off = block_offset + (hit_tokens // block_size)
+            store_num_blocks = (num_full_tokens - hit_tokens) // block_size
+            cold_ground_truth = _compute_client_checksums(
+                client_tensors,
+                store_block_off,
+                store_num_blocks,
+                block_size,
+                chunk_size,
+            )
+        if pass_label == "warm" and hit_chunks > 0:
+            retr_num_blocks = hit_tokens // block_size
+            _zero_fill_client_blocks(
+                client_tensors,
+                block_offset,
+                retr_num_blocks,
+            )
+
+    # 3. RETRIEVE hit portion
+    retrieve_ms: float = 0.0
+    store_ms: float = 0.0
+    if hit_chunks > 0:
+        retrieve_key = _make_key(
+            token_ids,
+            request_id,
+            start=0,
+            end=hit_tokens,
+            worker_id=0,
+        )
+        t1 = time.monotonic()
+        status = _send_retrieve(
+            client,
+            retrieve_key,
+            chunk_size,
+            hit_chunks,
+            block_offset=block_offset,
+            block_size=block_size,
+            num_engine_group_infos=num_engine_group_infos,
+            use_gpu=use_gpu,
+            use_handle=use_handle,
+            client_tensors=client_tensors,
+            server_pool=server_pool,
+        )
+        retrieve_ms = (time.monotonic() - t1) * 1000
+        print(
+            "  [seq %d/%s] RETRIEVE: %s "
+            "(%d tokens, %.1f ms)"
+            % (
+                seq_no,
+                pass_label,
+                status,
+                hit_tokens,
+                retrieve_ms,
+            )
+        )
+
+    # 4. STORE miss portion
+    if miss_chunks > 0:
+        store_start = hit_tokens
+        store_end = num_full_tokens
+        store_key = _make_key(
+            token_ids,
+            request_id,
+            start=store_start,
+            end=store_end,
+            worker_id=0,
+        )
+        t2 = time.monotonic()
+        store_block_off = block_offset + (hit_tokens // block_size)
+        status = _send_store(
+            client,
+            store_key,
+            block_offset=store_block_off,
+            block_size=block_size,
+            num_engine_group_infos=num_engine_group_infos,
+            use_gpu=use_gpu,
+            use_handle=use_handle,
+            client_tensors=client_tensors,
+            chunk_size=chunk_size,
+            server_pool=server_pool,
+        )
+        store_ms = (time.monotonic() - t2) * 1000
+        print(
+            "  [seq %d/%s] STORE: %s "
+            "(%d tokens, %.1f ms)"
+            % (
+                seq_no,
+                pass_label,
+                status,
+                store_end - store_start,
+                store_ms,
+            )
+        )
+
+    # 5. Compute checksums.
+    #   * data mode (client_tensors set):
+    #       cold -> ground truth captured pre-STORE
+    #       warm -> hash post-RETRIEVE; cold == warm proves the
+    #               server returned the exact bytes we wrote.
+    #   * handle mode: query /cache/checksums on the server, which
+    #     reads the shared SHM/IPC pages directly.
+    checksums: list[str] | None = None
+    if client_tensors is not None and num_full_tokens > 0:
+        if pass_label == "cold":
+            checksums = cold_ground_truth
+        elif pass_label == "warm" and hit_chunks > 0:
+            retr_num_blocks = hit_tokens // block_size
+            checksums = _compute_client_checksums(
+                client_tensors,
+                block_offset,
+                retr_num_blocks,
+                block_size,
+                chunk_size,
+            )
+    elif http_base and num_full_tokens > 0:
+        checksums = _query_checksum(
+            http_base,
+            block_offset,
+            num_blocks,
+            block_size,
+            chunk_size,
+        )
+    if checksums:
+        digest = hashlib.md5("".join(checksums).encode()).hexdigest()[:16]
+        print(
+            "  [seq %d/%s] CHECKSUM: %s (%d chunks)"
+            % (
+                seq_no,
+                pass_label,
+                digest,
+                len(checksums),
+            )
+        )
+
+    # 6. END_SESSION
+    _send_end_session(client, request_id)
+    return RequestResult(
+        checksums=checksums,
+        lookup_ms=lookup_ms,
+        retrieve_ms=retrieve_ms if hit_chunks > 0 else None,
+        store_ms=store_ms if miss_chunks > 0 else None,
+        hit_chunks=hit_chunks,
+        total_chunks=total_chunks,
+        store_tokens=(num_full_tokens - hit_tokens) if miss_chunks > 0 else 0,
+        retrieve_tokens=hit_tokens if hit_chunks > 0 else 0,
+    )
+
+
+# ------------------------------------------------------------------ #
+#  Server query helper                                                 #
+# ------------------------------------------------------------------ #
+
+
+def _get_chunk_size(client: MessageQueueClient) -> int:
+    """Query the server's chunk size."""
+    result = _call(client, RequestType.GET_CHUNK_SIZE, [])
+    if result is _TIMEOUT or result is None:
+        return 256  # fallback
+    return int(result)
diff --git a/lmcache/cli/commands/coordinator.py b/lmcache/cli/commands/coordinator.py
new file mode 100644
index 0000000..438d370
--- /dev/null
+++ b/lmcache/cli/commands/coordinator.py
@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache coordinator`` — launch the LMCache mp coordinator (HTTP).
+
+The coordinator tracks mp server instances via a registry and evicts those
+whose heartbeats lapse. Configuration falls back to ``LMCACHE_MP_COORDINATOR_*``
+environment variables; CLI flags override them.
+"""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class CoordinatorCommand(BaseCommand):
+    """CLI command that launches the LMCache mp coordinator (HTTP)."""
+
+    def name(self) -> str:
+        """Return the subcommand name.
+
+        Returns:
+            The string ``"coordinator"``.
+        """
+        return "coordinator"
+
+    def help(self) -> str:
+        """Return short help text.
+
+        Returns:
+            Help string shown by ``lmcache -h``.
+        """
+        return "Launch the LMCache mp coordinator (HTTP)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add coordinator-specific arguments to the parser.
+
+        Each flag defaults to ``None`` so that unset flags fall back to the
+        ``LMCACHE_MP_COORDINATOR_*`` environment variables (and then the
+        config defaults) in :meth:`execute`.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+        parser.add_argument(
+            "--host",
+            type=str,
+            default=None,
+            help="Host the coordinator's HTTP server binds to (default: 0.0.0.0).",
+        )
+        parser.add_argument(
+            "--port",
+            type=int,
+            default=None,
+            help="Port the coordinator's HTTP server binds to (default: 9300).",
+        )
+        parser.add_argument(
+            "--instance-timeout",
+            type=float,
+            default=None,
+            help=(
+                "Seconds without a heartbeat after which an instance is evicted "
+                "(default: 30)."
+            ),
+        )
+        parser.add_argument(
+            "--health-check-interval",
+            type=float,
+            default=None,
+            help=(
+                "Seconds between health-check sweeps; 0 disables the loop "
+                "(default: 10)."
+            ),
+        )
+        parser.add_argument(
+            "--eviction-check-interval",
+            type=float,
+            default=None,
+            help=(
+                "Seconds between L2 eviction sweeps; 0 disables the loop (default: 5)."
+            ),
+        )
+        parser.add_argument(
+            "--eviction-ratio",
+            type=float,
+            default=None,
+            help=(
+                "Fraction of tracked keys (by count) to evict per cycle, "
+                "0.0 to 1.0 (default: 0.2)."
+            ),
+        )
+        parser.add_argument(
+            "--trigger-watermark",
+            type=float,
+            default=None,
+            help=(
+                "Eviction fires when usage reaches this fraction of the "
+                "quota, 0.0 (exclusive) to 1.0 (default: 1.0)."
+            ),
+        )
+        parser.add_argument(
+            "--chunk-size",
+            type=int,
+            default=None,
+            help=(
+                "Tokens per KV chunk: the CacheBlend match unit and the unit used "
+                "to resolve pin token_ids to keys. Must equal the MP servers' "
+                "--chunk-size (default: 256)."
+            ),
+        )
+        parser.add_argument(
+            "--hash-algorithm",
+            type=str,
+            default=None,
+            help=(
+                "Token hash algorithm for pin key resolution; must equal the MP "
+                "servers' --hash-algorithm. 'blake3' (default) is self-contained; "
+                "other algorithms require vLLM importable in the coordinator."
+            ),
+        )
+        parser.add_argument(
+            "--blend-probe-stride",
+            type=int,
+            default=None,
+            help=(
+                "Positions between CacheBlend match probes; 1 probes every "
+                "offset for full recall (default: 1)."
+            ),
+        )
+        parser.add_argument(
+            "--timeout-keep-alive",
+            type=int,
+            default=None,
+            help=(
+                "Seconds the HTTP server keeps idle connections open "
+                "before closing them (default: 10)."
+            ),
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        """Build the coordinator config and serve the app with uvicorn.
+
+        Resolves config from the environment, then overrides any field whose
+        corresponding CLI flag was supplied.
+
+        Args:
+            args: Parsed CLI arguments.
+
+        Raises:
+            SystemExit: When coordinator dependencies are not installed.
+        """
+        # Standard
+        import dataclasses
+        import sys
+
+        try:
+            # Third Party
+            import uvicorn
+
+            # First Party
+            from lmcache.v1.mp_coordinator.app import create_app
+            from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+        except ImportError:
+            print(
+                "The 'lmcache coordinator' command requires the full lmcache "
+                "installation.\nInstall with: pip install lmcache",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        config = MPCoordinatorConfig.from_env()
+
+        overrides = {
+            field: value
+            for field, value in (
+                ("host", args.host),
+                ("port", args.port),
+                ("instance_timeout", args.instance_timeout),
+                ("health_check_interval", args.health_check_interval),
+                ("eviction_check_interval", args.eviction_check_interval),
+                ("eviction_ratio", args.eviction_ratio),
+                ("trigger_watermark", args.trigger_watermark),
+                ("chunk_size", args.chunk_size),
+                ("hash_algorithm", args.hash_algorithm),
+                ("blend_probe_stride", args.blend_probe_stride),
+                ("timeout_keep_alive", args.timeout_keep_alive),
+            )
+            if value is not None
+        }
+        if overrides:
+            config = dataclasses.replace(config, **overrides)
+
+        app = create_app(config)
+        uvicorn.run(
+            app,
+            host=config.host,
+            port=config.port,
+            log_level="info",
+            timeout_keep_alive=config.timeout_keep_alive,
+        )
diff --git a/lmcache/cli/commands/describe.py b/lmcache/cli/commands/describe.py
new file mode 100644
index 0000000..a94fd91
--- /dev/null
+++ b/lmcache/cli/commands/describe.py
@@ -0,0 +1,489 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache describe`` — show detailed status of a running LMCache service.
+
+Usage::
+
+    lmcache describe kvcache --url http://localhost:8000
+"""
+
+# Standard
+from typing import TYPE_CHECKING
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+
+# Third Party
+from prometheus_client.parser import text_string_to_metric_families
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.cli.metrics import Metrics
+
+# Default server URLs per describe target (ZMQ/HTTP semantics differ).
+DEFAULT_URLS: dict[str, str] = {
+    "kvcache": "http://localhost:8080",
+    "engine": "http://localhost:8000",
+}
+
+# -------------------------------------------------------------------
+# Shared helpers
+# -------------------------------------------------------------------
+
+
+class DescribeError(Exception):
+    """Raised when the describe command cannot fetch or parse status data."""
+
+
+def normalize_url(url: str) -> str:
+    """Ensure *url* has an ``http://`` or ``https://`` scheme."""
+    if not url.startswith(("http://", "https://")):
+        url = f"http://{url}"
+    return url.rstrip("/")
+
+
+def fetch_json(url: str, timeout: int = 10) -> dict:
+    """GET *url* and return the parsed JSON body.
+
+    Raises:
+        DescribeError: On network/HTTP errors.
+    """
+    req = urllib.request.Request(url)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as exc:
+        if exc.code == 503:
+            body = exc.read().decode()
+            try:
+                detail = json.loads(body).get("error", body)
+            except (json.JSONDecodeError, AttributeError):
+                detail = body
+            raise DescribeError(f"Server unhealthy: {detail}") from exc
+        raise DescribeError(f"HTTP {exc.code} from {url}: {exc.reason}") from exc
+    except urllib.error.URLError as exc:
+        raise DescribeError(f"Cannot connect to {url}: {exc.reason}") from exc
+    except OSError as exc:
+        raise DescribeError(f"Cannot connect to {url}: {exc}") from exc
+
+
+def fetch_health(url: str, timeout: int = 10) -> bool:
+    """Return whether *url* responds with HTTP 200.
+
+    A lightweight liveness probe for endpoints (e.g. the vLLM ``/health``
+    route) that return an empty body rather than JSON, so :func:`fetch_json`
+    cannot be used.
+
+    Args:
+        url: Full health-check URL to GET.
+        timeout: Socket timeout in seconds.
+
+    Returns:
+        ``True`` if the server responds with HTTP 200, ``False`` on any
+        non-200 status or connection error.
+    """
+    try:
+        with urllib.request.urlopen(
+            urllib.request.Request(url), timeout=timeout
+        ) as resp:
+            return resp.status == 200
+    except (urllib.error.URLError, OSError):
+        return False
+
+
+def fetch_running_requests(url: str, timeout: int = 10) -> int | None:
+    """Return the number of in-flight requests from a vLLM ``/metrics`` page.
+
+    Parses the Prometheus ``vllm:num_requests_running`` gauge, summing the
+    value across all reported series (e.g. one per model). This is best
+    effort: the metric is informational, so any failure to fetch or parse
+    degrades to ``None`` (rendered as ``N/A``) rather than raising.
+
+    Args:
+        url: Full ``/metrics`` URL to GET.
+        timeout: Socket timeout in seconds.
+
+    Returns:
+        The total running-request count, or ``None`` if the endpoint is
+        unreachable or the metric is absent (e.g. metrics disabled or an
+        unsupported engine version).
+    """
+    try:
+        with urllib.request.urlopen(
+            urllib.request.Request(url), timeout=timeout
+        ) as resp:
+            text = resp.read().decode()
+    except (urllib.error.URLError, OSError):
+        return None
+
+    total = 0.0
+    found = False
+    try:
+        for family in text_string_to_metric_families(text):
+            if family.name != "vllm:num_requests_running":
+                continue
+            for sample in family.samples:
+                total += sample.value
+                found = True
+    except ValueError:
+        # Malformed exposition text; treat as unavailable.
+        return None
+    return int(total) if found else None
+
+
+def fmt_bytes(n: int) -> str:
+    """Format a byte count as a human-readable string."""
+    if n >= 1024**3:
+        return f"{n / 1024**3:.2f} GB"
+    if n >= 1024**2:
+        return f"{n / 1024**2:.2f} MB"
+    if n >= 1024:
+        return f"{n / 1024:.2f} KB"
+    return f"{n} B"
+
+
+def fmt_health(is_healthy: object) -> str | None:
+    """Format a boolean health flag as ``'OK'`` / ``'UNHEALTHY'``."""
+    if is_healthy is None:
+        return None
+    return "OK" if is_healthy else "UNHEALTHY"
+
+
+def safe_get(data: dict, *keys, default=None):  # type: ignore[type-arg]
+    """Walk nested dicts by *keys*, returning *default* on any miss."""
+    cur: object = data
+    for key in keys:
+        if not isinstance(cur, dict):
+            return default
+        cur = cur.get(key)
+        if cur is None:
+            return default
+    return cur
+
+
+# -------------------------------------------------------------------
+# KVCache describer
+# -------------------------------------------------------------------
+
+
+class KVCacheDescriber:
+    """Builds the ``describe kvcache`` output from a ``/status`` response.
+
+    Each ``add_*`` method populates one logical section. The orchestrating
+    :meth:`describe` calls them in order and emits the result.  Adding a
+    new section is a one-method change — no other code needs to know
+    about it.
+    """
+
+    def __init__(self, metrics: "Metrics", data: dict, base_url: str) -> None:
+        self.metrics = metrics
+        self.data = data
+        self.base_url = base_url
+
+    def describe(self) -> None:
+        """Run all section builders and emit."""
+        self.add_overview()
+        self.add_l1_storage()
+        self.add_models()
+        self.add_l2_adapters()
+        self.metrics.emit()
+
+    # -- sections --------------------------------------------------------
+
+    def add_overview(self) -> None:
+        """Top-level engine overview."""
+        self.metrics.add("health", "Health", fmt_health(self.data.get("is_healthy")))
+        self.metrics.add("url", "URL", self.base_url)
+        self.metrics.add("engine_type", "Engine type", self.data.get("engine_type"))
+        self.metrics.add("chunk_size", "Chunk size", self.data.get("chunk_size"))
+
+    def add_l1_storage(self) -> None:
+        """L1 cache capacity, usage, eviction, and object count."""
+        total_bytes = safe_get(
+            self.data, "storage_manager", "l1_manager", "memory_total_bytes"
+        )
+        if total_bytes is not None:
+            self.metrics.add(
+                "l1_capacity_gb",
+                "L1 capacity (GB)",
+                round(total_bytes / (1024**3), 2),
+            )
+        else:
+            self.metrics.add("l1_capacity_gb", "L1 capacity (GB)", None)
+
+        used_bytes = safe_get(
+            self.data, "storage_manager", "l1_manager", "memory_used_bytes"
+        )
+        usage_ratio = safe_get(
+            self.data, "storage_manager", "l1_manager", "memory_usage_ratio"
+        )
+        if used_bytes is not None and usage_ratio is not None:
+            gb = used_bytes / (1024**3)
+            pct = usage_ratio * 100
+            self.metrics.add("l1_used_gb", "L1 used (GB)", f"{gb:.2f} ({pct:.1f}%)")
+        else:
+            self.metrics.add("l1_used_gb", "L1 used (GB)", None)
+
+        self.metrics.add(
+            "eviction_policy",
+            "Eviction policy",
+            safe_get(
+                self.data,
+                "storage_manager",
+                "eviction_controller",
+                "eviction_policy",
+            ),
+        )
+        self.metrics.add(
+            "cached_objects",
+            "Cached objects",
+            safe_get(self.data, "storage_manager", "l1_manager", "total_object_count"),
+        )
+        self.metrics.add(
+            "active_sessions", "Active sessions", self.data.get("active_sessions")
+        )
+
+    def add_models(self) -> None:
+        """Per-model KV cache layout sections.
+
+        Each model gets one section with context-wide fields, followed by
+        one ``kernel_groups`` list entry per kernel group carrying that
+        group's identity and geometry.
+        """
+        gpu_meta = self.data.get("cache_context_meta", {})
+        if not gpu_meta:
+            return
+
+        # Deduplicate by (model_name, world_size) — multiple GPU IDs
+        # may share the same model.
+        seen: dict[tuple[str, int], dict] = {}
+        for gpu_id, meta in gpu_meta.items():
+            key = (meta["model_name"], meta["world_size"])
+            if key not in seen:
+                seen[key] = {
+                    "gpu_ids": [],
+                    "layout": meta.get("kv_cache_layout"),
+                }
+            seen[key]["gpu_ids"].append(gpu_id)
+
+        for idx, ((model_name, world_size), info) in enumerate(seen.items()):
+            section_key = f"model_{idx}"
+            self.metrics.add_list_section("models", section_key, f"Model: {model_name}")
+            sec = self.metrics[section_key]
+            sec.add("model", "Model", model_name)
+            sec.add("world_size", "World size", world_size)
+            sec.add("gpu_ids", "GPU IDs", ", ".join(info["gpu_ids"]))
+
+            layout = info.get("layout")
+            if not layout:
+                continue
+            for _key, _label in (
+                ("num_layers", "Num layers"),
+                ("num_blocks", "Num blocks"),
+                ("cache_size_per_token", "Cache size per token (bytes)"),
+            ):
+                if _key in layout:
+                    sec.add(_key, _label, layout[_key])
+
+            self._add_kernel_groups(idx, model_name, layout.get("kernel_groups", []))
+
+    def _add_kernel_groups(
+        self, model_idx: int, model_name: str, kernel_groups: list
+    ) -> None:
+        """Emit one ``kernel_groups`` list section per kernel group.
+
+        Args:
+            model_idx: Index of the owning model section (keeps section keys
+                unique across models).
+            model_name: Human-readable model name, shown in each group header.
+            kernel_groups: The model layout's ``kernel_groups`` list (each a
+                dict produced by ``GPUCacheContext.report_status``).
+        """
+        for group in kernel_groups:
+            kg_idx = group.get("kernel_group_idx")
+            section_key = f"model_{model_idx}_kg_{kg_idx}"
+            self.metrics.add_list_section(
+                "kernel_groups",
+                section_key,
+                f"Kernel group {kg_idx} ({model_name})",
+            )
+            sec = self.metrics[section_key]
+            sec.add("model", "Model", model_name)
+            for _key, _label in (
+                ("kernel_group_idx", "Kernel group index"),
+                ("engine_group_idx", "Engine group index"),
+                ("object_group_idx", "Object group index"),
+                ("num_layers", "Num layers"),
+                ("tokens_per_block", "Tokens per block"),
+                ("slots_per_block", "Slots per block"),
+                ("dtype", "Dtype"),
+                ("is_mla", "MLA"),
+                ("attention_backend", "Attention backend"),
+                ("engine_kv_shape", "Engine KV shape"),
+                ("engine_kv_concrete_shape", "Engine KV tensor shape"),
+            ):
+                if _key in group:
+                    sec.add(_key, _label, group[_key])
+
+    def add_l2_adapters(self) -> None:
+        """L2 adapter sections."""
+        l2_adapters = safe_get(self.data, "storage_manager", "l2_adapters") or []
+        for idx, adapter in enumerate(l2_adapters):
+            adapter_type = adapter.get("type", "Unknown")
+            section_key = f"l2_{idx}"
+            self.metrics.add_list_section(
+                "l2_adapters", section_key, f"L2: {adapter_type}"
+            )
+            sec = self.metrics[section_key]
+            sec.add("type", "Type", adapter_type)
+            sec.add("health", "Health", fmt_health(adapter.get("is_healthy")))
+
+            if "backend" in adapter:
+                sec.add("backend", "Backend", adapter["backend"])
+            if "base_path" in adapter:
+                sec.add("base_path", "Base path", adapter["base_path"])
+            if "stored_object_count" in adapter:
+                sec.add(
+                    "stored_object_count",
+                    "Stored objects",
+                    adapter["stored_object_count"],
+                )
+
+            cap = adapter.get("max_capacity_bytes")
+            used = adapter.get("current_size_bytes")
+            if cap is not None and used is not None:
+                pct = used / cap * 100 if cap > 0 else 0.0
+                sec.add(
+                    "used",
+                    "Used",
+                    f"{fmt_bytes(used)} / {fmt_bytes(cap)} ({pct:.1f}%)",
+                )
+
+            pool_size = adapter.get("pool_size")
+            pool_free = adapter.get("pool_free_slots")
+            if pool_size is not None and pool_free is not None:
+                pool_used = pool_size - pool_free
+                pct = pool_used / pool_size * 100 if pool_size > 0 else 0.0
+                sec.add(
+                    "pool_used",
+                    "Pool used",
+                    f"{pool_used} / {pool_size} ({pct:.1f}%)",
+                )
+
+
+# -------------------------------------------------------------------
+# Engine describer
+# -------------------------------------------------------------------
+
+
+class EngineDescriber:
+    """Builds the ``describe engine`` output from vLLM server responses.
+
+    Reads model identity and context window from the engine's
+    ``/v1/models`` response and combines them with a ``/health`` liveness
+    result to render a concise status view.
+    """
+
+    def __init__(
+        self,
+        metrics: "Metrics",
+        models_data: dict,
+        is_healthy: bool,
+        running_requests: int | None,
+        base_url: str,
+    ) -> None:
+        self.metrics = metrics
+        self.models_data = models_data
+        self.is_healthy = is_healthy
+        self.running_requests = running_requests
+        self.base_url = base_url
+
+    def describe(self) -> None:
+        """Run all section builders and emit."""
+        self.add_overview()
+        self.metrics.emit()
+
+    def add_overview(self) -> None:
+        """Model identity, context window, health status, and load."""
+        model = self._first_model()
+        self.metrics.add("model", "Model", model.get("id") if model else None)
+        self.metrics.add(
+            "max_context",
+            "Max context (tokens)",
+            model.get("max_model_len") if model else None,
+        )
+        self.metrics.add("status", "Status", fmt_health(self.is_healthy))
+        self.metrics.add("running_requests", "Running requests", self.running_requests)
+
+    def _first_model(self) -> dict | None:
+        """Return the first model entry from a ``/v1/models`` response."""
+        data = self.models_data.get("data") or []
+        return data[0] if data else None
+
+
+# -------------------------------------------------------------------
+# Command
+# -------------------------------------------------------------------
+
+
+class DescribeCommand(BaseCommand):
+    """Show detailed status of a running LMCache service."""
+
+    def name(self) -> str:
+        return "describe"
+
+    def help(self) -> str:
+        return "Show detailed status of a running LMCache service."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "target",
+            choices=["kvcache", "engine"],
+            help="What to describe.",
+        )
+        parser.add_argument(
+            "--url",
+            default=None,
+            help=(
+                "Server URL (default: http://localhost:8080 for kvcache, "
+                "http://localhost:8000 for engine)."
+            ),
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        if getattr(args, "url", None) is None:
+            args.url = DEFAULT_URLS[args.target]
+        if args.target == "kvcache":
+            self._describe_kvcache(args)
+        elif args.target == "engine":
+            self._describe_engine(args)
+
+    def _describe_kvcache(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url)
+        try:
+            data = fetch_json(f"{base_url}/status")
+        except DescribeError as exc:
+            print(str(exc), file=sys.stderr)
+            sys.exit(1)
+
+        metrics = self.create_metrics("LMCache KV Cache Service", args, width=50)
+        KVCacheDescriber(metrics, data, base_url).describe()
+
+    def _describe_engine(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url)
+        try:
+            models = fetch_json(f"{base_url}/v1/models")
+        except DescribeError as exc:
+            print(str(exc), file=sys.stderr)
+            sys.exit(1)
+
+        is_healthy = fetch_health(f"{base_url}/health")
+        running_requests = fetch_running_requests(f"{base_url}/metrics")
+        metrics = self.create_metrics("Inference Engine", args, width=50)
+        EngineDescriber(
+            metrics, models, is_healthy, running_requests, base_url
+        ).describe()
diff --git a/lmcache/cli/commands/kvcache.py b/lmcache/cli/commands/kvcache.py
new file mode 100644
index 0000000..0dd64ba
--- /dev/null
+++ b/lmcache/cli/commands/kvcache.py
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache kvcache`` — KV cache management.
+
+Sub-commands:
+    clear         Clear all cached KV data
+"""
+
+# Standard
+from typing import Any, Optional
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def _http_request(
+    method: str, url: str, data: Optional[dict[str, Any]] = None
+) -> dict[str, Any]:
+    """Send an HTTP request and return the parsed JSON response.
+
+    Args:
+        method: HTTP method (GET, POST, PUT, DELETE).
+        url: Full URL to request.
+        data: Optional JSON body to send.
+
+    Returns:
+        Parsed JSON response as a dict.
+
+    Raises:
+        SystemExit: On connection error or non-2xx HTTP response.
+    """
+    body = None
+    headers: dict[str, str] = {}
+    if data is not None:
+        body = json.dumps(data).encode()
+        headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        try:
+            error_body = json.loads(e.read().decode())
+            msg = error_body.get("message") or error_body.get("error") or str(e)
+        except (json.JSONDecodeError, ValueError, OSError):
+            msg = str(e)
+        logger.error("Server error: %s", msg)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        logger.error("Cannot reach %s — is the server running? (%s)", url, e.reason)
+        sys.exit(1)
+
+
+class KVCacheCommand(BaseCommand):
+    """Manage KV cache state.
+
+    This command provides sub-commands for managing KV cache data on the
+    MP HTTP server. Currently supports clearing all L1 cache. Future
+    sub-commands (pin, compress, info) are defined in the design doc.
+    """
+
+    def name(self) -> str:
+        """Return the subcommand name.
+
+        Returns:
+            The string ``"kvcache"``.
+        """
+        return "kvcache"
+
+    def help(self) -> str:
+        """Return short help text.
+
+        Returns:
+            Help string shown by ``lmcache -h``.
+        """
+        return "Manage KV cache state."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add kvcache-specific sub-commands and their arguments.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+        sub = parser.add_subparsers(dest="action")
+
+        # clear
+        p_clear = sub.add_parser("clear", help="Clear all cached KV data in L1 (CPU).")
+        p_clear.add_argument(
+            "--url",
+            type=str,
+            required=True,
+            help="Target MP HTTP endpoint (e.g. http://localhost:8000).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        """Dispatch to the appropriate sub-command handler.
+
+        Args:
+            args: Parsed CLI arguments. Must contain ``action`` indicating
+                which sub-command was invoked.
+        """
+        action = getattr(args, "action", None)
+        if action is None:
+            logger.error("No sub-command specified. Run: lmcache kvcache -h")
+            sys.exit(1)
+
+        dispatch = {
+            "clear": self._clear,
+        }
+        dispatch[action](args)
+
+    def _clear(self, args: argparse.Namespace) -> None:
+        """Clear all cached KV data via the MP HTTP server."""
+        url = args.url.rstrip("/")
+
+        # MP HTTP server endpoint: POST /cache/clear
+        _http_request("POST", f"{url}/cache/clear", {"tier": "l1"})
+
+        quiet = getattr(args, "quiet", False)
+        if quiet:
+            return
+
+        metrics = self.create_metrics("KV Cache Clear", args)
+        metrics.add("status", "Status", "OK")
+        metrics.emit()
diff --git a/lmcache/cli/commands/mock.py b/lmcache/cli/commands/mock.py
new file mode 100644
index 0000000..3d37768
--- /dev/null
+++ b/lmcache/cli/commands/mock.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache mock`` — example command that demonstrates the CLI framework.
+
+This command does not connect to any server.  It generates fake metrics
+to exercise argument parsing, the ``Metrics`` logger, and both terminal
+and JSON output paths.
+"""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class MockCommand(BaseCommand):
+    """Mock command used as a reference implementation for new commands."""
+
+    def name(self) -> str:
+        """Return the subcommand name.
+
+        Returns:
+            The string ``"mock"``.
+        """
+        return "mock"
+
+    def help(self) -> str:
+        """Return short help text.
+
+        Returns:
+            Help string shown by ``lmcache -h``.
+        """
+        return "Run a mock command (example/test)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add mock-specific arguments.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+        parser.add_argument(
+            "--name",
+            type=str,
+            default="default",
+            help="Name tag for this mock run.",
+        )
+        parser.add_argument(
+            "--num-items",
+            type=int,
+            default=10,
+            help="Number of fake items to process.",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        """Execute the mock command.
+
+        Args:
+            args: Parsed CLI arguments containing ``name``, ``num_items``,
+                and optionally ``output``.
+        """
+        metrics = self.create_metrics("Mock Result", args, width=40)
+
+        metrics.add_section("input", "Input Parameters")
+        metrics["input"].add("name", "Name", args.name)
+        metrics["input"].add("num_items", "Num items", args.num_items)
+
+        metrics.add_section("mock", "Mock Metrics")
+        metrics["mock"].add("items_processed", "Items processed", 42)
+        metrics["mock"].add("total_time_ms", "Total time (ms)", 12.34)
+        metrics["mock"].add("throughput", "Throughput (items/s)", 3403.73)
+
+        metrics.add_section("validation", "Validation")
+        metrics["validation"].add("status", "Status", "OK")
+
+        metrics.emit()
diff --git a/lmcache/cli/commands/ping.py b/lmcache/cli/commands/ping.py
new file mode 100644
index 0000000..4e23f28
--- /dev/null
+++ b/lmcache/cli/commands/ping.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache ping`` — liveness check for LMCache and vLLM servers.
+
+Usage::
+
+    lmcache ping kvcache --url http://localhost:8080
+    lmcache ping engine  --url http://localhost:8000
+"""
+
+# Standard
+import argparse
+import sys
+import time
+import urllib.error
+import urllib.request
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.describe import normalize_url
+
+# -------------------------------------------------------------------
+# Constants
+# -------------------------------------------------------------------
+
+HEALTH_ENDPOINTS: dict[str, str] = {
+    "kvcache": "/healthcheck",
+    "engine": "/health",
+}
+
+DEFAULT_URLS: dict[str, str] = {
+    "kvcache": "http://localhost:8080",
+    "engine": "http://localhost:8000",
+}
+
+TITLES: dict[str, str] = {
+    "kvcache": "Ping KV Cache",
+    "engine": "Ping Engine",
+}
+
+# -------------------------------------------------------------------
+# Helper
+# -------------------------------------------------------------------
+
+
+def ping(url: str, timeout: int = 10) -> tuple[str, float, str | None]:
+    """GET *url* and return ``(status, rtt_ms, error_msg)``.
+
+    Returns:
+        ``("OK", rtt_ms, None)`` on HTTP 200.
+        ``("FAIL", rtt_ms, detail)`` on any error.
+    """
+    start = time.monotonic()
+    try:
+        with urllib.request.urlopen(
+            urllib.request.Request(url), timeout=timeout
+        ) as resp:
+            rtt_ms = (time.monotonic() - start) * 1000
+            if resp.status == 200:
+                return ("OK", rtt_ms, None)
+            return ("FAIL", rtt_ms, f"HTTP {resp.status}")
+    except urllib.error.HTTPError as exc:
+        rtt_ms = (time.monotonic() - start) * 1000
+        return ("FAIL", rtt_ms, f"HTTP {exc.code}: {exc.reason}")
+    except (urllib.error.URLError, OSError) as exc:
+        rtt_ms = (time.monotonic() - start) * 1000
+        reason = getattr(exc, "reason", str(exc))
+        return ("FAIL", rtt_ms, f"Cannot connect to {url}: {reason}")
+
+
+# -------------------------------------------------------------------
+# Command
+# -------------------------------------------------------------------
+
+
+class PingCommand(BaseCommand):
+    """Ping LMCache or vLLM server (liveness check)."""
+
+    def name(self) -> str:
+        return "ping"
+
+    def help(self) -> str:
+        return "Ping LMCache or vLLM server (liveness check)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "target",
+            choices=["kvcache", "engine"],
+            help="What to ping.",
+        )
+        parser.add_argument(
+            "--url",
+            default=None,
+            help=(
+                "Server URL (default: http://localhost:8080 for kvcache, "
+                "http://localhost:8000 for engine)."
+            ),
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url or DEFAULT_URLS[args.target])
+        endpoint = HEALTH_ENDPOINTS[args.target]
+        title = TITLES[args.target]
+
+        status, rtt_ms, error = ping(f"{base_url}{endpoint}")
+
+        metrics = self.create_metrics(title, args, width=30)
+        metrics.add("status", "Status", status)
+        metrics.add("round_trip_time_ms", "Round trip time (ms)", round(rtt_ms, 2))
+        metrics.emit()
+
+        if error:
+            print(error, file=sys.stderr)
+            sys.exit(1)
diff --git a/lmcache/cli/commands/query/__init__.py b/lmcache/cli/commands/query/__init__.py
new file mode 100644
index 0000000..8d1271e
--- /dev/null
+++ b/lmcache/cli/commands/query/__init__.py
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache query`` command — single-shot inference request interface.
+
+Sub-subcommands are auto-discovered from modules in this package.
+To add a new subcommand, create a module defining a concrete
+:class:`BaseCommand` subclass — no edits to this file are required.
+"""
+
+# First Party
+from lmcache.cli.commands.base import CompositeCommand
+
+
+class QueryCommand(CompositeCommand):
+    """CLI command that sends one request to a serving engine."""
+
+    def name(self) -> str:
+        return "query"
+
+    def help(self) -> str:
+        return "Run one inference request and report metrics."
diff --git a/lmcache/cli/commands/query/_prompt.py b/lmcache/cli/commands/query/_prompt.py
new file mode 100644
index 0000000..b26f32f
--- /dev/null
+++ b/lmcache/cli/commands/query/_prompt.py
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Prompt placeholder expansion helpers for ``lmcache query``."""
+
+# Standard
+from pathlib import Path
+from typing import Optional
+import re
+
+PLACEHOLDER = re.compile(r"\{(\w+)\}")
+BUILTIN_DOCUMENT_PATHS = {
+    "lmcache": (
+        Path(__file__).resolve().parent.parent.parent / "documents" / "lmcache.txt"
+    ),
+}
+
+
+class PromptBuilder:
+    """Build a complete prompt from CLI inputs."""
+
+    def __init__(self, prompt: str, documents_args: Optional[list[str]] = None) -> None:
+        self._complete_prompt = self.expand_prompt(prompt, documents_args or [])
+
+    @property
+    def complete_prompt(self) -> str:
+        """Return the expanded prompt from constructor inputs."""
+        return self._complete_prompt
+
+    def expand_prompt(
+        self,
+        prompt: str,
+        documents_args: Optional[list[str]] = None,
+    ) -> str:
+        """Expand placeholders and return the complete prompt text.
+
+        Args:
+            prompt: The prompt template string with {name} placeholders.
+            documents_args: Optional list of document paths or NAME=PATH strings.
+
+        Returns:
+            The expanded prompt string.
+        """
+        docs_args = documents_args or []
+        documents, appended_text = resolve_documents(prompt, docs_args)
+
+        for key in _unique_placeholders(prompt):
+            if key not in documents:
+                unknown_documents(key)
+
+        complete_prompt = PLACEHOLDER.sub(
+            lambda match: documents[match.group(1)], prompt
+        )
+        if appended_text:
+            complete_prompt = (
+                f"{complete_prompt}\n{appended_text}"
+                if complete_prompt
+                else appended_text
+            )
+        return complete_prompt
+
+
+def resolve_documents(
+    prompt_template: str, documents_args: list[str]
+) -> tuple[dict[str, str], str]:
+    """Resolve ``--documents`` args into placeholder mapping and trailing text.
+
+    Args:
+        prompt_template: The prompt string containing placeholders.
+        documents_args: List of document arguments from the CLI.
+
+    Returns:
+        A tuple containing a dictionary mapping placeholder names to document
+        content and a string containing any appended document text.
+    """
+    placeholders = _unique_placeholders(prompt_template)
+    documents: dict[str, str] = {}
+    plain_docs: list[str] = []
+    for item in documents_args:
+        if "=" not in item:
+            plain_docs.append(_read_document_file(item))
+            continue
+        name, path = [x.strip() for x in item.split("=", 1)]
+        if not name:
+            raise ValueError(f"Invalid --documents {item!r}; empty name")
+        documents[name] = _read_document_file(path, name=name)
+
+    unresolved = [key for key in placeholders if key not in documents]
+    for idx, key in enumerate(unresolved[: len(plain_docs)]):
+        documents[key] = plain_docs[idx]
+    appended_docs = plain_docs[len(unresolved) :]
+
+    for key in placeholders:
+        if key in documents:
+            continue
+        builtin_path = BUILTIN_DOCUMENT_PATHS.get(key)
+        if builtin_path is None:
+            continue
+        documents[key] = _read_document_file(str(builtin_path), name=key)
+
+    return documents, "\n".join(appended_docs).strip()
+
+
+def unknown_documents(key: str) -> None:
+    """Raise an error for a missing documents placeholder.
+
+    Args:
+        key: The name of the missing placeholder.
+
+    Raises:
+        ValueError: Always raised with a descriptive message.
+    """
+    raise ValueError(
+        f"Unknown documents {key!r}. Define it with --documents {key}=PATH "
+    )
+
+
+def _read_document_file(path: str, *, name: Optional[str] = None) -> str:
+    file_path = Path(path).expanduser()
+    if not file_path.is_file():
+        if name is not None:
+            raise ValueError(f"documents file not found for {name!r}: {file_path}")
+        raise ValueError(f"documents file not found: {file_path}")
+    return file_path.read_text(encoding="utf-8", errors="replace")
+
+
+def _unique_placeholders(prompt_template: str) -> list[str]:
+    seen: set[str] = set()
+    keys: list[str] = []
+    for match in PLACEHOLDER.finditer(prompt_template):
+        key = match.group(1)
+        if key in seen:
+            continue
+        seen.add(key)
+        keys.append(key)
+    return keys
diff --git a/lmcache/cli/commands/query/_request.py b/lmcache/cli/commands/query/_request.py
new file mode 100644
index 0000000..f1564fd
--- /dev/null
+++ b/lmcache/cli/commands/query/_request.py
@@ -0,0 +1,368 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP request for VLLM Serving Engine."""
+
+# Standard
+from typing import Any, Optional
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+
+_MAX_ERR = 65536
+MetricValue = tuple[str, Any]
+MetricMap = dict[str, MetricValue]
+_METRIC_NAMES = {
+    "prompt_tokens": "Input tokens",
+    "output_tokens": "Output tokens",
+    "ttft_ms": "TTFT (ms)",
+    "tpot_ms_per_token": "TPOT (ms/token)",
+    "total_latency_ms": "Total latency (ms)",
+    "throughput_tokens_per_s": "Throughput (tokens/s)",
+    "model": "Model",
+}
+
+
+def _clip(text: str, limit: int = _MAX_ERR) -> str:
+    return (
+        text
+        if len(text) <= limit
+        else text[: max(0, limit - 24)] + "\n...(message truncated)..."
+    )
+
+
+def _info(msg: str) -> None:
+    print(f"lmcache query: {msg}", file=sys.stderr)
+
+
+def _openai_error(obj: dict[str, Any]) -> Optional[str]:
+    err = obj.get("error")
+    if err is None:
+        return None
+    if isinstance(err, str):
+        return err.strip() or None
+    if not isinstance(err, dict):
+        return _clip(str(err))
+    for key in ("message", "detail"):
+        val = err.get(key)
+        if not isinstance(val, str) or not val.strip():
+            continue
+        typ = err.get("type") or err.get("code")
+        if key == "message" and isinstance(typ, str) and typ.strip():
+            return f"{typ.strip()}: {val.strip()}"
+        return val.strip()
+    try:
+        return _clip(json.dumps(err, ensure_ascii=False))
+    except Exception:
+        return _clip(str(err))
+
+
+def _raise_openai_error(obj: dict[str, Any]) -> None:
+    msg = _openai_error(obj)
+    if msg:
+        raise RuntimeError(_clip(msg))
+
+
+def _raise_json_blob_error(blob: str) -> None:
+    s = blob.strip()
+    if not s.startswith("{"):
+        return
+    try:
+        obj = json.loads(s)
+    except json.JSONDecodeError:
+        return
+    if isinstance(obj, dict):
+        _raise_openai_error(obj)
+
+
+def _api_url(base: str, path: str) -> str:
+    base = base.strip()
+    if "://" not in base:
+        base = f"http://{base}"
+    base = base.rstrip("/")
+    return f"{base if base.endswith('/v1') else base + '/v1'}/{path}"
+
+
+def _read_json(url: str, timeout: float) -> dict[str, Any]:
+    try:
+        with urllib.request.urlopen(
+            urllib.request.Request(url, method="GET"), timeout=max(timeout + 2.0, 5.0)
+        ) as resp:
+            raw = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")[:512]
+        raise RuntimeError(
+            f"GET {url} failed (HTTP {e.code}): {body or 'no body'}"
+        ) from e
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"GET {url} failed: {getattr(e, 'reason', e)}") from e
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"Invalid JSON from GET {url}: {e}") from e
+    if not isinstance(obj, dict):
+        raise RuntimeError(f"GET {url}: expected a JSON object")
+    return obj
+
+
+def _sse_piece(obj: dict[str, Any], chat: bool) -> str:
+    choices = obj.get("choices") or []
+    if not choices:
+        return ""
+    c0 = choices[0]
+    return (
+        str((c0.get("delta") or {}).get("content") or "")
+        if chat
+        else str(c0.get("text") or "")
+    )
+
+
+def _trim_misc_buffer(misc: list[str], limit: int = _MAX_ERR) -> None:
+    while misc and sum(map(len, misc)) > limit:
+        misc.pop(0)
+
+
+def _stream(
+    url: str,
+    body: dict[str, Any],
+    timeout: float,
+    *,
+    chat: bool,
+    max_tokens: int,
+) -> dict[str, Any]:
+    """POST with ``stream: true``; parse SSE; return the completion text plus
+    TTFT/TPOT and token metrics."""
+    payload = {
+        **body,
+        "stream": True,
+        "stream_options": {"include_usage": True},
+    }
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        method="POST",
+        headers={"Content-Type": "application/json"},
+    )
+    t0, first_token_t, pieces, usage, misc = time.time(), None, [], None, []
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            while True:
+                raw = resp.readline()
+                if not raw:
+                    break
+                line = raw.decode("utf-8", errors="replace").strip()
+                if not line:
+                    continue
+                if not line.startswith("data:"):
+                    misc.append(line)
+                    _trim_misc_buffer(misc)
+                    continue
+                chunk = line[5:].strip()
+                if chunk == "[DONE]":
+                    break
+                try:
+                    obj = json.loads(chunk)
+                except json.JSONDecodeError:
+                    misc.append(chunk)
+                    _trim_misc_buffer(misc)
+                    continue
+                if not isinstance(obj, dict):
+                    continue
+                _raise_openai_error(obj)
+                piece = _sse_piece(obj, chat)
+                if piece:
+                    first_token_t = first_token_t or time.time()
+                    pieces.append(piece)
+
+                u_chunk = obj.get("usage")
+                if u_chunk is not None:
+                    usage = u_chunk
+            t1 = time.time()
+    except urllib.error.HTTPError as e:
+        err_body = e.read().decode("utf-8", errors="replace")
+        _raise_json_blob_error(err_body)
+        raise RuntimeError(
+            _clip(f"POST {url} failed (HTTP {e.code}):\n{_clip(err_body)}")
+        ) from e
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"POST {url} failed: {getattr(e, 'reason', e)}") from e
+
+    misc_text = "\n".join(misc).strip()
+    _raise_json_blob_error(misc_text)
+    joined = "".join(pieces)
+    if not joined and usage is None:
+        raise RuntimeError(
+            _clip(f"No completion output from engine. Captured response:\n{misc_text}")
+            if misc_text
+            else "Empty response from engine (no SSE chunks parsed)."
+        )
+
+    u = usage or {}
+    prompt_tokens = int(u.get("prompt_tokens") or 0)
+    num_completion = int(u.get("completion_tokens") or 0)
+    # Match V2RequestSender: server count if present, else max_tokens cap.
+    num_generated = num_completion if num_completion > 0 else max_tokens
+    if first_token_t is None:
+        # Use total round-trip as a conservative TTFT approximation.
+        ttft_s = t1 - t0
+        decode_time = 0.0
+    else:
+        ttft_s = first_token_t - t0
+        decode_time = t1 - first_token_t
+    dt = t1 - t0
+    decoding_speed = (num_generated / decode_time) if decode_time > 0 else 0.0
+    tpot_s = (
+        (decode_time / num_generated) if num_generated > 0 and decode_time > 0 else 0.0
+    )
+    return {
+        "answer": joined,
+        "prompt_tokens": prompt_tokens,
+        "output_tokens": num_generated,
+        "ttft_ms": ttft_s * 1000.0,
+        "tpot_ms_per_token": tpot_s * 1000.0,
+        "total_latency_ms": dt * 1000.0,
+        "throughput_tokens_per_s": decoding_speed,
+    }
+
+
+def _missing_chat_template(exc: BaseException) -> bool:
+    msg = str(exc).lower()
+    return any(
+        s in msg
+        for s in (
+            "chat template",
+            "chat_template",
+            "chattemplate",
+            "template resolution",
+            "must provide a chat template",
+            "default chat template is no longer allowed",
+        )
+    )
+
+
+def _weak_completions_error(msg: str) -> bool:
+    msg = msg.lower()
+    return any(
+        s in msg
+        for s in (
+            "empty response from engine",
+            "no completion output from engine",
+            "no sse chunks parsed",
+        )
+    )
+
+
+class Request:
+    """Build and send one query request against an OpenAI-compatible endpoint."""
+
+    def __init__(
+        self,
+        base: str,
+        model: Optional[str],
+        max_tokens: int,
+        timeout: float,
+        *,
+        completions_only: bool = False,
+        chat_first: bool = False,
+    ) -> None:
+        self._base = base
+        self._model = model
+        self._max_tokens = max_tokens
+        self._timeout = timeout
+        self._completions_only = completions_only
+        self._chat_first = chat_first
+
+    def build_request(self, prompt: str) -> dict[str, Any]:
+        """Build request payload and metadata for the provided prompt."""
+        model = self._model or self._first_model_id()
+        return {
+            "base": self._base,
+            "model": model,
+            "prompt": prompt,
+            "max_tokens": self._max_tokens,
+            "timeout": self._timeout,
+            "completions_only": self._completions_only,
+            "chat_first": self._chat_first,
+        }
+
+    def send_request(self, prompt: str) -> tuple[str, MetricMap]:
+        """Send request and return the completion text and its metrics.
+
+        Args:
+            prompt: The fully expanded prompt to send to the engine.
+
+        Returns:
+            A ``(answer, metrics)`` tuple where ``answer`` is the model's
+            completion text and ``metrics`` is a :data:`MetricMap` of token
+            and latency stats keyed by metric id.
+        """
+        request_data = self.build_request(prompt)
+        result = self._query_with_fallback(request_data)
+        answer = str(result.pop("answer", ""))
+        stats = {"model": request_data["model"], **result}
+        metrics = {key: (_METRIC_NAMES.get(key, key), stats[key]) for key in stats}
+        return answer, metrics
+
+    def _first_model_id(self) -> str:
+        """Return the first model ID from ``GET /v1/models``."""
+        obj = _read_json(_api_url(self._base, "models"), self._timeout)
+        data = obj.get("data")
+        if not isinstance(data, list) or not data:
+            raise RuntimeError(
+                "GET /v1/models returned no models; pass --model explicitly."
+            )
+        first = data[0]
+        if not isinstance(first, dict) or "id" not in first:
+            raise RuntimeError("GET /v1/models: first entry missing 'id'.")
+        return str(first["id"])
+
+    def _query_with_fallback(self, request_data: dict[str, Any]) -> dict[str, Any]:
+        """Send one query and fallback between completions/chat endpoints."""
+        if request_data["completions_only"]:
+            return self._query(request_data, chat=False)
+        try:
+            return self._query(request_data, chat=request_data["chat_first"])
+        except RuntimeError as first_err:
+            if request_data["chat_first"]:
+                if not _missing_chat_template(first_err):
+                    raise
+                _info(
+                    "chat API failed (no chat template); retrying with /v1/completions"
+                )
+                return self._query(request_data, chat=False)
+            _info("/v1/completions failed; retrying with /v1/chat/completions")
+            try:
+                return self._query(request_data, chat=True)
+            except RuntimeError as second_err:
+                if _weak_completions_error(str(first_err)) and _missing_chat_template(
+                    second_err
+                ):
+                    _info(
+                        "base / completion-only models: try `--completions` or "
+                        "an instruct model with a chat template."
+                    )
+                    raise second_err
+                raise RuntimeError(f"{first_err}; then {second_err}") from second_err
+
+    def _query(self, request_data: dict[str, Any], *, chat: bool) -> dict[str, Any]:
+        path = "chat/completions" if chat else "completions"
+        model = request_data["model"]
+        prompt = request_data["prompt"]
+        max_tokens = request_data["max_tokens"]
+        timeout = request_data["timeout"]
+        body = (
+            {
+                "model": model,
+                "messages": [{"role": "user", "content": prompt}],
+                "max_tokens": max_tokens,
+            }
+            if chat
+            else {"model": model, "prompt": prompt, "max_tokens": max_tokens}
+        )
+        return _stream(
+            _api_url(request_data["base"], path),
+            body,
+            timeout,
+            chat=chat,
+            max_tokens=max_tokens,
+        )
diff --git a/lmcache/cli/commands/query/engine_command.py b/lmcache/cli/commands/query/engine_command.py
new file mode 100644
index 0000000..49faa76
--- /dev/null
+++ b/lmcache/cli/commands/query/engine_command.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache query engine`` — send one request to an OpenAI-compatible API."""
+
+# Standard
+import argparse
+import sys
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.query._prompt import PromptBuilder
+from lmcache.cli.commands.query._request import Request
+
+
+class EngineCommand(BaseCommand):
+    """Send one request to an OpenAI-compatible HTTP API."""
+
+    def name(self) -> str:
+        return "engine"
+
+    def help(self) -> str:
+        return "Send one request to an OpenAI-compatible HTTP API."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("--url", required=True, help="Serving engine base URL.")
+        parser.add_argument(
+            "--prompt",
+            required=True,
+            help="Prompt text with optional {name} placeholders.",
+        )
+        parser.add_argument(
+            "--model",
+            default=None,
+            metavar="ID",
+            help="Model ID for the serving engine.",
+        )
+        parser.add_argument(
+            "--max-tokens",
+            type=int,
+            default=128,
+            help="Maximum completion tokens (default: 128).",
+        )
+        parser.add_argument(
+            "--timeout",
+            type=float,
+            default=30.0,
+            help="HTTP timeout in seconds (default: 30).",
+        )
+        parser.add_argument(
+            "--documents",
+            action="extend",
+            nargs="+",
+            default=[],
+            metavar="NAME=PATH",
+            help=(
+                "Load file text for {NAME} in --prompt. "
+                "Accepts one or more NAME=PATH values."
+            ),
+        )
+        parser.add_argument(
+            "--path",
+            dest="documents",
+            action="extend",
+            nargs="+",
+            metavar="NAME=PATH",
+            help=argparse.SUPPRESS,
+        )
+        parser.add_argument(
+            "--completions",
+            action="store_true",
+            help="Use POST /v1/completions only.",
+        )
+        parser.add_argument(
+            "--chat-first",
+            action="store_true",
+            help="Try /v1/chat/completions first, then fall back to /v1/completions.",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        try:
+            prompt_builder = PromptBuilder(args.prompt, args.documents)
+            sender = Request(
+                base=args.url,
+                model=args.model,
+                max_tokens=args.max_tokens,
+                timeout=args.timeout,
+                completions_only=args.completions,
+                chat_first=args.chat_first,
+            )
+            answer, engine_stats = sender.send_request(prompt_builder.complete_prompt)
+
+            model_id = args.model or str(engine_stats["model"][1])
+            metrics = self.create_metrics("Query Engine", args)
+            metrics.add("model", "Model", model_id)
+            metrics.add("answer", "Answer", answer)
+            prompt_name, prompt_value = engine_stats["prompt_tokens"]
+            metrics.add("prompt_tokens", prompt_name, int(prompt_value))
+            output_name, output_value = engine_stats["output_tokens"]
+            metrics.add("output_tokens", output_name, int(output_value))
+
+            latency = metrics.add_section("latency", "Latency Metrics")
+            for key, (name, value) in engine_stats.items():
+                if key in ("model", "prompt_tokens", "output_tokens"):
+                    continue
+                latency.add(key, name, round(float(value), 2))
+
+            metrics.emit()
+        except (RuntimeError, ValueError) as err:
+            print(str(err), file=sys.stderr)
+            sys.exit(1)
diff --git a/lmcache/cli/commands/query/kvcache_command.py b/lmcache/cli/commands/query/kvcache_command.py
new file mode 100644
index 0000000..793500f
--- /dev/null
+++ b/lmcache/cli/commands/query/kvcache_command.py
@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache query kvcache`` — query KV-cache endpoints (placeholder)."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class KVCacheCommand(BaseCommand):
+    """Query KV-cache endpoints (not implemented yet)."""
+
+    def name(self) -> str:
+        return "kvcache"
+
+    def help(self) -> str:
+        return "Query KV-cache endpoints (not implemented yet)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        pass  # TODO: add kvcache query arguments
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # TODO: implement kvcache query logic
+        pass
diff --git a/lmcache/cli/commands/quota/__init__.py b/lmcache/cli/commands/quota/__init__.py
new file mode 100644
index 0000000..c6504e4
--- /dev/null
+++ b/lmcache/cli/commands/quota/__init__.py
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache quota`` command — per-salt quota management.
+
+Sub-subcommands are auto-discovered from modules in this package.
+To add a new subcommand, create a module defining a concrete
+:class:`BaseCommand` subclass — no edits to this file are required.
+"""
+
+# First Party
+from lmcache.cli.commands.base import CompositeCommand
+
+
+class QuotaCommand(CompositeCommand):
+    """CLI command for per-salt quota management on LMCache server."""
+
+    def name(self) -> str:
+        return "quota"
+
+    def help(self) -> str:
+        return "Manage per-salt cache quotas."
diff --git a/lmcache/cli/commands/quota/_helpers.py b/lmcache/cli/commands/quota/_helpers.py
new file mode 100644
index 0000000..4d64ee6
--- /dev/null
+++ b/lmcache/cli/commands/quota/_helpers.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared helpers for ``lmcache quota`` subcommands."""
+
+# Standard
+from typing import Any, Optional
+import json
+import sys
+import urllib.error
+import urllib.request
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# The MP HTTP server uses "_default" as a sentinel for the empty-string
+# cache_salt (anonymous / un-salted traffic).
+DEFAULT_SALT_SENTINEL = "_default"
+
+
+def normalize_url(url: str) -> str:
+    """Ensure *url* has an ``http://`` or ``https://`` scheme."""
+    if not url.startswith(("http://", "https://")):
+        url = f"http://{url}"
+    return url.rstrip("/")
+
+
+def escape_salt(salt: str) -> str:
+    """Translate the empty-string salt to the URL sentinel."""
+    return DEFAULT_SALT_SENTINEL if salt == "" else salt
+
+
+def unescape_salt(salt: str) -> str:
+    """Translate the URL sentinel back to the empty-string salt."""
+    return "" if salt == DEFAULT_SALT_SENTINEL else salt
+
+
+def http_request(
+    method: str,
+    url: str,
+    data: Optional[dict[str, Any]] = None,
+    timeout: int = 10,
+) -> dict[str, Any]:
+    """Send an HTTP request and return the parsed JSON response.
+
+    Args:
+        method: HTTP method (GET, POST, PUT, DELETE).
+        url: Full URL to request.
+        data: Optional JSON body to send.
+        timeout: HTTP timeout in seconds.
+
+    Returns:
+        Parsed JSON response as a dict.
+
+    Raises:
+        SystemExit: On connection error or non-2xx HTTP response.
+    """
+    body = None
+    headers: dict[str, str] = {}
+    if data is not None:
+        body = json.dumps(data).encode()
+        headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        try:
+            error_body = json.loads(e.read().decode())
+            msg = error_body.get("error") or error_body.get("message") or str(e)
+        except (json.JSONDecodeError, ValueError, OSError):
+            msg = str(e)
+        logger.error("Server error: %s", msg)
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        logger.error("Cannot reach %s — is the server running? (%s)", url, e.reason)
+        sys.exit(1)
diff --git a/lmcache/cli/commands/quota/delete_command.py b/lmcache/cli/commands/quota/delete_command.py
new file mode 100644
index 0000000..f8c88bb
--- /dev/null
+++ b/lmcache/cli/commands/quota/delete_command.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache quota delete`` — remove a quota for a cache_salt."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.quota._helpers import (
+    escape_salt,
+    http_request,
+    normalize_url,
+)
+
+
+class DeleteCommand(BaseCommand):
+    """Remove a quota for a cache_salt."""
+
+    def name(self) -> str:
+        return "delete"
+
+    def help(self) -> str:
+        return "Remove a quota for a cache_salt."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "salt",
+            type=str,
+            help=(
+                "The cache_salt identifier. Use '_default' for anonymous "
+                "(un-salted) traffic."
+            ),
+        )
+        parser.add_argument(
+            "--url",
+            type=str,
+            default="http://localhost:8080",
+            help="LMCache HTTP server URL (default: http://localhost:8080).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url)
+        salt = escape_salt(args.salt)
+
+        result = http_request("DELETE", f"{base_url}/quota/{salt}")
+
+        metrics = self.create_metrics("Quota Delete", args)
+        metrics.add("cache_salt", "Cache salt", result.get("cache_salt", salt))
+        metrics.add("status", "Status", result.get("status", "unknown"))
+        metrics.emit()
diff --git a/lmcache/cli/commands/quota/get_command.py b/lmcache/cli/commands/quota/get_command.py
new file mode 100644
index 0000000..17039ad
--- /dev/null
+++ b/lmcache/cli/commands/quota/get_command.py
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache quota get`` — read the quota and usage for a cache_salt."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.quota._helpers import (
+    escape_salt,
+    http_request,
+    normalize_url,
+)
+
+
+class GetCommand(BaseCommand):
+    """Show the quota and current usage for a cache_salt."""
+
+    def name(self) -> str:
+        return "get"
+
+    def help(self) -> str:
+        return "Show the quota and current usage for a cache_salt."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "salt",
+            type=str,
+            help=(
+                "The cache_salt identifier. Use '_default' for anonymous "
+                "(un-salted) traffic."
+            ),
+        )
+        parser.add_argument(
+            "--url",
+            type=str,
+            default="http://localhost:8080",
+            help="LMCache HTTP server URL (default: http://localhost:8080).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url)
+        salt = escape_salt(args.salt)
+
+        result = http_request("GET", f"{base_url}/quota/{salt}")
+
+        metrics = self.create_metrics("Quota Info", args)
+        metrics.add("cache_salt", "Cache salt", result.get("cache_salt", salt))
+        metrics.add("limit_gb", "Limit (GB)", result.get("limit_gb"))
+        metrics.add(
+            "current_usage_gb", "Current usage (GB)", result.get("current_usage_gb")
+        )
+        metrics.add("exists", "Exists", result.get("exists"))
+        metrics.emit()
diff --git a/lmcache/cli/commands/quota/list_command.py b/lmcache/cli/commands/quota/list_command.py
new file mode 100644
index 0000000..2bd798a
--- /dev/null
+++ b/lmcache/cli/commands/quota/list_command.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache quota list`` — list all registered quotas and their usage."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.quota._helpers import http_request, normalize_url
+
+
+class ListCommand(BaseCommand):
+    """List all registered quotas and their usage."""
+
+    def name(self) -> str:
+        return "list"
+
+    def help(self) -> str:
+        return "List all registered quotas and their usage."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--url",
+            type=str,
+            default="http://localhost:8080",
+            help="LMCache HTTP server URL (default: http://localhost:8080).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url)
+
+        result = http_request("GET", f"{base_url}/quota")
+        users = result.get("users", {})
+
+        metrics = self.create_metrics("Quota List", args, width=55)
+
+        if not users:
+            metrics.add("info", "Info", "No quotas configured")
+            metrics.emit()
+            return
+
+        for idx, (salt, info) in enumerate(users.items()):
+            section_key = f"quota_{idx}"
+            metrics.add_list_section("quotas", section_key, f"Salt: {salt}")
+            sec = metrics[section_key]
+            sec.add("cache_salt", "Cache salt", salt)
+            sec.add("limit_gb", "Limit (GB)", info.get("limit_gb"))
+            sec.add(
+                "current_usage_gb", "Current usage (GB)", info.get("current_usage_gb")
+            )
+
+        metrics.emit()
diff --git a/lmcache/cli/commands/quota/set_command.py b/lmcache/cli/commands/quota/set_command.py
new file mode 100644
index 0000000..568362e
--- /dev/null
+++ b/lmcache/cli/commands/quota/set_command.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache quota set`` — create or update a quota for a cache_salt."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.commands.quota._helpers import (
+    escape_salt,
+    http_request,
+    normalize_url,
+)
+
+
+class SetCommand(BaseCommand):
+    """Create or update a quota for a cache_salt."""
+
+    def name(self) -> str:
+        return "set"
+
+    def help(self) -> str:
+        return "Create or update a quota for a cache_salt."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "salt",
+            type=str,
+            help=(
+                "The cache_salt identifier. Use '_default' for anonymous "
+                "(un-salted) traffic."
+            ),
+        )
+        parser.add_argument(
+            "--limit-gb",
+            type=float,
+            required=True,
+            metavar="GB",
+            help="Quota limit in gigabytes (non-negative).",
+        )
+        parser.add_argument(
+            "--url",
+            type=str,
+            default="http://localhost:8080",
+            help="LMCache HTTP server URL (default: http://localhost:8080).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        base_url = normalize_url(args.url)
+        salt = escape_salt(args.salt)
+        limit_gb = args.limit_gb
+
+        result = http_request(
+            "PUT",
+            f"{base_url}/quota/{salt}",
+            data={"limit_gb": limit_gb},
+        )
+
+        metrics = self.create_metrics("Quota Set", args)
+        metrics.add("cache_salt", "Cache salt", result.get("cache_salt", salt))
+        metrics.add("limit_gb", "Limit (GB)", result.get("limit_gb", limit_gb))
+        metrics.add("status", "Status", result.get("status", "ok"))
+        metrics.emit()
diff --git a/lmcache/cli/commands/server.py b/lmcache/cli/commands/server.py
new file mode 100644
index 0000000..af445d9
--- /dev/null
+++ b/lmcache/cli/commands/server.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache server`` — launch the LMCache server (ZMQ + HTTP)."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class ServerCommand(BaseCommand):
+    """CLI command that launches the LMCache server (ZMQ + HTTP)."""
+
+    def name(self) -> str:
+        """Return the subcommand name.
+
+        Returns:
+            The string ``"server"``.
+        """
+        return "server"
+
+    def help(self) -> str:
+        """Return short help text.
+
+        Returns:
+            Help string shown by ``lmcache -h``.
+        """
+        return "Launch the LMCache server (ZMQ + HTTP)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add server-specific arguments to the parser.
+
+        Composes argument groups from the multiprocess, storage manager,
+        HTTP frontend, Prometheus, and telemetry config modules.
+        Silently skips argument registration when server dependencies
+        (e.g. CUDA extensions) are not installed; ``execute`` will then
+        print an actionable error.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+        try:
+            # First Party
+            from lmcache.v1.distributed.config import add_storage_manager_args
+            from lmcache.v1.mp_observability.config import add_observability_args
+            from lmcache.v1.multiprocess.config import (
+                add_coordinator_args,
+                add_http_frontend_args,
+                add_mp_server_args,
+                add_p2p_args,
+            )
+
+            add_mp_server_args(parser)
+            add_p2p_args(parser)
+            add_storage_manager_args(parser)
+            add_http_frontend_args(parser)
+            add_observability_args(parser)
+            add_coordinator_args(parser)
+        except ImportError as e:
+            logger.warning(
+                "lmcache-cli (lightweight) detected (%s); install the full "
+                "lmcache package to use 'server' and 'bench'.",
+                e,
+            )
+            return
+
+    def execute(self, args: argparse.Namespace) -> None:
+        """Parse CLI arguments into config objects and launch the HTTP server.
+
+        Args:
+            args: Parsed CLI arguments.
+
+        Raises:
+            SystemExit: When server dependencies are not installed.
+        """
+        # Standard
+        import sys
+
+        try:
+            # First Party
+            from lmcache.v1.distributed.config import parse_args_to_config
+            from lmcache.v1.mp_observability.config import (
+                parse_args_to_observability_config,
+            )
+            from lmcache.v1.multiprocess.config import (
+                parse_args_to_coordinator_config,
+                parse_args_to_http_frontend_config,
+                parse_args_to_mp_server_config,
+            )
+            from lmcache.v1.multiprocess.http_server import run_http_server
+        except ImportError:
+            print(
+                "The 'lmcache server' command requires the full lmcache "
+                "installation with CUDA extensions.\n"
+                "Install with: pip install lmcache",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        run_http_server(
+            http_config=parse_args_to_http_frontend_config(args),
+            mp_config=parse_args_to_mp_server_config(args),
+            storage_manager_config=parse_args_to_config(args),
+            obs_config=parse_args_to_observability_config(args),
+            coordinator_config=parse_args_to_coordinator_config(args),
+        )
diff --git a/lmcache/cli/commands/tool/__init__.py b/lmcache/cli/commands/tool/__init__.py
new file mode 100644
index 0000000..4f63422
--- /dev/null
+++ b/lmcache/cli/commands/tool/__init__.py
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool`` command — offline analysis utilities.
+
+Sub-subcommands are auto-discovered from modules in this package.
+To add a new tool, create a module defining a concrete
+:class:`BaseCommand` subclass — no edits to this file are required.
+"""
+
+# First Party
+from lmcache.cli.commands.base import CompositeCommand
+
+
+class ToolCommand(CompositeCommand):
+    """CLI command for offline analysis tools bundled with LMCache."""
+
+    def name(self) -> str:
+        return "tool"
+
+    def help(self) -> str:
+        return "Run offline analysis tools."
diff --git a/lmcache/cli/commands/tool/cache_simulator/__init__.py b/lmcache/cli/commands/tool/cache_simulator/__init__.py
new file mode 100644
index 0000000..1f07b4a
--- /dev/null
+++ b/lmcache/cli/commands/tool/cache_simulator/__init__.py
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool cache-simulator`` command group.
+
+Sub-subcommands (simulate, sweep, gen-dataset) are auto-discovered from
+modules in this package.  To add a new action, create a module defining
+a concrete :class:`BaseCommand` subclass — no edits to this file are
+required.
+"""
+
+# First Party
+from lmcache.cli.commands.base import CompositeCommand
+
+
+class CacheSimulatorCommand(CompositeCommand):
+    """Simulate KV-cache token hit rate from lookup-hash JSONL logs."""
+
+    def name(self) -> str:
+        return "cache-simulator"
+
+    def help(self) -> str:
+        return "Simulate KV-cache token hit rate from lookup-hash JSONL logs."
diff --git a/lmcache/cli/commands/tool/cache_simulator/gen_dataset_command.py b/lmcache/cli/commands/tool/cache_simulator/gen_dataset_command.py
new file mode 100644
index 0000000..720f9bb
--- /dev/null
+++ b/lmcache/cli/commands/tool/cache_simulator/gen_dataset_command.py
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool cache-simulator gen-dataset`` subcommand."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class GenDatasetCommand(BaseCommand):
+    """
+    Generate a vllm bench serve custom dataset (JSONL)
+    from lookup-hash JSONL logs.
+    """
+
+    def name(self) -> str:
+        return "gen-dataset"
+
+    def help(self) -> str:
+        return (
+            "Generate a vllm bench serve custom dataset (JSONL) from "
+            "lookup-hash JSONL logs, preserving prefix-sharing structure."
+        )
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # First Party
+        from lmcache.tools.cache_simulator.gen_bench_dataset import (
+            add_gen_dataset_arguments,
+        )
+
+        add_gen_dataset_arguments(parser)
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        # Skip _add_output_args — this command defines its own --output.
+        # Gracefully skip if optional dependencies are missing.
+        try:
+            parser = subparsers.add_parser(self.name(), help=self.help())
+            self.add_arguments(parser)
+            parser.set_defaults(func=self.execute)
+        except ImportError:
+            return
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.tools.cache_simulator.gen_bench_dataset import run_gen_dataset
+
+        run_gen_dataset(args)
diff --git a/lmcache/cli/commands/tool/cache_simulator/simulate_command.py b/lmcache/cli/commands/tool/cache_simulator/simulate_command.py
new file mode 100644
index 0000000..ca8d490
--- /dev/null
+++ b/lmcache/cli/commands/tool/cache_simulator/simulate_command.py
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool cache-simulator simulate`` subcommand."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class SimulateCommand(BaseCommand):
+    """
+    Replay logs at a fixed cache capacity; print a text report and s
+    ave a 7-panel statistics PNG.
+    """
+
+    def name(self) -> str:
+        return "simulate"
+
+    def help(self) -> str:
+        return (
+            "Replay logs at a fixed cache capacity; print a text report "
+            "and save a 7-panel statistics PNG."
+        )
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # First Party
+        from lmcache.tools.cache_simulator.simulator import add_simulate_arguments
+
+        add_simulate_arguments(parser)
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        # Skip _add_output_args — this command defines its own --output.
+        # Gracefully skip if optional dependencies are missing.
+        try:
+            parser = subparsers.add_parser(self.name(), help=self.help())
+            self.add_arguments(parser)
+            parser.set_defaults(func=self.execute)
+        except ImportError:
+            return
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.tools.cache_simulator.simulator import run_simulate
+
+        run_simulate(args)
diff --git a/lmcache/cli/commands/tool/cache_simulator/sweep_command.py b/lmcache/cli/commands/tool/cache_simulator/sweep_command.py
new file mode 100644
index 0000000..af49795
--- /dev/null
+++ b/lmcache/cli/commands/tool/cache_simulator/sweep_command.py
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool cache-simulator sweep`` subcommand."""
+
+# Standard
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class SweepCommand(BaseCommand):
+    """
+    Sweep across a range of cache capacities and save a hit-rate vs capacity PNG.
+    """
+
+    def name(self) -> str:
+        return "sweep"
+
+    def help(self) -> str:
+        return (
+            "Sweep across a range of cache capacities and save a "
+            "hit-rate vs capacity PNG."
+        )
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        # First Party
+        from lmcache.tools.cache_simulator.plot_hit_rate import add_sweep_arguments
+
+        add_sweep_arguments(parser)
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        # Skip _add_output_args — this command defines its own --output.
+        # Gracefully skip if optional dependencies are missing.
+        try:
+            parser = subparsers.add_parser(self.name(), help=self.help())
+            self.add_arguments(parser)
+            parser.set_defaults(func=self.execute)
+        except ImportError:
+            return
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.tools.cache_simulator.plot_hit_rate import run_sweep
+
+        run_sweep(args)
diff --git a/lmcache/cli/commands/tool/transfer_channel_benchmark.py b/lmcache/cli/commands/tool/transfer_channel_benchmark.py
new file mode 100644
index 0000000..52a9a33
--- /dev/null
+++ b/lmcache/cli/commands/tool/transfer_channel_benchmark.py
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache tool transfer-channel-benchmark`` — transfer channel throughput benchmark.
+
+Exposes :class:`TransferChannelBenchmarkCommand` for auto-discovery by
+:class:`~lmcache.cli.commands.base.CompositeCommand`.
+
+Argument definitions and execution logic live in the benchmark module:
+
+* :func:`~lmcache.tools.transfer_channel_benchmark.config.add_benchmark_arguments`
+* :func:`~lmcache.tools.transfer_channel_benchmark.benchmark.run_benchmark`
+"""
+
+# Standard
+import argparse
+import sys
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class TransferChannelBenchmarkCommand(BaseCommand):
+    """Benchmark transfer channel read throughput (server/client)."""
+
+    def name(self) -> str:
+        return "transfer-channel-benchmark"
+
+    def help(self) -> str:
+        return "Benchmark transfer channel read throughput (server/client)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        """Add benchmark-specific arguments.
+
+        Only the torch-free ``config`` module is imported here, so registering
+        this tool does not require torch or the distributed runtime.
+
+        Args:
+            parser: The ``ArgumentParser`` for this subcommand.
+        """
+        # First Party
+        from lmcache.tools.transfer_channel_benchmark.config import (
+            add_benchmark_arguments,
+        )
+
+        add_benchmark_arguments(parser)
+
+    def register(self, subparsers: argparse._SubParsersAction) -> None:
+        """Register without the common output args (--format/--output/--quiet).
+
+        The benchmark manages its own output lifecycle and does not use the
+        generic metrics output flags.
+        """
+        parser = subparsers.add_parser(
+            self.name(),
+            help=self.help(),
+            description=(
+                "Throughput benchmark for the LMCache transfer channel. Run one "
+                "process with --role server and another with --role client."
+            ),
+            formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        )
+        self.add_arguments(parser)
+        parser.set_defaults(func=self.execute)
+
+    def execute(self, args: argparse.Namespace) -> None:
+        """Run the benchmark and exit non-zero on failure.
+
+        Args:
+            args: Parsed CLI arguments.
+        """
+        # First Party
+        from lmcache.tools.transfer_channel_benchmark.benchmark import (
+            run_benchmark,
+        )
+
+        if not run_benchmark(args):
+            sys.exit(1)
diff --git a/lmcache/cli/commands/trace/__init__.py b/lmcache/cli/commands/trace/__init__.py
new file mode 100644
index 0000000..b04651e
--- /dev/null
+++ b/lmcache/cli/commands/trace/__init__.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache trace`` command — inspect and replay storage-level trace files.
+
+Sub-subcommands are auto-discovered from modules in this package.
+To add a new subcommand, create a module defining a concrete
+:class:`BaseCommand` subclass — no edits to this file are required.
+
+Trace *capture* is not a ``trace`` subcommand — recording is bound to
+the live process via ``lmcache server --trace-level storage
+[--trace-output ...]``.
+"""
+
+# First Party
+from lmcache.cli.commands.base import CompositeCommand
+
+
+class TraceCommand(CompositeCommand):
+    """Subcommand group for trace inspection and replay."""
+
+    def name(self) -> str:
+        return "trace"
+
+    def help(self) -> str:
+        return "Inspect and replay LMCache storage-level trace files."
diff --git a/lmcache/cli/commands/trace/_dispatch.py b/lmcache/cli/commands/trace/_dispatch.py
new file mode 100644
index 0000000..06951c9
--- /dev/null
+++ b/lmcache/cli/commands/trace/_dispatch.py
@@ -0,0 +1,249 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Dispatcher mapping recorded ``qualname`` strings to live callables.
+
+The recorder writes one :class:`~lmcache.v1.mp_observability.trace.format.Record`
+per decorated call, tagged by the function's fully-qualified name.
+The dispatcher translates those strings back into concrete calls on a
+live :class:`~lmcache.v1.distributed.storage_manager.StorageManager`.
+
+Adding support for a new traced operation is a two-line change: put
+``@enable_tracing`` on the function, then register a handler here with
+a matching ``qualname``.  No per-op schemas, no new event types.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import deque
+from contextlib import AbstractContextManager
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+logger = init_logger(__name__)
+
+#: Fully-qualified name of the ``StorageManager`` class.  Used to
+#: build the qualnames of all its traced methods.  Kept as a constant
+#: so tests and dispatcher registrations stay in lock-step if the class
+#: is ever renamed or moved.
+_SM_PREFIX = "lmcache.v1.distributed.storage_manager.StorageManager"
+
+
+@dataclass
+class ReplayContext:
+    """State carried across dispatcher invocations during one replay.
+
+    The driver creates exactly one ``ReplayContext`` per trace file,
+    hands it to every dispatched handler, and closes the StorageManager
+    when replay finishes.
+
+    Attributes:
+        sm: The live StorageManager that receives replayed calls.
+        open_read_contexts: FIFO queue of
+            ``read_prefetched_results`` contexts entered but not yet
+            exited.  Matching ``__enter__``/``__exit__`` records are
+            popped in the order they were entered for the same
+            ``keys`` tuple.  A dict-of-deques keyed on
+            ``tuple(keys)`` supports interleaved contexts across
+            different key sets.
+    """
+
+    sm: StorageManager
+    open_read_contexts: dict[tuple[ObjectKey, ...], deque[AbstractContextManager]] = (
+        field(default_factory=dict)
+    )
+
+
+#: Type of a dispatcher handler: takes a :class:`ReplayContext` and an
+#: already-decoded ``args`` dict (keys = parameter names, values =
+#: native Python values restored by
+#: :mod:`lmcache.v1.mp_observability.trace.codecs`).  Handlers return
+#: nothing; any return value from the live call is discarded.
+Handler = Callable[[ReplayContext, dict[str, Any]], None]
+
+
+class CallDispatcher:
+    """Registry mapping recorded qualnames to replay handlers.
+
+    Handlers are plain callables — no per-op subclass hierarchy.  The
+    default factory :func:`build_default_dispatcher` populates the
+    registry with every v1 ``StorageManager`` operation.
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, Handler] = {}
+
+    def register(self, qualname: str, handler: Handler) -> None:
+        """Register a handler for *qualname*.
+
+        Args:
+            qualname: Fully-qualified call-site name exactly matching
+                the ``qualname`` field written by the recorder.
+            handler: Callable invoked on each matching record.
+
+        Raises:
+            ValueError: If a handler is already registered for
+                *qualname*.
+        """
+        if qualname in self._handlers:
+            raise ValueError(f"handler already registered for {qualname!r}")
+        self._handlers[qualname] = handler
+
+    def has(self, qualname: str) -> bool:
+        """Return ``True`` if a handler is registered for *qualname*."""
+        return qualname in self._handlers
+
+    def registered_qualnames(self) -> list[str]:
+        """Return the list of currently registered qualnames.
+
+        Returns:
+            A new list of qualname strings, suitable for inspection or
+            assertion in tests.
+        """
+        return list(self._handlers)
+
+    def dispatch(
+        self,
+        qualname: str,
+        context: ReplayContext,
+        args: dict[str, Any],
+    ) -> None:
+        """Invoke the handler for *qualname*.
+
+        Args:
+            qualname: The recorded qualname.
+            context: Replay context passed through to the handler.
+            args: Decoded argument dict for the call.
+
+        Raises:
+            KeyError: If no handler is registered for *qualname*.  The
+                driver catches this and logs a warning so unknown
+                qualnames (e.g. from a future trace level) do not stop
+                replay.
+        """
+        handler = self._handlers.get(qualname)
+        if handler is None:
+            raise KeyError(qualname)
+        handler(context, args)
+
+
+# ---------------------------------------------------------------------------
+# Default handlers for v1 StorageManager operations
+# ---------------------------------------------------------------------------
+
+
+def _call_sm_method(method_name: str) -> Handler:
+    """Build a handler that forwards a record to ``sm.<method_name>``.
+
+    The returned callable invokes ``getattr(ctx.sm, method_name)(**args)``
+    and discards the result.  Used for every "plain" traced method on
+    StorageManager — ``reserve_write``, ``finish_write``,
+    ``submit_prefetch_task``, ``finish_read_prefetched``.
+
+    Args:
+        method_name: Attribute name on the live StorageManager.
+
+    Returns:
+        A :data:`Handler` closure.
+    """
+
+    def _handler(ctx: ReplayContext, args: dict[str, Any]) -> None:
+        method = getattr(ctx.sm, method_name)
+        method(**args)
+
+    _handler.__name__ = f"_call_sm_{method_name}"
+    return _handler
+
+
+def _enter_read_prefetched(ctx: ReplayContext, args: dict[str, Any]) -> None:
+    """Handle a ``read_prefetched_results.__enter__`` record.
+
+    Enters the live context manager and stashes it under
+    ``tuple(keys)``.  The matching ``__exit__`` handler pops the top
+    entry for that key tuple, preserving FIFO order when multiple
+    contexts are simultaneously open for identical key lists.
+
+    Args:
+        ctx: Active replay context.
+        args: Decoded record arguments.  Must contain ``"keys"``.
+    """
+    keys = args["keys"]
+    cm = ctx.sm.read_prefetched_results(keys)
+    cm.__enter__()
+    key_tuple = tuple(keys)
+    ctx.open_read_contexts.setdefault(key_tuple, deque()).append(cm)
+
+
+def _exit_read_prefetched(ctx: ReplayContext, args: dict[str, Any]) -> None:
+    """Handle a ``read_prefetched_results.__exit__`` record.
+
+    Pops and exits the oldest context opened for ``tuple(keys)``.  If
+    no matching open context exists — typically because the trace was
+    truncated between the enter and exit events — logs a warning and
+    continues so replay does not abort.
+
+    Args:
+        ctx: Active replay context.
+        args: Decoded record arguments.  Must contain ``"keys"``.
+    """
+    keys = args["keys"]
+    key_tuple = tuple(keys)
+    pending = ctx.open_read_contexts.get(key_tuple)
+    if not pending:
+        logger.warning(
+            "trace replay: read_prefetched_results.__exit__ with no "
+            "matching __enter__ (keys=%d); ignoring",
+            len(keys),
+        )
+        return
+    cm = pending.popleft()
+    if not pending:
+        del ctx.open_read_contexts[key_tuple]
+    # Pass a clean exit — replay does not reproduce caller-side
+    # exceptions.  The context manager's ``finally`` block runs
+    # regardless, so read locks are released.
+    cm.__exit__(None, None, None)
+
+
+def build_default_dispatcher() -> CallDispatcher:
+    """Return a :class:`CallDispatcher` populated with v1 handlers.
+
+    Covers every qualname the storage-level recorder emits:
+
+    * ``StorageManager.reserve_write``
+    * ``StorageManager.finish_write``
+    * ``StorageManager.submit_prefetch_task``
+    * ``StorageManager.finish_read_prefetched``
+    * ``StorageManager.read_prefetched_results.__enter__``
+    * ``StorageManager.read_prefetched_results.__exit__``
+
+    Returns:
+        A ready-to-use dispatcher.  Callers may further register
+        additional handlers on it for future trace levels.
+    """
+    dispatcher = CallDispatcher()
+    for method_name in (
+        "reserve_write",
+        "finish_write",
+        "submit_prefetch_task",
+        "finish_read_prefetched",
+    ):
+        dispatcher.register(
+            f"{_SM_PREFIX}.{method_name}",
+            _call_sm_method(method_name),
+        )
+    dispatcher.register(
+        f"{_SM_PREFIX}.read_prefetched_results.__enter__",
+        _enter_read_prefetched,
+    )
+    dispatcher.register(
+        f"{_SM_PREFIX}.read_prefetched_results.__exit__",
+        _exit_read_prefetched,
+    )
+    return dispatcher
diff --git a/lmcache/cli/commands/trace/_driver.py b/lmcache/cli/commands/trace/_driver.py
new file mode 100644
index 0000000..ba35e78
--- /dev/null
+++ b/lmcache/cli/commands/trace/_driver.py
@@ -0,0 +1,372 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""High-level replay driver for storage-level traces.
+
+Usage::
+
+    driver = StorageReplayDriver(sm_config, trace_path)
+    result = driver.run()
+    driver.close()
+
+The driver:
+
+1. Opens the trace file via :class:`TraceReader`.
+2. Constructs a fresh :class:`StorageManager` from the supplied
+   :class:`StorageManagerConfig`.  Notably, the replay-side config is
+   chosen by the *caller*, not copied from the trace's header.  This
+   lets the same trace exercise different L1/L2 configurations —
+   e.g., record with a Redis L2 adapter and replay with a
+   local-filesystem adapter.
+3. Iterates records, decodes their argument dicts via the trace
+   codec registry, and dispatches each to a live StorageManager call
+   through a :class:`CallDispatcher`.  Each dispatch is aligned to
+   the recorded ``t_mono`` offset via ``time.sleep`` — the replay
+   never runs ahead of the recording.  Dispatching as-fast-as-
+   possible is unsafe because reads and writes are async in
+   ``StorageManager`` and carry cross-call dependencies; collapsing
+   the recorded gaps races the async queues.
+4. Records per-qualname timings into a :class:`ReplayStatsCollector`.
+
+Replay is deliberately single-threaded: the recorder captures calls
+in the order the EventBus drained them, which is already a
+linearization of the concurrent production calls.  Replaying
+in that same order preserves the observed interleaving without
+needing to reconstruct thread identities.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable
+import hashlib
+import json
+import time
+
+# First Party
+from lmcache.cli.commands.trace._dispatch import (
+    CallDispatcher,
+    ReplayContext,
+    build_default_dispatcher,
+)
+from lmcache.cli.commands.trace._stats import ReplayStatsCollector
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.config import StorageManagerConfig
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.mp_observability.config import (
+    ObservabilityConfig,
+    init_observability,
+)
+from lmcache.v1.mp_observability.trace import codecs
+from lmcache.v1.mp_observability.trace.reader import TraceReader
+from lmcache.v1.mp_observability.trace.recorder import safe_storage_config_dict
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.mp_observability.event_bus import EventBus
+
+logger = init_logger(__name__)
+
+#: Default :class:`ObservabilityConfig` for replay sessions.
+#:
+#: Enables the EventBus and its logging subscribers so users can see
+#: SM/L1/L2 log output during replay.  Metrics and tracing are off:
+#: the OTel / Prometheus pipelines bind a port, which would collide
+#: across concurrent replays.  Declared at module scope to avoid
+#: Ruff B008 (mutable default argument).
+DEFAULT_REPLAY_OBS_CONFIG: ObservabilityConfig = ObservabilityConfig(
+    enabled=True,
+    metrics_enabled=False,
+    logging_enabled=True,
+    tracing_enabled=False,
+)
+
+
+@dataclass
+class ReplayResult:
+    """Summary returned from :meth:`StorageReplayDriver.run`.
+
+    Attributes:
+        records_replayed: Successful dispatches.
+        records_skipped: Records with no registered handler (likely
+            from a newer trace level).
+        records_failed: Records whose handler raised.
+        stats: The per-qualname timing collector.  Exposed so the
+            caller can export CSV/JSON or inspect individual
+            percentiles.
+        header_level: ``level`` field read from the trace header.
+        header_digest: ``sm_config_digest`` from the trace header.
+        replay_config_digest: SHA-256 of the replay-side
+            StorageManagerConfig, for mismatch comparisons.  Empty
+            string if the driver could not compute it.
+    """
+
+    records_replayed: int
+    records_skipped: int
+    records_failed: int
+    stats: ReplayStatsCollector
+    header_level: str
+    header_digest: str
+    replay_config_digest: str
+
+
+class StorageReplayDriver:
+    """Replays a storage-level trace against a live StorageManager.
+
+    The driver owns the StorageManager for its lifetime; call
+    :meth:`close` (or use as a context manager) to shut it down.
+    """
+
+    def __init__(
+        self,
+        sm_config: StorageManagerConfig,
+        trace_path: str,
+        dispatcher: CallDispatcher | None = None,
+        obs_config: ObservabilityConfig = DEFAULT_REPLAY_OBS_CONFIG,
+    ) -> None:
+        """Construct a driver.
+
+        Initializes the global observability EventBus **before**
+        constructing the StorageManager so internal events
+        (L0/L1/L2 lifecycle, eviction, etc.) flow through a live bus
+        during replay.  This lets the same logging and monitoring
+        subscribers that run in the real server attach to the replay
+        session — e.g. operators can eyeball L1/L2 log output to
+        spot eviction churn or L2 bottlenecks.
+
+        Metrics (OTel / Prometheus) are **off by default** because
+        the metrics pipeline binds a Prometheus port; running two
+        replays concurrently with the same port would fail.  Callers
+        who want metrics can pass their own ``obs_config``.
+
+        Args:
+            sm_config: Replay-side StorageManager configuration.
+                Determines L1 size, eviction policy, and L2 adapters
+                used during replay.  Typically different from the
+                recording-side config (the original deployment may
+                have used adapters unavailable on the replay host).
+            trace_path: Path to a ``.lct`` trace file written by
+                :class:`StorageTraceRecorder`.
+            dispatcher: Custom dispatcher.  When omitted, a fresh
+                :func:`build_default_dispatcher` is used; passing one
+                explicitly is useful for tests that register extra
+                handlers.
+            obs_config: Observability configuration for the replay
+                session.  Defaults to an enabled bus with logging
+                subscribers and no metrics/tracing.  The driver
+                installs this config as the global singleton via
+                :func:`init_observability` and stops the resulting
+                bus on :meth:`close`.
+        """
+        self._sm_config = sm_config
+        self._trace_path = trace_path
+        self._dispatcher = dispatcher or build_default_dispatcher()
+        self._closed = False
+
+        # Each resource is acquired under its own try/except so that a
+        # failure partway through __init__ still releases what has
+        # already been opened.  Without this, ``__exit__`` / ``close``
+        # never runs (the caller never got a valid instance), and the
+        # reader / bus would leak — see Cursor bugbot comment on
+        # PR #3075.
+        reader: TraceReader | None = None
+        bus: EventBus | None = None
+        try:
+            reader = TraceReader(trace_path)
+            bus = init_observability(obs_config)
+            self._sm = StorageManager(sm_config)
+        except BaseException:
+            # ``BaseException`` to also cover KeyboardInterrupt /
+            # SystemExit raised from inside StorageManager setup —
+            # the resources below must still be released.
+            if bus is not None:
+                try:
+                    bus.stop()
+                except Exception:
+                    logger.warning(
+                        "trace replay: error stopping bus during failed driver init",
+                        exc_info=True,
+                    )
+            if reader is not None:
+                try:
+                    reader.close()
+                except Exception:
+                    logger.warning(
+                        "trace replay: error closing reader during failed driver init",
+                        exc_info=True,
+                    )
+            raise
+
+        self._reader = reader
+        self._bus = bus
+
+    def __enter__(self) -> StorageReplayDriver:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+
+    @property
+    def trace_path(self) -> str:
+        """Path of the trace file being replayed."""
+        return self._trace_path
+
+    @property
+    def storage_manager(self) -> StorageManager:
+        """The live StorageManager driving replay.
+
+        Exposed primarily for tests that need to introspect residency
+        or eviction state after ``run()`` returns.
+        """
+        return self._sm
+
+    def close(self) -> None:
+        """Close the StorageManager, stop the bus, and close the reader.
+
+        Idempotent.  The order matters: the StorageManager may
+        publish teardown events, so the bus outlives it briefly.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._sm.close()
+        finally:
+            try:
+                self._bus.stop()
+            finally:
+                self._reader.close()
+
+    # ------------------------------------------------------------------
+
+    def run(
+        self,
+        on_record: RecordCallback | None = None,
+    ) -> ReplayResult:
+        """Replay every record in the trace.
+
+        Dispatch is always paced to the recorded ``t_mono`` offsets
+        via ``time.sleep``: the replay never runs *ahead* of the
+        recording.  Running ahead is unsafe because ``StorageManager``
+        reads and writes are async — collapsing the recorded gaps
+        races the async queues and leads to retrieve misses.  If the
+        replay host is slower than recording, the loop simply lags
+        the recorded schedule.
+
+        Args:
+            on_record: Optional per-record callback invoked after
+                dispatch with ``(qualname, latency_s, failed)``.
+                Used by the CLI's ``--jsonl-out`` feature.
+
+        Returns:
+            A :class:`ReplayResult` summarizing the run.
+        """
+        stats = ReplayStatsCollector()
+        context = ReplayContext(sm=self._sm)
+        header = self._reader.header
+        t_start = time.time()
+        stats.mark_start(t_start)
+
+        replayed = skipped = failed = 0
+        t_wall_origin = time.monotonic()
+
+        for record in self._reader.records():
+            # Sleep just long enough to align to the recorded
+            # offset from the start of replay.  No speedup — if
+            # the replay machine is slower than recording, the
+            # loop simply runs behind.
+            target = t_wall_origin + record.t_mono
+            now = time.monotonic()
+            if now < target:
+                time.sleep(target - now)
+
+            try:
+                decoded_args = codecs.decode_args(record.args)
+            except Exception:
+                skipped += 1
+                logger.warning(
+                    "trace replay: failed to decode args for %s; skipping",
+                    record.qualname,
+                    exc_info=True,
+                )
+                if on_record is not None:
+                    on_record(record.qualname, 0.0, True)
+                continue
+
+            if not self._dispatcher.has(record.qualname):
+                skipped += 1
+                logger.warning(
+                    "trace replay: no handler for qualname %r; skipping",
+                    record.qualname,
+                )
+                if on_record is not None:
+                    on_record(record.qualname, 0.0, True)
+                continue
+
+            t0 = time.monotonic()
+            try:
+                self._dispatcher.dispatch(record.qualname, context, decoded_args)
+                latency = time.monotonic() - t0
+                stats.record(record.qualname, latency, failed=False)
+                replayed += 1
+                if on_record is not None:
+                    on_record(record.qualname, latency, False)
+            except Exception:
+                latency = time.monotonic() - t0
+                stats.record(record.qualname, latency, failed=True)
+                failed += 1
+                logger.warning(
+                    "trace replay: handler for %s raised",
+                    record.qualname,
+                    exc_info=True,
+                )
+                if on_record is not None:
+                    on_record(record.qualname, latency, True)
+
+        # Close any contexts the trace left open (truncated trace,
+        # or missing __exit__ records).  Releasing these keeps the
+        # StorageManager in a consistent state for a follow-up run
+        # or inspection.
+        for key_tuple, pending in list(context.open_read_contexts.items()):
+            while pending:
+                cm = pending.popleft()
+                try:
+                    cm.__exit__(None, None, None)
+                except Exception:
+                    logger.warning(
+                        "trace replay: forced exit of dangling "
+                        "read_prefetched_results raised (keys=%d)",
+                        len(key_tuple),
+                        exc_info=True,
+                    )
+            context.open_read_contexts.pop(key_tuple, None)
+
+        stats.mark_end(time.time())
+
+        # Digest of the replay-side config so callers can compare
+        # against ``header.sm_config_digest``.  Same hashing used by
+        # the recorder — see :func:`safe_storage_config_dict`.
+        safe = safe_storage_config_dict(self._sm_config)
+        replay_digest = hashlib.sha256(
+            json.dumps(safe, sort_keys=True).encode("utf-8")
+        ).hexdigest()
+
+        return ReplayResult(
+            records_replayed=replayed,
+            records_skipped=skipped,
+            records_failed=failed,
+            stats=stats,
+            header_level=header.level,
+            header_digest=header.sm_config_digest,
+            replay_config_digest=replay_digest,
+        )
+
+
+#: Callback signature for per-record hooks during replay.  Arguments
+#: are ``(qualname, latency_seconds, failed)``.  Declared at module
+#: scope so callers can type-annotate their hooks without importing
+#: the driver class.
+RecordCallback = Callable[[str, float, bool], None]
diff --git a/lmcache/cli/commands/trace/_stats.py b/lmcache/cli/commands/trace/_stats.py
new file mode 100644
index 0000000..e6151da
--- /dev/null
+++ b/lmcache/cli/commands/trace/_stats.py
@@ -0,0 +1,289 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Per-qualname latency statistics for trace replay.
+
+The replay driver times every dispatched call.  Timings feed into this
+collector, which computes count + mean + percentiles (p50, p90, p99)
+per qualname.
+
+The shape is deliberately simpler than
+:class:`lmcache.cli.commands.bench.engine_bench.stats.StatsCollector`
+— that one is tailored to OpenAI-style streaming inference (TTFT,
+decode speed, etc.), which is not applicable to in-process storage
+replay.  Sharing the computation code between the two would push a
+small helper deep into the bench module; keeping this collector local
+keeps the storage-replay code self-contained and easy to evolve.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+import csv
+import json
+import statistics
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class OpStats:
+    """Aggregate timing stats for one qualname.
+
+    Attributes:
+        qualname: The qualname these stats cover.
+        count: Number of successful replays for this qualname.
+        error_count: Number of replays that raised.
+        total_s: Total wall time spent replaying this qualname.
+        mean_ms: Mean per-call latency in milliseconds.
+        p50_ms: 50th-percentile latency in milliseconds.
+        p90_ms: 90th-percentile latency in milliseconds.
+        p99_ms: 99th-percentile latency in milliseconds.
+        min_ms: Minimum observed latency in milliseconds.
+        max_ms: Maximum observed latency in milliseconds.
+    """
+
+    qualname: str
+    count: int
+    error_count: int
+    total_s: float
+    mean_ms: float
+    p50_ms: float
+    p90_ms: float
+    p99_ms: float
+    min_ms: float
+    max_ms: float
+
+
+@dataclass
+class _Bucket:
+    """Internal per-qualname sample bucket."""
+
+    latencies_ms: list[float] = field(default_factory=list)
+    errors: int = 0
+
+
+def _percentile(sorted_values: list[float], pct: float) -> float:
+    """Return the *pct*-th percentile from an already-sorted list.
+
+    Uses nearest-rank with no interpolation: for N samples, the
+    p-th percentile is the sample at index ``ceil(p/100 * N) - 1``.
+    Returns 0.0 for empty input.
+
+    Args:
+        sorted_values: Ascending-sorted list of values.
+        pct: Percentile in ``[0, 100]``.
+
+    Returns:
+        The percentile value, or 0.0 for empty input.
+    """
+    if not sorted_values:
+        return 0.0
+    if pct <= 0:
+        return sorted_values[0]
+    if pct >= 100:
+        return sorted_values[-1]
+    # bisect_left gives the insertion index; the nearest-rank formula
+    # maps p to ceil(p/100 * N) which equals floor((p/100 * N - eps) + 1).
+    n = len(sorted_values)
+    idx = max(0, min(n - 1, int((pct / 100.0) * n)))
+    return sorted_values[idx]
+
+
+class ReplayStatsCollector:
+    """Thread-safe per-qualname latency collector.
+
+    The replay driver is single-threaded at the dispatcher boundary,
+    but the underlying StorageManager performs async work on helper
+    threads whose timings may eventually feed back here.  A lock keeps
+    concurrent ``record()`` calls safe.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._buckets: dict[str, _Bucket] = {}
+        self._wall_start_s: float | None = None
+        self._wall_end_s: float | None = None
+
+    def mark_start(self, wall_time_s: float) -> None:
+        """Record the wall-clock time when replay began.
+
+        Called once before the first ``record()``; replay-duration
+        metrics are derived from start/end marks.
+
+        Args:
+            wall_time_s: ``time.time()`` at replay start.
+        """
+        with self._lock:
+            self._wall_start_s = wall_time_s
+
+    def mark_end(self, wall_time_s: float) -> None:
+        """Record the wall-clock time when replay finished.
+
+        Args:
+            wall_time_s: ``time.time()`` at replay end.
+        """
+        with self._lock:
+            self._wall_end_s = wall_time_s
+
+    def record(self, qualname: str, latency_s: float, failed: bool = False) -> None:
+        """Record one replayed call.
+
+        Args:
+            qualname: Qualified name of the replayed function.
+            latency_s: Elapsed seconds for the call.
+            failed: ``True`` if the call raised.  Failed calls still
+                contribute to the count but do not add a latency
+                sample — the raising path's timing is not comparable
+                to successful calls.
+        """
+        with self._lock:
+            bucket = self._buckets.get(qualname)
+            if bucket is None:
+                bucket = _Bucket()
+                self._buckets[qualname] = bucket
+            if failed:
+                bucket.errors += 1
+                return
+            # Append is O(1); the one-shot sort in :meth:`summary` is
+            # O(N log N), which beats the O(N) shift from keeping the
+            # list sorted on insert.  For large traces (>1M records
+            # per qualname) the driver should sample or switch to an
+            # approximation; for now, exact percentiles suffice.
+            bucket.latencies_ms.append(latency_s * 1000.0)
+
+    def total_duration_s(self) -> float:
+        """Return replay wall-clock duration in seconds.
+
+        Returns:
+            ``mark_end - mark_start`` if both were set, else 0.0.
+        """
+        with self._lock:
+            if self._wall_start_s is None or self._wall_end_s is None:
+                return 0.0
+            return max(0.0, self._wall_end_s - self._wall_start_s)
+
+    def summary(self) -> dict[str, OpStats]:
+        """Return a per-qualname :class:`OpStats` snapshot.
+
+        Returns:
+            A dict keyed by qualname.  A qualname with only errors
+            still appears, with zero latency stats.
+        """
+        with self._lock:
+            result: dict[str, OpStats] = {}
+            for qualname, bucket in self._buckets.items():
+                # Sort once per summary call — ``record`` keeps the
+                # list unsorted (O(1) append) so the total work is
+                # O(N log N) per summary rather than O(N) per insert.
+                lats = sorted(bucket.latencies_ms)
+                if lats:
+                    mean = statistics.fmean(lats)
+                    total_s = sum(lats) / 1000.0
+                    p50 = _percentile(lats, 50)
+                    p90 = _percentile(lats, 90)
+                    p99 = _percentile(lats, 99)
+                    lo, hi = lats[0], lats[-1]
+                else:
+                    mean = total_s = p50 = p90 = p99 = lo = hi = 0.0
+                result[qualname] = OpStats(
+                    qualname=qualname,
+                    count=len(lats),
+                    error_count=bucket.errors,
+                    total_s=total_s,
+                    mean_ms=mean,
+                    p50_ms=p50,
+                    p90_ms=p90,
+                    p99_ms=p99,
+                    min_ms=lo,
+                    max_ms=hi,
+                )
+            return result
+
+    def export_csv(self, path: str) -> None:
+        """Write per-qualname stats to a CSV file.
+
+        Columns: ``qualname, count, errors, mean_ms, p50_ms, p90_ms,
+        p99_ms, min_ms, max_ms``.  One row per qualname.
+
+        Args:
+            path: File path to write.  Overwritten if it exists.
+        """
+        summary = self.summary()
+        with open(path, "w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(
+                [
+                    "qualname",
+                    "count",
+                    "errors",
+                    "mean_ms",
+                    "p50_ms",
+                    "p90_ms",
+                    "p99_ms",
+                    "min_ms",
+                    "max_ms",
+                ]
+            )
+            for qn in sorted(summary):
+                s = summary[qn]
+                w.writerow(
+                    [
+                        s.qualname,
+                        s.count,
+                        s.error_count,
+                        f"{s.mean_ms:.6f}",
+                        f"{s.p50_ms:.6f}",
+                        f"{s.p90_ms:.6f}",
+                        f"{s.p99_ms:.6f}",
+                        f"{s.min_ms:.6f}",
+                        f"{s.max_ms:.6f}",
+                    ]
+                )
+
+    def export_json(self, path: str) -> None:
+        """Write per-qualname stats + replay duration to a JSON file.
+
+        Schema::
+
+            {
+              "duration_s": <float>,
+              "ops": {
+                "<qualname>": {
+                  "count": int, "errors": int,
+                  "mean_ms": float, "p50_ms": float,
+                  "p90_ms": float, "p99_ms": float,
+                  "min_ms": float, "max_ms": float
+                },
+                ...
+              }
+            }
+
+        Args:
+            path: File path to write.  Overwritten if it exists.
+        """
+        summary = self.summary()
+        payload = {
+            "duration_s": self.total_duration_s(),
+            "ops": {
+                qn: {
+                    "count": s.count,
+                    "errors": s.error_count,
+                    "mean_ms": s.mean_ms,
+                    "p50_ms": s.p50_ms,
+                    "p90_ms": s.p90_ms,
+                    "p99_ms": s.p99_ms,
+                    "min_ms": s.min_ms,
+                    "max_ms": s.max_ms,
+                }
+                for qn, s in summary.items()
+            },
+        }
+        with open(path, "w") as f:
+            json.dump(payload, f, indent=2, sort_keys=True)
+            f.write("\n")
diff --git a/lmcache/cli/commands/trace/info_command.py b/lmcache/cli/commands/trace/info_command.py
new file mode 100644
index 0000000..8db6c73
--- /dev/null
+++ b/lmcache/cli/commands/trace/info_command.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache trace info`` — print a summary of a trace file."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import Counter
+import argparse
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+
+
+class InfoCommand(BaseCommand):
+    """Print a summary of a trace file."""
+
+    def name(self) -> str:
+        return "info"
+
+    def help(self) -> str:
+        return "Print a summary of a trace file."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "trace_path",
+            metavar="FILE",
+            help="Path to a .lct trace file.",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # First Party
+        from lmcache.v1.mp_observability.trace.reader import TraceReader
+
+        with TraceReader(args.trace_path) as r:
+            header = r.header
+            counts: Counter[str] = Counter()
+            max_mono = 0.0
+            for record in r.records():
+                counts[record.qualname] += 1
+                if record.t_mono > max_mono:
+                    max_mono = record.t_mono
+
+        print(f"Trace file: {args.trace_path}")
+        print(f"  level:                {header.level}")
+        print(f"  format_version:       {header.format_version}")
+        print(f"  trace_schema_version: {header.trace_schema_version}")
+        print(f"  duration:             {max_mono:.3f}s")
+        print(f"  sm_config_digest:     {header.sm_config_digest or '(none)'}")
+        print(f"  total_records:        {sum(counts.values())}")
+        if counts:
+            print("  ops:")
+            for qn in sorted(counts):
+                print(f"    {qn}: {counts[qn]}")
+        else:
+            print("  ops: (none)")
diff --git a/lmcache/cli/commands/trace/replay_command.py b/lmcache/cli/commands/trace/replay_command.py
new file mode 100644
index 0000000..ac9deb6
--- /dev/null
+++ b/lmcache/cli/commands/trace/replay_command.py
@@ -0,0 +1,326 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``lmcache trace replay`` — replay a trace file against a StorageManager."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import argparse
+import json
+import os
+import sys
+
+# First Party
+from lmcache.cli.commands.base import BaseCommand
+from lmcache.cli.metrics import Metrics, StreamHandler, get_formatter
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.cli.commands.trace._driver import ReplayResult
+    from lmcache.cli.commands.trace._stats import ReplayStatsCollector
+
+
+class ReplayCommand(BaseCommand):
+    """Replay a trace file against a fresh StorageManager."""
+
+    def name(self) -> str:
+        return "replay"
+
+    def help(self) -> str:
+        return "Replay a trace file against a fresh StorageManager."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        add_replay_arguments(parser)
+
+    def execute(self, args: argparse.Namespace) -> None:
+        run_trace_replay(args)
+
+
+def add_replay_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add ``lmcache trace replay`` arguments to *parser*.
+
+    Args:
+        parser: The ``ArgumentParser`` for the replay subcommand.
+    """
+    parser.add_argument(
+        "trace_path",
+        metavar="FILE",
+        help="Path to a .lct trace file.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        default=False,
+        help="Print one line per replayed record.",
+    )
+    parser.add_argument(
+        "--jsonl-out",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Write one JSON object per replayed record to PATH "
+            "(qualname, latency_ms, failed).  Useful for post-hoc "
+            "analysis."
+        ),
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help=(
+            "Directory for aggregated CSV/JSON summary output "
+            "(default: current directory)."
+        ),
+    )
+    parser.add_argument(
+        "--no-csv",
+        action="store_true",
+        help="Skip the aggregated CSV summary export.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Also export an aggregated JSON summary.",
+    )
+
+    try:
+        # First Party
+        from lmcache.v1.distributed.config import add_storage_manager_args
+        from lmcache.v1.mp_observability.config import add_observability_args
+
+        add_storage_manager_args(parser)
+        add_observability_args(parser)
+    except ImportError as e:
+        logger.warning("lmcache trace replay import error, error is %s", e)
+
+
+def run_trace_replay(args: argparse.Namespace) -> None:
+    """Construct a StorageManager from *args* and drive replay.
+
+    Produces three kinds of output:
+
+    * Per-record stream: every dispatch is logged at INFO with its
+      progress (``[N/total]``), qualname, and latency.
+      ``--verbose`` additionally mirrors each record to stdout,
+      and ``--jsonl-out PATH`` writes one JSON object per record
+      to ``PATH`` for post-hoc analysis.
+    * Aggregated per-qualname summary: CSV (unless ``--no-csv``)
+      and JSON (with ``--json``) written under ``--output-dir``.
+    * Terminal metrics table (unless ``--quiet``) using the shared
+      :class:`~lmcache.cli.metrics.Metrics` renderer.
+
+    Args:
+        args: Parsed CLI arguments.
+    """
+    # First Party
+    from lmcache.cli.commands.trace._driver import StorageReplayDriver
+    from lmcache.v1.distributed.config import StorageManagerConfig, parse_args_to_config
+    from lmcache.v1.mp_observability.config import parse_args_to_observability_config
+    from lmcache.v1.mp_observability.trace.reader import TraceReader
+
+    sm_config: StorageManagerConfig = parse_args_to_config(args)
+
+    # ``--trace-level`` / ``--trace-output`` belong to the recording
+    # surface.  They are still registered on the parser so the flag set
+    # stays in lock-step with ``lmcache server``, but they have no
+    # meaning here — any value a caller passes is silently clobbered to
+    # ``None`` so the replay-side ``ObservabilityConfig`` never tries to
+    # start a recorder.
+    args.trace_level = None
+    args.trace_output = None
+    obs_config = parse_args_to_observability_config(args)
+
+    # Create output directories *before* replay starts.  A replay
+    # can run for minutes; surfacing a bad ``--output-dir`` or
+    # unwritable ``--jsonl-out`` parent now avoids silently losing
+    # the summary/stream after the work has already happened.
+    os.makedirs(args.output_dir, exist_ok=True)
+    if args.jsonl_out:
+        jsonl_parent = os.path.dirname(os.path.abspath(args.jsonl_out))
+        if jsonl_parent:
+            os.makedirs(jsonl_parent, exist_ok=True)
+
+    # ANSI: bold + yellow for the banner text, reset at the end.
+    bold = "\033[1;33m"
+    reset = "\033[0m"
+    bar = "=" * 78
+    logger.warning(
+        "\n%s%s\n"
+        "  !! REPLAY ENVIRONMENT MISMATCH MAY CAUSE RETRIEVE MISSES !!\n"
+        "%s%s\n"
+        "  * Replay uses the *replay-side* StorageManager config, which\n"
+        "    may differ from the config recorded in the trace.\n"
+        "  * Replay runs on a host whose performance may differ from\n"
+        "    the recording host.\n"
+        "  * StorageManager reads/writes are async — an L2 load that\n"
+        "    had finished at record time may not have finished yet at\n"
+        "    replay time, so the matching retrieve can miss.\n"
+        "\n"
+        "  Treat retrieve-miss counts as a signal about the replay\n"
+        "  environment, not as a defect in the trace.\n"
+        "%s%s",
+        bold,
+        bar,
+        bar,
+        reset,
+        bar,
+        reset,
+    )
+
+    # Pre-scan to count total records so progress logs can show
+    # [N/total].  The reader streams frames, so counting is cheap
+    # relative to replay (which actually dispatches StorageManager
+    # calls).
+    with TraceReader(args.trace_path) as r:
+        total_records = sum(1 for _ in r.records())
+    logger.info(
+        "trace replay: file=%s records=%d",
+        args.trace_path,
+        total_records,
+    )
+
+    jsonl_fh = open(args.jsonl_out, "w") if args.jsonl_out else None
+    verbose = args.verbose
+    counter = {"n": 0}
+
+    def _on_record(qualname: str, latency_s: float, failed: bool) -> None:
+        counter["n"] += 1
+        status = "FAIL" if failed else "OK"
+        logger.info(
+            "[%d/%d] %s %s (%.3fms)",
+            counter["n"],
+            total_records,
+            status,
+            qualname,
+            latency_s * 1000.0,
+        )
+        if verbose:
+            print(
+                f"  [{counter['n']}/{total_records}]  "
+                f"{status:<4}  {latency_s * 1000:8.3f}ms  {qualname}"
+            )
+        if jsonl_fh is not None:
+            jsonl_fh.write(
+                json.dumps(
+                    {
+                        "qualname": qualname,
+                        "latency_ms": latency_s * 1000.0,
+                        "failed": failed,
+                    }
+                )
+                + "\n"
+            )
+
+    try:
+        with StorageReplayDriver(
+            sm_config, args.trace_path, obs_config=obs_config
+        ) as driver:
+            result = driver.run(on_record=_on_record)
+    finally:
+        if jsonl_fh is not None:
+            jsonl_fh.close()
+
+    if not args.no_csv:
+        csv_path = os.path.join(args.output_dir, "trace_replay_ops.csv")
+        result.stats.export_csv(csv_path)
+        logger.info("CSV written to %s", csv_path)
+    if args.json:
+        json_path = os.path.join(args.output_dir, "trace_replay_summary.json")
+        result.stats.export_json(json_path)
+        logger.info("JSON written to %s", json_path)
+
+    if not args.quiet:
+        _emit_replay_metrics(result.stats, result)
+
+    if result.records_failed > 0:
+        sys.exit(1)
+
+
+def _emit_replay_metrics(
+    stats: "ReplayStatsCollector",
+    result: "ReplayResult",
+) -> None:
+    """Print the replay summary using the shared :class:`Metrics` renderer.
+
+    Args:
+        stats: The stats collector populated during replay.
+        result: The full :class:`ReplayResult` — used for the
+            replayed/skipped/failed totals and digest comparison.
+    """
+    metrics = Metrics(title="Trace Replay Result")
+    metrics.add_handler(StreamHandler(get_formatter("terminal", width=64)))
+
+    overall = metrics.add_section("overall", "Overall")
+    overall.add("level", "Trace level", result.header_level)
+    overall.add("replayed", "Records replayed", result.records_replayed)
+    overall.add("skipped", "Records skipped", result.records_skipped)
+    overall.add("failed", "Records failed", result.records_failed)
+    overall.add(
+        "duration",
+        "Replay duration (s)",
+        round(stats.total_duration_s(), 3),
+    )
+    header_digest = result.header_digest
+    replay_digest = result.replay_config_digest
+    if header_digest and replay_digest and header_digest != replay_digest:
+        overall.add(
+            "digest",
+            "Config digest",
+            f"MISMATCH (rec={header_digest[:8]}, run={replay_digest[:8]})",
+        )
+    elif header_digest:
+        overall.add("digest", "Config digest", f"match ({header_digest[:8]})")
+
+    summary = stats.summary()
+    if summary:
+        ops_section = metrics.add_section("ops", "Per-Op Latency (ms)")
+        for qn in sorted(summary):
+            s = summary[qn]
+            short = _short_op_name(qn)
+            ops_section.add(f"{short}_count", f"{short} count", s.count)
+            ops_section.add(
+                f"{short}_mean",
+                f"{short} mean",
+                round(s.mean_ms, 3),
+            )
+            ops_section.add(
+                f"{short}_p50",
+                f"{short} p50",
+                round(s.p50_ms, 3),
+            )
+            ops_section.add(
+                f"{short}_p99",
+                f"{short} p99",
+                round(s.p99_ms, 3),
+            )
+
+    metrics.emit()
+
+
+def _short_op_name(qualname: str) -> str:
+    """Return a compact, human-readable label for a traced qualname.
+
+    Plain methods collapse to the method name: the table has limited
+    column width and the fully-qualified path is verbose.
+
+    Context-manager handlers (``__enter__`` / ``__exit__``) instead
+    collapse to ``<owning_method>.enter`` / ``<owning_method>.exit``,
+    so the reader can tell *which* context manager the pair belongs
+    to — the bare ``__enter__`` / ``__exit__`` label is useless when
+    multiple context-manager-returning methods are traced.
+
+    Args:
+        qualname: Dotted qualname recorded by the tracer, e.g.
+            ``lmcache.v1.distributed.storage_manager.StorageManager.read_prefetched_results.__enter__``.
+
+    Returns:
+        A short label suitable as a metrics row prefix.
+    """
+    parts = qualname.split(".")
+    last = parts[-1]
+    if last in ("__enter__", "__exit__") and len(parts) >= 2:
+        return f"{parts[-2]}.{last.strip('_')}"
+    return last
diff --git a/lmcache/cli/documents/lmcache.txt b/lmcache/cli/documents/lmcache.txt
new file mode 100644
index 0000000..9400962
--- /dev/null
+++ b/lmcache/cli/documents/lmcache.txt
@@ -0,0 +1,11 @@
+LMCache is a high-performance key–value (KV) cache management system designed to accelerate large language model (LLM) inference by efficiently storing, transferring, and reusing intermediate attention states. As modern LLM serving increasingly becomes bottlenecked by memory bandwidth, redundant computation, and cross-device communication, LMCache provides a system-level solution that decouples KV cache storage from the model execution pipeline and enables scalable, low-latency reuse across requests, processes, and even distributed nodes.
+
+At its core, LMCache targets one of the most expensive components of autoregressive inference: the KV cache generated during the prefill phase. In conventional serving systems, this cache is tightly coupled to a single process or GPU, making it difficult to reuse across requests or share between instances. As a result, repeated prompts or multi-turn conversations often trigger redundant computation, increasing both latency and resource consumption. LMCache addresses this limitation by introducing a unified KV cache abstraction that can be externally managed, retrieved asynchronously, and seamlessly reintegrated into the decoding pipeline.
+
+A key design principle of LMCache is minimizing the impact of cache operations on the critical path of inference. By supporting asynchronous KV retrieval and background prefetching, LMCache allows decoding to proceed without blocking on cache transfers. This is particularly important in disaggregated or multi-process (MP) deployments, where different inference engines may collaborate through a shared cache backend. In such settings, LMCache enables one instance to reuse KV states computed by another, significantly reducing time-to-first-token (TTFT) and improving tail latency. Empirical results show substantial gains in multi-turn and stateful workloads, where reuse opportunities are abundant.
+
+LMCache also provides flexible support for heterogeneous memory and storage backends, including GPU memory, host memory, persistent storage (e.g., SSD or DAX devices), and high-speed interconnects such as RDMA. Through pluggable connectors and configurable transfer policies, it can adapt to diverse deployment environments, from single-node setups to large-scale distributed clusters. This flexibility enables system designers to balance trade-offs between latency, capacity, and cost, while maintaining high throughput.
+
+Beyond performance optimization, LMCache emphasizes observability and integration. It exposes detailed metrics for cache lookup, retrieval, and storage operations, allowing users to understand system behavior and diagnose bottlenecks. It is designed to integrate seamlessly with popular serving frameworks such as vLLM, requiring minimal changes to existing workflows while unlocking advanced caching capabilities.
+
+In summary, LMCache rethinks KV cache management as a first-class system component for LLM serving. By enabling efficient reuse, asynchronous data movement, and cross-instance sharing, it addresses fundamental inefficiencies in current inference pipelines and paves the way for more scalable, responsive, and resource-efficient AI systems.
\ No newline at end of file
diff --git a/lmcache/cli/main.py b/lmcache/cli/main.py
new file mode 100644
index 0000000..754b8c6
--- /dev/null
+++ b/lmcache/cli/main.py
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LMCache CLI entry point.
+
+Subcommands are explicitly registered in
+``lmcache.cli.commands.ALL_COMMANDS``.
+"""
+
+# Standard
+import argparse
+import sys
+
+# First Party
+from lmcache.banner import print_banner_once
+from lmcache.cli.commands import ALL_COMMANDS
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def main() -> None:
+    """CLI entry point registered as ``lmcache`` in *pyproject.toml*."""
+    print_banner_once(sys.stderr)
+    parser = argparse.ArgumentParser(
+        prog="lmcache",
+        description="LMCache — KV cache management for LLM serving",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    for cmd in ALL_COMMANDS:
+        cmd.register(subparsers)
+
+    args = parser.parse_args()
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except Exception:  # noqa: BLE001
+        logger.exception("Command failed")
+        sys.exit(1)
diff --git a/lmcache/cli/metrics/__init__.py b/lmcache/cli/metrics/__init__.py
new file mode 100644
index 0000000..e15d561
--- /dev/null
+++ b/lmcache/cli/metrics/__init__.py
@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Metrics package — collector, handlers, and formatters."""
+
+# First Party
+from lmcache.cli.metrics.formatter import (
+    JsonFormatter,
+    MetricsFormatter,
+    TerminalFormatter,
+    get_formatter,
+)
+from lmcache.cli.metrics.handler import (
+    FileHandler,
+    MetricsHandler,
+    StreamHandler,
+)
+from lmcache.cli.metrics.metrics import Metrics
+from lmcache.cli.metrics.section import Section
+
+__all__ = [
+    "FileHandler",
+    "JsonFormatter",
+    "get_formatter",
+    "Metrics",
+    "MetricsFormatter",
+    "MetricsHandler",
+    "Section",
+    "StreamHandler",
+    "TerminalFormatter",
+]
diff --git a/lmcache/cli/metrics/formatter.py b/lmcache/cli/metrics/formatter.py
new file mode 100644
index 0000000..2264b3f
--- /dev/null
+++ b/lmcache/cli/metrics/formatter.py
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Metrics formatters — control *how* metrics are rendered.
+
+A formatter converts a title + sections into a string (or dict).
+Formatters are attached to handlers, separating rendering from destination.
+"""
+
+# Standard
+from typing import Any
+import abc
+import inspect
+import json
+
+# First Party
+from lmcache.cli.metrics.section import Section, sections_to_dict
+
+
+class MetricsFormatter(abc.ABC):
+    """Base class for metrics formatters."""
+
+    @abc.abstractmethod
+    def format(self, title: str, sections: list[Section]) -> str:
+        """Render metrics into a string.
+
+        Args:
+            title: The report title.
+            sections: Ordered list of ``Section`` objects.
+
+        Returns:
+            The formatted string.
+        """
+
+
+# ---------------------------------------------------------------------------
+# Formatter registry
+# ---------------------------------------------------------------------------
+
+_FORMATTER_REGISTRY: dict[str, type[MetricsFormatter]] = {}
+
+
+def register_formatter(name: str):
+    """Decorator that registers a ``MetricsFormatter`` subclass under *name*.
+
+    Args:
+        name: The format name used for CLI lookup (e.g. ``"json"``).
+
+    Returns:
+        A class decorator that registers the class and returns it unchanged.
+    """
+
+    def decorator(cls: type[MetricsFormatter]) -> type[MetricsFormatter]:
+        _FORMATTER_REGISTRY[name] = cls
+        return cls
+
+    return decorator
+
+
+def get_formatter(name: str, **kwargs: Any) -> MetricsFormatter:
+    """Instantiate a formatter by its registered name.
+
+    Args:
+        name: Registered format name (e.g. ``"terminal"``, ``"json"``).
+        **kwargs: Forwarded to the formatter constructor (e.g. ``width``).
+
+    Returns:
+        A new formatter instance.
+
+    Raises:
+        ValueError: If *name* is not registered.
+    """
+    cls = _FORMATTER_REGISTRY.get(name)
+    if cls is None:
+        available = ", ".join(sorted(_FORMATTER_REGISTRY))
+        raise ValueError(f"Unknown format {name!r}. Available: {available}")
+    # Only forward kwargs that the constructor accepts.
+    sig = inspect.signature(cls.__init__)
+    valid = {k: v for k, v in kwargs.items() if k in sig.parameters}
+    return cls(**valid)
+
+
+# ---------------------------------------------------------------------------
+# Built-in formatters
+# ---------------------------------------------------------------------------
+
+
+def _format_value(value: Any) -> str:
+    """Format a metric value for terminal display."""
+    if value is None:
+        return "N/A"
+    if isinstance(value, float):
+        return f"{value:.2f}"
+    return str(value)
+
+
+@register_formatter("terminal")
+class TerminalFormatter(MetricsFormatter):
+    """Plain ASCII table formatter for terminal output.
+
+    Title is centered in ``=`` borders, section headers are centered in
+    ``-`` borders, key-value lines have left-aligned labels and
+    right-aligned values.
+
+    Args:
+        width: Target total character width for the output.
+    """
+
+    def __init__(self, width: int = 48) -> None:
+        self._width = width
+
+    def format(self, title: str, sections: list[Section]) -> str:
+        """Render metrics as an ASCII table.
+
+        Args:
+            title: The report title.
+            sections: Ordered list of ``Section`` objects.
+
+        Returns:
+            Rendered multi-line string.
+        """
+        width = self._width
+        lines: list[str] = []
+
+        # Title bar
+        title_text = f" {title} "
+        lines.append(title_text.center(width, "="))
+
+        for section in sections:
+            # Section header (skip for unnamed section)
+            if section.label is not None:
+                header_text = f" {section.label} "
+                lines.append(header_text.center(width, "-"))
+
+            for _key, label, value in section.entries:
+                formatted = _format_value(value)
+                label_part = f"{label}:"
+                padding = width - len(label_part) - len(formatted)
+                if padding < 1:
+                    padding = 1
+                lines.append(f"{label_part}{' ' * padding}{formatted}")
+
+        # Footer
+        lines.append("=" * width)
+
+        return "\n".join(lines)
+
+
+@register_formatter("json")
+class JsonFormatter(MetricsFormatter):
+    """Renders metrics as a JSON string.
+
+    Args:
+        indent: JSON indentation level.
+    """
+
+    def __init__(self, indent: int = 2) -> None:
+        self._indent = indent
+
+    def format(self, title: str, sections: list[Section]) -> str:
+        """Render metrics as indented JSON.
+
+        Args:
+            title: The report title.
+            sections: Ordered list of ``Section`` objects.
+
+        Returns:
+            JSON string.
+        """
+        return json.dumps(
+            sections_to_dict(title, sections),
+            indent=self._indent,
+        )
diff --git a/lmcache/cli/metrics/handler.py b/lmcache/cli/metrics/handler.py
new file mode 100644
index 0000000..dbbfc76
--- /dev/null
+++ b/lmcache/cli/metrics/handler.py
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Metrics handlers — control *where* metrics are written.
+
+Each handler pairs a destination (stream, file, …) with a
+:class:`~lmcache.cli.metrics.formatter.MetricsFormatter` that controls
+the rendering.
+"""
+
+# Standard
+from typing import IO, Optional, Union
+import abc
+import os
+import sys
+
+# First Party
+from lmcache.cli.metrics.formatter import (
+    JsonFormatter,
+    MetricsFormatter,
+    TerminalFormatter,
+)
+from lmcache.cli.metrics.section import Section
+
+
+class MetricsHandler(abc.ABC):
+    """Base class for metrics handlers."""
+
+    def __init__(self, formatter: MetricsFormatter) -> None:
+        self.formatter = formatter
+
+    @abc.abstractmethod
+    def emit(self, title: str, sections: list[Section]) -> None:
+        """Format and write metrics to the destination.
+
+        Args:
+            title: The report title.
+            sections: Ordered list of ``Section`` objects.
+        """
+
+
+class StreamHandler(MetricsHandler):
+    """Writes formatted metrics to a text stream.
+
+    Args:
+        formatter: The formatter to use for rendering.
+        stream: Writable text stream. Defaults to ``sys.stdout``.
+    """
+
+    def __init__(
+        self,
+        formatter: Optional[MetricsFormatter] = None,
+        stream: Optional[IO[str]] = None,
+    ) -> None:
+        super().__init__(formatter or TerminalFormatter())
+        self._stream = stream
+
+    def emit(self, title: str, sections: list[Section]) -> None:
+        """Format and write metrics to the stream.
+
+        Args:
+            title: The report title.
+            sections: Ordered list of ``Section`` objects.
+        """
+        stream = self._stream or sys.stdout
+        stream.write(self.formatter.format(title, sections))
+        stream.write("\n")
+
+
+class FileHandler(MetricsHandler):
+    """Writes formatted metrics to a file.
+
+    Args:
+        path: Destination file path.
+        formatter: The formatter to use for rendering. Defaults to
+            :class:`~lmcache.cli.metrics.formatter.JsonFormatter`.
+    """
+
+    def __init__(
+        self,
+        path: Union[str, os.PathLike],
+        formatter: Optional[MetricsFormatter] = None,
+    ) -> None:
+        super().__init__(formatter or JsonFormatter())
+        self.path = path
+
+    def emit(self, title: str, sections: list[Section]) -> None:
+        """Format and write metrics to the file.
+
+        Args:
+            title: The report title.
+            sections: Ordered list of ``Section`` objects.
+        """
+        with open(self.path, "w") as f:
+            f.write(self.formatter.format(title, sections))
+            f.write("\n")
diff --git a/lmcache/cli/metrics/metrics.py b/lmcache/cli/metrics/metrics.py
new file mode 100644
index 0000000..2097505
--- /dev/null
+++ b/lmcache/cli/metrics/metrics.py
@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Hierarchical metrics collector with handler-based output.
+
+Example usage::
+
+    from lmcache.cli.metrics import Metrics
+
+    metrics = Metrics(title="Bench KV Cache Result (30s)")
+
+    # Sectioned metrics
+    metrics.add_section("ops", "Operations (ops/s)")
+    metrics["ops"].add("store", "Store", 41.3)
+    metrics["ops"].add("retrieve", "Retrieve", 127.3)
+
+    # Top-level (flat) metrics
+    metrics.add("status", "Status", "OK")
+
+    metrics.emit()
+"""
+
+# Standard
+from typing import Any, Optional
+
+# First Party
+from lmcache.cli.metrics.handler import FileHandler, MetricsHandler
+from lmcache.cli.metrics.section import Section, sections_to_dict
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class Metrics:
+    """Hierarchical metrics collector with handler-based output.
+
+    Handlers are registered via :meth:`add_handler` and triggered
+    together by :meth:`emit`.  ``BaseCommand`` sets up default
+    handlers automatically, so command authors typically only need
+    to build metrics and call :meth:`emit`.
+
+    Args:
+        title: Report title shown in the header.
+    """
+
+    def __init__(self, title: str) -> None:
+        self._title = title
+        self._sections: list[Section] = []
+        self._section_map: dict[Optional[str], Section] = {}
+        self._handlers: list[MetricsHandler] = []
+
+    def title(self, title: str) -> None:
+        """Set the report title.
+
+        Args:
+            title: New report title shown in the header.
+        """
+        self._title = title
+
+    # -- Handler management -------------------------------------------------
+
+    def add_handler(self, handler: MetricsHandler) -> None:
+        """Register a handler.
+
+        Args:
+            handler: The handler to add.
+        """
+        self._handlers.append(handler)
+
+    # -- Section management -------------------------------------------------
+
+    def add_section(self, key: str, label: str) -> Section:
+        """Add a named section.
+
+        Args:
+            key: Machine-readable section key (used in JSON output and
+                for ``metrics["key"]`` access).
+            label: Human-readable label (used in terminal output).
+
+        Returns:
+            The newly created ``Section``.
+
+        Raises:
+            ValueError: If a section with the same *key* already exists.
+        """
+        if key in self._section_map:
+            raise ValueError(f"Section {key!r} already exists")
+        section = Section(key, label)
+        self._sections.append(section)
+        self._section_map[key] = section
+        return section
+
+    def add_list_section(self, group: str, key: str, label: str) -> Section:
+        """Add a section that belongs to a list group.
+
+        In terminal output, renders as a normal section with *label* as
+        the header. In JSON output, sections sharing the same *group*
+        are collected into a list: ``"group": [{...}, {...}]``.
+
+        Args:
+            group: The JSON key for the list (e.g., ``"models"``).
+            key: Unique machine key for this section instance.
+            label: Human-readable label (used in terminal output).
+
+        Returns:
+            The newly created ``Section``.
+        """
+        if key in self._section_map:
+            raise ValueError(f"Section {key!r} already exists")
+        section = Section(key, label, list_group=group)
+        self._sections.append(section)
+        self._section_map[key] = section
+        return section
+
+    def __getitem__(self, key: str) -> Section:
+        """Return the section registered under *key*.
+
+        Raises:
+            KeyError: If ``add_section(key, ...)`` was not called first.
+        """
+        return self._section_map[key]
+
+    # -- Flat (top-level) metrics -------------------------------------------
+
+    def _default_section(self) -> Section:
+        """Return the unnamed default section, creating it on first use."""
+        if None not in self._section_map:
+            section = Section(None, None)
+            # Insert at the beginning so flat metrics appear first
+            self._sections.insert(0, section)
+            self._section_map[None] = section
+        return self._section_map[None]
+
+    def add(self, key: str, label: str, value: Any) -> None:
+        """Record a top-level metric (not inside any named section).
+
+        Args:
+            key: Machine-readable key (used in JSON output).
+            label: Human-readable label (used in terminal output).
+            value: Metric value.
+        """
+        self._default_section().add(key, label, value)
+
+    # -- Output -------------------------------------------------------------
+
+    def emit(self) -> None:
+        """Trigger all registered handlers."""
+        for handler in self._handlers:
+            handler.emit(self._title, self._sections)
+        for handler in self._handlers:
+            if isinstance(handler, FileHandler):
+                logger.info("Results saved to %s", handler.path)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return metrics as a JSON-serialisable dictionary.
+
+        Returns:
+            A dict with ``"title"`` and ``"metrics"`` keys. Named
+            sections become nested dicts keyed by machine key. The
+            unnamed default section's entries are placed at the top
+            level of ``"metrics"``.
+        """
+        return sections_to_dict(self._title, self._sections)
diff --git a/lmcache/cli/metrics/section.py b/lmcache/cli/metrics/section.py
new file mode 100644
index 0000000..9d09c19
--- /dev/null
+++ b/lmcache/cli/metrics/section.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Section — a named group of metric entries."""
+
+# Standard
+from typing import Any, Optional
+
+
+class Section:
+    """A named group of metrics.
+
+    Each entry has a machine ``key`` (used in JSON), a human-readable
+    ``label`` (used in terminal output), and a ``value``.
+
+    Sections with the same :attr:`list_group` are collected into a
+    JSON list under that key (e.g., ``"models": [{...}, {...}]``).
+    In terminal output they render as normal independent sections.
+    """
+
+    def __init__(
+        self,
+        key: Optional[str],
+        label: Optional[str],
+        list_group: Optional[str] = None,
+    ) -> None:
+        self.key = key
+        self.label = label
+        self.list_group = list_group
+        self.entries: list[tuple[str, str, Any]] = []
+
+    def add(self, key: str, label: str, value: Any) -> None:
+        """Record a metric in this section.
+
+        Args:
+            key: Machine-readable key (used in JSON output).
+            label: Human-readable label (used in terminal output).
+            value: Metric value. Floats are formatted to 2 decimal
+                places on terminal output; strings are printed as-is.
+        """
+        self.entries.append((key, label, value))
+
+
+def sections_to_dict(
+    title: str,
+    sections: list[Section],
+) -> dict[str, Any]:
+    """Convert a title and sections to a JSON-serialisable dictionary.
+
+    Named sections become nested dicts keyed by machine key. The
+    unnamed default section's entries are placed at the top level
+    of ``"metrics"``.
+
+    Args:
+        title: The report title.
+        sections: Ordered list of ``Section`` objects.
+
+    Returns:
+        A dict with ``"title"`` and ``"metrics"`` keys.
+    """
+    metrics: dict[str, Any] = {}
+    list_groups: dict[str, list[dict[str, Any]]] = {}
+    for section in sections:
+        if section.key is None:
+            for key, _label, value in section.entries:
+                metrics[key] = value
+        elif section.list_group is not None:
+            section_dict: dict[str, Any] = {}
+            for key, _label, value in section.entries:
+                section_dict[key] = value
+            list_groups.setdefault(section.list_group, []).append(section_dict)
+        else:
+            section_dict = {}
+            for key, _label, value in section.entries:
+                section_dict[key] = value
+            metrics[section.key] = section_dict
+    for group_key, items in list_groups.items():
+        metrics[group_key] = items
+    return {"title": title, "metrics": metrics}
diff --git a/lmcache/connections.py b/lmcache/connections.py
new file mode 100644
index 0000000..d159dd8
--- /dev/null
+++ b/lmcache/connections.py
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+# This file is copied from the vLLM project (https://github.com/vllm-project/vllm).
+# Original source file: [vllm/vllm/connections.py]
+# License: [Apache License 2.0]
+# Modifications: header name
+
+# Standard
+from pathlib import Path
+from typing import Mapping, MutableMapping, Optional
+from urllib.parse import urlparse
+
+# Third Party
+import aiohttp
+import requests
+
+
+class HTTPConnection:
+    """Helper class to send HTTP requests."""
+
+    def __init__(self, *, reuse_client: bool = True) -> None:
+        super().__init__()
+
+        self.reuse_client = reuse_client
+
+        self._sync_client: Optional[requests.Session] = None
+        self._async_client: Optional[aiohttp.ClientSession] = None
+
+    def get_sync_client(self) -> requests.Session:
+        if self._sync_client is None or not self.reuse_client:
+            self._sync_client = requests.Session()
+
+        return self._sync_client
+
+    # NOTE: We intentionally use an async function even though it is not
+    # required, so that the client is only accessible inside async event loop
+    async def get_async_client(self) -> aiohttp.ClientSession:
+        if self._async_client is None or not self.reuse_client:
+            self._async_client = aiohttp.ClientSession()
+
+        return self._async_client
+
+    def _validate_http_url(self, url: str):
+        parsed_url = urlparse(url)
+
+        if parsed_url.scheme not in ("http", "https"):
+            raise ValueError(
+                "Invalid HTTP URL: A valid HTTP URL must have scheme 'http' or 'https'."
+            )
+
+    def _headers(self, **extras: str) -> MutableMapping[str, str]:
+        return {"User-Agent": "LMCache", **extras}
+
+    def get_response(
+        self,
+        url: str,
+        *,
+        stream: bool = False,
+        timeout: Optional[float] = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ):
+        self._validate_http_url(url)
+
+        client = self.get_sync_client()
+        extra_headers = extra_headers or {}
+
+        return client.get(
+            url,
+            headers=self._headers(**extra_headers),
+            stream=stream,
+            timeout=timeout,
+        )
+
+    async def get_async_response(
+        self,
+        url: str,
+        *,
+        timeout: Optional[float] = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+    ):
+        self._validate_http_url(url)
+
+        client = await self.get_async_client()
+        extra_headers = extra_headers or {}
+
+        return client.get(url, headers=self._headers(**extra_headers), timeout=timeout)
+
+    def get_bytes(self, url: str, *, timeout: Optional[float] = None) -> bytes:
+        with self.get_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            return r.content
+
+    async def async_get_bytes(
+        self,
+        url: str,
+        *,
+        timeout: Optional[float] = None,
+    ) -> bytes:
+        async with await self.get_async_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            return await r.read()
+
+    def get_text(self, url: str, *, timeout: Optional[float] = None) -> str:
+        with self.get_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            return r.text
+
+    async def async_get_text(
+        self,
+        url: str,
+        *,
+        timeout: Optional[float] = None,
+    ) -> str:
+        async with await self.get_async_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            return await r.text()
+
+    def get_json(self, url: str, *, timeout: Optional[float] = None) -> str:
+        with self.get_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            return r.json()
+
+    async def async_get_json(
+        self,
+        url: str,
+        *,
+        timeout: Optional[float] = None,
+    ) -> str:
+        async with await self.get_async_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            return await r.json()
+
+    def download_file(
+        self,
+        url: str,
+        save_path: Path,
+        *,
+        timeout: Optional[float] = None,
+        chunk_size: int = 128,
+    ) -> Path:
+        with self.get_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            with save_path.open("wb") as f:
+                for chunk in r.iter_content(chunk_size):
+                    f.write(chunk)
+
+        return save_path
+
+    async def async_download_file(
+        self,
+        url: str,
+        save_path: Path,
+        *,
+        timeout: Optional[float] = None,
+        chunk_size: int = 128,
+    ) -> Path:
+        async with await self.get_async_response(url, timeout=timeout) as r:
+            r.raise_for_status()
+
+            with save_path.open("wb") as f:
+                async for chunk in r.content.iter_chunked(chunk_size):
+                    f.write(chunk)
+
+        return save_path
+
+
+global_http_connection = HTTPConnection()
diff --git a/lmcache/integration/__init__.py b/lmcache/integration/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/lmcache/integration/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/lmcache/integration/base_service_factory.py b/lmcache/integration/base_service_factory.py
new file mode 100644
index 0000000..8fcb050
--- /dev/null
+++ b/lmcache/integration/base_service_factory.py
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+BaseServiceFactory: Abstract interface for creating LMCache service components.
+
+Each serving engine integration (e.g., vLLM) should implement a concrete
+ServiceFactory that determines which components to create for each role.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional, Union
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.health_monitor.base import HealthMonitor
+from lmcache.v1.health_monitor.constants import (
+    DEFAULT_PING_INTERVAL,
+    PING_INTERVAL_CONFIG_KEY,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.observability import PrometheusLogger
+    from lmcache.v1.cache_engine import LMCacheEngine
+    from lmcache.v1.internal_api_server.api_server import InternalAPIServer
+    from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+    from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+        LMCacheAsyncLookupServer,
+    )
+    from lmcache.v1.lookup_client.lmcache_lookup_client import LMCacheLookupServer
+    from lmcache.v1.manager import LMCacheManager
+    from lmcache.v1.metadata import LMCacheMetadata
+    from lmcache.v1.offload_server.zmq_server import ZMQOffloadServer
+    from lmcache.v1.plugin.runtime_plugin_launcher import RuntimePluginLauncher
+
+logger = init_logger(__name__)
+
+
+class BaseServiceFactory(ABC):
+    """Abstract base for creating LMCache service components.
+
+    Subclasses must implement all methods to provide the appropriate
+    components for their serving engine integration.
+    """
+
+    @abstractmethod
+    def get_engine_instance_id(self) -> str:
+        """Return the instance_id used to register the engine with
+        LMCacheEngineBuilder. Used by LMCacheManager for engine destruction."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_or_create_metadata(self) -> Optional["LMCacheMetadata"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_or_create_lmcache_engine(self) -> Optional["LMCacheEngine"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_lookup_client(self) -> Optional["LookupClientInterface"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_prometheus_logger(self) -> Optional["PrometheusLogger"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_lookup_server(
+        self,
+    ) -> Optional[Union["LMCacheLookupServer", "LMCacheAsyncLookupServer"]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_offload_server(self) -> Optional["ZMQOffloadServer"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_runtime_plugin_launcher(
+        self,
+    ) -> Optional["RuntimePluginLauncher"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_internal_api_server(
+        self, lmcache_manager: "LMCacheManager"
+    ) -> Optional["InternalAPIServer"]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def maybe_create_health_monitor(
+        self, lmcache_manager: "LMCacheManager"
+    ) -> Optional[HealthMonitor]:
+        raise NotImplementedError
+
+    def _create_health_monitor(
+        self,
+        lmcache_manager: "LMCacheManager",
+        config: LMCacheEngineConfig,
+        engine: Optional["LMCacheEngine"] = None,
+    ) -> HealthMonitor:
+        """Create, configure, and start the health monitor.
+
+        Shared implementation used by subclass maybe_create_health_monitor.
+        """
+        # First Party
+        from lmcache.observability import PrometheusLogger
+        from lmcache.v1.periodic_thread import (
+            PeriodicThreadRegistry,
+            ThreadLevel,
+        )
+
+        ping_interval = config.get_extra_config_value(
+            PING_INTERVAL_CONFIG_KEY, DEFAULT_PING_INTERVAL
+        )
+        health_monitor = HealthMonitor(
+            manager=lmcache_manager,
+            ping_interval=ping_interval,
+        )
+
+        if engine is not None:
+            engine.set_health_monitor(health_monitor)
+
+        health_monitor.start()
+        logger.info("Health monitor initialized and started")
+
+        metadata = lmcache_manager.lmcache_engine_metadata
+        if metadata is not None:
+            prometheus_logger = PrometheusLogger.GetOrCreate(
+                metadata,
+                config=config,
+            )
+            prometheus_logger.lmcache_is_healthy.set_function(
+                lambda: 1 if lmcache_manager.is_healthy() else 0
+            )
+
+            registry = PeriodicThreadRegistry.get_instance()
+
+            prometheus_logger.periodic_threads_total_count.set_function(
+                lambda: len(registry.get_all())
+            )
+            prometheus_logger.periodic_threads_running_count.set_function(
+                lambda: registry.get_running_count()
+            )
+            prometheus_logger.periodic_threads_active_count.set_function(
+                lambda: registry.get_active_count()
+            )
+
+            for level in ThreadLevel:
+                level_name = level.value
+                total_attr = f"periodic_threads_{level_name}_total"
+                running_attr = f"periodic_threads_{level_name}_running"
+                active_attr = f"periodic_threads_{level_name}_active"
+
+                if hasattr(prometheus_logger, total_attr):
+                    getattr(prometheus_logger, total_attr).set_function(
+                        lambda lvl=level: registry.get_count_by_level(lvl)["total"]
+                    )
+                if hasattr(prometheus_logger, running_attr):
+                    getattr(prometheus_logger, running_attr).set_function(
+                        lambda lvl=level: registry.get_count_by_level(lvl)["running"]
+                    )
+                if hasattr(prometheus_logger, active_attr):
+                    getattr(prometheus_logger, active_attr).set_function(
+                        lambda lvl=level: registry.get_count_by_level(lvl)["active"]
+                    )
+
+        return health_monitor
diff --git a/lmcache/integration/request_telemetry/__init__.py b/lmcache/integration/request_telemetry/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/integration/request_telemetry/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/integration/request_telemetry/base.py b/lmcache/integration/request_telemetry/base.py
new file mode 100644
index 0000000..13cb60a
--- /dev/null
+++ b/lmcache/integration/request_telemetry/base.py
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Abstract base class for request telemetry.
+
+This module provides the interface for tracking request-level events
+in LMCache, such as when a request finishes and its associated async
+save operations complete.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class RequestTelemetry(ABC):
+    """
+    Abstract base class for request telemetry.
+
+    This class defines the interface for capturing request-level telemetry
+    events. Implementations can log events, emit metrics, or perform other
+    actions when specific request lifecycle events occur.
+    """
+
+    @abstractmethod
+    def __init__(self, config: dict[str, Any]) -> None:
+        pass
+
+    @abstractmethod
+    def on_request_store_finished(
+        self,
+        request_ids_set: set[str],
+        model_name: str,
+        world_size: int,
+        kv_rank: int,
+    ) -> None:
+        """
+        Callback when request finishes AND all its KV cache store ops completes.
+
+        This method ensures that request_ids_set is not empty.
+
+        Technically this function is implemented by inspecting the return value
+        of `get_finished` method.
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        pass
+
+    def __del__(self) -> None:
+        self.close()
diff --git a/lmcache/integration/request_telemetry/factory.py b/lmcache/integration/request_telemetry/factory.py
new file mode 100644
index 0000000..0ca1f28
--- /dev/null
+++ b/lmcache/integration/request_telemetry/factory.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Factory for creating request telemetry reporters based on configuration.
+"""
+
+# Standard
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Optional
+import importlib
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.integration.request_telemetry.base import RequestTelemetry
+
+
+class RequestTelemetryFactory:
+    """Factory for creating request telemetry reporters."""
+
+    _registry: dict[str, Callable[[], type["RequestTelemetry"]]] = {}
+    _instances: dict[str, "RequestTelemetry"] = {}
+
+    @classmethod
+    def register(cls, name: str, module_path: str, class_name: str) -> None:
+        """Register a telemetry reporter with lazy-loading module and class name.
+
+        Args:
+            name: The name to register the telemetry reporter under.
+            module_path: The module path to import the class from.
+            class_name: The class name to import from the module.
+
+        Raises:
+            ValueError: If a reporter with the same name is already registered.
+        """
+        if name in cls._registry:
+            raise ValueError(f"Telemetry reporter '{name}' is already registered.")
+
+        def loader() -> type["RequestTelemetry"]:
+            module = importlib.import_module(module_path)
+            return getattr(module, class_name)
+
+        cls._registry[name] = loader
+
+    @classmethod
+    def create(
+        cls,
+        telemetry_type: Optional[str] = None,
+        config: Optional[dict[str, Any]] = None,
+        use_singleton: bool = True,
+    ) -> "RequestTelemetry":
+        """Create a request telemetry reporter based on the specified type.
+
+        Args:
+            telemetry_type: The type of telemetry reporter to create.
+                If None, defaults to "noop".
+                Supported values: "noop", "fastapi".
+            config: Optional dict of configuration options passed to the reporter.
+                Each reporter defines its own expected keys.
+            use_singleton: If True, returns a cached singleton instance.
+                If False, creates a new instance each time.
+                Note: Singleton is keyed by telemetry_type only.
+
+        Returns:
+            A RequestTelemetry instance.
+
+        Raises:
+            ValueError: If an unsupported telemetry type is specified.
+        """
+        if telemetry_type is None:
+            telemetry_type = "noop"
+
+        telemetry_type = telemetry_type.lower()
+
+        if telemetry_type not in cls._registry:
+            raise ValueError(
+                f"Unsupported request telemetry type: {telemetry_type}. "
+                f"Supported types: {list(cls._registry.keys())}"
+            )
+
+        if use_singleton and telemetry_type in cls._instances:
+            return cls._instances[telemetry_type]
+
+        if config is None:
+            config = {}
+
+        telemetry_cls = cls._registry[telemetry_type]()
+        instance = telemetry_cls(config)
+
+        if use_singleton:
+            cls._instances[telemetry_type] = instance
+
+        return instance
+
+    @classmethod
+    def get_registered_types(cls) -> list[str]:
+        """Get a list of all registered telemetry types."""
+        return list(cls._registry.keys())
+
+
+# Register telemetry types here.
+# The registration should not be done in each individual file, as we want to
+# only load the files corresponding to the current telemetry type.
+
+RequestTelemetryFactory.register(
+    "noop",
+    "lmcache.integration.request_telemetry.noop",
+    "NoOpRequestTelemetry",
+)
+
+RequestTelemetryFactory.register(
+    "fastapi",
+    "lmcache.integration.request_telemetry.fastapi",
+    "FastAPIRequestTelemetry",
+)
diff --git a/lmcache/integration/request_telemetry/fastapi.py b/lmcache/integration/request_telemetry/fastapi.py
new file mode 100644
index 0000000..29397ed
--- /dev/null
+++ b/lmcache/integration/request_telemetry/fastapi.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+FastAPI-based request telemetry reporter.
+"""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+import json
+import threading
+
+# First Party
+from lmcache.integration.request_telemetry.base import RequestTelemetry
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class FastAPIRequestTelemetry(RequestTelemetry):
+    """
+    FastAPI-based request telemetry reporter.
+
+    Sends telemetry events to a FastAPI server endpoint asynchronously
+    using a thread pool to avoid blocking the main execution path.
+
+    Config dict keys:
+        endpoint: The FastAPI endpoint URL to send telemetry events to. (required)
+        timeout: Timeout in seconds for HTTP requests. Defaults to 5.0.
+        max_workers: Maximum number of threads for async HTTP requests.
+            Defaults to 2.
+    """
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        endpoint = config.get("endpoint", None)
+        if endpoint is None:
+            raise ValueError(
+                "FastAPIRequestTelemetry requires setting endpoint. "
+                "Please set LMCACHE_REQUEST_TELEMETRY_ENDPOINT envvar."
+            )
+
+        self._endpoint = endpoint
+        self._timeout = config.get("timeout", 5.0)
+        self._executor = ThreadPoolExecutor(
+            max_workers=config.get("max_workers", 2),
+            thread_name_prefix="fastapi-telemetry",
+        )
+        self._lock = threading.Lock()
+        self._closed = False
+
+        logger.info(
+            "LMCache FastAPIRequestTelemetry initialized with endpoint: %s",
+            self._endpoint,
+        )
+
+    def on_request_store_finished(
+        self,
+        request_ids_set: set[str],
+        model_name: str,
+        world_size: int,
+        kv_rank: int,
+    ) -> None:
+        """Send request store finished event to the FastAPI endpoint."""
+        if self._closed:
+            return
+
+        payload = {
+            "event": "request_store_finished",
+            "request_ids_set": list(request_ids_set),
+            "model_name": model_name,
+            "world_size": world_size,
+            "kv_rank": kv_rank,
+        }
+
+        # Submit async HTTP request
+        self._executor.submit(self._send_event, payload)
+
+    def _send_event(self, payload: dict[str, Any]) -> None:
+        """Send an event to the FastAPI endpoint (runs in thread pool)."""
+        try:
+            data = json.dumps(payload).encode("utf-8")
+            request = Request(
+                self._endpoint,
+                data=data,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            # TODO: this introduces blocking IO, should use asyncio.
+            with urlopen(request, timeout=self._timeout) as response:
+                if response.status >= 400:
+                    logger.warning(
+                        f"FastAPI telemetry request failed with"
+                        f" status {response.status}"
+                    )
+        except URLError as e:
+            logger.warning(f"FastAPI telemetry request failed: {e}")
+        except Exception as e:
+            logger.warning(f"FastAPI telemetry request failed unexpectedly: {e}")
+
+    def close(self) -> None:
+        """Shutdown the thread pool executor."""
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+
+        self._executor.shutdown(wait=True)
+        logger.info("FastAPIRequestTelemetry closed")
diff --git a/lmcache/integration/request_telemetry/noop.py b/lmcache/integration/request_telemetry/noop.py
new file mode 100644
index 0000000..8e052a3
--- /dev/null
+++ b/lmcache/integration/request_telemetry/noop.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+No-op implementation of request telemetry.
+"""
+
+# Standard
+from typing import Any
+
+# First Party
+from lmcache.integration.request_telemetry.base import RequestTelemetry
+
+
+class NoOpRequestTelemetry(RequestTelemetry):
+    """
+    A no-op implementation of RequestTelemetry.
+
+    This implementation does nothing when events are reported.
+    Use this when telemetry is disabled or not needed.
+    """
+
+    def __init__(self, config: dict[str, Any]) -> None:
+        # NoOp doesn't need any config, but accepts it for interface consistency
+        pass
+
+    def on_request_store_finished(
+        self,
+        request_ids_set: set[str],
+        model_name: str,
+        world_size: int,
+        kv_rank: int,
+    ) -> None:
+        pass
+
+    def close(self) -> None:
+        pass
diff --git a/lmcache/integration/sglang/__init__.py b/lmcache/integration/sglang/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/lmcache/integration/sglang/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/lmcache/integration/sglang/multi_process_adapter.py b/lmcache/integration/sglang/multi_process_adapter.py
new file mode 100644
index 0000000..53a4529
--- /dev/null
+++ b/lmcache/integration/sglang/multi_process_adapter.py
@@ -0,0 +1,555 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+import os
+import threading
+
+# Third Party
+from sglang.srt.configs.model_config import ModelConfig
+import torch
+import torch.distributed as dist
+import zmq
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.sglang.sglang_adapter import (
+    LoadMetadata,
+    StoreMetadata,
+)
+from lmcache.integration.vllm.vllm_multi_process_adapter import (
+    DEFAULT_HEARTBEAT_INTERVAL,
+    DEFAULT_MQ_TIMEOUT,
+    HeartbeatThread,
+    get_lmcache_chunk_size,
+    send_lmcache_request,
+)
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.mp_observability.errors import LMCacheTimeoutError
+from lmcache.v1.multiprocess.custom_types import (
+    IPCCacheServerKey,
+    KVCache,
+)
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import RequestType
+from lmcache.v1.platform.cuda.ipc_wrapper import CudaIPCWrapper
+
+logger = init_logger(__name__)
+
+# Extra seconds the WAIT_PREFETCH_STATUS response is allowed beyond the daemon's
+# own blocking-wait budget, to cover the request/response round trip.
+_WAIT_LOOKUP_RESPONSE_BUFFER_S = 5.0
+
+
+def _wrap_sglang_kv_caches(
+    k_pool: list[torch.Tensor],
+    v_pool: list[torch.Tensor],
+) -> KVCache:
+    """Flatten SGLang's depth-2 ``[K_layers, V_layers]`` KV layout into a
+    single flat ``KVCache`` so it fits upstream's wire
+    ``KVCache`` payload type. The daemon's
+    :func:`normalize_kv_and_discover_format` recognizes this shape from
+    ``EngineType.SGLANG`` plus a ``tokens_per_block`` ``LayoutHints`` field
+    and splits it back at its midpoint before format detection.
+    """
+    wrapped: KVCache = []
+    wrapped.extend(CudaIPCWrapper(tensor) for tensor in k_pool)
+    wrapped.extend(CudaIPCWrapper(tensor) for tensor in v_pool)
+    return wrapped
+
+
+@dataclass
+class _PendingLookup:
+    """Per-request_id state retained between ``lookup_kv`` and
+    ``retrieve_kv``.
+
+    Attributes:
+        token_ids: tokens that LOOKUP was issued for.
+        matched_token_num: number of chunk-aligned tokens the daemon
+            reported as cached (return value of LOOKUP →
+            QUERY_PREFETCH_STATUS).
+        locks_held: True iff the daemon still holds the read locks
+            reserved by this LOOKUP. RETRIEVE consumes them; explicit
+            FREE_LOOKUP_LOCKS releases them.
+    """
+
+    token_ids: list[int]
+    matched_token_num: int
+    locks_held: bool
+
+
+class LMCacheMPConnector:
+    """SGLang LMCache multi-process connector.
+
+    Talks to a standalone LMCache daemon over ZMQ.
+
+    - ``lookup_kv``: fires LOOKUP. Daemon prefetches missing
+      chunks L2→L1 (DRAM), keeps the read locks held, returns the
+      matched-token count.
+    - ``retrieve_kv``: fires RETRIEVE using the cached LOOKUP result.
+      Daemon copies L1→GPU via ``multi_layer_block_kv_transfer``
+      (single CUDA launch, all layers) and releases the read locks
+      via ``finish_read_prefetched``.
+    - ``release_pending``: frees the held locks when no RETRIEVE will
+      follow (LMCache had nothing fresh beyond radix).
+    - ``end_session``: per-request cleanup. Frees any still-held
+      locks then sends END_SESSION so the daemon doesn't leak
+      read-lock reservations.
+    """
+
+    def __init__(
+        self,
+        sgl_config: ModelConfig,
+        tp_size: int,
+        rank: int,
+        page_size: int,
+        host: str,
+        port: int,
+        k_pool: list[torch.Tensor],
+        v_pool: list[torch.Tensor],
+        tp_group: Optional[torch.distributed.ProcessGroup] = None,
+        mq_timeout: float = DEFAULT_MQ_TIMEOUT,
+        heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL,
+    ):
+        self.tp_size = tp_size
+        self.worker_id = rank
+        self.page_size = page_size
+        self.device = k_pool[0].device
+        self.model_name = sgl_config.model_path
+        self.num_layers = len(k_pool)
+        self.tp_group = tp_group
+        self.instance_id = os.getpid()
+        self._mq_timeout = mq_timeout
+        self._heartbeat_interval = heartbeat_interval
+        self._registered = False
+        self._heartbeat: HeartbeatThread | None = None
+        self._health_event = threading.Event()
+        self._health_event.set()
+        self._pending_lookups: dict[str, _PendingLookup] = {}
+        self._pending_lookups_lock = threading.Lock()
+
+        self.context = zmq.Context.instance()
+        self.mq_client = MessageQueueClient(f"tcp://{host}:{port}", self.context)
+
+        self._lmcache_chunk_size = get_lmcache_chunk_size(self.mq_client)
+        if self._lmcache_chunk_size % self.page_size != 0:
+            raise ValueError(
+                "LMCache chunk size must be a multiple of SGLang page size, got "
+                f"{self._lmcache_chunk_size} and {self.page_size}"
+            )
+
+        # Upstream's REGISTER_KV_CACHE protocol takes flat positional args:
+        # (instance_id, kv_cache, model_name, world_size, engine_type,
+        # layout_hints, engine_group_infos). SGLang's natural KV layout is depth-2
+        # ([K_layers, V_layers]); we flatten it on the wire to fit
+        # ``KVCache = list[DeviceIPCWrapper]``. The daemon recognizes the
+        # SGLang-MHA flat-of-2NL pattern from ``EngineType.SGLANG`` plus the
+        # ``tokens_per_block`` hint and un-flattens + reshapes per layer.
+        # SGLang is non-hybrid (a single KV cache group), so engine_group_infos is the
+        # empty list -- which the server treats as one group spanning all layers
+        # (matching the vLLM non-hybrid and TensorRT-LLM register paths).
+        send_lmcache_request(
+            self.mq_client,
+            RequestType.REGISTER_KV_CACHE,
+            [
+                self.instance_id,
+                _wrap_sglang_kv_caches(k_pool, v_pool),
+                self.model_name,
+                self.tp_size,
+                EngineType.SGLANG,
+                {"tokens_per_block": self.page_size},
+                [],
+            ],
+        ).result(timeout=self._mq_timeout)
+        self._registered = True
+        self._start_heartbeat()
+
+    def _start_heartbeat(self) -> None:
+        if self._heartbeat is not None:
+            return
+        self._heartbeat = HeartbeatThread(
+            mq_client=self.mq_client,
+            health_event=self._health_event,
+            interval=self._heartbeat_interval,
+            instance_id=self.instance_id,
+        )
+        self._heartbeat.start()
+
+    @property
+    def is_healthy(self) -> bool:
+        return self._health_event.is_set()
+
+    def chunk_size(self) -> int:
+        return self._lmcache_chunk_size
+
+    @torch.no_grad()
+    def _global_min_tokens(self, local_tokens: int) -> int:
+        if self.tp_size == 1:
+            return local_tokens
+        t = torch.tensor([local_tokens], dtype=torch.int32, device=self.device)
+        dist.all_reduce(t, op=dist.ReduceOp.MIN, group=self.tp_group)
+        return int(t.item())
+
+    def _create_key(
+        self,
+        token_ids: list[int],
+        start: int,
+        end: int,
+        request_id: str,
+        no_worker_id: bool = False,
+    ) -> IPCCacheServerKey:
+        return IPCCacheServerKey(
+            model_name=self.model_name,
+            world_size=self.tp_size,
+            worker_id=None if no_worker_id else self.worker_id,
+            token_ids=tuple(token_ids),
+            start=start,
+            end=end,
+            request_id=request_id,
+        )
+
+    def _slot_mapping_to_block_ids(self, slot_mapping: torch.Tensor) -> list[int]:
+        if slot_mapping.numel() == 0:
+            return []
+        if slot_mapping.numel() % self.page_size != 0:
+            raise ValueError(
+                "Slot mapping length must be page-aligned for MP mode, got "
+                f"{slot_mapping.numel()} and page_size={self.page_size}"
+            )
+        groups = (
+            slot_mapping.detach()
+            .to(dtype=torch.int64, device="cpu")
+            .reshape(-1, self.page_size)
+        )
+        starts = groups[:, 0]
+        if torch.any(starts % self.page_size != 0):
+            raise ValueError("Slot mapping does not start on page boundaries")
+        expected = starts[:, None] + torch.arange(self.page_size, dtype=torch.int64)
+        if not torch.equal(groups, expected):
+            raise ValueError("Slot mapping must cover full contiguous pages in MP mode")
+        return (starts // self.page_size).tolist()
+
+    def _wait_for_lookup(self, request_id: str) -> int:
+        """Wait for the LOOKUP's prefetch to finish and return the matched bytes.
+
+        Sends a single blocking WAIT_PREFETCH_STATUS request so the daemon
+        blocks until the prefetch result is published (or its wait times out),
+        instead of the client busy-polling QUERY_PREFETCH_STATUS. Upstream keys
+        the prefetch job by request_id (a string); the result is the number of
+        matched chunks once available.
+        """
+        # The daemon blocks up to ``self._mq_timeout`` for the result, so give
+        # the response itself a little longer than that to cover the round trip.
+        matched_chunks = send_lmcache_request(
+            self.mq_client,
+            RequestType.WAIT_PREFETCH_STATUS,
+            [request_id, self._mq_timeout],
+        ).result(timeout=self._mq_timeout + _WAIT_LOOKUP_RESPONSE_BUFFER_S)
+        if matched_chunks is None:
+            raise LMCacheTimeoutError(
+                "Timed out waiting for LMCache prefetch to finish",
+                session_id=request_id,
+            )
+        return matched_chunks * self._lmcache_chunk_size
+
+    def _free_lookup_locks(
+        self,
+        token_ids: list[int],
+        start: int,
+        end: int,
+        request_id: str,
+    ) -> None:
+        if start >= end or not self.is_healthy:
+            return
+        send_lmcache_request(
+            self.mq_client,
+            RequestType.FREE_LOOKUP_LOCKS,
+            [
+                self._create_key(
+                    token_ids,
+                    start=start,
+                    end=end,
+                    request_id=request_id,
+                    no_worker_id=True,
+                ),
+                self.tp_size,
+            ],
+        )
+
+    def lookup_kv(self, token_ids: list[int], request_id: str) -> int:
+        """Phase 1 of the two-phase load — fires LOOKUP only.
+
+        The daemon prefetches missing chunks L2 → L1 (DRAM), creates a
+        session keyed by ``request_id`` with ``lookup_ipc_key`` set,
+        and submits a prefetch task whose read locks stay held for the
+        eventual ``retrieve_kv``. Does **not** copy KV to GPU.
+
+        Idempotent across re-scheduling passes for the same
+        ``request_id``: a prior pending LOOKUP for the same rid has
+        its read locks released before the new LOOKUP fires, so locks
+        don't accumulate.
+
+        Returns the chunk-aligned matched-token count (0 if no
+        chunk-aligned hit, including the ``aligned_end == 0`` short-
+        prompt case).
+        """
+        if not self.is_healthy or not request_id:
+            return 0
+
+        # If a previous LOOKUP for this rid is still pending (e.g., a
+        # rescheduling pass or a prior partial flow), release its locks
+        # first so we don't accumulate read-lock reservations.
+        with self._pending_lookups_lock:
+            stale = self._pending_lookups.pop(request_id, None)
+        if stale is not None and stale.locks_held:
+            self._free_lookup_locks(
+                stale.token_ids, 0, stale.matched_token_num, request_id
+            )
+
+        aligned_end = (len(token_ids) // self._lmcache_chunk_size) * (
+            self._lmcache_chunk_size
+        )
+        if aligned_end == 0:
+            return 0  # too few tokens; no chunk-aligned range to LOOKUP
+
+        lookup_key = self._create_key(
+            token_ids,
+            start=0,
+            end=aligned_end,
+            request_id=request_id,
+            no_worker_id=True,
+        )
+        send_lmcache_request(
+            self.mq_client,
+            RequestType.LOOKUP,
+            [lookup_key, self.tp_size],
+        ).result(timeout=self._mq_timeout)
+        matched = self._wait_for_lookup(request_id)
+        matched = self._global_min_tokens(matched)
+
+        # Daemon now holds read locks for the matched chunks. Record
+        # state for the eventual retrieve_kv / release_pending /
+        # end_session call. Locks are released by exactly one of those.
+        with self._pending_lookups_lock:
+            self._pending_lookups[request_id] = _PendingLookup(
+                token_ids=list(token_ids),
+                matched_token_num=matched,
+                locks_held=matched > 0,
+            )
+        return matched
+
+    def release_pending(self, request_id: str) -> None:
+        """Free read locks acquired by ``lookup_kv`` when no ``retrieve_kv``
+        will follow (LMCache's hit is covered by radix). The pending entry
+        stays so ``end_session`` still sends END_SESSION.
+        """
+        with self._pending_lookups_lock:
+            pending = self._pending_lookups.get(request_id)
+            if pending is None or not pending.locks_held:
+                return
+            pending.locks_held = False
+            token_ids = pending.token_ids
+            matched = pending.matched_token_num
+        if matched > 0:
+            self._free_lookup_locks(token_ids, 0, matched, request_id)
+
+    def end_session(self, request_id: str) -> None:
+        """Tell the daemon we're done with this request_id.
+
+        Single per-request cleanup hook — owned by the engine's
+        request-finish path (e.g., :meth:`LMCRadixCache.cache_finished_req`),
+        not bundled into ``store_kv``. Skipped (no wire send) for ids
+        we never fired a LOOKUP for, so warmup and short-prompt
+        requests don't trigger the daemon's "Session not found,
+        skipping touch" warning. Frees any still-held read locks
+        before sending END_SESSION (covers failure paths where
+        retrieve_kv didn't consume the locks).
+        """
+        if not self.is_healthy:
+            return
+        with self._pending_lookups_lock:
+            pending = self._pending_lookups.pop(request_id, None)
+        if pending is None:
+            return
+        if pending.locks_held and pending.matched_token_num > 0:
+            self._free_lookup_locks(
+                pending.token_ids, 0, pending.matched_token_num, request_id
+            )
+        send_lmcache_request(self.mq_client, RequestType.END_SESSION, [request_id])
+
+    def _submit_retrieve(
+        self,
+        request_id: str,
+        token_ids: list[int],
+        offset: int,
+        matched_end: int,
+        block_ids: list[int],
+        skip_prefix_n_blocks: int = 0,
+    ):
+        event = torch_dev.Event(interprocess=True)
+        event.record(torch_dev.current_stream())
+        return send_lmcache_request(
+            self.mq_client,
+            RequestType.RETRIEVE,
+            [
+                self._create_key(
+                    token_ids,
+                    start=offset,
+                    end=matched_end,
+                    request_id=request_id,
+                ),
+                self.instance_id,
+                # RETRIEVE takes per-group block IDs (list[list[int]]); SGLang is
+                # non-hybrid, so wrap the flat list as a single group.
+                [block_ids],
+                event.ipc_handle(),
+                skip_prefix_n_blocks,
+            ],
+        ).to_cuda_future(device=self.device)
+
+    def retrieve_kv(self, load_metadata: LoadMetadata) -> int:
+        """Phase 2 of the two-phase load — fires RETRIEVE only.
+
+        Reuses the matched-token count cached by a prior ``lookup_kv``
+        for the same ``request_id`` (no second LOOKUP wire call). The
+        daemon's RETRIEVE handler copies L1 (DRAM) → GPU KV pool slots
+        in a single ``multi_layer_block_kv_transfer`` launch and
+        consumes the held read locks via ``finish_read_prefetched`` —
+        we don't separately free them on the success path.
+
+        Failure paths free the still-held trailing read locks
+        explicitly to avoid leaking them in the daemon.
+
+        Returns ``matched - offset`` (tokens covered by the chunks
+        whose RETRIEVE was issued, equivalent to the legacy
+        ``start_load_kv`` return). Caller subtracts ``prefix_pad`` to
+        compute "newly added to radix".
+        """
+        if not self.is_healthy:
+            return 0
+
+        request_id = load_metadata.request_id
+        with self._pending_lookups_lock:
+            pending = self._pending_lookups.get(request_id)
+        if pending is None or not pending.locks_held:
+            raise RuntimeError(
+                f"retrieve_kv called for {request_id} without a pending lookup_kv"
+            )
+
+        retrieve_token_num = pending.matched_token_num
+        token_ids = pending.token_ids
+        offset = load_metadata.offset
+
+        # ``slot_mapping[offset : offset + prefix_pad)`` is sentinel ``-1`` —
+        # those tokens already live in the engine's radix tree and must not
+        # be overwritten. We still RETRIEVE the full chunk-aligned range
+        # (LMCache stores at chunk granularity), but tell the daemon to skip
+        # the leading ``prefix_pad // page_size`` blocks. Real block_ids are
+        # computed only from the freshly-allocated slot range; the skipped
+        # blocks get harmless placeholder ids the kernel never dereferences.
+        prefix_pad = load_metadata.prefix_pad
+        fresh_start = offset + prefix_pad
+        prefix_pad_pages = prefix_pad // self.page_size
+
+        self._free_lookup_locks(token_ids, 0, offset, request_id)
+        fresh_block_ids = self._slot_mapping_to_block_ids(
+            load_metadata.slot_mapping[fresh_start:retrieve_token_num]
+        )
+        block_ids = [0] * prefix_pad_pages + fresh_block_ids
+
+        # Successful RETRIEVE releases the trailing read locks via
+        # ``finish_read_prefetched`` inside the daemon. The trailing
+        # ``_free_lookup_locks`` is the failure path's cleanup — calling
+        # it after a successful RETRIEVE would double-release and trigger
+        # "finish read on non-read-locked key".
+        retrieve_succeeded = False
+        try:
+            future = self._submit_retrieve(
+                request_id=request_id,
+                token_ids=token_ids,
+                offset=offset,
+                matched_end=retrieve_token_num,
+                block_ids=block_ids,
+                skip_prefix_n_blocks=prefix_pad_pages,
+            )
+            if not future.result(timeout=self._mq_timeout):
+                raise RuntimeError(
+                    f"LMCache MP retrieve failed for request_id={request_id}"
+                )
+            retrieve_succeeded = True
+        finally:
+            if not retrieve_succeeded:
+                self._free_lookup_locks(
+                    token_ids, offset, retrieve_token_num, request_id
+                )
+            with self._pending_lookups_lock:
+                if request_id in self._pending_lookups:
+                    self._pending_lookups[request_id].locks_held = False
+        return retrieve_token_num - offset
+
+    def store_kv(self, store_metadata: StoreMetadata) -> None:
+        if not self.is_healthy:
+            return
+
+        aligned_end = (len(store_metadata.token_ids) // self._lmcache_chunk_size) * (
+            self._lmcache_chunk_size
+        )
+        if aligned_end == 0:
+            return
+
+        request_id = store_metadata.request_id
+        block_ids = self._slot_mapping_to_block_ids(
+            store_metadata.kv_indices[:aligned_end]
+        )
+        event = torch_dev.Event(interprocess=True)
+        event.record(torch_dev.current_stream())
+        success = (
+            send_lmcache_request(
+                self.mq_client,
+                RequestType.STORE,
+                [
+                    self._create_key(
+                        store_metadata.token_ids,
+                        start=0,
+                        end=aligned_end,
+                        request_id=request_id,
+                    ),
+                    self.instance_id,
+                    # STORE takes per-group block IDs (list[list[int]]); SGLang is
+                    # non-hybrid, so wrap the flat list as a single group.
+                    [block_ids],
+                    event.ipc_handle(),
+                ],
+            )
+            .to_cuda_future(device=self.device)
+            .result(timeout=self._mq_timeout)
+        )
+        # END_SESSION is owned by ``LMCRadixCache.cache_finished_req`` so
+        # it fires once per request, even when STORE early-returns or no
+        # STORE was needed. See ``LMCacheMPConnector.end_session``.
+        if not success:
+            raise RuntimeError("LMCache MP store failed")
+
+    def reset(self) -> None:
+        pass
+
+    def close(self) -> None:
+        self.reset()
+        if self._heartbeat is not None:
+            self._heartbeat.stop()
+            self._heartbeat = None
+        if self._registered:
+            try:
+                send_lmcache_request(
+                    self.mq_client,
+                    RequestType.UNREGISTER_KV_CACHE,
+                    [self.instance_id],
+                ).result(timeout=self._mq_timeout)
+            except Exception:
+                logger.warning("Failed to unregister SGLang MP KV cache", exc_info=True)
+            self._registered = False
+        self.mq_client.close()
diff --git a/lmcache/integration/sglang/sglang_adapter.py b/lmcache/integration/sglang/sglang_adapter.py
new file mode 100644
index 0000000..2431b29
--- /dev/null
+++ b/lmcache/integration/sglang/sglang_adapter.py
@@ -0,0 +1,376 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import Any, Iterable, List, Optional
+import uuid
+
+# Third Party
+from sglang.srt.configs.model_config import ModelConfig
+import torch
+import torch.distributed as dist
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.integration.sglang.utils import ENGINE_NAME, lmcache_get_config
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    CacheStoreEvent,
+    EngineType,
+    mock_up_broadcast_fn,
+    mock_up_broadcast_object_fn,
+)
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector import CreateGPUConnector
+from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class StoreMetadata:
+    last_node: Any
+    token_ids: List[int]
+    kv_indices: torch.Tensor
+    offset: int
+    request_id: str = ""
+
+
+@dataclass
+class LoadMetadata:
+    token_ids: List[int]
+    slot_mapping: torch.Tensor
+    offset: int
+    prefix_pad: int = 0
+    request_id: str = ""
+
+
+def init_lmcache_engine(
+    model_config: ModelConfig,
+    tp_size: int,
+    local_rank: int,
+    global_rank: int,
+    kv_dtype: torch.dtype,
+    config_file: str,
+) -> LMCacheEngine:
+    """
+    Initialize LMCache engine for SGLang integration.
+
+    Args:
+        model_config: SGLang model configuration
+        tp_size: Tensor parallel size
+        local_rank: Local GPU device index (for device selection)
+        global_rank: Global tensor parallel rank (for metadata)
+        kv_dtype: Data type for KV cache tensors
+        config_file: Path to the LMCache YAML configuration file
+    """
+    if curr_engine := LMCacheEngineBuilder.get(ENGINE_NAME):
+        return curr_engine
+
+    config = lmcache_get_config(config_file)
+    assert isinstance(config, LMCacheEngineConfig), (
+        "LMCache v1 configuration is should be passed."
+    )
+
+    # construct kv shape (for mem pool)
+    num_layer = model_config.num_hidden_layers
+    chunk_size = config.chunk_size
+    num_kv_head = model_config.get_num_kv_heads(tp_size)
+    head_dim = model_config.head_dim
+
+    kv_shape = (num_layer, 2, chunk_size, num_kv_head, head_dim)
+
+    # Change current device using local GPU index
+    # Use global rank for metadata (tensor parallel rank)
+    metadata = LMCacheMetadata(
+        model_name=model_config.model_path,
+        world_size=tp_size,
+        local_world_size=tp_size,
+        worker_id=global_rank,
+        local_worker_id=local_rank,
+        kv_dtype=kv_dtype,
+        kv_shape=kv_shape,
+    )
+
+    gpu_connector = CreateGPUConnector(config, metadata, EngineType.SGLANG)
+    engine = LMCacheEngineBuilder.get_or_create(
+        ENGINE_NAME,
+        config,
+        metadata,
+        gpu_connector,
+        mock_up_broadcast_fn,
+        mock_up_broadcast_object_fn,
+    )
+
+    return engine
+
+
+class LMCacheConnector:
+    def __init__(
+        self,
+        sgl_config: ModelConfig,
+        tp_size: int,
+        rank: int,
+        k_pool: List[torch.Tensor],
+        v_pool: List[torch.Tensor],
+        config_file: str,
+    ):
+        if not k_pool:
+            raise ValueError("k_pool cannot be empty during initialization.")
+        kv_dtype = k_pool[0].dtype
+        if (
+            k_pool[0].device.type == torch_device_type
+            and k_pool[0].device.index is not None
+        ):
+            local_rank = k_pool[0].device.index
+        else:
+            # Fallback for CPU / odd cases
+            local_rank = rank
+
+        # rank is the global tensor parallel rank (tp_rank) from SGLang
+        # local_rank is the local GPU device index
+        self.lmcache_engine = init_lmcache_engine(
+            sgl_config,
+            tp_size,
+            local_rank,
+            rank,  # global_rank (tp_rank) for metadata
+            kv_dtype,
+            config_file,
+        )
+        self.sgl_config = sgl_config
+        self.tp_size = tp_size
+        self.rank = local_rank  # Use local_rank for torch.device() calls
+        self.kvcaches = k_pool + v_pool
+        self.num_layer = sgl_config.num_hidden_layers
+
+        self.lmcache_engine.post_init(kvcaches=self.kvcaches)
+
+    ####################
+    # Worker side APIs
+    ####################
+
+    def load_kv(self, load_metadata: LoadMetadata) -> int:
+        token_ids = torch.tensor(load_metadata.token_ids, dtype=torch.int64).to(
+            torch_device_type
+        )
+        slot_mapping = load_metadata.slot_mapping.to(torch_device_type)
+        offset = load_metadata.offset
+        if (len(token_ids) - offset) != len(slot_mapping):
+            raise ValueError(
+                "Length of token_ids (minus offset) must match slot_mapping length"
+            )
+        load_mask = torch.ones_like(token_ids, dtype=torch.bool)
+        load_mask[:offset] = False
+        ret_token_mask = self.lmcache_engine.retrieve(
+            token_ids,
+            mask=load_mask,
+            kvcaches=self.kvcaches,
+            slot_mapping=slot_mapping,
+            offset=offset,
+        )
+
+        num_retrieved_tokens = ret_token_mask.sum().item()
+
+        return num_retrieved_tokens
+
+    def store_kv(self, store_metadata: StoreMetadata) -> None:
+        token_ids = torch.tensor(store_metadata.token_ids, dtype=torch.int64).to(
+            torch_device_type
+        )
+        slot_mapping = store_metadata.kv_indices.to(torch.int64).to(torch_device_type)
+        offset = store_metadata.offset
+        if len(token_ids) != len(slot_mapping):
+            raise ValueError("Length of token_ids must match slot_mapping length")
+        store_mask = torch.ones_like(token_ids, dtype=torch.bool)
+
+        self.lmcache_engine.store(
+            token_ids,
+            mask=store_mask,
+            kvcaches=self.kvcaches,
+            slot_mapping=slot_mapping,
+            offset=offset,
+        )
+
+    def get_kv_events(self) -> Iterable[CacheStoreEvent]:
+        if self.lmcache_engine is not None:
+            return self.lmcache_engine.get_kv_events()
+        return []
+
+    def chunk_size(self):
+        return self.lmcache_engine.config.chunk_size
+
+    def reset(self):
+        self.lmcache_engine.clear()
+
+    def close(self):
+        self.lmcache_engine.close()
+
+
+class LMCacheLayerwiseConnector(LMCacheConnector):
+    def __init__(
+        self,
+        sgl_config: ModelConfig,
+        tp_size: int,
+        rank: int,
+        k_pool: List[torch.Tensor],
+        v_pool: List[torch.Tensor],
+        config_file: str,
+        tp_group: Optional[torch.distributed.ProcessGroup] = None,
+    ):
+        super().__init__(sgl_config, tp_size, rank, k_pool, v_pool, config_file)
+        self._lmcache_chunk_size = self.lmcache_engine.config.chunk_size
+        self.layerwise_retrievers: List[Any] = []
+        self.layer_load_layer: List[int] = []
+        self.kvcaches = [k_pool, v_pool]
+        self.tp_group = tp_group
+        self.lookup_id_list: List[str] = []
+
+    @torch.no_grad()
+    def global_min_tokens(
+        self, local_tokens: int, tp_group: dist.ProcessGroup, device: torch.device
+    ):
+        # If tensor parallel size is 1, no need for all_reduce
+        if self.tp_size == 1:
+            return local_tokens
+
+        t = torch.tensor([local_tokens], dtype=torch.int32, device=device)
+        dist.all_reduce(t, op=dist.ReduceOp.MIN, group=tp_group)
+        return int(t.item())
+
+    def load_kv_layerwise(self, layer_id: int) -> None:
+        if len(self.layerwise_retrievers) == 0:
+            return
+
+        indices_to_remove = []
+        for i in range(len(self.layerwise_retrievers)):
+            if self.layer_load_layer[i] == layer_id + 1:
+                next(self.layerwise_retrievers[i])
+                self.layer_load_layer[i] += 1
+                if self.layer_load_layer[i] == self.sgl_config.num_hidden_layers:
+                    indices_to_remove.append(i)
+
+        for i in sorted(indices_to_remove, reverse=True):
+            del self.layerwise_retrievers[i]
+            del self.layer_load_layer[i]
+            self.lmcache_engine.lookup_unpin(self.lookup_id_list[i])
+            del self.lookup_id_list[i]
+
+        return
+
+    def start_load_kv(self, load_metadata: LoadMetadata) -> int:
+        token_ids = torch.tensor(load_metadata.token_ids, dtype=torch.int64).to(
+            torch_device_type
+        )
+        slot_mapping = load_metadata.slot_mapping.to(torch_device_type)
+        offset = load_metadata.offset
+
+        assert self.lmcache_engine is not None
+
+        load_mask = torch.ones_like(token_ids, dtype=torch.bool)
+        load_mask[:offset] = False
+
+        lookup_id = str(uuid.uuid4())
+        retrieve_token_num = self.lmcache_engine.lookup(
+            token_ids,
+            lookup_id=lookup_id,
+            pin=True,
+        )
+
+        retrieve_token_num = self.global_min_tokens(
+            retrieve_token_num,
+            self.tp_group,
+            torch.device(f"{torch_device_type}:{self.rank}"),
+        )
+
+        # No new tokens to retrieve from LMCache
+        if retrieve_token_num <= offset:
+            self.lmcache_engine.lookup_unpin(lookup_id)
+            logger.info(
+                f"LMCache retrieve skipped: lookup={retrieve_token_num}, "
+                f"offset={offset}, no new tokens to retrieve"
+            )
+            return 0
+
+        layerwise_retriever = self.lmcache_engine.retrieve_layer(
+            token_ids[:retrieve_token_num],
+            mask=load_mask[:retrieve_token_num],
+            kvcaches=self.kvcaches,
+            slot_mapping=slot_mapping[:retrieve_token_num],
+            sync=False,
+        )
+
+        next(layerwise_retriever)
+        # Load First Layer
+        next(layerwise_retriever)
+
+        self.layerwise_retrievers.append(layerwise_retriever)
+        self.layer_load_layer.append(1)
+
+        self.lookup_id_list.append(lookup_id)
+
+        num_new_tokens = retrieve_token_num - offset
+        logger.info(
+            f"LMCache retrieve started: lookup={retrieve_token_num}, "
+            f"offset={offset}, retrieve {num_new_tokens} new tokens"
+        )
+
+        return num_new_tokens
+
+    def store_kv(self, store_metadata: StoreMetadata) -> None:
+        slot_mapping = store_metadata.kv_indices.to(torch.int64).to(torch_device_type)
+        token_ids = torch.tensor(store_metadata.token_ids, dtype=torch.int64).to(
+            torch_device_type
+        )
+        store_mask = torch.ones_like(token_ids, dtype=torch.bool)
+
+        logger.info(
+            f"LMCache store_kv started: tokens={len(token_ids)}, "
+            f"num_layers={self.sgl_config.num_hidden_layers}, "
+            f"offset={store_metadata.offset}"
+        )
+
+        lookup_id = str(uuid.uuid4())
+        try:
+            self.lmcache_engine.lookup(token_ids, lookup_id=lookup_id, pin=True)
+
+            layerwise_storer = self.lmcache_engine.store_layer(
+                token_ids,
+                mask=store_mask,
+                kvcaches=self.kvcaches,
+                slot_mapping=slot_mapping,
+                offset=store_metadata.offset,
+                sync=False,
+            )
+
+            # Initial next() to start the generator
+            try:
+                next(layerwise_storer)
+            except StopIteration:
+                logger.error(
+                    "store_layer generator stopped prematurely before layer loop"
+                )
+                return
+
+            # Iterate through each layer
+            for layer_idx in range(self.sgl_config.num_hidden_layers):
+                try:
+                    next(layerwise_storer)
+                except StopIteration:
+                    logger.error(
+                        (
+                            f"store_layer generator stopped at layer {layer_idx}/"
+                            f"{self.sgl_config.num_hidden_layers}"
+                        )
+                    )
+                    break
+
+            self.lmcache_engine.lookup_unpin(lookup_id)
+            logger.info(f"LMCache store_kv completed: stored {len(token_ids)} tokens")
+        except Exception as e:
+            logger.error(
+                f"LMCache store_kv failed: {type(e).__name__}: {e}", exc_info=True
+            )
+            try:
+                self.lmcache_engine.lookup_unpin(lookup_id)
+            except Exception as unpin_err:
+                logger.error(f"Failed to unpin lookup: {unpin_err}", exc_info=True)
diff --git a/lmcache/integration/sglang/utils.py b/lmcache/integration/sglang/utils.py
new file mode 100644
index 0000000..74ce08c
--- /dev/null
+++ b/lmcache/integration/sglang/utils.py
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+
+logger = init_logger(__name__)
+ENGINE_NAME = "sglang-instance"
+
+
+def is_false(value: str) -> bool:
+    """Check if the given string value is equivalent to 'false'."""
+    return value.lower() in ("false", "0", "no", "n", "off")
+
+
+def lmcache_get_config(config_file: str = "") -> LMCacheEngineConfig:
+    """Load the LMCache configuration.
+
+    Args:
+        config_file: Path to a YAML configuration file, or empty string
+            to build the config from ``LMCACHE_*`` environment variables.
+
+    Returns:
+        A validated ``LMCacheEngineConfig``.
+    """
+    if config_file:
+        logger.info(f"Loading LMCache config file {config_file}")
+        config = LMCacheEngineConfig.from_file(config_file)
+    else:
+        config = LMCacheEngineConfig.from_defaults()
+    config.validate()
+    return config
diff --git a/lmcache/integration/tensorrt_llm/__init__.py b/lmcache/integration/tensorrt_llm/__init__.py
new file mode 100644
index 0000000..7acf19c
--- /dev/null
+++ b/lmcache/integration/tensorrt_llm/__init__.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LMCache integration for NVIDIA TensorRT-LLM via the KV Cache Connector API.
+
+Two modes are supported:
+
+**In-process mode** (``lmcache``)
+    The LMCache engine runs inside the TRT-LLM process. Simple to set
+    up; no extra services required.
+
+    .. code-block:: yaml
+
+       kv_connector_config:
+         connector: lmcache
+
+**Multi-process mode** (``lmcache-mp``)
+    The LMCache engine runs as a standalone ZMQ server, providing
+    process isolation and shared KV caching across multiple TRT-LLM
+    instances on the same node.
+
+    1. Start the LMCache server::
+
+        python -m lmcache.v1.multiprocess.server \\
+            --host 0.0.0.0 --port 5555 \\
+            --l1-size-gb 10 --eviction-policy LRU --max-workers 4
+
+    2. Use the ``lmcache-mp`` preset with ``server_url``::
+
+        kv_connector_config:
+          connector: lmcache-mp
+          server_url: tcp://localhost:5555
+
+Both modes can also be configured explicitly instead of via presets::
+
+    # In-process
+    kv_connector_config:
+      connector_module: lmcache.integration.tensorrt_llm.tensorrt_adapter
+      connector_scheduler_class: LMCacheKvConnectorScheduler
+      connector_worker_class: LMCacheKvConnectorWorker
+
+    # Multi-process
+    kv_connector_config:
+      connector_module: lmcache.integration.tensorrt_llm.tensorrt_mp_adapter
+      connector_scheduler_class: LMCacheMPKvConnectorScheduler
+      connector_worker_class: LMCacheMPKvConnectorWorker
+"""
+
+# tensorrt_llm is an optional dependency. Guard the import so importing
+# ``lmcache.integration.tensorrt_llm`` does not crash when the package
+# is absent (e.g. core LMCache unit tests, doc builds).
+try:
+    # First Party
+    from lmcache.integration.tensorrt_llm.tensorrt_adapter import (
+        LMCacheKvConnectorScheduler,
+        LMCacheKvConnectorWorker,
+        destroy_engine,
+    )
+
+    __all__ = [
+        "LMCacheKvConnectorScheduler",
+        "LMCacheKvConnectorWorker",
+        "destroy_engine",
+    ]
+except ImportError:
+    __all__ = []
+
+try:
+    # First Party
+    from lmcache.integration.tensorrt_llm.tensorrt_mp_adapter import (
+        LMCacheMPKvConnectorScheduler,
+        LMCacheMPKvConnectorWorker,
+    )
+
+    __all__ += [
+        "LMCacheMPKvConnectorScheduler",
+        "LMCacheMPKvConnectorWorker",
+    ]
+except ImportError:
+    pass
diff --git a/lmcache/integration/tensorrt_llm/tensorrt_adapter.py b/lmcache/integration/tensorrt_llm/tensorrt_adapter.py
new file mode 100644
index 0000000..2a07dcd
--- /dev/null
+++ b/lmcache/integration/tensorrt_llm/tensorrt_adapter.py
@@ -0,0 +1,377 @@
+# SPDX-License-Identifier: Apache-2.0
+"""TensorRT-LLM KV Cache Connector adapter for LMCache (in-process mode).
+
+Implements ``LMCacheKvConnectorScheduler`` and ``LMCacheKvConnectorWorker`` —
+the two classes TRT-LLM's ``kv_connector_config`` requires — backed by
+an in-process LMCache engine singleton.
+
+Lifecycle (per TRT-LLM connector ABC):
+    * scheduler.get_num_new_matched_tokens → engine.lookup(tokens)
+    * scheduler.build_connector_meta → LMCacheConnectorMetadata(loads, saves)
+    * worker.register_kv_caches → builds engine via _get_or_create_engine,
+      calls gpu_connector.register_kv_caches(kv_cache_tensor)
+    * worker.start_load_kv → engine.retrieve(tokens, block_ids)
+    * worker.wait_for_save → engine.store(tokens, block_ids)
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+import time
+
+# Third Party
+from tensorrt_llm._torch.pyexecutor.connectors.kv_cache_connector import (
+    KvCacheConnectorScheduler,
+    KvCacheConnectorWorker,
+    SchedulerOutput,
+)
+from tensorrt_llm.bindings.internal.batch_manager import LlmRequest
+from tensorrt_llm.llmapi.llm_args import TorchLlmArgs
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.tensorrt_llm.utils import (
+    ENGINE_NAME,
+    create_trtllm_metadata,
+    lmcache_get_config,
+)
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType, mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.gpu_connector import CreateGPUConnector
+
+logger = init_logger(__name__)
+
+
+def _get_or_create_engine(
+    llm_args: TorchLlmArgs,
+    kv_cache_tensor: torch.Tensor,
+) -> LMCacheEngine:
+    """Return the LMCache engine singleton, creating it on first call.
+
+    Called by the worker's ``register_kv_caches``. On subsequent calls
+    (e.g. after a model reload) the existing engine is reused and the
+    GPU connector is re-registered with the new KV tensor.
+    """
+    existing = LMCacheEngineBuilder.get(ENGINE_NAME)
+    if existing is not None:
+        gpu_connector = existing.gpu_connector
+        if gpu_connector is not None:
+            gpu_connector.register_kv_caches(kv_cache_tensor)  # type: ignore[attr-defined]
+        logger.info("LMCache TRT-LLM: reusing existing engine")
+        return existing
+
+    config = lmcache_get_config()
+
+    # Third Party
+    from transformers import AutoConfig
+
+    hf_config = AutoConfig.from_pretrained(str(llm_args.model))
+    head_dim = getattr(
+        hf_config,
+        "head_dim",
+        hf_config.hidden_size // hf_config.num_attention_heads,
+    )
+    num_kv_heads = getattr(
+        hf_config, "num_key_value_heads", hf_config.num_attention_heads
+    )
+    num_kv_heads = num_kv_heads // llm_args.tensor_parallel_size
+
+    metadata = create_trtllm_metadata(
+        llm_args,
+        kv_cache_tensor,
+        config,
+        num_kv_heads=num_kv_heads,
+        head_dim=head_dim,
+    )
+    gpu_connector = CreateGPUConnector(config, metadata, EngineType.TRTLLM)
+    gpu_connector.register_kv_caches(kv_cache_tensor)  # type: ignore[attr-defined]
+
+    engine = LMCacheEngineBuilder.get_or_create(
+        ENGINE_NAME,
+        config,
+        metadata,
+        gpu_connector,
+        mock_up_broadcast_fn,
+        mock_up_broadcast_object_fn,
+    )
+    engine.post_init()
+
+    logger.info(
+        "LMCache TRT-LLM: created engine (chunk_size=%d, tensor_shape=%s, dtype=%s)",
+        config.chunk_size,
+        list(kv_cache_tensor.shape),
+        kv_cache_tensor.dtype,
+    )
+    return engine
+
+
+def destroy_engine() -> None:
+    """Destroy the engine singleton. Safe to call if not created."""
+    if LMCacheEngineBuilder.get(ENGINE_NAME) is not None:
+        LMCacheEngineBuilder.destroy(ENGINE_NAME)
+        logger.info("LMCache TRT-LLM: engine destroyed")
+
+
+@dataclass
+class _BlockSpec:
+    """Tokens and block IDs for a single load or store operation."""
+
+    tokens: List[int]
+    block_ids: List[int]
+
+
+@dataclass
+class LMCacheConnectorMetadata:
+    """Metadata passed from the scheduler to the worker each forward step."""
+
+    loads: dict = field(default_factory=dict)
+    saves: dict = field(default_factory=dict)
+
+
+class LMCacheKvConnectorScheduler(KvCacheConnectorScheduler):
+    """Scheduler-side connector hook.
+
+    Queries the LMCache engine for cached token counts and emits
+    per-request load/save block specs for the worker to act on.
+    """
+
+    def __init__(self, llm_args: TorchLlmArgs) -> None:
+        super().__init__(llm_args)
+        self._block_size: int = self._llm_args.kv_cache_config.tokens_per_block
+        # request_id -> (all_tokens, num_matched) — set by
+        # get_num_new_matched_tokens, consumed by build_connector_meta.
+        self._pending: dict = {}
+        # Engine is created by the worker in register_kv_caches, which
+        # may run concurrently with scheduler init. Resolved lazily.
+        self._engine: Optional[LMCacheEngine] = None
+
+    def get_num_new_matched_tokens(
+        self,
+        request: LlmRequest,
+        num_computed_tokens: int,
+    ) -> Tuple[int, bool]:
+        """Return how many additional tokens LMCache can provide beyond
+        ``num_computed_tokens`` (which TRT-LLM matched via GPU block reuse).
+
+        Args:
+            request: The incoming request with its full token sequence.
+            num_computed_tokens: Tokens already matched on device
+                (block-aligned).
+
+        Returns:
+            ``(new_matched, is_async)``. ``is_async`` is always
+            ``False`` in this adapter.
+        """
+        t0 = time.perf_counter()
+
+        if not self._engine:
+            self._engine = LMCacheEngineBuilder.get(ENGINE_NAME)
+        if not self._engine:
+            self._pending[request.request_id] = ([], 0)
+            return 0, False
+
+        # TRT-LLM should always pass block-aligned positions.
+        if num_computed_tokens % self._block_size != 0:
+            self._pending[request.request_id] = ([], 0)
+            return 0, False
+
+        all_tokens = list(request.get_tokens(0))
+
+        max_block_aligned = (len(all_tokens) // self._block_size) * self._block_size
+        if num_computed_tokens >= max_block_aligned:
+            self._pending[request.request_id] = (all_tokens, 0)
+            logger.debug(
+                "LMCache TRT-LLM scheduler: req %d short-circuit "
+                "(TRT matched %d of %d block-aligned tokens) %.3fms",
+                request.request_id,
+                num_computed_tokens,
+                max_block_aligned,
+                (time.perf_counter() - t0) * 1000,
+            )
+            return 0, False
+
+        t1 = time.perf_counter()
+        cached_tokens = self._engine.lookup(tokens=all_tokens)
+        t2 = time.perf_counter()
+
+        new_matched = max(0, cached_tokens - num_computed_tokens)
+        new_matched = (new_matched // self._block_size) * self._block_size
+
+        self._pending[request.request_id] = (all_tokens, new_matched)
+
+        logger.debug(
+            "LMCache TRT-LLM scheduler: req %d lookup=%.3fms total=%.3fms "
+            "trt_matched=%d lmcache_cached=%d new_matched=%d",
+            request.request_id,
+            (t2 - t1) * 1000,
+            (time.perf_counter() - t0) * 1000,
+            num_computed_tokens,
+            cached_tokens,
+            new_matched,
+        )
+        return new_matched, False
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> LMCacheConnectorMetadata:
+        """Build per-request load/save specs from the pending lookup
+        results. The runtime binds the returned metadata to the worker
+        via ``bind_connector_meta`` before the forward pass starts.
+        """
+        meta = LMCacheConnectorMetadata()
+
+        for req in scheduler_output.new_requests:
+            if req.request_id not in self._pending:
+                continue
+
+            all_tokens, num_matched = self._pending[req.request_id]
+            block_ids: List[int] = list(req.new_block_ids)
+            num_computed_blocks = req.computed_position // self._block_size
+
+            if num_matched > 0:
+                meta.loads[req.request_id] = _BlockSpec(
+                    tokens=all_tokens, block_ids=block_ids
+                )
+
+            save_start = max(num_computed_blocks, num_matched // self._block_size)
+            num_full_new_blocks = len(req.new_tokens) // self._block_size
+            if (
+                save_start < len(block_ids)
+                and num_full_new_blocks > 0
+                and save_start < num_computed_blocks + num_full_new_blocks
+            ):
+                meta.saves[req.request_id] = _BlockSpec(
+                    tokens=all_tokens, block_ids=block_ids
+                )
+
+        self._pending.clear()
+        return meta
+
+    def request_finished(self, request: LlmRequest, cache_block_ids: List[int]) -> bool:
+        """Return whether async saving is in progress.
+
+        Always ``False`` — saves are synchronous in this adapter.
+        """
+        return False
+
+    def update_state_after_alloc(
+        self, request: LlmRequest, block_ids: List[int]
+    ) -> None:
+        """No-op — block IDs are captured in ``build_connector_meta``
+        from ``scheduler_output.new_requests``.
+        """
+        pass
+
+
+class LMCacheKvConnectorWorker(KvCacheConnectorWorker):
+    """Worker-side connector hook.
+
+    Performs GPU↔CPU KV transfers via the LMCache engine.
+    """
+
+    def __init__(self, llm_args: TorchLlmArgs) -> None:
+        super().__init__(llm_args)
+        self._block_size: int = self._llm_args.kv_cache_config.tokens_per_block
+        # Cached after register_kv_caches to avoid per-call singleton lookup.
+        self._engine: Optional[LMCacheEngine] = None
+        self._load_stream: Optional[torch_dev.Stream] = None
+        self._store_stream: Optional[torch_dev.Stream] = None
+
+    @property
+    def _meta(self) -> Optional[LMCacheConnectorMetadata]:
+        """Typed accessor for ``self._metadata`` set by the base class."""
+        return self._metadata  # type: ignore[return-value]
+
+    def register_kv_caches(self, kv_cache_tensor: torch.Tensor) -> None:
+        """Register the KV cache tensor and create the LMCache engine.
+
+        Called once by the runtime after KV cache allocation. Caches the
+        engine and its load/store streams for fast access on every step.
+        """
+        self._engine = _get_or_create_engine(
+            llm_args=self._llm_args,
+            kv_cache_tensor=kv_cache_tensor,
+        )
+        gpu_conn = self._engine.gpu_connector
+        if gpu_conn is not None:
+            self._load_stream = gpu_conn.load_stream  # type: ignore[attr-defined]
+            self._store_stream = gpu_conn.store_stream  # type: ignore[attr-defined]
+
+    def start_load_kv(self, stream: torch_dev.Stream) -> None:
+        """Load KV blocks from LMCache into the GPU paged cache.
+
+        Retrieves all pending blocks on the load stream, then syncs the
+        forward-pass stream against it. The cross-layer format loads
+        every layer in a single kernel — no per-layer overlap to exploit.
+        """
+        meta = self._meta
+        if meta is None or not meta.loads or self._engine is None:
+            return
+
+        t0 = time.perf_counter()
+        for spec in meta.loads.values():
+            if not spec.tokens or not spec.block_ids:
+                continue
+            self._engine.retrieve(tokens=spec.tokens, block_ids=spec.block_ids)
+
+        if self._load_stream is not None:
+            stream.wait_stream(self._load_stream)
+
+        logger.debug(
+            "LMCache TRT-LLM worker: start_load_kv retrieve=%.3fms num_loads=%d",
+            (time.perf_counter() - t0) * 1000,
+            len(meta.loads),
+        )
+
+    def wait_for_layer_load(self, layer_idx: int, stream: torch_dev.Stream) -> None:
+        """No-op — cross-layer loads complete in :meth:`start_load_kv`."""
+        pass
+
+    def save_kv_layer(self, layer_idx: int, stream: torch_dev.Stream) -> None:
+        """No-op — saves are batched in :meth:`wait_for_save`."""
+        pass
+
+    def wait_for_save(self, stream: torch_dev.Stream) -> None:
+        """Store newly computed KV blocks from GPU to LMCache's CPU cache.
+
+        Waits on the forward-pass stream, runs ``engine.store`` for each
+        request with new blocks, and synchronizes the store stream
+        before returning.
+        """
+        meta = self._meta
+        if meta is None or not meta.saves or self._engine is None:
+            return
+
+        t0 = time.perf_counter()
+        if self._store_stream is not None:
+            self._store_stream.wait_stream(stream)
+        t1 = time.perf_counter()
+
+        for spec in meta.saves.values():
+            if not spec.tokens or not spec.block_ids:
+                continue
+            self._engine.store(tokens=spec.tokens, block_ids=spec.block_ids)
+        t2 = time.perf_counter()
+
+        if self._store_stream is not None:
+            self._store_stream.synchronize()
+        t3 = time.perf_counter()
+
+        logger.debug(
+            "LMCache TRT-LLM worker: wait_for_save stream_wait=%.3fms "
+            "store=%.3fms sync=%.3fms num_saves=%d",
+            (t1 - t0) * 1000,
+            (t2 - t1) * 1000,
+            (t3 - t2) * 1000,
+            len(meta.saves),
+        )
+
+    def get_finished(
+        self,
+        finished_gen_req_ids: List[int],
+        started_loading_req_ids: List[int],
+    ) -> Tuple[List[int], List[int]]:
+        """All ops are synchronous here — nothing is ever pending."""
+        return [], []
diff --git a/lmcache/integration/tensorrt_llm/tensorrt_mp_adapter.py b/lmcache/integration/tensorrt_llm/tensorrt_mp_adapter.py
new file mode 100644
index 0000000..4fd8992
--- /dev/null
+++ b/lmcache/integration/tensorrt_llm/tensorrt_mp_adapter.py
@@ -0,0 +1,488 @@
+# SPDX-License-Identifier: Apache-2.0
+"""TensorRT-LLM KV Cache Connector adapter for LMCache (multi-process mode).
+
+Implements ``LMCacheMPKvConnectorScheduler`` and
+``LMCacheMPKvConnectorWorker`` — the two classes TRT-LLM's
+``kv_connector_config`` requires — backed by a standalone LMCache server
+reached over ZMQ. Provides process isolation and shared caching across
+multiple TRT-LLM instances on the same node.
+
+The KV pool tensor is shared with the server via :class:`RawCudaIPCWrapper`
+because TRT-LLM's pool is allocated outside PyTorch's caching allocator
+(``at::for_blob`` over ``cudaMalloc``), which makes
+``UntypedStorage._share_cuda_()`` raise. The wrapper bypasses that path.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+import os
+import time
+
+# Third Party
+from tensorrt_llm._torch.pyexecutor.connectors.kv_cache_connector import (
+    KvCacheConnectorScheduler,
+    KvCacheConnectorWorker,
+    SchedulerOutput,
+)
+from tensorrt_llm.bindings.internal.batch_manager import LlmRequest
+from tensorrt_llm.llmapi.llm_args import TorchLlmArgs
+import torch
+import zmq
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType, check_interprocess_event_support
+from lmcache.v1.multiprocess.custom_types import (
+    IPCCacheServerKey,
+)
+from lmcache.v1.multiprocess.mq import MessageQueueClient, MessagingFuture
+from lmcache.v1.multiprocess.protocol import RequestType, get_response_class
+from lmcache.v1.platform.cuda.ipc_wrapper import RawCudaIPCWrapper
+
+logger = init_logger(__name__)
+
+DEFAULT_SERVER_URL = "ipc:///tmp/lmcache.sock"
+DEFAULT_MQ_TIMEOUT: float = 300.0
+
+
+def _get_server_url(llm_args: "TorchLlmArgs") -> str:
+    """Resolve the server URL: connector-config field > env var > default."""
+    cfg = llm_args.kv_connector_config
+    if cfg is not None and cfg.server_url is not None:
+        return cfg.server_url
+    return os.environ.get("LMCACHE_SERVER_URL", DEFAULT_SERVER_URL)
+
+
+def _send_request(
+    mq_client: MessageQueueClient,
+    request_type: RequestType,
+    payloads: list,
+) -> MessagingFuture:
+    return mq_client.submit_request(
+        request_type, payloads, get_response_class(request_type)
+    )
+
+
+@dataclass
+class _BlockSpec:
+    tokens: List[int]
+    block_ids: List[int]
+
+
+@dataclass
+class LMCacheMPConnectorMetadata:
+    loads: dict = field(default_factory=dict)
+    saves: dict = field(default_factory=dict)
+
+
+class LMCacheMPKvConnectorScheduler(KvCacheConnectorScheduler):
+    """TRT-LLM scheduler that routes lookup requests to an LMCache MP server."""
+
+    def __init__(self, llm_args: TorchLlmArgs) -> None:
+        super().__init__(llm_args)
+        self._block_size: int = self._llm_args.kv_cache_config.tokens_per_block
+        # request_id -> (all_tokens, num_matched).
+        self._pending: dict = {}
+
+        self._zmq_context = zmq.Context()
+        self._mq_client = MessageQueueClient(
+            _get_server_url(self._llm_args), self._zmq_context
+        )
+        self._mq_timeout = float(
+            os.environ.get("LMCACHE_MQ_TIMEOUT", DEFAULT_MQ_TIMEOUT)
+        )
+
+        future = _send_request(self._mq_client, RequestType.GET_CHUNK_SIZE, [])
+        self._chunk_size = future.result(timeout=self._mq_timeout)
+        logger.info(
+            "LMCache MP scheduler: connected to server at %s (chunk_size=%d)",
+            _get_server_url(self._llm_args),
+            self._chunk_size,
+        )
+
+        # Third Party
+        import tensorrt_llm
+
+        self._rank = tensorrt_llm.mpi_rank()
+        tp_size = llm_args.tensor_parallel_size
+        pp_size = llm_args.pipeline_parallel_size
+        self._world_size = tp_size * pp_size
+        self._model_name = str(getattr(llm_args, "model", "unknown_model"))
+
+    def _create_key(
+        self,
+        token_ids: List[int],
+        start: int,
+        end: int,
+        request_id: int,
+    ) -> IPCCacheServerKey:
+        return IPCCacheServerKey(
+            model_name=self._model_name,
+            world_size=self._world_size,
+            worker_id=None,
+            token_ids=tuple(token_ids),
+            start=start,
+            end=end,
+            request_id=str(request_id),
+        )
+
+    def get_num_new_matched_tokens(
+        self,
+        request: LlmRequest,
+        num_computed_tokens: int,
+    ) -> Tuple[int, bool]:
+        """Return how many additional tokens the LMCache server can provide.
+
+        Submits a ``LOOKUP`` to the server and queries
+        ``QUERY_PREFETCH_STATUS`` by ``request_id`` to read the result.
+        ``LOOKUP`` returns ``None`` on the server protocol — the prefetch
+        is tracked server-side keyed by ``request_id``.
+        """
+        t0 = time.perf_counter()
+
+        if num_computed_tokens % self._block_size != 0:
+            self._pending[request.request_id] = ([], 0)
+            return 0, False
+
+        all_tokens = list(request.get_tokens(0))
+
+        max_block_aligned = (len(all_tokens) // self._block_size) * self._block_size
+        if num_computed_tokens >= max_block_aligned:
+            self._pending[request.request_id] = (all_tokens, 0)
+            return 0, False
+
+        aligned_end = (len(all_tokens) // self._chunk_size) * self._chunk_size
+        key = self._create_key(
+            all_tokens, start=0, end=aligned_end, request_id=request.request_id
+        ).no_worker_id_version()
+
+        t1 = time.perf_counter()
+
+        try:
+            _send_request(self._mq_client, RequestType.LOOKUP, [key, 1]).result(
+                timeout=self._mq_timeout
+            )
+            result = _send_request(
+                self._mq_client,
+                RequestType.QUERY_PREFETCH_STATUS,
+                [str(request.request_id)],
+            ).result(timeout=self._mq_timeout)
+            cached_tokens = result * self._chunk_size if result is not None else 0
+        except Exception as e:
+            logger.warning("LMCache MP scheduler: lookup failed: %s", e)
+            self._pending[request.request_id] = (all_tokens, 0)
+            return 0, False
+
+        t2 = time.perf_counter()
+
+        new_matched = max(0, cached_tokens - num_computed_tokens)
+        new_matched = (new_matched // self._block_size) * self._block_size
+
+        # ``LOOKUP`` acquires read locks on chunks in [0, cached_tokens).
+        # TRT-LLM already has [0, num_computed_tokens), so those chunks
+        # will never be retrieved — release their locks (chunk-aligned)
+        # to avoid holding them until TTL expiry.
+        overlap_end = min(cached_tokens, num_computed_tokens)
+        overlap_end = (overlap_end // self._chunk_size) * self._chunk_size
+        if overlap_end > 0:
+            free_key = self._create_key(
+                all_tokens,
+                start=0,
+                end=overlap_end,
+                request_id=request.request_id,
+            ).no_worker_id_version()
+            try:
+                _send_request(
+                    self._mq_client,
+                    RequestType.FREE_LOOKUP_LOCKS,
+                    [free_key, 1],
+                )
+            except Exception as e:
+                logger.warning("LMCache MP scheduler: free_lookup_locks failed: %s", e)
+
+        self._pending[request.request_id] = (all_tokens, new_matched)
+
+        logger.debug(
+            "LMCache MP scheduler: req %d lookup=%.3fms total=%.3fms "
+            "trt_matched=%d lmcache_cached=%d new_matched=%d",
+            request.request_id,
+            (t2 - t1) * 1000,
+            (time.perf_counter() - t0) * 1000,
+            num_computed_tokens,
+            cached_tokens,
+            new_matched,
+        )
+        return new_matched, False
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> LMCacheMPConnectorMetadata:
+        """Build per-request load/save specs from pending lookup results."""
+        meta = LMCacheMPConnectorMetadata()
+
+        for req in scheduler_output.new_requests:
+            if req.request_id not in self._pending:
+                continue
+
+            all_tokens, num_matched = self._pending[req.request_id]
+            block_ids: List[int] = list(req.new_block_ids)
+            num_computed_blocks = req.computed_position // self._block_size
+
+            if num_matched > 0:
+                meta.loads[req.request_id] = _BlockSpec(
+                    tokens=all_tokens, block_ids=block_ids
+                )
+
+            save_start = max(num_computed_blocks, num_matched // self._block_size)
+            num_full_new_blocks = len(req.new_tokens) // self._block_size
+            if (
+                save_start < len(block_ids)
+                and num_full_new_blocks > 0
+                and save_start < num_computed_blocks + num_full_new_blocks
+            ):
+                meta.saves[req.request_id] = _BlockSpec(
+                    tokens=all_tokens, block_ids=block_ids
+                )
+
+        self._pending.clear()
+        return meta
+
+    def request_finished(self, request: LlmRequest, cache_block_ids: List[int]) -> bool:
+        """Notify the server so it can clean up per-request state.
+
+        Saves are synchronous in this adapter, so we never need to defer
+        deallocation — return ``False``. We still call ``END_SESSION`` to
+        release the server-side token-hash/session state for the request.
+        """
+        try:
+            _send_request(
+                self._mq_client,
+                RequestType.END_SESSION,
+                [str(request.request_id)],
+            )
+        except Exception as e:
+            logger.warning("LMCache MP scheduler: end_session failed: %s", e)
+        return False
+
+    def update_state_after_alloc(
+        self, request: LlmRequest, block_ids: List[int]
+    ) -> None:
+        """No-op — block IDs are captured in :meth:`build_connector_meta`."""
+        pass
+
+
+class LMCacheMPKvConnectorWorker(KvCacheConnectorWorker):
+    """TRT-LLM worker that routes store/retrieve to an LMCache MP server."""
+
+    def __init__(self, llm_args: TorchLlmArgs) -> None:
+        super().__init__(llm_args)
+        self._block_size: int = self._llm_args.kv_cache_config.tokens_per_block
+
+        self._zmq_context = zmq.Context()
+        self._mq_client = MessageQueueClient(
+            _get_server_url(self._llm_args), self._zmq_context
+        )
+        self._mq_timeout = float(
+            os.environ.get("LMCACHE_MQ_TIMEOUT", DEFAULT_MQ_TIMEOUT)
+        )
+
+        self._instance_id = os.getpid()
+        self._registered = False
+
+        # Third Party
+        import tensorrt_llm
+
+        self._rank = tensorrt_llm.mpi_rank()
+        tp_size = llm_args.tensor_parallel_size
+        pp_size = llm_args.pipeline_parallel_size
+        self._world_size = tp_size * pp_size
+        self._model_name = str(getattr(llm_args, "model", "unknown_model"))
+
+        future = _send_request(self._mq_client, RequestType.GET_CHUNK_SIZE, [])
+        self._chunk_size = future.result(timeout=self._mq_timeout)
+
+    def _create_key(
+        self,
+        token_ids: List[int],
+        request_id: int,
+    ) -> IPCCacheServerKey:
+        aligned_end = (len(token_ids) // self._chunk_size) * self._chunk_size
+        return IPCCacheServerKey(
+            model_name=self._model_name,
+            world_size=self._world_size,
+            worker_id=self._rank,
+            token_ids=tuple(token_ids),
+            start=0,
+            end=aligned_end,
+            request_id=str(request_id),
+        )
+
+    def register_kv_caches(self, kv_cache_tensor: torch.Tensor) -> None:
+        """Register the KV pool with the LMCache server via raw CUDA IPC.
+
+        TRT-LLM provides a 4-D pool tensor
+        ``[NB, NL, 2, NH * BS * HS]``. The server reshapes it to 6-D
+        ``[NB, NL, 2, NH, BS, HS]`` from the ``layout_hints`` so format
+        detection lands on ``NB_NL_TWO_NH_BS_HS``.
+        """
+        if self._registered:
+            logger.info("LMCache MP worker: KV caches already registered")
+            return
+
+        # Third Party
+        from transformers import AutoConfig
+
+        hf_config = AutoConfig.from_pretrained(self._model_name)
+        head_dim = getattr(
+            hf_config,
+            "head_dim",
+            hf_config.hidden_size // hf_config.num_attention_heads,
+        )
+        num_kv_heads = getattr(
+            hf_config, "num_key_value_heads", hf_config.num_attention_heads
+        )
+        tp_size = self._llm_args.tensor_parallel_size
+        num_kv_heads = num_kv_heads // tp_size
+
+        _, _, _, block_size_flat = kv_cache_tensor.shape
+        tokens_per_block = block_size_flat // (num_kv_heads * head_dim)
+
+        wrapped = [RawCudaIPCWrapper(kv_cache_tensor)]
+
+        layout_hints = {
+            "kv_layout": "HND",
+            "num_kv_heads": num_kv_heads,
+            "tokens_per_block": tokens_per_block,
+            "head_dim": head_dim,
+        }
+
+        future = _send_request(
+            self._mq_client,
+            RequestType.REGISTER_KV_CACHE,
+            [
+                self._instance_id,
+                wrapped,
+                self._model_name,
+                self._world_size,
+                EngineType.TRTLLM,
+                layout_hints,
+                [],
+            ],
+        )
+        try:
+            future.result(timeout=self._mq_timeout)
+            self._registered = True
+            logger.info(
+                "LMCache MP worker: registered KV caches "
+                "(tensor_shape=%s, NH=%d, BS=%d, HS=%d)",
+                list(kv_cache_tensor.shape),
+                num_kv_heads,
+                tokens_per_block,
+                head_dim,
+            )
+        except TimeoutError:
+            logger.error(
+                "LMCache MP worker: KV cache registration timed out after %ss",
+                self._mq_timeout,
+            )
+
+    def start_load_kv(self, stream: torch_dev.Stream) -> None:
+        """Send ``RETRIEVE`` requests for each pending load."""
+        meta: Optional[LMCacheMPConnectorMetadata] = self._metadata
+        if meta is None or not meta.loads:
+            return
+
+        t0 = time.perf_counter()
+        # Not all backends support interprocess Events (CUDA IPC specific)
+        check_interprocess_event_support()
+        event = torch_dev.Event(interprocess=True)
+        event.record(stream)
+
+        for req_id, spec in meta.loads.items():
+            if not spec.tokens or not spec.block_ids:
+                continue
+
+            key = self._create_key(spec.tokens, req_id)
+            try:
+                _send_request(
+                    self._mq_client,
+                    RequestType.RETRIEVE,
+                    [
+                        key,
+                        self._instance_id,
+                        [spec.block_ids],
+                        event.ipc_handle(),
+                        0,  # skip_first_n_tokens
+                    ],
+                ).result(timeout=self._mq_timeout)
+            except Exception as e:
+                logger.warning(
+                    "LMCache MP worker: retrieve failed for req %d: %s",
+                    req_id,
+                    e,
+                )
+
+        logger.debug(
+            "LMCache MP worker: start_load_kv retrieve=%.3fms num_loads=%d",
+            (time.perf_counter() - t0) * 1000,
+            len(meta.loads),
+        )
+
+    def wait_for_layer_load(self, layer_idx: int, stream: torch_dev.Stream) -> None:
+        """No-op — server synchronizes via CUDA IPC events."""
+        pass
+
+    def save_kv_layer(self, layer_idx: int, stream: torch_dev.Stream) -> None:
+        """No-op — saves are batched in :meth:`wait_for_save`."""
+        pass
+
+    def wait_for_save(self, stream: torch_dev.Stream) -> None:
+        """Send ``STORE`` requests for each pending save."""
+        meta: Optional[LMCacheMPConnectorMetadata] = self._metadata
+        if meta is None or not meta.saves:
+            return
+
+        t0 = time.perf_counter()
+        # Not all backends support interprocess Events (CUDA IPC specific)
+        check_interprocess_event_support()
+        event = torch_dev.Event(interprocess=True)
+        event.record(stream)
+
+        for req_id, spec in meta.saves.items():
+            if not spec.tokens or not spec.block_ids:
+                continue
+
+            key = self._create_key(spec.tokens, req_id)
+            try:
+                _send_request(
+                    self._mq_client,
+                    RequestType.STORE,
+                    [
+                        key,
+                        self._instance_id,
+                        [spec.block_ids],
+                        event.ipc_handle(),
+                    ],
+                ).result(timeout=self._mq_timeout)
+            except Exception as e:
+                logger.warning(
+                    "LMCache MP worker: store failed for req %d: %s",
+                    req_id,
+                    e,
+                )
+
+        logger.debug(
+            "LMCache MP worker: wait_for_save store=%.3fms num_saves=%d",
+            (time.perf_counter() - t0) * 1000,
+            len(meta.saves),
+        )
+
+    def get_finished(
+        self,
+        finished_gen_req_ids: List[int],
+        started_loading_req_ids: List[int],
+    ) -> Tuple[List[int], List[int]]:
+        """All operations are synchronous — nothing is ever pending."""
+        return [], []
diff --git a/lmcache/integration/tensorrt_llm/utils.py b/lmcache/integration/tensorrt_llm/utils.py
new file mode 100644
index 0000000..8d6eb43
--- /dev/null
+++ b/lmcache/integration/tensorrt_llm/utils.py
@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Utility helpers for the TensorRT-LLM integration."""
+
+# Standard
+from typing import TYPE_CHECKING
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+
+if TYPE_CHECKING:
+    # Third Party
+    from tensorrt_llm.llmapi.llm_args import TorchLlmArgs
+
+logger = init_logger(__name__)
+
+ENGINE_NAME = "trtllm-instance"
+
+
+def lmcache_get_config() -> LMCacheEngineConfig:
+    """Return an LMCacheEngineConfig from ``LMCACHE_CONFIG_FILE`` or env.
+
+    Mirrors the in-process pattern used by the vLLM adapter: prefer a
+    config file if the env var is set; otherwise pull from individual
+    ``LMCACHE_*`` environment variables.
+    """
+    if "LMCACHE_CONFIG_FILE" not in os.environ:
+        logger.warning(
+            "No LMCache configuration file is set. Trying to read"
+            " configurations from the environment variables."
+        )
+        logger.warning(
+            "You can set the configuration file through "
+            "the environment variable: LMCACHE_CONFIG_FILE"
+        )
+        config = LMCacheEngineConfig.from_env()
+    else:
+        config_file = os.environ["LMCACHE_CONFIG_FILE"]
+        logger.info("Loading LMCache config file %s", config_file)
+        config = LMCacheEngineConfig.from_file(config_file)
+
+    return config
+
+
+def create_trtllm_metadata(
+    llm_args: "TorchLlmArgs",
+    kv_cache_tensor: torch.Tensor,
+    config: LMCacheEngineConfig,
+    num_kv_heads: int,
+    head_dim: int,
+) -> LMCacheMetadata:
+    """Construct LMCacheMetadata from TRT-LLM args and the KV pool tensor.
+
+    Args:
+        llm_args: TRT-LLM ``TorchLlmArgs``.
+        kv_cache_tensor: TRT-LLM KV pool tensor of shape
+            ``[num_blocks, num_layers, kv_factor, flat]`` where
+            ``flat = num_kv_heads * tokens_per_block * head_dim``.
+        config: The LMCache engine config (used for ``chunk_size``).
+        num_kv_heads: Per-rank number of KV attention heads.
+        head_dim: Per-head dimension.
+
+    Returns:
+        Populated :class:`LMCacheMetadata`.
+    """
+    # Third Party
+    import tensorrt_llm
+
+    _, num_layers, kv_factor, _ = kv_cache_tensor.shape
+    kv_shape = (num_layers, kv_factor, config.chunk_size, num_kv_heads, head_dim)
+
+    rank = tensorrt_llm.mpi_rank()
+    tp_size = llm_args.tensor_parallel_size
+    pp_size = llm_args.pipeline_parallel_size
+    world_size = tp_size * pp_size
+    local_world_size = tp_size
+    local_worker_id = rank % local_world_size
+    model_name = str(getattr(llm_args, "model", "unknown_model"))
+
+    return LMCacheMetadata(
+        model_name=model_name,
+        world_size=world_size,
+        local_world_size=local_world_size,
+        worker_id=rank,
+        local_worker_id=local_worker_id,
+        kv_dtype=kv_cache_tensor.dtype,
+        kv_shape=kv_shape,
+        chunk_size=config.chunk_size,
+    )
diff --git a/lmcache/integration/vllm/__init__.py b/lmcache/integration/vllm/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/integration/vllm/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/integration/vllm/kv_cache_group_edits.py b/lmcache/integration/vllm/kv_cache_group_edits.py
new file mode 100644
index 0000000..c8feb86
--- /dev/null
+++ b/lmcache/integration/vllm/kv_cache_group_edits.py
@@ -0,0 +1,402 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Centralized edits to vLLM kv cache specs.
+
+This is needed to mask out attention-specific details while making sure that
+LMCache can still store / load KV cache correctly.
+
+Currently there are two edits, one per :class:`KVCacheGroupEdit` subclass
+below. Both are for Mamba-hybrid models; the registry is only consulted when
+``kv_cache_config.has_mamba_layers``. :func:`validate_kv_cache_groups`
+additionally rejects, at startup, group specs the transfer path cannot serve
+correctly yet (see its docstring).
+
+Reference design: vLLM PR #42828 ("[KVConnector][DSV4] HMA support for
+Mooncake store connector") solves the same problem class for an external KV
+store. Check it again when working on any of the following:
+
+- Extending :func:`validate_kv_cache_groups` (its connector validates and
+  rejects unsupported specs up front, with one aggregated error).
+- Per-group store/load masks (SWA / Mamba tail-only transfer, the
+  "sliding-window load-plan trimming" deferred in the hybrid design doc):
+  its ``MooncakeStoreCoordinator.store_mask`` / ``load_mask`` derive masks
+  from vLLM's own per-spec managers. Requires per-group objects in LMCache
+  (``ObjectKey.object_group_id``, LMCache #3608).
+- Hit-length computation for hybrid models: its ``ExternalCachedBlockPool``
+  duck-types vLLM's ``BlockPool`` over a ``(group_id, hash)`` existence set
+  and reuses ``KVCacheSpecRegistry`` manager classes, so promised hits are
+  consumable by construction. NOTE: LMCache's lookup doubles as prefetch, so
+  vLLM's lookup-first-then-trim flow does not map directly -- this needs its
+  own design before borrowing.
+- Eagle + HMA: see its ``apply_eagle`` notes (the eagle last-block prune must
+  be applied exactly once between hit-length and mask computation).
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from collections import Counter
+from collections.abc import Mapping
+from typing import TypeAlias
+
+# Third Party
+from vllm.v1.kv_cache_interface import (
+    KVCacheConfig,
+    KVCacheSpec,
+    KVCacheSpecKind,
+    get_kv_cache_spec_kind,
+)
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# One registered cache value: a paged KV tensor, or [conv_state, ssm_state]
+# for Mamba layers.
+RegisteredKVCache: TypeAlias = torch.Tensor | list[torch.Tensor]
+
+# Synthetic head count for a reinterpreted page. The page is opaque bytes, so
+# one "head" holding the whole per-(K/V) slab is enough; head_size is derived
+# to fill the page.
+_SYNTHETIC_NUM_HEADS = 1
+
+# Standard-paged (non-MLA) attention kinds eligible for the sub-paged edit.
+_SUBPAGEABLE_ATTENTION_KINDS = frozenset(
+    {
+        KVCacheSpecKind.FULL_ATTENTION,
+        KVCacheSpecKind.SLIDING_WINDOW,
+        KVCacheSpecKind.CHUNKED_LOCAL_ATTENTION,
+        KVCacheSpecKind.SINK_FULL_ATTENTION,
+    }
+)
+
+
+def _declares_slot_compression(spec: KVCacheSpec) -> bool:
+    """Return whether a spec declares slot compression (must not be edited).
+
+    Covers ``MLAAttentionSpec.compress_ratio > 1`` (DeepSeek-V4 slot packing)
+    and ``TQFullAttentionSpec.tq_slot_size > 0`` (TurboQuant slots); such
+    groups belong to the compression path in ``lmcache.v1.kv_layer_groups``.
+    """
+    return (
+        getattr(spec, "compress_ratio", 1) > 1 or getattr(spec, "tq_slot_size", 0) > 0
+    )
+
+
+def _leaf_specs(spec: KVCacheSpec) -> list[KVCacheSpec]:
+    """Return a group spec's leaf specs, unwrapping ``UniformTypeKVCacheSpecs``."""
+    inner = getattr(spec, "kv_cache_specs", None)
+    if isinstance(inner, dict):
+        return list(inner.values())
+    return [spec]
+
+
+def validate_kv_cache_groups(kv_cache_config: KVCacheConfig | None) -> None:
+    """Reject KV cache group specs the transfer path cannot serve correctly.
+
+    Rejected, with one aggregated error listing every offending group:
+
+    - ``CrossAttentionSpec`` (encoder-decoder caches).
+    - Mamba groups with ``mamba_cache_mode != "align"``: other modes keep no
+      reusable per-block state snapshots.
+
+    Specs declaring slot compression (``compress_ratio > 1`` /
+    ``tq_slot_size > 0``, e.g. DeepSeek-V4) are NOT rejected: they are served
+    by the compression path in ``lmcache.v1.kv_layer_groups`` and merely
+    skipped by the edits here (see ``_declares_slot_compression``).
+
+    Args:
+        kv_cache_config: vLLM ``KVCacheConfig``; ``None`` skips validation
+            (callers without the config validate again at registration).
+
+    Raises:
+        ValueError: Listing every unsupported group and why.
+    """
+    if kv_cache_config is None:
+        return
+    unsupported: list[str] = []
+    for group_idx, group in enumerate(kv_cache_config.kv_cache_groups):
+        for spec in _leaf_specs(group.kv_cache_spec):
+            kind = get_kv_cache_spec_kind(spec)
+            if kind == KVCacheSpecKind.CROSS_ATTENTION:
+                unsupported.append(f"group {group_idx}: CrossAttentionSpec")
+            elif (
+                kind == KVCacheSpecKind.MAMBA
+                and getattr(spec, "mamba_cache_mode", "none") != "align"
+            ):
+                unsupported.append(
+                    f"group {group_idx}: MambaSpec with mamba_cache_mode="
+                    f"'{getattr(spec, 'mamba_cache_mode', 'none')}' "
+                    f"(only 'align' keeps reusable state snapshots)"
+                )
+    if unsupported:
+        raise ValueError(
+            "LMCache cannot serve this model's KV cache groups: "
+            + "; ".join(unsupported)
+            + ". See lmcache/integration/vllm/kv_cache_group_edits.py."
+        )
+
+
+def _synthetic_attention_shape(elems_per_page: int, block_size: int) -> tuple[int, int]:
+    """Factor a page's element count into the synthetic attention layout.
+
+    Args:
+        elems_per_page: Total elements in one page (one logical block).
+        block_size: Logical block size (tokens per page).
+
+    Returns:
+        ``(num_heads, head_size)`` such that
+        ``2 * block_size * num_heads * head_size == elems_per_page``.
+
+    Raises:
+        ValueError: If the page size does not factor into the target shape.
+    """
+    denom = 2 * block_size * _SYNTHETIC_NUM_HEADS
+    if elems_per_page % denom != 0:
+        raise ValueError(
+            f"page ({elems_per_page} elems) does not factor into "
+            f"(2, block_size={block_size}, num_heads={_SYNTHETIC_NUM_HEADS}, head_size)"
+        )
+    return _SYNTHETIC_NUM_HEADS, elems_per_page // denom
+
+
+class KVCacheGroupEdit(ABC):
+    """One structural edit rule for a KV cache group's registered cache.
+
+    ``matches`` must be side-effect free and decide purely from the vLLM spec
+    and the registered cache value; ``apply`` must return a view over the same
+    storage (never a copy). ``name`` labels the rule in logs.
+    """
+
+    name: str
+
+    @abstractmethod
+    def matches(self, spec: KVCacheSpec, kv_cache: RegisteredKVCache) -> bool:
+        """Return whether this rule applies to the layer's registered cache.
+
+        Args:
+            spec: The layer's vLLM KV cache spec (from its group).
+            kv_cache: The layer's registered cache value -- a tensor, or a
+                list of tensors for Mamba layers.
+        """
+
+    @abstractmethod
+    def apply(self, spec: KVCacheSpec, kv_cache: RegisteredKVCache) -> torch.Tensor:
+        """Return the edited view for a layer this rule matched.
+
+        Args:
+            spec: The layer's vLLM KV cache spec (from its group).
+            kv_cache: The layer's registered cache value.
+
+        Raises:
+            ValueError: If the cache's layout violates the rule's invariants.
+        """
+
+
+class _MambaPageViewEdit(KVCacheGroupEdit):
+    """Convert a Mamba page to its equivalent: a sliding-window-style layer.
+
+    A Mamba layer registers ``[conv_state, ssm_state]`` -- two tensors with
+    different shapes and dtypes sharing one padded page per block
+    (``conv | ssm | pad``) -- which LMCache's attention-shaped transfer path
+    cannot represent. Each page is one recurrent state snapshot, equivalent
+    for caching purposes to one block of a sliding-window attention layer with
+    window == block_size: only the last matched block is ever consumed. The
+    edit reinterprets the page buffer as one
+    ``[#blocks, 2, block_size, 1, head_size]`` tensor in the conv state's
+    dtype, with ``head_size`` derived to fill the page exactly.
+
+    The view's dims are addressing metadata only; the bytes are opaque
+    (conv | ssm | pad, not K/V), so content-aware processing does not apply.
+    """
+
+    name = "mamba-page-view"
+
+    def matches(self, spec: KVCacheSpec, kv_cache: RegisteredKVCache) -> bool:
+        return get_kv_cache_spec_kind(spec) == KVCacheSpecKind.MAMBA
+
+    def apply(self, spec: KVCacheSpec, kv_cache: RegisteredKVCache) -> torch.Tensor:
+        # vLLM lays out one padded page per block as (conv | ssm | pad), and
+        # the conv state is the view that starts at the page base: its leading
+        # dim is the block count and its per-block stride is one full page.
+        # Re-striding it therefore covers the whole page, ssm and pad included.
+        if not isinstance(kv_cache, list) or not kv_cache:
+            raise ValueError(
+                f"expected a Mamba [conv_state, ssm_state] tensor list, "
+                f"got {type(kv_cache).__name__}"
+            )
+        conv_state = kv_cache[0]
+        if conv_state.storage_offset() != 0:
+            raise ValueError(
+                f"Mamba conv state must view the page base, got "
+                f"storage_offset={conv_state.storage_offset()}"
+            )
+        if conv_state.stride(0) * conv_state.element_size() != spec.page_size_bytes:
+            raise ValueError(
+                f"Mamba conv state per-block stride "
+                f"({conv_state.stride(0) * conv_state.element_size()} bytes) "
+                f"does not equal the page size ({spec.page_size_bytes} bytes)"
+            )
+        num_blocks = conv_state.shape[0]
+        elems_per_page = spec.page_size_bytes // conv_state.element_size()
+        num_heads, head_size = _synthetic_attention_shape(
+            elems_per_page, spec.block_size
+        )
+        flat = conv_state.as_strided((num_blocks, elems_per_page), (elems_per_page, 1))
+        return flat.reshape(num_blocks, 2, spec.block_size, num_heads, head_size)
+
+
+class _SubpagedAttentionViewEdit(KVCacheGroupEdit):
+    """Re-view a kernel-paged attention tensor as logical-block pages.
+
+    For a Mamba-hybrid model vLLM inflates the attention block size to align
+    with the Mamba page (e.g. 544 for Qwen3.5-0.8B), and that size is used for
+    all prefix-caching logic at the scheduler. But at the worker the attention
+    kernel has to run at block size 32 for numerical stability (vLLM #27753,
+    working around the NaN-propagation issue
+    Dao-AILab/flash-attention#1974), so the registered tensor is paged as
+
+        ``[#blocks, 2, 32, #heads, head_size]``
+
+    which makes LMCache detect block size 32, mistake the group for a
+    DeepSeek-compression layer (``block size < scheduler block size``), and
+    corrupt the store/retrieve. Fix: re-view the tensor at the scheduler
+    block size (one logical block = its 17 contiguous kernel pages),
+
+        ``[#blocks / 17, 2, 544, 1, head_size']``
+
+    Cost: before this fix ``kv_caches[:, 0]`` is just the K tensor; after, it
+    interleaves K and V at kernel-page granularity. The bytes round-trip
+    correctly (store and retrieve share the mapping), but the dims are no
+    longer semantic, so content-aware processing does not apply.
+    """
+
+    name = "subpaged-attention-view"
+
+    def matches(self, spec: KVCacheSpec, kv_cache: RegisteredKVCache) -> bool:
+        return (
+            # Standard-paged attention only; MLA layouts and declared slot
+            # compression (DeepSeek) belong to other transfer paths.
+            get_kv_cache_spec_kind(spec) in _SUBPAGEABLE_ATTENTION_KINDS
+            and not _declares_slot_compression(spec)
+            # (num_blocks, 2, block_size, num_heads, head_size) layout whose
+            # block dim disagrees with the scheduler block-id unit -- the
+            # backend re-paged the tensor at its kernel block size.
+            and isinstance(kv_cache, torch.Tensor)
+            and kv_cache.ndim == 5
+            and kv_cache.shape[2] != spec.block_size
+        )
+
+    def apply(self, spec: KVCacheSpec, kv_cache: RegisteredKVCache) -> torch.Tensor:
+        """Re-view ``kv_cache`` at logical-block granularity.
+
+        The tensor is kernel-paged as ``(num_kernel_pages, 2,
+        kernel_block_size, num_kv_heads, head_size)``; the result is
+        ``(num_logical_blocks, 2, spec.block_size, num_heads, head_size)``
+        over the same storage.
+
+        Raises:
+            ValueError: If the layout is not the expected kernel-paged shape,
+                the sizes do not divide evenly, or the kernel pages of one
+                logical block do not tile its page bytes exactly (which would
+                indicate an undeclared packed layout that must not be edited).
+        """
+        if not isinstance(kv_cache, torch.Tensor) or kv_cache.shape[1] != 2:
+            got = (
+                tuple(kv_cache.shape)
+                if isinstance(kv_cache, torch.Tensor)
+                else type(kv_cache).__name__
+            )
+            raise ValueError(
+                f"expected a (num_blocks, 2, block_size, num_heads, head_size) "
+                f"attention KV tensor, got {got}"
+            )
+        logical_block_size = spec.block_size
+        kernel_block_size = kv_cache.shape[2]
+        if logical_block_size % kernel_block_size != 0:
+            raise ValueError(
+                f"logical block size {logical_block_size} is not a multiple of "
+                f"kernel block size {kernel_block_size}"
+            )
+        ratio = logical_block_size // kernel_block_size
+
+        num_kernel_pages = kv_cache.shape[0]
+        if num_kernel_pages % ratio != 0:
+            raise ValueError(
+                f"kernel page count {num_kernel_pages} is not a multiple of "
+                f"the logical/kernel block ratio {ratio}"
+            )
+        kernel_page_bytes = kv_cache.shape[1:].numel() * kv_cache.element_size()
+        if kernel_page_bytes * ratio != spec.page_size_bytes:
+            raise ValueError(
+                f"{ratio} kernel pages ({kernel_page_bytes * ratio} bytes) do "
+                f"not tile the logical page ({spec.page_size_bytes} bytes)"
+            )
+        if not kv_cache.is_contiguous():
+            raise ValueError(
+                "kernel-paged attention KV tensor must be contiguous to "
+                "re-view as logical pages"
+            )
+
+        num_blocks = num_kernel_pages // ratio
+        elems_per_page = spec.page_size_bytes // kv_cache.element_size()
+        num_heads, head_size = _synthetic_attention_shape(
+            elems_per_page, logical_block_size
+        )
+        return kv_cache.view(num_blocks, 2, logical_block_size, num_heads, head_size)
+
+
+# Rule registry, in match priority order.
+_EDITS: tuple[KVCacheGroupEdit, ...] = (
+    _MambaPageViewEdit(),
+    _SubpagedAttentionViewEdit(),
+)
+
+
+def apply_kv_cache_group_edits(
+    kv_cache_config: KVCacheConfig | None,
+    kv_caches: Mapping[str, RegisteredKVCache],
+) -> dict[str, RegisteredKVCache]:
+    """Apply all KV cache group metadata edits for LMCache registration.
+
+    Each layer is checked against the ``_EDITS`` rules (first match wins) and
+    re-viewed by the matching rule; layers matching no rule pass through
+    unchanged. ``None`` configs and configs without Mamba groups are returned
+    as-is (as a dict): all current rules only apply to Mamba-hybrid models.
+
+    Args:
+        kv_cache_config: vLLM ``KVCacheConfig`` (read for per-group specs).
+        kv_caches: Registered tensors keyed by layer name. Mamba entries are
+            ``[conv_state, ssm_state]`` lists; others are single tensors.
+
+    Returns:
+        A new ``dict`` with edited layers re-viewed, others untouched.
+
+    Raises:
+        ValueError: If the groups fail :func:`validate_kv_cache_groups`, or a
+            matched layer's cache layout violates its rule's invariants (see
+            each rule's ``apply``).
+    """
+    # Backstop for connectors initialized without a kv_cache_config.
+    validate_kv_cache_groups(kv_cache_config)
+    if kv_cache_config is None or not kv_cache_config.has_mamba_layers:
+        return dict(kv_caches)
+
+    edited = dict(kv_caches)
+    counts: Counter[str] = Counter()
+    for group in kv_cache_config.kv_cache_groups:
+        spec = group.kv_cache_spec
+        for name in group.layer_names:
+            for edit in _EDITS:
+                if edit.matches(spec, kv_caches[name]):
+                    edited[name] = edit.apply(spec, kv_caches[name])
+                    counts[edit.name] += 1
+                    break
+    logger.info(
+        "KV cache group edits applied: %s",
+        dict(counts) if counts else "none",
+    )
+    return edited
diff --git a/lmcache/integration/vllm/kv_cache_groups.py b/lmcache/integration/vllm/kv_cache_groups.py
new file mode 100644
index 0000000..5af763b
--- /dev/null
+++ b/lmcache/integration/vllm/kv_cache_groups.py
@@ -0,0 +1,192 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Build LMCache engine group infos from vLLM KV cache group metadata."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.gpu_connector.utils import LayoutHints
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+
+logger = init_logger(__name__)
+
+
+def _is_sliding_window_spec(spec: Any) -> bool:
+    """Return whether the KV cache spec is a vLLM sliding-window spec.
+
+    Checked by class name so this module stays importable without vLLM.
+    Subclasses such as ``SlidingWindowMLASpec`` count.
+    """
+    return any(cls.__name__ == "SlidingWindowSpec" for cls in type(spec).__mro__)
+
+
+def _resolve_per_layer_sw_sizes(
+    vllm_groups: Sequence[Any],
+    layer_to_idx: Mapping[str, int],
+    num_layers: int,
+) -> list[int]:
+    """Resolve the sliding window size in tokens for each registered KV tensor.
+
+    Will resolve -1 for non-sliding-window layers.
+
+    Args:
+        vllm_groups: vLLM ``KVCacheGroupSpec`` instances.
+        layer_to_idx: Layer name to registered tensor index mapping.
+        num_layers: Number of registered KV tensors.
+
+    Returns:
+        A list of length ``num_layers`` mapping each registered tensor index
+        to its sliding window size in tokens, or ``-1`` for
+        non-sliding-window layers.
+    """
+    per_layer_sw_size = [-1] * num_layers
+    for group in vllm_groups:
+        spec = getattr(group, "kv_cache_spec", None)
+        if spec is None:
+            continue
+        # ``UniformTypeKVCacheSpecs`` carries per-layer specs in
+        # ``kv_cache_specs``; other specs apply to all of the group's layers.
+        per_layer_specs = getattr(spec, "kv_cache_specs", None)
+        for name in group.layer_names:
+            layer_spec = per_layer_specs[name] if per_layer_specs else spec
+            if _is_sliding_window_spec(layer_spec):
+                per_layer_sw_size[layer_to_idx[name]] = layer_spec.sliding_window
+    return per_layer_sw_size
+
+
+def _merge_layer_sw_sizes(per_layer_sw_size: list[int], indices: list[int]) -> int:
+    """Merge the per-layer sliding window sizes of one LMCache group.
+
+    Args:
+        per_layer_sw_size: Sliding window size per registered tensor index.
+        indices: Registered tensor indices of the group's layers.
+
+    Returns:
+        The group's common sliding window size in tokens, or ``-1`` when the
+        layers are not sliding-window attention.
+
+    Raises:
+        ValueError: If the layers have different non-negative sliding window sizes.
+    """
+    sw_sizes = {per_layer_sw_size[idx] for idx in indices}
+    if len(sw_sizes) != 1:
+        raise ValueError(
+            f"Layers with indices {indices} have different sliding window sizes "
+            f"{sw_sizes}, but they are in the same group. This should "
+            "not happen because vLLM should only group layers with the same "
+            "KV cache spec, but got inconsistent metadata or registered tensors."
+        )
+    return sw_sizes.pop()
+
+
+def create_engine_group_infos_from_vllm(
+    kv_cache_config: Any,
+    kv_caches: Mapping[str, Any],
+    layout_hints: "LayoutHints | None" = None,
+) -> list[EngineGroupInfo]:
+    """Build the LMCache engine group infos from vLLM metadata and registered tensors.
+
+    This is the single entry point for the vLLM -> LMCache conversion. It reads
+    the vLLM-specific fields (``KVCacheConfig.kv_cache_groups`` and
+    ``KVCacheGroupSpec.layer_names`` from the v1 KV cache interface), maps each
+    engine KV cache group's layer names to registered tensor indices, then
+    splits the layers by physical transfer identity using the real tensors (via
+    the shared :func:`lmcache.v1.kv_layer_groups.group_layers_by_identity`).
+    vLLM-specific field access is intentionally confined to this function.
+
+    Args:
+        kv_cache_config: vLLM ``KVCacheConfig`` describing the engine KV cache
+            groups (or ``None`` / no groups, which yields a single-group spec).
+        kv_caches: Registered KV tensors keyed by layer name, in registration
+            order. Keys provide the layer-name -> tensor-index mapping; values
+            are inspected for physical shape and dtype.
+        layout_hints: Optional engine-provided layout hints forwarded to format
+            detection (e.g. ``NHD``/``HND`` and compression metadata).
+
+    Returns:
+        The list of ``EngineGroupInfo`` in protocol order, i.e. the LMCache group
+        order used by store/retrieve block IDs.
+    """
+    # First Party
+    from lmcache.utils import EngineType
+    from lmcache.v1.gpu_connector.utils import (
+        normalize_and_discover_per_layer_formats,
+    )
+    from lmcache.v1.kv_layer_groups import (
+        EXCLUDED_ENGINE_GROUP,
+        group_layers_by_identity,
+    )
+
+    # vLLM-specific field access (confined to this function): map each
+    # registered KV tensor to its vLLM engine KV cache group index. vLLM places
+    # every registered layer in exactly one group; layers in different groups
+    # have disjoint block-id spaces and must not share an LMCache group. ``None``
+    # means a single (non-hybrid) group, i.e. every layer shares one block-id
+    # space.
+    per_layer_discoverable_kv_caches = list(kv_caches.values())
+    layer_to_idx = {name: idx for idx, name in enumerate(kv_caches.keys())}
+    vllm_groups = (
+        getattr(kv_cache_config, "kv_cache_groups", ()) or ()
+        if kv_cache_config is not None
+        else ()
+    )
+
+    layer_index_groups = [
+        [layer_to_idx[name] for name in group.layer_names] for group in vllm_groups
+    ]
+    normalized_kv_caches, engine_kv_formats = normalize_and_discover_per_layer_formats(
+        per_layer_discoverable_kv_caches,
+        layer_index_groups,
+        EngineType.VLLM,
+        layout_hints,
+    )
+    num_layers = len(engine_kv_formats)
+    # Layers absent from every engine group's ``layer_names`` are cross-layer
+    # KV-sharing layers (e.g. google/gemma-4-E4B-it): vLLM aliases them to a
+    # target owner's KV tensor, so the owner's group already covers them. Tag
+    # them EXCLUDED_ENGINE_GROUP so they form no group of their own (a
+    # wrong-block-size group would corrupt the per-group block-id counts).
+    per_layer_group_idx: list[int] | None = None
+    group_tokens_per_block: dict[int, int] = {}
+    per_layer_sw_size = [-1] * num_layers
+    if vllm_groups:
+        per_layer_group_idx = [EXCLUDED_ENGINE_GROUP] * num_layers
+        for engine_group_id, group in enumerate(vllm_groups):
+            # The spec's block_size is the logical tokens covered by one of
+            # this group's paged chunks (block IDs); the physical slot count
+            # per chunk is discovered later from the registered tensors.
+            group_tokens_per_block[engine_group_id] = group.kv_cache_spec.block_size
+            for name in group.layer_names:
+                per_layer_group_idx[layer_to_idx[name]] = engine_group_id
+        per_layer_sw_size = _resolve_per_layer_sw_sizes(
+            vllm_groups, layer_to_idx, num_layers
+        )
+
+    # Within one vLLM engine group, layers can have different hidden dimensions
+    # (e.g. a different head count), which require different GPU copy kernels.
+    # ``group_layers_by_identity`` splits each engine group further by physical
+    # transfer identity (kv_size, num_heads, head_size, block_size, dtype), so
+    # every resulting LMCache group can be served by a single copy kernel. It is
+    # the shared, engine-neutral primitive the server reuses to reproduce the
+    # same grouping from the registered tensors.
+    return [
+        EngineGroupInfo(
+            engine_group_id=identity.engine_group_idx,
+            layer_indices=tuple(indices),
+            tokens_per_block=group_tokens_per_block.get(identity.engine_group_idx, 0),
+            sw_size_tokens=_merge_layer_sw_sizes(per_layer_sw_size, indices),
+        )
+        for identity, indices in group_layers_by_identity(
+            normalized_kv_caches,
+            engine_kv_formats,
+            per_layer_group_idx,
+        )
+    ]
diff --git a/lmcache/integration/vllm/lmcache_connector_v1.py b/lmcache/integration/vllm/lmcache_connector_v1.py
new file mode 100644
index 0000000..dbfa921
--- /dev/null
+++ b/lmcache/integration/vllm/lmcache_connector_v1.py
@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any, Optional
+
+# Third Party
+from vllm.config import VllmConfig
+from vllm.distributed.kv_transfer.kv_connector.v1.base import (
+    KVConnectorBase_V1,
+    KVConnectorMetadata,
+    KVConnectorRole,
+)
+from vllm.logger import init_logger
+from vllm.v1.core.sched.output import SchedulerOutput
+import torch
+
+# First Party
+from lmcache.integration.vllm.vllm_v1_adapter import LMCacheConnectorV1Impl
+
+if TYPE_CHECKING:
+    # Third Party
+    from vllm.attention.backends.abstract import AttentionMetadata
+    from vllm.forward_context import ForwardContext
+    from vllm.v1.core.kv_cache_manager import KVCacheBlocks
+    from vllm.v1.request import Request
+
+logger = init_logger(__name__)
+
+
+class LMCacheConnectorV1Dynamic(KVConnectorBase_V1):
+    def __init__(
+        self,
+        vllm_config: "VllmConfig",
+        role: KVConnectorRole,
+        kv_cache_config: Optional[Any] = None,
+    ):
+        if kv_cache_config is not None:
+            super().__init__(
+                vllm_config=vllm_config,
+                role=role,
+                kv_cache_config=kv_cache_config,
+            )
+        else:
+            super().__init__(vllm_config=vllm_config, role=role)
+        self._lmcache_engine = LMCacheConnectorV1Impl(vllm_config, role, self)
+
+    # ==============================
+    # Worker-side methods
+    # ==============================
+    def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
+        """
+        Initialize with the KV caches. Useful for pre-registering the
+        KV Caches in the KVConnector (e.g. for NIXL).
+
+        Args: kv_caches:
+            dictionary of layer names, kv cache
+        """
+        self._lmcache_engine.register_kv_caches(kv_caches)
+
+    def start_load_kv(self, forward_context: "ForwardContext", **kwargs) -> None:
+        """
+        Start loading the KV cache from the connector to vLLM's paged
+        KV buffer. This is called from the forward context before the
+        forward pass to enable async loading during model execution.
+
+        Args:
+            forward_context (ForwardContext): the forward context.
+            **kwargs: additional arguments for the load operation
+        """
+        self._lmcache_engine.start_load_kv(forward_context, **kwargs)
+
+    def wait_for_layer_load(self, layer_name: str) -> None:
+        """
+        Block until the KV for a specific layer is loaded into vLLM's
+        paged buffer. This is called from within attention layer to ensure
+        async copying from start_load_kv is complete.
+
+        This interface will be useful for layer-by-layer pipelining.
+
+        Args:
+            layer_name: the name of that layer
+        """
+        self._lmcache_engine.wait_for_layer_load(layer_name)
+
+    def save_kv_layer(
+        self,
+        layer_name: str,
+        kv_layer: torch.Tensor,
+        attn_metadata: "AttentionMetadata",
+        **kwargs,
+    ) -> None:
+        """
+        Start saving the a layer of KV cache from vLLM's paged buffer
+        to the connector. This is called from within attention layer to
+        enable async copying during execution.
+
+        Args:
+            layer_name (str): the name of the layer.
+            kv_layer (torch.Tensor): the paged KV buffer of the current
+                layer in vLLM.
+            attn_metadata (AttentionMetadata): the attention metadata.
+            **kwargs: additional arguments for the save operation.
+        """
+        self._lmcache_engine.save_kv_layer(
+            layer_name, kv_layer, attn_metadata, **kwargs
+        )
+
+    def wait_for_save(self):
+        """
+        Block until all the save operations is done. This is called
+        as the forward context exits to ensure that the async saving
+        from save_kv_layer is complete before finishing the forward.
+
+        This prevents overwrites of paged KV buffer before saving done.
+        """
+        self._lmcache_engine.wait_for_save()
+
+    def get_finished(
+        self, finished_req_ids: set[str]
+    ) -> tuple[Optional[set[str]], Optional[set[str]]]:
+        """
+        Notifies worker-side connector ids of requests that have
+        finished generating tokens.
+
+        Returns:
+            ids of requests that have finished asynchronous transfer
+            (requests that previously returned True from request_finished()),
+            tuple of (sending/saving ids, recving/loading ids).
+            The finished saves/sends req ids must belong to a set provided in a
+            call to this method (this call or a prior one).
+        """
+        return self._lmcache_engine.get_finished(finished_req_ids)
+
+    def get_block_ids_with_load_errors(self) -> set[int]:
+        """Return block IDs that failed to load during the last interval."""
+        return self._lmcache_engine.get_block_ids_with_load_errors()
+
+    def shutdown(self):
+        """
+        Shutdown the connector. This is called when the worker process
+        is shutting down to ensure that all the async operations are
+        completed and the connector is cleaned up properly.
+        """
+        return self._lmcache_engine.shutdown()
+
+    # ==============================
+    # Scheduler-side methods
+    # ==============================
+    def get_num_new_matched_tokens(
+        self,
+        request: "Request",
+        num_computed_tokens: int,
+    ) -> tuple[Optional[int], bool]:
+        """
+        Get number of new tokens that can be loaded from the
+        external KV cache beyond the num_computed_tokens.
+
+        Args:
+            request (Request): the request object.
+            num_computed_tokens (int): the number of locally
+                computed tokens for this request
+
+        Returns:
+            the number of tokens that can be loaded from the
+            external KV cache beyond what is already computed.
+        """
+        return self._lmcache_engine.get_num_new_matched_tokens(
+            request, num_computed_tokens
+        ), False
+
+    def update_state_after_alloc(
+        self, request: "Request", blocks: "KVCacheBlocks", num_external_tokens: int
+    ):
+        """
+        Update KVConnector state after block allocation.
+        """
+        self._lmcache_engine.update_state_after_alloc(request, num_external_tokens)
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> KVConnectorMetadata:
+        """
+        Build the connector metadata for this step.
+
+        This function should NOT modify fields in the scheduler_output.
+        Also, calling this function will reset the state of the connector.
+
+        Args:
+            scheduler_output (SchedulerOutput): the scheduler output object.
+        """
+        return self._lmcache_engine.build_connector_meta(scheduler_output)
+
+    def request_finished(
+        self,
+        request: "Request",
+        block_ids: list[int],
+    ) -> tuple[bool, Optional[dict[str, Any]]]:
+        """
+        Called when a request has finished, before its blocks are freed.
+
+        Returns:
+            True if the request is being saved/sent asynchronously and blocks
+            should not be freed until the request_id is returned from
+            get_finished().
+            Optional KVTransferParams to be included in the request outputs
+            returned by the engine.
+        """
+        return self._lmcache_engine.request_finished(request, block_ids)
diff --git a/lmcache/integration/vllm/lmcache_connector_v1_085.py b/lmcache/integration/vllm/lmcache_connector_v1_085.py
new file mode 100644
index 0000000..8abfb5d
--- /dev/null
+++ b/lmcache/integration/vllm/lmcache_connector_v1_085.py
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING
+
+# Third Party
+from vllm.config import VllmConfig
+from vllm.distributed.kv_transfer.kv_connector.v1.base import (
+    KVConnectorBase_V1,
+    KVConnectorMetadata,
+    KVConnectorRole,
+)
+from vllm.logger import init_logger
+from vllm.v1.core.sched.output import SchedulerOutput
+import torch
+
+# First Party
+from lmcache.integration.vllm.vllm_v1_adapter import LMCacheConnectorV1Impl
+
+if TYPE_CHECKING:
+    # Third Party
+    from vllm.attention.backends.abstract import AttentionMetadata
+    from vllm.forward_context import ForwardContext
+    from vllm.v1.request import Request
+
+logger = init_logger(__name__)
+
+
+class LMCacheConnectorV1Dynamic(KVConnectorBase_V1):
+    def __init__(self, vllm_config: "VllmConfig", role: KVConnectorRole):
+        super().__init__(vllm_config=vllm_config, role=role)
+        self._lmcache_engine = LMCacheConnectorV1Impl(vllm_config, role, self)
+
+    # ==============================
+    # Worker-side methods
+    # ==============================
+    def start_load_kv(self, forward_context: "ForwardContext", **kwargs) -> None:
+        """
+        Start loading the KV cache from the connector to vLLM's paged
+        KV buffer. This is called from the forward context before the
+        forward pass to enable async loading during model execution.
+
+        Args:
+            forward_context (ForwardContext): the forward context.
+            **kwargs: additional arguments for the load operation
+        """
+        self._lmcache_engine.start_load_kv(forward_context, **kwargs)
+
+    def wait_for_layer_load(self, layer_name: str) -> None:
+        """
+        Block until the KV for a specific layer is loaded into vLLM's
+        paged buffer. This is called from within attention layer to ensure
+        async copying from start_load_kv is complete.
+
+        This interface will be useful for layer-by-layer pipelining.
+
+        Args:
+            layer_name: the name of that layer
+        """
+        self._lmcache_engine.wait_for_layer_load(layer_name)
+
+    def save_kv_layer(
+        self,
+        layer_name: str,
+        kv_layer: torch.Tensor,
+        attn_metadata: "AttentionMetadata",
+        **kwargs,
+    ) -> None:
+        """
+        Start saving the a layer of KV cache from vLLM's paged buffer
+        to the connector. This is called from within attention layer to
+        enable async copying during execution.
+
+        Args:
+            layer_name (str): the name of the layer.
+            kv_layer (torch.Tensor): the paged KV buffer of the current
+                layer in vLLM.
+            attn_metadata (AttentionMetadata): the attention metadata.
+            **kwargs: additional arguments for the save operation.
+        """
+        self._lmcache_engine.save_kv_layer(
+            layer_name, kv_layer, attn_metadata, **kwargs
+        )
+
+    def wait_for_save(self):
+        """
+        Block until all the save operations is done. This is called
+        as the forward context exits to ensure that the async saving
+        from save_kv_layer is complete before finishing the forward.
+
+        This prevents overwrites of paged KV buffer before saving done.
+        """
+        self._lmcache_engine.wait_for_save()
+
+    def shutdown(self):
+        """
+        Shutdown the connector. This is called when the worker process
+        is shutting down to ensure that all the async operations are
+        completed and the connector is cleaned up properly.
+        """
+        return self._lmcache_engine.shutdown()
+
+    # ==============================
+    # Scheduler-side methods
+    # ==============================
+    def get_num_new_matched_tokens(
+        self,
+        request: "Request",
+        num_computed_tokens: int,
+    ) -> int:
+        """
+        Get number of new tokens that can be loaded from the
+        external KV cache beyond the num_computed_tokens.
+
+        Args:
+            request (Request): the request object.
+            num_computed_tokens (int): the number of locally
+                computed tokens for this request
+
+        Returns:
+            the number of tokens that can be loaded from the
+            external KV cache beyond what is already computed.
+        """
+        return self._lmcache_engine.get_num_new_matched_tokens(
+            request, num_computed_tokens
+        )
+
+    def update_state_after_alloc(self, request: "Request", num_external_tokens: int):
+        """
+        Update KVConnector state after block allocation.
+        """
+        self._lmcache_engine.update_state_after_alloc(request, num_external_tokens)
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> KVConnectorMetadata:
+        """
+        Build the connector metadata for this step.
+
+        This function should NOT modify fields in the scheduler_output.
+        Also, calling this function will reset the state of the connector.
+
+        Args:
+            scheduler_output (SchedulerOutput): the scheduler output object.
+        """
+        return self._lmcache_engine.build_connector_meta(scheduler_output)
diff --git a/lmcache/integration/vllm/lmcache_mp_connector.py b/lmcache/integration/vllm/lmcache_mp_connector.py
new file mode 100644
index 0000000..82abcd3
--- /dev/null
+++ b/lmcache/integration/vllm/lmcache_mp_connector.py
@@ -0,0 +1,1436 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# Standard
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+import enum
+import math
+import sys
+
+# Third Party
+from vllm.config import VllmConfig
+from vllm.distributed.kv_transfer.kv_connector.v1.base import (
+    KVConnectorBase_V1,
+    KVConnectorMetadata,
+    KVConnectorRole,
+)
+
+try:
+    # Third Party
+    from vllm.distributed.kv_transfer.kv_connector.v1.base import SupportsHMA
+except ImportError:
+    # Older vLLM builds do not expose HMA. They cannot route per-group
+    # request-finished calls, but keeping the class importable preserves
+    # legacy single-group behavior.
+    class SupportsHMA:  # type: ignore[no-redef]
+        pass
+
+
+# Third Party
+from vllm.v1.attention.backend import AttentionMetadata
+from vllm.v1.core.sched.output import SchedulerOutput
+from vllm.v1.outputs import KVConnectorOutput
+from vllm.v1.request import RequestStatus
+from vllm.v1.utils import ConstantList
+import torch
+import zmq
+
+# First Party
+from lmcache import torch_dev
+from lmcache.banner import print_banner_once
+from lmcache.integration.vllm.kv_cache_group_edits import (
+    apply_kv_cache_group_edits,
+    validate_kv_cache_groups,
+)
+from lmcache.integration.vllm.kv_cache_groups import (
+    create_engine_group_infos_from_vllm,
+)
+from lmcache.integration.vllm.utils import mla_enabled, vllm_layout_hints
+from lmcache.utils import init_logger as lmcache_init_logger
+from lmcache.v1.multiprocess.group_view import slice_block_ids_per_group
+
+try:
+    # First Party
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        LMCacheMPSchedulerAdapter,
+        LMCacheMPWorkerAdapter,
+        LoadStoreOp,
+        ParallelStrategy,
+    )
+
+    try:
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import (  # type: ignore[attr-defined]
+            RequestAllocationRecord,
+        )
+    except ImportError:
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import (
+            BlockAllocationRecord as RequestAllocationRecord,
+        )
+except ImportError:
+    # Third Party
+    from vllm.distributed.kv_transfer.kv_connector.v1.lmcache_integration import (  # type: ignore[no-redef]
+        LMCacheMPSchedulerAdapter,
+        LMCacheMPWorkerAdapter,
+        LoadStoreOp,
+        ParallelStrategy,
+    )
+
+    # First Party
+    from lmcache.v1.multiprocess.custom_types import (
+        BlockAllocationRecord as RequestAllocationRecord,
+    )
+
+if TYPE_CHECKING:
+    # Third Party
+    from vllm.distributed.kv_events import KVCacheEvent
+    from vllm.distributed.kv_transfer.kv_connector.v1.metrics import (
+        KVConnectorPromMetrics,
+        KVConnectorStats,
+        PromMetric,
+        PromMetricT,
+    )
+    from vllm.forward_context import ForwardContext
+    from vllm.v1.core.kv_cache_manager import KVCacheBlocks
+    from vllm.v1.kv_cache_interface import KVCacheConfig
+    from vllm.v1.request import Request
+
+logger = lmcache_init_logger(__name__)
+
+
+# Helper functions
+def _has_preemption_reqs(scheduler_output: SchedulerOutput) -> bool:
+    """Return whether the scheduler output contains preemption-related requests.
+
+    Checks for the presence of resumed or preempted requests in the
+    scheduler output.
+
+    A preemption is detected if:
+    - ``scheduled_cached_reqs.resumed_req_ids``: Requests resumed from
+      preemption this step.
+    - ``scheduler_output.preempted_req_ids``: Requests preempted this step.
+
+    Args:
+        scheduler_output: The vLLM scheduler output for this step.
+
+    Returns:
+        True if preemption-related requests exist, False otherwise.
+    """
+    cached_reqs = getattr(scheduler_output, "scheduled_cached_reqs", None)
+
+    # Primary signal: requests resumed from preemption this step.
+    resumed_ids = getattr(cached_reqs, "resumed_req_ids", None)
+    if resumed_ids:
+        logger.warning("<preempted> by resumed requests: %s", resumed_ids)
+        return True
+
+    # Primary signal: requests preempted this step.
+    preempted_ids = getattr(scheduler_output, "preempted_req_ids", None)
+    if preempted_ids:
+        logger.warning("<preempted> by preempted requests: %s", preempted_ids)
+        return True
+
+    return False
+
+
+def validate_mamba_step_alignment(vllm_config: VllmConfig) -> None:
+    """Reject scheduler configs that can skip Mamba state snapshots.
+
+    In ``mamba_cache_mode="align"`` vLLM snapshots the recurrent state only at
+    the end of each scheduler step, and a step that advances more than one
+    block fills the skipped block-table positions with the null block
+    (``MambaManager.allocate_new_blocks``). LMCache keys chunks by token hash,
+    so a skipped boundary would be stored as null-block garbage under a valid
+    key and silently corrupt any request that later resumes from that prefix.
+    Requiring ``block_size <= max_num_batched_tokens < 2 * block_size`` makes
+    vLLM's block-aligned splitting (``Scheduler._mamba_block_aligned_split``)
+    advance every mid-prefill step by exactly one block, so every chunk
+    boundary holds a real snapshot.
+
+    Args:
+        vllm_config: The vLLM config; only Mamba-hybrid models in ``align``
+            cache mode are constrained, others pass.
+
+    Raises:
+        ValueError: If ``max_num_batched_tokens`` is not in
+            ``[block_size, 2 * block_size)``.
+    """
+    if getattr(vllm_config.cache_config, "mamba_cache_mode", "none") != "align":
+        return
+    block_size = vllm_config.cache_config.block_size
+    max_batched = vllm_config.scheduler_config.max_num_batched_tokens
+    if not (block_size <= max_batched < 2 * block_size):
+        raise ValueError(
+            f"Mamba-hybrid models with LMCache require "
+            f"block_size <= max_num_batched_tokens < 2 * block_size so every "
+            f"prefill step advances exactly one block and every block boundary "
+            f"gets a state snapshot; got max_num_batched_tokens={max_batched}, "
+            f"block_size={block_size}. Set --max-num-batched-tokens "
+            f"{block_size}."
+        )
+
+
+def build_parallel_strategy_from_vllm_config(
+    vllm_config: "VllmConfig",
+    n_servers: int,
+) -> ParallelStrategy:
+    """Build a ParallelStrategy from a vLLM config.
+
+    Centralises the (vllm_config -> KV parallel geometry) mapping.
+
+    Args:
+        vllm_config: The vLLM configuration object.
+        n_servers: Number of LMCache servers backing this deployment.
+
+    Returns:
+        The constructed ParallelStrategy.
+    """
+    pc = vllm_config.parallel_config
+    return ParallelStrategy(
+        use_mla=mla_enabled(vllm_config.model_config),
+        vllm_world_size=pc.world_size,
+        vllm_worker_id=pc.rank,
+        tp_size=pc.tensor_parallel_size,
+        pp_size=pc.pipeline_parallel_size,
+        n_servers=n_servers,
+    )
+
+
+class LMCacheMPRequestState(enum.Enum):
+    """
+    State machine:
+    PREFETCHING -- update_state_after_alloc --> WAITING_FOR_LOAD
+    WAITING_FOR_LOAD -- process_loading_requests --> READY
+    """
+
+    PREFETCHING = enum.auto()
+    WAITING_FOR_LOAD = enum.auto()
+    READY = enum.auto()
+
+
+@dataclass
+class LMCacheMPRequestTracker:
+    # NOTE: this class used vLLM data structures, should be part of
+    # vLLM integration code
+
+    request_id: str
+
+    # Read-only list to track the token ids
+    all_token_ids: ConstantList[int]
+
+    # Block ids will be updated at update_states_after_alloc and
+    # during generation. Keyed by engine_group_idx; non-HMA models use 0.
+    allocated_block_ids: dict[int, list[int]] = field(default_factory=dict)
+
+    # Number of scheduled tokens in this request. We keep tracking this to
+    # avoid saving tokens whose KV has not been computed yet.
+    num_scheduled_tokens: int = 0
+
+    # Number of tokens stored will be initialized when lookup the external
+    # hit tokens and will be updated when processing new requests and cached
+    # requests.
+    num_stored_tokens: int = 0
+
+    # Staging load operation -- save vllm and lmcache hit tokens during lookup
+    num_vllm_hit_tokens: int = 0
+    num_lmcache_hit_tokens: int = 0
+
+    # Main state
+    state: LMCacheMPRequestState = LMCacheMPRequestState.PREFETCHING
+
+    cache_salt: str = ""
+
+    def __init__(self, request: "Request"):
+        self.request_id = request.request_id
+        self.cache_salt: str = request.cache_salt or ""
+        self.all_token_ids = request.all_token_ids
+        self.allocated_block_ids = {}
+        self.num_stored_tokens = 0
+        self.num_vllm_hit_tokens = 0
+        self.num_lmcache_hit_tokens = 0
+        self.state = LMCacheMPRequestState.PREFETCHING
+
+    ####
+    # Check the state of the request
+    ####
+    def needs_retrieve(self) -> bool:
+        """Check whether the current request needs retrieve, will be used
+        update_stage_after_alloc"""
+        return (
+            self.num_lmcache_hit_tokens > self.num_vllm_hit_tokens
+            and self.state != LMCacheMPRequestState.READY
+        )
+
+    def is_ready_for_retrieving(self) -> bool:
+        """Check whether the current request is ready for retrieving,
+        will be used in process_loading_requests"""
+        return (
+            self.state == LMCacheMPRequestState.WAITING_FOR_LOAD
+            and self.needs_retrieve()
+        )
+
+    ####
+    # Update internal states
+    ####
+    def increase_num_scheduled_tokens(self, num_new_tokens: int):
+        self.num_scheduled_tokens += num_new_tokens
+
+    def increase_num_stored_tokens(self, num_new_tokens: int):
+        """Increase the number of stored tokens for the current request
+        This function will be called when processing the cached requests.
+        """
+        self.num_stored_tokens += num_new_tokens
+
+    def append_block_ids(
+        self,
+        new_block_ids: tuple[list[int], ...],
+    ):
+        """Update the block ids for the current request
+        This function will be called when processing the cached requests.
+        """
+        for engine_group_idx, group_block_ids in enumerate(new_block_ids):
+            if group_block_ids:
+                self.allocated_block_ids.setdefault(engine_group_idx, []).extend(
+                    group_block_ids
+                )
+
+    def num_allocated_blocks(self) -> dict[int, int]:
+        return {
+            engine_group_idx: len(blocks)
+            for engine_group_idx, blocks in self.allocated_block_ids.items()
+        }
+
+    ####
+    # For debugging
+    ####
+    def __repr__(self) -> str:
+        return (
+            f"LMCacheMPRequestTracker(request_id={self.request_id}, "
+            f"num_tokens={len(self.all_token_ids)}, "
+            f"num_allocated_blocks="
+            f"{self.num_allocated_blocks()}, "
+            f"num_stored_tokens={self.num_stored_tokens}, "
+            f"vllm_hit_tokens={self.num_vllm_hit_tokens}, "
+            f"lmcache_hit_tokens={self.num_lmcache_hit_tokens}, "
+            f"state={self.state})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+@dataclass
+class LMCacheMPRequestMetadata:
+    request_id: str
+    direction: Literal["STORE", "RETRIEVE"]
+    op: LoadStoreOp
+    cache_salt: str = ""
+
+    @staticmethod
+    def GetStoreMetadata(
+        tracker: LMCacheMPRequestTracker,
+        lmcache_tokens_per_chunk: int,
+        group_tokens_per_block: list[int],
+    ) -> "LMCacheMPRequestMetadata | None":
+        """
+        Generate the store metadata for the current request tracker.
+
+        Args:
+            tracker: The request tracker to generate the metadata from.
+            lmcache_tokens_per_chunk: the number of tokens in a LMCache data chunk
+            group_tokens_per_block: per-engine-group tokens covered by one
+                paged chunk (one block ID) of that group, i.e. the group's
+                KV cache spec ``block_size``. Must each divide
+                ``lmcache_tokens_per_chunk`` (hybrid models can mix different values).
+        """
+        num_engine_groups = len(group_tokens_per_block)
+        # NOTE: the invariant here is that `num_stored_tokens` should
+        # always be a multiple of `lmcache_tokens_per_chunk`
+        # TODO: This should be checked every time we update the num_stored_tokens
+        #
+        # Why computed_tokens uses max(num_vllm_hit_tokens, num_lmcache_hit_tokens):
+        #
+        # Both values represent a prefix of tokens whose KV data is already
+        # available (either from vLLM APC or from LMCache), so they must NOT
+        # be summed (that would double-count the overlapping prefix).
+        #
+        # * num_lmcache_hit_tokens: LMCache-hit tokens are already counted in
+        #   num_stored_tokens (set during lookup), so they must be included
+        #   here to keep the upper bound consistent.  They are NOT re-stored.
+        # * num_vllm_hit_tokens: LMCache stores in units of chunks, so
+        #   num_lmcache_hit_tokens is rounded DOWN to the nearest chunk
+        #   boundary.  When vLLM APC hits more tokens than that rounded value
+        #   (e.g. APC=704 tokens, LMCache=512 tokens after chunk alignment),
+        #   using only num_lmcache_hit_tokens would set the upper bound too
+        #   low and silently skip the APC-hit tokens that fall between the
+        #   two values, causing under-storing.  Taking the max ensures we
+        #   always use the tighter (larger) of the two hit counts.
+        computed_tokens = tracker.num_scheduled_tokens + max(
+            tracker.num_vllm_hit_tokens, tracker.num_lmcache_hit_tokens
+        )
+        # Each group covers ``len(block_ids) * tokens_per_block`` tokens; the
+        # storable prefix is bounded by the least-covered group (e.g.
+        # gemma-4 sliding: one 32-token ID covers 2x the tokens of a
+        # 16-token full-attention ID).
+        allocated_lengths = tracker.num_allocated_blocks()
+        allocated_tokens = (
+            min(
+                allocated_lengths.get(engine_group_idx, 0)
+                * group_tokens_per_block[engine_group_idx]
+                for engine_group_idx in range(num_engine_groups)
+            )
+            if num_engine_groups > 0
+            else 0
+        )
+        min_available_tokens = min(
+            len(tracker.all_token_ids),
+            allocated_tokens,
+            computed_tokens,
+        )
+        num_staging_tokens = min_available_tokens - tracker.num_stored_tokens
+        num_chunks = num_staging_tokens // lmcache_tokens_per_chunk
+
+        if num_chunks >= 1:
+            start_token_idx = tracker.num_stored_tokens
+            end_token_idx = start_token_idx + num_chunks * lmcache_tokens_per_chunk
+            block_ids = slice_block_ids_per_group(
+                tracker.allocated_block_ids,
+                group_tokens_per_block,
+                start_token_idx,
+                end_token_idx,
+            )
+            token_ids = list(tracker.all_token_ids)
+            op = LoadStoreOp(
+                token_ids=token_ids,
+                block_ids=block_ids,
+                start=start_token_idx,
+                end=end_token_idx,
+            )
+
+            ret = LMCacheMPRequestMetadata(
+                request_id=tracker.request_id,
+                direction="STORE",
+                op=op,
+                cache_salt=tracker.cache_salt,
+            )
+
+            # Update the request tracker
+            tracker.increase_num_stored_tokens(end_token_idx - start_token_idx)
+            return ret
+
+        return None
+
+    @staticmethod
+    def GetRetrieveMetadata(
+        tracker: LMCacheMPRequestTracker,
+        lmcache_tokens_per_chunk: int,
+        group_tokens_per_block: list[int],
+    ) -> "LMCacheMPRequestMetadata | None":
+        """
+        Generate the retrieve metadata for the current request tracker.
+
+        Args:
+            tracker: The request tracker to generate the metadata from.
+            lmcache_tokens_per_chunk: the number of tokens in a LMCache data chunk
+            group_tokens_per_block: per-engine-group tokens covered by one
+                paged chunk (one block ID) of that group, i.e. the group's
+                KV cache spec ``block_size``. Must each divide
+                ``lmcache_tokens_per_chunk`` (hybrid models can mix different values).
+        """
+        if not tracker.is_ready_for_retrieving():
+            return None
+
+        # |---------------------|-----------------|----------------|
+        # | num_vllm_hit_tokens |
+        # | lmcache chunk 1   | lmcache chunk 2   |
+        #                     |  need to retrieve |
+
+        start_token_idx = (
+            tracker.num_vllm_hit_tokens
+            // lmcache_tokens_per_chunk
+            * lmcache_tokens_per_chunk
+        )
+        end_token_idx = tracker.num_lmcache_hit_tokens
+        assert end_token_idx % lmcache_tokens_per_chunk == 0, (
+            "The number of LMCache hit tokens should be a multiple of the "
+            "LMCache chunk size. "
+        )
+        assert len(tracker.all_token_ids) >= end_token_idx, (
+            "The number of tokens should be greater than or equal to the "
+            "number of LMCache hit tokens. "
+        )
+        if end_token_idx > start_token_idx:
+            block_ids = slice_block_ids_per_group(
+                tracker.allocated_block_ids,
+                group_tokens_per_block,
+                start_token_idx,
+                end_token_idx,
+            )
+            token_ids = list(tracker.all_token_ids)
+
+            # Compute how many tokens at the start of the retrieve range
+            # overlap with APC-shared blocks. The server must skip writing
+            # to these positions to avoid a cross-stream data race: the
+            # retrieve writes on the LMCache CUDA stream while concurrent
+            # requests may read these APC-shared blocks on the vLLM stream.
+            skip_first_n_tokens = tracker.num_vllm_hit_tokens - start_token_idx
+
+            op = LoadStoreOp(
+                token_ids=token_ids,
+                block_ids=block_ids,
+                start=start_token_idx,
+                end=end_token_idx,
+                skip_first_n_tokens=skip_first_n_tokens,
+            )
+
+            ret = LMCacheMPRequestMetadata(
+                request_id=tracker.request_id,
+                direction="RETRIEVE",
+                op=op,
+                cache_salt=tracker.cache_salt,
+            )
+            return ret
+
+        return None
+
+
+class LMCacheMPConnectorMetadata(KVConnectorMetadata):
+    def __init__(self):
+        super().__init__()
+        self.requests: list[LMCacheMPRequestMetadata] = []
+        self.need_flush_before_forward: bool = False
+
+    def add_request_metadata(self, request_metadata: LMCacheMPRequestMetadata):
+        self.requests.append(request_metadata)
+
+    def __len__(self):
+        return len(self.requests)
+
+    # For debugging
+    def __str__(self):
+        request_strs = []
+        for req_meta in self.requests:
+            request_strs.append(
+                f"RequestMetadata(request_id={req_meta.request_id}, "
+                f"direction={req_meta.direction}, "
+                f"num_blocks={len(req_meta.op.flat_block_ids)}, "
+                f"block_ids={req_meta.op.block_ids})"
+            )
+        return (
+            f"need_flush_before_forward={self.need_flush_before_forward}; ["
+            + "\n".join(request_strs)
+            + "]"
+        )
+
+    def __repr__(self):
+        return self.__str__()
+
+
+def _ensure_zmq_scheme(server_url: str) -> str:
+    """Ensure a ZMQ server URL carries a transport scheme.
+
+    ZeroMQ requires an explicit transport (e.g. ``tcp://``) in the address;
+    a bare ``host:port`` such as ``127.0.0.1:5557`` is rejected with
+    ``ZMQError: Invalid argument``. Users naturally configure
+    ``lmcache.mp.host`` as a plain IP/hostname, so prepend ``tcp://`` when no
+    scheme is present.
+
+    Args:
+        server_url: A server URL, with or without a ``<scheme>://`` prefix.
+
+    Returns:
+        The URL with a transport scheme, defaulting to ``tcp://``.
+    """
+    if "://" in server_url:
+        return server_url
+    return f"tcp://{server_url}"
+
+
+class LMCacheMPConnector(KVConnectorBase_V1, SupportsHMA):
+    """
+    The connector for LMCache multi-process mode.
+
+    Extra configs (kv_transfer_config.extra_config):
+
+    Multi-server deployment:
+    - lmcache.mp.server_urls: server URL list or comma-separated string,
+      e.g. "tcp://host1:6667,tcp://host2:6667".
+
+    Single-server deployment:
+    - lmcache.mp.host: the host of the LMCache server.
+    - lmcache.mp.port: the port of the LMCache server.
+
+    - lmcache.mp.mq_timeout: timeout (seconds) for message queue requests.
+    - lmcache.mp.heartbeat_interval: interval (seconds) between server
+      heartbeat pings.
+    """
+
+    def __init__(
+        self,
+        vllm_config: "VllmConfig",
+        role: KVConnectorRole,
+        kv_cache_config: "KVCacheConfig | None" = None,
+    ):
+        super().__init__(vllm_config, role, kv_cache_config)
+
+        # Fail fast, before the server handshake below.
+        validate_mamba_step_alignment(vllm_config)
+        validate_kv_cache_groups(getattr(self, "_kv_cache_config", None))
+
+        assert vllm_config.kv_transfer_config is not None
+
+        # Multi-server: prefer lmcache.mp.server_urls (list or comma-separated
+        # string) over the single-server lmcache.mp.host / lmcache.mp.port.
+        server_urls_cfg = vllm_config.kv_transfer_config.get_from_extra_config(
+            "lmcache.mp.server_urls", None
+        )
+        if server_urls_cfg:
+            if isinstance(server_urls_cfg, list):
+                server_urls = [u.strip() for u in server_urls_cfg if u.strip()]
+            else:
+                server_urls = [
+                    u.strip() for u in server_urls_cfg.split(",") if u.strip()
+                ]
+        else:
+            # Legacy single-server fallback.
+            server_host = vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.mp.host", "tcp://localhost"
+            )
+            server_port = vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.mp.port", 5555
+            )
+            server_urls = [f"{server_host}:{server_port}"]
+
+        # Normalize so a bare host:port (no transport scheme) is accepted;
+        # ZMQ requires an explicit transport such as ``tcp://``.
+        server_urls = [_ensure_zmq_scheme(u) for u in server_urls]
+
+        # The server count is derived from lmcache.mp.server_urls.
+        n_servers = len(server_urls)
+
+        assert vllm_config.parallel_config.world_size % n_servers == 0, (
+            f"world_size ({vllm_config.parallel_config.world_size}) must be "
+            f"divisible by n_servers ({n_servers})"
+        )
+
+        # Multi-server + DP is not supported yet.
+        dp_size = getattr(vllm_config.parallel_config, "data_parallel_size", 1)
+        if n_servers > 1 and dp_size > 1:
+            raise ValueError(
+                "LMCacheMPConnector multi-server mode (n_servers > 1) does not "
+                f"support data parallelism yet; got dp_size={dp_size}. "
+                "DP across multiple LMCache servers will be "
+                "supported in a follow-up PR."
+            )
+
+        # Multi-server + MLA: only TP is supported (no PP).
+        # PP splits layers across nodes, which would cause per-piece
+        # reader counts to vary per (server, pp_stage) pair and break
+        # the single-``tp_size`` LOOKUP / FREE_LOOKUP_LOCKS protocol.
+        # Non-MLA mode is not affected by this restriction.
+        if n_servers > 1:
+            pp_size = vllm_config.parallel_config.pipeline_parallel_size
+            if pp_size > 1:
+                raise ValueError(
+                    "LMCacheMPConnector multi-server mode only supports "
+                    "tensor parallelism (TP), not pipeline parallelism (PP). "
+                    f"Got pp_size={pp_size}."
+                )
+
+        zmq_context = zmq.Context.instance()
+        parallel_strategy = build_parallel_strategy_from_vllm_config(
+            vllm_config, n_servers
+        )
+
+        if self.role == KVConnectorRole.SCHEDULER:
+            # Banner from the scheduler role only, so tensor-parallel
+            # deployments print it once rather than once per worker.
+            print_banner_once(sys.stderr)
+            self.scheduler_adapter = LMCacheMPSchedulerAdapter(
+                server_urls=server_urls,
+                context=zmq_context,
+                model_name=vllm_config.model_config.model,
+                vllm_block_size=vllm_config.cache_config.block_size,
+                parallel_strategy=parallel_strategy,
+                extra_config=vllm_config.kv_transfer_config.kv_connector_extra_config,
+            )
+            self.request_trackers: dict[str, LMCacheMPRequestTracker] = {}
+        elif self.role == KVConnectorRole.WORKER:
+            # Node routing: a worker connects only to its local LMCache server.
+            # Global ranks are assigned to nodes in contiguous blocks:
+            #   node 0 → ranks [0, ranks_per_node),
+            #   node 1 → [ranks_per_node, 2 * ranks_per_node), ...
+            ranks_per_node = parallel_strategy.vllm_world_size // n_servers
+            local_server_url = server_urls[
+                parallel_strategy.vllm_worker_id // ranks_per_node
+            ]
+            self.worker_adapter = LMCacheMPWorkerAdapter(
+                server_url=local_server_url,
+                context=zmq_context,
+                model_name=vllm_config.model_config.model,
+                vllm_block_size=vllm_config.cache_config.block_size,
+                parallel_strategy=parallel_strategy,
+                extra_config=vllm_config.kv_transfer_config.kv_connector_extra_config,
+            )
+        else:
+            raise ValueError(f"Unknown KVConnectorRole: {self.role}")
+
+        kv_cache_config = getattr(self, "_kv_cache_config", None)
+        vllm_groups = (
+            getattr(kv_cache_config, "kv_cache_groups", ()) or ()
+            if kv_cache_config is not None
+            else ()
+        )
+        # Tokens covered by one paged chunk (one block ID) of each engine
+        # group, from the group's KV cache spec. Hybrid models can mix
+        # different values (e.g. gemma-4: sliding-window groups 32,
+        # full-attention groups 16; DeepSeek V4: 256/64/8/4). Falls back to
+        # the engine's base block size when no group metadata is available
+        # (single non-hybrid group).
+        self._group_tokens_per_block: list[int] = [
+            group.kv_cache_spec.block_size for group in vllm_groups
+        ] or [vllm_config.cache_config.block_size]
+        for engine_group_idx, tokens_per_block in enumerate(
+            self._group_tokens_per_block
+        ):
+            if tokens_per_block <= 0:
+                raise ValueError(
+                    f"group {engine_group_idx} tokens_per_block "
+                    f"{tokens_per_block} must be positive"
+                )
+        # Smallest token count aligned to every group's paged-chunk
+        # boundary; used to round down vLLM APC hit counts.
+        self._hit_alignment_tokens = math.lcm(*self._group_tokens_per_block)
+        if self.role == KVConnectorRole.SCHEDULER:
+            # Chunk boundaries must land on every group's paged-chunk
+            # boundary so per-group block-id slicing stays aligned.
+            lmcache_tokens_per_chunk = self.scheduler_adapter.lmcache_tokens_per_chunk
+            for engine_group_idx, tokens_per_block in enumerate(
+                self._group_tokens_per_block
+            ):
+                if lmcache_tokens_per_chunk % tokens_per_block != 0:
+                    raise ValueError(
+                        f"LMCache chunk size {lmcache_tokens_per_chunk} must be "
+                        f"a multiple of group {engine_group_idx} "
+                        f"tokens_per_block {tokens_per_block}"
+                    )
+
+    @property
+    def role(self) -> KVConnectorRole:
+        return self._role
+
+    # ==============================
+    # Worker-side methods
+    # ==============================
+
+    def _get_connector_metadata(self) -> KVConnectorMetadata:
+        """Get the connector metadata.
+
+        This function should only be called inside the connector.
+
+        Returns:
+            ConnectorMetadata: the connector metadata.
+        """
+
+        # Should only be called while set to valid metadata.
+        assert self._connector_metadata is not None
+        return self._connector_metadata
+
+    def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
+        """
+        Initialize with the KV caches. Useful for pre-registering the
+        KV Caches in the KVConnector (e.g. for NIXL).
+
+        Args:
+            kv_caches: dictionary of layer names, kv cache
+        """
+        logger.info("Registering kv caches!")
+        kv_cache_config = getattr(self, "_kv_cache_config", None)
+        # Must precede both group-info creation and transfer registration so
+        # they see the same edited views.
+        kv_caches = apply_kv_cache_group_edits(kv_cache_config, kv_caches)
+        engine_group_infos = create_engine_group_infos_from_vllm(
+            kv_cache_config,
+            kv_caches,
+            layout_hints=vllm_layout_hints(),
+        )
+        self.worker_adapter.register_kv_caches(
+            kv_caches, engine_group_infos=engine_group_infos
+        )
+        return
+
+    def start_load_kv(self, forward_context: "ForwardContext", **kwargs: Any) -> None:
+        """
+        Start loading the KV cache from the connector to vLLM's paged
+        KV buffer. This is called from the forward context before the
+        forward pass to enable async loading during model execution.
+
+        Args:
+            forward_context (ForwardContext): the forward context.
+            **kwargs: additional arguments for the load operation
+
+        Note:
+            The number of elements in kv_caches and layer_names should be
+            the same.
+
+        """
+        metadata = self._get_connector_metadata()
+        assert isinstance(metadata, LMCacheMPConnectorMetadata)
+
+        request_ids = []
+        ops = []
+        cache_salts = []
+
+        for meta in metadata.requests:
+            if meta.direction != "RETRIEVE":
+                continue
+            request_ids.append(meta.request_id)
+            ops.append(meta.op)
+            cache_salts.append(meta.cache_salt)
+
+        if len(request_ids) == 0:
+            return
+
+        with torch_dev.stream(torch_dev.current_stream()):
+            event = torch_dev.Event(interprocess=True)
+            event.record()
+
+        self.worker_adapter.batched_submit_retrieve_requests(
+            request_ids, ops, event, cache_salts=cache_salts
+        )
+
+    def wait_for_layer_load(self, layer_name: str) -> None:
+        """
+        Block until the KV for a specific layer is loaded into vLLM's
+        paged buffer. This is called from within attention layer to ensure
+        async copying from start_load_kv is complete.
+
+        This interface will be useful for layer-by-layer pipelining.
+
+        Args:
+            layer_name: the name of that layer
+        """
+        return
+
+    def save_kv_layer(
+        self,
+        layer_name: str,
+        kv_layer: torch.Tensor,
+        attn_metadata: AttentionMetadata,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Start saving a layer of KV cache from vLLM's paged buffer
+        to the connector. This is called from within attention layer to
+        enable async copying during execution.
+
+        Args:
+            layer_name (str): the name of the layer.
+            kv_layer (torch.Tensor): the paged KV buffer of the current
+                layer in vLLM.
+            attn_metadata (AttentionMetadata): the attention metadata.
+            **kwargs: additional arguments for the save operation.
+        """
+        return
+
+    def wait_for_save(self):
+        """
+        Block until all the save operations is done. This is called
+        as the forward context exits to ensure that the async saving
+        from save_kv_layer is complete before finishing the forward.
+
+        This prevents overwrites of paged KV buffer before saving done.
+        """
+        metadata = self._get_connector_metadata()
+        assert isinstance(metadata, LMCacheMPConnectorMetadata)
+
+        request_ids = []
+        ops = []
+        cache_salts = []
+        for meta in metadata.requests:
+            if meta.direction != "STORE":
+                continue
+            request_ids.append(meta.request_id)
+            ops.append(meta.op)
+            cache_salts.append(meta.cache_salt)
+
+        if len(request_ids) == 0:
+            return
+
+        with torch_dev.stream(torch_dev.current_stream()):
+            event = torch_dev.Event(interprocess=True)
+            event.record()
+
+        self.worker_adapter.batched_submit_store_requests(
+            request_ids, ops, event, cache_salts=cache_salts
+        )
+
+    # TODO: How does lmcache driven path handle preemption?
+    # NOTE1: handle_preemptions is called by vllm each step regardless
+    #        preemption really happens or not.
+    # NOTE2: preemption hint is managed by KVConnectorRole.SCHEDULER,
+    #        that's why here we have to judge preemption by
+    #        need_flush_before_forward flag which is set by SCHEDULER.
+    def handle_preemptions(self, kv_connector_metadata: KVConnectorMetadata) -> None:
+        """Flush async engine-driven stores only when scheduler metadata requests it.
+
+        Args:
+            kv_connector_metadata: Connector metadata produced by the scheduler;
+                only acts when it is a :class:`LMCacheMPConnectorMetadata` with
+                ``need_flush_before_forward=True``.
+        """
+        worker_adapter = getattr(self, "worker_adapter", None)
+        if self.role != KVConnectorRole.WORKER or worker_adapter is None:
+            return
+        need_flush_before_forward = (
+            isinstance(kv_connector_metadata, LMCacheMPConnectorMetadata)
+            and kv_connector_metadata.need_flush_before_forward
+        )
+        worker_adapter.handle_preemptions(need_flush_before_forward)
+
+    def get_finished(
+        self, finished_req_ids: set[str]
+    ) -> tuple[set[str] | None, set[str] | None]:
+        """
+        Notifies worker-side connector ids of requests that have
+        finished generating tokens on the worker.
+        The scheduler process (via the Executors) will use this output
+        to track which workers are done.
+
+        Returns:
+            ids of requests that have finished asynchronous transfer
+            (requests that previously returned True from request_finished()),
+            tuple of (sending/saving ids, recving/loading ids).
+            The finished saves/sends req ids must belong to a set provided in a
+            call to this method (this call or a prior one).
+        """
+        val = self.worker_adapter.get_finished(finished_req_ids)
+        # logger.error("Finished req ids: %s, %s", val[0], val[1])
+        return val
+
+    def get_block_ids_with_load_errors(self) -> set[int]:
+        """
+        Get the set of block IDs that failed to load.
+
+        Returns:
+            Set of block IDs that encountered load errors.
+            Empty set if no load errors occurred.
+
+        Notes:
+            - Applies to both sync- and async-loading requests.
+            - Async loading: failed blocks may be reported in any forward pass
+              up to and including the pass where the request ID is returned by
+              `get_finished()`. Even if failures occur, the request must still
+              be reported via `get_finished()`, and the failed block IDs must
+              appear here no later than that same pass.
+            - Sync loading: failed blocks should be reported in the forward
+              pass in which they are detected.
+        """
+        return self.worker_adapter.get_block_ids_with_load_errors()
+
+    def shutdown(self):
+        """
+        Shutdown the connector. This is called when the worker process
+        is shutting down to ensure that all the async operations are
+        completed and the connector is cleaned up properly.
+        """
+        if hasattr(self, "worker_adapter"):
+            self.worker_adapter.shutdown()
+        if hasattr(self, "scheduler_adapter"):
+            self.scheduler_adapter.shutdown()
+        return None
+
+    def get_kv_connector_stats(self) -> "KVConnectorStats | None":
+        """
+        Get the KV connector stats collected during the last interval.
+        """
+        return None
+
+    # ==============================
+    # Scheduler-side methods
+    # ==============================
+
+    def get_num_new_matched_tokens(
+        self,
+        request: "Request",
+        num_computed_tokens: int,
+    ) -> tuple[int | None, bool]:
+        """
+        Get number of new tokens that can be loaded from the
+        external KV cache beyond the num_computed_tokens.
+
+        Args:
+            request (Request): the request object.
+            num_computed_tokens (int): the number of locally
+                computed tokens for this request
+
+        Returns:
+            A tuple with the following elements:
+                - An optional number of tokens that can be loaded from the
+                  external KV cache beyond what is already computed.
+                  If None, it means that the connector needs more time to
+                  determine the number of matched tokens, and the scheduler
+                  should query for this request again later.
+                - `True` if external KV cache tokens will be loaded
+                  asynchronously (between scheduler steps). Must be
+                  'False' if the first element is 0.
+
+        Notes:
+            The connector should only consider the largest prefix of prompt-
+            tokens for which KV cache is actually available at the time of the
+            call. If the cache cannot be loaded for some tokens (e.g., due to
+            connectivity issues or eviction), those tokens must not be taken
+            into account.
+        """
+        tracker = self._get_or_create_request_tracker(request)
+        # TODO: support loading KV for preempted requests in the future
+        if request.status == RequestStatus.PREEMPTED:
+            return 0, False
+
+        self.scheduler_adapter.maybe_submit_lookup_request(
+            request.request_id,
+            token_ids=list(request.all_token_ids),
+            cache_salt=tracker.cache_salt,
+        )
+
+        ret = self.scheduler_adapter.check_lookup_result(request.request_id)
+        if ret is None:
+            return None, True
+
+        if ret == 0:
+            return 0, False
+
+        assert ret % self.scheduler_adapter.lmcache_tokens_per_chunk == 0
+
+        # Update num stored tokens for the tracker
+        tracker.increase_num_stored_tokens(ret)
+
+        # Save the vllm and lmcache hit tokens. The vLLM hit count is
+        # rounded down to a boundary aligned for every engine group (e.g.
+        # a full-prompt APC hit reports ``num_prompt_tokens - 1``), so the
+        # retrieve-skip range stays paged-chunk-aligned in all groups.
+        tracker.num_vllm_hit_tokens = (
+            num_computed_tokens
+            // self._hit_alignment_tokens
+            * self._hit_alignment_tokens
+        )
+        tracker.num_lmcache_hit_tokens = ret
+
+        need_to_load = max(0, ret - num_computed_tokens)
+        logger.debug(
+            "vLLM hit is: %d, Need to load is %d", num_computed_tokens, need_to_load
+        )
+        return need_to_load, need_to_load > 0
+
+    def update_state_after_alloc(
+        self, request: "Request", blocks: "KVCacheBlocks", num_external_tokens: int
+    ):
+        """
+        Update KVConnector state after block allocation.
+
+        If get_num_new_matched_tokens previously returned True for a
+        request, this function may be called twice for that same request -
+        first when blocks are allocated for the connector tokens to be
+        asynchronously loaded into, and second when any additional blocks
+        are allocated, after the load/transfer is complete.
+
+        Args:
+            request (Request): the request object.
+            blocks (KVCacheBlocks): the blocks allocated for the request.
+            num_external_tokens (int): the number of tokens that will be
+                loaded from the external KV cache.
+        """
+        # NOTE: `blocks` comes from kv_cache_manager.get_blocks(request_id),
+        # which returns ALL blocks for the request (not just newly allocated).
+        # This function may be called twice for async-load requests:
+        #   1st call: blocks = initial allocation (APC + fresh)
+        #   2nd call: blocks = all blocks
+        #  (initial + newly allocated for remaining tokens)
+        # We must only append the NEW blocks beyond what's already tracked
+        # to avoid duplication, which would corrupt the store path's block indexing.
+        tracker = self._get_request_tracker(request.request_id)
+        block_ids = blocks.get_block_ids() or ()
+
+        # Only append blocks beyond what's already tracked, per engine group.
+        existing_counts = tracker.num_allocated_blocks()
+        new_block_ids: list[list[int]] = []
+        for engine_group_idx, group_blocks in enumerate(block_ids):
+            existing = existing_counts.get(engine_group_idx, 0)
+            new_block_ids.append(list(group_blocks[existing:]))
+        if any(new_block_ids):
+            tracker.append_block_ids(tuple(new_block_ids))
+
+        # Update the state of the tracker
+        condition = tracker.needs_retrieve()
+        if tracker.state == LMCacheMPRequestState.PREFETCHING:
+            # If need to retrieve, change to WAITING_FOR_LOAD
+            # Otherwise, change to READY
+            tracker.state = (
+                LMCacheMPRequestState.WAITING_FOR_LOAD
+                if condition
+                else LMCacheMPRequestState.READY
+            )
+            # Clean up lookup future in scheduler adapter
+            self.scheduler_adapter.cleanup_lookup_result(request.request_id)
+
+            # Free locks on chunks that vLLM already computed and won't
+            # retrieve from LMCache.
+            if tracker.num_lmcache_hit_tokens > 0:
+                if not condition:
+                    # No retrieve needed — free ALL locked chunks
+                    free_end = tracker.num_lmcache_hit_tokens
+                else:
+                    # Note(Roy): Boundary misalignment between vLLM blocks and LMCache
+                    # blocks is handled in free_lookup_locks. It makes sure that if
+                    # the last vLLM computed block ends in the middle of a LMCache
+                    # block, the end LMCache block is not freed (i.e., floor division)
+                    # since it will still be needed by vLLM and such block's lock will
+                    # be freed by vLLM's retrieve.
+                    free_end = tracker.num_vllm_hit_tokens
+
+                if free_end > 0:
+                    self.scheduler_adapter.free_lookup_locks(
+                        token_ids=list(tracker.all_token_ids),
+                        start=0,
+                        end=free_end,
+                        request_id=request.request_id,
+                        cache_salt=tracker.cache_salt,
+                    )
+                    logger.debug(
+                        "Free locks of tokens %d-%d since it is cached by vLLM.",
+                        0,
+                        free_end,
+                    )
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> KVConnectorMetadata:
+        """
+        Build the connector metadata for this step.
+
+        This function should NOT modify fields in the scheduler_output.
+        Also, calling this function will reset the state of the connector.
+
+        Args:
+            scheduler_output (SchedulerOutput): the scheduler output object.
+        """
+        metadata = LMCacheMPConnectorMetadata()
+        metadata.need_flush_before_forward = _has_preemption_reqs(scheduler_output)
+
+        self._process_retrieve_requests(metadata)
+        self._process_new_requests(scheduler_output, metadata)
+        self._process_cached_requests(scheduler_output, metadata)
+
+        if len(metadata) > 0:
+            logger.debug("Final connector metadata: %s", metadata)
+
+        # Report block allocation deltas to LMCache for observability
+        self._report_block_allocation_deltas(scheduler_output)
+
+        return metadata
+
+    def update_connector_output(self, connector_output: KVConnectorOutput):
+        """
+        Update KVConnector state from worker-side connectors output.
+
+        Args:
+            connector_output (KVConnectorOutput): the worker-side
+                connectors output.
+        """
+        return
+
+    def request_finished(
+        self,
+        request: "Request",
+        block_ids: list[int],
+    ) -> tuple[bool, dict[str, Any] | None]:
+        """
+        Called exactly once when a request has finished, before its blocks are
+        freed.
+
+        The connector may assumes responsibility for freeing the blocks
+        asynchronously by returning True.
+
+        Returns:
+            True if the request is being saved/sent asynchronously and blocks
+            should not be freed until the request_id is returned from
+            get_finished().
+            Optional KVTransferParams to be included in the request outputs
+            returned by the engine.
+        """
+
+        params: dict[str, Any] | None = getattr(request, "kv_transfer_params", None)
+        return_params: dict[str, Any] | None = {} if params is not None else None
+
+        if (
+            params is not None
+            and return_params is not None
+            and "cached_token_stats" in params
+        ):
+            request_tracker = self._get_request_tracker(request.request_id)
+            num_vllm = request_tracker.num_vllm_hit_tokens
+            num_lmcache = request_tracker.num_lmcache_hit_tokens
+            return_params["cached_token_stats"] = {
+                "num_vllm_cached_tokens": num_vllm,
+                "num_lmcache_cached_tokens": num_lmcache,
+                "num_lmcache_extra_cached_tokens": max(0, num_lmcache - num_vllm),
+            }
+
+        # Clean up request tracker to prevent memory leak
+        self._cleanup_request_tracker(request.request_id)
+        # Notify LMCache to end the session for this request
+        self.scheduler_adapter.end_session(request.request_id)
+
+        return True, (return_params or None)
+
+    def request_finished_all_groups(
+        self,
+        request: "Request",
+        block_ids: tuple[list[int], ...],
+    ) -> tuple[bool, dict[str, Any] | None]:
+        """HMA request-finished entry point; cleanup is request-id based."""
+        return self.request_finished(request, block_ids[0] if block_ids else [])
+
+    def take_events(self) -> Iterable["KVCacheEvent"]:
+        """
+        Take the KV cache events from the connector.
+
+        Yields:
+            New KV cache events since the last call.
+        """
+        return ()
+
+    @classmethod
+    def get_required_kvcache_layout(cls, vllm_config: "VllmConfig") -> str | None:
+        """
+        Get the required KV cache layout for this connector.
+        Args:
+            vllm_config (VllmConfig): the vllm config.
+
+        Returns:
+            str: the required KV cache layout. e.g. HND, or NHD.
+            None if the connector does not require a specific layout.
+        """
+
+        if cls is KVConnectorBase_V1:
+            raise TypeError(
+                "get_required_kvcache_layout should not be called "
+                "on the abstract base class"
+            )
+        return None
+
+    def get_finished_count(self) -> int | None:
+        """
+        Get the count of requests expected to complete send/receive operations
+        via this connector. This method is used to initialize the
+        KVOutputAggregator, overwriting the default world_size.
+
+        Returns:
+            int: expected sending or receiving completion count.
+        """
+        return None
+
+    @classmethod
+    def build_kv_connector_stats(
+        cls, data: dict[str, Any] | None = None
+    ) -> "KVConnectorStats | None":
+        """
+        KVConnectorStats resolution method. This method allows dynamically
+        registered connectors to return their own KVConnectorStats object,
+        which can implement custom aggregation logic on the data dict.
+        """
+        return None
+
+    @classmethod
+    def build_prom_metrics(
+        cls,
+        vllm_config: "VllmConfig",
+        metric_types: dict[type["PromMetric"], type["PromMetricT"]],
+        labelnames: list[str],
+        per_engine_labelvalues: dict[int, list[object]],
+    ) -> "KVConnectorPromMetrics | None":
+        """
+        Create a KVConnectorPromMetrics subclass which should register
+        per-connector Prometheus metrics and implement observe() to
+        expose connector transfer stats via Prometheus.
+        """
+        return None
+
+    ##############################
+    # Helper functions
+    ##############################
+    def _process_retrieve_requests(
+        self,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        lmcache_tokens_per_chunk = self.scheduler_adapter.lmcache_tokens_per_chunk
+
+        for request_tracker in self.request_trackers.values():
+            if request_tracker.state != LMCacheMPRequestState.WAITING_FOR_LOAD:
+                continue
+            r_metadata = LMCacheMPRequestMetadata.GetRetrieveMetadata(
+                request_tracker,
+                lmcache_tokens_per_chunk,
+                group_tokens_per_block=self._group_tokens_per_block,
+            )
+            if r_metadata is not None:
+                metadata.add_request_metadata(r_metadata)
+            request_tracker.state = LMCacheMPRequestState.READY
+
+    def _process_new_requests(
+        self,
+        scheduler_output: SchedulerOutput,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        lmcache_tokens_per_chunk = self.scheduler_adapter.lmcache_tokens_per_chunk
+
+        for new_request in scheduler_output.scheduled_new_reqs:
+            request_tracker = self._get_request_tracker(new_request.req_id)
+
+            num_new_tokens = scheduler_output.num_scheduled_tokens[new_request.req_id]
+            request_tracker.increase_num_scheduled_tokens(num_new_tokens)
+
+            r_meta = LMCacheMPRequestMetadata.GetStoreMetadata(
+                request_tracker,
+                lmcache_tokens_per_chunk,
+                self._group_tokens_per_block,
+            )
+            if r_meta is not None:
+                metadata.add_request_metadata(r_meta)
+
+    def _process_cached_requests(
+        self,
+        scheduler_output: SchedulerOutput,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        lmcache_tokens_per_chunk = self.scheduler_adapter.lmcache_tokens_per_chunk
+
+        cached_reqs = scheduler_output.scheduled_cached_reqs
+        for idx, request_id in enumerate(cached_reqs.req_ids):
+            request_tracker = self._get_request_tracker(request_id)
+
+            # Update block ids
+            new_block_ids = cached_reqs.new_block_ids[idx] or ()
+            if request_id not in cached_reqs.resumed_req_ids:
+                request_tracker.append_block_ids(new_block_ids)
+
+            # Use the incremental num_scheduled_tokens to
+            # stay consistent with _process_new_requests.
+            num_new_tokens = scheduler_output.num_scheduled_tokens[request_id]
+            request_tracker.increase_num_scheduled_tokens(num_new_tokens)
+
+            r_meta = LMCacheMPRequestMetadata.GetStoreMetadata(
+                request_tracker,
+                lmcache_tokens_per_chunk,
+                self._group_tokens_per_block,
+            )
+
+            if r_meta is not None:
+                metadata.add_request_metadata(r_meta)
+
+    def _report_block_allocation_deltas(
+        self,
+        scheduler_output: SchedulerOutput,
+    ) -> None:
+        """Gather per-request block allocation deltas and report to LMCache.
+
+        For new requests: all allocated_block_ids and token_ids are new.
+        For cached requests: only newly appended block_ids and token_ids.
+        The L0 allocation telemetry is flat today, so HMA reports engine group 0.
+        """
+        records: list[RequestAllocationRecord] = []
+
+        # New requests: send all tokens covering all allocated blocks so
+        # the L0 metrics subscriber can correctly map each block to its
+        # actual token content (not just the newly-scheduled slice).
+        for new_request in scheduler_output.scheduled_new_reqs:
+            tracker = self.request_trackers.get(new_request.req_id)
+            if tracker is None:
+                continue
+            primary_block_ids = tracker.allocated_block_ids.get(0, [])
+            num_blocks = len(primary_block_ids)
+            total_tokens = num_blocks * self._group_tokens_per_block[0]
+            records.append(
+                RequestAllocationRecord(
+                    req_id=new_request.req_id,
+                    new_block_ids=list(primary_block_ids),
+                    new_token_ids=list(tracker.all_token_ids[:total_tokens]),
+                )
+            )
+
+        # Cached requests: only the newly added blocks and their full
+        # token content.  We send all tokens covered by the new blocks
+        # (not just the tokens scheduled this step) so the L0 subscriber
+        # can correctly identify block content.
+        cached_reqs = scheduler_output.scheduled_cached_reqs
+        for idx, request_id in enumerate(cached_reqs.req_ids):
+            # The L0 subscriber works on the primary (group 0) block-id list.
+            new_group_block_ids = cached_reqs.new_block_ids[idx]
+            new_block_ids = new_group_block_ids[0] if new_group_block_ids else []
+            if not new_block_ids:
+                continue
+            tracker = self.request_trackers.get(request_id)
+            if tracker is None:
+                continue
+            # The new blocks sit at the end of the request's block list.
+            # Compute the token range they cover.
+            total_blocks = len(tracker.allocated_block_ids.get(0, []))
+            num_new_blocks = len(new_block_ids)
+            tokens_per_block = self._group_tokens_per_block[0]
+            start_token = (total_blocks - num_new_blocks) * tokens_per_block
+            end_token = total_blocks * tokens_per_block
+            new_token_ids = list(tracker.all_token_ids[start_token:end_token])
+            records.append(
+                RequestAllocationRecord(
+                    req_id=request_id,
+                    new_block_ids=new_block_ids,
+                    new_token_ids=new_token_ids,
+                )
+            )
+
+        if records:
+            self.scheduler_adapter.report_block_allocations(records)
+
+    def _get_request_tracker(self, request_id: str) -> LMCacheMPRequestTracker:
+        assert request_id in self.request_trackers, (
+            f"Request tracker for request_id {request_id} not found. "
+        )
+        return self.request_trackers[request_id]
+
+    def _get_or_create_request_tracker(
+        self, request: "Request"
+    ) -> LMCacheMPRequestTracker:
+        request_id = request.request_id
+        # Remove the old trackers that is created before the preemption
+        if (
+            request.status == RequestStatus.PREEMPTED
+            and request_id in self.request_trackers
+        ):
+            tracker = self.request_trackers[request_id]
+
+            # NOTE: since this function may be called multiple times
+            # for a single request (because get_num_new_matched_tokens
+            # may be called multiple times) for the same request, we
+            # will only do the remove if the tracker is not in the "fresh"
+            # state, i.e., PREFETCHING
+            if tracker.state != LMCacheMPRequestState.PREFETCHING:
+                self.request_trackers.pop(request_id)
+
+        if request_id not in self.request_trackers:
+            new_tracker = LMCacheMPRequestTracker(request)
+            self.request_trackers[request_id] = new_tracker
+        return self.request_trackers[request_id]
+
+    def _cleanup_request_tracker(self, request_id: str) -> None:
+        """
+        Clean up request tracker and associated lookup future for a request.
+        This should be called when a request is finished to prevent memory leak.
+        """
+        # Clean up request tracker
+        if self.request_trackers.pop(request_id, None):
+            logger.debug(
+                "[KVConnector] Cleaned up request_tracker for request %s",
+                request_id,
+            )
diff --git a/lmcache/integration/vllm/lmcache_mp_connector_0180.py b/lmcache/integration/vllm/lmcache_mp_connector_0180.py
new file mode 100644
index 0000000..7799856
--- /dev/null
+++ b/lmcache/integration/vllm/lmcache_mp_connector_0180.py
@@ -0,0 +1,1080 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+import enum
+import inspect
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+import torch
+import zmq
+from lmcache import torch_dev, torch_device_type
+from lmcache.integration.vllm.utils import mla_enabled
+from lmcache.utils import check_interprocess_event_support, init_logger as lmcache_init_logger
+
+from vllm.config import VllmConfig
+from vllm.distributed.kv_transfer.kv_connector.v1.base import (
+    KVConnectorBase_V1,
+    KVConnectorMetadata,
+    KVConnectorRole,
+)
+from vllm.v1.attention.backend import AttentionMetadata
+from vllm.v1.core.sched.output import SchedulerOutput
+from vllm.v1.outputs import KVConnectorOutput
+from vllm.v1.request import RequestStatus
+from vllm.v1.utils import ConstantList
+
+try:
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        LMCacheMPSchedulerAdapter,
+        LMCacheMPWorkerAdapter,
+        LoadStoreOp,
+    )
+except ImportError:
+    from vllm.distributed.kv_transfer.kv_connector.v1.lmcache_integration import (
+        LMCacheMPSchedulerAdapter,
+        LMCacheMPWorkerAdapter,
+        LoadStoreOp,
+    )
+
+if TYPE_CHECKING:
+    from vllm.distributed.kv_events import KVCacheEvent
+    from vllm.distributed.kv_transfer.kv_connector.v1.metrics import (
+        KVConnectorPromMetrics,
+        KVConnectorStats,
+        PromMetric,
+        PromMetricT,
+    )
+    from vllm.forward_context import ForwardContext
+    from vllm.v1.core.kv_cache_manager import KVCacheBlocks
+    from vllm.v1.core.kv_cache_utils import BlockHash
+    from vllm.v1.kv_cache_interface import KVCacheConfig
+    from vllm.v1.request import Request
+
+logger = lmcache_init_logger(__name__)
+
+
+def _adapter_accepts_tp_size() -> bool:
+    """Check if the imported adapter accepts tp_size."""
+    sig = inspect.signature(LMCacheMPSchedulerAdapter.__init__)
+    return "tp_size" in sig.parameters
+
+
+# Helper functions
+def reformat_block_ids(block_ids: tuple[list[int], ...] | None) -> list[int]:
+    if block_ids is None:
+        return []
+    assert isinstance(block_ids, tuple), (
+        f"Expected block_ids to be a tuple of lists, but got {type(block_ids)}"
+    )
+
+    if len(block_ids) > 1:
+        raise RuntimeError(
+            "LMCacheMPConnector only works without hybrid kv cache manager. "
+            "Please pass --disable-hybrid-kv-cache-manager when starting vllm"
+        )
+
+    return block_ids[0]
+
+
+def extract_world_size_and_kv_rank(
+    world_size: int,
+    rank: int,
+    vllm_config: VllmConfig,
+) -> tuple[int, int]:
+    """
+    Convert the rank for the MLA.
+    """
+    use_mla = mla_enabled(vllm_config.model_config)
+    if not use_mla:
+        return world_size, rank
+    else:
+        # Tensor parallel does not change the KV caches for MLA models.
+        # So we need to "exclude" the effect of TP on rank and world size
+        tp_size = vllm_config.parallel_config.tensor_parallel_size
+        # vLLM constructs TP groups first, and then construct other
+        # parallel groups on top of TP groups.
+        # for example, TP=4, PP=2,
+        # TP group: [0, 1, 2, 3], [4, 5, 6, 7]
+        # PP group: [0, 4], [1, 5], [2, 6], [3, 7]
+        # So we can "exclude" the effect of TP by rank // tp_size.
+        return world_size // tp_size, rank // tp_size
+
+
+def create_scheduler_adapter(
+    server_url: str,
+    zmq_context: zmq.Context,
+    vllm_config: VllmConfig,
+    mq_timeout: float,
+    heartbeat_interval: float,
+) -> LMCacheMPSchedulerAdapter:
+    world_size, kv_rank = extract_world_size_and_kv_rank(
+        vllm_config.parallel_config.world_size,
+        vllm_config.parallel_config.rank,
+        vllm_config,
+    )
+    tp_size = vllm_config.parallel_config.tensor_parallel_size
+
+    # Pass tp_size only when the adapter accepts it so that
+    # a newer vllm can still work with an older LMCache.
+    kwargs: dict[str, Any] = {}
+    if _adapter_accepts_tp_size():
+        kwargs["tp_size"] = tp_size
+
+    return LMCacheMPSchedulerAdapter(
+        server_url,
+        zmq_context,
+        vllm_config.model_config.model,
+        world_size,
+        kv_rank,
+        vllm_config.cache_config.block_size,
+        mq_timeout=mq_timeout,
+        heartbeat_interval=heartbeat_interval,
+        **kwargs,
+    )
+
+
+def create_worker_adapter(
+    server_url: str,
+    zmq_context: zmq.Context,
+    vllm_config: VllmConfig,
+    mq_timeout: float,
+    heartbeat_interval: float,
+) -> LMCacheMPWorkerAdapter:
+    world_size, kv_rank = extract_world_size_and_kv_rank(
+        vllm_config.parallel_config.world_size,
+        vllm_config.parallel_config.rank,
+        vllm_config,
+    )
+    extra_config = vllm_config.kv_transfer_config.kv_connector_extra_config
+    return LMCacheMPWorkerAdapter(
+        server_url,
+        zmq_context,
+        vllm_config.model_config.model,
+        world_size,
+        kv_rank,
+        vllm_config.cache_config.block_size,
+        mq_timeout=mq_timeout,
+        heartbeat_interval=heartbeat_interval,
+        extra_config=extra_config,
+    )
+
+
+class LMCacheMPRequestState(enum.Enum):
+    """
+    State machine:
+    PREFETCHING -- update_state_after_alloc --> WAITING_FOR_LOAD
+    WAITING_FOR_LOAD -- process_loading_requests --> READY
+    """
+
+    PREFETCHING = enum.auto()
+    WAITING_FOR_LOAD = enum.auto()
+    READY = enum.auto()
+
+
+@dataclass
+class LMCacheMPRequestTracker:
+    # NOTE: this class used vLLM data structures, should be part of
+    # vLLM integration code
+
+    request_id: str
+
+    # Read-only lists to track the token ids and block hashes
+    all_token_ids: ConstantList[int]
+    block_hashes: ConstantList["BlockHash"]
+
+    # Block ids and hashes will be updated at update_states_after_alloc and
+    # during the generation
+    allocated_block_ids: list[int] = field(default_factory=list)
+
+    # Number of scheduled tokens in this request. We keep tracking this to
+    # avoid saving half-full blocks.
+    num_scheduled_tokens: int = 0
+
+    # Number of blocks stored will be initialized when lookup the external
+    # hit tokens and will be updated when processing new requests and cached
+    # requests.
+    num_stored_blocks: int = 0
+
+    # Staging load operation -- save vllm and lmcache hit tokens during lookup
+    num_vllm_hit_blocks: int = 0
+    num_lmcache_hit_blocks: int = 0
+
+    # Main state
+    state: LMCacheMPRequestState = LMCacheMPRequestState.PREFETCHING
+
+    def __init__(self, request: "Request"):
+        self.request_id = request.request_id
+        self.all_token_ids = request.all_token_ids
+        self.block_hashes = ConstantList(request.block_hashes)
+        self.allocated_block_ids = []
+        self.num_stored_blocks = 0
+        self.num_vllm_hit_blocks = 0
+        self.num_lmcache_hit_blocks = 0
+        self.state = LMCacheMPRequestState.PREFETCHING
+
+    ####
+    # Check the state of the request
+    ####
+    def needs_retrieve(self) -> bool:
+        """Check whether the current request needs retrieve, will be used
+        update_stage_after_alloc"""
+        return (
+            self.num_lmcache_hit_blocks > self.num_vllm_hit_blocks
+            and self.state != LMCacheMPRequestState.READY
+        )
+
+    def is_ready_for_retrieving(self) -> bool:
+        """Check whether the current request is ready for retrieving,
+        will be used in process_loading_requests"""
+        return (
+            self.state == LMCacheMPRequestState.WAITING_FOR_LOAD
+            and self.needs_retrieve()
+        )
+
+    ####
+    # Update internal states
+    ####
+    def increase_num_scheduled_tokens(self, num_new_tokens: int):
+        self.num_scheduled_tokens += num_new_tokens
+
+    def increase_num_stored_blocks(self, num_new_blocks: int):
+        """Increase the number of stored blocks for the current request
+        This function will be called when processing the cached requests.
+        """
+        self.num_stored_blocks += num_new_blocks
+
+    def append_block_ids(
+        self,
+        new_block_ids: list[int],
+    ):
+        """Update the block ids for the current request
+        This function will be called when processing the cached requests.
+        """
+        self.allocated_block_ids.extend(new_block_ids)
+
+    ####
+    # For debugging
+    ####
+    def __repr__(self) -> str:
+        return (
+            f"LMCacheMPRequestTracker(request_id={self.request_id}, "
+            f"num_tokens={len(self.all_token_ids)}, "
+            f"num_block_hashes={len(self.block_hashes)}, "
+            f"num_allocated_blocks={len(self.allocated_block_ids)}, "
+            f"num_stored_blocks={self.num_stored_blocks}, "
+            f"vllm_hit_blocks={self.num_vllm_hit_blocks}, "
+            f"lmcache_hit_blocks={self.num_lmcache_hit_blocks}, "
+            f"state={self.state})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+@dataclass
+class LMCacheMPRequestMetadata:
+    request_id: str
+    direction: Literal["STORE", "RETRIEVE"]
+    op: LoadStoreOp
+
+    @staticmethod
+    def GetStoreMetadata(
+        tracker: LMCacheMPRequestTracker,
+        blocks_in_chunk: int,
+        vllm_block_size: int,
+    ) -> "LMCacheMPRequestMetadata | None":
+        """
+        Generate the store metadata for the current request tracker.
+
+        Args:
+            tracker: The request tracker to generate the metadata from.
+            blocks_in_chunk: the number of blocks in a LMCache data chunk
+            vllm_block_size: the block size used in vLLM
+        """
+        # Store the blocks that has block hashes
+        # NOTE: the invariant here is that `num_stored_blocks` should
+        # always be a multiple of `blocks_in_chunk`
+        # TODO: This should be checked everytime we update the num_stored_blocks
+        #
+        # Why computed_blocks uses max(num_vllm_hit_blocks, num_lmcache_hit_blocks):
+        #
+        # Both values represent a prefix of blocks whose KV data is already
+        # available (either from vLLM APC or from LMCache), so they must NOT
+        # be summed (that would double-count the overlapping prefix).
+        #
+        # * num_lmcache_hit_blocks: LMCache-hit blocks are already counted in
+        #   num_stored_blocks (set during lookup), so they must be included
+        #   here to keep the upper bound consistent.  They are NOT re-stored.
+        # * num_vllm_hit_blocks: LMCache stores in units of chunks (N blocks),
+        #   so num_lmcache_hit_blocks is rounded DOWN to the nearest chunk
+        #   boundary.  When vLLM APC hits more blocks than that rounded value
+        #   (e.g. APC=44 blocks, LMCache=32 blocks after chunk alignment),
+        #   using only num_lmcache_hit_blocks would set the upper bound too
+        #   low and silently skip the APC-hit blocks that fall between the
+        #   two values, causing under-storing.  Taking the max ensures we
+        #   always use the tighter (larger) of the two hit counts.
+        computed_blocks = tracker.num_scheduled_tokens // vllm_block_size + max(
+            tracker.num_vllm_hit_blocks, tracker.num_lmcache_hit_blocks
+        )
+        min_available_blocks = min(
+            len(tracker.block_hashes),
+            len(tracker.allocated_block_ids),
+            computed_blocks,
+        )
+        num_staging_blocks = min_available_blocks - tracker.num_stored_blocks
+        num_chunks = num_staging_blocks // blocks_in_chunk
+
+        if num_chunks >= 1:
+            start = tracker.num_stored_blocks
+            end = start + num_chunks * blocks_in_chunk
+            block_ids = tracker.allocated_block_ids[start:end]
+            start_token_idx = start * vllm_block_size
+            end_token_idx = end * vllm_block_size
+            token_ids = list(tracker.all_token_ids)
+            op = LoadStoreOp(
+                token_ids=token_ids,
+                block_ids=block_ids,
+                start=start_token_idx,
+                end=end_token_idx,
+            )
+
+            ret = LMCacheMPRequestMetadata(
+                request_id=tracker.request_id,
+                direction="STORE",
+                op=op,
+            )
+
+            # Update the request tracker
+            tracker.increase_num_stored_blocks(end - start)
+            return ret
+
+        return None
+
+    @staticmethod
+    def GetRetrieveMetadata(
+        tracker: LMCacheMPRequestTracker,
+        blocks_in_chunk: int,
+        vllm_block_size: int,
+    ) -> "LMCacheMPRequestMetadata | None":
+        """
+        Generate the retrieve metadata for the current request tracker.
+
+        Args:
+            tracker: The request tracker to generate the metadata from.
+            blocks_in_chunk: the number of blocks in a LMCache data chunk
+            vllm_block_size: the block size used in vLLM
+        """
+        if not tracker.is_ready_for_retrieving():
+            return None
+
+        # |---------------------|-----------------|----------------|
+        # | num_vllm_hit_blocks |
+        # | lmcache chunk 1   | lmcache chunk 2   |
+        #                     |  need to retrieve |
+
+        start = tracker.num_vllm_hit_blocks // blocks_in_chunk * blocks_in_chunk
+        end = tracker.num_lmcache_hit_blocks
+        assert end % blocks_in_chunk == 0, (
+            "The number of LMCache hit blocks should be a multiple of the "
+            "number of blocks in a lmcache chunk. "
+        )
+        assert len(tracker.block_hashes) >= end, (
+            "The number of block hashes should be greater than or equal to the "
+            "number of LMCache hit blocks. "
+        )
+        if end > start:
+            block_ids = tracker.allocated_block_ids[start:end]
+            start_token_idx = start * vllm_block_size
+            end_token_idx = end * vllm_block_size
+            token_ids = list(tracker.all_token_ids)
+
+            # Compute how many tokens at the start of the retrieve range
+            # overlap with APC-shared blocks. The server must skip writing
+            # to these positions to avoid a cross-stream data race: the
+            # retrieve writes on the LMCache CUDA stream while concurrent
+            # requests may read these APC-shared blocks on the vLLM stream.
+            apc_overlap_blocks = tracker.num_vllm_hit_blocks - start
+            skip_first_n_tokens = apc_overlap_blocks * vllm_block_size
+
+            op = LoadStoreOp(
+                token_ids=token_ids,
+                block_ids=block_ids,
+                start=start_token_idx,
+                end=end_token_idx,
+                skip_first_n_tokens=skip_first_n_tokens,
+            )
+
+            ret = LMCacheMPRequestMetadata(
+                request_id=tracker.request_id,
+                direction="RETRIEVE",
+                op=op,
+            )
+            return ret
+
+        return None
+
+
+class LMCacheMPConnectorMetadata(KVConnectorMetadata):
+    def __init__(self):
+        super().__init__()
+        self.requests: list[LMCacheMPRequestMetadata] = []
+
+    def add_request_metadata(self, request_metadata: LMCacheMPRequestMetadata):
+        self.requests.append(request_metadata)
+
+    def __len__(self):
+        return len(self.requests)
+
+    # For debugging
+    def __str__(self):
+        request_strs = []
+        for req_meta in self.requests:
+            request_strs.append(
+                f"RequestMetadata(request_id={req_meta.request_id}, "
+                f"direction={req_meta.direction}, "
+                f"num_blocks={len(req_meta.op.flat_block_ids)}, "
+                f"block_ids={req_meta.op.block_ids})"
+            )
+        return "[" + "\n".join(request_strs) + "]"
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class LMCacheMPConnector(KVConnectorBase_V1):
+    """
+    The connector for LMCache multi-process mode.
+
+    Extra configs (kv_transfer_config.extra_config):
+    - lmcache.mp.host: the host of the LMCache server.
+    - lmcache.mp.port: the port of the LMCache server.
+    - lmcache.mp.mq_timeout: timeout (seconds) for message queue requests.
+    - lmcache.mp.heartbeat_interval: interval (seconds) between server
+      heartbeat pings.
+    - lmcache.mp.mp_transfer_mode: routing mode for the worker -> server
+      transfer context. One of ``auto`` (default; CUDA -> engine_driven,
+      others -> lmcache_driven), ``engine_driven`` (force IPC / SHM
+      zero-copy), ``lmcache_driven`` (force worker-side gather/scatter
+      copy). Overrides the ``LMCACHE_MP_TRANSFER_MODE`` env var when set.
+    """
+
+    def __init__(
+        self,
+        vllm_config: "VllmConfig",
+        role: KVConnectorRole,
+        kv_cache_config: "KVCacheConfig | None" = None,
+    ):
+        super().__init__(vllm_config, role, kv_cache_config)
+
+        # fast-fail if interprocess is not supported
+        check_interprocess_event_support()
+
+        assert vllm_config.kv_transfer_config is not None
+        server_host = vllm_config.kv_transfer_config.get_from_extra_config(
+            "lmcache.mp.host", "tcp://localhost"
+        )
+        server_port = vllm_config.kv_transfer_config.get_from_extra_config(
+            "lmcache.mp.port", 5555
+        )
+        mq_timeout = float(
+            vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.mp.mq_timeout", 300.0
+            )
+        )
+        heartbeat_interval = float(
+            vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.mp.heartbeat_interval", 10.0
+            )
+        )
+
+        server_url = f"{server_host}:{server_port}"
+        zmq_context = zmq.Context.instance()
+        if self.role == KVConnectorRole.SCHEDULER:
+            self.scheduler_adapter = create_scheduler_adapter(
+                server_url,
+                zmq_context,
+                vllm_config,
+                mq_timeout,
+                heartbeat_interval,
+            )
+            self.request_trackers: dict[str, LMCacheMPRequestTracker] = {}
+        elif self.role == KVConnectorRole.WORKER:
+            self.worker_adapter = create_worker_adapter(
+                server_url,
+                zmq_context,
+                vllm_config,
+                mq_timeout,
+                heartbeat_interval,
+            )
+        else:
+            raise ValueError(f"Unknown KVConnectorRole: {self.role}")
+
+        self.vllm_block_size = vllm_config.cache_config.block_size
+
+    @property
+    def role(self) -> KVConnectorRole:
+        return self._role
+
+    # ==============================
+    # Worker-side methods
+    # ==============================
+
+    def _get_connector_metadata(self) -> KVConnectorMetadata:
+        """Get the connector metadata.
+
+        This function should only be called inside the connector.
+
+        Returns:
+            ConnectorMetadata: the connector metadata.
+        """
+
+        # Should only be called while set to valid metadata.
+        assert self._connector_metadata is not None
+        return self._connector_metadata
+
+    def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
+        """
+        Initialize with the KV caches. Useful for pre-registering the
+        KV Caches in the KVConnector (e.g. for NIXL).
+
+        Args:
+            kv_caches: dictionary of layer names, kv cache
+        """
+        logger.info("Registering kv caches!")
+        self.worker_adapter.register_kv_caches(kv_caches)
+        return
+
+    def start_load_kv(self, forward_context: "ForwardContext", **kwargs: Any) -> None:
+        """
+        Start loading the KV cache from the connector to vLLM's paged
+        KV buffer. This is called from the forward context before the
+        forward pass to enable async loading during model execution.
+
+        Args:
+            forward_context (ForwardContext): the forward context.
+            **kwargs: additional arguments for the load operation
+        """
+        metadata = self._get_connector_metadata()
+        assert isinstance(metadata, LMCacheMPConnectorMetadata)
+
+        request_ids = []
+        ops = []
+
+        for meta in metadata.requests:
+            if meta.direction != "RETRIEVE":
+                continue
+            request_ids.append(meta.request_id)
+            ops.append(meta.op)
+
+        if len(request_ids) == 0:
+            return
+
+        with torch_dev.stream(torch_dev.current_stream()):
+            # Not all backends support interprocess Events (CUDA IPC specific)
+            event = torch_dev.Event(interprocess=True)
+            event.record()
+
+        self.worker_adapter.batched_submit_retrieve_requests(request_ids, ops, event)
+
+    def wait_for_layer_load(self, layer_name: str) -> None:
+        """
+        Block until the KV for a specific layer is loaded into vLLM's
+        paged buffer. This is called from within attention layer to ensure
+        async copying from start_load_kv is complete.
+
+        This interface will be useful for layer-by-layer pipelining.
+
+        Args:
+            layer_name: the name of that layer
+        """
+        return
+
+    def save_kv_layer(
+        self,
+        layer_name: str,
+        kv_layer: torch.Tensor,
+        attn_metadata: AttentionMetadata,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Start saving a layer of KV cache from vLLM's paged buffer
+        to the connector. This is called from within attention layer to
+        enable async copying during execution.
+
+        Args:
+            layer_name (str): the name of the layer.
+            kv_layer (torch.Tensor): the paged KV buffer of the current
+                layer in vLLM.
+            attn_metadata (AttentionMetadata): the attention metadata.
+            **kwargs: additional arguments for the save operation.
+        """
+        return
+
+    def wait_for_save(self):
+        """
+        Block until all the save operations is done. This is called
+        as the forward context exits to ensure that the async saving
+        from save_kv_layer is complete before finishing the forward.
+
+        This prevents overwrites of paged KV buffer before saving done.
+        """
+        metadata = self._get_connector_metadata()
+        assert isinstance(metadata, LMCacheMPConnectorMetadata)
+
+        request_ids = []
+        ops = []
+        for meta in metadata.requests:
+            if meta.direction != "STORE":
+                continue
+            request_ids.append(meta.request_id)
+            ops.append(meta.op)
+
+        if len(request_ids) == 0:
+            return
+
+        with torch_dev.stream(torch_dev.current_stream()):
+            # Not all backends support interprocess Events (CUDA IPC specific)
+            event = torch_dev.Event(interprocess=True)
+            event.record()
+
+        self.worker_adapter.batched_submit_store_requests(request_ids, ops, event)
+
+    def get_finished(
+        self, finished_req_ids: set[str]
+    ) -> tuple[set[str] | None, set[str] | None]:
+        """
+        Notifies worker-side connector ids of requests that have
+        finished generating tokens on the worker.
+        The scheduler process (via the Executors) will use this output
+        to track which workers are done.
+
+        Returns:
+            ids of requests that have finished asynchronous transfer
+            (requests that previously returned True from request_finished()),
+            tuple of (sending/saving ids, recving/loading ids).
+            The finished saves/sends req ids must belong to a set provided in a
+            call to this method (this call or a prior one).
+        """
+        val = self.worker_adapter.get_finished(finished_req_ids)
+        # logger.error("Finished req ids: %s, %s", val[0], val[1])
+        return val
+
+    def get_block_ids_with_load_errors(self) -> set[int]:
+        """
+        Get the set of block IDs that failed to load.
+
+        Returns:
+            Set of block IDs that encountered load errors.
+            Empty set if no load errors occurred.
+
+        Notes:
+            - Applies to both sync- and async-loading requests.
+            - Async loading: failed blocks may be reported in any forward pass
+              up to and including the pass where the request ID is returned by
+              `get_finished()`. Even if failures occur, the request must still
+              be reported via `get_finished()`, and the failed block IDs must
+              appear here no later than that same pass.
+            - Sync loading: failed blocks should be reported in the forward
+              pass in which they are detected.
+        """
+        return self.worker_adapter.get_block_ids_with_load_errors()
+
+    def shutdown(self):
+        """
+        Shutdown the connector. This is called when the worker process
+        is shutting down to ensure that all the async operations are
+        completed and the connector is cleaned up properly.
+        """
+        if hasattr(self, "worker_adapter"):
+            self.worker_adapter.shutdown()
+        return None
+
+    def get_kv_connector_stats(self) -> "KVConnectorStats | None":
+        """
+        Get the KV connector stats collected during the last interval.
+        """
+        return None
+
+    # ==============================
+    # Scheduler-side methods
+    # ==============================
+
+    def get_num_new_matched_tokens(
+        self,
+        request: "Request",
+        num_computed_tokens: int,
+    ) -> tuple[int | None, bool]:
+        """
+        Get number of new tokens that can be loaded from the
+        external KV cache beyond the num_computed_tokens.
+
+        Args:
+            request (Request): the request object.
+            num_computed_tokens (int): the number of locally
+                computed tokens for this request
+
+        Returns:
+            A tuple with the following elements:
+                - An optional number of tokens that can be loaded from the
+                  external KV cache beyond what is already computed.
+                  If None, it means that the connector needs more time to
+                  determine the number of matched tokens, and the scheduler
+                  should query for this request again later.
+                - `True` if external KV cache tokens will be loaded
+                  asynchronously (between scheduler steps). Must be
+                  'False' if the first element is 0.
+
+        Notes:
+            The connector should only consider the largest prefix of prompt-
+            tokens for which KV cache is actually available at the time of the
+            call. If the cache cannot be loaded for some tokens (e.g., due to
+            connectivity issues or eviction), those tokens must not be taken
+            into account.
+        """
+        tracker = self._get_or_create_request_tracker(request)
+        # TODO: support loading KV for preempted requests in the future
+        if request.status == RequestStatus.PREEMPTED:
+            return 0, False
+
+        self.scheduler_adapter.maybe_submit_lookup_request(
+            request.request_id,
+            token_ids=list(request.all_token_ids),
+        )
+
+        ret = self.scheduler_adapter.check_lookup_result(request.request_id)
+        if ret is None:
+            return None, True
+
+        if ret == 0:
+            return 0, False
+
+        assert (
+            ret % (self.scheduler_adapter.num_blocks_per_chunk() * self.vllm_block_size)
+            == 0
+        )
+
+        # Update num stored blocks for the tracker
+        num_vllm_blocks = num_computed_tokens // self.vllm_block_size
+        num_lmcache_blocks = ret // self.vllm_block_size
+        tracker.increase_num_stored_blocks(num_lmcache_blocks)
+
+        # Save the vllm and lmcache hit tokens
+        tracker.num_vllm_hit_blocks = num_vllm_blocks
+        tracker.num_lmcache_hit_blocks = num_lmcache_blocks
+
+        need_to_load = max(0, ret - num_computed_tokens)
+        logger.debug(
+            "vLLM hit is: %d, Need to load is %d", num_computed_tokens, need_to_load
+        )
+        return need_to_load, need_to_load > 0
+
+    def update_state_after_alloc(
+        self, request: "Request", blocks: "KVCacheBlocks", num_external_tokens: int
+    ):
+        """
+        Update KVConnector state after block allocation.
+
+        If get_num_new_matched_tokens previously returned True for a
+        request, this function may be called twice for that same request -
+        first when blocks are allocated for the connector tokens to be
+        asynchronously loaded into, and second when any additional blocks
+        are allocated, after the load/transfer is complete.
+
+        Args:
+            request (Request): the request object.
+            blocks (KVCacheBlocks): the blocks allocated for the request.
+            num_external_tokens (int): the number of tokens that will be
+                loaded from the external KV cache.
+        """
+        # NOTE: `blocks` comes from kv_cache_manager.get_blocks(request_id),
+        # which returns ALL blocks for the request (not just newly allocated).
+        # This function may be called twice for async-load requests:
+        #   1st call: blocks = initial allocation (APC + fresh)
+        #   2nd call: blocks = all blocks
+        #  (initial + newly allocated for remaining tokens)
+        # We must only append the NEW blocks beyond what's already tracked
+        # to avoid duplication, which would corrupt the store path's block indexing.
+        tracker = self._get_request_tracker(request.request_id)
+        block_ids = reformat_block_ids(blocks.get_block_ids())
+
+        # Only append blocks beyond what's already tracked
+        existing_count = len(tracker.allocated_block_ids)
+        new_block_ids = block_ids[existing_count:]
+        if new_block_ids:
+            tracker.append_block_ids(new_block_ids)
+
+        # Update the state of the tracker
+        condition = tracker.needs_retrieve()
+        if tracker.state == LMCacheMPRequestState.PREFETCHING:
+            # If need to retrieve, change to WAITING_FOR_LOAD
+            # Otherwise, change to READY
+            tracker.state = (
+                LMCacheMPRequestState.WAITING_FOR_LOAD
+                if condition
+                else LMCacheMPRequestState.READY
+            )
+            # Clean up lookup future in scheduler adapter
+            self.scheduler_adapter.cleanup_lookup_result(request.request_id)
+
+            # Free locks on chunks that vLLM already computed and won't
+            # retrieve from LMCache.
+            if tracker.num_lmcache_hit_blocks > 0:
+                if not condition:
+                    # No retrieve needed — free ALL locked chunks
+                    free_end = tracker.num_lmcache_hit_blocks * self.vllm_block_size
+                else:
+                    # Note(Roy): Boundary misalignment between vLLM blocks and LMCache
+                    # blocks is handled in free_lookup_locks. It makes sure that if
+                    # the last vLLM computed block ends in the middle of a LMCache
+                    # block, the end LMCache block is not freed (i.e., floor division)
+                    # since it will still be needed by vLLM and such block's lock will
+                    # be freed by vLLM's retrieve.
+                    free_end = tracker.num_vllm_hit_blocks * self.vllm_block_size
+
+                if free_end > 0:
+                    self.scheduler_adapter.free_lookup_locks(
+                        token_ids=list(tracker.all_token_ids),
+                        start=0,
+                        end=free_end,
+                        request_id=request.request_id,
+                    )
+                    logger.debug(
+                        "Free locks of tokens %d-%d since it is cached by vLLM.",
+                        0,
+                        free_end,
+                    )
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> KVConnectorMetadata:
+        """
+        Build the connector metadata for this step.
+
+        This function should NOT modify fields in the scheduler_output.
+        Also, calling this function will reset the state of the connector.
+
+        Args:
+            scheduler_output (SchedulerOutput): the scheduler output object.
+        """
+        metadata = LMCacheMPConnectorMetadata()
+
+        self._process_retrieve_requests(metadata)
+        self._process_new_requests(scheduler_output, metadata)
+        self._process_cached_requests(scheduler_output, metadata)
+
+        if len(metadata) > 0:
+            logger.debug("Final connector metadata: %s", metadata)
+
+        return metadata
+
+    def update_connector_output(self, connector_output: KVConnectorOutput):
+        """
+        Update KVConnector state from worker-side connectors output.
+
+        Args:
+            connector_output (KVConnectorOutput): the worker-side
+                connectors output.
+        """
+        return
+
+    def request_finished(
+        self,
+        request: "Request",
+        block_ids: list[int],
+    ) -> tuple[bool, dict[str, Any] | None]:
+        """
+        Called exactly once when a request has finished, before its blocks are
+        freed.
+
+        The connector may assumes responsibility for freeing the blocks
+        asynchronously by returning True.
+
+        Returns:
+            True if the request is being saved/sent asynchronously and blocks
+            should not be freed until the request_id is returned from
+            get_finished().
+            Optional KVTransferParams to be included in the request outputs
+            returned by the engine.
+        """
+        # Clean up request tracker to prevent memory leak
+        self._cleanup_request_tracker(request.request_id)
+        # Notify LMCache to end the session for this request
+        self.scheduler_adapter.end_session(request.request_id)
+
+        return True, None
+
+    def take_events(self) -> Iterable["KVCacheEvent"]:
+        """
+        Take the KV cache events from the connector.
+
+        Yields:
+            New KV cache events since the last call.
+        """
+        return ()
+
+    @classmethod
+    def get_required_kvcache_layout(cls, vllm_config: "VllmConfig") -> str | None:
+        """
+        Get the required KV cache layout for this connector.
+        Args:
+            vllm_config (VllmConfig): the vllm config.
+
+        Returns:
+            str: the required KV cache layout. e.g. HND, or NHD.
+            None if the connector does not require a specific layout.
+        """
+
+        if cls is KVConnectorBase_V1:
+            raise TypeError(
+                "get_required_kvcache_layout should not be called "
+                "on the abstract base class"
+            )
+        return None
+
+    def get_finished_count(self) -> int | None:
+        """
+        Get the count of requests expected to complete send/receive operations
+        via this connector. This method is used to initialize the
+        KVOutputAggregator, overwriting the default world_size.
+
+        Returns:
+            int: expected sending or receiving completion count.
+        """
+        return None
+
+    @classmethod
+    def build_kv_connector_stats(
+        cls, data: dict[str, Any] | None = None
+    ) -> "KVConnectorStats | None":
+        """
+        KVConnectorStats resolution method. This method allows dynamically
+        registered connectors to return their own KVConnectorStats object,
+        which can implement custom aggregation logic on the data dict.
+        """
+        return None
+
+    @classmethod
+    def build_prom_metrics(
+        cls,
+        vllm_config: "VllmConfig",
+        metric_types: dict[type["PromMetric"], type["PromMetricT"]],
+        labelnames: list[str],
+        per_engine_labelvalues: dict[int, list[object]],
+    ) -> "KVConnectorPromMetrics | None":
+        """
+        Create a KVConnectorPromMetrics subclass which should register
+        per-connector Prometheus metrics and implement observe() to
+        expose connector transfer stats via Prometheus.
+        """
+        return None
+
+    ##############################
+    # Helper functions
+    ##############################
+    def _process_retrieve_requests(
+        self,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        blocks_per_chunk = self.scheduler_adapter.num_blocks_per_chunk()
+
+        for request_tracker in self.request_trackers.values():
+            if request_tracker.state != LMCacheMPRequestState.WAITING_FOR_LOAD:
+                continue
+            r_metadata = LMCacheMPRequestMetadata.GetRetrieveMetadata(
+                request_tracker,
+                blocks_per_chunk,
+                vllm_block_size=self.vllm_block_size,
+            )
+            if r_metadata is not None:
+                metadata.add_request_metadata(r_metadata)
+            request_tracker.state = LMCacheMPRequestState.READY
+
+    def _process_new_requests(
+        self,
+        scheduler_output: SchedulerOutput,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        blocks_per_chunk = self.scheduler_adapter.num_blocks_per_chunk()
+
+        for new_request in scheduler_output.scheduled_new_reqs:
+            request_tracker = self._get_request_tracker(new_request.req_id)
+
+            num_new_tokens = scheduler_output.num_scheduled_tokens[new_request.req_id]
+            request_tracker.increase_num_scheduled_tokens(num_new_tokens)
+
+            r_meta = LMCacheMPRequestMetadata.GetStoreMetadata(
+                request_tracker, blocks_per_chunk, self.vllm_block_size
+            )
+            if r_meta is not None:
+                metadata.add_request_metadata(r_meta)
+
+    def _process_cached_requests(
+        self,
+        scheduler_output: SchedulerOutput,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        blocks_per_chunk = self.scheduler_adapter.num_blocks_per_chunk()
+
+        cached_reqs = scheduler_output.scheduled_cached_reqs
+        for idx, request_id in enumerate(cached_reqs.req_ids):
+            request_tracker = self._get_request_tracker(request_id)
+
+            # Update block ids
+            new_block_ids = reformat_block_ids(cached_reqs.new_block_ids[idx])
+            if request_id not in cached_reqs.resumed_req_ids:
+                request_tracker.append_block_ids(new_block_ids)
+
+            # Use the incremental num_scheduled_tokens to
+            # stay consistent with _process_new_requests.
+            num_new_tokens = scheduler_output.num_scheduled_tokens[request_id]
+            request_tracker.increase_num_scheduled_tokens(num_new_tokens)
+
+            r_meta = LMCacheMPRequestMetadata.GetStoreMetadata(
+                request_tracker, blocks_per_chunk, self.vllm_block_size
+            )
+
+            if r_meta is not None:
+                metadata.add_request_metadata(r_meta)
+
+    def _get_request_tracker(self, request_id: str) -> LMCacheMPRequestTracker:
+        assert request_id in self.request_trackers, (
+            f"Request tracker for request_id {request_id} not found. "
+        )
+        return self.request_trackers[request_id]
+
+    def _get_or_create_request_tracker(
+        self, request: "Request"
+    ) -> LMCacheMPRequestTracker:
+        request_id = request.request_id
+        # Remove the old trackers that is created before the preemption
+        if (
+            request.status == RequestStatus.PREEMPTED
+            and request_id in self.request_trackers
+        ):
+            tracker = self.request_trackers[request_id]
+
+            # NOTE: since this function may be called multiple times
+            # for a single request (because get_num_new_matched_tokens
+            # may be called multiple times) for the same request, we
+            # will only do the remove if the tracker is not in the "fresh"
+            # state, i.e., PREFETCHING
+            if tracker.state != LMCacheMPRequestState.PREFETCHING:
+                self.request_trackers.pop(request_id)
+
+        if request_id not in self.request_trackers:
+            new_tracker = LMCacheMPRequestTracker(request)
+            self.request_trackers[request_id] = new_tracker
+        return self.request_trackers[request_id]
+
+    def _cleanup_request_tracker(self, request_id: str) -> None:
+        """
+        Clean up request tracker and associated lookup future for a request.
+        This should be called when a request is finished to prevent memory leak.
+        """
+        # Clean up request tracker
+        if self.request_trackers.pop(request_id, None):
+            logger.debug(
+                "[KVConnector] Cleaned up request_tracker for request %s",
+                request_id,
+            )
diff --git a/lmcache/integration/vllm/lmcache_mp_connector_0201.py b/lmcache/integration/vllm/lmcache_mp_connector_0201.py
new file mode 100644
index 0000000..5856a46
--- /dev/null
+++ b/lmcache/integration/vllm/lmcache_mp_connector_0201.py
@@ -0,0 +1,1201 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+import enum
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal
+
+import torch
+import zmq
+from lmcache import torch_dev, torch_device_type
+from lmcache.integration.vllm.utils import mla_enabled
+from lmcache.utils import init_logger as lmcache_init_logger
+from lmcache.utils import check_interprocess_event_support
+
+from vllm.config import VllmConfig
+from vllm.distributed.kv_transfer.kv_connector.v1.base import (
+    KVConnectorBase_V1,
+    KVConnectorMetadata,
+    KVConnectorRole,
+)
+from vllm.v1.attention.backend import AttentionMetadata
+from vllm.v1.core.sched.output import SchedulerOutput
+from vllm.v1.outputs import KVConnectorOutput
+from vllm.v1.request import RequestStatus
+from vllm.v1.utils import ConstantList
+
+try:
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        LMCacheMPSchedulerAdapter,
+        LMCacheMPWorkerAdapter,
+        LoadStoreOp,
+        ParallelStrategy,
+    )
+
+    try:
+        from lmcache.v1.multiprocess.custom_types import RequestAllocationRecord
+    except ImportError:
+        from lmcache.v1.multiprocess.custom_types import (
+            BlockAllocationRecord as RequestAllocationRecord,
+        )
+except ImportError:
+    from lmcache.v1.multiprocess.custom_types import (
+        BlockAllocationRecord as RequestAllocationRecord,
+    )
+
+    from vllm.distributed.kv_transfer.kv_connector.v1.lmcache_integration import (
+        LMCacheMPSchedulerAdapter,
+        LMCacheMPWorkerAdapter,
+        LoadStoreOp,
+        ParallelStrategy,
+    )
+
+if TYPE_CHECKING:
+    from vllm.distributed.kv_events import KVCacheEvent
+    from vllm.distributed.kv_transfer.kv_connector.v1.metrics import (
+        KVConnectorPromMetrics,
+        KVConnectorStats,
+        PromMetric,
+        PromMetricT,
+    )
+    from vllm.forward_context import ForwardContext
+    from vllm.v1.core.kv_cache_manager import KVCacheBlocks
+    from vllm.v1.core.kv_cache_utils import BlockHash
+    from vllm.v1.kv_cache_interface import KVCacheConfig
+    from vllm.v1.request import Request
+
+logger = lmcache_init_logger(__name__)
+
+
+# Helper functions
+def reformat_block_ids(block_ids: tuple[list[int], ...] | None) -> list[int]:
+    if block_ids is None:
+        return []
+    assert isinstance(block_ids, tuple), (
+        f"Expected block_ids to be a tuple of lists, but got {type(block_ids)}"
+    )
+
+    if len(block_ids) > 1:
+        raise RuntimeError(
+            "LMCacheMPConnector only works without hybrid kv cache manager. "
+            "Please pass --disable-hybrid-kv-cache-manager when starting vllm"
+        )
+
+    return block_ids[0]
+
+
+def extract_world_size_and_kv_rank(
+    world_size: int,
+    rank: int,
+    vllm_config: VllmConfig,
+) -> tuple[int, int]:
+    """
+    Convert the rank for the MLA.
+    """
+    use_mla = mla_enabled(vllm_config.model_config)
+    if not use_mla:
+        return world_size, rank
+    else:
+        # Tensor parallel does not change the KV caches for MLA models.
+        # So we need to "exclude" the effect of TP on rank and world size
+        tp_size = vllm_config.parallel_config.tensor_parallel_size
+        # vLLM constructs TP groups first, and then construct other
+        # parallel groups on top of TP groups.
+        # for example, TP=4, PP=2,
+        # PP group: [0, 1, 2, 3], [4, 5, 6, 7]
+        # TP group: [0, 4], [1, 5], [2, 6], [3, 7]
+        # So we can "exclude" the effect of TP by rank // tp_size.
+        return world_size // tp_size, rank // tp_size
+
+
+def create_scheduler_adapter(
+    server_url: str,
+    zmq_context: zmq.Context,
+    vllm_config: VllmConfig,
+    mq_timeout: float,
+    heartbeat_interval: float,
+) -> LMCacheMPSchedulerAdapter:
+    world_size, kv_rank = extract_world_size_and_kv_rank(
+        vllm_config.parallel_config.world_size,
+        vllm_config.parallel_config.rank,
+        vllm_config,
+    )
+    parallel_strategy = ParallelStrategy(
+        mla_enabled(vllm_config.model_config),
+        world_size,
+        kv_rank,
+        vllm_config.parallel_config.world_size,
+        vllm_config.parallel_config.rank,
+        vllm_config.parallel_config.tensor_parallel_size,
+        vllm_config.parallel_config.pipeline_parallel_size,
+    )
+
+    return LMCacheMPSchedulerAdapter(
+        server_url=server_url,
+        context=zmq_context,
+        model_name=vllm_config.model_config.model,
+        vllm_block_size=vllm_config.cache_config.block_size,
+        parallel_strategy=parallel_strategy,
+        mq_timeout=mq_timeout,
+        heartbeat_interval=heartbeat_interval,
+    )
+
+
+def create_worker_adapter(
+    server_url: str,
+    zmq_context: zmq.Context,
+    vllm_config: VllmConfig,
+    mq_timeout: float,
+    heartbeat_interval: float,
+) -> LMCacheMPWorkerAdapter:
+    world_size, kv_rank = extract_world_size_and_kv_rank(
+        vllm_config.parallel_config.world_size,
+        vllm_config.parallel_config.rank,
+        vllm_config,
+    )
+    parallel_strategy = ParallelStrategy(
+        mla_enabled(vllm_config.model_config),
+        world_size,
+        kv_rank,
+        vllm_config.parallel_config.world_size,
+        vllm_config.parallel_config.rank,
+        vllm_config.parallel_config.tensor_parallel_size,
+        vllm_config.parallel_config.pipeline_parallel_size,
+    )
+
+    return LMCacheMPWorkerAdapter(
+        server_url=server_url,
+        context=zmq_context,
+        model_name=vllm_config.model_config.model,
+        vllm_block_size=vllm_config.cache_config.block_size,
+        parallel_strategy=parallel_strategy,
+        mq_timeout=mq_timeout,
+        heartbeat_interval=heartbeat_interval,
+        extra_config=vllm_config.kv_transfer_config.kv_connector_extra_config,
+    )
+
+
+class LMCacheMPRequestState(enum.Enum):
+    """
+    State machine:
+    PREFETCHING -- update_state_after_alloc --> WAITING_FOR_LOAD
+    WAITING_FOR_LOAD -- process_loading_requests --> READY
+    """
+
+    PREFETCHING = enum.auto()
+    WAITING_FOR_LOAD = enum.auto()
+    READY = enum.auto()
+
+
+@dataclass
+class LMCacheMPRequestTracker:
+    # NOTE: this class used vLLM data structures, should be part of
+    # vLLM integration code
+
+    request_id: str
+
+    # Read-only lists to track the token ids and block hashes
+    all_token_ids: ConstantList[int]
+    block_hashes: ConstantList["BlockHash"]
+
+    # Block ids and hashes will be updated at update_states_after_alloc and
+    # during the generation
+    allocated_block_ids: list[int] = field(default_factory=list)
+
+    # Number of scheduled tokens in this request. We keep tracking this to
+    # avoid saving half-full blocks.
+    num_scheduled_tokens: int = 0
+
+    # Number of blocks stored will be initialized when lookup the external
+    # hit tokens and will be updated when processing new requests and cached
+    # requests.
+    num_stored_blocks: int = 0
+
+    # Staging load operation -- save vllm and lmcache hit tokens during lookup
+    num_vllm_hit_blocks: int = 0
+    num_lmcache_hit_blocks: int = 0
+
+    # Main state
+    state: LMCacheMPRequestState = LMCacheMPRequestState.PREFETCHING
+
+    cache_salt: str = ""
+
+    def __init__(self, request: "Request"):
+        self.request_id = request.request_id
+        self.cache_salt: str = request.cache_salt or ""
+        self.all_token_ids = request.all_token_ids
+        self.block_hashes = ConstantList(request.block_hashes)
+        self.allocated_block_ids = []
+        self.num_stored_blocks = 0
+        self.num_vllm_hit_blocks = 0
+        self.num_lmcache_hit_blocks = 0
+        self.state = LMCacheMPRequestState.PREFETCHING
+
+    ####
+    # Check the state of the request
+    ####
+    def needs_retrieve(self) -> bool:
+        """Check whether the current request needs retrieve, will be used
+        update_stage_after_alloc"""
+        return (
+            self.num_lmcache_hit_blocks > self.num_vllm_hit_blocks
+            and self.state != LMCacheMPRequestState.READY
+        )
+
+    def is_ready_for_retrieving(self) -> bool:
+        """Check whether the current request is ready for retrieving,
+        will be used in process_loading_requests"""
+        return (
+            self.state == LMCacheMPRequestState.WAITING_FOR_LOAD
+            and self.needs_retrieve()
+        )
+
+    ####
+    # Update internal states
+    ####
+    def increase_num_scheduled_tokens(self, num_new_tokens: int):
+        self.num_scheduled_tokens += num_new_tokens
+
+    def increase_num_stored_blocks(self, num_new_blocks: int):
+        """Increase the number of stored blocks for the current request
+        This function will be called when processing the cached requests.
+        """
+        self.num_stored_blocks += num_new_blocks
+
+    def append_block_ids(
+        self,
+        new_block_ids: list[int],
+    ):
+        """Update the block ids for the current request
+        This function will be called when processing the cached requests.
+        """
+        self.allocated_block_ids.extend(new_block_ids)
+
+    ####
+    # For debugging
+    ####
+    def __repr__(self) -> str:
+        return (
+            f"LMCacheMPRequestTracker(request_id={self.request_id}, "
+            f"num_tokens={len(self.all_token_ids)}, "
+            f"num_block_hashes={len(self.block_hashes)}, "
+            f"num_allocated_blocks={len(self.allocated_block_ids)}, "
+            f"num_stored_blocks={self.num_stored_blocks}, "
+            f"vllm_hit_blocks={self.num_vllm_hit_blocks}, "
+            f"lmcache_hit_blocks={self.num_lmcache_hit_blocks}, "
+            f"state={self.state})"
+        )
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+
+@dataclass
+class LMCacheMPRequestMetadata:
+    request_id: str
+    direction: Literal["STORE", "RETRIEVE"]
+    op: LoadStoreOp
+    cache_salt: str = ""
+
+    @staticmethod
+    def GetStoreMetadata(
+        tracker: LMCacheMPRequestTracker,
+        blocks_in_chunk: int,
+        vllm_block_size: int,
+    ) -> "LMCacheMPRequestMetadata | None":
+        """
+        Generate the store metadata for the current request tracker.
+
+        Args:
+            tracker: The request tracker to generate the metadata from.
+            blocks_in_chunk: the number of blocks in a LMCache data chunk
+            vllm_block_size: the block size used in vLLM
+        """
+        # Store the blocks that has block hashes
+        # NOTE: the invariant here is that `num_stored_blocks` should
+        # always be a multiple of `blocks_in_chunk`
+        # TODO: This should be checked everytime we update the num_stored_blocks
+        #
+        # Why computed_blocks uses max(num_vllm_hit_blocks, num_lmcache_hit_blocks):
+        #
+        # Both values represent a prefix of blocks whose KV data is already
+        # available (either from vLLM APC or from LMCache), so they must NOT
+        # be summed (that would double-count the overlapping prefix).
+        #
+        # * num_lmcache_hit_blocks: LMCache-hit blocks are already counted in
+        #   num_stored_blocks (set during lookup), so they must be included
+        #   here to keep the upper bound consistent.  They are NOT re-stored.
+        # * num_vllm_hit_blocks: LMCache stores in units of chunks (N blocks),
+        #   so num_lmcache_hit_blocks is rounded DOWN to the nearest chunk
+        #   boundary.  When vLLM APC hits more blocks than that rounded value
+        #   (e.g. APC=44 blocks, LMCache=32 blocks after chunk alignment),
+        #   using only num_lmcache_hit_blocks would set the upper bound too
+        #   low and silently skip the APC-hit blocks that fall between the
+        #   two values, causing under-storing.  Taking the max ensures we
+        #   always use the tighter (larger) of the two hit counts.
+        computed_blocks = tracker.num_scheduled_tokens // vllm_block_size + max(
+            tracker.num_vllm_hit_blocks, tracker.num_lmcache_hit_blocks
+        )
+        min_available_blocks = min(
+            len(tracker.block_hashes),
+            len(tracker.allocated_block_ids),
+            computed_blocks,
+        )
+        num_staging_blocks = min_available_blocks - tracker.num_stored_blocks
+        num_chunks = num_staging_blocks // blocks_in_chunk
+
+        if num_chunks >= 1:
+            start = tracker.num_stored_blocks
+            end = start + num_chunks * blocks_in_chunk
+            block_ids = tracker.allocated_block_ids[start:end]
+            start_token_idx = start * vllm_block_size
+            end_token_idx = end * vllm_block_size
+            token_ids = list(tracker.all_token_ids)
+            op = LoadStoreOp(
+                token_ids=token_ids,
+                block_ids=block_ids,
+                start=start_token_idx,
+                end=end_token_idx,
+            )
+
+            ret = LMCacheMPRequestMetadata(
+                request_id=tracker.request_id,
+                direction="STORE",
+                op=op,
+                cache_salt=tracker.cache_salt,
+            )
+
+            # Update the request tracker
+            tracker.increase_num_stored_blocks(end - start)
+            return ret
+
+        return None
+
+    @staticmethod
+    def GetRetrieveMetadata(
+        tracker: LMCacheMPRequestTracker,
+        blocks_in_chunk: int,
+        vllm_block_size: int,
+    ) -> "LMCacheMPRequestMetadata | None":
+        """
+        Generate the retrieve metadata for the current request tracker.
+
+        Args:
+            tracker: The request tracker to generate the metadata from.
+            blocks_in_chunk: the number of blocks in a LMCache data chunk
+            vllm_block_size: the block size used in vLLM
+        """
+        if not tracker.is_ready_for_retrieving():
+            return None
+
+        # |---------------------|-----------------|----------------|
+        # | num_vllm_hit_blocks |
+        # | lmcache chunk 1   | lmcache chunk 2   |
+        #                     |  need to retrieve |
+
+        start = tracker.num_vllm_hit_blocks // blocks_in_chunk * blocks_in_chunk
+        end = tracker.num_lmcache_hit_blocks
+        assert end % blocks_in_chunk == 0, (
+            "The number of LMCache hit blocks should be a multiple of the "
+            "number of blocks in a lmcache chunk. "
+        )
+        assert len(tracker.block_hashes) >= end, (
+            "The number of block hashes should be greater than or equal to the "
+            "number of LMCache hit blocks. "
+        )
+        if end > start:
+            block_ids = tracker.allocated_block_ids[start:end]
+            start_token_idx = start * vllm_block_size
+            end_token_idx = end * vllm_block_size
+            token_ids = list(tracker.all_token_ids)
+
+            # Compute how many tokens at the start of the retrieve range
+            # overlap with APC-shared blocks. The server must skip writing
+            # to these positions to avoid a cross-stream data race: the
+            # retrieve writes on the LMCache CUDA stream while concurrent
+            # requests may read these APC-shared blocks on the vLLM stream.
+            apc_overlap_blocks = tracker.num_vllm_hit_blocks - start
+            skip_first_n_tokens = apc_overlap_blocks * vllm_block_size
+
+            op = LoadStoreOp(
+                token_ids=token_ids,
+                block_ids=block_ids,
+                start=start_token_idx,
+                end=end_token_idx,
+                skip_first_n_tokens=skip_first_n_tokens,
+            )
+
+            ret = LMCacheMPRequestMetadata(
+                request_id=tracker.request_id,
+                direction="RETRIEVE",
+                op=op,
+                cache_salt=tracker.cache_salt,
+            )
+            return ret
+
+        return None
+
+
+class LMCacheMPConnectorMetadata(KVConnectorMetadata):
+    def __init__(self):
+        super().__init__()
+        self.requests: list[LMCacheMPRequestMetadata] = []
+
+    def add_request_metadata(self, request_metadata: LMCacheMPRequestMetadata):
+        self.requests.append(request_metadata)
+
+    def __len__(self):
+        return len(self.requests)
+
+    # For debugging
+    def __str__(self):
+        request_strs = []
+        for req_meta in self.requests:
+            request_strs.append(
+                f"RequestMetadata(request_id={req_meta.request_id}, "
+                f"direction={req_meta.direction}, "
+                f"num_blocks={len(req_meta.op.flat_block_ids)}, "
+                f"block_ids={req_meta.op.block_ids})"
+            )
+        return "[" + "\n".join(request_strs) + "]"
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class LMCacheMPConnector(KVConnectorBase_V1):
+    """
+    The connector for LMCache multi-process mode.
+
+    Extra configs (kv_transfer_config.extra_config):
+    - lmcache.mp.host: the host of the LMCache server.
+    - lmcache.mp.port: the port of the LMCache server.
+    - lmcache.mp.mq_timeout: timeout (seconds) for message queue requests.
+    - lmcache.mp.heartbeat_interval: interval (seconds) between server
+      heartbeat pings.
+    - lmcache.mp.mp_transfer_mode: routing mode for the worker -> server
+      transfer context. One of ``auto`` (default; CUDA -> engine_driven,
+      others -> lmcache_driven), ``engine_driven`` (force IPC / SHM
+      zero-copy), ``lmcache_driven`` (force worker-side gather/scatter
+      copy). Overrides the ``LMCACHE_MP_TRANSFER_MODE`` env var when set.
+    """
+
+    def __init__(
+        self,
+        vllm_config: "VllmConfig",
+        role: KVConnectorRole,
+        kv_cache_config: "KVCacheConfig | None" = None,
+    ):
+        super().__init__(vllm_config, role, kv_cache_config)
+
+        # fast-fail if interprocess is not supported
+        check_interprocess_event_support()
+
+        assert vllm_config.kv_transfer_config is not None
+        server_host = vllm_config.kv_transfer_config.get_from_extra_config(
+            "lmcache.mp.host", "tcp://localhost"
+        )
+        server_port = vllm_config.kv_transfer_config.get_from_extra_config(
+            "lmcache.mp.port", 5555
+        )
+        mq_timeout = float(
+            vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.mp.mq_timeout", 300.0
+            )
+        )
+        heartbeat_interval = float(
+            vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.mp.heartbeat_interval", 10.0
+            )
+        )
+
+        server_url = f"{server_host}:{server_port}"
+        zmq_context = zmq.Context.instance()
+        if self.role == KVConnectorRole.SCHEDULER:
+            self.scheduler_adapter = create_scheduler_adapter(
+                server_url,
+                zmq_context,
+                vllm_config,
+                mq_timeout,
+                heartbeat_interval,
+            )
+            self.request_trackers: dict[str, LMCacheMPRequestTracker] = {}
+        elif self.role == KVConnectorRole.WORKER:
+            self.worker_adapter = create_worker_adapter(
+                server_url,
+                zmq_context,
+                vllm_config,
+                mq_timeout,
+                heartbeat_interval,
+            )
+        else:
+            raise ValueError(f"Unknown KVConnectorRole: {self.role}")
+
+        self.vllm_block_size = vllm_config.cache_config.block_size
+
+    @property
+    def role(self) -> KVConnectorRole:
+        return self._role
+
+    # ==============================
+    # Worker-side methods
+    # ==============================
+
+    def _get_connector_metadata(self) -> KVConnectorMetadata:
+        """Get the connector metadata.
+
+        This function should only be called inside the connector.
+
+        Returns:
+            ConnectorMetadata: the connector metadata.
+        """
+
+        # Should only be called while set to valid metadata.
+        assert self._connector_metadata is not None
+        return self._connector_metadata
+
+    def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
+        """
+        Initialize with the KV caches. Useful for pre-registering the
+        KV Caches in the KVConnector (e.g. for NIXL).
+
+        Args:
+            kv_caches: dictionary of layer names, kv cache
+        """
+        logger.info("Registering kv caches!")
+        self.worker_adapter.register_kv_caches(kv_caches)
+        return
+
+    def start_load_kv(self, forward_context: "ForwardContext", **kwargs: Any) -> None:
+        """
+        Start loading the KV cache from the connector to vLLM's paged
+        KV buffer. This is called from the forward context before the
+        forward pass to enable async loading during model execution.
+
+        Args:
+            forward_context (ForwardContext): the forward context.
+            **kwargs: additional arguments for the load operation
+
+        Note:
+            The number of elements in kv_caches and layer_names should be
+            the same.
+
+        """
+        metadata = self._get_connector_metadata()
+        assert isinstance(metadata, LMCacheMPConnectorMetadata)
+
+        request_ids = []
+        ops = []
+        cache_salts = []
+
+        for meta in metadata.requests:
+            if meta.direction != "RETRIEVE":
+                continue
+            request_ids.append(meta.request_id)
+            ops.append(meta.op)
+            cache_salts.append(meta.cache_salt)
+
+        if len(request_ids) == 0:
+            return
+
+        with torch_dev.stream(torch_dev.current_stream()):
+            event = torch_dev.Event(interprocess=True)
+            event.record()
+
+        self.worker_adapter.batched_submit_retrieve_requests(
+            request_ids, ops, event, cache_salts=cache_salts
+        )
+
+    def wait_for_layer_load(self, layer_name: str) -> None:
+        """
+        Block until the KV for a specific layer is loaded into vLLM's
+        paged buffer. This is called from within attention layer to ensure
+        async copying from start_load_kv is complete.
+
+        This interface will be useful for layer-by-layer pipelining.
+
+        Args:
+            layer_name: the name of that layer
+        """
+        return
+
+    def save_kv_layer(
+        self,
+        layer_name: str,
+        kv_layer: torch.Tensor,
+        attn_metadata: AttentionMetadata,
+        **kwargs: Any,
+    ) -> None:
+        """
+        Start saving a layer of KV cache from vLLM's paged buffer
+        to the connector. This is called from within attention layer to
+        enable async copying during execution.
+
+        Args:
+            layer_name (str): the name of the layer.
+            kv_layer (torch.Tensor): the paged KV buffer of the current
+                layer in vLLM.
+            attn_metadata (AttentionMetadata): the attention metadata.
+            **kwargs: additional arguments for the save operation.
+        """
+        return
+
+    def wait_for_save(self):
+        """
+        Block until all the save operations is done. This is called
+        as the forward context exits to ensure that the async saving
+        from save_kv_layer is complete before finishing the forward.
+
+        This prevents overwrites of paged KV buffer before saving done.
+        """
+        # In MLA scenario, only the first rank of the pipeline group
+        # needs to save the KV cache.
+        if (
+            self.worker_adapter.use_mla
+            and not self.worker_adapter.is_first_rank_of_pp_group
+        ):
+            return
+
+        metadata = self._get_connector_metadata()
+        assert isinstance(metadata, LMCacheMPConnectorMetadata)
+
+        request_ids = []
+        ops = []
+        cache_salts = []
+        for meta in metadata.requests:
+            if meta.direction != "STORE":
+                continue
+            request_ids.append(meta.request_id)
+            ops.append(meta.op)
+            cache_salts.append(meta.cache_salt)
+
+        if len(request_ids) == 0:
+            return
+
+        with torch_dev.stream(torch_dev.current_stream()):
+            event = torch_dev.Event(interprocess=True)
+            event.record()
+
+        self.worker_adapter.batched_submit_store_requests(
+            request_ids, ops, event, cache_salts=cache_salts
+        )
+
+    def get_finished(
+        self, finished_req_ids: set[str]
+    ) -> tuple[set[str] | None, set[str] | None]:
+        """
+        Notifies worker-side connector ids of requests that have
+        finished generating tokens on the worker.
+        The scheduler process (via the Executors) will use this output
+        to track which workers are done.
+
+        Returns:
+            ids of requests that have finished asynchronous transfer
+            (requests that previously returned True from request_finished()),
+            tuple of (sending/saving ids, recving/loading ids).
+            The finished saves/sends req ids must belong to a set provided in a
+            call to this method (this call or a prior one).
+        """
+        val = self.worker_adapter.get_finished(finished_req_ids)
+        # logger.error("Finished req ids: %s, %s", val[0], val[1])
+        return val
+
+    def get_block_ids_with_load_errors(self) -> set[int]:
+        """
+        Get the set of block IDs that failed to load.
+
+        Returns:
+            Set of block IDs that encountered load errors.
+            Empty set if no load errors occurred.
+
+        Notes:
+            - Applies to both sync- and async-loading requests.
+            - Async loading: failed blocks may be reported in any forward pass
+              up to and including the pass where the request ID is returned by
+              `get_finished()`. Even if failures occur, the request must still
+              be reported via `get_finished()`, and the failed block IDs must
+              appear here no later than that same pass.
+            - Sync loading: failed blocks should be reported in the forward
+              pass in which they are detected.
+        """
+        return self.worker_adapter.get_block_ids_with_load_errors()
+
+    def shutdown(self):
+        """
+        Shutdown the connector. This is called when the worker process
+        is shutting down to ensure that all the async operations are
+        completed and the connector is cleaned up properly.
+        """
+        if hasattr(self, "worker_adapter"):
+            self.worker_adapter.shutdown()
+        return None
+
+    def get_kv_connector_stats(self) -> "KVConnectorStats | None":
+        """
+        Get the KV connector stats collected during the last interval.
+        """
+        return None
+
+    # ==============================
+    # Scheduler-side methods
+    # ==============================
+
+    def get_num_new_matched_tokens(
+        self,
+        request: "Request",
+        num_computed_tokens: int,
+    ) -> tuple[int | None, bool]:
+        """
+        Get number of new tokens that can be loaded from the
+        external KV cache beyond the num_computed_tokens.
+
+        Args:
+            request (Request): the request object.
+            num_computed_tokens (int): the number of locally
+                computed tokens for this request
+
+        Returns:
+            A tuple with the following elements:
+                - An optional number of tokens that can be loaded from the
+                  external KV cache beyond what is already computed.
+                  If None, it means that the connector needs more time to
+                  determine the number of matched tokens, and the scheduler
+                  should query for this request again later.
+                - `True` if external KV cache tokens will be loaded
+                  asynchronously (between scheduler steps). Must be
+                  'False' if the first element is 0.
+
+        Notes:
+            The connector should only consider the largest prefix of prompt-
+            tokens for which KV cache is actually available at the time of the
+            call. If the cache cannot be loaded for some tokens (e.g., due to
+            connectivity issues or eviction), those tokens must not be taken
+            into account.
+        """
+        tracker = self._get_or_create_request_tracker(request)
+        # TODO: support loading KV for preempted requests in the future
+        if request.status == RequestStatus.PREEMPTED:
+            return 0, False
+
+        self.scheduler_adapter.maybe_submit_lookup_request(
+            request.request_id,
+            token_ids=list(request.all_token_ids),
+            cache_salt=tracker.cache_salt,
+        )
+
+        ret = self.scheduler_adapter.check_lookup_result(request.request_id)
+        if ret is None:
+            return None, True
+
+        if ret == 0:
+            return 0, False
+
+        assert (
+            ret % (self.scheduler_adapter.num_blocks_per_chunk() * self.vllm_block_size)
+            == 0
+        )
+
+        # Update num stored blocks for the tracker
+        num_vllm_blocks = num_computed_tokens // self.vllm_block_size
+        num_lmcache_blocks = ret // self.vllm_block_size
+        tracker.increase_num_stored_blocks(num_lmcache_blocks)
+
+        # Save the vllm and lmcache hit tokens
+        tracker.num_vllm_hit_blocks = num_vllm_blocks
+        tracker.num_lmcache_hit_blocks = num_lmcache_blocks
+
+        need_to_load = max(0, ret - num_computed_tokens)
+        logger.debug(
+            "vLLM hit is: %d, Need to load is %d", num_computed_tokens, need_to_load
+        )
+        return need_to_load, need_to_load > 0
+
+    def update_state_after_alloc(
+        self, request: "Request", blocks: "KVCacheBlocks", num_external_tokens: int
+    ):
+        """
+        Update KVConnector state after block allocation.
+
+        If get_num_new_matched_tokens previously returned True for a
+        request, this function may be called twice for that same request -
+        first when blocks are allocated for the connector tokens to be
+        asynchronously loaded into, and second when any additional blocks
+        are allocated, after the load/transfer is complete.
+
+        Args:
+            request (Request): the request object.
+            blocks (KVCacheBlocks): the blocks allocated for the request.
+            num_external_tokens (int): the number of tokens that will be
+                loaded from the external KV cache.
+        """
+        # NOTE: `blocks` comes from kv_cache_manager.get_blocks(request_id),
+        # which returns ALL blocks for the request (not just newly allocated).
+        # This function may be called twice for async-load requests:
+        #   1st call: blocks = initial allocation (APC + fresh)
+        #   2nd call: blocks = all blocks
+        #  (initial + newly allocated for remaining tokens)
+        # We must only append the NEW blocks beyond what's already tracked
+        # to avoid duplication, which would corrupt the store path's block indexing.
+        tracker = self._get_request_tracker(request.request_id)
+        block_ids = reformat_block_ids(blocks.get_block_ids())
+
+        # Only append blocks beyond what's already tracked
+        existing_count = len(tracker.allocated_block_ids)
+        new_block_ids = block_ids[existing_count:]
+        if new_block_ids:
+            tracker.append_block_ids(new_block_ids)
+
+        # Update the state of the tracker
+        condition = tracker.needs_retrieve()
+        if tracker.state == LMCacheMPRequestState.PREFETCHING:
+            # If need to retrieve, change to WAITING_FOR_LOAD
+            # Otherwise, change to READY
+            tracker.state = (
+                LMCacheMPRequestState.WAITING_FOR_LOAD
+                if condition
+                else LMCacheMPRequestState.READY
+            )
+            # Clean up lookup future in scheduler adapter
+            self.scheduler_adapter.cleanup_lookup_result(request.request_id)
+
+            # Free locks on chunks that vLLM already computed and won't
+            # retrieve from LMCache.
+            if tracker.num_lmcache_hit_blocks > 0:
+                if not condition:
+                    # No retrieve needed — free ALL locked chunks
+                    free_end = tracker.num_lmcache_hit_blocks * self.vllm_block_size
+                else:
+                    # Note(Roy): Boundary misalignment between vLLM blocks and LMCache
+                    # blocks is handled in free_lookup_locks. It makes sure that if
+                    # the last vLLM computed block ends in the middle of a LMCache
+                    # block, the end LMCache block is not freed (i.e., floor division)
+                    # since it will still be needed by vLLM and such block's lock will
+                    # be freed by vLLM's retrieve.
+                    free_end = tracker.num_vllm_hit_blocks * self.vllm_block_size
+
+                if free_end > 0:
+                    self.scheduler_adapter.free_lookup_locks(
+                        token_ids=list(tracker.all_token_ids),
+                        start=0,
+                        end=free_end,
+                        request_id=request.request_id,
+                    )
+                    logger.debug(
+                        "Free locks of tokens %d-%d since it is cached by vLLM.",
+                        0,
+                        free_end,
+                    )
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> KVConnectorMetadata:
+        """
+        Build the connector metadata for this step.
+
+        This function should NOT modify fields in the scheduler_output.
+        Also, calling this function will reset the state of the connector.
+
+        Args:
+            scheduler_output (SchedulerOutput): the scheduler output object.
+        """
+        metadata = LMCacheMPConnectorMetadata()
+
+        self._process_retrieve_requests(metadata)
+        self._process_new_requests(scheduler_output, metadata)
+        self._process_cached_requests(scheduler_output, metadata)
+
+        if len(metadata) > 0:
+            logger.debug("Final connector metadata: %s", metadata)
+
+        # Report block allocation deltas to LMCache for observability
+        self._report_block_allocation_deltas(scheduler_output)
+
+        return metadata
+
+    def update_connector_output(self, connector_output: KVConnectorOutput):
+        """
+        Update KVConnector state from worker-side connectors output.
+
+        Args:
+            connector_output (KVConnectorOutput): the worker-side
+                connectors output.
+        """
+        return
+
+    def request_finished(
+        self,
+        request: "Request",
+        block_ids: list[int],
+    ) -> tuple[bool, dict[str, Any] | None]:
+        """
+        Called exactly once when a request has finished, before its blocks are
+        freed.
+
+        The connector may assumes responsibility for freeing the blocks
+        asynchronously by returning True.
+
+        Returns:
+            True if the request is being saved/sent asynchronously and blocks
+            should not be freed until the request_id is returned from
+            get_finished().
+            Optional KVTransferParams to be included in the request outputs
+            returned by the engine.
+        """
+
+        params: dict[str, Any] | None = getattr(request, "kv_transfer_params", None)
+        return_params: dict[str, Any] | None = {} if params is not None else None
+
+        if (
+            params is not None
+            and return_params is not None
+            and "num_lmcache_extra_cached_tokens" in params
+        ):
+            request_tracker = self._get_request_tracker(request.request_id)
+            num_extra_cached_blocks = max(
+                0,
+                request_tracker.num_lmcache_hit_blocks
+                - request_tracker.num_vllm_hit_blocks,
+            )
+            return_params["num_lmcache_extra_cached_tokens"] = (
+                num_extra_cached_blocks * self.vllm_block_size
+            )
+
+        # Clean up request tracker to prevent memory leak
+        self._cleanup_request_tracker(request.request_id)
+        # Notify LMCache to end the session for this request
+        self.scheduler_adapter.end_session(request.request_id)
+
+        return True, return_params
+
+    def take_events(self) -> Iterable["KVCacheEvent"]:
+        """
+        Take the KV cache events from the connector.
+
+        Yields:
+            New KV cache events since the last call.
+        """
+        return ()
+
+    @classmethod
+    def get_required_kvcache_layout(cls, vllm_config: "VllmConfig") -> str | None:
+        """
+        Get the required KV cache layout for this connector.
+        Args:
+            vllm_config (VllmConfig): the vllm config.
+
+        Returns:
+            str: the required KV cache layout. e.g. HND, or NHD.
+            None if the connector does not require a specific layout.
+        """
+
+        if cls is KVConnectorBase_V1:
+            raise TypeError(
+                "get_required_kvcache_layout should not be called "
+                "on the abstract base class"
+            )
+        return None
+
+    def get_finished_count(self) -> int | None:
+        """
+        Get the count of requests expected to complete send/receive operations
+        via this connector. This method is used to initialize the
+        KVOutputAggregator, overwriting the default world_size.
+
+        Returns:
+            int: expected sending or receiving completion count.
+        """
+        return None
+
+    @classmethod
+    def build_kv_connector_stats(
+        cls, data: dict[str, Any] | None = None
+    ) -> "KVConnectorStats | None":
+        """
+        KVConnectorStats resolution method. This method allows dynamically
+        registered connectors to return their own KVConnectorStats object,
+        which can implement custom aggregation logic on the data dict.
+        """
+        return None
+
+    @classmethod
+    def build_prom_metrics(
+        cls,
+        vllm_config: "VllmConfig",
+        metric_types: dict[type["PromMetric"], type["PromMetricT"]],
+        labelnames: list[str],
+        per_engine_labelvalues: dict[int, list[object]],
+    ) -> "KVConnectorPromMetrics | None":
+        """
+        Create a KVConnectorPromMetrics subclass which should register
+        per-connector Prometheus metrics and implement observe() to
+        expose connector transfer stats via Prometheus.
+        """
+        return None
+
+    ##############################
+    # Helper functions
+    ##############################
+    def _process_retrieve_requests(
+        self,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        blocks_per_chunk = self.scheduler_adapter.num_blocks_per_chunk()
+
+        for request_tracker in self.request_trackers.values():
+            if request_tracker.state != LMCacheMPRequestState.WAITING_FOR_LOAD:
+                continue
+            r_metadata = LMCacheMPRequestMetadata.GetRetrieveMetadata(
+                request_tracker,
+                blocks_per_chunk,
+                vllm_block_size=self.vllm_block_size,
+            )
+            if r_metadata is not None:
+                metadata.add_request_metadata(r_metadata)
+            request_tracker.state = LMCacheMPRequestState.READY
+
+    def _process_new_requests(
+        self,
+        scheduler_output: SchedulerOutput,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        blocks_per_chunk = self.scheduler_adapter.num_blocks_per_chunk()
+
+        for new_request in scheduler_output.scheduled_new_reqs:
+            request_tracker = self._get_request_tracker(new_request.req_id)
+
+            num_new_tokens = scheduler_output.num_scheduled_tokens[new_request.req_id]
+            request_tracker.increase_num_scheduled_tokens(num_new_tokens)
+
+            r_meta = LMCacheMPRequestMetadata.GetStoreMetadata(
+                request_tracker, blocks_per_chunk, self.vllm_block_size
+            )
+            if r_meta is not None:
+                metadata.add_request_metadata(r_meta)
+
+    def _process_cached_requests(
+        self,
+        scheduler_output: SchedulerOutput,
+        metadata: LMCacheMPConnectorMetadata,
+    ) -> None:
+        blocks_per_chunk = self.scheduler_adapter.num_blocks_per_chunk()
+
+        cached_reqs = scheduler_output.scheduled_cached_reqs
+        for idx, request_id in enumerate(cached_reqs.req_ids):
+            request_tracker = self._get_request_tracker(request_id)
+
+            # Update block ids
+            new_block_ids = reformat_block_ids(cached_reqs.new_block_ids[idx])
+            if request_id not in cached_reqs.resumed_req_ids:
+                request_tracker.append_block_ids(new_block_ids)
+
+            # Use the incremental num_scheduled_tokens to
+            # stay consistent with _process_new_requests.
+            num_new_tokens = scheduler_output.num_scheduled_tokens[request_id]
+            request_tracker.increase_num_scheduled_tokens(num_new_tokens)
+
+            r_meta = LMCacheMPRequestMetadata.GetStoreMetadata(
+                request_tracker, blocks_per_chunk, self.vllm_block_size
+            )
+
+            if r_meta is not None:
+                metadata.add_request_metadata(r_meta)
+
+    def _report_block_allocation_deltas(
+        self,
+        scheduler_output: SchedulerOutput,
+    ) -> None:
+        """Gather per-request block allocation deltas and report to LMCache.
+
+        For new requests: all allocated_block_ids and token_ids are new.
+        For cached requests: only newly appended block_ids and token_ids.
+        """
+        records: list[RequestAllocationRecord] = []
+
+        # New requests: send all tokens covering all allocated blocks so
+        # the L0 metrics subscriber can correctly map each block to its
+        # actual token content (not just the newly-scheduled slice).
+        for new_request in scheduler_output.scheduled_new_reqs:
+            tracker = self.request_trackers.get(new_request.req_id)
+            if tracker is None:
+                continue
+            num_blocks = len(tracker.allocated_block_ids)
+            total_tokens = num_blocks * self.vllm_block_size
+            records.append(
+                RequestAllocationRecord(
+                    req_id=new_request.req_id,
+                    new_block_ids=list(tracker.allocated_block_ids),
+                    new_token_ids=list(tracker.all_token_ids[:total_tokens]),
+                )
+            )
+
+        # Cached requests: only the newly added blocks and their full
+        # token content.  We send all tokens covered by the new blocks
+        # (not just the tokens scheduled this step) so the L0 subscriber
+        # can correctly identify block content.
+        cached_reqs = scheduler_output.scheduled_cached_reqs
+        for idx, request_id in enumerate(cached_reqs.req_ids):
+            new_block_ids = reformat_block_ids(cached_reqs.new_block_ids[idx])
+            if not new_block_ids:
+                continue
+            tracker = self.request_trackers.get(request_id)
+            if tracker is None:
+                continue
+            # The new blocks sit at the end of the request's block list.
+            # Compute the token range they cover.
+            total_blocks = len(tracker.allocated_block_ids)
+            num_new_blocks = len(new_block_ids)
+            start_token = (total_blocks - num_new_blocks) * self.vllm_block_size
+            end_token = total_blocks * self.vllm_block_size
+            new_token_ids = list(tracker.all_token_ids[start_token:end_token])
+            records.append(
+                RequestAllocationRecord(
+                    req_id=request_id,
+                    new_block_ids=new_block_ids,
+                    new_token_ids=new_token_ids,
+                )
+            )
+
+        if records:
+            self.scheduler_adapter.report_block_allocations(records)
+
+    def _get_request_tracker(self, request_id: str) -> LMCacheMPRequestTracker:
+        assert request_id in self.request_trackers, (
+            f"Request tracker for request_id {request_id} not found. "
+        )
+        return self.request_trackers[request_id]
+
+    def _get_or_create_request_tracker(
+        self, request: "Request"
+    ) -> LMCacheMPRequestTracker:
+        request_id = request.request_id
+        # Remove the old trackers that is created before the preemption
+        if (
+            request.status == RequestStatus.PREEMPTED
+            and request_id in self.request_trackers
+        ):
+            tracker = self.request_trackers[request_id]
+
+            # NOTE: since this function may be called multiple times
+            # for a single request (because get_num_new_matched_tokens
+            # may be called multiple times) for the same request, we
+            # will only do the remove if the tracker is not in the "fresh"
+            # state, i.e., PREFETCHING
+            if tracker.state != LMCacheMPRequestState.PREFETCHING:
+                self.request_trackers.pop(request_id)
+
+        if request_id not in self.request_trackers:
+            new_tracker = LMCacheMPRequestTracker(request)
+            self.request_trackers[request_id] = new_tracker
+        return self.request_trackers[request_id]
+
+    def _cleanup_request_tracker(self, request_id: str) -> None:
+        """
+        Clean up request tracker and associated lookup future for a request.
+        This should be called when a request is finished to prevent memory leak.
+        """
+        # Clean up request tracker
+        if self.request_trackers.pop(request_id, None):
+            logger.debug(
+                "[KVConnector] Cleaned up request_tracker for request %s",
+                request_id,
+            )
diff --git a/lmcache/integration/vllm/tests/test_mm_hash_utils.py b/lmcache/integration/vllm/tests/test_mm_hash_utils.py
new file mode 100644
index 0000000..923ea3d
--- /dev/null
+++ b/lmcache/integration/vllm/tests/test_mm_hash_utils.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import dataclasses
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import (
+    apply_mm_hashes_to_token_ids,
+    hex_hash_to_int16,
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class DummyPlaceholderRange:
+    offset: int
+    length: int
+
+
+def test_hex_hash_to_int16_accepts_hex_and_non_hex() -> None:
+    # Hex behavior preserved (with and without 0x prefix).
+    assert hex_hash_to_int16("0000") == 0
+    assert hex_hash_to_int16("ffff") == 0xFFFF
+    assert hex_hash_to_int16("0xFFFF") == 0xFFFF
+    assert hex_hash_to_int16("0x0001") == 1
+
+    # Non-hex identifiers must not raise and must be deterministic.
+    s = "chatcmpl-a2a48871c4aad192-image-0"
+    v1 = hex_hash_to_int16(s)
+    v2 = hex_hash_to_int16(s)
+    assert isinstance(v1, int)
+    assert 0 <= v1 <= 0xFFFF
+    assert v1 == v2
+
+
+def test_hex_hash_to_int16_hex_variants_whitespace_and_truncation() -> None:
+    # Whitespace should be ignored and case should not matter.
+    assert hex_hash_to_int16(" FfFf ") == 0xFFFF
+    assert hex_hash_to_int16("\n0x00aB\t") == 0x00AB
+
+    # Long hex should be truncated to 16 bits via masking.
+    assert hex_hash_to_int16("123456") == 0x3456
+    assert hex_hash_to_int16("0x123456") == 0x3456
+
+
+def test_hex_hash_to_int16_empty_and_invalid_hex_are_safe_and_deterministic() -> None:
+    # Empty (or effectively empty) values should not raise.
+    for s in ("", "   ", "0x"):
+        v1 = hex_hash_to_int16(s)
+        v2 = hex_hash_to_int16(s)
+        assert isinstance(v1, int)
+        assert 0 <= v1 <= 0xFFFF
+        assert v1 == v2
+
+    # Invalid "hex-looking" strings must fall back to hashing.
+    for s in ("0xGG", "deadbeeg", "0x12xz"):
+        v1 = hex_hash_to_int16(s)
+        v2 = hex_hash_to_int16(s)
+        assert isinstance(v1, int)
+        assert 0 <= v1 <= 0xFFFF
+        assert v1 == v2
+
+
+def test_hex_hash_to_int16_non_string_inputs_are_safe() -> None:
+    # Be defensive: callers may pass None or other non-string types.
+    for val in (None, 0, 12345, 3.14, b"deadbeef"):
+        v1 = hex_hash_to_int16(val)  # type: ignore[arg-type]
+        v2 = hex_hash_to_int16(val)  # type: ignore[arg-type]
+        assert isinstance(v1, int)
+        assert 0 <= v1 <= 0xFFFF
+        assert v1 == v2
+
+
+def test_apply_mm_hashes_to_token_ids_handles_non_hex_mm_hash() -> None:
+    token_ids = torch.arange(0, 10, dtype=torch.long)
+    mm_hashes = ["chatcmpl-a2a48871c4aad192-image-0"]
+    mm_positions = [DummyPlaceholderRange(offset=2, length=4)]
+
+    out = apply_mm_hashes_to_token_ids(token_ids.clone(), mm_hashes, mm_positions)
+    expected_val = hex_hash_to_int16(mm_hashes[0])
+    assert out[2:6].tolist() == [expected_val] * 4
+
+
+def test_apply_mm_hashes_to_token_ids_out_of_bounds_is_safe() -> None:
+    token_ids = torch.zeros(5, dtype=torch.long)
+    mm_hashes = ["deadbeef"]
+    mm_positions = [DummyPlaceholderRange(offset=999, length=10)]
+
+    out = apply_mm_hashes_to_token_ids(token_ids.clone(), mm_hashes, mm_positions)
+    assert out.tolist() == token_ids.tolist()
+
+
+def test_apply_mm_hashes_to_token_ids_multiple_placeholders_and_length_mismatch() -> (
+    None
+):
+    token_ids = torch.zeros(12, dtype=torch.long)
+    mm_hashes = ["deadbeef", "chatcmpl-a2a48871c4aad192-image-0", "EXTRA_HASH_IGNORED"]
+    mm_positions = [
+        DummyPlaceholderRange(offset=0, length=3),
+        DummyPlaceholderRange(offset=5, length=4),
+    ]
+
+    out = apply_mm_hashes_to_token_ids(token_ids.clone(), mm_hashes, mm_positions)
+    v0 = hex_hash_to_int16(mm_hashes[0])
+    v1 = hex_hash_to_int16(mm_hashes[1])
+
+    assert out[0:3].tolist() == [v0] * 3
+    assert out[5:9].tolist() == [v1] * 4
+    # Other regions remain unchanged.
+    assert out[3:5].tolist() == [0, 0]
+    assert out[9:12].tolist() == [0, 0, 0]
diff --git a/lmcache/integration/vllm/utils.py b/lmcache/integration/vllm/utils.py
new file mode 100644
index 0000000..ce6262a
--- /dev/null
+++ b/lmcache/integration/vllm/utils.py
@@ -0,0 +1,419 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, Literal, Optional, Tuple
+import hashlib
+import os
+import string
+import threading
+
+if TYPE_CHECKING:
+    from vllm.config import ModelConfig, VllmConfig
+    from vllm.multimodal.inputs import PlaceholderRange
+    from vllm.v1.request import Request
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig, load_ec_engine_config
+from lmcache.v1.config_base import apply_remote_configs, fetch_remote_config
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.gpu_connector.utils import LayoutHints
+
+logger = init_logger(__name__)
+ENGINE_NAME = "vllm-instance"
+
+# Thread-safe singleton storage
+_config_instance: Optional[LMCacheEngineConfig] = None
+_config_lock = threading.Lock()
+
+
+def is_false(value: str) -> bool:
+    """Check if the given string value is equivalent to 'false'."""
+    return value.lower() in ("false", "0", "no", "n", "off")
+
+
+def vllm_layout_hints() -> "LayoutHints":
+    """Build layout_hints dict by querying vLLM at runtime."""
+    hints: dict[str, str] = {}
+    kv_layout = try_get_vllm_kv_cache_layout()
+    if kv_layout is not None:
+        hints["kv_layout"] = kv_layout
+    return hints  # type: ignore[return-value]
+
+
+def try_get_vllm_kv_cache_layout() -> Literal["NHD", "HND"] | None:
+    """Try to query the KV cache layout from vLLM at runtime.
+
+    Returns ``"NHD"`` or ``"HND"`` if vLLM is available and the layout
+    has been configured, otherwise ``None``.
+
+    Please only call this where vllm is available (i.e. not in the MP server)
+    We will print an error if we try to get vllm kv layout where vllm
+    is not available.
+    """
+
+    # Third Party
+    try:
+        # Third Party
+        from vllm.v1.attention.backends.utils import (  # type: ignore[import-untyped]
+            get_kv_cache_layout,
+        )
+
+        return get_kv_cache_layout()
+    except Exception:
+        logger.error(
+            "vLLM is not available but tried to query kv cache "
+            "layout information, cannot get KV cache layout"
+        )
+        return None
+
+
+def lmcache_get_or_create_config() -> LMCacheEngineConfig:
+    """Get the LMCache configuration from the environment variable
+    `LMCACHE_CONFIG_FILE`. If the environment variable is not set, this
+    function will return the default configuration.
+
+    This function is thread-safe and implements singleton pattern,
+    ensuring the configuration is loaded only once.
+
+    After loading the configuration, if 'remote_config_url' is configured,
+    this function will attempt to fetch additional configuration from the
+    remote config service. The current config and LMCACHE environment
+    variables will be sent to the service, along with 'appid' if set.
+    """
+    global _config_instance
+
+    # Double-checked locking for thread-safe singleton
+    if _config_instance is None:
+        with _config_lock:
+            if _config_instance is None:  # Check again within lock
+                if "LMCACHE_CONFIG_FILE" not in os.environ:
+                    logger.warning(
+                        "No LMCache configuration file is set. Trying to read"
+                        " configurations from the environment variables."
+                    )
+                    logger.warning(
+                        "You can set the configuration file through "
+                        "the environment variable: LMCACHE_CONFIG_FILE"
+                    )
+                    _config_instance = LMCacheEngineConfig.from_env()
+                    # from_env() doesn't call validate(); the file path
+                    # gets it via update_config_from_env() below, but the
+                    # env-only path needs an explicit call.
+                    _config_instance.validate()
+                else:
+                    config_file = os.environ["LMCACHE_CONFIG_FILE"]
+                    logger.info(f"Loading LMCache config file {config_file}")
+                    _config_instance = LMCacheEngineConfig.from_file(config_file)
+                    # Update config from environment variables
+                    _config_instance.update_config_from_env()
+
+                # Fetch and apply remote configuration if configured
+                remote_config_url = _config_instance.remote_config_url
+                if remote_config_url:
+                    logger.info(
+                        "Fetching remote configuration from %s", remote_config_url
+                    )
+                    app_id = _config_instance.app_id
+                    remote_response = fetch_remote_config(
+                        remote_config_url, app_id, _config_instance
+                    )
+                    if remote_response:
+                        _config_instance = apply_remote_configs(
+                            _config_instance, remote_response
+                        )
+                    else:
+                        logger.warning(
+                            "Failed to fetch remote configuration from %s. "
+                            "Using local configuration only.",
+                            remote_config_url,
+                        )
+    return _config_instance
+
+
+def create_lmcache_ec_config() -> LMCacheEngineConfig:
+    """Create EC config from LMCache config plus EC-specific overrides."""
+    return load_ec_engine_config(base_config=lmcache_get_or_create_config())
+
+
+def hex_hash_to_int16(s: str) -> int:
+    """
+    Convert a hash identifier into a 16-bit integer.
+
+    Historically, LMCache expected multimodal identifiers to be hex strings.
+    In practice (e.g., OpenAI-style multimodal requests), identifiers may be
+    arbitrary strings like `chatcmpl-...-image-0`. This function therefore:
+      - Parses hex strings (optionally prefixed with `0x`) as before, or
+      - Falls back to a stable string hash (SHA-256) when the input is not hex.
+    """
+    # Be defensive: vLLM may pass non-string identifiers.
+    s = "" if s is None else str(s)
+    s_stripped = s.strip()
+
+    # Fast-path: pure hex (optionally 0x-prefixed).
+    hex_part = s_stripped[2:] if s_stripped.lower().startswith("0x") else s_stripped
+    if hex_part and all(c in string.hexdigits for c in hex_part):
+        try:
+            return int(hex_part, 16) & 0xFFFF
+        except ValueError:
+            # Extremely unlikely (e.g., oversized/odd formatting); fall back to hashing.
+            pass
+
+    # Fallback: stable 16-bit value derived from the full identifier string.
+    digest = hashlib.sha256(s_stripped.encode("utf-8")).digest()
+    return int.from_bytes(digest[:2], byteorder="big", signed=False)
+
+
+def apply_mm_hashes_to_token_ids(
+    token_ids: torch.Tensor,
+    mm_hashes: list[str],
+    mm_positions: list["PlaceholderRange"],
+) -> torch.Tensor:
+    """
+    Overwrite token_ids in-place for multimodal placeholders using
+    efficient slice assignments.
+    """
+    n = token_ids.size(0)
+    for hash_str, placeholder in zip(mm_hashes, mm_positions, strict=False):
+        start, length = placeholder.offset, placeholder.length
+        if start >= n:
+            continue
+        end = min(start + length, n)
+        token_ids[start:end] = hex_hash_to_int16(hash_str)
+    return token_ids
+
+
+def mla_enabled(model_config: "ModelConfig") -> bool:
+    return (
+        hasattr(model_config, "use_mla")
+        and isinstance(model_config.use_mla, bool)
+        and model_config.use_mla
+    )
+
+
+def create_lmcache_metadata(
+    vllm_config=None,
+    model_config=None,
+    parallel_config=None,
+    cache_config=None,
+    role=None,
+):
+    """
+    Create LMCacheMetadata from vLLM configuration.
+
+    This function extracts common metadata creation logic that was duplicated
+    across multiple files.
+
+    Args:
+        vllm_config: vLLM configuration object containing model, parallel, and
+                    cache configs (alternative to individual config parameters)
+        model_config: Model configuration (alternative to vllm_config)
+        parallel_config: Parallel configuration (alternative to vllm_config)
+        cache_config: Cache configuration (alternative to vllm_config)
+
+    Returns:
+        tuple: (LMCacheMetadata, LMCacheEngineConfig)
+    """
+    # Third Party
+    # Try to import from old location before merged https://github.com/vllm-project/vllm/pull/26908
+    try:
+        # Third Party
+        from vllm.utils.torch_utils import get_kv_cache_torch_dtype
+    except ImportError:
+        # Third Party
+        from vllm.utils import get_kv_cache_torch_dtype
+    # First Party
+    from lmcache.v1.metadata import LMCacheMetadata
+
+    config = lmcache_get_or_create_config()
+    # Support both vllm_config object and individual config parameters
+    if vllm_config is not None:
+        model_cfg = vllm_config.model_config
+        parallel_cfg = vllm_config.parallel_config
+        cache_cfg = vllm_config.cache_config
+    else:
+        model_cfg = model_config
+        parallel_cfg = parallel_config
+        cache_cfg = cache_config
+
+    # Get KV cache dtype
+    kv_dtype = get_kv_cache_torch_dtype(cache_cfg.cache_dtype, model_cfg.dtype)
+
+    # Check if MLA is enabled
+    use_mla = mla_enabled(model_cfg)
+
+    # Construct KV shape (for memory pool)
+    num_layer = model_cfg.get_num_layers(parallel_cfg)
+    chunk_size = config.chunk_size
+    num_kv_head = model_cfg.get_num_kv_heads(parallel_cfg)
+    head_size = model_cfg.get_head_size()
+    kv_shape = (num_layer, 1 if use_mla else 2, chunk_size, num_kv_head, head_size)
+
+    # Extract engine_id and kv_connector_extra_config from vllm_config if available
+    engine_id = None
+    kv_connector_extra_config = None
+    if vllm_config is not None and hasattr(vllm_config, "kv_transfer_config"):
+        kv_transfer_config = vllm_config.kv_transfer_config
+        if kv_transfer_config is not None:
+            engine_id = getattr(kv_transfer_config, "engine_id", None)
+            kv_connector_extra_config = getattr(
+                kv_transfer_config, "kv_connector_extra_config", None
+            )
+
+    # Create metadata
+    metadata = LMCacheMetadata(
+        model_name=model_cfg.model,
+        world_size=parallel_cfg.world_size,
+        local_world_size=parallel_cfg.world_size,
+        worker_id=parallel_cfg.rank,
+        local_worker_id=parallel_cfg.rank,
+        kv_dtype=kv_dtype,
+        kv_shape=kv_shape,
+        use_mla=use_mla,
+        role=role,
+        served_model_name=model_cfg.served_model_name,
+        engine_id=engine_id,
+        kv_connector_extra_config=kv_connector_extra_config,
+    )
+
+    return metadata, config
+
+
+def extract_mm_features(
+    request: "Request", modify: bool = False
+) -> Tuple[list[str], list["PlaceholderRange"]]:
+    """
+    Normalize multimodal information from a Request into parallel lists.
+
+    This helper reads either:
+      1) `request.mm_features` (objects each exposing `.identifier` and
+      `.mm_position`), or
+      2) legacy fields `request.mm_hashes` and `request.mm_positions`.
+
+    It returns two equally sized lists: the multimodal hash identifiers and their
+    corresponding positions. If the request contains no multimodal info, it returns
+    `([], [])`.
+
+    Args:
+        request (Request): The source object.
+        modify (bool):
+            Controls copy semantics for the legacy-path return values.
+            - If True and legacy fields are used, shallow-copies are returned so
+              the caller can mutate the lists without affecting `request`.
+            - If False, the original legacy sequences are returned as-is
+              (zero-copy); treat them as read-only.
+
+    Returns:
+        Tuple[list[str], list[PlaceholderRange]]: (`mm_hashes`, `mm_positions`).
+        May be `([], [])` when no multimodal data is present.
+    """
+    if getattr(request, "mm_features", None):
+        mm_hashes, mm_positions = zip(
+            *((f.identifier, f.mm_position) for f in request.mm_features), strict=False
+        )
+        return (list(mm_hashes), list(mm_positions))
+    elif getattr(request, "mm_hashes", None):
+        if modify:
+            return (request.mm_hashes.copy(), request.mm_positions.copy())
+        else:
+            return (request.mm_hashes, request.mm_positions)
+    else:
+        return ([], [])
+
+
+def get_size_bytes(shapes: list[torch.Size], kv_dtypes: list[torch.dtype]):
+    """
+    Calculate the size in bytes with the given shapes and dtypes.
+    """
+    assert len(shapes) == len(kv_dtypes), (
+        f"shapes and dtypes must have the same length, "
+        f"but got {len(shapes)} and {len(kv_dtypes)}"
+    )
+    return sum(
+        shape.numel() * kv_dtype.itemsize
+        for shape, kv_dtype in zip(shapes, kv_dtypes, strict=True)
+    )
+
+
+def calculate_local_rank_and_world_size(vllm_config: "VllmConfig") -> Tuple[int, int]:
+    """
+    Calculate the local worker id and local world size.
+
+    Current assumption (TODO: add custom logic in the future):
+    - Tensor Parallel is intra-node
+    - Pipeline Parallel is inter-node
+
+    Returns:
+        Tuple[int, int]: (local_worker_id, local_world_size)
+    """
+    # First Party
+    from lmcache import torch_dev
+
+    parallel_config = vllm_config.parallel_config
+    global_rank = parallel_config.rank
+    global_world_size = parallel_config.world_size
+    num_gpus = torch_dev.device_count()
+    if global_world_size <= num_gpus:
+        # single node case
+        return parallel_config.rank, parallel_config.world_size
+    else:
+        tp_size = parallel_config.tensor_parallel_size
+        pp_size = parallel_config.pipeline_parallel_size
+        local_world_size = global_world_size // pp_size
+        assert local_world_size == tp_size, (
+            "LMCache is operating under the assumption that the "
+            "local world size is equal to the tensor parallel size "
+            "in multi-node deployment."
+        )
+        local_worker_id = global_rank % local_world_size
+        return local_worker_id, local_world_size
+
+
+def validate_mla_config(config: LMCacheEngineConfig, use_mla: bool) -> None:
+    """Validate MLA-related configuration."""
+    if use_mla and (config.remote_serde != "naive" and config.remote_serde is not None):
+        raise ValueError("MLA only works with naive serde mode..")
+
+    if use_mla and config.use_layerwise and config.enable_blending:
+        raise ValueError(
+            "We haven't supported MLA with Cacheblend yet. Please disable blending."
+        )
+
+
+def calculate_draft_layers(vllm_config: "VllmConfig") -> int:
+    """Calculate the number of draft layers for speculative decoding."""
+    assert vllm_config is not None, "vllm_config required for vLLM mode"
+
+    num_draft_layers = 0
+    model_config = vllm_config.model_config
+
+    if vllm_config.speculative_config is not None:
+        logger.info(
+            "vllm_config.speculative_config: %s", vllm_config.speculative_config
+        )
+        if vllm_config.speculative_config.method == "deepseek_mtp":
+            num_draft_layers = getattr(
+                model_config.hf_config, "num_nextn_predict_layers", 0
+            )
+        elif vllm_config.speculative_config.use_eagle():
+            try:
+                draft_model_config = vllm_config.speculative_config.draft_model_config
+                num_draft_layers = draft_model_config.get_num_layers(
+                    vllm_config.parallel_config
+                )
+                logger.info("EAGLE detected %d extra layer(s)", num_draft_layers)
+            except Exception:
+                logger.info(
+                    "EAGLE detected, but failed to get the number of extra layers"
+                    "falling back to 1"
+                )
+                num_draft_layers = 1
+    return num_draft_layers
+
+
+def is_dp_rank0(vllm_config: "VllmConfig") -> bool:
+    return vllm_config.parallel_config.data_parallel_rank_local == 0
diff --git a/lmcache/integration/vllm/vllm_ec_adapter.py b/lmcache/integration/vllm/vllm_ec_adapter.py
new file mode 100644
index 0000000..d004260
--- /dev/null
+++ b/lmcache/integration/vllm/vllm_ec_adapter.py
@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+
+# Standard
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+# Third Party
+from vllm.distributed.ec_transfer.ec_connector.base import ECConnectorMetadata
+from vllm.logger import init_logger
+from vllm.v1.core.sched.output import SchedulerOutput
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.integration.vllm.utils import (
+    create_lmcache_ec_config,
+    create_lmcache_metadata,
+)
+from lmcache.v1.ec_engine import ECCacheEngine
+
+if TYPE_CHECKING:
+    # Third Party
+    from vllm.config import VllmConfig
+    from vllm.distributed.ec_transfer.ec_connector.base import (
+        ECConnectorBase,
+        ECConnectorRole,
+    )
+    from vllm.v1.request import Request
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class MMMeta:
+    mm_hash: str
+
+    @staticmethod
+    def make_meta(mm_hash: str) -> "MMMeta":
+        """Create metadata for a single multimodal hash."""
+        return MMMeta(mm_hash=mm_hash)
+
+
+@dataclass
+class LMCacheECConnectorMetadata(ECConnectorMetadata):
+    mm_datas: list[MMMeta] = field(default_factory=list)
+
+    def add_mm_data(self, mm_data: MMMeta) -> None:
+        """Append one multimodal metadata entry."""
+        self.mm_datas.append(mm_data)
+
+
+class LMCacheECConnectorImpl:
+    """Worker- and scheduler-side glue between vLLM's EC connector and LMCache.
+
+    Bridges vLLM ``ECConnectorBase`` calls to an :class:`ECCacheEngine`: on the
+    worker side it saves and loads encoder tensors, and on the scheduler side
+    it tracks which multimodal hashes need to be loaded next step.
+    """
+
+    def __init__(
+        self,
+        vllm_config: "VllmConfig",
+        role: "ECConnectorRole",
+        parent: "ECConnectorBase",
+    ) -> None:
+        """Initialize the EC connector implementation.
+
+        Args:
+            vllm_config: vLLM engine configuration; ``ec_transfer_config`` and
+                ``model_config`` must be set.
+            role: vLLM EC connector role (worker or scheduler).
+            parent: vLLM ``ECConnectorBase`` that owns this implementation;
+                used to read connector metadata and producer/consumer state.
+
+        Raises:
+            ValueError: if ``vllm_config.ec_transfer_config`` is None, or if
+                no LMCache storage backend is configured.
+        """
+        self._parent = parent
+
+        # Scheduler-side state: set of multimodal hashes to load. Unused on
+        # worker-side instances; kept here because vLLM's ECConnectorBase
+        # multiplexes both roles onto a single class.
+        self._mm_hashes_need_loads: set[str] = set()
+
+        if vllm_config.ec_transfer_config is None:
+            raise ValueError("ec_transfer_config must be set for ECConnectorBase")
+
+        # Build EC config from standard LMCache config + EC-prefixed overrides.
+        config = create_lmcache_ec_config()
+
+        # EC scheduler-side instances must look like workers to LMCache:
+        # ``has_cache_item`` calls ``engine.contains()``, which needs a fully
+        # constructed StorageManager (including LocalCPUBackend, since the
+        # local-disk backend is layered on top of it). LMCache's
+        # ``CreateStorageBackends`` skips the CPU backend when
+        # ``metadata.role == "scheduler"`` and then asserts on it for the
+        # disk backend — passing role="scheduler" therefore aborts startup.
+        # Until LMCache grows a scheduler-friendly storage path (or EC
+        # splits scheduler/worker into separate engines), keep role pinned
+        # to "worker" here regardless of the vLLM-side role.
+        lmcache_metadata, _ = create_lmcache_metadata(vllm_config, role="worker")
+
+        self._ec_engine = ECCacheEngine(
+            config=config,
+            metadata=lmcache_metadata,
+            encoder_dtype=vllm_config.model_config.dtype,
+        )
+
+    # ------------------------------
+    # Worker-side methods
+    # ------------------------------
+
+    def start_load_caches(
+        self,
+        encoder_cache: dict[str, torch.Tensor],
+        **kwargs: Any,
+    ) -> None:
+        """Load needed encoder caches from LMCache into vLLM encoder_cache."""
+        # vLLM's ECConnectorBase exposes connector metadata only via the
+        # underscored accessor; matches the pattern used in vllm_v1_adapter.py
+        # for the KV connector.
+        metadata = self._parent._get_connector_metadata()  # noqa: SLF001
+        if metadata is None:
+            logger.warning(
+                "In connector.start_load_caches, but the connector metadata is None"
+            )
+            return
+        if not isinstance(metadata, LMCacheECConnectorMetadata):
+            raise TypeError(f"Unexpected metadata type: {type(metadata)}")
+
+        device = torch_device_type
+        for mm_data in metadata.mm_datas:
+            mm_hash = mm_data.mm_hash
+            if mm_hash in encoder_cache:
+                # vLLM already has it; don't overwrite.
+                continue
+            tensor = self._ec_engine.get(mm_hash, device)
+            if tensor is None:
+                continue
+            encoder_cache[mm_hash] = tensor
+            logger.debug("Loaded encoder cache for hash %s", mm_hash)
+
+    def save_caches(
+        self,
+        encoder_cache: dict[str, torch.Tensor],
+        mm_hash: str,
+        **kwargs: Any,
+    ) -> None:
+        """Save one encoder cache entry from vLLM into LMCache."""
+
+        if not getattr(self._parent, "is_producer", False):
+            return
+
+        if mm_hash not in encoder_cache:
+            return
+
+        did_store = self._ec_engine.put(mm_hash, encoder_cache[mm_hash])
+        if did_store:
+            logger.debug("Saved encoder cache for mm_hash %s", mm_hash)
+
+    # ------------------------------
+    # Scheduler-side methods
+    # ------------------------------
+
+    def has_cache_item(self, identifier: str) -> bool:
+        """Return whether LMCache already contains the encoder cache for hash."""
+        return self._ec_engine.contains(identifier)
+
+    def update_state_after_alloc(self, request: "Request", index: int) -> None:
+        """Track which multimodal item (request.mm_features[index]) needs loading."""
+        mm_hash = request.mm_features[index].identifier
+        self._mm_hashes_need_loads.add(mm_hash)
+
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> ECConnectorMetadata:
+        """Build worker-load metadata for hashes queued this scheduler step."""
+        _ = scheduler_output
+        meta = LMCacheECConnectorMetadata()
+        for mm_hash in sorted(self._mm_hashes_need_loads):
+            meta.add_mm_data(MMMeta.make_meta(mm_hash))
+        self._mm_hashes_need_loads.clear()
+        return meta
+
+    # ------------------------------
+    # Helpers
+    # ------------------------------
+
+    def close(self) -> None:
+        """Release EC engine resources."""
+        if hasattr(self, "_ec_engine") and self._ec_engine is not None:
+            self._ec_engine.close()
diff --git a/lmcache/integration/vllm/vllm_multi_process_adapter.py b/lmcache/integration/vllm/vllm_multi_process_adapter.py
new file mode 100644
index 0000000..d091048
--- /dev/null
+++ b/lmcache/integration/vllm/vllm_multi_process_adapter.py
@@ -0,0 +1,1802 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# Standard
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Callable, NoReturn, Protocol
+import enum
+import os
+import threading
+import uuid
+
+# Third Party
+import torch
+import zmq
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.request_telemetry.factory import RequestTelemetryFactory
+from lmcache.integration.vllm.utils import vllm_layout_hints
+from lmcache.utils import _lmcache_nvtx_annotate, init_logger
+from lmcache.v1.multiprocess.custom_types import (
+    BlockAllocationRecord,
+    IPCCacheServerKey,
+    KVCache,
+)
+from lmcache.v1.multiprocess.group_view import (
+    EngineGroupInfo,
+    expand_engine_block_ids,
+)
+from lmcache.v1.multiprocess.mq import MessageQueueClient, MessagingFuture
+from lmcache.v1.multiprocess.protocol import RequestType, get_response_class
+from lmcache.v1.multiprocess.transfer_context import (
+    EngineDrivenTransferContext,
+    TransferContext,
+    create_transfer_context,
+)
+from lmcache.v1.periodic_thread import PeriodicThread, ThreadLevel, ThreadRunSummary
+from lmcache.v1.platform import _registry as platform_registry
+
+logger = init_logger(__name__)
+
+
+class ExtraConfigDefault(enum.Enum):
+    """Centralized default values for extra_config keys.
+
+    Each member's *name* is the key used in the extra_config dict,
+    and its *value* is the default.
+    """
+
+    # Timeout (seconds) for blocking MQ requests: initial
+    # chunk-size query, KV cache registration/unregistration,
+    # and other synchronous operations.
+    mq_timeout = 300.0
+    # Interval (seconds) between periodic heartbeat pings
+    # to the server.
+    heartbeat_interval = 10.0
+    # Routing mode for ``create_transfer_context``: ``auto`` keeps the
+    # historical CUDA -> lmcache_driven / others -> engine_driven dispatch;
+    # ``lmcache_driven`` forces the IPC / SHM zero-copy path where the
+    # LMCache server pulls data via device handles;
+    # ``engine_driven`` forces the worker-side gather/scatter copy path.
+    # Mirrors the ``LMCACHE_MP_TRANSFER_MODE`` env var; this extra_config
+    # key wins when both are set.
+    mp_transfer_mode = "auto"
+
+
+# Backward-compatible aliases for the legacy `lmcache_mp_connector_0180`
+# entry point, which still passes these as positional/keyword args.
+DEFAULT_MQ_TIMEOUT: float = ExtraConfigDefault.mq_timeout.value
+DEFAULT_HEARTBEAT_INTERVAL: float = ExtraConfigDefault.heartbeat_interval.value
+
+_EXTRA_CONFIG_KEY_PREFIX = "lmcache.mp."
+
+# Floor (seconds) of the MP server's worker reap timeout. It only covers the
+# default 10 s heartbeat interval (3 x 10 s); the adapter warns at startup
+# when 3 x heartbeat_interval exceeds it (server timeout must be raised too).
+_SERVER_REAP_TIMEOUT_FLOOR_SECONDS: float = 30.0
+
+
+def _resolve_extra_config(
+    extra_config: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Resolve extra_config against :class:`ExtraConfigDefault`.
+
+    Keys in *extra_config* are expected to carry the
+    ``lmcache.mp.`` prefix (e.g. ``lmcache.mp.mq_timeout``).
+    The prefix is stripped before matching against
+    :class:`ExtraConfigDefault` members.
+
+    All ``lmcache.mp.*`` entries are logged.  Entries whose
+    value differs from the default are additionally marked as
+    *overridden*.
+
+    Args:
+        extra_config: User-supplied config dict (may be *None*).
+
+    Returns:
+        A dict keyed by :pyattr:`ExtraConfigDefault` member names.
+    """
+    stripped: dict[str, Any] = {}
+    if extra_config is not None:
+        for k, v in extra_config.items():
+            if k.startswith(_EXTRA_CONFIG_KEY_PREFIX):
+                short = k[len(_EXTRA_CONFIG_KEY_PREFIX) :]
+                stripped[short] = v
+
+    resolved: dict[str, Any] = {}
+    for item in ExtraConfigDefault:
+        default = item.value
+        raw = stripped.get(item.name)
+        value = type(default)(raw) if raw is not None else default
+        if value != default:
+            logger.info(
+                "%s%s = %s (overridden, default: %s)",
+                _EXTRA_CONFIG_KEY_PREFIX,
+                item.name,
+                value,
+                default,
+            )
+        else:
+            logger.info(
+                "%s%s = %s",
+                _EXTRA_CONFIG_KEY_PREFIX,
+                item.name,
+                value,
+            )
+        resolved[item.name] = value
+    return resolved
+
+
+class _IpcEvent(Protocol):
+    def ipc_handle(self) -> Any: ...
+
+    def wait(self, stream: Any = None) -> None: ...
+
+
+def wrap_kv_caches(kv_caches: dict[str, torch.Tensor]) -> KVCache:
+    # Emit a per-layer (name, shape, dtype) summary so the operator can
+    # verify the exact layer set & tensor geometry being shipped to the
+    # LMCache server, then the low-noise count of handles being wrapped.
+    kept_summary = [
+        (name, tuple(tensor.shape), str(tensor.dtype))
+        for name, tensor in kv_caches.items()
+    ]
+    logger.debug(
+        "KV cache transfer keeping %d layer(s) (name, shape, dtype):\n%s",
+        len(kept_summary),
+        "\n".join(
+            f"  [{i}] {name}  shape={shape}  dtype={dtype}"
+            for i, (name, shape, dtype) in enumerate(kept_summary)
+        ),
+    )
+    logger.info("Wrapping %d KV cache tensors for IPC", len(kv_caches))
+    # Per-iteration resource management: if wrapping the N-th tensor
+    # raises, ``shm_unlink`` whatever earlier iterations already
+    # registered with POSIX SHM so the named segments do not outlive
+    # the failed batch. CUDA wrappers do not own a named segment and
+    # are skipped via the duck-typed ``shm_name`` check.
+    wrappers: KVCache = []
+    try:
+        for tensor in kv_caches.values():
+            wrappers.append(wrap_one_kv_cache(tensor))
+    except BaseException:
+        _release_partial_kv_wrappers(wrappers)
+        raise
+    return wrappers
+
+
+def _release_partial_kv_wrappers(wrappers: list[Any]) -> None:
+    """Best-effort unlink of SHM segments owned by partially built wrappers.
+
+    Used by :func:`wrap_kv_caches` to roll back a half-finished batch
+    when a later iteration raises. Only POSIX-SHM-backed wrappers carry
+    a ``shm_name`` attribute, so other wrapper kinds (e.g. CUDA-IPC)
+    are silently skipped.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.posix_shm import shm_unlink
+
+    for w in wrappers:
+        name = getattr(w, "shm_name", None)
+        if name is None:
+            continue
+        try:
+            shm_unlink(name)
+        except Exception:  # pragma: no cover - best effort
+            logger.debug("shm_unlink failed during rollback", exc_info=True)
+
+
+def wrap_one_kv_cache(tensor: torch.Tensor) -> Any:
+    """Dispatch by ``tensor.device.type`` via the platform registry.
+
+    Concrete factories are auto-discovered from
+    ``DeviceIPCWrapper`` subclasses under ``lmcache.v1.platform``, so
+    this call site stays free of if/elif chains and new accelerators
+    plug in by shipping a sibling wrapper class.
+    """
+    return platform_registry.get_kv_wrapper_factory(tensor.device.type)(tensor)
+
+
+def send_lmcache_request(
+    mq_client: MessageQueueClient,
+    request_type: RequestType,
+    payloads: list[Any],
+) -> MessagingFuture[Any]:
+    """
+    Helper function to send the request to the LMCache multiprocess server
+
+    Args:
+        mq_client: The LMCache multiprocess mode message queue client
+        request_type: The request type
+        payloads: The request payloads
+
+    Returns:
+        A messaging future for the request
+    """
+
+    future = mq_client.submit_request(
+        request_type, payloads, get_response_class(request_type)
+    )
+    return future
+
+
+def get_lmcache_chunk_size(
+    mq_client: MessageQueueClient,
+    timeout: float = DEFAULT_MQ_TIMEOUT,
+) -> int:
+    """
+    Helper function to get the LMCache chunk size from the server
+
+    Args:
+        mq_client: The LMCache multiprocess mode message queue client
+        timeout: Timeout in seconds for the blocking request.
+
+    Returns:
+        An integer representing the LMCache chunk size
+    """
+    future = send_lmcache_request(mq_client, RequestType.GET_CHUNK_SIZE, [])
+    lmcache_tokens_per_chunk = future.result(timeout=timeout)
+    return lmcache_tokens_per_chunk
+
+
+def _raise_server_unreachable(server_url: str, timeout: float) -> NoReturn:
+    """Raise a verbose ConnectionError when the LMCache MP server is
+    unreachable.
+
+    The message intentionally spells out the most common cause (the
+    standalone ``lmcache server`` process is not running), the URL that
+    was being dialed, and the exact command to start it -- so that users
+    landing here via ``vllm serve --kv-offloading-backend lmcache`` are
+    not left guessing.
+    """
+    hint = (
+        "Cannot reach the LMCache MP server at "
+        f"'{server_url}' within {timeout}s.\n"
+        "This usually means the standalone LMCache server is not "
+        "running, or it is listening on a different host/port.\n"
+        "To start one locally with the default port (5555):\n"
+        "    lmcache server --l1-size-gb 20 --eviction-policy LRU\n"
+        "To target a different host/port, override via "
+        "kv_connector_extra_config (lmcache.mp.host / lmcache.mp.port), "
+        "e.g.:\n"
+        '    --kv-transfer-config \'{"kv_connector":'
+        '"LMCacheMPConnector","kv_role":"kv_both",'
+        '"kv_connector_extra_config":{"lmcache.mp.host":'
+        '"tcp://localhost","lmcache.mp.port":5555}}\'\n'
+        "See https://docs.lmcache.ai/mp/quickstart.html for details."
+    )
+    logger.warning(hint)
+    raise ConnectionError(hint) from None
+
+
+def send_ping(
+    mq_client: MessageQueueClient,
+    timeout: float,
+    instance_id: int | None = None,
+) -> bool:
+    """Send a PING request and return the result.
+
+    Args:
+        mq_client: The message queue client.
+        timeout: Seconds to wait for the server's response.
+        instance_id: The worker's instance ID so the server can refresh its
+            liveness, or None for an untracked prober (scheduler adapter).
+
+    Returns:
+        True if server is healthy, False on timeout or error.
+    """
+    try:
+        future = send_lmcache_request(mq_client, RequestType.PING, [instance_id])
+        return future.result(timeout=timeout)
+    except TimeoutError:
+        return False
+    except Exception:
+        logger.debug("Ping failed with exception", exc_info=True)
+        return False
+
+
+@dataclass
+class ParallelStrategy:
+    use_mla: bool
+    """Whether to use the MLA."""
+
+    vllm_world_size: int
+    """Number of workers managed by one vLLM scheduler (TP × PP; excludes DP).
+
+    Mirrors ``vllm.parallel_config.world_size``.
+    """
+
+    vllm_worker_id: int
+    """This worker's rank within its scheduler group."""
+
+    tp_size: int
+    """The tensor parallel size."""
+
+    pp_size: int
+    """The pipeline parallel size."""
+
+    n_servers: int
+    """Number of LMCache servers backing this deployment"""
+
+    @property
+    def kv_world_size(self) -> int:
+        """Number of pieces a single token chunk's KV cache is split into
+        on the LMCache server storage."""
+        if self.use_mla:
+            # In this PR we do not support PP + TP + MLA in multi-server mode.
+            # A precondition check enforces pp_size == 1, so kv_world_size for
+            # MLA can be derived as world_size / tp_size.
+            return self.vllm_world_size // self.tp_size
+        return self.vllm_world_size // self.n_servers
+
+    @property
+    def kv_worker_id(self) -> int:
+        """Index of the piece of a single token chunk's KV cache
+        that the current worker is responsible for,
+        in ``[0, kv_world_size)``."""
+        if self.use_mla:
+            return self.vllm_worker_id // self.tp_size
+        return self.vllm_worker_id % (self.vllm_world_size // self.n_servers)
+
+    @property
+    def kv_tp_size(self) -> int:
+        """Tensor-parallel size as seen from a single LMCache server."""
+        return self.tp_size // self.n_servers
+
+    @property
+    def is_kv_writer(self) -> bool:
+        """Whether this rank is responsible for storing KV."""
+        if not self.use_mla:
+            return True
+        # MLA: only first rank per node is a writer.
+        return self.vllm_worker_id % (self.tp_size // self.n_servers) == 0
+
+
+def _normalize_adapter_init_args(
+    vllm_block_size: int,
+    parallel_strategy: ParallelStrategy | int,
+    legacy_block_size: int | None,
+    mq_timeout: float,
+) -> tuple[int, ParallelStrategy, float]:
+    """Normalize adapter constructor args from old and new vLLM connectors.
+
+    Args:
+        vllm_block_size: The vLLM block size for the current connector API, or
+            the legacy KV world size when ``parallel_strategy`` is an int.
+        parallel_strategy: The current ``ParallelStrategy`` object, or the
+            legacy KV worker id from older vLLM MP connectors.
+        legacy_block_size: The legacy vLLM block size passed positionally by
+            older vLLM MP connectors.
+        mq_timeout: Timeout in seconds for synchronous message queue requests.
+
+    Returns:
+        A tuple of normalized ``(vllm_block_size, parallel_strategy,
+        mq_timeout)``.
+
+    Raises:
+        TypeError: If the connector argument shape is not supported.
+    """
+    if isinstance(parallel_strategy, ParallelStrategy):
+        return vllm_block_size, parallel_strategy, mq_timeout
+    if not isinstance(parallel_strategy, int) or legacy_block_size is None:
+        raise TypeError(
+            "parallel_strategy must be ParallelStrategy, or legacy "
+            "(kv_world_size, kv_worker_id, block_size) arguments"
+        )
+
+    kv_world_size = int(vllm_block_size)
+    kv_worker_id = int(parallel_strategy)
+    strategy = ParallelStrategy(
+        use_mla=False,
+        vllm_world_size=kv_world_size,
+        vllm_worker_id=kv_worker_id,
+        tp_size=kv_world_size,
+        pp_size=1,
+        n_servers=1,
+    )
+    return int(legacy_block_size), strategy, mq_timeout
+
+
+class HeartbeatThread(PeriodicThread):
+    """Periodically checks server health via PING.
+
+    Manages a threading.Event that adapters use to gate operations.
+    When unhealthy, the adapter enters degraded mode; if the server
+    recovers, the adapter automatically resumes normal operation.
+    """
+
+    def __init__(
+        self,
+        mq_client: MessageQueueClient,
+        health_event: threading.Event,
+        interval: float = DEFAULT_HEARTBEAT_INTERVAL,
+        instance_id: int | None = None,
+    ):
+        """
+        Args:
+            mq_client: The message queue client used to send PING requests.
+            health_event: A threading.Event shared with the adapter.
+                Set when the server is healthy, cleared when unhealthy.
+                Adapters check this event to decide whether to proceed
+                with operations or enter degraded mode.
+            interval: Seconds between heartbeat pings and ping timeout.
+            instance_id: The worker's instance ID sent with each PING so the
+                server can refresh its liveness, or None for an untracked
+                prober (the scheduler adapter).
+        """
+        super().__init__(
+            name="lmcache-heartbeat",
+            interval=interval,
+            level=ThreadLevel.CRITICAL,
+        )
+        self._mq_client = mq_client
+        self._health_event = health_event
+        self._interval = interval
+        self._instance_id = instance_id
+
+        # Optional callback invoked on the unhealthy->healthy edge,
+        # before the health event is set. See register_recover_callback.
+        def noop() -> bool:
+            return True
+
+        self._recover_callback: Callable[[], bool] = noop
+
+    def register_recover_callback(self, callback: Callable[[], bool]) -> None:
+        """Register a callback fired on the unhealthy->healthy transition.
+
+        The callback runs **before** the health event is set. It must
+        return ``True`` on success (event will be set) or ``False`` on
+        failure (event will stay cleared, and the next heartbeat will
+        invoke the callback again on the next successful PING).
+
+        The callback function should NEVER raise exceptions.
+
+        Intended for setup work that must complete before downstream
+        callers observe the recovery — for example, re-registering KV
+        caches with a server that just restarted.
+
+        Should be called before :meth:`start`. Only one callback is
+        supported; a second call replaces the first.
+
+        Args:
+            callback: Zero-arg callable returning a success bool.
+        """
+        self._recover_callback = callback
+
+    def _execute(self) -> ThreadRunSummary:
+        """Run one heartbeat cycle: ping, recover callback, event update.
+
+        A cycle that observes a stop request returns without firing the
+        callback or touching the event — a straggler success after
+        UNREGISTER must not re-register a ghost context.
+        """
+        was_healthy = self._health_event.is_set()
+        healthy = send_ping(
+            self._mq_client, timeout=self._interval, instance_id=self._instance_id
+        )
+
+        if self.stop_requested:
+            return ThreadRunSummary(
+                success=True,
+                message="stop requested; skipping health update",
+            )
+
+        need_trigger_recover = (
+            healthy and not was_healthy and self._recover_callback is not None
+        )
+
+        # Try to call recover callback
+        if need_trigger_recover:
+            logger.warning(
+                "LMCache server is healthy again, triggering recovery callback"
+            )
+            # If the callback fails, it should not become healthy
+            healthy = self._recover_callback()
+
+        if healthy:
+            self._health_event.set()
+            if not was_healthy:
+                logger.warning(
+                    "LMCache server is healthy again — resuming normal operation"
+                )
+        else:
+            self._health_event.clear()
+            if was_healthy:
+                logger.warning("LMCache server is unhealthy — entering degraded mode")
+
+        return ThreadRunSummary(
+            success=True,
+            message="healthy" if healthy else "unhealthy",
+        )
+
+
+@dataclass
+class LoadStoreOp:
+    token_ids: list[int]
+    """Token IDs for the load/store operation"""
+
+    block_ids: list[list[int]]
+    """Block IDs for the load/store operation, indexed by engine KV cache
+    group (one inner list per engine group). Worker submit paths expand
+    this to LMCache KV group order before sending requests to the server.
+    """
+
+    start: int = 0
+    """Start token index"""
+
+    end: int = 0
+    """End token index"""
+
+    skip_first_n_tokens: int = 0
+    """Number of tokens to skip writing at the beginning of the retrieve
+    range. Used to avoid overwriting APC-shared GPU blocks during retrieve."""
+
+    @property
+    def flat_block_ids(self) -> list[int]:
+        """Return all block IDs flattened for group-blind error paths.
+
+        Handles both the normal ``list[list[int]]`` format and the
+        IPC-flattened ``list[int]`` format that vLLM v0.19.0 produces when
+        ``SchedulerOutput`` serializes single-element nested lists across
+        process boundaries (e.g. ``[[20, 21]]`` → ``[20, 21]``).
+        Returns an empty list when ``block_ids`` is empty.
+        """
+        if not self.block_ids:
+            return []
+        # Defend against IPC serialization flattening [[20, 21, …]] → [20, 21, …]
+        if isinstance(self.block_ids[0], int):
+            return list(self.block_ids)
+        return [
+            block_id
+            for group_block_ids in self.block_ids
+            for block_id in group_block_ids
+        ]
+
+
+StoreResult = bool
+RetrieveResult = bool
+LookupResult = int
+
+
+class LMCacheMPSchedulerAdapter:
+    def __init__(
+        self,
+        server_urls: list[str],
+        context: zmq.Context,
+        model_name: str,
+        vllm_block_size: int,
+        parallel_strategy: ParallelStrategy | int,
+        legacy_block_size: int | None = None,
+        *,
+        mq_timeout: float = DEFAULT_MQ_TIMEOUT,
+        heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL,
+        extra_config: dict[str, Any] | None = None,
+    ):
+        """
+        Args:
+            server_urls: The servers URL for the LMCache message queue
+            context: The ZMQ context
+            model_name: The model name used for LMCache keys
+            vllm_block_size: The block size used in vLLM
+            parallel_strategy:
+                The parallel strategy, which includes `use_mla`,
+                `kv_world_size`, `kv_worker_id` and so on. Older vLLM
+                connectors pass the KV worker id here.
+            legacy_block_size: The vLLM block size passed positionally by
+                older vLLM connectors.
+            mq_timeout: Timeout in seconds for message queue requests.
+                Ignored when ``extra_config`` is provided.
+            heartbeat_interval: Interval in seconds between heartbeat pings.
+                Ignored when ``extra_config`` is provided.
+            extra_config: Optional dict with keys starting with
+                ``lmcache.mp.`` (e.g., ``lmcache.mp.mq_timeout``). When
+                provided, it overrides ``mq_timeout`` / ``heartbeat_interval``.
+        """
+        vllm_block_size, parallel_strategy, mq_timeout = _normalize_adapter_init_args(
+            vllm_block_size,
+            parallel_strategy,
+            legacy_block_size,
+            mq_timeout,
+        )
+        assert len(server_urls) >= 1, "At least one server url required"
+        self._server_urls: list[str] = list(server_urls)
+        self.mq_clients: dict[str, MessageQueueClient] = {
+            url: MessageQueueClient(url, context) for url in self._server_urls
+        }
+        if extra_config is not None:
+            cfg = _resolve_extra_config(extra_config)
+            mq_timeout = cfg[ExtraConfigDefault.mq_timeout.name]
+            heartbeat_interval = cfg[ExtraConfigDefault.heartbeat_interval.name]
+        self._mq_timeout = mq_timeout
+
+        # Lookup state tracking:
+        # - _pending_lookups: request_ids submitted but not yet resolved
+        # - _finished_lookup_results: cached chunk count keyed by request_id,
+        #   so that repeated calls to check_lookup_result return the same value
+        #   even after the server has already popped the job (exactly-once).
+        # - _per_server_hits: {request_id: {server_url: hit_chunks}}.
+        #   Per-server hit counts, used to detect disagreement and free tail locks.
+        self._pending_lookups: set[str] = set()
+        self._finished_lookup_results: dict[str, int] = {}
+        self._per_server_hits: dict[str, dict[str, int]] = {}
+        self._lookup_params: dict[str, tuple[list[int], str]] = {}
+
+        self.model_name = model_name
+        self.parallel_strategy = parallel_strategy
+
+        # Read chunk size from lmcache
+        chunk_sizes: dict[str, int] = {}
+        for url, client in self.mq_clients.items():
+            try:
+                chunk_sizes[url] = get_lmcache_chunk_size(
+                    client, timeout=self._mq_timeout
+                )
+            except TimeoutError:
+                for c in self.mq_clients.values():
+                    c.close()
+                _raise_server_unreachable(url, self._mq_timeout)
+
+        # All servers must share chunk_size, otherwise the min() aggregation
+        # over per-server hits would mix different granularities.
+        unique_sizes = set(chunk_sizes.values())
+        if len(unique_sizes) != 1:
+            raise ValueError(
+                f"All LMCache servers must share the same chunk_size, got {chunk_sizes}"
+            )
+        self.lmcache_tokens_per_chunk = unique_sizes.pop()
+
+        assert self.lmcache_tokens_per_chunk % vllm_block_size == 0, (
+            "LMCache chunk size should be a multiple of vLLM block size"
+        )
+        self.blocks_in_chunk = self.lmcache_tokens_per_chunk // vllm_block_size
+
+        # Health state: one Event per server. The adapter is considered healthy
+        # only if ALL per-server events are set (any unhealthy server taints
+        # the whole adapter, matching the min() semantics used for lookups).
+        self._health_events: dict[str, threading.Event] = {}
+        for url in self._server_urls:
+            ev = threading.Event()
+            ev.set()
+            self._health_events[url] = ev
+
+        # Heartbeat thread is created but NOT started yet.
+        # It will be lazily started on the first lookup
+        # request, by which time vLLM is fully ready.
+        self._heartbeat_interval = heartbeat_interval
+        self._heartbeats: dict[str, HeartbeatThread] = {}
+        self._heartbeat_lock = threading.Lock()
+
+    @property
+    def world_size(self) -> int:
+        """Get the kv world size."""
+        return self.parallel_strategy.kv_world_size
+
+    @property
+    def tp_size(self) -> int:
+        """The tensor parallel size."""
+        return self.parallel_strategy.kv_tp_size
+
+    @property
+    def is_healthy(self) -> bool:
+        """True iff every backing LMCache server is healthy."""
+        return all(ev.is_set() for ev in self._health_events.values())
+
+    def _ensure_heartbeat_started(self) -> None:
+        """Lazily start the heartbeat thread on first use."""
+        if self._heartbeats is not None:
+            return
+        with self._heartbeat_lock:
+            if self._heartbeats is not None:
+                return
+            for url, client in self.mq_clients.items():
+                hb = HeartbeatThread(
+                    mq_client=client,
+                    health_event=self._health_events[url],
+                    interval=self._heartbeat_interval,
+                )
+                hb.start()
+                self._heartbeats[url] = hb
+
+    @_lmcache_nvtx_annotate
+    def maybe_submit_lookup_request(
+        self,
+        request_id: str,
+        token_ids: list[int],
+        cache_salt: str = "",
+    ):
+        """
+        Submit a new lookup request to LMCache if there is no ongoing request.
+
+        Sends a LOOKUP request to the server and blocks until a prefetch
+        job ID is returned.  The actual prefetch result can then be polled
+        via ``check_lookup_result``.
+
+        Args:
+            request_id: The ID of the lookup request. The same ID indicates it's
+                from the same request
+            token_ids: Token IDs to lookup from LMCache
+            cache_salt: Per-user isolation salt. Requests with different
+                cache_salt values produce separate cache entries.
+
+        Returns:
+            None
+
+        Notes:
+            This function will have a side-effect: submitting a look up request to
+            LMCache, which will essentially 'lock' the KV cache chunks in the LMCache
+            for later retrieve operations.
+            In the meantime, this function will record the lookup request, and the
+            status of the look up request can be checked by `check_lookup_result`.
+        """
+        self._ensure_heartbeat_started()
+
+        if not self.is_healthy:
+            return
+
+        if request_id in self._pending_lookups:
+            # Skip if there is already a lookup request
+            return
+
+        aligned_end = (
+            len(token_ids) // self.lmcache_tokens_per_chunk
+        ) * self.lmcache_tokens_per_chunk
+
+        key = self._create_key(
+            token_ids,
+            start=0,
+            end=aligned_end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        ).no_worker_id_version()
+
+        futures: dict[str, MessagingFuture[Any]] = {
+            url: send_lmcache_request(
+                self.mq_clients[url],
+                RequestType.LOOKUP,
+                [key, self.tp_size],
+            )
+            for url in self._server_urls
+        }
+
+        # Any one server failure means the whole lookup fails.
+        for url, fut in futures.items():
+            try:
+                fut.result(timeout=self._mq_timeout)
+            except TimeoutError:
+                logger.warning(
+                    "LOOKUP to %s timed out after %ss. Marking server as unhealthy.",
+                    url,
+                    self._mq_timeout,
+                )
+                self._health_events[url].clear()
+                return
+
+        self._pending_lookups.add(request_id)
+        self._lookup_params[request_id] = (token_ids, cache_salt)
+
+    def _free_inconsistent_lookup_locks(
+        self,
+        request_id: str,
+        per_server: dict[str, int],
+        min_chunks: int,
+    ) -> None:
+        """Release over-hit tail locks on servers that reported more than min.
+
+        When servers disagree on hit chunk counts, servers reporting more
+        than min_chunks have locked chunks in the range
+        [min_chunks * tokens_per_chunk, hit_chunks * tokens_per_chunk)
+        that will never be retrieved. This method frees those tail locks.
+
+        Args:
+            request_id: The lookup request ID.
+            per_server: Per-server hit chunk counts.
+            min_chunks: Minimum hit chunk count across all servers.
+        """
+        token_ids_l, cs = self._lookup_params.pop(request_id, (None, None))
+        if token_ids_l is not None:
+            for url, hit_chunks in per_server.items():
+                if hit_chunks <= min_chunks:
+                    continue
+                tail_end = min(
+                    hit_chunks * self.lmcache_tokens_per_chunk, len(token_ids_l)
+                )
+                tail_key = self._create_key(
+                    token_ids=token_ids_l,
+                    start=min_chunks * self.lmcache_tokens_per_chunk,
+                    end=tail_end,
+                    request_id=request_id,
+                    cache_salt=cs or "",
+                ).no_worker_id_version()
+                send_lmcache_request(
+                    self.mq_clients[url],
+                    RequestType.FREE_LOOKUP_LOCKS,
+                    [tail_key, self.tp_size],
+                )
+
+    @_lmcache_nvtx_annotate
+    def check_lookup_result(self, request_id: str) -> int | None:
+        """
+        Check the result of a previously submitted lookup request.
+
+        Sends a QUERY_PREFETCH_STATUS request to the servers and blocks
+        until the server responds.  Returns the matched token count
+        when the prefetch is complete, or None if still in progress.
+
+        Args:
+            request_id: The ID of the lookup request submitted in
+                `maybe_submit_lookup_request`
+
+        Returns:
+            An integer representing the total number of tokens matched
+            in LMCache (prefix matching), or
+            None if the lookup request is not finished yet.
+        """
+        if request_id not in self._pending_lookups:
+            # No job — either unhealthy at submit time or already cleaned up.
+            # Return the cached aggregate if any, otherwise 0.
+            return self._finished_lookup_results.get(request_id, 0)
+
+        if not self.is_healthy:
+            # Server went down — give up on this lookup
+            return 0
+
+        if request_id in self._finished_lookup_results:
+            # Aggregation already done; return the cached value.
+            return self._finished_lookup_results[request_id]
+
+        # Persistent accumulator for this request. A server present in
+        # the dict has already handed over its final hit count and must
+        # not be polled again; absence means "not yet observed".
+        per_server = self._per_server_hits.setdefault(request_id, {})
+        unresolved_urls = [u for u in self._server_urls if u not in per_server]
+
+        futures: dict[str, MessagingFuture[Any]] = {
+            url: send_lmcache_request(
+                self.mq_clients[url],
+                RequestType.QUERY_PREFETCH_STATUS,
+                [request_id],
+            )
+            for url in unresolved_urls
+        }
+
+        for url, fut in futures.items():
+            try:
+                r = fut.result(timeout=self._mq_timeout)
+            except TimeoutError:
+                logger.warning(
+                    "QUERY_PREFETCH_STATUS to %s timed out. Marking unhealthy.",
+                    url,
+                )
+                self._health_events[url].clear()
+                return 0
+            if r is None:
+                continue
+            per_server[url] = int(r)
+
+        if len(per_server) < len(self._server_urls):
+            return None
+
+        min_chunks = min(per_server.values())
+        max_chunks = max(per_server.values())
+        if min_chunks != max_chunks:
+            logger.warning(
+                "[req=%s] LMCache hit mismatch across servers: %s → take min=%d",
+                request_id,
+                dict(per_server),
+                min_chunks,
+            )
+            self._free_inconsistent_lookup_locks(request_id, per_server, min_chunks)
+
+        token_count = min_chunks * self.lmcache_tokens_per_chunk
+
+        self._finished_lookup_results[request_id] = token_count
+        return token_count
+
+    def num_blocks_per_chunk(self) -> int:
+        """
+        Returns:
+            The number of vllm blocks in a LMCache data chunk
+        """
+        return self.blocks_in_chunk
+
+    def cleanup_lookup_result(self, request_id: str) -> None:
+        """
+        Clean up lookup state for a finished request to prevent memory leak.
+        Args:
+            request_id: The ID of the finished request.
+        """
+        self._pending_lookups.discard(request_id)
+        self._finished_lookup_results.pop(request_id, None)
+        self._per_server_hits.pop(request_id, None)
+        self._lookup_params.pop(request_id, None)
+
+    def shutdown(self) -> None:
+        """Shutdown the scheduler adapter and its resources."""
+        for client in self.mq_clients.values():
+            client.close()
+        with self._heartbeat_lock:
+            for hb in self._heartbeats.values():
+                hb.stop()
+
+    def free_lookup_locks(
+        self,
+        token_ids: list[int],
+        start: int,
+        end: int,
+        request_id: str,
+        cache_salt: str = "",
+    ) -> None:
+        """Release read locks acquired during lookup without a full retrieve.
+
+        Use this when some chunks matched by lookup overlap with blocks that
+        vLLM has already computed, so they will never be retrieved.  Calling
+        this prevents those chunks from holding read locks until TTL expiry.
+
+        Or use this when a request is cancelled or aborted after lookup but
+        before retrieve to avoid holding read locks until TTL expiry.
+
+        When ``start`` or ``end`` is not aligned to the chunk size, the
+        entire chunk containing start boundary is freed but not end boundary.
+        It is caller's responsibility to properly align the boundaries.
+
+        Args:
+            token_ids: Token IDs for the key (same as used in lookup).
+            start: Start token index.
+            end: End token index.
+            request_id: The request ID.
+            cache_salt: Per-user isolation salt.
+        """
+        if not self.is_healthy:
+            return
+
+        # Free [start, end) on every server.
+        base_key = self._create_key(
+            token_ids,
+            start=start,
+            end=end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        ).no_worker_id_version()
+        for url in self._server_urls:
+            send_lmcache_request(
+                self.mq_clients[url],
+                RequestType.FREE_LOOKUP_LOCKS,
+                [base_key, self.tp_size],
+            )
+
+    def end_session(self, request_id: str) -> None:
+        """
+        Notify LMCache server to remove the session for a finished request.
+        Args:
+            request_id: The ID of the finished request.
+        """
+        if not self.is_healthy:
+            return
+
+        for url in self._server_urls:
+            send_lmcache_request(
+                self.mq_clients[url],
+                RequestType.END_SESSION,
+                [request_id],
+            )
+
+    def report_block_allocations(
+        self,
+        records: list[BlockAllocationRecord],
+    ) -> None:
+        """Report vLLM GPU block allocation deltas to LMCache server.
+
+        Fire-and-forget: does not wait for a response. If the server
+        is unhealthy the report is silently dropped.
+
+        Args:
+            records: List of BlockAllocationRecord with per-request
+                block and token allocation deltas.
+        """
+        if not self.is_healthy or not records:
+            return
+
+        for url in self._server_urls:
+            send_lmcache_request(
+                self.mq_clients[url],
+                RequestType.REPORT_BLOCK_ALLOCATION,
+                [os.getpid(), self.model_name, records],
+            )
+
+    # Helper functions
+    def _create_key(
+        self,
+        token_ids: list[int],
+        start: int,
+        end: int,
+        request_id: str,
+        cache_salt: str = "",
+    ) -> IPCCacheServerKey:
+        """Convert token IDs to an IPC cache engine key.
+
+        Args:
+            token_ids: The token IDs.
+            start: Start token index.
+            end: End token index.
+            request_id: The request ID.
+            cache_salt: Per-user isolation salt.
+
+        Returns:
+            IPCCacheServerKey: The constructed key.
+        """
+        # NOTE: for the scheduler adapter, we don't have a worker id,
+        # so we set it to None in the key.
+        return IPCCacheServerKey(
+            model_name=self.model_name,
+            world_size=self.world_size,
+            worker_id=None,
+            token_ids=tuple(token_ids),
+            start=start,
+            end=end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        )
+
+
+class LMCacheMPWorkerAdapter:
+    def __init__(
+        self,
+        server_url: str,
+        context: zmq.Context,
+        model_name: str,
+        vllm_block_size: int,
+        parallel_strategy: ParallelStrategy | int,
+        legacy_block_size: int | None = None,
+        *,
+        mq_timeout: float = DEFAULT_MQ_TIMEOUT,
+        heartbeat_interval: float = DEFAULT_HEARTBEAT_INTERVAL,
+        extra_config: dict[str, Any] | None = None,
+    ):
+        """Initialize the worker adapter for current or legacy vLLM callers.
+
+        Args:
+            server_url: The server URL for the LMCache message queue.
+            context: The ZMQ context.
+            model_name: The model name used for LMCache keys.
+            vllm_block_size: The block size used in vLLM, or legacy KV world
+                size when ``parallel_strategy`` is an int.
+            parallel_strategy: Current ``ParallelStrategy`` metadata, or the
+                legacy KV worker id from older vLLM connectors.
+            legacy_block_size: The vLLM block size passed positionally by
+                older vLLM connectors.
+            mq_timeout: Timeout in seconds for message queue requests.
+                Ignored when ``extra_config`` is provided.
+            heartbeat_interval: Interval in seconds between heartbeat pings.
+                Ignored when ``extra_config`` is provided.
+            extra_config: Optional dict with keys starting with
+                ``lmcache.mp.`` (e.g., ``lmcache.mp.mq_timeout``). When
+                provided, it overrides ``mq_timeout`` / ``heartbeat_interval``.
+
+        Raises:
+            TypeError: If the connector argument shape is unsupported.
+        """
+        vllm_block_size, parallel_strategy, mq_timeout = _normalize_adapter_init_args(
+            vllm_block_size,
+            parallel_strategy,
+            legacy_block_size,
+            mq_timeout,
+        )
+        if extra_config is not None:
+            cfg = _resolve_extra_config(extra_config)
+            mq_timeout = cfg[ExtraConfigDefault.mq_timeout.name]
+            heartbeat_interval = cfg[ExtraConfigDefault.heartbeat_interval.name]
+            # Only treat ``mp_transfer_mode`` as an explicit override when
+            # the user actually set it in extra_config; otherwise leave it
+            # as ``None`` so ``create_transfer_context`` can still consult
+            # the ``LMCACHE_MP_TRANSFER_MODE`` env var.
+            mp_mode_key = (
+                _EXTRA_CONFIG_KEY_PREFIX + ExtraConfigDefault.mp_transfer_mode.name
+            )
+            if mp_mode_key in extra_config:
+                self._mp_transfer_mode = cfg[ExtraConfigDefault.mp_transfer_mode.name]
+            else:
+                self._mp_transfer_mode = None
+        else:
+            self._mp_transfer_mode = None
+        self.mq_client = MessageQueueClient(server_url, context)
+        self._mq_timeout = mq_timeout
+
+        # Instance id for GPU worker. uuid4-derived (OS entropy) rather
+        # than os.getpid() to avoid collision in containerized deployments.
+        # Masked to 63 bits to stay signed-int64-safe for any msgpack peer.
+        self.instance_id: int = uuid.uuid4().int & ((1 << 63) - 1)
+        logger.info(
+            "LMCache MP worker adapter created with instance_id=%d",
+            self.instance_id,
+        )
+
+        # Registered kv caches from vLLM
+        self.kv_caches: dict[str, torch.Tensor] = {}
+        self.engine_group_infos: list[EngineGroupInfo] = []
+
+        # Transport context for transfer operations.
+        self.transfer_ctx: TransferContext | None = None
+
+        # Request futures
+        self.store_futures: dict[str, MessagingFuture[StoreResult]] = {}
+        # request_id -> (future, block_ids)
+        self.retrieve_futures: dict[
+            str, tuple[MessagingFuture[RetrieveResult], list[int]]
+        ] = {}
+        # The IPC handle is not enough by itself; CUDA needs the exporting
+        # event object to stay alive until the consumer is done with it.
+        self.store_events: dict[str, _IpcEvent] = {}
+        self.retrieve_events: dict[str, _IpcEvent] = {}
+
+        # Block IDs that failed due to retrieve timeout
+        self.error_block_ids: set[int] = set()
+
+        # Retrieve request ids dropped by the unhealthy early-return of
+        # submit_retrieve_request. get_finished must still report each id
+        # exactly once, or async loads hang in WAITING_FOR_REMOTE_KVS.
+        self._dropped_retrieves: set[str] = set()
+
+        # The store requests that have finished execution in LMCache
+        self.finished_stores: set[str] = set()
+        # The finished request ids that are passed via vLLM and also
+        # have corresponding store requests submitted to LMCache before
+        self.previously_finished: set[str] = set()
+        # Request IDs already returned as finished_sending to the scheduler.
+        # Prevents re-reporting the same ID after drain clears tracking sets.
+        self._returned_finished: set[str] = set()
+
+        self.model_name = model_name
+        self.parallel_strategy = parallel_strategy
+
+        # Read chunk size from lmcache
+        try:
+            lmcache_tokens_per_chunk = get_lmcache_chunk_size(
+                self.mq_client, timeout=self._mq_timeout
+            )
+        except TimeoutError:
+            self.mq_client.close()
+            _raise_server_unreachable(server_url, self._mq_timeout)
+        self.lmcache_tokens_per_chunk = lmcache_tokens_per_chunk
+        assert lmcache_tokens_per_chunk % vllm_block_size == 0, (
+            "LMCache chunk size should be a multiple of vLLM block size"
+        )
+        self.blocks_in_chunk = lmcache_tokens_per_chunk // vllm_block_size
+
+        # Health state (shared with heartbeat thread)
+        self._health_event = threading.Event()
+        self._health_event.set()
+
+        # Heartbeat thread is created but NOT started yet.
+        # It will be lazily started on the first store or retrieve
+        # request, by which time vLLM is fully ready (model loaded,
+        # KV caches allocated, warmup & CUDA graph capture done).
+        self._heartbeat_interval = heartbeat_interval
+        self._heartbeat: HeartbeatThread | None = None
+        self._heartbeat_lock = threading.Lock()
+        if 3 * heartbeat_interval > _SERVER_REAP_TIMEOUT_FLOOR_SECONDS:
+            logger.warning(
+                "lmcache.mp.heartbeat_interval is %.1fs, so 3 x "
+                "heartbeat_interval (%.1fs) exceeds the MP server's "
+                "default worker reap timeout floor (%.1fs). Raise the "
+                "server's worker reap timeout to at least 3 x the "
+                "heartbeat interval, or the server may reap this "
+                "worker between heartbeats.",
+                heartbeat_interval,
+                3 * heartbeat_interval,
+                _SERVER_REAP_TIMEOUT_FLOOR_SECONDS,
+            )
+
+        # request telemetry, used for prefill-decode disagg
+        # TODO: pass down the configuration via vLLM connector config
+        # instead of env var
+        self.request_telemetry = RequestTelemetryFactory.create(
+            telemetry_type=os.getenv("LMCACHE_REQUEST_TELEMETRY_TYPE", "noop"),
+            config={
+                "endpoint": os.getenv(
+                    "LMCACHE_REQUEST_TELEMETRY_ENDPOINT",
+                    "http://localhost:5768/api/v1/telemetry",
+                ),
+            },
+        )
+
+    @property
+    def is_healthy(self) -> bool:
+        """Whether the LMCache server is healthy.
+
+        Reflects the most recent heartbeat result. KV cache
+        re-registration on the unhealthy->healthy transition is handled
+        by the heartbeat thread itself via ``register_recover_callback``,
+        so this property only reads the shared event.
+        """
+        return self._health_event.is_set()
+
+    @property
+    def world_size(self) -> int:
+        """Get the kv world size."""
+        return self.parallel_strategy.kv_world_size
+
+    @property
+    def worker_id(self) -> int:
+        """Get the kv worker id."""
+        return self.parallel_strategy.kv_worker_id
+
+    @property
+    def is_kv_writer(self) -> bool:
+        """Whether this worker is responsible for storing KV."""
+        return self.parallel_strategy.is_kv_writer
+
+    def register_kv_caches(
+        self,
+        kv_caches: dict[str, torch.Tensor],
+        engine_group_infos: Sequence[EngineGroupInfo] = (),
+    ) -> None:
+        """
+        Register the kv caches with LMCache server.
+
+        Args:
+            kv_caches: A dict of kv caches to register. The keys are the
+                layer names and the values are the corresponding tensors.
+            engine_group_infos: LMCache-owned engine KV cache group metadata.
+
+        Raises:
+            ConnectionError: if the server does not respond within
+                mq_timeout.
+            ValueError: if the LMCache chunk size is not a multiple of an
+                engine group's ``tokens_per_block`` (chunk boundaries would
+                not align with that group's paged-chunk boundaries).
+        """
+        logger.info("Registering kv caches")
+        for info in engine_group_infos:
+            if (
+                info.tokens_per_block > 0
+                and self.lmcache_tokens_per_chunk % info.tokens_per_block
+            ):
+                raise ValueError(
+                    f"LMCache chunk size {self.lmcache_tokens_per_chunk} must be a "
+                    f"multiple of engine group {info.engine_group_id} "
+                    f"tokens_per_block {info.tokens_per_block}"
+                )
+        self.kv_caches = kv_caches
+        self.engine_group_infos = list(engine_group_infos)
+        self._send_register_kv_caches_request(kv_caches)
+
+    def _block_ids_per_group(self, op: LoadStoreOp) -> list[list[int]]:
+        return expand_engine_block_ids(self.engine_group_infos, op.block_ids)
+
+    def _send_register_kv_caches_request(
+        self,
+        kv_caches: dict[str, torch.Tensor],
+    ) -> None:
+        """Submit a REGISTER_KV_CACHE request and wait for the response.
+
+        Shared by the public ``register_kv_caches`` entry point and the
+        heartbeat recovery path (``_reregister_kv_caches_callback``).
+
+        Args:
+            kv_caches: The KV cache dict to register.
+
+        Raises:
+            ConnectionError: if the server does not respond within
+                mq_timeout.
+        """
+        self.kv_caches = kv_caches
+        transfer_ctx = create_transfer_context(kv_caches, mode=self._mp_transfer_mode)
+        layout_hints = vllm_layout_hints()
+        self.transfer_ctx = transfer_ctx
+        try:
+            # Register on the local, not self.transfer_ctx: a concurrent
+            # shutdown() may null self.transfer_ctx between publish and this
+            # call. The local is always non-None.
+            transfer_ctx.register(
+                self.instance_id,
+                kv_caches,
+                self.model_name,
+                self.world_size,
+                self.blocks_in_chunk,
+                self.mq_client,
+                self._mq_timeout,
+                send_request=send_lmcache_request,
+                layout_hints=layout_hints,
+                engine_group_infos=self.engine_group_infos,
+            )
+        except TimeoutError:
+            raise ConnectionError(
+                "LMCache server did not respond to "
+                "register_kv_caches within "
+                f"{self._mq_timeout}s. Is the server running?"
+            ) from None
+
+    def _ensure_heartbeat_started(self) -> None:
+        """Lazily start the heartbeat thread on first store/retrieve.
+
+        The heartbeat starts healthy (the event was set at construction). A
+        live worker pings every interval, refreshing its server-side
+        ``last_seen``, so it is never reaped while alive -- no re-registration
+        is needed at startup, and the first store/retrieve is not gated. The
+        recover callback still re-registers on a genuine unhealthy->healthy
+        edge (server restart).
+        """
+        if self._heartbeat is not None:
+            return
+        with self._heartbeat_lock:
+            if self._heartbeat is not None:
+                return
+            heartbeat = HeartbeatThread(
+                mq_client=self.mq_client,
+                health_event=self._health_event,
+                interval=self._heartbeat_interval,
+                instance_id=self.instance_id,
+            )
+            heartbeat.register_recover_callback(self._reregister_kv_caches_callback)
+            heartbeat.start()
+            self._heartbeat = heartbeat
+
+    def _heartbeat_stop_requested(self) -> bool:
+        """Whether a created heartbeat thread has a stop requested.
+
+        Returns:
+            ``True`` only if a heartbeat exists and its stop was requested.
+        """
+        heartbeat = self._heartbeat
+        return heartbeat is not None and heartbeat.stop_requested
+
+    def _reregister_kv_caches_callback(self) -> bool:
+        """Heartbeat recover callback: re-register KV caches after the
+        server returns. Runs on the heartbeat thread, before the health
+        event is set.
+
+        Returns:
+            ``True`` if nothing needs re-registering or registration
+            succeeds; ``False`` on failure or a requested heartbeat stop
+            (event stays cleared; retried on the next successful PING).
+        """
+        if not self.kv_caches:
+            # Nothing was registered yet (server flapped before the
+            # very first register_kv_caches). Treat as success so the
+            # health event can be set.
+            return True
+
+        # Skip the rebuild if a shutdown already requested the heartbeat stop.
+        if self._heartbeat_stop_requested():
+            logger.info("Heartbeat stop requested; skipping KV cache re-registration")
+            return False
+
+        try:
+            self._send_register_kv_caches_request(self.kv_caches)
+        except ConnectionError:
+            logger.exception(
+                "Failed to re-register KV caches after server recovery; "
+                "will retry on next heartbeat"
+            )
+            return False
+        except Exception:
+            logger.exception(
+                "Unexpected error during KV cache re-registration; "
+                "will retry on next heartbeat"
+            )
+            return False
+        logger.warning("Finished re-registering KV caches after server recovery")
+        return True
+
+    @_lmcache_nvtx_annotate
+    def submit_store_request(
+        self,
+        request_id: str,
+        op: LoadStoreOp,
+        event: _IpcEvent,
+        cache_salt: str = "",
+    ):
+        """
+        Submit a KV cache store request to LMCache
+
+        Args:
+            request_id: The ID of the request
+            op: The LoadStoreOp describing the store operation.
+            event: The CUDA event that is recorded after the current
+                model inference step
+            cache_salt: Per-user isolation salt.
+        """
+        self._ensure_heartbeat_started()
+
+        if not self.is_kv_writer:
+            return
+
+        if not self.is_healthy:
+            return
+
+        assert op.token_ids is not None
+        key = self._create_key(
+            op.token_ids,
+            op.start,
+            op.end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        )
+        if self.transfer_ctx is None:
+            raise RuntimeError(
+                "Transfer context is not initialized. "
+                "Call register_kv_caches() before submitting store requests."
+            )
+        future = self.transfer_ctx.submit_store(
+            request_id,
+            key,
+            self.instance_id,
+            self.kv_caches,
+            self._block_ids_per_group(op),
+            event,
+            self.blocks_in_chunk,
+        )
+        self.store_futures[request_id] = future
+        self.store_events[request_id] = event
+
+    @_lmcache_nvtx_annotate
+    def submit_retrieve_request(
+        self,
+        request_id: str,
+        op: LoadStoreOp,
+        event: _IpcEvent,
+        cache_salt: str = "",
+    ) -> None:
+        """
+        Submit a KV cache retrieve request to LMCache
+
+        When the server is unhealthy the request is not submitted: blocks
+        are flagged via ``error_block_ids`` (vLLM recomputes) and the id is
+        recorded so ``get_finished`` still reports it exactly once.
+
+        Args:
+            request_id: The ID of the request
+            op: The LoadStoreOp describing the retrieve operation.
+            event: The CUDA event that is recorded after the current
+                model inference step
+            cache_salt: Per-user isolation salt.
+        """
+        self._ensure_heartbeat_started()
+
+        if not self.is_healthy:
+            self.error_block_ids.update(op.flat_block_ids)
+            self._dropped_retrieves.add(request_id)
+            return
+
+        assert op.token_ids is not None
+        key = self._create_key(
+            op.token_ids,
+            op.start,
+            op.end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        )
+        if self.transfer_ctx is None:
+            raise RuntimeError(
+                "Transfer context is not initialized. "
+                "Call register_kv_caches() before submitting retrieve requests."
+            )
+        future = self.transfer_ctx.submit_retrieve(
+            request_id,
+            key,
+            self.instance_id,
+            self.kv_caches,
+            self._block_ids_per_group(op),
+            event,
+            self.blocks_in_chunk,
+            skip_first_n_tokens=op.skip_first_n_tokens,
+        )
+        self.retrieve_futures[request_id] = (future, op.flat_block_ids)
+        self.retrieve_events[request_id] = event
+
+    @_lmcache_nvtx_annotate
+    def batched_submit_store_requests(
+        self,
+        request_ids: list[str],
+        ops: list[LoadStoreOp],
+        event: _IpcEvent,
+        cache_salts: list[str] | None = None,
+    ):
+        """
+        Submit a batched store request to LMCache
+
+        Args:
+            request_ids: The IDs of the requests
+            ops: The LoadStoreOps describing the store operations. Should have
+                the same length as request_ids
+            event: The CUDA event that is recorded after the current
+                model inference step
+            cache_salts: Per-user isolation salts, one per request. If None,
+                all requests use cache_salt="". The list length should be the same as
+                request_ids.
+        """
+        if cache_salts is None:
+            cache_salts = [""] * len(request_ids)
+        for request_id, op, salt in zip(request_ids, ops, cache_salts, strict=False):
+            self.submit_store_request(request_id, op, event, cache_salt=salt)
+
+    @_lmcache_nvtx_annotate
+    def batched_submit_retrieve_requests(
+        self,
+        request_ids: list[str],
+        ops: list[LoadStoreOp],
+        event: _IpcEvent,
+        cache_salts: list[str] | None = None,
+    ):
+        """
+        Submit a batched retrieve request to LMCache
+
+        Args:
+            request_ids: The IDs of the requests
+            ops: The LoadStoreOps describing the retrieve operations. Should have
+                the same length as request_ids
+            event: The CUDA event that is recorded after the current
+                model inference step
+            cache_salts: Per-user isolation salts, one per request. If None,
+                all requests use cache_salt="". The list length should be same as
+                request_ids.
+        """
+        if cache_salts is None:
+            cache_salts = [""] * len(request_ids)
+        for request_id, op, salt in zip(request_ids, ops, cache_salts, strict=False):
+            self.submit_retrieve_request(request_id, op, event, cache_salt=salt)
+
+    def _process_finished_stores(
+        self,
+        finished_req_ids_from_lmcache: set[str],
+        finished_req_ids_from_engine: set[str],
+    ) -> set[str]:
+        """Merge LMCache-side and engine-side finished store info."""
+        self.finished_stores.update(finished_req_ids_from_lmcache)
+        ret_stores = set()
+        for req_id in finished_req_ids_from_engine:
+            if req_id in self._returned_finished:
+                continue
+            if req_id in self.finished_stores or req_id in self.store_futures:
+                self.previously_finished.add(req_id)
+            else:
+                ret_stores.add(req_id)
+        ret_stores.update(self._update_and_get_finished_store())
+        self._returned_finished.update(ret_stores)
+        return ret_stores
+
+    @_lmcache_nvtx_annotate
+    def get_finished(
+        self, finished_req_ids_from_engine: set[str]
+    ) -> tuple[set[str] | None, set[str] | None]:
+        """
+        Check and get the finished store and retrieve requests.
+
+        Args:
+            finished_req_ids_from_engine: the set of request ids that are
+                reported as finished from the vLLM engine side.
+
+        Returns:
+            A tuple of two sets:
+            - The first set contains the finished store request ids. The returned
+                store request ids MUST be seen before in the
+                `finished_req_ids_from_engine`.
+            - The second set contains the finished retrieve request ids,
+                including retrieves dropped at submit time while unhealthy
+                (reported exactly once; blocks already in error_block_ids).
+
+        Notes:
+            When enabling async scheduling in vLLM, the same request ID may appear
+            multiple times in `finished_req_ids_from_engine`. The adapter should
+            take care of deduplicating the request IDs and only return the request
+            IDs that have not been returned before.
+        """
+        # If unhealthy, drain all pending futures immediately
+        if not self.is_healthy:
+            finished_stores = set(self.store_futures.keys())
+            finished_retrieves = set()
+            for request_id, (
+                _r_future,
+                r_block_ids,
+            ) in self.retrieve_futures.items():
+                finished_retrieves.add(request_id)
+                self.error_block_ids.update(r_block_ids)
+            self.store_futures.clear()
+            self.retrieve_futures.clear()
+            self.store_events.clear()
+            self.retrieve_events.clear()
+
+            # Retrieves dropped at submit time still must be reported,
+            # exactly once, or async loads hang in WAITING_FOR_REMOTE_KVS.
+            # Swap-drain (not update-then-clear): a concurrent
+            # submit_retrieve_request add lands in the old set (reported now)
+            # or the fresh set (reported next call), never lost.
+            dropped = self._dropped_retrieves
+            self._dropped_retrieves = set()
+            finished_retrieves.update(dropped)
+
+            ret_stores = self._process_finished_stores(
+                finished_stores, finished_req_ids_from_engine
+            )
+            # A request may have a pending retrieve AND appear in
+            # finished_req_ids_from_engine (it ran without loading KV after
+            # the server died).  The scheduler processes finished_recving
+            # first and deletes the request, so we must not also report it
+            # in finished_sending.
+            ret_stores -= finished_retrieves
+            return ret_stores, finished_retrieves
+
+        finished_stores = set()
+        finished_retrieves = set()
+        for request_id, s_future in self.store_futures.items():
+            if not s_future.query():
+                continue
+
+            s_result = s_future.result()
+            finished_stores.add(request_id)
+
+            if not s_result:
+                logger.error(
+                    "Something went wrong when processing the "
+                    "store request for request_id=%s",
+                    request_id,
+                )
+
+        for request_id, (r_future, _) in self.retrieve_futures.items():
+            if not r_future.query():
+                continue
+
+            r_result = r_future.result()
+            finished_retrieves.add(request_id)
+
+            if not r_result:
+                logger.error(
+                    "Something went wrong when processing the "
+                    "retrieve request for request_id=%s, result=%s",
+                    request_id,
+                    r_result,
+                )
+
+        # Remove the finished requests from the tracking dicts
+        for request_id in finished_stores:
+            self.store_futures.pop(request_id, None)
+            self.store_events.pop(request_id, None)
+        for request_id in finished_retrieves:
+            self.retrieve_futures.pop(request_id, None)
+            self.retrieve_events.pop(request_id, None)
+
+        # Retrieves dropped while unhealthy still must be reported,
+        # exactly once, or async loads hang in WAITING_FOR_REMOTE_KVS. No
+        # finished_sending dedup is needed (unlike the unhealthy branch): a
+        # dropped retrieve's request is parked in WAITING_FOR_REMOTE_KVS until
+        # this report, so it cannot also be engine-finished in the same call.
+        # Swap-drain so a concurrent submit_retrieve_request add is never lost.
+        dropped = self._dropped_retrieves
+        self._dropped_retrieves = set()
+        finished_retrieves.update(dropped)
+
+        # Update the internal states
+        ret_stores = self._process_finished_stores(
+            finished_stores, finished_req_ids_from_engine
+        )
+
+        # the invocation of `get_finished` means that
+        # these requests' KV caches are already fully stored.
+        # or the requests normally ends without any store.
+        if ret_stores:
+            self.request_telemetry.on_request_store_finished(
+                request_ids_set=ret_stores,
+                model_name=self.model_name,
+                world_size=self.world_size,
+                kv_rank=self.worker_id,
+            )
+
+        return ret_stores, finished_retrieves
+
+    def num_blocks_per_chunk(self) -> int:
+        """
+        Returns:
+            The number of vllm blocks in a LMCache data chunk
+        """
+        return self.blocks_in_chunk
+
+    def get_block_ids_with_load_errors(self) -> set[int]:
+        """
+        Returns the block IDs that failed due to retrieve timeout,
+        then clears the internal set.
+        """
+        errors = self.error_block_ids.copy()
+        self.error_block_ids.clear()
+        return errors
+
+    def handle_preemptions(self, need_flush_before_forward: bool) -> None:
+        """Handle worker-side preemption hints from connector metadata.
+
+        When ``need_flush_before_forward`` is true, synchronize deferred
+        engine-driven gather work before the next forward pass can overwrite
+        paged KV blocks.
+
+        Args:
+            need_flush_before_forward: When True, flush in-flight gather
+                operations on the transfer context. When False, this is a no-op.
+        """
+        if not need_flush_before_forward:
+            return
+        if not self.is_healthy or self.transfer_ctx is None:
+            return
+        self.transfer_ctx.flush_inflight_stores()
+        # Force device sync here, compare to preemption, perf panelty is trivial
+        torch_dev.synchronize()
+
+    def shutdown(self) -> None:
+        """
+        Shutdown the LMCache MP worker adapter.
+
+        Stops the heartbeat (if started) before UNREGISTER: no new ping
+        on the closing mq_client, and a straggler in-flight cycle cannot
+        re-register or flip the health event after unregistration.
+        """
+        with self._heartbeat_lock:
+            if self._heartbeat is not None:
+                self._heartbeat.stop()
+
+        logger.info("Unregistering kv caches")
+        try:
+            unregister_type = (
+                RequestType.UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT
+                if isinstance(self.transfer_ctx, EngineDrivenTransferContext)
+                else RequestType.UNREGISTER_KV_CACHE
+            )
+            send_lmcache_request(
+                self.mq_client,
+                unregister_type,
+                [self.instance_id],
+            ).result(timeout=self._mq_timeout)
+        except TimeoutError:
+            logger.warning(
+                "LMCache server did not respond to unregister within %ss. "
+                "Proceeding with shutdown.",
+                self._mq_timeout,
+            )
+
+        if self.transfer_ctx is not None:
+            self.transfer_ctx.close()
+            self.transfer_ctx = None
+
+        self.mq_client.close()
+        self.request_telemetry.close()
+
+    # Helper functions
+    def _update_and_get_finished_store(
+        self,
+    ) -> set[str]:
+        """Converge the internal states about finished stores
+        and returns the 'safe finished store request ids' back
+        """
+        safe_finished_s = self.finished_stores.intersection(self.previously_finished)
+        self.finished_stores.difference_update(self.previously_finished)
+        self.previously_finished.difference_update(safe_finished_s)
+
+        return safe_finished_s
+
+    def _create_key(
+        self,
+        token_ids: list[int],
+        start: int,
+        end: int,
+        request_id: str,
+        cache_salt: str = "",
+    ) -> IPCCacheServerKey:
+        """Convert token IDs to an IPC cache engine key.
+
+        Args:
+            token_ids: The token IDs.
+            start: Start token index.
+            end: End token index.
+            request_id: The request ID.
+            cache_salt: Per-user isolation salt.
+
+        Returns:
+            IPCCacheServerKey: The constructed key.
+        """
+        return IPCCacheServerKey(
+            model_name=self.model_name,
+            world_size=self.world_size,
+            worker_id=self.worker_id,
+            token_ids=tuple(token_ids),
+            start=start,
+            end=end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        )
diff --git a/lmcache/integration/vllm/vllm_service_factory.py b/lmcache/integration/vllm/vllm_service_factory.py
new file mode 100644
index 0000000..8ca487f
--- /dev/null
+++ b/lmcache/integration/vllm/vllm_service_factory.py
@@ -0,0 +1,339 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+VllmServiceFactory: Creates LMCache service components for vLLM integration.
+
+This factory encapsulates all vLLM-specific component creation logic,
+keeping the LMCacheManager agnostic to the serving engine.
+"""
+
+# Standard
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Optional, Union
+
+if TYPE_CHECKING:
+    # Third Party
+    from vllm.config import VllmConfig
+
+    # First Party
+    from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+        LMCacheAsyncLookupServer,
+    )
+    from lmcache.v1.lookup_client.lmcache_lookup_client import LMCacheLookupServer
+    from lmcache.v1.manager import LMCacheManager
+
+# First Party
+from lmcache.integration.base_service_factory import BaseServiceFactory
+from lmcache.logging import init_logger
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.health_monitor.base import HealthMonitor
+from lmcache.v1.internal_api_server.api_server import InternalAPIServer
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.offload_server.zmq_server import ZMQOffloadServer
+from lmcache.v1.plugin.runtime_plugin_launcher import RuntimePluginLauncher
+
+logger = init_logger(__name__)
+
+
+class VllmServiceFactory(BaseServiceFactory):
+    """Creates LMCache service components for vLLM integration.
+
+    Handles role-based component creation:
+    - scheduler: lookup client, PrometheusLogger (no engine if bypass disabled)
+    - worker: engine, lookup server, offload server
+    - DP rank 0: API server, plugin launcher
+    - all roles: health monitor (created during post_init)
+    """
+
+    def __init__(
+        self,
+        lmcache_config: LMCacheEngineConfig,
+        vllm_config: "VllmConfig",
+        role: str,
+    ):
+        self.lmcache_config = lmcache_config
+        self.vllm_config = vllm_config
+        self.role = role
+        self.metadata: Optional[LMCacheMetadata] = None
+        self.lmcache_engine: Optional[LMCacheEngine] = None
+
+    def get_engine_instance_id(self) -> str:
+        # First Party
+        from lmcache.integration.vllm.utils import ENGINE_NAME
+
+        return ENGINE_NAME
+
+    def get_or_create_metadata(self) -> Optional[LMCacheMetadata]:
+        if self.metadata is not None:
+            return self.metadata
+
+        # First Party
+        from lmcache.integration.vllm.utils import (
+            calculate_draft_layers,
+            calculate_local_rank_and_world_size,
+            mla_enabled,
+            validate_mla_config,
+        )
+
+        try:
+            # Third Party
+            from vllm.utils.torch_utils import get_kv_cache_torch_dtype
+        except ImportError:
+            # Third Party
+            from vllm.utils import get_kv_cache_torch_dtype
+
+        model_config = self.vllm_config.model_config
+        parallel_config = self.vllm_config.parallel_config
+        cache_config = self.vllm_config.cache_config
+
+        kv_dtype = get_kv_cache_torch_dtype(
+            cache_config.cache_dtype, model_config.dtype
+        )
+
+        use_mla = mla_enabled(model_config)
+        validate_mla_config(self.lmcache_config, use_mla)
+
+        num_layer = model_config.get_num_layers(parallel_config)
+        num_draft_layers = calculate_draft_layers(self.vllm_config)
+        num_layer += num_draft_layers
+        chunk_size = self.lmcache_config.chunk_size
+        num_kv_head = model_config.get_num_kv_heads(parallel_config)
+        head_size = model_config.get_head_size()
+        kv_shape = (
+            num_layer,
+            1 if use_mla else 2,
+            chunk_size,
+            num_kv_head,
+            head_size,
+        )
+
+        logger.info(
+            "num_layer: %d, chunk_size: %d, num_kv_head (per gpu): %d, "
+            "head_size: %d, hidden_dim (D) for KV (per gpu): %d, "
+            "use mla: %s, kv shape: %s, num_draft_layers: %d",
+            num_layer,
+            chunk_size,
+            num_kv_head,
+            head_size,
+            num_kv_head * head_size,
+            use_mla,
+            kv_shape,
+            num_draft_layers,
+        )
+
+        # Extract engine_id and kv_connector_extra_config from vllm_config
+        engine_id = None
+        kv_connector_extra_config = None
+        if hasattr(self.vllm_config, "kv_transfer_config"):
+            kv_transfer_config = self.vllm_config.kv_transfer_config
+            if kv_transfer_config is not None:
+                engine_id = getattr(kv_transfer_config, "engine_id", None)
+                kv_connector_extra_config = getattr(
+                    kv_transfer_config, "kv_connector_extra_config", None
+                )
+
+        if self.role == "scheduler":
+            # Avoid GPU probing for scheduler-only metadata path;
+            # scheduler may run on CPU-only control-plane nodes.
+            local_worker_id = parallel_config.rank
+            local_world_size = parallel_config.world_size
+        else:
+            local_worker_id, local_world_size = calculate_local_rank_and_world_size(
+                self.vllm_config
+            )
+        self.metadata = LMCacheMetadata(
+            model_name=model_config.model,
+            world_size=parallel_config.world_size,
+            local_world_size=local_world_size,
+            worker_id=parallel_config.rank,
+            local_worker_id=local_worker_id,
+            kv_dtype=kv_dtype,
+            kv_shape=kv_shape,
+            use_mla=use_mla,
+            role=self.role,
+            served_model_name=model_config.served_model_name,
+            chunk_size=self.lmcache_config.chunk_size,
+            engine_id=engine_id,
+            kv_connector_extra_config=kv_connector_extra_config,
+        )
+        return self.metadata
+
+    def get_or_create_lmcache_engine(self) -> Optional[LMCacheEngine]:
+        self._ensure_metadata()
+        assert self.metadata is not None
+
+        # Scheduler without bypass lookup does not need an engine
+        if (
+            self.role == "scheduler"
+            and not self.lmcache_config.enable_scheduler_bypass_lookup
+        ):
+            # Create PrometheusLogger for scheduler without engine
+            # First Party
+            from lmcache.observability import PrometheusLogger
+
+            PrometheusLogger.GetOrCreate(
+                self.metadata,
+                config=self.lmcache_config,
+            )
+            return None
+
+        # First Party
+        from lmcache.integration.vllm.utils import ENGINE_NAME
+        from lmcache.utils import EngineType
+        from lmcache.v1.gpu_connector import CreateGPUConnector
+
+        if curr_engine := LMCacheEngineBuilder.get(ENGINE_NAME):
+            self.lmcache_engine = curr_engine
+            return curr_engine
+
+        if self.role == "scheduler":
+            tpg = SimpleNamespace()
+            tpg.broadcast = lambda tensor, src: tensor
+            tpg.broadcast_object = lambda obj, src: obj
+            vllm_gpu_connector = None
+        else:
+            # Third Party
+            from vllm.distributed.parallel_state import get_tp_group
+
+            tpg = get_tp_group()
+            # First Party
+            from lmcache.integration.vllm.utils import vllm_layout_hints
+
+            vllm_gpu_connector = CreateGPUConnector(
+                self.lmcache_config,
+                self.metadata,
+                EngineType.VLLM,
+                layout_hints=vllm_layout_hints(),
+            )
+
+        engine = LMCacheEngineBuilder.get_or_create(
+            ENGINE_NAME,
+            self.lmcache_config,
+            self.metadata,
+            vllm_gpu_connector,
+            tpg.broadcast,
+            tpg.broadcast_object,
+        )
+        self.lmcache_engine = engine
+
+        if (
+            self.role == "scheduler"
+            and self.lmcache_config.enable_scheduler_bypass_lookup
+        ):
+            assert engine.save_only_first_rank or (
+                self.lmcache_config.get_extra_config_value(
+                    "remote_enable_mla_worker_id_as0", self.metadata.use_mla
+                )
+            ), (
+                "enable_scheduler_bypass_lookup is only supported with "
+                "save_only_first_rank or remote_enable_mla_worker_id_as0"
+            )
+
+        return engine
+
+    def _ensure_metadata(self):
+        if self.metadata is None:
+            self.get_or_create_metadata()
+
+    def _ensure_engine(self):
+        if self.lmcache_engine is None:
+            self.get_or_create_lmcache_engine()
+
+    def maybe_create_prometheus_logger(self):
+        # PrometheusLogger is created on-demand within other components
+        # (e.g., engine creation for scheduler, health monitor setup).
+        return None
+
+    def maybe_create_lookup_client(self) -> Optional[LookupClientInterface]:
+        # Only scheduler needs lookup client
+        if self.role != "scheduler":
+            return None
+
+        # First Party
+        from lmcache.v1.lookup_client.factory import LookupClientFactory
+
+        self._ensure_metadata()
+        assert self.metadata is not None
+        return LookupClientFactory.create_lookup_client(
+            self.lmcache_config,
+            self.metadata,
+            self.lmcache_engine,
+        )
+
+    def maybe_create_lookup_server(
+        self,
+    ) -> Optional[Union["LMCacheLookupServer", "LMCacheAsyncLookupServer"]]:
+        # Only worker needs lookup server
+        if self.role != "worker":
+            return None
+
+        # First Party
+        from lmcache.v1.lookup_client.factory import LookupClientFactory
+
+        self._ensure_metadata()
+        self._ensure_engine()
+        assert self.metadata is not None
+        assert self.lmcache_engine is not None
+        return LookupClientFactory.create_lookup_server(
+            self.lmcache_engine,
+            self.metadata,
+        )
+
+    def maybe_create_offload_server(self) -> Optional[ZMQOffloadServer]:
+        # Only worker needs offload server
+        if self.role != "worker":
+            return None
+
+        # Third Party
+        from vllm.distributed.parallel_state import (
+            get_tensor_model_parallel_rank,
+        )
+
+        self._ensure_engine()
+        assert self.lmcache_engine is not None
+        return ZMQOffloadServer(
+            self.lmcache_engine,
+            get_tensor_model_parallel_rank(),
+        )
+
+    def maybe_create_runtime_plugin_launcher(
+        self,
+    ) -> Optional[RuntimePluginLauncher]:
+        # First Party
+        from lmcache.integration.vllm.utils import is_dp_rank0
+
+        # Only DP rank 0 needs runtime plugin launcher
+        if not is_dp_rank0(self.vllm_config):
+            return None
+
+        worker_id = (
+            -1
+            if self.lmcache_engine is None or self.metadata is None
+            else self.metadata.worker_id
+        )
+        return RuntimePluginLauncher(
+            self.lmcache_config,
+            self.role,
+            self.vllm_config.parallel_config.tensor_parallel_size,
+            worker_id,
+        )
+
+    def maybe_create_internal_api_server(
+        self, lmcache_manager: "LMCacheManager"
+    ) -> Optional[InternalAPIServer]:
+        # First Party
+        from lmcache.integration.vllm.utils import is_dp_rank0
+
+        # Only DP rank 0 needs internal API server
+        if not is_dp_rank0(self.vllm_config):
+            return None
+
+        return InternalAPIServer(lmcache_manager)
+
+    def maybe_create_health_monitor(
+        self, lmcache_manager: "LMCacheManager"
+    ) -> Optional[HealthMonitor]:
+        return self._create_health_monitor(
+            lmcache_manager, self.lmcache_config, self.lmcache_engine
+        )
diff --git a/lmcache/integration/vllm/vllm_v1_adapter.py b/lmcache/integration/vllm/vllm_v1_adapter.py
new file mode 100644
index 0000000..985ef9a
--- /dev/null
+++ b/lmcache/integration/vllm/vllm_v1_adapter.py
@@ -0,0 +1,1942 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generator, Optional, Union
+import math
+import os
+import sys
+
+# Third Party
+from vllm.config import (
+    VllmConfig,
+)
+from vllm.distributed.kv_transfer.kv_connector.v1.base import (
+    KVConnectorBase_V1,
+    KVConnectorMetadata,
+    KVConnectorRole,
+)
+from vllm.distributed.parallel_state import (
+    get_pp_group,
+)
+from vllm.sampling_params import SamplingParams
+from vllm.v1.core.sched.output import SchedulerOutput
+from vllm.v1.request import RequestStatus
+from vllm.version import __version__ as VLLM_VERSION
+import torch
+
+# First Party
+# Use LMCache's own math utilities instead of vllm's
+# (avoids dependency on vllm internal changes like https://github.com/vllm-project/vllm/pull/27188)
+from lmcache import utils
+from lmcache.banner import print_banner_once
+from lmcache.integration.vllm.utils import (
+    ENGINE_NAME,
+    apply_mm_hashes_to_token_ids,
+    extract_mm_features,
+    lmcache_get_or_create_config,
+)
+from lmcache.integration.vllm.vllm_service_factory import VllmServiceFactory
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor, PrometheusLogger
+from lmcache.utils import CacheStoreEvent, _lmcache_nvtx_annotate, cdiv
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.compute.blend import LMCBlenderBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.config_base import validate_and_set_config_value
+from lmcache.v1.manager import LMCacheManager
+
+if TYPE_CHECKING:
+    # Third Party
+    from vllm.attention.backends.abstract import AttentionMetadata
+    from vllm.forward_context import ForwardContext
+    from vllm.multimodal.inputs import PlaceholderRange
+    from vllm.v1.core.kv_cache_manager import KVCacheManager
+    from vllm.v1.core.sched.output import NewRequestData
+    from vllm.v1.request import Request
+
+    # First Party
+    from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class LoadSpec:
+    # Number of tokens cached in vLLM
+    vllm_cached_tokens: int
+    # Number of tokens that are cached in LMCache
+    lmcache_cached_tokens: int
+    # Whether the scheduler allow us to load the tokens
+    can_load: bool
+
+
+@dataclass
+class SaveSpec:
+    # Skip already saved tokens
+    skip_leading_tokens: int
+    # Whether the scheduler allow us to save the tokens
+    can_save: bool
+
+
+@dataclass
+class DisaggSpec:
+    req_id: str
+    receiver_id: str
+    receiver_host: str
+    receiver_init_port: int
+    receiver_alloc_port: int
+    is_last_prefill: bool = False
+    num_transferred_tokens: int = 0
+    total_chunks: int = 0
+    receiver_query_port: Optional[list[int]] = None
+
+
+tmp_disagg_tracker: dict[str, DisaggSpec] = {}
+
+
+def extract_request_configs(sampling_params: SamplingParams) -> Optional[dict]:
+    request_configs = None
+    if sampling_params and sampling_params.extra_args is not None:
+        if kv_transfer_params := sampling_params.extra_args.get("kv_transfer_params"):
+            for k, v in kv_transfer_params.items():
+                if k.startswith("lmcache."):
+                    if request_configs is None:
+                        request_configs = {}
+                    request_configs[k] = v
+    return request_configs
+
+
+@dataclass
+class RequestTracker:
+    # Request id
+    req_id: str
+
+    # Total prompt token length
+    prompt_len: int
+
+    # The token ids that has been scheduled so far
+    token_ids: list[int]
+
+    # The block ids that has been allocated so far
+    # NOTE: allocated blocks could be more than the number of tokens
+    allocated_block_ids: list[int]
+
+    # The number of tokens that has been saved
+    num_saved_tokens: int = 0
+
+    # Disagg spec for the request
+    disagg_spec: Optional[DisaggSpec] = None
+
+    # Multimodal hashes and positions
+    mm_hashes: Optional[list[str]] = None
+    mm_positions: Optional[list["PlaceholderRange"]] = None
+
+    # The configs of the request, includes tags and other configs
+    request_configs: Optional[dict] = None
+
+    # Whether the request is in decode phase
+    is_decode_phase = False
+
+    # Whether the request cache should be saved
+    skip_save: bool = False
+
+    # The number of tokens that are cached in LMCache for this request
+    num_lmcache_cached_tokens: int = 0
+
+    @_lmcache_nvtx_annotate
+    @staticmethod
+    def from_new_request(
+        lmcache_config: LMCacheEngineConfig,
+        new_request: "NewRequestData",
+        num_tokens_to_compute: int,
+        lmcache_cached_tokens: int,
+        skip_save: bool,
+    ) -> "RequestTracker":
+        """Create the request tracker from a new request.
+
+        Args:
+            lmcache_config (LMCacheEngineConfig): the LMCache engine config.
+            new_request (NewRequestData): the new request data.
+            num_tokens_to_compute (int): the number of tokens that will
+                be 'computed', including the `num_computed_tokens` (vLLM's
+                local cache hit) and new tokens that will be scheduled.
+            lmcache_cached_tokens (int): the number of tokens that are
+                cached in LMCache.
+            request_priority (int): the priority of the request
+            skip_save (bool): whether the request cache should be saved
+        """
+        # vLLM 0.9.0 update: request.block_ids changed from list[int] to
+        # tuple[list[int]]
+        # Need to check the type of request.block_ids
+
+        unfolded_block_ids = []
+
+        if not isinstance(new_request.block_ids[0], list):
+            unfolded_block_ids = new_request.block_ids.copy()
+        else:
+            # According to the vLLM code
+            # (https://github.com/vllm-project/vllm/blob/main/vllm/v1/core/
+            # sched/scheduler.py#L943),
+            # only one KVCacheGroup is supported in connector for now.
+
+            # TODO: Please support multiple KVCacheGroup in connector.
+            # NOTE: Also, `update` method in RequestTracker should be
+            # updated accordingly.
+            unfolded_block_ids = new_request.block_ids[0].copy()
+
+        # NOTE: Initialized in `update_state_after_alloc`
+        disagg_spec = tmp_disagg_tracker.pop(new_request.req_id, None)
+
+        request_configs = extract_request_configs(new_request.sampling_params)
+
+        mm_hashes, mm_positions = extract_mm_features(new_request, modify=True)
+
+        return RequestTracker(
+            req_id=new_request.req_id,
+            prompt_len=len(new_request.prompt_token_ids),
+            token_ids=new_request.prompt_token_ids[:num_tokens_to_compute].copy(),
+            allocated_block_ids=unfolded_block_ids,
+            num_saved_tokens=lmcache_cached_tokens,
+            disagg_spec=disagg_spec,
+            mm_hashes=mm_hashes,
+            mm_positions=mm_positions,
+            skip_save=skip_save,
+            request_configs=request_configs,
+            num_lmcache_cached_tokens=lmcache_cached_tokens,
+        )
+
+    def update(
+        self,
+        new_token_ids: list[int],
+        new_block_ids: Union[Optional[tuple[list[int], ...]], list[int]],
+        preempted: bool = False,
+        lmcache_cached_tokens: int = 0,
+        vllm_cached_tokens: int = 0,
+        all_token_ids: Optional[list[int]] = None,
+    ) -> None:
+        """Update the request tracker when a running request is
+        scheduled again
+
+        vllm_cached_tokens: the number of tokens that are cached in vLLM
+        is only used for preempted requests
+        all_token_ids: the full token list from the vLLM request, used to
+        restore token_ids for preempted requests to ensure chunk keys match
+        """
+
+        if new_block_ids is None:
+            # https://github.com/vllm-project/vllm/commit/
+            # b029de9902aa3ac58806c8c17776c7074175b6db#
+            # diff-cafd89ce8a698a56acb24ada62831cbc7a980782f78a52d1742ba238031f296cL94
+            new_block_ids = []
+        elif len(new_block_ids) == 0:
+            new_block_ids = []
+        elif isinstance(new_block_ids, tuple):
+            new_block_ids = new_block_ids[0]
+        elif isinstance(new_block_ids, list):
+            # If input is a list, flatten it to handle potential nesting.
+            # This also correctly processes already-flat lists.
+            new_block_ids = [
+                i
+                for elem in new_block_ids
+                for i in (elem if isinstance(elem, list) else [elem])
+            ]
+        else:
+            raise ValueError(f"Unsupported new_block_ids type {type(new_block_ids)}")
+
+        if preempted:
+            assert all_token_ids is not None, (
+                f"Preempted request {self.req_id} has no all_token_ids"
+            )
+            # the block ids will change after preemption
+            self.allocated_block_ids = new_block_ids
+            # reset the number of saved tokens
+            self.num_saved_tokens = lmcache_cached_tokens
+            num_computed_tokens = max(lmcache_cached_tokens, vllm_cached_tokens)
+
+            # FIX: For preempted requests, restore token_ids from the full
+            # token list to ensure chunk keys match what was used during
+            # lookup. The lookup uses request.all_token_ids, so we need the
+            # same tokens for retrieve.
+            num_tokens_needed = max(
+                num_computed_tokens + len(new_token_ids),
+                lmcache_cached_tokens,
+            )
+            self.token_ids = all_token_ids[:num_tokens_needed]
+        else:
+            self.allocated_block_ids.extend(new_block_ids)
+            self.token_ids.extend(new_token_ids)
+
+        # When a request is scheduled again, and the number of new tokens
+        # is 1 (excluding chunked prefill), the request is in decode phase.
+        # TODO: Need to further exclude the case of chunked prefill with 1 token.
+        if len(new_token_ids) == 1:
+            self.is_decode_phase = True
+
+
+@dataclass
+class ReqMeta:
+    # Request id
+    req_id: str
+    # Request tokens
+    token_ids: list[int]  # torch.Tensor
+    # Slot mapping
+    slot_mapping: torch.Tensor
+
+    # Whether is last prefill or not
+    is_last_prefill: bool = False
+
+    # Skip save or not
+    save_spec: Optional[SaveSpec] = None
+    # load_spec
+    load_spec: Optional[LoadSpec] = None
+    # disagg spec
+    disagg_spec: Optional[DisaggSpec] = None
+    # the configs of the request
+    request_configs: Optional[dict] = None
+
+    @staticmethod
+    def from_request_tracker(
+        tracker: RequestTracker,
+        block_size: int,
+        lmcache_chunk_size: int = 256,
+        load_spec: Optional[LoadSpec] = None,
+        discard_partial_chunks: bool = True,
+        save_decode_cache: bool = False,
+    ) -> Optional["ReqMeta"]:
+        """Create the request metadata from a request tracker.
+
+        Args:
+            tracker (RequestTracker): the request tracker.
+            block_size (int): the block size in vLLM.
+            lmcache_chunk_size (int): the chunk size for LMCache.
+            load_spec (Optional[LoadSpec]): the load spec for KV cache loading.
+            discard_partial_chunks (bool): whether to discard partial chunks.
+            save_decode_cache (bool): whether to save the cache in decode phase.
+
+        Returns:
+            the request metadata if we need to perform load/save
+            operations, None otherwise.
+        """
+        input_token_ids = tracker.token_ids
+        input_token_len = len(input_token_ids)
+
+        is_last_prefill = False
+        if input_token_len >= tracker.prompt_len:
+            is_last_prefill = True
+
+        # For save operation: do not save if the following condition is met
+        # 1. has already been saved before (num_saved_tokens > 0)
+        # 2. number of unsaved tokens is not reached the chunk boundary
+        # 3. if save_decode_cache is False and it is in decode phase
+
+        skip_leading_tokens = tracker.num_saved_tokens
+        chunk_boundary = (
+            cdiv(tracker.num_saved_tokens + 1, lmcache_chunk_size) * lmcache_chunk_size
+        )
+
+        # NOTE(vladnosiv): for disagg, you cannot skip saving, as saving is a transfer
+        # Check if request_configs has lmcache.skip_save set to True
+        request_skip = (tracker.request_configs or {}).get("lmcache.skip_save", False)
+
+        skip_save = tracker.disagg_spec is None and (
+            tracker.skip_save
+            or (tracker.num_saved_tokens > 0 and input_token_len < chunk_boundary)
+            or (tracker.is_decode_phase and not save_decode_cache)
+            or request_skip
+        )
+
+        if skip_save and load_spec is None:
+            return None
+
+        # Calculate number of tokens to save based on discard_partial_chunks
+        # setting
+
+        # NOTE(vladnosiv): for the input_token_len chunk prefill,
+        # we are required to discard partial chunks,
+        # as new tokens will be added in the next iteration.
+        if not is_last_prefill or discard_partial_chunks:
+            num_tokens_to_save = (
+                input_token_len // lmcache_chunk_size * lmcache_chunk_size
+            )
+        else:
+            num_tokens_to_save = input_token_len
+
+        # If we need to save, update the number of saved tokens
+        if not skip_save:
+            tracker.num_saved_tokens = num_tokens_to_save
+        save_spec = SaveSpec(skip_leading_tokens, not skip_save)
+
+        # Calculate the token ids and slot mappings for load and save
+        token_ids = input_token_ids[:num_tokens_to_save]
+
+        # If the request has multimodal hashes, apply them to the token ids
+        if tracker.mm_hashes:
+            # TODO: Optimize this
+            token_ids = torch.tensor(token_ids)
+            assert tracker.mm_positions is not None, (
+                "tracker got mm_hashes but no mm_positions"
+            )
+            apply_mm_hashes_to_token_ids(
+                token_ids, tracker.mm_hashes, tracker.mm_positions
+            )
+            token_ids = token_ids.tolist()
+
+        num_blocks = len(tracker.allocated_block_ids)
+
+        if len(token_ids) > num_blocks * block_size:
+            logger.error(
+                "The number of tokens is more than the number of blocks"
+                " for request %s. "
+                "Something might be wrong in scheduling logic!",
+                tracker.req_id,
+            )
+            logger.error(
+                "Num tokens: %d, num blocks: %d, block size: %d",
+                len(token_ids),
+                num_blocks,
+                block_size,
+            )
+
+        block_ids = torch.tensor(tracker.allocated_block_ids, dtype=torch.long)
+        block_offsets = torch.arange(0, block_size, dtype=torch.long)
+        slot_mapping = (
+            block_offsets.reshape((1, block_size))
+            + block_ids.reshape((num_blocks, 1)) * block_size
+        )
+
+        slot_mapping = slot_mapping.flatten()[: len(token_ids)]
+        assert slot_mapping.dtype == torch.long  # TODO: this could be removed
+
+        # For load operation: log if the request is scheduled to load
+        if load_spec is not None and load_spec.can_load:
+            logger.debug(
+                "Scheduled to load %d tokens (%d cached in vLLM) for request %s",
+                load_spec.lmcache_cached_tokens,
+                load_spec.vllm_cached_tokens,
+                tracker.req_id,
+            )
+
+        # For disagg requests, compute total_chunks for sender admission control.
+        if tracker.disagg_spec is not None and tracker.disagg_spec.total_chunks == 0:
+            # Only compute once (on first batch)
+            total_chunks_for_req = math.ceil(tracker.prompt_len / lmcache_chunk_size)
+            tracker.disagg_spec.total_chunks = total_chunks_for_req
+
+        # Note: We keep load_spec even when can_load=False to pass metrics to worker
+        return ReqMeta(
+            req_id=tracker.req_id,
+            token_ids=token_ids,
+            slot_mapping=slot_mapping,
+            is_last_prefill=is_last_prefill,
+            save_spec=save_spec,
+            load_spec=load_spec,
+            disagg_spec=tracker.disagg_spec,
+            request_configs=tracker.request_configs,
+        )
+
+
+@dataclass
+class LMCacheConnectorMetadata(KVConnectorMetadata):
+    requests: list[ReqMeta] = field(default_factory=list)
+
+    @_lmcache_nvtx_annotate
+    def add_request(self, req_meta: ReqMeta) -> None:
+        """Add a request to the metadata.
+
+        Args:
+            req_meta (ReqMeta): the request metadata.
+        """
+        self.requests.append(req_meta)
+
+
+class LMCacheConnectorV1Impl:
+    def __init__(
+        self,
+        vllm_config: "VllmConfig",
+        role: KVConnectorRole,
+        parent: KVConnectorBase_V1,
+    ):
+        # Banner from the scheduler role only, so tensor-parallel
+        # deployments print it once rather than once per worker.
+        if role == KVConnectorRole.SCHEDULER:
+            print_banner_once(sys.stderr)
+
+        self._parent = parent
+        self._vllm_config = vllm_config
+        self._role = role
+        self.device = vllm_config.device_config.device
+        self.kv_role = vllm_config.kv_transfer_config.kv_role
+        self.worker_count = vllm_config.parallel_config.tensor_parallel_size
+
+        # Load and configure LMCache config
+        config = lmcache_get_or_create_config()
+        assert isinstance(config, LMCacheEngineConfig), (
+            "LMCache v1 configuration is should be passed for vLLM v1."
+        )
+        self._apply_extra_config(config, vllm_config)
+        self.config = config
+
+        service_factory = VllmServiceFactory(config, vllm_config, role.name.lower())
+        self._manager = LMCacheManager(config, service_factory, connector=self)
+
+        # Start services managed by LMCacheManager
+        self._manager.start_services()
+
+        # Initialize connector-specific state
+        self._init_connector_state(role, vllm_config, config)
+
+        # Setup metrics for monitoring data structures
+        self._setup_metrics()
+
+        logger.info(
+            "LMCache initialized for role %s with version %s, "
+            "vllm version %s, lmcache cache_engine metadata: %s",
+            role,
+            utils.get_version(),
+            VLLM_VERSION,
+            getattr(self.lmcache_engine, "metadata", None),
+        )
+
+    def _apply_extra_config(
+        self, config: LMCacheEngineConfig, vllm_config: "VllmConfig"
+    ) -> None:
+        """Apply extra config from vLLM to LMCache config."""
+        kv_connector_extra_config = (
+            vllm_config.kv_transfer_config.kv_connector_extra_config
+        )
+        if kv_connector_extra_config:
+            for key, value in kv_connector_extra_config.items():
+                if key.startswith("lmcache."):
+                    config_key = key[8:]  # Remove "lmcache." prefix
+                    if validate_and_set_config_value(config, config_key, value):
+                        logger.info(
+                            "Updated config %s from vLLM extra config",
+                            config_key,
+                        )
+
+    def _init_connector_state(
+        self,
+        role: KVConnectorRole,
+        vllm_config: "VllmConfig",
+        config: LMCacheEngineConfig,
+    ) -> None:
+        """Initialize connector-specific state variables."""
+        self.async_loading = config.enable_async_loading
+        self.layerwise_retrievers: list[
+            Generator[Optional[torch.Tensor], None, None]
+        ] = []
+        self._layerwise_save_storers: dict[
+            str, Generator[Optional[torch.Tensor], None, None]
+        ] = {}
+        self._stats_monitor = LMCStatsMonitor.GetOrCreate()
+
+        # Role-specific initialization
+        if role == KVConnectorRole.SCHEDULER:
+            self._unfinished_requests: dict[str, "Request"] = {}
+        else:
+            self.use_layerwise = config.use_layerwise
+            self.enable_blending = config.enable_blending
+
+            if self.enable_blending:
+                assert self.lmcache_engine is not None
+                assert self.lmcache_engine.gpu_connector is not None, (
+                    "GPU connector must be available for blending"
+                )
+                self.blender = LMCBlenderBuilder.get_or_create(
+                    ENGINE_NAME,
+                    self.lmcache_engine,
+                    self.lmcache_engine.gpu_connector,
+                    config,
+                )
+
+        # Legacy compatibility check
+        self._check_legacy_register_kv_caches()
+
+        self.kv_caches: dict[str, torch.Tensor] = {}
+        self._block_size = vllm_config.cache_config.block_size
+        self.load_specs: dict[str, LoadSpec] = {}
+        self.kv_cache_manager: Optional["KVCacheManager"] = None
+        self._request_trackers: dict[str, RequestTracker] = {}
+
+        self._discard_partial_chunks = (
+            vllm_config.kv_transfer_config.get_from_extra_config(
+                "discard_partial_chunks", False
+            )
+            or not config.save_unfull_chunk
+        )
+
+        self._lmcache_chunk_size = config.chunk_size
+
+        self.skip_last_n_tokens = vllm_config.kv_transfer_config.get_from_extra_config(
+            "skip_last_n_tokens", 0
+        )
+
+        self.num_layers = vllm_config.model_config.get_num_layers(
+            vllm_config.parallel_config
+        )
+        self.current_layer = 0
+
+        self.force_skip_save = bool(os.environ.get("LMCACHE_FORCE_SKIP_SAVE", False))
+        self._requests_priority: dict[str, int] = {}
+
+        # Chunked KV loading: cap the number of external tokens
+        # reported per scheduling step to prevent GPU block pool
+        # exhaustion at high concurrency with long contexts.
+        # Configurable via kv_connector_extra_config:
+        #   "lmcache.max_tokens_per_load": <int>
+        # Default 0 (no cap — original behavior, all matched tokens
+        # reported at once). Set to a positive value (e.g. 131072)
+        # to enable chunked loading.
+        self._max_tokens_per_load: int = int(
+            vllm_config.kv_transfer_config.get_from_extra_config(
+                "lmcache.max_tokens_per_load", 0
+            )
+        )
+        self._invalid_block_ids: set[int] = set()
+
+    def _check_legacy_register_kv_caches(self) -> None:
+        """Check for legacy connector without register_kv_caches implementation."""
+        if self.lmcache_engine is None:
+            return
+
+        child_class = self._parent.__class__
+        parent_class = KVConnectorBase_V1
+        child_method = getattr(child_class, "register_kv_caches", None)
+        parent_method = getattr(parent_class, "register_kv_caches", None)
+
+        if child_method is None or parent_method is None:
+            implements = False
+        else:
+            implements = child_method is not parent_method
+
+        if not implements:
+            logger.warning(
+                "Please use the latest lmcache connector, otherwise some "
+                "features may not work, such as DSA"
+            )
+            self._manager.post_init()
+
+    # ==================== Property Accessors ====================
+
+    @property
+    def lmcache_engine(self) -> Optional[LMCacheEngine]:
+        """Get the LMCache engine instance from manager."""
+        return self._manager.lmcache_engine
+
+    @property
+    def lmcache_engine_metadata(self):
+        """Get the LMCache engine metadata from manager."""
+        return self._manager.lmcache_engine_metadata
+
+    @property
+    def lookup_client(self) -> Optional["LookupClientInterface"]:
+        """Get the lookup client from manager."""
+        return self._manager.lookup_client
+
+    @property
+    def lookup_server(self):
+        """Get the lookup server from manager."""
+        return self._manager.lookup_server
+
+    def _setup_metrics(self) -> None:
+        """Setup metrics for monitoring data structures in the connector."""
+        metadata = self._manager.lmcache_engine_metadata
+        if metadata is None:
+            logger.warning(
+                "LMCache metadata is not initialized, "
+                "connector metrics will not be collected"
+            )
+            return
+        prometheus_logger = PrometheusLogger.GetOrCreate(
+            metadata,
+            config=self.config,
+        )
+
+        # Set up metrics for scheduler-specific and general data structures
+        metrics_map = {
+            "_unfinished_requests": "scheduler_unfinished_requests_count",
+            "load_specs": "connector_load_specs_count",
+            "_request_trackers": "connector_request_trackers_count",
+            "kv_caches": "connector_kv_caches_count",
+            "layerwise_retrievers": "connector_layerwise_retrievers_count",
+            "_invalid_block_ids": "connector_invalid_block_ids_count",
+            "_requests_priority": "connector_requests_priority_count",
+        }
+
+        for attr_name, metric_name in metrics_map.items():
+            if hasattr(self, attr_name):
+                metric = getattr(prometheus_logger, metric_name)
+                # Use a default argument in the lambda to capture
+                # the current value of `attr_name`
+                # to avoid issues with late binding in closures.
+                metric.set_function(lambda name=attr_name: len(getattr(self, name)))
+
+    def get_inference_info(self) -> dict:
+        """Get inference information including vLLM config and related details.
+
+        Returns:
+            dict: Dictionary containing inference information
+        """
+        # Get vLLM config information
+        vllm_config = self._vllm_config
+
+        # Use vLLM config's string representation and add specific configs
+        inference_info = {
+            "vllm_version": VLLM_VERSION,
+            "lmcache_version": utils.get_version(),
+            "vllm_config": str(vllm_config),
+            "model_config": {
+                "model": getattr(vllm_config.model_config, "model", None),
+                "dtype": str(getattr(vllm_config.model_config, "dtype", None)),
+                "max_model_len": getattr(
+                    vllm_config.model_config, "max_model_len", None
+                ),
+                "vocab_size": getattr(vllm_config.model_config, "vocab_size", None),
+                "num_layers": getattr(
+                    vllm_config.model_config, "get_num_layers", lambda _: None
+                )(vllm_config.parallel_config),
+                "num_attention_heads": getattr(
+                    vllm_config.model_config, "get_num_attention_heads", lambda _: None
+                )(vllm_config.parallel_config),
+                "num_kv_heads": getattr(
+                    vllm_config.model_config, "get_num_kv_heads", lambda _: None
+                )(vllm_config.parallel_config),
+                "head_size": getattr(
+                    vllm_config.model_config, "get_head_size", lambda: None
+                )(),
+            },
+            "cache_config": {
+                "block_size": getattr(vllm_config.cache_config, "block_size", None),
+                "cache_dtype": str(
+                    getattr(vllm_config.cache_config, "cache_dtype", None)
+                ),
+                "gpu_memory_utilization": getattr(
+                    vllm_config.cache_config, "gpu_memory_utilization", None
+                ),
+                "swap_space": getattr(vllm_config.cache_config, "swap_space", None),
+                "enable_prefix_caching": getattr(
+                    vllm_config.cache_config, "enable_prefix_caching", None
+                ),
+            },
+        }
+
+        return inference_info
+
+    def get_inference_version(self) -> str:
+        """Get vLLM version information.
+
+        Returns:
+            str: vLLM version string
+        """
+        return VLLM_VERSION
+
+    # TODO(chunxiaozheng): in the latest lmcache_connector, we use `register_kv_caches`
+    #  to init self.kv_caches, we keep it in order to be compatible with old versions
+    #  and will be removed in the future.
+    @_lmcache_nvtx_annotate
+    def _init_kv_caches_from_forward_context(self, forward_context: "ForwardContext"):
+        for layer_name in forward_context.no_compile_layers:
+            attn_layer = forward_context.no_compile_layers[layer_name]
+            if not hasattr(attn_layer, "kv_cache"):
+                logger.debug("The layer %s does not have kv_cache, skip it", layer_name)
+                continue
+
+            if layer_name not in self.kv_caches:
+                self.kv_caches[layer_name] = attn_layer.kv_cache[
+                    forward_context.virtual_engine
+                ]
+
+    ####################
+    # Worker side APIs
+    ####################
+    @_lmcache_nvtx_annotate
+    def register_kv_caches(self, kv_caches: dict[str, torch.Tensor]):
+        logger.info("Registering KV caches")
+        # TODO(chunxiaozheng): `_init_kv_caches_from_forward_context` is
+        #  not called, we should consider removing it.
+        assert len(self.kv_caches) == 0 and len(kv_caches) > 0
+        self.kv_caches = kv_caches
+        self._manager.post_init()
+
+    @_lmcache_nvtx_annotate
+    def start_load_kv(self, forward_context: "ForwardContext", **kwargs) -> None:
+        """Start loading the KV cache from the connector buffer to vLLM's
+        paged KV buffer.
+
+        Args:
+            forward_context (ForwardContext): the forward context.
+            **kwargs: additional arguments for the load operation
+        """
+        self.current_layer = 0
+
+        if len(self.kv_caches) == 0:
+            logger.warning(
+                "Please update LMCacheConnector, "
+                "use register_kv_caches to init kv_caches"
+            )
+            self._init_kv_caches_from_forward_context(forward_context)
+
+        metadata = self._parent._get_connector_metadata()
+        assert isinstance(metadata, LMCacheConnectorMetadata)
+
+        assert len(self.kv_caches) > 0
+        kvcaches = list(self.kv_caches.values())
+
+        attn_metadata = forward_context.attn_metadata
+        if attn_metadata is None:
+            logger.debug("In connector.start_load_kv, but the attn_metadata is None")
+            return
+
+        # LMCache failed to initialize and is running in degraded mode; skip the
+        # KV load so vLLM falls back to recompute instead of crashing EngineCore.
+        if self.lmcache_engine is None:
+            return
+
+        self.layerwise_retrievers = []
+
+        for idx, request in enumerate(metadata.requests):
+            if request.load_spec is None or not request.load_spec.can_load:
+                continue
+            last_idx = idx
+
+        for idx, request in enumerate(metadata.requests):
+            # Update metrics for all requests that have a load_spec
+            if request.load_spec is not None:
+                self._stats_monitor.update_interval_vllm_hit_tokens(
+                    request.load_spec.vllm_cached_tokens
+                )
+                self._stats_monitor.update_interval_prompt_tokens(
+                    len(request.token_ids)
+                )
+
+            if request.load_spec is None or not request.load_spec.can_load:
+                continue
+
+            tokens = request.token_ids
+            # TODO: have a pre-allocated buffer to hold the slot_mappings
+            slot_mapping = request.slot_mapping.to(self.device)
+            assert len(tokens) == len(slot_mapping)
+
+            token_mask = torch.ones(len(tokens), dtype=torch.bool)
+            masked_token_count = (
+                request.load_spec.vllm_cached_tokens
+                // self._lmcache_chunk_size
+                * self._lmcache_chunk_size
+            )
+            token_mask[:masked_token_count] = False
+
+            lmcache_cached_tokens = request.load_spec.lmcache_cached_tokens
+            if self.use_layerwise:
+                if idx == last_idx:
+                    sync = True
+                else:
+                    sync = False
+                # NOTE(Jiayi): Perform blending before layerwise prefix caching
+                if self.enable_blending:
+                    # TODO(Jiayi): Need to make prefix caching and blending compatible
+                    self.blender.blend(
+                        tokens[:lmcache_cached_tokens],
+                        token_mask[:lmcache_cached_tokens],
+                        kvcaches=kvcaches,
+                        slot_mapping=slot_mapping[:lmcache_cached_tokens],
+                        vllm_cached_tokens=request.load_spec.vllm_cached_tokens,
+                    )
+                else:
+                    layerwise_retriever = self.lmcache_engine.retrieve_layer(
+                        tokens[:lmcache_cached_tokens],
+                        token_mask[:lmcache_cached_tokens],
+                        kvcaches=kvcaches,
+                        slot_mapping=slot_mapping[:lmcache_cached_tokens],
+                        vllm_cached_tokens=request.load_spec.vllm_cached_tokens,
+                        sync=sync,
+                    )
+                    # NOTE: retrieve for two layers at the first layer
+                    next(layerwise_retriever)
+                    next(layerwise_retriever)
+                    self.layerwise_retrievers.append(layerwise_retriever)
+            else:
+                ret_token_mask = self.lmcache_engine.retrieve(
+                    tokens[:lmcache_cached_tokens],
+                    token_mask[:lmcache_cached_tokens],
+                    kvcaches=kvcaches,
+                    slot_mapping=slot_mapping[:lmcache_cached_tokens],
+                    vllm_cached_tokens=request.load_spec.vllm_cached_tokens,
+                    request_configs=request.request_configs,
+                    req_id=request.req_id,
+                )
+
+                # Check the result
+                num_retrieved_tokens = ret_token_mask.sum().item()
+                num_expected_tokens = (
+                    lmcache_cached_tokens - request.load_spec.vllm_cached_tokens
+                )
+                if num_retrieved_tokens < num_expected_tokens:
+                    logger.error(
+                        "Request %s"
+                        "The number of retrieved tokens is less than the "
+                        "expected number of tokens! This should not happen!",
+                        request.req_id,
+                    )
+                    logger.error(
+                        "Num retrieved tokens: %d, num expected tokens: %d",
+                        num_retrieved_tokens,
+                        num_expected_tokens,
+                    )
+                    """
+                    Report failed block IDs in case of partial failure.
+                    """
+                    missing_blocks = self.record_failed_blocks(
+                        request.req_id,
+                        token_mask[:lmcache_cached_tokens],
+                        ret_token_mask,
+                        slot_mapping[:lmcache_cached_tokens],
+                    )
+                    self._invalid_block_ids.update(missing_blocks)
+
+    def record_failed_blocks(
+        self,
+        request_id: str,
+        expected_mask: torch.Tensor,
+        ret_mask: torch.Tensor,
+        slot_mapping: torch.Tensor,
+    ) -> set[int]:
+        """Record block IDs associated with failed load attempts.
+
+        Args:
+            request_id: request id from vLLM.
+            expected_mask: Boolean tensor indicating which tokens were expected to
+                be loaded from LMCache. True means the token should be loaded,
+                False means the token is already cached in vLLM and does not need
+                to be loaded from LMCache.
+            ret_mask: Boolean tensor indicating which tokens were actually
+                successfully retrieved from LMCache. True means the token was
+                successfully loaded. For example, if 256 tokens are expected to be
+                loaded, but only 192 tokens are successfully loaded, then the
+                ret_mask will be a tensor of 256 items like [T, T, ..., F, F, ...]
+                where the first 192 elements are True and the last 64 elements
+                are False.
+            slot_mapping: Tensor indicating slot IDs for each token. The block
+                ID is computed by dividing the slot ID by the block size.
+
+        Example:
+            expected_mask = [F, T, T, T] meaning the 1st is in vLLM cache
+            ret_mask = [F, T, F, F] meaning failure from loading the 3rd
+            missing_mask = expected_mask & ~ret_mask = [F, F, T, T]
+            missing_indices = [2, 3]
+            then missing_blocks is calculated from slot_mapping and missing_indices
+
+        Returns:
+            set[int]: Set of block IDs that failed to load.
+        """
+
+        if expected_mask.numel() == 0:
+            return set()
+
+        expected_mask_cpu = expected_mask.to(device="cpu", dtype=torch.bool)
+        ret_mask_cpu = ret_mask.to(device="cpu", dtype=torch.bool)
+
+        if ret_mask_cpu.shape[0] != expected_mask_cpu.shape[0]:
+            logger.debug("expected_mask_cpu.shape[0] != ret_mask_cpu.shape[0]")
+            return set()
+
+        missing_mask = expected_mask_cpu & ~ret_mask_cpu
+        if not torch.any(missing_mask):
+            return set()
+
+        missing_indices = torch.nonzero(missing_mask, as_tuple=False).view(-1)
+        if missing_indices.numel() == 0:
+            return set()
+
+        slot_mapping_cpu = slot_mapping.to(device="cpu", dtype=torch.long)
+        if slot_mapping_cpu.shape[0] > missing_mask.shape[0]:
+            slot_mapping_cpu = slot_mapping_cpu[: missing_mask.shape[0]]
+
+        missing_blocks_tensor = torch.unique(
+            slot_mapping_cpu[missing_indices] // self._block_size
+        )
+        missing_blocks = {int(block.item()) for block in missing_blocks_tensor}
+
+        if not missing_blocks:
+            return set()
+
+        logger.warning(
+            "Request %s failed to load %d tokens across %d blocks",
+            request_id,
+            missing_indices.numel(),
+            len(missing_blocks),
+        )
+        return missing_blocks
+
+    @_lmcache_nvtx_annotate
+    def wait_for_layer_load(self, layer_name: str) -> None:
+        """Blocking until the KV for a specific layer is loaded into vLLM's
+        paged buffer.
+
+        This interface will be useful for layer-by-layer pipelining.
+
+        Args:
+            layer_name: the name of that layer
+        """
+        if self.layerwise_retrievers:
+            logger.debug(f"Waiting for layer {self.current_layer} to be loaded")
+
+        # Wait for the layer to be loaded
+        for layerwise_retriever in self.layerwise_retrievers:
+            ret_token_mask = next(layerwise_retriever)
+
+            if self.current_layer == self.num_layers - 1:
+                assert ret_token_mask is not None
+                num_retrieved_tokens = ret_token_mask.sum().item()
+                logger.info(f"Retrieved {num_retrieved_tokens} tokens")
+
+        if self.layerwise_retrievers:
+            self.current_layer += 1
+
+        return
+
+    @_lmcache_nvtx_annotate
+    def save_kv_layer(
+        self,
+        layer_name: str,
+        kv_layer: torch.Tensor,
+        attn_metadata: "AttentionMetadata",
+        **kwargs,
+    ) -> None:
+        """Start saving the a layer of KV cache from vLLM's paged buffer
+        to the connector.
+
+        Args:
+            layer_name (str): the name of the layer.
+            kv_layer (torch.Tensor): the paged KV buffer of the current
+                layer in vLLM.
+            attn_metadata (AttentionMetadata): the attention metadata.
+            **kwargs: additional arguments for the save operation.
+        """
+        # Degraded mode (LMCache init failed): nothing to save, fall back silently.
+        if self.lmcache_engine is None:
+            return
+
+        if not self.use_layerwise:
+            return
+
+        if self.kv_role == "kv_consumer":
+            # Don't do save if the role is kv_consumer
+            return
+        if self._parent._connector_metadata is None:
+            logger.warning(
+                "In connector.save_kv_layer, but the connector metadata is None"
+            )
+            return
+        connector_metadata = self._parent._get_connector_metadata()
+        assert isinstance(connector_metadata, LMCacheConnectorMetadata)
+
+        assert len(self.kv_caches) > 0
+
+        kvcaches = list(self.kv_caches.values())
+        is_first = True
+
+        for request in connector_metadata.requests:
+            save_spec = request.save_spec
+            if (
+                save_spec is None or not save_spec.can_save
+            ) and self.kv_role != "kv_producer":
+                continue
+
+            layerwise_storer = self._layerwise_save_storers.get(request.req_id)
+            if layerwise_storer is None:
+                token_ids = request.token_ids
+                assert isinstance(token_ids, list)
+
+                slot_mapping = request.slot_mapping
+                assert isinstance(slot_mapping, torch.Tensor)
+                assert len(slot_mapping) == len(token_ids)
+
+                # TODO: have a pre-allocated buffer to hold the slot_mappings
+                slot_mapping = slot_mapping.to(self.device)
+
+                if self.kv_role == "kv_producer":
+                    skip_leading_tokens = 0
+                else:
+                    assert save_spec is not None
+                    skip_leading_tokens = save_spec.skip_leading_tokens
+
+                    if skip_leading_tokens == len(token_ids):
+                        continue  # skip this request
+                    # Align to lmcache chunk size
+                    skip_leading_tokens = (
+                        skip_leading_tokens
+                        // self._lmcache_chunk_size
+                        * self._lmcache_chunk_size
+                    )
+
+                store_mask = torch.ones(len(token_ids), dtype=torch.bool)
+                store_mask[:skip_leading_tokens] = False
+
+                logger.debug(
+                    "Storing KV cache for %d out of %d tokens "
+                    "(skip_leading_tokens=%d) for request %s",
+                    len(token_ids) - skip_leading_tokens,
+                    len(token_ids),
+                    skip_leading_tokens,
+                    request.req_id,
+                )
+
+                # TODO (Jiayi): need to make layerwise storing
+                # compatible with disagg spec
+                layerwise_storer = self.lmcache_engine.store_layer(
+                    token_ids,
+                    mask=store_mask,
+                    kvcaches=kvcaches,
+                    slot_mapping=slot_mapping,
+                    offset=skip_leading_tokens,
+                    sync=is_first,
+                    req_id=request.req_id,
+                )
+                self._layerwise_save_storers[request.req_id] = layerwise_storer
+                if is_first:
+                    is_first = False
+
+            next(layerwise_storer)
+
+    @_lmcache_nvtx_annotate
+    def wait_for_save(self):
+        """Blocking until the KV cache is saved to the connector buffer."""
+
+        # Degraded mode (LMCache init failed): no engine to save to / unpin from.
+        if self.lmcache_engine is None:
+            return
+
+        connector_metadata = self._parent._get_connector_metadata()
+        assert isinstance(connector_metadata, LMCacheConnectorMetadata)
+
+        if self.kv_role == "kv_consumer":
+            # Don't do save if the role is kv_consumer
+            # But still need to unpin the kv caches according to req_id
+            # to balance the pin count from contains()
+            assert self.lmcache_engine is not None, (
+                "LMCacheEngine must be initialized to unpin requests."
+            )
+            for request in connector_metadata.requests:
+                self.lmcache_engine.lookup_unpin(request.req_id)
+
+            return
+
+        if self.use_layerwise:
+            for request in connector_metadata.requests:
+                layerwise_storer = self._layerwise_save_storers.pop(
+                    request.req_id, None
+                )
+                if layerwise_storer is not None:
+                    next(layerwise_storer)
+                # unpin the kv caches according to req_id
+                self.lmcache_engine.lookup_unpin(request.req_id)
+            return
+
+        assert len(self.kv_caches) > 0
+        kvcaches = list(self.kv_caches.values())
+
+        assert self.lmcache_engine is not None
+
+        # Probe decoder cache before store if bidirectional mode is enabled
+        bidir_enabled = getattr(self.config, "pd_bidirectional", False)
+
+        for request in connector_metadata.requests:
+            # unpin the kv caches according to req_id
+            self.lmcache_engine.lookup_unpin(request.req_id)
+
+            save_spec = request.save_spec
+            if (
+                save_spec is None or not save_spec.can_save
+            ) and self.kv_role != "kv_producer":
+                continue
+
+            token_ids = request.token_ids
+
+            slot_mapping = request.slot_mapping
+            assert isinstance(slot_mapping, torch.Tensor)
+            if len(slot_mapping) != len(token_ids):
+                logger.warning(
+                    "Skipping KV save for request %s: slot_mapping/token_ids "
+                    "length mismatch (slot_mapping=%d, token_ids=%d). Likely "
+                    "an upstream allocation/preemption desync; the engine "
+                    "stays alive and only this request's save is dropped.",
+                    request.req_id,
+                    len(slot_mapping),
+                    len(token_ids),
+                )
+                continue
+
+            # TODO: have a pre-allocated buffer to hold the slot_mappings
+            slot_mapping = slot_mapping.to(self.device)
+
+            skip_leading_tokens = save_spec.skip_leading_tokens
+            # shared storage disaggregation will not have a disagg_spec passed in
+            if self.kv_role == "kv_producer" and request.disagg_spec:
+                skip_leading_tokens = min(
+                    skip_leading_tokens, request.disagg_spec.num_transferred_tokens
+                )
+
+            if skip_leading_tokens == len(token_ids):
+                continue  # skip this request
+            # Align to lmcache chunk size
+            skip_leading_tokens = (
+                skip_leading_tokens
+                // self._lmcache_chunk_size
+                * self._lmcache_chunk_size
+            )
+
+            store_mask = torch.ones(len(token_ids), dtype=torch.bool)
+            store_mask[:skip_leading_tokens] = False
+
+            logger.debug(
+                "Storing KV cache for %d out of %d tokens "
+                "(skip_leading_tokens=%d) for request %s",
+                len(token_ids) - skip_leading_tokens,
+                len(token_ids),
+                skip_leading_tokens,
+                request.req_id,
+            )
+
+            is_last_prefill = request.is_last_prefill
+            if is_last_prefill:
+                if request.disagg_spec:
+                    request.disagg_spec.is_last_prefill = True
+            else:
+                if not self.enable_blending:
+                    token_len = len(token_ids)
+                    aligned_token_len = (
+                        token_len // self._lmcache_chunk_size * self._lmcache_chunk_size
+                    )
+                    token_ids = token_ids[:aligned_token_len]
+                    store_mask = store_mask[:aligned_token_len]
+                    slot_mapping = slot_mapping[:aligned_token_len]
+
+            # Probe decoder cache before store
+            if bidir_enabled and request.disagg_spec is not None:
+                try:
+                    self._probe_decoder_cache(request, token_ids)
+                except Exception as e:
+                    logger.warning(
+                        "Bidirectional NIXL cache probe failed for %s: %s",
+                        request.req_id,
+                        e,
+                    )
+
+            self.lmcache_engine.store(
+                token_ids,
+                mask=store_mask,
+                kvcaches=kvcaches,
+                slot_mapping=slot_mapping,
+                offset=skip_leading_tokens,
+                transfer_spec=request.disagg_spec,
+                request_configs=request.request_configs,
+                req_id=request.req_id,
+            )
+
+            # Probe decoder cache after store
+            if (
+                bidir_enabled
+                and request.disagg_spec is not None
+                and request.disagg_spec.receiver_query_port is not None
+            ):
+                try:
+                    self._probe_decoder_cache(request, token_ids)
+                except Exception as e:
+                    logger.warning(
+                        "Bidirectional NIXL cache probe failed for %s: %s",
+                        request.req_id,
+                        e,
+                    )
+
+            # Update skip_leading_tokens only on last rank to ensure
+            # each PP stage stores its own KV cache
+            if get_pp_group().is_last_rank:
+                # NOTE(Jiayi): We assume all tokens are saved
+                save_spec.skip_leading_tokens = len(token_ids)
+                if request.disagg_spec:
+                    request.disagg_spec.num_transferred_tokens = len(token_ids)
+
+    def _probe_decoder_cache(self, request: ReqMeta, token_ids: list[int]) -> None:
+        """Query the decoder's cache to check which blocks are already cached.
+
+        This is the bidirectional NIXL cache probe: the prefiller queries the
+        decoder via ZMQ to find out which KV blocks are already in the
+        decoder's GPU memory. This validates the cache query channel works
+        E2E through the real inference path.
+
+        In the future, this information can be used to skip prefill
+        computation for cached blocks.
+        """
+        sm = self.lmcache_engine.storage_manager  # type: ignore[union-attr]
+        if sm is None or sm.allocator_backend is None:
+            return
+        pd_backend = sm.allocator_backend
+        if not hasattr(pd_backend, "query_remote_cache"):
+            return
+        if not hasattr(pd_backend, "cache_query_sockets"):
+            return
+
+        # Get query port from LMCache config (pd_peer_query_port)
+        query_ports = self.config.pd_peer_query_port
+        if query_ports is None:
+            return
+
+        # Build cache keys using the token database's process_tokens
+        td = self.lmcache_engine.token_database  # type: ignore[union-attr]
+        if td is None:
+            return
+
+        chunk_keys = []
+        for _start, _end, key in td.process_tokens(
+            tokens=token_ids, mask=None, make_key=True
+        ):
+            chunk_keys.append(key)
+
+        if not chunk_keys:
+            return
+
+        # Build receiver_id from disagg_spec
+        disagg = request.disagg_spec
+        init_port = disagg.receiver_init_port  # type: ignore[union-attr]
+        if isinstance(init_port, list):
+            init_port = init_port[pd_backend.tp_rank]  # type: ignore[union-attr]
+        receiver_id = disagg.receiver_host + str(init_port)  # type: ignore[union-attr]
+
+        # Ensure peer and cache query connections
+        alloc_port = disagg.receiver_alloc_port  # type: ignore[union-attr]
+        if isinstance(alloc_port, list):
+            alloc_port = alloc_port[pd_backend.tp_rank]  # type: ignore[union-attr]
+        query_port = query_ports[pd_backend.tp_rank]  # type: ignore[union-attr]
+
+        pd_backend._ensure_peer_connection(  # type: ignore[union-attr]
+            receiver_id=receiver_id,
+            receiver_host=disagg.receiver_host,  # type: ignore[union-attr]
+            receiver_init_port=init_port,
+            receiver_alloc_port=alloc_port,
+        )
+        pd_backend._ensure_cache_query_connection(  # type: ignore[union-attr]
+            receiver_id=receiver_id,
+            receiver_host=disagg.receiver_host,  # type: ignore[union-attr]
+            receiver_query_port=query_port,
+        )
+
+        # Query decoder cache
+        cache_resp = pd_backend.query_remote_cache(receiver_id, chunk_keys)
+
+        logger.info(
+            "Bidirectional NIXL cache probe: req=%s, "
+            "queried %d chunks, decoder has %d cached "
+            "(%.0f%% hit rate)",
+            request.req_id,
+            len(chunk_keys),
+            len(cache_resp.cached_keys),
+            100.0 * len(cache_resp.cached_keys) / len(chunk_keys) if chunk_keys else 0,
+        )
+
+    @_lmcache_nvtx_annotate
+    def get_finished(
+        self, finished_req_ids: set[str]
+    ) -> tuple[Optional[set[str]], Optional[set[str]]]:
+        return None, None
+
+    def get_block_ids_with_load_errors(self) -> set[int]:
+        invalid_blocks = self._invalid_block_ids.copy()
+        self._invalid_block_ids.clear()
+        return invalid_blocks
+
+    @_lmcache_nvtx_annotate
+    def shutdown(self):
+        """Shutdown the connector by delegating to LMCacheManager."""
+        logger.info("Starting LMCacheConnector shutdown...")
+        self._manager.stop_services()
+
+    ###################
+    # Scheduler side APIs
+    ####################
+
+    @_lmcache_nvtx_annotate
+    def get_num_new_matched_tokens(
+        self,
+        request: "Request",
+        num_computed_tokens: int,
+    ) -> Optional[int]:
+        """
+        Check for external KV cache hit.
+
+        Args:
+            request (Request): the request object.
+            num_computed_tokens (int): the number of locally
+                computed tokens for this request
+
+        Returns:
+            the number of tokens that can be loaded from the
+            external KV cache beyond what is already computed.
+        """
+        # Ignore DP attention mock requests
+        if request.request_id.startswith("mock_req"):
+            return 0
+        # to handle preempted requests, we want `get_num_new_matched_tokens` to be
+        # idempotent under the condition that `update_state_after_alloc` is NOT called
+        # then the two side-effects that must be idempotent are:
+        # 1. lookup_client caches a result
+        #     uncached in `update_state_after_alloc` if this request can be scheduled
+        # 2. cache engine will pin the KV caches for the request
+        #     unpinned in `wait_for_save` if this request can be scheduled
+        if self.kv_role == "kv_producer" and not hasattr(
+            self.lookup_client, "supports_producer_reuse"
+        ):
+            return 0
+
+        req_id = request.request_id
+
+        # Degraded mode (LMCache init failed): no lookup client is available, so
+        # report no external hits and let vLLM recompute instead of asserting and
+        # crashing EngineCore during scheduling.
+        if self.lookup_client is None:
+            return 0
+
+        if (
+            num_external_hit_tokens := self.lookup_client.lookup_cache(lookup_id=req_id)
+        ) != -1:
+            # -1 means no result cached
+            # None or int means ongoing (async) or cached result
+            logger.debug(
+                f"Found {num_external_hit_tokens} hit tokens for request"
+                f" {req_id} in the lookup cache."
+            )
+        else:
+            logger.debug(f"Looking up cache for the first time for request {req_id}!")
+            self._requests_priority[req_id] = getattr(request, "priority", 0)
+
+            # token_ids = request.prompt_token_ids
+            # all token ids covers the preemption case
+            token_ids = request.all_token_ids
+
+            # If the request has multimodal hashes, apply them to the token ids
+            mm_hashes, mm_positions = extract_mm_features(request)
+            if mm_hashes and mm_positions:
+                # TODO(Jiayi): Optimize this
+                token_ids = torch.tensor(request.prompt_token_ids)
+                apply_mm_hashes_to_token_ids(token_ids, mm_hashes, mm_positions)
+                token_ids = token_ids.tolist()
+
+            request_configs = extract_request_configs(request.sampling_params)
+            if self.skip_last_n_tokens > 0:
+                token_ids = token_ids[: -self.skip_last_n_tokens]
+
+            num_external_hit_tokens = self.lookup_client.lookup(
+                token_ids,
+                lookup_id=req_id,
+                request_configs=request_configs,
+            )
+
+        if num_external_hit_tokens is None:
+            logger.debug(
+                "Reqid: %s, Total tokens %d, Inference Engine computed tokens: %d, "
+                "LMCache hit tokens: None.",
+                req_id,
+                request.num_tokens,
+                num_computed_tokens,
+            )
+            return None
+
+        # When prompt length is divisible by the block size and all
+        # blocks are cached, we need to recompute the last token.
+        # This will be removed in the future if vLLM's scheduler provides
+        # a better support for this case.
+        need_to_allocate = num_external_hit_tokens - num_computed_tokens
+
+        # In, full-prompt-hit case, we need to recompute the last token
+        if num_external_hit_tokens == request.num_tokens:
+            need_to_allocate -= 1
+
+        # Check if hit tokens meet the minimum for retrieve
+        # If below minimum, skip retrieve but still record hit tokens
+        # for skip_leading_tokens to avoid re-storing existing chunks
+        min_retrieve = self.config.min_retrieve_tokens
+        below_min_retrieve = min_retrieve > 0 and need_to_allocate < min_retrieve
+
+        if below_min_retrieve:
+            logger.info(
+                "Reqid: %s, Total tokens %d, Inference Engine computed tokens: %d, "
+                "LMCache hit tokens: %d, but need to load: %d < min_retrieve %d, "
+                "skip retrieve but record for save skip",
+                req_id,
+                request.num_tokens,
+                num_computed_tokens,
+                num_external_hit_tokens,
+                max(need_to_allocate, 0),
+                min_retrieve,
+            )
+        else:
+            logger.info(
+                "Reqid: %s, Total tokens %d, Inference Engine computed tokens: %d, "
+                "LMCache hit tokens: %d, need to load: %d",
+                req_id,
+                request.num_tokens,
+                num_computed_tokens,
+                num_external_hit_tokens,
+                max(need_to_allocate, 0),
+            )
+
+        # Chunked KV loading: cap the number of tokens reported
+        # to the scheduler to avoid exhausting the GPU block pool
+        # when many concurrent requests each need large allocations.
+        # Remaining tokens beyond the cap will be computed locally
+        # via chunked prefill rather than loaded from external cache.
+        capped_lmcache_tokens = num_external_hit_tokens
+        if (
+            self._max_tokens_per_load > 0
+            and need_to_allocate > self._max_tokens_per_load
+        ):
+            # Align cap to LMCache chunk boundaries so that the
+            # retrieve path receives chunk-aligned token ranges.
+            cap = (
+                self._max_tokens_per_load
+                // self._lmcache_chunk_size
+                * self._lmcache_chunk_size
+            )
+            need_to_allocate = cap
+            # Align capped_lmcache_tokens to chunk boundary so that
+            # session.get_hashes() receives a chunk-aligned end value.
+            capped_lmcache_tokens = (
+                (num_computed_tokens + cap)
+                // self._lmcache_chunk_size
+                * self._lmcache_chunk_size
+            )
+            logger.debug(
+                "Reqid: %s, Chunked KV loading: capped from "
+                "%d to %d external tokens "
+                "(max_tokens_per_load=%d)",
+                req_id,
+                num_external_hit_tokens - num_computed_tokens,
+                need_to_allocate,
+                self._max_tokens_per_load,
+            )
+
+        self.load_specs[req_id] = LoadSpec(
+            vllm_cached_tokens=num_computed_tokens,
+            lmcache_cached_tokens=capped_lmcache_tokens,
+            can_load=False,
+        )
+
+        if below_min_retrieve or need_to_allocate <= 0:
+            return 0
+
+        # TODO: Align to vLLM block size. Should test whether it can be removed
+        # need_to_allocate = need_to_allocate // self._block_size * \
+        #        self._block_size
+
+        return need_to_allocate
+
+    @_lmcache_nvtx_annotate
+    def update_state_after_alloc(self, request: "Request", num_external_tokens: int):
+        """
+        Update KVConnector state after temporary buffer alloc.
+
+        For SharedStorageConnector, update _request_needs_load
+        if the CacheManager this allocated blocks for us.
+        """
+
+        # Degraded mode (LMCache init failed): there is no lookup client to clear
+        # and no load spec was recorded, so nothing to do.
+        if self.lookup_client is None:
+            return
+
+        # Clear local status in lookup client when a new request is
+        # successfully scheduled.
+        self.lookup_client.clear_lookup_status(request.request_id)
+
+        kv_transfer_params = (
+            request.kv_transfer_params
+            if hasattr(request, "kv_transfer_params")
+            else None
+        )
+
+        if kv_transfer_params is not None and "disagg_spec" in kv_transfer_params:
+            req_disagg_spec = kv_transfer_params["disagg_spec"]
+
+            receiver_id = req_disagg_spec["receiver_host"] + str(
+                req_disagg_spec["receiver_init_port"]
+            )
+
+            disagg_spec = DisaggSpec(
+                req_id=req_disagg_spec["req_id"],
+                receiver_id=receiver_id,
+                receiver_host=req_disagg_spec["receiver_host"],
+                receiver_init_port=req_disagg_spec["receiver_init_port"],
+                receiver_alloc_port=req_disagg_spec["receiver_alloc_port"],
+                receiver_query_port=req_disagg_spec.get("receiver_query_port"),
+            )
+
+            tmp_disagg_tracker[request.request_id] = disagg_spec
+        self._unfinished_requests[request.request_id] = request
+
+        if request.request_id not in self.load_specs:
+            # No KV tokens from external KV cache, return
+            return
+
+        if num_external_tokens == 0:
+            # No need to load anything
+            self.load_specs[request.request_id].can_load = False
+            return
+
+        recalc_last = (
+            1
+            if (
+                self.load_specs[request.request_id].lmcache_cached_tokens
+                == request.num_tokens
+            )
+            else 0
+        )
+        assert (
+            num_external_tokens
+            == self.load_specs[request.request_id].lmcache_cached_tokens
+            - self.load_specs[request.request_id].vllm_cached_tokens
+            - recalc_last
+        ), (
+            f"Mismatch in tokens to load: {num_external_tokens} vs "
+            f"{self.load_specs[request.request_id].lmcache_cached_tokens} "
+            "(tokens in lmcache) - "
+            f"{self.load_specs[request.request_id].vllm_cached_tokens} "
+            "(tokens in vllm) - "
+            f"{recalc_last} "
+            "(full lmcache hits subtracts last token to recalculate logits)"
+            f" for request {request.request_id}"
+        )
+
+        self.load_specs[request.request_id].can_load = True
+
+    @_lmcache_nvtx_annotate
+    def build_connector_meta(
+        self, scheduler_output: SchedulerOutput
+    ) -> KVConnectorMetadata:
+        """Attach the connector metadata to the request object.
+
+        This function should NOT modify other fields in the scheduler_output
+        except the `kv_connector_metadata` field.
+        Also, calling this function will reset the state of the connector.
+
+        Args:
+            scheduler_output (SchedulerOutput): the scheduler output object.
+        """
+
+        # Degraded mode (LMCache init failed): no lookup client means no load specs
+        # were ever recorded, so return empty metadata for the worker-side hooks.
+        if self.lookup_client is None:
+            return LMCacheConnectorMetadata()
+
+        force_skip_save = self.kv_role == "kv_consumer" or self.force_skip_save
+
+        meta = LMCacheConnectorMetadata()
+
+        for finished_req_id in scheduler_output.finished_req_ids:
+            self._request_trackers.pop(finished_req_id, None)
+            self._unfinished_requests.pop(finished_req_id, None)
+
+        # We should load KV for:
+        # 1. new requests
+        # 2. preempted requests (once per recovery)
+        # can_load will only be True if `update_state_after_alloc` has been called
+        # which only happens when vLLM's KV manager has space to receive KV from LMCache
+        for request in scheduler_output.scheduled_new_reqs:
+            # Ignore DP attention mock requests
+            if request.req_id.startswith("mock_req"):
+                continue
+            load_spec = self.load_specs.pop(request.req_id, None)
+            num_tokens_to_compute = (
+                request.num_computed_tokens
+                + scheduler_output.num_scheduled_tokens[request.req_id]
+            )
+            lmcache_cached_tokens = 0
+            if load_spec is not None:
+                lmcache_cached_tokens = load_spec.lmcache_cached_tokens
+            request_priority = self._requests_priority.pop(request.req_id, 0)
+
+            skip_save = force_skip_save or (
+                self.config.priority_limit is not None
+                and request_priority > self.config.priority_limit
+            )
+
+            request_tracker = RequestTracker.from_new_request(
+                self.config,
+                request,
+                num_tokens_to_compute,
+                lmcache_cached_tokens,
+                skip_save,
+            )
+            self._request_trackers[request.req_id] = request_tracker
+
+            req_meta = ReqMeta.from_request_tracker(
+                request_tracker,
+                self._block_size,
+                self._lmcache_chunk_size,
+                load_spec=load_spec,
+                discard_partial_chunks=self._discard_partial_chunks,
+                save_decode_cache=self.config.save_decode_cache,
+            )
+            if req_meta is not None:
+                meta.add_request(req_meta)
+
+        cached_reqs = scheduler_output.scheduled_cached_reqs
+
+        # NOTE: For backward compatibility with vllm version < 0.9.2,
+        # In the latest vllm version, the type of scheduled_cached_reqs has
+        # changed from list to object `CachedRequestData`
+        if isinstance(cached_reqs, list):
+            for i, req in enumerate(cached_reqs):
+                load_spec = self.load_specs.pop(req.req_id, None)
+                lmcache_cached_tokens = 0
+                vllm_cached_tokens = 0
+                if load_spec is not None:
+                    lmcache_cached_tokens = load_spec.lmcache_cached_tokens
+                    vllm_cached_tokens = load_spec.vllm_cached_tokens
+                request_tracker = self._request_trackers[req.req_id]
+
+                # Pass all_token_ids for preempted requests to restore
+                # token_ids correctly for chunk key computation
+                all_token_ids = None
+                if req.resumed_from_preemption:
+                    vllm_request = self._unfinished_requests.get(req.req_id)
+                    assert vllm_request is not None, (
+                        f"Preempted request {req.req_id} not found "
+                        "in _unfinished_requests"
+                    )
+                    all_token_ids = list(vllm_request.all_token_ids)
+
+                request_tracker.update(
+                    req.new_token_ids,
+                    req.new_block_ids,
+                    req.resumed_from_preemption,
+                    lmcache_cached_tokens=lmcache_cached_tokens,
+                    vllm_cached_tokens=vllm_cached_tokens,
+                    all_token_ids=all_token_ids,
+                )
+
+                req_meta = ReqMeta.from_request_tracker(
+                    request_tracker,
+                    self._block_size,
+                    self._lmcache_chunk_size,
+                    load_spec=load_spec,
+                    discard_partial_chunks=self._discard_partial_chunks,
+                    save_decode_cache=self.config.save_decode_cache,
+                )
+                if req_meta is not None:
+                    meta.add_request(req_meta)
+            return meta
+
+        for i, req_id in enumerate(cached_reqs.req_ids):
+            request_tracker = self._request_trackers[req_id]
+            num_new_tokens = scheduler_output.num_scheduled_tokens[req_id]
+            # TODO: this is a dangerous reference to the request object inside vllm
+            if request := self._unfinished_requests.get(req_id):
+                num_current_tokens = request.num_computed_tokens
+                # tracker_len < num_computed_tokens during decode
+                #   (important for save_decode_cache).
+                # num_computed_tokens < tracker_len after preemption.
+                tracker_len = len(request_tracker.token_ids)
+                slice_base = min(num_current_tokens, tracker_len)
+                new_token_ids = request.all_token_ids[
+                    slice_base : slice_base + num_new_tokens
+                ]
+            else:
+                raise ValueError(
+                    f"Request {req_id} is not in _unfinished_requests, "
+                    f"but it is scheduled to be cached"
+                )
+            new_block_ids = cached_reqs.new_block_ids[i]
+
+            load_spec = self.load_specs.pop(req_id, None)
+            lmcache_cached_tokens = 0
+            vllm_cached_tokens = 0
+            if load_spec is not None:
+                lmcache_cached_tokens = load_spec.lmcache_cached_tokens
+                vllm_cached_tokens = load_spec.vllm_cached_tokens
+
+            # Handle both old and new versions of CachedRequestData
+            if hasattr(cached_reqs, "resumed_req_ids"):
+                # New version with resumed_req_ids
+                preempted = req_id in cached_reqs.resumed_req_ids
+            elif hasattr(cached_reqs, "resumed_from_preemption"):
+                # Old version with resumed_from_preemption
+                preempted = cached_reqs.resumed_from_preemption[i]
+            else:
+                # This case should not be reached with supported vLLM versions.
+                # Raising an error is safer than assuming not preempted.
+                raise AttributeError(
+                    f"Unable to determine preemption status for request {req_id}. "
+                    f"This might be due to an unsupported vLLM version."
+                )
+            if preempted:
+                assert load_spec is not None, (
+                    f"Request {req_id} is preempted but was not given a load spec"
+                )
+                # num_computed_tokens should be reset to 0 during preemption
+                # and then set to the number of already cached tokens (maxxing
+                # prefix caching and lmcache)
+                # this assumption is crucial for the update() call of RequestTracker
+                # On full cache hit, get_num_new_matched_tokens subtracts 1
+                # to force last-token recomputation. This only affects
+                # num_computed_tokens when lmcache has all tokens AND
+                # provides more than vLLM's local cache.
+                expected = max(lmcache_cached_tokens, load_spec.vllm_cached_tokens)
+                full_hit_adj = (
+                    lmcache_cached_tokens == len(request.all_token_ids)
+                    and lmcache_cached_tokens > load_spec.vllm_cached_tokens
+                )
+                if full_hit_adj:
+                    expected -= 1
+                assert request.num_computed_tokens == expected, (
+                    f"Preempted request {req_id} has "
+                    f"num_computed_tokens {request.num_computed_tokens} "
+                    f"but expected {expected} "
+                    f"(full_hit_adj={full_hit_adj})"
+                )
+
+            # When retrieve fail, vllm will call _handle_invalid_blocks to
+            # reset request.num_computed_tokens, this will lead to
+            # request_tracker.token_ids being not matched with vllm
+            if num_current_tokens < len(request_tracker.token_ids):
+                logger.warning(
+                    "Request %s rolled back from %d to %d tokens; "
+                    "truncating tracker state.",
+                    req_id,
+                    len(request_tracker.token_ids),
+                    num_current_tokens,
+                )
+                num_token_slots = (
+                    len(request_tracker.allocated_block_ids) * self._block_size
+                )
+                tokens_to_keep = num_current_tokens
+                if num_token_slots < num_current_tokens:
+                    logger.warning(
+                        "Request %s tracker has %d token slots but %d tokens; "
+                        "capping token_ids to slot capacity.",
+                        req_id,
+                        num_token_slots,
+                        num_current_tokens,
+                    )
+                    tokens_to_keep = num_token_slots
+
+                request_tracker.token_ids = list(request.all_token_ids[:tokens_to_keep])
+                request_tracker.num_saved_tokens = min(
+                    request_tracker.num_saved_tokens, tokens_to_keep
+                )
+
+            # Pass all_token_ids for preempted requests to restore
+            # token_ids correctly for chunk key computation
+            all_token_ids = list(request.all_token_ids) if preempted else None
+
+            request_tracker.update(
+                new_token_ids,
+                new_block_ids,
+                preempted=preempted,
+                lmcache_cached_tokens=lmcache_cached_tokens,
+                vllm_cached_tokens=vllm_cached_tokens,
+                all_token_ids=all_token_ids,
+            )
+
+            req_meta = ReqMeta.from_request_tracker(
+                request_tracker,
+                self._block_size,
+                self._lmcache_chunk_size,
+                load_spec=load_spec,
+                discard_partial_chunks=self._discard_partial_chunks,
+                save_decode_cache=self.config.save_decode_cache,
+            )
+            if req_meta is not None:
+                meta.add_request(req_meta)
+
+        return meta
+
+    @_lmcache_nvtx_annotate
+    def request_finished(
+        self,
+        request: "Request",
+        block_ids: list[int],
+    ) -> tuple[bool, Optional[dict[str, Any]]]:
+        # Layerwise save uses request-scoped generators. If request finishes
+        # without entering wait_for_save (abort/error/evict path), make sure
+        # we release the generator entry to avoid leaking state.
+        if getattr(self, "use_layerwise", False) and hasattr(
+            self, "_layerwise_save_storers"
+        ):
+            self._layerwise_save_storers.pop(request.request_id, None)
+
+        # Cleanup if request was aborted. The per-branch logic below already
+        # degrades gracefully when ``lmcache_engine`` and/or ``lookup_client``
+        # are missing (it warns and skips only the unavailable backend), so we
+        # must not short-circuit the whole method here -- doing so would drop
+        # the storage/lookup cancels that still need to run when just one of
+        # the two is present. See LMCache#3337.
+        if request.status == RequestStatus.FINISHED_ABORTED:
+            # ``request_finished`` is a Scheduler-side connector API.
+            # The Scheduler typically does not initialize the storage
+            # engine (unless ``enable_scheduler_bypass_lookup`` is set);
+            # only the Worker role builds it by default. The Scheduler
+            # *does* own the lookup_client though, so the async lookup
+            # cancel below must run independently of the engine check
+            # to avoid leaking in-flight async lookups on Scheduler-side
+            # aborts. See LMCache#3337.
+            if self.lmcache_engine is None:
+                logger.warning(
+                    "Skipping abort-time backend cleanup for request %s: "
+                    "lmcache_engine is not initialized (Scheduler role "
+                    "without enable_scheduler_bypass_lookup).",
+                    request.request_id,
+                )
+            else:
+                # Notify storage backends of aborted requests
+                sm = self.lmcache_engine.storage_manager
+                if sm is not None:
+                    sm.cancel_request(request.request_id)
+
+            if self.async_loading:
+                # Cancel any ongoing async lookup and prefetch tasks on
+                # workers. Independent of ``lmcache_engine`` because the
+                # Scheduler owns ``lookup_client`` even when it does not
+                # build an engine.
+                lookup_id = request.request_id
+                if self.lookup_client is None:
+                    logger.warning(
+                        "Skipping abort-time async lookup cancel for "
+                        "request %s: lookup_client is not initialized "
+                        "while async_loading is enabled. Engine stays "
+                        "alive; this request's lookup is dropped.",
+                        request.request_id,
+                    )
+                else:
+                    self.lookup_client.cancel_lookup(lookup_id)  # type: ignore[attr-defined]
+
+        params = (
+            request.kv_transfer_params
+            if hasattr(request, "kv_transfer_params")
+            else None
+        )
+        return_params = None
+
+        # NOTE: Used to stream back the first token
+        # for disagg prefill
+        if params is not None and "ret_first_tok" in params:
+            return_params = {
+                "first_tok": request._output_token_ids[0],
+            }
+
+        if self.config.get_extra_config_value(
+            "enable_cache_usage_details_in_response", False
+        ):
+            request_tracker = self._request_trackers.get(request.request_id)
+            if request_tracker:
+                return_params = return_params or {}
+                return_params["num_lmcache_cached_tokens"] = (
+                    request_tracker.num_lmcache_cached_tokens
+                )
+
+        return False, return_params
+
+    @_lmcache_nvtx_annotate
+    def get_kv_events(self) -> Iterable[CacheStoreEvent]:
+        if self.lmcache_engine is not None:
+            return self.lmcache_engine.get_kv_events()
+        return []
diff --git a/lmcache/lmcache_frontend/__init__.py b/lmcache/lmcache_frontend/__init__.py
new file mode 100644
index 0000000..d8ca5f1
--- /dev/null
+++ b/lmcache/lmcache_frontend/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# This file makes the directory a Python package
diff --git a/lmcache/lmcache_frontend/app.py b/lmcache/lmcache_frontend/app.py
new file mode 100644
index 0000000..e5aac70
--- /dev/null
+++ b/lmcache/lmcache_frontend/app.py
@@ -0,0 +1,1036 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from importlib import resources
+from urllib.parse import unquote
+import argparse
+import asyncio
+import json
+import os
+import threading
+import time
+
+# Third Party
+from fastapi import APIRouter, FastAPI, HTTPException, Request
+from fastapi.staticfiles import StaticFiles
+from starlette.responses import FileResponse, PlainTextResponse
+import httpx
+import uvicorn
+
+_PACKAGE = "lmcache.lmcache_frontend"
+
+
+def _package_resource_path(relative: str) -> str:
+    """Return absolute filesystem path for a file shipped inside the package.
+
+    Replacement for the deprecated ``pkg_resources.resource_filename``;
+    works for regular (non-zipped) installs, which is how LMCache ships.
+    """
+    return str(resources.files(_PACKAGE).joinpath(relative))
+
+
+try:
+    # Local
+    from .heartbeat import HeartbeatService  # import as module
+except ImportError:
+    # Third Party
+    from heartbeat import HeartbeatService  # type: ignore  # import as script
+
+
+# Create router
+router = APIRouter()
+
+
+class _NodeRegistry:
+    """Encapsulates the mutable proxy/node list used by the frontend.
+
+    Replacing the list is done in-place via :py:meth:`replace` so that
+    aliases (the module-level ``target_nodes`` reference and the list
+    handed to ``HeartbeatService``) stay in sync.
+    """
+
+    def __init__(self) -> None:
+        self._nodes: list[dict] = []
+
+    @property
+    def nodes(self) -> list[dict]:
+        """Return the underlying list (mutated in place)."""
+        return self._nodes
+
+    def replace(self, new_nodes: list[dict]) -> None:
+        """Swap the registry content in place with ``new_nodes``."""
+        self._nodes[:] = new_nodes
+
+    def is_allowed(self, host: str, port: str) -> bool:
+        """Return True if ``host:port`` matches any registered node.
+
+        Used by the SSRF guard in :func:`proxy_request` so the proxy
+        only forwards to pre-registered destinations.
+        """
+        return self.resolve(host, port) is not None
+
+    def resolve(self, host: str, port: str) -> tuple[str, str] | None:
+        """Return the registry-owned ``(host, port)`` matching the input.
+
+        The returned tuple is taken from the registry itself, not from
+        the caller-supplied arguments.  Using this value to build the
+        outbound URL breaks the SSRF taint flow for static analysers.
+        """
+        port = str(port)
+        for proxy in self._nodes:
+            p_host, p_port = str(proxy.get("host")), str(proxy.get("port"))
+            if p_host == host and p_port == port:
+                return p_host, p_port
+            for child in proxy.get("nodes", []):
+                c_host, c_port = str(child.get("host")), str(child.get("port"))
+                if c_host == host and c_port == port:
+                    return c_host, c_port
+        return None
+
+
+_node_registry = _NodeRegistry()
+# ``target_nodes`` is a module-level alias to the list owned by the
+# registry.  External readers and in-place mutations (append / element
+# update) keep working unchanged; whole-list replacement MUST go
+# through ``_node_registry.replace`` so all aliases stay in sync.
+target_nodes = _node_registry.nodes
+
+# Initialize heartbeat service with app context
+heartbeat_service: HeartbeatService = HeartbeatService()
+
+global args
+args = None
+
+
+async def fetch_child_nodes_from_proxy(proxy_node: dict) -> list[dict]:
+    """Fetch child nodes from a single proxy node.
+
+    Args:
+        proxy_node: Proxy dict with ``name``/``host``/``port`` keys.
+            ``/api/nodes`` of the proxy is queried.
+
+    Returns:
+        A list of leaf node dicts discovered from the proxy.  An
+        empty list is returned when the request fails.
+    """
+    try:
+        url = f"http://{proxy_node['host']}:{proxy_node['port']}/api/nodes"
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            return_nodes = []
+            added_names = set()  # Track node names to avoid duplicates
+            nodes = response.json().get("nodes", [])
+
+            # Process each node: only add leaf nodes (nodes without children)
+            for node in nodes:
+                if node.get("children"):
+                    # If node has children, add only the children (leaf nodes)
+                    for child in node["children"]:
+                        # Skip if already added
+                        if child["name"] in added_names:
+                            continue
+                        child["proxy_id"] = proxy_node["name"]
+                        return_nodes.append(child)
+                        added_names.add(child["name"])
+                else:
+                    # Skip if already added
+                    if node["name"] in added_names:
+                        continue
+                    node["proxy_id"] = proxy_node["name"]
+                    return_nodes.append(node)
+                    added_names.add(node["name"])
+            return return_nodes
+    except Exception as e:
+        print(f"Failed to fetch nodes from proxy {proxy_node['name']}: {e}")
+        return []
+
+
+async def fetch_all_child_nodes_concurrently(
+    proxy_nodes: list[dict],
+) -> list[dict]:
+    """Fetch child nodes from multiple proxy nodes concurrently.
+
+    Args:
+        proxy_nodes: Proxy dicts to query.  Each dict is mutated in
+            place with a new ``nodes`` field.
+
+    Returns:
+        The same ``proxy_nodes`` list with ``nodes`` populated.
+    """
+    tasks = [fetch_child_nodes_from_proxy(proxy) for proxy in proxy_nodes]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    # Process results and handle exceptions
+    for i, result in enumerate(results):
+        if isinstance(result, Exception):
+            print(f"Error fetching nodes from proxy {proxy_nodes[i]['name']}: {result}")
+            proxy_nodes[i]["nodes"] = []
+        else:
+            proxy_nodes[i]["nodes"] = result
+
+    return proxy_nodes
+
+
+async def _fetch_child_nodes_from_api_nodes(
+    host: str, port: str, proxy_name: str
+) -> list:
+    """Try to fetch child nodes via /api/nodes from a multiProcess server.
+
+    Returns a non-empty list of child node dicts when the target is a
+    multiProcess lmcache server that exposes /api/nodes.  Returns an
+    empty list for inProcess nodes (connection error or no children).
+    """
+    try:
+        url = "http://%s:%s/api/nodes" % (host, port)
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+        nodes_data = response.json().get("nodes", [])
+        children = []
+        for node in nodes_data:
+            if node.get("children"):
+                for child in node["children"]:
+                    child["proxy_id"] = proxy_name
+                    children.append(child)
+            else:
+                node["proxy_id"] = proxy_name
+                children.append(node)
+        return children
+    except Exception:
+        return []
+
+
+async def fetch_nodes_from_supplier(url: str) -> list[dict]:
+    """Fetch node information from node supplier.
+
+    For each discovered node, attempt to retrieve its child nodes via
+    ``/api/nodes`` (multiProcess lmcache server).  If that call
+    succeeds and returns children, those children are used as the
+    ``nodes`` list (multiProcess mode).  Otherwise the node itself is
+    used as the sole child (inProcess / leaf mode).
+    """
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get(url)
+            response.raise_for_status()
+            data = response.json()
+
+            unique_nodes: dict[str, dict] = {}
+            for api_address, info in data.get("processInfos", {}).items():
+                for entity in info.get("lmCacheInfoEntities", []):
+                    addr = entity["apiAddress"]
+                    if addr.startswith("http://"):
+                        addr = addr[7:]
+                    host, port = addr.split(":")
+                    node_key = "%s:%s" % (host, port)
+                    if node_key not in unique_nodes:
+                        unique_nodes[node_key] = {
+                            "host": host,
+                            "port": port,
+                        }
+
+            # Fetch child nodes concurrently for all discovered nodes.
+            proxy_list = [
+                {
+                    "name": "proxy_%s" % node_key.replace(":", "_"),
+                    "host": info["host"],
+                    "port": info["port"],
+                }
+                for node_key, info in unique_nodes.items()
+            ]
+            child_tasks = [
+                _fetch_child_nodes_from_api_nodes(p["host"], p["port"], p["name"])
+                for p in proxy_list
+            ]
+            child_results = await asyncio.gather(*child_tasks, return_exceptions=True)
+
+            result = []
+            for proxy, children in zip(proxy_list, child_results, strict=False):
+                if isinstance(children, Exception) or not children:
+                    # inProcess mode: node itself is the leaf target.
+                    leaf = {
+                        "name": proxy["name"],
+                        "host": proxy["host"],
+                        "port": proxy["port"],
+                    }
+                    nodes = [leaf]
+                else:
+                    # multiProcess mode: use discovered child nodes.
+                    assert not isinstance(children, BaseException)
+                    nodes = children
+                result.append(
+                    {
+                        "name": proxy["name"],
+                        "host": proxy["host"],
+                        "port": proxy["port"],
+                        "nodes": nodes,
+                    }
+                )
+            return result
+    except Exception as e:
+        print(f"Failed to fetch nodes from supplier: {e}")
+        return []
+
+
+def load_config(config_path: str | None = None) -> None:
+    """Load proxy/node list from a JSON config file.
+
+    Args:
+        config_path: Optional path to the JSON file.  When ``None`` the
+            packaged ``config.json`` is used.
+    """
+    try:
+        # Prioritize user-specified configuration file
+        if config_path:
+            with open(config_path, "r") as f:
+                _node_registry.replace(json.load(f))
+            print(
+                f"Loaded {len(target_nodes)} target nodes from specified path: "
+                f"{config_path}"
+            )
+        else:
+            # Use package resource path as default configuration
+            default_config_path = _package_resource_path("config.json")
+            with open(default_config_path, "r") as f:
+                _node_registry.replace(json.load(f))
+            print(f"Loaded default configuration with {len(target_nodes)} target nodes")
+    except Exception as e:
+        print(f"Failed to load configuration file: {e}")
+        _node_registry.replace([])
+
+
+def validate_node(node: dict, is_proxy: bool = False) -> bool:
+    """Validate a single node configuration dict.
+
+    Args:
+        node: Candidate node dict.
+        is_proxy: Reserved for future proxy-specific validation.
+
+    Returns:
+        True when ``node`` has the required ``name``/``host``/``port``
+        keys and (optionally) a string ``proxy_id``.
+    """
+    if not isinstance(node, dict):
+        return False
+
+    required_keys = {"name", "host", "port"}
+    if not required_keys.issubset(node.keys()):
+        return False
+
+    if "proxy_id" in node and node["proxy_id"]:
+        if not isinstance(node["proxy_id"], str):
+            return False
+
+    return True
+
+
+def validate_nodes(nodes: list) -> bool:
+    """Validate a list of node dicts; see :func:`validate_node`."""
+    if not isinstance(nodes, list):
+        return False
+
+    return all(validate_node(node) for node in nodes)
+
+
+@router.get("/api/nodes")
+async def get_all_nodes() -> dict:
+    """Get all nodes in tree structure (proxies with their child nodes).
+
+    Returns:
+        ``{"nodes": [...]}`` where each element is a proxy dict whose
+        ``children`` list contains the leaf nodes behind it.
+    """
+    all_nodes = []
+    for proxy in target_nodes:
+        # Create proxy node with children property
+        proxy_node = {
+            "id": f"proxy_{proxy['name']}",
+            "name": proxy["name"],
+            "host": proxy["host"],
+            "port": proxy["port"],
+            "is_proxy": True,
+            "children": [],
+        }
+
+        # Add child nodes
+        for node in proxy.get("nodes", []):
+            proxy_node["children"].append(
+                {
+                    "id": "node_%s" % node["name"],
+                    "name": node["name"],
+                    "host": node["host"],
+                    "port": node["port"],
+                    "is_proxy": False,
+                    "proxy_id": proxy["name"],
+                }
+            )
+
+        all_nodes.append(proxy_node)
+
+    return {"nodes": all_nodes}
+
+
+@router.get("/api/proxies/{proxy_name}/refresh")
+async def refresh_proxy_nodes(proxy_name: str):
+    """Refresh child nodes of a proxy"""
+    proxy = next((p for p in target_nodes if p["name"] == proxy_name), None)
+    if not proxy:
+        raise HTTPException(status_code=404, detail="Proxy not found")
+
+    try:
+        child_nodes = await fetch_child_nodes_from_proxy(proxy)
+        proxy["nodes"] = child_nodes
+        return {"status": "success", "nodes": child_nodes}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.get("/api/proxies")
+async def get_proxies():
+    """Get all proxy nodes (without child nodes)"""
+    proxies = [
+        {"name": proxy["name"], "host": proxy["host"], "port": proxy["port"]}
+        for proxy in target_nodes
+    ]
+    return {"proxies": proxies}
+
+
+@router.get("/api/proxies/{proxy_name}/nodes")
+async def get_proxy_nodes(proxy_name: str):
+    """Get all nodes under specified proxy"""
+    proxy = next((p for p in target_nodes if p["name"] == proxy_name), None)
+    if not proxy:
+        raise HTTPException(status_code=404, detail="Proxy not found")
+    return {"nodes": proxy["nodes"]}
+
+
+# ==== Node Management Endpoints ====
+@router.post("/api/proxies")
+async def add_proxy(request: Request):
+    """Add a new proxy node"""
+    try:
+        new_proxy = await request.json()
+        if not validate_node(new_proxy, is_proxy=True):
+            raise HTTPException(status_code=400, detail="Invalid proxy format")
+
+        # Check for duplicate names
+        if any(proxy["name"] == new_proxy["name"] for proxy in target_nodes):
+            raise HTTPException(status_code=409, detail="Proxy name already exists")
+
+        # Ensure nodes field exists
+        if "nodes" not in new_proxy:
+            new_proxy["nodes"] = []
+
+        target_nodes.append(new_proxy)
+        return {"status": "success", "message": "Proxy added"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.post("/api/proxies/{proxy_name}/nodes")
+async def add_node_to_proxy(proxy_name: str, request: Request):
+    """Add child node to proxy"""
+    try:
+        new_node = await request.json()
+        if not validate_node(new_node):
+            raise HTTPException(status_code=400, detail="Invalid node format")
+
+        # Find corresponding proxy
+        proxy = next((p for p in target_nodes if p["name"] == proxy_name), None)
+        if not proxy:
+            raise HTTPException(status_code=404, detail="Proxy not found")
+
+        # Check for duplicate names
+        if any(node["name"] == new_node["name"] for node in proxy["nodes"]):
+            raise HTTPException(status_code=409, detail="Node name already exists")
+
+        proxy["nodes"].append(new_node)
+        return {"status": "success", "message": "Node added to proxy"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.put("/api/nodes/{node_name}")
+async def update_node(node_name: str, request: Request):
+    """Update a proxy or child node identified by ``node_name``.
+
+    Searches top-level proxies first, then children of every proxy,
+    so both direct proxies and supplier-discovered leaf nodes can be
+    updated through the same endpoint (mirrors ``proxy_request_by_name``).
+    """
+    try:
+        updated_node = await request.json()
+        if not validate_node(updated_node):
+            raise HTTPException(status_code=400, detail="Invalid node format")
+
+        for i, node in enumerate(target_nodes):
+            if node["name"] == node_name:
+                # Preserve existing children when the caller did not
+                # provide one; proxies are expected to keep ``nodes``.
+                if "nodes" not in updated_node and "nodes" in node:
+                    updated_node["nodes"] = node["nodes"]
+                target_nodes[i] = updated_node
+                return {"status": "success", "message": "Node updated"}
+
+        for proxy in target_nodes:
+            children = proxy.get("nodes", [])
+            for j, child in enumerate(children):
+                if child["name"] == node_name:
+                    children[j] = updated_node
+                    return {
+                        "status": "success",
+                        "message": "Child node updated",
+                    }
+
+        raise HTTPException(status_code=404, detail="Node not found")
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.delete("/api/nodes/{node_name}")
+async def delete_node(node_name: str):
+    """Delete a proxy or child node by ``node_name``.
+
+    Mirrors :func:`update_node`: matches top-level proxies first,
+    falls back to scanning children of each proxy.
+    """
+    try:
+        original_count = len(target_nodes)
+        _node_registry.replace(
+            [node for node in target_nodes if node["name"] != node_name]
+        )
+
+        if len(target_nodes) != original_count:
+            return {"status": "success", "message": "Node deleted"}
+
+        for proxy in target_nodes:
+            children = proxy.get("nodes", [])
+            for idx, child in enumerate(children):
+                if child["name"] == node_name:
+                    del children[idx]
+                    return {
+                        "status": "success",
+                        "message": "Child node deleted",
+                    }
+
+        raise HTTPException(status_code=404, detail="Node not found")
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.api_route(
+    "/proxy2/{node_name}/{path:path}",
+    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"],
+)
+async def proxy_request_by_name(request: Request, node_name: str, path: str):
+    """Proxy requests using node name as identifier.
+
+    Searches top-level target_nodes first, then child nodes of every
+    proxy, so both direct nodes and supplier-discovered leaf nodes are
+    reachable with a single /proxy2/{name}/{path} call.
+    """
+    # 1. top-level proxy nodes
+    node = next((n for n in target_nodes if n["name"] == node_name), None)
+
+    # 2. child nodes of every proxy
+    if not node:
+        for proxy in target_nodes:
+            node = next(
+                (n for n in proxy.get("nodes", []) if n["name"] == node_name),
+                None,
+            )
+            if node:
+                break
+
+    if not node:
+        raise HTTPException(
+            status_code=404, detail=f"Node with name '{node_name}' not found"
+        )
+
+    # Use existing proxy_request logic
+    return await proxy_request(
+        request, target_host=node["host"], target_port_or_socket=node["port"], path=path
+    )
+
+
+@router.api_route(
+    "/proxy/{target_host}/{target_port_or_socket}/{path:path}",
+    methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"],
+)
+async def proxy_request(
+    request: Request, target_host: str, target_port_or_socket: str | int, path: str
+):
+    """Proxy requests to the specified target host and port or socket path.
+
+    For security, non-socket targets must match a host/port already
+    registered in :data:`_node_registry`; this prevents the endpoint
+    from being used as an open relay (SSRF).  Socket paths are
+    accepted as-is because they are local UDS endpoints.
+    """
+    target_port_or_socket = unquote(str(target_port_or_socket))
+    # Check if target_port_or_socket is a socket path (contains '/')
+    is_socket_path = "/" in target_port_or_socket
+
+    if is_socket_path:
+        # For socket paths, use UDS transport
+        socket_path = target_port_or_socket
+        target_url = f"http://localhost/{path}"
+
+        # Create UDS transport
+        transport = httpx.AsyncHTTPTransport(uds=socket_path)
+    else:
+        port = target_port_or_socket
+        # SSRF guard: resolve against the registry and reuse the
+        # trusted host/port from there when building the outbound URL.
+        # This keeps user-controlled values out of the URL sink.
+        resolved = _node_registry.resolve(target_host, port)
+        if resolved is None:
+            raise HTTPException(
+                status_code=403,
+                detail=("Target %s:%s is not a registered node" % (target_host, port)),
+            )
+        safe_host, safe_port = resolved
+        target_url = f"http://{safe_host}:{safe_port}/{path}"
+        transport = None  # Use default transport
+
+    headers = {}
+    for key, value in request.headers.items():
+        if key.lower() in [
+            "host",
+            "content-length",
+            "connection",
+            "keep-alive",
+            "proxy-authenticate",
+            "proxy-authorization",
+            "te",
+            "trailers",
+            "transfer-encoding",
+            "upgrade",
+        ]:
+            continue
+        headers[key] = value
+
+    body = await request.body()
+
+    # Create client with appropriate transport
+    async with httpx.AsyncClient(transport=transport) as client:
+        try:
+            response = await client.request(
+                method=request.method,
+                url=target_url,
+                headers=headers,
+                content=body,
+                params=request.query_params,
+                timeout=60.0,
+            )
+
+            response_headers = {}
+            for key, value in response.headers.items():
+                if key.lower() in [
+                    "connection",
+                    "keep-alive",
+                    "proxy-authenticate",
+                    "proxy-authorization",
+                    "te",
+                    "trailers",
+                    "transfer-encoding",
+                    "upgrade",
+                ]:
+                    continue
+                response_headers[key] = value
+
+            return PlainTextResponse(
+                content=response.content,
+                headers=response_headers,
+                media_type=response.headers.get("content-type", "text/plain"),
+                status_code=response.status_code,
+            )
+
+        except httpx.ConnectError as e:
+            if is_socket_path:
+                detail = f"Failed to connect to socket: {socket_path}"
+            else:
+                detail = f"Failed to connect to target service {target_host}:{port}"
+            raise HTTPException(status_code=502, detail=detail) from e
+        except httpx.TimeoutException as e:
+            if is_socket_path:
+                detail = f"Connection to socket {socket_path} timed out"
+            else:
+                detail = f"Connection to target service {target_host}:{port} timed out"
+            raise HTTPException(status_code=504, detail=detail) from e
+        except httpx.HTTPError as e:
+            raise HTTPException(
+                status_code=502,
+                detail=f"Error communicating with target service: {str(e)}",
+            ) from e
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Proxy error: {str(e)}") from e
+
+
+@router.get("/health")
+async def health_check():
+    return {"status": "healthy", "service": "lmcache-monitor"}
+
+
+@router.get("/api/heartbeat/status")
+async def get_heartbeat_status():
+    """Get heartbeat status"""
+    return heartbeat_service.status()
+
+
+@router.post("/api/heartbeat/start")
+async def start_heartbeat_api(request: Request):
+    """Start heartbeat service"""
+    try:
+        data = await request.json()
+        heartbeat_url = data.get("heartbeat_url")
+        initial_delay = data.get("initial_delay", 0)
+        interval = data.get("interval", 30)
+
+        if not heartbeat_url:
+            raise HTTPException(status_code=400, detail="heartbeat_url is required")
+
+        heartbeat_service.start(heartbeat_url, initial_delay, interval)
+        return {"status": "success", "message": "Heartbeat service started"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+@router.post("/api/heartbeat/stop")
+async def stop_heartbeat_api():
+    """Stop heartbeat service"""
+    try:
+        heartbeat_service.stop()
+        return {"status": "success", "message": "Heartbeat service stopped"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from e
+
+
+async def load_nodes_from_supplier(node_supplier_url: str | None = None) -> bool:
+    """Load node information from node supplier.
+
+    Args:
+        node_supplier_url: Discovery service URL, e.g. ``/lmcache_infos``.
+
+    Returns:
+        ``True`` when a non-empty node list was retrieved and stored.
+    """
+    if not node_supplier_url:
+        return False
+
+    print(f"Fetching nodes from supplier: {node_supplier_url}")
+    nodes = await fetch_nodes_from_supplier(node_supplier_url)
+    if nodes:
+        _node_registry.replace(nodes)
+        print(f"Loaded {len(target_nodes)} proxy nodes from supplier")
+
+        # Child nodes are already populated by fetch_nodes_from_supplier;
+        # no secondary /api/nodes round-trip is needed.
+        for proxy in target_nodes:
+            print(f"Proxy {proxy['name']} loaded {len(proxy['nodes'])} child nodes")
+        return True
+    else:
+        print("Warning: No nodes loaded from supplier")
+        return False
+
+
+async def initialize_nodes(node_supplier_url: str | None = None) -> None:
+    """Initialize node configuration from CLI args or supplier URL.
+
+    Args:
+        node_supplier_url: Optional discovery service URL.  When set,
+            nodes are loaded via :func:`load_nodes_from_supplier`.
+            Otherwise falls back to ``args.nodes`` / ``args.config``.
+    """
+    global args
+
+    if args is None:
+        raise ValueError("args is not initialized")
+
+    if node_supplier_url:
+        await load_nodes_from_supplier(node_supplier_url)
+    elif args.nodes:
+        try:
+            nodes = json.loads(args.nodes)
+            if validate_nodes(nodes):
+                _node_registry.replace(
+                    [
+                        {
+                            "name": "local_proxy",
+                            "host": args.host,
+                            "port": args.port,
+                            "nodes": nodes,
+                        }
+                    ]
+                )
+                print(f"Loaded {len(nodes)} target nodes from command line arguments")
+        except json.JSONDecodeError:
+            print("Failed to parse nodes JSON parameter")
+    elif args.config:
+        load_config(args.config)
+
+
+# Minimum seconds between two supplier refreshes triggered by ``/``.
+# Each refresh fans out to every registered proxy's ``/api/nodes``
+# endpoint, so an unthrottled ``/`` would DOS both the supplier and
+# every proxy. 30s matches the default heartbeat interval.
+_SUPPLIER_REFRESH_INTERVAL_SEC = 30.0
+_supplier_last_refresh: float = 0.0
+_supplier_refresh_lock = asyncio.Lock()
+
+
+async def _maybe_refresh_from_supplier(node_supplier_url: str) -> None:
+    """Refresh the node registry from supplier, at most once per interval.
+
+    The first caller within the interval performs the refresh; other
+    concurrent callers return immediately (stale-on-read). This keeps
+    the homepage responsive even under high traffic.
+    """
+    global _supplier_last_refresh
+    now = time.monotonic()
+    if now - _supplier_last_refresh < _SUPPLIER_REFRESH_INTERVAL_SEC:
+        return
+    if _supplier_refresh_lock.locked():
+        return
+    async with _supplier_refresh_lock:
+        now = time.monotonic()
+        if now - _supplier_last_refresh < _SUPPLIER_REFRESH_INTERVAL_SEC:
+            return
+        await initialize_nodes(node_supplier_url)
+        _supplier_last_refresh = time.monotonic()
+
+
+@router.get("/")
+async def serve_frontend():
+    """Return frontend homepage.
+
+    When a node supplier URL is configured, trigger a throttled
+    background-style refresh so opening the homepage repeatedly does
+    not hammer the supplier or every proxy's ``/api/nodes``.
+    """
+    if args.node_supplier_url:
+        await _maybe_refresh_from_supplier(args.node_supplier_url)
+
+    try:
+        # Use package resource path
+        index_path = _package_resource_path("static/index.html")
+        return FileResponse(index_path)
+    except Exception:
+        # Development environment uses local files
+        return FileResponse("static/index.html")
+
+
+# Helper function to fetch metrics from a single node
+async def _fetch_node_metrics(node):
+    """Fetch metrics from a single node"""
+    try:
+        # Check if port is a socket path
+        is_socket_path = "/" in node["port"]
+
+        if is_socket_path:
+            # Use UDS transport for socket paths
+            transport = httpx.AsyncHTTPTransport(uds=node["port"])
+            # Use localhost as host
+            url = "http://localhost/metrics"
+            async with httpx.AsyncClient(transport=transport, timeout=5.0) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+                return response.text
+        else:
+            # Build URL for regular port
+            url = f"http://{node['host']}:{node['port']}/metrics"
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+                return response.text
+    except Exception as e:
+        return f"# ERROR: Failed to get metrics from {node['name']}: {str(e)}\n"
+
+
+@router.get("/metrics")
+async def aggregated_metrics():
+    """Aggregate /metrics from all leaf (child) nodes across every proxy.
+
+    Previously only nodes under the ``local_proxy`` entry were
+    aggregated, which silently returned nothing in supplier mode
+    (where proxy names follow the ``proxy_<host>_<port>`` pattern).
+    Now every proxy's ``nodes`` list is flattened.
+    """
+    if not target_nodes:
+        return PlainTextResponse("# No nodes configured\n", status_code=404)
+
+    nodes: list[dict] = []
+    seen: set[str] = set()
+    for proxy in target_nodes:
+        for child in proxy.get("nodes", []) or []:
+            # De-duplicate by name so the same leaf reported via
+            # multiple proxies is only scraped once.
+            name = child.get("name")
+            if name and name in seen:
+                continue
+            if name:
+                seen.add(name)
+            nodes.append(child)
+
+    if not nodes:
+        return PlainTextResponse(
+            "# No nodes available for metrics collection\n", status_code=404
+        )
+
+    metrics_results = await asyncio.gather(
+        *[_fetch_node_metrics(node) for node in nodes]
+    )
+
+    # Combine all metrics with node name as comment header
+    aggregated = ""
+    for i, metrics in enumerate(metrics_results):
+        node = nodes[i]
+        aggregated += (
+            f"# Metrics from node: {node['name']} ({node['host']}:{node['port']})\n"
+        )
+        aggregated += metrics
+        aggregated += "\n\n"
+
+    return PlainTextResponse(aggregated)
+
+
+def create_app():
+    """Create and configure FastAPI application"""
+    app = FastAPI(
+        title="Flexible Proxy Server",
+        description="HTTP proxy service supporting specified target hosts and ports",
+    )
+    app.include_router(router)
+
+    # Get static file path (prefer package resources)
+    try:
+        static_path = _package_resource_path("static")
+    except Exception:
+        static_path = os.path.join(os.path.dirname(__file__), "static")
+
+    # Mount static file service
+    app.mount("/static", StaticFiles(directory=static_path), name="static")
+
+    return app
+
+
+def main():
+    global args
+    parser = argparse.ArgumentParser(description="LMCache Cluster Monitoring Tool")
+    parser.add_argument(
+        "--port", type=int, default=8000, help="Service port, default 8000"
+    )
+    parser.add_argument(
+        "--host", type=str, default="0.0.0.0", help="Bind host address, default 0.0.0.0"
+    )
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Specify configuration file path, default uses internal config.json",
+    )
+    parser.add_argument(
+        "--nodes",
+        type=str,
+        default=None,
+        help="Directly specify target nodes as a JSON string. "
+        'Example: \'[{"name":"node1","host":"127.0.0.1","port":8001}]\'',
+    )
+    parser.add_argument(
+        "--heartbeat-url",
+        type=str,
+        default=None,
+        help="Heartbeat service URL, e.g.: http://example.com/heartbeat",
+    )
+    parser.add_argument(
+        "--heartbeat-initial-delay",
+        type=int,
+        default=0,
+        help="Initial delay before starting heartbeat (seconds), default 0",
+    )
+    parser.add_argument(
+        "--heartbeat-interval",
+        type=int,
+        default=30,
+        help="Heartbeat interval (seconds), default 30",
+    )
+    parser.add_argument(
+        "--node-supplier-url",
+        type=str,
+        default=None,
+        help="URL to fetch node information from, e.g.: http://example.com/lmcache_infos",
+    )
+    parser.add_argument(
+        "--log-level",
+        type=str,
+        default="warning",
+        choices=["critical", "error", "warning", "warn", "info", "debug", "trace"],
+        help="Uvicorn log level, default: warn",
+    )
+    parser.add_argument(
+        "--no-http",
+        action="store_true",
+        default=False,
+        help="Disable HTTP server startup (heartbeat still runs)",
+    )
+
+    args = parser.parse_args()
+
+    # Initialize node configuration
+    asyncio.run(initialize_nodes(args.node_supplier_url))
+
+    app = create_app()
+    print(f"Monitoring service running at http://{args.host}:{args.port}")
+    print(f"Node management: http://{args.host}:{args.port}/static/index.html")
+
+    # Start heartbeat service if URL is configured
+    if args.heartbeat_url:
+        # Set application configuration for heartbeat service
+        heartbeat_service.set_app_config(args.host, args.port, target_nodes)
+
+        print("Starting heartbeat service...")
+        print(f"Heartbeat URL: {args.heartbeat_url}")
+        print(f"Initial delay: {args.heartbeat_initial_delay}s")
+        print(f"Interval: {args.heartbeat_interval}s")
+        print(f"API Address: http://{args.host}:{args.port}")
+        print(f"Target nodes count: {len(target_nodes)}")
+
+        heartbeat_service.start(
+            args.heartbeat_url, args.heartbeat_initial_delay, args.heartbeat_interval
+        )
+    else:
+        print("Heartbeat URL not configured, heartbeat disabled")
+
+    if args.no_http:
+        print("HTTP server disabled (--no-http), running heartbeat only")
+        try:
+            stop_event = threading.Event()
+            stop_event.wait()
+        finally:
+            print("Shutting down application...")
+            heartbeat_service.stop()
+        return
+
+    try:
+        uvicorn.run(app, host=args.host, port=args.port, log_level=args.log_level)
+    finally:
+        # Stop heartbeat service when app closes
+        print("Shutting down application...")
+        heartbeat_service.stop()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/lmcache_frontend/config.json b/lmcache/lmcache_frontend/config.json
new file mode 100644
index 0000000..0637a08
--- /dev/null
+++ b/lmcache/lmcache_frontend/config.json
@@ -0,0 +1 @@
+[]
\ No newline at end of file
diff --git a/lmcache/lmcache_frontend/heartbeat.py b/lmcache/lmcache_frontend/heartbeat.py
new file mode 100644
index 0000000..e380733
--- /dev/null
+++ b/lmcache/lmcache_frontend/heartbeat.py
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Heartbeat service module for periodic health reporting"""
+
+# Standard
+from datetime import datetime
+import asyncio
+import json
+import os
+import socket
+import threading
+
+# Third Party
+import httpx
+
+
+class HeartbeatService:
+    """Periodic heartbeat service to report system status"""
+
+    def __init__(self):
+        self.thread = None
+        self.stop_event = threading.Event()
+        self.startup_time = datetime.now()
+        self.app_host = "0.0.0.0"
+        self.app_port = 8000
+        self.target_nodes = []
+
+    def get_local_ip(self) -> str:
+        """Get the local IP address of the machine using multiple methods.
+
+        Returns:
+            A non-loopback IPv4 string when discoverable, otherwise
+            ``"127.0.0.1"`` as the final fallback.
+        """
+        # Method 1: Try UDP socket connection (works when network is available)
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            s.settimeout(0.1)
+            # Use a non-routable address - doesn't actually send packets
+            s.connect(("10.255.255.255", 1))
+            ip = s.getsockname()[0]
+            s.close()
+            if not ip.startswith("127."):
+                return ip
+        except Exception:
+            pass
+
+        # Method 2: Try hostname resolution
+        try:
+            hostname = socket.gethostname()
+            ips = socket.gethostbyname_ex(hostname)[2]
+            for ip in ips:
+                if not ip.startswith("127."):
+                    return ip
+        except Exception:
+            pass
+
+        # Method 3: Iterate through network interfaces (platform-specific)
+        try:
+            # Standard
+            import platform
+            import subprocess
+
+            if platform.system() == "Darwin":  # macOS
+                result = subprocess.run(
+                    ["ipconfig", "getifaddr", "en0"],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    return result.stdout.strip()
+            elif platform.system() == "Linux":
+                result = subprocess.run(
+                    ["hostname", "-I"],
+                    capture_output=True,
+                    text=True,
+                    timeout=2,
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    return result.stdout.strip().split()[0]
+        except Exception:
+            pass
+
+        print("Failed to get local IP address. Falling back to loopback address.")
+        return "127.0.0.1"
+
+    def set_app_config(self, host: str, port: int, target_nodes: list):
+        """Set application configuration for heartbeat reporting"""
+        self.app_host = host
+        self.app_port = port
+        self.target_nodes = target_nodes
+
+    async def send_heartbeat(self, heartbeat_url: str):
+        """Send heartbeat request"""
+        try:
+            api_address = f"http://{self.get_local_ip()}:{self.app_port}"
+            version = await self._get_version_from_nodes()
+            if version:
+                print(f"Got version from target nodes: {version}")
+
+            # Calculate total children nodes across all proxies
+            total_children = sum(
+                len(proxy_node["nodes"]) for proxy_node in self.target_nodes
+            )
+            params = {
+                "pid": os.getpid(),
+                "api_address": api_address,
+                "version": version or "1.0.0",
+                "other_info": json.dumps(
+                    {
+                        "startup_time": self.startup_time.isoformat(),
+                        "nodes_count": total_children,
+                    }
+                ),
+            }
+
+            async with httpx.AsyncClient(timeout=10.0) as client:
+                response = await client.get(heartbeat_url, params=params)
+                response.raise_for_status()
+                print(
+                    f"Heartbeat sent successfully: "
+                    f"{heartbeat_url} - Status: {response.status_code}"
+                )
+                return True
+        except Exception as e:
+            print(f"Heartbeat send failed: {heartbeat_url} - Error: {str(e)}")
+            return False
+
+    async def _get_version_from_nodes(self):
+        """Get version from target nodes by querying each node directly."""
+        if not self.target_nodes:
+            return None
+
+        for proxy_node in self.target_nodes:
+            for node in proxy_node["nodes"]:
+                try:
+                    url = "http://%s:%s/version" % (
+                        node["host"],
+                        node["port"],
+                    )
+                    async with httpx.AsyncClient(timeout=5.0) as client:
+                        response = await client.get(url)
+
+                    if response.status_code == 200 and response.content:
+                        content = response.content.decode("utf-8").strip()
+                        if (content.startswith('"') and content.endswith('"')) or (
+                            content.startswith("'") and content.endswith("'")
+                        ):
+                            content = content[1:-1]
+                        return content
+
+                except Exception as e:
+                    print(
+                        "Failed to get version from node %s: %s"
+                        % (node["name"], str(e))
+                    )
+                    continue
+
+        return None
+
+    def worker(self, heartbeat_url: str, initial_delay: int, interval: int):
+        """Heartbeat background thread worker function"""
+        local_ip = self.get_local_ip()
+        print(
+            f"Heartbeat thread started - Local IP: {local_ip}, "
+            f"Service URL: {heartbeat_url}"
+        )
+        print(f"Initial delay: {initial_delay}s, Interval: {interval}s")
+
+        if initial_delay > 0:
+            print(f"Waiting initial delay {initial_delay}s...")
+            if self.stop_event.wait(initial_delay):
+                print("Heartbeat thread stopped during initial delay")
+                return
+
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        try:
+            while not self.stop_event.is_set():
+                try:
+                    loop.run_until_complete(self.send_heartbeat(heartbeat_url))
+                except Exception as e:
+                    print(f"Heartbeat send exception: {str(e)}")
+
+                if self.stop_event.wait(interval):
+                    break
+        finally:
+            loop.close()
+            print("Heartbeat thread stopped")
+
+    def start(self, heartbeat_url: str, initial_delay: int = 0, interval: int = 30):
+        """Start heartbeat thread"""
+        if self.thread and self.thread.is_alive():
+            print("Heartbeat thread is already running")
+            return
+
+        self.stop_event.clear()
+        self.thread = threading.Thread(
+            target=self.worker,
+            args=(heartbeat_url, initial_delay, interval),
+            daemon=True,
+        )
+        self.thread.start()
+        print("Heartbeat thread started")
+
+    def stop(self):
+        """Stop heartbeat thread"""
+        if self.thread and self.thread.is_alive():
+            print("Stopping heartbeat thread...")
+            self.stop_event.set()
+            self.thread.join(timeout=5)
+            if self.thread.is_alive():
+                print("Warning: Heartbeat thread didn't stop within 5 seconds")
+            else:
+                print("Heartbeat thread stopped successfully")
+        else:
+            print("Heartbeat thread is not running")
+
+    def status(self) -> dict:
+        """Return a snapshot of the heartbeat thread state.
+
+        Returns:
+            Dict containing ``running`` (bool), ``local_ip``,
+            ``startup_time`` and ``current_time`` (ISO-8601 strings).
+        """
+        is_running = self.thread and self.thread.is_alive()
+        return {
+            "running": is_running,
+            "local_ip": self.get_local_ip(),
+            "startup_time": self.startup_time.isoformat(),
+            "current_time": datetime.now().isoformat(),
+        }
diff --git a/lmcache/lmcache_frontend/lmcache_mp_plugin/__init__.py b/lmcache/lmcache_frontend/lmcache_mp_plugin/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/lmcache_frontend/lmcache_mp_plugin/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py b/lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py
new file mode 100644
index 0000000..17d5932
--- /dev/null
+++ b/lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py
@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""MP mode frontend plugin for LMCache multiprocess server.
+
+Launched by MPRuntimePluginLauncher via ``--runtime-plugin-locations``.
+Reads the aggregated config from ``LMCACHE_RUNTIME_PLUGIN_CONFIG``,
+builds argv for the frontend app, and calls ``app.main()``.
+
+Config JSON structure (MP mode)::
+
+    {
+      "mp_config": { ... },
+      "storage_manager_config": { ... },
+      "obs_config": { ... },
+      "http_config": {
+        "http_host": "0.0.0.0",
+        "http_port": 8085,
+        "http_socket_path": null
+      },
+      "runtime_plugin_extra_config": {
+        "plugin.frontend.heartbeat_url": "http://...",
+        ...
+      }
+    }
+
+The ``http_config`` block is forwarded by ``http_server.py`` so the
+plugin can automatically derive the LMCache HTTP port without any
+extra flags. For backwards compatibility the plugin also accepts the
+legacy key name ``http_frontend_config``.
+"""
+
+# Standard
+import json
+import os
+import signal
+import sys
+
+# ---------------------------------------------------------------------------
+# Import the frontend app.  When running as a subprocess via
+# ``MPRuntimePluginLauncher``, ``lmcache`` is normally already installed
+# (editable or regular pip install), so the direct import just works.
+# As a development fallback, if the import fails we add the repo root
+# (3 levels above this file) to ``sys.path`` and try again.
+# ---------------------------------------------------------------------------
+
+try:
+    # First Party
+    from lmcache.lmcache_frontend import app  # noqa: E402
+except ImportError:
+    _PLUGIN_DIR = os.path.dirname(os.path.abspath(__file__))
+    _REPO_ROOT = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.dirname(_PLUGIN_DIR)))
+    )
+    if _REPO_ROOT not in sys.path:
+        sys.path.insert(0, _REPO_ROOT)
+    # First Party
+    from lmcache.lmcache_frontend import app  # noqa: E402
+
+
+# ---------------------------------------------------------------------------
+# Graceful shutdown
+# ---------------------------------------------------------------------------
+
+
+def _handle_exit(signum, frame):
+    print("[mp_frontend] Received termination signal, exiting...")
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# Config helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_mp_config() -> dict:
+    raw = os.getenv("LMCACHE_RUNTIME_PLUGIN_CONFIG", "")
+    if not raw:
+        print("[mp_frontend] WARNING: LMCACHE_RUNTIME_PLUGIN_CONFIG is empty")
+        return {}
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print("[mp_frontend] ERROR: failed to parse config: %s" % exc)
+        return {}
+
+
+def _extra_cfg(config: dict) -> dict:
+    """Return ``plugin.frontend.*`` extra config dict.
+
+    Reads ``runtime_plugin_extra_config`` from the top-level of the
+    aggregated ``LMCACHE_RUNTIME_PLUGIN_CONFIG`` JSON::
+
+        {
+          "runtime_plugin_extra_config": {   <- this dict
+            "plugin.frontend.heartbeat_url": "...",
+            ...
+          }
+        }
+    """
+    return config.get("runtime_plugin_extra_config") or {}
+
+
+def build_argv(config: dict, prog: str = "lmcache_mp_frontend_plugin") -> list:
+    """Build argv for ``app.main()`` from the aggregated MP config.
+
+    Extracted as a pure function so it can be unit-tested without
+    actually launching the frontend.
+    """
+    extra = _extra_cfg(config)
+    http_cfg = config.get("http_config") or config.get("http_frontend_config") or {}
+
+    argv: list = [prog]
+
+    # Forward all plugin.frontend.* keys as CLI args to app.main().
+    for key, value in extra.items():
+        if key.startswith("plugin.frontend."):
+            arg_name = "--" + key.replace("plugin.frontend.", "").replace("_", "-")
+            argv.extend([arg_name, str(value)])
+
+    # Build the lmcache server node entry so the frontend can proxy to it.
+    socket_path = http_cfg.get("http_socket_path")
+    if socket_path:
+        lmc_node = {
+            "name": "lmcache_server",
+            "host": "localhost",
+            "port": socket_path,
+        }
+    else:
+        lmc_host = http_cfg.get("http_host", "localhost")
+        # 0.0.0.0 is a listen address, not a connectable address
+        if lmc_host in ("0.0.0.0", "::"):
+            lmc_host = "localhost"
+        lmc_port = http_cfg.get("http_port", 8080)
+        lmc_node = {
+            "name": "lmcache_server",
+            "host": lmc_host,
+            "port": str(lmc_port),
+        }
+
+    argv.extend(["--nodes", json.dumps([lmc_node])])
+
+    # --port is used by heartbeat to build api_address; set it to the
+    # lmcache HTTP port so the reported address is correct.
+    lmcache_port = http_cfg.get("http_port")
+    if lmcache_port:
+        argv.extend(["--port", str(lmcache_port)])
+
+    argv.append("--no-http")
+    return argv
+
+
+def main() -> None:
+    """Entry point for the MP-mode frontend plugin subprocess.
+
+    Registers SIGTERM/SIGINT handlers for graceful shutdown, parses
+    the aggregated config from ``LMCACHE_RUNTIME_PLUGIN_CONFIG``,
+    rewrites ``sys.argv`` via :func:`build_argv`, and delegates to
+    :func:`lmcache.lmcache_frontend.app.main`.
+    """
+    signal.signal(signal.SIGTERM, _handle_exit)
+    signal.signal(signal.SIGINT, _handle_exit)
+
+    config = _parse_mp_config()
+    print("[mp_frontend] config keys: %s" % list(config.keys()))
+    print("[mp_frontend] extra_cfg: %s" % json.dumps(_extra_cfg(config), default=str))
+
+    sys.argv = build_argv(config, prog=sys.argv[0])
+
+    print("[mp_frontend] Starting frontend application...")
+    print("[mp_frontend] argv: %s" % sys.argv)
+
+    app.main()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/lmcache_frontend/run_mp_server_with_frontend.sh b/lmcache/lmcache_frontend/run_mp_server_with_frontend.sh
new file mode 100755
index 0000000..385585b
--- /dev/null
+++ b/lmcache/lmcache_frontend/run_mp_server_with_frontend.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+#
+# Launch the LMCache MP HTTP server with the frontend plugin wired in.
+# The plugin reports heartbeats to a (remote or local) discovery service
+# whose URL is passed through ``--runtime-plugin-config``.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+PLUGIN="${REPO_ROOT}/lmcache/lmcache_frontend/lmcache_mp_plugin/lmcache_mp_frontend_plugin.py"
+HEARTBEAT_URL="${HEARTBEAT_URL:-http://localhost:5000/lmcache_heartbeat}"
+
+python3 -m lmcache.v1.multiprocess.http_server \
+    --host localhost --port 5555 \
+    --http-host 0.0.0.0 --http-port 8085 \
+    --l1-size-gb 2 \
+    --eviction-policy LRU \
+    --runtime-plugin-locations "${PLUGIN}" \
+    --runtime-plugin-config \
+        "{\"plugin.frontend.heartbeat-url\": \"${HEARTBEAT_URL}\"}"
diff --git a/lmcache/lmcache_frontend/static/css/style.css b/lmcache/lmcache_frontend/static/css/style.css
new file mode 100644
index 0000000..db675ef
--- /dev/null
+++ b/lmcache/lmcache_frontend/static/css/style.css
@@ -0,0 +1,190 @@
+body {
+    background-color: #f8f9fa;
+    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+}
+
+header {
+    border-radius: 0 0 10px 10px;
+    box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+}
+
+#currentNode {
+    padding: 10px 15px;
+    border-radius: 5px;
+}
+
+#refreshNodesBtn, #refreshPageBtn, #filterNodesBtn, #clearFilterBtn {
+    padding: 0.375rem 0.75rem;
+    font-size: 1rem;
+    color: #fff;
+    background-color: #0d6efd;
+    border-color: #0d6efd;
+}
+
+.bi {
+    margin-right: 0.25rem;
+}
+
+.tab-content {
+    background-color: white;
+    border-radius: 0 0 10px 10px;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.05);
+    min-height: 400px;
+}
+
+pre {
+    background-color: #f8f9fa;
+    padding: 15px;
+    border-radius: 5px;
+    max-height: 500px;
+    overflow: auto;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+}
+
+.card {
+    margin-top: 20px;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.05);
+}
+
+#logLevelContent {
+    min-height: 200px;
+}
+
+#loggerSelector {
+    margin-bottom: 15px;
+}
+
+#setLogLevelBtn {
+    margin-top: 10px;
+}
+
+/* Config tab styles */
+#configContent {
+    min-height: 200px;
+}
+
+#configKeyInput, #configValueInput {
+    margin-bottom: 15px;
+}
+
+#getConfigBtn, #setConfigBtn {
+    margin-top: 10px;
+}
+
+/* Meta and Inference tab styles */
+#metaContent, #inferenceContent {
+    min-height: 300px;
+}
+
+/* Config, Meta, and Inference content word wrapping */
+#configContent, #metaContent, #inferenceContent {
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    overflow-wrap: break-word;
+}
+
+/* Proxy search dropdown styles */
+#proxySearchInput {
+    cursor: pointer;
+}
+
+#proxyDropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    z-index: 1000;
+    display: none;
+    min-width: 100%;
+    padding: 0.5rem 0;
+    margin: 0.125rem 0 0;
+    font-size: 1rem;
+    color: #212529;
+    text-align: left;
+    list-style: none;
+    background-color: #fff;
+    background-clip: padding-box;
+    border: 1px solid rgba(0,0,0,.15);
+    border-radius: 0.25rem;
+    box-shadow: 0 0.5rem 1rem rgba(0,0,0,.175);
+}
+
+#proxyDropdown.show {
+    display: block;
+}
+
+#proxyDropdown .dropdown-item {
+    display: block;
+    width: 100%;
+    padding: 0.25rem 1rem;
+    clear: both;
+    font-weight: 400;
+    color: #212529;
+    text-align: inherit;
+    text-decoration: none;
+    white-space: nowrap;
+    background-color: transparent;
+    border: 0;
+    cursor: pointer;
+}
+
+#proxyDropdown .dropdown-item:hover,
+#proxyDropdown .dropdown-item:focus {
+    color: #1e2125;
+    background-color: #e9ecef;
+}
+
+
+/* MultiProcess Overview card styles */
+.stat-card {
+    border: 1px solid #dee2e6;
+    border-radius: 0.5rem;
+    box-shadow: 0 1px 3px rgba(0,0,0,.08);
+    margin-top: 0;
+}
+
+.stat-label {
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: #6c757d;
+    font-weight: 600;
+}
+
+.stat-value {
+    font-size: 2rem;
+    font-weight: 700;
+    line-height: 1.2;
+}
+
+.health-dot {
+    display: inline-block;
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    margin-right: 6px;
+    vertical-align: middle;
+}
+
+.health-dot.healthy   { background-color: #198754; }
+.health-dot.unhealthy { background-color: #dc3545; }
+
+.memory-bar {
+    height: 18px;
+    background-color: #e9ecef;
+    border-radius: 4px;
+    overflow: hidden;
+}
+
+.memory-bar .bar-fill {
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.7rem;
+    color: #fff;
+    font-weight: 600;
+    min-width: 2rem;
+    transition: width 0.4s ease;
+}
+
diff --git a/lmcache/lmcache_frontend/static/img/logo.png b/lmcache/lmcache_frontend/static/img/logo.png
new file mode 100644
index 0000000..398771d
Binary files /dev/null and b/lmcache/lmcache_frontend/static/img/logo.png differ
diff --git a/lmcache/lmcache_frontend/static/index.html b/lmcache/lmcache_frontend/static/index.html
new file mode 100644
index 0000000..c2de9e9
--- /dev/null
+++ b/lmcache/lmcache_frontend/static/index.html
@@ -0,0 +1,239 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>LMCache Dashboard</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/font/bootstrap-icons.css">
+    <link rel="stylesheet" href="/static/css/style.css">
+    <link rel="icon" href="/static/img/logo.png" type="image/png">
+</head>
+<body>
+    <div class="container-fluid">
+        <header class="bg-primary text-white p-3 mb-4">
+            <h1>LMCache Cluster Monitoring</h1>
+            <div class="row align-items-center">
+                <div class="col-md-6">
+                    <div class="row g-2">
+                        <div class="col-md-6">
+                            <div class="position-relative">
+                                <input type="text" id="proxySearchInput" class="form-control" placeholder="Search and select proxy..." autocomplete="off">
+                                <select id="proxySelector" class="form-select d-none">
+                                    <option value="">-- Select Proxy --</option>
+                                </select>
+                                <div id="proxyDropdown" class="dropdown-menu" style="max-height: 300px; overflow-y: auto; width: 100%;">
+                                    <!-- Proxy options will be populated here -->
+                                </div>
+                            </div>
+                        </div>
+                        <div class="col-md-6">
+                            <select id="targetSelector" class="form-select" disabled>
+                                <option value="">-- Select Target --</option>
+                            </select>
+                        </div>
+                    </div>
+                    <div class="mt-2 row g-2">
+                        <div class="col-md-6">
+                            <div class="input-group input-group-sm">
+                                <input type="text" class="form-control" id="envFilterInput" placeholder="Filter by env (e.g., TAG=TaijiDS)">
+                                <button id="filterNodesBtn" class="btn btn-outline-primary" type="button">
+                                    <i class="bi bi-funnel"></i> Filter Nodes
+                                </button>
+                                <button id="clearFilterBtn" class="btn btn-outline-secondary" type="button">
+                                    <i class="bi bi-x"></i> Clear
+                                </button>
+                            </div>
+                        </div>
+                        <div class="col-md-6">
+                            <button id="refreshNodesBtn" class="btn btn-sm btn-outline-primary me-2">
+                                <i class="bi bi-arrow-clockwise"></i> Refresh Nodes
+                            </button>
+                            <button id="refreshPageBtn" class="btn btn-sm btn-outline-primary me-2">
+                                <i class="bi bi-arrow-clockwise"></i> Refresh Page
+                            </button>
+                        </div>
+                    </div>
+                </div>
+                <div class="col-md-6 text-end">
+                    <span id="currentNode" class="badge bg-info fs-6">No node selected</span>
+                </div>
+            </div>
+        </header>
+
+        <ul class="nav nav-tabs" id="myTab" role="tablist">
+            <li class="nav-item" role="presentation">
+                <button class="nav-link active" id="overview-tab" data-bs-toggle="tab" data-bs-target="#overview" type="button" role="tab">Overview</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="metrics-tab" data-bs-toggle="tab" data-bs-target="#metrics" type="button" role="tab">Metrics</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="threads-tab" data-bs-toggle="tab" data-bs-target="#threads" type="button" role="tab">Threads</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="loglevel-tab" data-bs-toggle="tab" data-bs-target="#loglevel" type="button" role="tab">Log Level</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="config-tab" data-bs-toggle="tab" data-bs-target="#config" type="button" role="tab">Config</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="meta-tab" data-bs-toggle="tab" data-bs-target="#meta" type="button" role="tab">Meta</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="inference-tab" data-bs-toggle="tab" data-bs-target="#inference" type="button" role="tab">Inference</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="env-tab" data-bs-toggle="tab" data-bs-target="#env" type="button" role="tab">Environment</button>
+            </li>
+            <!-- Add Node Management Tab -->
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="node-management-tab" data-bs-toggle="tab" data-bs-target="#node-management" type="button" role="tab">Node Management</button>
+            </li>
+        </ul>
+
+        <div class="tab-content p-3 border border-top-0" id="myTabContent">
+            <div class="tab-pane fade show active" id="overview" role="tabpanel">
+                <h3>Node Overview</h3>
+                <div id="overviewContent">Please select a target node first</div>
+            </div>
+
+            <div class="tab-pane fade" id="metrics" role="tabpanel">
+                <h3>Performance Metrics</h3>
+                <pre id="metricsContent">Please select a target node first</pre>
+            </div>
+
+            <div class="tab-pane fade" id="threads" role="tabpanel">
+                <h3>Thread Information</h3>
+                <pre id="threadsContent">Please select a target node first</pre>
+            </div>
+
+            <div class="tab-pane fade" id="loglevel" role="tabpanel">
+                <h3>Log Level Management</h3>
+                <div class="row">
+                    <div class="col-md-6">
+                        <div class="mb-3">
+                            <label for="loggerInput" class="form-label">Logger Name (leave empty for all)</label>
+                            <input type="text" class="form-control" id="loggerInput" placeholder="Enter logger name">
+                        </div>
+                        <div class="mb-3">
+                            <label for="logLevelSelector" class="form-label">Log Level</label>
+                            <select class="form-select" id="logLevelSelector">
+                                <option value="">-- Read Level --</option>
+                                <option value="TRACE">TRACE</option>
+                                <option value="DEBUG">DEBUG</option>
+                                <option value="INFO">INFO</option>
+                                <option value="WARN">WARN</option>
+                                <option value="ERROR">ERROR</option>
+                                <option value="FATAL">FATAL</option>
+                                <option value="OFF">OFF</option>
+                            </select>
+                        </div>
+                        <button id="setLogLevelBtn" class="btn btn-primary">Set Level</button>
+                    </div>
+                    <div class="col-md-6">
+                        <h4>Current Log Levels</h4>
+                        <pre id="logLevelContent">Please select a target node first</pre>
+                    </div>
+                </div>
+            </div>
+
+            <div class="tab-pane fade" id="config" role="tabpanel">
+                <h3>Configuration Management</h3>
+                <div class="row">
+                    <div class="col-md-6">
+                        <div class="mb-3">
+                            <label for="configKeyInput" class="form-label">Configuration Key (leave empty for all)</label>
+                            <input type="text" class="form-control" id="configKeyInput" placeholder="Enter config key">
+                        </div>
+                        <div class="mb-3">
+                            <label for="configValueInput" class="form-label">Configuration Value</label>
+                            <input type="text" class="form-control" id="configValueInput" placeholder="Enter config value">
+                        </div>
+                        <button id="getConfigBtn" class="btn btn-info me-2">Get Config</button>
+                        <button id="setConfigBtn" class="btn btn-primary">Set Config</button>
+                    </div>
+                    <div class="col-md-6">
+                        <h4>Current Configuration</h4>
+                        <pre id="configContent">Please select a target node first</pre>
+                    </div>
+                </div>
+            </div>
+
+            <div class="tab-pane fade" id="meta" role="tabpanel">
+                <h3>Meta Information</h3>
+                <pre id="metaContent">Please select a target node first</pre>
+            </div>
+
+            <div class="tab-pane fade" id="inference" role="tabpanel">
+                <h3>Inference Information</h3>
+                <pre id="inferenceContent">Please select a target node first</pre>
+            </div>
+
+            <div class="tab-pane fade" id="env" role="tabpanel">
+                <h3>Environment Variables</h3>
+                <div class="mb-3">
+                    <input type="text" class="form-control" id="envSearchInput" placeholder="Search environment variables...">
+                </div>
+                <pre id="envContent">Please select a target node first</pre>
+            </div>
+
+            <!-- Node Management Tab -->
+            <div class="tab-pane fade" id="node-management" role="tabpanel">
+                <h3>Node Management</h3>
+                <div class="card mb-4">
+                    <div class="card-body">
+                        <h5 class="card-title">Add/Update Node</h5>
+                        <div class="mb-3">
+                            <label for="nodeName" class="form-label">Node Name</label>
+                            <input type="text" class="form-control" id="nodeName" placeholder="Unique node name">
+                        </div>
+                        <div class="mb-3">
+                            <label for="nodeHost" class="form-label">Host</label>
+                            <input type="text" class="form-control" id="nodeHost" placeholder="Hostname or IP">
+                        </div>
+                        <div class="mb-3">
+                            <label for="nodePort" class="form-label">Port/Socket Path</label>
+                            <input type="text" class="form-control" id="nodePort" placeholder="Port number or socket path">
+                        </div>
+                        <div class="mb-3 form-check">
+                            <input type="checkbox" class="form-check-input" id="isProxyCheck">
+                            <label class="form-check-label" for="isProxyCheck">Is Proxy Node</label>
+                        </div>
+                        <div class="mb-3">
+                            <label for="proxyIdInput" class="form-label">Proxy ID (if this node needs proxy)</label>
+                            <input type="text" class="form-control" id="proxyIdInput" placeholder="Enter proxy node name">
+                        </div>
+                        <button id="addNodeBtn" class="btn btn-primary me-2">Add Node</button>
+                        <button id="updateNodeBtn" class="btn btn-warning me-2">Update Node</button>
+                    </div>
+                </div>
+                
+                <div class="card">
+                    <div class="card-body">
+                        <h5 class="card-title">Current Nodes</h5>
+                        <div class="table-responsive">
+                            <table class="table table-striped">
+                                <thead>
+                                    <tr>
+                                        <th>Name</th>
+                                        <th>Host</th>
+                                        <th>Port/Socket</th>
+                                        <th>Actions</th>
+                                    </tr>
+                                </thead>
+                                <tbody id="nodeListBody">
+                                    <!-- Node list will be populated here -->
+                                </tbody>
+                            </table>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+    <script src="/static/js/app.js"></script>
+</body>
+</html>
diff --git a/lmcache/lmcache_frontend/static/js/app.js b/lmcache/lmcache_frontend/static/js/app.js
new file mode 100644
index 0000000..0a5a04b
--- /dev/null
+++ b/lmcache/lmcache_frontend/static/js/app.js
@@ -0,0 +1,1189 @@
+// Global variables
+let currentNode = null;
+let currentProxy = null;
+let proxyNodes = {};
+let allProxies = []; // Store all proxies for filtering
+
+// Initialize after DOM is loaded
+window.addEventListener('DOMContentLoaded', () => {
+    // Initialize proxy selector
+    loadProxies();
+
+    // Proxy search input event
+    const proxySearchInput = document.getElementById('proxySearchInput');
+    const proxyDropdown = document.getElementById('proxyDropdown');
+    
+    proxySearchInput.addEventListener('focus', () => {
+        filterProxies();
+        proxyDropdown.classList.add('show');
+    });
+    
+    proxySearchInput.addEventListener('input', () => {
+        filterProxies();
+    });
+    
+    // Close dropdown when clicking outside
+    document.addEventListener('click', (e) => {
+        if (!proxySearchInput.contains(e.target) && !proxyDropdown.contains(e.target)) {
+            proxyDropdown.classList.remove('show');
+        }
+    });
+
+    // Proxy selection event (kept for compatibility)
+    document.getElementById('proxySelector').addEventListener('change', (e) => {
+        const proxyName = e.target.value;
+        if (proxyName) {
+            currentProxy = proxyNodes[proxyName];
+            loadTargetNodes(proxyName);
+        } else {
+            currentProxy = null;
+            document.getElementById('targetSelector').disabled = true;
+            document.getElementById('targetSelector').innerHTML = '<option value="">-- Select Target --</option>';
+        }
+    });
+
+    // Target selection event
+    document.getElementById('targetSelector').addEventListener('change', (e) => {
+        const nodeId = e.target.value;
+        if (nodeId) {
+            currentNode = JSON.parse(nodeId);
+            document.getElementById('currentNode').textContent =
+                `${currentNode.name} (${currentNode.host}:${currentNode.port})`;
+
+            // Refresh active tab
+            refreshActiveTab();
+        } else {
+            currentNode = null;
+            document.getElementById('currentNode').textContent = 'No Node Selected';
+            clearAllTabs();
+        }
+    });
+
+    // Tab switching event
+    document.querySelectorAll('.nav-link').forEach(tab => {
+        tab.addEventListener('shown.bs.tab', () => {
+            if (currentNode) {
+                refreshActiveTab();
+            }
+        });
+    });
+
+    // Set log level button
+    document.getElementById('setLogLevelBtn').addEventListener('click', setLogLevel);
+
+    // Config management buttons
+    document.getElementById('getConfigBtn').addEventListener('click', getConfig);
+    document.getElementById('setConfigBtn').addEventListener('click', setConfig);
+
+    // Refresh page button
+    document.getElementById('refreshPageBtn').addEventListener('click', refreshCurrentPage);
+
+    // Node management buttons
+    document.getElementById('addNodeBtn').addEventListener('click', addNode);
+    document.getElementById('updateNodeBtn').addEventListener('click', updateNode);
+
+    // Refresh nodes button
+    document.getElementById('refreshNodesBtn').addEventListener('click', refreshNodes);
+
+    // Environment search input
+    document.getElementById('envSearchInput').addEventListener('input', filterEnvVariables);
+
+    // Environment filter buttons
+    document.getElementById('filterNodesBtn').addEventListener('click', filterNodesByEnv);
+    document.getElementById('clearFilterBtn').addEventListener('click', clearEnvFilter);
+
+    // Refresh current page function
+    function refreshCurrentPage() {
+        if (currentNode) {
+            refreshActiveTab();
+        } else {
+            alert('Please select a target node first');
+        }
+    }
+
+    // Load node management list
+    document.getElementById('node-management-tab').addEventListener('shown.bs.tab', () => {
+        loadNodeListForManagement();
+    });
+});
+
+// Load proxy list
+async function loadProxies() {
+    try {
+        const response = await fetch('/api/proxies');
+        const data = await response.json();
+
+        const selector = document.getElementById('proxySelector');
+        selector.innerHTML = '<option value="">-- Select Proxy --</option>';
+
+        proxyNodes = {};
+        allProxies = [];
+
+        data.proxies.forEach(proxy => {
+            const option = document.createElement('option');
+            option.value = proxy.name;
+            option.textContent = `${proxy.name} (${proxy.host}:${proxy.port})`;
+            selector.appendChild(option);
+
+            proxyNodes[proxy.name] = proxy;
+            allProxies.push(proxy);
+        });
+        
+        // Initialize dropdown with all proxies
+        filterProxies();
+    } catch (error) {
+        console.error('Failed to load proxies:', error);
+    }
+}
+
+// Filter proxies based on search input
+function filterProxies() {
+    const searchInput = document.getElementById('proxySearchInput');
+    const dropdown = document.getElementById('proxyDropdown');
+    const searchTerm = searchInput.value.toLowerCase();
+    
+    dropdown.innerHTML = '';
+    
+    const filteredProxies = allProxies.filter(proxy => {
+        const proxyText = `${proxy.name} (${proxy.host}:${proxy.port})`.toLowerCase();
+        return proxyText.includes(searchTerm);
+    });
+    
+    if (filteredProxies.length === 0) {
+        const noResultItem = document.createElement('div');
+        noResultItem.className = 'dropdown-item disabled';
+        noResultItem.textContent = 'No matching proxies found';
+        dropdown.appendChild(noResultItem);
+    } else {
+        filteredProxies.forEach(proxy => {
+            const item = document.createElement('a');
+            item.className = 'dropdown-item';
+            item.href = '#';
+            item.textContent = `${proxy.name} (${proxy.host}:${proxy.port})`;
+            item.dataset.proxyName = proxy.name;
+            
+            item.addEventListener('click', (e) => {
+                e.preventDefault();
+                selectProxy(proxy);
+            });
+            
+            dropdown.appendChild(item);
+        });
+    }
+}
+
+// Select a proxy
+function selectProxy(proxy) {
+    const searchInput = document.getElementById('proxySearchInput');
+    const dropdown = document.getElementById('proxyDropdown');
+    const selector = document.getElementById('proxySelector');
+    
+    // Update search input display
+    searchInput.value = `${proxy.name} (${proxy.host}:${proxy.port})`;
+    
+    // Update hidden selector
+    selector.value = proxy.name;
+    
+    // Close dropdown
+    dropdown.classList.remove('show');
+    
+    // Trigger proxy selection
+    currentProxy = proxyNodes[proxy.name];
+    loadTargetNodes(proxy.name);
+}
+
+// Load target nodes for selected proxy
+async function loadTargetNodes(proxyName, filteredNodes = null) {
+    try {
+        let nodes;
+        if (filteredNodes) {
+            nodes = filteredNodes;
+        } else {
+            const response = await fetch(`/api/proxies/${proxyName}/nodes`);
+            const data = await response.json();
+            nodes = data.nodes;
+        }
+
+        const selector = document.getElementById('targetSelector');
+        selector.innerHTML = '<option value="">-- Select Target --</option>';
+        selector.disabled = false;
+
+        nodes.forEach(node => {
+            const option = document.createElement('option');
+            option.value = JSON.stringify(node);
+            option.textContent = `${node.name} (${node.host}:${node.port})`;
+            selector.appendChild(option);
+        });
+    } catch (error) {
+        console.error('Failed to load target nodes:', error);
+    }
+}
+
+// Refresh child nodes of proxy
+async function refreshProxyNodes(proxyName) {
+    try {
+        const response = await fetch(`/api/proxies/${proxyName}/refresh`);
+        const data = await response.json();
+        if (data.status === "success") {
+            return data.nodes;
+        }
+        return [];
+    } catch (error) {
+        console.error('Failed to refresh proxy nodes:', error);
+        return [];
+    }
+}
+
+// Load node list
+async function loadNodes() {}
+
+// Refresh nodes for current proxy
+async function refreshNodes() {
+    if (!currentProxy) return;
+    await loadTargetNodes(currentProxy.name);
+}
+
+// ==== Node Management Functions ====
+async function loadNodeListForManagement() {
+    try {
+        const response = await fetch('/api/nodes');
+        const data = await response.json();
+        
+        const tableBody = document.getElementById('nodeListBody');
+        tableBody.innerHTML = '';
+        
+        data.nodes.forEach(node => {
+            const row = document.createElement('tr');
+            row.innerHTML = `
+                <td>${node.name}</td>
+                <td>${node.host}</td>
+                <td>${node.port}</td>
+                <td>${node.is_proxy ? 'Yes' : 'No'}</td>
+                <td>${node.proxy_id || '-'}</td>
+                <td>
+                    <button class="btn btn-sm btn-warning edit-node me-1" data-name="${node.name}">Edit</button>
+                    <button class="btn btn-sm btn-danger delete-node" data-name="${node.name}">Delete</button>
+                </td>
+            `;
+            tableBody.appendChild(row);
+        });
+        
+        // Add event listeners to edit/delete buttons
+        document.querySelectorAll('.edit-node').forEach(btn => {
+            btn.addEventListener('click', (e) => {
+                const nodeName = e.target.dataset.name;
+                const node = data.nodes.find(n => n.name === nodeName);
+                if (node) {
+                    document.getElementById('nodeName').value = node.name;
+                    document.getElementById('nodeHost').value = node.host;
+                    document.getElementById('nodePort').value = node.port;
+                    
+                    // Auto-set proxy fields
+                    document.getElementById('isProxyCheck').checked = node.is_proxy || false;
+                    document.getElementById('proxyIdInput').value = node.proxy_id || '';
+                }
+            });
+        });
+        
+        document.querySelectorAll('.delete-node').forEach(btn => {
+            btn.addEventListener('click', (e) => {
+                const nodeName = e.target.dataset.name;
+                if (confirm(`Are you sure you want to delete node ${nodeName}?`)) {
+                    deleteNode(nodeName);
+                }
+            });
+        });
+        
+    } catch (error) {
+        console.error('Failed to load nodes for management:', error);
+        alert('Failed to load nodes: ' + error.message);
+    }
+}
+
+
+async function addNode() {
+    const name = document.getElementById('nodeName').value.trim();
+    const host = document.getElementById('nodeHost').value.trim();
+    const port = document.getElementById('nodePort').value.trim();
+    const isProxy = document.getElementById('isProxyCheck').checked;
+    const proxyId = document.getElementById('proxyIdInput').value.trim();
+    
+    if (!name || !host || !port) {
+        alert('Please fill all fields');
+        return;
+    }
+    
+    try {
+        const response = await fetch('/api/nodes', {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({
+                name, 
+                host, 
+                port,
+                is_proxy: isProxy,
+                proxy_id: proxyId || null
+            })
+        });
+        
+        if (!response.ok) {
+            const errorData = await response.json();
+            throw new Error(errorData.detail || 'Failed to add node');
+        }
+        
+        // Refresh UI
+        document.getElementById('nodeName').value = '';
+        document.getElementById('nodeHost').value = '';
+        document.getElementById('nodePort').value = '';
+        
+        loadNodeListForManagement();
+        loadNodes(); // Refresh node selector
+        
+        alert('Node added successfully');
+    } catch (error) {
+        console.error('Add node error:', error);
+        alert('Failed to add node: ' + error.message);
+    }
+}
+
+
+async function updateNode() {
+    const name = document.getElementById('nodeName').value.trim();
+    const host = document.getElementById('nodeHost').value.trim();
+    const port = document.getElementById('nodePort').value.trim();
+    const isProxy = document.getElementById('isProxyCheck').checked;
+    const proxyId = document.getElementById('proxyIdInput').value.trim();
+    
+    if (!name || !host || !port) {
+        alert('Please fill all fields');
+        return;
+    }
+    
+    try {
+        const response = await fetch(`/api/nodes/${encodeURIComponent(name)}`, {
+            method: 'PUT',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({
+                name, 
+                host, 
+                port,
+                is_proxy: isProxy,
+                proxy_id: proxyId || null
+            })
+        });
+        
+        if (!response.ok) {
+            const errorData = await response.json();
+            throw new Error(errorData.detail || 'Failed to update node');
+        }
+        
+        // Refresh UI
+        loadNodeListForManagement();
+        loadNodes(); // Refresh node selector
+        
+        alert('Node updated successfully');
+    } catch (error) {
+        console.error('Update node error:', error);
+        alert('Failed to update node: ' + error.message);
+    }
+}
+
+
+async function deleteNode(nodeName) {
+    try {
+        const response = await fetch(`/api/nodes/${encodeURIComponent(nodeName)}`, {
+            method: 'DELETE'
+        });
+        
+        if (!response.ok) {
+            const errorData = await response.json();
+            throw new Error(errorData.detail || 'Failed to delete node');
+        }
+        
+        // Refresh UI
+        loadNodeListForManagement();
+        loadNodes(); // Refresh node selector
+        
+        // Clear form if deleting the currently edited node
+        if (document.getElementById('nodeName').value === nodeName) {
+            document.getElementById('nodeName').value = '';
+            document.getElementById('nodeHost').value = '';
+            document.getElementById('nodePort').value = '';
+        }
+        
+        alert('Node deleted successfully');
+    } catch (error) {
+        console.error('Delete node error:', error);
+        alert('Failed to delete node: ' + error.message);
+    }
+}
+
+// Refresh active tab
+function refreshActiveTab() {
+    const activeTab = document.querySelector('.tab-pane.active');
+    if (!activeTab) return;
+
+    switch (activeTab.id) {
+        case 'overview':
+            loadOverview();
+            break;
+        case 'metrics':
+            loadMetrics();
+            break;
+        case 'threads':
+            loadThreads();
+            break;
+        case 'loglevel':
+            loadLogLevel();
+            break;
+        case 'config':
+            loadConfig();
+            break;
+        case 'meta':
+            loadMeta();
+            break;
+        case 'inference':
+            loadInference();
+            break;
+        case 'env':
+            loadEnvironment();
+            break;
+        case 'node-management':
+            loadNodeListForManagement();
+            break;
+    }
+}
+
+// Load overview information
+async function loadOverview() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('overviewContent');
+    contentDiv.innerHTML = '<div class="spinner-border" role="status">'
+        + '<span class="visually-hidden">Loading...</span></div>';
+
+    // Try multiProcess /api/status first; fall back to basic info.
+    try {
+        const statusResp = await fetch(transformPath('api/status'));
+        if (statusResp.ok) {
+            const statusData = await statusResp.json();
+            renderMpOverview(contentDiv, statusData);
+            return;
+        }
+    } catch (_) {
+        // not a multiProcess node – fall through
+    }
+
+    // Basic overview for inProcess / legacy nodes
+    try {
+        const response = await fetch(transformPath('version'));
+        const versionInfo = await response.text();
+
+        contentDiv.innerHTML = `
+            <div class="card">
+                <div class="card-body">
+                    <h5 class="card-title">Node Information</h5>
+                    <p><strong>Name:</strong> ${escapeHtmlStr(currentNode.name)}</p>
+                    <p><strong>Host:</strong> ${escapeHtmlStr(currentNode.host)}</p>
+                    <p><strong>Port:</strong> ${escapeHtmlStr(String(currentNode.port))}</p>
+                </div>
+            </div>
+            <div class="card mt-3">
+                <div class="card-body">
+                    <h5 class="card-title">Version Information</h5>
+                    <pre>${escapeHtmlStr(versionInfo)}</pre>
+                </div>
+            </div>
+        `;
+    } catch (error) {
+        contentDiv.innerHTML = '<div class="alert alert-danger">'
+            + 'Failed to load overview: '
+            + escapeHtmlStr(error.message) + '</div>';
+    }
+}
+
+// ---------------------------------------------------------------
+// MultiProcess Overview renderer (ported from mp_app.js)
+// ---------------------------------------------------------------
+function renderMpOverview(container, data) {
+    var isHealthy = data.is_healthy;
+    var healthClass = isHealthy ? "healthy" : "unhealthy";
+    var healthText  = isHealthy ? "Healthy" : "Unhealthy";
+
+    var sm = data.storage_manager || {};
+    var l1 = sm.l1_manager || {};
+    var l1TotalBytes = l1.memory_total_bytes || 0;
+    var l1UsedBytes  = l1.memory_used_bytes  || 0;
+    var l1Pct = l1TotalBytes > 0
+        ? Math.round((l1UsedBytes / l1TotalBytes) * 100) : 0;
+    var l1Objects = l1.total_object_count || 0;
+    var barColor = l1Pct > 90 ? "#dc3545"
+        : l1Pct > 70 ? "#ffc107" : "#198754";
+
+    var gpuIds      = data.registered_gpu_ids || [];
+    var sessions    = data.active_sessions    || 0;
+    var engineType  = data.engine_type        || "Unknown";
+    var chunkSize   = data.chunk_size         || "N/A";
+    var hashAlgo    = data.hash_algorithm     || "N/A";
+    var numAdapters = sm.num_l2_adapters      || 0;
+
+    var html = '<div class="row">';
+
+    // Row 1: Health / Engine / Sessions
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Health</div>'
+        + '<div class="mt-2"><span class="health-dot ' + healthClass + '"></span>'
+        + '<span class="fs-4 fw-bold">' + healthText + '</span>'
+        + '</div></div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Engine Type</div>'
+        + '<div class="stat-value fs-4">' + escapeHtmlStr(engineType) + '</div>'
+        + '<small class="text-muted">Chunk: ' + escapeHtmlStr(String(chunkSize))
+        + ' | Hash: ' + escapeHtmlStr(hashAlgo) + '</small>'
+        + '</div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Active Sessions</div>'
+        + '<div class="stat-value">' + sessions + '</div>'
+        + '</div></div></div>';
+
+    // Row 2: GPU / L1 / L2
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">GPU Workers</div>'
+        + '<div class="stat-value">' + gpuIds.length + '</div>'
+        + '<small class="text-muted">IDs: '
+        + escapeHtmlStr(gpuIds.length > 0 ? gpuIds.join(", ") : "none")
+        + '</small></div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">L1 Cache Usage</div>'
+        + '<div class="memory-bar mt-2"><div class="bar-fill" style="width:'
+        + l1Pct + '%;background-color:' + barColor + '">' + l1Pct + '%</div></div>'
+        + '<small class="text-muted mt-1 d-block">'
+        + formatBytesStr(l1UsedBytes) + ' / ' + formatBytesStr(l1TotalBytes)
+        + ' (' + l1Objects + ' objects)</small>'
+        + '</div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">L2 Adapters</div>'
+        + '<div class="stat-value">' + numAdapters + '</div>'
+        + '</div></div></div>';
+
+    // Row 3: Pending & Prefetch
+    var pendingLookups  = data.pending_lookup_count    || 0;
+    var nextJobId       = data.next_prefetch_job_id    || 0;
+    var prefetchJobIds  = data.prefetch_job_ids        || [];
+    var pendingReqIds   = data.pending_request_ids     || [];
+
+    html += '<div class="col-12 mt-2 mb-2"><h5 class="text-muted">'
+        + '<i class="bi bi-hourglass-split"></i> Pending &amp; Prefetch</h5></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Active Prefetch Jobs</div>'
+        + '<div class="stat-value">' + prefetchJobIds.length + '</div>'
+        + '<small class="text-muted">next ID: ' + nextJobId;
+    if (prefetchJobIds.length > 0) {
+        html += ' &middot; IDs: '
+            + escapeHtmlStr(prefetchJobIds.slice(0, 5).join(", "));
+        if (prefetchJobIds.length > 5) {
+            html += ' +' + (prefetchJobIds.length - 5) + ' more';
+        }
+    }
+    html += '</small></div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Pending Lookups</div>'
+        + '<div class="stat-value">' + pendingLookups + '</div>'
+        + '</div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Pending Requests</div>'
+        + '<div class="stat-value">' + pendingReqIds.length + '</div>';
+    if (pendingReqIds.length > 0) {
+        html += '<small class="text-muted">'
+            + escapeHtmlStr(pendingReqIds.slice(0, 3).join(", "));
+        if (pendingReqIds.length > 3) {
+            html += ' +' + (pendingReqIds.length - 3) + ' more';
+        }
+        html += '</small>';
+    }
+    html += '</div></div></div>';
+
+    // Row 4: Periodic Threads summary
+    var pt       = data.periodic_threads || {};
+    var ptTotal   = pt.total_count   || 0;
+    var ptRunning = pt.running_count || 0;
+    var ptActive  = pt.active_count  || 0;
+
+    if (ptTotal > 0) {
+        html += '<div class="col-12 mt-2 mb-2"><h5 class="text-muted">'
+            + '<i class="bi bi-arrow-repeat"></i> Periodic Threads</h5></div>';
+
+        html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+            + '<div class="card-body"><div class="stat-label">Registered</div>'
+            + '<div class="stat-value">' + ptTotal + '</div>'
+            + '</div></div></div>';
+
+        var runColor = ptRunning === ptTotal ? "#198754" : "#ffc107";
+        html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+            + '<div class="card-body"><div class="stat-label">Running</div>'
+            + '<div class="stat-value" style="color:' + runColor + '">'
+            + ptRunning + ' / ' + ptTotal + '</div>'
+            + '</div></div></div>';
+
+        var actColor = ptActive === ptRunning ? "#198754" : "#dc3545";
+        html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+            + '<div class="card-body"><div class="stat-label">Active</div>'
+            + '<div class="stat-value" style="color:' + actColor + '">'
+            + ptActive + ' / ' + ptRunning + '</div>'
+            + '</div></div></div>';
+    }
+
+    // Row 5: Hit Statistics
+    html += renderMpHitStats(data.hit_stats);
+
+    html += '</div>'; // close .row
+    container.innerHTML = html;
+}
+
+function renderMpHitStats(stats) {
+    if (!stats) return "";
+
+    var hitRate  = stats.hit_rate || 0;
+    var hitPct   = Math.round(hitRate * 100);
+    var hitColor = hitPct >= 80 ? "#198754"
+        : hitPct >= 50 ? "#ffc107" : "#dc3545";
+
+    var totalReqs       = stats.total_requests        || 0;
+    var totalTokens     = stats.total_tokens          || 0;
+    var retrievedTokens = stats.total_retrieved_tokens || 0;
+
+    var html = '<div class="col-12 mt-2 mb-2"><h5 class="text-muted">'
+        + '<i class="bi bi-bullseye"></i> Hit Statistics</h5></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">GPU Hit Rate</div>'
+        + '<div class="stat-value" style="color:' + hitColor + '">'
+        + hitPct + '%</div>'
+        + '<div class="memory-bar mt-2"><div class="bar-fill" style="width:'
+        + hitPct + '%;background-color:' + hitColor + '">' + hitPct + '%</div></div>'
+        + '<small class="text-muted mt-1 d-block">'
+        + formatTokenCountStr(retrievedTokens) + ' / '
+        + formatTokenCountStr(totalTokens) + ' tokens</small>'
+        + '</div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">Total Requests</div>'
+        + '<div class="stat-value">' + totalReqs + '</div>'
+        + '<small class="text-muted">'
+        + formatTokenCountStr(totalTokens) + ' tokens total</small>'
+        + '</div></div></div>';
+
+    html += '<div class="col-md-4 mb-3"><div class="card stat-card">'
+        + '<div class="card-body"><div class="stat-label">GPU Retrieved</div>'
+        + '<div class="stat-value">'
+        + formatTokenCountStr(retrievedTokens) + '</div>'
+        + '<small class="text-muted">tokens written to GPU</small>'
+        + '</div></div></div>';
+
+    return html;
+}
+
+function formatBytesStr(bytes) {
+    if (bytes >= 1073741824) return (bytes / 1073741824).toFixed(2) + " GB";
+    if (bytes >= 1048576)    return (bytes / 1048576).toFixed(1)    + " MB";
+    if (bytes >= 1024)       return (bytes / 1024).toFixed(1)       + " KB";
+    return bytes + " B";
+}
+
+function formatTokenCountStr(count) {
+    if (count >= 1000000) return (count / 1000000).toFixed(1) + "M";
+    if (count >= 1000)    return (count / 1000).toFixed(1)    + "K";
+    return String(count);
+}
+
+function escapeHtmlStr(str) {
+    var div = document.createElement("div");
+    div.appendChild(document.createTextNode(str));
+    return div.innerHTML;
+}
+
+// Load metrics information
+async function loadMetrics() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('metricsContent');
+    contentDiv.textContent = 'Loading...';
+
+    try {
+        const response = await fetch(transformPath('metrics'));
+        const metrics = await response.text();
+        contentDiv.textContent = metrics;
+    } catch (error) {
+        contentDiv.textContent = `Failed to load metrics: ${error.message}`;
+    }
+}
+
+// Load threads information
+async function loadThreads() {
+    if (!currentNode) return;
+    const contentDiv = document.getElementById('threadsContent');
+    contentDiv.textContent = 'Loading...';
+
+    try {
+        const response = await fetch(transformPath('threads'));
+        const threads = await response.text();
+        contentDiv.textContent = threads;
+    } catch (error) {
+        contentDiv.textContent = `Failed to load threads: ${error.message}`;
+    }
+}
+
+// Load log level
+async function loadLogLevel() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('logLevelContent');
+    const loggerInput = document.getElementById('loggerInput');
+
+    contentDiv.textContent = 'Loading...';
+    loggerInput.value = '';
+
+    try {
+        const response = await fetch(transformPath('loglevel'));
+
+        const text = await response.text();
+
+        contentDiv.textContent = text;
+    } catch (error) {
+        contentDiv.textContent = `Failed to load log levels: ${error.message}`;
+    }
+}
+
+// Set log level
+async function setLogLevel() {
+    if (!currentNode) return;
+
+    const loggerInput = document.getElementById('loggerInput');
+    const levelSelector = document.getElementById('logLevelSelector');
+
+    const loggerName = loggerInput.value.trim();
+    const level = levelSelector.value;
+
+    try {
+        let url;
+        // Encode socket path if needed
+        const portOrSocket = encodeURIComponent(encodeURIComponent(currentNode.port));
+
+        if (!level) {
+            // Read log level if no level is selected
+            url = transformPath('loglevel');
+            if (loggerName) {
+                url += `?logger_name=${encodeURIComponent(loggerName)}`;
+            }
+            const response = await fetch(url);
+            const text = await response.text();
+            alert(text);
+        } else {
+            // Set log level if level is selected
+            if (!loggerName) {
+                alert('Please enter a Logger name');
+                return;
+            }
+            url = transformPath('loglevel');
+            url += `?logger_name=${encodeURIComponent(loggerName)}&level=${level}`;
+            const response = await fetch(url, { method: 'GET' });
+
+            const text = await response.text();
+            alert(text);
+
+            if (response.ok) {
+                loadLogLevel();
+            }
+        }
+    } catch (error) {
+        alert(`Failed to manage log level: ${error.message}`);
+    }
+}
+
+// Load configuration
+async function loadConfig() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('configContent');
+    const configKeyInput = document.getElementById('configKeyInput');
+    const configValueInput = document.getElementById('configValueInput');
+
+    contentDiv.textContent = 'Loading...';
+    configKeyInput.value = '';
+    configValueInput.value = '';
+
+    try {
+        const response = await fetch(transformPath('conf'));
+        const text = await response.text();
+        contentDiv.textContent = text;
+    } catch (error) {
+        contentDiv.textContent = `Failed to load configuration: ${error.message}`;
+    }
+}
+
+// Get configuration
+async function getConfig() {
+    if (!currentNode) return;
+
+    const configKeyInput = document.getElementById('configKeyInput');
+    const configKey = configKeyInput.value.trim();
+
+    try {
+        let url = transformPath('conf');
+        if (configKey) {
+            url += `?key=${encodeURIComponent(configKey)}`;
+        }
+        const response = await fetch(url);
+        const text = await response.text();
+        alert(text);
+    } catch (error) {
+        alert(`Failed to get configuration: ${error.message}`);
+    }
+}
+
+// Set configuration
+async function setConfig() {
+    if (!currentNode) return;
+
+    const configKeyInput = document.getElementById('configKeyInput');
+    const configValueInput = document.getElementById('configValueInput');
+
+    const configKey = configKeyInput.value.trim();
+    const configValue = configValueInput.value.trim();
+
+    if (!configKey) {
+        alert('Please enter a configuration key');
+        return;
+    }
+
+    if (!configValue) {
+        alert('Please enter a configuration value');
+        return;
+    }
+
+    try {
+        const url = transformPath('conf') + `?key=${encodeURIComponent(configKey)}&value=${encodeURIComponent(configValue)}`;
+        const response = await fetch(url, { method: 'GET' });
+        const text = await response.text();
+        alert(text);
+
+        if (response.ok) {
+            loadConfig();
+        }
+    } catch (error) {
+        alert(`Failed to set configuration: ${error.message}`);
+    }
+}
+
+// Load meta information
+async function loadMeta() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('metaContent');
+    contentDiv.textContent = 'Loading...';
+
+    try {
+        const response = await fetch(transformPath('meta'));
+        const text = await response.text();
+        contentDiv.textContent = text;
+    } catch (error) {
+        contentDiv.textContent = `Failed to load meta information: ${error.message}`;
+    }
+}
+
+// Load inference information
+async function loadInference() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('inferenceContent');
+    contentDiv.textContent = 'Loading...';
+
+    try {
+        const response = await fetch(transformPath('inference_info'));
+        const text = await response.text();
+        contentDiv.textContent = text;
+    } catch (error) {
+        contentDiv.textContent = `Failed to load inference information: ${error.message}`;
+    }
+}
+
+// Load environment variables
+let envVariablesData = null; // Store as object instead of string
+async function loadEnvironment() {
+    if (!currentNode) return;
+
+    const contentDiv = document.getElementById('envContent');
+    const searchInput = document.getElementById('envSearchInput');
+    contentDiv.textContent = 'Loading...';
+    searchInput.value = '';
+
+    try {
+        const response = await fetch(transformPath('env'));
+        const text = await response.text();
+        
+        // Parse JSON and format for display
+        try {
+            envVariablesData = JSON.parse(text);
+            // Format as KEY=VALUE lines for display
+            const formattedText = Object.entries(envVariablesData)
+                .map(([key, value]) => `${key}=${value}`)
+                .join('\n');
+            contentDiv.textContent = formattedText;
+        } catch (e) {
+            // Fallback to plain text if not JSON
+            envVariablesData = text;
+            contentDiv.textContent = text;
+        }
+    } catch (error) {
+        contentDiv.textContent = `Failed to load environment variables: ${error.message}`;
+        envVariablesData = null;
+    }
+}
+
+// Filter environment variables based on search input
+function filterEnvVariables() {
+    const searchInput = document.getElementById('envSearchInput');
+    const contentDiv = document.getElementById('envContent');
+    const searchTerm = searchInput.value.toLowerCase();
+
+    if (!envVariablesData) {
+        return;
+    }
+
+    if (!searchTerm) {
+        // Show all variables
+        if (typeof envVariablesData === 'object') {
+            const formattedText = Object.entries(envVariablesData)
+                .map(([key, value]) => `${key}=${value}`)
+                .join('\n');
+            contentDiv.textContent = formattedText;
+        } else {
+            contentDiv.textContent = envVariablesData;
+        }
+        return;
+    }
+
+    // Filter based on search term
+    if (typeof envVariablesData === 'object') {
+        const filteredEntries = Object.entries(envVariablesData).filter(([key, value]) => {
+            const line = `${key}=${value}`;
+            return line.toLowerCase().includes(searchTerm);
+        });
+        const formattedText = filteredEntries
+            .map(([key, value]) => `${key}=${value}`)
+            .join('\n');
+        contentDiv.textContent = formattedText;
+    } else {
+        // Fallback for plain text
+        const lines = envVariablesData.split('\n');
+        const filteredLines = lines.filter(line => 
+            line.toLowerCase().includes(searchTerm)
+        );
+        contentDiv.textContent = filteredLines.join('\n');
+    }
+}
+
+// Clear all tab contents
+function clearAllTabs() {
+    document.getElementById('overviewContent').innerHTML = 'Please select a target node first';
+    document.getElementById('metricsContent').textContent = 'Please select a target node first';
+    document.getElementById('threadsContent').textContent = 'Please select a target node first';
+    document.getElementById('logLevelContent').textContent = 'Please select a target node first';
+    document.getElementById('configContent').textContent = 'Please select a target node first';
+    document.getElementById('metaContent').textContent = 'Please select a target node first';
+    document.getElementById('inferenceContent').textContent = 'Please select a target node first';
+    document.getElementById('envContent').textContent = 'Please select a target node first';
+    document.getElementById('loggerInput').value = '';
+    document.getElementById('configKeyInput').value = '';
+    document.getElementById('configValueInput').value = '';
+    document.getElementById('envSearchInput').value = '';
+    envVariablesData = null;
+}
+
+function transformPath(path) {
+    if (!currentNode) return path;
+
+    // When proxy_id equals the node's own name the node IS the proxy
+    // (multiProcess child node) – use a single proxy2 hop.
+    if (
+        currentNode.proxy_id
+        && proxyNodes[currentNode.proxy_id]
+        && currentNode.proxy_id !== currentNode.name
+    ) {
+        const proxyNode = proxyNodes[currentNode.proxy_id];
+        return `/proxy2/${proxyNode.name}/proxy2/${currentNode.name}/${path}`;
+    }
+    return `/proxy2/${currentNode.name}/${path}`;
+}
+
+// Filter nodes by environment variable and show matching proxies
+async function filterNodesByEnv() {
+    const envFilter = document.getElementById('envFilterInput').value.trim();
+    if (!envFilter) {
+        alert('Please enter an environment variable filter (e.g., TAG or TAG=TaijiDS)');
+        return;
+    }
+
+    // Parse filter condition
+    let filterKey, filterValue;
+    const filterParts = envFilter.split('=');
+    
+    if (filterParts.length === 1) {
+        // Only key provided, filter by key existence
+        filterKey = filterParts[0].trim();
+        filterValue = null;
+    } else if (filterParts.length === 2) {
+        // Key=Value provided, filter by exact match
+        filterKey = filterParts[0].trim();
+        filterValue = filterParts[1].trim();
+    } else {
+        alert('Invalid filter format. Please use KEY or KEY=VALUE format (e.g., TAG or TAG=TaijiDS)');
+        return;
+    }
+
+    try {
+        // Show loading indicator
+        const proxySearchInput = document.getElementById('proxySearchInput');
+        const proxySelector = document.getElementById('proxySelector');
+        const targetSelector = document.getElementById('targetSelector');
+        const proxyDropdown = document.getElementById('proxyDropdown');
+        
+        proxySearchInput.value = 'Filtering proxies...';
+        proxySearchInput.disabled = true;
+        proxyDropdown.classList.remove('show');
+        targetSelector.innerHTML = '<option value="">-- Select Target --</option>';
+        targetSelector.disabled = true;
+
+        // Get all proxies
+        const response = await fetch('/api/proxies');
+        const data = await response.json();
+        const fetchedProxies = data.proxies;
+
+        // Check each proxy's nodes for matching environment variables
+        const matchingProxies = new Map(); // Map<proxyName, matchingNodes[]>
+        
+        for (const proxy of fetchedProxies) {
+            try {
+                // Get nodes for this proxy
+                const nodesResponse = await fetch(`/api/proxies/${proxy.name}/nodes`);
+                const nodesData = await nodesResponse.json();
+                const nodes = nodesData.nodes;
+
+                // Check each node's environment variables
+                const matchingNodes = [];
+                const checkPromises = nodes.map(async (node) => {
+                    try {
+                        // Build the path to check env
+                        let envPath;
+                        if (node.proxy_id && proxyNodes[node.proxy_id]) {
+                            const proxyNode = proxyNodes[node.proxy_id];
+                            envPath = `/proxy2/${proxyNode.name}/proxy2/${node.name}/env`;
+                        } else {
+                            envPath = `/proxy2/${node.name}/env`;
+                        }
+
+                        const envResponse = await fetch(envPath);
+                        if (!envResponse.ok) {
+                            console.warn(`Failed to fetch env for node ${node.name}`);
+                            return null;
+                        }
+
+                        const envText = await envResponse.text();
+                        
+                        // Parse JSON response
+                        let envData;
+                        try {
+                            envData = JSON.parse(envText);
+                        } catch (e) {
+                            console.warn(`Failed to parse env JSON for node ${node.name}:`, e);
+                            return null;
+                        }
+                        
+                        // Check if the environment variable matches
+                        if (filterValue === null) {
+                            // Only key provided, check if key exists
+                            if (filterKey in envData) {
+                                return node;
+                            }
+                        } else {
+                            // Key=Value provided, match exact value
+                            if (filterKey in envData && envData[filterKey] === filterValue) {
+                                return node;
+                            }
+                        }
+                        
+                        return null;
+                    } catch (error) {
+                        console.error(`Error checking node ${node.name}:`, error);
+                        return null;
+                    }
+                });
+
+                const results = await Promise.all(checkPromises);
+                const validNodes = results.filter(node => node !== null);
+                
+                if (validNodes.length > 0) {
+                    matchingProxies.set(proxy.name, validNodes);
+                }
+            } catch (error) {
+                console.error(`Error checking proxy ${proxy.name}:`, error);
+            }
+        }
+
+        // Update proxy selector with filtered proxies
+        proxySearchInput.value = '';
+        proxySearchInput.disabled = false;
+
+        if (matchingProxies.size === 0) {
+            const filterDesc = filterValue === null ? filterKey : `${filterKey}=${filterValue}`;
+            alert(`No nodes found with ${filterDesc}`);
+            // Restore original proxy list
+            loadProxies();
+        } else {
+            // Update global allProxies with filtered results
+            allProxies = [];
+            let totalNodes = 0;
+            const proxyNodeMap = new Map(); // Store matching nodes for each proxy
+            
+            matchingProxies.forEach((nodes, proxyName) => {
+                const proxy = fetchedProxies.find(p => p.name === proxyName);
+                if (proxy) {
+                    allProxies.push(proxy);
+                    proxyNodeMap.set(proxyName, nodes);
+                    totalNodes += nodes.length;
+                }
+            });
+            
+            // Rebuild filtered proxy list
+            filterProxies();
+            
+            const filterDesc = filterValue === null ? filterKey : `${filterKey}=${filterValue}`;
+            alert(`Found ${matchingProxies.size} proxy(ies) with ${totalNodes} matching node(s) for ${filterDesc}`);
+        }
+    } catch (error) {
+        console.error('Failed to filter nodes:', error);
+        alert('Failed to filter nodes: ' + error.message);
+        // Restore original proxy list
+        loadProxies();
+    }
+}
+
+// Clear environment filter
+function clearEnvFilter() {
+    document.getElementById('envFilterInput').value = '';
+    
+    // Restore original proxy list
+    loadProxies();
+    
+    // Clear target selector
+    const targetSelector = document.getElementById('targetSelector');
+    targetSelector.innerHTML = '<option value="">-- Select Target --</option>';
+    targetSelector.disabled = true;
+}
diff --git a/lmcache/logging.py b/lmcache/logging.py
new file mode 100644
index 0000000..a162bdf
--- /dev/null
+++ b/lmcache/logging.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from logging import Logger
+import logging
+import os
+
+
+def build_format(color):
+    reset = "\x1b[0m"
+    underline = "\x1b[3m"
+    return (
+        f"{color}[%(asctime)s] LMCache %(levelname)s:{reset} %(message)s "
+        f"{underline}(%(filename)s:%(lineno)d:%(name)s){reset}"
+    )
+
+
+class CustomFormatter(logging.Formatter):
+    grey = "\x1b[1m"
+    green = "\x1b[32;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+
+    FORMATS = {
+        logging.DEBUG: build_format(grey),
+        logging.INFO: build_format(green),
+        logging.WARNING: build_format(yellow),
+        logging.ERROR: build_format(red),
+        logging.CRITICAL: build_format(bold_red),
+    }
+
+    def format(self, record):
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def get_log_level() -> int:
+    """
+    Try to read LMCACHE_LOG_LEVEL from environment variables.
+    Could be:
+    - DEBUG
+    - INFO
+    - WARNING
+    - ERROR
+    - CRITICAL
+
+    If not found, defaults to INFO.
+    """
+    log_level = os.getenv("LMCACHE_LOG_LEVEL", "INFO").upper()
+    return getattr(logging, log_level, logging.INFO)
+
+
+def init_logger(name: str) -> Logger:
+    # Get the logger
+    logger = logging.getLogger(name)
+
+    # Clear any existing handlers
+    logger.handlers.clear()
+
+    # Prevent propagation to parent loggers
+    logger.propagate = False
+
+    # Add our custom handler
+    log_level = get_log_level()
+    ch = logging.StreamHandler()
+    ch.setLevel(log_level)
+    ch.setFormatter(CustomFormatter())
+    logger.addHandler(ch)
+
+    # OTel log forwarding (no-op if opentelemetry is not installed or
+    # no LoggerProvider has been configured at startup)
+    try:
+        # Third Party
+        from opentelemetry.sdk._logs import LoggingHandler
+
+        logger.addHandler(LoggingHandler(level=log_level))
+    except ImportError:
+        pass
+
+    logger.setLevel(log_level)
+    return logger
+
+
+if __name__ == "__main__":
+    logger = init_logger(__name__)
+    logger.debug("Debug message")
+    logger.info("Info message")
+    logger.warning("Warning message")
+    logger.error("Error message")
+    logger.critical("Critical message")
+
+# import logging
+# from logging import Logger
+#
+# logging.basicConfig(
+#    format="\033[33m%(levelname)s LMCache: \033[0m%(message)s "
+#    "[%(asctime)s] -- %(pathname)s:%(lineno)d",
+#    level=logging.INFO,
+# )
+#
+#
+# def init_logger(name: str) -> Logger:
+#    logger = logging.getLogger(name)
+#    logger.setLevel(logging.DEBUG)
+#    return logger
diff --git a/lmcache/native_storage_ops.pyi b/lmcache/native_storage_ops.pyi
new file mode 100644
index 0000000..217a364
--- /dev/null
+++ b/lmcache/native_storage_ops.pyi
@@ -0,0 +1,349 @@
+# SPDX-License-Identifier: Apache-2.0
+# Stub for the native_storage_ops C++ extension (implemented in csrc/storage_manager/).
+
+"""Native storage operations for LMCache."""
+
+# Standard
+from collections.abc import Sequence
+from typing import Any, Set, overload
+
+class TTLLock:
+    """
+    A thread-safe lock with TTL (Time-To-Live) support.
+
+    The lock maintains a counter that can be incremented (lock) and decremented
+    (unlock). If the TTL expires, the lock is considered unlocked regardless
+    of the counter value.
+    """
+
+    def __init__(self, ttl_second: int = 300) -> None:
+        """
+        Construct a TTLLock with the specified TTL duration in seconds.
+
+        Args:
+            ttl_second: TTL duration in seconds. Default is 300.
+        """
+        ...
+
+    def lock(self) -> None:
+        """
+        Increment the lock counter by 1 and update the TTL.
+        If the previous TTL has expired, reset counter to 1.
+        """
+        ...
+
+    def unlock(self) -> None:
+        """Decrement the lock counter by 1 (minimum 0)."""
+        ...
+
+    def is_locked(self) -> bool:
+        """
+        Check if the lock is held (counter > 0 and TTL not expired).
+
+        Returns:
+            True if the lock is held, False otherwise.
+        """
+        ...
+
+    def reset(self) -> None:
+        """Reset the lock to initial state (counter = 0, TTL expired)."""
+        ...
+
+class Bitmap:
+    """
+    A bitmap for tracking the state of L2 storage operation results.
+
+    Each bit represents the success or failure of a key.
+    """
+
+    @overload
+    def __init__(self, size: int) -> None:
+        """
+        Construct a Bitmap with the specified number of bits.
+
+        Args:
+            size: The number of bits in the bitmap.
+        """
+        ...
+    @overload
+    def __init__(self, size: int, prefix_bits: int) -> None:
+        """
+        Construct a Bitmap with the specified number of bits and prefix.
+
+        Args:
+            size: The number of bits in the bitmap.
+            prefix_bits: The first N bits are set to 1.
+        """
+        ...
+
+    def set(self, index: int) -> None:
+        """Set the bit at the specified index to 1."""
+        ...
+
+    def batched_set(self, indices: Sequence[int]) -> None:
+        """Set every bit in ``indices`` to 1 (positions >= size ignored)."""
+        ...
+
+    def set_range(self, start: int, end: int) -> None:
+        """Set every bit in the half-open range ``[start, end)`` to 1.
+
+        ``end`` is clamped to the bitmap size. Fills whole bytes, so far cheaper
+        than per-bit ``set`` for a contiguous span.
+        """
+        ...
+
+    def clear(self, index: int) -> None:
+        """Clear the bit at the specified index to 0."""
+        ...
+
+    def test(self, index: int) -> bool:
+        """
+        Test the bit at the specified index.
+
+        Returns:
+            True if the bit is set to 1, False otherwise.
+        """
+        ...
+
+    def popcount(self) -> int:
+        """Return the number of bits set to 1."""
+        ...
+
+    def count_leading_zeros(self) -> int:
+        """Return the number of leading zeros."""
+        ...
+
+    def count_leading_ones(self) -> int:
+        """Return the number of leading ones."""
+        ...
+
+    def highest_set_bit(self) -> int:
+        """Index of the highest set bit, or ``-1`` if no bit is set.
+
+        The value is signed so the empty bitmap is representable (an unsigned
+        index could not encode it).
+        """
+        ...
+
+    def __and__(self, other: Bitmap) -> Bitmap:
+        """
+        Bitwise AND with another bitmap.
+        If sizes differ, the result is truncated to the smaller size.
+        """
+        ...
+
+    def __invert__(self) -> Bitmap:
+        """Bitwise NOT (flip all bits)."""
+        ...
+
+    def __or__(self, other: Bitmap) -> Bitmap:
+        """
+        Bitwise OR with another bitmap.
+        If sizes differ, the result is truncated to the smaller size.
+        """
+        ...
+
+    def get_indices_list(self) -> list[int]:
+        """Return a list of indices where the bit is set to 1, in ascending order."""
+        ...
+
+    def get_indices_set(self) -> Set[int]:
+        """Return a set of indices where the bit is set to 1."""
+        ...
+
+    def gather(self, items: Sequence[Any]) -> list[Any]:
+        """
+        Return elements from items at indices where the bit is set to 1.
+
+        Args:
+            items: A sequence of objects. Length should match the bitmap size.
+
+        Returns:
+            A list of objects from items at positions where the bitmap bit is 1.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """String representation: '1' for set bits, '0' for clear bits."""
+        ...
+
+def fold(
+    found: Bitmap,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> Bitmap:
+    """Fold per-(group, chunk, rank) presence into servable prefix lengths.
+
+    Args:
+        found: Group-major / chunk-major / rank-minor presence bitmap of length
+            ``len(group_windows) * num_chunks * num_ranks``.
+        num_chunks: Number of LMCache chunks in the request.
+        num_ranks: Number of kv_rank shards per chunk.
+        group_windows: Per-object-group cross-chunk window size in chunks;
+            ``<= 0`` means full attention.
+
+    Returns:
+        A bitmap of size ``num_chunks + 1``; bit ``L`` set iff every object
+        group can serve a length-``L`` prefix. Bit 0 is always set.
+    """
+    ...
+
+def unfold(
+    hit_length: int,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> Bitmap:
+    """Expand a model-wide hit length into the per-group retain mask.
+
+    Args:
+        hit_length: Model-wide prefix hit length in chunks (clamped to
+            ``num_chunks``).
+        num_chunks: Number of LMCache chunks in the request.
+        num_ranks: Number of kv_rank shards per chunk.
+        group_windows: Per-object-group cross-chunk window size in chunks;
+            ``<= 0`` means full attention.
+
+    Returns:
+        Retain mask of length ``len(group_windows) * num_chunks * num_ranks``
+        (all ranks of each retained ``(group, chunk)`` set).
+    """
+    ...
+
+class ParallelPatternMatcher:
+    """
+    Pattern matcher for integer vectors.
+
+    This class performs pattern matching on a vector of integers.
+    It finds all positions where a given pattern occurs in the input data.
+    """
+
+    def __init__(self, pattern: list[int]) -> None:
+        """
+        Construct a ParallelPatternMatcher with the specified pattern.
+
+        Args:
+            pattern: The pattern to search for. Must not be empty.
+
+        Raises:
+            ValueError: If pattern is empty.
+        """
+        ...
+
+    def match(self, data: list[int]) -> list[int]:
+        """
+        Match the pattern in the given data.
+
+        Args:
+            data: The data to search in.
+
+        Returns:
+            A sorted list of positions where the pattern starts.
+            Returns an empty list if no matches are found.
+        """
+        ...
+
+class PeriodicEventNotifier:
+    """Singleton that periodically signals registered file descriptors.
+
+    A background thread writes to every registered fd at a configurable
+    interval.  The thread sleeps when no fds are registered and wakes
+    automatically when the first fd is added.
+    """
+
+    @staticmethod
+    def create(interval_ms: int, use_eventfd: bool) -> None:
+        """Create the singleton. Idempotent -- second call is a no-op.
+
+        Args:
+            interval_ms: Notification interval in milliseconds.
+            use_eventfd: True to write as eventfd (8-byte uint64),
+                False to write as pipe (1-byte).
+        """
+        ...
+
+    @staticmethod
+    def get() -> PeriodicEventNotifier | None:
+        """Return the singleton instance, or None if not created."""
+        ...
+
+    @staticmethod
+    def shutdown() -> None:
+        """Shut down the singleton and join its thread. Idempotent."""
+        ...
+
+    def register_fd(self, fd: int) -> None:
+        """Register a file descriptor for periodic signaling.
+
+        Args:
+            fd: The file descriptor to signal. For eventfd, pass the
+                eventfd itself. For pipes, pass the write end.
+        """
+        ...
+
+    def unregister_fd(self, fd: int) -> None:
+        """Unregister a file descriptor. No-op if not registered.
+
+        Args:
+            fd: The file descriptor to stop signaling.
+        """
+        ...
+
+    def set_interval_ms(self, interval_ms: int) -> None:
+        """Change the notification interval. Clamped to >= 1ms.
+
+        Args:
+            interval_ms: New interval in milliseconds.
+        """
+        ...
+
+class RangePatternMatcher:
+    """
+    Range pattern matcher for integer vectors.
+
+    This class performs range pattern matching on a vector of integers.
+    It finds ranges that start with a start pattern and end with an end pattern.
+    When multiple end patterns exist after a start pattern, it matches the first
+    one (minimal range).
+    """
+
+    def __init__(self, start_pattern: list[int], end_pattern: list[int]) -> None:
+        """
+        Construct a RangePatternMatcher with start and end patterns.
+
+        Args:
+            start_pattern: The pattern marking the start of a range.
+            end_pattern: The pattern marking the end of a range.
+
+        Raises:
+            ValueError: If either pattern is empty or has more than 5 elements.
+        """
+        ...
+
+    def match(self, data: list[int]) -> list[tuple[int, int]]:
+        """
+        Match ranges in the given data.
+
+        Finds all ranges that start with the start pattern and end with the end
+        pattern. When multiple end patterns exist after a start pattern, matches
+        the first one (minimal range).
+
+        Args:
+            data: The data to search in.
+
+        Returns:
+            A list of (start_pos, end_pos) tuples where:
+            - start_pos is the beginning index of the start pattern
+            - end_pos is the exclusive index after the end pattern
+            Returns an empty list if no ranges are found.
+
+        Example:
+            >>> start = [1, 2]
+            >>> end = [3, 4]
+            >>> matcher = RangePatternMatcher(start, end)
+            >>> data = [1, 2, 0, 3, 4, 0, 3, 4, 1, 2, 0, 0, 3, 4]
+            >>> matcher.match(data)
+            [(0, 5), (8, 14)]
+        """
+        ...
diff --git a/lmcache/observability.py b/lmcache/observability.py
new file mode 100644
index 0000000..757e2bb
--- /dev/null
+++ b/lmcache/observability.py
@@ -0,0 +1,2020 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import contextmanager
+from copy import copy
+from dataclasses import dataclass, field
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    Union,
+)
+import os
+import threading
+import time
+
+# Third Party
+from prometheus_client import REGISTRY
+import prometheus_client
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.usage_telemetry import ContinuousUsageContext
+from lmcache.utils import thread_safe
+from lmcache.v1.metadata import LMCacheMetadata
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.config import LMCacheEngineConfig
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class LMCacheStats:
+    # Counter (Note that these are incremental values,
+    # which will accumulate over time in Counter)
+    interval_retrieve_requests: int
+    interval_store_requests: int
+    interval_lookup_requests: int
+    interval_requested_tokens: int
+    interval_hit_tokens: int
+    interval_stored_tokens: int
+    interval_lookup_tokens: int
+    interval_lookup_hits: int
+    interval_vllm_hit_tokens: int
+    interval_prompt_tokens: int
+
+    interval_num_slow_retrieval_by_time: int
+    interval_num_slow_retrieval_by_speed: int
+
+    interval_remote_read_requests: int
+    interval_remote_read_bytes: int
+    interval_remote_write_requests: int
+    interval_remote_write_bytes: int
+
+    interval_remote_time_to_get: List[float]
+    interval_remote_time_to_put: List[float]
+    interval_remote_time_to_get_sync: List[float]
+
+    interval_remote_ping_latency: float  # Ping latency in milliseconds
+    interval_remote_ping_errors: int  # Number of ping errors
+    interval_remote_ping_success: int  # Number of ping successes
+    interval_remote_ping_error_code: int  # Latest ping error code
+
+    interval_local_cpu_evict_count: int  # evict count
+    interval_local_cpu_evict_keys_count: int  # evict keys count
+    interval_local_cpu_evict_failed_count: int  # evict failed count
+
+    interval_forced_unpin_count: int  # forced unpin count due to timeout
+
+    # Real time value measurements (will be reset after each log)
+    retrieve_hit_rate: float
+    lookup_hit_rate: float
+
+    local_cache_usage_bytes: int  # Size of the used local cache in bytes
+    remote_cache_usage_bytes: int  # Size of the used remote cache in bytes
+    local_storage_usage_bytes: int  # Size of the used local storage in bytes
+
+    active_memory_objs_count: int  # the number of active memory objects
+    pinned_memory_objs_count: int  # the number of pinned memory objects
+
+    # Distribution measurements
+    time_to_retrieve: List[float]
+    time_to_store: List[float]
+    time_to_lookup: List[float]
+    retrieve_speed: List[float]  # Tokens per second
+    store_speed: List[float]  # Tokens per second
+
+    # Granular profiling measurements
+    retrieve_process_tokens_time: List[float]
+    retrieve_broadcast_time: List[float]
+    retrieve_to_gpu_time: List[float]
+    remote_backend_batched_get_blocking_time: List[float]
+    instrumented_connector_batched_get_time: List[float]
+    store_process_tokens_time: List[float]
+    store_from_gpu_time: List[float]
+    store_put_time: List[float]
+
+    # P2P transfer metrics
+    interval_p2p_requests: int
+    interval_p2p_transferred_tokens: int
+    p2p_time_to_transfer: List[float]
+    p2p_transfer_speed: List[float]  # Tokens per second
+
+    # request lookup hit rates
+    # use bucket of interval_lookup_hit_rates to represents non-0 hit requests
+    # use interval_lookup_0_hit_requests to represents 0 hit requests
+    interval_lookup_hit_rates: List[float]
+    interval_lookup_0_hit_requests: int
+
+    interval_request_cache_lifespan: List[float]  # cache lifespan in minutes
+
+
+@dataclass
+class LookupRequestStats:
+    request_id: int
+    num_tokens: int
+    hit_tokens: int
+    is_finished: bool
+    start_time: float = 0
+    end_time: float = 0
+
+    def time_to_lookup(self):
+        if self.end_time == 0:
+            return 0
+        return self.end_time - self.start_time
+
+    def hit_rate(self):
+        if self.num_tokens == 0:
+            return 0
+        return self.hit_tokens / self.num_tokens
+
+
+@dataclass
+class RetrieveRequestStats:
+    request_id: int
+    num_tokens: int
+    local_hit_tokens: int
+    remote_hit_tokens: int  # Not used for now
+    start_time: float
+    end_time: float
+    process_tokens_time: float = 0
+    broadcast_time: float = 0
+    to_gpu_time: float = 0
+    detailed_metrics: Dict[str, Any] = field(default_factory=dict)
+
+    def time_to_retrieve(self):
+        if self.end_time == 0:
+            return 0
+        return self.end_time - self.start_time
+
+    def retrieve_speed(self):
+        if self.time_to_retrieve() == 0:
+            return 0
+        return (
+            self.local_hit_tokens + self.remote_hit_tokens
+        ) / self.time_to_retrieve()
+
+    @contextmanager
+    def profile_process_tokens(self):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.process_tokens_time += time.perf_counter() - start
+
+    @contextmanager
+    def profile_broadcast(self):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.broadcast_time += time.perf_counter() - start
+
+    @contextmanager
+    def profile_to_gpu(self):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.to_gpu_time += time.perf_counter() - start
+
+
+@dataclass
+class StoreRequestStats:
+    request_id: int
+    num_tokens: int
+    start_time: float
+    end_time: float
+    process_tokens_time: float = 0
+    from_gpu_time: float = 0
+    put_time: float = 0
+
+    def time_to_store(self):
+        if self.end_time == 0:
+            return 0
+        return self.end_time - self.start_time
+
+    def store_speed(self):
+        if self.time_to_store() == 0:
+            return 0
+        return self.num_tokens / self.time_to_store()
+
+    @contextmanager
+    def profile_process_tokens(self):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.process_tokens_time += time.perf_counter() - start
+
+    @contextmanager
+    def profile_from_gpu(self):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.from_gpu_time += time.perf_counter() - start
+
+    @contextmanager
+    def profile_put(self):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            self.put_time += time.perf_counter() - start
+
+
+@dataclass
+class P2PTransferRequestStats:
+    num_tokens: int
+    start_time: float
+    end_time: float
+
+    def time_to_transfer(self):
+        if self.end_time == 0:
+            return 0
+        return self.end_time - self.start_time
+
+    def transfer_speed(self):
+        if self.time_to_transfer() == 0:
+            return 0
+        return self.num_tokens / self.time_to_transfer()
+
+
+class LMCStatsMonitor:
+    def __init__(self):
+        # Interval metrics that will be reset after each log
+        # Accumulate incremental values in the Prometheus Counter
+        self.interval_retrieve_requests = 0
+        self.interval_store_requests = 0
+        self.interval_lookup_requests = 0
+        self.interval_requested_tokens = 0  # total requested tokens retrieve
+        self.interval_hit_tokens = 0  # total hit tokens retrieve
+        self.interval_stored_tokens = 0  # total tokens tored in LMCache
+        self.interval_lookup_tokens = 0  # total requested tokens lookup
+        self.interval_lookup_hits = 0  # total hit tokens lookup
+        self.interval_vllm_hit_tokens = 0  # total hit tokens in vllm
+        self.interval_prompt_tokens = 0  # total prompt tokens
+        self.interval_lookup_0_hit_requests = 0
+
+        self.interval_num_slow_retrieval_by_time = 0
+        self.interval_num_slow_retrieval_by_speed = 0
+
+        # P2P transfer metrics
+        self.interval_p2p_requests = 0
+        self.interval_p2p_transferred_tokens = 0
+        self.p2p_requests: Dict[int, P2PTransferRequestStats] = {}
+        self.p2p_request_id = 0
+
+        # remote backends read/write metrics
+        self.interval_remote_read_requests = 0
+        self.interval_remote_read_bytes = 0
+        self.interval_remote_write_requests = 0
+        self.interval_remote_write_bytes = 0
+
+        # remote backends get/put cost time metrics
+        self.interval_remote_time_to_get: List[float] = []
+        self.interval_remote_time_to_put: List[float] = []
+        # the time of get value from remote backends synchronously,
+        # which includes rpc and schedule time
+        self.interval_remote_time_to_get_sync: List[float] = []
+
+        self.interval_remote_ping_latency = 0
+        self.interval_remote_ping_errors = 0
+        self.interval_remote_ping_success = 0
+        self.interval_remote_ping_error_code = 0  # 0 means success
+
+        self.interval_local_cpu_evict_count = 0
+        self.interval_local_cpu_evict_keys_count = 0
+        self.interval_local_cpu_evict_failed_count = 0
+
+        self.interval_forced_unpin_count = 0
+
+        self.local_cache_usage_bytes = 0
+        self.remote_cache_usage_bytes = 0
+        self.local_storage_usage_bytes = 0
+
+        self.active_memory_objs_count = 0
+        self.pinned_memory_objs_count = 0
+
+        self.retrieve_requests: Dict[int, RetrieveRequestStats] = {}
+        self.store_requests: Dict[int, StoreRequestStats] = {}
+        self.lookup_requests: Dict[int, LookupRequestStats] = {}
+
+        self.retrieve_request_id = 0
+        self.store_request_id = 0
+        self.lookup_request_id = 0
+
+        self.interval_request_cache_lifespan: Dict[int, float] = {}
+        self.reuse_chunk_id = 0
+
+        self._current_retrieve_stats: Optional[RetrieveRequestStats] = None
+        self.retrieve_time_threshold: float = 1e9
+        self.retrieve_token_speed_threshold: float = -1.0
+        self.last_retrieve_warning_time: float = 0.0
+        self.skipped_retrieve_warning_count: int = 0
+
+    def set_current_retrieve_stats(self, stats: RetrieveRequestStats):
+        self._current_retrieve_stats = stats
+
+    def get_current_retrieve_stats(self) -> Optional[RetrieveRequestStats]:
+        return self._current_retrieve_stats
+
+    def clear_current_retrieve_stats(self):
+        self._current_retrieve_stats = None
+
+    @thread_safe
+    def on_lookup_request(self, num_tokens: int) -> LookupRequestStats:
+        """
+        This function is called when a lookup request is sent to the cache.
+        It will record the number of tokens requested.
+        """
+        curr_time = time.perf_counter()
+        lookup_stats = LookupRequestStats(
+            request_id=self.lookup_request_id,
+            num_tokens=num_tokens,
+            hit_tokens=0,
+            is_finished=False,
+            start_time=curr_time,
+        )
+        self.interval_lookup_requests += 1
+        self.interval_lookup_tokens += num_tokens
+        self.lookup_requests[self.lookup_request_id] = lookup_stats
+        self.lookup_request_id += 1
+        return lookup_stats
+
+    @thread_safe
+    def on_lookup_finished(
+        self,
+        stats: LookupRequestStats,
+        num_hit_tokens: int,
+    ):
+        """
+        This function is called when a lookup request is finished.
+        It will record the number of tokens hit and track by node type.
+
+        Args:
+            stats: LookupRequestStats object
+            num_hit_tokens: Total number of tokens found in lookup
+        """
+        curr_time = time.perf_counter()
+        assert stats.request_id in self.lookup_requests
+        stats.hit_tokens = num_hit_tokens
+        stats.is_finished = True
+        if stats.end_time == 0:
+            stats.end_time = curr_time
+        self.interval_lookup_hits += num_hit_tokens
+        if num_hit_tokens == 0:
+            self.interval_lookup_0_hit_requests += 1
+
+    @thread_safe
+    def on_retrieve_request(self, num_tokens: int) -> RetrieveRequestStats:
+        """
+        Returns the internal "request id" that will be used in
+        on_retrieve_finished
+        """
+        curr_time = time.perf_counter()
+        retrieve_stats = RetrieveRequestStats(
+            request_id=self.retrieve_request_id,
+            num_tokens=num_tokens,
+            local_hit_tokens=0,
+            remote_hit_tokens=0,
+            start_time=curr_time,
+            end_time=0,
+        )
+        self.interval_requested_tokens += num_tokens
+        self.interval_retrieve_requests += 1
+        self.retrieve_requests[self.retrieve_request_id] = retrieve_stats
+        self.retrieve_request_id += 1
+        self.set_current_retrieve_stats(retrieve_stats)
+        return retrieve_stats
+
+    @thread_safe
+    def on_retrieve_finished(
+        self,
+        retrieve_stats: RetrieveRequestStats,
+        num_retrieved_tokens: int,
+    ):
+        curr_time = time.perf_counter()
+        assert retrieve_stats.request_id in self.retrieve_requests
+        retrieve_stats.local_hit_tokens = num_retrieved_tokens
+        if retrieve_stats.end_time == 0:
+            retrieve_stats.end_time = curr_time
+        self.interval_hit_tokens += num_retrieved_tokens
+        self.clear_current_retrieve_stats()
+
+        time_to_retrieve = retrieve_stats.time_to_retrieve()
+        retrieve_speed = retrieve_stats.retrieve_speed()
+        if time_to_retrieve > self.retrieve_time_threshold:
+            self.interval_num_slow_retrieval_by_time += 1
+        if 0 < retrieve_speed < self.retrieve_token_speed_threshold:
+            self.interval_num_slow_retrieval_by_speed += 1
+
+        # Log a warning if the retrieval performance is below defined thresholds:
+        # 1. Total time taken (time_to_retrieve) exceeds the maximum allowed time.
+        # 2. Retrieval speed (retrieve_speed) falls below the minimum required tokens/s.
+        # The warnings are rate-limited to once every 10 seconds to avoid log flooding.
+        if (
+            time_to_retrieve > self.retrieve_time_threshold
+            or 0 < retrieve_speed < self.retrieve_token_speed_threshold
+        ):
+            if curr_time - self.last_retrieve_warning_time > 10.0:
+                logger.warning(
+                    "Retrieve request %d surpassed threshold: "
+                    "time_to_retrieve=%.4f s (threshold=%.4f s), "
+                    "retrieve_speed=%.2f tokens/s (threshold=%.2f tokens/s). "
+                    "Skipped %d slow retrieval logs in the last %.1f seconds. "
+                    "Detailed metrics: "
+                    "num_tokens=%d, local_hit_tokens=%d, remote_hit_tokens=%d, "
+                    "process_tokens_time=%.5f s, "
+                    "broadcast_time=%.5f s, "
+                    "to_gpu_time=%.5f s, "
+                    "detailed_metrics=%s",
+                    retrieve_stats.request_id,
+                    time_to_retrieve,
+                    self.retrieve_time_threshold,
+                    retrieve_speed,
+                    self.retrieve_token_speed_threshold,
+                    self.skipped_retrieve_warning_count,
+                    curr_time - self.last_retrieve_warning_time,
+                    retrieve_stats.num_tokens,
+                    retrieve_stats.local_hit_tokens,
+                    retrieve_stats.remote_hit_tokens,
+                    retrieve_stats.process_tokens_time,
+                    retrieve_stats.broadcast_time,
+                    retrieve_stats.to_gpu_time,
+                    retrieve_stats.detailed_metrics,
+                )
+                self.last_retrieve_warning_time = curr_time
+                self.skipped_retrieve_warning_count = 0
+            else:
+                self.skipped_retrieve_warning_count += 1
+
+    @thread_safe
+    def on_store_request(self, num_tokens: int) -> StoreRequestStats:
+        """
+        Returns the internal "request id" that will be used in on_store_finished
+        """
+        curr_time = time.perf_counter()
+        store_stats = StoreRequestStats(
+            request_id=self.store_request_id,
+            num_tokens=num_tokens,
+            start_time=curr_time,
+            end_time=0,
+        )
+        self.interval_store_requests += 1
+        self.interval_stored_tokens += num_tokens
+        self.store_requests[self.store_request_id] = store_stats
+        self.store_request_id += 1
+        return store_stats
+
+    @thread_safe
+    def on_store_finished(
+        self,
+        store_stats: StoreRequestStats,
+        num_stored_tokens: int = -1,
+    ):
+        curr_time = time.perf_counter()
+        assert store_stats.request_id in self.store_requests
+        if store_stats.end_time == 0:
+            store_stats.end_time = curr_time
+        if num_stored_tokens >= 0:
+            store_stats.num_tokens = num_stored_tokens
+
+    @thread_safe
+    def on_p2p_transfer_request(self, num_tokens: int) -> int:
+        curr_time = time.time()
+        self.interval_p2p_requests += 1
+        self.p2p_requests[self.p2p_request_id] = P2PTransferRequestStats(
+            num_tokens=num_tokens,
+            start_time=curr_time,
+            end_time=0,
+        )
+        self.p2p_request_id += 1
+        return self.p2p_request_id - 1
+
+    @thread_safe
+    def on_p2p_transfer_finished(self, request_id: int):
+        curr_time = time.time()
+        assert request_id in self.p2p_requests
+        p2p_stats = self.p2p_requests[request_id]
+        self.interval_p2p_transferred_tokens += p2p_stats.num_tokens
+        p2p_stats.end_time = curr_time
+
+    @thread_safe
+    def on_chunk_reuse(self, time_interval: float):
+        """
+        time_interval: float or int, in seconds
+        """
+        self.interval_request_cache_lifespan[self.reuse_chunk_id] = time_interval / 60.0
+        self.reuse_chunk_id += 1
+
+    @thread_safe
+    def update_local_cache_usage(self, usage: int):
+        self.local_cache_usage_bytes = usage
+
+    @thread_safe
+    def update_remote_cache_usage(self, usage: int):
+        self.remote_cache_usage_bytes = usage
+
+    @thread_safe
+    def update_local_storage_usage(self, usage: int):
+        self.local_storage_usage_bytes = usage
+
+    @thread_safe
+    def update_interval_remote_read_metrics(self, read_bytes: int):
+        self.interval_remote_read_requests += 1
+        self.interval_remote_read_bytes += read_bytes
+
+    @thread_safe
+    def update_interval_remote_write_metrics(self, write_bytes: int):
+        self.interval_remote_write_requests += 1
+        self.interval_remote_write_bytes += write_bytes
+
+    @thread_safe
+    def update_interval_remote_time_to_get(self, get_time: float):
+        self.interval_remote_time_to_get.append(get_time)
+
+    @thread_safe
+    def update_interval_remote_time_to_put(self, put_time: float):
+        self.interval_remote_time_to_put.append(put_time)
+
+    @thread_safe
+    def update_interval_remote_time_to_get_sync(self, get_time_sync: float):
+        self.interval_remote_time_to_get_sync.append(get_time_sync)
+
+    @thread_safe
+    def update_remote_ping_latency(self, latency: float):
+        self.interval_remote_ping_latency = latency
+
+    @thread_safe
+    def update_remote_ping_error_code(self, error_code: int):
+        """Update ping error code"""
+        self.interval_remote_ping_error_code = error_code
+        if error_code != 0:
+            self.interval_remote_ping_errors += 1
+        else:
+            self.interval_remote_ping_success += 1
+
+    @thread_safe
+    def update_local_cpu_evict_metrics(self, evict_keys_count: int):
+        self.interval_local_cpu_evict_count += 1
+        self.interval_local_cpu_evict_keys_count += evict_keys_count
+
+    @thread_safe
+    def update_local_cpu_evict_failed_count(self, evict_failed_count: int):
+        self.interval_local_cpu_evict_failed_count += evict_failed_count
+
+    @thread_safe
+    def update_forced_unpin_count(self, delta: int):
+        self.interval_forced_unpin_count += delta
+
+    @thread_safe
+    def update_active_memory_objs_count(self, active_memory_objs_count: int):
+        self.active_memory_objs_count = active_memory_objs_count
+
+    @thread_safe
+    def update_pinned_memory_objs_count(self, delta: int):
+        self.pinned_memory_objs_count += delta
+
+    @thread_safe
+    def update_interval_vllm_hit_tokens(self, delta: int):
+        self.interval_vllm_hit_tokens += delta
+
+    @thread_safe
+    def update_interval_prompt_tokens(self, delta: int):
+        self.interval_prompt_tokens += delta
+
+    def _clear(self):
+        """
+        Clear all the distribution stats
+        """
+        self.interval_retrieve_requests = 0
+        self.interval_store_requests = 0
+        self.interval_lookup_requests = 0
+
+        self.interval_requested_tokens = 0
+        self.interval_hit_tokens = 0
+        self.interval_stored_tokens = 0
+        self.interval_lookup_tokens = 0
+        self.interval_lookup_hits = 0
+        self.interval_vllm_hit_tokens = 0
+        self.interval_prompt_tokens = 0
+
+        self.interval_num_slow_retrieval_by_time = 0
+        self.interval_num_slow_retrieval_by_speed = 0
+
+        self.interval_remote_read_requests = 0
+        self.interval_remote_read_bytes = 0
+        self.interval_remote_write_requests = 0
+        self.interval_remote_write_bytes = 0
+
+        self.interval_remote_time_to_get.clear()
+        self.interval_remote_time_to_put.clear()
+        self.interval_remote_time_to_get_sync.clear()
+
+        self.interval_remote_ping_latency = 0
+        self.interval_remote_ping_errors = 0
+        self.interval_remote_ping_success = 0
+        self.interval_remote_ping_error_code = 0
+
+        self.interval_local_cpu_evict_count = 0
+        self.interval_local_cpu_evict_keys_count = 0
+        self.interval_local_cpu_evict_failed_count = 0
+
+        self.interval_forced_unpin_count = 0
+
+        self.interval_p2p_requests = 0
+        self.interval_p2p_transferred_tokens = 0
+
+        self.interval_lookup_0_hit_requests = 0
+
+        new_retrieve_requests = {}
+        for request_id, retrieve_stats in self.retrieve_requests.items():
+            if retrieve_stats.end_time == 0:
+                new_retrieve_requests[request_id] = retrieve_stats
+        self.retrieve_requests = new_retrieve_requests
+
+        new_store_requests = {}
+        for request_id, store_stats in self.store_requests.items():
+            if store_stats.end_time == 0:
+                new_store_requests[request_id] = store_stats
+        self.store_requests = new_store_requests
+
+        new_p2p_requests = {}
+        for request_id, p2p_stats in self.p2p_requests.items():
+            if p2p_stats.end_time == 0:
+                new_p2p_requests[request_id] = p2p_stats
+        self.p2p_requests = new_p2p_requests
+
+        new_lookup_requests = {}
+        for request_id, lookup_stats in self.lookup_requests.items():
+            if not lookup_stats.is_finished:
+                new_lookup_requests[request_id] = lookup_stats
+        self.lookup_requests = new_lookup_requests
+
+        self.interval_request_cache_lifespan.clear()
+        self.reuse_chunk_id = 0
+
+    @thread_safe
+    def get_stats_and_clear(self) -> LMCacheStats:
+        """
+        This function should be called with by prometheus adapter with
+        a specific interval.
+        The function will return the latest states between the current
+        call and the previous call.
+        """
+        # Calculate retrieve hit rate based on requests finished in this interval
+        finished_retrieve_stats = [
+            s for s in self.retrieve_requests.values() if s.end_time != 0
+        ]
+        sum_finished_retrieve_requested_tokens = sum(
+            s.num_tokens for s in finished_retrieve_stats
+        )
+        sum_finished_retrieve_hit_tokens = sum(
+            s.local_hit_tokens + s.remote_hit_tokens for s in finished_retrieve_stats
+        )
+        retrieve_hit_rate = (
+            1
+            if len(finished_retrieve_stats) == 0
+            or sum_finished_retrieve_requested_tokens == 0
+            else sum_finished_retrieve_hit_tokens
+            / sum_finished_retrieve_requested_tokens
+        )
+
+        # Calculate lookup hit rate based on requests finished in this interval
+        finished_lookup_stats = [
+            s for s in self.lookup_requests.values() if s.is_finished
+        ]
+        sum_finished_lookup_requested = sum(s.num_tokens for s in finished_lookup_stats)
+        sum_finished_lookup_hit = sum(s.hit_tokens for s in finished_lookup_stats)
+        lookup_hit_rate = (
+            0
+            if sum_finished_lookup_requested == 0
+            else sum_finished_lookup_hit / sum_finished_lookup_requested
+        )
+
+        def filter_out_zeros(stats: Iterable[float]) -> List[float]:
+            return [x for x in stats if x != 0]
+
+        time_to_retrieve = filter_out_zeros(
+            stats.time_to_retrieve() for stats in self.retrieve_requests.values()
+        )
+
+        time_to_store = filter_out_zeros(
+            stats.time_to_store() for stats in self.store_requests.values()
+        )
+
+        time_to_lookup = filter_out_zeros(
+            stats.time_to_lookup() for stats in self.lookup_requests.values()
+        )
+
+        retrieve_speed = filter_out_zeros(
+            stats.retrieve_speed() for stats in self.retrieve_requests.values()
+        )
+
+        store_speed = filter_out_zeros(
+            stats.store_speed() for stats in self.store_requests.values()
+        )
+
+        # Granular profiling measurements
+        retrieve_process_tokens_time = filter_out_zeros(
+            stats.process_tokens_time for stats in self.retrieve_requests.values()
+        )
+        retrieve_broadcast_time = filter_out_zeros(
+            stats.broadcast_time for stats in self.retrieve_requests.values()
+        )
+        retrieve_to_gpu_time = filter_out_zeros(
+            stats.to_gpu_time for stats in self.retrieve_requests.values()
+        )
+        remote_backend_batched_get_blocking_time = filter_out_zeros(
+            stats.detailed_metrics.get("remote_backend_batched_get_blocking_time", 0.0)
+            for stats in self.retrieve_requests.values()
+        )
+        instrumented_connector_batched_get_time = filter_out_zeros(
+            stats.detailed_metrics.get("instrumented_connector_batched_get_time", 0.0)
+            for stats in self.retrieve_requests.values()
+        )
+        store_process_tokens_time = filter_out_zeros(
+            stats.process_tokens_time for stats in self.store_requests.values()
+        )
+        store_from_gpu_time = filter_out_zeros(
+            stats.from_gpu_time for stats in self.store_requests.values()
+        )
+        store_put_time = filter_out_zeros(
+            stats.put_time for stats in self.store_requests.values()
+        )
+
+        p2p_time_to_transfer = filter_out_zeros(
+            stats.time_to_transfer() for stats in self.p2p_requests.values()
+        )
+
+        p2p_transfer_speed = filter_out_zeros(
+            stats.transfer_speed() for stats in self.p2p_requests.values()
+        )
+
+        request_lookup_hit_rates = filter_out_zeros(
+            stats.hit_rate()
+            for stats in self.lookup_requests.values()
+            if stats.is_finished
+        )
+
+        request_lifespan = list(self.interval_request_cache_lifespan.values())
+
+        ret = LMCacheStats(
+            interval_retrieve_requests=self.interval_retrieve_requests,
+            interval_store_requests=self.interval_store_requests,
+            interval_lookup_requests=self.interval_lookup_requests,
+            interval_requested_tokens=self.interval_requested_tokens,
+            interval_hit_tokens=self.interval_hit_tokens,
+            interval_stored_tokens=self.interval_stored_tokens,
+            interval_lookup_tokens=self.interval_lookup_tokens,
+            interval_lookup_hits=self.interval_lookup_hits,
+            interval_remote_read_requests=self.interval_remote_read_requests,
+            interval_remote_read_bytes=self.interval_remote_read_bytes,
+            interval_remote_write_requests=self.interval_remote_write_requests,
+            interval_remote_write_bytes=self.interval_remote_write_bytes,
+            interval_remote_time_to_get=self.interval_remote_time_to_get.copy(),
+            interval_remote_time_to_put=self.interval_remote_time_to_put.copy(),
+            interval_remote_time_to_get_sync=self.interval_remote_time_to_get_sync.copy(),
+            interval_remote_ping_latency=self.interval_remote_ping_latency,
+            interval_remote_ping_errors=self.interval_remote_ping_errors,
+            interval_remote_ping_success=self.interval_remote_ping_success,
+            interval_remote_ping_error_code=self.interval_remote_ping_error_code,
+            retrieve_hit_rate=retrieve_hit_rate,
+            lookup_hit_rate=lookup_hit_rate,
+            interval_local_cpu_evict_count=self.interval_local_cpu_evict_count,
+            interval_local_cpu_evict_keys_count=self.interval_local_cpu_evict_keys_count,
+            interval_local_cpu_evict_failed_count=self.interval_local_cpu_evict_failed_count,
+            interval_forced_unpin_count=self.interval_forced_unpin_count,
+            local_cache_usage_bytes=self.local_cache_usage_bytes,
+            remote_cache_usage_bytes=self.remote_cache_usage_bytes,
+            local_storage_usage_bytes=self.local_storage_usage_bytes,
+            active_memory_objs_count=self.active_memory_objs_count,
+            pinned_memory_objs_count=self.pinned_memory_objs_count,
+            time_to_retrieve=time_to_retrieve,
+            time_to_store=time_to_store,
+            time_to_lookup=time_to_lookup,
+            retrieve_speed=retrieve_speed,
+            store_speed=store_speed,
+            retrieve_process_tokens_time=retrieve_process_tokens_time,
+            retrieve_broadcast_time=retrieve_broadcast_time,
+            retrieve_to_gpu_time=retrieve_to_gpu_time,
+            remote_backend_batched_get_blocking_time=remote_backend_batched_get_blocking_time,  # noqa: E501
+            instrumented_connector_batched_get_time=instrumented_connector_batched_get_time,  # noqa: E501
+            store_process_tokens_time=store_process_tokens_time,
+            store_from_gpu_time=store_from_gpu_time,
+            store_put_time=store_put_time,
+            interval_vllm_hit_tokens=self.interval_vllm_hit_tokens,
+            interval_p2p_requests=self.interval_p2p_requests,
+            interval_num_slow_retrieval_by_time=self.interval_num_slow_retrieval_by_time,
+            interval_num_slow_retrieval_by_speed=self.interval_num_slow_retrieval_by_speed,
+            interval_p2p_transferred_tokens=self.interval_p2p_transferred_tokens,
+            p2p_time_to_transfer=p2p_time_to_transfer,
+            p2p_transfer_speed=p2p_transfer_speed,
+            interval_lookup_hit_rates=request_lookup_hit_rates,
+            interval_request_cache_lifespan=request_lifespan,
+            interval_prompt_tokens=self.interval_prompt_tokens,
+            interval_lookup_0_hit_requests=self.interval_lookup_0_hit_requests,
+        )
+        self._clear()
+        return ret
+
+    _instance = None
+
+    @staticmethod
+    def GetOrCreate() -> "LMCStatsMonitor":
+        if LMCStatsMonitor._instance is None:
+            LMCStatsMonitor._instance = LMCStatsMonitor()
+        return LMCStatsMonitor._instance
+
+    @staticmethod
+    def DestroyInstance():
+        LMCStatsMonitor._instance = None
+
+    @staticmethod
+    def unregister_all_metrics():
+        collectors = list(REGISTRY._collector_to_names.keys())
+        for collector in collectors:
+            try:
+                REGISTRY.unregister(collector)
+            except KeyError:
+                pass
+
+
+class PrometheusLogger:
+    lmcache_is_healthy: prometheus_client.Gauge
+    periodic_threads_total_count: prometheus_client.Gauge
+    periodic_threads_running_count: prometheus_client.Gauge
+    periodic_threads_active_count: prometheus_client.Gauge
+
+    _gauge_cls = prometheus_client.Gauge
+    _counter_cls = prometheus_client.Counter
+    _histogram_cls = prometheus_client.Histogram
+
+    def _create_counter(
+        self, name: str, documentation: str, labelnames: List[str]
+    ) -> prometheus_client.Counter:
+        """Create a Counter and register it for reset_counters()."""
+        counter = self._counter_cls(
+            name=name, documentation=documentation, labelnames=labelnames
+        )
+        self._counters.append(counter)
+        return counter
+
+    def _create_histogram(
+        self,
+        name: str,
+        documentation: str,
+        labelnames: List[str],
+        buckets: Sequence[float],
+    ) -> prometheus_client.Histogram:
+        """Create a Histogram and register it for reset_histograms().
+
+        If the ``config`` object's extra_config contains a key
+        ``histogram_bucket_<short_name>`` (where ``<short_name>``
+        is the metric name without the ``lmcache:`` prefix),
+        the value will be used as the bucket list, overriding
+        the default *buckets* argument.
+        """
+        short_name = name.split(":", 1)[-1]
+        config_key = "histogram_bucket_%s" % short_name
+        custom = (
+            self.config.get_extra_config_value(config_key)
+            if self.config is not None
+            else None
+        )
+        if custom is not None:
+            buckets = custom
+            logger.info(
+                "Using custom buckets for histogram %s from extra_config key '%s'",
+                name,
+                config_key,
+            )
+        histogram = self._histogram_cls(
+            name=name,
+            documentation=documentation,
+            labelnames=labelnames,
+            buckets=buckets,
+        )
+        self._histograms.append(histogram)
+        return histogram
+
+    @staticmethod
+    def _ensure_multiprocess_dir() -> None:
+        multiprocess_dir = os.environ.get("PROMETHEUS_MULTIPROC_DIR")
+        if not multiprocess_dir:
+            multiprocess_dir = "/tmp/lmcache_prometheus"
+            os.environ["PROMETHEUS_MULTIPROC_DIR"] = multiprocess_dir
+        os.makedirs(multiprocess_dir, exist_ok=True)
+
+    def __init__(
+        self,
+        metadata: LMCacheMetadata,
+        config: Optional["LMCacheEngineConfig"] = None,
+    ):
+        # Ensure PROMETHEUS_MULTIPROC_DIR is set before any metric registration
+        PrometheusLogger._ensure_multiprocess_dir()
+
+        self.metadata = metadata
+        self.config = config
+
+        self.labels = self._metadata_to_labels(metadata)
+        labelnames = list(self.labels.keys())
+
+        # List to track all counters/histograms for reset methods
+        self._counters: List[prometheus_client.Counter] = []
+        self._histograms: List[prometheus_client.Histogram] = []
+
+        self.counter_num_retrieve_requests = self._create_counter(
+            name="lmcache:num_retrieve_requests",
+            documentation="Total number of retrieve requests sent to lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_store_requests = self._create_counter(
+            name="lmcache:num_store_requests",
+            documentation="Total number of store requests sent to lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_lookup_requests = self._create_counter(
+            name="lmcache:num_lookup_requests",
+            documentation="Total number of lookup requests sent to lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_requested_tokens = self._create_counter(
+            name="lmcache:num_requested_tokens",
+            documentation="Total number of tokens requested from lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_hit_tokens = self._create_counter(
+            name="lmcache:num_hit_tokens",
+            documentation="Total number of tokens hit in lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_stored_tokens = self._create_counter(
+            name="lmcache:num_stored_tokens",
+            documentation=(
+                "Total number of tokens stored in lmcache including evicted ones"
+            ),
+            labelnames=labelnames,
+        )
+
+        self.counter_num_lookup_tokens = self._create_counter(
+            name="lmcache:num_lookup_tokens",
+            documentation="Total number of tokens requested in lookup from lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_lookup_hits = self._create_counter(
+            name="lmcache:num_lookup_hits",
+            documentation="Total number of tokens hit in lookup from lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_vllm_hit_tokens = self._create_counter(
+            name="lmcache:num_vllm_hit_tokens",
+            documentation="Number of hit tokens in vllm",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_prompt_tokens = self._create_counter(
+            name="lmcache:num_prompt_tokens",
+            documentation="Number of prompt tokens in lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_remote_read_requests = self._create_counter(
+            name="lmcache:num_remote_read_requests",
+            documentation="Total number of requests read from "
+            "remote backends in lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_remote_read_bytes = self._create_counter(
+            name="lmcache:num_remote_read_bytes",
+            documentation="Total number of bytes read from remote backends in lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_remote_write_requests = self._create_counter(
+            name="lmcache:num_remote_write_requests",
+            documentation="Total number of requests write to "
+            "remote backends in lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_remote_write_bytes = self._create_counter(
+            name="lmcache:num_remote_write_bytes",
+            documentation="Total number of bytes write to remote backends in lmcache",
+            labelnames=labelnames,
+        )
+
+        self.counter_local_cpu_evict_count = self._create_counter(
+            name="lmcache:local_cpu_evict_count",
+            documentation="Total number of evict in local cpu backend",
+            labelnames=labelnames,
+        )
+
+        self.counter_local_cpu_evict_keys_count = self._create_counter(
+            name="lmcache:local_cpu_evict_keys_count",
+            documentation="Total number of evict keys in local cpu backend",
+            labelnames=labelnames,
+        )
+
+        self.counter_local_cpu_evict_failed_count = self._create_counter(
+            name="lmcache:local_cpu_evict_failed_count",
+            documentation="Total number of failed eviction in local cpu backend",
+            labelnames=labelnames,
+        )
+
+        self.counter_forced_unpin_count = self._create_counter(
+            name="lmcache:forced_unpin_count",
+            documentation="Total number of forced unpin due to timeout",
+            labelnames=labelnames,
+        )
+
+        self.counter_lookup_0_hit_requests = self._create_counter(
+            name="lmcache:lookup_0_hit_requests",
+            documentation="Total number of 0 hit lookup requests",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_slow_retrieval_by_time = self._create_counter(
+            name="lmcache:num_slow_retrieval_by_time",
+            documentation="Total number of slow retrievals by time threshold",
+            labelnames=labelnames,
+        )
+
+        self.counter_num_slow_retrieval_by_speed = self._create_counter(
+            name="lmcache:num_slow_retrieval_by_speed",
+            documentation="Total number of slow retrievals by speed threshold",
+            labelnames=labelnames,
+        )
+
+        self.gauge_retrieve_hit_rate = self._gauge_cls(
+            name="lmcache:retrieve_hit_rate",
+            documentation="Hit rate of lmcache retrieve requests since last log",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+
+        self.gauge_lookup_hit_rate = self._gauge_cls(
+            name="lmcache:lookup_hit_rate",
+            documentation="Hit rate of lmcache lookup requests since last log",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+
+        self.gauge_local_cache_usage = self._gauge_cls(
+            name="lmcache:local_cache_usage",
+            documentation="Local cache usage (bytes) of lmcache",
+            labelnames=labelnames,
+            multiprocess_mode="sum",
+        )
+
+        self.gauge_remote_cache_usage = self._gauge_cls(
+            name="lmcache:remote_cache_usage",
+            documentation="Remote cache usage (bytes) of lmcache",
+            labelnames=labelnames,
+            multiprocess_mode="sum",
+        )
+
+        self.gauge_local_storage_usage = self._gauge_cls(
+            name="lmcache:local_storage_usage",
+            documentation="Local storage usage (bytes) of lmcache",
+            labelnames=labelnames,
+            multiprocess_mode="sum",
+        )
+
+        self.gauge_active_memory_objs_count = self._gauge_cls(
+            name="lmcache:active_memory_objs_count",
+            documentation="The number of active memory objects",
+            labelnames=labelnames,
+            multiprocess_mode="sum",
+        )
+
+        self.gauge_pinned_memory_objs_count = self._gauge_cls(
+            name="lmcache:pinned_memory_objs_count",
+            documentation="The number of pinned memory objects",
+            labelnames=labelnames,
+            multiprocess_mode="sum",
+        )
+
+        time_to_retrieve_buckets = [
+            0.001,
+            0.005,
+            0.01,
+            0.02,
+            0.04,
+            0.06,
+            0.08,
+            0.1,
+            0.25,
+            0.5,
+            0.75,
+            1.0,
+            2.5,
+            5.0,
+            7.5,
+            10.0,
+        ]
+        self.histogram_time_to_retrieve = self._create_histogram(
+            name="lmcache:time_to_retrieve",
+            documentation="Time to retrieve from lmcache (seconds)",
+            labelnames=labelnames,
+            buckets=time_to_retrieve_buckets,
+        )
+
+        time_to_store_buckets = [
+            0.001,
+            0.005,
+            0.01,
+            0.02,
+            0.04,
+            0.06,
+            0.08,
+            0.1,
+            0.25,
+            0.5,
+            0.75,
+            1.0,
+            2.5,
+            5.0,
+            7.5,
+            10.0,
+        ]
+        self.histogram_time_to_store = self._create_histogram(
+            name="lmcache:time_to_store",
+            documentation="Time to store to lmcache (seconds)",
+            labelnames=labelnames,
+            buckets=time_to_store_buckets,
+        )
+
+        time_to_lookup_buckets = [
+            0.00001 * 2**i for i in range(20)
+        ]  # 0.01 ms to 5000 ms
+        self.histogram_time_to_lookup = self._create_histogram(
+            name="lmcache:time_to_lookup",
+            documentation="Time to lookup in lmcache (seconds)",
+            labelnames=labelnames,
+            buckets=time_to_lookup_buckets,
+        )
+
+        profiling_buckets = [0.00001 * 2**i for i in range(20)]  # 0.01 ms to 5000 ms
+        self.histogram_retrieve_process_tokens_time = self._create_histogram(
+            name="lmcache:retrieve_process_tokens_time",
+            documentation="Time to process tokens in retrieve (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+        self.histogram_retrieve_broadcast_time = self._create_histogram(
+            name="lmcache:retrieve_broadcast_time",
+            documentation="Time to broadcast memory objects in retrieve (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+        self.histogram_retrieve_to_gpu_time = self._create_histogram(
+            name="lmcache:retrieve_to_gpu_time",
+            documentation="Time to move data to GPU in retrieve (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+        self.histogram_remote_backend_batched_get_blocking_time = (
+            self._create_histogram(
+                name="lmcache:remote_backend_batched_get_blocking_time",
+                documentation="Time to get data from remote backend (seconds)",
+                labelnames=labelnames,
+                buckets=profiling_buckets,
+            )
+        )
+        self.histogram_instrumented_connector_batched_get_time = self._create_histogram(
+            name="lmcache:instrumented_connector_batched_get_time",
+            documentation="Time used by the connector (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+        self.histogram_store_process_tokens_time = self._create_histogram(
+            name="lmcache:store_process_tokens_time",
+            documentation="Time to process tokens in store (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+        self.histogram_store_from_gpu_time = self._create_histogram(
+            name="lmcache:store_from_gpu_time",
+            documentation="Time to move data from GPU in store (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+        self.histogram_store_put_time = self._create_histogram(
+            name="lmcache:store_put_time",
+            documentation="Time to put data to storage in store (seconds)",
+            labelnames=labelnames,
+            buckets=profiling_buckets,
+        )
+
+        retrieve_speed_buckets = [
+            1,
+            8,
+            16,
+            32,
+            64,
+            128,
+            256,
+            512,
+            1024,
+            2048,
+            4096,
+            8192,
+            16384,
+            32768,
+            65536,
+        ]
+        self.histogram_retrieve_speed = self._create_histogram(
+            name="lmcache:retrieve_speed",
+            documentation="Retrieve speed of lmcache (tokens per second)",
+            labelnames=labelnames,
+            buckets=retrieve_speed_buckets,
+        )
+
+        store_speed_buckets = [
+            1,
+            8,
+            16,
+            32,
+            64,
+            128,
+            256,
+            512,
+            1024,
+            2048,
+            4096,
+            8192,
+            16384,
+            32768,
+            65536,
+        ]
+        self.histogram_store_speed = self._create_histogram(
+            name="lmcache:store_speed",
+            documentation="Store speed of lmcache (tokens per second)",
+            labelnames=labelnames,
+            buckets=store_speed_buckets,
+        )
+
+        # P2P transfer metrics
+        p2p_time_buckets = [
+            0.001,  # 1ms
+            0.005,  # 5ms
+            0.01,  # 10ms
+            0.02,  # 20ms
+            0.04,  # 40ms
+            0.06,  # 60ms
+            0.08,  # 80ms
+            0.1,  # 100ms
+            0.25,  # 250ms
+            0.5,  # 500ms
+            0.75,  # 750ms
+            1.0,  # 1s
+            2.5,  # 2.5s
+            5.0,  # 5s
+            7.5,  # 7.5s
+            10.0,  # 10s
+        ]
+        self.histogram_p2p_time_to_transfer = self._create_histogram(
+            name="lmcache:p2p_time_to_transfer",
+            documentation="Time to transfer via P2P (seconds)",
+            labelnames=labelnames,
+            buckets=p2p_time_buckets,
+        )
+
+        p2p_speed_buckets = [
+            1,
+            8,
+            16,
+            32,
+            64,
+            128,
+            256,
+            512,
+            1024,
+            2048,
+            4096,
+            8192,
+            16384,
+            32768,
+            65536,
+        ]
+        self.histogram_p2p_transfer_speed = self._create_histogram(
+            name="lmcache:p2p_transfer_speed",
+            documentation="P2P transfer speed (tokens per second)",
+            labelnames=labelnames,
+            buckets=p2p_speed_buckets,
+        )
+
+        remote_time_to_get = [
+            1,
+            5,
+            10,
+            20,
+            40,
+            60,
+            80,
+            100,
+            250,
+            500,
+            750,
+            1000,
+            2500,
+            5000,
+            7500,
+            10000,
+        ]
+        self.histogram_remote_time_to_get = self._create_histogram(
+            name="lmcache:remote_time_to_get",
+            documentation="Time to get from remote backends (ms)",
+            labelnames=labelnames,
+            buckets=remote_time_to_get,
+        )
+
+        remote_time_to_put = [
+            1,
+            5,
+            10,
+            20,
+            40,
+            60,
+            80,
+            100,
+            250,
+            500,
+            750,
+            1000,
+            2500,
+            5000,
+            7500,
+            10000,
+        ]
+        self.histogram_remote_time_to_put = self._create_histogram(
+            name="lmcache:remote_time_to_put",
+            documentation="Time to put to remote backends (ms)",
+            labelnames=labelnames,
+            buckets=remote_time_to_put,
+        )
+
+        remote_time_to_get_sync = [
+            1,
+            5,
+            10,
+            20,
+            40,
+            60,
+            80,
+            100,
+            250,
+            500,
+            750,
+            1000,
+            2500,
+            5000,
+            7500,
+            10000,
+        ]
+        self.histogram_remote_time_to_get_sync = self._create_histogram(
+            name="lmcache:remote_time_to_get_sync",
+            documentation="Time to get from remote backends synchronously(ms)",
+            labelnames=labelnames,
+            buckets=remote_time_to_get_sync,
+        )
+
+        request_cache_hit_rate = [
+            0.1,
+            0.2,
+            0.3,
+            0.4,
+            0.5,
+            0.6,
+            0.7,
+            0.8,
+            0.9,
+            1.0,
+        ]
+        self.histogram_request_cache_hit_rate = self._create_histogram(
+            name="lmcache:request_cache_hit_rate",
+            documentation="Request cache hit rate",
+            labelnames=labelnames,
+            buckets=request_cache_hit_rate,
+        )
+
+        request_cache_lifespan_buckets = [
+            0,
+            1,
+            5,
+            10,
+            20,
+            40,
+            60,
+            80,
+            100,
+            250,
+            500,
+            750,
+            1000,
+            2500,
+            5000,
+        ]
+        self.histogram_request_cache_lifespan = self._create_histogram(
+            name="lmcache:request_cache_lifespan",
+            documentation="Request cache lifespan in minutes",
+            labelnames=labelnames,
+            buckets=request_cache_lifespan_buckets,
+        )
+
+        # Ping latency metrics: use a gauge to record the latest ping latency
+        self.gauge_remote_ping_latency = self._gauge_cls(
+            name="lmcache:remote_ping_latency",
+            documentation="Latest ping latency to remote backends (ms)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self.counter_remote_ping_errors = self._create_counter(
+            name="lmcache:remote_ping_errors",
+            documentation="Number of ping errors to remote backends",
+            labelnames=labelnames,
+        )
+        self.counter_remote_ping_successes = self._create_counter(
+            name="lmcache:remote_ping_successes",
+            documentation="Number of ping successes to remote backends",
+            labelnames=labelnames,
+        )
+        self.gauge_remote_ping_error_code = self._gauge_cls(
+            name="lmcache:remote_ping_error_code",
+            documentation="Latest ping error code to remote backends",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._dynamic_metrics(labelnames)
+
+    def _create_dynamic_gauge(
+        self,
+        name: str,
+        documentation: str,
+        labelnames: List[str],
+        multiprocess_mode: str,
+    ) -> None:
+        metric_attr = name.removeprefix("lmcache:")
+        if metric_attr == name or not metric_attr.isidentifier():
+            raise ValueError(f"Invalid dynamic metric name: {name}")
+
+        gauge = self._gauge_cls(
+            name=name,
+            documentation=documentation,
+            labelnames=labelnames,
+            multiprocess_mode=multiprocess_mode,
+        )
+        # Store the shared collector separately from the labeled child.
+        # Shallow-copied label views reuse the collector, then call labels()
+        # with their own labels so set_function callbacks publish to that view.
+        self._dynamic_gauge_collectors[metric_attr] = gauge
+        setattr(self, metric_attr, gauge.labels(**self.labels))
+
+    def _bind_dynamic_metric_children(self) -> None:
+        PrometheusLogger._ensure_multiprocess_dir()
+        for metric_attr, gauge in self._dynamic_gauge_collectors.items():
+            setattr(self, metric_attr, gauge.labels(**self.labels))
+
+    def _dynamic_metrics(self, labelnames: List[str]) -> None:
+        """
+        Dynamically get value by lambda function while capture
+        """
+        self._dynamic_gauge_collectors: Dict[str, prometheus_client.Gauge] = {}
+        self._create_dynamic_gauge(
+            name="lmcache:local_cpu_hot_cache_count",
+            documentation="The size of the hot_cache",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:local_cpu_keys_in_request_count",
+            documentation="The size of the keys_in_request",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:kv_msg_queue_size",
+            documentation="The size of the KV message queue in BatchedMessageSender",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:remote_put_task_num",
+            documentation="The number of remote put tasks",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:pin_monitor_pinned_objects_count",
+            documentation="The number of pinned objects in PinMonitor",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:lmcache_is_healthy",
+            documentation="The health status of LMCache (1=healthy, 0=unhealthy)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:get_blocking_failed_count",
+            documentation="The number of get blocking failed",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:put_failed_count",
+            documentation="The number of put failed",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+
+        event_statuses = ["ongoing", "done", "not_found"]
+        for status in event_statuses:
+            metric_name = f"storage_events_{status}_count"
+            self._create_dynamic_gauge(
+                name=f"lmcache:{metric_name}",
+                documentation=f"The number of {status.replace('_', ' ')} events",
+                labelnames=labelnames,
+                multiprocess_mode="sum",
+            )
+
+        # Chunk statistics metrics (dynamic)
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_enabled",
+            documentation="Whether chunk statistics collection is enabled",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_total_requests",
+            documentation="Total number of requests processed by chunk statistics",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_total_chunks",
+            documentation="Total number of chunks processed",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_unique_chunks",
+            documentation="Number of unique chunks (estimated)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_reuse_rate",
+            documentation="Chunk reuse rate (0.0 to 1.0)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_bloom_filter_size_mb",
+            documentation="Bloom Filter memory usage in MB",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_bloom_filter_fill_rate",
+            documentation="Bloom Filter fill rate (0.0 to 1.0)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_file_count",
+            documentation="Number of files created for file_hash strategy",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:chunk_statistics_current_file_size",
+            documentation="Current file size in bytes for file_hash strategy",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+
+        # Connector metrics
+        connector_metrics = [
+            "scheduler_unfinished_requests_count",
+            "connector_load_specs_count",
+            "connector_request_trackers_count",
+            "connector_kv_caches_count",
+            "connector_layerwise_retrievers_count",
+            "connector_invalid_block_ids_count",
+            "connector_requests_priority_count",
+        ]
+
+        for metric_name in connector_metrics:
+            self._create_dynamic_gauge(
+                name=f"lmcache:{metric_name}",
+                documentation=f"The count of {metric_name.replace('_', ' ')}",
+                labelnames=labelnames,
+                multiprocess_mode="livemostrecent",
+            )
+
+        # PeriodicThread metrics
+        self._create_dynamic_gauge(
+            name="lmcache:periodic_threads_total_count",
+            documentation="Total number of registered periodic threads",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:periodic_threads_running_count",
+            documentation="Number of running periodic threads",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+        self._create_dynamic_gauge(
+            name="lmcache:periodic_threads_active_count",
+            documentation="Number of active periodic threads (recently executed)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        )
+
+        # Per-level metrics for periodic threads
+        for level_name in ["critical", "high", "medium", "low"]:
+            self._create_dynamic_gauge(
+                name=f"lmcache:periodic_threads_{level_name}_total",
+                documentation=f"Total number of {level_name} level periodic threads",
+                labelnames=labelnames,
+                multiprocess_mode="livemostrecent",
+            )
+
+            self._create_dynamic_gauge(
+                name=f"lmcache:periodic_threads_{level_name}_running",
+                documentation=f"Number of running {level_name} level periodic threads",
+                labelnames=labelnames,
+                multiprocess_mode="livemostrecent",
+            )
+
+            self._create_dynamic_gauge(
+                name=f"lmcache:periodic_threads_{level_name}_active",
+                documentation=f"Number of active {level_name} level periodic threads",
+                labelnames=labelnames,
+                multiprocess_mode="livemostrecent",
+            )
+
+    def _log_gauge(self, gauge, data: Union[int, float]) -> None:
+        # Convenience function for logging to gauge.
+        gauge.labels(**self.labels).set(data)
+
+    def _log_counter(self, counter, data: Union[int, float]) -> None:
+        # Convenience function for logging to counter.
+        # Prevent ValueError from negative increment
+        if data < 0:
+            return
+        counter.labels(**self.labels).inc(data)
+
+    def _log_histogram(self, histogram, data: Union[List[int], List[float]]) -> None:
+        # Convenience function for logging to histogram.
+        for value in data:
+            histogram.labels(**self.labels).observe(value)
+
+    def log_prometheus(self, stats: LMCacheStats):
+        self._log_counter(
+            self.counter_num_retrieve_requests, stats.interval_retrieve_requests
+        )
+        self._log_counter(
+            self.counter_num_store_requests, stats.interval_store_requests
+        )
+        self._log_counter(
+            self.counter_num_lookup_requests, stats.interval_lookup_requests
+        )
+
+        self._log_counter(
+            self.counter_num_requested_tokens, stats.interval_requested_tokens
+        )
+        self._log_counter(self.counter_num_hit_tokens, stats.interval_hit_tokens)
+        self._log_counter(self.counter_num_stored_tokens, stats.interval_stored_tokens)
+        self._log_counter(self.counter_num_lookup_tokens, stats.interval_lookup_tokens)
+        self._log_counter(self.counter_num_lookup_hits, stats.interval_lookup_hits)
+        self._log_counter(self.counter_num_prompt_tokens, stats.interval_prompt_tokens)
+        self._log_counter(
+            self.counter_num_vllm_hit_tokens, stats.interval_vllm_hit_tokens
+        )
+
+        self._log_counter(
+            self.counter_num_remote_read_requests,
+            stats.interval_remote_read_requests,
+        )
+        self._log_counter(
+            self.counter_num_remote_read_bytes, stats.interval_remote_read_bytes
+        )
+        self._log_counter(
+            self.counter_num_remote_write_requests,
+            stats.interval_remote_write_requests,
+        )
+        self._log_counter(
+            self.counter_num_remote_write_bytes,
+            stats.interval_remote_write_bytes,
+        )
+        self._log_counter(
+            self.counter_local_cpu_evict_count,
+            stats.interval_local_cpu_evict_count,
+        )
+        self._log_counter(
+            self.counter_local_cpu_evict_keys_count,
+            stats.interval_local_cpu_evict_keys_count,
+        )
+        self._log_counter(
+            self.counter_local_cpu_evict_failed_count,
+            stats.interval_local_cpu_evict_failed_count,
+        )
+        self._log_counter(
+            self.counter_forced_unpin_count,
+            stats.interval_forced_unpin_count,
+        )
+        self._log_counter(
+            self.counter_lookup_0_hit_requests,
+            stats.interval_lookup_0_hit_requests,
+        )
+        self._log_counter(
+            self.counter_num_slow_retrieval_by_time,
+            stats.interval_num_slow_retrieval_by_time,
+        )
+        self._log_counter(
+            self.counter_num_slow_retrieval_by_speed,
+            stats.interval_num_slow_retrieval_by_speed,
+        )
+
+        self._log_gauge(self.gauge_retrieve_hit_rate, stats.retrieve_hit_rate)
+
+        self._log_gauge(self.gauge_lookup_hit_rate, stats.lookup_hit_rate)
+
+        self._log_gauge(self.gauge_local_cache_usage, stats.local_cache_usage_bytes)
+
+        self._log_gauge(self.gauge_remote_cache_usage, stats.remote_cache_usage_bytes)
+
+        self._log_gauge(self.gauge_local_storage_usage, stats.local_storage_usage_bytes)
+
+        self._log_histogram(self.histogram_time_to_retrieve, stats.time_to_retrieve)
+
+        self._log_histogram(self.histogram_time_to_store, stats.time_to_store)
+
+        self._log_histogram(self.histogram_time_to_lookup, stats.time_to_lookup)
+
+        self._log_histogram(self.histogram_retrieve_speed, stats.retrieve_speed)
+
+        self._log_histogram(self.histogram_store_speed, stats.store_speed)
+
+        self._log_histogram(
+            self.histogram_retrieve_process_tokens_time,
+            stats.retrieve_process_tokens_time,
+        )
+        self._log_histogram(
+            self.histogram_retrieve_broadcast_time, stats.retrieve_broadcast_time
+        )
+        self._log_histogram(
+            self.histogram_retrieve_to_gpu_time, stats.retrieve_to_gpu_time
+        )
+        self._log_histogram(
+            self.histogram_remote_backend_batched_get_blocking_time,
+            stats.remote_backend_batched_get_blocking_time,
+        )
+        self._log_histogram(
+            self.histogram_instrumented_connector_batched_get_time,
+            stats.instrumented_connector_batched_get_time,
+        )
+        self._log_histogram(
+            self.histogram_store_process_tokens_time, stats.store_process_tokens_time
+        )
+        self._log_histogram(
+            self.histogram_store_from_gpu_time, stats.store_from_gpu_time
+        )
+        self._log_histogram(self.histogram_store_put_time, stats.store_put_time)
+
+        self._log_histogram(
+            self.histogram_p2p_time_to_transfer, stats.p2p_time_to_transfer
+        )
+
+        self._log_histogram(self.histogram_p2p_transfer_speed, stats.p2p_transfer_speed)
+
+        self._log_histogram(
+            self.histogram_remote_time_to_get, stats.interval_remote_time_to_get
+        )
+        self._log_histogram(
+            self.histogram_remote_time_to_put, stats.interval_remote_time_to_put
+        )
+        self._log_histogram(
+            self.histogram_remote_time_to_get_sync,
+            stats.interval_remote_time_to_get_sync,
+        )
+        self._log_histogram(
+            self.histogram_request_cache_hit_rate, stats.interval_lookup_hit_rates
+        )
+        self._log_histogram(
+            self.histogram_request_cache_lifespan, stats.interval_request_cache_lifespan
+        )
+        self._log_gauge(
+            self.gauge_remote_ping_latency, stats.interval_remote_ping_latency
+        )
+        self._log_counter(
+            self.counter_remote_ping_errors, stats.interval_remote_ping_errors
+        )
+        self._log_counter(
+            self.counter_remote_ping_successes, stats.interval_remote_ping_success
+        )
+        self._log_gauge(
+            self.gauge_remote_ping_error_code, stats.interval_remote_ping_error_code
+        )
+        self._log_gauge(
+            self.gauge_active_memory_objs_count, stats.active_memory_objs_count
+        )
+        self._log_gauge(
+            self.gauge_pinned_memory_objs_count, stats.pinned_memory_objs_count
+        )
+
+    _instances: Dict[tuple[tuple[str, str], ...], "PrometheusLogger"] = {}
+
+    @staticmethod
+    @thread_safe
+    def GetOrCreate(
+        metadata: LMCacheMetadata,
+        config: Optional["LMCacheEngineConfig"] = None,
+    ) -> "PrometheusLogger":
+        metadata_key = PrometheusLogger._metadata_to_key(metadata)
+        if metadata_key in PrometheusLogger._instances:
+            return PrometheusLogger._instances[metadata_key]
+
+        base_logger = PrometheusLogger._get_base_logger()
+        if base_logger is None:
+            logger_instance = PrometheusLogger(metadata, config=config)
+        else:
+            logger_instance = PrometheusLogger._create_label_view(
+                base_logger,
+                metadata,
+            )
+
+        PrometheusLogger._instances[metadata_key] = logger_instance
+        return logger_instance
+
+    @staticmethod
+    def _get_base_logger() -> Optional["PrometheusLogger"]:
+        """
+        Return an existing logger to reuse registered Prometheus collectors.
+        """
+        return next(iter(PrometheusLogger._instances.values()), None)
+
+    @thread_safe
+    def reset_counters(self) -> None:
+        """
+        Reset all Prometheus Counter metrics by calling clear().
+        After clearing, re-initialize with labels so metrics remain visible.
+        """
+        label_views = self._reset_label_views()
+        for counter in self._counters:
+            counter.clear()
+            # Re-initialize all known label views to keep each series visible.
+            for label_view in label_views:
+                counter.labels(**label_view.labels)
+
+    @thread_safe
+    def reset_histograms(self) -> None:
+        """
+        Reset all Prometheus Histogram metrics by calling clear().
+        After clearing, re-initialize with labels so metrics remain visible.
+        """
+        label_views = self._reset_label_views()
+        for histogram in self._histograms:
+            histogram.clear()
+            # Re-initialize all known label views to keep each series visible.
+            for label_view in label_views:
+                histogram.labels(**label_view.labels)
+
+    @staticmethod
+    def _metadata_to_labels(metadata: LMCacheMetadata) -> Dict[str, Any]:
+        labels = {
+            "model_name": metadata.model_name,
+            "worker_id": metadata.worker_id,
+            "role": metadata.role,
+            "served_model_name": metadata.served_model_name or "",
+        }
+        return labels
+
+    @staticmethod
+    def _metadata_to_key(metadata: LMCacheMetadata) -> tuple[tuple[str, str], ...]:
+        labels = PrometheusLogger._metadata_to_labels(metadata)
+        return tuple(sorted((name, str(value)) for name, value in labels.items()))
+
+    @staticmethod
+    def _create_label_view(
+        base_logger: "PrometheusLogger",
+        metadata: LMCacheMetadata,
+    ) -> "PrometheusLogger":
+        """Reuse registered collectors with a different metadata/label view."""
+        label_view = copy(base_logger)
+        label_view.metadata = metadata
+        label_view.labels = PrometheusLogger._metadata_to_labels(metadata)
+        label_view._bind_dynamic_metric_children()
+        return label_view
+
+    def _reset_label_views(self) -> List["PrometheusLogger"]:
+        """Return label views whose children must be restored after clear().
+
+        Counter.clear() and Histogram.clear() remove every child from the
+        shared collector, so reset must recreate children for all known labels.
+        """
+        views = list(PrometheusLogger._instances.values())
+        if self not in views:
+            views.append(self)
+        return views
+
+
+def reset_observability_metrics() -> None:
+    """
+    Reset observability metrics to their initial state.
+    """
+
+    prometheus_logger = PrometheusLogger._get_base_logger()
+    if prometheus_logger is not None:
+        prometheus_logger.reset_counters()
+        prometheus_logger.reset_histograms()
+
+
+class LMCacheStatsLogger:
+    def __init__(
+        self,
+        metadata: LMCacheMetadata,
+        log_interval: int,
+        config: Optional["LMCacheEngineConfig"] = None,
+    ):
+        self.metadata = metadata
+        self.log_interval = log_interval
+        self.monitor = LMCStatsMonitor.GetOrCreate()
+        self.prometheus_logger = PrometheusLogger.GetOrCreate(metadata, config=config)
+        self.lmc_usage_logger = ContinuousUsageContext.GetOrCreate(metadata)
+        self.is_running = True
+        # Event for interruptible sleep during shutdown
+        self.shutdown_event = threading.Event()
+
+        self.thread = threading.Thread(
+            target=self.log_worker, daemon=True, name="stats-logger-thread"
+        )
+        self.thread.start()
+
+    def log_worker(self):
+        while self.is_running:
+            stats = self.monitor.get_stats_and_clear()
+            self.prometheus_logger.log_prometheus(stats)
+            self.lmc_usage_logger.incr_or_send_stats(stats)
+            # Use Event.wait() instead of time.sleep() for interruptible sleep
+            # Returns True if event was set, False if timeout occurred
+            self.shutdown_event.wait(self.log_interval)
+
+    def shutdown(self):
+        """Shutdown the stats logger gracefully with immediate wake-up"""
+        logger.info("Shutting down LMCacheStatsLogger...")
+
+        # Signal the worker thread to stop
+        self.is_running = False
+
+        # Signal the event to wake up the thread immediately from sleep
+        self.shutdown_event.set()
+
+        # Wait for thread with a reasonable timeout
+        if self.thread.is_alive():
+            # Since we wake up the thread immediately, use a shorter timeout
+            # Just enough time for the thread to finish its current iteration
+            timeout = 5.0
+            logger.info(
+                f"Waiting for stats logger thread to finish (timeout: {timeout}s)..."
+            )
+
+            try:
+                self.thread.join(timeout=timeout)
+
+                if self.thread.is_alive():
+                    logger.warning(
+                        f"Stats logger thread did not terminate "
+                        f"within {timeout}s timeout. "
+                        "Thread may be blocked in logging operations. "
+                        "Proceeding with shutdown anyway."
+                    )
+                else:
+                    logger.info("Stats logger thread terminated successfully")
+            except Exception as e:
+                logger.error("Error waiting for stats logger thread: %s", e)
+        else:
+            logger.info("Stats logger thread already stopped")
+
+        logger.info("LMCacheStatsLogger shutdown complete")
diff --git a/lmcache/python_ops_fallback.py b/lmcache/python_ops_fallback.py
new file mode 100644
index 0000000..0aa6ee3
--- /dev/null
+++ b/lmcache/python_ops_fallback.py
@@ -0,0 +1,2764 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# This file contains Python non-CUDA fallback implementations for
+# CUDA-specific operations.
+#
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+from enum import IntEnum
+from multiprocessing import shared_memory
+from typing import Any, Optional, Tuple
+import ctypes
+import ctypes.util
+import os
+import threading
+import warnings
+
+# Third Party
+from numba import njit
+import numpy as np
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.v1.platform import current_device_spec
+
+# Store the tensor objects in memory so that they can be accessed
+# outside the scope of this file
+_tensor_registry: dict[int, torch.Tensor] = {}
+_shm_registry: dict[int, shared_memory.SharedMemory] = {}
+_buf_registry: dict[int, ctypes.Array] = {}
+_pinned_ptr_registry: dict[int, int] = {}  # ptr -> size, for cudaHostUnregister
+
+# Cached copy library for lmcache_memcpy_async (lazy-initialized)
+_copy_lib_NOT_LOADED = object()
+_copy_lib: Optional[ctypes.CDLL] = _copy_lib_NOT_LOADED  # type: ignore
+
+
+def _get_copy_lib() -> Optional[ctypes.CDLL]:
+    """Lazily load and cache the CUDA/ROCm runtime library, or None for CPU fallback."""
+    global _copy_lib
+    if _copy_lib is _copy_lib_NOT_LOADED:
+        # Try to load GPU runtime libraries in priority order: CUDA first, then ROCm
+        # TODO: ROCm path to be validated on real device
+        for name, fallback in [
+            ("cudart", "libcudart.so"),  # NVIDIA CUDA Runtime
+            ("amdhip64", "libamdhip64.so"),  # AMD ROCm HIP Runtime
+        ]:
+            try:
+                path = ctypes.util.find_library(name)
+                if path:
+                    _copy_lib = ctypes.CDLL(path)
+                else:
+                    _copy_lib = ctypes.CDLL(fallback)
+                break  # Successfully loaded, stop trying
+            except OSError:
+                continue  # Current library not available, try next
+        else:
+            # All GPU libraries failed to load, fall back to CPU
+            _copy_lib = None
+    return _copy_lib
+
+
+def _tensor_from_ptr(
+    ptr: int,
+    shape: tuple[int, ...],
+    dtype: torch.dtype,
+    device: torch.device | str | None = None,
+) -> torch.Tensor:
+    """
+    Create a tensor view over a raw pointer (zero-copy where possible).
+
+    Supports both CPU (pinned or regular) and CUDA device pointers.
+
+    Args:
+        ptr:    Raw memory pointer as int (must be non-zero).
+        shape:  Desired tensor shape.
+        dtype:  Desired tensor dtype, must match the memory layout.
+        device: Where the pointer lives.
+                - None / "cpu" / torch.device("cpu")  → CPU pointer
+                - "cuda" / "cuda:N" / torch.device("cuda", N) → CUDA pointer
+                  If None and ptr looks like a CUDA ptr, pass device explicitly.
+
+    Returns:
+        A tensor that shares memory with the original pointer.
+        For CPU: always zero-copy via ctypes + torch.frombuffer.
+        For CUDA: zero-copy via torch._C._construct_storage_from_data_pointer
+                  (PyTorch >= 2.0) or __cuda_array_interface__, with a
+                  cudaMemcpy D2D fallback.
+
+    Raises:
+        ValueError: if ptr is 0.
+
+    Warning:
+        The caller is responsible for keeping the underlying memory alive
+        for the entire lifetime of the returned tensor.
+    """
+    if ptr == 0:
+        raise ValueError("Pointer must be non-zero")
+
+    # ------------------------------------------------------------------ #
+    # Normalise device                                                   #
+    # ------------------------------------------------------------------ #
+    if device is None:
+        device = torch.device("cpu")
+    elif not isinstance(device, torch.device):
+        device = torch.device(device)
+
+    assert isinstance(device, torch.device)
+    # ------------------------------------------------------------------ #
+    # Compute size                                                       #
+    # ------------------------------------------------------------------ #
+    numel = 1
+    for dim in shape:
+        numel *= int(dim)
+    element_size = torch.empty((), dtype=dtype).element_size()
+    total_bytes = numel * element_size
+
+    # ------------------------------------------------------------------ #
+    # CPU path                                                           #
+    # ------------------------------------------------------------------ #
+    if device.type == "cpu":
+        return _tensor_from_cpu_ptr(ptr, shape, dtype, numel, total_bytes)
+
+    # ------------------------------------------------------------------ #
+    # CUDA path                                                          #
+    # ------------------------------------------------------------------ #
+    if device.type == "cuda":
+        return _tensor_from_cuda_ptr(ptr, shape, dtype, device, numel, total_bytes)
+
+    raise ValueError(
+        f"Unsupported device type: {device.type!r}. Expected 'cpu' or 'cuda'."
+    )
+
+
+# ====================================================================== #
+#  CPU implementation                                                    #
+# ====================================================================== #
+
+
+def _tensor_from_cpu_ptr(
+    ptr: int,
+    shape: tuple[int, ...],
+    dtype: torch.dtype,
+    numel: int,
+    total_bytes: int,
+) -> torch.Tensor:
+    """
+    Zero-copy CPU tensor from a raw host pointer via ctypes + torch.frombuffer.
+
+    """
+    buffer_type = ctypes.c_uint8 * total_bytes
+    buf = buffer_type.from_address(ptr)
+    # torch.frombuffer is zero-copy for contiguous byte buffers on CPU.
+    return torch.frombuffer(buf, dtype=dtype).view(*shape)
+
+
+# ====================================================================== #
+#  CUDA implementation                                                   #
+# ====================================================================== #
+def _tensor_from_cuda_ptr(
+    ptr: int,
+    shape: tuple[int, ...],
+    dtype: torch.dtype,
+    device: torch.device,
+    numel: int,
+    total_bytes: int,
+) -> torch.Tensor:
+    """Zero-copy CUDA tensor from a raw device pointer."""
+
+    try:
+        _DTYPE_TO_TYPESTR = {
+            torch.float16: "<f2",
+            torch.float32: "<f4",
+            torch.float64: "<f8",
+            torch.int8: "|i1",
+            torch.int16: "<i2",
+            torch.int32: "<i4",
+            torch.int64: "<i8",
+            torch.uint8: "|u1",
+            torch.bool: "|b1",
+        }
+        is_bf16 = dtype == torch.bfloat16
+
+        # Determine the correct typestr, smuggle bfloat16 as int16
+        typestr = "<i2" if is_bf16 else _DTYPE_TO_TYPESTR.get(dtype, "|u1")
+
+        class _CudaArrayWrapper:
+            def __init__(self, ptr_int: int, shape_tuple: tuple, type_str: str):
+                self.__cuda_array_interface__ = {
+                    "data": (ptr_int, False),
+                    "shape": shape_tuple,
+                    "typestr": type_str,
+                    "version": 3,
+                }
+
+        t = torch.as_tensor(_CudaArrayWrapper(ptr, (numel,), typestr), device=device)
+        if is_bf16:
+            t = t.view(torch.bfloat16)
+
+        return t.view(*shape)
+    except Exception:
+        pass
+
+    # Strategy 2: cudaMemcpy Device-to-Device (Fallback)
+    libcudart = _get_copy_lib()
+    if libcudart is None:
+        raise RuntimeError("Failed to load libcudart/libamdhip")
+
+    cudaMemcpy = libcudart.cudaMemcpy
+    cudaMemcpy.restype = ctypes.c_int
+    cudaMemcpy.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.c_size_t,
+        ctypes.c_int,
+    ]
+    _MEMCPY_D2D = 3
+
+    dst = torch.empty(numel, dtype=dtype, device=device)
+
+    err = cudaMemcpy(
+        ctypes.c_void_p(dst.data_ptr()),
+        ctypes.c_void_p(ptr),
+        ctypes.c_size_t(total_bytes),
+        ctypes.c_int(_MEMCPY_D2D),
+    )
+    if err != 0:
+        raise RuntimeError(f"cudaMemcpy D2D failed with error code {err}.")
+
+    return dst.view(*shape)
+
+
+def _copy_bytes_with_tensor(dst: int, src: int, num_bytes: int) -> None:
+    """Copy raw bytes between pointers using torch tensor semantics.
+
+    Note: This function only works for CPU-accessible memory. For device
+    memory (CUDA/XPU), use lmcache_memcpy_async with the appropriate runtime
+    library or PyTorch's tensor copy operations.
+    """
+    if num_bytes <= 0:
+        return
+
+    buffer_type = ctypes.c_uint8 * num_bytes
+    dst_tensor = torch.frombuffer(buffer_type.from_address(dst), dtype=torch.uint8)
+    src_tensor = torch.frombuffer(buffer_type.from_address(src), dtype=torch.uint8)
+    dst_tensor.copy_(src_tensor)
+
+
+class TransferDirection(IntEnum):
+    """Specifies the direction of a memory transfer.
+
+    Inherits from IntEnum so that members compare equal to plain ints
+    and to native pybind11 enum members with the same integer value.
+    Several call sites (and the fallback ops themselves) use
+    ``int(direction)`` to compare across backend / fallback boundaries.
+    """
+
+    H2D = 0
+    D2H = 1
+
+
+class EngineKVFormat(IntEnum):
+    """Enumeration of different engine KV cache memory layouts."""
+
+    # used by: vLLM CROSS_LAYER mode
+    NB_NL_TWO_BS_NH_HS = 0
+
+    # used by: vLLM non-MLA flash attention
+    NL_X_TWO_NB_BS_NH_HS = 1
+
+    # used by: vLLM non-MLA flash infer
+    NL_X_NB_TWO_BS_NH_HS = 2
+
+    # used by: vLLM MLA
+    NL_X_NB_BS_HS = 3
+
+    # used by: SGLang MHA (flash attention and flash infer)
+    TWO_X_NL_X_NBBS_NH_HS = 4
+
+    # used by: SGLang MLA
+    NL_X_NBBS_ONE_HS = 5
+
+    # used by: vLLM non-MLA flash attention (HND layout)
+    NL_X_TWO_NB_NH_BS_HS = 6
+
+    # used by: vLLM non-MLA flash infer (HND layout)
+    NL_X_NB_TWO_NH_BS_HS = 7
+
+    # used by: TRT-LLM cross-layer (HND layout)
+    NB_NL_TWO_NH_BS_HS = 8
+
+    # used by: SGLang MHA via the MP daemon path
+    TWO_X_NL_X_NB_BS_NH_HS = 9
+
+    # used by: vLLM non-MLA blocks-first attention with K/V fused into the
+    # trailing dim. Per-layer physical shape
+    # [num_blocks, num_heads, block_size, 2, head_size] -- the K/V "2" axis is
+    # second-to-last, recovered by splitting the fused [..., 2 * head_size].
+    NL_X_NB_NH_BS_TWO_HS = 10
+
+
+# Backward-compat alias
+GPUKVFormat = EngineKVFormat
+
+
+class PageBufferShapeDesc:
+    """Python stand-in for the C++ ``PageBufferShapeDesc`` struct.
+
+    Mirrors the pybind ``def_readwrite`` attributes in ``csrc/pybind.cpp``
+    so non-CUDA code paths can construct and inspect shape descriptors
+    without the compiled extension.
+
+    ``block_stride_elems`` captures the *physical* per-block step in
+    element units (= ``tensor.stride(0)``). For a tightly-packed paged
+    buffer it equals ``bs * kv_size * nh * hs`` (non-MLA) /
+    ``bs * nh * hs`` (MLA); for a vLLM KV pool where a group's row is
+    padded to the pool's maximum row width (e.g. DeepSeek V4 compressor
+    / indexer caches), it is strictly larger. Downstream kernels must
+    use this value instead of recomputing a "tight" stride from the
+    logical shape, otherwise they'll skip into the next block's padding
+    region and read/write the wrong slots.
+    """
+
+    __slots__ = (
+        "kv_size",
+        "nl",
+        "nb",
+        "bs",
+        "nh",
+        "hs",
+        "element_size",
+        "block_stride_elems",
+        "dtype",
+    )
+
+    def __init__(self) -> None:
+        self.kv_size: int = 0
+        self.nl: int = 0
+        self.nb: int = 0
+        self.bs: int = 0
+        self.nh: int = 0
+        self.hs: int = 0
+        self.element_size: int = 0
+        # 0 means "unset — fall back to tight stride"; any downstream
+        # consumer that needs exact addressing must check this.
+        self.block_stride_elems: int = 0
+        self.dtype: torch.dtype | None = None
+
+
+class _NativePlanType:
+    """Base for object-group transfer plan types that only exist natively.
+
+    The plan value structs (see ``csrc/mp_mem_kernels.cuh``) are built on the
+    Python side and consumed by the native ``execute_object_group_transfer``.
+    They have no pure-Python fallback, so constructing one without the compiled
+    ``c_ops`` extension is unsupported. Subclasses exist only so the CPU-only
+    build exposes the same names as ``c_ops``.
+    """
+
+    def __init__(self, *args: object, **kwargs: object) -> None:
+        raise NotImplementedError(
+            f"{type(self).__name__} requires the c_ops native extension; "
+            "no pure-Python fallback exists."
+        )
+
+
+class StagingCopy(_NativePlanType):
+    """Fallback stub for the native ``StagingCopy`` plan type."""
+
+
+class LaunchVar(_NativePlanType):
+    """Fallback stub for the native ``LaunchVar`` plan type."""
+
+
+class BatchStep(_NativePlanType):
+    """Fallback stub for the native ``BatchStep`` plan type."""
+
+
+class KernelGroupSpec(_NativePlanType):
+    """Fallback stub for the native ``KernelGroupSpec`` plan type."""
+
+
+def set_shape_desc_dtype(shape_desc: Any, dtype: torch.dtype) -> None:
+    """Best-effort ``shape_desc.dtype = dtype``.
+
+    The pure-Python ``PageBufferShapeDesc`` exposes a ``dtype`` slot so
+    the CPU fallback kernel can disambiguate float16 vs bfloat16 (both
+    have ``element_size == 2``). The pybind C++ struct in
+    ``csrc/pybind.cpp`` has no such field; assignment raises
+    ``AttributeError`` and is silently swallowed here so call sites
+    don't need to branch on the active backend.
+
+    Args:
+        shape_desc: A ``PageBufferShapeDesc`` instance (either the
+            pure-Python fallback or the C++ pybind struct).
+        dtype: The torch dtype to assign.
+    """
+    try:
+        shape_desc.dtype = dtype
+    except AttributeError:
+        pass
+
+
+# Cuda path goes through func cudaHostAlloc, which is
+# already page aligned by CUDA spec. This fallback shim mirrors that
+# guarantee so consumers that require page-aligned host buffers, in
+# particular the Rust raw-block backend when O_DIRECT is enabled, which
+# requires page-aligned buffer pointer
+try:
+    _PAGE_SIZE = os.sysconf("SC_PAGESIZE")
+except (AttributeError, ValueError, OSError):
+    _PAGE_SIZE = 4096
+
+logger = init_logger(__name__)
+
+# Cached one-shot decision: pin host buffers only when an accelerator is
+# present. Probed lazily on first allocation; if a pinned allocation ever
+# fails at runtime we flip this to False permanently and fall back to
+# pageable memory for all subsequent allocations.
+_use_pinned: Optional[bool] = None
+
+
+def _alloc_page_aligned_pinned_view(size: int) -> Tuple[torch.Tensor, int]:
+    """
+    Allocate a pinned CPU buffer whose first usable byte is page-aligned,
+    and return a torch view of ``size`` bytes plus its base pointer.
+
+    Internally over-allocates one extra page on a backing tensor, then
+    slices the aligned region out. The slice shares storage with the
+    backing tensor, so keeping the slice alive keeps the underlying
+    memory alive (no need to track the backing tensor separately).
+    """
+    # Pin the host buffer when an accelerator is present (probed once).
+    # StubCPUDevice.is_available returns False on CPU-only hosts.
+    global _use_pinned
+    if _use_pinned is None:
+        _use_pinned = torch_dev.is_available()
+    try:
+        backing = torch.empty(
+            size + _PAGE_SIZE, dtype=torch.uint8, pin_memory=_use_pinned
+        )
+    except RuntimeError:
+        if not _use_pinned:
+            # Pure host allocation failed (e.g. OOM); nothing to fall back to.
+            raise
+        logger.warning(
+            "Pinned host allocation failed on device '%s'; falling back to "
+            "unpinned allocation from now on.",
+            torch_device_type,
+        )
+        _use_pinned = False
+        backing = torch.empty(size + _PAGE_SIZE, dtype=torch.uint8, pin_memory=False)
+    # First-touch initialization on the entire backing region
+    backing.fill_(0)
+    base = backing.data_ptr()
+    # Distance from `base` to the next page boundary (0..PAGE_SIZE-1).
+    offset = (-base) % _PAGE_SIZE
+    aligned_view = backing[offset : offset + size]
+    return aligned_view, aligned_view.data_ptr()
+
+
+def alloc_pinned_numa_ptr(size: int, numa_id: int = 0) -> int:
+    """Non-CUDA equivalent of allocating pinned memory with NUMA awareness.
+    On XPU, uses pin_memory=True (SYCL USM host allocation) for fast transfers.
+    Note: NUMA node selection is not supported on non-CUDA."""
+
+    view, aligned_ptr = _alloc_page_aligned_pinned_view(size)
+    # view shares storage with its over-allocated backing tensor;
+    # holding the view in the registry transitively keeps the underlying
+    # memory alive.
+    _tensor_registry[aligned_ptr] = view
+    return aligned_ptr
+
+
+def free_pinned_numa_ptr(ptr: int, size: int | None = None) -> None:
+    """Non-CUDA equivalent of freeing a previously allocated NUMA pointer."""
+
+    # Release the tensor object for that pointer reference
+    _tensor_registry.pop(ptr, None)
+
+
+def alloc_pinned_ptr(size: int, device_id: int = 0) -> int:
+    """Non-CUDA equivalent of allocating pinned memory and returning pointer
+    to it. On XPU, uses pin_memory=True (SYCL USM host allocation) for
+    fast DMA transfers. On other non-CUDA platforms, pinning is not supported."""
+
+    view, aligned_ptr = _alloc_page_aligned_pinned_view(size)
+    _tensor_registry[aligned_ptr] = view
+    return aligned_ptr
+
+
+def free_pinned_ptr(ptr: int) -> None:
+    """Non-CUDA equivalent of freeing a previously allocated pinned pointer."""
+
+    # Release the tensor object for that pointer reference
+    _tensor_registry.pop(ptr, None)
+
+
+def batched_memcpy(src_ptrs: list[int], dst_ptrs: list[int], sizes: list[int]) -> None:
+    """Non-CUDA equivalent of the native batched memcpy helper."""
+
+    if len(src_ptrs) != len(dst_ptrs) or len(src_ptrs) != len(sizes):
+        raise ValueError(
+            "batched_memcpy expects equally sized src_ptrs, dst_ptrs, and sizes"
+        )
+
+    for src_ptr, dst_ptr, size in zip(src_ptrs, dst_ptrs, sizes, strict=True):
+        if size <= 0:
+            continue
+        ctypes.memmove(
+            ctypes.c_void_p(dst_ptr),
+            ctypes.c_void_p(src_ptr),
+            size,
+        )
+
+
+def alloc_shm_pinned_ptr(size: int, shm_name: str = "") -> int:
+    """Non-CUDA equivalent of allocating shared memory pinned pointer.
+    Uses multiprocessing.shared_memory for cross-platform POSIX shm.
+    Attempts to pin the buffer via cudaHostRegister for async D2H;
+    if pinning fails, continues without pinning."""
+
+    # Strip leading '/' for SharedMemory name
+    name = shm_name.lstrip("/") if shm_name else None
+
+    # Clean up stale shm segment if it exists
+    if name:
+        try:
+            stale = shared_memory.SharedMemory(name=name, create=False)
+            stale.close()
+            stale.unlink()
+        except FileNotFoundError:
+            pass
+
+    shm = shared_memory.SharedMemory(name=name, create=True, size=size)
+
+    array_type = ctypes.c_uint8 * size
+    buf = array_type.from_buffer(shm.buf)
+    ptr = ctypes.addressof(buf)
+
+    # Store references to keep them alive
+    tensor = torch.frombuffer(buf, dtype=torch.uint8)
+    _tensor_registry[ptr] = tensor
+    _buf_registry[ptr] = buf
+    _shm_registry[ptr] = shm
+
+    # Try to pin the SHM buffer for async D2H copies
+    if current_device_spec.pin_memory(ptr, size):
+        _pinned_ptr_registry[ptr] = size
+
+    return ptr
+
+
+def free_shm_pinned_ptr(ptr: int, size: int = 0, shm_name: str = "") -> None:
+    """Non-CUDA equivalent of freeing a shared memory
+    pinned pointer. Unregisters pinned memory if it was pinned."""
+
+    # Unpin if previously registered
+    if ptr in _pinned_ptr_registry:
+        current_device_spec.unpin_memory(ptr)
+        _pinned_ptr_registry.pop(ptr, None)
+
+    # Release in order: tensor -> ctypes buf -> shm
+    _tensor_registry.pop(ptr, None)
+    _buf_registry.pop(ptr, None)
+    shm = _shm_registry.pop(ptr, None)
+    if shm is not None:
+        shm.close()
+        shm.unlink()
+
+
+# Hugepage variants: non-CUDA platforms do not support hugepages, so these
+# fall back to the same regular pinned allocation.
+
+
+def alloc_hugepage_pinned_ptr(size: int, device_id: int = 0) -> int:
+    """Non-CUDA fallback for alloc_hugepage_pinned_ptr (no hugepage support)."""
+    warnings.warn(
+        "Hugepages requested but not available on non-CUDA platforms; "
+        "falling back to regular allocation.",
+        RuntimeWarning,
+        stacklevel=2,
+    )
+    return alloc_pinned_ptr(size, device_id)
+
+
+def free_hugepage_pinned_ptr(ptr: int, size: int = 0) -> None:
+    """Non-CUDA fallback for free_hugepage_pinned_ptr (no hugepage support)."""
+    free_pinned_ptr(ptr)
+
+
+def alloc_hugepage_pinned_numa_ptr(size: int, numa_id: int = 0) -> int:
+    """Non-CUDA fallback for alloc_hugepage_pinned_numa_ptr (no hugepage support)."""
+    warnings.warn(
+        "Hugepages requested but not available on non-CUDA platforms; "
+        "falling back to regular allocation.",
+        RuntimeWarning,
+        stacklevel=2,
+    )
+    return alloc_pinned_numa_ptr(size, numa_id)
+
+
+def free_hugepage_pinned_numa_ptr(ptr: int, size: int = 0) -> None:
+    """Non-CUDA fallback for free_hugepage_pinned_numa_ptr (no hugepage support)."""
+    free_pinned_numa_ptr(ptr, size)
+
+
+def alloc_numa_ptr(size: int, numa_id: int = 0) -> int:
+    """Non-CUDA equivalent of allocating numa memory and returning pointer
+    to it. Note: Numa memory is not supported on non-CUDA."""
+    return alloc_pinned_numa_ptr(size, numa_id)
+
+
+def free_numa_ptr(ptr: int, size: int | None = None) -> None:
+    """Non-CUDA equivalent of freeing a previously allocated NUMA pointer."""
+    return free_pinned_numa_ptr(ptr, size)
+
+
+def multi_layer_kv_transfer(
+    key_value: torch.Tensor,
+    key_value_ptrs: torch.Tensor | list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+    paged_memory_device: torch.device,
+    page_buffer_size: int,
+    direction: TransferDirection,
+    engine_kv_format: EngineKVFormat,
+    block_size: int = 0,
+    head_size: int = 0,
+    skip_prefix_n_tokens: int = 0,
+):
+    """
+    Fully vectorized Python fallback for multi_layer_kv_transfer.
+    Eliminates ALL token- and KV-level Python loops.
+    """
+    if not isinstance(key_value_ptrs, (torch.Tensor, list)):
+        raise TypeError(
+            f"Expected torch.Tensor or list, but got {type(key_value_ptrs).__name__}"
+        )
+
+    # TODO: Implement head_size support for HND layouts (NL_X_TWO_NB_NH_BS_HS,
+    # NL_X_NB_TWO_NH_BS_HS) as next step.
+    if int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS),
+        int(EngineKVFormat.NL_X_NB_TWO_NH_BS_HS),
+    ):
+        raise NotImplementedError(
+            "HND layouts (NL_X_TWO_NB_NH_BS_HS, NL_X_NB_TWO_NH_BS_HS) "
+            "are not supported in the non-CUDA fallback. "
+            "head_size parameter is required but not implemented in this path."
+        )
+
+    # 1. Filter out invalid slots.
+    #    valid_mask_kv:  on key_value.device, used to index key_value
+    #    valid_slots:    on paged_memory_device, used to index paged_tensor
+    kv_device = key_value.device
+    slots_kv = slot_mapping.to(dtype=torch.long).to(kv_device)
+    valid_mask_kv = slots_kv >= 0
+    # Skip the first skip_prefix_n_tokens tokens from transfer.
+    # This matches the CUDA kernel semantics where the grid starts at
+    # token_id=0 but indexes key_value/slot_mapping at
+    # kv_token_id = token_id + skip_prefix_n_tokens.
+    # By masking them as invalid, the vectorized indexing via valid_mask_kv
+    # naturally skips them while keeping key_value indices aligned.
+    if skip_prefix_n_tokens > 0:
+        valid_mask_kv[:skip_prefix_n_tokens] = False
+    if not valid_mask_kv.any():
+        return
+
+    valid_slots = slots_kv[valid_mask_kv].to(paged_memory_device)
+
+    # 2. Determine architecture variant and tensor dimensions.
+    is_mla = int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_NB_BS_HS),
+        int(EngineKVFormat.NL_X_NBBS_ONE_HS),
+    )
+    is_flash_infer = int(engine_kv_format) == int(EngineKVFormat.NL_X_NB_TWO_BS_NH_HS)
+
+    num_layers = key_value.size(1)
+    hidden_size = key_value.size(3)
+
+    # For the flash_infer interleaved layout, pre-compute block-level indices.
+    if is_flash_infer:
+        block_indices = valid_slots // block_size
+        block_offsets = valid_slots % block_size
+
+    # Determine the physical shape of the underlying paged tensor
+    # (used when wrapping a raw pointer).
+    layer_shape: Tuple[int, ...]
+
+    if is_mla:
+        layer_shape = (page_buffer_size, hidden_size)
+    elif is_flash_infer:
+        num_blocks = page_buffer_size // block_size
+        layer_shape = (num_blocks, 2, block_size, hidden_size)
+    else:
+        layer_shape = (2, page_buffer_size, hidden_size)
+
+    # 3. Iterate over layers — the only remaining Python-level loop.
+    for layer_id in range(num_layers):
+        # --- A. Obtain the physical device-memory view for this layer. ---
+        if isinstance(key_value_ptrs, list):
+            paged_tensor = key_value_ptrs[layer_id]
+        else:
+            ptr = int(key_value_ptrs[layer_id].item())
+            # Convert a raw device pointer into a PyTorch tensor view.
+            paged_tensor = _tensor_from_ptr(
+                ptr, layer_shape, key_value.dtype, paged_memory_device
+            )
+
+        # --- B. Vectorized bulk data transfer. ---
+        if is_mla:
+            # Paged layout : [page_buffer_size, hidden_size]
+            # key_value layout: [1, num_layers, num_tokens, hidden_size]
+            if int(direction) == int(TransferDirection.H2D):
+                lmc_valid = key_value[0, layer_id, valid_mask_kv, :]
+                paged_tensor.index_copy_(
+                    0, valid_slots, lmc_valid.to(paged_tensor.device)
+                )
+            else:
+                gathered = paged_tensor.index_select(0, valid_slots)
+                key_value[0, layer_id, valid_mask_kv, :] = gathered.to(
+                    kv_device, non_blocking=False
+                )
+        elif is_flash_infer:
+            # Paged layout : [num_blocks, 2, block_size, hidden_size]
+            # key_value layout: [2, num_layers, num_tokens, hidden_size]
+            if int(direction) == int(TransferDirection.H2D):
+                lmc_valid = key_value[:, layer_id, valid_mask_kv, :]
+                src_data = lmc_valid.transpose(0, 1).to(paged_memory_device)
+                # src_data: [num_valid, 2, hidden_size]
+                paged_tensor[block_indices, :, block_offsets, :] = src_data
+            else:
+                gathered = paged_tensor[block_indices, :, block_offsets, :]
+                # gathered: [num_valid, 2, hidden_size]
+                key_value[:, layer_id, valid_mask_kv, :] = gathered.to(
+                    kv_device, non_blocking=False
+                ).transpose(0, 1)
+        else:
+            # Paged layout : [2, page_buffer_size, hidden_size]
+            # key_value layout: [2, num_layers, num_tokens, hidden_size]
+            if int(direction) == int(TransferDirection.H2D):
+                lmc_valid = key_value[:, layer_id, valid_mask_kv, :]
+                paged_tensor.index_copy_(
+                    1, valid_slots, lmc_valid.to(paged_memory_device)
+                )
+            else:
+                gathered = paged_tensor.index_select(1, valid_slots)
+                key_value[:, layer_id, valid_mask_kv, :] = gathered.to(
+                    kv_device, non_blocking=False
+                )
+
+
+def multi_layer_kv_transfer_unilateral(
+    key_value: torch.Tensor,
+    key_value_ptrs: torch.Tensor | list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+    paged_memory_device: torch.device,
+    page_buffer_size: int,
+    direction: TransferDirection,
+    engine_kv_format: EngineKVFormat,
+):
+    """
+    Python fallback for multi_layer_kv_transfer_unilateral
+
+    Handles SGLang MHA format where K and V paged buffers are stored separately:
+        ptrs = [K_layer0, K_layer1, ..., V_layer0, V_layer1, ...]
+        each buffer shape: [page_buffer_size, hidden_size]
+
+    For MLA, delegates to multi_layer_kv_transfer (same as C++ implementation).
+
+    key_value_ptrs:
+        - If torch.Tensor: int64 tensor containing raw memory pointers.
+        - If list[torch.Tensor]: list of tensor objects.
+
+    key_value layout:
+        - Standard: [2, num_layers, num_tokens, hidden_size]
+        - MLA:      [1, num_layers, num_tokens, hidden_size]
+
+    direction:
+        H2D = LMCache  -> PagedBuffer
+        D2H = PagedBuffer -> LMCache
+    """
+    is_mla = int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_NB_BS_HS),
+        int(EngineKVFormat.NL_X_NBBS_ONE_HS),
+    )
+
+    # MLA case collapses back to multi_layer_kv_transfer
+    # (vLLM and SGLang indexing are compatible)
+    if is_mla:
+        return multi_layer_kv_transfer(
+            key_value,
+            key_value_ptrs,
+            slot_mapping,
+            paged_memory_device,
+            page_buffer_size,
+            direction,
+            engine_kv_format,
+            0,  # block_size unused for MLA formats
+        )
+    # ── Non-MLA path: unilateral (separate K/V buffers per layer) ──
+    num_layers = key_value.size(1)
+    hidden_size = key_value.size(3)
+    layer_shape = (page_buffer_size, hidden_size)
+
+    kv_device = key_value.device
+    slots_kv = slot_mapping.to(dtype=torch.long).to(kv_device)
+    valid_mask_kv = slots_kv >= 0
+    if not valid_mask_kv.any():
+        return
+
+    valid_slots = slots_kv[valid_mask_kv].to(paged_memory_device)
+
+    for layer_id in range(num_layers):
+        for kv_idx in range(2):  # 0 = K, 1 = V
+            buffer_idx = layer_id + kv_idx * num_layers
+            if isinstance(key_value_ptrs, list):
+                paged_tensor = key_value_ptrs[buffer_idx]
+            else:
+                ptr = int(key_value_ptrs[buffer_idx].item())
+                paged_tensor = _tensor_from_ptr(
+                    ptr, layer_shape, key_value.dtype, paged_memory_device
+                )
+
+            if int(direction) == int(TransferDirection.H2D):
+                lmc_valid = key_value[kv_idx, layer_id, valid_mask_kv, :]
+                paged_tensor.index_copy_(
+                    0, valid_slots, lmc_valid.to(paged_memory_device)
+                )
+            else:
+                gathered = paged_tensor.index_select(0, valid_slots)
+                key_value[kv_idx, layer_id, valid_mask_kv, :] = gathered.to(kv_device)
+
+
+# Pure-Python mirrors of the c_ops predicates (csrc/engine_kv_format.h); the
+# parity test pins these to the same names and signatures.
+def is_cross_layer(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when all layers live in one fused tensor."""
+    return int(engine_kv_format) in (
+        int(EngineKVFormat.NB_NL_TWO_BS_NH_HS),
+        int(EngineKVFormat.NB_NL_TWO_NH_BS_HS),
+    )
+
+
+def is_kv_list(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when keys and values are two separate top-level lists."""
+    return int(engine_kv_format) in (
+        int(EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS),
+        int(EngineKVFormat.TWO_X_NL_X_NB_BS_NH_HS),
+    )
+
+
+def is_layer_list(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when the structure is one list entry per layer."""
+    return int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_TWO_NB_BS_NH_HS),
+        int(EngineKVFormat.NL_X_NB_TWO_BS_NH_HS),
+        int(EngineKVFormat.NL_X_NB_BS_HS),
+        int(EngineKVFormat.NL_X_NBBS_ONE_HS),
+        int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS),
+        int(EngineKVFormat.NL_X_NB_TWO_NH_BS_HS),
+        int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS),
+    )
+
+
+def is_mla(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when a KV format uses MLA paged layout."""
+    return int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_NB_BS_HS),
+        int(EngineKVFormat.NL_X_NBBS_ONE_HS),
+    )
+
+
+def _is_cross_layer_format(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when a KV format uses a single cross-layer tensor."""
+    return is_cross_layer(engine_kv_format)
+
+
+def _is_sglang_mha_format(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when a KV format uses SGLang MHA layout (2*NL tensors)."""
+    return is_kv_list(engine_kv_format)
+
+
+def _is_hnd_format(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when a per-layer KV format stores heads before block tokens (HND)."""
+    return int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS),
+        int(EngineKVFormat.NL_X_NB_TWO_NH_BS_HS),
+        int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS),
+    )
+
+
+def _is_mla_format(engine_kv_format: EngineKVFormat) -> bool:
+    """Return True when a KV format uses MLA paged layout."""
+    return is_mla(engine_kv_format)
+
+
+_ELEMENT_SIZE_TO_DTYPE: dict[int, torch.dtype] = {
+    # Maps the byte width of a KV-cache element to a representative torch dtype.
+    # Only widths that commonly appear in KV caches are listed; 1-byte entries
+    # are treated as uint8 (raw bytes), 2-byte as float16, 4-byte as float32.
+    # Note: bfloat16 also has element_size == 2 but cannot be distinguished here;
+    # callers that need exact dtype should supply it explicitly.
+    1: torch.uint8,
+    2: torch.float16,
+    4: torch.float32,
+}
+
+
+def _is_ptr_tensor(x: object) -> bool:
+    """Return True when *x* is a 1-D pointer tensor (int64 or uint64)."""
+    return (
+        isinstance(x, torch.Tensor)
+        and x.dtype in (torch.int64, torch.uint64)
+        and x.ndim == 1
+    )
+
+
+def _per_layer_paged_shape(
+    engine_kv_format: EngineKVFormat,
+    nb: int,
+    bs: int,
+    nh: int,
+    hs: int,
+) -> tuple[int, ...]:
+    """Return the logical shape of a single per-layer paged buffer tensor.
+
+    Args:
+        engine_kv_format: The format enum that describes how K/V tokens are laid out.
+        nb: Number of blocks in the paged buffer (``shape_desc.nb``).
+        bs: Tokens per block / block size (``shape_desc.bs``).
+        nh: Number of attention heads (``shape_desc.nh``).
+        hs: Per-head hidden size (``shape_desc.hs``).
+
+    Returns:
+        A tuple representing the shape needed to reconstruct one layer's tensor
+        from a raw pointer via :func:`_tensor_from_ptr`.
+    """
+    fmt = int(engine_kv_format)
+    if fmt == int(EngineKVFormat.NL_X_NBBS_ONE_HS):
+        return (nb * bs, 1, hs)
+    if fmt == int(EngineKVFormat.NL_X_NB_BS_HS):
+        return (nb, bs, hs)
+    if fmt == int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS):
+        return (2, nb, nh, bs, hs)
+    if fmt == int(EngineKVFormat.NL_X_NB_TWO_NH_BS_HS):
+        return (nb, 2, nh, bs, hs)
+    if fmt == int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS):
+        # vLLM CPU blocks-first fused KV: K and V interleaved at the
+        # second-to-last dim so each layer is [NB, NH, BS, 2, HS].
+        return (nb, nh, bs, 2, hs)
+    if fmt == int(EngineKVFormat.NL_X_TWO_NB_BS_NH_HS):
+        return (2, nb, bs, nh, hs)
+    if fmt == int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS):
+        return (nb, nh, bs, 2, hs)
+    # Covers NL_X_NB_TWO_BS_NH_HS and any future NHD variants.
+    return (nb, 2, bs, nh, hs)
+
+
+def _infer_kv_dtype(
+    paged_buffer_ptrs_tensor: object,
+    lmcache_objects_ptrs: object,
+    shape_desc: "PageBufferShapeDesc",
+) -> torch.dtype:
+    """Infer the KV element dtype from whichever inputs carry it.
+
+    Inference order (first match wins):
+    1. ``shape_desc.dtype`` — authoritative when set (requires the
+       ``set_shape_desc_dtype`` helper from PR #3514; correctly distinguishes
+       float16 vs bfloat16 which share ``element_size == 2``).
+    2. ``paged_buffer_ptrs_tensor`` — if it is a non-pointer tensor or a list
+       of tensors (including nested SGLang MHA lists), the dtype of the first
+       tensor is used.
+    3. ``lmcache_objects_ptrs`` — if it is a list of tensors, the dtype of the
+       first chunk tensor is used.
+    4. ``shape_desc.element_size`` — looked up in :data:`_ELEMENT_SIZE_TO_DTYPE`
+       (ambiguous for 2-byte types; kept only as last-resort fallback).
+    5. ``torch.bfloat16`` — silent default when no other source is available.
+    """
+    # Prefer shape_desc.dtype — it is exact and avoids the element_size ambiguity.
+    if shape_desc is not None:
+        sd_dtype = getattr(shape_desc, "dtype", None)
+        if sd_dtype is not None:
+            return sd_dtype
+    if isinstance(paged_buffer_ptrs_tensor, list) and paged_buffer_ptrs_tensor:
+        first = paged_buffer_ptrs_tensor[0]
+        if isinstance(first, list) and first and isinstance(first[0], torch.Tensor):
+            return first[0].dtype
+        if isinstance(first, torch.Tensor):
+            return first.dtype
+    if isinstance(paged_buffer_ptrs_tensor, torch.Tensor) and not _is_ptr_tensor(
+        paged_buffer_ptrs_tensor
+    ):
+        return paged_buffer_ptrs_tensor.dtype
+    if isinstance(lmcache_objects_ptrs, list) and lmcache_objects_ptrs:
+        if isinstance(lmcache_objects_ptrs[0], torch.Tensor):
+            return lmcache_objects_ptrs[0].dtype
+    if shape_desc is not None and shape_desc.element_size > 0:
+        dtype = _ELEMENT_SIZE_TO_DTYPE.get(shape_desc.element_size)
+        if dtype is None:
+            raise ValueError(
+                f"Unsupported element_size {shape_desc.element_size!r} in "
+                "shape_desc; cannot infer KV dtype. "
+                f"Supported sizes: {sorted(_ELEMENT_SIZE_TO_DTYPE)}"
+            )
+        return dtype
+    return torch.bfloat16
+
+
+def _normalize_paged_layers(
+    paged_buffer_ptrs_tensor: "torch.Tensor | list",
+    engine_kv_format: EngineKVFormat,
+    shape_desc: "PageBufferShapeDesc | None" = None,
+    device: "torch.device | str | None" = None,
+    dtype: "torch.dtype | None" = None,
+) -> "torch.Tensor | list[torch.Tensor] | list[list[torch.Tensor]]":
+    """Normalize paged buffer input based on GPU KV format.
+
+    Accepts either tensor-form inputs (list / Tensor) or a 1-D pointer tensor
+    (int64 / uint64).  When a pointer tensor is provided *shape_desc*, *device*,
+    and *dtype* must be supplied so the tensors can be reconstructed via
+    :func:`_tensor_from_ptr`.
+
+    Returns:
+        - Single ``torch.Tensor`` for cross-layer formats.
+        - ``list[list[torch.Tensor]]`` (2 x NL) for SGLang MHA formats.
+        - ``list[torch.Tensor]`` (per-layer) for all other formats.
+    """
+    if _is_cross_layer_format(engine_kv_format):
+        if isinstance(paged_buffer_ptrs_tensor, torch.Tensor):
+            if _is_ptr_tensor(paged_buffer_ptrs_tensor):
+                # 1-D pointer tensor with a single entry → reconstruct full tensor.
+                if shape_desc is None or device is None or dtype is None:
+                    raise ValueError(
+                        "_normalize_paged_layers: shape_desc, device, and dtype are "
+                        "required when paged_buffer_ptrs_tensor is a pointer tensor"
+                    )
+                nb = int(shape_desc.nb)
+                nl = int(shape_desc.nl)
+                bs = int(shape_desc.bs)
+                nh = int(shape_desc.nh)
+                hs = int(shape_desc.hs)
+                if int(engine_kv_format) == int(EngineKVFormat.NB_NL_TWO_NH_BS_HS):
+                    shape: tuple[int, ...] = (nb, nl, 2, nh, bs, hs)
+                else:
+                    shape = (nb, nl, 2, bs, nh, hs)
+                ptr = int(paged_buffer_ptrs_tensor[0].item())
+                return _tensor_from_ptr(ptr, shape, dtype, device)
+            return paged_buffer_ptrs_tensor
+        raise TypeError(
+            "Cross-layer formats require a single torch.Tensor input; "
+            "got: " + type(paged_buffer_ptrs_tensor).__name__
+        )
+    if _is_sglang_mha_format(engine_kv_format):
+        if _is_ptr_tensor(paged_buffer_ptrs_tensor):
+            # 1-D pointer tensor [K_L0,...,K_LN-1, V_L0,...,V_LN-1] → nested list.
+            if shape_desc is None or device is None or dtype is None:
+                raise ValueError(
+                    "_normalize_paged_layers: shape_desc, device, and dtype are "
+                    "required when paged_buffer_ptrs_tensor is a pointer tensor"
+                )
+            nb = int(shape_desc.nb)
+            nl = int(shape_desc.nl)
+            bs = int(shape_desc.bs)
+            nh = int(shape_desc.nh)
+            hs = int(shape_desc.hs)
+            is_flat = int(engine_kv_format) == int(EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS)
+            per_layer_shape: tuple[int, ...] = (
+                (nb * bs, nh, hs) if is_flat else (nb, bs, nh, hs)
+            )
+            ptrs = [int(p.item()) for p in paged_buffer_ptrs_tensor]
+            k_tensors = [
+                _tensor_from_ptr(ptrs[i], per_layer_shape, dtype, device)
+                for i in range(nl)
+            ]
+            v_tensors = [
+                _tensor_from_ptr(ptrs[nl + i], per_layer_shape, dtype, device)
+                for i in range(nl)
+            ]
+            return [k_tensors, v_tensors]
+        if isinstance(paged_buffer_ptrs_tensor, list):
+            # Already nested [[K tensors], [V tensors]]
+            if (
+                len(paged_buffer_ptrs_tensor) == 2
+                and isinstance(paged_buffer_ptrs_tensor[0], list)
+                and all(
+                    isinstance(t, torch.Tensor)
+                    for group in paged_buffer_ptrs_tensor
+                    for t in group
+                )
+            ):
+                return paged_buffer_ptrs_tensor
+            # Flat list [K_L0, ..., K_LN-1, V_L0, ..., V_LN-1]
+            if all(isinstance(t, torch.Tensor) for t in paged_buffer_ptrs_tensor):
+                if len(paged_buffer_ptrs_tensor) % 2 != 0:
+                    raise ValueError(
+                        "Flat SGLang MHA list must have even length (2*NL)"
+                    )
+                half = len(paged_buffer_ptrs_tensor) // 2
+                return [
+                    paged_buffer_ptrs_tensor[:half],
+                    paged_buffer_ptrs_tensor[half:],
+                ]
+        raise TypeError(
+            "SGLang MHA formats require a list[list[torch.Tensor]], a flat "
+            "list[torch.Tensor] (2*NL entries), or a 1-D pointer tensor; "
+            "got: " + type(paged_buffer_ptrs_tensor).__name__
+        )
+    # Per-layer formats
+    if _is_ptr_tensor(paged_buffer_ptrs_tensor):
+        # 1-D pointer tensor [ptr_L0, ..., ptr_LN-1] → list of per-layer tensors.
+        if shape_desc is None or device is None or dtype is None:
+            raise ValueError(
+                "_normalize_paged_layers: shape_desc, device, and dtype are "
+                "required when paged_buffer_ptrs_tensor is a pointer tensor"
+            )
+        nb = int(shape_desc.nb)
+        bs = int(shape_desc.bs)
+        nh = int(shape_desc.nh)
+        hs = int(shape_desc.hs)
+        per_shape = _per_layer_paged_shape(engine_kv_format, nb, bs, nh, hs)
+        return [
+            _tensor_from_ptr(int(p.item()), per_shape, dtype, device)
+            for p in paged_buffer_ptrs_tensor
+        ]
+    if isinstance(paged_buffer_ptrs_tensor, list):
+        if not all(isinstance(t, torch.Tensor) for t in paged_buffer_ptrs_tensor):
+            raise TypeError(
+                "paged_buffer_ptrs_tensor list must contain torch.Tensor entries"
+            )
+        return paged_buffer_ptrs_tensor
+    raise TypeError(
+        "paged_buffer_ptrs_tensor must be a list[torch.Tensor] or 1-D pointer tensor; "
+        "got: " + type(paged_buffer_ptrs_tensor).__name__
+    )
+
+
+def _normalize_lmcache_objects(
+    lmcache_objects_ptrs: "list[int] | list[torch.Tensor]",
+    shape_desc: "PageBufferShapeDesc | None" = None,
+    lmcache_chunk_size: "int | None" = None,
+    engine_kv_format: "EngineKVFormat | None" = None,
+    dtype: "torch.dtype | None" = None,
+) -> list[torch.Tensor]:
+    """Normalize LMCache object inputs to chunk tensors.
+
+    Accepts either a list of chunk tensors or a ``list[int]`` of raw CPU pointers.
+    When a pointer list is provided *shape_desc*, *lmcache_chunk_size*,
+    *engine_kv_format*, and *dtype* must be supplied so the tensors can be
+    reconstructed via :func:`_tensor_from_ptr` on the CPU.
+    """
+    if not isinstance(lmcache_objects_ptrs, list):
+        raise TypeError(
+            "lmcache_objects_ptrs must be a list[torch.Tensor] or list[int]; "
+            "got: " + type(lmcache_objects_ptrs).__name__
+        )
+    if not lmcache_objects_ptrs:
+        return []
+    if isinstance(lmcache_objects_ptrs[0], torch.Tensor):
+        return lmcache_objects_ptrs  # type: ignore[return-value]
+    if isinstance(lmcache_objects_ptrs[0], int):
+        # Pointer mode: reconstruct chunk tensors (always on CPU).
+        if (
+            shape_desc is None
+            or lmcache_chunk_size is None
+            or engine_kv_format is None
+            or dtype is None
+        ):
+            raise ValueError(
+                "_normalize_lmcache_objects: shape_desc, lmcache_chunk_size, "
+                "engine_kv_format, and dtype are required when lmcache_objects_ptrs "
+                "contains raw int pointers"
+            )
+        nl = int(shape_desc.nl)
+        nh = int(shape_desc.nh)
+        hs = int(shape_desc.hs)
+        chunk_tokens = lmcache_chunk_size
+        if _is_mla_format(engine_kv_format):
+            chunk_shape: tuple[int, ...] = (nl, chunk_tokens, hs)
+        else:
+            chunk_shape = (2, nl, chunk_tokens, nh * hs)
+        return [
+            _tensor_from_ptr(ptr, chunk_shape, dtype, "cpu")
+            for ptr in lmcache_objects_ptrs
+        ]
+    raise TypeError(
+        "lmcache_objects_ptrs must be a list[torch.Tensor] or list[int]; "
+        "got list containing: " + type(lmcache_objects_ptrs[0]).__name__
+    )
+
+
+def _to_block_id_list(block_ids: torch.Tensor | list[int]) -> list[int]:
+    """Convert block IDs from tensor/list form into a Python ``list[int]``."""
+    if isinstance(block_ids, torch.Tensor):
+        return [int(x) for x in block_ids.to(dtype=torch.int64).cpu().tolist()]
+    if isinstance(block_ids, list):
+        return [int(x) for x in block_ids]
+    raise TypeError("block_ids must be a torch.Tensor or list[int]")
+
+
+def multi_layer_block_kv_transfer(
+    paged_buffer_ptrs_tensor: "torch.Tensor | list",
+    lmcache_objects_ptrs: list[int] | list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    device: torch.device | str,
+    direction: TransferDirection,
+    shape_desc: PageBufferShapeDesc,
+    lmcache_chunk_size: int,
+    engine_kv_format: EngineKVFormat,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """Python fallback implementation of block-based multi-layer KV transfer.
+
+    Signature intentionally mirrors the C++ binding so callers can invoke
+    ``lmcache.c_ops.multi_layer_block_kv_transfer`` uniformly on native and
+    fallback backends.
+
+    Args:
+        paged_buffer_ptrs_tensor: Paged buffer pointers or tensors.
+        lmcache_objects_ptrs: LMCache object pointers or chunk tensors.
+        block_ids: Ordered engine block IDs for the transfer.
+        device: Target device for the transfer.
+        direction: Transfer direction (H2D or D2H).
+        shape_desc: Shape descriptor of the page buffer.
+        lmcache_chunk_size: Chunk size of LMCache objects.
+        engine_kv_format: GPU KV cache format.
+        skip_prefix_n_blocks: Number of leading blocks to skip.
+
+    Returns:
+        None
+
+    Raises:
+        ValueError: If chunk size is invalid, or transfer direction is unsupported.
+        TypeError: If input types do not match expected types.
+    """
+    if lmcache_chunk_size <= 0:
+        raise ValueError("lmcache_chunk_size must be positive")
+    if int(shape_desc.bs) <= 0 or lmcache_chunk_size % int(shape_desc.bs) != 0:
+        raise ValueError(
+            "lmcache_chunk_size must be a positive multiple of shape_desc.bs"
+        )
+    if skip_prefix_n_blocks < 0:
+        raise ValueError("skip_prefix_n_blocks must be >= 0")
+
+    is_d2h = int(direction) == int(TransferDirection.D2H)
+    is_h2d = int(direction) == int(TransferDirection.H2D)
+    if not (is_d2h or is_h2d):
+        raise ValueError(f"Unsupported transfer direction: {direction!r}")
+
+    kv_dtype = _infer_kv_dtype(
+        paged_buffer_ptrs_tensor, lmcache_objects_ptrs, shape_desc
+    )
+    normalized = _normalize_paged_layers(
+        paged_buffer_ptrs_tensor,
+        engine_kv_format,
+        shape_desc=shape_desc,
+        device=device,
+        dtype=kv_dtype,
+    )
+    object_tensors = _normalize_lmcache_objects(
+        lmcache_objects_ptrs,
+        shape_desc=shape_desc,
+        lmcache_chunk_size=lmcache_chunk_size,
+        engine_kv_format=engine_kv_format,
+        dtype=kv_dtype,
+    )
+    n_block_ids = (
+        int(block_ids.numel())
+        if isinstance(block_ids, torch.Tensor)
+        else len(block_ids)
+    )
+    blocks_per_object = lmcache_chunk_size // int(shape_desc.bs)
+    block_size = int(shape_desc.bs)
+
+    if _is_cross_layer_format(engine_kv_format):
+        _transfer_cross_layer(
+            normalized,
+            object_tensors,
+            block_ids,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            engine_kv_format,
+            is_d2h,
+            skip_prefix_n_blocks,
+        )
+    elif _is_sglang_mha_format(engine_kv_format):
+        _transfer_sglang_mha(
+            normalized,
+            object_tensors,
+            block_ids,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            engine_kv_format,
+            is_d2h,
+            skip_prefix_n_blocks,
+        )
+    elif _is_mla_format(engine_kv_format):
+        _transfer_per_layer_mla(
+            normalized,
+            object_tensors,
+            block_ids,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            engine_kv_format,
+            is_d2h,
+            skip_prefix_n_blocks,
+        )
+    elif _is_hnd_format(engine_kv_format):
+        _transfer_per_layer_hnd(
+            normalized,
+            object_tensors,
+            block_ids,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            engine_kv_format,
+            is_d2h,
+            skip_prefix_n_blocks,
+        )
+    else:
+        _transfer_per_layer_nhd(
+            normalized,
+            object_tensors,
+            block_ids,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            engine_kv_format,
+            is_d2h,
+            skip_prefix_n_blocks,
+        )
+
+
+def execute_object_group_transfer(
+    direction: TransferDirection,
+    device: torch.device | str,
+    host_buffer_alignment: int,
+    kernel_group_specs: list,
+    batch_steps: list,
+) -> None:
+    """Python fallback for the native object-group transfer plan executor.
+
+    The planned/batched object-group transfer (see ``csrc/mp_mem_kernels.cuh``
+    and ``execute_object_group_transfer``) is only implemented in the compiled
+    ``c_ops`` extension. The signature mirrors the C++ binding so callers can
+    dispatch uniformly, but there is no pure-Python equivalent.
+
+    Args:
+        direction: Transfer direction (H2D or D2H).
+        device: CUDA device of the transfer.
+        host_buffer_alignment: Host buffer alignment for staging copies.
+        kernel_group_specs: Per-kernel-group invariants (native ``KernelGroupSpec``).
+        batch_steps: Ordered per-batch staging + launch work (native ``BatchStep``).
+
+    Raises:
+        NotImplementedError: Always; requires the c_ops native extension.
+    """
+    raise NotImplementedError(
+        "execute_object_group_transfer requires the c_ops native extension; "
+        "no pure-Python fallback exists."
+    )
+
+
+def _valid_block_range(
+    object_idx: int,
+    block_id_list: list[int],
+    blocks_per_object: int,
+    block_size: int,
+    skip_prefix_n_blocks: int,
+) -> tuple[list[int], int] | None:
+    """Return valid engine block IDs and their LMCache object token offset.
+
+    Args:
+        object_idx: Index of the LMCache object/chunk being processed.
+        block_id_list: Full ordered engine block ids for the transfer.
+        blocks_per_object: Number of blocks represented by one LMCache object.
+        block_size: Number of tokens per block.
+        skip_prefix_n_blocks: Number of leading flat block positions to skip.
+
+    Returns:
+        ``None`` if this object has no valid blocks after skip handling.
+        Otherwise, a tuple of valid engine block ids and the token offset
+        within this LMCache object where those blocks start.
+    """
+    object_flat_start = object_idx * blocks_per_object
+    valid_flat_start = max(object_flat_start, skip_prefix_n_blocks)
+    valid_flat_end = min(object_flat_start + blocks_per_object, len(block_id_list))
+    if valid_flat_start >= valid_flat_end:
+        return None
+    offset_in_object = (valid_flat_start - object_flat_start) * block_size
+    return block_id_list[valid_flat_start:valid_flat_end], offset_in_object
+
+
+def _valid_block_range_indices(
+    object_idx: int,
+    n_block_ids: int,
+    blocks_per_object: int,
+    block_size: int,
+    skip_prefix_n_blocks: int,
+) -> tuple[int, int, int] | None:
+    """Return valid [start, end) range over flat block IDs and object token offset."""
+    object_flat_start = object_idx * blocks_per_object
+    valid_flat_start = max(object_flat_start, skip_prefix_n_blocks)
+    valid_flat_end = min(object_flat_start + blocks_per_object, n_block_ids)
+    if valid_flat_start >= valid_flat_end:
+        return None
+    offset_in_object = (valid_flat_start - object_flat_start) * block_size
+    return valid_flat_start, valid_flat_end, offset_in_object
+
+
+def _transfer_cross_layer(
+    paged_tensor: torch.Tensor,
+    object_tensors: list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    n_block_ids: int,
+    blocks_per_object: int,
+    block_size: int,
+    engine_kv_format: EngineKVFormat,
+    is_d2h: bool,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """Handle cross-layer formats: single tensor [NB, NL, 2, ...]."""
+    # NHD: [NB, NL, 2, BS, NH, HS]  HND: [NB, NL, 2, NH, BS, HS]
+    is_hnd = int(engine_kv_format) == int(EngineKVFormat.NB_NL_TWO_NH_BS_HS)
+    num_layers = paged_tensor.shape[1]
+
+    if is_hnd:
+        # [NB, NL, 2, NH, BS, HS]
+        nh = paged_tensor.shape[3]
+        hs = paged_tensor.shape[5]
+    else:
+        # [NB, NL, 2, BS, NH, HS]
+        nh = paged_tensor.shape[4]
+        hs = paged_tensor.shape[5]
+
+    # H2D: pre-transfer objects to paged device
+    if not is_d2h and object_tensors:
+        objs_on_device = [obj.to(paged_tensor.device) for obj in object_tensors]
+    block_ids_dev = torch.as_tensor(
+        block_ids, dtype=torch.long, device=paged_tensor.device
+    )
+
+    for object_idx, obj in enumerate(object_tensors):
+        valid = _valid_block_range_indices(
+            object_idx,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            skip_prefix_n_blocks,
+        )
+        if valid is None:
+            continue
+        idx_start, idx_end, offset_in_object = valid
+        n_valid = idx_end - idx_start
+        token_end = offset_in_object + n_valid * block_size
+        eff_idx = block_ids_dev[idx_start:idx_end]
+
+        if is_d2h:
+            selected = paged_tensor.index_select(0, eff_idx)
+
+        for layer_idx in range(num_layers):
+            for kv in range(2):
+                if is_d2h:
+                    slice_t = selected[:, layer_idx, kv]
+                    if is_hnd:
+                        # N=n_valid, BS=block_size:
+                        # [N, NH, BS, HS] -> [N, BS, NH, HS] -> [N*BS, NH*HS]
+                        flat = slice_t.permute(0, 2, 1, 3).reshape(
+                            n_valid * block_size, nh * hs
+                        )
+                    else:
+                        # [N, BS, NH, HS] → [N*BS, NH*HS]
+                        flat = slice_t.reshape(n_valid * block_size, nh * hs)
+                    obj[kv, layer_idx, offset_in_object:token_end].copy_(
+                        flat, non_blocking=True
+                    )
+                else:
+                    obj_device = objs_on_device[object_idx]
+                    src = obj_device[kv, layer_idx, offset_in_object:token_end]
+                    if is_hnd:
+                        # N=n_valid, BS=block_size:
+                        # [N*BS, NH*HS] -> [N, BS, NH, HS] -> [N, NH, BS, HS]
+                        src_blocks = src.reshape(n_valid, block_size, nh, hs).permute(
+                            0, 2, 1, 3
+                        )
+                    else:
+                        # N=n_valid, BS=block_size:
+                        # [N*BS, NH*HS] -> [N, BS, NH, HS]
+                        src_blocks = src.reshape(n_valid, block_size, nh, hs)
+                    paged_tensor[:, layer_idx, kv].index_copy_(0, eff_idx, src_blocks)
+
+
+def _transfer_sglang_mha(
+    paged_tensors: list[list[torch.Tensor]],
+    object_tensors: list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    n_block_ids: int,
+    blocks_per_object: int,
+    block_size: int,
+    engine_kv_format: EngineKVFormat,
+    is_d2h: bool,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """Handle SGLang MHA formats: 2*NL tensors (list[list[Tensor]])."""
+    # TWO_X_NL_X_NBBS_NH_HS: each tensor [NB*BS, NH, HS]
+    # TWO_X_NL_X_NB_BS_NH_HS: each tensor [NB, BS, NH, HS]
+    is_flat = int(engine_kv_format) == int(EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS)
+    num_layers = len(paged_tensors[0])
+
+    # Determine target device from first tensor
+    target_device = paged_tensors[0][0].device
+
+    # H2D: pre-transfer objects
+    if not is_d2h and object_tensors:
+        objs_on_device = [obj.to(target_device) for obj in object_tensors]
+    block_ids_dev = torch.as_tensor(block_ids, dtype=torch.long, device=target_device)
+
+    for object_idx, obj in enumerate(object_tensors):
+        valid = _valid_block_range_indices(
+            object_idx,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            skip_prefix_n_blocks,
+        )
+        if valid is None:
+            continue
+        idx_start, idx_end, offset_in_object = valid
+        n_valid = idx_end - idx_start
+        token_end = offset_in_object + n_valid * block_size
+        eff_idx = block_ids_dev[idx_start:idx_end]
+        if is_flat:
+            # Flat token positions for all valid blocks:
+            # block_id * block_size + token offset. Reused across layer/KV pairs.
+            token_indices = (
+                eff_idx[:, None] * block_size
+                + torch.arange(block_size, dtype=torch.long, device=target_device)
+            ).reshape(-1)
+
+        for layer_idx in range(num_layers):
+            for kv in range(2):
+                layer_t = paged_tensors[kv][layer_idx]
+                nh = layer_t.shape[-2]
+                hs = layer_t.shape[-1]
+
+                if is_d2h:
+                    if is_flat:
+                        # [NB*BS, NH, HS]
+                        gathered = layer_t.index_select(0, token_indices)
+                    else:
+                        # [NB, BS, NH, HS]
+                        gathered = layer_t.index_select(0, eff_idx).reshape(
+                            n_valid * block_size, nh, hs
+                        )
+                    flat = gathered.reshape(n_valid * block_size, nh * hs)
+                    obj[kv, layer_idx, offset_in_object:token_end].copy_(
+                        flat, non_blocking=True
+                    )
+                else:
+                    obj_device = objs_on_device[object_idx]
+                    src = obj_device[kv, layer_idx, offset_in_object:token_end]
+                    src_shaped = src.reshape(n_valid * block_size, nh, hs)
+                    if is_flat:
+                        # scatter into [NB*BS, NH, HS]
+                        layer_t.index_copy_(0, token_indices, src_shaped)
+                    else:
+                        # N=n_valid, BS=block_size:
+                        # [N*BS, NH, HS] -> [N, BS, NH, HS]
+                        src_blocks = src_shaped.reshape(n_valid, block_size, nh, hs)
+                        layer_t.index_copy_(0, eff_idx, src_blocks)
+
+
+def _transfer_per_layer_mla(
+    layer_tensors: list[torch.Tensor],
+    object_tensors: list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    n_block_ids: int,
+    blocks_per_object: int,
+    block_size: int,
+    engine_kv_format: EngineKVFormat,
+    is_d2h: bool,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """Handle MLA per-layer formats: [NB, BS, HS]."""
+    if not layer_tensors or not object_tensors:
+        return
+
+    is_flat = int(engine_kv_format) == int(EngineKVFormat.NL_X_NBBS_ONE_HS)
+    target_device = layer_tensors[0].device
+    if is_flat:
+        token_offsets = torch.arange(block_size, dtype=torch.long, device=target_device)
+    block_ids_dev = torch.as_tensor(block_ids, dtype=torch.long, device=target_device)
+
+    for object_idx, obj in enumerate(object_tensors):
+        valid = _valid_block_range_indices(
+            object_idx,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            skip_prefix_n_blocks,
+        )
+        if valid is None:
+            continue
+        idx_start, idx_end, offset_in_object = valid
+        n_valid = idx_end - idx_start
+        token_end = offset_in_object + n_valid * block_size
+        eff_idx = block_ids_dev[idx_start:idx_end]
+        if is_flat:
+            token_indices = (
+                eff_idx[:, None] * block_size + token_offsets[None, :]
+            ).reshape(-1)
+
+        if is_d2h:
+            hidden_size = layer_tensors[0].shape[-1]
+            chunk_gpu = torch.empty(
+                len(layer_tensors),
+                n_valid * block_size,
+                hidden_size,
+                dtype=layer_tensors[0].dtype,
+                device=target_device,
+            )
+            for layer_idx, layer in enumerate(layer_tensors):
+                if is_flat:
+                    dst = chunk_gpu[layer_idx].view(
+                        n_valid * block_size, 1, hidden_size
+                    )
+                    torch.index_select(layer, 0, token_indices, out=dst)
+                else:
+                    dst = chunk_gpu[layer_idx].view(n_valid, block_size, hidden_size)
+                    torch.index_select(layer, 0, eff_idx, out=dst)
+            obj[:, offset_in_object:token_end].copy_(chunk_gpu, non_blocking=True)
+        else:
+            chunk_gpu = obj[:, offset_in_object:token_end].to(
+                target_device, non_blocking=True
+            )
+            for layer_idx, layer in enumerate(layer_tensors):
+                src = chunk_gpu[layer_idx]
+                hidden_size = layer.shape[-1]
+                if is_flat:
+                    src_tokens = src.reshape(n_valid * block_size, 1, hidden_size)
+                    layer.index_copy_(0, token_indices, src_tokens)
+                else:
+                    src_blocks = src.reshape(n_valid, block_size, hidden_size)
+                    layer.index_copy_(0, eff_idx, src_blocks)
+
+
+def _transfer_per_layer_hnd(
+    layer_tensors: list[torch.Tensor],
+    object_tensors: list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    n_block_ids: int,
+    blocks_per_object: int,
+    block_size: int,
+    engine_kv_format: EngineKVFormat,
+    is_d2h: bool,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """Handle per-layer HND formats: heads before block tokens."""
+    if not layer_tensors or not object_tensors:
+        return
+
+    target_device = layer_tensors[0].device
+    block_ids_dev = torch.as_tensor(block_ids, dtype=torch.long, device=target_device)
+
+    first_layer = layer_tensors[0]
+    if int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS):
+        first_k = first_layer[0]
+    elif int(engine_kv_format) == int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS):
+        first_k = first_layer[:, :, :, 0]
+    else:
+        first_k = first_layer[:, 0]
+    _nb0, nh0, _bs0, hs0 = first_k.shape
+
+    for object_idx, obj in enumerate(object_tensors):
+        valid = _valid_block_range_indices(
+            object_idx,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            skip_prefix_n_blocks,
+        )
+        if valid is None:
+            continue
+        idx_start, idx_end, offset_in_object = valid
+        n_valid = idx_end - idx_start
+        token_end = offset_in_object + n_valid * block_size
+        eff_idx = block_ids_dev[idx_start:idx_end]
+
+        if is_d2h:
+            chunk_gpu = torch.empty(
+                2,
+                len(layer_tensors),
+                n_valid * block_size,
+                nh0 * hs0,
+                dtype=first_k.dtype,
+                device=target_device,
+            )
+            scratch = torch.empty(
+                n_valid,
+                nh0,
+                block_size,
+                hs0,
+                dtype=first_k.dtype,
+                device=target_device,
+            )
+            for layer_idx, layer in enumerate(layer_tensors):
+                if int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS):
+                    k_t, v_t = layer[0], layer[1]
+                    torch.index_select(k_t, 0, eff_idx, out=scratch)
+                    chunk_gpu[0, layer_idx].view(n_valid, block_size, nh0, hs0).copy_(
+                        scratch.permute(0, 2, 1, 3)
+                    )
+                    torch.index_select(v_t, 0, eff_idx, out=scratch)
+                    chunk_gpu[1, layer_idx].view(n_valid, block_size, nh0, hs0).copy_(
+                        scratch.permute(0, 2, 1, 3)
+                    )
+                elif int(engine_kv_format) == int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS):
+                    k_t, v_t = layer[:, :, :, 0], layer[:, :, :, 1]
+                    torch.index_select(k_t, 0, eff_idx, out=scratch)
+                    chunk_gpu[0, layer_idx].view(n_valid, block_size, nh0, hs0).copy_(
+                        scratch.permute(0, 2, 1, 3)
+                    )
+                    torch.index_select(v_t, 0, eff_idx, out=scratch)
+                    chunk_gpu[1, layer_idx].view(n_valid, block_size, nh0, hs0).copy_(
+                        scratch.permute(0, 2, 1, 3)
+                    )
+                else:
+                    # FlashInfer HND stores KV as [NB, 2, NH, BS, HS].
+                    # Gather on dim=0 first so reads stay contiguous in memory;
+                    # index_select on layer[:, 0]/layer[:, 1] non-contiguous views
+                    # triggers slower element-wise gather reads.
+                    selected = layer.index_select(0, eff_idx)
+                    chunk_gpu[0, layer_idx].view(n_valid, block_size, nh0, hs0).copy_(
+                        selected[:, 0].permute(0, 2, 1, 3)
+                    )
+                    chunk_gpu[1, layer_idx].view(n_valid, block_size, nh0, hs0).copy_(
+                        selected[:, 1].permute(0, 2, 1, 3)
+                    )
+            obj[:, :, offset_in_object:token_end].copy_(chunk_gpu, non_blocking=True)
+        else:
+            chunk_gpu = obj[:, :, offset_in_object:token_end].to(
+                target_device, non_blocking=True
+            )
+            for layer_idx, layer in enumerate(layer_tensors):
+                if int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_NH_BS_HS):
+                    k_t, v_t = layer[0], layer[1]
+                elif int(engine_kv_format) == int(EngineKVFormat.NL_X_NB_NH_BS_TWO_HS):
+                    k_t, v_t = layer[:, :, :, 0], layer[:, :, :, 1]
+                else:
+                    k_t, v_t = layer[:, 0], layer[:, 1]
+                _nb, nh, _bs, hs = k_t.shape
+                k_blocks = (
+                    chunk_gpu[0, layer_idx]
+                    .reshape(n_valid, block_size, nh, hs)
+                    .permute(0, 2, 1, 3)
+                )
+                v_blocks = (
+                    chunk_gpu[1, layer_idx]
+                    .reshape(n_valid, block_size, nh, hs)
+                    .permute(0, 2, 1, 3)
+                )
+                if int(engine_kv_format) == int(EngineKVFormat.NL_X_NB_TWO_NH_BS_HS):
+                    layer.index_copy_(
+                        0, eff_idx, torch.stack([k_blocks, v_blocks], dim=1)
+                    )
+                else:
+                    k_t.index_copy_(0, eff_idx, k_blocks)
+                    v_t.index_copy_(0, eff_idx, v_blocks)
+
+
+def _transfer_per_layer_nhd(
+    layer_tensors: list[torch.Tensor],
+    object_tensors: list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    n_block_ids: int,
+    blocks_per_object: int,
+    block_size: int,
+    engine_kv_format: EngineKVFormat,
+    is_d2h: bool,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """Handle per-layer NHD formats: block tokens before heads."""
+    if not layer_tensors or not object_tensors:
+        return
+
+    target_device = layer_tensors[0].device
+    block_ids_dev = torch.as_tensor(block_ids, dtype=torch.long, device=target_device)
+
+    first_layer = layer_tensors[0]
+    if int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_BS_NH_HS):
+        first_k = first_layer[0]
+    else:
+        first_k = first_layer[:, 0]
+    _nb0, _bs0, nh0, hs0 = first_k.shape
+
+    for object_idx, obj in enumerate(object_tensors):
+        valid = _valid_block_range_indices(
+            object_idx,
+            n_block_ids,
+            blocks_per_object,
+            block_size,
+            skip_prefix_n_blocks,
+        )
+        if valid is None:
+            continue
+        idx_start, idx_end, offset_in_object = valid
+        n_valid = idx_end - idx_start
+        token_end = offset_in_object + n_valid * block_size
+        eff_idx = block_ids_dev[idx_start:idx_end]
+
+        if is_d2h:
+            chunk_gpu = torch.empty(
+                2,
+                len(layer_tensors),
+                n_valid * block_size,
+                nh0 * hs0,
+                dtype=first_k.dtype,
+                device=target_device,
+            )
+            for layer_idx, layer in enumerate(layer_tensors):
+                if int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_BS_NH_HS):
+                    k_t, v_t = layer[0], layer[1]
+                    torch.index_select(
+                        k_t,
+                        0,
+                        eff_idx,
+                        out=chunk_gpu[0, layer_idx].view(n_valid, block_size, nh0, hs0),
+                    )
+                    torch.index_select(
+                        v_t,
+                        0,
+                        eff_idx,
+                        out=chunk_gpu[1, layer_idx].view(n_valid, block_size, nh0, hs0),
+                    )
+                else:
+                    # FlashInfer NHD stores KV as [NB, 2, BS, NH, HS].
+                    # Gather on dim=0 first to avoid index_select from
+                    # non-contiguous layer[:, 0]/layer[:, 1] views, which
+                    # trigger slower element-wise gather reads.
+                    selected = layer.index_select(0, eff_idx)
+                    chunk_gpu[0, layer_idx].copy_(
+                        selected[:, 0].reshape(n_valid * block_size, nh0 * hs0)
+                    )
+                    chunk_gpu[1, layer_idx].copy_(
+                        selected[:, 1].reshape(n_valid * block_size, nh0 * hs0)
+                    )
+            obj[:, :, offset_in_object:token_end].copy_(chunk_gpu, non_blocking=True)
+        else:
+            chunk_gpu = obj[:, :, offset_in_object:token_end].to(
+                target_device, non_blocking=True
+            )
+            for layer_idx, layer in enumerate(layer_tensors):
+                if int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_BS_NH_HS):
+                    k_t, v_t = layer[0], layer[1]
+                    k_t.index_copy_(
+                        0,
+                        eff_idx,
+                        chunk_gpu[0, layer_idx].reshape(n_valid, block_size, nh0, hs0),
+                    )
+                    v_t.index_copy_(
+                        0,
+                        eff_idx,
+                        chunk_gpu[1, layer_idx].reshape(n_valid, block_size, nh0, hs0),
+                    )
+                else:
+                    k_blocks = chunk_gpu[0, layer_idx].reshape(
+                        n_valid, block_size, nh0, hs0
+                    )
+                    v_blocks = chunk_gpu[1, layer_idx].reshape(
+                        n_valid, block_size, nh0, hs0
+                    )
+                    layer.index_copy_(
+                        0, eff_idx, torch.stack([k_blocks, v_blocks], dim=1)
+                    )
+
+
+def single_layer_kv_transfer(
+    lmc_key_value_cache: torch.Tensor,
+    vllm_key_value_cache: torch.Tensor,
+    slot_mapping: torch.Tensor,
+    direction: TransferDirection,
+    engine_kv_format: EngineKVFormat,
+    token_major: bool = False,
+):
+    """
+    Vectorized Python fallback for single_layer_kv_transfer
+    (eliminates per-token loops).
+
+    Transfers KV data between LMCache buffer
+    and a single vLLM paged KV cache layer.
+
+    lmc_key_value_cache layout:
+        - MLA:                    [num_tokens, aligned_head_size]
+        - token_major=True:       [num_tokens, 2, num_heads * head_size]
+        - token_major=False:      [2, num_tokens, num_heads * head_size]
+
+    vllm_key_value_cache layout:
+        - NL_X_TWO_NB_BS_NH_HS (flash attn):
+            [2, num_blocks, block_size, num_heads, head_size]
+        - NL_X_NB_TWO_BS_NH_HS (flash infer):
+            [num_blocks, 2, block_size, num_heads, head_size]
+        - NL_X_NB_BS_HS (vLLM MLA):
+            [num_blocks, block_size, head_size]
+
+    direction:
+        H2D = LMCache  -> vLLM GPU
+        D2H = vLLM GPU -> LMCache
+    """
+    kv_device = lmc_key_value_cache.device
+    paged_memory_device = vllm_key_value_cache.device
+    slots_kv = slot_mapping.to(dtype=torch.long).to(kv_device)
+    valid_mask_kv = slots_kv >= 0
+
+    if not valid_mask_kv.any():
+        return
+
+    valid_token_indices = torch.nonzero(valid_mask_kv, as_tuple=True)[0]
+    valid_slots = slots_kv[valid_mask_kv].to(paged_memory_device)
+
+    is_mla = int(engine_kv_format) in (
+        int(EngineKVFormat.NL_X_NB_BS_HS),
+        int(EngineKVFormat.NL_X_NBBS_ONE_HS),
+    )
+
+    if is_mla:
+        # ── MLA format ──
+        # vllm: [num_blocks, block_size, head_size]
+        # lmc:  [num_tokens, aligned_head_size]
+        block_size = vllm_key_value_cache.size(1)
+        block_indices = valid_slots // block_size
+        block_offsets = valid_slots % block_size
+
+        if int(direction) == int(TransferDirection.D2H):
+            # vLLM -> LMCache
+            lmc_key_value_cache[valid_token_indices] = vllm_key_value_cache[
+                block_indices, block_offsets
+            ].to(lmc_key_value_cache.device)
+        else:
+            # LMCache -> vLLM
+            vllm_key_value_cache[block_indices, block_offsets] = lmc_key_value_cache[
+                valid_token_indices
+            ].to(paged_memory_device)
+
+    else:
+        # ── Non-MLA format ──
+        # Determine vLLM layout and block_size
+        is_two_major = int(engine_kv_format) == int(EngineKVFormat.NL_X_TWO_NB_BS_NH_HS)
+        # flash attn:
+        #   [2, num_blocks, block_size, num_heads, head_size]
+        #   -> dim2 = block_size
+        # flash infer:
+        #   [num_blocks, 2, block_size, num_heads, head_size]
+        #   -> dim2 = block_size
+        block_size = vllm_key_value_cache.size(2)
+        num_heads = vllm_key_value_cache.size(3)
+        head_size = vllm_key_value_cache.size(4)
+        block_indices = valid_slots // block_size
+        block_offsets = valid_slots % block_size
+
+        for kv in range(2):
+            if int(direction) == int(TransferDirection.D2H):
+                if is_two_major:
+                    gathered = vllm_key_value_cache[kv, block_indices, block_offsets]
+                else:
+                    gathered = vllm_key_value_cache[block_indices, kv, block_offsets]
+
+                gathered_flat = gathered.reshape(-1, num_heads * head_size).to(
+                    lmc_key_value_cache.device
+                )
+                if token_major:
+                    lmc_key_value_cache[valid_token_indices, kv] = gathered_flat
+                else:
+                    lmc_key_value_cache[kv, valid_token_indices] = gathered_flat
+            else:
+                if token_major:
+                    lmc_src = lmc_key_value_cache[valid_token_indices, kv]
+                else:
+                    lmc_src = lmc_key_value_cache[kv, valid_token_indices]
+                lmc_reshaped = lmc_src.reshape(-1, num_heads, head_size).to(
+                    vllm_key_value_cache.device
+                )
+
+                if is_two_major:
+                    vllm_key_value_cache[kv, block_indices, block_offsets] = (
+                        lmc_reshaped
+                    )
+                else:
+                    vllm_key_value_cache[block_indices, kv, block_offsets] = (
+                        lmc_reshaped
+                    )
+
+
+def single_layer_kv_transfer_sgl(
+    lmc_key_value_cache: torch.Tensor,
+    sgl_key_cache: torch.Tensor,
+    sgl_value_cache: torch.Tensor,
+    slot_mapping: torch.Tensor,
+    direction: TransferDirection,
+    token_major: bool = False,
+):
+    """
+    Python fallback implementation of single_layer_kv_transfer_sgl.
+
+    Args:
+        lmc_key_value_cache:
+            [num_tokens, 2, num_heads*head_size] or
+            [2, num_tokens, num_heads*head_size]
+        sgl_key_cache: [num_blocks, block_size, num_heads, head_size]
+        sgl_value_cache: [num_blocks, block_size, num_heads, head_size]
+        slot_mapping: [num_tokens] - maps each token to a global slot index
+        direction: False for LMCache -> SGLang, True for SGLang -> LMCache
+        token_major: Boolean to determine the layout of lmc_key_value_cache
+    """
+    kv_device = lmc_key_value_cache.device
+    paged_memory_device = sgl_key_cache.device
+    slots_kv = slot_mapping.to(dtype=torch.long).to(kv_device)
+    valid_mask_kv = slots_kv >= 0
+    if not valid_mask_kv.any():
+        return
+
+    # 1. Get basic dimensions
+    block_size = sgl_key_cache.size(1)
+    num_heads = sgl_key_cache.size(2)
+    head_size = sgl_key_cache.size(3)
+
+    # 2. Calculate block indices and offsets within the blocks from slot_mapping
+    # In SGLang/vLLM, slot_idx = block_idx * block_size + block_offset
+    valid_slots = slots_kv[valid_mask_kv].to(paged_memory_device)
+    block_indices = valid_slots // block_size
+    block_offsets = valid_slots % block_size
+
+    # 3. Prepare LMCache views for K and V
+    if token_major:
+        # Layout: [num_tokens, 2, hidden_size]
+        lmc_k = lmc_key_value_cache[:, 0, :]
+        lmc_v = lmc_key_value_cache[:, 1, :]
+    else:
+        # Layout: [2, num_tokens, hidden_size]
+        lmc_k = lmc_key_value_cache[0, :, :]
+        lmc_v = lmc_key_value_cache[1, :, :]
+
+    # 4. Perform the transfer
+    if int(direction) == int(TransferDirection.H2D):
+        # --- Direction: LMCache to SGLang (Paged Buffer) ---
+        # Reshape LMC flat tensors to match SGL [num_heads, head_size]
+        src_k_reshaped = (
+            lmc_k[valid_mask_kv]
+            .reshape(-1, num_heads, head_size)
+            .to(paged_memory_device)
+        )
+        src_v_reshaped = (
+            lmc_v[valid_mask_kv]
+            .reshape(-1, num_heads, head_size)
+            .to(paged_memory_device)
+        )
+
+        # Advanced indexing: update specific slots in the paged cache
+        sgl_key_cache[block_indices, block_offsets] = src_k_reshaped
+        sgl_value_cache[block_indices, block_offsets] = src_v_reshaped
+
+    else:
+        # --- Direction: SGLang (Paged Buffer) to LMCache ---
+        # Gather tensors from paged cache based on mapping
+        sampled_k = sgl_key_cache[block_indices, block_offsets].to(kv_device)
+        sampled_v = sgl_value_cache[block_indices, block_offsets].to(kv_device)
+
+        # Flatten the head dimensions and copy into LMC tensors
+        lmc_k[valid_mask_kv] = sampled_k.reshape(-1, num_heads * head_size)
+        lmc_v[valid_mask_kv] = sampled_v.reshape(-1, num_heads * head_size)
+
+
+def load_and_reshape_flash(
+    key_value: torch.Tensor,
+    # Destination (Dst): Pinned CPU Tensor [2, L, T, H]
+    key_cache: torch.Tensor,
+    # Source (Src): GPU Cache [Blocks, BlockSize, NumHeads, HeadSize]
+    value_cache: torch.Tensor,  # Source (Src): GPU Cache
+    slot_mapping: torch.Tensor,  # Mapping indices [num_tokens]
+    layer_idx: int,
+):
+    """
+    Python equivalent of load_and_reshape_flash.
+    Note: In the context of 'test_extract_and_load_back', this function performs
+    an EXTRACT operation (Reads from GPU Cache and writes to Pinned CPU memory).
+    """
+    # 1. Prepare indices on the target device
+    # Mapping must be on the same GPU as the cache to perform indexing
+    device = key_cache.device
+    slot_mapping = slot_mapping.to(device=device, dtype=torch.long)
+
+    block_size = key_cache.size(1)
+
+    # Calculate physical locations within the paged cache
+    block_indices = torch.div(slot_mapping, block_size, rounding_mode="floor")
+    block_offsets = slot_mapping % block_size
+
+    # 2. Extract data from Cache (Gather operation)
+    # The result k_out/v_out will be on the GPU
+    # Shape: [num_tokens, num_heads, head_size]
+    k_out = key_cache[block_indices, block_offsets]
+    v_out = value_cache[block_indices, block_offsets]
+
+    # 3. Write to the destination tensor (CPU Copy)
+    # Target shape: [2, num_layers, num_tokens, hidden_dim]
+
+    # Flatten heads into the hidden dimension: [T, NumHeads, HeadSize] -> [T, HiddenDim]
+    hidden_dim = k_out.shape[1] * k_out.shape[2]
+
+    # Assignment automatically handles the Device-to-Host (D2H) transfer
+    key_value[0, layer_idx] = k_out.view(-1, hidden_dim)
+    key_value[1, layer_idx] = v_out.view(-1, hidden_dim)
+
+
+def reshape_and_cache_back_flash(
+    key_value: torch.Tensor,
+    # Source: [2, num_layer, num_tokens, num_heads * head_size]
+    # (Can be on CPU/Pinned Memory or GPU)
+    key_cache: torch.Tensor,
+    # Destination: [num_blocks, block_size, num_heads, head_size]
+    # (Must be on GPU)
+    value_cache: torch.Tensor,  # Destination: (Must be on GPU)
+    slot_mapping: torch.Tensor,  # Indices: [num_tokens]
+    layer_idx: int,
+):
+    """
+    Python implementation of reshape_and_cache_back_flash.
+
+    Operation:
+        Flat Tensor (Source) -> Paged Attention Cache (Destination)
+
+    Logic:
+        1. Extract the specific layer's data from key_value.
+        2. Move it to the GPU (if it's on CPU).
+        3. Reshape it to match the cache's head structure.
+        4. Scatter (write) it into the non-contiguous cache blocks using slot_mapping.
+    """
+
+    # 1. Setup Device & Dimensions
+    # The cache is on the GPU, so all indices and source data must eventually be there.
+    device = key_cache.device
+
+    block_size = key_cache.size(1)
+    num_heads = key_cache.size(2)
+    head_size = key_cache.size(3)
+
+    # 2. Prepare Indices
+    # slot_mapping might be on CPU, must move to GPU for indexing.
+    slot_mapping = slot_mapping.to(device=device, dtype=torch.long)
+
+    # Calculate physical block indices and offsets
+    block_indices = torch.div(slot_mapping, block_size, rounding_mode="floor")
+    block_offsets = slot_mapping % block_size
+
+    # 3. Process Source Data (Key)
+    # Step A: Slice the specific layer from the source tensor
+    # Source shape: [2, num_layers, num_tokens, hidden_dim] -> [num_tokens, hidden_dim]
+    k_src_flat = key_value[0, layer_idx]
+    v_src_flat = key_value[1, layer_idx]
+
+    # Step B: Reshape & Move to GPU
+    # .to(device) handles the CPU -> GPU transfer if key_value is in pinned memory.
+    # View shape: [num_tokens, num_heads, head_size]
+    k_src = k_src_flat.to(device).view(-1, num_heads, head_size)
+    v_src = v_src_flat.to(device).view(-1, num_heads, head_size)
+
+    # 4. Write to Cache (Scatter)
+    # Using Advanced Indexing to write data into specific blocks/offsets
+    key_cache[block_indices, block_offsets] = k_src
+    value_cache[block_indices, block_offsets] = v_src
+
+
+def lmcache_memcpy_async(
+    dest: int | torch.Tensor,
+    src: int | torch.Tensor,
+    nbytes: int,
+    direction: TransferDirection,
+    host_buffer_offset: int,
+    host_buffer_alignments: int,
+):
+    """
+    Python fallback for lmcache_memcpy_async.
+
+    - Tensor mode (non-CUDA devices like HPU): uses .to(device) + copy_()
+    - Pointer mode with libcudart: uses synchronous cudaMemcpy (cudaMemcpyDefault)
+    - Pointer mode without libcudart: uses CPU tensor copy
+
+    Unlike the C++ version (which uses cudaMemcpyAsync and must split copies
+    at cudaHostRegister boundaries), this Python fallback does NOT need
+    alignment-based chunking because:
+    - cudaMemcpy (synchronous) handles cross-cudaHostRegister boundaries
+      internally via staging buffers
+    - CPU tensor copy has no alignment constraints
+    - Tensor mode bypasses raw pointers entirely
+
+    dest:
+        - If int: raw memory pointer (used for CUDA/CPU devices where we
+          work with pointers).
+        - If torch.Tensor: tensor object (used for non-CUDA/CPU devices
+          where we operate on tensor objects directly).
+
+    src:
+        - If int: raw memory pointer (used for CUDA/CPU devices where we
+          work with pointers).
+        - If torch.Tensor: tensor object (used for non-CUDA/CPU devices
+          where we operate on tensor objects directly).
+    """
+    # 1. Power of two check (kept for API compatibility)
+    if host_buffer_alignments <= 0 or (
+        host_buffer_alignments & (host_buffer_alignments - 1) != 0
+    ):
+        raise ValueError("host_buffer_alignments must be power of two")
+
+    # 2. Validate direction
+    if int(direction) not in (int(TransferDirection.H2D), int(TransferDirection.D2H)):
+        raise ValueError(f"Unsupported direction: {direction}")
+
+    # 3. Tensor-backed mode.
+    # Mixed pointer/tensor are not allowed
+    if isinstance(dest, torch.Tensor) or isinstance(src, torch.Tensor):
+        if not (isinstance(dest, torch.Tensor) and isinstance(src, torch.Tensor)):
+            raise TypeError(
+                "Mixed types are not allowed: both dest and src must be torch.Tensor "
+                "if either of them is a tensor."
+            )
+        if nbytes % dest.element_size() != 0:
+            raise ValueError("nbytes must align with tensor element size")
+
+        num_elements = nbytes // dest.element_size()
+
+        dest_slice = dest.flatten()[:num_elements]
+        src_slice = src.flatten()[:num_elements]
+
+        copied = src_slice.to(dest_slice.device)
+        dest_slice.copy_(copied)
+        return
+
+    # 4. Pointer mode
+    if not isinstance(dest, int) or not isinstance(src, int):
+        raise TypeError(
+            "dest and src must be both int (pointer mode) "
+            "or both torch.Tensor (tensor mode)"
+        )
+
+    libcudart = _get_copy_lib()
+    if libcudart is not None and hasattr(libcudart, "cudaMemcpy"):
+        try:
+            # Synchronous cudaMemcpy handles cross-cudaHostRegister boundaries
+            # internally — no manual alignment splitting needed.
+            ret = libcudart.cudaMemcpy(
+                ctypes.c_void_p(dest),
+                ctypes.c_void_p(src),
+                ctypes.c_size_t(nbytes),
+                ctypes.c_int(4),  # cudaMemcpyDefault
+            )
+            if ret != 0:
+                raise RuntimeError(f"cudaMemcpy failed with error code {ret}")
+        except AttributeError:
+            raise
+    else:
+        # Pure CPU copy — no alignment constraints.
+        _copy_bytes_with_tensor(dest, src, nbytes)
+
+
+@njit(cache=True)
+def _encode_single_channel(
+    cdf_layer_c,  # np.uint32 [lp]
+    sym_channel,  # np.uint8 [n_tokens]
+    out_buf_lc,  # np.uint8 [buffer_size]
+):
+    """Core arithmetic encoding for a single (layer, channel).
+    Returns number of bytes written."""
+    MASK32 = 0xFFFFFFFF
+    precision = 16
+    max_symbol = len(cdf_layer_c) - 2
+    n_tokens = len(sym_channel)
+
+    low, high = 0, MASK32
+    pending_bits = 0
+    output_reg, output_reg_len = 0, 0
+    ptr = 0
+    buf_size = len(out_buf_lc)
+
+    # Inline flush_bit to avoid closure (numba does not support nonlocal)
+    for token_idx in range(n_tokens):
+        sym = int(sym_channel[token_idx])
+        c_low = int(cdf_layer_c[sym])
+        c_high = 0x10000 if sym == max_symbol else int(cdf_layer_c[sym + 1])
+
+        span = (high - low + 1) & MASK32
+        if span == 0:
+            span = 0x100000000
+
+        high = (low + ((span * c_high) >> precision) - 1) & MASK32
+        low = (low + ((span * c_low) >> precision)) & MASK32
+
+        while True:
+            if (high & 0x80000000) == (low & 0x80000000):
+                # flush_bit(bit)
+                bit = (high >> 31) & 1
+                output_reg = (output_reg << 1) | bit
+                output_reg_len += 1
+                if output_reg_len == 8:
+                    if ptr < buf_size:
+                        out_buf_lc[ptr] = output_reg & 0xFF
+                        ptr += 1
+                    output_reg, output_reg_len = 0, 0
+                # flush pending bits
+                for _ in range(pending_bits):
+                    output_reg = (output_reg << 1) | (1 - bit)
+                    output_reg_len += 1
+                    if output_reg_len == 8:
+                        if ptr < buf_size:
+                            out_buf_lc[ptr] = output_reg & 0xFF
+                            ptr += 1
+                        output_reg, output_reg_len = 0, 0
+                pending_bits = 0
+                low = (low << 1) & MASK32
+                high = ((high << 1) | 1) & MASK32
+            elif (low & 0x40000000) != 0 and (high & 0x40000000) == 0:
+                pending_bits += 1
+                low = (low << 1) & 0x7FFFFFFF
+                high = ((high << 1) | 0x80000001) & MASK32
+            else:
+                break
+
+    # Final flushing sequence
+    pending_bits += 1
+    bit = 1 if (low & 0x40000000) != 0 else 0
+    output_reg = (output_reg << 1) | bit
+    output_reg_len += 1
+    if output_reg_len == 8:
+        if ptr < buf_size:
+            out_buf_lc[ptr] = output_reg & 0xFF
+            ptr += 1
+        output_reg, output_reg_len = 0, 0
+    for _ in range(pending_bits):
+        output_reg = (output_reg << 1) | (1 - bit)
+        output_reg_len += 1
+        if output_reg_len == 8:
+            if ptr < buf_size:
+                out_buf_lc[ptr] = output_reg & 0xFF
+                ptr += 1
+            output_reg, output_reg_len = 0, 0
+    pending_bits = 0  # noqa: F841
+
+    if output_reg_len > 0:
+        if ptr < buf_size:
+            out_buf_lc[ptr] = (output_reg << (8 - output_reg_len)) & 0xFF
+            ptr += 1
+
+    return ptr
+
+
+def encode_fast_new(cdf, input_sym, output_buffer, output_lengths):
+    """
+    Python equivalent of C++ Arithmetic Encoder.
+    Strictly emulates 32-bit unsigned overflow for high/low.
+    """
+    cdf_np = cdf.cpu().numpy().view(np.uint16).astype(np.uint32)
+    sym_np = input_sym.cpu().numpy().astype(np.uint8)
+
+    n_layers, n_tokens, n_channels = sym_np.shape
+    out_buf_np = np.zeros(output_buffer.shape, dtype=np.uint8)
+    out_len_np = np.zeros(output_lengths.shape, dtype=np.int32)
+
+    def encode_one(args):
+        layer_idx, c = args
+        length = _encode_single_channel(
+            cdf_np[layer_idx, c],
+            sym_np[layer_idx, :, c],
+            out_buf_np[layer_idx, c],
+        )
+        out_len_np[layer_idx, c] = length
+
+    tasks = [(layer_idx, c) for layer_idx in range(n_layers) for c in range(n_channels)]
+
+    with ThreadPoolExecutor() as executor:
+        list(executor.map(encode_one, tasks))
+
+    output_buffer.copy_(torch.from_numpy(out_buf_np))
+    output_lengths.copy_(torch.from_numpy(out_len_np))
+
+
+@njit(cache=True)
+def _decode_single_channel(
+    cdf_layer_c,
+    bs_np,
+    start_off,
+    end_off,
+    n_tokens,
+    out_layer_c,
+):
+    MASK32 = 0xFFFFFFFF
+    precision = 16
+    max_symbol = len(cdf_layer_c) - 2
+
+    v_val = 0
+    if start_off + 4 <= len(bs_np):
+        v_val = (
+            (int(bs_np[start_off]) << 24)
+            | (int(bs_np[start_off + 1]) << 16)
+            | (int(bs_np[start_off + 2]) << 8)
+            | int(bs_np[start_off + 3])
+        ) & MASK32
+
+    low, high = 0, MASK32
+    byte_buffer_offset = start_off + 4
+    bit_idx = 1
+    byte_buffer = int(bs_np[byte_buffer_offset]) if byte_buffer_offset < end_off else 0
+
+    for i in range(n_tokens):
+        span = (high - low + 1) & MASK32
+        if span == 0:
+            span = 0x100000000
+
+        v_minus_l = (v_val - low) & MASK32
+        count = ((v_minus_l + 1) * 0x10000 - 1) // span
+        count = count & 0xFFFF
+
+        left = 0
+        right = max_symbol + 1
+        while left + 1 < right:
+            m = (left + right) // 2
+            if int(cdf_layer_c[m]) < count:
+                left = m
+            elif int(cdf_layer_c[m]) > count:
+                right = m
+            else:
+                left = m
+                break
+
+        out_layer_c[i] = left
+
+        if i == n_tokens - 1:
+            break
+
+        sym_i = left
+        c_low = int(cdf_layer_c[sym_i])
+        c_high = 0x10000 if sym_i == max_symbol else int(cdf_layer_c[sym_i + 1])
+
+        high = (low + ((span * c_high) >> precision) - 1) & MASK32
+        low = (low + ((span * c_low) >> precision)) & MASK32
+
+        while True:
+            if low >= 0x80000000 or high < 0x80000000:
+                v_val = ((v_val << 1) | ((byte_buffer >> (8 - bit_idx)) & 1)) & MASK32
+                low = (low << 1) & MASK32
+                high = ((high << 1) | 1) & MASK32
+                bit_idx += 1
+            elif low >= 0x40000000 and high < 0xC0000000:
+                v_val = (v_val - 0x40000000) & MASK32
+                v_val = ((v_val << 1) | ((byte_buffer >> (8 - bit_idx)) & 1)) & MASK32
+                low = (low << 1) & 0x7FFFFFFF
+                high = ((high << 1) | 0x80000001) & MASK32
+                bit_idx += 1
+            else:
+                break
+
+            if bit_idx == 9:
+                bit_idx = 1
+                byte_buffer_offset += 1
+                byte_buffer = (
+                    int(bs_np[byte_buffer_offset])
+                    if byte_buffer_offset < end_off
+                    else 0
+                )
+
+
+# Standard
+
+
+def decode_fast_new(cdf, bytestreams, lengths, output):
+    """
+    Python implementation of Arithmetic Decoding.
+    Strictly aligned with CUDA decode_with_accessor_kernel.
+    bytestreams shape: [nlayers, nchannels, buffer_size]
+    """
+    cdf_np = cdf.cpu().numpy().view(np.uint16).astype(np.uint32)
+    bs_np = bytestreams.cpu().numpy().astype(np.uint8)
+    len_np = lengths.cpu().numpy().astype(np.int32)
+
+    n_layers, n_tokens, n_channels = output.shape
+    out_np = np.zeros(output.shape, dtype=np.uint8)
+
+    def decode_one(args):
+        layer_idx, c = args
+        curr_len = int(len_np[layer_idx, c])
+        # For decode_fast_new, each channel has its own contiguous buffer,
+        # so start_off=0 and end_off=curr_len within channel_bs
+        channel_bs = bs_np[layer_idx, c]  # shape [buffer_size]
+        _decode_single_channel(
+            cdf_np[layer_idx, c],
+            channel_bs,
+            0,
+            curr_len,
+            n_tokens,
+            out_np[layer_idx, :, c],
+        )
+
+    tasks = [(layer_idx, c) for layer_idx in range(n_layers) for c in range(n_channels)]
+
+    with ThreadPoolExecutor() as executor:
+        list(executor.map(decode_one, tasks))
+
+    if output is not None:
+        output.copy_(torch.from_numpy(out_np))
+
+
+def decode_fast_prefsum(cdf, bytestreams, lengths_prefsum, output):
+    """
+    Python equivalent of C++ decode_fast_prefsum.
+    bytestreams shape: [total_bytes] (1D, all channels packed)
+    """
+    cdf_np = cdf.cpu().numpy().view(np.uint16).astype(np.uint32)
+    pref_np = lengths_prefsum.cpu().numpy().astype(np.int64).flatten()
+
+    # WA: CUDA kernel reads out-of-bound in two ways:
+    # 1. max(prefsum) may equal len(bytestreams) (off-by-one on exclusive-end)
+    # 2. v_val init reads 4 bytes starting at start_off, may exceed bytestreams
+    # Pad with zeros to make all reads safe.
+    max_prefsum = int(pref_np.max())
+    pad_size = max(0, max_prefsum + 4 - bytestreams.shape[0])
+    if pad_size > 0:
+        bytestreams = torch.nn.functional.pad(bytestreams, (0, pad_size), value=0)
+
+    bs_np = bytestreams.cpu().numpy().astype(np.uint8)  # must be after padding
+
+    n_layers, n_tokens, n_channels = output.shape
+    out_np = np.zeros(output.shape, dtype=np.uint8)
+
+    def decode_one(args):
+        layer_idx, c = args
+        cid = layer_idx * n_channels + c
+        start_off = 0 if cid == 0 else int(pref_np[cid - 1])
+        end_off = int(pref_np[cid])
+        _decode_single_channel(
+            cdf_np[layer_idx, c],
+            bs_np,
+            start_off,
+            end_off,
+            n_tokens,
+            out_np[layer_idx, :, c],
+        )
+
+    tasks = [(layer_idx, c) for layer_idx in range(n_layers) for c in range(n_channels)]
+
+    with ThreadPoolExecutor() as executor:
+        list(executor.map(decode_one, tasks))
+
+    output.copy_(torch.from_numpy(out_np))
+
+
+def calculate_cdf(input_tensor: torch.Tensor, num_bins: int) -> torch.Tensor:
+    """Equivalent to CUDA calculate_cdf.
+
+    Calculates the CDF across tokens for each (layer, channel) pair.
+
+    Args:
+        input_tensor: 3D tensor with shape [nlayers, ntokens, nchannels].
+        num_bins: Maximum number of bins (i.e., Lp - 1).
+
+    Returns:
+        int16 tensor with shape [nlayers, nchannels, num_bins + 1]
+        containing normalized CDF values.
+    """
+    nlayers, ntokens, nchannels = input_tensor.shape
+    device = input_tensor.device
+
+    # Compute per-(layer, channel) histogram via scatter_add.
+    # Permute to [nlayers, nchannels, ntokens] then flatten first two dims.
+    input_perm = input_tensor.permute(0, 2, 1).reshape(-1, ntokens).long()
+    src = torch.ones_like(input_perm)
+    counts = torch.zeros(nlayers * nchannels, num_bins, dtype=torch.long, device=device)
+    counts.scatter_add_(1, input_perm.clamp(0, num_bins - 1), src)
+    counts = counts.reshape(nlayers, nchannels, num_bins)
+
+    # Build CDF: cdf[..., 0] = 0, cdf[..., i] = sum(counts[..., 0:i])
+    cdf = torch.zeros(nlayers, nchannels, num_bins + 1, dtype=torch.long, device=device)
+    cdf[:, :, 1:] = torch.cumsum(counts, dim=2)
+
+    # Total count per (layer, channel)
+    total = cdf[:, :, -1:]  # [nlayers, nchannels, 1]
+
+    # Normalize: (0xFFFF - num_bins) * cdf / total + bin_index
+    max_uint16_value = 0xFFFF - num_bins
+    bin_offsets = torch.arange(num_bins + 1, dtype=torch.long, device=device)
+
+    safe_total = total.clamp(min=1)
+    normalized = (max_uint16_value * cdf) // safe_total + bin_offsets
+
+    # Where total is 0, use just the bin offsets
+    normalized = torch.where(
+        total > 0, normalized, bin_offsets.unsqueeze(0).unsqueeze(0)
+    )
+
+    return normalized.to(torch.int16)
+
+
+def rotary_embedding_k_fused(
+    old_positions: torch.Tensor,
+    new_positions: torch.Tensor,
+    key: torch.Tensor,
+    head_size: int,
+    cos_sin_cache: torch.Tensor,
+    is_neox: bool,
+) -> None:
+    """Apply fused rotary embedding undo/redo to key tensor in-place.
+
+    Reverses the rotary embedding at old_positions and applies the rotary
+    embedding at new_positions. head_size is unused but kept for API
+    compatibility with the CUDA equivalent.
+
+    Args:
+        old_positions: Token positions whose rotary embedding to reverse.
+        new_positions: Token positions whose rotary embedding to apply.
+        key: Key tensor to update in-place.
+        head_size: Head size (unused; kept for API compatibility).
+        cos_sin_cache: Precomputed cosine/sine cache indexed by position.
+        is_neox: If True, uses NeoX-style rotary (contiguous halves);
+            otherwise uses GPT-J-style (interleaved).
+    """
+    rot_dim = cos_sin_cache.shape[1]
+    half_rot = rot_dim // 2
+
+    old_cs = cos_sin_cache[old_positions]
+    new_cs = cos_sin_cache[new_positions]
+
+    oc, os = old_cs[:, :half_rot].unsqueeze(1), old_cs[:, half_rot:].unsqueeze(1)
+    nc, ns = new_cs[:, :half_rot].unsqueeze(1), new_cs[:, half_rot:].unsqueeze(1)
+
+    if is_neox:
+        x = key[..., :half_rot]
+        y = key[..., half_rot:rot_dim]
+    else:
+        x = key[..., :rot_dim:2]
+        y = key[..., 1:rot_dim:2]
+
+    x_rev = x * oc + y * os
+    y_rev = y * oc - x * os
+
+    x_out = x_rev * nc - y_rev * ns
+    y_out = y_rev * nc + x_rev * ns
+
+    if is_neox:
+        key[..., :half_rot] = x_out
+        key[..., half_rot:rot_dim] = y_out
+    else:
+        key[..., :rot_dim:2] = x_out
+        key[..., 1:rot_dim:2] = y_out
+
+
+def get_gpu_pci_bus_id(device_id: int = 0) -> str | None:
+    """
+    Get the PCI bus ID via CUDA/ROCm runtime.
+    Other backends return None.
+
+    Args:
+        device_id (int): CUDA/ROCm device index.
+
+    Returns:
+        str | None: PCI bus ID (e.g., "0000:29:00.0") or None if unavailable.
+    """
+    try:
+        if torch_dev.is_available() and device_id < torch_dev.device_count():
+            props = torch_dev.get_device_properties(device_id)
+            # PCI function number is always 0 for GPUs
+            bus_id = (
+                f"{props.pci_domain_id:04x}:{props.pci_bus_id:02x}:"
+                f"{props.pci_device_id:02x}.0"
+            )
+            return bus_id.upper()
+    except Exception:
+        pass
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Completion recorder fallback (no CUDA stream ordering; enqueue immediately)
+# ---------------------------------------------------------------------------
+
+_completion_lock = threading.Lock()
+_completion_buffer: list[tuple[str, bytes]] = []
+
+
+def record_completion_on_stream(
+    cuda_stream_ptr: int, kind: str, payload: bytes
+) -> None:
+    """Fallback: immediately enqueue the completion without stream ordering.
+
+    Args:
+        cuda_stream_ptr: Ignored on non-CUDA path.
+        kind: Dispatch key identifying the handler (e.g. "finish_write").
+        payload: Opaque msgpack-encoded bytes forwarded to the handler.
+    """
+    with _completion_lock:
+        _completion_buffer.append((kind, payload))
+
+
+def drain_recorded_completions() -> list[tuple[str, bytes]]:
+    """Fallback: atomically drain and return all pending completions.
+
+    Returns:
+        List of (kind, payload) pairs recorded since the last drain.
+    """
+    with _completion_lock:
+        items = list(_completion_buffer)
+        _completion_buffer.clear()
+    return items
+
+
+# ---------------------------------------------------------------------------
+# Event recorder fallback (no CUDA stream ordering; timestamp immediately)
+# ---------------------------------------------------------------------------
+
+_event_lock = threading.Lock()
+_event_buffer: list[tuple[str, str, float, dict[str, str], dict[str, int]]] = []
+
+
+def record_event_on_stream(
+    cuda_stream_ptr: int,
+    event_type_name: str,
+    session_id: str,
+    str_metadata: dict[str, str],
+    int_metadata: dict[str, int],
+) -> None:
+    """Fallback: immediately record the event without CUDA stream ordering.
+
+    The wall-clock timestamp is captured at call time (no host-callback).
+
+    Args:
+        cuda_stream_ptr: Ignored on non-CUDA path.
+        event_type_name: Event type identifier (e.g. "mp.store.start").
+        session_id: Session identifier for the event.
+        str_metadata: String-valued metadata dict.
+        int_metadata: Integer-valued metadata dict.
+    """
+    # Standard
+    import time
+
+    ts = time.time()
+    with _event_lock:
+        _event_buffer.append(
+            (event_type_name, session_id, ts, dict(str_metadata), dict(int_metadata))
+        )
+
+
+def drain_recorded_events() -> list[
+    tuple[str, str, float, dict[str, str], dict[str, int]]
+]:
+    """Fallback: atomically drain and return all pending events.
+
+    Returns:
+        List of (event_type_name, session_id, timestamp, str_metadata,
+        int_metadata) tuples recorded since the last drain.
+    """
+    with _event_lock:
+        items = list(_event_buffer)
+        _event_buffer.clear()
+    return items
diff --git a/lmcache/sdk/__init__.py b/lmcache/sdk/__init__.py
new file mode 100644
index 0000000..8f68bd6
--- /dev/null
+++ b/lmcache/sdk/__init__.py
@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public LMCache SDK helpers."""
+
+# First Party
+from lmcache.sdk.kvcache import KVCacheSDKError, LMCacheKVCacheContext
+
+__all__ = [
+    "KVCacheSDKError",
+    "LMCacheKVCacheContext",
+]
diff --git a/lmcache/sdk/batch.py b/lmcache/sdk/batch.py
new file mode 100644
index 0000000..ea3d4f6
--- /dev/null
+++ b/lmcache/sdk/batch.py
@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Public API for Batched Stream, a wrapper of Streams that are batched together.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Callable, Sequence
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.cli.metrics import Metrics, StreamHandler, get_formatter
+import lmcache.sdk.stream as lmc_stream
+
+
+class LMCacheBatchedStreamError(RuntimeError):
+    """Raised when a BatchedStream operation fails."""
+
+
+class LMCacheBatchedStream:
+    """A collection of LMCacheStreams run together as one batch."""
+
+    def __init__(self) -> None:
+        """Create a batch.
+
+        Attributes:
+            streams: Member streams keyed by stream id.
+            perf_metrics: Latest StreamPerfMetrics per stream id, overwritten
+                on each call to run_streams.
+        """
+        self.streams: dict[str, lmc_stream.LMCacheStream] = {}
+        self.perf_metrics: dict[str, lmc_stream.StreamPerfMetrics] = {}
+
+    def add(self, stream: lmc_stream.LMCacheStream) -> None:
+        """Add a stream to the batch, keyed by its stream id.
+
+        Args:
+            stream: The stream to add.
+
+        Raises:
+            LMCacheBatchedStreamError: If a stream with the same id is
+                in the batch.
+        """
+        if stream.stream_id() in self.streams:
+            raise LMCacheBatchedStreamError(
+                f"Stream {stream.stream_id()} already exists."
+            )
+        self.streams[stream.stream_id()] = stream
+
+    def get_stream(self, stream_id: str) -> lmc_stream.LMCacheStream:
+        """Return the stream registered under stream_id.
+
+        Args:
+            stream_id: The id of the stream to fetch.
+
+        Returns:
+            The matching LMCacheStream.
+
+        Raises:
+            LMCacheBatchedStreamError: If no stream has that id.
+        """
+        if stream_id not in self.streams:
+            raise LMCacheBatchedStreamError(
+                f"Stream with id {stream_id} does not exist."
+            )
+        return self.streams[stream_id]
+
+    def run_streams(
+        self, sampling_params: dict[str, Any], stream_ids: list[str] | None = None
+    ) -> float:
+        """Decode every selected stream concurrently and store their metrics.
+
+        Submits stream.generate(sampling_params) on a thread pool (one worker
+        per stream) and records each StreamPerfMetrics in perf_metrics.
+
+        Args:
+            sampling_params: Engine sampling params (e.g. max_tokens,
+                temperature) passed to every stream's generate().
+            stream_ids: Streams to run; None means all streams in the batch.
+
+        Returns:
+            Wall-clock duration of the batch, in seconds (0.0 if no streams).
+
+        Raises:
+            LMCacheBatchedStreamError: If any requested stream id is unknown.
+        """
+        if stream_ids is None:
+            stream_ids = list(self.streams.keys())
+
+        for stream_id in stream_ids:
+            if stream_id not in self.streams:
+                raise LMCacheBatchedStreamError(f"Stream {stream_id} does not exist.")
+
+        if not stream_ids:
+            return 0.0
+
+        self.perf_metrics.clear()
+        start_time = time.perf_counter()
+        with ThreadPoolExecutor(max_workers=len(stream_ids)) as executor:
+            futures = {}
+            for stream_id in stream_ids:
+                stream = self.streams[stream_id]
+                future = executor.submit(
+                    stream.generate, sampling_params=sampling_params
+                )
+                futures[future] = stream_id
+            # collect metrics
+            for future in as_completed(futures):
+                stream_id = futures[future]
+                self.perf_metrics[stream_id] = future.result()
+
+        return time.perf_counter() - start_time  # in seconds
+
+    def modify_stream(
+        self,
+        fn: Callable[[torch.Tensor, Sequence[int]], tuple[torch.Tensor, Sequence[int]]],
+        stream_ids: list[str] | None = None,
+        timeout: float = 30.0,
+        poll_interval: float = 0.2,
+    ) -> float:
+        """Apply KV edit to every selected stream concurrently.
+
+        Submits stream.modify_kv(fn) on a thread pool (one worker per stream).
+
+        Args:
+            fn: KV editor applied to each stream. Given (kv, tokens) and
+                returning (new_kv, new_tokens). See LMCacheStream.modify_kv().
+            stream_ids: Streams to modify. None means all streams in the batch.
+            timeout: Max seconds to wait for the cached KV to appear.
+            poll_interval: Seconds between retrieve attempts.
+
+        Returns:
+            Wall-clock duration of the batch, in seconds (0.0 if no streams).
+
+        Raises:
+            LMCacheBatchedStreamError: If any requested stream id is unknown.
+        """
+        if stream_ids is None:
+            stream_ids = list(self.streams.keys())
+
+        for stream_id in stream_ids:
+            if stream_id not in self.streams:
+                raise LMCacheBatchedStreamError(f"Stream {stream_id} does not exist.")
+
+        if not stream_ids:
+            return 0.0
+
+        start_time = time.perf_counter()
+
+        with ThreadPoolExecutor(max_workers=len(stream_ids)) as executor:
+            futures = {}
+            for stream_id in stream_ids:
+                stream = self.streams[stream_id]
+                future = executor.submit(
+                    stream.modify_kv, fn, timeout=timeout, poll_interval=poll_interval
+                )
+                futures[future] = stream_id
+            for future in as_completed(futures):
+                stream_id = futures[future]
+                future.result()
+
+        return time.perf_counter() - start_time  # in seconds
+
+    def get_perf_metrics(
+        self,
+        duration: float,
+        fmt: str,
+        width: int,
+        mode: str,
+        stream_ids: list[str] | None = None,
+    ) -> Metrics:
+        """Aggregate the stored per-stream metrics into a Metrics report.
+
+        Args:
+            duration: Batch wall-clock duration in seconds, for throughput.
+            fmt: Formatter name for the output handler (e.g. "terminal").
+            width: Output width passed to the formatter.
+            mode: "prefill" (input tokens + TTFT) or "decode" (output tokens +
+                TPOT + decoding speed).
+            stream_ids: Streams to include. None means all streams in batch.
+
+        Returns:
+            The aggregated Metrics report.
+
+        Raises:
+            LMCacheBatchedStreamError: If mode is not "prefill" or "decode".
+        """
+        if stream_ids is None:
+            stream_ids = list(self.streams.keys())
+
+        if mode not in ["prefill", "decode"]:
+            raise LMCacheBatchedStreamError(f"Invalid mode {mode}.")
+
+        metrics = Metrics(title=f"Batched Stream Metrics ({mode})")
+        metrics.add_handler(StreamHandler(get_formatter(fmt, width=width)))
+
+        cfg_section = metrics.add_section("config", "Configuration")
+        cfg_section.add("num_streams", "Number of Streams", len(self.streams))
+
+        result_section = metrics.add_section("results", "Results")
+        result_section.add("duration", "Total Duration (s)", duration)
+
+        input_tokens = 0
+        output_tokens = 0
+        for stream_id, perf_metrics in self.perf_metrics.items():
+            if stream_id in stream_ids:
+                input_tokens += perf_metrics.input_tokens
+                output_tokens += perf_metrics.output_tokens
+
+        if mode == "prefill":
+            result_section.add("input_tokens", "Total Input Tokens", input_tokens)
+            result_section.add(
+                "input_tput",
+                "Input Throughput (tokens/s)",
+                input_tokens / duration if duration > 0 else 0.0,
+            )
+
+        if mode == "decode":
+            result_section.add("output_tokens", "Total Output Tokens", output_tokens)
+            result_section.add(
+                "output_tput",
+                "Decode Throughput (tokens/s)",
+                output_tokens / duration if duration > 0 else 0.0,
+            )
+
+        return metrics
+
+    def prefill(
+        self,
+        sampling_params: dict[str, Any],
+        fmt: str = "terminal",
+        width: int = 80,
+        stream_ids: list[str] | None = None,
+    ) -> Metrics:
+        """Prefill every stream once (max_tokens forced to 1) and report.
+
+        Args:
+            sampling_params: Engine sampling params, max_tokens is set 1.
+            fmt: Formatter name for the output handler.
+            width: Output width passed to the formatter.
+            stream_ids: Streams to run; None means all streams in the batch.
+
+        Returns:
+            A prefill-mode Metrics report (input tokens, throughput, TTFT).
+        """
+        sampling_params = {**sampling_params, "max_tokens": 1}
+        duration = self.run_streams(
+            sampling_params=sampling_params, stream_ids=stream_ids
+        )
+        return self.get_perf_metrics(
+            duration=duration,
+            fmt=fmt,
+            width=width,
+            mode="prefill",
+            stream_ids=stream_ids,
+        )
+
+    def modify(
+        self,
+        fn: Callable[[torch.Tensor, Sequence[int]], tuple[torch.Tensor, Sequence[int]]],
+        fmt: str = "terminal",
+        width: int = 80,
+        stream_ids: list[str] | None = None,
+    ) -> Metrics:
+        """Apply a KV edit to every stream and report the time taken.
+
+        Args:
+            fn: KV editor applied to each stream (see modify_stream).
+            fmt: Formatter name for the output handler.
+            width: Output width passed to the formatter.
+            stream_ids: Streams to modify. None means all streams in the batch.
+
+        Returns:
+            A Metrics report containing the total modify duration.
+        """
+        duration = self.modify_stream(fn, stream_ids=stream_ids)
+
+        metrics = Metrics(title="Batched Stream Modify Metrics")
+        metrics.add_handler(StreamHandler(get_formatter(fmt, width=width)))
+        result_section = metrics.add_section("results", "Results")
+        result_section.add("duration", "Total Duration (s)", duration)
+
+        return metrics
+
+    def decode(
+        self,
+        sampling_params: dict[str, Any],
+        fmt: str = "terminal",
+        width: int = 80,
+        stream_ids: list[str] | None = None,
+    ) -> Metrics:
+        """Decode every stream and report decode metrics.
+
+        Args:
+            sampling_params: Engine sampling params (e.g. max_tokens,
+                temperature) passed to every stream's generate().
+            fmt: Formatter name for the output handler.
+            width: Output width passed to the formatter.
+            stream_ids: Streams to run. None means all streams in the batch.
+
+        Returns:
+            A decode-mode Metrics report (output tokens, throughput, TPOT,
+            decoding speed).
+        """
+        duration = self.run_streams(
+            sampling_params=sampling_params, stream_ids=stream_ids
+        )
+        return self.get_perf_metrics(
+            duration=duration,
+            fmt=fmt,
+            width=width,
+            mode="decode",
+            stream_ids=stream_ids,
+        )
diff --git a/lmcache/sdk/kvcache.py b/lmcache/sdk/kvcache.py
new file mode 100644
index 0000000..a9cb587
--- /dev/null
+++ b/lmcache/sdk/kvcache.py
@@ -0,0 +1,539 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+SDK for retrieving and storing KV cache tensors.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Sequence
+import os
+import time
+import uuid
+
+# Third Party
+import requests
+import torch
+import zmq
+
+# First Party
+from lmcache.integration.vllm.vllm_multi_process_adapter import send_lmcache_request
+from lmcache.logging import init_logger
+from lmcache.sdk.wrapper.contiguous import ContiguousTransferWrapper
+from lmcache.v1.gpu_connector.utils import (
+    DiscoverableKVCache,
+    LayoutHints,
+    get_block_size,
+    get_num_heads,
+)
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import RequestType, get_response_class
+from lmcache.v1.multiprocess.transfer_context.worker_transfer import (
+    EngineDrivenTransferContext,
+    create_transfer_context,
+)
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+class KVCacheSDKError(RuntimeError):
+    """Raised when an SDK KV-cache operation fails."""
+
+
+class LMCacheKVCacheContext:
+    """
+    Retrieve and store KV cache tensors via LMCache's MQ endpoints.
+
+    The model layout must already be registered in the running LMCache server
+    (e.g. by a vllm instance that called REGISTER_KV_CACHE).
+    Getting the layout information from server requires inference engine running
+    with GPU so that SDK can derive the shapes.
+
+    SDK is running on CPU, so the allocated paged KV cache is on CPU, and the
+    geometry is always in HND order regardless of the inference engine's.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        http_url: str,
+        model_name: str,
+        timeout: float = 60.0,
+    ) -> None:
+        """
+        Initialize the SDK context and register the SDK transfer strategy.
+
+        Args:
+            url: ZMQ endpoint URL for the LMCache message queue.
+            http_url: HTTP endpoint URL for fetching information.
+            model_name: Model name used by the running LMCache server instance.
+            timeout: Timeout in seconds for blocking MQ calls. Defaults to 60.
+
+        Returns:
+            LMCacheKVCacheContext instance.
+        """
+        self._zmq_context = zmq.Context()
+        self._mq_client = MessageQueueClient(url, self._zmq_context)
+        self._mq_timeout = timeout
+        self._model_name = model_name
+        self.instance_id = os.getpid()
+        self._http_url = http_url
+
+        mp_conf = {}
+        try:
+            response = requests.get(f"{self._http_url}/config", timeout=timeout)
+            response.raise_for_status()
+            mp_conf = response.json()["mp"]
+        except (requests.RequestException, KeyError, ValueError) as err:
+            raise KVCacheSDKError(
+                f"failed to fetch server config from {self._http_url}/config"
+            ) from err
+        self._chunk_size: int = int(mp_conf["chunk_size"])
+        self.shm_name: str = str(mp_conf.get("shm_name", "")).lstrip("/")
+        if self.shm_name and not self.shm_name.startswith("lmcache_l1_pool_"):
+            self.shm_name = f"lmcache_l1_pool_{self.shm_name}"
+
+        self._cache_context_meta_conf = {}
+        try:
+            response = requests.get(f"{self._http_url}/status", timeout=timeout)
+            response.raise_for_status()
+            self._cache_context_meta_conf = response.json().get(
+                "cache_context_meta", {}
+            )
+        except (requests.RequestException, KeyError, ValueError) as err:
+            raise KVCacheSDKError(
+                f"failed to fetch server config from {self._http_url}/status"
+            ) from err
+
+        self._pending_lookups: set[str] = set()
+        self._finished_lookups: dict[str, int] = {}
+
+        logger.info(
+            f"Initialized LMCacheKVCacheContext with instance_id={self.instance_id}, "
+            f"model_name={self._model_name}, chunk_size={self._chunk_size}, "
+            f"shm_name={self.shm_name}"
+        )
+
+    def register_kv_caches(
+        self,
+    ) -> None:
+        """Register the KV cache layout for the model with the SDK context."""
+        entry = None
+        for e in self._cache_context_meta_conf.values():
+            if e.get("model_name") == self._model_name:
+                entry = e
+                break
+        if not entry:
+            raise KVCacheSDKError(
+                f"no registered GPU layout for model_name={self._model_name!r}; "
+                "MP mode cannot derive geometry from model_name alone — "
+                "register from a vLLM instance first, or pass the geometry explicitly."
+            )
+
+        try:
+            self._world_size = int(entry.get("world_size", 1))
+            kv_cache_layout = entry.get("kv_cache_layout", {})
+            if not kv_cache_layout:
+                raise KVCacheSDKError(
+                    f"no registered KV cache layout for {self._model_name!r}."
+                )
+            num_layers = kv_cache_layout.get("num_layers", 0)
+
+            kernel_groups = kv_cache_layout.get("kernel_groups", [])
+            if len(kernel_groups) != 1:
+                raise KVCacheSDKError(
+                    "Currently not supporting hybrid models with multiple "
+                    f"kernel groups; found {len(kernel_groups)} "
+                    f"for model_name={self._model_name!r}."
+                )
+            kernel_group = kernel_groups[0]
+            dtype = getattr(torch, kernel_group["dtype"].replace("torch.", ""))
+            tokens_per_block = kernel_group.get("tokens_per_block", 0)
+
+            inner = [
+                int(x)
+                for x in kernel_group["engine_kv_concrete_shape"]
+                .split("[")[1]
+                .rstrip("] ")
+                .split(",")
+            ]
+
+            fmt = getattr(lmc_ops.EngineKVFormat, kernel_group["engine_kv_format"])
+            probe: list[DiscoverableKVCache] = [torch.empty(inner, device="meta")]
+            num_kv_heads = get_num_heads(probe, fmt)
+            block_size = get_block_size(probe, fmt)
+            head_dim = inner[-1]
+            if block_size != tokens_per_block:
+                raise KVCacheSDKError(
+                    f"decoded block_size {block_size} != tokens_per_block "
+                    f"{tokens_per_block} for model_name={self._model_name!r}"
+                )
+        except Exception as err:
+            raise KVCacheSDKError(
+                f"failed to decode KV cache layout for model_name={self._model_name!r}"
+            ) from err
+
+        # SDK runs on CPU, LMCache's detects HND (gpu_connector/utils.py:663).
+        # Build in HND-physical order [NB, 2, NH, BS, HS] (flip from GPU order)
+        # So, no matter the inference engine runs on CPU or GPU, SDK will always
+        # use HND.
+        # Hardcode number of blocks to 1 (dummy shape) only for registering
+        num_blocks = 1
+        shape = (num_blocks, 2, num_kv_heads, block_size, head_dim)
+
+        self._kv_caches = {
+            f"layer.{i}": torch.zeros(shape, dtype=dtype, device="cpu")
+            for i in range(num_layers)
+        }
+
+        transfer_ctx = create_transfer_context(self._kv_caches)
+        self.blocks_in_chunk = self._chunk_size // block_size
+        layout_hints = LayoutHints(
+            kv_layout="HND",
+            num_kv_heads=num_kv_heads,
+            tokens_per_block=block_size,
+            head_dim=head_dim,
+        )
+
+        transfer_ctx.register(
+            self.instance_id,
+            self._kv_caches,
+            self._model_name,
+            self._world_size,
+            self.blocks_in_chunk,
+            self._mq_client,
+            self._mq_timeout,
+            send_request=send_lmcache_request,
+            layout_hints=layout_hints,
+        )
+
+        if not isinstance(transfer_ctx, EngineDrivenTransferContext):
+            raise KVCacheSDKError(
+                "SDK requires an engine-driven transfer context, got "
+                f"{type(transfer_ctx).__name__}."
+            )
+        self._transfer_ctx = ContiguousTransferWrapper(
+            transfer_ctx.engine_driven_context, self._chunk_size
+        )
+
+    @property
+    def chunk_size(self) -> int:
+        """Return the chunk size of the context."""
+        return self._chunk_size
+
+    @property
+    def mq_timeout(self) -> float:
+        """Return the message queue timeout of the context."""
+        return self._mq_timeout
+
+    @property
+    def transfer_ctx(self) -> ContiguousTransferWrapper:
+        """Return the contiguous transfer context."""
+        return self._transfer_ctx
+
+    def close(self) -> None:
+        """Close the MQ client and ZMQ context."""
+        self._mq_client.close()
+
+    def maybe_submit_lookup_request(
+        self,
+        request_id: str,
+        token_ids: list[int],
+        cache_salt: str = "",
+    ) -> None:
+        """Submit a LOOKUP request for the given token IDs.
+        Modification from lmcache/integration/vllm/vllm_multi_process_adapter.py.
+        Need duplicate since SDK has TransferContext, not Adapter, but still need
+        lookup and end_session functionality.
+
+        Args:
+            request_id: Unique ID for this lookup request.
+            token_ids: List of token IDs to look up.
+            cache_salt: Optional cache salt string for the lookup.
+        """
+        if request_id in self._pending_lookups:
+            # Skip if there is already a lookup request
+            return
+
+        aligned_end = (len(token_ids) // self._chunk_size) * self._chunk_size
+
+        key = self._create_key(
+            token_ids,
+            start=0,
+            end=aligned_end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        ).no_worker_id_version()
+
+        future = self._mq_client.submit_request(
+            RequestType.LOOKUP,
+            [key, self._world_size],
+            get_response_class(RequestType.LOOKUP),
+        )
+        try:
+            future.result(timeout=self._mq_timeout)
+        except TimeoutError:
+            logger.warning(
+                "LOOKUP request timed out after %ss.",
+                self._mq_timeout,
+            )
+            return
+        self._pending_lookups.add(request_id)
+
+    def check_lookup_result(self, request_id: str) -> int | None:
+        """Check the result of a LOOKUP request.
+        Modification from lmcache/integration/vllm/vllm_multi_process_adapter.py.
+        Need duplicate since SDK has TransferContext, not Adapter, but still need
+        lookup and end_session functionality.
+
+        Args:
+            request_id: The request ID of the LOOKUP to check.
+
+        Returns:
+            The number of prefetched tokens if the LOOKUP is finished,
+            0 if not finished, or None if the request ID is not found.
+        """
+        if request_id not in self._pending_lookups:
+            # No job — either unhealthy at submit time or already cleaned up.
+            # If we have a cached result, return it to handle repeated calls.
+            return self._finished_lookups.get(request_id, 0)
+
+        if request_id in self._finished_lookups:
+            # Return cached result if the job is already finished
+            return self._finished_lookups[request_id]
+
+        try:
+            result = self._mq_client.submit_request(
+                RequestType.QUERY_PREFETCH_STATUS,
+                [request_id],
+                get_response_class(RequestType.QUERY_PREFETCH_STATUS),
+            ).result(timeout=self._mq_timeout)
+        except TimeoutError:
+            logger.warning(
+                "QUERY_PREFETCH_STATUS timed out after %ss.",
+                self._mq_timeout,
+            )
+            return 0
+
+        if result is None:
+            return None
+
+        token_count = result * self._chunk_size
+        self._finished_lookups[request_id] = token_count
+        return token_count
+
+    def end_session(self, request_id: str, block_ids: list[int] | None = None) -> None:
+        """End a session and clean up associated resources on the server.
+
+        Args:
+            request_id: The request ID of the session to end.
+            block_ids: Optional list of block IDs to free.
+        """
+        self._pending_lookups.discard(request_id)
+        self._finished_lookups.pop(request_id, None)
+        try:
+            self._mq_client.submit_request(
+                RequestType.END_SESSION,
+                [request_id],
+                get_response_class(RequestType.END_SESSION),
+            ).result(timeout=self._mq_timeout)
+        except TimeoutError:
+            logger.warning(
+                "END_SESSION timed out after %ss for request_id=%s.",
+                self._mq_timeout,
+                request_id,
+            )
+
+    # Helper functions
+    def _create_key(
+        self,
+        token_ids: list[int],
+        start: int,
+        end: int,
+        request_id: str,
+        cache_salt: str = "",
+        worker_id: int | None = None,
+    ) -> IPCCacheServerKey:
+        """Convert token IDs to an IPC cache engine key.
+
+        Args:
+            token_ids: The token IDs.
+            start: Start token index.
+            end: End token index.
+            request_id: The request ID.
+            cache_salt: Per-user isolation salt.
+            worker_id: Optional worker ID for the key.
+                If None, the key will be created without a worker ID (for lookups).
+
+        Returns:
+            IPCCacheServerKey: The constructed key.
+        """
+        return IPCCacheServerKey(
+            model_name=self._model_name,
+            world_size=self._world_size,
+            worker_id=worker_id,
+            token_ids=tuple(token_ids),
+            start=start,
+            end=end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        )
+
+
+def connect(
+    url: str,
+    http_url: str,
+    model_name: str,
+    timeout: float = 60.0,
+) -> "LMCacheKVCacheContext":
+    """Create and initialize the LMCache SDK context.
+
+    Args:
+        url: ZMQ endpoint URL for the LMCache message queue.
+        http_url: HTTP endpoint URL for fetching server configuration.
+        model_name: Model name used by the running LMCache server instance.
+        timeout: Timeout in seconds for blocking MQ calls. Defaults to 60.
+
+    Returns:
+        An initialized LMCacheKVCacheContext instance.
+        Ready to be passed to close(), retrieve(), and store() functions.
+    """
+    ctx = LMCacheKVCacheContext(
+        url=url, http_url=http_url, model_name=model_name, timeout=timeout
+    )
+    ctx.register_kv_caches()
+    return ctx
+
+
+def close(ctx: "LMCacheKVCacheContext") -> None:
+    """Close the LMCache SDK context and release resources.
+
+    Args:
+        ctx: The LMCacheKVCacheContext instance to close.
+    """
+    ctx.close()
+
+
+def retrieve(
+    ctx: "LMCacheKVCacheContext",
+    tokens: Sequence[int],
+    cache_salt: str = "",
+) -> torch.Tensor | None:
+    """Retrieve KV cache tensors for the given token IDs.
+
+    Args:
+        ctx: The LMCacheKVCacheContext instance to use for retrieval.
+        tokens: The list of token IDs to retrieve KV cache for.
+        cache_salt: Optional cache salt string for the lookup.
+
+    Returns:
+        A contiguous CPU tensor containing the retrieved KV cache for
+        the requested tokens.
+        None if retrieval fails or there are no tokens to retrieve.
+    """
+    if not tokens:
+        return None
+
+    # Drop tokens not fit into a whole chunk
+    total_tokens = (len(tokens) // ctx.chunk_size) * ctx.chunk_size
+    if total_tokens == 0:
+        return None
+
+    # Assign request ID to this request
+    request_id = f"retrieve-{uuid.uuid4().hex}"
+    key = ctx._create_key(
+        token_ids=list(tokens[:total_tokens]),
+        start=0,
+        end=total_tokens,
+        request_id=request_id,
+        cache_salt=cache_salt,
+        worker_id=0,
+    )
+
+    # Phase 0: Trigger lookup
+    ctx.maybe_submit_lookup_request(
+        request_id,
+        token_ids=list(tokens[:total_tokens]),
+        cache_salt=cache_salt,
+    )
+
+    start_time = time.time()
+    num_prefetched_tokens = ctx.check_lookup_result(request_id)
+    while num_prefetched_tokens is None:
+        if time.time() - start_time > ctx.mq_timeout:
+            raise KVCacheSDKError(
+                f"LOOKUP request timed out after {ctx.mq_timeout}s "
+                f"for request_id={request_id}"
+            )
+        logger.info(
+            "Waiting for LOOKUP result for request_id=%s...",
+            request_id,
+        )
+        time.sleep(0.01)
+        num_prefetched_tokens = ctx.check_lookup_result(request_id)
+
+    if num_prefetched_tokens <= 0:
+        ctx.end_session(request_id)
+        return None
+
+    # Phase 1: retrieve the cached prefix as one contiguous tensor
+    key = ctx._create_key(
+        token_ids=list(tokens[:num_prefetched_tokens]),
+        start=0,
+        end=num_prefetched_tokens,
+        request_id=request_id,
+        cache_salt=cache_salt,
+        worker_id=0,
+    )
+    try:
+        return ctx.transfer_ctx.retrieve(key, ctx.instance_id)
+    finally:
+        ctx.end_session(request_id)
+
+
+def store(
+    ctx: "LMCacheKVCacheContext",
+    kv: torch.Tensor,
+    tokens: Sequence[int],
+    cache_salt: str = "",
+) -> bool:
+    """Store KV cache tensors for the given token IDs.
+
+    Args:
+        ctx: The LMCacheKVCacheContext instance to use for storage.
+        kv: The KV cache tensor to store, of shape [2, L, T, D].
+        tokens: The list of token IDs corresponding to the KV cache tensor.
+        cache_salt: Optional cache salt string for the store.
+
+    Returns:
+        True if the store operation is successful, False otherwise.
+    """
+    if len(tokens) != kv.shape[2]:
+        raise KVCacheSDKError(
+            f"Number of tokens ({len(tokens)}) does not match KV tensor's "
+            f"token dimension ({kv.shape[2]})."
+        )
+    token_ids = list(tokens)
+    total_tokens = (len(token_ids) // ctx.chunk_size) * ctx.chunk_size
+    token_ids = token_ids[:total_tokens]
+    kv_cpu = kv[:, :, :total_tokens, :].detach().cpu().contiguous()
+
+    # Phase 0: assign request ID to this request
+    request_id = f"store-{uuid.uuid4().hex}"
+    key = ctx._create_key(
+        token_ids=token_ids,
+        start=0,
+        end=total_tokens,
+        request_id=request_id,
+        cache_salt=cache_salt,
+        worker_id=0,
+    )
+
+    # Phase 1: store the KV cache tensor
+    try:
+        return ctx.transfer_ctx.store(key, ctx.instance_id, kv_cpu)
+    finally:
+        ctx.end_session(request_id)
diff --git a/lmcache/sdk/stream.py b/lmcache/sdk/stream.py
new file mode 100644
index 0000000..3975f60
--- /dev/null
+++ b/lmcache/sdk/stream.py
@@ -0,0 +1,326 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Public API for LMCacheStream, a wrapper of a logical request going through the SDK.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+import time
+import uuid
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+import lmcache.sdk.kvcache as lmc_sdk
+
+logger = init_logger(__name__)
+
+
+class LMCacheStreamError(RuntimeError):
+    """Raised when a LMCacheStream operation fails."""
+
+
+@dataclass(frozen=True)
+class StreamPerfMetrics:
+    """Performance metrics for a single generate() call.
+
+    Args:
+        duration: Time taken for the generate() call, in seconds.
+        input_tokens: number of input tokens (prompt + suffix).
+        output_tokens: Number of tokens generated in this generate() call.
+        input_tput: Input tokens per second over this call.
+        output_tput: Generated tokens per second over this call.
+        tpot: List of times between generated tokens, in seconds.
+        ttft: Time to first token, in seconds.
+    """
+
+    duration: float = 0.0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    input_tput: float = 0.0
+    output_tput: float = 0.0
+    tpot: list[float] = field(default_factory=list)
+    ttft: float = 0.0
+
+
+@dataclass(frozen=True)
+class TokenEvent:
+    """One decoded token reported by the injected post_completion callable.
+
+    Args:
+        token_id: The generated token id.
+        text: The decoded text for this token.
+    """
+
+    token_id: int
+    text: str = ""
+
+
+class PostCompletion(Protocol):
+    """Inference function (callable) to be called by stream."""
+
+    def __call__(
+        self,
+        prompt_token_ids: list[int],
+        sampling_params: dict[str, Any],
+        cache_salt: str,
+    ) -> Iterable[TokenEvent]:
+        """Stream decoded tokens for the given prompt.
+
+        Args:
+            prompt_token_ids: Prompt, encoded to list of token ids.
+            sampling_params: Sampling parameters for generation.
+            cache_salt: Per-user isolation salt, or empty string.
+
+        Returns:
+            An iterable yielding one TokenEvent per decoded token.
+        """
+        ...
+
+
+def create_request(
+    ctx: lmc_sdk.LMCacheKVCacheContext,
+    post_completion: PostCompletion,
+    prompt_token_ids: Sequence[int],
+    cache_salt: str = "",
+) -> LMCacheStream:
+    """Create an LMCacheStream for a new request.
+
+    Args:
+        ctx: The LMCache SDK context used for retrieve/store.
+        post_completion: Callable that submits a request to the engine.
+        prompt_token_ids: Initial prompt token ids.
+        cache_salt: Per-user isolation salt, or empty string.
+
+    Returns:
+        A new LMCacheStream.
+    """
+    return LMCacheStream(
+        ctx=ctx,
+        post_completion=post_completion,
+        prompt_token_ids=prompt_token_ids,
+        cache_salt=cache_salt,
+    )
+
+
+def generate(
+    stream: LMCacheStream,
+    sampling_params: dict[str, Any],
+    suffix_tokens: Sequence[int] = (),
+) -> StreamPerfMetrics:
+    """Run/continue a stream's generate. See LMCacheStream.generate."""
+    return stream.generate(sampling_params, suffix_tokens)
+
+
+def get(
+    stream: LMCacheStream, timeout: float = 30.0, poll_interval: float = 0.2
+) -> torch.Tensor:
+    """Retrieve the cached KV for a stream. See LMCacheStream.retrieve_kv."""
+    return stream.retrieve_kv(timeout=timeout, poll_interval=poll_interval)
+
+
+def update(
+    stream: LMCacheStream,
+    kv: torch.Tensor,
+    tokens: Sequence[int],
+) -> None:
+    """Store edited KV into a stream. See LMCacheStream.update_kv."""
+    stream.update_kv(kv, tokens)
+
+
+class LMCacheStream:
+    """Handle for one logical request spanning multiple inference passes.
+
+    Args:
+        ctx: The LMCache SDK context used for retrieve/store.
+        post_completion: Callable for submitting request to inference engine.
+        prompt_token_ids: Initial prompt token ids.
+        cache_salt: Per-user isolation salt, or empty string.
+    """
+
+    def __init__(
+        self,
+        ctx: lmc_sdk.LMCacheKVCacheContext,
+        post_completion: PostCompletion,
+        prompt_token_ids: Sequence[int],
+        cache_salt: str = "",
+    ) -> None:
+        """Initialize per-request state from the initial prompt.
+
+        Beyond the constructor args, sets up: tokens (the live sequence backing
+        the KV, starting as the prompt), done (the EOS flag), and internal
+        output history / suffix-token bookkeeping.
+        """
+        self.ctx = ctx
+        self.post_completion = post_completion
+        self.cache_salt = cache_salt
+        self.tokens: list[int] = list(prompt_token_ids)
+        self.done: bool = False
+        self._decoded: int = 0
+        self._text_parts: list[str] = []
+        self._stream_id: str = str(uuid.uuid4())
+        self._suffix_tokens: list[int] = []
+
+    def stream_id(self) -> str:
+        """Return the unique stream id."""
+        return self._stream_id
+
+    def suffix_tokens(self) -> list[int]:
+        """Return the suffix tokens to be appended to the prompt."""
+        return self._suffix_tokens
+
+    def decoded_tokens(self) -> int:
+        """Return cumulative tokens decoded across all segments so far."""
+        return self._decoded
+
+    def output_text(self) -> str:
+        """Return the concatenated generated text across all segments."""
+        return "".join(self._text_parts)
+
+    def output_tokens(self) -> list[int]:
+        """Return the concatenated generated tokens across all segments."""
+        return self.tokens
+
+    def is_done(self) -> bool:
+        """Return True if the stream has finished generating."""
+        return self.done
+
+    def generate(
+        self, sampling_params: dict[str, Any], suffix_tokens: Sequence[int] = ()
+    ) -> StreamPerfMetrics:
+        """Run one inference pass and append the result to the stream history.
+
+        Args:
+            sampling_params: Engine sampling params.
+            suffix_tokens: Extra tokens not fit into chunk_size.
+
+        Returns:
+            StreamPerfMetrics for this call (duration, token counts,
+            throughputs, ttft, tpot — all times in seconds).
+
+        Raises:
+            LMCacheStreamError: If post_completion fails mid-stream.
+        """
+        pending = self._suffix_tokens + list(suffix_tokens)
+        self._suffix_tokens = []
+        if pending:
+            self.tokens.extend(pending)
+        events = self.post_completion(self.tokens, sampling_params, self.cache_salt)
+
+        input_tokens = len(self.tokens)
+
+        gen_tokens: list[int] = []
+        gen_texts: list[str] = []
+        start_time = time.perf_counter()
+        last_token_time = start_time
+        time_between_tokens = []
+        try:
+            for event in events:
+                gen_tokens.append(event.token_id)
+                gen_texts.append(event.text)
+                time_between_tokens.append(time.perf_counter() - last_token_time)
+                last_token_time = time.perf_counter()
+        except Exception as e:
+            raise LMCacheStreamError(
+                f"Stream {self.stream_id} failed during generation: {e}"
+            ) from e
+        finally:
+            self._decoded += len(gen_tokens)
+            self._text_parts.extend(gen_texts)
+            self.tokens.extend(gen_tokens)
+
+        # produces less than max_tokens --> EOS
+        output_tokens = len(gen_tokens)
+        max_tokens = sampling_params.get("max_tokens", 1)
+        self.done = output_tokens < max_tokens
+
+        total_time = time.perf_counter() - start_time
+
+        return StreamPerfMetrics(
+            duration=total_time,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            input_tput=input_tokens / total_time if total_time > 0 else 0.0,
+            output_tput=output_tokens / total_time if total_time > 0 else 0.0,
+            tpot=time_between_tokens[1:] if len(time_between_tokens) > 1 else [],
+            ttft=time_between_tokens[0] if time_between_tokens else 0.0,
+        )
+
+    def retrieve_kv(
+        self, timeout: float = 30.0, poll_interval: float = 0.2
+    ) -> torch.Tensor:
+        """Retrieve the cached KV for the current tokens, polling until ready.
+
+        Args:
+            timeout: Max seconds to wait for the cached KV to appear.
+            poll_interval: Seconds between retrieve attempts.
+
+        Returns:
+            The cached KV as a [2, L, hit_tokens, D] tensor (chunk-aligned).
+
+        Raises:
+            LMCacheStreamError: If no cached KV is available within timeout.
+        """
+        deadline = time.perf_counter() + timeout
+        kv = lmc_sdk.retrieve(self.ctx, self.tokens, self.cache_salt)
+        while kv is None and time.perf_counter() < deadline:
+            time.sleep(poll_interval)
+            kv = lmc_sdk.retrieve(self.ctx, self.tokens, self.cache_salt)
+        if kv is None:
+            raise LMCacheStreamError(
+                f"no cached KV for {self.stream_id} after {timeout:.0f}s"
+            )
+        return kv
+
+    def update_kv(
+        self,
+        kv: torch.Tensor,
+        tokens: Sequence[int],
+    ) -> None:
+        """Store an edited KV and reset the stream to back it.
+
+        Replaces tokens with the given tokens and clears done. Logs a warning
+        if the store reports the KV was already cached.
+
+        Args:
+            kv: The edited KV tensor to store, shape [2, L, T, D].
+            tokens: Token ids the KV corresponds to (T must match kv.shape[2]).
+        """
+        if not lmc_sdk.store(self.ctx, kv, tokens, self.cache_salt):
+            logger.warning(
+                "store reported edited KV already cached for stream %s",
+                self.stream_id,
+            )
+        self.tokens = list(tokens)
+        self.done = False
+
+    def modify_kv(
+        self,
+        fn: Callable[[torch.Tensor, Sequence[int]], tuple[torch.Tensor, Sequence[int]]],
+        timeout: float = 30.0,
+        poll_interval: float = 0.2,
+    ) -> None:
+        """Edit the cached KV via a caller-supplied function.
+
+        Retrieves the chunk-aligned KV, records the non-chunk-aligned tail in
+        _suffix_tokens (prepended, so it survives until the next generate),
+        applies fn to the cached prefix, and stores the result via update_kv.
+
+        Args:
+            fn: KV editor given (kv[2,L,T,D], tokens[:cached_len]) and returning
+                (new_kv, new_tokens) for the edited prefix.
+        """
+        kv = self.retrieve_kv(timeout=timeout, poll_interval=poll_interval)
+        cached_len = kv.shape[2]
+        # Tokens past the cached KV: the remainder of chunks that retrieve()
+        # (chunk-aligned) didn't return.
+        self._suffix_tokens = list(self.tokens[cached_len:]) + self._suffix_tokens
+        new_kv, new_tokens = fn(kv, self.tokens[:cached_len])
+        self.update_kv(new_kv, new_tokens)
diff --git a/lmcache/sdk/wrapper/__init__.py b/lmcache/sdk/wrapper/__init__.py
new file mode 100644
index 0000000..6d8d1c1
--- /dev/null
+++ b/lmcache/sdk/wrapper/__init__.py
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Transport wrappers for the LMCache KV cache SDK."""
+
+# First Party
+from lmcache.sdk.wrapper.contiguous import ContiguousTransferWrapper
+
+__all__ = [
+    "ContiguousTransferWrapper",
+]
diff --git a/lmcache/sdk/wrapper/contiguous.py b/lmcache/sdk/wrapper/contiguous.py
new file mode 100644
index 0000000..cd6b36b
--- /dev/null
+++ b/lmcache/sdk/wrapper/contiguous.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+"""EngineDrivenContext to store/retrieve a contiguous KV tensor for SDK use."""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.transfer_context.base import EngineDrivenContext
+
+
+class ContiguousTransferWrapper:
+    """Store/retrieve a contiguous KV tensor through an ``EngineDrivenContext``.
+
+    Args:
+        context: The engine-driven (SHM or pickle) transport.
+        chunk_size: Number of tokens per LMCache chunk.
+    """
+
+    def __init__(self, context: EngineDrivenContext, chunk_size: int) -> None:
+        self._context = context
+        self._chunk_size = chunk_size
+
+    def store(self, key: IPCCacheServerKey, instance_id: int, kv: torch.Tensor) -> bool:
+        """Store a contiguous [2, L, T, D] tensor
+
+        Args:
+            key: The cache server key.
+            instance_id: The cache server instance ID.
+            kv: The contiguous KV tensor to store.
+
+        Returns:
+            True if the store was successful, False otherwise.
+        """
+        result = self._context.prepare_store(key, instance_id)
+        if result is None:
+            # Pickle: chunk the contiguous KV tensor (commit takes list of chunks).
+            num_chunks = kv.shape[2] // self._chunk_size
+            chunks = [
+                kv[
+                    :, :, i * self._chunk_size : (i + 1) * self._chunk_size, :
+                ].contiguous()
+                for i in range(num_chunks)
+            ]
+        else:
+            # SHM: fill missing chunks' slots in place.
+            slot_tensors, chunk_indices = result
+            for slot, chunk_idx in zip(slot_tensors, chunk_indices, strict=True):
+                start = chunk_idx * self._chunk_size
+                slot.copy_(kv[:, :, start : start + self._chunk_size, :])
+            chunks = []
+        return self._context.commit_store(key, instance_id, chunks)
+
+    def retrieve(self, key: IPCCacheServerKey, instance_id: int) -> torch.Tensor | None:
+        """Retrieve the KV as a contiguous [2, L, hit_tokens, D] tensor
+
+        Args:
+            key: The cache server key.
+            instance_id: The cache server instance ID.
+
+        Returns:
+            The contiguous KV tensor if found, None otherwise.
+        """
+        slot_tensors = self._context.prepare_retrieve(key, instance_id)
+        if not slot_tensors:
+            return None
+        try:
+            # Both Pickle and SHM returns list of [2, L, T, D] tensors
+            # Concatenate along the token dimension.
+            return torch.cat(slot_tensors, dim=2)
+        finally:
+            self._context.commit_retrieve(key, instance_id)
diff --git a/lmcache/storage_backend/serde/__init__.py b/lmcache/storage_backend/serde/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/storage_backend/serde/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/storage_backend/serde/cachegen_basics.py b/lmcache/storage_backend/serde/cachegen_basics.py
new file mode 100644
index 0000000..f359693
--- /dev/null
+++ b/lmcache/storage_backend/serde/cachegen_basics.py
@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import List
+import io
+import pickle
+
+# Third Party
+from transformers import AutoConfig
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import _lmcache_nvtx_annotate
+
+logger = init_logger(__name__)
+
+CACHEGEN_GPU_MAX_TOKENS_PER_CHUNK = 256
+
+
+@dataclass
+class QuantizationSpec:
+    start_layer: int
+    end_layer: int
+    bins: int
+
+    def __getitem__(self, key: str) -> int:
+        return getattr(self, key)
+
+
+@dataclass
+class CacheGenConfig:
+    # TODO: move this class to another file like "cachegen_basics.py"
+    nlayers: int
+    kspecs: List[QuantizationSpec]
+    vspecs: List[QuantizationSpec]
+
+    def __getitem__(self, key: str) -> int:
+        return getattr(self, key)
+
+    @staticmethod
+    def from_model_name(model_name: str) -> "CacheGenConfig":
+        family_7b = [
+            "mistralai/Mistral-7B-Instruct-v0.2",
+            "lmsys/longchat-7b-16k",
+            "Qwen/Qwen-7B",
+        ]
+        family_8b = ["meta-llama/Llama-3.1-8B-Instruct"]
+        family_9b = ["THUDM/glm-4-9b-chat"]
+        if model_name in family_7b:
+            return CacheGenConfig(
+                nlayers=32,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=32, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=32, bins=16),
+                ],
+            )
+        elif model_name in family_8b:
+            return CacheGenConfig(
+                nlayers=32,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=32, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=32, bins=16),
+                ],
+            )
+        # TODO(Jiayi): needs tuning for better quality
+        elif model_name in family_9b:
+            return CacheGenConfig(
+                nlayers=40,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=40, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=40, bins=16),
+                ],
+            )
+        else:
+            try:
+                config = AutoConfig.from_pretrained(model_name)
+                # Default name caught by num_hidden_layers
+                if config.num_hidden_layers is None:
+                    raise ValueError(
+                        f"num_hidden_layers is None for model {model_name}"
+                    )
+                if config.num_hidden_layers < 10:
+                    return CacheGenConfig(
+                        nlayers=config.num_hidden_layers,
+                        kspecs=[
+                            QuantizationSpec(
+                                start_layer=0,
+                                end_layer=config.num_hidden_layers,
+                                bins=32,
+                            ),
+                        ],
+                        vspecs=[
+                            QuantizationSpec(
+                                start_layer=0,
+                                end_layer=config.num_hidden_layers,
+                                bins=32,
+                            ),
+                        ],
+                    )
+                else:
+                    return CacheGenConfig(
+                        nlayers=config.num_hidden_layers,
+                        kspecs=[
+                            QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                            QuantizationSpec(
+                                start_layer=10,
+                                end_layer=config.num_hidden_layers,
+                                bins=16,
+                            ),
+                        ],
+                        vspecs=[
+                            QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                            QuantizationSpec(
+                                start_layer=2,
+                                end_layer=config.num_hidden_layers,
+                                bins=16,
+                            ),
+                        ],
+                    )
+            except Exception as e:
+                raise ValueError(
+                    f"Model {model_name} not supported by CacheGenConfig"
+                ) from e
+
+
+@dataclass
+class CacheGenEncoderOutput:
+    # TODO: maybe use numpy array so that we can directly tobytes() and
+    # frombuffer() to have a better performance
+    bytestream: bytes
+    start_indices: torch.Tensor
+    cdf: torch.Tensor
+    max_tensors_key: torch.Tensor
+    max_tensors_value: torch.Tensor
+    num_heads: int
+    head_size: int
+
+    def __getitem__(self, key: str) -> int:
+        return getattr(self, key)
+
+    def to_bytes(self) -> bytes:
+        """Save the output to a file"""
+        with io.BytesIO() as f:
+            # torch.save(self, f)
+            pickle.dump(self, f)
+            return f.getvalue()
+
+    @staticmethod
+    def from_bytes(bs: bytes) -> "CacheGenEncoderOutput":
+        with io.BytesIO(bs) as f:
+            return pickle.load(f)
+
+
+@dataclass
+class CacheGenGPUBytestream:
+    bytestream: torch.Tensor
+    bytestream_lengths: torch.Tensor  # [nlayers, nchannels, bytestream_length]
+    ntokens: int
+
+    def __getitem__(self, key: str) -> int:
+        return getattr(self, key)
+
+
+@dataclass
+class CacheGenGPUEncoderOutput:
+    data_chunks: List[CacheGenGPUBytestream]
+    cdf: torch.Tensor
+    max_tensors_key: torch.Tensor
+    max_tensors_value: torch.Tensor
+    num_heads: int
+    head_size: int
+
+    def __getitem__(self, key: str) -> int:
+        return getattr(self, key)
+
+    @_lmcache_nvtx_annotate
+    def to_bytes(self) -> bytes:
+        """Save the output to a file"""
+        with io.BytesIO() as f:
+            pickle.dump(self, f)
+            return f.getvalue()
+
+    @staticmethod
+    @_lmcache_nvtx_annotate
+    def from_bytes(bs: bytes) -> "CacheGenGPUEncoderOutput":
+        with io.BytesIO(bs) as f:
+            return pickle.load(f)
+
+    def debug_print_device(self):
+        logger.debug(f"bytestream device: {self.data_chunks[0].bytestream.device}")
+        logger.debug(
+            f"bytestream_lengths device: "
+            f"{self.data_chunks[0].bytestream_lengths.device}"
+        )
+        logger.debug(f"cdf device: {self.cdf.device}")
+        logger.debug(f"max_tensors_key device: {self.max_tensors_key.device}")
+        logger.debug(f"max_tensors_value device: {self.max_tensors_value.device}")
diff --git a/lmcache/storage_backend/serde/cachegen_decoder.py b/lmcache/storage_backend/serde/cachegen_decoder.py
new file mode 100644
index 0000000..7e02e63
--- /dev/null
+++ b/lmcache/storage_backend/serde/cachegen_decoder.py
@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.logging import init_logger
+from lmcache.storage_backend.serde.cachegen_basics import (
+    CacheGenConfig,
+    CacheGenGPUBytestream,
+    CacheGenGPUEncoderOutput,
+)
+from lmcache.storage_backend.serde.serde import Deserializer
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+import lmcache.c_ops as lmc_ops
+import lmcache.storage_backend.serde.cachegen_basics as CGBasics
+
+logger = init_logger(__name__)
+
+
+@_lmcache_nvtx_annotate
+def quant(bins: int, xq: torch.Tensor, max1: float):
+    C = bins // 2 - 1
+    x = xq / C * max1
+    return x
+
+
+def do_dequantize(t: torch.Tensor, bins: torch.Tensor, maxtensors: torch.Tensor):
+    """
+    t: [nlayers, ntokens, nchannels]
+    bins: [nlayers]
+    maxtensors: [nlayers, ntokens, 1]
+    """
+    C = (bins // 2 - 1)[:, None, None]
+    t = t - C
+    t = t / C
+    t = t * maxtensors
+    return t
+
+
+@_lmcache_nvtx_annotate
+def recombine_bytes(bytes_tensor, output_lengths) -> torch.Tensor:
+    output_buffer_size = CGBasics.CACHEGEN_GPU_MAX_TOKENS_PER_CHUNK
+    offsets = output_lengths.flatten().cumsum(0).roll(1).reshape(output_lengths.shape)
+    offsets[0][0] = 0
+    indexes = torch.arange(output_buffer_size, device=offsets.device).tile(
+        (output_lengths.shape[0], output_lengths.shape[1], 1)
+    )
+    final_indexes = (indexes + offsets[:, :, None]).clamp(max=len(bytes_tensor) - 1)
+    return bytes_tensor[final_indexes]
+
+
+@_lmcache_nvtx_annotate
+def decode_chunk(
+    cdf: torch.Tensor,
+    data_chunk: CacheGenGPUBytestream,
+    target_buffer: torch.Tensor,
+) -> None:
+    """
+    Write the decode output in target_buffer
+    Expected shape: [nlayers (kv in total), ntokens, nchannels]
+    """
+    bytes_tensor = data_chunk.bytestream
+    length_prefsum = (
+        data_chunk.bytestream_lengths.flatten()
+        .cumsum(0)
+        .reshape(data_chunk.bytestream_lengths.shape)
+    )
+    lmc_ops.decode_fast_prefsum(cdf, bytes_tensor, length_prefsum, target_buffer)
+
+
+@_lmcache_nvtx_annotate
+def decode_function_gpu(
+    cdf: torch.Tensor,
+    data_chunks: List[CacheGenGPUBytestream],
+    layers_in_key: int,
+    chunk_size: int,
+    output: torch.Tensor,
+):
+    # TODO: dtype and shape -- still have 128 and 8
+    """
+    Given the path to the encoded KV bytestream, decode the KV cache
+
+    Inputs:
+        cdf: the cdf tensor, in shape [2 * nlayers, nchannels, bins + 1]
+        data_chunks: the data_chunks in the encoder's output
+        layers_in_key: number of layers in K (or V)
+        (K/V should have the same number of layers)
+        chunk_size: the chunk_size
+        output: output buffer, in shape [ntokens, 2 * nlayers * nchannels]
+
+    Outputs:
+        key: the decoded key tensor in the shape of (layers, tokens, nchannels)
+        value: the decoded value tensor in the shape of
+        (layers, tokens, nchannels)
+    """
+    nlayers, nchannels, _ = cdf.shape
+    output = output.reshape((nlayers, chunk_size, nchannels))
+
+    start = 0
+    for data_chunk in data_chunks:
+        end = start + data_chunk.ntokens
+        decode_chunk(cdf, data_chunk, output[:, start:end, :])
+        start = end
+
+    out = output.reshape((2, layers_in_key, chunk_size, nchannels))
+    key, value = out.float()
+
+    return key, value
+
+
+class CacheGenDeserializer(Deserializer):
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        dtype,
+    ):
+        self.dtype = dtype
+        self.cachegen_config = CacheGenConfig.from_model_name(metadata.model_name)
+        self.chunk_size = config.chunk_size
+        self.output_buffer: Optional[torch.Tensor] = None
+        self.key_bins = self.make_key_bins(self.cachegen_config)
+        self.value_bins = self.make_value_bins(self.cachegen_config)
+
+    def make_key_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.kspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    def make_value_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.vspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    def get_output_buffer(self, nlayers: int, nchannels: int, ntokens: int):
+        if (
+            self.output_buffer is None
+            or self.output_buffer.shape[1] != 2 * nlayers * nchannels
+        ):
+            self.output_buffer = torch.zeros(
+                (self.chunk_size, 2 * nlayers * nchannels), dtype=torch.uint8
+            ).to(torch_device_type)
+        return self.output_buffer[:ntokens, :]
+
+    @_lmcache_nvtx_annotate
+    def from_bytes(self, bs: bytes) -> torch.Tensor:
+        encoder_output = CacheGenGPUEncoderOutput.from_bytes(bs)
+        encoder_output.max_tensors_key = encoder_output.max_tensors_key.to(
+            torch_device_type
+        )
+        encoder_output.max_tensors_value = encoder_output.max_tensors_value.to(
+            torch_device_type
+        )
+
+        ntokens = encoder_output.max_tensors_key.shape[1]
+        layers_in_key = encoder_output.max_tensors_key.shape[0]
+        key, value = decode_function_gpu(
+            encoder_output.cdf,
+            encoder_output.data_chunks,
+            layers_in_key,
+            ntokens,
+            self.get_output_buffer(
+                encoder_output.cdf.shape[0] // 2,
+                encoder_output.cdf.shape[1],
+                ntokens,
+            ),
+        )
+
+        # Temporary fix for #83: change the device of key_bins and value_bins
+        # to the device of key and value
+        # This requires a long-term fix in the future. Currently,
+        # CacheGenGPUEncoderOutput has implicit device in itself.
+        # More specifically, if the encoder encodes the tensor on GPU0, the
+        # from_bytes will also return a tensor on GPU0
+        # We may want to dynamically configure the device based on config and
+        # metadata in the future
+        if self.key_bins.device != key.device:
+            self.key_bins = self.key_bins.to(key.device)
+
+        if self.value_bins.device != value.device:
+            self.value_bins = self.value_bins.to(value.device)
+
+        key = do_dequantize(key, self.key_bins, encoder_output.max_tensors_key)
+        value = do_dequantize(value, self.value_bins, encoder_output.max_tensors_value)
+        """ merge key and value back and reshape """
+        nlayers, ntokens, nchannels = key.shape
+        blob = torch.stack([key, value])  # [2, nlayers, ntokens, nchannels]
+        blob = blob.reshape(
+            (
+                2,
+                nlayers,
+                ntokens,
+                encoder_output.num_heads,
+                encoder_output.head_size,
+            )
+        )
+
+        return blob.permute((1, 0, 2, 3, 4)).to(
+            self.dtype
+        )  # [nlayers, 2, ntokens, num_heads, head_size]
+        # huggingface
+        # return blob.permute((1, 0, 3, 2, 4)).to(
+        #     self.dtype
+        # )  # [nlayers, 2, num_heads, ntokens, head_size]
diff --git a/lmcache/storage_backend/serde/cachegen_encoder.py b/lmcache/storage_backend/serde/cachegen_encoder.py
new file mode 100644
index 0000000..24a4d27
--- /dev/null
+++ b/lmcache/storage_backend/serde/cachegen_encoder.py
@@ -0,0 +1,397 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict, Tuple
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.storage_backend.serde.cachegen_basics import (
+    CacheGenConfig,
+    CacheGenGPUBytestream,
+    CacheGenGPUEncoderOutput,
+)
+from lmcache.storage_backend.serde.serde import Serializer
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+import lmcache.c_ops as lmc_ops
+import lmcache.storage_backend.serde.cachegen_basics as CGBasics
+
+logger = init_logger(__name__)
+
+
+@_lmcache_nvtx_annotate
+def torch_quant(bins: int, qA: torch.Tensor) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    Quantize a float tensor to fixed number of bins
+
+    Input:
+        bins: number of bins
+        qA: the input tensor
+
+    Returns:
+        xq: the quantized tensor, in float32
+        max1: the maximum value of the tensor
+    """
+    MAX = bins // 2 - 1
+    C = MAX
+    max1 = torch.amax(torch.abs(qA), dim=-1, keepdim=True)
+    xq = torch.round(qA * (C / max1)).to(torch.int8)
+
+    return xq, max1
+
+
+@_lmcache_nvtx_annotate
+def torch_quant_vectorized(
+    bins: torch.Tensor, input_groups: torch.Tensor
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """
+    Quantize each group of a tensor to fixed number of bins
+
+    Input:
+        bins: number of bins for different layers, with shape [nlayer]
+        input_groups: with shape [nlayers, ntokens, nchannels]
+
+    Returns:
+        quantized groups: [nlayers, ntokens, nchannels]
+        maxes: [nlayers, ntokens, 1]
+    """
+    MAX = (bins // 2 - 1)[:, None, None]  # shape [nlayers, 1, 1]
+    max1 = torch.amax(
+        torch.abs(input_groups), dim=-1, keepdim=True
+    )  # shape [nlayers, ntokens, 1]
+    factor = MAX / max1  # shape [nlayers, ntokens, 1]
+    xq = torch.round(input_groups * factor + MAX).to(
+        torch.int8
+    )  # shape [nlayers, ntokens, nchannels]
+
+    return xq, max1
+
+
+@_lmcache_nvtx_annotate
+def concat_max(max1):
+    """
+    Given a dict of max tensors, concatenate them into a single tensor
+    """
+    # TODO: this function can be optimized, we don't really need this
+    maxes = []
+    for i in range(len(max1)):
+        maxes.append(max1[i].unsqueeze(0))
+    return torch.cat(maxes, dim=0)
+
+
+def _split_kv(tensor: torch.Tensor) -> Tuple[torch.Tensor, ...]:
+    """
+    Split a blob KV tensor to K and V tensors with the merged heads
+
+    Input:
+        tensor: the KV tensor with shape
+            [num_layers, 2, num_tokens, num_heads, head_size]
+
+    Returns:
+        K and V tensors with shape
+            [num_layers, num_tokens, num_channels]
+    """
+    num_layers, _, num_tokens, num_heads, head_size = tensor.shape
+    return torch.unbind(
+        tensor.reshape(num_layers, 2, num_tokens, num_heads * head_size), dim=1
+    )
+
+
+@_lmcache_nvtx_annotate
+def _convert_to_int_and_normalize(cdf_float, needs_normalization):
+    """
+    Convert floatingpoint CDF to integers. See README for more info.
+
+    The idea is the following:
+    When we get the cdf here, it is (assumed to be) between 0 and 1, i.e,
+      cdf in [0, 1)
+    (note that 1 should not be included.)
+    We now want to convert this to int16 but make sure we do not get
+    the same value twice, as this would break the arithmetic coder
+    (you need a strictly monotonically increasing function).
+    So, if needs_normalization==True, we multiply the input CDF
+    with 2**16 - (Lp - 1). This means that now,
+      cdf in [0, 2**16 - (Lp - 1)].
+    Then, in a final step, we add an arange(Lp), which is just a line with
+    slope one. This ensure that for sure, we will get unique, strictly
+    monotonically increasing CDFs, which are in [0, 2**16)
+    """
+    PRECISION = 16
+    Lp = cdf_float.shape[-1]
+    factor = torch.tensor(2, dtype=torch.float32, device=cdf_float.device).pow_(
+        PRECISION
+    )
+    new_max_value = factor
+    if needs_normalization:
+        new_max_value = new_max_value - (Lp - 1)
+    cdf_float = cdf_float.mul(new_max_value)
+    cdf_float = cdf_float.round()
+    cdf = cdf_float.to(dtype=torch.int16, non_blocking=True)
+    if needs_normalization:
+        r = torch.arange(Lp, dtype=torch.int16, device=cdf.device)
+        cdf.add_(r)
+    return cdf
+
+
+class CacheGenEncoderImpl:
+    def __init__(self, **kwargs) -> None:
+        """
+        Fields:
+        - fp_kv:
+            should be a tensor of shape (num_layers, num_tokens, num_channels)
+        - fp_v:
+            should be a tensor of shape (num_layers, num_tokens, num_channels)
+        """
+        self.fp_k = kwargs["fp_k"]
+        self.fp_v = kwargs["fp_v"]
+
+        self.quantized_key: Dict[int, torch.Tensor] = {}
+        self.max_tensors_key: Dict[int, torch.Tensor] = {}
+        self.quantized_value: Dict[int, torch.Tensor] = {}
+        self.max_tensors_value: Dict[int, torch.Tensor] = {}
+        self.config = kwargs["config"]
+
+    @_lmcache_nvtx_annotate
+    def quantize(self):
+        """Quantize the key and value tensors
+        (self.fp_k and self.fp_v)
+        """
+        for layer in range(len(self.fp_k)):
+            if layer < self.config["key_first_layers"]:
+                bins = self.config["key_first_bins"]
+            elif layer < self.config["key_second_layers"]:
+                bins = self.config["key_second_bins"]
+            else:
+                bins = self.config["key_third_bins"]
+
+            tmp = torch_quant(bins, self.fp_k[layer].float())
+            self.quantized_key[layer] = tmp[0] + bins // 2 - 1
+            self.max_tensors_key[layer] = tmp[1]
+
+        for layer in range(len(self.fp_v)):
+            if layer < self.config["value_first_layers"]:
+                bins = self.config["value_first_bins"]
+            else:
+                bins = self.config["value_second_bins"]
+            tmp = torch_quant(bins, self.fp_v[layer].float())
+            self.quantized_value[layer] = tmp[0] + bins // 2 - 1
+            self.max_tensors_value[layer] = tmp[1]
+
+    @_lmcache_nvtx_annotate
+    def compute_cdf(self, is_key):
+        """
+        Compute the CDF based on the quantized tensors
+        Field:
+        - start_layer: the start layer to compute the CDF
+        - end_layer: the end layer to compute the CDF
+        """
+        # TODO: Add start_index here
+        channels = self.fp_k[0].shape[-1]
+
+        def process_batch(X, max_val):
+            """
+            input shape should be [channels, tokens]
+            """
+            nchannels, ntokens = X.shape
+            one_hot = torch.nn.functional.one_hot(X.long(), num_classes=max_val + 1).to(
+                torch.float32
+            )  # Use float32 to avoid integer overflow
+            counts = one_hot.sum(dim=1) / ntokens
+            ret = torch.cumsum(counts, dim=1).roll(1)
+            ret[:, 0] = 0
+            return ret
+
+        def process_layers(X, max_val):
+            """
+            x is a iterator of dict values
+            each element's shape is [tokens, channels]
+            """
+            results = []
+            for x in X:
+                """do permute here"""
+                batch_counts = process_batch(
+                    x.to(torch_device_type).permute(1, 0), max_val
+                )
+                results.append(batch_counts)
+
+            final_counts = torch.cat(results, dim=0)
+
+            return final_counts
+
+        if is_key:
+            X = self.quantized_key.values()
+        else:
+            X = self.quantized_value.values()
+        value_range = 32
+        cdfs = process_layers(X, value_range)  # 4096 is batch size, ==> 18GB GPU memory
+        final_cdf = cdfs.reshape((len(self.fp_k), channels, value_range + 1))
+
+        return final_cdf
+
+
+@_lmcache_nvtx_annotate
+def collect_bytes(output_buffer, output_lengths) -> torch.Tensor:
+    """
+    Collect a byte tensor from the output_buffer + output_lengths
+    """
+    output_buffer_size = output_buffer.shape[-1]
+    flattened_lengths = output_lengths.flatten()
+    flattened_buffer = output_buffer.flatten()
+    summed_length = (output_buffer_size - flattened_lengths).cumsum(0)
+    summed_length = summed_length.roll(1)
+    summed_length[0] = 0
+    indexes = summed_length.repeat_interleave(flattened_lengths)
+    indexes = indexes + torch.arange(len(indexes), device=indexes.device)
+    return flattened_buffer[indexes]
+
+
+@_lmcache_nvtx_annotate
+def encode_ntokens(
+    cdf_int, encode_input, output_buffer, output_lengths
+) -> torch.Tensor:
+    """Encode a batch of ntokens.
+
+    :param cdf_int: int16 tensor on GPU with shape [nlayers, nchannels, Lp]
+    :param encode_input: int8 tensor on GPU with shape
+    :param [nlayers, ntokens, nchannels]
+    :param output_buffer: uint8 tensor on GPU with shape
+        [nlayers, nchannels, BUFFER_SIZE]
+    :param output_lengths: int32 tensor on GPU with shape [nlayers, nchannels]
+
+    :return byte_tensor: the byte tensor
+    """
+    lmc_ops.encode_fast_new(
+        cdf_int,
+        encode_input,
+        output_buffer,
+        output_lengths,
+    )
+    byte_tensor = collect_bytes(output_buffer, output_lengths)
+    return byte_tensor
+    # return byte_tensor.cpu().numpy().tobytes()
+
+
+@_lmcache_nvtx_annotate
+def encode_function(
+    kv: torch.Tensor,
+    config: CacheGenConfig,
+    key_bins: torch.Tensor,
+    value_bins: torch.Tensor,
+    chunk_size: int,
+) -> CacheGenGPUEncoderOutput:
+    """
+    Given the path to the original key value cache, encode the KV cache
+    """
+    num_heads, head_size = kv.shape[-2:]
+    fp_k, fp_v = _split_kv(kv)
+    nchannels = num_heads * head_size
+    nlayers = fp_k.shape[0] + fp_v.shape[0]
+
+    new_key, max_tensors_key = torch_quant_vectorized(key_bins, fp_k)
+    new_value, max_tensors_value = torch_quant_vectorized(value_bins, fp_v)
+    encode_input = torch.cat((new_key, new_value), dim=0).reshape(
+        nlayers, chunk_size, nchannels
+    )
+
+    new_cdf_key = lmc_ops.calculate_cdf(new_key, int(key_bins.max()))
+    new_cdf_value = lmc_ops.calculate_cdf(new_value, int(value_bins.max()))
+    cdf_int = torch.cat([new_cdf_key, new_cdf_value])
+
+    output_buffer = torch.zeros(
+        (nlayers, nchannels, CGBasics.CACHEGEN_GPU_MAX_TOKENS_PER_CHUNK),
+        dtype=torch.uint8,
+        device=encode_input.device,
+    )
+    output_lengths = torch.zeros(
+        (nlayers, nchannels), dtype=torch.int32, device=encode_input.device
+    )
+
+    data_chunks = []
+    for i in range(0, chunk_size, CGBasics.CACHEGEN_GPU_MAX_TOKENS_PER_CHUNK):
+        start = i
+        end = min(i + CGBasics.CACHEGEN_GPU_MAX_TOKENS_PER_CHUNK, chunk_size)
+        bytestream = encode_ntokens(
+            cdf_int,
+            encode_input[:, start:end, :],
+            output_buffer,
+            output_lengths,
+        )
+        data_chunks.append(
+            CacheGenGPUBytestream(
+                bytestream=bytestream,
+                bytestream_lengths=output_lengths.clone(),
+                ntokens=end - start,
+            )
+        )
+
+    return CacheGenGPUEncoderOutput(
+        data_chunks,
+        cdf_int,
+        max_tensors_key=max_tensors_key,
+        max_tensors_value=max_tensors_value,
+        num_heads=num_heads,
+        head_size=head_size,
+    )
+
+
+class CacheGenSerializer(Serializer):
+    def __init__(self, config: LMCacheEngineConfig, metadata: LMCacheMetadata):
+        self.cachegen_config = CacheGenConfig.from_model_name(metadata.model_name)
+        self.chunk_size = config.chunk_size
+        self.key_bins = self.make_key_bins(self.cachegen_config)
+        self.value_bins = self.make_value_bins(self.cachegen_config)
+
+    def make_key_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.kspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    def make_value_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.vspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    @_lmcache_nvtx_annotate
+    def to_bytes(self, tensor: torch.Tensor) -> bytes:
+        """
+        Serialize a pytorch tensor to bytes. The serialized bytes should contain
+        both the data and the metadata (shape, dtype, etc.) of the tensor.
+
+        Input:
+            t: the input pytorch tensor, can be on any device, in any shape,
+               with any dtype
+
+        Returns:
+            bytes: the serialized bytes
+        """
+        # Temporary fix for issue #83: encoder will have the default device 0
+        # on all the ray workers. Need to set it to the correct device.
+        # Also need to figure out why this happens.
+        if torch_dev.current_device() != tensor.device.index:
+            torch_dev.set_device(tensor.device)
+        if tensor.device != self.key_bins.device:
+            self.key_bins = self.key_bins.to(tensor.device)
+        if tensor.device != self.value_bins.device:
+            self.value_bins = self.value_bins.to(tensor.device)
+
+        # TODO: permute is expensive here, need a better way to do it at lower
+        # level
+        # huggingface:
+        # tensor = tensor.permute(0, 1, 3, 2, 4)
+        """ expecting a tensor of shape 
+        [num_layers, 2, num_tokens, num_heads, head_size] """
+        ntokens = tensor.shape[2]
+        output_dict = encode_function(
+            tensor.to(torch_device_type),
+            self.cachegen_config,
+            self.key_bins,
+            self.value_bins,
+            ntokens,
+        )
+        return output_dict.to_bytes()
diff --git a/lmcache/storage_backend/serde/serde.py b/lmcache/storage_backend/serde/serde.py
new file mode 100644
index 0000000..b51801d
--- /dev/null
+++ b/lmcache/storage_backend/serde/serde.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import abc
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import _lmcache_nvtx_annotate
+
+logger = init_logger(__name__)
+
+
+class Serializer(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def to_bytes(self, t: torch.Tensor) -> bytes:
+        """
+        Serialize a pytorch tensor to bytes. The serialized bytes should contain
+        both the data and the metadata (shape, dtype, etc.) of the tensor.
+
+        Input:
+            t: the input pytorch tensor, can be on any device, in any shape,
+               with any dtype
+
+        Returns:
+            bytes: the serialized bytes
+        """
+        raise NotImplementedError
+
+
+class SerializerDebugWrapper(Serializer):
+    def __init__(self, s: Serializer):
+        self.s = s
+
+    def to_bytes(self, t: torch.Tensor) -> bytes:
+        start = time.perf_counter()
+        bs = self.s.to_bytes(t)
+        end = time.perf_counter()
+
+        logger.debug(f"Serialization took {end - start:.2f} seconds")
+        return bs
+
+
+class Deserializer(metaclass=abc.ABCMeta):
+    def __init__(self, dtype):
+        self.dtype = dtype
+
+    @abc.abstractmethod
+    def from_bytes(self, bs: bytes) -> torch.Tensor:
+        """
+        Deserialize a pytorch tensor from bytes.
+
+        Input:
+            bytes: a stream of bytes
+
+        Output:
+            torch.Tensor: the deserialized pytorch tensor
+        """
+        raise NotImplementedError
+
+
+class DeserializerDebugWrapper(Deserializer):
+    def __init__(self, d: Deserializer):
+        self.d = d
+
+    @_lmcache_nvtx_annotate
+    def from_bytes(self, t: bytes) -> torch.Tensor:
+        start = time.perf_counter()
+        ret = self.d.from_bytes(t)
+        end = time.perf_counter()
+
+        logger.debug(f"Deserialization took {(end - start) * 1000:.2f} ms")
+        return ret
diff --git a/lmcache/tools/__init__.py b/lmcache/tools/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/tools/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/tools/cache_simulator/README.md b/lmcache/tools/cache_simulator/README.md
new file mode 100644
index 0000000..dd8df9e
--- /dev/null
+++ b/lmcache/tools/cache_simulator/README.md
@@ -0,0 +1,392 @@
+# Cache Simulator
+
+The cache simulator replays recorded LMCache lookup events to measure **token cache hit rate** — the fraction of input tokens served from the KV cache rather than recomputed. It answers questions like:
+
+- What hit rate can I expect for my workload at a given cache size?
+- How much cache memory do I need to reach 80% / 90% hit rate?
+- Which requests benefit most from caching?
+
+## Table of Contents
+
+- [How it Works](#how-it-works)
+- [Quick Start](#quick-start)
+- [Step 1: Enable Lookup Hash Logging](#step-1-enable-lookup-hash-logging)
+- [Step 2: Run the Simulator](#step-2-run-the-simulator)
+- [Step 3: Plot Hit Rate vs Capacity](#step-3-plot-hit-rate-vs-capacity)
+- [Understanding the Output](#understanding-the-output)
+- [CLI Reference](#cli-reference)
+- [For Developers](#for-developers)
+
+---
+
+## How it Works
+
+LMCache splits each request's KV cache into fixed-size **chunks** and identifies them by hash. The simulator replays those hashes through a simulated LRU cache to predict hit rate without running the actual model.
+
+### Token hit rate
+
+The primary metric is **token hit rate**, not chunk hit rate:
+
+```
+token_hit_rate = total_hit_tokens / total_tokens
+```
+
+Where:
+
+- `total_tokens` is the sum of `seq_len` across all requests — this includes **tail tokens** (the partial chunk at the end of each sequence that does not fill a complete chunk). Tail tokens are always a miss because LMCache only caches complete chunks.
+- `total_hit_tokens` is the number of tokens covered by a **continuous hit prefix** at the start of each request: if the first *k* chunks are all cache hits, that contributes `k × chunk_size` hit tokens.
+
+This is the same definition used by the LMCache server itself.
+
+### Prefix caching semantics
+
+The simulator enforces the same prefix rule as LMCache: a chunk is only counted as a hit if it **and every chunk before it** in the request are cached. The first miss breaks the prefix — subsequent chunks are not counted as hits even if they happen to be in cache.
+
+### Cache model
+
+- **Eviction policy:** LRU (Least Recently Used)
+- **Cache key:** chunk hash (hex string, opaque)
+- **Capacity unit:** bytes of KV cache memory
+
+---
+
+## Quick Start
+
+```bash
+# 1. Collect logs from a live server (see Step 1 below)
+lmcache server --lookup-hash-log-dir /data/lmcache/lookup_hashes ...
+
+# 2. Simulate at a fixed capacity — prints text report and saves a PNG chart
+lmcache tool cache-simulator simulate \
+    -i /data/lmcache/lookup_hashes \
+    --cache-capacity-gib 64 \
+    -o stats.png
+
+# 3. Sweep across capacities to find the right cache size
+lmcache tool cache-simulator sweep \
+    -i /data/lmcache/lookup_hashes \
+    --min-capacity-gib 1 \
+    --max-capacity-gib 512 \
+    --points 30 \
+    -o sweep.png
+```
+
+---
+
+## Step 1: Enable Lookup Hash Logging
+
+Start the LMCache server with `--lookup-hash-log-dir` pointing to a writable directory:
+
+```bash
+lmcache server \
+    --host 0.0.0.0 \
+    --port 8080 \
+    --chunk-size 256 \
+    --lookup-hash-log-dir /data/lmcache/lookup_hashes \
+    --lookup-hash-log-rotation-interval 21600 \
+    --lookup-hash-log-rotation-max-size 104857600 \
+    --lookup-hash-log-max-files 100
+```
+
+The server will write rotating JSONL files to that directory. Each line is one request:
+
+```json
+{
+  "timestamp": 1711929600.123,
+  "request_id": "req-001",
+  "model_name": "DeepSeek-V3",
+  "chunk_size": 256,
+  "seq_len": 8192,
+  "dtypes": ["float8_e4m3fn"],
+  "shapes": [[32, 256, 128]],
+  "chunk_hashes": ["0xabcd1234...", "0xef567890...", ...]
+}
+```
+
+| Field | Description |
+|---|---|
+| `timestamp` | Unix timestamp of the lookup |
+| `request_id` | Unique request identifier |
+| `model_name` | Model being served |
+| `chunk_size` | Tokens per chunk |
+| `seq_len` | Total input tokens (including tail) |
+| `dtypes` | KV tensor data types |
+| `shapes` | KV tensor shapes (used to compute bytes/chunk) |
+| `chunk_hashes` | Ordered list of full-chunk hashes (hex strings) |
+
+Note: `chunk_hashes` only covers **complete** chunks. The tail tokens (`seq_len mod chunk_size`) are not represented — they are implicitly always a miss.
+
+---
+
+## Step 2: Run the Simulator
+
+```bash
+lmcache tool cache-simulator simulate \
+    -i /data/lmcache/lookup_hashes \
+    --cache-capacity-gib 64 \
+    -o stats.png
+```
+
+This prints a full text report to the terminal **and** saves a 7-panel statistics chart to `stats.png`. The `kv_bytes_per_chunk` value is auto-detected from the `shapes` and `dtypes` fields of the first event. You can override it:
+
+```bash
+lmcache tool cache-simulator simulate \
+    -i /data/lmcache/lookup_hashes \
+    --cache-capacity-gib 64 \
+    --kv-bytes-per-chunk 20971520 \
+    -o stats.png
+```
+
+To analyse only one model when the logs contain multiple:
+
+```bash
+lmcache tool cache-simulator simulate \
+    -i /data/lmcache/lookup_hashes \
+    --cache-capacity-gib 64 \
+    --model DeepSeek-V3 \
+    -o stats.png
+```
+
+### Example text output
+
+```
+============================================================
+Aggregate
+============================================================
+  Requests processed  : 9,161
+  Total tokens        : 449,114,449
+  Hit tokens          : 268,330,752
+  Miss tokens         : 180,783,697
+  Token hit rate      : 59.75%
+  Cache capacity      : 64.00 GiB  (3,276 chunks × 20,971,520 bytes/chunk)
+  Cache occupancy     : 3,276 / 3,276 chunks
+
+============================================================
+Stat 1 — Per-request token hit rate distribution
+============================================================
+  Requests with 0% hit rate   : 38 (0.4%)
+  Requests with 100% hit rate : 3 (0.0%)
+  Mean                        : 80.82%
+  p50                         : 90.59%
+  p90                         : 98.85%
+  p99                         : 99.93%
+...
+```
+
+### Example statistics chart
+
+![Simulation statistics chart](docs/simulate_example.png)
+
+---
+
+## Step 3: Plot Hit Rate vs Capacity
+
+The plot tool sweeps across a log-spaced range of cache sizes and shows how hit rate changes with capacity — the key curve for capacity planning.
+
+```bash
+lmcache tool cache-simulator sweep \
+    -i /data/lmcache/lookup_hashes \
+    --min-capacity-gib 1 \
+    --max-capacity-gib 512 \
+    --points 30 \
+    -o sweep.png
+```
+
+This prints a table and saves a PNG:
+
+```
+    Capacity (GiB)    Hit rate
+--------------------------------
+             1.000     29.18%
+             2.151     36.93%
+             9.257     51.44%
+            39.830     63.51%
+           118.993     68.96%
+           512.000     78.58%
+```
+
+The x-axis is in GiB (log scale by default). Use `--linear` for a linear scale.
+
+### Example capacity sweep chart
+
+![Hit rate vs capacity chart](docs/sweep_example.png)
+
+---
+
+## Understanding the Output
+
+### Text report statistics
+
+| Stat | What it measures |
+|---|---|
+| **Aggregate** | Overall token hit rate, capacity utilisation, eviction count |
+| **Stat 1** | Per-request hit rate distribution (mean, percentiles, 0%/100% counts) |
+| **Stat 2** | Hit prefix length per request in chunks (how far the prefix match extends) |
+| **Stat 3** | Chunk reuse count distribution (how many times each unique chunk was hit) |
+| **Stat 4** | Rolling cumulative hit rate over time (does the cache warm up quickly?) |
+| **Stat 5** | Total evictions (non-zero means the cache was full and chunks were displaced) |
+| **Stat 6** | Global span distribution — chunks processed between when a chunk was last stored and when it was hit again (measures temporal locality) |
+| **Stat 7** | Cache position at hit time (0 = MRU, max = LRU; low values mean recently-used chunks are being hit, high values indicate stale hits that nearly got evicted) |
+
+### Chart panels (stats.png)
+
+The saved PNG contains the same seven statistics as visual histograms:
+
+| Panel | Chart |
+|---|---|
+| **1** | Per-request token hit rate histogram + hit/miss request pie inset |
+| **1b** | Same zoomed into the 97–100% range |
+| **2** | Hit prefix length per request + hit/miss token pie inset |
+| **3** | Chunk reuse count histogram (x-axis capped at 100) |
+| **4** | Rolling cumulative token hit rate over time |
+| **5** | Input length per request (tokens) |
+| **6** | Global span distribution |
+| **7** | Cache position at hit time |
+
+---
+
+## CLI Reference
+
+### `simulate` — single-run report and chart
+
+```
+lmcache tool cache-simulator simulate [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `-i / --input PATH [PATH ...]` | required | JSONL files or directories (directories are globbed for `lookup_hashes_*.jsonl`) |
+| `--cache-capacity-gib GiB` | required | Cache size in gibibytes |
+| `-o / --output FILE` | `cache_stats.png` | Output image path |
+| `-n / --max-samples N` | all | Truncate to N events after sorting by timestamp |
+| `--model NAME` | all | Filter by `model_name` (exact match) |
+| `--kv-bytes-per-chunk BYTES` | auto | KV bytes per chunk; auto-computed from first event if omitted |
+
+### `sweep` — capacity sweep and plot
+
+```
+lmcache tool cache-simulator sweep [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `-i / --input PATH [PATH ...]` | required | JSONL files or directories |
+| `--min-capacity-gib GiB` | `0.5` | Lower bound of capacity sweep |
+| `--max-capacity-gib GiB` | `500` | Upper bound of capacity sweep |
+| `--points N` | `30` | Number of log-spaced capacity samples |
+| `--linear` | off | Use linear x-axis instead of log scale |
+| `-o / --output FILE` | `hit_rate_vs_capacity.png` | Output image path |
+| `-n / --max-samples N` | all | Truncate events |
+| `--model NAME` | all | Filter by model name |
+| `--kv-bytes-per-chunk BYTES` | auto | KV bytes per chunk |
+
+### `gen-dataset` — generate vllm bench serve dataset
+
+```
+lmcache tool cache-simulator gen-dataset [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `-i / --input PATH [PATH ...]` | required | JSONL files or directories |
+| `--tokenizer PATH` | required | HuggingFace tokenizer path or name |
+| `--output-len N` | `128` | `output_tokens` per request |
+| `-o / --output FILE` | `bench_dataset.jsonl` | Output JSONL path |
+| `-n / --max-samples N` | all | Truncate events |
+| `--model NAME` | all | Filter by model name |
+
+### How token generation works
+
+1. A *safe vocabulary* is built from the tokenizer: token IDs that decode to printable text and round-trip stably through `encode(decode([id])) == [id]`. Tokens with a leading space are preferred to prevent BPE merges at chunk boundaries.
+2. Each unique chunk hash is mapped deterministically to `chunk_size` token IDs by seeding a PRNG with `SHA-256(hash)`. The same hash always produces the same tokens.
+3. Tail tokens (`seq_len mod chunk_size`) use a per-request seed so they are never accidentally shared across requests (matching LMCache's behaviour of never caching partial chunks).
+4. The full token list is decoded to text and written as the `"prompt"` field. `"output_tokens"` is set to `--output-len`.
+
+---
+
+## For Developers
+
+### Package layout
+
+```
+lmcache/tools/cache_simulator/
+    __init__.py             — package marker
+    lru_cache.py            — LRUCache and LRUCacheFast implementations
+    simulator.py            — event loading, simulation engine, text report, chart, CLI
+    plot_hit_rate.py        — capacity sweep and matplotlib plot
+    gen_bench_dataset.py    — lookup-hash → vllm bench serve dataset converter
+
+lmcache/cli/commands/tool/
+    __init__.py             — ToolCommand dispatcher (lmcache tool ...)
+    cache_simulator.py      — wires cache-simulator into the lmcache CLI
+```
+
+### CLI integration
+
+The same functionality is also accessible via the `lmcache` CLI (see
+[Quick Start](#quick-start)).  The CLI entry point lives in
+`lmcache/cli/commands/tool/cache_simulator.py`, which calls
+`add_simulate_arguments` / `run_simulate` from `simulator.py` and
+`add_sweep_arguments` / `run_sweep` from `plot_hit_rate.py`.
+
+**When adding or removing a CLI flag**, update only the relevant
+`add_*_arguments` function in `simulator.py` or `plot_hit_rate.py` — the
+`lmcache tool` command picks up the change automatically.
+
+**When adding a new action** (e.g. `lmcache tool cache-simulator compare`),
+register it in `lmcache/cli/commands/tool/cache_simulator.py` alongside the
+existing `simulate` and `sweep` actions.
+
+### `lru_cache.py`
+
+Two implementations are provided to trade off speed against feature richness:
+
+**`LRUCacheFast`** — O(1) all operations, backed by a single `OrderedDict`. Supports `contains`, `access`, `insert`, and `eviction_count`. Used during capacity sweeps where only hit/miss counts are needed.
+
+**`LRUCache`** — O(log n) operations, backed by a `dict` (for O(1) lookup) plus a `SortedList` (for O(log n) rank queries). Adds `position(key)` which returns the LRU rank of a key (0 = MRU, len−1 = LRU). Used in the single-run report for Stat 7.
+
+Both take `capacity` in **number of chunks**. The byte-to-chunk conversion is done by the caller in `simulator.py`.
+
+### `simulator.py`
+
+Key public functions:
+
+**`compute_kv_bytes_per_chunk(event)`** — derives the byte footprint of one cached chunk from a record's `shapes` and `dtypes` fields. Uses a hard-coded `dtype → bytes` table; unknown dtypes warn and contribute 0 bytes.
+
+**`load_lookup_events(paths, model, max_samples)`** — loads and merges events from one or more JSONL files or directories, sorts by `timestamp` ascending, applies optional model filter and sample cap.
+
+**`simulate(events, cache_capacity_bytes, kv_bytes_per_chunk, fast)`** — the core replay loop. Converts byte capacity to chunk count (`capacity_bytes // kv_bytes_per_chunk`), then walks events in order. For each event:
+
+1. Walk `chunk_hashes` from the front; count consecutive hits as `hit_prefix`.
+2. Accumulate `hit_prefix × chunk_size` hit tokens and `seq_len` total tokens.
+3. Update the cache: `access` for hit chunks, `insert` for miss chunks.
+4. In `fast=False` mode, additionally track per-request rates, reuse counts, span distribution, and cache positions.
+
+Returns a dict with all statistics. In `fast=True` mode the per-request and chunk-level lists are empty, making capacity sweeps significantly faster.
+
+**`print_statistics(results)`** — formats and prints the text report to stdout.
+
+**`plot_statistics(results, events, output)`** — renders the 7-panel chart and saves it to `output`.
+
+### Adding a new statistic
+
+1. Add accumulator variables in `simulate()` before the main loop.
+2. Populate them inside the `if not fast:` block.
+3. Include them in the returned dict.
+4. Add a print block in `print_statistics()`.
+5. Add a subplot in `plot_statistics()`.
+
+### Feeding custom data
+
+`simulate()` accepts any list of dicts with the fields `chunk_hashes` (list of strings), `seq_len` (int), and `chunk_size` (int). The other fields (`timestamp`, `model_name`, etc.) are only used by `load_lookup_events`. You can construct events programmatically for unit tests or synthetic benchmarks:
+
+```python
+from lmcache.tools.cache_simulator.simulator import simulate
+
+events = [
+    {"chunk_hashes": ["0xaa", "0xbb"], "seq_len": 600, "chunk_size": 256},
+    {"chunk_hashes": ["0xaa", "0xbb"], "seq_len": 600, "chunk_size": 256},
+]
+result = simulate(events, cache_capacity_bytes=10 * 1024**3, kv_bytes_per_chunk=20971520)
+print(f"Token hit rate: {result['token_hit_rate']:.2%}")
+```
diff --git a/lmcache/tools/cache_simulator/__init__.py b/lmcache/tools/cache_simulator/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/tools/cache_simulator/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/tools/cache_simulator/docs/simulate_example.png b/lmcache/tools/cache_simulator/docs/simulate_example.png
new file mode 100644
index 0000000..62f1287
Binary files /dev/null and b/lmcache/tools/cache_simulator/docs/simulate_example.png differ
diff --git a/lmcache/tools/cache_simulator/docs/sweep_example.png b/lmcache/tools/cache_simulator/docs/sweep_example.png
new file mode 100644
index 0000000..330a801
Binary files /dev/null and b/lmcache/tools/cache_simulator/docs/sweep_example.png differ
diff --git a/lmcache/tools/cache_simulator/gen_bench_dataset.py b/lmcache/tools/cache_simulator/gen_bench_dataset.py
new file mode 100644
index 0000000..d2d28f2
--- /dev/null
+++ b/lmcache/tools/cache_simulator/gen_bench_dataset.py
@@ -0,0 +1,360 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Convert LMCache lookup-hash JSONL logs into a ``vllm bench serve`` custom
+dataset (JSONL with ``"prompt"`` and ``"output_tokens"`` fields).
+
+The conversion preserves the **prefix-sharing structure** of the original
+requests: requests that shared a chunk hash in the lookup logs will share the
+same token prefix in the generated prompts.  This allows the synthetic
+benchmark to exercise LMCache prefix caching in the same pattern as the
+original production workload.
+
+Algorithm
+---------
+1. Build a *safe vocabulary*: token IDs from the tokenizer whose single-token
+   round-trip is stable (``decode([id])`` re-encodes back to exactly ``[id]``).
+   Tokens that start with a leading space are preferred to avoid BPE merges at
+   chunk boundaries.
+2. For each unique chunk hash, deterministically seed an RNG from
+   ``SHA-256(hash)`` and sample ``chunk_size`` token IDs from the safe vocab.
+   The same hash always produces the same token sequence.
+3. Per request: concatenate the token sequences for each full chunk, add
+   ``tail_len = seq_len mod chunk_size`` tail tokens (unique per request so
+   they are never accidentally cached), decode the whole list to text, and
+   write ``{"prompt": <text>, "output_tokens": <N>}``.
+
+Usage (module mode)::
+
+    python3 -m lmcache.tools.cache_simulator.gen_bench_dataset \\
+        -i /path/to/lookup_hashes/ \\
+        --tokenizer /models/DeepSeek-V3 \\
+        --output-len 128 \\
+        -o bench_dataset.jsonl
+
+Usage (CLI)::
+
+    lmcache tool cache-simulator gen-dataset \\
+        -i /path/to/lookup_hashes/ \\
+        --tokenizer /models/DeepSeek-V3 \\
+        --output-len 128 \\
+        -o bench_dataset.jsonl
+"""
+
+# Standard
+from pathlib import Path
+from typing import Any
+import argparse
+import hashlib
+import json
+import random
+import sys
+
+# ---------------------------------------------------------------------------
+# Safe-vocabulary helpers
+# ---------------------------------------------------------------------------
+
+
+def build_safe_vocab(tokenizer: Any) -> list[int]:
+    """Return token IDs that round-trip stably through the tokenizer.
+
+    A *safe* token is one where::
+
+        tokenizer.encode(tokenizer.decode([id]), add_special_tokens=False) == [id]
+
+    These tokens can be concatenated safely — decoding a list of safe tokens
+    and re-tokenizing it will reproduce the same token IDs as long as each
+    token starts with a leading space (preventing BPE merges at boundaries).
+
+    Tokens that begin with a space (``Ġ``, ``▁``, or ``" "``) are placed
+    first so that ``hash_to_tokens`` preferentially picks space-prefixed
+    tokens, making BPE boundary merges much less likely.
+
+    Args:
+        tokenizer: A HuggingFace ``PreTrainedTokenizer`` or
+            ``PreTrainedTokenizerFast`` instance.
+
+    Returns:
+        A non-empty list of safe token IDs.  Raises ``RuntimeError`` if
+        fewer than 10 safe tokens are found (the tokenizer is probably
+        unsupported).
+    """
+    vocab_size = tokenizer.vocab_size
+    safe_with_space: list[int] = []
+    safe_other: list[int] = []
+
+    for token_id in range(vocab_size):
+        try:
+            decoded = tokenizer.decode(
+                [token_id], skip_special_tokens=True, clean_up_tokenization_spaces=False
+            )
+        except Exception:
+            continue
+        if not decoded or not decoded.isprintable():
+            continue
+        # Re-encode and check round-trip
+        try:
+            re_encoded = tokenizer.encode(decoded, add_special_tokens=False)
+        except Exception:
+            continue
+        if re_encoded != [token_id]:
+            continue
+        # Prefer tokens that start with whitespace (prevents inter-chunk merges)
+        if decoded[0] in (" ", "\u0120", "\u2581"):
+            safe_with_space.append(token_id)
+        else:
+            safe_other.append(token_id)
+
+    result = safe_with_space + safe_other
+    if len(result) < 10:
+        raise RuntimeError(
+            f"Only {len(result)} safe tokens found in the vocabulary. "
+            "This tokenizer may not be supported."
+        )
+    return result
+
+
+def hash_to_tokens(chunk_hash: str, n_tokens: int, vocab_ids: list[int]) -> list[int]:
+    """Deterministically map *chunk_hash* to *n_tokens* token IDs.
+
+    The mapping is a pure function of ``chunk_hash`` and ``n_tokens`` — the
+    same inputs always produce the same output regardless of call order.
+
+    Args:
+        chunk_hash: Hex string identifying the chunk (e.g. ``"0xabcd1234"``).
+        n_tokens: Number of token IDs to generate.
+        vocab_ids: Pool of safe token IDs to sample from.
+
+    Returns:
+        A list of ``n_tokens`` token IDs drawn from ``vocab_ids``.
+    """
+    seed_bytes = hashlib.sha256(chunk_hash.encode()).digest()
+    seed = int.from_bytes(seed_bytes, "big") % (2**31)
+    rng = random.Random(seed)
+    return [rng.choice(vocab_ids) for _ in range(n_tokens)]
+
+
+# ---------------------------------------------------------------------------
+# Main conversion
+# ---------------------------------------------------------------------------
+
+
+def gen_bench_dataset(
+    events: list[dict[str, Any]],
+    tokenizer: Any,
+    output_len: int,
+    output_path: Path,
+) -> int:
+    """Convert lookup-hash events into a vllm bench serve custom dataset.
+
+    Each event becomes one JSONL line with fields ``"prompt"`` (text) and
+    ``"output_tokens"`` (int).  Chunk hashes are deterministically mapped to
+    token sequences so that prefix-sharing in the original workload is
+    reproduced in the synthetic prompts.
+
+    Args:
+        events: Lookup-hash events as returned by
+            :func:`~lmcache.tools.cache_simulator.simulator.load_lookup_events`.
+        tokenizer: A HuggingFace tokenizer loaded for the target model.
+        output_len: Number of output tokens for every request in the dataset.
+        output_path: Where to write the output JSONL file.
+
+    Returns:
+        Number of records written.
+    """
+    print("Building safe vocabulary …", flush=True)
+    vocab_ids = build_safe_vocab(tokenizer)
+    space_chars = (" ", "\u0120", "\u2581")
+    n_space = sum(1 for t in vocab_ids if tokenizer.decode([t])[0] in space_chars)
+    print(
+        f"  Safe vocab size: {len(vocab_ids)} tokens ({n_space} space-prefixed)",
+        flush=True,
+    )
+
+    # Cache: chunk_hash -> token_id list (memoized across requests)
+    hash_cache: dict[str, list[int]] = {}
+    n_written = 0
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(output_path, "w", encoding="utf-8") as fout:
+        for event in events:
+            chunk_hashes: list[str] = event.get("chunk_hashes", [])
+            chunk_size: int = event["chunk_size"]
+            seq_len: int = event["seq_len"]
+
+            # --- Full-chunk tokens ----------------------------------------
+            all_token_ids: list[int] = []
+            for h in chunk_hashes:
+                if h not in hash_cache:
+                    hash_cache[h] = hash_to_tokens(h, chunk_size, vocab_ids)
+                all_token_ids.extend(hash_cache[h])
+
+            # --- Tail tokens ----------------------------------------------
+            # seq_len mod chunk_size tail tokens; always a miss in LMCache.
+            # Use a per-request unique seed so tails are never accidentally
+            # shared across requests.
+            tail_len = seq_len - len(chunk_hashes) * chunk_size
+            if tail_len > 0:
+                # Build a per-request identifier: prefer request_id, fall back
+                # to timestamp+index to ensure uniqueness.
+                req_id = event.get(
+                    "request_id", f"{event.get('timestamp', n_written)}_{n_written}"
+                )
+                tail_hash = f"__tail__{req_id}"
+                all_token_ids.extend(hash_to_tokens(tail_hash, tail_len, vocab_ids))
+
+            # --- Decode and write -----------------------------------------
+            prompt_text = tokenizer.decode(
+                all_token_ids,
+                skip_special_tokens=True,
+                clean_up_tokenization_spaces=False,
+            )
+            record = {"prompt": prompt_text, "output_tokens": output_len}
+            fout.write(json.dumps(record, ensure_ascii=False) + "\n")
+            n_written += 1
+
+            if n_written % 1000 == 0:
+                print(f"  {n_written} / {len(events)} records written …", flush=True)
+
+    return n_written
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers (shared by main() and lmcache tool cache-simulator gen-dataset)
+# ---------------------------------------------------------------------------
+
+
+def add_gen_dataset_arguments(parser: argparse.ArgumentParser) -> None:
+    """Register all gen-dataset CLI flags onto *parser*.
+
+    Called by both :func:`main` (``python -m`` entry point) and the
+    ``lmcache tool cache-simulator gen-dataset`` sub-command in
+    ``lmcache/cli/commands/tool/cache_simulator.py``.
+
+    **When adding or removing a flag**, edit only this function — the
+    ``lmcache tool`` command picks up the change automatically.
+
+    Args:
+        parser: The :class:`argparse.ArgumentParser` (or sub-parser) to
+            populate.
+    """
+    parser.add_argument(
+        "-i",
+        "--input",
+        nargs="+",
+        required=True,
+        metavar="PATH",
+        type=Path,
+        help=(
+            "One or more JSONL files or directories containing "
+            "``lookup_hashes_*.jsonl`` files."
+        ),
+    )
+    parser.add_argument(
+        "--tokenizer",
+        required=True,
+        metavar="PATH",
+        help=(
+            "Path or HuggingFace model name for the tokenizer used to decode "
+            "synthetic token IDs into text.  Should match the model that will "
+            "be benchmarked."
+        ),
+    )
+    parser.add_argument(
+        "--output-len",
+        type=int,
+        default=128,
+        metavar="N",
+        help="Number of output tokens for every request (default: %(default)s).",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="bench_dataset.jsonl",
+        metavar="FILE",
+        help="Output JSONL file path (default: %(default)s).",
+    )
+    parser.add_argument(
+        "-n",
+        "--max-samples",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Truncate to the first N events after sorting by timestamp.",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        metavar="NAME",
+        help=(
+            "Filter events by ``model_name`` (exact match).  Useful when logs "
+            "contain traffic for multiple models."
+        ),
+    )
+
+
+def run_gen_dataset(args: argparse.Namespace) -> None:
+    """Execute the gen-dataset workflow from a parsed argument namespace.
+
+    Loads events via
+    :func:`~lmcache.tools.cache_simulator.simulator.load_lookup_events`,
+    loads the tokenizer, calls :func:`gen_bench_dataset`, and prints a
+    summary.
+
+    Args:
+        args: Parsed CLI namespace produced by a parser that was populated
+            with :func:`add_gen_dataset_arguments`.
+    """
+    # Lazy imports — keeps CLI startup fast
+    # Third Party
+    from transformers import AutoTokenizer
+
+    # First Party
+    from lmcache.tools.cache_simulator.simulator import load_lookup_events
+
+    # ---- Load events -------------------------------------------------------
+    print(f"Loading events from: {[str(p) for p in args.input]}", flush=True)
+    events = load_lookup_events(
+        args.input,
+        model=args.model,
+        max_samples=args.max_samples,
+    )
+    if not events:
+        print("No events found — nothing to write.", file=sys.stderr)
+        sys.exit(1)
+    print(f"Loaded {len(events):,} events.", flush=True)
+
+    # ---- Load tokenizer ----------------------------------------------------
+    print(f"Loading tokenizer: {args.tokenizer}", flush=True)
+    tokenizer = AutoTokenizer.from_pretrained(args.tokenizer, trust_remote_code=True)
+
+    # ---- Convert -----------------------------------------------------------
+    output_path = Path(args.output)
+    n = gen_bench_dataset(
+        events=events,
+        tokenizer=tokenizer,
+        output_len=args.output_len,
+        output_path=output_path,
+    )
+    print(f"\nWrote {n:,} records to {output_path}")
+
+
+# ---------------------------------------------------------------------------
+# Module entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """CLI entry point for ``python -m``."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Convert LMCache lookup-hash JSONL logs into a "
+            "vllm bench serve custom dataset."
+        )
+    )
+    add_gen_dataset_arguments(parser)
+    args = parser.parse_args()
+    run_gen_dataset(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/tools/cache_simulator/lru_cache.py b/lmcache/tools/cache_simulator/lru_cache.py
new file mode 100644
index 0000000..d49dc63
--- /dev/null
+++ b/lmcache/tools/cache_simulator/lru_cache.py
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LRU cache implementations for the cache simulator.
+
+Two variants are provided:
+
+* ``LRUCacheFast`` — O(1) OrderedDict-backed.  Supports only hit/miss queries.
+  Use this for capacity sweeps where per-chunk statistics are not needed.
+
+* ``LRUCache`` — O(log n) dict + SortedList.  Adds ``position(key)`` for
+  computing cache-position statistics (0 = MRU, capacity-1 = LRU).
+  Use this for the detailed single-run report.
+"""
+
+# Standard
+from collections import OrderedDict
+from typing import Any
+
+# Third Party
+from sortedcontainers import SortedList
+
+
+class LRUCacheFast:
+    """
+    Lightweight LRU cache using a single :class:`OrderedDict`.
+
+    All operations are O(1).  No per-key position tracking.
+
+    Parameters
+    ----------
+    capacity:
+        Maximum number of entries before LRU eviction kicks in.
+    """
+
+    def __init__(self, capacity: int) -> None:
+        if capacity < 1:
+            raise ValueError(f"LRUCacheFast capacity must be >= 1, got {capacity}")
+        self.capacity = capacity
+        self._cache: OrderedDict[Any, None] = OrderedDict()
+        self.eviction_count: int = 0
+
+    def contains(self, key: Any) -> bool:
+        return key in self._cache
+
+    def access(self, key: Any) -> None:
+        """Mark an existing entry as most-recently used. O(1)."""
+        self._cache.move_to_end(key)
+
+    def insert(self, key: Any) -> None:
+        """Insert a new entry, or refresh if already present. O(1)."""
+        if key in self._cache:
+            self._cache.move_to_end(key)
+            return
+        if len(self._cache) >= self.capacity:
+            self._cache.popitem(last=False)
+            self.eviction_count += 1
+        self._cache[key] = None
+
+    def __len__(self) -> int:
+        return len(self._cache)
+
+
+class LRUCache:
+    """
+    LRU cache backed by a dict (O(1) lookup) and a
+    :class:`~sortedcontainers.SortedList` (O(log n) rank queries).
+
+    Each entry carries a strictly-increasing clock value so that the SortedList
+    order is unambiguous.
+
+    * LRU end = smallest clock value = ``SortedList[0]``
+    * MRU end = largest clock value  = ``SortedList[-1]``
+
+    Parameters
+    ----------
+    capacity:
+        Maximum number of entries before LRU eviction kicks in.
+    """
+
+    def __init__(self, capacity: int) -> None:
+        if capacity < 1:
+            raise ValueError(f"LRUCache capacity must be >= 1, got {capacity}")
+        self.capacity = capacity
+        self._clock: int = 0
+        self._map: dict[Any, int] = {}  # key -> clock value at last access
+        self._sl: SortedList = SortedList(key=lambda x: x[0])
+        self.eviction_count: int = 0
+
+    def contains(self, key: Any) -> bool:
+        return key in self._map
+
+    def position(self, key: Any) -> int:
+        """
+        LRU rank of *key*: 0 = most-recently used, ``len-1`` = least-recently used.
+        O(log n).
+        """
+        clock = self._map[key]
+        idx = self._sl.index((clock, key))
+        return len(self._sl) - 1 - idx
+
+    def access(self, key: Any) -> None:
+        """Mark an existing entry as most-recently used. O(log n)."""
+        old_clock = self._map[key]
+        self._sl.remove((old_clock, key))
+        self._clock += 1
+        self._map[key] = self._clock
+        self._sl.add((self._clock, key))
+
+    def insert(self, key: Any) -> None:
+        """Insert a new entry, or refresh if already present. O(log n)."""
+        if key in self._map:
+            self.access(key)
+            return
+        if len(self._map) >= self.capacity:
+            lru_clock, lru_key = self._sl[0]
+            self._sl.remove((lru_clock, lru_key))
+            del self._map[lru_key]
+            self.eviction_count += 1
+        self._clock += 1
+        self._map[key] = self._clock
+        self._sl.add((self._clock, key))
+
+    def __len__(self) -> int:
+        return len(self._map)
diff --git a/lmcache/tools/cache_simulator/plot_hit_rate.py b/lmcache/tools/cache_simulator/plot_hit_rate.py
new file mode 100644
index 0000000..e65cb4d
--- /dev/null
+++ b/lmcache/tools/cache_simulator/plot_hit_rate.py
@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Plot token cache hit rate vs cache capacity (GiB).
+
+Sweeps a logarithmically-spaced range of cache capacities, runs the simulator
+at each point, and produces a matplotlib figure showing how token hit rate
+scales with available memory.
+
+Usage::
+
+    python -m lmcache.tools.cache_simulator.plot_hit_rate \\
+        -i /path/to/lookup_hashes/ \\
+        --min-capacity-gib 1 \\
+        --max-capacity-gib 512 \\
+        --points 30 \\
+        -o hit_rate_vs_capacity.png
+"""
+
+# Standard
+from pathlib import Path
+import argparse
+import math
+import sys
+
+# First Party
+from lmcache.tools.cache_simulator.simulator import (
+    compute_kv_bytes_per_chunk,
+    load_lookup_events,
+    simulate,
+)
+
+_GIB = 2**30
+
+
+def capacity_range_bytes(
+    min_gib: float,
+    max_gib: float,
+    num_points: int,
+) -> list[int]:
+    """
+    Return *num_points* byte capacities log-spaced between *min_gib* and
+    *max_gib* GiB.
+    """
+    log_min = math.log10(min_gib * _GIB)
+    log_max = math.log10(max_gib * _GIB)
+    step = (log_max - log_min) / max(num_points - 1, 1)
+    return sorted({round(10 ** (log_min + i * step)) for i in range(num_points)})
+
+
+def add_sweep_arguments(parser: argparse.ArgumentParser) -> None:
+    """Register all ``sweep`` CLI flags onto *parser*.
+
+    Called by both the module ``main()`` and by
+    :class:`~lmcache.cli.commands.tool.ToolCommand` so that flag definitions
+    live in exactly one place.
+
+    Args:
+        parser: The ``ArgumentParser`` (or sub-parser) to add flags to.
+    """
+    parser.add_argument(
+        "-i",
+        "--input",
+        nargs="+",
+        required=True,
+        metavar="PATH",
+        help="One or more lookup-hash JSONL files or directories",
+    )
+    parser.add_argument(
+        "-n",
+        "--max-samples",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum number of events to process (default: all)",
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        metavar="NAME",
+        help="Filter events by model_name (exact match)",
+    )
+    parser.add_argument(
+        "--min-capacity-gib",
+        type=float,
+        default=0.5,
+        metavar="GiB",
+        help="Minimum cache capacity to sweep (default: 0.5 GiB)",
+    )
+    parser.add_argument(
+        "--max-capacity-gib",
+        type=float,
+        default=500.0,
+        metavar="GiB",
+        help="Maximum cache capacity to sweep (default: 500 GiB)",
+    )
+    parser.add_argument(
+        "--points",
+        type=int,
+        default=30,
+        metavar="N",
+        help="Number of log-spaced capacity samples (default: 30)",
+    )
+    parser.add_argument(
+        "--linear",
+        action="store_true",
+        help="Use a linear x-axis (default: log scale)",
+    )
+    parser.add_argument(
+        "--kv-bytes-per-chunk",
+        type=int,
+        default=None,
+        metavar="BYTES",
+        help=(
+            "Bytes consumed by one cached chunk.  "
+            "Auto-computed from the first event's shapes/dtypes if omitted."
+        ),
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="hit_rate_vs_capacity.png",
+        metavar="FILE",
+        help="Output image path (default: hit_rate_vs_capacity.png)",
+    )
+
+
+def run_sweep(args: argparse.Namespace) -> None:
+    """Execute the sweep workflow from a parsed argument namespace.
+
+    Loads events, resolves ``kv_bytes_per_chunk``, sweeps across a log-spaced
+    range of cache capacities, prints a results table, and saves a hit-rate vs
+    capacity PNG.  Called by both the module ``main()`` and by
+    :class:`~lmcache.cli.commands.tool.ToolCommand`.
+
+    Args:
+        args: Parsed CLI arguments.  Must have the attributes registered by
+            :func:`add_sweep_arguments`.
+    """
+    paths = [Path(p) for p in args.input]
+    print(f"Loading lookup events from {[str(p) for p in paths]} …")
+    events = load_lookup_events(paths, model=args.model, max_samples=args.max_samples)
+    print(f"Loaded {len(events):,} event(s)\n")
+
+    if not events:
+        print("No events to process.")
+        sys.exit(0)
+
+    kv_bpc = args.kv_bytes_per_chunk
+    if kv_bpc is None:
+        kv_bpc = compute_kv_bytes_per_chunk(events[0])
+        if kv_bpc == 0:
+            print(
+                "Error: could not determine kv_bytes_per_chunk from the first event "
+                "(shapes/dtypes are empty).  Pass --kv-bytes-per-chunk explicitly.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        print(f"Auto-detected kv_bytes_per_chunk = {kv_bpc:,} bytes")
+
+    chunk_size = events[0].get("chunk_size", "?")
+    model_label = args.model or "all models"
+
+    capacities_bytes = capacity_range_bytes(
+        args.min_capacity_gib, args.max_capacity_gib, args.points
+    )
+    hit_rates: list[float] = []
+
+    scale_label = "linear" if args.linear else "log"
+    print(
+        f"Sweeping {len(capacities_bytes)} capacity values "
+        f"({args.min_capacity_gib:.2f} – {args.max_capacity_gib:.2f} GiB), "
+        f"chunk_size = {chunk_size} tokens, model = {model_label}\n"
+    )
+    print(f"{'Capacity (GiB)':>18}  {'Hit rate':>10}")
+    print("-" * 32)
+
+    for cap_bytes in capacities_bytes:
+        cap_gib = cap_bytes / _GIB
+        res = simulate(events, cap_bytes, kv_bpc, fast=True)
+        rate = res["token_hit_rate"]
+        hit_rates.append(rate)
+        print(f"{cap_gib:>18.3f}  {rate:>9.2%}")
+
+    # ── Plot ────────────────────────────────────────────────────────────────
+    x_values = [c / _GIB for c in capacities_bytes]
+
+    # Third Party
+    import matplotlib.pyplot as plt  # noqa: PLC0415 — lazy import to avoid hard dependency
+
+    fig, ax = plt.subplots(figsize=(9, 5))
+    ax.plot(
+        x_values,
+        [r * 100 for r in hit_rates],
+        marker="o",
+        linewidth=2,
+        markersize=4,
+    )
+
+    if not args.linear:
+        ax.set_xscale("log")
+
+    ax.set_xlabel("Cache capacity (GiB)", fontsize=12)
+    ax.set_ylabel("Token hit rate (%)", fontsize=12)
+    ax.set_title(
+        f"Token cache hit rate vs capacity\n"
+        f"(chunk_size = {chunk_size} tokens, {len(events):,} requests, "
+        f"model = {model_label}, {scale_label} scale)",
+        fontsize=11,
+    )
+    ax.set_ylim(0, 100)
+    ax.grid(True, which="both", linestyle="--", alpha=0.5)
+    ax.yaxis.set_major_formatter(plt.FuncFormatter(lambda y, _: f"{y:.0f}%"))
+
+    fig.tight_layout()
+    fig.savefig(args.output, dpi=150)
+    print(f"\nPlot saved to '{args.output}'")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Plot token cache hit rate vs cache capacity from lookup-hash JSONL logs"
+        )
+    )
+    add_sweep_arguments(parser)
+    args = parser.parse_args()
+    run_sweep(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/tools/cache_simulator/simulator.py b/lmcache/tools/cache_simulator/simulator.py
new file mode 100644
index 0000000..32fa664
--- /dev/null
+++ b/lmcache/tools/cache_simulator/simulator.py
@@ -0,0 +1,795 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Cache hit-rate simulator driven by LMCache lookup-hash JSONL logs.
+
+The simulator replays ``MP_LOOKUP`` events recorded by
+:class:`~lmcache.v1.mp_observability.subscribers.logging.lookup_hash.LookupHashLoggingSubscriber`.
+Each event contains the ordered list of *full-chunk* hashes that were looked up
+for a single request, together with the sequence length and chunk size.
+
+**Token cache hit rate** (the primary metric) is defined as::
+
+    token_hit_rate = total_hit_tokens / total_tokens
+
+where:
+
+* ``total_tokens`` = sum of ``seq_len`` across all requests (includes tail tokens
+  that do not fill a complete chunk — these are *always* a miss because LMCache
+  only caches complete chunks).
+* ``total_hit_tokens`` = number of tokens covered by a *continuous prefix* of
+  cache-hit chunks at the start of each request, i.e.
+  ``hit_prefix_chunks × chunk_size``.
+
+Running the simulator prints a text report **and** saves a multi-panel PNG with
+seven statistical charts.
+
+Usage (module mode)::
+
+    python3 -m lmcache.tools.cache_simulator.simulator \\
+        -i /path/to/lookup_hashes/ \\
+        --cache-capacity-gib 64 \\
+        -o stats.png
+"""
+
+# Standard
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+import argparse
+import json
+import math
+import sys
+import warnings
+
+# First Party
+from lmcache.tools.cache_simulator.lru_cache import LRUCache, LRUCacheFast
+
+# ---------------------------------------------------------------------------
+# Dtype → bytes mapping
+# ---------------------------------------------------------------------------
+
+_DTYPE_BYTES: dict[str, int] = {
+    "float32": 4,
+    "float16": 2,
+    "bfloat16": 2,
+    "float8_e4m3fn": 1,
+    "float8_e5m2": 1,
+    "int8": 1,
+    "int32": 4,
+    "int64": 8,
+}
+
+_GIB = 2**30
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+
+def compute_kv_bytes_per_chunk(event: dict[str, Any]) -> int:
+    """
+    Compute the number of KV-cache bytes that one chunk occupies.
+
+    The value is derived from the ``shapes`` and ``dtypes`` fields of a single
+    lookup event.  Each ``(shape, dtype)`` pair represents one tensor stored
+    per chunk (e.g. key and value tensors for all layers); their byte sizes are
+    summed.
+
+    Returns 0 if ``shapes`` or ``dtypes`` is empty (caller must handle this).
+    """
+    shapes = event.get("shapes", [])
+    dtypes = event.get("dtypes", [])
+    if not shapes or not dtypes:
+        return 0
+    total = 0
+    for shape, dt in zip(shapes, dtypes, strict=False):
+        elem_bytes = _DTYPE_BYTES.get(dt, 0)
+        if elem_bytes == 0:
+            warnings.warn(
+                f"Unknown dtype '{dt}' — treating as 0 bytes per element.",
+                UserWarning,
+                stacklevel=2,
+            )
+        total += math.prod(shape) * elem_bytes
+    return total
+
+
+def load_lookup_events(
+    paths: list[Path],
+    model: str | None = None,
+    max_samples: int | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Load and return lookup events from one or more JSONL files or directories.
+
+    Parameters
+    ----------
+    paths:
+        Each element may be a ``.jsonl`` file or a directory.  Directories are
+        globbed for ``lookup_hashes_*.jsonl`` files.
+    model:
+        If given, only events whose ``model_name`` exactly matches this string
+        are returned.
+    max_samples:
+        If given, truncate the final sorted list to this many events.
+
+    Returns
+    -------
+    list[dict]
+        Events sorted by ``timestamp`` ascending.
+    """
+    all_events: list[dict[str, Any]] = []
+
+    for p in paths:
+        files: list[Path]
+        if p.is_dir():
+            files = sorted(p.glob("lookup_hashes_*.jsonl"))
+            if not files:
+                warnings.warn(
+                    f"Directory '{p}' contains no lookup_hashes_*.jsonl files.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+        else:
+            files = [p]
+
+        for f in files:
+            try:
+                with open(f, encoding="utf-8") as fh:
+                    for lineno, line in enumerate(fh, start=1):
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            event = json.loads(line)
+                        except json.JSONDecodeError as exc:
+                            warnings.warn(
+                                f"{f}:{lineno}: skipping malformed JSON — {exc}",
+                                UserWarning,
+                                stacklevel=2,
+                            )
+                            continue
+                        if model is not None and event.get("model_name") != model:
+                            continue
+                        all_events.append(event)
+            except OSError as exc:
+                warnings.warn(
+                    f"Could not open '{f}': {exc}",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
+    all_events.sort(key=lambda e: e.get("timestamp", 0.0))
+
+    if max_samples is not None and max_samples > 0:
+        all_events = all_events[:max_samples]
+
+    return all_events
+
+
+# ---------------------------------------------------------------------------
+# Simulation
+# ---------------------------------------------------------------------------
+
+
+def simulate(
+    events: list[dict[str, Any]],
+    cache_capacity_bytes: int,
+    kv_bytes_per_chunk: int,
+    fast: bool = False,
+) -> dict[str, Any]:
+    """
+    Replay lookup events through an LRU cache and compute token hit-rate
+    statistics.
+
+    Parameters
+    ----------
+    events:
+        Lookup events as returned by :func:`load_lookup_events`.
+    cache_capacity_bytes:
+        Total cache capacity in bytes.
+    kv_bytes_per_chunk:
+        Bytes consumed by one cached chunk.
+    fast:
+        If ``True``, use :class:`~lmcache.tools.cache_simulator.lru_cache.LRUCacheFast`
+        and skip per-chunk statistics (faster for capacity sweeps).
+
+    Returns
+    -------
+    dict
+        Simulation results (see source for field list).
+    """
+    if kv_bytes_per_chunk <= 0:
+        raise ValueError(
+            "kv_bytes_per_chunk must be > 0.  "
+            "Either pass --kv-bytes-per-chunk or ensure the JSONL records "
+            "contain non-empty 'shapes' and 'dtypes' fields."
+        )
+
+    cache_capacity_chunks = max(1, cache_capacity_bytes // kv_bytes_per_chunk)
+
+    cache: LRUCacheFast | LRUCache
+    if fast:
+        cache = LRUCacheFast(cache_capacity_chunks)
+    else:
+        cache = LRUCache(cache_capacity_chunks)
+
+    # ── Aggregates ──────────────────────────────────────────────────────────
+    total_requests = 0
+    total_tokens = 0
+    total_hit_tokens = 0
+
+    # ── Per-request (skipped in fast mode) ──────────────────────────────────
+    per_request_token_hit_rates: list[float] = []
+    hit_prefix_lengths: list[int] = []
+    rolling_token_hit_rate: list[float] = []
+    input_lengths: list[int] = []
+
+    # ── Chunk-level (skipped in fast mode) ──────────────────────────────────
+    chunk_reuse_counts: dict[str, int] = defaultdict(int)
+    chunk_last_seen: dict[str, int] = {}
+    global_span_distribution: list[int] = []
+    cache_position_distribution: list[int] = []
+    global_chunk_index = 0
+
+    for event in events:
+        hashes: list[str] = event.get("chunk_hashes", [])
+        seq_len: int = event.get("seq_len", 0)
+        chunk_sz: int = event.get("chunk_size", 1)
+
+        if not hashes and seq_len == 0:
+            continue
+
+        # ── Prefix hit count ────────────────────────────────────────────────
+        hit_prefix = 0
+        for h in hashes:
+            if cache.contains(h):
+                hit_prefix += 1
+            else:
+                break
+
+        # ── Token accounting ────────────────────────────────────────────────
+        # Tail tokens (seq_len - len(hashes)*chunk_sz) are always a miss.
+        hit_tokens = hit_prefix * chunk_sz
+        request_tokens = seq_len  # includes tail tokens
+
+        total_requests += 1
+        total_tokens += request_tokens
+        total_hit_tokens += hit_tokens
+
+        if not fast:
+            input_lengths.append(seq_len)
+            per_request_token_hit_rates.append(
+                hit_tokens / request_tokens if request_tokens > 0 else 0.0
+            )
+            hit_prefix_lengths.append(hit_prefix)
+            rolling_token_hit_rate.append(
+                total_hit_tokens / total_tokens if total_tokens > 0 else 0.0
+            )
+
+            # Per-hit-chunk statistics
+            for i, h in enumerate(hashes[:hit_prefix]):
+                chunk_reuse_counts[h] += 1
+                if h in chunk_last_seen:
+                    global_span_distribution.append(
+                        global_chunk_index + i - chunk_last_seen[h]
+                    )
+                if isinstance(cache, LRUCache):
+                    cache_position_distribution.append(cache.position(h))
+
+        # ── Update cache ────────────────────────────────────────────────────
+        for i, h in enumerate(hashes):
+            if not fast:
+                chunk_last_seen[h] = global_chunk_index + i
+            if i < hit_prefix:
+                cache.access(h)
+            else:
+                cache.insert(h)
+
+        if not fast:
+            global_chunk_index += len(hashes)
+
+    token_hit_rate = total_hit_tokens / total_tokens if total_tokens > 0 else 0.0
+
+    return {
+        # ── Aggregates ──────────────────────────────────────────────────────
+        "total_requests": total_requests,
+        "total_tokens": total_tokens,
+        "total_hit_tokens": total_hit_tokens,
+        "total_miss_tokens": total_tokens - total_hit_tokens,
+        "token_hit_rate": token_hit_rate,
+        "eviction_count": cache.eviction_count,
+        "cache_size_at_end_chunks": len(cache),
+        "cache_capacity_chunks": cache_capacity_chunks,
+        "cache_capacity_bytes": cache_capacity_bytes,
+        "kv_bytes_per_chunk": kv_bytes_per_chunk,
+        # ── Per-request ─────────────────────────────────────────────────────
+        "per_request_token_hit_rates": per_request_token_hit_rates,
+        "hit_prefix_lengths": hit_prefix_lengths,
+        "input_lengths": input_lengths,
+        "rolling_token_hit_rate": rolling_token_hit_rate,
+        # ── Chunk-level ─────────────────────────────────────────────────────
+        "chunk_reuse_counts": dict(chunk_reuse_counts),
+        "global_span_distribution": global_span_distribution,
+        "cache_position_distribution": cache_position_distribution,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Reporting — text
+# ---------------------------------------------------------------------------
+
+
+def _percentiles(values: list[float], pcts: list[int]) -> dict[str, float]:
+    if not values:
+        return {}
+    s = sorted(values)
+    n = len(s)
+    result = {}
+    for p in pcts:
+        idx = min(int(p / 100 * n), n - 1)
+        result[f"p{p}"] = s[idx]
+    return result
+
+
+def print_statistics(results: dict[str, Any]) -> None:
+    sep = "=" * 60
+
+    gib = results["cache_capacity_bytes"] / _GIB
+    print(sep)
+    print("Aggregate")
+    print(sep)
+    print(f"  Requests processed  : {results['total_requests']:,}")
+    print(f"  Total tokens        : {results['total_tokens']:,}")
+    print(f"  Hit tokens          : {results['total_hit_tokens']:,}")
+    print(f"  Miss tokens         : {results['total_miss_tokens']:,}")
+    print(f"  Token hit rate      : {results['token_hit_rate']:.2%}")
+    print(
+        f"  Cache capacity      : {gib:.2f} GiB  "
+        f"({results['cache_capacity_chunks']:,} chunks × "
+        f"{results['kv_bytes_per_chunk']:,} bytes/chunk)"
+    )
+    print(
+        f"  Cache occupancy     : {results['cache_size_at_end_chunks']:,} / "
+        f"{results['cache_capacity_chunks']:,} chunks"
+    )
+
+    rates = results["per_request_token_hit_rates"]
+    if rates:
+        zero_hit = sum(1 for r in rates if r == 0.0)
+        full_hit = sum(1 for r in rates if r == 1.0)
+        pcts = _percentiles(rates, [25, 50, 75, 90, 99])
+        print()
+        print(sep)
+        print("Stat 1 — Per-request token hit rate distribution")
+        print(sep)
+        print(
+            f"  Requests with 0% hit rate   : "
+            f"{zero_hit:,} ({zero_hit / len(rates):.1%})"
+        )
+        print(
+            f"  Requests with 100% hit rate : "
+            f"{full_hit:,} ({full_hit / len(rates):.1%})"
+        )
+        print(f"  Mean                        : {sum(rates) / len(rates):.2%}")
+        for k, v in pcts.items():
+            print(f"  {k:4s}                        : {v:.2%}")
+
+    lengths = results["hit_prefix_lengths"]
+    if lengths:
+        pcts_len = _percentiles([float(x) for x in lengths], [25, 50, 75, 90, 99])
+        print()
+        print(sep)
+        print("Stat 2 — Hit prefix length per request (chunks)")
+        print(sep)
+        print(f"  Mean               : {sum(lengths) / len(lengths):.1f}")
+        for k, v in pcts_len.items():
+            print(f"  {k:4s}               : {v:.0f}")
+
+    reuse = sorted(results["chunk_reuse_counts"].values())
+    if reuse:
+        pcts_reuse = _percentiles([float(x) for x in reuse], [25, 50, 75, 90, 99])
+        print()
+        print(sep)
+        print("Stat 3 — Chunk reuse count distribution")
+        print(sep)
+        print(f"  Unique chunks hit at least once : {len(reuse):,}")
+        print(f"  Mean reuse count                : {sum(reuse) / len(reuse):.1f}")
+        print(f"  Max reuse count                 : {reuse[-1]:,}")
+        for k, v in pcts_reuse.items():
+            print(f"  {k:4s}                            : {v:.0f}")
+
+    rolling = results["rolling_token_hit_rate"]
+    if rolling:
+        print()
+        print(sep)
+        print("Stat 4 — Rolling (cumulative) token hit rate over time")
+        print(sep)
+        n = len(rolling)
+        for frac in (0.1, 0.25, 0.5, 0.75, 1.0):
+            idx = max(0, min(int(n * frac) - 1, n - 1))
+            print(f"  After request {idx + 1:>6,} : {rolling[idx]:.2%}")
+
+    print()
+    print(sep)
+    print("Stat 5 — Evictions")
+    print(sep)
+    print(f"  Total evictions    : {results['eviction_count']:,}")
+
+    spans = results["global_span_distribution"]
+    if spans:
+        pcts_span = _percentiles([float(x) for x in spans], [25, 50, 75, 90, 99])
+        print()
+        print(sep)
+        print("Stat 6 — Global span distribution (chunks between last store and hit)")
+        print(sep)
+        print(f"  Total hit chunks   : {len(spans):,}")
+        print(f"  Mean span          : {sum(spans) / len(spans):.1f}")
+        print(f"  Max span           : {max(spans):,}")
+        for k, v in pcts_span.items():
+            print(f"  {k:4s}               : {v:.0f}")
+
+    positions = results["cache_position_distribution"]
+    if positions:
+        pcts_pos = _percentiles([float(x) for x in positions], [25, 50, 75, 90, 99])
+        print()
+        print(sep)
+        print("Stat 7 — Cache position at hit (0 = MRU, max = LRU)")
+        print(sep)
+        print(f"  Mean position      : {sum(positions) / len(positions):.1f}")
+        print(f"  Max position       : {max(positions):,}")
+        for k, v in pcts_pos.items():
+            print(f"  {k:4s}               : {v:.0f}")
+
+    print(sep)
+
+
+# ---------------------------------------------------------------------------
+# Reporting — charts
+# ---------------------------------------------------------------------------
+
+
+def plot_statistics(
+    results: dict[str, Any], events: list[dict[str, Any]], output: str
+) -> None:
+    """
+    Render and save a 2×4 multi-panel figure with seven statistical charts.
+
+    Parameters
+    ----------
+    results:
+        Output of :func:`simulate` with ``fast=False``.
+    events:
+        The event list used to produce *results* (used for chunk_size label).
+    output:
+        Output file path (PNG).
+    """
+    cap_gib = results["cache_capacity_bytes"] / _GIB
+    chunk_size = events[0].get("chunk_size", "?") if events else "?"
+    n_req = results["total_requests"]
+
+    per_request_hit_rates = [r * 100 for r in results["per_request_token_hit_rates"]]
+    hit_prefix_lengths = results["hit_prefix_lengths"]
+    reuse_counts = sorted(results["chunk_reuse_counts"].values())
+    rolling = [r * 100 for r in results["rolling_token_hit_rate"]]
+    input_lengths = results["input_lengths"]
+    global_spans = results["global_span_distribution"]
+    cache_positions = results["cache_position_distribution"]
+
+    # Third Party
+    import matplotlib.pyplot as plt  # noqa: PLC0415 — lazy import to avoid hard dependency
+
+    fig, axes = plt.subplots(2, 4, figsize=(22, 10))
+    fig.suptitle(
+        f"Cache simulation statistics  "
+        f"(chunk_size={chunk_size} tokens,  capacity={cap_gib:.1f} GiB,  "
+        f"{n_req:,} requests,  token hit rate={results['token_hit_rate']:.2%})",
+        fontsize=12,
+    )
+
+    # ------------------------------------------------------------------
+    # Plot 1 — Per-request token hit rate (non-zero requests only)
+    # Two small pies: left = requests hit/miss, right = tokens hit/miss
+    # ------------------------------------------------------------------
+    ax = axes[0, 0]
+    nonzero = [r for r in per_request_hit_rates if r > 0]
+    n_zero = len(per_request_hit_rates) - len(nonzero)
+    ax.hist(nonzero, bins=50, edgecolor="black", linewidth=0.4)
+    ax.set_xlabel("Token hit rate (%) — zero-hit requests excluded")
+    ax.set_ylabel("Number of requests")
+    ax.set_title("1. Per-request token hit rate")
+
+    # Left pie — requests
+    ax_pie = ax.inset_axes([0.01, 0.52, 0.24, 0.42])
+    ax_pie.patch.set_alpha(0)
+    wedges, _, _ = ax_pie.pie(
+        [len(nonzero), n_zero],
+        labels=["hit", "miss"],
+        autopct="%1.0f%%",
+        startangle=90,
+        textprops={"fontsize": 5},
+        colors=["#4C72B0", "#DD8452"],
+    )
+    for w in wedges:
+        w.set_alpha(0.6)
+    ax_pie.set_title("requests", fontsize=5, pad=2)
+    ax_pie.text(
+        0.5,
+        -0.08,
+        "Fraction of requests\nwith ≥1 chunk hit",
+        transform=ax_pie.transAxes,
+        fontsize=5,
+        ha="center",
+        va="top",
+        color="dimgray",
+    )
+
+    # Right pie — tokens
+    ax_pie2 = ax.inset_axes([0.27, 0.52, 0.24, 0.42])
+    ax_pie2.patch.set_alpha(0)
+    wedges2, _, _ = ax_pie2.pie(
+        [results["total_hit_tokens"], results["total_miss_tokens"]],
+        labels=["hit", "miss"],
+        autopct="%1.0f%%",
+        startangle=90,
+        textprops={"fontsize": 5},
+        colors=["#4C72B0", "#DD8452"],
+    )
+    for w in wedges2:
+        w.set_alpha(0.6)
+    ax_pie2.set_title("tokens", fontsize=5, pad=2)
+    ax_pie2.text(
+        0.5,
+        -0.08,
+        "Fraction of tokens\nserved from cache",
+        transform=ax_pie2.transAxes,
+        fontsize=5,
+        ha="center",
+        va="top",
+        color="dimgray",
+    )
+
+    # ------------------------------------------------------------------
+    # Plot 1b — Zoom into 97–100% hit rate
+    # ------------------------------------------------------------------
+    ax = axes[0, 1]
+    n_full = sum(1 for r in per_request_hit_rates if r == 100)
+    high = [r for r in nonzero if r >= 97]
+    ax.hist(high, bins=20, edgecolor="black", linewidth=0.4)
+    ax.set_xlim(97, 100)
+    ax.set_xlabel("Token hit rate (%) — 97–100% zoom")
+    ax.set_ylabel("Number of requests")
+    ax.set_title("1b. Per-request token hit rate (97–100%)")
+    ax.text(
+        0.03,
+        0.95,
+        f"100% hit: {n_full:,} requests",
+        transform=ax.transAxes,
+        fontsize=8,
+        ha="left",
+        va="top",
+        bbox=dict(boxstyle="round,pad=0.3", facecolor="wheat", alpha=0.7),
+    )
+
+    # ------------------------------------------------------------------
+    # Plot 2 — Hit prefix length per request (clean histogram, no pie)
+    # ------------------------------------------------------------------
+    ax = axes[0, 2]
+    nonzero_prefix = [n for n in hit_prefix_lengths if n > 0]
+    ax.hist(nonzero_prefix, bins=50, edgecolor="black", linewidth=0.4)
+    ax.set_xlabel("Hit prefix length (chunks) — zero-hit requests excluded")
+    ax.set_ylabel("Number of requests")
+    ax.set_title("2. Hit prefix length per request")
+
+    # Plot 3 — Chunk reuse count
+    # ------------------------------------------------------------------
+    ax = axes[0, 3]
+    if reuse_counts:
+        cap = min(max(reuse_counts), 100)
+        ax.hist(
+            [r for r in reuse_counts if r <= cap],
+            bins=range(1, cap + 2),
+            edgecolor="black",
+            linewidth=0.4,
+        )
+        if max(reuse_counts) > cap:
+            n_above = sum(1 for r in reuse_counts if r > cap)
+            pct_above = n_above / len(reuse_counts) * 100
+            ax.text(
+                0.97,
+                0.95,
+                f"max={max(reuse_counts):,}\n"
+                f"{n_above:,} chunks ({pct_above:.1f}%) above cap",
+                transform=ax.transAxes,
+                fontsize=8,
+                ha="right",
+                va="top",
+                bbox=dict(boxstyle="round,pad=0.3", facecolor="wheat", alpha=0.7),
+            )
+    ax.set_xlabel("Times a chunk was hit (capped at 100)")
+    ax.set_ylabel("Number of unique chunks")
+    ax.set_title("3. Chunk reuse count")
+
+    # ------------------------------------------------------------------
+    # Plot 4 — Rolling token hit rate over time
+    # ------------------------------------------------------------------
+    ax = axes[1, 0]
+    ax.plot(range(1, len(rolling) + 1), rolling, linewidth=1.5)
+    ax.set_xlabel("Request index")
+    ax.set_ylabel("Cumulative token hit rate (%)")
+    ax.set_title("4. Rolling token hit rate over time")
+    ax.set_ylim(0, 100)
+    ax.grid(True, linestyle="--", alpha=0.5)
+
+    # ------------------------------------------------------------------
+    # Plot 5 — Input length distribution
+    # ------------------------------------------------------------------
+    ax = axes[1, 1]
+    ax.hist(input_lengths, bins=50, edgecolor="black", linewidth=0.4)
+    ax.set_xlabel("Input length (tokens / seq_len)")
+    ax.set_ylabel("Number of requests")
+    ax.set_title("5. Input length per request")
+
+    # ------------------------------------------------------------------
+    # Plot 6 — Global span distribution
+    # ------------------------------------------------------------------
+    ax = axes[1, 2]
+    if global_spans:
+        ax.hist(global_spans, bins=50, edgecolor="black", linewidth=0.4)
+    ax.set_xlabel("Global span (chunks between last store and hit)")
+    ax.set_ylabel("Number of hit chunks")
+    ax.set_title("6. Global span distribution")
+
+    # ------------------------------------------------------------------
+    # Plot 7 — Cache position at hit time
+    # ------------------------------------------------------------------
+    ax = axes[1, 3]
+    if cache_positions:
+        ax.hist(cache_positions, bins=50, edgecolor="black", linewidth=0.4)
+    ax.set_xlabel("Cache position (0 = MRU, max = LRU)")
+    ax.set_ylabel("Number of hit chunks")
+    ax.set_title("7. Cache position at hit")
+
+    fig.tight_layout()
+    fig.savefig(output, dpi=150)
+    print(f"\nStats plot saved to '{output}'")
+
+
+# ---------------------------------------------------------------------------
+# CLI helpers — shared between the module entry point and lmcache tool
+# ---------------------------------------------------------------------------
+
+
+def add_simulate_arguments(parser: argparse.ArgumentParser) -> None:
+    """Register all ``simulate`` CLI flags onto *parser*.
+
+    Called by both the module ``main()`` and by
+    :class:`~lmcache.cli.commands.tool.ToolCommand` so that flag definitions
+    live in exactly one place.
+
+    Args:
+        parser: The ``ArgumentParser`` (or sub-parser) to add flags to.
+    """
+    parser.add_argument(
+        "-i",
+        "--input",
+        nargs="+",
+        required=True,
+        metavar="PATH",
+        help="One or more lookup-hash JSONL files or directories",
+    )
+    parser.add_argument(
+        "-n",
+        "--max-samples",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum number of events to process (default: all)",
+    )
+    parser.add_argument(
+        "--cache-capacity-gib",
+        type=float,
+        required=True,
+        metavar="GiB",
+        help="Cache capacity in gibibytes",
+    )
+    parser.add_argument(
+        "--kv-bytes-per-chunk",
+        type=int,
+        default=None,
+        metavar="BYTES",
+        help=(
+            "Bytes consumed by one cached chunk.  "
+            "Auto-computed from the first event's shapes/dtypes if omitted."
+        ),
+    )
+    parser.add_argument(
+        "--model",
+        default=None,
+        metavar="NAME",
+        help="Filter events by model_name (exact match)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        default="cache_stats.png",
+        metavar="FILE",
+        help="Output image path (default: cache_stats.png)",
+    )
+
+
+def run_simulate(args: argparse.Namespace) -> None:
+    """Execute the simulate workflow from a parsed argument namespace.
+
+    Loads events, resolves ``kv_bytes_per_chunk``, runs the simulator, prints
+    a text report, and saves a statistics PNG.  Called by both the module
+    ``main()`` and by :class:`~lmcache.cli.commands.tool.ToolCommand`.
+
+    Args:
+        args: Parsed CLI arguments.  Must have the attributes registered by
+            :func:`add_simulate_arguments`.
+    """
+    paths = [Path(p) for p in args.input]
+    print(f"Loading lookup events from {[str(p) for p in paths]} …")
+    events = load_lookup_events(paths, model=args.model, max_samples=args.max_samples)
+    print(f"Loaded {len(events):,} event(s)")
+
+    if not events:
+        print("No events to process.")
+        sys.exit(0)
+
+    kv_bpc = args.kv_bytes_per_chunk
+    if kv_bpc is None:
+        kv_bpc = compute_kv_bytes_per_chunk(events[0])
+        if kv_bpc == 0:
+            print(
+                "Error: could not determine kv_bytes_per_chunk from the first event "
+                "(shapes/dtypes are empty).  Pass --kv-bytes-per-chunk explicitly.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        print(f"Auto-detected kv_bytes_per_chunk = {kv_bpc:,} bytes")
+
+    capacity_bytes = int(args.cache_capacity_gib * _GIB)
+
+    print("\nSimulation parameters:")
+    print(
+        f"  Cache capacity     : {args.cache_capacity_gib:.2f} GiB "
+        f"({capacity_bytes:,} bytes)"
+    )
+    print(f"  KV bytes/chunk     : {kv_bpc:,}")
+    chunk_sz = events[0].get("chunk_size", "?")
+    print(f"  Chunk size         : {chunk_sz} tokens")
+    if args.model:
+        print(f"  Model filter       : {args.model}")
+    print()
+
+    results = simulate(events, capacity_bytes, kv_bpc)
+    print_statistics(results)
+    plot_statistics(results, events, args.output)
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """CLI entry point for ``python -m lmcache.tools.cache_simulator.simulator``.
+
+    Parses command-line arguments and delegates to :func:`run_simulate`.
+    """
+    parser = argparse.ArgumentParser(
+        description=(
+            "Simulate LRU token cache hit rate from lookup-hash JSONL logs. "
+            "Prints a text report and saves a multi-panel statistics chart."
+        )
+    )
+    add_simulate_arguments(parser)
+    args = parser.parse_args()
+    run_simulate(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/tools/controller_benchmark/README.md b/lmcache/tools/controller_benchmark/README.md
new file mode 100644
index 0000000..798f3ec
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/README.md
@@ -0,0 +1,161 @@
+# LMCache Controller ZMQ Benchmark Tool
+
+This tool performs load testing on LMCache Controller using ZMQ interface to measure message throughput, latency, and system performance.
+
+## Overview
+
+The benchmark tool simulates multiple instances and workers sending various types of messages to the LMCache Controller:
+
+- **BatchedKVOperationMsg**: admit/evict messages via pull socket
+- **BatchedP2PLookupMsg**: p2p_lookup messages via reply socket
+- **RegisterMsg/DeRegisterMsg/HeartbeatMsg**: worker lifecycle messages
+
+### Key Components
+
+- **constants.py**: Defines ZMQ socket timeouts and other constants
+- **config.py**: `ZMQBenchmarkConfig` dataclass for benchmark configuration
+- **handlers/**: Operation handlers using Strategy Pattern with dynamic discovery
+  - Each operation has its own file (e.g., `admit.py`, `evict.py`)
+  - Automatically discovers and registers all handlers at import time
+  - Add new operations by creating a new handler file - no need to modify existing code
+- **benchmark.py**: `ZMQControllerBenchmark` class with core logic
+- **__main__.py**: Argument parsing and main entry point
+
+## Prerequisites
+
+- A running LMCache Controller instance
+- Python 3.10+
+- Required dependencies: `zmq`, `msgspec`, `psutil`
+
+## Quick Start
+
+### Basic Usage
+- Start the controller
+```bash
+python3 -m lmcache.v1.api_server --host 0.0.0.0 --port 9009 \
+  --monitor-ports "{\"pull\":7555,\"reply\":7556}" \
+  --lmcache-worker-timeout 100 --health-check-interval 10 
+```
+
+- Start the benchmark
+```bash
+python3 -m lmcache.tools.controller_benchmark \
+  --monitor-ports  "{\"pull\":7555,\"reply\":7556}" \
+  --num-instances 50 --num-workers 1 --num-keys 1000000 --batch-size 100 \
+  --operations "admit:35,evict:29,heartbeat:1,p2p_lookup:35"
+```
+
+
+## Command Line Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--controller-host` | `localhost` | Controller host address |
+| `--monitor-ports` | `{"pull":8100,"reply":8101}` | Monitor ports in JSON format |
+| `--duration` | `60` | Benchmark duration in seconds |
+| `--batch-size` | `50` | Number of KV operations per batch message |
+| `--operations` | `admit:70,evict:25,heartbeat:5` | Operation distribution (name:percentage) |
+| `--num-instances` | `10` | Number of instances to simulate |
+| `--num-workers` | `1` | Number of workers per instance |
+| `--num-locations` | `1` | Number of storage locations |
+| `--num-keys` | `10000` | Number of unique keys |
+| `--num-hashes` | `100` | Number of hashes for P2P lookup operations |
+| `--no-register-first` | `false` | Skip pre-registering workers before benchmark |
+
+## Operation Types
+
+The benchmark supports the following operation types:
+
+| Operation | Description                               |
+|-----------|-------------------------------------------|
+| `admit` | Simulates KV cache admission (adds entries) |
+| `evict` | Simulates KV cache eviction (removes entries) |
+| `p2p_lookup` | Simulates p2p batch lookup messages       |
+| `register` | Simulates worker registration             |
+| `deregister` | Simulates worker deregistration           |
+
+### Adding New Operations
+
+To add a new operation, simply create a new handler file in `handlers/` directory:
+
+1. Create `handlers/your_operation.py` implementing `OperationHandler` base class
+2. Define `operation_name` property and implement required methods
+3. The handler will be automatically discovered and registered
+
+No need to modify existing code - the system uses dynamic discovery!
+
+## Output Metrics
+
+The benchmark reports:
+
+- **Overall QPS**: Total messages per second
+- **Per-operation QPS**: Messages per second for each operation type
+- **Latency statistics**: avg, min, max, p95 (in milliseconds)
+- **Error counts**: Number of failed operations
+- **Memory usage**: System memory usage during the test
+
+### Sample Output
+
+The following is a sample output from the benchmark ran in my macbook m4 pro.
+
+```
+================================================================================
+LMCache Controller ZMQ Benchmark Results
+================================================================================
+
+Configuration:
+  Controller URL: 127.0.0.1:7555
+  Duration: 60 seconds
+  Batch Size: 100
+  Operations: {'admit': 35.0, 'evict': 29.0, 'heartbeat': 1.0, 'p2p_lookup': 35.0}
+  Instances: 50, Workers: 1, Locations: 1, Keys: 1000000
+
+Overall Performance:
+  Total Requests: 270035
+  Total Messages: 26736200
+  Total Time: 60.00s
+  Overall RPS (Requests/sec): 4500.58
+  Overall QPS (Messages/sec): 445602.80
+
+Per-Operation Performance:
+  admit:
+    RPS (Requests/sec): 1575.23
+    QPS (Messages/sec): 157523.14
+    Latency - Avg: 0.016ms, Min: 0.007ms, Max: 0.249ms, P95: 0.031ms
+    Errors: 0
+  evict:
+    RPS (Requests/sec): 1305.13
+    QPS (Messages/sec): 130513.18
+    Latency - Avg: 0.016ms, Min: 0.007ms, Max: 1.201ms, P95: 0.031ms
+    Errors: 0
+  heartbeat:
+    RPS (Requests/sec): 45.00
+    QPS (Messages/sec): 45.00
+    Latency - Avg: 0.010ms, Min: 0.003ms, Max: 0.138ms, P95: 0.024ms
+    Errors: 0
+  p2p_lookup:
+    RPS (Requests/sec): 1575.21
+    QPS (Messages/sec): 157521.48
+    Latency - Avg: 0.440ms, Min: 0.150ms, Max: 6.291ms, P95: 0.843ms
+    Errors: 0
+
+System Metrics:
+  Memory Usage - Avg: 62.3%, Max: 63.5%
+================================================================================
+```
+
+## Troubleshooting
+
+### Send Timeout Error
+
+If you see "Send timeout - Controller may not be running", ensure:
+1. The LMCache Controller is running
+2. The `--controller-host` and `--monitor-ports` are correct
+3. No firewall is blocking the connection
+
+### High Error Rate
+
+If you observe high error rates:
+1. Reduce `--batch-size` to decrease message size
+2. Increase controller resources
+3. Check network connectivity
diff --git a/lmcache/tools/controller_benchmark/__init__.py b/lmcache/tools/controller_benchmark/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/tools/controller_benchmark/__main__.py b/lmcache/tools/controller_benchmark/__main__.py
new file mode 100644
index 0000000..3530543
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/__main__.py
@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+"""
+LMCache Controller ZMQ Benchmark Tool - CLI Entry Point
+
+This tool performs load testing on LMCache Controller using ZMQ interface
+to measure message throughput, latency, and system performance.
+
+Test operations:
+- BatchedKVOperationMsg: admit/evict messages via PUSH socket
+- RegisterMsg/DeRegisterMsg/HeartbeatMsg: worker lifecycle messages
+"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Dict, List
+import argparse
+import asyncio
+import json
+import multiprocessing
+import statistics
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.tools.controller_benchmark.benchmark import (
+    BenchmarkResults,
+    OperationStats,
+    ZMQControllerBenchmark,
+)
+from lmcache.tools.controller_benchmark.config import ZMQBenchmarkConfig
+
+logger = init_logger(__name__)
+
+
+def run_single_process(config: ZMQBenchmarkConfig) -> BenchmarkResults:
+    """Run benchmark in a single process and return results"""
+    benchmark = ZMQControllerBenchmark(config)
+    asyncio.run(benchmark.run_benchmark())
+    benchmark.print_results()
+    return benchmark.get_results()
+
+
+def aggregate_results(
+    results_list: List[BenchmarkResults], operations: Dict[str, float]
+) -> BenchmarkResults:
+    """Aggregate results from multiple processes"""
+    aggregated = BenchmarkResults()
+
+    if not results_list:
+        return aggregated
+
+    # Sum up totals
+    aggregated.total_requests = sum(r.total_requests for r in results_list)
+    aggregated.total_messages = sum(r.total_messages for r in results_list)
+    aggregated.total_time = max(r.total_time for r in results_list)
+    aggregated.overall_rps = sum(r.overall_rps for r in results_list)
+    aggregated.overall_qps = sum(r.overall_qps for r in results_list)
+
+    # Aggregate memory usage
+    for r in results_list:
+        aggregated.memory_usage.extend(r.memory_usage)
+
+    # Aggregate per-operation stats
+    for op_name in operations.keys():
+        op_stats_list = [
+            r.operations[op_name] for r in results_list if op_name in r.operations
+        ]
+        if op_stats_list:
+            # Sum QPS and RPS
+            total_qps = sum(s.qps for s in op_stats_list)
+            total_rps = sum(s.rps for s in op_stats_list)
+
+            # Average latencies (weighted by RPS would be more accurate,
+            # but simple average is acceptable)
+            min_latencies = [s.min_latency for s in op_stats_list if s.min_latency > 0]
+            max_latencies = [s.max_latency for s in op_stats_list if s.max_latency > 0]
+            p95_latencies = [s.p95_latency for s in op_stats_list if s.p95_latency > 0]
+
+            aggregated.operations[op_name] = OperationStats(
+                qps=total_qps,
+                rps=total_rps,
+                avg_latency=(
+                    sum(s.avg_latency * s.rps for s in op_stats_list) / total_rps
+                    if total_rps > 0
+                    else 0.0
+                ),
+                min_latency=min(min_latencies) if min_latencies else 0.0,
+                max_latency=max(max_latencies) if max_latencies else 0.0,
+                p95_latency=(
+                    sum(s.p95_latency * s.rps for s in op_stats_list) / total_rps
+                    if total_rps > 0 and p95_latencies
+                    else 0.0
+                ),
+                errors=sum(s.errors for s in op_stats_list),
+            )
+
+    return aggregated
+
+
+def print_aggregated_results(
+    results: BenchmarkResults,
+    config: ZMQBenchmarkConfig,
+    num_processes: int,
+):
+    """Print aggregated benchmark results from all processes"""
+    print("\n" + "=" * 80)
+    print(
+        "LMCache Controller ZMQ Benchmark - AGGREGATED RESULTS (%d processes)"
+        % num_processes
+    )
+    print("=" * 80)
+
+    print("\nConfiguration:")
+    print("  Controller URL: %s" % config.controller_pull_url)
+    print("  Duration: %d seconds" % config.duration)
+    print("  Batch Size: %d" % config.batch_size)
+    print("  Operations: %s" % config.operations)
+    print(
+        "  Instances per process: %d, Workers: %d, Locations: %d, Keys: %d"
+        % (
+            config.num_instances,
+            config.num_workers,
+            config.num_locations,
+            config.num_keys,
+        )
+    )
+    print("  Total Instances: %d" % (config.num_instances * num_processes))
+
+    print("\nAggregated Performance:")
+    print("  Total Requests: %d" % results.total_requests)
+    print("  Total Messages: %d" % results.total_messages)
+    print("  Total Time: %.2fs" % results.total_time)
+    print("  Overall RPS (Requests/sec): %.2f" % results.overall_rps)
+    print("  Overall QPS (Messages/sec): %.2f" % results.overall_qps)
+
+    print("\nPer-Operation Performance (Aggregated):")
+    for op_name in config.operations.keys():
+        if op_name in results.operations:
+            stats = results.operations[op_name]
+            print("  %s:" % op_name)
+            print("    RPS (Requests/sec): %.2f" % stats.rps)
+            print("    QPS (Messages/sec): %.2f" % stats.qps)
+            print(
+                "    Latency - Avg: %.3fms, Min: %.3fms, Max: %.3fms, P95: %.3fms"
+                % (
+                    stats.avg_latency * 1000,
+                    stats.min_latency * 1000,
+                    stats.max_latency * 1000,
+                    stats.p95_latency * 1000,
+                )
+            )
+            print("    Errors: %d" % stats.errors)
+
+    print("\nSystem Metrics (All Processes):")
+    if results.memory_usage:
+        avg_memory = statistics.mean(results.memory_usage)
+        max_memory = max(results.memory_usage)
+        print("  Memory Usage - Avg: %.1f%%, Max: %.1f%%" % (avg_memory, max_memory))
+
+    print("=" * 80)
+
+
+def main():
+    """Main function with argument parsing"""
+    parser = argparse.ArgumentParser(
+        description="LMCache Controller ZMQ Benchmark Tool",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--controller-host",
+        type=str,
+        default="127.0.0.1",
+        help="Controller host address",
+    )
+
+    parser.add_argument(
+        "--monitor-ports",
+        type=str,
+        default='{"pull":8100,"reply":8101}',
+        help='Monitor ports in JSON format, e.g. {"pull":8100,"reply":8101}',
+    )
+
+    parser.add_argument(
+        "--duration",
+        type=int,
+        default=60,
+        help="Benchmark duration in seconds",
+    )
+
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=50,
+        help="Number of KV operations per batch message",
+    )
+
+    parser.add_argument(
+        "--operations",
+        type=str,
+        default="admit:70,evict:25,heartbeat:5",
+        help="Operation distribution (name:percentage comma-separated)",
+    )
+
+    parser.add_argument(
+        "--num-instances",
+        type=int,
+        default=10,
+        help="Number of instances to simulate per process",
+    )
+
+    parser.add_argument(
+        "--num-workers",
+        type=int,
+        default=1,
+        help="Number of workers per instance",
+    )
+
+    parser.add_argument(
+        "--num-locations",
+        type=int,
+        default=1,
+        help="Number of storage locations",
+    )
+
+    parser.add_argument(
+        "--num-keys",
+        type=int,
+        default=10000,
+        help="Number of unique keys",
+    )
+
+    parser.add_argument(
+        "--num-hashes",
+        type=int,
+        default=100,
+        help="Number of hashes for P2P lookup operations",
+    )
+
+    parser.add_argument(
+        "--num-processes",
+        type=int,
+        default=1,
+        help="Number of concurrent benchmark processes",
+    )
+
+    parser.add_argument(
+        "--no-register-first",
+        action="store_true",
+        help="Skip pre-registering workers before benchmark",
+    )
+
+    args = parser.parse_args()
+
+    # Parse monitor ports from JSON
+    try:
+        monitor_ports = json.loads(args.monitor_ports)
+        pull_port = monitor_ports.get("pull", 8100)
+        reply_port = monitor_ports.get("reply")
+        heartbeat_port = monitor_ports.get("heartbeat")
+    except json.JSONDecodeError as e:
+        logger.error("Failed to parse monitor-ports JSON: %s", e)
+        raise ValueError("Invalid monitor-ports format") from e
+
+    # Convert 0.0.0.0 to 127.0.0.1 for client connections
+    client_host = (
+        "127.0.0.1" if args.controller_host == "0.0.0.0" else args.controller_host
+    )
+    controller_pull_url = f"{client_host}:{pull_port}"
+    controller_reply_url = f"{client_host}:{reply_port}" if reply_port else None
+    controller_heartbeat_url = (
+        f"{client_host}:{heartbeat_port}" if heartbeat_port else None
+    )
+
+    # Parse operations
+    operations = {}
+    for op_str in args.operations.split(","):
+        if ":" in op_str:
+            name, percentage = op_str.split(":", 1)
+            operations[name.strip()] = float(percentage.strip())
+
+    num_processes = args.num_processes
+
+    # Create a base config dict
+    base_config_kwargs = {
+        "controller_pull_url": controller_pull_url,
+        "controller_reply_url": controller_reply_url,
+        "controller_heartbeat_url": controller_heartbeat_url,
+        "duration": args.duration,
+        "batch_size": args.batch_size,
+        "operations": operations,
+        "num_instances": args.num_instances,
+        "num_workers": args.num_workers,
+        "num_locations": args.num_locations,
+        "num_keys": args.num_keys,
+        "num_hashes": args.num_hashes,
+        "register_first": not args.no_register_first,
+        "num_processes": num_processes,
+    }
+
+    try:
+        if num_processes == 1:
+            # Single process mode
+            config = ZMQBenchmarkConfig(**base_config_kwargs, process_id=0)
+            run_single_process(config)
+        else:
+            # Multi-process mode
+            logger.info(
+                "Starting multi-process benchmark with %d processes", num_processes
+            )
+            configs = [
+                ZMQBenchmarkConfig(**base_config_kwargs, process_id=i)
+                for i in range(num_processes)
+            ]
+            # Use multiprocessing pool to run benchmarks in parallel
+            with multiprocessing.Pool(processes=num_processes) as pool:
+                results_list = pool.map(run_single_process, configs)
+
+            # Aggregate and print combined results
+            aggregated = aggregate_results(results_list, operations)
+            print_aggregated_results(aggregated, configs[0], num_processes)
+
+    except KeyboardInterrupt:
+        print("\nBenchmark interrupted by user")
+    except Exception as e:
+        logger.error("Benchmark failed: %s", e)
+        raise e
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/tools/controller_benchmark/benchmark.py b/lmcache/tools/controller_benchmark/benchmark.py
new file mode 100644
index 0000000..5f91a52
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/benchmark.py
@@ -0,0 +1,660 @@
+"""Core benchmark class for LMCache Controller ZMQ testing"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+import asyncio
+import random
+import statistics
+import time
+
+# Third Party
+import msgspec
+import psutil
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.message import (
+    DeRegisterMsg,
+    RegisterMsg,
+    RegisterRetMsg,
+)
+from lmcache.v1.cache_controller.utils import KVChunkInfo
+from lmcache.v1.rpc_utils import (
+    close_zmq_socket,
+    get_zmq_context,
+    get_zmq_socket,
+    get_zmq_socket_with_timeout,
+)
+
+# Local
+from .config import ZMQBenchmarkConfig
+from .constants import (
+    DEFAULT_BATCH_SEND_SIZE,
+    DEFAULT_OP_DISTRIBUTION_BASE,
+    DEFAULT_RECV_TIMEOUT_MS,
+    DEFAULT_SEND_HWM,
+    DEFAULT_SEND_TIMEOUT_MS,
+)
+from .handlers import OPERATION_HANDLERS
+from .handlers.base import SocketType
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class TestData:
+    """Test data for benchmark operations"""
+
+    instances: List[str]
+    workers: List[int]
+    locations: List[str]
+    keys: List[int]
+
+
+@dataclass
+class OperationStats:
+    """Statistics for a single operation type"""
+
+    qps: float = 0.0  # messages per second
+    rps: float = 0.0  # requests per second
+    avg_latency: float = 0.0
+    min_latency: float = 0.0
+    max_latency: float = 0.0
+    p95_latency: float = 0.0
+    errors: int = 0
+
+
+@dataclass
+class BenchmarkResults:
+    """Overall benchmark results"""
+
+    total_requests: int = 0
+    total_messages: int = 0
+    total_time: float = 0.0
+    overall_rps: float = 0.0  # requests per second
+    overall_qps: float = 0.0  # messages per second
+    operations: Dict[str, OperationStats] = field(default_factory=dict)
+    memory_usage: List[float] = field(default_factory=list)
+
+
+class ZMQControllerBenchmark:
+    """Benchmark class for LMCache Controller via ZMQ"""
+
+    def __init__(self, config: ZMQBenchmarkConfig):
+        self.config = config
+        self.context: Optional[zmq.asyncio.Context] = None
+        self.push_socket: Optional[Any] = None
+        self.req_socket: Optional[Any] = None
+        self.heartbeat_socket: Optional[Any] = None
+        self.heartbeat_url: Optional[str] = None
+        self.results = BenchmarkResults()
+        self.running = False
+        # Track sequence numbers per KVChunkInfo (instance_id, worker_id, location)
+        self.sequence_numbers: Dict[KVChunkInfo, int] = {}
+
+        # Track registered workers for cleanup
+        self.registered_workers: List[Tuple[str, int, str, int]] = []
+
+    async def setup(self):
+        """Setup ZMQ sockets"""
+        self.context = get_zmq_context(use_asyncio=True)
+        self.push_socket = get_zmq_socket(
+            self.context,
+            self.config.controller_pull_url,
+            protocol="tcp",
+            role=zmq.PUSH,
+            bind_or_connect="connect",
+        )
+        # Set send timeout to avoid blocking indefinitely when controller is down
+        # SNDTIMEO: timeout in milliseconds, 0 means non-blocking
+        self.push_socket.setsockopt(zmq.SNDTIMEO, DEFAULT_SEND_TIMEOUT_MS)
+        # SNDHWM: high watermark for outbound messages
+        self.push_socket.setsockopt(zmq.SNDHWM, DEFAULT_SEND_HWM)
+        logger.info(
+            "Connected to controller PULL socket at %s",
+            self.config.controller_pull_url,
+        )
+
+        # Setup DEALER socket for request-reply operations (e.g., P2P lookup)
+        if self.config.controller_reply_url:
+            self.req_socket = get_zmq_socket_with_timeout(
+                self.context,
+                self.config.controller_reply_url,
+                protocol="tcp",
+                role=zmq.DEALER,
+                bind_or_connect="connect",
+                recv_timeout_ms=DEFAULT_RECV_TIMEOUT_MS,
+                send_timeout_ms=DEFAULT_SEND_TIMEOUT_MS,
+            )
+            logger.info(
+                "Connected to controller ROUTER socket at tcp://%s",
+                self.config.controller_reply_url,
+            )
+            logger.info(
+                "DEALER socket type: %d, last_endpoint: %s",
+                self.req_socket.get(zmq.TYPE),
+                self.req_socket.get_string(zmq.LAST_ENDPOINT, encoding="utf-8"),
+            )
+            # Give ZMQ time to establish the connection
+            time.sleep(0.1)
+
+        # Setup heartbeat DEALER socket if configured
+        if self.config.controller_heartbeat_url:
+            self.heartbeat_url = self.config.controller_heartbeat_url
+            self._setup_heartbeat_socket()
+            logger.info(
+                "Connected to heartbeat ROUTER socket at tcp://%s",
+                self.config.controller_heartbeat_url,
+            )
+
+    def cleanup(self):
+        """Cleanup ZMQ sockets"""
+        if self.push_socket:
+            close_zmq_socket(self.push_socket)
+        if self.req_socket:
+            close_zmq_socket(self.req_socket)
+        if self.heartbeat_socket:
+            close_zmq_socket(self.heartbeat_socket)
+        logger.info("ZMQ sockets closed")
+
+    def generate_test_data(self) -> TestData:
+        """Generate test data based on configuration
+
+        Each process gets a unique range of instance IDs to avoid conflicts.
+        Format: instance_p{process_id}_{instance_index}
+        """
+        process_id = self.config.process_id
+        return TestData(
+            instances=[
+                "instance_p%d_%d" % (process_id, i)
+                for i in range(self.config.num_instances)
+            ],
+            workers=list(range(self.config.num_workers)),
+            locations=["location_%d" % i for i in range(self.config.num_locations)],
+            keys=list(range(self.config.num_keys)),
+        )
+
+    def get_next_sequence_number(
+        self, instance_id: str, worker_id: int, location: str
+    ) -> int:
+        """
+        Get monotonically increasing sequence number for specific
+        instance-worker-location
+        """
+        key = KVChunkInfo(instance_id, worker_id, location)
+        if key not in self.sequence_numbers:
+            self.sequence_numbers[key] = 0
+        seq = self.sequence_numbers[key]
+        self.sequence_numbers[key] += 1
+        return seq
+
+    async def send_messages(self, messages: List[Any]) -> float:
+        """Send multiple messages via ZMQ PUSH socket
+
+        Args:
+            messages: List of messages to send
+
+        Returns:
+            Time taken to send all messages
+
+        Raises:
+            RuntimeError: If socket not initialized or send timeout
+        """
+        if self.push_socket is None:
+            raise RuntimeError("Socket not initialized. Call setup() first.")
+        start_time = time.time()
+        encoded_msgs = [msgspec.msgpack.encode(msg) for msg in messages]
+        try:
+            await self.push_socket.send_multipart(encoded_msgs)
+        except zmq.Again as e:
+            raise RuntimeError(
+                "Send timeout - Controller may not be running at %s"
+                % self.config.controller_pull_url
+            ) from e
+        return time.time() - start_time
+
+    async def send_request(self, message: Any) -> Tuple[float, Any]:
+        """Send a message via ZMQ DEALER socket and wait for reply
+
+        Args:
+            message: Message to send
+
+        Returns:
+            Tuple of (time taken, response)
+
+        Raises:
+            RuntimeError: If socket not initialized or timeout
+            zmq.ZMQError: If DEALER socket error occurs
+        """
+        if self.req_socket is None:
+            raise RuntimeError(
+                "DEALER socket not initialized. "
+                "Ensure controller_reply_url is configured."
+            )
+        start_time = time.time()
+        encoded_msg = msgspec.msgpack.encode(message)
+        logger.debug(
+            "Sending request to %s, message type: %s, size: %d bytes",
+            self.config.controller_reply_url,
+            type(message).__name__,
+            len(encoded_msg),
+        )
+
+        try:
+            # DEALER socket: send [empty_frame, payload]
+            await self.req_socket.send_multipart([b"", encoded_msg])
+            frames = await self.req_socket.recv_multipart()
+            # DEALER receives: [empty_frame, payload]
+            response = frames[-1]
+            logger.debug("Response received, size: %d bytes", len(response))
+            return time.time() - start_time, response
+        except zmq.Again as e:
+            logger.error("Request timeout after waiting for response")
+            raise RuntimeError(
+                "Request timeout - Controller may not be running at %s"
+                % self.config.controller_reply_url
+            ) from e
+        except zmq.ZMQError as e:
+            logger.error("ZMQ error: %s", e)
+            # Re-raise other ZMQ errors
+            raise
+
+    async def register_workers(self, test_data: TestData):
+        """Pre-register all workers before benchmark using DEALER-ROUTER mode"""
+        if not self.config.register_first:
+            return
+
+        if self.req_socket is None:
+            logger.warning(
+                "DEALER socket not initialized, skipping worker registration"
+            )
+            return
+
+        logger.info("Pre-registering workers via REQ-REP...")
+        for instance in test_data.instances:
+            for worker in test_data.workers:
+                ip = "192.168.1.%d" % (worker + 1)
+                port = 10000 + worker
+                peer_port = 20000 + worker
+                peer_init_url = "tcp://%s:%d" % (ip, peer_port)
+                msg = RegisterMsg(
+                    instance_id=instance,
+                    worker_id=worker,
+                    ip=ip,
+                    port=port,
+                    peer_init_url=peer_init_url,
+                )
+                try:
+                    _, response = await self.send_request(msg)
+                    self.registered_workers.append((instance, worker, ip, port))
+                    # Extract heartbeat_url from first successful registration
+                    # (only if not already configured)
+                    if self.heartbeat_url is None and response:
+                        self._process_register_response(response)
+                except (RuntimeError, zmq.ZMQError) as e:
+                    logger.error(
+                        "Failed to register worker %s-%d: %s", instance, worker, e
+                    )
+
+        logger.info("Registered %d workers", len(self.registered_workers))
+        # Setup heartbeat socket after getting heartbeat_url (if not already setup)
+        if self.heartbeat_url and self.heartbeat_socket is None:
+            self._setup_heartbeat_socket()
+        await asyncio.sleep(0.5)
+
+    def _process_register_response(self, response: bytes):
+        """Process RegisterRetMsg to extract heartbeat_url"""
+        try:
+            ret_msg = msgspec.msgpack.decode(response, type=RegisterRetMsg)
+            if ret_msg.extra_config and "heartbeat_url" in ret_msg.extra_config:
+                raw_url = ret_msg.extra_config["heartbeat_url"]
+                # Strip tcp:// prefix if present (get_zmq_socket adds it)
+                if raw_url.startswith("tcp://"):
+                    raw_url = raw_url[6:]
+                # If benchmark connects to localhost but controller returns
+                # a different IP, use localhost for heartbeat as well
+                raw_url = self._normalize_heartbeat_url(raw_url)
+                self.heartbeat_url = raw_url
+                logger.info("Got heartbeat_url from register: %s", self.heartbeat_url)
+        except msgspec.DecodeError as e:
+            logger.warning("Failed to decode RegisterRetMsg: %s", e)
+
+    def _normalize_heartbeat_url(self, heartbeat_url: str) -> str:
+        """Normalize heartbeat URL based on controller connection.
+
+        If benchmark connects to controller via localhost (127.0.0.1),
+        but heartbeat_url contains a different IP (e.g., from get_ip()),
+        replace it with 127.0.0.1 to ensure connectivity.
+
+        Args:
+            heartbeat_url: The heartbeat URL from controller (e.g., "10.0.0.1:7557")
+
+        Returns:
+            Normalized URL (e.g., "127.0.0.1:7557" if connecting locally)
+        """
+        if ":" not in heartbeat_url:
+            return heartbeat_url
+
+        hb_host, hb_port = heartbeat_url.rsplit(":", 1)
+
+        # Check if we're connecting to controller via localhost
+        controller_host = self.config.controller_pull_url.split(":")[0]
+        if controller_host in ("127.0.0.1", "localhost"):
+            # If controller returns a non-localhost IP, use localhost instead
+            if hb_host not in ("127.0.0.1", "localhost"):
+                logger.info(
+                    "Controller returned heartbeat IP %s, "
+                    "but we're connecting locally. Using 127.0.0.1 instead.",
+                    hb_host,
+                )
+                return "127.0.0.1:%s" % hb_port
+
+        return heartbeat_url
+
+    def _setup_heartbeat_socket(self):
+        """Setup heartbeat DEALER socket after getting heartbeat_url from register"""
+        if not self.heartbeat_url or not self.context:
+            logger.warning(
+                "Cannot setup heartbeat socket: heartbeat_url=%s, context=%s",
+                self.heartbeat_url,
+                self.context is not None,
+            )
+            return
+        if self.heartbeat_socket is not None:
+            return  # Already setup
+        logger.info(
+            "Setting up heartbeat DEALER socket to %s, "
+            "recv_timeout=%dms, send_timeout=%dms",
+            self.heartbeat_url,
+            DEFAULT_RECV_TIMEOUT_MS,
+            DEFAULT_SEND_TIMEOUT_MS,
+        )
+        self.heartbeat_socket = get_zmq_socket_with_timeout(
+            self.context,
+            self.heartbeat_url,
+            protocol="tcp",
+            role=zmq.DEALER,
+            bind_or_connect="connect",
+            recv_timeout_ms=DEFAULT_RECV_TIMEOUT_MS,
+            send_timeout_ms=DEFAULT_SEND_TIMEOUT_MS,
+        )
+        logger.info("Heartbeat socket created successfully")
+
+    async def send_heartbeat(self, message: Any) -> Tuple[float, Any]:
+        """Send heartbeat via dedicated heartbeat DEALER socket
+
+        Args:
+            message: HeartbeatMsg to send
+
+        Returns:
+            Tuple of (time taken, response)
+        """
+        if self.heartbeat_socket is None:
+            raise RuntimeError(
+                "Heartbeat socket not initialized. "
+                "heartbeat_url=%s. Register first to get heartbeat_url."
+                % self.heartbeat_url
+            )
+        start_time = time.time()
+        encoded_msg = msgspec.msgpack.encode(message)
+        try:
+            # DEALER socket: send [empty_frame, payload]
+            await self.heartbeat_socket.send_multipart([b"", encoded_msg])
+            frames = await self.heartbeat_socket.recv_multipart()
+            response = frames[-1]
+            return time.time() - start_time, response
+        except zmq.Again as e:
+            raise RuntimeError(
+                "Heartbeat timeout waiting for response from %s" % self.heartbeat_url
+            ) from e
+
+    async def deregister_workers(self):
+        """Deregister all workers after benchmark"""
+        if not self.registered_workers:
+            return
+
+        logger.info("Deregistering workers...")
+        messages = []
+        for instance, worker, ip, port in self.registered_workers:
+            msg = DeRegisterMsg(
+                instance_id=instance,
+                worker_id=worker,
+                ip=ip,
+                port=port,
+            )
+            messages.append(msg)
+
+        # Send in batches
+        for i in range(0, len(messages), DEFAULT_BATCH_SEND_SIZE):
+            batch = messages[i : i + DEFAULT_BATCH_SEND_SIZE]
+            await self.send_messages(batch)
+
+        logger.info("Deregistered %d workers", len(messages))
+        self.registered_workers.clear()
+
+    def _build_operation_distribution(self) -> List[str]:
+        """Build operation distribution list based on percentages"""
+        operations = []
+        for op_name, percentage in self.config.operations.items():
+            count = int(DEFAULT_OP_DISTRIBUTION_BASE * percentage / 100)
+            operations.extend([op_name] * count)
+        random.shuffle(operations)
+        return operations
+
+    async def _execute_operation(
+        self, op_name: str, test_data: TestData
+    ) -> Tuple[int, int, float, Optional[Exception]]:
+        """Execute a single operation
+
+        Returns:
+            Tuple of (message_count, request_count, latency, error)
+        """
+        handler = OPERATION_HANDLERS.get(op_name)
+        if not handler:
+            logger.warning("Unknown operation: %s", op_name)
+            return 0, 0, 0.0, ValueError("Unknown operation")
+
+        try:
+            msg = handler.create_message(self, test_data)
+            socket_type = handler.socket_type
+
+            if socket_type == SocketType.HEARTBEAT:
+                latency, _ = await self.send_heartbeat(msg)
+            elif socket_type == SocketType.DEALER:
+                latency, _ = await self.send_request(msg)
+            else:  # SocketType.PUSH
+                msg_start = time.time()
+                await self.send_messages([msg])
+                latency = time.time() - msg_start
+            return handler.get_message_count(self), 1, latency, None
+        except Exception as e:
+            logger.error("Error in %s: %s", op_name, e)
+            return 0, 0, 0.0, e
+
+    async def run_benchmark(self):
+        """Run the main benchmark"""
+        await self.setup()
+
+        try:
+            test_data = self.generate_test_data()
+
+            # Pre-register workers
+            await self.register_workers(test_data)
+
+            # Build operation distribution
+            operations = self._build_operation_distribution()
+
+            # Initialize tracking
+            latencies: Dict[str, List[float]] = {
+                op: [] for op in self.config.operations.keys()
+            }
+            errors: Dict[str, int] = {op: 0 for op in self.config.operations.keys()}
+            message_counts: Dict[str, int] = {
+                op: 0 for op in self.config.operations.keys()
+            }
+            request_counts: Dict[str, int] = {
+                op: 0 for op in self.config.operations.keys()
+            }
+            total_messages = 0
+            total_requests = 0
+
+            # Start monitoring
+            self.running = True
+            monitoring_task = asyncio.create_task(self.monitor_system())
+
+            start_time = time.time()
+            op_index = 0
+
+            logger.info("Starting benchmark for %d seconds...", self.config.duration)
+
+            while time.time() - start_time < self.config.duration:
+                # Get next operation
+                op_name = operations[op_index % len(operations)]
+                op_index += 1
+
+                msg_count, req_count, latency, error = await self._execute_operation(
+                    op_name, test_data
+                )
+                total_messages += msg_count
+                total_requests += req_count
+                if error:
+                    errors[op_name] += 1
+                else:
+                    latencies[op_name].append(latency)
+                    message_counts[op_name] += msg_count
+                    request_counts[op_name] += req_count
+
+                # Small yield to prevent blocking
+                if op_index % 100 == 0:
+                    await asyncio.sleep(0)
+
+            # Stop monitoring
+            self.running = False
+            monitoring_task.cancel()
+            try:
+                await monitoring_task
+            except asyncio.CancelledError:
+                pass
+
+            # Calculate results
+            total_time = time.time() - start_time
+            overall_qps = total_messages / total_time if total_time > 0 else 0
+            overall_rps = total_requests / total_time if total_time > 0 else 0
+
+            self.results.total_messages = total_messages
+            self.results.total_requests = total_requests
+            self.results.total_time = total_time
+            self.results.overall_qps = overall_qps
+            self.results.overall_rps = overall_rps
+
+            # Per-operation stats
+            for op_name in self.config.operations.keys():
+                if latencies[op_name]:
+                    op_qps = (
+                        message_counts[op_name] / total_time if total_time > 0 else 0
+                    )
+                    op_rps = (
+                        request_counts[op_name] / total_time if total_time > 0 else 0
+                    )
+                    avg_latency = statistics.mean(latencies[op_name])
+
+                    self.results.operations[op_name] = OperationStats(
+                        qps=op_qps,
+                        rps=op_rps,
+                        avg_latency=avg_latency,
+                        min_latency=min(latencies[op_name]),
+                        max_latency=max(latencies[op_name]),
+                        p95_latency=(
+                            statistics.quantiles(latencies[op_name], n=20)[18]
+                            if len(latencies[op_name]) >= 20
+                            else max(latencies[op_name])
+                        ),
+                        errors=errors[op_name],
+                    )
+
+            # Deregister workers
+            await self.deregister_workers()
+
+        finally:
+            self.cleanup()
+
+    async def monitor_system(self):
+        """Monitor system metrics during benchmark"""
+        while self.running:
+            try:
+                memory_usage = psutil.virtual_memory().percent
+                self.results.memory_usage.append(memory_usage)
+            except Exception as e:
+                logger.warning("Failed to get memory usage: %s", e)
+            await asyncio.sleep(1)
+
+    def print_results(self):
+        """Print benchmark results"""
+        print("\n" + "=" * 80)
+        if self.config.num_processes > 1:
+            print(
+                "LMCache Controller ZMQ Benchmark Results (Process %d/%d)"
+                % (self.config.process_id + 1, self.config.num_processes)
+            )
+        else:
+            print("LMCache Controller ZMQ Benchmark Results")
+        print("=" * 80)
+
+        print("\nConfiguration:")
+        print("  Controller URL: %s" % self.config.controller_pull_url)
+        print("  Duration: %d seconds" % self.config.duration)
+        print("  Batch Size: %d" % self.config.batch_size)
+        print("  Operations: %s" % self.config.operations)
+        print(
+            "  Instances: %d, Workers: %d, Locations: %d, Keys: %d"
+            % (
+                self.config.num_instances,
+                self.config.num_workers,
+                self.config.num_locations,
+                self.config.num_keys,
+            )
+        )
+
+        print("\nOverall Performance:")
+        print("  Total Requests: %d" % self.results.total_requests)
+        print("  Total Messages: %d" % self.results.total_messages)
+        print("  Total Time: %.2fs" % self.results.total_time)
+        print("  Overall RPS (Requests/sec): %.2f" % self.results.overall_rps)
+        print("  Overall QPS (Messages/sec): %.2f" % self.results.overall_qps)
+
+        print("\nPer-Operation Performance:")
+        for op_name in self.config.operations.keys():
+            if op_name in self.results.operations:
+                stats = self.results.operations[op_name]
+                print("  %s:" % op_name)
+                print("    RPS (Requests/sec): %.2f" % stats.rps)
+                print("    QPS (Messages/sec): %.2f" % stats.qps)
+                print(
+                    "    Latency - Avg: %.3fms, Min: %.3fms, Max: %.3fms, P95: %.3fms"
+                    % (
+                        stats.avg_latency * 1000,
+                        stats.min_latency * 1000,
+                        stats.max_latency * 1000,
+                        stats.p95_latency * 1000,
+                    )
+                )
+                print("    Errors: %d" % stats.errors)
+
+        print("\nSystem Metrics:")
+        if self.results.memory_usage:
+            avg_memory = statistics.mean(self.results.memory_usage)
+            max_memory = max(self.results.memory_usage)
+            print(
+                "  Memory Usage - Avg: %.1f%%, Max: %.1f%%" % (avg_memory, max_memory)
+            )
+
+        print("=" * 80)
+
+    def get_results(self) -> BenchmarkResults:
+        """Return benchmark results for aggregation"""
+        return self.results
diff --git a/lmcache/tools/controller_benchmark/config.py b/lmcache/tools/controller_benchmark/config.py
new file mode 100644
index 0000000..8bce5d7
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/config.py
@@ -0,0 +1,44 @@
+"""Configuration for LMCache Controller ZMQ Benchmark"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+
+
+@dataclass
+class ZMQBenchmarkConfig:
+    """Configuration for ZMQ benchmark parameters"""
+
+    controller_pull_url: str
+    controller_reply_url: Optional[str]
+    duration: int
+    batch_size: int
+    num_instances: int
+    num_workers: int
+    num_locations: int
+    num_keys: int
+    controller_heartbeat_url: Optional[str] = None
+    num_hashes: int = 100
+    operations: Dict[str, float] = field(default_factory=dict)
+    heartbeat_interval: float = 1.0
+    register_first: bool = True
+    # Multi-process settings
+    num_processes: int = 1
+    process_id: int = 0
+
+    def __post_init__(self):
+        if not self.operations:
+            # Default: 70% admit, 25% evict, 5% heartbeat
+            self.operations = {
+                "admit": 70.0,
+                "evict": 25.0,
+                "heartbeat": 5.0,
+            }
+        # Validate operation percentages sum to 100
+        total_percentage = sum(self.operations.values())
+        if abs(total_percentage - 100.0) > 0.01:
+            raise ValueError(
+                "Operation percentages must sum to 100, got: %s" % total_percentage
+            )
diff --git a/lmcache/tools/controller_benchmark/constants.py b/lmcache/tools/controller_benchmark/constants.py
new file mode 100644
index 0000000..e2b21fa
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/constants.py
@@ -0,0 +1,10 @@
+"""Constants for LMCache Controller ZMQ Benchmark"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# ZMQ socket configuration
+DEFAULT_SEND_TIMEOUT_MS = 5000
+DEFAULT_RECV_TIMEOUT_MS = 5000
+DEFAULT_SEND_HWM = 10000
+DEFAULT_BATCH_SEND_SIZE = 50
+DEFAULT_OP_DISTRIBUTION_BASE = 1000
diff --git a/lmcache/tools/controller_benchmark/handlers/__init__.py b/lmcache/tools/controller_benchmark/handlers/__init__.py
new file mode 100644
index 0000000..ac65a9e
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/__init__.py
@@ -0,0 +1,31 @@
+"""Operation handlers with dynamic discovery and registration"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Dict
+
+# First Party
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+# Local
+from .base import OperationHandler
+
+# Operation handler registry
+OPERATION_HANDLERS: Dict[str, OperationHandler] = {}
+
+
+def _discover_and_register_handlers():
+    """Dynamically discover and register all operation handlers"""
+    for cls in discover_subclasses(
+        __name__,
+        OperationHandler,
+        module_filter=lambda name: name != "base",
+        require_defined_in_module=False,
+    ):
+        handler = cls()
+        OPERATION_HANDLERS[handler.operation_name] = handler
+
+
+# Auto-discover and register handlers on import
+_discover_and_register_handlers()
diff --git a/lmcache/tools/controller_benchmark/handlers/admit.py b/lmcache/tools/controller_benchmark/handlers/admit.py
new file mode 100644
index 0000000..1f09087
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/admit.py
@@ -0,0 +1,52 @@
+"""Admit operation handler"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any
+import random
+
+# First Party
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    KVOpEvent,
+    OpType,
+)
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+# Local
+from .base import OperationHandler
+
+
+class AdmitHandler(OperationHandler):
+    """Handler for admit operations"""
+
+    @property
+    def operation_name(self) -> str:
+        return "admit"
+
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        instance = random.choice(test_data.instances)
+        worker = random.choice(test_data.workers)
+        location = random.choice(test_data.locations)
+
+        operations = []
+        for _ in range(benchmark.config.batch_size):
+            key = random.choice(test_data.keys)
+            seq_num = benchmark.get_next_sequence_number(instance, worker, location)
+            operations.append(KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=seq_num))
+
+        return BatchedKVOperationMsg(
+            instance_id=instance,
+            worker_id=worker,
+            location=location,
+            operations=operations,
+        )
+
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        return benchmark.config.batch_size
diff --git a/lmcache/tools/controller_benchmark/handlers/base.py b/lmcache/tools/controller_benchmark/handlers/base.py
new file mode 100644
index 0000000..9ae3644
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/base.py
@@ -0,0 +1,47 @@
+"""Base handler class for benchmark operations (Strategy Pattern)"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from abc import ABC, abstractmethod
+from enum import Enum, auto
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+
+class SocketType(Enum):
+    """Socket type for benchmark operations"""
+
+    PUSH = auto()  # PUSH socket for fire-and-forget messages
+    DEALER = auto()  # DEALER socket for async request-reply messages
+    HEARTBEAT = auto()  # Dedicated heartbeat DEALER socket
+
+
+class OperationHandler(ABC):
+    """Base class for benchmark operation handlers (Strategy Pattern)"""
+
+    @property
+    @abstractmethod
+    def operation_name(self) -> str:
+        """Return the operation name for registration"""
+        pass
+
+    @abstractmethod
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        """Create a message for this operation"""
+        pass
+
+    @abstractmethod
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        """Get the number of messages in a single operation"""
+        pass
+
+    @property
+    def socket_type(self) -> SocketType:
+        """Return the socket type for this operation (default: PUSH)"""
+        return SocketType.PUSH
diff --git a/lmcache/tools/controller_benchmark/handlers/deregister.py b/lmcache/tools/controller_benchmark/handlers/deregister.py
new file mode 100644
index 0000000..212a336
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/deregister.py
@@ -0,0 +1,49 @@
+"""Deregister operation handler"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any
+import random
+
+# First Party
+from lmcache.v1.cache_controller.message import DeRegisterMsg
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+# Local
+from .base import OperationHandler
+
+
+class DeregisterHandler(OperationHandler):
+    """Handler for deregister operations"""
+
+    @property
+    def operation_name(self) -> str:
+        return "deregister"
+
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        instance = random.choice(test_data.instances)
+        worker = random.choice(test_data.workers)
+        ip, port = self._generate_random_endpoint()
+
+        return DeRegisterMsg(
+            instance_id=instance,
+            worker_id=worker,
+            ip=ip,
+            port=port,
+        )
+
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        return 1
+
+    @staticmethod
+    def _generate_random_endpoint():
+        """Generate random IP and port for test messages"""
+        ip = "192.168.%d.%d" % (random.randint(1, 255), random.randint(1, 255))
+        port = random.randint(10000, 60000)
+        return ip, port
diff --git a/lmcache/tools/controller_benchmark/handlers/evict.py b/lmcache/tools/controller_benchmark/handlers/evict.py
new file mode 100644
index 0000000..07711c2
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/evict.py
@@ -0,0 +1,52 @@
+"""Evict operation handler"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any
+import random
+
+# First Party
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    KVOpEvent,
+    OpType,
+)
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+# Local
+from .base import OperationHandler
+
+
+class EvictHandler(OperationHandler):
+    """Handler for evict operations"""
+
+    @property
+    def operation_name(self) -> str:
+        return "evict"
+
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        instance = random.choice(test_data.instances)
+        worker = random.choice(test_data.workers)
+        location = random.choice(test_data.locations)
+
+        operations = []
+        for _ in range(benchmark.config.batch_size):
+            key = random.choice(test_data.keys)
+            seq_num = benchmark.get_next_sequence_number(instance, worker, location)
+            operations.append(KVOpEvent(op_type=OpType.EVICT, key=key, seq_num=seq_num))
+
+        return BatchedKVOperationMsg(
+            instance_id=instance,
+            worker_id=worker,
+            location=location,
+            operations=operations,
+        )
+
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        return benchmark.config.batch_size
diff --git a/lmcache/tools/controller_benchmark/handlers/heartbeat.py b/lmcache/tools/controller_benchmark/handlers/heartbeat.py
new file mode 100644
index 0000000..3b39eed
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/heartbeat.py
@@ -0,0 +1,56 @@
+"""Heartbeat operation handler"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any
+import random
+
+# First Party
+from lmcache.v1.cache_controller.message import HeartbeatMsg
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+# Local
+from .base import OperationHandler, SocketType
+
+
+class HeartbeatHandler(OperationHandler):
+    """Handler for heartbeat operations (dedicated heartbeat socket)"""
+
+    @property
+    def operation_name(self) -> str:
+        return "heartbeat"
+
+    @property
+    def socket_type(self) -> SocketType:
+        return SocketType.HEARTBEAT
+
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        instance = random.choice(test_data.instances)
+        worker = random.choice(test_data.workers)
+        ip, port = self._generate_random_endpoint()
+        peer_ip, peer_port = self._generate_random_endpoint()
+        peer_init_url = "tcp://%s:%d" % (peer_ip, peer_port)
+
+        return HeartbeatMsg(
+            instance_id=instance,
+            worker_id=worker,
+            ip=ip,
+            port=port,
+            peer_init_url=peer_init_url,
+        )
+
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        return 1
+
+    @staticmethod
+    def _generate_random_endpoint():
+        """Generate random IP and port for test messages"""
+        ip = "192.168.%d.%d" % (random.randint(1, 255), random.randint(1, 255))
+        port = random.randint(10000, 60000)
+        return ip, port
diff --git a/lmcache/tools/controller_benchmark/handlers/p2p_lookup.py b/lmcache/tools/controller_benchmark/handlers/p2p_lookup.py
new file mode 100644
index 0000000..fa4d192
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/p2p_lookup.py
@@ -0,0 +1,47 @@
+"""P2P lookup operation handler"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any
+import random
+
+# First Party
+from lmcache.v1.cache_controller.message import BatchedP2PLookupMsg
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+# Local
+from .base import OperationHandler, SocketType
+
+
+class P2PLookupHandler(OperationHandler):
+    """Handler for P2P lookup operations (uses DEALER-ROUTER socket)"""
+
+    @property
+    def operation_name(self) -> str:
+        return "p2p_lookup"
+
+    @property
+    def socket_type(self) -> SocketType:
+        return SocketType.DEALER
+
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        instance = random.choice(test_data.instances)
+        worker = random.choice(test_data.workers)
+        hashes = [
+            random.choice(test_data.keys) for _ in range(benchmark.config.num_hashes)
+        ]
+
+        return BatchedP2PLookupMsg(
+            hashes=hashes,
+            instance_id=instance,
+            worker_id=worker,
+        )
+
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        return benchmark.config.num_hashes
diff --git a/lmcache/tools/controller_benchmark/handlers/register.py b/lmcache/tools/controller_benchmark/handlers/register.py
new file mode 100644
index 0000000..df68260
--- /dev/null
+++ b/lmcache/tools/controller_benchmark/handlers/register.py
@@ -0,0 +1,56 @@
+"""Register operation handler"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any
+import random
+
+# First Party
+from lmcache.v1.cache_controller.message import RegisterMsg
+
+if TYPE_CHECKING:
+    # Local
+    from ..benchmark import TestData, ZMQControllerBenchmark
+
+# Local
+from .base import OperationHandler, SocketType
+
+
+class RegisterHandler(OperationHandler):
+    """Handler for register operations (DEALER-ROUTER mode)"""
+
+    @property
+    def operation_name(self) -> str:
+        return "register"
+
+    @property
+    def socket_type(self) -> SocketType:
+        return SocketType.DEALER
+
+    def create_message(
+        self, benchmark: "ZMQControllerBenchmark", test_data: "TestData"
+    ) -> Any:
+        instance = random.choice(test_data.instances)
+        worker = random.choice(test_data.workers)
+        ip, port = self._generate_random_endpoint()
+        peer_ip, peer_port = self._generate_random_endpoint()
+        peer_init_url = "tcp://%s:%d" % (peer_ip, peer_port)
+
+        return RegisterMsg(
+            instance_id=instance,
+            worker_id=worker,
+            ip=ip,
+            port=port,
+            peer_init_url=peer_init_url,
+        )
+
+    def get_message_count(self, benchmark: "ZMQControllerBenchmark") -> int:
+        return 1
+
+    @staticmethod
+    def _generate_random_endpoint():
+        """Generate random IP and port for test messages"""
+        ip = "192.168.%d.%d" % (random.randint(1, 255), random.randint(1, 255))
+        port = random.randint(10000, 60000)
+        return ip, port
diff --git a/lmcache/tools/mp_status_viewer/__init__.py b/lmcache/tools/mp_status_viewer/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/tools/mp_status_viewer/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/tools/mp_status_viewer/__main__.py b/lmcache/tools/mp_status_viewer/__main__.py
new file mode 100644
index 0000000..bdd7372
--- /dev/null
+++ b/lmcache/tools/mp_status_viewer/__main__.py
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+CLI tool to fetch and display the MP cache server status.
+
+Usage:
+    python -m lmcache.tools.mp_status_viewer [--url URL]
+"""
+
+# Standard
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+
+HEALTHY = "\033[32mHEALTHY\033[0m"
+UNHEALTHY = "\033[31mUNHEALTHY\033[0m"
+
+INDENT = "  "
+
+
+def _health_str(is_healthy: bool) -> str:
+    return HEALTHY if is_healthy else UNHEALTHY
+
+
+def _fmt_bytes(n: int) -> str:
+    if n >= 1024**3:
+        return f"{n / 1024**3:.2f} GB"
+    if n >= 1024**2:
+        return f"{n / 1024**2:.2f} MB"
+    if n >= 1024:
+        return f"{n / 1024:.2f} KB"
+    return f"{n} B"
+
+
+def _print_section(title: str, data: dict, depth: int = 0) -> None:
+    prefix = INDENT * depth
+    health = _health_str(data.get("is_healthy", True))
+    print(f"{prefix}{title}  [{health}]")
+
+    for key, value in data.items():
+        if key == "is_healthy":
+            continue
+        if isinstance(value, dict):
+            _print_section(key, value, depth + 1)
+        elif isinstance(value, list) and value and isinstance(value[0], dict):
+            for i, item in enumerate(value):
+                _print_section(f"{key}[{i}]", item, depth + 1)
+        else:
+            display = value
+            if "bytes" in key.lower() and isinstance(value, (int, float)):
+                display = _fmt_bytes(int(value))
+            elif isinstance(value, float):
+                display = f"{value:.4f}"
+            print(f"{prefix}{INDENT}{key}: {display}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Fetch and display LMCache MP server status"
+    )
+    parser.add_argument(
+        "--url",
+        type=str,
+        default="http://localhost:8000/status",
+        help="URL of the status endpoint",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output raw JSON instead of formatted view",
+    )
+    args = parser.parse_args()
+
+    try:
+        req = urllib.request.Request(args.url)
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode())
+    except urllib.error.URLError as e:
+        print(f"Error connecting to {args.url}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        print(json.dumps(data, indent=2))
+        return
+
+    print("=" * 60)
+    print("  LMCache MP Server Status")
+    print("=" * 60)
+    _print_section("engine", data)
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/tools/simple_discover_service.py b/lmcache/tools/simple_discover_service.py
new file mode 100644
index 0000000..ec9e6ec
--- /dev/null
+++ b/lmcache/tools/simple_discover_service.py
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import datetime
+
+# Third Party
+from flask import Flask, jsonify, request
+
+app = Flask(__name__)
+
+# Global variable to store heartbeat data
+HEARTBEAT_DATA = {}
+
+
+@app.route("/lmcache_heartbeat", methods=["GET"])
+@app.route("/heartbeat", methods=["GET"])
+def record_heartbeat():
+    api_address = request.args.get("api_address")
+    pid = request.args.get("pid", type=int)
+    version = request.args.get("version", "1.0.0")
+    other_info = request.args.get("other_info", "{}")
+
+    if api_address:
+        HEARTBEAT_DATA[api_address] = {
+            "pid": pid,
+            "version": version,
+            "otherInfo": other_info,
+            "lastReportTime": datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        }
+    return jsonify({"status": "success"})
+
+
+@app.route("/lmcache_infos", methods=["GET"])
+def get_lmcache_infos():
+    hour = request.args.get("hour", type=int)
+    minute = request.args.get("minute", type=int)
+
+    if hour is not None:
+        threshold = datetime.datetime.now() - datetime.timedelta(hours=hour)
+    elif minute is not None:
+        threshold = datetime.datetime.now() - datetime.timedelta(minutes=minute)
+    else:
+        # Format HEARTBEAT_DATA to match MOCK_DATA structure
+        process_infos = {}
+        for api_address, data in HEARTBEAT_DATA.items():
+            process_infos[api_address] = {
+                "count": 1,
+                "lmCacheInfoEntities": [
+                    {
+                        "ipAddress": None,
+                        "pid": data.get("pid"),
+                        "apiAddress": api_address,
+                        "version": data.get("version", "1.0.0"),
+                        "startTime": data.get(
+                            "startTime",
+                            datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                        ),
+                        "lastReportTime": datetime.datetime.now().strftime(
+                            "%Y-%m-%d %H:%M:%S"
+                        ),
+                        "otherInfo": data.get("otherInfo", "{}"),
+                    }
+                ],
+            }
+        return jsonify(
+            {
+                "processCount": len(HEARTBEAT_DATA),
+                "versionCount": len(HEARTBEAT_DATA),
+                "processInfos": process_infos,
+                "versions": None,
+            }
+        )
+
+    # Filter data based on threshold
+    filtered_data = {
+        "processCount": 0,
+        "versionCount": 0,
+        "processInfos": {},
+        "versions": None,
+    }
+
+    for api_address, data in HEARTBEAT_DATA.items():
+        last_report_time = datetime.datetime.strptime(
+            data.get(
+                "lastReportTime", datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            ),
+            "%Y-%m-%d %H:%M:%S",
+        )
+        if last_report_time >= threshold:
+            filtered_data["processInfos"][api_address] = {
+                "count": 1,
+                "lmCacheInfoEntities": [
+                    {
+                        "ipAddress": None,
+                        "pid": data.get("pid"),
+                        "apiAddress": api_address,
+                        "version": data.get("version", "1.0.0"),
+                        "startTime": data.get(
+                            "startTime",
+                            datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                        ),
+                        "lastReportTime": last_report_time.strftime(
+                            "%Y-%m-%d %H:%M:%S"
+                        ),
+                        "otherInfo": data.get("otherInfo", "{}"),
+                    }
+                ],
+            }
+            filtered_data["processCount"] += 1
+
+    return jsonify(filtered_data)
+
+
+if __name__ == "__main__":
+    # Bind on all interfaces so remote peers (e.g. the MP server running
+    # on another host) can report heartbeats. ``debug=False`` avoids
+    # spawning Flask's reloader, which can double-launch the process
+    # inside containers.
+    app.run(host="0.0.0.0", port=5000, debug=False)
diff --git a/lmcache/tools/transfer_channel_benchmark/README.md b/lmcache/tools/transfer_channel_benchmark/README.md
new file mode 100644
index 0000000..f2caf0b
--- /dev/null
+++ b/lmcache/tools/transfer_channel_benchmark/README.md
@@ -0,0 +1,128 @@
+# Transfer Channel Throughput Benchmark
+
+Measures read throughput (GB/s) of the LMCache **transfer channel**
+(`lmcache/v1/distributed/transfer_channel/`) for batched peer-to-peer reads.
+
+Unlike a raw-tensor microbenchmark, this tool uses LMCache's `L1MemoryManager`
+to initialize the registered memory region and to **allocate the transferred
+objects** on both sides, so it exercises the same memory path production uses.
+
+## How it works
+
+The benchmark runs as **two separate processes**:
+
+- **server** — uses an `L1MemoryManager` to allocate a registered L1 buffer and
+  a pool of source memory objects, registers the buffer with the transfer
+  channel, and publishes the source object catalog (`offset`/`size` per object)
+  over a small ZMQ side-channel.
+- **client** — fetches the catalog, allocates its own destination objects via an
+  `L1MemoryManager`, connects the transfer channel, and repeatedly reads a random
+  `--num-objects` subset of the source objects, then reports throughput.
+
+A side-channel is needed because the transfer channel handshake only exchanges
+the whole-buffer registration, not per-object offsets.
+
+> Only the `nixl` transfer channel type is registered today. The tool is generic
+> over `--transfer-channel-type`; an unknown type raises a clear error.
+
+## Usage
+
+Run via the module or the `lmcache` CLI. Start the server first.
+
+### `python -m`
+
+```bash
+# terminal 1 — server
+python -m lmcache.tools.transfer_channel_benchmark \
+  --role server --transfer-channel-type nixl \
+  --url 0.0.0.0:7600 --control-url 0.0.0.0:7610 \
+  --buffer-size 2GB --page-size 512KB --object-size 10MB
+
+# terminal 2 — client
+python -m lmcache.tools.transfer_channel_benchmark \
+  --role client --transfer-channel-type nixl \
+  --url 127.0.0.1:7600 --control-url 127.0.0.1:7610 \
+  --listen-url 0.0.0.0:7601 \
+  --page-size 512KB --object-size 10MB \
+  --num-objects 10 --iters 3 --warmup 1
+```
+
+### `lmcache tool`
+
+```bash
+lmcache tool transfer-channel-benchmark --role server  --url 0.0.0.0:7600 \
+  --control-url 0.0.0.0:7610 --buffer-size 2GB --object-size 10MB
+lmcache tool transfer-channel-benchmark --role client --url 127.0.0.1:7600 \
+  --control-url 127.0.0.1:7610 --object-size 10MB --num-objects 10
+```
+
+The server always writes a deterministic per-object byte pattern (object index
+mod 256) into its source objects, so adding `--verify` on the **client** checks
+the transferred bytes against that pattern (no `--verify` needed on the server).
+
+## Key options
+
+| Option | Role | Meaning |
+| --- | --- | --- |
+| `--role {server,client}` | both | Which side to run (required). |
+| `--transfer-channel-type` | both | Implementation to benchmark (default `nixl`). |
+| `--nixl-backend` | both | nixl backend, e.g. `UCX` (nixl-specific). |
+| `--url` | both | Server binds its transfer-channel server here; client dials it. |
+| `--listen-url` | client | Client's own (mandatory) transfer-channel server bind. |
+| `--control-url` | both | Catalog side-channel: server binds, client connects. |
+| `--buffer-size` | server | Registered L1 source buffer size (e.g. `8GB`). |
+| `--page-size` | both | Page / alignment size; **must match** on both sides. |
+| `--object-size` | both | Per-object size; multiple of `--page-size`. |
+| `--num-objects` | client | Objects transferred per read. |
+| `--num-source-objects` | server | Source pool size (default `5 * --num-objects`). |
+| `--iters` / `--warmup` | client | Measured / warmup read iterations. |
+| `--seed` | client | RNG seed for the read subset. |
+| `--verify` | client | Verify transferred bytes against the server's known pattern. |
+| `--use-lazy` | both | Use the lazy L1 allocator (experimental for registration). |
+| `--server-timeout` | server | Seconds to serve catalog requests before exiting. |
+
+## Notes
+
+- `--page-size` must be identical on server and client (enforced via the catalog
+  handshake) so remote page-index math lines up.
+- With the default (non-lazy) allocator the whole `--buffer-size` is allocated up
+  front and may be CUDA-pinned; keep it within available host memory.
+- Requires a working transfer channel runtime (for `nixl`, a UCX backend).
+
+## Performance: NUMA placement
+
+On a multi-NUMA host with NICs spread across nodes (e.g. an 8-NIC, 2-socket
+box), run **both** the server and client under `numactl --interleave=all`:
+
+```bash
+numactl --interleave=all \
+python -m lmcache.tools.transfer_channel_benchmark --role server ...
+```
+
+Without it the registered buffer is allocated on a single NUMA node, so only the
+rails local to that node reach full bandwidth and the rest are throttled by the
+cross-socket link — roughly halving throughput. In testing on a 2-NUMA / 8-rail
+host this was the difference between **~110 GB/s** (no interleave) and
+**~210 GB/s** (`--interleave=all`), with everything else identical. Page size
+only matters in the small regime (descriptor-bound below ~64KB); from ~128KB up
+the transfer is bandwidth-bound and flat.
+
+## Troubleshooting
+
+- **Client hangs after "connected" or during connect, then raises
+  `TimeoutError` after ~60s.** The transfer-channel handshake could not reach the
+  server. Check that `--url`/`--control-url` on the client point at the *server's*
+  reachable address (a common mistake is a typo such as a trailing dot:
+  `10.0.0.5.:7600`), that the server is running, and that the ports are open
+  between hosts:
+  ```bash
+  nc -vz <server-host> 7600   # transfer channel
+  nc -vz <server-host> 7610   # catalog side-channel
+  ```
+  The handshake has a fixed 60s timeout, so a misconfiguration fails with a clear
+  error instead of hanging forever.
+- **`page_size`/`object_size` mismatch error.** The client validates these against
+  the server's catalog; pass the same `--page-size` and `--object-size` on both.
+- **Allocation `RuntimeError` on the server.** The source pool
+  (`--num-source-objects` × `--object-size`) must fit in `--buffer-size`; increase
+  the buffer or reduce the pool/object size.
diff --git a/lmcache/tools/transfer_channel_benchmark/__init__.py b/lmcache/tools/transfer_channel_benchmark/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/tools/transfer_channel_benchmark/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/tools/transfer_channel_benchmark/__main__.py b/lmcache/tools/transfer_channel_benchmark/__main__.py
new file mode 100644
index 0000000..3769a32
--- /dev/null
+++ b/lmcache/tools/transfer_channel_benchmark/__main__.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``python -m lmcache.tools.transfer_channel_benchmark`` entry point."""
+
+# Standard
+import argparse
+import sys
+
+# First Party
+# Only the torch-free config module is imported eagerly so that `-h` works
+# without torch installed. The runtime (which needs torch) is imported after
+# arguments are parsed.
+from lmcache.tools.transfer_channel_benchmark.config import add_benchmark_arguments
+
+
+def main() -> int:
+    """Parse arguments and run the transfer channel benchmark.
+
+    Returns:
+        Process exit code (0 on success, 1 on failure).
+    """
+    parser = argparse.ArgumentParser(
+        prog="python -m lmcache.tools.transfer_channel_benchmark",
+        description="Throughput benchmark for the LMCache transfer channel.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    add_benchmark_arguments(parser)
+    args = parser.parse_args()
+
+    # Imported here (not at module load) so this entry point can show --help
+    # without requiring torch; importing it raises a clear error if torch is
+    # missing.
+    # First Party
+    from lmcache.tools.transfer_channel_benchmark.benchmark import run_benchmark
+
+    return 0 if run_benchmark(args) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/lmcache/tools/transfer_channel_benchmark/benchmark.py b/lmcache/tools/transfer_channel_benchmark/benchmark.py
new file mode 100644
index 0000000..ab3519c
--- /dev/null
+++ b/lmcache/tools/transfer_channel_benchmark/benchmark.py
@@ -0,0 +1,385 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Core logic for the transfer channel throughput benchmark.
+
+A *server* process uses an :class:`L1MemoryManager` to initialize a registered
+L1 region, allocates a pool of source memory objects in it, registers the
+region with a transfer channel, and publishes the source object catalog
+(offset/size per object) over a small ZMQ side-channel.
+
+A *client* process fetches the catalog, allocates its own destination objects
+via an :class:`L1MemoryManager`, connects the transfer channel, and issues
+batched reads of a random subset of the source objects, reporting aggregate
+read throughput in GB/s.
+"""
+
+# Standard
+import argparse
+import json
+import random
+import time
+
+# Third Party
+import zmq
+
+# torch is an optional dependency for this benchmark tool. It (and the
+# distributed runtime imported below, which also needs torch) is imported here
+# rather than in config.py so the `lmcache` CLI can register this tool without
+# torch installed. Raise a clear, actionable error if it is missing.
+try:
+    # Third Party
+    import torch
+except ImportError as err:
+    raise ImportError(
+        "PyTorch is required to run the transfer channel benchmark but is not "
+        "installed. Install it (e.g. `pip install torch`) and retry."
+    ) from err
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.tools.transfer_channel_benchmark.config import (
+    BenchmarkConfig,
+    build_config,
+)
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.config import L1MemoryManagerConfig
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.memory_manager import L1MemoryManager
+from lmcache.v1.distributed.transfer_channel import (
+    TransferChannelAddress,
+    delete_transfer_channel_context,
+    initialize_transfer_channel_context,
+)
+
+logger = init_logger(__name__)
+
+_CATALOG_REQUEST = b"catalog"
+_LARGE_LAZY_INIT = 20 * 1024**3
+_CLIENT_BUFFER_SLACK = 64 * 1024**2
+
+
+############################################################
+# Helpers
+############################################################
+def _zmq_endpoint(url: str) -> str:
+    """Return a ZMQ tcp endpoint for a ``host:port`` (or pass-through url)."""
+    return url if "://" in url else f"tcp://{url}"
+
+
+def _gbps(num_bytes: int, seconds: float) -> float:
+    """Return throughput in GB/s (decimal GB) for ``num_bytes`` over ``seconds``."""
+    return (num_bytes / 1e9) / seconds if seconds > 0 else float("inf")
+
+
+def _create_l1_manager(cfg: BenchmarkConfig, size_bytes: int) -> L1MemoryManager:
+    """Create an L1 memory manager sized to ``size_bytes`` for this benchmark."""
+    manager_config = L1MemoryManagerConfig(
+        size_in_bytes=size_bytes,
+        use_lazy=cfg.use_lazy,
+        init_size_in_bytes=min(_LARGE_LAZY_INIT, size_bytes),
+        align_bytes=cfg.page_size,
+    )
+    return L1MemoryManager(manager_config)
+
+
+def _object_layout(cfg: BenchmarkConfig) -> MemoryLayoutDesc:
+    """Return the layout for a single ``object_size``-byte uint8 object."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([cfg.object_size])], dtypes=[torch.uint8]
+    )
+
+
+############################################################
+# Server
+############################################################
+def server_main(cfg: BenchmarkConfig) -> None:
+    """Run the benchmark server: register a buffer and serve its catalog.
+
+    Args:
+        cfg: The benchmark configuration (``role == "server"``).
+
+    Raises:
+        RuntimeError: If the source pool cannot be allocated in the buffer.
+    """
+    pool_bytes = cfg.num_source_objects * cfg.object_size
+    if pool_bytes > cfg.buffer_size:
+        raise RuntimeError(
+            f"source pool ({pool_bytes / 1e9:.2f} GB = {cfg.num_source_objects} "
+            f"x {cfg.object_size / 1024**2:.1f} MiB) does not fit in the "
+            f"{cfg.buffer_size / 1e9:.2f} GB buffer; increase --buffer-size or "
+            f"reduce --num-source-objects / --object-size."
+        )
+
+    logger.debug(
+        "Allocating L1 buffer (%.2f GB) and %d source objects",
+        cfg.buffer_size / 1e9,
+        cfg.num_source_objects,
+    )
+    manager = _create_l1_manager(cfg, cfg.buffer_size)
+    source_objs: list = []
+    try:
+        error, source_objs = manager.allocate(
+            _object_layout(cfg), cfg.num_source_objects
+        )
+        if error != L1Error.SUCCESS:
+            raise RuntimeError(
+                f"Failed to allocate {cfg.num_source_objects} source objects: "
+                f"{error}. Increase --buffer-size or reduce "
+                f"--num-source-objects / --object-size."
+            )
+
+        # Always write a deterministic per-object byte pattern (object index
+        # mod 256) so that a client run with --verify can validate the
+        # transferred bytes without any extra coordination. This is a one-time
+        # cost at startup and does not affect the measured read throughput.
+        for index, obj in enumerate(source_objs):
+            assert obj.tensor is not None, "Failed to allocate tensor!"
+            obj.tensor.fill_(index % 256)
+
+        catalog = [
+            (obj.shm_offset, obj.shm_byte_length, index)
+            for index, obj in enumerate(source_objs)
+        ]
+
+        initialize_transfer_channel_context(
+            cfg.transfer_channel_type,
+            l1_memory_desc=manager.get_l1_memory_desc(),
+            listen_url=cfg.url,
+            advertise_url=cfg.url,
+            backends=[cfg.nixl_backend],
+        )
+        try:
+            _serve_catalog(cfg, catalog)
+        finally:
+            delete_transfer_channel_context()
+    finally:
+        if source_objs:
+            manager.free(source_objs)
+        manager.close()
+
+
+def _serve_catalog(cfg: BenchmarkConfig, catalog: list[tuple[int, int, int]]) -> None:
+    """Serve the source object catalog over a ZMQ REP socket until timeout."""
+    payload = json.dumps(
+        {
+            "page_size": cfg.page_size,
+            "object_size": cfg.object_size,
+            "objects": catalog,
+        }
+    ).encode()
+
+    socket = zmq.Context.instance().socket(zmq.REP)
+    socket.setsockopt(zmq.LINGER, 0)
+    socket.bind(_zmq_endpoint(cfg.control_url))
+    print(
+        f"[server] ready: transfer channel on {cfg.url}, "
+        f"catalog on {cfg.control_url} ({len(catalog)} source objects)",
+        flush=True,
+    )
+
+    poller = zmq.Poller()
+    poller.register(socket, zmq.POLLIN)
+    deadline = time.monotonic() + cfg.server_timeout
+    try:
+        while time.monotonic() < deadline:
+            events = dict(poller.poll(timeout=1000))
+            if socket in events:
+                socket.recv()
+                socket.send(payload)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        socket.close(linger=0)
+        print("[server] shut down", flush=True)
+
+
+############################################################
+# Client
+############################################################
+def client_main(cfg: BenchmarkConfig) -> bool:
+    """Run the benchmark client: read a subset of source objects and report.
+
+    Args:
+        cfg: The benchmark configuration (``role == "client"``).
+
+    Returns:
+        ``True`` on success.
+
+    Raises:
+        ValueError: If the server's page/object size or pool size is
+            incompatible with this client's configuration.
+        RuntimeError: If allocation or a read transfer fails.
+    """
+    catalog = _fetch_catalog(cfg)
+    if catalog["page_size"] != cfg.page_size:
+        raise ValueError(
+            f"page_size mismatch: client {cfg.page_size} vs server "
+            f"{catalog['page_size']}; they must match."
+        )
+    if catalog["object_size"] != cfg.object_size:
+        raise ValueError(
+            f"object_size mismatch: client {cfg.object_size} vs server "
+            f"{catalog['object_size']}; they must match."
+        )
+    source_objs = catalog["objects"]
+    if len(source_objs) < cfg.num_objects:
+        raise ValueError(
+            f"server has only {len(source_objs)} source objects, fewer than "
+            f"--num-objects ({cfg.num_objects})."
+        )
+
+    client_buffer = cfg.num_objects * cfg.object_size + _CLIENT_BUFFER_SLACK
+    manager = _create_l1_manager(cfg, client_buffer)
+    dst_objs: list = []
+    try:
+        error, dst_objs = manager.allocate(_object_layout(cfg), cfg.num_objects)
+        if error != L1Error.SUCCESS:
+            raise RuntimeError(
+                f"Failed to allocate {cfg.num_objects} destination objects: {error}."
+            )
+
+        ctx = initialize_transfer_channel_context(
+            cfg.transfer_channel_type,
+            l1_memory_desc=manager.get_l1_memory_desc(),
+            listen_url=cfg.listen_url,
+            advertise_url=cfg.listen_url,
+            backends=[cfg.nixl_backend],
+        )
+        try:
+            local_addrs = ctx.get_transfer_channel_address(
+                [(obj.shm_offset, obj.shm_byte_length) for obj in dst_objs]
+            )
+            rng = random.Random(cfg.seed)
+            chosen = rng.sample(source_objs, cfg.num_objects)
+            remote_addrs = [
+                TransferChannelAddress(offset=offset, size=size)
+                for offset, size, _ in chosen
+            ]
+            chosen_indices = [index for _, _, index in chosen]
+
+            connect_start = time.perf_counter()
+            client = ctx.get_transfer_channel_client(cfg.url)
+            print(
+                f"[client] connected in {time.perf_counter() - connect_start:.1f}s; "
+                f"reading {cfg.num_objects} objects x "
+                f"{cfg.object_size / 1024**2:.1f} MiB",
+                flush=True,
+            )
+
+            def one_read() -> float:
+                start = time.perf_counter()
+                task_id = client.submit_read(local_addrs, remote_addrs)
+                result = client.query_read_status(task_id)
+                while not result.is_finished():
+                    result = client.query_read_status(task_id)
+                elapsed = time.perf_counter() - start
+                succeeded = sum(result.succeeded_mask)
+                if succeeded != cfg.num_objects:
+                    raise RuntimeError(
+                        f"read failed: {succeeded}/{cfg.num_objects} objects succeeded."
+                    )
+                return elapsed
+
+            for _ in range(cfg.warmup):
+                one_read()
+            times = [one_read() for _ in range(cfg.iters)]
+
+            if cfg.verify:
+                _verify(dst_objs, chosen_indices)
+
+            _report(cfg, times)
+            return True
+        finally:
+            delete_transfer_channel_context()
+            del ctx
+    finally:
+        if dst_objs:
+            manager.free(dst_objs)
+        manager.close()
+
+
+def _fetch_catalog(cfg: BenchmarkConfig) -> dict:
+    """Fetch the source object catalog from the server's control socket."""
+    socket = zmq.Context.instance().socket(zmq.REQ)
+    socket.setsockopt(zmq.LINGER, 0)
+    socket.setsockopt(zmq.RCVTIMEO, int(cfg.server_timeout * 1000))
+    socket.connect(_zmq_endpoint(cfg.control_url))
+    try:
+        socket.send(_CATALOG_REQUEST)
+        try:
+            reply = socket.recv()
+        except zmq.Again as exc:
+            raise RuntimeError(
+                f"timed out fetching catalog from {cfg.control_url}; is the "
+                f"server running?"
+            ) from exc
+    finally:
+        socket.close(linger=0)
+    return json.loads(reply)
+
+
+def _verify(dst_objs: list, chosen_indices: list[int]) -> None:
+    """Check each destination object holds the expected per-object byte pattern.
+
+    Raises:
+        RuntimeError: If any destination object does not match.
+    """
+    for obj, index in zip(dst_objs, chosen_indices, strict=False):
+        expected = index % 256
+        tensor = obj.tensor
+        if tensor is None or not bool((tensor == expected).all()):
+            raise RuntimeError(
+                f"verify FAILED for source object {index}: expected all bytes "
+                f"== {expected}."
+            )
+    print(
+        f"[client] verify OK: {len(dst_objs)} objects match expected pattern",
+        flush=True,
+    )
+
+
+def _report(cfg: BenchmarkConfig, times: list[float]) -> None:
+    """Print best/median/mean latency and throughput for the measured reads."""
+    total_bytes = cfg.num_objects * cfg.object_size
+    ordered = sorted(times)
+    best = ordered[0]
+    median = ordered[len(ordered) // 2]
+    mean = sum(ordered) / len(ordered)
+    print("\n==== Transfer channel read throughput ====", flush=True)
+    print(f"  channel type     : {cfg.transfer_channel_type}", flush=True)
+    print(
+        f"  payload per read : {total_bytes / 1e9:.3f} GB "
+        f"({cfg.num_objects} objs x {cfg.object_size / 1024**2:.1f} MiB)",
+        flush=True,
+    )
+    print(f"  iterations       : {cfg.iters} (warmup {cfg.warmup})", flush=True)
+    print(
+        f"  best   : {best * 1e3:8.2f} ms   {_gbps(total_bytes, best):7.2f} GB/s",
+        flush=True,
+    )
+    print(
+        f"  median : {median * 1e3:8.2f} ms   {_gbps(total_bytes, median):7.2f} GB/s",
+        flush=True,
+    )
+    print(
+        f"  mean   : {mean * 1e3:8.2f} ms   {_gbps(total_bytes, mean):7.2f} GB/s",
+        flush=True,
+    )
+
+
+############################################################
+# Entry
+############################################################
+def run_benchmark(args: argparse.Namespace) -> bool:
+    """Dispatch to the server or client role.
+
+    Args:
+        args: Parsed CLI arguments produced by ``add_benchmark_arguments``.
+
+    Returns:
+        ``True`` on success, ``False`` otherwise.
+    """
+    cfg = build_config(args)
+    if cfg.role == "server":
+        server_main(cfg)
+        return True
+    return client_main(cfg)
diff --git a/lmcache/tools/transfer_channel_benchmark/config.py b/lmcache/tools/transfer_channel_benchmark/config.py
new file mode 100644
index 0000000..a5a76d3
--- /dev/null
+++ b/lmcache/tools/transfer_channel_benchmark/config.py
@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Configuration and argument parsing for the transfer channel benchmark.
+
+This module is intentionally free of heavy/optional dependencies (torch, the
+``lmcache.v1.distributed`` runtime) so the CLI can build its argument parser
+without importing them. The runtime imports live in ``benchmark.py``.
+"""
+
+# Standard
+from dataclasses import dataclass
+import argparse
+
+_UNITS = {
+    "B": 1,
+    "KB": 1024,
+    "MB": 1024**2,
+    "GB": 1024**3,
+    "TB": 1024**4,
+    "K": 1024,
+    "M": 1024**2,
+    "G": 1024**3,
+    "T": 1024**4,
+}
+
+# Defaults expressed as byte counts so they can be used directly as argparse
+# defaults (argparse applies ``type=parse_size`` only to string inputs).
+DEFAULT_BUFFER_SIZE = 8 * 1024**3
+DEFAULT_PAGE_SIZE = 512 * 1024
+DEFAULT_OBJECT_SIZE = 10 * 1024**2
+
+
+def parse_size(value: str) -> int:
+    """Parse a human-friendly size string into a byte count.
+
+    Args:
+        value: A size such as ``"8GB"``, ``"512KB"``, ``"10MB"`` or a plain
+            integer byte count (e.g. ``"1048576"``).
+
+    Returns:
+        The size in bytes.
+
+    Raises:
+        ValueError: If the string cannot be parsed.
+    """
+    text = str(value).strip().upper()
+    for suffix in ("TB", "GB", "MB", "KB", "T", "G", "M", "K", "B"):
+        if text.endswith(suffix) and text[: -len(suffix)].strip():
+            return int(float(text[: -len(suffix)].strip()) * _UNITS[suffix])
+    return int(text)
+
+
+@dataclass
+class BenchmarkConfig:
+    """Resolved configuration for one benchmark process (server or client).
+
+    Attributes:
+        role: ``"server"`` or ``"client"``.
+        transfer_channel_type: The transfer channel implementation to use
+            (e.g. ``"nixl"``).
+        nixl_backend: The nixl backend name (e.g. ``"UCX"``). Only used by the
+            nixl transfer channel type.
+        url: Server role binds its transfer-channel server here; client role
+            dials this as the peer (server) advertise url to read from.
+        listen_url: Client role binds its own (mandatory) transfer-channel
+            server here. It never receives reads in this benchmark.
+        control_url: Benchmark catalog side-channel. The server binds a ZMQ REP
+            socket here; the client connects to fetch the source object catalog.
+        buffer_size: Size in bytes of the server's registered L1 region.
+        page_size: Page / alignment size in bytes (the L1 ``align_bytes``).
+        object_size: Size in bytes of each transferred object (multiple of
+            ``page_size``).
+        num_objects: Number of objects transferred per read.
+        num_source_objects: Number of source objects the server allocates. The
+            client reads a random ``num_objects``-sized subset of these.
+        use_lazy: Whether the L1 memory manager uses lazy allocation.
+        iters: Number of measured read iterations.
+        warmup: Number of warmup read iterations (not measured).
+        seed: RNG seed for selecting the read subset.
+        verify: Whether to verify transferred bytes against a known pattern.
+        server_timeout: Seconds the server stays up serving catalog requests.
+    """
+
+    role: str
+    transfer_channel_type: str = "nixl"
+    nixl_backend: str = "UCX"
+    url: str = "127.0.0.1:7600"
+    listen_url: str = "0.0.0.0:7601"
+    control_url: str = "0.0.0.0:7610"
+    buffer_size: int = DEFAULT_BUFFER_SIZE
+    page_size: int = DEFAULT_PAGE_SIZE
+    object_size: int = DEFAULT_OBJECT_SIZE
+    num_objects: int = 100
+    num_source_objects: int = 0
+    use_lazy: bool = False
+    iters: int = 5
+    warmup: int = 1
+    seed: int = 0
+    verify: bool = False
+    server_timeout: float = 1800.0
+
+    def __post_init__(self) -> None:
+        """Apply derived defaults and validate the configuration.
+
+        Raises:
+            ValueError: If any field is out of range or mutually inconsistent.
+        """
+        if self.num_source_objects <= 0:
+            self.num_source_objects = 5 * self.num_objects
+
+        if self.page_size <= 0:
+            raise ValueError(f"page_size must be positive, got {self.page_size}")
+        if self.object_size <= 0 or self.object_size % self.page_size != 0:
+            raise ValueError(
+                f"object_size ({self.object_size}) must be a positive multiple "
+                f"of page_size ({self.page_size})"
+            )
+        if self.num_objects < 1:
+            raise ValueError(f"num_objects must be >= 1, got {self.num_objects}")
+        if self.num_source_objects < self.num_objects:
+            raise ValueError(
+                f"num_source_objects ({self.num_source_objects}) must be >= "
+                f"num_objects ({self.num_objects})"
+            )
+
+
+def add_benchmark_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add all benchmark arguments to ``parser``.
+
+    Defined here (not in ``benchmark.py``) so the CLI can build its parser
+    without importing torch or the distributed runtime.
+
+    Args:
+        parser: The argument parser (or subparser) to populate.
+    """
+    parser.add_argument(
+        "--role",
+        choices=["server", "client"],
+        required=True,
+        help="server: register a source buffer and serve its object catalog; "
+        "client: read a subset of the server's objects and report throughput.",
+    )
+    parser.add_argument(
+        "--transfer-channel-type",
+        default="nixl",
+        help="Transfer channel implementation to benchmark.",
+    )
+    parser.add_argument(
+        "--nixl-backend",
+        default="UCX",
+        help="nixl backend name (nixl-specific), e.g. UCX.",
+    )
+    parser.add_argument(
+        "--url",
+        default="127.0.0.1:7600",
+        help="server: host:port to bind the transfer-channel server; "
+        "client: the server (peer) advertise url to read from.",
+    )
+    parser.add_argument(
+        "--listen-url",
+        default="0.0.0.0:7601",
+        help="client: host:port for the client's own (mandatory) "
+        "transfer-channel server; it never receives reads here.",
+    )
+    parser.add_argument(
+        "--control-url",
+        default="0.0.0.0:7610",
+        help="benchmark catalog side-channel: server binds here, client "
+        "connects here to fetch the source object catalog.",
+    )
+    parser.add_argument(
+        "--buffer-size",
+        type=parse_size,
+        default=DEFAULT_BUFFER_SIZE,
+        help="server: total registered L1 source buffer size (e.g. 8GB).",
+    )
+    parser.add_argument(
+        "--page-size",
+        type=parse_size,
+        default=DEFAULT_PAGE_SIZE,
+        help="page / alignment size; must match on server and client.",
+    )
+    parser.add_argument(
+        "--object-size",
+        type=parse_size,
+        default=DEFAULT_OBJECT_SIZE,
+        help="size of each transferred object (multiple of --page-size).",
+    )
+    parser.add_argument(
+        "--num-objects",
+        type=int,
+        default=100,
+        help="number of objects transferred per read.",
+    )
+    parser.add_argument(
+        "--num-source-objects",
+        type=int,
+        default=0,
+        help="server source pool size; 0 means 5 * --num-objects.",
+    )
+    parser.add_argument(
+        "--use-lazy",
+        action="store_true",
+        help="use the lazy L1 allocator (experimental for registration).",
+    )
+    parser.add_argument(
+        "--iters", type=int, default=5, help="measured read iterations."
+    )
+    parser.add_argument("--warmup", type=int, default=1, help="warmup read iterations.")
+    parser.add_argument(
+        "--seed", type=int, default=0, help="RNG seed for read-subset selection."
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="verify transferred bytes against a known per-object pattern.",
+    )
+    parser.add_argument(
+        "--server-timeout",
+        type=float,
+        default=1800.0,
+        help="seconds the server serves catalog requests before exiting.",
+    )
+
+
+def build_config(args: argparse.Namespace) -> BenchmarkConfig:
+    """Build a :class:`BenchmarkConfig` from parsed arguments.
+
+    Args:
+        args: Parsed CLI arguments produced by ``add_benchmark_arguments``.
+
+    Returns:
+        The resolved, validated benchmark configuration.
+    """
+    return BenchmarkConfig(
+        role=args.role,
+        transfer_channel_type=args.transfer_channel_type,
+        nixl_backend=args.nixl_backend,
+        url=args.url,
+        listen_url=args.listen_url,
+        control_url=args.control_url,
+        buffer_size=args.buffer_size,
+        page_size=args.page_size,
+        object_size=args.object_size,
+        num_objects=args.num_objects,
+        num_source_objects=args.num_source_objects,
+        use_lazy=args.use_lazy,
+        iters=args.iters,
+        warmup=args.warmup,
+        seed=args.seed,
+        verify=args.verify,
+        server_timeout=args.server_timeout,
+    )
diff --git a/lmcache/usage_context.py b/lmcache/usage_context.py
new file mode 100644
index 0000000..e6dcb7d
--- /dev/null
+++ b/lmcache/usage_context.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Backward-compatibility shim; the implementation lives in
+:mod:`lmcache.usage_telemetry`."""
+
+# First Party
+from lmcache.usage_telemetry import (
+    ContinuousContextMessage,
+    ContinuousUsageContext,
+    EngineMessage,
+    EnvMessage,
+    InitializeUsageContext,
+    MetadataMessage,
+    UsageContext,
+)
+
+__all__ = [
+    "ContinuousContextMessage",
+    "ContinuousUsageContext",
+    "EngineMessage",
+    "EnvMessage",
+    "InitializeUsageContext",
+    "MetadataMessage",
+    "UsageContext",
+]
diff --git a/lmcache/usage_telemetry/README.md b/lmcache/usage_telemetry/README.md
new file mode 100644
index 0000000..61eed56
--- /dev/null
+++ b/lmcache/usage_telemetry/README.md
@@ -0,0 +1,137 @@
+# Anonymous Usage Telemetry (`lmcache/usage_telemetry/`)
+
+Phone-home usage statistics: what LMCache deployments look like and how much
+caching they do. This is **not** operator observability — Prometheus/OTel
+metrics for operators live in `lmcache/v1/mp_observability/` (MP mode) and
+`lmcache/observability.py` (single-process mode). The two systems share event
+sources in places but have different consumers (LMCache maintainers vs.
+deployment operators), different transports, and independent opt-outs.
+
+## Package layout
+
+| Module | Contents |
+|---|---|
+| `messages.py` | **Wire schema — single source of truth.** Every message dataclass, `USAGE_SCHEMA_VERSION`, per-message `ENDPOINT` |
+| `guard.py` | `swallow_telemetry_errors` decorator — the no-throw guarantee |
+| `identity.py` | Opt-out gate (`is_usage_tracking_enabled`), `UsageIdentity` (session/machine ids) |
+| `transport.py` | `UsageMessageSender` (HTTP), `build_usage_payload` (identity + schema stamping) |
+| `env_probe.py` | Hardware/platform/cloud detection feeding `EnvMessage` |
+| `context.py` | `UsageContextBase`, single-process `UsageContext`, `InitializeUsageContext` — the `/context` snapshot reporters |
+| `continuous.py` | `ContinuousUsageContext` interval counters and lifespan histogram |
+| `mp.py` | MP server `MPUsageContext`, `InitializeMPUsageContext` |
+
+`lmcache/usage_context.py` remains as a backward-compatibility shim
+re-exporting the pre-package public names.
+
+## Message schema contract
+
+`messages.py` is the protobuf-style registry: every message LMCache can
+phone home is a dataclass there, and nowhere else. The contract:
+
+- The **class name** is the wire `message_type` discriminator —
+  `build_usage_payload` derives it, so senders cannot disagree with the
+  schema.
+- Each message declares the stats-server **`ENDPOINT`** it POSTs to as a
+  class attribute; senders route by it.
+- Fields are **flat and JSON-serializable** (the backend stores flat
+  key-value pairs; lists are joined into delimited strings).
+- `session_id`, `machine_id`, `schema_version`, and `deployment_mode` are
+  stamped onto every payload by `build_usage_payload`, not declared per
+  message.
+
+## Reporting paths
+
+| Path | Trigger | Messages |
+|---|---|---|
+| Single-process one-shot | `LMCacheEngine.__init__` → `InitializeUsageContext` | `EnvMessage`, `EngineMessage`, `MetadataMessage` |
+| MP server one-shot | `run_cache_server` → `InitializeMPUsageContext` | `EnvMessage`, `MPServerMessage` |
+| Continuous (single-process) | `LMCacheStatsLogger.log_worker`, every `LMCACHE_USAGE_TRACK_INTERVAL` s (default 600) | `ContinuousContextMessage`, `CacheLifespanMessage` |
+
+Model and KV-layout information only become visible to the MP server when
+a serving engine registers its KV caches; a registration-time report
+(`MPInstanceMessage`) is planned for a follow-up PR, together with MP-mode
+continuous reporting (an EventBus subscriber feeding the same endpoints).
+
+## Failure isolation (no-throw guarantee)
+
+A failure anywhere in telemetry must never affect caching or serving. The
+mechanisms, outermost first:
+
+- Every entry point called from serving code — `InitializeUsageContext`,
+  `InitializeMPUsageContext`, `ContinuousUsageContext.incr_or_send_stats`,
+  `report_once` — is decorated with
+  `guard.swallow_telemetry_errors`: exceptions are logged at debug level
+  and swallowed.
+- One-shot sends run on a daemon thread; startup never blocks on the
+  stats server.
+- `UsageMessageSender.send` additionally swallows all transport errors
+  with a 5 s timeout.
+- `ContinuousUsageContext.__init__` degrades (kv-bytes-per-token = 0)
+  rather than raising on nonstandard kv shapes.
+
+Tests for this contract live in `TestFailureIsolation`
+(`tests/test_usage_telemetry.py`): a transport that raises must not break
+the startup report or the stats-logger flush.
+
+## Identity and association contract
+
+Every payload — one-shot or continuous — is stamped with:
+
+- `session_id`: random UUID minted once per process. The join key: the
+  `/context` rows keyed by a `session_id` describe the deployment that
+  produced all other rows with that `session_id`.
+- `machine_id`: random UUID persisted at `~/.config/lmcache/machine_id`.
+  Groups sessions from the same machine across restarts (deployment-level
+  dedup, restart cadence). Empty string when the file cannot be created.
+- `schema_version`: bump `USAGE_SCHEMA_VERSION` whenever a field changes
+  meaning so backend analysis can partition by schema.
+- `deployment_mode`: `single_process` or `mp_server` — which deployment
+  mode produced the payload. Needed because `EnvMessage` and the continuous
+  messages are shared between modes and are otherwise ambiguous.
+
+Continuous messages additionally carry `sequence_number` (monotonic per
+session). Send failures drop the interval's data rather than retrying —
+telemetry must never accumulate unbounded state — so sequence gaps are the
+backend's signal that intervals were lost rather than idle.
+
+Privacy rules:
+
+- Identifiers are random UUIDs, never derived from hardware (no MAC address,
+  hostname, or `/etc/machine-id`).
+- The MP server's `instance_id` is deliberately excluded from payloads: it is
+  operator-settable (`--instance-id`) and may contain identifying strings.
+  It stays in the operator-facing OTel `service.instance.id` only.
+- No prompts, keys, or KV-cache contents are ever sent. Model names are
+  reported (they identify public model architectures, not deployments).
+
+## Opt-out semantics
+
+`is_usage_tracking_enabled()` is the single gate, checked by every path:
+
+1. `LMCACHE_TRACK_USAGE=false` (LMCache-specific),
+2. `DO_NOT_TRACK` in `1`/`true`/`yes` (cross-tool convention).
+
+When disabled, the factory functions return `None`, the continuous reporter
+no-ops, and no state files (`machine_id`) are created.
+
+## Transport and testing
+
+`UsageMessageSender` is the injectable transport boundary. Tests inject a
+recording stub into the usage contexts (see `tests/test_usage_telemetry.py`);
+no test may hit the network. The test suite globally disables tracking via an
+autouse fixture in `tests/conftest.py` so no other test phones home.
+
+## Extension guide
+
+To add a new message type:
+
+1. Define a dataclass in `messages.py` extending `UsageMessage`, with flat
+   JSON-serializable fields and an `ENDPOINT` (the class name becomes the
+   wire `message_type`).
+2. Send it through `build_usage_payload` so identity and schema stamping
+   stay uniform; wrap any new serving-code entry point with
+   `swallow_telemetry_errors`.
+3. Coordinate with the stats-server owner: unknown `message_type` values are
+   dropped silently on the backend.
+4. Bump `USAGE_SCHEMA_VERSION` only when an *existing* field changes meaning;
+   adding a message type or field is not a schema bump.
diff --git a/lmcache/usage_telemetry/__init__.py b/lmcache/usage_telemetry/__init__.py
new file mode 100644
index 0000000..c63c80e
--- /dev/null
+++ b/lmcache/usage_telemetry/__init__.py
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Anonymous usage telemetry for LMCache.
+
+Phone-home usage statistics, described in this package's ``README.md``.
+
+- The wire schema of every message lives in :mod:`.messages` — the single
+  source of truth for what LMCache can phone home.
+- Context reporting (:mod:`.context`, :mod:`.mp`) sends a
+  snapshot of the environment and configuration at startup.
+- Continuous reporting (:mod:`.continuous`) flushes interval counters
+  (hit/stored tokens) and a cache-lifespan histogram periodically.
+
+Every outgoing payload is stamped with a :class:`UsageIdentity` (per-process
+``session_id`` plus persistent ``machine_id``) so the stats backend can join
+continuous messages with the one-shot context that describes the deployment.
+
+Every entry point called from serving code is wrapped with
+:func:`lmcache.usage_telemetry.guard.swallow_telemetry_errors`: a failure
+anywhere in telemetry can never affect caching or serving functionality.
+
+Users can opt out at any time; see :func:`is_usage_tracking_enabled`.
+"""
+
+# First Party
+from lmcache.usage_telemetry.context import (
+    InitializeUsageContext,
+    UsageContext,
+    UsageContextBase,
+)
+from lmcache.usage_telemetry.continuous import ContinuousUsageContext
+from lmcache.usage_telemetry.env_probe import collect_env_message
+from lmcache.usage_telemetry.identity import (
+    UsageIdentity,
+    get_usage_identity,
+    is_usage_tracking_enabled,
+)
+from lmcache.usage_telemetry.messages import (
+    USAGE_SCHEMA_VERSION,
+    CacheLifespanMessage,
+    ContinuousContextMessage,
+    DeploymentMode,
+    EngineMessage,
+    EnvMessage,
+    MetadataMessage,
+    MPServerMessage,
+    UsageMessage,
+)
+from lmcache.usage_telemetry.mp import InitializeMPUsageContext, MPUsageContext
+from lmcache.usage_telemetry.transport import UsageMessageSender
+
+__all__ = [
+    "USAGE_SCHEMA_VERSION",
+    "CacheLifespanMessage",
+    "ContinuousContextMessage",
+    "ContinuousUsageContext",
+    "DeploymentMode",
+    "EngineMessage",
+    "EnvMessage",
+    "InitializeMPUsageContext",
+    "InitializeUsageContext",
+    "MPServerMessage",
+    "MPUsageContext",
+    "MetadataMessage",
+    "UsageContext",
+    "UsageContextBase",
+    "UsageIdentity",
+    "UsageMessage",
+    "UsageMessageSender",
+    "collect_env_message",
+    "get_usage_identity",
+    "is_usage_tracking_enabled",
+]
diff --git a/lmcache/usage_telemetry/context.py b/lmcache/usage_telemetry/context.py
new file mode 100644
index 0000000..eef97ca
--- /dev/null
+++ b/lmcache/usage_telemetry/context.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Context reporting: snapshot messages describing a deployment.
+
+Context reports are sent once each (at startup, or at KV-cache registration
+for the MP path in :mod:`.mp`), in contrast to the periodic interval
+counters in :mod:`.continuous`.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import TYPE_CHECKING
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.usage_telemetry.env_probe import collect_env_message
+from lmcache.usage_telemetry.guard import swallow_telemetry_errors
+from lmcache.usage_telemetry.identity import (
+    get_usage_identity,
+    is_usage_tracking_enabled,
+)
+from lmcache.usage_telemetry.messages import (
+    DeploymentMode,
+    EngineMessage,
+    MetadataMessage,
+    UsageMessage,
+)
+from lmcache.usage_telemetry.transport import (
+    DEFAULT_SENDER,
+    UsageMessageSender,
+    build_usage_payload,
+    usage_server_url,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+class UsageContextBase(ABC):
+    """Shared plumbing for one-shot usage reporting.
+
+    Subclasses define which messages the report contains via
+    :meth:`_collect_messages`; this base owns the identity, transport, and
+    optional local logging. Each message is POSTed to the endpoint it
+    declares in the schema (:mod:`lmcache.usage_telemetry.messages`).
+    """
+
+    def __init__(
+        self,
+        mode: DeploymentMode,
+        local_log: str | None,
+        sender: UsageMessageSender | None,
+    ) -> None:
+        """Initialize shared reporting state.
+
+        Args:
+            mode: Deployment mode stamped on every payload this reporter
+                sends.
+            local_log: Path of a human-readable local log of every sent
+                payload; ``None`` disables local logging.
+            sender: Message transport; ``None`` selects the default HTTP
+                sender.
+        """
+        self._mode = mode
+        self._local_log = local_log
+        self._sender = sender if sender is not None else DEFAULT_SENDER
+        self._identity = get_usage_identity()
+        self._start_time = datetime.now()
+
+    @abstractmethod
+    def _collect_messages(self) -> list[UsageMessage]:
+        """Return the messages of the one-shot report."""
+        raise NotImplementedError
+
+    @swallow_telemetry_errors
+    def report_once(self) -> None:
+        """Collect and send every one-shot message on the calling thread.
+
+        Failures are swallowed; never raises.
+        """
+        for message in self._collect_messages():
+            payload = build_usage_payload(message, self._identity, self._mode)
+            self._sender.send(usage_server_url(message.ENDPOINT), payload)
+            self._write_local(payload)
+
+    def _write_local(self, payload: dict[str, object]) -> None:
+        """Append *payload* to the local log file, if one is configured."""
+        if self._local_log is None:
+            return
+        text = "".join(f"{key}: {value}\n" for key, value in payload.items()) + "\n"
+        try:
+            with open(self._local_log, "a") as f:
+                f.write(text)
+        except OSError:
+            logger.debug("Unable to write usage log to %s", self._local_log)
+
+
+class UsageContext(UsageContextBase):
+    """One-shot usage reporter for the single-process LMCacheEngine path.
+
+    Sends an ``EnvMessage``, an ``EngineMessage``, and a
+    ``MetadataMessage`` to the stats server.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        local_log: str | None = None,
+        sender: UsageMessageSender | None = None,
+    ) -> None:
+        """Initialize the reporter.
+
+        Args:
+            config: The engine configuration to snapshot.
+            metadata: The engine metadata (model, world size, kv layout).
+            local_log: Path of a local log of sent payloads; ``None``
+                disables local logging.
+            sender: Message transport; ``None`` selects the default HTTP
+                sender.
+        """
+        super().__init__(DeploymentMode.SINGLE_PROCESS, local_log, sender)
+        self._config = config
+        self._metadata = metadata
+
+    def _collect_messages(self) -> list[UsageMessage]:
+        metadata_message = MetadataMessage(
+            start_time=self._start_time.strftime("%Y-%m-%d %H:%M:%S"),
+            duration=(datetime.now() - self._start_time).total_seconds(),
+        )
+        return [
+            collect_env_message(),
+            EngineMessage.from_config(self._config, self._metadata),
+            metadata_message,
+        ]
+
+
+@swallow_telemetry_errors
+def InitializeUsageContext(
+    config: LMCacheEngineConfig,
+    metadata: LMCacheMetadata,
+    local_log: str | None = None,
+    sender: UsageMessageSender | None = None,
+) -> UsageContext | None:
+    """Start one-shot usage reporting for a single-process engine.
+
+    Returns immediately; the report is sent in the background. Never
+    blocks or raises.
+
+    Args:
+        config: The engine configuration to snapshot.
+        metadata: The engine metadata (model, world size, kv layout).
+        local_log: Path of a local log of sent payloads; ``None`` disables
+            local logging.
+        sender: Message transport; ``None`` selects the default HTTP sender.
+
+    Returns:
+        The usage context, or ``None`` when usage tracking is disabled or
+        initialization failed.
+    """
+    if not is_usage_tracking_enabled():
+        return None
+    logger.info("Initializing usage context.")
+    context = UsageContext(config, metadata, local_log, sender)
+    threading.Thread(
+        target=context.report_once, daemon=True, name="lmcache-usage-report"
+    ).start()
+    return context
diff --git a/lmcache/usage_telemetry/continuous.py b/lmcache/usage_telemetry/continuous.py
new file mode 100644
index 0000000..207eb98
--- /dev/null
+++ b/lmcache/usage_telemetry/continuous.py
@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Continuous usage reporting: periodic interval counters and histograms."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import os
+import time
+
+# Third Party
+import numpy as np
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.usage_telemetry.guard import swallow_telemetry_errors
+from lmcache.usage_telemetry.identity import (
+    get_usage_identity,
+    is_usage_tracking_enabled,
+)
+from lmcache.usage_telemetry.messages import (
+    CacheLifespanMessage,
+    ContinuousContextMessage,
+    DeploymentMode,
+)
+from lmcache.usage_telemetry.transport import (
+    DEFAULT_SENDER,
+    UsageMessageSender,
+    build_usage_payload,
+    usage_server_url,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.observability import LMCacheStats
+    from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+class ContinuousUsageContext:
+    """Periodic reporter of interval cache-usage counters.
+
+    Accumulates hit/stored token counts and cache lifespans via
+    :meth:`incr_or_send_stats` and flushes them to the stats server every
+    ``LMCACHE_USAGE_TRACK_INTERVAL`` seconds (default 600). Interval data
+    is dropped, not retried, when a send fails; gaps in
+    ``sequence_number`` mark lost intervals on the backend.
+    """
+
+    _instance: ContinuousUsageContext | None = None
+
+    def __init__(
+        self,
+        metadata: LMCacheMetadata,
+        sender: UsageMessageSender | None = None,
+        mode: DeploymentMode = DeploymentMode.SINGLE_PROCESS,
+    ) -> None:
+        """Initialize the reporter.
+
+        Args:
+            metadata: The engine metadata; its kv shape/dtype size the
+                stored-bytes estimate.
+            sender: Message transport; ``None`` selects the default HTTP
+                sender.
+            mode: Deployment mode stamped on every payload this reporter
+                sends.
+        """
+        self.cache_lifespan_buckets: list[float] = [
+            0,
+            1,
+            5,
+            10,
+            20,
+            40,
+            60,
+            80,
+            100,
+            250,
+            500,
+            750,
+            1000,
+            2500,
+            5000,
+        ]
+        self.metadata: LMCacheMetadata = metadata
+        self.cache_usage_url: str = usage_server_url(ContinuousContextMessage.ENDPOINT)
+        self.cache_lifespan_url: str = usage_server_url(CacheLifespanMessage.ENDPOINT)
+        self.min_logging_interval: int = int(
+            os.getenv("LMCACHE_USAGE_TRACK_INTERVAL", "600")
+        )
+        # send the first message immediately after init
+        self.last_logged_ts: float = -1
+
+        self.interval_num_hit_tokens: int = 0
+        self.interval_num_stored_tokens: int = 0
+        try:
+            self.kv_sz_per_token_bytes: int = int(
+                np.prod(self.metadata.kv_shape)
+                * self.metadata.kv_dtype.itemsize
+                / self.metadata.kv_shape[2]
+            )
+        except Exception:
+            # 0 marks the stored-bytes estimate as unavailable.
+            logger.debug("Cannot derive kv bytes per token", exc_info=True)
+            self.kv_sz_per_token_bytes = 0
+        self.cache_lifespan_data: list[float] = []
+        self._sender = sender if sender is not None else DEFAULT_SENDER
+        self._mode = mode
+        self._sequence_number: int = 0
+
+    @staticmethod
+    def GetOrCreate(metadata: LMCacheMetadata) -> ContinuousUsageContext:
+        """Return the process-wide instance, creating it on first call.
+
+        Args:
+            metadata: The engine metadata used on first creation.
+
+        Returns:
+            The singleton continuous usage context.
+        """
+        if ContinuousUsageContext._instance is None:
+            ContinuousUsageContext._instance = ContinuousUsageContext(metadata)
+        if ContinuousUsageContext._instance.metadata != metadata:
+            logger.error(
+                "ContinuousUsageContext instance already created with"
+                "different metadata. This should not happen except "
+                "in test."
+            )
+        return ContinuousUsageContext._instance
+
+    def send_caching_message(self) -> None:
+        """Flush the interval counters and lifespan histogram, then reset."""
+        self._sequence_number += 1
+        identity = get_usage_identity()
+
+        usage_message = ContinuousContextMessage(
+            interval_stored_kv_size=int(
+                self.kv_sz_per_token_bytes * self.interval_num_stored_tokens
+            ),
+            interval_num_hit_tokens=int(self.interval_num_hit_tokens),
+            interval_num_stored_tokens=int(self.interval_num_stored_tokens),
+            sequence_number=self._sequence_number,
+        )
+        self._sender.send(
+            self.cache_usage_url,
+            build_usage_payload(usage_message, identity, self._mode),
+        )
+        self.interval_num_hit_tokens = 0
+        self.interval_num_stored_tokens = 0
+
+        lifespan_message = CacheLifespanMessage(
+            cache_lifespan_histogram=self.list_to_histogram(
+                self.cache_lifespan_data, self.cache_lifespan_buckets
+            ),
+            sequence_number=self._sequence_number,
+        )
+        self._sender.send(
+            self.cache_lifespan_url,
+            build_usage_payload(lifespan_message, identity, self._mode),
+        )
+        self.cache_lifespan_data = []
+
+    def list_to_histogram(
+        self, data: list[float], buckets: list[float]
+    ) -> dict[float, int]:
+        """Bucket *data* into a ``{bucket_lower_bound: count}`` histogram.
+
+        Args:
+            data: The raw samples.
+            buckets: Ascending bucket boundaries.
+
+        Returns:
+            Mapping from each bucket boundary to the sample count in it.
+        """
+        histogram, _ = np.histogram(data, bins=buckets)
+        counts = list(histogram)
+        counts.insert(0, 0)
+        return {
+            bucket: int(count) for bucket, count in zip(buckets, counts, strict=False)
+        }
+
+    @swallow_telemetry_errors
+    def incr_or_send_stats(self, stats: LMCacheStats) -> None:
+        """Accumulate interval stats and flush when the interval elapsed.
+
+        No-op when usage tracking is disabled; never raises into the
+        stats-logger loop.
+
+        Args:
+            stats: The stats snapshot of the elapsed logging tick.
+        """
+        if not is_usage_tracking_enabled():
+            return
+        self.cache_lifespan_data.extend(stats.interval_request_cache_lifespan)
+        self.interval_num_hit_tokens += stats.interval_hit_tokens
+        self.interval_num_stored_tokens += stats.interval_stored_tokens
+
+        cur_ts: float = time.monotonic()
+        if cur_ts - self.last_logged_ts >= self.min_logging_interval:
+            self.send_caching_message()
+            self.last_logged_ts = cur_ts
diff --git a/lmcache/usage_telemetry/env_probe.py b/lmcache/usage_telemetry/env_probe.py
new file mode 100644
index 0000000..e9ddc09
--- /dev/null
+++ b/lmcache/usage_telemetry/env_probe.py
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Hardware and platform environment probing for usage telemetry."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from pathlib import Path
+import importlib.metadata
+import os
+import platform
+import subprocess
+
+# Third Party
+import cpuinfo
+import psutil
+
+# First Party
+from lmcache import torch_dev
+from lmcache.usage_telemetry.messages import EnvMessage
+
+
+def _get_provider() -> str:
+    """Detect the cloud provider from DMI files and environment variables."""
+    vendor_files = [
+        "/sys/class/dmi/id/product_version",
+        "/sys/class/dmi/id/bios_vendor",
+        "/sys/class/dmi/id/product_name",
+        "/sys/class/dmi/id/chassis_asset_tag",
+        "/sys/class/dmi/id/sys_vendor",
+    ]
+    # Mapping of identifiable strings to cloud providers
+    cloud_identifiers = {
+        "amazon": "AWS",
+        "microsoft corporation": "AZURE",
+        "google": "GCP",
+        "oraclecloud": "OCI",
+    }
+
+    for vendor_file in vendor_files:
+        path = Path(vendor_file)
+        if path.is_file():
+            file_content = path.read_text().lower()
+            for identifier, provider in cloud_identifiers.items():
+                if identifier in file_content:
+                    return provider
+
+    # Try detecting through environment variables
+    env_to_cloud_provider = {
+        "RUNPOD_DC_ID": "RUNPOD",
+    }
+    for env_var, provider in env_to_cloud_provider.items():
+        if os.environ.get(env_var):
+            return provider
+
+    return "UNKNOWN"
+
+
+def _get_cpu_info() -> tuple[int, str, str]:
+    """Return (cpu count, cpu brand, family/model/stepping); 0 = unknown."""
+    info = cpuinfo.get_cpu_info()
+    num_cpu = int(info.get("count") or 0)
+    cpu_type = str(info.get("brand_raw", ""))
+    cpu_family_model_stepping = ",".join(
+        [
+            str(info.get("family", "")),
+            str(info.get("model", "")),
+            str(info.get("stepping", "")),
+        ]
+    )
+    return num_cpu, cpu_type, cpu_family_model_stepping
+
+
+def _get_gpu_info() -> tuple[int, str, int]:
+    """Return (gpu count, gpu type, memory per device in bytes).
+
+    On accelerator-less machines this falls back to the physical CPU count,
+    the processor name, and total host memory.
+    """
+    if torch_dev.is_available():
+        device_property = torch_dev.get_device_properties(0)
+        return (
+            torch_dev.device_count(),
+            device_property.name,
+            device_property.total_memory,
+        )
+    return (
+        int(psutil.cpu_count(logical=False) or 0),
+        platform.processor(),
+        psutil.virtual_memory().total,
+    )
+
+
+def _get_source() -> str:
+    """Detect the install source (DOCKER, PIP, CONDA, or UNKNOWN)."""
+    path = "/proc/1/cgroup"
+    if os.path.exists(path):
+        with open(path, "r") as f:
+            for line in f:
+                if "docker" in line:
+                    return "DOCKER"
+    try:
+        _ = importlib.metadata.distribution("LMCache")
+        return "PIP"
+    except importlib.metadata.PackageNotFoundError:
+        pass
+    try:
+        result = subprocess.run(
+            ["conda", "list", "LMCache"], capture_output=True, text=True
+        )
+        if "LMCache" in result.stdout:
+            return "CONDA"
+    except FileNotFoundError:
+        pass
+
+    return "UNKNOWN"
+
+
+def collect_env_message() -> EnvMessage:
+    """Collect the hardware/platform environment for one-shot reporting.
+
+    Returns:
+        The populated environment message.
+    """
+    num_cpu, cpu_type, cpu_family_model_stepping = _get_cpu_info()
+    gpu_count, gpu_type, gpu_memory_per_device = _get_gpu_info()
+    return EnvMessage(
+        provider=_get_provider(),
+        num_cpu=num_cpu,
+        cpu_type=cpu_type,
+        cpu_family_model_stepping=cpu_family_model_stepping,
+        total_memory=psutil.virtual_memory().total,
+        architecture=platform.architecture(),
+        platforms=platform.platform(),
+        gpu_count=gpu_count,
+        gpu_type=gpu_type,
+        gpu_memory_per_device=gpu_memory_per_device,
+        source=_get_source(),
+    )
diff --git a/lmcache/usage_telemetry/guard.py b/lmcache/usage_telemetry/guard.py
new file mode 100644
index 0000000..b25c35d
--- /dev/null
+++ b/lmcache/usage_telemetry/guard.py
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""No-throw guarantee for usage telemetry.
+
+Every usage-telemetry entry point that serving code calls (engine startup,
+MP server startup, KV-cache registration, the stats-logger loop) is wrapped
+with :func:`swallow_telemetry_errors`, so a bug or environment failure in
+telemetry can never propagate into the caching or serving path.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Callable, ParamSpec, TypeVar
+import functools
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def swallow_telemetry_errors(func: Callable[P, R]) -> Callable[P, R | None]:
+    """Wrap *func* so that every exception is logged at debug and swallowed.
+
+    Args:
+        func: The telemetry entry point to protect.
+
+    Returns:
+        A wrapper with the same signature that returns ``None`` instead of
+        raising when *func* fails.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | None:
+        try:
+            return func(*args, **kwargs)
+        except Exception:
+            logger.debug(
+                "Usage telemetry failure in %s (suppressed)",
+                func.__qualname__,
+                exc_info=True,
+            )
+            return None
+
+    return wrapper
diff --git a/lmcache/usage_telemetry/identity.py b/lmcache/usage_telemetry/identity.py
new file mode 100644
index 0000000..2d7463e
--- /dev/null
+++ b/lmcache/usage_telemetry/identity.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Opt-out gate and anonymous identity for usage telemetry."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import threading
+import uuid
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def usage_config_dir() -> Path:
+    """Directory holding LMCache usage-telemetry state files."""
+    return Path(os.path.expanduser("~/.config/lmcache"))
+
+
+def is_usage_tracking_enabled() -> bool:
+    """Whether anonymous usage telemetry may be collected and sent.
+
+    Tracking is enabled by default and disabled when either opt-out is
+    present:
+
+    - Environment variable ``LMCACHE_TRACK_USAGE=false``.
+    - Environment variable ``DO_NOT_TRACK`` set to ``1``/``true``/``yes``
+      (the cross-tool "do not track" console convention).
+
+    Returns:
+        True when usage telemetry may be sent, False otherwise.
+    """
+    if os.getenv("LMCACHE_TRACK_USAGE") == "false":
+        return False
+    if os.getenv("DO_NOT_TRACK", "").lower() in ("1", "true", "yes"):
+        return False
+    return True
+
+
+@dataclass(frozen=True)
+class UsageIdentity:
+    """Anonymous identifiers stamped on every usage message.
+
+    Both identifiers are random UUIDs, never derived from hardware
+    (MAC address, hostname, or ``/etc/machine-id``), so they carry no
+    identifying information.
+    """
+
+    session_id: str
+    """Random UUID minted once per process. Joins the one-shot context
+    messages with the continuous messages of the same run."""
+
+    machine_id: str
+    """Random UUID persisted at ``~/.config/lmcache/machine_id``. Groups
+    sessions from the same machine across restarts. Empty string when the
+    file can be neither read nor created."""
+
+
+_usage_identity: UsageIdentity | None = None
+_usage_identity_lock = threading.Lock()
+
+
+def get_usage_identity() -> UsageIdentity:
+    """Return the process-wide usage identity, minting it on first call.
+
+    The first call creates the persistent machine id file if needed; callers
+    must therefore consult :func:`is_usage_tracking_enabled` first so that
+    opted-out users get no state files written.
+
+    Returns:
+        The identity shared by all usage messages of this process.
+    """
+    global _usage_identity
+    with _usage_identity_lock:
+        if _usage_identity is None:
+            _usage_identity = UsageIdentity(
+                session_id=str(uuid.uuid4()),
+                machine_id=_read_or_create_machine_id(),
+            )
+        return _usage_identity
+
+
+def _read_or_create_machine_id() -> str:
+    """Read the persistent machine id, creating it on first use.
+
+    Returns:
+        The machine id, or an empty string when the state file can be
+        neither read nor created (e.g. read-only filesystem).
+    """
+    path = usage_config_dir() / "machine_id"
+    try:
+        if path.is_file():
+            machine_id = path.read_text().strip()
+            if machine_id:
+                return machine_id
+        machine_id = str(uuid.uuid4())
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(machine_id)
+        return machine_id
+    except OSError:
+        logger.debug("Cannot persist usage machine id", exc_info=True)
+        return ""
diff --git a/lmcache/usage_telemetry/messages.py b/lmcache/usage_telemetry/messages.py
new file mode 100644
index 0000000..7fc5c1e
--- /dev/null
+++ b/lmcache/usage_telemetry/messages.py
@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Wire schema for all usage-telemetry messages — the single source of truth.
+
+Every message that LMCache can phone home is defined in this module,
+protobuf-style: one dataclass per message, whose
+
+- **class name** is the wire ``message_type`` discriminator,
+- ``ENDPOINT`` class attribute names the stats-server endpoint it POSTs to,
+- fields are the payload keys (flat and JSON-serializable; join lists into
+  delimited strings, since the stats backend stores flat key-value pairs).
+
+:data:`USAGE_SCHEMA_VERSION` is stamped on every payload; bump it only when
+an *existing* field changes meaning — adding a message or field is not a
+schema bump.
+
+Identity fields (``session_id``, ``machine_id``) and ``deployment_mode``
+are stamped by :func:`lmcache.usage_telemetry.transport.build_usage_payload`,
+not declared here. See ``README.md`` for the full schema contract and
+extension guide.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, ClassVar
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.distributed.config import StorageManagerConfig
+    from lmcache.v1.metadata import LMCacheMetadata
+    from lmcache.v1.multiprocess.config import MPServerConfig
+
+
+USAGE_SCHEMA_VERSION = 1
+"""Version stamped on every usage payload; bump when fields change meaning."""
+
+
+class DeploymentMode(Enum):
+    """Which LMCache deployment mode produced a payload.
+
+    Stamped on every payload as the ``deployment_mode`` key.
+    """
+
+    SINGLE_PROCESS = "single_process"
+    """LMCache runs inside the serving engine (vLLM/SGLang/TRT-LLM
+    integrations)."""
+
+    MP_SERVER = "mp_server"
+    """LMCache runs as a standalone multiprocess cache server."""
+
+
+@dataclass
+class UsageMessage:
+    """Base class of every wire message.
+
+    Subclasses set :attr:`ENDPOINT`; the wire ``message_type`` is the
+    subclass name.
+    """
+
+    ENDPOINT: ClassVar[str] = "context"
+    """Stats-server endpoint this message POSTs to."""
+
+
+@dataclass
+class EnvMessage(UsageMessage):
+    """Hardware and platform environment of the reporting process.
+
+    Sent once at startup by every reporter. Integer fields use ``0`` for
+    "unknown" (e.g. CPU count unavailable).
+    """
+
+    provider: str
+    num_cpu: int
+    cpu_type: str
+    cpu_family_model_stepping: str
+    total_memory: int
+    architecture: tuple[str, str]
+    platforms: str
+    gpu_count: int
+    gpu_type: str
+    gpu_memory_per_device: int
+    source: str
+
+
+@dataclass
+class EngineMessage(UsageMessage):
+    """Configuration snapshot of a single-process LMCacheEngine.
+
+    Sent once at engine startup (single-process integrations only).
+    """
+
+    chunksize: int
+    local_device: str
+    max_local_cache_size: int
+    remote_url: str | None
+    remote_serde: str | None
+    pipelined_backend: bool
+    save_decode_cache: bool
+    enable_blending: bool
+    blend_recompute_ratio: float
+    blend_min_tokens: int
+    model_name: str
+    world_size: int
+    worker_id: int
+    kv_dtype: torch.dtype
+    kv_shape: tuple[int, int, int, int, int]
+
+    @classmethod
+    def from_config(
+        cls, config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ) -> EngineMessage:
+        """Build the message from the engine configuration and metadata.
+
+        Args:
+            config: The engine configuration to snapshot.
+            metadata: The engine metadata (model, world size, kv layout).
+
+        Returns:
+            The populated message.
+        """
+        return cls(
+            chunksize=config.chunk_size,
+            local_device="cpu" if config.local_cpu else torch_device_type,
+            max_local_cache_size=int(config.max_local_cpu_size),
+            remote_url=config.remote_url,
+            remote_serde=config.remote_serde,
+            pipelined_backend=False,
+            save_decode_cache=config.save_decode_cache,
+            enable_blending=config.enable_blending,
+            blend_recompute_ratio=0.15,
+            blend_min_tokens=config.blend_min_tokens,
+            model_name=metadata.model_name,
+            world_size=metadata.world_size,
+            worker_id=metadata.worker_id,
+            kv_dtype=metadata.kv_dtype,
+            kv_shape=metadata.kv_shape,
+        )
+
+
+@dataclass
+class MetadataMessage(UsageMessage):
+    """Process start time and uptime at send time.
+
+    Sent once at engine startup (single-process integrations only).
+    """
+
+    start_time: str
+    duration: float
+
+
+@dataclass
+class MPServerMessage(UsageMessage):
+    """Configuration snapshot of a multiprocess (MP) cache server.
+
+    Sent once at MP server startup.
+
+    Note:
+        The server's operator-facing ``instance_id`` is deliberately not
+        included: it can be operator-chosen and therefore identifying.
+        Usage messages are correlated through
+        :class:`lmcache.usage_telemetry.identity.UsageIdentity` only.
+    """
+
+    lmcache_version: str
+    chunk_size: int
+    hash_algorithm: str
+    engine_type: str
+    enable_segmented_prefix: bool
+    supported_transfer_mode: str
+    separate_object_groups: bool
+    max_gpu_workers: int
+    max_cpu_workers: int
+    p2p_enabled: bool
+    l1_size_bytes: int
+    l1_medium: str
+    l1_shm_enabled: bool
+    eviction_policy: str
+    l2_adapter_types: str
+    l2_serde_types: str
+    l2_store_policy: str
+    l2_prefetch_policy: str
+
+    @classmethod
+    def from_configs(
+        cls,
+        mp_config: MPServerConfig,
+        storage_manager_config: StorageManagerConfig,
+    ) -> MPServerMessage:
+        """Build the message from the MP server and storage configurations.
+
+        Args:
+            mp_config: The MP server configuration.
+            storage_manager_config: The storage manager configuration.
+
+        Returns:
+            The populated message. ``l1_medium`` is one of ``"dram"``,
+            ``"gds"``, or ``"dram+devdax"``; ``l2_adapter_types`` is a
+            comma-joined list of adapter type names (empty when no L2 is
+            configured); ``l2_serde_types`` is comma-joined and aligned
+            with ``l2_adapter_types``, with an empty entry for adapters
+            that have no serde configured.
+        """
+        # Import here to avoid pulling the distributed config stack into
+        # every usage_telemetry import (single-process deployments never
+        # load it).
+        # First Party
+        from lmcache import __version__
+        from lmcache.v1.distributed.l2_adapters.config import (
+            get_type_name_for_config,
+        )
+
+        l1_config = storage_manager_config.l1_manager_config
+        memory_config = l1_config.memory_config
+        if l1_config.gds_l1_config is not None:
+            l1_size_bytes = l1_config.gds_l1_config.size_in_bytes
+            l1_medium = "gds"
+        else:
+            l1_size_bytes = (
+                memory_config.size_in_bytes + memory_config.devdax_size_in_bytes
+            )
+            l1_medium = "dram+devdax" if memory_config.devdax_path else "dram"
+        adapter_configs = storage_manager_config.l2_adapter_config.adapters
+        l2_adapter_types = ",".join(
+            get_type_name_for_config(adapter_config)
+            for adapter_config in adapter_configs
+        )
+        l2_serde_types = ",".join(
+            adapter_config.serde_config.type
+            if adapter_config.serde_config is not None
+            else ""
+            for adapter_config in adapter_configs
+        )
+        return cls(
+            lmcache_version=__version__,
+            chunk_size=mp_config.chunk_size,
+            hash_algorithm=mp_config.hash_algorithm,
+            engine_type=mp_config.engine_type,
+            enable_segmented_prefix=mp_config.enable_segmented_prefix,
+            supported_transfer_mode=mp_config.supported_transfer_mode,
+            separate_object_groups=mp_config.separate_object_groups,
+            max_gpu_workers=mp_config.max_gpu_workers,
+            max_cpu_workers=mp_config.max_cpu_workers,
+            p2p_enabled=mp_config.p2p_config.enabled,
+            l1_size_bytes=l1_size_bytes,
+            l1_medium=l1_medium,
+            l1_shm_enabled=bool(memory_config.shm_name),
+            eviction_policy=storage_manager_config.eviction_config.eviction_policy,
+            l2_adapter_types=l2_adapter_types,
+            l2_serde_types=l2_serde_types,
+            l2_store_policy=storage_manager_config.store_policy,
+            l2_prefetch_policy=storage_manager_config.prefetch_policy,
+        )
+
+
+@dataclass
+class ContinuousContextMessage(UsageMessage):
+    """Interval counters flushed periodically by the continuous reporter."""
+
+    ENDPOINT: ClassVar[str] = "cache-usage"
+
+    interval_num_stored_tokens: int
+    interval_num_hit_tokens: int
+    interval_stored_kv_size: int
+    sequence_number: int
+
+
+@dataclass
+class CacheLifespanMessage(UsageMessage):
+    """Cache-entry lifespan histogram flushed with each continuous report."""
+
+    ENDPOINT: ClassVar[str] = "cache-lifespan"
+
+    cache_lifespan_histogram: dict[float, int]
+    """Bucket lower bound (seconds) to sample count. Numeric keys become
+    strings on the wire (JSON object keys)."""
+    sequence_number: int
diff --git a/lmcache/usage_telemetry/mp.py b/lmcache/usage_telemetry/mp.py
new file mode 100644
index 0000000..c305cfe
--- /dev/null
+++ b/lmcache/usage_telemetry/mp.py
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Usage reporting for the multiprocess (MP) cache server."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.usage_telemetry.context import UsageContextBase
+from lmcache.usage_telemetry.env_probe import collect_env_message
+from lmcache.usage_telemetry.guard import swallow_telemetry_errors
+from lmcache.usage_telemetry.identity import is_usage_tracking_enabled
+from lmcache.usage_telemetry.messages import (
+    DeploymentMode,
+    MPServerMessage,
+    UsageMessage,
+)
+from lmcache.usage_telemetry.transport import UsageMessageSender
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.config import StorageManagerConfig
+    from lmcache.v1.multiprocess.config import MPServerConfig
+
+logger = init_logger(__name__)
+
+
+class MPUsageContext(UsageContextBase):
+    """Usage reporter for the multiprocess cache server.
+
+    Sends an ``EnvMessage`` and an ``MPServerMessage`` at startup.
+    """
+
+    def __init__(
+        self,
+        mp_config: MPServerConfig,
+        storage_manager_config: StorageManagerConfig,
+        local_log: str | None = None,
+        sender: UsageMessageSender | None = None,
+    ) -> None:
+        """Initialize the reporter.
+
+        Args:
+            mp_config: The MP server configuration to snapshot.
+            storage_manager_config: The storage manager configuration to
+                snapshot.
+            local_log: Path of a local log of sent payloads; ``None``
+                disables local logging.
+            sender: Message transport; ``None`` selects the default HTTP
+                sender.
+        """
+        super().__init__(DeploymentMode.MP_SERVER, local_log, sender)
+        self._mp_config = mp_config
+        self._storage_manager_config = storage_manager_config
+
+    def _collect_messages(self) -> list[UsageMessage]:
+        return [
+            collect_env_message(),
+            MPServerMessage.from_configs(self._mp_config, self._storage_manager_config),
+        ]
+
+
+@swallow_telemetry_errors
+def InitializeMPUsageContext(
+    mp_config: MPServerConfig,
+    storage_manager_config: StorageManagerConfig,
+    local_log: str | None = None,
+    sender: UsageMessageSender | None = None,
+) -> MPUsageContext | None:
+    """Start usage reporting for a multiprocess cache server.
+
+    Returns immediately; the startup report is sent in the background.
+    Never blocks or raises.
+
+    Args:
+        mp_config: The MP server configuration to snapshot.
+        storage_manager_config: The storage manager configuration to
+            snapshot.
+        local_log: Path of a local log of sent payloads; ``None`` disables
+            local logging.
+        sender: Message transport; ``None`` selects the default HTTP sender.
+
+    Returns:
+        The usage context, or ``None`` when usage tracking is disabled or
+        initialization failed.
+    """
+    if not is_usage_tracking_enabled():
+        return None
+    logger.info("Initializing MP usage context.")
+    context = MPUsageContext(mp_config, storage_manager_config, local_log, sender)
+    threading.Thread(
+        target=context.report_once, daemon=True, name="lmcache-usage-report"
+    ).start()
+    return context
diff --git a/lmcache/usage_telemetry/transport.py b/lmcache/usage_telemetry/transport.py
new file mode 100644
index 0000000..2cedc39
--- /dev/null
+++ b/lmcache/usage_telemetry/transport.py
@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Payload construction and HTTP transport for usage telemetry."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from urllib.parse import urljoin
+import json
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.connections import global_http_connection
+from lmcache.logging import init_logger
+from lmcache.usage_telemetry.identity import UsageIdentity
+from lmcache.usage_telemetry.messages import (
+    USAGE_SCHEMA_VERSION,
+    DeploymentMode,
+    UsageMessage,
+)
+
+logger = init_logger(__name__)
+
+
+def usage_server_url(endpoint: str) -> str:
+    """Build the stats-server URL for *endpoint*.
+
+    Args:
+        endpoint: Path component on the stats server, e.g. ``"context"``.
+
+    Returns:
+        The full URL, honoring the ``LMCACHE_USAGE_TRACK_URL`` override.
+    """
+    base = os.getenv("LMCACHE_USAGE_TRACK_URL", "http://stats.lmcache.ai:8080")
+    return urljoin(base, endpoint)
+
+
+class UsageMessageSender:
+    """Default HTTP transport for usage messages.
+
+    Posts JSON payloads with a short timeout and swallows every failure
+    (telemetry must never disturb serving). Inject a stub instance into the
+    usage contexts to capture payloads in tests.
+    """
+
+    def send(self, url: str, payload: dict[str, object]) -> None:
+        """POST one JSON payload to *url*; never raises.
+
+        Args:
+            url: Full endpoint URL on the stats server.
+            payload: Flat JSON-serializable payload.
+        """
+        try:
+            client = global_http_connection.get_sync_client()
+            client.post(
+                url,
+                data=json.dumps(payload),
+                headers={"Content-Type": "application/json"},
+                timeout=5,
+            )
+        except Exception as e:
+            logger.debug("Unable to send lmcache usage message: %s", e)
+
+
+DEFAULT_SENDER = UsageMessageSender()
+"""Shared default sender; stateless, safe to reuse across contexts."""
+
+
+def build_usage_payload(
+    message: UsageMessage, identity: UsageIdentity, mode: DeploymentMode
+) -> dict[str, object]:
+    """Flatten *message* into a payload stamped with identity and schema info.
+
+    The wire ``message_type`` is the message's class name, per the schema
+    contract in :mod:`lmcache.usage_telemetry.messages`.
+
+    Args:
+        message: The message to serialize; its fields become payload keys.
+        identity: Identifiers stamped on the payload.
+        mode: Deployment mode stamped as the ``deployment_mode`` key.
+
+    Returns:
+        A flat JSON-serializable dict (``torch.dtype`` values stringified).
+    """
+    payload: dict[str, object] = {
+        "message_type": type(message).__name__,
+        "schema_version": USAGE_SCHEMA_VERSION,
+        "session_id": identity.session_id,
+        "machine_id": identity.machine_id,
+        "deployment_mode": mode.value,
+    }
+    for key, value in vars(message).items():
+        payload[key] = str(value) if isinstance(value, torch.dtype) else value
+    return payload
diff --git a/lmcache/utils.py b/lmcache/utils.py
new file mode 100644
index 0000000..68ff244
--- /dev/null
+++ b/lmcache/utils.py
@@ -0,0 +1,781 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Tuple, TypeVar, Union
+import asyncio
+import functools
+import hashlib
+import inspect
+import re
+import threading
+import traceback
+import warnings
+
+try:
+    # Third Party
+    from nvtx import annotate  # type: ignore
+except ImportError:
+
+    def annotate(*args, **kwargs):
+        """Dummy decorator when nvtx is not available."""
+
+        def decorator(func):
+            return func
+
+        return decorator
+
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.memory_management import MemoryFormat
+
+logger = init_logger(__name__)
+
+# Type definition
+KVCache = Tuple[Tuple[torch.Tensor, torch.Tensor], ...]
+
+
+# Device utility functions
+def check_interprocess_event_support() -> None:
+    """Check if the current backend supports interprocess Events.
+
+    This function checks if torch_dev.Event exists and exposes the
+    interprocess parameter, which is required for multiprocess IPC.
+
+    Raises:
+        RuntimeError: If the backend does not support interprocess Events
+            or if the Event class doesn't expose the interprocess parameter.
+    """
+    # First Party
+    from lmcache import torch_dev, torch_device_type
+
+    if not hasattr(torch_dev, "Event"):
+        raise RuntimeError(
+            f"Backend '{torch_device_type}' does not support "
+            "interprocess Events (torch_dev.Event not available). "
+            "Multiprocess IPC requires CUDA."
+        )
+
+    event_cls = torch_dev.Event
+
+    def has_interprocess_parameter(obj) -> bool:
+        try:
+            sig = inspect.signature(obj)
+        except (TypeError, ValueError):
+            return False
+
+        return "interprocess" in sig.parameters
+
+    if not (
+        has_interprocess_parameter(event_cls)
+        or has_interprocess_parameter(event_cls.__new__)
+    ):
+        raise RuntimeError(
+            f"Backend '{torch_device_type}' does not support "
+            "interprocess=True parameter for Events. "
+            "Multiprocess IPC requires CUDA."
+        )
+
+    if not hasattr(torch_dev.Event, "from_ipc_handle"):
+        raise RuntimeError(
+            f"Backend '{torch_device_type}' does not support IPC event "
+            "handles (Event.from_ipc_handle not available). "
+            "Multiprocess IPC requires CUDA."
+        )
+
+
+# Math utility functions
+def cdiv(a: int, b: int) -> int:
+    """Ceiling division."""
+    return -(a // -b)
+
+
+def round_down(x: int, y: int) -> int:
+    """Round down x to the nearest multiple of y."""
+    return (x // y) * y
+
+
+def compress_slot_mapping(slots: list[int]) -> list[Union[int, list[int]]]:
+    """Compress a list of slot indices into ranges while preserving order.
+
+    Consecutive slots (3 or more) are represented as [start, end] ranges.
+    Single elements or pairs are kept as individual integers.
+    For example: [1, 2, 3, 4, 5, 9, 10, 11, 12] -> [[1, 5], [9, 12]]
+    Order-preserving: [5, 3, 1, 2, 4] -> [5, 3, 1, 2, 4] (no compression)
+    Mixed: [1, 2, 3, 4, 5, 7, 8] -> [[1, 5], 7, 8]
+
+    Args:
+        slots: List of slot indices (order is preserved).
+
+    Returns:
+        List of integers or [start, end] ranges. Ranges are only used
+        when there are 3 or more consecutive elements.
+    """
+    if not slots:
+        return []
+
+    result: list[Union[int, list[int]]] = []
+    range_start = slots[0]
+    range_end = slots[0]
+
+    for slot in slots[1:]:
+        if slot == range_end + 1:
+            # Extend current range
+            range_end = slot
+        else:
+            # Close current range and start a new one
+            _append_range_or_elements(result, range_start, range_end)
+            range_start = slot
+            range_end = slot
+
+    # Append the last range
+    _append_range_or_elements(result, range_start, range_end)
+    return result
+
+
+def _append_range_or_elements(
+    result: list[Union[int, list[int]]], start: int, end: int
+) -> None:
+    """Helper to append range or individual elements based on length.
+
+    Only compresses to [start, end] if there are 3 or more consecutive elements.
+    """
+    length = end - start + 1
+    if length >= 3:
+        # Compress: 3 or more consecutive elements
+        result.append([start, end])
+    else:
+        # Don't compress: 1 or 2 elements
+        for i in range(start, end + 1):
+            result.append(i)
+
+
+def decompress_slot_mapping(compressed: list[Union[int, list[int]]]) -> list[int]:
+    """Decompress slot ranges back to a list of slot indices.
+
+    Inverse operation of compress_slot_mapping.
+    For example: [[1, 5], [9, 12]] -> [1, 2, 3, 4, 5, 9, 10, 11, 12]
+    Mixed: [[1, 5], 7, 8] -> [1, 2, 3, 4, 5, 7, 8]
+
+    Args:
+        compressed: List of integers or [start, end] ranges from
+            compress_slot_mapping.
+
+    Returns:
+        List of slot indices.
+    """
+    slots: list[int] = []
+    for item in compressed:
+        if isinstance(item, list):
+            start, end = item
+            slots.extend(range(start, end + 1))
+        else:
+            slots.append(item)
+    return slots
+
+
+def parse_mixed_slot_mapping(
+    slot_mapping_str: str,
+) -> Tuple[Optional[list[int]], Optional[dict]]:
+    """Parse mixed format slot_mapping string.
+
+    Supports two formats:
+    1. Single numbers: "1,2,3,17,19"
+    2. Range format: "[9,12]" (represents 9,10,11,12)
+    3. Mixed format: "1,2,3,[9,12],17,19" (represents 1,2,3,9,10,11,12,17,19)
+
+    Args:
+        slot_mapping_str: String containing slot mapping information.
+
+    Returns:
+        Tuple of (slot_indices list, error dict).
+        If error dict is not None, slot_indices will be None.
+    """
+    try:
+        # Remove all whitespace
+        clean_str = "".join(slot_mapping_str.split())
+
+        # Split by comma but preserve range expressions
+        parts = []
+        buffer = ""
+        in_brackets = False
+
+        for char in clean_str:
+            if char == "[":
+                if in_brackets:
+                    raise ValueError("Nested brackets not allowed")
+                in_brackets = True
+                buffer += char
+            elif char == "]":
+                if not in_brackets:
+                    raise ValueError("Unmatched closing bracket")
+                in_brackets = False
+                buffer += char
+                parts.append(buffer)
+                buffer = ""
+            elif char == "," and not in_brackets:
+                if buffer:
+                    parts.append(buffer)
+                    buffer = ""
+            else:
+                buffer += char
+
+        # Add the last part if any
+        if buffer:
+            parts.append(buffer)
+
+        if in_brackets:
+            raise ValueError("Unclosed bracket")
+
+        # Parse each part
+        compressed: list[Union[int, list[int]]] = []
+
+        for part in parts:
+            part = part.strip()
+            if not part:
+                continue
+
+            # Check if it's a range format [start,end]
+            range_match = re.match(r"^\[(\d+),(\d+)\]$", part)
+            if range_match:
+                start = int(range_match.group(1))
+                end = int(range_match.group(2))
+                if start > end:
+                    raise ValueError(f"Range start {start} must be <= end {end}")
+                compressed.append([start, end])
+            else:
+                # Single number
+                try:
+                    num = int(part)
+                    compressed.append(num)
+                except ValueError as ve:
+                    raise ValueError(f"Invalid slot format: '{part}'") from ve
+
+        # Decompress to individual slot indices
+        slot_indices = decompress_slot_mapping(compressed)
+        return slot_indices, None
+
+    except Exception as e:
+        return None, {
+            "error": "Invalid slot_mapping format",
+            "message": (
+                f"slot_mapping must be comma-separated integers "
+                f"or ranges like [start,end]: {str(e)}"
+            ),
+        }
+
+
+try:
+    # First Party
+    from lmcache import _version  # type: ignore[attr-defined]
+
+    VERSION = getattr(_version, "__version__", "")
+    COMMIT_ID = getattr(_version, "__commit_id__", "")
+except ImportError:
+    VERSION = ""
+    COMMIT_ID = ""
+
+
+def get_version():
+    """Return a human-readable version string.
+
+    Returns:
+        ``"<version>-<commit-id>"``, with ``"NA"`` substituted when the
+        package version or commit id is not available (e.g. when running
+        from a source checkout without a tag).
+    """
+    version_display = VERSION if VERSION else "NA"
+    commit_id_display = COMMIT_ID if COMMIT_ID else "NA"
+    return f"{version_display}-{commit_id_display}"
+
+
+def convert_tokens_to_list(
+    tokens: Optional[Union[torch.Tensor, list[int]]], token_start: int, token_end: int
+) -> List[int]:
+    """Convert tokens to a list.
+    token_start and token_end delineate tokens to convert"""
+    if tokens is None:
+        return []
+
+    return (
+        tokens.tolist()[token_start : token_end + 1]
+        if isinstance(tokens, torch.Tensor)
+        else tokens[token_start : token_end + 1]
+    )
+
+
+@dataclass
+class DiskCacheMetadata:
+    path: str
+    size: int  # in bytes
+    shape: Optional[torch.Size] = None
+    dtype: Optional[torch.dtype] = None
+    cached_positions: Optional[torch.Tensor] = None
+    fmt: Optional[MemoryFormat] = None
+    pin_count: int = 0
+
+    def pin(self) -> bool:
+        self.pin_count += 1
+        return True
+
+    def unpin(self) -> bool:
+        self.pin_count -= 1
+        return True
+
+    @property
+    def is_pinned(self) -> bool:
+        return self.pin_count > 0
+
+    @property
+    def can_evict(self) -> bool:
+        """
+        Check if the disk cache can be evicted.
+        """
+        return not self.is_pinned
+
+
+TORCH_DTYPE_TO_STR_DTYPE = {
+    torch.half: "half",
+    torch.float16: "half",
+    torch.bfloat16: "bfloat16",
+    torch.float: "float",
+    torch.float32: "float",
+    torch.double: "double",
+    torch.float64: "double",
+    torch.int8: "int8",
+    torch.uint8: "uint8",
+    torch.int16: "int16",
+    torch.int32: "int32",
+    torch.int64: "int64",
+    torch.bool: "bool",
+}
+
+# FP8 variants (PyTorch ≥2.1)
+if hasattr(torch, "float8_e4m3fn"):
+    TORCH_DTYPE_TO_STR_DTYPE[torch.float8_e4m3fn] = "fp8_e4m3fn"
+if hasattr(torch, "float8_e4m3fnuz"):
+    TORCH_DTYPE_TO_STR_DTYPE[torch.float8_e4m3fnuz] = "fp8_e4m3fnuz"
+if hasattr(torch, "float8_e5m2"):
+    TORCH_DTYPE_TO_STR_DTYPE[torch.float8_e5m2] = "fp8_e5m2"
+if hasattr(torch, "float8_e5m2fnuz"):
+    TORCH_DTYPE_TO_STR_DTYPE[torch.float8_e5m2fnuz] = "fp8_e5m2fnuz"
+
+STR_DTYPE_TO_TORCH_DTYPE = {v: k for k, v in TORCH_DTYPE_TO_STR_DTYPE.items()}
+
+
+def parse_cache_key(key_str: str) -> Union[CacheEngineKey, LayerCacheEngineKey]:
+    """Parse a key string into either a CacheEngineKey or LayerCacheEngineKey.
+
+    Args:
+    key_str: String in format:
+        CacheEngineKey:
+            model_name@world_size@worker_id@chunk_hash@dtype[@tag%value...]
+        LayerCacheEngineKey:
+            model_name@world_size@worker_id@chunk_hash@dtype@layer_id[@tag%value...]
+
+    Returns:
+        CacheEngineKey if no layer_id, LayerCacheEngineKey if valid layer_id
+    """
+    parts = key_str.strip().split("@")
+    # parts[0]=model, [1]=world_size, [2]=worker_id, [3]=chunk_hash, [4]=dtype
+    # parts[5]=layer_id OR tag%value
+    # If parts[5] exists and is a digit (not containing '%'), it's a LayerCacheEngineKey
+    if len(parts) >= 6 and parts[5].isdigit():
+        return LayerCacheEngineKey.from_string(key_str)
+    return CacheEngineKey.from_string(key_str)
+
+
+@dataclass(slots=True)
+class CacheEngineKey:
+    model_name: str
+    world_size: int
+    worker_id: int
+    chunk_hash: int
+    dtype: torch.dtype
+    request_configs: Optional[dict] = field(default_factory=dict)
+    tags: Optional[tuple] = field(init=False, default=None)
+    _dtype_str: str = field(init=False, default="")
+
+    def __post_init__(self):
+        tag_list = None
+        if self.request_configs is not None:
+            for k, v in self.request_configs.items():
+                if k.startswith("lmcache.tag."):
+                    if tag_list is None:
+                        tag_list = []
+                    tag_list.append((k[len("lmcache.tag.") :], v))
+        if self.dtype not in TORCH_DTYPE_TO_STR_DTYPE:
+            raise ValueError(f"Unsupported dtype in CacheEngineKey: {self.dtype}")
+        self._dtype_str = TORCH_DTYPE_TO_STR_DTYPE[self.dtype]
+        # use tuple to save tags
+        self.tags = None if tag_list is None else tuple(tag_list)
+
+    def __hash__(self):
+        return hash(
+            (
+                self.model_name,
+                self.world_size,
+                self.worker_id,
+                self.chunk_hash,
+                self._dtype_str,
+                self.tags,
+            )
+        )
+
+    def __eq__(self, other):
+        if type(self) is type(other):
+            return (
+                self.model_name == other.model_name
+                and self.world_size == other.world_size
+                and self.worker_id == other.worker_id
+                and self.chunk_hash == other.chunk_hash
+                and self.dtype == other.dtype
+                and self.tags == other.tags
+            )
+
+        return False
+
+    def to_string(self):
+        s = (
+            f"{self.model_name}@{self.world_size}"
+            f"@{self.worker_id}@{self.chunk_hash_hex}@{self._dtype_str}"
+        )
+        if self.tags is not None and len(self.tags) != 0:
+            tags = [f"{k}%{v}" for k, v in self.tags]
+            s += "@" + "@".join(tags)
+        return s
+
+    def split_layers(self, num_layers: int) -> List["LayerCacheEngineKey"]:
+        """Split the key into multiple keys for each layer"""
+        keys = []
+        for layer_id in range(num_layers):
+            keys.append(
+                LayerCacheEngineKey(
+                    model_name=self.model_name,
+                    world_size=self.world_size,
+                    worker_id=self.worker_id,
+                    chunk_hash=self.chunk_hash,
+                    dtype=self.dtype,
+                    request_configs=self.request_configs,
+                    layer_id=layer_id,
+                )
+            )
+        return keys
+
+    def get_first_layer(self) -> "LayerCacheEngineKey":
+        """Return the key for the first layer"""
+        key = LayerCacheEngineKey(
+            model_name=self.model_name,
+            world_size=self.world_size,
+            worker_id=self.worker_id,
+            chunk_hash=self.chunk_hash,
+            dtype=self.dtype,
+            request_configs=self.request_configs,
+            layer_id=0,
+        )
+        return key
+
+    @staticmethod
+    def from_string(s):
+        parts = s.split("@")
+        if len(parts) < 5:
+            raise ValueError(f"Invalid key string: {s}")
+        request_configs = None
+        if len(parts) >= 6:
+            request_configs = {}
+            for kv in parts[5:]:
+                kvs = kv.split("%", 1)
+                if len(kvs) != 2:
+                    raise ValueError(f"Invalid key string: {s}")
+                request_configs["lmcache.tag." + kvs[0]] = kvs[1]
+        return CacheEngineKey(
+            model_name=parts[0],
+            world_size=int(parts[1]),
+            worker_id=int(parts[2]),
+            chunk_hash=int(parts[3], 16),
+            dtype=STR_DTYPE_TO_TORCH_DTYPE[parts[4]],
+            request_configs=request_configs,
+        )
+
+    def to_dict(self):
+        # Note(Kuntai): this is used for serializing CacheEngineKey via msgpack.
+        msg = {
+            "__type__": "CacheEngineKey",
+            "model_name": self.model_name,
+            "world_size": self.world_size,
+            "worker_id": self.worker_id,
+            "chunk_hash": self.chunk_hash,
+            "dtype": self._dtype_str,
+        }
+        if self.request_configs is not None and len(self.request_configs) != 0:
+            msg["request_configs"] = [
+                f"{k}%{v}" for k, v in self.request_configs.items()
+            ]
+        return msg
+
+    @staticmethod
+    def from_dict(d):
+        request_configs = None
+        if request_configs_list := d.get("request_configs"):
+            request_configs = {}
+            for kv in request_configs_list:
+                kvs = kv.split("%", 1)
+                if len(kvs) != 2:
+                    raise ValueError(f"Invalid key dict: {d}")
+                request_configs[kvs[0]] = kvs[1]
+        return CacheEngineKey(
+            model_name=d["model_name"],
+            world_size=d["world_size"],
+            worker_id=d["worker_id"],
+            chunk_hash=d["chunk_hash"],
+            dtype=STR_DTYPE_TO_TORCH_DTYPE[d["dtype"]],
+            request_configs=request_configs,
+        )
+
+    def with_new_worker_id(self, new_worker_id: int) -> "CacheEngineKey":
+        # Reconstruct the cache engine key with new worker id
+        return CacheEngineKey(
+            self.model_name,
+            world_size=self.world_size,
+            worker_id=new_worker_id,
+            chunk_hash=self.chunk_hash,
+            dtype=self.dtype,
+            request_configs=self.request_configs,
+        )
+
+    @property
+    def chunk_hash_hex(self) -> str:
+        if isinstance(self.chunk_hash, bytes):
+            return self.chunk_hash.hex()
+        return f"{self.chunk_hash:x}"
+
+
+@dataclass(slots=True)
+class LayerCacheEngineKey(CacheEngineKey):
+    """A key for the layer cache engine"""
+
+    layer_id: int = 0
+
+    def __hash__(self):
+        return hash(
+            (
+                self.model_name,
+                self.world_size,
+                self.worker_id,
+                self.chunk_hash,
+                self._dtype_str,
+                self.tags,
+                self.layer_id,
+            )
+        )
+
+    def __eq__(self, other):
+        if super(LayerCacheEngineKey, self).__eq__(other):
+            return self.layer_id == other.layer_id
+
+        return False
+
+    def to_string(self):
+        s = (
+            f"{self.model_name}@{self.world_size}"
+            f"@{self.worker_id}@{self.chunk_hash_hex}@{self._dtype_str}@{self.layer_id}"
+        )
+        if self.tags is not None and len(self.tags) != 0:
+            tags = [f"{k}%{v}" for k, v in self.tags]
+            s += "@" + "@".join(tags)
+        return s
+
+    def split_layers(self, num_layers: int) -> List["LayerCacheEngineKey"]:
+        """Split the key into multiple keys for each layer"""
+        keys = []
+        for layer_id in range(num_layers):
+            keys.append(
+                LayerCacheEngineKey(
+                    model_name=self.model_name,
+                    world_size=self.world_size,
+                    worker_id=self.worker_id,
+                    chunk_hash=self.chunk_hash,
+                    dtype=self.dtype,
+                    request_configs=self.request_configs,
+                    layer_id=layer_id,
+                )
+            )
+        return keys
+
+    @staticmethod
+    def from_string(s):
+        parts = s.split("@")
+        if len(parts) < 6:
+            raise ValueError(f"Invalid key string: {s}")
+        request_configs = None
+        if len(parts) >= 7:
+            request_configs = {}
+            for kv in parts[6:]:
+                kvs = kv.split("%", 1)
+                if len(kvs) != 2:
+                    raise ValueError(f"Invalid key string: {s}")
+                request_configs["lmcache.tag." + kvs[0]] = kvs[1]
+        return LayerCacheEngineKey(
+            model_name=parts[0],
+            world_size=int(parts[1]),
+            worker_id=int(parts[2]),
+            chunk_hash=int(parts[3], 16),
+            dtype=STR_DTYPE_TO_TORCH_DTYPE[parts[4]],
+            request_configs=request_configs,
+            layer_id=int(parts[5]),
+        )
+
+
+@dataclass
+class CacheStoreEvent:
+    block_hashes: list[int]
+    parent_block_hash: int | None
+    token_ids: list[int]
+    block_size: int
+
+    # Deprecated, use lora_name instead
+    # Retained for backwards compatibility
+    # Remove when vLLM removes it from BlockStored
+    lora_id: int | None
+
+    medium: str | None
+    lora_name: str | None
+
+
+class EngineType(Enum):
+    VLLM = "vllm"
+    SGLANG = "sglang"
+    TRTLLM = "trtllm"
+    MOCK = "mock"
+
+
+##### NVTX annotation #####
+_NVTX_COLORS = ["green", "blue", "purple", "rapids"]
+
+
+def _get_color_for_nvtx(name):
+    m = hashlib.sha256()
+    m.update(name.encode())
+    hash_value = int(m.hexdigest(), 16)
+    idx = hash_value % len(_NVTX_COLORS)
+    return _NVTX_COLORS[idx]
+
+
+def _lmcache_nvtx_annotate(func, domain="lmcache"):
+    """Decorator for applying nvtx annotations to methods in lmcache."""
+    return annotate(
+        message=func.__qualname__,
+        color=_get_color_for_nvtx(func.__qualname__),
+        domain=domain,
+    )(func)
+
+
+##### Observability Threading related #####
+_shared_observability_lock = threading.Lock()
+
+
+def thread_safe(func):
+    """Wrap a callable with the shared observability lock.
+
+    Args:
+        func: Callable to execute while holding the lock.
+
+    Returns:
+        A wrapper that serializes calls to ``func`` using the shared lock.
+    """
+
+    def wrapper(*args, **kwargs):
+        with _shared_observability_lock:
+            result = func(*args, **kwargs)
+        return result
+
+    return wrapper
+
+
+##### Deprecation #####
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def lmcache_deprecate(reason: str) -> Callable[[F], F]:
+    """Mark a function or method as deprecated.
+
+    Calling the wrapped callable emits a ``DeprecationWarning`` and logs a
+    warning the first time it is invoked, including the supplied reason.
+
+    Args:
+        reason: Human-readable explanation of why the callable is deprecated
+            and, ideally, what to use instead.
+
+    Returns:
+        A decorator that wraps the target callable while preserving its
+        signature and metadata.
+    """
+
+    def decorator(func: F) -> F:
+        warned = False
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            nonlocal warned
+            if not warned:
+                message = f"{func.__qualname__} is deprecated: {reason}"
+                warnings.warn(message, DeprecationWarning, stacklevel=2)
+                logger.warning(message)
+                warned = True
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+#### Thread/asyncio-related utilities ####
+def handle_thread_exception(args):
+    """Handle an uncaught exception reported by ``threading``.
+
+    Args:
+        args: Thread exception information provided by ``threading``.
+    """
+    logger.error(
+        f"Thread {args.thread.name} crashed: {args.exc_type.__name__}: {args.exc_value}"
+    )
+
+
+def start_loop_in_thread_with_exceptions(loop: asyncio.AbstractEventLoop):
+    """Run an event loop forever with an exception handler.
+
+    Args:
+        loop: Event loop to bind to the current thread and run.
+    """
+    # The loop must be set in the *same* thread where it runs.
+    asyncio.set_event_loop(loop)
+
+    # Catch unhandled exceptions from callbacks/tasks in this loop:
+    def loop_excepthook(loop, context):
+        msg = context.get("message", "Unhandled exception in event loop")
+        exc = context.get("exception")
+        logger.error("[asyncio] %s", msg)
+        if exc:
+            traceback.print_exception(type(exc), exc, exc.__traceback__)
+
+    loop.set_exception_handler(loop_excepthook)
+    loop.run_forever()
+
+
+#### Placeholder for dpsk broadcast functionality ####
+def mock_up_broadcast_fn(t: torch.Tensor, i: int) -> None:
+    raise NotImplementedError("Calling invalid broadcast function")
+
+
+def mock_up_broadcast_object_fn(a: Any, i: int) -> None:
+    raise NotImplementedError("Calling invalid broadcast object function")
diff --git a/lmcache/v1/__init__.py b/lmcache/v1/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/lmcache/v1/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/lmcache/v1/api_server/__init__.py b/lmcache/v1/api_server/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/lmcache/v1/api_server/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/lmcache/v1/api_server/__main__.py b/lmcache/v1/api_server/__main__.py
new file mode 100644
index 0000000..dcc8f34
--- /dev/null
+++ b/lmcache/v1/api_server/__main__.py
@@ -0,0 +1,537 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import asynccontextmanager
+from typing import Any, Dict, List, Optional, Tuple
+import argparse
+import asyncio
+import json
+import os
+import sys
+import uuid
+
+# Add project root to Python path for local development
+sys.path.insert(
+    0,
+    os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    ),
+)
+
+# Third Party
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+import uvicorn
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.config import (
+    load_controller_config_with_overrides,
+)
+from lmcache.v1.cache_controller.controller_manager import LMCacheControllerManager
+from lmcache.v1.cache_controller.message import (  # noqa: E501
+    CheckFinishMsg,
+    CheckFinishRetMsg,
+    ClearMsg,
+    ClearRetMsg,
+    CompressMsg,
+    CompressRetMsg,
+    DecompressMsg,
+    DecompressRetMsg,
+    ErrorMsg,
+    HealthMsg,
+    HealthRetMsg,
+    LookupMsg,
+    LookupRetMsg,
+    MoveMsg,
+    MoveRetMsg,
+    PinMsg,
+    PinRetMsg,
+    QueryInstMsg,
+    QueryInstRetMsg,
+    QueryWorkerInfoMsg,
+    QueryWorkerInfoRetMsg,
+    WorkerInfo,
+)
+from lmcache.v1.config_base import parse_command_line_extra_params
+from lmcache.v1.internal_api_server.api_registry import APIRegistry
+
+logger = init_logger(__name__)
+
+
+def parse_extra_params(extra_args: list) -> Dict[str, Any]:
+    """Parse extra parameters in key=value format"""
+    params = {}
+    for arg in extra_args:
+        if "=" in arg:
+            key, value = arg.split("=", 1)
+            key = key.lstrip("-")
+            try:
+                if value.lower() in ("true", "false"):
+                    params[key] = value.lower() == "true"
+                elif value.isdigit():
+                    params[key] = int(value)
+                elif value.replace(".", "", 1).isdigit():
+                    params[key] = float(value)
+                else:
+                    params[key] = value
+            except ValueError:
+                params[key] = value
+            logger.info(f"Extra parameter: {key} = {params[key]}")
+    return params
+
+
+def create_app(
+    controller_urls: dict[str, str],
+    health_check_interval: int,
+    lmcache_worker_timeout: int,
+) -> FastAPI:
+    """
+    Create a FastAPI application with endpoints for LMCache operations.
+    """
+    lmcache_controller_manager = LMCacheControllerManager(
+        controller_urls, health_check_interval, lmcache_worker_timeout
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        # Start background task here
+        lmcache_cluster_monitor_task = asyncio.create_task(
+            lmcache_controller_manager.start_all()
+        )
+        yield
+        # Optionally cancel the task on shutdown
+        lmcache_cluster_monitor_task.cancel()
+        try:
+            await lmcache_cluster_monitor_task
+        except asyncio.CancelledError:
+            pass
+
+    app = FastAPI(lifespan=lifespan)
+    app.state.lmcache_controller_manager = lmcache_controller_manager
+
+    # Register internal APIs (only common APIs, not vllm-specific ones)
+    registry = APIRegistry(app)
+    registry.register_all_apis(categories=["common", "controller"])
+
+    # Add static files for frontend
+    project_root = os.path.dirname(
+        os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    )
+    static_dir = os.path.join(
+        project_root,
+        "lmcache",
+        "v1",
+        "cache_controller",
+        "frontend",
+        "static",
+    )
+    if os.path.exists(static_dir):
+        app.mount("/static", StaticFiles(directory=static_dir), name="static")
+        logger.info("Controller frontend static files mounted at /static")
+    else:
+        logger.warning("Controller frontend static directory not found: %s", static_dir)
+
+    @app.get("/", response_class=HTMLResponse)
+    async def serve_frontend():
+        """Serve the Controller frontend HTML page."""
+        index_path = os.path.join(static_dir, "index.html")
+        if os.path.exists(index_path):
+            with open(index_path, "r") as f:
+                html_content = f.read()
+            return HTMLResponse(content=html_content)
+        else:
+            return HTMLResponse(
+                content="<h1>Controller Frontend not found</h1>"
+                "<p>Please build the frontend first.</p>",
+                status_code=404,
+            )
+
+    class QueryInstRequest(BaseModel):
+        event_id: str
+        ip: str
+
+    class QueryInstResponse(BaseModel):
+        event_id: str
+        res: str  # the instance id
+
+    @app.post("/query_instance")
+    async def query_instance(req: QueryInstRequest):
+        try:
+            event_id = "QueryInst" + str(uuid.uuid4())
+            msg = QueryInstMsg(
+                event_id=event_id,
+                ip=req.ip,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, QueryInstRetMsg)
+            return QueryInstResponse(
+                event_id=ret_msg.event_id,
+                res=ret_msg.instance_id,
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class LookupRequest(BaseModel):
+        tokens: List[int]
+
+    class LookupResponse(BaseModel):
+        event_id: str
+        # a list of (instance_id, location, token_count)
+        layout_info: Dict[str, Tuple[str, int]]
+
+    @app.post("/lookup", response_model=LookupResponse)
+    async def lookup(req: LookupRequest):
+        try:
+            event_id = "Lookup" + str(uuid.uuid4())
+            msg = LookupMsg(
+                event_id=event_id,
+                tokens=req.tokens,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, LookupRetMsg)
+            return LookupResponse(
+                event_id=ret_msg.event_id, layout_info=ret_msg.layout_info
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class ClearRequest(BaseModel):
+        instance_id: str
+        location: str
+
+    class ClearResponse(BaseModel):
+        event_id: str
+        num_tokens: int
+
+    @app.post("/clear", response_model=ClearResponse)
+    async def clear(req: ClearRequest):
+        try:
+            event_id = "Clear" + str(uuid.uuid4())
+            msg = ClearMsg(
+                event_id=event_id,
+                instance_id=req.instance_id,
+                location=req.location,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, ClearRetMsg)
+            return ClearResponse(
+                event_id=ret_msg.event_id, num_tokens=ret_msg.num_tokens
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class PinRequest(BaseModel):
+        instance_id: str
+        location: str
+        tokens: list[int]
+
+    class PinResponse(BaseModel):
+        event_id: str
+        num_tokens: int
+
+    @app.post("/pin", response_model=PinResponse)
+    async def pin(req: PinRequest):
+        try:
+            event_id = "Pin" + str(uuid.uuid4())
+            msg = PinMsg(
+                event_id=event_id,
+                instance_id=req.instance_id,
+                location=req.location,
+                tokens=req.tokens,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, PinRetMsg)
+            return PinResponse(event_id=ret_msg.event_id, num_tokens=ret_msg.num_tokens)
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class CompressRequest(BaseModel):
+        instance_id: str
+        method: str
+        location: str
+        tokens: Optional[List[int]] = []
+
+    class CompressResponse(BaseModel):
+        event_id: str
+        num_tokens: int
+
+    class DecompressRequest(BaseModel):
+        instance_id: str
+        method: str
+        location: str
+        tokens: Optional[List[int]] = []
+
+    class DecompressResponse(BaseModel):
+        event_id: str
+        num_tokens: int
+
+    @app.post("/compress", response_model=CompressResponse)
+    async def compress(req: CompressRequest):
+        try:
+            event_id = "Compress" + str(uuid.uuid4())
+            msg = CompressMsg(
+                event_id=event_id,
+                instance_id=req.instance_id,
+                method=req.method,
+                location=req.location,
+                tokens=req.tokens,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, CompressRetMsg)
+            return CompressResponse(
+                event_id=ret_msg.event_id, num_tokens=ret_msg.num_tokens
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    @app.post("/decompress", response_model=DecompressResponse)
+    async def decompress(req: DecompressRequest):
+        try:
+            event_id = "Decompress" + str(uuid.uuid4())
+            msg = DecompressMsg(
+                event_id=event_id,
+                instance_id=req.instance_id,
+                method=req.method,
+                location=req.location,
+                tokens=req.tokens,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert isinstance(ret_msg, DecompressRetMsg)
+            return DecompressResponse(
+                event_id=ret_msg.event_id, num_tokens=ret_msg.num_tokens
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class MoveRequest(BaseModel):
+        # (instance_id, location)
+        old_position: Tuple[str, str]
+        new_position: Tuple[str, str]
+        tokens: Optional[List[int]] = []
+        should_copy: Optional[bool] = False
+
+    class MoveResponse(BaseModel):
+        event_id: str
+        num_tokens: int
+
+    @app.post("/move", response_model=MoveResponse)
+    async def move(req: MoveRequest):
+        try:
+            event_id = "Move" + str(uuid.uuid4())
+            msg = MoveMsg(
+                event_id=event_id,
+                old_position=req.old_position,
+                new_position=req.new_position,
+                tokens=req.tokens,
+                copy=req.should_copy,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, MoveRetMsg)
+            return MoveResponse(
+                event_id=ret_msg.event_id,
+                num_tokens=ret_msg.num_tokens,
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class HealthRequest(BaseModel):
+        instance_id: str
+
+    class HealthResponse(BaseModel):
+        event_id: str
+        # worker_id -> error_code
+        error_codes: dict[int, int]
+
+    @app.post("/health", response_model=HealthResponse)
+    async def health(req: HealthRequest):
+        try:
+            event_id = "health" + str(uuid.uuid4())
+            msg = HealthMsg(
+                event_id=event_id,
+                instance_id=req.instance_id,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, HealthRetMsg)
+            return HealthResponse(
+                event_id=ret_msg.event_id, error_codes=ret_msg.error_codes
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class CheckFinishRequest(BaseModel):
+        event_id: str
+
+    class CheckFinishResponse(BaseModel):
+        status: str
+
+    @app.post("/check_finish", response_model=CheckFinishResponse)
+    async def check_finish(req: CheckFinishRequest):
+        try:
+            msg = CheckFinishMsg(
+                event_id=req.event_id,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, CheckFinishRetMsg)
+            return CheckFinishResponse(status=ret_msg.status)
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    class QueryWorkerInfoRequest(BaseModel):
+        instance_id: str
+        worker_ids: Optional[list[int]] = None
+
+    class QueryWorkerInfoResponse(BaseModel):
+        event_id: str
+        worker_infos: list[WorkerInfo]
+
+    @app.post("/query_worker_info", response_model=QueryWorkerInfoResponse)
+    async def query_worker_info(req: QueryWorkerInfoRequest):
+        try:
+            event_id = "QueryWorkerInfo" + str(uuid.uuid4())
+            msg = QueryWorkerInfoMsg(
+                event_id=event_id,
+                instance_id=req.instance_id,
+                worker_ids=req.worker_ids,
+            )
+            ret_msg = await lmcache_controller_manager.handle_orchestration_message(msg)
+            assert not isinstance(ret_msg, ErrorMsg), ret_msg.error
+            assert isinstance(ret_msg, QueryWorkerInfoRetMsg)
+            return QueryWorkerInfoResponse(
+                event_id=ret_msg.event_id, worker_infos=ret_msg.worker_infos
+            )
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e)) from e
+
+    return app
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--config", type=str, help="Path to controller configuration file"
+    )
+    parser.add_argument("--host", type=str, default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=9000)
+    parser.add_argument(
+        "--monitor-ports",
+        type=json.loads,
+        default=None,
+        help='JSON string of monitor ports, e.g. \'{"pull": 8300, "reply": 8400}\'',
+    )
+    parser.add_argument(
+        "--monitor-port",
+        type=int,
+        default=9001,
+        help="The controller pull port to maintain backward compatibility.",
+    )
+    parser.add_argument(
+        "--health-check-interval",
+        type=int,
+        default=-1,
+        help="Health check interval in secs, default is -1, which means disabled.",
+    )
+    parser.add_argument(
+        "--lmcache-worker-timeout",
+        type=int,
+        default=300,
+        help="The lmcache worker timeout in seconds.",
+    )
+
+    # Parse known args first, then handle extra parameters
+    args, extra = parser.parse_known_args()
+    extra_params = parse_command_line_extra_params(extra)
+
+    try:
+        # Build overrides dictionary from command-line arguments
+        override_dict = {}
+
+        # Map command-line arguments to config keys
+        arg_mappings = {
+            "host": "controller_host",
+            "port": "controller_port",
+            "monitor_ports": "controller_monitor_ports",
+            "health_check_interval": "health_check_interval",
+            "lmcache_worker_timeout": "lmcache_worker_timeout",
+        }
+
+        for arg_name, config_key in arg_mappings.items():
+            arg_value = getattr(args, arg_name)
+            if arg_value is not None:
+                override_dict[config_key] = arg_value
+
+        # Add extra parameters
+        if extra_params:
+            override_dict.update(extra_params)
+
+        # Load configuration using the generic utility function
+        # This replaces the previous manual config loading code
+        config = load_controller_config_with_overrides(
+            config_file_path=args.config,
+            overrides=override_dict,
+        )
+
+        # Build controller URLs from config or arguments
+        if config.controller_monitor_ports is not None:
+            controller_urls = {
+                "pull": (
+                    f"{config.controller_host}:"
+                    f"{config.controller_monitor_ports['pull']}"
+                ),
+                "reply": (
+                    f"{config.controller_host}:"
+                    f"{config.controller_monitor_ports['reply']}"
+                ),
+                "heartbeat": (
+                    f"{config.controller_host}:"
+                    f"{config.controller_monitor_ports['heartbeat']}"
+                    if config.controller_monitor_ports.get("heartbeat")
+                    else None
+                ),
+            }
+        else:
+            if args.monitor_port != 9001:  # Only warn if explicitly set
+                logger.warning(
+                    "Argument --monitor-port will be deprecated soon. "
+                    "Please use --monitor-ports instead."
+                )
+            controller_urls = {
+                "pull": f"{config.controller_host}:{args.monitor_port}",
+                "reply": None,
+                "heartbeat": None,
+            }
+
+        # Use config values for health check and timeout
+        health_check_interval = config.health_check_interval
+        lmcache_worker_timeout = config.lmcache_worker_timeout
+
+        app = create_app(controller_urls, health_check_interval, lmcache_worker_timeout)
+
+        logger.info(
+            f"Starting LMCache controller at "
+            f"{config.controller_host}:{config.controller_port}"
+        )
+        ports_message = f"Monitoring lmcache workers at ports {controller_urls}"
+        logger.info(ports_message)
+        logger.info(f"Health check interval: {health_check_interval}s")
+        logger.info(f"Worker timeout: {lmcache_worker_timeout}s")
+
+        uvicorn.run(app, host=config.controller_host, port=config.controller_port)
+    except TimeoutError as e:
+        logger.error(e)
+    except Exception as e:
+        logger.error(f"Failed to start controller: {e}", exc_info=True)
+        sys.exit(1)  # Exit with error code
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/v1/basic_check.py b/lmcache/v1/basic_check.py
new file mode 100644
index 0000000..db6c6a5
--- /dev/null
+++ b/lmcache/v1/basic_check.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import asyncio
+
+# First Party
+from lmcache.v1.check import registry
+
+model_name = "/lmcache_test_model/"
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="LMCache basic check Tool")
+    parser.add_argument(
+        "--mode",
+        required=True,
+        help="Operation mode (e.g. test_remote, test_storage_manager). "
+        "Use 'list' to show available modes",
+    )
+    parser.add_argument("--model", default=model_name, help="model name")
+    parser.add_argument(
+        "--num-keys",
+        type=int,
+        default=5,
+        help="Number of keys for gen mode or test iterations "
+        "for test_* modes (default: 5)",
+    )
+    parser.add_argument(
+        "--concurrency",
+        type=int,
+        default=16,
+        help="Concurrency level for generation (gen mode only)",
+    )
+    parser.add_argument(
+        "--offset",
+        type=int,
+        default=0,
+        help="Offset for key generation (gen mode only)",
+    )
+    parser.add_argument(
+        "--l2-adapter",
+        dest="l2_adapter",
+        action="append",
+        default=[],
+        type=str,
+        metavar="JSON",
+        help="L2 adapter spec as JSON (test_l2_adapter mode). "
+        'e.g. \'{"type":"mock","max_size_gb":1}\'.',
+    )
+    parser.add_argument(
+        "--obj-size",
+        dest="obj_size",
+        type=int,
+        default=None,
+        help="Object size in number of elements (default: 1024)",
+    )
+    parser.add_argument(
+        "--kv-dtype",
+        dest="kv_dtype",
+        type=str,
+        default=None,
+        help="KV dtype, e.g. float32, bfloat16, float16 (default depends on mode)",
+    )
+    parser.add_argument(
+        "--settle-time",
+        dest="settle_time",
+        type=float,
+        default=0.0,
+        help="Seconds to wait after store before load "
+        "(default: 0, useful for remote backends)",
+    )
+    return parser.parse_args()
+
+
+async def main():
+    args = parse_args()
+
+    # List available modes if requested
+    if args.mode == "list":
+        registry.load_modes()
+        print("Available check modes:")
+        for mode_name in registry.modes:
+            print(f"  - {mode_name}")
+        return
+
+    # Get the requested mode function
+    mode_func = registry.get_mode(args.mode)
+    if not mode_func:
+        print(
+            f"Error: Unknown mode '{args.mode}'. "
+            "Use '--mode list' to see available modes."
+        )
+        return
+
+    # Prepare arguments for the mode function
+    mode_args = {
+        "model": args.model,
+        "num_keys": args.num_keys,
+        "concurrency": args.concurrency,
+        "offset": args.offset,
+        "l2_adapter": args.l2_adapter,
+        "obj_size": args.obj_size,
+        "kv_dtype": args.kv_dtype,
+        "settle_time": args.settle_time,
+    }
+
+    # Execute the mode function
+    await mode_func(**mode_args)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/lmcache/v1/cache_controller/__init__.py b/lmcache/v1/cache_controller/__init__.py
new file mode 100644
index 0000000..4536df5
--- /dev/null
+++ b/lmcache/v1/cache_controller/__init__.py
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.cache_controller.executor import LMCacheClusterExecutor  # noqa: E501
+from lmcache.v1.cache_controller.worker import LMCacheWorker  # noqa: E501
+
+__all__ = [
+    "LMCacheClusterExecutor",
+    "LMCacheWorker",
+]
diff --git a/lmcache/v1/cache_controller/commands/__init__.py b/lmcache/v1/cache_controller/commands/__init__.py
new file mode 100644
index 0000000..6833241
--- /dev/null
+++ b/lmcache/v1/cache_controller/commands/__init__.py
@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Heartbeat commands module
+
+This module provides the command abstraction for the heartbeat mechanism.
+Commands can be sent from controller to workers through heartbeat responses.
+"""
+
+# First Party
+from lmcache.v1.cache_controller.commands.base import HeartbeatCommand
+from lmcache.v1.cache_controller.commands.full_sync import FullSyncCommand
+
+__all__ = [
+    "HeartbeatCommand",
+    "FullSyncCommand",
+]
diff --git a/lmcache/v1/cache_controller/commands/base.py b/lmcache/v1/cache_controller/commands/base.py
new file mode 100644
index 0000000..3de6466
--- /dev/null
+++ b/lmcache/v1/cache_controller/commands/base.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base class for heartbeat commands"""
+
+# Standard
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+# Third Party
+import msgspec
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+
+class HeartbeatCommand(msgspec.Struct, tag_field="command_type"):
+    """Base class for heartbeat commands (polymorphic)
+
+    This abstraction allows controller to send various commands to workers
+    through the heartbeat mechanism. Each command type is a subclass with
+    its own specific fields.
+
+    Uses msgspec's tagged union for serialization/deserialization.
+    """
+
+    reason: Optional[str] = None  # Why this command is issued
+    args: Optional[Dict[str, Any]] = None  # Extension arguments for command
+
+    def describe(self) -> str:
+        return f"{self.__class__.__name__}(reason={self.reason}, args={self.args})"
+
+    def execute(self, worker: "LMCacheWorker") -> None:
+        """Execute this command on the worker. Override in subclasses."""
+        raise NotImplementedError(
+            f"{self.__class__.__name__}.execute() not implemented"
+        )
diff --git a/lmcache/v1/cache_controller/commands/full_sync.py b/lmcache/v1/cache_controller/commands/full_sync.py
new file mode 100644
index 0000000..6e54798
--- /dev/null
+++ b/lmcache/v1/cache_controller/commands/full_sync.py
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Full sync command implementation"""
+
+# Standard
+from typing import TYPE_CHECKING
+import asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.commands.base import HeartbeatCommand
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+logger = init_logger(__name__)
+
+
+class FullSyncCommand(HeartbeatCommand, tag="full_sync"):
+    """Command to request full state synchronization
+
+    Sent when the controller needs the worker to perform a full sync,
+    e.g., after controller restart or worker re-registration.
+    """
+
+    # FullSync-specific fields can be added here, e.g.:
+    # sync_scope: Optional[str] = None  # "all", "metadata", "data"
+    # priority: int = 0  # Sync priority level
+
+    def describe(self) -> str:
+        return f"FullSyncCommand(reason={self.reason}, args={self.args})"
+
+    def execute(self, worker: "LMCacheWorker") -> None:
+        """Trigger full sync on the worker"""
+        logger.info(
+            "Received full sync command with reason: %s, args: %s",
+            self.reason,
+            self.args,
+        )
+
+        sender = worker._get_full_sync_sender()
+
+        # Check if full sync is already in progress
+        if sender.is_syncing:
+            logger.warning("Full sync already in progress, skipping")
+            return
+
+        # Trigger full sync in background
+        asyncio.create_task(sender.start_full_sync(self.reason))
diff --git a/lmcache/v1/cache_controller/config.py b/lmcache/v1/cache_controller/config.py
new file mode 100644
index 0000000..bdc83f7
--- /dev/null
+++ b/lmcache/v1/cache_controller/config.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LMCache Controller Configuration
+
+Configuration system for LMCache Controller that:
+- Loads configuration from YAML file or environment variables
+- Supports command-line parameter overrides
+- Provides thread-safe singleton pattern for global access
+"""
+
+# Standard
+from typing import Any, Dict, Optional
+import json
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config_base import (
+    create_config_class,
+    create_singleton_config,
+    load_config_with_overrides,
+)
+
+logger = init_logger(__name__)
+
+
+# Controller-specific configuration definitions
+_CONTROLLER_CONFIG_DEFINITIONS: dict[str, dict[str, Any]] = {
+    # Basic controller configurations
+    "controller_monitor_ports": {
+        "type": Optional[dict],
+        "default": '{"pull": 8300, "reply": 8400}',
+        "env_converter": lambda x: (
+            x if isinstance(x, dict) else json.loads(x) if x else None
+        ),
+        "description": "JSON string of monitor ports",
+    },
+    "controller_host": {
+        "type": str,
+        "default": "0.0.0.0",
+        "env_converter": str,
+        "description": "Controller host address",
+    },
+    "controller_port": {
+        "type": int,
+        "default": 9000,
+        "env_converter": int,
+        "description": "Controller API server port",
+    },
+    "health_check_interval": {
+        "type": int,
+        "default": -1,
+        "env_converter": int,
+        "description": "Health check interval in seconds (-1 = disabled)",
+    },
+    "lmcache_worker_timeout": {
+        "type": int,
+        "default": 300,
+        "env_converter": int,
+        "description": "LMCache worker timeout in seconds",
+    },
+    # Extra configurations
+    "extra_config": {
+        "type": Optional[dict],
+        "default": None,
+        "env_converter": lambda x: (
+            x if isinstance(x, dict) else json.loads(x) if x else None
+        ),
+        "description": "Extra configuration parameters",
+    },
+}
+
+
+# Specialized methods that are unique to ControllerConfig
+def _validate_config(self):
+    """Validate configuration parameters"""
+    # Validate timeouts
+    if self.health_check_interval != -1 and self.health_check_interval < 1:
+        raise ValueError(f"Invalid health_check_interval: {self.health_check_interval}")
+    return self
+
+
+def _log_config(self):
+    """Log configuration"""
+    config_dict = {}
+    for name in _CONTROLLER_CONFIG_DEFINITIONS:
+        value = getattr(self, name)
+        config_dict[name] = value
+
+    logger.info(f"Controller Configuration: {config_dict}")
+    return self
+
+
+def _post_init(self):
+    """Post-initialization setup"""
+    pass
+
+
+# Create configuration class using the base utility
+ControllerConfig = create_config_class(
+    config_name="ControllerConfig",
+    config_definitions=_CONTROLLER_CONFIG_DEFINITIONS,
+    namespace_extras={
+        "validate": _validate_config,
+        "log_config": _log_config,
+        "__post_init__": _post_init,
+    },
+    env_prefix="LMCACHE_CONTROLLER_",
+)
+
+
+# Create singleton getter using the base utility
+controller_get_or_create_config = create_singleton_config(
+    getter_func_name="controller_get_or_create_config",
+    config_class=ControllerConfig,
+    config_env_var="LMCACHE_CONTROLLER_CONFIG_FILE",
+)
+
+
+def override_controller_config_from_dict(
+    config: "ControllerConfig",  # type: ignore[valid-type]
+    overrides: dict[str, Any],
+):
+    """Override configuration with dictionary"""
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            old_value = getattr(config, key)
+
+            # Check if this field has an env_converter in the definitions
+            if key in _CONTROLLER_CONFIG_DEFINITIONS:
+                env_converter = _CONTROLLER_CONFIG_DEFINITIONS[key].get("env_converter")
+                if env_converter:
+                    try:
+                        # Apply the env_converter to the value
+                        converted_value = env_converter(value)
+                        setattr(config, key, converted_value)
+                    except (ValueError, json.JSONDecodeError) as e:
+                        logger.warning(f"Failed to convert {key}={value!r}: {e}")
+                        # Keep the original value if conversion fails
+                        setattr(config, key, value)
+                else:
+                    setattr(config, key, value)
+            else:
+                setattr(config, key, value)
+
+            new_value = getattr(config, key)
+            if old_value != new_value:
+                logger.info(
+                    f"Override controller config: {key} = {new_value} (was {old_value})"
+                )
+        else:
+            logger.warning(f"Unknown controller config key: {key}, ignoring")
+
+
+def load_controller_config_with_overrides(
+    config_file_path: Optional[str] = None,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> "ControllerConfig":  # type: ignore[valid-type]
+    """
+    Load controller configuration with support for file, env vars, and overrides.
+
+    This function uses the generic load_config_with_overrides utility from
+    config_base.py to reduce code duplication.
+
+    Args:
+        config_file_path: Optional direct path to config file
+        overrides: Optional dictionary of configuration overrides
+
+    Returns:
+        Loaded and validated ControllerConfig instance
+    """
+    return load_config_with_overrides(
+        config_class=ControllerConfig,
+        config_file_env_var="LMCACHE_CONTROLLER_CONFIG_FILE",
+        config_file_path=config_file_path,
+        overrides=overrides,
+    )
diff --git a/lmcache/v1/cache_controller/controller_manager.py b/lmcache/v1/cache_controller/controller_manager.py
new file mode 100644
index 0000000..9cbae8a
--- /dev/null
+++ b/lmcache/v1/cache_controller/controller_manager.py
@@ -0,0 +1,535 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+import asyncio
+import json
+import threading
+import time
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.controllers import KVController, RegistrationController
+from lmcache.v1.cache_controller.executor import LMCacheClusterExecutor
+from lmcache.v1.cache_controller.observability import (
+    PrometheusLogger,
+    SocketMetricsContext,
+    SocketType,
+)
+from lmcache.v1.rpc_utils import (
+    get_ip,
+    get_zmq_context,
+    get_zmq_socket,
+)
+
+from lmcache.v1.cache_controller.message import (  # isort: skip
+    BatchedKVOperationMsg,
+    BatchedP2PLookupMsg,
+    CheckFinishMsg,
+    ClearMsg,
+    CompressMsg,
+    DecompressMsg,
+    DeRegisterMsg,
+    ErrorMsg,
+    FullSyncBatchMsg,
+    FullSyncEndMsg,
+    FullSyncStartMsg,
+    FullSyncStatusMsg,
+    HealthMsg,
+    HeartbeatMsg,
+    LookupMsg,
+    MoveMsg,
+    Msg,
+    MsgBase,
+    OrchMsg,
+    OrchRetMsg,
+    PinMsg,
+    QueryInstMsg,
+    QueryWorkerInfoMsg,
+    RegisterMsg,
+    WorkerMsg,
+    WorkerReqMsg,
+    WorkerReqRetMsg,
+)
+
+logger = init_logger(__name__)
+
+# TODO(Jiayi): Need to align the message types. For example,
+# a controller should take in an control message and return
+# a control message.
+
+
+class LMCacheControllerManager:
+    def __init__(
+        self,
+        controller_urls: dict[str, str],
+        health_check_interval: int,
+        lmcache_worker_timeout: int,
+        full_sync_completion_threshold: float = 0.8,
+        full_sync_timeout_s: float = 300.0,
+    ):
+        # Initialize stats logger
+        prometheus_labels = {
+            "role": "controller",
+        }
+        PrometheusLogger.GetOrCreate(prometheus_labels)
+        self.zmq_context = get_zmq_context()
+        self.controller_urls = controller_urls
+        # TODO(Jiayi): We might need multiple sockets if there are more
+        # controllers. For now, we use a single socket to receive messages
+        # for all controllers.
+        # Similarly we might need more sockets to handle different control
+        # messages. For now, we use one socket to handle all control messages.
+
+        # TODO(Jiayi): Another thing is that we might need to decoupe the
+        # interactions among `handle_worker_message`, `handle_control_message`
+        # and `handle_orchestration_message`. For example, in
+        # `handle_orchestration_message`, we might need to call
+        # `issue_control_message`. This will make the system less concurrent.
+
+        # Micro controllers
+        self.controller_pull_socket = get_zmq_socket(
+            self.zmq_context,
+            self.controller_urls["pull"],
+            protocol="tcp",
+            role=zmq.PULL,  # type: ignore[attr-defined]
+            bind_or_connect="bind",
+        )
+
+        if self.controller_urls["reply"] is not None:
+            self.controller_reply_socket = get_zmq_socket(
+                self.zmq_context,
+                self.controller_urls["reply"],
+                protocol="tcp",
+                role=zmq.ROUTER,  # type: ignore[attr-defined]
+                bind_or_connect="bind",
+            )
+
+        # Dedicated heartbeat socket to avoid blocking from other requests
+        if self.controller_urls.get("heartbeat") is not None:
+            self.controller_heartbeat_socket = get_zmq_socket(
+                self.zmq_context,
+                self.controller_urls["heartbeat"],
+                protocol="tcp",
+                role=zmq.ROUTER,  # type: ignore[attr-defined]
+                bind_or_connect="bind",
+            )
+        else:
+            self.controller_heartbeat_socket = None
+        self.reg_controller = RegistrationController()
+        self.kv_controller = KVController(
+            registry=self.reg_controller.registry,
+            full_sync_completion_threshold=full_sync_completion_threshold,
+            full_sync_timeout_s=full_sync_timeout_s,
+        )
+
+        # Cluster executor
+        self.cluster_executor = LMCacheClusterExecutor(
+            reg_controller=self.reg_controller,
+        )
+
+        # post initialization of controllers
+        self.kv_controller.post_init(
+            reg_controller=self.reg_controller,
+            cluster_executor=self.cluster_executor,
+        )
+        self.reg_controller.post_init(
+            kv_controller=self.kv_controller,
+            cluster_executor=self.cluster_executor,
+        )
+        self.health_check_interval = health_check_interval
+        self.lmcache_worker_timeout = lmcache_worker_timeout
+
+        if self.health_check_interval > 0:
+            logger.info(
+                "Start health check thread, interval: %s", self.health_check_interval
+            )
+            self.loop = asyncio.new_event_loop()
+            self.thread = threading.Thread(
+                target=self.loop.run_forever,
+                daemon=True,
+                name="controller-health-thread",
+            )
+            self.thread.start()
+            asyncio.run_coroutine_threadsafe(self.health_check(), self.loop)
+
+        # Setup socket message count metrics
+        self._setup_socket_metrics()
+
+    async def handle_worker_message(self, msg: WorkerMsg) -> None:
+        if isinstance(msg, RegisterMsg):
+            await self.reg_controller.register(msg)
+        elif isinstance(msg, DeRegisterMsg):
+            await self.reg_controller.deregister(msg)
+        elif isinstance(msg, BatchedKVOperationMsg):
+            await self.kv_controller.handle_batched_kv_operations(msg)
+        elif isinstance(msg, FullSyncBatchMsg):
+            await self.kv_controller.handle_full_sync_batch(msg)
+        elif isinstance(msg, FullSyncEndMsg):
+            await self.kv_controller.handle_full_sync_end(msg)
+        else:
+            logger.error(f"Unknown worker message type: {msg}")
+
+    async def handle_worker_req_message(
+        self, msg: WorkerReqMsg
+    ) -> Union[WorkerReqRetMsg, ErrorMsg]:
+        ret_msg: Union[WorkerReqRetMsg, ErrorMsg]
+        if isinstance(msg, RegisterMsg):
+            # Build extra_config with heartbeat_url if available
+            extra_config: dict[str, str] = {}
+            if self.controller_urls.get("heartbeat") is not None:
+                # Convert bind address (e.g., "0.0.0.0:8082" or "*:8082")
+                # to a connectable address using actual controller IP
+                heartbeat_bind_url = self.controller_urls["heartbeat"]
+                heartbeat_url = self._convert_bind_to_connect_url(
+                    heartbeat_bind_url, worker_ip=msg.ip
+                )
+                extra_config["heartbeat_url"] = heartbeat_url
+                logger.debug(
+                    "Returning heartbeat_url to worker: %s (bind: %s)",
+                    heartbeat_url,
+                    heartbeat_bind_url,
+                )
+            ret_msg = await self.reg_controller.register(msg, extra_config)
+        elif isinstance(msg, BatchedP2PLookupMsg):
+            ret_msg = await self.kv_controller.batched_p2p_lookup(msg)
+        elif isinstance(msg, HeartbeatMsg):
+            ret_msg = await self.reg_controller.heartbeat(msg)
+        elif isinstance(msg, FullSyncStartMsg):
+            ret_msg = await self.kv_controller.handle_full_sync_start(msg)
+        elif isinstance(msg, FullSyncStatusMsg):
+            ret_msg = await self.kv_controller.handle_full_sync_status(msg)
+        else:
+            logger.error(f"Unknown worker request message type: {msg}")
+            ret_msg = ErrorMsg(error=f"Unknown message type: {type(msg)}")
+        return ret_msg
+
+    async def handle_orchestration_message(self, msg: OrchMsg) -> OrchRetMsg:
+        if isinstance(msg, LookupMsg):
+            return await self.kv_controller.lookup(msg)
+        elif isinstance(msg, HealthMsg):
+            return await self.reg_controller.health(msg)
+        elif isinstance(msg, QueryInstMsg):
+            return await self.reg_controller.get_instance_id(msg)
+        elif isinstance(msg, ClearMsg):
+            return await self.kv_controller.clear(msg)
+        elif isinstance(msg, PinMsg):
+            return await self.kv_controller.pin(msg)
+        elif isinstance(msg, CompressMsg):
+            return await self.kv_controller.compress(msg)
+        elif isinstance(msg, DecompressMsg):
+            return await self.kv_controller.decompress(msg)
+        elif isinstance(msg, MoveMsg):
+            return await self.kv_controller.move(msg)
+        elif isinstance(msg, CheckFinishMsg):
+            # FIXME(Jiayi): This `check_finish` thing
+            # shouldn't be implemented in kv_controller.
+            return await self.kv_controller.check_finish(msg)
+        elif isinstance(msg, QueryWorkerInfoMsg):
+            return await self.reg_controller.query_worker_info(msg)
+        else:
+            logger.error(f"Unknown orchestration message type: {msg}")
+            raise RuntimeError(f"Unknown orchestration message type: {msg}")
+
+    def _setup_socket_metrics(self):
+        """Setup metrics for socket message counts."""
+        # Initialize message counters for observability
+        self.pull_socket_message_count = 0
+        self.reply_socket_message_count = 0
+
+        # Initialize active request counters
+        self.pull_socket_active_requests = 0
+        self.reply_socket_active_requests = 0
+
+        prometheus_logger = PrometheusLogger.GetInstanceOrNone()
+        if prometheus_logger is not None:
+            prometheus_logger.pull_socket_message_count.set_function(
+                lambda: self.pull_socket_message_count
+            )
+            prometheus_logger.reply_socket_message_count.set_function(
+                lambda: self.reply_socket_message_count
+            )
+
+            # Socket queue/backlog metrics
+            prometheus_logger.pull_socket_has_pending.set_function(
+                lambda: self._check_socket_has_pending(self.controller_pull_socket)
+            )
+            if self.controller_urls["reply"] is not None:
+                prometheus_logger.reply_socket_has_pending.set_function(
+                    lambda: self._check_socket_has_pending(self.controller_reply_socket)
+                )
+
+            # Active request metrics
+            prometheus_logger.pull_socket_active_requests.set_function(
+                lambda: self.pull_socket_active_requests
+            )
+            prometheus_logger.reply_socket_active_requests.set_function(
+                lambda: self.reply_socket_active_requests
+            )
+
+    def _convert_bind_to_connect_url(
+        self, bind_url: str, worker_ip: Optional[str] = None
+    ) -> str:
+        """Convert a bind address to a connectable address.
+
+        Bind addresses like "0.0.0.0:port" or "*:port" cannot be used
+        by workers to connect. We need to replace them with the actual
+        controller IP address.
+
+        If worker_ip is provided and matches the controller's IP, use
+        127.0.0.1 for loopback connection (more reliable than external IP).
+
+        Args:
+            bind_url: The bind URL (e.g., "0.0.0.0:8082" or "*:8082")
+            worker_ip: The IP address of the requesting worker (optional)
+
+        Returns:
+            A connectable URL (e.g., "192.168.1.100:8082" or "127.0.0.1:8082")
+        """
+        if ":" not in bind_url:
+            return bind_url
+
+        host, port = bind_url.rsplit(":", 1)
+        # Replace bind-all addresses with actual IP
+        if host in ("0.0.0.0", "*", ""):
+            actual_ip = get_ip()
+            # If worker is on the same machine, use loopback for reliability
+            # This handles cases where external IP (e.g., VPN) doesn't support
+            # local loopback connections
+            if worker_ip is not None and worker_ip == actual_ip:
+                logger.debug(
+                    "Worker IP %s matches controller IP, using 127.0.0.1",
+                    worker_ip,
+                )
+                return f"127.0.0.1:{port}"
+            return f"{actual_ip}:{port}"
+        return bind_url
+
+    def _check_socket_has_pending(self, socket) -> int:
+        """Check if socket has pending messages.
+
+        Returns:
+            1 if socket has pending messages, 0 otherwise
+        """
+        try:
+            events = socket.get(zmq.EVENTS)  # type: ignore[attr-defined]
+            # Check if POLLIN flag is set (indicates readable/pending messages)
+            has_pending = 1 if (events & zmq.POLLIN) else 0  # type: ignore[attr-defined]
+            return has_pending
+        except Exception as e:
+            logger.error(f"Error checking socket pending status: {e}")
+            return 0
+
+    async def handle_batched_push_request(self, socket) -> Optional[MsgBase]:
+        while True:
+            parts = await socket.recv_multipart()
+            part_count = len(parts)
+            with SocketMetricsContext(self, SocketType.PULL, part_count):
+                for part in parts:
+                    # Parse message based on format
+                    if part.startswith(b"{"):
+                        # JSON format - typically from external systems
+                        # like Mooncake
+                        msg_dict = json.loads(part)
+                        msg = msgspec.convert(msg_dict, type=Msg)
+                    else:
+                        # MessagePack format - internal LMCache communication
+                        msg = msgspec.msgpack.decode(part, type=Msg)
+                    if isinstance(msg, WorkerMsg):
+                        await self.handle_worker_message(msg)
+
+                    # FIXME(Jiayi): The abstraction of control messages
+                    # might not be necessary.
+                    # elif isinstance(msg, ControlMsg):
+                    #    await self.issue_control_message(msg)
+                    elif isinstance(msg, OrchMsg):
+                        await self.handle_orchestration_message(msg)
+                    else:
+                        logger.error(f"Unknown message type: {type(msg)}")
+
+    async def handle_batched_req_request(self, socket) -> Optional[MsgBase]:
+        """Handle requests on ROUTER socket.
+
+        ROUTER socket receives multi-part messages:
+        [identity, empty_frame, payload]
+        and must reply with the same identity frame.
+        """
+        while True:
+            frames = await socket.recv_multipart()
+            with SocketMetricsContext(self, SocketType.REPLY):
+                identity = None
+                try:
+                    # ROUTER socket: [identity, empty_frame, payload]
+                    if len(frames) < 3:
+                        logger.error(
+                            "Invalid ROUTER message format, expected >= 3 frames, "
+                            "got %d",
+                            len(frames),
+                        )
+                        continue
+                    identity = frames[0]
+                    # frames[1] is empty delimiter
+                    part = frames[2]
+
+                    # Parse message based on format
+                    if part.startswith(b"{"):
+                        # JSON format - typically from external systems like Mooncake
+                        msg_dict = json.loads(part)
+                        msg = msgspec.convert(msg_dict, type=Msg)
+                    else:
+                        # MessagePack format - internal LMCache communication
+                        msg = msgspec.msgpack.decode(part, type=Msg)
+
+                    if isinstance(msg, WorkerReqMsg):
+                        ret_msg = await self.handle_worker_req_message(msg)
+                        # Reply with identity frame for ROUTER socket
+                        await socket.send_multipart(
+                            [identity, b"", msgspec.msgpack.encode(ret_msg)]
+                        )
+                    else:
+                        logger.error("Unknown message type: %s", type(msg))
+                        err_msg = ErrorMsg(error=f"Unknown message type: {type(msg)}")
+                        await socket.send_multipart(
+                            [identity, b"", msgspec.msgpack.encode(err_msg)]
+                        )
+                except (
+                    json.JSONDecodeError,
+                    msgspec.DecodeError,
+                    msgspec.ValidationError,
+                    zmq.ZMQError,
+                ) as e:
+                    logger.error("Error handling request message: %s", e, exc_info=True)
+                    err_msg = ErrorMsg(error=str(e))
+                    # Try to reply with error if we have identity
+                    if identity is not None:
+                        await socket.send_multipart(
+                            [identity, b"", msgspec.msgpack.encode(err_msg)]
+                        )
+
+    async def handle_heartbeat_request(self, socket) -> None:
+        """Handle heartbeat requests on dedicated ROUTER socket.
+
+        This runs on a separate socket to ensure heartbeats are processed
+        without being blocked by other requests.
+
+        ROUTER socket receives multi-part messages:
+        [identity, empty_frame, payload]
+        """
+        logger.info("Heartbeat handler task started, waiting for heartbeat requests...")
+        while True:
+            frames = await socket.recv_multipart()
+            logger.debug("Received heartbeat request with %d frames", len(frames))
+            with SocketMetricsContext(self, SocketType.REPLY):
+                identity = None
+                try:
+                    # ROUTER socket: [identity, empty_frame, payload]
+                    if len(frames) < 3:
+                        logger.error(
+                            "Invalid heartbeat ROUTER message format, "
+                            "expected >= 3 frames, got %d",
+                            len(frames),
+                        )
+                        continue
+                    identity = frames[0]
+                    part = frames[2]
+
+                    if part.startswith(b"{"):
+                        msg_dict = json.loads(part)
+                        msg = msgspec.convert(msg_dict, type=Msg)
+                    else:
+                        msg = msgspec.msgpack.decode(part, type=Msg)
+
+                    if isinstance(msg, HeartbeatMsg):
+                        ret_msg = await self.reg_controller.heartbeat(msg)
+                        await socket.send_multipart(
+                            [identity, b"", msgspec.msgpack.encode(ret_msg)]
+                        )
+                    else:
+                        logger.error(
+                            "Unexpected message type on heartbeat socket: %s",
+                            type(msg),
+                        )
+                        err_msg = ErrorMsg(
+                            error=f"Expected HeartbeatMsg, got {type(msg)}"
+                        )
+                        await socket.send_multipart(
+                            [identity, b"", msgspec.msgpack.encode(err_msg)]
+                        )
+                except (
+                    json.JSONDecodeError,
+                    msgspec.DecodeError,
+                    msgspec.ValidationError,
+                    zmq.ZMQError,
+                ) as e:
+                    logger.error(
+                        "Error handling heartbeat request: %s", e, exc_info=True
+                    )
+                    err_msg = ErrorMsg(error=str(e))
+                    # Try to reply with error if we have identity
+                    if identity is not None:
+                        await socket.send_multipart(
+                            [identity, b"", msgspec.msgpack.encode(err_msg)]
+                        )
+
+    async def health_check(self):
+        while True:
+            await asyncio.sleep(self.health_check_interval)
+            worker_infos = self.reg_controller.registry.get_all_worker_infos_cached(1)
+            for worker_info in worker_infos:
+                if (
+                    time.time() - worker_info.last_heartbeat_time
+                    > self.lmcache_worker_timeout
+                ):
+                    logger.warning(
+                        "Worker %s_%s last heartbeat time: %s, "
+                        "current time: %s, more than %s seconds",
+                        worker_info.instance_id,
+                        worker_info.worker_id,
+                        worker_info.last_heartbeat_time,
+                        time.time(),
+                        self.lmcache_worker_timeout,
+                    )
+                    # Perform a full deregister to clean up all associated resources.
+                    deregister_msg = DeRegisterMsg(
+                        instance_id=worker_info.instance_id,
+                        worker_id=worker_info.worker_id,
+                        ip=worker_info.ip,
+                        port=worker_info.port,
+                    )
+                    await self.reg_controller.deregister(deregister_msg)
+
+    async def start_all(self):
+        tasks = []
+        if self.controller_urls["reply"] is not None:
+            logger.info(
+                "Starting reply request handler on %s", self.controller_urls["reply"]
+            )
+            tasks.append(self.handle_batched_req_request(self.controller_reply_socket))
+        if self.controller_heartbeat_socket is not None:
+            logger.info(
+                "Starting heartbeat request handler on %s",
+                self.controller_urls.get("heartbeat"),
+            )
+            tasks.append(
+                self.handle_heartbeat_request(self.controller_heartbeat_socket)
+            )
+        else:
+            logger.warning("Heartbeat socket is None, heartbeat handler not started!")
+        logger.info("Starting pull request handler on %s", self.controller_urls["pull"])
+        tasks.append(self.handle_batched_push_request(self.controller_pull_socket))
+        await asyncio.gather(
+            *tasks,
+            return_exceptions=True,
+        )
+
+    def close(self):
+        """Clean up all resources owned by the controller manager."""
+        if hasattr(self, "controller_pull_socket"):
+            self.controller_pull_socket.close()
+        if hasattr(self, "controller_reply_socket"):
+            self.controller_reply_socket.close()
+        if hasattr(self, "zmq_context"):
+            self.zmq_context.destroy()
diff --git a/lmcache/v1/cache_controller/controllers/__init__.py b/lmcache/v1/cache_controller/controllers/__init__.py
new file mode 100644
index 0000000..bae35a0
--- /dev/null
+++ b/lmcache/v1/cache_controller/controllers/__init__.py
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.cache_controller.controllers.kv_controller import KVController
+from lmcache.v1.cache_controller.controllers.registration_controller import (  # noqa: E501
+    RegistrationController,
+)
+
+__all__ = [
+    "KVController",
+    "RegistrationController",
+]
diff --git a/lmcache/v1/cache_controller/controllers/full_sync_tracker.py b/lmcache/v1/cache_controller/controllers/full_sync_tracker.py
new file mode 100644
index 0000000..b602d4e
--- /dev/null
+++ b/lmcache/v1/cache_controller/controllers/full_sync_tracker.py
@@ -0,0 +1,473 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Tuple
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.utils import (
+    FullSyncState,
+    RegistryTree,
+    WorkerNode,
+    WorkerSyncInfo,
+)
+
+logger = init_logger(__name__)
+
+
+class FullSyncTracker:
+    """
+    Tracks full sync state for all workers.
+
+    This class manages the state of full sync operations, including:
+    - Tracking which workers need full sync
+    - Monitoring sync progress
+    - Handling sync timeout
+    - Determining when freeze mode can be exited
+    """
+
+    def __init__(
+        self,
+        registry_tree: RegistryTree,
+        completion_threshold: float = 0.8,
+        sync_timeout_s: float = 300.0,
+    ):
+        """
+        Initialize the FullSyncTracker.
+
+        Args:
+            registry_tree: The registry tree containing worker nodes
+            completion_threshold: Percentage of workers that need to complete
+                                  sync before others can exit freeze mode (default: 80%)
+            sync_timeout_s: Timeout in seconds for a single worker's sync
+                                  (default: 300s)
+        """
+        self.registry_tree = registry_tree
+        self.completion_threshold = completion_threshold
+        self.sync_timeout_s = sync_timeout_s
+
+        # Flag to indicate if controller just restarted and needs full sync
+        self._need_full_sync_all = True
+
+    def _get_sync_info(
+        self, instance_id: str, worker_id: int
+    ) -> Optional[WorkerSyncInfo]:
+        """Get sync info for a worker from the registry tree."""
+        worker_node = self.registry_tree.get_worker(instance_id, worker_id)
+        if worker_node is None:
+            return None
+        return worker_node.sync_info
+
+    def _set_sync_info(
+        self, instance_id: str, worker_id: int, sync_info: Optional[WorkerSyncInfo]
+    ) -> bool:
+        """Set sync info for a worker. Returns True if successful."""
+        worker_node = self.registry_tree.get_worker(instance_id, worker_id)
+        if worker_node is None:
+            return False
+        worker_node.sync_info = sync_info
+        return True
+
+    def set_need_full_sync_all(self, need: bool) -> None:
+        """Set whether all workers need full sync (e.g., after controller restart)"""
+        self._need_full_sync_all = need
+        logger.info("Set need_full_sync_all to %s", need)
+
+    def _get_all_workers_cached(
+        self, timeout_seconds: Optional[float] = None
+    ) -> list[tuple[str, WorkerNode]]:
+        """Get all registered workers from the registry tree."""
+        return self.registry_tree.get_all_worker_nodes_cached(timeout_seconds)
+
+    def should_request_full_sync(
+        self, instance_id: str, worker_id: int
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Check if a worker should perform full sync.
+
+        Returns:
+            Tuple of (need_sync, reason)
+        """
+        # Case 1: Controller just restarted, all workers need sync
+        if self._need_full_sync_all:
+            sync_info = self._get_sync_info(instance_id, worker_id)
+            if sync_info is None or sync_info.state not in (
+                FullSyncState.SYNCING,
+                FullSyncState.COMPLETED,
+            ):
+                return True, "controller_restart"
+
+        # Case 2: Worker sync failed/timeout, needs retry
+        sync_info = self._get_sync_info(instance_id, worker_id)
+        if sync_info is not None and sync_info.state == FullSyncState.FAILED:
+            return True, "sync_failed_retry"
+
+        return False, None
+
+    def is_worker_syncing(self, instance_id: str, worker_id: int) -> bool:
+        """
+        Check if a worker is currently in sync state.
+
+        When a worker is syncing, incremental events should be discarded.
+        """
+        sync_info = self._get_sync_info(instance_id, worker_id)
+        if sync_info is None:
+            return False
+        return sync_info.state == FullSyncState.SYNCING
+
+    def get_sync_id(self, instance_id: str, worker_id: int) -> Optional[str]:
+        """
+        Get sync ID for a worker.
+
+        Returns sync ID if worker is syncing, None otherwise.
+        """
+        sync_info = self._get_sync_info(instance_id, worker_id)
+        if sync_info is None:
+            return None
+        return sync_info.sync_id
+
+    def start_sync(
+        self,
+        instance_id: str,
+        worker_id: int,
+        sync_id: str,
+        total_keys: int,
+        batch_count: int,
+    ) -> bool:
+        """
+        Start sync for a worker.
+
+        Returns:
+            True if sync started successfully, False otherwise
+        """
+        report_id = (instance_id, worker_id)
+        current_time = time.time()
+
+        # Check if already syncing with different sync_id
+        existing_sync = self._get_sync_info(instance_id, worker_id)
+        if existing_sync is not None and existing_sync.state == FullSyncState.SYNCING:
+            if existing_sync.sync_id != sync_id:
+                logger.warning(
+                    "Worker %s already syncing with different sync_id: "
+                    "existing=%s, new=%s",
+                    report_id,
+                    existing_sync.sync_id,
+                    sync_id,
+                )
+                return False
+
+        new_sync_info = WorkerSyncInfo(
+            sync_id=sync_id,
+            state=FullSyncState.SYNCING,
+            start_time=current_time,
+            expected_total_keys=total_keys,
+            expected_batch_count=batch_count,
+            last_activity_time=current_time,
+        )
+        if not self._set_sync_info(instance_id, worker_id, new_sync_info):
+            logger.warning(
+                "Failed to start sync for worker %s: worker not found", report_id
+            )
+            return False
+
+        logger.info(
+            "Started full sync for worker %s: sync_id=%s, "
+            "expected_keys=%d, expected_batches=%d",
+            report_id,
+            sync_id,
+            total_keys,
+            batch_count,
+        )
+        return True
+
+    def receive_batch(
+        self,
+        instance_id: str,
+        worker_id: int,
+        sync_id: str,
+        batch_id: int,
+        keys_count: int,
+    ) -> bool:
+        """
+        Record receipt of a sync batch.
+
+        Returns:
+            True if batch was recorded, False if invalid
+        """
+        report_id = (instance_id, worker_id)
+        sync_info = self._get_sync_info(instance_id, worker_id)
+
+        if sync_info is None:
+            logger.warning(
+                "Received batch for unknown sync session: worker=%s, sync_id=%s",
+                report_id,
+                sync_id,
+            )
+            return False
+
+        if sync_info.sync_id != sync_id:
+            logger.warning(
+                "Sync ID mismatch: expected=%s, received=%s",
+                sync_info.sync_id,
+                sync_id,
+            )
+            return False
+
+        if sync_info.state != FullSyncState.SYNCING:
+            logger.warning(
+                "Received batch for non-syncing worker: worker=%s, state=%s",
+                report_id,
+                sync_info.state,
+            )
+            return False
+
+        sync_info.received_batches.add(batch_id)
+        sync_info.received_keys_count += keys_count
+        sync_info.last_activity_time = time.time()
+
+        logger.debug(
+            "Received batch %d for worker %s: keys=%d, total_received=%d",
+            batch_id,
+            report_id,
+            keys_count,
+            sync_info.received_keys_count,
+        )
+        return True
+
+    def complete_sync(
+        self,
+        instance_id: str,
+        worker_id: int,
+        sync_id: str,
+        actual_total_keys: int,
+    ) -> bool:
+        """
+        Mark sync as completed for a worker.
+
+        Returns:
+            True if completion was successful, False otherwise
+        """
+        report_id = (instance_id, worker_id)
+        sync_info = self._get_sync_info(instance_id, worker_id)
+
+        if sync_info is None:
+            logger.warning(
+                "Received sync end for unknown session: worker=%s, sync_id=%s",
+                report_id,
+                sync_id,
+            )
+            return False
+
+        if sync_info.sync_id != sync_id:
+            logger.warning(
+                "Sync ID mismatch on completion: expected=%s, received=%s",
+                sync_info.sync_id,
+                sync_id,
+            )
+            return False
+
+        # Verify key count
+        if sync_info.received_keys_count != actual_total_keys:
+            logger.warning(
+                "Key count mismatch on completion: received=%d, reported=%d",
+                sync_info.received_keys_count,
+                actual_total_keys,
+            )
+            # Still mark as completed but log the discrepancy
+
+        sync_info.state = FullSyncState.COMPLETED
+        sync_info.last_activity_time = time.time()
+
+        logger.info(
+            "Completed full sync for worker %s: sync_id=%s, "
+            "received_keys=%d, batches=%d",
+            report_id,
+            sync_id,
+            sync_info.received_keys_count,
+            len(sync_info.received_batches),
+        )
+        return True
+
+    def mark_failed(self, instance_id: str, worker_id: int, reason: str) -> None:
+        """Mark a worker's sync as failed"""
+        report_id = (instance_id, worker_id)
+        sync_info = self._get_sync_info(instance_id, worker_id)
+
+        if sync_info is not None:
+            sync_info.state = FullSyncState.FAILED
+            logger.warning(
+                "Marked sync as failed for worker %s: reason=%s", report_id, reason
+            )
+
+    # Only for testing
+    def check_sync_timeout(self) -> None:
+        """
+        Check for sync timeouts and mark failed workers.
+
+        This should be called periodically (e.g., in health check loop).
+        """
+        current_time = time.time()
+        for instance_id, worker_node in self._get_all_workers_cached():
+            sync_info = worker_node.sync_info
+            if sync_info is not None and sync_info.state == FullSyncState.SYNCING:
+                if current_time - sync_info.last_activity_time > self.sync_timeout_s:
+                    self.mark_failed(
+                        instance_id,
+                        worker_node.worker_id,
+                        f"timeout after {self.sync_timeout_s}s",
+                    )
+
+    def get_global_progress(self) -> float:
+        """
+        Get the global sync progress.
+
+        Returns:
+            Progress as a float between 0.0 and 1.0
+
+        Note: Uses cached worker list for Prometheus metrics efficiency.
+
+        Progress calculation:
+        - Denominator: total number of all workers
+        - Numerator: workers that are ready to serve (COMPLETED or no sync info needed)
+        - Workers in SYNCING or FAILED state are NOT considered ready
+        """
+        all_workers = self._get_all_workers_cached()
+        if not all_workers:
+            return 0.0
+
+        total = len(all_workers)
+        ready_count = sum(
+            1
+            for _, worker_node in all_workers
+            if worker_node.sync_info is None
+            or worker_node.sync_info.state == FullSyncState.COMPLETED
+        )
+
+        # Progress = ready / total
+        return ready_count / total
+
+    def get_completed_count(self) -> int:
+        """Get count of workers that have completed sync.
+
+        Note: Uses cached worker list for Prometheus metrics efficiency.
+        """
+        return sum(
+            1
+            for _, worker_node in self._get_all_workers_cached()
+            if worker_node.sync_info is not None
+            and worker_node.sync_info.state == FullSyncState.COMPLETED
+        )
+
+    def get_syncing_count(self) -> int:
+        """Get count of workers currently syncing.
+
+        Note: Uses cached worker list for Prometheus metrics efficiency.
+        """
+        return sum(
+            1
+            for _, worker_node in self._get_all_workers_cached()
+            if worker_node.sync_info is not None
+            and worker_node.sync_info.state == FullSyncState.SYNCING
+        )
+
+    def can_exit_freeze(self, progress: Optional[float] = None) -> bool:
+        """
+        Check if the completion threshold is reached and freeze mode can be exited.
+
+        Args:
+            progress: Pre-computed global progress. If None, will be computed.
+
+        Returns:
+            True if enough workers have completed sync
+        """
+        if progress is None:
+            progress = self.get_global_progress()
+        can_exit = progress >= self.completion_threshold
+
+        if can_exit and self._need_full_sync_all:
+            # Once threshold is reached, disable the global full sync flag
+            logger.info(
+                "Full sync completion threshold reached (%.1f%%), "
+                "disabling need_full_sync_all",
+                progress * 100,
+            )
+            self._need_full_sync_all = False
+
+        return can_exit
+
+    def get_total_missing_batches_count(self) -> int:
+        """
+        Get total count of missing batches across all syncing workers.
+
+        Returns:
+            Total number of missing batches
+
+        Note: Uses cached worker list for Prometheus metrics efficiency.
+        """
+        total = 0
+        for instance_id, worker_node in self._get_all_workers_cached():
+            sync_info = worker_node.sync_info
+            if sync_info is not None and sync_info.state == FullSyncState.SYNCING:
+                expected_batches = set(range(sync_info.expected_batch_count))
+                missing = expected_batches - sync_info.received_batches
+                total += len(missing)
+        return total
+
+    def get_missing_batches(
+        self, instance_id: str, worker_id: int, sync_id: str
+    ) -> list[int]:
+        """
+        Get list of missing batch IDs that need to be resent.
+
+        Args:
+            instance_id: The instance ID
+            worker_id: The worker ID
+            sync_id: The sync session ID
+
+        Returns:
+            List of missing batch IDs, empty if sync is complete or invalid
+        """
+        sync_info = self._get_sync_info(instance_id, worker_id)
+
+        if sync_info is None:
+            return []
+
+        # Check sync_id matches
+        if sync_info.sync_id != sync_id:
+            return []
+
+        # If already completed, no missing batches
+        if sync_info.state == FullSyncState.COMPLETED:
+            return []
+
+        # If not syncing, no missing batches
+        if sync_info.state != FullSyncState.SYNCING:
+            return []
+
+        # Calculate missing batches
+        expected_batches = set(range(sync_info.expected_batch_count))
+        missing = expected_batches - sync_info.received_batches
+
+        return sorted(missing)
+
+    def get_sync_status(
+        self, instance_id: str, worker_id: int, sync_id: str
+    ) -> Tuple[bool, float, bool, list[int]]:
+        """
+        Get sync status for a specific worker.
+
+        Returns:
+            Tuple of (is_complete, global_progress, can_exit_freeze, missing_batches)
+        """
+        sync_info = self._get_sync_info(instance_id, worker_id)
+
+        is_complete = (
+            sync_info is not None
+            and sync_info.sync_id == sync_id
+            and sync_info.state == FullSyncState.COMPLETED
+        )
+        global_progress = self.get_global_progress()
+        can_exit = self.can_exit_freeze(global_progress)
+        missing_batches = self.get_missing_batches(instance_id, worker_id, sync_id)
+
+        return is_complete, global_progress, can_exit, missing_batches
diff --git a/lmcache/v1/cache_controller/controllers/kv_controller.py b/lmcache/v1/cache_controller/controllers/kv_controller.py
new file mode 100644
index 0000000..80c7f3c
--- /dev/null
+++ b/lmcache/v1/cache_controller/controllers/kv_controller.py
@@ -0,0 +1,439 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, Any
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.controllers.full_sync_tracker import FullSyncTracker
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    BatchedP2PLookupMsg,
+    BatchedP2PLookupRetMsg,
+    CheckFinishMsg,
+    CheckFinishRetMsg,
+    ClearMsg,
+    ClearRetMsg,
+    CompressMsg,
+    CompressRetMsg,
+    DecompressMsg,
+    DecompressRetMsg,
+    FullSyncBatchMsg,
+    FullSyncEndMsg,
+    FullSyncStartMsg,
+    FullSyncStartRetMsg,
+    FullSyncStatusMsg,
+    FullSyncStatusRetMsg,
+    KVOpEvent,
+    LookupMsg,
+    LookupRetMsg,
+    MoveMsg,
+    MoveRetMsg,
+    OpType,
+    PinMsg,
+    PinRetMsg,
+)
+from lmcache.v1.cache_controller.observability import PrometheusLogger
+from lmcache.v1.cache_controller.utils import RegistryTree
+from lmcache.v1.token_database import ChunkedTokenDatabase
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.controllers import RegistrationController
+
+logger = init_logger(__name__)
+
+
+"""
+The kv controller use `(instance_id, worker_id)` -> [location -> set[chunk_hash]] 
+as kv_pool. When the number of instances is small and stable, the time complexity 
+of `lookup` in kv controller is O(n). If the number of instance is large or unknown, 
+the time complexity will degrade to O(n^2), and the ReverseIndexKVController is a 
+better choice.
+"""
+
+
+class KVController:
+    def __init__(
+        self,
+        registry: RegistryTree,
+        full_sync_completion_threshold: float = 0.8,
+        full_sync_timeout_s: float = 300.0,
+    ) -> None:
+        # TODO(Jiayi): remove this hardcode
+        self.token_database = ChunkedTokenDatabase()
+        self.registry = registry
+        self.cluster_executor: Any = None
+
+        # Full sync tracker
+        self.full_sync_tracker = FullSyncTracker(
+            registry_tree=registry,
+            completion_threshold=full_sync_completion_threshold,
+            sync_timeout_s=full_sync_timeout_s,
+        )
+
+    def _setup_metrics(self) -> None:
+        prometheus_logger = PrometheusLogger.GetInstanceOrNone()
+        if prometheus_logger is not None:
+            prometheus_logger.kv_pool_keys_count.set_function(
+                self.registry.get_total_kv_count
+            )
+            prometheus_logger.kv_op_seq_discontinuity_count.set_function(
+                self.registry.get_seq_discontinuity_count
+            )
+            # Full sync metrics
+            prometheus_logger.full_sync_workers_syncing.set_function(
+                self.full_sync_tracker.get_syncing_count
+            )
+            prometheus_logger.full_sync_workers_completed.set_function(
+                self.full_sync_tracker.get_completed_count
+            )
+            prometheus_logger.full_sync_global_progress.set_function(
+                self.full_sync_tracker.get_global_progress
+            )
+            prometheus_logger.full_sync_missing_batches_total.set_function(
+                self.full_sync_tracker.get_total_missing_batches_count
+            )
+
+    def post_init(
+        self, reg_controller: "RegistrationController", cluster_executor: Any
+    ) -> None:
+        """
+        Post initialization of the KV controller.
+        """
+        self.reg_controller = reg_controller
+        self.cluster_executor = cluster_executor
+        self._setup_metrics()
+
+    async def clear(self, msg: ClearMsg) -> ClearRetMsg:
+        """
+        Clear kv chunks of instance-worker(s).
+        """
+        assert self.cluster_executor is not None
+        return await self.cluster_executor.execute("clear", msg)
+
+    async def pin(self, msg: PinMsg) -> PinRetMsg:
+        """
+        Pin kv chunks of instance-worker(s).
+        """
+        assert self.cluster_executor is not None
+        return await self.cluster_executor.execute("pin", msg)
+
+    async def compress(self, msg: CompressMsg) -> CompressRetMsg:
+        """
+        Compress kv chunks of instance-worker(s).
+        """
+        assert self.cluster_executor is not None
+        return await self.cluster_executor.execute("compress", msg)
+
+    async def decompress(self, msg: DecompressMsg) -> DecompressRetMsg:
+        """
+        Decompress kv chunks of instance-worker(s).
+        """
+        assert self.cluster_executor is not None
+        return await self.cluster_executor.execute("decompress", msg)
+
+    async def move(self, msg: MoveMsg) -> MoveRetMsg:
+        """
+        Move kv chunks of instance-worker(s).
+        """
+        assert self.cluster_executor is not None
+        return await self.cluster_executor.execute("move", msg)
+
+    async def check_finish(self, msg: CheckFinishMsg) -> CheckFinishRetMsg:
+        """
+        Check if an event is finished.
+        """
+        assert self.cluster_executor is not None
+        return await self.cluster_executor.execute("check_finish", msg)
+
+    async def handle_batched_kv_operations(self, msg: BatchedKVOperationMsg) -> None:
+        """Handle batched KV operations by forwarding to registry."""
+        if not msg.operations:
+            return
+
+        # Check if worker is currently in full sync
+        if self.full_sync_tracker.is_worker_syncing(msg.instance_id, msg.worker_id):
+            # During full sync, incremental operations should be discarded
+            logger.debug(
+                "Discarding incremental KV operations during full sync: "
+                "instance=%s, worker=%d, sync_id=%s, operation_count=%d",
+                msg.instance_id,
+                msg.worker_id,
+                self.full_sync_tracker.get_sync_id(msg.instance_id, msg.worker_id),
+                len(msg.operations),
+            )
+            return
+
+        if not self.registry.handle_batched_kv_operations(msg):
+            logger.warning(
+                "Failed to handle batched KV operations, instance: %s, worker: %d",
+                msg.instance_id,
+                msg.worker_id,
+            )
+
+    # ============= Full Sync Message Handlers =============
+
+    async def handle_full_sync_start(
+        self, msg: FullSyncStartMsg
+    ) -> FullSyncStartRetMsg:
+        """
+        Handle full sync start request from a worker.
+
+        This is called when a worker wants to start full sync.
+        The controller should:
+        1. Clear existing keys for this worker
+        2. Mark the worker as syncing (incremental events will be discarded)
+        3. Return acceptance
+        """
+        instance_id = msg.instance_id
+        worker_id = msg.worker_id
+        sync_id = msg.sync_id
+        report_id = (instance_id, worker_id)
+
+        # Start sync tracking first (mark worker as SYNCING)
+        success = self.full_sync_tracker.start_sync(
+            instance_id=instance_id,
+            worker_id=worker_id,
+            sync_id=sync_id,
+            total_keys=msg.total_keys,
+            batch_count=msg.batch_count,
+        )
+
+        if not success:
+            logger.warning(
+                "Failed to start sync for worker %s: sync_id=%s", report_id, sync_id
+            )
+            return FullSyncStartRetMsg(
+                sync_id=sync_id,
+                accepted=False,
+                error_msg="Failed to start sync: worker already syncing with "
+                "different sync_id or worker not found",
+            )
+
+        # Now clear existing keys for this worker/location using efficient batch method
+        # This prevents new incremental messages from being processed while we clear
+        existing_keys = self.registry.get_worker_kv_keys(
+            instance_id, worker_id, msg.location
+        )
+        if existing_keys:
+            old_count = len(existing_keys)
+            # Use efficient batch clear method
+            cleared = self.registry.clear_worker_kv(
+                instance_id, worker_id, msg.location
+            )
+            if cleared:
+                logger.info(
+                    "Cleared %d existing keys for worker %s location %s "
+                    "before full sync",
+                    old_count,
+                    report_id,
+                    msg.location,
+                )
+            else:
+                logger.warning(
+                    "Failed to clear keys for worker %s location %s",
+                    report_id,
+                    msg.location,
+                )
+
+        logger.info(
+            "Accepted full sync start: worker=%s, sync_id=%s, "
+            "total_keys=%d, batch_count=%d",
+            report_id,
+            sync_id,
+            msg.total_keys,
+            msg.batch_count,
+        )
+        return FullSyncStartRetMsg(sync_id=sync_id, accepted=True)
+
+    async def handle_full_sync_batch(self, msg: FullSyncBatchMsg) -> None:
+        """
+        Handle full sync batch message from a worker.
+
+        This adds the keys from the batch to the registry.
+        """
+        instance_id = msg.instance_id
+        worker_id = msg.worker_id
+        location = msg.location
+        sync_id = msg.sync_id
+        batch_id = msg.batch_id
+        keys = msg.keys
+        report_id = (instance_id, worker_id)
+
+        # Record batch receipt
+        if not self.full_sync_tracker.receive_batch(
+            instance_id=instance_id,
+            worker_id=worker_id,
+            sync_id=sync_id,
+            batch_id=batch_id,
+            keys_count=len(keys),
+        ):
+            logger.warning(
+                "Failed to record batch %d for worker %s", batch_id, report_id
+            )
+            return
+
+        # Add keys to registry using batched operations
+        operations = []
+        for seq_num, key in enumerate(keys):
+            operations.append(
+                KVOpEvent(
+                    op_type=OpType.ADMIT,
+                    key=key,
+                    seq_num=seq_num,
+                )
+            )
+        if operations:
+            batch_msg = BatchedKVOperationMsg(
+                instance_id=instance_id,
+                worker_id=worker_id,
+                location=location,
+                operations=operations,
+            )
+            self.registry.handle_batched_kv_operations(batch_msg, is_full_sync=True)
+
+        current_keys = self.registry.get_worker_kv_keys(
+            instance_id, worker_id, location
+        )
+        logger.debug(
+            "Added %d keys from batch %d for worker %s, total now: %d",
+            len(keys),
+            batch_id,
+            report_id,
+            len(current_keys),
+        )
+
+    async def handle_full_sync_end(self, msg: FullSyncEndMsg) -> None:
+        """
+        Handle full sync end message from a worker.
+
+        This marks the sync as end-received and records actual total keys.
+        """
+        instance_id = msg.instance_id
+        worker_id = msg.worker_id
+        sync_id = msg.sync_id
+        actual_total_keys = msg.actual_total_keys
+        report_id = (instance_id, worker_id)
+
+        success = self.full_sync_tracker.complete_sync(
+            instance_id=instance_id,
+            worker_id=worker_id,
+            sync_id=sync_id,
+            actual_total_keys=actual_total_keys,
+        )
+
+        if success:
+            # Verify registry has the expected number of keys
+            actual_keys_in_pool = len(
+                self.registry.get_worker_kv_keys(instance_id, worker_id, msg.location)
+            )
+            logger.info(
+                "Full sync completed for worker %s: sync_id=%s, "
+                "reported_keys=%d, keys_in_pool=%d",
+                report_id,
+                sync_id,
+                actual_total_keys,
+                actual_keys_in_pool,
+            )
+        else:
+            logger.warning(
+                "Failed to complete full sync for worker %s: sync_id=%s",
+                report_id,
+                sync_id,
+            )
+
+    async def handle_full_sync_status(
+        self, msg: FullSyncStatusMsg
+    ) -> FullSyncStatusRetMsg:
+        """
+        Handle full sync status query from a worker.
+
+        Returns the sync status including any missing batches that need resending.
+        """
+        is_complete, global_progress, can_exit_freeze, missing_batches = (
+            self.full_sync_tracker.get_sync_status(
+                instance_id=msg.instance_id,
+                worker_id=msg.worker_id,
+                sync_id=msg.sync_id,
+            )
+        )
+
+        if missing_batches:
+            logger.info(
+                "Full sync status query: worker=(%s, %d), sync_id=%s, "
+                "is_complete=%s, missing_batches=%s",
+                msg.instance_id,
+                msg.worker_id,
+                msg.sync_id,
+                is_complete,
+                missing_batches,
+            )
+
+        return FullSyncStatusRetMsg(
+            sync_id=msg.sync_id,
+            is_complete=is_complete,
+            global_progress=global_progress,
+            can_exit_freeze=can_exit_freeze,
+            missing_batches=missing_batches,
+        )
+
+    # TODO(Jiayi): The current implementation does not handle
+    # the case where the prefix chunks are evicted while the
+    # suffix chunk is still in the system. LMCache should guarantee
+    # this does not happen.
+    # TODO(Jiayi): The current implementation does not consider
+    # the location of the kv chunks. It simply returns the
+    # `instance_id` with longest prefix.
+    # TODO(Jiayi): Need to get rid of the hash somehow
+    async def lookup(self, msg: LookupMsg) -> LookupRetMsg:
+        tokens = msg.tokens
+        layout_info = {}
+        for start, end, key in self.token_database.process_tokens(
+            tokens, make_key=False
+        ):
+            result = self.registry.find_kv(key)
+            if result is None:
+                break
+            matched_instance = result.instance_id
+            matched_location = result.location
+            layout_info[matched_instance] = (matched_location, end)
+        return LookupRetMsg(layout_info=layout_info, event_id=msg.event_id)
+
+    # TODO: improve the matching logic, return multi results
+    async def batched_p2p_lookup(
+        self, msg: BatchedP2PLookupMsg
+    ) -> BatchedP2PLookupRetMsg:
+        """
+        Perform batched P2P lookup for multiple keys.
+
+        :param BatchedP2PLookupMsg msg: The batched P2P lookup message containing keys.
+
+        :return: A BatchedP2PLookupRetMsg containing the lookup results.
+        """
+        hashes = msg.hashes
+        if not hashes:
+            return BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+
+        # Single lookup to get all needed info (optimized path)
+        result = self.registry.find_kv_with_worker_info(
+            hashes[0], exclude_instance_id=msg.instance_id
+        )
+        if result is None:
+            return BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+
+        kv_info, peer_init_url, current_keys = result
+        if peer_init_url is None:
+            return BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+
+        # Count hits efficiently
+        num_hit_chunks = 0
+        for key in hashes:
+            if key not in current_keys:
+                break
+            num_hit_chunks += 1
+
+        return BatchedP2PLookupRetMsg(
+            layout_info=[
+                (kv_info.instance_id, kv_info.location, num_hit_chunks, peer_init_url),
+            ]
+        )
diff --git a/lmcache/v1/cache_controller/controllers/registration_controller.py b/lmcache/v1/cache_controller/controllers/registration_controller.py
new file mode 100644
index 0000000..b4970b6
--- /dev/null
+++ b/lmcache/v1/cache_controller/controllers/registration_controller.py
@@ -0,0 +1,282 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+import time
+
+# Third Party
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.commands import FullSyncCommand, HeartbeatCommand
+from lmcache.v1.cache_controller.message import (
+    DeRegisterMsg,
+    HealthMsg,
+    HealthRetMsg,
+    HeartbeatMsg,
+    HeartbeatRetMsg,
+    QueryInstMsg,
+    QueryInstRetMsg,
+    QueryWorkerInfoMsg,
+    QueryWorkerInfoRetMsg,
+    RegisterMsg,
+    RegisterRetMsg,
+)
+from lmcache.v1.cache_controller.observability import PrometheusLogger
+from lmcache.v1.cache_controller.utils import RegistryTree
+from lmcache.v1.rpc_utils import (
+    close_zmq_socket,
+    get_zmq_context,
+    get_zmq_socket,
+)
+
+logger = init_logger(__name__)
+
+
+class RegistrationController:
+    def __init__(self):
+        # Central registry tree managing all instances and workers
+        self.registry = RegistryTree()
+        self._setup_metrics()
+
+    def _setup_metrics(self):
+        prometheus_logger = PrometheusLogger.GetInstanceOrNone()
+        if prometheus_logger is not None:
+            prometheus_logger.registered_workers_count.set_function(
+                lambda: len(self.registry.get_all_worker_infos_cached())
+            )
+
+    def post_init(self, kv_controller, cluster_executor):
+        """
+        Post initialization of the Registration Controller.
+        """
+        self.kv_controller = kv_controller
+        self.cluster_executor = cluster_executor
+
+    def get_socket(
+        self, instance_id: str, worker_id: int
+    ) -> Optional[zmq.asyncio.Socket]:
+        """
+        Get the socket for a given instance and worker ID.
+        """
+        worker_node = self.registry.get_worker(instance_id, worker_id)
+        if worker_node is None:
+            logger.warning(
+                "Instance-worker %s not registered", (instance_id, worker_id)
+            )
+            return None
+        return worker_node.socket
+
+    def get_peer_init_url(self, instance_id: str, worker_id: int) -> Optional[str]:
+        """
+        Get the URL for a given instance and worker ID.
+        """
+        worker_node = self.registry.get_worker(instance_id, worker_id)
+        if worker_node is None:
+            logger.warning(
+                "Instance-worker %s not registered or P2P is not used",
+                (instance_id, worker_id),
+            )
+            return None
+        return worker_node.peer_init_url
+
+    def get_workers(self, instance_id: str) -> list[int]:
+        """
+        Get worker ids given an instance id.
+        """
+        return self.registry.get_worker_ids(instance_id)
+
+    async def get_instance_id(self, msg: QueryInstMsg) -> QueryInstRetMsg:
+        """
+        Get the instance id given an ip address.
+        """
+        ip = msg.ip
+        event_id = msg.event_id
+        instance_node = self.registry.get_instance_by_ip(ip)
+        if instance_node is None:
+            logger.warning("Instance not registered for IP %s", ip)
+            return QueryInstRetMsg(instance_id=None, event_id=event_id)
+        return QueryInstRetMsg(instance_id=instance_node.instance_id, event_id=event_id)
+
+    async def register(
+        self, msg: RegisterMsg, extra_config: Optional[dict[str, str]] = None
+    ) -> RegisterRetMsg:
+        """
+        Register a new instance-worker connection mapping.
+
+        Args:
+            msg: RegisterMsg from worker
+            extra_config: Optional extra configuration to return to worker,
+                          e.g., {"heartbeat_url": "tcp://...:8082"}
+
+        Returns:
+            RegisterRetMsg with extra_config for worker initialization
+        """
+        instance_id = msg.instance_id
+        worker_id = msg.worker_id
+        ip = msg.ip
+        port = msg.port
+        url = f"{ip}:{port}"
+
+        # prevent duplicate registration
+        existing_worker = self.registry.get_worker(instance_id, worker_id)
+        if existing_worker is not None:
+            logger.warning(
+                "Instance-worker %s already registered, skip registration",
+                (instance_id, worker_id),
+            )
+            self.registry.clear_worker_kv(instance_id, worker_id)
+            return (
+                RegisterRetMsg()
+                if extra_config is None
+                else RegisterRetMsg(extra_config=extra_config)
+            )
+
+        peer_init_url = msg.peer_init_url
+        if peer_init_url is None:
+            logger.info(
+                "peer init url of %s is None, only register when p2p is used.",
+                (instance_id, worker_id),
+            )
+
+        context = get_zmq_context()
+        socket = get_zmq_socket(
+            context,
+            url,
+            protocol="tcp",
+            role=zmq.REQ,  # type: ignore[attr-defined]
+            bind_or_connect="connect",
+        )
+
+        # Register worker in the tree
+        self.registry.register_worker(
+            instance_id=instance_id,
+            worker_id=worker_id,
+            ip=ip,
+            port=port,
+            peer_init_url=peer_init_url,
+            socket=socket,
+            registration_time=time.time(),
+        )
+
+        logger.info(
+            "Registered instance-worker %s with URL %s", (instance_id, worker_id), url
+        )
+        return (
+            RegisterRetMsg()
+            if extra_config is None
+            else RegisterRetMsg(extra_config=extra_config)
+        )
+
+    async def deregister(self, msg: DeRegisterMsg) -> None:
+        """
+        Deregister an instance-worker connection mapping.
+        """
+        instance_id = msg.instance_id
+        worker_id = msg.worker_id
+
+        worker_node = self.registry.deregister_worker(instance_id, worker_id)
+        if worker_node is None:
+            logger.warning(
+                "Instance-worker %s not registered", (instance_id, worker_id)
+            )
+            return
+
+        # Close socket
+        if worker_node.socket is not None:
+            close_zmq_socket(worker_node.socket)
+
+        logger.info("Deregistered instance-worker %s", (instance_id, worker_id))
+
+    async def health(self, msg: HealthMsg) -> HealthRetMsg:
+        """
+        Check the health of the lmcache worker.
+        """
+        return await self.cluster_executor.execute(
+            "health",
+            msg,
+        )
+
+    async def heartbeat(self, msg: HeartbeatMsg) -> HeartbeatRetMsg:
+        """
+        Heartbeat from lmcache worker (REQ-REP mode).
+
+        Returns HeartbeatRetMsg with optional commands for the worker to execute.
+        Commands are executed sequentially by the worker.
+        """
+        instance_id = msg.instance_id
+        worker_id = msg.worker_id
+        success = self.registry.update_heartbeat(instance_id, worker_id, time.time())
+
+        commands: list[HeartbeatCommand] = []
+
+        if not success:
+            logger.warning(
+                "%s has not been registered, re-register the worker.",
+                (instance_id, worker_id),
+            )
+            # re-register the worker
+            register_msg = RegisterMsg(
+                instance_id=msg.instance_id,
+                worker_id=msg.worker_id,
+                ip=msg.ip,
+                port=msg.port,
+                peer_init_url=msg.peer_init_url,
+            )
+            await self.register(register_msg)
+            # New worker needs full sync
+            commands.append(FullSyncCommand(reason="worker_re_registered"))
+        else:
+            # Check if full sync is needed (e.g., controller restart)
+            if self.kv_controller is not None and hasattr(
+                self.kv_controller, "full_sync_tracker"
+            ):
+                should_sync, reason = (
+                    self.kv_controller.full_sync_tracker.should_request_full_sync(
+                        instance_id, worker_id
+                    )
+                )
+                if should_sync:
+                    commands.append(FullSyncCommand(reason=reason))
+
+        return HeartbeatRetMsg(commands=commands)
+
+    async def query_worker_info(self, msg: QueryWorkerInfoMsg) -> QueryWorkerInfoRetMsg:
+        """
+        Query worker info.
+        """
+        event_id = msg.event_id
+        worker_infos = []
+
+        # Handle special case: instance_id = "all"
+        if msg.instance_id == "all":
+            # Get all worker infos from the registry
+            worker_infos = self.registry.get_all_worker_infos_cached()
+            # If specific worker_ids are requested, filter the results
+            if msg.worker_ids is not None and len(msg.worker_ids) > 0:
+                worker_infos = [
+                    worker_info
+                    for worker_info in worker_infos
+                    if worker_info.worker_id in msg.worker_ids
+                ]
+            return QueryWorkerInfoRetMsg(event_id=event_id, worker_infos=worker_infos)
+
+        # Normal case: query specific instance
+        instance_node = self.registry.get_instance(msg.instance_id)
+        if instance_node is None:
+            logger.warning("instance %s not registered.", msg.instance_id)
+        else:
+            worker_ids = msg.worker_ids
+            if worker_ids is None or len(worker_ids) == 0:
+                worker_ids = instance_node.get_worker_ids()
+            for worker_id in worker_ids:
+                worker_node = instance_node.get_worker(worker_id)
+                if worker_node is not None:
+                    worker_infos.append(worker_node.to_worker_info(msg.instance_id))
+                else:
+                    logger.warning(
+                        "worker %s not registered.", (msg.instance_id, worker_id)
+                    )
+
+        return QueryWorkerInfoRetMsg(event_id=event_id, worker_infos=worker_infos)
diff --git a/lmcache/v1/cache_controller/executor.py b/lmcache/v1/cache_controller/executor.py
new file mode 100644
index 0000000..a78d197
--- /dev/null
+++ b/lmcache/v1/cache_controller/executor.py
@@ -0,0 +1,463 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Union
+import asyncio
+import uuid
+
+# Third Party
+import msgspec
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.message import (  # noqa: E501
+    CheckFinishMsg,
+    CheckFinishRetMsg,
+    ClearMsg,
+    ClearRetMsg,
+    ClearWorkerMsg,
+    CompressMsg,
+    CompressRetMsg,
+    CompressWorkerMsg,
+    DecompressMsg,
+    DecompressRetMsg,
+    DecompressWorkerMsg,
+    ErrorMsg,
+    HealthMsg,
+    HealthRetMsg,
+    HealthWorkerMsg,
+    HealthWorkerRetMsg,
+    MoveMsg,
+    MoveRetMsg,
+    MoveWorkerMsg,
+    Msg,
+    MsgBase,
+    PinMsg,
+    PinRetMsg,
+    PinWorkerMsg,
+)
+
+logger = init_logger(__name__)
+
+
+# NOTE (Jiayi): `LMCacheClusterExecutor` might need to be in different processes
+# in the future for the sake of performance.
+# NOTE (Jiayi): Also, consider scaling up the number of cluster executors
+# in the future.
+# TODO (Jiayi): need better error handling
+class LMCacheClusterExecutor:
+    """
+    LMCache Cluster Executor class to handle the execution of cache operations.
+    """
+
+    def __init__(self, reg_controller):
+        """
+        Initialize the LMCache Executor with a cache instance.
+
+        :param lmcache_instance_id: lmcache_instance_id
+        """
+        self.reg_controller = reg_controller
+
+    async def clear(self, msg: ClearMsg) -> Union[ClearRetMsg, ErrorMsg]:
+        """
+        Execute a clear cache operation with error handling.
+        """
+        instance_id = msg.instance_id
+        location = msg.location
+
+        worker_ids = self.reg_controller.get_workers(instance_id)
+        assert worker_ids is not None
+        sockets = []
+        serialized_msgs = []
+        for worker_id in worker_ids:
+            socket = self.reg_controller.get_socket(instance_id, worker_id)
+            if socket is None:
+                return ErrorMsg(
+                    error=(
+                        f"Worker {worker_id} not registered for instance {instance_id}"
+                    )
+                )
+            sockets.append(socket)
+
+            # TODO(Jiayi): Need a way to track event_id -> worker_event_id mapping
+            # Also, we need to track worker_event_id status
+            worker_event_id = f"Worker{worker_id}{msg.event_id}"
+            serialized_msg = msgspec.msgpack.encode(
+                ClearWorkerMsg(
+                    worker_event_id=worker_event_id,
+                    location=location,
+                )
+            )
+            serialized_msgs.append(serialized_msg)
+        serialized_results = await self.execute_workers(
+            sockets=sockets,
+            serialized_msgs=serialized_msgs,
+        )
+
+        num_tokens_list = []
+        for i, serialized_result in enumerate(serialized_results):
+            result = msgspec.msgpack.decode(serialized_result, type=Msg)
+            num_tokens_list.append(result.num_tokens)
+
+        # TODO(Jiayi): Need to ensure cache consistency across workers.
+        assert len(set(num_tokens_list)) == 1, (
+            "The number of tokens cleared should be the same across all workers."
+        )
+
+        return ClearRetMsg(event_id=msg.event_id, num_tokens=num_tokens_list[0])
+
+    async def pin(self, msg: PinMsg) -> Union[PinRetMsg, ErrorMsg]:
+        """
+        Execute a pin cache operation with error handling.
+        """
+        instance_id = msg.instance_id
+        tokens = msg.tokens
+        location = msg.location
+
+        worker_ids = self.reg_controller.get_workers(instance_id)
+        assert worker_ids is not None
+        sockets = []
+        serialized_msgs = []
+        for worker_id in worker_ids:
+            socket = self.reg_controller.get_socket(instance_id, worker_id)
+            if socket is None:
+                return ErrorMsg(
+                    error=(
+                        f"Worker {worker_id} not registered for instance {instance_id}"
+                    )
+                )
+            sockets.append(socket)
+
+            # TODO(Jiayi): Need a way to track event_id -> worker_event_id mapping
+            # Also, we need to track worker_event_id status
+            worker_event_id = f"Worker{worker_id}{msg.event_id}"
+            serialized_msg = msgspec.msgpack.encode(
+                PinWorkerMsg(
+                    worker_event_id=worker_event_id,
+                    tokens=tokens,
+                    location=location,
+                )
+            )
+            serialized_msgs.append(serialized_msg)
+        serialized_results = await self.execute_workers(
+            sockets=sockets,
+            serialized_msgs=serialized_msgs,
+        )
+
+        num_tokens_list = []
+        for i, serialized_result in enumerate(serialized_results):
+            result = msgspec.msgpack.decode(serialized_result, type=Msg)
+            num_tokens_list.append(result.num_tokens)
+
+        # TODO(Jiayi): Need to ensure cache consistency across workers.
+        assert len(set(num_tokens_list)) == 1, (
+            "The number of tokens pinned should be the same across all workers."
+        )
+
+        return PinRetMsg(event_id=msg.event_id, num_tokens=num_tokens_list[0])
+
+    async def compress(self, msg: CompressMsg) -> Union[CompressRetMsg, ErrorMsg]:
+        """
+        Execute a compress operation with error handling.
+        """
+        event_id = msg.event_id
+        instance_id = msg.instance_id
+        method = msg.method
+        location = msg.location
+        tokens = msg.tokens
+
+        worker_ids = self.reg_controller.get_workers(instance_id)
+        assert worker_ids is not None
+
+        # TODO(Jiayi): Currently, we do not support PP or heterogeneous TP.
+        # NOTE(Jiayi): The TP ranks are already sorted in registration_controller.
+
+        sockets = []
+        serialized_msgs = []
+        for worker_id in worker_ids:
+            socket = self.reg_controller.get_socket(instance_id, worker_id)
+
+            if socket is None:
+                return ErrorMsg(
+                    error=(
+                        f"Worker {worker_id} not registered for "
+                        f"instance {instance_id} or "
+                    )
+                )
+            sockets.append(socket)
+
+            worker_event_id = f"CompressWorker{worker_id}{str(uuid.uuid4())}"
+            serialized_msg = msgspec.msgpack.encode(
+                CompressWorkerMsg(
+                    worker_event_id=worker_event_id,
+                    method=method,
+                    location=location,
+                    tokens=tokens,
+                )
+            )
+            serialized_msgs.append(serialized_msg)
+            logger.debug(
+                f"Sending compress operation to worker ({instance_id}, {worker_id})"
+            )
+        serialized_results = await self.execute_workers(
+            sockets=sockets,
+            serialized_msgs=serialized_msgs,
+        )
+
+        num_tokens_list = []
+        for serialized_result in serialized_results:
+            result = msgspec.msgpack.decode(serialized_result, type=Msg)
+            num_tokens_list.append(result.num_tokens)
+
+        # TODO(Jiayi): Need to ensure cache consistency across workers.
+        assert len(set(num_tokens_list)) == 1, (
+            "The number of tokens compressed should be the same across all workers."
+        )
+
+        return CompressRetMsg(
+            event_id=event_id,
+            num_tokens=num_tokens_list[0],
+        )
+
+    async def decompress(self, msg: DecompressMsg) -> Union[DecompressRetMsg, ErrorMsg]:
+        """
+        Execute a decompress operation with error handling.
+        """
+        event_id = msg.event_id
+        instance_id = msg.instance_id
+        method = msg.method
+        location = msg.location
+        tokens = msg.tokens
+
+        worker_ids = self.reg_controller.get_workers(instance_id)
+        assert worker_ids is not None
+
+        sockets = []
+        serialized_msgs = []
+        for worker_id in worker_ids:
+            socket = self.reg_controller.get_socket(instance_id, worker_id)
+
+            if socket is None:
+                return ErrorMsg(
+                    error=(
+                        f"Worker {worker_id} not registered for "
+                        f"instance {instance_id} or "
+                    )
+                )
+            sockets.append(socket)
+
+            worker_event_id = f"DecompressWorker{worker_id}{str(uuid.uuid4())}"
+            serialized_msg = msgspec.msgpack.encode(
+                DecompressWorkerMsg(
+                    worker_event_id=worker_event_id,
+                    method=method,
+                    location=location,
+                    tokens=tokens,
+                )
+            )
+            serialized_msgs.append(serialized_msg)
+            logger.debug(
+                f"Sending decompress operation to worker ({instance_id}, {worker_id})"
+            )
+        serialized_results = await self.execute_workers(
+            sockets=sockets,
+            serialized_msgs=serialized_msgs,
+        )
+
+        num_tokens_list = []
+        for serialized_result in serialized_results:
+            result = msgspec.msgpack.decode(serialized_result, type=Msg)
+            num_tokens_list.append(result.num_tokens)
+
+        assert len(set(num_tokens_list)) == 1, (
+            "The number of tokens decompressed should be the same across all workers."
+        )
+
+        return DecompressRetMsg(
+            event_id=event_id,
+            num_tokens=num_tokens_list[0],
+        )
+
+    async def move(self, msg: MoveMsg) -> Union[MoveRetMsg, ErrorMsg]:
+        """
+        Execute a move cache operation with error handling.
+        """
+        # NOTE(Jiayi): Currently we assume the transfer is push-based.
+        src_instance_id = msg.old_position[0]
+        dst_instance_id = msg.new_position[0]
+
+        src_worker_ids = self.reg_controller.get_workers(src_instance_id)
+        assert src_worker_ids is not None
+        dst_worker_ids = self.reg_controller.get_workers(dst_instance_id)
+        assert dst_worker_ids is not None
+
+        # TODO(Jiayi): Currently, we do not support PP or heterogeneous TP.
+        # NOTE(Jiayi): The TP ranks are already sorted in registration_controller.
+
+        sockets = []
+        serialized_msgs = []
+        for src_worker_id, dst_worker_id in zip(
+            src_worker_ids, dst_worker_ids, strict=False
+        ):
+            socket = self.reg_controller.get_socket(src_instance_id, src_worker_id)
+            dst_url = self.reg_controller.get_peer_init_url(
+                dst_instance_id, dst_worker_id
+            )
+
+            if socket is None or dst_url is None:
+                return ErrorMsg(
+                    error=(
+                        f"Src worker {src_worker_id} not registered for "
+                        f"instance {src_instance_id} or "
+                        f"dst worker {dst_worker_id} not registered for "
+                        f"instance {dst_instance_id} or P2P is not enabled."
+                    )
+                )
+            sockets.append(socket)
+
+            worker_event_id = f"MoveWorker{src_worker_id}{str(uuid.uuid4())}"
+            serialized_msg = msgspec.msgpack.encode(
+                MoveWorkerMsg(
+                    worker_event_id=worker_event_id,
+                    old_position=msg.old_position[1],
+                    new_position=(dst_url, msg.new_position[1]),
+                    tokens=msg.tokens,
+                    copy=msg.copy,
+                )
+            )
+            serialized_msgs.append(serialized_msg)
+            logger.debug(
+                f"Sending move operation to worker ({src_instance_id}, {src_worker_id})"
+            )
+        serialized_results = await self.execute_workers(
+            sockets=sockets,
+            serialized_msgs=serialized_msgs,
+        )
+
+        num_tokens_list = []
+        for serialized_result in serialized_results:
+            result = msgspec.msgpack.decode(serialized_result, type=Msg)
+            num_tokens_list.append(result.num_tokens)
+
+        # TODO(Jiayi): Need to ensure cache consistency across workers.
+        assert len(set(num_tokens_list)) == 1, (
+            "The number of tokens moved should be the same across all workers."
+        )
+
+        return MoveRetMsg(
+            event_id=msg.event_id,
+            num_tokens=num_tokens_list[0],
+        )
+
+    async def health(self, msg: HealthMsg) -> Union[HealthRetMsg, ErrorMsg]:
+        """
+        Execute a compress operation with error handling.
+        """
+        instance_id = msg.instance_id
+
+        worker_ids = self.reg_controller.get_workers(instance_id)
+        if worker_ids is None:
+            return ErrorMsg(error=f"No workers found for instance {instance_id}")
+
+        # TODO(Jiayi): Currently, we do not support PP or heterogeneous TP.
+        # NOTE(Jiayi): The TP ranks are already sorted in registration_controller.
+
+        sockets = []
+        serialized_msgs = []
+        for worker_id in worker_ids:
+            socket = self.reg_controller.get_socket(instance_id, worker_id)
+
+            if socket is None:
+                return ErrorMsg(
+                    error=(
+                        f"Worker {worker_id} not registered for "
+                        f"instance {instance_id} or socket not found"
+                    )
+                )
+            sockets.append(socket)
+
+            worker_event_id = f"HealthWorker{worker_id}{str(uuid.uuid4())}"
+            serialized_msg = msgspec.msgpack.encode(
+                HealthWorkerMsg(
+                    worker_event_id=worker_event_id,
+                )
+            )
+            serialized_msgs.append(serialized_msg)
+            logger.debug(
+                f"Sending health check operation to worker ({instance_id}, {worker_id})"
+            )
+
+        # Collect results from all workers
+        serialized_results = await self.execute_workers(
+            sockets=sockets,
+            serialized_msgs=serialized_msgs,
+        )
+
+        # Process results
+        error_codes = {}
+        for i, serialized_result in enumerate(serialized_results):
+            try:
+                result = msgspec.msgpack.decode(serialized_result, type=Msg)
+                if isinstance(result, HealthWorkerRetMsg):
+                    error_codes[worker_ids[i]] = result.error_code
+                elif isinstance(result, ErrorMsg):
+                    error_codes[worker_ids[i]] = -1001  # Worker returned error
+                else:
+                    error_codes[worker_ids[i]] = -1002  # Unexpected response
+            except Exception as e:
+                logger.error(
+                    f"Failed to parse health response from worker "
+                    f"{worker_ids[i]}: {str(e)}"
+                )
+                error_codes[worker_ids[i]] = -1003  # Failed to parse response
+
+        return HealthRetMsg(
+            event_id=msg.event_id,
+            error_codes=error_codes,
+        )
+
+    async def check_finish(
+        self, msg: CheckFinishMsg
+    ) -> Union[CheckFinishRetMsg, ErrorMsg]:
+        raise NotImplementedError
+
+    # TODO(Jiayi): need to make the types more specific
+    async def execute(self, operation: str, msg: MsgBase) -> MsgBase:
+        """
+        Execute a cache operation with error handling.
+
+        :param operation: The operation to execute
+        (e.g., 'clear').
+        :param msg: The message containing the operation details.
+        :return: The result of the operation or an error message.
+        """
+        try:
+            method = getattr(self, operation)
+            return await method(msg)
+        except AttributeError:
+            return ErrorMsg(error=f"Operation '{operation}' is not supported.")
+        except Exception as e:
+            return ErrorMsg(error=str(e))
+
+    async def execute_workers(
+        self,
+        sockets: list[zmq.asyncio.Socket],
+        serialized_msgs: list[bytes],
+    ) -> list[bytes]:
+        """
+        Execute a list of serialized messages on the given sockets.
+        :param sockets: The list of sockets to send the messages to.
+        :param serialized_msgs: The list of serialized messages to send.
+        :return: A list of serialized results received from the sockets.
+        """
+        tasks = []
+        for socket, serialized_msg in zip(sockets, serialized_msgs, strict=False):
+
+            async def send_and_receive(s, msg):
+                await s.send(msg)
+                return await s.recv()
+
+            tasks.append(send_and_receive(socket, serialized_msg))
+
+        serialized_results = await asyncio.gather(*tasks)
+        return serialized_results
diff --git a/lmcache/v1/cache_controller/frontend/static/css/style.css b/lmcache/v1/cache_controller/frontend/static/css/style.css
new file mode 100644
index 0000000..c830697
--- /dev/null
+++ b/lmcache/v1/cache_controller/frontend/static/css/style.css
@@ -0,0 +1,201 @@
+/* Controller Dashboard Styles */
+body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background-color: #f8f9fa;
+}
+
+.container-fluid {
+    max-width: 1400px;
+    margin: 0 auto;
+}
+
+header {
+    border-radius: 0.5rem;
+    margin-bottom: 1rem;
+}
+
+.nav-tabs {
+    border-bottom: 2px solid #dee2e6;
+}
+
+.nav-tabs .nav-link {
+    border: none;
+    color: #495057;
+    font-weight: 500;
+    padding: 0.75rem 1.5rem;
+}
+
+.nav-tabs .nav-link:hover {
+    border: none;
+    color: #0d6efd;
+}
+
+.nav-tabs .nav-link.active {
+    color: #0d6efd;
+    border-bottom: 3px solid #0d6efd;
+    background-color: transparent;
+}
+
+.tab-content {
+    background-color: white;
+    border-radius: 0 0 0.5rem 0.5rem;
+    box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
+}
+
+.card {
+    border: 1px solid rgba(0, 0, 0, 0.125);
+    border-radius: 0.5rem;
+    box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075);
+}
+
+.card-title {
+    color: #495057;
+    font-weight: 600;
+    margin-bottom: 1rem;
+}
+
+.table-responsive {
+    margin-top: 1rem;
+}
+
+.table {
+    margin-bottom: 0;
+}
+
+.table thead th {
+    background-color: #f8f9fa;
+    border-bottom: 2px solid #dee2e6;
+    font-weight: 600;
+    color: #495057;
+}
+
+.table tbody tr:hover {
+    background-color: #f8f9fa;
+}
+
+.btn {
+    border-radius: 0.375rem;
+    font-weight: 500;
+}
+
+.btn-primary {
+    background-color: #0d6efd;
+    border-color: #0d6efd;
+}
+
+.btn-primary:hover {
+    background-color: #0b5ed7;
+    border-color: #0a58ca;
+}
+
+.btn-outline-primary {
+    color: #0d6efd;
+    border-color: #0d6efd;
+}
+
+.btn-outline-primary:hover {
+    background-color: #0d6efd;
+    border-color: #0d6efd;
+}
+
+.form-control, .form-select {
+    border-radius: 0.375rem;
+    border: 1px solid #ced4da;
+}
+
+.form-control:focus, .form-select:focus {
+    border-color: #86b7fe;
+    box-shadow: 0 0 0 0.25rem rgba(13, 110, 253, 0.25);
+}
+
+pre {
+    background-color: #f8f9fa;
+    border: 1px solid #dee2e6;
+    border-radius: 0.375rem;
+    padding: 1rem;
+    white-space: pre-wrap;
+    word-wrap: break-word;
+    font-family: 'Courier New', Courier, monospace;
+    font-size: 0.875rem;
+}
+
+.badge {
+    font-weight: 500;
+    padding: 0.35em 0.65em;
+}
+
+.badge.bg-success {
+    background-color: #198754 !important;
+}
+
+.badge.bg-warning {
+    background-color: #ffc107 !important;
+}
+
+.badge.bg-danger {
+    background-color: #dc3545 !important;
+}
+
+.badge.bg-info {
+    background-color: #0dcaf0 !important;
+}
+
+.spinner-border {
+    margin: 1rem auto;
+    display: block;
+}
+
+.modal-content {
+    border-radius: 0.5rem;
+}
+
+.modal-header {
+    border-bottom: 1px solid #dee2e6;
+}
+
+.modal-footer {
+    border-top: 1px solid #dee2e6;
+}
+
+/* Status indicators */
+.status-active {
+    color: #198754;
+}
+
+.status-inactive {
+    color: #6c757d;
+}
+
+.status-error {
+    color: #dc3545;
+}
+
+.status-warning {
+    color: #ffc107;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+    .container-fluid {
+        padding: 0.5rem;
+    }
+    
+    .nav-tabs .nav-link {
+        padding: 0.5rem 0.75rem;
+        font-size: 0.875rem;
+    }
+    
+    .tab-content {
+        padding: 1rem;
+    }
+}
+
+/* Animation for refreshing */
+@keyframes spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+}
+
+.refreshing {
+    animation: spin 1s linear infinite;
+}
diff --git a/lmcache/v1/cache_controller/frontend/static/img/logo.png b/lmcache/v1/cache_controller/frontend/static/img/logo.png
new file mode 100644
index 0000000..398771d
Binary files /dev/null and b/lmcache/v1/cache_controller/frontend/static/img/logo.png differ
diff --git a/lmcache/v1/cache_controller/frontend/static/index.html b/lmcache/v1/cache_controller/frontend/static/index.html
new file mode 100644
index 0000000..81803db
--- /dev/null
+++ b/lmcache/v1/cache_controller/frontend/static/index.html
@@ -0,0 +1,234 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>LMCache Controller Dashboard</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/font/bootstrap-icons.css">
+    <link rel="stylesheet" href="/static/css/style.css">
+    <link rel="icon" href="/static/img/logo.png" type="image/png">
+</head>
+<body>
+    <div class="container-fluid">
+        <header class="bg-primary text-white p-3 mb-4">
+            <h1>LMCache Controller Dashboard</h1>
+            <div class="row align-items-center">
+                <div class="col-md-8">
+                    <div class="row g-2">
+                        <div class="col-md-6">
+                            <div class="input-group input-group-sm">
+                                <input type="text" class="form-control" id="controllerHostInput" placeholder="Controller Host (default: localhost)" value="localhost">
+                                <input type="text" class="form-control" id="controllerPortInput" placeholder="Controller Port (default: 9000)" value="9000">
+                                <button id="connectControllerBtn" class="btn btn-outline-light" type="button">
+                                    <i class="bi bi-plug"></i> Connect
+                                </button>
+                            </div>
+                        </div>
+                        <div class="col-md-6">
+                            <button id="refreshAllBtn" class="btn btn-sm btn-outline-light me-2">
+                                <i class="bi bi-arrow-clockwise"></i> Refresh All
+                            </button>
+                            <span id="connectionStatus" class="badge bg-warning">Not Connected</span>
+                        </div>
+                    </div>
+                </div>
+                <div class="col-md-4 text-end">
+                    <span id="currentTime" class="badge bg-info fs-6"></span>
+                </div>
+            </div>
+        </header>
+
+        <ul class="nav nav-tabs" id="controllerTabs" role="tablist">
+            <li class="nav-item" role="presentation">
+                <button class="nav-link active" id="overview-tab" data-bs-toggle="tab" data-bs-target="#overview" type="button" role="tab">Overview</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="instances-tab" data-bs-toggle="tab" data-bs-target="#instances" type="button" role="tab">Instances</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="workers-tab" data-bs-toggle="tab" data-bs-target="#workers" type="button" role="tab">Workers</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="metrics-tab" data-bs-toggle="tab" data-bs-target="#metrics" type="button" role="tab">Metrics</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="threads-tab" data-bs-toggle="tab" data-bs-target="#threads" type="button" role="tab">Threads</button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" id="env-tab" data-bs-toggle="tab" data-bs-target="#env" type="button" role="tab">Environment</button>
+            </li>
+        </ul>
+
+        <div class="tab-content p-3 border border-top-0" id="controllerTabContent">
+            <div class="tab-pane fade show active" id="overview" role="tabpanel">
+                <h3>Controller Overview</h3>
+                <div class="row">
+                    <div class="col-md-6">
+                        <div class="card mb-3">
+                            <div class="card-body">
+                                <h5 class="card-title">System Status</h5>
+                                <div id="systemStatus" class="text-center">
+                                    <div class="spinner-border" role="status">
+                                        <span class="visually-hidden">Loading...</span>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="col-md-6">
+                        <div class="card mb-3">
+                            <div class="card-body">
+                                <h5 class="card-title">Quick Stats</h5>
+                                <div id="quickStats" class="text-center">
+                                    <div class="spinner-border" role="status">
+                                        <span class="visually-hidden">Loading...</span>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+                <div class="row">
+                    <div class="col-md-12">
+                        <div class="card">
+                            <div class="card-body">
+                                <h5 class="card-title">Recent Activities</h5>
+                                <div id="recentActivities">
+                                    <div class="spinner-border" role="status">
+                                        <span class="visually-hidden">Loading...</span>
+                                    </div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <div class="tab-pane fade" id="instances" role="tabpanel">
+                <h3>Instance Management</h3>
+                <div class="mb-3">
+                    <button id="refreshInstancesBtn" class="btn btn-primary me-2">
+                        <i class="bi bi-arrow-clockwise"></i> Refresh Instances
+                    </button>
+                    <button id="addInstanceBtn" class="btn btn-success" data-bs-toggle="modal" data-bs-target="#addInstanceModal">
+                        <i class="bi bi-plus-circle"></i> Add Instance
+                    </button>
+                </div>
+                <div class="table-responsive">
+                    <table class="table table-striped" id="instances">
+                        <thead>
+                            <tr>
+                                <th>Instance ID</th>
+                                <th>IP Address</th>
+                                <th>Status</th>
+                                <th>Worker Count</th>
+                                <th>Key Count</th>
+                                <th>Last Heartbeat</th>
+                                <th>Actions</th>
+                            </tr>
+                        </thead>
+                        <tbody id="instancesTableBody">
+                            <!-- Instances will be populated here -->
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+
+            <div class="tab-pane fade" id="workers" role="tabpanel">
+                <h3>Worker Management</h3>
+                <div class="mb-3">
+                    <div class="row g-2">
+                        <div class="col-md-4">
+                            <select id="instanceFilter" class="form-select">
+                                <option value="">All Instances</option>
+                            </select>
+                        </div>
+                        <div class="col-md-2">
+                            <button id="refreshWorkersBtn" class="btn btn-primary w-100">
+                                <i class="bi bi-arrow-clockwise"></i> Refresh
+                            </button>
+                        </div>
+                    </div>
+                </div>
+                <div class="table-responsive">
+                    <table class="table table-striped" id="workers">
+                        <thead>
+                            <tr>
+                                <th>Instance ID</th>
+                                <th>Worker ID</th>
+                                <th>IP</th>
+                                <th>Port</th>
+                                <th>Status</th>
+                                <th>Key Count</th>
+                                <th>Last Heartbeat</th>
+                                <th>Actions</th>
+                            </tr>
+                        </thead>
+                        <tbody id="workersTableBody">
+                            <!-- Workers will be populated here -->
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+
+            <div class="tab-pane fade" id="metrics" role="tabpanel">
+                <h3>Performance Metrics</h3>
+                <div class="mb-3">
+                    <button id="refreshMetricsBtn" class="btn btn-primary">
+                        <i class="bi bi-arrow-clockwise"></i> Refresh Metrics
+                    </button>
+                </div>
+                <pre id="metricsContent">Please connect to controller first</pre>
+            </div>
+
+            <div class="tab-pane fade" id="threads" role="tabpanel">
+                <h3>Thread Information</h3>
+                <div class="mb-3">
+                    <button id="refreshThreadsBtn" class="btn btn-primary">
+                        <i class="bi bi-arrow-clockwise"></i> Refresh Threads
+                    </button>
+                </div>
+                <pre id="threadsContent">Please connect to controller first</pre>
+            </div>
+
+            <div class="tab-pane fade" id="env" role="tabpanel">
+                <h3>Environment Variables</h3>
+                <div class="mb-3">
+                    <input type="text" class="form-control" id="envSearchInput" placeholder="Search environment variables...">
+                </div>
+                <pre id="envContent">Please connect to controller first</pre>
+            </div>
+        </div>
+    </div>
+
+    <!-- Add Instance Modal -->
+    <div class="modal fade" id="addInstanceModal" tabindex="-1" aria-labelledby="addInstanceModalLabel" aria-hidden="true">
+        <div class="modal-dialog">
+            <div class="modal-content">
+                <div class="modal-header">
+                    <h5 class="modal-title" id="addInstanceModalLabel">Add New Instance</h5>
+                    <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+                </div>
+                <div class="modal-body">
+                    <div class="mb-3">
+                        <label for="newInstanceId" class="form-label">Instance ID</label>
+                        <input type="text" class="form-control" id="newInstanceId" placeholder="Enter instance ID">
+                    </div>
+                    <div class="mb-3">
+                        <label for="newInstanceIp" class="form-label">IP Address</label>
+                        <input type="text" class="form-control" id="newInstanceIp" placeholder="Enter IP address">
+                    </div>
+                </div>
+                <div class="modal-footer">
+                    <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
+                    <button type="button" class="btn btn-primary" id="saveInstanceBtn">Save Instance</button>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+    <script src="/static/js/controller_app.js"></script>
+</body>
+</html>
diff --git a/lmcache/v1/cache_controller/frontend/static/js/controller_app.js b/lmcache/v1/cache_controller/frontend/static/js/controller_app.js
new file mode 100644
index 0000000..86b94e7
--- /dev/null
+++ b/lmcache/v1/cache_controller/frontend/static/js/controller_app.js
@@ -0,0 +1,660 @@
+// Controller Dashboard JavaScript
+// Global variables
+let controllerBaseUrl = "";
+let isConnected = false;
+let currentInstances = [];
+let currentWorkers = [];
+let currentKeyPool = [];
+let envVariablesData = null;
+
+// Initialize after DOM is loaded
+window.addEventListener('DOMContentLoaded', () => {
+    // Initialize current time display
+    updateCurrentTime();
+    setInterval(updateCurrentTime, 1000);
+
+    // Connect button event
+    document.getElementById('connectControllerBtn').addEventListener('click', connectToController);
+
+    // Refresh all button
+    document.getElementById('refreshAllBtn').addEventListener('click', refreshAllData);
+
+    // Tab switching event
+    document.querySelectorAll('.nav-link').forEach(tab => {
+        tab.addEventListener('shown.bs.tab', (event) => {
+            if (isConnected) {
+                const tabId = event.target.getAttribute('data-bs-target').replace('#', '');
+                loadTabData(tabId);
+            }
+        });
+    });
+
+    // Instance management
+    document.getElementById('refreshInstancesBtn').addEventListener('click', loadInstances);
+    document.getElementById('saveInstanceBtn').addEventListener('click', addInstance);
+
+    // Worker management
+    document.getElementById('refreshWorkersBtn').addEventListener('click', loadWorkers);
+    document.getElementById('instanceFilter').addEventListener('change', loadWorkers);
+
+    // Metrics
+    document.getElementById('refreshMetricsBtn').addEventListener('click', loadMetrics);
+
+    // Threads
+    document.getElementById('refreshThreadsBtn').addEventListener('click', loadThreads);
+
+    // Environment
+    document.getElementById('envSearchInput').addEventListener('input', filterEnvVariables);
+
+    // Auto-connect on startup
+    const urlParams = new URLSearchParams(window.location.search);
+    const urlHostParam = urlParams.get('host');
+    const urlPortParam = urlParams.get('port');
+    
+    // Get host and port from URL parameters, or use current page's hostname and port
+    const autoHost = urlHostParam || window.location.hostname;
+    const autoPort = urlPortParam || window.location.port || (window.location.protocol === 'https:' ? '443' : '80');
+    
+    // Always set input values and attempt to connect
+    document.getElementById('controllerHostInput').value = autoHost;
+    document.getElementById('controllerPortInput').value = autoPort;
+    setTimeout(() => connectToController(), 1000);
+});
+
+// Update current time display
+function updateCurrentTime() {
+    const now = new Date();
+    const timeString = now.toLocaleTimeString('en-US', {
+        hour12: false,
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit'
+    });
+    document.getElementById('currentTime').textContent = timeString;
+}
+
+// Connect to Controller
+async function connectToController() {
+    const host = document.getElementById('controllerHostInput').value.trim();
+    const port = document.getElementById('controllerPortInput').value.trim();
+    
+    if (!host || !port) {
+        alert('Please enter controller host and port');
+        return;
+    }
+
+    // Construct the base URL
+    const protocol = window.location.protocol;
+    controllerBaseUrl = `${protocol}//${host}:${port}`;
+    const statusElement = document.getElementById('connectionStatus');
+    
+    try {
+        statusElement.textContent = 'Connecting...';
+        statusElement.className = 'badge bg-warning';
+        
+        // Test connection with a simple health check
+        const response = await fetch(`${controllerBaseUrl}/health`, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({ instance_id: 'test' })
+        });
+        
+        if (response.ok) {
+            isConnected = true;
+            statusElement.textContent = 'Connected';
+            statusElement.className = 'badge bg-success';
+            
+            // Load initial data
+            loadOverview();
+            loadInstances();
+            loadWorkers();
+            
+            // Update URL with connection parameters
+            const newUrl = new URL(window.location);
+            newUrl.searchParams.set('host', host);
+            newUrl.searchParams.set('port', port);
+            window.history.replaceState({}, '', newUrl);
+            
+        } else {
+            throw new Error('Connection failed');
+        }
+    } catch (error) {
+        console.error('Connection error:', error);
+        statusElement.textContent = 'Connection Failed';
+        statusElement.className = 'badge bg-danger';
+        isConnected = false;
+        alert('Failed to connect to controller: ' + error.message);
+    }
+}
+
+// Refresh all data
+async function refreshAllData() {
+    if (!isConnected) {
+        alert('Please connect to controller first');
+        return;
+    }
+
+    const activeTab = document.querySelector('.tab-pane.active').id;
+    loadTabData(activeTab);
+}
+
+// Load data for active tab
+function loadTabData(tabId) {
+    if (!isConnected) return;
+
+    switch (tabId) {
+        case 'overview':
+            loadOverview();
+            break;
+        case 'instances':
+            loadInstances();
+            break;
+        case 'workers':
+            loadWorkers();
+            break;
+        case 'metrics':
+            loadMetrics();
+            break;
+        case 'threads':
+            loadThreads();
+            break;
+        case 'env':
+            loadEnvironment();
+            break;
+    }
+}
+
+// Load overview data
+async function loadOverview() {
+    if (!isConnected) return;
+
+    const systemStatusElement = document.getElementById('systemStatus');
+    const quickStatsElement = document.getElementById('quickStats');
+    const recentActivitiesElement = document.getElementById('recentActivities');
+
+    try {
+        // Load system status
+        const healthResponse = await fetch(`${controllerBaseUrl}/health`, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({ instance_id: 'system' })
+        });
+
+        if (healthResponse.ok) {
+            const healthData = await healthResponse.json();
+            systemStatusElement.innerHTML = `
+                <div class="text-success">
+                    <i class="bi bi-check-circle-fill fs-1"></i>
+                    <p class="mt-2">Controller is running</p>
+                    <small class="text-muted">Event ID: ${healthData.event_id}</small>
+                </div>
+            `;
+        }
+
+        // Load quick stats (instance count, worker count, key count)
+        const response = await fetch(`${controllerBaseUrl}/query_worker_info`, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({ instance_id: 'all', worker_ids: [] })
+        });
+
+        // Load key stats
+        const keyStatsResponse = await fetch(`${controllerBaseUrl}/controller/key-stats`, {
+            method: 'GET',
+            headers: {'Content-Type': 'application/json'}
+        });
+
+        if (response.ok && keyStatsResponse.ok) {
+            const data = await response.json();
+            const keyStatsData = await keyStatsResponse.json();
+            const instanceCount = new Set(data.worker_infos.map(w => w.instance_id)).size;
+            const workerCount = data.worker_infos.length;
+            const keyCount = keyStatsData.total_key_count;
+            
+            quickStatsElement.innerHTML = `
+                <div class="row">
+                    <div class="col-4">
+                        <div class="card bg-light mb-2">
+                            <div class="card-body p-2">
+                                <h6 class="card-title mb-0">Instances</h6>
+                                <h3 class="mb-0">${instanceCount}</h3>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="col-4">
+                        <div class="card bg-light mb-2">
+                            <div class="card-body p-2">
+                                <h6 class="card-title mb-0">Workers</h6>
+                                <h3 class="mb-0">${workerCount}</h3>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="col-4">
+                        <div class="card bg-light mb-2">
+                            <div class="card-body p-2">
+                                <h6 class="card-title mb-0">Total Keys</h6>
+                                <h3 class="mb-0">${keyCount}</h3>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            `;
+        }
+
+        // Recent activities (placeholder)
+        recentActivitiesElement.innerHTML = `
+            <div class="list-group">
+                <div class="list-group-item">
+                    <small class="text-muted">Just now</small>
+                    <p class="mb-1">Controller dashboard loaded</p>
+                </div>
+                <div class="list-group-item">
+                    <small class="text-muted">2 minutes ago</small>
+                    <p class="mb-1">Health check performed</p>
+                </div>
+            </div>
+        `;
+
+    } catch (error) {
+        console.error('Error loading overview:', error);
+        systemStatusElement.innerHTML = `<div class="alert alert-danger">Error: ${error.message}</div>`;
+    }
+}
+
+// Load instances
+async function loadInstances() {
+    if (!isConnected) return;
+
+    const tableBody = document.getElementById('instancesTableBody');
+    tableBody.innerHTML = '<tr><td colspan="7" class="text-center"><div class="spinner-border" role="status"></div></td></tr>';
+
+    try {
+        const response = await fetch(`${controllerBaseUrl}/query_worker_info`, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify({ instance_id: 'all' })
+        });
+
+        // Load key stats for instances
+        const keyStatsResponse = await fetch(`${controllerBaseUrl}/controller/key-stats`, {
+            method: 'GET',
+            headers: {'Content-Type': 'application/json'}
+        });
+
+        if (!response.ok || !keyStatsResponse.ok) {
+            throw new Error('Failed to fetch instances or key stats');
+        }
+
+        const data = await response.json();
+        const keyStatsData = await keyStatsResponse.json();
+        currentInstances = data.worker_infos;
+        
+        // Create a map of instance key counts from key stats
+        const instanceKeyCounts = new Map();
+        keyStatsData.instances.forEach(instance => {
+            instanceKeyCounts.set(instance.instance_id, instance.key_count);
+        });
+        
+        // Group workers by instance
+        const instancesMap = new Map();
+        currentInstances.forEach(worker => {
+            if (!instancesMap.has(worker.instance_id)) {
+                instancesMap.set(worker.instance_id, {
+                    instance_id: worker.instance_id,
+                    ip: worker.ip,
+                    workers: [],
+                    last_heartbeat: worker.last_heartbeat_time,
+                    key_count: instanceKeyCounts.get(worker.instance_id) || 0
+                });
+            }
+            instancesMap.get(worker.instance_id).workers.push(worker);
+            // Update latest heartbeat
+            if (worker.last_heartbeat_time > instancesMap.get(worker.instance_id).last_heartbeat) {
+                instancesMap.get(worker.instance_id).last_heartbeat = worker.last_heartbeat_time;
+            }
+        });
+
+        // Update instance filter dropdown
+        const instanceFilter = document.getElementById('instanceFilter');
+        instanceFilter.innerHTML = '<option value="">All Instances</option>';
+        instancesMap.forEach((instance, instanceId) => {
+            const option = document.createElement('option');
+            option.value = instanceId;
+            option.textContent = instanceId;
+            instanceFilter.appendChild(option);
+        });
+
+        // Update HTML table header to include Key Count column
+        const tableHeader = document.querySelector('#instances thead tr');
+        if (tableHeader && !tableHeader.innerHTML.includes('Key Count')) {
+            tableHeader.innerHTML = `
+                <th>Instance ID</th>
+                <th>IP Address</th>
+                <th>Status</th>
+                <th>Worker Count</th>
+                <th>Key Count</th>
+                <th>Last Heartbeat</th>
+                <th>Actions</th>
+            `;
+        }
+
+        // Populate table
+        tableBody.innerHTML = '';
+        instancesMap.forEach((instance, instanceId) => {
+            const row = document.createElement('tr');
+            const now = Math.floor(Date.now() / 1000);
+            const timeDiff = now - instance.last_heartbeat;
+            const status = timeDiff < 60 ? 'Active' : timeDiff < 300 ? 'Warning' : 'Inactive';
+            const statusClass = timeDiff < 60 ? 'status-active' : timeDiff < 300 ? 'status-warning' : 'status-inactive';
+            
+            const lastHeartbeat = new Date(instance.last_heartbeat * 1000).toLocaleTimeString();
+            
+            row.innerHTML = `
+                <td><strong>${instanceId}</strong></td>
+                <td>${instance.ip}</td>
+                <td><span class="${statusClass}">${status}</span></td>
+                <td>${instance.workers.length}</td>
+                <td>${instance.key_count}</td>
+                <td>${lastHeartbeat}</td>
+                <td>
+                    <button class="btn btn-sm btn-info view-instance" data-instance="${instanceId}">View</button>
+                    <button class="btn btn-sm btn-danger remove-instance" data-instance="${instanceId}">Remove</button>
+                </td>
+            `;
+            tableBody.appendChild(row);
+        });
+
+        // Add event listeners to buttons
+        document.querySelectorAll('.view-instance').forEach(btn => {
+            btn.addEventListener('click', (e) => {
+                const instanceId = e.target.dataset.instance;
+                alert(`Viewing instance: ${instanceId}`);
+                // In a real implementation, this would navigate to instance details
+            });
+        });
+
+        document.querySelectorAll('.remove-instance').forEach(btn => {
+            btn.addEventListener('click', (e) => {
+                const instanceId = e.target.dataset.instance;
+                if (confirm(`Are you sure you want to remove instance ${instanceId}?`)) {
+                    removeInstance(instanceId);
+                }
+            });
+        });
+
+    } catch (error) {
+        console.error('Error loading instances:', error);
+        tableBody.innerHTML = `<tr><td colspan="7" class="text-center text-danger">Error: ${error.message}</td></tr>`;
+    }
+}
+
+// Add instance (placeholder - would need backend implementation)
+async function addInstance() {
+    const instanceId = document.getElementById('newInstanceId').value.trim();
+    const instanceIp = document.getElementById('newInstanceIp').value.trim();
+
+    if (!instanceId || !instanceIp) {
+        alert('Please fill all fields');
+        return;
+    }
+
+    // This is a placeholder - in reality, you would need a backend endpoint to add instances
+    alert(`Would add instance: ${instanceId} with IP: ${instanceIp}`);
+    
+    // Close modal
+    const modal = bootstrap.Modal.getInstance(document.getElementById('addInstanceModal'));
+    modal.hide();
+    
+    // Clear form
+    document.getElementById('newInstanceId').value = '';
+    document.getElementById('newInstanceIp').value = '';
+    
+    // Refresh instances list
+    loadInstances();
+}
+
+// Remove instance (placeholder)
+async function removeInstance(instanceId) {
+    // This is a placeholder - in reality, you would need a backend endpoint to remove instances
+    alert(`Would remove instance: ${instanceId}`);
+    loadInstances();
+}
+
+// Load workers
+async function loadWorkers() {
+    if (!isConnected) return;
+
+    const tableBody = document.getElementById('workersTableBody');
+    const instanceFilter = document.getElementById('instanceFilter').value;
+    
+    tableBody.innerHTML = '<tr><td colspan="8" class="text-center"><div class="spinner-border" role="status"></div></td></tr>';
+
+    try {
+        const requestBody = instanceFilter ? 
+            { instance_id: instanceFilter, worker_ids: [] } : 
+            { instance_id: 'all', worker_ids: [] };
+        
+        const response = await fetch(`${controllerBaseUrl}/query_worker_info`, {
+            method: 'POST',
+            headers: {'Content-Type': 'application/json'},
+            body: JSON.stringify(requestBody)
+        });
+
+        if (!response.ok) {
+            throw new Error('Failed to fetch workers');
+        }
+
+        const data = await response.json();
+        currentWorkers = data.worker_infos;
+        
+        // Get detailed worker info with key counts
+        const workersWithKeyCounts = await Promise.all(
+            currentWorkers.map(async (worker) => {
+                try {
+                    // Get detailed worker info including key count
+                    const workerDetailResponse = await fetch(`${controllerBaseUrl}/controller/workers?instance_id=${worker.instance_id}&worker_id=${worker.worker_id}`, {
+                        method: 'GET',
+                        headers: {'Content-Type': 'application/json'}
+                    });
+                    
+                    if (workerDetailResponse.ok) {
+                        const workerDetail = await workerDetailResponse.json();
+                        return {
+                            ...worker,
+                            key_count: workerDetail.key_count || 0
+                        };
+                    }
+                } catch (error) {
+                    console.warn(`Failed to get key count for worker ${worker.instance_id}/${worker.worker_id}:`, error);
+                }
+                
+                // Fallback to 0 if key count is not available
+                return {
+                    ...worker,
+                    key_count: 0
+                };
+            })
+        );
+        
+        // Update HTML table header to include Key Count column
+        const tableHeader = document.querySelector('#workers thead tr');
+        if (tableHeader && !tableHeader.innerHTML.includes('Key Count')) {
+            tableHeader.innerHTML = `
+                <th>Instance ID</th>
+                <th>Worker ID</th>
+                <th>IP</th>
+                <th>Port</th>
+                <th>Status</th>
+                <th>Key Count</th>
+                <th>Last Heartbeat</th>
+                <th>Actions</th>
+            `;
+        }
+        
+        // Populate table
+        tableBody.innerHTML = '';
+        workersWithKeyCounts.forEach(worker => {
+            const row = document.createElement('tr');
+            const now = Math.floor(Date.now() / 1000);
+            const timeDiff = now - worker.last_heartbeat_time;
+            const status = timeDiff < 60 ? 'Active' : timeDiff < 300 ? 'Warning' : 'Inactive';
+            const statusClass = timeDiff < 60 ? 'status-active' : timeDiff < 300 ? 'status-warning' : 'status-inactive';
+            
+            const lastHeartbeat = new Date(worker.last_heartbeat_time * 1000).toLocaleTimeString();
+            
+            row.innerHTML = `
+                <td>${worker.instance_id}</td>
+                <td>${worker.worker_id}</td>
+                <td>${worker.ip}</td>
+                <td>${worker.port}</td>
+                <td><span class="${statusClass}">${status}</span></td>
+                <td>${worker.key_count}</td>
+                <td>${lastHeartbeat}</td>
+                <td>
+                    <button class="btn btn-sm btn-info view-worker" data-instance="${worker.instance_id}" data-worker="${worker.worker_id}">View</button>
+                </td>
+            `;
+            tableBody.appendChild(row);
+        });
+
+    } catch (error) {
+        console.error('Error loading workers:', error);
+        tableBody.innerHTML = `<tr><td colspan="8" class="text-center text-danger">Error: ${error.message}</td></tr>`;
+    }
+}
+
+// Load log level
+async function removeKey(key) {
+    // This is a placeholder - in reality, you would need a backend endpoint to remove keys
+    alert(`Would remove key: ${key}`);
+    loadKeyPool();
+}
+
+// Load metrics
+async function loadMetrics() {
+    if (!isConnected) return;
+
+    const contentDiv = document.getElementById('metricsContent');
+    contentDiv.textContent = 'Loading...';
+
+    try {
+        // Note: This endpoint might not exist in the current controller
+        // You would need to implement a metrics endpoint
+        const response = await fetch(`${controllerBaseUrl}/metrics`);
+        
+        if (response.ok) {
+            const metrics = await response.text();
+            contentDiv.textContent = metrics;
+        } else {
+            contentDiv.textContent = 'Metrics endpoint not available. Would need to implement /metrics endpoint.';
+        }
+    } catch (error) {
+        contentDiv.textContent = `Failed to load metrics: ${error.message}`;
+    }
+}
+
+// Load environment variables
+async function loadEnvironment() {
+    if (!isConnected) return;
+
+    const contentDiv = document.getElementById('envContent');
+    const searchInput = document.getElementById('envSearchInput');
+    contentDiv.textContent = 'Loading...';
+    searchInput.value = '';
+
+    try {
+        // Call /env API to get environment variables
+        const response = await fetch(`${controllerBaseUrl}/env`);
+        
+        if (!response.ok) {
+            throw new Error('Failed to fetch environment variables');
+        }
+
+        envVariablesData = await response.json();
+        
+        // Format for display
+        if (typeof envVariablesData === 'object' && envVariablesData !== null) {
+            const formattedText = Object.entries(envVariablesData)
+                .map(([key, value]) => `${key}=${value}`)
+                .join('\n');
+            contentDiv.textContent = formattedText;
+        } else {
+            contentDiv.textContent = 'No environment variables found or invalid data format';
+            envVariablesData = null;
+        }
+    } catch (error) {
+        console.error('Error loading environment variables:', error);
+        contentDiv.textContent = `Failed to load environment variables: ${error.message}`;
+        envVariablesData = null;
+    }
+}
+
+// Filter environment variables
+function filterEnvVariables() {
+    const searchInput = document.getElementById('envSearchInput');
+    const contentDiv = document.getElementById('envContent');
+    const searchTerm = searchInput.value.toLowerCase();
+
+    if (!envVariablesData) return;
+
+    if (typeof envVariablesData === 'object') {
+        const filteredEntries = Object.entries(envVariablesData).filter(([key, value]) => {
+            const line = `${key}=${value}`;
+            return line.toLowerCase().includes(searchTerm);
+        });
+        const formattedText = filteredEntries
+            .map(([key, value]) => `${key}=${value}`)
+            .join('\n');
+        contentDiv.textContent = formattedText;
+    }
+}
+
+// Load threads
+async function loadThreads() {
+    if (!isConnected) return;
+
+    const contentDiv = document.getElementById('threadsContent');
+    contentDiv.textContent = 'Loading...';
+
+    try {
+        const response = await fetch(`${controllerBaseUrl}/threads`);
+        
+        if (!response.ok) {
+            throw new Error('Failed to fetch threads');
+        }
+
+        // Try to parse as JSON first
+        const responseText = await response.text();
+        
+        let formattedText;
+        try {
+            // Try to parse as JSON
+            const threadsData = JSON.parse(responseText);
+            
+            // Format threads data as text
+            formattedText = '';
+            threadsData.forEach((thread, index) => {
+                formattedText += `Thread: ${thread.function_name}\n`;
+                // Add thread details in a format similar to stack trace
+                formattedText += `  thread_id: ${thread.thread_id}\n`;
+                formattedText += `  name: ${thread.name}\n`;
+                formattedText += `  state: ${thread.state}\n`;
+                formattedText += `  cpu_time: ${thread.cpu_time}\n`;
+                formattedText += `  memory_usage: ${thread.memory_usage}\n`;
+                
+                // Add separator between threads
+                if (index < threadsData.length - 1) {
+                    formattedText += '\n\n';
+                }
+            });
+        } catch (jsonError) {
+            // If not JSON, use the text as-is
+            formattedText = responseText;
+        }
+        
+        contentDiv.textContent = formattedText;
+    } catch (error) {
+        console.error('Error loading threads:', error);
+        contentDiv.textContent = `Failed to load threads: ${error.message}`;
+    }
+}
\ No newline at end of file
diff --git a/lmcache/v1/cache_controller/full_sync_sender.py b/lmcache/v1/cache_controller/full_sync_sender.py
new file mode 100644
index 0000000..394c0dc
--- /dev/null
+++ b/lmcache/v1/cache_controller/full_sync_sender.py
@@ -0,0 +1,475 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List, Optional
+import asyncio
+import random
+import uuid
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.message import (
+    FullSyncBatchMsg,
+    FullSyncEndMsg,
+    FullSyncStartMsg,
+    FullSyncStartRetMsg,
+    FullSyncStatusMsg,
+    FullSyncStatusRetMsg,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+    from lmcache.v1.cache_engine import LMCacheEngine
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class SyncInitResult:
+    """Result of sync initialization"""
+
+    sync_id: str
+    keys: List[int]
+    total_keys: int
+    batch_count: int
+
+
+@dataclass
+class BatchInfo:
+    """Information about a batch for resending"""
+
+    batch_id: int
+    start_idx: int
+    end_idx: int
+
+
+class FullSyncSender:
+    """
+    Handles full sync of hot_cache keys to the Controller.
+
+    This class manages the process of sending all keys from the local hot_cache
+    to the Controller when a full sync is requested (e.g., after Controller restart).
+
+    The sync process:
+    1. Enter freeze mode (prevent allocations)
+    2. Add random startup delay (avoid thundering herd)
+    3. Send FullSyncStartMsg and wait for confirmation
+    4. Send keys in batches via FullSyncBatchMsg
+    5. Send FullSyncEndMsg
+    6. Poll for completion status
+    7. Exit freeze mode when threshold is reached
+    """
+
+    def __init__(
+        self,
+        config: "LMCacheEngineConfig",
+        worker: "LMCacheWorker",
+        lmcache_engine: "LMCacheEngine",
+        local_cpu_backend: "LocalCPUBackend",
+    ):
+        # Configuration
+        self.batch_size = config.get_extra_config_value("full_sync_batch_size", 2000)
+        self.batch_interval_ms = config.get_extra_config_value(
+            "full_sync_batch_interval_ms", 5
+        )
+        self.startup_delay_range_s = config.get_extra_config_value(
+            "full_sync_startup_delay_s", 5.0
+        )
+        self.status_poll_interval_s = config.get_extra_config_value(
+            "full_sync_status_poll_interval_s", 5.0
+        )
+        self.max_retry_count = config.get_extra_config_value(
+            "full_sync_max_retry_count", 3
+        )
+        self.retry_delay_s = config.get_extra_config_value(
+            "full_sync_retry_delay_s", 1.0
+        )
+        self.max_poll_attempts = config.get_extra_config_value(
+            "full_sync_max_poll_attempts", 60
+        )
+
+        # Dependencies
+        self.worker = worker
+        self.lmcache_engine = lmcache_engine
+        self.local_cpu_backend = local_cpu_backend
+        self.config = config
+
+        # State
+        self._is_syncing = False
+        self._current_sync_id: Optional[str] = None
+
+    @property
+    def instance_id(self) -> str:
+        return self.config.lmcache_instance_id
+
+    @property
+    def worker_id(self) -> int:
+        return self.worker.worker_id
+
+    @property
+    def location(self) -> str:
+        return str(self.local_cpu_backend)
+
+    def _generate_sync_id(self) -> str:
+        """Generate a unique sync session ID"""
+        return f"{self.instance_id}_{self.worker_id}_{uuid.uuid4().hex[:8]}"
+
+    def _get_all_hot_cache_keys(self) -> List[int]:
+        """Get all chunk hashes from the hot cache"""
+        keys = self.local_cpu_backend.get_keys()
+        return [key.chunk_hash for key in keys]
+
+    async def _send_sync_start(
+        self, sync_id: str, total_keys: int, batch_count: int
+    ) -> Optional[FullSyncStartRetMsg]:
+        """Send FullSyncStartMsg and wait for confirmation"""
+        msg = FullSyncStartMsg(
+            instance_id=self.instance_id,
+            worker_id=self.worker_id,
+            location=self.location,
+            sync_id=sync_id,
+            total_keys=total_keys,
+            batch_count=batch_count,
+        )
+
+        try:
+            ret_msg = await self.worker.async_put_and_wait_msg(msg)
+            if isinstance(ret_msg, FullSyncStartRetMsg):
+                return ret_msg
+            else:
+                logger.error(
+                    "Unexpected response type for FullSyncStartMsg: %s", type(ret_msg)
+                )
+                return None
+        except Exception as e:
+            logger.error("Error sending FullSyncStartMsg: %s", e)
+            return None
+
+    def _send_sync_batch(self, sync_id: str, batch_id: int, keys: List[int]) -> None:
+        """Send a batch of keys via PUSH mode"""
+        msg = FullSyncBatchMsg(
+            instance_id=self.instance_id,
+            worker_id=self.worker_id,
+            location=self.location,
+            sync_id=sync_id,
+            batch_id=batch_id,
+            keys=keys,
+        )
+        self.worker.put_msg(msg)
+
+    def _send_sync_end(self, sync_id: str, actual_total_keys: int) -> None:
+        """Send FullSyncEndMsg via PUSH mode"""
+        msg = FullSyncEndMsg(
+            instance_id=self.instance_id,
+            worker_id=self.worker_id,
+            location=self.location,
+            sync_id=sync_id,
+            actual_total_keys=actual_total_keys,
+        )
+        self.worker.put_msg(msg)
+
+    async def _query_sync_status(self, sync_id: str) -> Optional[FullSyncStatusRetMsg]:
+        """Query sync status from controller"""
+        msg = FullSyncStatusMsg(
+            instance_id=self.instance_id,
+            worker_id=self.worker_id,
+            sync_id=sync_id,
+        )
+
+        try:
+            ret_msg = await self.worker.async_put_and_wait_msg(msg)
+            if isinstance(ret_msg, FullSyncStatusRetMsg):
+                return ret_msg
+            else:
+                logger.error(
+                    "Unexpected response type for FullSyncStatusMsg: %s", type(ret_msg)
+                )
+                return None
+        except Exception as e:
+            logger.error("Error querying sync status: %s", e)
+            return None
+
+    async def _initialize_sync(
+        self, reason: Optional[str] = None
+    ) -> Optional[SyncInitResult]:
+        """
+        Initialize the sync process.
+
+        Handles startup delay, entering freeze mode, getting keys,
+        and sending the start message with retry.
+
+        Args:
+            reason: The reason for full sync
+
+        Returns:
+            SyncInitResult if initialization succeeded, None otherwise
+        """
+        # Step 1: Random startup delay to avoid thundering herd
+        delay = random.uniform(0, self.startup_delay_range_s)
+        logger.info("Full sync startup delay: %.2fs", delay)
+        await asyncio.sleep(delay)
+
+        # Step 2: Enter freeze mode
+        logger.info("Entering freeze mode for full sync.")
+        self.lmcache_engine.freeze(True)
+
+        # Step 3: Get all keys from hot cache
+        keys = self._get_all_hot_cache_keys()
+        total_keys = len(keys)
+        batch_count = (total_keys + self.batch_size - 1) // self.batch_size
+        batch_count = max(batch_count, 1)  # At least 1 batch even if empty
+
+        logger.info(
+            "Full sync: total_keys=%d, batch_size=%d, batch_count=%d",
+            total_keys,
+            self.batch_size,
+            batch_count,
+        )
+
+        # Step 4: Generate sync ID and send start message with retry
+        sync_id = self._generate_sync_id()
+        self._current_sync_id = sync_id
+
+        start_accepted = False
+        for attempt in range(self.max_retry_count):
+            ret_msg = await self._send_sync_start(sync_id, total_keys, batch_count)
+            if ret_msg is not None and ret_msg.accepted:
+                start_accepted = True
+                break
+            logger.warning(
+                "FullSyncStart not accepted, attempt %d/%d, error: %s",
+                attempt + 1,
+                self.max_retry_count,
+                ret_msg.error_msg if ret_msg else "No response",
+            )
+            await asyncio.sleep(self.retry_delay_s)
+
+        if not start_accepted:
+            logger.error(
+                "Failed to start full sync after %d attempts", self.max_retry_count
+            )
+            return None
+
+        return SyncInitResult(
+            sync_id=sync_id,
+            keys=keys,
+            total_keys=total_keys,
+            batch_count=batch_count,
+        )
+
+    async def _send_key_batches(
+        self, sync_id: str, keys: List[int], batch_count: int
+    ) -> int:
+        """
+        Send keys in batches to the controller.
+
+        Args:
+            sync_id: The sync session ID
+            keys: List of all keys to send
+            batch_count: Number of batches to send
+
+        Returns:
+            Total number of keys sent
+        """
+        total_keys = len(keys)
+
+        for batch_id in range(batch_count):
+            start_idx = batch_id * self.batch_size
+            end_idx = min(start_idx + self.batch_size, total_keys)
+            batch_keys = keys[start_idx:end_idx]
+
+            self._send_sync_batch(sync_id, batch_id, batch_keys)
+
+            logger.debug(
+                "Sent batch %d/%d with %d keys",
+                batch_id + 1,
+                batch_count,
+                len(batch_keys),
+            )
+
+            # Small delay between batches to avoid overwhelming controller
+            if self.batch_interval_ms > 0 and batch_id < batch_count - 1:
+                await asyncio.sleep(self.batch_interval_ms / 1000.0)
+
+        # Send end message
+        self._send_sync_end(sync_id, total_keys)
+        logger.info("Full sync batches sent, total_keys=%d", total_keys)
+
+        return total_keys
+
+    async def _resend_missing_batches(
+        self, sync_id: str, keys: List[int], missing_batches: List[int]
+    ) -> None:
+        """
+        Resend missing batches to the controller.
+
+        Args:
+            sync_id: The sync session ID
+            keys: List of all keys
+            missing_batches: List of missing batch IDs to resend
+        """
+        total_keys = len(keys)
+
+        logger.info(
+            "Resending %d missing batches: %s",
+            len(missing_batches),
+            missing_batches,
+        )
+
+        for batch_id in missing_batches:
+            start_idx = batch_id * self.batch_size
+            end_idx = min(start_idx + self.batch_size, total_keys)
+            batch_keys = keys[start_idx:end_idx]
+
+            self._send_sync_batch(sync_id, batch_id, batch_keys)
+
+            logger.debug(
+                "Resent batch %d with %d keys",
+                batch_id,
+                len(batch_keys),
+            )
+
+            # Small delay between batches
+            if self.batch_interval_ms > 0:
+                await asyncio.sleep(self.batch_interval_ms / 1000.0)
+
+        logger.info("Finished resending %d missing batches", len(missing_batches))
+
+    async def _poll_for_completion(
+        self, sync_id: str, keys: List[int], total_keys: int
+    ) -> bool:
+        """
+        Poll for sync completion status and resend missing batches if needed.
+
+        Args:
+            sync_id: The sync session ID
+            keys: List of all keys (needed for resending missing batches)
+            total_keys: Total number of keys
+
+        Returns:
+            True if sync completed and can exit freeze mode, False on timeout
+        """
+        resend_count = 0
+        # TODO(baoloongmao): This can be an individual config
+        max_resend_attempts = self.max_retry_count
+
+        for poll_attempt in range(self.max_poll_attempts):
+            await asyncio.sleep(self.status_poll_interval_s)
+
+            status = await self._query_sync_status(sync_id)
+            if status is None:
+                logger.warning(
+                    "Failed to query sync status, attempt %d", poll_attempt + 1
+                )
+                continue
+
+            logger.info(
+                "Sync status: is_complete=%s, global_progress=%.1f%%, "
+                "can_exit_freeze=%s, missing_batches=%s",
+                status.is_complete,
+                status.global_progress * 100,
+                status.can_exit_freeze,
+                status.missing_batches if status.missing_batches else "none",
+            )
+
+            if status.can_exit_freeze:
+                return True
+
+            # Handle missing batches - resend them
+            if status.missing_batches and resend_count < max_resend_attempts:
+                resend_count += 1
+                logger.warning(
+                    "Controller reported missing batches, resending "
+                    "(attempt %d/%d): %s",
+                    resend_count,
+                    max_resend_attempts,
+                    status.missing_batches,
+                )
+                await self._resend_missing_batches(
+                    sync_id, keys, status.missing_batches
+                )
+                # Resend end message after resending missing batches
+                self._send_sync_end(sync_id, total_keys)
+            elif status.missing_batches and resend_count >= max_resend_attempts:
+                logger.error(
+                    "Max resend attempts reached (%d), "
+                    "giving up on missing batches: %s",
+                    max_resend_attempts,
+                    status.missing_batches,
+                )
+
+        # TODO(baoloongmao): Use heartbeat to detect controller failure
+        # and exit freeze mode if necessary
+        logger.warning("Full sync status poll timeout, exiting freeze mode anyway")
+        return False
+
+    async def start_full_sync(self, reason: Optional[str] = None) -> bool:
+        """
+        Start the full sync process.
+
+        This method orchestrates the full sync by delegating to helper methods:
+        1. _initialize_sync: Startup delay, freeze mode, get keys, send start msg
+        2. _send_key_batches: Send all keys in batches
+        3. _poll_for_completion: Poll for sync completion status
+
+        Args:
+            reason: The reason for full sync (e.g., "controller_restart")
+
+        Returns:
+            True if sync completed successfully, False otherwise
+        """
+        if self._is_syncing:
+            logger.warning("Full sync already in progress, skipping")
+            return False
+
+        self._is_syncing = True
+        self._current_sync_id = None
+
+        logger.info(
+            "Starting full sync for worker %s:%s, reason: %s",
+            self.instance_id,
+            self.worker_id,
+            reason,
+        )
+
+        try:
+            # Step 1: Initialize sync (delay, freeze, get keys, send start)
+            init_result = await self._initialize_sync(reason)
+            if init_result is None:
+                return False
+
+            # Step 2: Send keys in batches
+            await self._send_key_batches(
+                init_result.sync_id,
+                init_result.keys,
+                init_result.batch_count,
+            )
+
+            # Step 3: Poll for completion status (with resend support)
+            await self._poll_for_completion(
+                init_result.sync_id,
+                init_result.keys,
+                init_result.total_keys,
+            )
+
+            logger.info("Full sync completed successfully")
+            return True
+
+        except Exception as e:
+            logger.error("Error during full sync: %s", e)
+            return False
+
+        finally:
+            # Always clean up state, regardless of success or failure
+            logger.info("Exiting freeze mode after full sync.")
+            self.lmcache_engine.freeze(False)
+            self._is_syncing = False
+            self._current_sync_id = None
+
+    @property
+    def is_syncing(self) -> bool:
+        """Check if full sync is currently in progress"""
+        return self._is_syncing
diff --git a/lmcache/v1/cache_controller/locks.py b/lmcache/v1/cache_controller/locks.py
new file mode 100644
index 0000000..b9d8912
--- /dev/null
+++ b/lmcache/v1/cache_controller/locks.py
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Lock utilities for thread-safe operations.
+
+This module provides thread synchronization primitives with timeout support.
+"""
+
+# Standard
+from contextlib import contextmanager
+from typing import Optional
+import threading
+import time
+
+
+class RWLockTimeoutError(Exception):
+    """Exception raised when a lock acquisition times out."""
+
+    pass
+
+
+class RWLockWithTimeout:
+    """
+    A simple read-write lock with timeout support.
+    Multiple readers can hold the lock simultaneously, but only one writer.
+
+    Note: This lock is NOT reentrant.
+    """
+
+    def __init__(self):
+        self._readers = 0
+        self._writers_waiting = 0
+        self._writer_active = False
+        self._condition = threading.Condition(threading.Lock())
+
+    def acquire_read(self, timeout: Optional[float] = None) -> bool:
+        """Acquire a read lock with optional timeout."""
+        deadline = time.monotonic() + timeout if timeout is not None else None
+
+        with self._condition:
+            # Note: Sustained write operations may starve reads if writers
+            # continuously arrive while readers are waiting
+            while self._writer_active or self._writers_waiting > 0:
+                if deadline is not None and time.monotonic() >= deadline:
+                    return False
+                remaining = deadline - time.monotonic() if deadline else None
+                if remaining is not None and remaining <= 0:
+                    return False
+                self._condition.wait(timeout=remaining)
+            self._readers += 1
+            return True
+
+    def release_read(self):
+        """Release a read lock."""
+        with self._condition:
+            self._readers -= 1
+            if self._readers == 0:
+                self._condition.notify_all()
+
+    def acquire_write(self, timeout: Optional[float] = None) -> bool:
+        """Acquire a write lock with optional timeout."""
+        deadline = time.monotonic() + timeout if timeout is not None else None
+
+        with self._condition:
+            self._writers_waiting += 1
+            try:
+                while self._readers > 0 or self._writer_active:
+                    if deadline is not None and time.monotonic() >= deadline:
+                        return False
+                    remaining = deadline - time.monotonic() if deadline else None
+                    if remaining is not None and remaining <= 0:
+                        return False
+                    self._condition.wait(timeout=remaining)
+                self._writer_active = True
+                return True
+            finally:
+                self._writers_waiting -= 1
+
+    def release_write(self):
+        """Release a write lock."""
+        with self._condition:
+            self._writer_active = False
+            self._condition.notify_all()
+
+    @contextmanager
+    def read_lock(self, timeout: Optional[float] = None):
+        """Context manager for read lock with timeout.
+
+        Args:
+            timeout: Timeout in seconds. None means wait forever.
+        """
+        if not self.acquire_read(timeout):
+            raise RWLockTimeoutError("Failed to acquire read lock within timeout")
+        try:
+            yield
+        finally:
+            self.release_read()
+
+    @contextmanager
+    def write_lock(self, timeout: Optional[float] = None):
+        """Context manager for write lock with timeout.
+
+        Args:
+            timeout: Timeout in seconds. None means wait forever.
+        """
+        if not self.acquire_write(timeout):
+            raise RWLockTimeoutError("Failed to acquire write lock within timeout")
+        try:
+            yield
+        finally:
+            self.release_write()
+
+
+class FastLockWithTimeout:
+    """
+    A fast lock with timeout support for WorkerNode.
+    Optimized for high frequency operations on small critical sections.
+    Uses non-blocking fast path for better performance.
+
+    Note: This lock is NOT reentrant.
+    """
+
+    __slots__ = ("_lock",)
+
+    def __init__(self):
+        self._lock = threading.Lock()
+
+    def acquire(self, timeout: Optional[float] = None) -> bool:
+        """Acquire the lock with optional timeout."""
+        if timeout is None:
+            return self._lock.acquire()
+        return self._lock.acquire(timeout=timeout)
+
+    def release(self):
+        """Release the lock."""
+        self._lock.release()
+
+    def __enter__(self):
+        # Fast path: try non-blocking acquire first (no context switch overhead)
+        if self._lock.acquire(blocking=False):
+            return self
+        # Slow path: reduced timeout for faster failure detection
+        if not self._lock.acquire(timeout=10):  # 10s timeout
+            # TODO(baoloongmao): Mark as operation failed for metrics
+            #  and schedule full sync
+            raise RWLockTimeoutError("Failed to acquire WorkerNode lock within 10s")
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._lock.release()
diff --git a/lmcache/v1/cache_controller/message.py b/lmcache/v1/cache_controller/message.py
new file mode 100644
index 0000000..d4d68dc
--- /dev/null
+++ b/lmcache/v1/cache_controller/message.py
@@ -0,0 +1,828 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List, Optional, Tuple, Union
+
+# Third Party
+import msgspec
+
+# First Party
+from lmcache.v1.cache_controller.commands.base import HeartbeatCommand
+from lmcache.v1.cache_controller.commands.full_sync import FullSyncCommand
+
+# Type alias for all command types - msgspec needs Union for tagged unions
+AnyCommand = Union[FullSyncCommand, HeartbeatCommand]
+
+
+class MsgBase(msgspec.Struct, tag=True):  # type: ignore
+    """Base class for all messages"""
+
+    def describe(self) -> str:
+        return ""
+
+
+# NOTE: The additional layer of abstraction is to
+# differentiate among
+# (1) WorkerMsg: push-pull (lmcache->controller)
+# (2) WorkerReqMsg: req-reply (lmcache->controller)
+# (3) ControlMessage: req-reply (controller->lmcache)
+# (4) OrchMsg: req-reply (ochestrator->controller)
+
+
+"""Message from LMCache to Controller"""
+
+
+class WorkerMsg(MsgBase):
+    """Message between LMCache and Controller"""
+
+    def describe(self) -> str:
+        return ""
+
+
+"""Worker Request (requiring a reply) Message from LMCache to Controller"""
+
+
+class WorkerReqMsg(MsgBase):
+    def describe(self) -> str:
+        return ""
+
+
+class RegisterMsg(WorkerReqMsg):
+    """Message for Registration (REQ-REP mode)"""
+
+    instance_id: str
+    worker_id: int
+    ip: str
+    port: int
+    # URL for actual KV cache transfer, only useful when p2p is enabled
+    peer_init_url: Optional[str]
+
+    def describe(self) -> str:
+        return (
+            f"Registering instance {self.instance_id}, "
+            f"worker {self.worker_id} "
+            f"at {self.ip}:{self.port}"
+            f" with peer init URL {self.peer_init_url}"
+        )
+
+
+class DeRegisterMsg(WorkerMsg):
+    """Message for Deregistration"""
+
+    instance_id: str
+    worker_id: int
+    ip: str
+    port: int
+
+    def describe(self) -> str:
+        return (
+            f"Deregistering instance {self.instance_id}, "
+            f"worker {self.worker_id} "
+            f"at {self.ip}:{self.port}"
+        )
+
+
+class KVOperationMsg(WorkerMsg):
+    """Base class for KV operation messages (admit/evict) with full context"""
+
+    instance_id: str
+    worker_id: int
+    key: int
+    location: str
+    seq_num: int = 0
+
+
+class KVAdmitMsg(KVOperationMsg):
+    """Message for KV chunk admission"""
+
+    def describe(self) -> str:
+        return f"kv_admit {self.key} to {self.instance_id}"
+
+
+class KVEvictMsg(KVOperationMsg):
+    """Message for KV chunk eviction"""
+
+    def describe(self) -> str:
+        return f"kv_evict {self.key} from {self.instance_id}"
+
+
+@dataclass
+class WorkerInfo:
+    """Information about a worker for external API consumption."""
+
+    instance_id: str
+    worker_id: int
+    ip: str
+    port: int
+    peer_init_url: Optional[str]
+    registration_time: float
+    last_heartbeat_time: float
+
+
+class OpType(Enum):
+    """Enum for KV operation types"""
+
+    ADMIT = "admit"
+    EVICT = "evict"
+
+
+class KVOpEvent(msgspec.Struct):
+    """Lightweight KV operation event for queue storage (without common fields)"""
+
+    op_type: OpType
+    key: int
+    seq_num: int
+
+
+class BatchedKVOperationMsg(WorkerMsg):
+    """Batched KV operation message with common fields and lightweight operations
+
+    Design: Common fields (instance_id, worker_id, location) are stored once
+    at the batch level, while individual operations only contain the varying
+    fields (op_type, key, seq_num). This reduces memory and network overhead.
+    """
+
+    instance_id: str
+    worker_id: int
+    location: str
+    operations: list[KVOpEvent]
+
+    def describe(self) -> str:
+        return (
+            f"Batched KV operations with {len(self.operations)} messages "
+            f"from {self.instance_id}:{self.worker_id}"
+        )
+
+
+# ============= Full Sync Messages (PUSH mode) =============
+
+
+class FullSyncBatchMsg(WorkerMsg):
+    """Full sync batch message (PUSH mode, no confirmation needed)
+
+    Used to send a batch of chunk hashes during full sync.
+    """
+
+    instance_id: str
+    worker_id: int
+    location: str
+    sync_id: str
+    batch_id: int  # Current batch number (0-indexed)
+    keys: list[int]  # List of chunk_hash in this batch
+
+    def describe(self) -> str:
+        return (
+            f"FullSyncBatch sync_id={self.sync_id} batch_id={self.batch_id} "
+            f"keys_count={len(self.keys)} from {self.instance_id}:{self.worker_id}"
+        )
+
+
+class FullSyncEndMsg(WorkerMsg):
+    """Full sync end message (PUSH mode)
+
+    Sent after all batches are sent to signal completion.
+    """
+
+    instance_id: str
+    worker_id: int
+    location: str
+    sync_id: str
+    actual_total_keys: int  # Actual total keys sent (for verification)
+
+    def describe(self) -> str:
+        return (
+            f"FullSyncEnd sync_id={self.sync_id} "
+            f"total_keys={self.actual_total_keys} from "
+            f"{self.instance_id}:{self.worker_id}"
+        )
+
+
+class HeartbeatMsg(WorkerReqMsg):
+    """Message for heartbeat (REQ-REP mode), include register info for re-register"""
+
+    instance_id: str
+    worker_id: int
+    ip: str
+    port: int
+    peer_init_url: Optional[str]
+
+    def describe(self) -> str:
+        return f"Heartbeat from instance {self.instance_id}, worker {self.worker_id}"
+
+
+class BatchedP2PLookupMsg(WorkerReqMsg):
+    """Batched P2P lookup message"""
+
+    hashes: list[int]
+    instance_id: str
+    worker_id: int  # TP rank
+
+    def describe(self) -> str:
+        return (
+            f"Batched P2P lookup for {len(self.hashes)} keys from "
+            f"instance id {self.instance_id} and "
+            f"worker id {self.worker_id}"
+        )
+
+
+class FullSyncStartMsg(WorkerReqMsg):
+    """Full sync start message (REQ-REP mode, needs confirmation)
+
+    Sent before starting full sync to notify controller and get confirmation.
+    """
+
+    instance_id: str
+    worker_id: int
+    location: str
+    sync_id: str  # Sync session ID
+    total_keys: int  # Expected total key count
+    batch_count: int  # Expected batch count
+
+    def describe(self) -> str:
+        return (
+            f"FullSyncStart sync_id={self.sync_id} "
+            f"total_keys={self.total_keys} batches={self.batch_count} "
+            f"from {self.instance_id}:{self.worker_id}"
+        )
+
+
+class FullSyncStatusMsg(WorkerReqMsg):
+    """Full sync status query message (REQ-REP mode)
+
+    Used to query sync progress and check if freeze mode can be exited.
+    """
+
+    instance_id: str
+    worker_id: int
+    sync_id: str
+
+    def describe(self) -> str:
+        return (
+            f"FullSyncStatus query sync_id={self.sync_id} "
+            f"from {self.instance_id}:{self.worker_id}"
+        )
+
+
+"""Worker Request Return Message from Controller back to LMCache"""
+
+
+class WorkerReqRetMsg(MsgBase):
+    def describe(self) -> str:
+        return ""
+
+
+class RegisterRetMsg(WorkerReqRetMsg):
+    """Register response message with controller configuration
+
+    Returns configuration information that the worker needs for initialization,
+    such as dedicated heartbeat URL.
+    """
+
+    # Extra configuration from controller to worker
+    # e.g., {"heartbeat_url": "tcp://...:8082"}
+    extra_config: dict[str, str] = msgspec.field(default_factory=dict)
+
+    def describe(self) -> str:
+        return f"RegisterRet extra_config={self.extra_config}"
+
+
+class HeartbeatRetMsg(WorkerReqRetMsg):
+    """Heartbeat response message with optional commands
+
+    The controller can use this to send commands to workers through
+    the heartbeat mechanism. This provides a general-purpose way to
+    trigger actions on workers without adding new message types.
+
+    The commands field uses msgspec's tagged union for polymorphic
+    serialization - each command subclass is identified by its tag.
+    Commands are executed sequentially by the worker.
+    """
+
+    commands: List[AnyCommand] = []
+
+    def describe(self) -> str:
+        if not self.commands:
+            return "HeartbeatRet (no commands)"
+        cmd_descs = [cmd.describe() for cmd in self.commands]
+        return f"HeartbeatRet commands=[{', '.join(cmd_descs)}]"
+
+    def has_commands(self) -> bool:
+        """Check if there are commands to execute"""
+        return len(self.commands) > 0
+
+
+class BatchedP2PLookupRetMsg(WorkerReqRetMsg):
+    """Batched P2P lookup return message"""
+
+    # (instance_id, location, num_hit_chunks, peer_init_url)
+    layout_info: list[tuple[str, str, int, str]]
+
+    def describe(self) -> str:
+        return f"The layout info is {self.layout_info}"
+
+
+class FullSyncStartRetMsg(WorkerReqRetMsg):
+    """Full sync start response message"""
+
+    sync_id: str
+    accepted: bool  # Whether sync request is accepted
+    error_msg: Optional[str] = None
+
+    def describe(self) -> str:
+        return f"FullSyncStartRet sync_id={self.sync_id} accepted={self.accepted}"
+
+
+class FullSyncStatusRetMsg(WorkerReqRetMsg):
+    """Full sync status response message"""
+
+    sync_id: str
+    is_complete: bool  # Whether current worker sync is complete
+    global_progress: float  # Global progress (0.0 - 1.0)
+    can_exit_freeze: bool  # Whether freeze mode can be exited
+    missing_batches: list[int] = []  # List of missing batch IDs that need to be resent
+
+    def describe(self) -> str:
+        missing_info = (
+            f" missing={self.missing_batches}" if self.missing_batches else ""
+        )
+        return (
+            f"FullSyncStatusRet sync_id={self.sync_id} "
+            f"complete={self.is_complete} progress={self.global_progress:.2%} "
+            f"can_exit_freeze={self.can_exit_freeze}{missing_info}"
+        )
+
+
+"""Control Message from Controller to LMCache"""
+
+
+class ControlMsg(MsgBase):
+    def describe(self) -> str:
+        return ""
+
+
+class ClearWorkerMsg(ControlMsg):
+    """Clear message for a single lmcache worker"""
+
+    worker_event_id: str
+    location: str
+
+    def describe(self) -> str:
+        return f"Clear tokens in location {self.location}"
+
+
+class PinWorkerMsg(ControlMsg):
+    """Pin message for a single lmcache worker"""
+
+    worker_event_id: str
+    location: str
+    tokens: list[int]
+
+    def describe(self) -> str:
+        return f"Pin tokens {self.tokens} in location {self.location}"
+
+
+class CompressWorkerMsg(ControlMsg):
+    """Compress message for a single lmcache worker"""
+
+    worker_event_id: str
+    method: str
+    location: str
+    tokens: Optional[list[int]] = None
+
+    def describe(self) -> str:
+        return (
+            f"Compress tokens {self.tokens} in "
+            f"locations {self.location} with "
+            f"method {self.method}"
+        )
+
+
+class DecompressWorkerMsg(ControlMsg):
+    """Decompress message for a single lmcache worker"""
+
+    worker_event_id: str
+    method: str
+    location: str
+    tokens: Optional[list[int]] = None
+
+    def describe(self) -> str:
+        return (
+            f"Decompress tokens {self.tokens} in "
+            f"locations {self.location} with "
+            f"method {self.method}"
+        )
+
+
+class MoveWorkerMsg(ControlMsg):
+    """Move message for a single lmcache worker"""
+
+    worker_event_id: str
+    old_position: str  # location (storage backend name)
+    new_position: Tuple[str, str]  # (target_url, location (storage backend name) )
+    tokens: Optional[list[int]] = None
+    copy: Optional[bool] = True
+
+    def describe(self) -> str:
+        return (
+            f"Move tokens {self.tokens} from {self.old_position} to {self.new_position}"
+        )
+
+
+class HealthWorkerMsg(ControlMsg):
+    """Health message for a single lmcache worker"""
+
+    worker_event_id: str
+
+    def describe(self) -> str:
+        return "Health check"
+
+
+class CheckFinishWorkerMsg(ControlMsg):
+    """Check finish message for a single lmcache worker"""
+
+    worker_event_id: str
+
+    def describe(self) -> str:
+        return f"Checking finish for worker event {self.worker_event_id}"
+
+
+class ControlRetMsg(MsgBase):
+    """Return message from LMCache to Controller"""
+
+    def describe(self) -> str:
+        return ""
+
+
+class ClearWorkerRetMsg(ControlRetMsg):
+    """Return message for a ClearWorkerMsg"""
+
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Number of cleared tokens: {self.num_tokens}"
+
+
+class PinWorkerRetMsg(ControlRetMsg):
+    """Pin return message for a single lmcache worker"""
+
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Number of pinned tokens: {self.num_tokens}"
+
+
+class CompressWorkerRetMsg(ControlRetMsg):
+    """Compress return message for a single lmcache worker"""
+
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Compress success: {self.num_tokens}"
+
+
+class DecompressWorkerRetMsg(ControlRetMsg):
+    """Decompress return message for a single lmcache worker"""
+
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Decompress success: {self.num_tokens}"
+
+
+class MoveWorkerRetMsg(ControlRetMsg):
+    """Move return message for a single lmcache worker"""
+
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Moving {self.num_tokens} tokens"
+
+
+class HealthWorkerRetMsg(ControlRetMsg):
+    """Health return message for a single lmcache worker"""
+
+    error_code: int
+
+    def describe(self) -> str:
+        return f"Health check error code: {self.error_code}"
+
+
+class CheckFinishWorkerRetMsg(ControlRetMsg):
+    """Check finish return message for a single lmcache worker"""
+
+    status: str
+
+    def describe(self) -> str:
+        return f"Check finish status: {self.status}"
+
+
+"""Orchestration Message from Ochestrator to LMCache"""
+
+
+class OrchMsg(MsgBase):
+    """Message from Ochestrator to Controller"""
+
+    def describe(self) -> str:
+        return ""
+
+
+class QueryInstMsg(OrchMsg):
+    """Query instance message"""
+
+    event_id: str
+    ip: str
+
+    def describe(self) -> str:
+        return f"Query instance id of ip {self.ip}"
+
+
+class LookupMsg(OrchMsg):
+    """Lookup message"""
+
+    event_id: str
+    tokens: list[int]
+
+    def describe(self) -> str:
+        return f"Lookup tokens {self.tokens}"
+
+
+class ClearMsg(OrchMsg):
+    """Clear message"""
+
+    event_id: str
+    instance_id: str
+    location: str
+
+    def describe(self) -> str:
+        return (
+            f"Clear tokens in instance {self.instance_id} and locations {self.location}"
+        )
+
+
+class PinMsg(OrchMsg):
+    """Pin message"""
+
+    event_id: str
+    instance_id: str
+    location: str
+    tokens: list[int]
+
+    def describe(self) -> str:
+        return (
+            f"Pin tokens {self.tokens} in instance "
+            f"{self.instance_id} and "
+            f"location {self.location}"
+        )
+
+
+class CompressMsg(OrchMsg):
+    """Compress message"""
+
+    event_id: str
+    instance_id: str
+    method: str
+    location: str
+    tokens: Optional[list[int]] = None  # `None` means compress all tokens
+
+    def describe(self) -> str:
+        return (
+            f"Compress tokens {self.tokens} in instance "
+            f"{self.instance_id} and "
+            f"locations {self.location} with "
+            f"method {self.method}"
+        )
+
+
+class DecompressMsg(OrchMsg):
+    """Decompress message"""
+
+    event_id: str
+    instance_id: str
+    method: str
+    location: str
+    tokens: Optional[list[int]] = None  # `None` means compress all tokens
+
+    def describe(self) -> str:
+        return (
+            f"Decompress tokens {self.tokens} in instance "
+            f"{self.instance_id} and "
+            f"locations {self.location} with "
+            f"method {self.method}"
+        )
+
+
+class MoveMsg(OrchMsg):
+    """Move message"""
+
+    event_id: str
+    old_position: Tuple[str, str]
+    new_position: Tuple[str, str]
+    tokens: Optional[list[int]] = None
+    copy: Optional[bool] = False
+
+    def describe(self) -> str:
+        return (
+            f"Move tokens {self.tokens} from {self.old_position} to {self.new_position}"
+        )
+
+
+class HealthMsg(OrchMsg):
+    """Health message"""
+
+    event_id: str
+    instance_id: str
+
+    def describe(self) -> str:
+        return f"Health check for instance {self.instance_id}"
+
+
+class CheckFinishMsg(OrchMsg):
+    """Check finish message"""
+
+    event_id: str
+
+    def describe(self) -> str:
+        return f"Checking finish for event {self.event_id}"
+
+
+class QueryWorkerInfoMsg(OrchMsg):
+    """Query worker info message"""
+
+    event_id: str
+    instance_id: str
+    worker_ids: Optional[list[int]]
+
+    def describe(self) -> str:
+        return f"Query worker info of {self.instance_id} : {self.worker_ids}"
+
+
+class OrchRetMsg(MsgBase):
+    """Return message from Controller to Ochestrator"""
+
+    def describe(self) -> str:
+        return ""
+
+
+class QueryInstRetMsg(OrchRetMsg):
+    """Query instance return message"""
+
+    event_id: str
+    instance_id: Optional[str]
+
+    def describe(self) -> str:
+        return f"The instance id is {self.instance_id}"
+
+
+class LookupRetMsg(OrchRetMsg):
+    """Lookup return message"""
+
+    event_id: str
+    layout_info: Dict[str, Tuple[str, int]]
+
+    def describe(self) -> str:
+        return f"The layout info is {self.layout_info}"
+
+
+class ClearRetMsg(OrchRetMsg):
+    """Clear return message"""
+
+    event_id: str
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Number of cleared tokens: {self.num_tokens}"
+
+
+class PinRetMsg(OrchRetMsg):
+    """Pin return message"""
+
+    event_id: str
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Number of pinned tokens: {self.num_tokens}"
+
+
+class CompressRetMsg(OrchRetMsg):
+    """Compress return message"""
+
+    event_id: str
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Compressed {self.num_tokens} tokens"
+
+
+class DecompressRetMsg(OrchRetMsg):
+    """Decompress return message"""
+
+    event_id: str
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Decompressed {self.num_tokens} tokens"
+
+
+class MoveRetMsg(OrchRetMsg):
+    """Move return message"""
+
+    event_id: str
+    num_tokens: int
+
+    def describe(self) -> str:
+        return f"Moving {self.num_tokens} tokens"
+
+
+class HealthRetMsg(OrchRetMsg):
+    """Health return message"""
+
+    event_id: str
+    # worker_id -> error_code
+    error_codes: Dict[int, int]
+
+    def describe(self) -> str:
+        return f"error_codes: {self.error_codes}"
+
+
+class CheckFinishRetMsg(OrchRetMsg):
+    """Check finish return message"""
+
+    status: str
+
+    def describe(self) -> str:
+        return f"Event status: {self.status}"
+
+
+class QueryWorkerInfoRetMsg(OrchRetMsg):
+    """Query worker info return message"""
+
+    event_id: str
+    worker_infos: list[WorkerInfo]
+
+    def describe(self) -> str:
+        return f"worker infos: {self.worker_infos}"
+
+
+class ErrorMsg(WorkerReqRetMsg):
+    """Control Error Message"""
+
+    error: str
+
+    def describe(self) -> str:
+        return f"Error: {self.error}"
+
+
+Msg = Union[
+    RegisterMsg,
+    RegisterRetMsg,
+    DeRegisterMsg,
+    KVAdmitMsg,
+    KVEvictMsg,
+    BatchedKVOperationMsg,
+    ClearWorkerMsg,
+    ClearWorkerRetMsg,
+    PinWorkerMsg,
+    PinWorkerRetMsg,
+    CompressWorkerMsg,
+    CompressWorkerRetMsg,
+    DecompressWorkerMsg,
+    DecompressWorkerRetMsg,
+    MoveWorkerMsg,
+    MoveWorkerRetMsg,
+    HealthWorkerMsg,
+    HealthWorkerRetMsg,
+    CheckFinishWorkerMsg,
+    CheckFinishWorkerRetMsg,
+    LookupMsg,
+    LookupRetMsg,
+    ClearMsg,
+    ClearRetMsg,
+    PinMsg,
+    PinRetMsg,
+    CompressMsg,
+    CompressRetMsg,
+    DecompressMsg,
+    DecompressRetMsg,
+    MoveMsg,
+    MoveRetMsg,
+    HealthMsg,
+    HealthRetMsg,
+    CheckFinishMsg,
+    CheckFinishRetMsg,
+    ErrorMsg,
+    QueryInstMsg,
+    QueryInstRetMsg,
+    HeartbeatMsg,
+    HeartbeatRetMsg,
+    BatchedP2PLookupMsg,
+    BatchedP2PLookupRetMsg,
+    QueryWorkerInfoMsg,
+    QueryWorkerInfoRetMsg,
+    FullSyncStartMsg,
+    FullSyncStartRetMsg,
+    FullSyncBatchMsg,
+    FullSyncEndMsg,
+    FullSyncStatusMsg,
+    FullSyncStatusRetMsg,
+]
diff --git a/lmcache/v1/cache_controller/observability.py b/lmcache/v1/cache_controller/observability.py
new file mode 100644
index 0000000..ddb073e
--- /dev/null
+++ b/lmcache/v1/cache_controller/observability.py
@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from enum import Enum
+from typing import Optional
+
+# Third Party
+from prometheus_client import REGISTRY
+import prometheus_client
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class SocketType(Enum):
+    """Enum for socket types to ensure type safety."""
+
+    PULL = "pull"
+    REPLY = "reply"
+
+
+class PrometheusLogger:
+    """
+    Prometheus logger for cache controller metrics.
+    Provides dynamic metrics for monitoring KV pool and worker registration.
+    """
+
+    _instance = None
+    _gauge_cls = prometheus_client.Gauge
+
+    def __init__(self, labels: dict):
+        self.labels = labels
+        labelnames = list(self.labels.keys())
+
+        # Dynamic metrics for cache controller
+        self._init_dynamic_metrics(labelnames)
+
+    def _init_dynamic_metrics(self, labelnames):
+        """
+        Initialize dynamic metrics that will be updated by lambda functions.
+        """
+        # KV Pool metrics
+        self.kv_pool_keys_count = self._gauge_cls(
+            name="lmcache:cache_controller_kv_pool_keys_count",
+            documentation="The number of keys in the KV pool",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        # Registration Controller metrics
+        self.registered_workers_count = self._gauge_cls(
+            name="lmcache:cache_controller_registered_workers_count",
+            documentation="The total number of registered workers",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        # Socket message count metrics
+        self.pull_socket_message_count = self._gauge_cls(
+            name="lmcache:cache_controller_pull_socket_message_count",
+            documentation="The total number of messages received on PULL socket",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        self.reply_socket_message_count = self._gauge_cls(
+            name="lmcache:cache_controller_reply_socket_message_count",
+            documentation="The total number of messages received on REPLY socket",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+
+        # Socket queue/backlog metrics
+        self.pull_socket_has_pending = self._gauge_cls(
+            name="lmcache:cache_controller_pull_socket_has_pending",
+            documentation="Whether PULL socket has pending messages (1=yes, 0=no)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        self.reply_socket_has_pending = self._gauge_cls(
+            name="lmcache:cache_controller_reply_socket_has_pending",
+            documentation="Whether REPLY socket has pending messages (1=yes, 0=no)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+
+        # Active request metrics
+        self.pull_socket_active_requests = self._gauge_cls(
+            name="lmcache:cache_controller_pull_socket_active_requests",
+            documentation="Number of requests being processed from PULL socket",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        self.reply_socket_active_requests = self._gauge_cls(
+            name="lmcache:cache_controller_reply_socket_active_requests",
+            documentation="Number of requests being processed from REPLY socket",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+
+        # Sequence number discontinuity metrics
+        self.kv_op_seq_discontinuity_count = self._gauge_cls(
+            name="lmcache:cache_controller_kv_op_seq_discontinuity_count",
+            documentation="Total count of KV operation sequence number discontinuities",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+
+        # Full sync metrics
+        self.full_sync_workers_syncing = self._gauge_cls(
+            name="lmcache:cache_controller_full_sync_workers_syncing",
+            documentation="Number of workers currently in full sync",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        self.full_sync_workers_completed = self._gauge_cls(
+            name="lmcache:cache_controller_full_sync_workers_completed",
+            documentation="Number of workers that have completed full sync",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        self.full_sync_global_progress = self._gauge_cls(
+            name="lmcache:cache_controller_full_sync_global_progress",
+            documentation="Global full sync progress (0.0 to 1.0)",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+        self.full_sync_missing_batches_total = self._gauge_cls(
+            name="lmcache:cache_controller_full_sync_missing_batches_total",
+            documentation="Total count of missing batches across all syncing workers",
+            labelnames=labelnames,
+            multiprocess_mode="livemostrecent",
+        ).labels(**self.labels)
+
+    @staticmethod
+    def GetOrCreate(
+        labels: dict,
+    ) -> "PrometheusLogger":
+        if PrometheusLogger._instance is None:
+            PrometheusLogger._instance = PrometheusLogger(labels)
+        if PrometheusLogger._instance.labels != labels:
+            logger.error(
+                "CacheControllerPrometheusLogger instance already created with "
+                "different metadata. This should not happen except in test"
+            )
+        return PrometheusLogger._instance
+
+    @staticmethod
+    def GetInstance() -> "PrometheusLogger":
+        assert PrometheusLogger._instance is not None, (
+            "CacheControllerPrometheusLogger instance not created yet"
+        )
+        return PrometheusLogger._instance
+
+    @staticmethod
+    def GetInstanceOrNone() -> Optional["PrometheusLogger"]:
+        """
+        Returns the singleton instance of CacheControllerPrometheusLogger if it exists,
+        otherwise returns None.
+        """
+        return PrometheusLogger._instance
+
+    @staticmethod
+    def DestroyInstance():
+        PrometheusLogger._instance = None
+
+    @staticmethod
+    def unregister_all_metrics():
+        collectors = list(REGISTRY._collector_to_names.keys())
+        for collector in collectors:
+            try:
+                REGISTRY.unregister(collector)
+            except KeyError:
+                pass
+
+
+class SocketMetricsContext:
+    """Context manager for socket message counting and error handling."""
+
+    def __init__(self, manager, socket_type: SocketType, message_count: int = 1):
+        self.manager = manager
+        self.socket_type = socket_type
+        self.message_count = message_count
+        self.counter_attr = f"{socket_type.value}_socket_message_count"
+        self.active_attr = f"{socket_type.value}_socket_active_requests"
+
+    def __enter__(self):
+        setattr(
+            self.manager,
+            self.counter_attr,
+            getattr(self.manager, self.counter_attr) + self.message_count,
+        )
+        setattr(
+            self.manager,
+            self.active_attr,
+            getattr(self.manager, self.active_attr) + self.message_count,
+        )
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        setattr(
+            self.manager,
+            self.active_attr,
+            getattr(self.manager, self.active_attr) - self.message_count,
+        )
+        if exc_type is not None:
+            logger.error(
+                "Controller Manager error", exc_info=(exc_type, exc_val, exc_tb)
+            )
+        return False
diff --git a/lmcache/v1/cache_controller/utils.py b/lmcache/v1/cache_controller/utils.py
new file mode 100644
index 0000000..038404c
--- /dev/null
+++ b/lmcache/v1/cache_controller/utils.py
@@ -0,0 +1,679 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Callable, NamedTuple, Optional, Set
+import threading
+
+# Third Party
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.locks import FastLockWithTimeout, RWLockWithTimeout
+from lmcache.v1.cache_controller.message import BatchedKVOperationMsg, WorkerInfo
+from lmcache.v1.utils.cache_utils import TTLListCache
+
+logger = init_logger(__name__)
+
+
+class KVChunkInfo(NamedTuple):
+    """
+    Represents the location information of a KV chunk in the cluster.
+    This class is immutable and can be used as a dictionary key.
+    """
+
+    instance_id: str
+    worker_id: int
+    location: str
+
+
+class FullSyncState(Enum):
+    """State of full sync for a worker"""
+
+    IDLE = "idle"  # Not in sync
+    SYNCING = "syncing"  # Sync in progress
+    COMPLETED = "completed"  # Sync completed
+    FAILED = "failed"  # Sync failed/timeout
+
+
+@dataclass
+class WorkerSyncInfo:
+    """Information about a worker's sync state"""
+
+    sync_id: str
+    state: FullSyncState
+    start_time: float
+    expected_total_keys: int
+    expected_batch_count: int
+    received_batches: Set[int] = field(default_factory=set)
+    received_keys_count: int = 0
+    last_activity_time: float = 0.0
+
+    def __post_init__(self):
+        if self.last_activity_time == 0.0:
+            self.last_activity_time = self.start_time
+
+
+@dataclass
+class WorkerNode:
+    """
+    Represents a single worker with all its associated metadata.
+    """
+
+    worker_id: int
+    ip: str
+    port: int
+    peer_init_url: Optional[str]
+    socket: Optional[zmq.asyncio.Socket]
+    registration_time: float
+    last_heartbeat_time: float
+    # Guarded by _lock
+    seq_tracker: dict[str, int] = field(default_factory=dict)  # location -> seq_num
+    kv_store: dict[str, set[int]] = field(
+        default_factory=dict
+    )  # location -> set[chunk_hash]
+    sync_info: Optional[WorkerSyncInfo] = None  # Full sync state
+
+    def __post_init__(self):
+        # Fast lock with timeout for WorkerNode operations
+        self._lock = FastLockWithTimeout()
+
+    def handle_batched_kv_operations(
+        self,
+        msg: BatchedKVOperationMsg,
+        on_seq_num_out_of_order: Optional[Callable[[], None]] = None,
+        is_full_sync: bool = False,
+    ) -> bool:
+        """
+        Handle batched KV operations with single lock acquisition.
+        Logs warning and calls callback if sequence out of order is detected.
+
+        Args:
+            msg: The batched KV operation message.
+            on_seq_num_out_of_order: Callback when sequence out of order detected.
+            is_full_sync: If True, this is a full sync batch operation.
+                         During full sync, sequence check is skipped.
+                         When worker is syncing, non-full-sync operations are rejected.
+
+        Returns:
+            True if operations were processed, False if rejected
+            (e.g., during syncing when is_full_sync=False).
+        """
+        seq_warning: Optional[tuple[int, int, int]] = None
+        with self._lock:
+            # During syncing, reject non-full-sync operations
+            if (
+                self.sync_info is not None
+                and self.sync_info.state == FullSyncState.SYNCING
+                and not is_full_sync
+            ):
+                return False
+
+            location = msg.location
+
+            if location not in self.kv_store:
+                self.kv_store[location] = set()
+
+            for op in msg.operations:
+                # Apply operation first, then check sequence
+                # (sequence check is skipped during full sync)
+                if op.op_type.value == "admit":
+                    self.kv_store[location].add(op.key)
+                elif op.op_type.value == "evict":
+                    self.kv_store[location].discard(op.key)
+                else:
+                    logger.error(f"Unknown op_type: {op.op_type}")
+
+                # Skip sequence check during full sync
+                if is_full_sync:
+                    continue
+
+                # Sequence check
+                last_seq_num = self.seq_tracker.get(location)
+                if last_seq_num is not None:
+                    expected_seq = last_seq_num + 1
+                    if op.seq_num != expected_seq and seq_warning is None:
+                        seq_warning = (
+                            expected_seq,
+                            op.seq_num,
+                            op.seq_num - expected_seq,
+                        )
+                self.seq_tracker[location] = op.seq_num
+
+            # Clean up empty set
+            if not self.kv_store[location]:
+                self.kv_store.pop(location, None)
+
+        # Log warning and call callback outside lock
+        if seq_warning is not None:
+            if on_seq_num_out_of_order is not None:
+                on_seq_num_out_of_order()
+            logger.warning(
+                "KV batch sequence out of order detected: "
+                "key=%s, expected_seq=%s, actual_seq=%s, gap=%s",
+                (msg.instance_id, msg.worker_id, msg.location),
+                seq_warning[0],
+                seq_warning[1],
+                seq_warning[2],
+            )
+        return True
+
+    def has_kv(self, location: str, key: int) -> bool:
+        """Check if a KV chunk exists in this worker."""
+        with self._lock:
+            return location in self.kv_store and key in self.kv_store[location]
+
+    def get_kv_keys(self, location: str) -> set[int]:
+        """Get all keys for a location."""
+        with self._lock:
+            keys = self.kv_store.get(location)
+            if keys is None:
+                return set()
+            # Return a shallow copy for thread safety
+            return set(keys)
+
+    def clear_kv_store(self) -> None:
+        """Clear all KV data for this worker."""
+        with self._lock:
+            self.kv_store.clear()
+            self.seq_tracker.clear()
+
+    def get_kv_count(self) -> int:
+        """Get total count of KV chunks."""
+        with self._lock:
+            return sum(len(keys) for keys in self.kv_store.values())
+
+    def update_seq_num(self, location: str, seq_num: int) -> None:
+        """Update sequence number for a location."""
+        with self._lock:
+            self.seq_tracker[location] = seq_num
+
+    def get_seq_num(self, location: str) -> Optional[int]:
+        """Get sequence number for a location."""
+        with self._lock:
+            return self.seq_tracker.get(location)
+
+    def find_key(
+        self, key: int
+    ) -> Optional[tuple[KVChunkInfo, Optional[str], set[int]]]:
+        """
+        Find a key in this worker's kv_store.
+        Returns: (KVChunkInfo, peer_init_url, keys) if found, None otherwise.
+        KVChunkInfo will have instance_id="" since WorkerNode doesn't know
+        its instance.
+        """
+        with self._lock:
+            for location, keys in self.kv_store.items():
+                if key in keys:
+                    # WorkerNode doesn't know its instance_id, so we leave it empty
+                    # The caller should fill in the instance_id
+                    return (
+                        KVChunkInfo("", self.worker_id, location),
+                        self.peer_init_url,
+                        keys,
+                    )
+        return None
+
+    def find_key_simple(self, key: int) -> Optional[KVChunkInfo]:
+        """
+        Find a key in this worker's kv_store, returning only KVChunkInfo.
+        KVChunkInfo will have instance_id="" since WorkerNode doesn't know
+        its instance.
+        """
+        with self._lock:
+            for location, keys in self.kv_store.items():
+                if key in keys:
+                    return KVChunkInfo("", self.worker_id, location)
+        return None
+
+    def to_worker_info(self, instance_id: str) -> WorkerInfo:
+        """Convert to WorkerInfo for backward compatibility."""
+        # No need to lock here
+        return WorkerInfo(
+            instance_id=instance_id,
+            worker_id=self.worker_id,
+            ip=self.ip,
+            port=self.port,
+            peer_init_url=self.peer_init_url,
+            registration_time=self.registration_time,
+            last_heartbeat_time=self.last_heartbeat_time,
+        )
+
+
+@dataclass
+class InstanceNode:
+    """
+    Represents an instance with all its workers.
+    Tree structure: InstanceNode -> WorkerNode
+    Each InstanceNode has its own lock for thread-safe worker operations.
+    """
+
+    instance_id: str
+    # Guarded by _rwlock
+    workers: dict[int, WorkerNode] = field(
+        default_factory=dict
+    )  # worker_id -> WorkerNode
+
+    def __post_init__(self):
+        # RW lock for protecting workers dict access
+        self._rwlock = RWLockWithTimeout()
+
+    def add_worker(self, worker_node: WorkerNode) -> None:
+        """Add a worker to this instance."""
+        with self._rwlock.write_lock(timeout=10):
+            self.workers[worker_node.worker_id] = worker_node
+
+    def remove_worker(self, worker_id: int) -> Optional[WorkerNode]:
+        """Remove and return a worker from this instance."""
+        with self._rwlock.write_lock(timeout=10):
+            return self.workers.pop(worker_id, None)
+
+    def get_worker(self, worker_id: int) -> Optional[WorkerNode]:
+        """Get a worker by worker_id. Uses optimistic locking (lock-free read)."""
+        # Optimistic read: workers dict rarely changes
+        return self.workers.get(worker_id)
+
+    def get_worker_ids(self) -> list[int]:
+        """Get sorted list of worker IDs."""
+        # Snapshot keys to avoid RuntimeError if dict changes during iteration
+        return sorted(list(self.workers.keys()))
+
+    def has_workers(self) -> bool:
+        """Check if instance has any workers."""
+        # Optimistic read: workers dict rarely changes
+        return len(self.workers) > 0
+
+    def get_all_worker_infos(self) -> list[WorkerInfo]:
+        """Get WorkerInfo for all workers in this instance."""
+        # Snapshot values to avoid RuntimeError if dict changes during iteration
+        workers_snapshot = list(self.workers.values())
+        return [worker.to_worker_info(self.instance_id) for worker in workers_snapshot]
+
+    def find_key(
+        self, key: int
+    ) -> Optional[tuple[KVChunkInfo, Optional[str], set[int]]]:
+        """
+        Find a key in any worker within this instance.
+        Returns: (KVChunkInfo, peer_init_url, keys) if found, None otherwise.
+        """
+        # Snapshot workers to avoid RuntimeError if dict changes during iteration
+        workers_snapshot = list(self.workers.items())
+        for worker_id, worker_node in workers_snapshot:
+            if result := worker_node.find_key(key):
+                # Fill in the instance_id in KVChunkInfo
+                kv_info, peer_init_url, keys = result
+                return (
+                    KVChunkInfo(self.instance_id, worker_id, kv_info.location),
+                    peer_init_url,
+                    keys,
+                )
+        return None
+
+    def find_key_simple(self, key: int) -> Optional[KVChunkInfo]:
+        """
+        Find a key in any worker within this instance, returning only KVChunkInfo.
+        """
+        # Snapshot workers to avoid RuntimeError if dict changes during iteration
+        workers_snapshot = list(self.workers.items())
+        for worker_id, worker_node in workers_snapshot:
+            if kv_info := worker_node.find_key_simple(key):
+                return KVChunkInfo(self.instance_id, worker_id, kv_info.location)
+        return None
+
+    def has_worker_with_ip(self, ip: str) -> bool:
+        """
+        Check if any worker in this instance has the specified IP address.
+        """
+        # Snapshot workers to avoid RuntimeError if dict changes during iteration
+        return any(worker.ip == ip for worker in list(self.workers.values()))
+
+    def get_total_kv_count(self) -> int:
+        """
+        Get total count of KV chunks across all workers in this instance.
+        """
+        # Snapshot workers to avoid RuntimeError if dict changes during iteration
+        return sum(worker.get_kv_count() for worker in list(self.workers.values()))
+
+
+class RegistryTree:
+    """
+    Central registry managing the tree structure of instances and workers.
+    Structure: instance_id -> InstanceNode -> WorkerNode
+
+    Lock hierarchy (from coarse to fine):
+    1. RegistryTree._rwlock: protects instances dict access
+    2. InstanceNode._rwlock: protects workers dict access
+    3. WorkerNode._lock: protects kv_store and seq_tracker access
+
+    This fine-grained locking allows concurrent operations on different
+    instances/workers, improving throughput significantly.
+    """
+
+    def __init__(self):
+        # Guarded by _rwlock
+        # instance_id -> InstanceNode
+        self.instances: dict[str, InstanceNode] = {}
+        # RW lock only for protecting instances dict access
+        self._rwlock = RWLockWithTimeout()
+        # Atomic counter for sequence discontinuity (protected by _counter_lock)
+        self._seq_discontinuity_count = 0
+        self._counter_lock = threading.Lock()
+        # Cache for get_all_worker_infos (for Prometheus metrics)
+        self._worker_info_cache: TTLListCache[WorkerInfo] = TTLListCache[WorkerInfo]()
+        # Cache for get_all_worker_nodes (for FullSyncTracker and other use cases)
+        self._worker_node_cache: TTLListCache[tuple[str, WorkerNode]] = TTLListCache[
+            tuple[str, WorkerNode]
+        ]()
+
+    def get_seq_discontinuity_count(self) -> int:
+        """Get the count of sequence discontinuities (thread-safe)."""
+        # Lock-free read, no need for lock
+        return self._seq_discontinuity_count
+
+    def _incr_seq_discontinuity_count(self) -> None:
+        """Increment the sequence discontinuity counter (thread-safe)."""
+        with self._counter_lock:
+            self._seq_discontinuity_count += 1
+
+    def _get_or_create_instance(self, instance_id: str) -> InstanceNode:
+        """Get or create an instance node. Internal use only."""
+        # Optimistic read first: instances dict rarely changes
+        instance_node = self.instances.get(instance_id)
+        if instance_node is not None:
+            return instance_node
+
+        # Need to create, use write lock
+        with self._rwlock.write_lock(timeout=10):
+            # Double-check after acquiring write lock
+            instance_node = self.instances.get(instance_id)
+            if instance_node is None:
+                instance_node = InstanceNode(instance_id=instance_id)
+                self.instances[instance_id] = instance_node
+            return instance_node
+
+    def _get_instance(self, instance_id: str) -> Optional[InstanceNode]:
+        """Get an instance node. Uses optimistic locking (lock-free read)."""
+        # Optimistic read: instances dict rarely changes
+        return self.instances.get(instance_id)
+
+    def register_worker(
+        self,
+        instance_id: str,
+        worker_id: int,
+        ip: str,
+        port: int,
+        peer_init_url: Optional[str],
+        socket: zmq.asyncio.Socket,
+        registration_time: float,
+    ) -> WorkerNode:
+        """Register a new worker, creating instance if needed."""
+        # Get or create instance (locks instances dict)
+        instance_node = self._get_or_create_instance(instance_id)
+
+        # Create worker node
+        worker_node = WorkerNode(
+            worker_id=worker_id,
+            ip=ip,
+            port=port,
+            peer_init_url=peer_init_url,
+            socket=socket,
+            registration_time=registration_time,
+            last_heartbeat_time=registration_time,
+        )
+        # Add worker (locks workers dict in instance_node)
+        instance_node.add_worker(worker_node)
+        return worker_node
+
+    def deregister_worker(
+        self, instance_id: str, worker_id: int
+    ) -> Optional[WorkerNode]:
+        """Deregister a worker and clean up empty instances."""
+        instance_node = self._get_instance(instance_id)
+        if instance_node is None:
+            return None
+
+        # Remove worker (locks workers dict in instance_node)
+        worker_node = instance_node.remove_worker(worker_id)
+
+        # Clean up empty instance (need write lock on instances)
+        if not instance_node.has_workers():
+            # TODO(baoloongmao): Move timeout values to configuration
+            with self._rwlock.write_lock(timeout=100):
+                # Double-check after acquiring write lock
+                # Use pop to avoid KeyError if another thread already removed it
+                if not instance_node.has_workers() and instance_id in self.instances:
+                    self.instances.pop(instance_id, None)
+
+        return worker_node
+
+    def get_worker(self, instance_id: str, worker_id: int) -> Optional[WorkerNode]:
+        """Get a specific worker."""
+        instance_node = self._get_instance(instance_id)
+        if instance_node is None:
+            return None
+        return instance_node.get_worker(worker_id)
+
+    def get_instance(self, instance_id: str) -> Optional[InstanceNode]:
+        """Get an instance by instance_id."""
+        return self._get_instance(instance_id)
+
+    def get_instance_by_ip(self, ip: str) -> Optional[InstanceNode]:
+        """Get an instance by IP address. Returns first instance if multiple exist."""
+        # Snapshot to avoid RuntimeError if dict changes during iteration
+        for instance_node in list(self.instances.values()):
+            if instance_node.has_worker_with_ip(ip):
+                return instance_node
+        return None
+
+    def get_instances_by_ip(self, ip: str) -> list[InstanceNode]:
+        """Get all instances by IP address."""
+        # Snapshot to avoid RuntimeError if dict changes during iteration
+        result = []
+        for instance_node in list(self.instances.values()):
+            if instance_node.has_worker_with_ip(ip):
+                result.append(instance_node)
+        return result
+
+    def get_worker_ids(self, instance_id: str) -> list[int]:
+        """Get sorted list of worker IDs for an instance."""
+        instance_node = self._get_instance(instance_id)
+        if instance_node is None:
+            return []
+        return instance_node.get_worker_ids()
+
+    def get_all_worker_infos_cached(
+        self, timeout_seconds: Optional[float] = None
+    ) -> list[WorkerInfo]:
+        """Get WorkerInfo for all workers across all instances.
+
+        Args:
+            timeout_seconds: Cache timeout in seconds.
+                - If None (default): use the cache's default timeout.
+                - If 0: cache immediately expires, always get fresh data
+                  and update cache.
+                - If > 0: use cache with specified timeout.
+
+        Returns:
+            List of WorkerInfo, either from cache or fresh data
+        """
+        return self._worker_info_cache.get_cached(
+            lambda: self._get_all_worker_infos_fresh(), timeout_override=timeout_seconds
+        )
+
+    def _get_all_worker_infos_fresh(self) -> list[WorkerInfo]:
+        """Internal method to get fresh WorkerInfo without cache."""
+        # Snapshot to avoid RuntimeError if dict changes during iteration
+        result = []
+        for instance_node in list(self.instances.values()):
+            result.extend(instance_node.get_all_worker_infos())
+        return result
+
+    def get_all_worker_nodes_cached(
+        self, timeout_seconds: Optional[float] = None
+    ) -> list[tuple[str, WorkerNode]]:
+        """Get all (instance_id, WorkerNode) tuples across all instances, with caching.
+
+        Args:
+            timeout_seconds: Cache timeout in seconds.
+                - If None (default): use the cache's default timeout.
+                - If 0: cache immediately expires, always get fresh data
+                  and update cache.
+                - If > 0: use cache with specified timeout.
+
+        Returns:
+            List of (instance_id, WorkerNode) tuples, either from cache or fresh data
+        """
+        return self._worker_node_cache.get_cached(
+            lambda: self._get_all_worker_nodes_fresh(), timeout_override=timeout_seconds
+        )
+
+    def _get_all_worker_nodes_fresh(self) -> list[tuple[str, WorkerNode]]:
+        """Internal method to get fresh (instance_id, WorkerNode) tuples
+        without cache."""
+        # Snapshot to avoid RuntimeError if dict changes during iteration
+        result = []
+        for instance_id, instance_node in self.instances.items():
+            for worker_node in instance_node.workers.values():
+                result.append((instance_id, worker_node))
+        return result
+
+    def update_heartbeat(
+        self, instance_id: str, worker_id: int, timestamp: float
+    ) -> bool:
+        """Update worker heartbeat timestamp. Returns True if successful."""
+        instance_node = self._get_instance(instance_id)
+        if instance_node is None:
+            return False
+        worker_node = instance_node.get_worker(worker_id)
+        if worker_node is None:
+            return False
+        worker_node.last_heartbeat_time = timestamp
+        return True
+
+    def handle_batched_kv_operations(
+        self, msg: BatchedKVOperationMsg, is_full_sync: bool = False
+    ) -> bool:
+        """
+        Handle batched KV operations by forwarding to WorkerNode.
+
+        Args:
+            msg: The batched KV operation message.
+            is_full_sync: If True, this is a full sync batch operation.
+
+        Returns:
+            True if operations were processed successfully.
+            False if worker not found or operations were rejected.
+        """
+        instance_node = self._get_instance(msg.instance_id)
+        if instance_node is None:
+            return False
+        worker_node = instance_node.get_worker(msg.worker_id)
+        if worker_node is None:
+            return False
+        return worker_node.handle_batched_kv_operations(
+            msg,
+            on_seq_num_out_of_order=self._incr_seq_discontinuity_count,
+            is_full_sync=is_full_sync,
+        )
+
+    def find_kv(
+        self,
+        key: int,
+        exclude_instance_id: Optional[str] = None,
+    ) -> Optional[KVChunkInfo]:
+        """
+        Find a KV chunk across all workers.
+
+        Args:
+            key: The KV chunk key to find.
+            exclude_instance_id: Instance ID to exclude
+            (all workers in this instance will be excluded).
+
+        Returns: KVChunkInfo if found, None otherwise.
+        """
+        with self._rwlock.read_lock(timeout=1):
+            for instance_id, instance_node in self.instances.items():
+                # Exclude all workers in the specified instance
+                if (
+                    exclude_instance_id is not None
+                    and instance_id == exclude_instance_id
+                ):
+                    continue
+                result = instance_node.find_key_simple(key)
+                if result is not None:
+                    return result
+            return None
+
+    def find_kv_with_worker_info(
+        self,
+        key: int,
+        exclude_instance_id: Optional[str] = None,
+    ) -> Optional[tuple[KVChunkInfo, Optional[str], set[int]]]:
+        """
+        Find a KV chunk and return worker info in one lookup.
+        Optimized for batched_p2p_lookup to avoid multiple lookups.
+
+        Returns: (KVChunkInfo, peer_init_url, kv_keys) if found, None otherwise.
+        """
+        # Snapshot instances to avoid RuntimeError if dict changes during iteration
+        for instance_id, instance_node in list(self.instances.items()):
+            if exclude_instance_id is not None and instance_id == exclude_instance_id:
+                continue
+            result = instance_node.find_key(key)
+            if result is not None:
+                return result
+        return None
+
+    def get_total_kv_count(self) -> int:
+        """Get total count of KV chunks across all workers."""
+        # Snapshot to avoid RuntimeError if dict changes during iteration
+        total = 0
+        for instance_node in list(self.instances.values()):
+            total += instance_node.get_total_kv_count()
+        return total
+
+    def get_worker_kv_keys(
+        self, instance_id: str, worker_id: int, location: str
+    ) -> set[int]:
+        """Get all KV keys for a specific worker and location."""
+        instance_node = self._get_instance(instance_id)
+        if instance_node is None:
+            return set()
+        worker_node = instance_node.get_worker(worker_id)
+        if worker_node is None:
+            return set()
+        return worker_node.get_kv_keys(location)
+
+    def clear_worker_kv(
+        self, instance_id: str, worker_id: int, location: Optional[str] = None
+    ) -> bool:
+        """
+        Clear all KV chunks for a specific worker and location.
+        Returns True if successful, False if worker not found.
+        """
+        worker_node = self.get_worker(instance_id, worker_id)
+        if worker_node is None:
+            return False
+        with worker_node._lock:
+            if location is None:
+                worker_node.kv_store.clear()
+                worker_node.seq_tracker.clear()
+                return True
+            if location in worker_node.kv_store:
+                del worker_node.kv_store[location]
+            if location in worker_node.seq_tracker:
+                del worker_node.seq_tracker[location]
+        return True
+
+    def clear_all_worker_kv(self, instance_id: str, worker_id: int) -> bool:
+        """
+        Clear all KV chunks for a worker across all locations.
+        Returns True if successful, False if worker not found.
+        """
+        worker_node = self.get_worker(instance_id, worker_id)
+        if worker_node is None:
+            return False
+
+        worker_node.clear_kv_store()
+        return True
diff --git a/lmcache/v1/cache_controller/worker.py b/lmcache/v1/cache_controller/worker.py
new file mode 100644
index 0000000..a6632c2
--- /dev/null
+++ b/lmcache/v1/cache_controller/worker.py
@@ -0,0 +1,665 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, Optional
+import asyncio
+import threading
+
+# Third Party
+import msgspec
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.full_sync_sender import FullSyncSender
+from lmcache.v1.cache_controller.message import (
+    BatchedP2PLookupMsg,
+    BatchedP2PLookupRetMsg,
+    ClearWorkerMsg,
+    ClearWorkerRetMsg,
+    CompressWorkerMsg,
+    CompressWorkerRetMsg,
+    DecompressWorkerMsg,
+    DecompressWorkerRetMsg,
+    DeRegisterMsg,
+    ErrorMsg,
+    FullSyncStartMsg,
+    FullSyncStartRetMsg,
+    FullSyncStatusMsg,
+    FullSyncStatusRetMsg,
+    HealthWorkerMsg,
+    HealthWorkerRetMsg,
+    HeartbeatMsg,
+    HeartbeatRetMsg,
+    MoveWorkerMsg,
+    MoveWorkerRetMsg,
+    Msg,
+    PinWorkerMsg,
+    PinWorkerRetMsg,
+    RegisterMsg,
+    RegisterRetMsg,
+    WorkerMsg,
+    WorkerReqMsg,
+    WorkerReqRetMsg,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc_utils import (
+    DEFAULT_SOCKET_RECV_TIMEOUT_MS,
+    DEFAULT_SOCKET_SEND_TIMEOUT_MS,
+    close_zmq_socket,
+    get_ip,
+    get_zmq_context,
+    get_zmq_socket,
+    get_zmq_socket_with_timeout,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_engine import LMCacheEngine
+
+logger = init_logger(__name__)
+
+
+class LMCacheWorker:
+    """
+    LMCache Worker class to handle the execution of cache operations.
+    This class is responsible for receiving requests from the executor and
+    executing the corresponding operations on the LMCache engine.
+    Each worker is associated with a specific LMCache instance and a worker id.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        lmcache_engine: "LMCacheEngine",
+    ):
+        # TODO (Jiayi): "instance_id" might not be needed anymore.
+        # Please consider removing it.
+        self.config = config
+        self.lmcache_instance_id = config.lmcache_instance_id
+        if self.lmcache_instance_id is None:
+            raise ValueError(
+                "lmcache_instance_id is required when enable_controller=True"
+            )
+        self.lmcache_engine = lmcache_engine
+        self.worker_id = metadata.worker_id
+
+        self.context = get_zmq_context()
+
+        # Load timeout configurations from extra_config (in milliseconds)
+        self.socket_recv_timeout_ms = config.get_extra_config_value(
+            "worker_socket_recv_timeout_ms", DEFAULT_SOCKET_RECV_TIMEOUT_MS
+        )
+        self.socket_send_timeout_ms = config.get_extra_config_value(
+            "worker_socket_send_timeout_ms", DEFAULT_SOCKET_SEND_TIMEOUT_MS
+        )
+
+        if config.controller_pull_url is None:
+            raise ValueError(
+                "controller_pull_url is required when enable_controller=True"
+            )
+
+        controller_pull_url = config.controller_pull_url
+        self.push_socket = get_zmq_socket(
+            self.context,
+            controller_pull_url,
+            protocol="tcp",
+            role=zmq.PUSH,  # type: ignore[attr-defined]
+            bind_or_connect="connect",
+        )
+
+        if config.controller_reply_url is not None:
+            self.controller_rep_url = config.controller_reply_url
+            self._create_req_socket()
+
+        # Heartbeat socket will be created dynamically after register
+        # based on heartbeat_url returned from controller
+        self.heartbeat_socket: Optional[zmq.asyncio.Socket] = None
+        self.controller_heartbeat_url: Optional[str] = None
+
+        # metadata.world_size comes from vLLM's parallel_config.world_size.
+        # For MLA models, vLLM divides this by tp_size (e.g. TP=8 PP=1 on
+        # 8 GPUs → world_size=1), so it may be much smaller than the total
+        # GPU count.  For non-MLA models it equals TP × PP.
+        #
+        # get_lmcache_worker_ids() decides which workers run an LMCache
+        # instance: [0] for MLA (only one worker needed since KV caches
+        # are not TP-sharded), or range(world_size) for non-MLA.
+        #
+        # We use >= because extra ports are harmless — port selection
+        # indexes by worker_id or lmcache_worker_ids position, so
+        # trailing entries are never bound to sockets.
+        lmcache_worker_ids = config.get_lmcache_worker_ids(
+            metadata.use_mla, metadata.world_size
+        )
+        if not lmcache_worker_ids:
+            # start lmcache worker on all ranks;
+            # need at least one port per rank (world_size)
+            if len(config.lmcache_worker_ports) < metadata.world_size:
+                raise ValueError(
+                    f"lmcache_worker_ports must have at least {metadata.world_size} "
+                    f"port(s) (world_size), got {len(config.lmcache_worker_ports)}"
+                )
+            lmcache_worker_port = config.lmcache_worker_ports[self.worker_id]
+        else:
+            # start lmcache worker on given worker ids;
+            # need at least one port per explicitly listed worker
+            if len(config.lmcache_worker_ports) < len(lmcache_worker_ids):
+                raise ValueError(
+                    f"lmcache_worker_ports must have at least "
+                    f"{len(lmcache_worker_ids)} "
+                    f"port(s) (one per lmcache worker), "
+                    f"got {len(config.lmcache_worker_ports)}"
+                )
+            index = lmcache_worker_ids.index(self.worker_id)
+            lmcache_worker_port = config.lmcache_worker_ports[index]
+
+        self.lmcache_worker_internal_url = f"*:{lmcache_worker_port}"
+        self.lmcache_worker_ip = get_ip()
+        self.lmcache_worker_port = lmcache_worker_port
+
+        self.p2p_init_url = None
+        if config.enable_p2p:
+            self.p2p_host = config.p2p_host
+            self.p2p_init_port = config.p2p_init_ports[self.worker_id]
+            self.p2p_init_url = f"{self.p2p_host}:{self.p2p_init_port}"
+
+        self.reply_socket = get_zmq_socket(
+            self.context,
+            self.lmcache_worker_internal_url,
+            protocol="tcp",
+            role=zmq.REP,  # type: ignore[attr-defined]
+            bind_or_connect="bind",
+        )
+
+        logger.info(f"Reply socket established at {self.lmcache_worker_internal_url}")
+
+        self.loop = asyncio.new_event_loop()
+        self.thread = threading.Thread(
+            target=self.loop.run_forever, daemon=True, name="lmcache-worker-thread"
+        )
+        self.thread.start()
+        asyncio.run_coroutine_threadsafe(self.start_all(), self.loop)
+
+        self.msg_queue: asyncio.Queue[WorkerMsg] = asyncio.Queue()
+
+        # Full sync sender (initialized lazily when needed)
+        self._full_sync_sender: Optional["FullSyncSender"] = None
+
+    async def register(self):
+        """
+        Register the lmcache worker with the controller via DEALER-ROUTER.
+
+        This method sends a RegisterMsg and waits for RegisterRetMsg
+        which contains extra_config (e.g., heartbeat_url).
+        """
+        assert self.lmcache_instance_id is not None
+        logger.info(
+            "Registering lmcache instance-worker: %s",
+            (self.lmcache_instance_id, self.worker_id),
+        )
+
+        register_msg = RegisterMsg(
+            instance_id=self.lmcache_instance_id,
+            worker_id=self.worker_id,
+            ip=self.lmcache_worker_ip,
+            port=self.lmcache_worker_port,
+            peer_init_url=self.p2p_init_url,
+        )
+
+        # Send via DEALER socket (empty frame + payload) and wait for response
+        try:
+            await self.req_socket.send_multipart(
+                [b"", msgspec.msgpack.encode(register_msg)]
+            )
+            # DEALER receives: [empty_frame, payload]
+            frames = await self.req_socket.recv_multipart()
+            serialized_ret_msg = frames[-1]
+            ret_msg = msgspec.msgpack.decode(serialized_ret_msg, type=Msg)
+
+            if isinstance(ret_msg, RegisterRetMsg):
+                self._process_register_response(ret_msg)
+            else:
+                logger.warning("Unexpected register response type: %s", type(ret_msg))
+        except zmq.ZMQError as e:
+            logger.error("Failed to register with controller: %s", e)
+            raise
+
+    def _process_register_response(self, ret_msg: RegisterRetMsg):
+        """Process RegisterRetMsg and initialize components based on extra_config."""
+        extra_config = ret_msg.extra_config
+
+        # Initialize heartbeat socket if heartbeat_url is provided
+        heartbeat_url = extra_config.get("heartbeat_url")
+        if heartbeat_url:
+            logger.info("Received heartbeat_url from controller: %s", heartbeat_url)
+            self.controller_heartbeat_url = heartbeat_url
+            self._create_heartbeat_socket()
+        else:
+            logger.info("No dedicated heartbeat_url provided by controller")
+
+    def deregister(self):
+        """
+        De-register the lmcache worker from the controller.
+        """
+        assert self.lmcache_instance_id is not None
+        self.put_msg(
+            DeRegisterMsg(
+                instance_id=self.lmcache_instance_id,
+                worker_id=self.worker_id,
+                ip=self.lmcache_worker_ip,
+                port=self.lmcache_worker_port,
+            )
+        )
+
+    async def async_put_and_wait_msg(
+        self,
+        msg: WorkerReqMsg,
+    ) -> WorkerReqRetMsg:
+        """
+        Send a message to the controller and wait for the response.
+
+        This method handles different types of WorkerReqMsg using appropriate sockets:
+        - HeartbeatMsg: Uses dedicated heartbeat socket
+        - Other messages (RegisterMsg, BatchedP2PLookupMsg, FullSyncStartMsg,
+          FullSyncStatusMsg): Uses DEALER socket (req_socket)
+
+        Note: With DEALER-ROUTER mode, we no longer need to separate FullSync
+        messages to heartbeat socket since DEALER supports async concurrent requests.
+        """
+        # Send heartbeat via dedicated heartbeat socket
+        if isinstance(msg, HeartbeatMsg):
+            return await self._send_heartbeat_msg(msg)
+
+        # Send other messages via DEALER socket
+        try:
+            # DEALER socket: send [empty_frame, payload]
+            await self.req_socket.send_multipart([b"", msgspec.msgpack.encode(msg)])
+            frames = await self.req_socket.recv_multipart()
+            # DEALER receives: [empty_frame, payload]
+            serialized_ret_msg = frames[-1]
+            ret_msg = msgspec.msgpack.decode(serialized_ret_msg, type=Msg)
+            return ret_msg
+        except zmq.Again as e:
+            logger.error("Timeout occurred, recreating socket. Error: %s", e)
+            self._recreate_req_socket()
+            return self._on_request_failure(msg)
+        except zmq.ZMQError as e:
+            logger.error("ZMQ error occurred, recreating socket. Error: %s", e)
+            self._recreate_req_socket()
+            return self._on_request_failure(msg)
+        except Exception as e:
+            logger.error("Error happens in lmcache worker req_socket. Error: %s", e)
+            return self._on_request_failure(msg)
+
+    def _create_req_socket(self):
+        self.req_socket = get_zmq_socket_with_timeout(
+            self.context,
+            self.controller_rep_url,
+            "tcp",
+            zmq.DEALER,  # type: ignore[attr-defined]
+            "connect",
+            self.socket_recv_timeout_ms,
+            self.socket_send_timeout_ms,
+        )
+
+    def _create_heartbeat_socket(self):
+        logger.info(
+            "Creating heartbeat socket to connect to: %s, "
+            "recv_timeout: %dms, send_timeout: %dms",
+            self.controller_heartbeat_url,
+            self.socket_recv_timeout_ms,
+            self.socket_send_timeout_ms,
+        )
+        self.heartbeat_socket = get_zmq_socket_with_timeout(
+            self.context,
+            self.controller_heartbeat_url,
+            "tcp",
+            zmq.DEALER,  # type: ignore[attr-defined]
+            "connect",
+            self.socket_recv_timeout_ms,
+            self.socket_send_timeout_ms,
+        )
+
+    def _recreate_heartbeat_socket(self):
+        try:
+            self.heartbeat_socket.close(linger=0)
+        except Exception as e:
+            logger.error("Error closing heartbeat socket: %s", e)
+        self._create_heartbeat_socket()
+
+    def _recreate_req_socket(self):
+        try:
+            self.req_socket.close(linger=0)
+        except Exception as e:
+            logger.error("Error closing req socket: %s", e)
+        self._create_req_socket()
+
+    def _get_full_sync_sender(self):
+        """Lazy initialization of FullSyncSender"""
+        if self._full_sync_sender is None:
+            # Get the local_cpu_backend from lmcache_engine
+            local_cpu_backend = self.lmcache_engine.storage_manager.local_cpu_backend
+            self._full_sync_sender = FullSyncSender(
+                config=self.config,
+                worker=self,
+                lmcache_engine=self.lmcache_engine,
+                local_cpu_backend=local_cpu_backend,
+            )
+        return self._full_sync_sender
+
+    def _on_request_failure(self, msg: WorkerReqMsg) -> WorkerReqRetMsg:
+        """
+        Create a default return message when worker -> controller
+        request encounters an error (e.g., timeout, ZMQ error).
+        """
+        if isinstance(msg, BatchedP2PLookupMsg):
+            return BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+        elif isinstance(msg, HeartbeatMsg):
+            return HeartbeatRetMsg()  # No command by default
+        elif isinstance(msg, FullSyncStartMsg):
+            return FullSyncStartRetMsg(
+                sync_id=msg.sync_id,
+                accepted=False,
+                error_msg="Communication error",
+            )
+        elif isinstance(msg, FullSyncStatusMsg):
+            return FullSyncStatusRetMsg(
+                sync_id=msg.sync_id,
+                is_complete=False,
+                global_progress=0.0,
+                can_exit_freeze=False,
+            )
+        else:
+            raise ValueError(f"Unknown message type: {type(msg)}")
+
+    def put_msg(self, msg: WorkerMsg):
+        """
+        Put a message into the message queue.
+        """
+        # TODO(Jiayi): This might introduce ~0.05ms latency than
+        # a normal function call.
+        # Not sure how much overhead is blocking though.
+        self.loop.call_soon_threadsafe(self.msg_queue.put_nowait, msg)
+
+    async def batched_get_msg(self, max_bsz: int = 50) -> list[WorkerMsg]:
+        """
+        Get a batch of messages from the message queue.
+        """
+        batch = []
+
+        # use blocking get for the first msg
+        try:
+            item = await self.msg_queue.get()
+            batch.append(item)
+        except asyncio.CancelledError:
+            return batch  # shutdown path
+
+        for _ in range(max_bsz - 1):
+            try:
+                item = self.msg_queue.get_nowait()
+                batch.append(item)
+            except asyncio.QueueEmpty:
+                break
+        return batch
+
+    async def _send_heartbeat_msg(self, msg: HeartbeatMsg) -> HeartbeatRetMsg:
+        """
+        Send heartbeat message via dedicated heartbeat DEALER socket.
+        This is separate from async_put_and_wait_msg to keep heartbeat independent.
+        """
+        if self.heartbeat_socket is None:
+            logger.warning("Heartbeat socket is not initialized")
+            return HeartbeatRetMsg()
+        try:
+            # DEALER socket: send [empty_frame, payload]
+            logger.info("Sending heartbeat message to controller...")
+            await self.heartbeat_socket.send_multipart(
+                [b"", msgspec.msgpack.encode(msg)]
+            )
+            logger.info("Heartbeat message sent, waiting for response...")
+            frames = await self.heartbeat_socket.recv_multipart()
+            logger.info("Received heartbeat response with %d frames", len(frames))
+            # DEALER receives: [empty_frame, payload]
+            serialized_ret_msg = frames[-1]
+            ret_msg = msgspec.msgpack.decode(serialized_ret_msg, type=Msg)
+            return ret_msg
+        except zmq.Again as e:
+            logger.error("Heartbeat timeout occurred, recreating socket. Error: %s", e)
+            self._recreate_heartbeat_socket()
+            return HeartbeatRetMsg()
+        except zmq.ZMQError as e:
+            logger.error(
+                "Heartbeat ZMQ error occurred, recreating socket. Error: %s", e
+            )
+            self._recreate_heartbeat_socket()
+            return HeartbeatRetMsg()
+        except Exception as e:
+            logger.error("Error happens in heartbeat socket. Error: %s", e)
+            return HeartbeatRetMsg()
+
+    async def heartbeat(self):
+        """
+        Send periodic heartbeats to the controller (DEALER-ROUTER mode).
+
+        Process any commands received in the heartbeat response.
+        Uses dedicated heartbeat socket to avoid blocking from other requests.
+        """
+        enable_heartbeat = (
+            self.config.lmcache_worker_heartbeat_time is not None
+            and self.config.lmcache_worker_heartbeat_time > 0
+            and self.heartbeat_socket is not None
+        )
+        if enable_heartbeat:
+            await asyncio.sleep(self.config.lmcache_worker_heartbeat_delay_time)
+            logger.info(
+                "Start heartbeat in %s : %s, delay time: %ss, heartbeat time: %ss",
+                self.lmcache_instance_id,
+                self.worker_id,
+                self.config.lmcache_worker_heartbeat_delay_time,
+                self.config.lmcache_worker_heartbeat_time,
+            )
+            while True:
+                # Send heartbeat via dedicated heartbeat socket
+                heartbeat_msg = HeartbeatMsg(
+                    instance_id=self.lmcache_instance_id,
+                    worker_id=self.worker_id,
+                    ip=self.lmcache_worker_ip,
+                    port=self.lmcache_worker_port,
+                    peer_init_url=self.p2p_init_url,
+                )
+
+                try:
+                    ret_msg = await self._send_heartbeat_msg(heartbeat_msg)
+
+                    if isinstance(ret_msg, HeartbeatRetMsg):
+                        self._handle_heartbeat_commands(ret_msg)
+                    else:
+                        logger.warning(
+                            "Unexpected heartbeat response type: %s", type(ret_msg)
+                        )
+                except Exception as e:
+                    logger.error("Error during heartbeat: %s", e)
+
+                await asyncio.sleep(self.config.lmcache_worker_heartbeat_time)
+
+    def _handle_heartbeat_commands(self, ret_msg: HeartbeatRetMsg):
+        """
+        Handle commands received in heartbeat response.
+
+        Uses polymorphic dispatch - each command class implements its own
+        execute() method. Commands are executed sequentially.
+        """
+        if not ret_msg.has_commands():
+            return
+
+        for command in ret_msg.commands:
+            logger.info(
+                "Executing heartbeat command: %s",
+                command.describe(),
+            )
+            try:
+                command.execute(self)
+            except NotImplementedError:
+                logger.warning(
+                    "Command %s.execute() not implemented yet",
+                    type(command).__name__,
+                )
+            except Exception as e:
+                logger.error(
+                    "Error executing command %s: %s",
+                    type(command).__name__,
+                    e,
+                )
+
+    async def push(self):
+        while True:
+            try:
+                msgs = await self.batched_get_msg()
+                logger.debug(f"Sending {len(msgs)} messages")
+                self.push_socket.send_multipart(
+                    [msgspec.msgpack.encode(msg) for msg in msgs]
+                )
+
+            except Exception as e:
+                logger.error(f"Push error: {e}")
+
+    async def handle_request(self):
+        """
+        Handle incoming requests (control msgs) from the controller.
+        """
+        while True:
+            try:
+                serialized_request = await self.reply_socket.recv()
+                request = msgspec.msgpack.decode(serialized_request, type=Msg)
+                logger.debug(f"Received message: {request}")
+                if isinstance(request, MoveWorkerMsg):
+                    tokens = request.tokens
+                    old_position = request.old_position
+                    new_position = request.new_position
+                    do_copy = request.copy
+                    worker_event_id = request.worker_event_id
+
+                    # Intra node move
+                    if new_position[0] == self.lmcache_worker_internal_url:
+                        # TODO(Jiayi): currently we only support moving from
+                        # local disk to local cpu.
+                        assert old_position[1] == "LocalDiskBackend"
+                        assert new_position[1] == "LocalCPUBackend"
+                        assert do_copy
+
+                        # TODO(Jiayi): We need to align prefetch and move.
+                        logger.debug("Executing prefetch operation.")
+                        raise NotImplementedError(
+                            "Prefetch from controller is not implemented yet."
+                        )
+                    else:
+                        assert new_position[1] == "LocalCPUBackend", (
+                            "Only support moving to cpu for now."
+                        )
+                        logger.debug("Executing cross-node move operation.")
+                        num_tokens = self.lmcache_engine.move(
+                            tokens=tokens,
+                            old_position=old_position,
+                            new_position=new_position,
+                            event_id=worker_event_id,
+                            do_copy=do_copy,
+                        )
+
+                    # TODO(Jiayi): LMCache needs to have an event tracking
+                    # pool to enable more advanced control-plane optims.
+                    # For now, we use a dummy `event_id`.
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        MoveWorkerRetMsg(num_tokens=num_tokens)
+                    )
+                elif isinstance(request, CompressWorkerMsg):
+                    num_compressed_tokens = self.lmcache_engine.compress(
+                        tokens=request.tokens,
+                        method=request.method,
+                        location=request.location,
+                        event_id=request.worker_event_id,
+                    )
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        CompressWorkerRetMsg(num_tokens=num_compressed_tokens)
+                    )
+                elif isinstance(request, DecompressWorkerMsg):
+                    num_decompressed_tokens = self.lmcache_engine.decompress(
+                        tokens=request.tokens,
+                        method=request.method,
+                        location=request.location,
+                        event_id=request.worker_event_id,
+                    )
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        DecompressWorkerRetMsg(num_tokens=num_decompressed_tokens)
+                    )
+                elif isinstance(request, PinWorkerMsg):
+                    num_pinned_tokens = self.lmcache_engine.lookup(
+                        tokens=request.tokens,
+                        search_range=[request.location],
+                        lookup_id=request.worker_event_id,
+                        pin=True,
+                    )
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        PinWorkerRetMsg(num_tokens=num_pinned_tokens)
+                    )
+                elif isinstance(request, ClearWorkerMsg):
+                    num_cleared_tokens = self.lmcache_engine.clear(
+                        locations=[request.location],
+                    )
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        ClearWorkerRetMsg(num_tokens=num_cleared_tokens)
+                    )
+                elif isinstance(request, HealthWorkerMsg):
+                    error_code = self.lmcache_engine.health()
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        HealthWorkerRetMsg(error_code=error_code)
+                    )
+                else:
+                    logger.error(f"Unknown message: {request}")
+                    serialized_ret_msg = msgspec.msgpack.encode(
+                        ErrorMsg(error=f"Unknown message: {request}")
+                    )
+
+                await self.reply_socket.send(serialized_ret_msg)
+            except Exception as e:
+                logger.error(f"Worker error: {e}")
+                serialized_ret_msg = msgspec.msgpack.encode(
+                    ErrorMsg(error=f"Worker error: {e}")
+                )
+                await self.reply_socket.send(serialized_ret_msg)
+
+    async def start_all(self):
+        try:
+            # Register first to get heartbeat_url before starting heartbeat task
+            await self.register()
+
+            logger.info(
+                f"Starting lmcache worker {self.worker_id}"
+                f"for instance {self.lmcache_instance_id}"
+            )
+            await asyncio.gather(
+                self.push(),
+                self.handle_request(),
+                self.heartbeat(),
+            )
+        except Exception as e:
+            logger.error(
+                f"Instance {self.lmcache_instance_id}, "
+                f"worker {self.worker_id} error: {e}"
+            )
+
+    def close(self):
+        self.deregister()
+        if self.loop.is_running():
+            self.loop.call_soon_threadsafe(self.loop.stop)
+        if self.thread.is_alive():
+            self.thread.join()
+        self.loop.close()
+        close_zmq_socket(self.push_socket)
+        close_zmq_socket(self.reply_socket)
+        if self.heartbeat_socket is not None:
+            close_zmq_socket(self.heartbeat_socket)
+        if hasattr(self, "req_socket"):
+            close_zmq_socket(self.req_socket)
diff --git a/lmcache/v1/cache_engine.py b/lmcache/v1/cache_engine.py
new file mode 100644
index 0000000..dd6e2e5
--- /dev/null
+++ b/lmcache/v1/cache_engine.py
@@ -0,0 +1,2193 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import defaultdict
+from collections.abc import Iterable
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    Generator,
+    List,
+    Optional,
+    Tuple,
+    Union,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.health_monitor.base import HealthMonitor
+
+# Standard
+import asyncio
+import gc
+import multiprocessing
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.observability import LMCacheStatsLogger, LMCStatsMonitor
+from lmcache.usage_telemetry import InitializeUsageContext
+from lmcache.utils import (
+    CacheEngineKey,
+    CacheStoreEvent,
+    _lmcache_nvtx_annotate,
+    compress_slot_mapping,
+    convert_tokens_to_list,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventManager, EventStatus, EventType
+from lmcache.v1.gpu_connector.gpu_connectors import GPUConnectorInterface
+from lmcache.v1.gpu_connector.utils import assert_layerwise_gpu_connector
+from lmcache.v1.hidden_state_store import HiddenStateStore
+from lmcache.v1.memory_allocators.cu_file_memory_allocator import CuFileMemoryAllocator
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.pin_monitor import PinMonitor
+from lmcache.v1.platform import current_device_spec
+from lmcache.v1.storage_backend.storage_manager import StorageManager
+from lmcache.v1.system_detection import NUMADetector, NUMAMapping
+from lmcache.v1.token_database import (
+    ChunkedTokenDatabase,
+    SegmentTokenDatabase,
+    TokenDatabase,
+)
+
+logger = init_logger(__name__)
+
+# Type aliases for processed chunks
+# (cache_key, memory_obj, start_index, end_index)
+ProcessedChunk = Tuple[CacheEngineKey, MemoryObj, int, int]
+# (list of processed chunks, total kv size)
+ProcessTokensInternalResult = Tuple[List[ProcessedChunk], int]
+
+
+class CacheEngineEndSignal:
+    pass
+
+
+class LMCacheEngine:
+    """The main class for the cache engine.
+
+    When storing the KV caches into the cache engine, it takes GPU KV
+    caches from the serving engine and convert them into MemoryObjs that
+    resides in the CPU. The MemoryObjs are then being stored into the
+    StorageBackends in an asynchronous manner.
+
+    When retrieving the KV caches from the cache engine, it fetches the
+    MemoryObjs from the StorageBackends and convert them into GPU KV caches
+    by GPUConnectors specialized for the serving engine.
+
+    It also supports prefetching the KV caches from the StorageBackends.
+    It relies on the StorageBackends to manage the requests of prefetching
+    and real retrieval and avoid the conflicts.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        token_database: TokenDatabase,
+        gpu_connector: Optional[GPUConnectorInterface],
+        broadcast_fn: Callable[[torch.Tensor, int], None],
+        broadcast_object_fn: Callable[[Any, int], Any],
+    ):
+        logger.info("Creating LMCacheEngine with config: %s", config)
+        self.config = config
+        self.metadata = metadata
+        self.token_database = token_database
+        self.gpu_connector = gpu_connector
+        self.broadcast_fn = broadcast_fn
+        self.broadcast_object_fn = broadcast_object_fn
+        # save_only_first_rank only works when use mla
+        self.save_only_first_rank = (
+            self.config.get_extra_config_value("save_only_first_rank", metadata.use_mla)
+            and metadata.use_mla
+        )
+
+        if self.save_only_first_rank and self.gpu_connector is not None:
+            self.broadcast_stream = (
+                self.gpu_connector.load_stream
+                if hasattr(self.gpu_connector, "load_stream")
+                else torch_dev.Stream()
+            )
+
+        # Holds GPU-resident copies of the broadcast send buffers on the
+        # leader rank so the subsequent batched_to_gpu can read from HBM
+        # rather than re-reading the same L1 bytes over PCIe. Always empty
+        # on non-leader ranks and outside the broadcast critical section.
+        # Typed as List[MemoryObj] (the supertype) so the list can be
+        # passed directly to batched_to_gpu without an invariance cast.
+        self._leader_gpu_substitute_objs: List[MemoryObj] = []
+
+        self.enable_controller = config.enable_controller
+
+        # NOTE: Unix systems use fork by default
+        multiprocessing.set_start_method("spawn", force=True)
+
+        # avoid circular import
+        # First Party
+        from lmcache.v1.cache_controller import LMCacheWorker
+
+        self.lmcache_worker: Optional[LMCacheWorker] = None
+        lmcache_worker_ids = config.get_lmcache_worker_ids(
+            metadata.use_mla, metadata.world_size
+        )
+        # lmcache_worker_ids is empty means start on all workers
+        if (
+            self.enable_controller
+            and self.metadata.role != "scheduler"
+            and (not lmcache_worker_ids or metadata.worker_id in lmcache_worker_ids)
+        ):
+            self.lmcache_worker = LMCacheWorker(config, metadata, self)
+        else:
+            self.lmcache_worker = None
+            logger.info(
+                "LMCacheWorker is not initialized (related configs: "
+                "enable_controller: %s, role: %s, worker_id: %d, worker_ids: %s).",
+                self.enable_controller,
+                self.metadata.role,
+                self.metadata.worker_id,
+                lmcache_worker_ids,
+            )
+
+        self.async_loading = config.enable_async_loading
+        self.event_manager = EventManager()
+
+        self.use_layerwise = config.use_layerwise
+
+        # TODO: support save_only_first_rank when use layerwise
+        # if use_layerwise is True, all ranks will initialize the storage_manager
+        # if save_only_first_rank is False, all ranks will initialize
+        # the storage_manager
+        # if save_only_first_rank is True, only the first rank and
+        # lookup server workers will initialize the storage_manager
+        self.storage_manager: Optional[StorageManager] = None
+
+        # KV events
+        self.kv_events_enabled = False
+        self.kv_events_enabled = config.enable_kv_events
+        if self.kv_events_enabled:
+            self.kv_events: List[CacheStoreEvent] = []
+            logger.info("KV events are enabled.")
+        else:
+            logger.info("KV events are disabled.")
+
+        # HACK: remove this in the future
+        # NOTE (Jiayi): This is currently used to support
+        # dropping the kv cache from the buffer in PD backend
+        # at decoder.
+        self.remove_after_retrieve = config.enable_pd and config.pd_role == "receiver"
+
+        # asymmetric store/retrieve location can be specified
+        # this is typically used (but not limited) in PD system
+        self.store_location = config.store_location
+        self.retrieve_locations = config.retrieve_locations
+
+        self.num_layers = metadata.kv_shape[0]
+        self.fmt = None
+        if self.use_layerwise:
+            if metadata.use_mla:
+                self.fmt = MemoryFormat.KV_MLA_FMT
+            elif config.enable_blending:
+                self.fmt = MemoryFormat.KV_2TD
+            else:
+                self.fmt = MemoryFormat.KV_T2D
+        if metadata.use_mla:
+            self.fmt = MemoryFormat.KV_MLA_FMT
+
+        # NOTE(ApostaC): we haven't support lookup-cache yet
+        self.lookup_cache: dict[CacheEngineKey, Any] = {}
+
+        # lookup_id -> {location -> [pinned keys]}
+        self.lookup_pins: dict[str, dict[str, list]] = defaultdict(
+            lambda: defaultdict(list)
+        )
+
+        InitializeUsageContext(config, metadata)
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+        # Initialize PinMonitor singleton with config
+        PinMonitor.GetOrCreate(config, metadata)
+
+        self.post_inited = False
+
+        # Flag to control KVCache Check logging (can be toggled via API)
+        self.kvcache_check_log_enabled = False
+
+        gc.collect()
+        if not config.py_enable_gc:
+            gc.disable()
+
+        # Health monitor reference (injected by LMCacheManager)
+        self._health_monitor: Optional["HealthMonitor"] = None
+
+        # Flag to indicate if initialization failed (irrecoverable error)
+        self._init_failed = False
+
+        # Hidden-state cache (logically separate from KV; lives on its own
+        # pinned pool). Bound to storage_manager in post_init for coupled
+        # eviction. None when disabled in config.
+        self.hidden_state_store: Optional[HiddenStateStore] = None
+        if config.enable_hidden_state_cache:
+            self.hidden_state_store = HiddenStateStore(config, token_database)
+
+    def set_health_monitor(self, health_monitor: "HealthMonitor") -> None:
+        """
+        Set the health monitor reference.
+
+        This is called by LMCacheManager after creating the HealthMonitor
+        to inject the reference into the engine.
+
+        Args:
+            health_monitor: The HealthMonitor instance from LMCacheManager
+        """
+        self._health_monitor = health_monitor
+
+    def is_healthy(self) -> bool:
+        """
+        Check if the LMCache system is healthy.
+
+        This method returns False if:
+        - Initialization failed (irrecoverable error)
+        - HealthMonitor reports unhealthy
+
+        If no health monitor is set and initialization succeeded,
+        it returns True (assume healthy).
+
+        Returns:
+            bool: True if healthy, False otherwise
+        """
+        if self._init_failed:
+            return False
+        if self._health_monitor is not None:
+            return self._health_monitor.is_healthy()
+        return True
+
+    def _get_req_id(self, kwargs: dict) -> str:
+        """Extracts request ID from kwargs for logging."""
+        return kwargs.get("req_id", "unspecified")
+
+    def mark_init_failed(self, reason: str = "") -> None:
+        """
+        Mark the engine as having failed initialization.
+
+        This is called by LMCacheManager when an irrecoverable error occurs
+        during initialization or post_init. Once marked, is_healthy() will
+        always return False, causing the system to fall back to recomputation.
+
+        Args:
+            reason: Optional reason string for logging
+        """
+        self._init_failed = True
+        if reason:
+            logger.error("LMCacheEngine marked as init failed: %s", reason)
+        else:
+            logger.error("LMCacheEngine marked as init failed")
+
+    def post_init(self, **kwargs) -> None:
+        if not self.post_inited:
+            logger.info("Post initializing LMCacheEngine")
+            lookup_server_worker_ids = self.config.get_lookup_server_worker_ids(
+                self.metadata.use_mla, self.metadata.world_size
+            )
+            if (
+                self.lmcache_worker is not None
+                or self.use_layerwise
+                or not self.save_only_first_rank
+                or self.metadata.is_first_rank()
+                or len(lookup_server_worker_ids) == 0
+                or self.metadata.worker_id in lookup_server_worker_ids
+            ):
+                logger.info(
+                    "Initialize storage manager on rank %d, "
+                    "use layerwise: %s,"
+                    "save only first rank: %s",
+                    self.metadata.worker_id,
+                    self.use_layerwise,
+                    self.save_only_first_rank,
+                )
+                async_lookup_server = kwargs.get("async_lookup_server", None)
+                self.storage_manager = StorageManager(
+                    self.config,
+                    self.metadata,
+                    event_manager=self.event_manager,
+                    lmcache_worker=self.lmcache_worker,
+                    async_lookup_server=async_lookup_server,
+                )
+                if self.hidden_state_store is not None:
+                    self.hidden_state_store.bind_storage_manager(self.storage_manager)
+            self.post_inited = True
+
+    def freeze(self, enabled: bool) -> None:
+        """
+        Set the freeze mode for the cache engine.
+
+        When freeze mode is enabled:
+        - All store operations will be skipped (no new data stored)
+        - Only local_cpu backend will be used for retrieval
+        - No admit/evict messages will be generated
+        This protects the local_cpu hot cache from changes.
+
+        Args:
+            enabled (bool): Whether to enable freeze mode
+        """
+        if self.storage_manager is not None:
+            self.storage_manager.set_freeze(enabled)
+
+    def is_frozen(self) -> bool:
+        """
+        Get the current freeze mode status.
+
+        Returns:
+            bool: True if freeze mode is enabled, False otherwise
+        """
+        if self.storage_manager is not None:
+            return self.storage_manager.is_frozen()
+        return False
+
+    def set_hot_cache(self, enabled: bool) -> None:
+        """
+        Dynamically enable or disable the LocalCPUBackend hot cache.
+
+        When disabled, the existing hot cache entries will be cleared
+        and no new data will be written to the hot cache.
+
+        Args:
+            enabled (bool): Whether to enable hot cache
+        """
+        if self.storage_manager is not None:
+            self.storage_manager.set_hot_cache(enabled)
+
+    def is_hot_cache_enabled(self) -> bool:
+        """
+        Get the current hot cache status of LocalCPUBackend.
+
+        Returns:
+            bool: True if hot cache is enabled, False otherwise
+        """
+        if self.storage_manager is not None:
+            return self.storage_manager.is_hot_cache_enabled()
+        return False
+
+    @_lmcache_nvtx_annotate
+    @torch.inference_mode()
+    def store(
+        self,
+        tokens: Optional[Union[torch.Tensor, list[int]]] = None,
+        hashes: Optional[List[int]] = None,
+        offsets: Optional[List[int]] = None,
+        mask: Optional[torch.Tensor] = None,
+        **kwargs,
+    ) -> None:
+        """Store the tokens/hashes and mask into the cache engine.
+
+        :param Optional[torch.Tensor] tokens: The tokens of the corresponding KV caches.
+
+        :param Optional[List[int]] hashes: The hashes of the corresponding KV caches.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched,
+            and the Falses will ALWAYS be at the PREFIX of the tensor.
+
+        :param **kwargs: The additional arguments for the storage backend which
+            will be passed into the gpu_connector.
+            Should include KV cache specific information (e.g., paged KV buffer
+            and the page tables).
+
+        :raises: ValueError if the number of Falses in the mask is not a
+            multiple of the chunk size.
+        """
+        # Health check: block operation if LMCache is unhealthy
+        if not self.is_healthy():
+            logger.warning("LMCache is unhealthy, skipping store operation")
+            return
+
+        assert self.gpu_connector is not None, (
+            "gpu_connector is required for store operation"
+        )
+
+        if self._is_passive():
+            logger.debug("rank=%d ignore store", self.metadata.worker_id)
+            return
+
+        assert self.storage_manager is not None
+
+        # Get req_id for logging
+        req_id = self._get_req_id(kwargs)
+
+        # Initialize num_to_store_tokens to avoid reference before assignment
+        num_to_store_tokens = 0
+
+        if mask is not None:
+            num_to_store_tokens = torch.sum(mask).item()
+        elif tokens is not None:
+            num_to_store_tokens = len(tokens)
+        elif hashes is not None:
+            assert offsets is not None, (
+                "Offsets should be set when hashes are provided during store"
+            )
+            num_to_store_tokens = sum(offsets)
+            kwargs["slot_mapping"] = torch.tensor(
+                kwargs["slot_mapping"], dtype=torch.long, device=torch_device_type
+            )
+
+        assert tokens is not None or hashes is not None, (
+            "Either 'tokens' or 'hashes' must be provided."
+        )
+
+        # KVCache Check logging
+        self._log_kvcache_for_check(
+            operation="Store",
+            kwargs=kwargs,
+            token_count=num_to_store_tokens,
+            require_req_id=False,
+        )
+
+        # Check if freeze mode is enabled
+        if self.is_frozen():
+            logger.debug(
+                "Freeze mode enabled, skipping store operation for %d tokens",
+                num_to_store_tokens,
+            )
+            return
+
+        store_stats = self.stats_monitor.on_store_request(num_to_store_tokens)
+
+        starts: List[int] = []
+        ends: List[int] = []
+        keys: List[CacheEngineKey] = []
+        memory_objs: List[MemoryObj] = []
+
+        tot_kv_size = 0
+        tot_token_num = 0
+
+        request_configs = kwargs.get("request_configs")
+        if request_configs is not None and len(request_configs) != 0:
+            assert isinstance(request_configs, dict)
+
+        with store_stats.profile_process_tokens():
+            prev_key = 0
+            for start, end, key in self.token_database.process_tokens(
+                tokens,
+                hashes,
+                offsets,
+                mask,
+                request_configs=request_configs,
+            ):
+                assert isinstance(key, CacheEngineKey)
+                # Allocate the memory object
+                num_tokens = end - start
+                kv_shapes = self.metadata.get_shapes(num_tokens)
+                kv_dtypes = self.metadata.get_dtypes()
+
+                # TODO (Jiayi): should be batched in the future
+                memory_obj = self.storage_manager.allocate(
+                    kv_shapes,
+                    kv_dtypes,
+                    busy_loop=self.config.get_extra_config_value(
+                        "force_store_wait", False
+                    ),
+                    fmt=self.fmt,
+                )
+                if memory_obj is None:
+                    logger.warning(
+                        "Local cpu memory under pressure so"
+                        " choosing to store only "
+                        " %d total chunks of KV cache.",
+                        len(memory_objs),
+                    )
+                    break
+
+                starts.append(start)
+                ends.append(end)
+                keys.append(key)
+                memory_objs.append(memory_obj)
+                tot_kv_size += memory_obj.get_size()
+                tot_token_num += num_tokens
+
+                # Create KV event
+                if self.kv_events_enabled:
+                    stored_event = CacheStoreEvent(
+                        block_hashes=[key.chunk_hash],
+                        parent_block_hash=None if start == 0 else prev_key,
+                        token_ids=[],
+                        block_size=num_tokens,
+                        lora_id=None,
+                        medium="cpu",
+                        lora_name=None,
+                    )
+                    if tokens is not None:
+                        stored_event.token_ids = convert_tokens_to_list(
+                            tokens,
+                            start,
+                            end,
+                        )
+                        if isinstance(tokens, torch.Tensor):
+                            stored_event.medium = tokens.device
+                    elif hashes is not None:
+                        stored_event.token_ids = hashes[start : end + 1]
+                    logger.debug(
+                        (
+                            "Added kv cache event '%s' to kv cache events queue"
+                            % stored_event
+                        )
+                    )
+                    self.kv_events.append(stored_event)
+                    prev_key = key.chunk_hash
+
+        # memory_objs might be empty, directly return to avoid sending tokens
+        if not memory_objs:
+            return
+
+        with store_stats.profile_from_gpu():
+            self.gpu_connector.batched_from_gpu(memory_objs, starts, ends, **kwargs)
+
+        with store_stats.profile_put():
+            transfer_spec = kwargs.get("transfer_spec", None)
+            # TODO: we implicitly rely on batched_put to call ref_count_down
+            # this management should be done in a cleaner way
+            self.storage_manager.batched_put(
+                keys,
+                memory_objs,
+                transfer_spec=transfer_spec,
+                location=self.store_location,
+            )
+
+        self.stats_monitor.on_store_finished(
+            store_stats,
+            tot_token_num,
+        )
+        tot_time = store_stats.time_to_store()
+
+        logger.info(
+            "[req_id=%s] Stored %d out of total %d tokens. "
+            "size: %.4f GB, cost %.4f ms, throughput: %.4f GB/s; "
+            "offload_time: %.4f ms, put_time: %.4f ms",
+            req_id,
+            tot_token_num,
+            num_to_store_tokens,
+            tot_kv_size / 1024**3,
+            tot_time * 1000,
+            tot_kv_size / tot_time / 1024**3 if tot_time > 0 else 0,
+            (store_stats.process_tokens_time + store_stats.from_gpu_time) * 1000,
+            store_stats.put_time * 1000,
+        )
+
+    @_lmcache_nvtx_annotate
+    @torch.inference_mode()
+    def store_layer(
+        self,
+        tokens: Union[torch.Tensor, list[int]],
+        mask: Optional[torch.Tensor] = None,
+        **kwargs,
+    ) -> Generator[None, None, None]:
+        """
+        Store the KV cache in a layerwise manner.
+
+        :param torch.Tensor tokens: The tokens of the corresponding KV caches.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched.
+
+        :param **kwargs: The additional arguments for the storage backend which
+            will be passed into the gpu_connector.
+
+        return: A generator that yields None. In the first iteration, the
+            generator allocates the memory objects for all layers and moves
+            the KV cache of the first layer from GPU to CPU. In the next
+            iterations, it moves the KV cache of layer i from GPU to the memory
+            objects (on CPU) and puts the memory objects of layer i-1 to the
+            storage backends. In the last iteration, it puts the memory objects
+            of the last layer to the storage backends.
+        """
+        # Health check: block operation if LMCache is unhealthy
+        if not self.is_healthy():
+            logger.warning("LMCache is unhealthy, skipping store_layer operation")
+            return
+
+        assert self.storage_manager is not None
+        assert self.gpu_connector is not None, (
+            "gpu_connector is required for store_layer operation"
+        )
+
+        # Get req_id for logging
+        req_id = self._get_req_id(kwargs)
+
+        if mask is not None:
+            num_to_store_tokens = torch.sum(mask).item()
+        else:
+            num_to_store_tokens = len(tokens)
+
+        # KVCache Check logging
+        self._log_kvcache_for_check(
+            operation="Layerwise store",
+            kwargs=kwargs,
+            token_count=num_to_store_tokens,
+            require_req_id=True,
+        )
+
+        monitor_req_id = self.stats_monitor.on_store_request(num_to_store_tokens)
+
+        # Check if freeze mode is enabled
+        if self.is_frozen():
+            logger.debug(
+                "Freeze mode enabled, skipping store_layer for %d tokens",
+                num_to_store_tokens,
+            )
+            # Still need to yield to avoid StopIteration
+            for layer_id in range(self.num_layers):
+                yield
+            return
+
+        starts = []
+        ends = []
+        keys = []
+        memory_objs = []
+        tot_token_num = 0
+        kv_dtype = self.metadata.kv_dtype
+        request_configs = kwargs.get("request_configs")
+        if request_configs is not None and len(request_configs) != 0:
+            assert isinstance(request_configs, dict)
+
+        prev_key = 0
+        for start, end, key in self.token_database.process_tokens(
+            tokens=tokens, mask=mask, request_configs=request_configs
+        ):
+            assert isinstance(key, CacheEngineKey)
+
+            keys_multi_layer = key.split_layers(self.num_layers)
+            # Only check the first layer
+            if self.storage_manager.contains(
+                keys_multi_layer[0], self.retrieve_locations
+            ):
+                continue
+
+            # Allocate the memory object
+            num_tokens = end - start
+            kv_shape_single_layer = self.gpu_connector.get_shape(num_tokens)
+
+            memory_objs_multi_layer = self.storage_manager.batched_allocate(
+                kv_shape_single_layer,
+                kv_dtype,
+                batch_size=self.num_layers,
+                fmt=self.fmt,
+                busy_loop=self.config.get_extra_config_value("force_store_wait", False),
+            )
+
+            if memory_objs_multi_layer is None:
+                logger.warning(
+                    "Local cpu memory under pressure so"
+                    " choosing to not store the KV cache."
+                )
+                break
+
+            starts.append(start)
+            ends.append(end)
+            keys.append(keys_multi_layer)
+            memory_objs.append(memory_objs_multi_layer)
+            tot_token_num += num_tokens
+
+            # Create KV event
+            if self.kv_events_enabled and tokens is not None:
+                stored_event = CacheStoreEvent(
+                    block_hashes=[key.chunk_hash],
+                    parent_block_hash=None if start == 0 else prev_key,
+                    token_ids=[],
+                    block_size=num_tokens,
+                    lora_id=None,
+                    medium="cpu",
+                    lora_name=None,
+                )
+                if tokens is not None:
+                    stored_event.token_ids = convert_tokens_to_list(
+                        tokens,
+                        start,
+                        end,
+                    )
+                    if isinstance(tokens, torch.Tensor):
+                        stored_event.medium = tokens.device
+                logger.debug(
+                    "Added kv cache event '%s' to kv cache events queue",
+                    stored_event,
+                )
+                self.kv_events.append(stored_event)
+                prev_key = key.chunk_hash
+
+        if keys:
+            # Transpose the keys and memory objects into layer major format
+            memory_objs = [list(row) for row in zip(*memory_objs, strict=False)]
+            keys = [list(row) for row in zip(*keys, strict=False)]
+
+            # Calculate total KV size for logging
+            tot_kv_size = sum(
+                mo.get_size() for layer_objs in memory_objs for mo in layer_objs
+            )
+
+            assert_layerwise_gpu_connector(self.gpu_connector)
+
+            t_start = time.perf_counter()
+            mem_obj_generator = self.gpu_connector.batched_from_gpu(
+                memory_objs, starts, ends, **kwargs
+            )
+
+            next(mem_obj_generator)
+
+            for layer_id in range(self.num_layers):
+                yield
+                next(mem_obj_generator)
+                self.storage_manager.batched_put(
+                    keys[layer_id], memory_objs[layer_id], location=self.store_location
+                )
+
+            tot_time = time.perf_counter() - t_start
+            logger.info(
+                "[req_id=%s] Stored %d out of total %d tokens. "
+                "size: %.4f GB, cost %.4f ms, throughput: %.4f GB/s",
+                req_id,
+                tot_token_num,
+                len(tokens),
+                tot_kv_size / 1024**3,
+                tot_time * 1000,
+                tot_kv_size / tot_time / 1024**3 if tot_time > 0 else 0,
+            )
+        else:
+            # If no cache are found, we still need to yield to avoid
+            # `StopIteration`
+            for layer_id in range(self.num_layers):
+                yield
+
+        self.stats_monitor.on_store_finished(monitor_req_id, tot_token_num)
+        yield
+
+    @_lmcache_nvtx_annotate
+    @torch.inference_mode()
+    def retrieve(
+        self,
+        tokens: Union[torch.Tensor, list[int]],
+        mask: Optional[torch.Tensor] = None,
+        **kwargs,
+    ) -> torch.Tensor:
+        """Retrieve the KV caches from the cache engine. And put the retrieved
+        KV cache to the serving engine via the GPU connector.
+
+        :param torch.Tensor tokens: The tokens of the corresponding KV caches.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched,
+            and the Falses will ALWAYS be at the PREFIX of the tensor.
+
+        :param **kwargs: The additional arguments for the storage backend which
+            will be passed into the gpu_connector.
+            Should include KV cache specific information (e.g., paged KV buffer
+            and the page tables).
+
+        :return: the boolean mask indicating which tokens are retrieved. The
+            length of the mask should be the same as the tokens. On CPU.
+
+        :raises: ValueError if the number of Falses in the mask is not a
+            multiple of the chunk size.
+        """
+        # Health check: block operation if LMCache is unhealthy
+        if not self.is_healthy():
+            logger.warning("LMCache is unhealthy, skipping retrieve operation")
+            return torch.zeros(len(tokens), dtype=torch.bool)
+
+        assert self.gpu_connector is not None, (
+            "gpu_connector is required for retrieve operation"
+        )
+
+        # Get req_id for logging
+        req_id = self._get_req_id(kwargs)
+
+        tot_kv_size = 0
+
+        if mask is not None:
+            num_required_tokens = torch.sum(mask).item()
+        else:
+            num_required_tokens = len(tokens)
+
+        # KVCache Check logging
+        self._log_kvcache_for_check(
+            operation="retrieve",
+            kwargs=kwargs,
+            token_count=num_required_tokens,
+            require_req_id=True,
+        )
+
+        retrieve_stats = self.stats_monitor.on_retrieve_request(num_required_tokens)
+
+        ret_mask = torch.zeros(len(tokens), dtype=torch.bool, device="cpu")
+
+        reordered_chunks: List[ProcessedChunk] = []
+        if not self._is_passive():
+            with retrieve_stats.profile_process_tokens():
+                if self.async_loading:
+                    reordered_chunks, tot_kv_size = self._async_process_tokens_internal(  # noqa: E501
+                        tokens,
+                        mask,
+                        ret_mask,
+                        **kwargs,
+                    )
+                else:
+                    reordered_chunks, tot_kv_size = self._process_tokens_internal(
+                        tokens,
+                        mask,
+                        ret_mask,
+                        **kwargs,
+                    )
+
+        if self.save_only_first_rank:
+            with retrieve_stats.profile_broadcast():
+                with torch_dev.stream(self.broadcast_stream):
+                    self._broadcast_or_receive_memory_objs(
+                        reordered_chunks,
+                        ret_mask,
+                    )
+
+                # if self.gpu_connector has load_stream, self.broadcast_stream is equals
+                # to self.gpu_connector.load_stream, the broadcast and to_gpu operation
+                # will execute sequentially within the stream.
+                # if self.gpu_connector does not have load_stream, self.broadcast_stream
+                # is created by torch_dev.Stream(), we need to synchronize broadcast
+                # operation, and then process to_cpu operation.
+                if not hasattr(self.gpu_connector, "load_stream"):
+                    self.broadcast_stream.synchronize()
+
+        # NOTE(Jiayi): memory_obj doesn't have to be a pinned
+        # cpu tensor for the sake of performance.
+        # For example, disk->gpu is faster than disk->cpu->gpu.
+        # RDMA is another example.
+        if len(reordered_chunks) > 0:
+            with retrieve_stats.profile_to_gpu():
+                _, memory_objs, starts, ends = zip(*reordered_chunks, strict=False)
+                # When save_only_first_rank is enabled, the leader rank's
+                # memory_objs from L1 are CPU-resident. The broadcast above
+                # already created GPU-resident copies on the leader to use as
+                # the NCCL send buffer. Substitute those here so this kernel
+                # reads from HBM rather than re-reading the same L1 bytes
+                # over PCIe via zero-copy mapped pinned memory. Without this
+                # swap, batched_to_gpu on the leader takes ~9 ms (PCIe-bound)
+                # while passive ranks take ~0.5 ms (HBM-bound) — a structural
+                # asymmetry on the critical path of every retrieve.
+                if self.save_only_first_rank and self.metadata.is_first_rank():
+                    if len(self._leader_gpu_substitute_objs) == len(memory_objs):
+                        memory_objs_for_togpu = self._leader_gpu_substitute_objs
+                    else:
+                        # Substitute list should always match memory_objs after
+                        # _broadcast_or_receive_memory_objs has run on the
+                        # leader.  A mismatch indicates a bug or stale state;
+                        # fall back to the CPU L1 source so retrieval is still
+                        # correct, but warn so the issue is visible.
+                        logger.warning(
+                            "Leader rank: GPU substitute count (%d) does not "
+                            "match memory_objs count (%d); falling back to "
+                            "CPU L1 source for batched_to_gpu (PCIe-bound, "
+                            "~9 ms slower).",
+                            len(self._leader_gpu_substitute_objs),
+                            len(memory_objs),
+                        )
+                        memory_objs_for_togpu = list(memory_objs)
+                else:
+                    memory_objs_for_togpu = list(memory_objs)
+                try:
+                    self.gpu_connector.batched_to_gpu(
+                        memory_objs_for_togpu, list(starts), list(ends), **kwargs
+                    )
+                finally:
+                    # Release GPU substitute references so the temporary
+                    # buffers can be freed; original memory_objs in
+                    # reordered_chunks are still tracked for the cleanup
+                    # loop below. Done in `finally` so a raise from
+                    # batched_to_gpu (e.g. CUDA OOM) does not leave the
+                    # references dangling on this long-lived engine.
+                    if self.save_only_first_rank and self.metadata.is_first_rank():
+                        self._leader_gpu_substitute_objs = []
+
+        # TODO(Jiayi): Remove the following for loop with batched operations
+        # TODO(Jiayi): Need to refactor the `remove_after_retrieve` logic.
+        for key, memory_obj, _, _ in reordered_chunks:
+            if self.remove_after_retrieve and not self._is_passive():
+                assert self.storage_manager is not None
+                self.storage_manager.remove(key, self.retrieve_locations)
+                # Sync PDBackend.remove() does NOT call ref_count_down() internally
+                # (unlike async PD and other backends), so we must call it manually.
+                # See pd_backend.py line 605 TODO comment.
+                if self._is_sync_pd_backend():
+                    memory_obj.ref_count_down()
+            else:
+                if memory_obj.is_pinned:
+                    memory_obj.unpin()
+                memory_obj.ref_count_down()
+
+        retrieved_tokens = torch.sum(ret_mask)
+        self.stats_monitor.on_retrieve_finished(
+            retrieve_stats,
+            retrieved_tokens,
+        )
+        onload_time = retrieve_stats.time_to_retrieve()
+        # The retrieved may be larger than the need_to_load
+        # Example (page_size=16, chunk_size=256):
+        #
+        # chunks:  [0..255]                [256..511]
+        # pages:   [0..15]...[240..255]    [256..271][272..287] ...
+        #
+        # num_computed_tokens = 288 => vLLM already has [0..287] (18 pages)
+        # LMCache hit_prefix_tokens = 512 => cache covers [0..511] (2 chunks)
+        #
+        # Skip chunk 1, retrieve chunk 2, overwrite [256..287] (32-token overlap)
+        # need_to_load: 512 - 288 = 224 tokens
+        # retrieved: 256 tokens
+        if not self._is_passive():
+            logger.info(
+                "[req_id=%s] Retrieved %d out of %d required tokens "
+                "(from %d total tokens). size: %.4f gb, "
+                "cost %.4f ms, throughput: %.4f GB/s;",
+                req_id,
+                retrieved_tokens,
+                num_required_tokens,
+                len(tokens),
+                tot_kv_size / 1024**3,
+                onload_time * 1000,
+                tot_kv_size / onload_time / 1024**3 if onload_time > 0 else 0,
+            )
+        return ret_mask
+
+    @_lmcache_nvtx_annotate
+    @torch.inference_mode()
+    def retrieve_layer(
+        self,
+        tokens: Union[torch.Tensor, list[int]],
+        mask: Optional[torch.Tensor] = None,
+        **kwargs,
+    ) -> Generator[Optional[torch.Tensor], None, None]:
+        """
+        Retrieve the KV cache in a layerwise manner.
+
+        :param torch.Tensor tokens: The tokens of the corresponding KV caches.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched.
+
+        :param **kwargs: The additional arguments for the storage backend which
+            will be passed into the gpu_connector.
+
+        return: A generator that yields Optional[torch.Tensor]. The tensor will
+            be the boolean mask indicating which tokens are retrieved and will
+            only be returned in the last iteration. In the first iteration,
+            the generator retrieve the memory objects of the first layer from
+            the storage backends. In the next iterations, it moves the KV cache
+            of layer i from the memory objects (on CPU) to GPU and retrieves
+            the memory objects of layer i+1 from the storage backends. In the
+            last iteration, it moves the memory objects of the last layer to
+            the GPU.
+        """
+        # Health check: block operation if LMCache is unhealthy
+        if not self.is_healthy():
+            logger.warning("LMCache is unhealthy, skipping retrieve_layer operation")
+            yield torch.zeros(len(tokens), dtype=torch.bool)
+            return
+
+        assert self.storage_manager is not None
+        assert self.gpu_connector is not None, (
+            "gpu_connector is required for retrieve_layer operation"
+        )
+
+        # Get req_id for logging
+        req_id = self._get_req_id(kwargs)
+
+        if mask is not None:
+            num_required_tokens = torch.sum(mask).item()
+        else:
+            num_required_tokens = len(tokens)
+        monitor_req_id = self.stats_monitor.on_retrieve_request(num_required_tokens)
+
+        ret_mask = torch.zeros(len(tokens), dtype=torch.bool, device="cpu")
+
+        starts = []
+        ends = []
+        keys = []
+
+        request_configs = kwargs.get("request_configs")
+        if request_configs is not None and len(request_configs) != 0:
+            assert isinstance(request_configs, dict)
+
+        location = None
+        for start, end, key in self.token_database.process_tokens(
+            tokens=tokens,
+            mask=mask,
+            request_configs=request_configs,
+        ):
+            assert isinstance(key, CacheEngineKey)
+
+            keys_multi_layer = key.split_layers(self.num_layers)
+
+            # NOTE: Only check the first layer
+            if current_location := self.storage_manager.contains(
+                keys_multi_layer[0], self.retrieve_locations
+            ):
+                if location is None:
+                    location = current_location
+                else:
+                    # TODO(Jiayi): Support multi-location retrieval in the future
+                    assert location == current_location, (
+                        "All retrieved keys should be from the same location "
+                        "when use layerwise retrieval."
+                        "Please support multi-location retrieval in the future."
+                    )
+            else:
+                break
+
+            starts.append(start)
+            ends.append(end)
+            keys.append(keys_multi_layer)
+
+            ret_mask[start:end] = True
+
+        if keys:
+            # Transpose the keys into layer major format
+            keys_layer_major = [list(row) for row in zip(*keys, strict=False)]
+
+            get_generator = self.storage_manager.layerwise_batched_get(
+                keys_layer_major,
+                location=location,
+            )
+
+            assert_layerwise_gpu_connector(self.gpu_connector)
+
+            mem_obj_consumer = self.gpu_connector.batched_to_gpu(starts, ends, **kwargs)
+            next(mem_obj_consumer)
+
+            to_count_down = []
+            for layer_id in range(self.num_layers):
+                task = next(get_generator)
+
+                assert task is not None
+
+                if layer_id == 0:
+                    # NOTE(Yuwei): For sglang integration we need to provide retrieved
+                    # tokens number in the first layer loading since there is no lookup
+                    yield torch.sum(ret_mask)
+                else:
+                    yield None
+
+                mem_objs_layer = task.result()
+                mem_obj_consumer.send(mem_objs_layer)
+                to_count_down.extend(mem_objs_layer)
+
+            for mem_obj in to_count_down:
+                mem_obj.ref_count_down()
+        else:
+            # If no cache are found, we still need to yield to avoid
+            # `StopIteration`
+            for layer_id in range(self.num_layers):
+                yield None
+
+        yield None
+
+        # synchronize the last layer
+        next(mem_obj_consumer)
+
+        # Unpin any disk-loaded staging objects now that the device-side sync
+        # has been enqueued (mem_obj_consumer advanced past its sync point).
+        # Without this, pin_count stays at 1 forever and the CPU staging pool
+        # fills up, causing the next retrieve to deadlock inside allocate().
+        for mem_obj in to_count_down:
+            if mem_obj.is_pinned:
+                mem_obj.unpin()
+
+        retrieved_tokens = torch.sum(ret_mask)
+        self.stats_monitor.on_retrieve_finished(monitor_req_id, retrieved_tokens)
+        if not self._is_passive():
+            logger.info(
+                "[req_id=%s] Retrieved %d out of %d out of total %d tokens",
+                req_id,
+                retrieved_tokens,
+                num_required_tokens,
+                len(tokens),
+            )
+
+        yield ret_mask
+
+    @_lmcache_nvtx_annotate
+    def lookup(
+        self,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        hashes: Optional[List[int]] = None,
+        offsets: Optional[List[int]] = None,
+        search_range: Optional[List[str]] = None,
+        lookup_id: Optional[str] = None,
+        pin: bool = False,
+        request_configs: Optional[dict] = None,
+    ) -> int:
+        """
+        Checks the existence of KV cache of the tokens from the cache engine.
+
+        :param Optional[Union[torch.Tensor, List[int]]] tokens: the input tokens,
+        with shape [seq_len]
+
+        :param Optional[List[int]] hashes: the input hashes, with length [num_chunks]
+        :param Optional[List[int]] offsets: the offsets of each chunk,
+        with length [num_chunks]
+
+        :param Optional[List[str]] search_range: The range of storage backends
+        to search in. Should be a subset of
+        ["LocalCPUBackend", "LocalDiskBackend"] for now.
+        If None, search in all backends.
+
+        :param Optional[str] lookup_id: The lookup ID to
+            associate with the lookup. When pin is true, this argument is
+            required to be not None.
+
+        :param bool pin: If True, pin the KV cache in the storage.
+
+        :param Optional[dict] request_configs: the configs of the request.
+
+        :return: An int indicating how many prefix tokens exist inside LMCache.
+        """
+        # Health check: block operation if LMCache is unhealthy
+        if not self.is_healthy():
+            logger.warning("LMCache is unhealthy, skipping lookup operation")
+            return 0
+
+        assert self.storage_manager is not None
+
+        if tokens is not None:
+            lookup_stats = self.stats_monitor.on_lookup_request(len(tokens))
+        else:
+            assert offsets is not None
+            assert hashes is not None
+            lookup_stats = self.stats_monitor.on_lookup_request(sum(offsets))
+
+        if search_range is None:
+            search_range = self.retrieve_locations
+
+        res = 0
+        try:
+            chunk_info_iterator = self.token_database.process_tokens(
+                tokens=tokens,
+                hashes=hashes,
+                offsets=offsets,
+                request_configs=request_configs,
+            )
+
+            # TODO: support batched_contains when layerwise is enabled
+            if self.use_layerwise:
+                for start, end, key in chunk_info_iterator:
+                    assert isinstance(key, CacheEngineKey)
+
+                    # TODO(Jiayi): Optimize by checking only the existence of the key
+                    # of one layer
+                    key_all_layers = key.split_layers(self.num_layers)
+
+                    hit_chunks, block_mapping = self.storage_manager.batched_contains(
+                        key_all_layers,  # type: ignore
+                        search_range,
+                        pin,
+                    )
+                    # Only all layers are hit and hit in one location,
+                    # we consider this key as a hit
+                    if hit_chunks == self.num_layers and len(block_mapping) == 1:
+                        if pin:
+                            assert lookup_id is not None, (
+                                "lookup_id is required when pin is True"
+                            )
+                            location = next(iter(block_mapping.keys()))
+                            self.lookup_pins[lookup_id][location].extend(key_all_layers)
+                        res = end
+                        continue
+                    return res
+            else:
+                chunk_info_list = []
+                keys = []
+                for chunk_info in chunk_info_iterator:
+                    assert isinstance(chunk_info[2], CacheEngineKey)
+                    start, end, _ = chunk_info
+                    chunk_info_list.append(chunk_info)
+                    # chunk_info contains (start, end, key)
+                    # chunk_info[2] is the key
+                    keys.append(chunk_info[2])
+                # hit chunks by prefix matching
+                hit_chunks, block_mapping = self.storage_manager.batched_contains(
+                    keys, search_range, pin
+                )
+                if pin and block_mapping:
+                    assert lookup_id is not None, (
+                        "lookup_id is required when pin is True"
+                    )
+                    self.lookup_pins[lookup_id] = block_mapping
+                for idx, (start, end, key) in enumerate(chunk_info_list):
+                    if idx < hit_chunks:
+                        res = end
+                        continue
+                    return res
+
+            # all tokens where found, return the maximal end
+            return res
+        finally:
+            self.stats_monitor.on_lookup_finished(lookup_stats, res)
+            # vllm lookup sets pin to True
+            if pin:
+                # touch_cache is tightly coupled with batched_contains
+                self.storage_manager.touch_cache()
+
+    @_lmcache_nvtx_annotate
+    def move(
+        self,
+        tokens: Union[torch.Tensor, List[int]],
+        old_position: str,
+        new_position: tuple[str, str],
+        event_id: str,
+        do_copy: bool = True,
+    ) -> int:
+        """
+        Perform cross-node move of the KV cache.
+        """
+        assert self.storage_manager is not None
+
+        num_tokens = self.lookup(
+            tokens,
+            search_range=[old_position],
+            lookup_id=event_id,
+            pin=True,
+        )
+
+        if not num_tokens:
+            logger.debug("Move is not performed as there are no tokens to move.")
+            return 0
+
+        block_mapping = self.lookup_pins[event_id]
+        assert len(block_mapping) == 1
+        keys = block_mapping[old_position]
+
+        memory_objs = self.storage_manager.batched_get(
+            keys=keys,
+            location=old_position,
+        )
+        assert None not in memory_objs, "Failed to get memory objects to move"
+        logger.debug(
+            f"Trying to send {len(memory_objs)} memory objects to {new_position}"
+        )
+
+        # TODO: reduce loops
+        token_dim = memory_objs[0].meta.fmt.token_dim()  # type: ignore
+        offsets = [m.meta.shape[token_dim] for m in memory_objs]  # type: ignore
+
+        transfer_spec = {
+            "target_peer_init_url": new_position[0],
+            "offsets": offsets,
+        }
+
+        logger.info(self.storage_manager.storage_backends)
+        p2p_backend = self.storage_manager.storage_backends["P2PBackend"]
+
+        future = asyncio.run_coroutine_threadsafe(
+            p2p_backend.async_batched_submit_put_task(
+                keys,
+                memory_objs,  # type: ignore
+                transfer_spec=transfer_spec,
+            ),
+            self.storage_manager.loop,
+        )
+
+        future.result()
+
+        if not do_copy:
+            self.storage_manager.batched_remove(keys, locations=[old_position])
+
+        logger.debug(
+            "Moving %d token from %s to %s", num_tokens, old_position, new_position
+        )
+        return num_tokens
+
+    # TODO(Jiayi): Add layerwise support.
+    @_lmcache_nvtx_annotate
+    def async_lookup_and_prefetch(
+        self,
+        lookup_id: str,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        hashes: Optional[List[int]] = None,
+        offsets: Optional[List[int]] = None,
+        search_range: Optional[List[str]] = None,
+        pin: bool = False,
+        request_configs: Optional[dict] = None,
+    ) -> None:
+        """
+        An async version of lookup + prefetch.
+
+        There are three categories of backends:
+        (1) sync lookup + sync retrieval (e.g., cpu)
+        (2) sync lookup + async retrieval (e.g., disk)
+        (3) async lookup + async retrieval (e.g., p2p)
+        """
+        assert self.storage_manager is not None
+
+        keys: list[CacheEngineKey] = []
+        cum_chunk_lengths = [0]
+
+        if search_range is None:
+            search_range = self.retrieve_locations
+
+        # When layerwise is enabled, store_layer writes per-layer keys
+        # (LayerCacheEngineKey, chunk_hash + layer_id). Async lookup must
+        # split each chunk key into num_layers per-layer keys so the
+        # storage backend hot_cache lookups match the same key type.
+        keys_per_chunk = self.num_layers if self.use_layerwise else 1
+
+        # TODO(Jiayi): make token database able to return list.
+        for start, end, key in self.token_database.process_tokens(
+            tokens=tokens,
+            hashes=hashes,
+            offsets=offsets,
+            request_configs=request_configs,
+        ):
+            assert isinstance(key, CacheEngineKey)
+            if self.use_layerwise:
+                keys.extend(key.split_layers(self.num_layers))
+            else:
+                keys.append(key)
+            cum_chunk_lengths.append(end)
+
+        asyncio.run_coroutine_threadsafe(
+            self.storage_manager.async_lookup_and_prefetch(
+                lookup_id,
+                keys,
+                cum_chunk_lengths,
+                search_range,
+                pin,
+                keys_per_chunk=keys_per_chunk,
+            ),
+            self.storage_manager.loop,
+        )
+
+    def cleanup_memory_objs(self, lookup_id: str) -> None:
+        """
+        Cleanup memory objects allocated during prefetch for an aborted lookup.
+
+        Called by the scheduler when it determines that an aborted lookup
+        has finished its prefetch tasks.
+        """
+        try:
+            # Get the completed future from event_manager
+            if (
+                self.event_manager.get_event_status(EventType.LOADING, lookup_id)
+                != EventStatus.DONE
+            ):
+                logger.debug(
+                    "No completed event found for lookup_id=%s to clean up.", lookup_id
+                )
+                return
+            future = self.event_manager.pop_event(EventType.LOADING, lookup_id)
+
+            # Get memory objects from the future result
+            memory_objs = future.result()
+            # Flatten nested lists (each backend returns a list of chunks)
+            memory_objs_flat = [mm for m in memory_objs for mm in m]
+
+            # Release each memory object
+            for key, memory_obj in memory_objs_flat:
+                try:
+                    logger.debug("Releasing memory object for lookup_id=%s", lookup_id)
+                    if memory_obj.is_pinned:
+                        memory_obj.unpin()
+                    memory_obj.ref_count_down()
+                except Exception as e:
+                    logger.error("Error releasing memory object: %s", e)
+        except Exception as e:
+            logger.error(
+                "Error during cleanup_memory_objs for lookup_id=%s: %s",
+                lookup_id,
+                e,
+            )
+
+    # TODO(Jiayi): Need to handle the case where `tokens=None`.
+    # In this case, we compress all tokens.
+    # TODO(Jiayi): support other compression methods.
+    @_lmcache_nvtx_annotate
+    def compress(
+        self,
+        tokens: Union[torch.Tensor, List[int]],
+        method: str,
+        location: str,
+        event_id: str,
+    ) -> int:
+        assert self.storage_manager is not None
+        if method not in ["cachegen"]:
+            logger.warning("Unsupported compression method: %s.", method)
+            return 0
+
+        # First Party
+        from lmcache.v1.storage_backend.naive_serde import CreateSerde
+
+        serializer, _ = CreateSerde(method, self.metadata, self.config)
+
+        num_tokens = self.lookup(
+            tokens,
+            search_range=[location],
+            lookup_id=event_id,
+            pin=True,
+        )
+
+        if not num_tokens:
+            logger.debug("Move is not performed as there are no tokens to move.")
+            return 0
+
+        block_mapping = self.lookup_pins[event_id]
+        assert len(block_mapping) == 1
+        keys = block_mapping[location]
+
+        memory_objs = self.storage_manager.batched_get(
+            keys=keys,
+            location=location,
+        )
+        assert None not in memory_objs, (
+            "LMCacheEngine.compress: Failed to get memory objects to compress"
+        )
+
+        compressed_memory_objs = []
+        for memory_obj in memory_objs:
+            assert memory_obj is not None
+            compressed_memory_obj = serializer.serialize(memory_obj)
+            if memory_obj.is_pinned:
+                memory_obj.unpin()
+            compressed_memory_objs.append(compressed_memory_obj)
+
+        self.storage_manager.batched_remove(keys, locations=[location])
+
+        self.storage_manager.batched_put(
+            keys=keys,
+            memory_objs=compressed_memory_objs,
+            location=location,
+        )
+
+        return num_tokens
+
+    @_lmcache_nvtx_annotate
+    def decompress(
+        self,
+        tokens: Union[torch.Tensor, List[int]],
+        method: str,
+        location: str,
+        event_id: str,
+    ) -> int:
+        assert self.storage_manager is not None
+        if method not in ["cachegen"]:
+            logger.warning("Unsupported decompression method: %s.", method)
+            return 0
+
+        # First Party
+        from lmcache.v1.storage_backend.naive_serde import CreateSerde
+
+        _, deserializer = CreateSerde(method, self.metadata, self.config)
+
+        num_tokens = self.lookup(
+            tokens,
+            search_range=[location],
+            lookup_id=event_id,
+            pin=True,
+        )
+
+        if not num_tokens:
+            logger.debug("there are no tokens to decompress.")
+            return 0
+
+        block_mapping = self.lookup_pins[event_id]
+        assert len(block_mapping) == 1
+        keys = block_mapping[location]
+
+        compressed_memory_objs = self.storage_manager.batched_get(
+            keys=keys,
+            location=location,
+        )
+
+        assert None not in compressed_memory_objs, (
+            "LMCacheEngine.compress: Failed to get compressed "
+            "memory objects to decompress"
+        )
+
+        memory_objs = []
+        for compressed_memory_obj in compressed_memory_objs:
+            assert compressed_memory_obj is not None
+            memory_obj = deserializer.deserialize(compressed_memory_obj)
+            if compressed_memory_obj.is_pinned:
+                compressed_memory_obj.unpin()
+            memory_objs.append(memory_obj)
+
+        self.storage_manager.batched_remove(keys, locations=[location])
+
+        self.storage_manager.batched_put(
+            keys=keys,
+            memory_objs=memory_objs,
+            location=location,
+        )
+
+        return num_tokens
+
+    @_lmcache_nvtx_annotate
+    def lookup_unpin(self, lookup_id: str) -> None:
+        if lookup_id in self.lookup_pins:
+            assert self.storage_manager is not None
+            for location, keys in self.lookup_pins.pop(lookup_id).items():
+                self.storage_manager.batched_unpin(keys, [location])
+
+        elif (
+            self.async_loading is not None
+            and self.event_manager.get_event_status(EventType.LOADING, lookup_id)
+            != EventStatus.NOT_FOUND
+        ):
+            self.cleanup_memory_objs(lookup_id)
+
+    @_lmcache_nvtx_annotate
+    def clear(
+        self,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        locations: Optional[List[str]] = None,
+        request_configs: Optional[dict] = None,
+    ) -> int:
+        # TODO: need to clear by request_configs
+        if self.save_only_first_rank:
+            if self.metadata.is_first_rank():
+                num_removed = self._clear(tokens, locations, request_configs)
+                return num_removed
+            else:
+                return 0
+        return self._clear(tokens, locations, request_configs)
+
+    @_lmcache_nvtx_annotate
+    def get_kv_events(self) -> Iterable[CacheStoreEvent]:
+        if self.kv_events_enabled and (events := self.kv_events):
+            self.kv_events = []
+            return events
+        return []
+
+    def _clear(
+        self,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        locations: Optional[List[str]] = None,
+        request_configs: Optional[dict] = None,
+    ) -> int:
+        assert self.storage_manager is not None
+        assert isinstance(self.storage_manager, StorageManager)
+        # Clear all caches if tokens is None
+        if tokens is None or len(tokens) == 0:
+            num_cleared = self.storage_manager.clear(locations)
+            return num_cleared
+
+        num_removed = 0
+        # Only remove the caches for the given tokens
+        for start, end, key in self.token_database.process_tokens(
+            tokens=tokens, request_configs=request_configs
+        ):
+            assert isinstance(key, CacheEngineKey)
+            removed = self.storage_manager.remove(key, locations)
+            num_removed += removed
+        return num_removed
+
+    @_lmcache_nvtx_annotate
+    def health(
+        self,
+    ) -> int:
+        """
+        Check the health of the cache engine.
+        return: 0 if healthy, otherwise the error code
+        """
+        assert self.storage_manager is not None
+        return 0 if self.storage_manager.memcheck() else -1
+
+    def close(self) -> None:
+        """Close the cache engine and free all the resources"""
+        logger.info("Closing LMCacheEngine...")
+
+        if self.hidden_state_store is not None:
+            try:
+                logger.info("Closing hidden_state_store...")
+                self.hidden_state_store.close()
+            except Exception as e:
+                logger.error(f"Error closing hidden_state_store: {e}")
+
+        if self.lmcache_worker is not None:
+            try:
+                logger.info("Closing lmcache_worker...")
+                self.lmcache_worker.close()
+                logger.info("lmcache_worker closed successfully")
+            except Exception as e:
+                logger.error("Error closing lmcache_worker: %s", e)
+
+        try:
+            logger.info("Closing storage_manager...")
+            if self.storage_manager is not None:
+                self.storage_manager.close()
+            logger.info("storage_manager closed successfully")
+        except Exception as e:
+            logger.error("Error closing storage_manager: %s", e)
+
+        logger.info("LMCacheEngine closed.")
+
+    def _async_process_tokens_internal(
+        self,
+        tokens,
+        mask,
+        ret_mask,
+        **kwargs,
+    ) -> ProcessTokensInternalResult:
+        """
+        This function is used to get the memory objects from the event manager.
+
+        Args:
+            tokens: Input tokens to process
+            mask: Mask indicating valid token positions
+            ret_mask: Output mask updated with cache hit positions
+            **kwargs: Additional keyword arguments
+        """
+        assert "req_id" in kwargs, "req_id is required for async loading"
+        request_configs = kwargs.get("request_configs")
+        if request_configs is not None and len(request_configs) != 0:
+            assert isinstance(request_configs, dict)
+
+        tot_kv_size = 0
+        chunks: List[ProcessedChunk] = []
+        future = self.event_manager.get_event_future(
+            EventType.LOADING, kwargs["req_id"]
+        )
+        # As mentioned in async_lookup_and_prefetch(), the future.result()
+        # is key data pair for each chunk in each tier. So extract the key
+        # and memory object pairs to memory_obj_map
+        try:
+            keyed_memory_objs = future.result()
+            memory_obj_map: dict[CacheEngineKey, MemoryObj] = {}
+        except Exception as e:
+            logger.error("Error popping event for request %s: %s", kwargs["req_id"], e)
+            return [], 0
+
+        for backend_results in keyed_memory_objs:
+            for key, memory_obj in backend_results:
+                memory_obj_map[key] = memory_obj
+
+        # TODO(Jiayi): hashing inside `process_tokens` can be skipped.
+        used_keys: set[CacheEngineKey] = set()
+        for start, end, key in self.token_database.process_tokens(
+            tokens=tokens,
+            mask=mask,
+            request_configs=request_configs,
+        ):
+            assert isinstance(key, CacheEngineKey)
+            memory_obj = memory_obj_map.get(key)
+            if memory_obj is None:
+                # returned chunks are expected to be contiguous.
+                # break at the first missing chunk.
+                break
+            chunks.append((key, memory_obj, start, end))
+            tot_kv_size += memory_obj.get_size()
+            ret_mask[start:end] = True
+            used_keys.add(key)
+
+        # NOTE: free the memory objects that are not hit.
+        for key, mem_obj in memory_obj_map.items():
+            if key not in used_keys:
+                mem_obj.ref_count_down()
+
+        return chunks, tot_kv_size
+
+    def _process_tokens_internal(
+        self,
+        tokens,
+        mask,
+        ret_mask,
+        **kwargs,
+    ) -> ProcessTokensInternalResult:
+        """Process tokens and populate the reordered lists.
+
+        This function is used to process tokens and populate the reordered lists.
+
+        Args:
+            tokens: Input tokens to process
+            mask: Mask indicating valid token positions
+            ret_mask: Output mask updated with cache hit positions
+            **kwargs: Additional keyword arguments
+        """
+        assert self.storage_manager is not None
+
+        tot_kv_size = 0
+        reordered_chunks: List[ProcessedChunk] = []
+        request_configs = kwargs.get("request_configs")
+        if request_configs is not None and len(request_configs) != 0:
+            assert isinstance(request_configs, dict)
+
+        chunk_infos = []
+        for start, end, key in self.token_database.process_tokens(
+            tokens=tokens,
+            mask=mask,
+            request_configs=request_configs,
+        ):
+            assert isinstance(key, CacheEngineKey)
+            chunk_infos.append((key, start, end))
+
+        # block_mapping: location -> [(CacheEngineKey, start, end)]
+        if (
+            "req_id" in kwargs
+            and kwargs["req_id"] in self.lookup_pins
+            and len(self.lookup_pins[kwargs["req_id"]]) == 1
+        ):
+            location = next(iter(self.lookup_pins[kwargs["req_id"]].keys()))
+            block_mapping = {location: chunk_infos}
+        else:
+            block_mapping = self.storage_manager.get_block_mapping(chunk_infos)
+
+        last_failed_block_start = None
+        for location, blocks in block_mapping.items():
+            keys = [key for key, _, _ in blocks]
+            memory_objs = self.storage_manager.batched_get(
+                keys=keys,
+                location=location,
+            )
+
+            used_keys: set[CacheEngineKey] = set()
+            for (key, start, end), memory_obj in zip(blocks, memory_objs, strict=False):
+                if memory_obj is None:
+                    logger.warning(
+                        "The cache block is in the storage, but it can't be retrieved"
+                    )
+                    if (
+                        last_failed_block_start is None
+                        # The minimum value should be taken here to ensure that
+                        # the prefix keys are all consecutive successful.
+                        or last_failed_block_start > start
+                    ):
+                        last_failed_block_start = start
+                    break
+                reordered_chunks.append((key, memory_obj, start, end))
+                tot_kv_size += memory_obj.get_size()
+                ret_mask[start:end] = True
+                used_keys.add(key)
+
+            for (key, _, _), memory_obj in zip(blocks, memory_objs, strict=False):
+                if memory_obj is not None and key not in used_keys:
+                    logger.debug(
+                        "ref_count_down for %s of %s as the previous key failed",
+                        key,
+                        location,
+                    )
+                    memory_obj.ref_count_down()
+
+        if last_failed_block_start is not None:
+            ret_mask[last_failed_block_start:] = False
+
+            kept_chunks: List[ProcessedChunk] = []
+            for key, memory_obj, start, end in reordered_chunks:
+                if end <= last_failed_block_start:
+                    kept_chunks.append((key, memory_obj, start, end))
+                else:
+                    tot_kv_size -= memory_obj.get_size()
+                    # This chunk will not be used. If the engine is configured
+                    # to remove-after-retrieve, the caller would normally call
+                    # remove (which frees the block), but since we are dropping
+                    # these chunks here, we must free them ourselves to avoid
+                    # leaking PD buffer pool memory.
+                    if self.remove_after_retrieve:
+                        assert self.storage_manager is not None
+                        self.storage_manager.remove(key, self.retrieve_locations)
+                        # Sync PDBackend.remove() does NOT call ref_count_down()
+                        # internally (unlike async PD and other backends), so we
+                        # must call it manually. See pd_backend.py line 605.
+                        if self._is_sync_pd_backend():
+                            memory_obj.ref_count_down()
+                    else:
+                        memory_obj.ref_count_down()
+            reordered_chunks = kept_chunks
+        return reordered_chunks, tot_kv_size
+
+    def _broadcast_or_receive_memory_objs(
+        self,
+        reordered_chunks,
+        ret_mask,
+    ):
+        """
+        Handles broadcasting or receiving memory objects in a distributed environment.
+
+        This function implements the communication logic where:
+        - The first rank (coordinator) broadcasts memory objects and metadata to others
+        - Other ranks receive and reconstruct the memory objects
+
+        Parameters:
+        reordered_chunks: List of tuples containing [key, memory object, start, end]
+        ret_mask: Boolean mask indicating which positions have been processed
+
+        Side Effects:
+        - On first rank:
+          * Broadcasts chunk count and each chunk's combined metadata
+          * Broadcasts tensor data
+        - On other ranks:
+          * Receives chunk data and populates reordered_chunks
+          * Updates ret_mask to mark received positions as True
+        """
+        if self.metadata.is_first_rank():
+            # Broadcast total chunk count
+            chunk_count = len(reordered_chunks)
+            self.broadcast_object_fn(chunk_count, self.metadata.first_rank)
+
+            # Reset the GPU-resident copy list. We populate it during this
+            # broadcast loop so the caller's subsequent batched_to_gpu can
+            # read from HBM instead of re-reading the same CPU L1 buffer
+            # over PCIe. (Declared in __init__; reassigning to a fresh list
+            # rather than .clear() to drop any references the caller's
+            # finally block missed if a previous retrieve raised.)
+            self._leader_gpu_substitute_objs = []
+
+            # Broadcast each chunk's data
+            for key, memory_obj, start, end in reordered_chunks:
+                # Combine (start, end) and metadata into single broadcast
+                metadata_dict = memory_obj.metadata.to_dict()
+                combined_metadata = (start, end, metadata_dict)
+                self.broadcast_object_fn(combined_metadata, self.metadata.first_rank)
+
+                # Broadcast tensor data
+                raw_tensor = memory_obj.raw_tensor
+                assert raw_tensor is not None
+                tensor_to_broadcast = raw_tensor.to(
+                    f"{torch_device_type}:{self.metadata.worker_id}"
+                )
+                self.broadcast_fn(tensor_to_broadcast, self.metadata.first_rank)
+
+                # Keep this GPU-resident copy alive so the subsequent
+                # batched_to_gpu can read from HBM rather than re-reading
+                # the L1 buffer over PCIe.
+                gpu_mo = TensorMemoryObj(
+                    raw_data=tensor_to_broadcast,
+                    metadata=memory_obj.metadata,
+                    parent_allocator=None,
+                )
+                self._leader_gpu_substitute_objs.append(gpu_mo)
+        else:
+            # Receive total chunk count
+            chunk_count = self.broadcast_object_fn(None, self.metadata.first_rank)
+            if chunk_count is None:
+                logger.warning(
+                    "rank=%d received None chunk_count", self.metadata.worker_id
+                )
+                return
+
+            # Fill reordered_chunks with received data
+            for _ in range(chunk_count):
+                # Receive combined metadata (start, end, metadata_dict)
+                combined_metadata = self.broadcast_object_fn(
+                    None, self.metadata.first_rank
+                )
+                if combined_metadata is None:
+                    logger.warning(
+                        "rank=%d received None combined_metadata",
+                        self.metadata.worker_id,
+                    )
+                    break
+                start, end, metadata_dict = combined_metadata
+                ret_mask[start:end] = True
+
+                # Create tensor and receive data
+                metadata = MemoryObjMetadata.from_dict(metadata_dict)
+                local_rank = self.metadata.worker_id % torch_dev.device_count()
+                raw_tensor = torch.empty(
+                    torch.Size([metadata.get_size()]),
+                    dtype=torch.uint8,
+                    device=f"{torch_device_type}:{local_rank}",
+                )
+                self.broadcast_fn(raw_tensor, self.metadata.first_rank)
+
+                # Create temporary memory object (key not needed for other ranks)
+                memory_obj = TensorMemoryObj(
+                    raw_data=raw_tensor, metadata=metadata, parent_allocator=None
+                )
+                reordered_chunks.append((None, memory_obj, start, end))
+
+    def _is_passive(self):
+        """
+        A 'passive' CacheEngine means that the node itself will not store/retrieve
+        the data directly, but from the "active" worker (i.e., rank 0 in MLA)
+        """
+        return self.save_only_first_rank and not self.metadata.is_first_rank()
+
+    def _is_sync_pd_backend(self) -> bool:
+        """Check if the PD backend is the sync variant.
+
+        :return: True when PD is enabled and ``pd_backend_mode`` is ``"sync"``.
+        :rtype: bool
+        """
+        return self.config.enable_pd and self.config.pd_backend_mode == "sync"
+
+    def _get_slot_mapping_list(
+        self,
+        slot_mapping: Optional[Union[torch.Tensor, List[int]]],
+    ) -> Optional[List[int]]:
+        """
+        Convert slot_mapping to list if it's a tensor, otherwise return as is.
+
+        :param slot_mapping: The slot_mapping to convert,
+            can be a torch.Tensor or List[int], or None
+        :type slot_mapping: Optional[Union[torch.Tensor, List[int]]]
+        :return: The slot_mapping as a List[int], or None if input is None
+        :rtype: Optional[List[int]]
+        """
+        if slot_mapping is None:
+            return None
+        if isinstance(slot_mapping, torch.Tensor):
+            return slot_mapping.tolist()
+        # At this point, slot_mapping must be List[int]
+        return slot_mapping
+
+    def _log_kvcache_for_check(
+        self,
+        operation: str,
+        kwargs: dict,
+        token_count: int,
+        require_req_id: bool = False,
+    ) -> None:
+        """
+        Helper method to log KVCache Check information.
+
+        This method centralizes the KVCache Check logging logic that was
+        duplicated in multiple methods.
+
+        Args:
+            operation: The operation being performed (e.g., "Store", "retrieve")
+            kwargs: The keyword arguments containing slot_mapping and req_id
+            token_count: The number of tokens involved in the operation
+            require_req_id: Whether req_id must be present (default: False)
+        """
+        if not self.kvcache_check_log_enabled:
+            return
+
+        slot_mapping = kwargs.get("slot_mapping")
+        if slot_mapping is None:
+            return
+
+        if require_req_id:
+            req_id = kwargs.get("req_id")
+            if req_id is None:
+                return
+        else:
+            req_id = kwargs.get("req_id", "unspecified")
+
+        # Convert slot_mapping to list if it's a tensor
+        slot_mapping_list = self._get_slot_mapping_list(slot_mapping)
+        # slot_mapping_list should not be None when slot_mapping is not None
+        assert slot_mapping_list is not None
+
+        logger.info(
+            "[KVCache Check] %s request %s, tokens=%d, slot_mapping: %s",
+            operation,
+            req_id,
+            token_count,
+            compress_slot_mapping(slot_mapping_list),
+        )
+
+
+class LMCacheEngineBuilder:
+    _instances: Dict[str, LMCacheEngine] = {}
+    _cfgs: Dict[str, LMCacheEngineConfig] = {}
+    _metadatas: Dict[str, LMCacheMetadata] = {}
+    _stat_loggers: Dict[str, LMCacheStatsLogger] = {}
+
+    # TODO(Jiayi): Please remove this helper function in the future.
+    # Currently, it's only used for testing.
+    @staticmethod
+    def _Create_memory_allocator(
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        numa_mapping: Optional[NUMAMapping] = None,
+    ) -> MemoryAllocatorInterface:
+        # NOTE: should remove this function after fixing the unit tests:
+        # raise RuntimeError("_Create_memory_allocator is deprecated!")
+        extra_config = config.extra_config
+        enable_nixl_storage = extra_config is not None and extra_config.get(
+            "enable_nixl_storage"
+        )
+
+        if enable_nixl_storage:
+            # TODO(Jiayi): weird to import from transfer utils.
+            # First Party
+            from lmcache.v1.transfer_channel.transfer_utils import (
+                get_correct_device,
+            )
+
+            corrected_device = get_correct_device(
+                config.nixl_buffer_device,
+                metadata.worker_id,
+            )
+
+            buffer = torch.empty(
+                config.nixl_buffer_size,
+                dtype=torch.uint8,
+                device=corrected_device,
+            )
+
+            if corrected_device == "cpu":
+                if not current_device_spec.pin_memory(
+                    buffer.data_ptr(), config.nixl_buffer_size
+                ):
+                    raise RuntimeError("Failed to pin NIXL CPU buffer for DMA access")
+            else:
+                logger.info("Setting device to %s", corrected_device)
+                torch_dev.set_device(corrected_device)
+
+            return PagedTensorMemoryAllocator(
+                buffer,
+                [torch.Size(metadata.kv_shape)],
+                [metadata.kv_dtype],
+                MemoryFormat.KV_2LTD,
+            )
+
+        if config.gds_path is not None:
+            assert config.gds_buffer_size is not None
+            return CuFileMemoryAllocator(config.gds_buffer_size * 1024**2)
+
+        max_local_cpu_size = config.max_local_cpu_size
+        # save_only_first_rank only works when use mla
+        save_only_first_rank = (
+            config.get_extra_config_value("save_only_first_rank", metadata.use_mla)
+            and metadata.use_mla
+        )
+        if save_only_first_rank and metadata.is_first_rank():
+            # Only the first rank will save the cache,
+            # so we need to set it lager than other ranks
+            first_rank_max_local_cpu_size = (
+                config.extra_config.get(
+                    "first_rank_max_local_cpu_size", max_local_cpu_size
+                )
+                if config.extra_config
+                else max_local_cpu_size
+            )
+            return MixedMemoryAllocator(
+                int(first_rank_max_local_cpu_size * 1024**3),
+                numa_mapping=numa_mapping,
+            )
+        return MixedMemoryAllocator(
+            int(max_local_cpu_size * 1024**3),
+            numa_mapping=numa_mapping,
+        )
+
+    @staticmethod
+    def _Create_token_database(
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ) -> TokenDatabase:
+        if config.enable_blending:
+            return SegmentTokenDatabase(config, metadata)
+        return ChunkedTokenDatabase(config, metadata)
+
+    @classmethod
+    def get_or_create(
+        cls,
+        instance_id: str,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        gpu_connector: Optional[GPUConnectorInterface],
+        broadcast_fn: Callable[[torch.Tensor, int], None],
+        broadcast_object_fn: Callable[[Any, int], Any],
+    ) -> LMCacheEngine:
+        """
+        Builds a new LMCacheEngine instance if it doesn't already exist for the
+        given ID.
+
+        raises: ValueError if the instance already exists with a different
+            configuration.
+        """
+        logger.info("Creating LMCacheEngine instance %s", instance_id)
+        if instance_id not in cls._instances:
+            numa_mapping = NUMADetector.get_numa_mapping(config)
+            logger.info("NUMA mapping for instance %s: %s", instance_id, numa_mapping)
+            token_database = cls._Create_token_database(config, metadata)
+            stat_logger = LMCacheStatsLogger(
+                metadata,
+                log_interval=10,
+                config=config,
+            )
+
+            engine = LMCacheEngine(
+                config,
+                metadata,
+                token_database,
+                gpu_connector,
+                broadcast_fn,
+                broadcast_object_fn,
+            )
+
+            cls._instances[instance_id] = engine
+            cls._cfgs[instance_id] = config
+            cls._metadatas[instance_id] = metadata
+            cls._stat_loggers[instance_id] = stat_logger
+            return engine
+        else:
+            if (
+                cls._cfgs[instance_id] != config
+                or cls._metadatas[instance_id] != metadata
+            ):
+                raise ValueError(
+                    f"Instance {instance_id} already exists with a different "
+                    f"configuration or metadata."
+                )
+            return cls._instances[instance_id]
+
+    @classmethod
+    def get(cls, instance_id: str) -> Optional[LMCacheEngine]:
+        """Returns the LMCacheEngine instance associated with the instance ID,
+        or None if not found."""
+        return cls._instances.get(instance_id)
+
+    @classmethod
+    def destroy(cls, instance_id: str) -> None:
+        """Close and delete the LMCacheEngine instance by the instance ID"""
+        # TODO: unit test for this
+        logger.info("Destroying LMCacheEngine instance: %s", instance_id)
+
+        if instance_id in cls._instances:
+            stat_logger = cls._stat_loggers[instance_id]
+            try:
+                logger.info("Shutting down stats logger...")
+                stat_logger.shutdown()
+                logger.info("Stats logger shut down successfully")
+            except Exception as e:
+                logger.error("Error shutting down stats logger: %s", e)
+
+            engine = cls._instances[instance_id]
+            try:
+                logger.info("Closing cache engine...")
+                engine.close()
+                logger.info("Cache engine closed successfully")
+            except Exception as e:
+                logger.error("Error closing cache engine: %s", e)
+
+            try:
+                logger.info("Cleaning up instance dictionaries...")
+                cls._instances.pop(instance_id, None)
+                cls._cfgs.pop(instance_id, None)
+                cls._metadatas.pop(instance_id, None)
+                cls._stat_loggers.pop(instance_id, None)
+                logger.info("Instance dictionaries cleaned up")
+            except Exception as e:
+                logger.error("Error cleaning up instances: %s", e)
+
+            try:
+                logger.info("Destroying stats monitor...")
+                LMCStatsMonitor.DestroyInstance()
+                logger.info("Stats monitor destroyed successfully")
+            except Exception as e:
+                logger.error("Error destroying stats monitor: %s", e)
+
+            logger.info("LMCacheEngine instance %s destroyed", instance_id)
+        else:
+            logger.warning("Instance %s not found for destruction", instance_id)
diff --git a/lmcache/v1/cache_interface.py b/lmcache/v1/cache_interface.py
new file mode 100644
index 0000000..559e537
--- /dev/null
+++ b/lmcache/v1/cache_interface.py
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+
+# Third Party
+import msgspec
+
+
+class LMCacheModelRequest(
+    msgspec.Struct,
+    array_like=True,  # type: ignore[call-arg]
+    omit_defaults=True,
+):  # type: ignore[call-arg]
+    """
+    User-provided information to control the cache behavior.
+    """
+
+    store_cache: bool = True  # Whether to store the cache
+    ttl: Optional[float] = None  # Time to live
diff --git a/lmcache/v1/check/__init__.py b/lmcache/v1/check/__init__.py
new file mode 100644
index 0000000..216ea04
--- /dev/null
+++ b/lmcache/v1/check/__init__.py
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Check mode registry implementation"""
+
+# Standard
+from typing import Callable, Dict, Optional
+import importlib
+import inspect
+import os
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class CheckModeRegistry:
+    """Registry for dynamically loaded check modes"""
+
+    def __init__(self):
+        self.modes: Dict[str, Callable] = {}
+        self.loaded = False
+
+    def register(self, name: str, func: Callable):
+        """Register a check mode function"""
+        if name in self.modes:
+            raise ValueError(f"Check mode '{name}' already registered")
+        self.modes[name] = func
+
+    def load_modes(self):
+        """Dynamically load all check mode modules"""
+        if self.loaded:
+            return
+
+        # Get current package
+        current_dir = os.path.dirname(__file__)
+
+        # Find all modules with check_mode_ prefix
+        for filename in os.listdir(current_dir):
+            if filename.startswith("check_mode_") and filename.endswith(".py"):
+                module_name = filename[:-3]  # Remove .py
+                try:
+                    module = importlib.import_module(
+                        f".{module_name}", package=__package__
+                    )
+                    # Find and register mode functions
+                    for name, obj in inspect.getmembers(module):
+                        if inspect.isfunction(obj) and hasattr(obj, "is_check_mode"):
+                            self.register(obj.mode_name, obj)
+                except ImportError as e:
+                    logger.error(f"Failed to load check mode module {module_name}: {e}")
+
+        self.loaded = True
+        logger.info(f"Loaded {len(self.modes)} check modes")
+
+    def get_mode(self, name: str) -> Optional[Callable]:
+        """Get registered mode function. Returns None if the mode is not found."""
+        if not self.loaded:
+            self.load_modes()
+        return self.modes.get(name)
+
+
+def check_mode(name: str):
+    """Decorator to mark functions as check modes"""
+
+    def decorator(func):
+        func.is_check_mode = True
+        func.mode_name = name
+        return func
+
+    return decorator
+
+
+# Global registry instance
+registry = CheckModeRegistry()
diff --git a/lmcache/v1/check/check_mode_gen.py b/lmcache/v1/check/check_mode_gen.py
new file mode 100644
index 0000000..da58879
--- /dev/null
+++ b/lmcache/v1/check/check_mode_gen.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generate mode implementation for key generation"""
+
+# Third Party
+import tqdm
+
+# First Party
+from lmcache.v1.check import check_mode
+from lmcache.v1.check.utils import (
+    _get_default_metadata,
+    create_memory_objects_batch,
+    create_storage_manager_with_config,
+    create_test_key,
+    find_remote_backend,
+    flow_control_check,
+    wait_put_tasks_complete,
+)
+
+
+@check_mode("gen")
+async def run_gen_mode(
+    model: str, num_keys: int, concurrency: int, offset: int = 0, **kwargs
+):
+    """Run key generation mode"""
+    # Create storage manager using common function
+    storage_manager = create_storage_manager_with_config(model)
+    metadata = _get_default_metadata(model)
+
+    try:
+        print("Generate: Passed - Created storage manager with valid config")
+
+        # Find remote backend for flow control
+        remote_backend = find_remote_backend(storage_manager)
+
+        # Create limited number of memory objects for reuse (memory efficiency)
+        batch_size = min(concurrency, 100)  # Limit to 100 for memory efficiency
+        memory_objs = create_memory_objects_batch(storage_manager, metadata, batch_size)
+
+        if not memory_objs:
+            print("Generate: Failed - Could not allocate any memory objects")
+            return
+
+        # Create progress bar
+        progress_bar = tqdm.tqdm(
+            total=num_keys, desc="Generating keys", unit="key", unit_scale=True
+        )
+        sleep_count = 1.0
+        # Process keys in batches of concurrency size
+        for batch_start in range(0, num_keys, concurrency):
+            batch_end = min(batch_start + concurrency, num_keys)
+            batch_keys = []
+            batch_memory_objs = []
+
+            # Create keys and reuse memory objects for this batch
+            for i in range(batch_start, batch_end):
+                key = create_test_key(model, f"gen_{offset + i}")
+                # Reuse memory objects in round-robin fashion
+                memory_obj = memory_objs[i % len(memory_objs)]
+                batch_keys.append(key)
+                batch_memory_objs.append(memory_obj)
+                memory_obj.ref_count_up()
+
+            # Flow control: check if remote backend has too many pending tasks
+            sleep_count = await flow_control_check(
+                remote_backend, concurrency, sleep_count
+            )
+
+            # Use batched_put to store the batch of memory objects
+            storage_manager.batched_put(batch_keys, batch_memory_objs)
+
+            # Update progress bar
+            progress_bar.update(len(batch_keys))
+
+        progress_bar.close()
+        print(f"Generate: Successfully generated {num_keys} keys")
+
+        # Wait for remote backend put_tasks to complete
+        wait_put_tasks_complete(find_remote_backend(storage_manager))
+
+    except Exception as e:
+        print(
+            f"Generate: Failed - Error creating storage manager with valid config: {e}"
+        )
+    finally:
+        if storage_manager:
+            storage_manager.close()
diff --git a/lmcache/v1/check/check_mode_test_l2_adapter.py b/lmcache/v1/check/check_mode_test_l2_adapter.py
new file mode 100644
index 0000000..f632e21
--- /dev/null
+++ b/lmcache/v1/check/check_mode_test_l2_adapter.py
@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Test mode implementation for MP mode L2 adapter basic checks"""
+
+# Standard
+import argparse
+import select
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.check import check_mode
+from lmcache.v1.check.utils import (
+    DEFAULT_KV_DTYPE_STR,
+    DEFAULT_OBJ_SIZE,
+    parse_kv_dtype,
+    print_performance_results,
+)
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.internal_api import L1MemoryDesc, L2StoreResult
+from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+from lmcache.v1.distributed.l2_adapters.config import (
+    parse_args_to_l2_adapters_config,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_POLL_TIMEOUT_MS = 100000
+
+
+def _create_object_key(model: str, key_id: str) -> ObjectKey:
+    """Create a test ObjectKey."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(hash(key_id) & 0xFFFFFFFF),
+        model_name=model,
+        kv_rank=0,
+    )
+
+
+def _create_memory_obj(
+    raw_data: torch.Tensor | None = None,
+    fill_value: float = 0.0,
+    obj_size: int = DEFAULT_OBJ_SIZE,
+    dtype: torch.dtype = torch.float32,
+) -> TensorMemoryObj:
+    """Create a test TensorMemoryObj."""
+    if raw_data is None:
+        raw_data = torch.empty(obj_size, dtype=dtype)
+    else:
+        raw_data = raw_data.view(-1)
+        if raw_data.numel() != obj_size:
+            raise ValueError(
+                "raw_data size mismatch: expected %d elements, got %d"
+                % (obj_size, raw_data.numel())
+            )
+        if raw_data.dtype != dtype:
+            raise ValueError(
+                "raw_data dtype mismatch: expected %s, got %s" % (dtype, raw_data.dtype)
+            )
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([obj_size]),
+        dtype=dtype,
+        address=raw_data.data_ptr(),
+        phy_size=obj_size * raw_data.element_size(),
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def _create_l1_memory_desc(buffer: torch.Tensor) -> L1MemoryDesc:
+    """Create an L1 memory descriptor for a contiguous test buffer."""
+    flat_buffer = buffer.view(-1)
+    return L1MemoryDesc(
+        ptr=flat_buffer.data_ptr(),
+        size=flat_buffer.numel() * flat_buffer.element_size(),
+        align_bytes=flat_buffer.element_size(),
+    )
+
+
+def _wait_event_fd(efd: int, timeout_ms: int = _POLL_TIMEOUT_MS) -> bool:
+    """Wait for an eventfd to be signaled."""
+    poll = select.poll()
+    poll.register(efd, select.POLLIN)
+    events = poll.poll(timeout_ms)
+    if events:
+        try:
+            consume_fd(efd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+def _run_store_phase(adapter, keys, objects):
+    """Run store phase and return (stats, success)."""
+    efd = adapter.get_store_event_fd()
+    start = time.perf_counter()
+    task_id = adapter.submit_store_task(keys, objects)
+    if not _wait_event_fd(efd):
+        print("  Store: timed out waiting for eventfd")
+        return None, False
+    completed = adapter.pop_completed_store_tasks()
+    elapsed_ms = (time.perf_counter() - start) * 1000
+    ok = completed.get(task_id, L2StoreResult(False, 0)).is_successful()
+    return elapsed_ms, ok
+
+
+def _run_lookup_phase(adapter, keys):
+    """Run lookup phase and return (stats, bitmap)."""
+    efd = adapter.get_lookup_and_lock_event_fd()
+    start = time.perf_counter()
+    task_id = adapter.submit_lookup_and_lock_task(keys)
+    if not _wait_event_fd(efd):
+        print("  Lookup: timed out waiting for eventfd")
+        return None, None
+    bitmap = adapter.query_lookup_and_lock_result(task_id)
+    elapsed_ms = (time.perf_counter() - start) * 1000
+    return elapsed_ms, bitmap
+
+
+def _run_load_phase(adapter, keys, buffers):
+    """Run load phase and return (stats, bitmap)."""
+    efd = adapter.get_load_event_fd()
+    start = time.perf_counter()
+    task_id = adapter.submit_load_task(keys, buffers)
+    if not _wait_event_fd(efd):
+        print("  Load: timed out waiting for eventfd")
+        return None, None
+    bitmap = adapter.query_load_result(task_id)
+    elapsed_ms = (time.perf_counter() - start) * 1000
+    return elapsed_ms, bitmap
+
+
+@check_mode("test_l2_adapter")
+async def run_test_mode(model: str, **kwargs):
+    """Run L2 adapter test mode.
+
+    Requires ``l2_adapter`` in *kwargs* (list of JSON
+    strings from ``--l2-adapter``).
+    """
+    l2_adapter_raw = kwargs.get("l2_adapter")
+    if not l2_adapter_raw:
+        print("Error: --l2-adapter is required for test_l2_adapter mode")
+        return
+
+    obj_size = kwargs.get("obj_size") or DEFAULT_OBJ_SIZE
+    kv_dtype_str = kwargs.get("kv_dtype") or DEFAULT_KV_DTYPE_STR
+    kv_dtype = parse_kv_dtype(kv_dtype_str)
+    if kv_dtype is None:
+        print("Error: unsupported --kv-dtype '%s'" % kv_dtype_str)
+        return
+
+    # Build adapter config via the standard parser
+    ns = argparse.Namespace(l2_adapter=l2_adapter_raw)
+    l2_cfg = parse_args_to_l2_adapters_config(ns)
+    if not l2_cfg.adapters:
+        print("Error: no L2 adapter configs parsed")
+        return
+
+    num_tests = kwargs.get("num_keys", 5)
+    settle_time = kwargs.get("settle_time", 0.0)
+
+    for idx, adapter_cfg in enumerate(l2_cfg.adapters):
+        l1_buffer = torch.empty(2 * num_tests * obj_size, dtype=kv_dtype)
+        l1_memory_desc = _create_l1_memory_desc(l1_buffer)
+        adapter = create_l2_adapter(adapter_cfg, l1_memory_desc=l1_memory_desc)
+        print("=== Testing L2 adapter #%d (%s) ===" % (idx, type(adapter).__name__))
+
+        try:
+            _test_single_adapter(
+                adapter,
+                model,
+                num_tests,
+                l1_buffer=l1_buffer,
+                obj_size=obj_size,
+                kv_dtype=kv_dtype,
+                settle_time=settle_time,
+            )
+        except Exception as e:
+            print("  Test Failed - Error: %s" % e)
+        finally:
+            adapter.close()
+
+
+def _test_single_adapter(
+    adapter,
+    model,
+    num_tests,
+    l1_buffer,
+    obj_size=DEFAULT_OBJ_SIZE,
+    kv_dtype=torch.float32,
+    settle_time=0.0,
+):
+    """Run all test phases against one adapter."""
+    # -- Prepare test data -----------------------------------
+    exist_keys = [_create_object_key(model, "exist_%d" % i) for i in range(num_tests)]
+    non_exist_keys = [
+        _create_object_key(model, "nonexist_%d" % i) for i in range(num_tests)
+    ]
+    flat_l1_buffer = l1_buffer.view(-1)
+    store_objs = [
+        _create_memory_obj(
+            raw_data=flat_l1_buffer[i * obj_size : (i + 1) * obj_size],
+            fill_value=float(i + 1),
+            obj_size=obj_size,
+            dtype=kv_dtype,
+        )
+        for i in range(num_tests)
+    ]
+
+    # -- Phase 1: lookup non-existing keys -------------------
+    print("Phase 1: Lookup non-existing keys...")
+    lk_absent_ms, lk_bitmap = _run_lookup_phase(adapter, non_exist_keys)
+    if lk_bitmap is None:
+        print("  FAIL: lookup returned None bitmap")
+        ne_pass = 0
+    else:
+        ne_pass = sum(1 for i in range(num_tests) if not lk_bitmap.test(i))
+    print("  Validation: %d/%d correctly absent" % (ne_pass, num_tests))
+    # Unlock the looked-up keys (contract)
+    adapter.submit_unlock(non_exist_keys)
+
+    # -- Phase 2: store existing keys ------------------------
+    print("Phase 2: Store operations (batch of %d)..." % num_tests)
+    st_ms, st_ok = _run_store_phase(adapter, exist_keys, store_objs)
+    store_pass = num_tests if st_ok else 0
+    print("  Batch store %s (%.2fms)" % ("OK" if st_ok else "FAIL", st_ms or 0))
+
+    if settle_time > 0:
+        print("  Waiting %.1fs for data to settle..." % settle_time)
+        time.sleep(settle_time)
+
+    # -- Phase 3: lookup existing keys -----------------------
+    print("Phase 3: Lookup existing keys...")
+    lk_exist_ms, lk_bitmap = _run_lookup_phase(adapter, exist_keys)
+    if lk_bitmap is None:
+        print("  FAIL: lookup returned None bitmap")
+        exist_pass = 0
+    else:
+        exist_pass = sum(1 for i in range(num_tests) if lk_bitmap.test(i))
+    print("  Validation: %d/%d found" % (exist_pass, num_tests))
+
+    # -- Phase 4: load existing keys -------------------------
+    print("Phase 4: Load operations...")
+    load_buffers = [
+        _create_memory_obj(
+            raw_data=flat_l1_buffer[
+                (num_tests + i) * obj_size : (num_tests + i + 1) * obj_size
+            ],
+            fill_value=0.0,
+            obj_size=obj_size,
+            dtype=kv_dtype,
+        )
+        for i in range(num_tests)
+    ]
+    ld_ms, ld_bitmap = _run_load_phase(adapter, exist_keys, load_buffers)
+    load_pass = 0
+    content_pass = 0
+    if ld_bitmap is not None:
+        for i in range(num_tests):
+            if ld_bitmap.test(i):
+                load_pass += 1
+                if torch.equal(
+                    load_buffers[i].tensor,
+                    store_objs[i].tensor,
+                ):
+                    content_pass += 1
+                else:
+                    print("  Key %d: data mismatch" % i)
+    print("  Validation (loaded): %d/%d" % (load_pass, num_tests))
+    print("  Validation (content): %d/%d" % (content_pass, num_tests))
+
+    # Unlock after load
+    adapter.submit_unlock(exist_keys)
+
+    # -- Summary ---------------------------------------------
+    total_bytes = obj_size * store_objs[0].tensor.element_size() * num_tests
+    stats_data = [
+        (
+            "LOOKUP (absent)",
+            {
+                "avg": lk_absent_ms or 0,
+                "max": lk_absent_ms or 0,
+                "min": lk_absent_ms or 0,
+            },
+            [False] * num_tests,
+            ne_pass,
+        ),
+        (
+            "STORE",
+            {
+                "avg": st_ms or 0,
+                "max": st_ms or 0,
+                "min": st_ms or 0,
+            },
+            [True] * store_pass + [False] * (num_tests - store_pass),
+            store_pass,
+        ),
+        (
+            "LOOKUP (exist)",
+            {
+                "avg": lk_exist_ms or 0,
+                "max": lk_exist_ms or 0,
+                "min": lk_exist_ms or 0,
+            },
+            [True] * exist_pass + [False] * (num_tests - exist_pass),
+            exist_pass,
+        ),
+        (
+            "LOAD",
+            {
+                "avg": ld_ms or 0,
+                "max": ld_ms or 0,
+                "min": ld_ms or 0,
+            },
+            [True] * content_pass + [False] * (num_tests - content_pass),
+            content_pass,
+        ),
+    ]
+    print_performance_results(stats_data, obj_bytes=total_bytes)
diff --git a/lmcache/v1/check/check_mode_test_remote.py b/lmcache/v1/check/check_mode_test_remote.py
new file mode 100644
index 0000000..3855eff
--- /dev/null
+++ b/lmcache/v1/check/check_mode_test_remote.py
@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Test mode implementation for basic checks"""
+
+# Standard
+import asyncio
+
+# First Party
+from lmcache.integration.vllm.utils import lmcache_get_or_create_config
+from lmcache.v1.check import check_mode
+
+# Import shared utilities
+from lmcache.v1.check.utils import (
+    DEFAULT_KV_DTYPE_STR,
+    EventLoopManager,
+    _get_default_metadata,
+    create_test_key,
+    parse_kv_dtype,
+    run_common_test_framework,
+    validate_get_results,
+)
+from lmcache.v1.memory_management import MemoryObj
+
+# Import from lmcache with absolute paths
+from lmcache.v1.storage_backend import RemoteBackend
+from lmcache.v1.storage_backend.connector import InstrumentedRemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+
+async def async_contains_backend(backend, key):
+    """Async wrapper for backend contains method"""
+    return backend.contains(key)
+
+
+async def async_get_backend(backend, key):
+    """Async wrapper for backend get_blocking method"""
+    return backend.get_blocking(key)
+
+
+async def async_submit_put_backend(backend, key, memory_obj):
+    """Async wrapper for backend submit_put_task"""
+    future = backend.submit_put_task(key, memory_obj)
+    # Wait for the future to complete with timeout
+    try:
+        await asyncio.wait_for(asyncio.wrap_future(future), timeout=10.0)
+        return True
+    except asyncio.TimeoutError:
+        print(f"Put task timed out for key: {key}")
+        return False
+
+
+def create_test_memory_obj(
+    backend: RemoteBackend, local_cpu_backend: LocalCPUBackend
+) -> MemoryObj:
+    """Create a test MemoryObj for testing."""
+    if backend.connection is None:
+        raise ValueError("Backend connection is None")
+
+    if isinstance(backend.connection, InstrumentedRemoteConnector):
+        connector = backend.connection.getWrappedConnector()
+    else:
+        connector = backend.connection
+
+    return local_cpu_backend.allocate(
+        connector.meta_shapes, connector.meta_dtypes, connector.meta_fmt
+    )
+
+
+def create_test_data_for_backend(
+    backend,
+    local_cpu_backend,
+    model,
+    num_tests,
+    kv_dtype=None,
+):
+    """Create test data for backend based tests"""
+    # Group 1: Non-existing keys
+    kw = {} if kv_dtype is None else {"kv_dtype": kv_dtype}
+    non_exist_keys = [
+        create_test_key(model, f"non_exist_{i}", **kw) for i in range(num_tests)
+    ]
+
+    # Group 2: Existing keys
+    exist_keys = [create_test_key(model, f"exist_{i}", **kw) for i in range(num_tests)]
+    exist_memories = [
+        create_test_memory_obj(backend, local_cpu_backend) for _ in range(num_tests)
+    ]
+
+    return non_exist_keys, exist_keys, exist_memories, num_tests
+
+
+@check_mode("test_remote")
+async def run_test_mode(model: str, **kwargs):
+    """Run connector test mode"""
+    kv_dtype_str = kwargs.get("kv_dtype") or DEFAULT_KV_DTYPE_STR
+    kv_dtype = parse_kv_dtype(kv_dtype_str)
+    if kv_dtype is None:
+        print("Error: unsupported --kv-dtype '%s'" % kv_dtype_str)
+        return
+
+    obj_size = kwargs.get("obj_size")
+
+    config = lmcache_get_or_create_config()
+    metadata = _get_default_metadata(model, kv_dtype=kv_dtype, obj_size=obj_size)
+
+    # Create and start event loop manager
+    loop_manager = EventLoopManager()
+    loop_manager.start()
+
+    local_cpu_backend = LocalCPUBackend(
+        config=config, metadata=metadata, dst_device="cpu"
+    )
+
+    backend = RemoteBackend(
+        config=config,
+        metadata=metadata,
+        loop=loop_manager.get_loop(),
+        local_cpu_backend=local_cpu_backend,
+        dst_device="cpu",
+    )
+
+    try:
+        # Create test context for the common framework
+        test_context = {
+            "create_test_data_func": create_test_data_for_backend,
+            "async_contains_func": async_contains_backend,
+            "async_put_func": async_submit_put_backend,
+            "async_get_func": async_get_backend,
+            "validate_get_func": validate_get_results,
+            "test_object": backend,
+            "extra_args": [
+                local_cpu_backend,
+            ],
+            "kv_dtype": kv_dtype,
+            "obj_size": obj_size,
+        }
+
+        # Run the common test framework
+        num_tests = kwargs.get("num_keys", 5)
+        settle_time = kwargs.get("settle_time", 0.0)
+        await run_common_test_framework(
+            test_context, model, num_tests=num_tests, settle_time=settle_time
+        )
+
+    except Exception as e:
+        print(f"Test Failed - Error: {e}")
+    finally:
+        # Clean up
+        try:
+            if backend:
+                backend.close()
+        except Exception as e:
+            print(f"Error closing backend: {e}")
+
+        # Stop the event loop
+        loop_manager.stop()
diff --git a/lmcache/v1/check/check_mode_test_storage_manager.py b/lmcache/v1/check/check_mode_test_storage_manager.py
new file mode 100644
index 0000000..3ff9a79
--- /dev/null
+++ b/lmcache/v1/check/check_mode_test_storage_manager.py
@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Test mode implementation for basic checks"""
+
+# Standard
+import asyncio
+
+# First Party
+from lmcache.v1.check import check_mode
+
+# Import shared utilities
+from lmcache.v1.check.utils import (
+    DEFAULT_KV_DTYPE_STR,
+    create_storage_manager_with_config,
+    create_test_key,
+    create_test_memory_obj_for_storage_manager,
+    find_remote_backend,
+    parse_kv_dtype,
+    run_common_test_framework,
+    validate_get_results,
+    wait_put_tasks_complete,
+)
+
+
+async def async_contains_storage_manager(storage_manager, key):
+    """Async wrapper for storage manager contains method"""
+    # Use asyncio.to_thread to make the synchronous call truly async
+    # This allows for proper timeout handling and non-blocking execution
+    result = await asyncio.to_thread(storage_manager.contains, key)
+    return result is not None
+
+
+async def async_get_storage_manager(storage_manager, key):
+    """Async wrapper for storage manager get method"""
+    # Use asyncio.to_thread to make the synchronous call truly async
+    # This allows for proper timeout handling and non-blocking execution
+    return await asyncio.to_thread(storage_manager.get, key)
+
+
+async def async_submit_put_storage_manager(storage_manager, key, memory_obj):
+    """Async wrapper for storage manager batched_put"""
+    try:
+        # Use asyncio.to_thread to make the synchronous calls truly async
+        # This allows for proper timeout handling and non-blocking execution
+        await asyncio.to_thread(storage_manager.batched_put, [key], [memory_obj])
+        await asyncio.to_thread(
+            wait_put_tasks_complete, find_remote_backend(storage_manager)
+        )
+        return True
+    except Exception as e:
+        print(f"Put task failed for key: {key}, error: {e}")
+        return False
+
+
+def create_test_data_for_storage_manager(
+    storage_manager,
+    metadata,
+    model,
+    num_tests,
+    kv_dtype=None,
+):
+    """Create test data for storage manager based tests"""
+    # Group 1: Non-existing keys
+    kw = {} if kv_dtype is None else {"kv_dtype": kv_dtype}
+    non_exist_keys = [
+        create_test_key(model, f"non_exist_{i}", **kw) for i in range(num_tests)
+    ]
+
+    # Group 2: Existing keys
+    exist_keys = [create_test_key(model, f"exist_{i}", **kw) for i in range(num_tests)]
+    exist_memories = []
+    for i in range(num_tests):
+        memory_obj = create_test_memory_obj_for_storage_manager(
+            storage_manager, metadata
+        )
+        if memory_obj is not None:
+            # Fill with unique test data for each memory object
+            if memory_obj.tensor is not None:
+                # Fill with a pattern based on the index to make each object unique
+                memory_obj.tensor.fill_(float(i + 1))
+            memory_obj.ref_count_up()
+            exist_memories.append(memory_obj)
+
+    if len(exist_memories) != num_tests:
+        print(
+            f"Warning: Could only allocate {len(exist_memories)}/{num_tests} "
+            f"memory objects"
+        )
+        num_tests = len(exist_memories)
+        exist_keys = exist_keys[:num_tests]
+
+    return non_exist_keys, exist_keys, exist_memories, num_tests
+
+
+@check_mode("test_storage_manager")
+async def run_test_mode(model: str, **kwargs):
+    """Run connector test mode"""
+    kv_dtype_str = kwargs.get("kv_dtype") or DEFAULT_KV_DTYPE_STR
+    kv_dtype = parse_kv_dtype(kv_dtype_str)
+    if kv_dtype is None:
+        print("Error: unsupported --kv-dtype '%s'" % kv_dtype_str)
+        return
+
+    obj_size = kwargs.get("obj_size")
+
+    # Create storage manager using common function
+    storage_manager = create_storage_manager_with_config(
+        model,
+        kv_dtype=kv_dtype,
+        obj_size=obj_size,
+    )
+
+    try:
+        print("Test: Passed - Created storage manager with valid config")
+
+        # Create test context for the common framework
+        test_context = {
+            "create_test_data_func": create_test_data_for_storage_manager,
+            "async_contains_func": async_contains_storage_manager,
+            "async_put_func": async_submit_put_storage_manager,
+            "async_get_func": async_get_storage_manager,
+            "validate_get_func": validate_get_results,
+            "test_object": storage_manager,
+            "kv_dtype": kv_dtype,
+            "obj_size": obj_size,
+        }
+
+        # Run the common test framework
+        num_tests = kwargs.get("num_keys", 5)
+        settle_time = kwargs.get("settle_time", 0.0)
+        await run_common_test_framework(
+            test_context, model, num_tests=num_tests, settle_time=settle_time
+        )
+
+    except Exception as e:
+        print(f"Test Failed - Error: {e}")
+    finally:
+        # Clean up
+        try:
+            if storage_manager:
+                storage_manager.close()
+        except Exception as e:
+            print(f"Error closing storage manager: {e}")
diff --git a/lmcache/v1/check/utils.py b/lmcache/v1/check/utils.py
new file mode 100644
index 0000000..0a38787
--- /dev/null
+++ b/lmcache/v1/check/utils.py
@@ -0,0 +1,566 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared utilities for check modes"""
+
+# Standard
+from typing import Optional
+import asyncio
+import hashlib
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.kv_layer_groups import DTYPE_MAP
+
+# Import from lmcache with absolute paths
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+from lmcache.v1.storage_backend.storage_manager import StorageManager
+
+DEFAULT_KV_DTYPE_STR = "bfloat16"
+DEFAULT_OBJ_SIZE = 1024
+
+
+def _compute_kv_shape(
+    obj_size: int,
+) -> tuple:
+    """Compute a kv_shape that yields the given obj_size.
+
+    The returned shape is in vllm format:
+    ``(num_layers, 2, num_tokens, num_heads, head_size)``.
+
+    The final KV_2LTD tensor has
+    ``2 * num_layers * num_tokens * (num_heads * head_size)``
+    elements, which equals *obj_size*.
+
+    We fix ``num_layers=1, num_heads=1`` and split the
+    remaining factor between ``num_tokens`` and ``head_size``
+    so that ``num_tokens * head_size = obj_size // 2``.
+    """
+    if obj_size % 2 != 0:
+        raise ValueError("obj_size must be even (got %d)" % obj_size)
+    half = obj_size // 2
+    # (num_layers, kv_dim, num_tokens, num_heads, head_size)
+    return (1, 2, half, 1, 1)
+
+
+def parse_kv_dtype(kv_dtype_str: str) -> Optional[torch.dtype]:
+    """Parse a kv_dtype string to a torch.dtype.
+
+    Returns None if the string is not recognized.
+    """
+    return DTYPE_MAP.get(kv_dtype_str)
+
+
+def _get_default_metadata(
+    model: str,
+    kv_dtype: torch.dtype = torch.bfloat16,
+    obj_size: Optional[int] = None,
+) -> LMCacheMetadata:
+    """Get default metadata for testing.
+
+    When *obj_size* is given the ``kv_shape`` is computed so
+    that the resulting KV_2LTD tensor has exactly *obj_size*
+    elements.  Otherwise a small default shape is used.
+    """
+    if obj_size is not None:
+        kv_shape = _compute_kv_shape(obj_size)
+    else:
+        kv_shape = _compute_kv_shape(DEFAULT_OBJ_SIZE)
+    return LMCacheMetadata(
+        model_name=model,
+        world_size=8,
+        local_world_size=8,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=kv_dtype,
+        kv_shape=kv_shape,
+    )
+
+
+def create_test_key(
+    model: str,
+    key_id: str = "test_key",
+    kv_dtype: torch.dtype = torch.bfloat16,
+) -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name=model,
+        world_size=8,
+        worker_id=0,
+        chunk_hash=int(hashlib.sha256(key_id.encode()).hexdigest(), 16),
+        dtype=kv_dtype,
+    )
+
+
+def create_test_memory_obj_for_storage_manager(
+    storage_manager: StorageManager, metadata: LMCacheMetadata
+) -> Optional[MemoryObj]:
+    """Create a test MemoryObj for testing with StorageManager."""
+    # The metadata.kv_shape is in vllm format:
+    # [num_layers, 2, num_tokens, num_heads, head_size]
+    # For KV_2LTD format, we need shape: [2, num_layers, num_tokens, hidden_dim]
+    # where hidden_dim = num_heads * head_size
+
+    vllm_shape = metadata.kv_shape  # [num_layers, 2, num_tokens, num_heads, head_size]
+    num_layers = vllm_shape[0]  # 8
+    kv_dim = vllm_shape[1]  # 2 (K and V)
+    num_tokens = vllm_shape[2]  # 16
+    num_heads = vllm_shape[3]  # 8
+    head_size = vllm_shape[4]  # 16
+
+    # Convert to KV_2LTD format shape: [2, num_layers, num_tokens, hidden_dim]
+    hidden_dim = num_heads * head_size
+    kv_2ltd_shape = torch.Size([kv_dim, num_layers, num_tokens, hidden_dim])
+
+    memory_obj = storage_manager.allocate(
+        kv_2ltd_shape,
+        metadata.kv_dtype,
+        fmt=MemoryFormat.KV_2LTD,
+        eviction=True,
+        busy_loop=False,
+    )
+    return memory_obj
+
+
+def create_storage_manager_with_config(
+    model: str,
+    kv_dtype: torch.dtype = torch.bfloat16,
+    obj_size: Optional[int] = None,
+):
+    """Create storage manager with default configuration"""
+    # First Party
+    from lmcache.integration.vllm.utils import lmcache_get_or_create_config
+    from lmcache.v1.event_manager import EventManager
+
+    config = lmcache_get_or_create_config()
+    metadata = _get_default_metadata(model, kv_dtype=kv_dtype, obj_size=obj_size)
+
+    # Create event manager
+    event_manager = EventManager()
+
+    # Create storage manager
+    storage_manager = StorageManager(
+        config=config,
+        metadata=metadata,
+        event_manager=event_manager,
+    )
+
+    return storage_manager
+
+
+def find_remote_backend(storage_manager: StorageManager) -> Optional[RemoteBackend]:
+    """Find remote backend from storage manager"""
+    for backend_name, backend in storage_manager.storage_backends.items():
+        if isinstance(backend, RemoteBackend):
+            return backend
+    return None
+
+
+def wait_put_tasks_complete(
+    remote_backend: Optional[RemoteBackend], max_wait_time: float = 5.0
+):
+    """Wait for remote backend put tasks to complete"""
+    if remote_backend is None:
+        return
+
+    check_interval = 0.001
+    elapsed_time = 0.0
+
+    while elapsed_time < max_wait_time:
+        if not remote_backend.put_tasks:
+            break
+        time.sleep(check_interval)
+        elapsed_time += check_interval
+
+    # Log warning if timeout
+    remaining_tasks = len(remote_backend.put_tasks)
+    if remaining_tasks > 0:
+        print(
+            f"Warning: {remaining_tasks} remote put tasks still "
+            f"pending after {max_wait_time}s timeout"
+        )
+
+
+def create_memory_objects_batch(
+    storage_manager: StorageManager, metadata: LMCacheMetadata, batch_size: int
+) -> list[MemoryObj]:
+    """Create a batch of memory objects for reuse"""
+    memory_objs = []
+    for i in range(batch_size):
+        memory_obj = create_test_memory_obj_for_storage_manager(
+            storage_manager, metadata
+        )
+        if memory_obj is not None:
+            memory_obj.ref_count_up()
+            memory_objs.append(memory_obj)
+    return memory_objs
+
+
+async def flow_control_check(
+    remote_backend: Optional[RemoteBackend], concurrency: int, sleep_count: float = 1.0
+) -> float:
+    """Check flow control and wait if necessary"""
+    if remote_backend is None:
+        return sleep_count
+
+    high_watermark = 100 * concurrency
+    low_watermark = 10 * concurrency
+    current_tasks = len(remote_backend.put_tasks)
+
+    while current_tasks > high_watermark:
+        current_tasks = len(remote_backend.put_tasks)
+        if current_tasks > high_watermark:
+            # Too many pending tasks, wait before proceeding
+            sleep_sec = 0.1 * sleep_count
+            current_tasks = len(remote_backend.put_tasks)
+            await asyncio.sleep(sleep_sec)
+            current_tasks_after_sleep = len(remote_backend.put_tasks)
+            if current_tasks_after_sleep > low_watermark:
+                sleep_count *= 2.0
+            elif current_tasks_after_sleep == 0:
+                sleep_count /= 2.0
+            continue
+        if current_tasks <= low_watermark:
+            break
+
+    return sleep_count
+
+
+async def run_perf_test_with_timeout(func, args_list, timeout=30.0):
+    """Common performance test framework with timeout handling"""
+    times = []
+    results = []  # Collect results for each operation
+    for i, args in enumerate(args_list):
+        try:
+            start = time.perf_counter()
+            result = await asyncio.wait_for(func(*args), timeout=timeout)
+            end = time.perf_counter()
+            times.append((end - start) * 1000)
+            results.append(result)
+            print(
+                f"  Test {i + 1}/{len(args_list)} completed in "
+                f"{(end - start) * 1000:.2f}ms"
+            )
+        except asyncio.TimeoutError:
+            print(f"  Test {i + 1}/{len(args_list)} timed out after {timeout}s")
+            times.append(timeout * 1000)
+            results.append(None)
+        except Exception as e:
+            print(f"  Test {i + 1}/{len(args_list)} failed: {e}")
+            times.append(0)
+            results.append(None)
+
+    if times:
+        return {
+            "time_stats": {
+                "avg": sum(times) / len(times),
+                "max": max(times),
+                "min": min(times),
+            },
+            "results": results,
+        }
+    else:
+        return {"time_stats": {"avg": 0, "max": 0, "min": 0}, "results": []}
+
+
+def _format_throughput(avg_ms: float, obj_bytes: int) -> str:
+    """Format throughput as a human-readable string."""
+    if avg_ms <= 0 or obj_bytes <= 0:
+        return "N/A"
+    bps = obj_bytes / (avg_ms / 1000.0)
+    if bps >= 1 << 30:
+        return "%.2f GB/s" % (bps / (1 << 30))
+    if bps >= 1 << 20:
+        return "%.2f MB/s" % (bps / (1 << 20))
+    return "%.2f KB/s" % (bps / (1 << 10))
+
+
+def print_performance_results(
+    stats_data,
+    obj_bytes: int = 0,
+    throughput_ops: Optional[set] = None,
+):
+    """Print performance results in a formatted table.
+
+    Args:
+        stats_data: list of (op, stats, results, pass_count).
+        obj_bytes: size of one object in bytes.  When > 0 a
+            throughput column is shown for operations listed
+            in *throughput_ops*.
+        throughput_ops: set of operation name prefixes that
+            should show throughput (e.g. {"STORE", "LOAD"}).
+            Defaults to common data-transfer operations.
+    """
+    if throughput_ops is None:
+        throughput_ops = {
+            "STORE",
+            "LOAD",
+            "PUT",
+            "GET",
+        }
+    show_tp = obj_bytes > 0
+
+    sep_len = 118 if show_tp else 100
+    tp_hdr = " | %s" % "Throughput".center(14) if show_tp else ""
+    print("\nPerformance Results:")
+    print("-" * sep_len)
+    print(
+        f"| {'Operation':<20} | {'Avg (ms)':>12} "
+        f"| {'Max (ms)':>12} "
+        f"| {'Min (ms)':>12} "
+        f"| {'Pass/All':>10} "
+        f"| {'Pass Rate':>10} |" + tp_hdr
+    )
+    print("-" * sep_len)
+    for op, stats, results, pass_count in stats_data:
+        total = len(results)
+        pass_all = f"{pass_count}/{total}"
+        pass_rate = pass_count / total * 100 if total > 0 else 0
+        tp_col = ""
+        if show_tp:
+            is_data_op = any(op.startswith(p) for p in throughput_ops)
+            if is_data_op:
+                tp_col = " | %s" % _format_throughput(
+                    stats["avg"],
+                    obj_bytes,
+                ).center(14)
+            else:
+                tp_col = " | %s" % "-".center(14)
+
+        print(
+            f"| {op:<20} "
+            f"| {stats['avg']:>12.6f} "
+            f"| {stats['max']:>12.6f} "
+            f"| {stats['min']:>12.6f} "
+            f"| {pass_all:>10} "
+            f"| {pass_rate:>9.1f}% |" + tp_col
+        )
+    print("-" * sep_len)
+
+
+def validate_get_results(get_results, exist_keys, exist_memories, num_tests):
+    """Validate GET operation results and return statistics"""
+    content_valid_count = 0
+    for i, result in enumerate(get_results["results"]):
+        if result is None:
+            print(f"  GET for key {exist_keys[i]} returned None result")
+            continue
+        try:
+            if result.tensor is None:
+                print(f"  GET for key {exist_keys[i]} returned None tensor")
+                continue
+
+            if exist_memories[i].tensor is None:
+                print(f"  Original memory object {i} has None tensor")
+                continue
+
+            # Compare data content
+            data_match = torch.equal(result.tensor, exist_memories[i].tensor)
+
+            if data_match:
+                content_valid_count += 1
+            else:
+                print(f"  GET for key {exist_keys[i]} returned incorrect memory object")
+                print("    Data content mismatch detected")
+
+        except Exception as e:
+            print(f"  Data comparison failed for key {exist_keys[i]}: {e}")
+            # Standard
+            import traceback
+
+            traceback.print_exc()
+
+    # Calculate pass rates
+    not_none_count = sum(1 for r in get_results["results"] if r is not None)
+    content_pass_rate = content_valid_count / num_tests * 100
+    print(f"  Validation (not None): {not_none_count}/{num_tests} passed")
+    print(
+        f"  Validation (content correct): {content_valid_count}/{num_tests}"
+        f" passed ({content_pass_rate:.1f}%)"
+    )
+    return content_valid_count, not_none_count
+
+
+async def run_common_test_framework(
+    test_context,
+    model: str,
+    num_tests: int = 5,
+    settle_time: float = 0.0,
+):
+    """
+    Common test framework for both storage manager and remote backend tests.
+
+    Args:
+        test_context: A dictionary containing test-specific functions and objects:
+            - 'create_test_data_func': Function to create test data
+            - 'async_contains_func': Async function for contains operations
+            - 'async_put_func': Async function for put operations
+            - 'async_get_func': Async function for get operations
+            - 'validate_get_func': Function to validate get results
+            - 'test_object': The main test object (storage_manager or backend)
+            - 'extra_args': Extra arguments for test data creation (optional)
+        model: Model name for testing
+        num_tests: Number of tests to run
+    """
+    print("Testing basic operations...")
+
+    # Create test data using the provided function
+    extra_args = test_context.get("extra_args", [])
+    extra_kwargs = {}
+    if "kv_dtype" in test_context:
+        extra_kwargs["kv_dtype"] = test_context["kv_dtype"]
+    if extra_args:
+        non_exist_keys, exist_keys, exist_memories, num_tests = test_context[
+            "create_test_data_func"
+        ](test_context["test_object"], *extra_args, model, num_tests, **extra_kwargs)
+    else:
+        kv_dtype = test_context.get("kv_dtype")
+        obj_size = test_context.get("obj_size")
+        meta_kw = {}
+        if kv_dtype:
+            meta_kw["kv_dtype"] = kv_dtype
+        if obj_size is not None:
+            meta_kw["obj_size"] = obj_size
+        metadata = _get_default_metadata(model, **meta_kw)
+        non_exist_keys, exist_keys, exist_memories, num_tests = test_context[
+            "create_test_data_func"
+        ](test_context["test_object"], metadata, model, num_tests, **extra_kwargs)
+
+    # Phase 1: exists test (key does not exist)
+    print("Phase 1: Testing exists for non-existing keys...")
+
+    exists_non_exist_res = await run_perf_test_with_timeout(
+        test_context["async_contains_func"],
+        [(test_context["test_object"], key) for key in non_exist_keys],
+    )
+    exists_non_exist_stats = exists_non_exist_res["time_stats"]
+    # Validation: All non-existing keys should return False
+    exists_non_exist_pass_count = sum(
+        1 for r in exists_non_exist_res["results"] if r is False
+    )
+    pass_rate = exists_non_exist_pass_count / len(non_exist_keys) * 100
+    print(
+        f"  Validation: {exists_non_exist_pass_count}/{len(non_exist_keys)} "
+        f"passed ({pass_rate:.1f}%)"
+    )
+
+    # Phase 2: put test (create new key)
+    print("Phase 2: Testing put operations...")
+
+    put_res = await run_perf_test_with_timeout(
+        test_context["async_put_func"],
+        [
+            (test_context["test_object"], exist_keys[i], exist_memories[i])
+            for i in range(num_tests)
+        ],
+    )
+    put_stats = put_res["time_stats"]
+    # Validation: All PUT operations should return True
+    put_pass_count = sum(1 for r in put_res["results"] if r is True)
+    pass_rate = put_pass_count / num_tests * 100
+    print(f"  Validation: {put_pass_count}/{num_tests} passed ({pass_rate:.1f}%)")
+
+    if settle_time > 0:
+        print("  Waiting %.1fs for data to settle..." % settle_time)
+        await asyncio.sleep(settle_time)
+
+    # Phase 3: exists test (key exists)
+    print("Phase 3: Testing exists for existing keys...")
+
+    exists_exist_res = await run_perf_test_with_timeout(
+        test_context["async_contains_func"],
+        [(test_context["test_object"], key) for key in exist_keys],
+    )
+    exists_exist_stats = exists_exist_res["time_stats"]
+    # Validation: All existing keys should return True
+    exists_exist_pass_count = sum(1 for r in exists_exist_res["results"] if r is True)
+    pass_rate = exists_exist_pass_count / num_tests * 100
+    print(
+        f"  Validation: {exists_exist_pass_count}/{num_tests} passed ({pass_rate:.1f}%)"
+    )
+
+    # Phase 4: get test (key exists)
+    print("Phase 4: Testing get operations...")
+
+    get_res = await run_perf_test_with_timeout(
+        test_context["async_get_func"],
+        [(test_context["test_object"], key) for key in exist_keys],
+    )
+    get_stats = get_res["time_stats"]
+    # Validation: Check for non-None results and content correctness
+    content_valid_count, not_none_count = test_context["validate_get_func"](
+        get_res, exist_keys, exist_memories, num_tests
+    )
+    # Use content_valid_count as the pass_count for GET operations
+    get_pass_count = content_valid_count
+
+    stats_data = [
+        (
+            "EXISTS (non-exist)",
+            exists_non_exist_stats,
+            exists_non_exist_res["results"],
+            exists_non_exist_pass_count,
+        ),
+        ("PUT", put_stats, put_res["results"], put_pass_count),
+        (
+            "EXISTS (exist)",
+            exists_exist_stats,
+            exists_exist_res["results"],
+            exists_exist_pass_count,
+        ),
+        ("GET", get_stats, get_res["results"], get_pass_count),
+    ]
+
+    # Compute per-object byte size for throughput display
+    tp_obj_size = test_context.get("obj_size") or DEFAULT_OBJ_SIZE
+    tp_kv_dtype = test_context.get("kv_dtype") or torch.bfloat16
+    obj_bytes = tp_obj_size * torch.tensor([], dtype=tp_kv_dtype).element_size()
+
+    # Use common performance results printing
+    print_performance_results(stats_data, obj_bytes=obj_bytes)
+
+
+class EventLoopManager:
+    """Manages a dedicated event loop in a separate thread"""
+
+    def __init__(self):
+        self.loop = None
+        self.thread = None
+        self._loop_started = threading.Event()
+
+    def start(self):
+        """Start the event loop in a separate thread"""
+        if self.thread is not None and self.thread.is_alive():
+            return
+
+        self.loop = asyncio.new_event_loop()
+        self.thread = threading.Thread(target=self._run_loop, daemon=True)
+        self.thread.start()
+        self._loop_started.wait()
+
+    def _run_loop(self):
+        """Run the event loop"""
+        asyncio.set_event_loop(self.loop)
+        self._loop_started.set()
+        try:
+            self.loop.run_forever()
+        except Exception as e:
+            print(f"Event loop error: {e}")
+        finally:
+            self.loop.close()
+
+    def stop(self):
+        """Stop the event loop and thread"""
+        if self.loop and not self.loop.is_closed():
+            self.loop.call_soon_threadsafe(self.loop.stop)
+        if self.thread and self.thread.is_alive():
+            self.thread.join(timeout=5.0)
+
+    def get_loop(self):
+        """Get the event loop"""
+        return self.loop
diff --git a/lmcache/v1/compute/__init__.py b/lmcache/v1/compute/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/lmcache/v1/compute/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/lmcache/v1/compute/attention/__init__.py b/lmcache/v1/compute/attention/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/compute/attention/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/compute/attention/abstract.py b/lmcache/v1/compute/attention/abstract.py
new file mode 100644
index 0000000..5f26396
--- /dev/null
+++ b/lmcache/v1/compute/attention/abstract.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING
+import abc
+
+# Third Party
+import torch
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.compute.attention.metadata import LMCAttnMetadata
+
+
+class AttentionInterface(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def forward_contiguous(
+        self,
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        output: torch.Tensor,
+        attn_metadata: "LMCAttnMetadata",
+        **kwargs,
+    ) -> torch.Tensor:
+        """
+        Perform forward pass of the attention mechanism.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def init_attn_metadata(
+        self,
+        input_ids: torch.Tensor,
+        **kwargs,
+    ) -> "LMCAttnMetadata":
+        """
+        Initialize attention metadata.
+        """
+        raise NotImplementedError
diff --git a/lmcache/v1/compute/attention/flash_attn.py b/lmcache/v1/compute/attention/flash_attn.py
new file mode 100644
index 0000000..2775134
--- /dev/null
+++ b/lmcache/v1/compute/attention/flash_attn.py
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING
+
+try:
+    # Third Party
+    from vllm.attention import Attention
+except ImportError:
+    # vLLM >= 0.17 moved the Attention class.
+    from vllm.model_executor.layers.attention.attention import Attention
+
+# Third Party
+from vllm.v1.attention.backends.flash_attn import FlashAttentionImpl
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.compute.attention.abstract import AttentionInterface
+from lmcache.v1.compute.attention.metadata import LMCFlashAttnMetadata
+from lmcache.v1.compute.attention.utils import infer_attn_func_from_vllm
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.compute.attention.metadata import LMCAttnMetadata
+
+
+class LMCFlashAttnBackend(AttentionInterface):
+    """
+    FlashAttention backend for LMCache.
+    This backend uses the FlashAttention implementation
+    for efficient attention computation.
+    """
+
+    def __init__(
+        self,
+        vllm_attn: Attention,
+    ):
+        self.vllm_attn = vllm_attn
+        self.vllm_attn_impl: FlashAttentionImpl = vllm_attn.impl
+
+        # TODO(Jiayi): remove this hardcode
+        self.aot_schedule = False
+
+        idx = torch_dev.current_device()
+        self.device = torch.device(f"{torch_device_type}:{idx}")
+        self.flash_attn_varlen_func, self.get_scheduler_metadata = (
+            infer_attn_func_from_vllm(torch_device_type)
+        )
+
+    def forward_contiguous(
+        self,
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        output: torch.Tensor,
+        attn_metadata: "LMCAttnMetadata",
+        **kwargs,
+    ) -> torch.Tensor:
+        assert isinstance(attn_metadata, LMCFlashAttnMetadata)
+
+        cu_seqlens_q = attn_metadata.query_start_loc
+        seqused_k = attn_metadata.seq_lens
+        cu_seqlens_k = attn_metadata.cu_seqlens_k
+        max_seqlen_q = attn_metadata.max_query_len
+        max_seqlen_k = attn_metadata.max_seq_len
+
+        descale_shape = (cu_seqlens_q.shape[0] - 1, key.shape[1])
+
+        # TODO(Jiayi): Figure out how to use aot_schedule.
+        scheduler_metadata = self._schedule(
+            batch_size=1,  # NOTE(Jiayi): Assuming batch size is 1,
+            # since we are processing request by request.
+            cu_query_lens=cu_seqlens_q,
+            max_query_len=max_seqlen_q,
+            seqlens=seqused_k,
+            max_seq_len=max_seqlen_k,
+            causal=True,  # Assuming causal attention
+        )
+
+        self.flash_attn_varlen_func(
+            q=query,  # contiguous
+            k=key,  # contiguous
+            v=value,  # contiguous
+            out=output,
+            cu_seqlens_q=cu_seqlens_q,
+            max_seqlen_q=max_seqlen_q,
+            cu_seqlens_k=cu_seqlens_k,
+            # seqused_k=seqused_k,
+            max_seqlen_k=max_seqlen_k,
+            softmax_scale=self.vllm_attn_impl.scale,
+            causal=True,
+            alibi_slopes=self.vllm_attn_impl.alibi_slopes,
+            window_size=self.vllm_attn_impl.sliding_window,
+            block_table=None,
+            softcap=self.vllm_attn_impl.logits_soft_cap,
+            scheduler_metadata=scheduler_metadata,
+            fa_version=self.vllm_attn_impl.vllm_flash_attn_version,
+            q_descale=self.vllm_attn._q_scale.expand(descale_shape),
+            k_descale=self.vllm_attn._k_scale.expand(descale_shape),
+            v_descale=self.vllm_attn._v_scale.expand(descale_shape),
+        )
+
+        return output
+
+    def _schedule(
+        self, batch_size, cu_query_lens, max_query_len, seqlens, max_seq_len, causal
+    ):
+        if self.aot_schedule:
+            return self.get_scheduler_metadata(
+                batch_size=batch_size,
+                max_seqlen_q=max_query_len,
+                max_seqlen_k=max_seq_len,
+                cache_seqlens=seqlens,
+                num_heads_q=self.vllm_attn_impl.num_heads_q,
+                num_heads_kv=self.vllm_attn_impl.num_heads_kv,
+                headdim=self.vllm_attn_impl.headdim,
+                page_size=self.vllm_attn_impl.block_size,
+                cu_seqlens_q=cu_query_lens,
+                causal=causal,
+                window_size=self.vllm_attn_impl.aot_sliding_window,
+            )
+        return None
+
+    def init_attn_metadata(
+        self,
+        input_ids: torch.tensor,
+        **kwargs,
+    ) -> LMCFlashAttnMetadata:
+        seq_len = input_ids.shape[0]
+        device = input_ids.device
+        return LMCFlashAttnMetadata(
+            query_start_loc=torch.tensor(
+                [0, seq_len], dtype=torch.int32, device=device
+            ),
+            seq_lens=torch.tensor([seq_len], device=device),
+            cu_seqlens_k=torch.tensor([0, seq_len], dtype=torch.int32, device=device),
+            max_query_len=seq_len,
+            max_seq_len=seq_len,
+        )
diff --git a/lmcache/v1/compute/attention/flash_infer_sparse.py b/lmcache/v1/compute/attention/flash_infer_sparse.py
new file mode 100644
index 0000000..357c218
--- /dev/null
+++ b/lmcache/v1/compute/attention/flash_infer_sparse.py
@@ -0,0 +1,285 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, Optional, Tuple, Union
+import math
+
+# Third Party
+from flashinfer import VariableBlockSparseAttentionWrapper
+from flashinfer.page import block_sparse_indices_to_vector_sparse_offsets
+from flashinfer.utils import (
+    TensorLayout,
+    _check_pos_encoding_mode,
+    check_shape_dtype_device,
+    device_support_pdl,
+)
+from vllm.attention import Attention
+from vllm.v1.attention.backends.flashinfer import FlashInferImpl
+import flashinfer
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.compute.attention.abstract import AttentionInterface
+from lmcache.v1.compute.attention.metadata import LMCFlashInferSparseMetadata
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.compute.attention.metadata import LMCAttnMetadata
+
+
+# NOTE(Jiayi): This flashinfer version is 0.3.1.
+class HackBSAWrapper(VariableBlockSparseAttentionWrapper):
+    def run(
+        self,
+        q: torch.Tensor,
+        k: torch.Tensor,
+        v: torch.Tensor,
+        out: Optional[torch.Tensor] = None,
+        lse: Optional[torch.Tensor] = None,
+        return_lse: bool = False,
+        enable_pdl: Optional[bool] = None,
+    ) -> Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]:
+        """
+        This is adapted from https://github.com/flashinfer-ai/flashinfer/blob/cc5ab77370dd9a489357a47e34315d9a8f3ad5fb/flashinfer/sparse.py#L1073
+
+        Compute block-sparse attention between Q/K/V tensors.
+
+        Parameters
+        ----------
+        q : torch.Tensor
+            The query tensor with shape ``(qo_len, num_qo_heads, head_dim)``.
+        k : torch.Tensor
+            The key tensor with shape ``(kv_len, num_kv_heads, head_dim)``.
+        v : torch.Tensor
+            The value tensor with shape ``(kv_len, num_kv_heads, head_dim)``.
+        out : Optional[torch.Tensor]
+            The output tensor, if not provided, will be allocated internally.
+        lse : Optional[torch.Tensor]
+            The log-sum-exp of attention logits, if not provided, will be
+            allocated internally.
+        return_lse : bool
+            Whether to return the log-sum-exp of attention logits
+        enable_pdl : bool
+            Whether to enable Programmatic Dependent Launch (PDL). See https://docs.nvidia.com/cuda/cuda-c-programming-guide/#programmatic-dependent-launch-and-synchronization
+            Only supported for >= sm90, and currently only for FA2 and CUDA core decode.
+
+        Returns
+        -------
+        Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]
+            If :attr:`return_lse` is ``False``, the attention output, shape:
+            ``[M, num_qo_heads, head_dim]``.
+            If :attr:`return_lse` is ``True``, a tuple of two tensors:
+
+            * The attention output, shape: ``[M, num_qo_heads, head_dim]``.
+            * The logsumexp of attention output, shape: ``[M, num_qo_heads]``.
+        """
+
+        if enable_pdl is None:
+            enable_pdl = device_support_pdl(q.device)
+
+        pos_encoding_mode = self._pos_encoding_mode
+        logits_soft_cap = self._logits_soft_cap
+        sm_scale = self._sm_scale
+        rope_scale = self._rope_scale
+        rope_theta = self._rope_theta
+        _check_pos_encoding_mode(pos_encoding_mode)
+        if logits_soft_cap is None:
+            logits_soft_cap = 0.0
+        if sm_scale is None:
+            sm_scale = 1.0 / math.sqrt(q.size(-1))
+        if rope_scale is None:
+            rope_scale = 1.0
+        if rope_theta is None:
+            rope_theta = 1e4
+
+        # 1 denotes page size
+        k = k.reshape(-1, 1, *k.shape[-2:])
+        v = v.reshape(-1, 1, *v.shape[-2:])
+
+        stride_block = k.stride(0)
+        stride_n = k.stride(1)
+
+        if return_lse:
+            if lse is None:
+                lse = torch.empty(
+                    (q.size(0), q.size(1)), dtype=torch.float32, device=q.device
+                )
+            else:
+                check_shape_dtype_device(
+                    lse, (q.size(0), q.size(1)), torch.float32, q.device, "lse"
+                )
+
+        if out is None:
+            out = torch.empty_like(q, dtype=self._o_dtype)
+        else:
+            check_shape_dtype_device(out, q.shape, self._o_dtype, q.device, "out")
+
+        if self._backend == "fa3":
+            if (
+                self._vector_sparse_indices_buffer.numel()
+                <= self._paged_kv_indices_buf.numel()
+            ):
+                raise ValueError(
+                    "_vector_sparse_indices_buffer is not large enough. "
+                    "Please increase the buffer size."
+                )
+
+            sparse_indices = block_sparse_indices_to_vector_sparse_offsets(
+                self._paged_kv_indices_buf,
+                self._paged_kv_indptr_buf,
+                self._vector_sparse_indices_buffer,  # output
+                self._vector_sparse_indptr_buffer,
+                self._kv_lens_buffer,
+                stride_block // stride_n,
+                1,  # stride_n // stride_n
+                1,  # block_size
+            )
+            sparse_indptr = self._vector_sparse_indptr_buffer
+        else:
+            sparse_indices = self._paged_kv_indices_buf
+            sparse_indptr = self._paged_kv_indptr_buf
+
+        self._cached_module.paged_run(
+            self._float_workspace_buffer,
+            self._int_workspace_buffer,
+            self._plan_info,
+            q,
+            k,
+            v,
+            self._qo_indptr,
+            sparse_indptr,
+            sparse_indices,
+            self._paged_kv_last_page_len,
+            out,
+            lse,
+            self._mask_mode,
+            TensorLayout[self._kv_layout].value,
+            -1,  # window_left
+            enable_pdl,
+            # ADDITIONAL_FUNC_PARAMS
+            # Not supported yet
+            None,  # packed_mask_buf
+            None,  # mask_indptr_buf
+            None,  # alibi_slopes_buf
+            None,
+            None,
+            None,
+            logits_soft_cap,
+            sm_scale,
+            None,  # scale_q
+            None,  # scale_k
+            None,  # scale_v
+            rope_scale,
+            rope_theta,
+            0,  # token_pos_in_items_len
+        )
+
+        return (out, lse) if return_lse else out
+
+
+class LMCFlashInferSparseBackend(AttentionInterface):
+    """
+    FlashAttention backend for LMCache.
+    This backend uses the FlashAttention implementation
+    for efficient attention computation.
+    """
+
+    # Workspace buffer size in bytes (128 MiB)
+    _WORKSPACE_BUFFER_SIZE_BYTES = 128 * 1024 * 1024
+
+    def __init__(
+        self,
+        vllm_attn: Attention,
+    ):
+        self.vllm_attn = vllm_attn
+        self.vllm_attn_impl: FlashInferImpl = vllm_attn.impl
+
+        idx = torch_dev.current_device()
+        self.device = torch.device(f"{torch_device_type}:{idx}")
+
+        self.workspace_buffer = torch.empty(
+            self._WORKSPACE_BUFFER_SIZE_BYTES, dtype=torch.uint8, device=self.device
+        )
+
+        self.num_qo_heads = self.vllm_attn_impl.num_heads
+        self.num_kv_heads = self.vllm_attn_impl.num_kv_heads
+        self.head_dim = self.vllm_attn_impl.head_size
+
+        self.sm_scale = self.vllm_attn_impl.scale
+        self.window_left = self.vllm_attn_impl.window_left
+        self.logits_soft_cap = self.vllm_attn_impl.logits_soft_cap
+
+        self.k_scale = vllm_attn._k_scale_float
+        self.v_scale = vllm_attn._v_scale_float
+
+    def forward_contiguous(
+        self,
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        output: torch.Tensor,
+        attn_metadata: "LMCAttnMetadata",
+        **kwargs,
+    ) -> torch.Tensor:
+        assert isinstance(attn_metadata, LMCFlashInferSparseMetadata)
+        is_causal = attn_metadata.is_causal
+        if is_causal:
+            output = flashinfer.prefill.single_prefill_with_kv_cache(
+                q=query,
+                k=key,
+                v=value,
+                scale_q=None,
+                scale_k=self.k_scale,
+                scale_v=self.v_scale,
+                o_dtype=query.dtype,
+                custom_mask=None,
+                packed_custom_mask=None,
+                causal=True,
+                kv_layout="NHD",
+                pos_encoding_mode="NONE",
+                use_fp16_qk_reduction=False,
+                sm_scale=self.sm_scale,
+                window_left=self.window_left,
+                logits_soft_cap=self.logits_soft_cap,
+                rope_scale=None,
+                rope_theta=None,
+                backend="auto",
+                return_lse=False,
+            )
+        else:
+            output = attn_metadata.wrapper.run(query, key, value, output)
+        return output
+
+    def init_attn_metadata(
+        self,
+        input_ids: torch.Tensor,
+        **kwargs,
+    ) -> LMCFlashInferSparseMetadata:
+        """
+        Initialize non-sparse attention metadata first.
+        """
+
+        wrapper = HackBSAWrapper(self.workspace_buffer)
+        seq_len = len(input_ids)
+
+        # TODO(Jiayi): remove this hardcode
+        sparse_blk_row_size = 32
+        sparse_blk_col_size = 32
+
+        num_block_col = seq_len // sparse_blk_col_size
+        last_col_len = seq_len % sparse_blk_col_size
+        block_col_sizes = torch.tensor(
+            [sparse_blk_col_size] * num_block_col, device=self.device
+        )
+        block_col_sizes[-1] += last_col_len
+        return LMCFlashInferSparseMetadata(
+            wrapper,
+            seq_len,
+            self.num_qo_heads,
+            self.num_kv_heads,
+            self.head_dim,
+            block_col_sizes,
+            sparse_blk_row_size,
+            sparse_blk_col_size,
+            is_causal=True,
+        )
diff --git a/lmcache/v1/compute/attention/metadata.py b/lmcache/v1/compute/attention/metadata.py
new file mode 100644
index 0000000..402e898
--- /dev/null
+++ b/lmcache/v1/compute/attention/metadata.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Optional
+import abc
+
+# Third Party
+import torch
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.compute.attention.flash_infer_sparse import HackBSAWrapper
+
+
+@dataclass
+class LMCAttnMetadata(metaclass=abc.ABCMeta):
+    @abstractmethod
+    def update_from_top_indices(self, top_indices: torch.Tensor):
+        raise NotImplementedError("This method should be implemented in subclasses.")
+
+
+@dataclass
+class LMCFlashAttnMetadata(LMCAttnMetadata):
+    query_start_loc: torch.Tensor
+    seq_lens: torch.Tensor
+    cu_seqlens_k: torch.Tensor
+    max_query_len: torch.Tensor
+    max_seq_len: torch.Tensor
+
+    def update_from_top_indices(self, top_indices: torch.Tensor):
+        top_k_num = len(top_indices)
+        self.max_query_len = top_k_num
+        device = self.query_start_loc.device
+        dtype = self.query_start_loc.dtype
+        self.query_start_loc = torch.tensor([0, top_k_num], dtype=dtype, device=device)
+
+
+@dataclass
+class LMCFlashInferSparseMetadata(LMCAttnMetadata):
+    wrapper: "HackBSAWrapper"
+    seq_len: int
+    num_qo_heads: int
+    num_kv_heads: int
+    head_dim: int
+    block_col_sizes: torch.Tensor
+    sparse_blk_row_size: int = 32  # TODO(Jiayi): make this tunable
+    sparse_blk_col_size: int = 32  # TODO(Jiayi): make this tunable
+    is_causal: bool = True
+    q_data_dtype: torch.dtype = torch.bfloat16  # TODO(Jiayi): remove hardcode
+
+    def update_from_top_indices(self, top_indices: torch.Tensor):
+        # self.is_causal = False
+        device = top_indices.device
+        top_k_num = len(top_indices)
+        num_block_row = top_k_num // self.sparse_blk_row_size
+        block_row_sizes = torch.tensor(
+            [self.sparse_blk_row_size] * num_block_row, device=device
+        )
+        block_row_sizes[-1] += top_k_num % self.sparse_blk_row_size
+
+        block_mask_map = torch.zeros(
+            num_block_row, len(self.block_col_sizes), dtype=torch.bool, device=device
+        )
+        cols = torch.arange(block_mask_map.size(1), device=device).expand(
+            block_mask_map.size(0), -1
+        )
+
+        # NOTE(Jiayi): select every `sparse_blk_row_size`-th index from top_indices
+        # to approximate the attention mask at block level.
+        top_indices_slice = top_indices[
+            self.sparse_blk_row_size - 1 :: self.sparse_blk_row_size
+        ]
+        top_indices_slice //= self.sparse_blk_col_size
+        mask = cols < top_indices_slice.unsqueeze(1)
+        block_mask_map[mask] = 1
+        self.wrapper.plan(
+            block_mask_map.expand(self.num_kv_heads, -1, -1),
+            block_row_sizes.expand(self.num_kv_heads, -1),
+            self.block_col_sizes.expand(self.num_kv_heads, -1),
+            self.num_qo_heads,
+            self.num_kv_heads,
+            self.head_dim,
+            q_data_type=self.q_data_dtype,
+        )
+
+
+def _block_mask_to_csr(
+    block_mask: torch.Tensor,
+    device: torch.device,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Convert a 2D boolean block mask to CSR sparse format.
+
+    Args:
+        block_mask: [num_q_blocks, num_kv_blocks] bool tensor
+        device: target device
+
+    Returns:
+        block_indices: [nnz] int32 column indices
+        block_indptr: [num_q_blocks + 1] int32 row pointers
+    """
+    num_q_blocks = block_mask.shape[0]
+    nnz_per_row = block_mask.sum(dim=1)
+    block_indptr = torch.zeros(num_q_blocks + 1, dtype=torch.int32, device=device)
+    torch.cumsum(nnz_per_row, dim=0, out=block_indptr[1:])
+    # Vectorized CSR column index extraction — torch.where naturally
+    # returns an empty tensor when the mask is all-False, so no early
+    # return is needed (and we avoid a .item() CPU-GPU sync).
+    block_indices = torch.where(block_mask)[1].to(torch.int32)
+    return block_indices, block_indptr
+
+
+@dataclass
+class LMCTritonSparseMetadata(LMCAttnMetadata):
+    """Metadata for Triton-based block-sparse attention.
+
+    Drop-in replacement for LMCFlashInferSparseMetadata.
+    Works on both CUDA and ROCm via Triton.
+    """
+
+    seq_len: int = 0
+    num_qo_heads: int = 0
+    num_kv_heads: int = 0
+    head_dim: int = 0
+    sparse_blk_row_size: int = 32
+    sparse_blk_col_size: int = 32
+    is_causal: bool = True
+
+    # Sparse indices (populated by update_from_top_indices)
+    block_indices: Optional[torch.Tensor] = None
+    block_indptr: Optional[torch.Tensor] = None
+
+    # Block column sizes for variable-size last block
+    block_col_sizes: Optional[torch.Tensor] = None
+
+    # LSE from sparse attention (for downstream merge if needed)
+    lse: Optional[torch.Tensor] = None
+
+    # Match flashinfer metadata interface
+    q_data_dtype: torch.dtype = torch.bfloat16
+
+    def update_from_top_indices(self, top_indices: torch.Tensor):
+        """Convert top_indices to CSR sparse structure for Triton kernel.
+
+        Called by CacheBlend when it determines which tokens have cache hits.
+        """
+        self.is_causal = False
+        device = top_indices.device
+        top_k_num = len(top_indices)
+
+        # Use ceiling division so all query positions are covered.
+        # The last block row may be partial (fewer than sparse_blk_row_size
+        # queries) — the kernel handles this via q_mask.
+        num_block_row = (
+            top_k_num + self.sparse_blk_row_size - 1
+        ) // self.sparse_blk_row_size
+        num_block_col = (
+            self.seq_len + self.sparse_blk_col_size - 1
+        ) // self.sparse_blk_col_size
+
+        block_mask = torch.zeros(
+            num_block_row, num_block_col, dtype=torch.bool, device=device
+        )
+
+        top_indices_slice = top_indices[
+            self.sparse_blk_row_size - 1 :: self.sparse_blk_row_size
+        ]
+        top_indices_block = top_indices_slice // self.sparse_blk_col_size
+
+        cols = torch.arange(num_block_col, device=device).expand(
+            len(top_indices_block), -1
+        )
+        mask = cols < top_indices_block.unsqueeze(1)
+        block_mask[: len(top_indices_block)] = mask
+
+        self.block_indices, self.block_indptr = _block_mask_to_csr(block_mask, device)
diff --git a/lmcache/v1/compute/attention/triton_kernels/__init__.py b/lmcache/v1/compute/attention/triton_kernels/__init__.py
new file mode 100644
index 0000000..59df1d6
--- /dev/null
+++ b/lmcache/v1/compute/attention/triton_kernels/__init__.py
@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+# Local
+from .block_sparse_attention import (  # noqa: F401
+    block_sparse_attention,
+    causal_prefill_attention,
+    merge_attention_outputs,
+)
+
+__all__ = [
+    "block_sparse_attention",
+    "causal_prefill_attention",
+    "merge_attention_outputs",
+]
diff --git a/lmcache/v1/compute/attention/triton_kernels/block_sparse_attention.py b/lmcache/v1/compute/attention/triton_kernels/block_sparse_attention.py
new file mode 100644
index 0000000..f329bca
--- /dev/null
+++ b/lmcache/v1/compute/attention/triton_kernels/block_sparse_attention.py
@@ -0,0 +1,559 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Triton block-sparse attention kernel for LMCache CacheBlend.
+
+Replaces flashinfer's VariableBlockSparseAttentionWrapper for ROCm support.
+Works on both CUDA and ROCm via Triton.
+
+The kernel computes attention only over the KV blocks specified by the
+sparse index structure (CSR format: block_indices + block_indptr), skipping
+non-cached blocks. Returns both output and LSE for downstream blending.
+
+Input layout: Q [M, H, D], K [N, H, D], V [N, H, D] (NHD / contiguous)
+Sparse structure: block_indptr [num_q_blocks+1], block_indices [nnz_blocks]
+Output: O [M, H, D], LSE [M, H] (log-sum-exp for blending)
+"""
+
+# Third Party
+import torch
+import triton
+import triton.language as tl
+
+
+@triton.jit
+def _block_sparse_attn_fwd_kernel(
+    Q_ptr,
+    K_ptr,
+    V_ptr,
+    O_ptr,
+    LSE_ptr,
+    block_indices_ptr,  # [nnz_blocks] int32 — which KV blocks to attend
+    block_indptr_ptr,  # [num_q_blocks+1] int32 — CSR row pointers
+    sm_scale: tl.constexpr,
+    seq_len_q,  # total query length
+    seq_len_k,  # total KV length
+    num_csr_rows,  # number of rows in CSR (may differ from grid dim 0)
+    stride_qm,
+    stride_qh,
+    stride_qd,
+    stride_km,
+    stride_kh,
+    stride_kd,
+    stride_vm,
+    stride_vh,
+    stride_vd,
+    stride_om,
+    stride_oh,
+    stride_od,
+    stride_lm,
+    stride_lh,
+    NUM_HEADS: tl.constexpr,
+    NUM_KV_HEADS: tl.constexpr,
+    HEAD_DIM: tl.constexpr,
+    BLOCK_M: tl.constexpr,  # query block size (typically 64 or 128)
+    BLOCK_N: tl.constexpr,  # KV block size (typically 64 or 128)
+):
+    """Block-sparse attention forward kernel.
+
+    Grid: (num_q_blocks, NUM_HEADS)
+    Each program instance computes attention for one query block × one head,
+    iterating only over the KV blocks specified by block_indices.
+    Supports GQA: maps query head_idx to kv_head_idx.
+    """
+    q_block_idx = tl.program_id(0)
+    head_idx = tl.program_id(1)
+
+    # GQA: map query head to KV head
+    kv_head_idx = head_idx * NUM_KV_HEADS // NUM_HEADS
+
+    # Query block range
+    q_start = q_block_idx * BLOCK_M
+    q_offs = q_start + tl.arange(0, BLOCK_M)
+    q_mask = q_offs < seq_len_q
+
+    # Dimension offsets (needed in early-return branch too)
+    d_offs = tl.arange(0, HEAD_DIM)
+
+    # Load the sparse KV block range for this query block
+    # Guard against grid blocks exceeding CSR rows (partial block case)
+    if q_block_idx >= num_csr_rows:
+        # No CSR entry for this block — write zeros and -inf LSE
+        o_ptrs = (
+            O_ptr
+            + q_offs[:, None] * stride_om
+            + head_idx * stride_oh
+            + d_offs[None, :] * stride_od
+        )
+        tl.store(
+            o_ptrs,
+            tl.zeros([BLOCK_M, HEAD_DIM], dtype=Q_ptr.dtype.element_ty),
+            mask=q_mask[:, None],
+        )
+        lse_ptrs = LSE_ptr + q_offs * stride_lm + head_idx * stride_lh
+        tl.store(
+            lse_ptrs, tl.full([BLOCK_M], float("-inf"), dtype=tl.float32), mask=q_mask
+        )
+        return
+
+    kv_block_start = tl.load(block_indptr_ptr + q_block_idx)
+    kv_block_end = tl.load(block_indptr_ptr + q_block_idx + 1)
+    num_kv_blocks = kv_block_end - kv_block_start
+
+    # Load Q block: [BLOCK_M, HEAD_DIM]
+    q_ptrs = (
+        Q_ptr
+        + q_offs[:, None] * stride_qm
+        + head_idx * stride_qh
+        + d_offs[None, :] * stride_qd
+    )
+    q = tl.load(q_ptrs, mask=q_mask[:, None], other=0.0)
+
+    # Online softmax accumulators
+    m_i = tl.full([BLOCK_M], float("-inf"), dtype=tl.float32)
+    l_i = tl.zeros([BLOCK_M], dtype=tl.float32)
+    acc = tl.zeros([BLOCK_M, HEAD_DIM], dtype=tl.float32)
+
+    # Iterate over sparse KV blocks
+    for kv_idx in range(0, num_kv_blocks):
+        # Get the actual KV block index
+        kv_block = tl.load(block_indices_ptr + kv_block_start + kv_idx)
+        kv_start = kv_block * BLOCK_N
+        kv_offs = kv_start + tl.arange(0, BLOCK_N)
+        kv_mask = kv_offs < seq_len_k
+
+        # Load K block: [BLOCK_N, HEAD_DIM] — use kv_head_idx for GQA
+        k_ptrs = (
+            K_ptr
+            + kv_offs[:, None] * stride_km
+            + kv_head_idx * stride_kh
+            + d_offs[None, :] * stride_kd
+        )
+        k = tl.load(k_ptrs, mask=kv_mask[:, None], other=0.0)
+
+        # Compute QK^T: [BLOCK_M, BLOCK_N]
+        qk = tl.dot(q, tl.trans(k)) * sm_scale
+
+        # Mask invalid KV positions
+        qk = tl.where(kv_mask[None, :], qk, float("-inf"))
+
+        # Online softmax update
+        m_ij = tl.max(qk, axis=1)
+        m_new = tl.maximum(m_i, m_ij)
+
+        # Rescale previous accumulator
+        alpha = tl.exp(m_i - m_new)
+        # Compute softmax weights for current block
+        p = tl.exp(qk - m_new[:, None])
+        l_ij = tl.sum(p, axis=1)
+
+        # Update running sum
+        l_new = alpha * l_i + l_ij
+
+        # Rescale accumulator
+        acc = acc * alpha[:, None]
+
+        # Load V block: [BLOCK_N, HEAD_DIM] — use kv_head_idx for GQA
+        v_ptrs = (
+            V_ptr
+            + kv_offs[:, None] * stride_vm
+            + kv_head_idx * stride_vh
+            + d_offs[None, :] * stride_vd
+        )
+        v = tl.load(v_ptrs, mask=kv_mask[:, None], other=0.0)
+
+        # Accumulate: acc += P @ V
+        acc += tl.dot(p.to(v.dtype), v)
+
+        # Update softmax state
+        m_i = m_new
+        l_i = l_new
+
+    # Final normalization — guard against zero-block case (l_i == 0)
+    acc = tl.where(l_i[:, None] > 0, acc / l_i[:, None], 0.0)
+
+    # Compute LSE = m_i + log(l_i); -inf when no blocks attended
+    lse = tl.where(l_i > 0, m_i + tl.log(l_i), float("-inf"))
+
+    # Store output — use input dtype to support both fp16 and bf16
+    o_ptrs = (
+        O_ptr
+        + q_offs[:, None] * stride_om
+        + head_idx * stride_oh
+        + d_offs[None, :] * stride_od
+    )
+    tl.store(o_ptrs, acc.to(Q_ptr.dtype.element_ty), mask=q_mask[:, None])
+
+    # Store LSE
+    lse_ptrs = LSE_ptr + q_offs * stride_lm + head_idx * stride_lh
+    tl.store(lse_ptrs, lse, mask=q_mask)
+
+
+@triton.jit
+def _causal_prefill_attention_kernel(
+    Q_ptr,
+    K_ptr,
+    V_ptr,
+    O_ptr,
+    sm_scale: tl.constexpr,
+    seq_len,
+    stride_qm,
+    stride_qh,
+    stride_qd,
+    stride_km,
+    stride_kh,
+    stride_kd,
+    stride_vm,
+    stride_vh,
+    stride_vd,
+    stride_om,
+    stride_oh,
+    stride_od,
+    NUM_HEADS: tl.constexpr,
+    NUM_KV_HEADS: tl.constexpr,
+    HEAD_DIM: tl.constexpr,
+    BLOCK_M: tl.constexpr,
+    BLOCK_N: tl.constexpr,
+):
+    """Standard causal prefill attention for the is_causal=True path.
+
+    Grid: (cdiv(seq_len, BLOCK_M), NUM_HEADS)
+    Supports GQA: maps query head_idx to kv_head_idx.
+    """
+    q_block_idx = tl.program_id(0)
+    head_idx = tl.program_id(1)
+
+    # GQA: map query head to KV head
+    kv_head_idx = head_idx * NUM_KV_HEADS // NUM_HEADS
+
+    q_start = q_block_idx * BLOCK_M
+    q_offs = q_start + tl.arange(0, BLOCK_M)
+    q_mask = q_offs < seq_len
+    d_offs = tl.arange(0, HEAD_DIM)
+
+    # Load Q
+    q_ptrs = (
+        Q_ptr
+        + q_offs[:, None] * stride_qm
+        + head_idx * stride_qh
+        + d_offs[None, :] * stride_qd
+    )
+    q = tl.load(q_ptrs, mask=q_mask[:, None], other=0.0)
+
+    m_i = tl.full([BLOCK_M], float("-inf"), dtype=tl.float32)
+    l_i = tl.zeros([BLOCK_M], dtype=tl.float32)
+    acc = tl.zeros([BLOCK_M, HEAD_DIM], dtype=tl.float32)
+
+    # Causal: only attend to kv_pos <= q_pos
+    # Iterate over KV blocks up to the causal boundary
+    num_kv_blocks = (q_start + BLOCK_M + BLOCK_N - 1) // BLOCK_N
+    for kv_block_idx in range(num_kv_blocks):
+        kv_start = kv_block_idx * BLOCK_N
+        kv_offs = kv_start + tl.arange(0, BLOCK_N)
+        kv_mask = kv_offs < seq_len
+
+        k_ptrs = (
+            K_ptr
+            + kv_offs[:, None] * stride_km
+            + kv_head_idx * stride_kh
+            + d_offs[None, :] * stride_kd
+        )
+        k = tl.load(k_ptrs, mask=kv_mask[:, None], other=0.0)
+
+        qk = tl.dot(q, tl.trans(k)) * sm_scale
+
+        # Causal mask: attend only where kv_pos <= q_pos
+        causal_mask = kv_offs[None, :] <= q_offs[:, None]
+        qk = tl.where(causal_mask & kv_mask[None, :], qk, float("-inf"))
+
+        m_ij = tl.max(qk, axis=1)
+        m_new = tl.maximum(m_i, m_ij)
+        alpha = tl.exp(m_i - m_new)
+        p = tl.exp(qk - m_new[:, None])
+        l_ij = tl.sum(p, axis=1)
+        l_new = alpha * l_i + l_ij
+        acc = acc * alpha[:, None]
+
+        v_ptrs = (
+            V_ptr
+            + kv_offs[:, None] * stride_vm
+            + kv_head_idx * stride_vh
+            + d_offs[None, :] * stride_vd
+        )
+        v = tl.load(v_ptrs, mask=kv_mask[:, None], other=0.0)
+        acc += tl.dot(p.to(v.dtype), v)
+
+        m_i = m_new
+        l_i = l_new
+
+    acc = acc / l_i[:, None]
+
+    o_ptrs = (
+        O_ptr
+        + q_offs[:, None] * stride_om
+        + head_idx * stride_oh
+        + d_offs[None, :] * stride_od
+    )
+    tl.store(o_ptrs, acc.to(Q_ptr.dtype.element_ty), mask=q_mask[:, None])
+
+
+@triton.jit
+def _merge_attention_kernel(
+    O1_ptr,
+    LSE1_ptr,
+    O2_ptr,
+    LSE2_ptr,
+    Out_ptr,
+    seq_len,
+    stride_om,
+    stride_oh,
+    stride_od,
+    stride_lm,
+    stride_lh,
+    NUM_HEADS: tl.constexpr,
+    HEAD_DIM: tl.constexpr,
+    BLOCK_M: tl.constexpr,
+):
+    """Merge two attention outputs using their LSE values.
+
+    out = (o1 * exp(lse1) + o2 * exp(lse2)) / (exp(lse1) + exp(lse2))
+
+    This is used to blend sparse-attention output (cached blocks)
+    with recomputed output (missing blocks).
+
+    Grid: (cdiv(seq_len, BLOCK_M), NUM_HEADS)
+    """
+    block_idx = tl.program_id(0)
+    head_idx = tl.program_id(1)
+
+    offs = block_idx * BLOCK_M + tl.arange(0, BLOCK_M)
+    mask = offs < seq_len
+    d_offs = tl.arange(0, HEAD_DIM)
+
+    # Load LSE values
+    lse1 = tl.load(
+        LSE1_ptr + offs * stride_lm + head_idx * stride_lh,
+        mask=mask,
+        other=float("-inf"),
+    )
+    lse2 = tl.load(
+        LSE2_ptr + offs * stride_lm + head_idx * stride_lh,
+        mask=mask,
+        other=float("-inf"),
+    )
+
+    # Numerically stable blending — guard against both-inf case
+    max_lse = tl.maximum(lse1, lse2)
+    # When both are -inf, set max_lse to 0 to avoid NaN in exp(-inf - -inf)
+    safe_max = tl.where(max_lse == float("-inf"), 0.0, max_lse)
+    w1 = tl.exp(lse1 - safe_max)
+    w2 = tl.exp(lse2 - safe_max)
+    w_sum = w1 + w2
+    # Guard against w_sum == 0 (both paths had no valid blocks)
+    w_sum = tl.where(w_sum > 0, w_sum, 1.0)
+
+    # Normalize weights
+    w1 = w1 / w_sum
+    w2 = w2 / w_sum
+
+    # Load and blend outputs
+    o1_ptrs = (
+        O1_ptr
+        + offs[:, None] * stride_om
+        + head_idx * stride_oh
+        + d_offs[None, :] * stride_od
+    )
+    o2_ptrs = (
+        O2_ptr
+        + offs[:, None] * stride_om
+        + head_idx * stride_oh
+        + d_offs[None, :] * stride_od
+    )
+
+    o1 = tl.load(o1_ptrs, mask=mask[:, None], other=0.0)
+    o2 = tl.load(o2_ptrs, mask=mask[:, None], other=0.0)
+
+    out = o1 * w1[:, None] + o2 * w2[:, None]
+
+    out_ptrs = (
+        Out_ptr
+        + offs[:, None] * stride_om
+        + head_idx * stride_oh
+        + d_offs[None, :] * stride_od
+    )
+    tl.store(out_ptrs, out.to(O1_ptr.dtype.element_ty), mask=mask[:, None])
+
+
+# ============================================================
+# Python wrappers
+# ============================================================
+
+
+def block_sparse_attention(
+    query: torch.Tensor,  # [M, H, D]
+    key: torch.Tensor,  # [N, H, D]
+    value: torch.Tensor,  # [N, H, D]
+    block_indices: torch.Tensor,  # [nnz_blocks] int32
+    block_indptr: torch.Tensor,  # [num_q_blocks+1] int32
+    sm_scale: float,
+    block_size: int = 64,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Compute block-sparse attention.
+
+    Args:
+        query: [M, H, D] query tensor
+        key: [N, H, D] key tensor
+        value: [N, H, D] value tensor
+        block_indices: [nnz_blocks] which KV blocks to attend to (CSR values)
+        block_indptr: [num_q_blocks+1] CSR row pointers
+        sm_scale: softmax scale (1/sqrt(head_dim))
+        block_size: block size for both Q and KV (default 64)
+
+    Returns:
+        output: [M, H, D] attention output
+        lse: [M, H] log-sum-exp for blending
+    """
+    M, H, D = query.shape
+    N = key.shape[0]
+    KV_H = key.shape[1]  # num_kv_heads (may differ from H for GQA)
+
+    output = torch.empty_like(query)
+    lse = torch.empty(M, H, dtype=torch.float32, device=query.device)
+
+    num_q_blocks = (M + block_size - 1) // block_size
+    # CSR rows may be fewer than grid blocks (partial trailing block)
+    num_csr_rows = block_indptr.shape[0] - 1
+
+    grid = (num_q_blocks, H)
+
+    _block_sparse_attn_fwd_kernel[grid](
+        query,
+        key,
+        value,
+        output,
+        lse,
+        block_indices,
+        block_indptr,
+        sm_scale,
+        M,
+        N,
+        num_csr_rows,
+        query.stride(0),
+        query.stride(1),
+        query.stride(2),
+        key.stride(0),
+        key.stride(1),
+        key.stride(2),
+        value.stride(0),
+        value.stride(1),
+        value.stride(2),
+        output.stride(0),
+        output.stride(1),
+        output.stride(2),
+        lse.stride(0),
+        lse.stride(1),
+        NUM_HEADS=H,
+        NUM_KV_HEADS=KV_H,
+        HEAD_DIM=D,
+        BLOCK_M=block_size,
+        BLOCK_N=block_size,
+    )
+
+    return output, lse
+
+
+def causal_prefill_attention(
+    query: torch.Tensor,  # [M, H, D]
+    key: torch.Tensor,  # [M, H, D]
+    value: torch.Tensor,  # [M, H, D]
+    sm_scale: float,
+    block_size: int = 64,
+) -> torch.Tensor:
+    """Standard causal prefill attention via Triton.
+
+    Args:
+        query: [M, H, D]
+        key: [M, H, D]
+        value: [M, H, D]
+        sm_scale: 1/sqrt(head_dim)
+
+    Returns:
+        output: [M, H, D]
+    """
+    M, H, D = query.shape
+    KV_H = key.shape[1]  # num_kv_heads (may differ from H for GQA)
+    output = torch.empty_like(query)
+
+    grid = ((M + block_size - 1) // block_size, H)
+
+    _causal_prefill_attention_kernel[grid](
+        query,
+        key,
+        value,
+        output,
+        sm_scale,
+        M,
+        query.stride(0),
+        query.stride(1),
+        query.stride(2),
+        key.stride(0),
+        key.stride(1),
+        key.stride(2),
+        value.stride(0),
+        value.stride(1),
+        value.stride(2),
+        output.stride(0),
+        output.stride(1),
+        output.stride(2),
+        NUM_HEADS=H,
+        NUM_KV_HEADS=KV_H,
+        HEAD_DIM=D,
+        BLOCK_M=block_size,
+        BLOCK_N=block_size,
+    )
+
+    return output
+
+
+def merge_attention_outputs(
+    output1: torch.Tensor,  # [M, H, D]
+    lse1: torch.Tensor,  # [M, H]
+    output2: torch.Tensor,  # [M, H, D]
+    lse2: torch.Tensor,  # [M, H]
+    block_size: int = 128,
+) -> torch.Tensor:
+    """Merge two attention outputs using LSE-based blending.
+
+    Used to combine sparse attention (cached blocks) with
+    recomputed attention (missing blocks).
+
+    Args:
+        output1: [M, H, D] first attention output
+        lse1: [M, H] first LSE
+        output2: [M, H, D] second attention output
+        lse2: [M, H] second LSE
+
+    Returns:
+        merged: [M, H, D] blended output
+    """
+    M, H, D = output1.shape
+    merged = torch.empty_like(output1)
+
+    grid = ((M + block_size - 1) // block_size, H)
+
+    _merge_attention_kernel[grid](
+        output1,
+        lse1,
+        output2,
+        lse2,
+        merged,
+        M,
+        output1.stride(0),
+        output1.stride(1),
+        output1.stride(2),
+        lse1.stride(0),
+        lse1.stride(1),
+        NUM_HEADS=H,
+        HEAD_DIM=D,
+        BLOCK_M=block_size,
+    )
+
+    return merged
diff --git a/lmcache/v1/compute/attention/triton_sparse.py b/lmcache/v1/compute/attention/triton_sparse.py
new file mode 100644
index 0000000..0de72a9
--- /dev/null
+++ b/lmcache/v1/compute/attention/triton_sparse.py
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Triton-based block-sparse attention backend for LMCache CacheBlend.
+
+Drop-in replacement for LMCFlashInferSparseBackend that works on ROCm.
+Uses Triton kernels instead of flashinfer for block-sparse attention.
+"""
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.v1.compute.attention.abstract import AttentionInterface
+from lmcache.v1.compute.attention.metadata import (
+    LMCAttnMetadata,
+    LMCTritonSparseMetadata,
+)
+from lmcache.v1.compute.attention.triton_kernels import (
+    block_sparse_attention,
+    causal_prefill_attention,
+)
+
+logger = init_logger(__name__)
+
+
+class LMCTritonSparseBackend(AttentionInterface):
+    """Triton-based block-sparse attention backend for LMCache.
+
+    Drop-in replacement for LMCFlashInferSparseBackend.
+    Works on both CUDA (via Triton) and ROCm (via Triton).
+    Does NOT require flashinfer.
+    """
+
+    def __init__(self, vllm_attn: "torch.nn.Module") -> None:
+        """Initialize from a vLLM Attention module.
+
+        Args:
+            vllm_attn: vLLM Attention layer (for extracting config)
+        """
+        self.vllm_attn = vllm_attn
+        impl = vllm_attn.impl
+
+        self.num_qo_heads = impl.num_heads
+        self.num_kv_heads = impl.num_kv_heads
+        self.head_dim = impl.head_size
+        self.sm_scale = impl.scale
+
+        # Optional scale factors for FP8 KV cache
+        self.k_scale = getattr(impl, "k_scale", None)
+        self.v_scale = getattr(impl, "v_scale", None)
+
+        idx = torch_dev.current_device()
+        self.device = torch.device(f"{torch_device_type}:{idx}")
+
+        logger.info(
+            f"Initialized LMCTritonSparseBackend: "
+            f"heads={self.num_qo_heads}, kv_heads={self.num_kv_heads}, "
+            f"head_dim={self.head_dim}, scale={self.sm_scale:.4f}"
+        )
+
+    def forward_contiguous(
+        self,
+        query: torch.Tensor,  # [M, H, D]
+        key: torch.Tensor,  # [N, H, D]
+        value: torch.Tensor,  # [N, H, D]
+        output: torch.Tensor,  # [M, H, D]
+        attn_metadata: LMCAttnMetadata,
+        **kwargs,
+    ) -> torch.Tensor:
+        """Compute attention using Triton kernels.
+
+        For causal (full prefill): uses causal_prefill_attention.
+        For non-causal (sparse CacheBlend): uses block_sparse_attention.
+        """
+        assert isinstance(attn_metadata, LMCTritonSparseMetadata)
+
+        if attn_metadata.is_causal:
+            output = causal_prefill_attention(
+                query,
+                key,
+                value,
+                sm_scale=self.sm_scale,
+                block_size=64,
+            )
+        else:
+            assert attn_metadata.block_indices is not None, (
+                "Sparse metadata not initialized. Call update_from_top_indices() first."
+            )
+            output, lse = block_sparse_attention(
+                query,
+                key,
+                value,
+                block_indices=attn_metadata.block_indices,
+                block_indptr=attn_metadata.block_indptr,
+                sm_scale=self.sm_scale,
+                # block_size controls BLOCK_M and BLOCK_N in the kernel.
+                # Use sparse_blk_row_size to match the CSR row structure
+                # built by update_from_top_indices.
+                # Note: sparse_blk_row_size == sparse_blk_col_size (both 32)
+                # in the current implementation.
+                block_size=attn_metadata.sparse_blk_row_size,
+            )
+            # Store LSE for downstream blending if needed
+            attn_metadata.lse = lse
+
+        return output
+
+    def init_attn_metadata(
+        self,
+        input_ids: torch.Tensor,
+        **kwargs,
+    ) -> LMCTritonSparseMetadata:
+        """Initialize attention metadata.
+
+        Creates a TritonSparseMetadata with default causal mode.
+        CacheBlend will call update_from_top_indices() to switch to sparse.
+        """
+        seq_len = len(input_ids)
+
+        sparse_blk_row_size = 32
+        sparse_blk_col_size = 32
+
+        num_block_col = (seq_len + sparse_blk_col_size - 1) // sparse_blk_col_size
+        block_col_sizes = torch.full(
+            (num_block_col,),
+            sparse_blk_col_size,
+            dtype=torch.int32,
+            device=self.device,
+        )
+        # Last block may be smaller
+        remainder = seq_len % sparse_blk_col_size
+        if remainder > 0:
+            block_col_sizes[-1] = remainder
+
+        return LMCTritonSparseMetadata(
+            seq_len=seq_len,
+            num_qo_heads=self.num_qo_heads,
+            num_kv_heads=self.num_kv_heads,
+            head_dim=self.head_dim,
+            sparse_blk_row_size=sparse_blk_row_size,
+            sparse_blk_col_size=sparse_blk_col_size,
+            is_causal=True,
+            block_col_sizes=block_col_sizes,
+        )
diff --git a/lmcache/v1/compute/attention/utils.py b/lmcache/v1/compute/attention/utils.py
new file mode 100644
index 0000000..0e9fd96
--- /dev/null
+++ b/lmcache/v1/compute/attention/utils.py
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.compute.attention.abstract import AttentionInterface
+
+logger = init_logger(__name__)
+
+
+def _is_rocm() -> bool:
+    """Check if we're running on ROCm (AMD GPU)."""
+    return torch.version.hip is not None
+
+
+def _flashinfer_available() -> bool:
+    """Check if flashinfer is importable."""
+    try:
+        # Third Party
+        import flashinfer  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def infer_attn_backend_from_vllm(
+    vllm_attn: "torch.nn.Module",
+    enable_sparse: bool = False,
+) -> "AttentionInterface":
+    attn_name = type(vllm_attn.impl).__name__
+
+    if enable_sparse:
+        # On ROCm or when flashinfer is unavailable, use Triton backend
+        if _is_rocm() or not _flashinfer_available():
+            # Local
+            from .triton_sparse import LMCTritonSparseBackend
+
+            logger.info(
+                "Using LMCTritonSparseBackend for CacheBlend "
+                f"(ROCm={_is_rocm()}, flashinfer={_flashinfer_available()})"
+            )
+            return LMCTritonSparseBackend(vllm_attn)
+
+        # On CUDA with flashinfer available, use flashinfer backend
+        # Local
+        from .flash_infer_sparse import LMCFlashInferSparseBackend
+
+        if attn_name == "FlashInferImpl":
+            return LMCFlashInferSparseBackend(vllm_attn)
+        else:
+            # Fallback to Triton even on CUDA if flashinfer impl doesn't match
+            # Local
+            from .triton_sparse import LMCTritonSparseBackend
+
+            logger.info(
+                f"Attention impl {attn_name} is not FlashInferImpl; "
+                "falling back to LMCTritonSparseBackend"
+            )
+            return LMCTritonSparseBackend(vllm_attn)
+
+    elif attn_name == "FlashAttentionImpl" and not enable_sparse:
+        # Local
+        from .flash_attn import LMCFlashAttnBackend
+
+        return LMCFlashAttnBackend(vllm_attn)
+    else:
+        raise ValueError(
+            f"Attention backend {attn_name} is not supported in LMCache. "
+            f"enable_sparse={enable_sparse}"
+        )
+
+
+def infer_attn_func_from_vllm(device_type):
+    if device_type == "cuda":
+        # Third Party
+        from vllm.vllm_flash_attn import flash_attn_varlen_func, get_scheduler_metadata
+    elif device_type == "xpu":
+        # CUDA flash-attention extensions are unavailable on Intel XPU; use the
+        # vLLM-shipped XPU flash-attention ops instead.
+        # Third Party
+        from vllm._xpu_ops import xpu_ops
+
+        flash_attn_varlen_func = xpu_ops.flash_attn_varlen_func
+        get_scheduler_metadata = xpu_ops.get_scheduler_metadata
+    else:
+        raise AssertionError(
+            f"Unsupported device type '{device_type}' for flash attention backends"
+        )
+
+    return flash_attn_varlen_func, get_scheduler_metadata
diff --git a/lmcache/v1/compute/blend/__init__.py b/lmcache/v1/compute/blend/__init__.py
new file mode 100644
index 0000000..1004961
--- /dev/null
+++ b/lmcache/v1/compute/blend/__init__.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.compute.blend.utils import LMCBlenderBuilder
+
+__all__ = [
+    "LMCBlenderBuilder",
+]
diff --git a/lmcache/v1/compute/blend/blender.py b/lmcache/v1/compute/blend/blender.py
new file mode 100644
index 0000000..3619513
--- /dev/null
+++ b/lmcache/v1/compute/blend/blender.py
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.logging import init_logger
+from lmcache.v1.compute.attention.metadata import LMCAttnMetadata
+from lmcache.v1.compute.blend.metadata import LMCBlendCommonMetadata, LMCBlendMetadata
+from lmcache.v1.compute.models.utils import infer_model_from_vllm
+from lmcache.v1.config import LMCacheEngineConfig
+
+logger = init_logger(__name__)
+
+
+class LMCBlender:
+    """
+    Cache-blender backend for LMCache.
+    This backend uses the Blender implementation for efficient blending computation.
+    """
+
+    def __init__(
+        self,
+        cache_engine,
+        gpu_connector,
+        vllm_model,
+        config: LMCacheEngineConfig,
+    ):
+        self.cache_engine = cache_engine
+        self.gpu_connector = gpu_connector
+
+        enable_sparse = False
+        if config.extra_config is not None:
+            enable_sparse = config.extra_config.get("enable_sparse", False)
+
+        self.layerwise_model = infer_model_from_vllm(vllm_model, self, enable_sparse)
+
+        # TODO: remove this hardcode
+        self.num_layers = len(vllm_model.model.layers)
+
+        # TODO(Jiayi): support threshold-based blending
+        # TODO(Jiayi): support different ratios for different layers
+        # TODO(Jiayi): support "skipping blending if hit too short"
+        self.common_metadata = LMCBlendCommonMetadata(
+            check_layers=config.blend_check_layers,
+            recomp_ratios=config.blend_recompute_ratios,
+            thresholds=config.blend_thresholds,
+        )
+
+        # This will be set during the blending process
+        self.metadata = LMCBlendMetadata(
+            imp_indices=None,
+            attn_mask=None,
+            positions=None,
+        )
+
+    def process_qkv(
+        self,
+        q: torch.Tensor,
+        k: torch.Tensor,
+        v: torch.Tensor,
+        residual: torch.Tensor,
+        layer_id: int,
+        attn_output: Optional[torch.Tensor],
+        attn_metadata: LMCAttnMetadata,
+    ):
+        logger.debug(f"Blender is processing KV for layer {layer_id}")
+        old_k, old_v = self.gpu_connector.get_kv(layer_id)
+
+        if attn_output is None:
+            attn_output = torch.empty(
+                q.shape,
+                dtype=q.dtype,
+                device=q.device,
+            )
+
+        # perform positional encoding
+        if self.metadata.positions is None:
+            self.metadata.positions = torch.arange(
+                q.shape[0], device=q.device, dtype=torch.int64
+            )
+        layer = self.layerwise_model.vllm_model.model.layers[layer_id]
+        attn_layer = layer.self_attn
+        q, k = attn_layer.rotary_emb(self.metadata.positions, q, k)
+
+        if layer_id in self.common_metadata.check_layers:
+            diff_k = torch.sum(
+                (k.to(torch.float32) - old_k.to(torch.float32)) ** 2, dim=[1]
+            )
+            total_len = diff_k.shape[0]
+
+            assert self.common_metadata.recomp_ratios is not None
+
+            # TODO(Jiayi): remove `[0]` hardcode
+            topk_num = int(total_len * self.common_metadata.recomp_ratios[0])
+            topk_num = max(topk_num, 1)
+
+            top_indices = torch.topk(diff_k, k=topk_num).indices
+            top_indices, _ = torch.sort(top_indices)
+
+            k, v = k[top_indices], v[top_indices]
+            q = q[top_indices]
+            residual = residual[top_indices]
+
+            logger.debug(f"Number of indices picked: {len(top_indices)}")
+
+            self.metadata.imp_indices = top_indices
+            self.metadata.positions = self.metadata.positions[top_indices]
+            attn_output = attn_output[:topk_num]
+
+            attn_metadata.update_from_top_indices(top_indices)
+
+        if self.metadata.imp_indices is not None:
+            old_k[self.metadata.imp_indices] = k
+            old_v[self.metadata.imp_indices] = v
+            return q, old_k, old_v, residual, attn_output, attn_metadata
+        else:
+            return q, k, v, residual, attn_output, attn_metadata
+
+    # NOTE(Jiayi): Exposing this `blend_layer` interface as we might
+    # want to ochestrate the blending process elsewhere
+    def blend_layer(
+        self,
+        tokens: torch.Tensor,
+        mask: Optional[torch.Tensor] = None,
+        **kwargs,
+    ):
+        """
+        Perform layerwiese retrieve + blending.
+        """
+
+        # TODO(Jiayi): store is currently not included in this function
+
+        layerwise_model_executor = self.layerwise_model.compute_layer(tokens)
+        layerwise_retriever = self.cache_engine.retrieve_layer(tokens, mask, **kwargs)
+
+        next(layerwise_retriever)
+        yield
+
+        for i in range(self.num_layers):
+            next(layerwise_retriever)
+            next(layerwise_model_executor)
+            yield
+
+        next(layerwise_retriever)
+
+        self.metadata.clean()
+        yield
+
+    def blend(
+        self,
+        tokens: Union[torch.Tensor, list[int]],
+        mask: Optional[torch.Tensor] = None,
+        **kwargs,
+    ):
+        """
+        Perform blending for the given tokens.
+        """
+
+        if isinstance(tokens, list):
+            tokens = torch.tensor(tokens).to(torch_device_type)
+
+        layerwise_blender = self.blend_layer(tokens, mask, **kwargs)
+
+        for i in range(self.num_layers + 2):
+            next(layerwise_blender)
diff --git a/lmcache/v1/compute/blend/metadata.py b/lmcache/v1/compute/blend/metadata.py
new file mode 100644
index 0000000..d109530
--- /dev/null
+++ b/lmcache/v1/compute/blend/metadata.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import List, Optional
+
+# Third Party
+import torch
+
+
+@dataclass
+class LMCBlendCommonMetadata:
+    """
+    CommonMetadata (fixed hyperparams) for blending operations in LMCache.
+    """
+
+    check_layers: List[int]
+    recomp_ratios: Optional[List[float]] = None
+    thresholds: Optional[List[float]] = None
+
+
+@dataclass
+class LMCBlendMetadata:
+    """
+    Metadata (determined during runtime) for blending operations in LMCache.
+    """
+
+    imp_indices: Optional[torch.Tensor] = None
+    attn_mask: Optional[torch.Tensor] = None
+    positions: Optional[torch.Tensor] = None
+
+    def clean(self):
+        self.imp_indices = None
+        self.attn_mask = None
+        self.positions = None
diff --git a/lmcache/v1/compute/blend/utils.py b/lmcache/v1/compute/blend/utils.py
new file mode 100644
index 0000000..6a0de15
--- /dev/null
+++ b/lmcache/v1/compute/blend/utils.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, Dict
+
+# Third Party
+from torch import nn
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.compute.blend.blender import LMCBlender
+from lmcache.v1.compute.models.utils import VLLMModelTracker
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_engine import LMCacheEngine
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.gpu_connector import GPUConnectorInterface
+
+logger = init_logger(__name__)
+
+
+class LMCBlenderBuilder:
+    _blenders: Dict[str, LMCBlender] = {}
+
+    @classmethod
+    def get_or_create(
+        cls,
+        instance_id: str,
+        cache_engine: "LMCacheEngine",
+        gpu_connector: "GPUConnectorInterface",
+        config: "LMCacheEngineConfig",
+    ):
+        """
+        Get or create a blender for the given instance_id.
+        """
+
+        if instance_id not in cls._blenders:
+            logger.info(f"Creating blender for {instance_id}")
+            vllm_model = VLLMModelTracker.get_model(instance_id)
+            blender = LMCBlender(
+                cache_engine=cache_engine,
+                gpu_connector=gpu_connector,
+                vllm_model=vllm_model,
+                config=config,
+            )
+            cls._blenders[instance_id] = blender
+        else:
+            logger.info(
+                f"Blender for {instance_id} already exists, returning the original one."
+            )
+        return cls._blenders[instance_id]
+
+    @classmethod
+    def get(
+        cls,
+        instance_id: str,
+    ) -> nn.Module:
+        """
+        Get the blender by instance_id.
+        """
+        if instance_id not in cls._blenders:
+            raise ValueError(f"Blender for {instance_id} not found.")
+        return cls._blenders[instance_id]
diff --git a/lmcache/v1/compute/models/__init__.py b/lmcache/v1/compute/models/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/lmcache/v1/compute/models/base.py b/lmcache/v1/compute/models/base.py
new file mode 100644
index 0000000..0a1812f
--- /dev/null
+++ b/lmcache/v1/compute/models/base.py
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from abc import ABC, abstractmethod
+
+# Third Party
+from torch import nn
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.v1.compute.attention.utils import infer_attn_backend_from_vllm
+from lmcache.v1.compute.positional_encoding import get_fused_rope
+
+# TODO(Jiayi): A few things need to be tested/supported:
+# TP, PP, Multimodal
+
+
+class LMCBaseModel(nn.Module, ABC):
+    def __init__(
+        self,
+        vllm_model,
+        blender,
+        enable_sparse: bool = False,
+    ):
+        super().__init__()
+        self.vllm_model = vllm_model
+
+        self.num_layers = len(vllm_model.model.layers)
+
+        self.vllm_attn_layers = []
+        self.lmc_attn_layers = []
+        for i in range(self.num_layers):
+            vllm_attn = vllm_model.model.layers[i].self_attn.attn
+            self.vllm_attn_layers.append(vllm_attn)
+
+            self.lmc_attn_layers.append(
+                infer_attn_backend_from_vllm(vllm_attn, enable_sparse)
+            )
+
+        # NOTE(Jiayi): better not to pass the blender in init
+        # if we want to make this LMCModel more general.
+        self.blender = blender
+
+        # remove hard code
+        rotary_emb = vllm_model.model.layers[0].self_attn.rotary_emb
+        head_dim = rotary_emb.head_size
+        max_position_embeddings = rotary_emb.max_position_embeddings
+        rope_scaling = None
+        base = rotary_emb.base
+        is_neox_style = rotary_emb.is_neox_style
+        dtype = rotary_emb.dtype
+        self.fused_rotary_emb = get_fused_rope(
+            head_dim,
+            rotary_dim=head_dim,
+            max_position=max_position_embeddings,
+            base=base,
+            rope_scaling=rope_scaling,
+            is_neox_style=is_neox_style,
+            dtype=dtype,
+        )
+
+    @abstractmethod
+    def _process_qkv(self, q, k, v, layer):
+        """Process QKV tensors. Model-specific implementation."""
+        pass
+
+    @torch.compile
+    def compute_layer(
+        self,
+        input_ids: torch.Tensor,
+    ):
+        input_ids = input_ids.to(torch_device_type)
+        # Compatible with both old vLLM (get_input_embeddings) and
+        # new vLLM 0.18+ (embed_input_ids / model.embed_tokens)
+        if hasattr(self.vllm_model, "get_input_embeddings"):
+            hidden_states = self.vllm_model.get_input_embeddings(input_ids)
+        elif hasattr(self.vllm_model, "embed_input_ids"):
+            hidden_states = self.vllm_model.embed_input_ids(input_ids)
+        elif hasattr(self.vllm_model, "model") and hasattr(
+            self.vllm_model.model, "embed_tokens"
+        ):
+            hidden_states = self.vllm_model.model.embed_tokens(input_ids)
+        else:
+            raise AttributeError(
+                f"{type(self.vllm_model).__name__} has no embedding method. "
+                f"Tried: get_input_embeddings, embed_input_ids, model.embed_tokens"
+            )
+        residual = None
+
+        attn_output = None
+
+        # TODO(Jiayi): Need to build `attn_metadata` more elegantly.
+        attn_metadata = self.lmc_attn_layers[0].init_attn_metadata(
+            input_ids=input_ids,
+        )
+
+        for idx, layer in enumerate(
+            self.vllm_model.model.layers[
+                self.vllm_model.model.start_layer : self.vllm_model.model.end_layer
+            ]
+        ):
+            # TODO(Jiayi) The last layer doesn't have to be computed
+            # hidden_states, residual = layer(positions, hidden_states, residual)
+
+            # Self Attention
+            if residual is None:
+                residual = hidden_states
+                hidden_states = layer.input_layernorm(hidden_states)
+            else:
+                hidden_states, residual = layer.input_layernorm(hidden_states, residual)
+            # hidden_states = self.self_attn(positions=positions,
+            #                            hidden_states=hidden_states)
+
+            qkv, _ = layer.self_attn.qkv_proj(hidden_states)
+            q, k, v = qkv.split(
+                [
+                    layer.self_attn.q_size,
+                    layer.self_attn.kv_size,
+                    layer.self_attn.kv_size,
+                ],
+                dim=-1,
+            )
+
+            # Model-specific QKV processing
+            q, k, v = self._process_qkv(q, k, v, layer)
+
+            q, k, v, residual, attn_output, attn_metadata = self.blender.process_qkv(
+                q, k, v, residual, idx, attn_output, attn_metadata
+            )
+
+            num_heads = self.vllm_attn_layers[idx].num_heads
+            num_kv_heads = self.vllm_attn_layers[idx].num_kv_heads
+            head_size = self.vllm_attn_layers[idx].head_size
+
+            q = q.view(-1, num_heads, head_size)
+            k = k.view(-1, num_kv_heads, head_size)
+            v = v.view(-1, num_kv_heads, head_size)
+            attn_output = attn_output.view(-1, num_heads, head_size)
+
+            attn_output = self.lmc_attn_layers[idx].forward_contiguous(
+                q, k, v, attn_output, attn_metadata
+            )
+
+            attn_output = attn_output.view(-1, num_heads * head_size)
+            k = k.view(-1, num_kv_heads * head_size)
+            v = v.view(-1, num_kv_heads * head_size)
+
+            hidden_states, _ = layer.self_attn.o_proj(attn_output)
+
+            # Fully Connected
+            hidden_states, residual = layer.post_attention_layernorm(
+                hidden_states, residual
+            )
+            hidden_states = layer.mlp(hidden_states)
+
+            yield
diff --git a/lmcache/v1/compute/models/llama.py b/lmcache/v1/compute/models/llama.py
new file mode 100644
index 0000000..7899ee0
--- /dev/null
+++ b/lmcache/v1/compute/models/llama.py
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.compute.models.base import LMCBaseModel
+
+
+class LMCLlamaModel(LMCBaseModel):
+    def _process_qkv(self, q, k, v, layer):
+        """Process QKV tensors for LLaMa model (no additional processing)."""
+        return q, k, v
diff --git a/lmcache/v1/compute/models/qwen3.py b/lmcache/v1/compute/models/qwen3.py
new file mode 100644
index 0000000..df64e9c
--- /dev/null
+++ b/lmcache/v1/compute/models/qwen3.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.compute.models.base import LMCBaseModel
+
+
+class LMCQwen3Model(LMCBaseModel):
+    def _process_qkv(self, q, k, v, layer):
+        """Process QKV tensors for Qwen3 model with q_norm and k_norm layers."""
+        # Qwen3 has q_norm and k_norm layers
+        q_by_head = q.view(
+            *q.shape[:-1],
+            q.shape[-1] // layer.self_attn.head_dim,
+            layer.self_attn.head_dim,
+        )
+        q_by_head = layer.self_attn.q_norm(q_by_head)
+        q = q_by_head.view(q.shape)
+        k_by_head = k.view(
+            *k.shape[:-1],
+            k.shape[-1] // layer.self_attn.head_dim,
+            layer.self_attn.head_dim,
+        )
+        k_by_head = layer.self_attn.k_norm(k_by_head)
+        k = k_by_head.view(k.shape)
+        return q, k, v
diff --git a/lmcache/v1/compute/models/utils.py b/lmcache/v1/compute/models/utils.py
new file mode 100644
index 0000000..31e31dd
--- /dev/null
+++ b/lmcache/v1/compute/models/utils.py
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict
+
+# Third Party
+from torch import nn
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def infer_model_from_vllm(vllm_model, blender, enable_sparse: bool = False):
+    model_name = type(vllm_model).__name__
+    if model_name == "LlamaForCausalLM":
+        # First Party
+        from lmcache.v1.compute.models.llama import LMCLlamaModel
+
+        return LMCLlamaModel(vllm_model, blender, enable_sparse)
+    elif model_name == "Qwen2ForCausalLM":
+        # First Party
+        from lmcache.v1.compute.models.llama import LMCLlamaModel
+
+        return LMCLlamaModel(vllm_model, blender, enable_sparse)
+    elif model_name == "Qwen3ForCausalLM":
+        # First Party
+        from lmcache.v1.compute.models.qwen3 import LMCQwen3Model
+
+        return LMCQwen3Model(vllm_model, blender, enable_sparse)
+    else:
+        # TODO(Jiayi): Add support for more models
+        raise NotImplementedError(
+            f"Model type {model_name} is not supported in LMCache."
+        )
+
+
+class VLLMModelTracker:
+    _vllm_models: Dict[str, nn.Module] = {}
+
+    @classmethod
+    def register_model(
+        cls,
+        instance_id: str,
+        vllm_model: nn.Module,
+    ):
+        """
+        Register a vllm model by instance_id.
+        """
+        logger.info(f"Registering vllm model for {instance_id}")
+        if instance_id not in cls._vllm_models:
+            cls._vllm_models[instance_id] = vllm_model
+        else:
+            logger.warning(
+                f"vllm model for {instance_id} already registered, doing nothing."
+            )
+
+    @classmethod
+    def get_model(
+        cls,
+        instance_id: str,
+    ) -> nn.Module:
+        """
+        Get the vllm model by instance_id.
+        """
+        if instance_id not in cls._vllm_models:
+            raise ValueError(f"vllm model for {instance_id} not found.")
+        return cls._vllm_models[instance_id]
diff --git a/lmcache/v1/compute/positional_encoding.py b/lmcache/v1/compute/positional_encoding.py
new file mode 100644
index 0000000..871ce21
--- /dev/null
+++ b/lmcache/v1/compute/positional_encoding.py
@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Callable, Dict, Optional
+
+# Third Party
+from vllm.model_executor.layers.rotary_embedding import get_rope as vllm_get_rope
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.logging import init_logger
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+# TODO(Jiayi): Add and test more types of rope
+# (e.g., rope scaling, (non-)neox style, dtype, etc.)
+
+
+class BasicReverseRope:
+    def __init__(self, rope, rotary_dim, is_neox_style):
+        self.rope = rope
+        self.rotary_dim = rotary_dim
+        self.is_neox_style = is_neox_style
+
+    def do_shuffle(self, t):
+        original_shape = t.shape
+        t = t.reshape(t.shape[0], -1, self.rotary_dim)
+
+        if self.is_neox_style:
+            o1, o2 = torch.chunk(t, 2, dim=-1)
+        else:
+            o1 = t[..., ::2]
+            o2 = t[..., 1::2]
+
+        if self.is_neox_style:
+            return torch.cat((o2, o1), dim=-1).reshape(original_shape)
+        else:
+            return torch.stack((o2, o1), dim=-1).reshape(original_shape)
+
+    def reverse_encode(self, positions, q, k):
+        sq = self.do_shuffle(q)
+        sk = self.do_shuffle(k)
+        nq, nk = self.rope(positions, sq, sk)
+        fq = self.do_shuffle(nq)
+        fk = self.do_shuffle(nk)
+        return fq, fk
+
+    def __call__(self, positions, q, k):
+        return self.reverse_encode(positions, q, k)
+
+
+class FusedRope:
+    """
+    Directly use the fused kernel to ratate K cache from
+    the old positions to the new positions.
+    """
+
+    def __init__(self, rope, is_neox_style):
+        self.rope = rope
+        self.is_neox_style = is_neox_style
+        self.head_size = rope.head_size
+        self.cos_sin_cache = rope.cos_sin_cache
+
+    def fused_encode(self, old_positions, new_positions, k):
+        num_tokens = k.shape[0]
+        k = k.view(num_tokens, -1, self.head_size)
+        lmc_ops.rotary_embedding_k_fused(
+            old_positions,
+            new_positions,
+            k,
+            self.head_size,
+            self.cos_sin_cache.to(k.device),
+            self.is_neox_style,
+        )
+        k = k.view(num_tokens, -1)
+        return k
+
+    def __call__(self, old_positions, new_positions, k):
+        return self.fused_encode(old_positions, new_positions, k)
+
+
+def validate_rope_params(
+    head_size: int,
+    rotary_dim: int,
+    max_position: int,
+    base: float,
+    is_neox_style: bool = True,
+    rope_scaling: Optional[Dict[str, Any]] = None,
+    dtype: Optional[torch.dtype] = None,
+    partial_rotary_factor: float = 1.0,
+):
+    if rotary_dim != head_size:
+        logger.error("Currently KV blending only support rotary_dim == head_size.")
+        return False
+
+    if rope_scaling is not None:
+        logger.error("Currently KV blending do not support rope scaling.")
+        return False
+
+    if partial_rotary_factor != 1.0:
+        logger.error(
+            "Currently KV blending do not support rotary factor other than 1.0."
+        )
+        return False
+
+    return True
+
+
+def validate_reverse_correctness(rope, reverse_rope, fused_rope, head_size) -> bool:
+    hidden_dim = head_size * 8
+    num_tokens = 10
+
+    dumb_q = torch.rand(
+        (num_tokens, hidden_dim), device=torch_device_type, dtype=torch.bfloat16
+    )
+    dumb_k = torch.rand(
+        (num_tokens, hidden_dim), device=torch_device_type, dtype=torch.bfloat16
+    )
+    positions = torch.arange(num_tokens, device=torch_device_type)
+
+    q1 = dumb_q.clone()
+    k1 = dumb_k.clone()
+    q1, k1 = rope(positions, q1, k1)
+    q1, k1 = reverse_rope(positions, q1, k1)
+
+    max_q_error = (dumb_q - q1).abs().max()
+    max_k_error = (dumb_k - k1).abs().max()
+
+    logger.info(f"Max Q error: {max_q_error.item()}")
+    logger.info(f"Max K error: {max_k_error.item()}")
+
+    q_no_pos = dumb_q.clone()
+    k_no_pos = dumb_k.clone()
+    positions2 = torch.arange(100, 100 + num_tokens, device=torch_device_type)
+    _, k_pos2 = rope(positions2, q_no_pos, k_no_pos)
+
+    k_no_pos = dumb_k.clone()
+    _, k_pos1 = rope(positions, q_no_pos, k_no_pos)
+    k_pos2_fused = fused_rope(positions, positions2, k_pos1)
+
+    max_k_error_fused = (k_pos2 - k_pos2_fused).abs().max()
+
+    logger.info(f"Max K error (fused): {max_k_error.item()}")
+
+    return max_q_error < 0.1 and max_k_error < 0.1 and max_k_error_fused < 0.1
+
+
+# Main interface
+def get_fused_rope(
+    head_size: int,
+    rotary_dim: int,
+    max_position: int,
+    base: float,
+    is_neox_style: bool = True,
+    rope_scaling: Optional[Dict[str, Any]] = None,
+    dtype: Optional[torch.dtype] = None,
+    partial_rotary_factor: float = 1.0,
+) -> Optional[Callable[..., Any]]:
+    # Validate the ROPE parameters
+    if not validate_rope_params(
+        head_size,
+        rotary_dim,
+        max_position,
+        base,
+        is_neox_style,
+        rope_scaling,
+        dtype,
+        partial_rotary_factor,
+    ):
+        logger.warning(
+            "The rope parameters is not supported! Cannot use cacheblend in this case"
+        )
+        return None
+
+    new_rope_params = {
+        "rope_theta": base,
+        "partial_rotary_factor": partial_rotary_factor,
+    }
+    if rope_scaling is not None:
+        new_rope_params.update(rope_scaling)
+        if "type" in rope_scaling:
+            new_rope_params["rope_type"] = rope_scaling["type"]
+
+    rope = vllm_get_rope(
+        head_size=head_size,
+        max_position=max_position,
+        is_neox_style=is_neox_style,
+        rope_parameters=new_rope_params,
+        dtype=dtype,
+        dual_chunk_attention_config=None,
+    )
+
+    reverse_rope = BasicReverseRope(rope, rotary_dim, is_neox_style)
+    fused_rope = FusedRope(rope, is_neox_style)
+
+    correct = validate_reverse_correctness(rope, reverse_rope, fused_rope, head_size)
+    if not correct:
+        logger.error(
+            "Fused/reverse rotary encoding is not correct! Will disable blending!"
+        )
+        return None
+
+    return fused_rope
diff --git a/lmcache/v1/config.py b/lmcache/v1/config.py
new file mode 100644
index 0000000..8995c7a
--- /dev/null
+++ b/lmcache/v1/config.py
@@ -0,0 +1,1234 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LMCache Engine Configuration
+
+Configuration system for LMCache Engine that:
+- Loads configuration from YAML file or environment variables
+- Supports command-line parameter overrides
+- Provides convenient access to configuration values
+"""
+
+# Standard
+from typing import Any, Dict, Optional, cast
+import json
+import os
+
+# Third Party
+import yaml
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config_base import (
+    _parse_local_disk,
+    _parse_quoted_string,
+    _resolve_config_aliases,
+    _to_bool,
+    _to_float_list,
+    _to_int_list,
+    _to_str_list,
+    create_config_class,
+    load_config_with_overrides,
+    validate_and_set_config_value,
+)
+
+logger = init_logger(__name__)
+
+
+def _to_hidden_states_retrieve_mode(value: Any) -> str:
+    """Normalize hidden_states_retrieve_mode from YAML/env."""
+    if value is None:
+        return "prefix_strict"
+    s = str(value).strip().lower().replace("-", "_")
+    if s in ("prefix_strict", "prefixstrict"):
+        return "prefix_strict"
+    if s in (
+        "skip_missing_chunks",
+        "skipmissingchunks",
+        "legacy",
+    ):
+        return "skip_missing_chunks"
+    raise ValueError(
+        "hidden_states_retrieve_mode must be 'prefix_strict' or "
+        f"'skip_missing_chunks', got {value!r}"
+    )
+
+
+# Configuration aliases and deprecated mappings
+_CONFIG_ALIASES = {
+    # Maps deprecated names to current names
+    "enable_xpyd": "enable_pd",
+    "nixl_peer_host": "pd_peer_host",
+    "nixl_peer_init_port": "pd_peer_init_port",
+    "nixl_peer_alloc_port": "pd_peer_alloc_port",
+    "nixl_proxy_host": "pd_proxy_host",
+    "nixl_proxy_port": "pd_proxy_port",
+    "nixl_buffer_size": "pd_buffer_size",
+    "nixl_role": "pd_role",
+    "controller_url": "controller_pull_url",
+    "lmcache_worker_port": "lmcache_worker_ports",
+    "plugin_locations": "runtime_plugin_locations",
+    "external_backends": "storage_plugins",
+}
+
+_DEPRECATED_CONFIGS = {
+    # Maps deprecated names to warning messages
+    "nixl_peer_port": "nixl_peer_port is deprecated, use nixl_receiver_port instead",
+    "plugin_locations": (
+        "plugin_locations is deprecated, use runtime_plugin_locations instead"
+    ),
+    "external_backends": (
+        "external_backends is deprecated, use storage_plugins instead"
+    ),
+}
+
+_EC_ENV_PREFIX = "LMCACHE_EC_"
+_EC_FILE_PREFIX = "ec_"
+
+# Single configuration definition center - add new config items only here
+_CONFIG_DEFINITIONS: dict[str, dict[str, Any]] = {
+    # Basic configurations
+    "chunk_size": {"type": int, "default": 256, "env_converter": int},
+    "local_cpu": {
+        "type": bool,
+        "default": True,
+        "env_converter": _to_bool,
+    },
+    "max_local_cpu_size": {"type": float, "default": 5.0, "env_converter": float},
+    "local_cpu_use_hugepages": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "reserve_local_cpu_size": {"type": float, "default": 0.0, "env_converter": float},
+    "local_disk": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": _parse_local_disk,
+    },
+    "local_disk_path_sharding": {
+        "type": str,
+        "default": "by_gpu",
+        "env_converter": str,
+    },
+    "max_local_disk_size": {"type": float, "default": 0.0, "env_converter": float},
+    "remote_url": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "remote_serde": {"type": Optional[str], "default": "naive", "env_converter": str},
+    # Feature toggles
+    "use_layerwise": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "save_decode_cache": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "pre_caching_hash_algorithm": {
+        "type": str,
+        "default": "builtin",
+        "env_converter": str,
+    },
+    # Blending configurations
+    "enable_blending": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "blend_recompute_ratios": {
+        "type": Optional[list[float]],
+        "default": None,
+        "env_converter": _to_float_list,
+    },
+    "blend_thresholds": {
+        "type": Optional[list[float]],
+        "default": None,
+        "env_converter": _to_float_list,
+    },
+    "blend_check_layers": {
+        "type": list[int],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "blend_min_tokens": {"type": int, "default": 256, "env_converter": int},
+    "blend_special_str": {"type": str, "default": " # # ", "env_converter": str},
+    "retrieve_locations": {"type": Optional[list[str]], "default": None},
+    "store_location": {"type": Optional[str], "default": None},
+    # P2P configurations
+    "enable_p2p": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "p2p_host": {"type": Optional[str], "default": None, "env_converter": str},
+    "p2p_init_ports": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "p2p_lookup_ports": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    # MP-server configurations required by SGLang
+    "mp_host": {"type": Optional[str], "default": None, "env_converter": str},
+    "mp_port": {"type": int, "default": 5555, "env_converter": int},
+    # Controller configurations
+    "enable_controller": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "lmcache_instance_id": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "controller_pull_url": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "controller_reply_url": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "lmcache_worker_ports": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "lmcache_worker_ids": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    # LMCache Worker heartbeat
+    # the lmcache_worker_heartbeat_delay_time means that delay a period of time
+    # before starting, ensures that the heartbeat starts working only after the
+    # service is fully ready(such as, waiting register).
+    "lmcache_worker_heartbeat_delay_time": {
+        "type": int,
+        "default": 10,
+        "env_converter": int,
+    },
+    # the lmcache_worker_heartbeat_time means that sending heartbeat periodically.
+    "lmcache_worker_heartbeat_time": {
+        "type": Optional[int],
+        "default": None,
+        "env_converter": int,
+    },
+    # PD-related configurations
+    "enable_pd": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "pd_role": {"type": Optional[str], "default": None, "env_converter": str},
+    "pd_buffer_size": {"type": Optional[int], "default": None, "env_converter": int},
+    "pd_buffer_device": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "pd_peer_host": {"type": Optional[str], "default": None, "env_converter": str},
+    "pd_peer_init_port": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "pd_peer_alloc_port": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "pd_peer_query_port": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "pd_proxy_host": {"type": Optional[str], "default": None, "env_converter": str},
+    "pd_proxy_port": {"type": Optional[int], "default": None, "env_converter": int},
+    "pd_allocation_timeout_sec": {
+        "type": float,
+        "default": float("inf"),
+        "env_converter": float,
+        "description": "Maximum seconds to retry memory allocation before giving up.",
+    },
+    "pd_shutdown_timeout_sec": {
+        "type": float,
+        "default": 5.0,
+        "env_converter": float,
+        "description": (
+            "Maximum seconds to wait for event loop shutdown and thread join."
+        ),
+    },
+    "pd_condition_poll_interval_sec": {
+        "type": float,
+        "default": 0.005,
+        "env_converter": float,
+        "description": (
+            "Polling interval in seconds when waiting on a threading/asyncio "
+            "Condition. Small enough to be responsive, large enough not to "
+            "spin-waste CPU."
+        ),
+    },
+    "pd_max_prefill_len": {
+        "type": int,
+        "default": 0,
+        "env_converter": int,
+        "description": (
+            "Maximum prefill token length that the PD buffer must be able to "
+            "hold. If > 0, initialization raises ValueError when the buffer "
+            "capacity (in tokens) is smaller than this value. "
+            "Set to 0 (default) to skip the check."
+        ),
+    },
+    "pd_backend_mode": {
+        "type": Optional[str],
+        "default": "async",
+        "env_converter": str,
+        "description": (
+            "Select the PD backend implementation: 'async' (default) uses the "
+            "asyncio-based implementation; 'sync' uses the original "
+            "thread-based synchronous implementation."
+        ),
+    },
+    "pd_skip_proxy_notification": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "pd_bidirectional": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    # Transfer-related configurations
+    "transfer_channel": {"type": Optional[str], "default": None, "env_converter": str},
+    # Nixl-related configurations
+    "nixl_backends": {
+        "type": Optional[list[str]],
+        "default": None,
+        "env_converter": _to_str_list,
+    },
+    "nixl_buffer_size": {
+        "type": Optional[int],
+        "default": None,
+        "env_converter": int,
+    },
+    "nixl_buffer_device": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    # Storage paths
+    "gds_path": {"type": Optional[str], "default": None, "env_converter": str},
+    "gds_path_sharding": {
+        "type": str,
+        "default": "by_gpu",
+        "env_converter": str,
+    },
+    "gds_buffer_size": {
+        "type": Optional[int],
+        "default": None,
+        "env_converter": int,
+    },
+    # Maru CXL shared memory backend
+    "maru_path": {"type": Optional[str], "default": None, "env_converter": str},
+    "maru_pool_size": {
+        "type": float,
+        "default": 4.0,
+        "env_converter": float,
+    },
+    # GDS (GPU Direct Storage) settings
+    "use_gds": {
+        "type": bool,
+        "default": True,
+        "env_converter": _to_bool,
+    },
+    "gds_backend": {
+        "type": str,
+        "default": "cufile",
+        "env_converter": str,
+    },
+    # Other configurations
+    # (Deprecated) The url of the actual remote lmcache instance for auditing.
+    # Please use extra_config['audit_actual_remote_url'] instead.
+    "audit_actual_remote_url": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "internal_api_server_host": {
+        "type": str,
+        "default": "0.0.0.0",
+        "env_converter": str,
+    },
+    "extra_config": {
+        "type": Optional[dict],
+        "default": None,
+        "env_converter": lambda x: (
+            x if isinstance(x, dict) else json.loads(x) if x else None
+        ),
+    },
+    "save_unfull_chunk": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "blocking_timeout_secs": {"type": int, "default": 10, "env_converter": int},
+    "external_lookup_client": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "py_enable_gc": {
+        "type": bool,
+        "default": True,
+        "env_converter": _to_bool,
+    },
+    "cache_policy": {
+        "type": str,
+        "default": "LRU",
+        "env_converter": str,
+    },
+    "numa_mode": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "enable_async_loading": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "internal_api_server_enabled": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "internal_api_server_port_start": {
+        "type": int,
+        "default": 6999,
+        "env_converter": int,
+    },
+    "priority_limit": {
+        "type": Optional[int],
+        "default": None,
+        "env_converter": int,
+    },
+    "internal_api_server_include_index_list": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "internal_api_server_socket_path_prefix": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+    },
+    "runtime_plugin_locations": {
+        "type": Optional[list[str]],
+        "default": None,
+        "env_converter": lambda x: x if isinstance(x, list) else [x] if x else [],
+    },
+    "storage_plugins": {
+        "type": Optional[list[str]],
+        "default": None,
+        "env_converter": _to_str_list,
+    },
+    "remote_storage_plugins": {
+        "type": Optional[list[str]],
+        "default": None,
+        "env_converter": _to_str_list,
+    },
+    # Lookup client configurations
+    "lookup_timeout_ms": {
+        "type": int,
+        "default": 3000,
+        "env_converter": int,
+    },
+    "min_retrieve_tokens": {
+        "type": int,
+        "default": 0,
+        "env_converter": int,
+        "description": (
+            "Minimum number of hit tokens required to perform retrieve. "
+            "If hit tokens < min_retrieve_tokens, skip retrieve but the "
+            "actual hit count is still used for skip_leading_tokens to avoid "
+            "re-storing existing chunks. Default is 0 (disabled)."
+        ),
+    },
+    "hit_miss_ratio": {
+        "type": Optional[float],
+        "default": None,
+        "env_converter": float,
+    },
+    "lookup_server_worker_ids": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+    },
+    "enable_scheduler_bypass_lookup": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    "script_allowed_imports": {
+        "type": Optional[list[str]],
+        "default": None,
+        "env_converter": _to_str_list,
+    },
+    # Lazy memory allocator configurations
+    "enable_lazy_memory_allocator": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+        "description": (
+            "Enable lazy memory allocator to reduce initial memory footprint. "
+            "Memory is allocated on-demand and expanded automatically when needed."
+        ),
+    },
+    "lazy_memory_initial_ratio": {
+        "type": float,
+        "default": 0.2,
+        "env_converter": float,
+        "description": (
+            "Initial memory allocation ratio (0.0-1.0). "
+            "Determines the percentage of target memory size to allocate at startup. "
+            "Default is 0.2 (20%)."
+        ),
+    },
+    "lazy_memory_expand_trigger_ratio": {
+        "type": float,
+        "default": 0.5,
+        "env_converter": float,
+        "description": (
+            "Memory usage ratio (0.0-1.0) that triggers automatic expansion. "
+            "When memory usage exceeds this threshold, expansion is triggered. "
+            "Default is 0.5 (50%)."
+        ),
+    },
+    "lazy_memory_step_ratio": {
+        "type": float,
+        "default": 0.1,
+        "env_converter": float,
+        "description": (
+            "Memory expansion step ratio (0.0-1.0). "
+            "Determines the percentage of target memory size to add in each expansion. "
+            "Default is 0.1 (10%)."
+        ),
+    },
+    "lazy_memory_safe_size": {
+        "type": float,
+        "default": 0.0,
+        "env_converter": float,
+        "description": (
+            "Safe threshold size in GB. Lazy allocator is only enabled when "
+            "max_local_cpu_size exceeds this value. Default is 0.0 GB (always enabled)."
+        ),
+    },
+    # Chunk statistics configurations
+    "enable_chunk_statistics": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+        "description": "Enable chunk statistics tracking.",
+    },
+    "chunk_statistics_auto_start_statistics": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+        "description": "Auto-start statistics on init.",
+    },
+    "chunk_statistics_auto_exit_timeout_hours": {
+        "type": float,
+        "default": 0.0,
+        "env_converter": float,
+        "description": "Auto-stop timeout in hours (0=disabled).",
+    },
+    "chunk_statistics_auto_exit_target_unique_chunks": {
+        "type": int,
+        "default": 0,
+        "env_converter": int,
+        "description": "Auto-stop at target unique chunks.",
+    },
+    "chunk_statistics_strategy": {
+        "type": str,
+        "default": "memory_bloom_filter",
+        "env_converter": str,
+        "description": "Recording strategy: memory_bloom_filter or file_hash.",
+    },
+    # KV events configuration
+    "enable_kv_events": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    # TODO(chunxiaozheng): remove this after VLLMPagedMemGPUConnectorV3 is stable
+    "use_gpu_connector_v3": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+    },
+    # Memory management configurations
+    "pin_timeout_sec": {
+        "type": int,
+        "default": 300,
+        "env_converter": int,
+        "description": (
+            "Maximum duration in seconds that a memory object can remain pinned. "
+            "If a pinned object exceeds this timeout, it will be forcibly unpinned "
+            "by the PinMonitor to prevent memory leaks. Default is 300 seconds."
+        ),
+    },
+    "pin_check_interval_sec": {
+        "type": int,
+        "default": 30,
+        "env_converter": int,
+        "description": (
+            "Interval in seconds between PinMonitor timeout checks. "
+            "The background thread periodically scans all pinned objects at this "
+            "interval to detect and handle timeouts. Default is 30 seconds."
+        ),
+    },
+    # Remote configuration service
+    "remote_config_url": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+        "description": (
+            "URL of the remote configuration service. When set, LMCache will "
+            "fetch additional configuration from this URL at startup."
+        ),
+    },
+    "app_id": {
+        "type": Optional[str],
+        "default": None,
+        "env_converter": str,
+        "description": (
+            "Application ID to send to the remote configuration service. "
+            "If not set, the remote service may infer it from current config "
+            "and environment variables."
+        ),
+    },
+    # Hidden state caching configurations (vLLM-Omni multi-stage pipeline)
+    "enable_hidden_state_cache": {
+        "type": bool,
+        "default": False,
+        "env_converter": _to_bool,
+        "description": (
+            "Enable caching of thinker hidden states alongside KV cache entries "
+            "for vLLM-Omni multi-stage pipelines. When enabled, hidden states "
+            "are stored in a separate CPU pinned memory pool and share the same "
+            "chunk keys as their corresponding KV entries."
+        ),
+    },
+    "max_hidden_state_cpu_size": {
+        "type": float,
+        "default": 2.0,
+        "env_converter": float,
+        "description": (
+            "Maximum size in GB of pinned CPU memory for the hidden state cache. "
+            "Each chunk-layer tensor is [chunk_size, hidden_dim] float32. "
+            "Sizing formula: num_cached_layers × chunk_size × hidden_dim × 4 bytes. "
+            "Example: Qwen3-Omni with layers=[0,24], chunk_size=256, hidden_dim=5120 "
+            "→ ~10 MB/chunk; 2 GB allows ≈200 chunks (~51K tokens) of prefix. "
+            "If this budget is too small, hidden entries will be evicted before "
+            "their KV counterparts, causing partial-prefix fallback. "
+            "Relevant only when enable_hidden_state_cache=True."
+        ),
+    },
+    "hidden_state_layers": {
+        "type": Optional[list[int]],
+        "default": None,
+        "env_converter": _to_int_list,
+        "description": (
+            "Optional allowlist of **storage layer indices** accepted by "
+            "HiddenStateStore.store_hidden_states. If None (recommended "
+            "default), every layer index passed on store is cached. "
+            "**Semantics depend on the integration:** these are storage "
+            "layer_idx values, not necessarily transformer layer IDs. For "
+            "example, a multi-stage pipeline may use layer_idx 0 for the main "
+            "hidden-state tensor and 1, 2, … for multimodal output slots; "
+            "copying unrelated examples such as [0, 24] as if they were "
+            '"model layers" can **silently drop** rows stored under other '
+            "indices. Leave this unset unless you have verified the exact "
+            "indices your stack writes—consult your integration's docs. "
+            "Relevant only when enable_hidden_state_cache=True."
+        ),
+    },
+    "hidden_states_retrieve_mode": {
+        "type": str,
+        "default": "prefix_strict",
+        "env_converter": _to_hidden_states_retrieve_mode,
+        "description": (
+            "How to assemble hidden_states_out on retrieve() when some KV-hit "
+            "chunks lack a paired hidden entry. "
+            "'prefix_strict' (default): stop at the first missing chunk — "
+            "outputs align with a contiguous token prefix (recommended for "
+            "thinker→talker). "
+            "'skip_missing_chunks': legacy behavior — skip missing chunks and "
+            "concatenate later chunks; tensor length may not match ret_mask. "
+            "Relevant only when enable_hidden_state_cache=True."
+        ),
+    },
+}
+
+
+# Specialized methods that are unique to LMCacheEngineConfig
+def _validate_config(self):
+    """Validate configuration"""
+
+    # needed for the old async serializer implementation
+    # # auto-adjust save_unfull_chunk for async loading to prevent CPU fragmentation
+    # if self.enable_async_loading:
+    #     logger.warning(
+    #         "Automatically setting save_unfull_chunk=False because "
+    #         "enable_async_loading=True or use_layerwise=True to prevent "
+    #         "CPU memory fragmentation"
+    #     )
+    #     self.save_unfull_chunk = False
+
+    if self.min_retrieve_tokens < 0:
+        raise ValueError(
+            "min_retrieve_tokens must be >= 0, got %d" % self.min_retrieve_tokens
+        )
+
+    if self.enable_blending:
+        if not self.save_unfull_chunk:
+            logger.warning(
+                "Automatically setting save_unfull_chunk=True because "
+                "enable_blending=True"
+            )
+            self.save_unfull_chunk = True
+
+    if self.enable_controller:
+        if self.lmcache_instance_id is None:
+            raise ValueError(
+                "lmcache_instance_id is required when enable_controller=True"
+            )
+        if self.controller_pull_url is None:
+            raise ValueError(
+                "controller_pull_url is required when enable_controller=True"
+            )
+        if self.controller_reply_url is None:
+            raise ValueError(
+                "controller_reply_url is required when enable_controller=True"
+            )
+        if not self.lmcache_worker_ports:
+            raise ValueError(
+                "lmcache_worker_ports is required and cannot be "
+                "empty when enable_controller=True"
+            )
+
+    if self.enable_p2p:
+        assert self.enable_controller
+        assert self.controller_pull_url is not None
+        assert self.controller_reply_url is not None
+        assert self.lmcache_worker_ports is not None
+        assert self.p2p_host is not None
+        assert self.p2p_init_ports is not None
+        assert self.p2p_lookup_ports is not None
+        assert self.transfer_channel is not None
+
+    enable_nixl_storage = self.extra_config is not None and self.extra_config.get(
+        "enable_nixl_storage"
+    )
+    if self.enable_pd:
+        assert self.pd_role is not None
+        assert self.pd_buffer_size is not None
+        assert self.pd_buffer_device is not None
+        assert self.enable_p2p is False, "PD only supports enable_p2p=False"
+        if self.pd_backend_mode not in ("sync", "async"):
+            raise ValueError(
+                f"pd_backend_mode must be 'sync' or 'async', "
+                f"got {self.pd_backend_mode!r}"
+            )
+
+        # PD requires save_unfull_chunk=True for complete KV cache transfer
+        # from prefill node to decode node. Without this, partial chunks would
+        # be discarded, causing incomplete KV cache transfer and wrong results
+        # on the decode node.
+        if not self.save_unfull_chunk:
+            logger.warning(
+                "PD (Peer-to-Peer Disaggregation) requires save_unfull_chunk=True "
+                "for complete KV cache transfer. Automatically setting "
+                "save_unfull_chunk=True."
+            )
+            self.save_unfull_chunk = True
+        else:
+            logger.info(
+                "PD mode enabled with save_unfull_chunk=True - all KV cache "
+                "including partial chunks will be transferred to decode node"
+            )
+
+        # for receiver, PDBackend is for retrieve location
+        # can't take PDBackend as store location
+        # as PDBackend is now one way from producer to receiver only
+        if self.pd_role == "receiver":
+            assert self.store_location != "PDBackend", (
+                "store_location cannot be PDBackend for receiver"
+            )
+            assert self.retrieve_locations in (None, ["PDBackend"]), (
+                "for pd receiver, "
+                'retrieve_locations are expected to be ["PDBackend"], '
+                f"now, it is {self.retrieve_locations}"
+            )
+
+    if enable_nixl_storage:
+        assert self.extra_config.get("nixl_backend") is not None
+        assert self.extra_config.get("nixl_pool_size") is not None
+        if self.extra_config.get(
+            "nixl_presence_cache_only"
+        ) and not self.extra_config.get("nixl_presence_cache"):
+            raise ValueError(
+                "nixl_presence_cache must be true when nixl_presence_cache_only is true"
+            )
+        assert self.nixl_buffer_device is not None
+        if self.nixl_buffer_device == "cpu":
+            # CPU mode shares LocalCPUBackend's pinned pool; nixl_buffer_size
+            # has no effect there. Reject the combo so users don't silently
+            # carry a stale GPU-mode value into a CPU-mode deployment.
+            if self.nixl_buffer_size is not None:
+                raise ValueError(
+                    "nixl_buffer_size must not be set when "
+                    "nixl_buffer_device='cpu'. In CPU mode NIXL shares "
+                    "LocalCPUBackend's pinned pool, which is sized by "
+                    "max_local_cpu_size."
+                )
+            if self.max_local_cpu_size <= 0:
+                raise ValueError(
+                    "nixl_buffer_device='cpu' requires max_local_cpu_size > 0 "
+                    "(LocalCPUBackend's pinned pool is the NIXL staging buffer)."
+                )
+            # With enable_p2p=True, both the P2P backend and the NIXL
+            # storage backend would run their own NIXL agents over
+            # LocalCPUBackend's pinned pool. The pieces are structurally
+            # supported — NIXL allows registering the same memory from
+            # multiple agents, and both backends already allocate via
+            # LocalCPUBackend.allocate() so any contention runs inside
+            # LocalCPUBackend's allocator rather than across backends.
+            # But the combined configuration has no CI coverage and has
+            # not been exercised end-to-end. Reject until it has been.
+            if self.enable_p2p:
+                raise ValueError(
+                    "enable_p2p=True together with enable_nixl_storage=True "
+                    "+ nixl_buffer_device='cpu' has not been validated "
+                    "end-to-end and has no CI coverage. Use enable_p2p=True "
+                    "with nixl_buffer_device='cuda', or disable enable_p2p "
+                    "when using the NIXL CPU shared pool. This rejection "
+                    "can be lifted once the combination is exercised by "
+                    "integration tests."
+                )
+        else:
+            assert self.nixl_buffer_size is not None
+
+        # Deprecation: extra_config.nixl_use_hugepages → local_cpu_use_hugepages.
+        # The flag was always a no-op for GPU buffers (hugepages don't apply);
+        # in CPU mode the pinned pool is now owned by LocalCPUBackend, so
+        # local_cpu_use_hugepages is the only effective knob. Alias the value
+        # in CPU mode, warn in GPU mode, then pop the deprecated key so
+        # downstream readers see a single source of truth.
+        if "nixl_use_hugepages" in self.extra_config:
+            nixl_huge = bool(self.extra_config["nixl_use_hugepages"])
+            user_set = getattr(self, "_user_set_keys", set())
+            if self.nixl_buffer_device == "cpu":
+                if (
+                    "local_cpu_use_hugepages" in user_set
+                    and self.local_cpu_use_hugepages != nixl_huge
+                ):
+                    raise ValueError(
+                        f"Conflicting hugepage settings: "
+                        f"extra_config.nixl_use_hugepages={nixl_huge!r} vs "
+                        f"local_cpu_use_hugepages={self.local_cpu_use_hugepages!r}. "
+                        "extra_config.nixl_use_hugepages is deprecated; "
+                        "remove it and set local_cpu_use_hugepages only."
+                    )
+                logger.warning(
+                    "extra_config.nixl_use_hugepages is deprecated; applying "
+                    "value (%r) to local_cpu_use_hugepages. Update your "
+                    "config to set local_cpu_use_hugepages directly.",
+                    nixl_huge,
+                )
+                self.local_cpu_use_hugepages = nixl_huge
+            else:
+                logger.warning(
+                    "extra_config.nixl_use_hugepages is deprecated and has no "
+                    "effect for nixl_buffer_device=%r (hugepages apply only to "
+                    "the CPU shared pool, controlled by local_cpu_use_hugepages).",
+                    self.nixl_buffer_device,
+                )
+            del self.extra_config["nixl_use_hugepages"]
+
+    return self
+
+
+def _log_config(self):
+    """Log configuration"""
+    config_dict = {}
+    for name in _CONFIG_DEFINITIONS:
+        value = getattr(self, name)
+        if name in ["max_local_cpu_size", "max_local_disk_size"]:
+            value = f"{value} GB"
+        config_dict[name] = value
+
+    logger.info("LMCache Configuration: %s", config_dict)
+    return self
+
+
+def _get_extra_config_value(self, key, default_value=None):
+    if hasattr(self, "extra_config") and self.extra_config is not None:
+        return self.extra_config.get(key, default_value)
+    else:
+        return default_value
+
+
+def _get_lmcache_worker_ids(self, use_mla, world_size):
+    if not self.lmcache_worker_ids:
+        # if mla is not enabled, return all worker ids, which means start
+        # lmcache worker on all ranks as default;
+        # if mla is enabled, return [0], which means start lmcache
+        # worker on worker 0 as default.
+        return [0] if use_mla else list(range(world_size))
+
+    # check the input
+    for worker_id in self.lmcache_worker_ids:
+        assert -1 < worker_id < world_size
+    return self.lmcache_worker_ids
+
+
+def _get_lookup_server_worker_ids(self, use_mla, world_size):
+    if not self.lookup_server_worker_ids:
+        # if mla is not enabled, return all worker ids, which means start
+        # lookup server on all worker as default;
+        # if mla is enabled, return [0], which means start lookup
+        # server on worker 0 as default.
+        return [0] if use_mla else list(range(world_size))
+
+    # check the input
+    for worker_id in self.lookup_server_worker_ids:
+        assert -1 < worker_id < world_size
+    return self.lookup_server_worker_ids
+
+
+def _from_legacy(cls, **kwargs):
+    """Create configuration from legacy format"""
+    backend = kwargs.pop("backend", "cpu")
+
+    # Define backend mappings
+    backend_configs = {
+        "cpu": {
+            "local_cpu": True,
+            "max_local_cpu_size": 2,
+            "local_disk": None,
+            "max_local_disk_size": 0,
+            "remote_url": None,
+        },
+        "local_disk": {
+            "local_cpu": False,
+            "max_local_cpu_size": 3,
+            "local_disk": "local/disk_test/local_disk/",
+            "max_local_disk_size": 2,
+            "remote_url": None,
+        },
+        "local_cpu_disk": {
+            "local_cpu": True,
+            "max_local_cpu_size": 2,
+            "local_disk": "local/disk_test/local_disk/",
+            "max_local_disk_size": 5,
+            "remote_url": None,
+        },
+        "remote": {"local_cpu": False, "max_local_cpu_size": 2, "local_disk": None},
+        "local_cpu_remote": {
+            "local_cpu": True,
+            "max_local_cpu_size": 2,
+            "local_disk": None,
+        },
+        "local_disk_remote": {
+            "local_cpu": False,
+            "max_local_cpu_size": 2,
+            "local_disk": "local/disk_test/local_disk/",
+            "max_local_disk_size": 5,
+        },
+        "local_cpu_disk_remote": {
+            "local_cpu": True,
+            "max_local_cpu_size": 2,
+            "local_disk": "local/disk_test/local_disk/",
+            "max_local_disk_size": 5,
+        },
+    }
+
+    if backend not in backend_configs:
+        raise ValueError(f"Invalid backend: {backend}")
+
+    # Merge configurations
+    config_values = {}
+    for name, config in _CONFIG_DEFINITIONS.items():
+        if name in backend_configs[backend]:
+            config_values[name] = backend_configs[backend][name]
+        elif name in kwargs:
+            config_values[name] = kwargs[name]
+        else:
+            config_values[name] = config["default"]
+
+    instance = cls(**config_values)
+    instance.validate()
+    return instance
+
+
+def _update_config_from_env(self):
+    """Update an existing config object with environment variable configurations."""
+
+    def get_env_name(attr_name: str) -> str:
+        return f"LMCACHE_{attr_name.upper()}"
+
+    # Collect environment variables
+    env_config = {}
+    for name in _CONFIG_DEFINITIONS:
+        env_name = get_env_name(name)
+        env_value = os.getenv(env_name)
+        if env_value is not None:
+            env_config[name] = env_value
+
+    # Handle deprecated environment variables
+    for deprecated_name, new_name in _CONFIG_ALIASES.items():
+        env_name = get_env_name(deprecated_name)
+        env_value = os.getenv(env_name)
+        if env_value is not None:
+            env_config[deprecated_name] = env_value
+
+    # Resolve aliases and handle deprecated configurations
+    resolved_config = _resolve_config_aliases(
+        env_config,
+        "environment variables",
+        _CONFIG_DEFINITIONS,
+        _CONFIG_ALIASES,
+        _DEPRECATED_CONFIGS,
+    )
+
+    # Ensure _user_set_keys exists
+    if not hasattr(self, "_user_set_keys"):
+        object.__setattr__(self, "_user_set_keys", set())
+
+    # Update config object with environment values
+    for name, config in _CONFIG_DEFINITIONS.items():
+        if name in resolved_config:
+            try:
+                # Parse quoted strings and handle escape characters
+                raw_value = resolved_config[name]  # Keep original value for logging
+                value = _parse_quoted_string(raw_value)
+                converted_value = config["env_converter"](value)
+                setattr(self, name, converted_value)
+                # Mark as user-set
+                self._user_set_keys.add(name)
+            except (ValueError, json.JSONDecodeError) as e:
+                logger.warning(
+                    f"Failed to parse {get_env_name(name)}={raw_value!r}: {e}"
+                )
+                # Keep existing value if conversion fails
+    self.validate()
+    return self
+
+
+# Create configuration class using the base utility
+LMCacheEngineConfig = create_config_class(
+    config_name="LMCacheEngineConfig",
+    config_definitions=_CONFIG_DEFINITIONS,
+    config_aliases=_CONFIG_ALIASES,
+    deprecated_configs=_DEPRECATED_CONFIGS,
+    namespace_extras={
+        "validate": _validate_config,
+        "log_config": _log_config,
+        "get_extra_config_value": _get_extra_config_value,
+        "get_lmcache_worker_ids": _get_lmcache_worker_ids,
+        "get_lookup_server_worker_ids": _get_lookup_server_worker_ids,
+        "from_legacy": classmethod(_from_legacy),
+        "update_config_from_env": _update_config_from_env,
+    },
+)
+
+
+def load_engine_config_with_overrides(
+    config_file_path: Optional[str] = None,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> "LMCacheEngineConfig":  # type: ignore[valid-type]
+    """
+    Load engine configuration with support for file, env vars, and overrides.
+
+    This function uses the generic load_config_with_overrides utility from
+    config_base.py to reduce code duplication.
+
+    Args:
+        config_file_path: Optional direct path to config file
+        overrides: Optional dictionary of configuration overrides
+
+    Returns:
+        Loaded and validated LMCacheEngineConfig instance
+    """
+
+    return load_config_with_overrides(
+        config_class=LMCacheEngineConfig,
+        config_file_env_var="LMCACHE_CONFIG_FILE",
+        config_file_path=config_file_path,
+        overrides=overrides,
+    )
+
+
+def _normalize_ec_config_key(raw_key: str, source: str) -> Optional[str]:
+    """Normalize one EC-prefixed config key to a LMCache config key."""
+    key = raw_key.strip().lower()
+    if not key:
+        logger.warning("Empty EC config key from %s", source)
+        return None
+
+    key = _CONFIG_ALIASES.get(key, key)
+    if key not in _CONFIG_DEFINITIONS:
+        logger.warning("Unknown EC config key '%s' from %s", raw_key, source)
+        return None
+    return key
+
+
+def _collect_ec_overrides_from_env() -> dict[str, Any]:
+    """Collect EC-specific overrides from environment variables."""
+    overrides: dict[str, Any] = {}
+    for env_name, env_value in os.environ.items():
+        if not env_name.startswith(_EC_ENV_PREFIX):
+            continue
+        stripped = env_name[len(_EC_ENV_PREFIX) :]
+
+        normalized_key = _normalize_ec_config_key(
+            stripped,
+            source=f"environment variable {env_name}",
+        )
+        if normalized_key is not None:
+            overrides[normalized_key] = env_value
+    return overrides
+
+
+def _collect_ec_overrides_from_file(
+    config_file_path: Optional[str],
+) -> dict[str, Any]:
+    """Collect EC-specific overrides from the LMCache YAML config file."""
+    if not config_file_path:
+        return {}
+
+    try:
+        with open(config_file_path, "r", encoding="utf-8") as fin:
+            loaded = yaml.safe_load(fin) or {}
+    except FileNotFoundError:
+        logger.warning(
+            "LMCache config file %s not found while loading EC overrides",
+            config_file_path,
+        )
+        return {}
+
+    if not isinstance(loaded, dict):
+        logger.warning(
+            "LMCache config file %s is not a mapping; skipping EC overrides",
+            config_file_path,
+        )
+        return {}
+
+    overrides: dict[str, Any] = {}
+    for raw_key, value in loaded.items():
+        if not isinstance(raw_key, str):
+            continue
+
+        lower_key = raw_key.lower()
+        if lower_key == "ec" and isinstance(value, dict):
+            for nested_key, nested_value in value.items():
+                if not isinstance(nested_key, str):
+                    continue
+                normalized_key = _normalize_ec_config_key(
+                    nested_key,
+                    source=f"config file nested key ec.{nested_key}",
+                )
+                if normalized_key is not None:
+                    overrides[normalized_key] = nested_value
+            continue
+
+        if not lower_key.startswith(_EC_FILE_PREFIX):
+            continue
+
+        normalized_key = _normalize_ec_config_key(
+            lower_key[len(_EC_FILE_PREFIX) :],
+            source=f"config file key {raw_key}",
+        )
+        if normalized_key is not None:
+            overrides[normalized_key] = value
+
+    return overrides
+
+
+def _clone_lmcache_engine_config(
+    base_config: "LMCacheEngineConfig",  # type: ignore[valid-type]
+) -> "LMCacheEngineConfig":  # type: ignore[valid-type]
+    """Create a detached LMCacheEngineConfig copy from an existing config."""
+    base_cfg = cast(Any, base_config)
+    cloned_config = LMCacheEngineConfig.from_dict(base_cfg.to_dict())
+    object.__setattr__(
+        cloned_config,
+        "_user_set_keys",
+        set(getattr(base_cfg, "_user_set_keys", set())),
+    )
+    return cloned_config
+
+
+def _apply_ec_storage_defaults(
+    config: "LMCacheEngineConfig",  # type: ignore[valid-type]
+) -> None:
+    """Apply EC-only storage defaults after EC override ingestion."""
+    cfg = cast(Any, config)
+
+    if not cfg.enable_pd:
+        if not cfg.local_cpu:
+            logger.info("EC config enabling local_cpu allocator backend")
+            cfg.local_cpu = True
+        if cfg.max_local_cpu_size <= 0:
+            logger.info("EC config setting max_local_cpu_size to 1 GB")
+            cfg.max_local_cpu_size = 1
+
+    if cfg.local_disk and cfg.max_local_disk_size <= 0:
+        logger.info("EC config setting max_local_disk_size to 64 GB")
+        cfg.max_local_disk_size = 64
+
+
+def load_ec_engine_config(
+    base_config: Optional["LMCacheEngineConfig"] = None,  # type: ignore[valid-type]
+    config_file_path: Optional[str] = None,
+) -> "LMCacheEngineConfig":  # type: ignore[valid-type]
+    """Build EC config from base config plus EC-prefixed overrides.
+
+    Precedence is:
+    1) base LMCache config,
+    2) YAML keys prefixed with ``ec_`` (or ``ec:`` nested map),
+    3) environment variables prefixed with ``LMCACHE_EC_``.
+    """
+    resolved_base_config = base_config
+    if resolved_base_config is None:
+        resolved_base_config = load_engine_config_with_overrides(
+            config_file_path=config_file_path,
+        )
+
+    ec_config = _clone_lmcache_engine_config(resolved_base_config)
+    resolved_config_file = config_file_path or os.getenv("LMCACHE_CONFIG_FILE")
+
+    file_overrides = _collect_ec_overrides_from_file(resolved_config_file)
+    env_overrides = _collect_ec_overrides_from_env()
+    merged_overrides = {**file_overrides, **env_overrides}
+
+    for key, value in merged_overrides.items():
+        if not validate_and_set_config_value(ec_config, key, value, override=True):
+            logger.warning("Failed to apply EC override %s=%r", key, value)
+
+    _apply_ec_storage_defaults(ec_config)
+    cast(Any, ec_config).validate()
+    return ec_config
diff --git a/lmcache/v1/config_base.py b/lmcache/v1/config_base.py
new file mode 100644
index 0000000..ac51c03
--- /dev/null
+++ b/lmcache/v1/config_base.py
@@ -0,0 +1,848 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LMCache Configuration Base Module
+
+This module provides common configuration utilities and base classes
+for all LMCache configuration systems to avoid code duplication.
+"""
+
+# Standard
+from dataclasses import make_dataclass
+from typing import Any, Callable, Dict, Optional, Protocol, Union
+import ast
+import json
+import os
+import threading
+import uuid
+
+# Third Party
+import requests
+import yaml
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def _apply_env_converter_safely(config_definitions, name, value):
+    """Apply env_converter to a value safely."""
+    if name not in config_definitions:
+        return value
+
+    config = config_definitions[name]
+    env_converter = config.get("env_converter")
+    if env_converter:
+        try:
+            # Don't apply converter if value is None
+            if value is None:
+                return None
+            return env_converter(value)
+        except (ValueError, json.JSONDecodeError) as e:
+            log_message = f"Failed to convert value for {name}={value!r}: {e}"
+            logger.warning(log_message)
+            # Return None if conversion fails
+            return None
+    return value
+
+
+# Common configuration parsing utilities
+def _parse_local_disk(local_disk) -> Optional[str]:
+    """Parse local disk path configuration.
+
+    Accepts a single path or comma-separated paths, each optionally
+    prefixed with ``file://``.  Returns a comma-joined string of bare
+    directory paths suitable for ``LocalDiskBackend``.
+
+    Examples::
+
+        "file:///mnt/nvme0/"              -> "/mnt/nvme0/"
+        "/mnt/nvme0/,/mnt/nvme1/"         -> "/mnt/nvme0/,/mnt/nvme1/"
+        "file:///mnt/nvme0/,file:///mnt/nvme1/"
+                                           -> "/mnt/nvme0/,/mnt/nvme1/"
+
+    Args:
+        local_disk: Raw config value — ``None``, a single path, or
+            comma-separated paths.
+
+    Returns:
+        Comma-joined bare directory paths, or ``None`` if disabled.
+    """
+    if local_disk is None:
+        return None
+
+    raw_parts = [p.strip() for p in str(local_disk).split(",") if p.strip()]
+    if not raw_parts:
+        return None
+
+    parsed: list[str] = []
+    for part in raw_parts:
+        if part.startswith("file://"):
+            parsed.append(part[7:])
+        else:
+            parsed.append(part)
+
+    return ",".join(parsed)
+
+
+def _to_int_list(
+    value: Optional[Union[str, int, list[Any]]],
+) -> Optional[list[int]]:
+    """Convert value to list of integers"""
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return [int(x) for x in value]
+    if isinstance(value, int):
+        return [value]
+    parts = [p.strip() for p in str(value).split(",") if p.strip()]
+    return [int(p) for p in parts]
+
+
+def _to_float_list(
+    value: Optional[Union[str, float, list[Any]]],
+) -> Optional[list[float]]:
+    """Convert value to list of floats"""
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return [float(x) for x in value]
+    if isinstance(value, float):
+        return [value]
+    parts = [p.strip() for p in str(value).split(",") if p.strip()]
+    return [float(p) for p in parts]
+
+
+def _to_str_list(
+    value: Optional[Union[str, list[str]]],
+) -> Optional[list[str]]:
+    """Convert value to list of strings"""
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return value
+    parts = [p.strip() for p in value.split(",") if p.strip()]
+    return [p for p in parts]
+
+
+def _to_bool(
+    value: Optional[Union[bool, int, str]],
+) -> bool:
+    """Convert value to boolean"""
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() in ["true", "1"]
+
+
+def _parse_quoted_string(value: str) -> str:
+    """Parse a string that may be surrounded by quotes and handle escape characters.
+
+    Args:
+        value: The input string that may be quoted
+
+    Returns:
+        The unquoted string with escape characters properly handled
+    """
+    if not value:
+        return value
+
+    value = value.strip()
+
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        try:
+            evaluated = ast.literal_eval(value)
+            if isinstance(evaluated, str):
+                return evaluated
+        except (ValueError, SyntaxError):
+            # If ast.literal_eval fails, it's not a valid Python literal.
+            # Fall back to simply stripping the outer quotes.
+            return value[1:-1]
+
+    return value
+
+
+def _to_json(obj: Any) -> str:
+    """Convert object to JSON string"""
+    # If object has to_dict method, use it to convert to dict first
+    if hasattr(obj, "to_dict"):
+        return json.dumps(obj.to_dict(), indent=2)
+    # Otherwise try to serialize directly
+    return json.dumps(obj, indent=2)
+
+
+def _from_json(cls, json_str: str):
+    """Deserialize a JSON string into a configuration object."""
+    try:
+        config_dict = json.loads(json_str)
+        return cls.from_dict(config_dict)
+    except json.JSONDecodeError as e:
+        logger.error("Invalid JSON input: %s", e)
+        raise
+
+
+# Configuration aliases and deprecated mappings utility
+def _resolve_config_aliases(
+    config_dict: dict,
+    source: str,
+    config_definitions: dict,
+    config_aliases: dict,
+    deprecated_configs: dict,
+) -> dict:
+    """Resolve configuration aliases and handle deprecated configurations."""
+    resolved = {}
+
+    # Process each key in the input
+    for key, value in config_dict.items():
+        if key in deprecated_configs:
+            # Log deprecation warning
+            logger.warning("%s (source: %s)", deprecated_configs[key], source)
+
+            # Map to new key if alias exists
+            if key in config_aliases:
+                new_key = config_aliases[key]
+                resolved[new_key] = value
+            else:
+                # Keep deprecated key for backward compatibility
+                resolved[key] = value
+        elif key in config_definitions:
+            # Valid configuration key
+            resolved[key] = value
+        else:
+            # Unknown configuration key
+            logger.warning("Unknown configuration key: %s (source: %s)", key, source)
+
+    return resolved
+
+
+# Base configuration class creator
+def create_config_class(
+    config_name: str,
+    config_definitions: dict[str, dict[str, Any]],
+    config_aliases: Optional[dict[str, str]] = None,
+    deprecated_configs: Optional[dict[str, str]] = None,
+    namespace_extras: Optional[dict[str, Any]] = None,
+    env_prefix: str = "LMCACHE_",
+):
+    """Create a configuration class dynamically with common functionality.
+
+    Args:
+        config_name: Name of the configuration class
+        config_definitions: Dictionary of configuration definitions
+        config_aliases: Optional mapping of deprecated names to current names
+        deprecated_configs: Optional mapping of deprecated names to warning messages
+        namespace_extras: Optional additional namespace items for the class
+        env_prefix: Environment variable prefix (default: "LMCACHE_")
+
+    Returns:
+        A dynamically created dataclass with configuration functionality
+    """
+    # Default values
+    config_aliases = config_aliases or {}
+    deprecated_configs = deprecated_configs or {}
+    namespace_extras = namespace_extras or {}
+
+    # Extract fields from configuration definitions
+    fields_dict = {}
+    for name, config in config_definitions.items():
+        fields_dict[name] = (config["type"], config["default"])
+
+    def _post_init(self):
+        """Post-initialization setup"""
+        # Initialize user-set keys tracking set
+        # This tracks which config keys were explicitly set by user
+        # (via file, env vars, or overrides) vs. using default values
+        if not hasattr(self, "_user_set_keys"):
+            object.__setattr__(self, "_user_set_keys", set())
+        # Generate instance ID if not set
+        if not getattr(self, "lmcache_instance_id", None):
+            self.lmcache_instance_id = f"{config_name.lower()}_{uuid.uuid4().hex}"
+
+    def _from_env(cls):
+        """Load configuration from environment variables"""
+
+        def get_env_name(attr_name: str) -> str:
+            return f"{env_prefix}{attr_name.upper()}"
+
+        # Collect all defined and deprecated env vars
+        all_keys = list(config_definitions.keys()) + list(config_aliases.keys())
+        env_config = {}
+        for name in all_keys:
+            env_name = get_env_name(name)
+            env_value = os.getenv(env_name)
+            if env_value is not None:
+                env_config[name] = env_value
+
+        # Resolve aliases and handle deprecated configurations
+        resolved_config = _resolve_config_aliases(
+            env_config,
+            "environment variables",
+            config_definitions,
+            config_aliases,
+            deprecated_configs,
+        )
+
+        config_values = {}
+        user_set_keys = set()  # Track keys explicitly set by user
+        for name, config in config_definitions.items():
+            if name in resolved_config:
+                try:
+                    raw_value = resolved_config[name]
+                    value = _parse_quoted_string(raw_value)
+                    # Apply env_converter safely
+                    config_values[name] = _apply_env_converter_safely(
+                        config_definitions, name, value
+                    )
+                    user_set_keys.add(name)  # Mark as user-set
+                except (ValueError, json.JSONDecodeError) as e:
+                    raw_value_for_log = resolved_config.get(name, "unknown value")
+                    log_message = (
+                        f"Failed to parse {get_env_name(name)}"
+                        f"={raw_value_for_log!r}: {e}"
+                    )
+                    logger.warning(log_message)
+                    # Use default value with conversion
+                    config_values[name] = _apply_env_converter_safely(
+                        config_definitions, name, config["default"]
+                    )
+            else:
+                # Use default value with conversion
+                config_values[name] = _apply_env_converter_safely(
+                    config_definitions, name, config["default"]
+                )
+
+        instance = cls(**config_values)
+        # Store user-set keys in the instance
+        object.__setattr__(instance, "_user_set_keys", user_set_keys)
+        return instance
+
+    def _from_file(cls, file_path: str):
+        """Load configuration from file"""
+        with open(file_path, "r") as fin:
+            file_config = yaml.safe_load(fin) or {}
+
+        # Resolve aliases and handle deprecated configurations
+        resolved_config = _resolve_config_aliases(
+            file_config,
+            f"file: {file_path}",
+            config_definitions,
+            config_aliases,
+            deprecated_configs,
+        )
+
+        config_values = {}
+        user_set_keys = set()  # Track keys explicitly set by user
+        for name, config in config_definitions.items():
+            if name in resolved_config:
+                value = resolved_config[name]
+                user_set_keys.add(name)  # Mark as user-set
+            else:
+                value = config["default"]
+            # Apply env_converter safely regardless of whether value is None or not
+            config_values[name] = _apply_env_converter_safely(
+                config_definitions, name, value
+            )
+
+        instance = cls(**config_values)
+        # Store user-set keys in the instance
+        object.__setattr__(instance, "_user_set_keys", user_set_keys)
+        return instance
+
+    def _from_defaults(cls, **kwargs):
+        """Create configuration from defaults"""
+        config_values = {}
+        user_set_keys = set()  # Track keys explicitly set by user
+        for name, config in config_definitions.items():
+            if name in kwargs:
+                value = kwargs[name]
+                user_set_keys.add(name)  # Mark as user-set
+            else:
+                value = config["default"]
+            # Apply env_converter safely regardless of whether value is None or not
+            config_values[name] = _apply_env_converter_safely(
+                config_definitions, name, value
+            )
+
+        instance = cls(**config_values)
+        # Store user-set keys in the instance
+        object.__setattr__(instance, "_user_set_keys", user_set_keys)
+        return instance
+
+    def _update_config_from_env(self):
+        """Update an existing config object with environment variable configurations."""
+
+        def get_env_name(attr_name: str) -> str:
+            return f"{env_prefix}{attr_name.upper()}"
+
+        env_config = {}
+        # Collect all defined and deprecated env vars
+        all_keys = list(config_definitions.keys()) + list(config_aliases.keys())
+        for name in all_keys:
+            env_name = get_env_name(name)
+            env_value = os.getenv(env_name)
+            if env_value is not None:
+                env_config[name] = env_value
+
+        # Resolve aliases
+        resolved_config = _resolve_config_aliases(
+            env_config,
+            "environment variables",
+            config_definitions,
+            config_aliases,
+            deprecated_configs,
+        )
+
+        # Ensure _user_set_keys exists
+        if not hasattr(self, "_user_set_keys"):
+            object.__setattr__(self, "_user_set_keys", set())
+
+        # Update config object
+        for name, config in config_definitions.items():
+            if name in resolved_config:
+                try:
+                    raw_value = resolved_config[name]
+                    value = _parse_quoted_string(raw_value)
+                    converted_value = config["env_converter"](value)
+                    setattr(self, name, converted_value)
+                    # Mark as user-set
+                    self._user_set_keys.add(name)
+                except (ValueError, json.JSONDecodeError) as e:
+                    raw_value_for_log = resolved_config.get(name, "unknown value")
+                    log_message = (
+                        f"Failed to parse {get_env_name(name)}"
+                        f"={raw_value_for_log!r}: {e}"
+                    )
+                    logger.warning(log_message)
+
+        return self
+
+    def _from_dict(cls, config_dict: dict):
+        """Create configuration from a dictionary."""
+        resolved_config = _resolve_config_aliases(
+            config_dict,
+            "dictionary input",
+            config_definitions,
+            config_aliases,
+            deprecated_configs,
+        )
+        config_values = {}
+        user_set_keys = set()  # Track keys explicitly set by user
+        for name, config in config_definitions.items():
+            if name in resolved_config:
+                value = resolved_config[name]
+                user_set_keys.add(name)  # Mark as user-set
+            else:
+                value = config["default"]
+            if value is not None:
+                value = config["env_converter"](value)
+            config_values[name] = value
+        instance = cls(**config_values)
+        # Store user-set keys in the instance
+        object.__setattr__(instance, "_user_set_keys", user_set_keys)
+        return instance
+
+    def _to_dict(self):
+        """Convert the configuration object into a dictionary."""
+        return {name: getattr(self, name) for name in config_definitions}
+
+    # Build namespace
+    namespace = {
+        "__post_init__": _post_init,
+        "from_defaults": classmethod(_from_defaults),
+        "from_file": classmethod(_from_file),
+        "from_env": classmethod(_from_env),
+        "update_config_from_env": _update_config_from_env,
+        "from_dict": classmethod(_from_dict),
+        "to_dict": _to_dict,
+        "to_json": _to_json,
+        "from_json": classmethod(_from_json),
+        "__str__": lambda self: str(
+            {name: getattr(self, name) for name in config_definitions}
+        ),
+    }
+
+    # Add extra namespace items
+    namespace.update(namespace_extras)
+
+    # Create class
+    cls = make_dataclass(
+        config_name,
+        [(name, type_, default) for name, (type_, default) in fields_dict.items()],
+        namespace=namespace,
+    )
+
+    # Add config_definitions as a class attribute for accessing converters
+    cls._config_definitions = config_definitions  # type: ignore[attr-defined]
+
+    return cls
+
+
+# Thread-safe singleton utility
+class SingletonGetter(Protocol):
+    """Protocol for singleton getter functions"""
+
+    def __call__(self) -> Any: ...
+
+    reset: Callable[[], None]
+
+
+def create_singleton_config(
+    getter_func_name: str,
+    config_class,
+    config_env_var: str = "LMCACHE_CONFIG_FILE",
+) -> SingletonGetter:
+    """Create thread-safe singleton configuration access pattern.
+
+    Args:
+        getter_func_name: Name for the singleton getter function
+        config_class: The configuration class to create singleton for
+        config_env_var: Environment variable name for configuration file path
+    """
+
+    _config_instance = None
+    _config_lock = threading.Lock()
+
+    def get_or_create_config() -> config_class:
+        """Get the configuration singleton"""
+        nonlocal _config_instance
+
+        # Double-checked locking for thread-safe singleton
+        if _config_instance is None:
+            with _config_lock:
+                if _config_instance is None:  # Check again within lock
+                    if config_env_var not in os.environ:
+                        logger.warning(
+                            "No configuration file is set. Trying to read "
+                            "configurations from the environment variables."
+                        )
+                        logger.warning(
+                            f"You can set the configuration file through "
+                            f"the environment variable: {config_env_var}"
+                        )
+                        _config_instance = config_class.from_env()
+                    else:
+                        config_file = os.environ[config_env_var]
+                        logger.info("Loading config file %s", config_file)
+                        _config_instance = config_class.from_file(config_file)
+                        # Update config from environment variables
+                        _config_instance.update_config_from_env()
+
+        return _config_instance
+
+    def reset_config_instance() -> None:
+        """Reset the configuration singleton for testing"""
+        nonlocal _config_instance
+        with _config_lock:
+            _config_instance = None
+
+    # Set the function name for better debugging
+    get_or_create_config.__name__ = getter_func_name
+    get_or_create_config.reset = reset_config_instance  # type: ignore[attr-defined]
+
+    return get_or_create_config  # type: ignore[return-value]
+
+
+def load_config_with_overrides(
+    config_class,
+    config_file_env_var: str = "LMCACHE_CONFIG_FILE",
+    config_file_path: Optional[str] = None,
+    overrides: Optional[Dict[str, Any]] = None,
+):
+    """
+    Load configuration with support for file, environment variables, and overrides.
+
+    This is a generic utility function that can be reused across different
+    configuration classes (LMCacheEngineConfig, ControllerConfig, etc.)
+
+    Args:
+        config_class: The configuration class to instantiate
+        config_file_env_var: Environment variable name for config file path
+        config_file_path: Optional direct config file path (overrides env var)
+        overrides: Optional dictionary of configuration overrides
+
+    Returns:
+        Loaded and validated configuration instance
+    """
+    # Load configuration from file or environment
+    actual_config_path = config_file_path or os.getenv(config_file_env_var)
+
+    if actual_config_path:
+        logger.info("Loading config file: %s", actual_config_path)
+        config = config_class.from_file(actual_config_path)
+        # Allow environment variables to override file settings
+        config.update_config_from_env()
+    else:
+        logger.info("No config file specified, loading from environment variables.")
+        config = config_class.from_env()
+
+    # Apply any overrides
+    if overrides:
+        for key, value in overrides.items():
+            if hasattr(config, key):
+                old_value = getattr(config, key)
+
+                # Check if this configuration class has definitions with converters
+                if (
+                    hasattr(config, "_config_definitions")
+                    and key in config._config_definitions
+                ):
+                    # Use the global helper function to safely apply env_converter
+                    new_value = _apply_env_converter_safely(
+                        config._config_definitions, key, value
+                    )
+                    setattr(config, key, new_value)
+                else:
+                    setattr(config, key, value)
+
+                new_value = getattr(config, key)
+                if old_value != new_value:
+                    logger.info(
+                        "Override config: %s = %s (was %s)", key, new_value, old_value
+                    )
+            else:
+                logger.warning("Unknown config key: %s, ignoring", key)
+
+    # Validate configuration
+    if hasattr(config, "validate"):
+        config.validate()
+
+    # Log configuration
+    if hasattr(config, "log_config"):
+        config.log_config()
+
+    return config
+
+
+def parse_command_line_extra_params(extra_args: list[str]) -> dict[str, Any]:
+    """
+    Parse extra command-line parameters in key=value format.
+
+    Args:
+        extra_args: List of strings in format "key=value"
+
+    Returns:
+        Dictionary of parsed parameters
+    """
+    params = {}
+    for arg in extra_args:
+        if "=" in arg:
+            key, value = arg.split("=", 1)
+            key = key.lstrip("-")
+            try:
+                if value.lower() in ("true", "false"):
+                    params[key] = value.lower() == "true"
+                elif value.isdigit():
+                    params[key] = int(value)  # type: ignore[assignment]
+                elif value.replace(".", "", 1).isdigit():
+                    params[key] = float(value)  # type: ignore[assignment]
+                else:
+                    params[key] = value  # type: ignore[assignment]
+            except ValueError:
+                params[key] = value  # type: ignore[assignment]
+            logger.info("Extra parameter: %s = %s", key, params[key])
+    return params
+
+
+def validate_and_set_config_value(config, config_key, value, override: bool = True):
+    """Validate and set configuration value.
+
+    Args:
+        config: Configuration object to update.
+        config_key: The configuration key to set.
+        value: The value to set.
+        override: If True, completely replace the value. If False:
+            - For 'extra_config': merge with existing dict (new values take
+              precedence for conflicting keys).
+            - For other keys: skip if key was user-set.
+            Default is True.
+
+    Returns:
+        True if the value was set successfully, False otherwise.
+    """
+    if not hasattr(config, config_key):
+        logger.warning("Config key '%s' does not exist in configuration", config_key)
+        return False
+
+    try:
+        # Apply type conversion using env_converter if available
+        # Skip for extra_config which has special handling below
+        if hasattr(config, "_config_definitions") and config_key != "extra_config":
+            original_value = value
+            value = _apply_env_converter_safely(
+                config._config_definitions, config_key, value
+            )
+            # If original value was not None but conversion returned None,
+            # it means conversion failed
+            if original_value is not None and value is None:
+                # _apply_env_converter_safely already logged warning
+                return False
+
+        # Convert string to dict for extra_config
+        if config_key == "extra_config" and isinstance(value, str):
+            value = json.loads(value) if value else None
+
+        # Handle extra_config special logic
+        if config_key == "extra_config":
+            current_value = getattr(config, config_key, None)
+
+            # Handle None or empty value when override=False
+            if not override and (value is None or value == ""):
+                # Keep current value
+                logger.info(
+                    "Keeping current extra_config (override=False, value is None/empty)"
+                )
+                return True
+
+            if override:
+                # Full override: replace current value with new value
+                setattr(config, config_key, value)
+                logger.info("Overridden extra_config")
+                return True
+            else:
+                # Merge mode (override=False)
+                if value is not None and isinstance(value, dict):
+                    if current_value is not None and isinstance(current_value, dict):
+                        # Merge: current values preserved, new values override
+                        merged_value = {**current_value, **value}
+                        setattr(config, config_key, merged_value)
+                        logger.info("Merged extra_config")
+                    else:
+                        # Current value is None or not a dict, set new value
+                        setattr(config, config_key, value)
+                        logger.info("Set extra_config")
+                return True
+
+        # For non-extra_config keys: skip if override=False and key user-set
+        if not override:
+            user_set_keys: set[str] = getattr(config, "_user_set_keys", set())
+            if config_key in user_set_keys:
+                current_value = getattr(config, config_key, None)
+                logger.info(
+                    "Skipping config %s (override=False, user-set value=%s)",
+                    config_key,
+                    current_value,
+                )
+                # Return True to indicate operation completed (kept existing)
+                return True
+
+        setattr(config, config_key, value)
+        logger.info("Set config item '%s'", config_key)
+        return True
+    except Exception as e:
+        logger.error(
+            "Failed to set config item '%s' with value %s: %s",
+            config_key,
+            value,
+            e,
+        )
+        return False
+
+
+def fetch_remote_config(
+    remote_config_url: str,
+    app_id: Optional[str],
+    config: Any,
+    timeout: int = 10,
+) -> Optional[dict]:
+    """Fetch configuration from remote config service.
+
+    The config server protocol:
+    - Request: POST with JSON body containing 'current_config' and 'env_variables'
+    - Query parameter: 'appId' if app_id is provided
+    - Response: JSON with 'configs' array, each item has 'key', 'value', 'override'
+
+    See examples/remote_config_server/ for a reference implementation.
+
+    Args:
+        remote_config_url: URL of the remote config service.
+        app_id: Optional app ID to send to the config service.
+        config: Current LMCacheEngineConfig to send to the config service.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Parsed JSON response from the config service, or None if failed.
+    """
+    try:
+        # Build request payload with current config and env variables
+        payload: dict[str, Any] = {
+            "current_config": config.to_dict(),
+            "env_variables": {k: v for k, v in os.environ.items()},
+        }
+
+        # Build URL with app_id query parameter if provided
+        params = {"appId": app_id} if app_id else None
+
+        # Send POST request with JSON payload
+        response = requests.get(
+            remote_config_url,
+            json=payload,
+            params=params,
+            headers={"Content-Type": "application/json"},
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return response.json()
+
+    except requests.RequestException as e:
+        logger.warning(
+            "Failed to fetch remote config from %s: %s", remote_config_url, e
+        )
+        return None
+    except json.JSONDecodeError as e:
+        logger.warning("Failed to parse remote config response: %s", e)
+        return None
+    except Exception as e:
+        logger.warning("Unexpected error fetching remote config: %s", e)
+        return None
+
+
+def apply_remote_configs(config: Any, remote_response: dict) -> Any:
+    """Apply remote configuration to LMCacheEngineConfig.
+
+    This function extracts the 'configs' field from the remote response
+    and applies each config item to the LMCacheEngineConfig instance.
+
+    The expected format of remote_response['configs'] is:
+    [
+        {"override": true, "key": "config_key", "value": "config_value"},
+        ...
+    ]
+
+    Args:
+        config: LMCacheEngineConfig instance to update.
+        remote_response: Response from the remote config service.
+
+    Returns:
+        Updated LMCacheEngineConfig instance.
+    """
+    configs = remote_response.get("configs", [])
+    if not configs:
+        logger.info("No configs found in remote response")
+        return config
+
+    applied_count = 0
+    for config_item in configs:
+        if not isinstance(config_item, dict):
+            logger.warning("Invalid config item format: %s", config_item)
+            continue
+
+        key = config_item.get("key")
+        value = config_item.get("value")
+        override = config_item.get("override", True)
+
+        if not key:
+            logger.warning("Config item missing 'key': %s", config_item)
+            continue
+
+        # Try to convert value to appropriate type
+        if validate_and_set_config_value(config, key, value, override=override):
+            logger.info("Applied remote config: %s=%s", key, value)
+            applied_count += 1
+        else:
+            logger.warning(
+                "Failed to apply remote config %s=%s. Using default value.",
+                key,
+                value,
+            )
+
+    logger.info("Applied %d remote configuration items", applied_count)
+    return config
diff --git a/lmcache/v1/distributed/api.py b/lmcache/v1/distributed/api.py
new file mode 100644
index 0000000..f1952c8
--- /dev/null
+++ b/lmcache/v1/distributed/api.py
@@ -0,0 +1,404 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Defines the data structures that will be used by the
+distributed storage manager public functions
+
+Could be implemented by native code in the future
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+import enum
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+logger = init_logger(__name__)
+
+
+class TrimPolicy(enum.Enum):
+    """How to pick the retained subset of found keys for a prefetch.
+
+    PREFIX retains the longest contiguous run from index 0; SEGMENTED_PREFIX
+    keeps the keys that loaded when an L2 hit failed to load into L1 mid-prefix
+    (gaps and all); SPARSE retains every found key for an intentional scatter.
+    """
+
+    PREFIX = enum.auto()
+    SEGMENTED_PREFIX = enum.auto()
+    SPARSE = enum.auto()
+
+
+class PrefetchMode(enum.Enum):
+    """The intent of a prefetch request.
+
+    ``LOOKUP`` -- prefetch for an imminent reader: loaded keys are pinned for
+    the requesting workers, and whether they persist or are dropped after use
+    follows the configured prefetch policy.
+
+    ``WARM`` -- speculative pre-warm with no imminent reader: loaded keys are
+    retained and left unpinned (immediately resident and evictable), so a later
+    lookup can hit them.
+    """
+
+    LOOKUP = enum.auto()
+    WARM = enum.auto()
+
+
+@dataclass(frozen=True)
+class ObjectKey:
+    """
+    The unique identifier for an object in the distributed storage manager
+    """
+
+    chunk_hash: bytes
+    """ Content hash of this particular chunk """
+
+    model_name: str
+    """ Name of the model this chunk belongs to.
+
+    Invariant: must not contain ``@``. The L2 adapters use ``@`` as the
+    field separator in serialized keys/filenames and rely on this
+    invariant for unambiguous parsing. HuggingFace model IDs use
+    alphanumerics + ``/-_.`` so this rejects nothing that appears in
+    practice.
+    """
+
+    kv_rank: int
+    """ The rank that uniquely identifies the slice of the KV cache """
+
+    object_group_id: int = 0
+    """ Index of the object group this chunk belongs to. """
+
+    cache_salt: str = ""
+    """ Per-user isolation salt. Same content from different users with
+    different cache_salt values produces different ObjectKeys, giving
+    strict per-user cache isolation. Defaults to empty string, in which
+    case serialized keys and filenames match the pre-cache_salt shape
+    (no trailing salt field) — no migration is needed for un-salted
+    deployments.
+
+    Invariant: must not contain ``@``, ``/``, ``\\``, or NUL. The L2
+    adapters use ``@`` as the field separator; ``/`` and ``\\`` are
+    filesystem path separators (FS adapter embeds the salt into
+    filenames); NUL terminates C strings (C++ connector). Max length
+    128 to stay well within ``NAME_MAX`` (255) after the model, rank,
+    hash, and extension are added.
+    """
+
+    _SALT_FORBIDDEN_CHARS = frozenset("@/\\\x00")
+    _SALT_MAX_LEN = 128
+
+    def __post_init__(self) -> None:
+        if "@" in self.model_name:
+            raise ValueError(
+                f"model_name must not contain '@' (got {self.model_name!r})"
+            )
+        if self.object_group_id < 0:
+            raise ValueError(
+                f"object_group_id must be >= 0 (got {self.object_group_id})"
+            )
+        bad = self._SALT_FORBIDDEN_CHARS & set(self.cache_salt)
+        if bad:
+            raise ValueError(
+                f"cache_salt must not contain {bad!r} (got {self.cache_salt!r})"
+            )
+        if len(self.cache_salt) > self._SALT_MAX_LEN:
+            raise ValueError(
+                f"cache_salt exceeds max length {self._SALT_MAX_LEN} "
+                f"(got {len(self.cache_salt)})"
+            )
+
+    def to_encoded_object_key(self) -> "EncodedObjectKey":
+        """Return the JSON-safe :class:`EncodedObjectKey` projection."""
+        return EncodedObjectKey(
+            chunk_hash_hex=self.chunk_hash.hex(),
+            model_name=self.model_name,
+            kv_rank=self.kv_rank,
+            object_group_id=self.object_group_id,
+            cache_salt=self.cache_salt,
+        )
+
+    @staticmethod
+    def IntHash2Bytes(chunk_hash: int) -> bytes:
+        # NOTE: this is only used by tests
+        return chunk_hash.to_bytes(4, byteorder="big")
+
+    @staticmethod
+    def Bytes2IntHash(chunk_hash: bytes) -> int:
+        # NOTE: this is only used by tests
+        return int.from_bytes(chunk_hash, byteorder="big") & ((1 << 64) - 1)
+
+    @staticmethod
+    def ComputeKVRank(
+        world_size: int,
+        global_rank: int,
+        local_world_size: int,
+        local_rank: int,
+    ) -> int:
+        """
+        Compute the kv_rank from world_size and worker_id
+
+        Args:
+            world_size (int): The total number of workers (include TP + PP)
+            global_rank (int): The global worker id (from 0 to world_size - 1)
+            local_world_size (int): The local world size (for local node),
+                should NOT be greater than 8
+            local_rank (int): The local world rank (for local node)
+
+        Returns:
+            The special KV rank (bitmap) used by the objectkey
+
+        Example:
+            In the case of TP=4, PP=2, the TP worker 1 on node 1 has:
+            - world_size = 8
+            - global_rank = 5
+            - local_world_size = 4
+            - local_rank = 1
+
+            The output KV rank is the bitmap:
+            +--head--+
+            |00000000|
+            |00000000|
+            |00000000|
+            |00000000| layers
+            |00001100|
+            |00001100|
+            |00001100|
+            |00001100|
+            +--------+
+        """
+        # TODO(ApostaC): in the long run, we want to have the above bitmap based
+        # representation for asymmetric parallelism (e.g., sharing across different
+        # TP/PP settings).
+        # For now, let's have a simple implementation that just
+        # differentiate between different parallel setups
+
+        # For each number, we use 8-bit, and pack them together
+        return (
+            (world_size << 24)
+            | (global_rank << 16)
+            | (local_world_size << 8)
+            | local_rank
+        )
+
+
+@dataclass(frozen=True)
+class EncodedObjectKey:
+    """JSON-safe wire form of :class:`ObjectKey` — ``chunk_hash`` is
+    hex-encoded; other fields are preserved verbatim."""
+
+    chunk_hash_hex: str
+    """Hex-encoded ``ObjectKey.chunk_hash``."""
+
+    model_name: str
+    kv_rank: int
+
+    object_group_id: int = 0
+    """Defaults to ``0`` so pre-``object_group_id`` wire payloads still
+    deserialize."""
+
+    cache_salt: str = ""
+
+    def to_object_key(self) -> ObjectKey:
+        """Recover the corresponding :class:`ObjectKey`.
+
+        Raises:
+            ValueError: ``chunk_hash_hex`` is not valid hex, or one of
+                :class:`ObjectKey`'s field invariants is violated.
+        """
+        return ObjectKey(
+            chunk_hash=bytes.fromhex(self.chunk_hash_hex),
+            model_name=self.model_name,
+            kv_rank=self.kv_rank,
+            object_group_id=self.object_group_id,
+            cache_salt=self.cache_salt,
+        )
+
+
+@dataclass(frozen=True)
+class KeyEntry:
+    """One entry in a :class:`KeyListPage` including the encoded object
+    key and its object size."""
+
+    key: EncodedObjectKey
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class KeyListPage:
+    """A page of keys returned by ``L2AdapterInterface.list_l2_keys``."""
+
+    entries: tuple[KeyEntry, ...]
+    """The keys in the current page."""
+
+    next_page_token: str | None
+    """``None`` means this is the last page. Otherwise pass the token
+    verbatim to the next call to fetch the next page."""
+
+
+@dataclass(frozen=True)
+class MemoryLayoutDesc:
+    """
+    Describes the layout of a memory object
+    """
+
+    shapes: list[torch.Size]
+    dtypes: list[torch.dtype]
+
+    def __post_init__(self):
+        if len(self.shapes) != len(self.dtypes):
+            raise ValueError(
+                "MemoryLayoutDesc: shapes and dtype must have the same length"
+            )
+
+
+@dataclass(frozen=True)
+class AttnWindowDesc:
+    """Per-object-group cross-chunk attention windows, in LMCache chunks.
+
+    ``num_chunks_in_sw[g]`` is the number of trailing prefix chunks that must
+    be present for object group ``g`` to serve a cache hit. ``-1`` means full
+    attention (the whole prefix); ``w >= 1`` is a sliding window of ``w``
+    chunks (mamba is ``1``).
+    """
+
+    num_chunks_in_sw: list[int]
+
+    def __post_init__(self) -> None:
+        for w in self.num_chunks_in_sw:
+            if w == 0 or w < -1:
+                raise ValueError(
+                    "AttnWindowDesc: each window must be -1 (full attention) "
+                    f"or >= 1 chunk, got {w}"
+                )
+
+    @property
+    def num_object_groups(self) -> int:
+        """Number of object groups this descriptor covers."""
+        return len(self.num_chunks_in_sw)
+
+    def is_full_attention(self, object_group_idx: int) -> bool:
+        """Whether the object group depends on the entire prefix.
+
+        Args:
+            object_group_idx: 0-based object group index.
+
+        Returns:
+            True if the group attends to the whole prefix, False if it uses a
+            bounded sliding window.
+        """
+        return self.num_chunks_in_sw[object_group_idx] < 0
+
+
+DEFAULT_ATTN_WINDOW_DESC = AttnWindowDesc(num_chunks_in_sw=[-1])
+"""A single full-attention object group; the default when no per-object-group
+windows are supplied."""
+
+
+@dataclass(frozen=True)
+class PrefetchHandle:
+    """Opaque handle returned by ``StorageManager.submit_prefetch_task``.
+
+    Carries the bookkeeping needed to later query lookup / prefetch status
+    without exposing controller internals.
+    """
+
+    prefetch_request_id: int
+    """Opaque ID for tracking L2 prefetch in the controller.
+    -1 if no L2 request was submitted."""
+
+    external_request_id: str
+    """Request ID from the caller for end-to-end tracing."""
+
+    l1_found_indices: tuple[int, ...]
+    """Original-key indices found (read-locked) in L1 at submission time."""
+
+    total_requested_keys: int
+    """Total number of keys originally requested (the result-bitmap size)."""
+
+    submit_time: float
+    """Monotonic timestamp when the prefetch task was submitted."""
+
+    l2_orig_indices: tuple[int, ...] = ()
+    """Original-key index of each key submitted to L2; maps the controller's
+    local result bitmap back to original positions."""
+
+
+def ipc_key_to_object_keys(
+    ipc_key: "IPCCacheServerKey",
+    chunk_hashes: list[bytes],
+    object_group_ids: list[int],
+) -> list[list[ObjectKey]]:
+    """
+    Convert a single IPCCacheServerKey and its chunk hashes to per-object-group
+    lists of ObjectKey.
+
+    When the ipc_key's worker_id is None, each chunk hash is exploded into
+    multiple ObjectKeys (one per worker in world_size).
+
+    ``cache_salt`` is read directly from ``ipc_key`` so the produced
+    ObjectKeys are per-user isolated whenever the sender set a non-empty
+    salt. There is intentionally no separate ``cache_salt`` parameter —
+    duplicating the source of truth would risk silent isolation bugs
+    where a caller passes ``ipc_key`` but forgets the salt.
+
+    Args:
+        ipc_key: The IPC key providing model_name, world_size, worker_id,
+            and cache_salt.
+        chunk_hashes: List of chunk hash bytes, one per chunk.
+        object_group_ids: Object group ids to produce keys for.
+
+    Returns:
+        list[list[ObjectKey]]: The i-th element is the list of ObjectKeys
+        for ``object_group_ids[i]``.
+    """
+    cache_salt = ipc_key.cache_salt
+
+    # The (chunk_hash, kv_rank) expansion is independent of the object group,
+    # so compute it once and reuse it for every group.
+    if ipc_key.worker_id is None:
+        # For look up request, we want to expand to all workers
+        # TODO (ApostaC): include local world size/rank info
+        # in the future once it's in IPCCacheServerKey
+        kv_ranks = [
+            ObjectKey.ComputeKVRank(
+                world_size=ipc_key.world_size,
+                global_rank=worker_id,
+                local_world_size=ipc_key.world_size,
+                local_rank=worker_id,
+            )
+            for worker_id in range(ipc_key.world_size)
+        ]
+    else:
+        kv_ranks = [
+            ObjectKey.ComputeKVRank(
+                world_size=ipc_key.world_size,
+                global_rank=ipc_key.worker_id,
+                local_world_size=ipc_key.world_size,
+                local_rank=ipc_key.worker_id,
+            )
+        ]
+
+    return [
+        [
+            ObjectKey(
+                chunk_hash=chunk_hash,
+                model_name=ipc_key.model_name,
+                kv_rank=kv_rank,
+                object_group_id=object_group_id,
+                cache_salt=cache_salt,
+            )
+            for chunk_hash in chunk_hashes
+            for kv_rank in kv_ranks
+        ]
+        for object_group_id in object_group_ids
+    ]
diff --git a/lmcache/v1/distributed/bitmap_ops/README.md b/lmcache/v1/distributed/bitmap_ops/README.md
new file mode 120000
index 0000000..5a12fea
--- /dev/null
+++ b/lmcache/v1/distributed/bitmap_ops/README.md
@@ -0,0 +1 @@
+../../../../docs/design/v1/distributed/bitmap_ops/README.md
\ No newline at end of file
diff --git a/lmcache/v1/distributed/bitmap_ops/__init__.py b/lmcache/v1/distributed/bitmap_ops/__init__.py
new file mode 100644
index 0000000..cb739cd
--- /dev/null
+++ b/lmcache/v1/distributed/bitmap_ops/__init__.py
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Bitmap arithmetic for multi-object-group prefix-cache hit computation.
+
+See :mod:`~lmcache.v1.distributed.bitmap_ops.fold` and the
+package ``README.md`` for the fold -> highest-set-bit -> unfold design.
+"""
+
+# First Party
+from lmcache.v1.distributed.bitmap_ops.fold import (
+    FULL_ATTENTION_WINDOW,
+    fold,
+    fold_unfold,
+    fold_unfold_ranked,
+    highest_set_bit,
+    merge_bitmaps,
+    select_retained,
+    unfold,
+    unfold_range,
+)
+
+__all__ = [
+    "FULL_ATTENTION_WINDOW",
+    "highest_set_bit",
+    "fold",
+    "fold_unfold",
+    "fold_unfold_ranked",
+    "merge_bitmaps",
+    "select_retained",
+    "unfold",
+    "unfold_range",
+]
diff --git a/lmcache/v1/distributed/bitmap_ops/fold.py b/lmcache/v1/distributed/bitmap_ops/fold.py
new file mode 100644
index 0000000..e3ec736
--- /dev/null
+++ b/lmcache/v1/distributed/bitmap_ops/fold.py
@@ -0,0 +1,339 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Fold / unfold logic for multi-object-group prefix-cache hit computation.
+
+With hybrid models, an LMCache request is split across several *object groups*
+(full attention, sliding window, mamba, ...), each stored as its own
+``MemoryObj`` and each with a different token-dependency rule:
+
+- **full attention** needs every chunk of the prefix present to serve it;
+- a **sliding window of ``w`` chunks** only needs the last ``w`` chunks of the
+  prefix present (mamba is the ``w == 1`` case).
+
+A model-wide prefix-cache hit of length ``L`` requires *every* object group to
+be able to serve a prefix of length ``L`` under its own rule. This module turns
+the per-group presence bitmaps into that single answer in three steps:
+
+1. **fold** — combine the per-group presence into a servable bitmap: bit ``j``
+   is set iff every group can serve a length-``j + 1`` prefix;
+2. **highest-set-bit** — the model-wide hit length is the highest set bit plus
+   one (``-1`` -> 0, no hit);
+3. **unfold** — expand the hit length into the concrete chunks each group needs
+   (``unfold_range``), producing the retain mask used to load / lock / transfer.
+
+When every group is full attention the servable set is a downward-closed prefix,
+so the hit length equals the leading-ones count of the AND of the per-group
+presences -- i.e. the plain ``TrimPolicy.PREFIX`` / require-all intersection.
+Fold/unfold is a strict generalization of that behavior.
+
+Bitmaps here are laid out **group-major**: bit ``g * num_chunks + j`` is set iff
+chunk ``j`` is available for object group ``g``.
+"""
+
+# Standard
+from collections.abc import Iterable, Sequence
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.native_storage_ops import fold as _native_fold
+from lmcache.native_storage_ops import unfold as _native_unfold
+from lmcache.v1.distributed.api import TrimPolicy
+
+FULL_ATTENTION_WINDOW = -1
+"""Sentinel ``group_windows`` value marking a full-attention object group
+(needs the whole prefix). Any value ``<= 0`` is treated as full attention."""
+
+
+def unfold_range(prefix_len: int, window: int) -> tuple[int, int]:
+    """Chunk range ``[lo, hi)`` one object group needs to serve a prefix.
+
+    Full attention needs ``[0, prefix_len)``; a window of ``w`` chunks needs
+    ``[max(0, prefix_len - w), prefix_len)``.
+
+    Args:
+        prefix_len: model-wide hit length in chunks.
+        window: cross-chunk sliding-window size in chunks; ``<= 0`` means full
+            attention.
+
+    Returns:
+        The half-open chunk range this group must keep. ``(0, 0)`` when
+        ``prefix_len <= 0``.
+    """
+    if prefix_len <= 0:
+        return (0, 0)
+    lo = 0 if window <= 0 else max(0, prefix_len - window)
+    return (lo, prefix_len)
+
+
+def fold(
+    found: Bitmap,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> Bitmap:
+    """Fold per-(group, chunk, rank) presence into servable prefix lengths.
+
+    For each object group, computes which prefix lengths it can serve under its
+    rule (a length-``L`` prefix needs the last ``min(window, L)`` chunks
+    present), and intersects across groups. A chunk is present for a group only
+    when **every** kv_rank shard is present.
+
+    Args:
+        found: presence bitmap of length
+            ``len(group_windows) * num_chunks * num_ranks``; bit
+            ``g * (num_chunks * num_ranks) + j * num_ranks + r`` set iff chunk
+            ``j`` of object group ``g`` is present for kv_rank ``r``.
+        num_chunks: number of LMCache chunks in the request.
+        num_ranks: number of kv_rank shards per chunk (``world_size`` at lookup).
+        group_windows: per-object-group cross-chunk sliding-window size in
+            chunks, in object-group order; ``<= 0`` means full attention.
+
+    Returns:
+        A bitmap of size ``num_chunks``; bit ``j`` set iff every group can
+        serve a length-``j + 1`` prefix. Feed it to :func:`highest_set_bit`;
+        the model-wide hit length is that index plus one (``-1`` -> 0).
+
+    Raises:
+        ValueError: If ``group_windows`` is empty, ``num_chunks`` is negative,
+            or ``num_ranks`` is not positive.
+    """
+    if num_ranks < 1:
+        raise ValueError(f"num_ranks must be >= 1 (got {num_ranks})")
+    if not group_windows:
+        raise ValueError("group_windows must be non-empty")
+    if num_chunks < 0:
+        raise ValueError(f"num_chunks must be >= 0 (got {num_chunks})")
+
+    return _native_fold(found, num_chunks, num_ranks, list(group_windows))
+
+
+def highest_set_bit(servable: Bitmap) -> int:
+    """Model-wide prefix hit length: the highest set bit of a fold output.
+
+    Args:
+        servable: A servable-lengths bitmap from :func:`fold`.
+
+    Returns:
+        The highest set bit index. On :func:`fold`'s output this is the
+        model-wide hit length, always ``>= 0`` because :func:`fold` always sets
+        bit 0 (the empty prefix is servable by every group).
+
+    Raises:
+        ValueError: If ``servable`` has no set bit. This cannot occur on
+            :func:`fold`'s output, which always sets bit 0.
+    """
+    return servable.highest_set_bit()
+
+
+def unfold(
+    hit_length: int,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> Bitmap:
+    """Expand a model-wide hit length into the per-group retain mask.
+
+    Each group retains the chunks it needs to serve ``hit_length``:
+    ``[0, hit_length)`` for full attention, ``[hit_length - window, hit_length)``
+    for a sliding window, with **all** kv_ranks of each retained
+    ``(group, chunk)`` set.
+
+    Args:
+        hit_length: model-wide prefix hit length in chunks (clamped to
+            ``num_chunks``).
+        num_chunks: number of LMCache chunks in the request.
+        num_ranks: number of kv_rank shards per chunk.
+        group_windows: per-object-group cross-chunk sliding-window size in
+            chunks, in object-group order; ``<= 0`` means full attention.
+
+    Returns:
+        A retain mask over the same ranked layout as :func:`fold`'s input,
+        length ``len(group_windows) * num_chunks * num_ranks``.
+
+    Raises:
+        ValueError: If ``group_windows`` is empty, ``num_chunks`` is negative,
+            or ``num_ranks`` is not positive.
+    """
+    if num_ranks < 1:
+        raise ValueError(f"num_ranks must be >= 1 (got {num_ranks})")
+    if not group_windows:
+        raise ValueError("group_windows must be non-empty")
+    if num_chunks < 0:
+        raise ValueError(f"num_chunks must be >= 0 (got {num_chunks})")
+
+    return _native_unfold(hit_length, num_chunks, num_ranks, list(group_windows))
+
+
+def fold_unfold_ranked(
+    found: Bitmap,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> tuple[int, Bitmap]:
+    """Compose :func:`fold` -> :func:`highest_set_bit` -> :func:`unfold`.
+
+    Convenience for the full pipeline over the ``group x chunk x kv_rank``
+    lookup key layout: the model-wide hit length and the keys each group must
+    retain to serve it.
+
+    Args:
+        found: presence bitmap (see :func:`fold`).
+        num_chunks: number of LMCache chunks in the request.
+        num_ranks: number of kv_rank shards per chunk.
+        group_windows: per-object-group cross-chunk window sizes.
+
+    Returns:
+        ``(hit_length, retain_mask)`` over the same ranked layout as ``found``.
+    """
+    servable = fold(found, num_chunks, num_ranks, group_windows)
+    # fold's bits are chunk-indexed (bit j == prefix length j + 1), so the hit
+    # length is the highest set bit plus one; -1 (no servable prefix) -> 0.
+    hit_length = highest_set_bit(servable) + 1
+    return hit_length, unfold(hit_length, num_chunks, num_ranks, group_windows)
+
+
+def fold_unfold(
+    found: Bitmap,
+    num_chunks: int,
+    group_windows: Sequence[int],
+) -> tuple[int, Bitmap]:
+    """:func:`fold_unfold_ranked` for the single-rank (group-major) layout.
+
+    Args:
+        found: group-major presence bitmap of length
+            ``len(group_windows) * num_chunks``; bit ``g * num_chunks + j`` set
+            iff chunk ``j`` is available for object group ``g``.
+        num_chunks: number of LMCache chunks in the request.
+        group_windows: per-object-group cross-chunk window sizes.
+
+    Returns:
+        ``(hit_length, retain_mask)`` over the group-major layout.
+    """
+    return fold_unfold_ranked(found, num_chunks, 1, group_windows)
+
+
+def _fold_python(
+    found: Bitmap,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> Bitmap:
+    """Reference (pure-Python) implementation of :func:`fold`, for testing only.
+
+    Kept as the oracle the native :func:`fold` is validated against in the test
+    suite; it is not used at runtime. Behavior matches :func:`fold`.
+
+    Args:
+        found: Group-major / chunk-major / rank-minor presence bitmap.
+        num_chunks: Number of LMCache chunks in the request.
+        num_ranks: Number of kv_rank shards per chunk.
+        group_windows: Per-object-group cross-chunk window size in chunks;
+            ``<= 0`` means full attention.
+
+    Returns:
+        A bitmap of size ``num_chunks``; bit ``j`` set iff every group can
+        serve a length-``j + 1`` prefix.
+    """
+    group_stride = num_chunks * num_ranks
+
+    # For each group, ``run`` is the count of consecutive present chunks ending
+    # at the current chunk, so a length-L prefix is servable iff the last
+    # ``min(window, L)`` chunks are present. ``servable[j]`` (bit ``j``, prefix
+    # length ``j + 1``) stays True only if every group can serve that length.
+    servable = [True] * num_chunks
+    for group_idx, window in enumerate(group_windows):
+        gbase = group_idx * group_stride
+        effective_window = num_chunks if window <= 0 else window
+        run = 0
+        for prefix_len in range(1, num_chunks + 1):
+            cbase = gbase + (prefix_len - 1) * num_ranks
+            present = all(found.test(cbase + r) for r in range(num_ranks))
+            run = run + 1 if present else 0
+            if servable[prefix_len - 1] and run < min(effective_window, prefix_len):
+                servable[prefix_len - 1] = False
+
+    servable_lengths = Bitmap(num_chunks)
+    for j in range(num_chunks):
+        if servable[j]:
+            servable_lengths.set(j)
+    return servable_lengths
+
+
+def _unfold_python(
+    hit_length: int,
+    num_chunks: int,
+    num_ranks: int,
+    group_windows: Sequence[int],
+) -> Bitmap:
+    """Reference (pure-Python) implementation of :func:`unfold`, for testing only.
+
+    Kept as the oracle the native :func:`unfold` is validated against in the
+    test suite; it is not used at runtime. Behavior matches :func:`unfold`.
+
+    Args:
+        hit_length: Model-wide prefix hit length in chunks (clamped to
+            ``num_chunks``).
+        num_chunks: Number of LMCache chunks in the request.
+        num_ranks: Number of kv_rank shards per chunk.
+        group_windows: Per-object-group cross-chunk window size in chunks;
+            ``<= 0`` means full attention.
+
+    Returns:
+        Retain mask of length ``len(group_windows) * num_chunks * num_ranks``.
+    """
+    hit_length = min(hit_length, num_chunks)
+    num_groups = len(group_windows)
+    group_stride = num_chunks * num_ranks
+    retain_mask = Bitmap(num_groups * group_stride)
+    if hit_length <= 0:
+        return retain_mask
+    for group_idx, window in enumerate(group_windows):
+        lo, hi = unfold_range(hit_length, window)
+        gbase = group_idx * group_stride
+        for j in range(lo, hi):
+            cbase = gbase + j * num_ranks
+            for r in range(num_ranks):
+                retain_mask.set(cbase + r)
+    return retain_mask
+
+
+def merge_bitmaps(bitmaps: Iterable[Bitmap], num_keys: int) -> Bitmap:
+    """Merge bitmaps with a bitwise OR into a ``num_keys``-sized bitmap.
+
+    Always returns a ``num_keys``-sized bitmap (empty input -> all zeros), so
+    downstream ``&`` operations never hit a size mismatch.
+
+    Args:
+        bitmaps: Per-source presence bitmaps to union.
+        num_keys: Size of the merged bitmap.
+
+    Returns:
+        The bitwise-OR of all inputs as a ``num_keys``-sized bitmap.
+    """
+    merged = Bitmap(num_keys)
+    for bm in bitmaps:
+        merged = merged | bm
+    return merged
+
+
+def select_retained(
+    found: Bitmap,
+    num_keys: int,
+    policy: TrimPolicy = TrimPolicy.PREFIX,
+) -> Bitmap:
+    """Select the retained subset of ``found`` for the non-windowed selections.
+
+    ``PREFIX`` (LONGEST) keeps the leading contiguous run and drops everything
+    from the first gap on; any other policy keeps every set bit, gaps included.
+    The windowed hybrid fold is handled by :func:`fold_unfold_ranked`, not here.
+
+    Args:
+        found: Bitmap of found keys, over key indices ``0..num_keys-1``.
+        num_keys: Total number of requested keys.
+        policy: Selection to apply (see :class:`TrimPolicy`).
+
+    Returns:
+        Bitmap of the retained key indices.
+    """
+    if policy is TrimPolicy.PREFIX:
+        return Bitmap(num_keys, found.count_leading_ones())
+    return found
diff --git a/lmcache/v1/distributed/config.py b/lmcache/v1/distributed/config.py
new file mode 100644
index 0000000..ee3f8f2
--- /dev/null
+++ b/lmcache/v1/distributed/config.py
@@ -0,0 +1,622 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Configuration for distributed storage manager
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+import argparse
+import os
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    L2AdaptersConfig,
+    add_l2_adapters_args,
+    get_type_name_for_config,
+    parse_args_to_l2_adapters_config,
+)
+from lmcache.v1.platform import current_device_spec
+
+logger = init_logger(__name__)
+
+
+_HYBRID_L1_SINGLE_REGION_L2_ADAPTERS = {
+    "nixl_store",
+    "nixl_store_dynamic",
+}
+
+
+def _requires_single_l1_memory_region(
+    adapter_config: L2AdapterConfigBase,
+) -> str | None:
+    type_name = get_type_name_for_config(adapter_config)
+    if type_name in _HYBRID_L1_SINGLE_REGION_L2_ADAPTERS:
+        return type_name
+    if (
+        type_name == "mooncake_store"
+        and getattr(adapter_config, "setup_config", {}).get("protocol") == "rdma"
+    ):
+        return type_name
+    return None
+
+
+def _infer_l1_devdax_overflow_from_dax_adapter(
+    memory_config: "L1MemoryManagerConfig",
+    l2_adapter_config: L2AdaptersConfig,
+) -> None:
+    if not memory_config.devdax_path or memory_config.devdax_size_in_bytes:
+        return
+
+    l1_devdax_path = memory_config.devdax_path
+    remaining_adapters: list[L2AdapterConfigBase] = []
+    matched_dax_device: Any | None = None
+    for adapter_config in l2_adapter_config.adapters:
+        if get_type_name_for_config(adapter_config) != "dax":
+            remaining_adapters.append(adapter_config)
+            continue
+
+        dax_adapter = cast(Any, adapter_config)
+        devices = list(getattr(dax_adapter, "devices", []))
+        matched_devices = [
+            device
+            for device in devices
+            if getattr(device, "device_path", None) == l1_devdax_path
+        ]
+        if not matched_devices:
+            remaining_adapters.append(adapter_config)
+            continue
+        if matched_dax_device is not None or len(matched_devices) > 1:
+            raise ValueError(
+                "Only one DAX device can match l1-devdax-path for hybrid L1"
+            )
+
+        matched_dax_device = matched_devices[0]
+        remaining_devices = [
+            device
+            for device in devices
+            if getattr(device, "device_path", None) != l1_devdax_path
+        ]
+        if remaining_devices:
+            remaining_dax_adapter = type(dax_adapter)(
+                devices=remaining_devices,
+                hotplug_enabled=dax_adapter.hotplug_enabled,
+                slot_bytes=dax_adapter.slot_bytes,
+                num_store_workers=dax_adapter.num_store_workers,
+                num_lookup_workers=dax_adapter.num_lookup_workers,
+                num_load_workers=dax_adapter.num_load_workers,
+            )
+            remaining_dax_adapter.eviction_config = dax_adapter.eviction_config
+            remaining_dax_adapter.persist_config = dax_adapter.persist_config
+            remaining_dax_adapter.serde_config = dax_adapter.serde_config
+            remaining_adapters.append(remaining_dax_adapter)
+
+    if matched_dax_device is None:
+        return
+    max_dax_size_gb = matched_dax_device.max_dax_size_gb
+    memory_config.devdax_size_in_bytes = int(max_dax_size_gb * (1 << 30))
+    l2_adapter_config.adapters = remaining_adapters
+
+
+@dataclass
+class L1MemoryManagerConfig:
+    """
+    The configuration for L1 memory manager.
+    """
+
+    size_in_bytes: int
+    """ The size of L1 memory in bytes. """
+
+    use_lazy: bool
+    """ Whether to use lazy initialization for L1 memory. """
+
+    init_size_in_bytes: int = field(default=20 << 30)
+    """ The initial size when using lazy allocation. Default is 20GB. """
+
+    align_bytes: int = field(default=0x1000)
+    """ The alignment size in bytes. Default is 4KB. """
+
+    shm_name: str = field(default_factory=lambda: f"lmcache_l1_pool_{os.getpid()}")
+    """ POSIX shared-memory segment name for L1 pool. Empty disables SHM. """
+
+    devdax_path: str | None = None
+    """ Optional Device-DAX path to use as the L1 backing arena. """
+
+    devdax_size_in_bytes: int = 0
+    """ Optional Device-DAX overflow size for hybrid DRAM + DAX L1. """
+
+    def __post_init__(self):
+        self.init_size_in_bytes = min(self.init_size_in_bytes, self.size_in_bytes)
+
+        if self.devdax_path is not None:
+            self.devdax_path = self.devdax_path.strip()
+
+        if self.devdax_size_in_bytes < 0:
+            raise ValueError("devdax_size_in_bytes must be >= 0")
+        if self.devdax_size_in_bytes and not self.devdax_path:
+            raise ValueError("devdax_size_in_bytes requires devdax_path")
+
+        if self.devdax_path and self.use_lazy:
+            raise ValueError(
+                "l1-devdax-path requires lazy allocation to be disabled. "
+                "Please set --no-l1-use-lazy."
+            )
+        if self.devdax_path and self.shm_name:
+            raise ValueError(
+                'l1-devdax-path requires SHM to be disabled. Please set --shm-name "".'
+            )
+
+        # LazyMemoryAllocator requires pinned memory support.
+        # Auto-disable on platforms that don't support it to avoid a RuntimeError.
+        if self.use_lazy and not current_device_spec.is_pin_supported:
+            logger.warning(
+                "LazyMemoryAllocator requires memory pinning which is not "
+                "supported on the current backend. Disabling l1-use-lazy."
+            )
+            self.use_lazy = False
+
+
+@dataclass
+class GdsL1Config:
+    """Configuration for the GDS slab-file L1 tier.
+
+    When present on :class:`L1ManagerConfig`, the L1 medium becomes an NVMe
+    slab file accessed via GPUDirect Storage DMA (cuFile on NVIDIA, hipFile on
+    AMD ROCm) instead of pinned DRAM (mutually exclusive with the pinned-DRAM
+    tier in ``memory_config``). Carries the slab location, capacity, and DMA
+    mode.
+    """
+
+    file_location: str
+    """Directory for the slab file (one shared slab per process, used by all
+    GPU instances)."""
+
+    size_in_bytes: int
+    """Slab capacity in bytes (from ``--l1-size-gb``). Sizes both the
+    preallocated slab file and the GDS tier's address space."""
+
+    use_direct_io: bool = True
+    """Open the slab with ``O_DIRECT`` (required for the GDS DMA fast path)."""
+
+    align_bytes: int = 4096
+    """Allocation alignment; cuFile/hipFile and O_DIRECT require 4 KiB."""
+
+
+@dataclass
+class L1ManagerConfig:
+    """
+    Special config for the L1 Object/Key manager
+    """
+
+    memory_config: L1MemoryManagerConfig
+    """ The memory manager configuration for L1 cache. """
+
+    gds_l1_config: "GdsL1Config | None" = None
+    """ Optional GDS L1 tier. When set, the GDS slab is the L1 medium
+    (mutually exclusive with the pinned-DRAM tier in ``memory_config``). """
+
+    write_ttl_seconds: int = field(default=600)
+    """ Time to live for each object's write lock. Default is 600s (10 minutes). """
+
+    read_ttl_seconds: int = field(default=300)
+    """ Time to live for each object's read lock. Default is 300s (5 minutes). """
+
+
+@dataclass
+class EvictionConfig:
+    """
+    The configuration for eviction policies (L1 and optionally L2).
+    """
+
+    eviction_policy: Literal["LRU", "IsolatedLRU", "noop"]
+    """ The eviction policy to use. """
+
+    trigger_watermark: float = field(default=0.8)
+    """ The memory usage watermark to trigger eviction (0.0 to 1.0). """
+
+    eviction_ratio: float = field(default=0.2)
+    """ The fraction of *allocated* memory to evict when triggered (0.0 to 1.0). """
+
+
+@dataclass
+class StorageManagerConfig:
+    """
+    The configuration for the distributed storage manager.
+    """
+
+    l1_manager_config: L1ManagerConfig
+    """ The configuration for the L1 manager. """
+
+    eviction_config: EvictionConfig
+    """ The configuration for eviction policies. """
+
+    l2_adapter_config: L2AdaptersConfig = field(
+        default_factory=lambda: L2AdaptersConfig([])
+    )
+    """ The configuration for L2 adapters. """
+
+    store_policy: str = "default"
+    """ The L2 store policy name. """
+
+    prefetch_policy: str = "default"
+    """ The L2 prefetch policy name. """
+
+    prefetch_max_in_flight: int = 8
+    """ Maximum number of concurrent prefetch requests. """
+
+    periodic_notifier_interval_ms: int = 5
+    """ Interval (ms) for the periodic event notifier heartbeat. """
+
+    def __post_init__(self) -> None:
+        normalize_storage_manager_config(self)
+        validate_storage_manager_config(self)
+
+
+def normalize_storage_manager_config(config: StorageManagerConfig) -> None:
+    """Normalize storage manager configuration.
+
+    This consumes a matching DAX adapter as hybrid L1 Device-DAX overflow
+    capacity.
+
+    Args:
+        config: Storage manager configuration to normalize in place.
+
+    Returns:
+        None.
+
+    Raises:
+        ValueError: If more than one DAX device matches ``l1-devdax-path``.
+    """
+    memory_config = config.l1_manager_config.memory_config
+    _infer_l1_devdax_overflow_from_dax_adapter(memory_config, config.l2_adapter_config)
+
+
+def validate_storage_manager_config(config: StorageManagerConfig) -> None:
+    """Validate storage manager configuration.
+
+    This rejects L2 adapters that require a single contiguous L1 memory
+    descriptor when hybrid L1 Device-DAX overflow is enabled.
+
+    Args:
+        config: Storage manager configuration to validate.
+
+    Returns:
+        None.
+
+    Raises:
+        ValueError: If mutually exclusive L1 tiers are both configured, or
+            hybrid L1 is paired with incompatible L2 adapters.
+    """
+    if (
+        config.l1_manager_config.gds_l1_config is not None
+        and config.l1_manager_config.memory_config.devdax_path
+    ):
+        raise ValueError("gds-l1-path cannot be used with l1-devdax-path")
+
+    memory_config = config.l1_manager_config.memory_config
+    if not (memory_config.devdax_path and memory_config.devdax_size_in_bytes):
+        return
+
+    incompatible_adapters = [
+        adapter_name
+        for adapter_config in config.l2_adapter_config.adapters
+        if (adapter_name := _requires_single_l1_memory_region(adapter_config))
+        is not None
+    ]
+    if incompatible_adapters:
+        raise ValueError(
+            "Hybrid DRAM + Device-DAX L1 cannot be used with L2 adapters "
+            "that register a single L1 memory region: "
+            f"{', '.join(incompatible_adapters)}"
+        )
+
+
+def l1_exposes_single_memory_region(config: StorageManagerConfig) -> bool:
+    """Whether L1 is a single memory region a transfer channel can register.
+
+    Args:
+        config: Storage manager configuration to inspect.
+
+    Returns:
+        ``True`` if L1 is a single registerable memory region, ``False`` for
+        GDS L1 or Device-DAX L1.
+    """
+    l1_config = config.l1_manager_config
+    if l1_config.gds_l1_config is not None:
+        return False
+    if l1_config.memory_config.devdax_path:
+        return False
+    return True
+
+
+def add_storage_manager_args(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    """
+    Add storage manager configuration arguments to an existing parser.
+
+    This function allows other modules to integrate storage manager arguments
+    into their own argument parsers. Arguments are organized into groups to
+    avoid naming conflicts with other modules.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        argparse.ArgumentParser: The same parser with storage manager
+            arguments added.
+
+    Example:
+        >>> # In another module that needs its own arguments
+        >>> parser = argparse.ArgumentParser(description="My Application")
+        >>> parser.add_argument("--my-arg", type=str)
+        >>> add_storage_manager_args(parser)
+        >>> args = parser.parse_args()
+        >>> config = parse_args_to_config(args)
+    """
+    # L1 Memory Manager Config
+    memory_group = parser.add_argument_group(
+        "L1 Memory Manager", "Configuration for L1 memory manager"
+    )
+    memory_group.add_argument(
+        "--l1-size-gb",
+        type=float,
+        required=True,
+        help="The size of L1 memory in GB.",
+    )
+    memory_group.add_argument(
+        "--l1-use-lazy",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Whether to use lazy loading for L1 memory. (Default is True)",
+    )
+    memory_group.add_argument(
+        "--l1-init-size-gb",
+        type=int,
+        default=20,
+        help="The initial size (GB) when using lazy allocation. Default is 20.",
+    )
+    memory_group.add_argument(
+        "--l1-align-bytes",
+        type=int,
+        default=4096,
+        help="The alignment size in bytes. Default is 4KB (4096 bytes).",
+    )
+    memory_group.add_argument(
+        "--l1-devdax-path",
+        type=str,
+        default=None,
+        help=(
+            "Optional /dev/dax device or mmap-able file to use as the L1 "
+            "backing arena. When set, L1 lazy allocation and SHM transfer "
+            "advertising must be disabled because the L1 bytes live in the DAX "
+            'map. Set --no-l1-use-lazy and --shm-name "". '
+            "If a DAX L2 adapter with the same device_path is registered, "
+            "that adapter's max_dax_size_gb is used as L1 overflow size."
+        ),
+    )
+
+    # GDS L1 tier (optional, opt-in via --gds-l1-path)
+    gds_group = parser.add_argument_group(
+        "GDS L1 tier",
+        "Configuration for the GDS slab-file L1 tier. Setting --gds-l1-path "
+        "makes the L1 medium an NVMe slab accessed via GPUDirect Storage DMA "
+        "(cuFile on NVIDIA, hipFile on AMD ROCm) instead of pinned DRAM; "
+        "--l1-size-gb then sizes the slab. Disable byte-array L2 adapters when "
+        "this is on.",
+    )
+    gds_group.add_argument(
+        "--gds-l1-path",
+        type=str,
+        default=None,
+        help="NVMe directory path for the GDS L1 slab. Setting this enables GDS L1.",
+    )
+    gds_group.add_argument(
+        "--gds-l1-use-direct-io",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Open the slab file with O_DIRECT (required for the GDS DMA fast "
+        "path on ext4). Default True.",
+    )
+    # L1 Manager Config (TTL settings)
+    ttl_group = parser.add_argument_group(
+        "L1 Manager TTL", "TTL configuration for L1 manager locks"
+    )
+    ttl_group.add_argument(
+        "--l1-write-ttl-seconds",
+        type=int,
+        default=600,
+        help="Time to live for each object's write lock. Default is 600s.",
+    )
+    ttl_group.add_argument(
+        "--l1-read-ttl-seconds",
+        type=int,
+        default=300,
+        help="Time to live for each object's read lock. Default is 300s.",
+    )
+
+    # Eviction Config
+    eviction_group = parser.add_argument_group(
+        "Eviction Policy", "Configuration for eviction policies"
+    )
+    eviction_group.add_argument(
+        "--eviction-policy",
+        type=str,
+        choices=["LRU", "IsolatedLRU", "noop"],
+        required=True,
+        help="The eviction policy to use ('LRU', 'IsolatedLRU', or 'noop'). "
+        "'IsolatedLRU' maintains one LRU list per cache_salt and requires "
+        "quotas keyed by cache_salt to be configured via the HTTP API.",
+    )
+    eviction_group.add_argument(
+        "--eviction-trigger-watermark",
+        type=float,
+        default=0.8,
+        help="The memory usage watermark to trigger eviction (0.0 to 1.0). "
+        "Default is 0.8.",
+    )
+    eviction_group.add_argument(
+        "--eviction-ratio",
+        type=float,
+        default=0.2,
+        help="The fraction of memory to evict when triggered (0.0 to 1.0). "
+        "Default is 0.2.",
+    )
+
+    # L2 Policies
+    # Import here to break circular dependency:
+    # config.py <-> storage_controllers (via eviction_controller)
+    # Safe because config.py is fully initialized by the time this
+    # function is called.
+    # First Party
+    from lmcache.v1.distributed.storage_controllers.prefetch_policy import (
+        get_registered_prefetch_policies,
+    )
+    from lmcache.v1.distributed.storage_controllers.store_policy import (
+        get_registered_store_policies,
+    )
+    import lmcache.v1.distributed.storage_controllers  # noqa: F401
+
+    policy_group = parser.add_argument_group(
+        "L2 Policies", "Store and prefetch policy selection for L2 adapters"
+    )
+    policy_group.add_argument(
+        "--l2-store-policy",
+        type=str,
+        choices=get_registered_store_policies(),
+        default="default",
+        help="L2 store policy. Determines which adapters receive each key "
+        "and whether keys are deleted from L1 after L2 store. "
+        "Default is 'default' (store all keys to all adapters, keep L1).",
+    )
+    policy_group.add_argument(
+        "--l2-prefetch-policy",
+        type=str,
+        choices=get_registered_prefetch_policies(),
+        default="default",
+        help="L2 prefetch policy. Determines which adapter loads each key "
+        "when multiple adapters have it. "
+        "Default is 'default' (pick the first adapter by index).",
+    )
+    policy_group.add_argument(
+        "--l2-prefetch-max-in-flight",
+        type=int,
+        default=8,
+        help="Maximum number of concurrent prefetch requests. Default is 8.",
+    )
+    policy_group.add_argument(
+        "--periodic-notifier-interval-ms",
+        type=int,
+        default=5,
+        help="Interval in ms for the periodic event notifier heartbeat. Default is 5.",
+    )
+
+    # Adapter config
+    add_l2_adapters_args(parser)
+    return parser
+
+
+def get_arg_parser() -> argparse.ArgumentParser:
+    """
+    Get a standalone argument parser for storage manager configuration.
+
+    This creates a new parser with only storage manager arguments.
+    For integrating with other modules' parsers, use add_storage_manager_args()
+    instead.
+
+    Returns:
+        argparse.ArgumentParser: The argument parser with all storage manager
+            configuration options.
+    """
+    parser = argparse.ArgumentParser(
+        description="Distributed Storage Manager Configuration"
+    )
+    return add_storage_manager_args(parser)
+
+
+def parse_args_to_config(
+    args: argparse.Namespace,
+) -> StorageManagerConfig:
+    """
+    Convert parsed command line arguments to a StorageManagerConfig.
+
+    Args:
+        args: Parsed arguments from the argument parser.
+
+    Returns:
+        StorageManagerConfig: The configuration object.
+    """
+    shm_name = getattr(args, "shm_name", None)
+    if shm_name is None:
+        memory_config = L1MemoryManagerConfig(
+            size_in_bytes=int(args.l1_size_gb * (1 << 30)),
+            use_lazy=args.l1_use_lazy,
+            init_size_in_bytes=int(args.l1_init_size_gb * (1 << 30)),
+            align_bytes=args.l1_align_bytes,
+            devdax_path=args.l1_devdax_path,
+        )
+    else:
+        memory_config = L1MemoryManagerConfig(
+            size_in_bytes=int(args.l1_size_gb * (1 << 30)),
+            use_lazy=args.l1_use_lazy,
+            init_size_in_bytes=int(args.l1_init_size_gb * (1 << 30)),
+            align_bytes=args.l1_align_bytes,
+            shm_name=shm_name,
+            devdax_path=args.l1_devdax_path,
+        )
+
+    gds_l1_config: GdsL1Config | None = None
+    if getattr(args, "gds_l1_path", None):
+        # --l1-size-gb is the single L1 size flag; under GDS it sizes the slab.
+        gds_l1_config = GdsL1Config(
+            file_location=args.gds_l1_path,
+            size_in_bytes=int(args.l1_size_gb * (1 << 30)),
+            use_direct_io=args.gds_l1_use_direct_io,
+        )
+
+    l1_manager_config = L1ManagerConfig(
+        memory_config=memory_config,
+        gds_l1_config=gds_l1_config,
+        write_ttl_seconds=args.l1_write_ttl_seconds,
+        read_ttl_seconds=args.l1_read_ttl_seconds,
+    )
+
+    eviction_config = EvictionConfig(
+        eviction_policy=args.eviction_policy,
+        trigger_watermark=args.eviction_trigger_watermark,
+        eviction_ratio=args.eviction_ratio,
+    )
+
+    l2_adapter_config = parse_args_to_l2_adapters_config(args)
+
+    config = StorageManagerConfig(
+        l1_manager_config=l1_manager_config,
+        eviction_config=eviction_config,
+        l2_adapter_config=l2_adapter_config,
+        store_policy=args.l2_store_policy,
+        prefetch_policy=args.l2_prefetch_policy,
+        prefetch_max_in_flight=args.l2_prefetch_max_in_flight,
+        periodic_notifier_interval_ms=args.periodic_notifier_interval_ms,
+    )
+    return config
+
+
+def parse_args(args: list[str] | None = None) -> StorageManagerConfig:
+    """
+    Parse command line arguments and return a StorageManagerConfig.
+
+    This is a convenience function that combines get_arg_parser() and
+    parse_args_to_config().
+
+    Args:
+        args: Optional list of arguments to parse. If None, uses sys.argv.
+
+    Returns:
+        StorageManagerConfig: The configuration object.
+    """
+    parser = get_arg_parser()
+    parsed_args = parser.parse_args(args)
+    return parse_args_to_config(parsed_args)
diff --git a/lmcache/v1/distributed/error.py b/lmcache/v1/distributed/error.py
new file mode 100644
index 0000000..7e9a488
--- /dev/null
+++ b/lmcache/v1/distributed/error.py
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Definition of errors for class APIs.
+"""
+
+# Standard
+import enum
+
+
+class L1Error(enum.Enum):
+    """Errors for L1Manager class APIs."""
+
+    SUCCESS = enum.auto()
+    """ Operation succeeded. """
+
+    KEY_NOT_EXIST = enum.auto()
+    """ The specified key does not exist. """
+
+    KEY_NOT_READABLE = enum.auto()
+    """ The specified key exists but cannot be read """
+
+    KEY_NOT_WRITABLE = enum.auto()
+    """ The specified key exists but cannot be written """
+
+    KEY_IN_WRONG_STATE = enum.auto()
+    """ The specified key is in the wrong state for the operation. """
+
+    KEY_IS_LOCKED = enum.auto()
+    """ The specified key is locked and cannot perform the operation. """
+
+    OUT_OF_MEMORY = enum.auto()
+    """ Not enough memory to complete the operation. """
+
+
+ErrorType = L1Error
+
+
+def strerror(error: ErrorType) -> str:
+    """Convert error code to human-readable string.
+
+    Args:
+        error (ErrorType): The error code.
+
+    Returns:
+        str: The human-readable string.
+    """
+    if isinstance(error, L1Error):
+        if error == L1Error.SUCCESS:
+            return "Operation succeeded."
+        elif error == L1Error.KEY_NOT_EXIST:
+            return "The specified key does not exist."
+        elif error == L1Error.KEY_NOT_READABLE:
+            return "The specified key exists but cannot be read."
+        elif error == L1Error.KEY_NOT_WRITABLE:
+            return "The specified key exists but cannot be written."
+        elif error == L1Error.KEY_IN_WRONG_STATE:
+            return "The specified key is in the wrong state for the operation."
+        elif error == L1Error.KEY_IS_LOCKED:
+            return "The specified key is locked and cannot perform the operation."
+        elif error == L1Error.OUT_OF_MEMORY:
+            return "Not enough memory to complete the operation."
+
+    return "Unknown error."
diff --git a/lmcache/v1/distributed/eviction.py b/lmcache/v1/distributed/eviction.py
new file mode 100644
index 0000000..0058367
--- /dev/null
+++ b/lmcache/v1/distributed/eviction.py
@@ -0,0 +1,192 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Eviction module to determine what to evict from L1 and L2 caches.
+"""
+
+# Standard
+from abc import abstractmethod
+from collections.abc import Callable
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.internal_api import (
+    EvictionAction,
+    EvictionDestination,
+    L1ManagerListener,
+    L2AdapterListener,
+)
+
+
+class EvictionPolicy:
+    """
+    Pure abstract base class for eviction policies.
+
+    Subclasses implement the LRU (or other) tracking logic via the
+    on_keys_* methods and expose eviction decisions via get_eviction_actions.
+    The binding to a specific cache tier (L1 or L2) is provided by
+    L1EvictionPolicy and L2EvictionPolicy respectively.
+    """
+
+    @property
+    def support_isolation(self) -> bool:
+        """Whether this policy supports isolation eviction (e.g., per user isolation).
+
+        When True, the eviction controller checks isolated usage (e.g., per user usage)
+        and passes ``cache_salt`` to ``get_eviction_actions()`` to scope
+        eviction to specific cache_salt. When False, the controller uses
+        aggregate usage only.
+
+        Default is False. Subclasses that support isolated eviction.
+        (e.g., ``IsolatedLRUEvictionPolicy``) should override to return True.
+        """
+        return False
+
+    @abstractmethod
+    def register_eviction_destination(self, destination: EvictionDestination):
+        """
+        Register an eviction destination for the eviction policy to use.
+
+        Args:
+            destination (EvictionDestination): The eviction destination to
+                register.
+        """
+        pass
+
+    @abstractmethod
+    def on_keys_created(self, keys: list[ObjectKey]):
+        """
+        Notify the eviction policy that new keys have been created.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been created.
+        """
+        pass
+
+    @abstractmethod
+    def on_keys_touched(self, keys: list[ObjectKey]):
+        """
+        Notify the eviction policy that keys have been accessed.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been accessed.
+        """
+        pass
+
+    @abstractmethod
+    def on_keys_removed(self, keys: list[ObjectKey]):
+        """
+        Notify the eviction policy that keys have been deleted.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been deleted.
+        """
+        pass
+
+    @abstractmethod
+    def get_eviction_actions(
+        self,
+        expected_ratio: float,
+        key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
+    ) -> list[EvictionAction]:
+        """
+        Get the eviction actions to evict objects from cache.
+
+        Args:
+            expected_ratio (float): A hint indicating approximately what
+                fraction of tracked keys should be evicted. Value should be
+                in range [0.0, 1.0]. For example, 0.1 means roughly 10% of
+                keys should be evicted. This is a hint and the policy may
+                return more or fewer keys.
+            key_eligible_filter: An optional callable that takes an ObjectKey
+                and returns True if the key is eligible for eviction. When
+                provided, keys for which the filter returns False will be
+                skipped. This is useful for skipping locked keys that
+                cannot be deleted.
+            cache_salt: When set, scope eviction to keys belonging to this
+                salt only (identified by ``ObjectKey.cache_salt``). When
+                None, evict globally across all salts. Only meaningful for
+                policies where ``support_isolation`` is True; other policies
+                ignore this parameter.
+
+        Returns:
+            list[EvictionAction]: The eviction actions to perform. Each
+                action contains the keys and one eviction destination.
+
+        Notes:
+            The eviction action may not be successfully executed, or it may
+            be executed asynchronously. Therefore, the eviction policy should
+            not assume that the objects are evicted immediately, but it should
+            use `on_keys_removed` to know when the objects are actually
+            deleted.
+        """
+        pass
+
+
+class L1EvictionPolicy(L1ManagerListener):
+    """
+    Bridges L1Manager lifecycle events to an EvictionPolicy instance.
+
+    The actual eviction policy is provided via the constructor, keeping
+    the policy logic decoupled from the listener interface.
+    """
+
+    def __init__(self, policy: EvictionPolicy):
+        self._policy = policy
+
+    @property
+    def policy(self) -> EvictionPolicy:
+        return self._policy
+
+    # L1ManagerListener implementations
+    def on_l1_keys_reserved_read(self, keys: list[ObjectKey]):
+        # No-op
+        pass
+
+    def on_l1_keys_read_finished(self, keys: list[ObjectKey]):
+        self._policy.on_keys_touched(keys)
+
+    def on_l1_keys_reserved_write(self, keys: list[ObjectKey]):
+        # No-op
+        pass
+
+    def on_l1_keys_write_finished(self, keys: list[ObjectKey]):
+        # TODO (ApostaC): we don't differentiate between the created keys and
+        # updated keys here. Probably need to fix that by introducing a new
+        # callback in L1ManagerListener or adding `mode` argument into
+        # on_keys_reserved_write.
+        self._policy.on_keys_created(keys)
+
+    def on_l1_keys_deleted_by_manager(self, keys: list[ObjectKey]):
+        self._policy.on_keys_removed(keys)
+
+    def on_l1_keys_finish_write_and_reserve_read(self, keys: list[ObjectKey]):
+        self._policy.on_keys_created(keys)
+
+    def on_l1_keys_accessed(self, keys: list[ObjectKey]):
+        self._policy.on_keys_touched(keys)
+
+
+class L2EvictionPolicy(L2AdapterListener):
+    """
+    Bridges L2Adapter lifecycle events to an EvictionPolicy instance.
+
+    The actual eviction policy is provided via the constructor, keeping
+    the policy logic decoupled from the listener interface.
+    """
+
+    def __init__(self, policy: EvictionPolicy):
+        self._policy = policy
+
+    @property
+    def policy(self) -> EvictionPolicy:
+        return self._policy
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        self._policy.on_keys_created(keys)
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        self._policy.on_keys_touched(keys)
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        self._policy.on_keys_removed(keys)
diff --git a/lmcache/v1/distributed/eviction_policy/__init__.py b/lmcache/v1/distributed/eviction_policy/__init__.py
new file mode 100644
index 0000000..6323c61
--- /dev/null
+++ b/lmcache/v1/distributed/eviction_policy/__init__.py
@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Eviction policies for L1 cache management
+"""
+
+# First Party
+from lmcache.v1.distributed.eviction_policy.factory import (
+    CreateEvictionPolicy,
+)
+from lmcache.v1.distributed.eviction_policy.isolated_lru import (
+    IsolatedLRUEvictionPolicy,
+)
+from lmcache.v1.distributed.eviction_policy.lru import (
+    LRUEvictionPolicy,
+)
+from lmcache.v1.distributed.eviction_policy.noop import (
+    NoOpEvictionPolicy,
+)
+
+__all__ = [
+    "LRUEvictionPolicy",
+    "NoOpEvictionPolicy",
+    "IsolatedLRUEvictionPolicy",
+    "CreateEvictionPolicy",
+]
diff --git a/lmcache/v1/distributed/eviction_policy/factory.py b/lmcache/v1/distributed/eviction_policy/factory.py
new file mode 100644
index 0000000..74e7858
--- /dev/null
+++ b/lmcache/v1/distributed/eviction_policy/factory.py
@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.distributed.config import EvictionConfig
+from lmcache.v1.distributed.eviction import EvictionPolicy
+from lmcache.v1.distributed.eviction_policy.isolated_lru import (
+    IsolatedLRUEvictionPolicy,
+)
+from lmcache.v1.distributed.eviction_policy.lru import LRUEvictionPolicy
+from lmcache.v1.distributed.eviction_policy.noop import NoOpEvictionPolicy
+
+
+def CreateEvictionPolicy(eviction_config: EvictionConfig) -> EvictionPolicy:
+    """
+    Factory method to create an eviction policy based on the provided configuration.
+
+    Args:
+        eviction_config (EvictionConfig): The configuration for the eviction policy.
+
+    Returns:
+        An instance of the specified eviction policy.
+    """
+    if eviction_config.eviction_policy == "LRU":
+        return LRUEvictionPolicy()
+    elif eviction_config.eviction_policy == "IsolatedLRU":
+        return IsolatedLRUEvictionPolicy()
+    elif eviction_config.eviction_policy == "noop":
+        return NoOpEvictionPolicy()
+    else:
+        raise ValueError(
+            f"Unsupported eviction policy: {eviction_config.eviction_policy}"
+        )
diff --git a/lmcache/v1/distributed/eviction_policy/isolated_lru.py b/lmcache/v1/distributed/eviction_policy/isolated_lru.py
new file mode 100644
index 0000000..95444cf
--- /dev/null
+++ b/lmcache/v1/distributed/eviction_policy/isolated_lru.py
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+IsolatedLRU (per-``cache_salt`` LRU) eviction policy.
+
+Unlike :class:`LRUEvictionPolicy` which maintains a single global LRU
+list, this policy keeps one LRU list per ``cache_salt`` and uses
+``support_isolation=True`` so the L2 eviction controller can scope
+eviction to a specific salt via the ``cache_salt`` argument to
+``get_eviction_actions``.
+
+Combined with :class:`QuotaManager`, this lets the controller evict
+only the over-quota ``cache_salt``'s keys while leaving other salts'
+cached data untouched.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import OrderedDict
+from collections.abc import Callable
+import threading
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.eviction import EvictionPolicy
+from lmcache.v1.distributed.internal_api import (
+    EvictionAction,
+    EvictionDestination,
+)
+
+
+class IsolatedLRUEvictionPolicy(EvictionPolicy):
+    """Per-``cache_salt`` LRU eviction policy.
+
+    Maintains one ``OrderedDict`` per ``cache_salt`` (keyed by
+    ``ObjectKey``). New and touched keys move to the end of their
+    bucket's ordering; least-recently-used keys stay at the front and
+    are evicted first.
+
+    Thread-safety: every public method holds a single lock so bucket
+    dicts cannot be mutated concurrently.
+    """
+
+    @property
+    def support_isolation(self) -> bool:
+        return True
+
+    def __init__(
+        self,
+        default_destination: EvictionDestination = EvictionDestination.DISCARD,
+    ):
+        self._lock = threading.Lock()
+        # cache_salt -> ordered {ObjectKey: None} (oldest first).
+        self._per_salt_order: dict[str, OrderedDict[ObjectKey, None]] = {}
+        # Registered destinations (first one wins if any are registered,
+        # matching LRUEvictionPolicy semantics).
+        self._destinations: list[EvictionDestination] = []
+        self._default_destination = default_destination
+
+    def register_eviction_destination(self, destination: EvictionDestination) -> None:
+        with self._lock:
+            if destination not in self._destinations:
+                self._destinations.append(destination)
+
+    def on_keys_created(self, keys: list[ObjectKey]) -> None:
+        if not keys:
+            return
+        with self._lock:
+            # Same prefix-match ordering rationale as ``LRUEvictionPolicy``:
+            # later keys in a request should be evicted first, so we
+            # insert in reverse to place the final key at the LRU head.
+            for key in reversed(keys):
+                order = self._per_salt_order.get(key.cache_salt)
+                if order is None:
+                    order = OrderedDict()
+                    self._per_salt_order[key.cache_salt] = order
+                if key in order:
+                    order.move_to_end(key)
+                else:
+                    order[key] = None
+
+    def on_keys_touched(self, keys: list[ObjectKey]) -> None:
+        if not keys:
+            return
+        with self._lock:
+            for key in reversed(keys):
+                order = self._per_salt_order.get(key.cache_salt)
+                if order is not None and key in order:
+                    order.move_to_end(key)
+
+    def on_keys_removed(self, keys: list[ObjectKey]) -> None:
+        if not keys:
+            return
+        with self._lock:
+            for key in keys:
+                order = self._per_salt_order.get(key.cache_salt)
+                if order is None:
+                    continue
+                order.pop(key, None)
+                if not order:
+                    # Drop the empty bucket so ``list``/iteration
+                    # snapshots stay compact.
+                    del self._per_salt_order[key.cache_salt]
+
+    def get_eviction_actions(
+        self,
+        expected_ratio: float,
+        key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
+    ) -> list[EvictionAction]:
+        """Select victims in LRU order, scoped to a single ``cache_salt``.
+
+        IsolatedLRU is "isolated only" by contract — callers must pass a
+        concrete ``cache_salt``. The base interface keeps ``cache_salt``
+        optional for compatibility with non-isolated policies; passing
+        ``None`` here raises ``ValueError`` rather than silently
+        falling back to a global pool.
+
+        Args:
+            expected_ratio: Fraction of the candidate pool to evict,
+                clamped to ``[0.0, 1.0]``. If the ratio rounds down to
+                zero and the pool is non-empty, at least one key is
+                returned (matches ``LRUEvictionPolicy``).
+            key_eligible_filter: Optional predicate — keys failing the
+                filter (e.g. locked) are skipped.
+            cache_salt: The salt whose bucket to evict from. Required.
+
+        Returns:
+            A list with at most one ``EvictionAction`` (one per
+            destination — IsolatedLRU has a single destination, so the
+            list is either empty or length 1). Empty when nothing is
+            available to evict under the current filter / ratio.
+
+        Raises:
+            ValueError: If ``cache_salt`` is ``None``.
+        """
+        if cache_salt is None:
+            raise ValueError(
+                "IsolatedLRUEvictionPolicy.get_eviction_actions requires "
+                "cache_salt; this policy is per-bucket and has no global "
+                "eviction path."
+            )
+        with self._lock:
+            order = self._per_salt_order.get(cache_salt)
+            pool = list(order.keys()) if order else []
+
+            if not pool:
+                return []
+
+            expected_ratio = max(0.0, min(1.0, expected_ratio))
+            target_count = int(len(pool) * expected_ratio)
+            if expected_ratio > 0 and target_count == 0:
+                target_count = 1
+            if target_count == 0:
+                return []
+
+            keys_to_evict: list[ObjectKey] = []
+            for key in pool:
+                if key_eligible_filter is not None and not key_eligible_filter(key):
+                    continue
+                keys_to_evict.append(key)
+                if len(keys_to_evict) >= target_count:
+                    break
+
+            if not keys_to_evict:
+                return []
+
+            destination = self._default_destination
+            if self._destinations:
+                destination = self._destinations[0]
+
+            return [EvictionAction(keys=keys_to_evict, destination=destination)]
+
+    # =========================================================================
+    # Methods below are NOT part of the EvictionPolicy interface.
+    # They are provided for testing and debugging purposes only.
+    # =========================================================================
+
+    def get_num_tracked_keys(self, cache_salt: str | None = None) -> int:
+        """Number of tracked keys, optionally scoped to one bucket."""
+        with self._lock:
+            if cache_salt is not None:
+                order = self._per_salt_order.get(cache_salt)
+                return len(order) if order is not None else 0
+            return sum(len(o) for o in self._per_salt_order.values())
+
+    def get_tracked_salts(self) -> list[str]:
+        """Return the set of cache_salts with at least one tracked key."""
+        with self._lock:
+            return list(self._per_salt_order.keys())
diff --git a/lmcache/v1/distributed/eviction_policy/lru.py b/lmcache/v1/distributed/eviction_policy/lru.py
new file mode 100644
index 0000000..5ac1e81
--- /dev/null
+++ b/lmcache/v1/distributed/eviction_policy/lru.py
@@ -0,0 +1,244 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LRU (Least Recently Used) eviction policy implementation
+"""
+
+# Standard
+from collections import OrderedDict
+from collections.abc import Callable
+import threading
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.eviction import EvictionPolicy
+from lmcache.v1.distributed.internal_api import (
+    EvictionAction,
+    EvictionDestination,
+)
+
+
+class LRUEvictionPolicy(EvictionPolicy):
+    """
+    LRU (Least Recently Used) eviction policy.
+
+    This policy tracks the order of key accesses and evicts the least recently
+    used keys first when eviction is needed.
+
+    Thread Safety:
+        This class is thread-safe. All operations are protected by a global lock
+        to ensure eventual consistency without corrupted states.
+
+    Attributes:
+        _lock: Threading lock for thread-safe operations
+        _order: OrderedDict maintaining LRU order (most recent at end)
+        _destinations: List of registered eviction destinations
+        _default_destination: The default destination for eviction actions
+    """
+
+    def __init__(
+        self,
+        default_destination: EvictionDestination = EvictionDestination.DISCARD,
+    ):
+        """
+        Initialize the LRU eviction policy.
+
+        Args:
+            default_destination: The default destination for evicted objects.
+                Defaults to DISCARD.
+        """
+        # Lock for thread-safe operations
+        self._lock = threading.Lock()
+
+        # OrderedDict to maintain LRU order - keys at the beginning are oldest
+        self._order: OrderedDict[ObjectKey, None] = OrderedDict()
+
+        # List of registered eviction destinations
+        self._destinations: list[EvictionDestination] = []
+
+        # Default destination for eviction
+        self._default_destination = default_destination
+
+    def register_eviction_destination(self, destination: EvictionDestination):
+        """
+        Register an eviction destination for the eviction policy to use.
+
+        Args:
+            destination (EvictionDestination): The eviction destination to register
+        """
+        with self._lock:
+            if destination not in self._destinations:
+                self._destinations.append(destination)
+
+    def on_keys_created(self, keys: list[ObjectKey]):
+        """
+        Notify the eviction policy that new keys have been created.
+        New keys are added as most recently used.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been created
+        """
+        if not keys:
+            return
+        with self._lock:
+            # NOTE: for the request, the later keys should be evicted first.
+            # For example, the request has (key1, key2, key3), if we first
+            # evict key1, due to prefix match, key2 and key3 will not be hit.
+            for key in reversed(keys):
+                # If key already exists, move it to the end (most recently used)
+                if key in self._order:
+                    self._order.move_to_end(key)
+                else:
+                    # Add new key at the end (most recently used)
+                    self._order[key] = None
+
+    def on_keys_touched(self, keys: list[ObjectKey]):
+        """
+        Notify the eviction policy that keys have been accessed.
+        Touched keys are moved to the most recently used position.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been accessed
+        """
+        if not keys:
+            return
+        with self._lock:
+            # NOTE: for the request, the later keys should be evicted first.
+            # The example is the same as `on_keys_created`.
+            for key in reversed(keys):
+                if key in self._order:
+                    # Move to end (most recently used)
+                    self._order.move_to_end(key)
+
+    def on_keys_removed(self, keys: list[ObjectKey]):
+        """
+        Notify the eviction policy that keys have been deleted.
+        Deleted keys are removed from tracking.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been deleted
+        """
+        if not keys:
+            return
+        with self._lock:
+            for key in keys:
+                # Remove from LRU order tracking
+                if key in self._order:
+                    del self._order[key]
+
+    def get_eviction_actions(
+        self,
+        expected_ratio: float,
+        key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
+    ) -> list[EvictionAction]:
+        """
+        Get the eviction actions to evict objects from L1 cache.
+        Returns keys in LRU order (least recently used first).
+
+        Args:
+            expected_ratio (float): A hint indicating approximately what fraction
+                of tracked keys should be evicted. Value should be in range [0.0, 1.0].
+                For example, 0.1 means roughly 10% of keys should be evicted.
+            key_eligible_filter: An optional callable that takes an ObjectKey
+                and returns True if the key is eligible for eviction. When
+                provided, keys for which the filter returns False will be
+                skipped. This is useful for skipping locked keys that
+                cannot be deleted.
+            cache_salt: Ignored by LRU policy (not user-level).
+
+        Returns:
+            list[EvictionAction]: The eviction actions to perform. Each
+                action contains the keys and one eviction destination.
+
+        Notes:
+            The eviction action may not be successfully executed, or it
+            may be executed asynchronously. Therefore, the eviction policy
+            should not assume that the objects are evicted immediately, but
+            it should use `on_keys_deleted` to know when the objects are actually
+            deleted.
+        """
+        with self._lock:
+            if not self._order:
+                return []
+
+            # Clamp expected_ratio to valid range
+            expected_ratio = max(0.0, min(1.0, expected_ratio))
+
+            # Calculate target number of keys to evict based on ratio
+            target_count = int(len(self._order) * expected_ratio)
+
+            # Ensure at least 1 key if ratio > 0 and we have keys
+            if expected_ratio > 0 and target_count == 0 and len(self._order) > 0:
+                target_count = 1
+
+            if target_count == 0:
+                return []
+
+            # Get keys in LRU order (from beginning - least recently used),
+            # skipping keys that fail the filter (e.g. locked keys).
+            keys_to_evict: list[ObjectKey] = []
+
+            for key in self._order:
+                if key_eligible_filter is not None and not key_eligible_filter(key):
+                    # Skip keys that are not eligible for eviction
+                    # (e.g. currently locked by read/write operations)
+                    continue
+                keys_to_evict.append(key)
+                if len(keys_to_evict) >= target_count:
+                    break
+
+            if not keys_to_evict:
+                return []
+
+            # Determine the destination
+            destination = self._default_destination
+            if self._destinations:
+                # Use the first registered destination if available
+                destination = self._destinations[0]
+
+            return [EvictionAction(keys=keys_to_evict, destination=destination)]
+
+    # =========================================================================
+    # Methods below are NOT part of the EvictionPolicy interface.
+    # They are provided for testing and debugging purposes only.
+    # =========================================================================
+
+    def get_num_tracked_keys(self) -> int:
+        """
+        Get the number of keys currently being tracked.
+
+        Note:
+            This method is NOT part of the EvictionPolicy interface.
+            It is provided for testing and debugging purposes only.
+
+        Returns:
+            int: The number of tracked keys
+        """
+        with self._lock:
+            return len(self._order)
+
+    def get_eviction_candidates(self, count: int) -> list[ObjectKey]:
+        """
+        Get a list of eviction candidates without creating eviction actions.
+        Useful for querying what would be evicted.
+
+        Note:
+            This method is NOT part of the EvictionPolicy interface.
+            It is provided for testing and debugging purposes only.
+
+        Args:
+            count: Maximum number of candidates to return
+
+        Returns:
+            list[ObjectKey]: List of keys that are candidates for eviction,
+                in LRU order (least recently used first)
+        """
+        with self._lock:
+            candidates: list[ObjectKey] = []
+
+            for key in self._order:
+                candidates.append(key)
+                if len(candidates) >= count:
+                    break
+
+            return candidates
diff --git a/lmcache/v1/distributed/eviction_policy/noop.py b/lmcache/v1/distributed/eviction_policy/noop.py
new file mode 100644
index 0000000..db14a1e
--- /dev/null
+++ b/lmcache/v1/distributed/eviction_policy/noop.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+No-op eviction policy for buffer-only mode.
+
+When L1 is used purely as a write buffer (data is deleted from L1
+immediately after being stored to L2 by the StoreController), there
+is no need for the eviction policy to track keys at all.
+"""
+
+# Standard
+from collections.abc import Callable
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.eviction import EvictionPolicy
+from lmcache.v1.distributed.internal_api import (
+    EvictionAction,
+    EvictionDestination,
+)
+
+
+class NoOpEvictionPolicy(EvictionPolicy):
+    """
+    Eviction policy that performs no tracking and never evicts.
+
+    Designed for buffer-only mode where the StoreController is
+    responsible for cleaning up L1 after successful L2 writes.
+    This avoids the overhead of maintaining an LRU OrderedDict
+    that would otherwise do pointless insert-then-remove cycles.
+    """
+
+    def register_eviction_destination(self, destination: EvictionDestination):
+        pass
+
+    def on_keys_created(self, keys: list[ObjectKey]):
+        pass
+
+    def on_keys_touched(self, keys: list[ObjectKey]):
+        pass
+
+    def on_keys_removed(self, keys: list[ObjectKey]):
+        pass
+
+    def get_eviction_actions(
+        self,
+        expected_ratio: float,
+        key_eligible_filter: Callable[[ObjectKey], bool] | None = None,
+        cache_salt: str | None = None,
+    ) -> list[EvictionAction]:
+        return []
diff --git a/lmcache/v1/distributed/internal_api.py b/lmcache/v1/distributed/internal_api.py
new file mode 100644
index 0000000..025274a
--- /dev/null
+++ b/lmcache/v1/distributed/internal_api.py
@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Class for distributed storage manager internal API data structures
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+import enum
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+
+
+@dataclass(frozen=True)
+class L1MemoryDesc:
+    """
+    Describes the L1 memory buffer registered with an external backend (e.g. Nixl).
+    """
+
+    ptr: int
+    size: int
+    align_bytes: int
+
+
+class EventListener(ABC):  # noqa: B024
+    pass
+
+
+# For L1 manager event notifications
+class L1ManagerListener(EventListener):
+    """
+    Listener for L1 manager events
+    """
+
+    @abstractmethod
+    def on_l1_keys_reserved_read(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that new keys have been reserved for read on L1.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been successfully reserved
+        """
+        pass
+
+    @abstractmethod
+    def on_l1_keys_read_finished(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been accessed on L1.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been successfully read
+        """
+        pass
+
+    @abstractmethod
+    def on_l1_keys_reserved_write(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been reserved for write on L1.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been successfully reserved
+        """
+        pass
+
+    @abstractmethod
+    def on_l1_keys_write_finished(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been finished for writing on L1.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been successfully written
+        """
+        pass
+
+    @abstractmethod
+    def on_l1_keys_finish_write_and_reserve_read(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been finished for writing
+        and reserved for read on L1.
+
+        This will only be trigger by the prefetch operation now.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been successfully
+                finished for writing and reserved for read
+        """
+        # NOTE (ApostaC): may consider renaming this to `on_l1_keys_finish_prefetch`
+        # for better clarity
+        pass
+
+    @abstractmethod
+    def on_l1_keys_deleted_by_manager(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been deleted from L1.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been deleted
+        """
+        pass
+
+    @abstractmethod
+    def on_l1_keys_accessed(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been accessed on L1.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been accessed
+        """
+        pass
+
+
+class L2AdapterListener(EventListener):
+    """Listener for L2 adapter events, analogous to L1ManagerListener."""
+
+    @abstractmethod
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        """
+        Notify the listener that keys have been successfully stored in L2.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been stored.
+            sizes (list[int]): The byte size of each stored key.
+        """
+        pass
+
+    @abstractmethod
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been accessed (lookup hit) in L2.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been accessed.
+        """
+        pass
+
+    @abstractmethod
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        """
+        Notify the listener that keys have been deleted from L2.
+
+        Args:
+            keys (list[ObjectKey]): The keys that have been deleted.
+        """
+        pass
+
+
+# For Eviction
+class EvictionDestination(enum.Enum):
+    """
+    The destination of evicted objects
+    """
+
+    DISCARD = enum.auto()
+    """Discard the evicted objects"""
+
+    L2_CACHE = enum.auto()
+    """Evict to L2 storage"""
+
+
+@dataclass(frozen=True)
+class EvictionAction:
+    """
+    An action to be taken for eviction
+    """
+
+    destination: EvictionDestination
+    """The destination of the evicted object"""
+
+    keys: list[ObjectKey] = field(default_factory=list)
+    """The key of the object to be evicted"""
+
+
+class L2StoreResult(int):
+    """Immutable result of a completed L2 store task.
+
+    Encodes both the success flag and bytes transferred in the int
+    value: ``>= 0`` means success (value = bytes transferred);
+    ``-1`` means failure.
+
+    Args:
+        success: Whether the store task succeeded.
+        bytes_transferred: Bytes actually written to L2. Must be >= 0.
+
+    Raises:
+        ValueError: If ``bytes_transferred`` is negative.
+    """
+
+    def __new__(cls, success: bool, bytes_transferred: int) -> "L2StoreResult":
+        if bytes_transferred < 0:
+            raise ValueError(f"bytes_transferred must be >= 0, got {bytes_transferred}")
+        return super().__new__(cls, bytes_transferred if success else -1)
+
+    def is_successful(self) -> bool:
+        """Return ``True`` when the store task succeeded."""
+        return int(self) >= 0
+
+    def bytes_transferred(self) -> int:
+        """Return the number of bytes actually written, or 0 on failure."""
+        value = int(self)
+        return value if value >= 0 else 0
+
+
+@dataclass(frozen=True)
+class QuotaEntry:
+    """Snapshot of a single quota registration."""
+
+    cache_salt: str
+    limit_bytes: int
diff --git a/lmcache/v1/distributed/l1_manager.py b/lmcache/v1/distributed/l1_manager.py
new file mode 100644
index 0000000..b8aefb3
--- /dev/null
+++ b/lmcache/v1/distributed/l1_manager.py
@@ -0,0 +1,894 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Managing objects and memory for L1 cache
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import Literal
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import TTLLock
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import L1ManagerConfig
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L1ManagerListener
+from lmcache.v1.distributed.memory_manager import (
+    GDSL1MemoryManager,
+    L1ManagerProtocol,
+    L1MemoryManager,
+)
+from lmcache.v1.distributed.memory_manager.devdax_l1_memory_manager import (
+    DevDaxL1MemoryManager,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+from lmcache.v1.mp_observability.otel_init import register_gauge
+
+logger = init_logger(__name__)
+
+
+# Internal classes and helper functions
+@dataclass
+class L1ObjectState:
+    """
+    The internal state of an object in L1 cache
+    """
+
+    memory_obj: MemoryObj
+    """ The memory object stored in L1 cache. """
+
+    write_lock: TTLLock
+    """ Whether the object is write-locked. """
+
+    read_lock: TTLLock
+    """ The read lock with TTL for the object. """
+
+    is_temporary: bool
+    """ Whether the object is temporary (need to be deleted after read). """
+
+    def available_for_read(self) -> bool:
+        """Check if the object is available for read.
+
+        Returns:
+            True if the object is not write-locked, False otherwise.
+        """
+        return not self.write_lock.is_locked()
+
+    def available_for_write(self) -> bool:
+        """Check if the object is available for write.
+
+        Returns:
+            True if the object is not write-locked and has no read locks
+            and is not a temporary object, False otherwise.
+        """
+
+        return (
+            not self.write_lock.is_locked()
+            and not self.read_lock.is_locked()
+            and not self.is_temporary
+        )
+
+
+def l1_mgr_synchronized(func):
+    """
+    Decorator to mark L1Manager methods as thread-safe
+    """
+
+    def wrapper(self: "L1Manager", *args, **kwargs):
+        with self._lock:
+            return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+L1OperationResult = tuple[L1Error, MemoryObj | None]
+
+# Upper bound for the count parameter in reserve_read / finish_read
+# to prevent a single call from holding the global lock for too long.
+MAX_READ_LOCK_COUNT = 128
+
+
+def _validate_extra_count(extra_count: int) -> int:
+    """Validate and clamp extra_count.
+
+    Args:
+        extra_count: Extra lock count on top of the
+            default 1 lock.
+
+    Returns:
+        Clamped value in [0, MAX_READ_LOCK_COUNT - 1].
+    """
+    if extra_count < 0:
+        logger.warning(
+            "L1Manager: extra_count=%d is invalid, clamping to 0",
+            extra_count,
+        )
+        return 0
+    upper = MAX_READ_LOCK_COUNT - 1
+    if extra_count > upper:
+        logger.warning(
+            "L1Manager: extra_count=%d exceeds limit=%d, clamping",
+            extra_count,
+            upper,
+        )
+        return upper
+    return extra_count
+
+
+def _l1_usage_ratio_or_zero(target: "L1Manager | None") -> float:
+    """Return ``target.get_memory_usage()`` as a 0.0-1.0 ratio.
+
+    Returns 0.0 when ``target`` is None or ``total_bytes`` is zero so the
+    observable-gauge callback never raises during scrape.
+    """
+    if target is None:
+        return 0.0
+    used, total = target.get_memory_usage()
+    if total <= 0:
+        return 0.0
+    return used / total
+
+
+# Main classes
+
+
+class L1Manager:
+    """
+    Object lifecycle state machine for L1 cache
+
+          +--------+
+          |  None  | <---------------------------------------+
+          +--------+                                         |
+            |   ^                                            |
+            |   | (write lock expired)                       | delete()
+            |   |                                            |
+    reserve |   +----------------------+                     |
+    write() |                          |                     |
+            v                          |                     |
+      +--------------+           +-----------+               |
+      | write_locked |           |           |---------------+
+      |              |---------->|   ready   |
+      |              | finish_   |           |---------------+
+      +--------------+ write()   +-----------+               |
+            ^                          |                     |
+            |                          | reserve_read()      | finish_read()
+            +--------------------------+                     | (if count becomes 0)
+                 reserve_write()       |                     |
+                                       v                     |
+                               +-----------------+           |
+                               |   read_locked   |-----------+
+                               |   (count = 1)   |
+                               +-----------------+
+                                     |     ^
+                      reserve_read() |     | finish_read()
+                                     v     |
+                               +-----------------+
+                               |   read_locked   |
+                               |   (count = 2)   |
+                               +-----------------+
+                                     |     ^
+                      reserve_read() |     | finish_read()
+                                     v     |
+                                   (...)  (...)
+                               (Higher Counts)
+
+    For every operation on list of keys, the operation is atomic
+    """
+
+    # Singleton dispatch for ``lmcache_mp.l1_memory_usage_bytes``: tests may
+    # construct multiple L1Managers but the OTel SDK only honors the first
+    # gauge registration, so the callback reads from the most recently built
+    # instance via ``_gauge_target``.
+    _gauge_registered: bool = False
+    _gauge_target: "L1Manager | None" = None
+
+    def __init__(self, config: L1ManagerConfig):
+        self._lock = threading.Lock()
+
+        self._objects: dict[ObjectKey, L1ObjectState] = {}
+
+        # GDS, Device-DAX, and CPU L1 are mutually exclusive tiers. Each tier
+        # owns its backing allocator instead of branching inside the CPU path.
+        self._memory_manager: L1ManagerProtocol
+        if config.gds_l1_config is not None:
+            self._memory_manager = GDSL1MemoryManager(config.gds_l1_config)
+            logger.info("L1Manager: GDS L1 tier enabled; CPU pinned-DRAM L1 disabled")
+        elif config.memory_config.devdax_path:
+            self._memory_manager = DevDaxL1MemoryManager(config.memory_config)
+            logger.info("L1Manager: Device-DAX L1 tier enabled; CPU-only L1 disabled")
+        else:
+            self._memory_manager = L1MemoryManager(config.memory_config)
+
+        self._write_ttl_seconds = config.write_ttl_seconds
+        self._read_ttl_seconds = config.read_ttl_seconds
+
+        self._registered_listeners: list[L1ManagerListener] = []
+
+        self._event_bus = get_event_bus()
+
+        L1Manager._gauge_target = self
+        if not L1Manager._gauge_registered:
+            L1Manager._gauge_registered = True
+            register_gauge(
+                "lmcache.l1_manager",
+                "lmcache_mp.l1_memory_usage_bytes",
+                "Bytes currently held in L1 cache",
+                lambda: (
+                    L1Manager._gauge_target.get_memory_usage()[0]
+                    if L1Manager._gauge_target is not None
+                    else 0
+                ),
+            )
+            register_gauge(
+                "lmcache.l1_manager",
+                "lmcache_mp.l1_usage_ratio",
+                "L1 used/total ratio (0.0–1.0)",
+                lambda: _l1_usage_ratio_or_zero(L1Manager._gauge_target),
+            )
+
+    def register_listener(self, listener: L1ManagerListener) -> None:
+        """Register a listener for L1Manager events.
+
+        Args:
+            listener: The listener to register.
+        """
+        with self._lock:
+            self._registered_listeners.append(listener)
+
+    @l1_mgr_synchronized
+    def reserve_read(
+        self,
+        keys: list[ObjectKey],
+        extra_count: int = 0,
+    ) -> dict[ObjectKey, L1OperationResult]:
+        """Reserve read access for the given keys.
+
+        Args:
+            keys: The list of object keys to reserve
+                read access for.
+            extra_count: Extra read locks on top of the
+                default 1 lock.  Total locks acquired per
+                key = 1 + extra_count.  Useful when multiple
+                workers each consume one read lock for the
+                same key (e.g. MLA models with TP > 1).
+
+        Returns:
+            A dictionary mapping each object key to a tuple
+            of (L1Error, Optional[MemoryObj]).
+
+        Errors:
+            KEY_NOT_EXIST: The key does not exist.
+            KEY_NOT_READABLE: The key exists but is not
+                readable.
+        """
+        extra_count = _validate_extra_count(extra_count)
+        total = 1 + extra_count
+        ret: dict[ObjectKey, L1OperationResult] = {}
+        successful_keys: list[ObjectKey] = []
+        for key in keys:
+            entry = self._objects.get(key, None)
+            if entry is None:
+                ret[key] = (L1Error.KEY_NOT_EXIST, None)
+                continue
+
+            if not entry.available_for_read():
+                ret[key] = (L1Error.KEY_NOT_READABLE, None)
+                continue
+
+            # TODO(perf): support a count argument in
+            # TTLLock.lock() to avoid Python for-loop
+            # overhead (TTLLock is C++ std::atomic).
+            for _ in range(total):
+                entry.read_lock.lock()
+            ret[key] = (L1Error.SUCCESS, entry.memory_obj)
+            successful_keys.append(key)
+
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_reserved_read(successful_keys)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_READ_RESERVED,
+                metadata={"keys": successful_keys},
+            )
+        )
+        return ret
+
+    @l1_mgr_synchronized
+    def unsafe_read(
+        self,
+        keys: list[ObjectKey],
+    ) -> dict[ObjectKey, L1OperationResult]:
+        """Unsafe read the read-locked objects without adding new read locks.
+
+        This method does not acquire read locks. Therefore, the caller need
+        to make sure the `unsafe_read` is called between `reserve_read` and
+        `finish_read` calls.
+
+        Args:
+            keys: The list of object keys to read.
+
+        Returns:
+            A dictionary mapping each object key to a tuple of
+            (L1Error, Optional[MemoryObj]).
+
+        Errors:
+            KEY_NOT_EXIST: The key does not exist.
+            KEY_NOT_READABLE: The key is not readable (in this case, not read-locked).
+        """
+        ret: dict[ObjectKey, L1OperationResult] = {}
+
+        for key in keys:
+            entry = self._objects.get(key, None)
+            if entry is None:
+                ret[key] = (L1Error.KEY_NOT_EXIST, None)
+                continue
+
+            if not entry.read_lock.is_locked():
+                ret[key] = (L1Error.KEY_NOT_READABLE, None)
+                continue
+
+            ret[key] = (L1Error.SUCCESS, entry.memory_obj)
+
+        return ret
+
+    @l1_mgr_synchronized
+    def finish_read(
+        self,
+        keys: list[ObjectKey],
+        extra_count: int = 0,
+    ) -> dict[ObjectKey, L1Error]:
+        """Finish read access for the given keys.
+
+        Will delete the object if it is temporary and read
+        count reaches zero.
+
+        Args:
+            keys: The list of object keys to finish read
+                access for.
+            extra_count: Extra read locks to release on top
+                of the default 1.  Must match the
+                ``extra_count`` used in the corresponding
+                ``reserve_read`` call.
+
+        Returns:
+            A dictionary mapping each object key to an
+            L1Error.
+
+        Errors:
+            KEY_NOT_EXIST: The key does not exist.
+            KEY_IN_WRONG_STATE: The key is write-locked or
+                non-read-locked, which means the reader may
+                read inconsistent data.
+        """
+        extra_count = _validate_extra_count(extra_count)
+        total = 1 + extra_count
+        need_to_free: list[MemoryObj] = []
+        need_to_free_keys: list[ObjectKey] = []
+        ret: dict[ObjectKey, L1Error] = {}
+        successful_keys: list[ObjectKey] = []
+
+        for key in keys:
+            entry = self._objects.get(key, None)
+            if entry is None:
+                logger.warning(
+                    "L1Manager: finish read on non-existing key %s, "
+                    "potential inconsistent data might be read",
+                    key,
+                )
+                ret[key] = L1Error.KEY_NOT_EXIST
+                continue
+
+            if entry.write_lock.is_locked():
+                logger.warning(
+                    "L1Manager: finish read on write-locked key %s, "
+                    "potential inconsistent data might be read",
+                    key,
+                )
+                ret[key] = L1Error.KEY_IN_WRONG_STATE
+                continue
+
+            if not entry.read_lock.is_locked():
+                logger.warning(
+                    "L1Manager: finish read on non-read-locked key %s, "
+                    "potential inconsistent data might be read",
+                    key,
+                )
+                ret[key] = L1Error.KEY_IN_WRONG_STATE
+                continue
+
+            # TODO(perf): support a count argument in
+            # TTLLock.unlock() to avoid Python for-loop
+            # overhead (TTLLock is C++ std::atomic).
+            for _ in range(total):
+                entry.read_lock.unlock()
+            if entry.is_temporary and not entry.read_lock.is_locked():
+                # NOTE: temporary objects shouldn't have write-locks
+                need_to_free.append(entry.memory_obj)
+                need_to_free_keys.append(key)
+                del self._objects[key]
+
+            ret[key] = L1Error.SUCCESS
+            successful_keys.append(key)
+
+        self._memory_manager.free(need_to_free)
+
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_read_finished(successful_keys)
+            listener.on_l1_keys_deleted_by_manager(need_to_free_keys)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_READ_FINISHED,
+                metadata={"keys": successful_keys},
+            )
+        )
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_KEYS_EVICTED,
+                metadata={"keys": need_to_free_keys},
+            )
+        )
+
+        return ret
+
+    @l1_mgr_synchronized
+    def reserve_write(
+        self,
+        keys: list[ObjectKey],
+        is_temporary: list[bool],
+        layout_desc: MemoryLayoutDesc,
+        mode: Literal["new", "update", "all"] = "all",
+    ) -> dict[ObjectKey, L1OperationResult]:
+        """Reserve write access for the given keys.
+
+        Args:
+            keys: The list of object keys to reserve write access for.
+            is_temporary: The list of booleans indicating whether each key is
+                temporary.
+            shape_spec: The memory layout description for the objects to be
+                allocated.
+            mode (Literal["new", "update", "all"]): Reservation mode.
+            - "new": Reserve only new objects that do not exist.
+            - "update": Reserve only existing objects for update.
+            - "all": Reserve all writable objects regardless of existence.
+
+        Returns:
+            A dictionary mapping each object key to a tuple of
+            (L1Error, Optional[MemoryObj]).
+
+        Errors:
+            KEY_NOT_WRITABLE: The key exists but is not writable.
+            OUT_OF_MEMORY: Not enough memory to allocate for the object.
+        """
+        need_to_allocate: list[tuple[ObjectKey, bool]] = []
+        ret: dict[ObjectKey, L1OperationResult] = {}
+        successful_keys: list[ObjectKey] = []
+
+        for key, is_temp in zip(keys, is_temporary, strict=False):
+            entry = self._objects.get(key, None)
+            if entry is None:
+                need_to_allocate.append((key, is_temp))
+                continue
+
+            if mode == "new":
+                ret[key] = (L1Error.KEY_NOT_WRITABLE, None)
+                continue
+
+            if not entry.available_for_write():
+                ret[key] = (L1Error.KEY_NOT_WRITABLE, None)
+                continue
+
+            entry.write_lock.lock()
+            ret[key] = (L1Error.SUCCESS, entry.memory_obj)
+            successful_keys.append(key)
+
+        # Early return if no allocation is needed
+        if len(need_to_allocate) == 0:
+            return ret
+
+        # Don't allow allocation in "update" mode
+        if mode == "update":
+            for key, _ in need_to_allocate:
+                ret[key] = (L1Error.KEY_NOT_WRITABLE, None)
+            return ret
+
+        err, allocated_objs = self._memory_manager.allocate(
+            layout_desc, len(need_to_allocate)
+        )
+
+        if err != L1Error.SUCCESS:
+            for key, _ in need_to_allocate:
+                ret[key] = (L1Error.OUT_OF_MEMORY, None)
+
+            # Free the memory if partial allocation succeeded
+            if allocated_objs:
+                self._memory_manager.free(allocated_objs)
+
+        else:
+            for (key, is_temp), mem_obj in zip(
+                need_to_allocate, allocated_objs, strict=False
+            ):
+                self._objects[key] = L1ObjectState(
+                    memory_obj=mem_obj,
+                    write_lock=TTLLock(self._write_ttl_seconds),
+                    read_lock=TTLLock(self._read_ttl_seconds),
+                    is_temporary=is_temp,
+                )
+                self._objects[key].write_lock.lock()
+                ret[key] = (L1Error.SUCCESS, mem_obj)
+                successful_keys.append(key)
+
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_reserved_write(successful_keys)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_WRITE_RESERVED,
+                metadata={"keys": successful_keys},
+            )
+        )
+        return ret
+
+    @l1_mgr_synchronized
+    def finish_write(
+        self,
+        keys: list[ObjectKey],
+    ) -> dict[ObjectKey, L1Error]:
+        """Finish write access for the given keys.
+
+        Args:
+            keys: The list of object keys to finish write access for.
+
+        Returns:
+            A dictionary mapping each object key to an L1Error.
+
+        Errors:
+            KEY_NOT_EXIST: The key does not exist.
+            KEY_IN_WRONG_STATE: The key is not write-locked, or it's read-locked,
+                which means the writer may have caused inconsistent data.
+        """
+        ret: dict[ObjectKey, L1Error] = {}
+        successful_keys: list[ObjectKey] = []
+
+        for key in keys:
+            entry = self._objects.get(key, None)
+            if entry is None:
+                ret[key] = L1Error.KEY_NOT_EXIST
+                continue
+
+            if not entry.write_lock.is_locked():
+                logger.warning(
+                    "L1Manager: finish write on non-write-locked key %s, "
+                    "potential inconsistent data might be written",
+                    key,
+                )
+                ret[key] = L1Error.KEY_IN_WRONG_STATE
+                continue
+
+            if entry.read_lock.is_locked():
+                logger.warning(
+                    "L1Manager: finish write on read-locked key %s, "
+                    "potential inconsistent data might be written",
+                    key,
+                )
+                ret[key] = L1Error.KEY_IN_WRONG_STATE
+                continue
+
+            entry.write_lock.unlock()
+            ret[key] = L1Error.SUCCESS
+            successful_keys.append(key)
+
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_write_finished(successful_keys)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_WRITE_FINISHED,
+                metadata={"keys": successful_keys},
+            )
+        )
+        return ret
+
+    @l1_mgr_synchronized
+    def finish_write_and_reserve_read(
+        self,
+        keys: list[ObjectKey],
+        extra_count: int = 0,
+    ) -> dict[ObjectKey, L1OperationResult]:
+        """Atomically finish write and acquire read lock for the given keys.
+
+        This is used by the prefetch controller after successfully loading
+        data from L2 into write-reserved L1 buffers. It transitions the
+        object from write-locked to read-locked in a single atomic step,
+        preventing a race window where eviction could interfere.
+
+        Args:
+            keys: Keys to transition from write-locked to read-locked.
+            extra_count: Extra read locks on top of the default 1 lock.
+                Total locks acquired per key = 1 + extra_count.  Useful
+                when multiple TP workers each consume one read lock for
+                the same key (e.g. MLA models with TP > 1).
+
+        Returns:
+            A dictionary mapping each object key to a tuple of
+            (L1Error, Optional[MemoryObj]).
+
+        Errors:
+            KEY_NOT_EXIST: The key does not exist.
+            KEY_IN_WRONG_STATE: The key is not write-locked, or it already
+                has read locks.
+        """
+        extra_count = _validate_extra_count(extra_count)
+        total = 1 + extra_count
+        ret: dict[ObjectKey, L1OperationResult] = {}
+        successful_keys: list[ObjectKey] = []
+
+        for key in keys:
+            entry = self._objects.get(key, None)
+            if entry is None:
+                ret[key] = (L1Error.KEY_NOT_EXIST, None)
+                continue
+
+            if not entry.write_lock.is_locked():
+                logger.warning(
+                    "L1Manager: finish_write_and_reserve_read on "
+                    "non-write-locked key %s",
+                    key,
+                )
+                ret[key] = (L1Error.KEY_IN_WRONG_STATE, None)
+                continue
+
+            if entry.read_lock.is_locked():
+                logger.warning(
+                    "L1Manager: finish_write_and_reserve_read on read-locked key %s",
+                    key,
+                )
+                ret[key] = (L1Error.KEY_IN_WRONG_STATE, None)
+                continue
+
+            entry.write_lock.unlock()
+            for _ in range(total):
+                entry.read_lock.lock()
+            ret[key] = (L1Error.SUCCESS, entry.memory_obj)
+            successful_keys.append(key)
+
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_finish_write_and_reserve_read(successful_keys)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_WRITE_FINISHED_AND_READ_RESERVED,
+                metadata={"keys": successful_keys},
+            )
+        )
+        return ret
+
+    @l1_mgr_synchronized
+    def delete(self, keys: list[ObjectKey]) -> dict[ObjectKey, L1Error]:
+        """Delete the given keys from L1 cache.
+
+        Args:
+            keys: The list of object keys to delete.
+
+        Returns:
+            A dictionary mapping each object key to an L1Error.
+
+        Errors:
+            KEY_NOT_EXIST: The key does not exist.
+            KEY_IS_LOCKED: The key is locked (either write-locked or read-locked
+                and cannot be deleted).
+        """
+        need_to_free: list[MemoryObj] = []
+        ret: dict[ObjectKey, L1Error] = {}
+        successful_keys: list[ObjectKey] = []
+
+        for key in keys:
+            entry = self._objects.get(key, None)
+            if entry is None:
+                ret[key] = L1Error.KEY_NOT_EXIST
+                continue
+
+            if entry.read_lock.is_locked() or entry.write_lock.is_locked():
+                ret[key] = L1Error.KEY_IS_LOCKED
+                continue
+
+            need_to_free.append(entry.memory_obj)
+            del self._objects[key]
+            ret[key] = L1Error.SUCCESS
+            successful_keys.append(key)
+
+        self._memory_manager.free(need_to_free)
+
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_deleted_by_manager(successful_keys)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_KEYS_EVICTED,
+                metadata={"keys": successful_keys},
+            )
+        )
+        return ret
+
+    def touch_keys(self, keys: list[ObjectKey]):
+        """Touch the given keys, marking the keys as accessed(retrieved or stored).
+
+        Args:
+            keys: The list of object keys to touch.
+        """
+        for listener in self._registered_listeners:
+            listener.on_l1_keys_accessed(keys)
+
+    @l1_mgr_synchronized
+    def clear(self, force: bool = False) -> None:
+        """Clear objects from L1 cache.
+
+        Args:
+            force: If True, clear ALL objects including locked ones.
+                This may corrupt in-flight store/prefetch operations.
+                If False (default), only clear unlocked objects, keeping
+                write-locked and read-locked objects intact.
+        """
+        if force:
+            logger.warning(
+                "L1Manager: force-clearing all %d objects "
+                "(including locked ones). This may corrupt in-flight "
+                "store/prefetch operations — use with caution.",
+                len(self._objects),
+            )
+            all_keys = list(self._objects.keys())
+            all_memory_objs = [entry.memory_obj for entry in self._objects.values()]
+            self._memory_manager.free(all_memory_objs)
+            self._objects.clear()
+            for listener in self._registered_listeners:
+                listener.on_l1_keys_deleted_by_manager(all_keys)
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L1_KEYS_EVICTED,
+                    metadata={"keys": all_keys},
+                )
+            )
+            logger.info(
+                "L1Manager: cleared %d objects, 0 remaining.",
+                len(all_keys),
+            )
+            return
+
+        keys_to_clear: list[ObjectKey] = []
+        objs_to_free: list[MemoryObj] = []
+        locked_count = 0
+
+        for key, entry in list(self._objects.items()):
+            if entry.write_lock.is_locked() or entry.read_lock.is_locked():
+                locked_count += 1
+                continue
+            keys_to_clear.append(key)
+            objs_to_free.append(entry.memory_obj)
+
+        for key in keys_to_clear:
+            del self._objects[key]
+
+        self._memory_manager.free(objs_to_free)
+
+        if keys_to_clear:
+            for listener in self._registered_listeners:
+                listener.on_l1_keys_deleted_by_manager(keys_to_clear)
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L1_KEYS_EVICTED,
+                    metadata={"keys": keys_to_clear},
+                )
+            )
+
+        logger.info(
+            "L1Manager: cleared %d objects, %d locked objects remaining.",
+            len(keys_to_clear),
+            locked_count,
+        )
+
+    def is_key_evictable(self, key: ObjectKey) -> bool:
+        """Check if a key is eligible for eviction (not locked).
+
+        This method does NOT acquire the global L1Manager lock.
+        L1Manager.delete() will check again and safely reject a key
+        that became locked between the check and the actual deletion.
+
+        Args:
+            key: The object key to check.
+
+        Returns:
+            True if the key exists and is not locked (neither read-locked
+            nor write-locked), False otherwise.
+        """
+        entry = self._objects.get(key, None)
+        if entry is None:
+            return False
+        return not entry.read_lock.is_locked() and not entry.write_lock.is_locked()
+
+    def get_memory_usage(self) -> tuple[int, int]:
+        """Get the current memory usage of L1 cache.
+
+        Returns:
+            A tuple of (used_memory_bytes, total_memory_bytes).
+
+        Note:
+            In the future, we many want to make a "callback" based mechanism
+            via "L1ManagerListener" to notify the memory usage changes.
+        """
+        return self._memory_manager.get_memory_usage()
+
+    def get_l1_memory_desc(self):
+        """Return an L1MemoryDesc describing the underlying L1 memory buffer."""
+        return self._memory_manager.get_l1_memory_desc()
+
+    def close(self) -> None:
+        """Close the L1Manager and free all resources."""
+        with self._lock:
+            all_memory_objs = [entry.memory_obj for entry in self._objects.values()]
+            self._memory_manager.free(all_memory_objs)
+            self._objects.clear()
+
+        self._memory_manager.close()
+
+    # Status reporting
+    @l1_mgr_synchronized
+    def report_status(self) -> dict:
+        """Return a status dict describing L1 cache state."""
+        write_locked = 0
+        read_locked = 0
+        temporary = 0
+        for entry in self._objects.values():
+            if entry.write_lock.is_locked():
+                write_locked += 1
+            if entry.read_lock.is_locked():
+                read_locked += 1
+            if entry.is_temporary:
+                temporary += 1
+        used, total = self._memory_manager.get_memory_usage()
+        return {
+            "is_healthy": self._memory_manager.memcheck(),
+            "total_object_count": len(self._objects),
+            "write_locked_count": write_locked,
+            "read_locked_count": read_locked,
+            "temporary_count": temporary,
+            "memory_used_bytes": used,
+            "memory_total_bytes": total,
+            "memory_usage_ratio": used / total if total > 0 else 0.0,
+            "write_ttl_seconds": self._write_ttl_seconds,
+            "read_ttl_seconds": self._read_ttl_seconds,
+        }
+
+    # Debugging APIs
+    @l1_mgr_synchronized
+    def get_object_state(self, key: ObjectKey) -> L1ObjectState | None:
+        """Get the internal state of the object with the given key.
+
+        Args:
+            key: The object key.
+
+        Returns:
+            The L1ObjectState if the object exists, None otherwise.
+        """
+        return self._objects.get(key, None)
+
+    @l1_mgr_synchronized
+    def memcheck(self) -> bool:
+        """Perform memory check for L1 cache."""
+        mem_check_result = self._memory_manager.memcheck()
+
+        # Log the locked objects for debugging
+        num_write_locked = 0
+        num_read_locked = 0
+        for key, entry in self._objects.items():
+            if entry.write_lock.is_locked():
+                num_write_locked += 1
+            if entry.read_lock.is_locked():
+                num_read_locked += 1
+
+        logger.info(
+            "L1Manager memcheck: total objects = %d, write-locked = %d, "
+            "read-locked = %d",
+            len(self._objects),
+            num_write_locked,
+            num_read_locked,
+        )
+        return mem_check_result
diff --git a/lmcache/v1/distributed/l2_adapters/__init__.py b/lmcache/v1/distributed/l2_adapters/__init__.py
new file mode 100644
index 0000000..2d32de1
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/__init__.py
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+L2 adapter factory with lazy module loading.
+
+Built-in adapter modules are auto-discovered via
+``pkgutil`` but only imported when their adapter type
+is actually requested.  To add a new built-in adapter,
+simply create a new ``*_l2_adapter.py`` module in this
+directory -- **no other changes are needed**.
+"""
+
+# Standard
+import pkgutil
+
+# First Party
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    add_pending_module,
+    create_l2_adapter_from_registry,
+)
+
+# ---------------------------------------------------------
+# Auto-discover built-in adapter modules (not imported yet)
+# Convention: any ``*_l2_adapter`` submodule is eligible.
+# ---------------------------------------------------------
+for _finder, _module_name, _ispkg in pkgutil.iter_modules(__path__):
+    if _module_name.endswith("_l2_adapter"):
+        add_pending_module(f"{__name__}.{_module_name}")
+
+
+def create_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: L1MemoryDesc | None = None,
+) -> L2AdapterInterface:
+    """Create an L2 adapter from its config via the
+    factory registry.
+
+    Args:
+        config: The adapter-specific config object.
+        l1_memory_desc: Descriptor of the L1 memory buffer,
+            required for adapters that register L1 memory
+            with an external backend (e.g. Nixl or
+            Mooncake when ``protocol == "rdma"``).
+
+    Returns:
+        L2AdapterInterface: A new adapter instance.
+
+    Raises:
+        ValueError: If no factory is registered for
+            the config type.
+    """
+    return create_l2_adapter_from_registry(
+        config,
+        l1_memory_desc=l1_memory_desc,
+    )
+
+
+__all__ = [
+    "L2AdapterInterface",
+    "L2AdapterConfigBase",
+    "create_l2_adapter",
+]
diff --git a/lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py
new file mode 100644
index 0000000..d416ddd
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/aerospike_l2_adapter.py
@@ -0,0 +1,239 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Aerospike L2 adapter config and factory.
+
+Backed by the native C++ Aerospike connector wrapped with
+``NativeConnectorL2Adapter``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Optional
+import os
+
+if TYPE_CHECKING:
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import register_l2_adapter_factory
+
+logger = init_logger(__name__)
+
+
+class AerospikeL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for an L2 adapter backed by the native Aerospike connector.
+
+    Fields:
+    - hosts: seed hosts as ``host:port[,host:port...]``
+    - namespace: Aerospike namespace
+    - set_name: Aerospike set name
+    - num_workers: C++ worker threads for I/O (default 8)
+    - read_timeout_ms / write_timeout_ms: client timeouts
+    - default_ttl_seconds: record TTL (0 = namespace default)
+    - target_segment_bytes: shard target (0 = use discovered cap)
+    - max_record_bytes: override server record cap (0 = discover)
+    - username / password: optional EE auth
+    - max_capacity_gb: L2 capacity tracking (0 = disabled)
+    """
+
+    def __init__(
+        self,
+        hosts: str,
+        namespace: str = "lmcache",
+        set_name: str = "kv_chunks",
+        num_workers: int = 8,
+        read_timeout_ms: int = 1000,
+        write_timeout_ms: int = 2000,
+        default_ttl_seconds: int = 86400,
+        target_segment_bytes: int = 0,
+        max_record_bytes: int = 0,
+        username: str = "",
+        password: str = "",
+        max_capacity_gb: float = 0,
+    ) -> None:
+        super().__init__()
+        self.hosts = hosts
+        self.namespace = namespace
+        self.set_name = set_name
+        self.num_workers = num_workers
+        self.read_timeout_ms = read_timeout_ms
+        self.write_timeout_ms = write_timeout_ms
+        self.default_ttl_seconds = default_ttl_seconds
+        self.target_segment_bytes = target_segment_bytes
+        self.max_record_bytes = max_record_bytes
+        self.username = username
+        self.password = password
+        self.max_capacity_gb = max_capacity_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AerospikeL2AdapterConfig":
+        """Construct a config from a raw configuration dict.
+
+        Args:
+            d: Raw configuration dict (typically from JSON/CLI).
+
+        Returns:
+            A validated ``AerospikeL2AdapterConfig``.
+
+        Raises:
+            ValueError: If required fields are missing or invalid.
+        """
+        hosts = d.get("hosts")
+        if not isinstance(hosts, str) or not hosts:
+            raise ValueError("hosts must be a non-empty string")
+
+        namespace = d.get("namespace", "lmcache")
+        if not isinstance(namespace, str) or not namespace:
+            raise ValueError("namespace must be a non-empty string")
+
+        set_name = d.get("set_name", d.get("set", "kv_chunks"))
+        if not isinstance(set_name, str) or not set_name:
+            raise ValueError("set_name must be a non-empty string")
+
+        num_workers = d.get("num_workers", 8)
+        if not isinstance(num_workers, int) or num_workers <= 0:
+            raise ValueError("num_workers must be a positive integer")
+
+        read_timeout_ms = d.get("read_timeout_ms", 1000)
+        if not isinstance(read_timeout_ms, int) or read_timeout_ms <= 0:
+            raise ValueError("read_timeout_ms must be a positive integer")
+
+        write_timeout_ms = d.get("write_timeout_ms", 2000)
+        if not isinstance(write_timeout_ms, int) or write_timeout_ms <= 0:
+            raise ValueError("write_timeout_ms must be a positive integer")
+
+        default_ttl_seconds = d.get("default_ttl_seconds", 86400)
+        if not isinstance(default_ttl_seconds, int) or default_ttl_seconds < 0:
+            raise ValueError("default_ttl_seconds must be a non-negative integer")
+
+        target_segment_bytes = d.get("target_segment_bytes", 0)
+        if not isinstance(target_segment_bytes, int) or target_segment_bytes < 0:
+            raise ValueError("target_segment_bytes must be a non-negative integer")
+
+        max_record_bytes = d.get("max_record_bytes", 0)
+        if not isinstance(max_record_bytes, int) or max_record_bytes < 0:
+            raise ValueError("max_record_bytes must be a non-negative integer")
+
+        username = d.get("username", "")
+        password = d.get("password", "")
+
+        max_capacity_gb = d.get("max_capacity_gb", 0)
+        if not isinstance(max_capacity_gb, (int, float)) or max_capacity_gb < 0:
+            raise ValueError("max_capacity_gb must be a non-negative number")
+
+        return cls(
+            hosts=hosts,
+            namespace=str(namespace),
+            set_name=str(set_name),
+            num_workers=num_workers,
+            read_timeout_ms=read_timeout_ms,
+            write_timeout_ms=write_timeout_ms,
+            default_ttl_seconds=default_ttl_seconds,
+            target_segment_bytes=target_segment_bytes,
+            max_record_bytes=max_record_bytes,
+            username=str(username),
+            password=str(password),
+            max_capacity_gb=float(max_capacity_gb),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Aerospike L2 adapter config fields:\n"
+            "- hosts (str): seed hosts host:port[,...] (required)\n"
+            "- namespace (str): Aerospike namespace (default lmcache)\n"
+            "- set_name / set (str): Aerospike set (default kv_chunks)\n"
+            "- num_workers (int): C++ I/O threads (default 8)\n"
+            "- read_timeout_ms (int): read timeout ms (default 1000)\n"
+            "- write_timeout_ms (int): write timeout ms (default 2000)\n"
+            "- default_ttl_seconds (int): record TTL (default 86400)\n"
+            "- target_segment_bytes (int): shard target, 0 = auto (default 0)\n"
+            "- max_record_bytes (int): cap override, 0 = discover (default 0)\n"
+            "- username / password (str): optional auth\n"
+            "- max_capacity_gb (float): L2 capacity for eviction (default 0)\n\n"
+            "Environment variable defaults (when config value is empty):\n"
+            "- LMCACHE_AEROSPIKE_HOSTS\n"
+            "- LMCACHE_AEROSPIKE_NAMESPACE\n"
+            "- LMCACHE_AEROSPIKE_SET\n"
+            "- LMCACHE_AEROSPIKE_USERNAME\n"
+            "- LMCACHE_AEROSPIKE_PASSWORD"
+        )
+
+
+def _create_aerospike_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Create a NativeConnectorL2Adapter backed by the C++ Aerospike connector."""
+    del l1_memory_desc
+    try:
+        # First Party
+        from lmcache.lmcache_aerospike import LMCacheAerospikeClient
+    except ImportError as e:
+        raise RuntimeError(
+            "Aerospike L2 adapter requires the C++ Aerospike extension. "
+            "Build with: BUILD_AEROSPIKE=1 pip install -e ."
+        ) from e
+
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+        NativeConnectorL2Adapter,
+    )
+
+    assert isinstance(config, AerospikeL2AdapterConfig)
+
+    hosts = config.hosts or os.environ.get("LMCACHE_AEROSPIKE_HOSTS", "")
+    namespace = config.namespace or os.environ.get(
+        "LMCACHE_AEROSPIKE_NAMESPACE", "lmcache"
+    )
+    set_name = config.set_name or os.environ.get("LMCACHE_AEROSPIKE_SET", "kv_chunks")
+    username = config.username or os.environ.get("LMCACHE_AEROSPIKE_USERNAME", "")
+    password = config.password or os.environ.get("LMCACHE_AEROSPIKE_PASSWORD", "")
+
+    if not hosts:
+        raise ValueError("hosts must be a non-empty string")
+
+    native_client = LMCacheAerospikeClient(
+        hosts,
+        namespace,
+        set_name,
+        config.num_workers,
+        config.read_timeout_ms,
+        config.write_timeout_ms,
+        config.default_ttl_seconds,
+        config.target_segment_bytes,
+        config.max_record_bytes,
+        username,
+        password,
+    )
+    logger.info(
+        "Created Aerospike L2 adapter: hosts=%s namespace=%s set=%s (workers=%d)",
+        hosts,
+        namespace,
+        set_name,
+        config.num_workers,
+    )
+    return NativeConnectorL2Adapter(
+        native_client,
+        max_capacity_gb=config.max_capacity_gb,
+        type_name="aerospike",
+        extra_status={
+            "hosts": hosts,
+            "namespace": namespace,
+            "set_name": set_name,
+            "num_workers": config.num_workers,
+        },
+    )
+
+
+register_l2_adapter_type("aerospike", AerospikeL2AdapterConfig)
+register_l2_adapter_factory("aerospike", _create_aerospike_l2_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/base.py b/lmcache/v1/distributed/l2_adapters/base.py
new file mode 100644
index 0000000..1838553
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/base.py
@@ -0,0 +1,552 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Interface for L2 adapters
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Mapping
+import threading
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.native_storage_ops import Bitmap
+    from lmcache.v1.distributed.api import KeyListPage, MemoryLayoutDesc, ObjectKey
+    from lmcache.v1.distributed.internal_api import L2AdapterListener, L2StoreResult
+    from lmcache.v1.memory_management import MemoryObj
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+L2TaskId = int
+
+
+_EMPTY_BY_CACHE_SALT: Mapping[str, int] = MappingProxyType({})
+
+
+@dataclass(frozen=True)
+class AdapterUsage:
+    """Unified usage report for an L2 adapter.
+
+    Replaces the old ``tuple[float, float]`` return shape with a structured
+    record that exposes both aggregate and per cache_salt byte counts.
+    Buckets are keyed by ``ObjectKey.cache_salt`` directly — the salt may
+    represent a user, a vLLM deployment, or any other isolation
+    granularity the caller chooses; the adapter stays agnostic.
+
+    Instances are returned as immutable snapshots:
+    ``bytes_by_cache_salt`` is a read-only ``Mapping``
+    (``MappingProxyType``) so callers cannot mutate the snapshot after
+    the fact. Each ``get_usage()`` call returns a fresh snapshot so a
+    held reference will never reflect later state.
+    """
+
+    total_bytes_used: int
+    """Aggregate bytes across all cache_salt buckets."""
+
+    total_capacity_bytes: int
+    """Adapter's maximum capacity. ``0`` means unknown / unlimited; the
+    adapter does not support aggregate (global) usage-based eviction."""
+
+    bytes_by_cache_salt: Mapping[str, int] = field(
+        default_factory=lambda: _EMPTY_BY_CACHE_SALT
+    )
+    """Bytes used per ``cache_salt``. Only entries with positive usage
+    appear; an empty mapping means no traffic has been tracked yet.
+    Read-only — wrap with ``dict(...)`` if you need a mutable copy."""
+
+    @property
+    def usage_fraction(self) -> float:
+        """Aggregate usage as a fraction in [0, 1].
+
+        Returns ``-1.0`` when capacity is unknown (``total_capacity_bytes
+        <= 0``) — matches the legacy sentinel from ``get_usage()`` so
+        callers can keep using ``< 0`` to mean "no eviction signal".
+        """
+        if self.total_capacity_bytes <= 0:
+            return -1.0
+        return self.total_bytes_used / self.total_capacity_bytes
+
+
+class L2AdapterInterface(ABC):
+    """
+    The abstracted interface for L2 I/O adapters.
+
+    The L2 I/O adapter mainly provides 3 main functionalities with non-blocking
+    primitives:
+    1. Store: store a batch of memory objects associated with a batch of keys.
+    2. Lookup and lock: look up and lock a batch of objects by the given keys.
+       will also try to 'lock' the objects to prevent being evicted before
+       loading them to L1.
+    3. Load: load a batch of objects by the given keys. The load operation is
+       not guaranteed to succeed, and the caller should check the return value.
+       In most of cases, it should be likely to succeed if the objects are locked.
+
+    Note that the store and the load operation are pre-provided with the data buffer
+    (i.e., memory objects), which is managed by the caller (L2 controller). The L2
+    adapter is not supposed to manage the lifecycle of the memory objects.
+
+    The non-blocking interface is designed as follows:
+    1. Submit task
+    2. Query the completed tasks (either pop all the completed tasks or query
+       a specific task by its id)
+    3. Use event fd to signal the completion of the tasks. The event fd will be
+       handled by the caller (L2 controller). Note that the event fd will be
+       closed by the `close()` function.
+
+
+    Error handling:
+    1. For store operation, we only provide a coarse-grained error handling, which
+       means that we only report the error at the task level. If a store task fails,
+       we will report the failure of the whole task, instead of reporting the failure
+       of each key-object pair in the task. The caller can choose to retry the failed
+       task or not.
+    2. For both lookup and load operations, we will return a bitmap indicating the
+       success or failure of each key-object pair in the task.
+
+    Thread-safe:
+    The L2 adapter is designed to be called by a 2 controller threads (store controller
+    and prefetch controller), therefore, it needs to be thread-safe.
+    """
+
+    def __init__(self, max_capacity_bytes: int = 0) -> None:
+        """
+        Args:
+            max_capacity_bytes: Adapter's maximum byte capacity. ``0``
+                (default) marks the adapter as not supporting global
+                (aggregate) eviction — ``supports_global_eviction``
+                returns ``False`` and ``get_usage`` returns
+                ``usage_fraction == -1.0``. Per-cache_salt eviction
+                policies (e.g. quota-based) can still operate on the
+                per-bucket byte counts regardless of this value.
+        """
+        self._listeners: list[L2AdapterListener] = []
+
+        # Centralized byte accounting. Subclasses pass ``sizes`` to
+        # ``_notify_keys_stored`` / ``_notify_keys_deleted`` and the base
+        # class maintains both aggregate and per cache_salt totals so
+        # every adapter exposes the same shape via ``get_usage()``.
+        self._max_capacity_bytes: int = max_capacity_bytes
+        self._total_bytes_used: int = 0
+        self._bytes_by_cache_salt: dict[str, int] = {}
+        self._usage_lock = threading.Lock()
+
+    #####################
+    # Event Fd Interface
+    #####################
+
+    # IMPORTANT: Each of the three event fd methods below MUST return a
+    # distinct file descriptor.  The store controller and prefetch controller
+    # build fd-to-adapter lookup maps; if any two methods return the same fd
+    # (within one adapter or across adapters), poll-based dispatch will
+    # silently misroute events.
+
+    @abstractmethod
+    def get_store_event_fd(self) -> int:
+        """
+        Get the event fd for store operation, which will be signaled on the
+        completion of the store tasks.
+
+        Returns:
+            int: the event fd for store operation.
+
+        Note:
+            Must be distinct from the lookup and load event fds of this
+            adapter, and from the event fds of all other adapters.
+        """
+        pass
+
+    @abstractmethod
+    def get_lookup_and_lock_event_fd(self) -> int:
+        """
+        Get the event fd for lookup and lock operation, which will be signaled
+        on the completion of the lookup and lock tasks.
+
+        Returns:
+            int: the event fd for lookup and lock operation.
+
+        Note:
+            Must be distinct from the store and load event fds of this
+            adapter, and from the event fds of all other adapters.
+        """
+        pass
+
+    @abstractmethod
+    def get_load_event_fd(self) -> int:
+        """
+        Get the event fd for load operation, which will be signaled on the completion
+        of the load tasks.
+
+        Returns:
+            int: the event fd for load operation.
+
+        Note:
+            Must be distinct from the store and lookup event fds of this
+            adapter, and from the event fds of all other adapters.
+        """
+        pass
+
+    #####################
+    # Store Interface
+    #####################
+
+    @abstractmethod
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """
+        Submit a store task to store a batch of memory objects associated with
+        a batch of keys.
+
+        Args:
+            keys (list[ObjectKey]): the list of keys to be stored.
+            objects (list[MemoryObj]): the list of memory objects to be stored.
+                The length of the objects list should be the same as the length of
+                the keys list.
+
+        Returns:
+            L2TaskId: the task id of the submitted store task.
+        """
+        pass
+
+    @abstractmethod
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        """Pop all completed store tasks.
+
+        Returns:
+            dict[L2TaskId, L2StoreResult]: a dictionary mapping the task
+            id to an ``L2StoreResult`` that encodes both the success flag
+            and the bytes actually transferred. Use
+            ``result.is_successful()`` and ``result.bytes_transferred()``
+            to inspect the outcome.
+        """
+        pass
+
+    #####################
+    # Lookup and Lock Interface
+    #####################
+
+    @abstractmethod
+    def submit_lookup_and_lock_task(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+    ) -> L2TaskId:
+        """
+        Submit a lookup and lock task to look up and lock a batch of objects
+        by the given keys.
+
+        Args:
+            keys (list[ObjectKey]): the list of keys to be looked up and locked.
+            layout_desc (MemoryLayoutDesc): the memory layout of the objects.
+                This is an advisory hint; most adapters ignore it. The P2P
+                adapter forwards it to the peer cache server.
+
+        Returns:
+            L2TaskId: the task id of the submitted lookup and lock task.
+        """
+        pass
+
+    @abstractmethod
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        """
+        Non-blockingly query the result of a lookup and lock task by its task id.
+        The result is a bitmap indicating the success or failure of each key-object
+        pair in the task.
+
+        For a single task id, this function will ONLY return a non-None value ONCE.
+        (Which means this function is not idempotent)
+
+        Args:
+            task_id (L2TaskId): the task id of the lookup and lock task.
+
+        Returns:
+            Optional[Bitmap]: a bitmap indicating the success or failure of each
+            key-object pair in the task. 1 means successful, and 0 means failed.
+            None is returned when the lookup and lock task is not completed.
+        """
+        pass
+
+    @abstractmethod
+    def submit_unlock(
+        self,
+        keys: list[ObjectKey],
+    ) -> None:
+        """
+        Submit an unlock task to unlock a batch of objects by the given keys.
+
+        Args:
+            keys (list[ObjectKey]): the list of keys to be unlocked.
+
+        Note:
+            This function does not return any task id, meaning that the caller
+            assumes the unlock operation will be eventually successful, and will
+            NEVER retry.
+            Therefore, the implementation MUST make sure that the unlock operation
+            is successful (i.e., have error handling and retry mechanism if needed).
+        """
+        pass
+
+    #####################
+    # Load Interface
+    ######################
+
+    @abstractmethod
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """
+        Submit a load task to load a batch of objects by the given keys. The load
+        operation is not guaranteed to succeed, and the caller should check the
+        return value.
+
+        Args:
+            keys (list[ObjectKey]): the list of keys to be loaded.
+            objects (list[MemoryObj]): the list of memory objects as the load buffer.
+                The L2 adapter will write the loaded data to the memory buffer provided
+                by the caller. The caller is responsible for managing the lifecycle of
+                the memory objects, and should make sure that the memory buffer is valid
+                until the load task is completed.
+                The length of the objects list should be the same as the length of the
+                keys list.
+
+        Returns:
+            L2TaskId: the task id of the submitted load task.
+        """
+        pass
+
+    @abstractmethod
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        """
+        Non-blockingly query the result of a load task by its task id. The result
+        is a bitmap indicating the success or failure of each key-object pair in
+        the task.
+
+        For a single task id, this function will ONLY return a non-None value ONCE.
+        (Which means this function is not idempotent)
+
+        Args:
+            task_id (L2TaskId): the task id of the load task.
+
+        Returns:
+            Optional[Bitmap]: a bitmap indicating the success or failure of each
+            key-object pair in the task. 1 means successful, and 0 means failed.
+            None is returned when the load task is not completed.
+        """
+        pass
+
+    #####################
+    # Listener Interface
+    #####################
+
+    def register_listener(self, listener: L2AdapterListener) -> None:
+        """Register a listener to receive L2 adapter events."""
+        self._listeners.append(listener)
+
+    def _notify_keys_stored(self, keys: list[ObjectKey], sizes: list[int]) -> None:
+        """Update byte accounting and notify listeners that ``keys`` were
+        stored. ``sizes[i]`` is the byte size of ``keys[i]``.
+
+        Accounting is held under ``_usage_lock``; listener callbacks fire
+        outside the lock so a slow listener cannot stall further notifies.
+        """
+        # Aggregate per-salt deltas before touching
+        # ``_bytes_by_cache_salt`` — one dict read/write per unique
+        # salt instead of one per key. This matters when the registry is
+        # large (10k+ salts) and keys/sizes are bulky.
+        delta: dict[str, int] = {}
+        total_delta = 0
+        for key, size in zip(keys, sizes, strict=True):
+            delta[key.cache_salt] = delta.get(key.cache_salt, 0) + size
+            total_delta += size
+
+        with self._usage_lock:
+            self._total_bytes_used += total_delta
+            for salt, d in delta.items():
+                self._bytes_by_cache_salt[salt] = (
+                    self._bytes_by_cache_salt.get(salt, 0) + d
+                )
+        for listener in self._listeners:
+            listener.on_l2_keys_stored(keys, sizes)
+
+    def _notify_keys_accessed(self, keys: list[ObjectKey]) -> None:
+        # ``_notify_keys_accessed`` carries no byte impact — only LRU
+        # bookkeeping cares about it, so no accounting is needed here.
+        for listener in self._listeners:
+            listener.on_l2_keys_accessed(keys)
+
+    def _notify_keys_deleted(self, keys: list[ObjectKey], sizes: list[int]) -> None:
+        """Update byte accounting and notify listeners that ``keys`` were
+        deleted. ``sizes[i]`` is the byte size of ``keys[i]`` (typically
+        the same value the adapter passed to ``_notify_keys_stored``).
+
+        Per-cache_salt buckets that drop to zero are removed so the
+        ``bytes_by_cache_salt`` snapshot in ``AdapterUsage`` stays compact.
+
+        Counters are clamped at zero — a delete that would drive
+        ``_total_bytes_used`` negative indicates an accounting bug in the
+        caller (size mismatch, double-delete, etc.). Without the clamp the
+        sentinel ``usage_fraction == -1`` would silently disable eviction
+        forever; with it we log a warning and recover.
+        """
+        # Same batching rationale as ``_notify_keys_stored`` — aggregate
+        # per-salt deltas first so the hot path does one dict read/write
+        # per unique salt, not per key.
+        delta: dict[str, int] = {}
+        total_delta = 0
+        for key, size in zip(keys, sizes, strict=True):
+            delta[key.cache_salt] = delta.get(key.cache_salt, 0) + size
+            total_delta += size
+
+        with self._usage_lock:
+            self._total_bytes_used -= total_delta
+            if self._total_bytes_used < 0:
+                logger.warning(
+                    "L2 adapter byte accounting underflow: "
+                    "_total_bytes_used dropped to %d after deleting %d "
+                    "keys (total size %d). Clamping to 0; this indicates "
+                    "an accounting bug (double-delete or size mismatch) "
+                    "in the adapter.",
+                    self._total_bytes_used,
+                    len(keys),
+                    total_delta,
+                )
+                self._total_bytes_used = 0
+            for salt, d in delta.items():
+                new_total = self._bytes_by_cache_salt.get(salt, 0) - d
+                if new_total <= 0:
+                    self._bytes_by_cache_salt.pop(salt, None)
+                else:
+                    self._bytes_by_cache_salt[salt] = new_total
+        for listener in self._listeners:
+            listener.on_l2_keys_deleted(keys)
+
+    #####################
+    # Eviction Interface
+    #####################
+
+    @property
+    def supports_global_eviction(self) -> bool:
+        """Whether this adapter supports **aggregate** (global) usage-driven
+        eviction.
+
+        ``True`` when the adapter declared a positive
+        ``max_capacity_bytes`` at construction time. Adapters that don't
+        track or cap aggregate byte usage (e.g. the FS adapter, which
+        assumes unbounded disk) pass ``0`` and return ``False``. The
+        storage manager skips creating an ``L2AdapterEvictionState``
+        with a global policy for these adapters even if an
+        ``eviction_config`` is otherwise present.
+
+        Per-cache_salt eviction policies (e.g. quota-based) are
+        orthogonal to this flag — they can operate on the per-bucket
+        byte counts regardless of whether aggregate capacity is
+        declared.
+        """
+        return self._max_capacity_bytes > 0
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """
+        Delete a batch of objects from L2 storage.
+
+        Args:
+            keys (list[ObjectKey]): The keys of the objects to delete.
+
+        Note:
+            Implementations should fire on_l2_keys_deleted on registered
+            L2AdapterListeners once the deletion completes.
+
+            The default implementation is a no-op. Subclasses that support
+            eviction should override this method.
+        """
+        return None
+
+    def list_l2_keys(
+        self,
+        model_name: str | None = None,
+        page_size: int = 500,
+        cursor: str | None = None,
+    ) -> KeyListPage:
+        """List keys currently resident in this adapter, paginated.
+
+        Args:
+            model_name: if set, restrict to keys with this
+                ``ObjectKey.model_name``.
+            page_size: maximum entries to return in this page.
+            cursor: opaque cursor from the previous page; ``None`` on
+                the first call.
+
+        Raises:
+            NotImplementedError: the adapter does not support listing.
+            ValueError: ``page_size`` is non-positive or ``cursor`` is
+                malformed.
+        """
+        raise NotImplementedError(
+            f"{type(self).__name__} does not implement list_l2_keys"
+        )
+
+    def get_usage(self) -> AdapterUsage:
+        """
+        Return the current L2 storage utilization as an ``AdapterUsage``.
+
+        The default implementation returns the totals maintained by the
+        base class via ``_notify_keys_stored`` / ``_notify_keys_deleted``,
+        so adapters that pass their stored sizes through those helpers do
+        not need to override this method.
+
+        ``AdapterUsage.usage_fraction`` returns ``-1.0`` when
+        ``max_capacity_bytes <= 0`` — the legacy "no eviction signal"
+        sentinel — so eviction-controller callers can keep the same
+        ``< 0`` short-circuit they had with the old tuple API.
+        """
+        with self._usage_lock:
+            per_salt_snapshot = {
+                k: v for k, v in self._bytes_by_cache_salt.items() if v > 0
+            }
+            return AdapterUsage(
+                total_bytes_used=self._total_bytes_used,
+                total_capacity_bytes=self._max_capacity_bytes,
+                # Wrap in a read-only view so callers can't mutate the
+                # snapshot. The underlying dict is a fresh copy so the
+                # view is fully detached from the adapter's live state.
+                bytes_by_cache_salt=MappingProxyType(per_salt_snapshot),
+            )
+
+    #####################
+    # Cleanup Interface
+    #####################
+
+    @abstractmethod
+    def close(self) -> None:
+        """
+        Close the L2 adapter and release all the resources. After calling this function,
+        the L2 adapter should not be used anymore.
+        """
+        pass
+
+    #####################
+    # Status Interface
+    #####################
+
+    def report_status(self) -> dict:
+        """
+        Return a status dict for this adapter.
+
+        Must include at least ``is_healthy: bool``.
+        Subclasses should override this with adapter-specific metrics.
+        """
+        return {
+            "is_healthy": True,
+            "extra_warning": "report_status is not implemented and runs default impl",
+        }
diff --git a/lmcache/v1/distributed/l2_adapters/config.py b/lmcache/v1/distributed/l2_adapters/config.py
new file mode 100644
index 0000000..c251c36
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/config.py
@@ -0,0 +1,512 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Configuration for L2 adapters.
+
+Supports multiple adapter instances (including multiple instances of the same
+adapter type with different configs) via repeatable --l2-adapter <JSON>.
+Each JSON object must include "type" (adapter type name) and type-specific keys.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypeVar
+import json
+
+if TYPE_CHECKING:
+    # Standard
+    import argparse
+
+    # First Party
+    from lmcache.v1.distributed.config import EvictionConfig
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.serde import SerdeConfig
+
+logger = init_logger(__name__)
+
+T = TypeVar("T", bound="L2AdapterConfigBase")
+
+
+@dataclass(frozen=True)
+class PersistConfig:
+    """
+    Configuration for persist on an L2 adapter.
+
+    When enabled, data files are kept on disk at shutdown instead of
+    deleted. Lookup always checks secondary storage (disk) on miss
+    regardless of this setting.
+    """
+
+    persist_enabled: bool = True
+    """ If True, data files are kept on disk at shutdown instead of deleted. """
+
+
+# -----------------------------------------------------------------------------
+# Registry: adapter type name -> config class
+# -----------------------------------------------------------------------------
+
+_L2_ADAPTER_CONFIG_REGISTRY: dict[str, type[L2AdapterConfigBase]] = {}
+
+
+def register_l2_adapter_type(
+    name: str,
+    config_cls: type[L2AdapterConfigBase],
+) -> None:
+    """
+    Register an L2 adapter config class under a type name.
+
+    The type name is used in JSON specs as the "type" field.
+    Each adapter config module should call this at import time.
+
+    Args:
+        name: Adapter type name (e.g. "fs", "mock").
+        config_cls: Config class that can parse from dict
+            via ``from_dict()``.
+    """
+    if name in _L2_ADAPTER_CONFIG_REGISTRY:
+        raise ValueError("L2 adapter type already registered: %s" % repr(name))
+    _L2_ADAPTER_CONFIG_REGISTRY[name] = config_cls
+
+
+def _ensure_config_loaded(name: str) -> None:
+    """Trigger lazy import for *name* if it is not
+    yet in the config registry.
+
+    Raises:
+        ImportError: If the adapter module cannot be
+            imported (missing dependency).
+    """
+    if name in _L2_ADAPTER_CONFIG_REGISTRY:
+        return
+    # Lazy import lives in factory to avoid circular deps
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.factory import (  # noqa: PLC0415
+        ensure_adapter_loaded,
+    )
+
+    ensure_adapter_loaded(name)
+
+
+def get_l2_adapter_config_class(type_name: str) -> type["L2AdapterConfigBase"]:
+    """Resolve a registered L2-adapter config class by type name.
+
+    Lazily imports the defining module if needed (via
+    :func:`_ensure_config_loaded`), then returns the registered config class.
+    Public accessor so callers need not reach into the private registry.
+
+    Args:
+        type_name: Registered adapter type (e.g. ``"fs_native"``, ``"mock"``).
+
+    Returns:
+        The :class:`L2AdapterConfigBase` subclass registered under *type_name*.
+
+    Raises:
+        ValueError: If *type_name* is not a registered adapter type.
+    """
+    _ensure_config_loaded(type_name)
+    if type_name not in _L2_ADAPTER_CONFIG_REGISTRY:
+        raise ValueError(f"unknown L2 adapter type {type_name!r}")
+    return _L2_ADAPTER_CONFIG_REGISTRY[type_name]
+
+
+def get_registered_l2_adapter_types() -> list[str]:
+    """Return all known adapter type names (eager
+    and lazy)."""
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.factory import (  # noqa: PLC0415
+        get_all_registered_names,
+    )
+
+    return get_all_registered_names()
+
+
+def get_type_name_for_config(
+    config: L2AdapterConfigBase,
+) -> str:
+    """
+    Reverse-lookup the registered type name for a config
+    instance.
+
+    Args:
+        config: An L2 adapter config instance.
+
+    Returns:
+        The registered type name (e.g., "mock", "fs").
+
+    Raises:
+        ValueError: If the config's class is not registered.
+    """
+    for name, cls in _L2_ADAPTER_CONFIG_REGISTRY.items():
+        if type(config) is cls:
+            return name
+    raise ValueError("Unregistered L2 adapter config type: %s" % type(config).__name__)
+
+
+# -----------------------------------------------------------------------------
+# Base config class for a single L2 adapter
+# -----------------------------------------------------------------------------
+
+
+class L2AdapterConfigBase(ABC):
+    """
+    Base class for per-adapter configs.
+
+    Each adapter type (e.g. disk, redis) defines a config class that:
+    - Subclasses this base.
+    - Implements from_dict() to parse a dict (from JSON) into an instance.
+    - Is registered via register_l2_adapter_type("type_name", ConfigClass).
+
+    An optional ``"eviction"`` key in the JSON dict enables per-adapter L2
+    eviction. When present it is parsed by ``_parse_eviction_config()`` and
+    stored on ``eviction_config``; the L2EvictionController is then created
+    for this adapter in the StorageManager.
+    """
+
+    #: Populated by ``_parse_eviction_config`` after ``from_dict``; ``None``
+    #: means L2 eviction is disabled for this adapter.
+    eviction_config: EvictionConfig | None = None
+
+    #: Populated by ``_parse_persist_config`` after ``from_dict``.
+    #: Defaults to ``PersistConfig()`` (persist enabled).
+    persist_config: PersistConfig = PersistConfig()
+
+    #: Populated by ``_parse_serde_config`` after ``from_dict``; ``None``
+    #: means serde is disabled for this adapter. When set,
+    #: ``StorageManager`` wraps the adapter with
+    #: ``SerdeL2AdapterWrapper`` so controllers see a plain L2 adapter
+    #: and serde runs transparently around store / load.
+    #:
+    #: JSON schema::
+    #:
+    #:     {
+    #:         "type": "<registered_serde_name>",
+    #:         ...type_specific_keys (forwarded to the factory)
+    #:     }
+    #:
+    #: Built-in types and their kwargs:
+    #:   - ``"fp8"`` — see :class:`Fp8QuantizationSerializer`.
+    #:     Accepts ``fp8_dtype`` (torch dtype name, default
+    #:     ``"float8_e4m3fn"``) and ``max_workers`` (thread-pool size
+    #:     for async (de)serialize, default ``1``).
+    serde_config: SerdeConfig | None = None
+
+    @staticmethod
+    def _parse_serde_config(d: dict[str, object]) -> SerdeConfig | None:
+        """Parse an optional ``"serde"`` sub-dict from an adapter JSON spec.
+
+        Expected format::
+
+            {
+                "type": "fs",
+                ...,
+                "serde": {"type": "fp8", "fp8_dtype": "float8_e4m3fn"}
+            }
+
+        Returns ``None`` when the key is absent (serde disabled).
+        """
+        serde_dict = d.get("serde")
+        if serde_dict is None:
+            return None
+        if not isinstance(serde_dict, dict):
+            raise ValueError(f"'serde' must be a dict, got {type(serde_dict).__name__}")
+        serde_type = serde_dict.get("type")
+        if not isinstance(serde_type, str):
+            raise ValueError("'serde' dict must include a 'type' field")
+        # Forward all keys except "type" as type-specific kwargs.
+        kwargs = {k: v for k, v in serde_dict.items() if k != "type"}
+        return SerdeConfig(type=serde_type, kwargs=kwargs)
+
+    @staticmethod
+    def _parse_eviction_config(d: dict) -> EvictionConfig | None:
+        """
+        Parse an optional ``"eviction"`` sub-dict from an adapter JSON spec.
+
+        Expected format::
+
+            {
+                "type": "mock",
+                ...
+                "eviction": {
+                    "eviction_policy": "LRU",
+                    "trigger_watermark": 0.8,
+                    "eviction_ratio": 0.2
+                }
+            }
+
+        Returns ``None`` when the key is absent (eviction disabled).
+        """
+        eviction_dict = d.get("eviction")
+        if eviction_dict is None:
+            return None
+
+        # Lazy import to avoid circular dependency:
+        # l2_adapters/config.py <- config.py <- l2_adapters/config.py
+        # First Party
+        from lmcache.v1.distributed.config import EvictionConfig  # noqa: PLC0415
+
+        policy = eviction_dict.get("eviction_policy")
+        if policy not in ("LRU", "IsolatedLRU", "noop"):
+            raise ValueError(
+                "eviction.eviction_policy must be 'LRU', 'IsolatedLRU', or "
+                f"'noop', got {policy!r}"
+            )
+        return EvictionConfig(
+            eviction_policy=policy,
+            trigger_watermark=float(eviction_dict.get("trigger_watermark", 0.8)),
+            eviction_ratio=float(eviction_dict.get("eviction_ratio", 0.2)),
+        )
+
+    @staticmethod
+    def _parse_persist_config(d: dict) -> PersistConfig:
+        """
+        Parse optional ``"persist_enabled"`` key from an adapter JSON spec.
+
+        Defaults to ``True``.
+
+        Expected format::
+
+            {
+                "type": "nixl_store_dynamic",
+                ...
+                "persist_enabled": true
+            }
+        """
+        persist_enabled = bool(d.get("persist_enabled", True))
+        return PersistConfig(persist_enabled=persist_enabled)
+
+    @staticmethod
+    def _validate_num_workers(raw: object) -> int:
+        """Validate and return a positive integer worker count.
+
+        Raises:
+            ValueError: If ``raw`` is not a positive integer.
+        """
+        if isinstance(raw, bool) or not isinstance(raw, int) or raw <= 0:
+            raise ValueError("num_workers must be a positive integer")
+        return raw
+
+    @staticmethod
+    def _validate_per_op_workers(
+        per_op_workers: dict[str, int] | None,
+    ) -> dict[str, int] | None:
+        """Validate per-operation worker counts (``None`` is a no-op).
+
+        Raises:
+            ValueError: If any worker count is not a positive integer.
+        """
+        if per_op_workers is None:
+            return None
+        for key, value in per_op_workers.items():
+            if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+                raise ValueError(
+                    f"per_op_workers[{key!r}] must be a positive integer, got {value!r}"
+                )
+        return per_op_workers
+
+    @staticmethod
+    def _parse_per_op_workers_from_dict(
+        d: dict[str, object],
+    ) -> dict[str, int] | None:
+        """Parse ``per_op_workers`` from a raw configuration dict.
+
+        Returns ``None`` if the key is absent.
+
+        Raises:
+            ValueError: If the value is not a dict of integers.
+        """
+        raw = d.get("per_op_workers")
+        if raw is None:
+            return None
+        if not isinstance(raw, dict):
+            raise ValueError("per_op_workers must be a dict")
+        per_op_workers: dict[str, int] = {}
+        for k, v in raw.items():
+            if isinstance(v, bool) or not isinstance(v, int):
+                raise ValueError(
+                    f"per_op_workers[{k!r}] must be an integer, got {type(v).__name__}"
+                )
+            per_op_workers[str(k)] = v
+        return per_op_workers
+
+    @classmethod
+    @abstractmethod
+    def from_dict(cls: type[T], d: dict) -> T:
+        """
+        Build a config instance from a dict (e.g. from parsed JSON).
+
+        The dict will contain the "type" key used for dispatch; the concrete
+        class may ignore it. All other keys are type-specific.
+
+        Args:
+            d: Adapter spec dict (must include type-specific keys).
+
+        Returns:
+            An instance of the config class.
+
+        Raises:
+            ValueError: If required keys are missing or values are invalid.
+        """
+        ...
+
+    @classmethod
+    @abstractmethod
+    def help(cls) -> str:
+        """
+        Return a help string describing the config fields for this adapter type.
+
+        This is used in command-line help to explain the expected JSON format for
+        each adapter type.
+
+        Returns:
+            A help string describing the config fields for this adapter type.
+        """
+        ...
+
+
+# -----------------------------------------------------------------------------
+# Main config: list of adapter configs (order = adapter order)
+# -----------------------------------------------------------------------------
+
+
+@dataclass
+class L2AdaptersConfig:
+    """
+    Main config for L2 adapters.
+
+    Holds an ordered list of adapter configs. Each element corresponds to one
+    L2 adapter instance (e.g. two disk adapters with different paths appear
+    as two entries).
+    """
+
+    adapters: list[L2AdapterConfigBase]
+    """ Ordered list of adapter configs; one per L2 adapter instance. """
+
+
+# -----------------------------------------------------------------------------
+# Command-line: add args and parse to config
+# -----------------------------------------------------------------------------
+
+_L2_ADAPTER_ARG_DEST = "l2_adapter"
+
+
+def add_l2_adapters_args(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
+    """
+    Add L2 adapter configuration arguments to an existing parser.
+
+    Adds a repeatable --l2-adapter <JSON> argument. Each JSON object specifies
+    one adapter: it must include "type" (registered adapter type name) and
+    type-specific keys. Order of arguments is the order of adapters.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        The same parser with L2 adapter arguments added.
+
+    Example:
+        >>> parser = argparse.ArgumentParser()
+        >>> add_l2_adapters_args(parser)
+        >>> args = parser.parse_args(["--l2-adapter", '{"type":"disk","path":"/data"}'])
+        >>> config = parse_args_to_l2_adapters_config(args)
+    """
+    group = parser.add_argument_group(
+        "L2 Adapters",
+        "L2 adapter instances. Each --l2-adapter is a JSON object with 'type' and "
+        "type-specific keys. Repeat for multiple adapters.",
+    )
+    group.add_argument(
+        "--l2-adapter",
+        dest=_L2_ADAPTER_ARG_DEST,
+        action="append",
+        default=[],
+        type=str,
+        metavar="JSON",
+        help='Adapter spec as JSON with a "type" field and adapter-specific configs'
+        ', e.g. \'{"type":"disk","path":"/data"}\'.'
+        "Repeat for multiple adapters."
+        "Supported adapters are: ["
+        + ", ".join(sorted(get_registered_l2_adapter_types()))
+        + "].",
+    )
+    return parser
+
+
+def parse_args_to_l2_adapters_config(args: argparse.Namespace) -> L2AdaptersConfig:
+    """
+    Build L2AdaptersConfig from parsed command-line arguments.
+
+    Expects args to have the attribute added by add_l2_adapters_args (a list
+    of JSON strings). Each string is parsed; the "type" field selects the
+    config class from the registry, and from_dict() builds the config instance.
+
+    Args:
+        args: Parsed arguments (e.g. from parser.parse_args()).
+
+    Returns:
+        L2AdaptersConfig with one entry per --l2-adapter argument.
+
+    Raises:
+        KeyError: If an adapter "type" is not registered.
+        ValueError: If JSON is invalid or a config class raises from_dict().
+    """
+    raw_list = getattr(args, _L2_ADAPTER_ARG_DEST, None)
+    if raw_list is None:
+        raw_list = []
+
+    adapter_configs: list[L2AdapterConfigBase] = []
+    for i, raw in enumerate(raw_list):
+        try:
+            d = json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON for --l2-adapter #{i + 1}: {e}") from e
+
+        if not isinstance(d, dict):
+            raise ValueError(
+                f"--l2-adapter #{i + 1}: expected a JSON object, got {type(d).__name__}"
+            )
+
+        type_name = d.get("type")
+        if type_name is None:
+            raise ValueError("--l2-adapter #%d: missing 'type' field" % (i + 1))
+
+        # Trigger lazy import for this adapter type
+        _ensure_config_loaded(type_name)
+
+        if type_name not in _L2_ADAPTER_CONFIG_REGISTRY:
+            known = ", ".join(sorted(_L2_ADAPTER_CONFIG_REGISTRY)) or "(none)"
+            raise ValueError(
+                f"--l2-adapter #{i + 1}: unknown adapter type "
+                f"{type_name!r}. Known: {known}"
+            )
+
+        config_cls = _L2_ADAPTER_CONFIG_REGISTRY[type_name]
+        try:
+            adapter_cfg = config_cls.from_dict(d)
+            adapter_cfg.eviction_config = L2AdapterConfigBase._parse_eviction_config(d)
+            adapter_cfg.persist_config = L2AdapterConfigBase._parse_persist_config(d)
+            adapter_cfg.serde_config = L2AdapterConfigBase._parse_serde_config(d)
+            adapter_configs.append(adapter_cfg)
+        except (TypeError, ValueError) as e:
+            logger.error(
+                "Error parsing --l2-adapter #%d (type %r): %s",
+                i + 1,
+                type_name,
+                e,
+            )
+            logger.error(
+                "Adapter config help for %s adapter:\n"
+                "---------------------\n"
+                "%s\n"
+                "---------------------\n\n",
+                type_name,
+                config_cls.help(),
+            )
+            raise ValueError(f"--l2-adapter #{i + 1} ({type_name!r}): {e}") from e
+
+    return L2AdaptersConfig(adapters=adapter_configs)
diff --git a/lmcache/v1/distributed/l2_adapters/dax_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/dax_l2_adapter.py
new file mode 100644
index 0000000..342667b
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/dax_l2_adapter.py
@@ -0,0 +1,1581 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Literal, Optional, Protocol, cast
+import os
+import threading
+
+if TYPE_CHECKING:
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    AdapterUsage,
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.distributed.l2_adapters.reconfiguration import (
+    L2ReconfigureError,
+    L2ReconfigureStatus,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import create_event_notifier
+from lmcache.v1.storage_backend.dax.core import (
+    DaxCore,
+    DaxPutFromPtrResult,
+    DaxReadReservation,
+)
+
+logger = init_logger(__name__)
+
+DaxDeviceState = Literal[
+    "active",
+    "draining",
+    "migrating",
+    "resizing",
+    "removing",
+    "closed",
+    "failed",
+    "removed",
+]
+HotplugRemoveMode = Literal["migrate", "evict", "drain"]
+HotplugResizeMode = Literal["migrate", "evict"]
+DaxHotplugError = L2ReconfigureError
+_DAX_RECONFIGURE_OPERATIONS = ["status", "add", "remove", "resize"]
+
+_READABLE_STATES: set[DaxDeviceState] = {
+    "active",
+    "draining",
+    "migrating",
+    "resizing",
+}
+_WRITABLE_STATES: set[DaxDeviceState] = {"active"}
+_CAPACITY_STATES: set[DaxDeviceState] = {
+    "active",
+    "draining",
+    "migrating",
+    "resizing",
+    "removing",
+}
+
+
+class _EventNotifier(Protocol):
+    def fileno(self) -> int: ...
+
+    def notify(self) -> None: ...
+
+    def close(self) -> None: ...
+
+
+@dataclass(frozen=True)
+class DaxDeviceConfig:
+    """One configured DAX arena in a DAX L2 adapter."""
+
+    device_path: str
+    max_dax_size_gb: float
+
+    @property
+    def max_dax_size_bytes(self) -> int:
+        """Return this device's configured arena size in bytes."""
+        return int(self.max_dax_size_gb * 1024**3)
+
+
+@dataclass
+class DaxDeviceEntry:
+    """Runtime state for one mapped DAX device."""
+
+    device_id: int
+    device_path: str
+    core: DaxCore[ObjectKey]
+    max_dax_size_bytes: int
+    slot_bytes: int
+    state: DaxDeviceState
+
+
+def _parse_positive_int(value: object, field_name: str) -> int:
+    if not isinstance(value, int) or value <= 0:
+        raise ValueError(f"{field_name} must be a positive integer")
+    return value
+
+
+def _parse_positive_float(value: object, field_name: str) -> float:
+    if not isinstance(value, (int, float)) or value <= 0:
+        raise ValueError(f"{field_name} must be a positive number")
+    return float(value)
+
+
+def _validate_device_path(value: object, field_name: str = "device_path") -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{field_name} must be a non-empty string")
+    return value.strip()
+
+
+def _reconfigure_device_path(payload: dict[str, object]) -> str:
+    try:
+        return _validate_device_path(payload.get("device_path"))
+    except ValueError as exc:
+        raise L2ReconfigureError(400, str(exc)) from exc
+
+
+def _reconfigure_size_bytes(payload: dict[str, object]) -> int:
+    value = payload.get("size_bytes")
+    if isinstance(value, bool):
+        raise L2ReconfigureError(400, "size_bytes must be a positive integer")
+    try:
+        return _parse_positive_int(value, "size_bytes")
+    except ValueError as exc:
+        raise L2ReconfigureError(400, str(exc)) from exc
+
+
+class DaxL2AdapterConfig(L2AdapterConfigBase):
+    """Configuration for the built-in MP Device-DAX L2 adapter."""
+
+    def __init__(
+        self,
+        *,
+        slot_bytes: int,
+        devices: list[DaxDeviceConfig],
+        hotplug_enabled: bool = False,
+        num_store_workers: int = 1,
+        num_lookup_workers: int = 1,
+        num_load_workers: int = min(4, os.cpu_count() or 1),
+    ) -> None:
+        """Initialize a validated DAX L2 adapter config.
+
+        Args:
+            slot_bytes: Fixed slot size for each stored object.
+            devices: Device mappings configured at startup. This may be empty
+                only when hotplug is enabled.
+            hotplug_enabled: Whether runtime add/remove/resize APIs are enabled.
+            num_store_workers: Number of worker threads for store tasks.
+            num_lookup_workers: Number of worker threads for lookup tasks.
+            num_load_workers: Number of worker threads for load tasks.
+        """
+        if not devices and not hotplug_enabled:
+            raise ValueError("devices may be empty only when hotplug_enabled is true")
+
+        self.devices = list(devices)
+        self.device_path = self.devices[0].device_path if self.devices else ""
+        self.max_dax_size_gb = self.devices[0].max_dax_size_gb if self.devices else 0.0
+        self.slot_bytes = slot_bytes
+        self.hotplug_enabled = hotplug_enabled
+        self.num_store_workers = num_store_workers
+        self.num_lookup_workers = num_lookup_workers
+        self.num_load_workers = num_load_workers
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DaxL2AdapterConfig":
+        """Build a DAX L2 adapter config from CLI JSON.
+
+        Args:
+            d: Parsed ``--l2-adapter`` JSON object.
+
+        Returns:
+            A validated ``DaxL2AdapterConfig`` instance.
+
+        Raises:
+            ValueError: If a required field is missing or any numeric field
+                is not positive.
+        """
+        slot_bytes = d.get("slot_bytes")
+        if not isinstance(slot_bytes, int) or slot_bytes <= 0:
+            raise ValueError("slot_bytes must be a positive integer")
+
+        hotplug_enabled = bool(d.get("hotplug_enabled", False))
+
+        devices: list[DaxDeviceConfig]
+        if "devices" in d:
+            raw_devices = d.get("devices")
+            if not isinstance(raw_devices, list):
+                raise ValueError("devices must be a list")
+            devices = []
+            for i, raw_device in enumerate(raw_devices):
+                if not isinstance(raw_device, dict):
+                    raise ValueError(f"devices[{i}] must be a dict")
+                device_path = _validate_device_path(
+                    raw_device.get("device_path"),
+                    f"devices[{i}].device_path",
+                )
+                max_dax_size_gb = _parse_positive_float(
+                    raw_device.get("max_dax_size_gb"),
+                    f"devices[{i}].max_dax_size_gb",
+                )
+                max_dax_size_bytes = int(max_dax_size_gb * 1024**3)
+                if max_dax_size_bytes // slot_bytes <= 0:
+                    raise ValueError(
+                        f"devices[{i}] configured DAX arena does not fit one slot"
+                    )
+                devices.append(
+                    DaxDeviceConfig(
+                        device_path=device_path,
+                        max_dax_size_gb=max_dax_size_gb,
+                    )
+                )
+        else:
+            device_path = _validate_device_path(d.get("device_path"))
+            max_dax_size_gb = _parse_positive_float(
+                d.get("max_dax_size_gb"),
+                "max_dax_size_gb",
+            )
+            max_dax_size_bytes = int(max_dax_size_gb * 1024**3)
+            if max_dax_size_bytes // slot_bytes <= 0:
+                raise ValueError("configured DAX arena does not fit even one slot")
+            devices = [
+                DaxDeviceConfig(
+                    device_path=device_path,
+                    max_dax_size_gb=max_dax_size_gb,
+                )
+            ]
+
+        num_store_workers = _parse_positive_int(
+            d.get("num_store_workers", 1),
+            "num_store_workers",
+        )
+        num_lookup_workers = _parse_positive_int(
+            d.get("num_lookup_workers", 1),
+            "num_lookup_workers",
+        )
+        num_load_workers = _parse_positive_int(
+            d.get("num_load_workers", min(4, os.cpu_count() or 1)),
+            "num_load_workers",
+        )
+
+        return cls(
+            devices=devices,
+            hotplug_enabled=hotplug_enabled,
+            slot_bytes=slot_bytes,
+            num_store_workers=num_store_workers,
+            num_lookup_workers=num_lookup_workers,
+            num_load_workers=num_load_workers,
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        """Return CLI help text for the DAX L2 adapter config.
+
+        Returns:
+            Human-readable field descriptions used by adapter config parsing.
+        """
+        return (
+            "DAX L2 adapter config fields:\n"
+            "- device_path (str): legacy single mmap-able DAX path or file path\n"
+            "- max_dax_size_gb (float): legacy single-device mapped size in GiB\n"
+            "- devices (list): optional multi-device entries with device_path and "
+            "max_dax_size_gb\n"
+            "- hotplug_enabled (bool): enables runtime /reconfigure/dax/* "
+            "management APIs\n"
+            "- slot_bytes (int): fixed slot size in bytes (required, >0)\n"
+            "- num_store_workers (int): store worker threads (optional, default 1)\n"
+            "- num_lookup_workers (int): lookup worker threads (optional, default 1)\n"
+            "- num_load_workers (int): load worker threads "
+            "(optional, default min(4, cpu_count))"
+        )
+
+
+class DaxL2Adapter(L2AdapterInterface):
+    """MP L2 adapter that stores fixed-size objects in DAX mmap arenas."""
+
+    def __init__(self, config: DaxL2AdapterConfig) -> None:
+        """Initialize the DAX adapter and its stable worker pools.
+
+        Args:
+            config: Validated DAX adapter configuration.
+
+        Raises:
+            RuntimeError: If a configured DAX device cannot be opened or mapped.
+            ValueError: If a mapped arena cannot fit at least one slot.
+        """
+        super().__init__(
+            max_capacity_bytes=sum(d.max_dax_size_bytes for d in config.devices)
+        )
+        self._config = config
+
+        self._device_lock = threading.RLock()
+        self._devices: list[DaxDeviceEntry] = []
+        self._next_device_id = 0
+        self._key_to_device: dict[ObjectKey, int] = {}
+        self._hotplug_enabled = config.hotplug_enabled
+
+        # Backward-compatible test/debug handle for the first configured core.
+        self._core: Optional[DaxCore[ObjectKey]] = None
+
+        self._store_efd = cast(_EventNotifier, create_event_notifier())
+        self._lookup_efd = cast(_EventNotifier, create_event_notifier())
+        self._load_efd = cast(_EventNotifier, create_event_notifier())
+
+        self._store_executor: Optional[ThreadPoolExecutor] = None
+        self._lookup_executor: Optional[ThreadPoolExecutor] = None
+        self._load_executor: Optional[ThreadPoolExecutor] = None
+
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+
+        self._lock = threading.Lock()
+        self._closing = False
+        self._closed = False
+        self._inflight_store_tasks = 0
+        self._inflight_lookup_tasks = 0
+        self._inflight_load_tasks = 0
+
+        try:
+            with self._device_lock:
+                for device_config in config.devices:
+                    self._add_device_entry_locked(
+                        device_path=device_config.device_path,
+                        size_bytes=device_config.max_dax_size_bytes,
+                    )
+            self._store_executor = ThreadPoolExecutor(
+                max_workers=config.num_store_workers,
+                thread_name_prefix="dax-l2-store",
+            )
+            self._lookup_executor = ThreadPoolExecutor(
+                max_workers=config.num_lookup_workers,
+                thread_name_prefix="dax-l2-lookup",
+            )
+            self._load_executor = ThreadPoolExecutor(
+                max_workers=config.num_load_workers,
+                thread_name_prefix="dax-l2-load",
+            )
+        except Exception:
+            self.close()
+            raise
+
+    def get_store_event_fd(self) -> int:
+        """Return the pollable fd signaled when store tasks complete.
+
+        Returns:
+            File descriptor owned by this adapter's store notifier.
+        """
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        """Return the pollable fd signaled when lookup tasks complete.
+
+        Returns:
+            File descriptor owned by this adapter's lookup notifier.
+        """
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        """Return the pollable fd signaled when load tasks complete.
+
+        Returns:
+            File descriptor owned by this adapter's load notifier.
+        """
+        return self._load_efd.fileno()
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Submit an asynchronous L1-to-DAX store task.
+
+        Args:
+            keys: Object keys to store.
+            objects: Caller-owned memory objects containing the payloads.
+
+        Returns:
+            Adapter-local task id for the submitted store task.
+
+        Raises:
+            ValueError: If ``keys`` and ``objects`` have different lengths.
+            RuntimeError: If the adapter is closing or already closed.
+        """
+        if len(keys) != len(objects):
+            raise ValueError(
+                "keys and objects must have the same length, "
+                f"got {len(keys)} and {len(objects)}"
+            )
+
+        with self._lock:
+            self._ensure_open_locked()
+            task_id = self._get_next_task_id_locked()
+            self._inflight_store_tasks += 1
+
+        assert self._store_executor is not None
+        self._store_executor.submit(
+            self._execute_store_task,
+            task_id,
+            list(keys),
+            list(objects),
+        )
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        """Drain completed store task results.
+
+        Returns:
+            Mapping from task id to store result. Each task appears at
+            most once; subsequent calls do not return already drained tasks.
+        """
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        """Submit an asynchronous lookup-and-lock task.
+
+        Found keys have their DAX external lock refcount incremented until
+        ``submit_unlock`` is called.
+
+        Args:
+            keys: Object keys to look up.
+
+        Returns:
+            Adapter-local task id for the submitted lookup task.
+
+        Raises:
+            RuntimeError: If the adapter is closing or already closed.
+        """
+        with self._lock:
+            self._ensure_open_locked()
+            task_id = self._get_next_task_id_locked()
+            self._inflight_lookup_tasks += 1
+
+        assert self._lookup_executor is not None
+        self._lookup_executor.submit(self._execute_lookup_task, task_id, list(keys))
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Optional[Bitmap]:
+        """Return and remove a completed lookup result.
+
+        Args:
+            task_id: Adapter-local lookup task id.
+
+        Returns:
+            A bitmap with bits set for keys that were found and locked, or
+            ``None`` if the task is still pending or was already queried.
+        """
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        """Release DAX external locks acquired by lookup tasks.
+
+        Args:
+            keys: Keys whose lock refcount should be decremented.
+        """
+        with self._device_lock:
+            cores = [entry.core for entry in self._devices]
+        for core in cores:
+            core.unlock_many(keys)
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Submit an asynchronous DAX-to-L1 load task.
+
+        Args:
+            keys: Object keys to load.
+            objects: Caller-owned destination buffers. Loaded bytes are
+                written directly into these ``MemoryObj`` instances.
+
+        Returns:
+            Adapter-local task id for the submitted load task.
+
+        Raises:
+            ValueError: If ``keys`` and ``objects`` have different lengths.
+            RuntimeError: If the adapter is closing or already closed.
+        """
+        if len(keys) != len(objects):
+            raise ValueError(
+                "keys and objects must have the same length, "
+                f"got {len(keys)} and {len(objects)}"
+            )
+
+        with self._lock:
+            self._ensure_open_locked()
+            task_id = self._get_next_task_id_locked()
+            self._inflight_load_tasks += 1
+
+        assert self._load_executor is not None
+        self._load_executor.submit(
+            self._execute_load_task,
+            task_id,
+            list(keys),
+            list(objects),
+        )
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Optional[Bitmap]:
+        """Return and remove a completed load result.
+
+        Args:
+            task_id: Adapter-local load task id.
+
+        Returns:
+            A bitmap with bits set for keys that were successfully loaded, or
+            ``None`` if the task is still pending or was already queried.
+        """
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """Delete unlocked keys from every DAX device index.
+
+        Externally locked keys are skipped. Slots borrowed by active reads are
+        reclaimed after the read finalizes.
+
+        Args:
+            keys: Object keys to delete.
+        """
+        if not keys or self._closed:
+            return
+
+        deleted_keys: list[ObjectKey] = []
+        with self._device_lock:
+            for entry in self._devices:
+                deleted = entry.core.delete_many(keys, force=False)
+                for key, ok in zip(keys, deleted, strict=True):
+                    if ok:
+                        self._key_to_device.pop(key, None)
+                        if key not in deleted_keys:
+                            deleted_keys.append(key)
+
+        if deleted_keys:
+            self._notify_keys_deleted(
+                deleted_keys,
+                [self._config.slot_bytes] * len(deleted_keys),
+            )
+
+    def get_usage(self) -> AdapterUsage:
+        """Return slot-based capacity usage for this adapter.
+
+        Returns:
+            Adapter usage where ``total_bytes_used`` is derived from occupied
+            DAX slots rather than payload bytes.
+        """
+        with self._device_lock:
+            total_capacity_bytes = 0
+            total_bytes_used = 0
+            for entry in self._devices:
+                if entry.state not in _CAPACITY_STATES:
+                    continue
+                status = entry.core.report_status()
+                total_capacity_bytes += entry.slot_bytes * int(status["max_slots"])
+                total_bytes_used += entry.slot_bytes * int(status["live_slot_count"])
+
+        base_usage = super().get_usage()
+        return AdapterUsage(
+            total_bytes_used=total_bytes_used,
+            total_capacity_bytes=total_capacity_bytes,
+            bytes_by_cache_salt=MappingProxyType(dict(base_usage.bytes_by_cache_salt)),
+        )
+
+    def close(self) -> None:
+        """Stop worker pools and release DAX resources.
+
+        The call waits for already submitted worker tasks to finish before
+        closing mapped DAX cores and event notifiers.
+        """
+        store_executor = None
+        lookup_executor = None
+        load_executor = None
+
+        with self._lock:
+            if self._closed:
+                return
+            self._closing = True
+            store_executor = self._store_executor
+            lookup_executor = self._lookup_executor
+            load_executor = self._load_executor
+            self._store_executor = None
+            self._lookup_executor = None
+            self._load_executor = None
+
+        if store_executor is not None:
+            store_executor.shutdown(wait=True)
+        if lookup_executor is not None:
+            lookup_executor.shutdown(wait=True)
+        if load_executor is not None:
+            load_executor.shutdown(wait=True)
+
+        with self._device_lock:
+            entries = list(self._devices)
+            for entry in entries:
+                entry.core.close()
+                entry.state = "closed"
+            self._key_to_device.clear()
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+        with self._lock:
+            self._closed = True
+
+    def report_status(self) -> dict:
+        """Return a health and capacity snapshot for this adapter.
+
+        Returns:
+            Dictionary containing health, DAX capacity, slot occupancy,
+            lock/borrow counts, in-flight task counts, and restart-recovery
+            capability.
+        """
+        hotplug = self.hotplug_status()
+        with self._lock:
+            closing = self._closing or self._closed
+
+        devices = hotplug["devices"]
+        return {
+            "is_healthy": all(d["is_healthy"] for d in devices) and not self._closed,
+            "type": "dax",
+            "device_path": self._config.device_path,
+            "max_dax_size_bytes": hotplug["total_capacity_bytes"],
+            "slot_bytes": self._config.slot_bytes,
+            "live_slot_count": sum(int(d["live_slot_count"]) for d in devices),
+            "locked_key_count": sum(int(d["locked_key_count"]) for d in devices),
+            "borrowed_slot_count": sum(int(d["borrowed_slot_count"]) for d in devices),
+            "inflight_store_tasks": self._inflight_store_tasks,
+            "inflight_lookup_tasks": self._inflight_lookup_tasks,
+            "inflight_load_tasks": self._inflight_load_tasks,
+            "closing": closing,
+            "supports_restart_recovery": False,
+            "hotplug_enabled": self._hotplug_enabled,
+            "devices": devices,
+            "num_devices": len(devices),
+        }
+
+    def hotplug_status(self) -> dict:
+        """Return runtime status for this DAX adapter.
+
+        Returns:
+            JSON-serializable status for the stable adapter facade and every
+            mapped DAX device.
+        """
+        with self._device_lock:
+            devices = [
+                self._device_status_locked(index, entry)
+                for index, entry in enumerate(self._devices)
+            ]
+            total_capacity_bytes = sum(
+                int(d["max_slots"]) * int(d["slot_bytes"])
+                for d in devices
+                if d["state"] in _CAPACITY_STATES
+            )
+            total_used_bytes = sum(
+                int(d["live_slot_count"]) * int(d["slot_bytes"])
+                for d in devices
+                if d["state"] in _CAPACITY_STATES
+            )
+            return {
+                "hotplug_enabled": self._hotplug_enabled,
+                "slot_bytes": self._config.slot_bytes,
+                "total_capacity_bytes": total_capacity_bytes,
+                "total_used_bytes": total_used_bytes,
+                "devices": devices,
+            }
+
+    def reconfigure_status(self) -> L2ReconfigureStatus:
+        """Return generic runtime reconfiguration status for this adapter.
+
+        Returns:
+            Standard reconfiguration status with DAX hotplug details nested
+            under ``status``.
+        """
+        return {
+            "backend": "dax",
+            "supported_operations": list(_DAX_RECONFIGURE_OPERATIONS),
+            "status": self.hotplug_status(),
+        }
+
+    def reconfigure(
+        self,
+        operation: str,
+        payload: dict[str, object],
+    ) -> dict:
+        """Apply one generic runtime reconfiguration operation.
+
+        Args:
+            operation: One of ``status``, ``add``, ``remove``, or ``resize``.
+            payload: DAX-specific operation payload.
+
+        Returns:
+            JSON-serializable operation result.
+
+        Raises:
+            L2ReconfigureError: If the operation or payload is invalid, or if the
+                underlying DAX hotplug operation fails.
+        """
+        if operation == "status":
+            return dict(self.reconfigure_status())
+
+        if operation == "add":
+            device_path = _reconfigure_device_path(payload)
+            size_bytes = _reconfigure_size_bytes(payload)
+            return self.hotplug_add_device(device_path, size_bytes)
+
+        if operation == "remove":
+            device_path = _reconfigure_device_path(payload)
+            mode = payload.get("mode", "migrate")
+            if not isinstance(mode, str):
+                raise L2ReconfigureError(400, "mode must be migrate, evict, or drain")
+            force = payload.get("force", False)
+            if not isinstance(force, bool):
+                raise L2ReconfigureError(400, "force must be a boolean")
+            return self.hotplug_remove_device(
+                device_path,
+                cast(HotplugRemoveMode, mode),
+                force,
+            )
+
+        if operation == "resize":
+            device_path = _reconfigure_device_path(payload)
+            size_bytes = _reconfigure_size_bytes(payload)
+            mode = payload.get("mode", "migrate")
+            if not isinstance(mode, str):
+                raise L2ReconfigureError(400, "mode must be migrate or evict")
+            force = payload.get("force", False)
+            if not isinstance(force, bool):
+                raise L2ReconfigureError(400, "force must be a boolean")
+            return self.hotplug_resize_device(
+                device_path,
+                size_bytes,
+                cast(HotplugResizeMode, mode),
+                force,
+            )
+
+        raise L2ReconfigureError(
+            400,
+            f"unsupported DAX reconfigure operation: {operation}",
+        )
+
+    def hotplug_add_device(self, device_path: str, size_bytes: int) -> dict:
+        """Map and activate one additional DAX device.
+
+        Args:
+            device_path: Path to an existing readable and writable DAX device.
+            size_bytes: Number of bytes to map.
+
+        Returns:
+            JSON-serializable operation result.
+
+        Raises:
+            L2ReconfigureError: If hotplug is disabled or the request is invalid.
+        """
+        self._ensure_hotplug_enabled()
+        device_path = device_path.strip()
+        if not device_path:
+            raise L2ReconfigureError(400, "device_path must be non-empty")
+        if size_bytes <= 0:
+            raise L2ReconfigureError(400, "size_bytes must be > 0")
+        if size_bytes // self._config.slot_bytes <= 0:
+            raise L2ReconfigureError(400, "size_bytes does not fit one slot")
+
+        with self._device_lock:
+            for index, entry in enumerate(self._devices):
+                if entry.device_path != device_path or entry.state in {
+                    "closed",
+                    "removed",
+                    "failed",
+                }:
+                    continue
+                if entry.max_dax_size_bytes == size_bytes:
+                    return {
+                        "status": "ok",
+                        "operation": "add",
+                        "adapter_index": 0,
+                        "device": self._device_status_locked(index, entry),
+                    }
+                raise L2ReconfigureError(
+                    409,
+                    "device_path already active with a different size",
+                )
+
+            try:
+                entry = self._add_device_entry_locked(
+                    device_path=device_path,
+                    size_bytes=size_bytes,
+                )
+            except ValueError as exc:
+                logger.exception("Invalid DAX hotplug add request")
+                raise L2ReconfigureError(
+                    400,
+                    "invalid DAX hotplug add request",
+                ) from exc
+            except RuntimeError as exc:
+                logger.exception("Failed to map DAX hotplug device")
+                raise L2ReconfigureError(400, "failed to map DAX device") from exc
+
+            index = self._devices.index(entry)
+            return {
+                "status": "ok",
+                "operation": "add",
+                "adapter_index": 0,
+                "device": self._device_status_locked(index, entry),
+            }
+
+    def hotplug_remove_device(
+        self,
+        device_path: str,
+        mode: HotplugRemoveMode,
+        force: bool = False,
+    ) -> dict:
+        """Remove or drain a DAX device.
+
+        Args:
+            device_path: Device path to remove.
+            mode: ``migrate`` preserves KV on another device, ``evict`` deletes
+                DAX-resident entries, and ``drain`` only stops new writes.
+            force: Whether destructive delete may remove locked entries.
+
+        Returns:
+            JSON-serializable operation result.
+
+        Raises:
+            L2ReconfigureError: If the request is invalid, blocked, or lacks
+                destination capacity.
+        """
+        self._ensure_hotplug_enabled()
+        self._validate_remove_mode(mode)
+
+        with self._device_lock:
+            source_index, source = self._get_device_for_path_locked(device_path)
+            if mode == "drain":
+                source.state = "draining"
+                return {
+                    "status": "ok",
+                    "operation": "drain",
+                    "adapter_index": 0,
+                    "device_path": source.device_path,
+                    "index": source_index,
+                    "state": source.state,
+                }
+
+            old_state = source.state
+            source.state = "draining"
+            try:
+                blocked = self._blocked_payload_locked(source)
+                if blocked is not None and not force:
+                    raise L2ReconfigureError(
+                        409,
+                        "device has locked or borrowed slots",
+                        payload=blocked,
+                    )
+
+                keys = source.core.snapshot_keys()
+                if mode == "migrate":
+                    self._assert_no_destination_duplicates_locked(source, keys)
+                    moved_keys, moved_bytes = self._migrate_keys_locked(source, keys)
+                    self._delete_source_keys_after_migration_locked(
+                        source,
+                        moved_keys,
+                        force,
+                    )
+                    deleted_keys = []
+                    source_slots_freed = len(moved_keys)
+                else:
+                    deleted_keys = self._evict_keys_locked(source, keys, force=force)
+                    moved_keys = []
+                    moved_bytes = 0
+                    source_slots_freed = len(deleted_keys)
+                    if deleted_keys:
+                        self._notify_keys_deleted(
+                            deleted_keys,
+                            [self._config.slot_bytes] * len(deleted_keys),
+                        )
+
+                source.state = "removing"
+                source.core.close()
+                source.state = "removed"
+                self._recalculate_capacity_locked()
+            except Exception:
+                if source.state not in {"closed", "removed"}:
+                    source.state = old_state
+                raise
+
+            return {
+                "status": "ok",
+                "operation": "remove",
+                "adapter_index": 0,
+                "device_path": source.device_path,
+                "index": source_index,
+                "moved_keys": len(moved_keys),
+                "moved_bytes": moved_bytes,
+                "deleted_keys": len(deleted_keys),
+                "source_slots_freed": source_slots_freed,
+                "state": "removed",
+            }
+
+    def hotplug_resize_device(
+        self,
+        device_path: str,
+        size_bytes: int,
+        mode: HotplugResizeMode,
+        force: bool = False,
+    ) -> dict:
+        """Resize a mapped DAX device.
+
+        Args:
+            device_path: Device path to resize.
+            size_bytes: New mapped byte size.
+            mode: Migration behavior for shrink operations.
+            force: Whether destructive shrink may evict out-of-range entries.
+
+        Returns:
+            JSON-serializable operation result.
+
+        Raises:
+            L2ReconfigureError: If the request is invalid, blocked, or lacks
+                destination capacity.
+        """
+        self._ensure_hotplug_enabled()
+        self._validate_resize_mode(mode)
+        if size_bytes <= 0:
+            raise L2ReconfigureError(400, "size_bytes must be > 0")
+        new_max_slots = size_bytes // self._config.slot_bytes
+        if new_max_slots <= 0:
+            raise L2ReconfigureError(400, "size_bytes does not fit one slot")
+
+        with self._device_lock:
+            device_index, entry = self._get_device_for_path_locked(device_path)
+            old_size_bytes = entry.max_dax_size_bytes
+            if old_size_bytes == size_bytes:
+                return {
+                    "status": "ok",
+                    "operation": "resize",
+                    "adapter_index": 0,
+                    "device_path": entry.device_path,
+                    "index": device_index,
+                    "old_size_bytes": old_size_bytes,
+                    "new_size_bytes": size_bytes,
+                    "state": entry.state,
+                }
+
+            old_state = entry.state
+            entry.state = "resizing"
+            try:
+                if size_bytes > old_size_bytes:
+                    entry.core.remap(size_bytes)
+                else:
+                    self._shrink_device_locked(entry, new_max_slots, mode, force)
+                    entry.core.remap(size_bytes)
+                entry.max_dax_size_bytes = size_bytes
+                entry.state = "active" if old_state == "active" else old_state
+                self._recalculate_capacity_locked()
+            except L2ReconfigureError:
+                entry.state = old_state
+                raise
+            except ValueError as exc:
+                entry.state = old_state
+                logger.exception("Invalid DAX hotplug resize request")
+                raise L2ReconfigureError(
+                    409,
+                    "invalid DAX hotplug resize request",
+                ) from exc
+            except RuntimeError as exc:
+                entry.state = old_state
+                logger.exception("Failed to remap DAX hotplug device")
+                raise L2ReconfigureError(400, "failed to remap DAX device") from exc
+
+            return {
+                "status": "ok",
+                "operation": "resize",
+                "adapter_index": 0,
+                "device_path": entry.device_path,
+                "index": device_index,
+                "old_size_bytes": old_size_bytes,
+                "new_size_bytes": size_bytes,
+                "state": entry.state,
+            }
+
+    def _ensure_open_locked(self) -> None:
+        if self._closing or self._closed:
+            raise RuntimeError("DaxL2Adapter is closing")
+
+    def _get_next_task_id_locked(self) -> L2TaskId:
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    def _signal_eventfd(self, notifier: _EventNotifier) -> None:
+        try:
+            notifier.notify()
+        except OSError:
+            logger.debug("Skipping eventfd write during adapter shutdown")
+
+    def _execute_store_task(
+        self,
+        task_id: L2TaskId,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> None:
+        per_key_results: list[bool] = []
+        stored_keys: list[ObjectKey] = []
+
+        try:
+            for key, obj in zip(keys, objects, strict=True):
+                try:
+                    with self._device_lock:
+                        ok = self._store_one_locked(key, obj)
+                except Exception:
+                    logger.exception("DAX L2 store failed for key %s", key)
+                    ok = False
+                per_key_results.append(ok)
+                if ok:
+                    stored_keys.append(key)
+        finally:
+            bytes_transferred = self._config.slot_bytes * len(stored_keys)
+            with self._lock:
+                self._completed_store_tasks[task_id] = L2StoreResult(
+                    all(per_key_results), bytes_transferred
+                )
+                self._inflight_store_tasks -= 1
+
+            if stored_keys:
+                self._notify_keys_stored(
+                    stored_keys,
+                    [self._config.slot_bytes] * len(stored_keys),
+                )
+            self._signal_eventfd(self._store_efd)
+
+    def _execute_lookup_task(
+        self,
+        task_id: L2TaskId,
+        keys: list[ObjectKey],
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        try:
+            with self._device_lock:
+                remaining_indices: list[int] = []
+                skip_device_by_index: dict[int, int] = {}
+                mapped_indices_by_device: dict[int, list[int]] = {}
+
+                for i, key in enumerate(keys):
+                    mapped_entry = self._get_mapped_device_locked(key)
+                    if (
+                        mapped_entry is not None
+                        and mapped_entry.state in _READABLE_STATES
+                    ):
+                        mapped_indices_by_device.setdefault(
+                            mapped_entry.device_id,
+                            [],
+                        ).append(i)
+                    else:
+                        remaining_indices.append(i)
+
+                readable_entries = [
+                    entry for entry in self._devices if entry.state in _READABLE_STATES
+                ]
+                entry_by_id = {entry.device_id: entry for entry in readable_entries}
+
+                for device_id, indices in mapped_indices_by_device.items():
+                    entry = entry_by_id.get(device_id)
+                    if entry is None:
+                        remaining_indices.extend(indices)
+                        continue
+
+                    hits = entry.core.exists_many([keys[i] for i in indices], lock=True)
+                    for i, hit in zip(indices, hits, strict=True):
+                        if hit:
+                            bitmap.set(i)
+                            self._key_to_device[keys[i]] = entry.device_id
+                        else:
+                            self._key_to_device.pop(keys[i], None)
+                            skip_device_by_index[i] = entry.device_id
+                            remaining_indices.append(i)
+
+                for entry in readable_entries:
+                    indices = [
+                        i
+                        for i in remaining_indices
+                        if not bitmap.test(i)
+                        and skip_device_by_index.get(i) != entry.device_id
+                    ]
+                    if not indices:
+                        continue
+
+                    hits = entry.core.exists_many([keys[i] for i in indices], lock=True)
+                    for i, hit in zip(indices, hits, strict=True):
+                        if hit:
+                            bitmap.set(i)
+                            self._key_to_device[keys[i]] = entry.device_id
+        except Exception:
+            logger.exception("DAX L2 lookup failed")
+        finally:
+            with self._lock:
+                self._completed_lookup_tasks[task_id] = bitmap
+                self._inflight_lookup_tasks -= 1
+            self._signal_eventfd(self._lookup_efd)
+
+    def _execute_load_task(
+        self,
+        task_id: L2TaskId,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        loaded_keys: list[ObjectKey] = []
+
+        try:
+            with self._device_lock:
+                for i, (key, obj) in enumerate(zip(keys, objects, strict=True)):
+                    entry = self._find_device_for_key_locked(key, lock=False)
+                    if entry is None:
+                        continue
+                    loaded = entry.core.load_many_into([key], [obj])[0]
+                    if loaded:
+                        bitmap.set(i)
+                        loaded_keys.append(key)
+        except Exception:
+            logger.exception("DAX L2 load failed")
+        finally:
+            with self._lock:
+                self._completed_load_tasks[task_id] = bitmap
+                self._inflight_load_tasks -= 1
+
+            if loaded_keys:
+                self._notify_keys_accessed(loaded_keys)
+            self._signal_eventfd(self._load_efd)
+
+    def _store_one_locked(self, key: ObjectKey, obj: MemoryObj) -> bool:
+        mapped_entry = self._get_mapped_device_locked(key)
+        if mapped_entry is not None and mapped_entry.state in _WRITABLE_STATES:
+            ok = mapped_entry.core.put_many([key], [obj])[0]
+            if ok:
+                self._key_to_device[key] = mapped_entry.device_id
+                return True
+
+        for entry in self._writable_devices_by_usage_locked(exclude_device_id=None):
+            if entry is mapped_entry:
+                continue
+            ok = entry.core.put_many([key], [obj])[0]
+            if ok:
+                self._key_to_device[key] = entry.device_id
+                return True
+        return False
+
+    def _find_device_for_key_locked(
+        self,
+        key: ObjectKey,
+        *,
+        lock: bool,
+    ) -> Optional[DaxDeviceEntry]:
+        mapped_entry = self._get_mapped_device_locked(key)
+        if mapped_entry is not None and mapped_entry.state in _READABLE_STATES:
+            if mapped_entry.core.exists_many([key], lock=lock)[0]:
+                return mapped_entry
+            self._key_to_device.pop(key, None)
+
+        for entry in self._devices:
+            if entry is mapped_entry or entry.state not in _READABLE_STATES:
+                continue
+            if entry.core.exists_many([key], lock=lock)[0]:
+                self._key_to_device[key] = entry.device_id
+                return entry
+        return None
+
+    def _get_mapped_device_locked(self, key: ObjectKey) -> Optional[DaxDeviceEntry]:
+        device_id = self._key_to_device.get(key)
+        if device_id is None:
+            return None
+        for entry in self._devices:
+            if entry.device_id == device_id:
+                return entry
+        self._key_to_device.pop(key, None)
+        return None
+
+    def _writable_devices_by_usage_locked(
+        self,
+        *,
+        exclude_device_id: Optional[int],
+    ) -> list[DaxDeviceEntry]:
+        devices = [
+            entry
+            for entry in self._devices
+            if entry.state in _WRITABLE_STATES and entry.device_id != exclude_device_id
+        ]
+        return sorted(devices, key=self._device_usage_ratio_locked)
+
+    def _device_usage_ratio_locked(self, entry: DaxDeviceEntry) -> float:
+        status = entry.core.report_status()
+        max_slots = int(status["max_slots"])
+        if max_slots <= 0:
+            return 1.0
+        return int(status["live_slot_count"]) / max_slots
+
+    def _add_device_entry_locked(
+        self,
+        *,
+        device_path: str,
+        size_bytes: int,
+    ) -> DaxDeviceEntry:
+        core = DaxCore[ObjectKey](
+            device_path=device_path,
+            max_dax_size_bytes=size_bytes,
+            slot_bytes=self._config.slot_bytes,
+        )
+        entry = DaxDeviceEntry(
+            device_id=self._next_device_id,
+            device_path=device_path,
+            core=core,
+            max_dax_size_bytes=size_bytes,
+            slot_bytes=self._config.slot_bytes,
+            state="active",
+        )
+        self._next_device_id += 1
+        self._devices.append(entry)
+        if self._core is None:
+            self._core = core
+        self._recalculate_capacity_locked()
+        return entry
+
+    def _device_status_locked(self, index: int, entry: DaxDeviceEntry) -> dict:
+        status = entry.core.report_status()
+        with self._lock:
+            inflight_store = self._inflight_store_tasks
+            inflight_lookup = self._inflight_lookup_tasks
+            inflight_load = self._inflight_load_tasks
+        return {
+            **status,
+            "index": index,
+            "device_id": entry.device_id,
+            "device_path": entry.device_path,
+            "state": entry.state,
+            "max_dax_size_bytes": entry.max_dax_size_bytes,
+            "slot_bytes": entry.slot_bytes,
+            "inflight_store_tasks": inflight_store,
+            "inflight_lookup_tasks": inflight_lookup,
+            "inflight_load_tasks": inflight_load,
+            "supports_restart_recovery": False,
+        }
+
+    def _get_device_for_path_locked(
+        self,
+        device_path: str,
+    ) -> tuple[int, DaxDeviceEntry]:
+        normalized_path = device_path.strip()
+        if not normalized_path:
+            raise L2ReconfigureError(400, "device_path must be non-empty")
+
+        matches: list[tuple[int, DaxDeviceEntry]] = []
+        for index, entry in enumerate(self._devices):
+            if entry.device_path != normalized_path:
+                continue
+            if entry.state in {"closed", "removed", "failed"}:
+                continue
+            matches.append((index, entry))
+
+        if len(matches) > 1:
+            raise L2ReconfigureError(
+                409,
+                "multiple active DAX devices have the same device_path",
+                payload={
+                    "error": "multiple active DAX devices have the same device_path",
+                    "device_path": normalized_path,
+                    "matches": [
+                        {
+                            "index": index,
+                            "device_id": entry.device_id,
+                            "state": entry.state,
+                        }
+                        for index, entry in matches
+                    ],
+                },
+            )
+
+        if matches:
+            return matches[0]
+
+        raise L2ReconfigureError(404, "DAX device not found")
+
+    def _blocked_payload_locked(
+        self,
+        entry: DaxDeviceEntry,
+    ) -> Optional[dict[str, object]]:
+        status = entry.core.report_status()
+        locked_key_count = int(status["locked_key_count"])
+        borrowed_slot_count = int(status["borrowed_slot_count"])
+        if locked_key_count == 0 and borrowed_slot_count == 0:
+            return None
+        return {
+            "status": "blocked",
+            "reason": "device has externally locked or borrowed slots",
+            "locked_key_count": locked_key_count,
+            "borrowed_slot_count": borrowed_slot_count,
+        }
+
+    def _migrate_keys_locked(
+        self,
+        source: DaxDeviceEntry,
+        keys: list[ObjectKey],
+    ) -> tuple[list[ObjectKey], int]:
+        if not keys:
+            return [], 0
+
+        if not self._writable_devices_by_usage_locked(
+            exclude_device_id=source.device_id
+        ):
+            raise L2ReconfigureError(507, "no active destination DAX capacity")
+
+        reservations = source.core.reserve_reads_for_keys(keys)
+        moved_keys: list[ObjectKey] = []
+        moved_bytes = 0
+        touched_keys: set[ObjectKey] = set()
+        try:
+            for reservation in reservations:
+                if self._copy_reservation_to_target_locked(source, reservation):
+                    moved_keys.append(reservation.key)
+                    moved_bytes += reservation.size
+                    touched_keys.add(reservation.key)
+        finally:
+            source.core.finalize_reads(reservations, touched_keys)
+
+        if len(moved_keys) != len(keys):
+            raise L2ReconfigureError(507, "insufficient destination DAX capacity")
+        return moved_keys, moved_bytes
+
+    def _assert_no_destination_duplicates_locked(
+        self,
+        source: DaxDeviceEntry,
+        keys: list[ObjectKey],
+    ) -> None:
+        if not keys:
+            return
+
+        key_set = set(keys)
+        for entry in self._devices:
+            if entry is source or entry.state != "active":
+                continue
+
+            duplicates = key_set.intersection(entry.core.snapshot_keys())
+            if not duplicates:
+                continue
+
+            sample = list(duplicates)[:8]
+            raise L2ReconfigureError(
+                409,
+                "migration target already contains source keys",
+                payload={
+                    "error": "migration target already contains source keys",
+                    "device_path": entry.device_path,
+                    "device_id": entry.device_id,
+                    "duplicate_count": len(duplicates),
+                    "sample_keys": [str(key) for key in sample],
+                },
+            )
+
+    def _copy_reservation_to_target_locked(
+        self,
+        source: DaxDeviceEntry,
+        reservation: DaxReadReservation[ObjectKey],
+    ) -> bool:
+        for target in self._writable_devices_by_usage_locked(
+            exclude_device_id=source.device_id
+        ):
+            result = target.core.put_reserved_from_ptr(
+                reservation.key,
+                source.core.base_ptr + reservation.offset,
+                reservation.size,
+                reservation.shape,
+                reservation.dtype,
+                reservation.fmt,
+                reservation.cached_positions,
+            )
+            if result is DaxPutFromPtrResult.INSERTED:
+                self._key_to_device[reservation.key] = target.device_id
+                return True
+            if result in {
+                DaxPutFromPtrResult.ALREADY_EXISTS,
+                DaxPutFromPtrResult.INFLIGHT,
+            }:
+                raise L2ReconfigureError(
+                    409,
+                    "migration destination already contains key",
+                    payload={
+                        "error": "migration destination already contains key",
+                        "key": str(reservation.key),
+                        "device_path": target.device_path,
+                        "result": result.name,
+                    },
+                )
+            if result is not DaxPutFromPtrResult.NO_SPACE:
+                raise L2ReconfigureError(
+                    409,
+                    "migration destination copy failed",
+                    payload={
+                        "error": "migration destination copy failed",
+                        "key": str(reservation.key),
+                        "device_path": target.device_path,
+                        "result": result.name,
+                    },
+                )
+        return False
+
+    def _delete_source_keys_after_migration_locked(
+        self,
+        source: DaxDeviceEntry,
+        keys: list[ObjectKey],
+        force: bool,
+    ) -> None:
+        deleted = source.core.delete_many(keys, force=force)
+        failed = [key for key, ok in zip(keys, deleted, strict=True) if not ok]
+        if failed:
+            raise L2ReconfigureError(
+                409,
+                "source device still has locked migrated keys",
+                payload={
+                    "status": "blocked",
+                    "reason": "source device still has locked migrated keys",
+                    "locked_key_count": len(failed),
+                    "borrowed_slot_count": 0,
+                },
+            )
+
+    def _evict_keys_locked(
+        self,
+        source: DaxDeviceEntry,
+        keys: list[ObjectKey],
+        *,
+        force: bool,
+    ) -> list[ObjectKey]:
+        deleted = source.core.delete_many(keys, force=force)
+        deleted_keys: list[ObjectKey] = []
+        failed_keys: list[ObjectKey] = []
+        for key, ok in zip(keys, deleted, strict=True):
+            if ok:
+                deleted_keys.append(key)
+                if self._key_to_device.get(key) == source.device_id:
+                    self._key_to_device.pop(key, None)
+            else:
+                failed_keys.append(key)
+
+        if failed_keys:
+            raise L2ReconfigureError(
+                409,
+                "device has externally locked or borrowed slots",
+                payload={
+                    "status": "blocked",
+                    "reason": "device has externally locked or borrowed slots",
+                    "locked_key_count": len(failed_keys),
+                    "borrowed_slot_count": 0,
+                },
+            )
+        return deleted_keys
+
+    def _shrink_device_locked(
+        self,
+        entry: DaxDeviceEntry,
+        new_max_slots: int,
+        mode: HotplugResizeMode,
+        force: bool,
+    ) -> None:
+        blocked = self._blocked_payload_locked(entry)
+        if blocked is not None and not force:
+            raise L2ReconfigureError(
+                409,
+                "device has locked or borrowed slots",
+                payload=blocked,
+            )
+        if entry.core.can_shrink_to(new_max_slots):
+            return
+        keys = entry.core.snapshot_keys()
+        reservations = entry.core.reserve_reads_for_keys(keys)
+        high_reservations = [
+            reservation
+            for reservation in reservations
+            if reservation.slot_id >= new_max_slots
+        ]
+        touched_keys: set[ObjectKey] = set()
+        try:
+            if mode == "migrate":
+                if high_reservations and not self._writable_devices_by_usage_locked(
+                    exclude_device_id=entry.device_id
+                ):
+                    raise L2ReconfigureError(507, "no active destination DAX capacity")
+                self._assert_no_destination_duplicates_locked(
+                    entry,
+                    [reservation.key for reservation in high_reservations],
+                )
+                moved_keys: list[ObjectKey] = []
+                for reservation in high_reservations:
+                    if not self._copy_reservation_to_target_locked(entry, reservation):
+                        raise L2ReconfigureError(
+                            507,
+                            "insufficient destination DAX capacity",
+                        )
+                    moved_keys.append(reservation.key)
+                    touched_keys.add(reservation.key)
+                self._delete_source_keys_after_migration_locked(
+                    entry,
+                    moved_keys,
+                    force,
+                )
+            elif mode == "evict" and force:
+                high_keys = [reservation.key for reservation in high_reservations]
+                deleted_keys = self._evict_keys_locked(entry, high_keys, force=True)
+                if deleted_keys:
+                    self._notify_keys_deleted(
+                        deleted_keys,
+                        [self._config.slot_bytes] * len(deleted_keys),
+                    )
+            else:
+                raise L2ReconfigureError(
+                    409,
+                    "resize shrink would drop live keys without migration",
+                )
+        finally:
+            entry.core.finalize_reads(reservations, touched_keys)
+
+        if not entry.core.can_shrink_to(new_max_slots):
+            raise L2ReconfigureError(409, "resize shrink still has live high slots")
+
+    def _recalculate_capacity_locked(self) -> None:
+        self._max_capacity_bytes = sum(
+            entry.max_dax_size_bytes
+            for entry in self._devices
+            if entry.state in _CAPACITY_STATES
+        )
+
+    def _ensure_hotplug_enabled(self) -> None:
+        if not self._hotplug_enabled:
+            raise L2ReconfigureError(403, "DAX hotplug is disabled")
+
+    @staticmethod
+    def _validate_remove_mode(mode: str) -> None:
+        if mode not in {"migrate", "evict", "drain"}:
+            raise L2ReconfigureError(400, "mode must be migrate, evict, or drain")
+
+    @staticmethod
+    def _validate_resize_mode(mode: str) -> None:
+        if mode not in {"migrate", "evict"}:
+            raise L2ReconfigureError(400, "mode must be migrate or evict")
+
+
+register_l2_adapter_type("dax", DaxL2AdapterConfig)
+
+
+def _create_dax_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    del l1_memory_desc
+    return DaxL2Adapter(config)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("dax", _create_dax_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/factory.py b/lmcache/v1/distributed/l2_adapters/factory.py
new file mode 100644
index 0000000..954b091
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/factory.py
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Factory registry for L2 adapters.
+
+Each adapter module self-registers a factory callable via
+``register_l2_adapter_factory`` at import time.  The factory
+signature is
+``(L2AdapterConfigBase, Optional[L1MemoryDesc]) -> L2AdapterInterface``.
+
+Built-in adapters are discovered via ``pkgutil`` but only
+imported on demand -- their modules (and third-party
+dependencies) are loaded only when the adapter type is
+actually requested.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Callable, Optional
+import importlib
+
+if TYPE_CHECKING:
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+    from lmcache.v1.distributed.l2_adapters.base import (
+        L2AdapterInterface,
+    )
+    from lmcache.v1.distributed.l2_adapters.config import (
+        L2AdapterConfigBase,
+    )
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# Type alias for factory callables:
+#   (config, l1_memory_desc) -> L2AdapterInterface
+L2AdapterFactory = Callable[
+    ["L2AdapterConfigBase", "Optional[L1MemoryDesc]"],
+    "L2AdapterInterface",
+]
+
+# -----------------------------------------------------------------
+# Registry: adapter type name -> factory callable
+# -----------------------------------------------------------------
+
+_L2_ADAPTER_FACTORY_REGISTRY: dict[str, L2AdapterFactory] = {}
+
+# -----------------------------------------------------------------
+# Pending modules: fully-qualified module paths that have
+# been discovered (e.g. via pkgutil) but not yet imported.
+# When a type name is not found in the eager registry we
+# import these one-by-one until the name appears.
+# -----------------------------------------------------------------
+
+_PENDING_MODULES: list[str] = []
+
+
+def register_l2_adapter_factory(
+    name: str,
+    factory: L2AdapterFactory,
+) -> None:
+    """Register an adapter factory for the given type
+    name.
+
+    Each adapter module should call this at import time
+    **after** its config class has been registered via
+    ``register_l2_adapter_type``.
+
+    Args:
+        name: Adapter type name (must match the name used
+            in ``register_l2_adapter_type``).
+        factory: ``(config, l1_memory_desc)``
+            -> ``L2AdapterInterface``.
+    """
+    if name in _L2_ADAPTER_FACTORY_REGISTRY:
+        raise ValueError("L2 adapter factory already registered: %s" % name)
+    _L2_ADAPTER_FACTORY_REGISTRY[name] = factory
+
+
+def add_pending_module(module_path: str) -> None:
+    """Register a module path for deferred import.
+
+    The module will only be imported when a type name
+    lookup misses the eager registry.  Importing the
+    module triggers its ``register_l2_adapter_type``
+    and ``register_l2_adapter_factory`` calls.
+
+    Args:
+        module_path: Fully-qualified module path
+            (e.g. ``"lmcache.v1.distributed.
+            l2_adapters.fs_l2_adapter"``).
+    """
+    if module_path not in _PENDING_MODULES:
+        _PENDING_MODULES.append(module_path)
+
+
+def ensure_adapter_loaded(name: str) -> None:
+    """Import pending modules until *name* appears in
+    the factory registry (or all pending modules have
+    been tried).
+
+    Raises:
+        ImportError: If a module fails to import due to
+            a missing third-party dependency **and** it
+            was the last candidate.
+    """
+    if name in _L2_ADAPTER_FACTORY_REGISTRY:
+        return
+
+    last_err: ImportError | None = None
+    while _PENDING_MODULES:
+        mod_path = _PENDING_MODULES.pop(0)
+        try:
+            importlib.import_module(mod_path)
+        except ImportError as exc:
+            logger.debug(
+                "Skipping module %s (import failed: %s)",
+                mod_path,
+                exc,
+            )
+            last_err = exc
+            continue
+        # Check if the name is now registered
+        if name in _L2_ADAPTER_FACTORY_REGISTRY:
+            return
+
+    # If we exhausted all pending modules and still
+    # didn't find the name, the last ImportError (if
+    # any) might be the root cause.
+    if last_err is not None and name not in _L2_ADAPTER_FACTORY_REGISTRY:
+        raise last_err
+
+
+def load_all_adapters() -> None:
+    """Force-import all pending adapter modules.
+
+    Useful for CLI help that needs to list every
+    registered type name.
+    """
+    while _PENDING_MODULES:
+        mod_path = _PENDING_MODULES.pop(0)
+        try:
+            importlib.import_module(mod_path)
+        except ImportError:
+            logger.debug(
+                "Skipping module %s during bulk load",
+                mod_path,
+            )
+
+
+def get_all_registered_names() -> list[str]:
+    """Return all known adapter type names.
+
+    Forces import of all pending modules so that the
+    returned list is complete.
+    """
+    load_all_adapters()
+    return sorted(_L2_ADAPTER_FACTORY_REGISTRY)
+
+
+def create_l2_adapter_from_registry(
+    config: "L2AdapterConfigBase",
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> "L2AdapterInterface":
+    """Create an L2 adapter using the factory registry.
+
+    Looks up the type name for *config* via the config
+    registry, then calls the matching factory.
+
+    Args:
+        config: An adapter config instance.
+        l1_memory_desc: Optional L1 memory descriptor,
+            required by adapters that register L1 memory
+            with an external backend (e.g. Nixl).
+
+    Returns:
+        A new ``L2AdapterInterface`` instance.
+
+    Raises:
+        ValueError: If no factory is registered for this
+            config type.
+    """
+    # Import here to avoid circular dependency
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.config import (
+        get_type_name_for_config,
+    )
+
+    name = get_type_name_for_config(config)
+
+    # Trigger lazy import if needed
+    ensure_adapter_loaded(name)
+
+    factory = _L2_ADAPTER_FACTORY_REGISTRY.get(name)
+    if factory is None:
+        raise ValueError(
+            "No adapter factory registered for type "
+            "%s. Make sure the adapter module is "
+            "imported." % name
+        )
+    return factory(config, l1_memory_desc)
diff --git a/lmcache/v1/distributed/l2_adapters/fault_inject_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/fault_inject_l2_adapter.py
new file mode 100644
index 0000000..f106718
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/fault_inject_l2_adapter.py
@@ -0,0 +1,464 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Fault-injecting L2 adapter (test/diagnostic only).
+
+Wraps a real inner L2 adapter (e.g. ``fs_native``) and deterministically
+drops keys to simulate partial L2 retrieve failures, exercising the
+segmented code paths (gapped found-set -> segmented prefetch ->
+segmented scatter/attention) that real caches never produce.
+
+Faults the load read primitive only: a dropped key is reported present
+at lookup but its load fails (the faithful "L2 retrieve error"; the
+prefetch controller releases the load-failed locks via the trim mask).
+The lookup-miss case is intentionally not modeled -- a key absent at
+lookup merely shortens the found-set, which the PREFIX trim policy
+(count_leading_ones) already covers. The drop-set is a stable hash of
+the key bucketed by ``rate``, plus optional ``gap_indices`` for precise
+single-gap repros.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import hashlib
+import threading
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.native_storage_ops import Bitmap
+    from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+    from lmcache.v1.distributed.internal_api import L2AdapterListener, L2StoreResult
+    from lmcache.v1.memory_management import MemoryObj
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.base import (
+    AdapterUsage,
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+
+logger = init_logger(__name__)
+
+_HASH_DENOM = 1_000_000
+
+
+# -----------------------------------------------------------------------------
+# Config
+# -----------------------------------------------------------------------------
+
+
+class FaultInjectL2AdapterConfig(L2AdapterConfigBase):
+    """Config for the fault-injecting L2 adapter.
+
+    JSON fields:
+    - inner (dict, required): full adapter spec for the wrapped adapter, with
+      its own "type" (e.g. {"type": "fs_native", "base_path": "/dev/shm/x"}).
+    - rate (float): per-key drop probability in [0, 1]. Default 0.0 (pass-through).
+    - seed (int): seed for the deterministic per-key hash. Default 0.
+    - gap_indices (list[int]): exact task-positions (from the head) to always
+      drop. Default [] -- mainly for precise unit tests.
+    - gap_tail_ratios (list[float]): positions to always drop, given as the
+      distance-from-the-tail as a FRACTION of the load length, so the rule is
+      workload-agnostic (the server needs no advance knowledge of the content).
+      The dropped chunk index = round((1 - ratio) * (n - 1)) over the n-key load
+      batch: 0.0 = last chunk, 0.5 = middle, 1.0 = first. Self-scaling across
+      context lengths; a stable mid-prefix gap for the segmented repro. Default [].
+    """
+
+    def __init__(
+        self,
+        inner_config: L2AdapterConfigBase,
+        rate: float,
+        seed: int,
+        gap_indices: tuple[int, ...],
+        gap_tail_ratios: tuple[float, ...] = (),
+    ) -> None:
+        self.inner_config = inner_config
+        self.rate = rate
+        self.seed = seed
+        self.gap_indices = gap_indices
+        self.gap_tail_ratios = gap_tail_ratios
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FaultInjectL2AdapterConfig":
+        """Parse a fault-inject adapter spec, building the inner config too.
+
+        The ``"inner"`` sub-dict is dispatched through the L2 adapter config
+        registry (lazy-importing its module if needed), mirroring
+        ``parse_args_to_l2_adapters_config`` so the inner adapter's own
+        eviction / persist / serde keys are honored.
+
+        Args:
+            d: The adapter spec dict (see the class docstring for fields).
+
+        Returns:
+            A populated ``FaultInjectL2AdapterConfig``.
+
+        Raises:
+            ValueError: If ``inner`` is missing or malformed, the inner type
+                is unknown, or ``rate`` / ``seed`` / ``gap_indices`` fail
+                validation.
+        """
+        inner = d.get("inner")
+        if not isinstance(inner, dict):
+            raise ValueError("'inner' must be an adapter spec dict with a 'type' field")
+        inner_type = inner.get("type")
+        if not isinstance(inner_type, str):
+            raise ValueError("'inner' adapter spec must include a string 'type'")
+
+        # Build the inner adapter config via the public registry accessor
+        # (lazy-importing its module if needed), mirroring
+        # parse_args_to_l2_adapters_config.
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.config import (  # noqa: PLC0415
+            get_l2_adapter_config_class,
+        )
+
+        inner_cls = get_l2_adapter_config_class(inner_type)
+        inner_config = inner_cls.from_dict(inner)
+        inner_config.eviction_config = cls._parse_eviction_config(inner)
+        inner_config.persist_config = cls._parse_persist_config(inner)
+        inner_config.serde_config = cls._parse_serde_config(inner)
+
+        rate = d.get("rate", 0.0)
+        if not isinstance(rate, (int, float)) or not (0.0 <= rate <= 1.0):
+            raise ValueError("rate must be a number in [0, 1]")
+
+        seed = d.get("seed", 0)
+        if isinstance(seed, bool) or not isinstance(seed, int):
+            raise ValueError("seed must be an integer")
+
+        raw_gap = d.get("gap_indices", [])
+        if not isinstance(raw_gap, list) or any(
+            isinstance(i, bool) or not isinstance(i, int) or i < 0 for i in raw_gap
+        ):
+            raise ValueError("gap_indices must be a list of non-negative integers")
+
+        raw_ratios = d.get("gap_tail_ratios", [])
+        if not isinstance(raw_ratios, list) or any(
+            isinstance(x, bool)
+            or not isinstance(x, (int, float))
+            or not (0.0 <= x <= 1.0)
+            for x in raw_ratios
+        ):
+            raise ValueError("gap_tail_ratios must be a list of floats in [0, 1]")
+
+        return cls(
+            inner_config=inner_config,
+            rate=float(rate),
+            seed=seed,
+            gap_indices=tuple(raw_gap),
+            gap_tail_ratios=tuple(float(x) for x in raw_ratios),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        """Return a help string describing this adapter's JSON config fields."""
+        return (
+            "Fault-injecting L2 adapter (test only; drops keys at load to "
+            "simulate L2 retrieve errors). Fields:\n"
+            "- inner (dict, required): wrapped adapter spec, e.g. "
+            '{"type":"fs_native","base_path":"/dev/shm/x"}\n'
+            "- rate (float): per-key drop probability in [0,1] (default 0.0)\n"
+            "- seed (int): deterministic hash seed (default 0)\n"
+            "- gap_indices (list[int]): exact head-relative positions to drop\n"
+            "- gap_tail_ratios (list[float]): distance-from-tail / load-length "
+            "in [0,1] (0=last, 0.5=middle, 1=first); workload-agnostic"
+        )
+
+
+# -----------------------------------------------------------------------------
+# Adapter (decorator)
+# -----------------------------------------------------------------------------
+
+
+class FaultInjectL2Adapter(L2AdapterInterface):
+    """Decorator over an inner L2 adapter that drops a deterministic key subset.
+
+    All operations delegate to ``inner``; only the load-result query is
+    post-processed (dropped bits cleared) to simulate L2 retrieve errors.
+    """
+
+    def __init__(
+        self,
+        inner: L2AdapterInterface,
+        rate: float,
+        seed: int,
+        gap_indices: tuple[int, ...],
+        gap_tail_ratios: tuple[float, ...] = (),
+    ) -> None:
+        """Wrap ``inner`` with deterministic load-failure injection.
+
+        Args:
+            inner: The real L2 adapter that every operation delegates to.
+            rate: Per-key drop probability in [0, 1]. ``0`` disables
+                rate-based drops (``gap_indices`` still applies).
+            seed: Seed for the deterministic per-key hash, so runs reproduce.
+            gap_indices: Exact task-positions (from the head) to always drop,
+                in addition to the rate-based drops.
+            gap_tail_ratios: Positions to always drop, given as distance-from-
+                tail / load-length in [0, 1] (0=last, 0.5=middle, 1=first).
+                Workload-agnostic and self-scaling across context lengths --
+                no advance knowledge of the stored content is needed.
+        """
+        # Usage and eviction are delegated to the inner adapter, so the base
+        # class's byte accounting (capacity 0) is intentionally unused here.
+        super().__init__(max_capacity_bytes=0)
+        self._inner = inner
+        self._rate = rate
+        self._seed = seed
+        self._gap_indices = frozenset(gap_indices)
+        self._gap_tail_ratios = tuple(gap_tail_ratios)
+        # task_id -> load keys, so query_load_result can map a dropped bit
+        # position back to its key.
+        self._load_keys: dict[L2TaskId, list[ObjectKey]] = {}
+        self._keys_lock = threading.Lock()
+        logger.warning(
+            "FaultInjectL2Adapter ACTIVE (rate=%.3f seed=%d gap_indices=%s "
+            "gap_tail_ratios=%s) wrapping %s -- test/diagnostic use only.",
+            rate,
+            seed,
+            sorted(self._gap_indices),
+            list(self._gap_tail_ratios),
+            type(inner).__name__,
+        )
+
+    # -- drop decision --------------------------------------------------------
+
+    def _should_drop_key(self, key: ObjectKey) -> bool:
+        """Return whether ``key`` falls in the rate-based drop bucket.
+
+        Deterministic in ``(seed, key)``: a stable blake2b hash bucketed by
+        ``rate``, so a key drops (or not) identically at lookup and at load
+        within a request, and reproducibly across runs with the same seed.
+        Returns ``False`` immediately when ``rate <= 0`` (pass-through).
+        """
+        if self._rate <= 0.0:
+            return False
+        # Hash the key's stable identity fields directly — never ``repr(key)``,
+        # whose format is for debugging and may change or carry non-deterministic
+        # fields, breaking the lookup-vs-load drop consistency this relies on.
+        ident = (
+            f"{self._seed}:{key.chunk_hash.hex()}:{key.model_name}:"
+            f"{key.kv_rank}:{key.object_group_id}:{key.cache_salt}"
+        )
+        h = hashlib.blake2b(ident.encode(), digest_size=8).digest()
+        bucket = int.from_bytes(h, "big") % _HASH_DENOM
+        return bucket < int(self._rate * _HASH_DENOM)
+
+    def _drop_positions(self, keys: list[ObjectKey]) -> list[int]:
+        """Return the positions in ``keys`` to drop, in ascending order.
+
+        ``keys`` is the token-ordered chunk batch of one load, so index ``i`` is
+        the chunk's sequence position and ``len(keys)`` the load's chunk count.
+        A position is dropped if it is a ``gap_tail_ratios`` slot (distance-from-
+        tail as a fraction of the load length -- workload-agnostic, computed here
+        from the batch the server received), or it is listed in ``gap_indices``
+        (an exact head-relative position), or its key falls in the rate-based
+        bucket per ``_should_drop_key``.
+        """
+        n = len(keys)
+        ratio_idxs = (
+            {int(round((1.0 - ratio) * (n - 1))) for ratio in self._gap_tail_ratios}
+            if n > 0
+            else set()
+        )
+        dropped = []
+        for i, key in enumerate(keys):
+            if i in ratio_idxs or i in self._gap_indices or self._should_drop_key(key):
+                dropped.append(i)
+        return dropped
+
+    # -- event fds (delegate) -------------------------------------------------
+
+    def get_store_event_fd(self) -> int:
+        """Return the inner adapter's store event fd."""
+        return self._inner.get_store_event_fd()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        """Return the inner adapter's lookup-and-lock event fd."""
+        return self._inner.get_lookup_and_lock_event_fd()
+
+    def get_load_event_fd(self) -> int:
+        """Return the inner adapter's load event fd."""
+        return self._inner.get_load_event_fd()
+
+    # -- store (delegate) -----------------------------------------------------
+
+    def submit_store_task(
+        self, keys: list[ObjectKey], objects: list[MemoryObj]
+    ) -> L2TaskId:
+        """Delegate the store task to the inner adapter (store is never faulted)."""
+        return self._inner.submit_store_task(keys, objects)
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        """Delegate to the inner adapter; store results are passed through."""
+        return self._inner.pop_completed_store_tasks()
+
+    # -- lookup and lock (pure delegation) ------------------------------------
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        """Delegate the lookup-and-lock task to the inner adapter (not faulted)."""
+        return self._inner.submit_lookup_and_lock_task(keys, layout_desc)
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        """Delegate to the inner adapter; lookup results are passed through.
+
+        Only the load primitive is faulted, so lookup reports keys present as
+        usual; the gap appears later when their load fails.
+        """
+        return self._inner.query_lookup_and_lock_result(task_id)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        """Delegate the unlock to the inner adapter."""
+        self._inner.submit_unlock(keys)
+
+    # -- load (intercept for 'error') -----------------------------------------
+
+    def submit_load_task(
+        self, keys: list[ObjectKey], objects: list[MemoryObj]
+    ) -> L2TaskId:
+        """Submit a load task, recording ``keys`` for result mapping.
+
+        Thread-safe. The key list is stored under the returned task id so
+        ``query_load_result`` can map dropped bit positions back to keys.
+        """
+        task_id = self._inner.submit_load_task(keys, objects)
+        with self._keys_lock:
+            self._load_keys[task_id] = keys
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        """Query the load result, clearing the dropped keys' bits.
+
+        Delegates to the inner adapter, then clears the bits at the dropped
+        positions. This is the faithful "L2 retrieve error": lookup reported
+        the key present but the load fails. No unlock is needed here; the
+        prefetch controller releases the load-failed read locks itself via the
+        trim mask.
+
+        Thread-safe. Non-idempotent: returns a non-None bitmap only once per
+        ``task_id``.
+
+        Args:
+            task_id: The task id returned by ``submit_load_task``.
+
+        Returns:
+            The post-processed bitmap, or ``None`` if the inner task has not
+            completed yet.
+        """
+        bitmap = self._inner.query_load_result(task_id)
+        if bitmap is None:
+            return None
+        with self._keys_lock:
+            keys = self._load_keys.pop(task_id, None)
+        if keys is not None:
+            dropped = self._drop_positions(keys)
+            for i in dropped:
+                bitmap.clear(i)
+            if dropped:
+                logger.debug(
+                    "FaultInject: task %s dropped %d/%d load keys",
+                    task_id,
+                    len(dropped),
+                    len(keys),
+                )
+        return bitmap
+
+    # -- listener / eviction / usage (delegate) -------------------------------
+
+    def register_listener(self, listener: L2AdapterListener) -> None:
+        """Forward the listener registration to the inner adapter."""
+        self._inner.register_listener(listener)
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """Delegate the delete to the inner adapter."""
+        self._inner.delete(keys)
+
+    def get_usage(self) -> AdapterUsage:
+        """Return the inner adapter's usage; this layer holds no data of its own."""
+        return self._inner.get_usage()
+
+    @property
+    def supports_global_eviction(self) -> bool:
+        """Whether the inner adapter supports aggregate usage-based eviction."""
+        return self._inner.supports_global_eviction
+
+    def report_status(self) -> dict:
+        """Return the inner adapter's status, annotated with the fault config.
+
+        Adds a ``"fault_inject"`` sub-dict (rate, seed, gap_indices) so the
+        active fault configuration is visible in diagnostics.
+        """
+        status = self._inner.report_status()
+        status["fault_inject"] = {
+            "rate": self._rate,
+            "seed": self._seed,
+            "gap_indices": sorted(self._gap_indices),
+            "gap_tail_ratios": list(self._gap_tail_ratios),
+        }
+        return status
+
+    def close(self) -> None:
+        """Clear the per-task key map, then close the inner adapter."""
+        with self._keys_lock:
+            self._load_keys.clear()
+        self._inner.close()
+
+
+# -----------------------------------------------------------------------------
+# Registration
+# -----------------------------------------------------------------------------
+
+register_l2_adapter_type("fault_inject", FaultInjectL2AdapterConfig)
+
+
+def _create_fault_inject_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "L1MemoryDesc | None" = None,
+) -> L2AdapterInterface:
+    """Build the inner adapter from the registry, then wrap it for faults.
+
+    Matches the L2 adapter factory signature so it can be registered under
+    the ``"fault_inject"`` type name.
+
+    Args:
+        config: A ``FaultInjectL2AdapterConfig`` whose ``inner_config`` names
+            the wrapped adapter.
+        l1_memory_desc: L1 memory descriptor forwarded to the inner adapter's
+            factory (some adapters need it for aligned buffers); ``None`` when
+            not applicable.
+
+    Returns:
+        A ``FaultInjectL2Adapter`` wrapping the freshly built inner adapter.
+    """
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.factory import (  # noqa: PLC0415
+        create_l2_adapter_from_registry,
+    )
+
+    assert isinstance(config, FaultInjectL2AdapterConfig)
+    inner = create_l2_adapter_from_registry(config.inner_config, l1_memory_desc)
+    return FaultInjectL2Adapter(
+        inner,
+        rate=config.rate,
+        seed=config.seed,
+        gap_indices=config.gap_indices,
+        gap_tail_ratios=config.gap_tail_ratios,
+    )
+
+
+register_l2_adapter_factory("fault_inject", _create_fault_inject_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/fs_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/fs_l2_adapter.py
new file mode 100644
index 0000000..175e04f
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/fs_l2_adapter.py
@@ -0,0 +1,764 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+File-system based L2 adapter using aiofiles for async I/O.
+
+Stores KV cache objects as raw tensor bytes on disk (no metadata
+header).  Each ObjectKey maps to a separate ``.data`` file whose
+name encodes all key fields so it can be reversed on startup.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional, Union
+import asyncio
+import os
+import threading
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+    from lmcache.v1.memory_management import MemoryObj
+
+# Third Party
+import aiofiles
+import aiofiles.os
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+_KEY_SEP = "@"
+# ``@`` in both ``model_name`` and ``cache_salt`` is rejected by
+# ObjectKey.__post_init__, so splitting on ``@`` is unambiguous.
+# Kept in sync with native_connector_l2_adapter.py and
+# csrc/storage_backends/fs/connector.cpp.
+_PATH_SLASH_REPLACEMENT = "-SEP-"
+_FILE_EXT = ".data"
+
+
+def _readinto_full(
+    f,  # typing: IO[bytes]
+    buf: Union[bytearray, memoryview, bytes],
+) -> int:
+    """Loop readinto() until *buf* is full or EOF.
+
+    A single ``readinto()`` may return fewer bytes than
+    *len(buf)* even when more data is available.  This
+    helper keeps reading until the buffer is completely
+    filled or the file reaches EOF.
+
+    Returns:
+        Total number of bytes read.
+    """
+    mv = memoryview(buf) if not isinstance(buf, memoryview) else buf
+    total = 0
+    while total < len(mv):
+        n = f.readinto(mv[total:])
+        if n is None or n == 0:
+            break
+        total += n
+    return total
+
+
+async def _async_readinto_full(
+    f,  # aiofiles async file handle
+    buf: Union[bytearray, memoryview, bytes],
+) -> int:
+    """Async version of :func:`_readinto_full`."""
+    mv = memoryview(buf) if not isinstance(buf, memoryview) else buf
+    total = 0
+    while total < len(mv):
+        n = await f.readinto(mv[total:])
+        if n is None or n == 0:
+            break
+        total += n
+    return total
+
+
+def _object_key_to_filename(key: ObjectKey) -> str:
+    """Build a reversible, filesystem-safe filename.
+
+    Unsalted::
+
+        <safe_model>@0x<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>.data
+
+    Salted (trailing ``cache_salt``)::
+
+        <safe_model>@0x<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>@<cache_salt>.data
+
+    ``kv_rank`` is written in ``0x`` prefixed hex so each byte
+    of the bitmap ``(ws<<24)|(rank<<16)|(local_ws<<8)|local``
+    is directly readable. ``object_group_id`` is written in plain hex.
+    """
+    safe_model = key.model_name.replace("/", _PATH_SLASH_REPLACEMENT)
+    base = (
+        f"{safe_model}{_KEY_SEP}{key.kv_rank:#010x}"
+        f"{_KEY_SEP}{key.object_group_id:x}{_KEY_SEP}{key.chunk_hash.hex()}"
+    )
+    if key.cache_salt:
+        return f"{base}{_KEY_SEP}{key.cache_salt}{_FILE_EXT}"
+    return f"{base}{_FILE_EXT}"
+
+
+def _filename_to_object_key(
+    filename: str,
+) -> Optional[ObjectKey]:
+    """Reverse ``_object_key_to_filename``.
+
+    Accepts both the 4-field unsalted shape and the 5-field salted
+    shape (trailing ``cache_salt``). Returns ``None`` for anything
+    else. Since ``model_name`` is guaranteed not to contain ``@``,
+    plain ``split`` suffices — no marker, no rsplit.
+    """
+    if not filename.endswith(_FILE_EXT):
+        return None
+    stem = filename[: -len(_FILE_EXT)]
+    parts = stem.split(_KEY_SEP)
+    if len(parts) == 4:
+        safe_model, kv_rank_str, object_group_str, chunk_hash_hex = parts
+        cache_salt = ""
+    elif len(parts) == 5:
+        safe_model, kv_rank_str, object_group_str, chunk_hash_hex, cache_salt = parts
+    else:
+        return None
+
+    model_name = safe_model.replace(_PATH_SLASH_REPLACEMENT, "/")
+    try:
+        chunk_hash = bytes.fromhex(chunk_hash_hex)
+        kv_rank = int(kv_rank_str, 16)
+        object_group_id = int(object_group_str, 16)
+        # ObjectKey.__post_init__ raises ValueError when the decoded
+        # model_name / cache_salt violate the forbidden-char or length
+        # invariants (e.g. a stray file from another tool on disk).
+        # The contract here is to return None for anything unparsable,
+        # so keep the constructor inside the try block.
+        return ObjectKey(
+            chunk_hash=chunk_hash,
+            model_name=model_name,
+            kv_rank=kv_rank,
+            object_group_id=object_group_id,
+            cache_salt=cache_salt,
+        )
+    except ValueError:
+        return None
+
+
+class FSL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for the filesystem-backed L2 adapter.
+
+    Fields:
+    - base_path: directory for storing KV cache files.
+    - relative_tmp_dir: optional relative sub-dir for
+      temp files (same as fs_connector_relative_tmp_dir).
+    """
+
+    def __init__(
+        self,
+        base_path: str,
+        relative_tmp_dir: Optional[str] = None,
+        read_ahead_size: Optional[int] = None,
+        use_odirect: bool = False,
+    ):
+        """Initialize FSL2AdapterConfig.
+
+        Args:
+            base_path: Directory for storing KV cache files.
+            relative_tmp_dir: Relative sub-dir under
+                base_path for temp files during writes.
+            read_ahead_size: If set, trigger filesystem
+                readahead by issuing a small initial read
+                of this many bytes before reading the rest.
+            use_odirect: If True, bypass the OS page cache
+                using O_DIRECT for both reads and writes.
+                Requires buffer sizes aligned to the
+                filesystem block size.
+        """
+        self.base_path = base_path
+        self.relative_tmp_dir = relative_tmp_dir
+        self.read_ahead_size = read_ahead_size
+        self.use_odirect = use_odirect
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FSL2AdapterConfig":
+        base_path = d.get("base_path")
+        if not isinstance(base_path, str) or not base_path:
+            raise ValueError("base_path must be a non-empty string")
+        relative_tmp_dir = d.get("relative_tmp_dir", None)
+        if relative_tmp_dir is not None:
+            if not isinstance(relative_tmp_dir, str):
+                raise ValueError("relative_tmp_dir must be a string")
+        read_ahead_size = d.get("read_ahead_size", None)
+        if read_ahead_size is not None:
+            if not isinstance(read_ahead_size, int) or read_ahead_size <= 0:
+                raise ValueError("read_ahead_size must be a positive integer")
+        use_odirect = d.get("use_odirect", False)
+        if not isinstance(use_odirect, bool):
+            raise ValueError("use_odirect must be a boolean")
+        return cls(
+            base_path=base_path,
+            relative_tmp_dir=relative_tmp_dir,
+            read_ahead_size=read_ahead_size,
+            use_odirect=use_odirect,
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "FS L2 adapter config fields:\n"
+            "- base_path (str): directory for KV cache "
+            "files (required)\n"
+            "- relative_tmp_dir (str): relative sub-dir "
+            "for temp files (optional, same as "
+            "fs_connector_relative_tmp_dir)\n"
+            "- read_ahead_size (int): trigger fs "
+            "readahead by reading this many bytes first "
+            "(optional)\n"
+            "- use_odirect (bool): bypass page cache "
+            "via O_DIRECT (optional, default false)"
+        )
+
+
+class FSL2Adapter(L2AdapterInterface):
+    """
+    File-system backed L2 adapter with async I/O via *aiofiles*.
+
+    Each file stores **only** the raw tensor bytes (no metadata
+    header), which gives maximum I/O throughput.  The file name
+    itself encodes the full ``ObjectKey`` so it is reversible.
+
+    Thread safety is ensured via a lock for shared bookkeeping
+    and an asyncio event loop running on a dedicated daemon
+    thread.
+    """
+
+    def __init__(self, config: FSL2AdapterConfig):
+        super().__init__()
+        self._config = config
+        base = config.base_path
+        self._base_path = Path(base)
+        self._base_path.mkdir(parents=True, exist_ok=True)
+
+        # Temp-file strategy aligned with FSConnector:
+        # if relative_tmp_dir is set, write to a sub-dir;
+        # otherwise fall back to a .tmp suffix.
+        self._relative_tmp_dir: Optional[Path] = None
+        if config.relative_tmp_dir is not None:
+            self._relative_tmp_dir = Path(config.relative_tmp_dir)
+            if (
+                self._relative_tmp_dir.is_absolute()
+                or ".." in self._relative_tmp_dir.parts
+            ):
+                raise ValueError("Invalid relative_tmp_dir: " + config.relative_tmp_dir)
+            (self._base_path / self._relative_tmp_dir).mkdir(
+                parents=False, exist_ok=True
+            )
+
+        # I/O tuning options aligned with FSConnector
+        self._read_ahead_size = config.read_ahead_size
+        self._use_odirect = config.use_odirect
+        self._os_disk_bs = 0
+        if self._use_odirect:
+            stat = os.statvfs(self._base_path)
+            self._os_disk_bs = stat.f_bsize
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        # Task bookkeeping
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+        self._lock = threading.Lock()
+
+        # Background asyncio event loop
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(target=self._run_event_loop, daemon=True)
+        self._loop_thread.start()
+
+        logger.info(
+            "Initialized FSL2Adapter with base_path=%s, "
+            "relative_tmp_dir=%s, "
+            "read_ahead_size=%s, use_odirect=%s",
+            self._base_path,
+            self._relative_tmp_dir,
+            self._read_ahead_size,
+            self._use_odirect,
+        )
+
+    # ------------------------------------------------------------------
+    # Event Fd Interface
+    # ------------------------------------------------------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    # ------------------------------------------------------------------
+    # Store Interface
+    # ------------------------------------------------------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_store(keys, objects, task_id),
+            self._loop,
+        )
+        return task_id
+
+    def pop_completed_store_tasks(
+        self,
+    ) -> dict[L2TaskId, L2StoreResult]:
+        """Pop all completed store tasks.
+
+        Returns:
+            dict[L2TaskId, L2StoreResult]: a dictionary mapping the task
+            id to an ``L2StoreResult`` that encodes both the success flag
+            and the bytes actually transferred.
+        """
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    # ------------------------------------------------------------------
+    # Lookup and Lock Interface
+    # ------------------------------------------------------------------
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_lookup(keys, task_id),
+            self._loop,
+        )
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        # No-op: FS adapter has no eviction, so locking
+        # between lookup and load is unnecessary.
+        pass
+
+    # ------------------------------------------------------------------
+    # Load Interface
+    # ------------------------------------------------------------------
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_load(keys, objects, task_id),
+            self._loop,
+        )
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    # ------------------------------------------------------------------
+    # Status Interface
+    # ------------------------------------------------------------------
+
+    def report_status(self) -> dict:
+        """Return a status dict for the FS L2 adapter."""
+        return {
+            "is_healthy": self._loop_thread.is_alive(),
+            "type": "FSL2Adapter",
+            "base_path": str(self._base_path),
+            "use_odirect": self._use_odirect,
+            "event_loop_alive": self._loop_thread.is_alive(),
+        }
+
+    # ------------------------------------------------------------------
+    # Eviction Interface
+    # ------------------------------------------------------------------
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        # Not implemented for the filesystem adapter.
+        pass
+
+    # ``get_usage()`` is inherited from ``L2AdapterInterface``. The FS
+    # adapter declares no max capacity (default 0) so ``supports_global_eviction``
+    # returns ``False`` and ``usage_fraction == -1.0`` — the eviction
+    # controller treats this as "no eviction signal" and skips the
+    # adapter entirely.
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        async def _stop_tasks():
+            tasks = [
+                t
+                for t in asyncio.all_tasks(self._loop)
+                if t is not asyncio.current_task()
+            ]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            fut = asyncio.run_coroutine_threadsafe(_stop_tasks(), self._loop)
+            try:
+                fut.result(timeout=5)
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._loop_thread.join()
+        self._loop.close()
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+        logger.info("FSL2Adapter closed")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _run_event_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _get_next_task_id(self) -> L2TaskId:
+        tid = self._next_task_id
+        self._next_task_id += 1
+        return tid
+
+    def _key_to_path(self, key: ObjectKey) -> Path:
+        return self._base_path / _object_key_to_filename(key)
+
+    async def _key_exists_on_disk(
+        self,
+        key: ObjectKey,
+    ) -> bool:
+        """Check whether the file for *key* exists on disk.
+
+        Uses ``aiofiles.os.path.exists`` so the check is
+        non-blocking and always reflects the real FS state,
+        which is critical for multi-node shared-FS setups.
+        """
+        path = self._key_to_path(key)
+        return await aiofiles.os.path.exists(path)
+
+    def _key_to_file_and_tmp_path(self, key: ObjectKey) -> tuple[Path, Path]:
+        """Return ``(final_path, tmp_path)``.
+
+        When ``relative_tmp_dir`` is configured, the temp file
+        is placed under that sub-directory (same behaviour as
+        ``FSConnector._get_file_and_tmp_path``).  Otherwise a
+        ``.tmp`` suffix is used.
+        """
+        fname = _object_key_to_filename(key)
+        final = self._base_path / fname
+        if self._relative_tmp_dir is not None:
+            tmp = self._base_path / self._relative_tmp_dir / fname
+        else:
+            tmp = final.with_suffix(".tmp")
+        return final, tmp
+
+    # ---- O_DIRECT helpers -----------------------------------------------
+
+    def _read_with_odirect(
+        self,
+        file_path: Path,
+        dst_buf: Union[bytearray, memoryview, bytes],
+    ) -> int:
+        """Synchronous O_DIRECT read into *dst_buf*.
+
+        Returns the number of bytes actually read.
+        Runs in an executor (not on the event loop).
+        """
+        fd = -1
+        size = len(dst_buf)
+        try:
+            aligned = self._os_disk_bs > 0 and size % self._os_disk_bs == 0
+            if not aligned:
+                logger.warning(
+                    "Cannot use O_DIRECT for %s, size is not aligned.",
+                    file_path,
+                )
+                with open(file_path, "rb") as f:
+                    return _readinto_full(f, dst_buf)
+
+            fd = os.open(
+                str(file_path),
+                os.O_RDONLY | getattr(os, "O_DIRECT", 0),
+            )
+            with os.fdopen(fd, "rb", buffering=0) as fdo:
+                fd = -1  # now managed by fdopen
+                return _readinto_full(fdo, dst_buf)
+        except Exception:
+            logger.exception("Failed to O_DIRECT read %s", file_path)
+            return 0
+        finally:
+            if fd >= 0:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+
+    def _write_with_odirect(self, file_path: Path, buf: bytes) -> None:
+        """Synchronous O_DIRECT write of *buf*.
+
+        Runs in an executor (not on the event loop).
+        """
+        fd = -1
+        try:
+            fd = os.open(
+                str(file_path),
+                os.O_CREAT | os.O_WRONLY | getattr(os, "O_DIRECT", 0),
+                0o644,
+            )
+            os.write(fd, buf)
+        except Exception:
+            logger.exception("Failed to O_DIRECT write %s", file_path)
+            raise
+        finally:
+            if fd >= 0:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+
+    # ---- store ----------------------------------------------------------
+
+    async def _execute_store(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        success = True
+        bytes_written = 0
+        try:
+            for key, obj in zip(keys, objects, strict=True):
+                file_path, tmp_path = self._key_to_file_and_tmp_path(key)
+
+                # Skip if already stored on disk
+                if await aiofiles.os.path.exists(file_path):
+                    continue
+                buf = obj.byte_array
+                size = len(buf)
+
+                try:
+                    # Decide whether O_DIRECT is usable
+                    do_odirect = self._use_odirect
+                    if do_odirect:
+                        aligned = self._os_disk_bs > 0 and size % self._os_disk_bs == 0
+                        if not aligned:
+                            logger.warning(
+                                "Cannot use O_DIRECT for "
+                                "writing size %d, not "
+                                "aligned to block size "
+                                "%d.",
+                                size,
+                                self._os_disk_bs,
+                            )
+                            do_odirect = False
+
+                    if do_odirect:
+                        await self._loop.run_in_executor(
+                            None,
+                            self._write_with_odirect,
+                            tmp_path,
+                            buf,
+                        )
+                    else:
+                        async with aiofiles.open(tmp_path, "wb") as f:
+                            await f.write(buf)
+
+                    await aiofiles.os.replace(tmp_path, file_path)
+                    bytes_written += size
+                    logger.debug(
+                        "FSL2Adapter stored key %s (%d bytes)",
+                        file_path.name,
+                        size,
+                    )
+                except Exception:
+                    logger.exception(
+                        "FSL2Adapter failed to store %s",
+                        file_path,
+                    )
+                    if await aiofiles.os.path.exists(tmp_path):
+                        await aiofiles.os.unlink(tmp_path)
+                    success = False
+        except Exception:
+            logger.exception(
+                "FSL2Adapter store task %s failed",
+                task_id,
+            )
+            success = False
+
+        with self._lock:
+            self._completed_store_tasks[task_id] = L2StoreResult(success, bytes_written)
+        self._store_efd.notify()
+
+    # ---- lookup ---------------------------------------------------------
+
+    async def _execute_lookup(
+        self,
+        keys: list[ObjectKey],
+        task_id: L2TaskId,
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        for i, key in enumerate(keys):
+            if not await self._key_exists_on_disk(key):
+                continue
+            bitmap.set(i)
+
+        with self._lock:
+            self._completed_lookup_tasks[task_id] = bitmap
+        self._lookup_efd.notify()
+
+    # ---- load -----------------------------------------------------------
+
+    async def _execute_load(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        for i, key in enumerate(keys):
+            file_path = self._key_to_path(key)
+            try:
+                dst_buf = objects[i].byte_array
+                expected = len(dst_buf)
+                num_read: Optional[int] = None
+
+                # O_DIRECT path (sync, via executor)
+                if self._use_odirect:
+                    num_read = await self._loop.run_in_executor(
+                        None,
+                        self._read_with_odirect,
+                        file_path,
+                        dst_buf,
+                    )
+                    if num_read != expected:
+                        logger.warning(
+                            "Incomplete O_DIRECT read for %s: expected %d, got %d",
+                            file_path.name,
+                            expected,
+                            num_read or 0,
+                        )
+                    else:
+                        bitmap.set(i)
+                        logger.debug(
+                            "FSL2Adapter loaded key %s (%d bytes, O_DIRECT)",
+                            file_path.name,
+                            num_read,
+                        )
+                    continue
+
+                # Standard async path with optional
+                # read-ahead
+                expected = len(dst_buf)
+                async with aiofiles.open(file_path, "rb") as f:
+                    if self._read_ahead_size is None:
+                        num_read = await _async_readinto_full(f, dst_buf)
+                    else:
+                        if not isinstance(dst_buf, memoryview):
+                            dst_buf = memoryview(dst_buf)
+                        # Trigger readahead with a
+                        # small initial read
+                        ra = self._read_ahead_size
+                        n_head = await _async_readinto_full(f, dst_buf[:ra])
+                        if n_head == ra:
+                            n_tail = await _async_readinto_full(f, dst_buf[ra:])
+                            num_read = n_head + n_tail
+                        else:
+                            num_read = n_head
+
+                    if num_read != expected:
+                        logger.warning(
+                            "Incomplete read for %s: expected %d, got %d",
+                            file_path.name,
+                            expected,
+                            num_read,
+                        )
+                        continue
+
+                    bitmap.set(i)
+                    logger.debug(
+                        "FSL2Adapter loaded key %s (%d bytes)",
+                        file_path.name,
+                        num_read,
+                    )
+            except FileNotFoundError:
+                continue
+            except Exception:
+                logger.exception(
+                    "FSL2Adapter failed to load %s",
+                    file_path,
+                )
+                continue
+
+        with self._lock:
+            self._completed_load_tasks[task_id] = bitmap
+        self._load_efd.notify()
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("fs", FSL2AdapterConfig)
+
+
+def _create_fs_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Create an FSL2Adapter from config."""
+    return FSL2Adapter(config)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("fs", _create_fs_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/fs_native_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/fs_native_l2_adapter.py
new file mode 100644
index 0000000..2d70349
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/fs_native_l2_adapter.py
@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Filesystem native L2 adapter config and factory.
+
+Backed by the native C++ filesystem connector wrapped with
+``NativeConnectorL2Adapter``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+
+logger = init_logger(__name__)
+
+
+class FSNativeL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for an L2 adapter backed by the native C++
+    filesystem connector.
+
+    Fields:
+    - base_path: directory for storing KV cache files.
+    - num_workers: C++ worker threads for I/O (default 4).
+    - relative_tmp_dir: relative sub-dir for temp files.
+    - use_odirect: bypass page cache via O_DIRECT.
+    - read_ahead_size: trigger filesystem readahead by
+      reading this many bytes first (optional).
+    """
+
+    def __init__(
+        self,
+        base_path: str,
+        num_workers: int = 4,
+        relative_tmp_dir: str = "",
+        use_odirect: bool = False,
+        read_ahead_size: Optional[int] = None,
+        max_capacity_gb: float = 0,
+    ):
+        self.base_path = base_path
+        self.num_workers = num_workers
+        self.relative_tmp_dir = relative_tmp_dir
+        self.use_odirect = use_odirect
+        self.read_ahead_size = read_ahead_size
+        self.max_capacity_gb = max_capacity_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "FSNativeL2AdapterConfig":
+        base_path = d.get("base_path")
+        if not isinstance(base_path, str) or not base_path:
+            raise ValueError("base_path must be a non-empty string")
+
+        num_workers = d.get("num_workers", 4)
+        if not isinstance(num_workers, int) or num_workers <= 0:
+            raise ValueError("num_workers must be a positive integer")
+
+        relative_tmp_dir = d.get("relative_tmp_dir", "")
+        if not isinstance(relative_tmp_dir, str):
+            raise ValueError("relative_tmp_dir must be a string")
+
+        use_odirect = d.get("use_odirect", False)
+        if not isinstance(use_odirect, bool):
+            raise ValueError("use_odirect must be a boolean")
+
+        read_ahead_size = d.get("read_ahead_size", None)
+        if read_ahead_size is not None:
+            if not isinstance(read_ahead_size, int) or read_ahead_size <= 0:
+                raise ValueError("read_ahead_size must be a positive integer")
+
+        max_capacity_gb = d.get("max_capacity_gb", 0)
+        if not isinstance(max_capacity_gb, (int, float)) or max_capacity_gb < 0:
+            raise ValueError("max_capacity_gb must be a non-negative number")
+
+        return cls(
+            base_path=base_path,
+            num_workers=num_workers,
+            relative_tmp_dir=str(relative_tmp_dir),
+            use_odirect=use_odirect,
+            read_ahead_size=read_ahead_size,
+            max_capacity_gb=float(max_capacity_gb),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "FS native L2 adapter config fields:\n"
+            "- base_path (str): directory for KV "
+            "cache files (required)\n"
+            "- num_workers (int): C++ worker threads "
+            "for I/O (default 4, >0)\n"
+            "- relative_tmp_dir (str): relative "
+            "sub-dir for temp files (default empty)\n"
+            "- use_odirect (bool): bypass page cache "
+            "via O_DIRECT (default false)\n"
+            "- read_ahead_size (int): trigger fs "
+            "readahead by reading this many bytes "
+            "first (optional)\n"
+            "- max_capacity_gb (float): max L2 capacity "
+            "in GB for usage tracking / eviction "
+            "(default 0 = disabled)"
+        )
+
+
+def _create_fs_native_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Create a NativeConnectorL2Adapter backed by the
+    C++ filesystem connector."""
+    try:
+        # First Party
+        from lmcache.lmcache_fs import (
+            LMCacheFSClient,
+        )
+    except ImportError as e:
+        raise RuntimeError(
+            "FS native L2 adapter requires the C++ FS "
+            "extension. Build with: pip install -e ."
+        ) from e
+
+    # Lazy import to avoid circular dependency
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (  # noqa: E501
+        NativeConnectorL2Adapter,
+    )
+
+    assert isinstance(config, FSNativeL2AdapterConfig)
+    native_client = LMCacheFSClient(
+        config.base_path,
+        config.num_workers,
+        config.relative_tmp_dir,
+        config.use_odirect,
+        config.read_ahead_size or 0,
+    )
+    logger.info(
+        "Created FS native L2 adapter: %s (workers=%d, odirect=%s, read_ahead=%s)",
+        config.base_path,
+        config.num_workers,
+        config.use_odirect,
+        config.read_ahead_size,
+    )
+    return NativeConnectorL2Adapter(
+        native_client,
+        max_capacity_gb=config.max_capacity_gb,
+        type_name="FSNativeL2Adapter",
+        extra_status={
+            "base_path": config.base_path,
+            "use_odirect": config.use_odirect,
+            "num_workers": config.num_workers,
+            "read_ahead_size": config.read_ahead_size,
+        },
+    )
+
+
+register_l2_adapter_type("fs_native", FSNativeL2AdapterConfig)
+register_l2_adapter_factory("fs_native", _create_fs_native_l2_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/hfbucket_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/hfbucket_l2_adapter.py
new file mode 100644
index 0000000..77e9aa0
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/hfbucket_l2_adapter.py
@@ -0,0 +1,905 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Hugging Face Buckets L2 adapter for LMCache MP mode.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+import asyncio
+import os
+import shutil
+import tempfile
+import threading
+import time
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+    from lmcache.v1.memory_management import MemoryObj
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.platform import create_event_notifier
+from lmcache.v1.storage_backend.connector.hfbucket_connector import (
+    HFBucketClient,
+    HFBucketClientInterface,
+    HFBucketLocation,
+    encode_hfbucket_object_name,
+    parse_hfbucket_handle,
+)
+
+logger = init_logger(__name__)
+
+# Use a separate temp root from non-MP HFBucket to avoid collisions.
+_DEFAULT_DOWNLOAD_TMP_DIR = Path(tempfile.gettempdir()) / "lmcache-hfbucket-mp"
+_METADATA_CACHE_PRUNE_INTERVAL = 128
+
+
+@dataclass(frozen=True)
+class _CachedObjectMetadata:
+    """Cached object size entry with expiration metadata."""
+
+    size_bytes: int
+    expires_at: float
+
+
+class _PartialStoreFailure(RuntimeError):
+    """Raised when a failed HFBucket batch store still wrote some objects."""
+
+    def __init__(
+        self,
+        message: str,
+        stored_keys: list[ObjectKey],
+        stored_sizes: list[int],
+    ) -> None:
+        super().__init__(message)
+        self.stored_keys = stored_keys
+        self.stored_sizes = stored_sizes
+
+
+def _object_key_to_string(key: ObjectKey) -> str:
+    """Serialize an MP ``ObjectKey`` to the shared L2 object-name format.
+
+    Unsalted keys use
+    ``<model_name>@<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>``. Salted
+    keys append ``@<cache_salt>`` so tenants/users with identical token chunks
+    do not collide in the backing bucket.
+    """
+    base = (
+        f"{key.model_name}@{key.kv_rank:08x}"
+        f"@{key.object_group_id:x}@{key.chunk_hash.hex()}"
+    )
+    if key.cache_salt:
+        return f"{base}@{key.cache_salt}"
+    return base
+
+
+def _object_key_to_bucket_path(key: ObjectKey, location: HFBucketLocation) -> str:
+    """Return the HFBucket object path for an MP object key."""
+    encoded = encode_hfbucket_object_name(_object_key_to_string(key))
+    if location.object_prefix:
+        return f"{location.object_prefix}/{encoded}"
+    return encoded
+
+
+def _resolve_hf_token(token_env: str, token: str | None) -> str | None:
+    """Resolve Hugging Face token from env-first adapter config."""
+    env_token = os.environ.get(token_env, "") if token_env else ""
+    if env_token:
+        return env_token
+    return token
+
+
+def _get_path_info_path(path_info: object) -> str:
+    """Read a Hugging Face path-info object's path field defensively."""
+    path = getattr(path_info, "path", "")
+    return path if isinstance(path, str) else ""
+
+
+def _get_path_info_type(path_info: object) -> str:
+    """Read a Hugging Face path-info object's type field defensively."""
+    obj_type = getattr(path_info, "type", "")
+    return obj_type if isinstance(obj_type, str) else ""
+
+
+def _get_path_info_size(path_info: object) -> int:
+    """Read a Hugging Face path-info object's size field defensively."""
+    size = getattr(path_info, "size", 0)
+    return size if isinstance(size, int) else 0
+
+
+def _is_not_found_error(exc: Exception) -> bool:
+    """Return whether an exception represents a missing bucket/object."""
+    response = getattr(exc, "response", None)
+    status_code = getattr(response, "status_code", None)
+    if isinstance(status_code, int):
+        return status_code == 404
+
+    direct_status_code = getattr(exc, "status_code", None)
+    if isinstance(direct_status_code, int):
+        return direct_status_code == 404
+
+    return "404" in str(exc)
+
+
+class HFBucketL2AdapterConfig(L2AdapterConfigBase):
+    """Configuration for the HFBucket MP L2 adapter.
+
+    Fields:
+    - ``bucket_handle``: ``hf://buckets/<namespace>/<bucket>[/<prefix>]``.
+    - ``token_env``: environment variable used to resolve the HF token.
+    - ``token``: optional direct token fallback.
+    - ``create_bucket_if_missing``: create the bucket lazily on first store.
+    - ``download_tmp_dir``: root directory for temporary load downloads.
+    - ``metadata_cache_ttl_secs``: TTL for path-size metadata cache.
+    - ``num_workers``: worker threads for blocking Hugging Face API calls.
+    - ``max_capacity_gb``: capacity used by inherited L2 usage accounting.
+    """
+
+    def __init__(
+        self,
+        bucket_handle: str,
+        token_env: str = "HF_TOKEN",
+        token: Optional[str] = None,
+        create_bucket_if_missing: bool = False,
+        download_tmp_dir: str = str(_DEFAULT_DOWNLOAD_TMP_DIR),
+        metadata_cache_ttl_secs: float = 30.0,
+        num_workers: int = 4,
+        max_capacity_gb: float = 0.0,
+    ) -> None:
+        self.bucket_handle = bucket_handle
+        self.bucket_location = parse_hfbucket_handle(bucket_handle)
+        self.token_env = token_env
+        self.token = token
+        self.create_bucket_if_missing = create_bucket_if_missing
+        self.download_tmp_dir = Path(download_tmp_dir)
+        self.metadata_cache_ttl_secs = metadata_cache_ttl_secs
+        self.num_workers = num_workers
+        self.max_capacity_gb = max_capacity_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "HFBucketL2AdapterConfig":
+        """Parse a config object from ``--l2-adapter`` JSON."""
+        bucket_handle = d.get("bucket_handle")
+        if not isinstance(bucket_handle, str) or not bucket_handle:
+            raise ValueError("bucket_handle must be a non-empty string")
+
+        token_env = d.get("token_env", "HF_TOKEN")
+        if not isinstance(token_env, str):
+            raise ValueError("token_env must be a string")
+
+        token = d.get("token")
+        if token is not None and not isinstance(token, str):
+            raise ValueError("token must be a string")
+
+        download_tmp_dir = d.get("download_tmp_dir", str(_DEFAULT_DOWNLOAD_TMP_DIR))
+        if not isinstance(download_tmp_dir, str) or not download_tmp_dir:
+            raise ValueError("download_tmp_dir must be a non-empty string")
+
+        metadata_cache_ttl_secs = d.get("metadata_cache_ttl_secs", 30.0)
+        if (
+            not isinstance(metadata_cache_ttl_secs, (int, float))
+            or isinstance(metadata_cache_ttl_secs, bool)
+            or metadata_cache_ttl_secs < 0
+        ):
+            raise ValueError("metadata_cache_ttl_secs must be a non-negative number")
+
+        num_workers = d.get("num_workers", 4)
+        if not isinstance(num_workers, int) or isinstance(num_workers, bool):
+            raise ValueError("num_workers must be a positive integer")
+        if num_workers <= 0:
+            raise ValueError("num_workers must be a positive integer")
+
+        max_capacity_gb = d.get("max_capacity_gb", 0.0)
+        if (
+            not isinstance(max_capacity_gb, (int, float))
+            or isinstance(max_capacity_gb, bool)
+            or max_capacity_gb < 0
+        ):
+            raise ValueError("max_capacity_gb must be a non-negative number")
+
+        create_bucket_if_missing = d.get("create_bucket_if_missing", False)
+        if not isinstance(create_bucket_if_missing, bool):
+            raise ValueError("create_bucket_if_missing must be a boolean")
+
+        cfg = cls(
+            bucket_handle=bucket_handle,
+            token_env=token_env,
+            token=token,
+            create_bucket_if_missing=create_bucket_if_missing,
+            download_tmp_dir=download_tmp_dir,
+            metadata_cache_ttl_secs=float(metadata_cache_ttl_secs),
+            num_workers=num_workers,
+            max_capacity_gb=float(max_capacity_gb),
+        )
+        cfg.eviction_config = cls._parse_eviction_config(d)
+        return cfg
+
+    @classmethod
+    def help(cls) -> str:
+        """Return CLI help text for this adapter type."""
+        return (
+            "HFBucket L2 adapter config fields:\n"
+            "- bucket_handle (str, required): "
+            "hf://buckets/<namespace>/<bucket>[/<prefix>]\n"
+            "- token_env (str): env var for HF token (default HF_TOKEN)\n"
+            "- token (str): direct token fallback\n"
+            "- create_bucket_if_missing (bool): create bucket on first store\n"
+            "- download_tmp_dir (str): temporary download root\n"
+            "- metadata_cache_ttl_secs (float): metadata cache TTL\n"
+            "- num_workers (int): blocking HF API worker threads\n"
+            "- max_capacity_gb (float): capacity for get_usage (0 = disabled)\n"
+            "- eviction (dict): optional, see L2AdapterConfigBase"
+        )
+
+
+class HFBucketL2Adapter(L2AdapterInterface):
+    """Hugging Face Buckets backed MP L2 adapter."""
+
+    def __init__(
+        self,
+        config: HFBucketL2AdapterConfig,
+        bucket_client: HFBucketClientInterface | None = None,
+    ) -> None:
+        super().__init__(max_capacity_bytes=int(config.max_capacity_gb * (1024**3)))
+        self._config = config
+        self._bucket_location = config.bucket_location
+        self._bucket_id = config.bucket_location.bucket_id
+        self._object_prefix = config.bucket_location.object_prefix
+        self._create_bucket_if_missing = config.create_bucket_if_missing
+        self._metadata_cache_ttl_secs = config.metadata_cache_ttl_secs
+
+        if bucket_client is None:
+            token = _resolve_hf_token(config.token_env, config.token)
+            self._bucket_client: HFBucketClientInterface = HFBucketClient(token=token)
+        else:
+            self._bucket_client = bucket_client
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+
+        self._locked_keys: dict[ObjectKey, int] = defaultdict(int)
+        self._key_sizes: dict[ObjectKey, int] = {}
+        self._metadata_cache: dict[str, _CachedObjectMetadata] = {}
+        self._metadata_cache_updates = 0
+
+        self._bucket_create_checked = False
+        self._bucket_create_lock = threading.Lock()
+
+        self._lock = threading.Lock()
+        self._closed = False
+
+        self._download_tmp_root = config.download_tmp_dir.expanduser()
+        self._download_tmp_root.mkdir(parents=True, exist_ok=True)
+        self._download_session_dir = Path(
+            tempfile.mkdtemp(
+                prefix="hfbucket-mp-",
+                dir=self._download_tmp_root,
+            )
+        )
+
+        self._executor = ThreadPoolExecutor(
+            max_workers=config.num_workers,
+            thread_name_prefix="hfbucket-l2",
+        )
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(
+            target=self._run_event_loop,
+            daemon=True,
+            name="hfbucket-l2-adapter-loop",
+        )
+        self._loop_thread.start()
+
+        logger.info(
+            "Initialized HFBucketL2Adapter (bucket_id=%s prefix=%r "
+            "workers=%d max_capacity_gb=%.2f)",
+            self._bucket_id,
+            self._object_prefix,
+            config.num_workers,
+            config.max_capacity_gb,
+        )
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id_locked()
+            if self._closed:
+                self._completed_store_tasks[task_id] = L2StoreResult(False, 0)
+                closed = True
+            else:
+                closed = False
+
+        if closed:
+            self._store_efd.notify()
+            return task_id
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_store(list(keys), list(objects), task_id),
+            self._loop,
+        )
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id_locked()
+            if self._closed:
+                self._completed_lookup_tasks[task_id] = Bitmap(len(keys))
+                closed = True
+            else:
+                closed = False
+
+        if closed:
+            self._lookup_efd.notify()
+            return task_id
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_lookup(list(keys), task_id),
+            self._loop,
+        )
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Optional[Bitmap]:
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        with self._lock:
+            for key in keys:
+                if key not in self._locked_keys:
+                    continue
+                if self._locked_keys[key] <= 1:
+                    del self._locked_keys[key]
+                else:
+                    self._locked_keys[key] -= 1
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id_locked()
+            if self._closed:
+                self._completed_load_tasks[task_id] = Bitmap(len(keys))
+                closed = True
+            else:
+                closed = False
+
+        if closed:
+            self._load_efd.notify()
+            return task_id
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_load(list(keys), list(objects), task_id),
+            self._loop,
+        )
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Optional[Bitmap]:
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        if not keys:
+            return
+
+        with self._lock:
+            if self._closed:
+                return
+            deletable = [key for key in keys if self._locked_keys.get(key, 0) == 0]
+
+        if not deletable:
+            return
+
+        future = asyncio.run_coroutine_threadsafe(
+            self._execute_delete(deletable),
+            self._loop,
+        )
+        try:
+            deleted_keys, deleted_sizes = future.result(timeout=30.0)
+        except Exception as exc:
+            logger.warning("HFBucketL2Adapter delete failed: %s", exc)
+            return
+
+        if deleted_keys:
+            self._notify_keys_deleted(deleted_keys, deleted_sizes)
+
+    def report_status(self) -> dict:
+        usage = self.get_usage()
+        with self._lock:
+            object_count = len(self._key_sizes)
+            locked_key_count = len(self._locked_keys)
+            closed = self._closed
+        return {
+            "is_healthy": self._loop_thread.is_alive() and not closed,
+            "type": "HFBucketL2Adapter",
+            "bucket_id": self._bucket_id,
+            "object_prefix": self._object_prefix,
+            "stored_object_count": object_count,
+            "locked_key_count": locked_key_count,
+            "current_size_bytes": usage.total_bytes_used,
+            "max_capacity_bytes": usage.total_capacity_bytes,
+        }
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+
+        async def _stop_tasks() -> None:
+            tasks = [
+                task
+                for task in asyncio.all_tasks(self._loop)
+                if task is not asyncio.current_task()
+            ]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            try:
+                asyncio.run_coroutine_threadsafe(_stop_tasks(), self._loop).result(
+                    timeout=5
+                )
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._loop_thread.join(timeout=5)
+        try:
+            self._loop.close()
+        except Exception:
+            pass
+
+        self._executor.shutdown(wait=True, cancel_futures=True)
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+        with self._lock:
+            self._metadata_cache.clear()
+            self._key_sizes.clear()
+            self._locked_keys.clear()
+
+        shutil.rmtree(self._download_session_dir, ignore_errors=True)
+        logger.info("HFBucketL2Adapter closed")
+
+    def _run_event_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _get_next_task_id_locked(self) -> L2TaskId:
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    async def _execute_store(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        try:
+            stored_keys, stored_sizes = await self._loop.run_in_executor(
+                self._executor,
+                self._store_batch_sync,
+                keys,
+                objects,
+            )
+            success = True
+        except _PartialStoreFailure as exc:
+            logger.exception("HFBucketL2Adapter store task partially failed")
+            stored_keys = exc.stored_keys
+            stored_sizes = exc.stored_sizes
+            success = False
+        except Exception:
+            logger.exception("HFBucketL2Adapter store task failed")
+            stored_keys = []
+            stored_sizes = []
+            success = False
+
+        bytes_transferred = sum(stored_sizes)
+        with self._lock:
+            self._completed_store_tasks[task_id] = L2StoreResult(
+                success,
+                bytes_transferred,
+            )
+
+        if stored_keys:
+            self._notify_keys_stored(stored_keys, stored_sizes)
+        self._store_efd.notify()
+
+    async def _execute_lookup(
+        self,
+        keys: list[ObjectKey],
+        task_id: L2TaskId,
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        try:
+            sizes = await self._loop.run_in_executor(
+                self._executor,
+                self._resolve_object_sizes_sync,
+                keys,
+            )
+        except Exception:
+            logger.exception("HFBucketL2Adapter lookup task failed")
+            sizes = [0] * len(keys)
+
+        accessed: list[ObjectKey] = []
+        with self._lock:
+            for i, (key, size) in enumerate(zip(keys, sizes, strict=True)):
+                if size <= 0:
+                    continue
+                bitmap.set(i)
+                self._locked_keys[key] += 1
+                accessed.append(key)
+            self._completed_lookup_tasks[task_id] = bitmap
+
+        self._lookup_efd.notify()
+        if accessed:
+            self._notify_keys_accessed(accessed)
+
+    async def _execute_load(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        try:
+            bitmap = await self._loop.run_in_executor(
+                self._executor,
+                self._load_batch_sync,
+                keys,
+                objects,
+            )
+        except Exception:
+            logger.exception("HFBucketL2Adapter load task failed")
+            bitmap = Bitmap(len(keys))
+
+        with self._lock:
+            self._completed_load_tasks[task_id] = bitmap
+        self._load_efd.notify()
+
+    async def _execute_delete(
+        self,
+        keys: list[ObjectKey],
+    ) -> tuple[list[ObjectKey], list[int]]:
+        return await self._loop.run_in_executor(
+            self._executor,
+            self._delete_batch_sync,
+            keys,
+        )
+
+    def _store_batch_sync(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> tuple[list[ObjectKey], list[int]]:
+        self._ensure_bucket_for_writes()
+
+        additions: list[tuple[bytes, str]] = []
+        indexed: list[tuple[ObjectKey, str, int]] = []
+        for key, obj in zip(keys, objects, strict=True):
+            object_path = _object_key_to_bucket_path(key, self._bucket_location)
+            data = memoryview(obj.byte_array).cast("B").tobytes()
+            additions.append((data, object_path))
+            indexed.append((key, object_path, len(data)))
+
+        if not additions:
+            return [], []
+
+        try:
+            self._bucket_client.upload_files(self._bucket_id, additions)
+        except Exception as exc:
+            # Hugging Face batch writes are not transactional: a request can
+            # write part of the batch and then fail. Fetch fresh backend
+            # metadata, update accounting for objects that really landed, and
+            # still report the submitted store task as failed.
+            reconciled_keys, reconciled_sizes = self._reconcile_failed_store(indexed)
+            raise _PartialStoreFailure(
+                "HFBucket batch upload failed after partial reconciliation",
+                reconciled_keys,
+                reconciled_sizes,
+            ) from exc
+
+        stored_keys: list[ObjectKey] = []
+        stored_sizes: list[int] = []
+        with self._lock:
+            for key, object_path, size in indexed:
+                was_new = key not in self._key_sizes
+                self._key_sizes[key] = size
+                self._set_cached_object_size_locked(object_path, size)
+                if was_new:
+                    stored_keys.append(key)
+                    stored_sizes.append(size)
+
+        return stored_keys, stored_sizes
+
+    def _resolve_object_sizes_sync(self, keys: list[ObjectKey]) -> list[int]:
+        object_paths = [
+            _object_key_to_bucket_path(key, self._bucket_location) for key in keys
+        ]
+
+        cached: dict[str, int] = {}
+        unresolved_paths: list[str] = []
+        with self._lock:
+            for object_path in object_paths:
+                cached_size = self._get_cached_object_size_locked(object_path)
+                if cached_size is None:
+                    unresolved_paths.append(object_path)
+                else:
+                    cached[object_path] = cached_size
+
+        if unresolved_paths:
+            fetched = self._fetch_object_sizes_sync(unresolved_paths)
+            with self._lock:
+                for object_path, size in fetched.items():
+                    self._set_cached_object_size_locked(object_path, size)
+            cached.update(fetched)
+
+        return [cached.get(object_path, 0) for object_path in object_paths]
+
+    def _fetch_object_sizes_sync(self, object_paths: list[str]) -> dict[str, int]:
+        if not object_paths:
+            return {}
+
+        try:
+            path_infos = self._bucket_client.get_paths_info(
+                self._bucket_id,
+                object_paths,
+            )
+        except Exception as exc:
+            if _is_not_found_error(exc):
+                return {object_path: 0 for object_path in object_paths}
+            raise
+
+        size_by_path: dict[str, int] = {}
+        for path_info in path_infos:
+            if _get_path_info_type(path_info) != "file":
+                continue
+            path = _get_path_info_path(path_info)
+            if path:
+                size_by_path[path] = _get_path_info_size(path_info)
+
+        return {
+            object_path: size_by_path.get(object_path, 0)
+            for object_path in object_paths
+        }
+
+    def _load_batch_sync(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> Bitmap:
+        bitmap = Bitmap(len(keys))
+        object_paths = [
+            _object_key_to_bucket_path(key, self._bucket_location) for key in keys
+        ]
+
+        batch_dir = Path(
+            tempfile.mkdtemp(prefix="load-", dir=self._download_session_dir)
+        )
+        local_paths: list[tuple[int, Path]] = []
+        files: list[tuple[str, str]] = []
+        for index, object_path in enumerate(object_paths):
+            local_path = batch_dir / f"{index}.bin"
+            local_paths.append((index, local_path))
+            files.append((object_path, str(local_path)))
+
+        try:
+            try:
+                self._bucket_client.download_files(self._bucket_id, files)
+            except Exception as exc:
+                if not _is_not_found_error(exc):
+                    logger.warning("Batch download from hfbucket raised: %s", exc)
+
+            for index, local_path in local_paths:
+                if not local_path.exists():
+                    continue
+
+                dst = memoryview(objects[index].byte_array).cast("B")
+                file_size = local_path.stat().st_size
+                if file_size != len(dst):
+                    logger.error(
+                        "Downloaded object %s has %d bytes, expected %d bytes; "
+                        "rejecting load",
+                        object_paths[index],
+                        file_size,
+                        len(dst),
+                    )
+                    with self._lock:
+                        self._set_cached_object_size_locked(
+                            object_paths[index],
+                            file_size,
+                        )
+                    continue
+
+                with local_path.open("rb") as f:
+                    bytes_read = f.readinto(dst)
+                if bytes_read != len(dst):
+                    logger.error(
+                        "Downloaded object %s read %d bytes, expected %d bytes; "
+                        "rejecting load",
+                        object_paths[index],
+                        bytes_read,
+                        len(dst),
+                    )
+                    with self._lock:
+                        self._set_cached_object_size_locked(
+                            object_paths[index],
+                            bytes_read,
+                        )
+                    continue
+
+                bitmap.set(index)
+                with self._lock:
+                    self._set_cached_object_size_locked(
+                        object_paths[index],
+                        file_size,
+                    )
+
+            return bitmap
+        finally:
+            shutil.rmtree(batch_dir, ignore_errors=True)
+
+    def _delete_batch_sync(
+        self,
+        keys: list[ObjectKey],
+    ) -> tuple[list[ObjectKey], list[int]]:
+        object_paths = [
+            _object_key_to_bucket_path(key, self._bucket_location) for key in keys
+        ]
+
+        try:
+            self._bucket_client.delete_files(self._bucket_id, object_paths)
+        except Exception as exc:
+            if not _is_not_found_error(exc):
+                raise
+
+        deleted_keys: list[ObjectKey] = []
+        deleted_sizes: list[int] = []
+        with self._lock:
+            for key, object_path in zip(keys, object_paths, strict=True):
+                size = self._key_sizes.pop(key, None)
+                self._set_cached_object_size_locked(object_path, 0)
+                deleted_keys.append(key)
+                deleted_sizes.append(size if size is not None else 0)
+
+        return deleted_keys, deleted_sizes
+
+    def _ensure_bucket_for_writes(self) -> None:
+        if not self._create_bucket_if_missing or self._bucket_create_checked:
+            return
+
+        with self._bucket_create_lock:
+            if self._bucket_create_checked:
+                return
+            self._bucket_client.create_bucket(self._bucket_id)
+            self._bucket_create_checked = True
+
+    def _refresh_cached_sizes(self, keys: list[ObjectKey]) -> None:
+        try:
+            self._resolve_object_sizes_sync(keys)
+        except Exception:
+            logger.debug("Failed to refresh hfbucket object sizes", exc_info=True)
+
+    def _reconcile_failed_store(
+        self,
+        indexed: list[tuple[ObjectKey, str, int]],
+    ) -> tuple[list[ObjectKey], list[int]]:
+        object_paths = [object_path for _, object_path, _ in indexed]
+        try:
+            sizes_by_path = self._fetch_object_sizes_sync(object_paths)
+        except Exception:
+            logger.debug("Failed to reconcile partial hfbucket store", exc_info=True)
+            return [], []
+
+        stored_keys: list[ObjectKey] = []
+        stored_sizes: list[int] = []
+        with self._lock:
+            for key, object_path, _expected_size in indexed:
+                size = sizes_by_path.get(object_path, 0)
+                self._set_cached_object_size_locked(object_path, size)
+                if size <= 0:
+                    continue
+
+                # Only notify net-new keys. Existing keys already contributed
+                # to byte accounting, and cache objects should be fixed size.
+                was_new = key not in self._key_sizes
+                self._key_sizes[key] = size
+                if was_new:
+                    stored_keys.append(key)
+                    stored_sizes.append(size)
+
+        return stored_keys, stored_sizes
+
+    def _get_cached_object_size_locked(self, object_path: str) -> int | None:
+        entry = self._metadata_cache.get(object_path)
+        if entry is None:
+            return None
+        if entry.expires_at <= time.monotonic():
+            self._metadata_cache.pop(object_path, None)
+            return None
+        return entry.size_bytes
+
+    def _set_cached_object_size_locked(self, object_path: str, size: int) -> None:
+        expires_at = time.monotonic() + self._metadata_cache_ttl_secs
+        self._metadata_cache[object_path] = _CachedObjectMetadata(
+            size_bytes=size,
+            expires_at=expires_at,
+        )
+        self._metadata_cache_updates += 1
+        if self._metadata_cache_updates % _METADATA_CACHE_PRUNE_INTERVAL == 0:
+            self._prune_expired_cache_entries_locked(time.monotonic())
+
+    def _prune_expired_cache_entries_locked(self, now: float) -> None:
+        expired = [
+            object_path
+            for object_path, entry in self._metadata_cache.items()
+            if entry.expires_at <= now
+        ]
+        for object_path in expired:
+            self._metadata_cache.pop(object_path, None)
+
+
+register_l2_adapter_type("hfbucket", HFBucketL2AdapterConfig)
+
+
+def _create_hfbucket_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Create an HFBucket L2 adapter from registry config."""
+    return HFBucketL2Adapter(config)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("hfbucket", _create_hfbucket_l2_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/mock_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/mock_l2_adapter.py
new file mode 100644
index 0000000..550a989
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/mock_l2_adapter.py
@@ -0,0 +1,525 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import defaultdict
+from typing import TYPE_CHECKING, Optional
+import asyncio
+import copy
+import threading
+import time
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface, L2TaskId
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.memory_management import MemoryObj, TensorMemoryObj
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+# Helper function
+
+
+def clone_tensor_memory_obj(obj: MemoryObj) -> TensorMemoryObj:
+    assert isinstance(obj, TensorMemoryObj), (
+        "Only TensorMemoryObj is supported in this mock adapter"
+    )
+    raw_tensor = obj.raw_tensor
+    assert raw_tensor is not None, (
+        "The tensor data of the object cannot be None for cloning"
+    )
+
+    new_obj = TensorMemoryObj(
+        raw_data=raw_tensor.detach().clone(),
+        metadata=copy.deepcopy(obj.metadata),
+        parent_allocator=None,
+    )
+
+    return new_obj
+
+
+# Config class
+
+
+class MockL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for a mock L2 adapter (for testing).
+
+    Fields:
+    - max_size_gb: maximum size in GB.
+    - mock_bandwidth_gb: simulated bandwidth in GB/sec.
+    """
+
+    def __init__(
+        self,
+        max_size_gb: float,
+        mock_bandwidth_gb: float,
+    ):
+        self.max_size_gb = max_size_gb
+        self.mock_bandwidth_gb = mock_bandwidth_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "MockL2AdapterConfig":
+        max_size_gb = d.get("max_size_gb")
+        if not isinstance(max_size_gb, (int, float)) or max_size_gb <= 0:
+            raise ValueError("max_size_gb must be a positive number")
+
+        mock_bandwidth_gb = d.get("mock_bandwidth_gb")
+        if not isinstance(mock_bandwidth_gb, (int, float)) or mock_bandwidth_gb <= 0:
+            raise ValueError("mock_bandwidth_gb must be a positive number")
+
+        return cls(
+            max_size_gb=max_size_gb,
+            mock_bandwidth_gb=mock_bandwidth_gb,
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Mock L2 adapter config fields:\n"
+            "- max_size_gb (float): maximum size of "
+            "the adapter in GB (required, >0)\n"
+            "- mock_bandwidth_gb (float): simulated "
+            "bandwidth in GB/sec (required, >0)"
+        )
+
+
+# Main class
+
+
+class MockL2Adapter(L2AdapterInterface):
+    """
+    A mock-up L2 adapter with a specific RAM size and mocked bandwidth
+    """
+
+    def __init__(self, config: MockL2AdapterConfig):
+        max_capacity_bytes = int(config.max_size_gb * (1024**3))
+        super().__init__(max_capacity_bytes=max_capacity_bytes)
+        self._config = config
+        self._bandwidth_byte_ps = int(config.mock_bandwidth_gb * (1024**3))
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        self._memory_objects: dict[ObjectKey, MemoryObj] = {}
+        self._locked_keys: dict[ObjectKey, int] = defaultdict(int)
+        self._current_size_bytes: int = 0
+
+        # Task ID management
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+        self._lock = threading.Lock()  # lock for all shared state
+
+        # Asyncio event loop running in a background thread
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(target=self._run_event_loop, daemon=True)
+        self._loop_thread.start()
+
+    # --------------------
+    # Event Fd Interface
+    # --------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    # --------------------
+    # Store Interface
+    # --------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """
+        Submit a store task to store a batch of memory objects associated with
+        a batch of keys.
+
+        For the mock adapter, the store operation simulates bandwidth-limited
+        transfer by delaying completion based on object size and configured bandwidth.
+
+        Args:
+            keys (list[ObjectKey]): the list of keys to be stored.
+            objects (list[MemoryObj]): the list of memory objects to be stored.
+                The length of the objects list should be the same as the length of
+                the keys list.
+
+        Returns:
+            L2TaskId: the task id of the submitted store task.
+        """
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_store_in_the_loop(keys, objects, task_id), self._loop
+        )
+
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        """
+        Pop all the completed store tasks with their results.
+
+        Returns:
+            dict[L2TaskId, L2StoreResult]: a dictionary mapping the task id to
+            an L2StoreResult encoding success/failure and bytes transferred.
+        """
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        # Schedule the lookup operation in the event loop thread
+        self._loop.call_soon_threadsafe(self._execute_lookup_in_the_loop, keys, task_id)
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        def _unlock_keys(keys: list[ObjectKey]) -> None:
+            """
+            Coroutine to unlock keys in the event loop thread.
+            This is a helper function to avoid blocking the main thread.
+            """
+            for key in keys:
+                if key not in self._locked_keys:
+                    continue
+                if self._locked_keys[key] <= 1:
+                    del self._locked_keys[key]
+                else:
+                    self._locked_keys[key] -= 1
+
+        # Schedule the unlock operation in the event loop thread
+        self._loop.call_soon_threadsafe(_unlock_keys, keys)
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        # Schedule the load operation in the event loop thread
+        asyncio.run_coroutine_threadsafe(
+            self._execute_load_in_loop(keys, objects, task_id), self._loop
+        )
+
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    def close(self):
+        # Stop the event loop and wait for the thread to finish
+        async def _stop_tasks():
+            tasks = [
+                t
+                for t in asyncio.all_tasks(self._loop)
+                if t is not asyncio.current_task()
+            ]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            future = asyncio.run_coroutine_threadsafe(_stop_tasks(), self._loop)
+            try:
+                future.result(timeout=5)  # Wait for tasks to be cancelled
+            except Exception:
+                pass  # Ignore exceptions during shutdown
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._loop_thread.join()
+        self._loop.close()
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+    ##################
+    # Debug / test-only functions
+    ##################
+
+    def report_status(self) -> dict:
+        """Return a status dict for the mock L2 adapter."""
+        with self._lock:
+            return {
+                "is_healthy": True,
+                "type": "MockL2Adapter",
+                "stored_object_count": len(self._memory_objects),
+                "locked_key_count": len(self._locked_keys),
+                "current_size_bytes": self._current_size_bytes,
+                "max_capacity_bytes": self._max_capacity_bytes,
+            }
+
+    def debug_get_stored_object_count(self) -> int:
+        """
+        Return the number of objects currently stored in the mock adapter.
+
+        This method is intended for testing and debugging only.
+
+        Returns:
+            int: Number of stored objects.
+        """
+        with self._lock:
+            return len(self._memory_objects)
+
+    def debug_get_locked_key_count(self) -> int:
+        """
+        Return the number of currently locked keys.
+
+        This method is intended for testing and debugging only.
+
+        Returns:
+            int: Number of locked keys.
+        """
+        with self._lock:
+            return len(self._locked_keys)
+
+    def debug_has_key(self, key: ObjectKey) -> bool:
+        """
+        Check whether a specific key is stored in the mock adapter.
+
+        This method is intended for testing and debugging only.
+
+        Args:
+            key: The object key to check.
+
+        Returns:
+            bool: True if the key is stored.
+        """
+        with self._lock:
+            return key in self._memory_objects
+
+    ##################
+    # Helper functions
+    ##################
+
+    def _run_event_loop(self) -> None:
+        """Run the asyncio event loop in a background thread."""
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _get_next_task_id(self) -> L2TaskId:
+        """Get the next task ID and increment the counter."""
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    #####################
+    # Eviction Interface
+    #####################
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """Delete a batch of objects from the mock adapter."""
+        deleted_keys: list[ObjectKey] = []
+        deleted_sizes: list[int] = []
+        with self._lock:
+            for key in keys:
+                if key not in self._memory_objects:
+                    continue
+                obj = self._memory_objects.pop(key)
+                size = obj.get_size()
+                self._current_size_bytes -= size
+                deleted_keys.append(key)
+                deleted_sizes.append(size)
+        if deleted_keys:
+            self._notify_keys_deleted(deleted_keys, deleted_sizes)
+
+    # ``get_usage()`` is inherited from ``L2AdapterInterface``, which derives
+    # the report from the byte counters maintained by ``_notify_keys_*``.
+    # ``_current_size_bytes`` above is a local within-batch accumulator
+    # used for the synchronous capacity check inside the store loop and is
+    # NOT the source of truth for external reporting.
+
+    def _signal_store_event(self) -> None:
+        """Signal the store event fd to notify completion."""
+        self._store_efd.notify()
+
+    async def _execute_store_in_the_loop(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        """
+        Execute the store operation in the event loop thread.
+        This is a helper function to avoid blocking the main thread.
+        """
+        total_bytes = 0
+        success = True
+        start = time.perf_counter()
+
+        stored_keys: list[ObjectKey] = []
+        stored_sizes: list[int] = []
+        try:
+            for key, obj in zip(keys, objects, strict=True):
+                obj_size = obj.get_size()
+
+                # If the object is larger than max capacity, skip it
+                if obj_size > self._max_capacity_bytes:
+                    continue
+
+                # If key already exists, simply skip
+                if key in self._memory_objects:
+                    continue
+
+                # Skip if there is not enough capacity
+                if self._current_size_bytes + obj_size > self._max_capacity_bytes:
+                    logger.warning(
+                        "MockL2Adapter: not enough capacity to store key %s "
+                        "(used=%d, needed=%d, max=%d); skipping.",
+                        key,
+                        self._current_size_bytes,
+                        obj_size,
+                        self._max_capacity_bytes,
+                    )
+                    continue
+
+                # Store the object
+                new_obj = clone_tensor_memory_obj(obj)
+                self._memory_objects[key] = new_obj
+                self._current_size_bytes += obj_size
+                total_bytes += obj_size
+                stored_keys.append(key)
+                stored_sizes.append(obj_size)
+        except Exception:
+            success = False
+
+        # Calculate delay based on bandwidth simulation
+        end = time.perf_counter()
+        delay_seconds = (
+            total_bytes / self._bandwidth_byte_ps if self._bandwidth_byte_ps > 0 else 0
+        )
+        delay_seconds -= end - start
+        delay_seconds = max(delay_seconds, 0)  # Ensure non-negative delay
+
+        # Schedule completion coroutine on the event loop
+        await asyncio.sleep(delay_seconds)
+        with self._lock:
+            # ``total_bytes`` counts only objects actually written into
+            # ``self._memory_objects`` — duplicates and capacity-skipped
+            # keys are excluded.  Reporting this lets the L2 throughput
+            # subscriber distinguish real I/O from fast-pathed no-ops.
+            self._completed_store_tasks[task_id] = L2StoreResult(success, total_bytes)
+
+        if stored_keys:
+            self._notify_keys_stored(stored_keys, stored_sizes)
+        self._signal_store_event()
+
+    def _signal_lookup_event(self) -> None:
+        """Signal the lookup event fd to notify completion."""
+        self._lookup_efd.notify()
+
+    def _execute_lookup_in_the_loop(
+        self, keys: list[ObjectKey], task_id: L2TaskId
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        for i, key in enumerate(keys):
+            if key not in self._memory_objects:
+                continue
+            bitmap.set(i)
+            self._locked_keys[key] += 1
+        with self._lock:
+            self._completed_lookup_tasks[task_id] = bitmap
+        self._signal_lookup_event()
+
+    def _signal_load_event(self) -> None:
+        """Signal the load event fd to notify completion."""
+        self._load_efd.notify()
+
+    async def _execute_load_in_loop(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        """
+        Execute the load operation in the event loop thread.
+        This is a helper function to avoid blocking the main thread.
+        """
+        bitmap = Bitmap(len(keys))
+        total_bytes = 0
+        accessed_keys: list[ObjectKey] = []
+        start = time.perf_counter()
+
+        for i, key in enumerate(keys):
+            if key not in self._memory_objects:
+                continue
+            # load data into the provided memory object
+            obj = self._memory_objects[key]
+            src_tensor = obj.tensor
+            dst_tensor = objects[i].tensor
+            assert src_tensor is not None
+            assert dst_tensor is not None
+            dst_tensor.copy_(src_tensor)
+            bitmap.set(i)
+            total_bytes += obj.get_size()
+            accessed_keys.append(key)
+
+        end = time.perf_counter()
+        delay_seconds = (
+            total_bytes / self._bandwidth_byte_ps if self._bandwidth_byte_ps > 0 else 0
+        )
+        delay_seconds -= end - start
+        delay_seconds = max(delay_seconds, 0)  # Ensure non-negative delay
+
+        await asyncio.sleep(delay_seconds)
+        if accessed_keys:
+            self._notify_keys_accessed(accessed_keys)
+        with self._lock:
+            self._completed_load_tasks[task_id] = bitmap
+        self._signal_load_event()
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("mock", MockL2AdapterConfig)
+
+
+def _create_mock_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Create a MockL2Adapter from config."""
+    return MockL2Adapter(config)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("mock", _create_mock_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/mooncake_store_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/mooncake_store_l2_adapter.py
new file mode 100644
index 0000000..8225494
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/mooncake_store_l2_adapter.py
@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Mooncake Store native L2 adapter config and factory.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+    from lmcache.v1.distributed.l2_adapters.base import (
+        L2AdapterInterface,
+    )
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+
+logger = init_logger(__name__)
+
+# Keys consumed only by LMCache (never sent to mooncake).
+_LMCACHE_ONLY_KEYS = {
+    "type",
+    "num_workers",
+    "eviction",
+    "per_op_workers",
+}
+
+
+class MooncakeStoreL2AdapterConfig(L2AdapterConfigBase):
+    """Config for an L2 adapter backed by the native
+    C++ Mooncake Store connector.
+
+    ``setup_config`` is a string-to-string dict forwarded
+    **as-is** to mooncake's
+    ``RealClient::setup_internal(ConfigDict)``.
+    LMCache does NOT interpret, validate, or fill in
+    defaults for any mooncake keys — that is mooncake's
+    responsibility.
+
+    Fields:
+        setup_config: Mooncake SDK configuration forwarded
+            as-is to ``RealClient::setup_internal()``.
+        num_workers: Shared worker thread count (default 4,
+            must be > 0).  Used for any op whose lane key
+            is not present in ``per_op_workers``.
+        per_op_workers: Optional dict mapping lane keys
+            (``"lookup"``, ``"retrieve"``, ``"store"``,
+            ``"delete"``) to dedicated worker counts.  Ops
+            not mentioned use the shared ``num_workers`` pool.
+    """
+
+    def __init__(
+        self,
+        setup_config: dict[str, str],
+        num_workers: int = 4,
+        per_op_workers: dict[str, int] | None = None,
+    ):
+        super().__init__()
+        self.num_workers = L2AdapterConfigBase._validate_num_workers(num_workers)
+        self.per_op_workers = L2AdapterConfigBase._validate_per_op_workers(
+            per_op_workers
+        )
+        self.setup_config: dict[str, str] = dict(setup_config)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, object]) -> "MooncakeStoreL2AdapterConfig":
+        """Construct a config from a raw configuration dict.
+
+        LMCache-only keys (``type``, ``num_workers``, ``eviction``,
+        ``per_op_workers``) are consumed locally.  All other keys are
+        forwarded to mooncake as string values.
+
+        Args:
+            d: Raw configuration dict (typically from JSON/CLI).
+
+        Returns:
+            A validated ``MooncakeStoreL2AdapterConfig``.
+
+        Raises:
+            ValueError: If ``num_workers`` or ``per_op_workers`` values
+                are invalid.
+        """
+        num_workers = cast(int, d.get("num_workers", 4))  # validated in __init__
+
+        per_op_workers = L2AdapterConfigBase._parse_per_op_workers_from_dict(d)
+        # Everything except LMCache-only keys is
+        # forwarded to mooncake as str values.
+        setup: dict[str, str] = {}
+        for k, v in d.items():
+            if k in _LMCACHE_ONLY_KEYS:
+                continue
+            if v is not None:
+                setup[k] = str(v)
+
+        return cls(
+            setup_config=setup,
+            num_workers=num_workers,
+            per_op_workers=per_op_workers,
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Mooncake Store L2 adapter config.\n"
+            "All keys except LMCache-only keys are "
+            "forwarded as-is to mooncake's "
+            "setup_internal(ConfigDict).\n"
+            "When protocol=rdma, LMCache must provide "
+            "a valid L1 memory descriptor for "
+            "preregistration.\n"
+            "Refer to mooncake documentation for "
+            "available setup keys.\n"
+            "- num_workers (int): C++ worker threads "
+            "(default 4, >0). Used for ops not in "
+            "per_op_workers.\n"
+            "- per_op_workers (dict[str, int]): Optional "
+            "dict mapping lane keys to dedicated worker "
+            "counts. Valid keys: lookup, retrieve, "
+            "store, delete. Ops not mentioned use the "
+            "shared num_workers pool."
+        )
+
+
+def _create_mooncake_store_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "L1MemoryDesc | None" = None,
+) -> L2AdapterInterface:
+    """Create a NativeConnectorL2Adapter backed by the
+    C++ Mooncake Store connector.
+
+    When ``config.setup_config["protocol"] == "rdma"``,
+    a valid ``l1_memory_desc`` must be provided so the
+    native Mooncake client can preregister the L1 memory
+    region for RDMA access.
+
+    Raises:
+        RuntimeError: If the native C++ Mooncake extension
+            is unavailable.
+        ValueError: If RDMA protocol is requested but
+            ``l1_memory_desc`` is missing or invalid.
+    """
+    try:
+        # First Party
+        from lmcache.lmcache_mooncake import (
+            L1RegistrationConfig,
+            LMCacheMooncakeClient,
+        )
+    except ImportError as e:
+        raise RuntimeError(
+            "Mooncake Store L2 adapter requires the "
+            "C++ Mooncake extension. Build with: "
+            "MOONCAKE_INCLUDE_DIR=/path/to/mooncake-"
+            "store/include pip install -e ."
+        ) from e
+
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (  # noqa: E501
+        NativeConnectorL2Adapter,
+    )
+
+    if not isinstance(config, MooncakeStoreL2AdapterConfig):
+        raise ValueError(f"Expected MooncakeStoreL2AdapterConfig, got {type(config)}")
+    l1_registration = L1RegistrationConfig()
+    if config.setup_config.get("protocol") == "rdma":
+        if l1_memory_desc is None:
+            raise ValueError(
+                "RDMA protocol is enabled, but no L1 memory descriptor "
+                "was provided; cannot create Mooncake Store L2 adapter."
+            )
+        elif l1_memory_desc.ptr == 0 or l1_memory_desc.size <= 0:
+            raise ValueError(
+                "RDMA protocol is enabled, but the L1 memory descriptor "
+                "is invalid (ptr=%d, size=%d); cannot create Mooncake Store L2 adapter."
+                % (l1_memory_desc.ptr, l1_memory_desc.size)
+            )
+        else:
+            l1_registration.enabled = True
+            l1_registration.base = l1_memory_desc.ptr
+            l1_registration.size = l1_memory_desc.size
+
+    native_client = LMCacheMooncakeClient(
+        config=config.setup_config,
+        num_workers=config.num_workers,
+        l1_registration=l1_registration,
+        per_op_workers=config.per_op_workers,
+    )
+    logger.info(
+        "Created Mooncake Store L2 adapter "
+        "(workers=%d, per_op_workers=%s, preregister_l1_memory=%s)",
+        config.num_workers,
+        config.per_op_workers,
+        l1_registration.enabled and l1_registration.size > 0,
+    )
+    return NativeConnectorL2Adapter(native_client)
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("mooncake_store", MooncakeStoreL2AdapterConfig)
+register_l2_adapter_factory("mooncake_store", _create_mooncake_store_l2_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py
new file mode 100644
index 0000000..c10d380
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py
@@ -0,0 +1,536 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+L2 adapter that wraps any pybind-wrapped C++ IStorageConnector (native client).
+
+This bridge lets any native storage connector (Redis, RDMA, Mooncake, etc.)
+serve as an MP-mode L2 adapter.  The same C++ connector implementation is
+also usable in non-MP mode via ConnectorClientBase.
+
+Architecture:
+  - The native client has 1 eventfd + drain_completions() for all operations.
+  - This adapter creates 3 Python eventfds (store, lookup, load) and runs a
+    background demux thread that routes native completions to the right
+    category based on a future_id → op_type mapping.
+  - ObjectKey serialization and MemoryObj buffer extraction happen at the
+    submit call boundary.
+  - Locking is client-side (refcount dict) since remote backends don't have
+    our eviction concept.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import defaultdict
+from typing import Any
+import select
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+
+# Key separator — kept in sync with fs_l2_adapter.py and
+# csrc/storage_backends/fs/connector.cpp. Both ``@`` in ``model_name``
+# and ``@`` in ``cache_salt`` are rejected by ObjectKey.__post_init__
+# so splitting on ``@`` is unambiguous.
+_KEY_SEP = "@"
+
+
+def _object_key_to_string(key: ObjectKey) -> str:
+    """Serialize an ObjectKey to the native-connector wire format.
+
+    Unsalted::
+
+        <model_name>@<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>
+
+    Salted (trailing ``cache_salt``)::
+
+        <model_name>@<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>@<cache_salt>
+    """
+    base = (
+        f"{key.model_name}{_KEY_SEP}{key.kv_rank:08x}"
+        f"{_KEY_SEP}{key.object_group_id:x}{_KEY_SEP}{key.chunk_hash.hex()}"
+    )
+    if key.cache_salt:
+        return f"{base}{_KEY_SEP}{key.cache_salt}"
+    return base
+
+
+def _obj_to_memoryview(
+    obj: MemoryObj,
+) -> memoryview:  # type: ignore[type-arg]
+    """
+    Extract a byte-oriented memoryview from a MemoryObj.
+
+    Uses the MemoryObj's byte_array property which returns
+    a ctypes-backed memoryview with itemsize=1, so pybind's
+    buffer_info.size == num_bytes.
+    """
+    return obj.byte_array  # type: ignore[return-value]
+
+
+class NativeConnectorL2Adapter(L2AdapterInterface):
+    """
+    Wraps a pybind-wrapped C++ IStorageConnector to
+    implement L2AdapterInterface.
+
+    The native_client must expose:
+      - event_fd() -> int
+      - submit_batch_get(keys, memoryviews) -> int
+      - submit_batch_set(keys, memoryviews) -> int
+      - submit_batch_exists(keys) -> int
+      - drain_completions()
+          -> list[tuple[int, bool, str, list[bool]|None]]
+      - close()
+    """
+
+    # Operation type tags for the pending-ops map
+    _OP_STORE = "store"
+    _OP_LOOKUP = "lookup"
+    _OP_LOAD = "load"
+    _OP_DELETE = "delete"
+
+    def __init__(
+        self,
+        native_client: Any,
+        max_capacity_gb: float = 0,
+        type_name: str = "",
+        extra_status: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(max_capacity_bytes=int(max_capacity_gb * (1024**3)))
+        self._client = native_client
+        self._client_fd: int = int(native_client.event_fd())
+        self._type_name: str = type_name or type(native_client).__name__
+        self._extra_status: dict[str, Any] = dict(extra_status or {})
+
+        # 3 distinct cross-platform notifiers for the L2 adapter
+        # interface
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        # Pending ops: native future_id →
+        #   (op_type, task_id, num_keys, keys_for_locking)
+        # keys_for_locking is only set for lookup ops so
+        # we can apply locks
+        self._pending_ops: dict[
+            int,
+            tuple[str, L2TaskId, int, list[ObjectKey] | None],
+        ] = {}
+
+        # Completed results (same pattern as MockL2Adapter)
+        self._completed_stores: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookups: dict[L2TaskId, Bitmap] = {}
+        self._completed_loads: dict[L2TaskId, Bitmap] = {}
+
+        # Client-side lock tracking (refcount per key)
+        self._locked_keys: dict[ObjectKey, int] = defaultdict(int)
+
+        # Delete capability detection
+        self._has_delete = callable(getattr(native_client, "submit_batch_delete", None))
+
+        # Pending delete events for synchronous delete() calls
+        self._pending_delete_events: dict[L2TaskId, threading.Event] = {}
+
+        # Per-key size tracking. ``_key_sizes`` lets us look up byte sizes
+        # at delete time (the native completion only carries booleans, not
+        # sizes) so we can pass them to ``_notify_keys_deleted``. Aggregate
+        # and per-user totals live in the base class — see ``get_usage``.
+        self._key_sizes: dict[ObjectKey, int] = {}
+        # Pending store sizes: native future_id -> (keys, per_key_sizes).
+        # Bridges the async store submit → demux completion gap so the
+        # demux thread can fire ``_notify_keys_stored(keys, sizes)``.
+        self._pending_store_sizes: dict[int, tuple[list[ObjectKey], list[int]]] = {}
+
+        # Task ID counter
+        self._next_task_id: L2TaskId = 0
+
+        # Lock for all shared state above
+        self._lock = threading.Lock()
+
+        # Background demux thread
+        self._stop = threading.Event()
+        self._demux_thread = threading.Thread(
+            target=self._demux_loop,
+            daemon=True,
+            name="l2-adapter-demux",
+        )
+        self._demux_thread.start()
+
+    # ---------------------------------------------------------------
+    # Event Fd Interface
+    # ---------------------------------------------------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    # ---------------------------------------------------------------
+    # Store Interface
+    # ---------------------------------------------------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        key_strings = [_object_key_to_string(k) for k in keys]
+        memviews = [_obj_to_memoryview(obj) for obj in objects]
+        per_key_sizes = [obj.get_size() for obj in objects]
+
+        # Register pending op BEFORE submit to avoid race
+        # with demux thread. The native submit is
+        # non-blocking so holding the lock is brief.
+        with self._lock:
+            task_id = self._get_next_task_id()
+            future_id = int(self._client.submit_batch_set(key_strings, memviews))
+            self._pending_ops[future_id] = (
+                self._OP_STORE,
+                task_id,
+                len(keys),
+                None,
+            )
+            self._pending_store_sizes[future_id] = (list(keys), per_key_sizes)
+
+        return task_id
+
+    def pop_completed_store_tasks(
+        self,
+    ) -> dict[L2TaskId, L2StoreResult]:
+        with self._lock:
+            completed = self._completed_stores
+            self._completed_stores = {}
+        return completed
+
+    # ---------------------------------------------------------------
+    # Lookup and Lock Interface
+    # ---------------------------------------------------------------
+
+    def submit_lookup_and_lock_task(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+    ) -> L2TaskId:
+        key_strings = [_object_key_to_string(k) for k in keys]
+
+        with self._lock:
+            task_id = self._get_next_task_id()
+            future_id = int(self._client.submit_batch_exists(key_strings))
+            self._pending_ops[future_id] = (
+                self._OP_LOOKUP,
+                task_id,
+                len(keys),
+                list(keys),
+            )
+
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_lookups.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        with self._lock:
+            for key in keys:
+                if key not in self._locked_keys:
+                    continue
+                if self._locked_keys[key] <= 1:
+                    del self._locked_keys[key]
+                else:
+                    self._locked_keys[key] -= 1
+
+    # ---------------------------------------------------------------
+    # Load Interface
+    # ---------------------------------------------------------------
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        key_strings = [_object_key_to_string(k) for k in keys]
+        memviews = [_obj_to_memoryview(obj) for obj in objects]
+
+        with self._lock:
+            task_id = self._get_next_task_id()
+            future_id = int(self._client.submit_batch_get(key_strings, memviews))
+            self._pending_ops[future_id] = (
+                self._OP_LOAD,
+                task_id,
+                len(keys),
+                list(keys),
+            )
+
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_loads.pop(task_id, None)
+
+    # ---------------------------------------------------------------
+    # Eviction Interface
+    # ---------------------------------------------------------------
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """Delete a batch of keys from the remote backend.
+
+        Submits a batch delete to the native connector and blocks
+        until the demux thread signals completion (up to 30s timeout).
+        Fires ``_notify_keys_deleted`` on success so eviction policy
+        tracking stays in sync.
+
+        No-op if the connector does not expose ``submit_batch_delete``
+        or if the key list is empty.
+        """
+        if not keys or not self._has_delete:
+            return
+
+        key_strings = [_object_key_to_string(k) for k in keys]
+        done_event = threading.Event()
+
+        with self._lock:
+            task_id = self._get_next_task_id()
+            future_id = int(self._client.submit_batch_delete(key_strings))
+            self._pending_ops[future_id] = (
+                self._OP_DELETE,
+                task_id,
+                len(keys),
+                list(keys),
+            )
+            self._pending_delete_events[task_id] = done_event
+
+        # Block until demux thread signals completion
+        if not done_event.wait(timeout=30.0):
+            with self._lock:
+                self._pending_delete_events.pop(task_id, None)
+                # Note: _pending_ops entry may already be consumed
+                # by the demux thread; pop is safe either way.
+                for fid, entry in list(self._pending_ops.items()):
+                    if entry[1] == task_id:
+                        self._pending_ops.pop(fid, None)
+                        break
+            logger.warning(
+                "delete() timed out after 30s for %d keys",
+                len(keys),
+            )
+            return
+
+        # ``_notify_keys_deleted`` is fired by the demux thread (with
+        # accurate per-key sizes drawn from ``_key_sizes``) when the
+        # backend reports per-key deletion results, so we don't notify
+        # again here.
+
+    # ``get_usage()`` is inherited from ``L2AdapterInterface``. The base
+    # class tracks aggregate + per-user totals via ``_notify_keys_*``;
+    # we feed it the byte sizes from each store/delete completion.
+
+    # ---------------------------------------------------------------
+    # Status Interface
+    # ---------------------------------------------------------------
+
+    def report_status(self) -> dict[str, Any]:
+        """Return a status dict for this native-connector L2 adapter.
+
+        Returns:
+            A dict with at minimum:
+              * ``is_healthy`` (bool): ``True`` while the background demux
+                thread is alive and not stopping.
+              * ``type`` (str): Stable adapter type label, supplied by the
+                factory or derived from the native client class name.
+            Plus any caller-supplied ``extra_status`` fields (e.g. backend
+            configuration like ``base_path``, ``num_workers``).
+        """
+        status: dict[str, Any] = {
+            "is_healthy": (self._demux_thread.is_alive() and not self._stop.is_set()),
+            "type": self._type_name,
+        }
+        status.update(self._extra_status)
+        return status
+
+    # ---------------------------------------------------------------
+    # Cleanup
+    # ---------------------------------------------------------------
+
+    def close(self) -> None:
+        self._stop.set()
+        self._demux_thread.join(timeout=5)
+
+        self._client.close()
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+    # ---------------------------------------------------------------
+    # Internal helpers
+    # ---------------------------------------------------------------
+
+    def _get_next_task_id(self) -> L2TaskId:
+        """Increment and return the next task ID.
+        Must be called under _lock."""
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    def _demux_loop(self) -> None:
+        """Background thread that polls the native
+        connector's eventfd, drains completions, and
+        routes them to the correct L2 result category.
+        """
+        poller = select.poll()
+        poller.register(self._client_fd, select.POLLIN)
+
+        while not self._stop.is_set():
+            events = poller.poll(500)
+            if not events:
+                continue
+
+            try:
+                completions = self._client.drain_completions()
+            except Exception:
+                logger.exception("drain_completions failed")
+                continue
+
+            if not completions:
+                continue
+
+            # Collect listener notifications to fire after
+            # releasing the lock. Sizes are collected in parallel so
+            # ``_notify_keys_*`` can update the base class's byte
+            # accounting in one shot.
+            keys_stored: list[ObjectKey] = []
+            sizes_stored: list[int] = []
+            keys_accessed: list[ObjectKey] = []
+            keys_deleted: list[ObjectKey] = []
+            sizes_deleted: list[int] = []
+            # Events for synchronous ``delete()`` callers. We set these
+            # AFTER firing ``_notify_keys_deleted`` below so that when
+            # the caller unblocks and calls ``get_usage()``, the base
+            # class's byte counters already reflect the deletion.
+            delete_done_events: list[threading.Event] = []
+
+            with self._lock:
+                for (
+                    future_id,
+                    ok,
+                    error,
+                    result_bools,
+                ) in completions:
+                    fid = int(future_id)
+                    entry = self._pending_ops.pop(fid, None)
+                    if entry is None:
+                        logger.warning(
+                            "Received completion for unknown future_id=%d",
+                            fid,
+                        )
+                        continue
+
+                    (
+                        op_type,
+                        task_id,
+                        num_keys,
+                        lookup_keys,
+                    ) = entry
+
+                    if op_type == self._OP_STORE:
+                        store_info = self._pending_store_sizes.pop(fid, None)
+                        task_bytes = 0
+                        if ok and store_info is not None:
+                            store_keys, sizes = store_info
+                            for key, size in zip(store_keys, sizes, strict=True):
+                                # First-store wins for byte accounting:
+                                # a re-store of an existing key adds 0
+                                # bytes (the backend already holds it).
+                                # We still notify the listener for every
+                                # store so LRU policies can ``move_to_end``
+                                # on re-store — passing size=0 in that
+                                # case is a no-op for the base counters.
+                                if key not in self._key_sizes:
+                                    self._key_sizes[key] = size
+                                    keys_stored.append(key)
+                                    sizes_stored.append(size)
+                                    task_bytes += size
+                                else:
+                                    keys_stored.append(key)
+                                    sizes_stored.append(0)
+                        self._completed_stores[task_id] = L2StoreResult(ok, task_bytes)
+                        self._store_efd.notify()
+
+                    elif op_type == self._OP_LOOKUP:
+                        bitmap = Bitmap(num_keys)
+                        if ok and result_bools is not None:
+                            for i, found in enumerate(result_bools):
+                                if found:
+                                    bitmap.set(i)
+                                    if lookup_keys is not None:
+                                        self._locked_keys[lookup_keys[i]] += 1
+                        self._completed_lookups[task_id] = bitmap
+                        self._lookup_efd.notify()
+
+                    elif op_type == self._OP_LOAD:
+                        bitmap = Bitmap(num_keys)
+                        loaded_keys: list[ObjectKey] = []
+                        if result_bools is not None:
+                            for i, loaded in enumerate(result_bools):
+                                if loaded:
+                                    bitmap.set(i)
+                                    if lookup_keys is not None:
+                                        loaded_keys.append(lookup_keys[i])
+                        elif ok:
+                            # Fallback for connectors that
+                            # do not report per-key results
+                            for i in range(num_keys):
+                                bitmap.set(i)
+                            if lookup_keys is not None:
+                                loaded_keys.extend(lookup_keys)
+                        keys_accessed.extend(loaded_keys)
+                        self._completed_loads[task_id] = bitmap
+                        self._load_efd.notify()
+
+                    elif op_type == self._OP_DELETE:
+                        if result_bools is not None and lookup_keys is not None:
+                            for i, deleted in enumerate(result_bools):
+                                if not deleted:
+                                    continue
+                                key = lookup_keys[i]
+                                # Only notify (with size) for keys we've
+                                # actually accounted for via a prior store.
+                                if key in self._key_sizes:
+                                    sizes_deleted.append(self._key_sizes.pop(key))
+                                    keys_deleted.append(key)
+                        evt = self._pending_delete_events.pop(task_id, None)
+                        if evt is not None:
+                            delete_done_events.append(evt)
+
+            # Fire listener notifications outside the lock so a slow
+            # listener cannot stall further demux iterations.
+            if keys_stored:
+                self._notify_keys_stored(keys_stored, sizes_stored)
+            if keys_accessed:
+                self._notify_keys_accessed(keys_accessed)
+            if keys_deleted:
+                self._notify_keys_deleted(keys_deleted, sizes_deleted)
+            # Unblock any synchronous ``delete()`` callers only AFTER
+            # ``_notify_keys_deleted`` has updated the base class byte
+            # accounting, so ``get_usage()`` never briefly reports stale
+            # (too-high) usage in the window between ``delete()``
+            # returning and the notify running.
+            for evt in delete_done_events:
+                evt.set()
diff --git a/lmcache/v1/distributed/l2_adapters/native_plugin_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/native_plugin_l2_adapter.py
new file mode 100644
index 0000000..aba5f08
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/native_plugin_l2_adapter.py
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Native plugin L2 adapter config and factory.
+
+Dynamically loads a third-party pybind-wrapped C++ connector
+and wraps it with ``NativeConnectorL2Adapter``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Any, Optional
+import importlib
+
+if TYPE_CHECKING:
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+
+logger = init_logger(__name__)
+
+
+class NativePluginL2AdapterConfig(L2AdapterConfigBase):
+    """Config for a native-plugin L2 adapter.
+
+    Dynamically loads a third-party pybind-wrapped C++
+    connector class and wraps it with
+    ``NativeConnectorL2Adapter``.
+
+    Fields:
+    - module_path: Dotted Python import path of the
+        module containing the connector class.
+    - class_name: Name of the connector class inside
+        *module_path*.
+    - adapter_params: Arbitrary dict forwarded to the
+        connector class constructor as keyword arguments.
+    """
+
+    def __init__(
+        self,
+        module_path: str,
+        class_name: str,
+        adapter_params: dict[str, Any] | None = None,
+        max_capacity_gb: float = 0,
+    ):
+        self.module_path = module_path
+        self.class_name = class_name
+        self.adapter_params = adapter_params or {}
+        self.max_capacity_gb = max_capacity_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "NativePluginL2AdapterConfig":
+        module_path = d.get("module_path")
+        if not isinstance(module_path, str) or not module_path:
+            raise ValueError("module_path must be a non-empty string")
+
+        class_name = d.get("class_name")
+        if not isinstance(class_name, str) or not class_name:
+            raise ValueError("class_name must be a non-empty string")
+
+        adapter_params = d.get("adapter_params", {})
+        if not isinstance(adapter_params, dict):
+            raise ValueError("adapter_params must be a dict")
+
+        max_capacity_gb = d.get("max_capacity_gb", 0)
+        if not isinstance(max_capacity_gb, (int, float)) or max_capacity_gb < 0:
+            raise ValueError("max_capacity_gb must be a non-negative number")
+
+        return cls(
+            module_path=module_path,
+            class_name=class_name,
+            adapter_params=adapter_params,
+            max_capacity_gb=float(max_capacity_gb),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Native plugin L2 adapter config fields:\n"
+            "- module_path (str): dotted import path of "
+            "the module containing the connector "
+            "class (required)\n"
+            "- class_name (str): name of the connector "
+            "class inside the module (required)\n"
+            "- adapter_params (dict): forwarded as "
+            "kwargs to the connector constructor "
+            "(optional, default {})\n"
+            "\n"
+            "Example JSON:\n"
+            '{"type": "native_plugin", '
+            '"module_path": "my_ext.connector", '
+            '"class_name": "MyConnectorClient", '
+            '"adapter_params": '
+            '{"host": "localhost", "port": 1234}}\n'
+            "- max_capacity_gb (float): max L2 capacity "
+            "in GB for usage tracking / eviction "
+            "(default 0 = disabled)"
+        )
+
+
+def _create_native_plugin_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Dynamically load a third-party native connector
+    and wrap it with NativeConnectorL2Adapter."""
+    # Lazy import to avoid circular dependency
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (  # noqa: E501
+        NativeConnectorL2Adapter,
+    )
+
+    assert isinstance(config, NativePluginL2AdapterConfig)
+
+    try:
+        module = importlib.import_module(config.module_path)
+    except ImportError as e:
+        raise ImportError(
+            "Could not import module '%s': %s" % (config.module_path, e)
+        ) from e
+
+    try:
+        connector_cls = getattr(module, config.class_name)
+    except AttributeError as e:
+        raise AttributeError(
+            "Module '%s' has no class '%s': %s"
+            % (
+                config.module_path,
+                config.class_name,
+                e,
+            )
+        ) from e
+
+    native_client = connector_cls(**config.adapter_params)
+
+    # Verify the native client exposes the required
+    # interface methods.
+    required_methods = [
+        "event_fd",
+        "submit_batch_get",
+        "submit_batch_set",
+        "submit_batch_exists",
+        "drain_completions",
+        "close",
+    ]
+    try:
+        for method in required_methods:
+            if not callable(getattr(native_client, method, None)):
+                raise TypeError(
+                    "%s.%s instance missing required method "
+                    "'%s'"
+                    % (
+                        config.module_path,
+                        config.class_name,
+                        method,
+                    )
+                )
+    except TypeError:
+        # Close the connector to avoid resource leak
+        # when validation fails.
+        if callable(getattr(native_client, "close", None)):
+            native_client.close()
+        raise
+
+    if not callable(getattr(native_client, "submit_batch_delete", None)):
+        logger.warning(
+            "%s.%s does not expose submit_batch_delete; "
+            "L2 eviction delete will be a no-op.",
+            config.module_path,
+            config.class_name,
+        )
+
+    logger.info(
+        "Created native plugin L2 adapter: %s.%s (params=%s)",
+        config.module_path,
+        config.class_name,
+        config.adapter_params,
+    )
+    return NativeConnectorL2Adapter(
+        native_client, max_capacity_gb=config.max_capacity_gb
+    )
+
+
+register_l2_adapter_type("native_plugin", NativePluginL2AdapterConfig)
+register_l2_adapter_factory("native_plugin", _create_native_plugin_l2_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/nixl_store_dynamic_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/nixl_store_dynamic_l2_adapter.py
new file mode 100644
index 0000000..b51ade6
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/nixl_store_dynamic_l2_adapter.py
@@ -0,0 +1,886 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Dynamic-file-mode Nixl L2 adapter.
+
+Unlike the static ``NixlStoreL2Adapter`` which pre-allocates all storage
+files at init time, this adapter opens/registers files per operation.
+
+Atomic publish:
+- Stores DMA-write to a per-operation ``<final_path>.tmp.<uuid>`` and
+  atomically ``rename()`` to the final deterministic path on completion.
+  This guarantees that readers (including other processes sharing the
+  same directory) never observe a partially-written file.
+
+Persist (enabled by default via ``persist_enabled``, can be opted out):
+- Keeps data files on disk at shutdown (no metadata dump).
+
+Secondary lookup (always on):
+- Lookup always checks secondary storage (disk) on miss and lazily
+  populates the in-memory index when a file is found. File names are
+  derived deterministically from ObjectKey.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Optional
+import asyncio
+import os
+import threading
+import uuid
+
+# Third Party
+from nixl._api import nixl_agent as NixlAgent
+from nixl._api import nixl_agent_config as NixlAgentConfig
+from nixl._api import (
+    nixlBind,
+)
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L1MemoryDesc, L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface, L2TaskId
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.distributed.l2_adapters.nixl_store_l2_adapter import (
+    NixlStoreObj,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+
+# ---------------------------------------------------------------
+# ObjectKey <-> file path helpers
+# ---------------------------------------------------------------
+
+
+def _object_key_to_filename(key: ObjectKey) -> str:
+    """Derive a deterministic file name from an ObjectKey.
+
+    Replaces ``/`` in model names with ``--`` to avoid creating
+    subdirectories (e.g. ``meta-llama/Llama-3-8B`` becomes
+    ``meta-llama--Llama-3-8B``).
+    """
+    safe_model_name = key.model_name.replace("/", "--")
+    chunk_hex = key.chunk_hash.hex()
+    return (
+        f"{safe_model_name}_{key.kv_rank:08x}_{key.object_group_id:x}_{chunk_hex}.bin"
+    )
+
+
+# ---------------------------------------------------------------
+# Dynamic Nixl storage agent
+# ---------------------------------------------------------------
+
+
+class DynamicNixlStorageAgent:
+    """Nixl storage agent that opens/registers files per operation.
+
+    The L1 memory handler is registered once at init (same as the static
+    agent).  Storage files are registered on-demand for each store/load
+    and deregistered immediately after the transfer completes.
+    """
+
+    def __init__(
+        self,
+        device: str,
+        backend: str,
+        backend_params: dict[str, str],
+        l1_memory_desc: L1MemoryDesc,
+    ):
+        self.backend = backend
+        self.device = device
+        self.backend_params = backend_params
+        self.l1_align_bytes = l1_memory_desc.align_bytes
+        self.file_path = backend_params["file_path"]
+        os.makedirs(self.file_path, exist_ok=True)
+        self.use_direct_io = (
+            str(backend_params.get("use_direct_io", "false")).lower() == "true"
+        )
+
+        self.agent_name = "DynNixlAgent_" + str(uuid.uuid4())
+        nixl_conf = NixlAgentConfig(backends=[])
+        self.nixl_agent = NixlAgent(self.agent_name, nixl_conf)
+        self.nixl_agent.create_backend(backend, backend_params)
+
+        # Register L1 memory (same as static agent)
+        self._init_mem_handlers(
+            device,
+            l1_memory_desc.ptr,
+            l1_memory_desc.size,
+            l1_memory_desc.align_bytes,
+            device_id=0,
+        )
+
+    # ---- L1 memory registration (one-time) ----
+
+    def _init_mem_handlers(self, device, buffer_ptr, buffer_size, page_size, device_id):
+        reg_list = [(buffer_ptr, buffer_size, device_id, "")]
+        xfer_desc = [
+            (base_addr, page_size, device_id)
+            for base_addr in range(buffer_ptr, buffer_ptr + buffer_size, page_size)
+        ]
+
+        mem_type = "DRAM" if device == "cpu" else "VRAM"
+
+        self.mem_reg_descs = self.nixl_agent.register_memory(
+            reg_list, mem_type=mem_type
+        )
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type=mem_type)
+        self.mem_xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            "", xfer_descs, mem_type=mem_type
+        )
+
+    # ---- Per-operation file helpers ----
+
+    def _open_flags(self, create: bool) -> int:
+        """Return os.open flags for storage files."""
+        flags = os.O_RDWR
+        if create:
+            # O_TRUNC ensures any orphaned file from a previous crash
+            # is truncated, avoiding stale trailing bytes on disk.
+            flags |= os.O_CREAT | os.O_TRUNC
+        if self.use_direct_io and hasattr(os, "O_DIRECT"):
+            flags |= os.O_DIRECT
+        return flags
+
+    def _register_single_file(self, fd: int, file_size: int, page_size: int):
+        """Register a single file with nixl and return (reg_descs, xfer_handler).
+
+        Returns:
+            Tuple of (reg_descs, xfer_handler) for later cleanup.
+        """
+        num_pages = file_size // page_size
+
+        reg_list = [(0, file_size, fd, "")]
+        xfer_desc = [(offset * page_size, page_size, fd) for offset in range(num_pages)]
+
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type="FILE")
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type="FILE")
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            self.agent_name, xfer_descs, mem_type="FILE"
+        )
+        return reg_descs, xfer_handler
+
+    def _deregister_file(self, reg_descs, xfer_handler):
+        """Deregister a file from nixl."""
+        self.nixl_agent.release_dlist_handle(xfer_handler)
+        self.nixl_agent.deregister_memory(reg_descs)
+
+    async def dynamic_store_file(
+        self,
+        mem_indices: list[int],
+        file_path: str,
+        page_size: int,
+    ) -> None:
+        """Write-to-temp-then-rename to publish the final file atomically.
+
+        The DMA write goes to ``<file_path>.tmp.<uuid>`` in the same
+        directory. Only after the transfer completes successfully is the
+        temp file atomically renamed to the final path, ensuring that
+        concurrent readers (including other processes sharing the same
+        directory) never observe a partially-written file.
+        """
+        file_size = len(mem_indices) * page_size
+        tmp_path = f"{file_path}.tmp.{uuid.uuid4().hex}"
+        fd = os.open(tmp_path, self._open_flags(create=True))
+        try:
+            reg_descs, xfer_handler = self._register_single_file(
+                fd, file_size, page_size
+            )
+            try:
+                storage_indices = list(range(len(mem_indices)))
+                handle = self.nixl_agent.make_prepped_xfer(
+                    "WRITE",
+                    self.mem_xfer_handler,
+                    mem_indices,
+                    xfer_handler,
+                    storage_indices,
+                )
+                await self._post_non_blocking(handle)
+                self.nixl_agent.release_xfer_handle(handle)
+            finally:
+                self._deregister_file(reg_descs, xfer_handler)
+        except BaseException:
+            # Best-effort cleanup of the temp file on failure.
+            try:
+                os.unlink(tmp_path)
+            except FileNotFoundError:
+                pass
+            raise
+        finally:
+            os.close(fd)
+
+        # Atomic publish: readers only ever see a complete file at file_path.
+        # TODO(Jiayi): Only guaranteed to be atomic within the local posix filesystems.
+        os.rename(tmp_path, file_path)
+
+    async def dynamic_load_file(
+        self,
+        mem_indices: list[int],
+        file_path: str,
+        page_size: int,
+    ) -> None:
+        """Open an existing file, DMA read into L1 memory, then clean up."""
+        file_size = len(mem_indices) * page_size
+        fd = os.open(file_path, self._open_flags(create=False))
+        try:
+            reg_descs, xfer_handler = self._register_single_file(
+                fd, file_size, page_size
+            )
+            try:
+                storage_indices = list(range(len(mem_indices)))
+                handle = self.nixl_agent.make_prepped_xfer(
+                    "READ",
+                    self.mem_xfer_handler,
+                    mem_indices,
+                    xfer_handler,
+                    storage_indices,
+                )
+                await self._post_non_blocking(handle)
+                self.nixl_agent.release_xfer_handle(handle)
+            finally:
+                self._deregister_file(reg_descs, xfer_handler)
+        finally:
+            os.close(fd)
+
+    def dynamic_delete_file(self, file_path: str) -> None:
+        """Delete a storage file from disk."""
+        try:
+            os.unlink(file_path)
+        except FileNotFoundError:
+            logger.warning("File already deleted: %s", file_path)
+
+    # ---- Shared helpers ----
+
+    def get_memory_indices(self, raw_addr: int, mem_size: int) -> list[int]:
+        """Get L1 memory page indices for the given address and size."""
+        if raw_addr % self.l1_align_bytes != 0:
+            raise ValueError(
+                f"Raw address {raw_addr} is not aligned to "
+                f"page size {self.l1_align_bytes}"
+            )
+        if mem_size % self.l1_align_bytes != 0:
+            raise ValueError(
+                f"Memory size {mem_size} is not a multiple of "
+                f"page size {self.l1_align_bytes}"
+            )
+        num_pages = mem_size // self.l1_align_bytes
+        return [(raw_addr // self.l1_align_bytes + i) for i in range(num_pages)]
+
+    def get_file_path_for_key(self, key: ObjectKey) -> str:
+        """Return the full file path for a given ObjectKey."""
+        return os.path.join(self.file_path, _object_key_to_filename(key))
+
+    async def _post_non_blocking(self, handle):
+        """Await a nixl transfer until done."""
+        state = self.nixl_agent.transfer(handle)
+        while state != "DONE" and state != "ERR":
+            try:
+                state = self.nixl_agent.check_xfer_state(handle)
+            except nixlBind.nixlBackendError:
+                raise
+            await asyncio.sleep(0.01)
+        if state == "ERR":
+            raise RuntimeError("NIXL transfer failed")
+
+    def cleanup_temp_files(self) -> None:
+        """Remove leftover ``*.tmp.*`` files in the storage directory.
+
+        These can be left behind if a store crashed between opening the
+        temp file and the atomic rename. Called at shutdown as a best-effort
+        GC; orphans don't affect correctness because they're never matched
+        by the deterministic ``ObjectKey → filename`` mapping.
+        """
+        try:
+            entries = os.listdir(self.file_path)
+        except FileNotFoundError:
+            return
+        for name in entries:
+            # Temp suffix format: "<final_name>.tmp.<hex>"
+            if ".tmp." in name:
+                try:
+                    os.unlink(os.path.join(self.file_path, name))
+                except FileNotFoundError:
+                    pass
+                except OSError as e:
+                    logger.warning(
+                        "Failed to remove leftover temp file %s: %s", name, e
+                    )
+
+    def close(self):
+        """Release L1 memory handlers."""
+        self.nixl_agent.release_dlist_handle(self.mem_xfer_handler)
+        self.nixl_agent.deregister_memory(self.mem_reg_descs)
+
+
+# ---------------------------------------------------------------
+# Dynamic L2 adapter
+# ---------------------------------------------------------------
+
+
+class DynamicNixlStoreL2Adapter(L2AdapterInterface):
+    """Nixl L2 adapter using dynamic per-operation file registration.
+
+    Each store creates a new file on disk; each load re-opens the file.
+
+    When ``persist_enabled`` is True (the default), data files are kept
+    on disk at shutdown.  Lookup always checks secondary storage (disk)
+    for keys not in the in-memory index and populates the index lazily.
+    """
+
+    def __init__(
+        self,
+        config: DynamicNixlStoreL2AdapterConfig,
+        l1_memory_desc: L1MemoryDesc,
+    ):
+        max_capacity_gb = float(config.backend_params.get("max_capacity_gb", 0))
+        if max_capacity_gb <= 0:
+            raise ValueError("backend_params must include a positive 'max_capacity_gb'")
+        super().__init__(max_capacity_bytes=int(max_capacity_gb * (1024**3)))
+        self._config = config
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        # Cache data structures
+        self._memory_objects: dict[ObjectKey, NixlStoreObj] = {}
+        self._inflight_stores: set[ObjectKey] = set()
+        self._total_bytes: int = 0
+
+        # Task ID management
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+        self._lock = threading.Lock()
+
+        # Asyncio event loop running in a background thread
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(target=self._run_event_loop, daemon=True)
+        self._loop_thread.start()
+
+        # Initialize dynamic Nixl agent (L1 memory only, no pre-allocated files)
+        self.nixl_agent = DynamicNixlStorageAgent(
+            device="cpu",
+            backend=config.backend,
+            backend_params=config.backend_params,
+            l1_memory_desc=l1_memory_desc,
+        )
+
+        self._persist_enabled = config.persist_config.persist_enabled
+
+    # --------------------
+    # Event Fd Interface
+    # --------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    #####################
+    # Store Interface
+    #####################
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_store_in_the_loop(keys, objects, task_id), self._loop
+        )
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    #####################
+    # Lookup and Lock Interface
+    #####################
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        self._loop.call_soon_threadsafe(self._execute_lookup_in_the_loop, keys, task_id)
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        def _unlock_keys(keys: list[ObjectKey]) -> None:
+            for key in keys:
+                if (obj := self._memory_objects.get(key)) is not None:
+                    obj.decrease_pin_count()
+
+        self._loop.call_soon_threadsafe(_unlock_keys, keys)
+
+    #####################
+    # Load Interface
+    #####################
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_load_in_loop(keys, objects, task_id), self._loop
+        )
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    #####################
+    # Eviction Interface
+    #####################
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """Delete objects from storage, removing their files from disk."""
+        to_delete: list[tuple[ObjectKey, int, str]] = []
+        with self._lock:
+            for key in keys:
+                obj = self._memory_objects.get(key)
+                if obj is None:
+                    continue
+                if obj.pin_count > 0:
+                    logger.debug(
+                        "Skipping eviction of pinned key %s (pin_count=%d)",
+                        key,
+                        obj.pin_count,
+                    )
+                    continue
+                self._total_bytes -= obj.size
+                del self._memory_objects[key]
+                to_delete.append(
+                    (key, obj.size, self.nixl_agent.get_file_path_for_key(key))
+                )
+        # Filesystem I/O outside the lock to avoid blocking concurrent
+        # store/lookup/load operations.
+        deleted_keys: list[ObjectKey] = []
+        deleted_sizes: list[int] = []
+        for key, size, file_path in to_delete:
+            self.nixl_agent.dynamic_delete_file(file_path)
+            deleted_keys.append(key)
+            deleted_sizes.append(size)
+        if deleted_keys:
+            self._notify_keys_deleted(deleted_keys, deleted_sizes)
+
+    # ``get_usage`` is inherited from L2AdapterInterface; byte accounting
+    # is driven by ``_notify_keys_*`` through the base class now.
+
+    #####################
+    # Status Interface
+    #####################
+
+    def report_status(self) -> dict:
+        with self._lock:
+            stored_object_count = len(self._memory_objects)
+            pinned_object_count = sum(
+                1 for obj in self._memory_objects.values() if obj.pin_count > 0
+            )
+        return {
+            "is_healthy": self._loop_thread.is_alive(),
+            "type": "DynamicNixlStoreL2Adapter",
+            "backend": self._config.backend,
+            "stored_object_count": stored_object_count,
+            "pinned_object_count": pinned_object_count,
+            "event_loop_alive": self._loop_thread.is_alive(),
+        }
+
+    #####################
+    # Cleanup Interface
+    #####################
+
+    def close(self):
+        # Stop the event loop and wait for all in-flight tasks to finish
+        async def _stop_tasks():
+            tasks = [
+                t
+                for t in asyncio.all_tasks(self._loop)
+                if t is not asyncio.current_task()
+            ]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            future = asyncio.run_coroutine_threadsafe(_stop_tasks(), self._loop)
+            future.result(timeout=5)
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._loop_thread.join()
+        self._loop.close()
+
+        # If persist is enabled, keep data files on disk; otherwise clean up.
+        if self._persist_enabled:
+            logger.info("persist_enabled=True, keeping data files on disk")
+        else:
+            logger.info("persist_enabled=False, deleting all data files")
+            with self._lock:
+                for key in list(self._memory_objects.keys()):
+                    file_path = self.nixl_agent.get_file_path_for_key(key)
+                    self.nixl_agent.dynamic_delete_file(file_path)
+
+        # Best-effort cleanup of orphaned temp files from crashed stores.
+        self.nixl_agent.cleanup_temp_files()
+
+        self.nixl_agent.close()
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+    ##################
+    # Helper functions
+    ##################
+
+    def _run_event_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _get_next_task_id(self) -> L2TaskId:
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    def _signal_store_event(self) -> None:
+        self._store_efd.notify()
+
+    def _signal_lookup_event(self) -> None:
+        self._lookup_efd.notify()
+
+    def _signal_load_event(self) -> None:
+        self._load_efd.notify()
+
+    async def _execute_store_in_the_loop(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        """Store each key-object pair to its own file via dynamic DMA write."""
+        success = True
+        stored_keys: list[ObjectKey] = []
+        stored_sizes: list[int] = []
+        try:
+            for key, obj in zip(keys, objects, strict=False):
+                mem_addr = obj.meta.address
+                mem_size = obj.meta.phy_size
+
+                # Reserve the key and capacity under the lock *before*
+                # the DMA write so that concurrent coroutines (other
+                # stores, secondary lookups) see the reservation.
+                with self._lock:
+                    if key in self._memory_objects or key in self._inflight_stores:
+                        continue
+                    if self._total_bytes + mem_size > self._max_capacity_bytes:
+                        logger.warning(
+                            "Storage capacity exceeded, skipping store for key %s",
+                            key,
+                        )
+                        break
+                    self._inflight_stores.add(key)
+                    self._total_bytes += mem_size
+
+                try:
+                    mem_indices = self.nixl_agent.get_memory_indices(mem_addr, mem_size)
+                    file_path = self.nixl_agent.get_file_path_for_key(key)
+
+                    await self.nixl_agent.dynamic_store_file(
+                        mem_indices, file_path, self.nixl_agent.l1_align_bytes
+                    )
+
+                    store_obj = NixlStoreObj(
+                        page_indices=[],  # not used in dynamic mode
+                        size=mem_size,
+                        layout=MemoryLayoutDesc(
+                            [obj.meta.shape],
+                            [obj.meta.dtype],
+                        ),
+                        pin_count=1,
+                    )
+                    with self._lock:
+                        self._inflight_stores.discard(key)
+                        self._memory_objects[key] = store_obj
+                        store_obj.decrease_pin_count()
+                    stored_keys.append(key)
+                    stored_sizes.append(mem_size)
+                except Exception:
+                    # Un-reserve on failure so capacity accounting
+                    # stays correct.
+                    with self._lock:
+                        self._inflight_stores.discard(key)
+                        self._total_bytes -= mem_size
+                    raise
+
+        except Exception:
+            logger.exception("Dynamic NIXL store task %d failed", task_id)
+            success = False
+
+        if stored_keys:
+            self._notify_keys_stored(stored_keys, stored_sizes)
+
+        bytes_transferred = sum(stored_sizes)
+        with self._lock:
+            self._completed_store_tasks[task_id] = L2StoreResult(
+                success, bytes_transferred
+            )
+        self._signal_store_event()
+
+    def _execute_lookup_in_the_loop(
+        self, keys: list[ObjectKey], task_id: L2TaskId
+    ) -> None:
+        """Look up keys and pin found objects.
+
+        Also checks secondary storage (disk) for keys not in the
+        in-memory index and lazily populates ``_memory_objects`` for any
+        data files found on disk.
+        """
+        bitmap = Bitmap(len(keys))
+        # Keys populated by secondary lookup need a ``_notify_keys_stored``
+        # so the base class accounting stays in sync with disk state.
+        recovered_keys: list[ObjectKey] = []
+        recovered_sizes: list[int] = []
+        with self._lock:
+            for i, key in enumerate(keys):
+                obj = self._memory_objects.get(key)
+                if obj is None:
+                    obj = self._secondary_lookup_locked(key)
+                    if obj is not None:
+                        recovered_keys.append(key)
+                        recovered_sizes.append(obj.size)
+                if obj is None:
+                    continue
+                bitmap.set(i)
+                obj.increase_pin_count()
+            self._completed_lookup_tasks[task_id] = bitmap
+        if recovered_keys:
+            self._notify_keys_stored(recovered_keys, recovered_sizes)
+        self._signal_lookup_event()
+
+    def _secondary_lookup_locked(self, key: ObjectKey) -> NixlStoreObj | None:
+        """Check if a data file for ``key`` exists on disk; if so, populate
+        ``_memory_objects`` and return the entry. Caller must hold ``_lock``.
+
+        The file size is read via ``os.stat``. Layout is left as ``None`` and
+        will be supplied by the caller's MemoryObj at load time.
+        """
+        # Skip keys with an in-flight store to avoid double-counting
+        # in _total_bytes.
+        if key in self._inflight_stores:
+            return None
+        file_path = self.nixl_agent.get_file_path_for_key(key)
+        try:
+            obj_size = os.stat(file_path).st_size
+        except FileNotFoundError:
+            return None
+
+        # Enforce capacity when populating lazily too.
+        if self._total_bytes + obj_size > self._max_capacity_bytes:
+            logger.debug(
+                "Secondary lookup hit for %s but capacity exceeded, skipping",
+                key,
+            )
+            return None
+
+        obj = NixlStoreObj(
+            page_indices=[],  # not used in dynamic mode
+            size=obj_size,
+            layout=None,
+        )
+        self._memory_objects[key] = obj
+        self._total_bytes += obj_size
+        return obj
+
+    async def _execute_load_in_loop(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        """Execute a queued load task for ``task_id``.
+
+        For each requested key present in this adapter, read its stored
+        data into the caller-provided ``objects[i]`` and set bit ``i`` of
+        the result bitmap; keys that are missing or fail to load are left
+        unset. The bitmap is recorded under ``task_id`` (retrieve via
+        ``query_load_result``) and the load event fd is signaled.
+        """
+        bitmap = Bitmap(len(keys))
+        accessed_keys: list[ObjectKey] = []
+        try:
+            # Read every present key's file concurrently (asyncio.gather
+            # below) so a multi-chunk request does not pay per-file NIXL
+            # latency serially -- the dominant cost of a single-request load.
+            #
+            # TODO(perf): batch a request's files into one NIXL
+            # ``register_memory`` (a single transfer + single deregister),
+            # like the static adapter's pre-registered flat-index pool,
+            # instead of the current per-file register/transfer/deregister.
+            # Trade-off: one large per-request registration list vs. many
+            # small ones.
+            coros = []
+            found_positions: list[int] = []
+            for i, key in enumerate(keys):
+                with self._lock:
+                    storage_obj = self._memory_objects.get(key)
+                if storage_obj is None:
+                    continue
+
+                mem_addr = objects[i].meta.address
+                mem_size = objects[i].meta.phy_size
+                mem_indices = self.nixl_agent.get_memory_indices(mem_addr, mem_size)
+                file_path = self.nixl_agent.get_file_path_for_key(key)
+
+                coros.append(
+                    self.nixl_agent.dynamic_load_file(
+                        mem_indices, file_path, self.nixl_agent.l1_align_bytes
+                    )
+                )
+                found_positions.append(i)
+
+            if coros:
+                # return_exceptions=True so one chunk's failure doesn't
+                # discard the chunks that loaded successfully: mark each
+                # key by its own result rather than all-or-nothing.
+                results = await asyncio.gather(*coros, return_exceptions=True)
+                for pos, result in zip(found_positions, results, strict=True):
+                    if isinstance(result, BaseException):
+                        logger.error(
+                            "Dynamic NIXL load failed for key %s: %r",
+                            keys[pos],
+                            result,
+                        )
+                        continue
+                    bitmap.set(pos)
+                    accessed_keys.append(keys[pos])
+
+        except Exception:
+            logger.exception("Dynamic NIXL load task %d failed", task_id)
+
+        if accessed_keys:
+            self._notify_keys_accessed(accessed_keys)
+        with self._lock:
+            self._completed_load_tasks[task_id] = bitmap
+        self._signal_load_event()
+
+
+# ---------------------------------------------------------------------
+# Config and self-registration
+# ---------------------------------------------------------------------
+
+# TODO(Jiayi): OBJ backend is not supported in the dynamic adapter yet.
+# Only file-based backends are supported.
+_VALID_DYNAMIC_BACKENDS = ("GDS", "GDS_MT", "POSIX", "HF3FS")
+
+
+class DynamicNixlStoreL2AdapterConfig(L2AdapterConfigBase):
+    """Config for the dynamic-file Nixl L2 adapter.
+
+    Fields:
+    - backend: Nixl storage backend (GDS, GDS_MT, POSIX, HF3FS).
+    - backend_params: Backend-specific parameters as a dict of string
+      key-value pairs. Must include ``file_path`` and ``use_direct_io``.
+    """
+
+    def __init__(
+        self,
+        backend: str,
+        backend_params: dict[str, str],
+    ):
+        if backend not in _VALID_DYNAMIC_BACKENDS:
+            raise ValueError(
+                "backend must be one of %s, got %r" % (_VALID_DYNAMIC_BACKENDS, backend)
+            )
+        if "file_path" not in backend_params:
+            raise ValueError(
+                "backend_params must include 'file_path' for backend %r" % backend
+            )
+        if "use_direct_io" not in backend_params:
+            raise ValueError(
+                "backend_params must include 'use_direct_io' for backend %r" % backend
+            )
+        self.backend = backend
+        self.backend_params = backend_params
+
+    @classmethod
+    def from_dict(cls, d: dict) -> DynamicNixlStoreL2AdapterConfig:
+        backend = d.get("backend")
+        if backend not in _VALID_DYNAMIC_BACKENDS:
+            raise ValueError(
+                "backend must be one of %s, got %r" % (_VALID_DYNAMIC_BACKENDS, backend)
+            )
+
+        backend_params = d.get("backend_params", {})
+        if not isinstance(backend_params, dict):
+            raise ValueError("backend_params must be a dict of string key-value pairs")
+
+        return cls(backend=backend, backend_params=backend_params)
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Dynamic Nixl store L2 adapter config fields:\n"
+            "- backend (str): Nixl storage backend, "
+            "one of %s (required)\n"
+            "- backend_params (dict): backend-specific "
+            "string key-value pairs. Must include "
+            "'file_path' and 'use_direct_io'.\n"
+            "- persist_enabled (bool): if True, keep data files on disk "
+            "at shutdown (optional, default True)\n"
+            "Lookup always checks secondary storage (disk) on miss."
+            % (_VALID_DYNAMIC_BACKENDS,)
+        )
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("nixl_store_dynamic", DynamicNixlStoreL2AdapterConfig)
+
+
+def _create_dynamic_nixl_store_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: Optional[L1MemoryDesc] = None,
+) -> L2AdapterInterface:
+    """Create a DynamicNixlStoreL2Adapter from config."""
+    if l1_memory_desc is None:
+        raise ValueError(
+            "l1_memory_desc is required to create a DynamicNixlStoreL2Adapter."
+        )
+    return DynamicNixlStoreL2Adapter(config, l1_memory_desc)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("nixl_store_dynamic", _create_dynamic_nixl_store_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/nixl_store_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/nixl_store_l2_adapter.py
new file mode 100644
index 0000000..41a54be
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/nixl_store_l2_adapter.py
@@ -0,0 +1,1011 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Optional
+import asyncio
+import os
+import threading
+import uuid
+
+# Third Party
+from nixl._api import nixl_agent as NixlAgent
+from nixl._api import nixl_agent_config as NixlAgentConfig
+from nixl._api import nixl_prepped_dlist_handle as NixlDlistHandle
+from nixl._api import nixl_xfer_handle as NixlXferHandle
+from nixl._api import (
+    nixlBind,
+)
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L1MemoryDesc, L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface, L2TaskId
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+# Main class
+
+
+@dataclass
+class NixlStoreObj:
+    """
+    The object stored in Nixl L2 cache.
+    Can be used for both file and object.
+    """
+
+    page_indices: list[int]
+
+    size: int  # in bytes
+
+    layout: Optional[MemoryLayoutDesc] = None
+
+    pin_count: int = 0
+    _lock: threading.Lock = field(
+        default_factory=threading.Lock, repr=False, compare=False
+    )
+
+    def increase_pin_count(self):
+        with self._lock:
+            self.pin_count += 1
+
+    def decrease_pin_count(self):
+        with self._lock:
+            if self.pin_count > 0:
+                self.pin_count -= 1
+            else:
+                logger.warning(
+                    "Trying to decrease pin count of object at page indices %s below 0",
+                    self.page_indices,
+                )
+
+
+class NixlObjPool:
+    """Thread-safe pool of integer indices representing pre-allocated storage slots."""
+
+    def __init__(self, num_total_objs: int):
+        """
+        Args:
+            num_total_objs: Total number of storage slots to manage.
+        """
+        self.indices = list(range(num_total_objs))
+        self._total = num_total_objs
+        self._lock = threading.Lock()
+
+    @property
+    def total_objs(self) -> int:
+        """Total number of storage slots this pool manages (allocated + free)."""
+        return self._total
+
+    def batched_allocate(self, num_objs: int) -> list[int]:
+        """
+        Allocate a batch of storage slot indices.
+
+        Args:
+            num_objs: Number of indices to allocate.
+
+        Returns:
+            list[int]: The allocated indices.
+
+        Raises:
+            RuntimeError: If fewer than ``num_objs`` slots remain in the pool.
+        """
+        with self._lock:
+            if num_objs > len(self.indices):
+                logger.debug("NixlObjPool allocation failure.")
+                return []
+            allocated = self.indices[:num_objs]
+            self.indices = self.indices[num_objs:]
+            return allocated
+
+    def batched_free(self, obj_indices: list[int]) -> None:
+        """
+        Return a batch of storage slot indices back to the pool.
+
+        Args:
+            obj_indices: Indices previously obtained from ``batched_allocate``.
+        """
+        with self._lock:
+            self.indices.extend(obj_indices)
+
+    def get_slot_usage(self) -> tuple[float, float]:
+        """
+        Return (current_usage, usage_after_ongoing_eviction) in [0, 1] for
+        the slot pool. Renamed from ``get_usage`` to avoid colliding with
+        the byte-based ``L2AdapterInterface.get_usage`` shape — this is
+        an internal pool helper, not the adapter-level usage report.
+
+        Both values are identical because slot frees are synchronous.
+        """
+        with self._lock:
+            if self._total == 0:
+                return (0.0, 0.0)
+            usage = (self._total - len(self.indices)) / self._total
+            return (usage, usage)
+
+
+class NixlStorageAgent:
+    agent_name: str
+    nixl_agent: NixlAgent
+    mem_reg_descs: nixlBind.nixlRegDList
+    mem_xfer_handler: NixlDlistHandle
+
+    def __init__(
+        self,
+        device: str,
+        backend: str,
+        backend_params: dict[str, str],
+        pool_size: int,
+        l1_memory_desc: L1MemoryDesc,
+    ):
+        """
+        Initialize the NixlStorageAgent.
+
+        Args:
+            device: Device type of the L1 memory buffer (e.g. "cpu", "cuda").
+            backend: Nixl storage backend to use. One of: GDS, GDS_MT, POSIX,
+                HF3FS (file-based) or OBJ, AZURE_BLOB (object-based).
+            backend_params: Backend-specific parameters. File-based backends
+                require "file_path" and "use_direct_io" keys.
+            pool_size: Number of storage descriptor slots to pre-allocate.
+            l1_memory_desc: Descriptor of the L1 memory buffer to register with Nixl
+                for data transfers.
+        """
+        self.backend = backend
+        self.pool_size = pool_size
+        self.device = device
+        self.backend_params = backend_params
+
+        self.l1_align_bytes = l1_memory_desc.align_bytes
+
+        self.agent_name = "NixlAgent_" + str(uuid.uuid4())
+        nixl_conf = NixlAgentConfig(backends=[])
+        self.nixl_agent = NixlAgent(self.agent_name, nixl_conf)
+        self.nixl_agent.create_backend(backend, backend_params)
+
+        self.init_mem_handlers(
+            self.device,
+            l1_memory_desc.ptr,
+            l1_memory_desc.size,
+            l1_memory_desc.align_bytes,
+            device_id=0,  # 0 indicates cpu
+        )
+
+        if self.backend in ["GDS", "GDS_MT", "POSIX", "HF3FS"]:
+            file_size = int(
+                self.backend_params.get("file_size", l1_memory_desc.align_bytes)
+            )
+            pages_per_file = file_size // l1_memory_desc.align_bytes
+            self.pool = NixlObjPool(num_total_objs=self.pool_size * pages_per_file)
+            self.init_storage_handlers_file(
+                num_files=self.pool_size,
+                page_size=l1_memory_desc.align_bytes,
+                file_size=file_size,
+                file_path=self.backend_params["file_path"],
+                # TODO(Jiayi): Need to make argument parsing more elegant
+                use_direct_io=str(self.backend_params["use_direct_io"]).lower()
+                == "true",
+            )
+        elif self.backend in ["OBJ", "AZURE_BLOB"]:
+            self.pool = NixlObjPool(num_total_objs=self.pool_size)
+            self.init_storage_handlers_object(
+                page_size=l1_memory_desc.align_bytes,
+                num_pages=self.pool_size,
+            )
+        else:
+            raise TypeError(f"Unsupported backend type: {self.backend}")
+
+    def init_mem_handlers(self, device, buffer_ptr, buffer_size, page_size, device_id):
+        """
+        Initialize memory handlers for the given device and buffer.
+        """
+        reg_list = [(buffer_ptr, buffer_size, device_id, "")]
+        xfer_desc = [
+            (base_addr, page_size, device_id)
+            for base_addr in range(buffer_ptr, buffer_ptr + buffer_size, page_size)
+        ]
+
+        if device == "cpu":
+            mem_type = "DRAM"
+        else:
+            mem_type = "VRAM"
+
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type=mem_type)
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type=mem_type)
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            "", xfer_descs, mem_type=mem_type
+        )
+
+        self.mem_reg_descs = reg_descs
+        self.mem_xfer_handler = xfer_handler
+
+    def init_storage_handlers_file(
+        self,
+        num_files: int,
+        page_size: int,
+        file_size: int,
+        file_path: str,
+        use_direct_io: bool,
+    ):
+        """Initialize storage handlers for file-based backends.
+
+        Each file holds ``file_size // page_size`` pages at successive offsets.
+        ``file_size`` must be a multiple of ``page_size``.
+
+        Args:
+            num_files: Number of storage files to create.
+            page_size: Granularity of L1 memory pages (transfer unit size).
+            file_size: Size in bytes of each storage file. Must be a multiple
+                of ``page_size``.
+            file_path: Directory where storage files are created.
+            use_direct_io: Whether to open files with O_DIRECT.
+        """
+        os.makedirs(file_path, exist_ok=True)
+        if file_size % page_size != 0:
+            raise ValueError(
+                f"file_size ({file_size}) must be a multiple of page_size ({page_size})"
+            )
+
+        pages_per_file = file_size // page_size
+        num_pages = num_files * pages_per_file
+
+        # Create file descriptors for Nixl to register
+        fds: list[int] = []
+        flags = os.O_CREAT | os.O_RDWR
+        if use_direct_io:
+            if hasattr(os, "O_DIRECT"):
+                flags |= os.O_DIRECT
+            else:
+                logger.warning(
+                    "use_direct_io is True, but O_DIRECT is not available on "
+                    "this system. Falling back to buffered I/O."
+                )
+        for i in range(num_files):
+            filename = f"obj_{i}_{uuid.uuid4().hex[0:4]}.bin"
+            tmp_path = os.path.join(file_path, filename)
+            fd = os.open(tmp_path, flags)
+            fds.append(fd)
+
+        # Register each file covering the full file_size.
+        # Build one xfer_desc entry per page slot (page index i maps to
+        # offset (i % pages_per_file) * page_size inside fd[i // pages_per_file]).
+        reg_list = []
+        xfer_desc = []
+        for fd in fds:
+            reg_list.append((0, file_size, fd, ""))
+        for page_idx in range(num_pages):
+            fd = fds[page_idx // pages_per_file]
+            offset = (page_idx % pages_per_file) * page_size
+            xfer_desc.append((offset, page_size, fd))
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type="FILE")
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type="FILE")
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            self.agent_name, xfer_descs, mem_type="FILE"
+        )
+
+        self.storage_fds = fds
+        self.storage_reg_descs = reg_descs
+        self.storage_xfer_descs = xfer_descs
+        self.storage_xfer_handler = xfer_handler
+
+    def init_storage_handlers_object(
+        self,
+        page_size: int,
+        num_pages: int,
+    ):
+        """Initialize storage handlers for object-based backends."""
+
+        # Create object keys for Nixl to register
+        keys = []
+
+        for i in range(num_pages):
+            key = f"obj_{i}_{uuid.uuid4().hex[0:4]}"
+            keys.append(key)
+
+        # Register and prepare xfer handler
+        reg_list = []
+        xfer_desc = []
+        for i, key in enumerate(keys):
+            reg_list.append((0, page_size, i, key))
+            xfer_desc.append((0, page_size, i))
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type="OBJ")
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type="OBJ")
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            self.agent_name, xfer_descs, mem_type="OBJ"
+        )
+
+        self.storage_reg_descs = reg_descs
+        self.storage_xfer_descs = xfer_descs
+        self.storage_xfer_handler = xfer_handler
+
+    def get_mem_to_storage_handle(self, mem_indices, storage_indices) -> NixlXferHandle:
+        """Get a Nixl transfer handle for transferring data from memory to storage."""
+
+        return self.nixl_agent.make_prepped_xfer(
+            "WRITE",
+            self.mem_xfer_handler,
+            mem_indices,
+            self.storage_xfer_handler,
+            storage_indices,
+        )
+
+    def get_storage_to_mem_handle(self, mem_indices, storage_indices) -> NixlXferHandle:
+        """Get a Nixl transfer handle for transferring data from storage to memory."""
+        return self.nixl_agent.make_prepped_xfer(
+            "READ",
+            self.mem_xfer_handler,
+            mem_indices,
+            self.storage_xfer_handler,
+            storage_indices,
+        )
+
+    def post_blocking(self, handle: NixlXferHandle):
+        """Post a Nixl transfer handle and block until the transfer is done."""
+
+        state = self.nixl_agent.transfer(handle)
+
+        while state != "DONE" and state != "ERR":
+            try:
+                state = self.nixl_agent.check_xfer_state(handle)
+            except nixlBind.nixlBackendError:
+                raise
+
+        if state == "ERR":
+            raise RuntimeError("NIXL transfer failed")
+
+    async def post_non_blocking(self, handle: NixlXferHandle):
+        """Post a Nixl transfer handle and await until the transfer is done."""
+
+        state = self.nixl_agent.transfer(handle)
+
+        while state != "DONE" and state != "ERR":
+            try:
+                state = self.nixl_agent.check_xfer_state(handle)
+            except nixlBind.nixlBackendError:
+                raise
+
+            # TODO(Jiayi): Tune this for better perf
+            await asyncio.sleep(0.01)
+
+        if state == "ERR":
+            raise RuntimeError("NIXL transfer failed")
+
+    def get_storage_indices(self, num_objs: int) -> list[int]:
+        # TODO(Jiayi): Support eviction
+        return self.pool.batched_allocate(num_objs)
+
+    def get_memory_indices(self, raw_addr: int, mem_size: int) -> list[int]:
+        """Get memory indices for the given raw address and size."""
+        # TODO(Jiayi): Now we assume the memory is contiguous and page-aligned. We may
+        # want to support more flexible memory layout in the future.
+        if raw_addr % self.l1_align_bytes != 0:
+            raise ValueError(
+                f"Raw address {raw_addr} is not aligned to "
+                f"page size {self.l1_align_bytes}"
+            )
+        if mem_size % self.l1_align_bytes != 0:
+            raise ValueError(
+                f"Memory size {mem_size} is not a multiple of "
+                f"page size {self.l1_align_bytes}"
+            )
+        num_pages = mem_size // self.l1_align_bytes
+        return [(raw_addr // self.l1_align_bytes + i) for i in range(num_pages)]
+
+    def release_handle(self, handle):
+        self.nixl_agent.release_xfer_handle(handle)
+
+    def close(self):
+        self.nixl_agent.release_dlist_handle(self.storage_xfer_handler)
+        self.nixl_agent.release_dlist_handle(self.mem_xfer_handler)
+        self.nixl_agent.deregister_memory(self.storage_reg_descs)
+        self.nixl_agent.deregister_memory(self.mem_reg_descs)
+        for fd in getattr(self, "storage_fds", []):
+            os.close(fd)
+
+
+class NixlStoreL2Adapter(L2AdapterInterface):
+    """
+    A Nixl-based L2 adapter
+    """
+
+    def __init__(self, config: NixlStoreL2AdapterConfig, l1_memory_desc: L1MemoryDesc):
+        """
+        Initialize the NixlStoreL2Adapter.
+
+        Args:
+            config: Nixl-specific adapter configuration including backend type,
+                backend parameters, and storage pool size.
+            l1_memory_desc: Descriptor of the L1 memory buffer to register with the
+                Nixl backend for DMA transfers.
+        """
+        # Initialize Nixl agent first so we know the actual page count the
+        # backend allocated; we then forward the byte capacity to the base
+        # class so ``get_usage()`` / ``supports_global_eviction`` reflect the real
+        # storage size.
+        self.nixl_agent = NixlStorageAgent(
+            device="cpu",
+            backend=config.backend,
+            backend_params=config.backend_params,
+            pool_size=config.pool_size,
+            l1_memory_desc=l1_memory_desc,
+        )
+        max_capacity_bytes = (
+            self.nixl_agent.pool.total_objs * l1_memory_desc.align_bytes
+        )
+        super().__init__(max_capacity_bytes=max_capacity_bytes)
+        self._config = config
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        # Cache data structures
+        self._memory_objects: dict[ObjectKey, NixlStoreObj] = {}
+
+        # Task ID management
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+        self._lock = threading.Lock()  # lock for all shared state
+
+        # Asyncio event loop running in a background thread
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(target=self._run_event_loop, daemon=True)
+        self._loop_thread.start()
+
+    # --------------------
+    # Event Fd Interface
+    # --------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    #####################
+    # Store Interface
+    #####################
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """
+        Submit a store task to store a batch of memory objects associated with
+        a batch of keys.
+
+        Args:
+            keys (list[ObjectKey]): the list of keys to be stored.
+            objects (list[MemoryObj]): the list of memory objects to be stored.
+                The length of the objects list should be the same as the length of
+                the keys list.
+
+        Returns:
+            L2TaskId: the task id of the submitted store task.
+        """
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_store_in_the_loop(keys, objects, task_id), self._loop
+        )
+
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        """Pop all completed store tasks.
+
+        Returns:
+            dict[L2TaskId, L2StoreResult]: a dictionary mapping the task
+            id to an ``L2StoreResult`` that encodes both the success flag
+            and the bytes actually transferred.
+        """
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    #####################
+    # Lookup and Lock Interface
+    #####################
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        # Schedule the lookup operation in the event loop thread
+        self._loop.call_soon_threadsafe(self._execute_lookup_in_the_loop, keys, task_id)
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        def _unlock_keys(keys: list[ObjectKey]) -> None:
+            """
+            Unlock keys in the event loop thread.
+            """
+            for key in keys:
+                if (obj := self._memory_objects.get(key)) is not None:
+                    obj.decrease_pin_count()
+
+        # Schedule the unlock operation in the event loop thread
+        self._loop.call_soon_threadsafe(_unlock_keys, keys)
+
+    #####################
+    # Load Interface
+    ######################
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._get_next_task_id()
+
+        # Schedule the load operation in the event loop thread
+        asyncio.run_coroutine_threadsafe(
+            self._execute_load_in_loop(keys, objects, task_id), self._loop
+        )
+
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    def close(self):
+        # Stop the event loop and wait for the thread to finish
+        async def _stop_tasks():
+            tasks = [
+                t
+                for t in asyncio.all_tasks(self._loop)
+                if t is not asyncio.current_task()
+            ]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            future = asyncio.run_coroutine_threadsafe(_stop_tasks(), self._loop)
+
+            future.result(timeout=5)  # Wait for tasks to be cancelled, with a timeout
+
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._loop_thread.join()
+        self._loop.close()
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+    #####################
+    # Eviction Interface
+    #####################
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """
+        Delete a batch of objects from Nixl storage, freeing their page slots.
+
+        Pinned objects (pin_count > 0) are skipped to avoid racing with an
+        in-flight load; the eviction controller will retry them on the next
+        cycle once they are unpinned.
+        """
+        # TODO(Jiayi): Optimize lock usage here
+        deleted_keys: list[ObjectKey] = []
+        deleted_sizes: list[int] = []
+        with self._lock:
+            for key in keys:
+                obj = self._memory_objects.get(key)
+                if obj is None:
+                    continue
+                if obj.pin_count > 0:
+                    logger.debug(
+                        "Skipping eviction of pinned key %s (pin_count=%d)",
+                        key,
+                        obj.pin_count,
+                    )
+                    continue
+                del self._memory_objects[key]
+                self.nixl_agent.pool.batched_free(obj.page_indices)
+                deleted_keys.append(key)
+                deleted_sizes.append(obj.size)
+        if deleted_keys:
+            self._notify_keys_deleted(deleted_keys, deleted_sizes)
+
+    # ``get_usage()`` is inherited from ``L2AdapterInterface``. The base
+    # class derives the report from ``_notify_keys_*`` totals which we
+    # update with the byte sizes from each store/delete. The Nixl pool's
+    # own slot-based ``get_usage()`` is still used internally for
+    # capacity-check style decisions but is no longer exposed via the
+    # adapter interface.
+
+    #####################
+    # Status Interface
+    #####################
+
+    def report_status(self) -> dict:
+        """Return a status dict for the Nixl L2 adapter."""
+        # NOTE(Jiayi): This function looks pretty slow.
+        with self._lock:
+            stored_object_count = len(self._memory_objects)
+            pinned_object_count = sum(
+                1 for obj in self._memory_objects.values() if obj.pin_count > 0
+            )
+        pool = self.nixl_agent.pool
+        with pool._lock:
+            pool_free_slots = len(pool.indices)
+        return {
+            "is_healthy": self._loop_thread.is_alive(),
+            "type": "NixlStoreL2Adapter",
+            "backend": self._config.backend,
+            "stored_object_count": stored_object_count,
+            "pinned_object_count": pinned_object_count,
+            "pool_size": self._config.pool_size,
+            "pool_free_slots": pool_free_slots,
+            "event_loop_alive": self._loop_thread.is_alive(),
+        }
+
+    ##################
+    # Helper functions
+    ##################
+
+    def _run_event_loop(self) -> None:
+        """Run the asyncio event loop in a background thread."""
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _get_next_task_id(self) -> L2TaskId:
+        """Get the next task ID and increment the counter."""
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    def _evict_if_needed(
+        self,
+    ) -> None:
+        """
+        Evict objects from the cache using desired caching policy.
+        """
+
+        # TODO(Jiayi): Support eviction
+
+        pass
+
+    def _signal_store_event(self) -> None:
+        """Signal the store event fd to notify completion."""
+        self._store_efd.notify()
+
+    async def _execute_store_in_the_loop(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        """
+        Coroutine that performs a batched store to Nixl storage.
+
+        For each key-object pair, memory page indices are mapped to storage
+        slot indices and a single batched DMA write is issued. On success the
+        key-to-storage mapping is recorded in ``_memory_objects``. On transfer
+        failure, all allocated storage slots are freed and the task is marked
+        as failed.
+
+        Args:
+            keys: Keys identifying each object to store.
+            objects: Memory objects whose contents will be written to storage.
+                Must be the same length as ``keys``.
+            task_id: Identifier used to report completion via
+                ``_completed_store_tasks``.
+        """
+        success = True
+        try:
+            # Get memory page indices and storage slot indices
+            mem_indices_flat = []
+            storage_indices_flat = []
+            stored_keys = []
+            storage_objs = []
+            for key, obj in zip(keys, objects, strict=False):
+                # Skip if key already exists to avoid leaking pool slots
+                with self._lock:
+                    if key in self._memory_objects:
+                        continue
+
+                mem_addr = obj.meta.address
+                mem_size = obj.meta.phy_size
+                mem_indices = self.nixl_agent.get_memory_indices(mem_addr, mem_size)
+                storage_indices = self.nixl_agent.get_storage_indices(
+                    num_objs=len(mem_indices)
+                )
+
+                if storage_indices == []:
+                    break
+
+                mem_indices_flat.extend(mem_indices)
+                storage_indices_flat.extend(storage_indices)
+
+                stored_keys.append(key)
+                storage_objs.append(
+                    NixlStoreObj(
+                        page_indices=storage_indices,
+                        size=obj.meta.phy_size,
+                        layout=MemoryLayoutDesc(
+                            [obj.meta.shape],
+                            [obj.meta.dtype],
+                        ),
+                        pin_count=1,
+                    )
+                )
+
+            if not mem_indices_flat:
+                # Nothing to store (all keys already existed or pool empty)
+                with self._lock:
+                    self._completed_store_tasks[task_id] = L2StoreResult(True, 0)
+                self._signal_store_event()
+                return
+
+            handle = self.nixl_agent.get_mem_to_storage_handle(
+                mem_indices_flat,
+                storage_indices_flat,
+            )
+
+            await self.nixl_agent.post_non_blocking(handle)
+            self.nixl_agent.release_handle(handle)
+
+            with self._lock:
+                for key, storage_obj in zip(stored_keys, storage_objs, strict=False):
+                    self._memory_objects[key] = storage_obj
+                    storage_obj.decrease_pin_count()
+            # ``stored_keys`` and ``storage_objs`` are built together in the
+            # pre-alloc loop above, so the size lists stay aligned even
+            # when the pool ran out of slots mid-batch.
+            if stored_keys:
+                stored_sizes = [obj.size for obj in storage_objs]
+                self._notify_keys_stored(stored_keys, stored_sizes)
+            bytes_transferred = sum(obj.size for obj in storage_objs)
+
+        # success is only set to false for transfer failures
+        except Exception:
+            logger.exception("NIXL store task %d failed", task_id)
+            success = False
+            bytes_transferred = 0
+
+            # free storage indices if transfer fails
+            self.nixl_agent.pool.batched_free(storage_indices_flat)
+
+        with self._lock:
+            self._completed_store_tasks[task_id] = L2StoreResult(
+                success, bytes_transferred
+            )
+
+        self._signal_store_event()
+
+    def _signal_lookup_event(self) -> None:
+        """Signal the lookup event fd to notify completion."""
+        self._lookup_efd.notify()
+
+    def _execute_lookup_in_the_loop(
+        self, keys: list[ObjectKey], task_id: L2TaskId
+    ) -> None:
+        """
+        Performs a batched lookup and pin in the event loop.
+
+        For each key present in ``_memory_objects``, its bit is set in the
+        result bitmap and its pin count is incremented to prevent eviction
+        while the caller holds the lock. Keys not found are left unset.
+
+        Args:
+            keys: Keys to look up.
+            task_id: Identifier used to report completion via
+                ``_completed_lookup_tasks``.
+        """
+        bitmap = Bitmap(len(keys))
+        with self._lock:
+            for i, key in enumerate(keys):
+                if (obj := self._memory_objects.get(key)) is None:
+                    continue
+                bitmap.set(i)
+                obj.increase_pin_count()
+            self._completed_lookup_tasks[task_id] = bitmap
+        self._signal_lookup_event()
+
+    def _signal_load_event(self) -> None:
+        """Signal the load event fd to notify completion."""
+        self._load_efd.notify()
+
+    async def _execute_load_in_loop(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        """
+        Coroutine that performs a batched load from Nixl storage into L1 memory.
+
+        For each key that exists in ``_memory_objects``, the corresponding
+        storage page indices are gathered and a single batched DMA read is
+        issued into the provided memory objects. Keys that are not found are
+        silently skipped and their bit in the result bitmap is left unset.
+
+        Args:
+            keys: Keys identifying each object to load.
+            objects: Pre-allocated memory objects that will receive the loaded
+                data. Must be the same length as ``keys``.
+            task_id: Identifier used to report completion via
+                ``_completed_load_tasks``.
+        """
+        bitmap = Bitmap(len(keys))
+        accessed_keys: list[ObjectKey] = []
+        try:
+            mem_indices_flat = []
+            storage_indices_flat = []
+
+            with self._lock:
+                for i, key in enumerate(keys):
+                    if (storage_obj := self._memory_objects.get(key)) is None:
+                        continue
+                    mem_addr = objects[i].meta.address
+                    mem_size = objects[i].meta.phy_size
+                    mem_indices = self.nixl_agent.get_memory_indices(mem_addr, mem_size)
+
+                    mem_indices_flat.extend(mem_indices)
+                    storage_indices_flat.extend(storage_obj.page_indices)
+
+                    bitmap.set(i)
+                    accessed_keys.append(key)
+
+            if mem_indices_flat:
+                handle = self.nixl_agent.get_storage_to_mem_handle(
+                    mem_indices_flat,
+                    storage_indices_flat,
+                )
+                await self.nixl_agent.post_non_blocking(handle)
+                self.nixl_agent.release_handle(handle)
+        except Exception:
+            logger.exception("NIXL load task %d failed", task_id)
+
+        if accessed_keys:
+            self._notify_keys_accessed(accessed_keys)
+        with self._lock:
+            self._completed_load_tasks[task_id] = bitmap
+        self._signal_load_event()
+
+
+# ---------------------------------------------------------------------
+# Config and self-registration
+# ---------------------------------------------------------------------
+
+_VALID_NIXL_BACKENDS = (
+    "GDS",
+    "GDS_MT",
+    "POSIX",
+    "HF3FS",
+    "OBJ",
+    "AZURE_BLOB",
+)
+_FILE_BACKENDS = ("GDS", "GDS_MT", "POSIX", "HF3FS")
+
+
+class NixlStoreL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for a Nixl-store-based L2 adapter.
+
+    Fields:
+    - backend: Nixl storage backend
+      (GDS, GDS_MT, POSIX, HF3FS, OBJ, AZURE_BLOB).
+    - backend_params: Backend-specific parameters as a
+      dict of string key-value pairs. For file-based
+      backends (GDS, GDS_MT, POSIX, HF3FS), must include
+      ``file_path``. May also include ``use_direct_io``
+      (default ``"false"``) and other backend-specific
+      keys.
+    - pool_size: Number of storage descriptors to
+      pre-allocate (must be > 0).
+    """
+
+    def __init__(
+        self,
+        backend: str,
+        backend_params: dict[str, str],
+        pool_size: int,
+    ):
+        if backend in _FILE_BACKENDS:
+            if "file_path" not in backend_params:
+                raise ValueError(
+                    "backend_params must include "
+                    "'file_path' for file-based "
+                    "backend %r" % backend
+                )
+            if "use_direct_io" not in backend_params:
+                raise ValueError(
+                    "backend_params must include "
+                    "'use_direct_io' for file-based "
+                    "backend %r" % backend
+                )
+        self.backend = backend
+        self.backend_params = backend_params
+        self.pool_size = pool_size
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "NixlStoreL2AdapterConfig":
+        backend = d.get("backend")
+        if backend not in _VALID_NIXL_BACKENDS:
+            raise ValueError(
+                "backend must be one of %s, got %r" % (_VALID_NIXL_BACKENDS, backend)
+            )
+
+        backend_params = d.get("backend_params", {})
+        if not isinstance(backend_params, dict):
+            raise ValueError("backend_params must be a dict of string key-value pairs")
+
+        pool_size = d.get("pool_size")
+        if not isinstance(pool_size, int) or pool_size <= 0:
+            raise ValueError("pool_size must be a positive integer")
+
+        return cls(
+            backend=backend,
+            backend_params=backend_params,
+            pool_size=pool_size,
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Nixl store L2 adapter config fields:\n"
+            "- backend (str): Nixl storage backend, "
+            "one of %s (required)\n"
+            "- backend_params (dict): backend-specific "
+            "string key-value pairs (optional, "
+            "default empty). File-based backends "
+            "require file_path. Optional keys include "
+            "'use_direct_io' (default 'false') and "
+            "'file_size' (int, size in bytes of each "
+            "storage file slot; defaults to the L1 "
+            "page size if not set).\n"
+            "- pool_size (int): number of storage "
+            "descriptors to pre-allocate (required, "
+            ">0)" % (_VALID_NIXL_BACKENDS,)
+        )
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("nixl_store", NixlStoreL2AdapterConfig)
+
+
+def _create_nixl_store_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: Optional[L1MemoryDesc] = None,
+) -> L2AdapterInterface:
+    """Create a NixlStoreL2Adapter from config."""
+    if l1_memory_desc is None:
+        raise ValueError("l1_memory_desc is required to create a NixlStoreL2Adapter.")
+    return NixlStoreL2Adapter(config, l1_memory_desc)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("nixl_store", _create_nixl_store_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/p2p_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/p2p_l2_adapter.py
new file mode 100644
index 0000000..7ca641c
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/p2p_l2_adapter.py
@@ -0,0 +1,406 @@
+# SPDX-License-Identifier: Apache-2.0
+"""P2P L2 adapter: reads KV objects from a single peer cache server.
+
+Lookups and unlocks are sent to the peer's P2P controller over the MQ; the
+located objects are pulled from the peer's L1 over the transfer channel. The
+adapter never stores, evicts, or deletes -- a peer's cache is read-only here.
+
+Because neither the lookup RPC nor the transfer-channel read exposes a
+completion fd, the lookup and load event fds are pulsed by the
+``PeriodicEventNotifier`` singleton so the prefetch controller re-polls
+``query_*`` periodically.
+
+Thread model: the lookup / load / unlock calls all come from the single
+prefetch-controller loop thread, and the store calls come from the
+store-controller loop thread. The two paths share no mutable state (each owns
+its own task-id counter and bookkeeping dicts), so this class needs no locks.
+"""
+
+# Standard
+from dataclasses import dataclass
+import time
+
+# Third Party
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap, PeriodicEventNotifier
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L1MemoryDesc, L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface, L2TaskId
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import register_l2_adapter_factory
+from lmcache.v1.distributed.transfer_channel import get_transfer_channel_context
+from lmcache.v1.distributed.transfer_channel.api import TransferChannelAddress
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import RequestType, get_response_class
+from lmcache.v1.platform import HAS_EVENTFD, create_event_notifier
+
+logger = init_logger(__name__)
+
+_LOOKUP_RPC_TIMEOUT_S = 3.0
+_PERIODIC_NOTIFIER_INTERVAL_MS = 5
+
+
+@dataclass
+class _LookupTask:
+    keys: list[ObjectKey]
+    remote_task_id: int
+    deadline: float
+    failed: bool = False
+
+
+@dataclass
+class _LoadTask:
+    keys: list[ObjectKey]
+    read_task_id: int
+    deadline: float
+    failed: bool = False
+
+
+class P2PL2AdapterConfig(L2AdapterConfigBase):
+    """Config for the P2P L2 adapter.
+
+    Fields:
+    - peer_mq_server_url: ZMQ url of the peer's MQ server (lookup/unlock RPCs).
+    - peer_transfer_channel_server_url: the peer's transfer-channel server url.
+    - lookup_timeout_s: deadline for a lookup result before it counts as a miss.
+    - load_timeout_s: deadline for a load before it counts as a failure.
+    """
+
+    def __init__(
+        self,
+        peer_mq_server_url: str,
+        peer_transfer_channel_server_url: str,
+        lookup_timeout_s: float = 10.0,
+        load_timeout_s: float = 10.0,
+    ) -> None:
+        self.peer_mq_server_url = peer_mq_server_url
+        self.peer_transfer_channel_server_url = peer_transfer_channel_server_url
+        self.lookup_timeout_s = lookup_timeout_s
+        self.load_timeout_s = load_timeout_s
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "P2PL2AdapterConfig":
+        peer_mq_server_url = d.get("peer_mq_server_url")
+        if not isinstance(peer_mq_server_url, str) or not peer_mq_server_url:
+            raise ValueError("peer_mq_server_url must be a non-empty string")
+
+        peer_tc_url = d.get("peer_transfer_channel_server_url")
+        if not isinstance(peer_tc_url, str) or not peer_tc_url:
+            raise ValueError(
+                "peer_transfer_channel_server_url must be a non-empty string"
+            )
+
+        lookup_timeout_s = d.get("lookup_timeout_s", 10.0)
+        load_timeout_s = d.get("load_timeout_s", 10.0)
+        if not isinstance(lookup_timeout_s, (int, float)) or lookup_timeout_s <= 0:
+            raise ValueError("lookup_timeout_s must be a positive number")
+        if not isinstance(load_timeout_s, (int, float)) or load_timeout_s <= 0:
+            raise ValueError("load_timeout_s must be a positive number")
+
+        return cls(
+            peer_mq_server_url=peer_mq_server_url,
+            peer_transfer_channel_server_url=peer_tc_url,
+            lookup_timeout_s=float(lookup_timeout_s),
+            load_timeout_s=float(load_timeout_s),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "P2P L2 adapter config fields:\n"
+            "- peer_mq_server_url (str): ZMQ url of the peer's MQ server (required)\n"
+            "- peer_transfer_channel_server_url (str): the peer's transfer channel "
+            "server url (required)\n"
+            "- lookup_timeout_s (float): lookup result deadline in seconds "
+            "(optional, default 10)\n"
+            "- load_timeout_s (float): load deadline in seconds "
+            "(optional, default 10)"
+        )
+
+
+class P2PL2Adapter(L2AdapterInterface):
+    """L2 adapter that reads KV objects from a single peer cache server."""
+
+    def __init__(self, config: P2PL2AdapterConfig) -> None:
+        super().__init__(max_capacity_bytes=0)
+        self._config = config
+
+        self._mq_client = MessageQueueClient(
+            config.peer_mq_server_url, zmq.Context.instance()
+        )
+        self._tc_context = get_transfer_channel_context()
+        self._tc_client = self._tc_context.get_transfer_channel_client(
+            config.peer_transfer_channel_server_url
+        )
+
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        PeriodicEventNotifier.create(
+            interval_ms=_PERIODIC_NOTIFIER_INTERVAL_MS, use_eventfd=HAS_EVENTFD
+        )
+        notifier = PeriodicEventNotifier.get()
+        if notifier is None:
+            raise RuntimeError("PeriodicEventNotifier is unavailable after create()")
+        self._notifier = notifier
+        self._notifier.register_fd(self._lookup_efd.fileno())
+        self._notifier.register_fd(self._load_efd.fileno())
+
+        # Prefetch-loop-thread state (lookup / load).
+        self._next_task_id: L2TaskId = 0
+        self._lookup_tasks: dict[L2TaskId, _LookupTask] = {}
+        self._load_tasks: dict[L2TaskId, _LoadTask] = {}
+        self._remote_addresses: dict[ObjectKey, TransferChannelAddress] = {}
+
+        # Store-loop-thread state (store no-op completions).
+        self._next_store_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+
+        self._closed = False
+
+    # --------------------
+    # Event Fd Interface
+    # --------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    # --------------------
+    # Store Interface (no-op: a peer's cache is read-only)
+    # --------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Record a 0-byte success and signal the store fd immediately.
+
+        The P2P adapter never writes to a peer, but the store controller still
+        tracks every submitted task (and the L1 read locks it reserved) until
+        the result is popped. Completing the task right away lets the
+        controller finalize that bookkeeping instead of leaking it.
+        """
+        task_id = self._next_store_task_id
+        self._next_store_task_id += 1
+        self._completed_store_tasks[task_id] = L2StoreResult(True, 0)
+        self._store_efd.notify()
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        completed = self._completed_store_tasks
+        self._completed_store_tasks = {}
+        return completed
+
+    # --------------------
+    # Lookup and Lock Interface
+    # --------------------
+
+    def submit_lookup_and_lock_task(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+    ) -> L2TaskId:
+        task_id = self._next_task_id
+        self._next_task_id += 1
+
+        if self._closed:
+            self._lookup_tasks[task_id] = _LookupTask(
+                keys=keys, remote_task_id=-1, deadline=0.0, failed=True
+            )
+            return task_id
+
+        future = self._mq_client.submit_request(
+            RequestType.P2P_LOOKUP_AND_LOCK,
+            [keys, layout_desc],
+            get_response_class(RequestType.P2P_LOOKUP_AND_LOCK),
+        )
+        failed = False
+        remote_task_id = -1
+        try:
+            remote_task_id = future.result(timeout=_LOOKUP_RPC_TIMEOUT_S)
+        except TimeoutError:
+            logger.warning(
+                "P2P lookup submit to %s timed out; treating as a miss",
+                self._config.peer_mq_server_url,
+            )
+            failed = True
+
+        self._lookup_tasks[task_id] = _LookupTask(
+            keys=keys,
+            remote_task_id=remote_task_id,
+            deadline=time.monotonic() + self._config.lookup_timeout_s,
+            failed=failed,
+        )
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        task = self._lookup_tasks.get(task_id)
+        if task is None:
+            return None
+        if task.failed:
+            del self._lookup_tasks[task_id]
+            return Bitmap(len(task.keys))
+        if time.monotonic() > task.deadline:
+            del self._lookup_tasks[task_id]
+            logger.warning("P2P lookup task %d timed out; treating as a miss", task_id)
+            return Bitmap(len(task.keys))
+
+        future = self._mq_client.submit_request(
+            RequestType.P2P_QUERY_LOOKUP_RESULTS,
+            [task.remote_task_id],
+            get_response_class(RequestType.P2P_QUERY_LOOKUP_RESULTS),
+        )
+        try:
+            addresses = future.result(timeout=_LOOKUP_RPC_TIMEOUT_S)
+        except TimeoutError:
+            return None
+
+        if addresses is None:
+            return None
+
+        bitmap = Bitmap(len(task.keys))
+        for i, (key, addr) in enumerate(zip(task.keys, addresses, strict=True)):
+            if addr.is_valid():
+                bitmap.set(i)
+                self._remote_addresses[key] = addr
+        del self._lookup_tasks[task_id]
+        return bitmap
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        if not keys:
+            return
+        self._mq_client.submit_request(
+            RequestType.P2P_UNLOCK_OBJECTS,
+            [keys],
+            get_response_class(RequestType.P2P_UNLOCK_OBJECTS),
+        )
+        for key in keys:
+            self._remote_addresses.pop(key, None)
+
+    # --------------------
+    # Load Interface
+    # --------------------
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        task_id = self._next_task_id
+        self._next_task_id += 1
+
+        remote_addresses: list[TransferChannelAddress] = []
+        for key in keys:
+            addr = self._remote_addresses.get(key)
+            if addr is None or not addr.is_valid():
+                logger.warning(
+                    "P2P load task %d has a missing/invalid remote address; "
+                    "treating as a failure",
+                    task_id,
+                )
+                self._load_tasks[task_id] = _LoadTask(
+                    keys=keys, read_task_id=-1, deadline=0.0, failed=True
+                )
+                return task_id
+            remote_addresses.append(addr)
+
+        local_addresses = self._tc_context.get_transfer_channel_address(
+            [(obj.shm_offset, obj.shm_byte_length) for obj in objects]
+        )
+        read_task_id = self._tc_client.submit_read(
+            local_addresses,
+            remote_addresses,  # type: ignore
+        )
+
+        self._load_tasks[task_id] = _LoadTask(
+            keys=keys,
+            read_task_id=read_task_id,
+            deadline=time.monotonic() + self._config.load_timeout_s,
+        )
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        task = self._load_tasks.get(task_id)
+        if task is None:
+            return None
+        if task.failed:
+            del self._load_tasks[task_id]
+            return Bitmap(len(task.keys))
+        if time.monotonic() > task.deadline:
+            del self._load_tasks[task_id]
+            logger.warning("P2P load task %d timed out; treating as a failure", task_id)
+            return Bitmap(len(task.keys))
+
+        result = self._tc_client.query_read_status(task.read_task_id)
+        if not result.is_finished():
+            return None
+
+        bitmap = Bitmap(len(task.keys))
+        for i, succeeded in enumerate(result.succeeded_mask):
+            if succeeded:
+                bitmap.set(i)
+        del self._load_tasks[task_id]
+        return bitmap
+
+    # --------------------
+    # Lifecycle / status
+    # --------------------
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+
+        self._notifier.unregister_fd(self._lookup_efd.fileno())
+        self._notifier.unregister_fd(self._load_efd.fileno())
+        # Release the peer's transfer-channel client now that this adapter no
+        # longer reads from it.
+        self._tc_context.remove_transfer_channel_client(
+            self._config.peer_transfer_channel_server_url
+        )
+        self._mq_client.close()
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+    def report_status(self) -> dict:
+        return {
+            "is_healthy": True,
+            "type": "P2PL2Adapter",
+            "peer_mq_server_url": self._config.peer_mq_server_url,
+            "peer_transfer_channel_server_url": (
+                self._config.peer_transfer_channel_server_url
+            ),
+            "in_flight_lookups": len(self._lookup_tasks),
+            "in_flight_loads": len(self._load_tasks),
+        }
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("p2p", P2PL2AdapterConfig)
+
+
+def _create_p2p_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: L1MemoryDesc | None = None,
+) -> L2AdapterInterface:
+    """Create a P2PL2Adapter from config (l1_memory_desc is unused)."""
+    return P2PL2Adapter(config)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("p2p", _create_p2p_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/plugin_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/plugin_l2_adapter.py
new file mode 100644
index 0000000..46c6085
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/plugin_l2_adapter.py
@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Plugin L2 adapter -- dynamically loads an external adapter
+class from a user-supplied Python module.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Any, Optional
+import importlib
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface as _L2AI
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+
+# Config class
+
+
+class PluginL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for a plugin L2 adapter.
+
+    Dynamically loads an adapter class from a user-supplied
+    Python module at creation time.
+
+    Fields:
+    - module_path: Dotted Python import path of the module
+        containing the adapter class.
+    - class_name: Name of the class inside *module_path*
+        that implements ``L2AdapterInterface``.
+    - adapter_params: Arbitrary dict forwarded to the
+        adapter class constructor.
+    - config_class_name: Optional name of a config class
+        inside *module_path* that subclasses
+        ``L2AdapterConfigBase``.  When set, the factory
+        builds a config instance via ``from_dict()`` and
+        passes it (instead of a raw dict) to the adapter
+        constructor -- matching the built-in convention.
+    """
+
+    def __init__(
+        self,
+        module_path: str,
+        class_name: str,
+        adapter_params: dict[str, Any] | None = None,
+        config_class_name: str | None = None,
+    ):
+        self.module_path = module_path
+        self.class_name = class_name
+        self.adapter_params = adapter_params or {}
+        self.config_class_name = config_class_name
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "PluginL2AdapterConfig":
+        module_path = d.get("module_path")
+        if not isinstance(module_path, str) or not module_path:
+            raise ValueError("module_path must be a non-empty string")
+
+        class_name = d.get("class_name")
+        if not isinstance(class_name, str) or not class_name:
+            raise ValueError("class_name must be a non-empty string")
+
+        adapter_params = d.get("adapter_params", {})
+        if not isinstance(adapter_params, dict):
+            raise ValueError("adapter_params must be a dict")
+
+        config_class_name = d.get("config_class_name")
+        if config_class_name is not None and not isinstance(config_class_name, str):
+            raise ValueError("config_class_name must be a string")
+
+        return cls(
+            module_path=module_path,
+            class_name=class_name,
+            adapter_params=adapter_params,
+            config_class_name=config_class_name,
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "Plugin L2 adapter config fields:\n"
+            "- module_path (str): dotted import path of "
+            "the module containing the adapter class "
+            "(required)\n"
+            "- class_name (str): name of the adapter "
+            "class inside the module (required)\n"
+            "- adapter_params (dict): forwarded to the "
+            "adapter constructor "
+            "(optional, default {})\n"
+            "- config_class_name (str): explicit config "
+            "class name; when omitted the factory "
+            "auto-discovers it (see plugin.md)\n"
+            "\n"
+            "Example JSON (raw dict):\n"
+            '{"type": "plugin", '
+            '"module_path": "my_plugin.l2", '
+            '"class_name": "MyL2Adapter", '
+            '"adapter_params": {"host": "localhost"}}\n'
+            "\n"
+            "Example JSON (with config class):\n"
+            '{"type": "plugin", '
+            '"module_path": "my_plugin.l2", '
+            '"class_name": "MyL2Adapter", '
+            '"config_class_name": "MyL2AdapterConfig", '
+            '"adapter_params": {"host": "localhost"}}'
+        )
+
+
+# Factory function
+
+
+def _create_plugin_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> _L2AI:
+    """Dynamically load and create a plugin L2 adapter."""
+    assert isinstance(config, PluginL2AdapterConfig)
+
+    try:
+        module = importlib.import_module(config.module_path)
+    except ImportError as e:
+        raise ImportError(
+            "Could not import module '%s': %s" % (config.module_path, e)
+        ) from e
+
+    try:
+        adapter_cls = getattr(module, config.class_name)
+    except AttributeError as e:
+        raise AttributeError(
+            "Module '%s' has no class '%s': %s"
+            % (config.module_path, config.class_name, e)
+        ) from e
+
+    if not (isinstance(adapter_cls, type) and issubclass(adapter_cls, _L2AI)):
+        raise TypeError(
+            "%s.%s is not a subclass of "
+            "L2AdapterInterface" % (config.module_path, config.class_name)
+        )
+
+    cfg_cls = _resolve_config_class(
+        module,
+        config,
+        adapter_cls,
+    )
+    kwargs: dict[str, object] = {}
+    if l1_memory_desc is not None:
+        kwargs["l1_memory_desc"] = l1_memory_desc
+
+    # mypy sees ``adapter_cls`` as ``type[L2AdapterInterface]`` and
+    # complains that we're passing a config object / dict where the
+    # base class expects ``max_capacity_bytes: int``. The plugin
+    # surface is intentionally dynamic, so silence both checks.
+    if cfg_cls is not None:
+        return adapter_cls(
+            cfg_cls.from_dict(config.adapter_params),  # type: ignore[arg-type]
+            **kwargs,  # type: ignore[call-arg]
+        )
+
+    return adapter_cls(
+        config.adapter_params,  # type: ignore[arg-type]
+        **kwargs,  # type: ignore[call-arg]
+    )
+
+
+def _resolve_config_class(
+    module: object,
+    config: PluginL2AdapterConfig,
+    adapter_cls: type,
+) -> type[L2AdapterConfigBase] | None:
+    """Resolve the config class for a plugin adapter.
+
+    Discovery order:
+    1. Explicit ``config.config_class_name`` field.
+    2. Convention: ``config.class_name`` + ``"Config"``.
+    3. ``config_class_name`` attribute on the adapter
+       class itself.
+    4. ``None`` -- fall back to raw dict mode.
+    """
+    candidates: list[str | None] = [
+        config.config_class_name,
+        config.class_name + "Config",
+        getattr(adapter_cls, "config_class_name", None),
+    ]
+    for name in candidates:
+        if not name:
+            continue
+        cls = getattr(module, name, None)
+        if cls is None:
+            continue
+        if isinstance(cls, type) and issubclass(
+            cls,
+            L2AdapterConfigBase,
+        ):
+            return cls
+    return None
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("plugin", PluginL2AdapterConfig)
+register_l2_adapter_factory("plugin", _create_plugin_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py
new file mode 100644
index 0000000..8c2768b
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/raw_block_l2_adapter.py
@@ -0,0 +1,803 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Raw-block L2 adapter for LMCache MP mode.
+
+Uses RawBlockCore as the synchronous durable engine and adapts it to the
+non-blocking L2AdapterInterface contract with separate eventfds for store,
+lookup, and load.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from concurrent.futures import Future, ThreadPoolExecutor
+from functools import partial
+from typing import TYPE_CHECKING, Any, Optional
+import threading
+
+if TYPE_CHECKING:
+    from lmcache.native_storage_ops import Bitmap
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc, L2AdapterListener
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import EventNotifier, create_event_notifier
+from lmcache.v1.storage_backend.raw_block import (
+    DEFAULT_IOURING_QUEUE_DEPTH,
+    RawBlockCore,
+    RawBlockCoreConfig,
+    decode_object_key,
+    encode_object_key,
+    normalize_raw_block_io_engine,
+    validate_raw_block_io_options,
+)
+
+logger = init_logger(__name__)
+
+RawBlockStoreTaskResult = tuple[
+    bool,
+    list[ObjectKey],
+    list[int],
+]
+
+
+def _make_bitmap(size: int) -> "Bitmap":
+    # First Party
+    from lmcache.native_storage_ops import Bitmap
+
+    return Bitmap(size)
+
+
+class RawBlockL2AdapterConfig(L2AdapterConfigBase):
+    """Configuration object for the built-in raw-block MP L2 adapter."""
+
+    def __init__(
+        self,
+        *,
+        device_path: str,
+        slot_bytes: int,
+        capacity_bytes: int = 0,
+        use_odirect: bool = True,
+        block_align: int = 4096,
+        header_bytes: int = 4096,
+        meta_total_bytes: int = 256 * 1024 * 1024,
+        meta_magic: str = "LMCIDX01",
+        meta_version: int = 1,
+        meta_checkpoint_interval_sec: int = 60,
+        meta_idle_quiet_ms: int = 100,
+        meta_enable_periodic: bool = True,
+        load_checkpoint_on_init: bool = True,
+        meta_verify_on_load: bool = True,
+        enable_zero_copy: bool = True,
+        io_engine: str = "posix",
+        iouring_queue_depth: int = DEFAULT_IOURING_QUEUE_DEPTH,
+        use_uring_cmd: bool = False,
+        max_data_transfer_size: int = 0,
+        num_store_workers: int = 2,
+        num_lookup_workers: int = 1,
+        num_load_workers: int = 4,
+    ):
+        """Initialize raw-block MP adapter configuration.
+
+        Args:
+            device_path: Raw device path or pre-sized file path used for L2.
+            slot_bytes: Fixed data-slot size in bytes.
+            capacity_bytes: Optional cap on usable bytes; zero uses device size.
+            use_odirect: Whether to open the raw path with O_DIRECT.
+            block_align: Required block alignment in bytes.
+            header_bytes: Per-slot header reservation in bytes.
+            meta_total_bytes: Reserved metadata checkpoint region size.
+            meta_magic: Eight-byte ASCII metadata checkpoint magic.
+            meta_version: Metadata checkpoint version.
+            meta_checkpoint_interval_sec: Periodic checkpoint interval.
+            meta_idle_quiet_ms: Quiet period before periodic checkpoints.
+            meta_enable_periodic: Whether to run the checkpoint thread.
+            load_checkpoint_on_init: Whether to load existing checkpoint metadata.
+            meta_verify_on_load: Whether recovery verifies slot headers.
+            enable_zero_copy: Whether to use aligned direct-buffer I/O.
+            io_engine: Raw-block I/O engine: ``"posix"`` or ``"io_uring"``.
+            iouring_queue_depth: Queue depth for the Rust io_uring engine.
+            use_uring_cmd: Whether to use NVMe io_uring_cmd passthrough.
+            max_data_transfer_size: Max data transfer size for a single request.
+            num_store_workers: Number of store worker threads.
+            num_lookup_workers: Number of lookup worker threads.
+            num_load_workers: Number of load worker threads.
+        """
+        super().__init__()
+        self.device_path = device_path
+        self.slot_bytes = int(slot_bytes)
+        self.capacity_bytes = int(capacity_bytes)
+        self.use_odirect = bool(use_odirect)
+        self.block_align = int(block_align)
+        self.header_bytes = int(header_bytes)
+        self.meta_total_bytes = int(meta_total_bytes)
+        self.meta_magic = meta_magic
+        self.meta_version = int(meta_version)
+        self.meta_checkpoint_interval_sec = int(meta_checkpoint_interval_sec)
+        self.meta_idle_quiet_ms = int(meta_idle_quiet_ms)
+        self.meta_enable_periodic = bool(meta_enable_periodic)
+        self.load_checkpoint_on_init = bool(load_checkpoint_on_init)
+        self.meta_verify_on_load = bool(meta_verify_on_load)
+        self.enable_zero_copy = bool(enable_zero_copy)
+        self.io_engine = normalize_raw_block_io_engine(io_engine)
+        self.iouring_queue_depth = int(iouring_queue_depth)
+        validate_raw_block_io_options(
+            iouring_queue_depth=self.iouring_queue_depth,
+        )
+        self.use_uring_cmd = bool(use_uring_cmd)
+        self.max_data_transfer_size = int(max_data_transfer_size)
+        self.num_store_workers = int(num_store_workers)
+        self.num_lookup_workers = int(num_lookup_workers)
+        self.num_load_workers = int(num_load_workers)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RawBlockL2AdapterConfig":
+        """Build and validate a raw-block config from ``--l2-adapter`` JSON."""
+        device_path = d.get("device_path")
+        if not isinstance(device_path, str) or not device_path:
+            raise ValueError("device_path must be a non-empty string")
+        if "per_tp_device_paths" in d:
+            raise ValueError(
+                "per_tp_device_paths is not supported in MP raw_block mode"
+            )
+        if not bool(d.get("persist_enabled", True)):
+            raise ValueError("raw_block requires persist_enabled=true")
+
+        slot_bytes = d.get("slot_bytes")
+        if not isinstance(slot_bytes, int) or slot_bytes <= 0:
+            raise ValueError("slot_bytes must be a positive integer")
+
+        block_align = int(d.get("block_align", 4096))
+        header_bytes = int(d.get("header_bytes", 4096))
+        meta_total_bytes = int(d.get("meta_total_bytes", 256 * 1024 * 1024))
+        capacity_bytes = int(d.get("capacity_bytes", 0))
+        io_engine = normalize_raw_block_io_engine(
+            d.get("io_engine"),
+            use_iouring=d.get("use_iouring"),
+            use_uring=d.get("use_uring"),
+        )
+        iouring_queue_depth = int(
+            d.get("iouring_queue_depth", DEFAULT_IOURING_QUEUE_DEPTH)
+        )
+        use_uring_cmd = bool(d.get("use_uring_cmd", False))
+        max_data_transfer_size = int(d.get("max_data_transfer_size", 0))
+
+        if block_align <= 0:
+            raise ValueError("block_align must be > 0")
+        if slot_bytes % block_align != 0:
+            raise ValueError("slot_bytes must be a multiple of block_align")
+        if header_bytes % block_align != 0:
+            raise ValueError("header_bytes must be a multiple of block_align")
+        if meta_total_bytes % block_align != 0:
+            raise ValueError("meta_total_bytes must be a multiple of block_align")
+        if slot_bytes < header_bytes + 1:
+            raise ValueError("slot_bytes must be >= header_bytes + 1")
+        if capacity_bytes > 0 and capacity_bytes <= meta_total_bytes:
+            raise ValueError("capacity_bytes must leave space for at least one slot")
+        validate_raw_block_io_options(
+            iouring_queue_depth=iouring_queue_depth,
+        )
+        if use_uring_cmd and io_engine != "io_uring":
+            raise ValueError("use_uring_cmd requires io_uring io_engine")
+
+        worker_defaults = {
+            "num_store_workers": 2,
+            "num_lookup_workers": 1,
+            "num_load_workers": 4,
+        }
+        worker_counts: dict[str, int] = {}
+        for field_name, default in worker_defaults.items():
+            value = int(d.get(field_name, default))
+            if value <= 0:
+                raise ValueError(f"{field_name} must be > 0")
+            worker_counts[field_name] = value
+
+        return cls(
+            device_path=device_path,
+            slot_bytes=slot_bytes,
+            capacity_bytes=capacity_bytes,
+            use_odirect=bool(d.get("use_odirect", True)),
+            block_align=block_align,
+            header_bytes=header_bytes,
+            meta_total_bytes=meta_total_bytes,
+            meta_magic=str(d.get("meta_magic", "LMCIDX01")),
+            meta_version=int(d.get("meta_version", 1)),
+            meta_checkpoint_interval_sec=int(d.get("meta_checkpoint_interval_sec", 60)),
+            meta_idle_quiet_ms=int(d.get("meta_idle_quiet_ms", 100)),
+            meta_enable_periodic=bool(d.get("meta_enable_periodic", True)),
+            load_checkpoint_on_init=bool(d.get("load_checkpoint_on_init", True)),
+            meta_verify_on_load=bool(d.get("meta_verify_on_load", True)),
+            enable_zero_copy=bool(d.get("enable_zero_copy", True)),
+            io_engine=io_engine,
+            iouring_queue_depth=iouring_queue_depth,
+            use_uring_cmd=use_uring_cmd,
+            max_data_transfer_size=max_data_transfer_size,
+            num_store_workers=worker_counts["num_store_workers"],
+            num_lookup_workers=worker_counts["num_lookup_workers"],
+            num_load_workers=worker_counts["num_load_workers"],
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        """Return human-readable raw-block adapter configuration help."""
+        return (
+            "raw_block L2 adapter config fields:\n"
+            "- device_path (str): raw device or file path (required)\n"
+            "- slot_bytes (int): slot size in bytes, aligned to block_align "
+            "(required)\n"
+            "- capacity_bytes (int): optional usable capacity cap "
+            "(default 0 = device size)\n"
+            "- use_odirect (bool): enable O_DIRECT raw I/O (default true)\n"
+            "- block_align (int): required block alignment in bytes (default 4096)\n"
+            "- header_bytes (int): per-slot header reservation (default 4096)\n"
+            "- meta_total_bytes (int): reserved metadata checkpoint region "
+            "(default 256MiB)\n"
+            "- meta_magic (str): 8-byte metadata magic (default LMCIDX01)\n"
+            "- meta_version (int): metadata version (default 1)\n"
+            "- meta_checkpoint_interval_sec (int): periodic checkpoint interval "
+            "(default 60)\n"
+            "- meta_idle_quiet_ms (int): quiet period before checkpoint (default 100)\n"
+            "- meta_enable_periodic (bool): enable periodic checkpointing "
+            "(default true)\n"
+            "- load_checkpoint_on_init (bool): load existing metadata checkpoint "
+            "on startup (default true)\n"
+            "- meta_verify_on_load (bool): validate slot headers on recovery "
+            "(default true)\n"
+            "- enable_zero_copy (bool): use aligned direct buffers when possible "
+            "(default true)\n"
+            "- io_engine (str): posix or io_uring (default posix)\n"
+            "- iouring_queue_depth (int): Rust io_uring queue depth "
+            f"(default {DEFAULT_IOURING_QUEUE_DEPTH})\n"
+            "- use_uring_cmd (bool): enable NVMe io_uring_cmd path "
+            "(default false, requires io_uring as the io_engine)\n"
+            "- max_data_transfer_size (int): for a single I/O request "
+            "(0: (default) auto detect limit splitting, > 0: explicit split, "
+            "< 0: auto detect limit splitting)\n"
+            "- num_store_workers (int): store worker threads (default 2)\n"
+            "- num_lookup_workers (int): lookup worker threads (default 1)\n"
+            "- num_load_workers (int): load worker threads (default 4)"
+        )
+
+    def to_core_config(self) -> RawBlockCoreConfig:
+        """Convert this adapter config to the shared RawBlockCore config."""
+        return RawBlockCoreConfig(
+            device_path=self.device_path,
+            capacity_bytes=self.capacity_bytes,
+            block_align=self.block_align,
+            header_bytes=self.header_bytes,
+            slot_bytes=self.slot_bytes,
+            use_odirect=self.use_odirect,
+            enable_zero_copy=self.enable_zero_copy,
+            meta_total_bytes=self.meta_total_bytes,
+            meta_magic=self.meta_magic.encode("ascii"),
+            meta_version=self.meta_version,
+            meta_checkpoint_interval_sec=self.meta_checkpoint_interval_sec,
+            meta_idle_quiet_ms=self.meta_idle_quiet_ms,
+            meta_enable_periodic=self.meta_enable_periodic,
+            load_checkpoint_on_init=self.load_checkpoint_on_init,
+            meta_verify_on_load=self.meta_verify_on_load,
+            io_engine=self.io_engine,
+            iouring_queue_depth=self.iouring_queue_depth,
+            use_uring_cmd=self.use_uring_cmd,
+            max_data_transfer_size=self.max_data_transfer_size,
+        )
+
+
+class RawBlockL2Adapter(L2AdapterInterface):
+    """MP L2 adapter that persists KV objects into raw-block slots."""
+
+    def __init__(
+        self,
+        config: RawBlockL2AdapterConfig,
+        l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+    ):
+        """Initialize the MP raw-block L2 adapter.
+
+        Args:
+            config: Validated raw-block adapter configuration.
+            l1_memory_desc: Optional L1 allocation descriptor used to validate
+                O_DIRECT alignment compatibility.
+
+        Raises:
+            ValueError: If O_DIRECT is enabled and L1 alignment is insufficient.
+            RuntimeError: If the shared core cannot open or recover the raw
+                device.
+
+        Notes:
+            Resources created before an initialization failure are closed before
+            the exception is re-raised.
+        """
+        super().__init__()
+        if (
+            (config.use_odirect or config.io_engine == "io_uring")
+            and l1_memory_desc is not None
+            and l1_memory_desc.align_bytes < config.block_align
+        ):
+            raise ValueError(
+                "raw_block requires l1_align_bytes >= block_align when "
+                "use_odirect=true or io_engine=io_uring"
+            )
+
+        self._closed = False
+        self._core: RawBlockCore
+        self._store_efd: EventNotifier | None = None
+        self._lookup_efd: EventNotifier | None = None
+        self._load_efd: EventNotifier | None = None
+        self._store_pool: ThreadPoolExecutor
+        self._lookup_pool: ThreadPoolExecutor
+        self._load_pool: ThreadPoolExecutor
+
+        try:
+            self._core = RawBlockCore(config.to_core_config(), key_namespace="object")
+            if config.io_engine == "io_uring":
+                logger.warning(
+                    "RawBlockL2Adapter: MP raw_block uses io_uring without "
+                    "fixed-buffer registration; zero-copy fixed buffers are "
+                    "disabled unless registered by a future MP allocator path"
+                )
+            self._max_capacity_bytes = int(
+                self._core.report_status().get("usable_capacity_bytes", 0)
+            )
+            self._seed_usage_from_core_snapshot()
+
+            self._store_efd = create_event_notifier()
+            self._lookup_efd = create_event_notifier()
+            self._load_efd = create_event_notifier()
+
+            self._store_pool = ThreadPoolExecutor(
+                max_workers=config.num_store_workers,
+                thread_name_prefix="rawblk-store",
+            )
+            self._lookup_pool = ThreadPoolExecutor(
+                max_workers=config.num_lookup_workers,
+                thread_name_prefix="rawblk-lookup",
+            )
+            self._load_pool = ThreadPoolExecutor(
+                max_workers=config.num_load_workers,
+                thread_name_prefix="rawblk-load",
+            )
+        except Exception:
+            self._cleanup_after_init_failure()
+            raise
+
+        self._lock = threading.Lock()
+        self._next_task_id: L2TaskId = 0
+
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+
+        self._store_inflight_tasks: int = 0
+        self._lookup_inflight_tasks: int = 0
+        self._load_inflight_tasks: int = 0
+
+    def get_store_event_fd(self) -> int:
+        """Return the eventfd signaled when store tasks complete."""
+        if self._store_efd is None:
+            return -1
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        """Return the eventfd signaled when lookup-and-lock tasks complete."""
+        if self._lookup_efd is None:
+            return -1
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        """Return the eventfd signaled when load tasks complete."""
+        if self._load_efd is None:
+            return -1
+        return self._load_efd.fileno()
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Submit a non-blocking raw-block store task.
+
+        Args:
+            keys: Object keys to persist.
+            objects: Memory objects containing payloads for ``keys``.
+
+        Returns:
+            Task ID that can be observed through ``pop_completed_store_tasks``.
+
+        Raises:
+            ValueError: If either list is empty or the lengths differ.
+        """
+        if not keys or not objects:
+            raise ValueError("keys and objects must be non-empty")
+        if len(keys) != len(objects):
+            raise ValueError("keys and objects must have the same length")
+
+        with self._lock:
+            self._raise_if_closed_locked()
+            task_id = self._get_next_task_id_locked()
+            self._store_inflight_tasks += 1
+        try:
+            future = self._store_pool.submit(
+                self._run_store_task, list(keys), list(objects)
+            )
+        except Exception:
+            with self._lock:
+                self._store_inflight_tasks -= 1
+            raise
+        future.add_done_callback(partial(self._finish_store_task, task_id))
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        """Drain and return completed store task results."""
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        """Submit a non-blocking lookup-and-lock task.
+
+        Args:
+            keys: Object keys to look up in raw-block L2.
+
+        Returns:
+            Task ID whose bitmap can be queried with
+            ``query_lookup_and_lock_result``.
+
+        Raises:
+            ValueError: If ``keys`` is empty.
+        """
+        if not keys:
+            raise ValueError("keys must be non-empty")
+        with self._lock:
+            self._raise_if_closed_locked()
+            task_id = self._get_next_task_id_locked()
+            self._lookup_inflight_tasks += 1
+        try:
+            future = self._lookup_pool.submit(self._run_lookup_task, list(keys))
+        except Exception:
+            with self._lock:
+                self._lookup_inflight_tasks -= 1
+            raise
+        future.add_done_callback(partial(self._finish_lookup_task, task_id, len(keys)))
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        """Return and remove a completed lookup bitmap if available."""
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        """Release L2 locks acquired by lookup-and-lock."""
+        encoded_keys = [encode_object_key(key).encoded for key in keys]
+        self._core.unlock_many(encoded_keys)
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Submit a non-blocking raw-block load task.
+
+        Args:
+            keys: Object keys to load.
+            objects: Caller-provided destination buffers.
+
+        Returns:
+            Task ID whose bitmap can be queried with ``query_load_result``.
+
+        Raises:
+            ValueError: If either list is empty or the lengths differ.
+        """
+        if not keys or not objects:
+            raise ValueError("keys and objects must be non-empty")
+        if len(keys) != len(objects):
+            raise ValueError("keys and objects must have the same length")
+
+        with self._lock:
+            self._raise_if_closed_locked()
+            task_id = self._get_next_task_id_locked()
+            self._load_inflight_tasks += 1
+        try:
+            future = self._load_pool.submit(
+                self._run_load_task, list(keys), list(objects)
+            )
+        except Exception:
+            with self._lock:
+                self._load_inflight_tasks -= 1
+            raise
+        future.add_done_callback(partial(self._finish_load_task, task_id, len(keys)))
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        """Return and remove a completed load bitmap if available."""
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        """Delete keys from raw-block L2 and notify listeners for removals."""
+        encoded_keys = [encode_object_key(key).encoded for key in keys]
+        metas = self._core.get_metadata_many(encoded_keys)
+        deleted_bitmap = self._core.delete_many(encoded_keys, force=False)
+        deleted_keys: list[ObjectKey] = []
+        deleted_sizes: list[int] = []
+        for key, meta, deleted in zip(keys, metas, deleted_bitmap, strict=False):
+            if not deleted:
+                continue
+            deleted_keys.append(key)
+            deleted_sizes.append(0 if meta is None else int(self._core.slot_bytes))
+        if deleted_keys:
+            try:
+                self._notify_keys_deleted(deleted_keys, deleted_sizes)
+            except Exception as e:
+                logger.warning("RawBlockL2Adapter delete notification failed: %s", e)
+
+    def register_listener(self, listener: "L2AdapterListener") -> None:
+        """Register a listener and seed it with currently indexed keys."""
+        super().register_listener(listener)
+        keys = self._snapshot_indexed_object_keys()
+        if not keys:
+            return
+        try:
+            listener.on_l2_keys_stored(keys, [0] * len(keys))
+        except Exception as e:
+            logger.warning(
+                "RawBlockL2Adapter listener recovery bootstrap failed: %s", e
+            )
+
+    def close(self) -> None:
+        """Wait for worker pools, close the core, and close eventfds."""
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+
+        self._store_pool.shutdown(wait=True)
+        self._lookup_pool.shutdown(wait=True)
+        self._load_pool.shutdown(wait=True)
+
+        self._core.close()
+
+        with self._lock:
+            store_efd = self._store_efd
+            lookup_efd = self._lookup_efd
+            load_efd = self._load_efd
+            self._store_efd = None
+            self._lookup_efd = None
+            self._load_efd = None
+
+        if store_efd is not None:
+            store_efd.close()
+        if lookup_efd is not None:
+            lookup_efd.close()
+        if load_efd is not None:
+            load_efd.close()
+
+    def report_status(self) -> dict:
+        """Return adapter health, task counters, and core status."""
+        core_status = self._core.report_status()
+        with self._lock:
+            return {
+                "is_healthy": core_status.get("is_healthy", True) and not self._closed,
+                "type": "RawBlockL2Adapter",
+                "store_inflight_task_count": self._store_inflight_tasks,
+                "lookup_inflight_task_count": self._lookup_inflight_tasks,
+                "load_inflight_task_count": self._load_inflight_tasks,
+                "completed_store_task_count": len(self._completed_store_tasks),
+                "completed_lookup_task_count": len(self._completed_lookup_tasks),
+                "completed_load_task_count": len(self._completed_load_tasks),
+                "core": core_status,
+            }
+
+    def _raise_if_closed_locked(self) -> None:
+        if self._closed:
+            raise RuntimeError("RawBlockL2Adapter is closed")
+
+    def _get_next_task_id_locked(self) -> L2TaskId:
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        return task_id
+
+    def _seed_usage_from_core_snapshot(self) -> None:
+        """Seed byte counters for entries recovered by RawBlockCore startup."""
+        recovered_keys = self._snapshot_indexed_object_keys()
+        if not recovered_keys:
+            return
+
+        slot_bytes = int(self._core.slot_bytes)
+        total_delta = len(recovered_keys) * slot_bytes
+        by_salt: dict[str, int] = {}
+        for key in recovered_keys:
+            by_salt[key.cache_salt] = by_salt.get(key.cache_salt, 0) + slot_bytes
+
+        with self._usage_lock:
+            self._total_bytes_used += total_delta
+            for salt, delta in by_salt.items():
+                self._bytes_by_cache_salt[salt] = (
+                    self._bytes_by_cache_salt.get(salt, 0) + delta
+                )
+
+    def _snapshot_indexed_object_keys(self) -> list[ObjectKey]:
+        """Return decoded ObjectKeys for all indexed raw-block entries."""
+        keys: list[ObjectKey] = []
+        for encoded_key in self._core.snapshot_indexed_keys():
+            try:
+                keys.append(decode_object_key(encoded_key))
+            except Exception as e:
+                logger.warning(
+                    "RawBlockL2Adapter could not decode indexed key %r: %s",
+                    encoded_key,
+                    e,
+                )
+        return keys
+
+    def _run_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> RawBlockStoreTaskResult:
+        """Persist one submitted store batch in the worker pool.
+
+        Args:
+            keys: Object keys submitted for storage.
+            objects: Payload buffers aligned with ``keys``.
+
+        Returns:
+            A 3-tuple containing:
+
+            - task success for the whole batch
+            - newly stored object keys
+            - raw-block slot byte charges aligned with the newly stored keys
+        """
+        specs = [encode_object_key(key) for key in keys]
+        put_result = self._core.put_many(specs, objects)
+        stored_encoded = set(put_result.stored_keys)
+        slot_bytes = int(self._core.slot_bytes)
+        stored_keys: list[ObjectKey] = []
+        stored_sizes: list[int] = []
+        for key, spec in zip(keys, specs, strict=False):
+            if spec.encoded not in stored_encoded:
+                continue
+            stored_keys.append(key)
+            stored_sizes.append(slot_bytes)
+        return all(put_result.results), stored_keys, stored_sizes
+
+    def _finish_store_task(
+        self,
+        task_id: L2TaskId,
+        future: Future[RawBlockStoreTaskResult],
+    ) -> None:
+        success = False
+        stored_keys: list[ObjectKey] = []
+        stored_sizes: list[int] = []
+        bytes_transferred = 0
+        try:
+            success, stored_keys, stored_sizes = future.result()
+            bytes_transferred = sum(stored_sizes)
+        except Exception as e:
+            logger.error("RawBlockL2Adapter store task %d failed: %s", task_id, e)
+        with self._lock:
+            self._store_inflight_tasks -= 1
+            self._completed_store_tasks[task_id] = L2StoreResult(
+                success, bytes_transferred
+            )
+            event_fd = self._store_efd
+        if stored_keys:
+            try:
+                self._notify_keys_stored(stored_keys, stored_sizes)
+            except Exception as e:
+                logger.warning("RawBlockL2Adapter store notification failed: %s", e)
+        self._signal_event_fd(event_fd)
+
+    def _run_lookup_task(self, keys: list[ObjectKey]) -> Bitmap:
+        specs = [encode_object_key(key) for key in keys]
+        exists = self._core.exists_many([spec.encoded for spec in specs], lock=True)
+        bitmap = _make_bitmap(len(keys))
+        for i, ok in enumerate(exists):
+            if ok:
+                bitmap.set(i)
+        return bitmap
+
+    def _finish_lookup_task(
+        self, task_id: L2TaskId, bitmap_size: int, future: Future[Any]
+    ) -> None:
+        bitmap = _make_bitmap(bitmap_size)
+        try:
+            bitmap = future.result()
+        except Exception as e:
+            logger.error("RawBlockL2Adapter lookup task %d failed: %s", task_id, e)
+        with self._lock:
+            self._lookup_inflight_tasks -= 1
+            self._completed_lookup_tasks[task_id] = bitmap
+            event_fd = self._lookup_efd
+        self._signal_event_fd(event_fd)
+
+    def _run_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> tuple[Bitmap, list[ObjectKey]]:
+        specs = [encode_object_key(key) for key in keys]
+        results = self._core.load_many_into([spec.encoded for spec in specs], objects)
+        bitmap = _make_bitmap(len(keys))
+        accessed_keys: list[ObjectKey] = []
+        for i, ok in enumerate(results):
+            if ok:
+                bitmap.set(i)
+                accessed_keys.append(keys[i])
+        return bitmap, accessed_keys
+
+    def _finish_load_task(
+        self, task_id: L2TaskId, bitmap_size: int, future: Future[Any]
+    ) -> None:
+        bitmap = _make_bitmap(bitmap_size)
+        accessed_keys: list[ObjectKey] = []
+        try:
+            bitmap, accessed_keys = future.result()
+        except Exception as e:
+            logger.error("RawBlockL2Adapter load task %d failed: %s", task_id, e)
+        with self._lock:
+            self._load_inflight_tasks -= 1
+            self._completed_load_tasks[task_id] = bitmap
+            event_fd = self._load_efd
+        if accessed_keys:
+            try:
+                self._notify_keys_accessed(accessed_keys)
+            except Exception as e:
+                logger.warning("RawBlockL2Adapter access notification failed: %s", e)
+        self._signal_event_fd(event_fd)
+
+    def _signal_event_fd(self, event_fd: EventNotifier | None) -> None:
+        try:
+            if event_fd is not None:
+                event_fd.notify()
+        except OSError:
+            logger.debug("event notifier was closed before signaling")
+
+    def _cleanup_after_init_failure(self) -> None:
+        for pool_name in ("_store_pool", "_lookup_pool", "_load_pool"):
+            pool = getattr(self, pool_name, None)
+            if pool is not None:
+                pool.shutdown(wait=False, cancel_futures=True)
+                setattr(self, pool_name, None)
+
+        core = getattr(self, "_core", None)
+        if core is not None:
+            core.close()
+
+        for fd_name in ("_store_efd", "_lookup_efd", "_load_efd"):
+            fd = getattr(self, fd_name, None)
+            if fd is not None:
+                fd.close()
+                setattr(self, fd_name, None)
+
+        self._closed = True
+
+
+register_l2_adapter_type("raw_block", RawBlockL2AdapterConfig)
+
+
+def _create_raw_block_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    return RawBlockL2Adapter(config, l1_memory_desc)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("raw_block", _create_raw_block_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/reconfiguration.py b/lmcache/v1/distributed/l2_adapters/reconfiguration.py
new file mode 100644
index 0000000..a9a5504
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/reconfiguration.py
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generic runtime reconfiguration protocol for L2 adapters."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Optional, Protocol, TypedDict, runtime_checkable
+
+
+class L2ReconfigureError(RuntimeError):
+    """HTTP-mappable runtime L2 reconfiguration error."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        payload: Optional[dict[str, object]] = None,
+    ) -> None:
+        """Create a runtime reconfiguration error.
+
+        Args:
+            status_code: HTTP status code the API should return.
+            message: Human-readable error message.
+            payload: Optional response body. When omitted, ``{"error": message}``
+                is used.
+        """
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload if payload is not None else {"error": message}
+
+
+class L2ReconfigureStatus(TypedDict):
+    """Standard status envelope for runtime-reconfigurable L2 adapters."""
+
+    backend: str
+    supported_operations: list[str]
+    status: dict[str, object]
+
+
+@runtime_checkable
+class L2ReconfigurableAdapter(Protocol):
+    """Protocol implemented by L2 adapters with runtime reconfiguration."""
+
+    def reconfigure_status(self) -> L2ReconfigureStatus:
+        """Return JSON-serializable runtime reconfiguration status."""
+        ...
+
+    def reconfigure(
+        self,
+        operation: str,
+        payload: dict[str, object],
+    ) -> dict:
+        """Apply an adapter-specific runtime reconfiguration operation.
+
+        Args:
+            operation: Adapter-specific operation name.
+            payload: Adapter-specific operation payload.
+
+        Returns:
+            JSON-serializable operation result.
+        """
+        ...
diff --git a/lmcache/v1/distributed/l2_adapters/resp_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/resp_l2_adapter.py
new file mode 100644
index 0000000..0f95fc3
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/resp_l2_adapter.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+RESP (Redis/Valkey) L2 adapter config and factory.
+
+Backed by the native C++ Redis connector wrapped with
+``NativeConnectorL2Adapter``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Optional
+import os
+
+if TYPE_CHECKING:
+    from lmcache.v1.distributed.internal_api import (
+        L1MemoryDesc,
+    )
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+
+logger = init_logger(__name__)
+
+
+class RESPL2AdapterConfig(L2AdapterConfigBase):
+    """
+    Config for an L2 adapter backed by a native RESP
+    connector (Redis/Valkey).
+
+    Fields:
+    - host: server hostname or IP.
+    - port: server port.
+    - num_workers: C++ worker threads for I/O (default 8).
+    - username: optional auth username.
+    - password: optional auth password.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        num_workers: int = 8,
+        username: str = "",
+        password: str = "",
+        max_capacity_gb: float = 0,
+    ):
+        super().__init__()
+        self.host = host
+        self.port = port
+        self.num_workers = num_workers
+        self.username = username
+        self.password = password
+        self.max_capacity_gb = max_capacity_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RESPL2AdapterConfig":
+        host = d.get("host")
+        if not isinstance(host, str) or not host:
+            raise ValueError("host must be a non-empty string")
+
+        port = d.get("port")
+        if not isinstance(port, int) or port <= 0:
+            raise ValueError("port must be a positive integer")
+
+        num_workers = d.get("num_workers", 8)
+        if not isinstance(num_workers, int) or num_workers <= 0:
+            raise ValueError("num_workers must be a positive integer")
+
+        username = d.get("username", "")
+        password = d.get("password", "")
+
+        max_capacity_gb = d.get("max_capacity_gb", 0)
+        if not isinstance(max_capacity_gb, (int, float)) or max_capacity_gb < 0:
+            raise ValueError("max_capacity_gb must be a non-negative number")
+
+        return cls(
+            host=host,
+            port=port,
+            num_workers=num_workers,
+            username=str(username),
+            password=str(password),
+            max_capacity_gb=float(max_capacity_gb),
+        )
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "RESP L2 adapter config fields:\n"
+            "- host (str): Redis/Valkey server hostname "
+            "or IP (required)\n"
+            "- port (int): server port (required, >0)\n"
+            "- num_workers (int): C++ worker threads "
+            "for I/O (default 8, >0)\n"
+            "- username (str): auth username "
+            "(default empty)\n"
+            "- password (str): auth password "
+            "(default empty)\n"
+            "- max_capacity_gb (float): max L2 capacity "
+            "in GB for usage tracking / eviction "
+            "(default 0 = disabled)\n\n"
+            "Environment variable defaults (used when "
+            "config value is empty, read at adapter "
+            "creation, not stored in config):\n"
+            "- LMCACHE_RESP_USERNAME: default username\n"
+            "- LMCACHE_RESP_PASSWORD: default password\n"
+            "- LMCACHE_RESP_HOST: default host\n"
+            "- LMCACHE_RESP_PORT: default port"
+        )
+
+
+def _create_resp_l2_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    """Create a NativeConnectorL2Adapter backed by the
+    C++ Redis connector."""
+    try:
+        # First Party
+        from lmcache.lmcache_redis import (
+            LMCacheRedisClient,
+        )
+    except ImportError as e:
+        raise RuntimeError(
+            "RESP L2 adapter requires the C++ Redis "
+            "extension. Build with: pip install -e ."
+        ) from e
+
+    # Lazy import to avoid circular dependency
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (  # noqa: E501
+        NativeConnectorL2Adapter,
+    )
+
+    assert isinstance(config, RESPL2AdapterConfig)
+
+    # Config/CLI args take precedence over environment variables,
+    # which serve as defaults. This keeps secrets out of logged
+    # config while allowing explicit CLI overrides.
+    host = config.host or os.environ.get("LMCACHE_RESP_HOST", "")
+    port = config.port if config.port else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+    username = config.username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+    password = config.password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+    native_client = LMCacheRedisClient(
+        host,
+        port,
+        config.num_workers,
+        username,
+        password,
+    )
+    logger.info(
+        "Created RESP L2 adapter: %s:%d (workers=%d)",
+        host,
+        port,
+        config.num_workers,
+    )
+    return NativeConnectorL2Adapter(
+        native_client, max_capacity_gb=config.max_capacity_gb
+    )
+
+
+# Self-register config type and adapter factory
+register_l2_adapter_type("resp", RESPL2AdapterConfig)
+register_l2_adapter_factory("resp", _create_resp_l2_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/s3_l2_adapter.py b/lmcache/v1/distributed/l2_adapters/s3_l2_adapter.py
new file mode 100644
index 0000000..f42d283
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/s3_l2_adapter.py
@@ -0,0 +1,1296 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+S3 L2 adapter using the AWS CRT Python bindings.
+
+Wraps the same awscrt.s3 client used by the non-MP ``S3Connector`` but
+exposes the poll-driven ``L2AdapterInterface`` contract instead of the
+async/await ``RemoteConnector`` one.
+
+Pattern follows ``FSL2Adapter`` (asyncio loop on a daemon thread + 3
+eventfds) and adds refcount-based locking + capacity tracking for
+eviction, modelled on ``NativeConnectorL2Adapter``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import defaultdict
+from typing import TYPE_CHECKING, Optional
+from urllib.parse import quote as url_quote
+from urllib.parse import urlencode
+import asyncio
+import ctypes
+import threading
+import xml.etree.ElementTree as ET
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.api import MemoryLayoutDesc
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+    from lmcache.v1.memory_management import MemoryObj
+
+# Third Party
+from awscrt import auth, io, s3
+from awscrt.http import HttpHeaders, HttpRequest
+from awscrt.io import ClientTlsContext, TlsConnectionOptions, TlsContextOptions
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import KeyEntry, KeyListPage, ObjectKey
+from lmcache.v1.distributed.internal_api import L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    register_l2_adapter_type,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    register_l2_adapter_factory,
+)
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Helpers (lifted from s3_connector.py / native_connector_l2_adapter.py)
+# ---------------------------------------------------------------------------
+
+
+def _string_to_object_key(name: str) -> ObjectKey:
+    """Reverse of :func:`_object_key_to_string`.
+
+    Expects
+    ``<model_name>@<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>[@<cache_salt>]``.
+
+    Raises:
+        ValueError: ``name`` does not match the expected format.
+    """
+    parts = name.split("@")
+    if len(parts) == 4:
+        model_name, kv_rank_hex, object_group_id_hex, chunk_hash_hex = parts
+        cache_salt = ""
+    elif len(parts) == 5:
+        (
+            model_name,
+            kv_rank_hex,
+            object_group_id_hex,
+            chunk_hash_hex,
+            cache_salt,
+        ) = parts
+    else:
+        raise ValueError(f"unparsable S3 object name {name!r}: wrong field count")
+    try:
+        kv_rank = int(kv_rank_hex, 16)
+    except ValueError as exc:
+        raise ValueError(
+            f"unparsable S3 object name {name!r}: bad kv_rank {kv_rank_hex!r}"
+        ) from exc
+    try:
+        object_group_id = int(object_group_id_hex, 16)
+    except ValueError as exc:
+        raise ValueError(
+            f"unparsable S3 object name {name!r}: "
+            f"bad object_group_id {object_group_id_hex!r}"
+        ) from exc
+    try:
+        chunk_hash = bytes.fromhex(chunk_hash_hex)
+    except ValueError as exc:
+        raise ValueError(
+            f"unparsable S3 object name {name!r}: bad chunk_hash {chunk_hash_hex!r}"
+        ) from exc
+    return ObjectKey(
+        chunk_hash=chunk_hash,
+        model_name=model_name,
+        kv_rank=kv_rank,
+        object_group_id=object_group_id,
+        cache_salt=cache_salt,
+    )
+
+
+def _parse_list_response_xml(
+    body: bytes,
+) -> tuple[list[tuple[ObjectKey, int]], Optional[str]]:
+    """Parse a ListObjectsV2 XML response into ``(entries, next_token)``.
+
+    Entries this adapter can't parse (foreign objects in the bucket)
+    are skipped silently. ``next_token`` is ``None`` when the listing
+    is not truncated.
+
+    Raises:
+        ValueError: the response body is not valid XML.
+    """
+    try:
+        root = ET.fromstring(body)
+    except ET.ParseError as exc:
+        raise ValueError(f"malformed ListObjectsV2 XML: {exc}") from None
+
+    # Strip the default XML namespace so ``findall("Contents")`` works.
+    # The tree is local to this function — do not cache or return it.
+    for elem in root.iter():
+        if "}" in elem.tag:
+            elem.tag = elem.tag.split("}", 1)[1]
+
+    entries: list[tuple[ObjectKey, int]] = []
+    for contents in root.findall("Contents"):
+        key_elem = contents.find("Key")
+        size_elem = contents.find("Size")
+        if key_elem is None or key_elem.text is None:
+            continue
+        try:
+            obj_key = _string_to_object_key(key_elem.text)
+        except ValueError as exc:
+            logger.debug(
+                "Skipping unparsable S3 object %r in listing: %s", key_elem.text, exc
+            )
+            continue
+        size = 0
+        if size_elem is not None and size_elem.text is not None:
+            try:
+                size = int(size_elem.text)
+            except ValueError:
+                pass
+        entries.append((obj_key, size))
+
+    next_token_elem = root.find("NextContinuationToken")
+    next_token = (
+        next_token_elem.text
+        if next_token_elem is not None and next_token_elem.text
+        else None
+    )
+    return entries, next_token
+
+
+def _object_key_to_string(key: ObjectKey) -> str:
+    """Serialize an ObjectKey to a deterministic S3 object name.
+
+    Unsalted::
+
+        <model_name>@<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>
+
+    Salted (trailing ``cache_salt``)::
+
+        <model_name>@<kv_rank_hex>@<object_group_id_hex>@<chunk_hash_hex>@<cache_salt>
+
+    ``@`` in ``model_name`` and ``cache_salt`` is rejected by
+    ``ObjectKey.__post_init__``, so the format is unambiguous.
+    """
+    base = (
+        f"{key.model_name}@{key.kv_rank:08x}"
+        f"@{key.object_group_id:x}@{key.chunk_hash.hex()}"
+    )
+    if key.cache_salt:
+        return f"{base}@{key.cache_salt}"
+    return base
+
+
+def _format_safe_path(key_str: str) -> str:
+    """URL-encode the object name to form a safe HTTP path."""
+    return "/" + url_quote(key_str)
+
+
+def _make_credentials_provider(
+    config: "S3L2AdapterConfig",
+) -> auth.AwsCredentialsProvider:
+    """Build an awscrt credentials provider for the S3 L2 adapter.
+
+    Resolution:
+
+    1. Static keys from ``config.aws_access_key_id`` /
+       ``config.aws_secret_access_key`` when both are set.
+    2. Otherwise, delegate to ``boto3``. ``botocore``'s default chain
+       covers env vars, shared profile, container credentials
+       (``AWS_CONTAINER_CREDENTIALS_FULL_URI`` /
+       ``AWS_CONTAINER_CREDENTIALS_RELATIVE_URI``), web-identity
+       (``AWS_WEB_IDENTITY_TOKEN_FILE`` / ``AWS_ROLE_ARN``), and IMDS
+       uniformly, including HTTPS endpoints that the awscrt Python
+       binding's default chain cannot reach. The resolved
+       ``RefreshableCredentials`` are republished to awscrt via
+       ``new_delegate``; every sign call invokes
+       ``get_frozen_credentials()`` so rotating short-lived OIDC
+       credentials refresh before expiry.
+
+    Args:
+        config: S3 L2 adapter configuration.
+
+    Returns:
+        An ``AwsCredentialsProvider`` ready to attach to ``S3Request``.
+
+    Raises:
+        ImportError: ``boto3`` is required but not installed.
+        RuntimeError: ``boto3`` returned no resolvable credentials.
+    """
+    if config.aws_access_key_id and config.aws_secret_access_key:
+        logger.info("S3L2Adapter using explicit AWS credentials")
+        return auth.AwsCredentialsProvider.new_static(
+            config.aws_access_key_id,
+            config.aws_secret_access_key,
+        )
+
+    logger.info("S3L2Adapter resolving AWS credentials via boto3 delegate")
+    try:
+        # Third Party
+        import boto3
+    except ImportError as e:
+        raise ImportError(
+            "S3L2Adapter requires boto3 to resolve credentials when "
+            "aws_access_key_id / aws_secret_access_key are not set. "
+            "Install boto3 or provide static credentials in the adapter "
+            "config."
+        ) from e
+
+    boto_creds = boto3.Session().get_credentials()
+    if boto_creds is None:
+        raise RuntimeError("S3L2Adapter: boto3 found no credentials in the environment")
+
+    def fetch() -> auth.AwsCredentials:
+        frozen = boto_creds.get_frozen_credentials()
+        return auth.AwsCredentials(
+            frozen.access_key,
+            frozen.secret_key,
+            frozen.token,
+        )
+
+    return auth.AwsCredentialsProvider.new_delegate(fetch)
+
+
+class MemoryViewStream:
+    """Zero-copy stream adapter over a ``memoryview``-like object."""
+
+    def __init__(self, mv):
+        self.mv = memoryview(mv).cast("B")
+        self.offset = 0
+
+    def read(self, size=None):
+        if size is None:
+            size = len(self.mv) - self.offset
+        if size < 0:
+            size = 0
+        end = min(self.offset + size, len(self.mv))
+        result = self.mv[self.offset : end]
+        self.offset = end
+        return result
+
+    def seek(self, offset, whence=0):
+        if whence == 0:
+            self.offset = offset
+        elif whence == 1:
+            self.offset += offset
+        elif whence == 2:
+            self.offset = len(self.mv) + offset
+        return self.offset
+
+    def tell(self):
+        return self.offset
+
+    def __len__(self):
+        return len(self.mv)
+
+
+def _is_connection_error(error_msg: str) -> bool:
+    return (
+        "CONNECTION_REFUSED" in error_msg
+        or "SOCKET" in error_msg
+        or "DNS" in error_msg
+        or "TIMEOUT" in error_msg
+    )
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+
+class S3L2AdapterConfig(L2AdapterConfigBase):
+    """Config for the S3 L2 adapter.
+
+    Fields:
+    - s3_endpoint (str, required): bucket URL using **virtual-hosted**
+      style; accepts either ``"s3://<bucket>.<host>"`` or the bare
+      ``"<bucket>.<host>"`` form. The bucket name must be part of the
+      host because requests are signed and routed against this Host
+      header (path-style addressing is not supported).
+    - s3_region (str, required): AWS region used for SigV4.
+    - s3_num_io_threads (int): CRT IO threads.
+    - s3_prefer_http2 (bool): ALPN negotiate to HTTP/2.
+    - s3_enable_s3express (bool): enable S3 Express signing.
+    - disable_tls (bool): bypass TLS on the bucket data plane (for
+      S3-compatible HTTP endpoints). Does not affect the credentials
+      resolver, which may still issue HTTPS calls.
+    - aws_access_key_id / aws_secret_access_key (str): optional static
+      credentials. When unset, credentials are resolved through boto3
+      (env vars, profile, container, web-identity, IMDS).
+    - max_capacity_gb (float): aggregate capacity used by
+      ``get_usage()``; ``0`` disables aggregate eviction
+      (``usage_fraction == -1.0``).
+    """
+
+    def __init__(
+        self,
+        s3_endpoint: str,
+        s3_region: str,
+        s3_num_io_threads: int = 64,
+        s3_prefer_http2: bool = True,
+        s3_enable_s3express: bool = False,
+        disable_tls: bool = False,
+        aws_access_key_id: Optional[str] = None,
+        aws_secret_access_key: Optional[str] = None,
+        max_capacity_gb: float = 0.0,
+    ):
+        self.s3_endpoint = s3_endpoint
+        self.s3_region = s3_region
+        self.s3_num_io_threads = s3_num_io_threads
+        self.s3_prefer_http2 = s3_prefer_http2
+        self.s3_enable_s3express = s3_enable_s3express
+        self.disable_tls = disable_tls
+        self.aws_access_key_id = aws_access_key_id
+        self.aws_secret_access_key = aws_secret_access_key
+        self.max_capacity_gb = max_capacity_gb
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "S3L2AdapterConfig":
+        endpoint = d.get("s3_endpoint")
+        if not isinstance(endpoint, str) or not endpoint:
+            raise ValueError("s3_endpoint must be a non-empty string")
+        region = d.get("s3_region")
+        if not isinstance(region, str) or not region:
+            raise ValueError("s3_region must be a non-empty string")
+
+        def _int(key, default):
+            v = d.get(key, default)
+            if not isinstance(v, int) or isinstance(v, bool) or v <= 0:
+                raise ValueError(f"{key} must be a positive integer")
+            return v
+
+        def _bool(key, default):
+            v = d.get(key, default)
+            if not isinstance(v, bool):
+                raise ValueError(f"{key} must be a boolean")
+            return v
+
+        def _opt_str(key):
+            v = d.get(key, None)
+            if v is None:
+                return None
+            if not isinstance(v, str):
+                raise ValueError(f"{key} must be a string")
+            return v
+
+        max_cap = d.get("max_capacity_gb", 0.0)
+        if not isinstance(max_cap, (int, float)) or isinstance(max_cap, bool):
+            raise ValueError("max_capacity_gb must be a number")
+
+        cfg = cls(
+            s3_endpoint=endpoint,
+            s3_region=region,
+            s3_num_io_threads=_int("s3_num_io_threads", 64),
+            s3_prefer_http2=_bool("s3_prefer_http2", True),
+            s3_enable_s3express=_bool("s3_enable_s3express", False),
+            disable_tls=_bool("disable_tls", False),
+            aws_access_key_id=_opt_str("aws_access_key_id"),
+            aws_secret_access_key=_opt_str("aws_secret_access_key"),
+            max_capacity_gb=float(max_cap),
+        )
+        cfg.eviction_config = cls._parse_eviction_config(d)
+        return cfg
+
+    @classmethod
+    def help(cls) -> str:
+        return (
+            "S3 L2 adapter config fields:\n"
+            "- s3_endpoint (str, required): virtual-hosted bucket URL "
+            "('s3://<bucket>.<host>' or '<bucket>.<host>')\n"
+            "- s3_region (str, required): AWS region for SigV4\n"
+            "- s3_num_io_threads (int): CRT IO threads (default 64)\n"
+            "- s3_prefer_http2 (bool): try HTTP/2 via ALPN (default true)\n"
+            "- s3_enable_s3express (bool): S3 Express signing (default false)\n"
+            "- disable_tls (bool): bypass TLS on the bucket data plane\n"
+            "- aws_access_key_id / aws_secret_access_key (str): static creds; "
+            "when unset, boto3 resolves credentials\n"
+            "- max_capacity_gb (float): capacity for get_usage (0 = disabled)\n"
+            "- eviction (dict): optional, see L2AdapterConfigBase"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------------
+
+
+class S3L2Adapter(L2AdapterInterface):
+    """S3-backed L2 adapter.
+
+    Concurrency model: one asyncio event loop on a dedicated daemon
+    thread. Each ``submit_*`` schedules a coroutine via
+    ``run_coroutine_threadsafe``; that coroutine launches parallel
+    ``s3.S3Request`` handles, awaits them with ``asyncio.gather``, and
+    signals the corresponding eventfd when done.
+
+    Locking: client-side refcount in ``_locked_keys``. ``delete()``
+    skips any key whose refcount is > 0 — prevents evicting a key that
+    a concurrent load is about to read.
+
+    Circuit breaker: after ``max_connection_failures`` consecutive
+    connection-class errors, ``connection_disabled`` is set; all
+    subsequent submits short-circuit and record failure without
+    touching S3.
+    """
+
+    max_connection_failures = 3
+
+    def __init__(self, config: S3L2AdapterConfig):
+        super().__init__(max_capacity_bytes=int(config.max_capacity_gb * (1024**3)))
+        self._config = config
+
+        endpoint = config.s3_endpoint
+        if endpoint.startswith("s3://"):
+            endpoint = endpoint[len("s3://") :]
+        self._endpoint = endpoint
+        self._region = config.s3_region
+        self._enable_s3express = config.s3_enable_s3express
+
+        # awscrt client setup (mirrors s3_connector.py:103-153)
+        event_loop_group = io.EventLoopGroup(config.s3_num_io_threads)
+        host_resolver = io.DefaultHostResolver(event_loop_group)
+        client_bootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
+
+        self._credentials_provider = _make_credentials_provider(config)
+
+        tls_opts = None
+        if config.s3_prefer_http2:
+            tls_ctx = ClientTlsContext(TlsContextOptions())
+            tls_opts = TlsConnectionOptions(tls_ctx)
+            try:
+                tls_opts.set_alpn_list(["h2", "http/1.1"])
+            except Exception:
+                tls_opts = None
+
+        signing_config = None
+        if self._enable_s3express:
+            signing_config = auth.AwsSigningConfig(
+                algorithm=auth.AwsSigningAlgorithm.V4_S3EXPRESS,
+                region=self._region,
+                service="s3",
+                credentials_provider=self._credentials_provider,
+            )
+
+        tls_mode = (
+            s3.S3RequestTlsMode.DISABLED
+            if config.disable_tls
+            else s3.S3RequestTlsMode.ENABLED
+        )
+        logger.info("Initializing S3 client for S3L2Adapter")
+        self._s3_client = s3.S3Client(
+            bootstrap=client_bootstrap,
+            region=self._region,
+            enable_s3express=self._enable_s3express,
+            tls_connection_options=tls_opts,
+            tls_mode=tls_mode,
+            signing_config=signing_config,
+        )
+
+        # 3 distinct cross-platform notifiers for the L2 interface.
+        self._store_efd = create_event_notifier()
+        self._lookup_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        self._next_task_id: L2TaskId = 0
+        self._completed_store_tasks: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_lookup_tasks: dict[L2TaskId, Bitmap] = {}
+        self._completed_load_tasks: dict[L2TaskId, Bitmap] = {}
+
+        # Refcounted locks (like NativeConnectorL2Adapter).
+        self._locked_keys: dict[ObjectKey, int] = defaultdict(int)
+
+        # Per-key size map — retained so ``delete`` can recover each
+        # key's stored size and pass it to ``_notify_keys_deleted``.
+        # Aggregate byte accounting lives in the base class via
+        # ``_notify_keys_stored``/``_notify_keys_deleted``; we do not
+        # maintain a parallel total here.
+        self._key_sizes: dict[ObjectKey, int] = {}
+
+        # Cached HEAD-verified object sizes (keyed by S3 object name).
+        self._object_size_cache: dict[str, int] = {}
+
+        # Circuit breaker state.
+        self._connection_failures = 0
+        self._connection_disabled = False
+
+        self._lock = threading.Lock()
+
+        # Background asyncio event loop.
+        self._loop = asyncio.new_event_loop()
+        self._loop_thread = threading.Thread(
+            target=self._run_event_loop,
+            daemon=True,
+            name="s3-l2-adapter-loop",
+        )
+        self._loop_thread.start()
+
+        self._closed = False
+
+        logger.info(
+            "Initialized S3L2Adapter (endpoint=%s region=%s "
+            "http2=%s s3express=%s tls=%s max_capacity_gb=%.2f)",
+            self._endpoint,
+            self._region,
+            config.s3_prefer_http2,
+            self._enable_s3express,
+            not config.disable_tls,
+            config.max_capacity_gb,
+        )
+
+    # ------------------------------------------------------------------
+    # Event Fd Interface
+    # ------------------------------------------------------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return self._lookup_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    # ------------------------------------------------------------------
+    # Store Interface
+    # ------------------------------------------------------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._next_task_id
+            self._next_task_id += 1
+            if self._connection_disabled:
+                self._completed_store_tasks[task_id] = L2StoreResult(False, 0)
+                disabled = True
+            else:
+                disabled = False
+
+        if disabled:
+            self._store_efd.notify()
+            return task_id
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_store(list(keys), list(objects), task_id),
+            self._loop,
+        )
+        return task_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        with self._lock:
+            completed = self._completed_store_tasks
+            self._completed_store_tasks = {}
+        return completed
+
+    # ------------------------------------------------------------------
+    # Lookup and Lock Interface
+    # ------------------------------------------------------------------
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._next_task_id
+            self._next_task_id += 1
+            if self._connection_disabled:
+                self._completed_lookup_tasks[task_id] = Bitmap(len(keys))
+                disabled = True
+            else:
+                disabled = False
+
+        if disabled:
+            self._lookup_efd.notify()
+            return task_id
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_lookup(list(keys), task_id),
+            self._loop,
+        )
+        return task_id
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Optional[Bitmap]:
+        with self._lock:
+            return self._completed_lookup_tasks.pop(task_id, None)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        with self._lock:
+            for key in keys:
+                if key not in self._locked_keys:
+                    continue
+                if self._locked_keys[key] <= 1:
+                    del self._locked_keys[key]
+                else:
+                    self._locked_keys[key] -= 1
+
+    # ------------------------------------------------------------------
+    # Load Interface
+    # ------------------------------------------------------------------
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        with self._lock:
+            task_id = self._next_task_id
+            self._next_task_id += 1
+            if self._connection_disabled:
+                self._completed_load_tasks[task_id] = Bitmap(len(keys))
+                disabled = True
+            else:
+                disabled = False
+
+        if disabled:
+            self._load_efd.notify()
+            return task_id
+
+        asyncio.run_coroutine_threadsafe(
+            self._execute_load(list(keys), list(objects), task_id),
+            self._loop,
+        )
+        return task_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Optional[Bitmap]:
+        with self._lock:
+            return self._completed_load_tasks.pop(task_id, None)
+
+    # ------------------------------------------------------------------
+    # Eviction Interface
+    # ------------------------------------------------------------------
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        if not keys:
+            return
+
+        # Filter out locked keys — they're being read right now.
+        with self._lock:
+            if self._connection_disabled:
+                return
+            deletable = [k for k in keys if self._locked_keys.get(k, 0) == 0]
+
+        if not deletable:
+            return
+
+        fut = asyncio.run_coroutine_threadsafe(
+            self._execute_delete(deletable),
+            self._loop,
+        )
+        try:
+            deleted_keys, deleted_sizes = fut.result(timeout=30.0)
+        except Exception as e:
+            logger.warning("S3L2Adapter delete failed: %s", e)
+            return
+
+        if deleted_keys:
+            self._notify_keys_deleted(deleted_keys, deleted_sizes)
+
+    # ``get_usage()`` is inherited from ``L2AdapterInterface``. The base
+    # class maintains the aggregate and per-``cache_salt`` byte totals
+    # via ``_notify_keys_stored`` / ``_notify_keys_deleted`` and returns
+    # an ``AdapterUsage`` snapshot with ``usage_fraction == -1.0`` when
+    # ``max_capacity_gb`` was 0 (unlimited / no eviction signal).
+
+    # ------------------------------------------------------------------
+    # Listing
+    # ------------------------------------------------------------------
+
+    def list_l2_keys(
+        self,
+        model_name: Optional[str] = None,
+        page_size: int = 500,
+        cursor: Optional[str] = None,
+    ) -> KeyListPage:
+        """List keys from the S3 bucket via ``ListObjectsV2``.
+
+        Args:
+            model_name: if set, restrict listing to objects whose name
+                starts with ``<model_name>@``.
+            page_size: target entries per page. Clamped to S3's
+                ``MaxKeys=1000`` ceiling.
+            cursor: opaque continuation token from the previous page.
+
+        Raises:
+            ValueError: ``page_size`` non-positive, malformed
+                ``cursor``, or malformed S3 response.
+            RuntimeError: connection is circuit-broken, or the
+                underlying CRT request errored out.
+        """
+        if page_size <= 0:
+            raise ValueError(f"page_size must be positive (got {page_size})")
+        # ListObjectsV2's ``MaxKeys`` is capped at 1000 by S3. The
+        # adapter clamps so callers asking for more just get the S3
+        # max plus a continuation token — they don't need to know
+        # about the server-side limit.
+        max_keys = min(page_size, 1000)
+        # ``model_name`` rides along as a ``prefix=`` query param so S3
+        # skips non-matching keys server-side. Keys are stored under
+        # their literal name (no path-flattening), so the prefix is
+        # just ``<model_name>@``.
+        prefix: Optional[str] = None
+        if model_name is not None:
+            prefix = f"{model_name}@"
+
+        with self._lock:
+            if self._connection_disabled:
+                raise RuntimeError(
+                    "S3 connection disabled (circuit-broken); listing unavailable"
+                )
+
+        fut = asyncio.run_coroutine_threadsafe(
+            self._execute_list(prefix, max_keys, cursor),
+            self._loop,
+        )
+        entries, next_token = fut.result(timeout=30.0)
+        page_entries = tuple(
+            KeyEntry(key=k.to_encoded_object_key(), size_bytes=sz) for k, sz in entries
+        )
+        return KeyListPage(entries=page_entries, next_page_token=next_token)
+
+    # ------------------------------------------------------------------
+    # Status / Cleanup
+    # ------------------------------------------------------------------
+
+    def report_status(self) -> dict:
+        with self._lock:
+            failures = self._connection_failures
+            disabled = self._connection_disabled
+        usage = self.get_usage()
+        return {
+            "is_healthy": self._loop_thread.is_alive() and not disabled,
+            "type": "S3L2Adapter",
+            "endpoint": self._endpoint,
+            "region": self._region,
+            "connection_failures": failures,
+            "connection_disabled": disabled,
+            "current_size_bytes": usage.total_bytes_used,
+            "max_capacity_bytes": usage.total_capacity_bytes,
+        }
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+
+        async def _stop_tasks():
+            tasks = [
+                t
+                for t in asyncio.all_tasks(self._loop)
+                if t is not asyncio.current_task()
+            ]
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+        if self._loop.is_running():
+            try:
+                asyncio.run_coroutine_threadsafe(_stop_tasks(), self._loop).result(
+                    timeout=5
+                )
+            except Exception:
+                pass
+            self._loop.call_soon_threadsafe(self._loop.stop)
+
+        self._loop_thread.join(timeout=5)
+        try:
+            self._loop.close()
+        except Exception:
+            pass
+
+        self._store_efd.close()
+        self._lookup_efd.close()
+        self._load_efd.close()
+
+        # Drop awscrt references so their native event loops / host
+        # resolver threads / epoll fds can be reaped immediately rather
+        # than surviving until this adapter is garbage-collected. Without
+        # this, spinning up many adapters in a process (e.g. a test
+        # module with per-test fixtures) can pile up FDs and exhaust
+        # ``ulimit -n`` on CI runners.
+        self._s3_client = None
+        self._credentials_provider = None
+        logger.info("S3L2Adapter closed")
+
+    # ------------------------------------------------------------------
+    # Internal: event loop & S3 request helpers
+    # ------------------------------------------------------------------
+
+    def _run_event_loop(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _make_request(
+        self, method: str, key_str: str, *, body_stream=None, extra_headers=None
+    ):
+        headers = HttpHeaders()
+        headers.add("Host", self._endpoint)
+        if extra_headers:
+            for k, v in extra_headers:
+                headers.add(k, v)
+        return HttpRequest(
+            method,
+            _format_safe_path(key_str),
+            headers,
+            body_stream=body_stream,
+        )
+
+    def _head_request(self, key_str: str):
+        req = self._make_request("HEAD", key_str)
+        captured = {"len": None, "status": None}
+
+        def on_headers(status_code, headers, **kwargs):
+            captured["status"] = status_code
+            for name, value in headers:
+                if name.lower() == "content-length":
+                    try:
+                        captured["len"] = int(value)
+                    except Exception:
+                        pass
+
+        s3_req = s3.S3Request(
+            client=self._s3_client,
+            type=s3.S3RequestType.DEFAULT,
+            request=req,
+            operation_name="HeadObject",
+            on_headers=on_headers,
+            credential_provider=self._credentials_provider,
+            region=self._region,
+        )
+        return s3_req, captured
+
+    def _get_request(self, key_str: str, mem_obj: MemoryObj):
+        req = self._make_request("GET", key_str)
+        data_ptr = mem_obj.data_ptr
+
+        def on_body(chunk, offset, **kwargs):
+            # Write chunk into the caller-provided MemoryObj buffer.
+            ctypes.memmove(data_ptr + offset, chunk, len(chunk))
+
+        def on_done(error=None, status_code=None, **kwargs):
+            ok = (status_code in (200, 206)) or (status_code is None and error is None)
+            if error or not ok:
+                raise RuntimeError(
+                    f"S3 GET failed for {key_str}: {error or status_code}"
+                )
+
+        s3_req = s3.S3Request(
+            client=self._s3_client,
+            type=s3.S3RequestType.GET_OBJECT,
+            request=req,
+            on_body=on_body,
+            on_done=on_done,
+            credential_provider=self._credentials_provider,
+            region=self._region,
+        )
+        return s3_req
+
+    def _put_request(self, key_str: str, mem_obj: MemoryObj):
+        stream = MemoryViewStream(mem_obj.byte_array)
+        total_len = len(stream)
+        req = self._make_request(
+            "PUT",
+            key_str,
+            body_stream=stream,
+            extra_headers=[
+                ("Content-Length", str(total_len)),
+                ("Content-Type", "application/octet-stream"),
+            ],
+        )
+        captured = {"status": None}
+
+        def on_done(error=None, status_code=None, **kwargs):
+            captured["status"] = status_code
+            if error or status_code not in (200, 201):
+                raise RuntimeError(
+                    f"S3 PUT failed for {key_str}: {error or status_code}"
+                )
+
+        s3_req = s3.S3Request(
+            client=self._s3_client,
+            type=s3.S3RequestType.PUT_OBJECT,
+            request=req,
+            on_done=on_done,
+            credential_provider=self._credentials_provider,
+            region=self._region,
+        )
+        return s3_req
+
+    def _delete_request(self, key_str: str):
+        req = self._make_request("DELETE", key_str)
+        captured = {"status": None}
+
+        def on_headers(status_code, headers, **kwargs):
+            captured["status"] = status_code
+
+        def on_done(error=None, status_code=None, **kwargs):
+            captured["status"] = status_code or captured["status"]
+            # 204 is standard for DeleteObject, 200 also tolerated.
+            if error or captured["status"] not in (200, 204):
+                raise RuntimeError(
+                    f"S3 DELETE failed for {key_str}: {error or captured['status']}"
+                )
+
+        s3_req = s3.S3Request(
+            client=self._s3_client,
+            type=s3.S3RequestType.DEFAULT,
+            request=req,
+            operation_name="DeleteObject",
+            on_headers=on_headers,
+            on_done=on_done,
+            credential_provider=self._credentials_provider,
+            region=self._region,
+        )
+        return s3_req
+
+    def _list_request(
+        self,
+        prefix: Optional[str],
+        max_keys: int,
+        continuation_token: Optional[str],
+    ):
+        """Build a ListObjectsV2 request.
+
+        Returns ``(s3_req, body_chunks, captured)``. The caller awaits
+        ``s3_req.finished_future`` and assembles the XML from
+        ``body_chunks``.
+        """
+        params: list[tuple[str, str]] = [
+            ("list-type", "2"),
+            ("max-keys", str(max_keys)),
+        ]
+        if prefix:
+            params.append(("prefix", prefix))
+        if continuation_token:
+            params.append(("continuation-token", continuation_token))
+        # urlencode handles percent-escaping of values (continuation
+        # tokens are typically base64 with ``+``/``/``/``=`` chars).
+        path = "/?" + urlencode(params, quote_via=url_quote)
+
+        headers = HttpHeaders()
+        headers.add("Host", self._endpoint)
+        req = HttpRequest("GET", path, headers)
+
+        body_chunks: list[bytes] = []
+        captured: dict[str, Optional[int]] = {"status": None}
+
+        def on_body(chunk, offset, **kwargs):
+            body_chunks.append(bytes(chunk))
+
+        def on_headers(status_code, headers, **kwargs):
+            captured["status"] = status_code
+
+        def on_done(error=None, status_code=None, **kwargs):
+            captured["status"] = status_code or captured["status"]
+            if error or captured["status"] != 200:
+                raise RuntimeError(
+                    f"S3 ListObjectsV2 failed: {error or captured['status']}"
+                )
+
+        s3_req = s3.S3Request(
+            client=self._s3_client,
+            type=s3.S3RequestType.DEFAULT,
+            request=req,
+            operation_name="ListObjectsV2",
+            on_body=on_body,
+            on_headers=on_headers,
+            on_done=on_done,
+            credential_provider=self._credentials_provider,
+            region=self._region,
+        )
+        return s3_req, body_chunks, captured
+
+    def _record_connection_outcome(self, error_msg: Optional[str]) -> None:
+        """Update the circuit breaker under the lock."""
+        with self._lock:
+            if error_msg is None:
+                if self._connection_failures > 0:
+                    logger.info("S3L2Adapter connection recovered")
+                self._connection_failures = 0
+                return
+            if not _is_connection_error(error_msg):
+                return
+            self._connection_failures += 1
+            logger.error(
+                "S3L2Adapter connection error (%d/%d): %s",
+                self._connection_failures,
+                self.max_connection_failures,
+                error_msg,
+            )
+            if self._connection_failures >= self.max_connection_failures:
+                self._connection_disabled = True
+                logger.error(
+                    "S3L2Adapter disabled after %d consecutive connection failures",
+                    self.max_connection_failures,
+                )
+
+    # ------------------------------------------------------------------
+    # Internal: coroutines
+    # ------------------------------------------------------------------
+
+    async def _execute_store(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        futures: list[Optional[asyncio.Future]] = []
+        indexed: list[tuple[int, ObjectKey, MemoryObj, Optional[str]]] = []
+        for i, (key, obj) in enumerate(zip(keys, objects, strict=True)):
+            try:
+                key_str = _object_key_to_string(key)
+                s3_req = self._put_request(key_str, obj)
+                futures.append(asyncio.wrap_future(s3_req.finished_future))
+                indexed.append((i, key, obj, key_str))
+            except Exception:
+                logger.exception("S3L2Adapter failed to launch PUT")
+                indexed.append((i, key, obj, None))
+                futures.append(None)
+
+        # Await all non-None futures.
+        results: list = []
+        real_futures = [f for f in futures if f is not None]
+        real_results = await asyncio.gather(*real_futures, return_exceptions=True)
+        real_iter = iter(real_results)
+        for f in futures:
+            if f is None:
+                results.append(RuntimeError("failed to launch S3 PUT"))
+            else:
+                results.append(next(real_iter))
+
+        success = True
+        # Track net-new keys for accounting notification. Same chunk_hash
+        # re-stored is identical content (content-addressed), so skipping
+        # re-notify here prevents the base class from double-counting
+        # bytes for the same object.
+        newly_stored_keys: list[ObjectKey] = []
+        newly_stored_sizes: list[int] = []
+        last_error: Optional[str] = None
+        for indexed_entry, result in zip(indexed, results, strict=True):
+            i, key, obj, opt_key_str = indexed_entry
+            if isinstance(result, Exception):
+                success = False
+                last_error = str(result)
+                continue
+            # Use logical size (``get_size``) to match the number of
+            # bytes actually PUT to S3 via ``obj.byte_array`` — which
+            # excludes any alignment padding in the underlying buffer.
+            # ``get_physical_size`` would inflate ``total_bytes_used``
+            # relative to the on-wire payload and cause premature
+            # aggregate-watermark eviction. Matches the convention used
+            # by ``native_connector_l2_adapter`` and ``mock_l2_adapter``.
+            size = obj.get_size()
+            with self._lock:
+                is_new = key not in self._key_sizes
+                self._key_sizes[key] = size
+                if opt_key_str is not None:
+                    self._object_size_cache[opt_key_str] = size
+            if is_new:
+                newly_stored_keys.append(key)
+                newly_stored_sizes.append(size)
+
+        self._record_connection_outcome(last_error if not success else None)
+
+        bytes_transferred = sum(newly_stored_sizes)
+        with self._lock:
+            self._completed_store_tasks[task_id] = L2StoreResult(
+                success, bytes_transferred
+            )
+
+        if newly_stored_keys:
+            self._notify_keys_stored(newly_stored_keys, newly_stored_sizes)
+        self._store_efd.notify()
+
+    async def _execute_lookup(
+        self,
+        keys: list[ObjectKey],
+        task_id: L2TaskId,
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        futures: list = []
+        captured_list: list = []
+        key_strings: list[str] = []
+        cache_hits: list[Optional[int]] = []
+
+        with self._lock:
+            for key in keys:
+                key_str = _object_key_to_string(key)
+                key_strings.append(key_str)
+                cache_hits.append(self._object_size_cache.get(key_str))
+
+        for idx, (key_str, cached_size) in enumerate(
+            zip(key_strings, cache_hits, strict=True)
+        ):
+            if cached_size is not None:
+                futures.append(None)
+                captured_list.append({"status": 200, "len": cached_size})
+                continue
+            try:
+                s3_req, captured = self._head_request(key_str)
+                futures.append(asyncio.wrap_future(s3_req.finished_future))
+                captured_list.append(captured)
+            except Exception:
+                logger.exception("S3L2Adapter failed to launch HEAD")
+                futures.append(None)
+                captured_list.append({"status": None, "len": None})
+
+        real_futures = [f for f in futures if f is not None]
+        real_results = await asyncio.gather(*real_futures, return_exceptions=True)
+        real_iter = iter(real_results)
+        combined: list = []
+        for f in futures:
+            if f is None:
+                combined.append(None)  # cached or failed-to-launch
+            else:
+                combined.append(next(real_iter))
+
+        last_error: Optional[str] = None
+        any_success = False
+
+        for i, (key, key_str, captured, result) in enumerate(
+            zip(keys, key_strings, captured_list, combined, strict=True)
+        ):
+            status = captured.get("status")
+            length = captured.get("len")
+            if isinstance(result, Exception):
+                # Non-200 surfaces as finished_future exception.
+                # 404 is an expected not-found.
+                if status == 404:
+                    continue
+                last_error = str(result)
+                continue
+            # result is None (cached) or None (success returned by future).
+            if status == 200 and length is not None and length > 0:
+                bitmap.set(i)
+                any_success = True
+                with self._lock:
+                    self._object_size_cache[key_str] = length
+                    self._locked_keys[key] += 1
+
+        if any_success:
+            self._record_connection_outcome(None)
+        elif last_error is not None:
+            self._record_connection_outcome(last_error)
+
+        with self._lock:
+            self._completed_lookup_tasks[task_id] = bitmap
+        self._lookup_efd.notify()
+
+        accessed = [keys[i] for i in range(len(keys)) if bitmap.test(i)]
+        if accessed:
+            self._notify_keys_accessed(accessed)
+
+    async def _execute_load(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+        task_id: L2TaskId,
+    ) -> None:
+        bitmap = Bitmap(len(keys))
+        futures = []
+        launched_indices = []
+
+        for i, (key, obj) in enumerate(zip(keys, objects, strict=True)):
+            try:
+                key_str = _object_key_to_string(key)
+                s3_req = self._get_request(key_str, obj)
+                futures.append(asyncio.wrap_future(s3_req.finished_future))
+                launched_indices.append(i)
+            except Exception:
+                logger.exception("S3L2Adapter failed to launch GET")
+
+        results = await asyncio.gather(*futures, return_exceptions=True)
+        last_error: Optional[str] = None
+        any_success = False
+
+        for idx, result in zip(launched_indices, results, strict=True):
+            if isinstance(result, Exception):
+                last_error = str(result)
+                continue
+            bitmap.set(idx)
+            any_success = True
+
+        if any_success:
+            self._record_connection_outcome(None)
+        elif last_error is not None:
+            self._record_connection_outcome(last_error)
+
+        with self._lock:
+            self._completed_load_tasks[task_id] = bitmap
+        self._load_efd.notify()
+
+    async def _execute_list(
+        self,
+        prefix: Optional[str],
+        max_keys: int,
+        continuation_token: Optional[str],
+    ) -> tuple[list[tuple[ObjectKey, int]], Optional[str]]:
+        """Issue one ``ListObjectsV2`` call and parse the response."""
+        s3_req, body_chunks, _captured = self._list_request(
+            prefix, max_keys, continuation_token
+        )
+        await asyncio.wrap_future(s3_req.finished_future)
+        return _parse_list_response_xml(b"".join(body_chunks))
+
+    async def _execute_delete(
+        self, keys: list[ObjectKey]
+    ) -> tuple[list[ObjectKey], list[int]]:
+        """Run DELETE for each key and drop its size-tracking entry.
+
+        Returns parallel lists of successfully deleted keys and their
+        stored sizes, suitable for passing straight to
+        ``_notify_keys_deleted``. Keys whose size we never learned
+        (delete of an unknown key) are reported with size ``0`` so
+        listener fanout still fires while base-class byte accounting
+        stays balanced.
+        """
+        futures = []
+        indexed = []
+        for key in keys:
+            try:
+                key_str = _object_key_to_string(key)
+                s3_req = self._delete_request(key_str)
+                futures.append(asyncio.wrap_future(s3_req.finished_future))
+                indexed.append((key, key_str))
+            except Exception:
+                logger.exception("S3L2Adapter failed to launch DELETE")
+
+        results = await asyncio.gather(*futures, return_exceptions=True)
+        deleted_keys: list[ObjectKey] = []
+        deleted_sizes: list[int] = []
+        for (key, key_str), result in zip(indexed, results, strict=True):
+            if isinstance(result, Exception):
+                logger.warning("S3L2Adapter DELETE failed for %s: %s", key_str, result)
+                continue
+            with self._lock:
+                sz = self._key_sizes.pop(key, None)
+                self._object_size_cache.pop(key_str, None)
+            deleted_keys.append(key)
+            deleted_sizes.append(sz if sz is not None else 0)
+        return deleted_keys, deleted_sizes
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+
+register_l2_adapter_type("s3", S3L2AdapterConfig)
+
+
+def _create_s3_adapter(
+    config: L2AdapterConfigBase,
+    l1_memory_desc: "Optional[L1MemoryDesc]" = None,
+) -> L2AdapterInterface:
+    return S3L2Adapter(config)  # type: ignore[arg-type]
+
+
+register_l2_adapter_factory("s3", _create_s3_adapter)
diff --git a/lmcache/v1/distributed/l2_adapters/serde_wrapper.py b/lmcache/v1/distributed/l2_adapters/serde_wrapper.py
new file mode 100644
index 0000000..5ccd234
--- /dev/null
+++ b/lmcache/v1/distributed/l2_adapters/serde_wrapper.py
@@ -0,0 +1,654 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+SerdeL2AdapterWrapper: wraps an inner L2 adapter with a SerdeProcessor
+so controllers see a plain ``L2AdapterInterface`` while data is
+transparently serialized on store and deserialized on load.
+
+Threading: the wrapper owns an internal poll thread that reacts to
+inner-adapter and serde event notifiers and chains
+
+    store : caller → serialize → inner.store            → signal store_efd
+    load  : caller → inner.load → deserialize           → signal load_efd
+
+Lookup / unlock / delete / eviction pass straight through to the inner
+adapter (no serde transform involved).
+
+Temp buffer lifecycle: temp byte buffers come from the injected
+``L1Manager`` so the extra memory shows up in L1 accounting just like
+the non-serde path's temporary KV buffers. For a store, the temp holds
+serialized bytes; for a load, the temp catches the bytes L2 reads
+before deserialize copies them into the caller-provided KV buffer.
+
+Failure policy: all-or-nothing per submit. A partial temp-alloc
+failure fails the whole task (``success=False`` for store, all-zeros
+bitmap for load). This preserves the coarse-grained success semantic
+of ``L2AdapterInterface`` and means the caller's lock / lifecycle
+invariants don't need to change.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+import enum
+import select
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import KeyListPage, MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L2AdapterListener, L2StoreResult
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.base import (
+    AdapterUsage,
+    L2AdapterInterface,
+    L2TaskId,
+)
+from lmcache.v1.distributed.serde import (
+    SerdeProcessor,
+    SerdeTaskId,
+    make_temp_key,
+    serialized_layout_desc,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import consume_fd, create_event_notifier
+
+logger = init_logger(__name__)
+
+_POLL_TIMEOUT_MS = 500
+
+
+class _StorePhase(enum.Enum):
+    SERIALIZE = enum.auto()
+    INNER_STORE = enum.auto()
+
+
+@dataclass
+class _StoreTaskState:
+    wrapped_id: L2TaskId
+    keys: list[ObjectKey]
+    temp_keys: list[ObjectKey]
+    temp_objs: list[MemoryObj]
+    phase: _StorePhase
+    """SERIALIZE while temps are write-locked; INNER_STORE after the
+    serialize→store transition. Only read on shutdown to pick the right
+    lock-release path; assignment is done under ``self._lock``."""
+
+
+@dataclass
+class _LoadTaskState:
+    wrapped_id: L2TaskId
+    keys: list[ObjectKey]
+    dst_objs: list[MemoryObj]
+    temp_keys: list[ObjectKey]
+    temp_objs: list[MemoryObj]
+    load_bitmap: Bitmap = field(default_factory=lambda: Bitmap(0))
+    """Inner adapter's per-key load bitmap; populated in
+    ``_drain_inner_load`` before the task transitions to the deserialize
+    stage. ``Bitmap(0)`` means "not populated yet" — by the time
+    ``_drain_deserialize`` reads it, this placeholder has been
+    overwritten with the real bitmap."""
+
+
+class SerdeL2AdapterWrapper(L2AdapterInterface):
+    """L2 adapter that adds transparent serde on top of an inner adapter.
+
+    Args:
+        inner: The wrapped L2 adapter doing the actual storage.
+        serde: The SerdeProcessor used to (de)serialize KV data.
+        l1_manager: L1 manager used to allocate temp byte buffers.
+    """
+
+    def __init__(
+        self,
+        inner: L2AdapterInterface,
+        serde: SerdeProcessor,
+        l1_manager: L1Manager,
+    ) -> None:
+        super().__init__()
+        self._inner = inner
+        self._serde = serde
+        self._l1_manager = l1_manager
+
+        # Our own notifiers for store/load completion. Lookup passes the
+        # inner adapter's fd straight through (no chaining needed there).
+        self._store_efd = create_event_notifier()
+        self._load_efd = create_event_notifier()
+
+        # Task-id space separate from inner's. Reverse maps let the
+        # internal thread pair inner / serde completions back to our
+        # wrapped task id.
+        self._lock = threading.Lock()
+        self._next_task_id: L2TaskId = 0
+        self._store_tasks: dict[L2TaskId, _StoreTaskState] = {}
+        self._load_tasks: dict[L2TaskId, _LoadTaskState] = {}
+        self._serde_to_store: dict[SerdeTaskId, L2TaskId] = {}
+        self._inner_to_store: dict[L2TaskId, L2TaskId] = {}
+        self._inner_to_load: dict[L2TaskId, L2TaskId] = {}
+        self._serde_to_load: dict[SerdeTaskId, L2TaskId] = {}
+
+        # User-visible completion queues (drained by controller polls).
+        self._completed_store: dict[L2TaskId, L2StoreResult] = {}
+        self._completed_load: dict[L2TaskId, Bitmap] = {}
+
+        self._stop_flag = threading.Event()
+        self._thread = threading.Thread(
+            target=self._loop,
+            name="serde-l2-wrapper",
+            daemon=True,
+        )
+        self._thread.start()
+
+    # ------------------------------------------------------------------
+    # Event fds
+    # ------------------------------------------------------------------
+
+    def get_store_event_fd(self) -> int:
+        return self._store_efd.fileno()
+
+    def get_load_event_fd(self) -> int:
+        return self._load_efd.fileno()
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        # Lookup doesn't touch serde; passing through the inner adapter's
+        # fd avoids a useless thread-hop per lookup.
+        return self._inner.get_lookup_and_lock_event_fd()
+
+    # ------------------------------------------------------------------
+    # Store
+    # ------------------------------------------------------------------
+
+    def submit_store_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Submit a wrapped store (serialize → inner.store).
+
+        All-or-nothing: if temp alloc fails for any key or serialize
+        submission raises, the whole task is marked failed and the
+        caller's next ``pop_completed_store_tasks`` call sees it.
+        """
+        with self._lock:
+            wrapped_id = self._next_task_id
+            self._next_task_id += 1
+
+        temp_keys, temp_objs = self._alloc_temp_buffers(keys, objects)
+        if temp_objs is None:
+            logger.warning(
+                "Serde wrapper: temp alloc failed for store task %d",
+                wrapped_id,
+            )
+            self._finalize_store(wrapped_id, success=False)
+            return wrapped_id
+
+        # Hold the wrapper lock across submit + reverse-map registration
+        # so the internal drain thread cannot observe a half-state where
+        # the serde already signaled completion but ``_serde_to_store``
+        # has no entry — which would leave the wrapped task hanging.
+        state = _StoreTaskState(
+            wrapped_id=wrapped_id,
+            keys=list(keys),
+            temp_keys=temp_keys,
+            temp_objs=temp_objs,
+            phase=_StorePhase.SERIALIZE,
+        )
+        try:
+            with self._lock:
+                self._store_tasks[wrapped_id] = state
+                serde_task_id = self._serde.submit_serialize(objects, temp_objs)
+                self._serde_to_store[serde_task_id] = wrapped_id
+        except Exception:
+            logger.exception(
+                "Serde wrapper: submit_serialize raised for store task %d",
+                wrapped_id,
+            )
+            with self._lock:
+                self._store_tasks.pop(wrapped_id, None)
+            self._release_write_temps(temp_keys)
+            self._finalize_store(wrapped_id, success=False)
+            return wrapped_id
+        return wrapped_id
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        with self._lock:
+            result = self._completed_store
+            self._completed_store = {}
+        return result
+
+    # ------------------------------------------------------------------
+    # Lookup / unlock (pure delegation)
+    # ------------------------------------------------------------------
+
+    def submit_lookup_and_lock_task(
+        self, keys: list[ObjectKey], layout_desc: MemoryLayoutDesc
+    ) -> L2TaskId:
+        return self._inner.submit_lookup_and_lock_task(keys, layout_desc)
+
+    def query_lookup_and_lock_result(self, task_id: L2TaskId) -> Bitmap | None:
+        return self._inner.query_lookup_and_lock_result(task_id)
+
+    def submit_unlock(self, keys: list[ObjectKey]) -> None:
+        self._inner.submit_unlock(keys)
+
+    # ------------------------------------------------------------------
+    # Load
+    # ------------------------------------------------------------------
+
+    def submit_load_task(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> L2TaskId:
+        """Submit a wrapped load (inner.load → deserialize).
+
+        All-or-nothing: if temp alloc or inner submission fails, the
+        caller gets an all-zeros bitmap on next ``query_load_result``.
+        """
+        with self._lock:
+            wrapped_id = self._next_task_id
+            self._next_task_id += 1
+
+        temp_keys, temp_objs = self._alloc_temp_buffers(keys, objects)
+        if temp_objs is None:
+            logger.warning(
+                "Serde wrapper: temp alloc failed for load task %d",
+                wrapped_id,
+            )
+            self._finalize_load(wrapped_id, Bitmap(len(keys)))
+            return wrapped_id
+
+        # Hold the wrapper lock across submit + reverse-map registration
+        # so the internal drain thread cannot observe a half-state where
+        # the inner already signaled completion but ``_inner_to_load``
+        # has no entry.
+        state = _LoadTaskState(
+            wrapped_id=wrapped_id,
+            keys=list(keys),
+            dst_objs=list(objects),
+            temp_keys=temp_keys,
+            temp_objs=temp_objs,
+        )
+        try:
+            with self._lock:
+                self._load_tasks[wrapped_id] = state
+                inner_task_id = self._inner.submit_load_task(keys, temp_objs)
+                self._inner_to_load[inner_task_id] = wrapped_id
+        except Exception:
+            logger.exception(
+                "Serde wrapper: inner.submit_load_task raised for task %d",
+                wrapped_id,
+            )
+            with self._lock:
+                self._load_tasks.pop(wrapped_id, None)
+            self._release_write_temps(temp_keys)
+            self._finalize_load(wrapped_id, Bitmap(len(keys)))
+            return wrapped_id
+        return wrapped_id
+
+    def query_load_result(self, task_id: L2TaskId) -> Bitmap | None:
+        with self._lock:
+            return self._completed_load.pop(task_id, None)
+
+    # ------------------------------------------------------------------
+    # Eviction / metadata / listeners (delegate to inner)
+    # ------------------------------------------------------------------
+
+    @property
+    def inner_adapter(self) -> L2AdapterInterface:
+        """Return the wrapped L2 adapter."""
+        return self._inner
+
+    @property
+    def supports_global_eviction(self) -> bool:
+        return self._inner.supports_global_eviction
+
+    def get_usage(self) -> AdapterUsage:
+        return self._inner.get_usage()
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        self._inner.delete(keys)
+
+    def list_l2_keys(
+        self,
+        model_name: str | None = None,
+        page_size: int = 500,
+        cursor: str | None = None,
+    ) -> KeyListPage:
+        return self._inner.list_l2_keys(
+            model_name=model_name,
+            page_size=page_size,
+            cursor=cursor,
+        )
+
+    def register_listener(self, listener: L2AdapterListener) -> None:
+        # Listeners track what's actually stored — which is inner's job.
+        self._inner.register_listener(listener)
+
+    def report_status(self) -> dict:
+        inner_status = self._inner.report_status()
+        return {**inner_status, "serde_wrapped": True}
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        self._stop_flag.set()
+        self._thread.join()
+
+        # Shut down the inner adapter and serde processor BEFORE
+        # releasing temp buffers. Both ``close()`` calls block until
+        # their in-flight reads / writes against the temp MemoryObjs
+        # finish; releasing the temps first would let L1 reclaim memory
+        # that the inner adapter or serde thread pool is still touching
+        # (use-after-free).
+        self._inner.close()
+        self._serde.close()
+
+        # Now safe to release leftover temp buffers. Store tasks in
+        # SERIALIZE phase hold write locks on their temps; tasks in
+        # INNER_STORE phase hold read locks (transitioned after
+        # serialize). Load tasks always hold write locks.
+        with self._lock:
+            write_locked: list[ObjectKey] = []
+            read_locked: list[ObjectKey] = []
+            for s in self._store_tasks.values():
+                if s.phase is _StorePhase.SERIALIZE:
+                    write_locked.extend(s.temp_keys)
+                else:
+                    read_locked.extend(s.temp_keys)
+            for load in self._load_tasks.values():
+                write_locked.extend(load.temp_keys)
+            self._store_tasks.clear()
+            self._load_tasks.clear()
+            self._serde_to_store.clear()
+            self._inner_to_store.clear()
+            self._inner_to_load.clear()
+            self._serde_to_load.clear()
+
+        if write_locked:
+            try:
+                self._l1_manager.finish_write(write_locked)
+                self._l1_manager.delete(write_locked)
+            except Exception:
+                logger.exception(
+                    "Serde wrapper: error releasing write-locked leftover temps"
+                )
+        if read_locked:
+            try:
+                self._l1_manager.finish_read(read_locked)
+            except Exception:
+                logger.exception(
+                    "Serde wrapper: error releasing read-locked leftover temps"
+                )
+
+        self._store_efd.close()
+        self._load_efd.close()
+
+    # ------------------------------------------------------------------
+    # Internal loop
+    # ------------------------------------------------------------------
+
+    def _loop(self) -> None:
+        poller = select.poll()
+        inner_store_efd = self._inner.get_store_event_fd()
+        inner_load_efd = self._inner.get_load_event_fd()
+        serialize_efd = self._serde.get_serialize_event_fd()
+        deserialize_efd = self._serde.get_deserialize_event_fd()
+
+        poller.register(inner_store_efd, select.POLLIN)
+        poller.register(inner_load_efd, select.POLLIN)
+        poller.register(serialize_efd, select.POLLIN)
+        poller.register(deserialize_efd, select.POLLIN)
+
+        while not self._stop_flag.is_set():
+            ready = poller.poll(_POLL_TIMEOUT_MS)
+            for fd, events in ready:
+                if not (events & select.POLLIN):
+                    continue
+                try:
+                    consume_fd(fd)
+                except OSError:
+                    pass
+                try:
+                    if fd == serialize_efd:
+                        self._drain_serialize()
+                    elif fd == inner_store_efd:
+                        self._drain_inner_store()
+                    elif fd == inner_load_efd:
+                        self._drain_inner_load()
+                    elif fd == deserialize_efd:
+                        self._drain_deserialize()
+                except Exception:
+                    logger.exception("Serde wrapper: internal loop error on fd %d", fd)
+
+    def _drain_serialize(self) -> None:
+        """Poll pending serialize tasks; on success submit inner store."""
+        with self._lock:
+            pending = list(self._serde_to_store.keys())
+        for serde_id in pending:
+            result = self._serde.query_serialize_result(serde_id)
+            if result is None:
+                continue
+            with self._lock:
+                wrapped_id = self._serde_to_store.pop(serde_id, None)
+                state = (
+                    self._store_tasks.get(wrapped_id)
+                    if wrapped_id is not None
+                    else None
+                )
+            if wrapped_id is None or state is None:
+                continue
+
+            if not result:
+                self._release_write_temps(state.temp_keys)
+                self._finalize_store(wrapped_id, success=False)
+                continue
+
+            # Serialize succeeded — transition temps write → read so inner
+            # can safely read them during the store.
+            self._l1_manager.finish_write_and_reserve_read(state.temp_keys)
+            try:
+                inner_id = self._inner.submit_store_task(state.keys, state.temp_objs)
+            except Exception:
+                logger.exception(
+                    "Serde wrapper: inner.submit_store_task raised for task %d",
+                    wrapped_id,
+                )
+                # Temps are now read-locked and temporary — finish_read
+                # is enough; the entries auto-delete.
+                self._l1_manager.finish_read(state.temp_keys)
+                self._finalize_store(wrapped_id, success=False)
+                continue
+
+            # Phase flip and reverse-map insert happen under the same
+            # lock so ``close()``'s cleanup can't observe a half-way
+            # transition.
+            with self._lock:
+                state.phase = _StorePhase.INNER_STORE
+                self._inner_to_store[inner_id] = wrapped_id
+
+    def _drain_inner_store(self) -> None:
+        """Drain inner store completions; release temp read locks (auto-
+        delete) and finalize the wrapped tasks."""
+        completed = self._inner.pop_completed_store_tasks()
+        for inner_id, result in completed.items():
+            with self._lock:
+                wrapped_id = self._inner_to_store.pop(inner_id, None)
+                state = (
+                    self._store_tasks.get(wrapped_id)
+                    if wrapped_id is not None
+                    else None
+                )
+            if wrapped_id is None:
+                logger.warning(
+                    "Serde wrapper: inner store task %d has no wrapped id",
+                    inner_id,
+                )
+                continue
+            if state is not None:
+                self._l1_manager.finish_read(state.temp_keys)
+            self._finalize_store(
+                wrapped_id, result.is_successful(), result.bytes_transferred()
+            )
+
+    def _drain_inner_load(self) -> None:
+        """Drain inner load completions; on per-key success submit
+        deserialize, otherwise fail the keys immediately."""
+        with self._lock:
+            pending = list(self._inner_to_load.keys())
+        for inner_id in pending:
+            bitmap = self._inner.query_load_result(inner_id)
+            if bitmap is None:
+                continue
+            with self._lock:
+                wrapped_id = self._inner_to_load.pop(inner_id, None)
+                state = (
+                    self._load_tasks.get(wrapped_id) if wrapped_id is not None else None
+                )
+            if wrapped_id is None or state is None:
+                continue
+
+            src_objs: list[MemoryObj] = []
+            dst_objs: list[MemoryObj] = []
+            for i in range(len(state.keys)):
+                if bitmap.test(i):
+                    src_objs.append(state.temp_objs[i])
+                    dst_objs.append(state.dst_objs[i])
+
+            if not src_objs:
+                # Inner loaded nothing — skip deserialize, finalize.
+                self._release_write_temps(state.temp_keys)
+                self._finalize_load(wrapped_id, bitmap)
+                continue
+
+            state.load_bitmap = bitmap
+            try:
+                serde_id = self._serde.submit_deserialize(src_objs, dst_objs)
+            except Exception:
+                logger.exception(
+                    "Serde wrapper: submit_deserialize raised for task %d",
+                    wrapped_id,
+                )
+                self._release_write_temps(state.temp_keys)
+                self._finalize_load(wrapped_id, Bitmap(len(state.keys)))
+                continue
+            with self._lock:
+                self._serde_to_load[serde_id] = wrapped_id
+
+    def _drain_deserialize(self) -> None:
+        """Drain deserialize completions; report inner's load bitmap on
+        success, all-zeros on deserialize failure."""
+        with self._lock:
+            pending = list(self._serde_to_load.keys())
+        for serde_id in pending:
+            result = self._serde.query_deserialize_result(serde_id)
+            if result is None:
+                continue
+            with self._lock:
+                wrapped_id = self._serde_to_load.pop(serde_id, None)
+                state = (
+                    self._load_tasks.get(wrapped_id) if wrapped_id is not None else None
+                )
+            if wrapped_id is None or state is None:
+                continue
+
+            if result:
+                # ``load_bitmap`` was populated by _drain_inner_load before
+                # the task was registered in ``_serde_to_load``.
+                final_bitmap = state.load_bitmap
+            else:
+                logger.warning(
+                    "Serde wrapper: deserialize failed for task %d; "
+                    "reporting all keys as failed",
+                    wrapped_id,
+                )
+                final_bitmap = Bitmap(len(state.keys))
+
+            self._release_write_temps(state.temp_keys)
+            self._finalize_load(wrapped_id, final_bitmap)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _alloc_temp_buffers(
+        self,
+        keys: list[ObjectKey],
+        objects: list[MemoryObj],
+    ) -> tuple[list[ObjectKey], list[MemoryObj] | None]:
+        """Reserve one temp byte buffer per input key. All-or-nothing:
+        any single failure releases the partial successes and returns
+        ``(temp_keys, None)``.
+
+        Args:
+            keys: Original logical keys; used only to derive temp keys.
+            objects: Source (store) or destination (load) MemoryObjs.
+                All entries must share a single ``(shape, dtype)`` — the
+                caller (store/prefetch controller) is responsible for
+                shape-grouping before submission.
+        """
+        shape_0 = objects[0].get_shapes()
+        dtype_0 = objects[0].get_dtypes()
+        temp_keys = [make_temp_key(k) for k in keys]
+        layout = serialized_layout_desc(
+            MemoryLayoutDesc(shapes=shape_0, dtypes=dtype_0), self._serde
+        )
+        results = self._l1_manager.reserve_write(
+            keys=temp_keys,
+            is_temporary=[True] * len(temp_keys),
+            layout_desc=layout,
+            mode="new",
+        )
+        # First pass: collect every key whose reserve_write succeeded.
+        # We must scan the full list (not bail on the first failure)
+        # so a mixed-success result still releases all reserved keys.
+        successful_temp_keys: list[ObjectKey] = []
+        for temp_key in temp_keys:
+            r = results.get(temp_key)
+            if r is not None and r[0] == L1Error.SUCCESS:
+                successful_temp_keys.append(temp_key)
+        if len(successful_temp_keys) != len(temp_keys):
+            self._release_write_temps(successful_temp_keys)
+            return temp_keys, None
+        temp_objs = [results[tk][1] for tk in temp_keys]
+        return temp_keys, temp_objs
+
+    def _release_write_temps(self, temp_keys: list[ObjectKey]) -> None:
+        """Release write-locked temps and delete them. No-op on empty."""
+        if not temp_keys:
+            return
+        try:
+            self._l1_manager.finish_write(temp_keys)
+            self._l1_manager.delete(temp_keys)
+        except Exception:
+            logger.exception("Serde wrapper: failed releasing write-locked temps")
+
+    def _finalize_store(
+        self,
+        wrapped_id: L2TaskId,
+        success: bool,
+        bytes_transferred: int = 0,
+    ) -> None:
+        with self._lock:
+            self._store_tasks.pop(wrapped_id, None)
+            self._completed_store[wrapped_id] = L2StoreResult(
+                success, bytes_transferred
+            )
+        try:
+            self._store_efd.notify()
+        except OSError:
+            logger.exception("Serde wrapper: failed to signal store notifier")
+
+    def _finalize_load(self, wrapped_id: L2TaskId, bitmap: Bitmap) -> None:
+        with self._lock:
+            self._load_tasks.pop(wrapped_id, None)
+            self._completed_load[wrapped_id] = bitmap
+        try:
+            self._load_efd.notify()
+        except OSError:
+            logger.exception("Serde wrapper: failed to signal load notifier")
diff --git a/lmcache/v1/distributed/memory_manager/__init__.py b/lmcache/v1/distributed/memory_manager/__init__.py
new file mode 100644
index 0000000..1621d26
--- /dev/null
+++ b/lmcache/v1/distributed/memory_manager/__init__.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+"""L1 memory managers for the distributed cache.
+
+Two interchangeable tiers behind :class:`L1ManagerProtocol`:
+
+- :class:`L1MemoryManager` -- CPU pinned-DRAM slab.
+- :class:`DevDaxL1MemoryManager` -- Device-DAX-backed L1 slab.
+- :class:`GDSL1MemoryManager` -- GDS slab file (cuFile DMA).
+"""
+
+# First Party
+from lmcache.v1.distributed.memory_manager.devdax_l1_memory_manager import (
+    DevDaxL1MemoryManager,
+)
+from lmcache.v1.distributed.memory_manager.gds_l1_memory_manager import (
+    GDSL1MemoryManager,
+)
+from lmcache.v1.distributed.memory_manager.l1_manager_protocol import L1ManagerProtocol
+from lmcache.v1.distributed.memory_manager.l1_memory_manager import (
+    L1MemoryManager,
+    create_memory_allocator,
+)
+
+__all__ = [
+    "DevDaxL1MemoryManager",
+    "GDSL1MemoryManager",
+    "L1ManagerProtocol",
+    "L1MemoryManager",
+    "create_memory_allocator",
+]
diff --git a/lmcache/v1/distributed/memory_manager/devdax_l1_memory_manager.py b/lmcache/v1/distributed/memory_manager/devdax_l1_memory_manager.py
new file mode 100644
index 0000000..bf2ab97
--- /dev/null
+++ b/lmcache/v1/distributed/memory_manager/devdax_l1_memory_manager.py
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Device-DAX L1 memory manager."""
+
+# Standard
+from typing import cast
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.config import L1MemoryManagerConfig
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.memory_manager.l1_memory_manager import L1MemoryManager
+from lmcache.v1.memory_allocators.devdax_memory_allocator import DevDaxMemoryAllocator
+
+logger = init_logger(__name__)
+
+
+class DevDaxL1MemoryManager(L1MemoryManager):
+    """L1 memory manager for Device-DAX-backed L1 memory.
+
+    This is a peer of
+    :class:`~lmcache.v1.distributed.memory_manager.l1_memory_manager.L1MemoryManager`
+    and owns the Device-DAX allocator path that used to live inside the generic
+    CPU L1 manager. A pure Device-DAX configuration maps the DAX device as the
+    full L1 arena. A hybrid configuration uses DRAM first and spills overflow
+    allocations into Device-DAX.
+    """
+
+    def __init__(self, config: L1MemoryManagerConfig) -> None:
+        """Create a Device-DAX L1 memory manager.
+
+        Args:
+            config: L1 memory configuration with ``devdax_path`` set.
+
+        Raises:
+            ValueError: If ``devdax_path`` is not configured.
+        """
+        if not config.devdax_path:
+            raise ValueError("DevDaxL1MemoryManager requires devdax_path")
+
+        devdax_size = config.devdax_size_in_bytes or config.size_in_bytes
+        local_size = config.size_in_bytes if config.devdax_size_in_bytes else 0
+        logger.debug(
+            "use devdax memory allocator, dram size is %d bytes, "
+            "devdax path is %s, devdax size is %d bytes, align bytes is %d bytes",
+            local_size,
+            config.devdax_path,
+            devdax_size,
+            config.align_bytes,
+        )
+        self._allocator = DevDaxMemoryAllocator(
+            devdax_size,
+            config.devdax_path,
+            local_size=local_size,
+            shm_name=config.shm_name or None,
+            align_bytes=config.align_bytes,
+        )
+        self._size_in_bytes = config.size_in_bytes
+        self._align_bytes = config.align_bytes
+
+    def get_l1_memory_desc(self) -> L1MemoryDesc:
+        """Return a descriptor for the primary L1 buffer.
+
+        Existing callers expect Device-DAX L1 to expose the mapped buffer here.
+        Hybrid DRAM + Device-DAX L1 is still rejected by transfer paths that
+        require one registerable L1 region via ``l1_exposes_single_memory_region``.
+
+        Returns:
+            The descriptor for the primary L1 buffer.
+        """
+        allocator = cast(DevDaxMemoryAllocator, self._allocator)
+        buffer = allocator.buffer
+        return L1MemoryDesc(
+            ptr=buffer.data_ptr(),
+            size=self._size_in_bytes,
+            align_bytes=self._align_bytes,
+        )
diff --git a/lmcache/v1/distributed/memory_manager/gds_l1_memory_manager.py b/lmcache/v1/distributed/memory_manager/gds_l1_memory_manager.py
new file mode 100644
index 0000000..e1275f3
--- /dev/null
+++ b/lmcache/v1/distributed/memory_manager/gds_l1_memory_manager.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: Apache-2.0
+"""GDS slab-file L1 memory manager."""
+
+# Standard
+from typing import Optional
+
+# First Party
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.config import GdsL1Config
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.memory_management import (
+    AddressManager,
+    GDSMemoryObject,
+    MemoryObj,
+    MemoryObjMetadata,
+)
+
+logger = init_logger(__name__)
+
+
+class GDSL1MemoryManager:
+    """L1 memory manager for the GDS slab-file tier.
+
+    A peer of
+    :class:`~lmcache.v1.distributed.memory_manager.l1_memory_manager.L1MemoryManager`
+    (both satisfy
+    :class:`~lmcache.v1.distributed.memory_manager.l1_manager_protocol.L1ManagerProtocol`).
+    It owns an :class:`AddressManager` over the slab's byte-offset space and
+    hands out :class:`GDSMemoryObject` chunks; the actual GPU<->slab DMA is
+    performed by the global
+    :class:`~lmcache.v1.gpu_connector.gds_context.GDSContext`, reached from the
+    ``gpu_ops`` dispatch.
+
+    There is no on-disk index: the slab is created and cleared at startup
+    (treated like DRAM), so allocations do not survive a restart.
+    """
+
+    def __init__(self, config: GdsL1Config) -> None:
+        """Create the manager.
+
+        Args:
+            config: The GDS tier config. ``size_in_bytes`` sizes the slab
+                address space, and ``align_bytes`` sets the allocation alignment
+                (cuFile/O_DIRECT require 4 KiB). The same ``GdsL1Config`` drives
+                the :class:`GDSContext` that preallocates the slab file, so the
+                address space and the file match by construction. The CPU-tier
+                ``memory_config`` is not referenced on the GDS path.
+        """
+        self._address_manager = AddressManager(config.size_in_bytes, config.align_bytes)
+
+    def allocate(
+        self, layout_desc: MemoryLayoutDesc, count: int
+    ) -> tuple[L1Error, list[MemoryObj]]:
+        """Reserve ``count`` slab regions for the given layout.
+
+        All-or-nothing: on the first slab OOM, frees what was reserved and
+        returns ``(L1Error.OUT_OF_MEMORY, [])``.
+
+        Args:
+            layout_desc: Layout descriptor; all ``count`` chunks share its
+                shape/dtype, and its byte size sets each chunk's size.
+            count: Number of chunks to reserve.
+
+        Returns:
+            ``(L1Error.SUCCESS, objects)`` on success, otherwise
+            ``(L1Error.OUT_OF_MEMORY, [])``.
+        """
+        chunk_bytes = get_size_bytes(layout_desc.shapes, layout_desc.dtypes)
+        shape = layout_desc.shapes[0]
+        dtype = layout_desc.dtypes[0]
+        objects: list[MemoryObj] = []
+        for _ in range(count):
+            try:
+                address, allocated = self._address_manager.allocate(chunk_bytes)
+            except RuntimeError:
+                for obj in objects:
+                    self._address_manager.free(
+                        obj.metadata.address, obj.get_physical_size()
+                    )
+                return L1Error.OUT_OF_MEMORY, []
+            meta = MemoryObjMetadata(
+                shape=shape,
+                dtype=dtype,
+                address=address,
+                phy_size=allocated,
+                ref_count=0,
+            )
+            objects.append(GDSMemoryObject(meta))
+        return L1Error.SUCCESS, objects
+
+    def free(self, mem_objs: list[MemoryObj]) -> L1Error:
+        """Return the slab regions of the given objects to the address manager.
+
+        Args:
+            mem_objs: Objects to free (slab-anchored :class:`GDSMemoryObject`s
+                handed out by :meth:`allocate`).
+
+        Returns:
+            ``L1Error.SUCCESS``.
+        """
+        for mo in mem_objs:
+            self._address_manager.free(mo.metadata.address, mo.get_physical_size())
+        return L1Error.SUCCESS
+
+    def get_memory_usage(self) -> tuple[int, int]:
+        """Return ``(used_bytes, total_bytes)`` of the slab."""
+        free_size = self._address_manager.get_free_size()
+        total_size = self._address_manager.get_heap_size()
+        return total_size - free_size, total_size
+
+    def get_l1_memory_desc(self) -> Optional[L1MemoryDesc]:
+        """Return ``None``: the GDS L1 medium is the slab file, not a buffer.
+
+        The only registerable memory on the GDS path is the GPU staging buffer,
+        not an L1 pool, so there is no descriptor to hand to L2 adapters (which
+        must be disabled when GDS L1 is enabled).
+        """
+        return None
+
+    def close(self) -> None:
+        """No-op: the GDSContext owning the slab is closed at server shutdown."""
+        return
+
+    def memcheck(self) -> bool:
+        """For debug purposes; logs allocator state and checks consistency.
+
+        Mirrors ``TensorMemoryAllocator.memcheck`` for the GDS slab address
+        space: logs the allocated / free sizes, then verifies the free and
+        allocated bytes add up to the slab size and that free blocks are
+        coalesced. Returns ``True`` when consistent, ``False`` otherwise.
+        """
+        clear = True
+        logger.info("Checking memory allocator consistency")
+        logger.info(
+            " - Total allocated size: %s MB",
+            self._address_manager.total_allocated_size / 1048576,
+        )
+
+        total_free_size = self._address_manager.get_free_size()
+        logger.info(" - Total free size: %s MB", total_free_size / 1048576)
+
+        if (
+            total_free_size + self._address_manager.total_allocated_size
+            != self._address_manager.get_heap_size()
+        ):
+            logger.error("Memory allocator size is inconsistent")
+            logger.error("This implies a bug in the memory allocator")
+            clear = False
+
+        if not self._address_manager.check_consistency():
+            logger.error("Memory allocator has non-coalesced blocks")
+            logger.error("This implies a bug in the memory allocator")
+            clear = False
+
+        return clear
diff --git a/lmcache/v1/distributed/memory_manager/l1_manager_protocol.py b/lmcache/v1/distributed/memory_manager/l1_manager_protocol.py
new file mode 100644
index 0000000..d456005
--- /dev/null
+++ b/lmcache/v1/distributed/memory_manager/l1_manager_protocol.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Structural interface shared by the L1 memory manager tiers."""
+
+# Standard
+from typing import Optional, Protocol, runtime_checkable
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.memory_management import MemoryObj
+
+
+@runtime_checkable
+class L1ManagerProtocol(Protocol):
+    """Structural interface for an L1 memory manager.
+
+    Both :class:`L1MemoryManager` (CPU pinned-DRAM tier) and
+    :class:`GDSL1MemoryManager` (GDS slab-file tier) satisfy this protocol, so
+    ``L1Manager`` can hold either behind one type.
+    """
+
+    def allocate(
+        self, layout_desc: MemoryLayoutDesc, count: int
+    ) -> tuple[L1Error, list[MemoryObj]]:
+        """Allocate ``count`` memory objects for the given layout."""
+        ...
+
+    def free(self, mem_objs: list[MemoryObj]) -> L1Error:
+        """Free the given memory objects."""
+        ...
+
+    def get_memory_usage(self) -> tuple[int, int]:
+        """Return ``(used_bytes, total_bytes)``."""
+        ...
+
+    def get_l1_memory_desc(self) -> Optional[L1MemoryDesc]:
+        """Describe the underlying L1 buffer for L2-adapter registration.
+
+        Returns ``None`` for tiers with no registerable L1 buffer (e.g. GDS).
+        """
+        ...
+
+    def close(self) -> None:
+        """Release all resources."""
+        ...
+
+    def memcheck(self) -> bool:
+        """Verify allocator bookkeeping consistency."""
+        ...
diff --git a/lmcache/v1/distributed/memory_manager/l1_memory_manager.py b/lmcache/v1/distributed/memory_manager/l1_memory_manager.py
new file mode 100644
index 0000000..9705fbe
--- /dev/null
+++ b/lmcache/v1/distributed/memory_manager/l1_memory_manager.py
@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CPU pinned-DRAM L1 memory manager."""
+
+# Standard
+from multiprocessing import shared_memory
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.config import L1MemoryManagerConfig
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.memory_allocators.lazy_memory_allocator import LazyMemoryAllocator
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryObj,
+)
+
+logger = init_logger(__name__)
+
+
+# HELPER FUNCTIONS
+def _unlink_stale_shm(shm_name: str) -> None:
+    """Remove a stale LMCache shm segment if it exists."""
+    normalized = shm_name.lstrip("/")
+    if "/" in normalized or "\\" in normalized:
+        logger.warning("Refusing to unlink invalid shm name %s", shm_name)
+        return
+    if not normalized.startswith("lmcache_l1_pool_"):
+        return
+    try:
+        shm = shared_memory.SharedMemory(name=normalized, create=False)
+        shm.close()
+        shm.unlink()
+    except FileNotFoundError:
+        return
+    except OSError:
+        logger.warning(
+            "Failed to remove stale shm segment %s", normalized, exc_info=True
+        )
+
+
+def create_memory_allocator(config: L1MemoryManagerConfig) -> MemoryAllocatorInterface:
+    """
+    Create a memory allocator based on the provided configuration.
+
+    Args:
+        config (L1MemoryManagerConfig): Configuration for the memory manager.
+
+    Returns:
+        MemoryAllocatorInterface: An instance of a memory allocator.
+    """
+    if config.use_lazy:
+        logger.debug(
+            "use lazy memory allocator, init size is %d bytes, "
+            "final size is %d bytes, align bytes is %d bytes",
+            config.init_size_in_bytes,
+            config.size_in_bytes,
+            config.align_bytes,
+        )
+        return LazyMemoryAllocator(
+            config.init_size_in_bytes, config.size_in_bytes, config.align_bytes
+        )
+    else:
+        logger.debug(
+            "use mixed memory allocator, total size is %d bytes, "
+            "align bytes is %d bytes",
+            config.size_in_bytes,
+            config.align_bytes,
+        )
+        shm_name = config.shm_name
+        if shm_name:
+            # Keep the lmcache_l1_pool_ prefix in normalized SHM names so
+            # stale-segment cleanup can recognize and unlink user-provided names.
+            bare = shm_name.lstrip("/")
+            if not bare.startswith("lmcache_l1_pool_"):
+                shm_name = f"lmcache_l1_pool_{bare}"
+            _unlink_stale_shm(shm_name)
+            return MixedMemoryAllocator(
+                config.size_in_bytes,
+                align_bytes=config.align_bytes,
+                shm_name=shm_name,
+            )
+        return MixedMemoryAllocator(
+            config.size_in_bytes,
+            align_bytes=config.align_bytes,
+        )
+
+
+# MAIN CLASS
+class L1MemoryManager:
+    """
+    L1MemoryManager manages the allocation and deallocation of L1 memory.
+
+    Observability metrics to emit:
+    1. Memory usage
+    2. Active allocations
+    """
+
+    def __init__(self, config: L1MemoryManagerConfig):
+        self._allocator = create_memory_allocator(config)
+        self._size_in_bytes = config.size_in_bytes
+        self._align_bytes = config.align_bytes
+
+    def allocate(
+        self, layout_desc: MemoryLayoutDesc, count: int
+    ) -> tuple[L1Error, list[MemoryObj]]:
+        """
+        Allocate memory objects based on the provided layout description and count.
+        This function should be thread-safe
+
+        Args:
+            layout_desc (MemoryLayoutDesc): Description of the memory layout.
+            count (int): Number of memory objects to allocate.
+
+        Returns:
+            tuple[L1Error, list[MemoryObj]]: Error code and list of
+            allocated memory objects.
+            Error code will be `L1Error.OUT_OF_MEMORY` if allocation
+            fails; otherwise, it will be `L1Error.SUCCESS`.
+
+        Note:
+            If the allocation fails, the memory object list will be empty.
+        """
+        objects = self._allocator.batched_allocate(
+            layout_desc.shapes, layout_desc.dtypes, count
+        )
+        if objects is None:
+            return L1Error.OUT_OF_MEMORY, []
+        return L1Error.SUCCESS, objects
+
+    def free(self, mem_objs: list[MemoryObj]) -> L1Error:
+        """
+        Free the provided memory objects.
+        This function should be thread-safe.
+
+        Args:
+            mem_objs (list[MemoryObj]): List of memory objects to free.
+
+        Returns:
+            L1Error: Error code indicating the result of the operation.
+            It will be `L1Error.SUCCESS` if the operation succeeds.
+        """
+        self._allocator.batched_free(mem_objs)
+        return L1Error.SUCCESS
+
+    def get_memory_usage(self) -> tuple[int, int]:
+        """
+        Get the current memory usage. This function will mainly be used to support
+        eviction decision.
+
+        Returns:
+            tuple[int, int]: A tuple containing used memory in bytes and total memory
+            in bytes.
+
+        Note:
+            In the future, we may want to make a "callback" based mechanism to
+            trigger eviction when the memory usage reaches a watermark.
+        """
+
+        if hasattr(self._allocator, "get_memory_usage"):
+            return self._allocator.get_memory_usage()
+
+        def get_address_manager(allocator: MemoryAllocatorInterface):
+            if isinstance(allocator, MixedMemoryAllocator) and hasattr(
+                allocator.pin_allocator, "address_manager"
+            ):
+                return allocator.pin_allocator.address_manager
+            if isinstance(allocator, LazyMemoryAllocator):
+                return allocator.get_address_manager()
+            raise NotImplementedError(
+                "get_memory_usage is not implemented for this allocator type."
+            )
+
+        address_manager = get_address_manager(self._allocator)
+        free_size = address_manager.get_free_size()
+        total_size = address_manager.get_heap_size()
+        used_size = total_size - free_size
+        return used_size, total_size
+
+    def get_l1_memory_desc(self) -> L1MemoryDesc:
+        """
+        Return an L1MemoryDesc describing the underlying memory buffer.
+
+        Returns:
+            L1MemoryDesc: Pointer, size, and alignment of the L1 buffer.
+
+        Raises:
+            NotImplementedError: If the allocator type does not support this operation.
+        """
+        if isinstance(self._allocator, MixedMemoryAllocator):
+            buffer = self._allocator.buffer
+        elif isinstance(self._allocator, LazyMemoryAllocator):
+            # TODO(ApostaC): need to test if the RDMA registration works
+            # before the lazy expansion is finished
+            buffer = self._allocator.get_underlying_buffer()
+        else:
+            raise NotImplementedError(
+                "get_l1_memory_desc is not implemented for this allocator type."
+            )
+        return L1MemoryDesc(
+            ptr=buffer.data_ptr(),
+            size=self._size_in_bytes,
+            align_bytes=self._align_bytes,
+        )
+
+    def close(self) -> None:
+        """
+        Close the memory manager and release all resources.
+        """
+        self._allocator.close()
+
+    # Debugging APIs
+    def memcheck(self):
+        return self._allocator.memcheck()
diff --git a/lmcache/v1/distributed/quota_manager.py b/lmcache/v1/distributed/quota_manager.py
new file mode 100644
index 0000000..b89d2df
--- /dev/null
+++ b/lmcache/v1/distributed/quota_manager.py
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Per-cache_salt quota registry.
+
+Holds the authoritative map from ``cache_salt`` to a byte budget.
+Consumed by the L2 eviction controller each cycle to decide which
+users are over their quota, and by the HTTP API for runtime
+administration (CRUD endpoints at ``/quota/...``).
+
+Salts without an explicit entry resolve through two different lenses:
+
+- :meth:`get_limit_bytes` — legacy allowlist semantics: unregistered
+  salts resolve to ``0`` bytes, so their data is evicted next cycle.
+  Used by the MP server's local eviction controller.
+- :meth:`effective_limit_bytes` — default-quota semantics: unregistered
+  salts resolve to the registry's *default limit*, which starts as
+  ``None`` (exempt from eviction). Used by the coordinator's eviction
+  manager, so a freshly booted coordinator whose quota table has not
+  been re-synced by the external quota controller cannot mass-evict
+  unknown tenants. The controller arms allowlist enforcement by setting
+  the default to ``0`` (``PUT /quota/config``) after syncing quotas.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import threading
+
+# First Party
+from lmcache.v1.distributed.internal_api import QuotaEntry
+
+
+class QuotaManager:
+    """Thread-safe registry of byte quotas keyed by ``cache_salt``.
+
+    Quotas are dynamic — CRUD operations (``set_quota``, ``delete_quota``)
+    are cheap, and any change takes effect on the very next eviction
+    cycle (no restart needed).
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        # cache_salt -> limit in bytes
+        self._limits: dict[str, int] = {}
+        # Limit applied by ``effective_limit_bytes`` to salts with no
+        # explicit entry. ``None`` (the boot default) means "exempt":
+        # consumers of the default-quota semantics skip eviction for
+        # unregistered salts until an operator sets a concrete value.
+        self._default_limit_bytes: int | None = None
+
+    def set_quota(self, cache_salt: str, limit_bytes: int) -> None:
+        """Create or update the quota for ``cache_salt``.
+
+        Raises ``ValueError`` for a negative limit. A zero limit is
+        accepted and behaves identically to having no entry at all
+        (keys under this salt will be evicted next cycle) — the
+        difference is purely bookkeeping: the entry shows up in
+        ``list_quotas()`` until removed.
+        """
+        if limit_bytes < 0:
+            raise ValueError(f"limit_bytes must be non-negative (got {limit_bytes})")
+        with self._lock:
+            self._limits[cache_salt] = limit_bytes
+
+    def delete_quota(self, cache_salt: str) -> bool:
+        """Remove the quota entry for ``cache_salt``.
+
+        Returns ``True`` if an entry was removed, ``False`` if the salt
+        had no registration. After deletion the effective limit drops
+        to ``0``, so any existing bytes under that salt will be evicted
+        at the next eviction cycle.
+        """
+        with self._lock:
+            return self._limits.pop(cache_salt, None) is not None
+
+    def get_limit_bytes(self, cache_salt: str) -> int:
+        """Return the effective limit for ``cache_salt``.
+
+        Unregistered salts resolve to ``0`` (allowlist semantics) —
+        callers use this value to drive eviction decisions, so the
+        zero default deliberately triggers eviction of any bytes
+        accumulated under an unknown salt.
+        """
+        with self._lock:
+            return self._limits.get(cache_salt, 0)
+
+    def set_default_limit_bytes(self, limit_bytes: int | None) -> None:
+        """Set the limit applied to salts with no explicit entry.
+
+        Args:
+            limit_bytes: ``None`` exempts unregistered salts from
+                eviction (the boot default). ``0`` activates strict
+                allowlist enforcement — all bytes under unregistered
+                salts become evictable next cycle. A positive value
+                gives every unregistered salt that byte budget.
+
+        Raises:
+            ValueError: If ``limit_bytes`` is negative.
+        """
+        if limit_bytes is not None and limit_bytes < 0:
+            raise ValueError(f"limit_bytes must be non-negative (got {limit_bytes})")
+        with self._lock:
+            self._default_limit_bytes = limit_bytes
+
+    def get_default_limit_bytes(self) -> int | None:
+        """Return the default limit for unregistered salts.
+
+        ``None`` means unregistered salts are exempt from eviction (no
+        default has been configured since startup).
+        """
+        with self._lock:
+            return self._default_limit_bytes
+
+    def effective_limit_bytes(self, cache_salt: str) -> int | None:
+        """Return the limit for ``cache_salt`` under default-quota semantics.
+
+        Explicitly registered salts return their registered limit.
+        Unregistered salts return the default limit — ``None`` (exempt
+        from eviction) until :meth:`set_default_limit_bytes` configures a
+        concrete value. See the module docstring for how this differs
+        from :meth:`get_limit_bytes`.
+        """
+        with self._lock:
+            explicit = self._limits.get(cache_salt)
+            if explicit is not None:
+                return explicit
+            return self._default_limit_bytes
+
+    def has_quota(self, cache_salt: str) -> bool:
+        """Whether ``cache_salt`` has an explicit registration.
+
+        Useful for distinguishing "zero limit by default" from
+        "explicitly registered with limit=0" in status reports.
+        """
+        with self._lock:
+            return cache_salt in self._limits
+
+    def list_quotas(self) -> list[QuotaEntry]:
+        """Return a snapshot of all registered quotas.
+
+        The returned list is a detached copy; mutating it does not
+        affect the registry.
+        """
+        with self._lock:
+            return [
+                QuotaEntry(cache_salt=salt, limit_bytes=limit)
+                for salt, limit in self._limits.items()
+            ]
diff --git a/lmcache/v1/distributed/serde/__init__.py b/lmcache/v1/distributed/serde/__init__.py
new file mode 100644
index 0000000..9e06c99
--- /dev/null
+++ b/lmcache/v1/distributed/serde/__init__.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.distributed.serde.async_processor import AsyncSerdeProcessor
+from lmcache.v1.distributed.serde.base import (
+    Deserializer,
+    SerdeConfig,
+    SerdeProcessor,
+    SerdeTaskId,
+    Serializer,
+)
+from lmcache.v1.distributed.serde.factory import (
+    create_serde_processor,
+    get_registered_serde_types,
+    register_serde_factory,
+)
+from lmcache.v1.distributed.serde.fp8 import (
+    Fp8QuantizationDeserializer,
+    Fp8QuantizationSerializer,
+)
+from lmcache.v1.distributed.serde.multi import (
+    LayoutDescGroup,
+    MemoryObjGroup,
+    MultiDeserializer,
+    MultiSerializer,
+    single_to_multi_deserializer,
+    single_to_multi_serializer,
+    validate_group_size,
+)
+from lmcache.v1.distributed.serde.turboquant import (
+    TurboQuantDeserializer,
+    TurboQuantSerdeConfig,
+    TurboQuantSerializer,
+)
+from lmcache.v1.distributed.serde.utils import (
+    make_temp_key,
+    serialized_layout_desc,
+)
+
+__all__ = [
+    "AsyncSerdeProcessor",
+    "Deserializer",
+    "Fp8QuantizationDeserializer",
+    "Fp8QuantizationSerializer",
+    "LayoutDescGroup",
+    "MemoryObjGroup",
+    "MultiDeserializer",
+    "MultiSerializer",
+    "SerdeConfig",
+    "SerdeProcessor",
+    "SerdeTaskId",
+    "Serializer",
+    "create_serde_processor",
+    "get_registered_serde_types",
+    "make_temp_key",
+    "register_serde_factory",
+    "serialized_layout_desc",
+    "TurboQuantDeserializer",
+    "TurboQuantSerdeConfig",
+    "TurboQuantSerializer",
+    "single_to_multi_deserializer",
+    "single_to_multi_serializer",
+    "validate_group_size",
+]
diff --git a/lmcache/v1/distributed/serde/asym_k16_v8.py b/lmcache/v1/distributed/serde/asym_k16_v8.py
new file mode 100644
index 0000000..c4fac58
--- /dev/null
+++ b/lmcache/v1/distributed/serde/asym_k16_v8.py
@@ -0,0 +1,537 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Asymmetric K16/V8 multi-output serde.
+
+Concrete :class:`MultiSerializer` / :class:`MultiDeserializer`
+pair that bridges :class:`AsymK16V8Codec` (in
+``lmcache/v1/kv_codec``) into the tuple-shaped serde contract
+from ``multi.py``.
+
+**Storage-only-dequant mode.** Group of size 2 on both endpoints:
+
+* serialize input ``src = (K, V)`` -- both at the model's native
+  dtype (fp16 / bf16). The codec quantizes V to FP8 internally
+  and writes a single byte buffer containing K bytes, V FP8
+  bytes, and the codec header with V's scale.
+* deserialize output ``dst = (K_out, V_out)`` -- both at the
+  model's native dtype, with V dequantized from the stored FP8.
+
+Compresses the bytes that ship to L2 storage; the consumer-visible
+view on read is unchanged.
+
+**Split-tier / V-only mode.** Group of size 2 on both endpoints;
+K is held in L1 (CPU-pinned host memory) and only V flows through
+this serde to L2:
+
+* serialize input ``src = (None, V)`` -- the K slot MUST be
+  ``None``. Emits an :class:`EncodedKV` with ``k_payload_len = 0``;
+  the ``k_dtype`` tag is still recorded so cross-config gating
+  works on the eventual restore.
+* deserialize output ``dst = (None | K_skip, V_out)`` -- slot 0
+  is a no-op regardless of input (K is sourced from L1); slot 1
+  is dequantized from the stored FP8.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import math
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.serde.multi import (
+    LayoutDescGroup,
+    MemoryObjGroup,
+    MultiDeserializer,
+    MultiSerializer,
+    validate_group_size,
+)
+from lmcache.v1.kv_codec import AsymK16V8Codec, EncodedKV, ScaleScope
+from lmcache.v1.kv_codec.asym_k16_v8 import (
+    _tensor_to_bytes_fast,
+    compute_v_scales,
+    dequantize_v_fp8,
+    quantize_v_fp8,
+)
+from lmcache.v1.memory_management import MemoryObj
+
+_GROUP_SIZE_STORAGE_ONLY = 2  # (K, V) on both sides for this mode.
+_GROUP_SIZE_V_ONLY = 2  # (None, V) on serialize ; (None|K_out, V_out) on deserialize.
+
+
+def _v_fp8_max_for_dtype(fp8_dtype: torch.dtype) -> float:
+    return float(torch.finfo(fp8_dtype).max)
+
+
+class AsymK16V8MultiSerializer(MultiSerializer):
+    """Encode ``(K, V)`` into a single asymmetric K16/V8 byte blob.
+
+    Slot semantics:
+
+    * ``slot 0 = K`` (required, fp16 or bf16, native model dtype).
+    * ``slot 1 = V`` (required, fp16 or bf16, native model dtype).
+
+    ``None`` is not admitted in either slot for this mode -- both K
+    and V must be supplied.
+
+    The codec produces a self-describing blob: header (dtype tags,
+    scale scope, scale tensor, optional shape metadata) followed by
+    K bytes (native dtype), V bytes (FP8 e4m3), and scale bytes.
+    The exact byte layout is owned by ``serialize_header`` /
+    ``deserialize_header`` in ``encoded_kv``; this serializer is
+    just glue so the codec is reachable through the
+    :class:`MultiSerializer` interface.
+    """
+
+    def __init__(
+        self,
+        fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+        scale_scope: ScaleScope = ScaleScope.PER_TENSOR,
+        scale_dtype: torch.dtype = torch.float32,
+    ) -> None:
+        self._codec = AsymK16V8Codec(
+            fp8_dtype=fp8_dtype,
+            scale_scope=scale_scope,
+            scale_dtype=scale_dtype,
+        )
+        self._fp8_dtype = fp8_dtype
+
+    @property
+    def group_size(self) -> int:
+        return _GROUP_SIZE_STORAGE_ONLY
+
+    def serialize(self, src: MemoryObjGroup, dst: MemoryObj) -> int:
+        validate_group_size(src, _GROUP_SIZE_STORAGE_ONLY, role="src")
+        k_obj, v_obj = src
+        if k_obj is None or v_obj is None:
+            raise ValueError(
+                "AsymK16V8MultiSerializer (storage-only-dequant): both K "
+                "and V must be provided"
+            )
+        if k_obj.tensor is None or v_obj.tensor is None:
+            raise ValueError(
+                "AsymK16V8MultiSerializer: src MemoryObjs must have tensors set"
+            )
+        if dst.tensor is None:
+            raise ValueError("AsymK16V8MultiSerializer: dst.tensor is None")
+
+        enc = self._codec.encode(k_obj.tensor, v_obj.tensor)
+        blob = self._codec.to_bytes(enc)
+        n = len(blob)
+        if dst.tensor.numel() < n:
+            raise ValueError(
+                f"AsymK16V8MultiSerializer: dst capacity {dst.tensor.numel()} "
+                f"below required {n}"
+            )
+        dst_view = dst.tensor.view(torch.uint8)
+        dst_view[:n].copy_(torch.frombuffer(blob, dtype=torch.uint8))
+        return n
+
+    def estimate_serialized_size(
+        self,
+        layout_descs: LayoutDescGroup,
+    ) -> int:
+        validate_group_size(layout_descs, _GROUP_SIZE_STORAGE_ONLY, role="layout")
+        k_layout, v_layout = layout_descs
+        if k_layout is None or v_layout is None:
+            raise ValueError(
+                "AsymK16V8MultiSerializer.estimate_serialized_size "
+                "(storage-only-dequant): both K and V layouts required"
+            )
+
+        # Bytes accounting:
+        #   K: sum(numel(shape)) * itemsize(K_dtype)
+        #   V: sum(numel(shape)) * 1          (FP8 = 1 byte / elem)
+        #   scales: scope-dependent; only PER_TENSOR and EXTERNAL are
+        #           bounded by layout alone. PER_LAYER_HEAD and
+        #           PER_PAGE_HEAD need head/page metadata that the
+        #           layout descriptor does not carry, so they are
+        #           rejected here -- callers with those scopes must
+        #           extend the API rather than risk a silent undersize.
+        #   header: <= 1 KB allowance for dtype tags + hashes + shape
+        scope = self._codec.scale_scope
+        scale_dtype = self._codec.scale_dtype
+        if scope == ScaleScope.PER_TENSOR:
+            scales_bytes = scale_dtype.itemsize
+        elif scope == ScaleScope.EXTERNAL:
+            scales_bytes = 0
+        else:
+            raise ValueError(
+                f"AsymK16V8MultiSerializer.estimate_serialized_size: "
+                f"scale_scope {scope} requires per-head/per-page metadata "
+                f"that MemoryLayoutDesc does not carry; only PER_TENSOR "
+                f"and EXTERNAL are supported here"
+            )
+        k_bytes = sum(
+            math.prod(s) * d.itemsize
+            for s, d in zip(k_layout.shapes, k_layout.dtypes, strict=True)
+        )
+        v_bytes = sum(math.prod(s) for s in v_layout.shapes)
+        header_allowance = 1024
+        return header_allowance + k_bytes + v_bytes + scales_bytes
+
+
+class AsymK16V8MultiDeserializer(MultiDeserializer):
+    """Decode an asymmetric K16/V8 byte blob into ``(K_out, V_out)``.
+
+    Slot semantics (storage-only-dequant mode):
+
+    * ``slot 0 = K_out`` — caller-provided MemoryObj at the model's
+      native dtype, populated bit-exact from the blob.
+    * ``slot 1 = V_out`` — caller-provided MemoryObj at the model's
+      native dtype, populated by dequantizing the stored FP8 V.
+
+    A ``None`` slot is treated as a deliberate skip (the corresponding
+    output is left untouched), matching the contract documented in
+    ``multi.py``. This provides the V-only-read shape: pass
+    ``(K_out, None)`` to load K only; pass ``(None, V_out)`` to load
+    V only.
+    """
+
+    def __init__(
+        self,
+        fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+        scale_scope: ScaleScope = ScaleScope.PER_TENSOR,
+        scale_dtype: torch.dtype = torch.float32,
+    ) -> None:
+        self._codec = AsymK16V8Codec(
+            fp8_dtype=fp8_dtype,
+            scale_scope=scale_scope,
+            scale_dtype=scale_dtype,
+        )
+
+    @property
+    def group_size(self) -> int:
+        return _GROUP_SIZE_STORAGE_ONLY
+
+    def deserialize(self, src: MemoryObj, dst: MemoryObjGroup) -> None:
+        validate_group_size(dst, _GROUP_SIZE_STORAGE_ONLY, role="dst")
+        if src.tensor is None:
+            raise ValueError("AsymK16V8MultiDeserializer: src.tensor is None")
+
+        # Pull blob bytes out of the source uint8 buffer.
+        src_view = src.tensor.view(torch.uint8).contiguous()
+        blob = src_view.numpy().tobytes()
+
+        # Decode through the codec; ``decode`` returns 1-D flat tensors
+        # for K and V, plus the scale tensor.  We reshape into the
+        # caller-provided dst shapes.
+        k_obj, v_obj = dst
+        if k_obj is None and v_obj is None:
+            # Both slots skipped — nothing to do.
+            return
+
+        # Pick the V output dtype from whichever dst slot is set.  If
+        # only K is requested we still decode V to the same dtype so
+        # the codec contract (no silent fp16 fallback) stays explicit;
+        # the V tensor is then discarded.
+        if v_obj is not None and v_obj.tensor is not None:
+            target_v_dtype = v_obj.tensor.dtype
+        elif k_obj is not None and k_obj.tensor is not None:
+            target_v_dtype = k_obj.tensor.dtype
+        else:
+            raise ValueError(
+                "AsymK16V8MultiDeserializer: at least one non-None dst "
+                "slot must have a tensor set"
+            )
+
+        enc = self._codec.from_bytes(blob)
+        # Push the K dtype conversion into the codec so the serde
+        # doesn't need a post-decode cast.
+        if k_obj is not None and k_obj.tensor is not None:
+            out_k_dtype = k_obj.tensor.dtype
+        else:
+            out_k_dtype = None
+        k_flat, v_dq_flat, _scales = self._codec.decode(
+            enc, out_k_dtype=out_k_dtype, out_v_dtype=target_v_dtype
+        )
+
+        if k_obj is not None:
+            if k_obj.tensor is None:
+                raise ValueError(
+                    "AsymK16V8MultiDeserializer: non-None K dst slot "
+                    "must have a tensor set"
+                )
+            target_shape = k_obj.tensor.shape
+            if k_flat.numel() != k_obj.tensor.numel():
+                raise ValueError(
+                    f"AsymK16V8MultiDeserializer: decoded K has "
+                    f"{k_flat.numel()} elements, dst K shape "
+                    f"{tuple(target_shape)} expects "
+                    f"{k_obj.tensor.numel()}"
+                )
+            k_obj.tensor.copy_(k_flat.reshape(target_shape))
+
+        if v_obj is not None:
+            if v_obj.tensor is None:
+                raise ValueError(
+                    "AsymK16V8MultiDeserializer: non-None V dst slot "
+                    "must have a tensor set"
+                )
+            target_shape = v_obj.tensor.shape
+            if v_dq_flat.numel() != v_obj.tensor.numel():
+                raise ValueError(
+                    f"AsymK16V8MultiDeserializer: decoded V has "
+                    f"{v_dq_flat.numel()} elements, dst V shape "
+                    f"{tuple(target_shape)} expects "
+                    f"{v_obj.tensor.numel()}"
+                )
+            v_obj.tensor.copy_(v_dq_flat.reshape(target_shape))
+
+
+class AsymK16V8VOnlyMultiSerializer(MultiSerializer):
+    """Encode V-only into a split-tier asymmetric byte blob.
+
+    Split-tier path: K stays in L1 (CPU-pinned host memory) and is
+    not written to the byte buffer; only the FP8-quantized V plus
+    its scales hit L2.  The blob is a regular :class:`EncodedKV`
+    with ``k_payload_len = 0`` and the ``k_dtype`` tag set to
+    whatever dtype K would have been (so cross-config gating still
+    works on the eventual restore).
+
+    Slot semantics:
+
+    * ``slot 0 = K`` MUST be ``None``.  Passing a tensor here is a
+      contract error: this serde does not write K bytes by design.
+      Use :class:`AsymK16V8MultiSerializer` instead if you want a
+      self-contained restorable object.
+    * ``slot 1 = V`` (required, fp16 or bf16, native model dtype).
+
+    Byte ratio vs FP16 KV: ``V_8 / (K_16 + V_16) = 1/4``,
+    equivalently ``1/3`` of the corresponding storage-only-dequant
+    blob (which carries both K and V).
+    """
+
+    def __init__(
+        self,
+        fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+        scale_scope: ScaleScope = ScaleScope.PER_TENSOR,
+        scale_dtype: torch.dtype = torch.float32,
+        # The k_dtype tag is recorded in the header so a future
+        # restore that pairs this V blob with its CPU-resident K can
+        # cross-check dtype agreement.  Defaults to bfloat16.
+        k_dtype_tag: torch.dtype = torch.bfloat16,
+    ) -> None:
+        # Reuse the same codec instance for header serialization.
+        self._codec = AsymK16V8Codec(
+            fp8_dtype=fp8_dtype,
+            scale_scope=scale_scope,
+            scale_dtype=scale_dtype,
+        )
+        self._fp8_dtype = fp8_dtype
+        self._scale_dtype = scale_dtype
+        self._scale_scope = scale_scope
+        self._k_dtype_tag = k_dtype_tag
+
+    @property
+    def group_size(self) -> int:
+        return _GROUP_SIZE_V_ONLY
+
+    def serialize(self, src: MemoryObjGroup, dst: MemoryObj) -> int:
+        validate_group_size(src, _GROUP_SIZE_V_ONLY, role="src")
+        k_obj, v_obj = src
+        if k_obj is not None:
+            raise ValueError(
+                "AsymK16V8VOnlyMultiSerializer (split-tier): K slot must "
+                "be None.  K stays in host RAM in this mode and is not "
+                "written to the byte buffer.  Use "
+                "AsymK16V8MultiSerializer for the self-contained "
+                "(K, V) write path."
+            )
+        if v_obj is None or v_obj.tensor is None:
+            raise ValueError(
+                "AsymK16V8VOnlyMultiSerializer: V slot is required and "
+                "must have a tensor set"
+            )
+        if dst.tensor is None:
+            raise ValueError("AsymK16V8VOnlyMultiSerializer: dst.tensor is None")
+
+        v = v_obj.tensor
+
+        # Compute per-tensor (or per-scope) V scales and quantize V.
+        v_scales = compute_v_scales(
+            v,
+            self._scale_scope,
+            fp8_dtype=self._fp8_dtype,
+        ).to(self._scale_dtype)
+        v_quant = quantize_v_fp8(
+            v,
+            v_scales,
+            self._scale_scope,
+            fp8_dtype=self._fp8_dtype,
+        )
+
+        v_cpu = v_quant.detach().to("cpu").contiguous().clone()
+        s_cpu = v_scales.detach().to("cpu").contiguous().clone()
+        v_bytes = _tensor_to_bytes_fast(v_cpu)
+        s_bytes = _tensor_to_bytes_fast(s_cpu)
+
+        enc = EncodedKV(
+            k_dtype=self._k_dtype_tag,
+            v_dtype=self._fp8_dtype,
+            scale_dtype=self._scale_dtype,
+            scale_scope=self._scale_scope,
+            k_payload_len=0,
+            v_payload_len=len(v_bytes),
+            scale_payload_len=len(s_bytes),
+            scale_shape=tuple(v_scales.shape),
+            payload=v_bytes + s_bytes,
+        )
+        blob = self._codec.to_bytes(enc)
+        n = len(blob)
+        if dst.tensor.numel() < n:
+            raise ValueError(
+                f"AsymK16V8VOnlyMultiSerializer: dst capacity "
+                f"{dst.tensor.numel()} below required {n}"
+            )
+        dst_view = dst.tensor.view(torch.uint8)
+        dst_view[:n].copy_(torch.frombuffer(blob, dtype=torch.uint8))
+        return n
+
+    def estimate_serialized_size(
+        self,
+        layout_descs: LayoutDescGroup,
+    ) -> int:
+        validate_group_size(layout_descs, _GROUP_SIZE_V_ONLY, role="layout")
+        k_layout, v_layout = layout_descs
+        if k_layout is not None:
+            raise ValueError(
+                "AsymK16V8VOnlyMultiSerializer.estimate_serialized_size: "
+                "K layout must be None — this mode does not write K bytes"
+            )
+        if v_layout is None:
+            raise ValueError(
+                "AsymK16V8VOnlyMultiSerializer.estimate_serialized_size: "
+                "V layout is required"
+            )
+
+        # Bytes accounting:
+        #   V (fp8): sum(numel(shape)) * 1 byte/elem
+        #   scales : scope-dependent; only PER_TENSOR and EXTERNAL are
+        #            bounded by layout alone (see the storage-only
+        #            estimator for the reasoning).
+        #   header : <= 1 KB allowance for dtype tags / hashes / shape
+        scope = self._codec.scale_scope
+        scale_dtype = self._codec.scale_dtype
+        if scope == ScaleScope.PER_TENSOR:
+            scales_bytes = scale_dtype.itemsize
+        elif scope == ScaleScope.EXTERNAL:
+            scales_bytes = 0
+        else:
+            raise ValueError(
+                f"AsymK16V8VOnlyMultiSerializer.estimate_serialized_size: "
+                f"scale_scope {scope} requires per-head/per-page metadata "
+                f"that MemoryLayoutDesc does not carry; only PER_TENSOR "
+                f"and EXTERNAL are supported here"
+            )
+        v_bytes = sum(math.prod(s) for s in v_layout.shapes)
+        header_allowance = 1024
+        return header_allowance + v_bytes + scales_bytes
+
+
+class AsymK16V8VOnlyMultiDeserializer(MultiDeserializer):
+    """Decode a split-tier (V-only) asymmetric blob into ``V_out``.
+
+    The blob carries V_fp8 + V_scales only; there is no K payload to
+    return.  The K slot is the no-op slot — passing a tensor there
+    is permitted but ignored (the slot is left untouched), which
+    lets the caller use the same dst-group shape as the storage-only
+    deserializer when convenient.
+
+    Slot semantics (split-tier mode):
+
+    * ``slot 0 = K_out`` — caller-provided MemoryObj, **left
+      untouched** by this deserializer regardless of whether the
+      slot is ``None`` or has a tensor set.  K must be supplied
+      from a separate source (typically the host-resident K cache).
+    * ``slot 1 = V_out`` — caller-provided MemoryObj at the model's
+      native dtype, populated by dequantizing the stored FP8 V.
+      ``None`` here is a deliberate skip (a no-op call).
+    """
+
+    def __init__(
+        self,
+        fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+        scale_scope: ScaleScope = ScaleScope.PER_TENSOR,
+        scale_dtype: torch.dtype = torch.float32,
+    ) -> None:
+        self._codec = AsymK16V8Codec(
+            fp8_dtype=fp8_dtype,
+            scale_scope=scale_scope,
+            scale_dtype=scale_dtype,
+        )
+
+    @property
+    def group_size(self) -> int:
+        return _GROUP_SIZE_V_ONLY
+
+    def deserialize(self, src: MemoryObj, dst: MemoryObjGroup) -> None:
+        validate_group_size(dst, _GROUP_SIZE_V_ONLY, role="dst")
+        if src.tensor is None:
+            raise ValueError("AsymK16V8VOnlyMultiDeserializer: src.tensor is None")
+
+        _k_obj, v_obj = dst
+        if v_obj is None:
+            # Nothing to materialize.  The K slot is a no-op for this
+            # mode regardless, so a (None, None) call is a deliberate
+            # skip rather than an error.
+            return
+        if v_obj.tensor is None:
+            raise ValueError(
+                "AsymK16V8VOnlyMultiDeserializer: non-None V dst slot "
+                "must have a tensor set"
+            )
+
+        src_view = src.tensor.view(torch.uint8).contiguous()
+        blob = src_view.numpy().tobytes()
+
+        enc = self._codec.from_bytes(blob)
+        if enc.k_payload_len != 0:
+            raise ValueError(
+                "AsymK16V8VOnlyMultiDeserializer: blob has k_payload_len="
+                f"{enc.k_payload_len} (>0); this is a storage-only-dequant "
+                "blob.  Use AsymK16V8MultiDeserializer to decode it."
+            )
+
+        # Inline the V-only slice of the codec's decode path.  We do
+        # NOT call ``self._codec.decode(enc)`` because that codepath
+        # tries to materialize a K tensor via ``torch.frombuffer`` on
+        # the empty K slice — which raises ``buffer length 0`` rather
+        # than returning an empty tensor.
+        target_v_dtype = v_obj.tensor.dtype
+        v_off = enc.k_payload_len  # = 0 for split-tier blobs
+        s_off = v_off + enc.v_payload_len
+        v_bytes = enc.payload[v_off:s_off]
+        s_bytes = enc.payload[s_off:]
+        scale_tensor = (
+            torch.frombuffer(s_bytes, dtype=enc.scale_dtype)
+            .clone()
+            .reshape(enc.scale_shape)
+        )
+        v_q = torch.frombuffer(v_bytes, dtype=enc.v_dtype).clone()
+        if target_v_dtype == enc.v_dtype:
+            v_dq_flat = v_q
+        else:
+            if not target_v_dtype.is_floating_point:
+                raise ValueError(
+                    "AsymK16V8VOnlyMultiDeserializer: target V dtype "
+                    f"{target_v_dtype} is not floating-point"
+                )
+            v_dq_flat = dequantize_v_fp8(
+                v_q,
+                scale_tensor,
+                enc.scale_scope,
+                out_dtype=target_v_dtype,
+            )
+
+        target_shape = v_obj.tensor.shape
+        if v_dq_flat.numel() != v_obj.tensor.numel():
+            raise ValueError(
+                f"AsymK16V8VOnlyMultiDeserializer: decoded V has "
+                f"{v_dq_flat.numel()} elements, dst V shape "
+                f"{tuple(target_shape)} expects {v_obj.tensor.numel()}"
+            )
+        v_obj.tensor.copy_(v_dq_flat.reshape(target_shape))
diff --git a/lmcache/v1/distributed/serde/async_processor.py b/lmcache/v1/distributed/serde/async_processor.py
new file mode 100644
index 0000000..10ceacf
--- /dev/null
+++ b/lmcache/v1/distributed/serde/async_processor.py
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+AsyncSerdeProcessor: wraps sync Serializer/Deserializer into the async
+SerdeProcessor interface expected by the controllers.
+
+Runs serialization/deserialization tasks in a thread pool and signals
+event notifiers on completion, matching the L2 adapter async pattern.
+The notifiers come from :mod:`lmcache.v1.platform` so the same code
+runs on Linux (eventfd) and other POSIX platforms (pipe fallback).
+"""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+import enum
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.base import (
+    Deserializer,
+    SerdeProcessor,
+    SerdeTaskId,
+    Serializer,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.platform import create_event_notifier
+
+logger = init_logger(__name__)
+
+
+class _TaskType(enum.Enum):
+    SERIALIZE = enum.auto()
+    DESERIALIZE = enum.auto()
+
+
+class AsyncSerdeProcessor(SerdeProcessor):
+    """Wraps sync Serializer/Deserializer into async SerdeProcessor.
+
+    Runs each submitted task in a thread pool. On completion, stores
+    the result and signals the appropriate event notifier so the
+    controller's poll loop wakes up.
+
+    Args:
+        serializer: Sync serializer implementation.
+        deserializer: Sync deserializer implementation.
+        max_workers: Thread pool size. Default 1 (serialization is
+            typically CPU-bound, more threads may help if the transform
+            releases the GIL).
+    """
+
+    def __init__(
+        self,
+        serializer: Serializer,
+        deserializer: Deserializer,
+        max_workers: int = 1,
+    ) -> None:
+        self._serializer = serializer
+        self._deserializer = deserializer
+
+        self._serialize_efd = create_event_notifier()
+        self._deserialize_efd = create_event_notifier()
+
+        self._lock = threading.Lock()
+        self._next_task_id: SerdeTaskId = 0
+        # task_id -> (success: bool) for completed tasks, partitioned by type
+        self._completed_serialize: dict[SerdeTaskId, bool] = {}
+        self._completed_deserialize: dict[SerdeTaskId, bool] = {}
+
+        self._pool = ThreadPoolExecutor(max_workers=max_workers)
+
+    # ----- Event fds -----
+
+    def get_serialize_event_fd(self) -> int:
+        """Return the fd signaled on serialize completion."""
+        return self._serialize_efd.fileno()
+
+    def get_deserialize_event_fd(self) -> int:
+        """Return the fd signaled on deserialize completion."""
+        return self._deserialize_efd.fileno()
+
+    # ----- Serialize -----
+
+    def submit_serialize(
+        self,
+        src_objs: list[MemoryObj],
+        dst_objs: list[MemoryObj],
+    ) -> SerdeTaskId:
+        """Submit a batch serialize task to the thread pool."""
+        task_id = self._alloc_task_id()
+        logger.debug(
+            "Serde: submitted serialize task %d (%d objects)",
+            task_id,
+            len(src_objs),
+        )
+        self._pool.submit(
+            self._run_task,
+            task_id,
+            _TaskType.SERIALIZE,
+            src_objs,
+            dst_objs,
+        )
+        return task_id
+
+    def query_serialize_result(self, task_id: SerdeTaskId) -> bool | None:
+        """Pop and return the serialize task result, or None if pending."""
+        with self._lock:
+            return self._completed_serialize.pop(task_id, None)
+
+    # ----- Deserialize -----
+
+    def submit_deserialize(
+        self,
+        src_objs: list[MemoryObj],
+        dst_objs: list[MemoryObj],
+    ) -> SerdeTaskId:
+        """Submit a batch deserialize task to the thread pool."""
+        task_id = self._alloc_task_id()
+        logger.debug(
+            "Serde: submitted deserialize task %d (%d objects)",
+            task_id,
+            len(src_objs),
+        )
+        self._pool.submit(
+            self._run_task,
+            task_id,
+            _TaskType.DESERIALIZE,
+            src_objs,
+            dst_objs,
+        )
+        return task_id
+
+    def query_deserialize_result(self, task_id: SerdeTaskId) -> bool | None:
+        """Pop and return the deserialize task result, or None if pending."""
+        with self._lock:
+            return self._completed_deserialize.pop(task_id, None)
+
+    # ----- Size estimation (delegates to sync serializer) -----
+
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        """Delegate to the sync serializer's estimate (includes margin)."""
+        return self._serializer.estimate_serialized_size(layout_desc)
+
+    # ----- Lifecycle -----
+
+    def close(self) -> None:
+        """Shut down the thread pool and close event notifiers."""
+        self._pool.shutdown(wait=True)
+        self._serialize_efd.close()
+        self._deserialize_efd.close()
+
+    # ----- Internal -----
+
+    def _alloc_task_id(self) -> SerdeTaskId:
+        with self._lock:
+            task_id = self._next_task_id
+            self._next_task_id += 1
+        return task_id
+
+    def _run_task(
+        self,
+        task_id: SerdeTaskId,
+        task_type: _TaskType,
+        src_objs: list[MemoryObj],
+        dst_objs: list[MemoryObj],
+    ) -> None:
+        """Execute a serialize/deserialize task in the thread pool.
+
+        On completion (success or failure), stores the result and
+        signals the event notifier.
+        """
+        success = True
+        try:
+            if task_type == _TaskType.SERIALIZE:
+                for src, dst in zip(src_objs, dst_objs, strict=True):
+                    # ``serialize`` returns the actual number of bytes
+                    # written, which may be smaller than the destination
+                    # buffer (since the destination is sized from
+                    # ``estimate_serialized_size``, an upper bound).
+                    # Narrow the destination's logical size to ``n`` so
+                    # downstream L2 adapters that read the size via
+                    # ``obj.get_size()`` / ``obj.byte_array`` store
+                    # exactly ``n`` bytes -- not the over-allocated
+                    # estimate.  Guarded so duck-typed test fakes that
+                    # don't implement the interface still work, and so a
+                    # serializer that does not honor the ``-> int``
+                    # contract (returns ``None``) is skipped rather than
+                    # tripping set_used_size's range check.
+                    n = self._serializer.serialize(src, dst)
+                    if isinstance(n, int) and hasattr(dst, "set_used_size"):
+                        dst.set_used_size(n)
+            else:
+                for src, dst in zip(src_objs, dst_objs, strict=True):
+                    self._deserializer.deserialize(src, dst)
+        except Exception:
+            logger.exception(
+                "Serde task %d (%s) failed",
+                task_id,
+                task_type.name,
+            )
+            success = False
+
+        if success:
+            logger.debug(
+                "Serde: %s task %d completed successfully (%d objects)",
+                task_type.name.lower(),
+                task_id,
+                len(src_objs),
+            )
+        else:
+            logger.warning(
+                "Serde: %s task %d failed (%d objects)",
+                task_type.name.lower(),
+                task_id,
+                len(src_objs),
+            )
+
+        with self._lock:
+            if task_type == _TaskType.SERIALIZE:
+                self._completed_serialize[task_id] = success
+            else:
+                self._completed_deserialize[task_id] = success
+
+        # Signal the appropriate notifier to wake the controller's poll loop
+        notifier = (
+            self._serialize_efd
+            if task_type == _TaskType.SERIALIZE
+            else self._deserialize_efd
+        )
+        try:
+            notifier.notify()
+        except OSError:
+            logger.exception("Failed to signal notifier for serde task %d", task_id)
diff --git a/lmcache/v1/distributed/serde/base.py b/lmcache/v1/distributed/serde/base.py
new file mode 100644
index 0000000..6a8a1ea
--- /dev/null
+++ b/lmcache/v1/distributed/serde/base.py
@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Serde interfaces for the distributed (multiprocess) storage controllers.
+
+Two layers:
+1. **Sync interface** (Serializer / Deserializer): user implements these.
+   Pure transform logic, no threading or eventfds.
+2. **Async interface** (SerdeProcessor): controllers consume this.
+   Provides non-blocking submit/query/eventfd pattern matching L2 adapters.
+
+Use ``AsyncSerdeProcessor`` to wrap sync implementations into the async
+interface automatically.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+import abc
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.memory_management import MemoryObj
+
+SerdeTaskId = int
+
+
+@dataclass
+class SerdeConfig:
+    """Per-adapter serde configuration.
+
+    Mirrors the role of ``EvictionConfig``: parsed from the ``"serde"``
+    JSON sub-dict on an L2 adapter spec, then handed to the serde factory
+    to build a SerdeProcessor.
+
+    Attributes:
+        type: Registered serde type name (e.g. ``"fp8"``).
+        kwargs: Type-specific keyword args forwarded to the factory.
+    """
+
+    type: str
+    kwargs: dict[str, object] = field(default_factory=dict)
+
+
+# ============================================================================
+# Sync interface (user-facing)
+# ============================================================================
+
+
+class Serializer(abc.ABC):
+    """Sync serializer — users implement this.
+
+    Defines the pure transform from KV-shaped data to serialized bytes.
+    """
+
+    @abc.abstractmethod
+    def serialize(self, src: MemoryObj, dst: MemoryObj) -> int:
+        """Serialize src KV data into dst byte buffer (in-place).
+
+        Args:
+            src: Source MemoryObj containing KV-shaped data (read-locked).
+            dst: Destination MemoryObj byte buffer (write-locked).
+                 Must have capacity >= estimate_serialized_size().
+
+        Returns:
+            The actual number of bytes written to dst.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        """Return the byte size to allocate for the serialized temp buffer.
+
+        Called BEFORE serialization to allocate the temp buffer. The
+        returned value must be an upper bound on the actual serialized
+        output — include any safety margin here (e.g., 1.5x for
+        compressors whose output may occasionally exceed the estimate).
+
+        Args:
+            layout_desc: Memory layout of the source KV data.
+
+        Returns:
+            Number of bytes to allocate for the temp buffer.
+        """
+        raise NotImplementedError
+
+
+class Deserializer(abc.ABC):
+    """Sync deserializer — users implement this.
+
+    Defines the pure transform from serialized bytes to KV-shaped data.
+    """
+
+    @abc.abstractmethod
+    def deserialize(self, src: MemoryObj, dst: MemoryObj) -> None:
+        """Deserialize src byte buffer into dst KV-shaped MemoryObj (in-place).
+
+        Args:
+            src: Source MemoryObj containing serialized bytes.
+            dst: Destination MemoryObj with KV-shaped layout (write-locked).
+        """
+        raise NotImplementedError
+
+
+# ============================================================================
+# Async interface (consumed by SerdeL2AdapterWrapper)
+# ============================================================================
+
+
+class SerdeProcessor(abc.ABC):
+    """Async serde processor with eventfd-based completion notification.
+
+    Provides non-blocking serialize / deserialize with the same
+    ``submit → eventfd → query`` pattern as L2 adapters.
+
+    The serialize and deserialize event fds are consumed by
+    :class:`lmcache.v1.distributed.l2_adapters.serde_wrapper.SerdeL2AdapterWrapper`'s
+    internal thread, which chains serialize → inner.store on the store
+    path and inner.load → deserialize on the load path so controllers
+    see a plain L2 adapter. The two fds must be distinct file
+    descriptors so the wrapper's poll loop can disambiguate completions.
+
+    Users should NOT implement this directly. Instead, implement
+    ``Serializer`` / ``Deserializer`` and wrap with ``AsyncSerdeProcessor``.
+    """
+
+    # ----- Event fds -----
+
+    @abc.abstractmethod
+    def get_serialize_event_fd(self) -> int:
+        """Event fd signaled when serialize tasks complete.
+
+        Must be distinct from the deserialize event fd.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_deserialize_event_fd(self) -> int:
+        """Event fd signaled when deserialize tasks complete.
+
+        Must be distinct from the serialize event fd.
+        """
+        raise NotImplementedError
+
+    # ----- Serialize (store controller: L1 KV -> temp bytes) -----
+
+    @abc.abstractmethod
+    def submit_serialize(
+        self,
+        src_objs: list[MemoryObj],
+        dst_objs: list[MemoryObj],
+    ) -> SerdeTaskId:
+        """Submit a batch serialization task.
+
+        Args:
+            src_objs: Source KV-shaped MemoryObjs (read-locked).
+            dst_objs: Destination byte-buffer MemoryObjs (write-locked).
+
+        Returns:
+            Task ID for querying completion.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def query_serialize_result(self, task_id: SerdeTaskId) -> bool | None:
+        """Query serialization task completion.
+
+        Returns True on success, False on failure, None if still pending.
+        Non-idempotent: only returns a non-None value once per task.
+        """
+        raise NotImplementedError
+
+    # ----- Deserialize (prefetch controller: temp bytes -> L1 KV) -----
+
+    @abc.abstractmethod
+    def submit_deserialize(
+        self,
+        src_objs: list[MemoryObj],
+        dst_objs: list[MemoryObj],
+    ) -> SerdeTaskId:
+        """Submit a batch deserialization task.
+
+        Args:
+            src_objs: Source byte-buffer MemoryObjs (filled by L2 load).
+            dst_objs: Destination KV-shaped MemoryObjs (write-locked).
+
+        Returns:
+            Task ID for querying completion.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def query_deserialize_result(self, task_id: SerdeTaskId) -> bool | None:
+        """Query deserialization task completion.
+
+        Returns True on success, False on failure, None if still pending.
+        Non-idempotent: only returns a non-None value once per task.
+        """
+        raise NotImplementedError
+
+    # ----- Size estimation -----
+
+    @abc.abstractmethod
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        """Return the byte size to allocate for the serialized temp buffer.
+
+        The returned value is used directly as the buffer size — include
+        any safety margin. See :meth:`Serializer.estimate_serialized_size`.
+        """
+        raise NotImplementedError
+
+    # ----- Lifecycle -----
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Release resources (event fds, threads, etc.)."""
+        raise NotImplementedError
diff --git a/lmcache/v1/distributed/serde/factory.py b/lmcache/v1/distributed/serde/factory.py
new file mode 100644
index 0000000..95379a1
--- /dev/null
+++ b/lmcache/v1/distributed/serde/factory.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Factory for creating SerdeProcessor instances from SerdeConfig.
+
+Each serde type registers itself here so it can be referenced by name
+in L2 adapter configs:
+
+    {
+      "type": "fs",
+      "base_path": "/cache",
+      "serde": {"type": "fp8", "fp8_dtype": "float8_e4m3fn"}
+    }
+"""
+
+# Standard
+from typing import Callable
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.serde.base import SerdeConfig, SerdeProcessor
+
+logger = init_logger(__name__)
+
+# name -> factory(kwargs) -> SerdeProcessor.
+# Factories receive the type-specific kwargs (everything except "type").
+_SERDE_FACTORY_REGISTRY: dict[str, Callable[[dict[str, object]], SerdeProcessor]] = {}
+
+
+def register_serde_factory(
+    name: str, factory: Callable[[dict[str, object]], SerdeProcessor]
+) -> None:
+    """Register a serde factory under a type name.
+
+    Args:
+        name: Serde type name (used in the JSON config ``"type"`` field).
+        factory: Callable that takes the type-specific kwargs dict and
+            returns a SerdeProcessor instance.
+
+    Raises:
+        ValueError: If ``name`` is already registered.
+    """
+    if name in _SERDE_FACTORY_REGISTRY:
+        raise ValueError(f"Serde type already registered: {name!r}")
+    _SERDE_FACTORY_REGISTRY[name] = factory
+
+
+def get_registered_serde_types() -> list[str]:
+    """Return the list of registered serde type names."""
+    return list(_SERDE_FACTORY_REGISTRY)
+
+
+def create_serde_processor(config: SerdeConfig) -> SerdeProcessor:
+    """Build a SerdeProcessor from a SerdeConfig.
+
+    Args:
+        config: Serde configuration. ``config.type`` must name a registered
+            serde; ``config.kwargs`` is forwarded to the factory.
+
+    Returns:
+        A SerdeProcessor instance ready to be passed to a controller.
+
+    Raises:
+        ValueError: If ``config.type`` names an unregistered serde.
+    """
+    factory = _SERDE_FACTORY_REGISTRY.get(config.type)
+    if factory is None:
+        known = ", ".join(sorted(_SERDE_FACTORY_REGISTRY)) or "(none)"
+        raise ValueError(f"Unknown serde type {config.type!r}. Registered: {known}")
+    return factory(config.kwargs)
diff --git a/lmcache/v1/distributed/serde/fp8.py b/lmcache/v1/distributed/serde/fp8.py
new file mode 100644
index 0000000..6f10fed
--- /dev/null
+++ b/lmcache/v1/distributed/serde/fp8.py
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Simple fp8 quantization serde.
+
+Casts KV cache tensors to fp8 (1 byte per element) on serialize, and
+casts back to the destination's original dtype on deserialize.
+
+Lossy: precision below fp8's representable range is lost.
+"""
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.async_processor import AsyncSerdeProcessor
+from lmcache.v1.distributed.serde.base import Deserializer, SerdeProcessor, Serializer
+from lmcache.v1.distributed.serde.factory import register_serde_factory
+from lmcache.v1.memory_management import MemoryObj
+
+
+class Fp8QuantizationSerializer(Serializer):
+    """Quantize KV cache tensors to fp8 for L2 storage.
+
+    Args:
+        fp8_dtype: torch fp8 dtype to use. Defaults to float8_e4m3fn
+            (4-bit exponent, 3-bit mantissa, finite-only — good range
+            for inference activations).
+    """
+
+    def __init__(self, fp8_dtype: torch.dtype = torch.float8_e4m3fn):
+        self._fp8_dtype = fp8_dtype
+
+    def serialize(self, src: MemoryObj, dst: MemoryObj) -> int:
+        """Cast src tensor to fp8 and copy bytes into dst buffer."""
+        src_tensor = src.tensor
+        dst_tensor = dst.tensor
+        if src_tensor is None or dst_tensor is None:
+            raise ValueError("Fp8 serde requires src and dst to have tensors")
+
+        # Cast to fp8 (1 byte per element)
+        fp8_tensor = src_tensor.to(self._fp8_dtype).contiguous()
+        n_bytes = fp8_tensor.numel()
+
+        # Reinterpret fp8 bytes as uint8 and copy into dst byte buffer
+        fp8_as_bytes = fp8_tensor.view(torch.uint8).flatten()
+        dst_tensor.flatten()[:n_bytes].copy_(fp8_as_bytes)
+        return n_bytes
+
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        """Return buffer size for fp8 output: exactly 1 byte per element.
+
+        fp8 has a fixed 1:1 element-to-byte mapping, so the size is
+        deterministic — no margin is needed. Inflating the estimate
+        would inflate the bytes the wrapped L2 adapter persists (it
+        stores the whole MemoryObj), eroding the storage savings fp8
+        is meant to provide.
+        """
+        total_elements = 0
+        for shape in layout_desc.shapes:
+            n = 1
+            for dim in shape:
+                n *= int(dim)
+            total_elements += n
+        return total_elements
+
+
+class Fp8QuantizationDeserializer(Deserializer):
+    """Dequantize fp8 bytes back into the dst's original dtype."""
+
+    def __init__(self, fp8_dtype: torch.dtype = torch.float8_e4m3fn):
+        self._fp8_dtype = fp8_dtype
+
+    def deserialize(self, src: MemoryObj, dst: MemoryObj) -> None:
+        """Read fp8 bytes from src, cast to dst's dtype, copy into dst."""
+        src_tensor = src.tensor
+        dst_tensor = dst.tensor
+        if src_tensor is None or dst_tensor is None:
+            raise ValueError("Fp8 serde requires src and dst to have tensors")
+
+        n_elements = dst_tensor.numel()
+
+        # Read n_elements bytes from src, reinterpret as fp8, reshape, cast back
+        fp8_bytes = src_tensor.flatten()[:n_elements]
+        fp8_tensor = fp8_bytes.view(self._fp8_dtype).reshape(dst_tensor.shape)
+        dst_tensor.copy_(fp8_tensor.to(dst_tensor.dtype))
+
+
+def _create_fp8_serde(kwargs: dict[str, object]) -> SerdeProcessor:
+    dtype_name = str(kwargs.get("fp8_dtype", "float8_e4m3fn"))
+    fp8_dtype = getattr(torch, dtype_name, None)
+    if fp8_dtype is None:
+        raise ValueError(f"Unknown torch dtype: {dtype_name!r}")
+
+    max_workers = int(kwargs.get("max_workers", 1))  # type: ignore[call-overload]
+    return AsyncSerdeProcessor(
+        Fp8QuantizationSerializer(fp8_dtype),
+        Fp8QuantizationDeserializer(fp8_dtype),
+        max_workers=max_workers,
+    )
+
+
+register_serde_factory("fp8", _create_fp8_serde)
diff --git a/lmcache/v1/distributed/serde/multi.py b/lmcache/v1/distributed/serde/multi.py
new file mode 100644
index 0000000..1986bff
--- /dev/null
+++ b/lmcache/v1/distributed/serde/multi.py
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Multi-output serde extensions.
+
+The :class:`Serializer` and :class:`Deserializer` classes in
+``serde/base.py`` operate on one typed tensor at each endpoint:
+one tensor in, one byte buffer out on serialize, and the reverse
+on deserialize. That shape works when K and V share a single data
+type -- the serde just sees them as one combined tensor. It does
+not work in two cases:
+
+* **K and V at different data types.** A typed tensor has one
+  dtype, so a serde that wants K at one dtype (e.g. fp16/bf16) and
+  V at another (e.g. FP8) cannot carry both -- one of them would
+  have to be reinterpreted bytewise, losing the typed-tensor
+  contract every other consumer relies on.
+
+* **One side absent.** For tier-split placements where K or V is
+  held outside this serde's data path -- e.g. K kept in L1 (CPU
+  pinned host memory) while V flows to L2 (durable storage) -- the
+  serialize input has no tensor for the absent slot and the
+  deserialize output has no destination for it.
+
+This module defines the additive extension. It does NOT modify the
+single-tensor interfaces or any of their existing callers; the
+async processor, factory registry, L2 adapter wrapper, and built-in
+``fp8`` serde all keep their current behavior. A serde implementation
+that needs multiple tensors at an endpoint mixes in the multi-output
+ABC alongside the existing ``Serializer`` / ``Deserializer``, and the
+async wiring around it is added in a follow-up change once a concrete
+multi-output serde lands.
+
+The contracts kept deliberately narrow here:
+
+* A :class:`MemoryObjGroup` is a fixed-length tuple of
+  ``Optional[MemoryObj]``. ``None`` at a position means "this slot is
+  absent": on the serialize input side the corresponding tensor is
+  not provided (e.g., V-only writes), and on the deserialize output
+  side the caller does not want that tensor materialized (e.g.,
+  V-only retrieval). Implementations decide per slot whether absence
+  is permitted.
+* :class:`MultiSerializer` and :class:`MultiDeserializer` declare
+  ``group_size`` so the async layer can pre-validate group lengths
+  and so callers can introspect the contract without instantiating
+  one tensor of the tuple.
+* A single-element ``MemoryObjGroup`` is the trivial bridge to the
+  existing single-tensor API: :func:`single_to_multi_serializer` and
+  :func:`single_to_multi_deserializer` adapt an existing
+  ``Serializer`` / ``Deserializer`` so callers that work in groups can
+  invoke them uniformly. The adapter is layout-equivalent: a single
+  non-None group element delegates to the underlying ``serialize`` /
+  ``deserialize`` and the existing per-byte semantics are unchanged.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Optional, Sequence, Tuple
+import abc
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.base import Deserializer, Serializer
+from lmcache.v1.memory_management import MemoryObj
+
+# A fixed-length tuple of optional MemoryObjs. ``None`` denotes an
+# absent slot whose semantics are defined per-implementation: on the
+# serialize input side it means the caller is not supplying that
+# tensor (V-only writes); on the deserialize output side it means
+# the caller does not want that tensor materialized (V-only reads).
+MemoryObjGroup = Tuple[Optional[MemoryObj], ...]
+
+# Parallel layout-description tuple used by size estimators when one
+# or more positions are absent.
+LayoutDescGroup = Tuple[Optional[MemoryLayoutDesc], ...]
+
+
+class MultiSerializer(abc.ABC):
+    """Sync serializer with a fixed-length tuple as input.
+
+    Implementations MUST document, at minimum:
+
+    * The fixed value of :attr:`group_size`.
+    * The semantic carried by each slot (e.g., ``slot 0 = K``,
+      ``slot 1 = V``).
+    * Which slots are required and which may be ``None``. A slot that
+      may be ``None`` MUST be tolerated by ``estimate_serialized_size``
+      with a ``None`` layout descriptor at the same index.
+
+    The single-tensor :class:`Serializer` ABC remains the canonical
+    interface for one-in-one-out serdes; this class is purely
+    additive.
+    """
+
+    @property
+    @abc.abstractmethod
+    def group_size(self) -> int:
+        """Fixed input-tuple length expected by this serializer.
+
+        The async layer validates submitted groups against this value
+        before dispatch; raising the abstract property keeps the
+        invariant visible without instantiating a tuple of tensors.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def serialize(self, src: MemoryObjGroup, dst: MemoryObj) -> int:
+        """Serialize ``src`` group into ``dst`` byte buffer.
+
+        Args:
+            src: Source group with length :attr:`group_size`. Slots
+                may be ``None`` to indicate absence; the implementation
+                decides whether absence is admissible per slot and
+                MUST raise ``ValueError`` when a required slot is
+                missing.
+            dst: Destination MemoryObj byte buffer (write-locked).
+                Capacity MUST be at least the value previously
+                returned by :meth:`estimate_serialized_size` for the
+                same layout group.
+
+        Returns:
+            The number of bytes written to ``dst``.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def estimate_serialized_size(
+        self,
+        layout_descs: LayoutDescGroup,
+    ) -> int:
+        """Upper bound on bytes produced by :meth:`serialize`.
+
+        Args:
+            layout_descs: Group of optional layout descriptors with
+                length :attr:`group_size`. ``None`` slots MUST mirror
+                the absence pattern that :meth:`serialize` will see.
+
+        Returns:
+            Number of bytes to allocate for the serialized buffer,
+            including any safety margin the implementation requires.
+        """
+        raise NotImplementedError
+
+
+class MultiDeserializer(abc.ABC):
+    """Sync deserializer with a fixed-length tuple as output.
+
+    Implementations MUST document the same per-slot semantics as
+    :class:`MultiSerializer`. ``None`` at a destination slot means the
+    caller does not want that output materialized; the implementation
+    MUST NOT touch the missing slot and MUST NOT fail solely because
+    a slot is ``None`` if the schema permits it.
+    """
+
+    @property
+    @abc.abstractmethod
+    def group_size(self) -> int:
+        """Fixed output-tuple length produced by this deserializer."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def deserialize(self, src: MemoryObj, dst: MemoryObjGroup) -> None:
+        """Deserialize ``src`` byte buffer into ``dst`` group.
+
+        Args:
+            src: Source byte-buffer MemoryObj.
+            dst: Destination group with length :attr:`group_size`.
+                ``None`` slots MUST be left untouched.
+        """
+        raise NotImplementedError
+
+
+# ----- Adapters bridging single-tensor and tuple interfaces -----
+
+
+class _SingleAsMultiSerializer(MultiSerializer):
+    """Adapt an existing single-tensor :class:`Serializer` to the
+    multi-output interface as a length-1 group.
+
+    Used by callers that want to invoke single- and multi-tensor
+    serdes through the same group-shaped call site without forcing
+    every existing serde to subclass the multi ABC.
+    """
+
+    def __init__(self, inner: Serializer) -> None:
+        self._inner = inner
+
+    @property
+    def group_size(self) -> int:
+        return 1
+
+    def serialize(self, src: MemoryObjGroup, dst: MemoryObj) -> int:
+        if len(src) != 1:
+            raise ValueError(
+                f"_SingleAsMultiSerializer expected group of size 1, got {len(src)}"
+            )
+        single = src[0]
+        if single is None:
+            raise ValueError(
+                "_SingleAsMultiSerializer: single-tensor serializer "
+                "does not admit a None src slot"
+            )
+        return self._inner.serialize(single, dst)
+
+    def estimate_serialized_size(
+        self,
+        layout_descs: LayoutDescGroup,
+    ) -> int:
+        if len(layout_descs) != 1:
+            raise ValueError(
+                f"_SingleAsMultiSerializer expected layout group of "
+                f"size 1, got {len(layout_descs)}"
+            )
+        single = layout_descs[0]
+        if single is None:
+            raise ValueError(
+                "_SingleAsMultiSerializer: single-tensor serializer "
+                "requires a non-None layout descriptor"
+            )
+        return self._inner.estimate_serialized_size(single)
+
+
+class _SingleAsMultiDeserializer(MultiDeserializer):
+    """Adapt an existing single-tensor :class:`Deserializer` to the
+    multi-output interface as a length-1 group.
+    """
+
+    def __init__(self, inner: Deserializer) -> None:
+        self._inner = inner
+
+    @property
+    def group_size(self) -> int:
+        return 1
+
+    def deserialize(self, src: MemoryObj, dst: MemoryObjGroup) -> None:
+        if len(dst) != 1:
+            raise ValueError(
+                f"_SingleAsMultiDeserializer expected group of size 1, got {len(dst)}"
+            )
+        single = dst[0]
+        if single is None:
+            # A length-1 group with a None slot is a no-op rather than
+            # an error: it lets callers pass-through groups uniformly
+            # even when they have already decided not to materialize
+            # the only output.
+            return
+        self._inner.deserialize(src, single)
+
+
+def single_to_multi_serializer(inner: Serializer) -> MultiSerializer:
+    """Wrap a single-tensor :class:`Serializer` as a length-1
+    :class:`MultiSerializer`.
+
+    The wrapper is layout-equivalent: identical bytes are written to
+    ``dst`` for the same input as a direct call to ``inner.serialize``.
+    """
+    return _SingleAsMultiSerializer(inner)
+
+
+def single_to_multi_deserializer(inner: Deserializer) -> MultiDeserializer:
+    """Wrap a single-tensor :class:`Deserializer` as a length-1
+    :class:`MultiDeserializer`.
+
+    The wrapper is layout-equivalent: identical bytes are written to
+    the dst tensor for the same input as a direct call to
+    ``inner.deserialize``. A length-1 group whose only slot is
+    ``None`` is treated as a deliberate skip rather than an error.
+    """
+    return _SingleAsMultiDeserializer(inner)
+
+
+def validate_group_size(
+    group: Sequence[object],
+    expected: int,
+    *,
+    role: str,
+) -> None:
+    """Validation helper used by callers and implementations alike.
+
+    Pure arity check: the element type is irrelevant, so ``group`` is
+    typed ``Sequence[object]`` to accept both a ``MemoryObjGroup`` and a
+    ``LayoutDescGroup`` (``role`` may be "src", "dst", or "layout").
+
+    Raises ``ValueError`` if ``group`` is not exactly ``expected``
+    long. ``role`` appears in the error message so test failures and
+    runtime errors point at the offending side.
+    """
+    if len(group) != expected:
+        raise ValueError(
+            f"MultiSerde {role} group length {len(group)} does not "
+            f"match expected {expected}"
+        )
diff --git a/lmcache/v1/distributed/serde/turboquant/__init__.py b/lmcache/v1/distributed/serde/turboquant/__init__.py
new file mode 100644
index 0000000..e04241e
--- /dev/null
+++ b/lmcache/v1/distributed/serde/turboquant/__init__.py
@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+"""TurboQuant serde backend."""
+
+# First Party
+from lmcache.v1.distributed.serde.turboquant.turboquant import (
+    TurboQuantDeserializer,
+    TurboQuantSerdeConfig,
+    TurboQuantSerializer,
+)
+
+__all__ = [
+    "TurboQuantDeserializer",
+    "TurboQuantSerdeConfig",
+    "TurboQuantSerializer",
+]
diff --git a/lmcache/v1/distributed/serde/turboquant/decode_kernel.py b/lmcache/v1/distributed/serde/turboquant/decode_kernel.py
new file mode 100644
index 0000000..9409bf3
--- /dev/null
+++ b/lmcache/v1/distributed/serde/turboquant/decode_kernel.py
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Triton fused TurboQuant decode attention.
+
+Decode path: Triton stage1 (split-KV tiled attention scoring + value
+accumulation) + stage2 (log-sum-exp reduction across splits).
+
+Supports FP8 (E4M3) keys, 3-bit and 4-bit uniform quantized values.
+"""
+
+# Standard
+
+# Third Party
+import triton
+import triton.language as tl
+
+# First Party
+from lmcache import torch_dev
+
+_FP8_E4B15: dict[int, int] = {}
+
+
+def _use_fp8_e4b15(device: int = 0) -> int:
+    """Return 1 if device needs fp8e4b15 (Ampere/Ada, SM < 8.9), else 0."""
+    if device not in _FP8_E4B15:
+        cap = torch_dev.get_device_capability(device)
+        _FP8_E4B15[device] = 1 if cap < (8, 9) else 0
+    return _FP8_E4B15[device]
+
+
+# ---------------------------------------------------------------------------
+# Pre-dequant kernel: Bulk dequant K (MSE+norms) and V to fp16
+# ---------------------------------------------------------------------------
+
+
+@triton.jit
+def _tq_full_dequant_kv(
+    KV_cache_ptr,
+    Block_table_ptr,
+    Centroids_ptr,
+    K_out_ptr,  # [B, Hk, max_seq, D] float16
+    V_out_ptr,  # [B, Hk, max_seq, D] float16
+    stride_ko_b,
+    stride_ko_h,
+    stride_ko_s,
+    stride_vo_b,
+    stride_vo_h,
+    stride_vo_s,
+    stride_cache_block,
+    stride_cache_pos,
+    stride_cache_head,
+    stride_bt_b,
+    HEAD_DIM: tl.constexpr,
+    BLOCK_SIZE: tl.constexpr,
+    NUM_KV_HEADS: tl.constexpr,
+    MSE_BYTES: tl.constexpr,
+    KPS: tl.constexpr,
+    VQB: tl.constexpr,
+    VAL_DATA_BYTES: tl.constexpr,
+    MSE_BITS: tl.constexpr,
+    KEY_FP8: tl.constexpr,
+    BLOCK_D: tl.constexpr,
+    NORM_CORRECTION: tl.constexpr = 0,
+    FP8_E4B15: tl.constexpr = 0,  # 1 = use e4b15 (Ampere/Ada), 0 = e4nv (Hopper+)
+):
+    """Full dequant: reconstruct K (MSE centroids * norm or FP8) and V to fp16."""
+    pos = tl.program_id(0)
+    bh = tl.program_id(1)
+    bid = bh // NUM_KV_HEADS
+    hid = bh % NUM_KV_HEADS
+
+    page_idx = pos // BLOCK_SIZE
+    page_off = pos % BLOCK_SIZE
+    block_num = tl.load(Block_table_ptr + bid * stride_bt_b + page_idx)
+    slot_base = (
+        block_num * stride_cache_block
+        + page_off * stride_cache_pos
+        + hid * stride_cache_head
+    )
+
+    d_offs = tl.arange(0, BLOCK_D)
+    d_mask = d_offs < HEAD_DIM
+
+    # === K dequant ===
+    ko_base = bid * stride_ko_b + hid * stride_ko_h + pos * stride_ko_s
+    if KEY_FP8:
+        k_raw = tl.load(KV_cache_ptr + slot_base + d_offs, mask=d_mask, other=0)
+        if FP8_E4B15:
+            k_recon = k_raw.to(tl.float8e4b15, bitcast=True).to(tl.float32)
+        else:
+            k_recon = k_raw.to(tl.float8e4nv, bitcast=True).to(tl.float32)
+        tl.store(K_out_ptr + ko_base + d_offs, k_recon.to(tl.float16), mask=d_mask)
+    else:
+        # MSE unpack (3-bit or 4-bit) + norms
+        mse_bit_off = d_offs * MSE_BITS
+        mse_byte_idx = mse_bit_off // 8
+        mse_bit_shift = mse_bit_off % 8
+        mse_umask = (1 << MSE_BITS) - 1
+
+        mse_raw0 = tl.load(
+            KV_cache_ptr + slot_base + mse_byte_idx, mask=d_mask, other=0
+        ).to(tl.int32)
+        mse_raw1 = tl.load(
+            KV_cache_ptr + slot_base + mse_byte_idx + 1, mask=d_mask, other=0
+        ).to(tl.int32)
+        raw16_key = mse_raw0 | (mse_raw1 << 8)
+        mse_idx = (raw16_key >> mse_bit_shift) & mse_umask
+
+        k_mse = tl.load(Centroids_ptr + mse_idx, mask=d_mask, other=0.0)
+
+        # Norm correction: re-normalize centroid vector to unit norm
+        if NORM_CORRECTION:
+            c_norm_sq = tl.sum(tl.where(d_mask, k_mse * k_mse, 0.0), axis=0)
+            c_inv_norm = 1.0 / tl.sqrt(c_norm_sq + 1e-16)
+            k_mse = k_mse * c_inv_norm
+
+        # Norms at MSE_BYTES offset (no QJL bytes)
+        norm_base = slot_base + MSE_BYTES
+        n_lo = tl.load(KV_cache_ptr + norm_base).to(tl.uint16)
+        n_hi = tl.load(KV_cache_ptr + norm_base + 1).to(tl.uint16)
+        vec_norm = (n_lo | (n_hi << 8)).to(tl.float16, bitcast=True).to(tl.float32)
+
+        k_recon = vec_norm * k_mse
+        tl.store(K_out_ptr + ko_base + d_offs, k_recon.to(tl.float16), mask=d_mask)
+
+    # === V dequant ===
+    val_base = slot_base + KPS
+    if VQB == 4:
+        vb_idx = d_offs // 2
+        vb_shift = (d_offs % 2) * 4
+        val_raw = tl.load(KV_cache_ptr + val_base + vb_idx, mask=d_mask, other=0).to(
+            tl.int32
+        )
+        v_idx = ((val_raw >> vb_shift) & 0xF).to(tl.float32)
+
+        sc_base = val_base + VAL_DATA_BYTES
+        sc_lo = tl.load(KV_cache_ptr + sc_base).to(tl.uint16)
+        sc_hi = tl.load(KV_cache_ptr + sc_base + 1).to(tl.uint16)
+        v_scale = (sc_lo | (sc_hi << 8)).to(tl.float16, bitcast=True).to(tl.float32)
+        zr_lo = tl.load(KV_cache_ptr + sc_base + 2).to(tl.uint16)
+        zr_hi = tl.load(KV_cache_ptr + sc_base + 3).to(tl.uint16)
+        v_zero = (zr_lo | (zr_hi << 8)).to(tl.float16, bitcast=True).to(tl.float32)
+        v_vals = v_idx * v_scale + v_zero
+    elif VQB == 3:
+        # 3-bit value unpack: 8 values per 3 bytes
+        val_bit_off = d_offs * 3
+        val_byte_idx = val_bit_off // 8
+        val_bit_shift = val_bit_off % 8
+        val_raw0 = tl.load(
+            KV_cache_ptr + val_base + val_byte_idx, mask=d_mask, other=0
+        ).to(tl.int32)
+        val_raw1 = tl.load(
+            KV_cache_ptr + val_base + val_byte_idx + 1, mask=d_mask, other=0
+        ).to(tl.int32)
+        raw16_val = val_raw0 | (val_raw1 << 8)
+        v_idx = ((raw16_val >> val_bit_shift) & 0x7).to(tl.float32)
+
+        sc_base = val_base + VAL_DATA_BYTES
+        sc_lo = tl.load(KV_cache_ptr + sc_base).to(tl.uint16)
+        sc_hi = tl.load(KV_cache_ptr + sc_base + 1).to(tl.uint16)
+        v_scale = (sc_lo | (sc_hi << 8)).to(tl.float16, bitcast=True).to(tl.float32)
+        zr_lo = tl.load(KV_cache_ptr + sc_base + 2).to(tl.uint16)
+        zr_hi = tl.load(KV_cache_ptr + sc_base + 3).to(tl.uint16)
+        v_zero = (zr_lo | (zr_hi << 8)).to(tl.float16, bitcast=True).to(tl.float32)
+        v_vals = v_idx * v_scale + v_zero
+    else:
+        v_vals = tl.zeros([BLOCK_D], dtype=tl.float32)
+
+    vo_base = bid * stride_vo_b + hid * stride_vo_h + pos * stride_vo_s
+    tl.store(V_out_ptr + vo_base + d_offs, v_vals.to(tl.float16), mask=d_mask)
+
+
+# ---------------------------------------------------------------------------
diff --git a/lmcache/v1/distributed/serde/turboquant/store_kernel.py b/lmcache/v1/distributed/serde/turboquant/store_kernel.py
new file mode 100644
index 0000000..77cd353
--- /dev/null
+++ b/lmcache/v1/distributed/serde/turboquant/store_kernel.py
@@ -0,0 +1,445 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Fused Triton kernels for TurboQuant KV store.
+
+Two kernels:
+1. _tq_fused_store_fp8: FP8 key scatter + value uniform quantization.
+2. _tq_fused_store_mse: Fused binary-search bucketize + MSE index
+   packing + value quantization.
+
+The launcher `triton_turboquant_store` selects the appropriate kernel.
+"""
+
+# Standard
+import math
+
+# Third Party
+import torch
+import triton
+import triton.language as tl
+
+# First Party
+from lmcache.v1.distributed.serde.turboquant.decode_kernel import _use_fp8_e4b15
+
+# ═══════════════════════════════════════════════════════════════════════
+# Shared: value uniform quantization + pack + scale/zero store
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@triton.jit
+def _store_quantized_value(
+    Value_ptr,
+    KV_cache_ptr,
+    base,  # pid * D offset into Value_ptr
+    slot_base,  # byte offset into KV_cache_ptr for this slot+head
+    d_offs,  # tl.arange(0, BLOCK_D)
+    d_mask,  # d_offs < D
+    D: tl.constexpr,
+    KPS: tl.constexpr,
+    VQB: tl.constexpr,
+    VAL_DATA_BYTES: tl.constexpr,
+    BLOCK_D: tl.constexpr,
+    BLOCK_VAL: tl.constexpr,
+    BLOCK_GRP: tl.constexpr,
+):
+    """Uniform quantization of values to VQB bits, pack, and store with scale/zero."""
+    val_cache_offset = KPS
+
+    if VQB == 3:
+        val_vec = tl.load(Value_ptr + base + d_offs, mask=d_mask, other=0.0).to(
+            tl.float32
+        )
+        val_min = tl.min(tl.where(d_mask, val_vec, float("inf")), axis=0)
+        val_max = tl.max(tl.where(d_mask, val_vec, -float("inf")), axis=0)
+        v_scale = (val_max - val_min) / 7.0
+        v_scale = tl.where(v_scale > 1e-8, v_scale, 1e-8)
+
+        q_vals = tl.minimum(
+            tl.maximum(((val_vec - val_min) / v_scale + 0.5).to(tl.int32), 0), 7
+        )
+
+        grp_offs = tl.arange(0, BLOCK_GRP)
+        grp_mask = grp_offs < (D // 8)
+        q_grp = tl.reshape(q_vals, [BLOCK_GRP, 8])
+        shifts_3bit = tl.arange(0, 8) * 3
+        packed_24 = tl.sum(q_grp << shifts_3bit[None, :], axis=1)
+        b0 = (packed_24 & 0xFF).to(tl.uint8)
+        b1 = ((packed_24 >> 8) & 0xFF).to(tl.uint8)
+        b2 = ((packed_24 >> 16) & 0xFF).to(tl.uint8)
+        tl.store(
+            KV_cache_ptr + slot_base + val_cache_offset + grp_offs * 3,
+            b0,
+            mask=grp_mask,
+        )
+        tl.store(
+            KV_cache_ptr + slot_base + val_cache_offset + grp_offs * 3 + 1,
+            b1,
+            mask=grp_mask,
+        )
+        tl.store(
+            KV_cache_ptr + slot_base + val_cache_offset + grp_offs * 3 + 2,
+            b2,
+            mask=grp_mask,
+        )
+
+        sc_offset = val_cache_offset + VAL_DATA_BYTES
+        sc_f16 = v_scale.to(tl.float16)
+        sc_u16 = sc_f16.to(tl.uint16, bitcast=True)
+        tl.store(KV_cache_ptr + slot_base + sc_offset, (sc_u16 & 0xFF).to(tl.uint8))
+        tl.store(
+            KV_cache_ptr + slot_base + sc_offset + 1,
+            ((sc_u16 >> 8) & 0xFF).to(tl.uint8),
+        )
+        zr_f16 = val_min.to(tl.float16)
+        zr_u16 = zr_f16.to(tl.uint16, bitcast=True)
+        tl.store(KV_cache_ptr + slot_base + sc_offset + 2, (zr_u16 & 0xFF).to(tl.uint8))
+        tl.store(
+            KV_cache_ptr + slot_base + sc_offset + 3,
+            ((zr_u16 >> 8) & 0xFF).to(tl.uint8),
+        )
+
+    else:  # VQB == 4
+        val_vec = tl.load(Value_ptr + base + d_offs, mask=d_mask, other=0.0).to(
+            tl.float32
+        )
+        val_min = tl.min(tl.where(d_mask, val_vec, float("inf")), axis=0)
+        val_max = tl.max(tl.where(d_mask, val_vec, -float("inf")), axis=0)
+        v_scale = (val_max - val_min) / 15.0
+        v_scale = tl.where(v_scale > 1e-8, v_scale, 1e-8)
+
+        # Quantize all D elements from register (no re-load)
+        q_all = tl.minimum(
+            tl.maximum(((val_vec - val_min) / v_scale + 0.5).to(tl.int32), 0), 15
+        )
+        # Reshape to pairs and pack two 4-bit values per byte
+        q_pairs = tl.reshape(q_all, [BLOCK_D // 2, 2])
+        shifts_4 = tl.arange(0, 2) * 4
+        packed_val = tl.sum((q_pairs & 0xF) << shifts_4[None, :], axis=1).to(tl.uint8)
+        val_offs = tl.arange(0, BLOCK_D // 2)
+        val_mask = val_offs < VAL_DATA_BYTES
+        tl.store(
+            KV_cache_ptr + slot_base + val_cache_offset + val_offs,
+            packed_val,
+            mask=val_mask,
+        )
+
+        sc_offset = val_cache_offset + VAL_DATA_BYTES
+        sc_f16 = v_scale.to(tl.float16)
+        sc_u16 = sc_f16.to(tl.uint16, bitcast=True)
+        tl.store(KV_cache_ptr + slot_base + sc_offset, (sc_u16 & 0xFF).to(tl.uint8))
+        tl.store(
+            KV_cache_ptr + slot_base + sc_offset + 1,
+            ((sc_u16 >> 8) & 0xFF).to(tl.uint8),
+        )
+        zr_f16 = val_min.to(tl.float16)
+        zr_u16 = zr_f16.to(tl.uint16, bitcast=True)
+        tl.store(KV_cache_ptr + slot_base + sc_offset + 2, (zr_u16 & 0xFF).to(tl.uint8))
+        tl.store(
+            KV_cache_ptr + slot_base + sc_offset + 3,
+            ((zr_u16 >> 8) & 0xFF).to(tl.uint8),
+        )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# FP8 key store + value uniform quantization
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@triton.jit
+def _tq_fused_store_fp8(
+    Key_ptr,  # [NH, D] float16/bfloat16 — raw keys
+    Value_ptr,  # [NH, D] float16/bfloat16 — raw values
+    KV_cache_ptr,  # [total_bytes] uint8 (flattened view)
+    Slot_mapping_ptr,  # [N] int32 — per-token slot indices
+    # Cache strides (for computing byte offsets)
+    stride_cache_block: tl.constexpr,
+    stride_cache_pos: tl.constexpr,
+    stride_cache_head: tl.constexpr,
+    # Dimensions
+    D: tl.constexpr,
+    H: tl.constexpr,
+    BLOCK_SIZE: tl.constexpr,
+    BLOCK_D: tl.constexpr,
+    # TQ layout
+    KPS: tl.constexpr,
+    # Value quantization
+    VQB: tl.constexpr,
+    VAL_DATA_BYTES: tl.constexpr,
+    # Packing block sizes
+    BLOCK_VAL: tl.constexpr,
+    BLOCK_GRP: tl.constexpr = 16,
+    FP8_E4B15: tl.constexpr = 0,  # 1 = e4b15 (Ampere/Ada), 0 = e4nv (Hopper+)
+):
+    """FP8 key cast+scatter + value uniform quantization."""
+    pid = tl.program_id(0)
+    token_idx = pid // H
+    head_idx = pid % H
+
+    slot = tl.load(Slot_mapping_ptr + token_idx)
+    if slot < 0:
+        return
+    blk = slot // BLOCK_SIZE
+    off = slot % BLOCK_SIZE
+    slot_base = (
+        blk * stride_cache_block + off * stride_cache_pos + head_idx * stride_cache_head
+    )
+
+    base = pid * D
+
+    # ── FP8 KEY: cast to FP8 in-kernel and store ─────────────────
+    d_offs = tl.arange(0, BLOCK_D)
+    d_mask = d_offs < D
+    k_vals = tl.load(Key_ptr + base + d_offs, mask=d_mask, other=0.0)
+    k_fp8 = k_vals.to(tl.float8e4b15) if FP8_E4B15 else k_vals.to(tl.float8e4nv)
+    k_bytes = k_fp8.to(tl.uint8, bitcast=True)
+    tl.store(KV_cache_ptr + slot_base + d_offs, k_bytes, mask=d_mask)
+
+    # ── VALUE QUANTIZE + PACK ───────────────────────────────────────
+    _store_quantized_value(
+        Value_ptr,
+        KV_cache_ptr,
+        base,
+        slot_base,
+        d_offs,
+        d_mask,
+        D=D,
+        KPS=KPS,
+        VQB=VQB,
+        VAL_DATA_BYTES=VAL_DATA_BYTES,
+        BLOCK_D=BLOCK_D,
+        BLOCK_VAL=BLOCK_VAL,
+        BLOCK_GRP=BLOCK_GRP,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Fused MSE store: bucketize + MSE index pack + norm store + value pack
+# (eliminates 4 PyTorch kernel launches per layer vs pack-only kernel)
+# ═══════════════════════════════════════════════════════════════════════
+
+
+@triton.jit
+def _tq_fused_store_mse(
+    # Post-rotation inputs
+    Y_ptr,  # [NH, D] float32 — rotated normalized keys (x_hat @ PiT)
+    Norms_ptr,  # [NH] float32 — key vector norms (||k||)
+    Value_ptr,  # [NH, D] float32 — raw values
+    # Quantization tables
+    Midpoints_ptr,  # [n_centroids-1] float32
+    # Cache and indexing
+    KV_cache_ptr,  # [total_bytes] uint8 (flattened view)
+    Slot_mapping_ptr,  # [N] int32 — per-token slot indices
+    # Cache strides
+    stride_cache_block: tl.constexpr,
+    stride_cache_pos: tl.constexpr,
+    stride_cache_head: tl.constexpr,
+    # Dimensions
+    D: tl.constexpr,
+    H: tl.constexpr,
+    BLOCK_SIZE: tl.constexpr,
+    BLOCK_D: tl.constexpr,
+    # TQ layout
+    MSE_BYTES: tl.constexpr,
+    KPS: tl.constexpr,
+    # Value quantization
+    VQB: tl.constexpr,
+    VAL_DATA_BYTES: tl.constexpr,
+    # Packing block sizes
+    BLOCK_VAL: tl.constexpr,
+    # MSE params
+    MSE_BITS: tl.constexpr,
+    N_CENTROIDS: tl.constexpr,
+    BLOCK_GRP: tl.constexpr = 16,
+):
+    """Fused MSE quantize + pack + store.
+
+    Performs binary-search bucketize, MSE index packing, norm storage,
+    and value quantization in one kernel.
+    """
+    pid = tl.program_id(0)
+    token_idx = pid // H
+    head_idx = pid % H
+
+    slot = tl.load(Slot_mapping_ptr + token_idx)
+    if slot < 0:
+        return
+    blk = slot // BLOCK_SIZE
+    off = slot % BLOCK_SIZE
+    slot_base = (
+        blk * stride_cache_block + off * stride_cache_pos + head_idx * stride_cache_head
+    )
+
+    base = pid * D
+    d_offs = tl.arange(0, BLOCK_D)
+    d_mask = d_offs < D
+
+    # ── 1. BINARY SEARCH BUCKETIZE ───────────────────────────────────
+    # Midpoints are sorted (N_CENTROIDS-1 values); binary search finds
+    # insertion point in MSE_BITS iterations vs N_CENTROIDS-1 for linear.
+    y_vec = tl.load(Y_ptr + base + d_offs, mask=d_mask, other=0.0)
+    lo = tl.zeros([BLOCK_D], dtype=tl.int32)
+    hi = tl.full([BLOCK_D], N_CENTROIDS - 1, dtype=tl.int32)
+    for _ in range(MSE_BITS):
+        mid = (lo + hi) >> 1
+        # Clamp to valid midpoint index [0, N_CENTROIDS-2] for load safety;
+        # the search result (lo) is still correct since converged lanes
+        # don't change.
+        safe_mid = tl.minimum(mid, N_CENTROIDS - 2)
+        mid_val = tl.load(Midpoints_ptr + safe_mid, mask=d_mask, other=0.0)
+        lo = tl.where(y_vec >= mid_val, mid + 1, lo)
+        hi = tl.where(y_vec >= mid_val, hi, mid)
+    idx = tl.minimum(lo, N_CENTROIDS - 1)
+
+    # ── 2. PACK MSE INDICES from register idx ─────────────────────────
+    if MSE_BITS == 4:
+        idx_pairs = tl.reshape(idx, [BLOCK_D // 2, 2])
+        shifts_4 = tl.arange(0, 2) * 4
+        packed = tl.sum((idx_pairs & 0xF) << shifts_4[None, :], axis=1).to(tl.uint8)
+        mse_offs = tl.arange(0, BLOCK_D // 2)
+        mse_mask = mse_offs < MSE_BYTES
+        tl.store(KV_cache_ptr + slot_base + mse_offs, packed, mask=mse_mask)
+
+    elif MSE_BITS == 3:
+        grp_offs = tl.arange(0, BLOCK_GRP)
+        grp_mask = grp_offs < (D // 8)
+        idx_grp = tl.reshape(idx, [BLOCK_GRP, 8])
+        shifts_3 = tl.arange(0, 8) * 3
+        packed_24 = tl.sum((idx_grp & 0x7) << shifts_3[None, :], axis=1)
+        b0 = (packed_24 & 0xFF).to(tl.uint8)
+        b1 = ((packed_24 >> 8) & 0xFF).to(tl.uint8)
+        b2 = ((packed_24 >> 16) & 0xFF).to(tl.uint8)
+        tl.store(KV_cache_ptr + slot_base + grp_offs * 3, b0, mask=grp_mask)
+        tl.store(KV_cache_ptr + slot_base + grp_offs * 3 + 1, b1, mask=grp_mask)
+        tl.store(KV_cache_ptr + slot_base + grp_offs * 3 + 2, b2, mask=grp_mask)
+
+    # ── 3. STORE vec_norm (fp16, 2 bytes) ─────────────────────────────
+    norm_offset = MSE_BYTES
+
+    vn_f16 = tl.load(Norms_ptr + pid).to(tl.float16)
+    vn_u16 = vn_f16.to(tl.uint16, bitcast=True)
+    tl.store(KV_cache_ptr + slot_base + norm_offset, (vn_u16 & 0xFF).to(tl.uint8))
+    tl.store(
+        KV_cache_ptr + slot_base + norm_offset + 1, ((vn_u16 >> 8) & 0xFF).to(tl.uint8)
+    )
+
+    # ── 4. VALUE QUANTIZE + PACK ──────────────────────────────────────
+    _store_quantized_value(
+        Value_ptr,
+        KV_cache_ptr,
+        base,
+        slot_base,
+        d_offs,
+        d_mask,
+        D=D,
+        KPS=KPS,
+        VQB=VQB,
+        VAL_DATA_BYTES=VAL_DATA_BYTES,
+        BLOCK_D=BLOCK_D,
+        BLOCK_VAL=BLOCK_VAL,
+        BLOCK_GRP=BLOCK_GRP,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Launcher
+# ═══════════════════════════════════════════════════════════════════════
+
+
+def triton_turboquant_store(
+    key: torch.Tensor,  # [N, H, D] — raw keys (post-RoPE)
+    value: torch.Tensor,  # [N, H, D] — raw values
+    kv_cache: torch.Tensor,  # [num_blocks, block_size, Hk, padded_slot] uint8
+    slot_mapping: torch.Tensor,  # [N] int32
+    PiT: torch.Tensor,  # [D, D] float32
+    midpoints: torch.Tensor,  # [n_centroids-1] float32
+    mse_bits: int,
+    key_packed_size: int,
+    value_quant_bits: int,
+    key_fp8: bool = False,
+):
+    """Launch TQ store kernel (FP8 or MSE path)."""
+    N, H, D = key.shape
+    NH = N * H
+    block_size = kv_cache.shape[1]
+    BLOCK_D = triton.next_power_of_2(D)
+    mse_bytes = math.ceil(D * mse_bits / 8)
+    n_centroids = 2**mse_bits
+
+    val_data_bytes = math.ceil(D * value_quant_bits / 8)
+
+    BLOCK_VAL = triton.next_power_of_2(val_data_bytes)
+
+    # Cache strides (element_size=1 for uint8, so stride in bytes = stride())
+    stride_block = kv_cache.stride(0)
+    stride_pos = kv_cache.stride(1)
+    stride_head = kv_cache.stride(2)
+
+    block_grp = triton.next_power_of_2(D // 8) if D >= 8 else 1
+
+    # ── FP8 PATH: in-kernel FP8 cast + scatter via fp8 kernel ──
+    if key_fp8:
+        k_flat = key.reshape(NH, D).contiguous()
+        v_flat = value.reshape(NH, D).contiguous()
+
+        fp8_e4b15 = _use_fp8_e4b15(key.device.index or 0)
+
+        grid = (NH,)
+        _tq_fused_store_fp8[grid](
+            k_flat,
+            v_flat,
+            kv_cache.view(-1),
+            slot_mapping,
+            stride_cache_block=stride_block,
+            stride_cache_pos=stride_pos,
+            stride_cache_head=stride_head,
+            D=D,
+            H=H,
+            BLOCK_SIZE=block_size,
+            BLOCK_D=BLOCK_D,
+            KPS=key_packed_size,
+            VQB=value_quant_bits,
+            VAL_DATA_BYTES=val_data_bytes,
+            BLOCK_VAL=BLOCK_VAL,
+            BLOCK_GRP=block_grp,
+            FP8_E4B15=fp8_e4b15,
+            num_warps=4,
+            num_stages=1,
+        )
+        return
+
+    # ── MSE PATH: external GEMM + fused bucketize/pack kernel ──
+    # Normalize + rotation GEMM externally (cuBLAS is faster than in-kernel)
+    k_flat = key.float().reshape(NH, D)
+    norms = k_flat.norm(dim=1, keepdim=True)
+    x_hat = k_flat / (norms + 1e-8)
+    y = x_hat @ PiT
+
+    v_flat = value.float().reshape(NH, D)
+
+    # Fused kernel: bucketize + MSE index pack + norm store + value pack
+    grid = (NH,)
+    _tq_fused_store_mse[grid](
+        y,
+        norms.squeeze(1),
+        v_flat,
+        midpoints,
+        kv_cache.view(-1),
+        slot_mapping,
+        stride_cache_block=stride_block,
+        stride_cache_pos=stride_pos,
+        stride_cache_head=stride_head,
+        D=D,
+        H=H,
+        BLOCK_SIZE=block_size,
+        BLOCK_D=BLOCK_D,
+        MSE_BYTES=mse_bytes,
+        KPS=key_packed_size,
+        VQB=value_quant_bits,
+        VAL_DATA_BYTES=val_data_bytes,
+        BLOCK_VAL=BLOCK_VAL,
+        MSE_BITS=mse_bits,
+        N_CENTROIDS=n_centroids,
+        BLOCK_GRP=block_grp,
+        num_warps=4,
+        num_stages=1,
+    )
diff --git a/lmcache/v1/distributed/serde/turboquant/turboquant.py b/lmcache/v1/distributed/serde/turboquant/turboquant.py
new file mode 100644
index 0000000..d41a37d
--- /dev/null
+++ b/lmcache/v1/distributed/serde/turboquant/turboquant.py
@@ -0,0 +1,896 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+TurboQuant serde backend for LMCache.
+
+This backend is intended to compress LMCache KV tensors before L2 store and
+decompress them after L2 load.
+
+Supported presets:
+- turboquant_k8v4
+- turboquant_4bit_nc
+- turboquant_k3v4_nc
+- turboquant_3bit_nc
+
+Input KV layout: [2, num_layers, num_tokens, hidden_dim]
+Serialized layout: [num_layers, num_blocks, block_size, num_heads, slot_size]
+"""
+
+# Standard
+from dataclasses import dataclass
+from functools import lru_cache
+import math
+import subprocess
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.async_processor import AsyncSerdeProcessor
+from lmcache.v1.distributed.serde.base import Deserializer, SerdeProcessor, Serializer
+from lmcache.v1.distributed.serde.factory import register_serde_factory
+from lmcache.v1.memory_management import MemoryObj
+
+TQ_PRESETS: dict[str, dict[str, object]] = {
+    "turboquant_k8v4": {
+        "key_quant_bits": 8,
+        "value_quant_bits": 4,
+        "norm_correction": False,
+    },
+    "turboquant_4bit_nc": {
+        "key_quant_bits": 4,
+        "value_quant_bits": 4,
+        "norm_correction": True,
+    },
+    "turboquant_k3v4_nc": {
+        "key_quant_bits": 3,
+        "value_quant_bits": 4,
+        "norm_correction": True,
+    },
+    "turboquant_3bit_nc": {
+        "key_quant_bits": 3,
+        "value_quant_bits": 3,
+        "norm_correction": True,
+    },
+}
+
+_TQ_LAYER_SEED_STRIDE = 1337
+
+
+@dataclass(frozen=True)
+class TurboQuantSerdeConfig:
+    """Configuration for TurboQuant serde.
+
+    Args:
+        preset: TurboQuant compression preset.
+        head_dim: Per-head hidden dimension.
+        block_size: Token block size used by the compressed layout.
+        skip_first_layers: Number of leading layers stored without quantization.
+        skip_last_layers: Number of trailing layers stored without quantization.
+        cuda_device: CUDA staging device used when both source and destination
+            tensors are CPU tensors. Empty string means automatically select a
+            CUDA device with sufficient free memory and the lowest GPU
+            utilization.
+    """
+
+    preset: str = "turboquant_k8v4"
+    head_dim: int = 128
+    block_size: int = 16
+    skip_first_layers: int = 2
+    skip_last_layers: int = 2
+    cuda_device: str = ""
+
+    def __post_init__(self) -> None:
+        if self.skip_first_layers < 0 or self.skip_last_layers < 0:
+            raise ValueError("TurboQuant skipped layer counts must be non-negative")
+
+    @property
+    def _preset_config(self) -> dict[str, object]:
+        if self.preset not in TQ_PRESETS:
+            valid = ", ".join(TQ_PRESETS)
+            raise ValueError(
+                f"Unsupported TurboQuant preset: {self.preset!r}. "
+                f"Valid presets: {valid}"
+            )
+        return TQ_PRESETS[self.preset]
+
+    @property
+    def key_quant_bits(self) -> int:
+        return int(self._preset_config["key_quant_bits"])  # type: ignore[call-overload]
+
+    @property
+    def key_fp8(self) -> bool:
+        return self.key_quant_bits == 8
+
+    @property
+    def key_mse_bits(self) -> int:
+        if self.key_fp8:
+            return 0
+        return self.key_quant_bits
+
+    @property
+    def value_quant_bits(self) -> int:
+        return int(self._preset_config["value_quant_bits"])  # type: ignore[call-overload]
+
+    @property
+    def effective_value_quant_bits(self) -> int:
+        return self.value_quant_bits
+
+    @property
+    def norm_correction(self) -> bool:
+        return bool(self._preset_config["norm_correction"])
+
+    @property
+    def mse_bits(self) -> int:
+        if self.key_fp8:
+            return self.value_quant_bits
+        return self.key_quant_bits
+
+    @property
+    def centroid_bits(self) -> int:
+        return self.mse_bits
+
+    @property
+    def n_centroids(self) -> int:
+        return 2**self.mse_bits
+
+    @property
+    def key_packed_size(self) -> int:
+        if self.key_fp8:
+            return self.head_dim
+        mse_bytes = math.ceil(self.head_dim * self.key_mse_bits / 8)
+        norm_bytes = 2
+        return mse_bytes + norm_bytes
+
+    @property
+    def value_packed_size(self) -> int:
+        data_bytes = math.ceil(self.head_dim * self.value_quant_bits / 8)
+        return data_bytes + 4  # scale fp16 + zero fp16
+
+    @property
+    def slot_size(self) -> int:
+        return self.key_packed_size + self.value_packed_size
+
+    @property
+    def slot_size_aligned(self) -> int:
+        s = self.slot_size
+        return s + (s % 2)
+
+
+def _validate_layout_shape(
+    shape: torch.Size, cfg: TurboQuantSerdeConfig
+) -> tuple[int, int, int, int]:
+    """Validate LMCache KV layout and return L, T, H, D.
+
+    Expected input shape:
+        [2, num_layers, num_tokens, hidden_dim]
+
+    Returns:
+        num_layers, num_tokens, num_heads, head_dim
+    """
+    if len(shape) != 4:
+        raise ValueError(
+            "TurboQuant serde expects 4D KV tensor "
+            f"[2, L, T, hidden_dim], got {tuple(shape)}"
+        )
+    if int(shape[0]) != 2:
+        raise ValueError(
+            f"TurboQuant serde expects first dim kv_size=2, got {int(shape[0])}"
+        )
+
+    num_layers = int(shape[1])
+    num_tokens = int(shape[2])
+    hidden_dim = int(shape[3])
+    head_dim = cfg.head_dim
+
+    if hidden_dim % head_dim != 0:
+        raise ValueError(
+            f"hidden_dim={hidden_dim} must be divisible by head_dim={head_dim}"
+        )
+
+    num_heads = hidden_dim // head_dim
+    return num_layers, num_tokens, num_heads, head_dim
+
+
+def _layer_ranges(num_layers: int, cfg: TurboQuantSerdeConfig) -> tuple[int, int]:
+    """Return the half-open range of layers compressed with TurboQuant."""
+    quant_start = min(cfg.skip_first_layers, num_layers)
+    quant_end = max(quant_start, num_layers - cfg.skip_last_layers)
+    return quant_start, quant_end
+
+
+def _raw_group_nbytes(
+    shape: torch.Size,
+    dtype: torch.dtype,
+    num_layers: int,
+) -> int:
+    _, _, num_tokens, hidden_dim = shape
+    return (
+        2
+        * num_layers
+        * int(num_tokens)
+        * int(hidden_dim)
+        * torch.empty((), dtype=dtype).element_size()
+    )
+
+
+def _serialized_nbytes_for_shape(
+    shape: torch.Size,
+    dtype: torch.dtype,
+    cfg: TurboQuantSerdeConfig,
+) -> int:
+    """Return serialized size in bytes for one LMCache KV tensor."""
+    num_layers, num_tokens, num_heads, _ = _validate_layout_shape(shape, cfg)
+    num_blocks = math.ceil(num_tokens / cfg.block_size)
+    quant_start, quant_end = _layer_ranges(num_layers, cfg)
+    quant_layers = quant_end - quant_start
+    raw_layers = num_layers - quant_layers
+    return _raw_group_nbytes(shape, dtype, raw_layers) + (
+        quant_layers * num_blocks * cfg.block_size * num_heads * cfg.slot_size_aligned
+    )
+
+
+def _compressed_layout_for_shape(
+    shape: torch.Size,
+    cfg: TurboQuantSerdeConfig,
+    num_layers: int | None = None,
+) -> tuple[int, int, int, int, int]:
+    """Return compressed layout [L, num_blocks, block_size, H, slot_size]."""
+    total_layers, num_tokens, num_heads, _ = _validate_layout_shape(shape, cfg)
+    if num_layers is None:
+        num_layers = total_layers
+    num_blocks = math.ceil(num_tokens / cfg.block_size)
+    return (
+        num_layers,
+        num_blocks,
+        cfg.block_size,
+        num_heads,
+        cfg.slot_size_aligned,
+    )
+
+
+def _make_slot_mapping(num_tokens: int, device: torch.device) -> torch.Tensor:
+    """Sequential slot mapping: token i -> slot i."""
+    return torch.arange(num_tokens, device=device, dtype=torch.int32)
+
+
+def _make_block_table(num_blocks: int, device: torch.device) -> torch.Tensor:
+    """Sequential block table: logical block i -> physical block i."""
+    return torch.arange(num_blocks, device=device, dtype=torch.int32).view(
+        1, num_blocks
+    )
+
+
+def _generate_wht_signs(
+    head_dim: int,
+    seed: int,
+    device: torch.device,
+) -> torch.Tensor:
+    """Generate deterministic random ±1 signs for WHT rotation."""
+    gen = torch.Generator(device="cpu")
+    gen.manual_seed(seed)
+    bits = torch.randint(0, 2, (head_dim,), generator=gen, device="cpu")
+    signs = bits.float() * 2 - 1
+    return signs.to(device=device, dtype=torch.float32)
+
+
+@lru_cache(maxsize=32)
+def _solve_lloyd_max(
+    head_dim: int,
+    bits: int,
+    max_iter: int = 200,
+    tol: float = 1e-10,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Solve Lloyd-Max optimal quantizer for N(0, 1/head_dim)."""
+    n_levels = 2**bits
+    sigma2 = 1.0 / head_dim
+    sigma = math.sqrt(sigma2)
+
+    def gaussian_pdf(x: float) -> float:
+        return (1.0 / math.sqrt(2 * math.pi * sigma2)) * math.exp(-x * x / (2 * sigma2))
+
+    def trapz(f, a: float, b: float, n: int = 200) -> float:
+        h = (b - a) / n
+        result = 0.5 * (f(a) + f(b))
+        for i in range(1, n):
+            result += f(a + i * h)
+        return result * h
+
+    lo, hi = -3.5 * sigma, 3.5 * sigma
+    centroids = [lo + (hi - lo) * (i + 0.5) / n_levels for i in range(n_levels)]
+
+    for _ in range(max_iter):
+        boundaries = [
+            (centroids[i] + centroids[i + 1]) / 2.0 for i in range(n_levels - 1)
+        ]
+        edges = [lo * 3] + boundaries + [hi * 3]
+
+        new_centroids = []
+        for i in range(n_levels):
+            a, b = edges[i], edges[i + 1]
+            num = trapz(lambda x: x * gaussian_pdf(x), a, b)
+            den = trapz(gaussian_pdf, a, b)
+            new_centroids.append(num / den if den > 1e-15 else centroids[i])
+
+        if max(abs(new_centroids[i] - centroids[i]) for i in range(n_levels)) < tol:
+            break
+        centroids = new_centroids
+
+    boundaries = [(centroids[i] + centroids[i + 1]) / 2.0 for i in range(n_levels - 1)]
+
+    return (
+        torch.tensor(centroids, dtype=torch.float32),
+        torch.tensor(boundaries, dtype=torch.float32),
+    )
+
+
+@lru_cache(maxsize=32)
+def _build_hadamard_cpu(head_dim: int) -> torch.Tensor:
+    """Build an orthonormal Sylvester Hadamard matrix on CPU."""
+    if head_dim <= 0 or head_dim & (head_dim - 1) != 0:
+        raise ValueError(
+            "TurboQuant WHT rotation requires head_dim to be a power of two, "
+            f"got {head_dim}"
+        )
+
+    h = torch.tensor([[1.0]], dtype=torch.float32)
+    while h.shape[0] < head_dim:
+        h = torch.cat([torch.cat([h, h], 1), torch.cat([h, -h], 1)], 0)
+    return h / math.sqrt(head_dim)
+
+
+def _make_tq_tensors_for_layer(
+    cfg: TurboQuantSerdeConfig,
+    layer_idx: int,
+    device: torch.device,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Create PiT, midpoints, and centroids for one TurboQuant layer."""
+    seed = 42 + layer_idx * _TQ_LAYER_SEED_STRIDE
+    signs = _generate_wht_signs(cfg.head_dim, seed=seed, device=device)
+    hadamard = _build_hadamard_cpu(cfg.head_dim).to(device=device)
+    pi_t = (signs.unsqueeze(1) * hadamard).contiguous()
+
+    centroids_cpu, midpoints_cpu = _solve_lloyd_max(
+        cfg.head_dim,
+        cfg.centroid_bits,
+    )
+    centroids = centroids_cpu.to(device=device, dtype=torch.float32)
+    midpoints = midpoints_cpu.to(device=device, dtype=torch.float32)
+
+    if cfg.key_fp8:
+        # FP8-key store/dequant paths do not use PiT/midpoints/centroids, but
+        # keep valid tensors to satisfy kernel signatures.
+        midpoints = torch.empty((0,), device=device, dtype=torch.float32)
+        centroids = torch.empty((1,), device=device, dtype=torch.float32)
+
+    return pi_t, midpoints, centroids
+
+
+def _tensor_nbytes(tensor: torch.Tensor) -> int:
+    """Return the number of bytes occupied by a tensor.
+
+    Args:
+        tensor: Tensor whose storage size should be estimated.
+
+    Returns:
+        Number of bytes represented by the tensor shape and element size.
+    """
+    return tensor.numel() * tensor.element_size()
+
+
+def _cuda_utilization(device_index: int) -> int:
+    """Return GPU utilization percentage for a CUDA device.
+
+    Args:
+        device_index: CUDA device index.
+
+    Returns:
+        GPU utilization percentage. Returns 0 if utilization cannot be queried.
+    """
+    try:
+        out = subprocess.check_output(
+            [
+                "nvidia-smi",
+                f"--id={device_index}",
+                "--query-gpu=utilization.gpu",
+                "--format=csv,noheader,nounits",
+            ],
+            text=True,
+            stderr=subprocess.DEVNULL,
+        )
+        return int(out.strip().splitlines()[0])
+    except Exception:
+        return 0
+
+
+def _normalize_cuda_device(cuda_device: str) -> torch.device:
+    """Normalize a configured CUDA device string.
+
+    Args:
+        cuda_device: CUDA device string, such as "0", "cuda", or "cuda:0".
+
+    Returns:
+        Normalized torch CUDA device.
+
+    Raises:
+        ValueError: If the configured device is not a CUDA device.
+    """
+    if cuda_device.isdigit():
+        return torch.device(f"{torch_device_type}:{cuda_device}")
+
+    device = torch.device(cuda_device)
+    if device.type != torch_device_type:
+        raise ValueError(
+            f"TurboQuant cuda_device must be a CUDA device, got {cuda_device!r}"
+        )
+    if device.index is None:
+        return torch.device(torch_device_type, torch_dev.current_device())
+    return torch.device(torch_device_type, device.index)
+
+
+def _auto_select_cuda_device(required_bytes: int) -> torch.device:
+    """Select a CUDA device with enough free memory and lowest utilization.
+
+    Args:
+        required_bytes: Estimated temporary CUDA memory required by the serde
+            operation.
+
+    Returns:
+        Selected CUDA device.
+
+    Raises:
+        RuntimeError: If CUDA is unavailable or no device has enough free memory.
+    """
+    if not torch_dev.is_available():
+        raise RuntimeError("TurboQuant Triton serde requires CUDA")
+
+    candidates: list[tuple[int, int, int]] = []
+    for device_index in range(torch_dev.device_count()):
+        with torch_dev.device(device_index):
+            free_bytes, _ = torch_dev.mem_get_info()
+
+        if int(free_bytes) < required_bytes:
+            continue
+
+        util = _cuda_utilization(device_index)
+        candidates.append((util, -int(free_bytes), device_index))
+
+    if not candidates:
+        raise RuntimeError(
+            "No CUDA device has enough free memory for TurboQuant serde staging: "
+            f"required_bytes={required_bytes}"
+        )
+
+    _, _, selected = min(candidates)
+    torch_dev.set_device(selected)
+    return torch.device(torch_device_type, selected)
+
+
+def _select_cuda_device(
+    required_bytes: int,
+    configured_cuda_device: str,
+    *tensors: torch.Tensor,
+) -> torch.device:
+    """Select the CUDA device for TurboQuant Triton kernels.
+
+    Args:
+        required_bytes: Estimated temporary CUDA memory required by the serde
+            operation.
+        configured_cuda_device: Explicit CUDA device from config. Empty string
+            means auto-select when CPU staging is needed.
+        tensors: Source and destination tensors participating in the serde
+            operation.
+
+    Returns:
+        CUDA device used for Triton kernels and temporary staging.
+
+    Raises:
+        RuntimeError: If CUDA is unavailable or no device has enough memory.
+        ValueError: If CUDA tensors are on different devices, or if the
+            configured CUDA device conflicts with existing CUDA tensors.
+    """
+    cuda_devices = {tensor.device for tensor in tensors if tensor.is_cuda}
+
+    if len(cuda_devices) > 1:
+        devices = ", ".join(sorted(str(device) for device in cuda_devices))
+        raise ValueError(
+            "TurboQuant serde requires all CUDA tensors in one operation "
+            f"to be on the same device, got: {devices}"
+        )
+
+    if configured_cuda_device:
+        configured = _normalize_cuda_device(configured_cuda_device)
+        if cuda_devices and configured not in cuda_devices:
+            existing = next(iter(cuda_devices))
+            raise ValueError(
+                "Configured TurboQuant cuda_device conflicts with tensor device: "
+                f"configured={configured}, tensor_device={existing}"
+            )
+        return configured
+
+    if cuda_devices:
+        selected = next(iter(cuda_devices))
+        if selected.index is None:
+            selected = torch.device(torch_device_type, torch_dev.current_device())
+        else:
+            selected = torch.device(torch_device_type, selected.index)
+        torch_dev.set_device(selected)
+        return selected
+
+    return _auto_select_cuda_device(required_bytes)
+
+
+class TurboQuantSerializer(Serializer):
+    """TurboQuant serializer skeleton."""
+
+    def __init__(self, cfg: TurboQuantSerdeConfig):
+        self._cfg = cfg
+
+    def serialize(self, src: MemoryObj, dst: MemoryObj) -> int:
+        """Serialize a KV tensor into a TurboQuant-compressed byte buffer.
+
+        Args:
+            src: Source memory object containing a KV tensor with shape
+                ``[2, num_layers, num_tokens, hidden_dim]``.
+            dst: Destination memory object containing a ``torch.uint8`` tensor
+                used as the serialized byte buffer.
+
+        Returns:
+            The number of serialized bytes written to ``dst``.
+
+        Raises:
+            ValueError: If source or destination tensors are missing, if the
+                destination buffer is too small, if the destination dtype is not
+                ``torch.uint8``, or if the KV tensor layout is unsupported.
+            RuntimeError: If CUDA is unavailable or no CUDA device has enough
+                memory for TurboQuant staging.
+        """
+        src_tensor = src.tensor
+        dst_tensor = dst.tensor
+        if src_tensor is None or dst_tensor is None:
+            raise ValueError("TurboQuant serde requires src and dst to have tensors")
+
+        n_bytes = _serialized_nbytes_for_shape(
+            src_tensor.shape, src_tensor.dtype, self._cfg
+        )
+        if dst_tensor.numel() < n_bytes:
+            raise ValueError(
+                f"Destination buffer too small: got {dst_tensor.numel()} bytes, "
+                f"need {n_bytes}"
+            )
+
+        if dst_tensor.dtype != torch.uint8:
+            raise ValueError(
+                "TurboQuant serialized destination must be torch.uint8, "
+                f"got {dst_tensor.dtype}"
+            )
+        required_cuda_bytes = n_bytes
+        if not src_tensor.is_cuda:
+            required_cuda_bytes += _tensor_nbytes(src_tensor)
+        if not dst_tensor.is_cuda:
+            required_cuda_bytes += n_bytes
+
+        cuda_device = _select_cuda_device(
+            required_cuda_bytes,
+            self._cfg.cuda_device,
+            src_tensor,
+            dst_tensor,
+        )
+
+        # StorageManager may provide CPU / pinned-memory MemoryObjs. Triton
+        # kernels require CUDA tensors, so use temporary CUDA buffers when
+        # necessary and copy the serialized bytes back to the original dst.
+        src_work = (
+            src_tensor
+            if src_tensor.is_cuda
+            else src_tensor.clone().to(device=cuda_device)
+        )
+        dst_work = (
+            dst_tensor
+            if dst_tensor.is_cuda
+            else torch.empty(n_bytes, dtype=torch.uint8, device=cuda_device)
+        )
+
+        cfg = self._cfg
+        num_layers, num_tokens, num_heads, head_dim = _validate_layout_shape(
+            src_work.shape, cfg
+        )
+        quant_start, quant_end = _layer_ranges(num_layers, cfg)
+        quant_layers = quant_end - quant_start
+        dst_flat = dst_work.flatten()[:n_bytes]
+        offset = 0
+
+        first_raw_bytes = _raw_group_nbytes(src_work.shape, src_work.dtype, quant_start)
+        if first_raw_bytes:
+            raw = src_work[:, :quant_start].contiguous().view(torch.uint8).flatten()
+            dst_flat[:first_raw_bytes].copy_(raw)
+            offset = first_raw_bytes
+
+        if quant_layers:
+            # First Party
+            from lmcache.v1.distributed.serde.turboquant.store_kernel import (
+                triton_turboquant_store,
+            )
+
+            compressed_shape = _compressed_layout_for_shape(
+                src_work.shape, cfg, quant_layers
+            )
+            compressed_bytes = math.prod(compressed_shape)
+            dst_view = dst_flat[offset : offset + compressed_bytes].view(
+                *compressed_shape
+            )
+            slot_mapping = _make_slot_mapping(num_tokens, cuda_device)
+
+            # LMCache layout: [2, L, T, hidden_dim]
+            # Kernel input layout per layer: key/value [T, H, D]
+            for compressed_idx, layer_idx in enumerate(range(quant_start, quant_end)):
+                key = (
+                    src_work[0, layer_idx]
+                    .view(num_tokens, num_heads, head_dim)
+                    .contiguous()
+                )
+                value = (
+                    src_work[1, layer_idx]
+                    .view(num_tokens, num_heads, head_dim)
+                    .contiguous()
+                )
+                pi_t, midpoints, _ = _make_tq_tensors_for_layer(
+                    cfg, layer_idx, cuda_device
+                )
+                triton_turboquant_store(
+                    key,
+                    value,
+                    dst_view[compressed_idx],
+                    slot_mapping,
+                    pi_t,
+                    midpoints,
+                    mse_bits=cfg.key_mse_bits,
+                    key_packed_size=cfg.key_packed_size,
+                    value_quant_bits=cfg.value_quant_bits,
+                    key_fp8=cfg.key_fp8,
+                )
+            offset += compressed_bytes
+
+        if quant_end < num_layers:
+            raw = src_work[:, quant_end:].contiguous().view(torch.uint8).flatten()
+            dst_flat[offset : offset + raw.numel()].copy_(raw)
+
+        if not dst_tensor.is_cuda:
+            dst_tensor.flatten()[:n_bytes].copy_(dst_work.cpu().flatten()[:n_bytes])
+
+        return n_bytes
+
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        total = 0
+        for shape, dtype in zip(layout_desc.shapes, layout_desc.dtypes, strict=False):
+            total += _serialized_nbytes_for_shape(shape, dtype, self._cfg)
+        return total
+
+
+class TurboQuantDeserializer(Deserializer):
+    """TurboQuant deserializer skeleton."""
+
+    def __init__(self, cfg: TurboQuantSerdeConfig):
+        self._cfg = cfg
+
+    def deserialize(self, src: MemoryObj, dst: MemoryObj) -> None:
+        """Deserialize a TurboQuant byte buffer into a destination KV tensor.
+
+        Args:
+            src: Source memory object containing the serialized TurboQuant
+                byte buffer as a ``torch.uint8`` tensor.
+            dst: Destination memory object containing the reconstructed KV
+                tensor with shape ``[2, num_layers, num_tokens, hidden_dim]``.
+
+        Raises:
+            ValueError: If source or destination tensors are missing, if the
+                source buffer is too small, if the source dtype is not
+                ``torch.uint8``, or if the destination KV tensor layout is
+                unsupported.
+            RuntimeError: If CUDA is unavailable or no CUDA device has enough
+                memory for TurboQuant staging.
+        """
+        src_tensor = src.tensor
+        dst_tensor = dst.tensor
+        if src_tensor is None or dst_tensor is None:
+            raise ValueError("TurboQuant serde requires src and dst to have tensors")
+
+        n_bytes = _serialized_nbytes_for_shape(
+            dst_tensor.shape, dst_tensor.dtype, self._cfg
+        )
+        if src_tensor.numel() < n_bytes:
+            raise ValueError(
+                f"Source buffer too small: got {src_tensor.numel()} bytes, "
+                f"need {n_bytes}"
+            )
+
+        if src_tensor.dtype != torch.uint8:
+            raise ValueError(
+                "TurboQuant serialized source must be torch.uint8, "
+                f"got {src_tensor.dtype}"
+            )
+        required_cuda_bytes = n_bytes
+        if not src_tensor.is_cuda:
+            required_cuda_bytes += n_bytes
+        if not dst_tensor.is_cuda:
+            required_cuda_bytes += _tensor_nbytes(dst_tensor)
+
+        cuda_device = _select_cuda_device(
+            required_cuda_bytes,
+            self._cfg.cuda_device,
+            src_tensor,
+            dst_tensor,
+        )
+
+        # StorageManager may provide CPU / pinned-memory MemoryObjs. Triton
+        # kernels require CUDA tensors, so copy compressed bytes to CUDA and
+        # dequantize into a CUDA temporary when the destination is CPU.
+        src_work = (
+            src_tensor
+            if src_tensor.is_cuda
+            else src_tensor.flatten()[:n_bytes].clone().to(device=cuda_device)
+        )
+        dst_work = (
+            dst_tensor
+            if dst_tensor.is_cuda
+            else torch.empty(
+                dst_tensor.shape,
+                dtype=dst_tensor.dtype,
+                device=cuda_device,
+            )
+        )
+
+        cfg = self._cfg
+        num_layers, num_tokens, num_heads, head_dim = _validate_layout_shape(
+            dst_work.shape, cfg
+        )
+        hidden_dim = num_heads * head_dim
+        quant_start, quant_end = _layer_ranges(num_layers, cfg)
+        quant_layers = quant_end - quant_start
+        src_flat = src_work.flatten()[:n_bytes]
+        offset = 0
+
+        first_raw_bytes = _raw_group_nbytes(dst_work.shape, dst_work.dtype, quant_start)
+        if first_raw_bytes:
+            raw = torch.empty(
+                (2, quant_start, num_tokens, hidden_dim),
+                dtype=dst_work.dtype,
+                device=cuda_device,
+            )
+            raw.view(torch.uint8).flatten().copy_(src_flat[:first_raw_bytes])
+            dst_work[:, :quant_start].copy_(raw)
+            offset = first_raw_bytes
+
+        if quant_layers:
+            # First Party
+            from lmcache.v1.distributed.serde.turboquant.decode_kernel import (
+                _tq_full_dequant_kv,
+                _use_fp8_e4b15,
+            )
+
+            compressed_shape = _compressed_layout_for_shape(
+                dst_work.shape, cfg, quant_layers
+            )
+            compressed_bytes = math.prod(compressed_shape)
+            src_view = src_flat[offset : offset + compressed_bytes].view(
+                *compressed_shape
+            )
+            num_blocks = compressed_shape[1]
+            alloc_len = num_blocks * cfg.block_size
+            block_table = _make_block_table(num_blocks, cuda_device)
+            block_d = 1 << (head_dim - 1).bit_length()
+            val_data_bytes = math.ceil(head_dim * cfg.value_quant_bits / 8)
+            mse_bytes = (
+                math.ceil(head_dim * cfg.key_mse_bits / 8)
+                if not cfg.key_fp8
+                else head_dim
+            )
+            k_out = torch.empty(
+                (1, num_heads, alloc_len, head_dim),
+                dtype=torch.float16,
+                device=cuda_device,
+            )
+            v_out = torch.empty_like(k_out)
+
+            for compressed_idx, layer_idx in enumerate(range(quant_start, quant_end)):
+                kv_cache_layer = src_view[compressed_idx]
+                pi_t, _, centroids = _make_tq_tensors_for_layer(
+                    cfg, layer_idx, cuda_device
+                )
+                grid = (alloc_len, num_heads)
+                _tq_full_dequant_kv[grid](
+                    kv_cache_layer,
+                    block_table,
+                    centroids,
+                    k_out,
+                    v_out,
+                    k_out.stride(0),
+                    k_out.stride(1),
+                    k_out.stride(2),
+                    v_out.stride(0),
+                    v_out.stride(1),
+                    v_out.stride(2),
+                    kv_cache_layer.stride(0),
+                    kv_cache_layer.stride(1),
+                    kv_cache_layer.stride(2),
+                    block_table.stride(0),
+                    HEAD_DIM=head_dim,
+                    BLOCK_SIZE=cfg.block_size,
+                    NUM_KV_HEADS=num_heads,
+                    MSE_BYTES=mse_bytes,
+                    KPS=cfg.key_packed_size,
+                    VQB=cfg.value_quant_bits,
+                    VAL_DATA_BYTES=val_data_bytes,
+                    MSE_BITS=cfg.key_mse_bits,
+                    KEY_FP8=1 if cfg.key_fp8 else 0,
+                    BLOCK_D=block_d,
+                    NORM_CORRECTION=1 if cfg.norm_correction else 0,
+                    FP8_E4B15=_use_fp8_e4b15(cuda_device.index or 0),
+                    num_warps=4,
+                )
+
+                k_layer = k_out[0, :, :num_tokens, :].transpose(0, 1).contiguous()
+                if not cfg.key_fp8:
+                    # Restore the original key after TurboQuant's WHT rotation.
+                    k_layer = torch.matmul(
+                        k_layer.to(torch.float32), pi_t.T.contiguous()
+                    ).to(k_out.dtype)
+                key = k_layer.contiguous().view(num_tokens, hidden_dim)
+                value = (
+                    v_out[0, :, :num_tokens, :]
+                    .transpose(0, 1)
+                    .contiguous()
+                    .view(num_tokens, hidden_dim)
+                )
+                dst_work[0, layer_idx].copy_(key.to(dst_work.dtype))
+                dst_work[1, layer_idx].copy_(value.to(dst_work.dtype))
+            offset += compressed_bytes
+
+        last_raw_layers = num_layers - quant_end
+        if last_raw_layers:
+            last_raw_bytes = _raw_group_nbytes(
+                dst_work.shape, dst_work.dtype, last_raw_layers
+            )
+            raw = torch.empty(
+                (2, last_raw_layers, num_tokens, hidden_dim),
+                dtype=dst_work.dtype,
+                device=cuda_device,
+            )
+            raw.view(torch.uint8).flatten().copy_(
+                src_flat[offset : offset + last_raw_bytes]
+            )
+            dst_work[:, quant_end:].copy_(raw)
+
+        if not dst_tensor.is_cuda:
+            dst_tensor.copy_(dst_work.cpu())
+
+
+def _create_turboquant_serde(kwargs: dict[str, object]) -> SerdeProcessor:
+    preset = str(kwargs.get("preset", "turboquant_k8v4"))
+    head_dim = int(kwargs.get("head_dim", 128))  # type: ignore[call-overload]
+    block_size = int(kwargs.get("block_size", 16))  # type: ignore[call-overload]
+    skip_first_layers = int(
+        kwargs.get("skip_first_layers", 2)  # type: ignore[call-overload]
+    )
+    skip_last_layers = int(
+        kwargs.get("skip_last_layers", 2)  # type: ignore[call-overload]
+    )
+    max_workers = int(kwargs.get("max_workers", 1))  # type: ignore[call-overload]
+
+    cfg = TurboQuantSerdeConfig(
+        preset=preset,
+        head_dim=head_dim,
+        block_size=block_size,
+        skip_first_layers=skip_first_layers,
+        skip_last_layers=skip_last_layers,
+    )
+
+    return AsyncSerdeProcessor(
+        TurboQuantSerializer(cfg),
+        TurboQuantDeserializer(cfg),
+        max_workers=max_workers,
+    )
+
+
+register_serde_factory("turboquant", _create_turboquant_serde)
diff --git a/lmcache/v1/distributed/serde/utils.py b/lmcache/v1/distributed/serde/utils.py
new file mode 100644
index 0000000..ed22086
--- /dev/null
+++ b/lmcache/v1/distributed/serde/utils.py
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Serde helper utilities for the distributed storage controllers.
+"""
+
+# Standard
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.serde.base import SerdeProcessor
+
+
+def serialized_layout_desc(
+    layout_desc: MemoryLayoutDesc,
+    serde: SerdeProcessor,
+) -> MemoryLayoutDesc:
+    """Compute a flat byte-buffer MemoryLayoutDesc for the serialized output.
+
+    Returns a single-group uint8 layout whose size is determined by the
+    serde processor's ``estimate_serialized_size`` (which already includes
+    any safety margin).
+    """
+    buffer_size = serde.estimate_serialized_size(layout_desc)
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([buffer_size])],
+        dtypes=[torch.uint8],
+    )
+
+
+def make_temp_key(original_key: ObjectKey) -> ObjectKey:
+    """Create a unique temporary key derived from the original.
+
+    Appends 16 random bytes (128 bits of entropy) to the original
+    chunk hash. Birthday-collision risk is ~1 in 2**64 keys, which is
+    effectively zero at any realistic scale, so the same original key
+    can be serde'd repeatedly without practical concern.
+
+    ``cache_salt`` are propagated so per-tenant L1 byte accounting and
+    quota / eviction logic continue to attribute temp buffers to the
+    same bucket as the originals.
+
+    Args:
+        original_key: The original ObjectKey to derive from.
+    """
+    return ObjectKey(
+        chunk_hash=original_key.chunk_hash + os.urandom(16),
+        model_name=original_key.model_name,
+        kv_rank=original_key.kv_rank,
+        object_group_id=original_key.object_group_id,
+        cache_salt=original_key.cache_salt,
+    )
diff --git a/lmcache/v1/distributed/storage_controller.py b/lmcache/v1/distributed/storage_controller.py
new file mode 100644
index 0000000..3bcd52c
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controller.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Interface for storage controllers
+
+Storage controllers are separate modules/threads that sees the L1 Manager
+and can operate on it.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+
+
+class StorageControllerInterface(ABC):
+    @abstractmethod
+    def start(self):
+        """
+        Start the storage controller.
+        This function should be implemented by subclasses to start
+        any necessary threads or processes.
+        """
+        pass
+
+    @abstractmethod
+    def stop(self):
+        """
+        Stop the storage controller.
+        This function should be implemented by subclasses to stop
+        any running threads or processes.
+        """
+        pass
+
+    @abstractmethod
+    def report_status(self) -> dict:
+        """
+        Return a status dict for this controller.
+
+        Must include at least ``is_healthy: bool``.
+        """
+        pass
diff --git a/lmcache/v1/distributed/storage_controllers/__init__.py b/lmcache/v1/distributed/storage_controllers/__init__.py
new file mode 100644
index 0000000..cfd574f
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/__init__.py
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Storage controllers with automatic module discovery.
+
+All modules under this package that call ``register_store_policy`` or
+``register_prefetch_policy`` at import time are discovered automatically.
+To add a new policy, simply create a new module in this directory -- **no
+changes to any existing file are needed**.
+"""
+
+# Standard
+import importlib
+import pkgutil
+
+# First Party
+from lmcache.v1.distributed.storage_controllers.eviction_controller import (
+    EvictionController,
+    L1EvictionController,
+    L2AdapterEvictionState,
+    L2EvictionController,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_controller import (
+    PrefetchController,
+)
+from lmcache.v1.distributed.storage_controllers.store_controller import (
+    StoreController,
+)
+
+# Auto-discover and import every module in this package so
+# that each policy's self-registration code runs.
+_PACKAGE_PATH = __path__  # type: ignore[name-defined]
+_PACKAGE_NAME = __name__
+for _finder, _mod_name, _is_pkg in pkgutil.iter_modules(_PACKAGE_PATH):
+    importlib.import_module(f".{_mod_name}", _PACKAGE_NAME)
+
+__all__ = [
+    "EvictionController",
+    "L1EvictionController",
+    "L2EvictionController",
+    "L2AdapterEvictionState",
+    "PrefetchController",
+    "StoreController",
+]
diff --git a/lmcache/v1/distributed/storage_controllers/adapter_lifecycle.py b/lmcache/v1/distributed/storage_controllers/adapter_lifecycle.py
new file mode 100644
index 0000000..bae9066
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/adapter_lifecycle.py
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Control-plane operations for runtime add/remove of L2 adapters.
+
+Both :class:`StoreController` and :class:`PrefetchController` own a
+``select.poll()`` loop on a dedicated background thread.  Their poll set,
+eventfd-to-id maps, and in-flight task tables are mutated only by that
+thread.  To add or remove an adapter at runtime without racing the loop,
+external callers enqueue one of these ops and signal a control eventfd;
+the loop applies the op at the top of its next iteration.
+"""
+
+# Standard
+from dataclasses import dataclass
+import threading
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface
+from lmcache.v1.distributed.storage_controllers.store_policy import AdapterDescriptor
+
+
+@dataclass
+class AddAdapterOp:
+    """Attach a new adapter under the stable id ``adapter_id``.
+
+    ``done`` is set by the loop once the adapter's eventfd(s) are
+    registered and the adapter is live for routing.
+    """
+
+    adapter_id: int
+    adapter: L2AdapterInterface
+    descriptor: AdapterDescriptor
+    done: threading.Event
+
+
+@dataclass
+class RemoveAdapterOp:
+    """Begin a graceful drain of the adapter under ``adapter_id``.
+
+    Applying the op marks the adapter as draining (no new work routes to
+    it).  ``done`` is set only once all in-flight work referencing the
+    adapter has finished and its eventfd(s) are unregistered.
+    """
+
+    adapter_id: int
+    done: threading.Event
diff --git a/lmcache/v1/distributed/storage_controllers/eviction_controller.py b/lmcache/v1/distributed/storage_controllers/eviction_controller.py
new file mode 100644
index 0000000..56bdb6a
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/eviction_controller.py
@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import abstractmethod
+from collections import Counter
+from typing import TYPE_CHECKING
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.config import EvictionConfig
+from lmcache.v1.distributed.eviction import L1EvictionPolicy, L2EvictionPolicy
+from lmcache.v1.distributed.eviction_policy import CreateEvictionPolicy
+from lmcache.v1.distributed.internal_api import (
+    EvictionAction,
+    EvictionDestination,
+)
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface
+from lmcache.v1.distributed.storage_controller import StorageControllerInterface
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.quota_manager import QuotaManager
+
+logger = init_logger(__name__)
+
+
+class EvictionController(StorageControllerInterface):
+    """
+    Abstract base class for eviction controllers.
+
+    Provides the shared eviction loop structure: background thread and stop
+    flag. Subclasses implement eviction_loop and execute_eviction_action
+    for their specific tier (L1 or L2).
+    """
+
+    def __init__(self):
+        self._stop_flag = threading.Event()
+        self._thread = threading.Thread(
+            target=self.eviction_loop,
+            daemon=True,
+        )
+
+    def start(self):
+        logger.info("Starting %s...", self.__class__.__name__)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        self._thread.join()
+
+    @abstractmethod
+    def report_status(self) -> dict:
+        """Return a status dict for this controller.
+
+        The child class needs to override this function to report
+        controller-specific health and configuration information.
+        """
+        pass
+
+    @abstractmethod
+    def eviction_loop(self):
+        """Run the eviction loop.
+
+        The child class needs to override this function to implement
+        internal eviction controlling logic.
+        """
+        pass
+
+    @abstractmethod
+    def execute_eviction_action(self, action: EvictionAction):
+        """Execute a single eviction action.
+
+        The child class needs to override this function to implement
+        internal eviction controlling logic.
+        """
+        pass
+
+
+class L1EvictionController(EvictionController):
+    """
+    Eviction controller for L1 cache.
+
+    Uses an L1EvictionPolicy bridge to keep the eviction policy up-to-date
+    with L1 manager events, and periodically triggers eviction based on
+    L1 memory usage.
+    """
+
+    def __init__(
+        self,
+        l1_manager: L1Manager,
+        eviction_config: EvictionConfig,
+    ):
+        super().__init__()
+        self._eviction_config = eviction_config
+        self._eviction_policy = CreateEvictionPolicy(eviction_config)
+        self._l1_manager = l1_manager
+        self._listener = L1EvictionPolicy(self._eviction_policy)
+        self._l1_manager.register_listener(self._listener)
+        self._event_bus = get_event_bus()
+
+    def report_status(self) -> dict:
+        return {
+            "is_healthy": self._thread.is_alive(),
+            "thread_alive": self._thread.is_alive(),
+            "eviction_policy": self._eviction_config.eviction_policy,
+            "trigger_watermark": self._eviction_config.trigger_watermark,
+            "eviction_ratio": self._eviction_config.eviction_ratio,
+        }
+
+    def _publish_skipped(self, usage: float, watermark: float) -> None:
+        """Publish a below-watermark loop tick (no eviction this cycle)."""
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_EVICTION_LOOP_TICK,
+                metadata={
+                    "usage": usage,
+                    "watermark": watermark,
+                    "triggered": False,
+                },
+            )
+        )
+
+    def _publish_triggered(self, usage: float, watermark: float) -> None:
+        """Publish an above-watermark loop tick (eviction policy ran)."""
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L1_EVICTION_LOOP_TICK,
+                metadata={
+                    "usage": usage,
+                    "watermark": watermark,
+                    "triggered": True,
+                },
+            )
+        )
+
+    def eviction_loop(self):
+        watermark = self._eviction_config.trigger_watermark
+        eviction_ratio = self._eviction_config.eviction_ratio
+
+        while not self._stop_flag.is_set():
+            time.sleep(1)
+            used_bytes, total_bytes = self._l1_manager.get_memory_usage()
+            usage = 0 if total_bytes == 0 else used_bytes / total_bytes
+            if usage < watermark:
+                logger.debug(
+                    "L1 memory usage %.2f below watermark %.2f; skipping eviction.",
+                    usage,
+                    watermark,
+                )
+                self._publish_skipped(usage, watermark)
+                continue
+
+            logger.info(
+                "L1 memory usage %.2f above watermark %.2f; triggering eviction.",
+                usage,
+                watermark,
+            )
+            actions = self._eviction_policy.get_eviction_actions(
+                eviction_ratio,
+                key_eligible_filter=self._l1_manager.is_key_evictable,
+            )
+            for action in actions:
+                self.execute_eviction_action(action)
+            self._publish_triggered(usage, watermark)
+
+    def execute_eviction_action(self, action: EvictionAction):
+        if action.destination == EvictionDestination.DISCARD:
+            self._l1_manager.delete(action.keys)
+        else:
+            logger.error("Unsupported eviction destination: %s", action.destination)
+            logger.error("Treating it as DISCARD.")
+            self._l1_manager.delete(action.keys)
+
+
+class L2AdapterEvictionState:
+    """Per-adapter eviction state: its own policy, listener, and config."""
+
+    def __init__(
+        self,
+        adapter_id: int,
+        adapter: L2AdapterInterface,
+        eviction_config: EvictionConfig,
+    ):
+        self.adapter_id = adapter_id
+        self.adapter = adapter
+        self.eviction_config = eviction_config
+        self.eviction_policy = CreateEvictionPolicy(eviction_config)
+        self.listener = L2EvictionPolicy(self.eviction_policy)
+        adapter.register_listener(self.listener)
+
+
+class L2EvictionController(StorageControllerInterface):
+    """
+    Unified eviction controller for all L2 adapters.
+
+    Each adapter gets its own eviction policy and listener bridge, but a
+    single background thread loops over all of them.
+
+    When the adapter's policy sets ``support_isolation == True``
+    (e.g. :class:`IsolatedLRUEvictionPolicy`), the controller consults
+    the injected :class:`QuotaManager` to decide which ``cache_salt``
+    buckets are over budget and evicts from each one in isolation.
+    Otherwise it uses the adapter's aggregate ``usage_fraction``
+    against the configured watermark — unchanged from the pre-PR5
+    behavior.
+    """
+
+    def __init__(
+        self,
+        l2_adapter_states: list[L2AdapterEvictionState],
+        quota_manager: QuotaManager | None = None,
+    ):
+        self._adapter_states = l2_adapter_states
+        self._quota_manager = quota_manager
+        # Guards _adapter_states against concurrent runtime add/remove.
+        self._states_lock = threading.Lock()
+        self._stop_flag = threading.Event()
+        self._thread = threading.Thread(
+            target=self._eviction_loop,
+            daemon=True,
+        )
+
+    def start(self):
+        logger.info("Starting %s...", self.__class__.__name__)
+        self._thread.start()
+
+    def stop(self):
+        self._stop_flag.set()
+        self._thread.join()
+
+    def add_adapter_state(self, state: L2AdapterEvictionState) -> None:
+        """Register a new adapter's eviction state at runtime."""
+        with self._states_lock:
+            self._adapter_states.append(state)
+
+    def remove_adapter_state(self, adapter_id: int) -> None:
+        """Drop the eviction state for ``adapter_id``.
+
+        Blocks until any in-progress eviction pass finishes (it holds the
+        same lock), so the adapter is guaranteed idle here before the
+        caller closes it. A no-op if the adapter has no eviction state.
+        """
+        with self._states_lock:
+            self._adapter_states = [
+                s for s in self._adapter_states if s.adapter_id != adapter_id
+            ]
+
+    def report_status(self) -> dict:
+        # NOTE: ``usage.bytes_by_cache_salt`` is intentionally NOT
+        # surfaced here. A deployment can have 10k+ salts, so embedding
+        # the full bucket map in the status response would blow up the
+        # payload. Per-salt inspection goes through the dedicated HTTP
+        # quota endpoints (which pull from ``QuotaManager`` +
+        # ``StorageManager.get_usage_bytes_by_cache_salt``).
+        adapter_statuses = []
+        with self._states_lock:
+            states = list(self._adapter_states)
+        for state in states:
+            usage = state.adapter.get_usage()
+            adapter_statuses.append(
+                {
+                    "eviction_policy": state.eviction_config.eviction_policy,
+                    "trigger_watermark": state.eviction_config.trigger_watermark,
+                    "eviction_ratio": state.eviction_config.eviction_ratio,
+                    "current_usage": usage.usage_fraction,
+                    "total_bytes_used": usage.total_bytes_used,
+                    "total_capacity_bytes": usage.total_capacity_bytes,
+                    "num_cache_salt_buckets": len(usage.bytes_by_cache_salt),
+                }
+            )
+        return {
+            "is_healthy": self._thread.is_alive(),
+            "thread_alive": self._thread.is_alive(),
+            "adapters": adapter_statuses,
+        }
+
+    def _eviction_loop(self):
+        while not self._stop_flag.is_set():
+            time.sleep(1)
+            # Hold the lock across the whole pass so remove_adapter_state
+            # cannot detach (and the caller close) an adapter while we are
+            # calling into it.
+            with self._states_lock:
+                for state in self._adapter_states:
+                    self._check_and_evict(state)
+
+    def _check_and_evict(self, state: L2AdapterEvictionState):
+        if state.eviction_policy.support_isolation and self._quota_manager is not None:
+            self._check_and_evict_by_cache_salt(state)
+        else:
+            self._check_and_evict_global(state)
+
+    def _check_and_evict_global(self, state: L2AdapterEvictionState):
+        """Aggregate-usage eviction (``LRU`` / ``noop``)."""
+        watermark = state.eviction_config.trigger_watermark
+        eviction_ratio = state.eviction_config.eviction_ratio
+
+        # ``usage_fraction == -1`` means the adapter doesn't support
+        # usage-based eviction (no max_capacity_bytes declared), so we
+        # do not trigger eviction. Adapters with ``supports_global_eviction ==
+        # False`` should already have been filtered out at construction
+        # time in ``StorageManager``; this check is a defensive belt.
+        current_usage = state.adapter.get_usage().usage_fraction
+        if current_usage < 0 or current_usage < watermark:
+            logger.debug(
+                "L2 usage %.2f below watermark %.2f; skipping eviction.",
+                current_usage,
+                watermark,
+            )
+            return
+
+        logger.info(
+            "L2 usage %.2f above watermark %.2f; triggering eviction.",
+            current_usage,
+            watermark,
+        )
+        actions = state.eviction_policy.get_eviction_actions(eviction_ratio)
+        for action in actions:
+            self._execute_eviction_action(state.adapter, action)
+
+    def _check_and_evict_by_cache_salt(self, state: L2AdapterEvictionState):
+        """Per-``cache_salt`` eviction driven by :class:`QuotaManager`.
+
+        For every salt with non-zero bytes, compare its usage against
+        ``watermark * quota``. Salts over threshold get eviction scoped
+        to their own LRU list. Salts with no quota registered have an
+        effective limit of ``0`` and are therefore always over budget,
+        so they get a full eviction (``effective_ratio=1.0``) — this
+        enforces the allowlist rule: only registered salts retain data.
+
+        Per-destination keys are batched across all over-budget salts
+        before invoking the adapter — one ``adapter.delete(...)`` call
+        per destination instead of one per (salt, destination) pair.
+        Adapters with non-trivial per-call overhead (NIXL handle setup,
+        FS sync, etc.) see this as a real win when many salts go over
+        budget in the same cycle.
+        """
+        assert self._quota_manager is not None
+        watermark = state.eviction_config.trigger_watermark
+        eviction_ratio = state.eviction_config.eviction_ratio
+        usage = state.adapter.get_usage()
+
+        # destination -> accumulated keys across all over-budget salts.
+        pending: dict[EvictionDestination, list[ObjectKey]] = {}
+
+        for cache_salt, user_bytes in usage.bytes_by_cache_salt.items():
+            if user_bytes <= 0:
+                continue
+            limit = self._quota_manager.get_limit_bytes(cache_salt)
+            # Trigger on ``>=`` to match the global branch's ``usage <
+            # watermark`` short-circuit. Salts with no quota (limit=0)
+            # always land here because ``user_bytes > 0 >= 0``.
+            if user_bytes < watermark * limit:
+                continue
+
+            # Unregistered / zero-quota salts: wipe everything.
+            # Registered salts: evict the configured ratio of their list.
+            effective_ratio = 1.0 if limit == 0 else eviction_ratio
+            logger.info(
+                "cache_salt=%r over quota (bytes=%d, limit=%d, "
+                "watermark=%.2f); evicting ratio=%.2f.",
+                cache_salt,
+                user_bytes,
+                limit,
+                watermark,
+                effective_ratio,
+            )
+            actions = state.eviction_policy.get_eviction_actions(
+                effective_ratio, cache_salt=cache_salt
+            )
+            for action in actions:
+                pending.setdefault(action.destination, []).extend(action.keys)
+
+        for destination, keys in pending.items():
+            self._execute_eviction_action(
+                state.adapter,
+                EvictionAction(keys=keys, destination=destination),
+            )
+
+    def _execute_eviction_action(
+        self, adapter: L2AdapterInterface, action: EvictionAction
+    ):
+        if action.destination == EvictionDestination.DISCARD:
+            adapter.delete(action.keys)
+        else:
+            logger.error("Unsupported eviction destination: %s", action.destination)
+            logger.error("Treating it as DISCARD.")
+            adapter.delete(action.keys)
+
+        if action.keys:
+            get_event_bus().publish(
+                Event(
+                    event_type=EventType.L2_KEYS_EVICTED,
+                    metadata={
+                        "key_count": len(action.keys),
+                        "key_count_per_salt": Counter(
+                            k.cache_salt for k in action.keys
+                        ),
+                    },
+                )
+            )
diff --git a/lmcache/v1/distributed/storage_controllers/prefetch_controller.py b/lmcache/v1/distributed/storage_controllers/prefetch_controller.py
new file mode 100644
index 0000000..a1bfc01
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/prefetch_controller.py
@@ -0,0 +1,1263 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Prefetch Controller: asynchronously prefetches data from L2 adapters into L1.
+
+The controller runs a background thread with an event-driven loop that:
+1. Accepts prefetch requests from external threads via submit_prefetch_request.
+2. Submits lookup_and_lock tasks to all L2 adapters.
+3. Computes a load plan, keeping the keys retained by the TrimPolicy
+   (PREFIX, SEGMENTED_PREFIX, or SPARSE).
+4. Reserves L1 write buffers and submits load tasks to L2 adapters.
+5. On load completion, transitions L1 entries from write-locked to read-locked.
+6. Reports the retained-key bitmap.
+"""
+
+# Standard
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Iterable
+import enum
+import select
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import (
+    DEFAULT_ATTN_WINDOW_DESC,
+    AttnWindowDesc,
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchMode,
+    TrimPolicy,
+)
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface, L2TaskId
+from lmcache.v1.distributed.storage_controller import StorageControllerInterface
+from lmcache.v1.distributed.storage_controllers.adapter_lifecycle import (
+    AddAdapterOp,
+    RemoveAdapterOp,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_policy import (
+    PrefetchPolicy,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+from lmcache.v1.mp_observability.otel_init import register_gauge
+from lmcache.v1.platform import (
+    consume_fd,
+    create_event_notifier,
+)
+
+logger = init_logger(__name__)
+
+
+# HELPER FUNCTIONS
+def merge_bitmaps(bitmaps: Iterable[Bitmap], num_keys: int) -> Bitmap:
+    """Merge bitmaps with a bitwise OR into a ``num_keys``-sized bitmap.
+
+    Always returns a ``num_keys``-sized bitmap (empty input -> all zeros), so
+    downstream ``&`` operations never hit a size mismatch.
+    """
+    merged = Bitmap(num_keys)
+    for bm in bitmaps:
+        merged = merged | bm
+    return merged
+
+
+def build_trim_mask(
+    found: Bitmap,
+    num_keys: int,
+    policy: TrimPolicy = TrimPolicy.PREFIX,
+) -> Bitmap:
+    """Subset of ``found`` to keep (load + read-lock + report); the rest is
+    released.
+
+    PREFIX trims at the first gap (leading contiguous run). The non-PREFIX
+    policies keep every set bit, gaps included, and differ only in intent:
+    SEGMENTED_PREFIX keeps the keys that loaded when an L2 hit fails to load
+    into L1 (e.g. OOM) mid-prefix; SPARSE keeps an intentionally scattered set.
+
+    Args:
+        found: Bitmap of found keys, over key indices ``0..num_keys-1``.
+        num_keys: Total number of requested keys.
+        policy: Trim policy to apply (see :class:`TrimPolicy`).
+
+    Returns:
+        Bitmap of the retained key indices.
+    """
+    if policy is TrimPolicy.PREFIX:
+        return Bitmap(num_keys, found.count_leading_ones())
+    return found
+
+
+def trim_load_plan_with_mask(
+    load_plan: dict[int, Bitmap],
+    mask: Bitmap,
+) -> dict[int, Bitmap]:
+    """Trim the load plan to the key indices set in ``mask`` (gap-tolerant).
+
+    Args:
+        load_plan: Mapping from adapter index to Bitmap of key indices.
+        mask: Bitmap of key indices to retain.
+
+    Returns:
+        Trimmed load plan; adapter indices retaining no keys are dropped.
+    """
+    trimmed_plan: dict[int, Bitmap] = {}
+    for adapter_idx, bitmap in load_plan.items():
+        new_bitmap = bitmap & mask
+        if new_bitmap.popcount() == 0:
+            continue
+        trimmed_plan[adapter_idx] = new_bitmap
+    return trimmed_plan
+
+
+# Poll timeout in milliseconds for the prefetch loop
+PREFETCH_LOOP_POLL_TIMEOUT_MS = 500
+
+PrefetchRequestId = int
+
+
+class PrefetchPhase(enum.Enum):
+    LOOKUP = enum.auto()
+    PLAN_AND_LOAD = enum.auto()
+
+
+@dataclass
+class InFlightPrefetchRequest:
+    """Tracks a single prefetch request across its lifecycle phases."""
+
+    request_id: PrefetchRequestId
+    keys: list[ObjectKey]
+    layout_desc: MemoryLayoutDesc
+    phase: PrefetchPhase
+    extra_count: int = 0
+    """Extra read locks per key (on top of the default 1) to acquire when
+    transitioning from write-locked to read-locked.  Must match the
+    ``extra_count`` used in the corresponding ``submit_prefetch_task`` call."""
+
+    policy: TrimPolicy = TrimPolicy.PREFIX
+    """Which retained-subset policy to apply (see :class:`TrimPolicy`)."""
+
+    attn_desc: AttnWindowDesc = DEFAULT_ATTN_WINDOW_DESC
+    """Cross-chunk attention windows of all object groups, in object-group
+    order."""
+    mode: PrefetchMode = PrefetchMode.LOOKUP
+    """The prefetch intent (see :class:`PrefetchMode`).  ``WARM`` forces all
+    loaded keys permanent and acquires no read lock; ``LOOKUP`` defers
+    retention to the policy and read-locks loaded keys."""
+
+    # Lookup phase: adapter_idx -> task_id (removed as results arrive)
+    pending_lookup_tasks: dict[int, L2TaskId] = field(default_factory=dict)
+    # Lookup phase: adapter_idx -> bitmap (populated as results arrive)
+    lookup_results: dict[int, Bitmap] = field(default_factory=dict)
+
+    # Load phase: adapter_idx -> bitmap of key indices to load
+    load_plan: dict[int, Bitmap] = field(default_factory=dict)
+    # Load phase: adapter_idx -> task_id (removed as results arrive)
+    pending_load_tasks: dict[int, L2TaskId] = field(default_factory=dict)
+    # Load phase: adapter_idx -> L1 bytes reserved for that adapter's
+    # in-flight load.  Read by the inflight_load_memory_usage_bytes gauge.
+    load_bytes_by_adapter: dict[int, int] = field(default_factory=dict)
+    # Load phase: adapter_idx -> bitmap (populated as results arrive)
+    load_results: dict[int, Bitmap] = field(default_factory=dict)
+    # Load phase: keys that were write-reserved in L1
+    write_reserved_keys: list[ObjectKey] = field(default_factory=list)
+    write_reserved_objs: dict[ObjectKey, MemoryObj] = field(default_factory=dict)
+
+    def all_lookups_done(self) -> bool:
+        return len(self.pending_lookup_tasks) == 0
+
+    def all_loads_done(self) -> bool:
+        return len(self.pending_load_tasks) == 0
+
+
+class PrefetchController(StorageControllerInterface):
+    """
+    Asynchronously prefetches data from L2 adapters into L1 memory.
+
+    The controller:
+    1. Accepts prefetch requests via submit_prefetch_request (thread-safe).
+    2. Runs a background thread that submits lookup_and_lock to all adapters.
+    3. Uses PrefetchPolicy to compute a load plan from lookup results.
+    4. Reserves L1 write buffers and submits load tasks to adapters.
+    5. On completion, transitions loaded keys to read-locked state.
+    6. Reports the number of prefix hits via query_prefetch_result.
+
+    Args:
+        l1_manager: The L1 manager instance.
+        l2_adapters: List of L2 adapter instances.
+        adapter_descriptors: Descriptors for each L2 adapter (same order).
+        policy: The prefetch policy for load plan decisions.
+        max_in_flight: Maximum number of concurrent prefetch requests.
+    """
+
+    # Singleton dispatch for the in-flight load gauges: tests may construct
+    # multiple controllers but the OTel SDK only honors the first gauge
+    # registration, so the callbacks read from the most recently built
+    # instance via ``_gauge_target``.
+    _gauges_registered: bool = False
+    _gauge_target: "PrefetchController | None" = None
+
+    def __init__(
+        self,
+        l1_manager: L1Manager,
+        l2_adapters: list[L2AdapterInterface],
+        adapter_descriptors: list[AdapterDescriptor],
+        policy: PrefetchPolicy,
+        max_in_flight: int = 8,
+    ) -> None:
+        self._l1_manager = l1_manager
+        self._l2_adapters: dict[int, L2AdapterInterface] = {
+            desc.index: adapter
+            for desc, adapter in zip(adapter_descriptors, l2_adapters, strict=True)
+        }
+        self._adapter_descriptors: dict[int, AdapterDescriptor] = {
+            desc.index: desc for desc in adapter_descriptors
+        }
+        self._policy = policy
+        self._max_in_flight = max_in_flight
+
+        # Adapters that are being drained and will be removed after all
+        # the in-flight operations are done.
+        self._draining: dict[int, threading.Event] = {}
+
+        # Control-plane queue for runtime add/remove, used by the internal
+        # loop thread
+        self._adapter_ops_lock = threading.Lock()
+        self._pending_adapter_ops: list[AddAdapterOp | RemoveAdapterOp] = []
+        self._adapter_ctrl_efd = create_event_notifier()
+
+        # In-flight request tracking (background thread only)
+        self._in_flight_requests: dict[PrefetchRequestId, InFlightPrefetchRequest] = {}
+        self._pending_queue: list[
+            tuple[
+                PrefetchRequestId,
+                list[ObjectKey],
+                MemoryLayoutDesc,
+                int,
+                TrimPolicy,
+                AttnWindowDesc,
+                PrefetchMode,
+            ]
+        ] = []
+
+        # Shadow counters for status reporting (updated in background loop)
+        self._status_in_flight_count: int = 0
+        self._status_pending_count: int = 0
+        self._status_lookup_phase_count: int = 0
+        self._status_load_phase_count: int = 0
+
+        # Thread-safe submission queue (external -> background)
+        self._submission_lock = threading.Lock()
+        self._submission_queue: list[
+            tuple[
+                PrefetchRequestId,
+                list[ObjectKey],
+                MemoryLayoutDesc,
+                int,
+                TrimPolicy,
+                AttnWindowDesc,
+                PrefetchMode,
+            ]
+        ] = []
+        self._next_request_id: PrefetchRequestId = 0
+        self._submission_efd = create_event_notifier()
+
+        # Thread-safe lookup results (background -> external)
+        self._lookup_results_lock = threading.Lock()
+        self._completed_lookups: dict[PrefetchRequestId, int] = {}
+
+        # Thread-safe prefetch results (background -> external).  The condition
+        # variable lets a WAIT_PREFETCH_STATUS handler block until a result is
+        # published instead of busy-polling QUERY_PREFETCH_STATUS.
+        self._prefetch_results_lock = threading.Lock()
+        self._prefetch_results_cv = threading.Condition(self._prefetch_results_lock)
+        self._completed_results: dict[PrefetchRequestId, Bitmap] = {}
+
+        # Map eventfds to adapter indices for quick lookup in poll.
+        # Relies on the L2AdapterInterface contract that every adapter
+        # returns distinct fds for store/lookup/load, and no two adapters
+        # share an fd.  See the docstrings in L2AdapterInterface.
+        self._lookup_efd_to_adapter: dict[int, int] = {}
+        self._load_efd_to_adapter: dict[int, int] = {}
+        for adapter_id, adapter in self._l2_adapters.items():
+            self._lookup_efd_to_adapter[adapter.get_lookup_and_lock_event_fd()] = (
+                adapter_id
+            )
+            self._load_efd_to_adapter[adapter.get_load_event_fd()] = adapter_id
+
+        self._event_bus = get_event_bus()
+
+        PrefetchController._gauge_target = self
+        if not PrefetchController._gauges_registered:
+            PrefetchController._gauges_registered = True
+            register_gauge(
+                "lmcache.l2_prefetch",
+                "lmcache_mp.num_inflight_l2_loads",
+                "L2 -> L1 prefetch load tasks currently executing, per adapter",
+                lambda: (
+                    PrefetchController._gauge_target.get_inflight_loads_observations()
+                    if PrefetchController._gauge_target is not None
+                    else []
+                ),
+            )
+            register_gauge(
+                "lmcache.l2_prefetch",
+                "lmcache_mp.inflight_load_memory_usage_bytes",
+                "L1 bytes reserved by in-flight L2 -> L1 prefetch loads, per adapter",
+                lambda: (
+                    PrefetchController._gauge_target.get_inflight_load_bytes_observations()
+                    if PrefetchController._gauge_target is not None
+                    else []
+                ),
+            )
+            register_gauge(
+                "lmcache.l2_prefetch",
+                "lmcache_mp.l2_adapters",
+                (
+                    "Count of L2 adapters attached to the prefetch controller, "
+                    "tagged by ``state`` (active or draining)."
+                ),
+                lambda: (
+                    PrefetchController._gauge_target.get_adapter_state_observations()
+                    if PrefetchController._gauge_target is not None
+                    else []
+                ),
+            )
+
+        self._stop_flag = threading.Event()
+        self._thread = threading.Thread(
+            target=self._prefetch_loop,
+            daemon=True,
+        )
+
+    # =========================================================================
+    # External API (thread-safe)
+    # =========================================================================
+
+    def submit_prefetch_request(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+        extra_count: int = 0,
+        policy: TrimPolicy = TrimPolicy.PREFIX,
+        attn_desc: AttnWindowDesc = DEFAULT_ATTN_WINDOW_DESC,
+        mode: PrefetchMode = PrefetchMode.LOOKUP,
+    ) -> PrefetchRequestId:
+        """
+        Submit a prefetch request for the given keys.
+
+        Thread-safe. Can be called from any thread.
+
+        The retained subset of found keys is chosen by ``policy`` (see
+        :class:`TrimPolicy`).  With the default ``PREFIX`` policy, only the
+        **contiguous prefix** of found keys is loaded from L2: if L2 has keys
+        {0, 1, 3, 4} but not key 2, only keys {0, 1} are loaded because the gap
+        at index 2 breaks the prefix.  Keys outside the retained set are never
+        transferred, saving I/O bandwidth and L1 memory.  Use
+        :meth:`query_prefetch_result` to retrieve the retained set once the
+        request completes.
+
+        Args:
+            keys: List of object keys to prefetch from L2 into L1.
+                The ordering defines the prefix: index 0 is the first key.
+            layout_desc: Memory layout for L1 write buffer allocation.
+            extra_count: Extra read locks per key (on top of the default 1)
+                to acquire when transitioning loaded keys from write-locked
+                to read-locked.  Must match the ``extra_count`` used in the
+                corresponding ``submit_prefetch_task`` call so that all TP
+                workers can each consume one read lock.
+            policy: Which retained-subset policy to apply (see
+                :class:`TrimPolicy`).  Defaults to ``PREFIX``.
+            attn_desc: Cross-chunk attention windows of all object groups, in
+                object-group order.
+            mode: The prefetch intent (see :class:`PrefetchMode`).  ``WARM``
+                forces every loaded key permanent and acquires no read lock;
+                ``LOOKUP`` defers retention to the configured
+                :class:`PrefetchPolicy` and read-locks loaded keys.
+
+        Returns:
+            A request ID for tracking via query_prefetch_result.
+        """
+        with self._submission_lock:
+            request_id = self._next_request_id
+            self._next_request_id += 1
+            self._submission_queue.append(
+                (request_id, keys, layout_desc, extra_count, policy, attn_desc, mode)
+            )
+        self._submission_efd.notify()
+        return request_id
+
+    def query_lookup_result(self, request_id: PrefetchRequestId) -> int | None:
+        """
+        Query the keys that are found during the lookup for a specific request.
+
+        Thread-safe. Returns the prefix-hit count if the lookup phase
+        has completed, None if still in progress, or the prefetch request
+        has already been consumed by query_prefetch_result.
+
+        Args:
+            request_id: The request ID from submit_prefetch_request.
+
+        Returns:
+            Number of prefix hits from the lookup phase, or None if not yet complete
+            or if the request has already been consumed by a previous call to this
+            method.
+
+        Note:
+            This function does not pop the result. The caller need to make sure to call
+            the query_prefetch_result after calling this function, otherwise nobody
+            will clean up the completed lookups dictionary, causing memory leak.
+        """
+        with self._lookup_results_lock:
+            return self._completed_lookups.get(request_id, None)
+
+    def query_prefetch_result(self, request_id: PrefetchRequestId) -> Bitmap | None:
+        """
+        Query the result of a prefetch request.
+
+        Thread-safe. Returns the retained-key bitmap if the request
+        has completed, None if still in progress. Each result can only
+        be retrieved once (subsequent calls return None).
+
+        Args:
+            request_id: The request ID from submit_prefetch_request.
+
+        Returns:
+            Number of prefix hits, or None if not yet complete.
+
+        Note:
+            This function will pop the completed lookup results as well.
+            Therefore, the caller need to make sure that never call
+            query_lookup_result after calling this function, otherwise it will
+            get None forever.
+        """
+        with self._prefetch_results_lock:
+            result = self._completed_results.pop(request_id, None)
+        if result is not None:
+            with self._lookup_results_lock:
+                self._completed_lookups.pop(request_id, None)
+        return result
+
+    def wait_prefetch_result(
+        self, request_id: PrefetchRequestId, timeout: float
+    ) -> bool:
+        """
+        Block until a prefetch request's result is published, or until timeout.
+
+        Thread-safe. Lets a handler wait for prefetch completion instead of
+        busy-polling query_prefetch_result. Does not consume the result; the
+        caller still retrieves it via query_prefetch_result.
+
+        Args:
+            request_id: The request ID from submit_prefetch_request.
+            timeout: Maximum number of seconds to wait for the result.
+
+        Returns:
+            True if the result became available within the timeout, False if
+            the wait timed out.
+        """
+        with self._prefetch_results_cv:
+            return self._prefetch_results_cv.wait_for(
+                lambda: request_id in self._completed_results, timeout
+            )
+
+    def report_status(self) -> dict:
+        """Return a status dict for the prefetch controller."""
+        is_healthy = self._thread.is_alive()
+        with self._submission_lock:
+            submission_queue_size = len(self._submission_queue)
+        with self._prefetch_results_lock:
+            completed_results_count = len(self._completed_results)
+        return {
+            "is_healthy": is_healthy,
+            "thread_alive": is_healthy,
+            "max_in_flight": self._max_in_flight,
+            "submission_queue_size": submission_queue_size,
+            "pending_queue_size": self._status_pending_count,
+            "in_flight_request_count": self._status_in_flight_count,
+            "lookup_phase_count": self._status_lookup_phase_count,
+            "load_phase_count": self._status_load_phase_count,
+            "completed_results_count": completed_results_count,
+            "num_l2_adapters": len(self._l2_adapters),
+            "num_active_adapters": len(self._l2_adapters) - len(self._draining),
+            "num_draining_adapters": len(self._draining),
+        }
+
+    def get_adapter_state_observations(
+        self,
+    ) -> list[tuple[int | float, dict[str, object]]]:
+        """``(count, {"state": ...})`` tuples for the ``lmcache_mp.l2_adapters``
+        gauge. ``len()`` reads are GIL-atomic, safe from the OTel thread."""
+        num_draining = len(self._draining)
+        return [
+            (len(self._l2_adapters) - num_draining, {"state": "active"}),
+            (num_draining, {"state": "draining"}),
+        ]
+
+    def _snapshot_inflight_loads(self) -> dict[int, tuple[int, int]]:
+        """``{adapter_idx: (count, reserved_bytes)}`` for in-flight L2 -> L1
+        loads, computed via GIL-atomic ``dict.copy()`` snapshots so the
+        OTel reader thread can call this concurrently with the prefetch
+        loop without locking.
+        """
+        counts: dict[int, int] = defaultdict(int)
+        bytes_by_adapter: dict[int, int] = defaultdict(int)
+        for request in self._in_flight_requests.copy().values():
+            for idx, reserved in request.load_bytes_by_adapter.copy().items():
+                counts[idx] += 1
+                bytes_by_adapter[idx] += reserved
+        return {idx: (counts[idx], bytes_by_adapter[idx]) for idx in counts}
+
+    def get_inflight_loads_observations(
+        self,
+    ) -> list[tuple[int | float, dict[str, object]]]:
+        """Per-adapter ``(count, attributes)`` for the
+        ``lmcache_mp.num_inflight_l2_loads`` gauge."""
+        observations: list[tuple[int | float, dict[str, object]]] = []
+        for idx, (count, _) in self._snapshot_inflight_loads().items():
+            desc = self._adapter_descriptors.get(idx)
+            if desc is None:
+                continue
+            observations.append(
+                (count, {"l2_name": desc.type_name, "adapter_index": idx})
+            )
+        return observations
+
+    def get_inflight_load_bytes_observations(
+        self,
+    ) -> list[tuple[int | float, dict[str, object]]]:
+        """Per-adapter ``(reserved_bytes, attributes)`` for the
+        ``lmcache_mp.inflight_load_memory_usage_bytes`` gauge."""
+        observations: list[tuple[int | float, dict[str, object]]] = []
+        for idx, (_, reserved_bytes) in self._snapshot_inflight_loads().items():
+            desc = self._adapter_descriptors.get(idx)
+            if desc is None:
+                continue
+            observations.append(
+                (reserved_bytes, {"l2_name": desc.type_name, "adapter_index": idx})
+            )
+        return observations
+
+    # =========================================================================
+    # Lifecycle
+    # =========================================================================
+
+    def start(self) -> None:
+        """Start the background prefetch loop thread."""
+        logger.info("Starting PrefetchController...")
+        self._thread.start()
+
+    def stop(self) -> None:
+        """
+        Signal the loop to stop and wait for the thread to join.
+
+        Cleans up any in-flight requests (releases L1 write locks,
+        L2 locks) before returning.
+        """
+        self._stop_flag.set()
+        self._submission_efd.notify()
+        self._thread.join()
+        self._cleanup_in_flight_requests()
+        self._submission_efd.close()
+        self._adapter_ctrl_efd.close()
+
+    def add_adapter(
+        self,
+        adapter_id: int,
+        adapter: L2AdapterInterface,
+        descriptor: AdapterDescriptor,
+    ) -> None:
+        """Blocking function to add a new adapter into the prefetch
+        controller with the specified adapter ID and descriptor.
+
+        Args:
+            adapter_id: Stable id assigned by the StorageManager.
+            adapter: The adapter instance to attach.
+            descriptor: The adapter's descriptor (``descriptor.index`` must
+                equal ``adapter_id``).
+
+        Raises:
+            RuntimeError: If the background loop did not apply the op in
+                time (e.g. the loop is not running).
+        """
+        op = AddAdapterOp(
+            adapter_id=adapter_id,
+            adapter=adapter,
+            descriptor=descriptor,
+            done=threading.Event(),
+        )
+        with self._adapter_ops_lock:
+            self._pending_adapter_ops.append(op)
+        self._adapter_ctrl_efd.notify()
+        if not op.done.wait(timeout=PREFETCH_LOOP_POLL_TIMEOUT_MS / 1000 + 5.0):
+            raise RuntimeError(
+                f"PrefetchController did not attach adapter {adapter_id} in time"
+            )
+
+    def request_remove_adapter(self, adapter_id: int) -> threading.Event:
+        """Non-blocking function to request the removal of a L2 adapter
+        specified by the adapter ID.
+
+        New lookups stop routing to the adapter immediately; in-flight
+        requests are allowed to complete.
+
+        Args:
+            adapter_id: Stable id of the adapter to drain.
+
+        Returns:
+            An Event signaled when the adapter is fully drained.
+        """
+        op = RemoveAdapterOp(adapter_id=adapter_id, done=threading.Event())
+        with self._adapter_ops_lock:
+            self._pending_adapter_ops.append(op)
+        self._adapter_ctrl_efd.notify()
+        return op.done
+
+    # =========================================================================
+    # Background loop
+    # =========================================================================
+
+    def _prefetch_loop(self) -> None:
+        """
+        Main event-driven loop running in a background thread.
+
+        Uses select.poll() to wait on:
+        - The submission eventfd (new prefetch requests).
+        - Each L2 adapter's lookup eventfd (completed lookups).
+        - Each L2 adapter's load eventfd (completed loads).
+        """
+        poller = select.poll()
+        submission_fd = self._submission_efd.fileno()
+        poller.register(submission_fd, select.POLLIN)
+        poller.register(self._adapter_ctrl_efd.fileno(), select.POLLIN)
+        for efd in self._lookup_efd_to_adapter:
+            poller.register(efd, select.POLLIN)
+        for efd in self._load_efd_to_adapter:
+            poller.register(efd, select.POLLIN)
+
+        while not self._stop_flag.is_set():
+            # First, apply runtime add/remove of the L2 adapters.
+            self._apply_pending_adapter_ops(poller)
+
+            ready = poller.poll(PREFETCH_LOOP_POLL_TIMEOUT_MS)
+
+            signaled_adapters: dict[PrefetchPhase, set[int]] = {
+                phase: set() for phase in PrefetchPhase
+            }
+            for fd, events in ready:
+                if not (events & select.POLLIN):
+                    continue
+
+                try:
+                    consume_fd(fd)
+                except (OSError, BlockingIOError):
+                    pass
+
+                try:
+                    if fd == submission_fd:
+                        self._drain_submission_queue()
+                    elif fd in self._lookup_efd_to_adapter:
+                        signaled_adapters[PrefetchPhase.LOOKUP].add(
+                            self._lookup_efd_to_adapter[fd]
+                        )
+                    elif fd in self._load_efd_to_adapter:
+                        signaled_adapters[PrefetchPhase.PLAN_AND_LOAD].add(
+                            self._load_efd_to_adapter[fd]
+                        )
+                except Exception:
+                    logger.exception(
+                        "Unexpected error in prefetch loop while processing fd %d",
+                        fd,
+                    )
+
+            if any(signaled_adapters.values()):
+                for request in list(self._in_flight_requests.values()):
+                    try:
+                        self._advance_request(request, signaled_adapters)
+                    except Exception:
+                        logger.exception(
+                            "Unexpected error advancing in-flight prefetch request %d",
+                            request.request_id,
+                        )
+
+            try:
+                self._start_pending_requests()
+            except Exception:
+                logger.exception(
+                    "Unexpected error in prefetch loop while starting pending requests"
+                )
+
+            # Finalize any draining adapter no longer have any in-flight
+            # requests.
+            self._finalize_drained_adapters(poller)
+
+    def _apply_pending_adapter_ops(self, poller: "select.poll") -> None:
+        """Apply queued add/remove ops on the prefetch loop thread."""
+        with self._adapter_ops_lock:
+            ops = self._pending_adapter_ops
+            self._pending_adapter_ops = []
+        for op in ops:
+            if isinstance(op, AddAdapterOp):
+                self._l2_adapters[op.adapter_id] = op.adapter
+                self._adapter_descriptors[op.adapter_id] = op.descriptor
+                lookup_efd = op.adapter.get_lookup_and_lock_event_fd()
+                load_efd = op.adapter.get_load_event_fd()
+                self._lookup_efd_to_adapter[lookup_efd] = op.adapter_id
+                self._load_efd_to_adapter[load_efd] = op.adapter_id
+                poller.register(lookup_efd, select.POLLIN)
+                poller.register(load_efd, select.POLLIN)
+                logger.info("PrefetchController attached adapter %d", op.adapter_id)
+                op.done.set()
+            elif isinstance(op, RemoveAdapterOp):
+                if op.adapter_id not in self._l2_adapters:
+                    op.done.set()
+                    continue
+                # Mark draining; new lookups skip it. The adapter stays
+                # registered so in-flight requests can still complete.
+                self._draining[op.adapter_id] = op.done
+                logger.info(
+                    "PrefetchController draining adapter %d (no new lookups routed)",
+                    op.adapter_id,
+                )
+
+    def _adapter_in_use(self, adapter_id: int) -> bool:
+        """True if any in-flight request still references ``adapter_id``."""
+        for request in self._in_flight_requests.values():
+            if (
+                adapter_id in request.pending_lookup_tasks
+                or adapter_id in request.pending_load_tasks
+                or adapter_id in request.load_plan
+                or adapter_id in request.lookup_results
+            ):
+                return True
+        return False
+
+    def _finalize_drained_adapters(self, poller: "select.poll") -> None:
+        """Detach draining adapters no longer referenced by any request."""
+        for adapter_id in list(self._draining):
+            if self._adapter_in_use(adapter_id):
+                continue
+            adapter = self._l2_adapters.pop(adapter_id)
+            self._adapter_descriptors.pop(adapter_id, None)
+            lookup_efd = adapter.get_lookup_and_lock_event_fd()
+            load_efd = adapter.get_load_event_fd()
+            self._lookup_efd_to_adapter.pop(lookup_efd, None)
+            self._load_efd_to_adapter.pop(load_efd, None)
+            for efd in (lookup_efd, load_efd):
+                try:
+                    poller.unregister(efd)
+                except (KeyError, OSError):
+                    pass
+            done = self._draining.pop(adapter_id)
+            logger.info("PrefetchController detached adapter %d", adapter_id)
+            done.set()
+
+    def _drain_submission_queue(self) -> None:
+        """Move items from the thread-safe submission queue to the
+        pending queue."""
+        with self._submission_lock:
+            items = self._submission_queue
+            self._submission_queue = []
+        self._pending_queue.extend(items)
+        self._status_pending_count += len(items)
+
+    def _start_pending_requests(self) -> None:
+        """Start pending requests up to the max in-flight limit."""
+        while (
+            self._pending_queue and len(self._in_flight_requests) < self._max_in_flight
+        ):
+            request_id, keys, layout_desc, extra_count, policy, attn_desc, mode = (
+                self._pending_queue.pop(0)
+            )
+            self._status_pending_count -= 1
+            self._start_lookup_phase(
+                request_id, keys, layout_desc, extra_count, policy, attn_desc, mode
+            )
+
+    # =========================================================================
+    # Lookup phase
+    # =========================================================================
+
+    def _start_lookup_phase(
+        self,
+        request_id: PrefetchRequestId,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+        extra_count: int = 0,
+        policy: TrimPolicy = TrimPolicy.PREFIX,
+        attn_desc: AttnWindowDesc = DEFAULT_ATTN_WINDOW_DESC,
+        mode: PrefetchMode = PrefetchMode.LOOKUP,
+    ) -> None:
+        """Submit lookup_and_lock to all live (non-draining) adapters for a
+        new request."""
+        # Skip adapters being drained so a new request never locks keys on
+        # an adapter that is on its way out.
+        routing_adapters = {
+            adapter_id: adapter
+            for adapter_id, adapter in self._l2_adapters.items()
+            if adapter_id not in self._draining
+        }
+        if not routing_adapters:
+            self._complete_request(request_id, Bitmap(len(keys)))
+            return
+
+        pending_lookup_tasks: dict[int, L2TaskId] = {}
+        for adapter_id, adapter in routing_adapters.items():
+            task_id = adapter.submit_lookup_and_lock_task(keys, layout_desc)
+            pending_lookup_tasks[adapter_id] = task_id
+
+        request = InFlightPrefetchRequest(
+            request_id=request_id,
+            keys=keys,
+            layout_desc=layout_desc,
+            phase=PrefetchPhase.LOOKUP,
+            extra_count=extra_count,
+            policy=policy,
+            attn_desc=attn_desc,
+            mode=mode,
+            pending_lookup_tasks=pending_lookup_tasks,
+        )
+        self._in_flight_requests[request_id] = request
+        self._status_in_flight_count += 1
+        self._status_lookup_phase_count += 1
+
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_SUBMITTED,
+                metadata={
+                    "request_id": request_id,
+                    "key_count": len(keys),
+                    "adapter_count": len(pending_lookup_tasks),
+                    "key_count_per_salt": Counter(k.cache_salt for k in keys),
+                },
+            )
+        )
+
+    # =========================================================================
+    # Load phase
+    # =========================================================================
+    def _transition_to_load_phase(self, request: InFlightPrefetchRequest) -> None:
+        """Compute load plan, reserve L1 buffers, and submit load tasks."""
+        request.phase = PrefetchPhase.PLAN_AND_LOAD
+        self._status_lookup_phase_count -= 1
+        self._status_load_phase_count += 1
+
+        # Step 1: get load plan from policy. Exclude draining adapters so no
+        # new load targets them; any keys they locked during lookup fall
+        # outside the plan and get unlocked in _unlock_unneeded_keys.
+        routing_descriptors = [
+            desc
+            for adapter_id, desc in self._adapter_descriptors.items()
+            if adapter_id not in self._draining
+        ]
+        load_plan = self._policy.select_load_plan(
+            request.keys,
+            request.lookup_results,
+            routing_descriptors,
+        )
+
+        # Step 2: trim the load plan to the policy's retained subset
+        num_keys = len(request.keys)
+        merged_lookup = merge_bitmaps(load_plan.values(), num_keys)
+        retained = build_trim_mask(merged_lookup, num_keys, request.policy)
+        trimmed_plan = trim_load_plan_with_mask(load_plan, retained)
+
+        if not trimmed_plan:
+            # Nothing to load after trimming. Unlock all lookup locks and
+            # complete with an empty retained set.
+            self._unlock_all_lookups(request)
+            self._update_lookup_results(request.request_id, 0)
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_LOOKUP_COMPLETED,
+                    metadata={
+                        "request_id": request.request_id,
+                        "prefix_hit_count": 0,
+                    },
+                )
+            )
+            self._complete_request(request.request_id, Bitmap(num_keys))
+            return
+
+        # Step 3: reserve L1 write buffers
+        merged_bitmap = merge_bitmaps(trimmed_plan.values(), len(request.keys))
+        keys_to_reserve = merged_bitmap.gather(request.keys)
+        l1_mgr = self._l1_manager
+
+        # WARM retains every loaded key; LOOKUP follows the configured policy.
+        if request.mode is PrefetchMode.WARM:
+            retentions = [True] * len(keys_to_reserve)
+        else:
+            retentions = self._policy.select_l1_retentions(
+                keys_to_reserve,
+            )
+        write_results = l1_mgr.reserve_write(
+            keys=keys_to_reserve,
+            is_temporary=[not r for r in retentions],
+            layout_desc=request.layout_desc,
+            mode="new",
+        )
+
+        # Step 4: filter to successfully reserved keys
+        reserved_key_set: set[ObjectKey] = set()
+        oom_keys: list[ObjectKey] = []
+        for key, (err, mem_obj) in write_results.items():
+            if err == L1Error.SUCCESS and mem_obj is not None:
+                request.write_reserved_keys.append(key)
+                request.write_reserved_objs[key] = mem_obj
+                reserved_key_set.add(key)
+            else:
+                if err == L1Error.OUT_OF_MEMORY:
+                    oom_keys.append(key)
+                logger.debug(
+                    "Prefetch request %d: reserve write failed for %s: %s",
+                    request.request_id,
+                    key,
+                    err,
+                )
+
+        if oom_keys:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L1_ALLOCATION_FAILED,
+                    metadata={"during": "l2_prefetch", "keys": oom_keys},
+                )
+            )
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_FAILED,
+                    metadata={"reason": "l1_oom", "keys": oom_keys},
+                )
+            )
+
+        # Step 5: recompute load plan excluding failed reservations
+        reserved_bitmap = Bitmap(num_keys)
+        for i, key in enumerate(request.keys):
+            if key in reserved_key_set:
+                reserved_bitmap.set(i)
+
+        retained = build_trim_mask(reserved_bitmap, num_keys, request.policy)
+        trimmed_plan = trim_load_plan_with_mask(load_plan, retained)
+        request.load_plan = trimmed_plan
+
+        ## Step 6: phase 1 unlock — keys locked in lookup but not in plan
+        self._unlock_unneeded_keys(request)
+
+        if not trimmed_plan:
+            # Nothing loadable after filtering
+            if request.write_reserved_keys:
+                l1_mgr.finish_write(request.write_reserved_keys)
+                l1_mgr.delete(request.write_reserved_keys)
+            self._update_lookup_results(request.request_id, 0)
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_LOOKUP_COMPLETED,
+                    metadata={
+                        "request_id": request.request_id,
+                        "prefix_hit_count": 0,
+                    },
+                )
+            )
+            self._complete_request(request.request_id, Bitmap(num_keys))
+            return
+
+        ## Step 7: submit load tasks per adapter
+        for adapter_idx, bitmap in trimmed_plan.items():
+            per_adapter_keys = bitmap.gather(request.keys)
+            per_adapter_objs = [
+                request.write_reserved_objs[key] for key in per_adapter_keys
+            ]
+            task_id = self._l2_adapters[adapter_idx].submit_load_task(
+                per_adapter_keys, per_adapter_objs
+            )
+            request.pending_load_tasks[adapter_idx] = task_id
+            # Per-adapter byte accounting for L2_LOAD_TASK_* throughput
+            # events.  Uniform layout per chunk -> size * count.
+            total_bytes = (
+                per_adapter_objs[0].get_size() * len(per_adapter_objs)
+                if per_adapter_objs
+                else 0
+            )
+            request.load_bytes_by_adapter[adapter_idx] = total_bytes
+
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_LOAD_TASK_SUBMITTED,
+                    metadata={
+                        "request_id": request.request_id,
+                        "adapter_index": adapter_idx,
+                        "task_id": task_id,
+                        "l2_name": self._adapter_descriptors[adapter_idx].type_name,
+                        "key_count": len(per_adapter_keys),
+                        "total_bytes": total_bytes,
+                    },
+                )
+            )
+
+        ## Step 8: update the lookup result based on the final load plan
+        self._update_lookup_results(request.request_id, retained.count_leading_ones())
+
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_COMPLETED,
+                metadata={
+                    "request_id": request.request_id,
+                    "prefix_hit_count": retained.count_leading_ones(),
+                },
+            )
+        )
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_SUBMITTED,
+                metadata={
+                    "request_id": request.request_id,
+                    "key_count": len(reserved_key_set),
+                    "adapter_count": len(trimmed_plan),
+                    "key_count_per_salt": Counter(
+                        k.cache_salt for k in reserved_key_set
+                    ),
+                },
+            )
+        )
+
+        logger.debug(
+            "Prefetch request %d: submitted load tasks to %d adapters for %d keys",
+            request.request_id,
+            len(trimmed_plan),
+            len(reserved_key_set),
+        )
+
+    def _update_lookup_results(
+        self, request_id: PrefetchRequestId, prefix_hit_count: int
+    ) -> None:
+        """Store the prefix-hit count from the lookup phase."""
+        with self._lookup_results_lock:
+            self._completed_lookups[request_id] = prefix_hit_count
+
+    def _advance_request(
+        self,
+        request: InFlightPrefetchRequest,
+        signaled_adapters: dict[PrefetchPhase, set[int]],
+    ) -> None:
+        """State-transition dispatcher by phase: poll signaled adapters for
+        the request's current phase via the per-phase helper, then trigger
+        the phase transition when done."""
+        phase_adapters = signaled_adapters[request.phase]
+        if not phase_adapters:
+            return
+        if request.phase == PrefetchPhase.LOOKUP:
+            self._poll_lookup_results(request, phase_adapters)
+            if request.all_lookups_done():
+                self._transition_to_load_phase(request)
+        elif request.phase == PrefetchPhase.PLAN_AND_LOAD:
+            self._poll_load_results(request, phase_adapters)
+            if request.all_loads_done():
+                self._finalize_load(request)
+
+    def _poll_lookup_results(
+        self,
+        request: InFlightPrefetchRequest,
+        signaled_adapters: set[int],
+    ) -> None:
+        """Query pending lookup-and-lock results from signaled adapters."""
+        for adapter_idx in list(request.pending_lookup_tasks):
+            if adapter_idx not in signaled_adapters:
+                continue
+            task_id = request.pending_lookup_tasks[adapter_idx]
+            result = self._l2_adapters[adapter_idx].query_lookup_and_lock_result(
+                task_id
+            )
+            if result is None:
+                continue
+            request.lookup_results[adapter_idx] = result
+            del request.pending_lookup_tasks[adapter_idx]
+
+    def _poll_load_results(
+        self,
+        request: InFlightPrefetchRequest,
+        signaled_adapters: set[int],
+    ) -> None:
+        """Query pending load results from signaled adapters."""
+        for adapter_idx in list(request.pending_load_tasks):
+            if adapter_idx not in signaled_adapters:
+                continue
+            task_id = request.pending_load_tasks[adapter_idx]
+            result = self._l2_adapters[adapter_idx].query_load_result(task_id)
+            if result is None:
+                continue
+            request.load_results[adapter_idx] = result
+            del request.pending_load_tasks[adapter_idx]
+            request.load_bytes_by_adapter.pop(adapter_idx, None)
+
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_LOAD_TASK_COMPLETED,
+                    metadata={
+                        "request_id": request.request_id,
+                        "adapter_index": adapter_idx,
+                        "task_id": task_id,
+                        "l2_name": self._adapter_descriptors[adapter_idx].type_name,
+                    },
+                )
+            )
+
+    def _finalize_load(self, request: InFlightPrefetchRequest) -> None:
+        """
+        Finalize a completed load: build result bitmap, transition L1
+        state, release read locks outside the retained set, and report the
+        retained-key bitmap.
+
+        Partial load failures can create gaps, so a loaded key may fall
+        outside the policy's retained set; its read lock must be released.
+        """
+        num_keys = len(request.keys)
+
+        # Scatter per-adapter local load results into global positions.
+        # Each adapter's load bitmap is locally indexed (size == adapter's
+        # key count).  The plan bitmap maps local → global indices via
+        # get_indices_list().
+        result_bitmap = Bitmap(num_keys)
+        for adapter_idx, plan_bitmap in request.load_plan.items():
+            load_bitmap = request.load_results.get(adapter_idx)
+            if load_bitmap is None:
+                continue
+            plan_indices = plan_bitmap.get_indices_list()
+            for global_i in load_bitmap.gather(plan_indices):
+                result_bitmap.set(global_i)
+
+        # Separate loaded vs. failed among write-reserved keys
+        loaded_keys: list[ObjectKey] = result_bitmap.gather(request.keys)
+        loaded_set = set(loaded_keys)
+        failed_keys = [k for k in request.write_reserved_keys if k not in loaded_set]
+
+        # Phase 2 unlock: release L2 locks for all keys in the load plan
+        self._unlock_all_plan_keys(request)
+
+        l1_mgr = self._l1_manager
+
+        # Transition loaded keys out of write-locked state.
+        if loaded_keys:
+            if request.mode is PrefetchMode.WARM:
+                # Warm: make ready, pin nothing.
+                l1_mgr.finish_write(loaded_keys)
+            else:
+                # write-locked -> read-locked; extra_count so each TP worker
+                # gets its own read lock.
+                l1_mgr.finish_write_and_reserve_read(
+                    loaded_keys, extra_count=request.extra_count
+                )
+
+        # Clean up failed keys
+        if failed_keys:
+            l1_mgr.finish_write(failed_keys)
+            l1_mgr.delete(failed_keys)
+
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_COMPLETED,
+                metadata={
+                    "request_id": request.request_id,
+                    "loaded_count": len(loaded_keys),
+                    "failed_count": len(failed_keys),
+                    "key_count_per_salt": Counter(k.cache_salt for k in loaded_keys),
+                },
+            )
+        )
+
+        # L2 prefetch-failure anomaly reporting: keys were reserved in L1
+        # (expected to load from L2) but did not appear in the load bitmap.
+        # Classified as ``not_found`` — the serde_failure reason will be
+        # added once the serde PR lands and adapters can distinguish
+        # deserialization errors from missing objects.
+        if failed_keys:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_FAILED,
+                    metadata={"reason": "not_found", "keys": failed_keys},
+                )
+            )
+
+        # Release read locks for any loaded key outside the retained set
+        # (partial load failures can create gaps).
+        retained = build_trim_mask(result_bitmap, num_keys, request.policy)
+        released_bitmap = result_bitmap & (~retained)
+        released = released_bitmap.gather(request.keys)
+        if released:
+            l1_mgr.finish_read(released, extra_count=request.extra_count)
+
+        self._complete_request(request.request_id, retained)
+
+    # =========================================================================
+    # Unlock helpers
+    # =========================================================================
+
+    def _unlock_unneeded_keys(self, request: InFlightPrefetchRequest) -> None:
+        """Phase 1 unlock: keys locked in lookup but not in the load plan."""
+        for adapter_idx, lookup_bitmap in request.lookup_results.items():
+            plan_bitmap = request.load_plan.get(adapter_idx, Bitmap(len(request.keys)))
+            to_unlock_bitmap = lookup_bitmap & (~plan_bitmap)
+            unlock_keys = to_unlock_bitmap.gather(request.keys)
+            if unlock_keys:
+                self._l2_adapters[adapter_idx].submit_unlock(unlock_keys)
+
+    def _unlock_all_plan_keys(self, request: InFlightPrefetchRequest) -> None:
+        """Phase 2 unlock: release L2 locks for all keys in the load plan."""
+        for adapter_idx, load_bitmap in request.load_plan.items():
+            unlock_keys = load_bitmap.gather(request.keys)
+            self._l2_adapters[adapter_idx].submit_unlock(unlock_keys)
+
+    def _unlock_all_lookups(self, request: InFlightPrefetchRequest) -> None:
+        """Unlock all keys locked during lookup (nothing to load case)."""
+        for adapter_idx, lookup_bitmap in request.lookup_results.items():
+            unlock_keys = lookup_bitmap.gather(request.keys)
+            if unlock_keys:
+                self._l2_adapters[adapter_idx].submit_unlock(unlock_keys)
+
+    # =========================================================================
+    # Completion and cleanup
+    # =========================================================================
+
+    def _complete_request(self, request_id: PrefetchRequestId, result: Bitmap) -> None:
+        """Store the retained-key bitmap and remove from in-flight tracking."""
+        with self._prefetch_results_lock:
+            self._completed_results[request_id] = result
+            # Wake any WAIT_PREFETCH_STATUS handler blocked on this result.
+            self._prefetch_results_cv.notify_all()
+        removed = self._in_flight_requests.pop(request_id, None)
+        if removed is not None:
+            self._status_in_flight_count -= 1
+            if removed.phase == PrefetchPhase.LOOKUP:
+                self._status_lookup_phase_count -= 1
+            elif removed.phase == PrefetchPhase.PLAN_AND_LOAD:
+                self._status_load_phase_count -= 1
+        logger.debug(
+            "Prefetch request %d completed: %d retained keys",
+            request_id,
+            result.popcount(),
+        )
+
+    def _cleanup_in_flight_requests(self) -> None:
+        """Release resources for any in-flight requests during shutdown."""
+        l1_mgr = self._l1_manager
+        for request in self._in_flight_requests.values():
+            if request.phase == PrefetchPhase.PLAN_AND_LOAD:
+                if request.write_reserved_keys:
+                    l1_mgr.finish_write(request.write_reserved_keys)
+                    l1_mgr.delete(request.write_reserved_keys)
+                self._unlock_all_plan_keys(request)
+            elif request.phase == PrefetchPhase.LOOKUP:
+                self._unlock_all_lookups(request)
+            logger.warning(
+                "Cleaning up in-flight prefetch request %d (%d keys).",
+                request.request_id,
+                len(request.keys),
+            )
+        self._in_flight_requests.clear()
diff --git a/lmcache/v1/distributed/storage_controllers/prefetch_policy.py b/lmcache/v1/distributed/storage_controllers/prefetch_policy.py
new file mode 100644
index 0000000..169267d
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/prefetch_policy.py
@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Prefetch policy interface and default implementation for L2-to-L1 load decisions.
+
+The prefetch policy decides which L2 adapter should load each key when multiple
+adapters have the same key. It receives lookup results (bitmaps) from all adapters
+and produces a load plan mapping each adapter to the key indices it should load.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+)
+
+
+class PrefetchPolicy(ABC):
+    """
+    Abstract interface for prefetch load-plan decisions.
+
+    The prefetch policy is called by the PrefetchController after all L2
+    adapters have completed their lookup_and_lock operations. Given the
+    lookup results, it decides which adapter should load which keys.
+    """
+
+    @abstractmethod
+    def select_load_plan(
+        self,
+        keys: list[ObjectKey],
+        lookup_results: dict[int, Bitmap],
+        adapters: list[AdapterDescriptor],
+    ) -> dict[int, Bitmap]:
+        """
+        Decide which adapter loads which keys.
+
+        Args:
+            keys: Full list of keys being prefetched from L2.
+            lookup_results: Mapping from adapter index to Bitmap.
+                A set bit at position i means the adapter has keys[i].
+            adapters: Descriptors of available L2 adapters.
+
+        Returns:
+            Mapping from adapter index to a bitmap telling which keys that
+            the adapter should load. The returned bitmaps should not
+            overlap, and the union of all returned bitmaps should be a subset
+            of the union of the input bitmaps.
+        """
+
+    def select_l1_retentions(
+        self,
+        keys: list[ObjectKey],
+    ) -> list[bool]:
+        """Determine which keys to retain in L1 after prefetched
+        objects are consumed.
+
+        Called by PrefetchController just before
+        ``l1_mgr.reserve_write`` to build the ``is_temporary``
+        flags.  A ``True`` value means the key is retained
+        (permanent); ``False`` means it is temporary and will be
+        deleted after the reader finishes.
+
+        The default implementation marks all keys as temporary
+        (not retained).  Override in subclasses to implement
+        hot-cache or selective-retention strategies.
+
+        Args:
+            keys: Keys about to be written into L1.
+
+        Returns:
+            A list of bools with the same length as *keys*.
+            ``True`` = retain (permanent), ``False`` = temporary.
+        """
+        return [False] * len(keys)
+
+
+# -----------------------------------------------------------------------------
+# Registry: prefetch policy name -> policy class
+# -----------------------------------------------------------------------------
+
+_PREFETCH_POLICY_REGISTRY: dict[str, type[PrefetchPolicy]] = {}
+
+
+def register_prefetch_policy(
+    name: str,
+    policy_cls: type[PrefetchPolicy],
+) -> None:
+    """
+    Register a prefetch policy class under a name.
+
+    Each policy module should call this at import time.
+
+    Args:
+        name: Policy name (e.g. "default").
+        policy_cls: A concrete PrefetchPolicy subclass.
+    """
+    if name in _PREFETCH_POLICY_REGISTRY:
+        raise ValueError(f"Prefetch policy already registered: {name!r}")
+    _PREFETCH_POLICY_REGISTRY[name] = policy_cls
+
+
+def get_registered_prefetch_policies() -> list[str]:
+    """Return the list of registered prefetch policy names."""
+    return list(_PREFETCH_POLICY_REGISTRY)
+
+
+def create_prefetch_policy(name: str) -> PrefetchPolicy:
+    """
+    Create a prefetch policy instance by name.
+
+    Args:
+        name: Registered policy name.
+
+    Returns:
+        A new PrefetchPolicy instance.
+
+    Raises:
+        ValueError: If no policy is registered under the given name.
+    """
+    if name not in _PREFETCH_POLICY_REGISTRY:
+        known = ", ".join(sorted(_PREFETCH_POLICY_REGISTRY)) or "(none)"
+        raise ValueError(f"Unknown prefetch policy {name!r}. Known: {known}")
+    return _PREFETCH_POLICY_REGISTRY[name]()
+
+
+class DefaultPrefetchPolicy(PrefetchPolicy):
+    """
+    Default prefetch policy: for each key, pick the first adapter
+    (lowest index) that has it.
+    """
+
+    def select_load_plan(
+        self,
+        keys: list[ObjectKey],
+        lookup_results: dict[int, Bitmap],
+        adapters: list[AdapterDescriptor],
+    ) -> dict[int, Bitmap]:
+        """
+        Assign each key to the first adapter (by index) that has it.
+
+        Args:
+            keys: Full list of keys being prefetched.
+            lookup_results: Adapter index -> Bitmap of lookup hits.
+            adapters: Descriptors of available L2 adapters.
+
+        Returns:
+            Mapping from adapter index to key bitmaps. Each key goes
+            to the lowest-indexed adapter that reported having it.
+        """
+        plan: dict[int, Bitmap] = {}
+        global_bitmap = Bitmap(len(keys))
+        for bitmap in lookup_results.values():
+            global_bitmap |= bitmap
+
+        for ad in sorted(adapters, key=lambda a: a.index):
+            curr_bitmap = lookup_results.get(ad.index)
+            if curr_bitmap is None:
+                continue
+
+            local_bitmap = global_bitmap & curr_bitmap
+            global_bitmap &= ~local_bitmap
+            if local_bitmap.popcount() == 0:
+                continue
+
+            plan[ad.index] = local_bitmap
+
+        return plan
+
+
+class RetainPrefetchPolicy(DefaultPrefetchPolicy):
+    """Prefetch policy that retains all prefetched keys in L1.
+
+    Inherits ``select_load_plan`` from ``DefaultPrefetchPolicy``
+    (first-adapter-wins) and only overrides the L1 retention
+    decision: all prefetched keys become permanent.
+
+    Use this when prefetched data is likely to be reused by
+    subsequent requests (e.g. shared system-prompt chunks).
+    """
+
+    def select_l1_retentions(
+        self,
+        keys: list[ObjectKey],
+    ) -> list[bool]:
+        """Retain all prefetched keys permanently in L1."""
+        return [True] * len(keys)
+
+
+register_prefetch_policy("default", DefaultPrefetchPolicy)
+register_prefetch_policy("retain", RetainPrefetchPolicy)
diff --git a/lmcache/v1/distributed/storage_controllers/store_controller.py b/lmcache/v1/distributed/storage_controllers/store_controller.py
new file mode 100644
index 0000000..44c20ee
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/store_controller.py
@@ -0,0 +1,797 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Store Controller: asynchronously copies data from L1 to L2 after writes complete.
+
+The controller runs a background thread with an event-driven loop that:
+1. Listens for L1 write-completion events via StoreListener.
+2. Submits store tasks to L2 adapters based on StorePolicy decisions.
+3. Monitors L2 task completion via event fds.
+4. Releases L1 read locks and optionally deletes keys from L1.
+"""
+
+# Standard
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+import enum
+import select
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L1ManagerListener
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface, L2TaskId
+from lmcache.v1.distributed.storage_controller import StorageControllerInterface
+from lmcache.v1.distributed.storage_controllers.adapter_lifecycle import (
+    AddAdapterOp,
+    RemoveAdapterOp,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+    StorePolicy,
+)
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+from lmcache.v1.mp_observability.otel_init import register_gauge
+from lmcache.v1.platform import (
+    consume_fd,
+    create_event_notifier,
+)
+
+logger = init_logger(__name__)
+
+# Poll timeout in milliseconds for the store loop
+STORE_LOOP_POLL_TIMEOUT_MS = 500
+
+
+def _group_keys_by_shape(
+    keys: list[ObjectKey],
+) -> dict[tuple, list[ObjectKey]]:
+    """Group ``keys`` by the fields that determine their KV cache shape.
+
+    Each bucket shares a single ``(shape, dtype)``, so each bucket can be
+    submitted as one ``submit_store_task`` call. Today the shape is pinned
+    by ``(model_name, kv_rank)`` — ``kv_rank`` packs ``world_size`` and
+    parallelism config, so different TP/PP setups land in different
+    buckets. Extend the grouping tuple when a new shape-affecting field is
+    added to ``ObjectKey``.
+    """
+    groups: dict[tuple, list[ObjectKey]] = defaultdict(list)
+    for key in keys:
+        groups[(key.model_name, key.kv_rank)].append(key)
+    return groups
+
+
+# Helper classes (module-level, before main class)
+
+
+class StoreListener(L1ManagerListener):
+    """
+    Listener that receives L1 write-completion callbacks and enqueues
+    keys for the StoreController's background loop.
+
+    The ``on_keys_write_finished`` callback is invoked inside L1Manager's
+    lock, so it must be non-blocking. It appends keys to an internal list
+    and signals an eventfd to wake up the controller's select.poll().
+    """
+
+    def __init__(self) -> None:
+        self._pending_keys: list[ObjectKey] = []
+        self._lock = threading.Lock()
+        self._event_fd = create_event_notifier()
+
+    def get_event_fd(self) -> int:
+        """
+        Return the notifier fd that is signaled when new keys are
+        available.
+
+        Returns:
+            int: The readable file descriptor for poller registration.
+        """
+        return self._event_fd.fileno()
+
+    def notify(self) -> None:
+        """Signal the notifier to wake any blocked poll() waiter."""
+        self._event_fd.notify()
+
+    def pop_pending_keys(self) -> list[ObjectKey]:
+        """
+        Pop all pending keys from the queue.
+
+        This is non-blocking and should be called by the StoreController's
+        main loop after select.poll() indicates the eventfd is ready.
+
+        Returns:
+            list[ObjectKey]: All keys enqueued since the last pop.
+        """
+        with self._lock:
+            keys = self._pending_keys
+            self._pending_keys = []
+        return keys
+
+    def pending_count(self) -> int:
+        """Return the number of pending keys waiting to be processed."""
+        with self._lock:
+            return len(self._pending_keys)
+
+    # L1ManagerListener implementation
+
+    def on_l1_keys_write_finished(self, keys: list[ObjectKey]) -> None:
+        """
+        Enqueue keys and signal the notifier.
+
+        Called inside L1Manager's lock. Must be fast and must not
+        call any L1Manager methods (would deadlock).
+
+        Args:
+            keys (list[ObjectKey]): Keys that finished writing.
+        """
+        with self._lock:
+            self._pending_keys.extend(keys)
+        self._event_fd.notify()
+
+    def on_l1_keys_reserved_read(self, keys: list[ObjectKey]) -> None:
+        pass
+
+    def on_l1_keys_read_finished(self, keys: list[ObjectKey]) -> None:
+        pass
+
+    def on_l1_keys_reserved_write(self, keys: list[ObjectKey]) -> None:
+        pass
+
+    def on_l1_keys_deleted_by_manager(self, keys: list[ObjectKey]) -> None:
+        pass
+
+    def on_l1_keys_finish_write_and_reserve_read(self, keys: list[ObjectKey]) -> None:
+        # No op here because we don't want to trigger store when the
+        # objects are prefetched to L1.
+        pass
+
+    def on_l1_keys_accessed(self, keys: list[ObjectKey]) -> None:
+        pass
+
+    def close(self) -> None:
+        """Close the notifier."""
+        self._event_fd.close()
+
+
+class StorePhase(enum.Enum):
+    """Phases a store task may be in. Currently there is only an
+    L2_STORE phase; new phases (e.g. verify, ack) would be added here and
+    threaded through ``signaled_adapters`` without changing
+    ``_advance_request``'s signature."""
+
+    L2_STORE = enum.auto()
+
+
+@dataclass
+class InFlightStoreTask:
+    """
+    Tracks a single submitted L2 store task so the controller can
+    release L1 read locks and perform cleanup when it completes.
+    """
+
+    adapter_index: int
+    """Which L2 adapter this task was submitted to."""
+
+    keys: list[ObjectKey]
+    """All keys that were submitted in this store task."""
+
+    read_locked_keys: list[ObjectKey]
+    """The subset of keys for which reserve_read succeeded
+    (i.e., keys holding an L1 read lock that must be released)."""
+
+    l2_store_result: bool | None = None
+    """L2 outcome (True=success, False=failure, None=still in flight)."""
+
+    l2_bytes_transferred: int = 0
+    """Bytes actually transferred by the adapter for this task."""
+
+
+# Main class
+
+
+class StoreController(StorageControllerInterface):
+    """
+    Asynchronously stores L1 data to L2 adapters after write completion.
+
+    The controller:
+    1. Registers a StoreListener with L1Manager to receive
+       on_keys_write_finished callbacks.
+    2. Runs a background thread with an event-driven loop using
+       select.poll() on the listener eventfd and all L2 adapter
+       store eventfds.
+    3. On new keys: consults StorePolicy to decide targets,
+       calls reserve_read to get MemoryObjs, and submits store
+       tasks to L2 adapters.
+    4. On L2 task completion: releases read locks, optionally
+       deletes keys from L1 per policy.
+
+    Args:
+        l1_manager: The L1 manager instance.
+        l2_adapters: List of L2 adapter instances.
+        adapter_descriptors: Descriptors for each L2 adapter (same order).
+        policy: The store policy for deciding targets and deletions.
+    """
+
+    # Singleton dispatch for ``lmcache_mp.num_inflight_l2_stores``: tests may
+    # construct multiple controllers but the OTel SDK only honors the first
+    # gauge registration, so the callback reads from the most recently built
+    # instance via ``_gauge_target``.
+    _gauge_registered: bool = False
+    _gauge_target: "StoreController | None" = None
+
+    def __init__(
+        self,
+        l1_manager: L1Manager,
+        l2_adapters: list[L2AdapterInterface],
+        adapter_descriptors: list[AdapterDescriptor],
+        policy: StorePolicy,
+    ) -> None:
+        self._l1_manager = l1_manager
+        self._l2_adapters: dict[int, L2AdapterInterface] = {
+            desc.index: adapter
+            for desc, adapter in zip(adapter_descriptors, l2_adapters, strict=True)
+        }
+        self._adapter_descriptors: dict[int, AdapterDescriptor] = {
+            desc.index: desc for desc in adapter_descriptors
+        }
+        self._policy = policy
+
+        # Adapters that are being drained and will be removed after all
+        # the in-flight operations are done.
+        self._draining: dict[int, threading.Event] = {}
+
+        # Control-plane queue for runtime add/remove, used by the internal
+        # loop thread
+        self._adapter_ops_lock = threading.Lock()
+        self._pending_adapter_ops: list[AddAdapterOp | RemoveAdapterOp] = []
+        self._adapter_ctrl_efd = create_event_notifier()
+
+        self._listener = StoreListener()
+        self._l1_manager.register_listener(self._listener)
+        self._event_bus = get_event_bus()
+
+        # (adapter_index, task_id) -> InFlightStoreTask
+        # Composite key is needed because task IDs are only unique
+        # within a single adapter, not across adapters.
+        self._in_flight_tasks: dict[tuple[int, L2TaskId], InFlightStoreTask] = {}
+
+        # Shadow counter for status reporting (updated in background loop)
+        self._status_in_flight_count: int = 0
+
+        StoreController._gauge_target = self
+        if not StoreController._gauge_registered:
+            StoreController._gauge_registered = True
+            register_gauge(
+                "lmcache.l2_store",
+                "lmcache_mp.num_inflight_l2_stores",
+                "L2 store tasks currently executing, per adapter",
+                lambda: (
+                    StoreController._gauge_target.get_inflight_stores_observations()
+                    if StoreController._gauge_target is not None
+                    else []
+                ),
+            )
+            register_gauge(
+                "lmcache.l2_store",
+                "lmcache_mp.l2_adapters",
+                (
+                    "Count of L2 adapters attached to the store controller, "
+                    "tagged by ``state`` (active or draining)."
+                ),
+                lambda: (
+                    StoreController._gauge_target.get_adapter_state_observations()
+                    if StoreController._gauge_target is not None
+                    else []
+                ),
+            )
+
+        # Map store eventfd -> adapter id for quick lookup in poll results
+        self._efd_to_adapter_index: dict[int, int] = {}
+        for adapter_id, adapter in self._l2_adapters.items():
+            self._efd_to_adapter_index[adapter.get_store_event_fd()] = adapter_id
+
+        self._stop_flag = threading.Event()
+        self._thread = threading.Thread(
+            target=self._store_loop,
+            daemon=True,
+        )
+
+    def start(self) -> None:
+        """Start the background store loop thread."""
+        logger.info("Starting StoreController...")
+        self._thread.start()
+
+    def stop(self) -> None:
+        """
+        Signal the loop to stop, wait for the thread to join.
+
+        Releases all in-flight read locks on shutdown so that
+        L1 objects are not permanently locked.
+        """
+        self._stop_flag.set()
+        # Wake up the poll loop so it can exit promptly
+        self._listener.notify()
+        self._thread.join()
+        self._cleanup_in_flight_tasks()
+        self._listener.close()
+        self._adapter_ctrl_efd.close()
+
+    def report_status(self) -> dict:
+        """Return a status dict for the store controller."""
+        is_healthy = self._thread.is_alive()
+        num_draining = len(self._draining)
+        return {
+            "is_healthy": is_healthy,
+            "thread_alive": is_healthy,
+            "pending_keys_count": self._listener.pending_count(),
+            "in_flight_task_count": self._status_in_flight_count,
+            "num_l2_adapters": len(self._l2_adapters),
+            "num_active_adapters": len(self._l2_adapters) - num_draining,
+            "num_draining_adapters": num_draining,
+        }
+
+    def add_adapter(
+        self,
+        adapter_id: int,
+        adapter: L2AdapterInterface,
+        descriptor: AdapterDescriptor,
+    ) -> None:
+        """Blocking function to add a new adapter into the store controller
+        with the specified adapter ID and descriptor.
+
+        Args:
+            adapter_id: Stable id assigned by the StorageManager.
+            adapter: The adapter instance to attach.
+            descriptor: The adapter's descriptor (``descriptor.index`` must
+                equal ``adapter_id``).
+
+        Raises:
+            RuntimeError: If the background loop did not apply the op in
+                time (e.g. the loop is not running).
+        """
+        op = AddAdapterOp(
+            adapter_id=adapter_id,
+            adapter=adapter,
+            descriptor=descriptor,
+            done=threading.Event(),
+        )
+        with self._adapter_ops_lock:
+            self._pending_adapter_ops.append(op)
+        self._adapter_ctrl_efd.notify()
+        if not op.done.wait(timeout=STORE_LOOP_POLL_TIMEOUT_MS / 1000 + 5.0):
+            raise RuntimeError(
+                f"StoreController did not attach adapter {adapter_id} in time"
+            )
+
+    def request_remove_adapter(self, adapter_id: int) -> threading.Event:
+        """Non-blocking function to request the removal of a L2 adapter
+        specified by the adapter ID.
+
+        New store tasks stop routing to the adapter immediately; in-flight
+        tasks are allowed to complete.
+
+        Args:
+            adapter_id: Stable id of the adapter to drain.
+
+        Returns:
+            An Event signaled when the adapter is fully drained.
+        """
+        op = RemoveAdapterOp(adapter_id=adapter_id, done=threading.Event())
+        with self._adapter_ops_lock:
+            self._pending_adapter_ops.append(op)
+        self._adapter_ctrl_efd.notify()
+        return op.done
+
+    def get_adapter_state_observations(
+        self,
+    ) -> list[tuple[int | float, dict[str, object]]]:
+        """``(count, {"state": ...})`` tuples for the ``lmcache_mp.l2_adapters``
+        gauge. ``len()`` reads are GIL-atomic, safe from the OTel thread."""
+        num_draining = len(self._draining)
+        return [
+            (len(self._l2_adapters) - num_draining, {"state": "active"}),
+            (num_draining, {"state": "draining"}),
+        ]
+
+    def get_inflight_stores_observations(
+        self,
+    ) -> list[tuple[int | float, dict[str, object]]]:
+        """Per-adapter ``(count, attributes)`` snapshot for the
+        ``lmcache_mp.num_inflight_l2_stores`` gauge.
+
+        ``dict.copy()`` is GIL-atomic in CPython, so reading from the
+        OTel reader thread while the store loop mutates is safe; the
+        snapshot may be one mutation stale, which is fine at the 10 s
+        scrape cadence.
+        """
+        counts: dict[int, int] = defaultdict(int)
+        for adapter_index, _ in self._in_flight_tasks.copy():
+            counts[adapter_index] += 1
+        observations: list[tuple[int | float, dict[str, object]]] = []
+        for idx, count in counts.items():
+            # A just-finalized adapter may be gone from the descriptor map
+            # while a stale in-flight snapshot still references it; skip it
+            # rather than KeyError on the OTel reader thread.
+            desc = self._adapter_descriptors.get(idx)
+            if desc is None:
+                continue
+            observations.append(
+                (count, {"l2_name": desc.type_name, "adapter_index": idx})
+            )
+        return observations
+
+    # Private methods
+
+    def _store_loop(self) -> None:
+        """
+        Main event-driven loop running in a background thread.
+
+        Uses select.poll() to wait on:
+        - The StoreListener's eventfd (new keys from L1 writes).
+        - Each L2 adapter's store eventfd (completed store tasks).
+
+        Exits when the stop flag is set.
+        """
+        poller = select.poll()
+
+        listener_efd = self._listener.get_event_fd()
+        poller.register(listener_efd, select.POLLIN)
+        poller.register(self._adapter_ctrl_efd.fileno(), select.POLLIN)
+
+        for efd in self._efd_to_adapter_index:
+            poller.register(efd, select.POLLIN)
+
+        while not self._stop_flag.is_set():
+            # First, apply runtime add/remove of the L2 adapters.
+            self._apply_pending_adapter_ops(poller)
+
+            ready = poller.poll(STORE_LOOP_POLL_TIMEOUT_MS)
+
+            signaled_adapters: dict[StorePhase, set[int]] = {
+                phase: set() for phase in StorePhase
+            }
+            for fd, events in ready:
+                if not (events & select.POLLIN):
+                    continue
+
+                # Consume the notifier value
+                try:
+                    consume_fd(fd)
+                except (OSError, BlockingIOError):
+                    pass
+
+                try:
+                    if fd == listener_efd:
+                        keys = self._listener.pop_pending_keys()
+                        if keys:
+                            self._process_new_keys(keys)
+                    else:
+                        adapter_idx = self._efd_to_adapter_index.get(fd)
+                        if adapter_idx is not None:
+                            signaled_adapters[StorePhase.L2_STORE].add(adapter_idx)
+                except Exception:
+                    logger.exception(
+                        "Unexpected error in store loop while processing fd %d",
+                        fd,
+                    )
+
+            if any(signaled_adapters.values()):
+                try:
+                    self._drain_l2_store_completions(
+                        signaled_adapters[StorePhase.L2_STORE]
+                    )
+                except Exception:
+                    logger.exception("Unexpected error draining L2 store completions")
+                for task_key, task in list(self._in_flight_tasks.items()):
+                    try:
+                        self._advance_request(task_key, task)
+                    except Exception:
+                        logger.exception(
+                            "Unexpected error advancing in-flight store task "
+                            "(adapter %d, task %d)",
+                            task_key[0],
+                            task_key[1],
+                        )
+
+            # Finalize any draining adapter no longer have any in-flight
+            # tasks.
+            self._finalize_drained_adapters(poller)
+
+    def _apply_pending_adapter_ops(self, poller: "select.poll") -> None:
+        """Apply queued add/remove ops on the store loop thread."""
+        with self._adapter_ops_lock:
+            ops = self._pending_adapter_ops
+            self._pending_adapter_ops = []
+        for op in ops:
+            if isinstance(op, AddAdapterOp):
+                self._l2_adapters[op.adapter_id] = op.adapter
+                self._adapter_descriptors[op.adapter_id] = op.descriptor
+                efd = op.adapter.get_store_event_fd()
+                self._efd_to_adapter_index[efd] = op.adapter_id
+                poller.register(efd, select.POLLIN)
+                logger.info("StoreController attached adapter %d", op.adapter_id)
+                op.done.set()
+            elif isinstance(op, RemoveAdapterOp):
+                if op.adapter_id not in self._l2_adapters:
+                    # Already gone (double remove); signal so the caller
+                    # doesn't block.
+                    op.done.set()
+                    continue
+                # Mark draining; routing skips it immediately. The adapter
+                # stays registered so in-flight completions still process.
+                self._draining[op.adapter_id] = op.done
+                logger.info(
+                    "StoreController draining adapter %d (no new stores routed)",
+                    op.adapter_id,
+                )
+
+    def _adapter_in_use(self, adapter_id: int) -> bool:
+        """True if any in-flight store task targets ``adapter_id``."""
+        for task_adapter_id, _ in self._in_flight_tasks:
+            if task_adapter_id == adapter_id:
+                return True
+        return False
+
+    def _finalize_drained_adapters(self, poller: "select.poll") -> None:
+        """Detach draining adapters that no longer have in-flight tasks."""
+        for adapter_id in list(self._draining):
+            if self._adapter_in_use(adapter_id):
+                continue
+            adapter = self._l2_adapters.pop(adapter_id)
+            self._adapter_descriptors.pop(adapter_id, None)
+            efd = adapter.get_store_event_fd()
+            self._efd_to_adapter_index.pop(efd, None)
+            try:
+                poller.unregister(efd)
+            except (KeyError, OSError):
+                pass
+            done = self._draining.pop(adapter_id)
+            logger.info("StoreController detached adapter %d", adapter_id)
+            done.set()
+
+    def _process_new_keys(self, keys: list[ObjectKey]) -> None:
+        """
+        Process a batch of newly written keys.
+
+        1. Ask the policy which adapters each key should go to.
+        2. For each adapter target, reserve read access on L1 to get
+           MemoryObj references (skip keys that fail — best-effort).
+        3. Submit store tasks to L2 adapters.
+        4. Track in-flight tasks for later cleanup.
+
+        Args:
+            keys (list[ObjectKey]): Keys that finished writing to L1.
+        """
+
+        for group in _group_keys_by_shape(keys).values():
+            self._submit_store_for_single_shape(group)
+
+    def _submit_store_for_single_shape(self, keys: list[ObjectKey]) -> None:
+        """Submit ``keys`` (all same shape) to their target adapters."""
+        # Only route to adapters that are live (not draining). Descriptors
+        # for draining adapters are kept for in-flight completion handling
+        # but excluded here so no new task targets them.
+        routing_descriptors = [
+            desc
+            for adapter_id, desc in self._adapter_descriptors.items()
+            if adapter_id not in self._draining
+        ]
+        plan = self._policy.select_store_targets(keys, routing_descriptors)
+
+        l1_mgr = self._l1_manager
+
+        for adapter_index, target_keys in plan.items():
+            if not target_keys:
+                continue
+
+            if adapter_index not in self._l2_adapters:
+                logger.error(
+                    "StorePolicy returned invalid adapter id %d "
+                    "(not among attached adapters). Skipping.",
+                    adapter_index,
+                )
+                continue
+
+            # Reserve read to get MemoryObj references and hold read locks
+            read_results = l1_mgr.reserve_read(target_keys)
+
+            successful_keys = []
+            successful_objs = []
+            not_found_keys: list[ObjectKey] = []
+            write_locked_keys: list[ObjectKey] = []
+            for key in target_keys:
+                result = read_results.get(key)
+                if result is None:
+                    continue
+                err, obj = result
+                if err != L1Error.SUCCESS or obj is None:
+                    if err == L1Error.KEY_NOT_EXIST:
+                        not_found_keys.append(key)
+                    elif err == L1Error.KEY_NOT_READABLE:
+                        write_locked_keys.append(key)
+                    logger.debug(
+                        "Skipping key %s for L2 store (adapter %d): %s",
+                        key,
+                        adapter_index,
+                        err,
+                    )
+                    continue
+                successful_keys.append(key)
+                successful_objs.append(obj)
+
+            # L1 read-failure anomaly reporting: target_keys come from an
+            # L1_WRITE_FINISHED notification, so failing to reserve_read them
+            # immediately after means an unexpected eviction or lock race.
+            if not_found_keys:
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.L1_READ_FAILED,
+                        metadata={
+                            "during": "l2_store",
+                            "reason": "not_found",
+                            "keys": not_found_keys,
+                        },
+                    )
+                )
+            if write_locked_keys:
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.L1_READ_FAILED,
+                        metadata={
+                            "during": "l2_store",
+                            "reason": "write_locked",
+                            "keys": write_locked_keys,
+                        },
+                    )
+                )
+
+            if not successful_keys:
+                continue
+
+            adapter = self._l2_adapters[adapter_index]
+            task_id = adapter.submit_store_task(successful_keys, successful_objs)
+
+            self._in_flight_tasks[(adapter_index, task_id)] = InFlightStoreTask(
+                adapter_index=adapter_index,
+                keys=successful_keys,
+                read_locked_keys=list(successful_keys),
+            )
+            self._status_in_flight_count += 1
+
+            # All objects for a single store task share one layout (L1
+            # allocates uniform MemoryObjs per chunk), so total bytes is
+            # size * count — avoids summing N identical values.
+            total_bytes = successful_objs[0].get_size() * len(successful_objs)
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_STORE_SUBMITTED,
+                    metadata={
+                        "adapter_index": adapter_index,
+                        "task_id": task_id,
+                        "l2_name": self._adapter_descriptors[adapter_index].type_name,
+                        "key_count": len(successful_keys),
+                        "total_bytes": total_bytes,
+                        "key_count_per_salt": Counter(
+                            k.cache_salt for k in successful_keys
+                        ),
+                    },
+                )
+            )
+
+            logger.debug(
+                "Submitted store task %d to adapter %d with %d keys.",
+                task_id,
+                adapter_index,
+                len(successful_keys),
+            )
+
+    def _drain_l2_store_completions(self, signaled_adapters: set[int]) -> None:
+        """Deposit each signaled adapter's L2 outcomes onto their in-flight
+        tasks, to be consumed by ``_advance_request``."""
+        for adapter_index in signaled_adapters:
+            adapter = self._l2_adapters[adapter_index]
+            completed = adapter.pop_completed_store_tasks()
+            for task_id, result in completed.items():
+                task = self._in_flight_tasks.get((adapter_index, task_id))
+                if task is None:
+                    logger.warning(
+                        "Completed store task %d (adapter %d) not found in tracking.",
+                        task_id,
+                        adapter_index,
+                    )
+                    continue
+                task.l2_store_result = result.is_successful()
+                task.l2_bytes_transferred = result.bytes_transferred()
+
+    def _advance_request(
+        self,
+        task_key: tuple[int, L2TaskId],
+        task: InFlightStoreTask,
+    ) -> None:
+        """State-transition dispatcher. Delegate to ``_finalize_store``
+        once the L2 outcome has been recorded by
+        ``_drain_l2_store_completions``."""
+        if task.l2_store_result is None:
+            return
+        self._finalize_store(task_key, task)
+
+    def _finalize_store(
+        self,
+        task_key: tuple[int, L2TaskId],
+        task: InFlightStoreTask,
+    ) -> None:
+        """Release read locks, publish completion, apply policy L1 deletions
+        on success, and remove the tracking entry."""
+        adapter_index, task_id = task_key
+        l1_mgr = self._l1_manager
+        success = task.l2_store_result
+
+        l1_mgr.finish_read(task.read_locked_keys)
+        del self._in_flight_tasks[task_key]
+        self._status_in_flight_count -= 1
+
+        l2_name = self._adapter_descriptors[adapter_index].type_name
+        completion_meta: dict[str, object] = {
+            "adapter_index": adapter_index,
+            "task_id": task_id,
+            "l2_name": l2_name,
+            "bytes_transferred": task.l2_bytes_transferred,
+        }
+        if success:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_STORE_COMPLETED,
+                    metadata={
+                        **completion_meta,
+                        "succeeded_count": len(task.keys),
+                        "failed_count": 0,
+                        "key_count_per_salt": Counter(k.cache_salt for k in task.keys),
+                    },
+                )
+            )
+            logger.debug(
+                "L2 store task %d completed: adapter %d, %d keys.",
+                task_id,
+                adapter_index,
+                len(task.keys),
+            )
+            delete_keys = self._policy.select_l1_deletions(task.keys)
+            if delete_keys:
+                l1_mgr.delete(delete_keys)
+        else:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L2_STORE_COMPLETED,
+                    metadata={
+                        **completion_meta,
+                        "succeeded_count": 0,
+                        "failed_count": len(task.keys),
+                    },
+                )
+            )
+            logger.warning(
+                "Store task %d to adapter %d failed for keys: %s",
+                task_id,
+                adapter_index,
+                task.keys,
+            )
+
+    def _cleanup_in_flight_tasks(self) -> None:
+        """
+        Release all held read locks for any in-flight tasks that
+        haven't completed. Called during stop().
+        """
+        l1_mgr = self._l1_manager
+        for (adapter_index, task_id), task in self._in_flight_tasks.items():
+            logger.warning(
+                "Cleaning up in-flight store task %d (adapter %d, %d keys).",
+                task_id,
+                adapter_index,
+                len(task.read_locked_keys),
+            )
+            l1_mgr.finish_read(task.read_locked_keys)
+        self._in_flight_tasks.clear()
diff --git a/lmcache/v1/distributed/storage_controllers/store_policy.py b/lmcache/v1/distributed/storage_controllers/store_policy.py
new file mode 100644
index 0000000..a8059ee
--- /dev/null
+++ b/lmcache/v1/distributed/storage_controllers/store_policy.py
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Store policy interface and default implementation for L1-to-L2 storage decisions.
+
+The store policy makes two decisions after data is written to L1:
+1. Which L2 adapter(s) should each key be stored to?
+2. After a successful L2 store, should the key be deleted from L1?
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    get_type_name_for_config,
+)
+
+
+@dataclass(frozen=True)
+class AdapterDescriptor:
+    """
+    Lightweight descriptor for an L2 adapter, giving the store policy
+    enough information to distinguish adapters without exposing runtime
+    objects.
+    """
+
+    index: int
+    """Position in the L2 adapters list."""
+
+    config: L2AdapterConfigBase
+    """The adapter's configuration object."""
+
+    @property
+    def type_name(self) -> str:
+        """
+        Registered adapter type name (e.g., "mock", "disk", "redis").
+
+        Derived from the config's registered type via reverse lookup.
+
+        Returns:
+            str: The registered type name.
+        """
+        return get_type_name_for_config(self.config)
+
+
+class StorePolicy(ABC):
+    """
+    Abstract interface for store decisions.
+
+    The store policy is called by the StoreController to decide:
+    1. Which adapter(s) to store each key to (select_store_targets).
+    2. Which keys to delete from L1 after successful L2 store
+       (select_l1_deletions).
+    """
+
+    @abstractmethod
+    def select_store_targets(
+        self,
+        keys: list[ObjectKey],
+        adapters: list[AdapterDescriptor],
+    ) -> dict[int, list[ObjectKey]]:
+        """
+        Decide which keys to store to which L2 adapters.
+
+        Args:
+            keys: Keys that were just written to L1 and are
+                candidates for L2 storage.
+            adapters: Descriptors of available L2 adapters.
+
+        Returns:
+            Mapping from adapter index to list of keys to store
+            to that adapter. Keys absent from all lists are NOT
+            stored to L2.
+        """
+
+    @abstractmethod
+    def select_l1_deletions(
+        self,
+        keys: list[ObjectKey],
+    ) -> list[ObjectKey]:
+        """
+        Decide which keys to delete from L1 after successful L2 store.
+
+        Args:
+            keys: Keys that were successfully stored to L2.
+
+        Returns:
+            Keys to delete from L1. Empty list means keep all.
+        """
+
+
+# -----------------------------------------------------------------------------
+# Registry: store policy name -> policy class
+# -----------------------------------------------------------------------------
+
+_STORE_POLICY_REGISTRY: dict[str, type[StorePolicy]] = {}
+
+
+def register_store_policy(
+    name: str,
+    policy_cls: type[StorePolicy],
+) -> None:
+    """
+    Register a store policy class under a name.
+
+    Each policy module should call this at import time.
+
+    Args:
+        name: Policy name (e.g. "default").
+        policy_cls: A concrete StorePolicy subclass.
+    """
+    if name in _STORE_POLICY_REGISTRY:
+        raise ValueError(f"Store policy already registered: {name!r}")
+    _STORE_POLICY_REGISTRY[name] = policy_cls
+
+
+def get_registered_store_policies() -> list[str]:
+    """Return the list of registered store policy names."""
+    return list(_STORE_POLICY_REGISTRY)
+
+
+def create_store_policy(name: str) -> StorePolicy:
+    """
+    Create a store policy instance by name.
+
+    Args:
+        name: Registered policy name.
+
+    Returns:
+        A new StorePolicy instance.
+
+    Raises:
+        ValueError: If no policy is registered under the given name.
+    """
+    if name not in _STORE_POLICY_REGISTRY:
+        known = ", ".join(sorted(_STORE_POLICY_REGISTRY)) or "(none)"
+        raise ValueError(f"Unknown store policy {name!r}. Known: {known}")
+    return _STORE_POLICY_REGISTRY[name]()
+
+
+class DefaultStorePolicy(StorePolicy):
+    """
+    Default store policy: store all keys to all adapters,
+    never delete from L1.
+    """
+
+    def select_store_targets(
+        self,
+        keys: list[ObjectKey],
+        adapters: list[AdapterDescriptor],
+    ) -> dict[int, list[ObjectKey]]:
+        """
+        Store all keys to all adapters.
+
+        Args:
+            keys: Keys that were just written to L1.
+            adapters: Descriptors of available L2 adapters.
+
+        Returns:
+            Mapping from every adapter index to the full list of keys.
+        """
+        return {ad.index: list(keys) for ad in adapters}
+
+    def select_l1_deletions(
+        self,
+        keys: list[ObjectKey],
+    ) -> list[ObjectKey]:
+        """
+        Never delete from L1.
+
+        Args:
+            keys: Keys that were successfully stored to L2.
+
+        Returns:
+            Empty list (keep all keys in L1).
+        """
+        return []
+
+
+class BufferOnlyStorePolicy(DefaultStorePolicy):
+    """
+    Buffer-only store policy: store all keys to all adapters,
+    then delete them from L1 immediately.
+
+    Use this with NoOpEvictionPolicy to avoid useless LRU
+    tracking overhead when L1 is a pure write buffer.
+
+    Inherits ``select_store_targets`` from ``DefaultStorePolicy``
+    (store all keys to all adapters) and only overrides the L1
+    deletion decision.
+    """
+
+    def select_l1_deletions(
+        self,
+        keys: list[ObjectKey],
+    ) -> list[ObjectKey]:
+        """
+        Delete all keys from L1 after successful L2 store.
+
+        Args:
+            keys: Keys that were successfully stored to L2.
+
+        Returns:
+            All keys (remove everything from L1).
+        """
+        return list(keys)
+
+
+register_store_policy("default", DefaultStorePolicy)
+register_store_policy("skip_l1", BufferOnlyStorePolicy)
diff --git a/lmcache/v1/distributed/storage_manager.py b/lmcache/v1/distributed/storage_manager.py
new file mode 100644
index 0000000..2154f2e
--- /dev/null
+++ b/lmcache/v1/distributed/storage_manager.py
@@ -0,0 +1,1136 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Distributed multi-tier storage manager for MP mode
+"""
+
+# Standard
+from contextlib import contextmanager
+from typing import Iterator, Literal, Optional
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.native_storage_ops import Bitmap, PeriodicEventNotifier
+from lmcache.v1.distributed.api import (
+    DEFAULT_ATTN_WINDOW_DESC,
+    AttnWindowDesc,
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchHandle,
+    PrefetchMode,
+    TrimPolicy,
+)
+from lmcache.v1.distributed.config import EvictionConfig, StorageManagerConfig
+from lmcache.v1.distributed.error import L1Error, strerror
+from lmcache.v1.distributed.internal_api import L1MemoryDesc, L2AdapterListener
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface
+from lmcache.v1.distributed.l2_adapters.config import L2AdapterConfigBase
+from lmcache.v1.distributed.l2_adapters.reconfiguration import (
+    L2ReconfigurableAdapter,
+    L2ReconfigureError,
+)
+from lmcache.v1.distributed.l2_adapters.serde_wrapper import SerdeL2AdapterWrapper
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.distributed.serde import create_serde_processor
+from lmcache.v1.distributed.storage_controllers import (
+    L1EvictionController,
+    L2AdapterEvictionState,
+    L2EvictionController,
+    PrefetchController,
+    StoreController,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_policy import (
+    create_prefetch_policy,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+    create_store_policy,
+)
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.mp_observability.errors import LMCacheTimeoutError
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+from lmcache.v1.mp_observability.otel_init import register_gauge
+from lmcache.v1.mp_observability.trace.decorator import (
+    enable_tracing,
+    is_tracing_enabled,
+    publish_call_event,
+)
+from lmcache.v1.platform import HAS_EVENTFD
+
+logger = init_logger(__name__)
+
+
+class StorageManager:
+    def __init__(self, config: StorageManagerConfig):
+        self._l1_manager = L1Manager(config.l1_manager_config)
+        self._event_bus = get_event_bus()
+
+        # L1 eviction controller
+        self._eviction_controller = L1EvictionController(
+            l1_manager=self._l1_manager,
+            eviction_config=config.eviction_config,
+        )
+        self._eviction_controller.start()
+
+        # L2 adapters and store controller. When an adapter config carries
+        # a ``serde_config``, the adapter is wrapped with
+        # ``SerdeL2AdapterWrapper`` so controllers see a plain L2 adapter
+        # and serde is transparent.
+        self._l1_memory_desc = self._l1_manager.get_l1_memory_desc()
+        self._next_adapter_id = 0
+        # Serializes add_l2_adapter / delete_l2_adapter against each other.
+        self._lifecycle_lock = threading.Lock()
+        # Guards the _l2_adapters and _adapter_descriptors dicts.
+        self._adapters_lock = threading.Lock()
+        self._registered_l2_listeners: list[L2AdapterListener] = []
+        self._l2_adapters: dict[int, L2AdapterInterface] = {}
+        self._adapter_descriptors: dict[int, AdapterDescriptor] = {}
+        for ac in config.l2_adapter_config.adapters:
+            adapter_id, adapter, descriptor = self._build_l2_adapter(ac)
+            self._l2_adapters[adapter_id] = adapter
+            self._adapter_descriptors[adapter_id] = descriptor
+
+        PeriodicEventNotifier.create(
+            interval_ms=config.periodic_notifier_interval_ms,
+            use_eventfd=HAS_EVENTFD,
+        )
+
+        # Per-cache_salt quota registry. Shared across the L2 eviction
+        # controller (reads quotas each cycle) and the HTTP quota
+        # endpoints (CRUD). Present even when no adapter uses
+        # IsolatedLRU so the HTTP layer has a stable ``quota_manager``
+        # reference. No explicit cleanup on close — the registry is
+        # just a dict protected by a lock and has no OS resources.
+        self._quota_manager = QuotaManager()
+
+        # Unified L2 eviction controller for all adapters with eviction
+        # config. Aggregate-usage policies (``LRU``, ``noop``) need
+        # ``max_capacity_bytes > 0`` to compute a usage fraction;
+        # adapters without capacity are skipped for those. Isolated
+        # policies (``IsolatedLRU``) operate on per cache_salt byte
+        # counts which the base class tracks regardless of capacity,
+        # so they are wired up unconditionally.
+        l2_eviction_states: list[L2AdapterEvictionState] = []
+        for adapter_id, ac in zip(
+            self._l2_adapters, config.l2_adapter_config.adapters, strict=True
+        ):
+            adapter = self._l2_adapters[adapter_id]
+            if self._should_enable_l2_eviction(adapter, ac.eviction_config):
+                assert ac.eviction_config is not None  # make linter happy
+                l2_eviction_states.append(
+                    L2AdapterEvictionState(
+                        adapter_id=adapter_id,
+                        adapter=adapter,
+                        eviction_config=ac.eviction_config,
+                    )
+                )
+        self._l2_eviction_controller = L2EvictionController(
+            l2_eviction_states, quota_manager=self._quota_manager
+        )
+        self._l2_eviction_controller.start()
+
+        # Controllers receive the initial set as ordered lists; they key
+        # their own copies by ``descriptor.index`` (== adapter_id) and learn
+        # of later changes via add_adapter/request_remove_adapter.
+        self._store_controller = StoreController(
+            l1_manager=self._l1_manager,
+            l2_adapters=list(self._l2_adapters.values()),
+            adapter_descriptors=list(self._adapter_descriptors.values()),
+            policy=create_store_policy(config.store_policy),
+        )
+        self._store_controller.start()
+
+        # Prefetch controller
+        self._prefetch_controller = PrefetchController(
+            l1_manager=self._l1_manager,
+            l2_adapters=list(self._l2_adapters.values()),
+            adapter_descriptors=list(self._adapter_descriptors.values()),
+            policy=create_prefetch_policy(config.prefetch_policy),
+            max_in_flight=config.prefetch_max_in_flight,
+        )
+        self._prefetch_controller.start()
+
+        # L2 usage gauge — one observation per adapter, tagged by
+        # ``l2_name``.  Parallel to L1Manager's ``l1_memory_usage_bytes``.
+        register_gauge(
+            "lmcache.l2",
+            "lmcache_mp.l2_usage_bytes",
+            (
+                "Bytes currently held in each L2 adapter, tagged by "
+                "``l2_name`` (one observation per adapter)."
+            ),
+            self.get_l2_usages,
+        )
+
+    # External APIs for serving engine integration code to call
+    @enable_tracing()
+    def reserve_write(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+        mode: Literal["new", "update", "all"],
+    ) -> dict[ObjectKey, MemoryObj]:
+        """
+        Reserve the object for writing into the storage manager.
+
+        Args:
+            keys (list[ObjectKey]): List of object keys to reserve for writing.
+            layout_desc (MemoryLayoutDesc): Description of the memory layout
+                for the objects to be reserved.
+            mode (Literal["new", "update", "all"]): Reservation mode.
+            - "new": Reserve only new objects that do not exist.
+            - "update": Reserve only existing objects for update.
+            - "all": Reserve all writable objects regardless of existence.
+
+        Returns:
+            dict[ObjectKey, MemoryObj]: A dictionary mapping object keys to their
+                reserved memory objects. Note that not all requested keys could be
+                reserved (e.g., out of memory or write conflict)
+        """
+        reserve_result = self._l1_manager.reserve_write(
+            keys=keys,
+            is_temporary=[False] * len(keys),
+            layout_desc=layout_desc,
+            mode=mode,
+        )
+
+        result = {k: m for k, (e, m) in reserve_result.items() if m is not None}
+        successful_keys = list(result.keys())
+        failed_keys = [k for k, (e, m) in reserve_result.items() if m is None]
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.SM_WRITE_RESERVED,
+                metadata={
+                    "succeeded_keys": successful_keys,
+                    "failed_keys": failed_keys,
+                },
+            )
+        )
+
+        oom_keys = [
+            k for k, (e, _) in reserve_result.items() if e == L1Error.OUT_OF_MEMORY
+        ]
+        if oom_keys:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L1_ALLOCATION_FAILED,
+                    metadata={"during": "l1_store", "keys": oom_keys},
+                )
+            )
+
+        return result
+
+    @enable_tracing()
+    def finish_write(
+        self,
+        keys: list[ObjectKey],
+    ) -> None:
+        """
+        Finish writing the objects into the storage manager.
+
+        Args:
+            keys (list[ObjectKey]): List of object keys that have been written.
+        """
+        finish_result = self._l1_manager.finish_write(keys)
+        successful_keys = [k for k, e in finish_result.items() if e == L1Error.SUCCESS]
+        failed_keys = [k for k, e in finish_result.items() if e != L1Error.SUCCESS]
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.SM_WRITE_FINISHED,
+                metadata={
+                    "succeeded_keys": successful_keys,
+                    "failed_keys": failed_keys,
+                },
+            )
+        )
+
+        # TODO: global key states update
+
+    @contextmanager
+    def read_prefetched_results(
+        self,
+        keys: list[ObjectKey],
+    ) -> Iterator[list[MemoryObj] | None]:
+        """
+        Read the memory objects from L1 storage that has been prefetched beforehand.
+        Yielding an optional list of memory objects corresponding to the requested
+        keys. If any the object is not found in L1, None is yielded.
+
+        Args:
+            keys (list[ObjectKey]): List of object keys to reserve for reading.
+
+        Returns:
+            Iterator[list[MemoryObj] | None]: An iterator yielding an optional list of
+                memory objects corresponding to the requested keys.
+
+        Note:
+            If any object is not found in L1 storage, None is yielded. In this case,
+            this function will release release the read lock of all successfully read
+            memory objects when exiting the context.
+
+            If the caller raised exception during the processing of the yielded memory
+            objects, this function will ensure that the read locks will be decreased.
+        """
+        # Manual TRACE_CALL emission for the context manager.  The
+        # ``@enable_tracing`` decorator cannot wrap a ``@contextmanager``
+        # generator function (it would publish the call to the wrapper
+        # rather than to ``__enter__``).  Emit enter/exit events
+        # directly, gated on the tracing flag for zero overhead when
+        # disabled.
+        if is_tracing_enabled():
+            publish_call_event(
+                "lmcache.v1.distributed.storage_manager."
+                "StorageManager.read_prefetched_results.__enter__",
+                {"keys": keys},
+            )
+        read_results = self._l1_manager.unsafe_read(keys)
+        good_keys: list[ObjectKey] = []
+        good_objs: list[MemoryObj] = []
+        bad_keys: list[ObjectKey] = []
+        not_found_keys: list[ObjectKey] = []
+        write_locked_keys: list[ObjectKey] = []
+        all_good = True
+        for k, (e, o) in read_results.items():
+            if o is None:
+                logger.error(
+                    "Failed to read prefetched object %s from L1 storage: %s",
+                    k,
+                    strerror(e),
+                )
+                bad_keys.append(k)
+                all_good = False
+                if e == L1Error.KEY_NOT_EXIST:
+                    not_found_keys.append(k)
+                elif e == L1Error.KEY_NOT_READABLE:
+                    write_locked_keys.append(k)
+                continue
+
+            good_keys.append(k)
+            good_objs.append(o)
+
+        # L1 read-failure anomaly reporting: unsafe_read is required to be
+        # called post-reserve_read, so any failure here is a lock/eviction
+        # race, not a normal cache miss.
+        if not_found_keys:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L1_READ_FAILED,
+                    metadata={
+                        "during": "l1_retrieve",
+                        "reason": "not_found",
+                        "keys": not_found_keys,
+                    },
+                )
+            )
+        if write_locked_keys:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.L1_READ_FAILED,
+                    metadata={
+                        "during": "l1_retrieve",
+                        "reason": "write_locked",
+                        "keys": write_locked_keys,
+                    },
+                )
+            )
+
+        successfully_yielded = False
+
+        try:
+            yield good_objs if all_good else None
+            successfully_yielded = True
+        except Exception:
+            logger.exception(
+                "Exception occurred while processing read prefetched results",
+            )
+            raise
+        finally:
+            # Decrease the read lock for all successfully read memory objects
+            # if None is yielded or exception occurs during caller's processing
+            if not all_good or not successfully_yielded:
+                self._l1_manager.finish_read(good_keys)
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.SM_READ_PREFETCHED_FINISHED,
+                        metadata={
+                            "succeeded_keys": good_keys,
+                            "failed_keys": bad_keys,
+                        },
+                    )
+                )
+            if is_tracing_enabled():
+                publish_call_event(
+                    "lmcache.v1.distributed.storage_manager."
+                    "StorageManager.read_prefetched_results.__exit__",
+                    {"keys": keys},
+                )
+
+    @enable_tracing()
+    def finish_read_prefetched(
+        self,
+        keys: list[ObjectKey],
+        extra_count: int = 0,
+    ) -> None:
+        """Finish reading prefetched objects.
+
+        Args:
+            keys: Object keys that have been read.
+            extra_count: Extra read locks to release per key
+                (on top of the default 1).
+        """
+        finish_result = self._l1_manager.finish_read(keys, extra_count=extra_count)
+        successful_keys = [k for k, e in finish_result.items() if e == L1Error.SUCCESS]
+        failed_keys = [k for k, e in finish_result.items() if e != L1Error.SUCCESS]
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.SM_READ_PREFETCHED_FINISHED,
+                metadata={
+                    "succeeded_keys": successful_keys,
+                    "failed_keys": failed_keys,
+                },
+            )
+        )
+
+    @enable_tracing()
+    def submit_prefetch_task(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+        extra_count: int = 0,
+        external_request_id: str = "",
+        policy: TrimPolicy = TrimPolicy.PREFIX,
+        attn_desc: AttnWindowDesc = DEFAULT_ATTN_WINDOW_DESC,
+        skip_l2: bool = False,
+        mode: PrefetchMode = PrefetchMode.LOOKUP,
+    ) -> PrefetchHandle:
+        """Prefetch objects into L1 asynchronously.
+
+        Args:
+            keys: Object keys to prefetch.
+            layout_desc: Memory layout description.
+            extra_count: Extra workers (on top of the default
+                1) that will independently retrieve the same
+                key.  Total locks = 1 + extra_count.
+            external_request_id: Request ID from the caller
+                for end-to-end log tracing.
+            policy: Which retained-subset policy to apply (see
+                :class:`TrimPolicy`).  ``PREFIX`` keeps the contiguous prefix;
+                ``SPARSE`` keeps every found key (gap-tolerant).
+            attn_desc: Cross-chunk attention windows of all object groups, in
+                object-group order.
+            skip_l2: If True, do not load from L2. For ``LOOKUP`` only
+                already-resident L1 keys are returned; for ``WARM`` nothing is
+                loaded and an empty handle is returned.
+            mode: The prefetch intent (see :class:`PrefetchMode`).  ``WARM``
+                retains loaded keys and pins none; ``LOOKUP`` (default) pins
+                them for an imminent reader and follows the policy.
+
+        Returns:
+            PrefetchHandle to track the task.
+        """
+        if mode is PrefetchMode.WARM:
+            # Warm path: load all keys, pin none. skip_l2 makes it a no-op.
+            prefetch_request_id = -1
+            if not skip_l2 and keys and self._l2_adapters:
+                prefetch_request_id = self._prefetch_controller.submit_prefetch_request(
+                    keys,
+                    layout_desc,
+                    extra_count=extra_count,
+                    policy=policy,
+                    mode=mode,
+                )
+            return PrefetchHandle(
+                prefetch_request_id=prefetch_request_id,
+                external_request_id=external_request_id,
+                l1_found_indices=(),
+                total_requested_keys=len(keys),
+                submit_time=time.monotonic(),
+                l2_orig_indices=(
+                    tuple(range(len(keys))) if prefetch_request_id != -1 else ()
+                ),
+            )
+
+        # NOTE: now we only have L1, so the prefetch is essentially checking how many
+        # objects are already in L1, and adding read locks to them.
+
+        l1_read_result = self._l1_manager.reserve_read(keys, extra_count=extra_count)
+
+        if policy is TrimPolicy.SPARSE:
+            # SPARSE: retain a read lock on every L1 hit (not just the leading
+            # prefix) and send all L1 misses to L2 as one coalesced request.
+            # reserve_read locks only SUCCESS keys, so the found-set already
+            # equals the locked set -- nothing to release.
+            l1_found_indices: list[int] = []
+            succeeded_keys: list[ObjectKey] = []
+            sparse_l2_indices: list[int] = []
+            remaining_keys: list[ObjectKey] = []
+            for i, key in enumerate(keys):
+                ent = l1_read_result.get(key)
+                if ent is not None and ent[0] == L1Error.SUCCESS and ent[1] is not None:
+                    l1_found_indices.append(i)
+                    succeeded_keys.append(key)
+                else:
+                    sparse_l2_indices.append(i)
+                    remaining_keys.append(key)
+
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.SM_READ_PREFETCHED,
+                    metadata={
+                        "succeeded_keys": succeeded_keys,
+                        "failed_keys": remaining_keys,
+                    },
+                )
+            )
+
+            prefetch_request_id = -1
+            if remaining_keys and self._has_l2_adapters():
+                prefetch_request_id = self._prefetch_controller.submit_prefetch_request(
+                    remaining_keys,
+                    layout_desc,
+                    extra_count=extra_count,
+                    policy=TrimPolicy.SPARSE,
+                    attn_desc=attn_desc,
+                    mode=mode,
+                )
+            return PrefetchHandle(
+                prefetch_request_id=prefetch_request_id,
+                external_request_id=external_request_id,
+                l1_found_indices=tuple(l1_found_indices),
+                total_requested_keys=len(keys),
+                submit_time=time.monotonic(),
+                l2_orig_indices=tuple(sparse_l2_indices),
+            )
+
+        hit_count = 0
+        for key in keys:
+            entry = l1_read_result.get(key, None)
+            if entry is None:
+                break
+
+            err, obj = entry
+            if err != L1Error.SUCCESS:
+                break
+
+            hit_count += 1
+
+        # NOTE: For L1, there will be cases that "object in the middle" is not found.
+        # In this case, we need to `finish_read` for the latter objects so that
+        # there won't be dangling read locks.
+        skipped_keys = []
+        for key in keys[hit_count:]:
+            if key in l1_read_result and l1_read_result[key][1] is not None:
+                # this key is actually reserved, need to release the read lock
+                skipped_keys.append(key)
+
+        if skipped_keys:
+            self._l1_manager.finish_read(skipped_keys, extra_count=extra_count)
+
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.SM_READ_PREFETCHED,
+                metadata={
+                    "succeeded_keys": keys[:hit_count],
+                    "failed_keys": keys[hit_count:],
+                },
+            )
+        )
+
+        if skip_l2:
+            return PrefetchHandle(
+                prefetch_request_id=-1,
+                external_request_id=external_request_id,
+                l1_found_indices=tuple(range(hit_count)),
+                total_requested_keys=len(keys),
+                submit_time=time.monotonic(),
+                l2_orig_indices=(),
+            )
+
+        # Submit remaining keys to L2 prefetch controller
+        remaining_keys = keys[hit_count:]
+        prefetch_request_id = -1
+        l2_orig_indices: tuple[int, ...] = ()
+        if remaining_keys and self._has_l2_adapters():
+            prefetch_request_id = self._prefetch_controller.submit_prefetch_request(
+                remaining_keys,
+                layout_desc,
+                extra_count=extra_count,
+                attn_desc=attn_desc,
+                policy=policy,
+                mode=mode,
+            )
+            # The controller indexes its result bitmap over remaining_keys
+            # (0-based); map those local indices back to original positions.
+            l2_orig_indices = tuple(range(hit_count, len(keys)))
+
+        submit_time = time.monotonic()
+        logger.debug(
+            "Prefetch request submitted: "
+            "%d total keys, %d L1 prefix hits, "
+            "%d remaining for L2 "
+            "(external_request_id=%s, "
+            "prefetch_request_id=%d)",
+            len(keys),
+            hit_count,
+            len(remaining_keys),
+            external_request_id,
+            prefetch_request_id,
+        )
+
+        return PrefetchHandle(
+            prefetch_request_id=prefetch_request_id,
+            external_request_id=external_request_id,
+            l1_found_indices=tuple(range(hit_count)),
+            total_requested_keys=len(keys),
+            submit_time=submit_time,
+            l2_orig_indices=l2_orig_indices,
+        )
+
+    def _combine_found(
+        self, handle: PrefetchHandle, l2_local: "Bitmap | None"
+    ) -> Bitmap:
+        """Merge the L1 found indices with an L2 result bitmap into one bitmap
+        over the original key positions.
+
+        ``l2_local`` is indexed over the keys submitted to L2 (0-based); its
+        set bits are mapped back to original positions via
+        ``handle.l2_orig_indices``.
+        """
+        found = Bitmap(handle.total_requested_keys)
+        found.batched_set(handle.l1_found_indices)
+        if l2_local is not None:
+            # gather maps each L2 set bit i to its original position
+            # ``l2_orig_indices[i]``; batched_set drops any position >= size.
+            found.batched_set(l2_local.gather(handle.l2_orig_indices))
+        return found
+
+    def query_prefetch_lookup_hits(
+        self,
+        handle: PrefetchHandle,
+    ) -> int | None:
+        """
+        Query the number of prefix-hit chunks for a prefetch task before the
+        L2 prefetching is done.
+
+        Args:
+            handle (PrefetchHandle): The handle of the lookup task.
+
+        Returns:
+            the number of prefix-hit chunks (L1 + L2) if the lookup is done,
+            None if it's still in progress or the prefetch task is already done.
+
+        Note:
+            This function is designed for the scenario where the caller wants
+            to check the L1 prefix hits as soon as possible without waiting for
+            the whole prefetch task to be done.
+            When the prefetch task is already done and the prefetch task result
+            has already been queried by `query_prefetch_status`, this function
+            will return None forever for the same prefetch handle.
+            Therefore, it's the caller’s responsibility to make sure not calling
+            this function after the prefetch task is done.
+        """
+        # Prefix-path only: l1_found_indices is contiguous, so len() == prefix hits.
+        l1_hits = len(handle.l1_found_indices)
+        if handle.prefetch_request_id == -1:
+            # No L2 request: the L1 prefix hit count is final.
+            return l1_hits
+
+        l2_r = self._prefetch_controller.query_lookup_result(handle.prefetch_request_id)
+        if l2_r is None:
+            # Still in progress, or already consumed by query_prefetch_status.
+            return None
+        # L2 lookup done: total prefix hits are L1 plus the L2 continuation.
+        return l1_hits + l2_r
+
+    def wait_prefetch_status(
+        self,
+        handle: PrefetchHandle,
+        timeout: float,
+    ) -> bool:
+        """
+        Block until the prefetch task for ``handle`` has a result, or timeout.
+
+        L1-only prefetches (``prefetch_request_id == -1``) have no L2 result to
+        wait for and return immediately. This lets a caller avoid busy-polling
+        query_prefetch_status; the status itself is still retrieved via
+        query_prefetch_status afterwards.
+
+        Args:
+            handle (PrefetchHandle): The handle of the prefetch task.
+            timeout: Maximum number of seconds to wait for the L2 result.
+
+        Returns:
+            True if a result is available within the timeout (always True for
+            an L1-only prefetch), False if the wait timed out.
+        """
+        if handle.prefetch_request_id == -1:
+            return True
+        return self._prefetch_controller.wait_prefetch_result(
+            handle.prefetch_request_id, timeout
+        )
+
+    def query_prefetch_status(
+        self,
+        handle: PrefetchHandle,
+    ) -> Bitmap | None:
+        """
+        Query the status of the prefetch task.
+
+        Args:
+            handle (PrefetchHandle): The handle of the prefetch task.
+
+        Returns:
+            the found-key bitmap (over original positions) if the prefetch is
+            done, None if it's still in progress. Derive the prefix hit count
+            via ``count_leading_ones``.
+        """
+        l2_r: Bitmap | None = None
+        if handle.prefetch_request_id != -1:
+            l2_r = self._prefetch_controller.query_prefetch_result(
+                handle.prefetch_request_id
+            )
+            if l2_r is None:
+                return None
+
+        found = self._combine_found(handle, l2_r)
+        # popcount (not count_leading_ones) so the log is accurate for
+        # non-contiguous policies (SEGMENTED_PREFIX / SPARSE) too.
+        total_hits = found.popcount()
+        elapsed_ms = (time.monotonic() - handle.submit_time) * 1000
+
+        if total_hits > 0:
+            # L1 and L2 sets are disjoint (only L1-misses go to L2).
+            l1_hits = len(handle.l1_found_indices)
+            l2_hits = l2_r.popcount() if l2_r is not None else 0
+            logger.info(
+                "Prefetch request completed (L1+L2): "
+                "%d/%d retained keys (%d L1, %d L2) in %.1f ms "
+                "(external_request_id=%s, prefetch_request_id=%d)",
+                total_hits,
+                handle.total_requested_keys,
+                l1_hits,
+                l2_hits,
+                elapsed_ms,
+                handle.external_request_id,
+                handle.prefetch_request_id,
+            )
+        return found
+
+    def touch_l1_keys(self, keys: list[ObjectKey]):
+        """
+        Touch the keys in L1 storage, marking the keys
+        as accessed(retrieved or stored).
+
+        Args:
+            keys (list[ObjectKey]): List of object keys to touch.
+        """
+        self._l1_manager.touch_keys(keys)
+
+    def unsafe_read(
+        self, keys: list[ObjectKey]
+    ) -> tuple[list[ObjectKey], list[MemoryObj]]:
+        """Read already read-locked objects without acquiring new read locks."""
+        read_results = self._l1_manager.unsafe_read(keys)
+        good_keys: list[ObjectKey] = []
+        good_objs: list[MemoryObj] = []
+        for key in keys:
+            err, obj = read_results.get(key, (L1Error.KEY_NOT_EXIST, None))
+            if err != L1Error.SUCCESS or obj is None:
+                continue
+            good_keys.append(key)
+            good_objs.append(obj)
+        return good_keys, good_objs
+
+    @property
+    def quota_manager(self) -> QuotaManager:
+        """Per-cache_salt quota registry.
+
+        Exposed so the HTTP layer can serve CRUD endpoints without
+        reaching into private state. Always non-``None`` — the
+        storage manager creates the registry at construction time.
+        """
+        return self._quota_manager
+
+    @property
+    def l1_memory_desc(self) -> L1MemoryDesc:
+        """Descriptor of the L1 memory buffer backing this storage manager."""
+        return self._l1_memory_desc
+
+    def get_l2_usages(
+        self,
+    ) -> list[tuple[int | float, dict[str, object]]]:
+        """Per-adapter L2 usage in OTel-observation shape.
+
+        Backing data for the ``lmcache_mp.l2_usage_bytes`` observable
+        gauge.  One entry per configured adapter.
+
+        Returns:
+            A list of ``(total_bytes_used, {"l2_name": <type_name>})``
+            tuples — empty when no L2 adapters are configured.  Adapters
+            whose ``get_usage()`` raises are skipped (the gauge prefers
+            silence over a poison observation).
+        """
+        out: list[tuple[int | float, dict[str, object]]] = []
+        for _adapter_id, desc, adapter in self._snapshot_adapters():
+            try:
+                usage = adapter.get_usage()
+            except Exception:
+                logger.exception(
+                    "L2 adapter %s get_usage() failed; skipping in gauge",
+                    desc.type_name,
+                )
+                continue
+            out.append((int(usage.total_bytes_used), {"l2_name": desc.type_name}))
+        return out
+
+    def get_usage_bytes_by_cache_salt(self) -> dict[str, int]:
+        """Aggregate ``cache_salt`` byte usage across every L2 adapter.
+
+        Used by the HTTP quota endpoints to report ``current_usage_gb``
+        alongside the configured limit. Aggregation is a simple sum:
+        each adapter tracks the same salt independently so the totals
+        are additive.
+        """
+        totals: dict[str, int] = {}
+        for _adapter_id, _desc, adapter in self._snapshot_adapters():
+            snap = adapter.get_usage().bytes_by_cache_salt
+            for salt, used in snap.items():
+                totals[salt] = totals.get(salt, 0) + used
+        return totals
+
+    # L2 APIs
+    def get_l2_adapter_reconfigure_status(self) -> dict:
+        """Return status for all runtime-reconfigurable L2 adapters.
+
+        Returns:
+            JSON-serializable status. If no reconfigurable adapter is configured,
+            ``enabled`` is ``False`` and the adapter list is empty.
+        """
+        type_names = {
+            adapter_id: desc.type_name
+            for adapter_id, desc, _ in self._snapshot_adapters()
+        }
+        adapters = []
+        for adapter_index, (
+            l2_adapter_index,
+            adapter,
+        ) in enumerate(self._list_reconfigurable_l2_adapters()):
+            status = dict(adapter.reconfigure_status())
+            if l2_adapter_index in type_names:
+                status["backend"] = type_names[l2_adapter_index]
+            status["adapter_index"] = adapter_index
+            status["l2_adapter_index"] = l2_adapter_index
+            adapters.append(status)
+
+        return {
+            "enabled": bool(adapters),
+            "num_adapters": len(adapters),
+            "adapters": adapters,
+        }
+
+    def reconfigurable_l2_backends(self) -> set[str]:
+        """Return the ``type_name`` of every L2 adapter that supports runtime
+        reconfiguration.
+
+        Returns:
+            The set of reconfigurable adapter ``type_name`` strings (empty when
+            none are reconfigurable). The ``{backend}`` path parameter the
+            ``/reconfigure`` routes expect is the adapter's ``type_name``.
+        """
+        return {
+            desc.type_name
+            for _adapter_id, desc, adapter in self._snapshot_adapters()
+            if self._unwrap_reconfigurable_l2_adapter(adapter) is not None
+        }
+
+    def reconfigure_l2_adapter(
+        self,
+        adapter_index: int,
+        operation: str,
+        payload: dict[str, object],
+    ) -> dict:
+        """Route a runtime reconfiguration request to one L2 adapter.
+
+        Args:
+            adapter_index: Zero-based reconfigurable-adapter index.
+            operation: Adapter-specific operation name.
+            payload: Adapter-specific operation payload.
+
+        Returns:
+            JSON-serializable operation result.
+        """
+        adapter = self._get_reconfigurable_l2_adapter(adapter_index)
+        result = adapter.reconfigure(operation, payload)
+        result["adapter_index"] = adapter_index
+        return result
+
+    def add_l2_adapter(self, config: L2AdapterConfigBase) -> int:
+        """Blocking function to add a new L2 adapter at runtime. Thread-safe.
+
+        Args:
+            config: The adapter configuration.
+
+        Returns:
+            The stable id assigned to the new adapter.
+        """
+        with self._lifecycle_lock:
+            adapter_id, adapter, descriptor = self._build_l2_adapter(config)
+            for listener in self._registered_l2_listeners:
+                adapter.register_listener(listener)
+            with self._adapters_lock:
+                self._l2_adapters[adapter_id] = adapter
+                self._adapter_descriptors[adapter_id] = descriptor
+            self._store_controller.add_adapter(adapter_id, adapter, descriptor)
+            self._prefetch_controller.add_adapter(adapter_id, adapter, descriptor)
+            if self._should_enable_l2_eviction(adapter, config.eviction_config):
+                assert config.eviction_config is not None  # make linter happy
+                self._l2_eviction_controller.add_adapter_state(
+                    L2AdapterEvictionState(
+                        adapter_id=adapter_id,
+                        adapter=adapter,
+                        eviction_config=config.eviction_config,
+                    )
+                )
+            logger.info("Added L2 adapter %d (%s)", adapter_id, descriptor.type_name)
+            return adapter_id
+
+    def delete_l2_adapter(self, adapter_id: int, timeout: float = 30.0) -> None:
+        """Blocking function to drain the L2 adapter gracefully at runtime.
+        Thread-safe.
+
+        Stops routing new stores/prefetches to the adapter, waits for its
+        in-flight work to finish, removes it from the controllers, and
+        closes it.
+
+        Args:
+            adapter_id: Stable id of the adapter to remove.
+            timeout: Maximum seconds to wait for in-flight work to drain.
+
+        Raises:
+            ValueError: If no adapter with ``adapter_id`` is active.
+            TimeoutError: If draining did not complete within ``timeout``;
+                the adapter is left active (draining) so the caller can
+                retry.
+        """
+        with self._lifecycle_lock:
+            if adapter_id not in self._l2_adapters:
+                raise ValueError(f"No L2 adapter with id {adapter_id}")
+
+            deadline = time.monotonic() + timeout
+            store_done = self._store_controller.request_remove_adapter(adapter_id)
+            prefetch_done = self._prefetch_controller.request_remove_adapter(adapter_id)
+            if not store_done.wait(timeout=max(0.0, deadline - time.monotonic())):
+                raise LMCacheTimeoutError(
+                    f"Timed out draining adapter {adapter_id} from store controller"
+                )
+            if not prefetch_done.wait(timeout=max(0.0, deadline - time.monotonic())):
+                raise LMCacheTimeoutError(
+                    f"Timed out draining adapter {adapter_id} from prefetch controller"
+                )
+
+            self._l2_eviction_controller.remove_adapter_state(adapter_id)
+            with self._adapters_lock:
+                adapter = self._l2_adapters.pop(adapter_id)
+                self._adapter_descriptors.pop(adapter_id, None)
+            adapter.close()
+            logger.info("Deleted L2 adapter %d", adapter_id)
+
+    def l2_adapters(self) -> list[tuple[AdapterDescriptor, L2AdapterInterface]]:
+        """Return all active L2 adapters paired with descriptors, in
+        ascending adapter-id order (== configuration order for the initial
+        set, then runtime-added adapters). The list is empty when no L2 is
+        configured.
+
+        Do not cache the returned pairs — ``reconfigure_l2_adapter``,
+        ``add_l2_adapter``, and ``delete_l2_adapter`` may change the set at
+        runtime.
+        """
+        return [
+            (desc, adapter) for _adapter_id, desc, adapter in self._snapshot_adapters()
+        ]
+
+    # Management APIs
+    def clear(self, force: bool = False):
+        """
+        Clear data in the storage manager.
+
+        Args:
+            force: If True, clear ALL objects including locked ones.
+                This may corrupt in-flight store/prefetch operations.
+                If False (default), only clear unlocked objects, keeping
+                write-locked and read-locked objects intact.
+        """
+        self._l1_manager.clear(force=force)
+
+    def close(self):
+        """
+        Close the storage manager and release all resources.
+        """
+        self._prefetch_controller.stop()
+        self._store_controller.stop()
+        self._eviction_controller.stop()
+        self._l2_eviction_controller.stop()
+
+        PeriodicEventNotifier.shutdown()
+
+        for adapter in self._l2_adapters.values():
+            adapter.close()
+
+        self._l1_manager.close()
+
+    def report_status(self) -> dict:
+        """Return a status dict aggregating all sub-component statuses."""
+        l1 = self._l1_manager.report_status()
+        store = self._store_controller.report_status()
+        prefetch = self._prefetch_controller.report_status()
+        l1_eviction = self._eviction_controller.report_status()
+        l2_eviction = self._l2_eviction_controller.report_status()
+        adapters = [a.report_status() for _id, _desc, a in self._snapshot_adapters()]
+        children = [l1, store, prefetch, l1_eviction, l2_eviction] + adapters
+        return {
+            "is_healthy": all(c["is_healthy"] for c in children),
+            "l1_manager": l1,
+            "store_controller": store,
+            "prefetch_controller": prefetch,
+            "l1_eviction_controller": l1_eviction,
+            "l2_eviction_controller": l2_eviction,
+            "l2_adapters": adapters,
+            "num_l2_adapters": len(adapters),
+        }
+
+    def register_l2_listener(self, listener: L2AdapterListener) -> None:
+        """Register a listener on all current and future L2 adapters.
+
+        The listener is recorded so that adapters added later via
+        :meth:`add_l2_adapter` receive it too.
+
+        Args:
+            listener: The listener to register.
+        """
+        with self._lifecycle_lock:
+            self._registered_l2_listeners.append(listener)
+            for adapter in self._l2_adapters.values():
+                adapter.register_listener(listener)
+
+    # Functions for debugging and testing
+    def memcheck(self) -> bool:
+        """
+        Perform memory check for all storage tiers.
+
+        Returns:
+            True if memory is consistent, False otherwise.
+        """
+        return self._l1_manager.memcheck()
+
+    def _snapshot_adapters(
+        self,
+    ) -> list[tuple[int, AdapterDescriptor, L2AdapterInterface]]:
+        """Snapshot the active adapters under the lock, in ascending
+        adapter-id order. Iterate this instead of the live dicts so a
+        concurrent add/delete cannot change them mid-iteration.
+
+        Returns:
+            A list of ``(adapter_id, descriptor, adapter)`` tuples.
+        """
+        with self._adapters_lock:
+            return [
+                (adapter_id, self._adapter_descriptors[adapter_id], adapter)
+                for adapter_id, adapter in sorted(self._l2_adapters.items())
+            ]
+
+    def _has_l2_adapters(self) -> bool:
+        """Return whether any L2 adapter is currently active."""
+        with self._adapters_lock:
+            return bool(self._l2_adapters)
+
+    def _build_l2_adapter(
+        self,
+        config: L2AdapterConfigBase,
+    ) -> tuple[int, L2AdapterInterface, AdapterDescriptor]:
+        """Create a L2 adapter instance based on the config.
+
+        Args:
+            config: The adapter configuration.
+
+        Returns:
+            A ``(adapter_id, adapter, descriptor)`` tuple. ``adapter_id`` is
+            the freshly allocated stable id, ``adapter`` is the new adapter
+            instance, and ``descriptor`` is its descriptor carrying that id.
+        """
+        adapter_id = self._next_adapter_id
+        self._next_adapter_id += 1
+        adapter: L2AdapterInterface = create_l2_adapter(config, self._l1_memory_desc)
+        if config.serde_config is not None:
+            adapter = SerdeL2AdapterWrapper(
+                inner=adapter,
+                serde=create_serde_processor(config.serde_config),
+                l1_manager=self._l1_manager,
+            )
+        descriptor = AdapterDescriptor(index=adapter_id, config=config)
+        return adapter_id, adapter, descriptor
+
+    def _should_enable_l2_eviction(
+        self,
+        adapter: L2AdapterInterface,
+        eviction_config: EvictionConfig | None,
+    ) -> bool:
+        """Whether to wire an adapter into the L2 eviction controller.
+
+        Args:
+            adapter: The adapter to evaluate.
+            eviction_config: The adapter's eviction config, if any.
+
+        Returns:
+            True if an eviction state should be created for this adapter.
+        """
+        if eviction_config is None:
+            return False
+        policy_name = eviction_config.eviction_policy
+        if policy_name != "IsolatedLRU" and not adapter.supports_global_eviction:
+            logger.warning(
+                "L2 adapter %s configured with '%s' eviction but does "
+                "not support global eviction (max_capacity_bytes=0); "
+                "skipping aggregate-usage eviction setup.",
+                type(adapter).__name__,
+                policy_name,
+            )
+            return False
+        return True
+
+    def _unwrap_reconfigurable_l2_adapter(
+        self,
+        adapter: L2AdapterInterface,
+    ) -> Optional[L2ReconfigurableAdapter]:
+        if isinstance(adapter, L2ReconfigurableAdapter):
+            return adapter
+
+        inner = getattr(adapter, "inner_adapter", None)
+        if inner is not None and isinstance(inner, L2ReconfigurableAdapter):
+            return inner
+
+        return None
+
+    def _list_reconfigurable_l2_adapters(
+        self,
+    ) -> list[tuple[int, L2ReconfigurableAdapter]]:
+        with self._adapters_lock:
+            items = sorted(self._l2_adapters.items())
+        adapters: list[tuple[int, L2ReconfigurableAdapter]] = []
+        for l2_adapter_index, adapter in items:
+            reconfigurable_adapter = self._unwrap_reconfigurable_l2_adapter(adapter)
+            if reconfigurable_adapter is not None:
+                adapters.append((l2_adapter_index, reconfigurable_adapter))
+        return adapters
+
+    def _get_reconfigurable_l2_adapter(
+        self,
+        adapter_index: int,
+    ) -> L2ReconfigurableAdapter:
+        adapters = self._list_reconfigurable_l2_adapters()
+        if adapter_index < 0 or adapter_index >= len(adapters):
+            raise L2ReconfigureError(404, "L2 adapter not reconfigurable")
+        return adapters[adapter_index][1]
diff --git a/lmcache/v1/distributed/tiers.py b/lmcache/v1/distributed/tiers.py
new file mode 100644
index 0000000..86ec77c
--- /dev/null
+++ b/lmcache/v1/distributed/tiers.py
@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cache tier vocabulary, shared across the MP server and the coordinator.
+
+The cache-management API treats the tier as request data (``tier`` /
+``source_tier`` / ``target_tier``) rather than baking it into paths, so the set
+of valid tiers lives in one neutral place that both packages import.
+"""
+
+# Standard
+from enum import Enum
+
+
+class Tier(str, Enum):
+    """A cache tier.
+
+    Subclasses ``str`` so it validates from / compares equal to the bare wire
+    value (``Tier.L2 == "l2"``) and serializes as that value. ``ALL`` is only
+    valid for operations that explicitly support multiple tiers.
+    """
+
+    L1 = "l1"
+    L2 = "l2"
+    ALL = "all"
diff --git a/lmcache/v1/distributed/transfer_channel/__init__.py b/lmcache/v1/distributed/transfer_channel/__init__.py
new file mode 100644
index 0000000..e3e7903
--- /dev/null
+++ b/lmcache/v1/distributed/transfer_channel/__init__.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+import threading
+
+# First Party
+from lmcache.v1.distributed.transfer_channel.abstract import (
+    TransferChannelClient,
+    TransferChannelContext,
+    TransferChannelServer,
+)
+from lmcache.v1.distributed.transfer_channel.api import (
+    TransferChannelAddress,
+    TransferChannelReadResult,
+)
+from lmcache.v1.distributed.transfer_channel.factory import (
+    create_transfer_channel_context,
+)
+
+# Import the implementations so they self-register their factories.
+import lmcache.v1.distributed.transfer_channel.impl  # noqa: F401
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+
+__all__ = [
+    "TransferChannelAddress",
+    "TransferChannelReadResult",
+    "TransferChannelContext",
+    "TransferChannelServer",
+    "TransferChannelClient",
+    "initialize_transfer_channel_context",
+    "get_transfer_channel_context",
+    "delete_transfer_channel_context",
+]
+
+_context: TransferChannelContext | None = None
+_context_lock = threading.Lock()
+
+
+def initialize_transfer_channel_context(
+    transfer_channel_type: str,
+    l1_memory_desc: "L1MemoryDesc",
+    listen_url: str,
+    advertise_url: str,
+    **kwargs,
+) -> TransferChannelContext:
+    """Create the global transfer channel context.
+
+    Args:
+        transfer_channel_type: Currently only ``"nixl"`` is supported.
+        l1_memory_desc: Describes the L1 memory region to register.
+        listen_url: ``host:port`` this peer's singleton server binds to.
+        advertise_url: ``host:port`` this peer advertises as its identity (the
+            key peers store its reverse client under).
+        **kwargs: Implementation-specific keyword arguments forwarded to the
+            factory.
+
+    Returns:
+        The created context (also retrievable via ``get_transfer_channel_context``).
+
+    Raises:
+        RuntimeError: If a context has already been initialized.
+        ValueError: If no factory is registered for ``transfer_channel_type``.
+    """
+    global _context
+    with _context_lock:
+        if _context is not None:
+            raise RuntimeError(
+                "Transfer channel context already initialized; call "
+                "delete_transfer_channel_context() first."
+            )
+        _context = create_transfer_channel_context(
+            transfer_channel_type=transfer_channel_type,
+            l1_memory_desc=l1_memory_desc,
+            listen_url=listen_url,
+            advertise_url=advertise_url,
+            **kwargs,
+        )
+        return _context
+
+
+def get_transfer_channel_context() -> TransferChannelContext:
+    """Get the global transfer channel context.
+
+    Raises:
+        RuntimeError: If the context has not been initialized yet.
+    """
+    with _context_lock:
+        if _context is None:
+            raise RuntimeError("Transfer channel context not initialized.")
+        return _context
+
+
+def delete_transfer_channel_context() -> None:
+    """Delete the global transfer channel context, if it exists."""
+    global _context
+    with _context_lock:
+        if _context is not None:
+            _context.close()
+            _context = None
diff --git a/lmcache/v1/distributed/transfer_channel/abstract.py b/lmcache/v1/distributed/transfer_channel/abstract.py
new file mode 100644
index 0000000..9969abf
--- /dev/null
+++ b/lmcache/v1/distributed/transfer_channel/abstract.py
@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract base classes for the transfer channel abstraction.
+
+Main classes:
+* ``TransferChannelContext`` -- the global singleton that owns the underlying
+  transfer engine, maintains the registered L1 memory, and translates L1 addresses
+  into transfer-channel-specific addresses.
+* ``TransferChannelServer`` -- listens for client connections and exchanges the
+  metadata during the handshake.
+* ``TransferChannelClient`` -- performs the read operations against a peer's
+  memory. Only reads are supported for P2P for now.
+"""
+
+# Standard
+import abc
+
+# First Party
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.transfer_channel.api import (
+    TransferChannelAddress,
+    TransferChannelReadResult,
+)
+
+
+class TransferChannelServer(metaclass=abc.ABCMeta):
+    """Listens for incoming client connections and exchanges transfer metadata."""
+
+    @abc.abstractmethod
+    def __init__(
+        self,
+        listen_url: str,
+        advertise_url: str,
+        l1_memory_desc: L1MemoryDesc,
+    ) -> None:
+        """Creates the server listening on ``listen_url``.
+
+        Args:
+            listen_url: The ``host:port`` to bind and listen on (e.g.
+                ``0.0.0.0:7600``).
+            advertise_url: The ``host:port`` this peer is reachable at and
+                announces in its outgoing handshakes.
+            l1_memory_desc: Describes the L1 memory region to register.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Free the resources created by the server."""
+        raise NotImplementedError
+
+
+class TransferChannelClient(metaclass=abc.ABCMeta):
+    """Performs read operations from a remote peer's memory."""
+
+    @abc.abstractmethod
+    def __init__(self, transfer_channel_server_url: str) -> None:
+        """Connect to the server at ``transfer_channel_server_url``."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def submit_read(
+        self,
+        local_addresses: list[TransferChannelAddress],
+        remote_addresses: list[TransferChannelAddress],
+    ) -> int:
+        """Read data from the remote addresses into the local addresses.
+
+        Args:
+            local_addresses: addresses in the local L1 buffer.
+            remote_addresses: addresses in the remote peer's L1 buffer.
+                Must have the same length as ``local_addresses``.
+
+        Returns:
+            A task id, to be passed to ``query_read_status``.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def query_read_status(self, task_id: int) -> TransferChannelReadResult:
+        """Query the status of a previously submitted read.
+
+        Args:
+            task_id: The task id returned by ``submit_read``.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Terminate in-flight requests, deregister from the server, free resources."""
+        raise NotImplementedError
+
+
+class TransferChannelContext(metaclass=abc.ABCMeta):
+    """Global singleton that owns the server singleton, and all clients."""
+
+    @abc.abstractmethod
+    def get_transfer_channel_server(self) -> TransferChannelServer:
+        """Return the transfer channel server singleton."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_transfer_channel_client(
+        self,
+        peer_advertise_url: str,
+    ) -> TransferChannelClient:
+        """Get or create a client that is connected to the peer identified by
+        ``peer_advertise_url``.
+
+        Args:
+            peer_advertise_url: The ``host:port`` url that can connects to the
+                peer.
+
+        Notes:
+            For some bi-directional transport libraries (like NIXL), the client
+            might be created passively when the current context (server) is
+            connected by the remote peer.
+            This behavior is per implementation and transparent to the caller.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def remove_transfer_channel_client(self, peer_advertise_url: str) -> None:
+        """Discard the client for ``peer_advertise_url`` and free its resources.
+
+        Call this when reads from the peer are no longer needed (e.g. the
+        owning L2 adapter is being removed). Any task ids previously returned by
+        that client become invalid. A later ``get_transfer_channel_client`` for
+        the same peer returns a fresh client.
+
+        Calling this for a peer with no current client does nothing.
+
+        Args:
+            peer_advertise_url: The ``host:port`` of the peer, as passed to
+                ``get_transfer_channel_client``.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_transfer_channel_address(
+        self,
+        lmcache_addresses: list[tuple[int, int]],
+    ) -> list[TransferChannelAddress]:
+        """Translate ``(offset, size)`` L1 objects into the transfer-channel-specific
+        addresses.
+
+        Args:
+            lmcache_addresses: A list of tuples of the form ``(offset, size)``, where
+                ``offset`` is the offset into the L1 buffer, and ``size`` is the
+                size of the region.
+
+        Returns:
+            A list of transfer-channel-specific addresses that can be used in the
+                client read operations. Must have the same length as
+                ``lmcache_addresses``.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_num_connected_clients(self) -> int:
+        """Return the number of currently connected clients."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Stop and clean up all servers and clients; free context resources."""
+        raise NotImplementedError
diff --git a/lmcache/v1/distributed/transfer_channel/api.py b/lmcache/v1/distributed/transfer_channel/api.py
new file mode 100644
index 0000000..cd659cc
--- /dev/null
+++ b/lmcache/v1/distributed/transfer_channel/api.py
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Data types exposed by the transfer channel abstraction.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class TransferChannelAddress:
+    """A transfer-channel-specific address, with starting position and size
+    (in bytes).
+
+    A single address corresponds to a single memory object.
+
+    Note:
+        Currently, this is no difference between a tuple of (offset, size).
+        But we are wrapping this as a class for future extensibility (e.g.
+        support non L1 memory).
+    """
+
+    offset: int
+    """ The offset (in bytes) against the L1 base address. """
+
+    size: int
+    """ The size (in bytes) of the memory object. """
+
+    def is_valid(self) -> bool:
+        """Whether the address is valid (non-negative offset and size)."""
+        return self.offset >= 0 and self.size > 0
+
+
+@dataclass
+class TransferChannelReadResult:
+    """Result of querying a submitted read task."""
+
+    finished: bool
+    """ Whether the transfer has reached a terminal state (done or errored). """
+
+    succeeded_mask: list[bool] = field(default_factory=list)
+    """ Per-object success flags, aligned with the submitted addresses. Empty while
+    the transfer is still in flight. """
+
+    def is_finished(self) -> bool:
+        """Whether the transfer reached a terminal state (done or errored)."""
+        return self.finished
diff --git a/lmcache/v1/distributed/transfer_channel/factory.py b/lmcache/v1/distributed/transfer_channel/factory.py
new file mode 100644
index 0000000..3b3ee75
--- /dev/null
+++ b/lmcache/v1/distributed/transfer_channel/factory.py
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Factory registry for transfer channel contexts.
+
+Each implementation under ``impl/`` self-registers a factory callable via
+``register_transfer_channel_factory`` at import time.
+``create_transfer_channel_context`` looks the factory up by transfer-channel
+type name and invokes it.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING, Callable
+
+# First Party
+from lmcache.logging import init_logger
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+    from lmcache.v1.distributed.transfer_channel.abstract import (
+        TransferChannelContext,
+    )
+
+logger = init_logger(__name__)
+
+# A factory creates a ``TransferChannelContext``. It is always called with the
+# keyword arguments ``l1_memory_desc``, ``listen_url`` and ``advertise_url``,
+# plus any implementation-specific keyword arguments forwarded by the caller.
+TransferChannelFactory = Callable[..., "TransferChannelContext"]
+
+# Registry: transfer-channel type name -> factory callable.
+_TRANSFER_CHANNEL_FACTORY_REGISTRY: dict[str, TransferChannelFactory] = {}
+
+
+def register_transfer_channel_factory(
+    transfer_channel_type: str,
+    factory: TransferChannelFactory,
+) -> None:
+    """Register a factory that creates a context for ``transfer_channel_type``.
+
+    Each implementation module should call this at import time.
+
+    Args:
+        transfer_channel_type: The type name to register the factory under
+            (e.g. ``"nixl"``).
+        factory: A callable invoked with the keyword arguments
+            ``l1_memory_desc``, ``listen_url``, ``advertise_url`` and any
+            implementation-specific keyword arguments, returning a
+            ``TransferChannelContext``.
+
+    Raises:
+        ValueError: If a factory is already registered for this type name.
+    """
+    if transfer_channel_type in _TRANSFER_CHANNEL_FACTORY_REGISTRY:
+        raise ValueError(
+            f"Transfer channel factory already registered: {transfer_channel_type!r}"
+        )
+    _TRANSFER_CHANNEL_FACTORY_REGISTRY[transfer_channel_type] = factory
+
+
+def create_transfer_channel_context(
+    transfer_channel_type: str,
+    l1_memory_desc: "L1MemoryDesc",
+    listen_url: str,
+    advertise_url: str,
+    **kwargs,
+) -> "TransferChannelContext":
+    """Create a transfer channel context using the registered factory.
+
+    Args:
+        transfer_channel_type: The type name of the implementation to create
+            (e.g. ``"nixl"``).
+        l1_memory_desc: Describes the L1 memory region to register.
+        listen_url: ``host:port`` this peer's server binds to.
+        advertise_url: ``host:port`` this peer advertises as its identity.
+        **kwargs: Implementation-specific keyword arguments forwarded to the
+            factory.
+
+    Returns:
+        A new ``TransferChannelContext`` instance.
+
+    Raises:
+        ValueError: If no factory is registered for ``transfer_channel_type``.
+    """
+    factory = _TRANSFER_CHANNEL_FACTORY_REGISTRY.get(transfer_channel_type)
+    if factory is None:
+        known = sorted(_TRANSFER_CHANNEL_FACTORY_REGISTRY)
+        raise ValueError(
+            f"Unsupported transfer_channel_type: {transfer_channel_type!r}. "
+            f"Registered types: {known}"
+        )
+
+    return factory(
+        l1_memory_desc=l1_memory_desc,
+        listen_url=listen_url,
+        advertise_url=advertise_url,
+        **kwargs,
+    )
diff --git a/lmcache/v1/distributed/transfer_channel/impl/__init__.py b/lmcache/v1/distributed/transfer_channel/impl/__init__.py
new file mode 100644
index 0000000..3247141
--- /dev/null
+++ b/lmcache/v1/distributed/transfer_channel/impl/__init__.py
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Transfer channel implementations.
+
+Importing this package imports each implementation module, which in turn
+self-registers its factory via ``register_transfer_channel_factory``.
+"""
+
+# First Party
+from lmcache.v1.distributed.transfer_channel.impl import nixl_impl  # noqa: F401
diff --git a/lmcache/v1/distributed/transfer_channel/impl/nixl_impl.py b/lmcache/v1/distributed/transfer_channel/impl/nixl_impl.py
new file mode 100644
index 0000000..a6c6b6d
--- /dev/null
+++ b/lmcache/v1/distributed/transfer_channel/impl/nixl_impl.py
@@ -0,0 +1,626 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Nixl-backed implementation of the transfer channel abstraction."""
+
+# Standard
+from typing import TYPE_CHECKING, Optional, Union
+import importlib
+import math
+import threading
+import uuid
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.transfer_channel.abstract import (
+    TransferChannelClient,
+    TransferChannelContext,
+    TransferChannelServer,
+)
+from lmcache.v1.distributed.transfer_channel.api import (
+    TransferChannelAddress,
+    TransferChannelReadResult,
+)
+from lmcache.v1.distributed.transfer_channel.factory import (
+    register_transfer_channel_factory,
+)
+from lmcache.v1.mp_observability.errors import LMCacheTimeoutError
+
+if TYPE_CHECKING:
+    # Third Party
+    from nixl._api import nixl_agent, nixl_agent_config, nixl_prepped_dlist_handle
+
+logger = init_logger(__name__)
+
+# Timeout for each blocking recv during the client handshake. Without it a
+# misconfigured/unreachable server url would block the connecting thread
+# forever. Hard-coded for now.
+_HANDSHAKE_TIMEOUT_MS = 60_000
+
+
+############################################################
+# Helper functions
+############################################################
+def _load_nixl() -> tuple["nixl_agent", "nixl_agent_config"]:
+    """Import the nixl Python bindings, tolerating the cuXX-suffixed packages."""
+    last_err: Optional[Exception] = None
+    for modname in ("nixl._api", "nixl_cu12._api", "nixl_cu13._api"):
+        try:
+            mod = importlib.import_module(modname)
+            return mod.nixl_agent, mod.nixl_agent_config
+        except ImportError as err:  # noqa: PERF203
+            last_err = err
+    raise RuntimeError(
+        "NIXL is not available (tried nixl._api, nixl_cu12._api, nixl_cu13._api)"
+    ) from last_err
+
+
+def _parse_url(url: str) -> tuple[str, int]:
+    """Parse a ``host:port`` (optionally ``tcp://host:port``) into (host, port)."""
+    stripped = url.split("://", 1)[-1]
+    host, _, port = stripped.rpartition(":")
+    if not host or not port:
+        raise ValueError(f"Invalid transfer channel url: {url!r} (expected host:port)")
+    return host, int(port)
+
+
+############################################################
+# Handshake messages (msgspec, tagged union)
+############################################################
+class HandshakeMsgBase(msgspec.Struct, tag=True):
+    pass
+
+
+class InitReq(HandshakeMsgBase):
+    agent_name: str
+    agent_meta: bytes
+
+
+class InitResp(HandshakeMsgBase):
+    agent_name: str
+    agent_meta: bytes
+
+
+class MemRegReq(HandshakeMsgBase):
+    sender_agent_name: str
+    sender_advertise_url: str
+    xfer_descs: bytes
+
+
+class MemRegResp(HandshakeMsgBase):
+    xfer_descs: bytes
+
+
+HandshakeMsg = Union[InitReq, InitResp, MemRegReq, MemRegResp]
+
+
+############################################################
+# Client
+############################################################
+class NixlTransferChannelClient(TransferChannelClient):
+    def __init__(
+        self,
+        context: "NixlTransferChannelContext",
+        remote_agent_name: str,
+        remote_dlist_handle: "nixl_prepped_dlist_handle",
+    ):
+        self._ctx = context
+        self._remote_agent_name = remote_agent_name
+        self._remote_handle = remote_dlist_handle
+
+        self._task_counter = 0
+        # task_id -> (xfer_handle, remote_addresses)
+        self._tasks: dict[int, tuple] = {}
+        self._lock = threading.Lock()
+
+    def submit_read(
+        self,
+        local_addresses: list[TransferChannelAddress],
+        remote_addresses: list[TransferChannelAddress],
+    ) -> int:
+        """Submit a read transfer from the remote addresses to the local addresses.
+
+        Args:
+            local_addresses: The local addresses to read into.
+            remote_addresses: The remote addresses to read from.
+
+        Returns:
+            A unique task ID for this transfer.
+        """
+        if len(local_addresses) != len(remote_addresses):
+            raise ValueError(
+                "local_addresses and remote_addresses must have equal length "
+                f"({len(local_addresses)} != {len(remote_addresses)})"
+            )
+
+        local_idx = self._ctx.addresses_to_indices(local_addresses)
+        remote_idx = self._ctx.addresses_to_indices(remote_addresses)
+
+        agent = self._ctx.agent
+        handle = agent.make_prepped_xfer(
+            "READ",
+            self._ctx.local_handle,
+            local_idx,
+            self._remote_handle,
+            remote_idx,
+        )
+        agent.transfer(handle)
+
+        with self._lock:
+            task_id = self._task_counter
+            self._task_counter += 1
+            self._tasks[task_id] = (handle, list(remote_addresses))
+        return task_id
+
+    def query_read_status(self, task_id: int) -> TransferChannelReadResult:
+        """
+        Query the status of a previously submitted read transfer.
+
+        Args:
+            task_id: The ID of the transfer task to query.
+
+        Returns:
+            A TransferChannelReadResult indicating whether the transfer is finished
+            and which objects succeeded (if finished).
+        """
+        with self._lock:
+            if task_id not in self._tasks:
+                raise KeyError(f"Unknown read task id: {task_id}")
+            handle, remote_addresses = self._tasks[task_id]
+
+        status = self._ctx.agent.check_xfer_state(handle)
+        if status == "PROC":
+            return TransferChannelReadResult(finished=False, succeeded_mask=[])
+
+        # Terminal state (DONE or ERR): release the handle and report.
+        with self._lock:
+            self._tasks.pop(task_id, None)
+        self._ctx.agent.release_xfer_handle(handle)
+
+        if status == "DONE":
+            return TransferChannelReadResult(
+                finished=True, succeeded_mask=[True] * len(remote_addresses)
+            )
+
+        # status == "ERR" (or any unexpected state): finished but nothing succeeded.
+        return TransferChannelReadResult(
+            finished=True, succeeded_mask=[False] * len(remote_addresses)
+        )
+
+    def close(self) -> None:
+        """
+        Close the transfer channel, releasing any pending tasks and the remote handle.
+
+        Note:
+            This function does not send any notifications to the server side. The
+            server-side teardown needs to be done by other ways (if needed).
+        """
+        with self._lock:
+            tasks = list(self._tasks.values())
+            self._tasks.clear()
+        for handle, _ in tasks:
+            try:
+                self._ctx.agent.release_xfer_handle(handle)
+            except Exception:  # noqa: BLE001 - best-effort cleanup
+                pass
+        if self._remote_handle is not None:
+            try:
+                self._ctx.agent.release_dlist_handle(self._remote_handle)
+            except Exception:  # noqa: BLE001
+                pass
+            self._remote_handle = None
+
+
+############################################################
+# Server
+############################################################
+class NixlTransferChannelServer(TransferChannelServer):
+    """
+    Note:
+        The server uses a ZMQ REP socket for the metadata handshake.
+        It's not using LMCache MQ because we think that's an overkill
+        and we don't want to register the transfer-channel specific
+        functions into the global LMCache MQ.
+    """
+
+    def __init__(
+        self,
+        listen_url: str,
+        advertise_url: str,
+        l1_memory_desc: L1MemoryDesc,
+        context: "NixlTransferChannelContext",
+    ) -> None:
+        self._ctx = context
+        self._listen_url = listen_url
+        self._advertise_url = advertise_url
+        self._l1_memory_desc = l1_memory_desc
+
+        self._running = True
+        self._socket = self._ctx.zmq_context.socket(zmq.REP)
+        self._socket.setsockopt(zmq.LINGER, 0)
+        host, port = _parse_url(listen_url)
+        self._socket.bind(f"tcp://{host}:{port}")
+
+        self._thread = threading.Thread(
+            target=self._serve_loop, name="tc-nixl-server", daemon=True
+        )
+        self._thread.start()
+
+    def _serve_loop(self) -> None:
+        poller = zmq.Poller()
+        poller.register(self._socket, zmq.POLLIN)
+        while self._running:
+            try:
+                events = dict(poller.poll(timeout=1000))  # ms
+                if self._socket not in events:
+                    continue
+                req_bytes = self._socket.recv()
+                req = msgspec.msgpack.decode(req_bytes, type=HandshakeMsg)
+                resp = self._handle_msg(req)
+                self._socket.send(msgspec.msgpack.encode(resp))
+            except Exception:  # noqa: BLE001
+                if self._running:
+                    logger.exception("Error in transfer channel server loop")
+
+    def _handle_msg(self, req: HandshakeMsg) -> HandshakeMsg:
+        agent = self._ctx.agent
+        if isinstance(req, InitReq):
+            # Learn the connecting peer's agent (idempotent on repeat).
+            agent.add_remote_agent(req.agent_meta)
+            return InitResp(
+                agent_name=self._ctx.agent_name,
+                agent_meta=agent.get_agent_metadata(),
+            )
+        elif isinstance(req, MemRegReq):
+            remote_xfer_dlist = agent.deserialize_descs(req.xfer_descs)
+            remote_handle = agent.prep_xfer_dlist(
+                req.sender_agent_name, remote_xfer_dlist
+            )
+
+            self._ctx.register_client(
+                key=req.sender_advertise_url,
+                client=NixlTransferChannelClient(
+                    context=self._ctx,
+                    remote_agent_name=req.sender_agent_name,
+                    remote_dlist_handle=remote_handle,
+                ),
+            )
+            return MemRegResp(xfer_descs=self._ctx.serialized_xfer_descs)
+        else:
+            raise ValueError(f"Unexpected handshake message: {type(req)}")
+
+    def close(self) -> None:
+        """
+        Close the transfer channel server, stopping the serve loop and
+        closing the socket.
+        """
+        self._running = False
+        if self._thread.is_alive():
+            self._thread.join(timeout=5)
+        self._socket.close(linger=0)
+
+
+############################################################
+# Context
+############################################################
+class NixlTransferChannelContext(TransferChannelContext):
+    """Owns the single nixl agent, the registered L1 buffer, and support
+    the address translation.
+    """
+
+    def __init__(
+        self,
+        l1_memory_desc: L1MemoryDesc,
+        listen_url: str,
+        advertise_url: str,
+        backends: Optional[list[str]] = None,
+    ) -> None:
+        """
+        Creates the transfer channel context using nixl.
+
+        Args:
+            l1_memory_desc: The description of the local L1 memory buffer to register.
+            listen_url: The URL to listen on for incoming connections.
+            advertise_url: The URL to advertise to peers for them to connect to us.
+            backends: Optional list of nixl backends to use (e.g., ["UCX"])
+        """
+        nixl_agent, nixl_agent_config = _load_nixl()
+
+        self._l1_memory_desc = l1_memory_desc
+        self._align = l1_memory_desc.align_bytes
+        self.listen_url = listen_url
+        self.advertise_url = advertise_url
+        backends = backends if backends else ["UCX"]
+
+        self.agent_name = str(uuid.uuid4())
+        self.agent = nixl_agent(self.agent_name, nixl_agent_config(backends=backends))
+
+        # Register the whole L1 buffer once (CPU/DRAM, fixed nixl dev_id=0).
+        ptr, size = l1_memory_desc.ptr, l1_memory_desc.size
+        self._reg_descs = self.agent.get_reg_descs([(ptr, size, 0, "")], "cpu")
+        self.agent.register_memory(self._reg_descs)
+
+        # Build + prep a page-granular local xfer dlist over the whole buffer.
+        xfer_list = [
+            (addr, self._align, 0) for addr in range(ptr, ptr + size, self._align)
+        ]
+        self._xfer_descs = self.agent.get_xfer_descs(xfer_list, "cpu")
+        self.local_handle = self.agent.prep_xfer_dlist("", self._xfer_descs, "cpu")
+        self.serialized_xfer_descs = self.agent.get_serialized_descs(self._xfer_descs)
+
+        self.zmq_context = zmq.Context.instance()
+
+        # Clients keyed by the peer's advertised url. Populated either actively
+        # (we dialed the peer) or reactively (the peer connected to our server).
+        self._clients: dict[str, NixlTransferChannelClient] = {}
+        self._lock = threading.Lock()
+
+        # Exactly one server per context, bound eagerly at construction.
+        self._server = NixlTransferChannelServer(
+            listen_url=listen_url,
+            advertise_url=advertise_url,
+            l1_memory_desc=l1_memory_desc,
+            context=self,
+        )
+
+    ############################################################
+    # Address translation
+    ############################################################
+    def get_transfer_channel_address(
+        self,
+        lmcache_addresses: list[tuple[int, int]],
+    ) -> list[TransferChannelAddress]:
+        """
+        Validate the given LMCache addresses (offset, size) against the
+        registered L1 memory region and convert it to TransferChannelAddress
+
+        Args:
+            lmcache_addresses: List of (offset, size) tuples representing the LMCache
+                addresses.
+
+        Returns:
+            A list of TransferChannelAddress corresponding to the given LMCache
+            addresses.
+        """
+        size = self._l1_memory_desc.size
+        out = []
+        for offset, obj_size in lmcache_addresses:
+            if offset < 0 or offset + obj_size > size:
+                raise ValueError(
+                    f"Object [{offset:#x}, {offset + obj_size:#x}) is outside the "
+                    f"registered L1 region [0x0, {size:#x})"
+                )
+            out.append(TransferChannelAddress(offset=offset, size=obj_size))
+        return out
+
+    def addresses_to_indices(
+        self, addresses: list[TransferChannelAddress]
+    ) -> list[int]:
+        """Translate (offset, size) addresses into page indices in the prepped dlist."""
+        indices: list[int] = []
+        for a in addresses:
+            if a.offset % self._align != 0:
+                raise ValueError(
+                    f"Address offset {a.offset} is not aligned to {self._align}"
+                )
+            start = a.offset // self._align
+            n_pages = max(1, math.ceil(a.size / self._align))
+            indices.extend(range(start, start + n_pages))
+        return indices
+
+    ############################################################
+    # Server / client management
+    ############################################################
+    def get_transfer_channel_server(self) -> NixlTransferChannelServer:
+        return self._server
+
+    def get_transfer_channel_client(
+        self,
+        peer_advertise_url: str,
+    ) -> NixlTransferChannelClient:
+        with self._lock:
+            client = self._clients.get(peer_advertise_url)
+            if client is not None:
+                return client
+
+        # Not yet known: actively connect to the peer and perform the handshake.
+        client = self._connect(peer_advertise_url)
+        return self.register_client(peer_advertise_url, client)
+
+    def get_num_connected_clients(self) -> int:
+        with self._lock:
+            return len(self._clients)
+
+    def register_client(
+        self, key: str, client: NixlTransferChannelClient
+    ) -> NixlTransferChannelClient:
+        """
+        Register a client for the given key (peer advertise url).
+
+        A client already registered for ``key`` is kept; ``client`` is then a
+        redundant duplicate (the active connect and the peer's inbound
+        connection can race) and is closed.
+
+        Args:
+            key: The peer advertise url to register the client under.
+            client: A freshly created NixlTransferChannelClient for the peer.
+
+        Returns:
+            The canonical client for ``key``: the previously registered one if
+            present, otherwise ``client``.
+        """
+        with self._lock:
+            existing = self._clients.get(key)
+            if existing is None:
+                self._clients[key] = client
+                return client
+            if existing is client:
+                return client
+
+        logger.debug("Reusing existing transfer channel client for %s", key)
+        try:
+            client.close()
+        except Exception:  # noqa: BLE001
+            logger.exception(
+                "Error closing duplicate transfer channel client for %s", key
+            )
+        return existing
+
+    def remove_transfer_channel_client(self, peer_advertise_url: str) -> None:
+        """Discard the client for ``peer_advertise_url`` and free its resources.
+
+        Call this when reads from the peer are no longer needed (e.g. the
+        owning L2 adapter is being removed). Any task ids previously returned by
+        that client become invalid. A later ``get_transfer_channel_client`` for
+        the same peer returns a fresh client. The peer is not notified.
+
+        Calling this for a peer with no current client does nothing.
+
+        Args:
+            peer_advertise_url: The ``host:port`` of the peer, as passed to
+                ``get_transfer_channel_client``.
+        """
+        with self._lock:
+            client = self._clients.pop(peer_advertise_url, None)
+        if client is None:
+            return
+        try:
+            client.close()
+        except Exception:  # noqa: BLE001 - best-effort cleanup
+            logger.exception(
+                "Error closing transfer channel client for %s", peer_advertise_url
+            )
+
+    ############################################################
+    # Cleanup
+    ############################################################
+    def close(self) -> None:
+        with self._lock:
+            server = self._server
+            clients = list(self._clients.values())
+            self._clients.clear()
+
+        if server is not None:
+            server.close()
+        for client in clients:
+            client.close()
+
+        try:
+            self.agent.release_dlist_handle(self.local_handle)
+        except Exception:  # noqa: BLE001
+            pass
+        try:
+            self.agent.deregister_memory(self._reg_descs)
+        except Exception:  # noqa: BLE001
+            pass
+
+    ############################################################
+    # Helper functions
+    ############################################################
+    def _recv_handshake(self, socket: "zmq.Socket", server_url: str) -> bytes:
+        """Receive one handshake reply, mapping a timeout to a clear error.
+
+        Args:
+            socket: The REQ socket awaiting the server's reply.
+            server_url: The peer url being dialed (for the error message).
+
+        Returns:
+            The raw reply bytes.
+
+        Raises:
+            TimeoutError: If no reply arrives within the handshake timeout
+                (e.g. the url is wrong/unreachable or the port is blocked).
+        """
+        try:
+            return socket.recv()
+        except zmq.Again as err:
+            raise LMCacheTimeoutError(
+                f"Timed out after {_HANDSHAKE_TIMEOUT_MS / 1000:.0f}s waiting for "
+                f"a transfer-channel handshake reply from {server_url!r}. Check "
+                f"that the peer is running and that the url/port is correct and "
+                f"reachable."
+            ) from err
+
+    def _connect(self, server_url: str) -> NixlTransferChannelClient:
+        socket = self.zmq_context.socket(zmq.REQ)
+        socket.setsockopt(zmq.LINGER, 0)
+        socket.setsockopt(zmq.RCVTIMEO, _HANDSHAKE_TIMEOUT_MS)
+        host, port = _parse_url(server_url)
+        socket.connect(f"tcp://{host}:{port}")
+        try:
+            # Stage 1: exchange agent metadata.
+            socket.send(
+                msgspec.msgpack.encode(
+                    InitReq(
+                        agent_name=self.agent_name,
+                        agent_meta=self.agent.get_agent_metadata(),
+                    )
+                )
+            )
+            init_resp = msgspec.msgpack.decode(
+                self._recv_handshake(socket, server_url), type=HandshakeMsg
+            )
+            assert isinstance(init_resp, InitResp)
+            server_agent_name = self.agent.add_remote_agent(init_resp.agent_meta)
+
+            # Stage 2: exchange transfer-descriptor lists.
+            socket.send(
+                msgspec.msgpack.encode(
+                    MemRegReq(
+                        sender_agent_name=self.agent_name,
+                        sender_advertise_url=self.advertise_url,
+                        xfer_descs=self.serialized_xfer_descs,
+                    )
+                )
+            )
+            memreg_resp = msgspec.msgpack.decode(
+                self._recv_handshake(socket, server_url), type=HandshakeMsg
+            )
+            assert isinstance(memreg_resp, MemRegResp)
+            remote_xfer_dlist = self.agent.deserialize_descs(memreg_resp.xfer_descs)
+            remote_handle = self.agent.prep_xfer_dlist(
+                server_agent_name, remote_xfer_dlist
+            )
+        finally:
+            socket.close(linger=0)
+
+        return NixlTransferChannelClient(
+            context=self,
+            remote_agent_name=server_agent_name,
+            remote_dlist_handle=remote_handle,
+        )
+
+
+############################################################
+# Factory registration
+############################################################
+def create_nixl_transfer_channel_context(
+    l1_memory_desc: L1MemoryDesc,
+    listen_url: str,
+    advertise_url: str,
+    **kwargs,
+) -> NixlTransferChannelContext:
+    """Create a ``NixlTransferChannelContext``.
+
+    Args:
+        l1_memory_desc: Describes the L1 memory region to register.
+        listen_url: ``host:port`` this peer's server binds to.
+        advertise_url: ``host:port`` this peer advertises as its identity.
+        **kwargs: Accepts ``backends`` (an optional list of nixl backends,
+            e.g. ``["UCX"]``).
+
+    Returns:
+        A new ``NixlTransferChannelContext`` instance.
+    """
+    return NixlTransferChannelContext(
+        l1_memory_desc=l1_memory_desc,
+        listen_url=listen_url,
+        advertise_url=advertise_url,
+        backends=kwargs.get("backends"),
+    )
+
+
+register_transfer_channel_factory("nixl", create_nixl_transfer_channel_context)
diff --git a/lmcache/v1/ec_engine.py b/lmcache/v1/ec_engine.py
new file mode 100644
index 0000000..237bfb9
--- /dev/null
+++ b/lmcache/v1/ec_engine.py
@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Encoder Cache (EC) engine.
+
+Mirrors the KV cache engine's layering, but each EC entry is keyed by one
+multimodal hash and stores a single tensor of shape ``[num_tokens,
+hidden_size]``. EC does not require token chunking, layerwise operations, or
+paged gather/scatter.
+
+See ``docs/design/v1/encoder-cache.md`` for the broader design.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Optional
+import hashlib
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventManager
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.storage_manager import StorageManager
+
+logger = init_logger(__name__)
+
+# Sentinel ``world_size``/``worker_id`` used in EC cache keys. Encoder outputs
+# are replicated across tensor-parallel ranks (every rank produces the same
+# tensor for a given mm_hash), so EC entries are deduplicated to a single
+# logical "rank" on disk. Concurrent puts from multiple ranks land on the same
+# key and are idempotent (identical contents).
+_EC_KEY_WORLD_SIZE = 1
+_EC_KEY_WORKER_ID = 0
+
+
+def _stable_u64_from_str(s: str) -> int:
+    """Hash an arbitrary string into a stable 64-bit unsigned int.
+
+    Used to project arbitrary multimodal-hash strings (which may be opaque,
+    not hex) into the ``chunk_hash: int`` field of :class:`CacheEngineKey`.
+    """
+    digest = hashlib.sha256(str(s).encode("utf-8")).digest()
+    return int.from_bytes(digest[:8], byteorder="big", signed=False)
+
+
+class ECCacheEngine:
+    """LMCache-backed engine for vLLM encoder cache (EC) tensors.
+
+    The engine speaks tensors, not container objects: the vLLM-aware adapter
+    is responsible for reading from / writing to vLLM's ``encoder_cache``
+    dict. The engine itself only needs ``mm_hash`` and a tensor.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        encoder_dtype: torch.dtype,
+    ) -> None:
+        """Initialize the EC cache engine.
+
+        Args:
+            config: LMCache engine configuration; supplies storage backends.
+            metadata: LMCache metadata describing model identity. Only
+                ``model_name`` is used in the EC cache key; ``world_size``
+                and ``worker_id`` are intentionally ignored (see module
+                comment) to keep EC entries shared across TP ranks.
+            encoder_dtype: dtype of the encoder output tensors. Used as the
+                dtype field of the on-disk cache key, so it must be stable
+                across processes that share the same EC cache. Decoupled
+                from ``metadata.kv_dtype`` so that changing KV quantization
+                does not invalidate EC entries.
+
+        Raises:
+            ValueError: if no non-allocator storage backend is configured.
+        """
+        self.config = config
+        self.metadata = metadata
+        self._model_name = metadata.model_name
+        self._dtype = encoder_dtype
+
+        self._event_manager = EventManager()
+        self._storage_manager = StorageManager(
+            config=config,
+            metadata=metadata,
+            event_manager=self._event_manager,
+            lmcache_worker=None,
+            async_lookup_server=None,
+        )
+
+        available_backends = self._storage_manager.get_non_allocator_backends()
+        if len(available_backends) == 0:
+            raise ValueError(
+                "EC cache engine found no storage backends. Configure at least one "
+                "backend (e.g. local_disk, remote_url, gds_path, nixl storage plugin)."
+            )
+
+        logger.info(
+            "Initialized EC cache engine with storage backends=%s",
+            available_backends,
+        )
+
+    def close(self) -> None:
+        """Close EC storage resources and background workers."""
+        if hasattr(self, "_storage_manager") and self._storage_manager is not None:
+            self._storage_manager.close()
+
+    def _make_cache_key(self, mm_hash: str) -> CacheEngineKey:
+        return CacheEngineKey(
+            model_name=self._model_name,
+            world_size=_EC_KEY_WORLD_SIZE,
+            worker_id=_EC_KEY_WORKER_ID,
+            chunk_hash=_stable_u64_from_str(mm_hash),
+            dtype=self._dtype,
+            request_configs={},
+        )
+
+    def contains(self, mm_hash: str) -> bool:
+        """Return whether encoder cache exists for the given multimodal hash."""
+        key = self._make_cache_key(mm_hash)
+        return self._storage_manager.contains(key) is not None
+
+    def put(self, mm_hash: str, tensor: torch.Tensor) -> bool:
+        """Store one encoder output tensor under ``mm_hash``.
+
+        Args:
+            mm_hash: multimodal-input identifier produced by vLLM.
+            tensor: encoder output, shape ``[num_tokens, hidden_size]``,
+                on any device. The engine copies it into a pinned CPU
+                buffer; the caller's tensor is not retained.
+
+        Returns:
+            ``True`` if a store task was submitted to the storage manager;
+            ``False`` if the underlying allocator could not provide a buffer
+            (transient resource pressure). Never returns ``False`` for
+            caller misuse — pass a real tensor.
+        """
+        key = self._make_cache_key(mm_hash)
+
+        # Allocate via LMCache allocator (LocalCPUBackend) through StorageManager.
+        # Preserve the source tensor dtype to avoid precision loss.
+        mem_obj = self._storage_manager.allocate(
+            shapes=tensor.shape,
+            dtypes=tensor.dtype,
+            fmt=MemoryFormat.EC_TD,
+            eviction=True,
+            busy_loop=False,
+        )
+        if mem_obj is None or mem_obj.tensor is None:
+            logger.warning("EC allocate failed; skipping put for key %s", key)
+            return False
+
+        # Single copy: src -> pinned CPU buffer, handles device transfer + dtype cast.
+        mem_obj.tensor.copy_(tensor)
+
+        self._storage_manager.batched_put(
+            [key],
+            [mem_obj],
+        )
+        nbytes = tensor.element_size() * tensor.numel()
+        logger.info("EC put: stored %d bytes for mm_hash=%s", nbytes, mm_hash)
+        return True
+
+    def get(self, mm_hash: str, device: str) -> Optional[torch.Tensor]:
+        """Load the encoder output tensor for ``mm_hash`` if present.
+
+        Args:
+            mm_hash: multimodal-input identifier produced by vLLM.
+            device: torch device string (e.g. ``"cuda"``, ``"cpu"``) onto
+                which the returned tensor should reside.
+
+        Returns:
+            The encoder tensor on the requested device, or ``None`` on a
+            cache miss. The returned tensor never aliases an LMCache-managed
+            buffer — callers may keep it indefinitely.
+        """
+        key = self._make_cache_key(mm_hash)
+
+        mem_objs = self._storage_manager.batched_get([key])
+        mem_obj = mem_objs[0]
+        if mem_obj is None:
+            return None
+        if mem_obj.tensor is None:
+            mem_obj.ref_count_down()
+            return None
+
+        try:
+            out = mem_obj.tensor.to(device=device)
+            # Ensure the returned tensor doesn't alias the buffer we're about
+            # to release: ``.to(same_device)`` is a no-op view, so clone.
+            if out.data_ptr() == mem_obj.tensor.data_ptr():
+                out = out.clone()
+            return out
+        finally:
+            mem_obj.ref_count_down()
diff --git a/lmcache/v1/event_manager.py b/lmcache/v1/event_manager.py
new file mode 100644
index 0000000..9913edb
--- /dev/null
+++ b/lmcache/v1/event_manager.py
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from enum import Enum, auto
+import asyncio
+import threading
+
+
+class EventType(Enum):
+    LOADING = auto()
+
+
+class EventStatus(Enum):
+    ONGOING = auto()
+    DONE = auto()
+    NOT_FOUND = auto()
+
+
+class EventManager:
+    """
+    A thread-safe event manager to manage asynchronous events.
+    Each event is identified by its type and a unique id.
+    Events are organized by status for efficient counting.
+    """
+
+    def __init__(self) -> None:
+        # Guard by lock
+        # Structure: events[event_type][event_status][event_id] = future
+        self.events: dict[EventType, dict[EventStatus, dict[str, asyncio.Future]]] = {
+            et: {es: {} for es in EventStatus} for et in EventType
+        }
+        self.lock = threading.Lock()
+
+    def add_event(
+        self,
+        event_type: EventType,
+        event_id: str,
+        future: asyncio.Future,
+    ) -> None:
+        """
+        Add an event with the given type and id.
+        """
+        with self.lock:
+            status_dict = self.events.get(event_type, None)
+            assert status_dict is not None, (
+                f"Invalid event type {event_type} in EventManager."
+            )
+            status_dict[EventStatus.ONGOING][event_id] = future
+
+    def pop_event(
+        self,
+        event_type: EventType,
+        event_id: str,
+    ) -> asyncio.Future:
+        """
+        Pop and return the event with the given type and id.
+        """
+        with self.lock:
+            status_dict = self.events.get(event_type, None)
+            assert status_dict is not None, (
+                f"Invalid event type {event_type} in EventManager."
+            )
+            done_events = status_dict[EventStatus.DONE]
+            assert event_id in done_events, (
+                f"Event {event_id} of type {event_type} is not done or not found."
+            )
+            return done_events.pop(event_id)
+
+    def update_event_status(
+        self,
+        event_type: EventType,
+        event_id: str,
+        status: EventStatus,
+    ) -> None:
+        """
+        Update the status of the event with the given type and id.
+        """
+        with self.lock:
+            status_dict = self.events.get(event_type, None)
+            assert status_dict is not None, (
+                f"Invalid event type {event_type} in EventManager."
+            )
+            # Find the event in any status dict
+            event = None
+            for s in EventStatus:
+                if event_id in status_dict[s]:
+                    event = status_dict[s].pop(event_id)
+                    break
+
+            if event is None:
+                raise KeyError(f"Event {event_id} of type {event_type} not found.")
+
+            # Move to new status dict
+            status_dict[status][event_id] = event
+
+    def get_event_status(
+        self,
+        event_type: EventType,
+        event_id: str,
+    ) -> EventStatus:
+        """
+        Get the status of the event with the given type and id.
+        """
+        with self.lock:
+            status_dict = self.events.get(event_type, None)
+            assert status_dict is not None, (
+                f"Invalid event type {event_type} in EventManager."
+            )
+            for status in EventStatus:
+                if event_id in status_dict[status]:
+                    return status
+            return EventStatus.NOT_FOUND
+
+    def get_events_count_by_status(
+        self,
+        event_type: EventType,
+        status: EventStatus,
+    ) -> int:
+        """
+        Get the count of events for the given event type and status.
+        This is a lightweight O(1) operation using dict length.
+        """
+        with self.lock:
+            status_dict = self.events.get(event_type, None)
+            if status_dict is None:
+                return 0
+            return len(status_dict[status])
+
+    def get_event_future(
+        self,
+        event_type: EventType,
+        event_id: str,
+    ) -> asyncio.Future:
+        """
+        Pop and return the event with the given type and id.
+        """
+        with self.lock:
+            status_dict = self.events.get(event_type, None)
+            assert status_dict is not None, (
+                f"Invalid event type {event_type} in EventManager."
+            )
+            done_events = status_dict[EventStatus.DONE]
+            assert event_id in done_events, (
+                f"Event {event_id} of type {event_type} is not done or not found."
+            )
+            return done_events[event_id]
diff --git a/lmcache/v1/exceptions/__init__.py b/lmcache/v1/exceptions/__init__.py
new file mode 100644
index 0000000..fe2af40
--- /dev/null
+++ b/lmcache/v1/exceptions/__init__.py
@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Custom exceptions for LMCache v1.
+"""
+
+
+class IrrecoverableException(Exception):
+    """
+    Exception raised when an irrecoverable error occurs.
+
+    This exception indicates that the system has encountered an error
+    that cannot be recovered from, and the health monitor should stop
+    checking and propagate the error up.
+    """
+
+    pass
diff --git a/lmcache/v1/gpu_connector/__init__.py b/lmcache/v1/gpu_connector/__init__.py
new file mode 100644
index 0000000..cc8a367
--- /dev/null
+++ b/lmcache/v1/gpu_connector/__init__.py
@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.utils import EngineType
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.gpu_connectors import GPUConnectorInterface
+from lmcache.v1.gpu_connector.mock_gpu_connector import MockGPUConnector
+from lmcache.v1.gpu_connector.utils import LayoutHints, need_gpu_interm_buffer
+from lmcache.v1.metadata import LMCacheMetadata
+
+# Boolean config flags whose underlying implementations exist only on a
+# subset of accelerators. Each entry is ``(attr_name, human_label,
+# supported_devices)``; the human label is what appears in the error message.
+_DEVICE_SCOPED_VLLM_BOOL_FEATURES: tuple[tuple[str, str, frozenset[str]], ...] = (
+    ("enable_blending", "config.enable_blending", frozenset({"cuda", "xpu"})),
+    ("use_gpu_connector_v3", "config.use_gpu_connector_v3", frozenset({"cuda", "xpu"})),
+)
+
+
+def _validate_vllm_device_features(config: LMCacheEngineConfig) -> None:
+    """Reject vLLM configurations that can't run on the active device.
+
+    Three classes of misconfiguration are rejected here, all *before* any
+    device-specific construction so the error surfaces as a plain
+    ``ValueError`` instead of a deep ``torch.cuda.Stream()`` crash or a
+    ``RuntimeError`` from ``torch.device('musa:0')`` on a non-MUSA build:
+
+    1. Any flag in :data:`_DEVICE_SCOPED_VLLM_BOOL_FEATURES` requested on
+       a device that has no implementation for that path.
+    2. ``config.use_layerwise=True`` on HPU — HPU only ships
+       :class:`VLLMPagedMemHPUConnectorV2`; previously, the dispatch silently
+       fell through to the CUDA layerwise connector.
+
+    Args:
+        config: The LMCache engine configuration.
+
+    Raises:
+        ValueError: For any of the unsupported combinations above.
+    """
+    for attr, label, supported_devices in _DEVICE_SCOPED_VLLM_BOOL_FEATURES:
+        if torch_device_type not in supported_devices and getattr(config, attr):
+            supported = "/".join(sorted(supported_devices))
+            raise ValueError(
+                f"{label}=True is only supported on {supported}; the active "
+                f"device is '{torch_device_type}'. Set {attr}=False or run "
+                "on a supported accelerator build."
+            )
+
+    if torch_device_type == "hpu" and config.use_layerwise:
+        raise ValueError(
+            "config.use_layerwise=True is not supported on HPU; LMCache "
+            "ships no layerwise HPU connector. Set use_layerwise=False or "
+            "run on a CUDA-capable build."
+        )
+
+
+def CreateGPUConnector(
+    config: LMCacheEngineConfig,
+    metadata: LMCacheMetadata,
+    engine: EngineType,
+    layout_hints: LayoutHints | None = None,
+) -> GPUConnectorInterface:
+    """
+    Create a GPU Connector based on the configuration and metadata.
+
+    Args:
+        config: The LMCache engine configuration.
+        metadata: The LMCache metadata.
+        engine: The serving engine type (EngineType.VLLM, EngineType.SGLANG,
+                EngineType.TRTLLM, or EngineType.MOCK).
+        layout_hints: Optional hints from the serving engine about KV cache
+            layout (e.g. ``{"kv_layout": "HND"}``).
+    """
+    use_gpu = need_gpu_interm_buffer(config)
+
+    if engine == EngineType.SGLANG:
+        if torch_device_type == "musa":
+            raise ValueError(
+                "SGLang on MUSA is not supported; only the vLLM MUSA "
+                "connector is available."
+            )
+
+        num_layer, _, chunk_size, num_kv_head, head_dim = metadata.kv_shape
+        hidden_dim_size = num_kv_head * head_dim
+        local_worker_id = metadata.local_worker_id
+        torch_dev.set_device(local_worker_id)
+        device = torch.device(f"{torch_device_type}:{local_worker_id}")
+        kv_dtype = metadata.kv_dtype
+
+        if torch_device_type == "xpu":
+            # First Party
+            from lmcache.v1.gpu_connector.xpu_connectors import (
+                SGLangLayerwiseXPUConnector,
+                SGLangXPUConnector,
+            )
+
+            if config.use_layerwise:
+                return SGLangLayerwiseXPUConnector(
+                    hidden_dim_size,
+                    num_layer,
+                    use_gpu=use_gpu,
+                    chunk_size=chunk_size,
+                    dtype=kv_dtype,
+                    device=device,
+                )
+            else:
+                return SGLangXPUConnector(
+                    hidden_dim_size,
+                    num_layer,
+                    use_gpu=use_gpu,
+                    chunk_size=chunk_size,
+                    dtype=kv_dtype,
+                    device=device,
+                )
+        else:  # GPU for SGLang
+            # First Party
+            from lmcache.v1.gpu_connector.gpu_connectors import (
+                SGLangGPUConnector,
+                SGLangLayerwiseGPUConnector,
+            )
+
+            if config.use_layerwise:
+                return SGLangLayerwiseGPUConnector(
+                    hidden_dim_size,
+                    num_layer,
+                    use_gpu=use_gpu,
+                    chunk_size=chunk_size,
+                    dtype=kv_dtype,
+                    device=device,
+                )
+            else:
+                return SGLangGPUConnector(
+                    hidden_dim_size,
+                    num_layer,
+                    use_gpu=use_gpu,
+                    chunk_size=chunk_size,
+                    dtype=kv_dtype,
+                    device=device,
+                )
+    elif engine == EngineType.VLLM:
+        _validate_vllm_device_features(config)
+
+        # First Party
+        from lmcache.v1.gpu_connector.gpu_connectors import (
+            VLLMBufferLayerwiseGPUConnector,
+            VLLMPagedMemGPUConnectorV2,
+            VLLMPagedMemGPUConnectorV3,
+            VLLMPagedMemLayerwiseGPUConnector,
+        )
+
+        local_worker_id = metadata.local_worker_id
+        torch_dev.set_device(local_worker_id)
+        device = torch.device(f"{torch_device_type}:{local_worker_id}")
+
+        if torch_device_type == "cuda":
+            # First Party
+            from lmcache.v1.gpu_connector.gpu_connectors import (
+                VLLMBufferLayerwiseGPUConnector,
+                VLLMPagedMemGPUConnectorV2,
+                VLLMPagedMemGPUConnectorV3,
+                VLLMPagedMemLayerwiseGPUConnector,
+            )
+
+            if config.use_layerwise:
+                if config.enable_blending:
+                    return VLLMBufferLayerwiseGPUConnector.from_metadata(
+                        metadata, use_gpu, device, layout_hints=layout_hints
+                    )
+                else:
+                    return VLLMPagedMemLayerwiseGPUConnector.from_metadata(
+                        metadata, use_gpu, device, layout_hints=layout_hints
+                    )
+
+            if config.use_gpu_connector_v3:
+                return VLLMPagedMemGPUConnectorV3.from_metadata(
+                    metadata, use_gpu, device, layout_hints=layout_hints
+                )
+            else:
+                return VLLMPagedMemGPUConnectorV2.from_metadata(
+                    metadata, use_gpu, device, layout_hints=layout_hints
+                )
+        elif torch_device_type == "xpu":
+            # First Party
+            from lmcache.v1.gpu_connector.xpu_connectors import (
+                VLLMBufferLayerwiseXPUConnector,
+                VLLMPagedMemLayerwiseXPUConnector,
+                VLLMPagedMemXPUConnectorV2,
+                VLLMPagedMemXPUConnectorV3,
+            )
+
+            if config.use_layerwise:
+                if config.enable_blending:
+                    return VLLMBufferLayerwiseXPUConnector.from_metadata(
+                        metadata, use_gpu, device
+                    )
+                else:
+                    return VLLMPagedMemLayerwiseXPUConnector.from_metadata(
+                        metadata, use_gpu, device
+                    )
+
+            if config.use_gpu_connector_v3:
+                return VLLMPagedMemXPUConnectorV3.from_metadata(
+                    metadata, use_gpu, device
+                )
+            else:
+                return VLLMPagedMemXPUConnectorV2.from_metadata(
+                    metadata, use_gpu, device
+                )
+        elif torch_device_type == "musa":
+            # First Party
+            from lmcache.v1.gpu_connector.musa_connectors import (
+                VLLMPagedMemLayerwiseMUSAConnector,
+                VLLMPagedMemMUSAConnectorV2,
+            )
+
+            if config.use_layerwise:
+                return VLLMPagedMemLayerwiseMUSAConnector.from_metadata(
+                    metadata, use_musa=use_gpu, device=device
+                )
+            return VLLMPagedMemMUSAConnectorV2.from_metadata(metadata, use_gpu, device)
+        elif torch_device_type == "hpu":
+            # First Party
+            from lmcache.v1.gpu_connector.hpu_connector import (
+                VLLMPagedMemHPUConnectorV2,
+            )
+
+            return VLLMPagedMemHPUConnectorV2.from_metadata(metadata, use_gpu, device)
+        else:
+            raise RuntimeError(f"No supported {torch_device_type} connector found.")
+
+    elif engine == EngineType.TRTLLM:
+        # First Party
+        from lmcache.v1.gpu_connector.gpu_connectors import TRTLLMGPUConnector
+
+        local_worker_id = metadata.local_worker_id
+        torch_dev.set_device(local_worker_id)
+        device = torch.device(f"{torch_device_type}:{local_worker_id}")
+        return TRTLLMGPUConnector.from_metadata(metadata, device=device)
+
+    elif engine == EngineType.MOCK:
+        kv_shape = metadata.kv_shape
+        return MockGPUConnector(kv_shape=kv_shape)
+    else:
+        raise RuntimeError(f"Unsupported engine: {engine}")
diff --git a/lmcache/v1/gpu_connector/_cufile_async.py b/lmcache/v1/gpu_connector/_cufile_async.py
new file mode 100644
index 0000000..89e5f50
--- /dev/null
+++ b/lmcache/v1/gpu_connector/_cufile_async.py
@@ -0,0 +1,401 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal ctypes wrapper around the cuFile async C API.
+
+kvikio's ``raw_read_async`` / ``raw_write_async`` work but on ext4 +
+real GDS they leave ~60% read throughput on the table compared to the
+bare C path (``cuFileReadAsync`` + ``cuFileStreamRegister`` + batched
+submit + single ``cudaStreamSynchronize``). This module exposes the
+same C primitives directly from Python so callers that batch
+submissions can match the C-direct throughput.
+
+Surface:
+
+- :func:`register_buffer` / :func:`deregister_buffer` — wrap
+  ``cuFileBufRegister`` / ``cuFileBufDeregister`` on a torch tensor.
+- :func:`register_stream` / :func:`deregister_stream` — wrap
+  ``cuFileStreamRegister`` / ``cuFileStreamDeregister`` on a raw
+  CUDA stream handle.
+- :class:`AsyncHandle` — opens a file with ``O_DIRECT`` (required by
+  cuFile on ext4) and registers the cuFile handle. ``read_async`` /
+  ``write_async`` enqueue an async IO on a stream and return a
+  :class:`Submission`. Callers run ``cudaStreamSynchronize`` once to
+  drain a batch; :meth:`Submission.bytes_done` returns the actual
+  byte count after the sync.
+
+This module is intentionally narrow: no thread pool, no future
+abstraction, no LRU. It is the layer :class:`GDSContext`
+(``lmcache.v1.gpu_connector.gds_context``) uses to talk to libcufile on
+the GDS DMA fast path.
+"""
+
+# Standard
+from typing import TYPE_CHECKING, Any, Optional
+import ctypes
+import os
+
+# Third Party
+import torch
+
+if TYPE_CHECKING:
+    # Third Party
+    from cufile.bindings import CUfileError
+
+# ``cufile.bindings`` dlopens ``libcufile.so`` at import time, which is absent
+# on CPU-only / macOS hosts. Importing this module (transitively pulled in by
+# the CLI command discovery via ``storage_manager``) must not trigger that, so
+# every cufile symbol is imported lazily inside the function that uses it and
+# the dlopen happens only when GDS is actually exercised. This mirrors the
+# lazy ``import cufile`` in the legacy ``GdsBackend``.
+
+# --- Declare ctypes signatures for the async symbols (see cufile.h) --
+
+
+def _declare_signatures() -> None:
+    """Set argtypes/restype on libcufile symbols. Idempotent."""
+    # Third Party
+    from cufile.bindings import CUfileError, libcufile
+
+    if getattr(libcufile.cuFileReadAsync, "argtypes", None):
+        return
+    libcufile.cuFileReadAsync.argtypes = [
+        ctypes.c_void_p,  # CUfileHandle_t fh
+        ctypes.c_void_p,  # void *bufPtr_base
+        ctypes.POINTER(ctypes.c_size_t),  # size_t *size_p
+        ctypes.POINTER(ctypes.c_int64),  # off_t *file_offset_p
+        ctypes.POINTER(ctypes.c_int64),  # off_t *bufPtr_offset_p
+        ctypes.POINTER(ctypes.c_int64),  # ssize_t *bytes_read_p
+        ctypes.c_void_p,  # CUstream stream
+    ]
+    libcufile.cuFileReadAsync.restype = CUfileError
+
+    libcufile.cuFileWriteAsync.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_size_t),
+        ctypes.POINTER(ctypes.c_int64),
+        ctypes.POINTER(ctypes.c_int64),
+        ctypes.POINTER(ctypes.c_int64),
+        ctypes.c_void_p,
+    ]
+    libcufile.cuFileWriteAsync.restype = CUfileError
+
+    libcufile.cuFileStreamRegister.argtypes = [ctypes.c_void_p, ctypes.c_uint]
+    libcufile.cuFileStreamRegister.restype = CUfileError
+
+    libcufile.cuFileStreamDeregister.argtypes = [ctypes.c_void_p]
+    libcufile.cuFileStreamDeregister.restype = CUfileError
+
+
+_driver_opened = False
+
+
+def _ensure_driver_open() -> None:
+    """Idempotently open the cuFile driver and declare async signatures."""
+    global _driver_opened
+    if _driver_opened:
+        return
+    # Third Party
+    from cufile.bindings import cuFileDriverOpen
+
+    cuFileDriverOpen()
+    _declare_signatures()
+    _driver_opened = True
+
+
+def close_driver() -> None:
+    """Close the cuFile driver. Optional — useful in tests."""
+    global _driver_opened
+    if not _driver_opened:
+        return
+    # Third Party
+    from cufile.bindings import cuFileDriverClose
+
+    try:
+        cuFileDriverClose()
+    finally:
+        _driver_opened = False
+
+
+def _check(err: "CUfileError", op: str) -> None:
+    """Convert a non-zero ``CUfileError_t`` into a Python exception."""
+    if err.err != 0:
+        raise RuntimeError(
+            f"{op} failed: cuFileError(err={err.err}, cu_err={err.cu_err})"
+        )
+
+
+# --- Handle registration -------------------------------------------
+
+
+def register_handle(fd: int) -> Any:
+    """Register an open fd with cuFile and return the ``CUfileHandle_t``.
+
+    Opens the cuFile driver on first use. The returned handle is accepted
+    directly as the first argument of ``cuFileReadAsync`` / ``cuFileWriteAsync``.
+    """
+    _ensure_driver_open()
+    # Third Party
+    from cufile.bindings import cuFileHandleRegister
+
+    return cuFileHandleRegister(fd)
+
+
+def deregister_handle(handle: Any) -> None:
+    """Reverse of :func:`register_handle` (``cuFileHandleDeregister``)."""
+    # Third Party
+    from cufile.bindings import cuFileHandleDeregister
+
+    cuFileHandleDeregister(handle)
+
+
+# --- Buffer / stream registration ----------------------------------
+
+
+def register_buffer(buf: torch.Tensor) -> None:
+    """Register a device tensor with cuFile for GDS DMA.
+
+    Must be called before any ``read_async`` / ``write_async`` whose
+    ``buf_base`` falls inside this tensor's allocation. Implicitly
+    opens the cuFile driver on first use.
+
+    Uses ``libcufile.cuFileBufRegister`` directly (not the
+    ``cufile.bindings`` wrapper) because the wrapper hides the error
+    code by raising internally — we want the raw status so callers
+    see ``cuFileError(err=…, cu_err=…)`` instead of a Python re-raise.
+    """
+    if not buf.is_cuda:
+        raise ValueError("register_buffer: tensor must be on CUDA")
+    # Third Party
+    from cufile.bindings import libcufile
+
+    nbytes = buf.numel() * buf.element_size()
+    _check(
+        libcufile.cuFileBufRegister(
+            ctypes.c_void_p(buf.data_ptr()),
+            ctypes.c_size_t(nbytes),
+            ctypes.c_int(0),
+        ),
+        "cuFileBufRegister",
+    )
+
+
+def deregister_buffer(buf: torch.Tensor) -> None:
+    """Reverse of :func:`register_buffer`."""
+    # Third Party
+    from cufile.bindings import libcufile
+
+    _check(
+        libcufile.cuFileBufDeregister(ctypes.c_void_p(buf.data_ptr())),
+        "cuFileBufDeregister",
+    )
+
+
+# cuFileStreamRegister flags (cufile.h): declare the buffer offset, file offset,
+# and size are all set at submission time (CU_FILE_STREAM_FIXED_* = 0x1|0x2|0x4).
+# Worth ~12% higher read throughput vs 0x0 in our benchmark (write unchanged).
+# PAGE_ALIGNED_INPUTS (0x8) is omitted -- transfer sizes are not always 4 KiB.
+_STREAM_REGISTER_FLAGS = 0x7
+
+
+def register_stream(raw_stream: int) -> None:
+    """Register a CUDA stream with cuFile.
+
+    ``raw_stream`` is the integer ``CUstream`` handle — get it via
+    ``torch_dev.current_stream().cuda_stream``.
+
+    Optional for correctness (``read_async`` / ``write_async`` also take the
+    stream per call). We register with the FIXED_* flags (0x7): cuFile still
+    reads the size/offset pointers at stream-execution time -- so their storage
+    must stay alive and unchanged until completion (see ``Submission``) -- but
+    promising the values are fixed at submission lets cuFile skip per-op setup,
+    worth ~12% higher read throughput in our benchmark.
+    """
+    # Third Party
+    from cufile.bindings import libcufile
+
+    _ensure_driver_open()
+    _check(
+        libcufile.cuFileStreamRegister(
+            ctypes.c_void_p(raw_stream), _STREAM_REGISTER_FLAGS
+        ),
+        "cuFileStreamRegister",
+    )
+
+
+def deregister_stream(raw_stream: int) -> None:
+    """Reverse of :func:`register_stream`."""
+    # Third Party
+    from cufile.bindings import libcufile
+
+    _check(
+        libcufile.cuFileStreamDeregister(ctypes.c_void_p(raw_stream)),
+        "cuFileStreamDeregister",
+    )
+
+
+# --- AsyncHandle + Submission --------------------------------------
+
+
+class Submission:
+    """One in-flight ``cuFileReadAsync`` / ``cuFileWriteAsync``.
+
+    Holds the host-side ``size_p`` / ``file_offset_p`` /
+    ``bufPtr_offset_p`` / ``bytes_done_p`` storage that cuFile writes
+    into asynchronously. These ctypes objects MUST stay alive until
+    the stream actually executes the op — keep the :class:`Submission`
+    reference (or stash it in a list) until after the stream sync.
+    """
+
+    __slots__ = ("_size", "_file_offset", "_buf_offset", "_bytes_done")
+
+    def __init__(
+        self,
+        size: int,
+        file_offset: int,
+        buf_offset: int,
+    ) -> None:
+        self._size = ctypes.c_size_t(size)
+        self._file_offset = ctypes.c_int64(file_offset)
+        self._buf_offset = ctypes.c_int64(buf_offset)
+        self._bytes_done = ctypes.c_int64(0)
+
+    @property
+    def bytes_done(self) -> int:
+        """Bytes actually transferred. Valid only AFTER the stream sync."""
+        return self._bytes_done.value
+
+
+class AsyncHandle:
+    """Open file + cuFile handle wrapper.
+
+    Opens with ``O_DIRECT`` (required for cuFile's GDS fast path on
+    ext4). Optionally pre-allocates the file via ``posix_fallocate``.
+    """
+
+    __slots__ = ("_fd", "_handle", "path", "writable")
+
+    def __init__(
+        self,
+        path: str,
+        writable: bool = False,
+        fallocate_size: Optional[int] = None,
+        mode: int = 0o644,
+    ) -> None:
+        flags = os.O_DIRECT
+        if writable:
+            flags |= os.O_CREAT | os.O_RDWR
+        else:
+            flags |= os.O_RDONLY
+        self.path = path
+        self.writable = writable
+        self._fd = os.open(path, flags, mode)
+        try:
+            if fallocate_size is not None and writable:
+                os.posix_fallocate(self._fd, 0, fallocate_size)
+            self._handle = register_handle(self._fd)
+        except Exception:
+            os.close(self._fd)
+            raise
+
+    @classmethod
+    def from_fd(
+        cls,
+        fd: int,
+        handle: Any,
+        path: str,
+        writable: bool = False,
+    ) -> "AsyncHandle":
+        """Wrap an already-opened fd and registered cuFile handle.
+
+        For callers that open + register the file themselves (e.g. a slab that
+        must be created, truncated, and ``posix_fallocate``d before
+        ``cuFileHandleRegister``) and just need an ``AsyncHandle`` around the
+        result.
+        """
+        obj = cls.__new__(cls)
+        obj._fd = fd
+        obj._handle = handle
+        obj.path = path
+        obj.writable = writable
+        return obj
+
+    @property
+    def fd(self) -> int:
+        return self._fd
+
+    def read_async(
+        self,
+        buf_base: int,
+        size: int,
+        file_offset: int,
+        buf_offset: int,
+        raw_stream: int,
+    ) -> Submission:
+        """Enqueue a ``cuFileReadAsync`` on the stream.
+
+        ``buf_base`` is the registered base pointer (e.g.
+        ``buf.data_ptr()``). ``buf_offset`` is the byte offset within
+        that registration that the data should land at.
+        """
+        # Third Party
+        from cufile.bindings import libcufile
+
+        sub = Submission(size=size, file_offset=file_offset, buf_offset=buf_offset)
+        _check(
+            libcufile.cuFileReadAsync(
+                self._handle,
+                ctypes.c_void_p(buf_base),
+                ctypes.byref(sub._size),
+                ctypes.byref(sub._file_offset),
+                ctypes.byref(sub._buf_offset),
+                ctypes.byref(sub._bytes_done),
+                ctypes.c_void_p(raw_stream),
+            ),
+            "cuFileReadAsync",
+        )
+        return sub
+
+    def write_async(
+        self,
+        buf_base: int,
+        size: int,
+        file_offset: int,
+        buf_offset: int,
+        raw_stream: int,
+    ) -> Submission:
+        """Enqueue a ``cuFileWriteAsync`` on the stream."""
+        # Third Party
+        from cufile.bindings import libcufile
+
+        sub = Submission(size=size, file_offset=file_offset, buf_offset=buf_offset)
+        _check(
+            libcufile.cuFileWriteAsync(
+                self._handle,
+                ctypes.c_void_p(buf_base),
+                ctypes.byref(sub._size),
+                ctypes.byref(sub._file_offset),
+                ctypes.byref(sub._buf_offset),
+                ctypes.byref(sub._bytes_done),
+                ctypes.c_void_p(raw_stream),
+            ),
+            "cuFileWriteAsync",
+        )
+        return sub
+
+    def close(self) -> None:
+        """Deregister the cuFile handle and close the fd."""
+        if self._fd < 0:
+            return
+        try:
+            deregister_handle(self._handle)
+        finally:
+            try:
+                os.close(self._fd)
+            finally:
+                self._fd = -1
+
+    def __enter__(self) -> "AsyncHandle":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
diff --git a/lmcache/v1/gpu_connector/_gds_async.py b/lmcache/v1/gpu_connector/_gds_async.py
new file mode 100644
index 0000000..e41e9e9
--- /dev/null
+++ b/lmcache/v1/gpu_connector/_gds_async.py
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Platform dispatch for the GDS async backend.
+
+Selects the GDSContext-facing backend by platform -- the cuFile wrapper
+(:mod:`lmcache.v1.gpu_connector._cufile_async`) on NVIDIA, or the hipFile
+wrapper (:mod:`lmcache.v1.gpu_connector._hipfile_async`) on AMD ROCm. Both
+modules expose an identical API -- :class:`AsyncHandle`, :class:`Submission`,
+and the ``register_*`` / ``deregister_*`` / ``close_driver`` functions -- so
+:mod:`lmcache.v1.gpu_connector.gds_context` imports this shim as ``ca`` and is
+platform-agnostic.
+
+Selection is by ``torch.version.hip``: a ROCm torch build reports a non-None
+HIP version. Importing this shim does not dlopen any GPU IO driver; both
+backends bind ``libcufile``/``libhipfile`` lazily on first use.
+"""
+
+# Standard
+from typing import TYPE_CHECKING
+
+# Third Party
+import torch
+
+# A static type checker analyzes the TYPE_CHECKING branch only (one ``_backend``
+# binding, so no ``no-redef``); at runtime the ``elif``/``else`` pick the real
+# backend by platform.
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.gpu_connector import _cufile_async as _backend
+elif torch.version.hip is not None:
+    # First Party
+    from lmcache.v1.gpu_connector import _hipfile_async as _backend
+else:
+    # First Party
+    from lmcache.v1.gpu_connector import _cufile_async as _backend
+
+# Re-export the selected backend's surface under stable names so callers
+# (and test monkeypatches) target this module.
+AsyncHandle = _backend.AsyncHandle
+Submission = _backend.Submission
+close_driver = _backend.close_driver
+register_handle = _backend.register_handle
+deregister_handle = _backend.deregister_handle
+register_buffer = _backend.register_buffer
+deregister_buffer = _backend.deregister_buffer
+register_stream = _backend.register_stream
+deregister_stream = _backend.deregister_stream
diff --git a/lmcache/v1/gpu_connector/_hipfile_async.py b/lmcache/v1/gpu_connector/_hipfile_async.py
new file mode 100644
index 0000000..984dc52
--- /dev/null
+++ b/lmcache/v1/gpu_connector/_hipfile_async.py
@@ -0,0 +1,532 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal ctypes wrapper around the hipFile async C API (AMD ROCm).
+
+AMD analog of :mod:`lmcache.v1.gpu_connector._cufile_async`. hipFile
+(``ROCm/hipFile``, "AMD Infinity Storage") is the ROCm GPUDirect-Storage
+library; its async surface mirrors cuFile 1:1 (``hipFileReadAsync`` +
+``hipFileStreamRegister`` + batched submit + single ``hipStreamSynchronize``),
+so this module exposes the same primitives and the **same Python surface** as
+the cuFile wrapper -- :class:`GDSContext` talks to either through the
+:mod:`lmcache.v1.gpu_connector._gds_async` dispatch shim.
+
+Surface (identical to ``_cufile_async``):
+
+- :func:`register_buffer` / :func:`deregister_buffer` — wrap
+  ``hipFileBufRegister`` / ``hipFileBufDeregister`` on a torch tensor.
+- :func:`register_stream` / :func:`deregister_stream` — wrap
+  ``hipFileStreamRegister`` / ``hipFileStreamDeregister`` on a raw HIP
+  stream handle.
+- :func:`register_handle` / :func:`deregister_handle` — wrap
+  ``hipFileHandleRegister`` / ``hipFileHandleDeregister`` on an fd.
+- :class:`AsyncHandle` — opens a file with ``O_DIRECT`` (required by
+  hipFile) and registers the hipFile handle. ``read_async`` /
+  ``write_async`` enqueue an async IO on a stream and return a
+  :class:`Submission`. Callers run ``hipStreamSynchronize`` once to drain a
+  batch; :meth:`Submission.bytes_done` returns the actual byte count.
+
+Unlike cuFile (which ships an ``nvidia.cufile`` Python binding), hipFile has
+no Python package, so every symbol -- driver lifecycle, handle/buffer
+registration, and the ``hipFileError_t`` / ``hipFileDescr_t`` structs -- is
+bound directly from ``libhipfile.so`` via ctypes here. Requires ROCm >= 7.2.0.
+"""
+
+# Standard
+from typing import Any, Optional
+import ctypes
+import os
+import threading
+
+# Third Party
+import torch
+
+# ``libhipfile.so`` is dlopened lazily (see ``_lib``) so importing this module
+# on a CPU-only / NVIDIA host -- it is transitively pulled in by the GDS
+# dispatch shim during CLI command discovery -- does not require the ROCm GPU
+# IO driver to be present. This mirrors the lazy ``import cufile`` in the cuFile
+# wrapper.
+
+_LIBHIPFILE_SONAME = "libhipfile.so"
+
+# hipFile handle type for a POSIX fd (hipfile.h: ``hipFileHandleTypeOpaqueFD``).
+_HIPFILE_HANDLE_TYPE_OPAQUE_FD = 1
+
+# hipFileStreamRegister flags (hipfile.h): buffer offset, file offset, and size
+# are all fixed at submission time (HIPFILE_STREAM_FIXED_* = 0x1|0x2|0x4). Same
+# 0x7 the cuFile wrapper uses. PAGE_ALIGNED_INPUTS (0x8) is omitted -- transfer
+# sizes are not always 4 KiB.
+_STREAM_REGISTER_FLAGS = 0x7
+
+# hipFileSuccess (hipfile.h ``hipFileOpError``).
+_HIPFILE_SUCCESS = 0
+
+
+class _HipFileError(ctypes.Structure):
+    """ctypes mirror of ``hipFileError_t`` (hipfile.h).
+
+    Two ints: ``err`` is the ``hipFileOpError_t`` status (0 == success);
+    ``hip_drv_err`` carries the underlying ``hipError_t`` when ``err`` indicates
+    a GPU-driver failure.
+    """
+
+    _fields_ = [("err", ctypes.c_int), ("hip_drv_err", ctypes.c_int)]
+
+
+class _HipFileHandleUnion(ctypes.Union):
+    """ctypes mirror of the ``hipFileDescr_t.handle`` union (fd or Win32 HANDLE)."""
+
+    _fields_ = [("fd", ctypes.c_int), ("hFile", ctypes.c_void_p)]
+
+
+class _HipFileDescr(ctypes.Structure):
+    """ctypes mirror of ``hipFileDescr_t`` (hipfile.h)."""
+
+    _fields_ = [
+        ("type", ctypes.c_int),
+        ("handle", _HipFileHandleUnion),
+        ("fs_ops", ctypes.c_void_p),
+    ]
+
+
+# Guards the one-time dlopen + driver open/close below. Only the init/teardown
+# transitions are serialized; the per-DMA fast path (``_lib()`` once loaded)
+# never touches the lock.
+_init_lock = threading.Lock()
+_lib_handle: Optional[ctypes.CDLL] = None
+
+
+def _declare_signatures(lib: ctypes.CDLL) -> None:
+    """Set argtypes/restype on the libhipfile symbols. Idempotent."""
+    if getattr(lib.hipFileReadAsync, "argtypes", None):
+        return
+
+    lib.hipFileDriverOpen.argtypes = []
+    lib.hipFileDriverOpen.restype = _HipFileError
+
+    lib.hipFileDriverClose.argtypes = []
+    lib.hipFileDriverClose.restype = _HipFileError
+
+    lib.hipFileHandleRegister.argtypes = [
+        ctypes.POINTER(ctypes.c_void_p),  # hipFileHandle_t *fh
+        ctypes.POINTER(_HipFileDescr),  # hipFileDescr_t *descr
+    ]
+    lib.hipFileHandleRegister.restype = _HipFileError
+
+    lib.hipFileHandleDeregister.argtypes = [ctypes.c_void_p]  # hipFileHandle_t fh
+    lib.hipFileHandleDeregister.restype = None  # void
+
+    lib.hipFileBufRegister.argtypes = [
+        ctypes.c_void_p,  # const void *buffer_base
+        ctypes.c_size_t,  # size_t length
+        ctypes.c_int,  # int flags
+    ]
+    lib.hipFileBufRegister.restype = _HipFileError
+
+    lib.hipFileBufDeregister.argtypes = [ctypes.c_void_p]  # const void *buffer_base
+    lib.hipFileBufDeregister.restype = _HipFileError
+
+    lib.hipFileReadAsync.argtypes = [
+        ctypes.c_void_p,  # hipFileHandle_t fh
+        ctypes.c_void_p,  # void *buffer_base
+        ctypes.POINTER(ctypes.c_size_t),  # size_t *size_p
+        ctypes.POINTER(ctypes.c_int64),  # hoff_t *file_offset_p
+        ctypes.POINTER(ctypes.c_int64),  # hoff_t *buffer_offset_p
+        ctypes.POINTER(ctypes.c_int64),  # ssize_t *bytes_read_p
+        ctypes.c_void_p,  # hipStream_t stream
+    ]
+    lib.hipFileReadAsync.restype = _HipFileError
+
+    lib.hipFileWriteAsync.argtypes = [
+        ctypes.c_void_p,
+        ctypes.c_void_p,
+        ctypes.POINTER(ctypes.c_size_t),
+        ctypes.POINTER(ctypes.c_int64),
+        ctypes.POINTER(ctypes.c_int64),
+        ctypes.POINTER(ctypes.c_int64),
+        ctypes.c_void_p,
+    ]
+    lib.hipFileWriteAsync.restype = _HipFileError
+
+    lib.hipFileStreamRegister.argtypes = [ctypes.c_void_p, ctypes.c_uint]
+    lib.hipFileStreamRegister.restype = _HipFileError
+
+    lib.hipFileStreamDeregister.argtypes = [ctypes.c_void_p]
+    lib.hipFileStreamDeregister.restype = _HipFileError
+
+    lib.hipFileGetOpErrorString.argtypes = [ctypes.c_int]
+    lib.hipFileGetOpErrorString.restype = ctypes.c_char_p
+
+
+_driver_opened = False
+
+
+def _lib() -> ctypes.CDLL:
+    """dlopen ``libhipfile.so`` once and declare signatures. Idempotent.
+
+    Thread-safe via double-checked locking: the common case (already loaded)
+    returns without taking ``_init_lock``, so the per-DMA path stays lock-free.
+
+    Returns:
+        The process-global ``libhipfile.so`` handle.
+    """
+    global _lib_handle
+    if _lib_handle is not None:
+        return _lib_handle
+    with _init_lock:
+        if _lib_handle is None:
+            handle = ctypes.CDLL(_LIBHIPFILE_SONAME)
+            _declare_signatures(handle)
+            _lib_handle = handle
+    return _lib_handle
+
+
+def _ensure_driver_open() -> None:
+    """Idempotently open the hipFile driver (thread-safe).
+
+    Raises:
+        RuntimeError: If ``hipFileDriverOpen`` reports a non-success status.
+    """
+    global _driver_opened
+    if _driver_opened:
+        return
+    # ``_lib()`` does its own locking; call it before taking ``_init_lock`` so
+    # the (non-reentrant) lock is never acquired twice on the same thread.
+    lib = _lib()
+    with _init_lock:
+        if _driver_opened:
+            return
+        _check(lib.hipFileDriverOpen(), "hipFileDriverOpen")
+        _driver_opened = True
+
+
+def close_driver() -> None:
+    """Close the hipFile driver (thread-safe). Optional — useful in tests.
+
+    Raises:
+        RuntimeError: If ``hipFileDriverClose`` reports a non-success status.
+    """
+    global _driver_opened
+    if not _driver_opened:
+        return
+    lib = _lib()
+    with _init_lock:
+        if not _driver_opened:
+            return
+        try:
+            _check(lib.hipFileDriverClose(), "hipFileDriverClose")
+        finally:
+            _driver_opened = False
+
+
+def _op_error_string(err_code: int) -> str:
+    """Return the human-readable name for a ``hipFileOpError_t`` value."""
+    raw = _lib().hipFileGetOpErrorString(ctypes.c_int(abs(err_code)))
+    return raw.decode() if raw is not None else "unknown"
+
+
+def _check(err: "_HipFileError", op: str) -> None:
+    """Convert a non-zero ``hipFileError_t`` into a Python exception."""
+    if err.err != _HIPFILE_SUCCESS:
+        raise RuntimeError(
+            f"{op} failed: hipFileError(err={err.err} [{_op_error_string(err.err)}], "
+            f"hip_drv_err={err.hip_drv_err})"
+        )
+
+
+# --- Handle registration -------------------------------------------
+
+
+def register_handle(fd: int) -> int:
+    """Register an open fd with hipFile and return the ``hipFileHandle_t``.
+
+    Opens the hipFile driver on first use. The returned handle is the raw
+    ``void *`` value (as an int), accepted directly as the first argument of
+    ``hipFileReadAsync`` / ``hipFileWriteAsync``.
+
+    Args:
+        fd: An open file descriptor for the slab (opened with ``O_DIRECT`` for
+            the GDS fast path).
+
+    Returns:
+        The registered ``hipFileHandle_t`` as an integer.
+
+    Raises:
+        RuntimeError: If ``hipFileHandleRegister`` reports a non-success status.
+    """
+    _ensure_driver_open()
+    lib = _lib()
+    handle = ctypes.c_void_p()
+    descr = _HipFileDescr()
+    descr.type = _HIPFILE_HANDLE_TYPE_OPAQUE_FD
+    descr.handle.fd = fd
+    descr.fs_ops = None
+    _check(
+        lib.hipFileHandleRegister(ctypes.byref(handle), ctypes.byref(descr)),
+        "hipFileHandleRegister",
+    )
+    return handle.value if handle.value is not None else 0
+
+
+def deregister_handle(handle: int) -> None:
+    """Reverse of :func:`register_handle` (``hipFileHandleDeregister``).
+
+    Args:
+        handle: The ``hipFileHandle_t`` (as an int) from :func:`register_handle`.
+    """
+    _lib().hipFileHandleDeregister(ctypes.c_void_p(handle))
+
+
+# --- Buffer / stream registration ----------------------------------
+
+
+def register_buffer(buf: torch.Tensor) -> None:
+    """Register a device tensor with hipFile for GPUDirect Storage DMA.
+
+    Must be called before any ``read_async`` / ``write_async`` whose
+    ``buf_base`` falls inside this tensor's allocation. Implicitly opens the
+    hipFile driver on first use.
+
+    Args:
+        buf: A GPU (HIP device) tensor to register for DMA.
+
+    Raises:
+        ValueError: If ``buf`` is not on the GPU.
+        RuntimeError: If ``hipFileBufRegister`` reports a non-success status.
+    """
+    if not buf.is_cuda:
+        raise ValueError("register_buffer: tensor must be on the GPU")
+    _ensure_driver_open()
+    lib = _lib()
+    nbytes = buf.numel() * buf.element_size()
+    _check(
+        lib.hipFileBufRegister(
+            ctypes.c_void_p(buf.data_ptr()),
+            ctypes.c_size_t(nbytes),
+            ctypes.c_int(0),
+        ),
+        "hipFileBufRegister",
+    )
+
+
+def deregister_buffer(buf: torch.Tensor) -> None:
+    """Reverse of :func:`register_buffer`.
+
+    Args:
+        buf: A tensor previously passed to :func:`register_buffer`.
+
+    Raises:
+        RuntimeError: If ``hipFileBufDeregister`` reports a non-success status.
+    """
+    _check(
+        _lib().hipFileBufDeregister(ctypes.c_void_p(buf.data_ptr())),
+        "hipFileBufDeregister",
+    )
+
+
+def register_stream(raw_stream: int) -> None:
+    """Register a HIP stream with hipFile.
+
+    ``raw_stream`` is the integer ``hipStream_t`` handle — get it via
+    ``torch_dev.current_stream().cuda_stream`` (torch reports the HIP stream
+    through the same attribute on ROCm).
+
+    Optional for correctness (``read_async`` / ``write_async`` also take the
+    stream per call). Registered with the FIXED_* flags (0x7): hipFile still
+    reads the size/offset pointers at stream-execution time -- so their storage
+    must stay alive and unchanged until completion (see ``Submission``) -- but
+    promising the values are fixed at submission lets hipFile skip per-op setup.
+
+    Args:
+        raw_stream: The integer ``hipStream_t`` handle to register.
+
+    Raises:
+        RuntimeError: If ``hipFileStreamRegister`` reports a non-success status.
+    """
+    _ensure_driver_open()
+    _check(
+        _lib().hipFileStreamRegister(
+            ctypes.c_void_p(raw_stream), _STREAM_REGISTER_FLAGS
+        ),
+        "hipFileStreamRegister",
+    )
+
+
+def deregister_stream(raw_stream: int) -> None:
+    """Reverse of :func:`register_stream`.
+
+    Args:
+        raw_stream: The ``hipStream_t`` handle passed to :func:`register_stream`.
+
+    Raises:
+        RuntimeError: If ``hipFileStreamDeregister`` reports a non-success status.
+    """
+    _check(
+        _lib().hipFileStreamDeregister(ctypes.c_void_p(raw_stream)),
+        "hipFileStreamDeregister",
+    )
+
+
+# --- AsyncHandle + Submission --------------------------------------
+
+
+class Submission:
+    """One in-flight ``hipFileReadAsync`` / ``hipFileWriteAsync``.
+
+    Holds the host-side ``size_p`` / ``file_offset_p`` / ``buf_offset_p`` /
+    ``bytes_done_p`` storage that hipFile writes into asynchronously. These
+    ctypes objects MUST stay alive until the stream actually executes the op —
+    keep the :class:`Submission` reference (or stash it in a list) until after
+    the stream sync.
+    """
+
+    __slots__ = ("_size", "_file_offset", "_buf_offset", "_bytes_done")
+
+    def __init__(
+        self,
+        size: int,
+        file_offset: int,
+        buf_offset: int,
+    ) -> None:
+        self._size = ctypes.c_size_t(size)
+        self._file_offset = ctypes.c_int64(file_offset)
+        self._buf_offset = ctypes.c_int64(buf_offset)
+        self._bytes_done = ctypes.c_int64(0)
+
+    @property
+    def bytes_done(self) -> int:
+        """Bytes actually transferred. Valid only AFTER the stream sync."""
+        return self._bytes_done.value
+
+
+class AsyncHandle:
+    """Open file + hipFile handle wrapper.
+
+    Opens with ``O_DIRECT`` (required for hipFile's GPUDirect Storage fast
+    path). Optionally pre-allocates the file via ``posix_fallocate``.
+    """
+
+    __slots__ = ("_fd", "_handle", "path", "writable")
+
+    def __init__(
+        self,
+        path: str,
+        writable: bool = False,
+        fallocate_size: Optional[int] = None,
+        mode: int = 0o644,
+    ) -> None:
+        flags = os.O_DIRECT
+        if writable:
+            flags |= os.O_CREAT | os.O_RDWR
+        else:
+            flags |= os.O_RDONLY
+        self.path = path
+        self.writable = writable
+        self._fd = os.open(path, flags, mode)
+        try:
+            if fallocate_size is not None and writable:
+                os.posix_fallocate(self._fd, 0, fallocate_size)
+            self._handle = register_handle(self._fd)
+        except Exception:
+            os.close(self._fd)
+            raise
+
+    @classmethod
+    def from_fd(
+        cls,
+        fd: int,
+        handle: Any,
+        path: str,
+        writable: bool = False,
+    ) -> "AsyncHandle":
+        """Wrap an already-opened fd and registered hipFile handle.
+
+        For callers that open + register the file themselves (e.g. a slab that
+        must be created, truncated, and ``posix_fallocate``d before
+        ``hipFileHandleRegister``) and just need an ``AsyncHandle`` around the
+        result.
+        """
+        obj = cls.__new__(cls)
+        obj._fd = fd
+        obj._handle = handle
+        obj.path = path
+        obj.writable = writable
+        return obj
+
+    @property
+    def fd(self) -> int:
+        return self._fd
+
+    def read_async(
+        self,
+        buf_base: int,
+        size: int,
+        file_offset: int,
+        buf_offset: int,
+        raw_stream: int,
+    ) -> Submission:
+        """Enqueue a ``hipFileReadAsync`` on the stream.
+
+        ``buf_base`` is the registered base pointer (e.g. ``buf.data_ptr()``).
+        ``buf_offset`` is the byte offset within that registration that the data
+        should land at.
+        """
+        sub = Submission(size=size, file_offset=file_offset, buf_offset=buf_offset)
+        _check(
+            _lib().hipFileReadAsync(
+                ctypes.c_void_p(self._handle),
+                ctypes.c_void_p(buf_base),
+                ctypes.byref(sub._size),
+                ctypes.byref(sub._file_offset),
+                ctypes.byref(sub._buf_offset),
+                ctypes.byref(sub._bytes_done),
+                ctypes.c_void_p(raw_stream),
+            ),
+            "hipFileReadAsync",
+        )
+        return sub
+
+    def write_async(
+        self,
+        buf_base: int,
+        size: int,
+        file_offset: int,
+        buf_offset: int,
+        raw_stream: int,
+    ) -> Submission:
+        """Enqueue a ``hipFileWriteAsync`` on the stream."""
+        sub = Submission(size=size, file_offset=file_offset, buf_offset=buf_offset)
+        _check(
+            _lib().hipFileWriteAsync(
+                ctypes.c_void_p(self._handle),
+                ctypes.c_void_p(buf_base),
+                ctypes.byref(sub._size),
+                ctypes.byref(sub._file_offset),
+                ctypes.byref(sub._buf_offset),
+                ctypes.byref(sub._bytes_done),
+                ctypes.c_void_p(raw_stream),
+            ),
+            "hipFileWriteAsync",
+        )
+        return sub
+
+    def close(self) -> None:
+        """Deregister the hipFile handle and close the fd."""
+        if self._fd < 0:
+            return
+        try:
+            deregister_handle(self._handle)
+        finally:
+            try:
+                os.close(self._fd)
+            finally:
+                self._fd = -1
+
+    def __enter__(self) -> "AsyncHandle":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[Any],
+    ) -> None:
+        self.close()
diff --git a/lmcache/v1/gpu_connector/gds_context.py b/lmcache/v1/gpu_connector/gds_context.py
new file mode 100644
index 0000000..4ce183a
--- /dev/null
+++ b/lmcache/v1/gpu_connector/gds_context.py
@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Process-global GPUDirect Storage data path for the GDS L1 tier.
+
+The actual GPU<->slab DMA goes through the platform GDS library -- cuFile on
+NVIDIA, hipFile on AMD ROCm -- reached via the :mod:`_gds_async` dispatch shim
+(imported here as ``ca``), so this module is platform-agnostic.
+
+One :class:`GDSContext` per worker process owns the slab file, its GDS handle,
+the registered GPU staging buffers, and the stream-ordered GDS submissions.
+Created once at startup by :func:`initialize_gds_context`, reached via
+:func:`get_gds_context`. :meth:`GDSContext.register_gpu_buffer` registers a
+staging buffer; :meth:`GDSContext.transfer_async` moves a chunk between that
+buffer and the slab. No POSIX fallback -- if the GDS library is unavailable,
+construction fails loudly. The slab is cleared on init, so it does not survive
+a restart (GDS L1 is treated like DRAM).
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Optional
+import bisect
+import enum
+import functools
+import os
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.config import GdsL1Config
+from lmcache.v1.gpu_connector import _gds_async as ca
+from lmcache.v1.memory_management import GDSMemoryObject
+
+logger = init_logger(__name__)
+
+_SLAB_FILENAME = "lmcache_gds_slab.bin"
+_CUFILE_ALIGNMENT = 4096
+# A single GDS buffer registration / DMA is capped at 16 MiB (both cuFile and
+# hipFile); larger buffers and chunks are registered and transferred in
+# <=16 MiB regions.
+_MAX_CUFILE_REGION = 16 * 1024 * 1024
+# GDS submissions to accumulate before recording a completion event and
+# draining finished ones (keeps the live submission set bounded).
+_SUBMISSION_CHECKPOINT_EVERY = 64
+
+
+class SlabDirection(enum.Enum):
+    """Direction of a GDS slab transfer. GPUDirect DMAs run straight between GPU
+    memory and the slab *file* (no host buffer), so directions are file I/O
+    (READ/WRITE), not host<->device (H2D/D2H)."""
+
+    READ = enum.auto()  # slab file -> GPU buffer
+    WRITE = enum.auto()  # GPU buffer -> slab file
+
+
+@dataclass
+class _StreamSubmissions:
+    """Per-stream GDS submissions, kept alive until their DMA has run.
+
+    Submissions accumulate in ``uncommitted``, move to ``inflight`` behind a
+    CUDA event on the stream, and drop once it completes. Per-stream because an
+    event only orders work on its own stream.
+    """
+
+    uncommitted: list[ca.Submission] = field(default_factory=list)
+    inflight: list[tuple[torch.Event, list[ca.Submission]]] = field(
+        default_factory=list
+    )
+    ops_since_checkpoint: int = 0
+
+
+class GDSContext:
+    """Per-process GDS context owning the slab file and its DMA path.
+
+    The singleton always exists but is inert until :meth:`initialize` creates
+    the slab and registers the GDS handle (flipping :attr:`initialized`).
+    While off, ``register_gpu_buffer`` is a no-op.
+    """
+
+    #: Whether :meth:`initialize` has completed (GDS L1 is active).
+    initialized: bool = False
+
+    def __init__(self) -> None:
+        # ``initialized`` defaults to False via the class attribute; it is
+        # flipped to True by ``initialize``.
+        self._slab_size = 0
+        self._slab_path = ""
+        self._slab_handle: Optional[ca.AsyncHandle] = None
+        # Per-stream in-flight submissions (keyed by raw ``CUstream``), released
+        # once a CUDA event recorded on that stream completes. Guarded by
+        # ``_submissions_lock`` (see ``_record_submission``).
+        self._submissions_lock = threading.Lock()
+        self._submissions: dict[int, _StreamSubmissions] = {}
+        # Registry of GDS-registered GPU regions and the streams they run on
+        self._registry_lock = threading.Lock()
+        self._buffers: list[torch.Tensor] = []
+        self._base_ptrs: list[int] = []
+        self._nbytes: list[int] = []
+        self._registered_streams: set[int] = set()  # maintained for close()
+
+    def initialize(self, config: GdsL1Config) -> None:
+        """Create + clear the slab and register it with the GDS library.
+
+        Args:
+            config: GDS tier config. ``size_in_bytes`` sizes the preallocated
+                slab (rounded up to 4 KiB) at
+                ``<file_location>/lmcache_gds_slab.bin`` (one per process);
+                ``use_direct_io`` opens it with ``O_DIRECT``.
+
+        Raises:
+            Exception: Whatever the GDS library (cuFile/hipFile) raises if GDS
+                is unavailable.
+        """
+        self._slab_size = (config.size_in_bytes + _CUFILE_ALIGNMENT - 1) & ~(
+            _CUFILE_ALIGNMENT - 1
+        )
+
+        # One shared slab per process (the GDSContext is a process-global
+        # singleton used by every GPU instance).
+        selected = config.file_location
+        os.makedirs(selected, exist_ok=True)
+        self._slab_path = os.path.join(selected, _SLAB_FILENAME)
+
+        self._open_and_register_slab(config.use_direct_io)
+        self.initialized = True
+
+    # --- Public API ---------------------------------------------------
+
+    def register_gpu_buffer(self, buffer: torch.Tensor) -> None:
+        """Register a staging buffer (and its stream) with the GDS library.
+
+        Registered as contiguous <=16 MiB regions (the GDS buffer-registration
+        cap); :meth:`transfer_async` splits transfers at these boundaries.
+
+        Args:
+            buffer: Contiguous CUDA staging buffer, 4 KiB-aligned in size.
+        """
+        if not self.initialized:
+            return
+        raw_stream = torch_dev.current_stream().cuda_stream
+        buf = buffer.view(torch.uint8)
+        nbytes = buf.numel()
+        with self._registry_lock:
+            if raw_stream not in self._registered_streams:
+                ca.register_stream(raw_stream)
+                self._registered_streams.add(raw_stream)
+            for start in range(0, nbytes, _MAX_CUFILE_REGION):
+                self._register_region_locked(
+                    buf[start : min(start + _MAX_CUFILE_REGION, nbytes)]
+                )
+
+    def deregister_gpu_buffer(self, buffer: torch.Tensor) -> None:
+        """Reverse of :meth:`register_gpu_buffer`: deregister its regions + stream.
+
+        Args:
+            buffer: The buffer passed to :meth:`register_gpu_buffer`.
+        """
+        if not self.initialized:
+            return
+        stream = torch_dev.current_stream()
+        raw_stream = stream.cuda_stream
+        # No in-flight DMA on this stream may still reference the buffer.
+        stream.synchronize()
+        buf = buffer.view(torch.uint8)
+        nbytes = buf.numel()
+        with self._registry_lock:
+            for start in range(0, nbytes, _MAX_CUFILE_REGION):
+                self._deregister_region_locked(
+                    buf[start : min(start + _MAX_CUFILE_REGION, nbytes)]
+                )
+            if raw_stream in self._registered_streams:
+                try:
+                    ca.deregister_stream(raw_stream)
+                except Exception as e:
+                    logger.warning(
+                        "GDSContext.deregister_gpu_buffer: deregister_stream: %s", e
+                    )
+                self._registered_streams.discard(raw_stream)
+        # Stream is synced above, so its submissions' DMAs are done -- drop them.
+        with self._submissions_lock:
+            self._submissions.pop(raw_stream, None)
+
+    def transfer_async(
+        self,
+        memory_obj: GDSMemoryObject,
+        gpu_buffer: torch.Tensor,
+        direction: SlabDirection,
+    ) -> None:
+        """DMA a chunk between ``gpu_buffer`` and its slab region.
+
+        ``READ`` pulls slab -> ``gpu_buffer``; ``WRITE`` pushes the reverse.
+        Split at registered-region boundaries (each GDS DMA must stay within
+        one <=16 MiB region), so any chunk size works. Stream-ordered, no sync.
+
+        Args:
+            memory_obj: The chunk; ``slab_offset`` / ``get_size()`` give the
+                file offset and length.
+            gpu_buffer: A slice of a registered staging buffer; its first
+                ``get_size()`` bytes are transferred.
+            direction: :attr:`SlabDirection.READ` or ``.WRITE``.
+        """
+        slab_op = (
+            self._slab_read if direction is SlabDirection.READ else self._slab_write
+        )
+        nbytes = memory_obj.get_size()
+        buf = gpu_buffer.view(torch.uint8)
+        pos = 0
+        while pos < nbytes:
+            base_ptr, dev_offset, region_nbytes = self._resolve_buffer(buf[pos:])
+            seg_len = min(nbytes - pos, region_nbytes - dev_offset)
+            slab_op(memory_obj.slab_offset + pos, seg_len, dev_offset, base_ptr)
+            pos += seg_len
+
+    def close(self) -> None:
+        """Sync the stream, deregister GDS state, and close the slab handle."""
+        if self._buffers:
+            torch_dev.synchronize(device=self._buffers[0].device)
+        with self._submissions_lock:
+            self._submissions.clear()
+        # Deregister any regions/streams still live (per-instance teardown via
+        # ``deregister_gpu_buffer`` normally clears these first; this is the
+        # shutdown sweep for anything left).
+        with self._registry_lock:
+            for buf in self._buffers:
+                try:
+                    ca.deregister_buffer(buf)
+                except Exception as e:
+                    logger.warning("GDSContext.close: deregister_buffer: %s", e)
+            self._buffers.clear()
+            self._base_ptrs.clear()
+            self._nbytes.clear()
+            for raw_stream in list(self._registered_streams):
+                try:
+                    ca.deregister_stream(raw_stream)
+                except Exception as e:
+                    logger.warning("GDSContext.close: deregister_stream: %s", e)
+            self._registered_streams.clear()
+        if self._slab_handle is not None:
+            try:
+                self._slab_handle.close()
+            except Exception as e:
+                logger.warning("GDSContext.close: slab handle close failed: %s", e)
+            self._slab_handle = None
+
+    # --- Internal -----------------------------------------------------
+
+    def _open_and_register_slab(self, use_direct_io: bool) -> None:
+        """Create, truncate, preallocate the slab file and register it with GDS.
+
+        Args:
+            use_direct_io: Open with ``O_DIRECT`` (required for the GDS fast path).
+        """
+        # Create, truncate, and fallocate via a regular (non-O_DIRECT) fd.
+        creator_fd = os.open(
+            self._slab_path, os.O_CREAT | os.O_RDWR | os.O_TRUNC, 0o644
+        )
+        try:
+            os.posix_fallocate(creator_fd, 0, self._slab_size)
+        finally:
+            os.close(creator_fd)
+        flags = os.O_RDWR
+        if use_direct_io:
+            flags |= os.O_DIRECT
+        fd = os.open(self._slab_path, flags)
+        try:
+            handle = ca.register_handle(fd)
+        except Exception:
+            os.close(fd)
+            raise
+        self._slab_handle = ca.AsyncHandle.from_fd(
+            fd, handle, self._slab_path, writable=True
+        )
+        logger.info(
+            "GDSContext: slab created at %s (%.1f GiB, O_DIRECT=%s), GDS "
+            "handle registered",
+            self._slab_path,
+            self._slab_size / (1 << 30),
+            use_direct_io,
+        )
+
+    def _register_region_locked(self, buffer: torch.Tensor) -> None:
+        """GDS-register one <=16 MiB region (caller holds the lock)."""
+        nbytes = buffer.numel() * buffer.element_size()
+        base = buffer.data_ptr()
+        ca.register_buffer(buffer)
+        idx = bisect.bisect_left(self._base_ptrs, base)
+        self._buffers.insert(idx, buffer)
+        self._base_ptrs.insert(idx, base)
+        self._nbytes.insert(idx, nbytes)
+        logger.info(
+            "GDSContext: registered %d bytes at 0x%x via GDS (total registrations: %d)",
+            nbytes,
+            base,
+            len(self._buffers),
+        )
+
+    def _deregister_region_locked(self, buffer: torch.Tensor) -> None:
+        """Deregister one region with the GDS library (caller holds the lock).
+
+        Args:
+            buffer: A staging-buffer slot previously registered.
+        """
+        base = buffer.data_ptr()
+        idx = bisect.bisect_left(self._base_ptrs, base)
+        try:
+            ca.deregister_buffer(self._buffers[idx])
+        except Exception as e:
+            logger.warning("GDSContext: deregister_buffer: %s", e)
+        del self._buffers[idx]
+        del self._base_ptrs[idx]
+        del self._nbytes[idx]
+
+    def _resolve_buffer(self, gpu_buffer: torch.Tensor) -> tuple[int, int, int]:
+        """Locate the registered region ``gpu_buffer`` starts in.
+
+        Returns ``(base_ptr, dev_offset, region_nbytes)``; ``region_nbytes -
+        dev_offset`` is the room left in the region, which :meth:`transfer_async`
+        uses to cut DMAs at region boundaries. Callers always pass a pointer
+        inside a registered region.
+        """
+        ptr = gpu_buffer.data_ptr()
+        # Held briefly so a concurrent deregister can't mutate the parallel
+        # lists mid-lookup.
+        with self._registry_lock:
+            idx = bisect.bisect_right(self._base_ptrs, ptr) - 1
+            base = self._base_ptrs[idx]
+            nbytes = self._nbytes[idx]
+        offset = ptr - base
+        return base, offset, nbytes
+
+    def _slab_read(
+        self, slab_offset: int, size: int, dev_offset: int, buf_base: int
+    ) -> None:
+        """Submit one async GDS read against the slab handle (stream-ordered)."""
+        if self._slab_handle is None:
+            raise RuntimeError("GDSContext._slab_read: slab handle not open")
+        stream_handle = torch_dev.current_stream().cuda_stream
+        sub = self._slab_handle.read_async(
+            buf_base, size, slab_offset, dev_offset, stream_handle
+        )
+        self._record_submission(sub)
+
+    def _slab_write(
+        self, slab_offset: int, size: int, dev_offset: int, buf_base: int
+    ) -> None:
+        """Submit one async GDS write against the slab handle (stream-ordered)."""
+        if self._slab_handle is None:
+            raise RuntimeError("GDSContext._slab_write: slab handle not open")
+        stream_handle = torch_dev.current_stream().cuda_stream
+        sub = self._slab_handle.write_async(
+            buf_base, size, slab_offset, dev_offset, stream_handle
+        )
+        self._record_submission(sub)
+
+    def _record_submission(self, sub: "ca.Submission") -> None:
+        """Track an in-flight submission so its ctypes storage outlives the DMA.
+
+        Accumulated per (current) stream; every ``_SUBMISSION_CHECKPOINT_EVERY``
+        ops a CUDA event is recorded and completed batches are released.
+        """
+        stream = torch_dev.current_stream()
+        raw_stream = stream.cuda_stream
+        with self._submissions_lock:
+            st = self._submissions.get(raw_stream)
+            if st is None:
+                st = self._submissions[raw_stream] = _StreamSubmissions()
+            st.uncommitted.append(sub)
+            st.ops_since_checkpoint += 1
+            if st.ops_since_checkpoint >= _SUBMISSION_CHECKPOINT_EVERY:
+                self._checkpoint_submissions_locked(st, stream)
+
+    def _checkpoint_submissions_locked(
+        self, st: _StreamSubmissions, stream: "torch.Stream"
+    ) -> None:
+        """Close ``st``'s current batch behind a CUDA event on ``stream`` and
+        drop earlier batches whose event has completed. Hold
+        ``self._submissions_lock``.
+        """
+        if st.uncommitted:
+            event = torch_dev.Event()
+            event.record(stream)
+            st.inflight.append((event, st.uncommitted))
+            st.uncommitted = []
+        st.ops_since_checkpoint = 0
+        st.inflight = [
+            (event, subs) for (event, subs) in st.inflight if not event.query()
+        ]
+
+
+@functools.cache
+def get_gds_context() -> GDSContext:
+    """Return the process-global :class:`GDSContext` singleton (created empty on
+    first access). Consult :attr:`GDSContext.initialized` to tell whether GDS L1
+    is active."""
+    return GDSContext()
+
+
+def initialize_gds_context(config: Optional[GdsL1Config]) -> GDSContext:
+    """Set up the process-global :class:`GDSContext` (once, at startup).
+
+    ``config=None`` leaves it uninitialized (GDS L1 disabled); otherwise the
+    slab is created and registered. Returns the singleton.
+    """
+    context = get_gds_context()
+    if config is not None:
+        context.initialize(config)
+    return context
diff --git a/lmcache/v1/gpu_connector/gpu_connectors.py b/lmcache/v1/gpu_connector/gpu_connectors.py
new file mode 100644
index 0000000..0e3cbec
--- /dev/null
+++ b/lmcache/v1/gpu_connector/gpu_connectors.py
@@ -0,0 +1,2222 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional, Tuple, Union
+import abc
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.python_ops_fallback import set_shape_desc_dtype
+from lmcache.utils import EngineType, _lmcache_nvtx_annotate
+from lmcache.v1.compute.blend.utils import LMCBlenderBuilder
+from lmcache.v1.gpu_connector.kv_format.contiguity import (
+    attempt_permute_to_contiguous_view,
+)
+from lmcache.v1.gpu_connector.utils import (
+    DiscoverableKVCache,
+    LayoutHints,
+    assert_is_vllm_flash_attn_or_flash_infer,
+    assert_is_vllm_mla_or_flash_attn_or_flash_infer,
+    get_block_size,
+    get_device,
+    get_elements_per_layer,
+    get_group_data_ptrs,
+    get_head_size,
+    get_num_blocks,
+    get_num_layers,
+    get_page_buffer_size,
+    get_tokens_per_layer,
+    normalize_and_discover_per_layer_formats,
+    normalize_kv_and_discover_format,
+)
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+class GPUConnectorInterface(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        # FIXME (Yihua): We shouldn't put start and end here since
+        # it's not the responsibility of the GPUConnector to know
+        # the token-sequence-related information.
+        """Store the data in the memory object into a GPU buffer.
+        Sub-classes should define the format of the kwargs.
+
+        :param MemoryObj memory_obj: The memory object to be copied into GPU.
+        :param int start: The starting index of the data in the corresponding
+            token sequence.
+        :param int end: The ending index of the data in the corresponding
+            token sequence.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        # FIXME (Yihua): We shouldn't put start and end here since
+        # it's not the responsibility of the GPUConnector to know
+        # the token-sequence-related information.
+        """Load the data from a GPU buffer into the memory object.
+        Sub-classes should define the format of the kwargs.
+
+        :param MemoryObj memory_obj: The memory object to store the data from
+            GPU.
+        :param int start: The starting index of the data in the corresponding
+            token sequence.
+        :param int end: The ending index of the data in the corresponding
+            token sequence.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]], List[MemoryObj]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        Batched load the data from a GPU memory into the memory objects.
+        Sub-classes should define the format of the kwargs.
+
+        :param Union[List[List[MemoryObj]], List[MemoryObj]] memory_obj:
+            The memory objects to store the data from GPU.
+        :param List[int] starts: The starting indices of the data in the corresponding
+            token sequence.
+        :param List[int] ends: The ending indices of the data in the corresponding
+            token sequence.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_to_gpu(
+        self,
+        memory_objs: Union[
+            List[List[MemoryObj]], List[MemoryObj], List[int], None
+        ] = None,
+        starts: Optional[List[int]] = None,
+        ends: Optional[List[int]] = None,
+        **kwargs,
+    ):
+        """
+        Batched store the data from the memory objects to GPU kv cache.
+        Sub-classes should define the format of the kwargs.
+
+        For non-layerwise connectors:
+        :param Union[List[List[MemoryObj]], List[MemoryObj]] memory_obj:
+            The memory objects to store the data to GPU.
+        :param List[int] starts: The starting indices of the data in the corresponding
+            token sequence.
+        :param List[int] ends: The ending indices of the data in the corresponding
+            token sequence.
+
+        For layerwise connectors (generator pattern):
+        :param List[int] memory_objs: Actually the starts list
+        (positional compatibility)
+        :param List[int] starts: Actually the ends list
+        (positional compatibility)
+        Note: Layerwise connectors receive memory objects
+        via generator.send()
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        """Get the shape of the data given the number of tokens."""
+        raise NotImplementedError
+
+    def initialize_kvcaches_ptr(self, **kwargs):
+        """Initialize the kvcaches pointers if not already initialized."""
+        if "kvcaches" in kwargs:
+            self.kvcaches = kwargs["kvcaches"]
+            # Ensure contiguity on every call.  HND tensors from vLLM have a
+            # non-contiguous logical view (NHD) that must be permuted back to
+            # the physical (HND) shape for correct kernel indexing.
+            # attempt_permute_to_contiguous_view is a no-op when already contiguous.
+            self.kvcaches = attempt_permute_to_contiguous_view(self.kvcaches)
+
+
+class VLLMPagedMemGPUConnectorV2(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a nested tuple of K and V tensors.
+    More specifically, we have:
+    - GPUTensor = Tuple[KVLayer, ...]
+    - KVLayer = Tuple[Tensor, Tensor]
+    - Tensor: [num_blocks, block_size, num_heads, head_size]
+
+    It will produce / consume memory object with KV_2LTD format
+    """
+
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_gpu: bool = False,
+        **kwargs,
+    ):
+        """
+        If use_gpu is true, it will create a gpu intermediate buffer. In this
+        case, it requires the following kwargs:
+        - chunk_size: The MAX size of the chunk to be copied to GPU.
+        - dtype: The data type of the intermediate buffer.
+        """
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+        self.kv_cache_pointers = torch.empty(
+            num_layers, dtype=torch.int64, device="cpu"
+        )
+        # Not sure we need a dict here. Maybe a single GPU connector always
+        # works with a single device?
+        self.kv_cache_pointers_on_gpu: dict[int, torch.Tensor] = {}
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        self.gpu_buffer: Optional[torch.Tensor] = None
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+        self.layout_hints: LayoutHints = (
+            kwargs.get(  # type: ignore[assignment]
+                "layout_hints"
+            )
+            or {}
+        )
+        if use_gpu:
+            assert "chunk_size" in kwargs, (
+                "chunk_size should be provided to create a GPU buffer."
+            )
+            assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+            assert "device" in kwargs, (
+                "device should be provided to create a GPU buffer."
+            )
+            shape = self.get_shape(kwargs["chunk_size"])
+            self.gpu_buffer = torch.empty(
+                shape, dtype=kwargs["dtype"], device=kwargs["device"]
+            )
+
+        self.store_stream = torch.cuda.Stream()
+        self.load_stream = torch.cuda.Stream()
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+        layout_hints: Optional[LayoutHints] = None,
+    ) -> "VLLMPagedMemGPUConnectorV2":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+            layout_hints: Optional hints about KV cache layout from the
+                serving engine.
+
+        Returns:
+            A new instance of VLLMPagedMemGPUConnectorV2.
+        """
+        # Extract parameters from metadata
+        # kv_shape: (num_layer, 2 or 1, chunk_size, num_kv_head, head_size)
+        num_layers = metadata.kv_shape[0]
+        chunk_size = metadata.kv_shape[2]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_gpu=use_gpu,
+            chunk_size=chunk_size,
+            dtype=metadata.kv_dtype,
+            device=device,
+            use_mla=metadata.use_mla,
+            layout_hints=layout_hints,
+        )
+
+    def _initialize_pointers(self, kv_caches: List[torch.Tensor]) -> torch.Tensor:
+        self.device = kv_caches[0].device
+        assert self.device.type == "cuda", "The device should be CUDA."
+        idx = self.device.index
+        if idx in self.kv_cache_pointers_on_gpu:
+            return self.kv_cache_pointers_on_gpu[idx]
+
+        self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+            kv_caches, EngineType.VLLM, layout_hints=self.layout_hints
+        )
+
+        self.kv_cache_pointers.numpy()[:] = [t.data_ptr() for t in kv_caches]
+        self.kv_cache_pointers_on_gpu[idx] = torch.empty(
+            self.num_layers, dtype=torch.int64, device=self.device
+        )
+        self.kv_cache_pointers_on_gpu[idx].copy_(self.kv_cache_pointers)
+        self.num_blocks = get_num_blocks(kv_caches, self.engine_kv_format)
+        self.block_size = get_block_size(kv_caches, self.engine_kv_format)
+        self.page_buffer_size = self.num_blocks * self.block_size
+        self.head_size = get_head_size(kv_caches, self.engine_kv_format)
+
+        return self.kv_cache_pointers_on_gpu[idx]
+
+    @_lmcache_nvtx_annotate
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "full slot mapping"
+             where it's length is the same as the whole token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying CUDA kernel will never see -1 in slot_mapping)
+
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs.
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if self.use_mla:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_MLA_FMT:
+                raise ValueError(
+                    "The memory object should be in KV_MLA_FMT format in"
+                    " order to be processed by VLLMPagedMemGPUConnector"
+                )
+        else:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_2LTD:
+                raise ValueError(
+                    "The memory object should be in KV_2LTD format in"
+                    " order to be processed by VLLMPagedMemGPUConnector"
+                )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(self.kvcaches)
+
+        # avoid read/write stream race condition for shared block
+        # this will only be potentially non-zero for the first
+        # block lmcache is transferring back
+        vllm_cached = kwargs.get("vllm_cached_tokens", 0)
+        skip_prefix_n_tokens = min(end - start, max(0, vllm_cached - start))
+
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj.tensor,
+            kv_cache_pointers,
+            slot_mapping[start:end],
+            self.device,
+            self.page_buffer_size,
+            lmc_ops.TransferDirection.H2D,
+            self.engine_kv_format,
+            block_size=self.block_size,
+            head_size=self.head_size,
+            skip_prefix_n_tokens=skip_prefix_n_tokens,
+        )
+
+    @_lmcache_nvtx_annotate
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Will set the memory_obj.metadata.fmt to MemoryFormat.KV_2LTD.
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "full slot mapping"
+             where it's length is the same as the whole token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying CUDA kernel will never see -1 in slot_mapping)
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs,
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(self.kvcaches)
+
+        with torch.cuda.stream(self.store_stream):
+            if self.gpu_buffer is None or end - start != self.gpu_buffer.shape[2]:
+                lmc_ops.multi_layer_kv_transfer(
+                    memory_obj.tensor,
+                    kv_cache_pointers,
+                    slot_mapping[start:end],
+                    self.kvcaches[0].device,
+                    self.page_buffer_size,
+                    lmc_ops.TransferDirection.D2H,
+                    self.engine_kv_format,
+                    block_size=self.block_size,
+                    head_size=self.head_size,
+                )
+            else:
+                # kvcaches -> gpu_buffer -> memobj
+                assert self.gpu_buffer.device == self.kvcaches[0].device
+                tmp_gpu_buffer = self.gpu_buffer[:, :, : end - start, :]
+                lmc_ops.multi_layer_kv_transfer(
+                    tmp_gpu_buffer,
+                    kv_cache_pointers,
+                    slot_mapping[start:end],
+                    self.kvcaches[0].device,
+                    self.page_buffer_size,
+                    lmc_ops.TransferDirection.D2H,
+                    self.engine_kv_format,
+                    block_size=self.block_size,
+                    head_size=self.head_size,
+                )
+                memory_obj.tensor.copy_(tmp_gpu_buffer, non_blocking=True)
+
+        if not memory_obj.tensor.is_cuda:
+            # Force a synchronize if the target buffer is NOT CUDA device
+            # NOTE: for better performance, we may not want to sync for every
+            # memory object
+            self.store_stream.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    # TODO(Jiayi): need to optimize to enable real batching
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        with torch.cuda.stream(self.load_stream):
+            for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+                self.to_gpu(memory_obj, start, end, **kwargs)
+        self.load_stream.synchronize()
+
+    # TODO(Jiayi): need to optimize to enable real batching
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        kv_size = 1 if self.use_mla else 2
+        return torch.Size([kv_size, self.num_layers, num_tokens, self.hidden_dim_size])
+
+
+class VLLMPagedMemGPUConnectorV3(GPUConnectorInterface):
+    def __init__(
+        self,
+        metadata: LMCacheMetadata,
+        device: torch.device,
+        use_gpu: bool = False,
+        layout_hints: Optional[LayoutHints] = None,
+    ):
+        assert device.type == "cuda", "The device should be CUDA."
+        self.metadata = metadata
+        self.device = device
+        self.use_mla = metadata.use_mla
+        self.chunk_size = metadata.chunk_size
+        self.use_gpu = use_gpu
+        self.layout_hints: LayoutHints = layout_hints or {}
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        self.init = False
+        self.group_kv_cache_pointers_on_gpu: Optional[list[torch.Tensor]] = None
+        self.group_tmp_buffer: Optional[list[torch.Tensor]] = None
+
+        self.store_stream = torch.cuda.Stream()
+        self.load_stream = torch.cuda.Stream()
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+        layout_hints: Optional[LayoutHints] = None,
+    ) -> "VLLMPagedMemGPUConnectorV3":
+        assert device is not None
+        return cls(metadata, device, use_gpu, layout_hints=layout_hints)
+
+    def _initialize_kv_cache_pointers(self):
+        """Discover KV-cache layout, build the layer-groups manager, and
+        capture per-group GPU pointer tensors.
+
+        All layout-adjacent work lives here: the connector already owns
+        ``layout_hints`` and the actual ``self.kvcaches`` tensors, so the
+        serving-engine adapter stays agnostic to format.
+        """
+        if self.init:
+            return
+
+        empty_layer_index_groups: list[list[int]] = []
+        self.kvcaches, engine_kv_formats = normalize_and_discover_per_layer_formats(
+            self.kvcaches, empty_layer_index_groups, EngineType.VLLM, self.layout_hints
+        )
+        self.engine_kv_format = engine_kv_formats[0]
+        self.num_blocks = get_num_blocks(self.kvcaches, self.engine_kv_format)
+        self.block_size = get_block_size(self.kvcaches, self.engine_kv_format)
+        self.page_buffer_size = self.num_blocks * self.block_size
+        self.head_size = get_head_size(self.kvcaches, self.engine_kv_format)
+
+        if self.metadata.kv_layer_groups_manager is None:
+            self.metadata.kv_layer_groups_manager = KVLayerGroupsManager(
+                self.kvcaches,
+                engine_kv_formats=engine_kv_formats,
+            )
+        klg_manager = self.metadata.kv_layer_groups_manager
+
+        # Heterogeneous-block_size sanity check.
+        #
+        # ``self.block_size`` is a single scalar sampled from the first
+        # layer's ``bs`` and is forwarded to ``multi_layer_kv_transfer``
+        # as a *global* kernel parameter below (see ``to_gpu`` /
+        # ``from_gpu`` / layerwise paths). That works only when every
+        # group shares the same ``shape_desc.bs``. Mixed-compression
+        # deployments (e.g. DeepSeek V4 with compressed + dense groups
+        # in the same model) violate this assumption and will silently
+        # corrupt transfers on this non-MP path. Log loudly so the
+        # mismatch surfaces before it turns into a data-corruption bug;
+        # the MP path (see ``GPUCacheContext`` / mp server) handles
+        # per-group ``bs`` correctly and should be used instead.
+        heterogeneous_bs = {g.shape_desc.bs for g in klg_manager.kv_layer_groups}
+        if len(heterogeneous_bs) > 1:
+            logger.warning(
+                "VLLMPagedMemGPUConnectorV3 detected heterogeneous per-group "
+                "block_size %s but forwards a single scalar block_size=%d to "
+                "multi_layer_kv_transfer. This non-MP path is NOT adapted for "
+                "mixed-compression KV layouts and may corrupt transfers. Use "
+                "the multi-process connector path for such models.",
+                sorted(heterogeneous_bs),
+                self.block_size,
+            )
+
+        if self.use_gpu:
+            tmp_buf_shapes = self.metadata.get_shapes(self.chunk_size)
+            tmp_buf_dtypes = self.metadata.get_dtypes()
+            assert len(tmp_buf_shapes) == len(tmp_buf_dtypes)
+            self.group_tmp_buffer = [
+                torch.empty(shape, dtype=dtype, device=self.device)
+                for shape, dtype in zip(tmp_buf_shapes, tmp_buf_dtypes, strict=True)
+            ]
+
+        self.group_kv_cache_pointers_on_gpu = []
+        for group in klg_manager.kv_layer_groups:
+            ptrs = get_group_data_ptrs(
+                self.kvcaches, self.engine_kv_format, group.layer_indices
+            )
+            cpu = torch.empty(len(ptrs), dtype=torch.int64, device="cpu")
+            cpu.numpy()[:] = ptrs
+            gpu = torch.empty(len(ptrs), dtype=torch.int64, device=self.device)
+            gpu.copy_(cpu)
+            self.group_kv_cache_pointers_on_gpu.append(gpu)
+
+        self.init = True
+        logger.info("init kv cache pointers success in VLLMPagedMemGPUConnectorV3")
+
+    @_lmcache_nvtx_annotate
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        assert memory_obj.raw_tensor is not None
+        assert "slot_mapping" in kwargs
+        if self.use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+        assert self.kvcaches[0].device == self.device
+        self._initialize_kv_cache_pointers()
+        assert self.group_kv_cache_pointers_on_gpu is not None
+
+        # avoid read/write stream race condition for shared block
+        # this will only be potentially non-zero for the first
+        # block lmcache is transferring back
+        vllm_cached = kwargs.get("vllm_cached_tokens", 0)
+        skip_prefix_n_tokens = min(end - start, max(0, vllm_cached - start))
+
+        for i, kv_cache_pointer in enumerate(self.group_kv_cache_pointers_on_gpu):
+            memory_obj_tensor = memory_obj.get_tensor(i)
+            assert memory_obj_tensor is not None
+            lmc_ops.multi_layer_kv_transfer(
+                memory_obj_tensor,
+                kv_cache_pointer,
+                slot_mapping[start:end],
+                self.device,
+                self.page_buffer_size,
+                lmc_ops.TransferDirection.H2D,
+                self.engine_kv_format,
+                block_size=self.block_size,
+                head_size=self.head_size,
+                skip_prefix_n_tokens=skip_prefix_n_tokens,
+            )
+
+    @_lmcache_nvtx_annotate
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        assert memory_obj.raw_tensor is not None
+        assert "slot_mapping" in kwargs
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+        assert self.kvcaches[0].device == self.device
+        self._initialize_kv_cache_pointers()
+        assert self.group_kv_cache_pointers_on_gpu is not None
+        with torch.cuda.stream(self.store_stream):
+            if not self.use_gpu or end - start != self.chunk_size:
+                for i, kv_cache_pointer in enumerate(
+                    self.group_kv_cache_pointers_on_gpu
+                ):
+                    memory_obj_tensor = memory_obj.get_tensor(i)
+                    assert memory_obj_tensor is not None
+                    lmc_ops.multi_layer_kv_transfer(
+                        memory_obj_tensor,
+                        kv_cache_pointer,
+                        slot_mapping[start:end],
+                        self.device,
+                        self.page_buffer_size,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        block_size=self.block_size,
+                        head_size=self.head_size,
+                    )
+            else:
+                # kvcaches -> gpu_buffer -> memobj
+                assert self.group_tmp_buffer is not None
+                for i, kv_cache_pointer in enumerate(
+                    self.group_kv_cache_pointers_on_gpu
+                ):
+                    tmp_gpu_buffer = self.group_tmp_buffer[i][:, :, : end - start, :]
+                    lmc_ops.multi_layer_kv_transfer(
+                        tmp_gpu_buffer,
+                        kv_cache_pointer,
+                        slot_mapping[start:end],
+                        self.device,
+                        self.page_buffer_size,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        block_size=self.block_size,
+                        head_size=self.head_size,
+                    )
+                    memory_obj_tensor = memory_obj.get_tensor(i)
+                    assert memory_obj_tensor is not None
+                    memory_obj_tensor.copy_(tmp_gpu_buffer, non_blocking=True)
+
+        if not memory_obj.raw_tensor.is_cuda:
+            # Force a synchronize if the target buffer is NOT CUDA device
+            # NOTE: for better performance, we may not want to sync for every
+            # memory object
+            self.store_stream.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        with torch.cuda.stream(self.load_stream):
+            for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+                self.to_gpu(memory_obj, start, end, **kwargs)
+        self.load_stream.synchronize()
+
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        raise NotImplementedError
+
+
+class VLLMBufferLayerwiseGPUConnector(GPUConnectorInterface):
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_gpu: bool = False,
+        use_double_buffer: bool = True,
+        **kwargs,
+    ):
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+        self.layout_hints: LayoutHints = (
+            kwargs.get(  # type: ignore[assignment]
+                "layout_hints"
+            )
+            or {}
+        )
+
+        # TODO(Jiayi): remove this hardcode
+        self.cache_positions = True
+
+        self.fused_rotary_emb = None
+
+        assert use_gpu, "use_gpu must be true in VLLMBufferLayerwiseGPUConnector"
+        assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+        assert "device" in kwargs, "device should be provided to create a GPU buffer."
+
+        self.dtype = kwargs["dtype"]
+        self.device = kwargs["device"]
+
+        self.load_stream = torch.cuda.Stream()
+        self.store_stream = torch.cuda.Stream()
+
+        self.buffer_mapping: dict[int, MemoryObj] = {}
+
+        # track gap positions between blended chunks
+        self.current_gap_positions = None
+
+        self.use_gpu = use_gpu
+        self.gpu_buffer_allocator = None
+        self.element_size = torch.tensor([], dtype=self.dtype).element_size()
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+        layout_hints: Optional[LayoutHints] = None,
+    ) -> "VLLMBufferLayerwiseGPUConnector":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+            layout_hints: Optional hints about KV cache layout from the
+                serving engine.
+
+        Returns:
+            A new instance of VLLMBufferLayerwiseGPUConnector.
+        """
+        # Extract parameters from metadata
+        # kv_shape: (num_layer, 2 or 1, chunk_size, num_kv_head, head_size)
+        num_layers = metadata.kv_shape[0]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_gpu=use_gpu,
+            dtype=metadata.kv_dtype,
+            device=device,
+            layout_hints=layout_hints,
+        )
+
+    def _lazy_initialize_buffer(self, kv_caches):
+        """
+        Lazily initialize the GPU buffer allocator if it is not initialized yet.
+        Currently, we use the `kv_caches` (kv cache pointer) to determine
+        the gpu buffer size in gpu connector.
+        Also, the first request might be a bit slower due to buffer creation.
+        """
+        if self.use_gpu and self.gpu_buffer_allocator is None:
+            logger.info("Lazily initializing GPU buffer.")
+            # NOTE (Jiayi): We use the first layer to determine the gpu buffer size.
+            # NOTE (Jiayi): Using the exact number of tokens in the first layer
+            # is okay since fragmentation shouldn't exist in the `gpu_buffer_allocator`
+            # in layerwise mode.
+
+            self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+                kv_caches, EngineType.VLLM, layout_hints=self.layout_hints
+            )
+            self.kvcaches = kv_caches
+            assert_is_vllm_flash_attn_or_flash_infer(self.engine_kv_format)
+            self.tokens_per_layer = get_tokens_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            self.elements_per_layer = get_elements_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            logger.info(
+                f"Lazily initializing GPU buffer (max tokens={self.tokens_per_layer})."
+            )
+            gpu_buffer_size = self.elements_per_layer * self.element_size
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                gpu_buffer_size, device=self.device
+            )
+
+    def get_kv(self, layer_id: int) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Get the KV cache for the given layer ID.
+        This function is used to get the KV cache from the GPU buffer.
+        """
+        if layer_id not in self.buffer_mapping:
+            raise ValueError(f"Layer {layer_id} is not loaded into GPU buffer.")
+
+        gpu_buffer = self.buffer_mapping[layer_id].tensor
+        assert gpu_buffer is not None
+        return gpu_buffer[0], gpu_buffer[1]
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    @_lmcache_nvtx_annotate
+    def batched_to_gpu(self, starts: List[int], ends: List[int], **kwargs):
+        """
+        This function is a generator that moves the KV cache from the memory
+        objects to buffer GPU memory. In each iteration i, it (1) loads the KV
+        cache of layer i from CPU -> GPU buffer, (2) recovers the positional
+        encoding of the layer i-1's KV cache in the GPU buffer, and (3)
+        moves the KV cache of layer i-2 from GPU buffer to paged GPU memory.
+        In total, this the generator will yield num_layers + 2 times.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if self.fused_rotary_emb is None and self.cache_positions:
+            # TODO(Jiayi): Make this more elegant
+            # First Party
+            from lmcache.integration.vllm.utils import ENGINE_NAME
+
+            self.lmc_model = LMCBlenderBuilder.get(ENGINE_NAME).layerwise_model
+            self.fused_rotary_emb = self.lmc_model.fused_rotary_emb
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        num_all_tokens = ends[-1] - starts[0]
+        slot_mapping_full = slot_mapping[starts[0] : ends[-1]]
+
+        # compute gap positions
+        gap_mask = torch.ones(
+            num_all_tokens, dtype=torch.bool, device=slot_mapping_full.device
+        )
+        buf_offset = starts[0]
+
+        for start, end in zip(starts, ends, strict=False):
+            gap_mask[start - buf_offset : end - buf_offset] = False
+
+        self.current_gap_positions = torch.where(gap_mask)[0]
+
+        buf_offset = starts[0]
+        if self.cache_positions:
+            new_positions_full = torch.arange(
+                starts[0], ends[-1], dtype=torch.int64, device=self.kvcaches[0].device
+            )
+
+        buffer_shape = self.get_shape(num_all_tokens)
+        assert self.gpu_buffer_allocator is not None
+        compute_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+            buffer_shape, self.dtype, MemoryFormat.KV_2TD
+        )
+        load_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+            buffer_shape, self.dtype, MemoryFormat.KV_2TD
+        )
+        assert compute_gpu_buffer_obj is not None, (
+            "Failed to allocate GPU buffer in GPUConnector"
+        )
+        assert load_gpu_buffer_obj is not None, (
+            "Failed to allocate GPU buffer in GPUConnector"
+        )
+        assert compute_gpu_buffer_obj.tensor is not None
+        assert load_gpu_buffer_obj.tensor is not None
+
+        # current_stream = torch.cuda.current_stream()
+
+        if self.cache_positions:
+            old_positions_full = torch.zeros(
+                (num_all_tokens,), dtype=torch.int64, device=self.kvcaches[0].device
+            )
+        for layer_id in range(self.num_layers + 2):
+            if layer_id > 1:
+                lmc_ops.single_layer_kv_transfer(
+                    self.buffer_mapping[layer_id - 2].tensor,
+                    self.kvcaches[layer_id - 2],
+                    slot_mapping_full,
+                    lmc_ops.TransferDirection.H2D,
+                    self.engine_kv_format,
+                    token_major=False,  # shape is [2, num_tokens, hidden_dim]
+                )
+                del self.buffer_mapping[layer_id - 2]
+
+                logger.debug(f"Finished loading layer {layer_id - 2} into paged memory")
+
+            if layer_id > 0 and layer_id <= self.num_layers:
+                # NOTE: wait until both compute and load streams are done
+                torch.cuda.synchronize()
+
+                # ping-pong the buffers
+                compute_gpu_buffer_obj, load_gpu_buffer_obj = (
+                    load_gpu_buffer_obj,
+                    compute_gpu_buffer_obj,
+                )
+
+                if self.cache_positions:
+                    assert compute_gpu_buffer_obj.tensor is not None
+
+                    compute_gpu_buffer_obj.tensor[0] = self.fused_rotary_emb(
+                        old_positions_full,
+                        new_positions_full,
+                        compute_gpu_buffer_obj.tensor[0],
+                    )
+
+                # gap zeroing after RoPE
+                if self.current_gap_positions.numel():
+                    compute_gpu_buffer_obj.tensor[:, self.current_gap_positions] = 0.0
+
+                self.buffer_mapping[layer_id - 1] = compute_gpu_buffer_obj
+
+                logger.debug(f"Finished loading layer {layer_id - 1} into buffer")
+
+            if layer_id < self.num_layers:
+                memory_objs_layer = yield
+
+                # memobj -> gpu_buffer
+                with torch.cuda.stream(self.load_stream):
+                    for start, end, memory_obj in zip(
+                        starts, ends, memory_objs_layer, strict=False
+                    ):
+                        assert memory_obj.metadata.fmt == MemoryFormat.KV_2TD
+                        assert load_gpu_buffer_obj.tensor is not None
+                        load_gpu_buffer_obj.tensor[0][
+                            start - buf_offset : end - buf_offset
+                        ].copy_(memory_obj.tensor[0], non_blocking=True)
+
+                        load_gpu_buffer_obj.tensor[1][
+                            start - buf_offset : end - buf_offset
+                        ].copy_(memory_obj.tensor[1], non_blocking=True)
+
+                        if self.cache_positions and layer_id == 0:
+                            old_positions_full[
+                                start - buf_offset : end - buf_offset
+                            ] = memory_obj.metadata.cached_positions
+
+            elif layer_id == self.num_layers:
+                yield
+
+        # free the buffer memory
+        load_gpu_buffer_obj.ref_count_down()
+        compute_gpu_buffer_obj.ref_count_down()
+
+        assert len(self.buffer_mapping) == 0, (
+            "There are still layers in the buffer mapping after "
+            "releasing the GPU buffers."
+        )
+
+        yield
+
+    # TODO(Jiayi): Reduce repetitive operations in `batched_to_gpu`
+    # and `batched_from_gpu`.
+    @_lmcache_nvtx_annotate
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]], List[MemoryObj]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        This function is a generator that moves the KV cache from the paged GPU
+        memory to the memory objects. The first iteration will prepare some
+        related metadata and initiate the transfer in the first layer. In each
+        of the following iterations, it will first wait until the storing of
+        previous layer finishes, and then initiate string the KV cache of the
+        current layer one. The storing process of the KV cache is paged GPU
+        memory -> GPU buffer -> memory objects. The last iteration simply waits
+        for the last layer to finish.
+        In total, this the generator will yield num_layers + 1 times.
+
+        :param memory_objs: The memory objects to store the KV cache. The first
+            dimension is the number of layers, and the second dimension is the
+            number of memory objects (i.e., number of chunks) for each layer.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        buf_start = 0
+        slot_mapping_chunks = []
+        buf_starts_ends = []
+        old_positions_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            buf_end = buf_start + end - start
+            buf_starts_ends.append((buf_start, buf_end))
+            slot_mapping_chunks.append(slot_mapping[start:end])
+            buf_start = buf_end
+            if self.cache_positions:
+                old_positions_chunks.append(
+                    torch.arange(
+                        start, end, device=self.kvcaches[0].device, dtype=torch.int64
+                    )
+                )
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+        buffer_shape = self.get_shape(num_tokens)
+        assert self.gpu_buffer_allocator is not None
+        tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+            buffer_shape, self.dtype, MemoryFormat.KV_2TD
+        )
+        assert tmp_gpu_buffer_obj is not None, (
+            "Failed to allocate GPU buffer in GPUConnector"
+        )
+        assert tmp_gpu_buffer_obj.tensor is not None
+
+        current_stream = torch.cuda.current_stream()
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = memory_objs[layer_id]
+            # kvcaches -> gpu_buffer -> memobj
+            with torch.cuda.stream(self.store_stream):
+                self.store_stream.wait_stream(current_stream)
+                lmc_ops.single_layer_kv_transfer(
+                    tmp_gpu_buffer_obj.tensor,
+                    self.kvcaches[layer_id],
+                    slot_mapping_full,
+                    lmc_ops.TransferDirection.D2H,
+                    self.engine_kv_format,
+                    token_major=False,  # shape is [2, num_tokens, hidden_dim]
+                )
+                for (buf_start, buf_end), memory_obj, old_positions in zip(
+                    buf_starts_ends,
+                    memory_objs_layer,
+                    old_positions_chunks,
+                    strict=False,
+                ):
+                    assert memory_obj.tensor is not None
+                    memory_obj.tensor[0].copy_(
+                        tmp_gpu_buffer_obj.tensor[0][buf_start:buf_end],
+                        non_blocking=True,
+                    )
+                    memory_obj.tensor[1].copy_(
+                        tmp_gpu_buffer_obj.tensor[1][buf_start:buf_end],
+                        non_blocking=True,
+                    )
+                    if self.cache_positions:
+                        memory_obj.metadata.cached_positions = old_positions
+
+            yield
+            self.store_stream.synchronize()
+            logger.debug(f"Finished offloading layer {layer_id}")
+
+        # free the buffer memory
+        tmp_gpu_buffer_obj.ref_count_down()
+        yield
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        return torch.Size([2, num_tokens, self.hidden_dim_size])
+
+
+class VLLMPagedMemLayerwiseGPUConnector(GPUConnectorInterface):
+    """ """
+
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_gpu: bool = False,
+        **kwargs,
+    ):
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+        self.use_gpu = use_gpu
+        self.layout_hints: LayoutHints = (
+            kwargs.get(  # type: ignore[assignment]
+                "layout_hints"
+            )
+            or {}
+        )
+
+        self.gpu_buffer_allocator = None
+
+        assert "chunk_size" in kwargs, (
+            "chunk_size should be provided to create a GPU buffer."
+        )
+        assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+        assert "device" in kwargs, "device should be provided to create a GPU buffer."
+
+        self.dtype = kwargs["dtype"]
+        self.device = kwargs["device"]
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        # All sizes are in bytes
+        self.element_size = torch.tensor([], dtype=self.dtype).element_size()
+
+        self.load_stream = torch.cuda.Stream()
+        self.store_stream = torch.cuda.Stream()
+
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+        layout_hints: Optional[LayoutHints] = None,
+    ) -> "VLLMPagedMemLayerwiseGPUConnector":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+            layout_hints: Optional hints about KV cache layout from the
+                serving engine.
+
+        Returns:
+            A new instance of VLLMPagedMemLayerwiseGPUConnector.
+        """
+        # Extract parameters from metadata
+        # kv_shape: (num_layer, 2 or 1, chunk_size, num_kv_head, head_size)
+        num_layers = metadata.kv_shape[0]
+        chunk_size = metadata.kv_shape[2]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_gpu=use_gpu,
+            chunk_size=chunk_size,
+            dtype=metadata.kv_dtype,
+            device=device,
+            use_mla=metadata.use_mla,
+            layout_hints=layout_hints,
+        )
+
+    def _lazy_initialize_buffer(self, kv_caches):
+        """
+        Lazily initialize the GPU buffer allocator if it is not initialized yet.
+        Currently, we use the `kv_caches` (kv cache pointer) to determine
+        the gpu buffer size in gpu connector.
+        Also, the first request might be a bit slower due to buffer creation.
+        """
+        if self.use_gpu and self.gpu_buffer_allocator is None:
+            logger.info("Lazily initializing GPU buffer.")
+            # NOTE (Jiayi): We use the first layer to determine the gpu buffer size.
+            # NOTE (Jiayi): Using the exact number of tokens in the first layer
+            # is okay since fragmentation shouldn't exist in the `gpu_buffer_allocator`
+            # in layerwise mode.
+
+            self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+                kv_caches, EngineType.VLLM, layout_hints=self.layout_hints
+            )
+            self.kvcaches = kv_caches
+            assert_is_vllm_mla_or_flash_attn_or_flash_infer(self.engine_kv_format)
+            self.tokens_per_layer = get_tokens_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            self.elements_per_layer = get_elements_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            logger.info(
+                f"Lazily initializing GPU buffer (max tokens={self.tokens_per_layer})."
+            )
+            gpu_buffer_size = self.elements_per_layer * self.element_size
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                gpu_buffer_size, device=self.device
+            )
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    @_lmcache_nvtx_annotate
+    def batched_to_gpu(self, starts: List[int], ends: List[int], **kwargs):
+        """
+        This function is a generator that moves the KV cache from the memory
+        objects to paged GPU memory. The first iteration will prepare some
+        related metadata. In each of the following iterations, it will first
+        wait until the loading of the previous layer finish, and then load
+        one layer of KV cache from the memory objects -> GPU buffer ->
+        paged GPU memory. The last iteration simply waits for the last layer
+        to finish.
+        In total, this the generator will yield num_layers + 2 times.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        sync: bool = kwargs["sync"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        # TODO(Jiayi): Optimize away this `cat`
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        mem_fmt = MemoryFormat.KV_MLA_FMT if self.use_mla else MemoryFormat.KV_T2D
+
+        tmp_gpu_buffer_obj: Optional[MemoryObj] = None
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+            assert self.gpu_buffer_allocator is not None
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, mem_fmt
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        offset = starts[0]
+        current_stream = torch.cuda.current_stream()
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = yield
+            if sync:
+                current_stream.wait_stream(self.load_stream)
+            if layer_id > 0:
+                logger.debug(f"Finished loading layer {layer_id - 1}")
+
+            # memobj -> gpu_buffer -> kvcaches
+            with torch.cuda.stream(self.load_stream):
+                for start, end, memory_obj in zip(
+                    starts, ends, memory_objs_layer, strict=False
+                ):
+                    # Validate memory format
+                    if self.use_mla:
+                        assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT, (
+                            f"Expected memory format {MemoryFormat.KV_MLA_FMT}, "
+                            f"got {memory_obj.metadata.fmt}"
+                        )
+                    else:
+                        assert memory_obj.metadata.fmt == MemoryFormat.KV_T2D, (
+                            f"Expected memory format {MemoryFormat.KV_T2D}, "
+                            f"got {memory_obj.metadata.fmt}"
+                        )
+                    if self.use_gpu:
+                        tmp_gpu_buffer_obj.tensor[start - offset : end - offset].copy_(
+                            memory_obj.tensor, non_blocking=True
+                        )
+                    else:
+                        lmc_ops.single_layer_kv_transfer(
+                            memory_obj.tensor,
+                            self.kvcaches[layer_id],
+                            slot_mapping_full,
+                            lmc_ops.TransferDirection.H2D,
+                            self.engine_kv_format,
+                            token_major=True,
+                        )
+
+                if self.use_gpu:
+                    lmc_ops.single_layer_kv_transfer(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[layer_id],
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.H2D,
+                        self.engine_kv_format,
+                        token_major=True,
+                    )
+        yield
+
+        # synchronize the last layer
+        if sync:
+            current_stream.wait_stream(self.load_stream)
+
+        # free the buffer memory
+        if tmp_gpu_buffer_obj is not None:
+            tmp_gpu_buffer_obj.ref_count_down()
+
+        logger.debug(f"Finished loading all {self.num_layers} layers.")
+        yield
+
+    @_lmcache_nvtx_annotate
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        This function is a generator that moves the KV cache from the paged GPU
+        memory to the memory objects. The first iteration will prepare some
+        related metadata and initiate the transfer in the first layer. In each
+        of the following iterations, it will first wait until the storing of
+        previous layer finishes, and then initiate string the KV cache of the
+        current layer one. The storing process of the KV cache is paged GPU
+        memory -> GPU buffer -> memory objects. The last iteration simply waits
+        for the last layer to finish.
+        In total, this the generator will yield num_layers + 1 times.
+
+        :param memory_objs: The memory objects to store the KV cache. The first
+            dimension is the number of layers, and the second dimension is the
+            number of memory objects (i.e., number of chunks) for each layer.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        sync: bool = kwargs["sync"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        mem_fmt = MemoryFormat.KV_MLA_FMT if self.use_mla else MemoryFormat.KV_T2D
+
+        tmp_gpu_buffer_obj: Optional[MemoryObj] = None
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+            assert self.gpu_buffer_allocator is not None
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, mem_fmt
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        offset = starts[0]
+        current_stream = torch.cuda.current_stream()
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = memory_objs[layer_id]
+            # kvcaches -> gpu_buffer -> memobj
+            with torch.cuda.stream(self.store_stream):
+                self.store_stream.wait_stream(current_stream)
+                if self.use_gpu:
+                    lmc_ops.single_layer_kv_transfer(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[layer_id],
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        token_major=True,
+                    )
+                for start, end, memory_obj in zip(
+                    starts, ends, memory_objs_layer, strict=False
+                ):
+                    assert memory_obj.tensor is not None
+                    if self.use_gpu:
+                        memory_obj.tensor.copy_(
+                            tmp_gpu_buffer_obj.tensor[start - offset : end - offset],
+                            non_blocking=True,
+                        )
+                    else:
+                        lmc_ops.single_layer_kv_transfer(
+                            memory_obj.tensor,
+                            self.kvcaches[layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.D2H,
+                            self.engine_kv_format,
+                            token_major=True,
+                        )
+                    # Set metadata format
+                    if self.use_mla:
+                        memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+            yield
+            if sync:
+                self.store_stream.synchronize()
+            logger.debug(f"Finished offloading layer {layer_id}")
+
+        # free the buffer memory
+        if tmp_gpu_buffer_obj is not None:
+            tmp_gpu_buffer_obj.ref_count_down()
+
+        yield
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        if self.use_mla:
+            # MLA format: [num_tokens, hidden_dim_size]
+            return torch.Size([num_tokens, self.hidden_dim_size])
+        else:
+            # Standard format: [num_tokens, 2, hidden_dim_size]
+            return torch.Size([num_tokens, 2, self.hidden_dim_size])
+
+
+class SGLangGPUConnector(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a list of tensors, one for each layer,
+    with separate key and value pointers.
+    More specifically, we have:
+    - kvcaches: Tuple[List[Tensor], List[Tensor]]
+      - The first element is a list of key tensors, one per layer.
+      - The second element is a list of value tensors, one per layer.
+    - Each tensor: [page_buffer_size, head_num, head_size]
+
+    The connector manages the transfer of KV cache data between CPU and GPU
+    memory for SGLang using pointer arrays for efficient access.
+    It will produce/consume memory objects with KV_2LTD format.
+    """
+
+    def __init__(
+        self, hidden_dim_size: int, num_layers: int, use_gpu: bool = False, **kwargs
+    ):
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+
+        self.kv_cache_pointers_on_gpu: dict[int, torch.Tensor] = {}
+        self.page_buffer_size = 0
+
+        self.gpu_buffer: Optional[torch.Tensor] = None
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+        self.num_kv_cache = num_layers if self.use_mla else num_layers * 2
+        self.kv_cache_pointers = torch.empty(
+            self.num_kv_cache, dtype=torch.int64, device="cpu"
+        )
+
+        if use_gpu:
+            assert "chunk_size" in kwargs, (
+                "chunk_size should be provided to create a GPU buffer."
+            )
+            assert "device" in kwargs, (
+                "device should be provided to create a GPU buffer."
+            )
+            shape = self.get_shape(kwargs["chunk_size"])
+            self.gpu_buffer = torch.empty(
+                shape, dtype=kwargs["dtype"], device=kwargs["device"]
+            )
+            logger.info(f"GPU buffer: {self.gpu_buffer.shape}")
+
+    def _initialize_pointers(self, kv_caches: DiscoverableKVCache) -> torch.Tensor:
+        self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+            kv_caches, EngineType.SGLANG
+        )
+        num_layers = get_num_layers(kv_caches, self.engine_kv_format)
+        # SGLang registers every layer as one group; pass all indices in order.
+        ptrs = get_group_data_ptrs(
+            kv_caches, self.engine_kv_format, list(range(num_layers))
+        )
+        assert len(ptrs) == self.num_kv_cache, (
+            f"Expected {self.num_kv_cache} KV cache pointers, got {len(ptrs)}"
+        )
+        self.kv_cache_pointers.numpy()[:] = ptrs
+
+        device = get_device(kv_caches)
+        assert device.type == "cuda", "The device should be CUDA."
+        idx = device.index
+        if idx not in self.kv_cache_pointers_on_gpu:
+            self.kv_cache_pointers_on_gpu[idx] = torch.empty(
+                self.num_kv_cache, dtype=torch.int64, device=device
+            )
+        self.kv_cache_pointers_on_gpu[idx].copy_(self.kv_cache_pointers)
+
+        self.page_buffer_size = get_page_buffer_size(kv_caches, self.engine_kv_format)
+        return self.kv_cache_pointers_on_gpu[idx]
+
+    @_lmcache_nvtx_annotate
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "partial slot mapping"
+             where its length is the same as the uncached token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying CUDA kernel will never see -1 in slot_mapping)
+
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs.
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        if self.use_mla:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_MLA_FMT:
+                raise ValueError(
+                    "The memory object should be in KV_MLA_FMT format in"
+                    f" order to be processed by {self.__class__.__name__}"
+                )
+        else:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_2LTD:
+                raise ValueError(
+                    "The memory object should be in KV_2LTD format in"
+                    f" order to be processed by {self.__class__.__name__}"
+                )
+
+        if "kvcaches" not in kwargs:
+            raise ValueError("'kvcaches' should be provided in kwargs.")
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        offset = kwargs.get("offset", 0)
+
+        kvcaches: DiscoverableKVCache = kwargs["kvcaches"]
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(kvcaches)
+        lmc_ops.multi_layer_kv_transfer_unilateral(
+            memory_obj.tensor,
+            kv_cache_pointers,
+            slot_mapping[start - offset : end - offset],
+            get_device(kvcaches),
+            self.page_buffer_size,
+            lmc_ops.TransferDirection.H2D,
+            self.engine_kv_format,
+        )
+
+    @_lmcache_nvtx_annotate
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Will set the memory_obj.metadata.fmt to MemoryFormat.KV_2LTD.
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "partial slot mapping"
+             where its length is the same as the uncached token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying CUDA kernel will never see -1 in slot_mapping)
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs,
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        if "kvcaches" not in kwargs:
+            raise ValueError("'kvcaches' should be provided in kwargs.")
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        kvcaches: DiscoverableKVCache = kwargs["kvcaches"]
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(kvcaches)
+
+        if self.gpu_buffer is None or end - start != self.gpu_buffer.shape[2]:
+            lmc_ops.multi_layer_kv_transfer_unilateral(
+                memory_obj.tensor,
+                kv_cache_pointers,
+                slot_mapping[start:end],
+                get_device(kvcaches),
+                self.page_buffer_size,
+                lmc_ops.TransferDirection.D2H,
+                self.engine_kv_format,
+            )
+        else:
+            # kvcaches -> gpu_buffer -> memobj
+            assert self.gpu_buffer.device == get_device(kvcaches)
+            tmp_gpu_buffer = self.gpu_buffer[:, :, : end - start, :]
+            lmc_ops.multi_layer_kv_transfer_unilateral(
+                tmp_gpu_buffer,
+                kv_cache_pointers,
+                slot_mapping[start:end],
+                get_device(kvcaches),
+                self.page_buffer_size,
+                lmc_ops.TransferDirection.D2H,
+                self.engine_kv_format,
+            )
+            memory_obj.tensor.copy_(tmp_gpu_buffer, non_blocking=True)
+
+        if not memory_obj.tensor.is_cuda:
+            # Force a synchronize if the target buffer is NOT CUDA device
+            # NOTE: for better performance, we may not want to sync for every
+            # memory object
+            torch.cuda.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        return torch.Size([2, self.num_layers, num_tokens, self.hidden_dim_size])
+
+    # TODO(Jiayi): need to optimize to enable real batching
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.to_gpu(memory_obj, start, end, **kwargs)
+
+    # TODO(Yuwei): need to optimize to enable real batching
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+
+# TODO: support MLA
+class SGLangLayerwiseGPUConnector(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a list of tensors, one for each layer,
+    with separate key and value pointers.
+    More specifically, we have:
+    - kvcaches: Tuple[List[Tensor], List[Tensor]]
+      - The first element is a list of key tensors, one per layer.
+      - The second element is a list of value tensors, one per layer.
+    - Each tensor: [page_buffer_size, head_num, head_size]
+
+    The connector manages the transfer of KV cache data between CPU and GPU
+    memory for SGLang using pointer arrays for efficient access.
+    It will produce/consume memory objects with KV_2LTD format.
+    """
+
+    def __init__(
+        self, hidden_dim_size: int, num_layers: int, use_gpu: bool = False, **kwargs
+    ):
+        assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+        self.dtype = kwargs["dtype"]
+        assert "device" in kwargs, "device should be provided to create a GPU buffer."
+        self.device = kwargs["device"]
+
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+
+        self.kv_cache_pointers_on_gpu: dict[int, torch.Tensor] = {}
+        self.page_buffer_size = 0
+
+        self.gpu_buffer: Optional[torch.Tensor] = None
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+        self.num_kv_cache = num_layers if self.use_mla else num_layers * 2
+        self.element_size = torch.tensor([], dtype=self.dtype).element_size()
+        self.kv_cache_pointers = torch.empty(
+            self.num_kv_cache, dtype=torch.int64, device="cpu"
+        )
+        self.use_gpu = use_gpu
+        self.gpu_buffer_allocator: Optional[GPUMemoryAllocator] = None
+
+    def _lazy_initialize_buffer(self, kv_caches):
+        """
+        Lazily initialize the GPU buffer allocator if it is not initialized yet.
+        Currently, we use the `kv_caches` (kv cache pointer) to determine
+        the gpu buffer size in gpu connector.
+        Also, the first request might be a bit slower due to buffer creation.
+        """
+        if self.use_gpu and self.gpu_buffer_allocator is None:
+            self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+                kv_caches, EngineType.SGLANG
+            )
+            self.tokens_per_layer = get_tokens_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            self.elements_per_layer = get_elements_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            logger.info(
+                f"Lazily initializing GPU buffer (max tokens={self.tokens_per_layer})."
+            )
+            gpu_buffer_size = self.elements_per_layer * self.element_size
+            logger.info(
+                f"Lazily initializing GPU buffer (gpu buffer size={gpu_buffer_size})."
+            )
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                gpu_buffer_size, device=self.device
+            )
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        raise NotImplementedError
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        raise NotImplementedError
+
+    @_lmcache_nvtx_annotate
+    def batched_to_gpu(self, starts: List[int], ends: List[int], **kwargs):
+        """
+        This function is a generator that moves the KV cache from the memory
+        objects to paged GPU memory. The first iteration will prepare some
+        related metadata. In each of the following iterations, it will first
+        wait until the loading of the previous layer finish, and then load
+        one layer of KV cache from the memory objects -> GPU buffer ->
+        paged GPU memory. The last iteration simply waits for the last layer
+        to finish.
+        In total, this the generator will yield num_layers + 2 times.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+
+            assert self.gpu_buffer_allocator is not None, (
+                "GPU buffer allocator should be initialized"
+            )
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, MemoryFormat.KV_T2D
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        offset = starts[0]
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = yield
+            if layer_id > 0:
+                logger.debug(f"Finished loading layer {layer_id - 1}")
+
+            # memobj -> gpu_buffer -> kvcaches
+            for start, end, memory_obj in zip(
+                starts, ends, memory_objs_layer, strict=False
+            ):
+                assert memory_obj.metadata.fmt == MemoryFormat.KV_T2D
+                if self.use_gpu:
+                    tmp_gpu_buffer_obj.tensor[start - offset : end - offset].copy_(
+                        memory_obj.tensor, non_blocking=True
+                    )
+                else:
+                    lmc_ops.single_layer_kv_transfer_sgl(
+                        memory_obj.tensor,
+                        self.kvcaches[0][layer_id],
+                        self.kvcaches[1][layer_id],
+                        slot_mapping[start:end],
+                        lmc_ops.TransferDirection.H2D,
+                        token_major=True,
+                    )
+
+            if self.use_gpu:
+                t, h, d = self.kvcaches[0][layer_id].shape
+
+                lmc_ops.single_layer_kv_transfer_sgl(
+                    tmp_gpu_buffer_obj.tensor,
+                    self.kvcaches[0][layer_id].view(t, 1, h, d),
+                    self.kvcaches[1][layer_id].view(t, 1, h, d),
+                    slot_mapping_full,
+                    lmc_ops.TransferDirection.H2D,
+                    token_major=True,
+                )
+
+        # free the buffer memory
+        if self.use_gpu:
+            tmp_gpu_buffer_obj.ref_count_down()
+
+        logger.debug(f"Finished loading layer {layer_id}")
+        yield
+
+    @_lmcache_nvtx_annotate
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        This function is a generator that moves the KV cache from the paged GPU
+        memory to the memory objects. The first iteration will prepare some
+        related metadata and initiate the transfer in the first layer. In each
+        of the following iterations, it will first wait until the storing of
+        previous layer finishes, and then initiate string the KV cache of the
+        current layer one. The storing process of the KV cache is paged GPU
+        memory -> GPU buffer -> memory objects. The last iteration simply waits
+        for the last layer to finish.
+        In total, this the generator will yield num_layers + 1 times.
+
+        :param memory_objs: The memory objects to store the KV cache. The first
+            dimension is the number of layers, and the second dimension is the
+            number of memory objects (i.e., number of chunks) for each layer.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+
+            assert self.gpu_buffer_allocator is not None, (
+                "GPU buffer allocator should be initialized"
+            )
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, MemoryFormat.KV_T2D
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = memory_objs[layer_id]
+            # kvcaches -> gpu_buffer -> memobj
+            if self.use_gpu:
+                t, h, d = self.kvcaches[0][layer_id].shape
+                lmc_ops.single_layer_kv_transfer_sgl(
+                    tmp_gpu_buffer_obj.tensor,
+                    self.kvcaches[0][layer_id].view(t, 1, h, d),
+                    self.kvcaches[1][layer_id].view(t, 1, h, d),
+                    slot_mapping_full,
+                    lmc_ops.TransferDirection.D2H,
+                    token_major=True,
+                )
+
+            start_idx = 0
+
+            for start, end, memory_obj in zip(
+                starts, ends, memory_objs_layer, strict=False
+            ):
+                assert memory_obj.tensor is not None
+                if self.use_gpu:
+                    chunk_len = memory_obj.tensor.shape[0]
+                    memory_obj.tensor.copy_(
+                        tmp_gpu_buffer_obj.tensor[start_idx : start_idx + chunk_len],
+                        non_blocking=True,
+                    )
+                    start_idx += chunk_len
+                else:
+                    lmc_ops.single_layer_kv_transfer_sgl(
+                        memory_obj.tensor,
+                        self.kvcaches[0][layer_id],
+                        self.kvcaches[1][layer_id],
+                        slot_mapping[start:end],
+                        lmc_ops.TransferDirection.D2H,
+                        token_major=True,
+                    )
+
+            yield
+            logger.debug(f"Finished offloading layer {layer_id}")
+
+        # free the buffer memory
+        if self.use_gpu:
+            tmp_gpu_buffer_obj.ref_count_down()
+        yield
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        # TODO: support MLA
+        return torch.Size([num_tokens, 2, self.hidden_dim_size])
+
+
+_TRTLLM_KERNEL_BATCH_SIZE = 32
+
+
+class TRTLLMGPUConnector(GPUConnectorInterface):
+    """GPU connector for TRT-LLM's cross-layer KV pool.
+
+    TRT-LLM hands LMCache a single 4-D pool tensor with shape
+    ``[num_blocks, num_layers, 2, num_kv_heads * tokens_per_block * head_dim]``
+    (HND layout, K and V interleaved on dim 2). On
+    :meth:`register_kv_caches` the connector calls
+    :func:`normalize_kv_and_discover_format` which reshapes the trailing
+    dim into ``[num_kv_heads, tokens_per_block, head_dim]``, yielding the
+    canonical 6-D ``[NB, NL, 2, NH, BS, HS]`` form (format
+    ``NB_NL_TWO_NH_BS_HS``).
+
+    Transfers go through :func:`lmc_ops.multi_layer_block_kv_transfer` —
+    the multiprocess kernel — using the single base pointer of the pool
+    tensor. Per-chunk block ids are taken from ``kwargs['block_ids']``,
+    sliced as ``block_ids[i * blocks_per_chunk : (i+1) * blocks_per_chunk]``
+    where ``blocks_per_chunk = chunk_size // tokens_per_block``.
+
+    This is intentionally NOT a subclass of
+    :class:`VLLMPagedMemGPUConnectorV3`. V3 drives the in-process kernel
+    with ``slot_mapping`` and per-layer pointers — the wrong primitive
+    for a single cross-layer base pointer.
+    """
+
+    def __init__(
+        self,
+        num_kv_heads: int,
+        head_dim: int,
+        hidden_dim_size: int,
+        num_layers: int,
+        chunk_size: int,
+        dtype: torch.dtype,
+        device: torch.device,
+    ) -> None:
+        self.num_kv_heads = num_kv_heads
+        self.head_dim = head_dim
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+        self.chunk_size = chunk_size
+        self.dtype = dtype
+        self.device = device
+        self._batch_size = _TRTLLM_KERNEL_BATCH_SIZE
+        self.load_stream = torch.cuda.Stream(device=device)
+        self.store_stream = torch.cuda.Stream(device=device)
+
+        self.kv_cache_tensor: Optional[torch.Tensor] = None
+        self.paged_buffer_ptrs: Optional[torch.Tensor] = None
+        self.shape_desc: Optional["lmc_ops.PageBufferShapeDesc"] = None
+        self._kv_format: Optional["lmc_ops.EngineKVFormat"] = None
+        self.tokens_per_block: Optional[int] = None
+        self.blocks_per_chunk: Optional[int] = None
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        device: torch.device,
+    ) -> "TRTLLMGPUConnector":
+        """Create a connector from :class:`LMCacheMetadata`.
+
+        Args:
+            metadata: Metadata carrying ``kv_shape``
+                ``(num_layers, 2, chunk_size, num_kv_heads, head_size)`` and
+                ``kv_dtype``.
+            device: CUDA device for transfer streams and block-ids staging.
+        """
+        num_layers = metadata.kv_shape[0]
+        chunk_size = metadata.kv_shape[2]
+        num_kv_heads = metadata.kv_shape[3]
+        head_dim = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_heads * head_dim
+        return cls(
+            num_kv_heads=num_kv_heads,
+            head_dim=head_dim,
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            chunk_size=chunk_size,
+            dtype=metadata.kv_dtype,
+            device=device,
+        )
+
+    def register_kv_caches(self, kv_cache_tensor: torch.Tensor) -> None:
+        """Register TRT-LLM's 4-D KV pool tensor with the connector.
+
+        Reshapes the 4-D tensor to canonical 6-D form, runs format
+        discovery, and caches the base pointer / shape descriptor used
+        by every subsequent transfer.
+
+        Called once at TRT-LLM worker init — separate from
+        :meth:`to_gpu` / :meth:`from_gpu`. Idempotent if called with the
+        same tensor; reassigning a different tensor replaces the
+        previously registered one.
+        """
+        if kv_cache_tensor.dim() != 4:
+            raise ValueError(
+                f"TRT-LLM kv_cache_tensor must be 4-D "
+                f"[NB, NL, 2, flat], got shape {tuple(kv_cache_tensor.shape)}"
+            )
+        num_blocks, num_layers, kv_factor, flat = kv_cache_tensor.shape
+        tokens_per_block = flat // (self.num_kv_heads * self.head_dim)
+        if tokens_per_block * self.num_kv_heads * self.head_dim != flat:
+            raise ValueError(
+                f"flat dim {flat} not divisible by "
+                f"num_kv_heads * head_dim ({self.num_kv_heads * self.head_dim})"
+            )
+        self.tokens_per_block = tokens_per_block
+        self.blocks_per_chunk = self.chunk_size // tokens_per_block
+
+        layout_hints: LayoutHints = {
+            "kv_layout": "HND",
+            "num_kv_heads": self.num_kv_heads,
+            "tokens_per_block": tokens_per_block,
+            "head_dim": self.head_dim,
+        }
+        kv_format, normalized = normalize_kv_and_discover_format(
+            kv_cache_tensor, EngineType.TRTLLM, layout_hints=layout_hints
+        )
+        if not isinstance(normalized, torch.Tensor):
+            raise ValueError(
+                "TRT-LLM normalize must return a bare tensor; "
+                f"got {type(normalized).__name__}"
+            )
+        self._kv_format = kv_format
+        self.kv_cache_tensor = normalized
+
+        shape_desc = lmc_ops.PageBufferShapeDesc()
+        shape_desc.kv_size = kv_factor
+        shape_desc.nl = num_layers
+        shape_desc.nb = num_blocks
+        shape_desc.bs = tokens_per_block
+        shape_desc.nh = self.num_kv_heads
+        shape_desc.hs = self.head_dim
+        shape_desc.element_size = normalized.element_size()
+        set_shape_desc_dtype(shape_desc, self.dtype)
+        self.shape_desc = shape_desc
+
+        self.paged_buffer_ptrs = torch.tensor(
+            get_group_data_ptrs(normalized, kv_format, list(range(num_layers))),
+            dtype=torch.int64,
+            device=self.device,
+        )
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        return torch.Size([2, self.num_layers, num_tokens, self.hidden_dim_size])
+
+    def _stage_block_ids(self, block_ids: List[int]) -> torch.Tensor:
+        return torch.tensor(block_ids, dtype=torch.int64, device=self.device)
+
+    def _get_chunk_block_ids(
+        self, block_ids: List[int], start: int
+    ) -> Optional[List[int]]:
+        assert self.blocks_per_chunk is not None
+        chunk_idx = start // self.chunk_size
+        bs = chunk_idx * self.blocks_per_chunk
+        be = bs + self.blocks_per_chunk
+        if be > len(block_ids):
+            return None
+        return block_ids[bs:be]
+
+    def _transfer(
+        self,
+        tensor_ptr: int,
+        block_ids: List[int],
+        direction: "lmc_ops.TransferDirection",
+        stream: torch.cuda.Stream,
+    ) -> None:
+        with torch.cuda.stream(stream):
+            block_ids_gpu = self._stage_block_ids(block_ids)
+            lmc_ops.multi_layer_block_kv_transfer(
+                self.paged_buffer_ptrs,
+                [tensor_ptr],
+                block_ids_gpu,
+                self.device,
+                direction,
+                self.shape_desc,
+                self.chunk_size,
+                self._kv_format,
+                0,  # skip_prefix_n_blocks
+            )
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs) -> None:
+        if self.kv_cache_tensor is None:
+            raise RuntimeError("register_kv_caches must be called before to_gpu")
+        chunk_blocks = self._get_chunk_block_ids(kwargs.get("block_ids", []), start)
+        if chunk_blocks is None or memory_obj.tensor is None:
+            return
+        self._transfer(
+            memory_obj.tensor.data_ptr(),
+            chunk_blocks,
+            lmc_ops.TransferDirection.H2D,
+            self.load_stream,
+        )
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs) -> None:
+        if self.kv_cache_tensor is None:
+            raise RuntimeError("register_kv_caches must be called before from_gpu")
+        chunk_blocks = self._get_chunk_block_ids(kwargs.get("block_ids", []), start)
+        if chunk_blocks is None or memory_obj.tensor is None:
+            return
+        self._transfer(
+            memory_obj.tensor.data_ptr(),
+            chunk_blocks,
+            lmc_ops.TransferDirection.D2H,
+            self.store_stream,
+        )
+
+    def _batched_transfer(
+        self,
+        memory_objs: List[MemoryObj],
+        starts: List[int],
+        block_ids: List[int],
+        direction: "lmc_ops.TransferDirection",
+        stream: torch.cuda.Stream,
+    ) -> None:
+        valid: List[Tuple[MemoryObj, List[int]]] = []
+        for memory_obj, start in zip(memory_objs, starts, strict=False):
+            if isinstance(memory_obj, list) or memory_obj.tensor is None:
+                continue
+            chunk_blocks = self._get_chunk_block_ids(block_ids, start)
+            if chunk_blocks is not None:
+                valid.append((memory_obj, chunk_blocks))
+
+        with torch.cuda.stream(stream):
+            for i in range(0, len(valid), self._batch_size):
+                batch = valid[i : i + self._batch_size]
+                all_block_ids: List[int] = []
+                ptrs: List[int] = []
+                for mo, blocks in batch:
+                    all_block_ids.extend(blocks)
+                    ptrs.append(mo.tensor.data_ptr())  # type: ignore[union-attr]
+                block_ids_gpu = self._stage_block_ids(all_block_ids)
+                lmc_ops.multi_layer_block_kv_transfer(
+                    self.paged_buffer_ptrs,
+                    ptrs,
+                    block_ids_gpu,
+                    self.device,
+                    direction,
+                    self.shape_desc,
+                    self.chunk_size,
+                    self._kv_format,
+                    0,
+                )
+
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]], List[MemoryObj]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ) -> None:
+        if self.kv_cache_tensor is None:
+            raise RuntimeError(
+                "register_kv_caches must be called before batched_from_gpu"
+            )
+        self._batched_transfer(
+            memory_objs,  # type: ignore[arg-type]
+            starts,
+            kwargs.get("block_ids", []),
+            lmc_ops.TransferDirection.D2H,
+            self.store_stream,
+        )
+
+    def batched_to_gpu(
+        self,
+        memory_objs: Union[
+            List[List[MemoryObj]], List[MemoryObj], List[int], None
+        ] = None,
+        starts: Optional[List[int]] = None,
+        ends: Optional[List[int]] = None,
+        **kwargs,
+    ) -> None:
+        if memory_objs is None or starts is None or ends is None:
+            return
+        if self.kv_cache_tensor is None:
+            raise RuntimeError(
+                "register_kv_caches must be called before batched_to_gpu"
+            )
+        self._batched_transfer(
+            memory_objs,  # type: ignore[arg-type]
+            starts,
+            kwargs.get("block_ids", []),
+            lmc_ops.TransferDirection.H2D,
+            self.load_stream,
+        )
diff --git a/lmcache/v1/gpu_connector/gpu_ops.py b/lmcache/v1/gpu_connector/gpu_ops.py
new file mode 100644
index 0000000..2070511
--- /dev/null
+++ b/lmcache/v1/gpu_connector/gpu_ops.py
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Sequence
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.gds_context import SlabDirection, get_gds_context
+from lmcache.v1.memory_allocators.lazy_memory_allocator import LazyMemoryAllocator
+from lmcache.v1.memory_management import GDSMemoryObject, MemoryObj
+import lmcache.c_ops as lmc_ops
+
+
+# Helper functions
+def lmcache_memcpy_async_h2d(
+    memory_obj: MemoryObj,
+    gpu_buffer: torch.Tensor,
+):
+    """Helper function to copy memory object allocated by different
+    allocators to GPU buffer.
+
+    This function is non-blocking and won't do stream synchronization.
+
+    :param MemoryObj memory_obj: The memory object to be copied.
+    :param torch.Tensor gpu_buffer: The GPU buffer to copy the data to.
+    """
+    if isinstance(memory_obj, GDSMemoryObject):
+        get_gds_context().transfer_async(memory_obj, gpu_buffer, SlabDirection.READ)
+        return
+    src_tensor = memory_obj.raw_tensor
+    if src_tensor is None:
+        raise ValueError(
+            "memory_obj.raw_tensor is None; ensure the MemoryObj has been allocated."
+        )
+    mem_obj_size = memory_obj.get_size()
+    if mem_obj_size != gpu_buffer.nbytes:
+        raise ValueError(
+            f"Size mismatch: memory_obj nbytes={mem_obj_size}, "
+            f"gpu_buffer nbytes={gpu_buffer.nbytes}"
+        )
+    if isinstance(memory_obj.parent(), LazyMemoryAllocator):
+        lmc_ops.lmcache_memcpy_async(
+            gpu_buffer.data_ptr(),
+            memory_obj.data_ptr,
+            mem_obj_size,
+            lmc_ops.TransferDirection.H2D,
+            memory_obj.meta.address,
+            LazyMemoryAllocator.PIN_CHUNK_SIZE,
+        )
+    else:
+        gpu_buffer.view(torch.uint8).copy_(
+            src_tensor.view(torch.uint8)[:mem_obj_size], non_blocking=True
+        )
+
+
+def lmcache_memcpy_async_d2h(
+    gpu_buffer: torch.Tensor,
+    memory_obj: MemoryObj,
+):
+    """Helper function to copy memory object allocated by different
+    allocators from GPU buffer.
+
+    This function is non-blocking and won't do stream synchronization.
+
+    :param torch.Tensor gpu_buffer: The GPU buffer to copy the data from.
+    :param MemoryObj memory_obj: The memory object to be copied to.
+    """
+    if isinstance(memory_obj, GDSMemoryObject):
+        get_gds_context().transfer_async(memory_obj, gpu_buffer, SlabDirection.WRITE)
+        return
+    dst_tensor = memory_obj.raw_tensor
+    if dst_tensor is None:
+        raise ValueError(
+            "memory_obj.raw_tensor is None; ensure the MemoryObj has been allocated."
+        )
+    mem_obj_size = memory_obj.get_size()
+    if mem_obj_size != gpu_buffer.nbytes:
+        raise ValueError(
+            f"Size mismatch: memory_obj nbytes={mem_obj_size}, "
+            f"gpu_buffer nbytes={gpu_buffer.nbytes}"
+        )
+    if isinstance(memory_obj.parent(), LazyMemoryAllocator):
+        lmc_ops.lmcache_memcpy_async(
+            memory_obj.data_ptr,
+            gpu_buffer.data_ptr(),
+            mem_obj_size,
+            lmc_ops.TransferDirection.D2H,
+            memory_obj.meta.address,
+            LazyMemoryAllocator.PIN_CHUNK_SIZE,
+        )
+    else:
+        dst_tensor.view(torch.uint8)[:mem_obj_size].copy_(
+            gpu_buffer.view(torch.uint8), non_blocking=True
+        )
+
+
+def build_staging_copies(
+    memory_objs: Sequence[MemoryObj],
+    gpu_buffers: Sequence[torch.Tensor],
+    is_h2d: bool,
+) -> list["lmc_ops.StagingCopy"]:
+    """Build native ``StagingCopy`` descriptors for one batch of lazy objects.
+
+    The H2D/D2H direction decides which side is source vs. destination; the host
+    side is always the lazy memory object. Callers must ensure every object is
+    lazy-allocator-backed.
+
+    Args:
+        memory_objs: Lazy-allocator memory objects, one per chunk in the batch.
+        gpu_buffers: GPU staging buffers, aligned element-wise with
+            ``memory_objs``.
+        is_h2d: True for retrieve (CPU->GPU), False for store (GPU->CPU).
+
+    Returns:
+        One ``lmc_ops.StagingCopy`` per object, in input order.
+
+    Raises:
+        ValueError: If an object has not been allocated (``raw_tensor`` is None)
+            or its size does not match its GPU buffer.
+    """
+    copies: list["lmc_ops.StagingCopy"] = []
+    for memory_obj, gpu_buffer in zip(memory_objs, gpu_buffers, strict=True):
+        if memory_obj.raw_tensor is None:
+            raise ValueError(
+                "memory_obj.raw_tensor is None; ensure the MemoryObj has been "
+                "allocated."
+            )
+        mem_obj_size = memory_obj.get_size()
+        if mem_obj_size != gpu_buffer.nbytes:
+            raise ValueError(
+                f"Size mismatch: memory_obj nbytes={mem_obj_size}, "
+                f"gpu_buffer nbytes={gpu_buffer.nbytes}"
+            )
+        host_ptr = memory_obj.data_ptr
+        gpu_ptr = gpu_buffer.data_ptr()
+        host_offset = memory_obj.meta.address
+        if is_h2d:
+            copies.append(
+                lmc_ops.StagingCopy(gpu_ptr, host_ptr, mem_obj_size, host_offset)
+            )
+        else:
+            copies.append(
+                lmc_ops.StagingCopy(host_ptr, gpu_ptr, mem_obj_size, host_offset)
+            )
+    return copies
diff --git a/lmcache/v1/gpu_connector/hpu_connector.py b/lmcache/v1/gpu_connector/hpu_connector.py
new file mode 100644
index 0000000..c65a91f
--- /dev/null
+++ b/lmcache/v1/gpu_connector/hpu_connector.py
@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 LMCache Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Standard
+from typing import List, Optional
+
+# Third Party
+import habana_frameworks.torch as htorch
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector import GPUConnectorInterface
+from lmcache.v1.gpu_connector.utils import (
+    get_block_size,
+    get_dtype,
+    get_head_size,
+    get_hidden_dim_size,
+    get_num_blocks,
+    get_num_heads,
+    get_num_layers,
+    get_page_buffer_size,
+    is_mla,
+    normalize_kv_and_discover_format,
+)
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+class VLLMPagedMemHPUConnectorV2(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a nested tuple of K and V tensors.
+    More specifically, we have:
+    - GPUTensor = Tuple[KVLayer, ...]
+    - KVLayer = Tuple[Tensor, Tensor]
+    - Tensor: [num_blocks, block_size, num_heads, head_size]
+    It will produce / consume memory object with KV_2LTD format
+    """
+
+    def __init__(
+        self,
+        use_gpu: bool = False,
+        **kwargs,
+    ):
+        self._attributes_initialized = False
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+        self.use_gpu = use_gpu
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+    ) -> "VLLMPagedMemHPUConnectorV2":
+        """Create a connector from LMCacheMetadata.
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+        Returns:
+            A new instance of VLLMPagedMemHPUConnectorV2.
+        """
+        return cls(
+            use_gpu=use_gpu,
+        )
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "full slot mapping"
+             where it's length is the same as the whole token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying kernel will never see -1 in slot_mapping)
+
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs,
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        slices = slot_mapping[start:end]
+        self._initialize_attributes(self.kvcaches)
+        self._validate_memory_format(memory_obj)
+
+        # Flush the HPU lazy-mode op graph so the slot_mapping slice is
+        # materialized before downstream ops consume it. This also keeps
+        # LMCache's transfer ops decoupled from vLLM's HPU compute graph,
+        # which issues its own mark_step() calls at forward-pass boundaries.
+        htorch.core.mark_step()
+
+        if self.use_mla:
+            tmp = memory_obj.tensor[0].to(slot_mapping.device)
+            total_blocks = self.num_blocks * self.block_size
+            for i, kvcache in enumerate(self.kvcaches):
+                kvcache.view(total_blocks, self.head_size).index_copy_(
+                    0, slices, tmp[i]
+                )
+                htorch.core.mark_step()
+        else:
+            tmp_k = memory_obj.tensor[0].to(slot_mapping.device)
+            tmp_v = memory_obj.tensor[1].to(slot_mapping.device)
+            total_blocks = self.num_blocks * self.block_size
+            d = self.num_heads * self.head_size
+            for i, (kcache, vcache) in enumerate(self.kvcaches):
+                kcache.view(total_blocks, d).index_copy_(0, slices, tmp_k[i])
+                vcache.view(total_blocks, d).index_copy_(0, slices, tmp_v[i])
+                htorch.core.mark_step()
+
+        torch.hpu.synchronize()
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Will set the memory_obj.metadata.fmt to MemoryFormat.KV_MLA_FMT
+        if use_mla is True.
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "full slot mapping"
+             where it's length is the same as the whole token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying kernel will never see -1 in slot_mapping)
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs,
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        slices = slot_mapping[start:end]
+        self._initialize_attributes(self.kvcaches)
+        self._validate_memory_format(memory_obj)
+
+        htorch.core.mark_step()
+
+        if self.use_mla:
+            total_blocks = self.num_blocks * self.block_size
+            tmp = torch.stack(
+                [
+                    kvcache.view(total_blocks, self.head_size).index_select(0, slices)
+                    for kvcache in self.kvcaches
+                ]
+            )
+        else:
+            total_blocks = self.num_blocks * self.block_size
+            d = self.num_heads * self.head_size
+            tmp_k = torch.stack(
+                [
+                    kvcache[0].view(total_blocks, d).index_select(0, slices)
+                    for kvcache in self.kvcaches
+                ]
+            )
+            tmp_v = torch.stack(
+                [
+                    kvcache[1].view(total_blocks, d).index_select(0, slices)
+                    for kvcache in self.kvcaches
+                ]
+            )
+            tmp = torch.stack([tmp_k, tmp_v])
+        memory_obj.tensor.copy_(tmp, non_blocking=True)
+
+        htorch.core.mark_step()
+        torch.hpu.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.to_gpu(memory_obj, start, end, **kwargs)
+
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        """Get the shape of the data given the number of tokens.
+
+        Args:
+            num_tokens: The number of tokens in the data.
+
+        Returns:
+            The shape of the KV cache data.
+
+        Raises:
+            RuntimeError: If attributes have not been initialized yet
+                (i.e., no kv_caches have been seen).
+        """
+        if not self._attributes_initialized:
+            raise RuntimeError(
+                "Cannot determine shape before attributes are initialized. "
+                "Call to_gpu or from_gpu first so that _initialize_attributes "
+                "can discover the KV cache layout."
+            )
+        kv_size = 1 if self.use_mla else 2
+        return torch.Size([kv_size, self.num_layers, num_tokens, self.hidden_dim_size])
+
+    def initialize_kvcaches_ptr(self, **kwargs) -> None:
+        """Initialize the kvcaches pointers if not already initialized."""
+        if "kvcaches" in kwargs:
+            self.kvcaches = kwargs["kvcaches"]
+
+    def _validate_memory_format(self, memory_obj: MemoryObj) -> None:
+        """Validate that the memory object has the expected format.
+
+        Args:
+            memory_obj: The memory object to validate.
+
+        Raises:
+            ValueError: If the memory format does not match the expected
+                format based on whether MLA is in use.
+        """
+        if self.use_mla:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_MLA_FMT:
+                raise ValueError(
+                    "The memory object should be in KV_MLA_FMT format in"
+                    " order to be processed by VLLMPagedMemHPUConnectorV2"
+                )
+        else:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_2LTD:
+                raise ValueError(
+                    "The memory object should be in KV_2LTD format in"
+                    " order to be processed by VLLMPagedMemHPUConnectorV2"
+                )
+
+    def _initialize_attributes(self, kv_caches: List[torch.Tensor]):
+        if self._attributes_initialized or not kv_caches:
+            return
+
+        first = kv_caches[0]
+        if isinstance(first, torch.Tensor):
+            self.device = first.device
+        else:
+            self.device = first[0].device
+        assert self.device.type == "hpu", "The device should be HPU."
+
+        # HPU vLLM provides kv_caches as List[TensorTuple(k_tensor, v_tensor)],
+        # where each TensorTuple contains two 4D tensors of shape
+        # (num_blocks, block_size, num_heads, head_size).
+        # We create a lightweight proxy List[Tensor(2, ...)] to match the
+        # standard vLLM format (NL_X_TWO_NB_BS_NH_HS) for format discovery.
+        if (
+            isinstance(kv_caches, (list, tuple))
+            and len(kv_caches) > 0
+            and len(kv_caches[0]) == 2
+            and not isinstance(kv_caches[0], torch.Tensor)
+            and isinstance(kv_caches[0][0], torch.Tensor)
+            and isinstance(kv_caches[0][1], torch.Tensor)
+        ):
+            # kv_caches[i][0].shape = (num_blocks, block_size, num_heads, head_size)
+            # We need shape (2, num_blocks, block_size, num_heads, head_size)
+            inner_shape = kv_caches[0][0].shape
+            fake_shape = (2, *inner_shape)
+            kv_caches = [
+                torch.empty(fake_shape, dtype=kv_caches[0][0].dtype, device="meta")
+                for _ in range(len(kv_caches))
+            ]
+            logger.info(
+                "HPU: created lightweight kv_caches proxy with shape %s "
+                "for format discovery",
+                fake_shape,
+            )
+
+        self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+            kv_caches, EngineType.VLLM
+        )
+        self.num_layers = get_num_layers(kv_caches, self.engine_kv_format)
+        self.num_blocks = get_num_blocks(kv_caches, self.engine_kv_format)
+        self.block_size = get_block_size(kv_caches, self.engine_kv_format)
+        self.page_buffer_size = get_page_buffer_size(kv_caches, self.engine_kv_format)
+        self.hidden_dim_size = get_hidden_dim_size(kv_caches, self.engine_kv_format)
+        self.head_size = get_head_size(kv_caches, self.engine_kv_format)
+        self.use_mla = is_mla(self.engine_kv_format)
+        self.dtype = get_dtype(kv_caches, self.engine_kv_format)
+        self.num_heads = (
+            1 if self.use_mla else get_num_heads(kv_caches, self.engine_kv_format)
+        )
+
+        self._attributes_initialized = True
+        logger.info(
+            "HPU: attributes initialized - format: %s, "
+            "num_layers: %d, num_blocks: %d, block_size: %d, "
+            "page_buffer_size: %d, hidden_dim_size: %d, head_size: %d, "
+            "use_mla: %s, dtype: %s, num_heads: %d",
+            self.engine_kv_format,
+            self.num_layers,
+            self.num_blocks,
+            self.block_size,
+            self.page_buffer_size,
+            self.hidden_dim_size,
+            self.head_size,
+            self.use_mla,
+            self.dtype,
+            self.num_heads,
+        )
diff --git a/lmcache/v1/gpu_connector/kv_format/__init__.py b/lmcache/v1/gpu_connector/kv_format/__init__.py
new file mode 100644
index 0000000..77f6330
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/__init__.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Format-dispatched geometry for GPU KV caches.
+
+Public surface:
+
+- :class:`KVFormatSpec` -- per-format geometry interface.
+- :func:`get_spec` / :func:`get_spec_class` -- look up the spec for a format.
+- :func:`detect_format` -- normalize a raw ``kv_caches`` and discover its format.
+- :func:`describe_shape` / :func:`concrete_shape` -- render a format's symbolic /
+  numeric shape string.
+"""
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.detection import detect_format
+from lmcache.v1.gpu_connector.kv_format.specs import (
+    KVFormatSpec,
+    concrete_shape,
+    describe_shape,
+    get_spec,
+    get_spec_class,
+)
+
+__all__ = [
+    "KVFormatSpec",
+    "concrete_shape",
+    "describe_shape",
+    "detect_format",
+    "get_spec",
+    "get_spec_class",
+]
diff --git a/lmcache/v1/gpu_connector/kv_format/contiguity.py b/lmcache/v1/gpu_connector/kv_format/contiguity.py
new file mode 100644
index 0000000..f5d0fa4
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/contiguity.py
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Contiguous-view recovery for raw engine KV caches.
+
+Metadata-only (zero-copy) preprocessing that makes a tensor's ``.shape``
+reflect its physical layout. Engine- and format-agnostic: ``detect_format``
+runs it before detection, and CUDA-IPC callers use it standalone.
+"""
+
+# mypy: disable-error-code="union-attr"
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache
+
+logger = init_logger(__name__)
+
+
+def attempt_permute_to_contiguous_view(
+    kv_caches: DiscoverableKVCache,
+) -> DiscoverableKVCache:
+    """Return a contiguous view of *kv_caches*, metadata-only (no copy).
+
+    For a tensor leaf: reorders the dims by stride magnitude so shape
+    lines up with a contiguous layout. For a list: recurses into each
+    element. Tensor leaves alias the input's storage; list nodes are
+    freshly allocated but hold the same tensor objects (or their
+    permuted views).
+
+    Recovers the vLLM HND case: tensors allocated physically as
+    ``[2, NB, NH, BS, HS]`` but exposed logically as
+    ``[2, NB, BS, NH, HS]`` via a dim permute. Sorting dims by stride
+    undoes the permute without touching storage.
+
+    For tensors that remain non-contiguous even after dim-permute
+    recovery (e.g. vLLM unified KV pool views where dim-0 has an
+    inflated periodic stride because every block slot is padded to a
+    model-wide maximum), this function returns the tensor unchanged.
+    Rationale: :class:`CudaIPCWrapper` transports ``(shape, stride,
+    storage_offset)`` verbatim and the receiver rebuilds the view via
+    ``torch.Tensor.set_(storage, offset, shape, stride)``, which
+    supports arbitrary strided views (including periodic-dim-0 and
+    ``as_strided``-produced layouts) and yields a bit-identical view.
+    Downstream consumers that rely on ``shape`` alone to infer the
+    physical layout must therefore also consult ``stride``.
+
+    We deliberately never fall back to ``.contiguous()`` (which would
+    allocate and copy), so the caller's zero-copy invariant is
+    preserved.
+    """
+    if isinstance(kv_caches, torch.Tensor):
+        if kv_caches.is_contiguous():
+            return kv_caches
+        strides = kv_caches.stride()
+        perm = sorted(range(kv_caches.ndim), key=lambda i: strides[i], reverse=True)
+        result = kv_caches.permute(perm)
+        if result.is_contiguous():
+            return result
+        padding_per_block = _validate_dim0_padded_layout(result)
+        logger.debug(
+            "attempt_permute_to_contiguous_view: accepting dim-0-padded "
+            "view; downstream kernels must honour block_stride_elems. "
+            "shape=%s, stride=%s, padding_per_block_elems=%d, "
+            "storage_nbytes=%s, dtype=%s",
+            tuple(result.shape),
+            tuple(result.stride()),
+            padding_per_block,
+            int(result.untyped_storage().nbytes()),
+            result.dtype,
+        )
+        return result
+    return [attempt_permute_to_contiguous_view(sub) for sub in kv_caches]
+
+
+def _validate_dim0_padded_layout(tensor: torch.Tensor) -> int:
+    """Validate that *tensor* matches the dim-0-padding-only strided layout.
+
+    Mainly used for DeepSeek V4 integration, where compressor / indexer
+    KV groups share a pool with larger attn groups and end up with
+    per-block dim-0 padding. The downstream KV transfer kernels only
+    honour this single non-contiguous shape (via
+    :class:`PageBufferShapeDesc.block_stride_elems`); any other strided
+    view would cause wrong reads/writes and is rejected here.
+
+    The accepted layout requires:
+
+    * ``stride[-1] == 1`` and ``stride[-2] == shape[-1]`` -- each block
+      row is internally tightly packed.
+    * Every interior dim ``i`` satisfies
+      ``stride[i] == prod(shape[i+1:])`` -- only dim-0 may carry
+      padding, with ``stride[0] >= prod(shape[1:])``.
+
+    Callers must pass the stride-sorted permuted view (not the original
+    tensor): for tensors that are both permuted and dim-0-padded, the
+    original's unsorted inner strides would falsely trip the tight-
+    packing check. ``permute`` shares storage and preserves
+    ``storage_offset``/``numel``/storage bytes, so those checks are
+    equivalent on either view.
+
+    Returns:
+        ``padding_per_block_elems`` (= ``stride[0] - prod(shape[1:])``).
+
+    Raises:
+        ValueError: *tensor* violates any of the invariants above.
+    """
+    shape = tuple(tensor.shape)
+    stride = tuple(tensor.stride())
+    ndim = tensor.ndim
+    storage_offset = int(tensor.storage_offset())
+
+    def _fail(reason: str) -> None:
+        raise ValueError(
+            "attempt_permute_to_contiguous_view: tensor is non-contiguous "
+            f"and not a supported (dim-0 padding only) layout -- {reason}. "
+            f"shape={shape}, stride={stride}, "
+            f"storage_offset={storage_offset}, numel={int(tensor.numel())}, "
+            f"storage_nbytes={int(tensor.untyped_storage().nbytes())}, "
+            f"dtype={tensor.dtype}. "
+            "Downstream KV transfer kernels only understand dim-0 "
+            "block-row padding; other strided views would produce "
+            "wrong reads/writes and are rejected."
+        )
+
+    if ndim < 2:
+        _fail("ndim < 2")
+    if stride[-1] != 1:
+        _fail("stride[-1] != 1 (inner dim not contiguous)")
+    if stride[-2] != shape[-1]:
+        _fail("stride[-2] != shape[-1] (last-two dims not tightly packed)")
+    inner_tight = 1
+    for i in range(ndim - 1, 0, -1):
+        if i < ndim - 1 and stride[i] != inner_tight:
+            _fail(
+                f"dim {i} stride {stride[i]} != tight {inner_tight} "
+                "(interior-dim padding is not supported)"
+            )
+        inner_tight *= shape[i]
+    if stride[0] < inner_tight:
+        _fail(
+            f"dim-0 stride {stride[0]} < prod(shape[1:])={inner_tight} "
+            "(overlapping blocks)"
+        )
+    return stride[0] - inner_tight
diff --git a/lmcache/v1/gpu_connector/kv_format/detection.py b/lmcache/v1/gpu_connector/kv_format/detection.py
new file mode 100644
index 0000000..d2576e1
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detection.py
@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Format detection orchestration for raw engine KV caches.
+
+``detect_format`` applies engine-agnostic contiguous-view recovery, then hands
+off to the engine's :class:`EngineDetector` to reshape and identify the format.
+"""
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format.contiguity import (
+    attempt_permute_to_contiguous_view,
+)
+from lmcache.v1.gpu_connector.kv_format.detectors import get_detector
+from lmcache.v1.gpu_connector.kv_format.specs import describe_shape
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache, LayoutHints
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+def detect_format(
+    kv_caches: DiscoverableKVCache,
+    serving_engine: EngineType,
+    layout_hints: "LayoutHints | None" = None,
+) -> "tuple[lmc_ops.EngineKVFormat, DiscoverableKVCache]":
+    """Recover a contiguous view, then discover the format + canonical kv_caches.
+
+    Returns ``(engine_kv_format, normalized_kv_caches)``. Callers must use the
+    returned structure -- it shares storage with the input but may be a
+    permuted/reshaped view.
+
+    Raises:
+        ValueError: If no detector exists for *serving_engine*, or the structure
+            matches no known format.
+    """
+    kv_caches = attempt_permute_to_contiguous_view(kv_caches)
+    detector = get_detector(serving_engine)
+    if detector is None:
+        raise ValueError(f"no KV cache detector for serving engine {serving_engine}")
+    engine_kv_format, kv_caches = detector.discover(kv_caches, layout_hints or {})
+    if engine_kv_format is None:
+        raise ValueError(f"unsupported kv_caches structure for {serving_engine}")
+    logger.info(
+        "Engine KV Format: %s %s", engine_kv_format, describe_shape(engine_kv_format)
+    )
+    return engine_kv_format, kv_caches
diff --git a/lmcache/v1/gpu_connector/kv_format/detectors/__init__.py b/lmcache/v1/gpu_connector/kv_format/detectors/__init__.py
new file mode 100644
index 0000000..1697554
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detectors/__init__.py
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-engine detectors.
+
+``base.py`` is the interface, ``<engine>.py`` are the per-engine
+implementations, and ``registry.py`` is the engine -> detector table.
+"""
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.detectors.registry import get_detector
+
+__all__ = ["get_detector"]
diff --git a/lmcache/v1/gpu_connector/kv_format/detectors/base.py b/lmcache/v1/gpu_connector/kv_format/detectors/base.py
new file mode 100644
index 0000000..81cd78f
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detectors/base.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-engine KV cache discovery interface.
+
+One :class:`EngineDetector` per serving engine reshapes a raw ``kv_caches`` into
+the canonical structure the specs expect and identifies its ``EngineKVFormat``,
+in a single step. The engine -> detector table is in ``registry.py``.
+"""
+
+# mypy: disable-error-code="union-attr"
+# Standard
+from abc import ABC, abstractmethod
+from typing import ClassVar, Optional
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache, LayoutHints
+import lmcache.c_ops as lmc_ops
+
+
+def measure_list_depth_until_tensor(
+    kv_caches: DiscoverableKVCache,
+) -> tuple[int, int, DiscoverableKVCache]:
+    """Return ``(list_depth, tensor_ndim, first_tensor)`` for *kv_caches*.
+
+    Descends the first element of each list down to the inner tensor, counting
+    the list-nesting depth on the way.
+    """
+    list_depth = 0
+    node = kv_caches
+    while isinstance(node, list):
+        if not node:
+            raise ValueError("encountered an empty kv_caches list")
+        list_depth += 1
+        node = node[0]
+    return list_depth, node.ndim, node
+
+
+class EngineDetector(ABC):
+    """Reshape + identify the ``EngineKVFormat`` for one serving engine."""
+
+    engine_type: ClassVar[EngineType]
+
+    @abstractmethod
+    def discover(
+        self, kv_caches: DiscoverableKVCache, layout_hints: LayoutHints
+    ) -> "tuple[Optional[lmc_ops.EngineKVFormat], DiscoverableKVCache]":
+        """Return ``(format, canonical_kv_caches)``, or ``(None, kv_caches)``.
+
+        Reshapes this engine's raw layout into the canonical structure the specs
+        expect, and identifies which ``EngineKVFormat`` it is (``None`` if the
+        structure is unrecognized).
+        """
diff --git a/lmcache/v1/gpu_connector/kv_format/detectors/registry.py b/lmcache/v1/gpu_connector/kv_format/detectors/registry.py
new file mode 100644
index 0000000..eed8478
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detectors/registry.py
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The serving-engine -> detector table, discovered from this folder.
+
+Every ``detectors/<engine>.py`` defines one :class:`EngineDetector` subclass.
+This imports them all and indexes each by the ``engine_type`` it declares, so
+adding an engine is just dropping a new file here -- nothing in this file
+changes.
+"""
+
+# Standard
+from pathlib import Path
+import importlib
+import pkgutil
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format.detectors.base import EngineDetector
+
+
+def _discover_detectors() -> dict[EngineType, type[EngineDetector]]:
+    """Import every detector module in this folder and index it by its engine."""
+    detectors: dict[EngineType, type[EngineDetector]] = {}
+    for module in pkgutil.iter_modules([str(Path(__file__).parent)]):
+        if module.name in ("base", "registry"):
+            continue
+        imported = importlib.import_module(f"{__package__}.{module.name}")
+        for value in vars(imported).values():
+            if (
+                isinstance(value, type)
+                and issubclass(value, EngineDetector)
+                and value is not EngineDetector
+            ):
+                detectors[value.engine_type] = value
+    return detectors
+
+
+DETECTORS = _discover_detectors()
+
+
+def get_detector(engine_type: EngineType) -> "EngineDetector | None":
+    """Return a detector instance for *engine_type*, or ``None`` if none exists."""
+    cls = DETECTORS.get(engine_type)
+    return cls() if cls is not None else None
diff --git a/lmcache/v1/gpu_connector/kv_format/detectors/sglang.py b/lmcache/v1/gpu_connector/kv_format/detectors/sglang.py
new file mode 100644
index 0000000..bbcd7a3
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detectors/sglang.py
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SGLang KV cache discovery."""
+
+# mypy: disable-error-code="union-attr"
+# Standard
+from typing import Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format.detectors.base import (
+    EngineDetector,
+    measure_list_depth_until_tensor,
+)
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache, LayoutHints
+import lmcache.c_ops as lmc_ops
+
+
+class SGLANG_Detector(EngineDetector):
+    engine_type = EngineType.SGLANG
+
+    def discover(
+        self, kv_caches: DiscoverableKVCache, layout_hints: LayoutHints
+    ) -> "tuple[Optional[lmc_ops.EngineKVFormat], DiscoverableKVCache]":
+        # MP path: a flat list[2*NL] of 3-D tensors (K layers then V layers)
+        # plus a tokens_per_block hint. Regroup into [K_layers, V_layers] and
+        # reshape each (PBS, NH, HS) -> (NB, BS, NH, HS).
+        if (
+            isinstance(kv_caches, list)
+            and len(kv_caches) > 0
+            and len(kv_caches) % 2 == 0
+            and isinstance(kv_caches[0], torch.Tensor)
+            and kv_caches[0].dim() == 3
+            and kv_caches[0].shape[1] > 1
+            and "tokens_per_block" in layout_hints
+        ):
+            block_size = layout_hints["tokens_per_block"]
+            half = len(kv_caches) // 2
+            regrouped: list[DiscoverableKVCache] = []
+            for layers in (kv_caches[:half], kv_caches[half:]):
+                reshaped: list[DiscoverableKVCache] = []
+                for layer in layers:
+                    page_buffer_size = layer.shape[0]
+                    if page_buffer_size % block_size != 0:
+                        raise ValueError(
+                            f"SGLang page_buffer_size {page_buffer_size} not "
+                            f"divisible by tokens_per_block {block_size}"
+                        )
+                    num_blocks = page_buffer_size // block_size
+                    reshaped.append(
+                        layer.view(num_blocks, block_size, *layer.shape[1:])
+                    )
+                regrouped.append(reshaped)
+            kv_caches = regrouped
+
+        list_depth, tensor_ndim, first_tensor = measure_list_depth_until_tensor(
+            kv_caches
+        )
+        if list_depth == 1 and first_tensor.shape[1] == 1:  # MLA, fused PBS
+            return lmc_ops.EngineKVFormat.NL_X_NBBS_ONE_HS, kv_caches
+        if list_depth == 2:
+            if tensor_ndim == 4:  # MP daemon: NB/BS split into separate axes
+                return lmc_ops.EngineKVFormat.TWO_X_NL_X_NB_BS_NH_HS, kv_caches
+            return lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS, kv_caches
+        return None, kv_caches
diff --git a/lmcache/v1/gpu_connector/kv_format/detectors/trtllm.py b/lmcache/v1/gpu_connector/kv_format/detectors/trtllm.py
new file mode 100644
index 0000000..1e5ca53
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detectors/trtllm.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""TRT-LLM KV cache discovery."""
+
+# mypy: disable-error-code="union-attr"
+# Standard
+from typing import Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format.detectors.base import (
+    EngineDetector,
+    measure_list_depth_until_tensor,
+)
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache, LayoutHints
+import lmcache.c_ops as lmc_ops
+
+
+class TRTLLM_Detector(EngineDetector):
+    engine_type = EngineType.TRTLLM
+
+    def discover(
+        self, kv_caches: DiscoverableKVCache, layout_hints: LayoutHints
+    ) -> "tuple[Optional[lmc_ops.EngineKVFormat], DiscoverableKVCache]":
+        # TRT-LLM hands a 4-D pool tensor (maybe wrapped in a 1-element list);
+        # reshape its fused trailing dim into the canonical 6-D cross-layer form
+        # [NB, NL, 2, num_kv_heads, tokens_per_block, head_dim].
+        if isinstance(kv_caches, list) and len(kv_caches) == 1:
+            kv_caches = kv_caches[0]
+        if isinstance(kv_caches, torch.Tensor) and kv_caches.dim() == 4:
+            num_kv_heads = layout_hints.get("num_kv_heads")
+            tokens_per_block = layout_hints.get("tokens_per_block")
+            head_dim = layout_hints.get("head_dim")
+            if num_kv_heads is None or tokens_per_block is None or head_dim is None:
+                raise ValueError(
+                    "TRT-LLM discovery needs layout_hints with "
+                    "num_kv_heads, tokens_per_block, head_dim"
+                )
+            num_blocks, num_layers, kv_size, flat = kv_caches.shape
+            if flat != num_kv_heads * tokens_per_block * head_dim:
+                raise ValueError(
+                    f"TRT-LLM 4-D flat dim {flat} != num_kv_heads ({num_kv_heads}) "
+                    f"* tokens_per_block ({tokens_per_block}) * head_dim ({head_dim})"
+                )
+            kv_caches = kv_caches.view(
+                num_blocks,
+                num_layers,
+                kv_size,
+                num_kv_heads,
+                tokens_per_block,
+                head_dim,
+            )
+
+        list_depth, tensor_ndim, _first_tensor = measure_list_depth_until_tensor(
+            kv_caches
+        )
+        if list_depth == 0 and tensor_ndim == 6:
+            return lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS, kv_caches
+        return None, kv_caches
diff --git a/lmcache/v1/gpu_connector/kv_format/detectors/vllm.py b/lmcache/v1/gpu_connector/kv_format/detectors/vllm.py
new file mode 100644
index 0000000..db42022
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/detectors/vllm.py
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+"""vLLM KV cache discovery."""
+
+# mypy: disable-error-code="union-attr"
+# Standard
+from typing import Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format.detectors.base import (
+    EngineDetector,
+    measure_list_depth_until_tensor,
+)
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache, LayoutHints
+import lmcache.c_ops as lmc_ops
+
+
+class VLLM_Detector(EngineDetector):
+    engine_type = EngineType.VLLM
+
+    def discover(
+        self, kv_caches: DiscoverableKVCache, layout_hints: LayoutHints
+    ) -> "tuple[Optional[lmc_ops.EngineKVFormat], DiscoverableKVCache]":
+        # Blocks-first fused K/V is the only rank-4 vLLM layout, so its raw rank
+        # identifies it unambiguously (the post-split 5-D shape would collide
+        # with flash-infer when num_heads == 2). Split [NB, NH, BS, 2*HS] into
+        # [NB, NH, BS, 2, HS].
+        if (
+            isinstance(kv_caches, list)
+            and kv_caches
+            and isinstance(kv_caches[0], torch.Tensor)
+            and kv_caches[0].dim() == 4
+        ):
+            fused_dim = kv_caches[0].shape[3]
+            if fused_dim % 2 != 0:
+                raise ValueError(
+                    f"blocks-first fused trailing dim {fused_dim} is not 2 * head_size"
+                )
+            split = [t.reshape(*t.shape[:3], 2, fused_dim // 2) for t in kv_caches]
+            return lmc_ops.EngineKVFormat.NL_X_NB_NH_BS_TWO_HS, split
+
+        list_depth, tensor_ndim, first_tensor = measure_list_depth_until_tensor(
+            kv_caches
+        )
+
+        # vLLM's CPU attention backend stores KV in HND but misreports it, so
+        # force HND there; otherwise honor the hint, defaulting to NHD.
+        kv_layout = layout_hints.get("kv_layout")
+        if torch_device_type == "cpu":
+            kv_layout = "HND"
+        elif kv_layout is None:
+            kv_layout = "NHD"
+        is_hnd = kv_layout == "HND"
+
+        if list_depth == 0:
+            return lmc_ops.EngineKVFormat.NB_NL_TWO_BS_NH_HS, kv_caches
+        if list_depth == 1 and tensor_ndim == 5:
+            if first_tensor.shape[0] == 2:  # K/V axis first
+                if is_hnd:
+                    return lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS, kv_caches
+                return lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS, kv_caches
+            if first_tensor.shape[1] == 2:  # num_blocks first
+                if is_hnd:
+                    return lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS, kv_caches
+                return lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS, kv_caches
+        if list_depth == 1 and tensor_ndim == 3:  # MLA
+            return lmc_ops.EngineKVFormat.NL_X_NB_BS_HS, kv_caches
+        return None, kv_caches
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/__init__.py b/lmcache/v1/gpu_connector/kv_format/specs/__init__.py
new file mode 100644
index 0000000..cad8fb5
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/__init__.py
@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+"""KVFormatSpec geometry layer.
+
+``base.py`` is the interface + shape rendering, ``<engine_kv_format>.py`` are
+the per-format implementations, and ``registry.py`` is the format -> spec table.
+"""
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import (
+    KVFormatSpec,
+    concrete_shape,
+    describe_shape,
+)
+from lmcache.v1.gpu_connector.kv_format.specs.registry import get_spec, get_spec_class
+
+__all__ = [
+    "KVFormatSpec",
+    "concrete_shape",
+    "describe_shape",
+    "get_spec",
+    "get_spec_class",
+]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/base.py b/lmcache/v1/gpu_connector/kv_format/specs/base.py
new file mode 100644
index 0000000..500c040
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/base.py
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-format geometry interface for GPU KV caches.
+
+Each :class:`KVFormatSpec` holds the geometry accessors for one
+``EngineKVFormat`` -- methods that read shape off a normalized ``kv_caches``.
+The format's static facts (MLA and the structural shape) live on the
+``EngineKVFormat`` enum itself (``csrc/engine_kv_format.h``, read via
+``lmc_ops``), shared with the device kernels. The enum is the single source of
+truth for which formats exist; engine identity lives only in detection. The
+format -> spec table is in ``registry.py``.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import ClassVar
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache
+import lmcache.c_ops as lmc_ops
+
+# A format's enum name *is* its shape: ``_``-joined tokens, with ``X`` marking a
+# list level. ``TWO_X_NL_X_NBBS_NH_HS`` reads as ``2 x NL x [PBS, NH, HS]``.
+# describe_shape and concrete_shape both render from it, so they can never drift.
+_LABELS = {
+    "ONE": "1",
+    "TWO": "2",
+    "NBBS": "PBS",
+    "NB": "NB",
+    "NL": "NL",
+    "BS": "BS",
+    "NH": "NH",
+    "HS": "HS",
+}
+_ACCESSORS = {
+    "NB": "num_blocks",
+    "NL": "num_layers",
+    "BS": "block_size",
+    "NH": "num_heads",
+    "HS": "head_size",
+    "PBS": "page_buffer_size",
+}
+
+
+def _render_shape(fmt: "lmc_ops.EngineKVFormat", token: Callable[[str], str]) -> str:
+    *lists, inner = fmt.name.split("_X_")
+    body = ", ".join(token(t) for t in inner.split("_"))
+    return " x ".join([token(t) for t in lists] + [f"[{body}]"])
+
+
+def describe_shape(fmt: "lmc_ops.EngineKVFormat") -> str:
+    """Symbolic shape of a format, e.g. ``NL_X_NB_BS_HS`` -> ``NL x [NB, BS, HS]``.
+
+    Named ``describe_shape`` (not ``shape_desc``) to avoid confusion with the
+    unrelated :class:`lmc_ops.PageBufferShapeDesc` and its ``shape_desc``
+    instances used on the transfer path.
+    """
+    return _render_shape(fmt, lambda t: _LABELS[t])
+
+
+def concrete_shape(fmt: "lmc_ops.EngineKVFormat", size: Callable[[str], int]) -> str:
+    """Numeric shape of a format; ``size(label)`` gives each axis's dimension.
+
+    E.g. ``NL_X_TWO_NB_BS_NH_HS`` with ``NL=32, NB=2048, BS=16, NH=8, HS=128``
+    -> ``32 x [2, 2048, 16, 8, 128]``.
+    """
+    return _render_shape(
+        fmt, lambda t: _LABELS[t] if t in ("ONE", "TWO") else str(size(_LABELS[t]))
+    )
+
+
+class KVFormatSpec(ABC):
+    """Pure geometry accessors for one ``EngineKVFormat``.
+
+    Wraps an already-normalized ``kv_caches`` (from ``detect_format``) and
+    answers geometry questions about it. Layout only -- no engine identity,
+    since one format may come from many (engine, backend) pairs.
+
+    Class attributes: ``engine_kv_format`` (the format this describes, its
+    identity) and ``attention_backends`` (diagnostic labels; first is the
+    representative). The format's static facts -- ``is_mla`` and the structural
+    shape ``is_cross_layer`` / ``is_kv_list`` / ``is_layer_list`` -- live on the
+    ``EngineKVFormat`` itself (``csrc/engine_kv_format.h``, read via ``lmc_ops``),
+    shared with the device kernels.
+
+    Method usage by mode -- every spec is consumed through the ``get_*``
+    facade in ``gpu_connector.utils``:
+
+    * Used by **both** MP (multiprocess) and non-MP (in-process) connectors:
+      :meth:`num_layers`, :meth:`num_blocks`, :meth:`block_size`,
+      :meth:`num_heads`, :meth:`hidden_dim`, :meth:`head_size`, :meth:`dtype`,
+      :meth:`data_ptrs`.
+    * Used by **non-MP only** (the legacy in-process GPU/XPU/HPU/MUSA
+      connectors, none of the MP transfer path): :meth:`page_buffer_size`,
+      :meth:`tokens_per_layer`, :meth:`elements_per_layer`. The MP path derives
+      these from a per-group :class:`PageBufferShapeDesc` instead.
+
+    Lifetime: a spec **borrows** ``kv_caches`` -- it does not own the GPU KV
+    tensors. ``get_spec`` builds a fresh instance per call and callers use it
+    transiently (``get_spec(...).num_layers()``), so the borrowed reference is
+    released as soon as the spec is dropped. Never cache a spec on a long-lived
+    object: that would keep the engine's GPU KV tensors alive past disconnect.
+    """
+
+    engine_kv_format: ClassVar["lmc_ops.EngineKVFormat"]
+    attention_backends: ClassVar[tuple[str, ...]] = ()
+
+    def __init__(self, kv_caches: DiscoverableKVCache) -> None:
+        # Borrowed, not owned: see the class docstring's "Lifetime" note. The
+        # spec must stay transient so it never outlives the engine's KV tensors.
+        self.kv_caches = kv_caches
+
+    @abstractmethod
+    def num_layers(self) -> int:
+        """Return the number of transformer layers."""
+
+    @abstractmethod
+    def num_blocks(self) -> int:
+        """Return the number of paged blocks (raises for NBBS-fused formats)."""
+
+    @abstractmethod
+    def block_size(self, layer_idx: int = 0) -> int:
+        """Return the block size (tokens per block; raises for NBBS-fused)."""
+
+    @abstractmethod
+    def page_buffer_size(self) -> int:
+        """Return ``num_blocks * block_size`` (or the fused PBS axis).
+
+        Non-MP only (see the class docstring).
+        """
+
+    @abstractmethod
+    def num_heads(self, layer_idx: int = 0) -> int:
+        """Return the number of KV heads for ``layer_idx`` (1 for MLA)."""
+
+    @abstractmethod
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        """Return the hidden dimension (``num_heads * head_size``) for a layer."""
+
+    @abstractmethod
+    def head_size(self, layer_idx: int = 0) -> int:
+        """Return the per-head dimension for ``layer_idx``."""
+
+    @abstractmethod
+    def tokens_per_layer(self) -> int:
+        """Return the token capacity per layer (``num_blocks * block_size``).
+
+        Non-MP only (see the class docstring).
+        """
+
+    @abstractmethod
+    def elements_per_layer(self) -> int:
+        """Return the element count per layer (both K and V for non-MLA).
+
+        Non-MP only (see the class docstring).
+        """
+
+    @abstractmethod
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        """Return the tensor dtype for ``layer_idx``."""
+
+    @abstractmethod
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        """Return device pointers for ``layer_indices`` in kernel-expected order.
+
+        Per-layer formats: one pointer per layer. SGLang two-list MHA: all K
+        pointers then all V. Cross-layer: a single base pointer (the kernel
+        walks layers itself, so ``layer_indices`` is ignored).
+        """
+
+    def concrete_shape_str(self) -> str:
+        """``describe_shape`` with real dims, e.g. ``80 x [2, 2048, 128, 8, 128]``."""
+        return concrete_shape(
+            self.engine_kv_format, lambda label: getattr(self, _ACCESSORS[label])()
+        )
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nb_nl_two_bs_nh_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nb_nl_two_bs_nh_hs.py
new file mode 100644
index 0000000..d8794da
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nb_nl_two_bs_nh_hs.py
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cross-layer, NHD: a single bare tensor ``[NB, NL, 2, BS, NH, HS]``.
+
+All layers are packed along dim-1. Produced e.g. by vLLM CROSS_LAYER.
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NB_NL_TWO_BS_NH_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NB_NL_TWO_BS_NH_HS
+    attention_backends = ("vLLM CROSS_LAYER",)
+
+    def num_layers(self) -> int:
+        return self.kv_caches.shape[1]
+
+    def num_blocks(self) -> int:
+        return self.kv_caches.shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[3]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches.shape[0] * self.kv_caches.shape[3]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[4]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[4] * self.kv_caches.shape[5]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[5]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches.shape[0] * self.kv_caches.shape[3]
+
+    def elements_per_layer(self) -> int:
+        t = self.kv_caches
+        return t.shape[0] * 2 * t.shape[3] * t.shape[4] * t.shape[5]
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches.dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        tensor = cast(torch.Tensor, self.kv_caches)
+        return [tensor.data_ptr()]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nb_nl_two_nh_bs_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nb_nl_two_nh_bs_hs.py
new file mode 100644
index 0000000..f1d07be
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nb_nl_two_nh_bs_hs.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cross-layer, HND: a single bare tensor ``[NB, NL, 2, NH, BS, HS]``.
+
+All layers are packed along dim-1, heads before block-size. Produced e.g. by
+TRT-LLM.
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NB_NL_TWO_NH_BS_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS
+    attention_backends = ("TRT-LLM cross-layer (HND layout)",)
+
+    def num_layers(self) -> int:
+        return self.kv_caches.shape[1]
+
+    def num_blocks(self) -> int:
+        return self.kv_caches.shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[4]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches.shape[0] * self.kv_caches.shape[4]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[3]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[3] * self.kv_caches.shape[5]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches.shape[5]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches.shape[0] * self.kv_caches.shape[4]
+
+    def elements_per_layer(self) -> int:
+        t = self.kv_caches
+        return t.shape[0] * 2 * t.shape[3] * t.shape[4] * t.shape[5]
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches.dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        tensor = cast(torch.Tensor, self.kv_caches)
+        return [tensor.data_ptr()]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_bs_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_bs_hs.py
new file mode 100644
index 0000000..1caddfd
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_bs_hs.py
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer MLA: ``NL x [NB, BS, HS]`` (e.g. vLLM MLA).
+
+A ``list[NL]`` of a 3-D tensor; K and V share one latent (``num_heads == 1``).
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_NB_BS_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    attention_backends = ("vLLM MLA",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0].shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[1]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[0] * self.kv_caches[0].shape[1]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return 1
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches[0].shape[0] * self.kv_caches[0].shape[1]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0].numel()
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_nh_bs_two_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_nh_bs_two_hs.py
new file mode 100644
index 0000000..b6d92ee
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_nh_bs_two_hs.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer, HND, blocks-first with fused K/V: ``NL x [NB, NH, BS, 2, HS]``.
+
+A ``list[NL]`` of a 5-D tensor whose K/V (size-2) axis is second-to-last.
+The engine registers it raw as 4-D ``[NB, NH, BS, 2*HS]`` (K/V fused into the
+trailing dim); detection splits that into this canonical 5-D shape. Produced
+by vLLM's non-MLA blocks-first CPU attention backend.
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_NB_NH_BS_TWO_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_NB_NH_BS_TWO_HS
+    attention_backends = ("vLLM non-MLA blocks-first, fused K/V",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0].shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[0] * self.kv_caches[0].shape[2]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[1]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        t = self.kv_caches[layer_idx]
+        return t.shape[1] * t.shape[4]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[4]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches[0].shape[0] * self.kv_caches[0].shape[2]
+
+    def elements_per_layer(self) -> int:
+        t = self.kv_caches[0]
+        return t.shape[0] * t.shape[1] * t.shape[2] * t.shape[4] * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_two_bs_nh_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_two_bs_nh_hs.py
new file mode 100644
index 0000000..f3ce08d
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_two_bs_nh_hs.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer, NHD, num_blocks first: ``NL x [NB, 2, BS, NH, HS]``.
+
+A ``list[NL]`` of a 5-D tensor whose leading axis is num_blocks, with the K/V
+(size-2) axis following. Produced e.g. by vLLM non-MLA flash infer.
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_NB_TWO_BS_NH_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS
+    attention_backends = ("vLLM non-MLA flash infer",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0].shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[0] * self.kv_caches[0].shape[2]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[3]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        t = self.kv_caches[layer_idx]
+        return t.shape[3] * t.shape[4]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[4]
+
+    def tokens_per_layer(self) -> int:
+        k = self.kv_caches[0][:, 0].shape
+        return k[0] * k[1]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0][:, 0].shape.numel() * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_two_nh_bs_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_two_nh_bs_hs.py
new file mode 100644
index 0000000..581a708
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nb_two_nh_bs_hs.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer, HND, num_blocks first: ``NL x [NB, 2, NH, BS, HS]``.
+
+A ``list[NL]`` of a 5-D tensor whose leading axis is num_blocks, the K/V
+(size-2) axis following, heads before block-size. Produced e.g. by vLLM
+non-MLA flash infer (HND).
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_NB_TWO_NH_BS_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS
+    attention_backends = ("vLLM non-MLA flash infer (HND layout)",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0].shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[3]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[0] * self.kv_caches[0].shape[3]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        t = self.kv_caches[layer_idx]
+        return t.shape[2] * t.shape[4]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[4]
+
+    def tokens_per_layer(self) -> int:
+        k = self.kv_caches[0][:, 0].shape
+        return k[0] * k[2]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0][:, 0].shape.numel() * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nbbs_one_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nbbs_one_hs.py
new file mode 100644
index 0000000..57adc35
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_nbbs_one_hs.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer MLA, fused PBS: ``NL x [PBS, 1, HS]`` (e.g. SGLang MLA).
+
+A ``list[NL]`` of a 3-D tensor with a singleton head axis; num_blocks*block_size
+is folded into the first axis (so num_blocks/block_size are absent).
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_NBBS_ONE_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_NBBS_ONE_HS
+    attention_backends = ("SGLang MLA",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        raise ValueError(
+            f"num_blocks is undefined for the fused format {self.engine_kv_format}"
+        )
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        raise ValueError(
+            f"block_size is undefined for the fused format {self.engine_kv_format}"
+        )
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[0]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[1]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches[0].shape[0]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0].numel()
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_two_nb_bs_nh_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_two_nb_bs_nh_hs.py
new file mode 100644
index 0000000..e7c7fde
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_two_nb_bs_nh_hs.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer, NHD, K/V-axis first: ``NL x [2, NB, BS, NH, HS]``.
+
+A ``list[NL]`` of a 5-D tensor whose leading axis is the K/V (size-2) axis.
+Produced e.g. by vLLM non-MLA flash attention.
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_TWO_NB_BS_NH_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    attention_backends = ("vLLM non-MLA flash attention",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0].shape[1]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[1] * self.kv_caches[0].shape[2]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[3]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        t = self.kv_caches[layer_idx]
+        return t.shape[3] * t.shape[4]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[4]
+
+    def tokens_per_layer(self) -> int:
+        k = self.kv_caches[0][0].shape
+        return k[0] * k[1]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0][0].shape.numel() * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/nl_x_two_nb_nh_bs_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_two_nb_nh_bs_hs.py
new file mode 100644
index 0000000..56e7a6a
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/nl_x_two_nb_nh_bs_hs.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-layer, HND, K/V-axis first: ``NL x [2, NB, NH, BS, HS]``.
+
+A ``list[NL]`` of a 5-D tensor whose leading axis is the K/V (size-2) axis,
+heads before block-size. Produced e.g. by vLLM non-MLA flash attention (HND).
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class NL_X_TWO_NB_NH_BS_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS
+    attention_backends = ("vLLM non-MLA flash attention (HND layout)",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches)
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0].shape[1]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[3]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0].shape[1] * self.kv_caches[0].shape[3]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[2]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        t = self.kv_caches[layer_idx]
+        return t.shape[2] * t.shape[4]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[layer_idx].shape[4]
+
+    def tokens_per_layer(self) -> int:
+        k = self.kv_caches[0][0].shape
+        return k[0] * k[2]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0][0].shape.numel() * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        layers = cast(list[torch.Tensor], self.kv_caches)
+        return [layers[i].data_ptr() for i in layer_indices]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/registry.py b/lmcache/v1/gpu_connector/kv_format/specs/registry.py
new file mode 100644
index 0000000..a6da71b
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/registry.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The ``EngineKVFormat`` -> spec table, discovered from this folder.
+
+Every ``specs/<engine_kv_format>.py`` defines one :class:`KVFormatSpec`
+subclass. This imports them all and indexes each by the ``engine_kv_format`` it
+declares, so adding a format is just dropping a new file here -- nothing in this
+file changes.
+"""
+
+# Standard
+from pathlib import Path
+import importlib
+import pkgutil
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache
+import lmcache.c_ops as lmc_ops
+
+
+def _discover_specs() -> dict["lmc_ops.EngineKVFormat", type[KVFormatSpec]]:
+    """Import every spec module in this folder and index it by its format."""
+    specs: dict["lmc_ops.EngineKVFormat", type[KVFormatSpec]] = {}
+    for module in pkgutil.iter_modules([str(Path(__file__).parent)]):
+        if module.name in ("base", "registry"):
+            continue
+        imported = importlib.import_module(f"{__package__}.{module.name}")
+        for value in vars(imported).values():
+            if (
+                isinstance(value, type)
+                and issubclass(value, KVFormatSpec)
+                and value is not KVFormatSpec
+            ):
+                specs[value.engine_kv_format] = value
+    return specs
+
+
+SPECS = _discover_specs()
+
+
+def get_spec_class(fmt: "lmc_ops.EngineKVFormat") -> type[KVFormatSpec]:
+    """Return the spec class for *fmt*, for static facts (``is_mla``, ...).
+
+    Raises:
+        ValueError: If *fmt* has no spec.
+    """
+    if fmt not in SPECS:
+        raise ValueError(f"Unknown Engine KV Format: {fmt}")
+    return SPECS[fmt]
+
+
+def get_spec(
+    kv_caches: DiscoverableKVCache, fmt: "lmc_ops.EngineKVFormat"
+) -> KVFormatSpec:
+    """Return a spec instance wrapping *kv_caches* of *fmt*."""
+    return get_spec_class(fmt)(kv_caches)
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/two_x_nl_x_nb_bs_nh_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/two_x_nl_x_nb_bs_nh_hs.py
new file mode 100644
index 0000000..675524e
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/two_x_nl_x_nb_bs_nh_hs.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Two-list MHA, split NB/BS: ``2 x NL x [NB, BS, NH, HS]`` (SGLang MP daemon).
+
+``[K_layers, V_layers]``, each a ``list[NL]`` of a 4-D tensor that keeps
+num_blocks and block_size as separate axes.
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class TWO_X_NL_X_NB_BS_NH_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.TWO_X_NL_X_NB_BS_NH_HS
+    attention_backends = ("SGLang MHA via MP daemon (4-D inner)",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches[0])
+
+    def num_blocks(self) -> int:
+        return self.kv_caches[0][0].shape[0]
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[0][0].shape[1]
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0][0].shape[0] * self.kv_caches[0][0].shape[1]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[0][layer_idx].shape[2]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        inner = self.kv_caches[0][layer_idx]
+        return inner.shape[2] * inner.shape[3]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[0][layer_idx].shape[-1]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches[0][0].shape[0] * self.kv_caches[0][0].shape[1]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0][0].numel() * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[0][layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        k, v = cast(list[list[torch.Tensor]], self.kv_caches)
+        return [k[i].data_ptr() for i in layer_indices] + [
+            v[i].data_ptr() for i in layer_indices
+        ]
diff --git a/lmcache/v1/gpu_connector/kv_format/specs/two_x_nl_x_nbbs_nh_hs.py b/lmcache/v1/gpu_connector/kv_format/specs/two_x_nl_x_nbbs_nh_hs.py
new file mode 100644
index 0000000..79ae735
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/specs/two_x_nl_x_nbbs_nh_hs.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Two-list MHA, fused PBS: ``2 x NL x [PBS, NH, HS]`` (e.g. SGLang MHA).
+
+``[K_layers, V_layers]``, each a ``list[NL]`` of a 3-D tensor that folds
+num_blocks*block_size into one PBS axis (so num_blocks/block_size are absent).
+"""
+
+# Each spec indexes ``kv_caches`` (Tensor | nested list) per its format, so the
+# ``.shape`` / ``[...]`` access is well-defined though mypy cannot prove it.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from typing import cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.specs.base import KVFormatSpec
+import lmcache.c_ops as lmc_ops
+
+
+class TWO_X_NL_X_NBBS_NH_HS_Spec(KVFormatSpec):
+    engine_kv_format = lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS
+    attention_backends = ("SGLang MHA (flash attention and flash infer)",)
+
+    def num_layers(self) -> int:
+        return len(self.kv_caches[0])
+
+    def num_blocks(self) -> int:
+        raise ValueError(
+            f"num_blocks is undefined for the fused format {self.engine_kv_format}"
+        )
+
+    def block_size(self, layer_idx: int = 0) -> int:
+        raise ValueError(
+            f"block_size is undefined for the fused format {self.engine_kv_format}"
+        )
+
+    def page_buffer_size(self) -> int:
+        return self.kv_caches[0][0].shape[0]
+
+    def num_heads(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[0][layer_idx].shape[1]
+
+    def hidden_dim(self, layer_idx: int = 0) -> int:
+        inner = self.kv_caches[0][layer_idx]
+        return inner.shape[1] * inner.shape[2]
+
+    def head_size(self, layer_idx: int = 0) -> int:
+        return self.kv_caches[0][layer_idx].shape[-1]
+
+    def tokens_per_layer(self) -> int:
+        return self.kv_caches[0][0].shape[0]
+
+    def elements_per_layer(self) -> int:
+        return self.kv_caches[0][0].numel() * 2
+
+    def dtype(self, layer_idx: int = 0) -> torch.dtype:
+        return self.kv_caches[0][layer_idx].dtype
+
+    def data_ptrs(self, layer_indices: list[int]) -> list[int]:
+        k, v = cast(list[list[torch.Tensor]], self.kv_caches)
+        return [k[i].data_ptr() for i in layer_indices] + [
+            v[i].data_ptr() for i in layer_indices
+        ]
diff --git a/lmcache/v1/gpu_connector/kv_format/types.py b/lmcache/v1/gpu_connector/kv_format/types.py
new file mode 100644
index 0000000..6b7cd95
--- /dev/null
+++ b/lmcache/v1/gpu_connector/kv_format/types.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Foundational types for the KV-cache format layer.
+
+``DiscoverableKVCache`` is the canonical KV-cache structure every ``kv_format``
+module operates on; ``LayoutHints`` carries the engine-supplied registration
+hints. The ``utils.py`` facade re-exports both for backward-compatible call
+sites.
+"""
+
+# Standard
+from typing import Literal, TypedDict, Union
+
+# Third Party
+import torch
+
+# Canonical recursive type consumed by ``detect_format`` and the
+# downstream format-aware helpers. A value is either a single
+# :class:`torch.Tensor` (e.g. vLLM cross-layer, TRT-LLM) or a list of
+# nested ``DiscoverableKVCache`` values (per-layer lists, SGLang's
+# two-list MHA, deeper nesting). Engine adapters that hand us other
+# containers (e.g. vLLM's ``dict[str, torch.Tensor]``) are responsible
+# for unwrapping to this form before calling the helpers.
+DiscoverableKVCache = Union[torch.Tensor, list["DiscoverableKVCache"]]
+
+
+class LayoutHints(TypedDict, total=False):
+    """Hints passed from a serving engine to LMCache during KV cache
+    registration (``REGISTER_KV_CACHE``).
+
+    Serving engines may pass a plain ``dict`` that satisfies this
+    schema -- importing this type is optional.
+
+    Keys:
+        kv_layout: Physical ordering of the KV cache dimensions.
+            ``"NHD"`` -- heads after block-size (default for most
+            vLLM builds).
+            ``"HND"`` -- heads before block-size (``VLLM_KV_CACHE_LAYOUT=HND``).
+        num_kv_heads: Number of KV heads per layer. Used by TRT-LLM to
+            reshape its 4-D pool tensor into the canonical 6-D form.
+        tokens_per_block: Tokens per paged block. Used by TRT-LLM (to
+            reshape its pool tensor) and by SGLang MHA (to split the
+            folded ``page_buffer_size`` dimension into separate
+            ``num_blocks`` and ``block_size``). Presence of this field
+            on a SGLang registration is what triggers the daemon-side
+            depth-1 -> depth-2 un-flatten + 3-D -> 4-D reshape.
+        head_dim: Per-head dimension. Used by TRT-LLM (same).
+    """
+
+    kv_layout: Literal["NHD", "HND"]
+    num_kv_heads: int
+    tokens_per_block: int
+    head_dim: int
diff --git a/lmcache/v1/gpu_connector/mock_gpu_connector.py b/lmcache/v1/gpu_connector/mock_gpu_connector.py
new file mode 100644
index 0000000..cf45379
--- /dev/null
+++ b/lmcache/v1/gpu_connector/mock_gpu_connector.py
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Mock GPU connector for testing and standalone mode without real GPU."""
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector import GPUConnectorInterface
+
+
+class MockGPUConnector(GPUConnectorInterface):
+    """Mock GPU connector for testing without real GPU.
+
+    This connector provides a no-op implementation of GPUConnectorInterface
+    that can be used in standalone mode or testing environments where no
+    actual GPU operations are needed.
+    """
+
+    def __init__(self, kv_shape: tuple):
+        """Initialize mock GPU connector.
+
+        Args:
+            kv_shape: KV cache shape tuple (num_layers, kv_dim,
+            num_blocks, num_heads, head_size)
+        """
+        self.kv_shape = kv_shape
+        self.num_layers = kv_shape[0]
+        self.stored_data: dict = {}
+        self.kvcaches = None
+
+    def from_gpu(self, memory_obj, start: int, end: int, **kwargs):
+        """Mock from_gpu operation."""
+        pass
+
+    def to_gpu(self, memory_obj, start: int, end: int, **kwargs):
+        """Mock to_gpu operation."""
+        pass
+
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        """Mock batched_from_gpu operation."""
+        pass
+
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        """Mock batched_to_gpu operation."""
+        pass
+
+    def get_shape(self, num_tokens=None):
+        """Mock get_shape operation.
+
+        Returns the shape based on the initialized kv_shape.
+        """
+        if num_tokens is None:
+            num_tokens = self.kv_shape[2]
+        return torch.Size(
+            [
+                self.num_layers,
+                self.kv_shape[1],
+                num_tokens,
+                self.kv_shape[3],
+                self.kv_shape[4],
+            ]
+        )
+
+    def initialize_kvcaches_ptr(self, **kwargs):
+        """Initialize the kvcaches pointers if not already initialized."""
+        if "kvcaches" in kwargs:
+            self.kvcaches = kwargs["kvcaches"]
diff --git a/lmcache/v1/gpu_connector/musa_connectors.py b/lmcache/v1/gpu_connector/musa_connectors.py
new file mode 100644
index 0000000..30ee98e
--- /dev/null
+++ b/lmcache/v1/gpu_connector/musa_connectors.py
@@ -0,0 +1,834 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Generator, List, Optional, Union, cast
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.gpu_connectors import (
+    GPUConnectorInterface,
+    VLLMPagedMemGPUConnectorV2,
+)
+from lmcache.v1.gpu_connector.utils import (
+    DiscoverableKVCache,
+    LayoutHints,
+    _get_head_size_view,
+    _split_token2d_kv,
+    get_block_size,
+    get_dtype,
+    get_head_size,
+    get_hidden_dim_size,
+    get_num_blocks,
+    get_num_heads,
+    get_num_layers,
+    get_page_buffer_size,
+    is_mla,
+    normalize_kv_and_discover_format,
+)
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.platform.musa.native_kv_transfer import (
+    try_native_from_gpu,
+    try_native_to_gpu,
+)
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+_SUPPORTED_MUSA_KV_FORMATS = (
+    lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+    lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+)
+
+ALLOWED_FORMAT_TRANSITIONS = {
+    (None, MemoryFormat.KV_MLA_FMT),
+    (MemoryFormat.KV_MLA_FMT, MemoryFormat.KV_MLA_FMT),
+    (MemoryFormat.KV_T2D, MemoryFormat.KV_MLA_FMT),
+}
+
+
+class VLLMPagedMemMUSAConnectorV2(VLLMPagedMemGPUConnectorV2):
+    """Non-layerwise paged KV connector for MUSA devices.
+
+    Follows the same contract as VLLMPagedMemXPUConnectorV2: pure torch ops
+    (index_copy_ / index_select) with ``torch.musa`` stream and sync APIs.
+
+    Supported paged KV cache layouts:
+      - Non-MLA vLLM flash-attention layout:
+        ``NL x [2, NB, BS, NH, HS]`` with LMCache ``KV_2LTD`` memory shaped
+        ``[2, NL, T, NH * HS]``.
+      - MLA vLLM layout:
+        ``NL x [NB, BS, HS]`` with LMCache ``KV_MLA_FMT`` memory shaped
+        ``[1, NL, T, HS]``.
+
+    Other vLLM layouts, including flash-infer, HND, cross-layer, connector
+    v3, and MP GPU-transfer kernel layouts, are not implemented by this
+    connector.
+    """
+
+    def __init__(
+        self,
+        use_gpu: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        self._attributes_initialized = False
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+        self.use_gpu = use_gpu
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+        layout_hints: Optional[LayoutHints] = None,
+    ) -> "VLLMPagedMemMUSAConnectorV2":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+            layout_hints: Optional hints about KV cache layout from the
+                serving engine.
+
+        Returns:
+            A new instance of VLLMPagedMemMUSAConnectorV2.
+        """
+        return cls(use_gpu=use_gpu)
+
+    def to_gpu(
+        self, memory_obj: MemoryObj, start: int, end: int, **kwargs: Any
+    ) -> None:
+        """Store KV data from a memory object into MUSA paged KV caches.
+
+        Args:
+            memory_obj: The memory object containing KV data.
+            start: Starting index in the token sequence.
+            end: Ending index in the token sequence.
+
+        Keyword Args:
+            kvcaches: Nested tuple of K/V tensors for the whole sequence.
+            slot_mapping: Full slot mapping tensor.
+
+        Raises:
+            ValueError: If slot_mapping is missing from kwargs.
+            AssertionError: If memory_obj has no tensor.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        self._initialize_attributes(self.kvcaches)
+        self._validate_memory_format(memory_obj)
+        self._validate_supported_kv_format()
+
+        vllm_cached = kwargs.get("vllm_cached_tokens", 0)
+        skip_prefix_n_tokens = min(end - start, max(0, vllm_cached - start))
+        transfer_start = start + skip_prefix_n_tokens
+        if transfer_start >= end:
+            return
+        if try_native_to_gpu(
+            use_mla=self.use_mla,
+            memory_tensor=memory_obj.tensor,
+            kvcaches=self.kvcaches,
+            slot_mapping=slot_mapping,
+            start=start,
+            end=end,
+            skip_prefix_n_tokens=skip_prefix_n_tokens,
+            block_size=self.block_size,
+            num_heads=self.num_heads,
+            head_size=self.head_size,
+        ):
+            return
+
+        slices = slot_mapping[transfer_start:end].to(
+            device=self.device, dtype=torch.long, non_blocking=True
+        )
+
+        if self.use_mla:
+            tmp = memory_obj.tensor[0].to(self.device, non_blocking=True)
+            total_blocks = self.num_blocks * self.block_size
+            for i, kvcache in enumerate(self.kvcaches):
+                kvcache.view(total_blocks, self.head_size).index_copy_(
+                    0, slices, tmp[i, skip_prefix_n_tokens:]
+                )
+        else:
+            tmp_k = memory_obj.tensor[0].to(self.device, non_blocking=True)
+            tmp_v = memory_obj.tensor[1].to(self.device, non_blocking=True)
+            total_blocks = self.num_blocks * self.block_size
+            d = self.num_heads * self.head_size
+            for i, (kcache, vcache) in enumerate(self.kvcaches):
+                kcache.view(total_blocks, d).index_copy_(
+                    0, slices, tmp_k[i, skip_prefix_n_tokens:]
+                )
+                vcache.view(total_blocks, d).index_copy_(
+                    0, slices, tmp_v[i, skip_prefix_n_tokens:]
+                )
+
+    def from_gpu(
+        self, memory_obj: MemoryObj, start: int, end: int, **kwargs: Any
+    ) -> None:
+        """Load KV data from MUSA paged KV caches into a memory object.
+
+        Args:
+            memory_obj: The memory object to populate.
+            start: Starting index in the token sequence.
+            end: Ending index in the token sequence.
+
+        Keyword Args:
+            kvcaches: Nested tuple of K/V tensors for the whole sequence.
+            slot_mapping: Full slot mapping tensor.
+
+        Raises:
+            ValueError: If slot_mapping is missing from kwargs.
+            AssertionError: If memory_obj has no tensor.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        self._initialize_attributes(self.kvcaches)
+        self._validate_memory_format(memory_obj)
+        self._validate_supported_kv_format()
+        if start >= end:
+            if self.use_mla:
+                memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+            return
+        if try_native_from_gpu(
+            use_mla=self.use_mla,
+            memory_tensor=memory_obj.tensor,
+            kvcaches=self.kvcaches,
+            slot_mapping=slot_mapping,
+            start=start,
+            end=end,
+            block_size=self.block_size,
+            num_heads=self.num_heads,
+            head_size=self.head_size,
+        ):
+            if memory_obj.tensor.device.type != "musa" and hasattr(torch, "musa"):
+                torch.musa.synchronize()  # type: ignore[attr-defined]
+            if self.use_mla:
+                memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+            return
+
+        slices = slot_mapping[start:end].to(
+            device=self.device, dtype=torch.long, non_blocking=True
+        )
+
+        if self.use_mla:
+            total_blocks = self.num_blocks * self.block_size
+            tmp = torch.stack(
+                [
+                    kvcache.view(total_blocks, self.head_size).index_select(0, slices)
+                    for kvcache in self.kvcaches
+                ]
+            )
+        else:
+            total_blocks = self.num_blocks * self.block_size
+            d = self.num_heads * self.head_size
+            tmp_k = torch.stack(
+                [
+                    kvcache[0].view(total_blocks, d).index_select(0, slices)
+                    for kvcache in self.kvcaches
+                ]
+            )
+            tmp_v = torch.stack(
+                [
+                    kvcache[1].view(total_blocks, d).index_select(0, slices)
+                    for kvcache in self.kvcaches
+                ]
+            )
+            tmp = torch.stack([tmp_k, tmp_v])
+        memory_obj.tensor.copy_(tmp, non_blocking=True)
+
+        if memory_obj.tensor.device.type != "musa":
+            torch.musa.synchronize()  # type: ignore[attr-defined]
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    def batched_to_gpu(
+        self,
+        memory_objs: Union[
+            List[List[MemoryObj]], List[MemoryObj], List[int], None
+        ] = None,
+        starts: Optional[List[int]] = None,
+        ends: Optional[List[int]] = None,
+        **kwargs: Any,
+    ) -> None:
+        if memory_objs is None or starts is None or ends is None:
+            raise ValueError("memory_objs, starts, and ends should be provided.")
+
+        typed_memory_objs = cast(List[MemoryObj], memory_objs)
+        for memory_obj, start, end in zip(
+            typed_memory_objs, starts, ends, strict=False
+        ):
+            self.to_gpu(memory_obj, start, end, **kwargs)
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        """Get the shape of the data given the number of tokens.
+
+        Args:
+            num_tokens: The number of tokens in the data.
+
+        Returns:
+            The shape of the KV cache data.
+
+        Raises:
+            RuntimeError: If attributes have not been initialized yet.
+        """
+        if not self._attributes_initialized:
+            raise RuntimeError(
+                "Cannot determine shape before attributes are initialized. "
+                "Call to_gpu or from_gpu first so that _initialize_attributes "
+                "can discover the KV cache layout."
+            )
+        kv_size = 1 if self.use_mla else 2
+        return torch.Size([kv_size, self.num_layers, num_tokens, self.hidden_dim_size])
+
+    def _validate_memory_format(self, memory_obj: MemoryObj) -> None:
+        """Validate that the memory object has the expected format.
+
+        Args:
+            memory_obj: The memory object to validate.
+
+        Raises:
+            ValueError: If the memory format does not match.
+        """
+        if self.use_mla:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_MLA_FMT:
+                raise ValueError(
+                    "The memory object should be in KV_MLA_FMT format in"
+                    " order to be processed by VLLMPagedMemMUSAConnectorV2"
+                )
+        else:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_2LTD:
+                raise ValueError(
+                    "The memory object should be in KV_2LTD format in"
+                    " order to be processed by VLLMPagedMemMUSAConnectorV2"
+                )
+
+    def _validate_supported_kv_format(self) -> None:
+        """Validate that this connector implements the discovered engine KV format.
+
+        Raises:
+            ValueError: If the active KV cache layout is unsupported by the
+                non-layerwise torch-based MUSA path.
+        """
+        if self.engine_kv_format not in _SUPPORTED_MUSA_KV_FORMATS:
+            supported = ", ".join(fmt.name for fmt in _SUPPORTED_MUSA_KV_FORMATS)
+            raise ValueError(
+                "VLLMPagedMemMUSAConnectorV2 supports only vLLM MUSA layouts "
+                f"{supported}; got {self.engine_kv_format.name}. Unsupported "
+                "layouts include flash-infer, HND, cross-layer, connector v3, "
+                "and MP GPU-transfer kernel layouts."
+            )
+
+    def _initialize_attributes(self, kv_caches: List[torch.Tensor]) -> None:
+        """Initialize attributes from KV caches using utils functions.
+
+        Args:
+            kv_caches: The KV cache tensors from which to discover layout.
+        """
+        if self._attributes_initialized:
+            return
+
+        self.device = kv_caches[0].device
+        assert self.device.type == "musa", "The device should be MUSA."
+
+        discoverable_kv_caches = cast(DiscoverableKVCache, kv_caches)
+        normalized_kv_caches: DiscoverableKVCache
+        self.engine_kv_format, normalized_kv_caches = normalize_kv_and_discover_format(
+            discoverable_kv_caches, EngineType.VLLM
+        )
+        self.num_layers = get_num_layers(normalized_kv_caches, self.engine_kv_format)
+        self.num_blocks = get_num_blocks(normalized_kv_caches, self.engine_kv_format)
+        self.block_size = get_block_size(normalized_kv_caches, self.engine_kv_format)
+        self.page_buffer_size = get_page_buffer_size(
+            normalized_kv_caches, self.engine_kv_format
+        )
+        self.hidden_dim_size = get_hidden_dim_size(
+            normalized_kv_caches, self.engine_kv_format
+        )
+        self.head_size = get_head_size(normalized_kv_caches, self.engine_kv_format)
+        self.use_mla = is_mla(self.engine_kv_format)
+        self.dtype = get_dtype(normalized_kv_caches, self.engine_kv_format)
+        self.num_heads = (
+            1
+            if self.use_mla
+            else get_num_heads(normalized_kv_caches, self.engine_kv_format)
+        )
+
+        self._attributes_initialized = True
+        logger.info(
+            "MUSA: attributes initialized - format: %s, "
+            "num_layers: %d, num_blocks: %d, block_size: %d, "
+            "page_buffer_size: %d, hidden_dim_size: %d, head_size: %d, "
+            "use_mla: %s, dtype: %s, num_heads: %d",
+            self.engine_kv_format,
+            self.num_layers,
+            self.num_blocks,
+            self.block_size,
+            self.page_buffer_size,
+            self.hidden_dim_size,
+            self.head_size,
+            self.use_mla,
+            self.dtype,
+            self.num_heads,
+        )
+
+
+class VLLMPagedMemLayerwiseMUSAConnector(GPUConnectorInterface):
+    """Layerwise paged KV connector for MUSA devices.
+
+    Implements the same generator contract as VLLMPagedMemLayerwiseXPUConnector:
+      - batched_to_gpu(...) yields num_layers + 2 times
+      - batched_from_gpu(...) yields num_layers + 1 times
+
+    Transfer is implemented with pure torch ops (index_copy_ / index_select).
+    """
+
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_musa: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+        self.use_musa = use_musa
+
+        assert "chunk_size" in kwargs, "chunk_size should be provided."
+        assert "dtype" in kwargs, "dtype should be provided."
+        assert "device" in kwargs, "device should be provided."
+
+        self.dtype = kwargs["dtype"]
+        self.device = kwargs["device"]
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        self._load_stream: Optional[Any] = None
+        self._store_stream: Optional[Any] = None
+
+        self.gpu_buffer_allocator: Optional[GPUMemoryAllocator] = None
+
+    @property
+    def load_stream(self) -> Any:
+        """Return the lazily-created MUSA load stream."""
+        self._ensure_streams()
+        return self._load_stream
+
+    @property
+    def store_stream(self) -> Any:
+        """Return the lazily-created MUSA store stream."""
+        self._ensure_streams()
+        return self._store_stream
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_musa: bool = False,
+        device: Optional[torch.device] = None,
+    ) -> "VLLMPagedMemLayerwiseMUSAConnector":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model
+                configuration.
+            use_musa: Whether to use MUSA intermediate buffer.
+            device: The device to use for the connector.
+
+        Returns:
+            A new instance of VLLMPagedMemLayerwiseMUSAConnector.
+        """
+        num_layers = metadata.kv_shape[0]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_musa=use_musa,
+            chunk_size=metadata.kv_shape[2],
+            dtype=metadata.kv_dtype,
+            device=device,
+            use_mla=metadata.use_mla,
+        )
+
+    def _validate_format_transition(
+        self, mem: MemoryObj, target_fmt: MemoryFormat
+    ) -> None:
+        current_fmt = mem.metadata.fmt
+        if (current_fmt, target_fmt) not in ALLOWED_FORMAT_TRANSITIONS:
+            raise ValueError(
+                f"Invalid KV format transition: {current_fmt} -> {target_fmt}"
+            )
+
+    def _lazy_initialize_buffer(self, kv_caches: List[torch.Tensor]) -> None:
+        if self.use_musa and self.gpu_buffer_allocator is None:
+            layer0 = kv_caches[0]
+            derived_bytes = layer0.numel() * layer0.element_size()
+            staging_bytes = int(
+                os.getenv("LMCACHE_GPU_STAGING_BUFFER_BYTES", derived_bytes)
+            )
+            logger.info(
+                "Initializing MUSA staging buffer (derived=%d bytes, final=%d bytes)",
+                derived_bytes,
+                staging_bytes,
+            )
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                size=staging_bytes, device=self.device
+            )
+
+    def to_gpu(
+        self, memory_obj: MemoryObj, start: int, end: int, **kwargs: Any
+    ) -> None:
+        raise NotImplementedError("Layerwise uses batched_to_gpu(generator).")
+
+    def from_gpu(
+        self, memory_obj: MemoryObj, start: int, end: int, **kwargs: Any
+    ) -> None:
+        raise NotImplementedError("Layerwise uses batched_from_gpu(generator).")
+
+    def _batched_to_gpu_gen(
+        self, starts: List[int], ends: List[int], **kwargs: Any
+    ) -> Generator[Any, Any, None]:
+        """Generator: CPU token2d -> (optional staging) -> MUSA paged KV."""
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        sync: bool = kwargs["sync"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        def _ensure_musa(t: torch.Tensor) -> torch.Tensor:
+            if t.device != self.device:
+                return t.to(self.device, non_blocking=True)
+            return t
+
+        slot_mapping_chunks = [
+            slot_mapping[s:e] for s, e in zip(starts, ends, strict=False)
+        ]
+        if not slot_mapping_chunks:
+            for _ in range(self.num_layers):
+                _ = yield
+            yield
+            if sync:
+                torch.musa.current_stream().wait_stream(self.load_stream)  # type: ignore[attr-defined]
+            yield
+            return
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+        slot_mapping_full = _ensure_musa(slot_mapping_full)
+
+        num_tokens = int(slot_mapping_full.numel())
+        if num_tokens <= 0:
+            for _ in range(self.num_layers):
+                _ = yield
+            yield
+            if sync:
+                torch.musa.current_stream().wait_stream(self.load_stream)  # type: ignore[attr-defined]
+            yield
+            return
+
+        tmp_gpu_buffer_obj: Optional[MemoryObj] = None
+        if self.use_musa:
+            buffer_shape = self.get_shape(num_tokens)
+            assert self.gpu_buffer_allocator is not None
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, MemoryFormat.KV_T2D
+            )
+            if tmp_gpu_buffer_obj is None or tmp_gpu_buffer_obj.tensor is None:
+                raise RuntimeError(
+                    "Failed to allocate MUSA staging buffer for batched_to_gpu."
+                )
+
+        current_stream = torch.musa.current_stream()  # type: ignore[attr-defined]
+
+        try:
+            for layer_id in range(self.num_layers):
+                memory_objs_layer = yield
+
+                if sync:
+                    current_stream.wait_stream(self.load_stream)
+
+                with torch.musa.stream(self.load_stream):  # type: ignore[attr-defined]
+                    dst_layer = self.kvcaches[layer_id]
+                    if self.use_mla:
+                        dst_flat = cast(
+                            torch.Tensor,
+                            _get_head_size_view(dst_layer, use_mla=True),
+                        )
+                    else:
+                        dst_k_flat, dst_v_flat = _get_head_size_view(  # type: ignore[misc]
+                            dst_layer, use_mla=False
+                        )
+
+                    cursor = 0
+
+                    if self.use_musa:
+                        assert tmp_gpu_buffer_obj is not None
+                        staged = tmp_gpu_buffer_obj.tensor
+                        assert staged is not None
+
+                        for s, e, mem in zip(
+                            starts, ends, memory_objs_layer, strict=False
+                        ):
+                            assert mem.tensor is not None
+                            n = int(e - s)
+                            if n <= 0:
+                                continue
+                            src = _ensure_musa(mem.tensor)
+                            staged[cursor : cursor + n].copy_(src, non_blocking=True)
+                            cursor += n
+
+                        sl = _ensure_musa(slot_mapping_full)
+
+                        if self.use_mla:
+                            staged_dev = _ensure_musa(staged)
+                            if staged_dev.dim() == 2:
+                                dst_flat.index_copy_(0, sl, staged_dev)
+                            elif staged_dev.dim() == 3 and staged_dev.shape[0] == 1:
+                                dst_flat.index_copy_(0, sl, staged_dev[0])
+                            else:
+                                raise ValueError(
+                                    f"Unexpected MLA staged tensor: {staged_dev.shape}"
+                                )
+                        else:
+                            k_tok, v_tok = _split_token2d_kv(staged)
+                            k_tok = _ensure_musa(k_tok)
+                            v_tok = _ensure_musa(v_tok)
+
+                            if (
+                                k_tok.dim() == 2
+                                and dst_k_flat.dim() == 3
+                                and k_tok.shape[1]
+                                == dst_k_flat.shape[1] * dst_k_flat.shape[2]
+                            ):
+                                k_tok = k_tok.reshape(
+                                    k_tok.shape[0],
+                                    dst_k_flat.shape[1],
+                                    dst_k_flat.shape[2],
+                                )
+                            if (
+                                v_tok.dim() == 2
+                                and dst_v_flat.dim() == 3
+                                and v_tok.shape[1]
+                                == dst_v_flat.shape[1] * dst_v_flat.shape[2]
+                            ):
+                                v_tok = v_tok.reshape(
+                                    v_tok.shape[0],
+                                    dst_v_flat.shape[1],
+                                    dst_v_flat.shape[2],
+                                )
+
+                            dst_k_flat.index_copy_(0, sl, k_tok)
+                            dst_v_flat.index_copy_(0, sl, v_tok)
+
+                    else:
+                        for s, e, mem in zip(
+                            starts, ends, memory_objs_layer, strict=False
+                        ):
+                            assert mem.tensor is not None
+                            n = int(e - s)
+                            if n <= 0:
+                                continue
+                            src = _ensure_musa(mem.tensor)
+                            sl = slot_mapping_full[cursor : cursor + n]
+                            sl = _ensure_musa(sl)
+                            cursor += n
+
+                            if self.use_mla:
+                                if src.dim() == 2:
+                                    dst_flat.index_copy_(0, sl, src)
+                                elif src.dim() == 3 and src.shape[0] == 1:
+                                    dst_flat.index_copy_(0, sl, src[0])
+                                else:
+                                    raise ValueError(
+                                        f"Unexpected MLA token tensor: {src.shape}"
+                                    )
+                            else:
+                                k_tok, v_tok = _split_token2d_kv(src)
+                                k_tok = _ensure_musa(k_tok)
+                                v_tok = _ensure_musa(v_tok)
+
+                                if (
+                                    k_tok.dim() == 2
+                                    and dst_k_flat.dim() == 3
+                                    and k_tok.shape[1]
+                                    == dst_k_flat.shape[1] * dst_k_flat.shape[2]
+                                ):
+                                    k_tok = k_tok.reshape(
+                                        k_tok.shape[0],
+                                        dst_k_flat.shape[1],
+                                        dst_k_flat.shape[2],
+                                    )
+                                if (
+                                    v_tok.dim() == 2
+                                    and dst_v_flat.dim() == 3
+                                    and v_tok.shape[1]
+                                    == dst_v_flat.shape[1] * dst_v_flat.shape[2]
+                                ):
+                                    v_tok = v_tok.reshape(
+                                        v_tok.shape[0],
+                                        dst_v_flat.shape[1],
+                                        dst_v_flat.shape[2],
+                                    )
+
+                                dst_k_flat.index_copy_(0, sl, k_tok)
+                                dst_v_flat.index_copy_(0, sl, v_tok)
+
+            yield
+
+            if sync:
+                current_stream.wait_stream(self.load_stream)
+        finally:
+            if tmp_gpu_buffer_obj is not None:
+                tmp_gpu_buffer_obj.ref_count_down()
+
+        yield
+
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]], List[MemoryObj]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs: Any,
+    ) -> Generator[Any, Any, None]:
+        """Generator: MUSA paged KV -> CPU token2d (per layer)."""
+        typed_memory_objs = cast(List[List[MemoryObj]], memory_objs)
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        sync: bool = kwargs["sync"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        current_stream = torch.musa.current_stream()  # type: ignore[attr-defined]
+
+        slot_mapping_on_device = slot_mapping.to(self.device)
+
+        for layer_id in range(self.num_layers):
+            mem_layer = typed_memory_objs[layer_id]
+
+            with torch.musa.stream(self.store_stream):  # type: ignore[attr-defined]
+                self.store_stream.wait_stream(current_stream)
+
+                src_layer = self.kvcaches[layer_id]
+
+                if self.use_mla:
+                    src_flat = cast(
+                        torch.Tensor,
+                        _get_head_size_view(src_layer, use_mla=True),
+                    )
+                    for s, e, mem in zip(starts, ends, mem_layer, strict=False):
+                        assert mem.tensor is not None
+                        sl = slot_mapping_on_device[s:e]
+                        gathered = src_flat.index_select(0, sl)
+                        mem.tensor.copy_(
+                            gathered.to(mem.tensor.device),
+                            non_blocking=True,
+                        )
+
+                    target_fmt = MemoryFormat.KV_MLA_FMT
+                    for mem in mem_layer:
+                        self._validate_format_transition(mem, target_fmt)
+                        mem.metadata.fmt = target_fmt
+                else:
+                    src_k_flat, src_v_flat = _get_head_size_view(
+                        src_layer, use_mla=False
+                    )
+                    for s, e, mem in zip(starts, ends, mem_layer, strict=False):
+                        assert mem.tensor is not None
+                        sl = slot_mapping_on_device[s:e]
+                        k = src_k_flat.index_select(0, sl)
+                        v = src_v_flat.index_select(0, sl)
+
+                        if mem.tensor.shape[0] == 2:
+                            mem.tensor[0].copy_(
+                                k.to(mem.tensor.device), non_blocking=True
+                            )
+                            mem.tensor[1].copy_(
+                                v.to(mem.tensor.device), non_blocking=True
+                            )
+                        elif mem.tensor.dim() >= 2 and mem.tensor.shape[1] == 2:
+                            mem.tensor[:, 0].copy_(
+                                k.to(mem.tensor.device), non_blocking=True
+                            )
+                            mem.tensor[:, 1].copy_(
+                                v.to(mem.tensor.device), non_blocking=True
+                            )
+                        else:
+                            raise ValueError(
+                                f"Unrecognized KV tensor layout: {mem.tensor.shape}"
+                            )
+
+            if sync:
+                self.store_stream.synchronize()
+            yield
+
+        yield
+
+    def batched_to_gpu(
+        self,
+        memory_objs: Union[
+            List[List[MemoryObj]], List[MemoryObj], List[int], None
+        ] = None,
+        starts: Optional[List[int]] = None,
+        ends: Optional[List[int]] = None,
+        **kwargs: Any,
+    ) -> Generator[Any, Any, None]:
+        return self._batched_to_gpu_gen(starts=starts or [], ends=ends or [], **kwargs)
+
+    def _ensure_streams(self) -> None:
+        """Lazily create MUSA streams on first transfer."""
+        if self._load_stream is None:
+            self._load_stream = torch.musa.Stream()  # type: ignore[attr-defined]
+            self._store_stream = torch.musa.Stream()  # type: ignore[attr-defined]
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        """Get the shape of the data for a single layer.
+
+        Args:
+            num_tokens: The number of tokens in the data.
+
+        Returns:
+            The shape of the KV cache data for one layer.
+        """
+        if self.use_mla:
+            return torch.Size([num_tokens, self.hidden_dim_size])
+        return torch.Size([num_tokens, 2, self.hidden_dim_size])
diff --git a/lmcache/v1/gpu_connector/utils.py b/lmcache/v1/gpu_connector/utils.py
new file mode 100644
index 0000000..88d22ad
--- /dev/null
+++ b/lmcache/v1/gpu_connector/utils.py
@@ -0,0 +1,767 @@
+# SPDX-License-Identifier: Apache-2.0
+# Format-dispatched geometry now lives in the ``kv_format`` package: each
+# ``EngineKVFormat`` has a :class:`KVFormatSpec` (geometry accessors) and
+# detection is split per engine in ``kv_format.detection``. The public
+# functions below are a thin, backwards-compatible facade that delegates
+# to ``get_spec`` / ``get_spec_class`` / ``detect_format`` so existing
+# callers keep working unchanged.
+# mypy: disable-error-code="union-attr,call-overload"
+# Standard
+from collections.abc import Hashable, Sequence
+from typing import TYPE_CHECKING, Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.python_ops_fallback import set_shape_desc_dtype
+from lmcache.utils import EngineType, lmcache_deprecate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.kv_format import (
+    concrete_shape,
+    describe_shape,
+    detect_format,
+    get_spec,
+    get_spec_class,
+)
+from lmcache.v1.gpu_connector.kv_format.types import DiscoverableKVCache, LayoutHints
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.gpu_connector.gpu_connectors import GPUConnectorInterface
+
+# First Party
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+def assert_contiguous(tensor: torch.Tensor) -> None:
+    """Assert that *tensor* has a contiguous physical layout with zero offset.
+
+    LMCache transfer kernels assume logical and physical views match for
+    coalesced memory accesses. Used at boundaries where we receive a
+    tensor we can't or shouldn't permute (e.g. raw CUDA-IPC reconstruction
+    in :class:`~lmcache.v1.platform.cuda.ipc_wrapper.RawCudaIPCWrapper`).
+
+    Raises:
+        ValueError: If *tensor* has a nonzero storage offset, or is
+            non-contiguous.
+    """
+    if tensor.storage_offset() != 0:
+        raise ValueError(f"expected storage_offset 0, got {tensor.storage_offset()}")
+    if not tensor.is_contiguous():
+        raise ValueError("tensor is not contiguous")
+
+
+def need_gpu_interm_buffer(lmcache_config: LMCacheEngineConfig):
+    """
+    Check if the GPU Connector needs to create an intermediate
+    buffer on the GPU
+    """
+    if lmcache_config.enable_pd:
+        return False
+    else:
+        return True
+
+
+def assert_layerwise_gpu_connector(gpu_connector: "GPUConnectorInterface"):
+    """
+    Assert that a GPU Connector is a layerwise connector.
+    """
+    # Import at runtime to avoid circular dependency
+    # First Party
+    from lmcache.v1.gpu_connector import gpu_connectors, xpu_connectors
+
+    valid_connectors = (
+        gpu_connectors.VLLMPagedMemLayerwiseGPUConnector,
+        gpu_connectors.VLLMBufferLayerwiseGPUConnector,
+        gpu_connectors.SGLangLayerwiseGPUConnector,
+        xpu_connectors.VLLMPagedMemLayerwiseXPUConnector,
+        xpu_connectors.VLLMBufferLayerwiseXPUConnector,
+        xpu_connectors.SGLangLayerwiseXPUConnector,
+    )
+
+    assert isinstance(gpu_connector, valid_connectors)
+
+
+def is_mla(engine_kv_format: "lmc_ops.EngineKVFormat") -> bool:
+    """Return ``True`` for a Multi-head Latent Attention (MLA) layout."""
+    return lmc_ops.is_mla(engine_kv_format)
+
+
+def get_engine_kv_shape_description(engine_kv_format: "lmc_ops.EngineKVFormat") -> str:
+    """Return a human-readable symbolic shape legend for the Engine KV format.
+
+    Uses short names matching the ``EngineKVFormat`` enum convention:
+    NB=num_blocks, NL=num_layers, BS=block_size, NH=num_heads,
+    HS=head_size, PBS=page_buffer_size (NB*BS).
+    """
+    try:
+        return describe_shape(engine_kv_format)
+    except KeyError:
+        return f"Unknown ({engine_kv_format})"
+
+
+def get_attention_backend(engine_kv_format: "lmc_ops.EngineKVFormat") -> str:
+    """Return a representative attention-backend label for the format.
+
+    Diagnostic only. A format may be produced by several (engine,
+    attention-backend) combinations; the spec lists them in
+    ``attention_backends`` and this returns the first (canonical) one.
+    """
+    try:
+        backends = get_spec_class(engine_kv_format).attention_backends
+    except ValueError:
+        return f"Unknown ({engine_kv_format})"
+    return backends[0] if backends else f"Unknown ({engine_kv_format})"
+
+
+def get_concrete_engine_kv_shape(
+    kv_caches: DiscoverableKVCache, engine_kv_format: "lmc_ops.EngineKVFormat"
+) -> str:
+    """Return the shape with actual numeric values substituted.
+
+    For example, instead of ``NL x [2, NB, BS, NH, HS]``
+    this returns ``80 x [2, 2048, 128, 8, 128]``.
+    """
+    try:
+        return get_spec(kv_caches, engine_kv_format).concrete_shape_str()
+    except ValueError:
+        return f"Unknown ({engine_kv_format})"
+
+
+def get_concrete_engine_kv_shape_from_shape_desc(
+    shape_desc: "lmc_ops.PageBufferShapeDesc",
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+) -> str:
+    """Return the concrete shape for a single kernel group's ``shape_desc``.
+
+    Like :func:`get_concrete_engine_kv_shape`, but the numeric values are
+    read from a per-group :class:`PageBufferShapeDesc` rather than from the
+    whole ``kv_caches`` structure. This makes the result *group-accurate*:
+    ``shape_desc.nl`` is the layer count of the group (not the model total),
+    so each kernel group of a hybrid model reports its own shape.
+
+    For example, instead of ``NL x [2, NB, BS, NH, HS]`` this returns
+    ``80 x [2, 2048, 128, 8, 128]``.
+
+    Args:
+        shape_desc: The kernel group's shape descriptor. Sizes are read
+            from its ``nl``/``nb``/``bs``/``nh``/``hs`` fields; fused
+            page-buffer (``NBBS``) formats use ``nb * bs``.
+        engine_kv_format: The format whose member name is the shape template.
+
+    Returns:
+        The shape string with numeric values substituted, or
+        ``"Unknown (<format>)"`` for an unrecognised format.
+    """
+    sizes = {
+        "NB": shape_desc.nb,
+        "NL": shape_desc.nl,
+        "BS": shape_desc.bs,
+        "NH": shape_desc.nh,
+        "HS": shape_desc.hs,
+        "PBS": shape_desc.nb * shape_desc.bs,
+    }
+    try:
+        return concrete_shape(engine_kv_format, lambda label: sizes[label])
+    except KeyError:
+        return f"Unknown ({engine_kv_format})"
+
+
+def legible_print_engine_kv_format(engine_kv_format: "lmc_ops.EngineKVFormat"):
+    """
+    Print the Engine KV Format in a legible way
+    """
+    shape = get_engine_kv_shape_description(engine_kv_format)
+    backend = get_attention_backend(engine_kv_format)
+    if shape.startswith("Unknown"):
+        logger.warning(f"Unknown Engine KV Format: {engine_kv_format}")
+    else:
+        logger.info("Engine KV Format: %s", shape)
+        logger.info("Currently used by:\n  - %s", backend)
+
+
+def normalize_kv_and_discover_format(
+    kv_caches: DiscoverableKVCache,
+    serving_engine: EngineType,
+    layout_hints: "LayoutHints | None" = None,
+) -> tuple["lmc_ops.EngineKVFormat", DiscoverableKVCache]:
+    """Normalize ``kv_caches`` into canonical form and discover its Engine KV format.
+
+    Thin wrapper over
+    :func:`lmcache.v1.gpu_connector.kv_format.detect_format`; see that
+    function for the full contract.
+
+    Args:
+        kv_caches: The KV cache tensors (possibly nested lists of tensors).
+        serving_engine: Which serving engine produced the caches.
+        layout_hints: See :class:`LayoutHints`.
+
+    Returns:
+        ``(engine_kv_format, normalized_kv_caches)``. Callers must use the
+        returned tensor structure for subsequent operations -- it shares
+        storage with the input but may be a permuted view.
+    """
+    return detect_format(kv_caches, serving_engine, layout_hints)
+
+
+def normalize_and_discover_per_layer_formats(
+    kv_caches: "DiscoverableKVCache",
+    layer_index_groups: "Sequence[Sequence[int]]",
+    serving_engine: EngineType,
+    layout_hints: "LayoutHints | None" = None,
+) -> "tuple[DiscoverableKVCache, list[lmc_ops.EngineKVFormat]]":
+    """Normalize the KV caches and return one Engine KV format per layer.
+
+    Reports each layer's own format, so models whose layers do not all share one
+    format -- e.g. a K+V main cache (``kv_size=2``) alongside a key-only MLA index
+    cache (``kv_size=1``) -- get a correct per-layer format rather than a single
+    model-wide one.
+
+    Args:
+        kv_caches: The registered KV caches: a per-layer list, or a single fused
+            tensor for cross-layer formats.
+        layer_index_groups: Layer indices of each engine group (one inner
+            sequence per group). Empty means a single non-hybrid group.
+        serving_engine: Which serving engine produced the caches.
+        layout_hints: See :class:`LayoutHints`.
+
+    Returns:
+        ``(normalized_kv_caches, engine_kv_formats)``: the canonical KV cache
+        structure and one format per layer (length equals the layer count),
+        ready for :func:`lmcache.v1.kv_layer_groups.group_layers_by_identity`.
+    """
+
+    # Detect the whole structure once. A format that isn't a per-layer list (a
+    # cross-layer tensor, or a K/V-split) is single-format -- return it whole.
+    whole_format, whole_normalized = detect_format(
+        kv_caches, serving_engine, layout_hints
+    )
+    if not lmc_ops.is_layer_list(whole_format):
+        return whole_normalized, [whole_format] * get_num_layers(
+            whole_normalized, whole_format
+        )
+
+    # Per-layer list: re-detect per engine group, split by tensor shape so a group
+    # that mixes layouts gets the right format per layer.
+    groups = layer_index_groups or [range(len(kv_caches))]
+    detected: dict[int, tuple[DiscoverableKVCache, "lmc_ops.EngineKVFormat"]] = {}
+    for indices in groups:
+        layers_by_shape: dict[Hashable, list[int]] = {}
+        for i in indices:
+            shape = getattr(kv_caches[i], "shape", None)
+            key = tuple(shape) if shape is not None else None
+            layers_by_shape.setdefault(key, []).append(i)
+        for same_shape_indices in layers_by_shape.values():
+            fmt, normalized = detect_format(
+                [kv_caches[i] for i in same_shape_indices],
+                serving_engine,
+                layout_hints,
+            )
+            for sub_idx, layer_idx in enumerate(same_shape_indices):
+                detected[layer_idx] = (normalized[sub_idx], fmt)
+
+    # A layer in no group (cross-layer KV sharing) keeps its own tensor and is
+    # skipped downstream; give it any detected format so every layer has one.
+    fallback_format = next(fmt for _, fmt in detected.values())
+    normalized_per_layer = [
+        detected[i][0] if i in detected else kv_caches[i] for i in range(len(kv_caches))
+    ]
+    engine_kv_formats = [
+        detected[i][1] if i in detected else fallback_format
+        for i in range(len(kv_caches))
+    ]
+    return normalized_per_layer, engine_kv_formats
+
+
+def get_num_layers(
+    kv_caches: DiscoverableKVCache, engine_kv_format: "lmc_ops.EngineKVFormat"
+) -> int:
+    """Return the number of layers from ``kv_caches``."""
+    return get_spec(kv_caches, engine_kv_format).num_layers()
+
+
+def get_num_blocks(
+    kv_caches: DiscoverableKVCache, engine_kv_format: "lmc_ops.EngineKVFormat"
+) -> int:
+    """Return the number of blocks from ``kv_caches``.
+
+    Raises:
+        ValueError: For NBBS-fused formats with no separate block axis.
+    """
+    return get_spec(kv_caches, engine_kv_format).num_blocks()
+
+
+def get_block_size(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int = 0,
+) -> int:
+    """Return the block size (tokens per block) for layer ``layer_idx``.
+
+    ``layer_idx`` is honoured only for per-layer formats where BS may
+    differ across layers (e.g. mixed-compression MLA pools). For
+    cross-layer formats BS is shared across layers and ``layer_idx``
+    is ignored.
+
+    Raises:
+        ValueError: For NBBS-fused formats with no separate block axis.
+    """
+    return get_spec(kv_caches, engine_kv_format).block_size(layer_idx)
+
+
+@lmcache_deprecate(
+    "page_buffer_size is only used by the legacy non-MP (in-process) connectors; "
+    "the MP transfer path reads geometry from a per-group PageBufferShapeDesc instead"
+)
+def get_page_buffer_size(
+    kv_caches: DiscoverableKVCache, engine_kv_format: "lmc_ops.EngineKVFormat"
+) -> int:
+    """Return the page buffer size (num_blocks * block_size) from ``kv_caches``."""
+    return get_spec(kv_caches, engine_kv_format).page_buffer_size()
+
+
+def get_num_heads(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int = 0,
+) -> int:
+    """Return the number of heads for a layer (defaults to layer 0)."""
+    return get_spec(kv_caches, engine_kv_format).num_heads(layer_idx)
+
+
+def get_hidden_dim_size(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int = 0,
+) -> int:
+    """Return the hidden dimension for a layer (defaults to layer 0)."""
+    return get_spec(kv_caches, engine_kv_format).hidden_dim(layer_idx)
+
+
+def get_head_size(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int = 0,
+) -> int:
+    """Return the head size for a layer (defaults to layer 0)."""
+    return get_spec(kv_caches, engine_kv_format).head_size(layer_idx)
+
+
+def get_tokens_per_layer(
+    kv_caches: DiscoverableKVCache, engine_kv_format: "lmc_ops.EngineKVFormat"
+) -> int:
+    """Return the number of tokens per layer (num_blocks * block_size)."""
+    return get_spec(kv_caches, engine_kv_format).tokens_per_layer()
+
+
+def get_elements_per_layer(
+    kv_caches: DiscoverableKVCache, engine_kv_format: "lmc_ops.EngineKVFormat"
+) -> int:
+    """Return the number of elements per layer (both K and V for non-MLA)."""
+    return get_spec(kv_caches, engine_kv_format).elements_per_layer()
+
+
+def get_dtype(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int = 0,
+) -> torch.dtype:
+    """Return the dtype for a layer (defaults to layer 0)."""
+    return get_spec(kv_caches, engine_kv_format).dtype(layer_idx)
+
+
+def get_group_data_ptrs(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_indices: list[int],
+) -> list[int]:
+    """Return device pointers for a group of layers in kernel-expected order.
+
+    See :meth:`KVFormatSpec.data_ptrs` for the per-format pointer-array
+    shape (per-layer list, SGLang K-then-V, or single cross-layer base).
+
+    Args:
+        kv_caches: Full kv_caches structure.
+        engine_kv_format: Format returned by :func:`normalize_kv_and_discover_format`.
+        layer_indices: 0-based layer indices in the group, in kernel order.
+
+    Returns:
+        Device pointers (int), in kernel-expected order.
+
+    Raises:
+        ValueError: If *engine_kv_format* is not recognized.
+    """
+    return get_spec(kv_caches, engine_kv_format).data_ptrs(layer_indices)
+
+
+def assert_is_vllm_flash_attn_or_flash_infer(
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+):
+    """
+    Ensure that we have an Engine KV Cache Format
+    that is either vLLM's flash attention or flash infer.
+    """
+    assert engine_kv_format in (
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS,
+        # Blocks-first fused K/V (vLLM CPU): a per-layer non-MLA layout that
+        # shares this transfer path even though it is not literally flash-*.
+        lmc_ops.EngineKVFormat.NL_X_NB_NH_BS_TWO_HS,
+    )
+
+
+def assert_is_vllm_mla_or_flash_attn_or_flash_infer(
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+) -> None:
+    """
+    Ensure that we have an Engine KV Cache Format that is either
+    vLLM's MLA, flash attention, or flash infer.
+
+    Accepted formats:
+        - ``NL_X_TWO_NB_BS_NH_HS`` (flash attention, NHD)
+        - ``NL_X_NB_TWO_BS_NH_HS`` (flash infer, NHD)
+        - ``NL_X_TWO_NB_NH_BS_HS`` (flash attention, HND)
+        - ``NL_X_NB_TWO_NH_BS_HS`` (flash infer, HND)
+        - ``NL_X_NB_BS_HS`` (MLA)
+
+    Raises:
+        AssertionError: If *engine_kv_format* is not one of the accepted formats.
+    """
+    assert engine_kv_format in (
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    )
+
+
+def get_device(kv_caches: DiscoverableKVCache) -> torch.device:
+    """Return the device of the KV cache tensors.
+
+    Descends into any list nesting until a tensor is found; assumes all
+    tensors in *kv_caches* live on the same device (true for every
+    current :class:`EngineKVFormat`).
+    """
+    probe: DiscoverableKVCache = kv_caches
+    while isinstance(probe, list):
+        probe = probe[0]
+    return probe.device
+
+
+# Formats whose per-layer tensor dim-0 is the *block* axis AND for
+# which we currently support dim-0 padding (e.g. DeepSeek V4
+# compressor / indexer caches sharing a KV pool with larger attn
+# groups). Today only the MLA layout (``NL_X_NB_BS_HS``, kv_size==1)
+# is exercised by real mixed-compression workloads.
+#
+# ``NL_X_NB_TWO_BS_NH_HS`` *could* in principle also be the block
+# axis on dim-0, but no real serving engine emits a padded layout of
+# that format yet, and supporting it would require: (a) deciding
+# (without a ground-truth example) which axis carries the padding
+# -- NB boundary vs K<->V offset -- and (b) a coordinated change in
+# ``attempt_permute_to_contiguous_view`` to let interior-dim padding
+# through for that one format. Rather than ship an unverifiable code
+# path, we keep ``NL_X_NB_TWO_BS_NH_HS`` out of this set, which means
+# any padded tensor of that format will fail loudly via the
+# non-block-axis dim-0-padding check below. Revisit and add a
+# properly-tested branch when a concrete use case lands.
+_BLOCK_AXIS_FORMATS: frozenset = frozenset(
+    {
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    }
+)
+
+
+def resolve_block_stride_and_log_layout(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int,
+    group_idx: int,
+) -> Optional[int]:
+    """Resolve the per-block stride for a KV layer group and log its layout.
+
+    Single entry point for :class:`KVLayerGroupsManager` to obtain the
+    ``block_stride_elems`` value for :class:`PageBufferShapeDesc` and emit
+    a one-shot layout audit line. All ``EngineKVFormat``-aware reasoning is
+    kept here so callers never touch a "representative KV cache" tensor.
+
+    * Block-axis formats (:data:`_BLOCK_AXIS_FORMATS`): ``stride(0)`` is
+      the per-block step and is returned as-is. A value larger than the
+      tight stride indicates dim-0 padding (e.g. DeepSeek V4 compressor
+      caches sharing a KV pool with larger attn groups).
+    * Other formats: dim-0 is not the block axis, so ``None`` is
+      returned and ``shape_desc`` falls back to the tight stride. Any
+      dim-0 padding in such formats is rejected with ``ValueError``
+      since downstream kernels cannot honour it.
+
+    Args:
+        kv_caches: Full KV cache structure (already normalised).
+        engine_kv_format: Format of ``kv_caches``.
+        layer_idx: 0-based layer index used as the layout probe.
+        group_idx: 0-based group index, used only for logging.
+
+    Returns:
+        ``stride(0)`` for block-axis formats; ``None`` otherwise.
+
+    Raises:
+        ValueError: Non-block-axis format carries dim-0 padding.
+    """
+
+    def _pick_layout_probe_tensor() -> torch.Tensor:
+        # Layout probe only (shape/stride/storage_offset/dtype); not
+        # the K/V slice fed to the transfer kernel.
+        # - Cross-layer formats: ``kv_caches`` is the single backing
+        #   tensor packing all layers along dim-1; indexing dim-0
+        #   (= NB) would yield a per-block slice, so return the whole
+        #   tensor (its ``stride(0)`` is the authoritative per-NB step).
+        # - SGL MHA: outer list is K/V (length 2), inner list is
+        #   per-layer; K & V share shape/stride by construction.
+        # - Other formats: ``kv_caches`` is already a per-layer list.
+        if lmc_ops.is_cross_layer(engine_kv_format):
+            if not isinstance(kv_caches, torch.Tensor):
+                raise TypeError(
+                    "Cross-layer EngineKVFormat expects a single backing "
+                    f"torch.Tensor, got {type(kv_caches).__name__}."
+                )
+            return kv_caches
+        if lmc_ops.is_kv_list(engine_kv_format):
+            return kv_caches[0][layer_idx]  # type: ignore[index,return-value]
+        return kv_caches[layer_idx]  # type: ignore[index,return-value]
+
+    rep = _pick_layout_probe_tensor()
+
+    block_stride_elems: Optional[int]
+    if engine_kv_format in _BLOCK_AXIS_FORMATS and rep.ndim > 0:
+        block_stride_elems = int(rep.stride(0))
+    else:
+        # Non-block-axis format: detect forbidden dim-0 padding.
+        if rep.ndim >= 2:
+            tight_dim0 = 1
+            for d in range(1, rep.ndim):
+                tight_dim0 *= int(rep.shape[d])
+            padding = int(rep.stride(0)) - tight_dim0
+            if padding > 0:
+                raise ValueError(
+                    "resolve_block_stride_and_log_layout: group's probe "
+                    f"tensor has dim-0 padding ({padding} elements per "
+                    f"block) but engine_kv_format={engine_kv_format!r} is not "
+                    "a supported dim-0-padded format (only "
+                    "NL_X_NB_BS_HS is); downstream transfer kernels "
+                    "cannot honour this padding and would read/write "
+                    "wrong bytes. "
+                    f"layer_idx={layer_idx}, shape={tuple(rep.shape)}, "
+                    f"stride={tuple(rep.stride())}, "
+                    f"tight_stride0={tight_dim0}, "
+                    f"storage_offset={int(rep.storage_offset())}, "
+                    f"dtype={rep.dtype}."
+                )
+        block_stride_elems = None
+
+    # Best-effort layout audit log; the log line itself must not raise.
+    shape = tuple(rep.shape)
+    stride = tuple(rep.stride())
+    try:
+        inner = 1
+        for s in shape[1:]:
+            inner *= int(s)
+        padding_per_block = stride[0] - inner if stride else 0
+    except Exception:
+        padding_per_block = -1
+    try:
+        storage_nbytes = rep.untyped_storage().nbytes()
+    except Exception:
+        storage_nbytes = -1
+    logger.info(
+        "Group %d first-layer tensor: layer_idx=%d shape=%s "
+        "stride=%s is_contiguous=%s dtype=%s device=%s "
+        "storage_offset=%d numel=%d storage_nbytes=%d "
+        "padding_per_block=%d",
+        group_idx,
+        layer_idx,
+        shape,
+        stride,
+        rep.is_contiguous(),
+        rep.dtype,
+        rep.device,
+        rep.storage_offset(),
+        rep.numel(),
+        storage_nbytes,
+        padding_per_block,
+    )
+
+    return block_stride_elems
+
+
+def make_page_buffer_shape_desc(
+    kv_caches: DiscoverableKVCache,
+    engine_kv_format: "lmc_ops.EngineKVFormat",
+    layer_idx: int,
+    num_layers_in_group: int,
+    num_blocks: int,
+    block_size: int,
+    block_stride_elems: Optional[int] = None,
+) -> "lmc_ops.PageBufferShapeDesc":
+    """Build a :class:`PageBufferShapeDesc` from a representative layer.
+
+    Args:
+        kv_caches: Full kv_caches structure.
+        engine_kv_format: Format returned by :func:`normalize_kv_and_discover_format`.
+        layer_idx: 0-based index of the representative layer.
+        num_layers_in_group: Number of layers in the group (``nl``).
+        num_blocks: Number of paged blocks (``nb``).
+        block_size: Tokens per block (``bs``).
+        block_stride_elems: Physical per-block stride in *elements*
+            (= ``tensor.stride(0)`` of the representative layer). Pass
+            the real value whenever the group's KV pool may be
+            dim-0-padded (e.g. DeepSeek V4 compressor/indexer caches
+            sharing a row width with a larger group in the same pool);
+            otherwise downstream transfer kernels will skip into
+            padding and corrupt data. Leave as ``None`` for unpadded
+            pools -- the kernel's ``per_block_stride()`` fallback
+            (block_stride_elems <= 0) will reconstruct the tight
+            stride from ``kv_size`` and ``scalars_per_block`` itself,
+            so we don't duplicate that arithmetic on the Python side.
+
+    Returns:
+        A populated ``PageBufferShapeDesc``.
+    """
+    desc = lmc_ops.PageBufferShapeDesc()
+    desc.kv_size = 1 if is_mla(engine_kv_format) else 2
+    desc.nl = num_layers_in_group
+    desc.nb = num_blocks
+    desc.bs = block_size
+    desc.nh = (
+        1
+        if is_mla(engine_kv_format)
+        else get_num_heads(kv_caches, engine_kv_format, layer_idx)
+    )
+    desc.hs = get_head_size(kv_caches, engine_kv_format, layer_idx)
+    dtype = get_dtype(kv_caches, engine_kv_format, layer_idx)
+    desc.element_size = dtype.itemsize
+    # The C++ PageBufferShapeDesc has no ``dtype`` field, but the pure-Python
+    # CPU fallback does -- and needs it to disambiguate float16 vs bfloat16
+    # (both have itemsize 2, so element_size alone is not enough). Best-effort.
+    set_shape_desc_dtype(desc, dtype)
+
+    resolved_stride = int(block_stride_elems) if block_stride_elems else 0
+    desc.block_stride_elems = resolved_stride
+    return desc
+
+
+def _split_token2d_kv(token2d: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+    """
+    Accepts either:
+      - [2, T, D]
+      - [T, 2, D]
+    Returns:
+      - k_tok: [T, D]
+      - v_tok: [T, D]
+    """
+    if token2d.dim() != 3:
+        raise ValueError(f"Expected token2d dim=3, got {token2d.shape}")
+    if token2d.shape[0] == 2:  # [2, T, D]
+        return token2d[0], token2d[1]
+    if token2d.shape[1] == 2:  # [T, 2, D]
+        return token2d[:, 0, :], token2d[:, 1, :]
+    raise ValueError(f"Unrecognized token2d layout: {token2d.shape}")
+
+
+def _get_head_size_view(
+    kv_cache_layer: Union[torch.Tensor, tuple[torch.Tensor, torch.Tensor]],
+    *,
+    use_mla: bool,
+    engine_kv_format: Optional["lmc_ops.EngineKVFormat"] = None,
+) -> Union[torch.Tensor, tuple[torch.Tensor, torch.Tensor]]:
+    """
+    Returns flattened views for index_copy/index_select.
+
+    If engine_kv_format is provided, use it to interpret tensor layout explicitly.
+    If not provided, fall back to current structural behavior:
+      - MLA: expects Tensor [P, B, HS]
+      - Non-MLA: expects either
+          * Tensor [2, P, B, NH, HS]  OR
+          * (k, v) tuple each [P, B, NH, HS]
+        (and also supports [P, 2, B, NH, HS] as a safe extension)
+    """
+    # -------------------------
+    # MLA
+    # -------------------------
+    if use_mla:
+        if not isinstance(kv_cache_layer, torch.Tensor):
+            raise ValueError("MLA expects kv_cache_layer as Tensor")
+        if kv_cache_layer.dim() != 3:
+            raise ValueError(f"MLA expects 3D [P,B,HS], got {kv_cache_layer.shape}")
+        p, b, hs = kv_cache_layer.shape
+        return kv_cache_layer.view(p * b, hs)
+
+    # -------------------------
+    # non-MLA (K/V)
+    # -------------------------
+    # If already provided (k, v) in canonical per-layer form, no format needed.
+    if not isinstance(kv_cache_layer, torch.Tensor):
+        k, v = kv_cache_layer
+        if k.dim() != 4 or v.dim() != 4:
+            raise ValueError(f"Expected (k,v) 4D [P,B,NH,HS], got {k.shape}, {v.shape}")
+        p, b, nh, hs = k.shape
+        if v.shape != (p, b, nh, hs):
+            raise ValueError(f"k/v shape mismatch: {k.shape} vs {v.shape}")
+        return k.view(p * b, nh * hs), v.view(p * b, nh * hs)
+
+    t = kv_cache_layer
+    if t.dim() != 5:
+        raise ValueError(f"Expected 5D tensor for non-MLA, got {t.shape}")
+
+    # If we have the format enum, decode explicitly.
+    if engine_kv_format is not None:
+        if engine_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS:
+            # per-layer: [2, NB, BS, NH, HS]
+            if t.shape[0] != 2:
+                raise ValueError(
+                    f"{engine_kv_format} expects [2,NB,BS,NH,HS], got {t.shape}"
+                )
+            k, v = t[0], t[1]  # [NB,BS,NH,HS]
+
+        elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS:
+            # per-layer: [NB, 2, BS, NH, HS]
+            if t.shape[1] != 2:
+                raise ValueError(
+                    f"{engine_kv_format} expects [NB,2,BS,NH,HS], got {t.shape}"
+                )
+            k, v = t[:, 0], t[:, 1]  # [NB,BS,NH,HS]
+
+        else:
+            # Other formats are either MLA-only or require upstream normalization.
+            raise NotImplementedError(
+                f"engine_kv_format={engine_kv_format} not supported in non-MLA "
+                "path here. Normalize to (k,v) tuple [NB,BS,NH,HS] per-layer "
+                "before calling."
+            )
+
+    else:
+        # No enum available: Assumed [2,P,B,H,D] (or [2,NB,BS,NH,HS] per-layer).
+        # Also accept [P,2,B,H,D] (or [NB,2,BS,NH,HS]) to be more robust.
+        if t.shape[0] == 2:
+            k, v = t[0], t[1]
+        elif t.shape[1] == 2:
+            k, v = t[:, 0], t[:, 1]
+        else:
+            raise ValueError(
+                f"engine_kv_format is None and tensor does not look like stacked KV. "
+                f"Expected axis0==2 or axis1==2, got {t.shape}"
+            )
+
+    if k.dim() != 4 or v.dim() != 4:
+        raise ValueError(f"Expected k/v 4D [NB,BS,NH,HS], got {k.shape}, {v.shape}")
+
+    nb, bs, nh, hs = k.shape
+    if v.shape != (nb, bs, nh, hs):
+        raise ValueError(f"k/v shape mismatch after decode: {k.shape} vs {v.shape}")
+
+    return k.view(nb * bs, nh * hs), v.view(nb * bs, nh * hs)
diff --git a/lmcache/v1/gpu_connector/xpu_connectors.py b/lmcache/v1/gpu_connector/xpu_connectors.py
new file mode 100644
index 0000000..6417604
--- /dev/null
+++ b/lmcache/v1/gpu_connector/xpu_connectors.py
@@ -0,0 +1,1796 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional, Tuple, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import ENGINE_NAME
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType, _lmcache_nvtx_annotate
+from lmcache.v1.compute.blend.utils import LMCBlenderBuilder
+from lmcache.v1.gpu_connector.gpu_connectors import GPUConnectorInterface
+from lmcache.v1.gpu_connector.utils import (
+    assert_is_vllm_flash_attn_or_flash_infer,
+    get_block_size,
+    get_elements_per_layer,
+    get_num_blocks,
+    get_page_buffer_size,
+    get_tokens_per_layer,
+    normalize_kv_and_discover_format,
+)
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+class VLLMPagedMemXPUConnectorV2(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a nested tuple of K and V tensors.
+    More specifically, we have:
+    - GPUTensor = Tuple[KVLayer, ...]
+    - KVLayer = Tuple[Tensor, Tensor]
+    - Tensor: [num_blocks, block_size, num_heads, head_size]
+
+    It will produce / consume memory object with KV_2LTD format
+    """
+
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_gpu: bool = False,
+        **kwargs,
+    ):
+        """
+        If use_gpu is true, it will create a gpu intermediate buffer. In this
+        case, it requires the following kwargs:
+        - chunk_size: The MAX size of the chunk to be copied to GPU.
+        - dtype: The data type of the intermediate buffer.
+        """
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+        self.kv_cache_pointers = torch.empty(
+            num_layers, dtype=torch.uint64, device="cpu"
+        )
+        # Not sure we need a dict here. Maybe a single GPU connector always
+        # works with a single device?
+        self.kv_cache_pointers_on_gpu: dict[int, torch.Tensor] = {}
+        self.page_buffer_size = 0
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        self.gpu_buffer: Optional[torch.Tensor] = None
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+        if use_gpu:
+            assert "chunk_size" in kwargs, (
+                "chunk_size should be provided to create a GPU buffer."
+            )
+            assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+            assert "device" in kwargs, (
+                "device should be provided to create a GPU buffer."
+            )
+            shape = self.get_shape(kwargs["chunk_size"])
+            self.gpu_buffer = torch.empty(
+                shape, dtype=kwargs["dtype"], device=kwargs["device"]
+            )
+
+        self.store_stream = torch.xpu.Stream()
+        self.load_stream = torch.xpu.Stream()
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+    ) -> "VLLMPagedMemXPUConnectorV2":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+
+        Returns:
+            A new instance of VLLMPagedMemXPUConnectorV2.
+        """
+        # Extract parameters from metadata
+        # kv_shape: (num_layer, 2 or 1, chunk_size, num_kv_head, head_size)
+        num_layers = metadata.kv_shape[0]
+        chunk_size = metadata.kv_shape[2]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_gpu=use_gpu,
+            chunk_size=chunk_size,
+            dtype=metadata.kv_dtype,
+            device=device,
+            use_mla=metadata.use_mla,
+        )
+
+    def _initialize_pointers(self, kv_caches: List[torch.Tensor]) -> torch.Tensor:
+        self.device = kv_caches[0].device
+        assert self.device.type == "xpu", "The device should be XPU."
+        idx = self.device.index
+        if idx in self.kv_cache_pointers_on_gpu:
+            return self.kv_cache_pointers_on_gpu[idx]
+        self.kv_cache_pointers.numpy()[:] = [t.data_ptr() for t in kv_caches]
+        self.kv_cache_pointers_on_gpu[idx] = torch.empty(
+            self.num_layers, dtype=torch.uint64, device=self.device
+        )
+        self.kv_cache_pointers_on_gpu[idx].copy_(self.kv_cache_pointers)
+
+        self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+            kv_caches, EngineType.VLLM
+        )
+        self.num_blocks = get_num_blocks(kv_caches, self.engine_kv_format)
+        self.block_size = get_block_size(kv_caches, self.engine_kv_format)
+        self.page_buffer_size = self.num_blocks * self.block_size
+
+        return self.kv_cache_pointers_on_gpu[idx]
+
+    @_lmcache_nvtx_annotate
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "full slot mapping"
+             where it's length is the same as the whole token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying XPU kernel will never see -1 in slot_mapping)
+
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs.
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if self.use_mla:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_MLA_FMT:
+                raise ValueError(
+                    "The memory object should be in KV_MLA_FMT format in"
+                    " order to be processed by VLLMPagedMemXPUConnector"
+                )
+        else:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_2LTD:
+                raise ValueError(
+                    "The memory object should be in KV_2LTD format in"
+                    " order to be processed by VLLMPagedMemXPUConnector"
+                )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(self.kvcaches)
+
+        # avoid read/write stream race condition for shared block
+        # this will only be potentially non-zero for the first
+        # block lmcache is transferring back
+        vllm_cached = kwargs.get("vllm_cached_tokens", 0)
+        skip_prefix_n_tokens = min(end - start, max(0, vllm_cached - start))
+
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj.tensor,
+            kv_cache_pointers,
+            slot_mapping[start:end],
+            self.device,
+            self.page_buffer_size,
+            lmc_ops.TransferDirection.H2D,
+            self.engine_kv_format,
+            self.block_size,
+            skip_prefix_n_tokens,
+        )
+
+    @_lmcache_nvtx_annotate
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Will set the memory_obj.metadata.fmt to MemoryFormat.KV_2LTD.
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "full slot mapping"
+             where it's length is the same as the whole token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying XPU kernel will never see -1 in slot_mapping)
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs,
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(self.kvcaches)
+
+        with torch.xpu.stream(self.store_stream):
+            if self.gpu_buffer is None or end - start != self.gpu_buffer.shape[2]:
+                lmc_ops.multi_layer_kv_transfer(
+                    memory_obj.tensor,
+                    kv_cache_pointers,
+                    slot_mapping[start:end],
+                    self.kvcaches[0].device,
+                    self.page_buffer_size,
+                    lmc_ops.TransferDirection.D2H,
+                    self.engine_kv_format,
+                    self.block_size,
+                )
+            else:
+                # kvcaches -> gpu_buffer -> memobj
+                assert self.gpu_buffer.device == self.kvcaches[0].device
+                tmp_gpu_buffer = self.gpu_buffer[:, :, : end - start, :]
+                lmc_ops.multi_layer_kv_transfer(
+                    tmp_gpu_buffer,
+                    kv_cache_pointers,
+                    slot_mapping[start:end],
+                    self.kvcaches[0].device,
+                    self.page_buffer_size,
+                    lmc_ops.TransferDirection.D2H,
+                    self.engine_kv_format,
+                    self.block_size,
+                )
+                memory_obj.tensor.copy_(tmp_gpu_buffer, non_blocking=True)
+
+        if not memory_obj.tensor.is_xpu:
+            # Force a synchronize if the target buffer is NOT XPU device
+            # NOTE: for better performance, we may not want to sync for every
+            # memory object
+            self.store_stream.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    # TODO(Jiayi): need to optimize to enable real batching
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        with torch.xpu.stream(self.load_stream):
+            for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+                self.to_gpu(memory_obj, start, end, **kwargs)
+        self.load_stream.synchronize()
+
+    # TODO(Jiayi): need to optimize to enable real batching
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        kv_size = 1 if self.use_mla else 2
+        return torch.Size([kv_size, self.num_layers, num_tokens, self.hidden_dim_size])
+
+
+class VLLMPagedMemXPUConnectorV3(GPUConnectorInterface):
+    def __init__(
+        self,
+        metadata: LMCacheMetadata,
+        device: torch.device,
+        use_gpu: bool = False,
+    ):
+        assert device.type == "xpu", "The device should be XPU."
+        self.metadata = metadata
+        self.device = device
+        self.use_mla = metadata.use_mla
+        self.chunk_size = metadata.chunk_size
+        self.use_gpu = use_gpu
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+        self.page_buffer_size = 0
+
+        self.init = False
+        self.group_kv_cache_pointers_on_gpu: Optional[list[torch.Tensor]] = None
+        self.group_tmp_buffer: Optional[list[torch.Tensor]] = None
+
+        self.store_stream = torch.xpu.Stream()
+        self.load_stream = torch.xpu.Stream()
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+    ) -> "VLLMPagedMemXPUConnectorV3":
+        assert device is not None
+        return cls(metadata, device, use_gpu)
+
+    def _initialize_kv_cache_pointers(self):
+        if self.init:
+            return
+        assert self.metadata.kv_layer_groups_manager.kv_layer_groups
+        if self.use_gpu:
+            # init tmp buffer
+            tmp_buf_shapes = self.metadata.get_shapes(self.chunk_size)
+            tmp_buf_dtypes = self.metadata.get_dtypes()
+            assert len(tmp_buf_shapes) == len(tmp_buf_dtypes)
+            self.group_tmp_buffer = [
+                torch.empty(tmp_buf_shape, dtype=tmp_buf_dtype, device=self.device)
+                for tmp_buf_shape, tmp_buf_dtype in zip(
+                    tmp_buf_shapes, tmp_buf_dtypes, strict=True
+                )
+            ]
+        self.group_kv_cache_pointers_on_gpu = []
+        for group in self.metadata.kv_layer_groups_manager.kv_layer_groups:
+            # init kv cache pointers
+            num_layers = group.num_layers
+            kv_cache_pointers = torch.empty(
+                num_layers, dtype=torch.uint64, device="cpu"
+            )
+            kv_cache_pointers.numpy()[:] = [
+                t.data_ptr()
+                for i, t in enumerate(self.kvcaches)
+                if i in group.layer_indices
+            ]
+            kv_cache_pointers_on_gpu = torch.empty(
+                num_layers, dtype=torch.uint64, device=self.device
+            )
+            kv_cache_pointers_on_gpu.copy_(kv_cache_pointers)
+            self.group_kv_cache_pointers_on_gpu.append(kv_cache_pointers_on_gpu)
+
+        self.engine_kv_format, self.kvcaches = normalize_kv_and_discover_format(
+            self.kvcaches, EngineType.VLLM
+        )
+        self.num_blocks = get_num_blocks(self.kvcaches, self.engine_kv_format)
+        self.block_size = get_block_size(self.kvcaches, self.engine_kv_format)
+        self.page_buffer_size = self.num_blocks * self.block_size
+
+        self.init = True
+        logger.info("init kv cache pointers success in VLLMPagedMemXPUConnectorV3")
+
+    @_lmcache_nvtx_annotate
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        assert memory_obj.raw_tensor is not None
+        assert "slot_mapping" in kwargs
+        if self.use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+        assert self.kvcaches[0].device == self.device
+        self._initialize_kv_cache_pointers()
+        assert self.group_kv_cache_pointers_on_gpu is not None
+
+        # avoid read/write stream race condition for shared block
+        # this will only be potentially non-zero for the first
+        # block lmcache is transferring back
+        vllm_cached = kwargs.get("vllm_cached_tokens", 0)
+        skip_prefix_n_tokens = min(end - start, max(0, vllm_cached - start))
+
+        for i, kv_cache_pointer in enumerate(self.group_kv_cache_pointers_on_gpu):
+            memory_obj_tensor = memory_obj.get_tensor(i)
+            assert memory_obj_tensor is not None
+            lmc_ops.multi_layer_kv_transfer(
+                memory_obj_tensor,
+                kv_cache_pointer,
+                slot_mapping[start:end],
+                self.device,
+                self.page_buffer_size,
+                lmc_ops.TransferDirection.H2D,
+                self.engine_kv_format,
+                self.block_size,
+                skip_prefix_n_tokens,
+            )
+
+    @_lmcache_nvtx_annotate
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        assert memory_obj.raw_tensor is not None
+        assert "slot_mapping" in kwargs
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None
+        assert self.kvcaches[0].device == self.device
+        self._initialize_kv_cache_pointers()
+        assert self.group_kv_cache_pointers_on_gpu is not None
+        with torch.xpu.stream(self.store_stream):
+            if not self.use_gpu or end - start != self.chunk_size:
+                for i, kv_cache_pointer in enumerate(
+                    self.group_kv_cache_pointers_on_gpu
+                ):
+                    memory_obj_tensor = memory_obj.get_tensor(i)
+                    assert memory_obj_tensor is not None
+                    lmc_ops.multi_layer_kv_transfer(
+                        memory_obj_tensor,
+                        kv_cache_pointer,
+                        slot_mapping[start:end],
+                        self.device,
+                        self.page_buffer_size,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        self.block_size,
+                    )
+            else:
+                # kvcaches -> gpu_buffer -> memobj
+                assert self.group_tmp_buffer is not None
+                for i, kv_cache_pointer in enumerate(
+                    self.group_kv_cache_pointers_on_gpu
+                ):
+                    tmp_gpu_buffer = self.group_tmp_buffer[i][:, :, : end - start, :]
+                    lmc_ops.multi_layer_kv_transfer(
+                        tmp_gpu_buffer,
+                        kv_cache_pointer,
+                        slot_mapping[start:end],
+                        self.device,
+                        self.page_buffer_size,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        self.block_size,
+                    )
+                    memory_obj_tensor = memory_obj.get_tensor(i)
+                    assert memory_obj_tensor is not None
+                    memory_obj_tensor.copy_(tmp_gpu_buffer, non_blocking=True)
+
+        if not memory_obj.raw_tensor.is_xpu:
+            # Force a synchronize if the target buffer is NOT XPU device
+            # NOTE: for better performance, we may not want to sync for every
+            # memory object
+            self.store_stream.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        with torch.xpu.stream(self.load_stream):
+            for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+                self.to_gpu(memory_obj, start, end, **kwargs)
+        self.load_stream.synchronize()
+
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        raise NotImplementedError
+
+
+class VLLMBufferLayerwiseXPUConnector(GPUConnectorInterface):
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_gpu: bool = False,
+        use_double_buffer: bool = True,
+        **kwargs,
+    ):
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        # TODO(Jiayi): remove this hardcode
+        self.cache_positions = True
+
+        self.fused_rotary_emb = None
+
+        assert use_gpu, "use_gpu must be true in VLLMBufferLayerwiseXPUConnector"
+        assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+        assert "device" in kwargs, "device should be provided to create a GPU buffer."
+
+        self.dtype = kwargs["dtype"]
+        self.device = kwargs["device"]
+
+        self.load_stream = torch.xpu.Stream()
+        self.store_stream = torch.xpu.Stream()
+
+        self.buffer_mapping: dict[int, MemoryObj] = {}
+
+        # track gap positions between blended chunks
+        self.current_gap_positions = None
+
+        self.use_gpu = use_gpu
+        self.gpu_buffer_allocator = None
+        self.element_size = torch.tensor([], dtype=self.dtype).element_size()
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+    ) -> "VLLMBufferLayerwiseXPUConnector":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+
+        Returns:
+            A new instance of VLLMBufferLayerwiseXPUConnector.
+        """
+        # Extract parameters from metadata
+        # kv_shape: (num_layer, 2 or 1, chunk_size, num_kv_head, head_size)
+        num_layers = metadata.kv_shape[0]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_gpu=use_gpu,
+            dtype=metadata.kv_dtype,
+            device=device,
+        )
+
+    def _lazy_initialize_buffer(self, kv_caches):
+        """
+        Lazily initialize the GPU buffer allocator if it is not initialized yet.
+        Currently, we use the `kv_caches` (kv cache pointer) to determine
+        the gpu buffer size in gpu connector.
+        Also, the first request might be a bit slower due to buffer creation.
+        """
+        if self.use_gpu and self.gpu_buffer_allocator is None:
+            logger.info("Lazily initializing GPU buffer.")
+            # NOTE (Jiayi): We use the first layer to determine the gpu buffer size.
+            # NOTE (Jiayi): Using the exact number of tokens in the first layer
+            # is okay since fragmentation shouldn't exist in the `gpu_buffer_allocator`
+            # in layerwise mode.
+
+            self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+                kv_caches, EngineType.VLLM
+            )
+            assert_is_vllm_flash_attn_or_flash_infer(self.engine_kv_format)
+            self.tokens_per_layer = get_tokens_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            self.elements_per_layer = get_elements_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            logger.info(
+                f"Lazily initializing GPU buffer (max tokens={self.tokens_per_layer})."
+            )
+            gpu_buffer_size = self.elements_per_layer * self.element_size
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                gpu_buffer_size, device=self.device
+            )
+
+    def get_kv(self, layer_id: int) -> Tuple[torch.Tensor, torch.Tensor]:
+        """
+        Get the KV cache for the given layer ID.
+        This function is used to get the KV cache from the GPU buffer.
+        """
+        if layer_id not in self.buffer_mapping:
+            raise ValueError(f"Layer {layer_id} is not loaded into GPU buffer.")
+
+        gpu_buffer = self.buffer_mapping[layer_id].tensor
+        assert gpu_buffer is not None
+        return gpu_buffer[0], gpu_buffer[1]
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    @_lmcache_nvtx_annotate
+    def batched_to_gpu(self, starts: List[int], ends: List[int], **kwargs):
+        """
+        This function is a generator that moves the KV cache from the memory
+        objects to buffer GPU memory. In each iteration i, it (1) loads the KV
+        cache of layer i from CPU -> GPU buffer, (2) recovers the positional
+        encoding of the layer i-1's KV cache in the GPU buffer, and (3)
+        moves the KV cache of layer i-2 from GPU buffer to paged GPU memory.
+        In total, this the generator will yield num_layers + 2 times.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if self.fused_rotary_emb is None and self.cache_positions:
+            # TODO(Jiayi): Make this more elegant
+            self.lmc_model = LMCBlenderBuilder.get(ENGINE_NAME).layerwise_model
+            self.fused_rotary_emb = self.lmc_model.fused_rotary_emb
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        num_all_tokens = ends[-1] - starts[0]
+        slot_mapping_full = slot_mapping[starts[0] : ends[-1]]
+
+        # compute gap positions
+        gap_mask = torch.ones(
+            num_all_tokens, dtype=torch.bool, device=slot_mapping_full.device
+        )
+        buf_offset = starts[0]
+
+        for start, end in zip(starts, ends, strict=False):
+            gap_mask[start - buf_offset : end - buf_offset] = False
+
+        self.current_gap_positions = torch.where(gap_mask)[0]
+
+        buf_offset = starts[0]
+        if self.cache_positions:
+            new_positions_full = torch.arange(
+                starts[0], ends[-1], dtype=torch.int64, device=self.kvcaches[0].device
+            )
+
+        buffer_shape = self.get_shape(num_all_tokens)
+        assert self.gpu_buffer_allocator is not None
+        compute_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+            buffer_shape, self.dtype, MemoryFormat.KV_2TD
+        )
+        load_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+            buffer_shape, self.dtype, MemoryFormat.KV_2TD
+        )
+        assert compute_gpu_buffer_obj is not None, (
+            "Failed to allocate GPU buffer in GPUConnector"
+        )
+        assert load_gpu_buffer_obj is not None, (
+            "Failed to allocate GPU buffer in GPUConnector"
+        )
+        assert compute_gpu_buffer_obj.tensor is not None
+        assert load_gpu_buffer_obj.tensor is not None
+
+        # current_stream = torch.xpu.current_stream()
+
+        if self.cache_positions:
+            old_positions_full = torch.zeros(
+                (num_all_tokens,), dtype=torch.int64, device=self.kvcaches[0].device
+            )
+        for layer_id in range(self.num_layers + 2):
+            if layer_id > 1:
+                lmc_ops.single_layer_kv_transfer(
+                    self.buffer_mapping[layer_id - 2].tensor,
+                    self.kvcaches[layer_id - 2],
+                    slot_mapping_full,
+                    lmc_ops.TransferDirection.H2D,
+                    self.engine_kv_format,
+                    token_major=False,  # shape is [2, num_tokens, hidden_dim]
+                )
+                del self.buffer_mapping[layer_id - 2]
+
+                logger.debug(f"Finished loading layer {layer_id - 2} into paged memory")
+
+            if layer_id > 0 and layer_id <= self.num_layers:
+                # NOTE: wait until both compute and load streams are done
+                torch.xpu.synchronize()
+
+                # ping-pong the buffers
+                compute_gpu_buffer_obj, load_gpu_buffer_obj = (
+                    load_gpu_buffer_obj,
+                    compute_gpu_buffer_obj,
+                )
+
+                if self.cache_positions:
+                    assert compute_gpu_buffer_obj.tensor is not None
+
+                    compute_gpu_buffer_obj.tensor[0] = self.fused_rotary_emb(
+                        old_positions_full,
+                        new_positions_full,
+                        compute_gpu_buffer_obj.tensor[0],
+                    )
+
+                # gap zeroing after RoPE
+                if self.current_gap_positions.numel():
+                    compute_gpu_buffer_obj.tensor[:, self.current_gap_positions] = 0.0
+
+                self.buffer_mapping[layer_id - 1] = compute_gpu_buffer_obj
+
+                logger.debug(f"Finished loading layer {layer_id - 1} into buffer")
+
+            if layer_id < self.num_layers:
+                memory_objs_layer = yield
+
+                # memobj -> gpu_buffer
+                with torch.xpu.stream(self.load_stream):
+                    for start, end, memory_obj in zip(
+                        starts, ends, memory_objs_layer, strict=False
+                    ):
+                        assert memory_obj.metadata.fmt == MemoryFormat.KV_2TD
+                        assert load_gpu_buffer_obj.tensor is not None
+                        load_gpu_buffer_obj.tensor[0][
+                            start - buf_offset : end - buf_offset
+                        ].copy_(memory_obj.tensor[0], non_blocking=True)
+
+                        load_gpu_buffer_obj.tensor[1][
+                            start - buf_offset : end - buf_offset
+                        ].copy_(memory_obj.tensor[1], non_blocking=True)
+
+                        if self.cache_positions and layer_id == 0:
+                            old_positions_full[
+                                start - buf_offset : end - buf_offset
+                            ] = memory_obj.metadata.cached_positions
+
+            elif layer_id == self.num_layers:
+                yield
+
+        # free the buffer memory
+        load_gpu_buffer_obj.ref_count_down()
+        compute_gpu_buffer_obj.ref_count_down()
+
+        assert len(self.buffer_mapping) == 0, (
+            "There are still layers in the buffer mapping after "
+            "releasing the GPU buffers."
+        )
+
+        yield
+
+    # TODO(Jiayi): Reduce repetitive operations in `batched_to_gpu`
+    # and `batched_from_gpu`.
+    @_lmcache_nvtx_annotate
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]], List[MemoryObj]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        This function is a generator that moves the KV cache from the paged GPU
+        memory to the memory objects. The first iteration will prepare some
+        related metadata and initiate the transfer in the first layer. In each
+        of the following iterations, it will first wait until the storing of
+        previous layer finishes, and then initiate string the KV cache of the
+        current layer one. The storing process of the KV cache is paged GPU
+        memory -> GPU buffer -> memory objects. The last iteration simply waits
+        for the last layer to finish.
+        In total, this the generator will yield num_layers + 1 times.
+
+        :param memory_objs: The memory objects to store the KV cache. The first
+            dimension is the number of layers, and the second dimension is the
+            number of memory objects (i.e., number of chunks) for each layer.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        buf_start = 0
+        slot_mapping_chunks = []
+        buf_starts_ends = []
+        old_positions_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            buf_end = buf_start + end - start
+            buf_starts_ends.append((buf_start, buf_end))
+            slot_mapping_chunks.append(slot_mapping[start:end])
+            buf_start = buf_end
+            if self.cache_positions:
+                old_positions_chunks.append(
+                    torch.arange(
+                        start, end, device=self.kvcaches[0].device, dtype=torch.int64
+                    )
+                )
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+        buffer_shape = self.get_shape(num_tokens)
+        assert self.gpu_buffer_allocator is not None
+        tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+            buffer_shape, self.dtype, MemoryFormat.KV_2TD
+        )
+        assert tmp_gpu_buffer_obj is not None, (
+            "Failed to allocate GPU buffer in GPUConnector"
+        )
+        assert tmp_gpu_buffer_obj.tensor is not None
+
+        current_stream = torch.xpu.current_stream()
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = memory_objs[layer_id]
+            # kvcaches -> gpu_buffer -> memobj
+            with torch.xpu.stream(self.store_stream):
+                self.store_stream.wait_stream(current_stream)
+                lmc_ops.single_layer_kv_transfer(
+                    tmp_gpu_buffer_obj.tensor,
+                    self.kvcaches[layer_id],
+                    slot_mapping_full,
+                    lmc_ops.TransferDirection.D2H,
+                    self.engine_kv_format,
+                    token_major=False,  # shape is [2, num_tokens, hidden_dim]
+                )
+                for (buf_start, buf_end), memory_obj, old_positions in zip(
+                    buf_starts_ends,
+                    memory_objs_layer,
+                    old_positions_chunks,
+                    strict=False,
+                ):
+                    assert memory_obj.tensor is not None
+                    memory_obj.tensor[0].copy_(
+                        tmp_gpu_buffer_obj.tensor[0][buf_start:buf_end],
+                        non_blocking=True,
+                    )
+                    memory_obj.tensor[1].copy_(
+                        tmp_gpu_buffer_obj.tensor[1][buf_start:buf_end],
+                        non_blocking=True,
+                    )
+                    if self.cache_positions:
+                        memory_obj.metadata.cached_positions = old_positions
+
+            yield
+            self.store_stream.synchronize()
+            logger.debug(f"Finished offloading layer {layer_id}")
+
+        # free the buffer memory
+        tmp_gpu_buffer_obj.ref_count_down()
+        yield
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        return torch.Size([2, num_tokens, self.hidden_dim_size])
+
+
+class VLLMPagedMemLayerwiseXPUConnector(GPUConnectorInterface):
+    """ """
+
+    def __init__(
+        self,
+        hidden_dim_size: int,
+        num_layers: int,
+        use_gpu: bool = False,
+        **kwargs,
+    ):
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+        self.use_gpu = use_gpu
+
+        self.gpu_buffer_allocator = None
+
+        assert "chunk_size" in kwargs, (
+            "chunk_size should be provided to create a GPU buffer."
+        )
+        assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+        assert "device" in kwargs, "device should be provided to create a GPU buffer."
+
+        self.dtype = kwargs["dtype"]
+        self.device = kwargs["device"]
+
+        self.kvcaches: Optional[List[torch.Tensor]] = None
+
+        # All sizes are in bytes
+        self.element_size = torch.tensor([], dtype=self.dtype).element_size()
+
+        self.load_stream = torch.xpu.Stream()
+        self.store_stream = torch.xpu.Stream()
+
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+    @classmethod
+    def from_metadata(
+        cls,
+        metadata: LMCacheMetadata,
+        use_gpu: bool = False,
+        device: Optional[torch.device] = None,
+    ) -> "VLLMPagedMemLayerwiseXPUConnector":
+        """Create a connector from LMCacheMetadata.
+
+        Args:
+            metadata: The LMCache engine metadata containing model configuration.
+            use_gpu: Whether to use GPU intermediate buffer.
+            device: The device to use for the connector.
+
+        Returns:
+            A new instance of VLLMPagedMemLayerwiseXPUConnector.
+        """
+        # Extract parameters from metadata
+        # kv_shape: (num_layer, 2 or 1, chunk_size, num_kv_head, head_size)
+        num_layers = metadata.kv_shape[0]
+        chunk_size = metadata.kv_shape[2]
+        num_kv_head = metadata.kv_shape[3]
+        head_size = metadata.kv_shape[4]
+        hidden_dim_size = num_kv_head * head_size
+
+        return cls(
+            hidden_dim_size=hidden_dim_size,
+            num_layers=num_layers,
+            use_gpu=use_gpu,
+            chunk_size=chunk_size,
+            dtype=metadata.kv_dtype,
+            device=device,
+            use_mla=metadata.use_mla,
+        )
+
+    def _lazy_initialize_buffer(self, kv_caches):
+        """
+        Lazily initialize the GPU buffer allocator if it is not initialized yet.
+        Currently, we use the `kv_caches` (kv cache pointer) to determine
+        the gpu buffer size in gpu connector.
+        Also, the first request might be a bit slower due to buffer creation.
+        """
+        if self.use_gpu and self.gpu_buffer_allocator is None:
+            logger.info("Lazily initializing GPU buffer.")
+            # NOTE (Jiayi): We use the first layer to determine the gpu buffer size.
+            # NOTE (Jiayi): Using the exact number of tokens in the first layer
+            # is okay since fragmentation shouldn't exist in the `gpu_buffer_allocator`
+            # in layerwise mode.
+
+            self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+                kv_caches, EngineType.VLLM
+            )
+            assert_is_vllm_flash_attn_or_flash_infer(self.engine_kv_format)
+            self.tokens_per_layer = get_tokens_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            self.elements_per_layer = get_elements_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            logger.info(
+                f"Lazily initializing GPU buffer (max tokens={self.tokens_per_layer})."
+            )
+            gpu_buffer_size = self.elements_per_layer * self.element_size
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                gpu_buffer_size, device=self.device
+            )
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """ """
+
+        raise NotImplementedError
+
+    @_lmcache_nvtx_annotate
+    def batched_to_gpu(self, starts: List[int], ends: List[int], **kwargs):
+        """
+        This function is a generator that moves the KV cache from the memory
+        objects to paged GPU memory. The first iteration will prepare some
+        related metadata. In each of the following iterations, it will first
+        wait until the loading of the previous layer finish, and then load
+        one layer of KV cache from the memory objects -> GPU buffer ->
+        paged GPU memory. The last iteration simply waits for the last layer
+        to finish.
+        In total, this the generator will yield num_layers + 2 times.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        sync: bool = kwargs["sync"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        # TODO(Jiayi): Optimize away this `cat`
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        tmp_gpu_buffer_obj: Optional[MemoryObj] = None
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+            assert self.gpu_buffer_allocator is not None
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, MemoryFormat.KV_T2D
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        offset = starts[0]
+        current_stream = torch.xpu.current_stream()
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = yield
+            if sync:
+                current_stream.wait_stream(self.load_stream)
+            if layer_id > 0:
+                logger.debug(f"Finished loading layer {layer_id - 1}")
+
+            # memobj -> gpu_buffer -> kvcaches
+            with torch.xpu.stream(self.load_stream):
+                for start, end, memory_obj in zip(
+                    starts, ends, memory_objs_layer, strict=False
+                ):
+                    # Validate memory format
+                    if self.use_mla:
+                        assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT, (
+                            f"Expected memory format {MemoryFormat.KV_MLA_FMT}, "
+                            f"got {memory_obj.metadata.fmt}"
+                        )
+                    else:
+                        assert memory_obj.metadata.fmt == MemoryFormat.KV_T2D, (
+                            f"Expected memory format {MemoryFormat.KV_T2D}, "
+                            f"got {memory_obj.metadata.fmt}"
+                        )
+                    if self.use_gpu:
+                        tmp_gpu_buffer_obj.tensor[start - offset : end - offset].copy_(
+                            memory_obj.tensor, non_blocking=True
+                        )
+                    else:
+                        lmc_ops.single_layer_kv_transfer(
+                            memory_obj.tensor,
+                            self.kvcaches[layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.H2D,
+                            self.engine_kv_format,
+                            token_major=True,
+                        )
+
+                if self.use_gpu:
+                    lmc_ops.single_layer_kv_transfer(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[layer_id],
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.H2D,
+                        self.engine_kv_format,
+                        token_major=True,
+                    )
+        yield
+
+        # synchronize the last layer
+        if sync:
+            current_stream.wait_stream(self.load_stream)
+
+        # free the buffer memory
+        if tmp_gpu_buffer_obj is not None:
+            tmp_gpu_buffer_obj.ref_count_down()
+
+        logger.debug(f"Finished loading all {self.num_layers} layers.")
+        yield
+
+    @_lmcache_nvtx_annotate
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        This function is a generator that moves the KV cache from the paged GPU
+        memory to the memory objects. The first iteration will prepare some
+        related metadata and initiate the transfer in the first layer. In each
+        of the following iterations, it will first wait until the storing of
+        previous layer finishes, and then initiate string the KV cache of the
+        current layer one. The storing process of the KV cache is paged GPU
+        memory -> GPU buffer -> memory objects. The last iteration simply waits
+        for the last layer to finish.
+        In total, this the generator will yield num_layers + 1 times.
+
+        :param memory_objs: The memory objects to store the KV cache. The first
+            dimension is the number of layers, and the second dimension is the
+            number of memory objects (i.e., number of chunks) for each layer.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+        sync: bool = kwargs["sync"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        tmp_gpu_buffer_obj: Optional[MemoryObj] = None
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+            assert self.gpu_buffer_allocator is not None
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, MemoryFormat.KV_T2D
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        offset = starts[0]
+        current_stream = torch.xpu.current_stream()
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = memory_objs[layer_id]
+            # kvcaches -> gpu_buffer -> memobj
+            with torch.xpu.stream(self.store_stream):
+                self.store_stream.wait_stream(current_stream)
+                if self.use_gpu:
+                    lmc_ops.single_layer_kv_transfer(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[layer_id],
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        token_major=True,
+                    )
+                for start, end, memory_obj in zip(
+                    starts, ends, memory_objs_layer, strict=False
+                ):
+                    assert memory_obj.tensor is not None
+                    if self.use_gpu:
+                        memory_obj.tensor.copy_(
+                            tmp_gpu_buffer_obj.tensor[start - offset : end - offset],
+                            non_blocking=True,
+                        )
+                    else:
+                        lmc_ops.single_layer_kv_transfer(
+                            memory_obj.tensor,
+                            self.kvcaches[layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.D2H,
+                            self.engine_kv_format,
+                            token_major=True,
+                        )
+                    # Set metadata format
+                    if self.use_mla:
+                        memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+            yield
+            if sync:
+                self.store_stream.synchronize()
+            logger.debug(f"Finished offloading layer {layer_id}")
+
+        # free the buffer memory
+        if tmp_gpu_buffer_obj is not None:
+            tmp_gpu_buffer_obj.ref_count_down()
+
+        yield
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        if self.use_mla:
+            # MLA format: [num_tokens, hidden_dim_size]
+            return torch.Size([num_tokens, self.hidden_dim_size])
+        else:
+            # Standard format: [num_tokens, 2, hidden_dim_size]
+            return torch.Size([num_tokens, 2, self.hidden_dim_size])
+
+
+class SGLangXPUConnector(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a list of tensors, one for each layer,
+    with separate key and value pointers.
+    More specifically, we have:
+    - kvcaches: Tuple[List[Tensor], List[Tensor]]
+      - The first element is a list of key tensors, one per layer.
+      - The second element is a list of value tensors, one per layer.
+    - Each tensor: [page_buffer_size, head_num, head_size]
+
+    The connector manages the transfer of KV cache data between CPU and GPU
+    memory for SGLang using pointer arrays for efficient access.
+    It will produce/consume memory objects with KV_2LTD format.
+    """
+
+    def __init__(
+        self, hidden_dim_size: int, num_layers: int, use_gpu: bool = False, **kwargs
+    ):
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+
+        self.kv_cache_pointers_on_gpu: dict[int, torch.Tensor] = {}
+        self.page_buffer_size = 0
+
+        self.gpu_buffer: Optional[torch.Tensor] = None
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+        self.num_kv_cache = num_layers if self.use_mla else num_layers * 2
+        self.kv_cache_pointers = torch.empty(
+            self.num_kv_cache, dtype=torch.uint64, device="cpu"
+        )
+
+        if use_gpu:
+            assert "chunk_size" in kwargs, (
+                "chunk_size should be provided to create a GPU buffer."
+            )
+            assert "device" in kwargs, (
+                "device should be provided to create a GPU buffer."
+            )
+            shape = self.get_shape(kwargs["chunk_size"])
+            self.gpu_buffer = torch.empty(
+                shape, dtype=kwargs["dtype"], device=kwargs["device"]
+            )
+            logger.info(f"GPU buffer: {self.gpu_buffer.shape}")
+
+    def _initialize_pointers(self, kv_caches: List[torch.Tensor]) -> torch.Tensor:
+        # Discover format first to handle flattening correctly
+        self.engine_kv_format, kv_caches = normalize_kv_and_discover_format(
+            kv_caches, EngineType.SGLANG
+        )
+
+        # For TWO_X_NL_X_NBBS_NH_HS format, kv_caches is [[k_list], [v_list]]
+        # We need to flatten it to [k0, k1, ..., v0, v1, ...]
+        if self.engine_kv_format == lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS:
+            flat_kv_caches = kv_caches[0] + kv_caches[1]  # [k_list] + [v_list]
+            device = flat_kv_caches[0].device
+        else:
+            flat_kv_caches = kv_caches
+            device = flat_kv_caches[0].device
+
+        assert len(flat_kv_caches) == self.num_kv_cache, (
+            f"Expected {self.num_kv_cache} KV caches, got {len(flat_kv_caches)}"
+        )
+
+        self.kv_cache_pointers.numpy()[:] = [t.data_ptr() for t in flat_kv_caches]
+        assert device.type == "xpu", "The device should be XPU."
+        idx = device.index
+        if idx not in self.kv_cache_pointers_on_gpu:
+            self.kv_cache_pointers_on_gpu[idx] = torch.empty(
+                self.num_kv_cache, dtype=torch.uint64, device=device
+            )
+        self.kv_cache_pointers_on_gpu[idx].copy_(self.kv_cache_pointers)
+
+        # sglang MLA kv_caches[0].shape: [num_pages * page_size, 1, head_size]
+        # sglang MHA kv_caches: [[k_list], [v_list]]
+        # each with shape [num_pages * page_size, num_heads, head_size]
+        self.page_buffer_size = get_page_buffer_size(kv_caches, self.engine_kv_format)
+        return self.kv_cache_pointers_on_gpu[idx]
+
+    @_lmcache_nvtx_annotate
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "partial slot mapping"
+             where its length is the same as the uncached token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying XPU kernel will never see -1 in slot_mapping)
+
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs.
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        if self.use_mla:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_MLA_FMT:
+                raise ValueError(
+                    "The memory object should be in KV_MLA_FMT format in"
+                    f" order to be processed by {self.__class__.__name__}"
+                )
+        else:
+            if memory_obj.metadata.fmt != MemoryFormat.KV_2LTD:
+                raise ValueError(
+                    "The memory object should be in KV_2LTD format in"
+                    f" order to be processed by {self.__class__.__name__}"
+                )
+
+        if "kvcaches" not in kwargs:
+            raise ValueError("'kvcaches' should be provided in kwargs.")
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        offset = kwargs.get("offset", 0)
+
+        kvcaches: List[torch.Tensor] = kwargs["kvcaches"]
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(kvcaches)
+        lmc_ops.multi_layer_kv_transfer_unilateral(
+            memory_obj.tensor,
+            kv_cache_pointers,
+            slot_mapping[start - offset : end - offset],
+            kvcaches[0][0].device,
+            self.page_buffer_size,
+            lmc_ops.TransferDirection.H2D,
+            self.engine_kv_format,
+        )
+
+    @_lmcache_nvtx_annotate
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        """Expect a kwarg 'kvcaches' which is a nested tuple of K and V tensors.
+        The kvcaches should correspond to the "WHOLE token sequence".
+
+        Will set the memory_obj.metadata.fmt to MemoryFormat.KV_2LTD.
+
+        Note:
+          1. This function expects the 'slot_mapping' is a "partial slot mapping"
+             where its length is the same as the uncached token sequence.
+          2. In the case that there is prefix caching, slot_mapping will starts
+             with -1s until the end of the matched prefix. The start and end
+             should NEVER overlap with the prefix caching (which means the
+             underlying XPU kernel will never see -1 in slot_mapping)
+
+        :raises ValueError: If 'kvcaches' is not provided in kwargs,
+        :raises AssertionError: If the memory object does not have a tensor.
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+        assert memory_obj.tensor is not None
+
+        if "kvcaches" not in kwargs:
+            raise ValueError("'kvcaches' should be provided in kwargs.")
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        kvcaches: List[torch.Tensor] = kwargs["kvcaches"]
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        kv_cache_pointers = self._initialize_pointers(kvcaches)
+
+        if self.gpu_buffer is None or end - start != self.gpu_buffer.shape[2]:
+            lmc_ops.multi_layer_kv_transfer_unilateral(
+                memory_obj.tensor,
+                kv_cache_pointers,
+                slot_mapping[start:end],
+                kvcaches[0][0].device,
+                self.page_buffer_size,
+                lmc_ops.TransferDirection.D2H,
+                self.engine_kv_format,
+            )
+        else:
+            # kvcaches -> gpu_buffer -> memobj
+            assert self.gpu_buffer.device == kvcaches[0][0].device
+            tmp_gpu_buffer = self.gpu_buffer[:, :, : end - start, :]
+            lmc_ops.multi_layer_kv_transfer_unilateral(
+                tmp_gpu_buffer,
+                kv_cache_pointers,
+                slot_mapping[start:end],
+                kvcaches[0][0].device,
+                self.page_buffer_size,
+                lmc_ops.TransferDirection.D2H,
+                self.engine_kv_format,
+            )
+            memory_obj.tensor.copy_(tmp_gpu_buffer, non_blocking=True)
+
+        if not memory_obj.tensor.is_xpu:
+            # Force a synchronize if the target buffer is NOT XPU device
+            # NOTE: for better performance, we may not want to sync for every
+            # memory object
+            torch.xpu.synchronize()
+
+        if self.use_mla:
+            memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        return torch.Size([2, self.num_layers, num_tokens, self.hidden_dim_size])
+
+    def batched_to_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.to_gpu(memory_obj, start, end, **kwargs)
+
+    def batched_from_gpu(self, memory_objs, starts, ends, **kwargs):
+        for memory_obj, start, end in zip(memory_objs, starts, ends, strict=False):
+            self.from_gpu(memory_obj, start, end, **kwargs)
+
+
+class SGLangLayerwiseXPUConnector(GPUConnectorInterface):
+    """
+    The GPU KV cache should be a list of tensors, one for each layer.
+    More specifically, we have:
+        - MHA: kvcaches is Tuple[List[Tensor], List[Tensor]] (K/V lists)
+        - MLA: kvcaches is List[Tensor]
+
+    The connector manages transfer of KV cache data between CPU and GPU memory
+    for SGLang layerwise loading/offloading in both MHA and MLA modes.
+    """
+
+    def __init__(
+        self, hidden_dim_size: int, num_layers: int, use_gpu: bool = False, **kwargs
+    ):
+        assert "dtype" in kwargs, "dtype should be provided to create a GPU buffer."
+        self.dtype = kwargs["dtype"]
+        assert "device" in kwargs, "device should be provided to create a GPU buffer."
+        self.device = kwargs["device"]
+
+        self.hidden_dim_size = hidden_dim_size
+        self.num_layers = num_layers
+
+        self.kv_cache_pointers_on_gpu: dict[int, torch.Tensor] = {}
+        self.page_buffer_size = 0
+
+        self.gpu_buffer: Optional[torch.Tensor] = None
+        self.use_mla = "use_mla" in kwargs and kwargs["use_mla"]
+
+        self.num_kv_cache = num_layers if self.use_mla else num_layers * 2
+        self.element_size = torch.tensor([], dtype=self.dtype).element_size()
+        self.kv_cache_pointers = torch.empty(
+            self.num_kv_cache, dtype=torch.uint64, device="cpu"
+        )
+        self.use_gpu = use_gpu
+        self.engine_kv_format = None
+        self.gpu_buffer_allocator: Optional[GPUMemoryAllocator] = None
+
+    def _lazy_initialize_buffer(self, kv_caches):
+        """
+        Lazily initialize the GPU buffer allocator if it is not initialized yet.
+        Currently, we use the `kv_caches` (kv cache pointer) to determine
+        the gpu buffer size in gpu connector.
+        Also, the first request might be a bit slower due to buffer creation.
+        """
+        discovered_format, normalized_kv_caches = normalize_kv_and_discover_format(
+            kv_caches, EngineType.SGLANG
+        )
+        if self.engine_kv_format is None:
+            self.engine_kv_format = discovered_format
+
+        if self.use_gpu and self.gpu_buffer_allocator is None:
+            self.tokens_per_layer = get_tokens_per_layer(
+                kv_caches, self.engine_kv_format
+            )
+            self.elements_per_layer = get_elements_per_layer(
+                normalized_kv_caches, self.engine_kv_format
+            )
+            logger.info(
+                f"Lazily initializing GPU buffer (max tokens={self.tokens_per_layer})."
+            )
+            gpu_buffer_size = self.elements_per_layer * self.element_size
+            logger.info(
+                f"Lazily initializing GPU buffer (gpu buffer size={gpu_buffer_size})."
+            )
+            self.gpu_buffer_allocator = GPUMemoryAllocator(
+                gpu_buffer_size, device=self.device
+            )
+
+    def to_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        raise NotImplementedError
+
+    def from_gpu(self, memory_obj: MemoryObj, start: int, end: int, **kwargs):
+        raise NotImplementedError
+
+    @_lmcache_nvtx_annotate
+    def batched_to_gpu(self, starts: List[int], ends: List[int], **kwargs):
+        """
+        This function is a generator that moves the KV cache from the memory
+        objects to paged GPU memory. The first iteration will prepare some
+        related metadata. In each of the following iterations, it will first
+        wait until the loading of the previous layer finish, and then load
+        one layer of KV cache from the memory objects -> GPU buffer ->
+        paged GPU memory. The last iteration simply waits for the last layer
+        to finish.
+        In total, this the generator will yield num_layers + 2 times.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+
+            assert self.gpu_buffer_allocator is not None, (
+                "GPU buffer allocator should be initialized"
+            )
+            memory_format = (
+                MemoryFormat.KV_MLA_FMT if self.use_mla else MemoryFormat.KV_T2D
+            )
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, memory_format
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        offset = starts[0]
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = yield
+            if layer_id > 0:
+                logger.debug(f"Finished loading layer {layer_id - 1}")
+
+            # memobj -> gpu_buffer -> kvcaches
+            for start, end, memory_obj in zip(
+                starts, ends, memory_objs_layer, strict=False
+            ):
+                if self.use_mla:
+                    assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+                else:
+                    assert memory_obj.metadata.fmt == MemoryFormat.KV_T2D
+                if self.use_gpu:
+                    tmp_gpu_buffer_obj.tensor[start - offset : end - offset].copy_(
+                        memory_obj.tensor, non_blocking=True
+                    )
+                else:
+                    if self.use_mla:
+                        lmc_ops.single_layer_kv_transfer(
+                            memory_obj.tensor,
+                            self.kvcaches[layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.H2D,
+                            self.engine_kv_format,
+                            token_major=True,
+                        )
+                    else:
+                        lmc_ops.single_layer_kv_transfer_sgl(
+                            memory_obj.tensor,
+                            self.kvcaches[0][layer_id],
+                            self.kvcaches[1][layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.H2D,
+                            token_major=True,
+                        )
+
+            if self.use_gpu:
+                if self.use_mla:
+                    lmc_ops.single_layer_kv_transfer(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[layer_id],
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.H2D,
+                        self.engine_kv_format,
+                        token_major=True,
+                    )
+                else:
+                    t, h, d = self.kvcaches[0][layer_id].shape
+                    lmc_ops.single_layer_kv_transfer_sgl(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[0][layer_id].view(t, 1, h, d),
+                        self.kvcaches[1][layer_id].view(t, 1, h, d),
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.H2D,
+                        token_major=True,
+                    )
+
+        # free the buffer memory
+        if self.use_gpu:
+            tmp_gpu_buffer_obj.ref_count_down()
+
+        logger.debug(f"Finished loading layer {layer_id}")
+        yield
+
+    @_lmcache_nvtx_annotate
+    def batched_from_gpu(
+        self,
+        memory_objs: Union[List[List[MemoryObj]]],
+        starts: List[int],
+        ends: List[int],
+        **kwargs,
+    ):
+        """
+        This function is a generator that moves the KV cache from the paged GPU
+        memory to the memory objects. The first iteration will prepare some
+        related metadata and initiate the transfer in the first layer. In each
+        of the following iterations, it will first wait until the storing of
+        previous layer finishes, and then initiate string the KV cache of the
+        current layer one. The storing process of the KV cache is paged GPU
+        memory -> GPU buffer -> memory objects. The last iteration simply waits
+        for the last layer to finish.
+        In total, this the generator will yield num_layers + 1 times.
+
+        :param memory_objs: The memory objects to store the KV cache. The first
+            dimension is the number of layers, and the second dimension is the
+            number of memory objects (i.e., number of chunks) for each layer.
+
+        :param starts: The starting indices of the KV cache in the corresponding
+            token sequence.
+
+        :param ends: The ending indices of the KV cache in the corresponding
+            token sequence.
+
+        :raises ValueError: If 'slot_mapping' is not provided in kwargs.
+        """
+
+        self.initialize_kvcaches_ptr(**kwargs)
+        assert self.kvcaches is not None, (
+            "kvcaches should be provided in kwargs or initialized beforehand."
+        )
+
+        if "slot_mapping" not in kwargs:
+            raise ValueError("'slot_mapping' should be provided in kwargs.")
+
+        if "sync" not in kwargs:
+            raise ValueError("'sync' should be provided in kwargs.")
+
+        slot_mapping: torch.Tensor = kwargs["slot_mapping"]
+
+        self._lazy_initialize_buffer(self.kvcaches)
+
+        slot_mapping_chunks = []
+        for start, end in zip(starts, ends, strict=False):
+            slot_mapping_chunks.append(slot_mapping[start:end])
+
+        slot_mapping_full = torch.cat(slot_mapping_chunks, dim=0)
+
+        num_tokens = len(slot_mapping_full)
+
+        if self.use_gpu:
+            buffer_shape = self.get_shape(num_tokens)
+
+            assert self.gpu_buffer_allocator is not None, (
+                "GPU buffer allocator should be initialized"
+            )
+            memory_format = (
+                MemoryFormat.KV_MLA_FMT if self.use_mla else MemoryFormat.KV_T2D
+            )
+            tmp_gpu_buffer_obj = self.gpu_buffer_allocator.allocate(
+                buffer_shape, self.dtype, memory_format
+            )
+            assert tmp_gpu_buffer_obj is not None, (
+                "Failed to allocate GPU buffer in GPUConnector"
+            )
+            assert tmp_gpu_buffer_obj.tensor is not None
+
+        for layer_id in range(self.num_layers):
+            memory_objs_layer = memory_objs[layer_id]
+            # kvcaches -> gpu_buffer -> memobj
+            if self.use_gpu:
+                if self.use_mla:
+                    lmc_ops.single_layer_kv_transfer(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[layer_id],
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.D2H,
+                        self.engine_kv_format,
+                        token_major=True,
+                    )
+                else:
+                    t, h, d = self.kvcaches[0][layer_id].shape
+                    lmc_ops.single_layer_kv_transfer_sgl(
+                        tmp_gpu_buffer_obj.tensor,
+                        self.kvcaches[0][layer_id].view(t, 1, h, d),
+                        self.kvcaches[1][layer_id].view(t, 1, h, d),
+                        slot_mapping_full,
+                        lmc_ops.TransferDirection.D2H,
+                        token_major=True,
+                    )
+
+            start_idx = 0
+
+            for start, end, memory_obj in zip(
+                starts, ends, memory_objs_layer, strict=False
+            ):
+                assert memory_obj.tensor is not None
+                if self.use_gpu:
+                    chunk_len = memory_obj.tensor.shape[0]
+                    memory_obj.tensor.copy_(
+                        tmp_gpu_buffer_obj.tensor[start_idx : start_idx + chunk_len],
+                        non_blocking=True,
+                    )
+                    start_idx += chunk_len
+                else:
+                    if self.use_mla:
+                        lmc_ops.single_layer_kv_transfer(
+                            memory_obj.tensor,
+                            self.kvcaches[layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.D2H,
+                            self.engine_kv_format,
+                            token_major=True,
+                        )
+                    else:
+                        lmc_ops.single_layer_kv_transfer_sgl(
+                            memory_obj.tensor,
+                            self.kvcaches[0][layer_id],
+                            self.kvcaches[1][layer_id],
+                            slot_mapping[start:end],
+                            lmc_ops.TransferDirection.D2H,
+                            token_major=True,
+                        )
+
+                if self.use_mla:
+                    memory_obj.metadata.fmt = MemoryFormat.KV_MLA_FMT
+
+            yield
+            logger.debug(f"Finished offloading layer {layer_id}")
+
+        # free the buffer memory
+        if self.use_gpu:
+            tmp_gpu_buffer_obj.ref_count_down()
+        yield
+
+    def get_shape(self, num_tokens: int) -> torch.Size:
+        # Single-layer token-major shape, matching SGLangLayerwiseGPUConnector (CUDA).
+        # MLA has only one stream (no K/V split), while MHA keeps token-major [T, 2, D].
+        if self.use_mla:
+            return torch.Size([num_tokens, self.hidden_dim_size])
+        return torch.Size([num_tokens, 2, self.hidden_dim_size])
diff --git a/lmcache/v1/health_monitor/__init__.py b/lmcache/v1/health_monitor/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/health_monitor/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/health_monitor/base.py b/lmcache/v1/health_monitor/base.py
new file mode 100644
index 0000000..8b4fe2c
--- /dev/null
+++ b/lmcache/v1/health_monitor/base.py
@@ -0,0 +1,568 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Base classes for health monitoring.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Dict, List, Optional
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.exceptions import IrrecoverableException
+from lmcache.v1.health_monitor.constants import (
+    DEFAULT_FALLBACK_POLICY,
+    DEFAULT_PING_INTERVAL,
+    FallbackPolicy,
+)
+from lmcache.v1.periodic_thread import (
+    PeriodicThread,
+    PeriodicThreadRegistry,
+    ThreadLevel,
+    ThreadRunSummary,
+)
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.manager import LMCacheManager
+    from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+    from lmcache.v1.storage_backend.storage_manager import StorageManager
+
+logger = init_logger(__name__)
+
+
+class HealthCheck(ABC):
+    """
+    Abstract base class for health checks.
+
+    Subclasses should implement the check() method to perform specific
+    health checks. Each health check represents one aspect of system health.
+
+    Subclasses must also implement the create() classmethod
+    to create instances from a LMCacheManager.
+
+    Attributes:
+        fallback_policy: The fallback policy when this health check fails.
+            - RECOMPUTE: Skip all cache operations, fall back to recomputation
+            - LOCAL_CPU: Fall back to local CPU backend only
+
+    Example:
+        class DatabaseHealthCheck(HealthCheck):
+            def __init__(self, db_connection, fallback_policy=FallbackPolicy.RECOMPUTE):
+                self._fallback_policy = fallback_policy
+                self.db = db_connection
+
+            def name(self) -> str:
+                return "DatabaseHealthCheck"
+
+            def check(self) -> bool:
+                return self.db.ping()
+
+            @property
+            def fallback_policy(self) -> FallbackPolicy:
+                return self._fallback_policy
+
+            @classmethod
+            def create(
+                cls, manager: "LMCacheManager"
+            ) -> List["HealthCheck"]:
+                # Create instances from manager's components
+                return [cls(manager.lmcache_engine.db_connection)]
+    """
+
+    @abstractmethod
+    def name(self) -> str:
+        """Return the name of this health check"""
+        pass
+
+    @abstractmethod
+    def check(self) -> bool:
+        """
+        Perform the health check.
+
+        Returns:
+            bool: True if healthy, False otherwise
+        """
+        pass
+
+    @property
+    def fallback_policy(self) -> FallbackPolicy:
+        """
+        Return the fallback policy for this health check.
+
+        Default is RECOMPUTE. Subclasses can override this property
+        to return a different policy.
+
+        Returns:
+            FallbackPolicy: The fallback policy
+        """
+        return DEFAULT_FALLBACK_POLICY
+
+    def should_skip(self) -> bool:
+        """
+        Check if this health check should be skipped.
+
+        Override this method to conditionally skip checks
+        (e.g., if the component doesn't support health checks).
+
+        Returns:
+            bool: True if the check should be skipped, False otherwise
+        """
+        return False
+
+    def get_bypass_backend_name(self) -> Optional[str]:
+        """
+        Return the backend name to bypass when this health check fails
+        and fallback_policy is LOCAL_CPU.
+
+        Override this method to specify the backend name.
+
+        Returns:
+            Optional[str]: The backend name to bypass, or None if not applicable
+        """
+        return None
+
+    @classmethod
+    @abstractmethod
+    def create(cls, manager: "LMCacheManager") -> List["HealthCheck"]:
+        """
+        Create health check instance(s) from a LMCacheManager.
+
+        This method should extract the necessary components from the manager
+        and create one or more health check instances.
+
+        Args:
+            manager: The LMCacheManager instance
+
+        Returns:
+            List[HealthCheck]: List of health check instances.
+                              Return empty list if the check is not applicable.
+        """
+        pass
+
+
+class HealthMonitor(PeriodicThread):
+    """
+    Health monitor for the entire LMCache system.
+
+    This is the unified health monitor for the entire LMCache system.
+    It supports extensible health checks and provides a centralized way
+    to check the health status of the LMCacheManager.
+
+    The monitor automatically discovers and instantiates all HealthCheck
+    subclasses using their create() method.
+
+    The monitor runs in a background thread and periodically executes
+    all registered health checks. If any check fails, the system is
+    marked as unhealthy and appropriate fallback actions are taken
+    based on each check's fallback_policy.
+
+    Fallback Policies:
+        - RECOMPUTE: Mark system as unhealthy, skip all cache operations
+        - LOCAL_CPU: Bypass the failed backend, use local CPU with hot_cache enabled
+
+    Usage:
+        # Create a health monitor with manager
+        health_monitor = HealthMonitor(
+            manager=manager,
+            ping_interval=30.0
+        )
+
+        # Start monitoring
+        health_monitor.start()
+
+        # Check health status
+        if health_monitor.is_healthy():
+            # Perform normal operations
+            pass
+
+        # Stop monitoring when done
+        health_monitor.stop()
+    """
+
+    def __init__(
+        self,
+        manager: "LMCacheManager",
+        ping_interval: float = DEFAULT_PING_INTERVAL,
+    ):
+        # Initialize PeriodicThread base class
+        super().__init__(
+            name="health-monitor-thread",
+            interval=ping_interval,
+            level=ThreadLevel.CRITICAL,
+            init_wait=0.0,
+        )
+
+        self._manager = manager
+        self._health_checks: List[HealthCheck] = []
+
+        # Health status
+        self._healthy = True
+        self._health_lock = threading.RLock()
+
+        # Configuration (also stored in base class)
+        self._ping_interval = ping_interval
+
+        # Track which backends are currently bypassed due to health check failures
+        # Key: backend_name, Value: check_name that caused the bypass
+        self._bypassed_backends: Dict[str, str] = {}
+        self._bypass_lock = threading.RLock()
+
+        # Track original hot_cache setting before any LOCAL_CPU fallback
+        # This is a global setting, not per-backend
+        # None means no fallback is active, otherwise stores the original use_hot value
+        self._original_hot_cache: Optional[bool] = None
+
+        # Track previous health status per check for detecting recovery
+        self._previous_check_status: Dict[str, bool] = {}
+
+        # Auto-discover and instantiate health checks
+        self._discover_health_checks()
+
+        # Register with the global registry
+        PeriodicThreadRegistry.get_instance().register(self)
+
+    def _discover_health_checks(self) -> None:
+        """
+        Discover all HealthCheck subclasses and instantiate them.
+
+        This method dynamically scans all modules in the checks package,
+        finds all HealthCheck subclasses and calls their `create()`
+        method to create instances.
+        """
+        cls: type[HealthCheck]
+        for cls in discover_subclasses(
+            "lmcache.v1.health_monitor.checks",
+            HealthCheck,  # type: ignore[type-abstract]
+            module_filter=lambda name: not name.startswith("_"),
+            include_abstract=True,
+            require_defined_in_module=False,
+        ):
+            try:
+                instances = cls.create(self._manager)
+            except Exception as e:
+                logger.warning(f"Failed to create health check {cls.__name__}: {e}")
+                continue
+            for instance in instances:
+                self._health_checks.append(instance)
+                # Initialize previous status as healthy
+                self._previous_check_status[instance.name()] = True
+                logger.info(
+                    f"Registered health check: {instance.name()} "
+                    f"with fallback_policy: {instance.fallback_policy}"
+                )
+
+    def get_health_checks(self) -> List[HealthCheck]:
+        """Get all registered health checks"""
+        return list(self._health_checks)
+
+    def is_healthy(self) -> bool:
+        """
+        Check if the system is currently healthy.
+
+        Returns:
+            bool: True if healthy, False otherwise
+        """
+        with self._health_lock:
+            return self._healthy
+
+    def _set_healthy(self, healthy: bool) -> None:
+        """Set the health status"""
+        with self._health_lock:
+            if self._healthy != healthy:
+                if healthy:
+                    logger.info(
+                        "HealthMonitor: System recovered, restoring normal operations"
+                    )
+                else:
+                    logger.warning(
+                        "HealthMonitor: System unhealthy, entering degraded mode"
+                    )
+                self._healthy = healthy
+
+    def _get_storage_manager(self) -> Optional["StorageManager"]:
+        """Get the storage manager from the cache engine."""
+        engine = self._manager.lmcache_engine
+        if engine is None:
+            return None
+        return engine.storage_manager
+
+    def _get_local_cpu_backend(
+        self, storage_manager: "StorageManager"
+    ) -> Optional["LocalCPUBackend"]:
+        """
+        Get the LocalCPUBackend from the storage manager with proper type.
+
+        Args:
+            storage_manager: The storage manager instance
+
+        Returns:
+            Optional[LocalCPUBackend]: The LocalCPUBackend instance, or None
+        """
+        # First Party
+        from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+        backend = storage_manager.local_cpu_backend
+        if backend is not None and isinstance(backend, LocalCPUBackend):
+            return backend
+        return None
+
+    def _apply_local_cpu_fallback(self, check: HealthCheck) -> None:
+        """
+        Apply LOCAL_CPU fallback policy for a failed health check.
+
+        This will:
+        1. Enable bypass for the specified backend in StorageManager
+        2. Enable hot_cache for LocalCPUBackend (only on first fallback)
+
+        Args:
+            check: The health check that failed
+        """
+        backend_name = check.get_bypass_backend_name()
+        if backend_name is None:
+            logger.warning(
+                f"Health check {check.name()} has LOCAL_CPU fallback but "
+                "get_bypass_backend_name() returned None"
+            )
+            return
+
+        storage_manager = self._get_storage_manager()
+        if storage_manager is None:
+            logger.warning("StorageManager is not available for fallback")
+            return
+
+        with self._bypass_lock:
+            if backend_name in self._bypassed_backends:
+                # Already bypassed
+                return
+
+            local_cpu = self._get_local_cpu_backend(storage_manager)
+
+            # Save original hot_cache setting only on the first fallback
+            # (when no backends are bypassed yet)
+            if len(self._bypassed_backends) == 0:
+                if local_cpu is not None:
+                    self._original_hot_cache = local_cpu.use_hot
+                else:
+                    self._original_hot_cache = None
+
+            # Enable bypass for the backend
+            storage_manager.set_backend_bypass(backend_name, True)
+
+            # Enable hot_cache for LocalCPUBackend
+            if local_cpu is not None:
+                local_cpu.use_hot = True
+                logger.info(
+                    f"Enabled hot_cache for LocalCPUBackend due to "
+                    f"{check.name()} failure"
+                )
+
+            # Record this backend as bypassed
+            self._bypassed_backends[backend_name] = check.name()
+
+            logger.info(
+                f"Applied LOCAL_CPU fallback for {check.name()}: "
+                f"bypassing {backend_name}"
+            )
+
+    def _recover_from_local_cpu_fallback(self, check: HealthCheck) -> None:
+        """
+        Recover from LOCAL_CPU fallback when a health check passes again.
+
+        This will:
+        1. Disable bypass for the specified backend in StorageManager
+        2. Only when ALL backends have recovered:
+           - Restore original hot_cache setting for LocalCPUBackend
+           - Clear hot_cache if it was originally disabled
+
+        Args:
+            check: The health check that recovered
+        """
+        backend_name = check.get_bypass_backend_name()
+        if backend_name is None:
+            return
+
+        storage_manager = self._get_storage_manager()
+        if storage_manager is None:
+            return
+
+        with self._bypass_lock:
+            if backend_name not in self._bypassed_backends:
+                # Not in bypassed state
+                return
+
+            check_name = self._bypassed_backends[backend_name]
+
+            # Verify this is the same check that caused the bypass
+            if check_name != check.name():
+                return
+
+            # Disable bypass for the backend
+            storage_manager.set_backend_bypass(backend_name, False)
+
+            # Remove from bypassed backends
+            del self._bypassed_backends[backend_name]
+
+            logger.info(
+                f"Recovered from LOCAL_CPU fallback for {check.name()}: "
+                f"restored {backend_name}"
+            )
+
+            # Only restore hot_cache when ALL backends have recovered
+            if len(self._bypassed_backends) == 0:
+                local_cpu = self._get_local_cpu_backend(storage_manager)
+                if local_cpu is not None and self._original_hot_cache is not None:
+                    # First, restore the original hot_cache setting
+                    # This prevents new data from being written during clear()
+                    local_cpu.use_hot = self._original_hot_cache
+                    logger.info(
+                        f"Restored hot_cache setting to {self._original_hot_cache} "
+                        f"for LocalCPUBackend (all backends restored)"
+                    )
+
+                    # Then, clear hot_cache if it was originally disabled
+                    # At this point, use_hot is already False, so no new data
+                    # will be written during the potentially long clear() operation
+                    if not self._original_hot_cache:
+                        local_cpu.clear()
+                        logger.info(
+                            "Cleared hot_cache for LocalCPUBackend during recovery "
+                            "(all backends restored)"
+                        )
+                # Reset original_hot_cache tracker
+                self._original_hot_cache = None
+
+    def _run_all_checks(self) -> bool:
+        """
+        Run all health checks.
+
+        Returns:
+            bool: True if all checks pass (considering fallback policies),
+                  False if any check with RECOMPUTE policy fails
+
+        Raises:
+            IrrecoverableException: If any check raises an irrecoverable error
+        """
+        all_healthy = True
+
+        for check in self._health_checks:
+            if check.should_skip():
+                continue
+
+            check_name = check.name()
+            was_healthy = self._previous_check_status.get(check_name, True)
+
+            try:
+                is_healthy = check.check()
+            except IrrecoverableException:
+                logger.error(f"Health check {check_name} raised IrrecoverableException")
+                raise
+            except Exception as e:
+                logger.error(f"Health check {check_name} raised exception: {e}")
+                is_healthy = False
+
+            # Update previous status
+            self._previous_check_status[check_name] = is_healthy
+
+            if is_healthy:
+                # Check recovered
+                if not was_healthy:
+                    logger.info(f"Health check {check_name} recovered")
+                    # If this check was using LOCAL_CPU fallback, recover
+                    if check.fallback_policy == FallbackPolicy.LOCAL_CPU:
+                        self._recover_from_local_cpu_fallback(check)
+            else:
+                # Check failed
+                logger.warning(f"Health check failed: {check_name}")
+
+                if check.fallback_policy == FallbackPolicy.RECOMPUTE:
+                    # RECOMPUTE policy: mark as unhealthy
+                    all_healthy = False
+                elif check.fallback_policy == FallbackPolicy.LOCAL_CPU:
+                    # LOCAL_CPU policy: apply fallback
+                    self._apply_local_cpu_fallback(check)
+                    # System is still considered healthy with LOCAL_CPU fallback
+
+        return all_healthy
+
+    def start(self) -> Optional[threading.Thread]:
+        """
+        Start the health monitor thread.
+
+        Returns:
+            Optional[threading.Thread]: The started thread,
+                or None if no checks need monitoring
+        """
+        # Check if we have any health checks that need to run
+        active_checks = [c for c in self._health_checks if not c.should_skip()]
+        if not active_checks:
+            logger.info("No active health checks to monitor, skipping monitor thread")
+            # Set last_summary even when not starting
+            self._last_summary = ThreadRunSummary(
+                success=True,
+                message="No active health checks to monitor, thread not started",
+                extra_info={
+                    "total_checks": str(len(self._health_checks)),
+                    "active_checks": "0",
+                    "skipped": "true",
+                },
+            )
+            self._level = ThreadLevel.LOW
+            return None
+
+        # Use the base class start method
+        thread = super().start()
+        if thread is not None:
+            logger.info(
+                f"Started health monitor thread with "
+                f"{len(active_checks)} active checks, "
+                f"interval: {self._ping_interval}s"
+            )
+        return thread
+
+    def stop(self, timeout: float = 5.0) -> None:
+        """Stop the health monitor thread"""
+        # Unregister from the global registry
+        PeriodicThreadRegistry.get_instance().unregister(self.name)
+        # Use base class stop method
+        super().stop(timeout)
+
+    def _execute(self) -> ThreadRunSummary:
+        """
+        Execute one health check cycle.
+
+        This method is called by the PeriodicThread base class.
+
+        Returns:
+            ThreadRunSummary: Summary of the health check cycle
+        """
+        try:
+            # Run all health checks
+            is_healthy = self._run_all_checks()
+            self._set_healthy(is_healthy)
+
+            # Build summary
+            failed_checks = [
+                name
+                for name, healthy in self._previous_check_status.items()
+                if not healthy
+            ]
+
+            return ThreadRunSummary(
+                success=is_healthy,
+                message="All checks passed"
+                if is_healthy
+                else f"Failed checks: {failed_checks}",
+                extra_info={
+                    "total_checks": str(len(self._health_checks)),
+                    "failed_checks": str(len(failed_checks)),
+                    "bypassed_backends": str(len(self._bypassed_backends)),
+                },
+            )
+        except IrrecoverableException as e:
+            logger.error(f"Irrecoverable error in health monitor: {e}")
+            self._set_healthy(False)
+            # Re-raise to stop the thread
+            raise
diff --git a/lmcache/v1/health_monitor/checks/__init__.py b/lmcache/v1/health_monitor/checks/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/health_monitor/checks/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/health_monitor/checks/remote_backend_check.py b/lmcache/v1/health_monitor/checks/remote_backend_check.py
new file mode 100644
index 0000000..bbc9d50
--- /dev/null
+++ b/lmcache/v1/health_monitor/checks/remote_backend_check.py
@@ -0,0 +1,308 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Health check for RemoteBackend.
+"""
+
+# Standard
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, List, Optional
+import asyncio
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.health_monitor.base import HealthCheck
+from lmcache.v1.health_monitor.constants import (
+    DEFAULT_FALLBACK_POLICY,
+    DEFAULT_GET_BLOCKING_FAILED_THRESHOLD,
+    DEFAULT_PING_TIMEOUT,
+    DEFAULT_WAITING_TIME_FOR_RECOVERY,
+    FALLBACK_POLICY_CONFIG_KEY,
+    GET_BLOCKING_FAILED_THRESHOLD_CONFIG_KEY,
+    PING_GENERIC_ERROR_CODE,
+    PING_TIMEOUT_CONFIG_KEY,
+    PING_TIMEOUT_ERROR_CODE,
+    WAITING_TIME_FOR_RECOVERY_CONFIG_KEY,
+    FallbackPolicy,
+)
+from lmcache.v1.storage_backend.connector import InstrumentedRemoteConnector
+from lmcache.v1.storage_backend.connector.audit_connector import AuditConnector
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.manager import LMCacheManager
+    from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+logger = init_logger(__name__)
+
+
+class RemoteBackendHealthCheck(HealthCheck):
+    """
+    Health check for RemoteBackend by pinging the remote connector.
+
+    This check verifies that the remote backend is reachable and responsive
+    by sending periodic ping requests.
+
+    Fallback Policies:
+        - RECOMPUTE (default): Skip all cache operations when
+          remote backend is unhealthy
+        - LOCAL_CPU: Bypass remote backend and use local CPU with hot_cache enabled
+    """
+
+    def __init__(
+        self,
+        backend: "RemoteBackend",
+    ):
+        self.backend = backend
+        # Get fallback policy from config
+        fallback_policy_str = backend.config.get_extra_config_value(
+            FALLBACK_POLICY_CONFIG_KEY, DEFAULT_FALLBACK_POLICY.value
+        )
+        # Convert string to FallbackPolicy enum
+        if isinstance(fallback_policy_str, str):
+            try:
+                self._fallback_policy = FallbackPolicy(fallback_policy_str)
+            except ValueError:
+                logger.warning(
+                    f"Invalid fallback_policy '{fallback_policy_str}' "
+                    f"for {backend}, using default: "
+                    f"{DEFAULT_FALLBACK_POLICY}"
+                )
+                self._fallback_policy = DEFAULT_FALLBACK_POLICY
+        elif isinstance(fallback_policy_str, FallbackPolicy):
+            self._fallback_policy = fallback_policy_str
+        self.failure_time: Optional[float] = None
+        self._stats_monitor = LMCStatsMonitor.GetOrCreate()
+        self._backend_name: Optional[str] = None
+        self._last_get_blocking_failed_count = 0
+
+    @classmethod
+    def create(cls, manager: "LMCacheManager") -> List[HealthCheck]:
+        """
+        Create RemoteBackendHealthCheck instances from a LMCacheManager.
+
+        This method finds all RemoteBackend instances in the storage manager
+        and creates a health check for each one.
+
+        Args:
+            manager: The LMCacheManager instance
+
+        Returns:
+            List of RemoteBackendHealthCheck instances
+        """
+        # Import here to avoid circular imports
+        # First Party
+        from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+        instances: List[HealthCheck] = []
+
+        # Get engine from manager
+        engine = manager.lmcache_engine
+        if engine is None or engine.storage_manager is None:
+            return instances
+
+        for backend_name, backend in engine.storage_manager.storage_backends.items():
+            if isinstance(backend, RemoteBackend):
+                check = cls(backend)
+                check._backend_name = backend_name
+                instances.append(check)
+                logger.info(f"Created {check} for {backend_name}")
+
+        return instances
+
+    def name(self) -> str:
+        return f"RemoteBackendHealthCheck({self.backend.remote_url})"
+
+    @property
+    def fallback_policy(self) -> FallbackPolicy:
+        """Return the fallback policy for this health check."""
+        return self._fallback_policy
+
+    def get_bypass_backend_name(self) -> Optional[str]:
+        """
+        Return the backend name to bypass when this health check fails.
+
+        Returns:
+            Optional[str]: The backend name (e.g., "RemoteBackend")
+        """
+        return self._backend_name
+
+    def _get_ping_timeout(self) -> float:
+        """Get the ping timeout from the backend config."""
+        return self.backend.config.get_extra_config_value(
+            PING_TIMEOUT_CONFIG_KEY, DEFAULT_PING_TIMEOUT
+        )
+
+    def _try_reinitialize_connection(self) -> bool:
+        """
+        Try to reinitialize the connection if connector is None.
+
+        Returns:
+            bool: True if connection was successfully initialized, False otherwise
+        """
+        if self.backend.connection is not None:
+            return True
+
+        logger.warning("Connector is None, re-initializing connection.")
+        self.backend.init_connection()
+
+        return self.backend.connection is not None
+
+    def check(self) -> bool:
+        """
+        Perform a health check on remote backend, which includes the following checks:
+
+        - get_blocking/batched_get_blocking, if failed count >= threshold,
+        which means check failed, update failure_time and return False.
+        If failure_time is not None, wait for more than`waiting_time_for_recovery`
+        seconds before resuming the check.
+
+        - ping, if connector supports ping, send a ping request to remote connector.
+
+        Returns:
+            bool: True if all checks succeeds, False otherwise
+        """
+        # Try to reinitialize connection if needed
+        if not self._try_reinitialize_connection():
+            return False
+
+        # At this point, connector is guaranteed to be not None
+        connector = self.backend.connection
+        assert connector is not None
+
+        if self.failure_time is not None:
+            waiting_time = self.backend.config.get_extra_config_value(
+                WAITING_TIME_FOR_RECOVERY_CONFIG_KEY,
+                DEFAULT_WAITING_TIME_FOR_RECOVERY,
+            )
+            if (
+                time.time() - self.failure_time > waiting_time
+                and self._put_and_get_check()
+            ):
+                # recover from get blocking failed
+                logger.info(
+                    "Failure time: %s, current time: %s, "
+                    "recover from get blocking failed",
+                    self.failure_time,
+                    time.time(),
+                )
+                self.failure_time = None
+            else:
+                logger.info(
+                    "Failure time: %s, current time: %s, "
+                    "still in get blocking failed recovery window",
+                    self.failure_time,
+                    time.time(),
+                )
+                return False
+
+        # Check read failed
+        current_get_blocking_failed_count = self.backend.get_blocking_failed_count
+        get_blocking_failed_count = (
+            current_get_blocking_failed_count - self._last_get_blocking_failed_count
+        )
+        self._last_get_blocking_failed_count = current_get_blocking_failed_count
+        threshold = self.backend.config.get_extra_config_value(
+            GET_BLOCKING_FAILED_THRESHOLD_CONFIG_KEY,
+            DEFAULT_GET_BLOCKING_FAILED_THRESHOLD,
+        )
+        if get_blocking_failed_count >= threshold:
+            logger.warning(
+                "Detected %s get blocking failed in interval, threshold: %s",
+                get_blocking_failed_count,
+                threshold,
+            )
+            self.failure_time = time.time()
+            return False
+
+        # If connector doesn't support ping, assume it's healthy
+        if not connector.support_ping():
+            return True
+
+        # Check ping
+        try:
+            start_time = time.perf_counter()
+            future = asyncio.run_coroutine_threadsafe(
+                connector.ping(), self.backend.loop
+            )
+            error_code = future.result(timeout=self._get_ping_timeout())
+            latency = (time.perf_counter() - start_time) * 1000
+
+            # Record ping latency
+            self._stats_monitor.update_remote_ping_latency(latency)
+            # Record error code (0 means success)
+            self._stats_monitor.update_remote_ping_error_code(error_code)
+
+            if error_code != 0:
+                logger.warning(f"Ping failed with error code: {error_code}")
+                return False
+
+            return True
+
+        except asyncio.TimeoutError:
+            logger.warning("Ping timeout")
+            self._stats_monitor.update_remote_ping_error_code(PING_TIMEOUT_ERROR_CODE)
+            return False
+        except Exception as e:
+            logger.error(f"Ping error: {e}")
+            self._stats_monitor.update_remote_ping_error_code(PING_GENERIC_ERROR_CODE)
+            return False
+
+    def _put_and_get_check(self) -> bool:
+        if self.backend.local_cpu_backend is None or self.backend.connection is None:
+            return False
+
+        with self._resource_manager() as (put_obj, get_obj):
+            if put_obj is None:
+                return False
+            if get_obj is None:
+                logger.warning("Get failed, the return value is None, check failed.")
+                return False
+            return torch.equal(put_obj.raw_tensor, get_obj.raw_tensor)
+
+    @contextmanager
+    def _resource_manager(self):
+        key = CacheEngineKey(
+            model_name="test",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0,
+            dtype=torch.bfloat16,
+        )
+        connector = self.backend.connection
+        if isinstance(connector, InstrumentedRemoteConnector):
+            connector = connector.getWrappedConnector()
+            if isinstance(connector, AuditConnector):
+                connector = connector.real_connector
+        shapes = connector.meta_shapes
+        dtypes = connector.meta_dtypes
+        fmt = connector.meta_fmt
+        put_obj, get_obj = None, None
+        try:
+            # put
+            put_obj = self.backend.local_cpu_backend.allocate(shapes, dtypes, fmt)
+            future = self.backend.submit_put_task(key, put_obj)
+            future.result(timeout=self._get_ping_timeout())
+            # get
+            if connector.support_batched_get():
+                get_objs = self.backend.batched_get_blocking([key])
+                get_obj = get_objs[0] if get_objs else None
+            else:
+                get_obj = self.backend.get_blocking(key)
+            yield put_obj, get_obj
+        except asyncio.TimeoutError:
+            logger.warning("Put timeout, check failed.")
+            yield None, None
+        except Exception as e:
+            logger.error(f"Put error, check failed: {e}")
+            yield None, None
+        finally:
+            if put_obj is not None:
+                put_obj.ref_count_down()
+            if get_obj is not None:
+                get_obj.ref_count_down()
diff --git a/lmcache/v1/health_monitor/constants.py b/lmcache/v1/health_monitor/constants.py
new file mode 100644
index 0000000..ace8fbf
--- /dev/null
+++ b/lmcache/v1/health_monitor/constants.py
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Constants for health monitoring.
+"""
+
+# Standard
+from enum import Enum
+
+
+class FallbackPolicy(str, Enum):
+    """Fallback policy when health check fails."""
+
+    RECOMPUTE = "recompute"  # Skip all cache operations, fall back to recomputation
+    LOCAL_CPU = "local_cpu"  # Fall back to local CPU backend only
+
+
+# Ping error codes
+PING_TIMEOUT_ERROR_CODE = -1
+PING_GENERIC_ERROR_CODE = -2
+
+# Configuration keys
+PING_TIMEOUT_CONFIG_KEY = "ping_timeout"
+PING_INTERVAL_CONFIG_KEY = "ping_interval"
+FALLBACK_POLICY_CONFIG_KEY = "fallback_policy"
+GET_BLOCKING_FAILED_THRESHOLD_CONFIG_KEY = "get_blocking_failed_threshold"
+WAITING_TIME_FOR_RECOVERY_CONFIG_KEY = "waiting_time_for_recovery"
+
+# Default values
+DEFAULT_PING_TIMEOUT = 5.0
+DEFAULT_PING_INTERVAL = 30.0
+DEFAULT_FALLBACK_POLICY = FallbackPolicy.RECOMPUTE
+DEFAULT_GET_BLOCKING_FAILED_THRESHOLD = 10
+DEFAULT_WAITING_TIME_FOR_RECOVERY = 300.0
+
+# Memory thresholds
+DEFAULT_MEMORY_THRESHOLD_PERCENT = 95.0  # Unhealthy if memory usage > 95%
diff --git a/lmcache/v1/hidden_state_store.py b/lmcache/v1/hidden_state_store.py
new file mode 100644
index 0000000..6c399ea
--- /dev/null
+++ b/lmcache/v1/hidden_state_store.py
@@ -0,0 +1,364 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HiddenStateStore: per-chunk hidden-state cache on a separate pinned pool.
+
+This module owns hidden-state caching as a logically separate component from
+the KV cache. It is constructed by :class:`~lmcache.v1.cache_engine.LMCacheEngine`
+when ``config.enable_hidden_state_cache`` is True and exposed as
+``engine.hidden_state_store``. See ``docs/design/v1/hidden_state_store.md``.
+"""
+
+# Standard
+from collections import OrderedDict
+from typing import TYPE_CHECKING, Dict, List, Optional, Union, cast
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.token_database import TokenDatabase
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.storage_backend.storage_manager import StorageManager
+
+logger = init_logger(__name__)
+
+_GIB = 1024**3
+
+# Maximum LRU-evict-and-retry attempts in _alloc_chunk.  Each retry evicts one
+# entry from this store's own pool (never from KV) before re-attempting the
+# allocation, so the effective "wait" is exhausting our own LRU queue.
+_HS_ALLOC_MAX_RETRIES = 8
+
+
+class HiddenStateStore:
+    """Stand-alone, chunk-aligned hidden-state cache.
+
+    The store keeps one MemoryObj per (chunk-key, layer_idx) pair on
+    its own pinned-CPU pool. Chunk keys are produced by the engine's
+    TokenDatabase, so HS chunks share the exact
+    CacheEngineKey as the corresponding KV chunks.
+
+    Eviction is "lazy coupled": when a retrieve walks chunks in order, the
+    store asks the bound StorageManager whether KV is still present
+    for each key. If KV is gone, the orphan HS entry is dropped and the
+    prefix ends there (KV evict -> HS evict). When the store's own pool is
+    full, the store evicts its own LRU entry; it never evicts KV.
+
+    Args:
+        config: Engine config. Reads enable_hidden_state_cache,
+            max_hidden_state_cpu_size (GB), and hidden_state_layers.
+            Retrieval always uses prefix-strict assembly (stop at the first
+            chunk missing KV or hidden state for the requested layer).
+        token_database: The same TokenDatabase used by the engine,
+            so chunk boundaries and keys match KV exactly.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        token_database: TokenDatabase,
+    ) -> None:
+        self._config = config
+        self._token_database = token_database
+        self._storage_manager: Optional["StorageManager"] = None
+
+        size_bytes = int(config.max_hidden_state_cpu_size * _GIB)
+        if size_bytes <= 0:
+            raise ValueError(
+                "max_hidden_state_cpu_size must be > 0 when "
+                "enable_hidden_state_cache=True"
+            )
+
+        self._allocator = MixedMemoryAllocator(size_bytes, config=config)
+
+        # CacheEngineKey -> {layer_idx: MemoryObj}. OrderedDict-like for LRU
+        # via a separate _lru ordering (cheap, lets us update on access).
+        self._chunks: Dict[CacheEngineKey, Dict[int, MemoryObj]] = {}
+        self._lru: "OrderedDict[CacheEngineKey, None]" = OrderedDict()
+
+        allowlist = config.hidden_state_layers
+        self._layer_allowlist: Optional[set] = (
+            set(allowlist) if allowlist is not None else None
+        )
+
+        logger.info(
+            "HiddenStateStore initialized: pool=%.2f GB, layer_allowlist=%s",
+            config.max_hidden_state_cpu_size,
+            self._layer_allowlist,
+        )
+
+    # ------------------------------------------------------------------
+    # Wiring
+    # ------------------------------------------------------------------
+
+    def bind_storage_manager(self, storage_manager: "StorageManager") -> None:
+        """Attach the engine's :class:`StorageManager`.
+
+        Required for coupled eviction. Without it, retrieve falls back to
+        HS-only presence checks.
+        """
+        self._storage_manager = storage_manager
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def store_hidden_states(
+        self,
+        token_ids: Union[torch.Tensor, List[int]],
+        hidden_states: torch.Tensor,
+        *,
+        layer_idx: int = 0,
+        token_offset: int = 0,
+    ) -> int:
+        """Store hidden_states chunked under the same keys as KV.
+
+        Args:
+            token_ids: 1-D int tensor or list of the **full** token-ID prefix
+                (same sequence used for KV storage so chunk boundaries and
+                chunk keys align with KV exactly).
+            hidden_states: 2-D tensor of shape
+                ``[len(token_ids) - token_offset, hidden_dim]``
+                (CPU or GPU). Will be moved to CPU/float32 internally.
+                Corresponds to ``token_ids[token_offset:]``.
+            layer_idx: Storage layer index. Defaults to 0 (main HS).
+            token_offset: Number of leading tokens in ``token_ids`` that are
+                **not** present in ``hidden_states`` because they were already
+                cached in a prior incremental call.  Defaults to 0 (full
+                sequence provided). Only chunks whose token range starts at or
+                after ``token_offset`` are written; partially-covered chunks
+                (``start < token_offset < end``) are skipped to keep each
+                chunk atomic.
+
+        Returns:
+            Number of chunks stored (0 when filtered by allowlist or on
+            allocation failure).
+
+        Raises:
+            ValueError: If ``token_offset`` is out of range, or if
+                ``hidden_states`` has an unexpected shape.
+            RuntimeError: If an allocated MemoryObj has no backing tensor
+                (indicates an allocator bug).
+        """
+        if self._layer_allowlist is not None and layer_idx not in self._layer_allowlist:
+            logger.debug(
+                "HiddenStateStore: dropping layer_idx=%d (not in allowlist=%s)",
+                layer_idx,
+                self._layer_allowlist,
+            )
+            return 0
+
+        if hidden_states.dim() != 2:
+            raise ValueError(
+                f"hidden_states must be 2-D [num_tokens, hidden_dim], "
+                f"got shape {tuple(hidden_states.shape)}"
+            )
+
+        n_toks = (
+            len(token_ids) if isinstance(token_ids, list) else int(token_ids.shape[0])
+        )
+        if not (0 <= token_offset <= n_toks):
+            raise ValueError(
+                f"token_offset ({token_offset}) must be in [0, len(token_ids) "
+                f"({n_toks})]"
+            )
+        expected_rows = n_toks - token_offset
+        if hidden_states.shape[0] != expected_rows:
+            raise ValueError(
+                f"hidden_states first dim ({hidden_states.shape[0]}) must equal "
+                f"len(token_ids) - token_offset ({expected_rows})"
+            )
+
+        # Detach but keep the tensor on its original device
+        hs_src = hidden_states.detach()
+        hidden_dim = hs_src.shape[1]
+
+        chunks = self._chunk(token_ids)
+        stored = 0
+        for start, end, key in chunks:
+            # Skip chunks that are entirely before the provided hidden states,
+            # or partially covered (keep chunks atomic with KV boundaries).
+            if start < token_offset:
+                continue
+
+            existing = self._chunks.get(key)
+            if existing is not None and layer_idx in existing:
+                # Already cached for this layer; bump LRU.
+                self._lru.pop(key, None)
+                self._lru[key] = None
+                continue
+
+            n = end - start
+            obj = self._alloc_chunk(n, hidden_dim)
+            if obj is None:
+                logger.warning(
+                    "HiddenStateStore: out of HS pool memory after eviction; "
+                    "stopping store at chunk start=%d",
+                    start,
+                )
+                break
+            tensor = obj.tensor
+            if tensor is None:
+                obj.ref_count_down()
+                raise RuntimeError(
+                    "HiddenStateStore: allocator returned MemoryObj with no "
+                    "backing tensor"
+                )
+
+            tensor.copy_(hs_src[start - token_offset : end - token_offset])
+
+            layer_map = self._chunks.setdefault(key, {})
+            layer_map[layer_idx] = obj
+            self._lru.pop(key, None)
+            self._lru[key] = None
+            stored += 1
+
+        return stored
+
+    def retrieve_hidden_states(
+        self,
+        token_ids: Union[torch.Tensor, List[int]],
+        *,
+        layer_idx: int = 0,
+    ) -> Optional[torch.Tensor]:
+        """Retrieve cached rows for layer_idx as a contiguous prefix.
+
+        Walks chunks of token_ids in order. Stops at the first chunk
+        where either KV is no longer present (lazy coupled-eviction cleanup)
+        or HS for layer_idx is missing (prefix-strict).
+
+        Returns:
+            CPU float32 tensor of shape [num_cached_prefix_tokens, hidden_dim],
+            or None if no chunk is cached.
+
+        Raises:
+            RuntimeError: If a cached MemoryObj has no backing tensor
+                (indicates an allocator bug).
+        """
+        chunks = self._chunk(token_ids)
+        out_rows: List[torch.Tensor] = []
+        hit_keys: List[CacheEngineKey] = []
+        for _, _, key in chunks:
+            if not self._kv_present(key):
+                # KV evicted -> drop HS for this key (coupled eviction) and stop.
+                if key in self._chunks:
+                    self._free_key(key)
+                break
+
+            layer_map = self._chunks.get(key)
+            if layer_map is None or layer_idx not in layer_map:
+                # HS missing for this chunk: prefix_strict stop.
+                break
+
+            obj = layer_map[layer_idx]
+            tensor = obj.tensor
+            if tensor is None:
+                raise RuntimeError(
+                    "HiddenStateStore: cached MemoryObj has no backing tensor"
+                )
+            out_rows.append(tensor)
+            hit_keys.append(key)
+
+        # evict the keys from the LRU
+        for key in reversed(hit_keys):
+            self._lru.pop(key, None)
+            self._lru[key] = None
+
+        if not out_rows:
+            return None
+        return torch.cat(out_rows, dim=0)
+
+    # ------------------------------------------------------------------
+    # Introspection / lifecycle
+    # ------------------------------------------------------------------
+
+    def num_cached_chunks(self) -> int:
+        """Return the number of distinct chunk keys currently cached."""
+        return len(self._chunks)
+
+    def has_chunk(self, key: CacheEngineKey, layer_idx: int = 0) -> bool:
+        """Return True if a chunk is cached for ``(key, layer_idx)``."""
+        layer_map = self._chunks.get(key)
+        return layer_map is not None and layer_idx in layer_map
+
+    def drop_key(self, key: CacheEngineKey) -> bool:
+        """Manually drop all HS layers for ``key``. Test/admin use."""
+        if key not in self._chunks:
+            return False
+        self._free_key(key)
+        return True
+
+    def close(self) -> None:
+        """Free every cached chunk and the underlying pinned pool."""
+        for key in list(self._chunks.keys()):
+            self._free_key(key)
+        self._allocator.close()
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _chunk(
+        self, token_ids: Union[torch.Tensor, List[int]]
+    ) -> List["tuple[int, int, CacheEngineKey]"]:
+        """Return [(start, end, key)] for token_ids using the engine TDB.
+
+        The list is materialized so we can iterate it twice (key check and
+        per-chunk copy) without re-running the hashing path.
+
+        ``process_tokens`` is typed to yield ``CacheEngineKey | int`` (the int
+        form is used by other callers); HiddenStateStore always runs it in the
+        keyed mode, so the third element is a ``CacheEngineKey`` here.
+        """
+        return cast(
+            "List[tuple[int, int, CacheEngineKey]]",
+            list(self._token_database.process_tokens(tokens=token_ids)),
+        )
+
+    def _kv_present(self, key: CacheEngineKey) -> bool:
+        """True if KV exists in any active backend, or unknown when SM unbound."""
+        if self._storage_manager is None:
+            # Without an SM we cannot distinguish "KV evicted" from "no KV";
+            # treat as present so the prefix walk doesn't truncate spuriously.
+            return True
+        return self._storage_manager.contains(key) is not None
+
+    def _alloc_chunk(self, n_tokens: int, hidden_dim: int) -> Optional[MemoryObj]:
+        shape = torch.Size([n_tokens, hidden_dim])
+        dtype = torch.float32
+        for _ in range(_HS_ALLOC_MAX_RETRIES):
+            obj = self._allocator.allocate(shape, dtype, MemoryFormat.HS_TD)
+            if obj is not None:
+                return obj
+            # Pressure: drop our LRU entry and retry. Never touches KV.
+            if not self._evict_one_lru():
+                break
+        return None
+
+    def _evict_one_lru(self) -> bool:
+        if not self._lru:
+            return False
+        key, _ = self._lru.popitem(last=False)
+        self._free_key(key)
+        logger.debug("HiddenStateStore: HS-only LRU evicted key=%s", key)
+        return True
+
+    def _free_key(self, key: CacheEngineKey) -> None:
+        layer_map = self._chunks.pop(key, None)
+        self._lru.pop(key, None)
+        if not layer_map:
+            return
+        # ref_count_down is the public release path: it free()s the
+        # underlying buffer when the count reaches zero (mirrors how
+        # LocalCPUBackend.remove releases entries).
+        for obj in layer_map.values():
+            obj.ref_count_down()
diff --git a/lmcache/v1/internal_api_server/__init__.py b/lmcache/v1/internal_api_server/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/lmcache/v1/internal_api_server/api_registry.py b/lmcache/v1/internal_api_server/api_registry.py
new file mode 100644
index 0000000..16ad755
--- /dev/null
+++ b/lmcache/v1/internal_api_server/api_registry.py
@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+from typing import List, Literal, Optional
+
+# Third Party
+from fastapi import APIRouter
+
+# First Party
+from lmcache.v1.utils.router_discovery import discover_api_routers
+
+APICategory = Literal["common", "vllm", "controller"]
+
+
+class APIRegistry:
+    """
+    Automatically discovers and registers API routes by category
+
+    Categories:
+    - common: APIs that work for all components (metrics, logs, etc.)
+    - vllm: APIs specific to vLLM scheduler/worker
+    - controller: APIs specific to LMCache controller
+    """
+
+    def __init__(self, app):
+        self.app = app
+        self.router = APIRouter()
+
+    def register_all_apis(self, categories: Optional[List[APICategory]] = None):
+        """
+        Discover and register API modules from specified categories
+
+        Args:
+            categories: List of categories to register.
+                       If None, registers all categories.
+        """
+        if categories is None:
+            categories = ["common", "vllm", "controller"]
+
+        package_path = Path(__file__).parent
+        package_name = __package__
+
+        for category in categories:
+            category_path = package_path / category
+            if not category_path.exists():
+                continue
+
+            category_package = f"{package_name}.{category}"
+            for r in discover_api_routers(category_path, category_package):
+                self.router.include_router(r)
+
+        self.app.include_router(self.router)
diff --git a/lmcache/v1/internal_api_server/api_server.py b/lmcache/v1/internal_api_server/api_server.py
new file mode 100644
index 0000000..14b020e
--- /dev/null
+++ b/lmcache/v1/internal_api_server/api_server.py
@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING
+import asyncio
+import os
+import threading
+
+# Third Party
+from fastapi import FastAPI
+import uvicorn
+
+# First Party
+from lmcache.logging import init_logger
+
+# Local
+from .api_registry import APIRegistry
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.manager import LMCacheManager
+
+logger = init_logger(__name__)
+
+
+def _build_app() -> FastAPI:
+    """Create a fresh FastAPI app with all internal API routes registered."""
+    new_app = FastAPI()
+    APIRegistry(new_app).register_all_apis()
+    return new_app
+
+
+# Module-level app kept for backward compatibility with existing tests that
+# import `app` directly. Production code no longer relies on this shared
+# singleton; each InternalAPIServer owns its own FastAPI app so that
+# multiple instances in the same process (e.g. scheduler + worker in TP=1
+# non-MP mode) do not overwrite each other's app.state.lmcache_adapter.
+app = _build_app()
+
+
+class InternalAPIServer:
+    def __init__(self, lmcache_manager: "LMCacheManager"):
+        lmcache_engine = lmcache_manager.lmcache_engine
+
+        # Check if lmcache_engine is None and handle accordingly
+        if lmcache_engine is None:
+            # Use manager's config directly when engine is not available
+            config = lmcache_manager.config
+            port_offset = 0  # Default for scheduler mode
+        else:
+            config = lmcache_engine.config
+            # 0 for scheduler, 1 for worker 0, 2 for worker 1, ...
+            port_offset = 1 + lmcache_engine.metadata.worker_id
+
+        self.port = config.internal_api_server_port_start + port_offset
+        self.socket_path_prefix = config.internal_api_server_socket_path_prefix
+        self.socket_path = (
+            f"{self.socket_path_prefix}_{self.port}"
+            if self.socket_path_prefix
+            else None
+        )
+        include_index_list = config.internal_api_server_include_index_list
+
+        self.enable = True
+        if not config.internal_api_server_enabled or (
+            include_index_list and port_offset not in include_index_list
+        ):
+            logger.info(
+                "Internal API server disabled. internal_api_server_enabled=%s, "
+                "port_offset=%s, port=%s, socket_path=%s, include_index_list=%s",
+                config.internal_api_server_enabled,
+                port_offset,
+                self.port,
+                self.socket_path,
+                include_index_list,
+            )
+            self.enable = False
+            return
+
+        self.app = _build_app()
+
+        uvicorn_config = {
+            "app": self.app,
+            "host": config.internal_api_server_host,
+            "loop": "uvloop",
+            "http": "httptools",
+            "access_log": config.get_extra_config_value(
+                "internal_api_server_access_log", True
+            ),
+            "log_level": config.get_extra_config_value(
+                "internal_api_server_log_level", "warning"
+            ),
+        }
+
+        if self.socket_path:
+            self.server_log_info = f"socket {self.socket_path}"
+            logger.info("Init internal API server on %s", self.server_log_info)
+            uvicorn_config["uds"] = self.socket_path
+            # Ensure socket directory exists
+            os.makedirs(os.path.dirname(self.socket_path), exist_ok=True)
+            # Remove existing socket file if exists
+            if os.path.exists(self.socket_path):
+                os.unlink(self.socket_path)
+        else:
+            self.server_log_info = f"port {self.port}"
+            logger.info("Init internal API server on %s", self.server_log_info)
+            uvicorn_config["port"] = self.port
+
+        self.server = uvicorn.Server(uvicorn.Config(**uvicorn_config))
+        self.app.state.lmcache_adapter = lmcache_manager
+
+    async def run(self):
+        logger.info("Running LMCache internal API server on %s", self.server_log_info)
+        if self.server:
+            await self.server.serve()
+
+    def start(self):
+        if not self.enable:
+            return
+        logger.info("Starting LMCache internal API server on %s", self.server_log_info)
+        threading.Thread(
+            target=asyncio.run,
+            args=(self.run(),),
+            daemon=True,
+            name="api-server-thread",
+        ).start()
+
+    def stop(self):
+        if not self.enable:
+            return
+        logger.info("Stopping LMCache internal API server")
+        if self.server:
+            self.server.should_exit = True
+            if self.socket_path and os.path.exists(self.socket_path):
+                os.unlink(self.socket_path)
diff --git a/lmcache/v1/internal_api_server/common/__init__.py b/lmcache/v1/internal_api_server/common/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/internal_api_server/common/env_api.py b/lmcache/v1/internal_api_server/common/env_api.py
new file mode 100644
index 0000000..88d462d
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/env_api.py
@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import json
+import os
+
+# Third Party
+from fastapi import APIRouter
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+@router.get("/env")
+async def get_env():
+    """
+    Get all environment variables
+    """
+    env_dict = dict(os.environ)
+    return PlainTextResponse(
+        content=json.dumps(env_dict, indent=2, sort_keys=True),
+        media_type="text/plain",
+    )
diff --git a/lmcache/v1/internal_api_server/common/loglevel_api.py b/lmcache/v1/internal_api_server/common/loglevel_api.py
new file mode 100644
index 0000000..5d5d74c
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/loglevel_api.py
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+import logging
+
+# Third Party
+from fastapi import APIRouter
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+@router.get("/loglevel")
+async def get_or_set_log_level(
+    logger_name: Optional[str] = None, level: Optional[str] = None
+):
+    """
+    Get or set the log level for a logger.
+    - No parameters: List all loggers and their levels.
+    - With logger_name: Get the level of the specified logger.
+    - With logger_name and level: Set the level of the specified logger.
+    """
+    if not logger_name and not level:
+        # List all loggers and their levels
+        loggers = logging.Logger.manager.loggerDict
+        result = "=== Loggers and Levels ===\n"
+        for name, logger_obj in loggers.items():
+            if isinstance(logger_obj, logging.Logger):
+                result += "%s: %s\n" % (name, logging.getLevelName(logger_obj.level))
+        return PlainTextResponse(content=result, media_type="text/plain")
+    elif logger_name and not level:
+        # Get the level of the specified logger
+        target_logger = logging.getLogger(logger_name)
+        return PlainTextResponse(
+            content="%s: %s" % (logger_name, logging.getLevelName(target_logger.level)),
+            media_type="text/plain",
+        )
+    elif logger_name and level:
+        # Set the level of the specified logger
+        target_logger = logging.getLogger(logger_name)
+        try:
+            level_value = getattr(logging, level.upper())
+            target_logger.setLevel(level_value)
+            # Set the level of all handlers
+            for handler in target_logger.handlers:
+                handler.setLevel(level_value)
+            return PlainTextResponse(
+                content="Set %s level to %s (including all handlers)"
+                % (logger_name, level.upper()),
+                media_type="text/plain",
+            )
+        except AttributeError:
+            return PlainTextResponse(
+                content="Invalid log level: %s" % level,
+                media_type="text/plain",
+                status_code=400,
+            )
diff --git a/lmcache/v1/internal_api_server/common/metrics_api.py b/lmcache/v1/internal_api_server/common/metrics_api.py
new file mode 100644
index 0000000..6e1d03c
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/metrics_api.py
@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+from fastapi import APIRouter
+from prometheus_client import REGISTRY, generate_latest
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+# First Party
+from lmcache.observability import reset_observability_metrics
+
+router = APIRouter()
+
+
+@router.get("/metrics")
+async def get_metrics(request: Request):
+    """
+    Provide Prometheus metrics data
+    """
+    metrics_data = generate_latest(REGISTRY)
+    return PlainTextResponse(content=metrics_data, media_type="text/plain")
+
+
+@router.post("/metrics/reset")
+async def reset_metrics():
+    """
+    Reset Prometheus metrics to their initial state.
+    """
+    reset_observability_metrics()
+    return PlainTextResponse(content="ok", media_type="text/plain")
diff --git a/lmcache/v1/internal_api_server/common/periodic_thread_api.py b/lmcache/v1/internal_api_server/common/periodic_thread_api.py
new file mode 100644
index 0000000..b87e2fe
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/periodic_thread_api.py
@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+API endpoint for monitoring periodic threads.
+"""
+
+# Standard
+from typing import Optional
+
+# Third Party
+from fastapi import APIRouter, Query
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+# First Party
+from lmcache.v1.periodic_thread import PeriodicThreadRegistry, ThreadLevel
+
+router = APIRouter()
+
+
+@router.get("/periodic-threads")
+async def get_periodic_threads(
+    request: Request,
+    level: Optional[str] = Query(
+        None,
+        description="Filter by thread level (critical, high, medium, low)",
+    ),
+    running_only: bool = Query(
+        False,
+        description="Only show running threads",
+    ),
+    active_only: bool = Query(
+        False,
+        description="Only show active threads",
+    ),
+):
+    """
+    Get information about registered periodic threads.
+
+    Returns a summary of all periodic threads including:
+    - Total, running, and active counts by level
+    - Individual thread status with last run time and summary
+    """
+    registry = PeriodicThreadRegistry.get_instance()
+
+    # Get all threads
+    if level:
+        try:
+            thread_level = ThreadLevel(level.lower())
+            threads = registry.get_by_level(thread_level)
+        except ValueError:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "error": f"Invalid level: {level}. "
+                    f"Valid values: critical, high, medium, low"
+                },
+            )
+    else:
+        threads = registry.get_all()
+
+    # Apply filters
+    if running_only:
+        threads = [t for t in threads if t.is_running]
+    if active_only:
+        threads = [t for t in threads if t.is_active]
+
+    # Build response
+    thread_statuses = [t.get_status() for t in threads]
+
+    # Get summary
+    summary = registry.get_summary()
+
+    return JSONResponse(
+        content={
+            "summary": {
+                "total_count": summary["total_count"],
+                "running_count": summary["running_count"],
+                "active_count": summary["active_count"],
+                "by_level": summary["by_level"],
+            },
+            "threads": thread_statuses,
+        }
+    )
+
+
+@router.get("/periodic-threads/{thread_name}")
+async def get_periodic_thread(
+    request: Request,
+    thread_name: str,
+):
+    """
+    Get detailed information about a specific periodic thread.
+    """
+    registry = PeriodicThreadRegistry.get_instance()
+    thread = registry.get(thread_name)
+
+    if thread is None:
+        return JSONResponse(
+            status_code=404,
+            content={"error": f"Thread not found: {thread_name}"},
+        )
+
+    return JSONResponse(content=thread.get_status())
+
+
+@router.get("/periodic-threads-health")
+async def get_periodic_threads_health(request: Request):
+    """
+    Quick health check for periodic threads.
+
+    Returns:
+    - healthy: True if all critical/high level threads are active
+    - unhealthy_threads: List of inactive critical/high threads
+    """
+    registry = PeriodicThreadRegistry.get_instance()
+
+    unhealthy_threads = []
+
+    # Check critical and high level threads
+    for level in [ThreadLevel.CRITICAL, ThreadLevel.HIGH]:
+        for thread in registry.get_by_level(level):
+            if thread.is_running and not thread.is_active:
+                unhealthy_threads.append(
+                    {
+                        "name": thread.name,
+                        "level": thread.level.value,
+                        "last_run_ago": thread.get_status().get("last_run_ago"),
+                        "interval": thread.interval,
+                    }
+                )
+
+    return JSONResponse(
+        content={
+            "healthy": len(unhealthy_threads) == 0,
+            "unhealthy_count": len(unhealthy_threads),
+            "unhealthy_threads": unhealthy_threads,
+        }
+    )
diff --git a/lmcache/v1/internal_api_server/common/run_script_api.py b/lmcache/v1/internal_api_server/common/run_script_api.py
new file mode 100644
index 0000000..e3f2bad
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/run_script_api.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, List
+import importlib
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+
+def _get_allowed_imports(request: Request) -> List[str]:
+    """Extract script_allowed_imports from either inProcess or mp mode."""
+    adapter = getattr(request.app.state, "lmcache_adapter", None)
+    if adapter is not None:
+        return getattr(adapter.config, "script_allowed_imports", None) or []
+    configs = getattr(request.app.state, "configs", None)
+    if isinstance(configs, dict):
+        mp_cfg = configs.get("mp")
+        return getattr(mp_cfg, "script_allowed_imports", None) or []
+    return []
+
+
+@router.post("/run_script")
+async def run_script(request: Request):
+    form_data = await request.form()
+    script_file = form_data.get("script")
+
+    if not script_file or not hasattr(script_file, "file"):
+        return PlainTextResponse("No script file provided", status_code=400)
+
+    script_content = await script_file.read()
+
+    try:
+        allowed_imports = _get_allowed_imports(request)
+
+        # Pre-import allowed modules
+        allowed_modules = {}
+        for module_name in allowed_imports:
+            try:
+                module = importlib.import_module(module_name)
+                allowed_modules[module_name] = module
+                logger.info("Imported allowed module: %s", module_name)
+            except ImportError as e:
+                logger.warning("Failed to import module %s: %s", module_name, e)
+
+        # Create custom __import__ function that only allows configured modules
+        def restricted_import(name, globals=None, locals=None, fromlist=(), level=0):
+            if name in allowed_modules:
+                return allowed_modules[name]
+            raise ImportError(f"Import of '{name}' is not allowed")
+
+        restricted_globals = {
+            "__builtins__": {
+                "print": print,
+                "str": str,
+                "int": int,
+                "float": float,
+                "list": list,
+                "dict": dict,
+                "tuple": tuple,
+                "set": set,
+                "__import__": restricted_import,
+            },
+            "app": request.app,
+        }
+
+        restricted_locals: dict[str, Any] = {}
+
+        exec(script_content, restricted_globals, restricted_locals)
+
+        result = restricted_locals.get("result", "Script executed successfully")
+        return PlainTextResponse(str(result), media_type="text/plain")
+
+    except Exception as e:
+        return PlainTextResponse(f"Error executing script: {str(e)}", status_code=500)
diff --git a/lmcache/v1/internal_api_server/common/thread_api.py b/lmcache/v1/internal_api_server/common/thread_api.py
new file mode 100644
index 0000000..414c06c
--- /dev/null
+++ b/lmcache/v1/internal_api_server/common/thread_api.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+import sys
+import threading
+import traceback
+
+# Third Party
+from fastapi import APIRouter, Query
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+@router.get("/threads")
+async def get_threads(
+    request: Request,
+    name: Optional[str] = Query(
+        None, description="Filter by thread name (fuzzy match)"
+    ),
+    thread_id: Optional[int] = Query(None, description="Filter by thread ID"),
+):
+    """Return information about active threads with optional filtering"""
+    threads = threading.enumerate()
+
+    filtered_threads = []
+    for t in threads:
+        # Apply filters
+        if name and name.lower() not in t.name.lower():
+            continue
+        if thread_id and t.ident != thread_id:
+            continue
+        filtered_threads.append(t)
+
+    thread_info = []
+
+    for t in filtered_threads:
+        # Basic thread info with creation time
+        info = f"Thread: {t}\n"
+
+        # Get stack trace if available
+        try:
+            stack_frames = (
+                sys._current_frames().get(t.ident) if t.ident is not None else None
+            )
+            if stack_frames:
+                stack_trace = traceback.format_stack(stack_frames)
+                info += "Stack trace:\n" + "".join(stack_trace)
+            else:
+                info += "No stack trace available\n"
+        except AttributeError:
+            info += "Stack trace unavailable\n"
+
+        thread_info.append(info)
+
+    # Add summary section
+    summary = "\n\n=== Thread Summary ===\n"
+    summary += f"Total threads: {len(filtered_threads)}\n"
+
+    return PlainTextResponse(
+        content="\n\n".join(thread_info) + summary, media_type="text/plain"
+    )
diff --git a/lmcache/v1/internal_api_server/controller/__init__.py b/lmcache/v1/internal_api_server/controller/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/internal_api_server/controller/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/internal_api_server/controller/key_stats_api.py b/lmcache/v1/internal_api_server/controller/key_stats_api.py
new file mode 100644
index 0000000..1338b5f
--- /dev/null
+++ b/lmcache/v1/internal_api_server/controller/key_stats_api.py
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List
+
+# Third Party
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class InstanceKeyStats(BaseModel):
+    instance_id: str
+    key_count: int
+    worker_count: int
+
+
+class KeyStatsResponse(BaseModel):
+    total_key_count: int
+    total_instance_count: int
+    total_worker_count: int
+    instances: List[InstanceKeyStats]
+
+
+@router.get("/controller/key-stats")
+async def get_key_stats(request: Request):
+    """
+    Get key statistics across all instances and workers.
+
+    Returns:
+        - Total key count across all instances
+        - Total instance count
+        - Total worker count
+        - Key count per instance
+    """
+    try:
+        controller_manager = getattr(
+            request.app.state, "lmcache_controller_manager", None
+        )
+
+        if controller_manager is None:
+            raise HTTPException(
+                status_code=503, detail="Controller manager not available"
+            )
+
+        reg_controller = controller_manager.reg_controller
+        registry = reg_controller.registry
+
+        # Get total key count
+        total_key_count = registry.get_total_kv_count()
+
+        # Get instances and their key counts
+        instances = []
+        total_instance_count = 0
+        total_worker_count = 0
+
+        for instance_id, instance_node in registry.instances.items():
+            total_instance_count += 1
+            workers = instance_node.workers.values()
+            num_workers = len(workers)
+            instance_key_count = sum(w.get_kv_count() for w in workers)
+            total_worker_count += num_workers
+            instances.append(
+                InstanceKeyStats(
+                    instance_id=instance_id,
+                    key_count=instance_key_count,
+                    worker_count=num_workers,
+                )
+            )
+
+        return KeyStatsResponse(
+            total_key_count=total_key_count,
+            total_instance_count=total_instance_count,
+            total_worker_count=total_worker_count,
+            instances=instances,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from None
diff --git a/lmcache/v1/internal_api_server/controller/worker_info_api.py b/lmcache/v1/internal_api_server/controller/worker_info_api.py
new file mode 100644
index 0000000..6f7dac9
--- /dev/null
+++ b/lmcache/v1/internal_api_server/controller/worker_info_api.py
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Annotated, Optional
+
+# Third Party
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class WorkerInfoResponse(BaseModel):
+    instance_id: str
+    worker_id: int
+    ip: str
+    port: int
+    peer_init_url: Optional[str]
+    registration_time: float
+    last_heartbeat_time: float
+    key_count: int
+
+
+class WorkerListResponse(BaseModel):
+    workers: list[WorkerInfoResponse]
+    total_count: int
+
+
+@router.get("/controller/workers")
+async def get_workers(
+    request: Request,
+    instance_id: Annotated[Optional[str], Query()] = None,
+    worker_id: Annotated[Optional[int], Query()] = None,
+):
+    """
+    Get worker information with flexible query parameters.
+
+    - No parameters: List all registered workers across all instances
+    - instance_id only: List all workers for a specific instance
+    - instance_id and worker_id: Get detailed info about a specific worker
+
+    Args:
+        instance_id: Optional instance ID to filter workers
+        worker_id: Optional worker ID to get specific worker details
+    """
+    try:
+        controller_manager = getattr(
+            request.app.state, "lmcache_controller_manager", None
+        )
+
+        if controller_manager is None:
+            raise HTTPException(
+                status_code=503, detail="Controller manager not available"
+            )
+
+        reg_controller = controller_manager.reg_controller
+
+        # Case 1: Get specific worker by instance_id and worker_id
+        if instance_id is not None and worker_id is not None:
+            worker_node = reg_controller.registry.get_worker(instance_id, worker_id)
+            if worker_node is None:
+                raise HTTPException(
+                    status_code=404,
+                    detail=f"Worker ({instance_id}, {worker_id}) not found",
+                )
+
+            worker_info = worker_node.to_worker_info(instance_id)
+            key_count = worker_node.get_kv_count()
+            return WorkerInfoResponse(
+                instance_id=worker_info.instance_id,
+                worker_id=worker_info.worker_id,
+                ip=worker_info.ip,
+                port=worker_info.port,
+                peer_init_url=worker_info.peer_init_url,
+                registration_time=worker_info.registration_time,
+                last_heartbeat_time=worker_info.last_heartbeat_time,
+                key_count=key_count,
+            )
+
+        # Case 2: Get all workers for a specific instance
+        elif instance_id is not None:
+            instance_node = reg_controller.registry.get_instance(instance_id)
+            if instance_node is None:
+                raise HTTPException(
+                    status_code=404,
+                    detail=f"No workers found for instance {instance_id}",
+                )
+
+            worker_infos = instance_node.get_all_worker_infos()
+            workers = []
+            for worker_info in worker_infos:
+                worker_node = reg_controller.registry.get_worker(
+                    instance_id, worker_info.worker_id
+                )
+                key_count = worker_node.get_kv_count() if worker_node else 0
+                workers.append(
+                    WorkerInfoResponse(
+                        instance_id=worker_info.instance_id,
+                        worker_id=worker_info.worker_id,
+                        ip=worker_info.ip,
+                        port=worker_info.port,
+                        peer_init_url=worker_info.peer_init_url,
+                        registration_time=worker_info.registration_time,
+                        last_heartbeat_time=worker_info.last_heartbeat_time,
+                        key_count=key_count,
+                    )
+                )
+
+            return WorkerListResponse(workers=workers, total_count=len(workers))
+
+        # Case 3: Get all workers across all instances
+        else:
+            worker_infos = reg_controller.registry.get_all_worker_infos_cached()
+            workers = []
+            for worker_info in worker_infos:
+                worker_node = reg_controller.registry.get_worker(
+                    worker_info.instance_id, worker_info.worker_id
+                )
+                key_count = worker_node.get_kv_count() if worker_node else 0
+                workers.append(
+                    WorkerInfoResponse(
+                        instance_id=worker_info.instance_id,
+                        worker_id=worker_info.worker_id,
+                        ip=worker_info.ip,
+                        port=worker_info.port,
+                        peer_init_url=worker_info.peer_init_url,
+                        registration_time=worker_info.registration_time,
+                        last_heartbeat_time=worker_info.last_heartbeat_time,
+                        key_count=key_count,
+                    )
+                )
+
+            return WorkerListResponse(workers=workers, total_count=len(workers))
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e)) from None
diff --git a/lmcache/v1/internal_api_server/utils.py b/lmcache/v1/internal_api_server/utils.py
new file mode 100644
index 0000000..2307900
--- /dev/null
+++ b/lmcache/v1/internal_api_server/utils.py
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict, List
+
+
+def get_all_server_infos(config, worker_count) -> List[Dict[str, str]]:
+    """
+    Generate a list of server information (scheduler and workers) based on the config.
+
+    Args:
+        config: The configuration object containing server details.
+        worker_count: The number of worker servers.
+
+    Returns:
+        List[Dict[str, str]]: A JSON list with server information.
+    """
+    servers = []
+    include_index_list = getattr(config, "internal_api_server_include_index_list", None)
+    socket_path_prefix = getattr(config, "internal_api_server_socket_path_prefix", None)
+
+    # Add scheduler info (index 0)
+    if include_index_list is None or 0 in include_index_list:
+        port = config.internal_api_server_port_start
+        server_info = {
+            "name": f"{config.lmcache_instance_id}_scheduler",
+            "host": config.internal_api_server_host,
+            "port": f"{socket_path_prefix}_{port}" if socket_path_prefix else port,
+        }
+        servers.append(server_info)
+
+    # Add workers info (index 1 to worker_count)
+    for worker_id in range(worker_count):
+        port_offset = 1 + worker_id
+        if include_index_list is None or port_offset in include_index_list:
+            port = config.internal_api_server_port_start + port_offset
+            server_info = {
+                "name": f"{config.lmcache_instance_id}_worker{worker_id}",
+                "host": config.internal_api_server_host,
+                "port": f"{socket_path_prefix}_{port}" if socket_path_prefix else port,
+            }
+            servers.append(server_info)
+
+    return servers
diff --git a/lmcache/v1/internal_api_server/vllm/__init__.py b/lmcache/v1/internal_api_server/vllm/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/internal_api_server/vllm/backend_api.py b/lmcache/v1/internal_api_server/vllm/backend_api.py
new file mode 100644
index 0000000..3ecf70b
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/backend_api.py
@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+
+def _get_storage_manager(request: Request):
+    """Extract storage_manager from the request app state.
+
+    Returns:
+        The StorageManager instance, or None if unavailable.
+    """
+    engine = getattr(
+        request.app.state.lmcache_adapter,
+        "lmcache_engine",
+        None,
+    )
+    if engine is None:
+        return None
+    return getattr(engine, "storage_manager", None)
+
+
+def _unavailable_response(endpoint: str) -> JSONResponse:
+    """Return a 503 response when the engine is unavailable."""
+    return JSONResponse(
+        content={
+            "error": "%s API is unavailable" % endpoint,
+            "message": "LMCache engine not configured.",
+        },
+        status_code=503,
+    )
+
+
+@router.get("/backends")
+async def list_backends(request: Request):
+    """List all active storage backends.
+
+    Returns:
+        JSONResponse: JSON dict mapping backend name
+        to class name.
+
+    Example:
+        .. code-block:: bash
+
+            curl http://localhost:7000/backends
+    """
+    sm = _get_storage_manager(request)
+    if sm is None:
+        return _unavailable_response("/backends")
+
+    try:
+        backends = sm.list_backends()
+        return JSONResponse(content=backends)
+    except Exception as e:
+        logger.exception("Failed to list backends")
+        return JSONResponse(
+            content={
+                "error": "Failed to list backends",
+                "message": str(e),
+            },
+            status_code=500,
+        )
+
+
+@router.delete("/backends/{backend_name}")
+async def close_backend(request: Request, backend_name: str):
+    """Close and remove a specific storage backend.
+
+    The backend will be closed and removed from the internal
+    dict so that no stale references remain.
+
+    Args:
+        backend_name: Name of the backend to close
+            (e.g. ``RemoteBackend``, ``LocalDiskBackend``).
+
+    Returns:
+        JSONResponse: Status of the close operation.
+
+    Example:
+        .. code-block:: bash
+
+            curl -X DELETE \\
+                http://localhost:7000/backends/RemoteBackend
+    """
+    sm = _get_storage_manager(request)
+    if sm is None:
+        return _unavailable_response("/backends")
+
+    try:
+        success = sm.close_backend(backend_name)
+        if success:
+            return JSONResponse(
+                content={
+                    "status": "success",
+                    "message": "Backend %s closed" % backend_name,
+                    "backends": sm.list_backends(),
+                },
+            )
+        return JSONResponse(
+            content={
+                "status": "not_found",
+                "message": "Backend %s not found" % backend_name,
+                "backends": sm.list_backends(),
+            },
+            status_code=404,
+        )
+    except Exception as e:
+        logger.exception("Failed to close backend: %s", backend_name)
+        return JSONResponse(
+            content={
+                "error": "Failed to close backend",
+                "message": str(e),
+            },
+            status_code=500,
+        )
+
+
+@router.post("/backends")
+async def create_backends(request: Request):
+    """Create new storage backends from current config.
+
+    Backends that are already present will be skipped.
+    This allows a workflow of:
+
+    1. ``DELETE /backends/RemoteBackend`` — close old backend
+    2. ``POST /conf`` — update config (e.g. ``remote_url``)
+    3. ``POST /backends`` — create new backends from config
+
+    Returns:
+        JSONResponse: Dict of newly created backends and the
+        full list of active backends.
+
+    Example:
+        .. code-block:: bash
+
+            curl -X POST http://localhost:7000/backends
+    """
+    sm = _get_storage_manager(request)
+    if sm is None:
+        return _unavailable_response("/backends")
+
+    try:
+        created = sm.create_backends()
+        return JSONResponse(
+            content={
+                "status": "success",
+                "created": created,
+                "backends": sm.list_backends(),
+            },
+        )
+    except Exception as e:
+        logger.exception("Failed to create backends")
+        return JSONResponse(
+            content={
+                "error": "Failed to create backends",
+                "message": str(e),
+            },
+            status_code=500,
+        )
+
+
+@router.post("/backends/{backend_name}/recreate")
+async def recreate_backend(request: Request, backend_name: str):
+    """Recreate a specific storage backend atomically.
+
+    The backend will be closed and recreated from the current
+    config in a single step.
+
+    Args:
+        backend_name: Name of the backend to recreate
+            (e.g. ``RemoteBackend``).
+
+    Returns:
+        JSONResponse: Dict of recreated backends and the
+        full list of active backends.
+
+    Example:
+        .. code-block:: bash
+
+            curl -X POST \\
+                http://localhost:7000/backends/RemoteBackend/recreate
+    """
+    sm = _get_storage_manager(request)
+    if sm is None:
+        return _unavailable_response("/backends")
+
+    try:
+        created = sm.recreate_backend(backend_name)
+        return JSONResponse(
+            content={
+                "status": "success",
+                "recreated": created,
+                "backends": sm.list_backends(),
+            },
+        )
+    except KeyError:
+        return JSONResponse(
+            content={
+                "status": "not_found",
+                "message": ("Backend %s not found" % backend_name),
+                "backends": sm.list_backends(),
+            },
+            status_code=404,
+        )
+    except Exception as e:
+        logger.exception("Failed to recreate backend: %s", backend_name)
+        return JSONResponse(
+            content={
+                "error": "Failed to recreate backend",
+                "message": str(e),
+            },
+            status_code=500,
+        )
diff --git a/lmcache/v1/internal_api_server/vllm/bypass_api.py b/lmcache/v1/internal_api_server/vllm/bypass_api.py
new file mode 100644
index 0000000..011cc1b
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/bypass_api.py
@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+router = APIRouter()
+
+
+def _get_storage_manager(request: Request):
+    """
+    Get the StorageManager from the request's app state.
+
+    Returns:
+        Tuple of (storage_manager, error_response).
+        If storage_manager is None, error_response is set.
+    """
+    lmcache_adapter = request.app.state.lmcache_adapter
+    lmcache_engine = getattr(lmcache_adapter, "lmcache_engine", None)
+    if not lmcache_engine:
+        error_info = {
+            "error": "Bypass API is unavailable",
+            "message": "LMCache engine not configured.",
+        }
+        return None, JSONResponse(
+            content=error_info,
+            status_code=503,
+        )
+    sm = lmcache_engine.storage_manager
+    if sm is None:
+        error_info = {
+            "error": "Bypass API is unavailable",
+            "message": "StorageManager not initialized.",
+        }
+        return None, JSONResponse(
+            content=error_info,
+            status_code=503,
+        )
+    return sm, None
+
+
+@router.get("/bypass/list")
+async def list_bypassed_backends(request: Request):
+    """
+    List all currently bypassed backends and all available
+    backend names.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        JSONResponse: JSON with bypassed and all backends.
+    """
+    try:
+        sm, err = _get_storage_manager(request)
+        if err:
+            return err
+
+        result = {
+            "status": "success",
+            "bypassed_backends": sm.get_bypassed_backends(),
+            "all_backends": sm.get_all_backend_names(),
+        }
+        return JSONResponse(content=result)
+    except Exception as e:
+        error_info = {
+            "error": "Failed to list bypassed backends",
+            "message": str(e),
+        }
+        return JSONResponse(
+            content=error_info,
+            status_code=500,
+        )
+
+
+@router.put("/bypass/add")
+async def add_bypass_backend(request: Request):
+    """
+    Add a backend to the bypass list.
+
+    Query Parameters:
+        backend_name: The name of the backend to bypass.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        JSONResponse: JSON with operation result.
+    """
+    try:
+        sm, err = _get_storage_manager(request)
+        if err:
+            return err
+
+        backend_name = request.query_params.get("backend_name", "")
+        if not backend_name:
+            error_info = {
+                "error": "Missing parameter",
+                "message": "backend_name is required",
+            }
+            return JSONResponse(
+                content=error_info,
+                status_code=400,
+            )
+
+        all_names = sm.get_all_backend_names()
+        if backend_name not in all_names:
+            error_info = {
+                "error": "Unknown backend",
+                "message": "Backend '%s' not found. "
+                "Available: %s" % (backend_name, all_names),
+            }
+            return JSONResponse(
+                content=error_info,
+                status_code=400,
+            )
+
+        already = sm.is_backend_bypassed(backend_name)
+        if not already:
+            sm.set_backend_bypass(backend_name, True)
+
+        result = {
+            "status": "success",
+            "backend_name": backend_name,
+            "bypassed": True,
+            "was_already_bypassed": already,
+            "bypassed_backends": sm.get_bypassed_backends(),
+        }
+        return JSONResponse(content=result)
+    except Exception as e:
+        error_info = {
+            "error": "Failed to add bypass backend",
+            "message": str(e),
+        }
+        return JSONResponse(
+            content=error_info,
+            status_code=500,
+        )
+
+
+@router.put("/bypass/remove")
+async def remove_bypass_backend(request: Request):
+    """
+    Remove a backend from the bypass list, restoring it
+    to normal operation.
+
+    Query Parameters:
+        backend_name: The backend name to restore.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        JSONResponse: JSON with operation result.
+    """
+    try:
+        sm, err = _get_storage_manager(request)
+        if err:
+            return err
+
+        backend_name = request.query_params.get("backend_name", "")
+        if not backend_name:
+            error_info = {
+                "error": "Missing parameter",
+                "message": "backend_name is required",
+            }
+            return JSONResponse(
+                content=error_info,
+                status_code=400,
+            )
+
+        all_names = sm.get_all_backend_names()
+        if backend_name not in all_names:
+            error_info = {
+                "error": "Unknown backend",
+                "message": "Backend '%s' not found. "
+                "Available: %s" % (backend_name, all_names),
+            }
+            return JSONResponse(
+                content=error_info,
+                status_code=400,
+            )
+
+        was_bypassed = sm.is_backend_bypassed(backend_name)
+        if was_bypassed:
+            sm.set_backend_bypass(backend_name, False)
+
+        result = {
+            "status": "success",
+            "backend_name": backend_name,
+            "bypassed": False,
+            "was_bypassed": was_bypassed,
+            "bypassed_backends": sm.get_bypassed_backends(),
+        }
+        return JSONResponse(content=result)
+    except Exception as e:
+        error_info = {
+            "error": "Failed to remove bypass backend",
+            "message": str(e),
+        }
+        return JSONResponse(
+            content=error_info,
+            status_code=500,
+        )
diff --git a/lmcache/v1/internal_api_server/vllm/cache_api.py b/lmcache/v1/internal_api_server/vllm/cache_api.py
new file mode 100644
index 0000000..a0fb7fc
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/cache_api.py
@@ -0,0 +1,897 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Annotated, Any, Callable, List, Optional, Tuple
+import asyncio
+import hashlib
+import json
+import traceback
+
+# Third Party
+from fastapi import APIRouter, Query
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    compress_slot_mapping,
+    parse_mixed_slot_mapping,
+)
+from lmcache.v1.cache_engine import LMCacheEngine
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+
+def _parse_tokens_from_params(
+    tokens_mock: Optional[str],
+) -> Tuple[Optional[List[int]], Optional[dict]]:
+    """Parse tokens from input parameters.
+
+    Args:
+        tokens_mock: Two comma-separated numbers specifying start and end of token range
+            - Example: "0,100" generates tokens [0, 1, 2, ..., 99]
+            - Example: "50,75" generates tokens [50, 51, 52, ..., 74]
+
+    Returns:
+        Tuple of (tokens list, error dict).
+        If error dict is not None, tokens will be None.
+    """
+    # TODO(baoloongmao): Add support for tokens_input parameter to read tokens from file
+    if tokens_mock:
+        try:
+            parts = tokens_mock.split(",")
+            if len(parts) != 2:
+                raise ValueError("tokens_mock must contain exactly 2 numbers")
+            start, end = int(parts[0].strip()), int(parts[1].strip())
+            if start >= end:
+                raise ValueError("start must be less than end")
+            tokens = list(range(start, end))
+            return tokens, None
+        except ValueError as e:
+            return None, {
+                "error": "Invalid tokens_mock format",
+                "message": f"tokens_mock must be 'start,end': {str(e)}",
+            }
+    else:
+        return None, {
+            "error": "Missing parameters",
+            "message": "Must specify either tokens_input or tokens_mock",
+        }
+
+
+def _create_error_response(error_info: dict, status_code: int) -> PlainTextResponse:
+    """Create a standardized error response.
+
+    Args:
+        error_info: Dictionary containing error information
+        status_code: HTTP status code
+
+    Returns:
+        PlainTextResponse with error information
+    """
+    return PlainTextResponse(
+        content=json.dumps(error_info, indent=2),
+        media_type="application/json",
+        status_code=status_code,
+    )
+
+
+def _check_lmcache_engine(
+    request: Request,
+) -> Tuple[Optional["LMCacheEngine"], Optional[PlainTextResponse]]:
+    """Check if LMCache engine is available.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        Tuple of (lmcache_engine, error_response).
+        If error_response is not None, engine will be None.
+    """
+    lmcache_adapter = request.app.state.lmcache_adapter
+    lmcache_engine = getattr(lmcache_adapter, "lmcache_engine", None)
+    if not lmcache_engine:
+        error_info = {
+            "error": "LMCache API is unavailable",
+            "message": "LMCache engine not configured.",
+        }
+        return None, _create_error_response(error_info, 503)
+    return lmcache_engine, None
+
+
+def _get_kvcaches_and_device(engine):
+    """Get kvcaches and device from engine's gpu_connector.
+
+    Args:
+        engine: LMCache engine instance
+
+    Returns:
+        Tuple of (kvcaches, device).
+        kvcaches may be None if not available.
+        device defaults to "cpu" if kvcaches not available.
+    """
+    kvcaches = None
+    device = "cpu"  # Default device
+
+    if engine.gpu_connector:
+        kvcaches = engine.gpu_connector.kvcaches
+        if kvcaches is not None and len(kvcaches) > 0:
+            device = kvcaches[0].device
+            logger.debug("Using kvcaches device: %s", device)
+        else:
+            logger.warning(
+                "gpu_connector.kvcaches is None or empty. "
+                "Make sure post_init was called with kvcaches."
+            )
+
+    return kvcaches, device
+
+
+def _compute_tensor_checksum(tensor: torch.Tensor) -> str:
+    """Compute MD5 checksum of a tensor."""
+    # Move to CPU and convert to bytes for hashing
+    # Handle BFloat16 which is not supported by numpy
+    if tensor.dtype == torch.bfloat16:
+        # Convert bfloat16 to float32 for numpy compatibility
+        tensor = tensor.to(torch.float32)
+
+    tensor_bytes = tensor.detach().cpu().contiguous().numpy().tobytes()
+    return hashlib.md5(tensor_bytes).hexdigest()
+
+
+def _slice_by_slot_dim(
+    kv_at_slots: torch.Tensor, start_idx: int, end_idx: int
+) -> torch.Tensor:
+    """Slice tensor by slot dimension based on tensor ndim."""
+    if kv_at_slots.ndim == 4:
+        # MHA: [2, num_slots, num_heads, head_size]
+        return kv_at_slots[:, start_idx:end_idx, :, :]
+    elif kv_at_slots.ndim == 3:
+        # 4D format: [num_slots, num_heads, head_size]
+        return kv_at_slots[start_idx:end_idx, :, :]
+    else:
+        # MLA: [num_slots, head_size]
+        return kv_at_slots[start_idx:end_idx, :]
+
+
+def _extract_kv_at_slots(
+    kv_tensor: torch.Tensor, slot_tensor: torch.Tensor
+) -> torch.Tensor:
+    """Extract KV data at specified slot positions from kv_tensor.
+
+    Handles different kv_tensor formats:
+    - MHA (5D): [2, num_blocks, block_size, num_heads, head_size]
+    - MLA (3D): [num_blocks, block_size, head_size]
+
+    The slot_mapping is calculated as:
+        slot_idx = block_id * block_size + block_offset
+
+    This means we can reshape the tensor to flatten (num_blocks, block_size)
+    into a single slot dimension and index directly.
+
+    Args:
+        kv_tensor: The KV cache tensor for a single layer.
+        slot_tensor: Tensor of slot indices to extract.
+
+    Returns:
+        Tensor with KV data at the specified slots.
+        - MHA: shape [2, num_slots, num_heads, head_size]
+        - MLA: shape [num_slots, head_size]
+    """
+    ndim = kv_tensor.ndim
+
+    if ndim == 5:
+        # MHA format: [2, num_blocks, block_size, num_heads, head_size]
+        # Reshape to [2, num_blocks * block_size, num_heads, head_size]
+        # then index by slot_tensor on dimension 1
+        kv_2d = 2
+        num_heads = kv_tensor.shape[3]
+        head_size = kv_tensor.shape[4]
+        kv_reshaped = kv_tensor.reshape(kv_2d, -1, num_heads, head_size)
+        return kv_reshaped[:, slot_tensor, :, :]
+    elif ndim == 3:
+        # MLA format: [num_blocks, block_size, head_size]
+        # Reshape to [num_blocks * block_size, head_size]
+        head_size = kv_tensor.shape[2]
+        kv_reshaped = kv_tensor.reshape(-1, head_size)
+        return kv_reshaped[slot_tensor, :]
+    elif ndim == 4:
+        # Alternative format: [num_blocks, block_size, num_heads, head_size]
+        # (used in some test cases)
+        num_heads = kv_tensor.shape[2]
+        head_size = kv_tensor.shape[3]
+        kv_reshaped = kv_tensor.reshape(-1, num_heads, head_size)
+        return kv_reshaped[slot_tensor, :, :]
+    else:
+        # Fallback: try the original approach
+        logger.warning(
+            "Unknown kv_tensor ndim=%d, shape=%s. Using fallback indexing.",
+            ndim,
+            kv_tensor.shape,
+        )
+        return kv_tensor.view(-1, *kv_tensor.shape[2:])[slot_tensor]
+
+
+def compute_kvcache_checksums(
+    lmcache_adapter,
+    slot_indices: list[int],
+    chunk_size: Optional[int] = None,
+    layerwise: bool = False,
+) -> Optional[dict[str, Any]]:
+    """Compute MD5 checksums for kvcaches at specified slot positions.
+
+    This method is used by the kvcache check API to verify that stored
+    and retrieved kvcaches are identical.
+
+    The slot_mapping is calculated in vllm_v1_adapter.py as:
+        slot_idx = block_id * block_size + block_offset
+
+    For vLLM kv_cache formats:
+    - MHA (5D): [2, num_blocks, block_size, num_heads, head_size]
+    - MLA (3D): [num_blocks, block_size, head_size]
+
+    Args:
+        lmcache_adapter: The LMCache adapter containing kv_caches.
+        slot_indices: List of slot indices to compute checksums for.
+        chunk_size: Optional chunk size for computing per-chunk checksums.
+            If provided, will compute checksums for each chunk.
+        layerwise: If True, output per-layer checksums for each chunk.
+            If False (default), output one checksum per chunk (all layers combined).
+
+    Returns:
+        Dictionary containing:
+        - 'chunk_checksums': (if layerwise=True) dict mapping layer names to
+          list of per-chunk checksums
+        - 'chunk_checksums': (if layerwise=False) list of checksums, one per chunk
+          (each checksum covers all layers for that chunk)
+        Returns None if kv_caches is not available.
+    """
+    if not lmcache_adapter.kv_caches:
+        logger.warning("kv_caches is empty, cannot compute checksums")
+        return None
+
+    if chunk_size is None or chunk_size <= 0:
+        return {"chunk_checksums": [], "chunk_size": chunk_size, "num_chunks": 0}
+
+    num_slots = len(slot_indices)
+    num_chunks = (num_slots + chunk_size - 1) // chunk_size
+
+    # Pre-extract all layer data at slot positions
+    layer_data_at_slots: dict[str, torch.Tensor] = {}
+    for layer_name, kv_tensor in lmcache_adapter.kv_caches.items():
+        try:
+            slot_tensor = torch.tensor(
+                slot_indices, dtype=torch.long, device=kv_tensor.device
+            )
+            layer_data_at_slots[layer_name] = _extract_kv_at_slots(
+                kv_tensor, slot_tensor
+            )
+        except Exception as e:
+            logger.error("Failed to extract data for layer %s: %s", layer_name, str(e))
+            layer_data_at_slots[layer_name] = None  # type: ignore
+
+    if layerwise:
+        # Output per-layer checksums for each chunk: {layer_name: [checksum1, ...]}
+        chunk_checksums: dict[str, list[str]] = {}
+        for layer_name, kv_at_slots in layer_data_at_slots.items():
+            if kv_at_slots is None:
+                chunk_checksums[layer_name] = ["error"] * num_chunks
+                continue
+            chunk_checksum_list: list[str] = []
+            for chunk_idx in range(num_chunks):
+                start_idx = chunk_idx * chunk_size
+                end_idx = min(start_idx + chunk_size, num_slots)
+                chunk_data = _slice_by_slot_dim(kv_at_slots, start_idx, end_idx)
+                chunk_checksum_list.append(_compute_tensor_checksum(chunk_data))
+            chunk_checksums[layer_name] = chunk_checksum_list
+        return {
+            "chunk_checksums": chunk_checksums,
+            "chunk_size": chunk_size,
+            "num_chunks": num_chunks,
+        }
+    else:
+        # Output one checksum per chunk (all layers combined): [checksum1, ...]
+        chunk_checksums_list: list[str] = []
+        for chunk_idx in range(num_chunks):
+            start_idx = chunk_idx * chunk_size
+            end_idx = min(start_idx + chunk_size, num_slots)
+            md5_hash = hashlib.md5()
+            for layer_name in sorted(layer_data_at_slots.keys()):
+                kv_at_slots = layer_data_at_slots[layer_name]
+                if kv_at_slots is None:
+                    continue
+                chunk_data = _slice_by_slot_dim(kv_at_slots, start_idx, end_idx)
+                md5_hash.update(_compute_tensor_checksum(chunk_data).encode())
+            chunk_checksums_list.append(md5_hash.hexdigest())
+        return {
+            "chunk_checksums": chunk_checksums_list,
+            "chunk_size": chunk_size,
+            "num_chunks": num_chunks,
+        }
+
+
+@router.delete("/cache/clear")
+async def clear(
+    request: Request,
+    locations: Annotated[Optional[List[str]], Query()] = None,
+    request_configs: Optional[dict] = None,
+):
+    """Clear cached data from the LMCache engine.
+
+    This endpoint provides a way to clear cached KV (Key-Value) data from the
+    LMCache engine. It can clear all cached data or selectively clear data
+    from specific storage locations.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+        locations (Optional[List[str]], optional): List of storage backend locations
+            to clear cache from. If None, clears from all available locations.
+            Common values include ["LocalCPUBackend", "LocalDiskBackend"].
+            Defaults to None.
+        request_configs (Optional[dict], optional): Additional configuration
+            parameters for the clear operation. Currently unused but reserved
+            for future extensions. Defaults to None.
+
+    Returns:
+        PlainTextResponse: A plain text response
+
+    Example:
+        Clear all cached data:
+        ```bash
+        curl -X DELETE "http://localhost:8000/cache/clear"
+        # Response: {"status": "success", "num_removed": 10,
+        #           "locations": null, "request_configs": null}
+        ```
+
+        Clear cache from specific locations:
+        ```bash
+        curl -X DELETE "http://localhost:8000/cache/clear?locations=LocalCPUBackend&locations=LocalDiskBackend"
+        # Response: {"status": "success", "num_removed": 5,
+        #           "locations": ["LocalCPUBackend", "LocalDiskBackend"],
+        #           "request_configs": null}
+        ```
+    """
+    try:
+        lmcache_engine, error_response = _check_lmcache_engine(request)
+        if error_response:
+            return error_response
+
+        assert lmcache_engine is not None
+        num_removed = lmcache_engine.clear(  # type: ignore[attr-defined]
+            locations=locations, request_configs=request_configs
+        )
+        success_info = {
+            "status": "success",
+            "num_removed": num_removed,
+        }
+        return PlainTextResponse(
+            content=json.dumps(success_info, indent=2),
+            media_type="application/json",
+        )
+    except Exception as e:
+        error_info = {"error": "Failed to clear cache", "message": str(e)}
+        return _create_error_response(error_info, 500)
+
+
+def _process_tokens_request(
+    request: Request,
+    tokens_mock: Optional[str],
+) -> Tuple[Optional[object], Optional[List[int]], Optional[PlainTextResponse]]:
+    """Process tokens request and validate parameters.
+
+    Args:
+        request: FastAPI request object
+        tokens_mock: Mock token range specification
+
+    Returns:
+        Tuple of (lmcache_engine, tokens, error_response).
+        If error_response is not None, the other values will be None.
+    """
+    lmcache_engine, error_response = _check_lmcache_engine(request)
+    if error_response:
+        return None, None, error_response
+
+    tokens, error_info = _parse_tokens_from_params(tokens_mock)
+    if error_info:
+        status_code = 400 if error_info["error"] != "File not found" else 404
+        return None, None, _create_error_response(error_info, status_code)
+
+    return lmcache_engine, tokens, None
+
+
+def _execute_cache_operation(
+    operation_name: str,
+    operation_func: Callable,
+    lmcache_engine: object,
+    tokens: List[int],
+) -> PlainTextResponse:
+    """Execute a cache operation and return standardized response.
+
+    Args:
+        operation_name: Name of the operation for error messages
+        operation_func: Function to execute the operation
+        lmcache_engine: LMCache engine instance
+        tokens: List of token IDs
+
+    Returns:
+        PlainTextResponse with operation result
+    """
+    try:
+        result = operation_func(lmcache_engine, tokens)
+        success_info = {
+            "status": "success",
+            "num_tokens": len(tokens),
+        }
+        if result is not None:
+            success_info.update(result)
+        return PlainTextResponse(
+            content=json.dumps(success_info, indent=2),
+            media_type="application/json",
+        )
+    except Exception as e:
+        # Log the full traceback for debugging
+        tb_str = traceback.format_exc()
+        logger.error("Failed to %s: %s\n%s", operation_name, e, tb_str)
+
+        # Include more detailed error info in response
+        error_message = str(e) if str(e) else f"Exception type: {type(e).__name__}"
+        error_info = {
+            "error": f"Failed to {operation_name}",
+            "message": error_message,
+            "exception_type": type(e).__name__,
+        }
+        return _create_error_response(error_info, 500)
+
+
+@router.post("/cache/store")
+async def store(
+    request: Request,
+    tokens_mock: Optional[str] = None,
+):
+    """Store KV cache data into the LMCache engine.
+
+    This endpoint provides a way to store KV cache data by generating mock tokens.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+        tokens_mock (Optional[str], optional): Two comma-separated numbers specifying
+            the start and end of a token range. Example: "0,100" generates tokens
+            from 0 to 99. Defaults to None.
+
+    Returns:
+        PlainTextResponse: A plain text response with operation status
+
+    Example:
+        Store with mock tokens:
+        ```bash
+        curl -X POST "http://localhost:8000/cache/store?tokens_mock=0,100"
+        # Response: {"status": "success", "num_tokens": 100}
+        ```
+    """
+    lmcache_engine, tokens, error_response = _process_tokens_request(
+        request, tokens_mock
+    )
+    if error_response:
+        return error_response
+
+    assert tokens is not None
+    assert lmcache_engine is not None
+
+    def _store_operation(engine, token_list):
+        # Get kvcaches and device using the shared function
+        kvcaches, device = _get_kvcaches_and_device(engine)
+
+        # Create slot mapping for the tokens
+        slot_mapping = torch.arange(len(token_list), dtype=torch.long, device=device)
+
+        logger.debug(
+            "Storing %d tokens with slot_mapping on device %s",
+            len(token_list),
+            device,
+        )
+
+        engine.store(
+            req_id="cache_api_store",
+            tokens=token_list,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches,
+        )
+        return None
+
+    return _execute_cache_operation(
+        "store cache", _store_operation, lmcache_engine, tokens
+    )
+
+
+@router.post("/cache/retrieve")
+async def retrieve(
+    request: Request,
+    tokens_mock: Optional[str] = None,
+):
+    """Retrieve KV cache data from the LMCache engine.
+
+    This endpoint provides a way to retrieve KV cache data by generating mock tokens.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+        tokens_mock (Optional[str], optional): Two comma-separated numbers specifying
+            the start and end of a token range. Example: "0,100" generates tokens
+            from 0 to 99. Defaults to None.
+
+    Returns:
+        PlainTextResponse: A plain text response with operation status
+
+    Example:
+        Retrieve with mock tokens:
+        ```bash
+        curl -X POST "http://localhost:8000/cache/retrieve?tokens_mock=0,100"
+        # Response: {"status": "success", "num_tokens": 100, "num_retrieved": 80}
+        ```
+    """
+    lmcache_engine, tokens, error_response = _process_tokens_request(
+        request, tokens_mock
+    )
+    if error_response:
+        return error_response
+
+    assert tokens is not None
+    assert lmcache_engine is not None
+
+    def _retrieve_operation(engine, token_list):
+        # Get kvcaches and device using the shared function
+        kvcaches, device = _get_kvcaches_and_device(engine)
+
+        # Create slot_mapping for retrieve operation
+        slot_mapping = torch.arange(len(token_list), dtype=torch.long, device=device)
+
+        logger.debug(
+            "Retrieving %d tokens with slot_mapping on device %s",
+            len(token_list),
+            device,
+        )
+
+        ret_mask = engine.retrieve(
+            req_id="cache_api_retrieve",
+            tokens=token_list,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches,
+        )
+        num_retrieved = int(ret_mask.sum().item())
+        return {"num_retrieved": num_retrieved}
+
+    return _execute_cache_operation(
+        "retrieve cache", _retrieve_operation, lmcache_engine, tokens
+    )
+
+
+@router.get("/cache/kvcache/check")
+async def kvcache_check(
+    request: Request,
+    slot_mapping: Optional[str] = None,
+    chunk_size: Optional[int] = None,
+    layerwise: bool = False,
+):
+    """Compute checksum for kvcaches at specified slot_mapping positions.
+
+    This endpoint is used to verify that stored and retrieved kvcaches are identical.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+        slot_mapping (Optional[str], optional): Slot indices in comma-separated format,
+            supports single numbers and range expressions.
+            Examples: "0,1,2,3", "1,2,3,[9,12],17,19". Defaults to None.
+        chunk_size (Optional[int], optional): Chunk size for computing checksums.
+            Each chunk contains `chunk_size` slots. Required parameter.
+        layerwise (bool, optional): If True, output per-layer checksums for each chunk.
+            If False (default), output one checksum per chunk (all layers combined).
+
+    Returns:
+        PlainTextResponse: A JSON response containing checksums.
+
+    Example:
+        ```bash
+        # layerwise=false (default): one checksum per chunk (all layers combined)
+        curl -X GET "http://localhost:8000/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"
+        # Response: {
+        #   "status": "success",
+        #   "slot_mapping_ranges": [[0, 3]],
+        #   "chunk_size": 2,
+        #   "num_chunks": 2,
+        #   "chunk_checksums": ["checksum_chunk0", "checksum_chunk1"],
+        #   "layerwise": false
+        # }
+
+        # layerwise=true: per-layer checksums for each chunk
+        curl -X GET "http://localhost:8000/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2&layerwise=true"
+        # Response: {
+        #   "status": "success",
+        #   "slot_mapping_ranges": [[0, 3]],
+        #   "chunk_size": 2,
+        #   "num_chunks": 2,
+        #   "chunk_checksums": {
+        #       "layer_0": ["checksum_chunk0", "checksum_chunk1"],
+        #       "layer_1": ["checksum_chunk0", "checksum_chunk1"],
+        #   },
+        #   "layerwise": true
+        # }
+        ```
+    """
+    try:
+        lmcache_adapter = request.app.state.lmcache_adapter
+        if not lmcache_adapter:
+            return _create_error_response(
+                {
+                    "error": "LMCache adapter unavailable",
+                    "message": "LMCache adapter not configured.",
+                },
+                503,
+            )
+
+        if not slot_mapping:
+            return _create_error_response(
+                {
+                    "error": "Missing parameters",
+                    "message": "slot_mapping parameter is required",
+                },
+                400,
+            )
+
+        # Parse slot_mapping from mixed format string
+        # (supports single numbers and ranges)
+        slot_indices, error_info = parse_mixed_slot_mapping(slot_mapping)
+        if error_info:
+            return _create_error_response(error_info, 400)
+
+        # slot_indices is guaranteed to be non-None when error_info is None
+        assert slot_indices is not None
+
+        # Validate slot indices are within valid range
+        if lmcache_adapter.kv_caches:
+            # Get the first kv_tensor to check dimensions
+            first_kv_tensor = next(iter(lmcache_adapter.kv_caches.values()))
+            # Calculate total slots: num_blocks * block_size
+            # For different formats:
+            # - MHA (5D): [2, num_blocks, block_size, num_heads, head_size]
+            # - MLA (3D): [num_blocks, block_size, head_size]
+            # - 4D: [num_blocks, block_size, num_heads, head_size]
+            ndim = first_kv_tensor.ndim
+            if ndim == 5:
+                # MHA: [2, num_blocks, block_size, num_heads, head_size]
+                total_slots = first_kv_tensor.shape[1] * first_kv_tensor.shape[2]
+            elif ndim == 3:
+                # MLA: [num_blocks, block_size, head_size]
+                total_slots = first_kv_tensor.shape[0] * first_kv_tensor.shape[1]
+            elif ndim == 4:
+                # 4D: [num_blocks, block_size, num_heads, head_size]
+                total_slots = first_kv_tensor.shape[0] * first_kv_tensor.shape[1]
+            else:
+                # Fallback
+                reshaped = first_kv_tensor.view(-1, *first_kv_tensor.shape[2:])
+                total_slots = reshaped.shape[0]
+
+            # Check each slot index
+            invalid_indices = []
+            for slot_idx in slot_indices:
+                if slot_idx < 0 or slot_idx >= total_slots:
+                    invalid_indices.append(slot_idx)
+
+            if invalid_indices:
+                return _create_error_response(
+                    {
+                        "error": "Invalid slot indices",
+                        "message": (
+                            "Slot indices out of bounds: %s. Valid range: 0 to %d"
+                        )
+                        % (invalid_indices, total_slots - 1),
+                    },
+                    400,
+                )
+        else:
+            return _create_error_response(
+                {
+                    "error": "kv_caches not available",
+                    "message": "kv_caches is empty or not initialized",
+                },
+                404,
+            )
+
+        # Validate chunk_size if provided
+        if chunk_size is not None and chunk_size <= 0:
+            return _create_error_response(
+                {
+                    "error": "Invalid chunk_size",
+                    "message": "chunk_size must be a positive integer",
+                },
+                400,
+            )
+
+        # Get checksums from the adapter asynchronously to not block the loop
+        loop = asyncio.get_running_loop()
+        checksums_result = await loop.run_in_executor(
+            None,  # Uses default ThreadPoolExecutor
+            lambda: compute_kvcache_checksums(
+                lmcache_adapter, slot_indices, chunk_size, layerwise
+            ),
+        )
+
+        if checksums_result is None:
+            return _create_error_response(
+                {
+                    "error": "Failed to compute checksums",
+                    "message": "kv_caches not available or empty",
+                },
+                500,
+            )
+
+        # Compute slot mapping ranges using compress_slot_mapping
+        slot_mapping_ranges = compress_slot_mapping(slot_indices)
+
+        response_data: dict[str, Any] = {
+            "status": "success",
+            "slot_mapping_ranges": slot_mapping_ranges,
+        }
+
+        # Include chunk checksums
+        response_data["chunk_size"] = checksums_result.get("chunk_size")
+        response_data["num_chunks"] = checksums_result.get("num_chunks")
+        response_data["chunk_checksums"] = checksums_result.get("chunk_checksums")
+        response_data["layerwise"] = layerwise
+
+        return PlainTextResponse(
+            content=json.dumps(response_data, indent=2),
+            media_type="application/json",
+        )
+
+    except Exception as e:
+        logger.error("Failed to compute kvcache checksums: %s", str(e))
+        return _create_error_response(
+            {"error": "Failed to compute checksums", "message": str(e)},
+            500,
+        )
+
+
+@router.post("/cache/kvcache/record_slot")
+async def kvcache_record_slot(
+    request: Request,
+    enabled: Optional[str] = None,
+):
+    """Enable or disable KVCache Check slot_mapping logging.
+
+    This endpoint controls whether the KVCache Check logs (slot_mapping info)
+    are printed when store/retrieve operations are performed.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+        enabled (Optional[str], optional): "true" to enable logging, "false" to
+            disable. Defaults to None.
+
+    Returns:
+        PlainTextResponse: A JSON response containing the current logging status.
+
+    Example:
+        ```bash
+        # Enable logging
+        curl -X POST "http://localhost:8000/cache/kvcache/record_slot?enabled=true"
+
+        # Disable logging
+        curl -X POST "http://localhost:8000/cache/kvcache/record_slot?enabled=false"
+
+        # Check current status
+        curl -X POST "http://localhost:8000/cache/kvcache/record_slot"
+        ```
+    """
+    try:
+        lmcache_adapter = request.app.state.lmcache_adapter
+        if not lmcache_adapter:
+            return _create_error_response(
+                {
+                    "error": "LMCache adapter unavailable",
+                    "message": "LMCache adapter not configured.",
+                },
+                503,
+            )
+
+        # Get current status from lmcache_engine
+        lmcache_engine = lmcache_adapter.lmcache_engine
+        current_status = getattr(lmcache_engine, "kvcache_check_log_enabled", False)
+
+        # Update status if enabled parameter is provided
+        if enabled is not None:
+            enabled_lower = enabled.lower()
+            if enabled_lower == "true":
+                lmcache_engine.kvcache_check_log_enabled = True
+                current_status = True
+                logger.info("KVCache Check logging enabled")
+            elif enabled_lower == "false":
+                lmcache_engine.kvcache_check_log_enabled = False
+                current_status = False
+                logger.info("KVCache Check logging disabled")
+            else:
+                return _create_error_response(
+                    {
+                        "error": "Invalid parameter",
+                        "message": "enabled must be 'true' or 'false'",
+                    },
+                    400,
+                )
+
+        response_data = {
+            "status": "success",
+            "kvcache_check_log_enabled": current_status,
+        }
+
+        return PlainTextResponse(
+            content=json.dumps(response_data, indent=2),
+            media_type="application/json",
+        )
+
+    except Exception as e:
+        logger.error("Failed to set kvcache record slot status: %s", str(e))
+        return _create_error_response(
+            {"error": "Failed to set record slot status", "message": str(e)},
+            500,
+        )
+
+
+@router.get("/cache/kvcache/info")
+async def kvcache_info(request: Request):
+    """Get information about the current kvcaches.
+
+    Returns information about the kvcaches structure including layer names,
+    shapes, and device information.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+
+    Returns:
+        PlainTextResponse: A JSON response containing kvcache information.
+    """
+    try:
+        lmcache_adapter = request.app.state.lmcache_adapter
+        if not lmcache_adapter:
+            return _create_error_response(
+                {
+                    "error": "LMCache adapter unavailable",
+                    "message": "LMCache adapter not configured.",
+                },
+                503,
+            )
+
+        kv_caches = getattr(lmcache_adapter, "kvcaches", None)
+        if not kv_caches:
+            return _create_error_response(
+                {
+                    "error": "kv_caches not available",
+                    "message": "kv_caches is empty or not initialized",
+                },
+                404,
+            )
+
+        layers_info: dict = {}
+        for layer_name, kv_tensor in kv_caches.items():
+            layers_info[layer_name] = {
+                "shape": list(kv_tensor.shape),
+                "dtype": str(kv_tensor.dtype),
+                "device": str(kv_tensor.device),
+            }
+
+        info = {
+            "status": "success",
+            "num_layers": len(kv_caches),
+            "layers": layers_info,
+        }
+
+        return PlainTextResponse(
+            content=json.dumps(info, indent=2),
+            media_type="application/json",
+        )
+
+    except Exception as e:
+        logger.error("Failed to get kvcache info: %s", str(e))
+        return _create_error_response(
+            {"error": "Failed to get kvcache info", "message": str(e)},
+            500,
+        )
diff --git a/lmcache/v1/internal_api_server/vllm/chunk_statistics_api.py b/lmcache/v1/internal_api_server/vllm/chunk_statistics_api.py
new file mode 100644
index 0000000..7ce49b8
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/chunk_statistics_api.py
@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Tuple, Union
+import json
+import time
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+# First Party
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.chunk_statistics_lookup_client import (
+    ChunkStatisticsLookupClient,
+)
+
+router = APIRouter()
+
+
+def _create_json_response(data: dict, status_code: int = 200) -> PlainTextResponse:
+    return PlainTextResponse(
+        content=json.dumps(data, indent=2),
+        media_type="application/json",
+        status_code=status_code,
+    )
+
+
+def _get_lookup_client(
+    request: Request,
+) -> Tuple[
+    Optional[Union[LookupClientInterface, ChunkStatisticsLookupClient]],
+    Optional[PlainTextResponse],
+]:
+    lookup_client = getattr(request.app.state.lmcache_adapter, "lookup_client", None)
+    if not lookup_client:
+        return None, _create_json_response(
+            {"error": "API unavailable", "message": "Lookup client not configured."},
+            status_code=503,
+        )
+    return lookup_client, None
+
+
+def _get_statistics_client(
+    request: Request,
+) -> Tuple[Optional[ChunkStatisticsLookupClient], Optional[PlainTextResponse]]:
+    lookup_client, error_response = _get_lookup_client(request)
+    if error_response:
+        return None, error_response
+    if not isinstance(lookup_client, ChunkStatisticsLookupClient):
+        return None, _create_json_response(
+            {
+                "error": "Not available",
+                "message": "Client does not support statistics.",
+            },
+            status_code=400,
+        )
+    return lookup_client, None
+
+
+def _handle_exception(operation: str, error: Exception) -> PlainTextResponse:
+    return _create_json_response(
+        {"error": f"Failed to {operation}", "message": str(error)}, status_code=500
+    )
+
+
+@router.post("/chunk_statistics/start")
+async def start_chunk_statistics(request: Request):
+    try:
+        lookup_client, error_response = _get_lookup_client(request)
+        if error_response:
+            return error_response
+        assert lookup_client is not None
+        if isinstance(lookup_client, ChunkStatisticsLookupClient):
+            lookup_client.start_statistics()
+            return _create_json_response({"status": "success", "message": "Started"})
+        return _create_json_response(
+            {
+                "error": "Not available",
+                "message": "Client does not support statistics.",
+            },
+            status_code=400,
+        )
+    except Exception as e:
+        return _handle_exception("start", e)
+
+
+@router.post("/chunk_statistics/stop")
+async def stop_chunk_statistics(request: Request):
+    try:
+        stats_client, error_response = _get_statistics_client(request)
+        if error_response:
+            return error_response
+        assert stats_client is not None
+        stats_client.stop_statistics()
+        return _create_json_response({"status": "success", "message": "Stopped"})
+    except Exception as e:
+        return _handle_exception("stop", e)
+
+
+@router.post("/chunk_statistics/reset")
+async def reset_chunk_statistics(request: Request):
+    try:
+        stats_client, error_response = _get_statistics_client(request)
+        if error_response:
+            return error_response
+        assert stats_client is not None
+        stats_client.reset_statistics()
+        return _create_json_response({"status": "success", "message": "Reset"})
+    except Exception as e:
+        return _handle_exception("reset", e)
+
+
+@router.get("/chunk_statistics/status")
+async def get_chunk_statistics_status(request: Request):
+    try:
+        stats_client, error_response = _get_statistics_client(request)
+        if error_response:
+            return error_response
+        assert stats_client is not None
+        config = request.app.state.lmcache_adapter.config
+        stats = stats_client.get_statistics()
+        stats.update(
+            {
+                "timestamp": time.time(),
+                "auto_exit_enabled": (
+                    config.chunk_statistics_auto_exit_timeout_hours > 0.0
+                    or config.chunk_statistics_auto_exit_target_unique_chunks
+                    is not None
+                ),
+                "auto_exit_timeout_hours": (
+                    config.chunk_statistics_auto_exit_timeout_hours
+                ),
+                "auto_exit_target_unique_chunks": (
+                    config.chunk_statistics_auto_exit_target_unique_chunks
+                ),
+            }
+        )
+        return _create_json_response(stats)
+    except Exception as e:
+        return _handle_exception("get status", e)
diff --git a/lmcache/v1/internal_api_server/vllm/conf_api.py b/lmcache/v1/internal_api_server/vllm/conf_api.py
new file mode 100644
index 0000000..a402ae3
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/conf_api.py
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Dict, Optional, Union
+import json
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import JSONResponse, PlainTextResponse
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import _CONFIG_DEFINITIONS, LMCacheEngineConfig
+from lmcache.v1.config_base import validate_and_set_config_value
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+
+def _is_mutable_config(key: str) -> bool:
+    """Check if a config key is mutable at runtime.
+
+    NOTE: This is currently experimental. All configs default to
+    mutable=True unless explicitly set to False. Once the feature
+    is stabilized, the default will be changed to mutable=False.
+    """
+    return _CONFIG_DEFINITIONS.get(key, {}).get("mutable", True)
+
+
+def _get_config_dict(
+    config: LMCacheEngineConfig,
+    keys: Union[list[str], Optional[dict[str, dict[str, Any]]]] = None,
+) -> Dict[str, Any]:
+    """Get the config dict filtered by keys"""
+    if keys is None:
+        keys = _CONFIG_DEFINITIONS
+    return {key: getattr(config, key) for key in keys if hasattr(config, key)}
+
+
+@router.get("/conf")
+async def get_config(request: Request, names: Optional[str] = None):
+    config = request.app.state.lmcache_adapter.config
+    # Parse query parameter names (comma-separated list of config names)
+    keys = names.split(",") if names else None
+    config_dict = _get_config_dict(config, keys)
+    return PlainTextResponse(
+        content=json.dumps(config_dict, indent=2), media_type="text/plain"
+    )
+
+
+@router.get("/meta")
+async def get_metadata(request: Request, names: Optional[str] = None):
+    """
+    Get metadata of the cache engine
+    """
+    metadata = request.app.state.lmcache_adapter.lmcache_engine_metadata
+
+    if names:
+        attr_list = names.split(",")
+        metadata_dict = {}
+        for attr in attr_list:
+            if (
+                hasattr(metadata, attr)
+                and not attr.startswith("__")
+                and not callable(getattr(metadata, attr))
+            ):
+                value = getattr(metadata, attr)
+                if isinstance(value, (torch.dtype, torch.Size)):
+                    value = str(value)
+                metadata_dict[attr] = value
+    else:
+        metadata_dict = {
+            attr: getattr(metadata, attr)
+            for attr in dir(metadata)
+            if not attr.startswith("__") and not callable(getattr(metadata, attr))
+        }
+        for key, value in metadata_dict.items():
+            if isinstance(value, (torch.dtype, torch.Size)):
+                metadata_dict[key] = str(value)
+
+    return PlainTextResponse(
+        content=json.dumps(metadata_dict, indent=2, default=str),
+        media_type="text/plain",
+    )
+
+
+@router.post("/conf")
+async def set_config(request: Request):
+    """Set config values dynamically.
+
+    NOTE: Currently experimental — all configs are mutable at runtime
+    by default unless explicitly set "mutable": False in
+    _CONFIG_DEFINITIONS. The default will change to immutable once
+    the feature is stabilized.
+
+    Request body should be JSON with config name-value pairs:
+        {"min_retrieve_tokens": 512, "save_decode_cache": true}
+
+    Returns:
+        PlainTextResponse: JSON response with updated config values
+    """
+    config = request.app.state.lmcache_adapter.config
+
+    try:
+        body = await request.json()
+    except Exception as e:
+        return JSONResponse(
+            content={"error": "Invalid JSON body", "message": str(e)},
+            status_code=400,
+        )
+
+    if not isinstance(body, dict):
+        return JSONResponse(
+            content={"error": "Request body must be a JSON object"},
+            status_code=400,
+        )
+
+    updated: Dict[str, Any] = {}
+    errors: Dict[str, str] = {}
+
+    for key, value in body.items():
+        if not _is_mutable_config(key):
+            errors[key] = "Config is not mutable at runtime"
+            continue
+
+        if key not in _CONFIG_DEFINITIONS:
+            errors[key] = "Unknown config"
+            continue
+
+        # Use shared validation and setting function
+        if validate_and_set_config_value(config, key, value):
+            updated[key] = getattr(config, key)
+            logger.info("Config %s updated to %s", key, updated[key])
+        else:
+            errors[key] = "Failed to set config value"
+
+    result: Dict[str, Any] = {"updated": updated}
+    if errors:
+        result["errors"] = errors
+
+    status_code = 400 if errors and not updated else 200
+    return JSONResponse(
+        content=result,
+        status_code=status_code,
+    )
diff --git a/lmcache/v1/internal_api_server/vllm/freeze_api.py b/lmcache/v1/internal_api_server/vllm/freeze_api.py
new file mode 100644
index 0000000..f3be386
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/freeze_api.py
@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import json
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+@router.put("/freeze/enable")
+async def enable_freeze(request: Request):
+    """
+    Enable freeze mode for the LMCache engine.
+
+    When freeze mode is enabled:
+    - All store operations will be skipped (no new data stored)
+    - Only local_cpu backend will be used for retrieval
+    - No admit/evict messages will be generated
+    This protects the local_cpu hot cache from changes.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+
+    Returns:
+        PlainTextResponse: A JSON response indicating the operation status.
+
+    Example:
+        ```bash
+        curl -X PUT "http://localhost:8000/freeze/enable"
+        # Response: {"status": "success", "freeze": true}
+        ```
+    """
+    try:
+        lmcache_adapter = request.app.state.lmcache_adapter
+        lmcache_engine = getattr(lmcache_adapter, "lmcache_engine", None)
+        if not lmcache_engine:
+            error_info = {
+                "error": "/freeze/enable API is unavailable",
+                "message": "LMCache engine not configured.",
+            }
+            return PlainTextResponse(
+                content=json.dumps(error_info, indent=2),
+                media_type="application/json",
+                status_code=503,  # Service Unavailable
+            )
+
+        lmcache_engine.freeze(True)
+        success_info = {
+            "status": "success",
+            "freeze": True,
+            "message": "Freeze mode enabled successfully",
+        }
+        return PlainTextResponse(
+            content=json.dumps(success_info, indent=2),
+            media_type="application/json",
+        )
+    except Exception as e:
+        error_msg = "Failed to enable freeze mode"
+        error_info = {"error": error_msg, "message": str(e)}
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=500,
+        )
+
+
+@router.put("/freeze/disable")
+async def disable_freeze(request: Request):
+    """
+    Disable freeze mode for the LMCache engine.
+
+    When freeze mode is disabled, store operations will proceed normally.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+
+    Returns:
+        PlainTextResponse: A JSON response indicating the operation status.
+
+    Example:
+        ```bash
+        curl -X PUT "http://localhost:8000/freeze/disable"
+        # Response: {"status": "success", "freeze": false}
+        ```
+    """
+    try:
+        lmcache_adapter = request.app.state.lmcache_adapter
+        lmcache_engine = getattr(lmcache_adapter, "lmcache_engine", None)
+        if not lmcache_engine:
+            error_info = {
+                "error": "/freeze/disable API is unavailable",
+                "message": "LMCache engine not configured.",
+            }
+            return PlainTextResponse(
+                content=json.dumps(error_info, indent=2),
+                media_type="application/json",
+                status_code=503,  # Service Unavailable
+            )
+
+        lmcache_engine.freeze(False)
+        success_info = {
+            "status": "success",
+            "freeze": False,
+            "message": "Freeze mode disabled successfully",
+        }
+        return PlainTextResponse(
+            content=json.dumps(success_info, indent=2),
+            media_type="application/json",
+        )
+    except Exception as e:
+        error_msg = "Failed to disable freeze mode"
+        error_info = {"error": error_msg, "message": str(e)}
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=500,
+        )
+
+
+@router.get("/freeze/status")
+async def get_freeze_status(request: Request):
+    """
+    Get the current freeze mode status of the LMCache engine.
+
+    Args:
+        request (Request): The FastAPI request object containing application state.
+
+    Returns:
+        PlainTextResponse: JSON response with current freeze mode status.
+
+    Example:
+        ```bash
+        curl -X GET "http://localhost:8000/freeze/status"
+        # Response: {"status": "success", "freeze": true}
+        ```
+    """
+    try:
+        lmcache_adapter = request.app.state.lmcache_adapter
+        lmcache_engine = getattr(lmcache_adapter, "lmcache_engine", None)
+        if not lmcache_engine:
+            error_info = {
+                "error": "/freeze/status API is unavailable",
+                "message": "LMCache engine not configured.",
+            }
+            return PlainTextResponse(
+                content=json.dumps(error_info, indent=2),
+                media_type="application/json",
+                status_code=503,  # Service Unavailable
+            )
+
+        freeze_mode = lmcache_engine.is_frozen()
+        mode_str = "enabled" if freeze_mode else "disabled"
+        success_info = {
+            "status": "success",
+            "freeze": freeze_mode,
+            "message": "Freeze mode is " + mode_str,
+        }
+        return PlainTextResponse(
+            content=json.dumps(success_info, indent=2),
+            media_type="application/json",
+        )
+    except Exception as e:
+        error_msg = "Failed to get freeze mode status"
+        error_info = {"error": error_msg, "message": str(e)}
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=500,
+        )
diff --git a/lmcache/v1/internal_api_server/vllm/hot_cache_api.py b/lmcache/v1/internal_api_server/vllm/hot_cache_api.py
new file mode 100644
index 0000000..df8e328
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/hot_cache_api.py
@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import json
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+def _get_engine(request: Request):
+    """
+    Extract the LMCache engine from the request state.
+
+    Returns:
+        A tuple of (engine, error_response). If engine is None,
+        error_response contains a PlainTextResponse to return.
+    """
+    adapter = request.app.state.lmcache_adapter
+    engine = getattr(adapter, "lmcache_engine", None)
+    if not engine:
+        error_info = {
+            "error": "hot_cache API is unavailable",
+            "message": "LMCache engine not configured.",
+        }
+        return None, PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=503,
+        )
+    return engine, None
+
+
+@router.put("/hot_cache/enable")
+async def enable_hot_cache(request: Request):
+    """
+    Enable hot cache for the LocalCPUBackend.
+
+    When hot cache is enabled, frequently accessed KV cache
+    data will be kept in CPU memory for faster retrieval.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        PlainTextResponse: JSON response with operation status.
+
+    Example:
+        ```bash
+        curl -X PUT "http://localhost:8000/hot_cache/enable"
+        # Response: {"status": "success", "hot_cache": true}
+        ```
+    """
+    try:
+        engine, err = _get_engine(request)
+        if err:
+            return err
+
+        engine.set_hot_cache(True)
+        return PlainTextResponse(
+            content=json.dumps(
+                {
+                    "status": "success",
+                    "hot_cache": True,
+                    "message": "Hot cache enabled successfully",
+                },
+                indent=2,
+            ),
+            media_type="application/json",
+        )
+    except Exception as e:
+        return PlainTextResponse(
+            content=json.dumps(
+                {
+                    "error": "Failed to enable hot cache",
+                    "message": str(e),
+                },
+                indent=2,
+            ),
+            media_type="application/json",
+            status_code=500,
+        )
+
+
+@router.put("/hot_cache/disable")
+async def disable_hot_cache(request: Request):
+    """
+    Disable hot cache for the LocalCPUBackend.
+
+    When hot cache is disabled, existing hot cache entries
+    will be cleared and no new data will be written.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        PlainTextResponse: JSON response with operation status.
+
+    Example:
+        ```bash
+        curl -X PUT "http://localhost:8000/hot_cache/disable"
+        # Response: {"status": "success", "hot_cache": false}
+        ```
+    """
+    try:
+        engine, err = _get_engine(request)
+        if err:
+            return err
+
+        engine.set_hot_cache(False)
+        return PlainTextResponse(
+            content=json.dumps(
+                {
+                    "status": "success",
+                    "hot_cache": False,
+                    "message": ("Hot cache disabled successfully"),
+                },
+                indent=2,
+            ),
+            media_type="application/json",
+        )
+    except Exception as e:
+        return PlainTextResponse(
+            content=json.dumps(
+                {
+                    "error": "Failed to disable hot cache",
+                    "message": str(e),
+                },
+                indent=2,
+            ),
+            media_type="application/json",
+            status_code=500,
+        )
+
+
+@router.get("/hot_cache/status")
+async def get_hot_cache_status(request: Request):
+    """
+    Get the current hot cache status of LocalCPUBackend.
+
+    Args:
+        request: The FastAPI request object.
+
+    Returns:
+        PlainTextResponse: JSON response with hot cache status.
+
+    Example:
+        ```bash
+        curl -X GET "http://localhost:8000/hot_cache/status"
+        # Response: {"status": "success", "hot_cache": true}
+        ```
+    """
+    try:
+        engine, err = _get_engine(request)
+        if err:
+            return err
+
+        enabled = engine.is_hot_cache_enabled()
+        mode_str = "enabled" if enabled else "disabled"
+        return PlainTextResponse(
+            content=json.dumps(
+                {
+                    "status": "success",
+                    "hot_cache": enabled,
+                    "message": "Hot cache is " + mode_str,
+                },
+                indent=2,
+            ),
+            media_type="application/json",
+        )
+    except Exception as e:
+        return PlainTextResponse(
+            content=json.dumps(
+                {
+                    "error": "Failed to get hot cache status",
+                    "message": str(e),
+                },
+                indent=2,
+            ),
+            media_type="application/json",
+            status_code=500,
+        )
diff --git a/lmcache/v1/internal_api_server/vllm/inference_api.py b/lmcache/v1/internal_api_server/vllm/inference_api.py
new file mode 100644
index 0000000..942744a
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/inference_api.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+import json
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+@router.get("/inference_info")
+async def get_inference_info(request: Request, format: Optional[str] = None):
+    """
+    Get inference information including vLLM config and LMCache details
+
+    Args:
+        format: Optional format parameter (currently unused, for future extension)
+
+    Returns:
+        PlainTextResponse: JSON string containing inference information
+    """
+    lmcache_adapter = request.app.state.lmcache_adapter
+
+    try:
+        inference_info = lmcache_adapter.get_inference_info()
+        return PlainTextResponse(
+            content=json.dumps(inference_info, indent=2, default=str),
+            media_type="application/json",
+        )
+    except Exception as e:
+        error_info = {"error": "Failed to get inference info", "message": str(e)}
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=500,
+        )
+
+
+@router.get("/inference_version")
+async def get_inference_version(request: Request):
+    """
+    Get vLLM version information
+
+    Returns:
+        PlainTextResponse: vLLM version string
+    """
+    lmcache_adapter = request.app.state.lmcache_adapter
+
+    try:
+        version_info = lmcache_adapter.get_inference_version()
+        version_response = {"vllm_version": version_info}
+        return PlainTextResponse(
+            content=json.dumps(version_response, indent=2),
+            media_type="application/json",
+        )
+    except Exception as e:
+        error_info = {"error": "Failed to get inference version", "message": str(e)}
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=500,
+        )
diff --git a/lmcache/v1/internal_api_server/vllm/load_fs_chunks_api.py b/lmcache/v1/internal_api_server/vllm/load_fs_chunks_api.py
new file mode 100644
index 0000000..126157c
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/load_fs_chunks_api.py
@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict, List, Optional
+import asyncio
+import json
+
+# Third Party
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+
+class LoadFSChunksRequest(BaseModel):
+    """Request model for loading FS chunks."""
+
+    config_path: str
+    max_chunks: Optional[int] = None
+    max_failed_keys: int = 10
+
+
+class LoadFSChunksResponse(BaseModel):
+    """Response model for load-fs-chunks endpoint."""
+
+    status: str
+    loaded_chunks: int
+    total_files: int
+    failed_keys: List[str]
+    config_path: str
+
+
+class ErrorResponse(BaseModel):
+    """Error response model for load-fs-chunks endpoint."""
+
+    error: str
+    message: str
+    config_path: Optional[str] = None
+
+
+router = APIRouter()
+logger = init_logger(__name__)
+
+
+@router.post(
+    "/cache/load-fs-chunks",
+    summary="Load chunks from FSConnector into hot cache",
+    description="""
+    Load chunk files from FSConnector storage into LocalCPUBackend's hot cache.
+    """,
+    responses={
+        200: {
+            "model": LoadFSChunksResponse,
+            "description": "Chunks loaded successfully",
+        },
+        400: {"model": ErrorResponse, "description": "Invalid configuration file"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+        503: {"model": ErrorResponse, "description": "LMCache engine not configured"},
+    },
+    tags=["cache-management"],
+)
+async def load_fs_chunks(
+    request: Request,
+    request_body: LoadFSChunksRequest,
+):
+    """
+    Load chunk files from FSConnector into LocalCPUBackend hot cache.
+
+    This endpoint loads all chunk files from the specified FSConnector directory
+    into the LocalCPUBackend's hot cache by:
+    1. Loading configuration from the specified config file
+    2. Initializing RemoteBackend with FSConnector
+    3. Listing all chunk files in the FSConnector directory
+    4. Constructing CacheEngineKey from filenames
+    5. Loading MemoryObj from files and putting into hot cache
+
+    Args:
+        request: The FastAPI request object containing application state
+        request_body: Request body containing:
+            - config_path: Path to LMCache engine configuration file
+            - max_chunks: Optional limit on number of chunks to load
+            - max_failed_keys: Maximum failed keys to report (default: 10)
+
+    Returns:
+        PlainTextResponse: JSON response with loading statistics
+
+    Raises:
+        HTTPException: Various error conditions with appropriate status codes
+
+    Example Request:
+        ```bash
+        curl -X POST "http://localhost:8000/cache/load-fs-chunks" \
+             -H "Content-Type: application/json" \
+             -d '{
+                   "config_path": "/path/to/lmcache.yaml", 
+                   "max_chunks": 100,
+                   "max_failed_keys": 10
+                 }'
+        ```
+
+    Example Response (Success):
+        ```json
+        {
+          "status": "success",
+          "loaded_chunks": 95,
+          "total_files": 100,
+          "failed_keys": ["key1", "key2"],
+          "config_path": "/path/to/lmcache.yaml"
+        }
+        ```
+
+    Example Response (Error):
+        ```json
+        {
+          "error": "Failed to load chunks from FSConnector",
+          "message": "Configuration file not found",
+          "config_path": "/path/to/lmcache.yaml"
+        }
+        ```
+    """
+    lmcache_adapter = request.app.state.lmcache_adapter
+    lmcache_engine = getattr(lmcache_adapter, "lmcache_engine", None)
+
+    if not lmcache_engine:
+        error_info = {
+            "error": "/cache/load-fs-chunks API is unavailable",
+            "message": "LMCache engine not configured.",
+        }
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=503,
+        )
+
+    remote_backend = None
+    try:
+        config = await _load_config_from_file(request_body.config_path)
+        local_cpu_backend = lmcache_engine.storage_manager.allocator_backend
+
+        remote_backend = await _initialize_remote_backend(
+            config,
+            lmcache_engine.metadata,
+            local_cpu_backend,
+            lmcache_engine.storage_manager.loop,
+        )
+
+        result = await _load_chunks_from_fs_connector(
+            remote_backend,
+            local_cpu_backend,
+            request_body.max_chunks,
+            request_body.max_failed_keys,
+        )
+
+        success_info = {
+            "status": "success",
+            "loaded_chunks": result["loaded_chunks"],
+            "total_files": result["total_files"],
+            "failed_keys": result["failed_keys"],
+            "config_path": request_body.config_path,
+        }
+
+        return PlainTextResponse(
+            content=json.dumps(success_info, indent=2),
+            media_type="application/json",
+        )
+
+    except Exception as e:
+        if isinstance(e, HTTPException):
+            raise
+        logger.error("Unexpected error in load_fs_chunks: %s", e, exc_info=True)
+        error_info = {
+            "error": "Failed to load chunks from FSConnector",
+            "message": str(e),
+            "config_path": request_body.config_path,
+        }
+        return PlainTextResponse(
+            content=json.dumps(error_info, indent=2),
+            media_type="application/json",
+            status_code=500,
+        )
+    finally:
+        if remote_backend is not None:
+            remote_backend.close()
+
+
+async def _load_config_from_file(config_path: str) -> LMCacheEngineConfig:
+    """Load configuration from yaml file."""
+    try:
+        return LMCacheEngineConfig.from_file(config_path)
+    except Exception as e:
+        logger.error("Failed to load config from %s: %s", config_path, e)
+        raise HTTPException(
+            status_code=400, detail="Invalid configuration file: %s" % str(e)
+        ) from e
+
+
+async def _initialize_remote_backend(
+    config: LMCacheEngineConfig, metadata, local_cpu_backend, loop
+) -> RemoteBackend:
+    """Initialize RemoteBackend with FSConnector."""
+    try:
+        remote_backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+        remote_backend.init_connection()
+        return remote_backend
+    except Exception as e:
+        logger.error("Failed to initialize RemoteBackend: %s", e)
+        raise HTTPException(
+            status_code=500, detail="Failed to initialize RemoteBackend: %s" % str(e)
+        ) from e
+
+
+async def _load_chunks_from_fs_connector(
+    remote_backend: RemoteBackend,
+    local_cpu_backend,
+    max_chunks: Optional[int] = None,
+    max_failed_keys: int = 10,
+) -> Dict:
+    """Load chunks from FSConnector into LocalCPUBackend."""
+    connector = remote_backend.connection
+    if not connector:
+        raise HTTPException(status_code=500, detail="FSConnector not initialized")
+
+    try:
+        chunk_files = await connector.list()
+        total_files = len(chunk_files)
+
+        if max_chunks:
+            chunk_files = chunk_files[:max_chunks]
+
+        logger.info("Found %d chunk files to load", len(chunk_files))
+
+        loaded_chunks = 0
+        failed_keys: List[str] = []
+
+        # Use semaphore to control concurrency (max 10 concurrent tasks)
+        semaphore = asyncio.Semaphore(10)
+
+        async def process_chunk(chunk_filename: str) -> bool:
+            """
+            Process a single chunk file from FSConnector.
+
+            This function is called for each chunk file and performs:
+            - Transforms filename to CacheEngineKey format
+            - Loads MemoryObj data from remote backend
+            - Places chunk into local CPU backend hot cache
+            - Handles errors and tracks failed keys
+
+            Args:
+                chunk_filename: Name of the chunk file from FSConnector
+
+            Returns:
+                bool: True if chunk was successfully loaded, False otherwise
+
+            Note:
+                This function runs with semaphore control to limit concurrency
+                and ensure system stability during bulk loading operations.
+            """
+            async with semaphore:
+                key_str = chunk_filename.replace("-SEP-", "/")
+                try:
+                    key = CacheEngineKey.from_string(key_str)
+
+                    # Get data from remote backend
+                    memory_obj = await asyncio.get_event_loop().run_in_executor(
+                        None, remote_backend.get_blocking, key
+                    )
+
+                    if memory_obj is None:
+                        failed_keys.append(key_str)
+                        logger.warning("Failed to load chunk: %s", key_str)
+                        return False
+
+                    # Put into local cpu backend and immediately release reference
+                    local_cpu_backend.submit_put_task(key, memory_obj)
+                    memory_obj.ref_count_down()
+                    return True
+
+                except Exception as e:
+                    failed_keys.append(key_str)
+                    logger.warning("Error processing chunk %s: %s", key_str, e)
+                    return False
+
+        # Process all chunks concurrently
+        tasks = [process_chunk(chunk_filename) for chunk_filename in chunk_files]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Count successful loads
+        loaded_chunks = sum(1 for result in results if result is True)
+
+        if loaded_chunks > 0 and loaded_chunks % 100 == 0:
+            logger.info("Loaded %d chunks...", loaded_chunks)
+
+        logger.info(
+            "Successfully loaded %d chunks from %d files",
+            loaded_chunks,
+            total_files,
+        )
+
+        return {
+            "loaded_chunks": loaded_chunks,
+            "total_files": total_files,
+            "failed_keys": failed_keys[:max_failed_keys],
+        }
+
+    except Exception as e:
+        logger.error("Error in chunk loading process: %s", e)
+        raise HTTPException(
+            status_code=500, detail="Chunk loading failed: %s" % str(e)
+        ) from e
diff --git a/lmcache/v1/internal_api_server/vllm/lookup_api.py b/lmcache/v1/internal_api_server/vllm/lookup_api.py
new file mode 100644
index 0000000..bb898a2
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/lookup_api.py
@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import json
+
+# Third Party
+from fastapi import APIRouter
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+router = APIRouter()
+
+
+def _json_response(data: dict, status_code: int = 200) -> PlainTextResponse:
+    """Helper to create JSON response."""
+    return PlainTextResponse(
+        content=json.dumps(data, indent=2),
+        media_type="application/json",
+        status_code=status_code,
+    )
+
+
+def _get_role(adapter) -> str:
+    """Get the role from the manager's engine metadata.
+
+    Returns "scheduler", "worker", or "unknown".
+    """
+    metadata = getattr(adapter, "lmcache_engine_metadata", None)
+    if metadata is not None:
+        role = getattr(metadata, "role", None)
+        if role is not None:
+            return role
+    return "unknown"
+
+
+@router.get("/lookup/info")
+async def get_lookup_info(request: Request):
+    """
+    Get information about the current lookup client and server.
+
+    Example:
+        curl http://localhost:6999/lookup/info
+    """
+    adapter = request.app.state.lmcache_adapter
+    if not hasattr(adapter, "get_lookup_info"):
+        return _json_response({"error": "API unavailable"}, 503)
+    return _json_response(adapter.get_lookup_info())
+
+
+@router.post("/lookup/close")
+async def close_lookup(request: Request):
+    """
+    Close the current lookup client (scheduler) or server (worker).
+
+    Example:
+        curl -X POST http://localhost:6999/lookup/close
+    """
+    adapter = request.app.state.lmcache_adapter
+    role = _get_role(adapter)
+
+    if role == "scheduler":
+        if not hasattr(adapter, "close_lookup_client"):
+            return _json_response({"error": "API unavailable"}, 503)
+        result = adapter.close_lookup_client()
+    elif role == "worker":
+        if not hasattr(adapter, "close_lookup_server"):
+            return _json_response({"error": "API unavailable"}, 503)
+        result = adapter.close_lookup_server()
+    else:
+        return _json_response({"error": "Unknown role"}, 400)
+
+    result["role"] = role
+    return _json_response(result)
+
+
+@router.post("/lookup/create")
+async def create_lookup(request: Request, dryrun: bool = False):
+    """
+    Create a new lookup client (scheduler) or server (worker).
+
+    Args:
+        dryrun: If true, only show what would be created without creating it.
+
+    Example:
+        # Actually create
+        curl -X POST http://localhost:6999/lookup/create
+
+        # Dryrun - show what would be created
+        curl -X POST "http://localhost:6999/lookup/create?dryrun=true"
+    """
+    adapter = request.app.state.lmcache_adapter
+    role = _get_role(adapter)
+
+    if role == "scheduler":
+        if not hasattr(adapter, "create_lookup_client"):
+            return _json_response({"error": "API unavailable"}, 503)
+        result = adapter.create_lookup_client(dryrun=dryrun)
+    elif role == "worker":
+        if not hasattr(adapter, "create_lookup_server"):
+            return _json_response({"error": "API unavailable"}, 503)
+        result = adapter.create_lookup_server(dryrun=dryrun)
+    else:
+        return _json_response({"error": "Unknown role"}, 400)
+
+    result["role"] = role
+    if "error" in result:
+        return _json_response(result, 400)
+    return _json_response(result)
+
+
+@router.post("/lookup/recreate")
+async def recreate_lookup(request: Request):
+    """
+    Recreate the lookup client (scheduler) or server (worker).
+
+    This is equivalent to calling /lookup/close + /lookup/create.
+
+    IMPORTANT: Update configuration via /conf API before calling this.
+
+    Example:
+        # Step 1: Update config
+        curl -X PUT http://localhost:6999/conf \\
+        curl -X POST http://localhost:6999/conf \\
+            -d '{"enable_scheduler_bypass_lookup": true}'
+
+        # Step 2: Recreate
+        curl -X POST http://localhost:6999/lookup/recreate
+    """
+    adapter = request.app.state.lmcache_adapter
+    role = _get_role(adapter)
+
+    if role == "scheduler":
+        if not hasattr(adapter, "recreate_lookup_client"):
+            return _json_response({"error": "API unavailable"}, 503)
+        result = adapter.recreate_lookup_client()
+    elif role == "worker":
+        if not hasattr(adapter, "recreate_lookup_server"):
+            return _json_response({"error": "API unavailable"}, 503)
+        result = adapter.recreate_lookup_server()
+    else:
+        return _json_response({"error": "Unknown role"}, 400)
+
+    result["role"] = role
+    if "error" in result:
+        return _json_response(result, 400)
+    return _json_response(result)
diff --git a/lmcache/v1/internal_api_server/vllm/version_api.py b/lmcache/v1/internal_api_server/vllm/version_api.py
new file mode 100644
index 0000000..a244647
--- /dev/null
+++ b/lmcache/v1/internal_api_server/vllm/version_api.py
@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+
+# Third Party
+from fastapi import APIRouter
+
+# First Party
+from lmcache import utils
+
+router = APIRouter()
+
+
+@router.get("/lmc_version")
+async def get_lmc_version():
+    return utils.VERSION
+
+
+@router.get("/commit_id")
+async def get_commit_id():
+    return utils.COMMIT_ID
+
+
+@router.get("/version")
+async def get_version():
+    return utils.get_version()
diff --git a/lmcache/v1/kv_codec/__init__.py b/lmcache/v1/kv_codec/__init__.py
new file mode 100644
index 0000000..edf82da
--- /dev/null
+++ b/lmcache/v1/kv_codec/__init__.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+"""KV storage codec layer.
+
+Codecs operate above the storage backends: they take K and V
+tensors plus scales and produce a self-describing byte blob that
+any backend (local disk, GDS, NIXL, Redis, etc.) can write
+opaque-by-byte. This module owns storage compression only; tier
+placement lives elsewhere. See
+``lmcache/v1/kv_codec/asym_k16_v8.py`` for the asymmetric K16/V8
+codec.
+
+Design constraints:
+
+- Cross-model / cross-tokenizer / cross-rope / cross-backend cache
+  poisoning is gated by hashes carried in the codec header. See
+  ``EncodedKV.hashes`` and ``_check_hash_match``.
+- All on-disk integers are little-endian regardless of host.
+"""
+
+# First Party
+from lmcache.v1.kv_codec.asym_k16_v8 import (
+    AsymK16V8Codec,
+    compute_v_scales,
+    dequantize_v_fp8,
+    quantize_v_fp8,
+)
+from lmcache.v1.kv_codec.encoded_kv import (
+    CODEC_MAGIC,
+    CodecHashes,
+    CodecVersion,
+    EncodedKV,
+    ScaleScope,
+    deserialize_header,
+    serialize_header,
+)
+from lmcache.v1.kv_codec.errors import (
+    CodecError,
+    CodecMismatchError,
+    CorruptEncodedKVError,
+    UnsupportedConfigError,
+)
+
+__all__ = [
+    # Public codec interface
+    "AsymK16V8Codec",
+    "EncodedKV",
+    "CodecHashes",
+    "ScaleScope",
+    "CodecVersion",
+    "CODEC_MAGIC",
+    # Errors
+    "CodecError",
+    "CodecMismatchError",
+    "CorruptEncodedKVError",
+    "UnsupportedConfigError",
+    # Quant primitives (exposed for tests and benchmarks)
+    "compute_v_scales",
+    "quantize_v_fp8",
+    "dequantize_v_fp8",
+    # Header serialization (exposed for low-level tests)
+    "serialize_header",
+    "deserialize_header",
+]
diff --git a/lmcache/v1/kv_codec/asym_k16_v8.py b/lmcache/v1/kv_codec/asym_k16_v8.py
new file mode 100644
index 0000000..4b28729
--- /dev/null
+++ b/lmcache/v1/kv_codec/asym_k16_v8.py
@@ -0,0 +1,473 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Asymmetric K16/V8 KV codec.
+
+K is stored at FP16 or BF16 (the model's native dtype), V is
+quantized to FP8 e4m3fn with per-tensor / per-layer-head /
+per-page-head scales.  The codec is pure PyTorch; GPU support is
+inherited automatically from the device of the input tensors.
+
+Quant convention:
+  scale = max(|V|) / finfo(fp8).max
+  q     = clamp(V / scale, -finfo.max, +finfo.max).to(fp8)
+  V_hat = q.to(fp32) * scale
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Optional, Tuple
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.kv_codec.encoded_kv import (
+    CodecHashes,
+    EncodedKV,
+    ScaleScope,
+    deserialize_header,
+    serialize_header,
+)
+from lmcache.v1.kv_codec.errors import (
+    CodecMismatchError,
+    UnsupportedConfigError,
+)
+
+# Sentinel scale used when an entire tensor / head / page is all
+# zero.  Picking 1.0 keeps `dequant(quant(0)) == 0` exact and avoids
+# a 0/0 NaN.
+_ZERO_SCALE_SENTINEL = 1.0
+
+
+def _tensor_to_bytes_fast(t: torch.Tensor) -> bytes:
+    """Convert a contiguous CPU tensor to bytes via a single C-level memcpy.
+
+    Reinterpreting the tensor as uint8 and calling numpy's ``.tobytes()``
+    emits exactly the tensor's bytes -- including for tensors whose dtype
+    numpy doesn't natively know about (FP8, BF16), and crucially for
+    slices, where ``t.untyped_storage()`` would return the underlying
+    storage of the parent tensor (including sibling-slice bytes) rather
+    than just this slice's bytes.
+
+    Much faster than ``bytes(tensor.untyped_storage())``, which routes
+    through Python's bytes() constructor and iterates byte-by-byte at the
+    Python level.
+    """
+    return t.contiguous().view(-1).view(torch.uint8).numpy().tobytes()
+
+
+def _fp8_max(dtype: torch.dtype) -> float:
+    """FP8 representable absolute max via torch.finfo."""
+    if dtype not in (torch.float8_e4m3fn, torch.float8_e5m2):
+        raise UnsupportedConfigError(
+            f"compute_v_scales: dtype {dtype} is not an FP8 dtype"
+        )
+    return float(torch.finfo(dtype).max)
+
+
+def compute_v_scales(
+    v: torch.Tensor,
+    scope: ScaleScope,
+    *,
+    fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+    head_axis: int = -2,
+    page_axis: Optional[int] = None,
+) -> torch.Tensor:
+    """Compute FP32 V scales according to the requested scope.
+
+    Args:
+        v: the V tensor.  Layout-agnostic; `head_axis` and
+            `page_axis` index the dimensions for the chosen scope.
+        scope: PER_TENSOR / PER_LAYER_HEAD / PER_PAGE_HEAD.
+        fp8_dtype: float8_e4m3fn or float8_e5m2.
+        head_axis: which dim is "kv head" for per-head scales.
+            Default -2 covers (..., heads, dim) layouts.
+        page_axis: which dim is "page" for per-page scales.  Required
+            when scope is PER_PAGE_HEAD.
+
+    Returns:
+        FP32 scale tensor whose shape depends on scope:
+            PER_TENSOR     -> ()
+            PER_LAYER_HEAD -> (n_heads,)
+            PER_PAGE_HEAD  -> (n_pages, n_heads)
+    """
+    qmax = _fp8_max(fp8_dtype)
+    v32 = v.detach().to(torch.float32)
+
+    if scope == ScaleScope.PER_TENSOR:
+        amax = v32.abs().amax()
+        return torch.where(
+            amax > 0,
+            amax / qmax,
+            torch.tensor(_ZERO_SCALE_SENTINEL, dtype=torch.float32, device=v.device),
+        ).reshape(())
+
+    if scope == ScaleScope.PER_LAYER_HEAD:
+        # reduce over all dims except head_axis
+        ndim = v32.ndim
+        head = head_axis if head_axis >= 0 else ndim + head_axis
+        reduce_dims = tuple(d for d in range(ndim) if d != head)
+        amax = v32.abs().amax(dim=reduce_dims)  # (n_heads,)
+        scale = torch.where(
+            amax > 0,
+            amax / qmax,
+            torch.full_like(amax, _ZERO_SCALE_SENTINEL),
+        )
+        return scale
+
+    if scope == ScaleScope.PER_PAGE_HEAD:
+        if page_axis is None:
+            raise UnsupportedConfigError(
+                "compute_v_scales(PER_PAGE_HEAD) requires page_axis"
+            )
+        ndim = v32.ndim
+        head = head_axis if head_axis >= 0 else ndim + head_axis
+        page = page_axis if page_axis >= 0 else ndim + page_axis
+        keep = (page, head)
+        reduce_dims = tuple(d for d in range(ndim) if d not in keep)
+        amax = v32.abs().amax(dim=reduce_dims)
+        # amax is shaped per the surviving dims in their original
+        # order; permute to (n_pages, n_heads) for the on-disk shape.
+        if page > head:
+            # head dim came first after reduction; transpose
+            amax = amax.transpose(-1, -2)
+        scale = torch.where(
+            amax > 0,
+            amax / qmax,
+            torch.full_like(amax, _ZERO_SCALE_SENTINEL),
+        )
+        return scale
+
+    if scope == ScaleScope.EXTERNAL:
+        raise UnsupportedConfigError(
+            "compute_v_scales does not produce EXTERNAL scales; the "
+            "caller is expected to attach them."
+        )
+
+    raise UnsupportedConfigError(f"unknown scale scope: {scope}")
+
+
+def quantize_v_fp8(
+    v: torch.Tensor,
+    scales: torch.Tensor,
+    scope: ScaleScope,
+    *,
+    fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+    head_axis: int = -2,
+    page_axis: Optional[int] = None,
+) -> torch.Tensor:
+    """Quantize V to FP8 using the given scales.
+
+    Saturates at +/- finfo(fp8).max (via clamp before cast).
+    Returns a tensor with dtype=fp8_dtype, same shape as v.
+    """
+    qmax = _fp8_max(fp8_dtype)
+    v32 = v.detach().to(torch.float32)
+
+    if scope == ScaleScope.PER_TENSOR:
+        s = scales.to(torch.float32).reshape(())
+        scaled = v32 / s
+    elif scope == ScaleScope.PER_LAYER_HEAD:
+        ndim = v32.ndim
+        head = head_axis if head_axis >= 0 else ndim + head_axis
+        # broadcast (n_heads,) along all other dims
+        view_shape = [1] * ndim
+        view_shape[head] = scales.shape[0]
+        s = scales.to(torch.float32).view(*view_shape)
+        scaled = v32 / s
+    elif scope == ScaleScope.PER_PAGE_HEAD:
+        if page_axis is None:
+            raise UnsupportedConfigError(
+                "quantize_v_fp8(PER_PAGE_HEAD) requires page_axis"
+            )
+        ndim = v32.ndim
+        head = head_axis if head_axis >= 0 else ndim + head_axis
+        page = page_axis if page_axis >= 0 else ndim + page_axis
+        view_shape = [1] * ndim
+        view_shape[page] = scales.shape[0]
+        view_shape[head] = scales.shape[1]
+        s = scales.to(torch.float32).view(*view_shape)
+        scaled = v32 / s
+    else:
+        raise UnsupportedConfigError(f"unsupported scope: {scope}")
+
+    # Saturate, then cast.
+    saturated = torch.clamp(scaled, min=-qmax, max=qmax)
+    return saturated.to(fp8_dtype)
+
+
+def dequantize_v_fp8(
+    q: torch.Tensor,
+    scales: torch.Tensor,
+    scope: ScaleScope,
+    *,
+    out_dtype: torch.dtype = torch.float16,
+    head_axis: int = -2,
+    page_axis: Optional[int] = None,
+) -> torch.Tensor:
+    """Inverse of quantize_v_fp8.  Returns out_dtype."""
+    q32 = q.detach().to(torch.float32)
+    if scope == ScaleScope.PER_TENSOR:
+        s = scales.to(torch.float32).reshape(())
+        out = q32 * s
+    elif scope == ScaleScope.PER_LAYER_HEAD:
+        ndim = q32.ndim
+        head = head_axis if head_axis >= 0 else ndim + head_axis
+        view_shape = [1] * ndim
+        view_shape[head] = scales.shape[0]
+        s = scales.to(torch.float32).view(*view_shape)
+        out = q32 * s
+    elif scope == ScaleScope.PER_PAGE_HEAD:
+        if page_axis is None:
+            raise UnsupportedConfigError(
+                "dequantize_v_fp8(PER_PAGE_HEAD) requires page_axis"
+            )
+        ndim = q32.ndim
+        head = head_axis if head_axis >= 0 else ndim + head_axis
+        page = page_axis if page_axis >= 0 else ndim + page_axis
+        view_shape = [1] * ndim
+        view_shape[page] = scales.shape[0]
+        view_shape[head] = scales.shape[1]
+        s = scales.to(torch.float32).view(*view_shape)
+        out = q32 * s
+    else:
+        raise UnsupportedConfigError(f"unsupported scope: {scope}")
+    return out.to(out_dtype)
+
+
+class AsymK16V8Codec:
+    """Concrete codec for FP16/BF16-K + FP8-V asymmetric KV cache.
+
+    The codec is stateless aside from configuration (fp8 variant,
+    expected scale scope).  Instances are cheap; one per
+    (kv_storage_codec, kv_scale_scope) pair is fine.
+    """
+
+    def __init__(
+        self,
+        *,
+        fp8_dtype: torch.dtype = torch.float8_e4m3fn,
+        scale_dtype: torch.dtype = torch.float32,
+        scale_scope: ScaleScope = ScaleScope.PER_TENSOR,
+    ):
+        # Default is PER_TENSOR because PER_PAGE_HEAD also needs a
+        # page_axis argument every time `encode` is called.  Callers
+        # operating on paged caches construct the codec with
+        # `scale_scope=PER_PAGE_HEAD` and pass `page_axis` to encode.
+        if fp8_dtype not in (torch.float8_e4m3fn, torch.float8_e5m2):
+            raise UnsupportedConfigError(
+                f"AsymK16V8Codec: fp8_dtype must be float8_e4m3fn "
+                f"(or e5m2 reserved); got {fp8_dtype}"
+            )
+        if fp8_dtype == torch.float8_e5m2:
+            raise UnsupportedConfigError(
+                "float8_e5m2 is reserved-but-not-implemented in v1; use float8_e4m3fn"
+            )
+        self.fp8_dtype = fp8_dtype
+        self.scale_dtype = scale_dtype
+        self.scale_scope = scale_scope
+
+    def encode(
+        self,
+        k: torch.Tensor,
+        v: torch.Tensor,
+        *,
+        hashes: Optional[CodecHashes] = None,
+        layer_id: int = -1,
+        chunk_id: int = -1,
+        chunk_size: int = -1,
+        page_size: int = -1,
+        kv_head_count: int = -1,
+        head_dim: int = -1,
+        head_axis: int = -2,
+        page_axis: Optional[int] = None,
+        precomputed_v_scales: Optional[torch.Tensor] = None,
+        precomputed_v_quant: Optional[torch.Tensor] = None,
+    ) -> EncodedKV:
+        """Encode an asymmetric (K, V) pair into one EncodedKV blob.
+
+        If `precomputed_v_quant` is provided it is used as-is: the
+        caller has already produced V in FP8 and we copy bytes
+        without re-quanting.  Otherwise V is quantized here from
+        FP16/BF16.
+
+        `precomputed_v_scales` must be supplied alongside
+        `precomputed_v_quant` since we cannot recompute scales from
+        already-quantized V.
+
+        K is always copied at its native dtype; we never quantize K
+        in this codec (that's the whole asymmetric point).
+        """
+        if k.shape != v.shape:
+            raise UnsupportedConfigError(
+                f"encode: K and V shapes must match; got K={tuple(k.shape)} "
+                f"vs V={tuple(v.shape)}"
+            )
+
+        if precomputed_v_quant is not None:
+            if precomputed_v_scales is None:
+                raise UnsupportedConfigError(
+                    "encode: precomputed_v_quant requires precomputed_v_scales"
+                )
+            if precomputed_v_quant.dtype != self.fp8_dtype:
+                raise UnsupportedConfigError(
+                    f"encode: precomputed_v_quant dtype "
+                    f"{precomputed_v_quant.dtype} != codec "
+                    f"{self.fp8_dtype}"
+                )
+            v_quant = precomputed_v_quant
+            v_scales = precomputed_v_scales.to(self.scale_dtype)
+        else:
+            v_scales = compute_v_scales(
+                v,
+                self.scale_scope,
+                fp8_dtype=self.fp8_dtype,
+                head_axis=head_axis,
+                page_axis=page_axis,
+            ).to(self.scale_dtype)
+            v_quant = quantize_v_fp8(
+                v,
+                v_scales,
+                self.scale_scope,
+                fp8_dtype=self.fp8_dtype,
+                head_axis=head_axis,
+                page_axis=page_axis,
+            )
+
+        # Ensure all payloads are contiguous and CPU for the byte
+        # write.  The caller may be on GPU; serialize_header runs on
+        # CPU bytes either way.
+        #
+        # `_tensor_to_bytes_fast` reinterprets via `view(uint8).numpy()`
+        # which respects the contiguous view's stride and emits exactly
+        # the slice's bytes, so `.contiguous()` after `.to("cpu")` is
+        # sufficient -- no additional `.clone()` is needed.
+        k_cpu = k.detach().to("cpu").contiguous()
+        v_cpu = v_quant.detach().to("cpu").contiguous()
+        s_cpu = v_scales.detach().to("cpu").contiguous()
+        k_bytes = _tensor_to_bytes_fast(k_cpu)
+        v_bytes = _tensor_to_bytes_fast(v_cpu)
+        s_bytes = _tensor_to_bytes_fast(s_cpu)
+
+        enc = EncodedKV(
+            k_dtype=k.dtype,
+            v_dtype=self.fp8_dtype,
+            scale_dtype=self.scale_dtype,
+            scale_scope=self.scale_scope,
+            hashes=hashes if hashes is not None else CodecHashes(),
+            layer_id=layer_id,
+            chunk_id=chunk_id,
+            chunk_size=chunk_size,
+            page_size=page_size,
+            kv_head_count=kv_head_count,
+            head_dim=head_dim,
+            scale_shape=tuple(v_scales.shape),
+            k_payload_len=len(k_bytes),
+            v_payload_len=len(v_bytes),
+            scale_payload_len=len(s_bytes),
+            payload=k_bytes + v_bytes + s_bytes,
+        )
+        enc.header_bytes = serialize_header(enc)
+        return enc
+
+    def to_bytes(self, enc: EncodedKV) -> bytes:
+        """Concatenate header + payload for on-disk write."""
+        if enc.header_bytes is None:
+            enc.header_bytes = serialize_header(enc)
+        # `enc.payload` may be a memoryview on the read path; coerce
+        # to bytes so the returned object satisfies the bytes contract
+        # callers rely on.
+        if isinstance(enc.payload, memoryview):
+            return enc.header_bytes + bytes(enc.payload)
+        return enc.header_bytes + enc.payload
+
+    def from_bytes(
+        self,
+        buf: bytes,
+        *,
+        expected_hashes: Optional[CodecHashes] = None,
+    ) -> EncodedKV:
+        """Parse a byte buffer into an EncodedKV.
+
+        Cross-config gates: if `expected_hashes` is provided, any
+        non-empty mismatch raises `CodecMismatchError`.  Empty
+        strings are wildcards on either side.
+        """
+        enc = deserialize_header(buf)
+        if expected_hashes is not None:
+            self._check_hash_match(enc.hashes, expected_hashes)
+        return enc
+
+    @staticmethod
+    def _check_hash_match(got: CodecHashes, expected: CodecHashes) -> None:
+        for key in CodecHashes._CHECK_ORDER:
+            ev = getattr(expected, key)
+            gv = getattr(got, key)
+            if ev and gv and ev != gv:
+                raise CodecMismatchError(
+                    f"codec hash mismatch on {key!r}: encoded={gv!r}, expected={ev!r}"
+                )
+
+    def decode(
+        self,
+        enc: EncodedKV,
+        *,
+        out_k_dtype: Optional[torch.dtype] = None,
+        out_v_dtype: Optional[torch.dtype] = None,
+        device: Optional[torch.device] = None,
+    ) -> Tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        """Decode an EncodedKV into (K, V_quant_or_dequant, scales).
+
+        If `out_v_dtype` is None, V is returned at its native FP8
+        dtype (storage_only=False, native asym pathway).  If
+        `out_v_dtype` is FP16/BF16, V is dequantized into that
+        dtype.
+
+        K is returned at `out_k_dtype` if specified, else at the
+        encoded dtype.
+        """
+        if out_k_dtype is None:
+            out_k_dtype = enc.k_dtype
+        device = device or torch.device("cpu")
+
+        k_off = 0
+        v_off = enc.k_payload_len
+        s_off = v_off + enc.v_payload_len
+        k_bytes = enc.payload[k_off:v_off]
+        v_bytes = enc.payload[v_off:s_off]
+        s_bytes = enc.payload[s_off:]
+
+        # K: read-only view over the source bytes, then own the
+        # destination via .clone() (single memcpy total).
+        k_tensor = torch.frombuffer(k_bytes, dtype=enc.k_dtype).clone()
+        if out_k_dtype != enc.k_dtype:
+            k_tensor = k_tensor.to(out_k_dtype)
+        k_tensor = k_tensor.to(device)
+
+        # Scales
+        scale_tensor = (
+            torch.frombuffer(s_bytes, dtype=enc.scale_dtype)
+            .clone()
+            .reshape(enc.scale_shape)
+        )
+        scale_tensor = scale_tensor.to(device)
+
+        # V: read as fp8, optionally dequantize
+        v_q = torch.frombuffer(v_bytes, dtype=enc.v_dtype).clone().to(device)
+
+        if out_v_dtype is None or out_v_dtype == enc.v_dtype:
+            return k_tensor, v_q, scale_tensor
+
+        # Dequantize.  Caller specifies a higher-precision dtype.
+        if not out_v_dtype.is_floating_point:
+            raise UnsupportedConfigError(
+                f"decode: out_v_dtype {out_v_dtype} is not floating-point"
+            )
+        v_dq = dequantize_v_fp8(
+            v_q,
+            scale_tensor,
+            enc.scale_scope,
+            out_dtype=out_v_dtype,
+        )
+        return k_tensor, v_dq, scale_tensor
diff --git a/lmcache/v1/kv_codec/encoded_kv.py b/lmcache/v1/kv_codec/encoded_kv.py
new file mode 100644
index 0000000..3d42a49
--- /dev/null
+++ b/lmcache/v1/kv_codec/encoded_kv.py
@@ -0,0 +1,403 @@
+# SPDX-License-Identifier: Apache-2.0
+"""On-disk encoded KV format and metadata."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Optional, Tuple, Union
+import struct
+import zlib
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.kv_codec.errors import (
+    CorruptEncodedKVError,
+    UnsupportedConfigError,
+)
+
+# Magic prefix used to identify a v1 EncodedKV blob.  Chosen so
+# `head -c 8 file.bin` is human-readable.  Do not change this value;
+# every reader on every node identifies blobs by this byte sequence.
+CODEC_MAGIC: bytes = b"LMCKV\x01\x00\x01"  # "LMCKV", version major.minor.patch
+CODEC_MAGIC_LEN: int = len(CODEC_MAGIC)
+ASSERT_MAGIC_BYTES = 8
+assert CODEC_MAGIC_LEN == ASSERT_MAGIC_BYTES, "magic must be 8 bytes"
+
+
+class CodecVersion(IntEnum):
+    """Bumped when the on-disk header format changes incompatibly.
+
+    The minor/patch bytes inside CODEC_MAGIC are reserved for future
+    backwards-compatible additions (a v2 reader can read v1 blobs by
+    interpreting unknown trailing fields as zero/None).
+    """
+
+    V1 = 1
+
+
+class ScaleScope(IntEnum):
+    """How V scales are organized in the encoded blob.
+
+    `per_tensor`     one FP32 scalar for the entire V tensor.
+    `per_layer_head` one FP32 scalar per head, applied to all pages
+                     of that layer.
+    `per_page_head`  one FP32 scalar per (page, head).  Recommended
+                     default for asymmetric storage because paged KV
+                     chunks do not naturally respect "whole layer
+                     tensor" assumptions; the overhead is tiny vs
+                     V-byte volume.
+    `external`       scales not stored in this blob; expected to be
+                     attached out-of-band by the caller.
+    """
+
+    PER_TENSOR = 0
+    PER_LAYER_HEAD = 1
+    PER_PAGE_HEAD = 2
+    EXTERNAL = 3
+
+
+# Header packing: little-endian throughout regardless of host.
+#
+#   8 B  magic ("LMCKV" + 3-byte version triplet)
+#   2 B  header version (CodecVersion)
+#   2 B  scale_scope (ScaleScope)
+#   2 B  k_dtype_id   (DTYPE_TO_INT)
+#   2 B  v_dtype_id   (DTYPE_TO_INT)
+#   2 B  scale_dtype_id (DTYPE_TO_INT, typically float32 or float16)
+#   2 B  reserved (zero)
+#   8 B  layer_id  (int64; signed sentinel value -1 means unset)
+#   8 B  chunk_id  (int64; -1 unset)
+#   8 B  chunk_size (int64; tokens per chunk for paged caches)
+#   8 B  page_size (int64; tokens per page)
+#   8 B  kv_head_count (int64)
+#   8 B  head_dim (int64)
+#   8 B  scale_shape_n (int64; number of dimensions in scale tensor)
+#   N×8B scale_shape values
+#   8 B  k_payload_len (int64, bytes)
+#   8 B  v_payload_len (int64, bytes)
+#   8 B  scale_payload_len (int64, bytes)
+#   2 B  hash_strs_n (number of (key, value) string pairs that follow)
+#   For each str pair: 2-byte key_len, key, 2-byte val_len, val.
+#     Currently used keys: model_id, model_revision_hash,
+#     tokenizer_hash, rope_config_hash, attention_backend, kv_layout.
+#   4 B  payload_crc32c        (CRC of the K + V + scales payload)
+#
+# Followed by: K_payload (k_payload_len bytes), V_payload, scales.
+#
+# Field order is fixed; new fields added in V2+ append after CRC.
+
+_FIXED_HEADER_FMT = "<8sHHHHHH" + "qqqqqqq"  # magic + 6 shorts + 7 int64
+_FIXED_HEADER_LEN = struct.calcsize(_FIXED_HEADER_FMT)
+# 8 + 2*6 + 8*7 = 76 bytes
+assert _FIXED_HEADER_LEN == 76, _FIXED_HEADER_LEN
+
+
+def _pack_str(s: str) -> bytes:
+    if s is None:
+        s = ""
+    encoded = s.encode("utf-8")
+    if len(encoded) > 0xFFFF:
+        raise UnsupportedConfigError(
+            f"hash string longer than 65535 bytes: {len(encoded)}"
+        )
+    return struct.pack("<H", len(encoded)) + encoded
+
+
+def _unpack_str(buf: memoryview, off: int) -> Tuple[str, int]:
+    if off + 2 > len(buf):
+        raise CorruptEncodedKVError(f"truncated string-length field at offset {off}")
+    (length,) = struct.unpack_from("<H", buf, off)
+    off += 2
+    if off + length > len(buf):
+        raise CorruptEncodedKVError(
+            f"string at offset {off} declares length {length} but only "
+            f"{len(buf) - off} bytes remain"
+        )
+    try:
+        s = bytes(buf[off : off + length]).decode("utf-8")
+    except UnicodeDecodeError as e:
+        raise CorruptEncodedKVError(
+            f"non-utf-8 bytes in string field at offset {off}: {e}"
+        ) from None
+    return s, off + length
+
+
+@dataclass
+class CodecHashes:
+    """Identifying hashes that gate cross-config cache poisoning.
+
+    Empty strings mean "not provided"; serialization treats empty
+    string and None identically.  Any non-empty mismatch on read
+    raises `CodecMismatchError` (see codec.AsymK16V8Codec.decode).
+    """
+
+    model_id: str = ""
+    model_revision_hash: str = ""
+    tokenizer_hash: str = ""
+    rope_config_hash: str = ""
+    attention_backend: str = ""
+    kv_layout: str = ""
+
+    # Fields are checked in this order during decode mismatch detection.
+    _CHECK_ORDER = (
+        "model_id",
+        "model_revision_hash",
+        "tokenizer_hash",
+        "rope_config_hash",
+        "attention_backend",
+        "kv_layout",
+    )
+
+
+@dataclass
+class EncodedKV:
+    """A self-describing encoded KV blob.
+
+    `payload` carries `K_bytes ‖ V_bytes ‖ scale_bytes` in that
+    order.  Lengths are in `k_payload_len`, `v_payload_len`,
+    `scale_payload_len`.  All numeric fields are little-endian on
+    disk regardless of host.
+    """
+
+    # Logical shape/dtype information (same fields as MemoryObjMetadata.dtypes/shapes)
+    k_dtype: torch.dtype
+    v_dtype: torch.dtype
+    scale_dtype: torch.dtype = torch.float32
+    scale_scope: ScaleScope = ScaleScope.PER_PAGE_HEAD
+
+    # Identity / cache-poisoning gates
+    hashes: CodecHashes = field(default_factory=CodecHashes)
+
+    # Layout / shape parameters (-1 = unset)
+    layer_id: int = -1
+    chunk_id: int = -1
+    chunk_size: int = -1
+    page_size: int = -1
+    kv_head_count: int = -1
+    head_dim: int = -1
+
+    # Scale tensor shape; e.g., () for per_tensor, (kv_head_count,)
+    # for per_layer_head, (n_pages, kv_head_count) for per_page_head.
+    scale_shape: Tuple[int, ...] = ()
+
+    # Payload byte counts
+    k_payload_len: int = 0
+    v_payload_len: int = 0
+    scale_payload_len: int = 0
+
+    # The actual encoded byte blob (header + payload).  When the
+    # EncodedKV is freshly assembled from tensors, callers populate
+    # `payload` (the K+V+scale bytes) and `header_bytes` is computed
+    # at serialize time.  When parsed from a buffer via
+    # ``deserialize_header``, ``payload`` is a memoryview slice over
+    # the source buffer to avoid a full payload copy on the read
+    # path.
+    payload: Union[bytes, memoryview] = b""
+    header_bytes: Optional[bytes] = None
+
+    @property
+    def total_bytes(self) -> int:
+        """Total encoded size: header + payload."""
+        if self.header_bytes is None:
+            return -1
+        return len(self.header_bytes) + len(self.payload)
+
+    def expected_payload_len(self) -> int:
+        return self.k_payload_len + self.v_payload_len + self.scale_payload_len
+
+
+def _dtype_to_int(dtype: Optional[torch.dtype]) -> int:
+    """Local re-export of the protocol DTYPE_TO_INT to avoid a
+    circular import at module-load time."""
+    # First Party
+    from lmcache.v1.protocol import DTYPE_TO_INT
+
+    if dtype not in DTYPE_TO_INT:
+        raise UnsupportedConfigError(
+            f"dtype {dtype} not in protocol DTYPE_TO_INT mapping"
+        )
+    return DTYPE_TO_INT[dtype]
+
+
+def _int_to_dtype(idx: int) -> Optional[torch.dtype]:
+    # First Party
+    from lmcache.v1.protocol import INT_TO_DTYPE
+
+    if idx not in INT_TO_DTYPE:
+        raise CorruptEncodedKVError(f"unknown dtype index {idx} in encoded header")
+    return INT_TO_DTYPE[idx]
+
+
+def serialize_header(enc: EncodedKV) -> bytes:
+    """Pack the EncodedKV header into bytes (excludes payload).
+
+    Computes payload CRC32 from `enc.payload` and writes it as the
+    last field.  Caller is responsible for ensuring `enc.payload`
+    matches `expected_payload_len()`.
+    """
+    if len(enc.payload) != enc.expected_payload_len():
+        raise UnsupportedConfigError(
+            f"payload length {len(enc.payload)} does not match "
+            f"declared K({enc.k_payload_len}) + V({enc.v_payload_len}) "
+            f"+ scales({enc.scale_payload_len})"
+        )
+
+    fixed = struct.pack(
+        _FIXED_HEADER_FMT,
+        CODEC_MAGIC,
+        int(CodecVersion.V1),
+        int(enc.scale_scope),
+        _dtype_to_int(enc.k_dtype),
+        _dtype_to_int(enc.v_dtype),
+        _dtype_to_int(enc.scale_dtype),
+        0,  # reserved
+        enc.layer_id,
+        enc.chunk_id,
+        enc.chunk_size,
+        enc.page_size,
+        enc.kv_head_count,
+        enc.head_dim,
+        len(enc.scale_shape),
+    )
+    scale_shape_bytes = struct.pack(f"<{len(enc.scale_shape)}q", *enc.scale_shape)
+    payload_lens = struct.pack(
+        "<qqq", enc.k_payload_len, enc.v_payload_len, enc.scale_payload_len
+    )
+    # Hash strings
+    hash_keys = list(CodecHashes._CHECK_ORDER)
+    hash_blob = struct.pack("<H", len(hash_keys))
+    for k in hash_keys:
+        hash_blob += _pack_str(k) + _pack_str(getattr(enc.hashes, k))
+
+    # CRC over the actual payload bytes (the K+V+scales blob), not
+    # over the header itself.  zlib.crc32 is CRC32/IEEE; if a future
+    # reader needs CRC32C specifically we bump CodecVersion.
+    crc = zlib.crc32(enc.payload) & 0xFFFFFFFF
+    crc_bytes = struct.pack("<I", crc)
+
+    return fixed + scale_shape_bytes + payload_lens + hash_blob + crc_bytes
+
+
+def deserialize_header(buf: bytes) -> EncodedKV:
+    """Parse an EncodedKV header from a contiguous byte buffer.
+
+    The buffer must contain header + payload.  Returns an EncodedKV
+    with `header_bytes` and `payload` both populated.
+
+    Raises:
+        CorruptEncodedKVError on magic/version/CRC mismatch or any
+        truncated field.
+    """
+    mv = memoryview(buf)
+    if len(mv) < _FIXED_HEADER_LEN:
+        raise CorruptEncodedKVError(
+            f"buffer too short for fixed header: {len(mv)} < {_FIXED_HEADER_LEN}"
+        )
+
+    fixed = struct.unpack_from(_FIXED_HEADER_FMT, mv, 0)
+    (
+        magic,
+        version,
+        scale_scope,
+        k_dtype_id,
+        v_dtype_id,
+        scale_dtype_id,
+        _reserved,
+        layer_id,
+        chunk_id,
+        chunk_size,
+        page_size,
+        kv_head_count,
+        head_dim,
+        scale_shape_n,
+    ) = fixed
+    if magic != CODEC_MAGIC:
+        raise CorruptEncodedKVError(
+            f"bad magic: got {magic!r}, expected {CODEC_MAGIC!r}"
+        )
+    if version != int(CodecVersion.V1):
+        raise CorruptEncodedKVError(
+            f"unsupported codec version {version}; this build supports "
+            f"{int(CodecVersion.V1)}"
+        )
+    if scale_shape_n < 0 or scale_shape_n > 8:
+        raise CorruptEncodedKVError(f"implausible scale_shape_n: {scale_shape_n}")
+
+    off = _FIXED_HEADER_LEN
+    if off + 8 * scale_shape_n > len(mv):
+        raise CorruptEncodedKVError(
+            f"buffer too short for scale_shape: need {8 * scale_shape_n} bytes"
+        )
+    scale_shape = tuple(struct.unpack_from(f"<{scale_shape_n}q", mv, off))
+    off += 8 * scale_shape_n
+
+    if off + 24 > len(mv):
+        raise CorruptEncodedKVError("truncated payload-lengths field")
+    k_len, v_len, s_len = struct.unpack_from("<qqq", mv, off)
+    off += 24
+
+    if off + 2 > len(mv):
+        raise CorruptEncodedKVError("truncated hashes-count field")
+    (n_hashes,) = struct.unpack_from("<H", mv, off)
+    off += 2
+
+    hashes = CodecHashes()
+    expected_keys = set(CodecHashes._CHECK_ORDER)
+    for _ in range(n_hashes):
+        key, off = _unpack_str(mv, off)
+        val, off = _unpack_str(mv, off)
+        if key in expected_keys:
+            setattr(hashes, key, val)
+
+    if off + 4 > len(mv):
+        raise CorruptEncodedKVError("truncated CRC field")
+    (crc_declared,) = struct.unpack_from("<I", mv, off)
+    off += 4
+
+    expected_payload = k_len + v_len + s_len
+    if off + expected_payload > len(mv):
+        raise CorruptEncodedKVError(
+            f"buffer truncated mid-payload: header ends at {off}, "
+            f"declared payload = {expected_payload}, buffer total "
+            f"= {len(mv)}"
+        )
+
+    payload = mv[off : off + expected_payload]
+    crc_computed = zlib.crc32(payload) & 0xFFFFFFFF
+    if crc_computed != crc_declared:
+        raise CorruptEncodedKVError(
+            f"payload CRC mismatch: declared {crc_declared:#x}, "
+            f"computed {crc_computed:#x}"
+        )
+
+    try:
+        scope_enum = ScaleScope(scale_scope)
+    except ValueError:
+        raise CorruptEncodedKVError(
+            f"unknown scale_scope index {scale_scope} in encoded header"
+        ) from None
+    enc = EncodedKV(
+        k_dtype=_int_to_dtype(k_dtype_id),
+        v_dtype=_int_to_dtype(v_dtype_id),
+        scale_dtype=_int_to_dtype(scale_dtype_id),
+        scale_scope=scope_enum,
+        hashes=hashes,
+        layer_id=layer_id,
+        chunk_id=chunk_id,
+        chunk_size=chunk_size,
+        page_size=page_size,
+        kv_head_count=kv_head_count,
+        head_dim=head_dim,
+        scale_shape=scale_shape,
+        k_payload_len=k_len,
+        v_payload_len=v_len,
+        scale_payload_len=s_len,
+        payload=payload,
+        header_bytes=bytes(mv[:off]),
+    )
+    return enc
diff --git a/lmcache/v1/kv_codec/errors.py b/lmcache/v1/kv_codec/errors.py
new file mode 100644
index 0000000..f71e1a0
--- /dev/null
+++ b/lmcache/v1/kv_codec/errors.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Codec error types.
+
+These are the only exceptions the codec layer raises.  Every error
+path in the codec must surface one of these with a message that
+names the observed-vs-expected condition; do not raise bare
+RuntimeError or KeyError.
+"""
+
+
+class CodecError(Exception):
+    """Base class for all KV codec errors."""
+
+
+class CodecMismatchError(CodecError):
+    """The encoded blob was produced under a different config than
+    what the caller is requesting.
+
+    Examples: cross-model cache poisoning (different model_id), a
+    different page_size, an attention backend the caller is not
+    running, or a scale_scope the caller did not configure.
+    """
+
+
+class CorruptEncodedKVError(CodecError):
+    """The encoded blob's header or payload failed an integrity
+    check.
+
+    Examples: codec_magic does not match, codec_version is unknown,
+    payload_crc32c does not match, the payload is truncated.
+    """
+
+
+class UnsupportedConfigError(CodecError):
+    """The caller asked the codec to emit something it cannot.
+
+    Examples: a runtime_layout this codec doesn't implement, or an
+    FP8 variant (e5m2) reserved-but-not-implemented in v1.
+    """
diff --git a/lmcache/v1/kv_layer_groups.py b/lmcache/v1/kv_layer_groups.py
new file mode 100644
index 0000000..2ae3f3c
--- /dev/null
+++ b/lmcache/v1/kv_layer_groups.py
@@ -0,0 +1,872 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import defaultdict
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NamedTuple
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.python_ops_fallback import set_shape_desc_dtype
+from lmcache.utils import lmcache_deprecate
+from lmcache.v1.distributed.api import AttnWindowDesc
+import lmcache.c_ops as lmc_ops
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.gpu_connector.utils import DiscoverableKVCache
+    from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+
+logger = init_logger(__name__)
+
+# ------------------------------------------------------------------ #
+#  Constants                                                           #
+# ------------------------------------------------------------------ #
+
+DEFAULT_LAYER_NAME_PREFIX = "model.layers."
+
+# ------------------------------------------------------------------ #
+#  dtype mapping                                                       #
+# ------------------------------------------------------------------ #
+
+DTYPE_MAP: dict[str, torch.dtype] = {
+    "float16": torch.float16,
+    "float32": torch.float32,
+    "bfloat16": torch.bfloat16,
+    "uint8": torch.uint8,
+}
+
+
+# The tuple that uniquely identifies a set of kernel-equivalent layers; one
+# distinct identity becomes one LMCache KV group:
+# ``(kv_size, num_heads, head_size, block_size, engine_group_idx, dtype,
+# engine_kv_format)``.
+# ``engine_group_idx`` is the engine group id (one paged-block address space):
+# block IDs are only meaningful within one group, so layers from different
+# groups must not share an LMCache group even if shape and dtype match.
+# ``engine_kv_format`` keeps layouts that share an engine group from merging --
+# load-bearing when one ``engine_group_idx`` mixes layouts (a rank-5 K/V group
+# alongside a rank-3 key-only indexer cache): this field is what splits them
+# into separate kernel groups, each transferred with its own layout.
+class KernelGroupIdentity(NamedTuple):
+    kv_size: int
+    num_heads: int
+    head_size: int
+    block_size: int
+    engine_group_idx: int
+    dtype: torch.dtype
+    engine_kv_format: "lmc_ops.EngineKVFormat"
+
+
+LayerGroupIdentity = KernelGroupIdentity  # Alias for compatibility
+
+
+# Sentinel ``per_layer_engine_group_idx`` value: a KV tensor tagged with it is
+# excluded from every LMCache group (used for cross-layer KV-sharing layers; see
+# ``create_engine_group_infos_from_vllm``).
+EXCLUDED_ENGINE_GROUP = -1
+
+
+def group_layers_by_identity(
+    kv_caches: "DiscoverableKVCache",
+    engine_kv_formats: "Sequence[lmc_ops.EngineKVFormat]",
+    per_layer_engine_group_idx: Sequence[int] | None = None,
+) -> list[tuple[LayerGroupIdentity, list[int]]]:
+    """Partition layer indices by :data:`LayerGroupIdentity`.
+
+    Args:
+        kv_caches: Registered KV cache structure, one entry per layer.
+        engine_kv_formats: One Engine KV format per registered tensor; its length
+            is the layer count. Homogeneous models repeat one shared format; a
+            model that mixes formats across engine groups -- e.g. a K+V main cache
+            (``kv_size=2``) plus a key-only MLA index cache (``kv_size=1``) --
+            supplies the differing per-layer formats.
+        per_layer_engine_group_idx: Optional engine block group id per layer.
+            When ``None`` every layer is treated as block group 0 (non-hybrid);
+            when present, layers from different engine block groups never share an
+            identity even if their tensor shapes match. Layers whose value is
+            ``EXCLUDED_ENGINE_GROUP`` are left out of all groups (e.g. cross-layer
+            KV-sharing layers whose KV lives in their target owner's blocks).
+
+    Returns:
+        A list of ``(identity, layer_indices)`` pairs sorted by each group's
+        first layer index, so the group order is deterministic.
+
+    Raises:
+        ValueError: If ``per_layer_engine_group_idx`` is given but its length
+            does not match ``engine_kv_formats``.
+    """
+    # First Party
+    from lmcache.v1.gpu_connector.utils import (
+        get_block_size,
+        get_dtype,
+        get_head_size,
+        get_num_heads,
+        is_mla,
+    )
+
+    num_layers = len(engine_kv_formats)
+    if (
+        per_layer_engine_group_idx is not None
+        and len(per_layer_engine_group_idx) != num_layers
+    ):
+        raise ValueError(
+            f"per_layer_engine_group_idx has {len(per_layer_engine_group_idx)} "
+            f"entries but engine_kv_formats has {num_layers} layers"
+        )
+
+    groups_dict: dict[LayerGroupIdentity, list[int]] = defaultdict(list)
+    for idx in range(num_layers):
+        engine_group_idx = (
+            per_layer_engine_group_idx[idx]
+            if per_layer_engine_group_idx is not None
+            else 0
+        )
+        # Skip layers explicitly excluded from grouping (e.g. cross-layer
+        # KV-sharing layers, whose KV lives in their target owner's blocks).
+        if engine_group_idx == EXCLUDED_ENGINE_GROUP:
+            continue
+        layer_format = engine_kv_formats[idx]
+        mla = is_mla(layer_format)
+        kv_size = 1 if mla else 2
+        nh = 1 if mla else get_num_heads(kv_caches, layer_format, idx)
+        hs = get_head_size(kv_caches, layer_format, idx)
+        dt = get_dtype(kv_caches, layer_format, idx)
+        bs = get_block_size(kv_caches, layer_format, idx)
+
+        identity = LayerGroupIdentity(
+            kv_size=kv_size,
+            num_heads=nh,
+            head_size=hs,
+            block_size=bs,
+            engine_group_idx=engine_group_idx,
+            dtype=dt,
+            engine_kv_format=layer_format,
+        )
+        groups_dict[identity].append(idx)
+    return sorted(groups_dict.items(), key=lambda kv: kv[1][0])
+
+
+@dataclass
+class KernelGroupInfo:
+    """A single transfer-kernel dispatch unit: a set of KV layers that can
+    ride one kernel launch with one ``PageBufferShapeDesc``.
+
+    Membership is decided by :class:`KVLayerGroupsManager` according to
+    :data:`LayerGroupIdentity`; every layer referenced by
+    ``layer_indices`` shares the same
+    ``(kv_size, num_heads, head_size, block_size, engine_group_idx,
+    dtype, engine_kv_format)`` signature.
+    Consumers use ``layer_indices`` to pull the matching device pointers
+    out of ``kv_caches`` (via
+    :func:`~lmcache.v1.gpu_connector.utils.get_group_data_ptrs`) and
+    feed them to the kernel alongside ``shape_desc``.
+
+    ``dtype`` is carried alongside ``shape_desc`` because
+    ``PageBufferShapeDesc.element_size`` is a byte width, which cannot
+    distinguish dtypes that share a byte count (e.g. bfloat16 and
+    float16 are both 2 bytes). Kernel template instantiation keys on the
+    torch dtype, not the byte width, so we keep it explicit.
+
+    Treat instances as immutable after construction; callers may hold
+    references for the lifetime of the manager.
+    """
+
+    layer_indices: list[int]
+    """0-based layer indices belonging to this group, in the order the
+    kernel should iterate them. Fed to ``get_group_data_ptrs`` to build
+    the per-group pointer array."""
+    shape_desc: "lmc_ops.PageBufferShapeDesc"
+    """Kernel-facing shape descriptor shared by every layer in the group.
+    All eight fields (``kv_size, nl, nb, bs, nh, hs, element_size,
+    block_stride_elems``) are stamped once at construction."""
+    dtype: torch.dtype
+    """Torch dtype of the KV cache tensors for this group. Used for
+    kernel template instantiation; see class docstring for why we keep
+    this alongside ``shape_desc.element_size``."""
+    engine_kv_format: "lmc_ops.EngineKVFormat | None" = None
+    """Per-group Engine KV format, read via
+    ``BaseCacheContext.get_engine_kv_format`` so mixed-format models dispatch each
+    group with its own. ``None`` only for bench bookkeeping groups from
+    :func:`parse_kvcache_shape_spec`, which have no detected format and never
+    transfer; detection-built groups always set it."""
+    tokens_per_block: int = 0
+    """Logical engine tokens covered by one paged chunk (one engine block
+    ID) of this group, as declared by the engine's KV cache spec at
+    initialization time (carried in ``EngineGroupInfo.tokens_per_block``).
+    ``0`` means the engine did not report it; the group is then treated as
+    uncompressed (``compress_ratio == 1``)."""
+    engine_group_idx: int = 0
+    """Engine group index (paged-block address space). 0 for non-hybrid."""
+    sw_size_tokens: int = -1
+    """Sliding window size in logical tokens for this group's layers.
+    ``-1`` means the layers are not sliding-window attention."""
+
+    def __repr__(self) -> str:
+        if not self.layer_indices:
+            indices_repr = "[]"
+        else:
+            indices_repr = f"{self.layer_indices[0]}-{self.layer_indices[-1]}"
+        sd = self.shape_desc
+        return (
+            f"KernelGroupInfo(layers={len(self.layer_indices)}, "
+            f"indices={indices_repr}, "
+            f"shape_desc=(kv={sd.kv_size}, nl={sd.nl}, nb={sd.nb}, "
+            f"bs={sd.bs}, nh={sd.nh}, hs={sd.hs}, "
+            f"element_size={sd.element_size}, "
+            f"block_stride_elems={sd.block_stride_elems}), "
+            f"dtype={self.dtype}, "
+            f"tokens_per_block={self.tokens_per_block}, "
+            f"slots_per_block={self.slots_per_block}, "
+            f"engine_group_idx={self.engine_group_idx}, "
+            f"sw_size_tokens={self.sw_size_tokens})"
+        )
+
+    @property
+    def num_layers(self) -> int:
+        """Number of layers in this group."""
+        return len(self.layer_indices)
+
+    @property
+    def hidden_dim_size(self) -> int:
+        """Hidden dimension size (``num_heads * head_size``)."""
+        return self.shape_desc.nh * self.shape_desc.hs
+
+    @property
+    def slots_per_block(self) -> int:
+        """Physical slots in one paged chunk of this group, detected from
+        the registered KV tensors at registration time (the batch-size
+        dimension, ``shape_desc.bs``)."""
+        return self.shape_desc.bs
+
+    def calculate_slots(self, num_tokens: int) -> int:
+        """Calculate the number of slots for the specified number of
+        tokens. Assuming the number of tokens are already aligned.
+        """
+        return num_tokens * self.slots_per_block // self.tokens_per_block
+
+
+KVLayerGroupInfo = KernelGroupInfo  # Alias for compatibility
+
+
+@dataclass
+class ObjectGroupInfo:
+    """Metadata for an 'object group'.
+
+    An object group contains one or more kernel groups whose
+    KV caches will be stored in the same memory object.
+
+    This will be useful for dealing with sliding window or mamba
+    KV caches that needs a different prefix matching logic from
+    the full attention KV caches.
+    """
+
+    kernel_group_indices: list[int]
+    """Indices of the kernel groups belonging to this object group, in the
+    order they should be laid out in memory."""
+
+    sw_size_chunks: int = -1
+    """Cross-chunk sliding window size in LMCache chunks shared by every
+    kernel group in this object group. ``-1`` means the kernel groups are
+    not sliding-window attention."""
+
+
+class KVLayerGroupsManager:
+    """Partition a model's KV layers into transfer-kernel dispatch units.
+
+    At construction time, every layer in ``kv_caches`` is bucketed by its
+    :data:`LayerGroupIdentity` (``(kv_size, num_heads, head_size,
+    block_size, engine_group_idx, dtype, engine_kv_format)``). Each bucket
+    becomes one
+    :class:`KernelGroupInfo` holding the layer indices, a shared
+    :class:`PageBufferShapeDesc`, and the group's torch dtype.
+
+    Downstream consumers (``VLLMPagedMemGPUConnectorV3``,
+    ``GPUCacheContext``, the multiprocess server) iterate
+    ``self._kernel_groups`` and issue one transfer-kernel launch per
+    group. The manager itself is a pure metadata object — it does not
+    own any GPU buffers or perform any transfers.
+
+    Layout parsing is delegated entirely to
+    :mod:`lmcache.v1.gpu_connector.utils`; this class only drives the
+    grouping and look-up.
+    """
+
+    def __init__(
+        self,
+        kv_caches: "DiscoverableKVCache",
+        engine_kv_formats: "Sequence[lmc_ops.EngineKVFormat]",
+        engine_group_infos: "Sequence[EngineGroupInfo]" = (),
+        lmcache_tokens_per_chunk: int = 256,
+        separate_object_groups: bool = True,
+    ) -> None:
+        """Partition the layers into kernel groups for this set of KV caches.
+
+        Group order is deterministic across runs.
+
+        Args:
+            kv_caches: KV cache structure accepted by
+                :func:`normalize_and_discover_per_layer_formats`.
+            engine_kv_formats: One Engine KV format per layer (its length is the
+                layer count), from
+                :func:`normalize_and_discover_per_layer_formats`. A model that
+                mixes formats across engine groups supplies the differing
+                per-layer formats so each group is shaped with its own;
+                homogeneous models repeat one shared format.
+            engine_group_infos: Engine KV cache group metadata, one info per
+                kernel group in kernel-group order, or empty.
+            lmcache_logical_chunk_size: Tokens per LMCache chunk
+            separate_object_groups: When True (default), split kernel groups
+                into one object group per sliding-window size; when False, all
+                kernel groups share a single full-attention object group.
+        """
+        # Import here to break a circular import via
+        # lmcache.v1.gpu_connector.__init__ → metadata → kv_layer_groups.
+        # First Party
+        from lmcache.v1.gpu_connector.utils import (
+            get_num_blocks,
+            make_page_buffer_shape_desc,
+            resolve_block_stride_and_log_layout,
+        )
+        from lmcache.v1.multiprocess.group_view import get_engine_group_indices
+
+        self._kernel_groups: list[KernelGroupInfo] = []
+        self._object_groups: list[ObjectGroupInfo] = []
+
+        num_layers = len(engine_kv_formats)
+        if num_layers == 0:
+            logger.debug("No KV caches available, skipping KV layer groups building")
+            return
+
+        per_layer_engine_group_idx = get_engine_group_indices(
+            engine_group_infos, num_layers
+        )
+        groups_by_identity = group_layers_by_identity(
+            kv_caches, engine_kv_formats, per_layer_engine_group_idx
+        )
+
+        # Engine group infos are produced by the same group_layers_by_identity
+        # bucketing on the engine side, so they correspond 1:1, in order, to
+        # the kernel groups built below.
+        if engine_group_infos and len(engine_group_infos) != len(groups_by_identity):
+            raise ValueError(
+                f"Got {len(engine_group_infos)} engine group infos for "
+                f"{len(groups_by_identity)} kernel groups; expecting one "
+                "engine group info per kernel group"
+            )
+
+        # Emit groups in order of their first-appearing layer so that group
+        # indices remain deterministic across runs.
+        for group_idx, (identity, indices) in enumerate(groups_by_identity):
+            bs = identity.block_size
+            engine_group_idx = identity.engine_group_idx
+            dt = identity.dtype
+            # Format is part of the identity, so every layer in the group shares
+            # it -- this is the whole group's format, by construction.
+            group_format = identity.engine_kv_format
+            # Block count is per engine group (each is its own block-id space), so
+            # read it from this group's own tensor rather than a context-wide value.
+            group_num_blocks = get_num_blocks([kv_caches[indices[0]]], group_format)
+            block_stride_elems = resolve_block_stride_and_log_layout(
+                kv_caches,
+                group_format,
+                layer_idx=indices[0],
+                group_idx=group_idx,
+            )
+            shape_desc = make_page_buffer_shape_desc(
+                kv_caches,
+                group_format,
+                layer_idx=indices[0],
+                num_layers_in_group=len(indices),
+                num_blocks=group_num_blocks,
+                block_size=bs,
+                block_stride_elems=block_stride_elems,
+            )
+
+            info = engine_group_infos[group_idx] if engine_group_infos else None
+            if info is not None and tuple(indices) != tuple(info.layer_indices):
+                raise ValueError(
+                    f"group {group_idx}: engine group info covers layers "
+                    f"{info.layer_indices}, but the kernel group covers "
+                    f"layers {indices}"
+                )
+
+            # tokens_per_block comes from the engine's KV cache spec; when
+            # absent, fall back to the physical slot count so the group is
+            # treated as non-compressed (compress_ratio == 1).
+            tokens_per_block = (
+                info.tokens_per_block
+                if info is not None and info.tokens_per_block > 0
+                else bs
+            )
+            sw_size_tokens = info.sw_size_tokens if info is not None else -1
+
+            self._validate_block_chunk_size_config(
+                group_idx,
+                slots_per_block=bs,
+                tokens_per_block=tokens_per_block,
+                lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+                sw_size_tokens=sw_size_tokens,
+            )
+
+            self._kernel_groups.append(
+                KernelGroupInfo(
+                    layer_indices=indices,
+                    shape_desc=shape_desc,
+                    dtype=dt,
+                    engine_kv_format=group_format,
+                    tokens_per_block=tokens_per_block,
+                    engine_group_idx=engine_group_idx,
+                    sw_size_tokens=sw_size_tokens,
+                )
+            )
+
+        self._lmcache_tokens_per_chunk = lmcache_tokens_per_chunk
+        self._separate_object_groups = separate_object_groups
+
+        # When True, sliding-window groups store/transfer FULL per-chunk KV
+        self._full_sw_kv = False
+
+        logger.info(
+            "KV layer groups: ---\n%s\n---",
+            "\n".join(repr(g) for g in self._kernel_groups),
+        )
+
+        # Detect the object groups
+        self._object_groups = self._detect_object_groups(engine_group_infos)
+
+    @property
+    def kernel_groups(self) -> list[KernelGroupInfo]:
+        """List of :class:`KernelGroupInfo`, one per kernel group."""
+        return self._kernel_groups
+
+    @property
+    def num_blocks(self) -> int:
+        """Paged block count, shared across kernel groups (one block-id space).
+
+        Read from the first kernel group's ``shape_desc.nb``, which was computed
+        from that group's own tensor and format -- not a guessed representative.
+        Returns ``0`` when there are no kernel groups.
+        """
+        if not self._kernel_groups:
+            return 0
+        return self._kernel_groups[0].shape_desc.nb
+
+    @property
+    @lmcache_deprecate("`kv_layer_groups` is an outdated alias for `kernel_groups`")
+    def kv_layer_groups(self) -> list[KernelGroupInfo]:
+        """List of :class:`KernelGroupInfo`, one per kernel group."""
+        return self._kernel_groups
+
+    @property
+    def num_kernel_groups(self) -> int:
+        """Number of :class:`KernelGroupInfo` entries.
+
+        Zero if ``kv_caches`` had no layers at construction time.
+        """
+        return len(self._kernel_groups)
+
+    @property
+    def object_groups(self) -> list[ObjectGroupInfo]:
+        """List of :class:`ObjectGroupInfo`, one per object group."""
+        return self._object_groups
+
+    @property
+    def num_object_groups(self) -> int:
+        """Number of :class:`ObjectGroupInfo` entries."""
+        return len(self._object_groups)
+
+    @property
+    @lmcache_deprecate("`num_groups` is an outdated alias for `num_kernel_groups`")
+    def num_groups(self) -> int:
+        """Number of :class:`KernelGroupInfo` entries.
+
+        Zero if ``kv_caches`` had no layers at construction time.
+        """
+        return len(self._kernel_groups)
+
+    def get_shape_desc(self, kernel_group_idx: int) -> "lmc_ops.PageBufferShapeDesc":
+        """Return the :class:`PageBufferShapeDesc` for *kernel_group_idx*.
+
+        Args:
+            kernel_group_idx: 0-based kernel group index.
+
+        Raises:
+            IndexError: If *kernel_group_idx* is out of range.
+        """
+        return self._kernel_groups[kernel_group_idx].shape_desc
+
+    @lmcache_deprecate("It does not have hybrid model support")
+    def get_slots_per_chunk(self, kernel_group_idx: int) -> int:
+        """Return the per-chunk slot count for *kernel_group_idx*.
+
+        Args:
+            kernel_group_idx: 0-based kernel group index.
+
+        Note:
+            This is a deprecated function because it does not have
+            hybrid model support
+        """
+        group = self._kernel_groups[kernel_group_idx]
+        return group.calculate_slots(self._lmcache_tokens_per_chunk)
+
+    def get_slots_per_chunk_in_sw(self, kernel_group_idx: int) -> int:
+        """Return the per-chunk *transfer* slot count for *kernel_group_idx*.
+
+        For sub-chunk sliding window groups, the transfer slots is smaller
+        than the physical slots in a chunk.
+
+        Args:
+            kernel_group_idx: 0-based kernel group index.
+        """
+        group = self._kernel_groups[kernel_group_idx]
+        sw_size = self.get_subchunk_sw_size_tokens(kernel_group_idx)
+        return group.calculate_slots(sw_size)
+
+    def enable_full_sw_kv(self) -> None:
+        """Store/transfer the FULL per-chunk KV for sliding-window groups.
+
+        Keeps every block so a chunk stays valid when reused at any position
+        (default windowing keeps only each chunk's last sub-chunk window).
+        """
+        self._full_sw_kv = True
+
+    def get_subchunk_sw_size_tokens(self, kernel_group_idx: int) -> int:
+        """Return the sub-chunk sliding window size of a given kernel group.
+        The size is measured in the number of tokens.
+
+        This is for the models like DSV4 where the sliding window size is
+        smaller than the tokens in a single lmcache chunk.
+
+        Args:
+            kernel_group_idx: 0-based kernel group index.
+
+        Returns:
+            The sub-chunk sliding window size. Will be the same as the
+            chunk size for non-slding-window models or big-sliding-
+            window models.
+        """
+        sw_size_tokens = self._kernel_groups[kernel_group_idx].sw_size_tokens
+        # full_sw_kv: report the full chunk as the window so store/transfer keep
+        # every block (chunk stays valid for reuse at any position).
+        if self._full_sw_kv:
+            return self._lmcache_tokens_per_chunk
+        if sw_size_tokens == -1 or sw_size_tokens >= self._lmcache_tokens_per_chunk:
+            return self._lmcache_tokens_per_chunk
+        return sw_size_tokens
+
+    def get_attn_desc(self) -> AttnWindowDesc:
+        """Return the cross-chunk attention windows of all object groups.
+
+        Returns:
+            An :class:`AttnWindowDesc` with one entry per object group, in
+            object-group order; the entry is ``-1`` for a non-sliding-window
+            group.
+
+        Note:
+            With object-group separation disabled (the default), the result
+            has a single full-attention entry.
+        """
+        if self._full_sw_kv:
+            # full_sw_kv: every group reports full attention, no cross-chunk
+            # window skipping (mirrors get_subchunk_sw_size_tokens).
+            return AttnWindowDesc(num_chunks_in_sw=[-1] * len(self._object_groups))
+        return AttnWindowDesc(
+            num_chunks_in_sw=[
+                w if w >= 1 else -1
+                for w in (g.sw_size_chunks for g in self._object_groups)
+            ]
+        )
+
+    def calculate_num_blocks(self, kernel_group_idx: int, num_tokens: int) -> int:
+        """Calculate the number of blocks for a given number of tokens in a
+        specified kernel group.
+
+        Args:
+            kernel_group_idx: 0-based index of the kernel group.
+            num_tokens: The total number of tokens to be processed for the group.
+
+        Returns:
+            The number of blocks.
+
+        Raises:
+            IndexError: If *kernel_group_idx* is out of range.
+        """
+        group = self._kernel_groups[kernel_group_idx]
+        # Physical slots for num_tokens, derived from the per-block geometry
+        # (slots_per_block / tokens_per_block) rather than a compress ratio.
+        num_physical_slots = (
+            num_tokens * group.slots_per_block // group.tokens_per_block
+        )
+        return num_physical_slots // group.shape_desc.bs
+
+    ### Helper methods
+    def _detect_object_groups(
+        self, engine_group_infos: "Sequence[EngineGroupInfo]"
+    ) -> list[ObjectGroupInfo]:
+        """Bucket kernel groups into object groups.
+
+        Puts all kernel groups into a single object group when object-group
+        separation is disabled (the default). Otherwise groups the kernel groups
+        by sliding-window size measured in number of chunks.
+
+        Args:
+            engine_group_infos: LMCache-owned engine KV cache group metadata.
+
+        Returns:
+            One :class:`ObjectGroupInfo` per object group.
+        """
+        if not self._separate_object_groups:
+            return [
+                ObjectGroupInfo(
+                    kernel_group_indices=list(range(len(self._kernel_groups)))
+                )
+            ]
+
+        chunk_size = self._lmcache_tokens_per_chunk
+        groups_by_sw_size: dict[int, list[int]] = defaultdict(list)
+        for kernel_group_idx, group in enumerate(self._kernel_groups):
+            if group.sw_size_tokens == -1:
+                sw_size_chunks = -1
+            else:
+                sw_size_chunks = (group.sw_size_tokens + chunk_size - 1) // chunk_size
+            groups_by_sw_size[sw_size_chunks].append(kernel_group_idx)
+        return [
+            ObjectGroupInfo(
+                kernel_group_indices=kernel_group_indices,
+                sw_size_chunks=sw_size_chunks,
+            )
+            for sw_size_chunks, kernel_group_indices in sorted(
+                groups_by_sw_size.items(), key=lambda kv: kv[1][0]
+            )
+        ]
+
+    @staticmethod
+    def _validate_block_chunk_size_config(
+        group_idx: int,
+        slots_per_block: int,
+        tokens_per_block: int,
+        lmcache_tokens_per_chunk: int,
+        sw_size_tokens: int = -1,
+    ) -> None:
+        """Validate the chunk size configuration against the slot and
+        tokens block detected from the serving engine.
+
+        Raises:
+            ValueError: If one of the following conditions is met:
+                - ``tokens_per_block`` is not a whole multiple of
+                  ``slots_per_block``
+                - ``lmcache_tokens_per_chunk`` is not a whole multiple of
+                  ``tokens_per_block``
+                - a sub-chunk sliding window is not a whole multiple of
+                  ``tokens_per_block``
+        """
+        if tokens_per_block % slots_per_block != 0:
+            raise ValueError(
+                f"group {group_idx}: tokens_per_block {tokens_per_block} "
+                f"must be a multiple of slots_per_block {slots_per_block}"
+            )
+        if lmcache_tokens_per_chunk % tokens_per_block != 0:
+            raise ValueError(
+                f"group {group_idx}: lmcache_tokens_per_chunk "
+                f"{lmcache_tokens_per_chunk} must be a multiple of "
+                f"tokens_per_block {tokens_per_block}"
+            )
+        if (
+            0 < sw_size_tokens < lmcache_tokens_per_chunk
+            and sw_size_tokens % tokens_per_block != 0
+        ):
+            raise ValueError(
+                f"group {group_idx}: sub-chunk sliding window size "
+                f"{sw_size_tokens} must be a multiple of tokens_per_block "
+                f"{tokens_per_block}"
+            )
+        if slots_per_block != tokens_per_block:
+            logger.info(
+                "group %d: compressed (tokens_per_block=%d, slots_per_block=%d)",
+                group_idx,
+                tokens_per_block,
+                slots_per_block,
+            )
+
+
+# ------------------------------------------------------------------ #
+#  CLI shape-spec parser                                               #
+# ------------------------------------------------------------------ #
+
+
+def parse_kvcache_shape_spec(
+    spec_str: str,
+) -> list[KernelGroupInfo]:
+    """Parse a ``--kvcache-shape-spec`` string into layer groups.
+
+    **Grammar** (EBNF-ish)::
+
+        spec        := group { ";" group }
+        group       := "(" shape ")" ":" dtype ":" layer_count
+        shape       := kv_size "," NB "," BS "," NH "," HS
+        dtype       := "float16" | "float32" | "bfloat16" | "uint8"
+        layer_count := positive integer
+
+    **Field semantics** (names aligned with ``EngineKVFormat``; see
+    :func:`lmcache.v1.gpu_connector.utils.get_engine_kv_shape_description`):
+
+    * ``kv_size`` -- leading dim (``2`` for standard K/V, ``1`` for MLA).
+    * ``NB`` -- ``num_blocks``: paged-KV block count.
+    * ``BS`` -- ``block_size``: tokens per paged-KV block.
+    * ``NH`` -- ``num_heads``: attention heads per layer.
+    * ``HS`` -- ``head_size``: per-head hidden dim.
+    * ``dtype`` -- element dtype (case-insensitive). ``uint8`` is used
+      by FP8-quantized layouts.
+    * ``layer_count`` -- number of consecutive layers sharing this
+      group's geometry. Groups are concatenated in declaration order;
+      ``layer_indices`` are assigned sequentially starting from 0.
+
+    When consumed by the ``lmcache bench server`` CLI, ``NB``/``BS``
+    from the spec take precedence over ``--num-blocks`` / ``--block-size``
+    CLI flags when set to a positive value.
+
+    **Examples**::
+
+        # Single homogeneous group: 32 layers of standard K/V
+        (2,1024,16,8,128):float16:32
+
+        # Heterogeneous model: 30 dense layers + 2 MLA-ish layers
+        (2,1024,16,8,128):float16:30;(1,1024,16,4,64):bfloat16:2
+
+        # FP8-quantized KV cache
+        (2,1024,16,8,128):uint8:32
+
+    See also :func:`format_kvcache_shape_spec` for the inverse -- it
+    turns a parsed group list back into a human-readable spec string
+    (handy for CLI echo-back / debug logging).
+
+    Returns:
+        A list of :class:`KernelGroupInfo`, one per group.
+
+    Raises:
+        ValueError: Malformed spec, unknown dtype, or a shape with a
+            wrong number of dimensions.
+    """
+    if not spec_str:
+        raise ValueError("KV shape specification cannot be empty")
+
+    groups: list[KernelGroupInfo] = []
+    layer_offset = 0
+
+    for group_spec in spec_str.split(";"):
+        group_spec = group_spec.strip()
+        if not group_spec:
+            continue
+
+        if not (group_spec.startswith("(") and "):" in group_spec):
+            raise ValueError("Invalid group spec format: %s" % group_spec)
+
+        shape_end = group_spec.find(")")
+        shape_str = group_spec[1:shape_end]
+
+        remaining = group_spec[shape_end + 2 :]  # Skip "):"
+        parts = remaining.split(":")
+        if len(parts) != 2:
+            raise ValueError("Invalid group spec format: %s" % group_spec)
+
+        dtype_str = parts[0].strip()
+        layer_count_str = parts[1].strip()
+
+        dtype_key = dtype_str.lower()
+        if dtype_key not in DTYPE_MAP:
+            raise ValueError(
+                "Unrecognized dtype '%s' in group spec: %s. "
+                "Supported: %s" % (dtype_str, group_spec, list(DTYPE_MAP.keys()))
+            )
+        try:
+            shape = tuple(int(p.strip()) for p in shape_str.split(","))
+            layer_count = int(layer_count_str)
+        except ValueError as exc:
+            raise ValueError("Invalid number in group spec: %s" % group_spec) from exc
+        dtype = DTYPE_MAP[dtype_key]
+
+        if len(shape) != 5:
+            raise ValueError(
+                "Shape must be a 5-tuple (kv_size,nb,bs,nh,hs): %s" % group_spec
+            )
+        kv_size, nb, bs, nh, hs = shape
+        shape_desc = lmc_ops.PageBufferShapeDesc()
+        shape_desc.kv_size = kv_size
+        shape_desc.nl = layer_count
+        shape_desc.nb = nb
+        shape_desc.bs = bs
+        shape_desc.nh = nh
+        shape_desc.hs = hs
+        shape_desc.element_size = dtype.itemsize
+        set_shape_desc_dtype(shape_desc, dtype)
+
+        indices = list(range(layer_offset, layer_offset + layer_count))
+        groups.append(
+            KernelGroupInfo(
+                layer_indices=indices,
+                shape_desc=shape_desc,
+                dtype=dtype,
+            )
+        )
+        layer_offset += layer_count
+
+    if not groups:
+        raise ValueError("No valid layer groups found in spec")
+
+    return groups
+
+
+def format_kvcache_shape_spec(groups: list[KernelGroupInfo]) -> str:
+    """Format layer groups back into a ``--kvcache-shape-spec`` string.
+
+    This is the inverse of :func:`parse_kvcache_shape_spec`; the
+    result is round-trip safe (i.e. ``parse(format(x)) == x`` for any
+    ``x`` that ``parse`` would produce).
+
+    The returned string is also human-readable and is used by the
+    ``lmcache bench server`` CLI to echo the resolved KV cache
+    geometry at startup, so operators can verify that their spec was
+    interpreted as intended.
+
+    Example::
+
+        >>> groups = parse_kvcache_shape_spec(
+        ...     "(2,1024,16,8,128):float16:30;"
+        ...     "(1,1024,16,4,64):bfloat16:2"
+        ... )
+        >>> format_kvcache_shape_spec(groups)
+        '(2,1024,16,8,128):float16:30;(1,1024,16,4,64):bfloat16:2'
+
+    Args:
+        groups: Layer groups as returned by
+            :func:`parse_kvcache_shape_spec`.
+
+    Raises:
+        ValueError: If *groups* is empty or contains an unsupported
+            dtype (one that is not present in :data:`DTYPE_MAP`).
+    """
+    if not groups:
+        raise ValueError("Cannot format an empty layer group list")
+
+    # Invert DTYPE_MAP once: torch.dtype -> canonical string name.
+    dtype_names = {v: k for k, v in DTYPE_MAP.items()}
+
+    parts: list[str] = []
+    for g in groups:
+        sd = g.shape_desc
+        try:
+            dtype_str = dtype_names[g.dtype]
+        except KeyError as exc:
+            raise ValueError("dtype %s is not present in DTYPE_MAP" % g.dtype) from exc
+        parts.append(
+            "(%d,%d,%d,%d,%d):%s:%d"
+            % (sd.kv_size, sd.nb, sd.bs, sd.nh, sd.hs, dtype_str, sd.nl)
+        )
+    return ";".join(parts)
diff --git a/lmcache/v1/lookup_client/__init__.py b/lmcache/v1/lookup_client/__init__.py
new file mode 100644
index 0000000..2c11647
--- /dev/null
+++ b/lmcache/v1/lookup_client/__init__.py
@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.chunk_statistics_lookup_client import (
+    ChunkStatisticsLookupClient,
+)
+from lmcache.v1.lookup_client.factory import LookupClientFactory
+from lmcache.v1.lookup_client.lmcache_lookup_client import (
+    LMCacheLookupClient,
+    LMCacheLookupServer,
+)
+from lmcache.v1.lookup_client.lmcache_lookup_client_bypass import (
+    LMCacheBypassLookupClient,
+)
+from lmcache.v1.lookup_client.mooncake_lookup_client import MooncakeLookupClient
+
+__all__ = [
+    "LookupClientInterface",
+    "LookupClientFactory",
+    "MooncakeLookupClient",
+    "LMCacheBypassLookupClient",
+    "LMCacheLookupClient",
+    "LMCacheLookupServer",
+    "ChunkStatisticsLookupClient",
+]
diff --git a/lmcache/v1/lookup_client/abstract_client.py b/lmcache/v1/lookup_client/abstract_client.py
new file mode 100644
index 0000000..96a1b6e
--- /dev/null
+++ b/lmcache/v1/lookup_client/abstract_client.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+import abc
+
+# Third Party
+import torch
+
+
+class LookupClientInterface(metaclass=abc.ABCMeta):
+    """Abstract interface for lookup clients."""
+
+    def lookup_cache(self, lookup_id: str) -> Optional[int]:
+        """
+        Lookup the cache for the given lookup ID.
+
+        Args:
+            lookup_id: The lookup ID to lookup
+
+        Returns:
+            -1 means not found;
+            None means ongoing; (this semantic is not supported in sync lookup clients)
+            int >= 0 means number of hit tokens
+        """
+        return None
+
+    @abc.abstractmethod
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        """
+        Perform lookup for the given token IDs.
+        Should be called for first lookup and pinning. Subsequent lookups for the same
+        request should call lookup_cache instead.
+
+        Caller should handle overlaps between tokens that exist in LMCache
+        and tokens that are already computed by the caller.
+
+        Args:
+            token_ids: The token IDs to lookup
+
+            lookup_id: The lookup ID to associate with the lookup
+
+            request_configs: The configs of the request,
+            includes tags and the other configs
+
+        Returns:
+            The number of tokens that exist inside LMCache.
+            None indicates the lookup/prefetch is in progress.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close the lookup client and clean up resources."""
+        raise NotImplementedError
+
+    def supports_producer_reuse(self) -> bool:
+        """
+        Return whether this lookup client supports producer KV cache reuse.
+
+        Returns:
+            True if producer reuse is supported, False otherwise
+        """
+        return False
+
+    def clear_lookup_status(self, lookup_id: str) -> None:
+        """
+        Clear temporary lookup status for a given lookup ID.
+
+        Args:
+            lookup_id: The lookup ID whose status needs to be cleared.
+        """
+        return
diff --git a/lmcache/v1/lookup_client/async_lookup_message.py b/lmcache/v1/lookup_client/async_lookup_message.py
new file mode 100644
index 0000000..0f960b1
--- /dev/null
+++ b/lmcache/v1/lookup_client/async_lookup_message.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict, Optional
+
+# Third Party
+import msgspec
+
+
+class AsyncLookupMsg(msgspec.Struct, tag=True):  # type: ignore
+    """Base class for async lookup messages"""
+
+    def describe(self) -> str:
+        return ""
+
+
+class LookupRequestMsg(AsyncLookupMsg):
+    """Async lookup request message from scheduler to worker"""
+
+    lookup_id: str
+    hashes: list[int]
+    offsets: list[int]
+    request_configs: Optional[Dict[str, str]] = None
+
+    def describe(self) -> str:
+        return (
+            f"Async lookup request for lookup_id={self.lookup_id} "
+            f"with {len(self.hashes)} hashes"
+        )
+
+
+class LookupResponseMsg(AsyncLookupMsg):
+    """Async lookup response message from worker to scheduler"""
+
+    lookup_id: str
+    num_hit_tokens: int
+
+    def describe(self) -> str:
+        return (
+            f"Async lookup response for lookup_id={self.lookup_id} "
+            f"with {self.num_hit_tokens} hit tokens"
+        )
+
+
+class LookupCleanupMsg(AsyncLookupMsg):
+    """Cleanup message from scheduler to worker to release memory objects"""
+
+    lookup_id: str
+
+    def describe(self) -> str:
+        return f"Cleanup memory for lookup_id={self.lookup_id}"
diff --git a/lmcache/v1/lookup_client/chunk_statistics_lookup_client.py b/lmcache/v1/lookup_client/chunk_statistics_lookup_client.py
new file mode 100644
index 0000000..4879e45
--- /dev/null
+++ b/lmcache/v1/lookup_client/chunk_statistics_lookup_client.py
@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Optional, Union
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import PrometheusLogger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.record_strategies import (
+    AsyncRecorder,
+    RecordStrategy,
+    create_record_strategy,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+class ChunkStatisticsLookupClient(LookupClientInterface):
+    """Wrapper client that tracks chunk reuse statistics."""
+
+    def __init__(
+        self,
+        actual_lookup_client: LookupClientInterface,
+        config: LMCacheEngineConfig,
+        metadata: Optional[LMCacheMetadata] = None,
+    ) -> None:
+        self.actual_lookup_client = actual_lookup_client
+        self.config = config
+        self.metadata = metadata
+        self.lock = threading.RLock()
+        self.chunk_size = config.chunk_size
+        self.enabled = False
+        self.request_seen: set[str] = set()
+        self.lookup_time = 0.0
+        self.record_time = 0.0
+        self.check_exit_time = 0.0
+        self.statistics_start_time = 0.0
+        self.timeout_hours = config.chunk_statistics_auto_exit_timeout_hours
+        self.target_unique_chunks = (
+            config.chunk_statistics_auto_exit_target_unique_chunks
+        )
+        self.enable_auto_exit = (
+            self.timeout_hours > 0.0 or self.target_unique_chunks > 0
+        )
+        strategy: RecordStrategy = create_record_strategy(config)
+        self.recorder = AsyncRecorder(
+            strategy=strategy,
+            queue_capacity=config.get_extra_config_value(
+                "chunk_statistics_async_queue_capacity", 100000
+            ),
+            preprocess_in_caller=config.get_extra_config_value(
+                "chunk_statistics_async_preprocess_chunks", False
+            ),
+        )
+        self._setup_metrics()
+        if config.chunk_statistics_auto_start_statistics:
+            self.start_statistics()
+
+    def lookup_cache(self, lookup_id: str) -> Optional[int]:
+        return self.actual_lookup_client.lookup_cache(lookup_id)
+
+    def start_statistics(self) -> None:
+        with self.lock:
+            self.enabled = True
+            # Assign the start time while first recording
+            self.statistics_start_time = 0.0
+
+    def stop_statistics(self) -> None:
+        with self.lock:
+            self.enabled = False
+
+    def reset_statistics(self) -> None:
+        self.recorder.wait_for_completion(timeout=5.0)
+        with self.lock:
+            self.request_seen.clear()
+            self.recorder.reset()
+
+    def get_statistics(self) -> dict:
+        self.recorder.wait_for_completion(timeout=5.0)
+        with self.lock:
+            strategy_stats = self.recorder.get_statistics()
+            total_time = self.lookup_time + self.record_time + self.check_exit_time
+            overhead_time = self.record_time + self.check_exit_time
+            overhead_pct = (
+                (overhead_time / total_time * 100.0) if total_time > 0 else 0.0
+            )
+            result = {
+                "enabled": self.enabled,
+                "total_requests": len(self.request_seen),
+                "timing": {
+                    "lookup_time_seconds": self.lookup_time,
+                    "record_statistics_time_seconds": self.record_time,
+                    "check_exit_conditions_time_seconds": self.check_exit_time,
+                    "total_time_seconds": total_time,
+                    "overhead_time_seconds": overhead_time,
+                    "overhead_percentage": overhead_pct,
+                },
+                "total_chunks": strategy_stats.get("total_chunks", 0),
+                "unique_chunks": strategy_stats.get("unique_chunks", 0),
+                "duplicate_chunks": strategy_stats.get("duplicate_chunks", 0),
+                "reuse_rate": strategy_stats.get("reuse_rate", 0.0),
+                **{
+                    k: v
+                    for k, v in strategy_stats.items()
+                    if k in ("bloom_filter", "async_queue", "file_hash")
+                },
+            }
+            return result
+
+    def wait_for_async_processing(self, timeout: float = 5.0) -> bool:
+        return self.recorder.wait_for_completion(timeout)
+
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        start_time = time.time()
+        result = self.actual_lookup_client.lookup(
+            token_ids,
+            lookup_id,
+            request_configs,
+        )
+        lookup_elapsed = time.time() - start_time
+        with self.lock:
+            self.lookup_time += lookup_elapsed
+
+        if not self.enabled:
+            return result
+
+        with self.lock:
+            if lookup_id in self.request_seen:
+                return result
+            self.request_seen.add(lookup_id)
+
+        start_time = time.time()
+        self.recorder.record_async(token_ids, lookup_id)
+        record_elapsed = time.time() - start_time
+        with self.lock:
+            self.record_time += record_elapsed
+
+        start_time = time.time()
+        self._check_exit_conditions()
+        check_elapsed = time.time() - start_time
+        with self.lock:
+            self.check_exit_time += check_elapsed
+
+        return result
+
+    def clear_lookup_status(self, lookup_id: str) -> None:
+        self.actual_lookup_client.clear_lookup_status(lookup_id)
+
+    def supports_producer_reuse(self) -> bool:
+        return self.actual_lookup_client.supports_producer_reuse()
+
+    def close(self) -> None:
+        if self.enabled:
+            self.stop_statistics()
+        self.recorder.close()
+        self.actual_lookup_client.close()
+
+    def _check_exit_conditions(self) -> None:
+        if not self.enable_auto_exit:
+            return
+        if self.statistics_start_time == 0.0:
+            self.statistics_start_time = time.time()
+        stop_reason = None
+        if self.timeout_hours > 0.0:
+            elapsed_hours = (time.time() - self.statistics_start_time) / 3600.0
+            if elapsed_hours >= self.timeout_hours:
+                stop_reason = (
+                    f"Timeout: {elapsed_hours:.2f}h >= {self.timeout_hours:.2f}h"
+                )
+        if self.target_unique_chunks > 0:
+            unique = self.recorder.strategy.unique_chunks_count
+            if unique >= self.target_unique_chunks:
+                stop_reason = f"Target reached: {unique} >= {self.target_unique_chunks}"
+        if stop_reason:
+            self._trigger_stop(stop_reason)
+
+    def _trigger_stop(self, reason: str) -> None:
+        logger.warning("Auto-stop: %s", reason)
+        if self.enabled:
+            self.stop_statistics()
+
+    def _setup_metrics(self) -> None:
+        if self.metadata is None:
+            return
+
+        prometheus_logger = PrometheusLogger.GetOrCreate(
+            self.metadata,
+            config=self.config,
+        )
+        prometheus_logger.chunk_statistics_enabled.set_function(
+            lambda: 1.0 if self.enabled else 0.0
+        )
+        prometheus_logger.chunk_statistics_total_requests.set_function(
+            lambda: len(self.request_seen)
+        )
+        self.recorder.strategy.setup_metrics(prometheus_logger)
diff --git a/lmcache/v1/lookup_client/factory.py b/lmcache/v1/lookup_client/factory.py
new file mode 100644
index 0000000..ef10c0f
--- /dev/null
+++ b/lmcache/v1/lookup_client/factory.py
@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, Optional, Union
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.chunk_statistics_lookup_client import (
+    ChunkStatisticsLookupClient,
+)
+from lmcache.v1.lookup_client.hit_limit_lookup_client import HitLimitLookupClient
+from lmcache.v1.lookup_client.lmcache_lookup_client_bypass import (
+    LMCacheBypassLookupClient,
+)
+from lmcache.v1.lookup_client.mooncake_lookup_client import MooncakeLookupClient
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc.zmq_transport import (
+    SocketParams,
+    ZmqReqRepClientTransport,
+    ZmqRouterServerTransport,
+)
+from lmcache.v1.rpc_utils import get_zmq_rpc_path_lmcache
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+        LMCacheAsyncLookupServer,
+    )
+    from lmcache.v1.lookup_client.lmcache_lookup_client import LMCacheLookupServer
+
+logger = init_logger(__name__)
+
+
+class LookupClientFactory:
+    """Factory for creating lookup clients and servers based on configuration."""
+
+    @staticmethod
+    def create_lookup_client(
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        lmcache_engine: Optional[LMCacheEngine] = None,
+    ) -> LookupClientInterface:
+        """
+        Create a lookup client based on the configuration.
+
+        Args:
+            config: The LMCache engine configuration
+            metadata: The LMCache engine metadata (includes engine_id,
+                world_size, kv_connector_extra_config)
+            lmcache_engine: Optional LMCacheEngine instance for
+                bypass lookup client
+
+        Returns:
+            A lookup client instance
+        """
+
+        client: LookupClientInterface
+        # Check if external_lookup_client is configured
+        if config.external_lookup_client is not None:
+            if config.enable_async_loading:
+                raise ValueError(
+                    "Asynchronous loading is not supported for external lookup clients."
+                )
+            client = LookupClientFactory._create_external_lookup_client(
+                config.external_lookup_client, config, metadata
+            )
+        else:
+            # First Party
+            from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+                LMCacheAsyncLookupClient,
+            )
+            from lmcache.v1.lookup_client.lmcache_lookup_client import (
+                LMCacheLookupClient,
+            )
+
+            # Check if bypass lookup is enabled and lmcache_engine is provided
+            if config.enable_scheduler_bypass_lookup and lmcache_engine is not None:
+                client = LMCacheBypassLookupClient(config, metadata, lmcache_engine)
+            elif config.enable_async_loading:
+                client = LMCacheAsyncLookupClient(config, metadata)
+            else:
+                transport = LookupClientFactory._create_zmq_client_transport(
+                    config, metadata
+                )
+                client = LMCacheLookupClient(config, metadata, transport)
+
+        if config.hit_miss_ratio is not None and 0 <= config.hit_miss_ratio <= 1:
+            client = HitLimitLookupClient(client, config)
+
+        # Wrap with ChunkStatisticsLookupClient if enabled
+        if config.enable_chunk_statistics:
+            client = ChunkStatisticsLookupClient(
+                client,
+                config,
+                metadata,
+            )
+        return client
+
+    @staticmethod
+    def create_lookup_server(
+        lmcache_engine: LMCacheEngine,
+        metadata: LMCacheMetadata,
+    ) -> Optional[Union["LMCacheLookupServer", "LMCacheAsyncLookupServer"]]:
+        """
+        Create a lookup server based on the configuration.
+
+        Args:
+            lmcache_engine: The LMCache engine instance
+            metadata: The LMCache engine metadata (includes engine_id,
+                world_size, kv_connector_extra_config, worker_id)
+
+        Returns:
+            A lookup server instance, or None if no server should be created
+        """
+        config = lmcache_engine.config
+        assert isinstance(config, LMCacheEngineConfig), (
+            "LMCache v1 config is expected for lookup server and client"
+        )
+
+        lookup_server_worker_ids = config.get_lookup_server_worker_ids(
+            metadata.use_mla, metadata.world_size
+        )
+
+        if config.external_lookup_client is None and (
+            len(lookup_server_worker_ids) == 0
+            or metadata.worker_id in lookup_server_worker_ids
+        ):
+            # First Party
+            from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+                LMCacheAsyncLookupServer,
+            )
+            from lmcache.v1.lookup_client.lmcache_lookup_client import (
+                LMCacheLookupServer,
+            )
+
+            if config.enable_async_loading:
+                return LMCacheAsyncLookupServer(lmcache_engine, metadata)
+            else:
+                transport = LookupClientFactory._create_zmq_server_transport(metadata)
+                return LMCacheLookupServer(lmcache_engine, metadata, transport)
+
+        return None
+
+    @staticmethod
+    def _create_external_lookup_client(
+        external_lookup_uri: str,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ) -> LookupClientInterface:
+        """
+        Create an external lookup client based on the URI format.
+
+        Args:
+            external_lookup_uri: URI in format <scheme>://<address>
+            config: The LMCache engine configuration
+            metadata: The LMCache engine metadata
+
+        Returns:
+            A lookup client instance
+
+        Raises:
+            ValueError: If the URI format is unsupported
+        """
+        # Parse URI scheme and address
+        if "://" not in external_lookup_uri:
+            raise ValueError(
+                f"Invalid external lookup client URI format: {external_lookup_uri}. "
+                "Expected format: <scheme>://<address>"
+            )
+
+        scheme, address = external_lookup_uri.split("://", 1)
+
+        # Route to appropriate client based on scheme
+        if scheme == "mooncakestore":
+            return LookupClientFactory._create_mooncake_lookup_client(
+                address, config, metadata
+            )
+        else:
+            raise ValueError(
+                f"Unsupported external lookup client scheme: {scheme}. "
+                "Supported schemes: mooncakestore"
+            )
+
+    @staticmethod
+    def _create_mooncake_lookup_client(
+        master_address: str,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ) -> "MooncakeLookupClient":
+        """Create a MooncakeLookupClient instance."""
+        return MooncakeLookupClient(config, metadata, master_address)
+
+    @staticmethod
+    def _create_zmq_client_transport(
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ) -> ZmqReqRepClientTransport:
+        """Create a ZMQ REQ-REP client transport."""
+        kv_extra = metadata.kv_connector_extra_config or {}
+        rpc_port = kv_extra.get("lmcache_rpc_port", 0)
+        assert metadata.engine_id is not None, (
+            "engine_id is required for RPC communication"
+        )
+
+        lookup_ids = config.get_lookup_server_worker_ids(
+            metadata.use_mla, metadata.world_size
+        )
+        ranks = lookup_ids if len(lookup_ids) > 0 else list(range(metadata.world_size))
+
+        socket_params = [
+            SocketParams(
+                socket_path=get_zmq_rpc_path_lmcache(
+                    metadata.engine_id,
+                    "lookup",
+                    rpc_port,
+                    rank,
+                ),
+                rank=rank,
+            )
+            for rank in ranks
+        ]
+        return ZmqReqRepClientTransport(
+            socket_params=socket_params,
+            timeout_ms=config.lookup_timeout_ms,
+        )
+
+    @staticmethod
+    def _create_zmq_server_transport(
+        metadata: LMCacheMetadata,
+    ) -> ZmqRouterServerTransport:
+        """Create a ZMQ ROUTER server transport."""
+        kv_extra = metadata.kv_connector_extra_config or {}
+        rpc_port = kv_extra.get("lmcache_rpc_port", 0)
+        assert metadata.engine_id is not None, (
+            "engine_id is required for RPC communication"
+        )
+        socket_path = get_zmq_rpc_path_lmcache(
+            metadata.engine_id,
+            "lookup",
+            rpc_port,
+            metadata.worker_id,
+        )
+        return ZmqRouterServerTransport(
+            socket_path=socket_path,
+        )
diff --git a/lmcache/v1/lookup_client/hit_limit_lookup_client.py b/lmcache/v1/lookup_client/hit_limit_lookup_client.py
new file mode 100644
index 0000000..1a39b61
--- /dev/null
+++ b/lmcache/v1/lookup_client/hit_limit_lookup_client.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+
+logger = init_logger(__name__)
+
+
+"""
+HitLimitLookupClient now is used for test, when lookup is called, cal the cache hit,
+- if the cache hit <= (1 - hit_miss_ratio), direct return the result
+- if the cache hit > (1 - hit_miss_ratio), re-compute the result by hit_miss_ratio
+"""
+
+
+class HitLimitLookupClient(LookupClientInterface):
+    def __init__(
+        self, actual_lookup_client: LookupClientInterface, config: LMCacheEngineConfig
+    ):
+        assert config.hit_miss_ratio is not None and 0 <= config.hit_miss_ratio <= 1
+        self.actual_lookup_client = actual_lookup_client
+        self.config = config
+        logger.info(
+            "create HitLimitLookupClient succeed, "
+            "the hit ratio upper is %s, chunk size is %s",
+            1 - config.hit_miss_ratio,
+            config.chunk_size,
+        )
+
+    def lookup_cache(self, lookup_id: str) -> Optional[int]:
+        return self.actual_lookup_client.lookup_cache(lookup_id)
+
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        # get real hit tokens
+        result = self.actual_lookup_client.lookup(
+            token_ids,
+            lookup_id,
+            request_configs,
+        )
+        if result is not None:
+            total_tokens_length = len(token_ids)
+            assert result <= total_tokens_length
+            current_hit_ratio = 0.0
+            if total_tokens_length > 0:
+                current_hit_ratio = result / total_tokens_length
+            # limit the hit tokens
+            hit_ratio_upper = 1 - self.config.hit_miss_ratio
+            if current_hit_ratio > hit_ratio_upper:
+                origin_result = result
+                # align to chunk size
+                chunk_size = self.config.chunk_size
+                new_result = (
+                    int(total_tokens_length * hit_ratio_upper)
+                    // chunk_size
+                    * chunk_size
+                )
+                # check again
+                result = min(result, new_result)
+                logger.debug(
+                    f"hit ratio upper: {hit_ratio_upper} is smaller than "
+                    f"the real hit ratio {current_hit_ratio}, "
+                    f"the origin result is {origin_result}, "
+                    f"the new result is {new_result}, the final result is {result}"
+                )
+        return result
+
+    def clear_lookup_status(self, lookup_id: str) -> None:
+        self.actual_lookup_client.clear_lookup_status(lookup_id)
+
+    def supports_producer_reuse(self) -> bool:
+        return self.actual_lookup_client.supports_producer_reuse()
+
+    def close(self) -> None:
+        self.actual_lookup_client.close()
diff --git a/lmcache/v1/lookup_client/lmcache_async_lookup_client.py b/lmcache/v1/lookup_client/lmcache_async_lookup_client.py
new file mode 100644
index 0000000..df9ca6a
--- /dev/null
+++ b/lmcache/v1/lookup_client/lmcache_async_lookup_client.py
@@ -0,0 +1,407 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+import threading
+import time
+
+# Third Party
+import msgspec
+import torch
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.async_lookup_message import (
+    LookupCleanupMsg,
+    LookupRequestMsg,
+    LookupResponseMsg,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc_utils import (
+    get_zmq_context,
+    get_zmq_rpc_path_lmcache,
+    get_zmq_socket,
+)
+
+logger = init_logger(__name__)
+
+
+# NOTE(Jiayi): Prefetch could load extra redundant cache if multiple
+# workers has different hit tokens.
+class LMCacheAsyncLookupClient(LookupClientInterface):
+    """
+    ZMQ-based lookup client that communicates with a lookup server.
+
+    Related extra_config:
+    - lookup_server_worker_ids:
+        is a config to control create lookup server on some workers.
+        if mla is not enabled, default is [];
+        if mla is enabled, default is [0];
+        - if lookup_server_worker_ids is [], start lookup server on all workers
+        - if lookup_server_worker_ids is [0], start lookup server on worker0
+        - if lookup_server_worker_ids is [0, 3, 6], start lookup server on
+          worker0, worker3 and worker6
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ):
+        # lookup_id -> first lookup time
+        # this helps us support timeout semantics
+        self.first_lookup_time: dict[str, float] = {}
+        self.config = config
+
+        self.ctx = get_zmq_context(use_asyncio=False)
+        kv_connector_extra_config = metadata.kv_connector_extra_config or {}
+        rpc_port = kv_connector_extra_config.get("lmcache_rpc_port", 0)
+        engine_id = metadata.engine_id
+        assert engine_id is not None, "engine_id is required for RPC communication"
+        self.world_size = metadata.world_size
+        self.lookup_server_worker_ids = config.get_lookup_server_worker_ids(
+            metadata.use_mla, metadata.world_size
+        )
+
+        self.push_sockets = []
+        if len(self.lookup_server_worker_ids) > 0:
+            ranks = self.lookup_server_worker_ids
+            self.world_size = len(self.lookup_server_worker_ids)
+        else:
+            ranks = [i for i in range(self.world_size)]
+
+        for rank in ranks:
+            worker_socket_path = get_zmq_rpc_path_lmcache(
+                engine_id, "lookup_worker", rpc_port, rank
+            )
+            logger.info(
+                "lmcache lookup client connect to rank %s with worker socket path %s",
+                rank,
+                worker_socket_path,
+            )
+
+            push_socket = get_zmq_socket(
+                self.ctx,
+                worker_socket_path,
+                "ipc",
+                zmq.PUSH,  # type: ignore[attr-defined]
+                "connect",
+            )
+
+            self.push_sockets.append(push_socket)
+
+        scheduler_socket_path = get_zmq_rpc_path_lmcache(
+            engine_id, "lookup_scheduler", rpc_port, 0
+        )
+        self.pull_socket = get_zmq_socket(
+            self.ctx,
+            scheduler_socket_path,
+            "ipc",
+            zmq.PULL,  # type: ignore[attr-defined]
+            "bind",
+        )
+        logger.info(
+            "lmcache lookup client connect to scheduler with socket path %s",
+            scheduler_socket_path,
+        )
+
+        # First Party
+        from lmcache.v1.token_database import (
+            ChunkedTokenDatabase,
+            SegmentTokenDatabase,
+            TokenDatabase,
+        )
+
+        self.token_database: TokenDatabase
+        if config.enable_blending:
+            self.token_database = SegmentTokenDatabase(config, metadata)
+        else:
+            self.token_database = ChunkedTokenDatabase(config, metadata)
+
+        # A lock is needed since we need another thread to pull
+        # responses from the lookup_and_prefetch server
+        # (e.g., worker process).
+        self.lock = threading.Lock()
+
+        # map from lookup_id (i.e., req_id) to req's status.
+        # None indicates ongoing.
+        # int indicates number of hit tokens.
+        self.reqs_status: dict[str, Optional[int]] = {}
+
+        # map from lookup_id (i.e., req_id) to number of hit tokens for each worker
+        self.res_for_each_worker: dict[str, list[int]] = {}
+
+        # The two parts are [lookup_id (i.e., req_id), num_hit_tokens]
+        self.num_parts = 2
+
+        # Track lookup_ids that have been aborted for cleanup
+        self.aborted_lookups: set[str] = set()
+
+        self.running = True
+
+        self.thread = threading.Thread(
+            target=self.process_responses_from_workers,
+            daemon=True,
+            name="async-lookup-client-thread",
+        )
+        self.thread.start()
+
+        # default backoff time
+        self.lookup_backoff_time = 0.01
+        if config.extra_config is not None:
+            self.lookup_backoff_time = float(
+                config.extra_config.get("lookup_backoff_time", self.lookup_backoff_time)
+            )
+
+    def lookup_cache(self, lookup_id: str) -> Optional[int]:
+        """
+        -1 means not found;
+        None means ongoing;
+        int >= 0 means number of hit tokens
+        """
+        # Check if any aborted lookups are finished, send cleanup messages
+        self._cleanup_finished_aborted_lookups()
+
+        with self.lock:
+            if (req_status := self.reqs_status.get(lookup_id, -1)) == -1:
+                self.reqs_status[lookup_id] = None
+                self.first_lookup_time[lookup_id] = time.time()
+            elif req_status is None:
+                time.sleep(self.lookup_backoff_time)
+                if (
+                    time.time() - self.first_lookup_time[lookup_id]
+                ) * 1000 > self.config.lookup_timeout_ms:
+                    logger.warning(
+                        (
+                            "Request %s is still waiting for async lookup "
+                            "after %d seconds, returning 0 lmcache cached tokens "
+                            "so vllm can recompute"
+                        ),
+                        lookup_id,
+                        self.config.lookup_timeout_ms // 1000,
+                    )
+                    self.cancel_lookup(lookup_id)
+                    self.first_lookup_time.pop(lookup_id, None)
+                    return 0
+
+            return req_status
+
+    # TODO(Jiayi): Consider batching here
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        hashes: list[int] = []
+        offsets = []
+        for start, end, hash_val in self.token_database.process_tokens(
+            token_ids, make_key=False
+        ):
+            hashes.append(hash_val)  # type: ignore[arg-type]
+            offsets.append(end - start)
+
+        # Create structured message
+        msg = LookupRequestMsg(
+            lookup_id=lookup_id,
+            hashes=hashes,
+            offsets=offsets,
+            request_configs=request_configs,
+        )
+
+        # Serialize message using msgspec
+        msg_buf = msgspec.msgpack.encode(msg)
+
+        for i in range(self.world_size):
+            self.push_sockets[i].send(msg_buf, copy=False)
+        time.sleep(self.lookup_backoff_time)
+        return None
+
+    def process_responses_from_workers(self):
+        while self.running:
+            try:
+                msg_buf = self.pull_socket.recv(copy=False)
+                # Deserialize message using msgspec
+                msg = msgspec.msgpack.decode(msg_buf, type=LookupResponseMsg)
+                lookup_id = msg.lookup_id
+                res = msg.num_hit_tokens
+
+                with self.lock:
+                    if lookup_id not in self.res_for_each_worker:
+                        self.res_for_each_worker[lookup_id] = [res]
+                    else:
+                        self.res_for_each_worker[lookup_id].append(res)
+                    all_res = self.res_for_each_worker[lookup_id]
+
+                    if len(all_res) == self.world_size:
+                        self.res_for_each_worker.pop(lookup_id)
+
+                        # NOTE: it is possible that the number of hit
+                        # tokens is different across (TP and PP) ranks, so we
+                        # can use the minimum value as the number of
+                        # hit tokens.
+                        self.reqs_status[lookup_id] = min(all_res)
+
+            except Exception as e:
+                logger.error("Error processing response from worker: %s", e)
+
+    def clear_lookup_status(self, lookup_id: str) -> None:
+        with self.lock:
+            self.reqs_status.pop(lookup_id, None)
+            self.first_lookup_time.pop(lookup_id, None)
+
+    def cancel_lookup(self, lookup_id: str) -> None:
+        """Mark lookup as aborted. Cleanup will happen after task finishes."""
+        self.aborted_lookups.add(lookup_id)
+
+    def _cleanup_finished_aborted_lookups(self) -> None:
+        """Check for finished aborted lookups and send cleanup messages to workers."""
+        # A lookup whose status is None is still loading.
+        # We wait for it to finish before cleanup.
+        finished_lookups = [
+            lookup_id
+            for lookup_id in self.aborted_lookups
+            if self.reqs_status.get(lookup_id) is not None
+        ]
+        if finished_lookups:
+            self.aborted_lookups.difference_update(finished_lookups)
+
+        # Tell the server to free the reserved memory buffers for each aborted lookup.
+        for lookup_id in finished_lookups:
+            self._send_cleanup_message(lookup_id)
+            self.clear_lookup_status(lookup_id)
+
+    def _send_cleanup_message(self, lookup_id: str) -> None:
+        """Send cleanup message to workers to release memory objects."""
+        msg = LookupCleanupMsg(lookup_id=lookup_id)
+        msg_buf = msgspec.msgpack.encode(msg)
+
+        for i in range(self.world_size):
+            self.push_sockets[i].send(msg_buf, copy=False)
+        logger.debug("Sent cleanup message for lookup_id=%s", lookup_id)
+
+    def supports_producer_reuse(self) -> bool:
+        """Return True as LMCacheLookupClient supports producer kvcache reuse"""
+        return True
+
+    def close(self):
+        self.running = False
+        try:
+            if self.thread.is_alive():
+                self.thread.join(timeout=1.0)
+            for s in self.push_sockets:
+                s.close(linger=0)  # type: ignore[arg-type]
+            self.pull_socket.close(linger=0)  # type: ignore[arg-type]
+            self.ctx.term()
+        except Exception as e:
+            logger.warning("Failed to join thread during close: %s", e)
+
+
+class LMCacheAsyncLookupServer:
+    """ZMQ-based async lookup server that handles lookup and prefetch
+    requests using LMCacheEngine."""
+
+    def __init__(
+        self,
+        lmcache_engine: LMCacheEngine,
+        metadata: LMCacheMetadata,
+    ):
+        self.ctx = zmq.Context()  # type: ignore[attr-defined]
+        kv_connector_extra_config = metadata.kv_connector_extra_config or {}
+        rpc_port = kv_connector_extra_config.get("lmcache_rpc_port", 0)
+        assert metadata.engine_id is not None, (
+            "engine_id is required for RPC communication"
+        )
+        worker_socket_path = get_zmq_rpc_path_lmcache(
+            metadata.engine_id, "lookup_worker", rpc_port, metadata.worker_id
+        )
+        scheduler_socket_path = get_zmq_rpc_path_lmcache(
+            metadata.engine_id, "lookup_scheduler", rpc_port, 0
+        )
+        self.push_socket = get_zmq_socket(
+            self.ctx,
+            scheduler_socket_path,
+            "ipc",
+            zmq.PUSH,  # type: ignore[attr-defined]
+            "connect",
+        )
+        self.pull_socket = get_zmq_socket(
+            self.ctx,
+            worker_socket_path,
+            "ipc",
+            zmq.PULL,  # type: ignore[attr-defined]
+            "bind",
+        )
+
+        self.lmcache_engine = lmcache_engine
+        self.running = True
+
+        logger.info(
+            "lmcache lookup server start with"
+            " scheduler socket path %s, "
+            "worker socket path %s",
+            scheduler_socket_path,
+            worker_socket_path,
+        )
+        self.thread = threading.Thread(
+            target=self.process_requests_from_scheduler,
+            daemon=True,
+            name="async-lookup-server-thread",
+        )
+        self.thread.start()
+
+    def process_requests_from_scheduler(self):
+        while self.running:
+            try:
+                msg_buf = self.pull_socket.recv(copy=False)
+                # rely on msgspec to automatically discriminate
+                # between LookupRequestMsg and LookupCleanupMsg
+                msg = msgspec.msgpack.decode(
+                    msg_buf,
+                    type=Union[LookupRequestMsg, LookupCleanupMsg],
+                )
+
+                if isinstance(msg, LookupRequestMsg):
+                    # Handle lookup request
+                    self.lmcache_engine.async_lookup_and_prefetch(
+                        lookup_id=msg.lookup_id,
+                        hashes=msg.hashes,
+                        offsets=msg.offsets,
+                        pin=True,
+                        request_configs=msg.request_configs,
+                    )
+
+                elif isinstance(msg, LookupCleanupMsg):
+                    # Handle cleanup request - release memory objects for aborted lookup
+                    self.lmcache_engine.cleanup_memory_objs(msg.lookup_id)
+
+                else:
+                    logger.warning("Unknown message type: %s", type(msg))
+
+            except Exception as e:
+                logger.error("Error processing request from scheduler: %s", e)
+
+    def send_response_to_scheduler(self, lookup_id: str, num_hit_tokens: int):
+        # Create structured response message
+        msg = LookupResponseMsg(
+            lookup_id=lookup_id,
+            num_hit_tokens=num_hit_tokens,
+        )
+
+        # Serialize message using msgspec
+        msg_buf = msgspec.msgpack.encode(msg)
+        self.push_socket.send(msg_buf, copy=False)
+
+    def close(self):
+        self.running = False
+        try:
+            if self.thread.is_alive():
+                self.thread.join(timeout=1.0)
+            self.push_socket.close(linger=0)  # type: ignore[arg-type]
+            self.pull_socket.close(linger=0)  # type: ignore[arg-type]
+            self.ctx.term()
+        except Exception as e:
+            logger.warning("Failed to join thread during close: %s", e)
diff --git a/lmcache/v1/lookup_client/lmcache_lookup_client.py b/lmcache/v1/lookup_client/lmcache_lookup_client.py
new file mode 100644
index 0000000..c8fc6c5
--- /dev/null
+++ b/lmcache/v1/lookup_client/lmcache_lookup_client.py
@@ -0,0 +1,293 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+import json
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc.transport import (
+    RpcClientTransport,
+    RpcServerTransport,
+)
+
+logger = init_logger(__name__)
+
+
+class LMCacheLookupClient(LookupClientInterface):
+    """
+    Lookup client that communicates with a lookup server
+    via an injected RpcClientTransport.
+
+    The client is decoupled from the underlying communication
+    mechanism. The transport layer handles connection management,
+    retries, and error recovery.
+
+    Related extra_config:
+    - lookup_server_worker_ids:
+        is a config to control create lookup server on some
+        workers.
+        if mla is not enabled, default is [];
+        if mla is enabled, default is [0];
+        - if lookup_server_worker_ids is [], start lookup
+          server on all workers
+        - if lookup_server_worker_ids is [0], start lookup
+          server on worker0
+        - if lookup_server_worker_ids is [0, 3, 6], start
+          lookup server on worker0, worker3 and worker6
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        transport: RpcClientTransport,
+    ):
+        self.config = config
+        self.transport = transport
+
+        # NOTE: map from lookup_id (i.e., req_id) to
+        # req's status.
+        # int indicates number of hit tokens.
+        # The assumption here is that once a request is
+        # looked up, the following lookups of the same
+        # request must have the same result.
+        self.reqs_status: dict[str, int] = {}
+
+        # First Party
+        from lmcache.v1.token_database import (
+            ChunkedTokenDatabase,
+            SegmentTokenDatabase,
+            TokenDatabase,
+        )
+
+        self.enable_blending = config.enable_blending
+        self.token_database: TokenDatabase
+        if self.enable_blending:
+            self.token_database = SegmentTokenDatabase(config, metadata)
+        else:
+            self.token_database = ChunkedTokenDatabase(config, metadata)
+
+    def lookup_cache(self, lookup_id: str) -> Optional[int]:
+        """
+        "-1 means not found;
+        None means ongoing; (not supported in sync client)
+        int >= 0 means number of hit tokens
+        """
+        return self.reqs_status.get(lookup_id, -1)
+
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        request_configs_str = ""
+        if request_configs is not None and len(request_configs) != 0:
+            request_configs_str = json.dumps(request_configs)
+
+        # NOTE(Jiayi): We cannot only send hashes when
+        # blending enabled because the blender need the
+        # input embedding.
+        if not self.enable_blending:
+            hashes = []
+            offsets = []
+
+            for (
+                start,
+                end,
+                key,
+            ) in self.token_database.process_tokens(token_ids, make_key=False):
+                hashes.append(key)
+                offsets.append(end - start)
+
+            # if the token database returns no hashes,
+            # return 0
+            if not hashes:
+                return 0
+
+            msg_buf = [
+                hashes,
+                offsets,
+                lookup_id,
+                request_configs_str,
+            ]
+        else:
+            # Convert token_ids to a plain list for msgpack serialization
+            # (vLLM 0.18+ may pass ConstantList which msgspec can't encode)
+            if isinstance(token_ids, torch.Tensor):
+                serializable_ids = token_ids.tolist()
+            elif not isinstance(token_ids, list):
+                serializable_ids = list(token_ids)
+            else:
+                serializable_ids = token_ids
+            msg_buf = [
+                serializable_ids,
+                lookup_id,
+                request_configs_str,
+            ]
+
+        responses = self.transport.send_and_recv_all(msg_buf)
+
+        # Transport returns empty list on failure
+        if not responses:
+            return 0
+
+        results = [int.from_bytes(resp, "big") for resp in responses]
+
+        assert len(results) == self.transport.world_size
+        if len(set(results)) > 1:
+            logger.warning(
+                "Lookup results (number of hit tokens) "
+                "differ across (TP and PP) ranks: %s.",
+                results,
+            )
+        # NOTE: it is possible that the number of hit
+        # tokens is different across (TP and PP) ranks,
+        # so we can use the minimum value.
+        num_hit_toks = min(results)
+        self.reqs_status[lookup_id] = num_hit_toks
+
+        return num_hit_toks
+
+    def clear_lookup_status(self, lookup_id: str) -> None:
+        self.reqs_status.pop(lookup_id, None)
+
+    def supports_producer_reuse(self) -> bool:
+        """Return True as LMCacheLookupClient supports
+        producer kvcache reuse"""
+        return True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def close(self):
+        self.transport.close()
+
+
+class LMCacheLookupServer:
+    """Lookup server that handles lookup requests using
+    LMCacheEngine, with an injected RpcServerTransport."""
+
+    def __init__(
+        self,
+        lmcache_engine: LMCacheEngine,
+        metadata: LMCacheMetadata,
+        transport: RpcServerTransport,
+    ):
+        self.transport = transport
+        self.lmcache_engine = lmcache_engine
+        self.running = True
+        self.enable_blending = lmcache_engine.config.enable_blending
+
+        def process_request():
+            while self.running:
+                try:
+                    result = self.transport.recv_request()
+                    if result is None:
+                        continue
+
+                    identity, data_frames = result
+
+                    # Validate frame structure
+                    if len(data_frames) < 3:
+                        logger.warning("Malformed request received: not enough frames.")
+                        continue
+
+                    # Validate and decode lookup_id
+                    lookup_id_bytes = data_frames[-2]
+                    request_configs_bytes = data_frames[-1]
+
+                    if not isinstance(lookup_id_bytes, (bytes, str)):
+                        logger.warning(
+                            "Malformed request received: lookup_id is not bytes or str."
+                        )
+                        continue
+
+                    if not isinstance(request_configs_bytes, (bytes, str)):
+                        logger.warning(
+                            "Malformed request received: "
+                            "request_configs is not bytes or str."
+                        )
+                        continue
+
+                    # Decode to strings
+                    if isinstance(lookup_id_bytes, bytes):
+                        lookup_id = lookup_id_bytes.decode("utf-8")
+                    else:
+                        lookup_id = lookup_id_bytes
+
+                    if isinstance(request_configs_bytes, bytes):
+                        request_configs_str = request_configs_bytes.decode("utf-8")
+                    else:
+                        request_configs_str = request_configs_bytes
+
+                    request_configs = (
+                        json.loads(request_configs_str) if request_configs_str else None
+                    )
+
+                    if not self.enable_blending:
+                        hashes = data_frames[0]
+                        offsets = data_frames[1]
+                        lookup_result = self.lmcache_engine.lookup(
+                            hashes=hashes,
+                            offsets=offsets,
+                            lookup_id=lookup_id,
+                            pin=True,
+                            request_configs=request_configs,
+                        )
+                    else:
+                        tokens = data_frames[0]
+                        lookup_result = self.lmcache_engine.lookup(
+                            tokens=tokens,
+                            lookup_id=lookup_id,
+                            pin=True,
+                            request_configs=request_configs,
+                        )
+                    response = lookup_result.to_bytes(4, "big")
+                    self.transport.send_response(identity, response)
+                except json.JSONDecodeError as e:
+                    logger.error("Error decoding JSON in lookup request: %s", e)
+                except UnicodeDecodeError as e:
+                    logger.error("Error decoding UTF-8 in lookup request: %s", e)
+                except Exception as e:
+                    logger.error("Error processing lookup request: %s", e)
+
+        logger.info("lmcache lookup server started")
+        self.thread = threading.Thread(
+            target=process_request,
+            daemon=True,
+            name="lookup-server-thread",
+        )
+        self.thread.start()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def close(self):
+        # Stop the processing thread first
+        self.running = False
+
+        # Wait for thread to finish with timeout
+        if self.thread.is_alive():
+            self.thread.join(timeout=2.0)
+            if self.thread.is_alive():
+                logger.warning("Lookup server thread did not terminate gracefully")
+
+        # Close transport after thread is stopped
+        self.transport.close()
diff --git a/lmcache/v1/lookup_client/lmcache_lookup_client_bypass.py b/lmcache/v1/lookup_client/lmcache_lookup_client_bypass.py
new file mode 100644
index 0000000..8c668ea
--- /dev/null
+++ b/lmcache/v1/lookup_client/lmcache_lookup_client_bypass.py
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+class LMCacheBypassLookupClient(LookupClientInterface):
+    """
+    Bypass lookup client that directly calls LMCacheEngine.lookup()
+    instead of using ZMQ communication. This is particularly useful
+    for MLA scenarios where only rank 0 needs to perform lookups.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        lmcache_engine: LMCacheEngine,
+    ):
+        """
+        Initialize the bypass lookup client.
+
+        Args:
+            config: The LMCacheEngine configuration
+            metadata: The LMCacheEngine metadata
+            lmcache_engine: The LMCacheEngine instance to use for lookups
+        """
+        assert isinstance(config, LMCacheEngineConfig), (
+            "LMCache v1 configuration should be passed."
+        )
+
+        self.lmcache_engine = lmcache_engine
+        self.config = config
+
+        # Use the token database from the provided LMCacheEngine
+        self.token_database = self.lmcache_engine.token_database
+        self.enable_blending = self.config.enable_blending
+
+        logger.info("LMCacheBypassLookupClient initialized")
+
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        try:
+            if not self.enable_blending:
+                # Process tokens to get hashes and offsets
+                hashes = []
+                offsets = []
+                for start, end, key in self.token_database.process_tokens(
+                    token_ids, make_key=False
+                ):
+                    hashes.append(key)
+                    offsets.append(end - start)
+                if not hashes:
+                    return 0
+
+                # Call LMCacheEngine lookup with hashes and offsets
+                result = self.lmcache_engine.lookup(
+                    hashes=hashes,
+                    offsets=offsets,
+                    lookup_id=lookup_id,
+                    pin=True,
+                    request_configs=request_configs,
+                )
+            else:
+                # For blending mode, pass tokens directly
+                result = self.lmcache_engine.lookup(
+                    tokens=token_ids,
+                    lookup_id=lookup_id,
+                    pin=True,
+                    request_configs=request_configs,
+                )
+
+            return result
+
+        except Exception as e:
+            logger.error("Error in bypass lookup: %s", e)
+            return 0
+
+    def supports_producer_reuse(self) -> bool:
+        return True
+
+    def close(self):
+        # No resources to clean up for bypass client
+        logger.info("LMCacheBypassLookupClient closed")
diff --git a/lmcache/v1/lookup_client/mooncake_lookup_client.py b/lmcache/v1/lookup_client/mooncake_lookup_client.py
new file mode 100644
index 0000000..9c8960d
--- /dev/null
+++ b/lmcache/v1/lookup_client/mooncake_lookup_client.py
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector.mooncakestore_connector import (
+    MooncakeStoreConfig,
+    setup_mooncake_store,
+)
+
+logger = init_logger(__name__)
+
+
+class MooncakeLookupClient(LookupClientInterface):
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        master_addr: str,
+    ):
+        # Third Party
+        from mooncake.store import MooncakeDistributedStore
+
+        self.store = MooncakeDistributedStore()
+        # Deprecated
+        # TODO(baoloongmao): use dict config instead in the future
+        lookup_config = MooncakeStoreConfig(
+            setup_config={
+                "local_hostname": "localhost",
+                "metadata_server": "P2PHANDSHAKE",
+                "global_segment_size": "0",
+                "local_buffer_size": str(16 * 1024 * 1024),
+                "protocol": "tcp",
+                "device_name": "",
+                "master_server_address": master_addr,
+            },
+        )
+        setup_mooncake_store(self.store, lookup_config)
+
+        # Initialize token database for processing tokens
+        assert isinstance(config, LMCacheEngineConfig), (
+            "LMCache v1 configuration is should be passed."
+        )
+
+        # First Party
+        from lmcache.v1.token_database import ChunkedTokenDatabase
+
+        assert not config.enable_blending, (
+            "LMCache v1 blending is not supported in MooncakeLookupClient yet."
+        )
+        self.token_database = ChunkedTokenDatabase(config, metadata)
+
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: Optional[str] = None,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        # process token_ids to cacheengine keys
+        keys = []
+        ends = []
+        for start, end, key in self.token_database.process_tokens(token_ids):
+            assert isinstance(key, CacheEngineKey)
+            keys.append(key.to_string())
+            ends.append(end)
+
+        # Use batch_is_exist to check all keys at once
+        # rets is list of int: 1 = found, 0 = not found, -1 = error
+        rets = self.store.batch_is_exist(keys)
+
+        # Find the first key that doesn't exist (ret != 1)
+        # This follows the same logic as cache engine's lookup method
+        for i, ret in enumerate(rets):
+            if ret != 1:  # Not found or error
+                # Return the end position of the previous chunk
+                # If i == 0, no chunks were found, return 0
+                return ends[i - 1] if i > 0 else 0
+
+        # All keys were found, return the last end position
+        return ends[-1] if ends else 0
+
+    def supports_producer_reuse(self) -> bool:
+        """Return True as MooncakeLookupClient supports producer kvcache reuse"""
+        return True
+
+    def close(self):
+        # nothing here
+        pass
diff --git a/lmcache/v1/lookup_client/record_strategies/__init__.py b/lmcache/v1/lookup_client/record_strategies/__init__.py
new file mode 100644
index 0000000..2cbb00d
--- /dev/null
+++ b/lmcache/v1/lookup_client/record_strategies/__init__.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Dict, Type
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.lookup_client.record_strategies.base import (
+    AsyncRecorder,
+    RecordStrategy,
+)
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+logger = init_logger(__name__)
+
+
+def _discover_strategies() -> Dict[str, Type[RecordStrategy]]:
+    strategies: Dict[str, Type[RecordStrategy]] = {}
+    for cls in discover_subclasses(
+        __name__,
+        RecordStrategy,  # type: ignore[type-abstract]
+        include_abstract=True,
+        on_import_error=lambda mod, exc: None,
+    ):
+        # Use module short name as strategy name
+        strategy_name = cls.__module__.rsplit(".", 1)[-1]
+        strategies[strategy_name] = cls
+    return strategies
+
+
+_strategies_cache = None
+
+
+def _get_strategies() -> Dict[str, Type[RecordStrategy]]:
+    global _strategies_cache
+    if _strategies_cache is None:
+        _strategies_cache = _discover_strategies()
+    return _strategies_cache
+
+
+def create_record_strategy(config) -> RecordStrategy:
+    strategies = _get_strategies()
+    strategy_name = config.chunk_statistics_strategy
+    chunk_size = config.chunk_size
+    if strategy_name not in strategies:
+        raise ValueError(
+            f"Unknown strategy: {strategy_name}. Available: {list(strategies.keys())}"
+        )
+    return strategies[strategy_name](config, chunk_size)  # type: ignore[call-arg]
+
+
+def list_record_strategies() -> list[str]:
+    return list(_get_strategies().keys())
+
+
+__all__ = [
+    "AsyncRecorder",
+    "RecordStrategy",
+    "create_record_strategy",
+    "list_record_strategies",
+]
+
+
+def __getattr__(name):
+    strategies = _get_strategies()
+    for strategy_class in strategies.values():
+        if strategy_class.__name__ == name:
+            return strategy_class
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
diff --git a/lmcache/v1/lookup_client/record_strategies/base.py b/lmcache/v1/lookup_client/record_strategies/base.py
new file mode 100644
index 0000000..deb1e1d
--- /dev/null
+++ b/lmcache/v1/lookup_client/record_strategies/base.py
@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import Any, Union
+import queue
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.token_database import ChunkedTokenDatabase
+
+logger = init_logger(__name__)
+
+
+class RecordStrategy(ABC):
+    """Base class for chunk recording strategies."""
+
+    def __init__(self, chunk_size: int):
+        """Initialize the recording strategy.
+
+        Args:
+            chunk_size: Size of each token chunk for processing
+        """
+        self.chunk_size = chunk_size
+        self.total_chunks = 0
+        self.unique_chunks_count = 0
+        self.lock = threading.RLock()
+
+        self._token_db = ChunkedTokenDatabase()
+        self._token_db.chunk_size = chunk_size
+
+    def _compute_chunk_hashes(self, token_ids: list[int]) -> list[int]:
+        """Compute prefix hashes for all chunks using ChunkedTokenDatabase.
+
+        Args:
+            token_ids: List of token IDs to process
+
+        Returns:
+            List of hash values (integers) for each chunk.
+        """
+        chunk_hashes = []
+        for _, _, hash_val in self._token_db.process_tokens(
+            tokens=token_ids, make_key=False
+        ):
+            chunk_hashes.append(hash_val)
+        return chunk_hashes
+
+    def _compute_chunk_hashes_hex(self, token_ids: list[int]) -> list[str]:
+        """Compute prefix hashes for all chunks and return as hex strings.
+
+        Args:
+            token_ids: List of token IDs to process
+
+        Returns:
+            List of hash values (hex strings) for each chunk.
+        """
+        chunk_hashes = []
+        for hash_val in self._compute_chunk_hashes(token_ids):
+            if hash_val < 0:
+                hash_val = hash_val & ((1 << 64) - 1)
+            chunk_hashes.append(hex(hash_val))
+        return chunk_hashes
+
+    @abstractmethod
+    def preprocess(self, token_ids: list[int]) -> Any:
+        """Preprocess token IDs before recording.
+
+        This method is called to transform raw token IDs into a format suitable
+        for the specific recording strategy. For example, it might compute hash
+        positions for a bloom filter or convert hashes to hex strings for file storage.
+
+        Args:
+            token_ids: List of token IDs to preprocess
+
+        Returns:
+            Preprocessed data in strategy-specific format. The return type depends
+            on the concrete strategy implementation.
+        """
+        pass
+
+    @abstractmethod
+    def record(self, preprocessed_data: Any, lookup_id: str) -> None:
+        """Record the preprocessed chunk data.
+
+        This method performs the actual recording operation using the preprocessed
+        data. It should update internal statistics (total_chunks,
+        unique_chunks_count) and perform strategy-specific recording (e.g., update
+        bloom filter, write to file).
+
+        This method must be thread-safe as it may be called from async worker
+        threads.
+
+        Args:
+            preprocessed_data: Data returned from preprocess() method
+            lookup_id: Unique identifier for this lookup operation
+        """
+        pass
+
+    @abstractmethod
+    def reset(self) -> None:
+        """Reset all statistics and internal state.
+
+        This method should clear all recorded data and reset counters to their
+        initial state. It should be safe to call at any time.
+        """
+
+    def get_statistics(self) -> dict:
+        """Get current statistics.
+
+        Returns:
+            Dictionary containing statistics about recorded chunks, including:
+            - total_chunks: Total number of chunks processed
+            - unique_chunks: Number of unique chunks seen
+            - duplicate_chunks: Number of duplicate chunks
+            - reuse_rate: Ratio of duplicate to total chunks
+        """
+        with self.lock:
+            dup = self.total_chunks - self.unique_chunks_count
+            base_stats = {
+                "total_chunks": self.total_chunks,
+                "unique_chunks": self.unique_chunks_count,
+                "duplicate_chunks": dup,
+                "reuse_rate": dup / self.total_chunks if self.total_chunks > 0 else 0.0,
+            }
+            return base_stats
+
+    def setup_metrics(self, prometheus_logger) -> None:
+        """Setup Prometheus metrics for this strategy.
+
+        Args:
+            prometheus_logger: Prometheus logger instance to register metrics with
+        """
+        prometheus_logger.chunk_statistics_total_chunks.set_function(
+            lambda: self.total_chunks
+        )
+        prometheus_logger.chunk_statistics_unique_chunks.set_function(
+            lambda: self.unique_chunks_count
+        )
+        prometheus_logger.chunk_statistics_reuse_rate.set_function(
+            lambda: (self.total_chunks - self.unique_chunks_count) / self.total_chunks
+            if self.total_chunks > 0
+            else 0.0
+        )
+
+    def close(self) -> None:  # noqa: B027
+        """Clean up resources.
+
+        This method is called when the strategy is no longer needed. Subclasses
+        should override this to clean up any resources (e.g., close file handles).
+        """
+        pass
+
+
+class AsyncRecorder:
+    """Async processing infrastructure for RecordStrategy.
+
+    This class wraps a RecordStrategy and provides asynchronous processing
+    capabilities using a background worker thread and queue.
+    """
+
+    def __init__(
+        self,
+        strategy: RecordStrategy,
+        queue_capacity: int = 100000,
+        preprocess_in_caller: bool = False,
+    ):
+        """Initialize the async recorder.
+
+        Args:
+            strategy: The RecordStrategy instance to wrap
+            queue_capacity: Maximum number of items in the async queue
+            preprocess_in_caller: If True, preprocess in caller thread before queueing;
+                                 if False, preprocess in worker thread
+        """
+        self.strategy = strategy
+        self.queue_capacity = queue_capacity
+        self.preprocess_in_caller = preprocess_in_caller
+
+        self.async_queue: queue.Queue = queue.Queue(maxsize=queue_capacity)
+        self.async_shutdown = False
+        self.queue_full_blocks = 0
+        self.queue_max_size = 0
+        self.lock = threading.RLock()
+
+        self.async_worker_thread = threading.Thread(
+            target=self._async_worker,
+            daemon=True,
+            name=f"{strategy.__class__.__name__}AsyncWorker",
+        )
+        self.async_worker_thread.start()
+
+    def _async_worker(self) -> None:
+        """Background worker thread that processes queued items."""
+        while not self.async_shutdown:
+            try:
+                item = self.async_queue.get(timeout=0.1)
+                if item is None:
+                    break
+                data, lookup_id = item
+                if self.preprocess_in_caller:
+                    preprocessed_data = data
+                else:
+                    preprocessed_data = self.strategy.preprocess(data)
+                self.strategy.record(preprocessed_data, lookup_id)
+                self.async_queue.task_done()
+            except queue.Empty:
+                continue
+            except Exception as e:
+                logger.error("Async worker error: %s", e, exc_info=True)
+
+        # Process remaining items
+        while not self.async_queue.empty():
+            try:
+                item = self.async_queue.get_nowait()
+                if item is not None:
+                    data, lookup_id = item
+                    if self.preprocess_in_caller:
+                        preprocessed_data = data
+                    else:
+                        preprocessed_data = self.strategy.preprocess(data)
+                    self.strategy.record(preprocessed_data, lookup_id)
+                self.async_queue.task_done()
+            except (queue.Empty, Exception):
+                break
+
+    def record_async(
+        self, token_ids: Union[torch.Tensor, list[int]], lookup_id: str
+    ) -> None:
+        """Record token IDs asynchronously.
+
+        Args:
+            token_ids: Token IDs to record (tensor or list)
+            lookup_id: Unique identifier for this lookup operation
+        """
+        if isinstance(token_ids, torch.Tensor):
+            token_ids = token_ids.tolist()
+
+        if self.preprocess_in_caller:
+            data = self.strategy.preprocess(token_ids)
+        else:
+            data = token_ids
+
+        self._queue_item((data, lookup_id))
+
+    def _queue_item(self, item, timeout: float = 10.0) -> None:
+        """Add item to async queue with timeout handling."""
+        try:
+            self.async_queue.put(item, block=True, timeout=timeout)
+        except queue.Full:
+            with self.lock:
+                self.queue_full_blocks += 1
+            self.async_queue.put(item, block=True)
+
+    def get_statistics(self) -> dict:
+        """Get statistics including async queue metrics.
+
+        Returns:
+            Dictionary containing strategy statistics plus async queue metrics
+        """
+        stats = self.strategy.get_statistics()
+        with self.lock:
+            queue_size = self.async_queue.qsize()
+            self.queue_max_size = max(self.queue_max_size, queue_size)
+            stats["async_queue"] = {
+                "capacity": self.queue_capacity,
+                "current_size": queue_size,
+                "max_size_reached": self.queue_max_size,
+                "full_blocks": self.queue_full_blocks,
+                "utilization": queue_size / self.queue_capacity
+                if self.queue_capacity > 0
+                else 0.0,
+            }
+        return stats
+
+    def wait_for_completion(self, timeout: float = 5.0) -> bool:
+        """Wait for async queue to be processed.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            True if queue is empty, False if timeout occurred
+        """
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if self.async_queue.empty():
+                time.sleep(0.01)
+                if self.async_queue.empty():
+                    return True
+            time.sleep(0.01)
+        return self.async_queue.empty()
+
+    def reset(self) -> None:
+        """Reset strategy and clear async queue."""
+        self.wait_for_completion(timeout=5.0)
+        with self.lock:
+            self.strategy.reset()
+            self.queue_full_blocks = 0
+            self.queue_max_size = 0
+            self._clear_queue()
+
+    def _clear_queue(self) -> None:
+        """Clear all items from async queue."""
+        while not self.async_queue.empty():
+            try:
+                self.async_queue.get_nowait()
+            except queue.Empty:
+                break
+
+    def close(self) -> None:
+        """Shutdown async worker and clean up resources."""
+        self.async_shutdown = True
+        try:
+            self.async_queue.put(None, block=False)
+        except queue.Full:
+            pass
+
+        self.async_worker_thread.join(timeout=5.0)
+        if self.async_worker_thread.is_alive():
+            logger.warning("Async worker did not stop gracefully")
+
+        self.strategy.close()
diff --git a/lmcache/v1/lookup_client/record_strategies/file_hash.py b/lmcache/v1/lookup_client/record_strategies/file_hash.py
new file mode 100644
index 0000000..f433365
--- /dev/null
+++ b/lmcache/v1/lookup_client/record_strategies/file_hash.py
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from pathlib import Path
+from typing import Optional, cast
+import io
+import json
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.lookup_client.record_strategies.base import RecordStrategy
+
+logger = init_logger(__name__)
+
+
+class FileHashStrategy(RecordStrategy):
+    """File-based strategy that writes chunk hashes to disk."""
+
+    def __init__(self, config, chunk_size: int):
+        super().__init__(chunk_size=chunk_size)
+        # File size threshold in bytes for rotation (default: 100MB)
+        self.file_rotation_size = config.get_extra_config_value(
+            "chunk_statistics_file_rotation_size", 100 * 1024 * 1024
+        )
+        # Maximum number of files to keep before deleting oldest
+        self.file_max_count = config.get_extra_config_value(
+            "chunk_statistics_file_max_count", 100
+        )
+        # Directory path for storing chunk hash files
+        self.output_dir = Path(
+            config.get_extra_config_value(
+                "chunk_statistics_file_output_dir", "./chunk_hashes"
+            )
+        )
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.file_count = 0
+        self.current_file_size = 0
+        self.current_file: Optional[Path] = None
+        self.current_file_handle: Optional[io.TextIOWrapper] = None
+        self.file_list: list[Path] = []
+
+    def preprocess(self, token_ids: list[int]) -> list[str]:
+        """Preprocess token IDs into hex hash strings."""
+        return self._compute_chunk_hashes_hex(token_ids)
+
+    def record(self, chunk_hashes: list[str], lookup_id: str) -> None:
+        """Record chunk hashes to file."""
+        with self.lock:
+            if (
+                self.current_file is None
+                or self.current_file_size >= self.file_rotation_size
+            ):
+                self._rotate_file()
+            data = {
+                "timestamp": time.time(),
+                "lookup_id": lookup_id,
+                "chunk_hashes": chunk_hashes,
+            }
+            if self.current_file_handle is not None:
+                file_handle = cast(io.TextIOWrapper, self.current_file_handle)
+                line = json.dumps(data) + "\n"
+                file_handle.write(line)
+                file_handle.flush()
+                self.current_file_size += len(line)
+            self.total_chunks += len(chunk_hashes)
+            self.unique_chunks_count += len(set(chunk_hashes))
+
+    def _rotate_file(self) -> None:
+        if self.current_file_handle is not None:
+            cast(io.TextIOWrapper, self.current_file_handle).close()
+        timestamp = int(time.time())
+        self.current_file = (
+            self.output_dir / f"chunk_hashes_{timestamp}_{self.file_count:06d}.jsonl"
+        )
+        self.current_file_handle = open(self.current_file, "w")
+        self.current_file_size = 0
+        self.file_count += 1
+        self.file_list.append(self.current_file)
+        if len(self.file_list) > self.file_max_count:
+            oldest_file = self.file_list.pop(0)
+            try:
+                if oldest_file.exists():
+                    oldest_file.unlink()
+            except Exception as e:
+                logger.error("Failed to delete file %s: %s", oldest_file, e)
+
+    def get_statistics(self) -> dict:
+        stats = super().get_statistics()
+        stats.update(
+            {
+                "file_hash": {
+                    "file_count": self.file_count,
+                    "current_file_size": self.current_file_size,
+                    "file_max_count": self.file_max_count,
+                    "output_dir": str(self.output_dir),
+                }
+            }
+        )
+        return stats
+
+    def setup_metrics(self, prometheus_logger) -> None:
+        """Setup file hash specific metrics."""
+        super().setup_metrics(prometheus_logger)
+        prometheus_logger.chunk_statistics_file_count.set_function(
+            lambda: self.file_count
+        )
+        prometheus_logger.chunk_statistics_current_file_size.set_function(
+            lambda: self.current_file_size
+        )
+
+    def reset(self) -> None:
+        """Reset file writer and statistics."""
+        with self.lock:
+            if self.current_file_handle is not None:
+                cast(io.TextIOWrapper, self.current_file_handle).close()
+                self.current_file_handle = None
+                self.current_file = None
+            self.total_chunks = 0
+            self.unique_chunks_count = 0
+            self.file_count = 0
+            self.current_file_size = 0
+            self.file_list.clear()
+
+    def close(self) -> None:
+        """Close file handles."""
+        if self.current_file_handle is not None:
+            cast(io.TextIOWrapper, self.current_file_handle).close()
+            self.current_file_handle = None
+            self.current_file = None
diff --git a/lmcache/v1/lookup_client/record_strategies/memory_bloom_filter.py b/lmcache/v1/lookup_client/record_strategies/memory_bloom_filter.py
new file mode 100644
index 0000000..01b6dd6
--- /dev/null
+++ b/lmcache/v1/lookup_client/record_strategies/memory_bloom_filter.py
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.lookup_client.record_strategies.base import RecordStrategy
+from lmcache.v1.utils.bloom_filter import BloomFilter
+
+logger = init_logger(__name__)
+
+
+class MemoryBloomFilterStrategy(RecordStrategy):
+    """Memory-based strategy using Bloom Filter."""
+
+    def __init__(self, config, chunk_size: int):
+        super().__init__(chunk_size=chunk_size)
+        self.global_bloom = BloomFilter(
+            # Expected number of chunks for bloom filter capacity planning
+            config.get_extra_config_value(
+                "chunk_statistics_mem_bf_expected_chunks", 20000000
+            ),
+            # Target false positive rate for bloom filter
+            config.get_extra_config_value(
+                "chunk_statistics_mem_bf_false_positive_rate", 0.01
+            ),
+        )
+
+    def preprocess(self, token_ids: list[int]) -> list[list[int]]:
+        """Preprocess token IDs into bloom filter hash positions.
+
+        Args:
+            token_ids: List of token IDs to process
+
+        Returns:
+            List of bloom filter hash positions for each chunk, where each inner list
+            contains the hash_count separate hash results for that chunk.
+
+            Example structure:
+            [
+                [hash1_pos1, hash1_pos2, ..., hash1_posN],  # chunk 1 hashes
+                [hash2_pos1, hash2_pos2, ..., hash2_posN],  # chunk 2 hashes
+                ...
+            ]
+            where N is the bloom filter's hash_count
+        """
+        chunk_data_list = []
+        for prefix_hash in self._compute_chunk_hashes(token_ids):
+            if prefix_hash < 0:
+                prefix_hash = prefix_hash & ((1 << 64) - 1)
+            chunk_data_list.append(self.global_bloom._hashes(prefix_hash))
+        return chunk_data_list
+
+    def record(self, chunk_bloom_positions: list[list[int]], lookup_id: str) -> None:
+        """Record chunk bloom filter positions and update statistics."""
+        with self.lock:
+            unique = self.global_bloom.add_batch_with_hashes_and_check(
+                chunk_bloom_positions
+            )
+            self.total_chunks += len(chunk_bloom_positions)
+            self.unique_chunks_count += unique
+
+    def get_statistics(self) -> dict:
+        stats = super().get_statistics()
+        stats.update({"bloom_filter": self.global_bloom.get_statistics()})
+        return stats
+
+    def setup_metrics(self, prometheus_logger) -> None:
+        """Setup bloom filter specific metrics."""
+        super().setup_metrics(prometheus_logger)
+        prometheus_logger.chunk_statistics_bloom_filter_size_mb.set_function(
+            lambda: self.global_bloom.get_memory_usage_bytes() / (1024 * 1024)
+        )
+        prometheus_logger.chunk_statistics_bloom_filter_fill_rate.set_function(
+            lambda: self.global_bloom.get_fill_rate()
+        )
+
+    def reset(self) -> None:
+        """Reset bloom filter and statistics."""
+        with self.lock:
+            self.global_bloom.clear()
+            self.total_chunks = 0
+            self.unique_chunks_count = 0
diff --git a/lmcache/v1/manager.py b/lmcache/v1/manager.py
new file mode 100644
index 0000000..12ae9b9
--- /dev/null
+++ b/lmcache/v1/manager.py
@@ -0,0 +1,539 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LMCacheManager: A unified manager for LMCache internal components.
+
+This module provides a clean interface to manage LMCache components lifecycle,
+decoupling the vLLM adapter from internal LMCache implementation details.
+"""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor, TimeoutError
+from typing import TYPE_CHECKING, Any, Optional, Union
+import time
+import traceback
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.base_service_factory import BaseServiceFactory
+from lmcache.logging import init_logger
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.health_monitor.base import HealthMonitor
+from lmcache.v1.internal_api_server.api_server import InternalAPIServer
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.offload_server.zmq_server import ZMQOffloadServer
+from lmcache.v1.plugin.runtime_plugin_launcher import RuntimePluginLauncher
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+        LMCacheAsyncLookupServer,
+    )
+    from lmcache.v1.lookup_client.lmcache_lookup_client import LMCacheLookupServer
+
+logger = init_logger(__name__)
+
+
+class LMCacheManager:
+    """
+    LMCacheManager manages the lifecycle of LMCache internal components.
+
+    For an integration to utilize the Manager, define a ServiceFactory
+    that determines which components to create for which workers.
+
+    This class encapsulates the initialization and shutdown of:
+    - LMCacheEngine
+    - LookupClient / LookupServer
+    - OffloadServer
+    - InternalAPIServer
+    - RuntimePluginLauncher
+    - HealthMonitor
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        service_factory: BaseServiceFactory,
+        connector: Optional[Any] = None,
+    ):
+        """
+        Initialize LMCacheManager.
+
+        Args:
+            config: LMCache engine configuration
+            service_factory: Factory for creating service components
+            role: The role string ("scheduler" or "worker")
+            connector: Reference to LMCacheConnectorV1Impl for internal
+                       API server
+        """
+        self._config = config
+        self._service_factory = service_factory
+        self._connector: Any = connector
+
+        # Flag to track if initialization failed
+        self._init_failed = False
+        self._init_failed_reason: str = ""
+
+        self._health_monitor: Optional[HealthMonitor] = None
+        self._lmcache_engine_metadata: Optional[LMCacheMetadata] = None
+        self._lmcache_engine: Optional[LMCacheEngine] = None
+        self._lookup_client: Optional[LookupClientInterface] = None
+        self._lookup_server: Optional[
+            Union["LMCacheLookupServer", "LMCacheAsyncLookupServer"]
+        ] = None
+        self._offload_server: Optional[ZMQOffloadServer] = None
+        self._runtime_plugin_launcher: Optional[RuntimePluginLauncher] = None
+        self._api_server: Optional[InternalAPIServer] = None
+
+        # Initialize components via service factory
+        try:
+            self._lmcache_engine_metadata = service_factory.get_or_create_metadata()
+            self._lmcache_engine = service_factory.get_or_create_lmcache_engine()
+            self._lookup_client = service_factory.maybe_create_lookup_client()
+            self._lookup_server = service_factory.maybe_create_lookup_server()
+            self._offload_server = service_factory.maybe_create_offload_server()
+            self._runtime_plugin_launcher = (
+                service_factory.maybe_create_runtime_plugin_launcher()
+            )
+            self._api_server = service_factory.maybe_create_internal_api_server(
+                lmcache_manager=self
+            )
+        except Exception as e:
+            self._init_failed = True
+            self._init_failed_reason = "".join(traceback.format_exception(e))
+            logger.error(
+                "Failed to initialize LMCacheManager components: %s. "
+                "System will operate in degraded mode (recompute).",
+                self._init_failed_reason,
+            )
+
+    # ==================== Property Accessors ====================
+
+    @property
+    def lmcache_engine(self) -> Optional[LMCacheEngine]:
+        """Get the LMCache engine instance."""
+        return self._lmcache_engine
+
+    @property
+    def lmcache_engine_metadata(self) -> Optional[LMCacheMetadata]:
+        """Get the LMCache engine metadata."""
+        return self._lmcache_engine_metadata
+
+    @property
+    def lookup_client(self) -> Optional[LookupClientInterface]:
+        """Get the lookup client instance."""
+        return self._lookup_client
+
+    @property
+    def lookup_server(
+        self,
+    ) -> Optional[Union["LMCacheLookupServer", "LMCacheAsyncLookupServer"]]:
+        """Get the lookup server instance."""
+        return self._lookup_server
+
+    @property
+    def offload_server(self) -> Optional[ZMQOffloadServer]:
+        """Get the offload server instance."""
+        return self._offload_server
+
+    @property
+    def api_server(self) -> Optional[InternalAPIServer]:
+        """Get the API server instance."""
+        return self._api_server
+
+    @property
+    def health_monitor(self) -> Optional[HealthMonitor]:
+        """Get the health monitor instance."""
+        return self._health_monitor
+
+    @property
+    def kv_caches(self) -> dict[str, torch.Tensor]:
+        if self._connector is not None and hasattr(self._connector, "kv_caches"):
+            return self._connector.kv_caches
+        return {}
+
+    @property
+    def config(self) -> LMCacheEngineConfig:
+        """Get the LMCache engine configuration."""
+        return self._config
+
+    # ==================== Lifecycle Methods ====================
+
+    def start_services(self) -> None:
+        """
+        Start all managed services.
+
+        Managed services include:
+        - InternalAPIServer: HTTP server exposing internal APIs for
+          monitoring and management (e.g., cache stats, flush operations).
+        - RuntimePluginLauncher: Launches external plugin processes defined
+          in the configuration (e.g., custom telemetry, cache warming).
+        """
+        if self._api_server is not None:
+            self._api_server.start()
+
+        if self._runtime_plugin_launcher is not None:
+            self._runtime_plugin_launcher.launch_plugins()
+
+    def post_init(self) -> None:
+        """
+        Post-initialization after KV caches are registered.
+        """
+        # If initialization already failed, mark engine and return early
+        if self._init_failed:
+            if self._lmcache_engine is not None:
+                self._lmcache_engine.mark_init_failed(self._init_failed_reason)
+            logger.warning("Skipping post_init due to previous initialization failure")
+            return
+
+        if self._lmcache_engine is None:
+            # Initialize health monitor for scheduler (even without engine)
+            self._init_health_monitor()
+            return
+
+        try:
+            # First Party
+            from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+                LMCacheAsyncLookupServer,
+            )
+
+            async_lookup_server = None
+            if self._config.enable_async_loading and self._lookup_server is not None:
+                assert isinstance(self._lookup_server, LMCacheAsyncLookupServer)
+                async_lookup_server = self._lookup_server
+
+            self._lmcache_engine.post_init(async_lookup_server=async_lookup_server)
+
+            # Initialize health monitor after engine post_init completes
+            self._init_health_monitor()
+        except Exception as e:
+            self._handle_post_init_failure(e)
+
+    def _init_health_monitor(self) -> None:
+        """Initialize the health monitor via the service factory.
+
+        Called during post_init after all components are initialized.
+        """
+        self._health_monitor = self._service_factory.maybe_create_health_monitor(
+            lmcache_manager=self
+        )
+
+    def _handle_post_init_failure(self, e: Exception) -> None:
+        """
+        Handle initialization failure during post_init.
+
+        Args:
+            e: The exception that caused the failure
+        """
+        self._init_failed = True
+        self._init_failed_reason = "".join(traceback.format_exception(e))
+        if self._lmcache_engine is not None:
+            self._lmcache_engine.mark_init_failed(self._init_failed_reason)
+        logger.error(
+            "Failed during post_init: %s. "
+            "System will operate in degraded mode (recompute).",
+            self._init_failed_reason,
+        )
+
+    def stop_services(self) -> None:
+        """Stop all managed components gracefully."""
+        logger.info("Stopping LMCacheManager services...")
+        start_time = time.time()
+        errors: list[tuple[str, Union[str, Exception]]] = []
+
+        def _safe_close(name: str, close_fn, timeout: float = 10.0):
+            """Helper to close a resource with timeout protection."""
+            try:
+                logger.info("Closing %s...", name)
+                with ThreadPoolExecutor(max_workers=1) as executor:
+                    future = executor.submit(close_fn)
+                    try:
+                        future.result(timeout=timeout)
+                        logger.info("%s closed successfully", name)
+                    except TimeoutError:
+                        logger.error(
+                            "%s close operation timed out after %ss. "
+                            "Continuing with shutdown...",
+                            name,
+                            timeout,
+                        )
+                        errors.append((name, "Timeout"))
+            except Exception as e:
+                logger.error("Error closing %s: %s", name, e)
+                errors.append((name, e))
+
+        # Stop health monitor first
+        if self._health_monitor is not None:
+            _safe_close("health_monitor", self._health_monitor.stop, timeout=5.0)
+
+        # Close offload server
+        if self._offload_server is not None:
+            _safe_close("offload_server", self._offload_server.close, timeout=10.0)
+
+        # Stop plugins
+        if self._runtime_plugin_launcher is not None:
+            _safe_close(
+                "runtime_plugin_launcher",
+                self._runtime_plugin_launcher.stop_plugins,
+                timeout=10.0,
+            )
+
+        # Stop API server
+        if self._api_server is not None:
+            _safe_close("api_server", self._api_server.stop, timeout=10.0)
+
+        # Close lookup server
+        if self._lookup_server is not None:
+            _safe_close("lookup_server", self._lookup_server.close, timeout=10.0)
+
+        # Close lookup client
+        if self._lookup_client is not None:
+            _safe_close("lookup_client", self._lookup_client.close, timeout=10.0)
+
+        # Destroy cache engine
+        try:
+            engine_instance_id = self._service_factory.get_engine_instance_id()
+            logger.info("Destroying LMCache engine: %s", engine_instance_id)
+            with ThreadPoolExecutor(max_workers=1) as executor:
+                future = executor.submit(
+                    LMCacheEngineBuilder.destroy, engine_instance_id
+                )
+                try:
+                    future.result(timeout=15.0)
+                    logger.info("LMCache engine destroyed successfully")
+                except TimeoutError:
+                    logger.error(
+                        "Cache engine destroy timed out after 15s. "
+                        "Continuing with shutdown..."
+                    )
+                    errors.append(("cache_engine", "Timeout"))
+        except Exception as e:
+            logger.error("Error destroying cache engine: %s", e)
+            errors.append(("cache_engine", e))
+
+        elapsed = time.time() - start_time
+        if errors:
+            logger.warning(
+                "Shutdown completed with %d errors in %.2fs: %s",
+                len(errors),
+                elapsed,
+                errors,
+            )
+        else:
+            logger.info(
+                "LMCacheManager services stopped successfully in %.2fs",
+                elapsed,
+            )
+
+    # ==================== Lookup Management ====================
+
+    def close_lookup_client(self) -> dict:
+        """
+        Close the current lookup client.
+
+        Returns:
+            dict: Result with old client type info.
+        """
+        old_type = self._get_lookup_type_str(self._lookup_client)
+        if self._lookup_client is not None:
+            try:
+                self._lookup_client.close()
+                self._lookup_client = None
+                logger.info("Closed lookup client: %s", old_type)
+            except Exception as e:
+                logger.warning("Error closing lookup client: %s", e)
+        return {"old": old_type}
+
+    def create_lookup_client(self, dryrun: bool = False) -> dict:
+        """
+        Create a new lookup client using the current configuration.
+
+        Args:
+            dryrun: If True, only return what would be created without
+                actually creating it.
+
+        Returns:
+            dict: Result with new client type info.
+        """
+        # First Party
+        from lmcache.v1.lookup_client.factory import LookupClientFactory
+
+        if self._lmcache_engine_metadata is None:
+            return {"error": "metadata not available"}
+
+        if dryrun:
+            client = LookupClientFactory.create_lookup_client(
+                self._config,
+                self._lmcache_engine_metadata,
+                self._lmcache_engine,
+            )
+            new_type = self._get_lookup_type_str(client)
+            client.close()
+            return {"new": new_type, "dryrun": True}
+
+        self._lookup_client = LookupClientFactory.create_lookup_client(
+            self._config,
+            self._lmcache_engine_metadata,
+            self._lmcache_engine,
+        )
+        new_type = self._get_lookup_type_str(self._lookup_client)
+        logger.info("Created lookup client: %s", new_type)
+        return {"new": new_type}
+
+    def recreate_lookup_client(self) -> dict:
+        """
+        Recreate the lookup client (close + create).
+
+        Returns:
+            dict: Result with old and new client type info.
+        """
+        if self._lookup_client is None:
+            return {"error": "lookup client not available"}
+        result = self.close_lookup_client()
+        create_result = self.create_lookup_client()
+        result.update(create_result)
+        return result
+
+    def close_lookup_server(self) -> dict:
+        """
+        Close the current lookup server.
+
+        Returns:
+            dict: Result with old server type info.
+        """
+        old_type = self._get_lookup_type_str(self._lookup_server)
+        if self._lookup_server is not None:
+            try:
+                self._lookup_server.close()
+                self._lookup_server = None
+                logger.info("Closed lookup server: %s", old_type)
+            except Exception as e:
+                logger.warning("Error closing lookup server: %s", e)
+        return {"old": old_type}
+
+    def create_lookup_server(self, dryrun: bool = False) -> dict:
+        """
+        Create a new lookup server using the current configuration.
+
+        Args:
+            dryrun: If True, only return what would be created without
+                actually creating it.
+
+        Returns:
+            dict: Result with new server type info.
+        """
+        # First Party
+        from lmcache.v1.lookup_client.factory import LookupClientFactory
+
+        if self._lmcache_engine is None:
+            return {"error": "engine not available"}
+        if self._lmcache_engine_metadata is None:
+            return {"error": "metadata not available"}
+
+        if dryrun:
+            server = LookupClientFactory.create_lookup_server(
+                self._lmcache_engine,
+                self._lmcache_engine_metadata,
+            )
+            new_type = self._get_lookup_type_str(server)
+            if server is not None:
+                server.close()
+            return {"new": new_type, "dryrun": True}
+
+        self._lookup_server = LookupClientFactory.create_lookup_server(
+            self._lmcache_engine,
+            self._lmcache_engine_metadata,
+        )
+        new_type = self._get_lookup_type_str(self._lookup_server)
+        logger.info("Created lookup server: %s", new_type)
+        return {"new": new_type}
+
+    def recreate_lookup_server(self) -> dict:
+        """
+        Recreate the lookup server (close + create).
+
+        Returns:
+            dict: Result with old and new server type info.
+        """
+        if self._lookup_server is None:
+            return {"error": "lookup server not available"}
+
+        result = self.close_lookup_server()
+        create_result = self.create_lookup_server()
+        result.update(create_result)
+        return result
+
+    def _get_lookup_type_str(self, obj) -> str:
+        """
+        Get type string for lookup client/server, including wrapper info.
+
+        Returns format: "OuterWrapper(InnerWrapper(CoreType))" or "None"
+        """
+        if obj is None:
+            return "None"
+
+        parts = []
+        current = obj
+        while True:
+            parts.append(type(current).__name__)
+            if hasattr(current, "actual_lookup_client"):
+                current = current.actual_lookup_client
+            else:
+                break
+
+        if len(parts) == 1:
+            return parts[0]
+        result = parts[-1]
+        for wrapper in reversed(parts[:-1]):
+            result = "%s(%s)" % (wrapper, result)
+        return result
+
+    def get_lookup_info(self) -> dict:
+        """
+        Get information about the current lookup client and server.
+
+        Returns:
+            dict: Information about lookup client/server types and role.
+        """
+        return {
+            "client": self._get_lookup_type_str(self._lookup_client),
+            "server": self._get_lookup_type_str(self._lookup_server),
+        }
+
+    # ==================== Health & Info ====================
+
+    def is_healthy(self) -> bool:
+        """
+        Check if the LMCacheManager is healthy.
+
+        Returns False if:
+        - Initialization failed
+        - HealthMonitor reports unhealthy
+        - Engine reports unhealthy
+
+        Returns:
+            bool: True if healthy, False otherwise
+        """
+        if self._init_failed:
+            return False
+        if self._lmcache_engine is not None and not self._lmcache_engine.is_healthy():
+            return False
+        if self._health_monitor is not None:
+            return self._health_monitor.is_healthy()
+        return True
+
+    def get_inference_info(self) -> dict:
+        """Get inference information by delegating to the connector.
+
+        Returns:
+            dict: Dictionary containing inference information,
+                  or empty dict if connector is not available.
+        """
+        if self._connector is not None and hasattr(
+            self._connector, "get_inference_info"
+        ):
+            return self._connector.get_inference_info()
+        return {}
diff --git a/lmcache/v1/memory_allocators/__init__.py b/lmcache/v1/memory_allocators/__init__.py
new file mode 100644
index 0000000..aa81e7a
--- /dev/null
+++ b/lmcache/v1/memory_allocators/__init__.py
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from importlib import import_module
+
+_EXPORT_TO_MODULE = {
+    "AdHocMemoryAllocator": "ad_hoc_memory_allocator",
+    "BufferAllocator": "buffer_allocator",
+    "CuFileMemoryAllocator": "cu_file_memory_allocator",
+    "DevDaxMemoryAllocator": "devdax_memory_allocator",
+    "GPUMemoryAllocator": "gpu_memory_allocator",
+    "HipFileMemoryAllocator": "hip_file_memory_allocator",
+    "HostMemoryAllocator": "host_memory_allocator",
+    "LazyMemoryAllocator": "lazy_memory_allocator",
+    "MixedMemoryAllocator": "mixed_memory_allocator",
+    "PagedCpuGpuMemoryAllocator": "paged_cpu_gpu_memory_allocator",
+    "PagedTensorMemoryAllocator": "paged_tensor_memory_allocator",
+    "PinMemoryAllocator": "pin_memory_allocator",
+    "TensorMemoryAllocator": "tensor_memory_allocator",
+}
+
+
+def __getattr__(name: str) -> object:
+    """Lazily re-export allocator classes without eager package imports.
+
+    Args:
+        name: Exported allocator or helper name.
+
+    Returns:
+        The requested object from its concrete allocator module.
+
+    Raises:
+        AttributeError: If ``name`` is not exported by this package.
+    """
+    module_name = _EXPORT_TO_MODULE.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module = import_module(f"{__name__}.{module_name}")
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+__all__ = list(_EXPORT_TO_MODULE)
diff --git a/lmcache/v1/memory_allocators/ad_hoc_memory_allocator.py b/lmcache/v1/memory_allocators/ad_hoc_memory_allocator.py
new file mode 100644
index 0000000..4b5bf6f
--- /dev/null
+++ b/lmcache/v1/memory_allocators/ad_hoc_memory_allocator.py
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import List, Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+
+
+class AdHocMemoryAllocator(MemoryAllocatorInterface):
+    """
+    AdHocMemoryAllocator is a simple allocator that does not actually
+    allocate memory. It is used for testing purposes only.
+    """
+
+    def __init__(self, device: str = "cpu") -> None:
+        """
+        :param str device: The device of the ad hoc memory allocator.
+        """
+        if not torch_dev.is_available():
+            self.device = "cpu"
+        else:
+            self.device = device
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """
+        Returns a dummy MemoryObj for testing purposes.
+        """
+        shapes, dtypes = self._adapt_shapes_and_dtypes(shapes, dtypes)
+        size = get_size_bytes(shapes, dtypes)
+
+        # Return a dummy object with no actual memory allocation
+        return TensorMemoryObj(
+            raw_data=torch.empty(
+                torch.Size([size]), dtype=torch.uint8, device=self.device
+            ),
+            metadata=MemoryObjMetadata(
+                shape=shapes[0],
+                dtype=dtypes[0],
+                address=0,
+                phy_size=0,
+                ref_count=1,
+                pin_count=0,
+                fmt=fmt,
+                shapes=shapes,
+                dtypes=dtypes,
+            ),
+            parent_allocator=self,
+        )
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate a batch of test memory objects.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in each object's metadata.
+            allocator_type: Optional allocator type string.
+
+        Raises:
+            NotImplementedError: Always raised because ad-hoc batched
+                allocation is not supported.
+        """
+        raise NotImplementedError(
+            "Batched allocation is not supported in AdHocMemoryAllocator"
+        )
+
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Release a test memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+        """
+        pass
+
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Release a batch of test memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        pass
+
+    def ref_count_up(self, memory_obj: MemoryObj) -> None:
+        """Increment the reference count for a test memory object.
+
+        Args:
+            memory_obj: Memory object whose reference count would be incremented.
+        """
+        pass
+
+    def ref_count_down(self, memory_obj: MemoryObj) -> None:
+        """Decrement the reference count for a test memory object.
+
+        Args:
+            memory_obj: Memory object whose reference count would be decremented.
+        """
+        pass
+
+    def get_ref_count(self, memory_obj: MemoryObj) -> int:
+        """Return the reference count for a test memory object.
+
+        Args:
+            memory_obj: Memory object to inspect.
+
+        Returns:
+            Always returns 0 because this test allocator does not track counts.
+        """
+        return 0
+
+    def memcheck(self) -> bool:
+        """Return whether allocator state is consistent."""
+        return True
+
+    def __str__(self) -> str:
+        return "AdHocMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/buffer_allocator.py b/lmcache/v1/memory_allocators/buffer_allocator.py
new file mode 100644
index 0000000..3114884
--- /dev/null
+++ b/lmcache/v1/memory_allocators/buffer_allocator.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import List, Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_management import (
+    BytesBufferMemoryObj,
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+
+
+class BufferAllocator(MemoryAllocatorInterface):
+    """Allocates memory in the pre-allocated pinned memory."""
+
+    def __init__(self, device: str = "cpu") -> None:
+        """
+        :param str device: The device of the buffer memory.
+        """
+        self.device = device
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.BINARY_BUFFER,
+        allocator_type: Optional[str] = None,
+    ) -> BytesBufferMemoryObj:
+        """Allocate one byte-buffer memory object.
+
+        Args:
+            shapes: Buffer shape. The first dimension is used as byte length.
+            dtypes: Unused dtype argument kept for allocator interface parity.
+            fmt: Memory format for the allocation.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A bytes-backed memory object.
+        """
+        if isinstance(shapes, list):
+            n = shapes[0][0]
+        else:
+            n = shapes[0]
+        byte_array = bytearray(n)
+        return BytesBufferMemoryObj(byte_array)
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.BINARY_BUFFER,
+        allocator_type: Optional[str] = None,
+    ) -> List[BytesBufferMemoryObj]:
+        """Allocate multiple byte-buffer memory objects.
+
+        Args:
+            shapes: Buffer shape. The first dimension is used as byte length.
+            dtypes: Unused dtype argument kept for allocator interface parity.
+            batch_size: Number of buffers to allocate.
+            fmt: Memory format for each allocation.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Bytes-backed memory objects.
+        """
+        if isinstance(shapes, list):
+            n = shapes[0][0]
+        else:
+            n = shapes[0]
+        # TODO(Jiayi): Optimize the following loop.
+        byte_arrays = [bytearray(n) for _ in range(batch_size)]
+        return [BytesBufferMemoryObj(byte_array) for byte_array in byte_arrays]
+
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Release a byte-buffer memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+        """
+        return
+
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Release byte-buffer memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        return
+
+    def __str__(self) -> str:
+        return "BufferAllocator"
+
+    def memcheck(self) -> bool:
+        """Return whether allocator state is consistent."""
+        return True
diff --git a/lmcache/v1/memory_allocators/cu_file_memory_allocator.py b/lmcache/v1/memory_allocators/cu_file_memory_allocator.py
new file mode 100644
index 0000000..0295a48
--- /dev/null
+++ b/lmcache/v1/memory_allocators/cu_file_memory_allocator.py
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+import ctypes
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+
+
+class CuFileMemoryAllocator(GPUMemoryAllocator):
+    def __init__(self, size: int, device=None) -> None:
+        # HACK(Jiayi): cufile import is buggy on some hardware
+        # (e.g., without GPUDirect), so it's temporarily put here.
+        # Third Party
+        from cufile.bindings import cuFileBufDeregister, cuFileBufRegister
+
+        self.cuFileBufDeregister = cuFileBufDeregister
+        if device is None:
+            # TODO(Serapheim): Ideally we'd get the device from the upper
+            # layer - for now just use the current device.
+            if torch_dev.is_available():
+                device = f"{torch_device_type}:{torch_dev.current_device()}"
+            else:
+                device = "cpu:0"
+        super().__init__(size, device, align_bytes=4096)
+        self.base_pointer = self.tensor.data_ptr()
+        cuFileBufRegister(ctypes.c_void_p(self.base_pointer), size, flags=0)
+
+    def __del__(self) -> None:
+        if hasattr(self, "base_pointer") and hasattr(self, "cuFileBufDeregister"):
+            try:
+                self.cuFileBufDeregister(ctypes.c_void_p(self.base_pointer))
+            except Exception:
+                pass
+
+    def __str__(self) -> str:
+        return "CuFileMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/devdax_memory_allocator.py b/lmcache/v1/memory_allocators/devdax_memory_allocator.py
new file mode 100644
index 0000000..d455110
--- /dev/null
+++ b/lmcache/v1/memory_allocators/devdax_memory_allocator.py
@@ -0,0 +1,501 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Any, List, Optional, Union
+import ctypes
+import mmap
+import os
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_allocators.buffer_allocator import BufferAllocator
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    AddressManager,
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+    TensorMemoryObj,
+    logger,
+)
+import lmcache.v1.memory_management as memory_management
+
+
+class DevDaxMemoryAllocator(MemoryAllocatorInterface):
+    """Allocates L1 objects from DRAM and/or an mmap-backed Device-DAX arena.
+
+    The mapped bytes are exposed as a flat CPU ``torch.uint8`` tensor so the
+    existing L1 state machine and tensor slicing logic can run unchanged while
+    the overflow backing storage is the configured Device-DAX device. When a
+    local allocator is provided, local DRAM is tried first and Device-DAX is
+    used as overflow.
+    """
+
+    def __init__(
+        self,
+        size: int,
+        device_path: str,
+        *,
+        local_allocator: MixedMemoryAllocator | None = None,
+        local_size: int = 0,
+        shm_name: str | None = None,
+        align_bytes: int = AddressManager.ALIGN_BYTES,
+    ) -> None:
+        if not device_path:
+            raise ValueError("device_path must be a non-empty string")
+        if size <= 0:
+            raise ValueError("size must be > 0")
+        if local_size < 0:
+            raise ValueError("local_size must be >= 0")
+        if local_size and local_allocator is not None:
+            raise ValueError("local_size cannot be used with local_allocator")
+        if align_bytes <= 0 or align_bytes & (align_bytes - 1) != 0:
+            raise ValueError("align_bytes must be a positive power of two")
+
+        self.size = size
+        self.device_path = device_path
+        self.align_bytes = align_bytes
+        self.local_allocator = local_allocator
+        if local_size:
+            self.local_allocator = MixedMemoryAllocator(
+                local_size,
+                align_bytes=self.align_bytes,
+                shm_name=shm_name,
+            )
+        self.host_mem_lock = threading.Lock()
+        self.buffer_allocator = BufferAllocator("cpu")
+        self.devdax_allocator: TensorMemoryAllocator | None = None
+        self._fd: int | None = None
+        self._mmap_obj: mmap.mmap | None = None
+        self._mmap_buffer: Any | None = None
+        self._unregistered = False
+        self._host_memory_pinned_ptr: int | None = None
+
+        self.devdax_buffer = self._map_devdax()
+        self.devdax_allocator = TensorMemoryAllocator(
+            self.devdax_buffer, align_bytes=self.align_bytes
+        )
+        self.address_manager = self.devdax_allocator.address_manager
+        self._register_cuda_host_memory()
+
+    @property
+    def buffer(self) -> torch.Tensor:
+        """Return the primary L1 buffer exposed by this allocator."""
+        if self.local_allocator is not None:
+            return self.local_allocator.buffer
+        return self.devdax_buffer
+
+    def _open_devdax_mapping(
+        self,
+        device_path: str,
+        size: int,
+    ) -> tuple[int, mmap.mmap, Any, torch.Tensor]:
+        fd: int | None = None
+        mmap_obj: mmap.mmap | None = None
+        try:
+            fd = os.open(device_path, os.O_RDWR)
+            capacity = os.fstat(fd).st_size
+            if capacity > 0 and size > capacity:
+                raise RuntimeError(
+                    f"l1 devdax size ({size} bytes) exceeds "
+                    f"{device_path} capacity ({capacity} bytes)"
+                )
+
+            mmap_obj = mmap.mmap(
+                fd,
+                size,
+                flags=mmap.MAP_SHARED,
+                prot=mmap.PROT_READ | mmap.PROT_WRITE,
+            )
+            array_type = ctypes.c_uint8 * size
+            mmap_buffer = array_type.from_buffer(mmap_obj)
+            buffer = torch.frombuffer(mmap_buffer, dtype=torch.uint8)
+            return fd, mmap_obj, mmap_buffer, buffer
+        except Exception:
+            if mmap_obj is not None:
+                mmap_obj.close()
+            if fd is not None:
+                os.close(fd)
+            raise
+
+    def _map_devdax(self) -> torch.Tensor:
+        fd, mmap_obj, mmap_buffer, buffer = self._open_devdax_mapping(
+            self.device_path,
+            self.size,
+        )
+        self._fd = fd
+        self._mmap_obj = mmap_obj
+        self._mmap_buffer = mmap_buffer
+        return buffer
+
+    def _close_devdax_mapping_locked(self) -> None:
+        self._unregister_cuda_host_memory()
+        self.devdax_allocator = None
+        self.devdax_buffer = torch.empty(0, dtype=torch.uint8)
+        self._mmap_buffer = None
+
+        if self._mmap_obj is not None:
+            self._mmap_obj.close()
+            self._mmap_obj = None
+        if self._fd is not None:
+            os.close(self._fd)
+            self._fd = None
+
+    def _register_cuda_host_memory(self) -> None:
+        if not memory_management.current_device_spec.is_pin_supported:
+            return
+        if not memory_management.current_device_spec.pin_memory(
+            self.devdax_buffer.data_ptr(), self.size
+        ):
+            logger.warning(
+                "pin_memory failed for Device-DAX L1 mapping; "
+                "falling back to pageable host copies"
+            )
+            return
+        self._host_memory_pinned_ptr = self.devdax_buffer.data_ptr()
+
+    def _unregister_cuda_host_memory(self) -> None:
+        if self._host_memory_pinned_ptr is None:
+            return
+        memory_management.current_device_spec.unpin_memory(self._host_memory_pinned_ptr)
+        self._host_memory_pinned_ptr = None
+
+    def _is_local_obj(self, memory_obj: MemoryObj) -> bool:
+        return (
+            self.local_allocator is not None
+            and memory_obj.parent() is self.local_allocator
+        )
+
+    def _is_devdax_obj(self, memory_obj: MemoryObj) -> bool:
+        return memory_obj.parent() is self
+
+    def _local_available_count(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+    ) -> int:
+        if self.local_allocator is None:
+            return 0
+        local_pin_allocator = self.local_allocator.pin_allocator
+        assert isinstance(local_pin_allocator, TensorMemoryAllocator)
+        shapes, dtypes = self._adapt_shapes_and_dtypes(shapes, dtypes)
+        unit_raw_size = get_size_bytes(shapes, dtypes)
+        unit_aligned_size = local_pin_allocator.address_manager.compute_aligned_size(
+            unit_raw_size
+        )
+        return local_pin_allocator.address_manager.get_free_size() // unit_aligned_size
+
+    def _local_memory_usage(self) -> tuple[int, int]:
+        if self.local_allocator is None:
+            return 0, 0
+        local_pin_allocator = self.local_allocator.pin_allocator
+        assert isinstance(local_pin_allocator, TensorMemoryAllocator)
+        local_total = local_pin_allocator.address_manager.get_heap_size()
+        local_used = local_total - local_pin_allocator.address_manager.get_free_size()
+        return local_used, local_total
+
+    def _allocate_from_devdax(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat,
+    ) -> Optional[MemoryObj]:
+        with self.host_mem_lock:
+            assert self.devdax_allocator is not None
+            obj = self.devdax_allocator.allocate(shapes, dtypes, fmt, str(self))
+            if isinstance(obj, TensorMemoryObj):
+                obj.parent_allocator = self
+            return obj
+
+    def _batched_allocate_from_devdax(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat,
+    ) -> Optional[List[MemoryObj]]:
+        with self.host_mem_lock:
+            assert self.devdax_allocator is not None
+            objs = self.devdax_allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt, str(self)
+            )
+            if objs is not None:
+                for obj in objs:
+                    if isinstance(obj, TensorMemoryObj):
+                        obj.parent_allocator = self
+            return objs
+
+    def _free_devdax_obj(self, memory_obj: MemoryObj) -> None:
+        with self.host_mem_lock:
+            assert self.devdax_allocator is not None
+            self.devdax_allocator.free(memory_obj)
+            if isinstance(memory_obj, TensorMemoryObj):
+                memory_obj.raw_data = torch.empty(0, dtype=torch.uint8)
+
+    def _batched_free_devdax_objs(
+        self,
+        memory_objs: List[MemoryObj],
+        update_stats: bool,
+    ) -> None:
+        with self.host_mem_lock:
+            assert self.devdax_allocator is not None
+            self.devdax_allocator.batched_free(memory_objs, update_stats=update_stats)
+            for memory_obj in memory_objs:
+                if isinstance(memory_obj, TensorMemoryObj):
+                    memory_obj.raw_data = torch.empty(0, dtype=torch.uint8)
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """Allocate one object from local DRAM first, then Device-DAX.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format to allocate.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A memory object, or ``None`` if both tiers are full.
+
+        Raises:
+            ValueError: If ``fmt`` is unsupported.
+        """
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            return self.buffer_allocator.allocate(shapes, dtypes, fmt)
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+        ]:
+            if self.local_allocator is not None:
+                obj = self.local_allocator.allocate(shapes, dtypes, fmt, str(self))
+                if obj is not None:
+                    return obj
+            if self.devdax_allocator is None:
+                return None
+            return self._allocate_from_devdax(shapes, dtypes, fmt)
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate multiple objects from local DRAM first, then Device-DAX.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format to allocate.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Memory objects, or ``None`` if the full batch cannot be allocated.
+
+        Raises:
+            ValueError: If ``fmt`` is unsupported.
+        """
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            return self.buffer_allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt
+            )
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+        ]:
+            local_objs: list[MemoryObj] = []
+            if self.local_allocator is not None:
+                local_count = min(
+                    batch_size, self._local_available_count(shapes, dtypes)
+                )
+                if local_count:
+                    local_objs = (
+                        self.local_allocator.batched_allocate(
+                            shapes, dtypes, local_count, fmt, str(self)
+                        )
+                        or []
+                    )
+
+            remaining = batch_size - len(local_objs)
+            if remaining == 0:
+                return local_objs
+
+            if self.devdax_allocator is None:
+                if local_objs and self.local_allocator is not None:
+                    self.local_allocator.batched_free(local_objs, update_stats=False)
+                return None
+
+            dax_objs = self._batched_allocate_from_devdax(
+                shapes, dtypes, remaining, fmt
+            )
+            if dax_objs is None:
+                if local_objs and self.local_allocator is not None:
+                    self.local_allocator.batched_free(local_objs, update_stats=False)
+                return None
+            return local_objs + dax_objs
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    @_lmcache_nvtx_annotate
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Free one Device-DAX allocator memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+
+        Raises:
+            ValueError: If the object format is unsupported or the object does
+                not belong to this allocator.
+        """
+        fmt = memory_obj.meta.fmt
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            self.buffer_allocator.free(memory_obj)
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+        ]:
+            if self._is_local_obj(memory_obj):
+                assert self.local_allocator is not None
+                self.local_allocator.free(memory_obj)
+                return
+            if self._is_devdax_obj(memory_obj):
+                self._free_devdax_obj(memory_obj)
+                return
+            raise ValueError("Memory object does not belong to DevDaxMemoryAllocator")
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    @_lmcache_nvtx_annotate
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple Device-DAX allocator memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+
+        Raises:
+            ValueError: If the object format is unsupported or any object does
+                not belong to this allocator.
+        """
+        if not memory_objs:
+            return
+
+        fmt = memory_objs[0].meta.fmt
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            self.buffer_allocator.batched_free(memory_objs)
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+        ]:
+            local_objs = [
+                memory_obj
+                for memory_obj in memory_objs
+                if self._is_local_obj(memory_obj)
+            ]
+            devdax_objs = [
+                memory_obj
+                for memory_obj in memory_objs
+                if self._is_devdax_obj(memory_obj)
+            ]
+            if len(local_objs) + len(devdax_objs) != len(memory_objs):
+                raise ValueError(
+                    "One or more memory objects do not belong to DevDaxMemoryAllocator"
+                )
+            if local_objs:
+                assert self.local_allocator is not None
+                self.local_allocator.batched_free(local_objs, update_stats=update_stats)
+            if devdax_objs:
+                self._batched_free_devdax_objs(devdax_objs, update_stats=update_stats)
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    def memcheck(self) -> bool:
+        """Return whether local and Device-DAX allocator state is consistent."""
+        local_ok = True
+        if self.local_allocator is not None:
+            local_ok = self.local_allocator.memcheck()
+        with self.host_mem_lock:
+            if self.devdax_allocator is None:
+                return local_ok
+            return local_ok and self.devdax_allocator.memcheck()
+
+    def get_memory_usage(self) -> tuple[int, int]:
+        """Return used and total bytes across local and Device-DAX tiers."""
+        local_used, local_total = self._local_memory_usage()
+
+        if self.devdax_allocator is None:
+            return local_used, local_total
+        dax_total = self.devdax_allocator.address_manager.get_heap_size()
+        dax_used = dax_total - self.devdax_allocator.address_manager.get_free_size()
+        return local_used + dax_used, local_total + dax_total
+
+    def close(self) -> None:
+        """Release mapped Device-DAX and optional local DRAM resources.
+
+        Raises:
+            BufferError: If Device-DAX allocations are still active.
+        """
+        if self._unregistered:
+            return
+        if memory_management.torch_dev.is_available():
+            memory_management.torch_dev.synchronize()
+
+        with self.host_mem_lock:
+            if (
+                self.devdax_allocator is not None
+                and self.devdax_allocator.num_active_allocations > 0
+            ):
+                raise BufferError(
+                    "cannot close DevDaxMemoryAllocator with active allocations"
+                )
+            self._close_devdax_mapping_locked()
+
+        if self.local_allocator is not None:
+            self.local_allocator.close()
+            self.local_allocator = None
+        self._unregistered = True
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def __str__(self) -> str:
+        return "DevDaxMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/gpu_memory_allocator.py b/lmcache/v1/memory_allocators/gpu_memory_allocator.py
new file mode 100644
index 0000000..6136e77
--- /dev/null
+++ b/lmcache/v1/memory_allocators/gpu_memory_allocator.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from contextlib import nullcontext
+from typing import List, Optional, Union
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+
+
+class GPUMemoryAllocator(MemoryAllocatorInterface):
+    """Allocates memory in the pre-allocated GPU memory."""
+
+    def __init__(
+        self,
+        size: int,
+        device=torch_device_type,
+        align_bytes: Optional[int] = None,
+        use_paging: bool = False,
+        **kwargs,
+    ) -> None:
+        """
+        :param int size: The size of the GPU memory in bytes.
+        :param Optional[int] align_bytes: The byte alignment for allocations.
+        """
+        if not torch_dev.is_available():
+            device = "cpu"
+
+        self.tensor = torch.empty(size, dtype=torch.uint8, device=device)
+
+        self.allocator: MemoryAllocatorInterface
+        if use_paging:
+            assert "shapes" in kwargs, (
+                "shapes must be specified for paged memory allocator"
+            )
+            assert "dtypes" in kwargs, (
+                "dtypes must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.allocator = PagedTensorMemoryAllocator(
+                tensor=self.tensor,
+                shapes=kwargs["shapes"],
+                dtypes=kwargs["dtypes"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            kwargs = {}
+            if align_bytes is not None:
+                kwargs["align_bytes"] = align_bytes
+            self.allocator = TensorMemoryAllocator(self.tensor, **kwargs)
+
+        self.device_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """Allocate one GPU-backed memory object.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A memory object, or ``None`` if the inner allocator is full.
+        """
+        with self.device_mem_lock:
+            return self.allocator.allocate(shapes, dtypes, fmt, str(self))
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate multiple GPU-backed memory objects.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in each returned object's metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Memory objects, or ``None`` if the inner allocator is full.
+        """
+        with self.device_mem_lock:
+            return self.allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt, str(self)
+            )
+
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Free one GPU-backed memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+        """
+        with self.device_mem_lock:
+            self.allocator.free(memory_obj)
+
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple GPU-backed memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        with self.device_mem_lock:
+            self.allocator.batched_free(memory_objs)
+
+    def memcheck(self) -> bool:
+        """Return whether allocator state is consistent."""
+        with self.device_mem_lock:
+            return self.allocator.memcheck()
+
+    def __str__(self) -> str:
+        return "GPUMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/hip_file_memory_allocator.py b/lmcache/v1/memory_allocators/hip_file_memory_allocator.py
new file mode 100644
index 0000000..f47a986
--- /dev/null
+++ b/lmcache/v1/memory_allocators/hip_file_memory_allocator.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+
+
+class HipFileMemoryAllocator(GPUMemoryAllocator):
+    def __init__(self, size: int, device=None) -> None:
+        # HACK: hipfile import is placed here to avoid import errors on
+        # hardware without GPUDirect Storage / hipFile support.
+        # Third Party
+        from hipfile import Buffer
+
+        if device is None:
+            if torch_dev.is_available():
+                # TODO: On ROCm, PyTorch still uses the CUDA API internally
+                device = f"{torch_device_type}:{torch_dev.current_device()}"
+            else:
+                device = "cpu:0"
+
+        super().__init__(size, device, align_bytes=4096)
+        self.base_pointer = self.tensor.data_ptr()
+        self.hipfile_buffer = Buffer(self.base_pointer, size, flags=0)
+        self.hipfile_buffer.register()
+
+    def __del__(self) -> None:
+        try:
+            self.hipfile_buffer.deregister()
+        except Exception:
+            pass
+
+    def __str__(self) -> str:
+        return "HipFileMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/host_memory_allocator.py b/lmcache/v1/memory_allocators/host_memory_allocator.py
new file mode 100644
index 0000000..e2e25eb
--- /dev/null
+++ b/lmcache/v1/memory_allocators/host_memory_allocator.py
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from contextlib import nullcontext
+from typing import List, Optional, Union
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+
+
+class HostMemoryAllocator(MemoryAllocatorInterface):
+    """Allocates memory in the pre-allocated Host memory."""
+
+    def __init__(self, size: int, use_paging: bool = False, **kwargs) -> None:
+        """
+        :param int size: The size of the pinned memory in bytes.
+        """
+        buffer = torch.empty(size, dtype=torch.uint8, device="cpu")
+
+        self.allocator: MemoryAllocatorInterface
+        if use_paging:
+            assert "shapes" in kwargs, (
+                "shapes must be specified for paged memory allocator"
+            )
+            assert "dtypes" in kwargs, (
+                "dtypes must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.allocator = PagedTensorMemoryAllocator(
+                tensor=buffer,
+                shapes=kwargs["shapes"],
+                dtypes=kwargs["dtypes"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.allocator = TensorMemoryAllocator(buffer)
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """Allocate one host-backed memory object.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A memory object, or ``None`` if the inner allocator is full.
+        """
+        with self.host_mem_lock:
+            return self.allocator.allocate(shapes, dtypes, fmt, str(self))
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate multiple host-backed memory objects.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in each returned object's metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Memory objects, or ``None`` if the inner allocator is full.
+        """
+        with self.host_mem_lock:
+            return self.allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt, str(self)
+            )
+
+    @_lmcache_nvtx_annotate
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Free one host-backed memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+        """
+        with self.host_mem_lock:
+            self.allocator.free(memory_obj)
+
+    @_lmcache_nvtx_annotate
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple host-backed memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        with self.host_mem_lock:
+            self.allocator.batched_free(memory_objs)
+
+    def memcheck(self) -> bool:
+        """Return whether allocator state is consistent."""
+        with self.host_mem_lock:
+            return self.allocator.memcheck()
+
+    def __str__(self) -> str:
+        return "HostMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/lazy_memory_allocator.py b/lmcache/v1/memory_allocators/lazy_memory_allocator.py
new file mode 100644
index 0000000..f190ef5
--- /dev/null
+++ b/lmcache/v1/memory_allocators/lazy_memory_allocator.py
@@ -0,0 +1,334 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional, Union
+import ctypes
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    AddressManager,
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.platform import current_device_spec
+from lmcache.v1.system_detection import NUMAMapping
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+# Helper functions
+def get_numa_id(numa_mapping: NUMAMapping) -> int:
+    """
+    Get the NUMA ID for the current GPU
+
+    Args:
+        numa_mapping (NUMAMapping): The NUMA mapping object.
+
+    Returns:
+        int: The NUMA ID for the current GPU.
+
+    Raises:
+        KeyError: If GPU id is not detected in the numa mapping.
+    """
+    gpu_id = torch_dev.current_device() if torch_dev.is_available() else 0
+    return numa_mapping.gpu_to_numa_mapping[gpu_id]
+
+
+def align_to(size: int, align_size: int) -> int:
+    """
+    Align the given size to the nearest multiple of align_size.
+
+    Args:
+        size (int): The size to align.
+        align_size (int): The alignment size, MUST BE a power of two.
+
+    Returns:
+        int: The aligned size.
+    """
+    return (size + align_size - 1) & (~(align_size - 1))
+
+
+# Main class
+class LazyMemoryAllocator(MemoryAllocatorInterface):
+    """
+    Allocates CPU (numa) pinned memory with a initial size and expand
+    the size to the required size in the background.
+
+    Background expansion logic:
+    - After registering X GB memory, we call sbrk and updates _curr_size
+    - Once everything is registered, the background thread stops
+    """
+
+    PIN_CHUNK_SIZE = 1 << 26  # 64 MB pin chunk
+    COMMIT_SIZE = 1 << 30  # Do a commit every 1 GB
+    LOG_INTERVAL = 10 << 30  # Log expansion progress every 10 GB
+
+    def __init__(
+        self,
+        init_size: int,
+        final_size: int,
+        align_bytes: int = AddressManager.ALIGN_BYTES,
+        numa_mapping: NUMAMapping | None = None,
+    ) -> None:
+        """
+        Args:
+            init_size (int): Initial size of the memory allocation in bytes.
+            final_size (int): Final size of the memory allocation in bytes.
+            align_bytes (int, optional): Alignment in for the underlying allocations
+        """
+        # Whether using NUMA allocation
+        self._use_numa = numa_mapping is not None
+        # Currently pinned size, only accessed by the expansion thread
+        self._curr_size = align_to(init_size, self.PIN_CHUNK_SIZE)
+        # Final size of the allocation, only accessed by the expansion thread
+        self._final_size = align_to(final_size, self.PIN_CHUNK_SIZE)
+        # Underlying buffer for the memory allocation
+        self._buffer: torch.Tensor
+        if not current_device_spec.is_pin_supported:
+            raise RuntimeError(
+                f"Backend '{torch_device_type}' does not support memory "
+                "pinning. LazyMemoryAllocator requires pinned memory."
+            )
+
+        # List of (ptr, size) for pinned memory chunks
+        self._pin_record: list[tuple[int, int]] = []
+
+        # Detect numa mapping
+        if numa_mapping is not None:
+            numa_id = get_numa_id(numa_mapping)
+            ptr = lmc_ops.alloc_numa_ptr(self._final_size, numa_id)
+            arr_type = ctypes.c_uint8 * self._final_size
+            buf = arr_type.from_address(ptr)
+            self._buffer = torch.frombuffer(buf, dtype=torch.uint8)
+        else:
+            self._buffer = torch.empty(
+                self._final_size, dtype=torch.uint8, device="cpu", pin_memory=False
+            )
+
+        # Pin the first `curr_size` bytes (aligned to the internal chunk size)
+        self._pin_memory_chunk(0, self._curr_size)
+
+        # Create the tensor memory allocator
+        self._allocator = TensorMemoryAllocator(
+            tensor=self._buffer,
+            align_bytes=align_bytes,
+            init_address_space=self._curr_size,
+        )
+
+        # Get the address manager
+        # NOTE(ApostaC): this assumes the tensor memory allocator owns the address
+        # manager, which creates extra coupling in the code.
+        # NOTE(ApostaC): this also assumes that the behavior of the allocation is
+        # completely determined by the address manager.
+        self._address_manager = self._allocator.address_manager
+
+        # Launch the background expansion thread
+        self._stop_expand = threading.Event()
+        self._expand_thread = threading.Thread(
+            target=self._expand_worker, daemon=True, name="lazy-mem-expand-thread"
+        )
+        self._expand_thread.start()
+
+    # Public methods
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.UNDEFINED,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """Allocate one object from the lazily pinned memory pool.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A memory object, or ``None`` if the committed address space is full.
+        """
+        obj = self._allocator.allocate(shapes, dtypes, fmt, allocator_type)
+        # HACK(ApostaC): reset the parent allocator to this lazy allocator
+        # There should be a cleaner way to decouple lazy allocator and
+        # tensor memory allocator
+        if obj is not None:
+            obj.parent_allocator = self
+        return obj
+
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.UNDEFINED,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate a batch of objects from the lazily pinned memory pool.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate for each object.
+            dtypes: Logical tensor dtype or dtypes to allocate for each object.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Memory objects for the batch, or ``None`` if allocation fails.
+        """
+        # HACK(ApostaC): reset the parent allocator to this lazy allocator
+        # There should be a cleaner way to decouple lazy allocator and
+        # tensor memory allocator
+        ret = self._allocator.batched_allocate(
+            shapes, dtypes, batch_size, fmt, allocator_type
+        )
+
+        if ret is None:
+            return ret
+
+        for obj in ret:
+            obj.parent_allocator = self
+        return ret
+
+    def free(
+        self,
+        memory_obj: MemoryObj,
+        allocator_type: Optional[str] = None,
+    ) -> None:
+        """Free one memory object back to the lazy allocator.
+
+        Args:
+            memory_obj: The memory object to free.
+            allocator_type: Optional allocator type string.
+        """
+        self._allocator.free(memory_obj, allocator_type)
+
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free a batch of memory objects back to the lazy allocator.
+
+        Args:
+            memory_objs: Memory objects to free.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        self._allocator.batched_free(memory_objs, allocator_type, update_stats)
+
+    def close(self) -> None:
+        """Stop background expansion and release pinned or NUMA memory."""
+        # Stop the background expansion thread
+        self._stop_expand.set()
+        self._expand_thread.join()
+
+        # Unpin all pinned memory chunks
+        for ptr, size in self._pin_record:
+            current_device_spec.unpin_memory(ptr)
+        self._pin_record.clear()
+
+        # Free the underlying buffer if using NUMA allocation
+        if self._use_numa:
+            lmc_ops.free_numa_ptr(self._buffer.data_ptr(), self._final_size)
+
+    def memcheck(self) -> bool:
+        """Return whether the delegated tensor allocator is consistent."""
+        return self._allocator.memcheck()
+
+    def get_underlying_buffer(self) -> torch.Tensor:
+        """
+        Get the underlying buffer tensor. Will be used by RDMA registrations.
+        """
+        return self._buffer
+
+    def get_address_manager(self) -> AddressManager:
+        """
+        Get the address manager used by this allocator.
+        """
+        return self._address_manager
+
+    # Helper functions
+    def _pin_memory_chunk(self, offset: int, size: int) -> None:
+        """
+        Pin a chunk of memory.
+
+        Args:
+            offset (int): Offset in the buffer to pin.
+            size (int): Size of the memory chunk in bytes.
+        """
+        assert offset & (self.PIN_CHUNK_SIZE - 1) == 0, (
+            "Offset must be aligned to PIN_CHUNK_SIZE"
+        )
+        assert size & (self.PIN_CHUNK_SIZE - 1) == 0, (
+            "Size must be aligned to PIN_CHUNK_SIZE"
+        )
+        assert offset + size <= self._final_size, "Pinning exceeds buffer size"
+
+        ptr = self._buffer.data_ptr() + offset
+        # Use flag: cudaHostRegisterMapped (0x02)
+        if not current_device_spec.pin_memory(ptr, size, 2):
+            logger.warning(
+                "pin_memory failed for chunk at ptr=%#x size=%d; "
+                "DMA performance may be degraded",
+                ptr,
+                size,
+            )
+        else:
+            self._pin_record.append((ptr, size))
+
+    def _commit_expansion(self, expand_size: int) -> None:
+        """
+        Call sbrk in the address manager to commit the expansion.
+        """
+        self._address_manager.sbrk(expand_size)
+
+    def _log_expansion_progress(self, expanded_since_last_log: int) -> None:
+        """
+        Log the cumulative expansion progress since the last log.
+        """
+        percent = 100.0 * self._curr_size / self._final_size
+        logger.info(
+            "LazyMemoryAllocator: Expanded %s MB pinned memory, "
+            "now total is %s MB / %s MB (%.1f%%)",
+            expanded_since_last_log >> 20,
+            self._curr_size >> 20,
+            self._final_size >> 20,
+            percent,
+        )
+
+    def _expand_worker(self) -> None:
+        """
+        Background worker to expand the pinned memory.
+        """
+        last_commit_size = self._curr_size
+        last_log_size = self._curr_size
+        while self._curr_size < self._final_size and not self._stop_expand.is_set():
+            # Expand chunk by chunk and commit
+            for i in range(self.COMMIT_SIZE // self.PIN_CHUNK_SIZE):
+                if self._curr_size >= self._final_size:
+                    break
+                self._pin_memory_chunk(self._curr_size, self.PIN_CHUNK_SIZE)
+                self._curr_size += self.PIN_CHUNK_SIZE
+
+            expand_size = self._curr_size - last_commit_size
+            self._commit_expansion(expand_size)
+            last_commit_size = self._curr_size
+
+            # Log every LOG_INTERVAL bytes, and always on the final commit.
+            expanded_since_last_log = self._curr_size - last_log_size
+            if (
+                expanded_since_last_log >= self.LOG_INTERVAL
+                or self._curr_size >= self._final_size
+            ):
+                self._log_expansion_progress(expanded_since_last_log)
+                last_log_size = self._curr_size
diff --git a/lmcache/v1/memory_allocators/mixed_memory_allocator.py b/lmcache/v1/memory_allocators/mixed_memory_allocator.py
new file mode 100644
index 0000000..06202b6
--- /dev/null
+++ b/lmcache/v1/memory_allocators/mixed_memory_allocator.py
@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from contextlib import nullcontext
+from typing import List, Optional, Union
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_allocators.buffer_allocator import BufferAllocator
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    AddressManager,
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+    TensorMemoryObj,
+)
+import lmcache.v1.memory_management as memory_management
+
+
+class MixedMemoryAllocator(MemoryAllocatorInterface):
+    """
+    Allocates (1) memory in the pre-allocated pinned memory.
+              (2) byte_array buffer memory.
+    """
+
+    def __init__(
+        self, size: int, use_paging: bool = False, use_hugepages: bool = False, **kwargs
+    ) -> None:
+        """
+        :param int size: The size of the pinned memory in bytes.
+        :param bool use_hugepages: Whether to use hugepages.
+        """
+
+        self.numa_mapping = kwargs.get("numa_mapping", None)
+        self.use_hugepages = use_hugepages
+        self.align_bytes = kwargs.get("align_bytes", AddressManager.ALIGN_BYTES)
+        if self.align_bytes <= 0 or self.align_bytes & (self.align_bytes - 1) != 0:
+            raise ValueError("align_bytes must be a positive power of two")
+
+        # Extract shm_name from config.extra_config if available
+        config = kwargs.get("config", None)
+        if config is not None:
+            self.shm_name: Optional[str] = config.get_extra_config_value(
+                "shm_name", None
+            )
+        else:
+            self.shm_name = kwargs.get("shm_name", None)
+
+        self.size = size
+
+        self.buffer = memory_management._allocate_cpu_memory(
+            size, self.numa_mapping, self.shm_name, use_hugepages=use_hugepages
+        )
+
+        self._unregistered = False
+
+        self.pin_allocator: MemoryAllocatorInterface
+        if use_paging:
+            assert "shapes" in kwargs, (
+                "shapes must be specified for paged memory allocator"
+            )
+            assert "dtypes" in kwargs, (
+                "dtypes must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.pin_allocator = PagedTensorMemoryAllocator(
+                tensor=self.buffer,
+                shapes=kwargs["shapes"],
+                dtypes=kwargs["dtypes"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.pin_allocator = TensorMemoryAllocator(
+                self.buffer, align_bytes=self.align_bytes
+            )
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+        self.buffer_allocator = BufferAllocator("cpu")
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """Allocate one object from the mixed pinned/buffer allocator.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format to allocate.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A memory object, or ``None`` if the selected allocator is full.
+
+        Raises:
+            ValueError: If ``fmt`` is unsupported.
+        """
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            return self.buffer_allocator.allocate(shapes, dtypes, fmt)
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+            MemoryFormat.HS_TD,
+        ]:
+            with self.host_mem_lock:
+                obj = self.pin_allocator.allocate(shapes, dtypes, fmt, str(self))
+                if isinstance(obj, TensorMemoryObj):
+                    obj.parent_allocator = self
+                return obj
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate multiple objects from the mixed pinned/buffer allocator.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format to allocate.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Memory objects, or ``None`` if the selected allocator is full.
+
+        Raises:
+            ValueError: If ``fmt`` is unsupported.
+        """
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            return self.buffer_allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt
+            )
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+            MemoryFormat.HS_TD,
+        ]:
+            with self.host_mem_lock:
+                objs = self.pin_allocator.batched_allocate(
+                    shapes, dtypes, batch_size, fmt, str(self)
+                )
+                if objs is not None:
+                    for obj in objs:
+                        if isinstance(obj, TensorMemoryObj):
+                            obj.parent_allocator = self
+                return objs
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    @_lmcache_nvtx_annotate
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Free one mixed-format memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+
+        Raises:
+            ValueError: If the object's memory format is unsupported.
+        """
+        fmt = memory_obj.meta.fmt
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            self.buffer_allocator.free(memory_obj)
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+            MemoryFormat.HS_TD,
+        ]:
+            with self.host_mem_lock:
+                self.pin_allocator.free(memory_obj)
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    @_lmcache_nvtx_annotate
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple mixed-format memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+
+        Raises:
+            ValueError: If the objects' memory format is unsupported.
+        """
+        if not memory_objs:
+            return
+
+        # NOTE: fmts of all memory_objs should be the same
+        fmt = memory_objs[0].meta.fmt
+        if fmt == MemoryFormat.BINARY_BUFFER:
+            self.buffer_allocator.batched_free(memory_objs)
+        elif fmt in [
+            MemoryFormat.KV_2LTD,
+            MemoryFormat.KV_2TD,
+            MemoryFormat.KV_T2D,
+            MemoryFormat.KV_MLA_FMT,
+            MemoryFormat.EC_TD,
+            MemoryFormat.HS_TD,
+        ]:
+            with self.host_mem_lock:
+                self.pin_allocator.batched_free(memory_objs)
+        else:
+            raise ValueError(f"Unsupported memory format: {fmt}")
+
+    def memcheck(self) -> bool:
+        """Return whether allocator state is consistent."""
+        with self.host_mem_lock:
+            return self.pin_allocator.memcheck()
+
+    def close(self) -> None:
+        """Release the owned pinned CPU arena."""
+        if not self._unregistered:
+            if torch_dev.is_available():
+                torch_dev.synchronize()
+            if self.buffer.numel() == 0:
+                return
+            memory_management._free_cpu_memory(
+                self.buffer,
+                self.size,
+                self.numa_mapping,
+                self.shm_name,
+                use_hugepages=self.use_hugepages,
+            )
+            self._unregistered = True
+
+    def get_paged_buffers(self) -> Optional[tuple[torch.Tensor, ...]]:
+        """
+        Get the paged buffers for fixed buffer registration.
+
+        Returns:
+            Tuple of paged buffer tensors if using paged allocator, None otherwise.
+            These buffers can be registered with io_uring for true zero copy operations.
+        """
+        if isinstance(self.pin_allocator, PagedTensorMemoryAllocator):
+            return self.pin_allocator.get_paged_buffers()
+        return None
+
+    def __str__(self) -> str:
+        return "MixedMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/paged_cpu_gpu_memory_allocator.py b/lmcache/v1/memory_allocators/paged_cpu_gpu_memory_allocator.py
new file mode 100644
index 0000000..d3d01e4
--- /dev/null
+++ b/lmcache/v1/memory_allocators/paged_cpu_gpu_memory_allocator.py
@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import List, Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.system_detection import NUMAMapping
+import lmcache.v1.memory_management as memory_management
+
+
+class PagedCpuGpuMemoryAllocator(MemoryAllocatorInterface):
+    """
+    Paged Memory Allocator for both CPU and GPU memory.
+    This is a paged memory allocator for PD and P2P sharing
+    when NIXL is enabled as NIXL relies on the paging abstraction.
+    """
+
+    def __init__(self) -> None:
+        self.cpu_buffer: torch.Tensor | None = None
+        self.cpu_size = 0
+        self.cpu_numa_mapping: Optional[NUMAMapping] = None
+
+    def init_gpu_memory_allocator(
+        self,
+        size: int,
+        shapes: list[torch.Size],
+        dtypes: list[torch.dtype],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        device: str = torch_device_type,
+    ) -> None:
+        """Initialize the GPU paged allocator.
+
+        Args:
+            size: GPU arena size in bytes.
+            shapes: Logical tensor shapes served by each page.
+            dtypes: Logical tensor dtypes served by each page.
+            fmt: Memory format served by each page.
+            device: Torch device string for the GPU arena.
+        """
+        self.gpu_buffer = torch.empty(
+            size,
+            dtype=torch.uint8,
+            device=device,
+        )
+        self.gpu_allocator = PagedTensorMemoryAllocator(
+            self.gpu_buffer,
+            shapes,
+            dtypes,
+            fmt,
+        )
+
+    def init_cpu_memory_allocator(
+        self,
+        size: int,
+        shapes: list[torch.Size],
+        dtypes: list[torch.dtype],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        numa_mapping: Optional[NUMAMapping] = None,
+    ) -> None:
+        """Initialize the CPU paged allocator.
+
+        Args:
+            size: CPU arena size in bytes.
+            shapes: Logical tensor shapes served by each page.
+            dtypes: Logical tensor dtypes served by each page.
+            fmt: Memory format served by each page.
+            numa_mapping: Optional NUMA placement for pinned CPU allocation.
+        """
+        self.cpu_buffer = memory_management._allocate_cpu_memory(size, numa_mapping)
+        self.cpu_size = size
+        self.cpu_numa_mapping = numa_mapping
+        self.cpu_allocator = PagedTensorMemoryAllocator(
+            self.cpu_buffer,
+            shapes,
+            dtypes,
+            fmt,
+        )
+        self.align_bytes = self.cpu_allocator.align_bytes
+
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.UNDEFINED,
+        allocator_type: Optional[str] = "cpu",
+    ) -> Optional[MemoryObj]:
+        """Allocate from the selected CPU or GPU paged allocator.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: ``"cpu"`` or ``"gpu"``.
+
+        Returns:
+            A memory object, or ``None`` when the selected allocator is full.
+
+        Raises:
+            ValueError: If ``allocator_type`` is unsupported.
+        """
+        if allocator_type == "gpu":
+            return self.gpu_allocator.allocate(shapes, dtypes, fmt)
+        elif allocator_type == "cpu":
+            return self.cpu_allocator.allocate(shapes, dtypes, fmt)
+        else:
+            raise ValueError(f"Unsupported allocator type: {allocator_type}")
+
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.UNDEFINED,
+        allocator_type: Optional[str] = "gpu",
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate a batch from the selected CPU or GPU paged allocator.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in each returned object's metadata.
+            allocator_type: ``"cpu"`` or ``"gpu"``.
+
+        Returns:
+            Memory objects, or ``None`` when the selected allocator is full.
+
+        Raises:
+            ValueError: If ``allocator_type`` is unsupported.
+        """
+        if allocator_type == "gpu":
+            return self.gpu_allocator.batched_allocate(shapes, dtypes, batch_size, fmt)
+        elif allocator_type == "cpu":
+            return self.cpu_allocator.batched_allocate(shapes, dtypes, batch_size, fmt)
+        else:
+            raise ValueError(f"Unsupported allocator type: {allocator_type}")
+
+    def free(
+        self, memory_obj: MemoryObj, allocator_type: Optional[str] = "cpu"
+    ) -> None:
+        """Free one CPU or GPU paged memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: ``"cpu"`` or ``"gpu"``.
+
+        Raises:
+            ValueError: If ``allocator_type`` is unsupported.
+        """
+        if allocator_type == "gpu":
+            self.gpu_allocator.free(memory_obj)
+        elif allocator_type == "cpu":
+            self.cpu_allocator.free(memory_obj)
+        else:
+            raise ValueError(f"Unsupported allocator type: {allocator_type}")
+
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple CPU or GPU paged memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: ``"cpu"`` or ``"gpu"``.
+            update_stats: Whether to update allocator statistics.
+
+        Raises:
+            ValueError: If ``allocator_type`` is unsupported.
+        """
+        if allocator_type == "gpu":
+            self.gpu_allocator.batched_free(memory_objs, update_stats=update_stats)
+        elif allocator_type == "cpu":
+            self.cpu_allocator.batched_free(memory_objs, update_stats=update_stats)
+        else:
+            raise ValueError(f"Unsupported allocator type: {allocator_type}")
+
+    def close(self) -> None:
+        """Release the owned pinned CPU arena, if initialized."""
+        if self.cpu_buffer is not None and self.cpu_buffer.numel() > 0:
+            memory_management._free_cpu_memory(
+                self.cpu_buffer,
+                self.cpu_size,
+                self.cpu_numa_mapping,
+            )
+            self.cpu_buffer = torch.empty(0, dtype=torch.uint8)
+            self.cpu_size = 0
+            self.cpu_numa_mapping = None
+
+    def __str__(self) -> str:
+        return "PDMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/paged_tensor_memory_allocator.py b/lmcache/v1/memory_allocators/paged_tensor_memory_allocator.py
new file mode 100644
index 0000000..4f35d70
--- /dev/null
+++ b/lmcache/v1/memory_allocators/paged_tensor_memory_allocator.py
@@ -0,0 +1,345 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from collections import deque
+from typing import List, Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+    logger,
+)
+
+
+class PagedAddressManager:
+    """
+    A lightweight address manager for PagedTensorMemoryAllocator.
+    Provides get_free_size() and get_heap_size() by reading the
+    paged allocator's state.
+    """
+
+    def __init__(self, paged_allocator: "PagedTensorMemoryAllocator") -> None:
+        self._allocator = paged_allocator
+
+    def get_heap_size(self) -> int:
+        """Get the total size of the paged address space in bytes."""
+        return self._allocator.buffer_size
+
+    def get_free_size(self) -> int:
+        """Get the total free size in bytes."""
+        return len(self._allocator.free_blocks) * self._allocator.align_bytes
+
+
+class PagedTensorMemoryAllocator(MemoryAllocatorInterface):
+    """
+    Implements a paged memory allocator.
+    """
+
+    def __init__(
+        self,
+        tensor: torch.Tensor,
+        shapes: list[torch.Size],
+        dtypes: list[torch.dtype],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+    ) -> None:
+        self.buffer = tensor.view(torch.uint8).flatten()
+        self.buffer_size = self.buffer.numel() * self.buffer.element_size()
+        self.buffer_ptr = self.buffer.data_ptr()
+
+        self.shapes = shapes
+        self.dtypes = dtypes
+        self.fmt = fmt
+
+        # full chunk size bytes
+        self.align_bytes = get_size_bytes(shapes, dtypes)
+
+        assert self.buffer_size % self.align_bytes == 0, (
+            f"Buffer size {self.buffer_size} must be a"
+            f" multiple of align bytes {self.align_bytes}"
+            " in paged memory allocator."
+        )
+
+        self.paged_buffers = torch.split(self.buffer, self.align_bytes, dim=0)
+
+        # NOTE: deque is used since thread-safety is not a concern here as
+        # is implemented in C under the hood (in CPython), and operations
+        # on deque are atomic.
+        self.free_blocks: deque[TensorMemoryObj] = deque()
+
+        for idx, buf in enumerate(self.paged_buffers):
+            # NOTE: idx is the paged index
+            # NOTE: the last unfull chunk's shape needs to be
+            # adjusted during allocation.
+            metadata = MemoryObjMetadata(
+                self.shapes[0],
+                self.dtypes[0],
+                idx,
+                self.align_bytes,  # 1 page
+                1,  # ref_count=1
+                0,  # pin_count=0
+                self.fmt,
+                shapes=self.shapes,
+                dtypes=self.dtypes,
+            )
+            mem_obj = TensorMemoryObj(
+                raw_data=buf,
+                metadata=metadata,
+                parent_allocator=self,
+            )
+            self.free_blocks.append(mem_obj)
+
+        # Address manager for memory usage tracking
+        self.address_manager = PagedAddressManager(self)
+
+        # For debugging purposes
+        self.num_active_allocations = 0
+        self.total_allocated_size = 0
+
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+        logger.info(
+            "Paged tensor memory allocator initialized, "
+            "shapes: %s, dtypes: %s, align bytes: %s",
+            self.shapes,
+            self.dtypes,
+            self.align_bytes,
+        )
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[TensorMemoryObj]:
+        """Allocate one page-backed memory object.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A page-backed tensor memory object, or ``None`` if no page is free.
+        """
+        shapes, dtypes = self._adapt_shapes_and_dtypes(shapes, dtypes)
+
+        try:
+            free_block = self.free_blocks.popleft()
+        except IndexError:
+            logger.debug(
+                f"Failed to allocate memory for "
+                f"tensor({shapes}, {dtypes}) because "
+                "no free blocks is available"
+            )
+            return None
+
+        # TODO (Jiayi): This is a bit redundant.
+        free_block.meta.shape = shapes[0]
+        free_block.meta.dtype = dtypes[0]
+        free_block.meta.shapes = shapes
+        free_block.meta.dtypes = dtypes
+        free_block.meta.fmt = fmt
+        free_block.meta.ref_count = 1
+        # Reset any narrowed-size override left over from the previous
+        # owner of this block, so get_size() returns the layout-derived
+        # size for the fresh allocation.
+        free_block._used_size_override = None
+
+        if shapes != self.shapes:
+            size_in_bytes = get_size_bytes(shapes, dtypes)
+            free_block.raw_data = free_block.raw_data[:size_in_bytes]
+
+        # TODO (Jiayi): need a flag to drop these debug ops
+        # NOTE (Jiayi): the following code is not thread-safe but
+        # is tolerable as this is only used for debugging purposes.
+        # Update debug status
+        self.num_active_allocations += 1
+        self.total_allocated_size += self.align_bytes
+        self.stats_monitor.update_local_cache_usage(self.total_allocated_size)
+        self.stats_monitor.update_active_memory_objs_count(self.num_active_allocations)
+
+        # Allocate the block
+        return free_block
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[TensorMemoryObj]]:
+        """
+        Batched allocate tensor memory objs with pre-defined equal sizes.
+        """
+        shapes, dtypes = self._adapt_shapes_and_dtypes(shapes, dtypes)
+
+        allocated_blocks: list[TensorMemoryObj] = []
+        for i in range(batch_size):
+            try:
+                free_block = self.free_blocks.popleft()
+            except IndexError:
+                logger.debug(
+                    f"Failed to allocate memory for "
+                    f"tensor({shapes}, {dtypes}) because "
+                    "no free blocks is available"
+                )
+                self.batched_free(allocated_blocks, update_stats=False)
+                return None
+
+            # FIXME: think about whether parent_allocator
+            # should be updated here.
+            free_block.meta.shape = shapes[0]
+            free_block.meta.dtype = dtypes[0]
+            free_block.meta.shapes = shapes
+            free_block.meta.dtypes = dtypes
+            free_block.meta.fmt = fmt
+            free_block.meta.ref_count = 1
+            # Reset narrowed-size override (see notes in ``allocate``).
+            free_block._used_size_override = None
+
+            if shapes != self.shapes:
+                size_in_bytes = get_size_bytes(shapes, dtypes)
+                free_block.raw_data = free_block.raw_data[:size_in_bytes]
+
+            allocated_blocks.append(free_block)
+
+        # TODO (Jiayi): need a flag to drop these debug ops
+        # NOTE (Jiayi): the following code is not thread-safe but
+        # is tolerable as this is only used for debugging purposes.
+        # Update debug status
+        self.num_active_allocations += batch_size
+        self.total_allocated_size = self.num_active_allocations * self.align_bytes
+        self.stats_monitor.update_local_cache_usage(self.total_allocated_size)
+        self.stats_monitor.update_active_memory_objs_count(self.num_active_allocations)
+
+        # Allocate the block
+        return allocated_blocks
+
+    @_lmcache_nvtx_annotate
+    def free(
+        self, memory_obj: TensorMemoryObj, allocator_type: Optional[str] = None
+    ) -> None:
+        """Free one page-backed memory object.
+
+        Args:
+            memory_obj: Memory object to return to the free-page pool.
+            allocator_type: Optional allocator type string.
+        """
+        if not memory_obj.is_valid():
+            return
+        if memory_obj.meta.shapes != self.shapes:
+            page_idx = memory_obj.meta.address
+            memory_obj.raw_data = self.paged_buffers[page_idx]
+
+        self.free_blocks.append(memory_obj)
+
+        # memory_obj.invalidate()
+
+        # TODO (Jiayi): need a flag to drop these debug ops
+        # NOTE (Jiayi): the following code is not thread-safe but
+        # is tolerable as this is only used for debugging purposes.
+        # Update debug status
+        self.total_allocated_size -= self.align_bytes
+        self.num_active_allocations -= 1
+        self.stats_monitor.update_local_cache_usage(self.total_allocated_size)
+        self.stats_monitor.update_active_memory_objs_count(self.num_active_allocations)
+
+    @_lmcache_nvtx_annotate
+    def batched_free(
+        self,
+        memory_objs: List[TensorMemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple page-backed memory objects.
+
+        Unlike `batched_allocate`, this function does not
+        assume that the memory objs are equal-sized.
+
+        Args:
+            memory_objs: Memory objects to return to the free-page pool.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        if not memory_objs:
+            return
+
+        for memory_obj in memory_objs:
+            if not memory_obj.is_valid():
+                logger.warning("Trying to free an invalidated MemoryObj")
+                continue
+            # memory_obj.invalidate()
+            if memory_obj.meta.shapes != self.shapes:
+                page_idx = memory_obj.meta.address
+                memory_obj.raw_data = self.paged_buffers[page_idx]
+
+            self.free_blocks.append(memory_obj)
+
+        if update_stats:
+            num_freed_blocks = len(memory_objs)
+            # TODO (Jiayi): need a flag to drop these debug ops
+            # NOTE (Jiayi): the following code is not thread-safe but
+            # is tolerable as this is only used for debugging purposes.
+            # Update debug status
+            self.total_allocated_size -= self.align_bytes * num_freed_blocks
+            self.num_active_allocations -= num_freed_blocks
+            self.stats_monitor.update_local_cache_usage(self.total_allocated_size)
+            self.stats_monitor.update_active_memory_objs_count(
+                self.num_active_allocations
+            )
+
+    def memcheck(self) -> bool:
+        """Check allocator consistency for debugging.
+
+        Returns:
+            True if allocator accounting is internally consistent, otherwise
+            False.
+        """
+
+        logger.info("Checking memory allocator consistency")
+        logger.info(" - Total active allocations: %d", self.num_active_allocations)
+        logger.info(
+            " - Total allocated size: %f MB", self.total_allocated_size / 1048576
+        )
+
+        # Check the real total free size
+        total_free_size = len(self.free_blocks) * self.align_bytes
+        logger.info(" - Total free size: %f MB", total_free_size / 1048576)
+
+        # Check if the numbers are consistent
+        if total_free_size + self.total_allocated_size != self.buffer.numel():
+            logger.error("Memory allocator size is inconsistent")
+            logger.error("This implies a bug in the memory allocator")
+            return False
+
+        return True
+
+    def __str__(self) -> str:
+        return "PagedTensorMemoryAllocator"
+
+    def get_paged_buffers(self) -> tuple[torch.Tensor, ...]:
+        """
+        Get the paged buffers for fixed buffer registration.
+
+        Returns:
+            Tuple of paged buffer tensors that can be registered with io_uring
+            for true zero copy operations.
+        """
+        return self.paged_buffers
+
+    def __del__(self) -> None:
+        # FIXME: NIXL-related memory leak should be handled somewhere (else).
+        del self.buffer
diff --git a/lmcache/v1/memory_allocators/pin_memory_allocator.py b/lmcache/v1/memory_allocators/pin_memory_allocator.py
new file mode 100644
index 0000000..82fc422
--- /dev/null
+++ b/lmcache/v1/memory_allocators/pin_memory_allocator.py
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from contextlib import nullcontext
+from typing import List, Optional, Union
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+import lmcache.v1.memory_management as memory_management
+
+
+class PinMemoryAllocator(MemoryAllocatorInterface):
+    """Allocates memory in the pre-allocated pinned memory."""
+
+    def __init__(self, size: int, use_paging: bool = False, **kwargs) -> None:
+        """
+        :param int size: The size of the pinned memory in bytes.
+        """
+        self.size = size
+        self.buffer = memory_management._allocate_cpu_memory(size)
+        self._unregistered = False
+
+        self.allocator: MemoryAllocatorInterface
+        if use_paging:
+            assert "shapes" in kwargs, (
+                "shapes must be specified for paged memory allocator"
+            )
+            assert "dtypes" in kwargs, (
+                "dtypes must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.allocator = PagedTensorMemoryAllocator(
+                tensor=self.buffer,
+                shapes=kwargs["shapes"],
+                dtypes=kwargs["dtypes"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.allocator = TensorMemoryAllocator(self.buffer)
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """Allocate one pinned-memory object.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            A memory object, or ``None`` if the inner allocator is full.
+        """
+        with self.host_mem_lock:
+            return self.allocator.allocate(shapes, dtypes, fmt, str(self))
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """Allocate multiple pinned-memory objects.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in each returned object's metadata.
+            allocator_type: Optional allocator type string.
+
+        Returns:
+            Memory objects, or ``None`` if the inner allocator is full.
+        """
+        with self.host_mem_lock:
+            return self.allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt, str(self)
+            )
+
+    @_lmcache_nvtx_annotate
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Free one pinned-memory object.
+
+        Args:
+            memory_obj: Memory object to release.
+            allocator_type: Optional allocator type string.
+        """
+        with self.host_mem_lock:
+            self.allocator.free(memory_obj)
+
+    @_lmcache_nvtx_annotate
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple pinned-memory objects.
+
+        Args:
+            memory_objs: Memory objects to release.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        with self.host_mem_lock:
+            self.allocator.batched_free(memory_objs)
+
+    def memcheck(self) -> bool:
+        """Return whether allocator state is consistent."""
+        with self.host_mem_lock:
+            return self.allocator.memcheck()
+
+    def close(self) -> None:
+        """Release the pinned-memory arena."""
+        if not self._unregistered:
+            if self.buffer.numel() == 0:
+                return
+            memory_management._free_cpu_memory(self.buffer, self.size)
+            self._unregistered = True
+
+    def __str__(self) -> str:
+        return "PinMemoryAllocator"
diff --git a/lmcache/v1/memory_allocators/tensor_memory_allocator.py b/lmcache/v1/memory_allocators/tensor_memory_allocator.py
new file mode 100644
index 0000000..06c5b45
--- /dev/null
+++ b/lmcache/v1/memory_allocators/tensor_memory_allocator.py
@@ -0,0 +1,328 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import List, Optional, Union
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.memory_management import (
+    AddressManager,
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+    logger,
+)
+
+
+class TensorMemoryAllocator(MemoryAllocatorInterface):
+    """
+    Implements a "explicit list" memory allocator.
+    Uses AddressManager for address space management.
+    """
+
+    def __init__(
+        self,
+        tensor: torch.Tensor,
+        align_bytes: int = AddressManager.ALIGN_BYTES,
+        init_address_space: int | None = None,
+    ) -> None:
+        """
+        Args:
+            tensor: The pre-allocated flat tensor to use as the memory pool.
+            align_bytes: The alignment requirement for allocations.
+            init_address_space: Initial size of the address space. If None,
+                use the size of the provided tensor.
+
+        Note:
+            The `init_address_space` is used for lazy memory allocation.
+            We probably want to have a better way to make sure that the
+            LazyMemoryAllocator can be decoupled from TensorMemoryAllocator.
+        """
+        self.buffer = tensor.view(torch.uint8).flatten()
+
+        # Use AddressManager for address space management
+        self.address_manager = AddressManager(
+            self.buffer.numel() if init_address_space is None else init_address_space,
+            align_bytes,
+        )
+
+        # For debugging purposes
+        self.num_active_allocations = 0
+
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+
+    @property
+    def total_allocated_size(self) -> int:
+        """Return the total currently allocated bytes."""
+        return self.address_manager.total_allocated_size
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[TensorMemoryObj]:
+        """Allocate one tensor-backed memory object.
+
+        Args:
+            shapes: Logical tensor shape or shapes to allocate.
+            dtypes: Logical tensor dtype or dtypes to allocate.
+            fmt: Memory format stored in the returned metadata.
+            allocator_type: Optional parent allocator identifier.
+
+        Returns:
+            A tensor-backed memory object, or ``None`` if no block is available.
+        """
+        shapes, dtypes = self._adapt_shapes_and_dtypes(shapes, dtypes)
+
+        # Calculate the size of the tensor
+        raw_size = get_size_bytes(shapes, dtypes)
+
+        # Allocate from address manager
+        try:
+            block_start, aligned_size = self.address_manager.allocate(raw_size)
+        except RuntimeError:
+            # No block found
+            return None
+
+        # For debug
+        self.num_active_allocations += 1
+
+        # Update stats
+        self.stats_monitor.update_local_cache_usage(
+            self.address_manager.total_allocated_size
+        )
+        self.stats_monitor.update_active_memory_objs_count(self.num_active_allocations)
+
+        # Allocate the block
+        raw_data = self._get_buffer_slice(block_start, raw_size)
+        return TensorMemoryObj(
+            raw_data=raw_data,
+            metadata=MemoryObjMetadata(
+                shapes[0],
+                dtypes[0],
+                block_start,
+                aligned_size,
+                1,
+                0,
+                fmt,
+                shapes=shapes,
+                dtypes=dtypes,
+            ),
+            parent_allocator=self,
+        )
+
+    def _get_buffer_slice(self, start: int, size: int) -> torch.Tensor:
+        """Hook: Get buffer slice. Override for custom buffer access."""
+        return self.buffer[start : start + size]
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[TensorMemoryObj]]:
+        """Allocate multiple equal-sized tensor-backed memory objects.
+
+        Args:
+            shapes: Logical tensor shape or shapes for each allocation.
+            dtypes: Logical tensor dtype or dtypes for each allocation.
+            batch_size: Number of memory objects to allocate.
+            fmt: Memory format stored in each returned object's metadata.
+            allocator_type: Optional parent allocator identifier.
+
+        Returns:
+            A list of tensor-backed memory objects, or ``None`` if there is
+            not enough contiguous free space for the full batch.
+        """
+        shapes, dtypes = self._adapt_shapes_and_dtypes(shapes, dtypes)
+
+        # Calculate the size of the tensor
+        unit_raw_size = get_size_bytes(shapes, dtypes)
+        unit_aligned_size = self.address_manager.compute_aligned_size(unit_raw_size)
+
+        try:
+            alloc_results = self.address_manager.batched_allocate(
+                unit_aligned_size, batch_size
+            )
+        except RuntimeError:
+            return None
+        addresses = [addr for addr, _ in alloc_results]
+        raw_datas = [
+            self._get_buffer_slice(addr, unit_aligned_size) for addr in addresses
+        ]
+
+        # For debug
+        self.num_active_allocations += batch_size
+
+        # Update stats
+        self.stats_monitor.update_local_cache_usage(
+            self.address_manager.total_allocated_size
+        )
+        self.stats_monitor.update_active_memory_objs_count(self.num_active_allocations)
+
+        tensor_mem_objs = []
+        for raw_data, address in zip(raw_datas, addresses, strict=True):
+            tensor_mem_objs.append(
+                TensorMemoryObj(
+                    raw_data=raw_data,
+                    metadata=MemoryObjMetadata(
+                        shapes[0],
+                        dtypes[0],
+                        address,
+                        unit_aligned_size,
+                        1,
+                        0,
+                        fmt,
+                        shapes=shapes,
+                        dtypes=dtypes,
+                    ),
+                    parent_allocator=self,
+                )
+            )
+
+        return tensor_mem_objs
+
+    @_lmcache_nvtx_annotate
+    def free(self, memory_obj: MemoryObj, allocator_type: Optional[str] = None) -> None:
+        """Free one tensor-backed memory object.
+
+        Args:
+            memory_obj: Memory object to release back to the allocator.
+            allocator_type: Optional allocator type string.
+        """
+        if not memory_obj.is_valid():
+            return
+
+        self.address_manager.free(memory_obj.meta.address, memory_obj.meta.phy_size)
+        memory_obj.invalidate()
+
+        # For debug
+        self.num_active_allocations -= 1
+
+        # Update stats
+        self.stats_monitor.update_local_cache_usage(
+            self.address_manager.total_allocated_size
+        )
+        self.stats_monitor.update_active_memory_objs_count(self.num_active_allocations)
+
+    @_lmcache_nvtx_annotate
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ) -> None:
+        """Free multiple tensor-backed memory objects.
+
+        Unlike `batched_allocate`, this function does not
+        assume that the memory objs are equal-sized.
+
+        Args:
+            memory_objs: Memory objects to release back to the allocator.
+            allocator_type: Optional allocator type string.
+            update_stats: Whether to update allocator statistics.
+        """
+        if not memory_objs:
+            return
+
+        # Coalesce adjacent memory objects before freeing to reduce
+        # the number of free operations
+        coalesced_blocks: list[tuple[int, int, int]] = []  # (address, size, count)
+        curr_start = None
+        curr_size = 0
+        curr_count = 0
+
+        memory_objs.sort(key=lambda x: x.meta.address)
+        for memory_obj in memory_objs:
+            if not memory_obj.is_valid():
+                logger.warning("Trying to free an invalidated MemoryObj")
+                continue
+            memory_obj.invalidate()
+
+            if curr_start is None:
+                curr_start = memory_obj.meta.address
+                curr_size = memory_obj.meta.phy_size
+                curr_count = 1
+            elif curr_start + curr_size == memory_obj.meta.address:
+                # Adjacent block, extend current
+                curr_size += memory_obj.meta.phy_size
+                curr_count += 1
+            else:
+                # Non-adjacent, save current and start new
+                coalesced_blocks.append((curr_start, curr_size, curr_count))
+                curr_start = memory_obj.meta.address
+                curr_size = memory_obj.meta.phy_size
+                curr_count = 1
+
+        if curr_start is not None:
+            coalesced_blocks.append((curr_start, curr_size, curr_count))
+
+        # Free all coalesced blocks
+        total_count = 0
+        for address, size, count in coalesced_blocks:
+            self.address_manager.free(address, size)
+            total_count += count
+
+        # For debug
+        self.num_active_allocations -= total_count
+
+        if update_stats:
+            self.stats_monitor.update_local_cache_usage(
+                self.address_manager.total_allocated_size
+            )
+            self.stats_monitor.update_active_memory_objs_count(
+                self.num_active_allocations
+            )
+
+    def memcheck(self) -> bool:
+        """Check allocator consistency for debugging.
+
+        Returns:
+            True if allocator accounting is internally consistent, otherwise
+            False.
+        """
+        clear = True
+        logger.info("Checking memory allocator consistency")
+        logger.info(" - Total active allocations: %d", self.num_active_allocations)
+        logger.info(
+            " - Total allocated size: %f MB",
+            self.address_manager.total_allocated_size / 1048576,
+        )
+
+        # Check the real total free size
+        total_free_size = self.address_manager.get_free_size()
+        logger.info(" - Total free size: %f MB", total_free_size / 1048576)
+
+        # Check if the numbers are consistent
+        if (
+            total_free_size + self.address_manager.total_allocated_size
+            != self.address_manager.get_heap_size()
+        ):
+            logger.error("Memory allocator size is inconsistent")
+            logger.error("This implies a bug in the memory allocator")
+            clear = False
+
+        # Check if the blocks are coalesced
+        if not self.address_manager.check_consistency():
+            logger.error("Memory allocator has non-coalesced blocks")
+            logger.error("This implies a bug in the memory allocator")
+            clear = False
+
+        return clear
+
+    def __str__(self) -> str:
+        """Return the allocator name."""
+        return "TensorMemoryAllocator"
diff --git a/lmcache/v1/memory_management.py b/lmcache/v1/memory_management.py
new file mode 100644
index 0000000..90825ba
--- /dev/null
+++ b/lmcache/v1/memory_management.py
@@ -0,0 +1,1626 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from enum import Enum, auto
+from functools import cache, wraps
+from typing import Any, List, Optional, Tuple, Union
+import abc
+import ctypes
+import os
+import threading
+
+# Third Party
+from sortedcontainers import SortedList
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache import torch_device_type as torch_device_type  # noqa: F401
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.pin_monitor import PinMonitor
+from lmcache.v1.platform import current_device_spec as current_device_spec  # noqa: F401
+from lmcache.v1.system_detection import NUMAMapping
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+# Cache for ctypes ubyte-array types keyed by length.
+#
+# ctypes does not cache `(c_ubyte * N)` array types -- each call to the `*`
+# operator builds a fresh heap type via PyCArrayType_from_ctype. The heap
+# type metadata stays alive forever (held by the type system), so calling
+# `(ctypes.c_ubyte * N).from_address(...)` on every TensorMemoryObj.byte_array
+# access leaks ~1-2 kB per call. Under long-running remote-backend put/get
+# workloads this is the dominant source of monotonic anonymous-memory growth
+# (see https://github.com/LMCache/LMCache/issues/3767).
+#
+# Caching by length is safe: the `from_address(addr)` instance never owns the
+# underlying buffer, only the metadata (length, item-type), and that metadata
+# depends solely on `N`. ``functools.cache`` provides a thread-safe unbounded
+# memoization primitive, so concurrent first-time accesses for the same `N`
+# cannot race to create distinct heap types.
+@cache
+def _get_cached_ubyte_array_type(num_bytes: int) -> type[ctypes.Array[ctypes.c_ubyte]]:
+    """Return a cached ``ctypes.c_ubyte * num_bytes`` array type.
+
+    Args:
+        num_bytes: The length of the array type in bytes.
+
+    Returns:
+        The cached ``ctypes.Array`` subclass for the given length. Subsequent
+        calls with the same ``num_bytes`` return the same type object.
+    """
+    return ctypes.c_ubyte * num_bytes
+
+
+# Helper functions for thread safety
+def synchronized(lock_attr_name):
+    """
+    Decorator to make a method thread-safe by acquiring the lock
+    specified by lock_attr_name on the instance.
+    """
+
+    def decorator(method):
+        @wraps(method)
+        def wrapper(self, *args, **kwargs):
+            lock = getattr(self, lock_attr_name)
+            with lock:
+                return method(self, *args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class MemoryFormat(Enum):
+    UNDEFINED = 0
+    """[2, num_layers, num_tokens, hidden_dim]
+    """
+    # KV_BLOB = 1
+    KV_2LTD = auto()
+    """[num_tokens, 2, hidden_dim]
+    """
+    # LAYER_KV_BLOB = 2
+    KV_T2D = auto()
+    """[2, num_tokens, hidden_dim]
+    """
+
+    KV_2TD = auto()
+    """Compressed binary array format
+    """
+    BINARY = auto()
+
+    BINARY_BUFFER = auto()
+
+    KV_MLA_FMT = auto()
+    """[1, num_layers, num_tokens, aligned_head_size]
+    """
+
+    # This is for the encoder cache (EC) tensor format
+    EC_TD = auto()
+    """[num_tokens, hidden_dim]
+    """
+
+    # Hidden-state store (HS) tensor format. Same logical shape as EC_TD
+    # ([num_tokens, hidden_dim]) but tagged separately so the allocator and
+    # any future mp/serialization paths can distinguish encoder-cache entries
+    # from hidden-state entries.
+    HS_TD = auto()
+    """[num_tokens, hidden_dim]
+    """
+
+    def token_dim(self) -> int:
+        if self == MemoryFormat.KV_2LTD:
+            return 2
+        elif self == MemoryFormat.KV_T2D:
+            return 1
+        elif self == MemoryFormat.KV_2TD:
+            return 0
+        elif self == MemoryFormat.BINARY:
+            return 0
+        elif self == MemoryFormat.BINARY_BUFFER:
+            return 0
+        elif self == MemoryFormat.KV_MLA_FMT:
+            return 2
+        elif self == MemoryFormat.EC_TD:
+            return 0
+        elif self == MemoryFormat.HS_TD:
+            return 0
+        return 0
+
+
+@dataclass
+class FreeBlock:
+    """Metadata class used by the memory allocators"""
+
+    start: int
+    size: int
+
+    def can_be_coalesced(self, succ: "FreeBlock") -> bool:
+        return self.start + self.size == succ.start
+
+
+@dataclass
+class MemoryObjMetadata:
+    # TODO(chunxiaozheng): use shapes and dtypes to replace shape and dtype
+    # The 'logical' shape of the tensor
+    shape: torch.Size
+
+    # The 'logical' dtype of the tensor
+    dtype: Optional[torch.dtype]
+
+    # The 'physical address' of the tensor
+    address: int
+
+    # The 'physical size' in bytes of the allocated memory
+    phy_size: int
+
+    # Reference count
+    ref_count: int
+
+    # Whether the object is pinned and cannot be evicted
+    # lookup pins are temporary
+    # cache controller pins are persistent
+    pin_count: int = 0
+
+    # The 'logical' format of the tensor
+    fmt: MemoryFormat = MemoryFormat.UNDEFINED
+
+    # Positions when the cache is stored
+    cached_positions: Optional[torch.Tensor] = None
+
+    # shapes and dtypes should be used in the future
+    shapes: Optional[list[torch.Size]] = None
+    dtypes: Optional[list[torch.dtype]] = None
+
+    def to_dict(self):
+        # Note(Kuntai): this is used for serializing MemoryObjMetadata via
+        # msgpack.
+        return {
+            "__type__": "MemoryObjMetadata",
+            "shape": list(self.shape),  # torch.Size -> list
+            "dtype": str(self.dtype) if self.dtype else None,
+            "address": self.address,
+            "phy_size": self.phy_size,
+            "ref_count": self.ref_count,
+            "fmt": self.fmt.value,
+            "shapes": [list(shape) for shape in self.shapes] if self.shapes else None,
+            "dtypes": [str(dtype) for dtype in self.dtypes] if self.dtypes else None,
+        }
+
+    @staticmethod
+    def from_dict(d):
+        dtype_str = d["dtype"]
+        dtype = getattr(torch, dtype_str.replace("torch.", "")) if dtype_str else None
+        shapes_list = d["shapes"]
+        shapes = [torch.Size(s) for s in shapes_list] if shapes_list else None
+        dtypes_list = d["dtypes"]
+        dtypes = (
+            [getattr(torch, d_str.replace("torch.", "")) for d_str in dtypes_list]
+            if dtypes_list
+            else None
+        )
+        return MemoryObjMetadata(
+            shape=torch.Size(d["shape"]),
+            dtype=dtype,
+            address=d["address"],
+            phy_size=d["phy_size"],
+            ref_count=d["ref_count"],
+            fmt=MemoryFormat(d["fmt"]),
+            shapes=shapes,
+            dtypes=dtypes,
+        )
+
+    def get_size(self) -> int:
+        if self.shapes is not None and self.dtypes is not None:
+            return get_size_bytes(self.shapes, self.dtypes)
+        return self.shape.numel() * self.dtype.itemsize  # type: ignore
+
+
+class MemoryObj(metaclass=abc.ABCMeta):
+    """
+    MemoryObj interface.
+    """
+
+    # subclasses should expose raw_data differently
+    raw_data: Any
+
+    def __init__(self, metadata: MemoryObjMetadata):
+        self.meta = metadata
+
+    @abc.abstractmethod
+    def invalidate(self):
+        """
+        Invalidate the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def is_valid(self):
+        """
+        Check if the MemoryObj is valid.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_size(self) -> int:
+        """
+        Get the size of the MemoryObj in bytes.
+        Note that this number could be smaller than the physical size.
+        The physical size is aligned to the allocator's alignment.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_shape(self) -> torch.Size:
+        """
+        Get the shape of the MemoryObj.
+        """
+        raise NotImplementedError
+
+    def get_dtype(self) -> Optional[torch.dtype]:
+        """
+        Get the dtype of the MemoryObj.
+        """
+        return None
+
+    @abc.abstractmethod
+    def get_shapes(self) -> list[torch.Size]:
+        """
+        Get the shapes of the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_dtypes(self) -> list[torch.dtype]:
+        """
+        Get the dtypes of the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_memory_format(self) -> MemoryFormat:
+        """
+        Get the memory format of the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_physical_size(self) -> int:
+        """
+        Get the physical size of the MemoryObj in bytes.
+        """
+        raise NotImplementedError
+
+    def set_used_size(self, n: int) -> None:  # noqa: B027
+        """Narrow this buffer's logical size to the first ``n`` bytes.
+
+        Optional hook for callers that have just written ``n`` bytes
+        into a buffer originally allocated with an upper-bound size
+        (e.g. the async serde processor, where the destination is sized
+        from ``estimate_serialized_size`` but ``serialize`` returns the
+        actual ``n`` it wrote). After this call, ``get_size()`` /
+        ``byte_array`` / any downstream L2 adapter that reads the
+        logical size will see exactly ``n`` bytes.
+
+        Default is a no-op so subclasses without a "used vs allocated"
+        distinction (e.g. :class:`BytesBufferMemoryObj`, where the raw
+        bytes already are the actual contents) keep working unchanged.
+
+        Args:
+            n: bytes actually used in this buffer. Subclasses that
+                implement this must validate ``n`` and raise
+                ``ValueError`` on out-of-range or unsupported layouts.
+        """
+        pass
+
+    @abc.abstractmethod
+    def pin(self) -> bool:
+        """
+        Pin the memory obj so that it will not be evicted.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def ref_count_up(self):
+        """
+        Increase ref count for the given MemoryObj by one.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def unpin(self) -> bool:
+        """
+        Unpin the memory obj so that it can be evicted.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def ref_count_down(self):
+        """
+        Decrease ref count for the given MemoryObj by one.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_ref_count(self) -> int:
+        """
+        Get ref count for the given MemoryObj.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_num_tokens(self) -> int:
+        """
+        Get token number for the given MemoryObj.
+        """
+        raise NotImplementedError
+
+    @property
+    def shm_offset(self) -> int:
+        """Return the byte offset of this object inside the SHM pool."""
+        return self.meta.address
+
+    @property
+    def shm_byte_length(self) -> int:
+        """Return the byte length of this object inside the SHM pool."""
+        return self.get_size()
+
+    @property
+    @abc.abstractmethod
+    def metadata(self) -> MemoryObjMetadata:
+        """
+        Get the metada of the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def tensor(self) -> Optional[torch.Tensor]:
+        """
+        Get the tensor from the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def byte_array(self) -> bytes:
+        """
+        Get the byte array from the MemoryObj.
+        The size is will be the physical size instead of the unaligned size.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def data_ptr(self) -> int:
+        """
+        Get the data pointer of the MemoryObj.
+        This is used to access the raw data in the memory.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def is_pinned(self) -> bool:
+        """
+        Check whether the memory obj is pinned.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def can_evict(self) -> bool:
+        """
+        Check whether the memory obj can be evicted.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def raw_tensor(self) -> Optional[torch.Tensor]:
+        """
+        Get the raw tensor from the MemoryObj.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_tensor(self, index: int) -> Optional[torch.Tensor]:
+        """
+        Get the tensor from the MemoryObj at the given index(group).
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def parent(self) -> Optional["MemoryAllocatorInterface"]:
+        """
+        Get the allocator that allocates this memory object
+        """
+        raise NotImplementedError
+
+
+@dataclass
+class PinnedAllocFree:
+    """Resolved alloc/free function pair for pinned CPU memory."""
+
+    alloc_fn: Any
+    alloc_args: tuple
+    free_fn: Any
+    free_args: tuple
+
+    def alloc(self) -> int:
+        """Allocate pinned memory and return the raw pointer."""
+        return self.alloc_fn(*self.alloc_args)
+
+    def free(self, ptr: int) -> None:
+        """Free a previously allocated pinned-memory pointer."""
+        self.free_fn(ptr, *self.free_args)
+
+
+def _resolve_pinned_alloc_free(
+    numa_mapping: Optional[NUMAMapping] = None,
+    shm_name: Optional[str] = None,
+    size: Optional[int] = None,
+    use_hugepages: bool = False,
+) -> PinnedAllocFree:
+    """Resolve the alloc/free function pair based on memory type.
+
+    Returns:
+        A PinnedAllocFree with the resolved functions and their extra
+        arguments.  Call ``ptr = resolved.alloc()`` and ``resolved.free(ptr)``.
+    """
+    if shm_name:
+        if use_hugepages:
+            raise ValueError("Hugepages are not supported with shared memory (shm)")
+        return PinnedAllocFree(
+            alloc_fn=lmc_ops.alloc_shm_pinned_ptr,
+            alloc_args=(size, shm_name),
+            free_fn=lmc_ops.free_shm_pinned_ptr,
+            free_args=(size, shm_name),
+        )
+    elif numa_mapping:
+        if torch_dev.is_available():
+            current_device_id = torch_dev.current_device()
+        else:
+            current_device_id = 0
+        gpu_to_numa_mapping = numa_mapping.gpu_to_numa_mapping
+        assert current_device_id in gpu_to_numa_mapping, (
+            f"Current device {current_device_id} is not in the GPU NUMA mapping."
+        )
+        numa_id = gpu_to_numa_mapping[current_device_id]
+        if use_hugepages:
+            return PinnedAllocFree(
+                alloc_fn=lmc_ops.alloc_hugepage_pinned_numa_ptr,
+                alloc_args=(size, numa_id),
+                free_fn=lmc_ops.free_hugepage_pinned_numa_ptr,
+                free_args=(size,),
+            )
+        else:
+            return PinnedAllocFree(
+                alloc_fn=lmc_ops.alloc_pinned_numa_ptr,
+                alloc_args=(size, numa_id),
+                free_fn=lmc_ops.free_pinned_numa_ptr,
+                free_args=(size,),
+            )
+    else:
+        flags = 0
+        if use_hugepages:
+            return PinnedAllocFree(
+                alloc_fn=lmc_ops.alloc_hugepage_pinned_ptr,
+                alloc_args=(size, flags),
+                free_fn=lmc_ops.free_hugepage_pinned_ptr,
+                free_args=(size,),
+            )
+        else:
+            return PinnedAllocFree(
+                alloc_fn=lmc_ops.alloc_pinned_ptr,
+                alloc_args=(size, flags),
+                free_fn=lmc_ops.free_pinned_ptr,
+                free_args=(),
+            )
+
+
+def _read_hugepage_info() -> Optional[Tuple[int, int, int]]:
+    """Read hugepage pool stats from sysfs.
+
+    NOTE: We only use 2 MiB hugepages, so the pool stats are taken from
+    the 2 MiB pool directly rather than the system default pool reported in
+    ``/proc/meminfo`` (which can be 1 GiB on some hosts).
+
+    Returns:
+        ``(nr_hugepages, free_hugepages, page_size_mb)`` for the hugepage
+        pool, or ``None`` if the sysfs entries are unavailable.
+    """
+    base = "/sys/kernel/mm/hugepages/hugepages-2048kB"
+    try:
+        with open(f"{base}/nr_hugepages") as f:
+            total = int(f.read().strip())
+        with open(f"{base}/free_hugepages") as f:
+            free = int(f.read().strip())
+        return total, free, 2
+    except (OSError, ValueError):
+        return None
+
+
+def _allocate_cpu_memory(
+    size: int,
+    numa_mapping: Optional[NUMAMapping] = None,
+    shm_name: Optional[str] = None,
+    use_hugepages: bool = False,
+) -> torch.Tensor:
+    if size == 0:
+        return torch.empty(0, dtype=torch.uint8)
+
+    resolved = _resolve_pinned_alloc_free(
+        numa_mapping,
+        shm_name,
+        size,
+        use_hugepages,
+    )
+
+    try:
+        ptr = resolved.alloc()
+    except RuntimeError as e:
+        if use_hugepages and "mmap failed" in str(e):
+            diag = _read_hugepage_info()
+            if diag is not None:
+                total, free, page_mb = diag
+                page_bytes = page_mb * 1024 * 1024
+                needed = (size + page_bytes - 1) // page_bytes
+                logger.error(
+                    "Failed to allocate huge pages. "
+                    "Pool has %d pages (%d free, each %d MiB). "
+                    "Requested %d bytes (%d pages). "
+                    "Please grow the %d MiB hugepage pool.",
+                    total,
+                    free,
+                    page_mb,
+                    size,
+                    needed,
+                    page_mb,
+                )
+            else:
+                logger.error(
+                    "Failed to allocate huge pages. "
+                    "Please grow the 2 MiB hugepage pool."
+                )
+        raise
+
+    array_type = ctypes.c_uint8 * size
+    buf = array_type.from_address(ptr)
+    buffer = torch.frombuffer(buf, dtype=torch.uint8)
+
+    return buffer
+
+
+def _free_cpu_memory(
+    buffer: torch.Tensor,
+    size: int | None = None,
+    numa_mapping: Optional[NUMAMapping] = None,
+    shm_name: Optional[str] = None,
+    use_hugepages: bool = False,
+) -> None:
+    if torch_dev.is_available():
+        torch_dev.synchronize()
+
+    resolved = _resolve_pinned_alloc_free(
+        numa_mapping,
+        shm_name,
+        size,
+        use_hugepages,
+    )
+    resolved.free(buffer.data_ptr())
+
+
+def _allocate_gpu_memory(
+    size: int,
+    device: str,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    page_size = os.sysconf("SC_PAGESIZE")
+
+    # Over-allocate
+    base_buffer = torch.empty(size + page_size, dtype=torch.uint8, device=device)
+    offset = -base_buffer.data_ptr() % page_size
+
+    # Make aligned view
+    aligned_buffer = base_buffer[offset : offset + size]
+
+    # Need to return the base buffer as well in order to prevent GC
+    return base_buffer, aligned_buffer
+
+
+class TensorMemoryObj(MemoryObj):
+    """
+    Wraps a raw flat tensor with some metadata
+    """
+
+    monitor = LMCStatsMonitor.GetOrCreate()
+
+    def __init__(
+        self,
+        raw_data: torch.Tensor,
+        metadata: MemoryObjMetadata,
+        parent_allocator: Optional["MemoryAllocatorInterface"],
+    ):
+        assert metadata.dtype is not None, "dtype must be specified for TensorMemoryObj"
+        super().__init__(metadata)
+        self.raw_data = raw_data
+        self.valid = True
+        self.lock = threading.Lock()
+        self.parent_allocator = parent_allocator
+        # ``None`` means "use the layout-derived size from
+        # group_prefix_sum"; a non-None value narrows the logical view to
+        # exactly that many bytes (see set_used_size).  Allocator reuse
+        # paths must reset this to None along with the rest of the
+        # per-allocation metadata.
+        self._used_size_override: Optional[int] = None
+        # Calculate the prefix sum of the group sizes
+        # If there are two groups, the prefix sum will be
+        # [0, size_of_group_1, size_of_group_1 + size_of_group_2]
+        self.group_prefix_sum = [0]
+        if self.meta.shapes is not None and self.meta.dtypes is not None:
+            size_in_bytes = 0
+            for shape, dtype in zip(self.meta.shapes, self.meta.dtypes, strict=True):
+                size_in_bytes += shape.numel() * dtype.itemsize
+                self.group_prefix_sum.append(size_in_bytes)
+        else:
+            self.group_prefix_sum.append(self.meta.get_size())
+
+    def __del__(self):
+        """
+        Destructor to ensure memory is released when the object is garbage collected.
+        This acts as a safety net to prevent memory leaks if ref_count_down() is not
+        called properly somewhere in the code path.
+        """
+        if self.parent_allocator is not None and self.is_valid():
+            if self.meta.ref_count > 0 or self.meta.pin_count > 0:
+                logger.warning(
+                    "MemoryObj at %s is being garbage collected "
+                    "with ref_count=%d, pin_count=%d. "
+                    "This indicates ref_count_down()/unpin() was not called properly.",
+                    self.meta.address,
+                    self.meta.ref_count,
+                    self.meta.pin_count,
+                )
+            self.parent_allocator.free(self)
+
+    def invalidate(self):
+        self.valid = False
+
+    def is_valid(self):
+        return self.valid
+
+    def get_size(self) -> int:
+        if self._used_size_override is not None:
+            return self._used_size_override
+        return self.group_prefix_sum[-1]
+
+    def set_used_size(self, n: int) -> None:
+        """Narrow the logical size to ``n`` bytes after a write.
+
+        After this call, ``get_size()`` returns ``n`` and ``byte_array``
+        exposes exactly ``n`` bytes from the start of ``raw_data``.  The
+        physical allocation (``get_physical_size``) and ``raw_data``
+        buffer are unchanged.  Allocator reuse resets this override to
+        ``None`` so a recycled block returns to its layout-derived size.
+
+        Note: the ``tensor`` property still derives its shape from
+        ``meta.shape``, so accessing ``.tensor`` on a buffer narrowed
+        below its layout size will fail to reshape.  Use ``byte_array``
+        (or read ``raw_data[: get_size()]`` directly) for downstream
+        I/O that must honor the narrowed size.
+
+        Args:
+            n: bytes actually written.  Must satisfy
+                ``0 <= n <= get_physical_size()``.
+
+        Raises:
+            ValueError: if ``n`` is outside the allowed range.
+        """
+        if n < 0 or n > self.meta.phy_size:
+            raise ValueError(
+                f"set_used_size: n={n} out of range [0, {self.meta.phy_size}]"
+            )
+        with self.lock:
+            self._used_size_override = n
+
+    # TODO(chunxiaozheng): use get_shapes and get_dtypes to replace
+    #  get_shape and get_dtype
+    def get_shape(self) -> torch.Size:
+        return self.meta.shape
+
+    def get_dtype(self) -> torch.dtype:
+        assert self.meta.dtype is not None
+        return self.meta.dtype
+
+    def get_shapes(self) -> list[torch.Size]:
+        assert self.meta.shapes is not None
+        return self.meta.shapes
+
+    def get_dtypes(self) -> list[torch.dtype]:
+        assert self.meta.dtypes is not None
+        return self.meta.dtypes
+
+    def get_memory_format(self) -> MemoryFormat:
+        with self.lock:
+            return self.meta.fmt
+
+    def get_physical_size(self) -> int:
+        return self.meta.phy_size
+
+    def ref_count_up(self):
+        with self.lock:
+            self.meta.ref_count += 1
+
+    def ref_count_down(self):
+        with self.lock:
+            self.meta.ref_count -= 1
+            if self.meta.ref_count < 0:
+                logger.warning(
+                    f"Ref count of MemoryObj {self.meta.address}"
+                    f"is negative: {self.meta.ref_count}."
+                    "Double free occurred somewhere."
+                    "Setting ref count back to 0 as a hack but please find the bug."
+                )
+                self.meta.ref_count = 0
+            if (
+                self.meta.ref_count == 0
+                and self.parent_allocator is not None
+                and self.meta.pin_count == 0
+            ):
+                self.parent_allocator.free(self)
+
+    def get_ref_count(self) -> int:
+        with self.lock:
+            return self.meta.ref_count
+
+    def get_num_tokens(self) -> int:
+        with self.lock:
+            token_dim = self.meta.fmt.token_dim()
+            return self.meta.shape[token_dim]
+
+    def pin(self) -> bool:
+        with self.lock:
+            # if pin_count is 0, indicates that the object is pinned for the first time
+            if self.meta.pin_count == 0:
+                TensorMemoryObj.monitor.update_pinned_memory_objs_count(1)
+
+            self.meta.pin_count += 1
+
+            # Register/update with PinMonitor for timeout tracking on every pin
+            pin_monitor = PinMonitor.GetOrCreate()
+            pin_monitor.on_pin(self)
+            return True
+
+    def unpin(self) -> bool:
+        with self.lock:
+            self.meta.pin_count -= 1
+
+            # if pin_count is 0, indicates that the object is unpinned
+            if self.meta.pin_count == 0:
+                TensorMemoryObj.monitor.update_pinned_memory_objs_count(-1)
+                # Unregister from PinMonitor when fully unpinned
+                pin_monitor = PinMonitor.GetOrCreate()
+                pin_monitor.on_unpin(self)
+
+            if self.meta.pin_count <= 0 and self.meta.ref_count <= 0:
+                if self.parent_allocator is None:
+                    logger.error(
+                        "Parent allocator is None when trying to free MemoryObj."
+                        "This could cause memory leak"
+                    )
+                else:
+                    self.parent_allocator.free(self)
+
+            if self.meta.pin_count < 0:
+                logger.warning(
+                    f"Pin count of MemoryObj {self.meta.address}"
+                    f"is negative: {self.meta.pin_count}."
+                    "Double unpin occurred somewhere."
+                    "Setting pin count back to 0 as a hack but please find the bug."
+                )
+                self.meta.pin_count = 0
+            return True
+
+    @property
+    def metadata(self) -> MemoryObjMetadata:
+        with self.lock:
+            return self.meta
+
+    @property
+    def tensor(self) -> Optional[torch.Tensor]:
+        if not self.valid:
+            logger.warning("Trying to access an invalidated MemoryObj")
+            return None
+        assert self.meta.dtype is not None
+        if self._used_size_override is not None:
+            # Narrowed byte buffer (see set_used_size): expose exactly
+            # the used bytes as a flat uint8 view.  Reshaping to the
+            # original meta.shape would raise -- fewer than shape-many
+            # bytes are logically present -- so keep the view consistent
+            # with get_size()/byte_array/shm_byte_length, which all
+            # report the narrowed length.  Consumers that build SHM
+            # transport slots from ``tensor.shape`` and
+            # ``shm_byte_length`` then stay self-consistent.
+            return self.raw_data[: self._used_size_override].view(torch.uint8)
+        # TODO(Jiayi): consider caching the `get_size()`
+        return (
+            self.raw_data[: self.get_size()].view(self.meta.dtype).view(self.meta.shape)
+        )
+
+    @property
+    def byte_array(self) -> memoryview:
+        # TODO: consider using one of the alternatives
+
+        # Alternative 1:
+        # # PyTorch tensors support buffer protocol directly for CPU tensors
+        # return memoryview(self.raw_data)
+
+        # Alternative 2:
+        # assert self.raw_data.device.type == 'cpu',
+        #   "byte_array only works with CPU tensors"
+        # return memoryview(self.raw_data.contiguous().numpy())
+
+        # Use logical size (get_size) rather than raw_data physical size.
+        # The raw_data buffer may include alignment padding (e.g. from
+        # batched_allocate) that must not be exposed to callers such as
+        # remote-backend put/get which rely on byte_array length matching
+        # the metadata length.
+        num_bytes = self.get_size()
+        ptr = self.raw_data.data_ptr()
+        # ctypes does not cache (c_ubyte * N) array types -- each `*` builds a
+        # fresh heap type. With this property accessed once per remote put/get,
+        # uncached creation leaks ~1-2 kB per call (heap-type metadata is held
+        # by the type system and never reclaimed). Cache the array type per
+        # size so steady-state usage reuses a fixed set of types. See
+        # https://github.com/LMCache/LMCache/issues/3767.
+        arr_type = _get_cached_ubyte_array_type(num_bytes)
+        ubyte_ptr = ctypes.cast(ptr, ctypes.POINTER(ctypes.c_ubyte))
+        byte_array = arr_type.from_address(ctypes.addressof(ubyte_ptr.contents))
+        return memoryview(byte_array)
+
+    @property
+    def data_ptr(self) -> int:
+        return self.raw_data.data_ptr()
+
+    @property
+    def is_pinned(self) -> bool:
+        return self.metadata.pin_count > 0
+
+    @property
+    def can_evict(self) -> bool:
+        """
+        Check whether the memory obj can be evicted.
+        A memory obj can be evicted if it is not pinned and ref_count=1.
+        """
+        return not self.is_pinned and self.get_ref_count() == 1
+
+    @property
+    def raw_tensor(self) -> Optional[torch.Tensor]:
+        if not self.valid:
+            logger.warning("Trying to access an invalidated MemoryObj")
+            return None
+        return self.raw_data
+
+    def get_tensor(self, index: int) -> Optional[torch.Tensor]:
+        if not self.valid:
+            logger.warning("Trying to access an invalidated MemoryObj")
+            return None
+        assert self.meta.shapes is not None
+        assert self.meta.dtypes is not None
+        begin = self.group_prefix_sum[index]
+        end = self.group_prefix_sum[index + 1]
+        return (
+            self.raw_data[begin:end]
+            .view(self.meta.dtypes[index])
+            .view(self.meta.shapes[index])
+        )
+
+    def parent(self) -> Optional["MemoryAllocatorInterface"]:
+        return self.parent_allocator
+
+
+class BytesBufferMemoryObj(MemoryObj):
+    """
+    Wraps a raw flat tensor with some metadata
+    """
+
+    def __init__(self, raw_bytes: bytes, metadata: Optional[MemoryObjMetadata] = None):
+        self.raw_data = raw_bytes
+        if metadata is None:
+            bytes_shape = torch.Size([len(self.raw_data), 0, 0, 0])
+            metadata = MemoryObjMetadata(
+                shape=bytes_shape,
+                dtype=None,
+                address=0,
+                phy_size=0,
+                ref_count=1,
+                pin_count=0,
+                fmt=MemoryFormat.BINARY_BUFFER,
+            )
+        super().__init__(metadata)
+        self.valid = True
+
+    def invalidate(self):
+        self.valid = False
+
+    def is_valid(self):
+        return self.valid
+
+    def get_size(self) -> int:
+        return len(self.raw_data)
+
+    def get_shape(self) -> torch.Size:
+        return torch.Size([len(self.raw_data), 0, 0, 0])
+
+    def get_dtype(self) -> Optional[torch.dtype]:
+        return None
+
+    def get_shapes(self) -> list[torch.Size]:
+        return [self.get_shape()]
+
+    def get_dtypes(self) -> list[torch.dtype]:
+        return []
+
+    def get_memory_format(self) -> MemoryFormat:
+        return self.metadata.fmt
+
+    def get_physical_size(self) -> int:
+        return self.metadata.phy_size
+
+    def pin(self) -> bool:
+        self.metadata.pin_count += 1
+        return True
+
+    def unpin(self) -> bool:
+        self.metadata.pin_count -= 1
+        if self.metadata.pin_count < 0:
+            logger.warning(
+                f"Pin count of MemoryObj {self.meta.address}"
+                f"is negative: {self.meta.pin_count}."
+                "Double unpin occurred somewhere."
+                "Setting pin count back to 0 as a hack but please find the bug."
+            )
+            self.metadata.pin_count = 0
+        return True
+
+    def ref_count_up(self):
+        pass
+
+    def ref_count_down(self):
+        pass
+
+    def get_ref_count(self) -> int:
+        return 1
+
+    def get_num_tokens(self) -> int:
+        # TODO(Jiayi): record the number of tokens somehow
+        return 1
+
+    @property
+    def metadata(self) -> MemoryObjMetadata:
+        return self.meta
+
+    @property
+    def tensor(self) -> Optional[torch.Tensor]:
+        if not self.valid:
+            logger.warning("Trying to access an invalidated MemoryObj")
+            return None
+        return None
+
+    @property
+    def byte_array(self) -> bytes:
+        return self.raw_data
+
+    @property
+    def data_ptr(self) -> int:
+        mv = memoryview(self.raw_data)
+        addr = ctypes.addressof(ctypes.c_char.from_buffer(mv))
+        return addr
+
+    @property
+    def is_pinned(self) -> bool:
+        return self.metadata.pin_count > 0
+
+    @property
+    def can_evict(self) -> bool:
+        """
+        Check whether the memory obj can be evicted.
+        A buffer memory obj can be evicted if it is not pinned.
+        """
+        return not self.is_pinned
+
+    @property
+    def raw_tensor(self) -> Optional[torch.Tensor]:
+        if not self.valid:
+            logger.warning("Trying to access an invalidated MemoryObj")
+            return None
+        return None
+
+    def get_tensor(self, index: int) -> Optional[torch.Tensor]:
+        return None
+
+    def parent(self) -> Optional["MemoryAllocatorInterface"]:
+        # NOTE: BytesBufferMemoryObj may not be allocated by any allocator,
+        # so just return None here
+        return None
+
+
+class GDSMemoryObject(MemoryObj):
+    """A slab-anchored ``MemoryObj`` for the GDS L1 tier.
+
+    The bytes live in the GDS slab file, not in host or device memory, so
+    this object carries only the slab ``(offset, size)`` (in ``meta.address``
+    / ``meta.phy_size``) and is otherwise a placeholder: ``tensor`` is always
+    ``None`` and ``byte_array`` / ``data_ptr`` raise.
+    """
+
+    def __init__(self, metadata: MemoryObjMetadata) -> None:
+        super().__init__(metadata)
+        self.valid = True
+
+    @property
+    def slab_offset(self) -> int:
+        """Byte offset of this chunk within the slab file (== ``meta.address``)."""
+        return self.meta.address
+
+    def invalidate(self) -> None:
+        self.valid = False
+
+    def is_valid(self) -> bool:
+        return self.valid
+
+    def get_size(self) -> int:
+        return self.meta.phy_size
+
+    def get_shape(self) -> torch.Size:
+        return self.meta.shape
+
+    def get_dtype(self) -> Optional[torch.dtype]:
+        return self.meta.dtype
+
+    def get_shapes(self) -> list[torch.Size]:
+        raise NotImplementedError(
+            "GDSMemoryObject.get_shapes: per-group shapes are not tracked on "
+            "the GDS path (only the singular meta.shape is); use get_shape()"
+        )
+
+    def get_dtypes(self) -> list[torch.dtype]:
+        raise NotImplementedError(
+            "GDSMemoryObject.get_dtypes: per-group dtypes are not tracked on "
+            "the GDS path (only the singular meta.dtype is); use get_dtype()"
+        )
+
+    def get_memory_format(self) -> MemoryFormat:
+        return self.meta.fmt
+
+    def get_physical_size(self) -> int:
+        return self.meta.phy_size
+
+    def ref_count_up(self) -> None:
+        raise NotImplementedError(
+            "GDSMemoryObject.ref_count_up: not used on the GDS path"
+        )
+
+    def ref_count_down(self) -> None:
+        raise NotImplementedError(
+            "GDSMemoryObject.ref_count_down: not used on the GDS path"
+        )
+
+    def get_ref_count(self) -> int:
+        raise NotImplementedError(
+            "GDSMemoryObject.get_ref_count: not used on the GDS path"
+        )
+
+    def get_num_tokens(self) -> int:
+        raise NotImplementedError(
+            "GDSMemoryObject.get_num_tokens: not used on the GDS path"
+        )
+
+    def pin(self) -> bool:
+        raise NotImplementedError("GDSMemoryObject.pin: not used on the GDS path")
+
+    def unpin(self) -> bool:
+        raise NotImplementedError("GDSMemoryObject.unpin: not used on the GDS path")
+
+    @property
+    def metadata(self) -> MemoryObjMetadata:
+        return self.meta
+
+    @property
+    def tensor(self) -> Optional[torch.Tensor]:
+        return None
+
+    @property
+    def byte_array(self) -> bytes:
+        raise NotImplementedError(
+            f"GDSMemoryObject(slab_offset={self.slab_offset}).byte_array is not "
+            "supported; bytes live in the GDS slab file and the staging buffer "
+            "is registered VRAM (no buffer protocol)."
+        )
+
+    @property
+    def data_ptr(self) -> int:
+        raise NotImplementedError(
+            f"GDSMemoryObject(slab_offset={self.slab_offset}).data_ptr is not "
+            "supported; GDS reads/writes use gpu_buffer.data_ptr() via the "
+            "gpu_ops dispatch, never the MemoryObj's data_ptr."
+        )
+
+    @property
+    def is_pinned(self) -> bool:
+        raise NotImplementedError("GDSMemoryObject.is_pinned: not used on the GDS path")
+
+    @property
+    def can_evict(self) -> bool:
+        raise NotImplementedError("GDSMemoryObject.can_evict: not used on the GDS path")
+
+    @property
+    def raw_tensor(self) -> Optional[torch.Tensor]:
+        return None
+
+    def get_tensor(self, index: int) -> Optional[torch.Tensor]:
+        return None
+
+    def parent(self) -> Optional["MemoryAllocatorInterface"]:
+        # The GDS slab is not a MemoryAllocatorInterface; dispatch in gpu_ops
+        # keys off the GDSMemoryObject type, not the parent allocator.
+        return None
+
+
+class MemoryAllocatorInterface(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.UNDEFINED,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """
+        Allocates the memory to hold a tensor of the given shape.
+
+        :param torch.Size shapes: The shape of the tensor to allocate.
+        :param torch.dtype dtypes: The dtype of the tensor to allocate.
+        :param MemoryFormat fmt: The format of the memory to allocate.
+
+        :return: A MemoryObj wrapping the allocated memory. Returns
+            None if the allocation failed.
+
+        :rtype: Optional[MemoryObj]
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.UNDEFINED,
+        allocator_type: Optional[str] = None,
+    ) -> Optional[List[MemoryObj]]:
+        """
+        Batched allocate the memory to hold a tensor of the given shape.
+
+        :param torch.Size shapes: The shape of the tensor to allocate.
+        :param torch.dtype dtypes: The dtype of the tensor to allocate.
+        :param int batch_size: The number of tensors to allocate.
+        :param MemoryFormat fmt: The format of the memory to allocate.
+
+        :return: A list of MemoryObjs wrapping the allocated memory.
+            Returns None if the allocation failed.
+
+        :rtype: Optional[List[MemoryObj]]
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def free(
+        self,
+        memory_obj: MemoryObj,
+        allocator_type: Optional[str] = None,
+    ):
+        """
+        Frees the memory allocated for the given MemoryObj.
+        Note that this function shouldn't be explicitly called.
+        Instead, use `ref_count_down` to decrease ref count.
+
+        :param MemoryObj memory_obj: The MemoryObj to free.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_free(
+        self,
+        memory_objs: List[MemoryObj],
+        allocator_type: Optional[str] = None,
+        update_stats: bool = True,
+    ):
+        """
+        Frees the memory allocated for the given list of MemoryObjs.
+
+        :param List[MemoryObj] memory_objs: The list of MemoryObjs
+            to free.
+        """
+        raise NotImplementedError
+
+    def close(self):
+        """
+        Closes the memory allocator.
+        This is called when the LMCacheEngine is closed.
+        """
+        return
+
+    def memcheck(self) -> bool:
+        """
+        Checks the memory allocator for consistency.
+
+        Returns:
+            True if everything is fine otherwise False
+        """
+        return True
+
+    # TODO(chunxiaozheng): remove if after all params replaced by shapes/dtypes
+    def _adapt_shapes_and_dtypes(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+    ) -> Tuple[list[torch.Size], list[torch.dtype]]:
+        if isinstance(shapes, torch.Size):
+            shapes = [shapes]
+
+        if isinstance(dtypes, torch.dtype):
+            dtypes = [dtypes]
+
+        assert len(shapes) == len(dtypes), (
+            f"shapes and dtypes must have the same length, "
+            f"got {len(shapes)} and {len(dtypes)}, "
+            f"shapes: {shapes}, dtypes: {dtypes}"
+        )
+        return shapes, dtypes
+
+
+class AddressManager:
+    """
+    Manages a virtual address space starting from 0 for memory allocation.
+
+    Key interfaces:
+    - allocate(size): Allocate a block of memory of the given size. The starting
+      address and the actual allocated size will be aligned.
+
+    - free(address, size): Free a previously allocated region. Note that if the
+      region is not "allocated" before, it may have internal errors.
+
+    - sbrk(size): Expand the virtual address space by the given size. The size
+      will be aligned internally.
+
+    Core assumptions:
+    - The allocated size should be aligned with ALIGN_BYTES.
+    """
+
+    ALIGN_BYTES = 4096
+
+    def __init__(self, size: int, align_bytes: int = ALIGN_BYTES):
+        """
+        Initializes the AddressManager with a given size.
+
+        Args:
+            size: The initial size of the virtual address space.
+            align_bytes: The alignment requirement for allocations.
+        """
+        self._size = size
+        self._align = align_bytes
+
+        # Current implementation: explicit list
+        self._explicit_list: SortedList[FreeBlock] = SortedList(key=lambda x: x.start)
+        self._explicit_list.add(FreeBlock(start=0, size=size))
+
+        # thread safe lock
+        self._lock = threading.Lock()
+
+        # For debugging purposes
+        self.total_allocated_size = 0
+
+    def compute_aligned_size(self, raw_size: int) -> int:
+        """
+        Helper function to compute the aligned size for a given raw size.
+
+        Args:
+            raw_size: The raw size to be aligned.
+
+        Returns:
+            The aligned size.
+        """
+        return (raw_size + self._align - 1) & ~(self._align - 1)
+
+    def _can_merge_with_prev(
+        self, curr_block: FreeBlock, prev_block: FreeBlock
+    ) -> bool:
+        """Hook: Check if curr_block can merge with prev_block."""
+        return prev_block.can_be_coalesced(curr_block)
+
+    def _can_merge_with_succ(
+        self, curr_block: FreeBlock, succ_block: FreeBlock
+    ) -> bool:
+        """Hook: Check if curr_block can merge with succ_block."""
+        return curr_block.can_be_coalesced(succ_block)
+
+    @_lmcache_nvtx_annotate
+    def _coalesce(
+        self,
+        curr_block: FreeBlock,
+        prev_block: Optional[FreeBlock],
+        succ_block: Optional[FreeBlock],
+    ):
+        """
+        Coalesces the current block with the previous and/or successor block.
+        This assumes the curr_block is NOT in self._explicit_list
+
+        Returns True if the current block was coalesced, otherwise False.
+        """
+        merge_prev = prev_block is not None and self._can_merge_with_prev(
+            curr_block, prev_block
+        )
+        merge_succ = succ_block is not None and self._can_merge_with_succ(
+            curr_block, succ_block
+        )
+
+        if merge_prev and merge_succ:
+            prev_block.size += curr_block.size + succ_block.size  # type: ignore
+            self._explicit_list.remove(succ_block)
+        elif merge_prev:
+            prev_block.size += curr_block.size  # type: ignore
+        elif merge_succ:
+            # NOTE: logically, this won't change the order of the succ_block,
+            #       so we don't need to do a "remove" and "reinsert" here
+            self._explicit_list.remove(succ_block)
+            succ_block.start -= curr_block.size  # type: ignore
+            succ_block.size += curr_block.size  # type: ignore
+            self._explicit_list.add(succ_block)
+
+        return merge_prev or merge_succ
+
+    @_lmcache_nvtx_annotate
+    @synchronized("_lock")
+    def allocate(self, size: int) -> tuple[int, int]:
+        """
+        Allocate a block of memory from the virtual address space of a given
+        size. The actual allocated size could be larger than the requested size
+        in order to satisfy alignment requirements.
+
+        Args:
+            size: The requested size of the memory block. Should be greater
+                than 0.
+
+        Returns:
+            A tuple (address, allocated_size) where address is the starting
+            address of the allocated block and allocated_size is the actual
+            size of the allocated block.
+
+        Raises:
+            RuntimeError: If no memory is available to allocate.
+        """
+        aligned_size = self.compute_aligned_size(size)
+        for block in self._explicit_list:
+            if block.size >= aligned_size:
+                break
+        else:
+            logger.warning(
+                "Failed to allocate memory block of size %d "
+                "because no memory is available",
+                size,
+            )
+            raise RuntimeError(
+                f"Failed to allocate memory block of size {size} "
+                "because no memory is available"
+            )
+
+        self._explicit_list.remove(block)
+        if block.size > aligned_size:
+            self._explicit_list.add(
+                FreeBlock(
+                    start=block.start + aligned_size,
+                    size=block.size - aligned_size,
+                )
+            )
+
+        # For debug
+        self.total_allocated_size += aligned_size
+
+        return block.start, aligned_size
+
+    @_lmcache_nvtx_annotate
+    @synchronized("_lock")
+    def batched_allocate(self, size: int, batch_size: int) -> list[tuple[int, int]]:
+        """
+        Allocate blocks of memory from the virtual address space of a given
+        size and batch size. The actual allocated size could be larger than
+        the requested size in order to satisfy alignment requirements.
+
+        Args:
+            size: The requested size of the memory block. Should be greater
+                than 0.
+            batch_size: The number of memory blocks to allocate.
+
+        Returns:
+            A list of tuple (address, allocated_size) where address is the starting
+            address of the allocated block and allocated_size is the actual size of
+            the allocated block.
+            Note: the length of the return list is the same as the batch_size.
+
+        Raises:
+            RuntimeError: If no memory is available to allocate.
+        """
+        aligned_size = self.compute_aligned_size(size)
+        remaining = batch_size
+        allocate_result: list[tuple[int, int]] = []
+
+        blocks_to_remove: list[FreeBlock] = []
+        blocks_to_add: list[FreeBlock] = []
+
+        for block in self._explicit_list:
+            if remaining <= 0:
+                break
+            if block.size < aligned_size:
+                continue
+
+            # Greedily carve out as many aligned_size chunks as possible
+            num_from_block = min(remaining, block.size // aligned_size)
+            start = block.start
+            for i in range(num_from_block):
+                allocate_result.append((start + i * aligned_size, aligned_size))
+            remaining -= num_from_block
+
+            # Mark the original block for removal
+            blocks_to_remove.append(block)
+
+            # Keep the remaining tail as a new free block if any space is left
+            used = num_from_block * aligned_size
+            if block.size > used:
+                blocks_to_add.append(
+                    FreeBlock(start=block.start + used, size=block.size - used)
+                )
+
+        if remaining > 0:
+            # Not enough memory; free list is untouched, no rollback needed
+            logger.warning(
+                "Failed to batched allocate %d memory blocks of size %d "
+                "because no enough memory is available (short by %d blocks)",
+                batch_size,
+                size,
+                remaining,
+            )
+            raise RuntimeError(
+                f"Failed to batched allocate {batch_size} memory blocks "
+                f"of size {size} because no enough memory is available"
+            )
+        if len(allocate_result) != batch_size:
+            # The length of allocate_result is not equal to batch_size;
+            # free list is untouched, no rollback needed
+            logger.warning(
+                "Failed to batched allocate %d memory blocks of size %d "
+                "because the length of allocate_result %d is not equal to batch_size",
+                batch_size,
+                size,
+                len(allocate_result),
+            )
+            raise RuntimeError(
+                f"Failed to batched allocate {batch_size} memory blocks "
+                f"of size {size} because the length of allocate_result "
+                f"{len(allocate_result)} is not equal to batch_size"
+            )
+
+        # Allocation succeeded; batch-update the free list
+        for block in blocks_to_remove:
+            self._explicit_list.remove(block)
+        for block in blocks_to_add:
+            self._explicit_list.add(block)
+
+        # Update debug statistics
+        total_allocated = aligned_size * batch_size
+        self.total_allocated_size += total_allocated
+
+        return allocate_result
+
+    @_lmcache_nvtx_annotate
+    @synchronized("_lock")
+    def free(self, address: int, size: int):
+        """
+        Free a previously allocated block of memory.
+
+        Args:
+            address: The starting address of the block to free.
+            size: The size of the block to free. Should be greater than 0.
+        """
+        new_free_block = FreeBlock(start=address, size=size)
+        index = self._explicit_list.bisect_left(new_free_block)
+        prev_block = self._explicit_list[index - 1] if index > 0 else None
+        succ_block = (
+            self._explicit_list[index] if index < len(self._explicit_list) else None
+        )
+
+        coalesced = self._coalesce(new_free_block, prev_block, succ_block)
+        if not coalesced:
+            self._explicit_list.add(new_free_block)
+
+        # For debug
+        self.total_allocated_size -= size
+
+    @synchronized("_lock")
+    def sbrk(self, size: int):
+        """
+        Expand the virtual address space by a given size.
+
+        Args:
+            size: The size to expand the address space. Will be aligned internally
+                with the ALIGN_BYTES
+        """
+        size = self.compute_aligned_size(size)
+        new_block = FreeBlock(start=self._size, size=size)
+        prev_block = self._explicit_list[-1] if len(self._explicit_list) > 0 else None
+        succ_block = None
+        coalesced = self._coalesce(new_block, prev_block, succ_block)
+        if not coalesced:
+            self._explicit_list.add(new_block)
+
+        self._size += size
+
+    def get_heap_size(self) -> int:
+        """
+        Get the total size of the address space.
+
+        Returns:
+            The total size in bytes.
+        """
+        return self._size
+
+    def get_free_size(self) -> int:
+        """
+        Get the total free size in the address space.
+
+        Returns:
+            The total free size in bytes.
+        """
+        return self._size - self.total_allocated_size
+
+    def check_consistency(self) -> bool:
+        """
+        Check if the address manager is consistent.
+
+        Returns:
+            True if consistent, False otherwise.
+        """
+        # Check if free blocks are properly coalesced
+        for prev, succ in zip(
+            self._explicit_list[:-1], self._explicit_list[1:], strict=False
+        ):
+            if prev.can_be_coalesced(succ):
+                return False
+
+        # Check if total size matches
+        total_free_size = sum(block.size for block in self._explicit_list)
+        if total_free_size + self.total_allocated_size != self._size:
+            return False
+
+        return True
+
+
+_CORE_EXPORTS = [
+    "AddressManager",
+    "BytesBufferMemoryObj",
+    "FreeBlock",
+    "GDSMemoryObject",
+    "MemoryAllocatorInterface",
+    "MemoryFormat",
+    "MemoryObj",
+    "MemoryObjMetadata",
+    "TensorMemoryObj",
+    "torch_device_type",
+]
+
+__all__ = list(_CORE_EXPORTS)
diff --git a/lmcache/v1/metadata.py b/lmcache/v1/metadata.py
new file mode 100644
index 0000000..237a091
--- /dev/null
+++ b/lmcache/v1/metadata.py
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class LMCacheMetadata:
+    """
+    LMCacheMetadata should be extracted from the northbound
+    serving engine configuration and wrap the extraction of
+    attributes (e.g. model name, tp rank, etc.)
+    """
+
+    """name of the LLM model"""
+    model_name: str
+    """ global world size when running under a distributed setting
+    (total number of workers)"""
+    world_size: int
+    """ host world size (workers on active localhost)
+    This information can be useful for multi-node
+    deployment. Will be the same as world_size
+    in single-node deployments.
+    """
+    local_world_size: int
+    """ worker id when running under a distributed setting """
+    worker_id: int
+    """ host worker id (a gpu bound worker id on active localhost)
+    This information can be useful for multi-node deployment.
+    Will be the same as worker_id in single-node deployments.
+    """
+    local_worker_id: int
+    """ the data type of kv tensors """
+    # (Deprecated) Will be replaced by kv_layer_groups_manager in the future
+    kv_dtype: torch.dtype
+    """ the shape of kv tensors """
+    # (Deprecated) Will be replaced by kv_layer_groups_manager in the future
+    """ (num_layer, 2, chunk_size, num_kv_head, head_size) """
+    kv_shape: tuple[int, int, int, int, int]
+    """ whether use MLA"""
+    use_mla: bool = False
+    """ the role of the current instance (e.g., 'scheduler', 'worker') """
+    role: Optional[str] = None
+    """ the first rank of the distributed setting """
+    # TODO(baoloongmao): first_rank should be configurable
+    first_rank = 0
+    served_model_name: Optional[str] = None
+    """chunk size"""
+    chunk_size: int = 256
+    """Manager for groups of layers with identical KV cache structure.
+
+    ``None`` until the serving-engine adapter (e.g. the vLLM connector)
+    registers KV caches and constructs the manager via
+    :class:`KVLayerGroupsManager`. Consumers must guard against ``None``
+    when accessed before registration.
+    """
+    kv_layer_groups_manager: Optional[KVLayerGroupsManager] = None
+    """ engine_id for RPC path (used by lookup client/server) """
+    engine_id: Optional[str] = None
+    """ extra config from kv_connector (e.g., lmcache_rpc_port) """
+    kv_connector_extra_config: Optional[dict] = None
+
+    def is_first_rank(self) -> bool:
+        """Check if the current worker is the first rank"""
+        return self.worker_id == self.first_rank
+
+    def get_dtypes(self) -> list[torch.dtype]:
+        """Return per-group dtypes, or the legacy single dtype if the
+        manager has not been registered yet (e.g. some unit tests)."""
+        klg_manager = self.kv_layer_groups_manager
+        if klg_manager is not None and klg_manager.kv_layer_groups:
+            return [group.dtype for group in klg_manager.kv_layer_groups]
+        return [self.kv_dtype]
+
+    def get_shapes(self, num_tokens: Optional[int] = None) -> list[torch.Size]:
+        """Get the shapes of the KV cache in LMCache"""
+        if num_tokens is None:
+            num_tokens = self.chunk_size
+        klg_manager = self.kv_layer_groups_manager
+        if klg_manager is not None and klg_manager.kv_layer_groups:
+            # Read kv_size from each group's shape_desc rather than self.use_mla
+            # so heterogeneous groups (should any ever co-exist) are handled.
+            return [
+                torch.Size(
+                    [
+                        group.shape_desc.kv_size,
+                        group.num_layers,
+                        num_tokens,
+                        group.hidden_dim_size,
+                    ]
+                )
+                for group in klg_manager.kv_layer_groups
+            ]
+        return [
+            torch.Size(
+                [
+                    self.kv_shape[1],
+                    self.kv_shape[0],
+                    num_tokens,
+                    self.kv_shape[3] * self.kv_shape[4],
+                ]
+            )
+        ]
+
+    def get_num_groups(self) -> int:
+        klg_manager = self.kv_layer_groups_manager
+        if klg_manager is not None and klg_manager.kv_layer_groups:
+            return klg_manager.num_groups
+        return 1
diff --git a/lmcache/v1/mp_coordinator/__init__.py b/lmcache/v1/mp_coordinator/__init__.py
new file mode 100644
index 0000000..520006e
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/__init__.py
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MP coordinator for LMCache multi-process (mp) servers.
+
+A standalone FastAPI process that mp servers across nodes register with, so they
+can be coordinated as a fleet: state reconcile (e.g. quota persistence and
+broadcast on join), blend-lookup routing across model replicas, and KV-cache
+operations (pin, prefetch, ...).
+
+The coordinator exposes a REST API; mp servers register / heartbeat / deregister
+over HTTP, and the coordinator pushes commands back to each mp server's own HTTP
+server. The package currently ships the framework -- the FastAPI app with
+auto-discovered ``http_apis`` routers, an instance registry, and a health-check
+loop -- plus the ``/instances`` membership resource. Further capabilities are
+added as new ``http_apis`` routers without framework changes; to push to an mp
+server, a router resolves its address from the registry and POSTs to that
+server's specific endpoint.
+"""
diff --git a/lmcache/v1/mp_coordinator/__main__.py b/lmcache/v1/mp_coordinator/__main__.py
new file mode 100644
index 0000000..62c48a4
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/__main__.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Entrypoint for the mp coordinator process.
+
+Run with ``python -m lmcache.v1.mp_coordinator``. Configuration is read from
+``LMCACHE_MP_COORDINATOR_*`` environment variables (see
+:class:`MPCoordinatorConfig`).
+"""
+
+# Third Party
+import uvicorn
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_coordinator.app import create_app
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+
+logger = init_logger(__name__)
+
+
+def main() -> None:
+    """Build the coordinator app from the environment and serve it."""
+    config = MPCoordinatorConfig.from_env()
+    app = create_app(config)
+    uvicorn.run(
+        app,
+        host=config.host,
+        port=config.port,
+        log_level="info",
+        timeout_keep_alive=config.timeout_keep_alive,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/v1/mp_coordinator/app.py b/lmcache/v1/mp_coordinator/app.py
new file mode 100644
index 0000000..878cd91
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/app.py
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: Apache-2.0
+"""FastAPI application factory for the mp coordinator.
+
+The coordinator is a FastAPI app. Endpoints are auto-discovered from the
+``http_apis`` package (the same convention as the mp server's HTTP API) and stay
+thin, operating on the shared collaborators carried on ``app.state``: ``config``,
+``registry``, ``quota_manager``, ``usage_manager``, and ``eviction_manager``.
+The lifespan runs background tasks for health-checking (eviction of instances
+whose heartbeats have lapsed) and L2 eviction (quota enforcement).
+
+Adding a capability = a new ``http_apis/<name>_api.py`` router (auto-discovered)
+that uses those shared collaborators. To push to an mp server, a future router
+resolves the instance's address from the registry (``ip`` + ``http_port``) and
+POSTs to that server's specific endpoint. A domain with real logic/state of its
+own adds a ``<name>_service.py`` stashed on ``app.state`` here; thin domains
+(like membership) just use the registry directly.
+"""
+
+# Standard
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+import asyncio
+import contextlib
+
+# Third Party
+from fastapi import FastAPI
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.mp_coordinator.blend_directory import GlobalBlendMatcher
+from lmcache.v1.mp_coordinator.cache_control.eviction_manager import (
+    L2EvictionManager,
+)
+from lmcache.v1.mp_coordinator.cache_control.prefetch_manager import PrefetchManager
+from lmcache.v1.mp_coordinator.cache_control.resync_manager import L2ResyncManager
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+from lmcache.v1.mp_coordinator.http_apis.dependencies import CoordinatorContext
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+from lmcache.v1.utils.router_discovery import discover_api_routers
+
+logger = init_logger(__name__)
+
+
+def evict_stale(registry: InstanceRegistry, instance_timeout: float) -> list[str]:
+    """Deregister every instance whose heartbeat is older than the timeout.
+
+    Args:
+        registry: The shared instance registry.
+        instance_timeout: Max seconds since the last heartbeat before eviction.
+
+    Returns:
+        The ids of instances evicted in this sweep.
+    """
+    evicted = []
+    for instance_id in registry.stale(instance_timeout):
+        if registry.deregister(instance_id) is not None:
+            logger.warning("Instance %s timed out; evicted", instance_id)
+            evicted.append(instance_id)
+    return evicted
+
+
+def create_app(config: MPCoordinatorConfig) -> FastAPI:
+    """Build the coordinator FastAPI app.
+
+    Args:
+        config: The coordinator configuration.
+
+    Returns:
+        A configured FastAPI application. ``app.state`` carries the shared
+        collaborators (``config``, ``registry``, ``quota_manager``,
+        ``usage_manager``, ``blend_directory``); all ``http_apis`` routers are
+        registered.
+    """
+    registry = InstanceRegistry()
+    quota_manager = QuotaManager()
+    usage_manager = L2UsageManager()
+    eviction_manager = L2EvictionManager(
+        quota_manager=quota_manager,
+        usage_manager=usage_manager,
+        eviction_ratio=config.eviction_ratio,
+        trigger_watermark=config.trigger_watermark,
+    )
+    resync_manager = L2ResyncManager(
+        usage_manager=usage_manager,
+        eviction_manager=eviction_manager,
+        page_size=config.resync_page_size,
+    )
+    prefetch_manager = PrefetchManager()
+    # Resolves pin requests' token_ids to object keys; must match the fleet's
+    # chunk size and hash algorithm (see MPCoordinatorConfig).
+    token_hasher = TokenHasher(
+        chunk_size=config.chunk_size, hash_algorithm=config.hash_algorithm
+    )
+    blend_directory = GlobalBlendMatcher(
+        chunk_size=config.chunk_size, probe_stride=config.blend_probe_stride
+    )
+    # Typed context the cache handlers resolve via ``get_context``;
+    # ``outbound_client`` is filled in by the lifespan (bound to the loop).
+    ctx = CoordinatorContext(
+        registry=registry,
+        quota_manager=quota_manager,
+        usage_manager=usage_manager,
+        eviction_manager=eviction_manager,
+        prefetch_manager=prefetch_manager,
+        token_hasher=token_hasher,
+    )
+
+    async def _health_loop() -> None:
+        """Evict stale instances on a timer until cancelled."""
+        while True:
+            await asyncio.sleep(config.health_check_interval)
+            evict_stale(registry, config.instance_timeout)
+
+    async def _eviction_loop(http_client: httpx.AsyncClient) -> None:
+        """Periodically check usage against quotas and dispatch
+        eviction RPCs to any one registered MP server.
+
+        Safe to start immediately: salts without an explicit quota are
+        exempt from eviction until the external quota controller sets a
+        default limit via ``PUT /quota/config`` (after re-syncing the
+        per-salt quotas), so a cold quota table cannot mass-evict."""
+        while True:
+            await asyncio.sleep(config.eviction_check_interval)
+            await eviction_manager.execute_evictions(registry, http_client)
+
+    async def _startup_resync(http_client: httpx.AsyncClient) -> None:
+        """One-shot backfill of usage + eviction trackers from a live
+        MP server's actual L2 contents."""
+        await resync_manager.wait_and_resync(
+            registry=registry,
+            http_client=http_client,
+            poll_interval=config.resync_poll_interval,
+            max_wait=config.resync_max_wait,
+        )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        """Start background tasks and clean up resources on shutdown."""
+        # Shared async client for outbound coordinator → MP server
+        # calls (eviction dispatch + startup resync). Created inside
+        # the lifespan so it binds to the running event loop.
+        outbound_client = httpx.AsyncClient(timeout=30.0)
+        # Fill in the context's outbound client so request handlers (e.g. POST
+        # /cache/prefetches) can issue outbound calls; background loops capture
+        # the local ``outbound_client`` directly.
+        ctx.outbound_client = outbound_client
+        health_task = None
+        eviction_task = None
+        resync_task = None
+        if config.health_check_interval > 0:
+            health_task = asyncio.create_task(_health_loop())
+        if config.eviction_check_interval > 0:
+            eviction_task = asyncio.create_task(_eviction_loop(outbound_client))
+        if config.enable_startup_resync:
+            resync_task = asyncio.create_task(_startup_resync(outbound_client))
+        logger.info(
+            "MP coordinator listening on http://%s:%d", config.host, config.port
+        )
+        try:
+            yield
+        finally:
+            for task in (health_task, eviction_task, resync_task):
+                if task is not None:
+                    task.cancel()
+                    with contextlib.suppress(asyncio.CancelledError):
+                        await task
+            await eviction_manager.wait_for_in_flight_dispatches()
+            await outbound_client.aclose()
+
+    app = FastAPI(title="LMCache MP Coordinator", version="1.0.0", lifespan=lifespan)
+    # The typed context carries the cache collaborators handlers compose from
+    # (registry, quota/usage/eviction/prefetch managers, outbound client);
+    # handlers resolve it via ``get_context``.
+    app.state.ctx = ctx
+    # Out-of-context collaborators kept on app.state directly: ``config`` and the
+    # blend directory (its own router), plus ``resync_manager`` for the lifespan.
+    app.state.config = config
+    app.state.resync_manager = resync_manager
+    app.state.blend_directory = blend_directory
+
+    apis_path = Path(__file__).parent / "http_apis"
+    package = f"{__package__}.http_apis"
+    for router in discover_api_routers(apis_path, package):
+        app.include_router(router)
+
+    return app
diff --git a/lmcache/v1/mp_coordinator/blend_client.py b/lmcache/v1/mp_coordinator/blend_client.py
new file mode 100644
index 0000000..da27b84
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/blend_client.py
@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Blend mp-server side client for the coordinator fingerprint directory.
+
+The blend module runs in sync thread pools with no asyncio loop, so this client
+owns a synchronous ``httpx.Client`` plus a background daemon, mirroring the
+module's existing ``_fingerprint_queue`` worker. STORE publishes are best-effort
+and fire-and-forget; LOOKUP match queries follow the same non-blocking
+submit-once / poll-on-recall pattern the blend lookup already uses for its prefix
+and sparse legs (the handler never blocks a worker thread on the round-trip).
+
+It is **opt-in**: with no coordinator URL configured the blend module receives
+``None`` and every publish/query path is skipped, so behavior is unchanged.
+"""
+
+# Standard
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from queue import Empty, Queue
+import os
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_coordinator.schemas import encode_tokens
+
+logger = init_logger(__name__)
+
+# poll_match sentinel: query submitted, round-trip not finished yet.
+PENDING = object()
+
+# (method, path, json_body) -> json_dict
+_RequestFn = Callable[[str, str, dict], dict]
+
+
+@dataclass
+class RemoteMatch:
+    """One chunk matched in the fleet directory (see directory.GlobalMatch).
+
+    Attributes:
+        object_key: Shared-L2 storage key of the matched chunk.
+        old_st: Token position in the stored sequence (re-RoPE source).
+        cur_st: Token position in the request (re-RoPE target).
+    """
+
+    object_key: str
+    old_st: int
+    cur_st: int
+
+
+@dataclass
+class _PublishItem:
+    """A queued best-effort write: an HTTP ``method``/``path``/``payload``."""
+
+    method: str
+    path: str
+    payload: dict
+
+
+@dataclass
+class _MatchItem:
+    """A queued match query for request ``rid``."""
+
+    rid: str
+    model_scope: str
+    tokens: list[int]
+
+
+class BlendCoordinatorClient:
+    """Background bridge from the blend module to the coordinator directory.
+
+    Thread-safe. Handler threads enqueue publishes and match queries; one daemon
+    thread dequeues them, dispatching each match query to a thread pool so
+    round-trips run concurrently. Match results land in a dict the handler
+    polls. Match queries drain ahead of publishes so lookup latency is not held
+    up by best-effort store traffic.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "",
+        *,
+        request_fn: _RequestFn | None = None,
+        request_timeout: float = 2.0,
+        match_budget_s: float = 2.0,
+        match_concurrency: int = 8,
+    ) -> None:
+        """Create the client and start its daemon.
+
+        Args:
+            base_url: Coordinator base URL (e.g. ``http://coordinator:9300``).
+                Ignored when ``request_fn`` is supplied.
+            request_fn: Optional injected ``(method, path, json_body) ->
+                json_dict`` used instead of the built-in HTTP client (for
+                testing). Must raise on transport failure.
+            request_timeout: Per-request HTTP timeout in seconds.
+            match_budget_s: Per-lookup wall-clock budget the blend module uses to
+                bound the optional global leg, including queue wait.
+            match_concurrency: Max match round-trips in flight at once (the
+                match dispatch pool size). Must be >= 1.
+
+        Raises:
+            ValueError: If ``match_concurrency`` is not positive.
+        """
+        if match_concurrency < 1:
+            raise ValueError(f"match_concurrency must be >= 1, got {match_concurrency}")
+        self.match_budget_s = match_budget_s
+        self._client = None
+        if request_fn is None:
+            # Third Party
+            import httpx
+
+            client = httpx.Client(timeout=request_timeout)
+            base = base_url.rstrip("/")
+
+            def _http_request(method: str, path: str, payload: dict) -> dict:
+                resp = client.request(method, f"{base}{path}", json=payload)
+                resp.raise_for_status()
+                return resp.json()
+
+            self._client = client
+            self._request: _RequestFn = _http_request
+        else:
+            self._request = request_fn
+
+        self._publish_q: "Queue[_PublishItem]" = Queue()
+        self._match_q: "Queue[_MatchItem]" = Queue()
+        self._results: dict[str, object] = {}
+        self._results_lock = threading.Lock()
+        self._stop = threading.Event()
+        self._match_pool = ThreadPoolExecutor(
+            max_workers=match_concurrency, thread_name_prefix="cb-coord-match"
+        )
+        self._worker = threading.Thread(
+            target=self._run, name="cb-coordinator-client", daemon=True
+        )
+        self._worker.start()
+
+    def enqueue_register(self, ranges: list[dict]) -> None:
+        """Queue a best-effort register of stored ranges.
+
+        Args:
+            ranges: Wire-form ``StoreRange`` dicts to register.
+        """
+        if not ranges:
+            return
+        self._publish_q.put(
+            _PublishItem("POST", "/blend/fingerprints", {"ranges": ranges})
+        )
+
+    def enqueue_evict(self, object_keys: list[str]) -> None:
+        """Queue a best-effort eviction of fingerprints by storage key.
+
+        Args:
+            object_keys: ``object_key`` values to evict.
+        """
+        if not object_keys:
+            return
+        self._publish_q.put(
+            _PublishItem("DELETE", "/blend/fingerprints", {"object_keys": object_keys})
+        )
+
+    def submit_match(self, rid: str, model_scope: str, tokens: list[int]) -> None:
+        """Submit a match query for a request once (idempotent per ``rid``).
+
+        Args:
+            rid: Request id, the poll key.
+            model_scope: Scope to match within.
+            tokens: The request tokens (the coordinator hashes and probes them).
+        """
+        with self._results_lock:
+            if rid in self._results:
+                return
+            self._results[rid] = PENDING
+        self._match_q.put(_MatchItem(rid=rid, model_scope=model_scope, tokens=tokens))
+
+    def poll_match(self, rid: str) -> object:
+        """Return the match state for a request.
+
+        Args:
+            rid: Request id used in :meth:`submit_match`.
+
+        Returns:
+            :data:`PENDING` while in flight, a ``list[RemoteMatch]`` when ready,
+            or ``None`` if never submitted (or already consumed).
+        """
+        with self._results_lock:
+            return self._results.get(rid)
+
+    def take_match(self, rid: str) -> None:
+        """Drop a request's stored match state once consumed.
+
+        Args:
+            rid: Request id to clear.
+        """
+        with self._results_lock:
+            self._results.pop(rid, None)
+
+    def close(self) -> None:
+        """Stop the daemon, drain the match pool, and close the HTTP client."""
+        self._stop.set()
+        self._worker.join(timeout=2.0)
+        self._match_pool.shutdown(wait=False)
+        if self._client is not None:
+            self._client.close()
+
+    @classmethod
+    def maybe_from_env(cls) -> "BlendCoordinatorClient | None":
+        """Build a client from ``LMCACHE_COORDINATOR_*`` env vars if configured.
+
+        Reads ``LMCACHE_COORDINATOR_URL`` (required to enable) and
+        ``LMCACHE_COORDINATOR_BLEND_TIMEOUT`` (default 1.0s). This timeout is the
+        wall-clock budget on the optional global leg: the blend module polls
+        until the match resolves (matches, or ``[]`` on failure) but gives up
+        once the budget elapses, so it bounds how long the critical path waits
+        -- including time queued behind other match queries -- before proceeding
+        local-only. It is used both as the per-request HTTP timeout and as the
+        module's per-lookup deadline. Keep it small.
+
+        Returns:
+            A started client, or ``None`` when no coordinator URL is configured
+            (the blend module then runs purely local).
+        """
+        url = os.getenv("LMCACHE_COORDINATOR_URL", "").strip()
+        if not url:
+            return None
+        concurrency = int(os.getenv("LMCACHE_COORDINATOR_BLEND_MATCH_CONCURRENCY", "8"))
+        timeout = float(os.getenv("LMCACHE_COORDINATOR_BLEND_TIMEOUT", "1.0"))
+        logger.info("Blend coordinator client enabled -> %s", url)
+        return cls(
+            url,
+            request_timeout=timeout,
+            match_budget_s=timeout,
+            match_concurrency=concurrency,
+        )
+
+    # -- daemon ------------------------------------------------------------
+
+    def _run(self) -> None:
+        """Dispatch match queries to the pool (priority), then publishes."""
+        while not self._stop.is_set():
+            try:
+                item = self._match_q.get(timeout=0.05)
+            except Empty:
+                item = None
+            if item is not None:
+                self._match_pool.submit(self._handle_match, item)
+                continue
+            try:
+                self._handle_publish(self._publish_q.get_nowait())
+            except Empty:
+                pass
+
+    def _handle_match(self, item: _MatchItem) -> None:
+        """POST a match query and store the parsed matches (miss on error)."""
+        matches: list[RemoteMatch] = []
+        try:
+            body = self._request(
+                "POST",
+                "/blend/match",
+                {
+                    "model_scope": item.model_scope,
+                    "tokens_b64": encode_tokens(item.tokens),
+                },
+            )
+            matches = [
+                RemoteMatch(
+                    object_key=m["object_key"],
+                    old_st=int(m["old_st"]),
+                    cur_st=int(m["cur_st"]),
+                )
+                for m in body.get("matches", [])
+            ]
+        except Exception:
+            # Best-effort: a failed query degrades to local-only (empty result).
+            logger.warning("Blend coordinator match failed for %s", item.rid)
+        with self._results_lock:
+            # Only fill if still awaited (not taken/cleared meanwhile).
+            if self._results.get(item.rid) is PENDING:
+                self._results[item.rid] = matches
+
+    def _handle_publish(self, item: _PublishItem) -> None:
+        """Send a best-effort register/evict; failures are logged and dropped."""
+        try:
+            self._request(item.method, item.path, item.payload)
+        except Exception:
+            logger.warning("Blend coordinator %s %s failed", item.method, item.path)
diff --git a/lmcache/v1/mp_coordinator/blend_directory.py b/lmcache/v1/mp_coordinator/blend_directory.py
new file mode 100644
index 0000000..3ea9e64
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/blend_directory.py
@@ -0,0 +1,392 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Fleet-wide CacheBlend fingerprint directory held by the MP coordinator.
+
+Blend mp-servers publish stored token ranges on STORE and query with the request
+tokens on LOOKUP; the coordinator does **all hashing and matching**, so the whole
+matching algorithm lives here and can evolve without touching or redeploying
+servers. Servers send raw tokens plus the storage mapping they alone know
+(``object_key`` per chunk, base token position).
+
+The algorithm matches the local matcher (`BlendTokenRangeMatcherV3`): a table of
+non-overlapping chunk polynomial hashes, probed by a strided rolling-hash scan of
+the request.
+
+- **Match unit = chunk_size** (fleet config). Each stored chunk is one poly hash.
+- **Probe stride** (the querying server's inference block size) controls which
+  request offsets can seed a match; sent per query, so servers with different
+  (per-machine, dynamic) block sizes interoperate.
+- **Scope** = the model name; cross-model content never matches. ``cache_salt``
+  is **not** part of the scope: matched hashes are expanded to ObjectKeys with
+  the *requester's* salt at retrieve (``ipc_key_to_object_keys``), so a
+  cross-salt match simply misses at L2 -- isolation holds with one table per
+  model instead of one per ``(model, salt)``.
+- **TP rank** is resolved at retrieve (``ipc_key_to_object_keys``), not here.
+
+``object_key`` is the chunk's shared-L2 storage key (``th``), which is
+prefix-bound and computed by the storing server -- the coordinator cannot derive
+it, so it is supplied with each published range.
+
+Concurrency: fingerprints are partitioned per scope (``_ScopeTable``), each
+mutated and probed in place under its own lock; a top-level lock guards only the
+scope map and the eviction map. The probe is vectorized, so the locked section
+is short.
+
+The probe mirrors the local matcher: the strided rolling hashes index a
+per-scope **direct-address table** in one numpy gather, and only occupied slots
+reach a short Python loop, where a full-64-bit re-check rejects bucket
+collisions. Inserts write the table in place (O(1) per chunk); evictions
+tombstone; a rebuild -- which also compacts tombstones -- happens only on the
+write path, when the table outgrows its load factor. Tables are sized per scope
+(power of two, a few times the entry count), so small scopes stay small, unlike
+the local matcher's fixed 2^20 array.
+
+Thread-safe and ephemeral. A stale entry or a (rare) bucket collision only costs
+a wasted prefetch or a missed reuse, recomputed downstream -- never wrong KV.
+
+See ``docs/design/v1/mp_coordinator/blend_lookup.md``.
+"""
+
+# Standard
+from collections import defaultdict
+from dataclasses import dataclass
+import threading
+
+# Third Party
+import numpy as np
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.multiprocess.token_hasher import (
+    chunk_hash_windows_numba,
+    rolling_hash_windows_numba,
+    update_table_id_numba,
+)
+
+logger = init_logger(__name__)
+
+# Fleet-constant polynomial base for blend fingerprints. The coordinator owns
+# the hashing, so this lives here: the same base hashes published chunks
+# (``chunk_hash_windows_numba``) and probes requests (``rolling_hash_windows_numba``)
+# so the two align. Constant across a coordinator's lifetime.
+POLY_BASE = np.uint64(0x9E3779B97F4A7C15)
+
+# Table size = smallest power of two >= _TABLE_GROWTH * live entries, keeping
+# the load factor (and thus bucket-collision recall loss) low for a few
+# bytes/chunk.
+_TABLE_GROWTH = 4
+_MIN_TABLE_SIZE = 1 << 10
+
+
+@dataclass
+class StoreRange:
+    """One stored token range published by a blend server.
+
+    Attributes:
+        model_scope: Reuse-compatibility scope (the model name).
+        tokens: The stored tokens (``token_ids[start:end]``). The coordinator
+            chunks these at ``chunk_size`` and hashes each chunk.
+        object_keys: Shared-L2 storage key (hex of the ObjectKey chunk hash) per
+            chunk, in order; chunk ``i`` maps to ``object_keys[i]``.
+        old_st_base: Token position of the range's first token in the stored
+            sequence; chunk ``i`` starts at ``old_st_base + i * chunk_size``.
+    """
+
+    model_scope: str
+    tokens: list[int]
+    object_keys: list[str]
+    old_st_base: int
+
+
+@dataclass
+class _ChunkLoc:
+    """Where a registered chunk lives (anchor index value)."""
+
+    object_key: str
+    old_st: int
+
+
+@dataclass
+class GlobalMatch:
+    """One matched chunk returned to a querying server.
+
+    Attributes:
+        object_key: Shared-L2 storage key of the matched chunk.
+        old_st: Token position of the chunk in the stored sequence (re-RoPE).
+        cur_st: Token position in the request where the match was found.
+    """
+
+    object_key: str
+    old_st: int
+    cur_st: int
+
+
+class _ScopeTable:
+    """One scope's fingerprint table, mutated in place under ``lock``.
+
+    Mirrors the local matcher: ``slots`` direct-addresses the low bits of a poly
+    hash to a compact entry id (``-1`` = empty, last writer wins on collision);
+    ``hashes[cid]`` / ``locs[cid]`` hold the full hash (collision rejection) and
+    chunk location. ``poly_to_cid`` gives idempotent insert and eviction lookup.
+    Eviction tombstones ``locs[cid]``; a rebuild (on load-factor growth, or when
+    tombstones outnumber live entries) re-creates ``slots`` compacted.
+
+    All methods require the caller to hold ``lock``.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty table at the minimum size."""
+        self.lock = threading.Lock()
+        self.poly_to_cid: dict[int, int] = {}
+        self.hashes: list[int] = []
+        self.locs: "list[_ChunkLoc | None]" = []
+        self.slots: np.ndarray = np.full(_MIN_TABLE_SIZE, -1, dtype=np.int64)
+        self.mask: np.uint64 = np.uint64(_MIN_TABLE_SIZE - 1)
+
+    def insert(self, poly: int, loc: _ChunkLoc) -> bool:
+        """Insert one fingerprint, growing the table when needed.
+
+        Args:
+            poly: The chunk's full 64-bit poly hash.
+            loc: The chunk's storage location.
+
+        Returns:
+            ``True`` if newly inserted, ``False`` if the hash was present.
+        """
+        if poly in self.poly_to_cid:
+            return False
+        cid = len(self.hashes)
+        self.hashes.append(poly)
+        self.locs.append(loc)
+        self.poly_to_cid[poly] = cid
+        self.slots[poly & int(self.mask)] = cid
+        if _TABLE_GROWTH * len(self.poly_to_cid) > self.slots.shape[0]:
+            self._rebuild()
+        return True
+
+    def evict(self, poly: int) -> bool:
+        """Tombstone one fingerprint, compacting when tombstones dominate.
+
+        Args:
+            poly: The chunk's full 64-bit poly hash.
+
+        Returns:
+            ``True`` if evicted, ``False`` if the hash was absent.
+        """
+        cid = self.poly_to_cid.pop(poly, None)
+        if cid is None:
+            return False
+        slot = poly & int(self.mask)
+        if self.slots[slot] == cid:  # a colliding later insert may own the slot
+            self.slots[slot] = -1
+        self.locs[cid] = None
+        if len(self.poly_to_cid) < len(self.locs) // 2:
+            self._rebuild()
+        return True
+
+    def _rebuild(self) -> None:
+        """Re-create ``slots`` sized to the live entries, dropping tombstones."""
+        live = [(poly, self.locs[cid]) for poly, cid in self.poly_to_cid.items()]
+        size = _MIN_TABLE_SIZE
+        while size < _TABLE_GROWTH * len(live):
+            size <<= 1
+        self.hashes = [poly for poly, _ in live]
+        self.locs = [loc for _, loc in live]
+        self.poly_to_cid = {poly: cid for cid, (poly, _) in enumerate(live)}
+        self.slots = np.full(size, -1, dtype=np.int64)
+        self.mask = np.uint64(size - 1)
+        if live:
+            update_table_id_numba(
+                np.array(self.hashes, dtype=np.uint64),
+                self.slots,
+                np.arange(len(live), dtype=np.int64),
+            )
+
+
+class GlobalBlendMatcher:
+    """Thread-safe fleet-wide chunk fingerprint directory.
+
+    Hashes published token ranges into per-scope direct-address tables, mutated
+    in place, and matches request tokens with a vectorized strided rolling-hash
+    probe under the scope's lock.
+    """
+
+    def __init__(self, chunk_size: int = 256, probe_stride: int = 1) -> None:
+        """Initialize an empty directory.
+
+        Args:
+            chunk_size: Tokens per chunk (the LMCache chunk size; fleet config).
+                The match unit; must be the same value the storing servers use.
+            probe_stride: Positions between match probes. With partial-fill reuse
+                any offset is usable, so the default ``1`` (probe every offset)
+                gives full recall; raise only to trade recall for coordinator CPU.
+
+        Raises:
+            ValueError: If ``chunk_size`` or ``probe_stride`` is not positive.
+        """
+        if chunk_size < 1:
+            raise ValueError(f"chunk_size must be >= 1, got {chunk_size}")
+        if probe_stride < 1:
+            raise ValueError(f"probe_stride must be >= 1, got {probe_stride}")
+        self._chunk_size = chunk_size
+        self._probe_stride = probe_stride
+        # Top-level lock: guards _scopes and _by_key only (cheap, short holds).
+        self._lock = threading.Lock()
+        self._scopes: dict[str, _ScopeTable] = {}
+        # Reverse map for eviction: object_key -> its (scope, poly_hash) keys.
+        self._by_key: dict[str, list[tuple[str, int]]] = {}
+
+    def _get_or_create_scope(self, model_scope: str) -> _ScopeTable:
+        """Return the table for ``model_scope``, creating it if absent.
+
+        Args:
+            model_scope: The reuse scope to fetch a table for.
+
+        Returns:
+            The (possibly newly created) per-scope table.
+        """
+        with self._lock:
+            table = self._scopes.get(model_scope)
+            if table is None:
+                table = _ScopeTable()
+                self._scopes[model_scope] = table
+            return table
+
+    def register(self, ranges: list[StoreRange]) -> int:
+        """Hash and insert published token ranges (idempotent per chunk).
+
+        The coordinator chunks each range's tokens, hashes each chunk, and maps
+        the poly hash to its storage key and position. Re-publishing a
+        ``(model_scope, poly_hash)`` already present is a no-op.
+
+        A range whose chunk count (``len(tokens) // chunk_size``) does not equal
+        its ``object_keys`` count is **skipped** with an error log: the two are
+        1:1 by construction, so a mismatch signals a publisher bug or a
+        chunk-size disagreement, and registering the aligned prefix would map
+        chunks to the wrong storage keys (a shift) -- worse than dropping it.
+
+        Args:
+            ranges: Stored token ranges to register.
+
+        Returns:
+            Number of chunk fingerprints newly inserted (excludes idempotent
+            skips).
+        """
+        # Hash every range outside any lock; keep only well-formed ranges.
+        prepared: list[tuple[str, np.ndarray, list[str], int]] = []
+        for rng in ranges:
+            arr = np.asarray(rng.tokens, dtype=np.uint64)
+            polys = chunk_hash_windows_numba(arr, self._chunk_size, POLY_BASE)
+            n_chunks = int(polys.shape[0])
+            if n_chunks != len(rng.object_keys):
+                logger.error(
+                    "blend register: %d chunks from %d tokens (chunk_size=%d) "
+                    "but %d object_keys for scope %s; skipping range "
+                    "(publisher/chunk_size mismatch)",
+                    n_chunks,
+                    len(rng.tokens),
+                    self._chunk_size,
+                    len(rng.object_keys),
+                    rng.model_scope,
+                )
+                continue
+            prepared.append((rng.model_scope, polys, rng.object_keys, rng.old_st_base))
+
+        inserted = 0
+        for model_scope, polys, object_keys, old_st_base in prepared:
+            table = self._get_or_create_scope(model_scope)
+            new_keys: list[tuple[str, int]] = []
+            with table.lock:
+                for i in range(len(object_keys)):
+                    poly = int(polys[i])
+                    loc = _ChunkLoc(object_keys[i], old_st_base + i * self._chunk_size)
+                    if table.insert(poly, loc):
+                        new_keys.append((object_keys[i], poly))
+            if new_keys:
+                inserted += len(new_keys)
+                with self._lock:
+                    for object_key, poly in new_keys:
+                        self._by_key.setdefault(object_key, []).append(
+                            (model_scope, poly)
+                        )
+        return inserted
+
+    def remove(self, object_keys: list[str]) -> int:
+        """Evict all fingerprints for the given storage keys.
+
+        Args:
+            object_keys: Storage keys of chunks to evict.
+
+        Returns:
+            Number of fingerprint entries removed.
+        """
+        # Collect keys under the top-level lock, then mutate per scope.
+        by_scope: dict[str, list[int]] = defaultdict(list)
+        with self._lock:
+            for object_key in object_keys:
+                for model_scope, poly in self._by_key.pop(object_key, []):
+                    by_scope[model_scope].append(poly)
+
+        removed = 0
+        for model_scope, polys in by_scope.items():
+            with self._lock:
+                table = self._scopes.get(model_scope)
+            if table is None:
+                continue
+            with table.lock:
+                for poly in polys:
+                    if table.evict(poly):
+                        removed += 1
+        return removed
+
+    def match(
+        self, model_scope: str, tokens: "list[int] | np.ndarray"
+    ) -> list[GlobalMatch]:
+        """Match request tokens against the directory.
+
+        Rolls a chunk-window hash over the request, then probes the scope's
+        direct-address table every ``probe_stride`` positions in one numpy
+        gather; a full 64-bit re-check in the sparse hit loop rejects bucket
+        collisions. De-duplicates by ``object_key``. Mirrors the local
+        ``BlendTokenRangeMatcherV3.match_sub_sequence``.
+
+        Args:
+            model_scope: Scope to match within (the model name).
+            tokens: The request tokens (a ``list[int]`` or a ``uint64`` array).
+
+        Returns:
+            Matches in ascending ``cur_st`` order; empty if nothing matched.
+        """
+        arr = np.asarray(tokens, dtype=np.uint64)
+        if arr.shape[0] < self._chunk_size:
+            return []
+
+        with self._lock:
+            table = self._scopes.get(model_scope)
+        if table is None:
+            return []
+
+        rolling = rolling_hash_windows_numba(arr, self._chunk_size, POLY_BASE)
+        probe = rolling[:: self._probe_stride]
+        matches: list[GlobalMatch] = []
+        seen: set[str] = set()
+        stride = self._probe_stride
+        with table.lock:
+            # One gather: strided hash -> slot's entry index (-1 = empty slot).
+            entry_ids = table.slots[probe & table.mask]
+            hit_positions = np.nonzero(entry_ids >= 0)[0]
+            for p in hit_positions.tolist():
+                cid = int(entry_ids[p])
+                if int(probe[p]) != table.hashes[cid]:
+                    continue  # bucket collision: different content in this slot
+                loc = table.locs[cid]
+                if loc is None or loc.object_key in seen:
+                    continue  # evicted, or already matched
+                seen.add(loc.object_key)
+                matches.append(
+                    GlobalMatch(
+                        object_key=loc.object_key,
+                        old_st=loc.old_st,
+                        cur_st=p * stride,
+                    )
+                )
+        return matches
diff --git a/lmcache/v1/mp_coordinator/cache_control/__init__.py b/lmcache/v1/mp_coordinator/cache_control/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/cache_control/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/mp_coordinator/cache_control/event_listener.py b/lmcache/v1/mp_coordinator/cache_control/event_listener.py
new file mode 100644
index 0000000..86fcdae
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/cache_control/event_listener.py
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MP-server-side L2 event client: batches adapter store/lookup/delete
+events and flushes them to the coordinator on a timer."""
+
+# Standard
+import asyncio
+import threading
+
+# Third Party
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.internal_api import L2AdapterListener
+from lmcache.v1.mp_coordinator.schemas import (
+    EventType,
+    ReportUsageRequest,
+    ReportUsageResponse,
+    UsageEvent,
+)
+
+logger = init_logger(__name__)
+
+_DEFAULT_FLUSH_INTERVAL = 1.0
+
+
+class L2EventListener(L2AdapterListener):
+    """L2 adapter listener that batches events and flushes to the
+    coordinator. Run :meth:`run` as a background task.
+
+    Args:
+        client: HTTP client.
+        coordinator_url: Coordinator base URL.
+        instance_id: This MP server's id (sent with every batch).
+        flush_interval: Seconds between flushes.
+    """
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        coordinator_url: str,
+        instance_id: str,
+        flush_interval: float = _DEFAULT_FLUSH_INTERVAL,
+    ) -> None:
+        self._client = client
+        self._base_url = coordinator_url.rstrip("/")
+        self._instance_id = instance_id
+        self._flush_interval = flush_interval
+        self._seq = 0
+        self._lock = threading.Lock()
+        self._buffer: list[UsageEvent] = []
+
+    # -- L2AdapterListener implementation ------------------------------------
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        """Buffer store events for each key. Thread-safe."""
+        for obj, size in zip(keys, sizes, strict=True):
+            event = UsageEvent(
+                type=EventType.STORE,
+                key=obj.to_encoded_object_key(),
+                bytes=size,
+            )
+            with self._lock:
+                self._buffer.append(event)
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        """Buffer lookup events for each key. Thread-safe."""
+        for obj in keys:
+            event = UsageEvent(
+                type=EventType.LOOKUP,
+                key=obj.to_encoded_object_key(),
+                bytes=0,
+            )
+            with self._lock:
+                self._buffer.append(event)
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        """Buffer DELETE events for each key. Thread-safe."""
+        for obj in keys:
+            event = UsageEvent(
+                type=EventType.DELETE,
+                key=obj.to_encoded_object_key(),
+                bytes=0,
+            )
+            with self._lock:
+                self._buffer.append(event)
+
+    # -- Flush loop ----------------------------------------------------------
+
+    async def run(self) -> None:
+        """Drain the buffer on a timer until cancelled. Flush failures
+        drop the batch to bound buffer growth when the coordinator is
+        down."""
+        while True:
+            await asyncio.sleep(self._flush_interval)
+            await self._flush()
+
+    async def _flush(self) -> None:
+        """Send buffered events to the coordinator."""
+        with self._lock:
+            if not self._buffer:
+                return
+            batch = self._buffer
+            self._buffer = []
+            self._seq += 1
+            seq = self._seq
+
+        body = ReportUsageRequest(
+            instance_id=self._instance_id,
+            seq=seq,
+            events=batch,
+        )
+        try:
+            resp = await self._client.post(
+                f"{self._base_url}/quota/events",
+                json=body.model_dump(),
+            )
+            resp.raise_for_status()
+            result = ReportUsageResponse.model_validate(resp.json())
+            logger.debug("Flushed %d L2 events to coordinator", result.recorded)
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning(
+                "Failed to flush %d L2 events to coordinator: %s",
+                len(batch),
+                e,
+            )
diff --git a/lmcache/v1/mp_coordinator/cache_control/eviction_manager.py b/lmcache/v1/mp_coordinator/cache_control/eviction_manager.py
new file mode 100644
index 0000000..b05a6d9
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/cache_control/eviction_manager.py
@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Coordinator-side per-``cache_salt`` LRU eviction.
+
+Periodically compares per-salt usage against ``watermark * quota``;
+when over threshold, dispatches a ``DELETE /cache/objects`` to one registered MP
+server. LRU bookkeeping is updated when the corresponding ``delete``
+event arrives back via ``POST /quota/events``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import asdict
+import asyncio
+
+# Third Party
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.eviction_policy.isolated_lru import (
+    IsolatedLRUEvictionPolicy,
+)
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry
+from lmcache.v1.multiprocess.cache_control.object_service import (
+    MAX_DELETE_BATCH,
+)
+
+logger = init_logger(__name__)
+
+
+class L2EvictionManager:
+    """Per-``cache_salt`` LRU eviction manager for the coordinator.
+
+    Args:
+        quota_manager: Shared quota registry.
+        usage_manager: Shared usage manager. Writes to the size ledger
+            (``record_stored`` / ``record_evicted``) are the caller's
+            responsibility, paired with :meth:`on_store` /
+            :meth:`on_remove`.
+        eviction_ratio: Fraction of tracked keys to evict per cycle.
+        trigger_watermark: Eviction fires when usage reaches this
+            fraction of the quota.
+    """
+
+    def __init__(
+        self,
+        quota_manager: QuotaManager,
+        usage_manager: L2UsageManager,
+        eviction_ratio: float = 0.5,
+        trigger_watermark: float = 1.0,
+    ) -> None:
+        self._quota_manager = quota_manager
+        self._usage_manager = usage_manager
+        self._eviction_ratio = max(0.0, min(1.0, eviction_ratio))
+        self._trigger_watermark = trigger_watermark
+        self._policy = IsolatedLRUEvictionPolicy()
+        self._in_flight_dispatches: set[asyncio.Task] = set()
+        # Reference-counted L2 pins: a key is excluded from eviction plans while
+        # its count is > 0. Not persisted across coordinator restarts.
+        self._pin_counts: dict[ObjectKey, int] = {}
+
+    def on_store(self, key: ObjectKey) -> None:
+        """Register a stored key in the LRU. Per-salt bytes are the
+        caller's responsibility (see :meth:`L2UsageManager.record_stored`)."""
+        self._policy.on_keys_created([key])
+
+    def on_lookup(self, key: ObjectKey) -> None:
+        """Touch ``key`` in the LRU (move to MRU end)."""
+        self._policy.on_keys_touched([key])
+
+    def on_remove(self, key: ObjectKey) -> None:
+        """Drop ``key`` from the LRU. Per-salt bytes are the caller's
+        responsibility (see :meth:`L2UsageManager.record_evicted`)."""
+        self._policy.on_keys_removed([key])
+
+    def pin(self, keys: list[ObjectKey]) -> None:
+        """Increment the L2 pin count of each key (excludes it from eviction).
+
+        Args:
+            keys: The object keys to pin.
+        """
+        for key in keys:
+            self._pin_counts[key] = self._pin_counts.get(key, 0) + 1
+
+    def unpin(self, keys: list[ObjectKey]) -> None:
+        """Decrement the L2 pin count of each key (floored at 0).
+
+        Args:
+            keys: The object keys to unpin.
+        """
+        for key in keys:
+            count = self._pin_counts.get(key, 0)
+            if count <= 1:
+                self._pin_counts.pop(key, None)
+            else:
+                self._pin_counts[key] = count - 1
+
+    def compute_eviction_plan(self) -> dict[str, list[ObjectKey]]:
+        """Select eviction candidates per ``cache_salt``.
+
+        Salts over ``watermark * quota`` get ``eviction_ratio`` of
+        their LRU keys; a quota of ``0`` means full eviction. Salts
+        without an explicit quota use the registry's default limit
+        (``QuotaManager.effective_limit_bytes``): until the external
+        quota controller sets one (``PUT /quota/config``), the
+        coordinator will not start evicting unquota'd salts.
+        """
+        tracked_salts = self._policy.get_tracked_salts()
+        eviction_plan: dict[str, list[ObjectKey]] = {}
+
+        for cache_salt in tracked_salts:
+            current_bytes = self._usage_manager.get(cache_salt)
+            if current_bytes <= 0:
+                continue
+            limit = self._quota_manager.effective_limit_bytes(cache_salt)
+            if limit is None:
+                # No explicit quota and no default configured yet —
+                # exempt until the quota controller arms enforcement.
+                continue
+            if current_bytes < self._trigger_watermark * limit:
+                continue
+
+            effective_ratio = 1.0 if limit == 0 else self._eviction_ratio
+            actions = self._policy.get_eviction_actions(
+                effective_ratio,
+                cache_salt=cache_salt,
+                key_eligible_filter=lambda key: key not in self._pin_counts,
+            )
+            keys_to_evict: list[ObjectKey] = []
+            for action in actions:
+                keys_to_evict.extend(action.keys)
+
+            if keys_to_evict:
+                eviction_plan[cache_salt] = keys_to_evict
+                sizes = [
+                    self._usage_manager.get_key_size(k) or 0 for k in keys_to_evict
+                ]
+                evict_bytes = sum(sizes)
+                logger.info(
+                    "Eviction plan for cache_salt=%r: %d keys "
+                    "(%d bytes) to free; usage=%d, quota=%d, "
+                    "watermark=%.2f, ratio=%.2f",
+                    cache_salt,
+                    len(keys_to_evict),
+                    evict_bytes,
+                    current_bytes,
+                    limit,
+                    self._trigger_watermark,
+                    effective_ratio,
+                )
+
+        return eviction_plan
+
+    async def execute_evictions(
+        self,
+        registry: InstanceRegistry,
+        http_client: httpx.AsyncClient,
+    ) -> dict[str, list[ObjectKey]]:
+        """Compute the plan and fire-and-forget one or more
+        ``DELETE /cache/objects`` requests to one random registered MP server.
+
+        The plan's keys are split into chunks of at most
+        ``MAX_DELETE_BATCH`` and each chunk is dispatched as its own
+        DELETE, because the MP endpoint rejects any single request over that
+        cap with HTTP 400.
+
+        Returns the scheduled plan as soon as the background dispatch
+        tasks are spawned. The LRU is not cleared here — that happens
+        when the corresponding ``delete`` event arrives at
+        ``POST /quota/events``. At-least-once semantics; safe because the
+        underlying delete is idempotent.
+        """
+        plan = self.compute_eviction_plan()
+        if not plan:
+            return plan
+
+        target = registry.random_instance()
+        if target is None:
+            logger.warning(
+                "Eviction plan computed (%d salts) but no MP servers are "
+                "registered; skipping dispatch",
+                len(plan),
+            )
+            return plan
+
+        url = f"http://{target.ip}:{target.http_port}/cache/objects"
+        all_keys: list[ObjectKey] = [k for keys in plan.values() for k in keys]
+
+        for start in range(0, len(all_keys), MAX_DELETE_BATCH):
+            chunk = all_keys[start : start + MAX_DELETE_BATCH]
+            body = {"keys": [asdict(k.to_encoded_object_key()) for k in chunk]}
+            task = asyncio.create_task(
+                self._dispatch_eviction(
+                    http_client=http_client,
+                    url=url,
+                    body=body,
+                    instance_id=target.instance_id,
+                    key_count=len(chunk),
+                    salt_count=len({k.cache_salt for k in chunk}),
+                )
+            )
+            self._in_flight_dispatches.add(task)
+            task.add_done_callback(self._in_flight_dispatches.discard)
+        return plan
+
+    async def wait_for_in_flight_dispatches(self) -> None:
+        """Await every outstanding fire-and-forget dispatch."""
+        await asyncio.gather(*self._in_flight_dispatches, return_exceptions=True)
+
+    @staticmethod
+    async def _dispatch_eviction(
+        http_client: httpx.AsyncClient,
+        url: str,
+        body: dict,
+        instance_id: str,
+        key_count: int,
+        salt_count: int,
+    ) -> None:
+        """Send the DELETE and log the outcome. Failures are not retried."""
+        try:
+            # ``httpx.AsyncClient.delete`` doesn't accept ``json=``;
+            # ``request("DELETE", ...)`` is the supported form.
+            resp = await http_client.request("DELETE", url, json=body)
+            resp.raise_for_status()
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning(
+                "Eviction dispatch to %s (%d keys) failed: %s",
+                instance_id,
+                key_count,
+                e,
+            )
+            return
+        logger.info(
+            "Eviction dispatched to %s: %d keys across %d salts",
+            instance_id,
+            key_count,
+            salt_count,
+        )
diff --git a/lmcache/v1/mp_coordinator/cache_control/prefetch_manager.py b/lmcache/v1/mp_coordinator/cache_control/prefetch_manager.py
new file mode 100644
index 0000000..cb93067
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/cache_control/prefetch_manager.py
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Coordinator-side warm-prefetch dispatch.
+
+Forwards a client's warm-prefetch request to one named MP server and proxies
+its status. The MP server's ``POST /cache/prefetches`` submits the load and returns
+a ``request_id`` immediately (the load runs in the server's storage-manager
+thread); the coordinator relays that id back to the client, which then polls
+``GET /cache/prefetches/{instance_id}/{request_id}`` on the coordinator until the
+server reports completion. There is no background polling on either side -- the
+submit and status calls are quick and the client drives completion on demand.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_coordinator.registry import MPInstance
+
+logger = init_logger(__name__)
+
+
+class PrefetchManager:
+    """Submit warm-prefetch requests to MP servers and proxy their status."""
+
+    async def submit_prefetch(
+        self,
+        target: MPInstance,
+        http_client: httpx.AsyncClient,
+        model_name: str,
+        world_size: int,
+        token_ids: list[int],
+        cache_salt: str,
+    ) -> dict[str, Any]:
+        """``POST /cache/prefetches`` to ``target`` and return its JSON reply.
+
+        Args:
+            target: The MP server to warm.
+            http_client: Shared async client for outbound coordinator calls.
+            model_name: Model whose layout the target uses to allocate L1.
+            world_size: World size selecting the layout and per-rank fan-out.
+            token_ids: Prompt tokens whose complete chunks should be warmed.
+            cache_salt: Per-tenant isolation salt applied to the produced keys.
+
+        Returns:
+            The server's reply, e.g. ``{"request_id", "chunks", "status"}`` or
+            ``{"chunks": 0, "status": "noop"}``.
+
+        Raises:
+            httpx.HTTPError: If the target is unreachable or returns non-2xx.
+        """
+        url = f"http://{target.ip}:{target.http_port}/cache/prefetches"
+        body = {
+            "model_name": model_name,
+            "world_size": world_size,
+            "token_ids": token_ids,
+            "cache_salt": cache_salt,
+        }
+        resp = await http_client.post(url, json=body)
+        resp.raise_for_status()
+        logger.info(
+            "Prefetch submitted to %s: %d tokens", target.instance_id, len(token_ids)
+        )
+        return resp.json()
+
+    async def get_status(
+        self,
+        target: MPInstance,
+        http_client: httpx.AsyncClient,
+        request_id: str,
+    ) -> tuple[int, dict[str, Any]]:
+        """Proxy ``GET /cache/prefetches/{request_id}`` on ``target``.
+
+        Args:
+            target: The MP server holding the job.
+            http_client: Shared async client for outbound coordinator calls.
+            request_id: The id returned by :meth:`submit_prefetch`.
+
+        Returns:
+            ``(status_code, body)`` from the server (e.g. 200 with a status
+            body, or 404 for an unknown id), relayed verbatim to the caller.
+
+        Raises:
+            httpx.HTTPError: If the target is unreachable (transport error).
+        """
+        url = f"http://{target.ip}:{target.http_port}/cache/prefetches/{request_id}"
+        resp = await http_client.get(url)
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {"detail": resp.text}
+        return resp.status_code, body
diff --git a/lmcache/v1/mp_coordinator/cache_control/resync_manager.py b/lmcache/v1/mp_coordinator/cache_control/resync_manager.py
new file mode 100644
index 0000000..93a41a2
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/cache_control/resync_manager.py
@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Coordinator-side L2 resync.
+
+On boot, paginates an MP server's ``GET /cache/objects`` and seeds the
+coordinator's usage + eviction trackers so quota enforcement starts
+from a representative baseline rather than zero. Best-effort: failures
+are logged and the manager gives up; the ongoing event stream corrects
+any initial blind spots.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import asyncio
+
+# Third Party
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import EncodedObjectKey
+from lmcache.v1.mp_coordinator.cache_control.eviction_manager import L2EvictionManager
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry, MPInstance
+
+logger = init_logger(__name__)
+
+
+class L2ResyncManager:
+    """Backfill the coordinator's L2 trackers from a live MP server's
+    actual L2 contents. Best-effort; not snapshot-isolated.
+
+    Args:
+        usage_manager: Shared usage manager.
+        eviction_manager: Shared eviction manager.
+        page_size: ``page_size`` forwarded to the MP server's
+            ``/cache/objects`` endpoint.
+    """
+
+    def __init__(
+        self,
+        usage_manager: L2UsageManager,
+        eviction_manager: L2EvictionManager,
+        page_size: int = 1000,
+    ) -> None:
+        if page_size <= 0:
+            raise ValueError(f"page_size must be positive (got {page_size})")
+        self._usage_manager = usage_manager
+        self._eviction_manager = eviction_manager
+        self._page_size = page_size
+
+    async def resync_from(
+        self,
+        instance: MPInstance,
+        http_client: httpx.AsyncClient,
+        request_timeout: float = 30.0,
+    ) -> int:
+        """Page through ``instance``'s L2 keys and record each one.
+
+        Returns the number of keys recorded; stops early on HTTP
+        failure and returns the partial count.
+        """
+        url = f"http://{instance.ip}:{instance.http_port}/cache/objects"
+        page_token: str | None = None
+        total = 0
+        pages = 0
+        while True:
+            params: dict[str, str | int] = {"page_size": self._page_size}
+            if page_token is not None:
+                params["page_token"] = page_token
+            try:
+                resp = await http_client.get(
+                    url, params=params, timeout=request_timeout
+                )
+                resp.raise_for_status()
+                body = resp.json()
+            except (httpx.HTTPError, ValueError) as exc:
+                logger.warning(
+                    "Resync from %s failed at page %d (recorded %d so far): %s",
+                    instance.instance_id,
+                    pages,
+                    total,
+                    exc,
+                )
+                return total
+            pages += 1
+            for entry in body.get("entries", []):
+                try:
+                    key = entry["key"]
+                    encoded = EncodedObjectKey(
+                        chunk_hash_hex=key["chunk_hash_hex"],
+                        model_name=key["model_name"],
+                        kv_rank=key["kv_rank"],
+                        object_group_id=key.get("object_group_id", 0),
+                        cache_salt=key.get("cache_salt", ""),
+                    )
+                    obj_key = encoded.to_object_key()
+                    size_bytes = int(entry["size_bytes"])
+                except (KeyError, TypeError, ValueError) as exc:
+                    logger.debug("Skipping unparsable resync entry %r: %s", entry, exc)
+                    continue
+                self._usage_manager.record_stored(obj_key, size_bytes)
+                self._eviction_manager.on_store(obj_key)
+                total += 1
+            page_token = body.get("next_page_token")
+            if page_token is None:
+                break
+        logger.info(
+            "Resync from %s complete: %d keys across %d page(s)",
+            instance.instance_id,
+            total,
+            pages,
+        )
+        return total
+
+    async def wait_and_resync(
+        self,
+        registry: InstanceRegistry,
+        http_client: httpx.AsyncClient,
+        poll_interval: float,
+        max_wait: float,
+        request_timeout: float = 30.0,
+    ) -> int:
+        """Poll the registry until an MP server registers, then resync.
+
+        Returns the number of keys recorded; ``0`` if no MP server
+        registered within ``max_wait``.
+        """
+        deadline = asyncio.get_running_loop().time() + max_wait
+        while True:
+            target = registry.random_instance()
+            if target is not None:
+                logger.info(
+                    "Starting L2 resync from %s (%s:%d)",
+                    target.instance_id,
+                    target.ip,
+                    target.http_port,
+                )
+                return await self.resync_from(
+                    target, http_client, request_timeout=request_timeout
+                )
+            if asyncio.get_running_loop().time() >= deadline:
+                logger.warning(
+                    "L2 resync giving up: no MP servers registered within %ds",
+                    int(max_wait),
+                )
+                return 0
+            await asyncio.sleep(poll_interval)
diff --git a/lmcache/v1/mp_coordinator/cache_control/usage_manager.py b/lmcache/v1/mp_coordinator/cache_control/usage_manager.py
new file mode 100644
index 0000000..e18abf6
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/cache_control/usage_manager.py
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-``cache_salt`` L2 usage manager for the MP coordinator."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+
+logger = init_logger(__name__)
+
+
+class L2UsageManager:
+    """Thread-safe in-memory ledger of L2 byte usage per ``cache_salt``,
+    plus a per-key size map so re-stores don't double-count."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._bytes_by_salt: dict[str, int] = {}
+        self._total_bytes: int = 0
+        self._key_sizes: dict[ObjectKey, int] = {}
+
+    def has_key(self, key: ObjectKey) -> bool:
+        """Return ``True`` if ``key`` has a recorded size."""
+        with self._lock:
+            return key in self._key_sizes
+
+    def get_key_size(self, key: ObjectKey) -> int | None:
+        """Return the bytes tracked for ``key``, or ``None`` if unknown."""
+        with self._lock:
+            return self._key_sizes.get(key)
+
+    def record_stored(self, key: ObjectKey, num_bytes: int) -> None:
+        """Record that ``key`` is resident on L2 at ``num_bytes``.
+
+        Re-storing the same key replaces its size (delta-adjusts the
+        per-salt and global totals); a re-store at the same size is a
+        no-op.
+
+        Raises:
+            ValueError: ``num_bytes`` is negative.
+        """
+        if num_bytes < 0:
+            raise ValueError(f"num_bytes must be non-negative (got {num_bytes})")
+        with self._lock:
+            existing = self._key_sizes.get(key)
+            if existing is not None:
+                delta = num_bytes - existing
+            else:
+                delta = num_bytes
+            if delta == 0:
+                # Already tracked at the same size — keep the entry,
+                # nothing to adjust.
+                self._key_sizes[key] = num_bytes
+                return
+            self._key_sizes[key] = num_bytes
+            salt = key.cache_salt
+            new_salt_total = self._bytes_by_salt.get(salt, 0) + delta
+            if new_salt_total <= 0:
+                self._bytes_by_salt.pop(salt, None)
+            else:
+                self._bytes_by_salt[salt] = new_salt_total
+            self._total_bytes = max(0, self._total_bytes + delta)
+
+    def record_evicted(self, key: ObjectKey) -> int:
+        """Drop ``key`` from the ledger and return the bytes freed
+        (``0`` if ``key`` was unknown)."""
+        with self._lock:
+            size = self._key_sizes.pop(key, None)
+            if size is None or size == 0:
+                return size or 0
+            salt = key.cache_salt
+            current = self._bytes_by_salt.get(salt, 0)
+            new_val = current - size
+            if new_val < 0:
+                logger.warning(
+                    "Usage underflow for cache_salt=%r on evict: %d - %d = %d",
+                    salt,
+                    current,
+                    size,
+                    new_val,
+                )
+                new_val = 0
+            if new_val == 0:
+                self._bytes_by_salt.pop(salt, None)
+            else:
+                self._bytes_by_salt[salt] = new_val
+            self._total_bytes = max(0, self._total_bytes - size)
+            return size
+
+    def get(self, cache_salt: str) -> int:
+        """Return the current byte usage for ``cache_salt``."""
+        with self._lock:
+            return self._bytes_by_salt.get(cache_salt, 0)
+
+    def get_all(self) -> dict[str, int]:
+        """Return a snapshot copy of per-salt byte usage."""
+        with self._lock:
+            return dict(self._bytes_by_salt)
+
+    def get_total(self) -> int:
+        """Return total bytes tracked across all salts."""
+        with self._lock:
+            return self._total_bytes
diff --git a/lmcache/v1/mp_coordinator/config.py b/lmcache/v1/mp_coordinator/config.py
new file mode 100644
index 0000000..9386156
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/config.py
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Configuration for the mp coordinator process.
+
+A small, explicit, frozen dataclass with environment-variable loading
+(``LMCACHE_MP_COORDINATOR_*``).
+"""
+
+# Standard
+from dataclasses import dataclass
+import os
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+_ENV_PREFIX = "LMCACHE_MP_COORDINATOR_"
+
+
+@dataclass(frozen=True)
+class MPCoordinatorConfig:
+    """HTTP bind address and timing parameters for the coordinator.
+
+    Attributes:
+        host: Host the coordinator's HTTP server binds to.
+        port: Port the coordinator's HTTP server binds to.
+        instance_timeout: Seconds without a heartbeat after which an instance is
+            considered dead and evicted. Set this comfortably above the mp
+            servers' own heartbeat cadence (which they choose).
+        health_check_interval: Seconds between health-check sweeps. A value of
+            ``0`` disables the health-check loop.
+        eviction_check_interval: Seconds between eviction sweeps. A value of
+            ``0`` disables the eviction loop.
+        eviction_ratio: Fraction of tracked keys (by count) to evict per
+            cycle (0.0 to 1.0).
+        trigger_watermark: Eviction fires when usage reaches this fraction
+            of the quota (0.0 to 1.0).
+        chunk_size: Tokens per KV chunk. The single fleet chunk size: it is the
+            CacheBlend match unit *and* resolves a pin request's ``token_ids`` to
+            object keys. Must equal the MP servers' ``--chunk-size`` or blend
+            matches and resolved pin keys will not line up with what was stored.
+        hash_algorithm: Token hash algorithm for pin key resolution. Must equal
+            the MP servers' ``--hash-algorithm`` (default ``blake3``, which is
+            self-contained; other algorithms require vLLM importable in the
+            coordinator process).
+        blend_probe_stride: Positions between match probes. With partial-fill
+            reuse any offset is usable, so ``1`` (probe every offset) gives full
+            recall; raise only to trade recall for coordinator CPU.
+        enable_startup_resync: When ``True``, run a one-shot L2 resync
+            on startup to backfill trackers from an MP server's
+            ``GET /cache/objects``.
+        resync_poll_interval: Seconds between registry checks while
+            waiting for the first MP server to register.
+        resync_max_wait: Maximum seconds startup resync waits for an MP
+            server before giving up.
+        resync_page_size: ``page_size`` forwarded to ``GET /cache/objects``
+            during resync.
+        timeout_keep_alive: Seconds the HTTP server keeps idle connections
+            open before closing them. Must be greater than the heartbeat
+            interval of MP servers to avoid race-condition disconnects.
+    """
+
+    host: str = "0.0.0.0"
+    port: int = 9300
+    instance_timeout: float = 30.0
+    health_check_interval: float = 10.0
+    eviction_check_interval: float = 5.0
+    eviction_ratio: float = 0.2
+    trigger_watermark: float = 1.0
+    chunk_size: int = 256
+    hash_algorithm: str = "blake3"
+    blend_probe_stride: int = 1
+    enable_startup_resync: bool = True
+    resync_poll_interval: float = 1.0
+    resync_max_wait: float = 60.0
+    resync_page_size: int = 1000
+    timeout_keep_alive: int = 10
+
+    def __post_init__(self) -> None:
+        """Validate timing parameters.
+
+        Raises:
+            ValueError: If a timing parameter is non-positive/negative.
+        """
+        if self.instance_timeout <= 0:
+            raise ValueError("instance_timeout must be positive")
+        if self.health_check_interval < 0:
+            raise ValueError("health_check_interval must be non-negative")
+        if self.eviction_check_interval < 0:
+            raise ValueError("eviction_check_interval must be non-negative")
+        if not 0.0 <= self.eviction_ratio <= 1.0:
+            raise ValueError("eviction_ratio must be between 0.0 and 1.0")
+        if not 0.0 < self.trigger_watermark <= 1.0:
+            raise ValueError(
+                "trigger_watermark must be between 0.0 (exclusive) and 1.0"
+            )
+        if self.resync_poll_interval <= 0:
+            raise ValueError("resync_poll_interval must be positive")
+        if self.resync_max_wait < 0:
+            raise ValueError("resync_max_wait must be non-negative")
+        if self.resync_page_size <= 0:
+            raise ValueError("resync_page_size must be positive")
+        if self.chunk_size < 1:
+            raise ValueError("chunk_size must be positive")
+        if not self.hash_algorithm:
+            raise ValueError("hash_algorithm must be a non-empty string")
+        if self.blend_probe_stride < 1:
+            raise ValueError("blend_probe_stride must be positive")
+        if self.timeout_keep_alive <= 0:
+            raise ValueError("timeout_keep_alive must be positive")
+
+    @classmethod
+    def from_env(cls) -> "MPCoordinatorConfig":
+        """Build a config from ``LMCACHE_MP_COORDINATOR_*`` environment variables.
+
+        Unset variables fall back to the dataclass defaults.
+
+        Returns:
+            A validated configuration instance.
+        """
+
+        def _str(name: str, default: str) -> str:
+            return os.getenv(f"{_ENV_PREFIX}{name}", default)
+
+        def _num(name: str, default: float, cast) -> float:
+            raw = os.getenv(f"{_ENV_PREFIX}{name}")
+            if raw is None:
+                return default
+            try:
+                return cast(raw)
+            except ValueError:
+                logger.warning(
+                    "Invalid %s%s=%r; using default %s", _ENV_PREFIX, name, raw, default
+                )
+                return default
+
+        def _bool(name: str, default: bool) -> bool:
+            raw = os.getenv(f"{_ENV_PREFIX}{name}")
+            if raw is None:
+                return default
+            return raw.strip().lower() in ("1", "true", "yes", "on")
+
+        return cls(
+            host=_str("HOST", cls.host),
+            port=int(_num("PORT", cls.port, int)),
+            instance_timeout=_num("INSTANCE_TIMEOUT", cls.instance_timeout, float),
+            health_check_interval=_num(
+                "HEALTH_CHECK_INTERVAL", cls.health_check_interval, float
+            ),
+            eviction_check_interval=_num(
+                "EVICTION_CHECK_INTERVAL", cls.eviction_check_interval, float
+            ),
+            eviction_ratio=_num("EVICTION_RATIO", cls.eviction_ratio, float),
+            trigger_watermark=_num("TRIGGER_WATERMARK", cls.trigger_watermark, float),
+            chunk_size=int(_num("CHUNK_SIZE", cls.chunk_size, int)),
+            hash_algorithm=_str("HASH_ALGORITHM", cls.hash_algorithm),
+            blend_probe_stride=int(
+                _num("BLEND_PROBE_STRIDE", cls.blend_probe_stride, int)
+            ),
+            enable_startup_resync=_bool(
+                "ENABLE_STARTUP_RESYNC", cls.enable_startup_resync
+            ),
+            resync_poll_interval=_num(
+                "RESYNC_POLL_INTERVAL", cls.resync_poll_interval, float
+            ),
+            resync_max_wait=_num("RESYNC_MAX_WAIT", cls.resync_max_wait, float),
+            resync_page_size=int(_num("RESYNC_PAGE_SIZE", cls.resync_page_size, int)),
+            timeout_keep_alive=int(
+                _num("TIMEOUT_KEEP_ALIVE", cls.timeout_keep_alive, int)
+            ),
+        )
diff --git a/lmcache/v1/mp_coordinator/http_apis/__init__.py b/lmcache/v1/mp_coordinator/http_apis/__init__.py
new file mode 100644
index 0000000..ef6ce9e
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/__init__.py
@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Auto-discovered REST routers for the mp coordinator.
+
+Each ``*_api.py`` module exposes a module-level ``router`` (a FastAPI
+``APIRouter``) and is registered automatically by ``create_app``.
+"""
diff --git a/lmcache/v1/mp_coordinator/http_apis/blend_directory_api.py b/lmcache/v1/mp_coordinator/http_apis/blend_directory_api.py
new file mode 100644
index 0000000..85c1454
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/blend_directory_api.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+"""REST resource for the global CacheBlend fingerprint directory.
+
+Blend mp-servers publish chunk fingerprints on STORE (``POST
+/blend/fingerprints``) and query them on LOOKUP (``POST /blend/match``).
+Endpoints operate on the shared :class:`GlobalBlendMatcher` reached via
+``app.state.blend_directory``.
+"""
+
+# Third Party
+from fastapi import APIRouter, Request
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_coordinator.blend_directory import (
+    GlobalBlendMatcher,
+    StoreRange,
+)
+from lmcache.v1.mp_coordinator.schemas import (
+    BlendEvictRequest,
+    BlendEvictResponse,
+    BlendFingerprintRequest,
+    BlendFingerprintResponse,
+    BlendMatchRequest,
+    BlendMatchResponse,
+    GlobalMatchModel,
+    decode_tokens,
+)
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+
+def _directory(request: Request) -> GlobalBlendMatcher:
+    """Return the shared blend directory from app state.
+
+    Args:
+        request: The incoming request.
+
+    Returns:
+        The shared :class:`GlobalBlendMatcher`.
+
+    Raises:
+        RuntimeError: If the directory is not initialized (wired by
+            ``create_app``, so this should not happen in practice).
+    """
+    directory = getattr(request.app.state, "blend_directory", None)
+    if directory is None:
+        raise RuntimeError("blend directory not initialized")
+    return directory
+
+
+@router.post("/blend/fingerprints")
+def publish_fingerprints(
+    body: BlendFingerprintRequest, request: Request
+) -> BlendFingerprintResponse:
+    """Register published chunk fingerprints (idempotent).
+
+    Returns:
+        Number of fingerprints newly inserted.
+    """
+    directory = _directory(request)
+    ranges = [
+        StoreRange(
+            model_scope=r.model_scope,
+            tokens=r.tokens,
+            object_keys=r.object_keys,
+            old_st_base=r.old_st_base,
+        )
+        for r in body.ranges
+    ]
+    inserted = directory.register(ranges) if ranges else 0
+    return BlendFingerprintResponse(inserted=inserted)
+
+
+@router.delete("/blend/fingerprints")
+def evict_fingerprints(body: BlendEvictRequest, request: Request) -> BlendEvictResponse:
+    """Evict fingerprints by storage key (idempotent).
+
+    Returns:
+        Number of fingerprint entries removed.
+    """
+    directory = _directory(request)
+    removed = directory.remove(body.object_keys) if body.object_keys else 0
+    return BlendEvictResponse(removed=removed)
+
+
+@router.post("/blend/match")
+def match_fingerprints(body: BlendMatchRequest, request: Request) -> BlendMatchResponse:
+    """Match a request's rolling-hash array against the directory.
+
+    The request tokens arrive base64-packed (``tokens_b64``); they are decoded
+    to a ``uint64`` array and handed straight to the matcher.
+
+    Returns:
+        Matched chunks (``object_key`` / ``old_st`` / ``cur_st``), ascending by
+        ``cur_st``.
+    """
+    directory = _directory(request)
+    matches = directory.match(body.model_scope, decode_tokens(body.tokens_b64))
+    return BlendMatchResponse(
+        matches=[
+            GlobalMatchModel(object_key=m.object_key, old_st=m.old_st, cur_st=m.cur_st)
+            for m in matches
+        ]
+    )
diff --git a/lmcache/v1/mp_coordinator/http_apis/cache_api.py b/lmcache/v1/mp_coordinator/http_apis/cache_api.py
new file mode 100644
index 0000000..a38812b
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/cache_api.py
@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cache-control endpoints on the coordinator (fleet-level).
+
+Warm-prefetch dispatch to a named MP server, thin over the
+:class:`PrefetchManager` on the typed :class:`CoordinatorContext` (resolved via
+:func:`get_context`). Handlers map fleet-routing failures to HTTP directly --
+``404`` for an unknown ``instance_id`` and ``502`` when an MP server is
+unreachable or rejects a proxied call.
+
+Quota writes, combined quota+usage status, and usage-event ingestion are
+accounting concerns and live in the ``/quota`` group (:mod:`quota_api`).
+"""
+
+# Third Party
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse
+import httpx
+
+# First Party
+from lmcache.v1.mp_coordinator.http_apis.dependencies import (
+    get_context,
+    get_outbound_client,
+)
+from lmcache.v1.mp_coordinator.schemas import (
+    PinRequest,
+    PinResponse,
+    PrefetchRequest,
+    PrefetchResponse,
+)
+from lmcache.v1.mp_coordinator.utils.cache_utils import resolve_object_keys
+
+router = APIRouter()
+
+
+# -- Prefetch dispatch -------------------------------------------------------
+
+
+@router.post("/cache/prefetches")
+async def request_prefetch(body: PrefetchRequest, request: Request) -> PrefetchResponse:
+    """Submit a warm prefetch of a token sequence on one MP server.
+
+    Resolves ``body.instance_id`` in the registry and proxies to that server's
+    ``POST /cache/prefetches``, which submits the load and returns a
+    ``request_id``. Poll ``GET /cache/prefetches/{instance_id}/{request_id}``.
+
+    Args:
+        body: Target instance, model/world_size, the token_ids to warm, and the
+            per-tenant cache_salt.
+
+    Returns:
+        ``PrefetchResponse`` carrying the server's ``request_id`` (empty when the
+        sequence was shorter than one chunk -- ``status`` ``"noop"``).
+
+    Raises:
+        HTTPException: 404 if ``instance_id`` is not registered; 502 if the
+            target server is unreachable or rejects the submit.
+    """
+    ctx = get_context(request)
+    target = ctx.registry.get(body.instance_id)
+    if target is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"no MP server registered with instance_id={body.instance_id!r}",
+        )
+
+    try:
+        result = await ctx.prefetch_manager.submit_prefetch(
+            target=target,
+            http_client=get_outbound_client(request),
+            model_name=body.model_name,
+            world_size=body.world_size,
+            token_ids=body.token_ids,
+            cache_salt=body.cache_salt,
+        )
+    except httpx.HTTPError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"prefetch submit to {body.instance_id!r} failed: {exc}",
+        ) from None
+
+    return PrefetchResponse(
+        instance_id=body.instance_id,
+        request_id=result.get("request_id", ""),
+        chunks=result.get("chunks", 0),
+        status=result.get("status", "submitted"),
+    )
+
+
+@router.get("/cache/prefetches/{instance_id}/{request_id}")
+async def get_prefetch_status(
+    instance_id: str, request_id: str, request: Request
+) -> JSONResponse:
+    """Proxy a warm-prefetch status poll to the owning MP server.
+
+    The warm holds no lock, so this poll only reports progress; the first poll
+    that observes completion drops the job on the server (exactly-once). Poll
+    until ``"completed"``.
+
+    Args:
+        instance_id: The MP server the prefetch was submitted to.
+        request_id: The id returned by ``POST /cache/prefetches``.
+
+    Returns:
+        The server's status body relayed verbatim with its status code (200
+        ``pending`` / ``completed``, or 404 for an unknown id).
+
+    Raises:
+        HTTPException: 404 if ``instance_id`` is not registered; 502 if the
+            target server is unreachable.
+    """
+    ctx = get_context(request)
+    target = ctx.registry.get(instance_id)
+    if target is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"no MP server registered with instance_id={instance_id!r}",
+        )
+
+    try:
+        code, payload = await ctx.prefetch_manager.get_status(
+            target=target,
+            http_client=get_outbound_client(request),
+            request_id=request_id,
+        )
+    except httpx.HTTPError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"prefetch status from {instance_id!r} failed: {exc}",
+        ) from None
+
+    return JSONResponse(status_code=code, content=payload)
+
+
+# -- Pin / unpin (L2 eviction protection) ------------------------------------
+
+
+@router.post("/cache/pins")
+async def request_pin(body: PinRequest, request: Request) -> PinResponse:
+    """Pin a token sequence's keys in the L2 eviction plan.
+
+    The coordinator resolves the token sequence to its object keys locally and
+    records them so they are excluded from its L2 eviction plan (fleet-wide,
+    per ``cache_salt``). No MP-server round-trip.
+
+    Args:
+        body: model/world_size, token_ids, cache_salt.
+
+    Returns:
+        ``PinResponse`` with ``requested`` chunks and ``affected`` L2 keys pinned.
+
+    Raises:
+        HTTPException: 400 if the token cap is exceeded or a key field is invalid.
+    """
+    ctx = get_context(request)
+    try:
+        resolved, chunks = resolve_object_keys(
+            ctx.token_hasher,
+            body.model_name,
+            body.world_size,
+            body.token_ids,
+            body.cache_salt,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from None
+
+    ctx.eviction_manager.pin(resolved)
+    return PinResponse(
+        requested=chunks,
+        affected=len(resolved),
+        status="pinned",
+    )
+
+
+@router.delete("/cache/pins")
+async def request_unpin(body: PinRequest, request: Request) -> PinResponse:
+    """Unpin a token sequence's keys from the L2 eviction plan.
+
+    Symmetric with pin: resolves the keys locally and releases them, making them
+    eligible for L2 eviction again.
+
+    Args:
+        body: model/world_size, token_ids, cache_salt.
+
+    Returns:
+        ``PinResponse`` with ``requested`` chunks and ``affected`` L2 keys unpinned.
+
+    Raises:
+        HTTPException: 400 if the token cap is exceeded or a key field is invalid.
+    """
+    ctx = get_context(request)
+    try:
+        resolved, chunks = resolve_object_keys(
+            ctx.token_hasher,
+            body.model_name,
+            body.world_size,
+            body.token_ids,
+            body.cache_salt,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from None
+
+    ctx.eviction_manager.unpin(resolved)
+    return PinResponse(
+        requested=chunks,
+        affected=len(resolved),
+        status="unpinned",
+    )
diff --git a/lmcache/v1/mp_coordinator/http_apis/dependencies.py b/lmcache/v1/mp_coordinator/http_apis/dependencies.py
new file mode 100644
index 0000000..56044b9
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/dependencies.py
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Typed per-app context for the coordinator's HTTP handlers.
+
+Instead of each handler reaching into ``request.app.state`` with stringly-typed
+``getattr`` calls, handlers resolve a single :class:`CoordinatorContext` via
+:func:`get_context`. The context is built in ``create_app``; ``outbound_client``
+is filled in by the lifespan (it must bind to the running event loop), so a
+dedicated accessor narrows that ``Optional`` for the dispatch handlers.
+"""
+
+# Standard
+from dataclasses import dataclass
+
+# Third Party
+from fastapi import Request
+import httpx
+
+# First Party
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.mp_coordinator.cache_control.eviction_manager import L2EvictionManager
+from lmcache.v1.mp_coordinator.cache_control.prefetch_manager import PrefetchManager
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+
+
+@dataclass
+class CoordinatorContext:
+    """Shared collaborators the coordinator's HTTP handlers operate on.
+
+    Attributes:
+        registry: Fleet membership (``MPInstance`` by ``instance_id``).
+        quota_manager: Per-``cache_salt`` L2 quota state.
+        usage_manager: Per-``cache_salt`` L2 usage tracking.
+        eviction_manager: Quota/LRU L2 eviction dispatcher; also holds the L2
+            pin set consulted when computing eviction plans.
+        prefetch_manager: Warm-prefetch proxy to MP servers.
+        token_hasher: Resolves a pin request's ``token_ids`` to object keys
+            (configured to match the fleet's ``chunk_size`` / ``hash_algorithm``).
+        outbound_client: Shared async client for coordinator -> MP calls. Set by
+            the lifespan (bound to the running loop); ``None`` until then.
+    """
+
+    registry: InstanceRegistry
+    quota_manager: QuotaManager
+    usage_manager: L2UsageManager
+    eviction_manager: L2EvictionManager
+    prefetch_manager: PrefetchManager
+    token_hasher: TokenHasher
+    outbound_client: httpx.AsyncClient | None = None
+
+
+def get_context(request: Request) -> CoordinatorContext:
+    """Return the per-app :class:`CoordinatorContext`.
+
+    Args:
+        request: The FastAPI request whose ``app.state`` carries the context.
+
+    Returns:
+        The shared :class:`CoordinatorContext`.
+
+    Raises:
+        RuntimeError: If the context is not initialized (wired by
+            ``create_app``, so this should not happen in practice).
+    """
+    ctx = getattr(request.app.state, "ctx", None)
+    if ctx is None:
+        raise RuntimeError("coordinator context not initialized")
+    return ctx
+
+
+def get_outbound_client(request: Request) -> httpx.AsyncClient:
+    """Return the lifespan-bound outbound client, or raise if unset.
+
+    Args:
+        request: The FastAPI request.
+
+    Returns:
+        The shared outbound :class:`httpx.AsyncClient`.
+
+    Raises:
+        RuntimeError: If accessed before the lifespan filled it in (e.g. a bare
+            app with no startup).
+    """
+    client = get_context(request).outbound_client
+    if client is None:
+        raise RuntimeError("outbound client not initialized")
+    return client
diff --git a/lmcache/v1/mp_coordinator/http_apis/health_api.py b/lmcache/v1/mp_coordinator/http_apis/health_api.py
new file mode 100644
index 0000000..dc91275
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/health_api.py
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Liveness endpoint for the mp coordinator (k8s probe)."""
+
+# Standard
+from typing import Any
+
+# Third Party
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/healthz")
+async def healthz() -> Any:
+    """Report coordinator liveness.
+
+    Returns:
+        ``{"status": "healthy"}``.
+    """
+    return {"status": "healthy"}
diff --git a/lmcache/v1/mp_coordinator/http_apis/instances_api.py b/lmcache/v1/mp_coordinator/http_apis/instances_api.py
new file mode 100644
index 0000000..7501cec
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/instances_api.py
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+"""REST resource for fleet membership: the ``/instances`` collection.
+
+mp servers register themselves, heartbeat, and deregister here; operators can
+list the fleet. Endpoints operate directly on the shared ``InstanceRegistry``
+reached via the :class:`CoordinatorContext` -- membership is thin enough to need
+no service layer.
+"""
+
+# Standard
+from typing import Any
+import time
+import uuid
+
+# Third Party
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_coordinator.http_apis.dependencies import get_context
+from lmcache.v1.mp_coordinator.registry import MPInstance
+from lmcache.v1.mp_coordinator.schemas import (
+    HeartbeatResponse,
+    RegisterRequest,
+    RegisterResponse,
+)
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+
+@router.post("/instances")
+async def register_instance(
+    body: RegisterRequest, request: Request
+) -> RegisterResponse:
+    """Register (or re-register) an mp server.
+
+    The body is validated by :class:`RegisterRequest`; FastAPI returns 422 on a
+    malformed body. An empty ``instance_id`` is replaced with a generated one,
+    returned in the response so the caller learns its assigned id.
+
+    Returns:
+        A :class:`RegisterResponse` carrying the (possibly generated) id.
+    """
+    instance_id = body.instance_id or f"mp-{uuid.uuid4().hex}"
+    # Wall-clock registration_time for display; monotonic last_heartbeat_time for
+    # NTP-safe stale detection (see registry.stale). register() does the
+    # exists-check and write under one lock, so the re_registered flag is correct
+    # even under concurrent registrations of the same id.
+    re_registered = get_context(request).registry.register(
+        MPInstance(
+            instance_id=instance_id,
+            ip=body.ip,
+            http_port=body.http_port,
+            registration_time=time.time(),
+            last_heartbeat_time=time.monotonic(),
+            metadata=dict(body.metadata),
+            p2p_advertised_url=body.p2p_advertised_url,
+            mq_port=body.mq_port,
+        )
+    )
+    logger.info("Registered instance %s at %s:%s", instance_id, body.ip, body.http_port)
+    return RegisterResponse(instance_id=instance_id, re_registered=re_registered)
+
+
+@router.put("/instances/{instance_id}/heartbeat")
+async def heartbeat(instance_id: str, request: Request) -> Any:
+    """Record a heartbeat for an instance.
+
+    Returns:
+        ``{"instance_id": str}`` with 200 if known, or a 404 JSON error if the
+        instance is unknown (the caller should re-register via ``POST
+        /instances``).
+    """
+    if get_context(request).registry.update_heartbeat(instance_id, time.monotonic()):
+        return HeartbeatResponse(instance_id=instance_id)
+    return JSONResponse(
+        status_code=404,
+        content={"error": f"unknown instance {instance_id}; re-register"},
+    )
+
+
+@router.delete("/instances/{instance_id}")
+async def deregister_instance(instance_id: str, request: Request) -> Response:
+    """Deregister an mp server.
+
+    Idempotent: returns 204 whether or not the instance was registered.
+
+    Returns:
+        An empty 204 response.
+    """
+    if get_context(request).registry.deregister(instance_id) is not None:
+        logger.info("Deregistered instance %s", instance_id)
+    else:
+        logger.info("Instance %s not registered, skipping deregistration", instance_id)
+    return Response(status_code=204)
+
+
+@router.get("/instances")
+async def list_instances(request: Request) -> Any:
+    """List all registered mp servers.
+
+    Returns:
+        ``{"instances": [ {instance_id, ip, http_port, ...}, ... ]}``.
+    """
+    instances = [
+        {
+            "instance_id": instance.instance_id,
+            "ip": instance.ip,
+            "http_port": instance.http_port,
+            "registration_time": instance.registration_time,
+            "metadata": instance.metadata,
+            "p2p_advertised_url": instance.p2p_advertised_url,
+            "mq_port": instance.mq_port,
+        }
+        for instance in get_context(request).registry.all_instances()
+    ]
+    return {"instances": instances}
diff --git a/lmcache/v1/mp_coordinator/http_apis/quota_api.py b/lmcache/v1/mp_coordinator/http_apis/quota_api.py
new file mode 100644
index 0000000..99470c9
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/http_apis/quota_api.py
@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Quota and usage-accounting endpoints on the coordinator (fleet-level).
+
+The ``/quota`` surface, thin over the collaborators on the typed
+:class:`CoordinatorContext` (resolved via :func:`get_context`): quota writes,
+combined quota+usage status reads, and usage-event ingestion from MP servers.
+This mirrors the MP server's node-local ``/quota`` group; warm-prefetch dispatch
+is genuine cache control and lives in :mod:`cache_api` instead.
+"""
+
+# Third Party
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+# First Party
+from lmcache.v1.distributed.tiers import Tier
+from lmcache.v1.mp_coordinator.http_apis.dependencies import get_context
+from lmcache.v1.mp_coordinator.schemas import (
+    EventType,
+    QuotaConfigRequest,
+    QuotaConfigResponse,
+    QuotaResponse,
+    ReportUsageRequest,
+    ReportUsageResponse,
+    SetQuotaRequest,
+    StatusListResponse,
+    StatusResponse,
+)
+
+router = APIRouter()
+
+_GB = 1024**3
+_DEFAULT_SALT_SENTINEL = "_default"
+# Quota / usage / status are L2-tier accounting today; other tiers are rejected.
+_SUPPORTED_TIER = Tier.L2
+
+
+def _resolve_salt_from_api_path(cache_salt: str) -> str:
+    """Map the ``_default`` sentinel to the empty string."""
+    return "" if cache_salt == _DEFAULT_SALT_SENTINEL else cache_salt
+
+
+def _require_supported_tier(tier: Tier) -> None:
+    """Raise ``HTTPException(400)`` unless ``tier`` is the supported one (``l2``)."""
+    if tier != _SUPPORTED_TIER:
+        raise HTTPException(
+            status_code=400,
+            detail=f"tier {tier.value!r} not supported; only {_SUPPORTED_TIER.value!r}",
+        )
+
+
+def _gb(n_bytes: int) -> float:
+    """Convert bytes to GiB."""
+    return n_bytes / _GB
+
+
+# -- Quota config  ---------------------------------------------
+
+
+@router.put("/quota/config")
+async def set_quota_config(
+    body: QuotaConfigRequest, request: Request
+) -> QuotaConfigResponse:
+    """Set the default quota applied to salts with no explicit entry.
+
+    Args:
+        body: The default limit to apply (and the ``tier`` it applies to).
+
+    Returns:
+        The applied config.
+    """
+    _require_supported_tier(body.tier)
+    default_limit_bytes = (
+        None if body.default_limit_gb is None else int(body.default_limit_gb * _GB)
+    )
+    get_context(request).quota_manager.set_default_limit_bytes(default_limit_bytes)
+    return QuotaConfigResponse(default_limit_gb=body.default_limit_gb)
+
+
+@router.get("/quota/config")
+async def get_quota_config(
+    request: Request, tier: Tier = Tier.L2
+) -> QuotaConfigResponse:
+    """Read the default quota applied to salts with no explicit entry.
+
+    Args:
+        tier: Cache tier (only ``l2`` is supported today).
+
+    Returns:
+        The current config; ``default_limit_gb`` is ``null`` while
+        unquota'd salts are exempt from eviction (the boot default).
+    """
+    _require_supported_tier(tier)
+    default_limit = get_context(request).quota_manager.get_default_limit_bytes()
+    return QuotaConfigResponse(
+        default_limit_gb=None if default_limit is None else _gb(default_limit)
+    )
+
+
+# -- Quota writes ------------------------------------------------------------
+
+
+@router.put("/quota/{cache_salt}", response_model=None)
+async def set_quota(
+    cache_salt: str, body: SetQuotaRequest, request: Request
+) -> QuotaResponse | JSONResponse:
+    """Create or update a quota.
+
+    Args:
+        cache_salt: Tenant identifier; use ``_default`` for the empty salt.
+        body: Quota limit to apply (and the ``tier`` it applies to).
+
+    Returns:
+        The applied quota, or a 400 JSON response if the limit is invalid.
+    """
+    _require_supported_tier(body.tier)
+    cache_salt = _resolve_salt_from_api_path(cache_salt)
+    limit_bytes = int(body.limit_gb * _GB)
+    try:
+        get_context(request).quota_manager.set_quota(cache_salt, limit_bytes)
+    except ValueError:
+        return JSONResponse(status_code=400, content={"error": "invalid quota limit"})
+    return QuotaResponse(cache_salt=cache_salt, limit_gb=body.limit_gb, status="ok")
+
+
+@router.delete("/quota/{cache_salt}")
+async def delete_quota(
+    cache_salt: str, request: Request, tier: Tier = Tier.L2
+) -> QuotaResponse:
+    """Remove a salt's quota entry.
+
+    Args:
+        cache_salt: Tenant identifier; use ``_default`` for the empty salt.
+        tier: Cache tier (only ``l2`` is supported today).
+
+    Returns:
+        ``QuotaResponse`` with ``status`` ``"removed"`` or ``"not_found"``.
+    """
+    _require_supported_tier(tier)
+    cache_salt = _resolve_salt_from_api_path(cache_salt)
+    removed = get_context(request).quota_manager.delete_quota(cache_salt)
+    return QuotaResponse(
+        cache_salt=cache_salt,
+        limit_gb=0.0,
+        status="removed" if removed else "not_found",
+    )
+
+
+# -- Combined status queries -------------------------------------------------
+
+
+@router.get("/quota/{cache_salt}")
+async def get_status(
+    cache_salt: str, request: Request, tier: Tier = Tier.L2
+) -> StatusResponse:
+    """Read quota and usage for a single salt.
+
+    Args:
+        cache_salt: Tenant identifier; use ``_default`` for the empty salt.
+        tier: Cache tier (only ``l2`` is supported today).
+
+    Returns:
+        Combined quota and live usage detail.
+    """
+    _require_supported_tier(tier)
+    cache_salt = _resolve_salt_from_api_path(cache_salt)
+    ctx = get_context(request)
+    usage = ctx.usage_manager.get(cache_salt)
+    exists = ctx.quota_manager.has_quota(cache_salt)
+    limit = ctx.quota_manager.get_limit_bytes(cache_salt)
+    return StatusResponse(
+        cache_salt=cache_salt,
+        quota_limit_gb=_gb(limit) if exists else 0.0,
+        quota_exists=exists,
+        usage_gb=_gb(usage),
+    )
+
+
+@router.get("/quota")
+async def list_status(request: Request, tier: Tier = Tier.L2) -> StatusListResponse:
+    """List quota and usage across all cache salts.
+
+    Args:
+        tier: Cache tier (only ``l2`` is supported today).
+
+    Returns:
+        Total usage plus per-salt breakdown with quota info.
+    """
+    _require_supported_tier(tier)
+    ctx = get_context(request)
+    tracker = ctx.usage_manager
+    store = ctx.quota_manager
+    by_salt = tracker.get_all()
+    total = tracker.get_total()
+    quota_entries = {e.cache_salt: e.limit_bytes for e in store.list_quotas()}
+    all_salts = sorted(set(by_salt) | set(quota_entries))
+    return StatusListResponse(
+        total_gb=_gb(total),
+        by_cache_salt=[
+            StatusResponse(
+                cache_salt=salt,
+                quota_limit_gb=_gb(quota_entries[salt])
+                if salt in quota_entries
+                else 0.0,
+                quota_exists=salt in quota_entries,
+                usage_gb=_gb(by_salt.get(salt, 0)),
+            )
+            for salt in all_salts
+        ],
+    )
+
+
+# -- Usage-event ingestion ---------------------------------------------------
+
+
+@router.post("/quota/events")
+async def report_events(
+    body: ReportUsageRequest, request: Request
+) -> ReportUsageResponse:
+    """Record a batch of ``store`` / ``lookup`` / ``delete`` events.
+
+    Usage events feed the same per-``cache_salt`` ledger the quota status reads
+    expose, so they live in the ``/quota`` group alongside the quota writes.
+
+    Args:
+        body: Event batch tagged with the reporter's ``instance_id``, ``seq``,
+            and the ``tier`` the events apply to.
+
+    Returns:
+        Number of events processed.
+    """
+    _require_supported_tier(body.tier)
+    ctx = get_context(request)
+    tracker = ctx.usage_manager
+    ctrl = ctx.eviction_manager
+    for event in body.events:
+        ok = event.key.to_object_key()
+        if event.type == EventType.STORE:
+            tracker.record_stored(ok, event.bytes)
+            ctrl.on_store(ok)
+        elif event.type == EventType.LOOKUP:
+            ctrl.on_lookup(ok)
+        elif event.type == EventType.DELETE:
+            tracker.record_evicted(ok)
+            ctrl.on_remove(ok)
+    return ReportUsageResponse(recorded=len(body.events))
diff --git a/lmcache/v1/mp_coordinator/registrar.py b/lmcache/v1/mp_coordinator/registrar.py
new file mode 100644
index 0000000..afe049c
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/registrar.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+"""mp-server-side coordinator registration helpers.
+
+These functions are the integration point an MP server uses to join the
+coordinator. They send plain HTTP requests with a caller-provided
+``httpx.AsyncClient`` (the MP server's generic client) and use the shared
+:mod:`schemas` models -- there is no dedicated client object, mirroring how the
+coordinator just calls mp endpoints directly.
+
+The MP server's FastAPI lifespan launches :func:`keep_registered` as a task and
+cancels it on shutdown. It is best-effort: registration/heartbeat failures are
+logged and retried, and it never takes the MP server down.
+"""
+
+# Standard
+import asyncio
+import contextlib
+
+# Third Party
+from pydantic import ValidationError
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_coordinator.schemas import RegisterRequest, RegisterResponse
+from lmcache.v1.rpc_utils import get_ip
+
+logger = init_logger(__name__)
+
+_DEFAULT_HEARTBEAT_INTERVAL = 5.0
+
+
+async def register(
+    client: httpx.AsyncClient,
+    base_url: str,
+    *,
+    http_port: int,
+    advertise_ip: str,
+    instance_id: str = "",
+    p2p_advertised_url: str = "",
+    mq_port: int = 0,
+) -> str:
+    """Register an MP server with the coordinator and return its id.
+
+    Args:
+        client: The HTTP client to send with.
+        base_url: Coordinator base URL (e.g. ``http://host:9300``).
+        http_port: This MP server's HTTP port to advertise.
+        advertise_ip: IP the coordinator should reach this server at.
+        instance_id: Desired id; empty lets the coordinator assign one.
+        p2p_advertised_url: Transfer-channel URL to advertise for P2P. Empty
+            when P2P is disabled.
+        mq_port: Port of this server's ZMQ message-queue server for P2P lookup
+            RPCs. 0 when P2P is disabled.
+
+    Returns:
+        The registered instance id (coordinator-assigned if ``instance_id`` was
+        empty).
+
+    Raises:
+        httpx.HTTPError: If the request fails or returns a non-2xx status.
+    """
+    body = RegisterRequest(
+        instance_id=instance_id,
+        ip=advertise_ip,
+        http_port=http_port,
+        p2p_advertised_url=p2p_advertised_url,
+        mq_port=mq_port,
+    )
+    response = await client.post(f"{base_url}/instances", json=body.model_dump())
+    response.raise_for_status()
+    return RegisterResponse.model_validate(response.json()).instance_id
+
+
+async def keep_registered(
+    client: httpx.AsyncClient,
+    coordinator_url: str,
+    *,
+    http_port: int,
+    instance_id: str = "",
+    advertise_ip: str = "",
+    heartbeat_interval: float = _DEFAULT_HEARTBEAT_INTERVAL,
+    p2p_advertised_url: str = "",
+    mq_port: int = 0,
+) -> None:
+    """Register, heartbeat on a timer, and deregister on cancellation.
+
+    Run as an asyncio task on the MP server's event loop and cancelled on
+    shutdown. Resilient: transient failures (network blips, 5xx, malformed or
+    version-skewed responses) are logged and retried on the next tick while the
+    current identity is kept, so a down coordinator never stops the MP server
+    and never spawns a duplicate registration. The identity is rebuilt only on
+    an explicit ``404`` (the coordinator forgot us) or after a failed initial
+    registration.
+
+    Args:
+        client: The HTTP client to send with.
+        coordinator_url: Coordinator base URL.
+        http_port: This MP server's HTTP port to advertise.
+        instance_id: Desired id; empty lets the coordinator assign one.
+        advertise_ip: IP the coordinator should reach this server at; defaults to
+            the machine's outbound IP.
+        heartbeat_interval: Seconds between heartbeats.
+        p2p_advertised_url: Transfer-channel URL to advertise for P2P. Empty
+            when P2P is disabled.
+        mq_port: Port of this server's ZMQ message-queue server for P2P lookup
+            RPCs. 0 when P2P is disabled.
+    """
+    base_url = coordinator_url.rstrip("/")
+    ip = advertise_ip or get_ip()
+    assigned_id: str | None = None
+    try:
+        while True:
+            try:
+                if assigned_id is None:
+                    assigned_id = await register(
+                        client,
+                        base_url,
+                        http_port=http_port,
+                        advertise_ip=ip,
+                        instance_id=instance_id,
+                        p2p_advertised_url=p2p_advertised_url,
+                        mq_port=mq_port,
+                    )
+                    logger.info("Registered with coordinator as %s", assigned_id)
+                else:
+                    response = await client.put(
+                        f"{base_url}/instances/{assigned_id}/heartbeat"
+                    )
+                    if response.status_code == 404:
+                        # Coordinator forgot us: drop id, re-register next tick.
+                        logger.info(
+                            "Coordinator no longer knows %s; re-registering",
+                            assigned_id,
+                        )
+                        assigned_id = None
+                    else:
+                        response.raise_for_status()
+            except (httpx.HTTPError, ValueError, ValidationError) as e:
+                # Transient: keep the current id so the next tick retries and
+                # shutdown can still deregister. ValueError/ValidationError cover
+                # bad JSON or schema skew; CancelledError still propagates.
+                logger.warning("Coordinator registration/heartbeat failed: %s", e)
+            await asyncio.sleep(heartbeat_interval)
+    finally:
+        if assigned_id is not None:
+            with contextlib.suppress(httpx.HTTPError, asyncio.CancelledError):
+                await client.delete(f"{base_url}/instances/{assigned_id}")
diff --git a/lmcache/v1/mp_coordinator/registry.py b/lmcache/v1/mp_coordinator/registry.py
new file mode 100644
index 0000000..6c88d37
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/registry.py
@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Thread-safe registry of live mp servers known to the coordinator.
+
+The registry is the single source of truth for fleet membership. It is mutated
+and read on the coordinator event loop (register / deregister / heartbeat /
+health-check eviction); access is lock-guarded to stay correct.
+
+The registry stores plain membership data only -- ip, http_port, heartbeat
+timestamps, metadata. How to reach an instance for push is derived from its
+``ip`` + ``http_port`` by whichever router needs to call it.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+import random
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class MPInstance:
+    """A single registered mp server.
+
+    Attributes:
+        instance_id: Globally unique identifier of the mp server.
+        ip: IP address the mp server's HTTP server is reachable at.
+        http_port: Port of the mp server's HTTP server, which the coordinator
+            calls to push work to this instance.
+        registration_time: Wall-clock time the instance registered (for display).
+        last_heartbeat_time: Monotonic-clock time of the most recent heartbeat,
+            used for stale detection so an NTP step cannot skew liveness.
+        metadata: Free-form string key/value pairs supplied at registration.
+        p2p_advertised_url: URL this instance advertises for peer-to-peer
+            transfers. Empty when the instance does not participate in P2P.
+        mq_port: Port of the instance's ZMQ message-queue server that P2P peers
+            send lookup/unlock RPCs to, reachable at this instance's ``ip``. 0
+            when P2P is disabled.
+    """
+
+    instance_id: str
+    ip: str
+    http_port: int
+    registration_time: float
+    last_heartbeat_time: float
+    metadata: dict[str, str] = field(default_factory=dict)
+    p2p_advertised_url: str = ""
+    mq_port: int = 0
+
+
+class InstanceRegistry:
+    """Thread-safe in-memory registry of mp servers.
+
+    All public methods acquire an internal lock, so the registry stays
+    consistent under concurrent access.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry."""
+        self._lock = threading.Lock()
+        self._instances: dict[str, MPInstance] = {}
+
+    def register(self, instance: MPInstance) -> bool:
+        """Insert or replace an mp server entry atomically.
+
+        Args:
+            instance: The instance to store. If one with the same
+                ``instance_id`` already exists it is overwritten.
+
+        Returns:
+            ``True`` if an instance with the same id already existed (i.e. this
+            was a re-registration), else ``False``. The check and the write
+            happen under one lock, so concurrent registrations of the same id
+            cannot both report ``False``.
+        """
+        with self._lock:
+            existed = instance.instance_id in self._instances
+            self._instances[instance.instance_id] = instance
+            return existed
+
+    def deregister(self, instance_id: str) -> MPInstance | None:
+        """Remove an mp server entry and return it.
+
+        Args:
+            instance_id: Identifier of the instance to remove.
+
+        Returns:
+            The removed instance, or ``None`` if no such instance was
+            registered.
+        """
+        with self._lock:
+            return self._instances.pop(instance_id, None)
+
+    def get(self, instance_id: str) -> MPInstance | None:
+        """Return the instance with the given id, or ``None`` if unknown.
+
+        Args:
+            instance_id: Identifier to look up.
+
+        Returns:
+            The matching instance, or ``None``.
+        """
+        with self._lock:
+            return self._instances.get(instance_id)
+
+    def contains(self, instance_id: str) -> bool:
+        """Report whether an instance is currently registered.
+
+        Args:
+            instance_id: Identifier to check.
+
+        Returns:
+            ``True`` if registered, otherwise ``False``.
+        """
+        with self._lock:
+            return instance_id in self._instances
+
+    def all_instances(self) -> list[MPInstance]:
+        """Return a snapshot list of all registered instances.
+
+        Returns:
+            A new list containing every currently registered instance.
+        """
+        with self._lock:
+            return list(self._instances.values())
+
+    def random_instance(self) -> "MPInstance | None":
+        """Return a uniformly random registered instance, or ``None``
+        when the registry is empty."""
+        with self._lock:
+            instances = list(self._instances.values())
+        if not instances:
+            return None
+        return random.choice(instances)
+
+    def update_heartbeat(self, instance_id: str, timestamp: float) -> bool:
+        """Record a heartbeat timestamp for an instance.
+
+        Args:
+            instance_id: Identifier of the instance.
+            timestamp: Monotonic-clock time of the heartbeat (see
+                :meth:`stale`); must come from the same clock as ``stale``.
+
+        Returns:
+            ``True`` if the instance was found and updated, ``False`` if it is
+            not registered (the caller should treat this as a re-register).
+        """
+        with self._lock:
+            instance = self._instances.get(instance_id)
+            if instance is None:
+                return False
+            instance.last_heartbeat_time = timestamp
+            return True
+
+    def stale(self, timeout: float) -> list[str]:
+        """Return the ids of instances whose heartbeat has expired.
+
+        Args:
+            timeout: Maximum allowed seconds since the last heartbeat.
+
+        Returns:
+            A list of instance ids that have not sent a heartbeat within
+            ``timeout`` seconds.
+        """
+        now = time.monotonic()
+        with self._lock:
+            return [
+                instance_id
+                for instance_id, instance in self._instances.items()
+                if now - instance.last_heartbeat_time > timeout
+            ]
diff --git a/lmcache/v1/mp_coordinator/schemas.py b/lmcache/v1/mp_coordinator/schemas.py
new file mode 100644
index 0000000..9d225f0
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/schemas.py
@@ -0,0 +1,447 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared request/response schemas for the mp coordinator REST API.
+
+These Pydantic models are the wire contract between the coordinator and mp
+servers. The coordinator uses them to validate requests and shape responses; an
+mp server (when it registers) imports the same models to build its request
+bodies and parse replies, so both sides agree on the schema in one place.
+"""
+
+# Standard
+from enum import Enum
+from typing import Annotated
+import base64
+
+# Third Party
+from pydantic import BaseModel, Field, StringConstraints, field_validator
+import numpy as np
+
+# First Party
+from lmcache.v1.distributed.api import EncodedObjectKey  # noqa: F401  re-exported
+from lmcache.v1.distributed.tiers import Tier
+
+
+def encode_tokens(tokens: "list[int] | np.ndarray") -> str:
+    """Encode token ids into a compact base64 wire string.
+
+    Token ids fit in ``uint32``, so a little-endian ``uint32`` buffer is far
+    smaller than a JSON integer list and decodes in one ``np.frombuffer`` call.
+
+    Args:
+        tokens: Token ids (a ``list[int]`` or any array castable to ``uint32``).
+
+    Returns:
+        Base64 of the little-endian ``uint32`` token buffer.
+    """
+    arr = np.ascontiguousarray(np.asarray(tokens, dtype="<u4"))
+    return base64.b64encode(arr.tobytes()).decode("ascii")
+
+
+def decode_tokens(tokens_b64: str) -> np.ndarray:
+    """Decode a base64 token string produced by :func:`encode_tokens`.
+
+    Args:
+        tokens_b64: Base64 of a little-endian ``uint32`` token buffer.
+
+    Returns:
+        A ``uint64`` array of token ids (widened so it feeds the hashers
+        directly).
+
+    Raises:
+        ValueError: If ``tokens_b64`` is not valid base64 or not a multiple of
+            4 bytes.
+    """
+    try:
+        raw = base64.b64decode(tokens_b64, validate=True)
+    except Exception as exc:
+        raise ValueError(f"tokens_b64 is not valid base64: {exc}") from exc
+    if len(raw) % 4 != 0:
+        raise ValueError(
+            f"tokens_b64 byte length {len(raw)} is not a multiple of 4 "
+            "(malformed uint32 token buffer)"
+        )
+    return np.frombuffer(raw, dtype="<u4").astype(np.uint64)
+
+
+class RegisterRequest(BaseModel):
+    """Body of a ``POST /instances`` registration request.
+
+    Attributes:
+        instance_id: Identifier of the mp server. Optional -- if empty (or
+            whitespace-only), the coordinator generates one and returns it.
+        ip: IP/host of the mp server's HTTP server. Whitespace is stripped and a
+            blank value is rejected, since the coordinator calls this address.
+        http_port: Port of the mp server's HTTP server, which the coordinator
+            calls to push work to this instance.
+        metadata: Free-form registration hints.
+        p2p_advertised_url: URL the instance advertises for peer-to-peer
+            transfers. Optional -- empty when the instance does not participate
+            in P2P.
+        mq_port: Port of the instance's ZMQ message-queue server that P2P peers
+            send lookup/unlock RPCs to, reachable at the instance's ``ip``.
+            Optional -- 0 when P2P is disabled.
+    """
+
+    instance_id: Annotated[str, StringConstraints(strip_whitespace=True)] = ""
+    ip: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)]
+    http_port: int = Field(ge=1, le=65535)
+    metadata: dict[str, str] = Field(default_factory=dict)
+    p2p_advertised_url: Annotated[str, StringConstraints(strip_whitespace=True)] = ""
+    mq_port: int = Field(default=0, ge=0, le=65535)
+
+
+class RegisterResponse(BaseModel):
+    """Reply to a successful ``POST /instances``.
+
+    Attributes:
+        instance_id: The registered instance's id.
+        re_registered: ``True`` if this replaced an existing registration.
+    """
+
+    instance_id: str
+    re_registered: bool
+
+
+class HeartbeatResponse(BaseModel):
+    """Reply to a successful ``PUT /instances/{id}/heartbeat``.
+
+    Attributes:
+        instance_id: The instance whose heartbeat was recorded.
+    """
+
+    instance_id: str
+
+
+# -- Quota management --------------------------------------------------------
+
+
+class SetQuotaRequest(BaseModel):
+    """Body of ``PUT /quota/{cache_salt}``.
+
+    Attributes:
+        limit_gb: Non-negative byte budget in GiB.
+        tier: Cache tier the quota applies to (only ``l2`` is supported today).
+    """
+
+    limit_gb: float = Field(ge=0.0)
+    tier: Tier = Tier.L2
+
+
+class QuotaResponse(BaseModel):
+    """Reply to ``PUT`` or ``DELETE /quota/{cache_salt}``.
+
+    Attributes:
+        cache_salt: The tenant identifier (``_default`` for empty salt).
+        limit_gb: The current limit in GiB (0.0 after deletion).
+        status: ``"ok"`` or ``"removed"`` or ``"not_found"``.
+    """
+
+    cache_salt: str
+    limit_gb: float
+    status: str
+
+
+class QuotaConfigRequest(BaseModel):
+    """Body of ``PUT /quota/config``.
+
+    Attributes:
+        default_limit_gb: Byte budget in GiB applied to salts with no
+            explicit quota entry. ``None`` (default) leaves unquota'd
+            salts exempt from eviction.
+        tier: Cache tier the config applies to (only ``l2`` today).
+    """
+
+    default_limit_gb: float | None = Field(default=None, ge=0.0)
+    tier: Tier = Tier.L2
+
+
+class QuotaConfigResponse(BaseModel):
+    """Reply to ``GET`` / ``PUT /quota/config``.
+
+    Attributes:
+        default_limit_gb: Current default limit in GiB, or ``None``
+            when unquota'd salts are exempt from eviction.
+    """
+
+    default_limit_gb: float | None
+
+
+# -- Usage tracking ----------------------------------------------------------
+
+
+class EventType(str, Enum):
+    """Cache events reported by an MP server."""
+
+    STORE = "store"
+    LOOKUP = "lookup"
+    DELETE = "delete"
+
+
+class UsageEvent(BaseModel):
+    """A single cache event reported by an MP server.
+
+    Attributes:
+        type: The event type.
+        key: The cache key this event applies to.
+        bytes: Bytes stored (``store`` only; ``0`` for other types).
+    """
+
+    type: EventType
+    key: EncodedObjectKey
+    bytes: int = Field(ge=0)
+
+
+class ReportUsageRequest(BaseModel):
+    """Body of ``POST /quota/events``.
+
+    Attributes:
+        instance_id: Identifier of the MP server that produced this batch.
+        seq: Monotonically increasing sequence number scoped to this
+            ``instance_id``. Starts at 1 for the first flush after the
+            server starts.
+        events: Batch of store/lookup events to record.
+        tier: Cache tier the events apply to (only ``l2`` is supported today).
+    """
+
+    instance_id: str
+    seq: int = Field(ge=1)
+    events: list[UsageEvent]
+    tier: Tier = Tier.L2
+
+
+class ReportUsageResponse(BaseModel):
+    """Reply to ``POST /quota/events``.
+
+    Attributes:
+        recorded: Number of events processed.
+    """
+
+    recorded: int
+
+
+class StatusResponse(BaseModel):
+    """Combined quota and usage for a single ``cache_salt``.
+
+    Attributes:
+        cache_salt: The tenant identifier.
+        quota_limit_gb: The byte budget in GiB (0.0 if no quota set).
+        quota_exists: Whether an explicit quota is registered.
+        usage_gb: Current usage in GiB.
+    """
+
+    cache_salt: str
+    quota_limit_gb: float
+    quota_exists: bool
+    usage_gb: float
+
+
+class StatusListResponse(BaseModel):
+    """Reply to ``GET /quota``.
+
+    Attributes:
+        total_gb: Aggregate usage in GiB.
+        by_cache_salt: Per-tenant breakdown with quota and usage.
+    """
+
+    total_gb: float
+    by_cache_salt: list[StatusResponse]
+
+
+# -- Global CacheBlend fingerprint directory ------------------------------
+
+
+class StoreRangeModel(BaseModel):
+    """Wire form of one published stored token range (see ``StoreRange``).
+
+    The coordinator chunks ``tokens`` at its chunk size and hashes each chunk;
+    chunk ``i`` maps to ``object_keys[i]`` at ``old_st_base + i * chunk_size``.
+
+    Attributes:
+        model_scope: Reuse scope (the model name).
+        tokens: The stored tokens (``token_ids[start:end]``).
+        object_keys: Shared-L2 storage key (hex) per chunk, in order.
+        old_st_base: Token position of the range's first token.
+    """
+
+    model_scope: str
+    tokens: list[int] = Field(default_factory=list)
+    object_keys: list[str] = Field(default_factory=list)
+    old_st_base: int = Field(ge=0)
+
+
+class BlendFingerprintRequest(BaseModel):
+    """Body of ``POST /blend/fingerprints``: register stored ranges.
+
+    Attributes:
+        ranges: Stored token ranges to register (idempotent).
+    """
+
+    ranges: list[StoreRangeModel] = Field(default_factory=list)
+
+
+class BlendFingerprintResponse(BaseModel):
+    """Reply to ``POST /blend/fingerprints``.
+
+    Attributes:
+        inserted: Number of fingerprints newly registered.
+    """
+
+    inserted: int
+
+
+class BlendEvictRequest(BaseModel):
+    """Body of ``DELETE /blend/fingerprints``: evict by storage key.
+
+    Attributes:
+        object_keys: ``object_key`` values to evict.
+    """
+
+    object_keys: list[str] = Field(default_factory=list)
+
+
+class BlendEvictResponse(BaseModel):
+    """Reply to ``DELETE /blend/fingerprints``.
+
+    Attributes:
+        removed: Number of fingerprint entries evicted.
+    """
+
+    removed: int
+
+
+class BlendMatchRequest(BaseModel):
+    """Body of ``POST /blend/match``.
+
+    Attributes:
+        model_scope: Scope to match within.
+        tokens_b64: The request tokens, packed via :func:`encode_tokens`
+            (base64 little-endian ``uint32``).
+    """
+
+    model_scope: str
+    tokens_b64: str = ""
+
+    @field_validator("tokens_b64")
+    @classmethod
+    def _validate_tokens_b64(cls, value: str) -> str:
+        """Reject a malformed token buffer at request validation.
+
+        Without this, ``decode_tokens`` would raise ``ValueError`` inside the
+        route handler, which FastAPI surfaces as a 500 (server error) for what
+        is really bad client input. Validating here returns a 422 instead.
+
+        Args:
+            value: The base64 ``tokens_b64`` field.
+
+        Returns:
+            The unchanged value once it is confirmed decodable.
+
+        Raises:
+            ValueError: If ``value`` is not valid base64 or not a whole number
+                of ``uint32`` tokens (surfaced by FastAPI as 422).
+        """
+        decode_tokens(value)
+        return value
+
+
+class GlobalMatchModel(BaseModel):
+    """Wire form of one matched chunk (see ``GlobalMatch``).
+
+    Attributes:
+        object_key: Shared-L2 storage key of the matched chunk.
+        old_st: Token position in the stored sequence (re-RoPE source).
+        cur_st: Token position in the request (re-RoPE target).
+    """
+
+    object_key: str
+    old_st: int
+    cur_st: int
+
+
+class BlendMatchResponse(BaseModel):
+    """Reply to ``POST /blend/match``.
+
+    Attributes:
+        matches: Matched chunks, ascending by ``cur_st``.
+    """
+
+    matches: list[GlobalMatchModel]
+
+
+class PrefetchRequest(BaseModel):
+    """Body of ``POST /cache/prefetches`` on the coordinator.
+
+    Asks the coordinator to warm one MP server's L1 with the chunks of a token
+    sequence. The caller describes content by ``token_ids`` -- the unit the
+    cache speaks -- not by internal cache keys, which it cannot construct. The
+    coordinator forwards the request verbatim to that server's own
+    ``POST /cache/prefetches``, which hashes the tokens and expands them into the
+    per-rank keys.
+
+    Attributes:
+        instance_id: Identifier of the target MP server (must be registered).
+        model_name: Model whose layout the target uses to allocate L1 buffers.
+        world_size: World size selecting the layout and the per-rank fan-out.
+        token_ids: Prompt tokens whose complete chunks should be warmed.
+        cache_salt: Per-tenant isolation salt applied to the produced keys.
+    """
+
+    instance_id: str
+    model_name: str
+    world_size: int = Field(ge=1)
+    token_ids: list[int] = Field(default_factory=list)
+    cache_salt: str = ""
+
+
+class PrefetchResponse(BaseModel):
+    """Reply to ``POST /cache/prefetches`` on the coordinator.
+
+    Attributes:
+        instance_id: The target MP server the prefetch was submitted to.
+        request_id: The server's job id to poll via
+            ``GET /cache/prefetches/{instance_id}/{request_id}``. Empty when
+            ``status`` is ``"noop"`` (nothing to warm).
+        chunks: Number of whole chunks submitted to warm.
+        status: ``"submitted"`` (a job is in flight) or ``"noop"`` (the
+            sequence was shorter than one chunk).
+    """
+
+    instance_id: str
+    request_id: str = ""
+    chunks: int = 0
+    status: str
+
+
+class PinRequest(BaseModel):
+    """Body of ``POST`` / ``DELETE /cache/pins`` on the coordinator.
+
+    Pinning protects the resolved keys from L2 eviction until unpinned. The
+    coordinator resolves ``token_ids`` to keys locally; L2 pins are fleet-wide
+    (per ``cache_salt``), so no target instance is needed.
+
+    Attributes:
+        model_name: Model whose rank fan-out to use when resolving keys.
+        world_size: World size selecting the per-rank fan-out.
+        token_ids: Prompt tokens whose complete chunks should be (un)pinned.
+        cache_salt: Per-tenant isolation salt applied to the produced keys.
+    """
+
+    model_name: str
+    world_size: int = Field(ge=1)
+    token_ids: list[int] = Field(default_factory=list)
+    cache_salt: str = ""
+
+
+class PinResponse(BaseModel):
+    """Reply to ``POST`` / ``DELETE /cache/pins`` on the coordinator.
+
+    Attributes:
+        requested: Number of whole chunks the token sequence resolved to.
+        affected: Number of L2 keys pinned (on pin) or unpinned (on unpin);
+            disambiguated by ``status``.
+        status: ``"pinned"`` / ``"unpinned"``.
+    """
+
+    requested: int = 0
+    affected: int = 0
+    status: str
diff --git a/lmcache/v1/mp_coordinator/utils/__init__.py b/lmcache/v1/mp_coordinator/utils/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/utils/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/mp_coordinator/utils/cache_utils.py b/lmcache/v1/mp_coordinator/utils/cache_utils.py
new file mode 100644
index 0000000..f3b069f
--- /dev/null
+++ b/lmcache/v1/mp_coordinator/utils/cache_utils.py
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Coordinator-side cache helpers.
+
+Resolve a token sequence to object keys without a round-trip to an MP server.
+Pin requests describe content by ``token_ids``; the coordinator hashes them and
+expands each complete chunk into its object keys (the same fan-out the lookup
+path uses), so it can pin/unpin those keys in its L2 eviction plan. The token
+hasher must be configured to match the fleet's ``chunk_size`` /
+``hash_algorithm`` (see :class:`MPCoordinatorConfig`), or the resolved keys will
+not match what the servers stored. Keys are resolved in a single object group,
+so the MP servers must run with ``--no-separate-object-groups``.
+"""
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey, ipc_key_to_object_keys
+from lmcache.v1.multiprocess.cache_control.key_resolver import MAX_TOKEN_IDS
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+
+
+def resolve_object_keys(
+    token_hasher: TokenHasher,
+    model_name: str,
+    world_size: int,
+    token_ids: list[int],
+    cache_salt: str,
+) -> tuple[list[ObjectKey], int]:
+    """Resolve a token sequence to the object keys of its complete chunks.
+
+    Args:
+        token_hasher: Hasher configured to match the fleet's chunk size and
+            hash algorithm.
+        model_name: Model whose rank fan-out to use.
+        world_size: Tensor-parallel world size selecting the per-rank fan-out.
+        token_ids: The token sequence to resolve.
+        cache_salt: Per-tenant isolation salt.
+
+    Returns:
+        ``(obj_keys, chunk_count)``. ``obj_keys`` holds one key per (chunk, rank)
+        and is empty (with ``chunk_count`` 0) when the sequence is shorter than
+        one chunk.
+
+    Raises:
+        ValueError: ``token_ids`` exceeds the per-request cap, or a key field
+            (e.g. ``cache_salt``) is invalid.
+    """
+    if len(token_ids) > MAX_TOKEN_IDS:
+        raise ValueError(
+            f"too many token_ids in a single request "
+            f"(limit={MAX_TOKEN_IDS}, got={len(token_ids)})"
+        )
+    ipc_key = IPCCacheServerKey(
+        model_name=model_name,
+        world_size=world_size,
+        worker_id=None,
+        token_ids=tuple(token_ids),
+        start=0,
+        end=len(token_ids),
+        request_id="",
+        cache_salt=cache_salt,
+    )
+    chunk_hashes = token_hasher.compute_chunk_hashes(list(token_ids))
+    if not chunk_hashes:
+        return [], 0
+    obj_keys = ipc_key_to_object_keys(ipc_key, chunk_hashes, [0])[0]
+    return obj_keys, len(chunk_hashes)
diff --git a/lmcache/v1/mp_observability/AGENTS.override.md b/lmcache/v1/mp_observability/AGENTS.override.md
new file mode 100644
index 0000000..bdc5a8f
--- /dev/null
+++ b/lmcache/v1/mp_observability/AGENTS.override.md
@@ -0,0 +1,21 @@
+# MP Observability — Agent Instructions
+
+When working in `lmcache/v1/mp_observability/`:
+
+Design docs live in `docs/design/v1/mp_observability/` — update them whenever
+the contracts below change.
+
+1. **New `EventType`** — after adding an entry to `event.py`, update the
+   metadata contract table in `docs/design/v1/mp_observability/EVENTS.md`
+   with the new type's metadata keys and types.
+
+2. **New metrics subscriber** — after adding counters/histograms, update the
+   metrics table in `docs/design/v1/mp_observability/METRICS.md` with the
+   metric name, type, and description.
+
+3. **New subscriber class** — follow the step-by-step guide in `README.md`
+   (co-located with this file; "How to Add a New Event and Subscriber") and
+   the design rules in `docs/design/v1/mp_observability/event-bus.md`.
+
+4. **CLI args** — if you add or change observability CLI flags in `config.py`,
+   update `docs/source/mp/observability.rst` to match.
diff --git a/lmcache/v1/mp_observability/README.md b/lmcache/v1/mp_observability/README.md
new file mode 100644
index 0000000..81d27e0
--- /dev/null
+++ b/lmcache/v1/mp_observability/README.md
@@ -0,0 +1,208 @@
+# MP Observability
+
+Event-driven observability for LMCache's multiprocess (MP) mode, built on
+[OpenTelemetry](https://opentelemetry.io/).
+
+For metrics, see [METRICS.md](../../../docs/design/v1/mp_observability/METRICS.md).
+For event metadata contracts, see
+[EVENTS.md](../../../docs/design/v1/mp_observability/EVENTS.md).
+For design rationale, see
+[event-bus.md](../../../docs/design/v1/mp_observability/event-bus.md).
+For the trace recording subsystem (`lmcache trace`), see
+[trace.md](../../../docs/design/v1/mp_observability/trace.md).
+
+---
+
+## Architecture
+
+```
+Producers (L1Manager, StorageManager, MPCacheServer)
+    │
+    │  event_bus.publish(Event(...))
+    ▼
+EventBus  (async queue + drain thread)
+    │
+    ├──► L1MetricsSubscriber          → OTel counter.add(...)
+    ├──► SMMetricsSubscriber          → OTel counter.add(...)
+    ├──► EventBusSelfMetricsSubscriber → OTel observable gauges/counters
+    │                                    (bus health: queue depth, drain
+    │                                    lag, drops, subscriber exceptions)
+    ├──► L1LoggingSubscriber          → logger.debug(...)
+    ├──► SMLoggingSubscriber          → logger.debug(...)
+    ├──► MPServerLoggingSubscriber    → logger.debug(...)
+    └──► MPServerTracingSubscriber    → OTel span start/end
+
+OTel SDK  (configured at startup)
+    │
+    ├──► OTLP push (production)       → OTel collector → Prometheus / Grafana / etc.
+    └──► Prometheus pull (dev/debug)   → /metrics on configured port
+```
+
+---
+
+## Configuration
+
+All observability behaviour is controlled by `ObservabilityConfig`
+(defined in `config.py`).  When running the LMCache MP mode server from the
+CLI, pass the flags below; when embedding programmatically, construct an
+`ObservabilityConfig` directly.
+
+### CLI flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--disable-observability` | off | Disable the EventBus entirely. No events are published or consumed. |
+| `--disable-metrics` | off | Skip registering metrics subscribers (OTel counters). |
+| `--disable-logging` | off | Skip registering logging subscribers. |
+| `--enable-tracing` | off | Register tracing subscribers (OTel spans). Disabled by default. **Requires `--otlp-endpoint`.** |
+| `--event-bus-queue-size N` | `10000` | Maximum number of events in the EventBus queue before tail-drop. |
+| `--otlp-endpoint URL` | *(none)* | OTLP gRPC endpoint (e.g. `http://localhost:4317`). When set, metrics and traces are pushed to an OTel collector. When unset, metrics fall back to Prometheus pull mode. |
+| `--prometheus-port PORT` | `9090` | Port for the Prometheus `/metrics` endpoint. Only used when `--otlp-endpoint` is not set. |
+
+### `ObservabilityConfig` fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `bool` | `True` | Master switch for the EventBus. |
+| `max_queue_size` | `int` | `10000` | Maximum events in the EventBus queue before tail-drop. |
+| `metrics_enabled` | `bool` | `True` | Register metrics subscribers (OTel counters / histograms). |
+| `logging_enabled` | `bool` | `True` | Register logging subscribers. |
+| `tracing_enabled` | `bool` | `False` | Register tracing subscribers (OTel spans). |
+| `otlp_endpoint` | `str \| None` | `None` | OTLP gRPC endpoint. When set, metrics and traces are pushed. When `None`, metrics use Prometheus pull fallback. |
+| `prometheus_port` | `int` | `9090` | Port for the Prometheus `/metrics` endpoint (pull fallback only). |
+| `service_instance_id` | `str \| None` | `None` | OTel Resource attribute `service.instance.id`, attached to every metric and span. No CLI flag: `run_cache_server` projects the MP server's `--instance-id` onto it. `None` (standalone callers only) falls back to a random UUID v4 at `init_observability` time; an explicit value is preserved. |
+
+### Metrics export modes
+
+| `otlp_endpoint` | Mode | How to query |
+|---|---|---|
+| `http://host:4317` | OTLP push | Query the OTel collector's Prometheus exporter |
+| `None` | Prometheus pull fallback | `curl http://localhost:<prometheus-port>/metrics` |
+
+> **Note:** OTel counters only appear on `/metrics` after the first increment.
+> If you see only Python runtime metrics, trigger a store/retrieve first.
+
+### Tracing
+
+Tracing is opt-in (`--enable-tracing`).  When enabled, `MPServerTracingSubscriber`
+creates OTel spans from MP server START/END event pairs (store, retrieve,
+lookup/prefetch).  Trace export requires an OTLP endpoint — there is no local
+fallback.  `--enable-tracing` **requires** `--otlp-endpoint`; the server will
+raise a `ValueError` at startup if the endpoint is missing.
+
+---
+
+## How to Add a New Event and Subscriber
+
+### Step 1 — Define the event type
+
+Add a new member to `EventType` in `event.py`:
+
+```python
+class EventType(Enum):
+    # ... existing events ...
+
+    # My new component events
+    MY_COMPONENT_OPERATION = "my_component.operation"
+```
+
+### Step 2 — Publish the event from the producer
+
+In your component (e.g., a manager class), publish to the EventBus:
+
+```python
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+
+class MyComponent:
+    def __init__(self):
+        self._event_bus = get_event_bus()
+
+    def do_operation(self, keys):
+        # ... business logic ...
+
+        self._event_bus.publish(Event(
+            event_type=EventType.MY_COMPONENT_OPERATION,
+            metadata={"keys": keys},
+        ))
+```
+
+### Step 3 — Create a subscriber
+
+Create a file under the appropriate `subscribers/` subdirectory:
+
+- `subscribers/metrics/` for OTel counters / histograms
+- `subscribers/logging/` for debug log output
+- `subscribers/tracing/` for OTel spans
+
+Example metrics subscriber (`subscribers/metrics/my_component.py`):
+
+```python
+from opentelemetry import metrics
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class MyComponentMetricsSubscriber(EventSubscriber):
+    def __init__(self):
+        meter = metrics.get_meter("lmcache.my_component")
+        self._op_counter = meter.create_counter(
+            "lmcache_mp.my_component_operations",
+            description="Total operations on my component",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MY_COMPONENT_OPERATION: self._on_operation,
+        }
+
+    def _on_operation(self, event: Event) -> None:
+        self._op_counter.add(len(event.metadata["keys"]))
+```
+
+### Step 4 — Export from `__init__.py`
+
+Add the subscriber to the corresponding `__init__.py` so it can be
+imported from the package:
+
+```python
+# subscribers/metrics/__init__.py
+from lmcache.v1.mp_observability.subscribers.metrics.my_component import (
+    MyComponentMetricsSubscriber,
+)
+```
+
+### Step 5 — Register the subscriber at startup
+
+In the server startup function (e.g., `run_cache_server()` in `server.py`),
+register conditionally based on `ObservabilityConfig`:
+
+```python
+if obs_config.metrics_enabled:
+    from lmcache.v1.mp_observability.subscribers.metrics import (
+        MyComponentMetricsSubscriber,
+    )
+    bus.register_subscriber(MyComponentMetricsSubscriber())
+```
+
+### Step 6 — Document the metadata contract
+
+Add a row to the metadata contracts table in
+[EVENTS.md](../../../docs/design/v1/mp_observability/EVENTS.md) so
+subscribers can rely on the schema:
+
+```markdown
+| `MY_COMPONENT_OPERATION` | `keys` | `list[ObjectKey]` |
+```
+
+---
+
+## Design rules
+
+| Rule | Reason |
+|---|---|
+| Create meters and counters in `__init__()`, not at module level | `MeterProvider` must be set before `get_meter()` is called. Module-level calls happen at import time, before setup. |
+| Prefix OTel metric names with `lmcache_mp.` | Keeps the MP namespace separate from `lmcache.` (the single-process engine namespace). |
+| Use `metadata: dict[str, Any]` for event payloads | Flexible, no coupling between producers and subscribers. See metadata contracts in [EVENTS.md](../../../docs/design/v1/mp_observability/EVENTS.md). |
+| Separate metrics, logging, and tracing subscribers | Single responsibility. Can enable/disable independently via config. |
+| Store `self._event_bus = get_event_bus()` in `__init__` | Avoids calling the singleton getter on every publish. |
diff --git a/lmcache/v1/mp_observability/config.py b/lmcache/v1/mp_observability/config.py
new file mode 100644
index 0000000..017796e
--- /dev/null
+++ b/lmcache/v1/mp_observability/config.py
@@ -0,0 +1,404 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Configuration for the MP-mode observability stack.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+import argparse
+import uuid
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.mp_observability.event_bus import EventBus
+
+# First Party
+from lmcache.v1.mp_observability.subscribers.logging.lookup_hash import (
+    LookupHashLogConfig,
+)
+
+
+@dataclass
+class ObservabilityConfig:
+    """Unified configuration for the EventBus-based observability system.
+
+    Controls the EventBus, OTel metrics/tracing pipelines, and subscriber
+    registration.
+    """
+
+    enabled: bool = True
+    """Master switch for the EventBus."""
+
+    max_queue_size: int = 10_000
+    """Maximum events in the EventBus queue before tail-drop."""
+
+    metrics_enabled: bool = True
+    """Register metrics subscribers (OTel counters / histograms)."""
+
+    logging_enabled: bool = True
+    """Register logging subscribers."""
+
+    tracing_enabled: bool = False
+    """Register span subscribers (OTel traces)."""
+
+    otlp_endpoint: str | None = None
+    """OTLP gRPC endpoint (e.g. ``http://localhost:4317``).  When set,
+    metrics and traces are pushed to an OTel collector.  When ``None``,
+    metrics fall back to an in-process Prometheus ``/metrics`` endpoint."""
+
+    prometheus_port: int = 9090
+    """Port for the Prometheus /metrics endpoint.  Only used when
+    ``otlp_endpoint`` is ``None`` (Prometheus pull fallback)."""
+
+    metrics_sample_rate: float = 0.01
+    """Fraction of chunks/blocks to track for lifecycle histograms (0, 1.0].
+    Counters always count all events regardless of this setting."""
+
+    lookup_hash_log: LookupHashLogConfig = field(default_factory=LookupHashLogConfig)
+    """Configuration for lookup hash file logging.  Disabled by default
+    (empty ``output_dir``)."""
+
+    trace_level: str | None = None
+    """If set, enables trace recording at the given level.  Currently
+    only ``"storage"`` is supported.  See
+    :mod:`lmcache.v1.mp_observability.trace` for details."""
+
+    trace_output: str | None = None
+    """Path to write the trace file.  When :attr:`trace_level` is set
+    but this is ``None``, a timestamped path under ``$TMPDIR`` is
+    minted and logged at INFO."""
+
+    service_instance_id: str | None = None
+    """OTel ``service.instance.id`` resource attribute, attached to every
+    metric and span. There is no CLI flag for it: the operator-facing id is
+    ``--instance-id`` (``MPServerConfig.instance_id``), which ``run_cache_server``
+    projects onto this attribute so telemetry and coordinator membership share
+    one id.
+
+    ``None`` (the default) means "not set": standalone callers that build an
+    ``ObservabilityConfig`` directly (e.g. the trace CLI driver) fall back to a
+    random UUID v4 at ``init_observability`` time. An explicit value is
+    preserved verbatim."""
+
+
+DEFAULT_OBSERVABILITY_CONFIG = ObservabilityConfig(enabled=False)
+
+
+def add_observability_args(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    """Add observability configuration arguments to an existing parser.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        The same parser with observability arguments added.
+    """
+    group = parser.add_argument_group(
+        "Observability", "Configuration for metrics, logging, and tracing"
+    )
+    group.add_argument(
+        "--disable-observability",
+        action="store_true",
+        default=False,
+        help="Disable the observability EventBus entirely.",
+    )
+    group.add_argument(
+        "--disable-metrics",
+        action="store_true",
+        default=False,
+        help="Disable metrics subscribers (OTel counters).",
+    )
+    group.add_argument(
+        "--disable-logging",
+        action="store_true",
+        default=False,
+        help="Disable logging subscribers.",
+    )
+    group.add_argument(
+        "--enable-tracing",
+        action="store_true",
+        default=False,
+        help="Enable span subscribers (OTel traces). Disabled by default.",
+    )
+    group.add_argument(
+        "--otlp-endpoint",
+        type=str,
+        default=None,
+        help=(
+            "OTLP gRPC endpoint (e.g. http://localhost:4317). "
+            "When set, metrics/traces are pushed to an OTel collector. "
+            "When unset, falls back to Prometheus pull mode."
+        ),
+    )
+    group.add_argument(
+        "--event-bus-queue-size",
+        type=int,
+        default=10_000,
+        help=(
+            "Maximum number of events in the EventBus queue before "
+            "tail-drop. Default is 10000."
+        ),
+    )
+    group.add_argument(
+        "--prometheus-port",
+        type=int,
+        default=9090,
+        help=(
+            "Port for the Prometheus /metrics endpoint. "
+            "Only used when --otlp-endpoint is not set. Default is 9090."
+        ),
+    )
+    group.add_argument(
+        "--metrics-sample-rate",
+        type=float,
+        default=0.01,
+        help=(
+            "Fraction of chunks/blocks to track for lifecycle histograms "
+            "(0, 1.0]. Counters always count all events. Default is 0.01 (1%%)."
+        ),
+    )
+
+    # Lookup hash logging config
+    log_group = parser.add_argument_group(
+        "Lookup Hash Logging",
+        "Configuration for lookup hash file logging (offline analysis)",
+    )
+    log_group.add_argument(
+        "--lookup-hash-log-dir",
+        type=str,
+        default="",
+        help="Directory to write lookup hash JSONL files for offline analysis. "
+        "Empty string (default) disables logging.",
+    )
+    log_group.add_argument(
+        "--lookup-hash-log-rotation-interval",
+        type=int,
+        default=6 * 3600,
+        help="Time interval in seconds before rotating to a new log file. "
+        "Default is 21600 (6 hours).",
+    )
+    log_group.add_argument(
+        "--lookup-hash-log-rotation-max-size",
+        type=int,
+        default=100 * 1024 * 1024,
+        help="Max file size in bytes before rotating even if the time "
+        "interval has not elapsed. Default is 100MB (104857600).",
+    )
+    log_group.add_argument(
+        "--lookup-hash-log-max-files",
+        type=int,
+        default=100,
+        help="Max number of lookup hash log files to keep. "
+        "Oldest files are deleted when this limit is exceeded. Default is 100.",
+    )
+
+    trace_group = parser.add_argument_group(
+        "Trace Recording",
+        "Capture LMCache operations to a binary trace file for replay "
+        "(see `lmcache trace`).",
+    )
+    trace_group.add_argument(
+        "--trace-level",
+        type=str,
+        choices=["storage"],
+        default=None,
+        help="Enable trace recording at the given level. Currently only "
+        "'storage' is supported (records StorageManager public-API calls).",
+    )
+    trace_group.add_argument(
+        "--trace-output",
+        type=str,
+        default=None,
+        help="Path to write the trace file. Defaults to a timestamped "
+        "file under $TMPDIR when --trace-level is set without an explicit "
+        "output path.",
+    )
+
+    return parser
+
+
+def parse_args_to_observability_config(
+    args: argparse.Namespace,
+) -> ObservabilityConfig:
+    """Convert parsed command line arguments to an ObservabilityConfig.
+
+    Args:
+        args: Parsed arguments from the argument parser.
+
+    Returns:
+        The configuration object.
+    """
+    config = ObservabilityConfig(
+        enabled=not args.disable_observability,
+        max_queue_size=args.event_bus_queue_size,
+        metrics_enabled=not args.disable_metrics,
+        logging_enabled=not args.disable_logging,
+        tracing_enabled=args.enable_tracing,
+        otlp_endpoint=args.otlp_endpoint,
+        prometheus_port=args.prometheus_port,
+        metrics_sample_rate=args.metrics_sample_rate,
+        lookup_hash_log=LookupHashLogConfig(
+            output_dir=args.lookup_hash_log_dir,
+            rotation_interval_sec=args.lookup_hash_log_rotation_interval,
+            rotation_max_size=args.lookup_hash_log_rotation_max_size,
+            max_files=args.lookup_hash_log_max_files,
+        ),
+        trace_level=args.trace_level,
+        trace_output=args.trace_output,
+    )
+
+    if config.tracing_enabled and config.otlp_endpoint is None:
+        raise ValueError(
+            "--enable-tracing requires --otlp-endpoint to be set. "
+            "Tracing needs an OTLP gRPC endpoint to export spans."
+        )
+
+    return config
+
+
+def init_observability(
+    obs_config: ObservabilityConfig,
+    *,
+    start_prometheus_http_server: bool = True,
+) -> EventBus:
+    """Initialize OTel providers, EventBus, and register subscribers.
+
+    This is the single entry-point that every MP server calls at startup.
+    Returns a **started** EventBus.
+
+    Args:
+        obs_config: Observability configuration.
+        start_prometheus_http_server: Whether to start a standalone
+            Prometheus HTTP server.  Set to ``False`` when an
+            external HTTP framework already serves ``/metrics``.
+    """
+    # First Party
+    from lmcache.v1.mp_observability.event_bus import (
+        EventBusConfig,
+        init_event_bus,
+    )
+
+    # Set up OTel providers BEFORE creating subscribers so that
+    # module-level get_meter()/get_tracer() calls bind to the real provider
+    instance_id = (
+        obs_config.service_instance_id
+        if obs_config.service_instance_id is not None
+        else str(uuid.uuid4())
+    )
+    resource_attrs = {"service.instance.id": instance_id}
+
+    if obs_config.enabled and obs_config.metrics_enabled:
+        # First Party
+        from lmcache.v1.mp_observability.otel_init import init_otel_metrics
+
+        init_otel_metrics(
+            otlp_endpoint=obs_config.otlp_endpoint,
+            prometheus_port=obs_config.prometheus_port,
+            resource_attributes=resource_attrs,
+            start_http_server=start_prometheus_http_server,
+        )
+
+    if obs_config.enabled and obs_config.tracing_enabled:
+        # First Party
+        from lmcache.v1.mp_observability.otel_init import init_otel_tracing
+
+        init_otel_tracing(
+            otlp_endpoint=obs_config.otlp_endpoint,
+            resource_attributes=resource_attrs,
+        )
+
+    bus = init_event_bus(
+        EventBusConfig(
+            enabled=obs_config.enabled,
+            max_queue_size=obs_config.max_queue_size,
+        )
+    )
+
+    if obs_config.metrics_enabled:
+        # First Party
+        from lmcache.v1.mp_observability.subscribers.metrics import (
+            BlendMetricsSubscriber,
+            EngineMetricsSubscriber,
+            EventBusSelfMetricsSubscriber,
+            L0L1ThroughputSubscriber,
+            L0LifecycleSubscriber,
+            L1EvictionLoopSubscriber,
+            L1FailureMetricsSubscriber,
+            L1LifecycleSubscriber,
+            L1MetricsSubscriber,
+            L2FailureMetricsSubscriber,
+            L2MetricsSubscriber,
+            L2ThroughputSubscriber,
+            LookupMetricsSubscriber,
+            SMLifecycleSubscriber,
+            TimeoutMetricsSubscriber,
+        )
+
+        sample_rate = obs_config.metrics_sample_rate
+        bus.register_subscriber(L0LifecycleSubscriber(sample_rate=sample_rate))
+        bus.register_subscriber(L1MetricsSubscriber())
+        bus.register_subscriber(L1LifecycleSubscriber(sample_rate=sample_rate))
+        bus.register_subscriber(L1FailureMetricsSubscriber())
+        bus.register_subscriber(L1EvictionLoopSubscriber())
+        bus.register_subscriber(L0L1ThroughputSubscriber())
+        bus.register_subscriber(L2MetricsSubscriber())
+        bus.register_subscriber(L2FailureMetricsSubscriber())
+        bus.register_subscriber(L2ThroughputSubscriber())
+        bus.register_subscriber(LookupMetricsSubscriber())
+        bus.register_subscriber(SMLifecycleSubscriber(sample_rate=sample_rate))
+        bus.register_subscriber(BlendMetricsSubscriber())
+        bus.register_subscriber(EngineMetricsSubscriber())
+        bus.register_subscriber(EventBusSelfMetricsSubscriber(bus))
+        bus.register_subscriber(TimeoutMetricsSubscriber())
+
+    if obs_config.logging_enabled:
+        # First Party
+        from lmcache.v1.mp_observability.subscribers.logging import (
+            BlendLoggingSubscriber,
+            L1LoggingSubscriber,
+            L2LoggingSubscriber,
+            MPServerLoggingSubscriber,
+            SMLoggingSubscriber,
+            TimeoutLoggingSubscriber,
+        )
+
+        bus.register_subscriber(MPServerLoggingSubscriber())
+        bus.register_subscriber(L1LoggingSubscriber())
+        bus.register_subscriber(L2LoggingSubscriber())
+        bus.register_subscriber(SMLoggingSubscriber())
+        bus.register_subscriber(BlendLoggingSubscriber())
+        bus.register_subscriber(TimeoutLoggingSubscriber())
+
+    if obs_config.tracing_enabled:
+        # First Party
+        from lmcache.v1.mp_observability.subscribers.tracing import (
+            BlendTracingSubscriber,
+            MPServerTracingSubscriber,
+            TimeoutTracingSubscriber,
+            get_span_registry,
+        )
+
+        registry = get_span_registry()
+        bus.register_subscriber(MPServerTracingSubscriber(registry))
+        bus.register_subscriber(BlendTracingSubscriber(registry))
+        bus.register_subscriber(TimeoutTracingSubscriber(registry))
+
+    # Lookup hash file logging (independent of the logging_enabled flag —
+    # it has its own enable gate via output_dir).
+    if obs_config.lookup_hash_log.enabled:
+        # First Party
+        from lmcache.v1.mp_observability.subscribers.logging.lookup_hash import (
+            LookupHashLoggingSubscriber,
+        )
+
+        bus.register_subscriber(LookupHashLoggingSubscriber(obs_config.lookup_hash_log))
+
+    bus.start()
+    return bus
diff --git a/lmcache/v1/mp_observability/errors.py b/lmcache/v1/mp_observability/errors.py
new file mode 100644
index 0000000..6ec5d25
--- /dev/null
+++ b/lmcache/v1/mp_observability/errors.py
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Observability-aware timeout error.
+
+Raise :class:`LMCacheTimeoutError` instead of the builtin ``TimeoutError`` so
+each timeout is reported to MP observability. The ``ban-raw-timeout-error``
+pre-commit hook enforces this across ``lmcache/``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import traceback
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import (
+    get_event_bus,
+    is_observability_enabled,
+)
+
+logger = init_logger(__name__)
+
+
+class LMCacheTimeoutError(TimeoutError):
+    """``TimeoutError`` that publishes a ``TIMEOUT_RAISED`` event on construction.
+
+    Subclasses the builtin, so existing ``except TimeoutError`` handlers still
+    catch it. Publishing is skipped (no event, no stack capture) when
+    observability is disabled, and a publish failure never propagates out of
+    ``__init__``.
+
+    Args:
+        message: Timeout description; also the event's ``message`` field.
+        session_id: Request id for correlating the timeout with its originating
+            request; empty when unavailable.
+    """
+
+    def __init__(self, message: str, *, session_id: str = "") -> None:
+        super().__init__(message)
+        if not is_observability_enabled():
+            return
+        # Stack at the raise site, minus this __init__ frame.
+        stacktrace = "".join(traceback.format_stack()[:-1])
+        self._publish_timeout_event(message, stacktrace, session_id)
+
+    def _publish_timeout_event(
+        self, message: str, stacktrace: str, session_id: str
+    ) -> None:
+        """Publish a ``TIMEOUT_RAISED`` event; swallow any failure."""
+        try:
+            get_event_bus().publish(
+                Event(
+                    event_type=EventType.TIMEOUT_RAISED,
+                    metadata={
+                        "message": message,
+                        "exception_type": type(self).__name__,
+                        "stacktrace": stacktrace,
+                    },
+                    session_id=session_id,
+                )
+            )
+        except Exception:
+            logger.debug("Failed to publish TIMEOUT_RAISED event", exc_info=True)
diff --git a/lmcache/v1/mp_observability/event.py b/lmcache/v1/mp_observability/event.py
new file mode 100644
index 0000000..18b3bdb
--- /dev/null
+++ b/lmcache/v1/mp_observability/event.py
@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unified event model for the MP observability system."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class EventType(Enum):
+    """All observable event types in the MP system.
+
+    Naming convention: ``<COMPONENT>_<OPERATION>`` or
+    ``<COMPONENT>_<OPERATION>_<PHASE>`` for start/end pairs.
+    """
+
+    # L1 Manager events
+    L1_READ_RESERVED = "l1.read.reserved"
+    L1_READ_FINISHED = "l1.read.finished"
+    L1_WRITE_RESERVED = "l1.write.reserved"
+    L1_WRITE_FINISHED = "l1.write.finished"
+    L1_WRITE_FINISHED_AND_READ_RESERVED = "l1.write_finished_and_read_reserved"
+    L1_KEYS_EVICTED = "l1.keys.evicted"
+    L1_EVICTION_LOOP_TICK = "l1.eviction.loop_tick"
+
+    # L1 failure events (LM-291 health monitoring)
+    L1_ALLOCATION_FAILED = "l1.allocation.failed"
+    L1_READ_FAILED = "l1.read.failed"
+
+    # StorageManager events
+    SM_READ_PREFETCHED = "sm.read.prefetched"
+    SM_READ_PREFETCHED_FINISHED = "sm.read.prefetched_finished"
+    SM_WRITE_RESERVED = "sm.write.reserved"
+    SM_WRITE_FINISHED = "sm.write.finished"
+
+    # L2 Store Controller events
+    L2_STORE_SUBMITTED = "l2.store.submitted"
+    L2_STORE_COMPLETED = "l2.store.completed"
+
+    # L2 Prefetch Controller events
+    L2_PREFETCH_LOOKUP_SUBMITTED = "l2.prefetch.lookup.submitted"
+    L2_PREFETCH_LOOKUP_COMPLETED = "l2.prefetch.lookup.completed"
+    L2_PREFETCH_LOAD_SUBMITTED = "l2.prefetch.load.submitted"
+    L2_PREFETCH_LOAD_COMPLETED = "l2.prefetch.load.completed"
+    # Per-adapter load task events, for throughput correlation.  Fire once
+    # per (request_id, adapter_index) pair, unlike the request-level
+    # L2_PREFETCH_LOAD_* events above which aggregate across adapters.
+    L2_LOAD_TASK_SUBMITTED = "l2.load_task.submitted"
+    L2_LOAD_TASK_COMPLETED = "l2.load_task.completed"
+
+    # L2 Eviction Controller events
+    L2_KEYS_EVICTED = "l2.keys.evicted"
+
+    # L2 failure events (LM-291 health monitoring)
+    L2_PREFETCH_FAILED = "l2.prefetch.failed"
+
+    # MP Server request-level events (start/end pairs)
+    MP_STORE_START = "mp.store.start"
+    MP_STORE_END = "mp.store.end"
+    MP_RETRIEVE_START = "mp.retrieve.start"
+    MP_RETRIEVE_END = "mp.retrieve.end"
+    MP_LOOKUP_PREFETCH_START = "mp.lookup_prefetch.start"
+    MP_LOOKUP_PREFETCH_END = "mp.lookup_prefetch.end"
+
+    # Chunk hash logging events
+    MP_LOOKUP = "mp.lookup"
+
+    # MP Server lifecycle sentinels (CPU-synchronous)
+    MP_REQUEST_START = "mp.request.start"
+    MP_RETRIEVE_SUBMITTED = "mp.retrieve.submitted"
+    MP_STORE_SUBMITTED = "mp.store.submitted"
+    MP_REQUEST_END = "mp.request.end"
+
+    # vLLM block allocation events
+    MP_VLLM_BLOCK_ALLOCATION = "mp.vllm.block_allocation"
+
+    # vLLM end session events
+    MP_VLLM_END_SESSION = "mp.vllm.end_session"
+
+    # Published by LMCacheTimeoutError on construction (see errors.py).
+    # Metadata: message (str), exception_type (str), stacktrace (str, mapped
+    # to the OTel exception.stacktrace span attribute).
+    TIMEOUT_RAISED = "timeout.raised"
+
+    # Trace recording — unified function-call entry event used by the
+    # ``@enable_tracing`` decorator.  Metadata layout:
+    #   ``qualname`` (str):   fully-qualified function name
+    #   ``args``     (dict):  name -> raw Python value (codec-encoded at
+    #                         record time by the recorder)
+    #   ``t_mono``   (float): ``time.monotonic()`` captured at publish
+    #                         time, so it is comparable to
+    #                         ``Event.timestamp`` (wall-clock) even
+    #                         though the drain thread processes the
+    #                         event later
+    TRACE_CALL = "trace.call"
+
+    # Cache Blending (CB) events — GPU operation start/end pairs
+    CB_LOOKUP_START = "cb.lookup.start"
+    CB_LOOKUP_END = "cb.lookup.end"
+    CB_STORE_PRE_COMPUTED_START = "cb.store_pre_computed.start"
+    CB_STORE_PRE_COMPUTED_END = "cb.store_pre_computed.end"
+    CB_RETRIEVE_START = "cb.retrieve.start"
+    CB_RETRIEVE_END = "cb.retrieve.end"
+    CB_STORE_FINAL_START = "cb.store_final.start"
+    CB_STORE_FINAL_END = "cb.store_final.end"
+    CB_FINGERPRINTS_REGISTERED = "cb.fingerprints.registered"
+    CB_CHUNKS_EVICTED = "cb.chunks.evicted"
+
+    # CB V3 lookup sub-spans (CPU) — nest under cb.lookup. Submitted-once but
+    # END may fire on a later poll (the non-blocking lookup re-issues), so the
+    # span captures submit→resident incl. poll-wait.
+    CB_FINGERPRINT_MATCH_START = "cb.fingerprint_match.start"
+    CB_FINGERPRINT_MATCH_END = "cb.fingerprint_match.end"
+    # Prefix leg: blend_v3 owns the submit/poll (direct storage_manager), so the
+    # prefix lookup is a CB-namespace span under cb.lookup. Its hit tokens ride
+    # the CB hit-rate metric via CB_LOOKUP_END (CB requests no longer feed the
+    # MP mp.lookup_prefetch span / hit-rate aggregate).
+    CB_PREFIX_LOOKUP_START = "cb.prefix_lookup.start"
+    CB_PREFIX_LOOKUP_END = "cb.prefix_lookup.end"
+    # Coordinator (fleet directory) match leg — cross-server analogue of
+    # cb.fingerprint_match. Async: START at submit, END on the resolving poll.
+    CB_COORDINATOR_MATCH_START = "cb.coordinator_match.start"
+    CB_COORDINATOR_MATCH_END = "cb.coordinator_match.end"
+    CB_SPARSE_PREFETCH_START = "cb.sparse_prefetch.start"
+    CB_SPARSE_PREFETCH_END = "cb.sparse_prefetch.end"
+
+    # CB V3 retrieve sub-span (GPU) — nest under cb.retrieve. Emitted via
+    # publish_on_stream for GPU-accurate timing of the L1->paged scatter.
+    CB_SCATTER_START = "cb.scatter.start"
+    CB_SCATTER_END = "cb.scatter.end"
+
+    # Cache Blending (CB) events — lifecycle sentinels (CPU-synchronous)
+    CB_REQUEST_START = "cb.request.start"
+    CB_STORE_PRE_COMPUTED_SUBMITTED = "cb.store_pre_computed.submitted"
+    CB_RETRIEVE_SUBMITTED = "cb.retrieve.submitted"
+    CB_STORE_FINAL_SUBMITTED = "cb.store_final.submitted"
+    CB_REQUEST_END = "cb.request.end"
+
+
+@dataclass
+class Event:
+    """A single observable event in the MP system.
+
+    Attributes:
+        event_type: The type of event.
+        timestamp: Wall-clock time (``time.time()``) stamped by
+            ``EventBus.publish()`` at the moment it is called — not when the
+            drain thread processes the event.  For CUDA host-callback events
+            this captures GPU-accurate timing.
+        metadata: Flat key-value payload.  Contents depend on ``event_type``;
+            see the metadata contracts in
+            ``docs/design/v1/mp_observability/event-bus.md`` Section 2.7.
+        session_id: Caller-provided ID for correlating start/end pairs.
+    """
+
+    event_type: EventType
+    timestamp: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+    session_id: str = ""
diff --git a/lmcache/v1/mp_observability/event_bus.py b/lmcache/v1/mp_observability/event_bus.py
new file mode 100644
index 0000000..2152dc5
--- /dev/null
+++ b/lmcache/v1/mp_observability/event_bus.py
@@ -0,0 +1,387 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""EventBus: unified pub/sub dispatcher for MP observability events."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Callable
+import collections
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.otel_init import register_gauge
+
+try:
+    # Third Party
+    import torch  # noqa: F401 — must be imported before lmcache.c_ops
+
+    # First Party
+    import lmcache.c_ops as _lmc_ops
+
+    _has_native_recorder = hasattr(_lmc_ops, "record_event_on_stream")
+except ImportError:
+    _has_native_recorder = False
+
+logger = init_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+EventCallback = Callable[[Event], None]
+
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EventBusConfig:
+    """Configuration for the EventBus.
+
+    Attributes:
+        enabled: Whether the event bus is active.  When disabled,
+            ``publish()`` is a no-op and the drain thread is not started.
+        max_queue_size: Maximum number of events in the queue.  When the
+            queue is full, new events are silently dropped with a
+            rate-limited warning.
+    """
+
+    enabled: bool = True
+    max_queue_size: int = 10_000
+
+
+# ---------------------------------------------------------------------------
+# Subscriber ABC
+# ---------------------------------------------------------------------------
+
+
+class EventSubscriber(ABC):
+    """Base class for per-component event subscribers.
+
+    Subclasses declare which ``EventType``\\s they care about via
+    ``get_subscriptions()``.  The ``register()`` helper wires them up to
+    an ``EventBus``.
+    """
+
+    @abstractmethod
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        """Return event_type -> callback mapping.
+
+        Called once during ``register()``.  The EventBus stores these
+        callbacks directly.
+        """
+        ...
+
+    def register(self, bus: EventBus) -> None:
+        """Subscribe all declared handlers to *bus*."""
+        for event_type, callback in self.get_subscriptions().items():
+            bus.subscribe(event_type, callback)
+
+    def shutdown(self) -> None:  # noqa: B027
+        """Optional cleanup hook.  Called by ``EventBus.stop()``."""
+        pass
+
+
+# ---------------------------------------------------------------------------
+# EventBus
+# ---------------------------------------------------------------------------
+
+
+class EventBus:
+    """Manages event ingestion, queueing, and dispatch to subscribers.
+
+    Events are appended to a deque on the hot path (``publish()``) and
+    drained by a background thread that dispatches to registered callbacks.
+    """
+
+    def __init__(self, config: EventBusConfig | None = None) -> None:
+        if config is None:
+            config = EventBusConfig()
+        self._config = config
+        self._subscribers: dict[EventType, list[EventCallback]] = defaultdict(list)
+        self._queue: collections.deque[Event] = collections.deque()
+        self._wake = threading.Event()
+        self._stop_flag = threading.Event()
+        self._lock = threading.Lock()
+        self._thread: threading.Thread | None = None
+        self._registered_subscribers: list[EventSubscriber] = []
+        self._discard_count: int = 0
+        self._last_discard_warning: float = 0.0
+        self._subscriber_exception_counts: dict[str, int] = {}
+
+        self._register_self_gauges()
+
+    def _register_self_gauges(self) -> None:
+        """Register the two self-monitoring gauges via ``register_gauge``."""
+        register_gauge(
+            "lmcache.event_bus",
+            "lmcache_mp.event_bus.queue_depth",
+            "Events currently queued in the EventBus.",
+            self.queue_depth,
+        )
+        register_gauge(
+            "lmcache.event_bus",
+            "lmcache_mp.event_bus.drain_lag_seconds",
+            (
+                "Seconds since the oldest queued event was published; 0.0 "
+                "when empty.  Rising values mean the drain thread is "
+                "falling behind."
+            ),
+            self.oldest_event_lag_seconds,
+        )
+
+    # -- Public API --------------------------------------------------------
+
+    def subscribe(self, event_type: EventType, callback: EventCallback) -> None:
+        """Register a callback for a specific event type (thread-safe)."""
+        with self._lock:
+            self._subscribers[event_type].append(callback)
+
+    def register_subscriber(self, subscriber: EventSubscriber) -> None:
+        """Register an ``EventSubscriber`` and wire up its callbacks."""
+        subscriber.register(self)
+        with self._lock:
+            self._registered_subscribers.append(subscriber)
+
+    def has_subscribers(self, event_type: EventType) -> bool:
+        """Return True if at least one callback is registered for *event_type*.
+
+        Use this to skip expensive event construction on the hot path when
+        no subscriber is listening::
+
+            if bus.has_subscribers(EventType.MP_LOOKUP):
+                bus.publish(Event(event_type=EventType.MP_LOOKUP, ...))
+        """
+        return bool(self._subscribers.get(event_type))
+
+    def publish_on_stream(self, stream: Any, event: Event) -> None:
+        """Schedule event recording as a CUDA host function on *stream*.
+
+        Uses a C++ callback via ``cudaLaunchHostFunc`` so the callback
+        never touches the GIL, avoiding the CUDA-driver/GIL deadlock.
+
+        No-op when the EventBus is disabled, avoiding the overhead of
+        scheduling a host function on the CUDA stream entirely.
+        """
+        if not self._config.enabled:
+            return
+        if _has_native_recorder:
+            str_metadata: dict[str, str] = {}
+            int_metadata: dict[str, int] = {}
+            for k, v in event.metadata.items():
+                if isinstance(v, int):
+                    int_metadata[k] = v
+                else:
+                    str_metadata[k] = str(v)
+            _lmc_ops.record_event_on_stream(
+                stream.ptr,
+                event.event_type.value,
+                event.session_id,
+                str_metadata,
+                int_metadata,
+            )
+        else:
+            stream.launch_host_func(self.publish, event)
+
+    def publish(self, event: Event) -> None:
+        """Submit an event (hot path — non-blocking).
+
+        The event's ``timestamp`` is set to ``time.time()`` at call time.
+        When the queue is full the event is silently discarded with a
+        rate-limited warning (at most once per second).
+        """
+        if not self._config.enabled:
+            return
+
+        if len(self._queue) >= self._config.max_queue_size:
+            self._discard_count += 1
+            now = time.monotonic()
+            if now - self._last_discard_warning >= 1.0:
+                logger.warning(
+                    "EventBus queue full (max_queue_size=%d), "
+                    "%d event(s) discarded so far",
+                    self._config.max_queue_size,
+                    self._discard_count,
+                )
+                self._last_discard_warning = now
+            return
+
+        event.timestamp = time.time()
+        self._queue.append(event)
+        self._wake.set()
+
+    def start(self) -> None:
+        """Start the background drain thread.  No-op when disabled or
+        already running."""
+        if not self._config.enabled:
+            return
+        if self._thread is not None and self._thread.is_alive():
+            return
+
+        self._stop_flag.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            daemon=True,
+            name="EventBus",
+        )
+        logger.debug("Starting EventBus drain thread...")
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop the drain thread, flush remaining events, and shut down
+        all registered subscribers.  Safe to call when not started."""
+        self._stop_flag.set()
+        self._wake.set()
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join()
+
+        # Final drain
+        self._drain_all()
+
+        # Shutdown subscribers
+        with self._lock:
+            snapshot = list(self._registered_subscribers)
+        for sub in snapshot:
+            try:
+                sub.shutdown()
+            except Exception:
+                logger.exception(
+                    "EventBus: error shutting down %s",
+                    type(sub).__name__,
+                )
+
+    # -- Self-monitoring ---------------------------------------------------
+
+    def queue_depth(self) -> int:
+        """Number of events currently queued waiting for dispatch.
+
+        Reads ``len`` on the underlying deque, which is atomic in CPython,
+        so callers can poll this from a metrics scrape callback without
+        holding the bus lock.
+        """
+        return len(self._queue)
+
+    def oldest_event_lag_seconds(self) -> float:
+        """Wall-clock age of the oldest queued event, or 0.0 when empty.
+
+        Used as a drain-lag gauge: a rising value means the drain thread
+        is not keeping up with publish rate.  Read without the lock; if
+        the deque is concurrently popped during the peek, returns 0.0.
+        """
+        try:
+            oldest = self._queue[0]
+        except IndexError:
+            return 0.0
+        return max(0.0, time.time() - oldest.timestamp)
+
+    def dropped_events_count(self) -> int:
+        """Cumulative count of events dropped because the queue was full."""
+        return self._discard_count
+
+    def subscriber_exception_counts(self) -> dict[str, int]:
+        """Snapshot of per-subscriber callback exception counts.
+
+        Maps ``subscriber_name`` (the owning class name for bound methods,
+        ``__qualname__`` for free functions) to the cumulative count of
+        exceptions raised by that subscriber's callbacks during dispatch.
+        Returns a copy that callers may iterate without holding the bus
+        lock.
+        """
+        with self._lock:
+            return dict(self._subscriber_exception_counts)
+
+    # -- Internal ----------------------------------------------------------
+
+    def _run(self) -> None:
+        """Drain loop: wait for wake signal or timeout, then drain."""
+        while not self._stop_flag.is_set():
+            self._wake.wait(timeout=0.1)
+            self._wake.clear()
+            self._drain_all()
+
+    def _drain_all(self) -> None:
+        """Pop all queued events and dispatch to subscribers."""
+        # Drain events buffered on the C++ side (from CUDA host callbacks)
+        if _has_native_recorder:
+            for name, sid, ts, str_meta, int_meta in _lmc_ops.drain_recorded_events():
+                metadata: dict[str, Any] = dict(str_meta)
+                metadata.update(int_meta)
+                self._queue.append(
+                    Event(
+                        event_type=EventType(name),
+                        session_id=sid,
+                        timestamp=ts,
+                        metadata=metadata,
+                    )
+                )
+
+        with self._lock:
+            snapshot = dict(self._subscribers)
+
+        while True:
+            try:
+                event = self._queue.popleft()
+            except IndexError:
+                break
+            for cb in snapshot.get(event.event_type, []):
+                try:
+                    cb(event)
+                except Exception:
+                    instance = getattr(cb, "__self__", None)
+                    name = (
+                        type(instance).__name__
+                        if instance is not None
+                        else getattr(cb, "__qualname__", repr(cb))
+                    )
+                    with self._lock:
+                        self._subscriber_exception_counts[name] = (
+                            self._subscriber_exception_counts.get(name, 0) + 1
+                        )
+                    logger.exception(
+                        "EventBus: error in callback %s for %s",
+                        name,
+                        event.event_type.value,
+                    )
+
+
+# ---------------------------------------------------------------------------
+# Singleton
+# ---------------------------------------------------------------------------
+
+_global_bus = EventBus(EventBusConfig(enabled=False))
+_observability_enabled: bool = False
+
+
+def is_observability_enabled() -> bool:
+    """Fast check for whether observability is active.
+
+    Use this to guard expensive event-construction or CUDA host-function
+    scheduling when observability is disabled.
+    """
+    return _observability_enabled
+
+
+def get_event_bus() -> EventBus:
+    """Return the current global EventBus singleton."""
+    return _global_bus
+
+
+def init_event_bus(config: EventBusConfig | None = None) -> EventBus:
+    """Replace the global singleton with a new EventBus built from *config*.
+
+    Returns the newly created bus.
+    """
+    global _global_bus, _observability_enabled
+    _global_bus = EventBus(config)
+    _observability_enabled = config.enabled if config else True
+    return _global_bus
diff --git a/lmcache/v1/mp_observability/otel_init.py b/lmcache/v1/mp_observability/otel_init.py
new file mode 100644
index 0000000..28f49fc
--- /dev/null
+++ b/lmcache/v1/mp_observability/otel_init.py
@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""OpenTelemetry SDK initialization for the MP observability system.
+
+Supports two modes, controlled by the ``otlp_endpoint`` field in
+``ObservabilityConfig``:
+
+- **OTLP push** (production): metrics/traces are pushed to an OTel collector.
+- **Prometheus pull** (dev/debug): metrics are served on a local ``/metrics``
+  endpoint via ``prometheus_client``, no collector needed.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Third Party
+    from opentelemetry.sdk.resources import Resource
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def _build_resource(resource_attributes: dict[str, str] | None) -> "Resource":
+    """Build an OTel ``Resource`` from the given attribute dict.
+
+    Returns an empty ``Resource`` when *resource_attributes* is empty or
+    ``None`` so that telemetry carries no stale process-level tags.
+    """
+    # Third Party
+    from opentelemetry.sdk.resources import Resource
+
+    if not resource_attributes:
+        return Resource.create({})
+    return Resource.create(dict(resource_attributes))
+
+
+def init_otel_metrics(
+    otlp_endpoint: str | None = None,
+    prometheus_port: int | None = None,
+    resource_attributes: dict[str, str] | None = None,
+    start_http_server: bool = True,
+) -> None:
+    """Set up the OpenTelemetry MeterProvider.
+
+    Args:
+        otlp_endpoint: OTLP gRPC endpoint (e.g. ``http://localhost:4317``).
+            When set, metrics are pushed to an OTel collector.
+            When ``None``, falls back to Prometheus pull mode.
+        prometheus_port: Port for the fallback Prometheus ``/metrics``
+            endpoint.  Only used when *otlp_endpoint* is ``None``.
+            Defaults to 9090.
+        resource_attributes: Optional ``{attr_name: value}`` map attached
+            to the ``MeterProvider`` ``Resource``.  Every metric emitted
+            through the provider carries these attributes.  Intended for
+            process-level identity (e.g. ``service.instance.id``) — never
+            for per-request tags.
+        start_http_server: Whether to start a standalone Prometheus
+            HTTP server.  Set to ``False`` when metrics are already
+            served by an external HTTP framework (e.g. FastAPI).
+    """
+    # Third Party
+    from opentelemetry import metrics
+    from opentelemetry.sdk.metrics import MeterProvider
+
+    resource = _build_resource(resource_attributes)
+
+    if otlp_endpoint is not None:
+        # OTLP push mode
+        # Third Party
+        from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+            OTLPMetricExporter,
+        )
+        from opentelemetry.sdk.metrics.export import (
+            PeriodicExportingMetricReader,
+        )
+
+        exporter = OTLPMetricExporter(endpoint=otlp_endpoint, insecure=True)
+        reader = PeriodicExportingMetricReader(exporter, export_interval_millis=10000)
+        provider = MeterProvider(metric_readers=[reader], resource=resource)
+        metrics.set_meter_provider(provider)
+        logger.info(
+            "OTel MeterProvider initialised with OTLP exporter (%s), resource=%s",
+            otlp_endpoint,
+            dict(resource.attributes),
+        )
+    else:
+        # Prometheus pull fallback — no collector needed
+        # Third Party
+        from opentelemetry.exporter.prometheus import PrometheusMetricReader
+        import prometheus_client
+
+        if prometheus_port is None:
+            prometheus_port = 9090
+
+        reader = PrometheusMetricReader()
+        provider = MeterProvider(metric_readers=[reader], resource=resource)
+        metrics.set_meter_provider(provider)
+        if start_http_server:
+            prometheus_client.start_http_server(prometheus_port)
+            logger.info(
+                "OTel MeterProvider initialised with Prometheus fallback "
+                "(http://0.0.0.0:%d/metrics), resource=%s",
+                prometheus_port,
+                dict(resource.attributes),
+            )
+        else:
+            logger.info(
+                "OTel MeterProvider initialised with Prometheus fallback "
+                "(standalone metrics HTTP server disabled; "
+                "/metrics must be exposed by the caller), resource=%s",
+                dict(resource.attributes),
+            )
+
+
+def init_otel_tracing(
+    otlp_endpoint: str | None = None,
+    resource_attributes: dict[str, str] | None = None,
+) -> None:
+    """Set up the OpenTelemetry TracerProvider with an OTLP exporter.
+
+    Tracing requires an OTLP endpoint — there is no local fallback.
+    When *otlp_endpoint* is ``None``, tracing init is skipped.
+
+    Args:
+        otlp_endpoint: OTLP gRPC endpoint.  When ``None``, tracing
+            init is skipped (no-op).
+        resource_attributes: Optional ``{attr_name: value}`` map attached
+            to the ``TracerProvider`` ``Resource``.  Every span emitted
+            through the provider carries these attributes.
+    """
+    if otlp_endpoint is None:
+        logger.debug("No OTLP endpoint configured, skipping tracing init")
+        return
+
+    # Third Party
+    from opentelemetry import trace
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+        OTLPSpanExporter,
+    )
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    resource = _build_resource(resource_attributes)
+    exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    logger.info(
+        "OTel TracerProvider initialised with OTLP exporter (%s), resource=%s",
+        otlp_endpoint,
+        dict(resource.attributes),
+    )
+
+
+def register_gauge(
+    meter_name: str,
+    gauge_name: str,
+    description: str,
+    func: Callable[[], int | float]
+    | Callable[[], list[tuple[int | float, dict[str, object]]]],
+) -> None:
+    """Register an OTel observable gauge with a callback.
+
+    This is a convenience wrapper that hides the OTel boilerplate.
+    If OTel is not available, the call is silently ignored.
+
+    Two callback shapes are accepted:
+
+    - **Single value (no attributes).** ``func`` returns ``int`` / ``float``
+      and the gauge emits one datapoint per scrape with no attributes.
+      Use this for whole-process metrics like
+      ``lmcache_mp.active_prefetch_jobs``.
+    - **Per-attribute-set values.** ``func`` returns a list of
+      ``(value, attrs)`` tuples; the gauge emits one datapoint per tuple
+      with the given attributes.  Use this for per-adapter or per-tier
+      metrics that share a name but vary by attribute.  An empty list
+      reports no datapoints (the metric simply does not appear in the
+      next scrape, which is the correct shape when there is nothing to
+      observe).
+
+    Args:
+        meter_name: OTel meter name (e.g. ``lmcache.mp_server``).
+        gauge_name: Metric name (e.g.
+            ``lmcache_mp.active_prefetch_jobs``).
+        description: Human-readable description of the gauge.
+        func: Zero-arg callable.  Either a function returning the current
+            scalar value, or a function returning a list of
+            ``(value, attrs)`` tuples for tagged observations.
+    """
+    try:
+        # Third Party
+        from opentelemetry import metrics as otel_metrics
+
+        def _callback(_options):
+            result = func()
+            if isinstance(result, list):
+                return [
+                    otel_metrics.Observation(value, attrs) for value, attrs in result
+                ]
+            return [otel_metrics.Observation(result)]
+
+        meter = otel_metrics.get_meter(meter_name)
+        meter.create_observable_gauge(
+            gauge_name,
+            callbacks=[_callback],
+            description=description,
+        )
+    except ImportError:
+        logger.debug(
+            "opentelemetry package not found, skipping gauge %s",
+            gauge_name,
+        )
diff --git a/lmcache/v1/mp_observability/subscribers/__init__.py b/lmcache/v1/mp_observability/subscribers/__init__.py
new file mode 100644
index 0000000..edcc6d0
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/__init__.py
@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.mp_observability.subscribers.logging import (
+    L1LoggingSubscriber,
+    MPServerLoggingSubscriber,
+    SMLoggingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics import (
+    L0LifecycleSubscriber,
+    L1LifecycleSubscriber,
+    L1MetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.tracing import (
+    MPServerTracingSubscriber,
+)
+
+__all__ = [
+    "L0LifecycleSubscriber",
+    "L1LifecycleSubscriber",
+    "L1LoggingSubscriber",
+    "L1MetricsSubscriber",
+    "MPServerLoggingSubscriber",
+    "MPServerTracingSubscriber",
+    "SMLoggingSubscriber",
+]
diff --git a/lmcache/v1/mp_observability/subscribers/logging/__init__.py b/lmcache/v1/mp_observability/subscribers/logging/__init__.py
new file mode 100644
index 0000000..5be00f7
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/__init__.py
@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.mp_observability.subscribers.logging.cb_server import (
+    BlendLoggingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.logging.l1 import L1LoggingSubscriber
+from lmcache.v1.mp_observability.subscribers.logging.l2 import L2LoggingSubscriber
+from lmcache.v1.mp_observability.subscribers.logging.lookup_hash import (
+    LookupHashLoggingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.logging.mp_server import (
+    MPServerLoggingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.logging.sm import SMLoggingSubscriber
+from lmcache.v1.mp_observability.subscribers.logging.timeout import (
+    TimeoutLoggingSubscriber,
+)
+
+__all__ = [
+    "BlendLoggingSubscriber",
+    "L1LoggingSubscriber",
+    "L2LoggingSubscriber",
+    "LookupHashLoggingSubscriber",
+    "MPServerLoggingSubscriber",
+    "SMLoggingSubscriber",
+    "TimeoutLoggingSubscriber",
+]
diff --git a/lmcache/v1/mp_observability/subscribers/logging/cb_server.py b/lmcache/v1/mp_observability/subscribers/logging/cb_server.py
new file mode 100644
index 0000000..86508b7
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/cb_server.py
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Blend logging subscriber — debug logs for cache blending events."""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class BlendLoggingSubscriber(EventSubscriber):
+    """Logs cache blending (CB) events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        """Return the mapping of event types to handler callbacks."""
+        return {
+            EventType.CB_STORE_PRE_COMPUTED_START: self._on_store_pre_start,
+            EventType.CB_STORE_PRE_COMPUTED_END: self._on_store_pre_end,
+            EventType.CB_LOOKUP_START: self._on_lookup_start,
+            EventType.CB_LOOKUP_END: self._on_lookup_end,
+            EventType.CB_RETRIEVE_START: self._on_retrieve_start,
+            EventType.CB_RETRIEVE_END: self._on_retrieve_end,
+            EventType.CB_STORE_FINAL_START: self._on_store_final_start,
+            EventType.CB_STORE_FINAL_END: self._on_store_final_end,
+            EventType.CB_FINGERPRINTS_REGISTERED: self._on_fingerprints_registered,
+            EventType.CB_CHUNKS_EVICTED: self._on_chunks_evicted,
+        }
+
+    def _on_store_pre_start(self, event: Event) -> None:
+        logger.debug(
+            "CB store_pre_computed start: session=%s instance_id=%s num_tokens=%s",
+            event.session_id,
+            event.metadata.get("instance_id"),
+            event.metadata.get("num_tokens"),
+        )
+
+    def _on_store_pre_end(self, event: Event) -> None:
+        logger.debug(
+            "CB store_pre_computed end: session=%s instance_id=%s"
+            " num_tokens=%s stored_chunks=%s success=%s",
+            event.session_id,
+            event.metadata.get("instance_id"),
+            event.metadata.get("num_tokens"),
+            event.metadata.get("stored_chunks"),
+            event.metadata.get("success"),
+        )
+
+    def _on_lookup_start(self, event: Event) -> None:
+        logger.debug(
+            "CB lookup start: session=%s num_tokens=%s",
+            event.session_id,
+            event.metadata.get("num_tokens"),
+        )
+
+    def _on_lookup_end(self, event: Event) -> None:
+        logger.debug(
+            "CB lookup end: session=%s num_tokens=%s"
+            " fingerprint_hits=%s storage_hits=%s stale_chunks=%s no_gpu_context=%s",
+            event.session_id,
+            event.metadata.get("num_tokens"),
+            event.metadata.get("fingerprint_hits"),
+            event.metadata.get("storage_hits"),
+            event.metadata.get("stale_chunks"),
+            event.metadata.get("no_gpu_context"),
+        )
+
+    def _on_retrieve_start(self, event: Event) -> None:
+        logger.debug(
+            "CB retrieve start: session=%s instance_id=%s num_chunks=%s",
+            event.session_id,
+            event.metadata.get("instance_id"),
+            event.metadata.get("num_chunks"),
+        )
+
+    def _on_retrieve_end(self, event: Event) -> None:
+        logger.debug(
+            "CB retrieve end: session=%s instance_id=%s num_chunks=%s success=%s",
+            event.session_id,
+            event.metadata.get("instance_id"),
+            event.metadata.get("num_chunks"),
+            event.metadata.get("success"),
+        )
+
+    def _on_store_final_start(self, event: Event) -> None:
+        logger.debug(
+            "CB store_final start: session=%s instance_id=%s num_tokens=%s",
+            event.session_id,
+            event.metadata.get("instance_id"),
+            event.metadata.get("num_tokens"),
+        )
+
+    def _on_store_final_end(self, event: Event) -> None:
+        logger.debug(
+            "CB store_final end: session=%s instance_id=%s"
+            " num_tokens=%s stored_chunks=%s success=%s",
+            event.session_id,
+            event.metadata.get("instance_id"),
+            event.metadata.get("num_tokens"),
+            event.metadata.get("stored_chunks"),
+            event.metadata.get("success"),
+        )
+
+    def _on_fingerprints_registered(self, event: Event) -> None:
+        logger.debug(
+            "CB fingerprint table: +%s chunks (%s tokens)",
+            event.metadata.get("num_chunks"),
+            event.metadata.get("num_tokens"),
+        )
+
+    def _on_chunks_evicted(self, event: Event) -> None:
+        logger.debug(
+            "CB fingerprint table: evicted %s stale chunks",
+            event.metadata.get("num_chunks"),
+        )
diff --git a/lmcache/v1/mp_observability/subscribers/logging/l1.py b/lmcache/v1/mp_observability/subscribers/logging/l1.py
new file mode 100644
index 0000000..8ffd536
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/l1.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L1 logging subscriber — debug logs for L1Manager events.
+
+Logs are emitted via Python's standard logging module.  When OpenTelemetry
+is installed, ``init_logger`` automatically attaches an OTel
+``LoggingHandler`` so records are forwarded to OTel when a
+``LoggerProvider`` is configured at startup.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class L1LoggingSubscriber(EventSubscriber):
+    """Logs L1Manager events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L1_READ_RESERVED: self._on_read_reserved,
+            EventType.L1_READ_FINISHED: self._on_read_finished,
+            EventType.L1_WRITE_RESERVED: self._on_write_reserved,
+            EventType.L1_WRITE_FINISHED: self._on_write_finished,
+            EventType.L1_WRITE_FINISHED_AND_READ_RESERVED: (
+                self._on_write_finished_and_read_reserved
+            ),
+            EventType.L1_KEYS_EVICTED: self._on_evicted,
+        }
+
+    def _on_read_reserved(self, event: Event) -> None:
+        logger.debug("L1 read reserved: %d keys", len(event.metadata["keys"]))
+
+    def _on_read_finished(self, event: Event) -> None:
+        logger.debug("L1 read finished: %d keys", len(event.metadata["keys"]))
+
+    def _on_write_reserved(self, event: Event) -> None:
+        logger.debug("L1 write reserved: %d keys", len(event.metadata["keys"]))
+
+    def _on_write_finished(self, event: Event) -> None:
+        logger.debug("L1 write finished: %d keys", len(event.metadata["keys"]))
+
+    def _on_write_finished_and_read_reserved(self, event: Event) -> None:
+        logger.debug(
+            "L1 write finished and read reserved: %d keys",
+            len(event.metadata["keys"]),
+        )
+
+    def _on_evicted(self, event: Event) -> None:
+        logger.debug("L1 eviction: %d keys", len(event.metadata["keys"]))
diff --git a/lmcache/v1/mp_observability/subscribers/logging/l2.py b/lmcache/v1/mp_observability/subscribers/logging/l2.py
new file mode 100644
index 0000000..ff16838
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/l2.py
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L2 storage logging subscriber — debug logs for L2 store/prefetch events."""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class L2LoggingSubscriber(EventSubscriber):
+    """Logs L2 store and prefetch events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L2_STORE_SUBMITTED: self._on_store_submitted,
+            EventType.L2_STORE_COMPLETED: self._on_store_completed,
+            EventType.L2_PREFETCH_LOOKUP_SUBMITTED: self._on_lookup_submitted,
+            EventType.L2_PREFETCH_LOOKUP_COMPLETED: self._on_lookup_completed,
+            EventType.L2_PREFETCH_LOAD_SUBMITTED: self._on_load_submitted,
+            EventType.L2_PREFETCH_LOAD_COMPLETED: self._on_load_completed,
+            EventType.L2_KEYS_EVICTED: self._on_evicted,
+        }
+
+    def _on_store_submitted(self, event: Event) -> None:
+        logger.debug(
+            "L2 store submitted: %d keys to adapter %d",
+            event.metadata["key_count"],
+            event.metadata["adapter_index"],
+        )
+
+    def _on_store_completed(self, event: Event) -> None:
+        logger.debug(
+            "L2 store completed: adapter %d, %d succeeded, %d failed",
+            event.metadata["adapter_index"],
+            event.metadata["succeeded_count"],
+            event.metadata["failed_count"],
+        )
+
+    def _on_lookup_submitted(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch lookup submitted: request %d, %d keys to %d adapters",
+            event.metadata["request_id"],
+            event.metadata["key_count"],
+            event.metadata["adapter_count"],
+        )
+
+    def _on_lookup_completed(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch lookup completed: request %d, %d prefix hits",
+            event.metadata["request_id"],
+            event.metadata["prefix_hit_count"],
+        )
+
+    def _on_load_submitted(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch load submitted: request %d, %d keys to %d adapters",
+            event.metadata["request_id"],
+            event.metadata["key_count"],
+            event.metadata["adapter_count"],
+        )
+
+    def _on_load_completed(self, event: Event) -> None:
+        logger.debug(
+            "L2 prefetch load completed: request %d, %d loaded, %d failed",
+            event.metadata["request_id"],
+            event.metadata["loaded_count"],
+            event.metadata["failed_count"],
+        )
+
+    def _on_evicted(self, event: Event) -> None:
+        logger.debug(
+            "L2 eviction: %d keys",
+            event.metadata["key_count"],
+        )
diff --git a/lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py b/lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py
new file mode 100644
index 0000000..65ef262
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py
@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Lookup hash file-logging subscriber.
+
+Subscribes to ``MP_LOOKUP`` events and writes lookup hash data to
+rotating JSONL files for offline analysis.  Because the EventBus
+drain thread dispatches callbacks off the hot path, no extra queue
+or worker thread is needed — file I/O happens in the EventBus
+background thread.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+import io
+import json
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+# Pattern for discovering existing log files on disk.
+_LOG_FILE_GLOB = "lookup_hashes_*.jsonl"
+
+
+def _format_timestamp(ts: float) -> str:
+    """Format a unix timestamp as a compact datetime string.
+
+    Example: 20260401_143025
+    """
+    dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+    return dt.strftime("%Y%m%d_%H%M%S")
+
+
+@dataclass
+class LookupHashLogConfig:
+    """Configuration for lookup hash file logging.
+
+    When ``output_dir`` is non-empty, chunk hashes computed during
+    lookup are written to rotating JSONL files for offline analysis.
+    """
+
+    output_dir: str = ""
+    """Directory to write lookup hash JSONL files.
+    Empty string disables logging."""
+
+    rotation_interval_sec: int = 6 * 3600
+    """Time interval in seconds before rotating to a new file
+    (default 6 hours)."""
+
+    rotation_max_size: int = 100 * 1024 * 1024
+    """Max file size in bytes before rotating even if the time
+    interval has not elapsed (default 100MB)."""
+
+    max_files: int = 100
+    """Max number of log files to keep before deleting oldest."""
+
+    @property
+    def enabled(self) -> bool:
+        """Whether lookup hash logging is enabled."""
+        return bool(self.output_dir)
+
+
+class LookupHashLoggingSubscriber(EventSubscriber):
+    """EventBus subscriber that writes lookup hashes to rotating JSONL files.
+
+    Leverages the EventBus drain thread for async I/O instead of maintaining
+    its own queue and worker.
+
+    Files rotate when either the time interval or file size limit is
+    reached, whichever comes first.  File names include a
+    human-readable timestamp, e.g.::
+
+        lookup_hashes_20260401_143025_000003.jsonl
+
+    Each JSONL line has the format::
+
+        {"timestamp": 1711929600.123, "request_id": "req-abc",
+         "model_name": "DeepSeek-V3",
+         "chunk_size": 256, "seq_len": 1024,
+         "dtypes": ["float8_e4m3fn"],
+         "shapes": [[32, 256, 128]],
+         "chunk_hashes": ["0xab...", ...]}
+    """
+
+    def __init__(self, config: LookupHashLogConfig) -> None:
+        self._config = config
+        self.output_dir = Path(config.output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # File state (only accessed from the EventBus drain thread)
+        self._current_file_size: int = 0
+        self._current_file: Optional[Path] = None
+        self._current_handle: Optional[io.TextIOWrapper] = None
+        self._current_file_opened_at: float = 0.0
+
+        # Discover existing log files so max_files limit accounts
+        # for files from previous runs.
+        self._file_list: list[Path] = sorted(
+            self.output_dir.glob(_LOG_FILE_GLOB),
+            key=lambda p: p.stat().st_mtime,
+        )
+        self._file_count: int = len(self._file_list)
+
+        logger.info(
+            "LookupHashLoggingSubscriber started: output_dir=%s, "
+            "rotation_interval=%ds, "
+            "rotation_max_size=%d, max_files=%d, "
+            "existing_files=%d",
+            self.output_dir,
+            config.rotation_interval_sec,
+            config.rotation_max_size,
+            config.max_files,
+            len(self._file_list),
+        )
+
+    # -- EventSubscriber interface -----------------------------------------
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_LOOKUP: self._on_lookup_hashes,
+        }
+
+    def shutdown(self) -> None:
+        """Close the current file handle on EventBus shutdown."""
+        if self._current_handle is not None:
+            self._current_handle.close()
+            self._current_handle = None
+        logger.info("LookupHashLoggingSubscriber closed")
+
+    # -- Callback ----------------------------------------------------------
+
+    def _on_lookup_hashes(self, event: Event) -> None:
+        """Write a lookup hash event to the current JSONL file."""
+        meta = event.metadata
+        timestamp = event.timestamp
+
+        if self._needs_rotation(timestamp):
+            self._rotate_file(timestamp)
+
+        chunk_hashes_raw = meta.get("chunk_hashes", [])
+        data = {
+            "timestamp": timestamp,
+            "request_id": meta.get("request_id", ""),
+            "model_name": meta.get("model_name", ""),
+            "chunk_size": meta.get("chunk_size", 0),
+            "seq_len": meta.get("seq_len", 0),
+            "dtypes": meta.get("dtypes", []),
+            "shapes": meta.get("shapes", []),
+            "chunk_hashes": [
+                "0x" + h.hex() if isinstance(h, bytes) else hex(h)
+                for h in chunk_hashes_raw
+            ],
+        }
+        line = json.dumps(data) + "\n"
+        if self._current_handle is not None:
+            self._current_handle.write(line)
+            self._current_handle.flush()
+            self._current_file_size = self._current_handle.tell()
+
+    # -- File rotation -----------------------------------------------------
+
+    def _needs_rotation(self, now: float) -> bool:
+        """Check if the current file needs rotation."""
+        if self._current_handle is None:
+            return True
+        elapsed = now - self._current_file_opened_at
+        if elapsed >= self._config.rotation_interval_sec:
+            return True
+        if self._current_file_size >= self._config.rotation_max_size:
+            return True
+        return False
+
+    def _rotate_file(self, now: float) -> None:
+        """Close current file and open a new one."""
+        if self._current_handle is not None:
+            self._current_handle.close()
+            self._current_handle = None
+
+        time_str = _format_timestamp(now)
+        self._current_file = (
+            self.output_dir / f"lookup_hashes_{time_str}_{self._file_count:06d}.jsonl"
+        )
+        self._current_handle = open(self._current_file, "w", encoding="utf-8")
+        self._current_file_opened_at = now
+        self._current_file_size = 0
+        self._file_count += 1
+        self._file_list.append(self._current_file)
+
+        # Enforce max file count
+        while len(self._file_list) > self._config.max_files:
+            oldest = self._file_list.pop(0)
+            try:
+                if oldest.exists():
+                    oldest.unlink()
+            except Exception as e:
+                logger.error(
+                    "Failed to delete old lookup hash file %s: %s",
+                    oldest,
+                    e,
+                )
diff --git a/lmcache/v1/mp_observability/subscribers/logging/mp_server.py b/lmcache/v1/mp_observability/subscribers/logging/mp_server.py
new file mode 100644
index 0000000..b2b0174
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/mp_server.py
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""MP Server logging subscriber — debug logs for store/retrieve/lookup events.
+
+Logs are emitted via Python's standard logging module.  When OpenTelemetry
+is installed, ``init_logger`` automatically attaches an OTel
+``LoggingHandler`` so records are forwarded to OTel when a
+``LoggerProvider`` is configured at startup.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class MPServerLoggingSubscriber(EventSubscriber):
+    """Logs MP server store/retrieve/lookup events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_STORE_START: self._on_store_start,
+            EventType.MP_STORE_END: self._on_store_end,
+            EventType.MP_RETRIEVE_START: self._on_retrieve_start,
+            EventType.MP_RETRIEVE_END: self._on_retrieve_end,
+            EventType.MP_LOOKUP_PREFETCH_START: self._on_lookup_prefetch_start,
+            EventType.MP_LOOKUP_PREFETCH_END: self._on_lookup_prefetch_end,
+            EventType.MP_VLLM_BLOCK_ALLOCATION: self._on_block_allocation,
+        }
+
+    def _on_store_start(self, event: Event) -> None:
+        logger.debug(
+            "MP store start: session=%s device=%s",
+            event.session_id,
+            event.metadata.get("device"),
+        )
+
+    def _on_store_end(self, event: Event) -> None:
+        logger.debug(
+            "MP store end: session=%s device=%s stored_count=%s",
+            event.session_id,
+            event.metadata.get("device"),
+            event.metadata.get("stored_count"),
+        )
+
+    def _on_retrieve_start(self, event: Event) -> None:
+        logger.debug(
+            "MP retrieve start: session=%s device=%s",
+            event.session_id,
+            event.metadata.get("device"),
+        )
+
+    def _on_retrieve_end(self, event: Event) -> None:
+        logger.debug(
+            "MP retrieve end: session=%s device=%s retrieved_count=%s",
+            event.session_id,
+            event.metadata.get("device"),
+            event.metadata.get("retrieved_count"),
+        )
+
+    def _on_lookup_prefetch_start(self, event: Event) -> None:
+        logger.debug(
+            "MP lookup/prefetch start: session=%s",
+            event.session_id,
+        )
+
+    def _on_lookup_prefetch_end(self, event: Event) -> None:
+        logger.debug(
+            "MP lookup/prefetch end: session=%s found_count=%s",
+            event.session_id,
+            event.metadata.get("found_count"),
+        )
+
+    def _on_block_allocation(self, event: Event) -> None:
+        records = event.metadata.get("records", [])
+        for rec in records:
+            logger.debug(
+                "vLLM block allocation: req_id=%s "
+                "new_blocks=%d new_tokens=%d "
+                "block_ids=%s",
+                rec.req_id,
+                len(rec.new_block_ids),
+                len(rec.new_token_ids),
+                rec.new_block_ids[:10],
+            )
diff --git a/lmcache/v1/mp_observability/subscribers/logging/sm.py b/lmcache/v1/mp_observability/subscribers/logging/sm.py
new file mode 100644
index 0000000..62c3b84
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/sm.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""StorageManager logging subscriber — debug logs for SM events.
+
+Logs are emitted via Python's standard logging module.  When OpenTelemetry
+is installed, ``init_logger`` automatically attaches an OTel
+``LoggingHandler`` so records are forwarded to OTel when a
+``LoggerProvider`` is configured at startup.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class SMLoggingSubscriber(EventSubscriber):
+    """Logs StorageManager events at debug level."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.SM_READ_PREFETCHED: self._on_read_prefetched,
+            EventType.SM_READ_PREFETCHED_FINISHED: self._on_read_prefetched_finished,
+            EventType.SM_WRITE_RESERVED: self._on_write_reserved,
+            EventType.SM_WRITE_FINISHED: self._on_write_finished,
+        }
+
+    def _on_read_prefetched(self, event: Event) -> None:
+        logger.debug(
+            "SM read prefetched: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
+
+    def _on_read_prefetched_finished(self, event: Event) -> None:
+        logger.debug(
+            "SM read prefetched finished: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
+
+    def _on_write_reserved(self, event: Event) -> None:
+        logger.debug(
+            "SM write reserved: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
+
+    def _on_write_finished(self, event: Event) -> None:
+        logger.debug(
+            "SM write finished: %d succeeded, %d failed",
+            len(event.metadata["succeeded_keys"]),
+            len(event.metadata["failed_keys"]),
+        )
diff --git a/lmcache/v1/mp_observability/subscribers/logging/timeout.py b/lmcache/v1/mp_observability/subscribers/logging/timeout.py
new file mode 100644
index 0000000..9926e61
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/logging/timeout.py
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Warning log for timeout errors (message + stack trace)."""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+logger = init_logger(__name__)
+
+
+class TimeoutLoggingSubscriber(EventSubscriber):
+    """Logs timeout errors at warning level with their stack trace."""
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {EventType.TIMEOUT_RAISED: self._on_timeout}
+
+    def _on_timeout(self, event: Event) -> None:
+        logger.warning(
+            "Timeout raised (%s): %s\n%s",
+            event.metadata["exception_type"],
+            event.metadata["message"],
+            event.metadata["stacktrace"],
+        )
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/__init__.py b/lmcache/v1/mp_observability/subscribers/metrics/__init__.py
new file mode 100644
index 0000000..c59898c
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/__init__.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.mp_observability.subscribers.metrics.cb_server import (
+    BlendMetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.engine import (
+    EngineMetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.event_bus import (
+    EventBusSelfMetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l0_l1_throughput import (
+    L0L1ThroughputSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l0_lifecycle import (
+    L0LifecycleSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l1 import L1MetricsSubscriber
+from lmcache.v1.mp_observability.subscribers.metrics.l1_eviction_loop import (
+    L1EvictionLoopSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l1_failures import (
+    L1FailureMetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l1_lifecycle import (
+    L1LifecycleSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l2 import L2MetricsSubscriber
+from lmcache.v1.mp_observability.subscribers.metrics.l2_failures import (
+    L2FailureMetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.l2_throughput import (
+    L2ThroughputSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.lookup import (
+    LookupMetricsSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.sm_lifecycle import (
+    SMLifecycleSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.timeout import (
+    TimeoutMetricsSubscriber,
+)
+
+__all__ = [
+    "BlendMetricsSubscriber",
+    "EngineMetricsSubscriber",
+    "EventBusSelfMetricsSubscriber",
+    "L0L1ThroughputSubscriber",
+    "L0LifecycleSubscriber",
+    "L1EvictionLoopSubscriber",
+    "L1FailureMetricsSubscriber",
+    "L1LifecycleSubscriber",
+    "L1MetricsSubscriber",
+    "L2FailureMetricsSubscriber",
+    "L2MetricsSubscriber",
+    "L2ThroughputSubscriber",
+    "LookupMetricsSubscriber",
+    "SMLifecycleSubscriber",
+    "TimeoutMetricsSubscriber",
+]
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/cb_server.py b/lmcache/v1/mp_observability/subscribers/metrics/cb_server.py
new file mode 100644
index 0000000..1fd9780
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/cb_server.py
@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Blend metrics subscriber — OTel counters for cache blending events."""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class BlendMetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters for cache blending (CB) operations.
+
+    Metrics:
+    - ``lmcache_blend.lookup_requests``              — total CB lookup calls
+    - ``lmcache_blend.lookup_requested_tokens``      — chunk-aligned tokens
+      submitted for CB lookup (denominator of the blend token-level hit
+      rate).  Sub-chunk trailing tokens are excluded because they cannot
+      hit by design.
+    - ``lmcache_blend.lookup_hit_tokens``            — tokens served by
+      blend during the lookup (numerator of the blend token-level hit
+      rate).  Equal to ``storage_hits * chunk_size``.
+    - ``lmcache_blend.lookup_fingerprint_hits``      — fingerprint table hits
+    - ``lmcache_blend.lookup_storage_hits``          — chunks confirmed in storage
+    - ``lmcache_blend.lookup_stale_chunks``          — fingerprint hits evicted as stale
+    - ``lmcache_blend.lookup_no_gpu_context_errors`` — lookup failures: no GPU context
+    - ``lmcache_blend.retrieve_requests``            — total CB retrieve calls
+    - ``lmcache_blend.retrieve_chunks``              — chunks requested for retrieval
+    - ``lmcache_blend.retrieve_failures``            — retrieves with success=False
+    - ``lmcache_blend.store_pre_computed_requests``  — total CB store_pre_computed calls
+    - ``lmcache_blend.store_pre_computed_chunks``    — chunks via store_pre_computed
+    - ``lmcache_blend.store_pre_computed_failures``  — store_pre_computed failures
+    - ``lmcache_blend.store_final_requests``         — total CB store_final calls
+    - ``lmcache_blend.store_final_chunks``           — chunks stored via store_final
+    - ``lmcache_blend.store_final_failures``         — store_final failures
+    - ``lmcache_blend.fingerprints_registered``      — chunks in fingerprint table
+    - ``lmcache_blend.chunks_evicted``               — evicted from fingerprint table
+    """
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache.blend")
+
+        self._lookup_requests = meter.create_counter(
+            "lmcache_blend.lookup_requests",
+            description="Total CB lookup requests",
+        )
+        self._lookup_requested_tokens = meter.create_counter(
+            "lmcache_blend.lookup_requested_tokens",
+            description=(
+                "Total tokens submitted for CB lookup (denominator of the "
+                "blend token-level hit rate). Only chunk-aligned tokens "
+                "are counted."
+            ),
+            unit="tokens",
+        )
+        self._lookup_hit_tokens = meter.create_counter(
+            "lmcache_blend.lookup_hit_tokens",
+            description=(
+                "Total tokens served by blend during lookup (numerator of "
+                "the blend token-level hit rate). Equal to "
+                "storage_hits * chunk_size."
+            ),
+            unit="tokens",
+        )
+        self._lookup_prefix_hit_tokens = meter.create_counter(
+            "lmcache_blend.lookup_prefix_hit_tokens",
+            description="Tokens served by blend from the prefix (L1+L2).",
+            unit="tokens",
+        )
+        self._lookup_non_prefix_hit_tokens = meter.create_counter(
+            "lmcache_blend.lookup_non_prefix_hit_tokens",
+            description="Tokens served by blend from non-prefix (shifted) chunks.",
+            unit="tokens",
+        )
+        self._lookup_segmented_prefix_hit_tokens = meter.create_counter(
+            "lmcache_blend.lookup_segmented_prefix_hit_tokens",
+            description=(
+                "Tokens served by blend from the segmented-prefix tail "
+                "(post-gap same-position chunks reused via the prefix leg)."
+            ),
+            unit="tokens",
+        )
+        self._lookup_fingerprint_hits = meter.create_counter(
+            "lmcache_blend.lookup_fingerprint_hits",
+            description="Chunks matched by local fingerprint table",
+        )
+        self._lookup_storage_hits = meter.create_counter(
+            "lmcache_blend.lookup_storage_hits",
+            description="Chunks confirmed present in storage after prefetch",
+        )
+        self._lookup_stale_chunks = meter.create_counter(
+            "lmcache_blend.lookup_stale_chunks",
+            description="Fingerprint hits evicted as stale (not in storage)",
+        )
+        self._lookup_no_gpu_ctx_errors = meter.create_counter(
+            "lmcache_blend.lookup_no_gpu_context_errors",
+            description="Lookup failures due to missing GPU context",
+        )
+        self._retrieve_requests = meter.create_counter(
+            "lmcache_blend.retrieve_requests",
+            description="Total CB retrieve requests",
+        )
+        self._retrieve_chunks = meter.create_counter(
+            "lmcache_blend.retrieve_chunks",
+            description="Total chunks requested for CB retrieval",
+        )
+        self._retrieve_failures = meter.create_counter(
+            "lmcache_blend.retrieve_failures",
+            description="CB retrieve operations that returned success=False",
+        )
+        self._store_pre_computed_requests = meter.create_counter(
+            "lmcache_blend.store_pre_computed_requests",
+            description="Total CB store_pre_computed requests",
+        )
+        self._store_pre_computed_chunks = meter.create_counter(
+            "lmcache_blend.store_pre_computed_chunks",
+            description="Chunks stored via CB store_pre_computed",
+        )
+        self._store_pre_computed_failures = meter.create_counter(
+            "lmcache_blend.store_pre_computed_failures",
+            description="CB store_pre_computed failures",
+        )
+        self._store_final_requests = meter.create_counter(
+            "lmcache_blend.store_final_requests",
+            description="Total CB store_final requests",
+        )
+        self._store_final_chunks = meter.create_counter(
+            "lmcache_blend.store_final_chunks",
+            description="Chunks stored via CB store_final",
+        )
+        self._store_final_failures = meter.create_counter(
+            "lmcache_blend.store_final_failures",
+            description="CB store_final failures",
+        )
+        self._fingerprints_registered = meter.create_counter(
+            "lmcache_blend.fingerprints_registered",
+            description="Chunks indexed into the fingerprint table",
+        )
+        self._chunks_evicted = meter.create_counter(
+            "lmcache_blend.chunks_evicted",
+            description="Stale chunks evicted from the fingerprint table",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        """Return the mapping of event types to handler callbacks."""
+        return {
+            EventType.CB_LOOKUP_START: self._on_lookup_start,
+            EventType.CB_LOOKUP_END: self._on_lookup_end,
+            EventType.CB_RETRIEVE_START: self._on_retrieve_start,
+            EventType.CB_RETRIEVE_END: self._on_retrieve_end,
+            EventType.CB_STORE_PRE_COMPUTED_START: self._on_store_pre_start,
+            EventType.CB_STORE_PRE_COMPUTED_END: self._on_store_pre_end,
+            EventType.CB_STORE_FINAL_START: self._on_store_final_start,
+            EventType.CB_STORE_FINAL_END: self._on_store_final_end,
+            EventType.CB_FINGERPRINTS_REGISTERED: self._on_fingerprints_registered,
+            EventType.CB_CHUNKS_EVICTED: self._on_chunks_evicted,
+        }
+
+    def _on_lookup_start(self, event: Event) -> None:
+        self._lookup_requests.add(1)
+
+    def _on_lookup_end(self, event: Event) -> None:
+        self._lookup_requested_tokens.add(event.metadata["requested_tokens"])
+        self._lookup_hit_tokens.add(event.metadata["hit_tokens"])
+        self._lookup_prefix_hit_tokens.add(event.metadata.get("prefix_hit_tokens", 0))
+        self._lookup_non_prefix_hit_tokens.add(
+            event.metadata.get("non_prefix_hit_tokens", 0)
+        )
+        self._lookup_segmented_prefix_hit_tokens.add(
+            event.metadata.get("segmented_prefix_hit_tokens", 0)
+        )
+        self._lookup_fingerprint_hits.add(event.metadata["fingerprint_hits"])
+        self._lookup_storage_hits.add(event.metadata["storage_hits"])
+        self._lookup_stale_chunks.add(event.metadata["stale_chunks"])
+        if event.metadata.get("no_gpu_context"):
+            self._lookup_no_gpu_ctx_errors.add(1)
+
+    def _on_retrieve_start(self, event: Event) -> None:
+        self._retrieve_requests.add(1)
+        self._retrieve_chunks.add(event.metadata["num_chunks"])
+
+    def _on_retrieve_end(self, event: Event) -> None:
+        if not event.metadata.get("success", True):
+            self._retrieve_failures.add(1)
+
+    def _on_store_pre_start(self, event: Event) -> None:
+        self._store_pre_computed_requests.add(1)
+
+    def _on_store_pre_end(self, event: Event) -> None:
+        self._store_pre_computed_chunks.add(event.metadata["stored_chunks"])
+        if not event.metadata.get("success", True):
+            self._store_pre_computed_failures.add(1)
+
+    def _on_store_final_start(self, event: Event) -> None:
+        self._store_final_requests.add(1)
+
+    def _on_store_final_end(self, event: Event) -> None:
+        self._store_final_chunks.add(event.metadata["stored_chunks"])
+        if not event.metadata.get("success", True):
+            self._store_final_failures.add(1)
+
+    def _on_fingerprints_registered(self, event: Event) -> None:
+        self._fingerprints_registered.add(event.metadata["num_chunks"])
+
+    def _on_chunks_evicted(self, event: Event) -> None:
+        self._chunks_evicted.add(event.metadata["num_chunks"])
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/engine.py b/lmcache/v1/mp_observability/subscribers/metrics/engine.py
new file mode 100644
index 0000000..a526817
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/engine.py
@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Worker-side engine metrics subscriber.
+
+Emits counters tied to what the MP server delivers back to each vLLM
+worker.  Today the only metric is ``lmcache_mp.num_chunks_loaded``;
+future worker-scoped counters (e.g., bytes loaded, blocks touched) would
+land here too.
+"""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class EngineMetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters tied to the MP server's retrieve path
+    (worker-side; ``worker_id`` = vLLM worker instance id).
+
+    Metrics:
+    - ``lmcache_mp.num_chunks_loaded`` — chunks loaded from LMCache into
+      the engine via ``retrieve()`` (attrs: ``worker_id``, ``model_name``,
+      ``cache_salt``).
+
+    ``worker_id`` on this metric names the vLLM **worker** instance id and
+    is distinct from any scheduler-scoped ``scheduler_id`` attribute used
+    elsewhere — the two IDs come from different vLLM processes and should
+    not be cross-joined on dashboards.
+    """
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache_mp.engine")
+        self._num_chunks_loaded = meter.create_counter(
+            "lmcache_mp.num_chunks_loaded",
+            description=(
+                "Total number of LMCache chunks loaded into the engine "
+                "(summed across all retrieve operations)."
+            ),
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_RETRIEVE_END: self._on_retrieve_end,
+        }
+
+    def _on_retrieve_end(self, event: Event) -> None:
+        retrieved_count = int(event.metadata.get("retrieved_count", 0))
+        if retrieved_count <= 0:
+            return
+        # MP_RETRIEVE_END carries the worker's instance_id under the
+        # ``engine_id`` key; re-emit as ``worker_id`` so the attribute
+        # name disambiguates from any scheduler-side id used elsewhere.
+        attrs: dict[str, str] = {}
+        engine_id = event.metadata.get("engine_id")
+        if engine_id is not None:
+            attrs["worker_id"] = str(engine_id)
+        model_name = event.metadata.get("model_name")
+        if model_name is not None:
+            attrs["model_name"] = str(model_name)
+        cache_salt = event.metadata.get("cache_salt")
+        if cache_salt is not None:
+            attrs["cache_salt"] = str(cache_salt)
+        self._num_chunks_loaded.add(retrieved_count, attributes=attrs)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/event_bus.py b/lmcache/v1/mp_observability/subscribers/metrics/event_bus.py
new file mode 100644
index 0000000..42b9f0d
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/event_bus.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""EventBus self-metrics subscriber.
+
+Surfaces two metrics describing the EventBus's own health (per #3108):
+
+- ``lmcache_mp.event_bus.dropped_events_total`` (observable counter)
+- ``lmcache_mp.event_bus.subscriber_exceptions`` (observable counter,
+  attr ``subscriber_name``)
+
+Unlike the other subscribers in this package, these metrics are not
+driven by events — they observe bus state via the ``EventBus`` accessors
+and report on every OTel scrape.  ``get_subscriptions`` therefore returns
+an empty mapping.
+"""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import EventType
+from lmcache.v1.mp_observability.event_bus import (
+    EventBus,
+    EventCallback,
+    EventSubscriber,
+)
+
+
+class EventBusSelfMetricsSubscriber(EventSubscriber):
+    """Registers OTel observers for EventBus health metrics."""
+
+    def __init__(self, bus: EventBus) -> None:
+        meter = metrics.get_meter("lmcache.event_bus")
+
+        meter.create_observable_counter(
+            "lmcache_mp.event_bus.dropped_events_total",
+            callbacks=[lambda _o: [metrics.Observation(bus.dropped_events_count())]],
+            description=(
+                "Cumulative events dropped because the EventBus queue was "
+                "at max_queue_size."
+            ),
+        )
+        meter.create_observable_counter(
+            "lmcache_mp.event_bus.subscriber_exceptions",
+            callbacks=[
+                lambda _o: [
+                    metrics.Observation(count, {"subscriber_name": name})
+                    for name, count in bus.subscriber_exception_counts().items()
+                ]
+            ],
+            description=(
+                "Cumulative exceptions raised by subscriber callbacks "
+                "during EventBus dispatch, tagged by ``subscriber_name``."
+            ),
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {}
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l0_l1_throughput.py b/lmcache/v1/mp_observability/subscribers/metrics/l0_l1_throughput.py
new file mode 100644
index 0000000..ded9ebb
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l0_l1_throughput.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L0↔L1 throughput metrics subscriber.
+
+Emits two OTel histograms in GB/s, labeled by ``engine_id``, ``device``,
+and ``model_name``:
+  - ``lmcache_mp.l0_l1_store_throughput``  — GPU→CPU (L0→L1) store
+  - ``lmcache_mp.l0_l1_load_throughput``   — CPU→GPU (L1→L0) load
+
+Implementation:
+  - Correlates ``MP_STORE_START`` → ``MP_STORE_END`` and
+    ``MP_RETRIEVE_START`` → ``MP_RETRIEVE_END`` pairs by the compound key
+    ``(session_id, device)``.  ``session_id`` alone is not sufficient
+    because one MP server process serves multiple vLLM workers, so TP/PP
+    replicas of the same request fire concurrent START/END pairs on
+    different GPUs.
+  - START/END events fire on the GPU cupy stream (``publish_on_stream``),
+    so their timestamps reflect true GPU-stream time for the D2H/H2D
+    copies — not Python/lock overhead.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class L0L1ThroughputSubscriber(EventSubscriber):
+    """Records L0↔L1 throughput by correlating MP_*_START→MP_*_END pairs."""
+
+    def __init__(self) -> None:
+        # (session_id, device) -> t_start.
+        # Compound key avoids collisions when one MP server
+        # handles the same request_id from multiple GPUs (TP/PP).
+        self._pending_store: dict[tuple[str, str], float] = {}
+        self._pending_load: dict[tuple[str, str], float] = {}
+
+        meter = metrics.get_meter("lmcache_mp.perf")
+        self._store_hist = meter.create_histogram(
+            "lmcache_mp.l0_l1_store_throughput",
+            description=(
+                "Histogram of L0→L1 (GPU→CPU) store throughput in GB/s, "
+                "measured per request as total_bytes / (end_ts - start_ts) "
+                "on the GPU cupy stream."
+            ),
+            unit="GB/s",
+        )
+        self._load_hist = meter.create_histogram(
+            "lmcache_mp.l0_l1_load_throughput",
+            description=(
+                "Histogram of L1→L0 (CPU→GPU) load throughput in GB/s, "
+                "measured per request as total_bytes / (end_ts - start_ts) "
+                "on the GPU cupy stream."
+            ),
+            unit="GB/s",
+        )
+
+    # -- EventSubscriber interface -----------------------------------------
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_STORE_START: self._on_store_start,
+            EventType.MP_STORE_END: self._on_store_end,
+            EventType.MP_RETRIEVE_START: self._on_retrieve_start,
+            EventType.MP_RETRIEVE_END: self._on_retrieve_end,
+        }
+
+    # -- Store path (L0→L1, GPU→CPU) ---------------------------------------
+
+    def _on_store_start(self, event: Event) -> None:
+        key = self._correlation_key(event)
+        if key is not None:
+            self._pending_store[key] = event.timestamp
+
+    def _on_store_end(self, event: Event) -> None:
+        self._record(
+            event=event,
+            pending=self._pending_store,
+            hist=self._store_hist,
+        )
+
+    # -- Retrieve path (L1→L0, CPU→GPU) ------------------------------------
+
+    def _on_retrieve_start(self, event: Event) -> None:
+        key = self._correlation_key(event)
+        if key is not None:
+            self._pending_load[key] = event.timestamp
+
+    def _on_retrieve_end(self, event: Event) -> None:
+        self._record(
+            event=event,
+            pending=self._pending_load,
+            hist=self._load_hist,
+        )
+
+    # -- Core computation --------------------------------------------------
+
+    @staticmethod
+    def _correlation_key(event: Event) -> tuple[str, str] | None:
+        """Build the ``(session_id, device)`` correlation key.
+
+        Returns ``None`` if either field is missing — such events cannot
+        be paired safely and are dropped.
+        """
+        device = event.metadata.get("device")
+        if not event.session_id or device is None:
+            return None
+        return (event.session_id, str(device))
+
+    @classmethod
+    def _record(
+        cls,
+        event: Event,
+        pending: dict[tuple[str, str], float],
+        hist: Any,
+    ) -> None:
+        key = cls._correlation_key(event)
+        if key is None:
+            return
+        t_start = pending.pop(key, None)
+        if t_start is None:
+            return  # No matching START event
+
+        total_bytes = event.metadata.get("total_bytes", 0)
+        if total_bytes <= 0:
+            return
+
+        dt = event.timestamp - t_start
+        if dt <= 0:
+            return
+
+        engine_id = event.metadata.get("engine_id")
+        model_name = event.metadata.get("model_name")
+        attrs: dict[str, Any] = {"device": key[1]}
+        if engine_id is not None:
+            attrs["engine_id"] = str(engine_id)
+        if model_name is not None:
+            attrs["model_name"] = str(model_name)
+
+        hist.record(total_bytes / dt / 1e9, attributes=attrs)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l0_lifecycle.py b/lmcache/v1/mp_observability/subscribers/metrics/l0_lifecycle.py
new file mode 100644
index 0000000..4024e29
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l0_lifecycle.py
@@ -0,0 +1,290 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L0 (GPU) KV cache metrics subscriber — OTel histograms for block lifecycle.
+
+Subscribes to ``MP_VLLM_BLOCK_ALLOCATION`` and ``MP_VLLM_END_SESSION`` events
+and maintains a shadow map of physical GPU block IDs to detect cache hits and
+evictions.
+
+State machine per block:
+
+  1. Block first seen in allocation → ACTIVE (owned by req_id)
+  2. Same block, same tokens, same req_id → ignore (decode continuation)
+  3. Same block, same tokens, different req_id, block ACTIVE →
+     prefix sharing, just add req_id as co-owner
+  4. Same block, same tokens, block RELEASED → true cache hit (reuse),
+     record access, transition to ACTIVE
+  5. Same block, different tokens → eviction detected,
+     emit metrics, start fresh
+  6. END_SESSION(req_id) → remove req_id from all blocks it owns.
+     If a block has no remaining owners → RELEASED.
+
+Limitations:
+  - ``BlockAllocationRecord`` only reports **new** block IDs per request per
+    scheduler step, not all blocks a request uses.  Blocks reused via prefix
+    cache are invisible after initial allocation.  This means the subscriber
+    only tracks a subset of physical blocks and will undercount evictions
+    compared to vLLM's internal ``KVCacheMetricsCollector``.
+  - Eviction is detected at **reallocation** time, not at the exact moment
+    vLLM frees the block.  Lifetime measurements include the gap between
+    eviction and reallocation.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import deque
+from dataclasses import dataclass, field
+from enum import Enum
+import random
+import time
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+# Maximum number of recent access timestamps kept per block (ring buffer).
+_MAX_ACCESS_HISTORY = 4
+
+
+class _BlockStatus(Enum):
+    ACTIVE = "active"  # Owned by at least one live request.
+    RELEASED = "released"  # All owning requests have ended.
+
+
+@dataclass
+class _L0BlockState:
+    """Per-block lifecycle state in the shadow map."""
+
+    instance_id: int
+    model_name: str
+    token_ids: list[int]
+    owners: set[str]  # Set of req_ids currently using this block.
+    status: _BlockStatus
+    alloc_time: float
+    last_access_time: float
+    access_history: deque[float] = field(
+        default_factory=lambda: deque(maxlen=_MAX_ACCESS_HISTORY)
+    )
+
+
+class L0LifecycleSubscriber(EventSubscriber):
+    """Tracks GPU (L0) KV cache block lifecycle via shadow monitoring.
+
+    Metrics (all histograms, in seconds):
+    - ``lmcache_mp.l0_block_lifetime``
+    - ``lmcache_mp.l0_block_idle_before_evict``
+    - ``lmcache_mp.l0_block_reuse_gap``
+
+    Parameters:
+        sample_rate: Fraction of blocks to track (0, 1.0].  Default 0.01
+            (1%) matches vLLM's default.
+    """
+
+    def __init__(self, sample_rate: float = 0.01) -> None:
+        assert 0 < sample_rate <= 1.0, (
+            f"sample_rate must be in (0, 1.0], got {sample_rate}"
+        )
+        self._sample_rate = sample_rate
+
+        # Shadow map: (instance_id, block_id) -> lifecycle state.
+        self._shadow: dict[tuple[int, int], _L0BlockState] = {}
+        # Set of (instance_id, block_id) we decided NOT to sample.
+        self._skipped: set[tuple[int, int]] = set()
+        # Reverse index: req_id -> set of (instance_id, block_id) owned.
+        self._req_blocks: dict[str, set[tuple[int, int]]] = {}
+
+        meter = metrics.get_meter("lmcache.l0")
+        self._lifetime_hist = meter.create_histogram(
+            "lmcache_mp.l0_block_lifetime",
+            description=(
+                "Histogram of GPU KV cache block lifetime from "
+                "allocation to eviction (seconds)."
+            ),
+            unit="s",
+        )
+        self._idle_hist = meter.create_histogram(
+            "lmcache_mp.l0_block_idle_before_evict",
+            description=(
+                "Histogram of idle time before GPU KV cache block eviction (seconds)."
+            ),
+            unit="s",
+        )
+        self._reuse_gap_hist = meter.create_histogram(
+            "lmcache_mp.l0_block_reuse_gap",
+            description=(
+                "Histogram of time gaps between consecutive GPU KV "
+                "cache block accesses (seconds)."
+            ),
+            unit="s",
+        )
+
+    # -- EventSubscriber interface -----------------------------------------
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_VLLM_BLOCK_ALLOCATION: self._on_block_allocation,
+            EventType.MP_VLLM_END_SESSION: self._on_end_session,
+        }
+
+    # -- Event handlers ----------------------------------------------------
+
+    def _on_block_allocation(self, event: Event) -> None:
+        """Process a batch of ``BlockAllocationRecord`` from vLLM."""
+        instance_id = event.metadata.get("instance_id", 0)
+        model_name = event.metadata.get("model_name", "")
+        records = event.metadata.get("records", [])
+        now = event.timestamp or time.time()
+
+        for record in records:
+            self._process_record(instance_id, model_name, record, now)
+
+    def _on_end_session(self, event: Event) -> None:
+        """Handle request completion — release blocks owned by this request."""
+        req_id = event.metadata.get("request_id", "")
+        if not req_id:
+            return
+
+        block_keys = self._req_blocks.pop(req_id, set())
+        for block_key in block_keys:
+            state = self._shadow.get(block_key)
+            if state is None:
+                continue
+            state.owners.discard(req_id)
+            if not state.owners:
+                state.status = _BlockStatus.RELEASED
+
+    # -- Record processing -------------------------------------------------
+
+    def _process_record(
+        self, instance_id: int, model_name: str, record: object, now: float
+    ) -> None:
+        """Process a single BlockAllocationRecord."""
+        req_id: str = record.req_id  # type: ignore[attr-defined]
+        block_ids: list[int] = record.new_block_ids  # type: ignore[attr-defined]
+        token_ids: list[int] = record.new_token_ids  # type: ignore[attr-defined]
+
+        if not block_ids:
+            return
+
+        num_blocks = len(block_ids)
+        block_size = (
+            (len(token_ids) + num_blocks - 1) // num_blocks if num_blocks else 0
+        )
+
+        for i, block_id in enumerate(block_ids):
+            start = i * block_size
+            end = min(start + block_size, len(token_ids))
+            chunk_tokens = token_ids[start:end]
+            if not chunk_tokens:
+                continue
+            self._process_block(
+                instance_id, model_name, block_id, chunk_tokens, req_id, now
+            )
+
+    def _process_block(
+        self,
+        instance_id: int,
+        model_name: str,
+        block_id: int,
+        token_ids: list[int],
+        req_id: str,
+        now: float,
+    ) -> None:
+        """Update shadow map for a single physical block."""
+        block_key = (instance_id, block_id)
+        existing = self._shadow.get(block_key)
+
+        if existing is None:
+            # Block not in shadow map.
+            if block_key in self._skipped:
+                return
+
+            if not self._should_sample():
+                self._skipped.add(block_key)
+                return
+
+            # New allocation — start tracking.
+            self._shadow[block_key] = _L0BlockState(
+                instance_id=instance_id,
+                model_name=model_name,
+                token_ids=token_ids,
+                owners={req_id},
+                status=_BlockStatus.ACTIVE,
+                alloc_time=now,
+                last_access_time=now,
+            )
+            self._req_blocks.setdefault(req_id, set()).add(block_key)
+            return
+
+        # Block exists in shadow map.
+        if existing.token_ids == token_ids:
+            # Same content.
+            if req_id in existing.owners:
+                # Case 2: Same request reporting same block again (decode
+                # continuation or redundant report). Ignore.
+                return
+
+            if existing.status == _BlockStatus.ACTIVE:
+                # Case 3: Prefix sharing — another request is using this
+                # block while original request(s) still active. Not a reuse.
+                existing.owners.add(req_id)
+                self._req_blocks.setdefault(req_id, set()).add(block_key)
+            else:
+                # Case 4: Block was RELEASED, now reused with same content.
+                # This is a true cache hit.
+                existing.owners.add(req_id)
+                existing.status = _BlockStatus.ACTIVE
+                existing.last_access_time = now
+                existing.access_history.append(now)
+                self._req_blocks.setdefault(req_id, set()).add(block_key)
+        else:
+            # Case 5: Different content — eviction detected.
+            self._emit_eviction_metrics(existing, now)
+
+            # Clear old owners from reverse index.
+            for old_req in existing.owners:
+                block_set = self._req_blocks.get(old_req)
+                if block_set:
+                    block_set.discard(block_key)
+
+            # Start fresh.
+            self._shadow[block_key] = _L0BlockState(
+                instance_id=instance_id,
+                model_name=model_name,
+                token_ids=token_ids,
+                owners={req_id},
+                status=_BlockStatus.ACTIVE,
+                alloc_time=now,
+                last_access_time=now,
+            )
+            self._req_blocks.setdefault(req_id, set()).add(block_key)
+
+    # -- Metrics emission --------------------------------------------------
+
+    def _emit_eviction_metrics(self, state: _L0BlockState, now: float) -> None:
+        """Record histogram observations for an evicted block."""
+        lifetime = now - state.alloc_time
+        idle_time = now - state.last_access_time
+        attrs = {
+            "instance_id": str(state.instance_id),
+            "model_name": state.model_name,
+        }
+
+        self._lifetime_hist.record(lifetime, attrs)
+        self._idle_hist.record(idle_time, attrs)
+
+        # Reuse gaps from access history.
+        history = list(state.access_history)
+        for i in range(1, len(history)):
+            gap = history[i] - history[i - 1]
+            self._reuse_gap_hist.record(gap, attrs)
+
+    # -- Sampling ----------------------------------------------------------
+
+    def _should_sample(self) -> bool:
+        return random.random() < self._sample_rate
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l1.py b/lmcache/v1/mp_observability/subscribers/metrics/l1.py
new file mode 100644
index 0000000..ee155ce
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l1.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L1 metrics subscriber — OTel counters for L1Manager events."""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.subscribers.metrics.utils import (
+    emit_salt_counts,
+    group_by_salt,
+)
+
+
+class L1MetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters for L1Manager operations.
+
+    Metric parity with the old ``L1ManagerStatsLogger``:
+    - ``lmcache_mp.l1_read``    — chunks read from L1
+    - ``lmcache_mp.l1_write``   — chunks written to L1
+    - ``lmcache_mp.l1_evicted`` — chunks evicted from L1
+    """
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache.l1")
+        self._read_counter = meter.create_counter(
+            "lmcache_mp.l1_read",
+            description="Total chunks read from L1",
+            unit="chunks",
+        )
+        self._write_counter = meter.create_counter(
+            "lmcache_mp.l1_write",
+            description="Total chunks written to L1",
+            unit="chunks",
+        )
+        self._evicted_counter = meter.create_counter(
+            "lmcache_mp.l1_evicted",
+            description="Total chunks evicted from L1",
+            unit="chunks",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L1_READ_FINISHED: self._on_read_finished,
+            EventType.L1_WRITE_FINISHED: self._on_write_finished,
+            EventType.L1_WRITE_FINISHED_AND_READ_RESERVED: self._on_write_finished,
+            EventType.L1_KEYS_EVICTED: self._on_evicted,
+        }
+
+    def _on_read_finished(self, event: Event) -> None:
+        emit_salt_counts(self._read_counter, group_by_salt(event.metadata["keys"]))
+
+    def _on_write_finished(self, event: Event) -> None:
+        emit_salt_counts(self._write_counter, group_by_salt(event.metadata["keys"]))
+
+    def _on_evicted(self, event: Event) -> None:
+        emit_salt_counts(self._evicted_counter, group_by_salt(event.metadata["keys"]))
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l1_eviction_loop.py b/lmcache/v1/mp_observability/subscribers/metrics/l1_eviction_loop.py
new file mode 100644
index 0000000..40dbbb3
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l1_eviction_loop.py
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L1 eviction-loop metrics subscriber — OTel instruments for L1EvictionController."""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class L1EvictionLoopSubscriber(EventSubscriber):
+    """Maintains OTel counters for the L1 eviction loop.
+
+    Metrics:
+    - ``lmcache_mp.l1_eviction_loop_ticks`` — every loop iteration.
+    - ``lmcache_mp.l1_eviction_loop_triggered`` — iterations where
+      ``usage >= watermark`` and the eviction policy ran.
+
+    The two counters distinguish "loop is alive" from "eviction fired",
+    which matters for short benchmarks that complete faster than the 1Hz
+    polling rate.  Current L1 fullness is exposed separately as the
+    ``lmcache_mp.l1_memory_usage_bytes`` and ``lmcache_mp.l1_usage_ratio``
+    observable gauges registered in :class:`L1Manager`.
+    """
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache.l1")
+        self._ticks = meter.create_counter(
+            "lmcache_mp.l1_eviction_loop_ticks",
+            description="L1 eviction-loop iterations (every cycle)",
+        )
+        self._triggered = meter.create_counter(
+            "lmcache_mp.l1_eviction_loop_triggered",
+            description="L1 eviction-loop iterations where the policy ran",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {EventType.L1_EVICTION_LOOP_TICK: self._on_tick}
+
+    def _on_tick(self, event: Event) -> None:
+        self._ticks.add(1)
+        if event.metadata.get("triggered", False):
+            self._triggered.add(1)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l1_failures.py b/lmcache/v1/mp_observability/subscribers/metrics/l1_failures.py
new file mode 100644
index 0000000..d4c8896
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l1_failures.py
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L1 failure metrics subscriber — OTel counters for L1 allocation and read failures.
+
+These counters cover the health-monitoring surface for L1 (see LM-291):
+
+- ``lmcache_mp.l1_allocation_failure`` — L1 memory allocation failures (OOM)
+  during reserve_write. Tagged by ``during`` (``l1_store`` vs ``l2_prefetch``)
+  to distinguish user-initiated stores from prefetch-triggered allocations.
+- ``lmcache_mp.l1_read_failure`` — L1 reserve_read failures. This is an
+  anomaly counter, not a cache-miss counter: in MP mode ``reserve_read`` is
+  only called after a successful lookup, so any failure here indicates a
+  lookup/reserve race or unexpected eviction and should stay near zero in
+  healthy operation.
+
+All counters carry ``model_name`` extracted from each ``ObjectKey`` so operators
+can slice by model on the Prometheus ``/metrics`` endpoint.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import Counter
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class L1FailureMetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters for L1 allocation and read failures."""
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache_mp.health")
+        self._allocation_counter = meter.create_counter(
+            "lmcache_mp.l1_allocation_failure",
+            description=(
+                "Count of L1 memory allocation failures (OOM) during "
+                "reserve_write. Tagged by ``during`` = l1_store | l2_prefetch "
+                "and ``model_name``."
+            ),
+            unit="chunks",
+        )
+        self._read_counter = meter.create_counter(
+            "lmcache_mp.l1_read_failure",
+            description=(
+                "Count of L1 reserve_read failures (post-lookup anomaly). "
+                "Tagged by ``during`` = l2_store | l1_retrieve, ``reason`` = "
+                "not_found | write_locked, and ``model_name``. Should stay "
+                "near zero in healthy operation; non-zero indicates a "
+                "lookup/reserve race or unexpected eviction."
+            ),
+            unit="chunks",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L1_ALLOCATION_FAILED: self._on_allocation_failed,
+            EventType.L1_READ_FAILED: self._on_read_failed,
+        }
+
+    def _on_allocation_failed(self, event: Event) -> None:
+        during: str = event.metadata["during"]
+        keys: list[ObjectKey] = event.metadata["keys"]
+        for model_name, count in Counter(k.model_name for k in keys).items():
+            self._allocation_counter.add(
+                count,
+                {"during": during, "model_name": model_name},
+            )
+
+    def _on_read_failed(self, event: Event) -> None:
+        during: str = event.metadata["during"]
+        reason: str = event.metadata["reason"]
+        keys: list[ObjectKey] = event.metadata["keys"]
+        for model_name, count in Counter(k.model_name for k in keys).items():
+            self._read_counter.add(
+                count,
+                {
+                    "during": during,
+                    "reason": reason,
+                    "model_name": model_name,
+                },
+            )
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l1_lifecycle.py b/lmcache/v1/mp_observability/subscribers/metrics/l1_lifecycle.py
new file mode 100644
index 0000000..dd87116
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l1_lifecycle.py
@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L1 chunk lifecycle subscriber — OTel histograms for L1 chunk lifecycle.
+
+Separated from L1MetricsSubscriber (counters) so that users can enable/disable
+lifecycle tracking independently.  The shadow map and sampling overhead are
+non-negligible, so this subscriber should only be registered when lifecycle
+metrics are needed.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import Any
+import time
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+@dataclass
+class _L1ChunkState:
+    """Per-chunk lifecycle state in the shadow map."""
+
+    alloc_time: float
+    last_access_time: float
+
+
+class L1LifecycleSubscriber(EventSubscriber):
+    """Tracks L1 chunk lifecycle via shadow monitoring.
+
+    Histograms (chunk lifecycle):
+    - ``lmcache_mp.l1_chunk_lifetime`` — allocation to eviction
+    - ``lmcache_mp.l1_chunk_idle_before_evict`` — last access to eviction
+    - ``lmcache_mp.l1_chunk_reuse_gap`` — gap between consecutive touches
+    - ``lmcache_mp.l1_chunk_evict_reuse_gap`` — eviction to
+      next reuse (capped at ``max_evict_reuse_wait``)
+
+    Parameters:
+        sample_rate: Fraction of chunks to track (0, 1.0].  Default 0.01 (1%).
+        max_evict_reuse_wait: Maximum seconds to track an evicted chunk
+            waiting for reuse.  Default 300 s (5 min).
+    """
+
+    def __init__(
+        self,
+        sample_rate: float = 0.01,
+        max_evict_reuse_wait: float = 300.0,
+    ) -> None:
+        assert 0 < sample_rate <= 1.0, (
+            f"sample_rate must be in (0, 1.0], got {sample_rate}"
+        )
+        self._sample_rate = sample_rate
+        self._max_evict_reuse_wait = max_evict_reuse_wait
+        # Deterministic sampling via hash: hash(key) % _SAMPLE_PRIME < threshold.
+        # O(1) memory, no set growth, same key always gets the same decision.
+        self._sample_prime = 1_000_003
+        self._sample_threshold = int(sample_rate * self._sample_prime)
+        meter = metrics.get_meter("lmcache.l1")
+        self._lifetime_hist = meter.create_histogram(
+            "lmcache_mp.l1_chunk_lifetime",
+            description=(
+                "Histogram of L1 chunk lifetime from allocation to eviction (seconds)."
+            ),
+            unit="s",
+        )
+        self._idle_hist = meter.create_histogram(
+            "lmcache_mp.l1_chunk_idle_before_evict",
+            description=("Histogram of idle time before L1 chunk eviction (seconds)."),
+            unit="s",
+        )
+        self._reuse_gap_hist = meter.create_histogram(
+            "lmcache_mp.l1_chunk_reuse_gap",
+            description=(
+                "Histogram of time gaps between consecutive "
+                "touches (write or read) of the same L1 chunk (seconds)."
+            ),
+            unit="s",
+        )
+        self._evict_reuse_gap_hist = meter.create_histogram(
+            "lmcache_mp.l1_chunk_evict_reuse_gap",
+            description=(
+                "Histogram of time from L1 chunk eviction to "
+                "next reuse.  Capped at max_evict_reuse_wait."
+            ),
+            unit="s",
+        )
+
+        # Shadow map: key -> chunk lifecycle state (live chunks).
+        self._shadow: dict[Any, _L1ChunkState] = {}
+        # Evicted map: key -> eviction timestamp (waiting for reuse).
+        self._evicted_at: dict[Any, float] = {}
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L1_READ_FINISHED: self._on_read_finished,
+            EventType.L1_WRITE_FINISHED: self._on_write_finished,
+            EventType.L1_WRITE_FINISHED_AND_READ_RESERVED: self._on_write_finished,
+            EventType.L1_KEYS_EVICTED: self._on_evicted,
+        }
+
+    def _on_read_finished(self, event: Event) -> None:
+        now = event.timestamp or time.time()
+        for key in event.metadata["keys"]:
+            state = self._shadow.get(key)
+            if state is not None:
+                self._reuse_gap_hist.record(now - state.last_access_time)
+                state.last_access_time = now
+
+    def _on_write_finished(self, event: Event) -> None:
+        now = event.timestamp or time.time()
+        for key in event.metadata["keys"]:
+            # Check if this is a reuse of an evicted chunk.
+            evict_time = self._evicted_at.pop(key, None)
+            if evict_time is not None:
+                gap = min(now - evict_time, self._max_evict_reuse_wait)
+                self._evict_reuse_gap_hist.record(gap)
+
+            state = self._shadow.get(key)
+            if state is not None:
+                # Re-write of existing chunk counts as a touch.
+                self._reuse_gap_hist.record(now - state.last_access_time)
+                self._shadow[key] = _L1ChunkState(
+                    alloc_time=now,
+                    last_access_time=now,
+                )
+            else:
+                # First time seeing this key — deterministic sample check.
+                if not self._should_sample(key):
+                    continue
+                self._shadow[key] = _L1ChunkState(
+                    alloc_time=now,
+                    last_access_time=now,
+                )
+        self._sweep_stale_evictions(now)
+
+    def _on_evicted(self, event: Event) -> None:
+        now = event.timestamp or time.time()
+        for key in event.metadata["keys"]:
+            state = self._shadow.pop(key, None)
+            if state is not None:
+                self._lifetime_hist.record(now - state.alloc_time)
+                self._idle_hist.record(now - state.last_access_time)
+                # Start tracking eviction-to-reuse gap (only for sampled).
+                self._evicted_at[key] = now
+        self._sweep_stale_evictions(now)
+
+    def _should_sample(self, key: object) -> bool:
+        return hash(key) % self._sample_prime < self._sample_threshold
+
+    def _sweep_stale_evictions(self, now: float) -> None:
+        """Report T and discard evicted entries older than max_evict_reuse_wait."""
+        stale = [
+            key
+            for key, evict_time in self._evicted_at.items()
+            if now - evict_time >= self._max_evict_reuse_wait
+        ]
+        for key in stale:
+            self._evicted_at.pop(key, None)
+            self._evict_reuse_gap_hist.record(self._max_evict_reuse_wait)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l2.py b/lmcache/v1/mp_observability/subscribers/metrics/l2.py
new file mode 100644
index 0000000..6406895
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l2.py
@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L2 storage metrics subscriber — OTel counters for L2 store/prefetch events."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.subscribers.metrics.utils import (
+    emit_salt_counts,
+)
+
+
+def _l2_name_attrs(event: Event) -> dict[str, Any]:
+    """Build ``{"l2_name": ...}`` if the event carries an ``l2_name``
+    metadata key, else ``{}``.  Keeps the counter dimensionless when
+    the emission site hasn't been updated to carry the label yet."""
+    l2_name = event.metadata.get("l2_name")
+    if l2_name is None:
+        return {}
+    return {"l2_name": str(l2_name)}
+
+
+class L2MetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters for L2 store and prefetch operations.
+
+    Metrics:
+    - ``lmcache_mp.l2_store_submitted`` — store requests submitted to L2
+    - ``lmcache_mp.l2_store_submitted_objects`` — chunks submitted for L2 store
+    - ``lmcache_mp.l2_store_completed`` — store requests completed (attr: ``l2_name``)
+    - ``lmcache_mp.l2_store_completed_objects`` — chunks successfully stored to L2
+    - ``lmcache_mp.l2_load_completed`` — per-adapter load tasks completed
+      (attr: ``l2_name``)
+    - ``lmcache_mp.l2_prefetch_lookup`` — prefetch lookup requests
+    - ``lmcache_mp.l2_prefetch_lookup_objects`` — chunks submitted for lookup
+    - ``lmcache_mp.l2_prefetch_hit`` — prefix chunks found in L2
+    - ``lmcache_mp.l2_prefetch_load_submitted`` — load tasks submitted
+    - ``lmcache_mp.l2_prefetch_load_submitted_objects`` — chunks submitted for load
+    - ``lmcache_mp.l2_prefetch_load_completed`` — chunks successfully loaded from L2
+
+    The ``l2_name``-labeled counters (``l2_store_completed``, ``l2_load_completed``)
+    let dashboards compute per-backend IOPS via
+    ``rate(<counter>_total{l2_name="..."}[1m])``.
+    """
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache.l2")
+
+        # Store counters
+        self._store_submitted = meter.create_counter(
+            "lmcache_mp.l2_store_submitted",
+            description="Total L2 store requests submitted",
+            unit="requests",
+        )
+        self._store_submitted_objects = meter.create_counter(
+            "lmcache_mp.l2_store_submitted_objects",
+            description="Total chunks submitted for L2 store",
+            unit="chunks",
+        )
+        self._store_completed = meter.create_counter(
+            "lmcache_mp.l2_store_completed",
+            description="Total L2 store requests completed",
+            unit="requests",
+        )
+        self._store_completed_objects = meter.create_counter(
+            "lmcache_mp.l2_store_completed_objects",
+            description="Total chunks successfully stored to L2",
+            unit="chunks",
+        )
+
+        # Per-adapter load task counter (for IOPS via rate()).
+        # Labeled by ``l2_name`` so dashboards can slice per backend.
+        self._load_completed = meter.create_counter(
+            "lmcache_mp.l2_load_completed",
+            description="Total L2 load tasks completed (per-adapter)",
+            unit="requests",
+        )
+
+        # Prefetch lookup counters
+        self._prefetch_lookup_submitted = meter.create_counter(
+            "lmcache_mp.l2_prefetch_lookup",
+            description="Total L2 prefetch lookup requests submitted",
+            unit="requests",
+        )
+        self._prefetch_lookup_submitted_objects = meter.create_counter(
+            "lmcache_mp.l2_prefetch_lookup_objects",
+            description="Total chunks submitted for L2 prefetch lookup",
+            unit="chunks",
+        )
+        self._prefetch_lookup_hit = meter.create_counter(
+            "lmcache_mp.l2_prefetch_hit",
+            description="Total prefix chunks found in L2 lookup",
+            unit="chunks",
+        )
+
+        # Prefetch load counters
+        self._prefetch_load_submitted = meter.create_counter(
+            "lmcache_mp.l2_prefetch_load_submitted",
+            description="Total L2 prefetch load requests submitted (per-adapter)",
+            unit="requests",
+        )
+        self._prefetch_load_submitted_objects = meter.create_counter(
+            "lmcache_mp.l2_prefetch_load_submitted_objects",
+            description="Total chunks submitted for L2 load",
+            unit="chunks",
+        )
+        self._prefetch_load_completed = meter.create_counter(
+            "lmcache_mp.l2_prefetch_load_completed",
+            description="Total chunks successfully loaded from L2",
+            unit="chunks",
+        )
+
+        # Eviction counter
+        self._evicted_objects = meter.create_counter(
+            "lmcache_mp.l2_evicted_objects",
+            description="Total chunks evicted from L2",
+            unit="chunks",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L2_STORE_SUBMITTED: self._on_store_submitted,
+            EventType.L2_STORE_COMPLETED: self._on_store_completed,
+            EventType.L2_LOAD_TASK_COMPLETED: self._on_load_task_completed,
+            EventType.L2_PREFETCH_LOOKUP_SUBMITTED: self._on_lookup_submitted,
+            EventType.L2_PREFETCH_LOOKUP_COMPLETED: self._on_lookup_completed,
+            EventType.L2_PREFETCH_LOAD_SUBMITTED: self._on_load_submitted,
+            EventType.L2_PREFETCH_LOAD_COMPLETED: self._on_load_completed,
+            EventType.L2_KEYS_EVICTED: self._on_evicted,
+        }
+
+    def _on_store_submitted(self, event: Event) -> None:
+        self._store_submitted.add(1)
+        emit_salt_counts(
+            self._store_submitted_objects,
+            event.metadata.get("key_count_per_salt", {}),
+        )
+
+    def _on_store_completed(self, event: Event) -> None:
+        attrs = _l2_name_attrs(event)
+        self._store_completed.add(1, attributes=attrs)
+        emit_salt_counts(
+            self._store_completed_objects,
+            event.metadata.get("key_count_per_salt", {}),
+        )
+
+    def _on_load_task_completed(self, event: Event) -> None:
+        self._load_completed.add(1, attributes=_l2_name_attrs(event))
+
+    def _on_lookup_submitted(self, event: Event) -> None:
+        self._prefetch_lookup_submitted.add(1)
+        emit_salt_counts(
+            self._prefetch_lookup_submitted_objects,
+            event.metadata.get("key_count_per_salt", {}),
+        )
+
+    def _on_lookup_completed(self, event: Event) -> None:
+        self._prefetch_lookup_hit.add(event.metadata["prefix_hit_count"])
+
+    def _on_load_submitted(self, event: Event) -> None:
+        self._prefetch_load_submitted.add(event.metadata["adapter_count"])
+        emit_salt_counts(
+            self._prefetch_load_submitted_objects,
+            event.metadata.get("key_count_per_salt", {}),
+        )
+
+    def _on_load_completed(self, event: Event) -> None:
+        emit_salt_counts(
+            self._prefetch_load_completed,
+            event.metadata.get("key_count_per_salt", {}),
+        )
+
+    def _on_evicted(self, event: Event) -> None:
+        emit_salt_counts(
+            self._evicted_objects,
+            event.metadata.get("key_count_per_salt", {}),
+        )
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l2_failures.py b/lmcache/v1/mp_observability/subscribers/metrics/l2_failures.py
new file mode 100644
index 0000000..77f103a
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l2_failures.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L2 failure metrics subscriber — OTel counters for L2 prefetch failures.
+
+This covers the health-monitoring surface for L2 prefetch (see LM-291):
+
+- ``lmcache_mp.l2_prefetch_failure`` — count of keys that failed to load from
+  L2 to L1. Tagged by ``reason``:
+    * ``l1_oom``    — L1 had no room to receive the prefetched object.
+    * ``not_found`` — L2 reported the key present during lookup but the load
+      returned no data (adapter-level inconsistency, e.g. concurrent delete).
+
+The ``serde_failure`` reason is intentionally omitted until the serde PR
+lands; once it does, it becomes an additive third value of the same tag
+with no breaking change to dashboards.
+
+All emissions carry ``model_name`` extracted from each ``ObjectKey``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import Counter
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class L2FailureMetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters for L2 prefetch failures."""
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache_mp.health")
+        self._prefetch_counter = meter.create_counter(
+            "lmcache_mp.l2_prefetch_failure",
+            description=(
+                "Count of keys that were expected in L2 but failed to load "
+                "into L1. Tagged by ``reason`` = l1_oom | not_found and "
+                "``model_name``."
+            ),
+            unit="chunks",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {EventType.L2_PREFETCH_FAILED: self._on_prefetch_failed}
+
+    def _on_prefetch_failed(self, event: Event) -> None:
+        reason: str = event.metadata["reason"]
+        keys: list[ObjectKey] = event.metadata["keys"]
+        for model_name, count in Counter(k.model_name for k in keys).items():
+            self._prefetch_counter.add(
+                count,
+                {"reason": reason, "model_name": model_name},
+            )
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/l2_throughput.py b/lmcache/v1/mp_observability/subscribers/metrics/l2_throughput.py
new file mode 100644
index 0000000..1d4119c
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/l2_throughput.py
@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""L1↔L2 throughput metrics subscriber.
+
+Emits two OTel histograms in GB/s, labeled by ``l2_name`` (the registered
+adapter type, e.g. ``"fs"``, ``"nixl_store"``):
+  - ``lmcache_mp.l2_store_throughput``  — L1→L2 store
+  - ``lmcache_mp.l2_load_throughput``   — L2→L1 load
+
+Implementation:
+  - Store path correlates ``L2_STORE_SUBMITTED`` → ``L2_STORE_COMPLETED``
+    by the compound key ``(adapter_index, task_id)``.
+  - Load path correlates ``L2_LOAD_TASK_SUBMITTED`` → ``L2_LOAD_TASK_COMPLETED``
+    by ``(request_id, adapter_index)``.  One prefetch request may fan out
+    across multiple adapters, so per-adapter correlation is required to
+    attribute throughput to the right ``l2_name``.
+  - ``total_bytes`` is read from the SUBMITTED event and cached in the
+    subscriber's pending dict alongside the start timestamp, so the
+    COMPLETED event does not need to carry it.  This keeps the byte
+    accounting out of the controllers' in-flight task state.
+  - ``(end_ts - start_ts)`` spans submit -> complete and therefore
+    includes adapter queue, network, and disk time — not just transfer.
+    The histogram is "bytes / end-to-end latency", not raw transfer rate.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class L2ThroughputSubscriber(EventSubscriber):
+    """Records L1↔L2 throughput by correlating SUBMITTED→COMPLETED pairs."""
+
+    def __init__(self) -> None:
+        # (adapter_index, task_id) -> (t_start, total_bytes).
+        self._pending_store: dict[tuple[int, int], tuple[float, int]] = {}
+        # (request_id, adapter_index) -> (t_start, total_bytes).
+        self._pending_load: dict[tuple[int, int], tuple[float, int]] = {}
+
+        meter = metrics.get_meter("lmcache_mp.perf")
+        self._store_hist = meter.create_histogram(
+            "lmcache_mp.l2_store_throughput",
+            description=(
+                "Histogram of L1->L2 store throughput in GB/s, measured "
+                "per task as total_bytes / (completed_ts - "
+                "submitted_ts).  Spans adapter queue + network/disk I/O, "
+                "so this is end-to-end latency-based throughput."
+            ),
+            unit="GB/s",
+        )
+        self._load_hist = meter.create_histogram(
+            "lmcache_mp.l2_load_throughput",
+            description=(
+                "Histogram of L2->L1 load throughput in GB/s, measured "
+                "per (request, adapter) pair as total_bytes / "
+                "(completed_ts - submitted_ts).  Spans adapter queue + "
+                "network/disk I/O."
+            ),
+            unit="GB/s",
+        )
+
+    # -- EventSubscriber interface -----------------------------------------
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.L2_STORE_SUBMITTED: self._on_store_submitted,
+            EventType.L2_STORE_COMPLETED: self._on_store_completed,
+            EventType.L2_LOAD_TASK_SUBMITTED: self._on_load_submitted,
+            EventType.L2_LOAD_TASK_COMPLETED: self._on_load_completed,
+        }
+
+    # -- Store path (L1->L2) -----------------------------------------------
+
+    def _on_store_submitted(self, event: Event) -> None:
+        key = self._store_key(event)
+        if key is not None:
+            total_bytes = int(event.metadata.get("total_bytes", 0))
+            self._pending_store[key] = (event.timestamp, total_bytes)
+
+    def _on_store_completed(self, event: Event) -> None:
+        key = self._store_key(event)
+        if key is None:
+            return
+
+        # ``bytes_transferred`` is always present in L2_STORE_COMPLETED
+        # events (populated from L2StoreResult).
+        bytes_transferred = event.metadata.get("bytes_transferred")
+        self._record(
+            event=event,
+            correlation_key=key,
+            pending=self._pending_store,
+            hist=self._store_hist,
+            real_bytes_transferred=bytes_transferred,
+        )
+
+    # -- Load path (L2->L1) ------------------------------------------------
+
+    def _on_load_submitted(self, event: Event) -> None:
+        key = self._load_key(event)
+        if key is not None:
+            total_bytes = int(event.metadata.get("total_bytes", 0))
+            self._pending_load[key] = (event.timestamp, total_bytes)
+
+    def _on_load_completed(self, event: Event) -> None:
+        key = self._load_key(event)
+        if key is None:
+            return
+        self._record(
+            event=event,
+            correlation_key=key,
+            pending=self._pending_load,
+            hist=self._load_hist,
+        )
+
+    # -- Correlation-key helpers ------------------------------------------
+
+    @staticmethod
+    def _store_key(event: Event) -> tuple[int, int] | None:
+        """Build the ``(adapter_index, task_id)`` correlation key.
+
+        Returns ``None`` if either field is missing.
+        """
+        adapter_index = event.metadata.get("adapter_index")
+        task_id = event.metadata.get("task_id")
+        if adapter_index is None or task_id is None:
+            return None
+        return (int(adapter_index), int(task_id))
+
+    @staticmethod
+    def _load_key(event: Event) -> tuple[int, int] | None:
+        """Build the ``(request_id, adapter_index)`` correlation key.
+
+        Returns ``None`` if either field is missing.
+        """
+        request_id = event.metadata.get("request_id")
+        adapter_index = event.metadata.get("adapter_index")
+        if request_id is None or adapter_index is None:
+            return None
+        return (int(request_id), int(adapter_index))
+
+    # -- Core computation --------------------------------------------------
+
+    @staticmethod
+    def _record(
+        event: Event,
+        correlation_key: tuple[int, int],
+        pending: dict[tuple[int, int], tuple[float, int]],
+        hist: Any,
+        real_bytes_transferred: int | None = None,
+    ) -> None:
+        """
+        Record a throughput sample.
+
+        Args:
+            event: The COMPLETED event, used for timestamp and metadata.
+            correlation_key: The key to look up the matching SUBMITTED event.
+            pending: The dict mapping correlation keys to (t_start, total_bytes).
+            hist: The OTel histogram to record into.
+            real_bytes_transferred: If set, use this instead of the submitted
+                totay_bytes, When it's 0, drop the sample.
+        """
+        pending_entry = pending.pop(correlation_key, None)
+        if pending_entry is None:
+            return  # no matching SUBMITTED event;
+        t_start, total_bytes = pending_entry
+
+        effective_bytes = (
+            total_bytes if real_bytes_transferred is None else real_bytes_transferred
+        )
+        if effective_bytes <= 0:
+            return
+
+        dt = event.timestamp - t_start
+        if dt <= 0:
+            return
+
+        l2_name = event.metadata.get("l2_name")
+        attrs: dict[str, Any] = {}
+        if l2_name is not None:
+            attrs["l2_name"] = str(l2_name)
+
+        hist.record(effective_bytes / dt / 1e9, attributes=attrs)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/lookup.py b/lmcache/v1/mp_observability/subscribers/metrics/lookup.py
new file mode 100644
index 0000000..31bc757
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/lookup.py
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Lookup metrics subscriber — OTel counters for L1+L2 token-level hit rate.
+
+Exposes two counters driven by the ``MP_LOOKUP_PREFETCH_END`` event.  Their
+ratio is the fraction of tokens requested by a lookup that were served from
+the L1 or L2 caches (L0/GPU prefix cache is vLLM-owned and not observable
+here):
+
+    rate(lmcache_mp_lookup_hit_tokens_total[5m])
+    / rate(lmcache_mp_lookup_requested_tokens_total[5m])
+
+Both counters carry ``model_name`` and ``cache_salt`` attributes so the
+ratio can be sliced per model and per tenant / isolation domain on the
+dashboard.
+
+See ``docs/design/v1/mp_observability/L1_L2_HIT_RATE_PLAN.md`` for the full
+rationale behind co-locating numerator and denominator on a single event.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+def _lookup_attrs(event: Event) -> dict[str, Any]:
+    """Build ``{"model_name": ..., "cache_salt": ...}`` from the event.
+
+    Missing fields are dropped from the returned dict so future emission
+    sites that haven't been updated to populate them won't crash; the
+    counter just records without that label dimension.
+    """
+    attrs: dict[str, Any] = {}
+    model_name = event.metadata.get("model_name")
+    if model_name is not None:
+        attrs["model_name"] = str(model_name)
+    cache_salt = event.metadata.get("cache_salt")
+    if cache_salt is not None:
+        attrs["cache_salt"] = str(cache_salt)
+    return attrs
+
+
+class LookupMetricsSubscriber(EventSubscriber):
+    """Maintains OTel counters for L1+L2 token-level cache hit rate.
+
+    Metrics (both labeled by ``model_name`` and ``cache_salt``):
+    - ``lmcache_mp.lookup_requested`` — tokens submitted for lookup
+      (denominator).  Counts only the chunk-aligned portion; sub-chunk
+      trailing tokens are excluded because they cannot hit by design.
+    - ``lmcache_mp.lookup_hit`` — tokens found in L1+L2 during the
+      lookup (numerator).  Counts the contiguous prefix hit only.
+    """
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache.lookup")
+
+        self._requested_tokens = meter.create_counter(
+            "lmcache_mp.lookup_requested",
+            description=(
+                "Total tokens submitted for lookup (denominator of the "
+                "L1+L2 token-level hit rate). Only chunk-aligned tokens "
+                "are counted."
+            ),
+            unit="tokens",
+        )
+        self._hit_tokens = meter.create_counter(
+            "lmcache_mp.lookup_hit",
+            description=(
+                "Total tokens found in L1+L2 during lookup (numerator of "
+                "the L1+L2 token-level hit rate). Counts the contiguous "
+                "prefix hit only."
+            ),
+            unit="tokens",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.MP_LOOKUP_PREFETCH_END: self._on_lookup_prefetch_end,
+        }
+
+    def _on_lookup_prefetch_end(self, event: Event) -> None:
+        attrs = _lookup_attrs(event)
+        self._requested_tokens.add(event.metadata["requested_tokens"], attributes=attrs)
+        self._hit_tokens.add(event.metadata["hit_tokens"], attributes=attrs)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/sm_lifecycle.py b/lmcache/v1/mp_observability/subscribers/metrics/sm_lifecycle.py
new file mode 100644
index 0000000..ecff664
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/sm_lifecycle.py
@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""StorageManager lifecycle subscriber — workload-level real-reuse histograms.
+
+Tracks the gap between consecutive uses of the same logical chunk
+(``(cache_salt, chunk_hash)``) at the StorageManager level — i.e.
+caller-driven reads/writes, not internal lock releases from the
+store/prefetch controllers.  Two histograms are emitted, both tagged
+with ``cache_salt``:
+
+- ``lmcache_mp.real_reuse_gap_seconds`` — wall-clock gap between a
+  chunk's last access (read or write) and the next read.  Captures
+  storage cost.
+- ``lmcache_mp.real_reuse_gap_chunks`` — same gap measured in the
+  per-salt access-counter stream (bumped on every read AND write of
+  every chunk, regardless of sampling).  Captures storage volume.
+
+Sampling: only chunks that pass a deterministic ``hash % prime``
+gate get a tracking entry.  The per-salt counter advances on every
+access, sampled or not, so the chunks-gap reflects true volume.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import random
+import time
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+# Cap on the (cache_salt, chunk_hash) reuse-tracking dict.  Random
+# eviction on overflow — all entries already passed the sampling gate.
+_REUSE_TRACK_CAP = 100_000
+
+
+class SMLifecycleSubscriber(EventSubscriber):
+    """Real-reuse histograms over StorageManager events.
+
+    Histograms (tagged with ``cache_salt``):
+
+    - ``lmcache_mp.real_reuse_gap_seconds`` — gap between a chunk's
+      last access (read or write) and the next read.  Storage cost.
+      Emitted on read events only.
+    - ``lmcache_mp.real_reuse_gap_chunks`` — same gap in the per-salt
+      access-counter stream (bumped on every read AND write).  Storage
+      volume.  Emitted on read events for sampled chunks.
+
+    Sources are caller-facing StorageManager events
+    (``SM_READ_PREFETCHED_FINISHED``, ``SM_WRITE_FINISHED``) so
+    internal lock releases from the store and prefetch controllers do
+    not pollute the signal.
+
+    Parameters:
+        sample_rate: Fraction of chunks to track (0, 1.0].  Default 0.01 (1%).
+    """
+
+    def __init__(self, sample_rate: float = 0.01) -> None:
+        if not 0 < sample_rate <= 1.0:
+            raise ValueError(f"sample_rate must be in (0, 1.0], got {sample_rate}")
+        self._sample_rate = sample_rate
+        self._sample_prime = 1_000_003
+        self._sample_threshold = int(sample_rate * self._sample_prime)
+        meter = metrics.get_meter("lmcache.sm")
+        self._real_reuse_gap_seconds_hist = meter.create_histogram(
+            "lmcache_mp.real_reuse_gap",
+            description=(
+                "Gap between a chunk's last access (read or write) and "
+                "next read.  Storage cost.  Tagged with cache_salt."
+            ),
+            unit="s",
+        )
+        self._real_reuse_gap_chunks_hist = meter.create_histogram(
+            "lmcache_mp.real_reuse_gap_objects",
+            description=(
+                "Per-cache_salt access-counter gap between two reads of "
+                "the same chunk.  Storage volume.  Tagged with cache_salt."
+            ),
+            unit="{chunks}",
+        )
+        # Per-salt access counter; bumped on every read and write.
+        # cache_salt is operator-set (tenant identifier), so cardinality
+        # is naturally bounded.
+        self._salt_chunk_counter: dict[str, int] = {}
+        # (cache_salt, chunk_hash) -> (last_access_time, counter_at_last_access).
+        self._reuse_track: dict[tuple[str, bytes], tuple[float, int]] = {}
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {
+            EventType.SM_READ_PREFETCHED_FINISHED: self._on_sm_read_finished,
+            EventType.SM_WRITE_FINISHED: self._on_sm_write_finished,
+        }
+
+    def _bump_salt_counter(self, salt: str) -> int:
+        """Advance and return the per-salt access counter."""
+        nxt = self._salt_chunk_counter.get(salt, 0) + 1
+        self._salt_chunk_counter[salt] = nxt
+        return nxt
+
+    def _admit_track(
+        self,
+        track_key: tuple[str, bytes],
+        when: float,
+        counter: int,
+    ) -> None:
+        """Admit a newly-sampled entry; random-evict on overflow."""
+        if (
+            len(self._reuse_track) >= _REUSE_TRACK_CAP
+            and track_key not in self._reuse_track
+        ):
+            victim = random.choice(list(self._reuse_track))
+            self._reuse_track.pop(victim, None)
+        self._reuse_track[track_key] = (when, counter)
+
+    def _should_sample(self, key: tuple[str, bytes]) -> bool:
+        return hash(key) % self._sample_prime < self._sample_threshold
+
+    def _on_sm_read_finished(self, event: Event) -> None:
+        """Bump counter and emit a real-reuse sample for sampled chunks."""
+        now = event.timestamp or time.time()
+        # Dedupe TP fanout: one ObjectKey per kv_rank for the same logical
+        # chunk should bump the per-salt counter once.
+        seen: set[tuple[str, bytes]] = set()
+        for key in event.metadata.get("succeeded_keys", []):
+            chunk_hash = getattr(key, "chunk_hash", None)
+            if chunk_hash is None:
+                continue
+            cache_salt = getattr(key, "cache_salt", "")
+            track_key = (cache_salt, chunk_hash)
+            if track_key in seen:
+                continue
+            seen.add(track_key)
+            counter = self._bump_salt_counter(cache_salt)
+            prior = self._reuse_track.get(track_key)
+            if prior is not None:
+                last_time, last_counter = prior
+                attrs = {"cache_salt": cache_salt}
+                self._real_reuse_gap_seconds_hist.record(now - last_time, attrs)
+                self._real_reuse_gap_chunks_hist.record(counter - last_counter, attrs)
+                self._reuse_track[track_key] = (now, counter)
+            elif self._should_sample(track_key):
+                self._admit_track(track_key, now, counter)
+
+    def _on_sm_write_finished(self, event: Event) -> None:
+        """Bump counter and update anchor; never emit a sample on write."""
+        now = event.timestamp or time.time()
+        seen: set[tuple[str, bytes]] = set()
+        for key in event.metadata.get("succeeded_keys", []):
+            chunk_hash = getattr(key, "chunk_hash", None)
+            if chunk_hash is None:
+                continue
+            cache_salt = getattr(key, "cache_salt", "")
+            track_key = (cache_salt, chunk_hash)
+            if track_key in seen:
+                continue
+            seen.add(track_key)
+            counter = self._bump_salt_counter(cache_salt)
+            if track_key in self._reuse_track:
+                self._reuse_track[track_key] = (now, counter)
+            elif self._should_sample(track_key):
+                self._admit_track(track_key, now, counter)
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/timeout.py b/lmcache/v1/mp_observability/subscribers/metrics/timeout.py
new file mode 100644
index 0000000..c964f47
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/timeout.py
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""OTel counter for timeout errors: ``lmcache_mp.timeouts`` by ``exception_type``."""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+from opentelemetry import metrics
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+
+
+class TimeoutMetricsSubscriber(EventSubscriber):
+    """Maintains an OTel counter for timeout errors."""
+
+    def __init__(self) -> None:
+        meter = metrics.get_meter("lmcache_mp.health")
+        self._timeout_counter = meter.create_counter(
+            "lmcache_mp.timeouts",
+            description="Timeouts raised, tagged by exception_type.",
+        )
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {EventType.TIMEOUT_RAISED: self._on_timeout}
+
+    def _on_timeout(self, event: Event) -> None:
+        exception_type: str = event.metadata["exception_type"]
+        self._timeout_counter.add(1, {"exception_type": exception_type})
diff --git a/lmcache/v1/mp_observability/subscribers/metrics/utils.py b/lmcache/v1/mp_observability/subscribers/metrics/utils.py
new file mode 100644
index 0000000..420adaf
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/metrics/utils.py
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared cache_salt helpers for metrics subscribers."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import Counter
+
+# Third Party
+from opentelemetry import metrics
+
+
+def group_by_salt(keys: list) -> dict[str, int]:
+    """Group *keys* by ``cache_salt``, returning salt → count."""
+    return Counter(getattr(k, "cache_salt", "") for k in keys)
+
+
+def emit_salt_counts(counter: metrics.Counter, salt_counts: dict[str, int]) -> None:
+    """Add to *counter* once per entry in *salt_counts*.
+
+    *salt_counts* maps ``cache_salt`` values to key counts.
+    Empty salt produces a dimensionless increment (no attribute).
+    """
+    for salt, count in salt_counts.items():
+        attrs = {"cache_salt": salt} if salt else {}
+        counter.add(count, attributes=attrs)
diff --git a/lmcache/v1/mp_observability/subscribers/tracing/__init__.py b/lmcache/v1/mp_observability/subscribers/tracing/__init__.py
new file mode 100644
index 0000000..4f265f3
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/tracing/__init__.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.mp_observability.subscribers.tracing.cb_server import (
+    BlendTracingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.tracing.mp_server import (
+    MPServerTracingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import (
+    SpanRegistry,
+    get_span_registry,
+)
+from lmcache.v1.mp_observability.subscribers.tracing.timeout import (
+    TimeoutTracingSubscriber,
+)
+
+__all__ = [
+    "BlendTracingSubscriber",
+    "MPServerTracingSubscriber",
+    "SpanRegistry",
+    "TimeoutTracingSubscriber",
+    "get_span_registry",
+]
diff --git a/lmcache/v1/mp_observability/subscribers/tracing/cb_server.py b/lmcache/v1/mp_observability/subscribers/tracing/cb_server.py
new file mode 100644
index 0000000..b04e54d
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/tracing/cb_server.py
@@ -0,0 +1,429 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""OTel tracing subscriber for Cache Blending (CB) operations.
+
+Creates a root ``"cb.request"`` span per session wrapping all CB child spans.
+Opens at ``CB_REQUEST_START``; closes at ``CB_REQUEST_END``, deferred until
+any in-flight GPU store/retrieve callbacks complete **and** until
+``CB_STORE_FINAL_SUBMITTED`` has been received (if a retrieve was submitted).
+
+On the HIT path the lifecycle is:
+
+  CB_RETRIEVE_SUBMITTED → [retrieve GPU op] → CB_RETRIEVE_END
+      → [inference, ~hundreds of ms, pending_gpu_ops==0 here]
+  CB_STORE_FINAL_SUBMITTED → CB_REQUEST_END → [store GPU op] → CB_STORE_FINAL_END
+
+During inference ``_pending_gpu_ops`` is 0, so a stray ``CB_REQUEST_END``
+(e.g. from a second CB lookup call that misses) would
+otherwise close the root span prematurely.  ``_waiting_for_store_final``
+bridges this gap: it is populated by ``CB_RETRIEVE_SUBMITTED`` and cleared by
+``CB_STORE_FINAL_SUBMITTED``, so the root span cannot close until both
+conditions hold simultaneously:
+
+* ``_pending_gpu_ops[sid] == 0``
+* ``sid not in _waiting_for_store_final``
+
+``cb.request`` is the trace root: blend_v3 owns the CB lookup end-to-end (prefix
++ non-prefix legs, direct against the storage manager), so a CB request never
+opens an MP ``"request"`` span to nest under. The optional
+:class:`~lmcache.v1.mp_observability.subscribers.tracing.span_registry\
+.SpanRegistry` is used to nest the CB child spans under ``cb.request``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import SpanRegistry
+
+logger = init_logger(__name__)
+
+try:
+    # Third Party
+    from opentelemetry import trace
+
+    _tracer = trace.get_tracer("lmcache_mp.blend")
+    _HAS_OTEL = True
+except ImportError:
+    _HAS_OTEL = False
+
+
+class BlendTracingSubscriber(EventSubscriber):
+    """Creates OTel spans from CB (Cache Blending) START/END event pairs.
+
+    Each session gets one root ``"cb.request"`` span that nests all child
+    spans (``cb.lookup``, ``cb.store_pre_computed``, ``cb.retrieve``,
+    ``cb.store_final``).  The root is opened at ``CB_REQUEST_START`` and
+    closed at ``CB_REQUEST_END``, with deferral if GPU ops are still in
+    flight.
+
+    When a shared :class:`SpanRegistry` is provided, ``"cb.request"`` is
+    nested under the MP server ``"request"`` span for the same session.
+    """
+
+    # Maps each START event to its span name (used for creation and registry key).
+    _SPAN_DEFS: dict[EventType, str] = {
+        EventType.CB_STORE_PRE_COMPUTED_START: "cb.store_pre_computed",
+        EventType.CB_LOOKUP_START: "cb.lookup",
+        EventType.CB_RETRIEVE_START: "cb.retrieve",
+        EventType.CB_STORE_FINAL_START: "cb.store_final",
+        # V3 lookup sub-spans (nest under cb.lookup, see _SPAN_PARENTS).
+        EventType.CB_FINGERPRINT_MATCH_START: "cb.fingerprint_match",
+        EventType.CB_PREFIX_LOOKUP_START: "cb.prefix_lookup",
+        EventType.CB_COORDINATOR_MATCH_START: "cb.coordinator_match",
+        EventType.CB_SPARSE_PREFETCH_START: "cb.sparse_prefetch",
+        # V3 retrieve sub-span (nests under cb.retrieve).
+        EventType.CB_SCATTER_START: "cb.scatter",
+    }
+
+    # Child span -> parent span name for nesting; absent => nest under the
+    # cb.request root (the default for the top-level lookup/retrieve/store spans).
+    _SPAN_PARENTS: dict[str, str] = {
+        "cb.fingerprint_match": "cb.lookup",
+        "cb.prefix_lookup": "cb.lookup",
+        "cb.coordinator_match": "cb.lookup",
+        "cb.sparse_prefetch": "cb.lookup",
+        "cb.scatter": "cb.retrieve",
+    }
+
+    _END_TO_START: dict[EventType, EventType] = {
+        EventType.CB_STORE_PRE_COMPUTED_END: EventType.CB_STORE_PRE_COMPUTED_START,
+        EventType.CB_LOOKUP_END: EventType.CB_LOOKUP_START,
+        EventType.CB_RETRIEVE_END: EventType.CB_RETRIEVE_START,
+        EventType.CB_STORE_FINAL_END: EventType.CB_STORE_FINAL_START,
+        EventType.CB_FINGERPRINT_MATCH_END: EventType.CB_FINGERPRINT_MATCH_START,
+        EventType.CB_PREFIX_LOOKUP_END: EventType.CB_PREFIX_LOOKUP_START,
+        EventType.CB_COORDINATOR_MATCH_END: EventType.CB_COORDINATOR_MATCH_START,
+        EventType.CB_SPARSE_PREFETCH_END: EventType.CB_SPARSE_PREFETCH_START,
+        EventType.CB_SCATTER_END: EventType.CB_SCATTER_START,
+    }
+
+    # END events that correspond to a SUBMITTED sentinel (decrement ops counter)
+    _GPU_OP_END_EVENTS: frozenset[EventType] = frozenset(
+        {
+            EventType.CB_STORE_PRE_COMPUTED_END,
+            EventType.CB_RETRIEVE_END,
+            EventType.CB_STORE_FINAL_END,
+        }
+    )
+
+    def __init__(self, registry: SpanRegistry | None = None) -> None:
+        self._registry = registry if registry is not None else SpanRegistry()
+
+        # session_id -> (span, start_event_type) for pending child spans
+        self._pending: dict[str, tuple[Any, EventType]] = {}
+
+        # session_id -> number of in-flight GPU ops (SUBMITTED without matching END)
+        self._pending_gpu_ops: dict[str, int] = {}
+
+        # session_id -> REQUEST_END timestamp saved when GPU ops are in flight
+        # or when a store_final is still expected
+        self._deferred_session_end_ts: dict[str, float] = {}
+
+        # Sessions where CB_RETRIEVE_SUBMITTED was seen but CB_STORE_FINAL_SUBMITTED
+        # has not yet arrived.  Prevents premature root-span closure during the
+        # inference window when _pending_gpu_ops is transiently 0.
+        self._waiting_for_store_final: set[str] = set()
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        """Return the event-to-callback mapping for this subscriber."""
+        return {
+            # Root span lifecycle
+            EventType.CB_REQUEST_START: self._on_request_start,
+            EventType.CB_STORE_PRE_COMPUTED_SUBMITTED: self._on_submitted,
+            EventType.CB_RETRIEVE_SUBMITTED: self._on_submitted,
+            EventType.CB_STORE_FINAL_SUBMITTED: self._on_submitted,
+            EventType.CB_REQUEST_END: self._on_session_end,
+            # Child spans
+            EventType.CB_STORE_PRE_COMPUTED_START: self._on_start,
+            EventType.CB_STORE_PRE_COMPUTED_END: self._on_end,
+            EventType.CB_LOOKUP_START: self._on_start,
+            EventType.CB_LOOKUP_END: self._on_end,
+            EventType.CB_RETRIEVE_START: self._on_start,
+            EventType.CB_RETRIEVE_END: self._on_end,
+            EventType.CB_STORE_FINAL_START: self._on_start,
+            EventType.CB_STORE_FINAL_END: self._on_end,
+            # V3 lookup sub-spans (nested under cb.lookup)
+            EventType.CB_FINGERPRINT_MATCH_START: self._on_start,
+            EventType.CB_FINGERPRINT_MATCH_END: self._on_end,
+            EventType.CB_PREFIX_LOOKUP_START: self._on_start,
+            EventType.CB_PREFIX_LOOKUP_END: self._on_end,
+            EventType.CB_COORDINATOR_MATCH_START: self._on_start,
+            EventType.CB_COORDINATOR_MATCH_END: self._on_end,
+            EventType.CB_SPARSE_PREFETCH_START: self._on_start,
+            EventType.CB_SPARSE_PREFETCH_END: self._on_end,
+            # V3 retrieve sub-span (nested under cb.retrieve, GPU-timed)
+            EventType.CB_SCATTER_START: self._on_start,
+            EventType.CB_SCATTER_END: self._on_end,
+            # Point events
+            EventType.CB_FINGERPRINTS_REGISTERED: self._on_point,
+            EventType.CB_CHUNKS_EVICTED: self._on_point,
+        }
+
+    # ------------------------------------------------------------------
+    # Public lifecycle
+    # ------------------------------------------------------------------
+
+    def shutdown(self) -> None:
+        """End all leaked spans on bus shutdown."""
+        for key, (span, _) in self._pending.items():
+            try:
+                span.end()
+            except Exception:
+                pass
+        self._pending.clear()
+
+        sessions = (
+            set(self._pending_gpu_ops)
+            | set(self._deferred_session_end_ts)
+            | self._registry.all_session_ids()
+        )
+        for sid in sessions:
+            self._registry.clear_session(sid)
+        self._pending_gpu_ops.clear()
+        self._deferred_session_end_ts.clear()
+        self._waiting_for_store_final.clear()
+
+    # ------------------------------------------------------------------
+    # Root span handlers
+    # ------------------------------------------------------------------
+
+    def _on_request_start(self, event: Event) -> None:
+        """Create the ``"cb.request"`` root span.
+
+        blend_v3 owns the CB lookup end-to-end, so a CB request never opens an MP
+        ``"request"`` span — ``cb.request`` is the trace root.
+
+        Args:
+            event: ``CB_REQUEST_START`` event with ``session_id`` set.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        if self._registry.get_context(sid, "cb.request") is not None:
+            logger.warning("CB_REQUEST_START fired twice for session=%s; ignoring", sid)
+            return
+        root_span = _tracer.start_span(
+            "cb.request",
+            start_time=int(event.timestamp * 1e9),
+        )
+        root_span.set_attribute("session_id", sid)
+        self._registry.open(
+            sid, "cb.request", root_span, trace.set_span_in_context(root_span)
+        )
+
+    def _on_submitted(self, event: Event) -> None:
+        """Increment the in-flight GPU-ops counter and update store-final tracking.
+
+        ``CB_RETRIEVE_SUBMITTED`` marks the session as waiting for a store_final,
+        bridging the inference gap where ``_pending_gpu_ops`` is transiently 0.
+        ``CB_STORE_FINAL_SUBMITTED`` clears that marker (store_final has arrived).
+
+        Args:
+            event: One of ``CB_STORE_PRE_COMPUTED_SUBMITTED``,
+                ``CB_RETRIEVE_SUBMITTED``, or ``CB_STORE_FINAL_SUBMITTED``.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        self._pending_gpu_ops[sid] = self._pending_gpu_ops.get(sid, 0) + 1
+        if event.event_type == EventType.CB_RETRIEVE_SUBMITTED:
+            self._waiting_for_store_final.add(sid)
+        elif event.event_type == EventType.CB_STORE_FINAL_SUBMITTED:
+            self._waiting_for_store_final.discard(sid)
+
+    def _on_session_end(self, event: Event) -> None:
+        """Close the root span, or defer if GPU ops are in flight or store_final
+        is pending.
+
+        Defers when either condition holds:
+        * ``_pending_gpu_ops[sid] > 0`` — a GPU callback is still in flight.
+        * ``sid in _waiting_for_store_final`` — retrieve completed but
+          ``CB_STORE_FINAL_SUBMITTED`` has not yet arrived (inference window).
+
+        Always overwrites any previously saved deferred timestamp so the
+        ``CB_REQUEST_END`` from ``cb_store_final`` (the correct logical end)
+        supersedes an earlier one from a concurrent lookup miss.
+
+        Args:
+            event: ``CB_REQUEST_END`` event carrying the logical end timestamp.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        if (
+            self._pending_gpu_ops.get(sid, 0) == 0
+            and sid not in self._waiting_for_store_final
+        ):
+            self._close_request_span(sid, event.timestamp)
+        else:
+            self._deferred_session_end_ts[sid] = event.timestamp
+
+    # ------------------------------------------------------------------
+    # Child span handlers
+    # ------------------------------------------------------------------
+
+    def _on_start(self, event: Event) -> None:
+        """Create a child span nested under the ``"cb.request"`` root span.
+
+        Args:
+            event: One of the CB ``*_START`` event types.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        span_name = self._SPAN_DEFS[event.event_type]
+
+        # Nest under the mapped parent span (e.g. cb.fingerprint_match under
+        # cb.lookup); top-level spans and any orphan fall back to cb.request.
+        parent_name = self._SPAN_PARENTS.get(span_name, "cb.request")
+        parent_ctx = self._registry.get_context(sid, parent_name)
+        if parent_ctx is None and parent_name != "cb.request":
+            parent_ctx = self._registry.get_context(sid, "cb.request")
+        span = _tracer.start_span(
+            span_name,
+            context=parent_ctx,
+            start_time=int(event.timestamp * 1e9),
+        )
+        span.set_attribute("session_id", sid)
+        for k, v in event.metadata.items():
+            span.set_attribute(k, str(v))
+
+        key = f"{sid}:{event.event_type.value}"
+        self._pending[key] = (span, event.event_type)
+
+        self._registry.open(sid, span_name, span, trace.set_span_in_context(span))
+
+    def _on_end(self, event: Event) -> None:
+        """Close a pending child span and handle GPU-ops counter deferral.
+
+        For GPU-backed END events (store_pre_computed, retrieve, store_final),
+        decrements the in-flight counter; if it reaches zero and a deferred
+        session-end timestamp exists, closes the root span using the GPU
+        callback timestamp so that ``cb.request`` end_time reflects when
+        inference and the GPU copy actually completed.
+
+        Args:
+            event: One of the CB ``*_END`` event types.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        start_type = self._END_TO_START[event.event_type]
+        key = f"{sid}:{start_type.value}"
+        entry = self._pending.pop(key, None)
+        if entry is None:
+            logger.debug(
+                "No pending CB span for %s session=%s",
+                event.event_type.value,
+                sid,
+            )
+        else:
+            span, _ = entry
+            for k, v in event.metadata.items():
+                span.set_attribute(k, str(v))
+            span.end(end_time=int(event.timestamp * 1e9))
+
+        self._registry.pop(sid, self._SPAN_DEFS[start_type])
+
+        if event.event_type == EventType.CB_LOOKUP_END:
+            root_entry = self._registry.get(sid, "cb.request")
+            if root_entry is not None:
+                root_span, _ = root_entry
+                hit_tokens = int(event.metadata.get("hit_tokens", 0))
+                requested_tokens = int(event.metadata.get("requested_tokens", 0))
+                prefix_hit_tokens = int(event.metadata.get("prefix_hit_tokens", 0))
+                seg_prefix_hit_tokens = int(
+                    event.metadata.get("segmented_prefix_hit_tokens", 0)
+                )
+                non_prefix_hit_tokens = int(
+                    event.metadata.get("non_prefix_hit_tokens", 0)
+                )
+                denom = requested_tokens or 1  # avoid /0; rates are 0 when requested=0
+                root_span.set_attribute("hit_tokens", hit_tokens)
+                root_span.set_attribute("requested_tokens", requested_tokens)
+                # hit_rate numerator = prefix + segmented-prefix tail + non-prefix
+                # reuse (hit_tokens).
+                root_span.set_attribute("hit_rate", hit_tokens / denom)
+                root_span.set_attribute(
+                    "prefix_hits", int(event.metadata.get("prefix_hits", 0))
+                )
+                root_span.set_attribute("prefix_hit_tokens", prefix_hit_tokens)
+                root_span.set_attribute(
+                    "segmented_prefix_hit_tokens", seg_prefix_hit_tokens
+                )
+                root_span.set_attribute("non_prefix_hit_tokens", non_prefix_hit_tokens)
+                # Per-component hit rates (sum to hit_rate).
+                root_span.set_attribute("prefix_hit_rate", prefix_hit_tokens / denom)
+                root_span.set_attribute(
+                    "segmented_prefix_hit_rate", seg_prefix_hit_tokens / denom
+                )
+                root_span.set_attribute(
+                    "non_prefix_hit_rate", non_prefix_hit_tokens / denom
+                )
+
+        if event.event_type in self._GPU_OP_END_EVENTS:
+            if (count := self._pending_gpu_ops.get(sid, 0)) > 0:
+                if count == 1:
+                    self._pending_gpu_ops.pop(sid)
+                else:
+                    self._pending_gpu_ops[sid] = count - 1
+            if (
+                sid in self._deferred_session_end_ts
+                and self._pending_gpu_ops.get(sid, 0) == 0
+                and sid not in self._waiting_for_store_final
+            ):
+                self._deferred_session_end_ts.pop(sid)
+                # Use the GPU callback timestamp so cb.request end_time reflects
+                # when inference + the GPU copy actually finished, not when
+                # cb_store_final was submitted on the CPU.
+                self._close_request_span(sid, event.timestamp)
+
+    def _on_point(self, event: Event) -> None:
+        """Emit an instant span for point events (no paired END).
+
+        Args:
+            event: ``CB_FINGERPRINTS_REGISTERED`` or ``CB_CHUNKS_EVICTED``.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        ts_ns = int(event.timestamp * 1e9)
+        parent_ctx = self._registry.get_context(sid, "cb.request")
+        span = _tracer.start_span(
+            event.event_type.value,
+            context=parent_ctx,
+            start_time=ts_ns,
+        )
+        span.set_attribute("session_id", sid)
+        for k, v in event.metadata.items():
+            span.set_attribute(k, str(v))
+        span.end(end_time=ts_ns)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _close_request_span(self, session_id: str, end_ts: float) -> None:
+        """End the ``"cb.request"`` root span and clean up per-session state.
+
+        Args:
+            session_id: The request session identifier.
+            end_ts: Wall-clock timestamp to stamp as the span end time.
+        """
+        entry = self._registry.pop(session_id, "cb.request")
+        if entry is not None:
+            root_span, _ = entry
+            try:
+                root_span.end(end_time=int(end_ts * 1e9))
+            except Exception:
+                pass
+        self._pending_gpu_ops.pop(session_id, None)
+        self._deferred_session_end_ts.pop(session_id, None)
+        self._waiting_for_store_final.discard(session_id)
diff --git a/lmcache/v1/mp_observability/subscribers/tracing/mp_server.py b/lmcache/v1/mp_observability/subscribers/tracing/mp_server.py
new file mode 100644
index 0000000..bbadd8e
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/tracing/mp_server.py
@@ -0,0 +1,346 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""OTel tracing subscriber for MP server operations.
+
+Creates a root ``"request"`` span per session wrapping all child spans.
+Opens at ``MP_REQUEST_START``; closes at ``MP_REQUEST_END``, deferred until
+any in-flight GPU store/retrieve callbacks complete.
+
+Accepts an optional :class:`~lmcache.v1.mp_observability.subscribers.tracing\
+.span_registry.SpanRegistry` so other subscribers can nest spans under the
+root or any child span — see
+``docs/design/observability/request-event-span.md`` for examples.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import SpanRegistry
+
+logger = init_logger(__name__)
+
+try:
+    # Third Party
+    from opentelemetry import trace
+
+    _tracer = trace.get_tracer("lmcache_mp.server")
+    _HAS_OTEL = True
+except ImportError:
+    _HAS_OTEL = False
+
+
+class MPServerTracingSubscriber(EventSubscriber):
+    """Creates OTel spans from MP server events with a per-request root span.
+
+    Each session gets one root ``"request"`` span that nests all child spans
+    (``mp.lookup_prefetch``, ``mp.retrieve``, ``mp.store``) beneath it.
+
+    The root span is opened eagerly at ``MP_REQUEST_START`` and closed at
+    ``MP_REQUEST_END``, with deferral if GPU stores are still in flight.
+    """
+
+    # Maps START event types to span names
+    _SPAN_NAMES: dict[EventType, str] = {
+        EventType.MP_STORE_START: "mp.store",
+        EventType.MP_RETRIEVE_START: "mp.retrieve",
+        EventType.MP_LOOKUP_PREFETCH_START: "mp.lookup_prefetch",
+    }
+
+    _END_TO_START: dict[EventType, EventType] = {
+        EventType.MP_STORE_END: EventType.MP_STORE_START,
+        EventType.MP_RETRIEVE_END: EventType.MP_RETRIEVE_START,
+        EventType.MP_LOOKUP_PREFETCH_END: EventType.MP_LOOKUP_PREFETCH_START,
+    }
+
+    # Logical registry names for child spans.  When a child span is opened it
+    # is also stored under this name in the shared registry so that other
+    # subscribers (or future sub-span subscribers) can look up its context as
+    # a parent without coupling to this class.
+    _LOGICAL_NAMES: dict[EventType, str] = {
+        EventType.MP_STORE_START: "store",
+        EventType.MP_RETRIEVE_START: "retrieve",
+        EventType.MP_LOOKUP_PREFETCH_START: "lookup_prefetch",
+    }
+
+    def __init__(self, registry: SpanRegistry | None = None) -> None:
+        # Shared span registry.  When a registry is provided, other subscribers
+        # that share the same instance can look up the root "request" span or
+        # any child span ("store", "retrieve", "lookup_prefetch") as a parent
+        # context.  If None, a private registry is created so that the class
+        # remains usable without a shared registry.
+        self._registry = registry if registry is not None else SpanRegistry()
+
+        # session_id -> (span, start_event_type) for pending child spans
+        self._pending: dict[str, tuple[Any, EventType]] = {}
+
+        # session_id -> number of MP_STORE_SUBMITTED events without a
+        # matching MP_STORE_END; guards against REQUEST_END racing GPU stores
+        self._pending_store_count: dict[str, int] = {}
+
+        # session_id -> number of MP_RETRIEVE_SUBMITTED events without a
+        # matching MP_RETRIEVE_END; guards against REQUEST_END racing GPU retrieves
+        self._pending_retrieve_count: dict[str, int] = {}
+
+        # session_id -> REQUEST_END timestamp saved when stores/retrieves are in
+        # flight; the last MP_STORE_END / MP_RETRIEVE_END uses this to close the
+        # root span
+        self._deferred_session_end_ts: dict[str, float] = {}
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        """Return the event-to-callback mapping for this subscriber."""
+        return {
+            EventType.MP_REQUEST_START: self._on_request_start,
+            EventType.MP_STORE_SUBMITTED: self._on_store_submitted,
+            EventType.MP_RETRIEVE_SUBMITTED: self._on_retrieve_submitted,
+            EventType.MP_REQUEST_END: self._on_session_end,
+            EventType.MP_STORE_START: self._on_start,
+            EventType.MP_STORE_END: self._on_end,
+            EventType.MP_RETRIEVE_START: self._on_start,
+            EventType.MP_RETRIEVE_END: self._on_end,
+            EventType.MP_LOOKUP_PREFETCH_START: self._on_start,
+            EventType.MP_LOOKUP_PREFETCH_END: self._on_end,
+        }
+
+    # ------------------------------------------------------------------
+    # Public lifecycle
+    # ------------------------------------------------------------------
+
+    def shutdown(self) -> None:
+        """End all leaked spans on bus shutdown."""
+        for key, (span, _) in self._pending.items():
+            try:
+                span.end()
+            except Exception:
+                pass
+        self._pending.clear()
+
+        sessions = (
+            set(self._pending_store_count)
+            | set(self._pending_retrieve_count)
+            | set(self._deferred_session_end_ts)
+            | self._registry.all_session_ids()
+        )
+        for sid in sessions:
+            self._registry.clear_session(sid)
+        self._pending_store_count.clear()
+        self._pending_retrieve_count.clear()
+        self._deferred_session_end_ts.clear()
+
+    # ------------------------------------------------------------------
+    # Root span handlers
+    # ------------------------------------------------------------------
+
+    def _on_request_start(self, event: Event) -> None:
+        """Create the root span eagerly at true request arrival.
+
+        Args:
+            event: ``MP_REQUEST_START`` event with ``session_id`` set.
+        """
+        if not _HAS_OTEL:
+            return
+        self._get_or_create_request_span(event.session_id, event.timestamp)
+
+    def _on_store_submitted(self, event: Event) -> None:
+        """Increment the in-flight store counter for the session.
+
+        Called CPU-synchronously before the GPU store is enqueued, ensuring
+        the counter is non-zero before ``MP_REQUEST_END`` can arrive.
+
+        Args:
+            event: ``MP_STORE_SUBMITTED`` event.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        self._pending_store_count[sid] = self._pending_store_count.get(sid, 0) + 1
+
+    def _on_retrieve_submitted(self, event: Event) -> None:
+        """Increment the in-flight retrieve counter for the session.
+
+        Called CPU-synchronously before the GPU retrieve is enqueued, ensuring
+        the counter is non-zero before ``MP_REQUEST_END`` can arrive.
+
+        Args:
+            event: ``MP_RETRIEVE_SUBMITTED`` event.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        self._pending_retrieve_count[sid] = self._pending_retrieve_count.get(sid, 0) + 1
+
+    def _on_session_end(self, event: Event) -> None:
+        """Close the root span, or defer if GPU stores/retrieves are still in flight.
+
+        Args:
+            event: ``MP_REQUEST_END`` event carrying the logical end timestamp.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        if (
+            self._pending_store_count.get(sid, 0) == 0
+            and self._pending_retrieve_count.get(sid, 0) == 0
+        ):
+            self._close_request_span(sid, event.timestamp)
+        else:
+            # Stores/retrieves still in flight — save timestamp; the last
+            # MP_STORE_END / MP_RETRIEVE_END closes the root span
+            self._deferred_session_end_ts[sid] = event.timestamp
+
+    # ------------------------------------------------------------------
+    # Child span handlers
+    # ------------------------------------------------------------------
+
+    def _on_start(self, event: Event) -> None:
+        """Create a child span nested under the root span.
+
+        Falls back to ``_get_or_create_request_span`` if ``MP_REQUEST_START`` was
+        never emitted (e.g. store-only path with no lookup).
+
+        Args:
+            event: One of ``MP_STORE_START``, ``MP_RETRIEVE_START``, or
+                ``MP_LOOKUP_PREFETCH_START``.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        _, root_ctx = self._get_or_create_request_span(sid, event.timestamp)
+
+        span_name = self._SPAN_NAMES[event.event_type]
+        span = _tracer.start_span(
+            span_name,
+            context=root_ctx,
+            start_time=int(event.timestamp * 1e9),
+        )
+        for k, v in event.metadata.items():
+            span.set_attribute(k, str(v))
+        span.set_attribute("session_id", sid)
+
+        key = f"{sid}:{event.event_type.value}"
+        self._pending[key] = (span, event.event_type)
+
+        # Also register in the shared registry so other subscribers can use
+        # this span as a parent context for nested sub-spans.
+        logical = self._LOGICAL_NAMES.get(event.event_type)
+        if logical:
+            self._registry.open(sid, logical, span, trace.set_span_in_context(span))
+
+    def _on_end(self, event: Event) -> None:
+        """Close a pending child span and handle store-count deferral.
+
+        On ``MP_STORE_END``: decrements the store counter; if it reaches zero
+        and a deferred session-end timestamp exists, closes the root span.
+
+        Args:
+            event: One of ``MP_STORE_END``, ``MP_RETRIEVE_END``, or
+                ``MP_LOOKUP_PREFETCH_END``.
+        """
+        if not _HAS_OTEL:
+            return
+        sid = event.session_id
+        start_type = self._END_TO_START[event.event_type]
+        key = f"{sid}:{start_type.value}"
+        entry = self._pending.pop(key, None)
+        if entry is None:
+            logger.debug(
+                "No pending span for %s session=%s",
+                event.event_type.value,
+                sid,
+            )
+        else:
+            span, _ = entry
+            for k, v in event.metadata.items():
+                span.set_attribute(k, str(v))
+            span.end(end_time=int(event.timestamp * 1e9))
+
+        # Remove the child span from the shared registry now that it is closed.
+        logical = self._LOGICAL_NAMES.get(start_type)
+        if logical:
+            self._registry.pop(sid, logical)
+
+        if event.event_type == EventType.MP_LOOKUP_PREFETCH_END:
+            root_entry = self._registry.get(sid, "request")
+            if root_entry is not None:
+                root_span, _ = root_entry
+                hit_tokens = int(event.metadata.get("hit_tokens", 0))
+                requested_tokens = int(event.metadata.get("requested_tokens", 0))
+                hit_rate = (
+                    hit_tokens / requested_tokens if requested_tokens > 0 else 0.0
+                )
+                root_span.set_attribute("hit_tokens", hit_tokens)
+                root_span.set_attribute("requested_tokens", requested_tokens)
+                root_span.set_attribute("hit_rate", hit_rate)
+
+        if event.event_type == EventType.MP_STORE_END:
+            if (count := self._pending_store_count.get(sid, 0)) > 0:
+                self._pending_store_count[sid] = count - 1
+        elif event.event_type == EventType.MP_RETRIEVE_END:
+            if (count := self._pending_retrieve_count.get(sid, 0)) > 0:
+                self._pending_retrieve_count[sid] = count - 1
+
+        if (
+            sid in self._deferred_session_end_ts
+            and self._pending_store_count.get(sid, 0) == 0
+            and self._pending_retrieve_count.get(sid, 0) == 0
+        ):
+            deferred_ts = self._deferred_session_end_ts.pop(sid)
+            self._close_request_span(sid, deferred_ts)
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _get_or_create_request_span(
+        self, session_id: str, ts: float
+    ) -> tuple[Any, Any]:
+        """Return the root span and its OTel context, creating them if absent.
+
+        The span is stored in the registry under ``span_name="request"`` so
+        that other subscribers sharing the same :class:`SpanRegistry` can
+        retrieve the parent context via
+        ``registry.get_context(session_id, "request")``.
+
+        Args:
+            session_id: The request session identifier.
+            ts: Wall-clock timestamp (``time.time()``) to use as span start
+                if the root is created now.
+
+        Returns:
+            ``(root_span, root_otel_context)`` tuple.
+        """
+        entry = self._registry.get(session_id, "request")
+        if entry is not None:
+            return entry
+        root_span = _tracer.start_span(
+            "request",
+            start_time=int(ts * 1e9),
+        )
+        root_span.set_attribute("session_id", session_id)
+        root_ctx = trace.set_span_in_context(root_span)
+        self._registry.open(session_id, "request", root_span, root_ctx)
+        return root_span, root_ctx
+
+    def _close_request_span(self, session_id: str, end_ts: float) -> None:
+        """End the root span and clean up all per-session state.
+
+        Args:
+            session_id: The request session identifier.
+            end_ts: Wall-clock timestamp to stamp as the span end time.
+        """
+        entry = self._registry.pop(session_id, "request")
+        if entry is not None:
+            root_span, _ = entry
+            try:
+                root_span.end(end_time=int(end_ts * 1e9))
+            except Exception:
+                pass
+        self._pending_store_count.pop(session_id, None)
+        self._pending_retrieve_count.pop(session_id, None)
+        self._deferred_session_end_ts.pop(session_id, None)
diff --git a/lmcache/v1/mp_observability/subscribers/tracing/span_registry.py b/lmcache/v1/mp_observability/subscribers/tracing/span_registry.py
new file mode 100644
index 0000000..79753c6
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/tracing/span_registry.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared OTel span registry for cross-subscriber context propagation.
+
+:class:`SpanRegistry` stores active spans keyed by ``(session_id, span_name)``
+so that multiple subscribers sharing the same instance can look up parent
+span contexts without tight coupling.
+
+All reads and writes happen on the single EventBus drain thread — no locking
+is needed.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class SpanRegistry:
+    """Registry of active OTel spans, keyed by ``(session_id, span_name)``.
+
+    ``span_name`` is a logical identifier (e.g. ``"request"``, ``"retrieve"``,
+    ``"store"``) that decouples parent-lookup from the concrete OTel span name.
+
+    All methods must be called from the EventBus drain thread; no locking is
+    performed.
+
+    Example usage across two subscribers that share one registry::
+
+        registry = SpanRegistry()
+        bus.register_subscriber(MPServerTracingSubscriber(registry))
+        bus.register_subscriber(MyL1TracingSubscriber(registry))
+
+        # Inside MyL1TracingSubscriber._on_l1_start:
+        parent_ctx = registry.get_context(session_id, "retrieve") \\
+                     or registry.get_context(session_id, "request")
+        span = tracer.start_span("l1.read", context=parent_ctx, ...)
+    """
+
+    def __init__(self) -> None:
+        # (session_id, span_name) -> (span, otel_context)
+        self._active: dict[tuple[str, str], tuple[Any, Any]] = {}
+
+    def open(self, session_id: str, span_name: str, span: Any, ctx: Any) -> None:
+        """Register an open span and its OTel context.
+
+        Args:
+            session_id: The request session identifier.
+            span_name: Logical name for the span (e.g. ``"request"``,
+                ``"retrieve"``).
+            span: The OTel span object.
+            ctx: The OTel context containing the span (from
+                ``trace.set_span_in_context(span)``).
+        """
+        self._active[(session_id, span_name)] = (span, ctx)
+
+    def get(self, session_id: str, span_name: str) -> tuple[Any, Any] | None:
+        """Return ``(span, context)`` for an open span, or ``None``.
+
+        Args:
+            session_id: The request session identifier.
+            span_name: Logical span name to look up.
+
+        Returns:
+            ``(span, otel_context)`` if the span is registered, else ``None``.
+        """
+        return self._active.get((session_id, span_name))
+
+    def get_context(self, session_id: str, span_name: str) -> Any | None:
+        """Return the OTel context for an open span, or ``None``.
+
+        Convenience wrapper over :meth:`get` for callers that only need the
+        context to pass as a ``context=`` argument when starting a child span.
+
+        Args:
+            session_id: The request session identifier.
+            span_name: Logical span name to look up.
+
+        Returns:
+            The OTel context, or ``None`` if the span is not registered.
+        """
+        entry = self._active.get((session_id, span_name))
+        return entry[1] if entry is not None else None
+
+    def pop(self, session_id: str, span_name: str) -> tuple[Any, Any] | None:
+        """Remove and return ``(span, context)``, or ``None`` if absent.
+
+        Args:
+            session_id: The request session identifier.
+            span_name: Logical span name to remove.
+
+        Returns:
+            ``(span, otel_context)`` if the span was registered, else ``None``.
+        """
+        return self._active.pop((session_id, span_name), None)
+
+    def all_session_ids(self) -> set[str]:
+        """Return the set of session IDs that have at least one open span.
+
+        Returns:
+            Set of session ID strings currently tracked in the registry.
+        """
+        return {k[0] for k in self._active}
+
+    def clear_session(self, session_id: str) -> None:
+        """End all open spans for *session_id* and remove them.
+
+        Intended for use in ``shutdown()`` to clean up leaked spans when the
+        EventBus stops unexpectedly.
+
+        Args:
+            session_id: The request session identifier to clean up.
+        """
+        keys = [k for k in self._active if k[0] == session_id]
+        for k in keys:
+            span, _ = self._active.pop(k)
+            try:
+                span.end()
+            except Exception:
+                logger.debug(
+                    "SpanRegistry: error ending leaked span for session %s key %s",
+                    session_id,
+                    k[1],
+                )
+
+
+_registry: SpanRegistry | None = None
+
+
+def get_span_registry() -> SpanRegistry:
+    """Return the process-level singleton :class:`SpanRegistry`.
+
+    The registry is created on first call.  Pass a fresh :class:`SpanRegistry`
+    directly to subscriber constructors when test isolation is needed.
+
+    Returns:
+        The shared :class:`SpanRegistry` instance.
+    """
+    global _registry
+    if _registry is None:
+        _registry = SpanRegistry()
+    return _registry
diff --git a/lmcache/v1/mp_observability/subscribers/tracing/timeout.py b/lmcache/v1/mp_observability/subscribers/tracing/timeout.py
new file mode 100644
index 0000000..23cae75
--- /dev/null
+++ b/lmcache/v1/mp_observability/subscribers/tracing/timeout.py
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""OTel span for timeout errors.
+
+Records each ``TIMEOUT_RAISED`` as a zero-duration ``timeout`` span with an
+``exception`` event (type/message/stacktrace) and ERROR status, nested under
+the request span when ``session_id`` matches an open one.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import SpanRegistry
+
+logger = init_logger(__name__)
+
+try:
+    # Third Party
+    from opentelemetry import trace
+    from opentelemetry.trace import Status, StatusCode
+
+    _tracer = trace.get_tracer("lmcache_mp.timeout")
+    _HAS_OTEL = True
+except ImportError:
+    _HAS_OTEL = False
+
+
+class TimeoutTracingSubscriber(EventSubscriber):
+    """Records each ``TIMEOUT_RAISED`` event as an OTel span.
+
+    Args:
+        registry: Shared span registry for finding the request span to nest
+            under; a private one is used when omitted (spans are then roots).
+    """
+
+    def __init__(self, registry: SpanRegistry | None = None) -> None:
+        self._registry = registry if registry is not None else SpanRegistry()
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {EventType.TIMEOUT_RAISED: self._on_timeout}
+
+    def _on_timeout(self, event: Event) -> None:
+        if not _HAS_OTEL:
+            return
+        parent_ctx = (
+            self._registry.get_context(event.session_id, "request")
+            if event.session_id
+            else None
+        )
+        start_ns = int(event.timestamp * 1e9)
+        message = str(event.metadata.get("message", ""))
+        exception_type = str(event.metadata.get("exception_type", "TimeoutError"))
+
+        span = _tracer.start_span("timeout", context=parent_ctx, start_time=start_ns)
+        span.set_attribute("session_id", event.session_id)
+        span.add_event(
+            "exception",
+            attributes={
+                "exception.type": exception_type,
+                "exception.message": message,
+                "exception.stacktrace": str(event.metadata.get("stacktrace", "")),
+            },
+            timestamp=start_ns,
+        )
+        span.set_status(Status(StatusCode.ERROR, message))
+        span.end(end_time=start_ns)
diff --git a/lmcache/v1/mp_observability/trace/__init__.py b/lmcache/v1/mp_observability/trace/__init__.py
new file mode 100644
index 0000000..db2db0f
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/__init__.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Trace recording subsystem.
+
+This package implements the **capture** half of the ``lmcache trace``
+feature.  Public API:
+
+* :func:`~lmcache.v1.mp_observability.trace.decorator.enable_tracing` —
+  decorator that publishes a unified ``TRACE_CALL`` event on each call
+  to a decorated function (entry-only, inputs only).
+* :class:`~lmcache.v1.mp_observability.trace.recorder.StorageTraceRecorder`
+  — :class:`EventSubscriber` that writes ``TRACE_CALL`` events to a
+  binary trace file.
+* :class:`~lmcache.v1.mp_observability.trace.reader.TraceReader` —
+  streaming reader for inspection (replay lives in a separate package).
+
+When tracing is disabled (the default), the decorator is a thin
+wrapper around the original function; only a single boolean attribute
+load is added per call.
+"""
+
+# First Party
+from lmcache.v1.mp_observability.trace.decorator import (
+    enable_tracing,
+    is_tracing_enabled,
+    publish_call_event,
+    set_tracing_enabled,
+)
+from lmcache.v1.mp_observability.trace.format import Header, Record
+from lmcache.v1.mp_observability.trace.lifecycle import (
+    maybe_initialize_trace_recorder,
+)
+from lmcache.v1.mp_observability.trace.reader import TraceReader
+from lmcache.v1.mp_observability.trace.recorder import (
+    StorageTraceRecorder,
+    TraceRecorder,
+)
+
+__all__ = [
+    "Header",
+    "Record",
+    "StorageTraceRecorder",
+    "TraceReader",
+    "TraceRecorder",
+    "enable_tracing",
+    "is_tracing_enabled",
+    "maybe_initialize_trace_recorder",
+    "publish_call_event",
+    "set_tracing_enabled",
+]
diff --git a/lmcache/v1/mp_observability/trace/codecs.py b/lmcache/v1/mp_observability/trace/codecs.py
new file mode 100644
index 0000000..da9f1e7
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/codecs.py
@@ -0,0 +1,316 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Type codecs for trace argument serialization.
+
+The trace recorder needs to serialize arbitrary Python values that
+appear as arguments to decorated functions.  Msgpack natively handles
+``int``, ``float``, ``str``, ``bytes``, ``bool``, ``None``, ``list``,
+``tuple``, ``dict``.  Anything else needs an explicit codec.
+
+A codec is a pair ``(encode, decode)`` keyed on a Python type.  At
+encode time the value is wrapped in a ``{"__t__": tag, "v": payload}``
+dict so the decoder can recognize it without losing the round-trip.
+
+This registry is shared between the recorder (PR1, encode-only path
+exercised) and the replay driver (PR2, decode-only path).  Both halves
+ship together to keep the format and behavior coherent.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import Any, Callable
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import (
+    AttnWindowDesc,
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchHandle,
+    PrefetchMode,
+    TrimPolicy,
+)
+
+
+@dataclass(frozen=True)
+class TypeCodec:
+    """Encode/decode pair for a single Python type."""
+
+    tag: str
+    encode: Callable[[Any], Any]
+    decode: Callable[[Any], Any]
+
+
+# Tag dispatch table populated by ``register_codec``.  Keyed by type.
+_BY_TYPE: dict[type, TypeCodec] = {}
+# Tag dispatch table for decode.  Keyed by tag string.
+_BY_TAG: dict[str, TypeCodec] = {}
+
+_WRAP_KEY = "__t__"
+_VALUE_KEY = "v"
+
+
+def register_codec(t: type, codec: TypeCodec) -> None:
+    """Register a codec for type ``t``.
+
+    Raises:
+        ValueError: If ``t`` or ``codec.tag`` is already registered.
+    """
+    if t in _BY_TYPE:
+        raise ValueError(f"codec already registered for type {t!r}")
+    if codec.tag in _BY_TAG:
+        raise ValueError(f"codec tag {codec.tag!r} already in use")
+    _BY_TYPE[t] = codec
+    _BY_TAG[codec.tag] = codec
+
+
+# ---------------------------------------------------------------------------
+# Encode / decode entry points
+# ---------------------------------------------------------------------------
+
+# Native msgpack types pass through unchanged.  Everything else must be
+# wrapped via a registered codec.
+_PASSTHROUGH = (int, float, str, bytes, bool, type(None))
+
+
+def encode_value(v: Any) -> Any:
+    """Encode ``v`` to a msgpack-friendly representation.
+
+    Recursively encodes lists, tuples, and dicts.  Tuples are preserved
+    via a tag so they can be decoded back to tuples (msgpack would
+    otherwise round-trip them as lists).
+
+    Raises:
+        TypeError: If ``v`` is of a type with no registered codec.
+    """
+    # Codec lookup by exact type takes priority so that registered
+    # types which happen to subclass ``tuple`` (e.g. ``torch.Size``) are
+    # handled by their codec rather than the generic tuple branch.
+    codec = _BY_TYPE.get(type(v))
+    if codec is not None:
+        return {_WRAP_KEY: codec.tag, _VALUE_KEY: codec.encode(v)}
+
+    if isinstance(v, _PASSTHROUGH):
+        return v
+    if isinstance(v, list):
+        return [encode_value(x) for x in v]
+    if isinstance(v, tuple):
+        return {_WRAP_KEY: "tuple", _VALUE_KEY: [encode_value(x) for x in v]}
+    if isinstance(v, dict):
+        # Dict keys must already be strings/ints for msgpack.  We do not
+        # encode keys, only values, to keep the on-wire form readable.
+        return {k: encode_value(x) for k, x in v.items()}
+
+    raise TypeError(
+        f"trace.codecs: no codec registered for type {type(v).__name__!r} "
+        f"(value={v!r}). Register one via register_codec() or extend "
+        f"the default registry."
+    )
+
+
+def decode_value(v: Any) -> Any:
+    """Decode a msgpack-deserialized value back to its native form.
+
+    Raises:
+        ValueError: If a wrapped value carries an unknown tag.
+    """
+    if isinstance(v, list):
+        return [decode_value(x) for x in v]
+    if isinstance(v, dict):
+        tag = v.get(_WRAP_KEY)
+        if tag is None:
+            return {k: decode_value(x) for k, x in v.items()}
+        if tag == "tuple":
+            return tuple(decode_value(x) for x in v[_VALUE_KEY])
+        codec = _BY_TAG.get(tag)
+        if codec is None:
+            raise ValueError(f"trace.codecs: unknown tag {tag!r}")
+        return codec.decode(v[_VALUE_KEY])
+    return v
+
+
+def encode_args(args: dict[str, Any]) -> dict[str, Any]:
+    """Encode an argument dict for serialization."""
+    return {k: encode_value(v) for k, v in args.items()}
+
+
+def decode_args(args: dict[str, Any]) -> dict[str, Any]:
+    """Decode an argument dict back to native values."""
+    return {k: decode_value(v) for k, v in args.items()}
+
+
+# ---------------------------------------------------------------------------
+# Default codecs for LMCache types
+# ---------------------------------------------------------------------------
+
+
+def _enc_object_key(k: ObjectKey) -> dict[str, Any]:
+    return {
+        "chunk_hash": k.chunk_hash,
+        "model_name": k.model_name,
+        "kv_rank": k.kv_rank,
+        "object_group_id": k.object_group_id,
+    }
+
+
+def _dec_object_key(d: dict[str, Any]) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=d["chunk_hash"],
+        model_name=d["model_name"],
+        kv_rank=d["kv_rank"],
+        object_group_id=d.get("object_group_id", 0),
+    )
+
+
+def _enc_layout_desc(d: MemoryLayoutDesc) -> dict[str, Any]:
+    return {
+        "shapes": [list(s) for s in d.shapes],
+        "dtypes": [str(dt) for dt in d.dtypes],
+    }
+
+
+# Mapping from str(torch.dtype) back to the dtype object.  Built lazily
+# the first time a layout desc is decoded.
+_DTYPE_BY_NAME: dict[str, torch.dtype] = {}
+
+
+def _resolve_dtype(name: str) -> torch.dtype:
+    if not _DTYPE_BY_NAME:
+        for attr in dir(torch):
+            obj = getattr(torch, attr)
+            if isinstance(obj, torch.dtype):
+                _DTYPE_BY_NAME[str(obj)] = obj
+    dtype = _DTYPE_BY_NAME.get(name)
+    if dtype is None:
+        raise ValueError(f"trace.codecs: unknown torch dtype {name!r}")
+    return dtype
+
+
+def _dec_layout_desc(d: dict[str, Any]) -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(
+        shapes=[torch.Size(s) for s in d["shapes"]],
+        dtypes=[_resolve_dtype(dt) for dt in d["dtypes"]],
+    )
+
+
+def _enc_prefetch_handle(h: PrefetchHandle) -> dict[str, Any]:
+    return {
+        "prefetch_request_id": h.prefetch_request_id,
+        "external_request_id": h.external_request_id,
+        # Derived count kept for readable traces; decode rebuilds from indices.
+        "l1_prefix_hit_count": len(h.l1_found_indices),
+        "l1_found_indices": list(h.l1_found_indices),
+        "total_requested_keys": h.total_requested_keys,
+        "submit_time": h.submit_time,
+        "l2_orig_indices": list(h.l2_orig_indices),
+    }
+
+
+def _dec_prefetch_handle(d: dict[str, Any]) -> PrefetchHandle:
+    return PrefetchHandle(
+        prefetch_request_id=d["prefetch_request_id"],
+        external_request_id=d["external_request_id"],
+        l1_found_indices=tuple(d["l1_found_indices"]),
+        total_requested_keys=d["total_requested_keys"],
+        submit_time=d["submit_time"],
+        l2_orig_indices=tuple(d.get("l2_orig_indices", ())),
+    )
+
+
+def _enc_torch_size(s: torch.Size) -> list[int]:
+    return list(s)
+
+
+def _dec_torch_size(s: list[int]) -> torch.Size:
+    return torch.Size(s)
+
+
+def _enc_torch_dtype(dt: torch.dtype) -> str:
+    return str(dt)
+
+
+def _dec_torch_dtype(name: str) -> torch.dtype:
+    return _resolve_dtype(name)
+
+
+def _enc_trim_policy(p: TrimPolicy) -> str:
+    return p.name
+
+
+def _dec_trim_policy(name: str) -> TrimPolicy:
+    return TrimPolicy[name]
+
+
+def _enc_prefetch_mode(m: PrefetchMode) -> str:
+    return m.name
+
+
+def _dec_prefetch_mode(name: str) -> PrefetchMode:
+    return PrefetchMode[name]
+
+
+def _enc_attn_window(d: AttnWindowDesc) -> list[int]:
+    return list(d.num_chunks_in_sw)
+
+
+def _dec_attn_window(num_chunks_in_sw: list[int]) -> AttnWindowDesc:
+    return AttnWindowDesc(num_chunks_in_sw=list(num_chunks_in_sw))
+
+
+def _enc_set(s: set) -> list:
+    return [encode_value(x) for x in s]
+
+
+def _dec_set(items: list) -> set:
+    return {decode_value(x) for x in items}
+
+
+register_codec(
+    ObjectKey,
+    TypeCodec(tag="ObjectKey", encode=_enc_object_key, decode=_dec_object_key),
+)
+register_codec(
+    MemoryLayoutDesc,
+    TypeCodec(
+        tag="MemoryLayoutDesc",
+        encode=_enc_layout_desc,
+        decode=_dec_layout_desc,
+    ),
+)
+register_codec(
+    PrefetchHandle,
+    TypeCodec(
+        tag="PrefetchHandle",
+        encode=_enc_prefetch_handle,
+        decode=_dec_prefetch_handle,
+    ),
+)
+register_codec(
+    torch.Size,
+    TypeCodec(tag="torch.Size", encode=_enc_torch_size, decode=_dec_torch_size),
+)
+register_codec(
+    torch.dtype,
+    TypeCodec(tag="torch.dtype", encode=_enc_torch_dtype, decode=_dec_torch_dtype),
+)
+register_codec(
+    AttnWindowDesc,
+    TypeCodec(tag="AttnWindowDesc", encode=_enc_attn_window, decode=_dec_attn_window),
+)
+register_codec(
+    TrimPolicy,
+    TypeCodec(tag="TrimPolicy", encode=_enc_trim_policy, decode=_dec_trim_policy),
+)
+register_codec(
+    PrefetchMode,
+    TypeCodec(tag="PrefetchMode", encode=_enc_prefetch_mode, decode=_dec_prefetch_mode),
+)
+register_codec(
+    set,
+    TypeCodec(tag="set", encode=_enc_set, decode=_dec_set),
+)
diff --git a/lmcache/v1/mp_observability/trace/decorator.py b/lmcache/v1/mp_observability/trace/decorator.py
new file mode 100644
index 0000000..b0f3b2a
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/decorator.py
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""``@enable_tracing`` decorator for capturing function calls.
+
+The decorator publishes a single :data:`EventType.TRACE_CALL` event on
+**function entry** (inputs only).  Output values and exceptions are not
+captured — replay re-runs the function and observes the live outcome.
+
+The decorator imposes near-zero overhead when tracing is disabled: a
+single boolean attribute load is added to each call.  Argument
+introspection is performed only when the gate is on.
+
+Codecs that turn LMCache-specific argument types into msgpack-friendly
+forms live in :mod:`lmcache.v1.mp_observability.trace.codecs`.  The
+decorator deliberately does not import them; raw Python values are
+attached to the event and the recorder encodes at write time.  This
+keeps the decorator import-cheap and breaks an otherwise circular
+dependency (``StorageManager → decorator → codecs → StorageManager``).
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from functools import wraps
+from typing import Any, Callable, Sequence, TypeVar
+import inspect
+import time
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Module-level gate.  Flipped on by the trace recorder when it
+# registers, off when it shuts down.  A simple bool is sufficient
+# (tracing capture is single-process; mutual visibility across threads
+# is not required for correctness — at worst a few events are missed
+# during the toggle window).
+_tracing_enabled: bool = False
+
+
+def is_tracing_enabled() -> bool:
+    """Return whether the trace gate is currently on."""
+    return _tracing_enabled
+
+
+def set_tracing_enabled(enabled: bool) -> None:
+    """Flip the trace gate.
+
+    Called by trace recorders during ``__init__`` (on) and ``close()``
+    (off).  Direct callers should not normally use this.
+    """
+    global _tracing_enabled
+    _tracing_enabled = enabled
+
+
+def publish_call_event(qualname: str, args: dict[str, Any]) -> None:
+    """Publish one ``TRACE_CALL`` event.
+
+    Used by :func:`enable_tracing` and by manual instrumentation
+    points (e.g. context-manager enter/exit) that cannot be wrapped
+    by the decorator.
+
+    Args:
+        qualname: Fully-qualified name of the call site.
+        args: Mapping of argument name to raw Python value.  Codec
+            encoding happens later, in the recorder.
+
+    ``time.monotonic()`` is sampled **here** (not on the drain thread)
+    so the recorded ``t_mono`` aligns with ``Event.timestamp`` —
+    otherwise the two clocks would drift by however long the drain
+    lagged behind the publisher.
+    """
+    if not _tracing_enabled:
+        return
+    t_mono = time.monotonic()
+    bus = get_event_bus()
+    bus.publish(
+        Event(
+            event_type=EventType.TRACE_CALL,
+            metadata={"qualname": qualname, "args": args, "t_mono": t_mono},
+        )
+    )
+
+
+def enable_tracing(
+    qualname: str | None = None,
+    capture: Sequence[str] | None = None,
+    redact: Sequence[str] = (),
+) -> Callable[[F], F]:
+    """Decorate a function so its calls publish ``TRACE_CALL`` events.
+
+    Args:
+        qualname: Fully-qualified call-site name placed in the event
+            metadata.  Defaults to ``f"{func.__module__}.{func.__qualname__}"``.
+        capture: If given, only these argument names are recorded.
+            ``None`` means capture every parameter except ``self`` and
+            ``cls``.
+        redact: Argument names that must not be recorded.  Applied
+            after ``capture``.
+
+    Returns:
+        A decorator that wraps the target function.
+
+    The signature is bound once at decoration time via
+    :func:`inspect.signature`, so per-call overhead is limited to a
+    bool check (when disabled) or a ``Signature.bind_partial`` plus
+    dict-comprehension (when enabled).
+    """
+    redact_set = frozenset(redact)
+    capture_set = frozenset(capture) if capture is not None else None
+
+    def deco(func: F) -> F:
+        sig = inspect.signature(func)
+        resolved_qualname = qualname or f"{func.__module__}.{func.__qualname__}"
+
+        # Pre-compute parameter names to record.  ``self`` and ``cls``
+        # are always dropped — recording the receiver object yields no
+        # useful information for replay and would force a codec for
+        # every receiver type.
+        param_names = [
+            name
+            for name in sig.parameters
+            if name not in ("self", "cls")
+            and (capture_set is None or name in capture_set)
+            and name not in redact_set
+        ]
+        param_set = frozenset(param_names)
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            if _tracing_enabled:
+                bound = sig.bind_partial(*args, **kwargs)
+                bound.apply_defaults()
+                payload = {k: v for k, v in bound.arguments.items() if k in param_set}
+                publish_call_event(resolved_qualname, payload)
+            return func(*args, **kwargs)
+
+        # Expose the resolved metadata for tests and dispatcher
+        # registration.
+        wrapper.__lmc_trace_qualname__ = resolved_qualname  # type: ignore[attr-defined]
+        wrapper.__lmc_trace_params__ = tuple(param_names)  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+    return deco
diff --git a/lmcache/v1/mp_observability/trace/format.py b/lmcache/v1/mp_observability/trace/format.py
new file mode 100644
index 0000000..6d4ef95
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/format.py
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""On-disk format for trace files.
+
+A trace file is a length-prefixed msgpack stream:
+
+    [4-byte big-endian frame length][msgpack frame]
+    [4-byte big-endian frame length][msgpack frame]
+    ...
+
+The first frame is always a :class:`Header`.  All subsequent frames
+are :class:`Record` objects.  Length-prefixing keeps the reader
+simple and supports concurrent appenders (each frame is atomic on
+local filesystems for sizes below ``PIPE_BUF``).
+
+Format version is policed by the reader.  Unknown versions are
+rejected to make corrupt or future-format files fail loudly rather
+than silently producing garbage.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+import msgspec
+
+#: Magic bytes at the start of every file for sanity checking.  The
+#: reader rejects files that do not begin with these bytes.
+MAGIC: bytes = b"LMCT"
+
+#: Bumped whenever the on-wire framing layout changes in a backwards-
+#: incompatible way (length prefix, header/record struct shape, etc.).
+FORMAT_VERSION: int = 1
+
+#: Bumped whenever the captured API surface changes in a way that makes
+#: older traces undecodable or incorrect to replay — e.g. a traced
+#: StorageManager method gains/loses an argument, an argument type's
+#: codec wire form changes, or a new codec tag is introduced.  Owned by
+#: the trace subsystem, independent of the LMCache package version,
+#: because ``lmcache.__version__`` bumps cover many changes irrelevant
+#: to the trace contract.
+TRACE_SCHEMA_VERSION: int = 1
+
+
+class Header(msgspec.Struct, tag="header", omit_defaults=True):
+    """One-per-file metadata block."""
+
+    magic: bytes
+    """Always :data:`MAGIC`."""
+
+    format_version: int
+    """File format version; readers reject unknown values."""
+
+    level: str
+    """Trace level — currently ``"storage"``.  Future levels (``"mq"``,
+    ``"gpu"``) will share this format."""
+
+    trace_schema_version: int
+    """:data:`TRACE_SCHEMA_VERSION` at record time.  Replay drivers may
+    refuse mismatched schemas rather than silently misinterpreting old
+    traces."""
+
+    t_mono_start: float
+    """``time.monotonic()`` at recorder construction.  Record
+    timestamps are relative to this."""
+
+    t_wall_start: float
+    """``time.time()`` at recorder construction.  Used to correlate
+    with external logs / metrics in absolute wall-clock time."""
+
+    sm_config_json: str
+    """JSON dump of ``StorageManagerConfig`` at record time, or an
+    empty string when not available."""
+
+    sm_config_digest: str
+    """SHA-256 hex digest of :attr:`sm_config_json`.  Replay drivers
+    use this to detect mismatched configurations."""
+
+
+class Record(msgspec.Struct, tag="record", omit_defaults=True):
+    """One captured function call.
+
+    All records share the same shape; the ``qualname`` field
+    differentiates operations.  Future trace levels can introduce new
+    ``qualname`` values without bumping the format version.
+    """
+
+    t_mono: float
+    """Monotonic seconds since :attr:`Header.t_mono_start`."""
+
+    t_wall: float
+    """Wall-clock ``time.time()`` at the moment the event was
+    published."""
+
+    qualname: str
+    """Fully-qualified call-site name (e.g.
+    ``lmcache.v1.distributed.storage_manager.StorageManager.reserve_write``)."""
+
+    args: dict[str, Any]
+    """Codec-encoded argument dict.  See
+    :mod:`lmcache.v1.mp_observability.trace.codecs` for the codec
+    contract."""
+
+
+# msgspec encoders/decoders.  Reused per-process; both are thread-safe
+# after construction.
+_ENCODER = msgspec.msgpack.Encoder()
+_DECODER_HEADER = msgspec.msgpack.Decoder(Header)
+_DECODER_RECORD = msgspec.msgpack.Decoder(Record)
+
+
+def encode_header(h: Header) -> bytes:
+    """Serialize a header to msgpack bytes."""
+    return _ENCODER.encode(h)
+
+
+def encode_record(r: Record) -> bytes:
+    """Serialize a record to msgpack bytes."""
+    return _ENCODER.encode(r)
+
+
+def decode_header(buf: bytes) -> Header:
+    """Parse a header from msgpack bytes."""
+    return _DECODER_HEADER.decode(buf)
+
+
+def decode_record(buf: bytes) -> Record:
+    """Parse a record from msgpack bytes."""
+    return _DECODER_RECORD.decode(buf)
diff --git a/lmcache/v1/mp_observability/trace/lifecycle.py b/lmcache/v1/mp_observability/trace/lifecycle.py
new file mode 100644
index 0000000..01bf9da
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/lifecycle.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Trace recorder lifecycle helpers.
+
+Used by the cache server entry points (``server.py`` and
+``http_server.py``) to construct, register, and tear down trace
+recorders alongside the EventBus.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from datetime import datetime, timezone
+import os
+import tempfile
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.config import StorageManagerConfig
+from lmcache.v1.mp_observability.config import ObservabilityConfig
+from lmcache.v1.mp_observability.event_bus import EventBus
+from lmcache.v1.mp_observability.trace.recorder import (
+    StorageTraceRecorder,
+    TraceRecorder,
+)
+
+logger = init_logger(__name__)
+
+
+def _default_trace_path() -> str:
+    """Mint a timestamped path for an unnamed trace file."""
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    return os.path.join(
+        tempfile.gettempdir(),
+        f"lmcache-trace-{os.getpid()}-{stamp}.lct",
+    )
+
+
+def maybe_initialize_trace_recorder(
+    bus: EventBus,
+    obs_config: ObservabilityConfig,
+    storage_manager_config: StorageManagerConfig,
+) -> TraceRecorder | None:
+    """Construct and register a trace recorder if configured.
+
+    Args:
+        bus: The active EventBus to subscribe the recorder to.
+        obs_config: Observability config carrying the trace flags.
+        storage_manager_config: The StorageManagerConfig in use.  Used
+            to populate the trace file's header digest so a replay
+            driver can detect mismatched configurations.
+
+    Returns:
+        The created recorder, or ``None`` when ``obs_config.trace_level``
+        is unset.
+
+    The recorder is registered on the bus, so :meth:`EventBus.stop`
+    will invoke its ``shutdown`` (which flushes and closes the file).
+    Callers do not need to track the returned reference for cleanup;
+    it is returned only for testing and observation.
+    """
+    level = obs_config.trace_level
+    if not level:
+        return None
+    if level != "storage":
+        raise ValueError(
+            f"unsupported trace level {level!r}; only 'storage' is supported"
+        )
+
+    output_path = obs_config.trace_output or _default_trace_path()
+    if obs_config.trace_output is None:
+        logger.info(
+            "trace recording enabled (level=%s); no --trace-output given, "
+            "writing to %s",
+            level,
+            output_path,
+        )
+
+    recorder = StorageTraceRecorder(output_path=output_path)
+    recorder.attach_storage_config(storage_manager_config)
+    bus.register_subscriber(recorder)
+    return recorder
diff --git a/lmcache/v1/mp_observability/trace/reader.py b/lmcache/v1/mp_observability/trace/reader.py
new file mode 100644
index 0000000..bbbc082
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/reader.py
@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Streaming reader for trace files.
+
+The reader yields ``(Header, Iterator[Record])`` pairs.  Records are
+yielded lazily so that arbitrarily large traces can be inspected
+without loading the whole file into memory.
+
+Trailing partial frames (truncated by SIGKILL or filesystem buffering)
+are detected and the iterator stops cleanly with a WARNING log.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import BinaryIO, Iterator
+import struct
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.trace.format import (
+    FORMAT_VERSION,
+    MAGIC,
+    TRACE_SCHEMA_VERSION,
+    Header,
+    Record,
+    decode_header,
+    decode_record,
+)
+
+logger = init_logger(__name__)
+
+_LEN_STRUCT = struct.Struct(">I")
+_LEN_PREFIX = _LEN_STRUCT.size
+
+
+class TraceReader:
+    """Streaming reader for a binary trace file.
+
+    Usage::
+
+        with TraceReader("/tmp/run.lct") as r:
+            header = r.header
+            for record in r.records():
+                ...
+
+    Closing the reader closes the underlying file handle.
+    """
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._fh: BinaryIO | None = open(path, "rb")
+        try:
+            self._header = self._read_header()
+        except Exception:
+            self._fh.close()
+            self._fh = None
+            raise
+
+    def __enter__(self) -> TraceReader:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    @property
+    def header(self) -> Header:
+        """Return the file header.  Always present; populated by
+        ``__init__``."""
+        return self._header
+
+    @property
+    def path(self) -> str:
+        """Path of the trace file."""
+        return self._path
+
+    def records(self) -> Iterator[Record]:
+        """Yield every record in the file in order.
+
+        Yields each :class:`Record` as it is read.  When the file ends
+        cleanly (boundary aligned to a frame), iteration stops without
+        error.  When a partial trailing frame is detected, a warning
+        is logged and iteration stops.
+        """
+        if self._fh is None:
+            raise RuntimeError("TraceReader is closed")
+        while True:
+            frame = self._read_frame(strict=False)
+            if frame is None:
+                return
+            try:
+                yield decode_record(frame)
+            except Exception as e:
+                logger.warning(
+                    "TraceReader: skipping malformed record at offset %d: %s",
+                    self._fh.tell(),
+                    e,
+                )
+                continue
+
+    def close(self) -> None:
+        """Close the underlying file.  Idempotent."""
+        if self._fh is not None:
+            self._fh.close()
+            self._fh = None
+
+    # ---- internal -----------------------------------------------------
+
+    def _read_header(self) -> Header:
+        frame = self._read_frame(strict=True)
+        if frame is None:
+            raise ValueError(f"trace file {self._path!r} is empty")
+        header = decode_header(frame)
+        if header.magic != MAGIC:
+            raise ValueError(
+                f"trace file {self._path!r}: bad magic "
+                f"(got {header.magic!r}, expected {MAGIC!r})"
+            )
+        if header.format_version != FORMAT_VERSION:
+            raise ValueError(
+                f"trace file {self._path!r}: unsupported format_version "
+                f"{header.format_version} (this build expects {FORMAT_VERSION})"
+            )
+        if header.trace_schema_version != TRACE_SCHEMA_VERSION:
+            raise ValueError(
+                f"trace file {self._path!r}: unsupported trace_schema_version "
+                f"{header.trace_schema_version} "
+                f"(this build expects {TRACE_SCHEMA_VERSION})"
+            )
+        return header
+
+    def _read_frame(self, strict: bool) -> bytes | None:
+        """Read one length-prefixed frame.
+
+        Returns ``None`` on clean EOF (when ``strict=False``).  On
+        truncation in the middle of a frame, logs a WARNING and
+        returns ``None``.  In ``strict=True`` mode, both partial and
+        empty reads raise.
+        """
+        assert self._fh is not None
+        prefix = self._fh.read(_LEN_PREFIX)
+        if not prefix:
+            if strict:
+                raise ValueError("unexpected EOF reading frame length")
+            return None
+        if len(prefix) < _LEN_PREFIX:
+            msg = (
+                f"truncated frame length prefix at offset "
+                f"{self._fh.tell() - len(prefix)}"
+            )
+            if strict:
+                raise ValueError(msg)
+            logger.warning("TraceReader: %s", msg)
+            return None
+        (length,) = _LEN_STRUCT.unpack(prefix)
+        body = self._fh.read(length)
+        if len(body) < length:
+            msg = (
+                f"truncated frame body at offset "
+                f"{self._fh.tell() - len(body)} (got {len(body)} of {length})"
+            )
+            if strict:
+                raise ValueError(msg)
+            logger.warning("TraceReader: %s", msg)
+            return None
+        return body
diff --git a/lmcache/v1/mp_observability/trace/recorder.py b/lmcache/v1/mp_observability/trace/recorder.py
new file mode 100644
index 0000000..2078308
--- /dev/null
+++ b/lmcache/v1/mp_observability/trace/recorder.py
@@ -0,0 +1,300 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Trace recorder — writes TRACE_CALL events to a binary file.
+
+Architecture:
+
+* The recorder is an :class:`EventSubscriber` registered on the global
+  EventBus.  Subscriber callbacks run on the EventBus drain thread, so
+  they are already off the request path.
+* Encoding (codec + msgpack) and disk I/O happen synchronously inside
+  the callback.  Adding a second worker thread would be premature
+  optimization; the EventBus drain thread already serves that role.
+* Length-prefixed framing: each frame is written as a 4-byte
+  big-endian length followed by msgpack bytes.  This keeps the reader
+  simple and tolerates partial-write tail truncation gracefully.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import asdict, is_dataclass
+from typing import Any
+import hashlib
+import json
+import os
+import struct
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.config import StorageManagerConfig
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventCallback, EventSubscriber
+from lmcache.v1.mp_observability.trace import codecs
+from lmcache.v1.mp_observability.trace.decorator import set_tracing_enabled
+from lmcache.v1.mp_observability.trace.format import (
+    FORMAT_VERSION,
+    MAGIC,
+    TRACE_SCHEMA_VERSION,
+    Header,
+    Record,
+    encode_header,
+    encode_record,
+)
+
+logger = init_logger(__name__)
+
+#: Frame length prefix size (bytes).  Big-endian uint32 — 4 GiB cap
+#: per frame which is far above any expected record size.
+_LEN_PREFIX = 4
+_LEN_STRUCT = struct.Struct(">I")
+
+
+class TraceRecorder(EventSubscriber, ABC):
+    """Base class for trace recorders.
+
+    Concrete subclasses select which events they care about.  This
+    base provides:
+
+    * file management (open / write / fsync / close)
+    * header emission
+    * the trace-gate flip (on at construction, off at ``close()``)
+
+    Subclasses implement :meth:`get_subscriptions`.
+    """
+
+    def __init__(self, output_path: str, level: str) -> None:
+        self._output_path = output_path
+        self._level = level
+        self._fd = open(output_path, "wb", buffering=0)
+        self._lock = threading.Lock()
+        self._closed = False
+        self._dropped_count = 0
+        self._header_written = False
+        self._t_mono_start = time.monotonic()
+        self._t_wall_start = time.time()
+
+        # The header is written lazily on the first of: a successful
+        # ``attach_storage_config`` call, the first record, or
+        # ``close()``.  Deferring avoids the in-place rewrite problem
+        # that would otherwise corrupt the file when the placeholder
+        # header and the final header have different byte lengths.
+        # Flip the trace gate AFTER the file is open so a racing publish
+        # cannot land on a half-initialized recorder.
+        set_tracing_enabled(True)
+        logger.info("trace recorder writing to %s (level=%s)", output_path, level)
+
+    # ---- subclass extension points ------------------------------------
+
+    @abstractmethod
+    def get_subscriptions(self) -> dict[EventType, EventCallback]: ...
+
+    # ---- public API ---------------------------------------------------
+
+    @property
+    def output_path(self) -> str:
+        """Path of the trace file on disk."""
+        return self._output_path
+
+    @property
+    def dropped_count(self) -> int:
+        """Number of records that failed to encode/write."""
+        return self._dropped_count
+
+    def attach_storage_config(self, config: StorageManagerConfig) -> None:
+        """Write the header populated from the StorageManagerConfig.
+
+        Must be called before any records are written; the
+        server lifecycle does this immediately after construction.
+        Subsequent calls are silently ignored — the header is written
+        once for the lifetime of the file.
+
+        Args:
+            config: The StorageManagerConfig in use.  Its dataclass
+                form is JSON-serialized and SHA-256 hashed for the
+                header digest, so a replay driver can detect
+                mismatched configurations.
+        """
+        with self._lock:
+            if self._closed or self._header_written:
+                return
+            sm_json = json.dumps(self._safe_config_dict(config), sort_keys=True)
+            digest = hashlib.sha256(sm_json.encode("utf-8")).hexdigest()
+            self._write_header(sm_json, digest)
+            self._header_written = True
+
+    def shutdown(self) -> None:
+        """:class:`EventBus` shutdown hook — close the recorder."""
+        self.close()
+
+    def close(self) -> None:
+        """Flush, fsync, and close the trace file.
+
+        Idempotent.  Flips the trace gate off so any straggler
+        publishes after this point are no-ops.  Writes a fallback
+        empty-config header if neither ``attach_storage_config`` nor
+        any record was written, so the resulting file is always
+        readable.
+        """
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            set_tracing_enabled(False)
+            try:
+                if not self._header_written:
+                    self._write_header(sm_config_json="", sm_config_digest="")
+                    self._header_written = True
+                self._fd.flush()
+                os.fsync(self._fd.fileno())
+            except OSError:
+                logger.exception("trace recorder: fsync failed")
+            finally:
+                self._fd.close()
+        if self._dropped_count:
+            logger.warning(
+                "trace recorder closed; %d record(s) dropped", self._dropped_count
+            )
+        else:
+            logger.info("trace recorder closed cleanly: %s", self._output_path)
+
+    # ---- internal -----------------------------------------------------
+
+    def _write_header(self, sm_config_json: str, sm_config_digest: str) -> None:
+        header = Header(
+            magic=MAGIC,
+            format_version=FORMAT_VERSION,
+            level=self._level,
+            trace_schema_version=TRACE_SCHEMA_VERSION,
+            t_mono_start=self._t_mono_start,
+            t_wall_start=self._t_wall_start,
+            sm_config_json=sm_config_json,
+            sm_config_digest=sm_config_digest,
+        )
+        self._write_frame(encode_header(header))
+
+    def _write_frame(self, frame: bytes) -> None:
+        # Single write so the prefix and body land atomically for frames
+        # below PIPE_BUF; two writes would let a concurrent appender
+        # interleave between them and would also double the syscall
+        # count on an unbuffered fd.  Caller holds ``self._lock`` (or is
+        # in __init__ before the gate flips on).
+        self._fd.write(_LEN_STRUCT.pack(len(frame)) + frame)
+
+    def _on_trace_call(self, event: Event) -> None:
+        """Encode and append one TRACE_CALL event.
+
+        Errors are logged at WARNING and counted, but do not propagate
+        — losing a record is preferable to taking down the EventBus
+        drain thread.
+        """
+        try:
+            qualname = event.metadata["qualname"]
+            args = event.metadata["args"]
+            # ``t_mono`` is stamped in the metadata at publish time
+            # (see ``publish_call_event``) so the recorded value is
+            # co-temporal with ``event.timestamp`` (wall-clock) instead
+            # of picking up the drain-thread delay.
+            publish_t_mono = event.metadata["t_mono"]
+            encoded_args = codecs.encode_args(args)
+            t_mono = max(0.0, publish_t_mono - self._t_mono_start)
+            record = Record(
+                t_mono=t_mono,
+                t_wall=event.timestamp,
+                qualname=qualname,
+                args=encoded_args,
+            )
+            frame = encode_record(record)
+        except Exception:
+            self._dropped_count += 1
+            logger.warning(
+                "trace recorder: failed to encode TRACE_CALL event "
+                "(qualname=%s); dropping",
+                event.metadata.get("qualname", "<unknown>"),
+                exc_info=True,
+            )
+            return
+
+        with self._lock:
+            if self._closed:
+                self._dropped_count += 1
+                return
+            try:
+                # Write a placeholder header on first record if the
+                # caller never invoked ``attach_storage_config``.
+                # Ensures the file is always readable.
+                if not self._header_written:
+                    self._write_header(sm_config_json="", sm_config_digest="")
+                    self._header_written = True
+                self._write_frame(frame)
+            except OSError:
+                self._dropped_count += 1
+                logger.warning(
+                    "trace recorder: write failed; dropping record",
+                    exc_info=True,
+                )
+
+    @staticmethod
+    def _safe_config_dict(config: StorageManagerConfig) -> dict[str, Any]:
+        """Best-effort conversion of a StorageManagerConfig to a JSON
+        dict.
+
+        Delegates to the module-level
+        :func:`safe_storage_config_dict` so the replay driver can
+        reproduce the exact digest the recorder writes.  Kept as a
+        staticmethod for backwards-compatible access.
+        """
+        return safe_storage_config_dict(config)
+
+
+def safe_storage_config_dict(config: StorageManagerConfig) -> dict[str, Any]:
+    """Best-effort JSON-serializable dict view of a StorageManagerConfig.
+
+    Falls back to ``str(config)`` for fields that are not directly
+    serializable.  The result is used only for the header digest and
+    human inspection — it does not need to be replay-faithful.
+
+    Exposed publicly so that the replay driver can compute a digest
+    of its *own* config using the same algorithm the recorder used,
+    for mismatch detection.
+
+    Args:
+        config: The StorageManagerConfig to serialize.
+
+    Returns:
+        A JSON-friendly dict.
+    """
+    if is_dataclass(config):
+        try:
+            return _coerce_jsonable(asdict(config))
+        except Exception:
+            pass
+    return {"repr": str(config)}
+
+
+def _coerce_jsonable(obj: Any) -> Any:
+    """Recursively coerce ``obj`` into a JSON-friendly value.
+
+    Anything not natively serializable falls through to ``str(obj)``.
+    """
+    if isinstance(obj, (str, int, float, bool)) or obj is None:
+        return obj
+    if isinstance(obj, (list, tuple)):
+        return [_coerce_jsonable(x) for x in obj]
+    if isinstance(obj, dict):
+        return {str(k): _coerce_jsonable(v) for k, v in obj.items()}
+    return str(obj)
+
+
+class StorageTraceRecorder(TraceRecorder):
+    """Records every ``TRACE_CALL`` event into a ``"storage"``-level file."""
+
+    def __init__(self, output_path: str) -> None:
+        super().__init__(output_path=output_path, level="storage")
+
+    def get_subscriptions(self) -> dict[EventType, EventCallback]:
+        return {EventType.TRACE_CALL: self._on_trace_call}
diff --git a/lmcache/v1/multiprocess/__init__.py b/lmcache/v1/multiprocess/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/lmcache/v1/multiprocess/affinity_pool.py b/lmcache/v1/multiprocess/affinity_pool.py
new file mode 100644
index 0000000..9832521
--- /dev/null
+++ b/lmcache/v1/multiprocess/affinity_pool.py
@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Thread pool with affinity routing.
+
+Tasks submitted with the same ``affinity_key`` always execute on the same
+worker thread.  Within each worker, tasks execute sequentially in FIFO order.
+
+This is used for GPU-bound request handlers (STORE / RETRIEVE) so that all
+operations for a given vLLM instance land on one thread, eliminating the need
+for per-instance locks on the shared temporary GPU buffer.
+"""
+
+# Standard
+from concurrent.futures import Future
+import queue
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# Sentinel object to signal worker shutdown
+_SHUTDOWN = object()
+
+
+class AffinityThreadPool:
+    """Thread pool that routes tasks to workers by affinity key.
+
+    Not thread-safe: ``submit()`` must be called from a single thread (the
+    ``MessageQueueServer`` main loop).
+
+    Args:
+        max_workers: Number of worker threads.
+        thread_name_prefix: Prefix for worker thread names.
+    """
+
+    def __init__(
+        self,
+        max_workers: int,
+        thread_name_prefix: str = "affinity",
+    ) -> None:
+        self._num_workers = max_workers
+        self._queues: list[queue.Queue] = [queue.Queue() for _ in range(max_workers)]
+        self._threads: list[threading.Thread] = []
+        # Maps an affinity_key -> the worker slot (thread index) bound to it.
+        self._key_to_slot: dict[int, int] = {}
+        self._next_slot = 0
+        self._overflow_warned = False
+        for i in range(max_workers):
+            t = threading.Thread(
+                target=self._worker,
+                args=(self._queues[i],),
+                daemon=True,
+                name=f"{thread_name_prefix}-{i}",
+            )
+            t.start()
+            self._threads.append(t)
+
+        logger.info(
+            "Created AffinityThreadPool '%s' with %d worker slots: up to %d "
+            "distinct affinity keys each bind to their own thread before slots "
+            "are shared. Compare this against the number of clients expected to "
+            "connect to confirm routing.",
+            thread_name_prefix,
+            max_workers,
+            max_workers,
+        )
+
+    # ------------------------------------------------------------------
+    # Worker loop
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _worker(q: queue.Queue) -> None:
+        while True:
+            item = q.get()
+            if item is _SHUTDOWN:
+                break
+            future, fn, args, kwargs = item
+            if future.set_running_or_notify_cancel():
+                try:
+                    result = fn(*args, **kwargs)
+                    future.set_result(result)
+                except BaseException as exc:
+                    future.set_exception(exc)
+
+    # ------------------------------------------------------------------
+    # Routing
+    # ------------------------------------------------------------------
+
+    def _slot_for_key(self, affinity_key: int) -> int:
+        """Return the worker slot bound to ``affinity_key``, assigning on first use.
+
+        Returns:
+            The worker slot (an index in ``[0, _num_workers)``) for the key.
+        """
+        slot = self._key_to_slot.get(affinity_key)
+        if slot is not None:
+            return slot
+
+        # First time we see this key -- bind it to the next free slot.
+        slot = self._next_slot % self._num_workers
+        is_overflow = self._next_slot >= self._num_workers
+        self._key_to_slot[affinity_key] = slot
+        self._next_slot += 1
+
+        logger.info(
+            "AffinityThreadPool: affinity_key=%d assigned to worker "
+            "slot %d of %d (thread %s); %d distinct key(s) now bound",
+            affinity_key,
+            slot,
+            self._num_workers,
+            self._threads[slot].name,
+            len(self._key_to_slot),
+        )
+        if is_overflow and not self._overflow_warned:
+            self._overflow_warned = True
+            logger.warning(
+                "AffinityThreadPool: affinity_key=%d wrapped onto worker slot "
+                "%d (only %d workers), so it shares a thread with an earlier "
+                "key and their tasks are serialized. Increase the worker count "
+                "to give each client its own thread.",
+                affinity_key,
+                slot,
+                self._num_workers,
+            )
+        return slot
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def submit(self, fn, *args, affinity_key: int = 0, **kwargs) -> Future:
+        """Submit *fn* for execution on the worker bound to *affinity_key*.
+
+        Returns a :class:`concurrent.futures.Future`.
+        """
+        future: Future = Future()
+        slot = self._slot_for_key(affinity_key)
+        self._queues[slot].put((future, fn, args, kwargs))
+        return future
+
+    def shutdown(self, wait: bool = True) -> None:
+        """Shut down the pool.
+
+        Sends a shutdown sentinel to every worker.  If *wait* is true, blocks
+        until all workers have exited.
+        """
+        for q in self._queues:
+            q.put(_SHUTDOWN)
+        if wait:
+            for t in self._threads:
+                t.join()
diff --git a/lmcache/v1/multiprocess/cache_control/__init__.py b/lmcache/v1/multiprocess/cache_control/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/multiprocess/cache_control/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/multiprocess/cache_control/errors.py b/lmcache/v1/multiprocess/cache_control/errors.py
new file mode 100644
index 0000000..bd36845
--- /dev/null
+++ b/lmcache/v1/multiprocess/cache_control/errors.py
@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Typed domain errors for cache-control operations.
+
+Transport-agnostic: each names *what* failed, not an HTTP status. The HTTP layer
+(``http_apis/error_handlers.py``) maps each subclass to a status code; an RPC /
+CLI / test caller can ``except`` the specific type. The subclasses are
+intentionally behaviorless -- the type itself is the signal -- so the message is
+passed in at the raise site.
+"""
+
+
+class CacheControlError(Exception):
+    """Base for cache-control domain failures."""
+
+
+class InvalidRequest(CacheControlError): ...  # malformed / unsupported / not-ready
+
+
+class NotFound(CacheControlError): ...  # referenced adapter / job missing
+
+
+class Unavailable(CacheControlError): ...  # backend can't serve the request
diff --git a/lmcache/v1/multiprocess/cache_control/key_resolver.py b/lmcache/v1/multiprocess/cache_control/key_resolver.py
new file mode 100644
index 0000000..a557c94
--- /dev/null
+++ b/lmcache/v1/multiprocess/cache_control/key_resolver.py
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Resolve a token sequence to the per-rank cache object keys it maps to.
+
+Several cache-control operations describe content by ``token_ids`` rather than
+by internal :class:`ObjectKey` values, which callers cannot construct. This
+hashes the tokens and expands each chunk into one key per rank, the same fan-out
+the lookup path uses. Failures raise :class:`Unavailable` (the model has not
+allocated KV cache on this node yet) or :class:`InvalidRequest` (an invalid key
+field).
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import TYPE_CHECKING
+
+# First Party
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+    ipc_key_to_object_keys,
+)
+from lmcache.v1.multiprocess.cache_control.errors import InvalidRequest, Unavailable
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.multiprocess.server import MPCacheServer
+
+# Hard cap on how many token ids a single token-addressed request may carry.
+# Keeps the request body bounded and the synchronous hashing / key-construction
+# work proportionate.
+MAX_TOKEN_IDS = 1_000_000
+
+
+def resolve_l1_keys(
+    engine: MPCacheServer,
+    model_name: str,
+    world_size: int,
+    token_ids: list[int],
+    cache_salt: str,
+) -> tuple[list[ObjectKey], int, MemoryLayoutDesc]:
+    """Resolve a token sequence to the per-rank object keys it maps to.
+
+    Args:
+        engine: The node's cache engine (its ``context`` carries the token
+            hasher and layout registry).
+        model_name: Model whose layout and rank fan-out to use.
+        world_size: Tensor-parallel world size selecting the layout.
+        token_ids: The token sequence to resolve.
+        cache_salt: Per-tenant isolation salt.
+
+    Returns:
+        ``(obj_keys, chunk_count, layout_desc)``. ``obj_keys`` is empty (and
+        ``chunk_count`` is 0) when the sequence is shorter than one chunk --
+        callers treat that as a no-op.
+
+    Raises:
+        Unavailable: No layout is registered for ``(model_name, world_size)``
+            (the model has not allocated KV cache on this node yet).
+        InvalidRequest: A key field (e.g. ``cache_salt``) is invalid.
+    """
+    ctx = engine.context
+    layout_desc = ctx.layout_desc_registry.find(model_name, world_size)
+    if layout_desc is None:
+        raise Unavailable(
+            f"no layout registered for model_name={model_name!r} "
+            f"world_size={world_size}; the model has not allocated "
+            f"KV cache on this node yet"
+        )
+
+    try:
+        ipc_key = IPCCacheServerKey(
+            model_name=model_name,
+            world_size=world_size,
+            worker_id=None,
+            token_ids=tuple(token_ids),
+            start=0,
+            end=len(token_ids),
+            request_id="",
+            cache_salt=cache_salt,
+        )
+    except ValueError as exc:
+        raise InvalidRequest(str(exc)) from None
+
+    chunk_hashes = ctx.token_hasher.compute_chunk_hashes(list(token_ids))
+    if not chunk_hashes:
+        return [], 0, layout_desc
+    obj_keys = ipc_key_to_object_keys(ipc_key, chunk_hashes, [0])[0]
+    return obj_keys, len(chunk_hashes), layout_desc
diff --git a/lmcache/v1/multiprocess/cache_control/object_service.py b/lmcache/v1/multiprocess/cache_control/object_service.py
new file mode 100644
index 0000000..805e00c
--- /dev/null
+++ b/lmcache/v1/multiprocess/cache_control/object_service.py
@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Node-local cache object operations (adapter listing, object listing, delete).
+
+:class:`ObjectService` wraps the storage manager's L2 adapters and exposes
+adapter resolution, paginated listing, and key-addressed deletion. It performs
+its own validation and raises transport-agnostic domain errors (see
+:mod:`cache_control.errors`); the HTTP layer maps those to status codes.
+Blocking adapter I/O is off-loaded to a worker thread so callers can ``await``.
+"""
+
+# Standard
+from typing import Any
+import asyncio
+
+# First Party
+from lmcache.v1.distributed.api import EncodedObjectKey
+from lmcache.v1.distributed.tiers import Tier
+from lmcache.v1.multiprocess.cache_control.errors import (
+    InvalidRequest,
+    NotFound,
+    Unavailable,
+)
+
+# Hard cap on how many keys a single delete request may target. Keeps the
+# request body bounded and prevents one call from monopolizing the adapter's
+# I/O loop for an unbounded interval.
+MAX_DELETE_BATCH = 10_000
+
+# Object operations address the L2 tier today; other tiers are rejected.
+_SUPPORTED_TIER = Tier.L2
+
+
+class ObjectService:
+    """Adapter-listing, object-listing, and key-addressed deletion on one node.
+
+    Args:
+        engine: The node's cache engine; its ``storage_manager`` owns the L2
+            adapters.
+    """
+
+    def __init__(self, engine: Any) -> None:
+        self._engine = engine
+
+    @staticmethod
+    def _require_supported_tier(tier: Tier) -> None:
+        """Raise :class:`InvalidRequest` unless ``tier`` is the supported one."""
+        if tier != _SUPPORTED_TIER:
+            raise InvalidRequest(
+                f"tier {tier.value!r} not supported; only {_SUPPORTED_TIER.value!r}"
+            )
+
+    def _resolve_adapter(self, selector: str | None) -> tuple[Any, Any]:
+        """Resolve the ``(descriptor, adapter)`` pair a request targets.
+
+        ``selector=None`` picks the primary (first-configured) adapter.
+
+        Raises:
+            Unavailable: No adapters configured.
+            NotFound: ``selector`` matches none.
+        """
+        adapters = self._engine.storage_manager.l2_adapters()
+        if not adapters:
+            raise Unavailable("no L2 adapters configured")
+        if selector is None:
+            return adapters[0]
+        for desc, adapter in adapters:
+            if desc.type_name == selector:
+                return desc, adapter
+        raise NotFound(f"no L2 adapter with type_name={selector!r}")
+
+    def list_adapters(self) -> dict[str, object]:
+        """Return the live L2 adapter inventory.
+
+        Returns:
+            ``{"adapters": [{index, type_name, tier, primary, reconfigurable},
+            ...]}`` (empty list when no backends are configured).
+            ``reconfigurable`` is ``True`` for adapters that accept runtime
+            ``/reconfigure`` operations; the ``{backend}`` path parameter for
+            those routes is the adapter's ``type_name``. This is the single live
+            adapter listing -- it supersedes the old ``/reconfigure/backends``.
+        """
+        sm = self._engine.storage_manager
+        adapters = sm.l2_adapters()
+        reconfigurable = sm.reconfigurable_l2_backends()
+        return {
+            "adapters": [
+                {
+                    "index": i,
+                    "type_name": desc.type_name,
+                    "tier": _SUPPORTED_TIER.value,
+                    "primary": i == 0,
+                    "reconfigurable": desc.type_name in reconfigurable,
+                }
+                for i, (desc, _) in enumerate(adapters)
+            ]
+        }
+
+    async def list_objects(
+        self,
+        tier: Tier,
+        adapter_selector: str | None,
+        model_name: str | None,
+        page_size: int,
+        page_token: str | None,
+    ) -> dict[str, object]:
+        """List keys resident in one adapter, paginated.
+
+        Returns:
+            ``{"adapter", "entries", "next_page_token"}``.
+
+        Raises:
+            InvalidRequest: unsupported ``tier`` or malformed ``page_token``.
+            Unavailable: no adapters configured, or the adapter does not
+                implement listing.
+            NotFound: ``adapter_selector`` matches none.
+        """
+        self._require_supported_tier(tier)
+        desc, adapter = self._resolve_adapter(adapter_selector)
+        try:
+            page = await asyncio.to_thread(
+                adapter.list_l2_keys,
+                model_name=model_name,
+                page_size=page_size,
+                cursor=page_token,
+            )
+        except ValueError as exc:
+            raise InvalidRequest(str(exc)) from None
+        except NotImplementedError as exc:
+            raise Unavailable(
+                f"L2 adapter {desc.type_name!r} does not support listing: {exc}"
+            ) from None
+        return {
+            "adapter": desc.type_name,
+            "entries": page.entries,
+            "next_page_token": page.next_page_token,
+        }
+
+    async def delete_objects(
+        self,
+        tier: Tier,
+        adapter_selector: str | None,
+        keys: list[EncodedObjectKey],
+    ) -> dict[str, object]:
+        """Delete a caller-supplied list of keys from one adapter.
+
+        Idempotent at the adapter level (absent / locked keys are skipped).
+
+        Returns:
+            ``{"requested", "adapter", "ok"[, "error"]}``; ``ok`` is ``False``
+            with ``error`` set when the adapter raised (a structured failure,
+            not a crash).
+
+        Raises:
+            InvalidRequest: unsupported ``tier``, batch too large, or an
+                ``ObjectKey`` invariant violation.
+            Unavailable / NotFound: adapter resolution.
+        """
+        self._require_supported_tier(tier)
+        if len(keys) > MAX_DELETE_BATCH:
+            raise InvalidRequest(
+                f"too many keys in a single request "
+                f"(limit={MAX_DELETE_BATCH}, got={len(keys)})"
+            )
+        parsed = []
+        for i, cache_key in enumerate(keys):
+            try:
+                parsed.append(cache_key.to_object_key())
+            except ValueError as exc:
+                raise InvalidRequest(f"keys[{i}]: {exc}") from None
+
+        desc, adapter = self._resolve_adapter(adapter_selector)
+        body: dict[str, object] = {"requested": len(parsed), "adapter": desc.type_name}
+        try:
+            await asyncio.to_thread(adapter.delete, parsed)
+        except Exception as exc:  # noqa: BLE001 - surfaced as a structured result
+            body["ok"] = False
+            body["error"] = str(exc)
+            return body
+        body["ok"] = True
+        return body
diff --git a/lmcache/v1/multiprocess/cache_control/prefetch_service.py b/lmcache/v1/multiprocess/cache_control/prefetch_service.py
new file mode 100644
index 0000000..786154b
--- /dev/null
+++ b/lmcache/v1/multiprocess/cache_control/prefetch_service.py
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Node-local warm-prefetch operations (submit + status).
+
+:class:`PrefetchService` resolves a token sequence to per-rank keys and submits
+a **warm** load (retained, unlocked) from L2 into L1, returning a ``request_id``
+the caller polls. It validates its own inputs and raises transport-agnostic
+domain errors (see :mod:`cache_control.errors`); the HTTP layer maps those to
+status codes. It owns the node's :class:`WarmPrefetchJobs` table.
+"""
+
+# Standard
+from typing import Any
+
+# First Party
+from lmcache.v1.distributed.tiers import Tier
+from lmcache.v1.multiprocess.cache_control.errors import InvalidRequest, NotFound
+from lmcache.v1.multiprocess.cache_control.key_resolver import (
+    MAX_TOKEN_IDS,
+    resolve_l1_keys,
+)
+from lmcache.v1.multiprocess.warm_prefetch import (
+    COMPLETED,
+    UNKNOWN,
+    WarmPrefetchJobs,
+)
+
+# Warm prefetch loads from L2 into L1; other directions are rejected.
+_SOURCE_TIER = Tier.L2
+_TARGET_TIER = Tier.L1
+
+
+class PrefetchService:
+    """Submit and poll warm prefetches on one node.
+
+    Args:
+        engine: The node's cache engine (resolves tokens and runs the load).
+    """
+
+    def __init__(self, engine: Any) -> None:
+        self._engine = engine
+        self._jobs = WarmPrefetchJobs()
+
+    def submit(
+        self,
+        model_name: str,
+        world_size: int,
+        token_ids: list[int],
+        cache_salt: str,
+        source_tier: Tier,
+        target_tier: Tier,
+    ) -> dict[str, object]:
+        """Submit a warm prefetch of a token sequence's chunks from L2 into L1.
+
+        Returns:
+            ``{"request_id", "chunks", "status": "submitted"}``, or
+            ``{"chunks": 0, "status": "noop"}`` for a sub-chunk sequence.
+
+        Raises:
+            InvalidRequest: unsupported direction, token cap exceeded, or an
+                invalid key field.
+            Unavailable: no layout registered for the model (via the resolver).
+        """
+        if source_tier != _SOURCE_TIER or target_tier != _TARGET_TIER:
+            raise InvalidRequest(
+                f"unsupported prefetch direction {source_tier.value!r}->"
+                f"{target_tier.value!r}; only {_SOURCE_TIER.value!r}->"
+                f"{_TARGET_TIER.value!r}"
+            )
+        if len(token_ids) > MAX_TOKEN_IDS:
+            raise InvalidRequest(
+                f"too many token_ids in a single request "
+                f"(limit={MAX_TOKEN_IDS}, got={len(token_ids)})"
+            )
+        obj_keys, chunks, layout_desc = resolve_l1_keys(
+            self._engine, model_name, world_size, token_ids, cache_salt
+        )
+        if not chunks:
+            return {"chunks": 0, "status": "noop"}
+        request_id = self._jobs.submit(
+            self._engine.storage_manager, obj_keys, layout_desc
+        )
+        return {"request_id": request_id, "chunks": chunks, "status": "submitted"}
+
+    def status(self, request_id: str) -> dict[str, object]:
+        """Report a job's status, finalizing it on the first completed poll.
+
+        Returns:
+            ``{"request_id", "status": "pending"}`` or ``{"request_id",
+            "status": "completed", "found_keys", "total_keys"}``.
+
+        Raises:
+            NotFound: unknown id (already completed-and-consumed, or never
+                submitted).
+        """
+        status = self._jobs.poll(self._engine.storage_manager, request_id)
+        if status.state == UNKNOWN:
+            raise NotFound(
+                f"unknown prefetch request_id={request_id!r} "
+                f"(already completed or never submitted)"
+            )
+        if status.state == COMPLETED:
+            return {
+                "request_id": request_id,
+                "status": COMPLETED,
+                "found_keys": status.found_keys,
+                "total_keys": status.total_keys,
+            }
+        return {"request_id": request_id, "status": status.state}
diff --git a/lmcache/v1/multiprocess/config.py b/lmcache/v1/multiprocess/config.py
new file mode 100644
index 0000000..aab4e4f
--- /dev/null
+++ b/lmcache/v1/multiprocess/config.py
@@ -0,0 +1,680 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Configuration for the multiprocess (ZMQ) server and HTTP frontend.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+import argparse
+import json
+import math
+import os
+import uuid
+
+
+@dataclass
+class MPServerConfig:
+    """Configuration for the ZMQ-based multiprocess cache server."""
+
+    host: str = "localhost"
+    """ZMQ server host."""
+
+    port: int = 5555
+    """ZMQ server port."""
+
+    chunk_size: int = 256
+    """Chunk size for KV cache operations."""
+
+    max_workers: int = 1
+    """Base number of worker threads. Sets default for both GPU and CPU pools."""
+
+    max_gpu_workers: int = 1
+    """Worker threads for the GPU affinity pool (STORE/RETRIEVE).
+    Resolved from --max-gpu-workers or --max-workers."""
+
+    max_cpu_workers: int = 1
+    """Worker threads for the normal (CPU) pool (LOOKUP, END_SESSION, etc.).
+    Resolved from --max-cpu-workers or --max-workers."""
+
+    hash_algorithm: str = "blake3"
+    """Hash algorithm for token-based operations (builtin, sha256_cbor, blake3)."""
+
+    engine_type: str = "default"
+    """Cache engine backend type
+    ('default' for standard prefix caching, 'blend' when cacheblend is enabled).
+    """
+
+    separate_object_groups: bool = True
+    """When True (default), split kernel groups into one object group per
+    sliding-window size at KV-cache registration (hybrid models). When False,
+    all kernel groups share a single full-attention object group."""
+
+    enable_segmented_prefix: bool = False
+    """CacheBlend only (engine_type='blend'): on a mid-prefix L2 retrieve
+    failure, retain the gapped contiguous prefix so the post-gap chunks stay
+    L1-resident (served by the sparse leg as L1 hits, the hole recomputed)
+    instead of truncating the prefix at the gap. No effect for other engines."""
+
+    supported_transfer_mode: str = "auto"
+    """Transfer mode: 'lmcache_driven' for server-driven transfer
+    (STORE/RETRIEVE, supports CUDA IPC and CPU SHM), 'engine_driven' for
+    engine-driven transfer (PREPARE/COMMIT), or 'auto' to enable both."""
+
+    runtime_plugin_config: "RuntimePluginConfig" = field(
+        default_factory=lambda: RuntimePluginConfig()
+    )
+    """Runtime plugin configuration (locations + extra config)."""
+
+    p2p_config: "P2PConfig" = field(default_factory=lambda: P2PConfig())
+    """Peer-to-peer configuration. P2P is enabled when its advertise URL is
+    set."""
+
+    shm_name: str | None = None
+    """SHM segment name for engine-driven KV transfer.
+    None: auto-allocate (default). "": force pickle. Other: use that name."""
+
+    script_allowed_imports: list[str] = field(default_factory=list)
+    """Modules that /run_script endpoint is allowed to import."""
+
+    instance_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    """Stable identity of this MP server, the single source of truth for who
+    this server is. Used as the coordinator membership key and projected onto
+    the OTel ``service.instance.id`` resource attribute (see
+    ``run_cache_server``) so metrics, traces, and coordinator state all key on
+    the same id. Set via ``--instance-id``; defaults to a random UUID v4."""
+
+    worker_reap_timeout_seconds: float = 120.0
+    """Silence budget (seconds) after which a ping-proven worker's KV cache
+    registration is reaped. 0 disables worker reaping. Keep it >= 3 x the
+    engine adapter's heartbeat interval so a few missed pings never reap a live
+    worker."""
+
+    worker_registration_grace_seconds: float = 3600.0
+    """Silence budget (seconds) for a worker that registered but has never
+    sent a PING (model warmup, or death before its first request). Must be
+    >= worker_reap_timeout_seconds."""
+
+    def __post_init__(self) -> None:
+        """Validate the worker-reaping timeouts.
+
+        Raises:
+            ValueError: If a timeout is non-finite, the reap timeout is
+                negative or a non-zero value below the 30 s floor, or the
+                registration grace is below the reap timeout.
+        """
+        reap = self.worker_reap_timeout_seconds
+        grace = self.worker_registration_grace_seconds
+        if not math.isfinite(reap) or reap < 0 or (reap != 0 and reap < 30.0):
+            raise ValueError(
+                "worker reap timeout must be 0 (disabled) or >= 30s; keep it "
+                ">= 3 x your configured lmcache.mp.heartbeat_interval "
+                f"(default 10s); got {reap}"
+            )
+        if not math.isfinite(grace) or grace < reap:
+            raise ValueError(
+                "worker registration grace must be >= the worker reap timeout "
+                f"({reap}s); got {grace}"
+            )
+
+
+@dataclass
+class RuntimePluginConfig:
+    """Configuration for runtime plugins."""
+
+    locations: list[str] = field(default_factory=list)
+    """Paths to runtime plugin scripts or directories."""
+
+    extra_config: dict = field(default_factory=dict)
+    """Extra key-value config forwarded to runtime plugins
+    via the JSON config blob.
+    Accepts a JSON string on the command line.
+    """
+
+
+@dataclass
+class P2PConfig:
+    """Configuration for peer-to-peer KV transfer.
+
+    P2P is enabled when :attr:`advertise_url` is non-empty. It additionally
+    requires a coordinator URL for peer discovery (validated at startup).
+    """
+
+    advertise_url: str = ""
+    """Transfer-channel server ``host:port`` this instance advertises to peers.
+    Empty disables P2P."""
+
+    listen_url: str = ""
+    """Transfer-channel server ``host:port`` to bind and listen on. Empty
+    defers to :attr:`advertise_url`."""
+
+    lookup_timeout: float = 30.0
+    """Seconds before a peer lookup result counts as a miss."""
+
+    load_timeout: float = 30.0
+    """Seconds before a peer load counts as a failure."""
+
+    transfer_engine: str = "nixl"
+    """Transfer-channel implementation to use."""
+
+    @property
+    def enabled(self) -> bool:
+        """Whether P2P is enabled (an advertise URL is configured)."""
+        return bool(self.advertise_url)
+
+    @property
+    def effective_listen_url(self) -> str:
+        """The listen URL, defaulting to the advertise URL when unset."""
+        return self.listen_url or self.advertise_url
+
+
+DEFAULT_P2P_CONFIG = P2PConfig()
+
+
+DEFAULT_MP_SERVER_CONFIG = MPServerConfig()
+
+
+@dataclass
+class HTTPFrontendConfig:
+    """Configuration for the HTTP frontend (uvicorn/FastAPI)."""
+
+    http_host: str = "0.0.0.0"
+    """HTTP server host."""
+
+    http_port: int = 8080
+    """HTTP server port."""
+
+
+DEFAULT_HTTP_FRONTEND_CONFIG = HTTPFrontendConfig()
+
+
+@dataclass
+class CoordinatorConfig:
+    """Configuration for joining an MP coordinator (registrant side).
+
+    Consumed by the HTTP server's lifespan to start the registration task.
+    When :attr:`url` is empty, the server registers with no coordinator and
+    runs exactly as before.
+    """
+
+    url: str = ""
+    """Coordinator base URL, e.g. ``http://coordinator:9300``. Empty disables
+    registration."""
+
+    advertise_ip: str = ""
+    """IP the coordinator should reach this server at. Empty defers to the
+    server's outbound IP (resolved by the registrar)."""
+
+    heartbeat_interval: float = 5.0
+    """Seconds between heartbeats. Must be strictly positive and kept well below
+    the coordinator's ``INSTANCE_TIMEOUT``."""
+
+    l2_event_reporting: bool = False
+    """When ``True``, report L2 store/lookup events to the coordinator for
+    fleet-wide usage tracking and eviction."""
+
+    l2_event_flush_interval: float = 1.0
+    """Seconds between L2 event flush attempts to the coordinator."""
+
+
+DEFAULT_COORDINATOR_CONFIG = CoordinatorConfig()
+
+
+def add_mp_server_args(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    """
+    Add MP server configuration arguments to an existing parser.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        The same parser with MP server arguments added.
+    """
+    mp_group = parser.add_argument_group(
+        "MP Server", "Configuration for the ZMQ multiprocess cache server"
+    )
+    mp_group.add_argument(
+        "--instance-id",
+        type=str,
+        default=None,
+        help="Stable identity of this MP server. Used as the coordinator "
+        "membership key and as the OTel 'service.instance.id' resource "
+        "attribute on every metric and span. Defaults to a random UUID v4 "
+        "minted at startup.",
+    )
+    mp_group.add_argument(
+        "--host",
+        type=str,
+        default="localhost",
+        help="Host to bind the ZMQ server. Default is localhost.",
+    )
+    mp_group.add_argument(
+        "--port",
+        type=int,
+        default=5555,
+        help="Port to bind the ZMQ server. Default is 5555.",
+    )
+    mp_group.add_argument(
+        "--chunk-size",
+        type=int,
+        default=256,
+        help="Chunk size for KV cache operations. Default is 256.",
+    )
+    mp_group.add_argument(
+        "--max-workers",
+        type=int,
+        default=1,
+        help="Base number of worker threads for both GPU and CPU pools. "
+        "Default is 1. Can be overridden per-pool with "
+        "--max-gpu-workers and --max-cpu-workers.",
+    )
+    mp_group.add_argument(
+        "--max-gpu-workers",
+        type=int,
+        default=None,
+        help="Worker threads for the GPU affinity pool (STORE/RETRIEVE). "
+        "Defaults to --max-workers if not specified.",
+    )
+    mp_group.add_argument(
+        "--max-cpu-workers",
+        type=int,
+        default=None,
+        help="Worker threads for the normal CPU pool (LOOKUP, etc.). "
+        "Defaults to --max-workers if not specified.",
+    )
+    mp_group.add_argument(
+        "--hash-algorithm",
+        type=str,
+        default="blake3",
+        help="Hash algorithm for token-based operations "
+        "(builtin, sha256_cbor, blake3). Default is blake3.",
+    )
+    mp_group.add_argument(
+        "--engine-type",
+        type=str,
+        default="default",
+        choices=["default", "blend", "blend_legacy"],
+        help="Cache engine backend type. 'default' uses standard prefix caching; "
+        "'blend' selects CacheBlend V3 (the current implementation); "
+        "'blend_legacy' selects the original CacheBlend. Default is 'default'.",
+    )
+    mp_group.add_argument(
+        "--supported-transfer-mode",
+        type=str,
+        default="auto",
+        choices=["lmcache_driven", "engine_driven", "auto"],
+        help="Supported transfer mode: 'lmcache_driven' for server-driven "
+        "transfer (STORE/RETRIEVE, supports CUDA IPC and CPU SHM), "
+        "'engine_driven' for engine-driven transfer (PREPARE/COMMIT), "
+        "or 'auto' to enable both transfer paths. Default is 'auto'.",
+    )
+    mp_group.add_argument(
+        "--runtime-plugin-locations",
+        type=str,
+        nargs="*",
+        default=[],
+        help="Paths to runtime plugin scripts or "
+        "directories to launch alongside the server.",
+    )
+    mp_group.add_argument(
+        "--runtime-plugin-config",
+        type=str,
+        default="{}",
+        help="JSON string of extra key-value config forwarded to runtime "
+        "plugins via LMCACHE_RUNTIME_PLUGIN_EXTRA_CONFIG. "
+        'Example: \'{"plugin.frontend.heartbeat_url": '
+        '"http://localhost:5000/heartbeat"}\'',
+    )
+    mp_group.add_argument(
+        "--shm-name",
+        type=str,
+        default=None,
+        help="SHM segment name for engine-driven KV transfer. "
+        "Default (not specified): auto-allocate. "
+        'Set to "" to force pickle path (disable SHM). '
+        "Set to a name to use that specific SHM segment.",
+    )
+    mp_group.add_argument(
+        "--script-allowed-imports",
+        type=str,
+        nargs="*",
+        default=[],
+        help="Python modules that the /run_script endpoint is allowed to "
+        "import. Example: --script-allowed-imports numpy pandas",
+    )
+    mp_group.add_argument(
+        "--separate-object-groups",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Split kernel groups into one object group per sliding-window size "
+        "at KV-cache registration (for hybrid models). (Default is True)",
+    )
+    mp_group.add_argument(
+        "--worker-reap-timeout-seconds",
+        type=float,
+        default=120.0,
+        help="Silence budget (s) before a ping-proven worker's KV cache "
+        "registration is reaped. 0 disables reaping. Must be >= 3 x the "
+        "engine adapter's heartbeat interval. Default is 120.",
+    )
+    mp_group.add_argument(
+        "--worker-registration-grace-seconds",
+        type=float,
+        default=3600.0,
+        help="Silence budget (s) for a worker that registered but never "
+        "pinged (model warmup or early death). Must be >= the worker reap "
+        "timeout. Default is 3600.",
+    )
+    mp_group.add_argument(
+        "--enable-segmented-prefix",
+        action="store_true",
+        help="CacheBlend (--engine-type blend) only: on a mid-prefix L2 "
+        "retrieve failure, retain the gapped prefix so post-gap chunks stay "
+        "L1-resident instead of truncating at the gap. No effect otherwise.",
+    )
+    return parser
+
+
+def parse_args_to_mp_server_config(
+    args: argparse.Namespace,
+) -> MPServerConfig:
+    """
+    Convert parsed command line arguments to an MPServerConfig.
+
+    Args:
+        args: Parsed arguments from the argument parser.
+
+    Returns:
+        MPServerConfig: The configuration object.
+    """
+    base = args.max_workers
+    max_gpu = args.max_gpu_workers if args.max_gpu_workers is not None else base
+    max_cpu = args.max_cpu_workers if args.max_cpu_workers is not None else base
+    try:
+        plugin_extra = json.loads(getattr(args, "runtime_plugin_config", None) or "{}")
+    except json.JSONDecodeError as exc:
+        raise ValueError("--runtime-plugin-config is not valid JSON: %s" % exc) from exc
+    return MPServerConfig(
+        instance_id=args.instance_id or str(uuid.uuid4()),
+        host=args.host,
+        port=args.port,
+        chunk_size=args.chunk_size,
+        max_workers=base,
+        max_gpu_workers=max_gpu,
+        max_cpu_workers=max_cpu,
+        hash_algorithm=args.hash_algorithm,
+        engine_type=args.engine_type,
+        separate_object_groups=args.separate_object_groups,
+        enable_segmented_prefix=args.enable_segmented_prefix,
+        supported_transfer_mode=args.supported_transfer_mode,
+        runtime_plugin_config=RuntimePluginConfig(
+            locations=(args.runtime_plugin_locations or []),
+            extra_config=plugin_extra,
+        ),
+        p2p_config=parse_args_to_p2p_config(args),
+        shm_name=args.shm_name,
+        script_allowed_imports=args.script_allowed_imports or [],
+        worker_reap_timeout_seconds=args.worker_reap_timeout_seconds,
+        worker_registration_grace_seconds=args.worker_registration_grace_seconds,
+    )
+
+
+def add_p2p_args(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    """Add peer-to-peer configuration arguments to an existing parser.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        The same parser with P2P arguments added.
+    """
+    group = parser.add_argument_group(
+        "P2P", "Configuration for peer-to-peer KV transfer"
+    )
+    group.add_argument(
+        "--p2p-advertise-url",
+        type=str,
+        default="",
+        help="Transfer-channel server host:port this instance advertises to "
+        "peers. Setting it enables P2P (also requires --coordinator-url).",
+    )
+    group.add_argument(
+        "--p2p-listen-url",
+        type=str,
+        default="",
+        help="Transfer-channel server host:port to bind. Defaults to "
+        "--p2p-advertise-url.",
+    )
+    group.add_argument(
+        "--p2p-lookup-timeout",
+        type=float,
+        default=30.0,
+        help="Seconds before a peer lookup result counts as a miss. Default is 30.",
+    )
+    group.add_argument(
+        "--p2p-load-timeout",
+        type=float,
+        default=30.0,
+        help="Seconds before a peer load counts as a failure. Default is 30.",
+    )
+    group.add_argument(
+        "--p2p-transfer-engine",
+        type=str,
+        default="nixl",
+        help="Transfer-channel implementation to use. Default is nixl.",
+    )
+    return parser
+
+
+def parse_args_to_p2p_config(
+    args: argparse.Namespace,
+) -> P2PConfig:
+    """Convert parsed command line arguments to a P2PConfig.
+
+    Args:
+        args: Parsed arguments from the argument parser.
+
+    Returns:
+        The configuration object.
+    """
+    return P2PConfig(
+        advertise_url=getattr(args, "p2p_advertise_url", "") or "",
+        listen_url=getattr(args, "p2p_listen_url", "") or "",
+        lookup_timeout=getattr(args, "p2p_lookup_timeout", 30.0),
+        load_timeout=getattr(args, "p2p_load_timeout", 30.0),
+        transfer_engine=getattr(args, "p2p_transfer_engine", "nixl"),
+    )
+
+
+def add_http_frontend_args(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    """
+    Add HTTP frontend configuration arguments to an existing parser.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        The same parser with HTTP frontend arguments added.
+    """
+    http_group = parser.add_argument_group(
+        "HTTP Frontend", "Configuration for the HTTP frontend server"
+    )
+    http_group.add_argument(
+        "--http-host",
+        type=str,
+        default="0.0.0.0",
+        help="Host to bind the HTTP server. Default is 0.0.0.0.",
+    )
+    http_group.add_argument(
+        "--http-port",
+        type=int,
+        default=8080,
+        help="Port to bind the HTTP server. Default is 8080.",
+    )
+    return parser
+
+
+def parse_args_to_http_frontend_config(
+    args: argparse.Namespace,
+) -> HTTPFrontendConfig:
+    """
+    Convert parsed command line arguments to an HTTPFrontendConfig.
+
+    Args:
+        args: Parsed arguments from the argument parser.
+
+    Returns:
+        HTTPFrontendConfig: The configuration object.
+    """
+    return HTTPFrontendConfig(
+        http_host=args.http_host,
+        http_port=args.http_port,
+    )
+
+
+def add_coordinator_args(
+    parser: argparse.ArgumentParser,
+) -> argparse.ArgumentParser:
+    """Add MP coordinator registration arguments to an existing parser.
+
+    Each flag falls back to its ``LMCACHE_COORDINATOR_*`` environment variable
+    so the server can be configured either way (the env var is convenient for
+    the Kubernetes downward API); an explicit flag wins over the env var.
+
+    Args:
+        parser: The argument parser to add arguments to.
+
+    Returns:
+        The same parser with coordinator arguments added.
+    """
+    group = parser.add_argument_group(
+        "Coordinator", "Configuration for joining an MP coordinator"
+    )
+    group.add_argument(
+        "--coordinator-url",
+        type=str,
+        default=None,
+        help="Coordinator base URL (e.g. http://coordinator:9300). When set, "
+        "this server registers, heartbeats, and deregisters on shutdown. "
+        "Defaults to LMCACHE_COORDINATOR_URL; unset disables registration.",
+    )
+    group.add_argument(
+        "--coordinator-advertise-ip",
+        type=str,
+        default=None,
+        help="IP the coordinator should reach this server at. Defaults to "
+        "LMCACHE_COORDINATOR_ADVERTISE_IP, then the server's outbound IP.",
+    )
+    group.add_argument(
+        "--coordinator-heartbeat-interval",
+        type=float,
+        default=None,
+        help="Seconds between heartbeats (must be > 0). Defaults to "
+        "LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL, then 5.0.",
+    )
+    group.add_argument(
+        "--coordinator-l2-event-reporting",
+        action="store_true",
+        default=None,
+        help="Report L2 store/lookup events to the coordinator for "
+        "fleet-wide usage tracking and eviction. Defaults to "
+        "LMCACHE_COORDINATOR_L2_EVENT_REPORTING; unset disables.",
+    )
+    group.add_argument(
+        "--coordinator-l2-event-flush-interval",
+        type=float,
+        default=None,
+        help="Seconds between L2 event flush attempts (must be > 0). "
+        "Defaults to LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL, then 1.0.",
+    )
+    return parser
+
+
+def parse_args_to_coordinator_config(
+    args: argparse.Namespace,
+) -> CoordinatorConfig:
+    """Convert parsed command line arguments to a CoordinatorConfig.
+
+    A flag value takes precedence over its environment variable. The heartbeat
+    interval is validated here so a malformed value fails fast at startup
+    (runtime best-effort only covers coordinator *reachability*, not config).
+
+    Args:
+        args: Parsed arguments from the argument parser.
+
+    Returns:
+        The configuration object.
+
+    Raises:
+        ValueError: If the heartbeat interval is not a positive number.
+    """
+    url = (
+        args.coordinator_url
+        if args.coordinator_url is not None
+        else os.getenv("LMCACHE_COORDINATOR_URL", "")
+    )
+    advertise_ip = (
+        args.coordinator_advertise_ip
+        if args.coordinator_advertise_ip is not None
+        else os.getenv("LMCACHE_COORDINATOR_ADVERTISE_IP", "")
+    )
+    if args.coordinator_heartbeat_interval is not None:
+        heartbeat_interval = args.coordinator_heartbeat_interval
+    else:
+        raw = os.getenv("LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL")
+        if raw:
+            try:
+                heartbeat_interval = float(raw)
+            except ValueError as exc:
+                raise ValueError(
+                    "LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL is not a number: %r" % raw
+                ) from exc
+        else:
+            heartbeat_interval = 5.0
+    if not math.isfinite(heartbeat_interval) or heartbeat_interval <= 0:
+        # Reject inf/nan too: inf would register once then sleep forever
+        # (never heartbeat), and nan has undefined sleep behavior.
+        raise ValueError(
+            "coordinator heartbeat interval must be a finite number > 0, "
+            "got %s" % heartbeat_interval
+        )
+    if args.coordinator_l2_event_reporting is not None:
+        l2_event_reporting = args.coordinator_l2_event_reporting
+    else:
+        l2_event_reporting = os.getenv(
+            "LMCACHE_COORDINATOR_L2_EVENT_REPORTING", ""
+        ).lower() in ("1", "true", "yes")
+
+    if args.coordinator_l2_event_flush_interval is not None:
+        l2_event_flush_interval = args.coordinator_l2_event_flush_interval
+    else:
+        raw = os.getenv("LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL")
+        if raw:
+            try:
+                l2_event_flush_interval = float(raw)
+            except ValueError as exc:
+                raise ValueError(
+                    "LMCACHE_COORDINATOR_L2_EVENT_FLUSH_INTERVAL is not a number: %r"
+                    % raw
+                ) from exc
+        else:
+            l2_event_flush_interval = 1.0
+    if not math.isfinite(l2_event_flush_interval) or l2_event_flush_interval <= 0:
+        raise ValueError(
+            "coordinator L2 event flush interval must be a finite number > 0, "
+            "got %s" % l2_event_flush_interval
+        )
+
+    return CoordinatorConfig(
+        url=url,
+        advertise_ip=advertise_ip,
+        heartbeat_interval=heartbeat_interval,
+        l2_event_reporting=l2_event_reporting,
+        l2_event_flush_interval=l2_event_flush_interval,
+    )
diff --git a/lmcache/v1/multiprocess/custom_types.py b/lmcache/v1/multiprocess/custom_types.py
new file mode 100644
index 0000000..0112329
--- /dev/null
+++ b/lmcache/v1/multiprocess/custom_types.py
@@ -0,0 +1,255 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+# Third Party
+import msgspec
+import torch
+
+# First Party
+from lmcache.v1.platform.base_ipc_wrapper import (  # noqa: E402,F401
+    DeviceIPCWrapper,
+)
+
+"""
+Defines the types and the customized encoder/decoders for inter-process
+communications.
+
+Key Types:
+- IPCCacheServerKey: Token-based cache key
+  - Contains token_ids, start, end, request_id (all required)
+  - Converted to ObjectKey for storage operations via ipc_key_to_object_keys()
+"""
+
+
+@dataclass(order=True, frozen=True)
+class IPCCacheServerKey:
+    """Cache key for the IPC (multiprocess) protocol.
+
+    This key type is sent by the client over ZMQ (serialized via msgspec).
+
+    The client sends token_ids, start, end, and request_id (all required).
+    The server computes chunk hashes via TokenHasher and converts to
+    ObjectKey for storage operations using ipc_key_to_object_keys().
+
+    The request_id field is for session tracking and is NOT included
+    in equality/hash comparisons (two keys with same content but different
+    request_ids are considered equal for cache purposes).
+    """
+
+    model_name: str
+    world_size: int
+    worker_id: int | None
+
+    token_ids: tuple[int, ...]  # frozen tuple for hashability
+    start: int
+    end: int
+
+    # === Session tracking (not part of cache identity) ===
+    request_id: str = field(compare=False)
+
+    # === Per-user isolation salt (part of cache identity) ===
+    # msgspec encodes dataclasses as maps, so forward wire compatibility
+    # works by field name: an old payload without ``cache_salt`` decodes
+    # on new code using the default "". Placing the field last is a style
+    # choice — all defaulted fields must come after non-defaulted ones.
+    #
+    # Invariant: must not contain ``@``, ``/``, ``\``, or NUL, and
+    # must be <= 128 chars — same rationale as ObjectKey (see
+    # ObjectKey.cache_salt). Validated in __post_init__.
+    cache_salt: str = ""
+
+    # Duplicated from ObjectKey — cannot import ObjectKey here due to
+    # circular dependency (api.py imports IPCCacheServerKey).
+    _SALT_FORBIDDEN_CHARS = frozenset("@/\\\x00")
+    _SALT_MAX_LEN = 128
+
+    def __post_init__(self) -> None:
+        bad = self._SALT_FORBIDDEN_CHARS & set(self.cache_salt)
+        if bad:
+            raise ValueError(
+                f"cache_salt must not contain {bad!r} (got {self.cache_salt!r})"
+            )
+        if len(self.cache_salt) > self._SALT_MAX_LEN:
+            raise ValueError(
+                f"cache_salt exceeds max length {self._SALT_MAX_LEN} "
+                f"(got {len(self.cache_salt)})"
+            )
+
+    # Helper function for unit tests only
+    @classmethod
+    def from_token_ids(
+        cls,
+        model_name: str,
+        world_size: int,
+        worker_id: int | None,
+        token_ids: list[int],
+        start: int = 0,
+        end: int = 0,
+        request_id: str = "",
+        cache_salt: str = "",
+    ) -> "IPCCacheServerKey":
+        """Create a key from token ids. Only used by the tests."""
+        return cls(
+            model_name=model_name,
+            world_size=world_size,
+            worker_id=worker_id,
+            token_ids=tuple(token_ids),
+            start=start,
+            end=end,
+            request_id=request_id,
+            cache_salt=cache_salt,
+        )
+
+    def no_worker_id_version(self) -> "IPCCacheServerKey":
+        """Create a copy with worker_id=None for lookup requests."""
+        return IPCCacheServerKey(
+            model_name=self.model_name,
+            world_size=self.world_size,
+            worker_id=None,
+            token_ids=self.token_ids,
+            start=self.start,
+            end=self.end,
+            request_id=self.request_id,
+            cache_salt=self.cache_salt,
+        )
+
+
+# Type exports
+KVCache = list[DeviceIPCWrapper]
+
+
+class RegisterEngineDrivenContextPayload(msgspec.Struct):
+    """Payload for the REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT protocol message.
+
+    Attributes:
+        instance_id: Worker instance identifier (typically PID).
+        model_name: Model name associated with this worker.
+        world_size: Worker world size used in cache keys.
+        block_size: Tokens per paged block.
+        num_layers: Number of model layers.
+        hidden_dim_size: Flattened hidden dimension per token.
+        dtype_str: Torch dtype name (e.g. ``"float16"``).
+        use_mla: Whether the worker KV format is MLA.
+    """
+
+    instance_id: int
+    model_name: str
+    world_size: int
+    block_size: int
+    num_layers: int
+    hidden_dim_size: int
+    dtype_str: str
+    use_mla: bool
+
+
+@dataclass
+class CustomizedSerdeConfig:
+    serializer: Callable[[Any], bytes]
+    deserializer: Callable[[bytes], Any]
+    code: int
+
+
+@dataclass
+class BlockAllocationRecord:
+    """A single per-request GPU block allocation delta from vLLM."""
+
+    req_id: str
+    new_block_ids: list[int]
+    new_token_ids: list[int]
+
+
+@dataclass
+class CBMatchResult:
+    """Result of a sub-sequence match from BlendTokenRangeMatcher.
+
+    Attributes:
+        old_st: Start position in the originally registered (stored) sequence.
+        old_ed: End position in the originally registered (stored) sequence.
+        cur_st: Start position in the query sequence where the match was found.
+        cur_ed: End position in the query sequence where the match was found.
+        hash: Token hash bytes (from registration) used as the storage key.
+    """
+
+    old_st: int
+    old_ed: int
+    cur_st: int
+    cur_ed: int
+    hash: bytes
+
+
+@dataclass
+class CBUnifiedLookupResult:
+    """Resolved payload of ``CB_UNIFIED_LOOKUP``: prefix lookup + non-prefix
+    fingerprint match, reconciled in one RPC. The RPC returns ``None`` (not this)
+    while either leg's KV is still loading into L1; this type is sent only once
+    both are resident.
+
+    Attributes:
+        prefix_coverage_tokens: Contiguous prefix-cache coverage (L1+L2) in
+            tokens — what the standard LOOKUP would report.
+        non_prefix_segments: Fingerprint matches outside the prefix coverage
+            (cur_st order), each carrying ``(old_st, old_ed, cur_st, cur_ed,
+            hash)``. Already sparse-prefetched, so the retrieve set equals the
+            prefetched set. Includes fleet-coordinator (shared-L2) matches:
+            those are merged in before the sparse prefetch -- prefix-covered and
+            locally-duplicated ones dropped -- so they ride the identical
+            prefetch + retrieve path and need no separate handling.
+        segmented_prefix_segments: Post-gap chunks retained by the
+            ``SEGMENTED_PREFIX`` prefix leg (beyond ``count_leading_ones``) — at
+            their original positions (``old_st == cur_st``), so the connector
+            tags them ``prefix`` (pure load, no recompute) and only the gap is
+            recomputed. Sourced from the prefix bitmap, not the fingerprint
+            matcher; empty when ``SEGMENTED_PREFIX`` is off.
+    """
+
+    prefix_coverage_tokens: int
+    non_prefix_segments: list[CBMatchResult]
+    segmented_prefix_segments: list[CBMatchResult] = field(default_factory=list)
+
+
+_CUSTOMERIZED_SERIALIZERS = {
+    DeviceIPCWrapper: CustomizedSerdeConfig(
+        serializer=DeviceIPCWrapper.Serialize,
+        deserializer=DeviceIPCWrapper.Deserialize,
+        code=1,
+    ),
+}
+
+
+def get_customized_encoder(type: Any) -> msgspec.msgpack.Encoder:
+    # TODO: `type` is not used here
+    def enc_hook(obj: Any) -> Any:
+        for supported_type, cfg in _CUSTOMERIZED_SERIALIZERS.items():
+            if isinstance(obj, supported_type):
+                data = cfg.serializer(obj)
+                return msgspec.msgpack.Ext(cfg.code, data)
+        if isinstance(obj, torch.dtype):
+            return str(obj).removeprefix("torch.")
+        if isinstance(obj, torch.Size):
+            return list(obj)
+        raise TypeError(f"Unsupported type for serialization: {type(obj)}")
+
+    return msgspec.msgpack.Encoder(enc_hook=enc_hook)
+
+
+def get_customized_decoder(type: Any) -> msgspec.msgpack.Decoder:
+    def ext_hook(code: int, data: bytes) -> Any:
+        for cfg in _CUSTOMERIZED_SERIALIZERS.values():
+            if cfg.code == code:
+                return cfg.deserializer(data)
+        raise TypeError(f"Unsupported ext code for deserialization: {code}")
+
+    def dec_hook(expected_type: type, obj: Any) -> Any:
+        if expected_type is torch.dtype:
+            return getattr(torch, obj)
+        if expected_type is torch.Size:
+            return torch.Size(obj)
+        if isinstance(obj, expected_type):
+            return obj
+        raise NotImplementedError(
+            f"Unsupported type for deserialization: {expected_type}"
+        )
+
+    return msgspec.msgpack.Decoder(ext_hook=ext_hook, dec_hook=dec_hook, type=type)
diff --git a/lmcache/v1/multiprocess/engine_context.py b/lmcache/v1/multiprocess/engine_context.py
new file mode 100644
index 0000000..f789907
--- /dev/null
+++ b/lmcache/v1/multiprocess/engine_context.py
@@ -0,0 +1,299 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared context and layout descriptor registry for engine modules."""
+
+# Standard
+from dataclasses import dataclass
+from typing import TypedDict
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import (
+    DEFAULT_ATTN_WINDOW_DESC,
+    AttnWindowDesc,
+    MemoryLayoutDesc,
+    ObjectKey,
+    ipc_key_to_object_keys,
+)
+from lmcache.v1.distributed.config import StorageManagerConfig
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.gpu_connector.gds_context import (
+    get_gds_context,
+    initialize_gds_context,
+)
+from lmcache.v1.mp_observability.event_bus import EventBus, get_event_bus
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.session import SessionManager
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+
+logger = init_logger(__name__)
+
+
+class ShmPoolInfo(TypedDict):
+    """Shared-memory pool metadata returned during registration."""
+
+    shm_name: str
+    pool_size: int
+
+
+@dataclass
+class _LayoutDescEntry:
+    """Stored layout descriptor and its active registration count."""
+
+    layout_desc: MemoryLayoutDesc
+    ref_count: int
+    attn_desc: AttnWindowDesc = DEFAULT_ATTN_WINDOW_DESC
+    """Cross-chunk attention windows of all object groups, in object-group
+    order. Defaults to a single full-attention group."""
+
+
+class LayoutDescRegistry:
+    """Thread-safe registry mapping (model_name, world_size) to MemoryLayoutDesc.
+
+    Modules write to this registry when KV caches are registered.
+    Consumers (e.g. LookupModule) read from it to find layout descriptors
+    for prefetch tasks. Multiple worker instances can share the same
+    ``(model_name, world_size)`` entry, so the registry keeps the descriptor
+    until the last matching registration is unregistered.
+    """
+
+    def __init__(self) -> None:
+        # Key: (model_name, world_size) -> layout descriptor entry
+        self._registry: dict[tuple[str, int], _LayoutDescEntry] = {}
+        self._lock = threading.Lock()
+
+    def register(
+        self,
+        model_name: str,
+        world_size: int,
+        layout_desc: MemoryLayoutDesc,
+        attn_desc: AttnWindowDesc = DEFAULT_ATTN_WINDOW_DESC,
+    ) -> None:
+        """Register a layout descriptor for a (model_name, world_size) pair.
+
+        Re-registering the same pair increments the active registration
+        count. The latest descriptor is retained for lookups.
+
+        Args:
+            model_name: The model name.
+            world_size: The world size.
+            layout_desc: The memory layout descriptor.
+            attn_desc: Cross-chunk attention windows of all object groups, in
+                object-group order. Defaults to a single full-attention group.
+        """
+        key = (model_name, world_size)
+        with self._lock:
+            entry = self._registry.get(key)
+            if entry is None:
+                self._registry[key] = _LayoutDescEntry(
+                    layout_desc=layout_desc,
+                    ref_count=1,
+                    attn_desc=attn_desc,
+                )
+                return
+
+            entry.layout_desc = layout_desc
+            entry.attn_desc = attn_desc
+            entry.ref_count += 1
+
+    def unregister(self, model_name: str, world_size: int) -> None:
+        """Unregister one layout descriptor registration for a pair.
+
+        The descriptor is removed only when the last active registration for
+        the pair is unregistered.
+
+        Args:
+            model_name: The model name.
+            world_size: The world size.
+        """
+        key = (model_name, world_size)
+        with self._lock:
+            entry = self._registry.get(key)
+            if entry is None:
+                return
+
+            if entry.ref_count <= 1:
+                self._registry.pop(key)
+                return
+
+            entry.ref_count -= 1
+
+    def find(self, model_name: str, world_size: int) -> MemoryLayoutDesc | None:
+        """Look up a layout descriptor by (model_name, world_size).
+
+        Args:
+            model_name: The model name.
+            world_size: The world size.
+
+        Returns:
+            The layout descriptor if found, otherwise None.
+        """
+        with self._lock:
+            entry = self._registry.get((model_name, world_size))
+            if entry is None:
+                return None
+            return entry.layout_desc
+
+    def find_attn_desc(self, model_name: str, world_size: int) -> AttnWindowDesc:
+        """Look up the attention-window descriptor for a pair.
+
+        Args:
+            model_name: The model name.
+            world_size: The world size.
+
+        Returns:
+            The :class:`AttnWindowDesc` registered for the pair.
+
+        Raises:
+            ValueError: If no descriptor is registered for the pair. Callers
+                must register the KV cache (which establishes the pair) before
+                looking up its windows.
+        """
+        with self._lock:
+            entry = self._registry.get((model_name, world_size))
+            if entry is None:
+                raise ValueError(
+                    f"No attention-window descriptor registered for model "
+                    f"{model_name!r} with world size {world_size}"
+                )
+            return entry.attn_desc
+
+
+class MPCacheServerContext:
+    """Shared infrastructure for all engine modules.
+
+    Holds the storage manager, token hasher, session manager, event bus,
+    and layout descriptor registry. Modules receive this context at init
+    and use it for shared operations.
+
+    Args:
+        storage_manager_config: Configuration for the storage manager.
+        chunk_size: Chunk size for KV cache operations.
+        hash_algorithm: Hash algorithm for token hashing.
+        separate_object_groups: Whether to split kernel groups into one object
+            group per sliding-window size at KV-cache registration. Default True.
+    """
+
+    def __init__(
+        self,
+        storage_manager_config: StorageManagerConfig,
+        chunk_size: int = 256,
+        hash_algorithm: str = "blake3",
+        separate_object_groups: bool = True,
+        full_sw_kv: bool = False,
+    ) -> None:
+        self._chunk_size = chunk_size
+        self._separate_object_groups = separate_object_groups
+        self._full_sw_kv = full_sw_kv
+
+        # Initialize the process-global GDS context.
+        # No-op when GDS L1 is disabled (config is None).
+        initialize_gds_context(storage_manager_config.l1_manager_config.gds_l1_config)
+
+        self.shm_pool_info: ShmPoolInfo = self._compute_shm_pool_info(
+            storage_manager_config
+        )
+        self._storage_manager = StorageManager(storage_manager_config)
+        self._token_hasher = TokenHasher(
+            chunk_size=chunk_size, hash_algorithm=hash_algorithm
+        )
+        self._session_manager = SessionManager(self._token_hasher)
+        self._event_bus = get_event_bus()
+        self._layout_desc_registry = LayoutDescRegistry()
+
+    def close(self) -> None:
+        """
+        Tear down the session manager, storage manager, and the process-global
+        GDS context.
+        """
+        self._session_manager.close()
+        self._storage_manager.close()
+        # Tear down the GDS cuFile context (the shared slab + its handle).
+        get_gds_context().close()
+
+    @property
+    def chunk_size(self) -> int:
+        """Chunk size for KV cache operations."""
+        return self._chunk_size
+
+    @property
+    def separate_object_groups(self) -> bool:
+        """Whether to split kernel groups into per-sliding-window object groups."""
+        return self._separate_object_groups
+
+    @property
+    def full_sw_kv(self) -> bool:
+        """Whether sliding-window groups cache full per-chunk KV (no window cutting)."""
+        return self._full_sw_kv
+
+    @property
+    def storage_manager(self) -> StorageManager:
+        """The storage manager instance."""
+        return self._storage_manager
+
+    @property
+    def token_hasher(self) -> TokenHasher:
+        """The token hasher for computing chunk hashes."""
+        return self._token_hasher
+
+    @property
+    def session_manager(self) -> SessionManager:
+        """The session manager for request lifecycle tracking."""
+        return self._session_manager
+
+    @property
+    def event_bus(self) -> EventBus:
+        """The event bus for observability events."""
+        return self._event_bus
+
+    @property
+    def layout_desc_registry(self) -> LayoutDescRegistry:
+        """Registry mapping (model_name, world_size) to MemoryLayoutDesc."""
+        return self._layout_desc_registry
+
+    def resolve_obj_keys(
+        self, key: IPCCacheServerKey, object_group_ids: list[int]
+    ) -> list[list[ObjectKey]]:
+        """Resolve per-object-group object keys from an IPC cache key.
+
+        Uses the session manager to track token state and the token hasher
+        to compute chunk hashes for the requested range.
+
+        Args:
+            key: IPC cache key describing model/session/token range.
+            object_group_ids: Object group ids to produce keys for.
+
+        Returns:
+            The i-th element is the list of ObjectKeys for
+            ``object_group_ids[i]``.
+
+        Raises:
+            ValueError: If ``key.worker_id`` is ``None``.
+        """
+        session = self.session_manager.get_or_create(key.request_id)
+        session.set_tokens(list(key.token_ids))
+        chunk_hashes = [
+            TokenHasher.hash_to_bytes(h) for h in session.get_hashes(key.start, key.end)
+        ]
+        if key.worker_id is None:
+            raise ValueError("Must resolve keys with worker_id != None")
+        return ipc_key_to_object_keys(key, chunk_hashes, object_group_ids)
+
+    @staticmethod
+    def _compute_shm_pool_info(
+        storage_manager_config: StorageManagerConfig,
+    ) -> ShmPoolInfo:
+        """Compute normalized SHM pool metadata from storage config.
+
+        Returns an empty pool (disabled SHM transport) when ``shm_name`` is
+        empty or lazy memory mode is enabled. Otherwise strips any leading ``/``
+        and ensures the name starts with ``lmcache_l1_pool_``.
+        """
+        mem_cfg = storage_manager_config.l1_manager_config.memory_config
+        shm_name = mem_cfg.shm_name or ""
+        if not shm_name or mem_cfg.use_lazy or mem_cfg.devdax_path:
+            return {"shm_name": "", "pool_size": 0}
+        bare = shm_name.lstrip("/")
+        if not bare.startswith("lmcache_l1_pool_"):
+            shm_name = f"lmcache_l1_pool_{bare}"
+        return {"shm_name": shm_name, "pool_size": mem_cfg.size_in_bytes}
diff --git a/lmcache/v1/multiprocess/engine_module.py b/lmcache/v1/multiprocess/engine_module.py
new file mode 100644
index 0000000..5fd5b5f
--- /dev/null
+++ b/lmcache/v1/multiprocess/engine_module.py
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Protocol and types for pluggable engine modules."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import TYPE_CHECKING, Callable, Protocol
+
+# First Party
+from lmcache.v1.multiprocess.protocol import RequestType
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+
+
+class ThreadPoolType(Enum):
+    """Declares which thread pool a handler should run in."""
+
+    SYNC = auto()
+    AFFINITY = auto()
+    NORMAL = auto()
+
+
+@dataclass
+class HandlerSpec:
+    """Specification for a single message queue handler.
+
+    Args:
+        request_type: The ZMQ request type this handler serves.
+        handler: The callable that processes the request.
+        pool: Which thread pool the handler runs in.
+    """
+
+    request_type: RequestType
+    handler: Callable
+    pool: ThreadPoolType
+
+
+class EngineModule(Protocol):
+    """Protocol for pluggable engine modules.
+
+    Each module owns its internal state and exposes handlers
+    that the compositor registers with the message queue server.
+    """
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        ...
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves."""
+        ...
+
+    def report_status(self) -> dict:
+        """Return module-specific status information."""
+        ...
+
+    def close(self) -> None:
+        """Release resources owned by this module."""
+        ...
+
+
+class InstanceLivenessTarget(Protocol):
+    """A module the periodic reaper drives, in either or both of two roles.
+
+    * **Liveness owner** -- tracks per-worker registrations keyed by
+      ``instance_id``, refreshed on PING and scanned for staleness
+      (``touch_instance`` / ``reap_stale_instances`` /
+      ``tracked_instance_count``). The transfer modules fill this role.
+    * **State mirror** -- holds a second reference to a reaped instance's
+      resources and releases it on demand (``drop_instance_state``).
+      ``BlendV3Module`` fills this role for its per-instance CB state.
+
+    Every method defaults to a no-op, so an implementer subclasses this
+    protocol and overrides only the role it fills. The management module
+    drives all targets from the PING handler and the reaper; no caller
+    touches a module's private state directly.
+    """
+
+    def touch_instance(self, instance_id: int) -> None:
+        """Refresh the worker's last-seen time and mark it ping-proven.
+
+        A no-op if the instance is not tracked (already reaped or never
+        registered), or for a target that owns no liveness state.
+
+        Args:
+            instance_id: The worker's opaque instance ID.
+        """
+        return
+
+    def reap_stale_instances(
+        self, reap_timeout_s: float, registration_grace_s: float
+    ) -> list[int]:
+        """Evict and clean up workers that have gone silent.
+
+        An instance that has sent at least one PING is judged against
+        ``reap_timeout_s``; one that has never pinged (warming up, or dead
+        before its first request) is judged against ``registration_grace_s``.
+
+        Args:
+            reap_timeout_s: Silence budget for ping-proven instances.
+            registration_grace_s: Silence budget for never-pinged instances;
+                must be >= ``reap_timeout_s``.
+
+        Returns:
+            The instance IDs reaped during this scan; empty for a target
+            that owns no liveness state.
+        """
+        return []
+
+    def tracked_instance_count(self) -> int:
+        """Return the number of currently tracked instances (0 if none)."""
+        return 0
+
+    def drop_instance_state(self, instance_id: int) -> None:
+        """Release any state mirrored for a reaped instance.
+
+        Called for every reaped ``instance_id``. A no-op unless the target
+        keeps a second reference to that instance's resources (only mirrors
+        such as ``BlendV3Module`` override this).
+
+        Args:
+            instance_id: The reaped worker's instance ID.
+        """
+        return
diff --git a/lmcache/v1/multiprocess/futures.py b/lmcache/v1/multiprocess/futures.py
new file mode 100644
index 0000000..beadae5
--- /dev/null
+++ b/lmcache/v1/multiprocess/futures.py
@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Generic, Optional, TypeVar
+import threading
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.mp_observability.errors import LMCacheTimeoutError
+
+T = TypeVar("T")
+
+
+class MessagingFuture(Generic[T]):
+    def __init__(self):
+        self.is_done_ = threading.Event()
+        self.result_ = None
+
+    def query(self) -> bool:
+        """
+        Check if the future is done.
+
+        Returns:
+            bool: True if the future is done, False otherwise.
+        """
+        return self.is_done_.is_set()
+
+    def wait(self, timeout: Optional[float] = None) -> bool:
+        """
+        Wait for the future to be done.
+
+        Args:
+            timeout (Optional[float]): Maximum time to wait in seconds.
+                If None, wait indefinitely.
+
+        Returns:
+            bool: True if the future is done, False if the timeout was reached.
+        """
+        return self.is_done_.wait(timeout)
+
+    def result(self, timeout: Optional[float] = None) -> T:
+        """
+        Get the result of the future.
+
+        Args:
+            timeout (Optional[float]): Maximum time to wait in seconds.
+                If None, wait indefinitely.
+
+        Returns:
+            T: The result of the future.
+
+        Raises:
+            TimeoutError: If the future is not done within the timeout.
+        """
+        flag = self.wait(timeout)
+        if not flag:
+            raise LMCacheTimeoutError("Future result not available within timeout")
+        return self.result_
+
+    def set_result(self, result: T) -> None:
+        """
+        Set the result of the future and mark it as done. This function is NOT
+        SUPPOSED TO BE CALLED by users directly. It should be only called by
+        the messaging system when the result is available.
+
+        Args:
+            result (T): The result to set.
+        """
+        self.result_ = result
+        self.is_done_.set()
+
+    def to_cuda_future(
+        self,
+        device: Any | None = None,
+    ) -> "CUDAMessagingFuture":
+        # TODO: need extra type checking for the future type
+        return CUDAMessagingFuture.FromMessagingFuture(self, device)  # type: ignore
+
+
+class CUDAMessagingFuture(MessagingFuture[T]):
+    """
+    The future class that wraps both result and a CUDA IPC event.
+    The `query`, `wait`, and `result` methods will pend on both the
+    original future and the CUDA event.
+    The original future should return tuple[bytes, T], where the first
+    element is the serialized CUDA event.
+    """
+
+    def __init__(
+        self,
+        raw_future: MessagingFuture[tuple[bytes, T]],
+        device: Any | None = None,
+    ) -> None:
+        super().__init__()
+        self.raw_future_ = raw_future
+        self.event_: Any | None = None
+        self.result_: T | None = None
+        self.device_ = device if device is not None else torch_dev.current_device()
+
+    def _on_raw_future_complete(self):
+        """
+        Update the CUDA event and result when the raw future is complete.
+        """
+        event_bytes, result = self.raw_future_.result()
+        self.result_ = result
+
+        # Not all backends support interprocess Events (CUDA IPC specific)
+        if not hasattr(torch_dev, "Event") or not hasattr(
+            torch_dev.Event, "from_ipc_handle"
+        ):
+            raise RuntimeError(
+                f"Backend '{torch_device_type}' does not support interprocess "
+                "Events (Event.from_ipc_handle not available). "
+                "Multiprocess IPC requires CUDA."
+            )
+        self.event_ = torch_dev.Event.from_ipc_handle(self.device_, event_bytes)
+
+    def wait(self, timeout: Optional[float] = None) -> bool:
+        """
+        Wait for the future to be done, with the CUDA stream.
+
+        Args:
+            timeout (Optional[float]): Maximum time to wait for the UNDERLYING
+                RAW FUTURE in seconds. The exact timeout is not guaranteed
+                when waiting on the CUDA event. (NOTE: this could be improved
+                with careful threading management)
+
+        Returns:
+            bool: True if the future is done, False if the timeout was reached.
+
+        Raises:
+            ValueError: if the timeout is not None.
+
+        Notes:
+            This function does not support waiting for a specific time.
+        """
+        if self.event_:
+            self.event_.synchronize()
+            return True
+
+        flag = self.raw_future_.wait(timeout)
+        if not flag:
+            return False
+
+        self._on_raw_future_complete()
+
+        assert self.event_ is not None
+        self.event_.synchronize()
+
+        return True
+
+    def result(self, timeout: Optional[float] = None) -> T:
+        """
+        Get the result of the future.
+
+        Args:
+            timeout (Optional[float]): Maximum time to wait for the UNDERLYING
+                RAW FUTURE in seconds. The exact timeout is not guaranteed
+                when waiting on the CUDA event. (NOTE: this could be improved
+                with careful threading management)
+
+        Returns:
+            T: The result of the future.
+
+        Raises:
+            TimeoutError: If the future is not done within the timeout.
+        """
+        flag = self.wait(timeout)
+        if not flag:
+            raise LMCacheTimeoutError(
+                "CUDAMessagingFuture result not available within timeout"
+            )
+
+        assert self.result_ is not None
+        return self.result_
+
+    def query(self) -> bool:
+        """
+        Check if the future is done.
+
+        Returns:
+            bool: True if the future is done, False otherwise.
+        """
+        if self.event_:
+            return self.event_.query()
+
+        if self.raw_future_.query():
+            self._on_raw_future_complete()
+            assert self.event_ is not None
+            return self.event_.query()
+
+        return False
+
+    def set_result(self, result: T) -> None:
+        raise NotImplementedError(
+            "CUDAMessagingFuture does not support set_result directly"
+        )
+
+    @staticmethod
+    def FromMessagingFuture(
+        raw_future: MessagingFuture[tuple[bytes, T]],
+        device: Any | None = None,
+    ) -> "CUDAMessagingFuture[T]":
+        return CUDAMessagingFuture(raw_future, device)
diff --git a/lmcache/v1/multiprocess/group_view.py b/lmcache/v1/multiprocess/group_view.py
new file mode 100644
index 0000000..32d19e2
--- /dev/null
+++ b/lmcache/v1/multiprocess/group_view.py
@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LMCache's engine-neutral description of a serving engine's KV cache groups.
+
+An *engine group* is one distinct paged-block address space exposed by the
+serving engine (e.g. one of vLLM's hybrid KV cache groups): block IDs are only
+meaningful within a single group, and layers from different groups must never be
+merged into one LMCache KV group. Engine group ids are assumed dense and
+consecutive starting from 0.
+
+LMCache's neutral KV cache spec is simply a ``list[EngineGroupInfo]`` (passed as
+a ``Sequence[EngineGroupInfo]`` where only order matters). The group order is
+the protocol-visible LMCache group order used by store/retrieve block IDs. An
+empty list means a single non-hybrid group (the default for engines that do not
+report KV cache group metadata). Engine-specific conversion belongs in the
+corresponding ``lmcache.integration.<engine>`` package, not here.
+"""
+
+# Standard
+from collections.abc import Mapping, Sequence
+from typing import cast
+
+# Third Party
+import msgspec
+
+
+class EngineGroupInfo(msgspec.Struct, frozen=True):
+    """One LMCache KV group: layers of one engine group that share a copy kernel.
+
+    Carries the layer indices and which engine group they belong to. Several
+    ``EngineGroupInfo`` instances may share the same ``engine_group_id`` when
+    one engine group is split by physical transfer identity (e.g. differing
+    hidden dims). A ``list[EngineGroupInfo]`` is carried verbatim in the
+    ``REGISTER_KV_CACHE`` IPC payload; the message queue handles
+    encoding/decoding.
+    """
+
+    engine_group_id: int
+    """Engine group these layers live in (one distinct paged-block address
+    space). Selects which request block-id list applies. Dense from 0."""
+
+    layer_indices: tuple[int, ...] = ()
+    """Registered KV tensor indices assigned to this group."""
+
+    tokens_per_block: int = 0
+    """Logical tokens covered by one paged chunk (one engine block ID) of
+    this engine group, as declared by the engine's KV cache spec
+    (``kv_cache_spec.block_size`` for vLLM). ``0`` means the engine did not
+    report it; consumers then fall back to the physical slot count detected
+    from the registered tensors (i.e. the group is treated as
+    uncompressed)."""
+
+    sw_size_tokens: int = -1
+    """Sliding window size in tokens for the layers of this group.
+    ``-1`` means the layers are not sliding-window attention."""
+
+
+def num_engine_groups(groups: Sequence[EngineGroupInfo]) -> int:
+    """Return the number of engine groups (block-id lists per transfer request).
+
+    Engine group ids are assumed dense and consecutive from 0.
+
+    Args:
+        groups: The LMCache KV groups, in protocol order.
+
+    Returns:
+        ``max(engine_group_id) + 1``, or ``1`` for an empty ``groups`` (single
+        non-hybrid group).
+    """
+    if not groups:
+        return 1
+    return max(group.engine_group_id for group in groups) + 1
+
+
+def num_engine_group_infos(groups: Sequence[EngineGroupInfo]) -> int:
+    """Return the number of LMCache KV groups visible to transfer requests.
+
+    Args:
+        groups: The LMCache KV groups, in protocol order.
+
+    Returns:
+        ``len(groups)``, or ``1`` for an empty ``groups`` (single non-hybrid
+        group).
+    """
+    if not groups:
+        return 1
+    return len(groups)
+
+
+def _engine_group_id_per_view(
+    groups: Sequence[EngineGroupInfo],
+) -> tuple[int, ...]:
+    """Return, per LMCache group, the engine group it draws block IDs from.
+
+    Args:
+        groups: The LMCache KV groups, in protocol order.
+
+    Returns:
+        A tuple whose length equals the number of LMCache groups (i.e.
+        :func:`num_engine_group_infos`); element ``i`` is the engine group id
+        that LMCache group ``i`` reads block IDs from. ``(0,)`` for an empty
+        ``groups`` (single non-hybrid group).
+    """
+    if not groups:
+        return (0,)
+    return tuple(group.engine_group_id for group in groups)
+
+
+def engine_group_layer_indices(
+    groups: Sequence[EngineGroupInfo],
+) -> list[list[int]]:
+    """Return each engine group's layer indices, ordered by engine group id.
+
+    Several ``EngineGroupInfo`` may share one ``engine_group_id``; their
+    ``layer_indices`` are unioned into that group's entry.
+
+    Args:
+        groups: The LMCache KV groups, in protocol order.
+
+    Returns:
+        One sorted ``list[int]`` of layer indices per engine group, indexed by
+        engine group id (dense from 0). Empty when ``groups`` is empty (a single
+        non-hybrid group with no per-group split).
+    """
+    if not groups:
+        return []
+    num_groups = max(group.engine_group_id for group in groups) + 1
+    per_group: list[list[int]] = [[] for _ in range(num_groups)]
+    for group in groups:
+        per_group[group.engine_group_id].extend(group.layer_indices)
+    return [sorted(indices) for indices in per_group]
+
+
+def expand_engine_block_ids(
+    groups: Sequence[EngineGroupInfo],
+    engine_side_block_ids: Sequence[Sequence[int]] | Sequence[int],
+) -> list[list[int]]:
+    """Expand the engine-side block id list to the list per LMCache kernel group.
+
+    The serving engine reports block IDs per engine group. LMCache transfer
+    requests are indexed by LMCache KV group, so each LMCache group reuses the
+    block IDs from its source engine group.
+
+    Args:
+        groups: The LMCache KV groups, in protocol order.
+        engine_side_block_ids: Block IDs indexed by engine group id, i.e. one
+            inner ``list[int]`` per engine group (element ``g`` is engine group
+            ``g``'s block list).
+
+    Returns:
+        Block IDs re-indexed by LMCache group order: one inner list per LMCache
+        group, copied from that group's source engine group.
+    """
+    # Back-compat: older vLLM connectors emit a flat Sequence[int] for the
+    # single (non-hybrid) engine group instead of one inner list per group.
+    # Normalize both shapes to a concrete list[list[int]] so downstream
+    # indexing is unambiguous for both runtime and mypy.
+    if not engine_side_block_ids or isinstance(engine_side_block_ids[0], int):
+        per_group: Sequence[Sequence[int]] = [
+            cast("Sequence[int]", engine_side_block_ids)
+        ]
+    else:
+        per_group = cast("Sequence[Sequence[int]]", engine_side_block_ids)
+    return [
+        list(per_group[engine_group_id])
+        for engine_group_id in _engine_group_id_per_view(groups)
+    ]
+
+
+def slice_block_ids_per_group(
+    allocated_block_ids: Mapping[int, Sequence[int]],
+    group_tokens_per_block: Sequence[int],
+    start_token_idx: int,
+    end_token_idx: int,
+) -> list[list[int]]:
+    """Slice each engine group's block IDs for a token range.
+
+    The range is given in tokens — the only unit shared by every engine
+    group. A group whose paged chunks each cover ``tokens_per_block`` tokens
+    holds one block ID per ``tokens_per_block`` tokens, so the range is
+    divided by that group's ``tokens_per_block``. Example: over the same 256
+    tokens, a tokens_per_block-64 group gets 4 IDs while a
+    tokens_per_block-256 group gets 1.
+
+    Args:
+        allocated_block_ids: Block IDs keyed by engine group id; a missing group
+            yields an empty list.
+        group_tokens_per_block: Each group's tokens-per-paged-chunk, in
+            engine-group order. Every value must be positive and divide both
+            range endpoints.
+        start_token_idx: Range start token index, inclusive.
+        end_token_idx: Range end token index, exclusive.
+
+    Returns:
+        One block-ID list per engine group, in engine-group order.
+
+    Raises:
+        ValueError: If the range does not align to a group's chunk boundary.
+    """
+    sliced: list[list[int]] = []
+    for engine_group_idx, tokens_per_block in enumerate(group_tokens_per_block):
+        if start_token_idx % tokens_per_block != 0 or (
+            end_token_idx % tokens_per_block != 0
+        ):
+            raise ValueError(
+                f"token range [{start_token_idx}, {end_token_idx}) does not "
+                f"align to group {engine_group_idx} tokens_per_block "
+                f"{tokens_per_block}"
+            )
+        group_block_ids = allocated_block_ids.get(engine_group_idx, [])
+        sliced.append(
+            list(
+                group_block_ids[
+                    start_token_idx // tokens_per_block : end_token_idx
+                    // tokens_per_block
+                ]
+            )
+        )
+    return sliced
+
+
+def get_engine_group_indices(
+    groups: Sequence[EngineGroupInfo],
+    num_registered_layers: int,
+) -> list[int] | None:
+    """Return the engine group index for each registered KV tensor.
+
+    Args:
+        groups: The LMCache KV groups, in protocol order.
+        num_registered_layers: Number of KV tensors registered with the server,
+            i.e. the length of the per-layer mapping to produce.
+
+    Returns:
+        A list of length ``num_registered_layers`` mapping each registered
+        tensor index to its engine group id, or ``None`` when there is no group
+        metadata (empty ``groups`` or zero layers) so callers fall back to
+        single-group behavior. Registered tensors not referenced by any group
+        are marked with ``EXCLUDED_ENGINE_GROUP`` (cross-layer KV-sharing layers
+        whose KV lives in their target owner's blocks); downstream grouping
+        skips them.
+
+    Raises:
+        ValueError: If a group references a layer index outside
+            ``[0, num_registered_layers)``.
+    """
+    # First Party
+    from lmcache.v1.kv_layer_groups import EXCLUDED_ENGINE_GROUP
+
+    if not groups or num_registered_layers == 0:
+        return None
+
+    # Default to "excluded": layers no group references are intentionally left
+    # out of grouping (e.g. KV-sharing layers aliasing a target owner's cache).
+    per_layer_engine_group_idx = [EXCLUDED_ENGINE_GROUP] * num_registered_layers
+
+    for group in groups:
+        for layer_idx in group.layer_indices:
+            if layer_idx < 0 or layer_idx >= num_registered_layers:
+                raise ValueError(
+                    f"Layer index {layer_idx} is outside registered layer "
+                    f"range [0, {num_registered_layers})"
+                )
+            per_layer_engine_group_idx[layer_idx] = group.engine_group_id
+
+    return per_layer_engine_group_idx
diff --git a/lmcache/v1/multiprocess/http_api_registry.py b/lmcache/v1/multiprocess/http_api_registry.py
new file mode 100644
index 0000000..3633ad2
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_api_registry.py
@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+
+# Third Party
+from fastapi import APIRouter, FastAPI
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.utils.router_discovery import discover_api_routers
+
+logger = init_logger(__name__)
+
+
+class HTTPAPIRegistry:
+    """
+    Automatically discovers and registers HTTP API routes
+    from the ``http_apis`` sub-package.
+
+    Any module whose name ends with ``_api`` and exposes a
+    module-level ``router`` (:class:`~fastapi.APIRouter`) will
+    be picked up automatically.
+    """
+
+    def __init__(self, app: FastAPI):
+        self.app = app
+        self.router = APIRouter()
+
+    def register_all_apis(self) -> None:
+        """
+        Discover and register all ``*_api`` modules under
+        the ``http_apis`` directory.
+        """
+        apis_path = Path(__file__).parent / "http_apis"
+        if not apis_path.exists():
+            logger.warning("http_apis directory not found")
+            return
+
+        apis_package = f"{__package__}.http_apis"
+
+        for r in discover_api_routers(apis_path, apis_package):
+            self.router.include_router(r)
+
+        self.app.include_router(self.router)
diff --git a/lmcache/v1/multiprocess/http_apis/__init__.py b/lmcache/v1/multiprocess/http_apis/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/multiprocess/http_apis/cache_api.py b/lmcache/v1/multiprocess/http_apis/cache_api.py
new file mode 100644
index 0000000..bc603bf
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/cache_api.py
@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cache-management HTTP endpoints on the MP server (node-local).
+
+A single ``/cache/*`` surface, thin over the typed services in
+``lmcache/v1/multiprocess/cache_control/`` (resolved via :func:`get_context`):
+
+- Objects   -- ``GET /cache/objects``, ``DELETE /cache/objects``
+  (:class:`ObjectService`). Adapter listing lives in the config group
+  (``GET /config/adapters``).
+- Prefetch  -- ``POST /cache/prefetches``, ``GET /cache/prefetches/{id}``
+  (:class:`PrefetchService`).
+- Diagnostics -- ``POST /cache/clear``, ``POST /cache/checksums`` (engine-local).
+
+The object / prefetch routes are pass-throughs: the services validate and raise
+domain errors, which the central handler in :mod:`error_handlers` maps to status
+codes -- so there is no per-route ``try/except``. The diagnostics routes reach
+engine internals directly (no service) and validate inline.
+"""
+
+# Standard
+from http import HTTPStatus
+from typing import Any, Optional
+import asyncio
+import hashlib
+
+# Third Party
+from fastapi import APIRouter, HTTPException, Query, Request
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import compress_slot_mapping
+from lmcache.v1.distributed.tiers import Tier
+from lmcache.v1.multiprocess.http_apis.dependencies import get_context
+from lmcache.v1.multiprocess.http_apis.schemas import (
+    ChecksumRequest,
+    ClearRequest,
+    DeleteObjectsRequest,
+    PrefetchRequest,
+)
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+router = APIRouter()
+
+_MAX_PAGE_SIZE = 5000
+_DEFAULT_PAGE_SIZE = 500
+_CLEAR_TIER = Tier.L1
+
+
+# ---------------------------------------------------------------------------
+# Objects -- pass-throughs to ObjectService
+# ---------------------------------------------------------------------------
+
+
+@router.get("/cache/objects", response_model=None)
+async def list_cache_objects(
+    request: Request,
+    tier: Tier = Tier.L2,
+    adapter: str | None = Query(default=None),
+    model_name: str | None = Query(default=None),
+    page_size: int = Query(default=_DEFAULT_PAGE_SIZE, ge=1, le=_MAX_PAGE_SIZE),
+    page_token: str | None = Query(default=None),
+) -> dict[str, object]:
+    """List cache objects resident in one tier/adapter, paginated.
+
+    Responses:
+        200: ``{"adapter", "entries", "next_page_token"}``.
+        400: ``tier`` unsupported or malformed ``page_token``. 404: adapter
+            matches none.
+        503: server not initialized, no adapters configured, or the adapter does
+            not support listing.
+    """
+    return await get_context(request).object_service.list_objects(
+        tier, adapter, model_name, page_size, page_token
+    )
+
+
+@router.delete("/cache/objects", response_model=None)
+async def delete_cache_objects(
+    body: DeleteObjectsRequest, request: Request
+) -> dict[str, object]:
+    """Delete a caller-supplied list of object keys from one tier/adapter.
+
+    Responses:
+        200: ``{"requested", "adapter", "ok"[, "error"]}``.
+        400: batch too large, ``ObjectKey`` invariant violation, or unsupported
+            tier. 404: adapter matches none. 422: body validation.
+        503: server not initialized, or no adapters configured.
+    """
+    return await get_context(request).object_service.delete_objects(
+        body.tier, body.adapter, body.keys
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prefetch -- pass-throughs to PrefetchService
+# ---------------------------------------------------------------------------
+
+
+@router.post("/cache/prefetches", response_model=None, status_code=202)
+async def submit_prefetch(body: PrefetchRequest, request: Request) -> dict[str, object]:
+    """Submit a warm prefetch of a token sequence from L2 into L1.
+
+    Responses:
+        202: ``{"request_id", "chunks", "status": "submitted"}``, or
+            ``{"chunks": 0, "status": "noop"}`` for a sub-chunk sequence.
+        400: token cap exceeded, invalid ``cache_salt``, or unsupported tiers.
+        422: body validation.
+        503: not initialized, or no layout registered for the model.
+    """
+    return get_context(request).prefetch_service.submit(
+        body.model_name,
+        body.world_size,
+        body.token_ids,
+        body.cache_salt,
+        body.source_tier,
+        body.target_tier,
+    )
+
+
+@router.get("/cache/prefetches/{request_id}", response_model=None)
+async def get_prefetch(request_id: str, request: Request) -> dict[str, object]:
+    """Poll a submitted warm prefetch.
+
+    Responses:
+        200: ``{"request_id", "status": "pending"}`` or ``{"request_id",
+            "status": "completed", "found_keys", "total_keys"}``.
+        404: unknown id. 503: server not initialized.
+    """
+    return get_context(request).prefetch_service.status(request_id)
+
+
+# ---------------------------------------------------------------------------
+# Diagnostics (clear, checksums) -- engine-local; validated inline
+# ---------------------------------------------------------------------------
+
+# Per-format axis of the ``num_blocks`` dimension inside a per-layer KV tensor.
+# The checksum endpoint gathers KV data by block IDs along this axis, which
+# preserves the block_size dimension verbatim so chunking is a clean slice on a
+# known axis. Formats that fuse num_blocks and block_size into a single
+# page-buffer dimension are intentionally not listed: the block-level semantics
+# don't map cleanly, and the endpoint declines them with 501.
+_BLOCK_AXIS_BY_FORMAT: dict[Any, int] = {
+    lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS: 1,  # [2, NB, BS, NH, HS]
+    lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS: 0,  # [NB, 2, BS, NH, HS]
+    lmc_ops.EngineKVFormat.NL_X_NB_BS_HS: 0,  # MLA: [NB, BS, HS]
+    lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS: 1,  # [2, NB, NH, BS, HS]
+    lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS: 0,  # [NB, 2, NH, BS, HS]
+}
+
+
+@router.post("/cache/clear", response_model=None)
+async def clear_cache(
+    request: Request, body: ClearRequest | None = None
+) -> dict[str, object]:
+    """Force-clear a tier's resident cache.
+
+    Clears all objects in the tier, including those with active read/write
+    locks; in-flight store/prefetch operations may be corrupted.
+
+    The body is optional: an absent (or empty) body defaults to
+    ``{"tier": "l1", "force": true}``.
+
+    Responses:
+        200: ``{"status": "ok", "cleared": {"tier": "l1"}}``.
+        400: unsupported tier. 503: server not initialized.
+    """
+    if body is None:
+        body = ClearRequest()
+    if body.tier != _CLEAR_TIER:
+        raise HTTPException(
+            status_code=HTTPStatus.BAD_REQUEST,
+            detail=(
+                f"tier {body.tier.value!r} not supported; only {_CLEAR_TIER.value!r}"
+            ),
+        )
+    # TODO(cache-control): ``body.force`` is accepted for API forward-compat but
+    # not honored -- the engine's CLEAR path always force-clears. Wiring it
+    # through would require extending the ZMQ ``RequestType.CLEAR`` payload
+    # (which currently carries no fields) so the cross-process op can pass force.
+    get_context(request).engine.clear()
+    logger.info("Cache cleared via HTTP API")
+    return {"status": "ok", "cleared": {"tier": _CLEAR_TIER.value}}
+
+
+def _resolve_per_layer_block_axes(
+    formats_per_layer: list[Optional["lmc_ops.EngineKVFormat"]],
+) -> tuple[Optional[list[int]], Optional[str]]:
+    """Map each layer to its ``num_blocks`` axis from its Engine KV format.
+
+    Each layer uses its own axis, so mixed-format models are checksummed rather
+    than rejected. A ``None`` layer (cross-layer KV sharing) inherits a
+    single-format model's axis and is rejected in a mixed-format one.
+
+    Returns ``(block_axes, None)``, or ``(None, error)`` if a format is
+    unsupported or a ``None`` layer can't be resolved.
+    """
+    axis_by_format: dict[int, int] = {}
+    for fmt in formats_per_layer:
+        if fmt is None or int(fmt) in axis_by_format:
+            continue
+        axis = _BLOCK_AXIS_BY_FORMAT.get(fmt)
+        if axis is None:
+            return None, "checksum not supported for GPU KV format %s" % fmt.name
+        axis_by_format[int(fmt)] = axis
+
+    shared_axis = (
+        next(iter(axis_by_format.values())) if len(axis_by_format) == 1 else None
+    )
+    block_axes: list[int] = []
+    for fmt in formats_per_layer:
+        if fmt is not None:
+            block_axes.append(axis_by_format[int(fmt)])
+        elif shared_axis is not None:
+            block_axes.append(shared_axis)
+        else:
+            return None, (
+                "checksum not supported: a cross-layer KV-sharing layer in a "
+                "mixed-format model has no resolvable block axis"
+            )
+    return block_axes, None
+
+
+def _compute_block_checksums(
+    kv_tensors: list[torch.Tensor],
+    block_ids: list[int],
+    block_axes: list[int],
+    chunk_size: int,
+    layerwise: bool,
+) -> dict[str, Any]:
+    """Compute MD5 checksums over KV cache blocks, grouped ``chunk_size`` blocks
+    per chunk.
+
+    The gather is performed in block space on each layer's own block axis via
+    :func:`torch.index_select`, so mixed-format models gather each layer
+    correctly. Each layer's gathered tensor is moved to CPU once, then chunk
+    checksums slice it along its block axis in steps of ``chunk_size`` blocks.
+    ``bfloat16`` is upcast to ``float32`` only if present.
+    """
+    num_blocks = len(block_ids)
+    num_chunks = (num_blocks + chunk_size - 1) // chunk_size
+
+    block_idx_cpu = torch.tensor(block_ids, dtype=torch.long)
+    block_idx_by_device: dict[torch.device, torch.Tensor] = {
+        block_idx_cpu.device: block_idx_cpu,
+    }
+
+    layer_blocks: list[torch.Tensor] = []
+    for li, kv in enumerate(kv_tensors):
+        idx = block_idx_by_device.get(kv.device)
+        if idx is None:
+            idx = block_idx_cpu.to(kv.device)
+            block_idx_by_device[kv.device] = idx
+        gathered = kv.index_select(block_axes[li], idx).cpu()
+        if gathered.dtype == torch.bfloat16:
+            gathered = gathered.to(torch.float32)
+        layer_blocks.append(gathered)
+
+    def _chunk_slice(t: torch.Tensor, axis: int, start: int, end: int) -> torch.Tensor:
+        return t.narrow(axis, start, end - start).contiguous()
+
+    if layerwise:
+        per_layer: dict[str, list[str]] = {}
+        for li, blocks in enumerate(layer_blocks):
+            axis = block_axes[li]
+            digests: list[str] = []
+            for ci in range(num_chunks):
+                s = ci * chunk_size
+                e = min(s + chunk_size, num_blocks)
+                chunk = _chunk_slice(blocks, axis, s, e)
+                digests.append(hashlib.md5(chunk.numpy().tobytes()).hexdigest())
+            per_layer["layer_%d" % li] = digests
+        return {
+            "status": "success",
+            "chunk_size": chunk_size,
+            "num_chunks": num_chunks,
+            "chunk_checksums": per_layer,
+            "layerwise": True,
+        }
+
+    aggregated: list[str] = []
+    for ci in range(num_chunks):
+        s = ci * chunk_size
+        e = min(s + chunk_size, num_blocks)
+        md5 = hashlib.md5()
+        for li, blocks in enumerate(layer_blocks):
+            chunk = _chunk_slice(blocks, block_axes[li], s, e)
+            md5.update(chunk.numpy().tobytes())
+        aggregated.append(md5.hexdigest())
+    return {
+        "status": "success",
+        "chunk_size": chunk_size,
+        "num_chunks": num_chunks,
+        "chunk_checksums": aggregated,
+        "layerwise": False,
+    }
+
+
+@router.post("/cache/checksums", response_model=None)
+async def cache_checksums(body: ChecksumRequest, request: Request) -> dict[str, Any]:
+    """Compute MD5 checksums over KV cache blocks, ``chunk_size`` blocks/chunk.
+
+    Responses:
+        200: ``{"status": "success", "chunk_size", "num_chunks",
+            "chunk_checksums", "layerwise", "block_id_ranges"}``.
+        400: no ``block_ids`` or non-positive ``chunk_size``.
+        404: unknown ``instance_id`` or empty KV. 501: unsupported engine/format.
+        503: server not initialized.
+    """
+    engine = get_context(request).engine
+    cache_ctxs = getattr(engine, "cache_contexts", None)
+    if cache_ctxs is None:
+        raise HTTPException(
+            status_code=HTTPStatus.NOT_IMPLEMENTED,
+            detail="checksum not supported for this engine type",
+        )
+    ctx = cache_ctxs.get(body.instance_id)
+    if ctx is None:
+        raise HTTPException(
+            status_code=HTTPStatus.NOT_FOUND,
+            detail="instance_id %d not registered" % body.instance_id,
+        )
+    if not body.block_ids:
+        raise HTTPException(
+            status_code=HTTPStatus.BAD_REQUEST, detail="block_ids is required"
+        )
+    if body.chunk_size <= 0:
+        raise HTTPException(
+            status_code=HTTPStatus.BAD_REQUEST, detail="chunk_size must be positive"
+        )
+    kv_tensors = ctx.kv_tensors
+    if not kv_tensors:
+        raise HTTPException(status_code=HTTPStatus.NOT_FOUND, detail="kv_caches empty")
+
+    block_axes, axis_err = _resolve_per_layer_block_axes(
+        ctx.engine_kv_format_per_layer()
+    )
+    if block_axes is None:
+        raise HTTPException(status_code=HTTPStatus.NOT_IMPLEMENTED, detail=axis_err)
+
+    loop = asyncio.get_running_loop()
+    result = await loop.run_in_executor(
+        None,
+        lambda: _compute_block_checksums(
+            kv_tensors, body.block_ids, block_axes, body.chunk_size, body.layerwise
+        ),
+    )
+    result["block_id_ranges"] = compress_slot_mapping(body.block_ids)
+    return result
diff --git a/lmcache/v1/multiprocess/http_apis/common_api.py b/lmcache/v1/multiprocess/http_apis/common_api.py
new file mode 100644
index 0000000..696ea76
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/common_api.py
@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Aggregate HTTP routes exposed by ``lmcache.v1.internal_api_server.common``.
+
+This module discovers every ``*_api`` sub-module under the
+``internal_api_server/common`` package and merges their ``router``
+attributes into a single :class:`~fastapi.APIRouter` named
+``router`` so that :class:`HTTPAPIRegistry` picks it up through the
+standard ``http_apis`` auto-discovery mechanism.
+
+Adding a new API module under ``internal_api_server/common`` requires
+no changes here: it is registered automatically.
+
+Note:
+    Some modules under ``internal_api_server/common`` target the
+    vLLM-embedded API server and rely on attributes that only exist
+    on that server's ``app.state`` (e.g. ``lmcache_adapter``).  Such
+    modules are listed in ``_MP_INCOMPATIBLE_MODULES`` and skipped
+    here so they don't raise misleading 500s when invoked on the
+    multiprocess HTTP server.
+"""
+
+# Standard
+from pathlib import Path
+
+# Third Party
+from fastapi import APIRouter
+
+# First Party
+from lmcache.v1 import internal_api_server
+from lmcache.v1.utils.router_discovery import discover_api_routers
+
+router = APIRouter()
+
+# Modules that depend on vLLM-specific ``app.state`` attributes and
+# therefore cannot run on the multiprocess HTTP server.
+_MP_INCOMPATIBLE_MODULES: frozenset[str] = frozenset()
+
+_common_path = Path(internal_api_server.__file__).parent / "common"
+_common_package = f"{internal_api_server.__name__}.common"
+
+for _discovered in discover_api_routers(
+    _common_path,
+    _common_package,
+    exclude=_MP_INCOMPATIBLE_MODULES,
+):
+    router.include_router(_discovered)
diff --git a/lmcache/v1/multiprocess/http_apis/config_api.py b/lmcache/v1/multiprocess/http_apis/config_api.py
new file mode 100644
index 0000000..1832973
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/config_api.py
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import is_dataclass
+from typing import Any
+import json
+
+# Third Party
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+# First Party
+from lmcache.v1.multiprocess.http_apis.dependencies import get_context
+from lmcache.v1.utils.json_utils import make_json_safe, safe_asdict
+
+router = APIRouter()
+
+
+class _IndentedJSONResponse(JSONResponse):
+    """JSONResponse with indented output for readability."""
+
+    def render(self, content: Any) -> bytes:
+        return json.dumps(
+            content,
+            ensure_ascii=False,
+            allow_nan=False,
+            indent=2,
+        ).encode("utf-8")
+
+
+@router.get("/config")
+async def config(request: Request) -> Any:
+    """
+    Return all server configurations (mp, storage_manager,
+    observability) as a single JSON object.
+
+    Args:
+        request (Request): The incoming HTTP request; its
+            ``app.state.configs`` mapping is serialized.
+
+    Returns:
+        Any: A JSON response whose body is a dict keyed by
+        config name. Returns HTTP 503 if ``configs`` is not
+        initialized yet.
+
+    Exceptions:
+        None.
+    """
+    configs = getattr(request.app.state, "configs", None)
+    if configs is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "configs not initialized"},
+        )
+    result = {}
+    for name, cfg in configs.items():
+        if is_dataclass(cfg) and not isinstance(cfg, type):
+            result[name] = safe_asdict(cfg)
+        else:
+            result[name] = make_json_safe(cfg)
+    return _IndentedJSONResponse(content=result)
+
+
+@router.get("/config/adapters", response_model=None)
+async def list_adapters(request: Request) -> dict[str, object]:
+    """Enumerate the live cache adapters.
+
+    Listing which storage adapters the engine loaded is a configuration
+    inspection concern, so it lives under the ``/config`` group rather than
+    ``/cache``. This is the single live adapter listing -- it supersedes the
+    removed ``/reconfigure/backends`` (the reconfigurable backends are the
+    ``type_name`` values whose ``reconfigurable`` flag is ``true``). It is a thin
+    pass-through to :meth:`ObjectService.list_adapters`.
+
+    Args:
+        request (Request): The incoming HTTP request; its per-app
+            :class:`MPHTTPContext` is resolved via :func:`get_context`.
+
+    Returns:
+        dict[str, object]: ``{"adapters": [{"index", "type_name", "tier",
+        "primary", "reconfigurable"}, ...]}``. Pass a ``reconfigurable``
+        adapter's ``type_name`` as the ``{backend}`` path parameter to
+        ``GET /reconfigure/{backend}/status`` and the reconfigure operations.
+
+    Raises:
+        HTTPException: ``503`` if the engine context is not initialized yet.
+    """
+    return get_context(request).object_service.list_adapters()
diff --git a/lmcache/v1/multiprocess/http_apis/dependencies.py b/lmcache/v1/multiprocess/http_apis/dependencies.py
new file mode 100644
index 0000000..97200fc
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/dependencies.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP-layer wiring for the MP server's cache handlers.
+
+Holds the per-app context (the typed services the handlers operate on) and the
+FastAPI dependency that retrieves it from the request. The context is built once
+in the server lifespan (after the engine is initialized). Retrieving it is the
+one genuinely HTTP-shaped concern here -- a request that races startup gets a
+``503`` -- so it lives in this adapter layer, not in ``cache_control``.
+"""
+
+# Standard
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any
+
+# Third Party
+from fastapi import HTTPException, Request
+
+# First Party
+from lmcache.v1.multiprocess.cache_control.object_service import ObjectService
+from lmcache.v1.multiprocess.cache_control.prefetch_service import PrefetchService
+
+
+@dataclass
+class MPHTTPContext:
+    """Typed collaborators the MP server's cache handlers operate on.
+
+    Attributes:
+        engine: The node's cache engine (``MPCacheServer``); the diagnostics
+            handlers (clear / checksums) reach engine internals directly.
+        object_service: Adapter / object listing and key-addressed deletion.
+        prefetch_service: Warm-prefetch submit / status (owns the job table).
+    """
+
+    engine: Any
+    object_service: ObjectService
+    prefetch_service: PrefetchService
+
+
+def build_context(engine: Any) -> MPHTTPContext:
+    """Construct the per-app context once the engine is ready.
+
+    Called from the server lifespan; the result is stashed on
+    ``app.state.context`` for :func:`get_context` to return.
+
+    Args:
+        engine: The initialized node cache engine.
+
+    Returns:
+        A fresh :class:`MPHTTPContext` wrapping the engine and its services.
+    """
+    return MPHTTPContext(
+        engine=engine,
+        object_service=ObjectService(engine),
+        prefetch_service=PrefetchService(engine),
+    )
+
+
+def get_context(request: Request) -> MPHTTPContext:
+    """Return the per-app :class:`MPHTTPContext`, or raise ``HTTPException``.
+
+    Args:
+        request: The FastAPI request whose ``app.state`` carries the context.
+
+    Returns:
+        The live :class:`MPHTTPContext`.
+
+    Raises:
+        HTTPException: 503 when the engine (and thus the context) isn't
+            initialized yet -- e.g. a request that races server startup. This is
+            a transport/DI concern, not a domain failure.
+    """
+    context = getattr(request.app.state, "context", None)
+    if context is None:
+        raise HTTPException(
+            status_code=HTTPStatus.SERVICE_UNAVAILABLE, detail="server not initialized"
+        )
+    return context
diff --git a/lmcache/v1/multiprocess/http_apis/error_handlers.py b/lmcache/v1/multiprocess/http_apis/error_handlers.py
new file mode 100644
index 0000000..0c0ee4b
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/error_handlers.py
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Map cache-control domain errors onto HTTP responses, centrally.
+
+The ``cache_control`` services raise transport-agnostic
+:class:`CacheControlError` subclasses; this module owns the single place where
+those become HTTP status codes. Registering one handler for the base class
+(Starlette matches by the exception's MRO) means routes never need a
+``try/except`` -- a domain error raised anywhere in the call stack is converted
+here into a ``{"detail": ...}`` body with the mapped status.
+"""
+
+# Standard
+from http import HTTPStatus
+
+# Third Party
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+# First Party
+from lmcache.v1.multiprocess.cache_control.errors import (
+    CacheControlError,
+    InvalidRequest,
+    NotFound,
+    Unavailable,
+)
+
+# Domain error type -> HTTP status. The only place the two vocabularies meet.
+_STATUS_BY_ERROR: dict[type[CacheControlError], HTTPStatus] = {
+    InvalidRequest: HTTPStatus.BAD_REQUEST,
+    NotFound: HTTPStatus.NOT_FOUND,
+    Unavailable: HTTPStatus.SERVICE_UNAVAILABLE,
+}
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """Register the cache-control domain-error handler on ``app``.
+
+    Must be called on the ``FastAPI`` app (not a router); router auto-discovery
+    does not pick up exception handlers.
+
+    Args:
+        app: The FastAPI application to attach the handler to.
+    """
+
+    async def _handle(request: Request, exc: Exception) -> JSONResponse:
+        # Registered for CacheControlError, so the isinstance branch always
+        # holds; the signature is widened to ``Exception`` to match Starlette's
+        # handler type (and narrowed back here for the typed lookup).
+        if isinstance(exc, CacheControlError):
+            status = _STATUS_BY_ERROR.get(type(exc), HTTPStatus.INTERNAL_SERVER_ERROR)
+        else:
+            status = HTTPStatus.INTERNAL_SERVER_ERROR
+        return JSONResponse(status_code=status, content={"detail": str(exc)})
+
+    app.add_exception_handler(CacheControlError, _handle)
diff --git a/lmcache/v1/multiprocess/http_apis/info_api.py b/lmcache/v1/multiprocess/http_apis/info_api.py
new file mode 100644
index 0000000..cdf7d68
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/info_api.py
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Basic-info endpoints: liveness, health, status, and version.
+
+These are the small, dependency-light routes used to inspect that the
+server is up and what it is running:
+
+- ``GET /`` — static liveness payload (does not touch the engine).
+- ``GET /healthcheck`` — Kubernetes liveness/readiness probe.
+- ``GET /status`` — detailed internal state of all MP components.
+- ``GET /version``, ``/lmc_version``, ``/commit_id`` — version descriptors,
+  re-exposed from the shared ``internal_api_server.vllm`` version router.
+"""
+
+# Standard
+from typing import Any
+
+# Third Party
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+# First Party
+from lmcache.v1.internal_api_server.vllm.version_api import router as _version_router
+
+router = APIRouter()
+
+# Re-expose the shared version routes (/version, /lmc_version, /commit_id)
+# as part of the basic-info group.
+router.include_router(_version_router)
+
+
+@router.get("/")
+async def root() -> dict[str, str]:
+    """
+    Basic liveness check endpoint.
+    Returns:
+        dict: A dictionary containing the status and service name.
+    """
+    return {"status": "ok", "service": "LMCache HTTP API"}
+
+
+@router.get("/healthcheck")
+async def healthcheck(request: Request) -> Any:
+    """
+    Health check endpoint for k8s liveness/readiness probes.
+
+    Checks:
+        - HTTP server is alive (implicit: if you get a response)
+        - Cache engine is alive
+    """
+    engine = getattr(request.app.state, "engine", None)
+    if engine is None:
+        return JSONResponse(
+            status_code=503,
+            content={
+                "status": "unhealthy",
+                "reason": "engine not initialized",
+            },
+        )
+
+    return {"status": "healthy"}
+
+
+@router.get("/status")
+async def status(request: Request) -> Any:
+    """
+    Detailed status endpoint for inspecting internal state
+    of all MP components (L1 cache, L2 adapters, controllers,
+    sessions).
+    """
+    engine = getattr(request.app.state, "engine", None)
+    if engine is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "engine not initialized"},
+        )
+    return engine.report_status()
diff --git a/lmcache/v1/multiprocess/http_apis/quota_api.py b/lmcache/v1/multiprocess/http_apis/quota_api.py
new file mode 100644
index 0000000..26ef2f0
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/quota_api.py
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Per-``cache_salt`` quota management endpoints.
+
+The adapter's ``IsolatedLRU`` eviction policy uses these quotas to
+scope per-bucket eviction decisions. Quotas are soft: setting a limit
+does not reject writes — any over-budget bucket is evicted at the
+next eviction cycle (~1s). Removing or never setting a quota leaves
+the bucket at an effective limit of ``0`` bytes, so its data is
+cleared next cycle (allowlist semantics).
+"""
+
+# Standard
+from typing import Any
+import math
+
+# Third Party
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+router = APIRouter()
+
+
+# ``cache_salt=""`` (un-salted / anonymous traffic) cannot appear in a
+# URL path parameter, so the API accepts this sentinel in its place.
+#
+# COLLISION CAVEAT: a user who legitimately stores data with
+# ``cache_salt="_default"`` cannot be managed via this HTTP API
+# distinctly from anonymous traffic — both map to the same path
+# parameter. Deployments that want to manage such a user should set
+# ``cache_salt`` to any other value (e.g. ``"default"`` without the
+# underscore, or a tenant prefix).
+_DEFAULT_SALT_SENTINEL = "_default"
+
+
+def _unescape_salt(path_salt: str) -> str:
+    """Translate the URL sentinel back to the empty-string salt."""
+    return "" if path_salt == _DEFAULT_SALT_SENTINEL else path_salt
+
+
+def _escape_salt(salt: str) -> str:
+    """Translate the empty-string salt to the URL sentinel."""
+    return _DEFAULT_SALT_SENTINEL if salt == "" else salt
+
+
+def _gb(n_bytes: int) -> float:
+    """Convert bytes → GB for the JSON payload."""
+    return n_bytes / (1024**3)
+
+
+def _get_storage_manager(request: Request) -> Any:
+    """Resolve the shared ``StorageManager`` or return a 503 response.
+
+    Returns either the ``StorageManager`` instance or a
+    ``JSONResponse`` (503) ready to be returned directly from the
+    endpoint — keeps the endpoint bodies short.
+    """
+    engine = getattr(request.app.state, "engine", None)
+    if engine is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "engine not initialized"},
+        )
+    return engine.storage_manager
+
+
+@router.put("/quota/{cache_salt}")
+async def set_quota(cache_salt: str, request: Request) -> Any:
+    """Create or update a quota for the given ``cache_salt``.
+
+    Body: ``{"limit_gb": <float>}`` (required, non-negative).
+    """
+    sm = _get_storage_manager(request)
+    if isinstance(sm, JSONResponse):
+        return sm
+
+    try:
+        body = await request.json()
+    except Exception:
+        return JSONResponse(status_code=400, content={"error": "invalid JSON body"})
+    if not isinstance(body, dict) or "limit_gb" not in body:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "body must be {'limit_gb': <float>}"},
+        )
+    try:
+        limit_gb = float(body["limit_gb"])
+    except (TypeError, ValueError):
+        return JSONResponse(
+            status_code=400,
+            content={"error": "limit_gb must be numeric"},
+        )
+    if not math.isfinite(limit_gb):
+        # ``nan`` / ``inf`` would propagate to an int() cast below that
+        # raises OverflowError / ValueError (reported as a 500). Reject
+        # here so the error surfaces as a clean 400.
+        return JSONResponse(
+            status_code=400,
+            content={"error": "limit_gb must be finite"},
+        )
+    if limit_gb < 0:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "limit_gb must be non-negative"},
+        )
+
+    salt = _unescape_salt(cache_salt)
+    try:
+        sm.quota_manager.set_quota(salt, int(limit_gb * (1024**3)))
+    except ValueError as exc:
+        return JSONResponse(status_code=400, content={"error": str(exc)})
+    return {
+        "cache_salt": _escape_salt(salt),
+        "limit_gb": limit_gb,
+        "status": "ok",
+    }
+
+
+@router.get("/quota/{cache_salt}")
+async def get_quota(cache_salt: str, request: Request) -> Any:
+    """Read the current quota + live usage for a single salt."""
+    sm = _get_storage_manager(request)
+    if isinstance(sm, JSONResponse):
+        return sm
+
+    salt = _unescape_salt(cache_salt)
+    exists = sm.quota_manager.has_quota(salt)
+    limit_bytes = sm.quota_manager.get_limit_bytes(salt)
+    usage_bytes = sm.get_usage_bytes_by_cache_salt().get(salt, 0)
+    return {
+        "cache_salt": _escape_salt(salt),
+        "limit_gb": _gb(limit_bytes),
+        "current_usage_gb": _gb(usage_bytes),
+        "exists": exists,
+    }
+
+
+@router.delete("/quota/{cache_salt}")
+async def delete_quota(cache_salt: str, request: Request) -> Any:
+    """Remove a salt's quota entry.
+
+    Any bytes still cached under this salt become over-budget on the
+    next eviction cycle (effective limit drops to 0) and will be
+    evicted.
+    """
+    sm = _get_storage_manager(request)
+    if isinstance(sm, JSONResponse):
+        return sm
+
+    salt = _unescape_salt(cache_salt)
+    removed = sm.quota_manager.delete_quota(salt)
+    return {
+        "cache_salt": _escape_salt(salt),
+        "status": "removed" if removed else "not_found",
+    }
+
+
+@router.get("/quota")
+async def list_quotas(request: Request) -> Any:
+    """List every registered quota alongside its live usage."""
+    sm = _get_storage_manager(request)
+    if isinstance(sm, JSONResponse):
+        return sm
+
+    usage_map = sm.get_usage_bytes_by_cache_salt()
+    users: dict[str, dict[str, float]] = {}
+    for entry in sm.quota_manager.list_quotas():
+        used_bytes = usage_map.get(entry.cache_salt, 0)
+        users[_escape_salt(entry.cache_salt)] = {
+            "limit_gb": _gb(entry.limit_bytes),
+            "current_usage_gb": _gb(used_bytes),
+        }
+    return {"users": users}
diff --git a/lmcache/v1/multiprocess/http_apis/reconfigure_api.py b/lmcache/v1/multiprocess/http_apis/reconfigure_api.py
new file mode 100644
index 0000000..7d6ae13
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/reconfigure_api.py
@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Runtime L2 adapter reconfiguration endpoints for MP mode."""
+
+# Standard
+from decimal import Decimal
+from typing import Literal, Protocol, cast
+
+# Third Party
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.reconfiguration import L2ReconfigureError
+
+router = APIRouter()
+
+_MAX_SIZE_STRING_LEN = 64
+_SIZE_ERROR = "size must be a positive integer byte count or a string like '100GiB'"
+_SIZE_UNITS = {
+    "": 1,
+    "b": 1,
+    "k": 1024,
+    "kb": 1024,
+    "kib": 1024,
+    "m": 1024**2,
+    "mb": 1024**2,
+    "mib": 1024**2,
+    "g": 1024**3,
+    "gb": 1024**3,
+    "gib": 1024**3,
+    "t": 1024**4,
+    "tb": 1024**4,
+    "tib": 1024**4,
+}
+SizeRequest = int | str
+
+
+class _StorageManagerLike(Protocol):
+    def get_l2_adapter_reconfigure_status(self) -> dict: ...
+
+    def reconfigure_l2_adapter(
+        self,
+        adapter_index: int,
+        operation: str,
+        payload: dict[str, object],
+    ) -> dict: ...
+
+
+class _EngineLike(Protocol):
+    storage_manager: _StorageManagerLike
+
+
+class GenericReconfigureRequest(BaseModel):
+    """Request body for generic ``POST /reconfigure/{backend}/{operation}``."""
+
+    model_config = ConfigDict(extra="allow")
+
+    adapter_index: int = 0
+
+
+class DaxAddRequest(BaseModel):
+    """Request body for ``POST /reconfigure/dax/add``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    adapter_index: int = 0
+    device_path: str
+    size: SizeRequest
+
+
+class DaxRemoveRequest(BaseModel):
+    """Request body for ``POST /reconfigure/dax/remove``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    adapter_index: int = 0
+    device_path: str
+    mode: Literal["migrate", "evict", "drain"] = "migrate"
+    force: bool = False
+
+
+class DaxResizeRequest(BaseModel):
+    """Request body for ``POST /reconfigure/dax/resize``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    adapter_index: int = 0
+    device_path: str
+    size: SizeRequest
+    mode: Literal["migrate", "evict"] = "migrate"
+    force: bool = False
+
+
+def _get_storage_manager(request: Request) -> _StorageManagerLike | JSONResponse:
+    engine = getattr(request.app.state, "engine", None)
+    if engine is None:
+        return JSONResponse(
+            status_code=503,
+            content={"error": "engine not initialized"},
+        )
+    return cast(_EngineLike, engine).storage_manager
+
+
+def _parse_size_string(size: str) -> int:
+    text = size.strip()
+    if not text or len(text) > _MAX_SIZE_STRING_LEN:
+        raise ValueError(_SIZE_ERROR)
+
+    unit_start = len(text)
+    while unit_start > 0 and text[unit_start - 1].isalpha():
+        unit_start -= 1
+
+    value_text = text[:unit_start].strip()
+    unit = text[unit_start:].lower()
+    if unit not in _SIZE_UNITS:
+        raise ValueError(_SIZE_ERROR)
+    if "." in value_text:
+        whole, fraction = value_text.split(".", 1)
+        if not whole or not fraction:
+            raise ValueError(_SIZE_ERROR)
+        if not whole.isdigit() or not fraction.isdigit():
+            raise ValueError(_SIZE_ERROR)
+    elif not value_text.isdigit():
+        raise ValueError(_SIZE_ERROR)
+
+    value = Decimal(value_text)
+    if value <= 0:
+        raise ValueError(_SIZE_ERROR)
+    return int(value * _SIZE_UNITS[unit])
+
+
+def _resolve_size_bytes(size: SizeRequest) -> int:
+    if isinstance(size, bool):
+        raise ValueError(_SIZE_ERROR)
+    resolved = size if isinstance(size, int) else _parse_size_string(size)
+    if resolved <= 0:
+        raise ValueError(_SIZE_ERROR)
+    return resolved
+
+
+def _api_error_response(exc: L2ReconfigureError) -> JSONResponse:
+    return JSONResponse(status_code=exc.status_code, content=exc.payload)
+
+
+def _validation_error_response(exc: ValidationError) -> JSONResponse:
+    return JSONResponse(status_code=422, content={"detail": exc.errors()})
+
+
+def _normalize_backend(backend: str) -> str:
+    normalized = backend.strip().lower()
+    if not normalized:
+        raise L2ReconfigureError(400, "backend must be non-empty")
+    return normalized
+
+
+def _normalize_operation(operation: str) -> str:
+    normalized = operation.strip().lower()
+    if not normalized:
+        raise L2ReconfigureError(400, "operation must be non-empty")
+    return normalized
+
+
+def _adapter_backend_name(adapter: dict) -> str | None:
+    backend = adapter.get("backend", adapter.get("type"))
+    if isinstance(backend, str) and backend:
+        return backend
+    return None
+
+
+def _backend_adapter_entries(status: dict, backend: str) -> list[tuple[int, dict]]:
+    raw_adapters = status.get("adapters", [])
+    if not isinstance(raw_adapters, list):
+        return []
+
+    backend_adapters = []
+    for raw_index, adapter in enumerate(raw_adapters):
+        if not isinstance(adapter, dict) or _adapter_backend_name(adapter) != backend:
+            continue
+        generic_index = adapter.get("adapter_index", raw_index)
+        if not isinstance(generic_index, int):
+            generic_index = raw_index
+        backend_adapters.append((generic_index, adapter))
+    return backend_adapters
+
+
+def _backend_status_response(status: dict, backend: str) -> dict:
+    adapters = []
+    for backend_index, (_, adapter) in enumerate(
+        _backend_adapter_entries(status, backend)
+    ):
+        public_adapter = dict(adapter)
+        public_adapter["adapter_index"] = backend_index
+        adapters.append(public_adapter)
+    return {
+        "enabled": bool(adapters),
+        "backend": backend,
+        "num_adapters": len(adapters),
+        "adapters": adapters,
+    }
+
+
+def _resolve_backend_adapter_index(
+    sm: _StorageManagerLike,
+    backend: str,
+    adapter_index: int,
+) -> int:
+    adapters = _backend_adapter_entries(
+        sm.get_l2_adapter_reconfigure_status(),
+        backend,
+    )
+    if adapter_index < 0 or adapter_index >= len(adapters):
+        raise L2ReconfigureError(404, f"{backend} adapter not found")
+    generic_index, _ = adapters[adapter_index]
+    return generic_index
+
+
+def _dax_operation_payload(
+    operation: str,
+    payload: dict[str, object],
+) -> tuple[int, dict[str, object]] | JSONResponse:
+    try:
+        if operation == "add":
+            add_body = DaxAddRequest.model_validate(payload)
+            try:
+                size_bytes = _resolve_size_bytes(add_body.size)
+            except ValueError:
+                return JSONResponse(status_code=400, content={"error": _SIZE_ERROR})
+            return (
+                add_body.adapter_index,
+                {
+                    "device_path": add_body.device_path,
+                    "size_bytes": size_bytes,
+                },
+            )
+
+        if operation == "remove":
+            remove_body = DaxRemoveRequest.model_validate(payload)
+            return (
+                remove_body.adapter_index,
+                {
+                    "device_path": remove_body.device_path,
+                    "mode": remove_body.mode,
+                    "force": remove_body.force,
+                },
+            )
+
+        if operation == "resize":
+            resize_body = DaxResizeRequest.model_validate(payload)
+            try:
+                size_bytes = _resolve_size_bytes(resize_body.size)
+            except ValueError:
+                return JSONResponse(status_code=400, content={"error": _SIZE_ERROR})
+            return (
+                resize_body.adapter_index,
+                {
+                    "device_path": resize_body.device_path,
+                    "size_bytes": size_bytes,
+                    "mode": resize_body.mode,
+                    "force": resize_body.force,
+                },
+            )
+    except ValidationError as exc:
+        return _validation_error_response(exc)
+
+    raise L2ReconfigureError(
+        400,
+        f"unsupported dax reconfigure operation: {operation}",
+    )
+
+
+def _generic_operation_payload(
+    payload: dict[str, object],
+) -> tuple[int, dict[str, object]] | JSONResponse:
+    try:
+        body = GenericReconfigureRequest.model_validate(payload)
+    except ValidationError as exc:
+        return _validation_error_response(exc)
+
+    operation_payload = dict(body.model_extra or {})
+    return body.adapter_index, operation_payload
+
+
+def _operation_payload(
+    backend: str,
+    operation: str,
+    payload: dict[str, object],
+) -> tuple[int, dict[str, object]] | JSONResponse:
+    if backend == "dax":
+        return _dax_operation_payload(operation, payload)
+    return _generic_operation_payload(payload)
+
+
+@router.get("/reconfigure/{backend}/status", response_model=None)
+async def reconfigure_status(backend: str, request: Request) -> dict | JSONResponse:
+    """Return runtime reconfiguration status for one backend type."""
+    sm = _get_storage_manager(request)
+    if isinstance(sm, JSONResponse):
+        return sm
+    try:
+        normalized_backend = _normalize_backend(backend)
+        status = sm.get_l2_adapter_reconfigure_status()
+        return _backend_status_response(status, normalized_backend)
+    except L2ReconfigureError as exc:
+        return _api_error_response(exc)
+
+
+@router.post("/reconfigure/{backend}/{operation}", response_model=None)
+async def reconfigure_backend(
+    backend: str,
+    operation: str,
+    payload: dict[str, object],
+    request: Request,
+) -> dict | JSONResponse:
+    """Apply a runtime reconfiguration operation to one backend type."""
+    sm = _get_storage_manager(request)
+    if isinstance(sm, JSONResponse):
+        return sm
+    try:
+        normalized_backend = _normalize_backend(backend)
+        normalized_operation = _normalize_operation(operation)
+        resolved = _operation_payload(normalized_backend, normalized_operation, payload)
+        if isinstance(resolved, JSONResponse):
+            return resolved
+        adapter_index, operation_payload = resolved
+        generic_adapter_index = _resolve_backend_adapter_index(
+            sm,
+            normalized_backend,
+            adapter_index,
+        )
+        return sm.reconfigure_l2_adapter(
+            generic_adapter_index,
+            normalized_operation,
+            operation_payload,
+        )
+    except L2ReconfigureError as exc:
+        return _api_error_response(exc)
diff --git a/lmcache/v1/multiprocess/http_apis/schemas.py b/lmcache/v1/multiprocess/http_apis/schemas.py
new file mode 100644
index 0000000..bd6a8e0
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_apis/schemas.py
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP wire models for the MP server's ``/cache/*`` endpoints.
+
+These describe request bodies only -- the HTTP boundary. FastAPI validates them
+(field types -> 422) before a handler runs; semantic validation and responses
+belong to the ``cache_control`` services. ``Tier`` is imported from the domain
+(it is cache vocabulary, not an HTTP type).
+"""
+
+# Standard
+from dataclasses import dataclass, field
+
+# First Party
+from lmcache.v1.distributed.api import EncodedObjectKey
+from lmcache.v1.distributed.tiers import Tier
+
+
+@dataclass(frozen=True)
+class DeleteObjectsRequest:
+    """Wire body for ``DELETE /cache/objects``.
+
+    ``keys`` field types are validated by FastAPI (422); their ``ObjectKey``
+    invariants, the batch cap, and tier support are enforced by the service.
+    ``tier`` defaults to ``l2``; ``adapter`` selects an adapter, else the primary.
+    """
+
+    keys: list[EncodedObjectKey]
+    tier: Tier = Tier.L2
+    adapter: str | None = None
+
+
+@dataclass(frozen=True)
+class PrefetchRequest:
+    """Wire body for ``POST /cache/prefetches``.
+
+    Callers describe content by ``token_ids``; the server resolves the per-rank
+    keys itself. ``source_tier`` / ``target_tier`` are request data (today only
+    ``l2`` -> ``l1``).
+    """
+
+    model_name: str
+    world_size: int
+    token_ids: list[int]
+    cache_salt: str = ""
+    source_tier: Tier = Tier.L2
+    target_tier: Tier = Tier.L1
+
+
+@dataclass(frozen=True)
+class ClearRequest:
+    """Wire body for ``POST /cache/clear``.
+
+    ``tier`` is request data (today only ``l1``). ``force=true`` means active
+    locks may be ignored if the implementation supports forced cleanup.
+    """
+
+    tier: Tier = Tier.L1
+    force: bool = True
+
+
+@dataclass(frozen=True)
+class ChecksumRequest:
+    """Wire body for ``POST /cache/checksums``.
+
+    ``block_ids`` are the target GPU block IDs; ``chunk_size`` blocks are hashed
+    per chunk. ``instance_id`` selects the GPU context; ``layerwise`` returns
+    per-layer digests.
+    """
+
+    block_ids: list[int] = field(default_factory=list)
+    chunk_size: int = 0
+    instance_id: int = 0
+    layerwise: bool = False
diff --git a/lmcache/v1/multiprocess/http_server.py b/lmcache/v1/multiprocess/http_server.py
new file mode 100644
index 0000000..43a382d
--- /dev/null
+++ b/lmcache/v1/multiprocess/http_server.py
@@ -0,0 +1,292 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import asynccontextmanager
+import argparse
+import asyncio
+import contextlib
+
+# Third Party
+from fastapi import FastAPI
+import httpx
+import uvicorn
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.config import (
+    StorageManagerConfig,
+    add_storage_manager_args,
+    l1_exposes_single_memory_region,
+    parse_args_to_config,
+)
+from lmcache.v1.mp_coordinator.cache_control.event_listener import L2EventListener
+from lmcache.v1.mp_coordinator.registrar import keep_registered
+from lmcache.v1.mp_observability.config import (
+    ObservabilityConfig,
+    add_observability_args,
+    parse_args_to_observability_config,
+)
+from lmcache.v1.mp_observability.event_bus import get_event_bus
+from lmcache.v1.multiprocess.config import (
+    DEFAULT_COORDINATOR_CONFIG,
+    CoordinatorConfig,
+    HTTPFrontendConfig,
+    MPServerConfig,
+    add_coordinator_args,
+    add_http_frontend_args,
+    add_mp_server_args,
+    add_p2p_args,
+    parse_args_to_coordinator_config,
+    parse_args_to_http_frontend_config,
+    parse_args_to_mp_server_config,
+)
+from lmcache.v1.multiprocess.http_api_registry import (
+    HTTPAPIRegistry,
+)
+from lmcache.v1.multiprocess.http_apis.dependencies import build_context
+from lmcache.v1.multiprocess.http_apis.error_handlers import register_error_handlers
+from lmcache.v1.multiprocess.mp_runtime_plugin_launcher import (
+    MPRuntimePluginLauncher,
+)
+from lmcache.v1.multiprocess.server import run_cache_server
+
+logger = init_logger(__name__)
+
+
+# Module-level config holders, set by run_http_server() before FastAPI startup.
+# Stored in a dict so the lifespan closure captures the mutable container.
+_configs: dict = {}
+
+
+# ----------------------------
+# FastAPI lifespan for initialization and cleanup
+# ----------------------------
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Manage the lifecycle of the LMCache HTTP server.
+
+    On startup: Initialize ZMQ server and cache engine.
+    On shutdown: Clean up ZMQ server resources.
+    """
+    # Startup
+    logger.info(
+        "Starting LMCache HTTP server... (accelerator available: %s)",
+        torch_dev.is_available(),
+    )
+    mp_config = _configs["mp"]
+    coordinator_config = _configs.get("coordinator") or DEFAULT_COORDINATOR_CONFIG
+
+    result = run_cache_server(
+        mp_config=mp_config,
+        storage_manager_config=_configs["storage_manager"],
+        obs_config=_configs["observability"],
+        return_engine=True,
+        start_prometheus_http_server=False,
+        coordinator_config=coordinator_config,
+    )
+    assert result is not None, "run_cache_server returned None with return_engine=True"
+    zmq_server, engine = result
+
+    # Launch runtime plugins if configured. Plugins receive the full
+    # server config (including HTTP host/port) via the
+    # LMCACHE_RUNTIME_PLUGIN_CONFIG environment variable.
+    plugin_launcher = None
+    if mp_config.runtime_plugin_config.locations:
+        extra_kwargs = {}
+        http_config = _configs.get("http")
+        if http_config is not None:
+            extra_kwargs["http_config"] = http_config
+        plugin_launcher = MPRuntimePluginLauncher(
+            runtime_plugin_config=mp_config.runtime_plugin_config,
+            mp_config=mp_config,
+            storage_manager_config=_configs["storage_manager"],
+            obs_config=_configs["observability"],
+            **extra_kwargs,
+        )
+        plugin_launcher.launch_plugins()
+
+    app.state.zmq_server = zmq_server
+    app.state.engine = engine
+    # Typed per-app context the cache handlers resolve via ``get_context``
+    # (built now that the engine is ready).
+    app.state.context = build_context(engine)
+    app.state.plugin_launcher = plugin_launcher
+
+    # Optionally register this server with an MP coordinator (enabled when
+    # coordinator config has a URL). A generic HTTP client sends the requests;
+    # the keep_registered task registers, heartbeats, and deregisters on
+    # shutdown. Best-effort: failures are logged and retried, never fatal.
+    http_config = _configs.get("http")
+    coordinator_client = None
+    coordinator_registration_task = None
+    if coordinator_config.url and http_config is not None:
+        coordinator_client = httpx.AsyncClient(timeout=10.0)
+        # Canonical id resolved by run_cache_server above; shared with
+        # the OTel service.instance.id so membership matches metrics/traces.
+        coordinator_registration_task = asyncio.create_task(
+            keep_registered(
+                coordinator_client,
+                coordinator_config.url,
+                http_port=http_config.http_port,
+                instance_id=mp_config.instance_id,
+                advertise_ip=coordinator_config.advertise_ip,
+                heartbeat_interval=coordinator_config.heartbeat_interval,
+                p2p_advertised_url=mp_config.p2p_config.advertise_url,
+                mq_port=mp_config.port if mp_config.p2p_config.enabled else 0,
+            )
+        )
+    # Optionally report L2 store/lookup events to the coordinator for
+    # fleet-wide usage tracking and eviction. Registers as a listener on
+    # all L2 adapters and flushes batched events on a timer.
+    coordinator_l2_event_client = None
+    coordinator_l2_event_task = None
+    if (
+        coordinator_client is not None
+        and coordinator_config is not None
+        and coordinator_config.url
+        and coordinator_config.l2_event_reporting
+    ):
+        coordinator_l2_event_client = L2EventListener(
+            coordinator_client,
+            coordinator_config.url,
+            instance_id=mp_config.instance_id,
+            flush_interval=coordinator_config.l2_event_flush_interval,
+        )
+        if engine.storage_manager is not None:
+            engine.storage_manager.register_l2_listener(coordinator_l2_event_client)
+        coordinator_l2_event_task = asyncio.create_task(
+            coordinator_l2_event_client.run()
+        )
+
+    app.state.coordinator_client = coordinator_client
+    app.state.coordinator_registration_task = coordinator_registration_task
+    app.state.coordinator_l2_event_task = coordinator_l2_event_task
+
+    logger.info("LMCache HTTP server initialized")
+
+    yield
+
+    # Shutdown
+    logger.info("Shutting down LMCache HTTP server...")
+    coordinator_l2_event_task = getattr(app.state, "coordinator_l2_event_task", None)
+    if coordinator_l2_event_task is not None:
+        coordinator_l2_event_task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await coordinator_l2_event_task
+    coordinator_registration_task = getattr(
+        app.state, "coordinator_registration_task", None
+    )
+    if coordinator_registration_task is not None:
+        coordinator_registration_task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await coordinator_registration_task
+    coordinator_client = getattr(app.state, "coordinator_client", None)
+    if coordinator_client is not None:
+        await coordinator_client.aclose()
+    launcher = getattr(app.state, "plugin_launcher", None)
+    if launcher is not None:
+        launcher.stop_plugins()
+    get_event_bus().stop()
+    if hasattr(app.state, "zmq_server") and app.state.zmq_server is not None:
+        app.state.zmq_server.close()
+    logger.info("LMCache HTTP server stopped")
+
+
+app = FastAPI(title="LMCache HTTP API", version="1.0.0", lifespan=lifespan)
+
+# Automatically discover and register all HTTP API endpoints
+registry = HTTPAPIRegistry(app)
+registry.register_all_apis()
+
+# Map cache-control domain errors to HTTP responses centrally, so routes need
+# no try/except (auto-discovery finds routers, not exception handlers).
+register_error_handlers(app)
+
+
+def run_http_server(
+    http_config: HTTPFrontendConfig,
+    mp_config: MPServerConfig,
+    storage_manager_config: StorageManagerConfig,
+    obs_config: ObservabilityConfig,
+    coordinator_config: CoordinatorConfig,
+) -> None:
+    """
+    Run the LMCache HTTP server with integrated MP (ZMQ) server.
+
+    Args:
+        http_config: Configuration for the HTTP frontend
+        mp_config: Configuration for the ZMQ multiprocess server
+        storage_manager_config: Configuration for the storage manager
+        obs_config: Configuration for the observability stack
+        coordinator_config: Configuration for MP coordinator registration
+            (an empty URL disables registration)
+
+    Raises:
+        ValueError: If P2P is enabled without a coordinator URL, or with an L1
+            tier that is not a single registerable memory region.
+    """
+    if mp_config.p2p_config.enabled:
+        if not coordinator_config.url:
+            raise ValueError(
+                "P2P requires a coordinator for peer discovery: set "
+                "--coordinator-url (or LMCACHE_COORDINATOR_URL) when "
+                "--p2p-advertise-url is set."
+            )
+        if not l1_exposes_single_memory_region(storage_manager_config):
+            raise ValueError(
+                "P2P requires a single L1 memory region the transfer channel "
+                "can register; it is incompatible with GDS L1 (--gds-l1-path) "
+                "and Device-DAX L1 (--l1-devdax-path)."
+            )
+    _configs["mp"] = mp_config
+    _configs["storage_manager"] = storage_manager_config
+    _configs["observability"] = obs_config
+    _configs["http"] = http_config
+    _configs["coordinator"] = coordinator_config
+    app.state.configs = _configs
+
+    config = uvicorn.Config(
+        app=app,
+        host=http_config.http_host,
+        port=http_config.http_port,
+        log_level="info",
+        access_log=True,
+    )
+    server = uvicorn.Server(config)
+
+    logger.info(
+        "Starting LMCache HTTP server on http://%s:%d",
+        http_config.http_host,
+        http_config.http_port,
+    )
+    server.run()
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="LMCache HTTP Server with integrated MP Cache Server"
+    )
+    add_http_frontend_args(parser)
+    add_mp_server_args(parser)
+    add_p2p_args(parser)
+    add_storage_manager_args(parser)
+    add_observability_args(parser)
+    add_coordinator_args(parser)
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    http_config = parse_args_to_http_frontend_config(args)
+    mp_config = parse_args_to_mp_server_config(args)
+    storage_manager_config = parse_args_to_config(args)
+    obs_config = parse_args_to_observability_config(args)
+    coordinator_config = parse_args_to_coordinator_config(args)
+    run_http_server(
+        http_config=http_config,
+        mp_config=mp_config,
+        storage_manager_config=storage_manager_config,
+        obs_config=obs_config,
+        coordinator_config=coordinator_config,
+    )
diff --git a/lmcache/v1/multiprocess/modules/__init__.py b/lmcache/v1/multiprocess/modules/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/multiprocess/modules/blend.py b/lmcache/v1/multiprocess/modules/blend.py
new file mode 100644
index 0000000..97f0a71
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/blend.py
@@ -0,0 +1,1185 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Blend (context-blend / cross-request KV reuse) module for MPCacheServer."""
+
+# Standard
+from typing import Any
+import threading
+import time
+
+# Third Party
+import numpy as np
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.utils import check_interprocess_event_support
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchHandle,
+    ipc_key_to_object_keys,
+)
+from lmcache.v1.gpu_connector.gpu_ops import (
+    lmcache_memcpy_async_d2h,
+    lmcache_memcpy_async_h2d,
+)
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.multiprocess.custom_types import (
+    CBMatchResult,
+    IPCCacheServerKey,
+    KVCache,
+)
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.protocols.base import RequestType
+from lmcache.v1.multiprocess.token_hasher import (
+    chunk_hash_windows_numba,
+    rolling_hash_windows_numba,
+    unique_hits_direct_id_numba,
+    update_table_id_numba,
+)
+from lmcache.v1.platform.cuda.cache_context import PlainGPUCacheContext
+
+logger = init_logger(__name__)
+
+
+class BlendTokenRangeMatcher:
+    """Fast token-range matcher using polynomial rolling/chunk hashes and a
+    direct-address lookup table.
+
+    Table layout: poly_chunk_hash (u64) -> compact_chunk_id (i64, sequential 0...N-1).
+
+    Because compact IDs are bounded by _TABLE_SIZE, unique_hits_direct_id_numba
+    can use a fixed ``seen`` array of _TABLE_SIZE bytes (~1 MB) rather than one
+    sized by an arbitrary max hash -- no memory explosion.
+
+    Auxiliary storage:
+      _chunk_token_hash[i]      : token_hash for chunk i (None if evicted)
+      _token_hash_to_start      : token_hash -> start position in seq
+      _compact_id_to_slot[i]    : table slot for compact_id i
+      _token_hash_to_compact_id : token_hash -> compact_chunk_id
+
+    Methods:
+      on_new_token_hashes  -- register a sequence; builds fingerprints
+                              and writes compact IDs.
+      match_sub_sequence   -- sliding-window probe -> compact IDs ->
+                              token_hash -> start. Skips evicted entries.
+      remove_chunks        -- lazily evict stale entries. Clears the
+                              table slot and auxiliary maps.
+
+    Args:
+        chunk_size: Number of tokens per chunk for fingerprint computation.
+    """
+
+    _TABLE_BITS: int = 20  # 2^20 ~ 1 M entries
+    _TABLE_SIZE: int = 1 << _TABLE_BITS
+    _BASE: np.uint64 = np.uint64(0x9E3779B97F4A7C15)  # Fibonacci-hashing constant
+
+    def __init__(self, chunk_size: int = 256):
+        self.chunk_size = chunk_size
+        # poly_chunk_hash -> compact_chunk_id; -1 = empty
+        self._table_id = np.full(self._TABLE_SIZE, -1, dtype=np.int64)
+        self._mask = np.uint64(self._TABLE_SIZE - 1)
+        # compact_chunk_id -> caller-supplied token_hash (full bytes)
+        self._chunk_token_hash: list[bytes | None] = []
+        # token_hash -> start position in its registered sequence
+        self._token_hash_to_start: dict[bytes, int] = {}
+        # compact_chunk_id -> table slot index (for reverse lookup during eviction)
+        self._compact_id_to_slot = np.full(self._TABLE_SIZE, -1, dtype=np.int64)
+        # token_hash -> compact_chunk_id (for eviction lookup)
+        self._token_hash_to_compact_id: dict[bytes, int] = {}
+        self._lock = threading.Lock()
+
+    def on_new_token_hashes(
+        self,
+        token_ids: list[int],
+        token_hashes: list[bytes],
+    ) -> None:
+        """Register a new token sequence and index its non-overlapping chunks.
+
+        Args:
+            token_ids: Raw token IDs for the full sequence (num_tokens elements).
+                       Used to compute polynomial chunk fingerprints that match
+                       the rolling hashes computed in match_sub_sequence.
+            token_hashes: Per-chunk bytes hashes supplied by the caller
+                          (one per complete chunk of chunk_size tokens).
+                          Stored as the storage key returned in CBMatchResult.hash.
+        """
+        arr = np.array(token_ids, dtype=np.uint64)
+        # Polynomial fingerprints for non-overlapping chunks, built from raw
+        # token IDs so they match the rolling hashes in match_sub_sequence
+        chunk_hashes = chunk_hash_windows_numba(arr, self.chunk_size, self._BASE)
+        n = int(chunk_hashes.shape[0])
+        if n == 0:
+            return
+
+        with self._lock:
+            # Filter chunks already registered to avoid duplicate compact-ID
+            # allocation.  When both cb_store_pre_computed and cb_store_final
+            # fire for the same token sequence they produce identical hashes;
+            # registering twice orphans the first compact ID permanently since
+            # _token_hash_to_compact_id is overwritten but the old list slot is
+            # not freed.
+            new_idxs = [
+                i
+                for i in range(n)
+                if token_hashes[i] not in self._token_hash_to_compact_id
+            ]
+            if not new_idxs:
+                return
+            n_new = len(new_idxs)
+            new_chunk_hashes = chunk_hashes[new_idxs]
+
+            # Compact sequential IDs: bounded by _TABLE_SIZE, safe for seen-array sizing
+            # NOTE: base_id grows monotonically (evicted slots are not reused); the hard
+            # limit is on total chunks ever registered, not active chunks.
+            base_id = len(self._chunk_token_hash)
+            if base_id + n_new > self._TABLE_SIZE:
+                logger.error(
+                    "BlendTokenRangeMatcher compact-ID overflow: %d chunks "
+                    "registered, cannot add %d more (limit %d). Skipping.",
+                    base_id,
+                    n_new,
+                    self._TABLE_SIZE,
+                )
+                return
+            if base_id + n_new > int(self._TABLE_SIZE * 0.8):
+                logger.warning(
+                    "BlendTokenRangeMatcher nearing capacity: %d/%d compact IDs used. "
+                    "Hash collision rate is rising; hit rate will degrade.",
+                    base_id + n_new,
+                    self._TABLE_SIZE,
+                )
+            compact_ids = np.arange(base_id, base_id + n_new, dtype=np.int64)
+
+            # Write table: poly_chunk_hash -> compact_chunk_id
+            update_table_id_numba(new_chunk_hashes, self._table_id, compact_ids)
+
+            # Persist compact_id -> token_hash, token_hash -> start, and reverse maps
+            for k, orig_i in enumerate(new_idxs):
+                th = token_hashes[orig_i]
+                cid = int(compact_ids[k])
+                slot = int(new_chunk_hashes[k]) & int(self._mask)
+                self._chunk_token_hash.append(th)
+                self._token_hash_to_start[th] = orig_i * self.chunk_size
+                self._compact_id_to_slot[cid] = slot
+                self._token_hash_to_compact_id[th] = cid
+
+    def match_sub_sequence(
+        self,
+        token_ids: list[int],
+    ) -> list[CBMatchResult]:
+        """Find stored chunks whose fingerprints appear anywhere in token_ids.
+
+        Uses a sliding-window rolling hash so matches need not be aligned to
+        chunk_size boundaries in the query.  Entries previously evicted via
+        remove_chunks (token_hash set to None) are silently skipped.
+
+        Args:
+            token_ids: Query token sequence to probe (raw token IDs as uint64).
+
+        Returns:
+            One CBMatchResult per unique stored chunk that was hit.
+              old_st/old_ed : positions in the originally registered sequence
+              cur_st/cur_ed : positions in the query (token_ids) where
+                              the match was found
+              hash          : token_hash bytes (from registration) for cache key lookup
+        """
+        if len(token_ids) < self.chunk_size:
+            return []
+
+        arr = np.array(token_ids, dtype=np.uint64)
+        # Sliding-window polynomial hashes over the query
+        rolling = rolling_hash_windows_numba(arr, self.chunk_size, self._BASE)
+
+        with self._lock:
+            if not self._chunk_token_hash:
+                return []
+
+            # Probe table; seen array is _TABLE_SIZE bytes (~1 MB), fixed and safe
+            hit_ids = unique_hits_direct_id_numba(
+                rolling, self._table_id, self._mask, self._TABLE_SIZE
+            )
+
+            if hit_ids.shape[0] == 0:
+                return []
+
+            # For each hit compact_id, find the first query position where it matched
+            hit_id_set = set(int(cid) for cid in hit_ids)
+            cid_to_query_pos: dict[int, int] = {}
+            for q_pos in range(rolling.shape[0]):
+                idx = int(rolling[q_pos]) & int(self._mask)
+                cid = int(self._table_id[idx])
+                if cid in hit_id_set and cid not in cid_to_query_pos:
+                    cid_to_query_pos[cid] = q_pos
+                    if len(cid_to_query_pos) == len(hit_id_set):
+                        break
+
+            results: list[CBMatchResult] = []
+            for cid in hit_ids:
+                cid_int = int(cid)
+                th = self._chunk_token_hash[cid_int]
+                if th is None:
+                    continue
+                old_st = self._token_hash_to_start.get(th)
+                cur_st = cid_to_query_pos.get(cid_int)
+                if old_st is None or cur_st is None:
+                    continue
+                results.append(
+                    CBMatchResult(
+                        old_st=old_st,
+                        old_ed=old_st + self.chunk_size,
+                        cur_st=cur_st,
+                        cur_ed=cur_st + self.chunk_size,
+                        hash=th,
+                    )
+                )
+            return results
+
+    def remove_chunks(self, token_hashes: list[bytes]) -> None:
+        """Evict stale entries whose backing data is no longer in storage.
+
+        Args:
+            token_hashes: Token hashes of chunks to remove from the table.
+        """
+        with self._lock:
+            for th in token_hashes:
+                cid = self._token_hash_to_compact_id.get(th)
+                if cid is None:
+                    continue
+                # Clear the table slot
+                slot = int(self._compact_id_to_slot[cid])
+                if slot < 0:
+                    logger.warning(
+                        "compact_id %d has no valid table slot; "
+                        "entry may have been evicted twice",
+                        cid,
+                    )
+                    continue
+                self._table_id[slot] = -1
+                self._compact_id_to_slot[cid] = -1
+                # Clean up auxiliary maps
+                self._chunk_token_hash[cid] = None
+                self._token_hash_to_start.pop(th, None)
+                del self._token_hash_to_compact_id[th]
+
+    def has_chunk(self, token_hash: bytes) -> bool:
+        """Return True if token_hash is currently registered in the matcher.
+
+        Used before lazy registration to avoid creating duplicate compact-ID
+        entries for a hash that is already in the fingerprint table.
+
+        Args:
+            token_hash: The storage hash bytes for a single chunk (as returned
+                        by TokenHasher.compute_chunk_hashes).
+
+        Returns:
+            True if the chunk is registered and not evicted, False otherwise.
+        """
+        with self._lock:
+            return token_hash in self._token_hash_to_compact_id
+
+
+def _unique_token_coverage(results: list[CBMatchResult]) -> int:
+    """Return the number of unique query tokens covered by a set of CBMatchResults.
+
+    match_sub_sequence is a sliding-window probe, so two results from different
+    registered chunks can have overlapping [cur_st, cur_ed) ranges.  Summing
+    chunk_size per result would double-count the overlapping tokens and produce
+    hit_rate > 1.  This function merges the intervals first.
+
+    Args:
+        results: Found CBMatchResult objects (each covers [cur_st, cur_ed) tokens).
+
+    Returns:
+        Total number of unique query-token positions covered.
+    """
+    if not results:
+        return 0
+    intervals = sorted((r.cur_st, r.cur_ed) for r in results)
+    coverage = 0
+    cur_end = -1
+    for st, ed in intervals:
+        if st >= cur_end:
+            coverage += ed - st
+        elif ed > cur_end:
+            coverage += ed - cur_end
+        cur_end = max(cur_end, ed)
+    return coverage
+
+
+class BlendModule:
+    """Handles blend (context-blend / cross-request KV reuse) operations.
+
+    Owns CB-specific GPU context registrations and the token range matcher.
+    Provides handlers for CB register, unregister, store, retrieve, and lookup.
+
+    Args:
+        ctx: The shared engine context.
+    """
+
+    def __init__(self, ctx: MPCacheServerContext) -> None:
+        self._ctx = ctx
+        self._cb_gpu_contexts: dict[int, PlainGPUCacheContext] = {}
+        self._cb_gpu_context_meta: dict[int, tuple[str, int]] = {}
+        self._token_range_matcher = BlendTokenRangeMatcher(ctx.chunk_size)
+        self._gpu_copy_lock = threading.Lock()
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        return self._ctx
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves.
+
+        Returns:
+            A list of HandlerSpec entries mapping request types to
+            their handler callables and thread pool assignments.
+        """
+        return [
+            HandlerSpec(
+                RequestType.CB_REGISTER_KV_CACHE,
+                self.cb_register_kv_cache,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.CB_UNREGISTER_KV_CACHE,
+                self.cb_unregister_kv_cache,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.CB_STORE_PRE_COMPUTED,
+                self.cb_store_pre_computed,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.CB_RETRIEVE_PRE_COMPUTED_V2,
+                self.cb_retrieve_pre_computed,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.CB_STORE_FINAL,
+                self.cb_store_final,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.CB_LOOKUP_PRE_COMPUTED_V2,
+                self.cb_lookup_pre_computed,
+                ThreadPoolType.NORMAL,
+            ),
+        ]
+
+    def report_status(self) -> dict:
+        """Return blend module status information.
+
+        Returns:
+            A dict containing registered CB GPU instance IDs and
+            per-instance KV cache layout metadata.
+        """
+        cb_gpu_context_meta: dict[str, dict] = {}
+        for gpu_id, meta in self._cb_gpu_context_meta.items():
+            model_name, world_size = meta
+            entry: dict = {
+                "model_name": model_name,
+                "world_size": world_size,
+            }
+            ctx = self._cb_gpu_contexts.get(gpu_id)
+            if ctx is not None:
+                # bytes per token = 2 (K+V) * num_layers * hidden_dim_size *
+                # itemsize; num_tokens is the cache capacity, not a per-token
+                # cost.
+                cache_size_per_token = (
+                    2 * ctx.num_layers * ctx.hidden_dim_size * ctx.dtype.itemsize
+                )
+                entry["kv_cache_layout"] = {
+                    "num_layers": ctx.num_layers,
+                    "num_tokens": ctx.num_tokens,
+                    "hidden_dim_size": ctx.hidden_dim_size,
+                    "dtype": str(ctx.dtype),
+                    "cache_size_per_token": cache_size_per_token,
+                }
+            cb_gpu_context_meta[str(gpu_id)] = entry
+
+        return {
+            "registered_cb_gpu_ids": list(self._cb_gpu_contexts.keys()),
+            "cb_gpu_context_meta": cb_gpu_context_meta,
+        }
+
+    def close(self) -> None:
+        """Release resources owned by this module."""
+        self._cb_gpu_contexts.clear()
+        self._cb_gpu_context_meta.clear()
+
+    def cb_register_kv_cache(
+        self,
+        instance_id: int,
+        kv_caches: KVCache,
+        model_name: str,
+        world_size: int,
+    ) -> None:
+        """Register the KV cache buffer from the blend engine.
+
+        Args:
+            instance_id: Unique identifier for the blend engine instance.
+            kv_caches: KVCache object containing the GPU buffer pointers.
+            model_name: The name of the model associated with this KV cache.
+            world_size: The world size associated with this KV cache.
+        """
+        gpu_context = PlainGPUCacheContext(kv_caches, self._ctx.chunk_size)
+        self._cb_gpu_contexts[instance_id] = gpu_context
+        self._cb_gpu_context_meta[instance_id] = (model_name, world_size)
+
+        layout_desc = MemoryLayoutDesc(
+            shapes=[gpu_context.get_kv_buffer_shape(self._ctx.chunk_size)],
+            dtypes=[gpu_context.dtype],
+        )
+        self._ctx.layout_desc_registry.register(model_name, world_size, layout_desc)
+
+        logger.info(
+            "Registered CB KV cache for instance_id %d with %d layers",
+            instance_id,
+            gpu_context.num_layers,
+        )
+
+    def cb_unregister_kv_cache(self, instance_id: int) -> None:
+        """Unregister the KV cache buffer for the given instance_id.
+
+        Args:
+            instance_id: Unique identifier for the blend engine instance
+                to unregister.
+        """
+        if instance_id in self._cb_gpu_contexts:
+            model_name, world_size = self._cb_gpu_context_meta[instance_id]
+            del self._cb_gpu_contexts[instance_id]
+            del self._cb_gpu_context_meta[instance_id]
+            self._ctx.layout_desc_registry.unregister(model_name, world_size)
+            logger.info("Unregistered CB KV cache for instance_id %d", instance_id)
+        else:
+            logger.warning(
+                "Attempted to unregister non-existent CB KV cache for instance_id %d",
+                instance_id,
+            )
+
+    def cb_lookup_pre_computed(self, key: IPCCacheServerKey) -> list[CBMatchResult]:
+        """Lookup the pre-computed chunks in the underlying storage.
+
+        Uses BlendTokenRangeMatcher for a fast local pre-filter, then submits
+        prefetch tasks for matched chunks using their stored hashes directly.
+        Chunks that the fingerprint table matched but are no longer present in
+        storage are lazily evicted from the matcher via remove_chunks.
+
+        Args:
+            key: IPCCacheServerKey containing the token ids to lookup.
+
+        Returns:
+            List of CBMatchResult for chunks that were actually found in storage,
+            ready to be passed to cb_retrieve_pre_computed.
+        """
+        num_tokens = len(key.token_ids)
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_START,
+                session_id=key.request_id,
+            )
+        )
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=key.request_id,
+                metadata={"num_tokens": num_tokens},
+            )
+        )
+
+        cb_match_result = self._token_range_matcher.match_sub_sequence(
+            list(key.token_ids)
+        )
+        if not cb_match_result:
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id=key.request_id,
+                    metadata={
+                        "num_tokens": num_tokens,
+                        "fingerprint_hits": 0,
+                        "prefix_hits": 0,
+                        "storage_hits": 0,
+                        "stale_chunks": 0,
+                        "no_gpu_context": False,
+                        "hit_tokens": 0,
+                        "requested_tokens": (num_tokens // self._ctx.chunk_size)
+                        * self._ctx.chunk_size,
+                    },
+                )
+            )
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.CB_REQUEST_END,
+                    session_id=key.request_id,
+                )
+            )
+            return []
+
+        # Sort by query position
+        cb_match_result.sort(key=lambda r: r.cur_st)
+
+        # The sliding-window probe returns O(table_size) overlapping matches.
+        # Greedy leftmost-first picks one chunk per slot; lossless when matches
+        # are chunk-aligned (the CB case).
+        deduped: list[CBMatchResult] = []
+        covered_end = -1
+        for r in cb_match_result:
+            if r.cur_st >= covered_end:
+                deduped.append(r)
+                covered_end = r.cur_ed
+        cb_match_result = deduped
+
+        # Group consecutive matched chunks
+        groups: list[list[CBMatchResult]] = []
+        for result in cb_match_result:
+            if groups and groups[-1][-1].cur_ed == result.cur_st:
+                groups[-1].append(result)
+            else:
+                groups.append([result])
+
+        prefetch_handles: list[PrefetchHandle] = []
+        found_cb_match_result: list[CBMatchResult] = []
+        model_name, world_size = key.model_name, key.world_size
+
+        # Find the cb gpu context and calculate the layout desc
+        layout_desc: MemoryLayoutDesc | None = None
+        for gpu_id, (m_name, w_size) in self._cb_gpu_context_meta.items():
+            if m_name == model_name and w_size == world_size:
+                cb_ctx = self._cb_gpu_contexts[gpu_id]
+                layout_desc = MemoryLayoutDesc(
+                    shapes=[cb_ctx.get_kv_buffer_shape(self._ctx.chunk_size)],
+                    dtypes=[cb_ctx.dtype],
+                )
+                break
+
+        if layout_desc is None:
+            logger.error(
+                "No CB GPU context found for model %s with world size %d "
+                "during cb_lookup_pre_computed!",
+                model_name,
+                world_size,
+            )
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id=key.request_id,
+                    metadata={
+                        "num_tokens": num_tokens,
+                        "fingerprint_hits": 0,
+                        "prefix_hits": 0,
+                        "storage_hits": 0,
+                        "stale_chunks": 0,
+                        "no_gpu_context": True,
+                        "hit_tokens": 0,
+                        "requested_tokens": (num_tokens // self._ctx.chunk_size)
+                        * self._ctx.chunk_size,
+                    },
+                )
+            )
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.CB_REQUEST_END,
+                    session_id=key.request_id,
+                )
+            )
+            return []
+
+        # Submit prefetch for each group.  All candidates use the standard chunk
+        # hash computed by token_hasher, which matches the hash used at store
+        # time, so ipc_key_to_object_keys resolves correctly.
+        for group in groups:
+            chunk_hashes = [r.hash for r in group]
+            obj_keys = ipc_key_to_object_keys(key, chunk_hashes, [0])[0]
+            handle = self._ctx.storage_manager.submit_prefetch_task(
+                obj_keys,
+                layout_desc,
+                external_request_id=key.request_id,
+            )
+            prefetch_handles.append(handle)
+
+            logger.debug(
+                "Submitted prefetch for %d chunks starting at %d",
+                len(group),
+                group[0].cur_st,
+            )
+
+        # Collect only the CBMatchResults for chunks actually found in storage
+        stale_hashes: list[bytes] = []
+        for handle, group in zip(prefetch_handles, groups, strict=False):
+            found = None
+            while True:
+                found = self._ctx.storage_manager.query_prefetch_status(handle)
+                if found is not None:
+                    break
+                time.sleep(0.001)
+
+            # Real found count after dedup the TP
+            found_count = found.count_leading_ones() // world_size
+
+            start = group[0].cur_st
+            end = group[-1].cur_ed
+            if found_count > 0:
+                found_cb_match_result.extend(group[:found_count])
+                # Chunks after found_count in the group are stale
+                stale_hashes.extend(r.hash for r in group[found_count:])
+                logger.debug(
+                    "Found %d pre-computed chunks for range (%d, %d)",
+                    found_count,
+                    start,
+                    end,
+                )
+            else:
+                stale_hashes.extend(r.hash for r in group)
+                logger.debug(
+                    "No pre-computed chunks found for range (%d, %d)",
+                    start,
+                    end,
+                )
+
+        # Evict stale fingerprint entries; remove_chunks safely skips hashes that
+        # were never registered (e.g. prefix-probe candidates not in storage).
+        if stale_hashes:
+            self._token_range_matcher.remove_chunks(stale_hashes)
+            logger.debug(
+                "Evicted %d stale chunks from fingerprint table",
+                len(stale_hashes),
+            )
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.CB_CHUNKS_EVICTED,
+                    metadata={"num_chunks": len(stale_hashes)},
+                )
+            )
+
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=key.request_id,
+                metadata={
+                    "num_tokens": num_tokens,
+                    "fingerprint_hits": len(found_cb_match_result),
+                    "prefix_hits": 0,
+                    "storage_hits": len(found_cb_match_result),
+                    "stale_chunks": len(stale_hashes),
+                    "no_gpu_context": False,
+                    "hit_tokens": _unique_token_coverage(found_cb_match_result),
+                    "requested_tokens": (num_tokens // self._ctx.chunk_size)
+                    * self._ctx.chunk_size,
+                },
+            )
+        )
+        return found_cb_match_result
+
+    def _cb_store_gpu_copy(
+        self,
+        obj_keys: list[ObjectKey],
+        gpu_context: PlainGPUCacheContext,
+        offset: int,
+        event_ipc_handle: bytes,
+        start_event: Event | None = None,
+    ) -> tuple[Any, dict]:
+        """Helper function to perform GPU-to-CPU copy operations for storing chunks.
+
+        Args:
+            obj_keys: List of object keys to store.
+            gpu_context: GPU context for the blend engine instance.
+            offset: The starting offset in the CB KV cache buffer.
+            event_ipc_handle: The IPC handle for the GPU event that signals the
+                completion of LLM inference.
+            start_event: Optional event to publish on the stream after waiting for
+                the vLLM GPU event, marking the true start of the store operation.
+
+        Returns:
+            A tuple of (event, reserved_dict) where event is the GPU event and
+            reserved_dict is the dictionary of reserved memory objects.
+        """
+        with (
+            torch_dev.device(gpu_context.device),
+            torch_dev.stream(gpu_context.stream),
+        ):
+            # Not all backends support interprocess Events (CUDA IPC specific)
+            check_interprocess_event_support()
+            event = torch_dev.Event(interprocess=True)
+
+            # Wait for vLLM event to finish
+            # Not all backends support IPC event handles (CUDA IPC specific)
+            if not hasattr(torch_dev.Event, "from_ipc_handle"):
+                raise RuntimeError(
+                    f"Backend '{torch_device_type}' does not support IPC event "
+                    "handles (Event.from_ipc_handle not available). "
+                    "Multiprocess IPC requires CUDA."
+                )
+            vllm_event = torch_dev.Event.from_ipc_handle(
+                gpu_context.device, event_ipc_handle
+            )
+            vllm_event.wait(stream=gpu_context.stream)
+
+            if start_event is not None:
+                self._ctx.event_bus.publish_on_stream(
+                    gpu_context.cupy_stream, start_event
+                )
+
+            # Prepare for the copy
+            num_tokens = self._ctx.chunk_size
+            cpu_shape = gpu_context.get_kv_buffer_shape(num_tokens)
+            layout_desc = MemoryLayoutDesc(
+                shapes=[cpu_shape], dtypes=[gpu_context.dtype]
+            )
+
+            reserved_dict = self._ctx.storage_manager.reserve_write(
+                obj_keys, layout_desc, "new"
+            )
+
+            for idx, obj_key in enumerate(obj_keys):
+                if obj_key in reserved_dict:
+                    memory_obj = reserved_dict[obj_key]
+                else:
+                    continue
+
+                offset_start = idx * self._ctx.chunk_size + offset
+                offset_end = offset_start + self._ctx.chunk_size
+
+                # Copy from GPU to CPU
+                tmp_buffer = gpu_context.get_tmp_gpu_buffer(offset_end - offset_start)
+                gpu_kv_slice = gpu_context.slice_kv_cache_on_tokens(
+                    offset_start, offset_end
+                )
+                with self._gpu_copy_lock:
+                    tmp_buffer.copy_(gpu_kv_slice, non_blocking=True)
+                    lmcache_memcpy_async_d2h(tmp_buffer, memory_obj)
+
+            event.record()
+        # Call finish_write after the copy is done
+        gpu_context.cupy_stream.launch_host_func(
+            self._ctx.storage_manager.finish_write,
+            list(reserved_dict.keys()),
+        )
+
+        return event, reserved_dict
+
+    def cb_store_pre_computed(
+        self,
+        key: IPCCacheServerKey,
+        offset: int,
+        instance_id: int,
+        event_ipc_handle: bytes,
+    ) -> tuple[bytes, bool]:
+        """Store the pre-computed chunks in the underlying storage for later retrieval.
+
+        Args:
+            key: IPCCacheServerKey containing the token ids for which the
+                pre-computed chunks are stored.
+            offset: The starting offset in the CB KV cache buffer where the
+                pre-computed chunks begin.
+            instance_id: The instance_id of the blend engine instance to store
+                the pre-computed chunks for.
+            event_ipc_handle: The IPC handle for the CUDA event that signals the
+                completion of LLM inference.
+
+        Returns:
+            IPC handle bytes for the event that signals the completion of storing
+            the pre-computed chunks, and a boolean flag indicating if the store
+            is successful.
+
+        Raises:
+            ValueError: If instance_id is not registered for CB KV cache.
+
+        Note:
+            The input tokens should not have any separator in it. It should just
+            be one "paragraph".
+            This function will discard the last partial chunk and only store the
+            full chunks.
+        """
+        num_tokens = key.end - key.start
+
+        if instance_id not in self._cb_gpu_contexts:
+            raise ValueError(
+                f"Instance ID {instance_id} not registered for CB KV cache"
+            )
+        gpu_context = self._cb_gpu_contexts[instance_id]
+
+        # CPU-synchronous sentinel: GPU store is about to be enqueued.
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_SUBMITTED,
+                session_id=key.request_id,
+                metadata={"instance_id": instance_id},
+            )
+        )
+        self._ctx.event_bus.publish_on_stream(
+            gpu_context.cupy_stream,
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id=key.request_id,
+                metadata={"instance_id": instance_id, "num_tokens": num_tokens},
+            ),
+        )
+
+        # Compute normal prefix hashes so these chunks are accessible both via
+        # the CB lookup path and via the standard lookup/retrieve path.
+        chunk_hashes = self._ctx.token_hasher.compute_chunk_hashes(list(key.token_ids))
+        # convert to object key
+        obj_keys = ipc_key_to_object_keys(key, chunk_hashes, [0])[0]
+
+        reserved_dict: dict = {}
+        try:
+            event, reserved_dict = self._cb_store_gpu_copy(
+                obj_keys, gpu_context, offset, event_ipc_handle
+            )
+
+            # Register chunk hashes with the local matcher for fast sub-sequence lookup
+            token_hashes = list(chunk_hashes)
+
+            # NOTE(Jiayi): We only register the token hashes for worker_id 0 or None
+            # to avoid duplicate registration across workers.
+            if key.worker_id in [0, None]:
+                self._token_range_matcher.on_new_token_hashes(
+                    list(key.token_ids), token_hashes
+                )
+                self._ctx.event_bus.publish(
+                    Event(
+                        event_type=EventType.CB_FINGERPRINTS_REGISTERED,
+                        session_id=key.request_id,
+                        metadata={
+                            "num_chunks": len(token_hashes),
+                            "num_tokens": len(list(key.token_ids)),
+                        },
+                    )
+                )
+
+            logger.info(
+                "Stored pre-computed doc with %d tokens, num stored chunks: %d",
+                key.end - key.start,
+                len(reserved_dict),
+            )
+        except Exception:
+            logger.exception("Cannot store pre-computed chunks due to exception")
+            self._ctx.event_bus.publish_on_stream(
+                gpu_context.cupy_stream,
+                Event(
+                    event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                    session_id=key.request_id,
+                    metadata={
+                        "instance_id": instance_id,
+                        "num_tokens": num_tokens,
+                        "stored_chunks": 0,
+                        "success": False,
+                    },
+                ),
+            )
+            raise
+
+        self._ctx.event_bus.publish_on_stream(
+            gpu_context.cupy_stream,
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id=key.request_id,
+                metadata={
+                    "instance_id": instance_id,
+                    "num_tokens": num_tokens,
+                    "stored_chunks": len(reserved_dict),
+                    "success": True,
+                },
+            ),
+        )
+        return event.ipc_handle(), True
+
+    def cb_retrieve_pre_computed(
+        self,
+        key: IPCCacheServerKey,
+        cb_match_result: list[CBMatchResult],
+        offset: int,
+        instance_id: int,
+        event_ipc_handle: bytes,
+    ) -> tuple[bytes, bool]:
+        """Retrieve pre-computed chunks from storage and copy them to the CB KV buffer.
+
+        Args:
+            key: IPCCacheServerKey containing the token ids for which the
+                pre-computed chunks are retrieved.
+            cb_match_result: List of CBMatchResult returned by
+                cb_lookup_pre_computed, containing the per-chunk hashes and
+                query positions.
+            offset: The starting offset in the CB KV cache buffer to copy the
+                retrieved chunks to.
+            instance_id: The instance_id of the blend engine instance to
+                retrieve the pre-computed chunks for.
+            event_ipc_handle: The IPC handle for the CUDA event that signals
+                the completion of LLM inference.
+
+        Returns:
+            IPC handle bytes for the event that signals the completion of
+            retrieving the pre-computed chunks, and a boolean flag indicating
+            if the retrieval is successful.
+
+        Raises:
+            ValueError: If instance_id is not registered for CB KV cache.
+
+        Note:
+            cb_lookup_pre_computed must be called first before calling this
+            function.
+        """
+        if instance_id not in self._cb_gpu_contexts:
+            raise ValueError(
+                f"Instance ID {instance_id} not registered for CB KV cache"
+            )
+        gpu_context = self._cb_gpu_contexts[instance_id]
+
+        # One obj_key per match_result, in cur_st order
+        cb_match_result = sorted(cb_match_result, key=lambda r: r.cur_st)
+        num_chunks = len(cb_match_result)
+        chunk_hashes = [r.hash for r in cb_match_result]
+        all_obj_keys = ipc_key_to_object_keys(key, chunk_hashes, [0])[0]
+
+        # CPU-synchronous sentinel: GPU retrieve is about to be enqueued.
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_SUBMITTED,
+                session_id=key.request_id,
+                metadata={"instance_id": instance_id},
+            )
+        )
+
+        logger.debug("DEBUG object keys to retrieve: %s", all_obj_keys)
+
+        with (
+            torch_dev.device(gpu_context.device),
+            torch_dev.stream(gpu_context.stream),
+        ):
+            # Not all backends support interprocess Events (CUDA IPC specific)
+            check_interprocess_event_support()
+            event = torch_dev.Event(interprocess=True)
+
+            self._ctx.event_bus.publish_on_stream(
+                gpu_context.cupy_stream,
+                Event(
+                    event_type=EventType.CB_RETRIEVE_START,
+                    session_id=key.request_id,
+                    metadata={
+                        "instance_id": instance_id,
+                        "num_chunks": num_chunks,
+                    },
+                ),
+            )
+
+            try:
+                with self._ctx.storage_manager.read_prefetched_results(
+                    all_obj_keys
+                ) as memory_objs:
+                    if memory_objs is None:
+                        logger.error("Some keys not found during CB retrieve!")
+                        self._ctx.event_bus.publish_on_stream(
+                            gpu_context.cupy_stream,
+                            Event(
+                                event_type=EventType.CB_RETRIEVE_END,
+                                session_id=key.request_id,
+                                metadata={
+                                    "instance_id": instance_id,
+                                    "num_chunks": num_chunks,
+                                    "success": False,
+                                },
+                            ),
+                        )
+                        return event.ipc_handle(), False
+
+                    for r, memory_obj in zip(
+                        cb_match_result, memory_objs, strict=False
+                    ):
+                        gpu_st = r.cur_st + offset
+                        gpu_ed = gpu_st + self._ctx.chunk_size
+                        tmp_buffer = gpu_context.get_tmp_gpu_buffer(
+                            self._ctx.chunk_size
+                        )
+                        target_buffer = gpu_context.slice_kv_cache_on_tokens(
+                            gpu_st, gpu_ed
+                        )
+                        with self._gpu_copy_lock:
+                            lmcache_memcpy_async_h2d(memory_obj, tmp_buffer)
+                            target_buffer.copy_(tmp_buffer, non_blocking=True)
+
+            except Exception:
+                logger.exception("Error during retrieving prefetched results")
+                self._ctx.event_bus.publish_on_stream(
+                    gpu_context.cupy_stream,
+                    Event(
+                        event_type=EventType.CB_RETRIEVE_END,
+                        session_id=key.request_id,
+                        metadata={
+                            "instance_id": instance_id,
+                            "num_chunks": num_chunks,
+                            "success": False,
+                        },
+                    ),
+                )
+                return event.ipc_handle(), False
+
+            finally:
+                event.record()
+                # TODO: here we simply "unlock" all the keys, which may cause
+                # double-unlock if error happens during read_prefetched_results.
+                # We should consider not unlocking objects in read_prefetched_results
+                # if error happens.
+                gpu_context.cupy_stream.launch_host_func(
+                    self._ctx.storage_manager.finish_read_prefetched,
+                    all_obj_keys,
+                )
+
+        logger.info(
+            "Retrieved pre-computed for %d match results to GPU offset starting at %d",
+            len(cb_match_result),
+            offset,
+        )
+        self._ctx.event_bus.publish_on_stream(
+            gpu_context.cupy_stream,
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id=key.request_id,
+                metadata={
+                    "instance_id": instance_id,
+                    "num_chunks": num_chunks,
+                    "success": True,
+                },
+            ),
+        )
+        return event.ipc_handle(), True
+
+    def cb_store_final(
+        self,
+        key: IPCCacheServerKey,
+        offset: int,
+        instance_id: int,
+        event_ipc_handle: bytes,
+    ) -> tuple[bytes, bool]:
+        """Store the final chunks in the underlying storage after processing.
+
+        The stored chunks should be accessible for normal mode LLMs.
+
+        Args:
+            key: IPCCacheServerKey containing the token ids for which the
+                final chunks are stored.
+            offset: The starting offset in the CB KV cache buffer where the
+                final chunks are stored.
+            instance_id: The instance_id of the blend engine instance to
+                store the final chunks for.
+            event_ipc_handle: The IPC handle for the CUDA event that signals
+                the completion of LLM inference.
+
+        Returns:
+            IPC handle bytes for the event that signals the completion of
+            storing the final chunks, and a boolean flag indicating if the
+            store is successful.
+
+        Raises:
+            ValueError: If instance_id is not registered for CB KV cache.
+        """
+        num_tokens = key.end - key.start
+
+        # Get GPU context
+        if instance_id not in self._cb_gpu_contexts:
+            raise ValueError(
+                f"Instance ID {instance_id} not registered for CB KV cache"
+            )
+        gpu_context = self._cb_gpu_contexts[instance_id]
+
+        # CPU-synchronous sentinels: SUBMITTED before SESSION_END so the
+        # tracing subscriber's in-flight counter is non-zero when SESSION_END
+        # arrives and correctly defers root span closure.
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_SUBMITTED,
+                session_id=key.request_id,
+                metadata={"instance_id": instance_id},
+            )
+        )
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=key.request_id,
+            )
+        )
+
+        # Compute normal hash for the keys
+        chunk_hashes = self._ctx.token_hasher.compute_chunk_hashes(list(key.token_ids))
+
+        # convert to object key
+        obj_keys = ipc_key_to_object_keys(key, chunk_hashes, [0])[0]
+
+        reserved_dict: dict = {}
+        try:
+            event, reserved_dict = self._cb_store_gpu_copy(
+                obj_keys,
+                gpu_context,
+                offset,
+                event_ipc_handle,
+                start_event=Event(
+                    event_type=EventType.CB_STORE_FINAL_START,
+                    session_id=key.request_id,
+                    metadata={
+                        "instance_id": instance_id,
+                        "num_tokens": num_tokens,
+                    },
+                ),
+            )
+
+            # Register fingerprints so future CB lookups can find these chunks.
+            # Mirrors cb_store_pre_computed; without this, chunks stored here are
+            # invisible to cb_lookup_pre_computed, causing 0% hit rate on re-requests.
+            if key.worker_id in [0, None]:
+                self._token_range_matcher.on_new_token_hashes(
+                    list(key.token_ids), list(chunk_hashes)
+                )
+                self._ctx.event_bus.publish(
+                    Event(
+                        event_type=EventType.CB_FINGERPRINTS_REGISTERED,
+                        session_id=key.request_id,
+                        metadata={
+                            "num_chunks": len(chunk_hashes),
+                            "num_tokens": len(list(key.token_ids)),
+                        },
+                    )
+                )
+
+            logger.info(
+                "Stored final doc with %d tokens, num stored chunks: %d",
+                key.end - key.start,
+                len(reserved_dict),
+            )
+        except Exception:
+            logger.exception("Cannot store final chunks due to exception")
+            self._ctx.event_bus.publish_on_stream(
+                gpu_context.cupy_stream,
+                Event(
+                    event_type=EventType.CB_STORE_FINAL_END,
+                    session_id=key.request_id,
+                    metadata={
+                        "instance_id": instance_id,
+                        "num_tokens": num_tokens,
+                        "stored_chunks": 0,
+                        "success": False,
+                    },
+                ),
+            )
+            raise
+
+        self._ctx.event_bus.publish_on_stream(
+            gpu_context.cupy_stream,
+            Event(
+                event_type=EventType.CB_STORE_FINAL_END,
+                session_id=key.request_id,
+                metadata={
+                    "instance_id": instance_id,
+                    "num_tokens": num_tokens,
+                    "stored_chunks": len(reserved_dict),
+                    "success": True,
+                },
+            ),
+        )
+        return event.ipc_handle(), True
diff --git a/lmcache/v1/multiprocess/modules/blend_v3.py b/lmcache/v1/multiprocess/modules/blend_v3.py
new file mode 100644
index 0000000..559783a
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/blend_v3.py
@@ -0,0 +1,1868 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Blend V3: paged-aware CacheBlend as an EngineModule.
+
+Plugs into the unified MPCacheServer; standard REGISTER_KV_CACHE +
+CB_REGISTER_ROPE_V3 for setup; STORE wrapper registers fingerprints;
+retrieve scatters into the request's paged blocks.
+"""
+
+# Standard
+from dataclasses import dataclass
+from queue import Empty as QueueEmpty
+from queue import Queue
+from typing import TYPE_CHECKING, Any
+import threading
+import time
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.mp_coordinator.blend_client import (
+        BlendCoordinatorClient,
+        RemoteMatch,
+    )
+
+# Third Party
+import numpy as np
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.utils import check_interprocess_event_support
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    TrimPolicy,
+    ipc_key_to_object_keys,
+)
+from lmcache.v1.distributed.storage_manager import PrefetchHandle
+from lmcache.v1.gpu_connector.gpu_ops import lmcache_memcpy_async_h2d
+from lmcache.v1.mp_coordinator.blend_client import PENDING
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.multiprocess.custom_types import (
+    CBMatchResult,
+    CBUnifiedLookupResult,
+    DeviceIPCWrapper,
+    IPCCacheServerKey,
+)
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    InstanceLivenessTarget,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.modules.lmcache_driven_transfer import (
+    LMCacheDrivenTransferModule,
+)
+from lmcache.v1.multiprocess.modules.lookup import compute_extra_count
+from lmcache.v1.multiprocess.protocol import RequestType
+from lmcache.v1.multiprocess.token_hasher import (
+    TokenHasher,
+    chunk_hash_windows_numba,
+    rolling_hash_windows_numba,
+    update_table_id_numba,
+)
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class _CBRopeState:
+    """Per-instance RoPE state IPC-shared from vLLM; dangles on reallocate.
+
+    Models with per-layer-type RoPE (distinct local/global theta)
+    register one cache per distinct rope and a per-layer index into
+    ``cos_sin_caches``.
+    """
+
+    head_size: int
+    is_neox_style: bool  # NeoX = contiguous halves; else GPT-J.
+    cos_sin_caches: list[torch.Tensor]
+    group_to_cache: list[int]  # engine group idx -> cache idx; empty = cache 0
+
+    def cache_for_group(self, engine_group_idx: int) -> torch.Tensor:
+        """The cos/sin cache for one engine group.
+
+        Engine groups partition layers by attention type, and rope follows
+        attention type (sliding=local theta, full=global theta),
+        so each engine group has exactly one cache.
+
+        Args:
+            engine_group_idx: The kernel group's engine group index.
+
+        Returns:
+            The group's cos/sin cache tensor.
+
+        Raises:
+            RuntimeError: If ``engine_group_idx`` is outside the map.
+        """
+        if not self.group_to_cache:
+            return self.cos_sin_caches[0]
+        if engine_group_idx >= len(self.group_to_cache):
+            raise RuntimeError(
+                f"CB re-RoPE: engine group {engine_group_idx} has no rope "
+                f"cache mapping (map covers {len(self.group_to_cache)} groups)."
+            )
+        return self.cos_sin_caches[self.group_to_cache[engine_group_idx]]
+
+
+@dataclass
+class _CBUnifiedJob:
+    """Per-request poll state for non-blocking cb_unified_lookup.
+
+    Stashed across polls because the underlying status/found polls are
+    consume-once.
+    """
+
+    matches: list[CBMatchResult]
+    num_tokens: int = 0
+    # Prefix leg (blend_v3-owned submit/poll). ``prefix_handle`` is None when
+    # there is no GPU context / no full chunk (poll reports 0 coverage).
+    prefix_handle: PrefetchHandle | None = None
+    prefix_world_size: int = 1
+    prefix_chunks: int | None = None  # stashed when the prefix poll completes
+    retained_chunks: list[int] | None = None  # SEGMENTED_PREFIX: full gapped set
+    sparse_started: bool = False  # prefix done -> sparse leg submitted/skipped
+    handle: PrefetchHandle | None = None  # sparse handle, None if no sparse leg
+    non_prefix: list[CBMatchResult] | None = None
+    per_hash_obj_keys: dict | None = None
+    expanded_uidx: list[int] | None = None
+    found_uidx: set[int] | None = None  # stashed when the sparse poll completes
+    l2_keys: int = 0  # sparse keys needing an L2 load (0 => no L2 read, span skipped)
+    coord_submitted: bool = False  # coordinator match query was issued
+    coord_deadline: float = 0.0  # time.monotonic() wall-clock cutoff for the leg
+
+
+class BlendTokenRangeMatcherV3:
+    """V3 matcher: token-level probe (any offset) + full-hash collision
+    rejection. Self-contained (does not inherit a base matcher)."""
+
+    _TABLE_BITS: int = 20  # 2^20 ~ 1 M entries
+    _TABLE_SIZE: int = 1 << _TABLE_BITS
+    _BASE: np.uint64 = np.uint64(0x9E3779B97F4A7C15)  # Fibonacci-hashing const
+
+    def __init__(self, chunk_size: int = 256):
+        """Initialize the V3 matcher.
+
+        Args:
+            chunk_size (int): Tokens per non-overlapping fingerprint chunk.
+        """
+        self.chunk_size = chunk_size
+        # poly_chunk_hash -> compact_chunk_id; -1 = empty
+        self._table_id = np.full(self._TABLE_SIZE, -1, dtype=np.int64)
+        self._mask = np.uint64(self._TABLE_SIZE - 1)
+        # compact_chunk_id -> caller token_hash (full bytes); None once evicted
+        self._chunk_token_hash: list[bytes | None] = []
+        # token_hash -> start position in its registered sequence
+        self._token_hash_to_start: dict[bytes, int] = {}
+        # compact_chunk_id -> table slot (reverse lookup for eviction)
+        self._compact_id_to_slot = np.full(self._TABLE_SIZE, -1, dtype=np.int64)
+        # token_hash -> compact_chunk_id (for eviction lookup)
+        self._token_hash_to_compact_id: dict[bytes, int] = {}
+        self._lock = threading.Lock()
+        # V3 addition: compact_chunk_id -> full poly hash, for collision reject.
+        self._chunk_poly_hash: list[int] = []
+
+    def on_new_token_hashes(
+        self,
+        token_ids: list[int],
+        token_hashes: list[bytes],
+        start_chunk_idx: int = 0,
+        position_offset: int = 0,
+    ) -> None:
+        """Index a stored sequence's non-overlapping chunks into the matcher.
+
+        Records each new chunk's poly hash + start position so a later
+        match_sub_sequence can find it. Thread-safe (holds the matcher lock).
+
+        Args:
+            token_ids (list[int]): The stored sequence's token IDs.
+            token_hashes (list[bytes]): Per-chunk content hashes (one per
+                chunk), used as the dedup/eviction key.
+            start_chunk_idx (int): First chunk to index; 1 skips chunk 0 (the
+                prefix lookup leg owns it).
+            position_offset (int): Added to each recorded start position (for
+                indexing a tail-slice of a larger sequence).
+
+        Returns:
+            None.
+        """
+        arr = np.array(token_ids, dtype=np.uint64)
+        chunk_hashes = chunk_hash_windows_numba(arr, self.chunk_size, self._BASE)
+        n = int(chunk_hashes.shape[0])
+        if n == 0 or start_chunk_idx >= n:
+            return
+
+        with self._lock:
+            new_idxs = [
+                i
+                for i in range(start_chunk_idx, n)
+                if token_hashes[i] not in self._token_hash_to_compact_id
+            ]
+            if not new_idxs:
+                return
+            n_new = len(new_idxs)
+            new_chunk_hashes = chunk_hashes[new_idxs]
+
+            base_id = len(self._chunk_token_hash)
+            if base_id + n_new > self._TABLE_SIZE:
+                logger.error(
+                    "BlendTokenRangeMatcherV3 compact-ID overflow: %d chunks "
+                    "registered, cannot add %d more (limit %d). Skipping.",
+                    base_id,
+                    n_new,
+                    self._TABLE_SIZE,
+                )
+                return
+            if base_id + n_new > int(self._TABLE_SIZE * 0.8):
+                logger.warning(
+                    "BlendTokenRangeMatcherV3 nearing capacity: %d/%d "
+                    "compact IDs used. Hash collision rate is rising; "
+                    "hit rate will degrade.",
+                    base_id + n_new,
+                    self._TABLE_SIZE,
+                )
+            compact_ids = np.arange(base_id, base_id + n_new, dtype=np.int64)
+
+            update_table_id_numba(new_chunk_hashes, self._table_id, compact_ids)
+
+            for k, orig_i in enumerate(new_idxs):
+                th = token_hashes[orig_i]
+                cid = int(compact_ids[k])
+                poly_hash = int(new_chunk_hashes[k])
+                slot = poly_hash & int(self._mask)
+                self._chunk_token_hash.append(th)
+                self._chunk_poly_hash.append(poly_hash)
+                self._token_hash_to_start[th] = (
+                    position_offset + orig_i * self.chunk_size
+                )
+                self._compact_id_to_slot[cid] = slot
+                self._token_hash_to_compact_id[th] = cid
+
+    def match_sub_sequence(
+        self,
+        token_ids: list[int],
+    ) -> list[CBMatchResult]:
+        """Find every registered chunk reused anywhere in a query sequence.
+
+        Vectorized direct-address probe over all token positions, then a small
+        verify loop over the surviving hits (a full poly-hash check rejects
+        bucket collisions; evicted/unknown chunks are skipped). Thread-safe.
+
+        Args:
+            token_ids (list[int]): The query sequence's token IDs.
+
+        Returns:
+            list[CBMatchResult]: One result per unique reused chunk (cur_st
+            = its first query position, old_st = its stored position).
+            Empty if the query is shorter than one chunk or nothing matched.
+        """
+        if len(token_ids) < self.chunk_size:
+            return []
+
+        arr = np.array(token_ids, dtype=np.uint64)
+        rolling = rolling_hash_windows_numba(arr, self.chunk_size, self._BASE)
+
+        with self._lock:
+            if not self._chunk_token_hash:
+                return []
+
+            # Vectorized direct-address probe over all positions. The table is
+            # sparse (TABLE_SIZE >> registered chunks), so only true matches and
+            # a few bucket collisions reach the Python verify loop below.
+            cids_at_pos = self._table_id[rolling & self._mask]
+            hit_positions = np.nonzero(cids_at_pos >= 0)[0]
+
+            seen_cids: set[int] = set()
+            results: list[CBMatchResult] = []
+            for pos in hit_positions:
+                pos = int(pos)
+                cid = int(cids_at_pos[pos])
+                if cid in seen_cids:
+                    continue
+                if int(rolling[pos]) != self._chunk_poly_hash[cid]:
+                    continue  # bucket-only collision
+                th = self._chunk_token_hash[cid]
+                if th is None:
+                    continue  # evicted
+                old_st = self._token_hash_to_start.get(th)
+                if old_st is None:
+                    continue
+                seen_cids.add(cid)
+                results.append(
+                    CBMatchResult(
+                        old_st=old_st,
+                        old_ed=old_st + self.chunk_size,
+                        cur_st=pos,
+                        cur_ed=pos + self.chunk_size,
+                        hash=th,
+                    )
+                )
+            logger.info(
+                "[match_probe] n_tok=%d table_hits=%d matches=%d",
+                len(token_ids),
+                len(hit_positions),
+                len(results),
+            )
+            return results
+
+    def remove_chunks(self, token_hashes: list[bytes]) -> None:
+        """Evict the given chunks from the matcher.
+
+        Clears each chunk's table slot + poly hash so later probes cannot match
+        it. Thread-safe.
+
+        Args:
+            token_hashes (list[bytes]): Content hashes of the chunks to evict.
+        """
+        with self._lock:
+            for th in token_hashes:
+                cid = self._token_hash_to_compact_id.get(th)
+                if cid is None:
+                    continue
+                slot = int(self._compact_id_to_slot[cid])
+                if slot < 0:
+                    logger.warning(
+                        "compact_id %d has no valid table slot; "
+                        "entry may have been evicted twice",
+                        cid,
+                    )
+                    continue
+                self._table_id[slot] = -1
+                self._compact_id_to_slot[cid] = -1
+                self._chunk_token_hash[cid] = None
+                self._chunk_poly_hash[cid] = 0
+                self._token_hash_to_start.pop(th, None)
+                del self._token_hash_to_compact_id[th]
+
+
+def _unique_token_coverage(results: list[CBMatchResult]) -> int:
+    """Total token coverage, merging overlapping ranges (sliding-window probe
+    can return overlaps; naive sum would double-count)."""
+    if not results:
+        return 0
+    intervals = sorted((r.cur_st, r.cur_ed) for r in results)
+    coverage = 0
+    cur_end = -1
+    for st, ed in intervals:
+        if st >= cur_end:
+            coverage += ed - st
+        elif ed > cur_end:
+            coverage += ed - cur_end
+        cur_end = max(cur_end, ed)
+    return coverage
+
+
+class BlendV3Module(InstanceLivenessTarget):
+    """Paged-aware V3 CacheBlend. Wraps LMCacheDrivenTransfer STORE to register
+    fingerprints; serves CB rope/lookup/retrieve RPCs; reads cross-module
+    GPU state via :class:`LMCacheDrivenTransferModule.cache_contexts`."""
+
+    def __init__(
+        self,
+        ctx: MPCacheServerContext,
+        lmcache_driven_transfer: LMCacheDrivenTransferModule,
+        coordinator: "BlendCoordinatorClient | None" = None,
+        enable_segmented_prefix: bool = False,
+    ):
+        self._ctx = ctx
+        self._transfer_module = lmcache_driven_transfer
+        # Server config (--enable-segmented-prefix): retain the gapped prefix on
+        # a mid-prefix L2 retrieve failure instead of truncating at the gap.
+        self._segmented_prefix = enable_segmented_prefix
+        # Optional bridge to the fleet-wide fingerprint directory. ``None`` =>
+        # purely local matching (publish/query paths skipped).
+        self._coordinator = coordinator
+
+        self._token_range_matcher = BlendTokenRangeMatcherV3(ctx.chunk_size)
+        self._event_bus = ctx.event_bus
+        self._cb_rope_state: dict[int, _CBRopeState] = {}
+
+        # L2 opt: cache TP-expanded obj_keys at lookup, pop at retrieve.
+        self._lookup_obj_keys_cache: dict[str, dict[bytes, list]] = {}
+        self._lookup_obj_keys_lock = threading.Lock()
+
+        # Non-blocking cb_unified_lookup poll state (submit-once, poll-on-recall)
+        # so the handler never holds a worker thread across the L2->L1 loads.
+        self._cb_jobs: dict[str, _CBUnifiedJob] = {}
+        self._cb_jobs_lock = threading.Lock()
+
+        # Async fingerprint registration: store enqueues, worker drains.
+        _FpJob = tuple[list[int], list[bytes], int, int]
+        self._fingerprint_queue: "Queue[_FpJob]" = Queue()
+        self._fingerprint_stop = threading.Event()
+        self._fingerprint_worker = threading.Thread(
+            target=self._drain_fingerprint_queue,
+            name="cb-fingerprint-worker",
+            daemon=True,
+        )
+        self._fingerprint_worker.start()
+
+        # In-flight fingerprint hashes; storage_gate keeps these from eviction.
+        self._pending_fp_hashes: set[bytes] = set()
+        self._pending_fp_lock = threading.Lock()
+
+        # Lazy eviction strikes; evict only at threshold so async re-store
+        # can refresh the bucket first.
+        self._stale_strike: dict[bytes, int] = {}
+        self._STALE_STRIKE_THRESHOLD = 2
+
+    # ------------------------------------------------------------------
+    # EngineModule protocol
+    # ------------------------------------------------------------------
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        return self._ctx
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        # STORE shadows LMCacheDrivenTransfer's; compositor registers V3 last.
+        return [
+            HandlerSpec(RequestType.STORE, self.store, ThreadPoolType.AFFINITY),
+            HandlerSpec(
+                RequestType.CB_REGISTER_ROPE_V3,
+                self.cb_register_rope,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.CB_UNREGISTER_ROPE_V3,
+                self.cb_unregister_rope,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.CB_UNIFIED_LOOKUP,
+                self.cb_unified_lookup,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.CB_RETRIEVE_PRE_COMPUTED_V3,
+                self.cb_retrieve_pre_computed,
+                ThreadPoolType.AFFINITY,
+            ),
+        ]
+
+    def report_status(self) -> dict:
+        # Meta is derived live from MP server gpu_transfe
+
+        cache_contexts = self._transfer_module.context_entries_snapshot()
+
+        def _meta(iid: int) -> "tuple[str, int] | None":
+            entry = cache_contexts.get(iid)
+            return (entry.model_name, entry.world_size) if entry is not None else None
+
+        return {
+            "registered_cb_rope_instances": list(self._cb_rope_state.keys()),
+            "cb_rope_meta": {str(iid): _meta(iid) for iid in self._cb_rope_state},
+            "active_cb_lookups": len(self._cb_jobs),
+        }
+
+    def close(self) -> None:
+        self._fingerprint_stop.set()
+        if self._coordinator is not None:
+            # Joins the client's daemon thread and closes its httpx.Client;
+            # otherwise the coordinator leg leaks both on server shutdown.
+            self._coordinator.close()
+        self._cb_rope_state.clear()
+
+    # ------------------------------------------------------------------
+    # V3 RPCs
+    # ------------------------------------------------------------------
+
+    def cb_register_rope(
+        self,
+        instance_id: int,
+        cos_sin_caches_ipc: list[DeviceIPCWrapper],
+        head_size: int,
+        is_neox_style: bool,
+        group_to_cache: list[int],
+    ) -> None:
+        """Bolt CB re-RoPE state onto an already-registered KV-cache instance.
+
+        Idempotent; ``REGISTER_KV_CACHE`` must precede this. Strips any
+        YaRN/longrope mscale baked into each rope cache so re-RoPE stays a
+        pure rotation.
+
+        Args:
+            instance_id (int): KV-cache instance to attach rope state to.
+            cos_sin_caches_ipc (list[DeviceIPCWrapper]): IPC handles to vLLM's
+                cos/sin rope cache(s) — one per distinct rope (dual-RoPE
+                models send local/global); single-rope models send one.
+            head_size (int): Rotary head dimension.
+            is_neox_style (bool): True for NeoX (contiguous halves), else GPT-J.
+            group_to_cache (list[int]): Per-engine-group index into the
+                caches list; empty means every group uses cache 0.
+
+        Raises:
+            ValueError: If ``instance_id`` has no registered KV cache, the
+                cache list is empty, or ``group_to_cache`` references a
+                missing cache or does not cover every engine group of the
+                registered model.
+        """
+        entry = self._transfer_module.get_and_touch_context_entry(instance_id)
+        if entry is None:
+            raise ValueError(
+                f"Instance {instance_id} has no paged KV cache registered; "
+                "send REGISTER_KV_CACHE before CB_REGISTER_ROPE_V3."
+            )
+        if not cos_sin_caches_ipc:
+            raise ValueError("CB_REGISTER_ROPE_V3 requires >=1 cos/sin cache.")
+        if group_to_cache:
+            if min(group_to_cache) < 0 or max(group_to_cache) >= len(
+                cos_sin_caches_ipc
+            ):
+                raise ValueError(
+                    f"group_to_cache {group_to_cache} contains indices outside "
+                    f"[0, {len(cos_sin_caches_ipc)}) for the sent cache(s)."
+                )
+            # Fail at registration, not mid-retrieve: every engine group of
+            # the registered model must have a cache mapping.
+            max_eg_idx = max(
+                (
+                    g.engine_group_idx
+                    for g in entry.cache_context.kv_layer_groups_manager.kernel_groups
+                ),
+                default=-1,
+            )
+            if len(group_to_cache) <= max_eg_idx:
+                raise ValueError(
+                    f"group_to_cache covers {len(group_to_cache)} engine "
+                    f"group(s) but the registered model has engine groups up "
+                    f"to index {max_eg_idx}."
+                )
+
+        cos_sin_caches: list[torch.Tensor] = []
+        for cache_idx, cache_ipc in enumerate(cos_sin_caches_ipc):
+            cos_sin_cache = cache_ipc.to_tensor()
+            # YaRN/longrope bake an mscale m into the rope cache
+            # (cos²+sin²=m²≠1). vLLM already folds m into stored K, but CB
+            # re-RoPE assumes a pure rotation, so an un-normalized m injects
+            # an m² error per K element.
+            _c32 = cos_sin_cache.to(torch.float32)
+            _half = _c32.shape[1] // 2
+            _m = float((_c32[:, :_half] ** 2 + _c32[:, _half:] ** 2).mean().sqrt())
+            if abs(_m - 1.0) >= 1e-3:
+                logger.info(
+                    "CB re-RoPE: cache %d: stripping rope-cache mscale=%.4f "
+                    "(m²=%.4f → K inflation if uncorrected) → unit magnitude",
+                    cache_idx,
+                    _m,
+                    _m * _m,
+                )
+                cos_sin_cache = (_c32 / _m).to(cos_sin_cache.dtype)
+            cos_sin_caches.append(cos_sin_cache)
+
+        self._cb_rope_state[instance_id] = _CBRopeState(
+            head_size=head_size,
+            is_neox_style=is_neox_style,
+            cos_sin_caches=cos_sin_caches,
+            group_to_cache=list(group_to_cache),
+        )
+
+        logger.info(
+            "Registered CB rope state for instance %d "
+            "(%d cache(s), shapes=%s dtype=%s, head_size=%d, is_neox=%s, "
+            "group_map=%s)",
+            instance_id,
+            len(cos_sin_caches),
+            [tuple(c.shape) for c in cos_sin_caches],
+            cos_sin_caches[0].dtype,
+            head_size,
+            is_neox_style,
+            "uniform" if not group_to_cache else str(group_to_cache),
+        )
+
+    def cb_unregister_rope(self, instance_id: int) -> None:
+        """Drop the instance's CB rope state; the paged KV cache is left intact.
+
+        Args:
+            instance_id (int): Instance whose rope state to remove (use
+                ``UNREGISTER_KV_CACHE`` to free the KV cache itself).
+        """
+        self._cb_rope_state.pop(instance_id, None)
+        if self._transfer_module.get_and_touch_context_entry(instance_id) is None:
+            logger.warning(
+                "cb_unregister_rope: instance %d not registered", instance_id
+            )
+            return
+        logger.info("Unregistered CB rope state for instance %d", instance_id)
+
+    def drop_instance_state(self, instance_id: int) -> None:
+        """Drop blend state for a reaped instance (InstanceLivenessTarget hook).
+
+        Only the CB rope state is held per instance; the GPU cache context is
+        owned by ``LMCacheDrivenTransferModule`` (no mirror here), so reaping
+        the GPU entry frees it directly. A no-op if no rope state is held.
+
+        Args:
+            instance_id: The reaped worker's instance ID.
+        """
+        if self._cb_rope_state.pop(instance_id, None) is not None:
+            logger.info("Dropped CB rope state for reaped instance %d", instance_id)
+
+    # ------------------------------------------------------------------
+    # Unified lookup (CB_UNIFIED_LOOKUP) + shared helpers
+    # ------------------------------------------------------------------
+
+    def _drain_fingerprints_sync(self) -> None:
+        """Sync-drain pending fingerprint registrations (the async drainer
+        races at low max_tokens)."""
+        while True:
+            try:
+                job = self._fingerprint_queue.get_nowait()
+            except QueueEmpty:
+                break
+            tokens_in_range, chunk_hashes, start_chunk_idx, position_offset = job
+            try:
+                self._token_range_matcher.on_new_token_hashes(
+                    tokens_in_range,
+                    chunk_hashes,
+                    start_chunk_idx=start_chunk_idx,
+                    position_offset=position_offset,
+                )
+            except Exception:
+                logger.exception("CB fingerprint registration failed (sync drain)")
+
+    def _match_fingerprints(self, key: IPCCacheServerKey) -> list[CBMatchResult]:
+        """Drain pending registrations and fingerprint-match sub-sequences.
+
+        Returns the raw matches (any order, possibly overlapping); the caller
+        applies the prefix filter + overlap dedup once via
+        :meth:`_non_overlapping_after_prefix`.
+        """
+        self._drain_fingerprints_sync()
+        return self._token_range_matcher.match_sub_sequence(list(key.token_ids))
+
+    @staticmethod
+    def _non_overlapping_after_prefix(
+        matches: list[CBMatchResult], prefix_tokens: int
+    ) -> list[CBMatchResult]:
+        """Matches outside the prefix coverage, leftmost-greedy overlap-deduped.
+
+        Drops matches the prefix leg already covers (``cur_st < prefix_tokens``),
+        then keeps a left-to-right non-overlapping subset -- two matches over the
+        same request range can't both scatter. Filtering precedes the dedup so a
+        prefix-covered match cannot suppress a usable one in the greedy pass.
+
+        Args:
+            matches: Candidate matches in any order; ``cur_st``/``cur_ed`` are
+                request token positions.
+            prefix_tokens: Contiguous prefix coverage in tokens; matches starting
+                before it are dropped. Pass ``0`` to keep all (dedup only).
+
+        Returns:
+            Non-overlapping matches in ascending ``cur_st`` order.
+        """
+        kept: list[CBMatchResult] = []
+        covered_end = -1
+        for r in sorted(
+            (r for r in matches if r.cur_st >= prefix_tokens),
+            key=lambda r: r.cur_st,
+        ):
+            if r.cur_st >= covered_end:
+                kept.append(r)
+                covered_end = r.cur_ed
+        return kept
+
+    def _resolve_cb_layout_desc(
+        self, model_name: str, world_size: int
+    ) -> "MemoryLayoutDesc | None":
+        """Find the CB KV buffer layout for ``(model_name, world_size)``.
+
+        Reads the thread-safe ``layout_desc_registry`` (populated by
+        ``lmcache_driven_transfer`` on KV-cache registration) rather than
+        iterating ``cache_contexts``: iteration races concurrent
+        register/unregister, and the registry holds the complete multi-group
+        descriptor instead of a single-group manual reconstruction.
+
+        Args:
+            model_name (str): Model name to match.
+            world_size (int): Tensor-parallel world size to match.
+
+        Returns:
+            MemoryLayoutDesc | None: The matching layout, or None if no
+            registered CB context matches.
+        """
+        return self._ctx.layout_desc_registry.find(model_name, world_size)
+
+    def _sparse_prefetch_submit(
+        self,
+        key: IPCCacheServerKey,
+        layout_desc: "MemoryLayoutDesc",
+        matches: list[CBMatchResult],
+    ) -> "tuple[PrefetchHandle, dict[bytes, list], list[int]]":
+        """Coalesce all matches into one sparse L2->L1 prefetch and submit it.
+
+        Non-blocking. Dedups object keys before submit (sparse keeps one read
+        lock per loaded key, so a duplicate would leak). The caller polls
+        ``query_prefetch_status(handle)`` then calls :meth:`_sparse_classify`
+        with the found set.
+
+        Args:
+            key (IPCCacheServerKey): The request key.
+            layout_desc (MemoryLayoutDesc): CB KV buffer layout for L1 alloc.
+            matches (list[CBMatchResult]): Non-prefix matches to prefetch.
+
+        Returns:
+            tuple[PrefetchHandle, dict[bytes, list], list[int]]: the prefetch
+            handle, per-hash TP-expanded object keys, and each expanded
+            position's deduped-key index (maps the per-key found set back to
+            every chunk).
+        """
+        world_size = key.world_size
+        per_hash_obj_keys: dict[bytes, list] = {}
+        all_hashes = [r.hash for r in matches]
+        all_obj_keys = ipc_key_to_object_keys(key, all_hashes, [0])[0]
+        for i, h in enumerate(all_hashes):
+            per_hash_obj_keys[h] = all_obj_keys[i * world_size : (i + 1) * world_size]
+
+        # Dedup keys before submit (sparse keeps one read lock per loaded key;
+        # a duplicate would leak). Map each expanded position to its deduped
+        # index so the per-key found set resolves back to every chunk.
+        uniq_keys: list = []
+        key_to_uidx: dict = {}
+        expanded_uidx: list[int] = []
+        for k in all_obj_keys:
+            uidx = key_to_uidx.get(k)
+            if uidx is None:
+                uidx = len(uniq_keys)
+                key_to_uidx[k] = uidx
+                uniq_keys.append(k)
+            expanded_uidx.append(uidx)
+
+        handle: PrefetchHandle = self._ctx.storage_manager.submit_prefetch_task(
+            uniq_keys,
+            layout_desc,
+            external_request_id=key.request_id,
+            policy=TrimPolicy.SPARSE,
+        )
+        return handle, per_hash_obj_keys, expanded_uidx
+
+    def _sparse_classify(
+        self,
+        key: IPCCacheServerKey,
+        matches: list[CBMatchResult],
+        found_uidx: set[int],
+        per_hash_obj_keys: dict[bytes, list],
+        expanded_uidx: list[int],
+    ) -> list[CBMatchResult]:
+        """Classify each prefetched chunk as found or stale, and finalize state.
+
+        A chunk is found only if every TP rank's key loaded; stale chunks take
+        an eviction strike (evicted at threshold, kept while still in-flight).
+        Stashes the found chunks' obj_keys for the retrieve path.
+
+        Args:
+            key (IPCCacheServerKey): The request key.
+            matches (list[CBMatchResult]): The submitted non-prefix matches.
+            found_uidx (set[int]): Deduped-key indices that loaded.
+            per_hash_obj_keys (dict[bytes, list]): Per-hash TP-expanded keys.
+            expanded_uidx (list[int]): Each expanded position's deduped index.
+
+        Returns:
+            list[CBMatchResult]: The found subset, in cur_st order.
+        """
+        world_size = key.world_size
+        found_cb_match_result: list[CBMatchResult] = []
+        stale_hashes: list[bytes] = []
+        for j, r in enumerate(matches):
+            base = j * world_size
+            if all(expanded_uidx[base + t] in found_uidx for t in range(world_size)):
+                found_cb_match_result.append(r)
+            else:
+                stale_hashes.append(r.hash)
+
+        # Reset strikes for confirmed hashes.
+        if found_cb_match_result:
+            with self._pending_fp_lock:
+                for r in found_cb_match_result:
+                    self._stale_strike.pop(r.hash, None)
+        # Stale: in-flight keep; >= threshold strikes -> evict.
+        if stale_hashes:
+            with self._pending_fp_lock:
+                truly_evict: list[bytes] = []
+                for h in stale_hashes:
+                    if h in self._pending_fp_hashes:
+                        continue
+                    n = self._stale_strike.get(h, 0) + 1
+                    if n >= self._STALE_STRIKE_THRESHOLD:
+                        truly_evict.append(h)
+                        self._stale_strike.pop(h, None)
+                    else:
+                        self._stale_strike[h] = n
+            if truly_evict:
+                self._token_range_matcher.remove_chunks(truly_evict)
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.CB_CHUNKS_EVICTED,
+                    metadata={"num_chunks": len(stale_hashes)},
+                )
+            )
+
+        # Stash per-hash obj_keys for retrieve (L2 opt).
+        if found_cb_match_result:
+            cache_entry = {
+                r.hash: per_hash_obj_keys[r.hash]
+                for r in found_cb_match_result
+                if r.hash in per_hash_obj_keys
+            }
+            with self._lookup_obj_keys_lock:
+                self._lookup_obj_keys_cache[key.request_id] = cache_entry
+
+        return found_cb_match_result
+
+    def _submit_prefix_leg(
+        self,
+        key: IPCCacheServerKey,
+        tp_size: int,
+        policy: TrimPolicy,
+    ) -> "tuple[PrefetchHandle | None, int]":
+        """Submit the CB prefix prefetch (non-blocking).
+
+        Opens the ``cb.prefix_lookup`` span (CB namespace — CB requests no longer
+        feed the MP request / mp.lookup_prefetch spans or the MP hit-rate
+        aggregate; the CB hit-rate metric carries prefix tokens via
+        CB_LOOKUP_END) and writes the shared session (``set_tokens`` +
+        ``lookup_ipc_key``) so ``end_session``'s L1 keep-alive touch still
+        resolves the request's keys.
+
+        Args:
+            key (IPCCacheServerKey): Request key (token IDs, request_id, model,
+                world_size).
+            tp_size (int): Tensor-parallel size for MLA multi-reader locking.
+            policy (TrimPolicy): ``PREFIX`` or ``SEGMENTED_PREFIX``.
+
+        Returns:
+            tuple: ``(handle, world_size)``. ``handle`` is None when there is no
+            GPU context or no full chunk (the poll then reports 0 coverage).
+        """
+        rid = key.request_id
+        model_name, world_size = key.model_name, key.world_size
+        self._event_bus.publish(
+            Event(event_type=EventType.CB_PREFIX_LOOKUP_START, session_id=rid)
+        )
+
+        layout_desc = self._resolve_cb_layout_desc(model_name, world_size)
+        if layout_desc is None:
+            logger.error(
+                "No CB GPU context for model %s ws %d during prefix lookup!",
+                model_name,
+                world_size,
+            )
+            return None, world_size
+
+        chunk_hashes = self._ctx.token_hasher.compute_chunk_hashes(list(key.token_ids))
+        if not chunk_hashes:
+            return None, world_size
+
+        # Lookup-hash logger (chunk hashes, for debug); guarded so the metadata
+        # dict is built only when a subscriber is listening.
+        if self._event_bus.has_subscribers(EventType.MP_LOOKUP):
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.MP_LOOKUP,
+                    session_id=rid,
+                    metadata={
+                        "request_id": rid,
+                        "chunk_hashes": chunk_hashes,
+                        "model_name": model_name,
+                        "chunk_size": self._ctx.chunk_size,
+                        "seq_len": len(key.token_ids),
+                        "dtypes": [str(d) for d in layout_desc.dtypes],
+                        "shapes": [list(s) for s in layout_desc.shapes],
+                    },
+                )
+            )
+
+        # Shared session: end_session reads lookup_ipc_key + the rolling hashes
+        # to keep the request's KV alive in L1.
+        session = self._ctx.session_manager.get_or_create(rid)
+        session.set_tokens(list(key.token_ids))
+        session.lookup_ipc_key = key
+
+        extra_count = compute_extra_count(tp_size, world_size)
+        obj_keys = ipc_key_to_object_keys(key, chunk_hashes, [0])[0]
+        handle = self._ctx.storage_manager.submit_prefetch_task(
+            obj_keys,
+            layout_desc,
+            extra_count=extra_count,
+            external_request_id=rid,
+            policy=policy,
+        )
+        return handle, world_size
+
+    def _poll_prefix_leg(
+        self, job: "_CBUnifiedJob", rid: str, segmented: bool
+    ) -> "tuple[int, list[int] | None] | None":
+        """Poll the CB prefix handle; on completion close the cb.prefix_lookup span.
+
+        Consume-once: publishes CB_PREFIX_LOOKUP_END exactly once when the
+        prefetch lands. The prefix hit tokens are accounted on the CB hit-rate
+        metric at CB_LOOKUP_END, not here. For SEGMENTED_PREFIX also surfaces the
+        gapped retained chunk set.
+
+        Args:
+            job (_CBUnifiedJob): Poll state holding the prefix handle + world size.
+            rid (str): Request ID (event session_id).
+            segmented (bool): SEGMENTED_PREFIX active -> also surface the gapped
+                retained chunk set.
+
+        Returns:
+            tuple | None: ``(leading_chunks, retained_or_None)`` when resident;
+            ``None`` while still loading. ``retained`` is the full gapped chunk
+            set for SEGMENTED_PREFIX, else None.
+        """
+        if job.prefix_handle is not None:
+            bm = self._ctx.storage_manager.query_prefetch_status(job.prefix_handle)
+            if bm is None:
+                return None  # still loading
+            ws = job.prefix_world_size
+            # NOTE(Kuntai): assumes uniform world size and prefix-ordered keys
+            # that break at the first miss.
+            leading = bm.count_leading_ones() // ws
+            retained = (
+                sorted({ki // ws for ki in bm.get_indices_list()})
+                if segmented
+                else None
+            )
+        else:
+            # No GPU context / no full chunk: nothing loaded.
+            leading, retained = 0, ([] if segmented else None)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.CB_PREFIX_LOOKUP_END,
+                session_id=rid,
+                metadata={"prefix_chunks": leading},
+            )
+        )
+        return leading, retained
+
+    def cb_unified_lookup(
+        self, key: IPCCacheServerKey, tp_size: int
+    ) -> CBUnifiedLookupResult | None:
+        """Non-blocking single-RPC CB lookup (submit-once, poll-on-recall).
+
+        First call submits the prefix lookup + fingerprint match; later calls
+        poll both legs, returning ``None`` until the prefix and the sparse
+        non-prefix complement are both resident in L1 (so a worker thread never
+        blocks on the L2->L1 loads). The prefix job's L1 read locks persist for
+        the retrieve.
+
+        Args:
+            key (IPCCacheServerKey): Request key (token IDs, request_id, model,
+                world_size).
+            tp_size (int): Tensor-parallel size for the prefix lookup.
+
+        Returns:
+            CBUnifiedLookupResult | None: ``None`` while either leg is still
+            loading (the caller re-issues to poll); on completion, the prefix
+            coverage in tokens plus the found non-prefix segments.
+        """
+        rid = key.request_id
+        chunk_size = self._ctx.chunk_size
+
+        with self._cb_jobs_lock:
+            job = self._cb_jobs.get(rid)
+        if job is None:
+            # First invocation: start events + submit prefix + fingerprint match.
+            self._event_bus.publish(
+                Event(event_type=EventType.CB_REQUEST_START, session_id=rid)
+            )
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_START,
+                    session_id=rid,
+                    metadata={"num_tokens": len(key.token_ids)},
+                )
+            )
+            # SEGMENTED_PREFIX: request the contiguous prefix with gap-tolerant
+            # retention so a mid-prefix L2 retrieve failure leaves the post-gap
+            # chunks L1-resident (picked up by the sparse leg as L1 hits, hole
+            # recomputed) instead of truncating the prefix at the gap.
+            prefix_policy = (
+                TrimPolicy.SEGMENTED_PREFIX
+                if self._segmented_prefix
+                else TrimPolicy.PREFIX
+            )
+            # Prefix leg: blend_v3 owns the submit + the cb.prefix_lookup span
+            # (under cb.lookup); prefix hit tokens land on the CB hit-rate
+            # metric via CB_LOOKUP_END below.
+            prefix_handle, prefix_ws = self._submit_prefix_leg(
+                key, tp_size, prefix_policy
+            )
+            # Local and coordinator matching are mutually exclusive: with a
+            # coordinator the fleet directory is the only source, so skip the
+            # local matcher (and its span). The coordinator leg is async
+            # (submitted below, resolved at poll) and is timed by cb.lookup.
+            matches: list[CBMatchResult]
+            if self._coordinator is not None:
+                matches = []
+            else:
+                # Local fingerprint match: CPU-bound, tight span.
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.CB_FINGERPRINT_MATCH_START,
+                        session_id=rid,
+                    )
+                )
+                matches = self._match_fingerprints(key)
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.CB_FINGERPRINT_MATCH_END,
+                        session_id=rid,
+                        metadata={"matches": len(matches)},
+                    )
+                )
+            job = _CBUnifiedJob(
+                matches=matches,
+                num_tokens=len(key.token_ids),
+                prefix_handle=prefix_handle,
+                prefix_world_size=prefix_ws,
+            )
+            job.coord_submitted = self._submit_coordinator_match(key)
+            if job.coord_submitted and self._coordinator is not None:
+                job.coord_deadline = time.monotonic() + self._coordinator.match_budget_s
+                # Coordinator match leg: async span, ended on the resolving poll
+                # (or deadline) in _poll_coordinator_match.
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.CB_COORDINATOR_MATCH_START,
+                        session_id=rid,
+                    )
+                )
+            with self._cb_jobs_lock:
+                self._cb_jobs[rid] = job
+
+        segmented = self._segmented_prefix
+
+        # --- Prefix leg: poll (consume-once) until the L1+L2 prefix lands. ---
+        if job.prefix_chunks is None:
+            res = self._poll_prefix_leg(job, rid, segmented)
+            if res is None:
+                return None  # prefix still loading -> defer
+            job.prefix_chunks, prefix_retained = res
+            if segmented:
+                job.retained_chunks = prefix_retained
+        # Poll above set it (or we returned); narrow for the arithmetic below.
+        assert job.prefix_chunks is not None
+        prefix_chunks: int = job.prefix_chunks
+
+        # Prefix done: reconcile the complement outside the prefix coverage and
+        # submit one sparse prefetch for it (once). Prefix-covered chunks never
+        # enter the sparse prefetch, so they cannot leak a read lock.
+        if not job.sparse_started:
+            prefix_tokens = prefix_chunks * chunk_size
+            if self._coordinator is not None:
+                candidates = self._poll_coordinator_match(job, rid)
+                if candidates is None:
+                    return None  # coordinator still in flight (bounded by deadline)
+            else:
+                candidates = job.matches
+            # Under SEGMENTED_PREFIX, a same-position match the prefix leg already
+            # retained rides the segmented tail (prefix-class: pure load, no CHECK)
+            # -- drop it here so it is not scattered twice. A same-position match
+            # the tail does NOT cover is a genuine cross-context hit: keep it as
+            # non-prefix (re-RoPE no-ops at delta 0, but it still needs CHECK).
+            # Shifted (cur != old) matches are always kept. Then the single
+            # prefix-filter + overlap dedup over the rest.
+            if segmented:
+                retained = set(job.retained_chunks or [])
+                candidates = [
+                    c
+                    for c in candidates
+                    if c.old_st != c.cur_st or (c.cur_st // chunk_size) not in retained
+                ]
+            job.non_prefix = self._non_overlapping_after_prefix(
+                candidates, prefix_tokens
+            )
+            if job.non_prefix:
+                layout_desc = self._resolve_cb_layout_desc(
+                    key.model_name, key.world_size
+                )
+                if layout_desc is not None:
+                    (
+                        job.handle,
+                        job.per_hash_obj_keys,
+                        job.expanded_uidx,
+                    ) = self._sparse_prefetch_submit(key, layout_desc, job.non_prefix)
+                    # Only trace the span when the prefetch actually reads L2;
+                    # all-L1-resident matches do no L2 work worth a span.
+                    job.l2_keys = len(job.handle.l2_orig_indices)
+                    if job.l2_keys > 0:
+                        self._event_bus.publish(
+                            Event(
+                                event_type=EventType.CB_SPARSE_PREFETCH_START,
+                                session_id=rid,
+                                metadata={
+                                    "n_chunks": len(job.non_prefix),
+                                    "world_size": key.world_size,
+                                    "n_keys": len(job.non_prefix) * key.world_size,
+                                    "l2_keys": job.l2_keys,
+                                },
+                            )
+                        )
+                else:
+                    logger.error(
+                        "No CB GPU context for model %s ws %d during cb_unified_lookup",
+                        key.model_name,
+                        key.world_size,
+                    )
+                    job.non_prefix = []
+            job.sparse_started = True
+
+        # --- Sparse leg: poll (consume-once) until the scattered chunks land. ---
+        if job.handle is not None and job.found_uidx is None:
+            bm = self._ctx.storage_manager.query_prefetch_status(job.handle)
+            if bm is None:
+                return None  # sparse still loading -> defer
+            job.found_uidx = set(bm.get_indices_list())
+            if job.l2_keys > 0:
+                self._event_bus.publish(
+                    Event(
+                        event_type=EventType.CB_SPARSE_PREFETCH_END,
+                        session_id=rid,
+                        metadata={
+                            "found_keys": len(job.found_uidx),
+                            "l2_keys": job.l2_keys,
+                        },
+                    )
+                )
+
+        # --- BOTH legs ready: classify the complement + finalize. ---
+        if job.handle is not None:
+            found = self._sparse_classify(
+                key,
+                job.non_prefix or [],
+                job.found_uidx or set(),
+                job.per_hash_obj_keys or {},
+                job.expanded_uidx or [],
+            )
+        else:
+            found = []
+
+        prefix_tokens = prefix_chunks * chunk_size
+        num_tokens = job.num_tokens
+
+        # Segmented tail: post-gap chunks the SEGMENTED_PREFIX prefix leg kept
+        # resident (retained index > the leading run). Delivered at their
+        # original positions (old_st == cur_st) so the connector tags them
+        # ``prefix`` (pure load, no recompute); only the gap is recomputed. The
+        # storage key is the same prefix-chained chunk hash the prefix leg used,
+        # so no fingerprint match is needed to retrieve them.
+        segmented_tail: list[CBMatchResult] = []
+        if segmented and job.retained_chunks:
+            chunk_hashes = self._ctx.token_hasher.compute_chunk_hashes(
+                list(key.token_ids)
+            )
+            for i in job.retained_chunks:
+                if i < prefix_chunks or i >= len(chunk_hashes):
+                    continue  # leading run (already prefix) / sub-chunk tail
+                st = i * chunk_size
+                segmented_tail.append(
+                    CBMatchResult(
+                        old_st=st,
+                        old_ed=st + chunk_size,
+                        cur_st=st,
+                        cur_ed=st + chunk_size,
+                        hash=chunk_hashes[i],
+                    )
+                )
+
+        seg_tail_tokens = _unique_token_coverage(segmented_tail)
+        non_prefix_hit_tokens = _unique_token_coverage(found)
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=rid,
+                metadata={
+                    "num_tokens": num_tokens,
+                    "fingerprint_hits": len(found),
+                    "prefix_hits": job.prefix_chunks,
+                    "prefix_chunks": job.prefix_chunks,
+                    "storage_hits": len(found),
+                    "stale_chunks": len(job.non_prefix or []) - len(found),
+                    "no_gpu_context": False,
+                    "prefix_hit_tokens": prefix_tokens,
+                    "segmented_prefix_hit_tokens": seg_tail_tokens,
+                    "non_prefix_hit_tokens": non_prefix_hit_tokens,
+                    "hit_tokens": prefix_tokens
+                    + _unique_token_coverage(found + segmented_tail),
+                    "requested_tokens": (num_tokens // chunk_size) * chunk_size,
+                },
+            )
+        )
+        with self._cb_jobs_lock:
+            self._cb_jobs.pop(rid, None)
+        return CBUnifiedLookupResult(
+            prefix_coverage_tokens=prefix_tokens,
+            non_prefix_segments=found,
+            segmented_prefix_segments=segmented_tail,
+        )
+
+    def store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        gpu_block_ids: list[list[int]],
+        event_ipc_handle: bytes,
+    ) -> tuple[bytes, bool]:
+        """Paged store, then register the stored chunks as match fingerprints.
+
+        Delegates the KV write to ``LMCacheDrivenTransfer.store``, then (worker 0 only)
+        enqueues the chunk hashes for async fingerprint registration ordered
+        after the L1 commit. Chunk 0 of a position-0 store is skipped (owned by
+        the standard prefix path). Fingerprint failures are logged, never
+        raised — they do not affect store correctness.
+
+        Args:
+            key (IPCCacheServerKey): Store key (token IDs + ``[start, end)``).
+            instance_id (int): Target KV-cache instance.
+            gpu_block_ids (list[list[int]]): Per-layer-group paged block IDs.
+            event_ipc_handle (bytes): IPC handle to the producer's CUDA event.
+
+        Returns:
+            tuple[bytes, bool]: The underlying ``LMCacheDrivenTransfer.store`` result
+            (event handle, success).
+        """
+        result = self._transfer_module.store(
+            key, instance_id, gpu_block_ids, event_ipc_handle
+        )
+
+        # The matcher is engine-shared; only worker 0 registers.
+        if key.worker_id not in (0, None):
+            return result
+
+        # Enqueue on cupy_stream so CUDA FIFO ordering puts registration
+        # after the L1-commit callback; otherwise lookups see the chunk as
+        # not-yet-committed and drop the whole group as stale.
+        try:
+            session = self._ctx.session_manager.get_or_create(key.request_id)
+            chunk_hashes = [
+                TokenHasher.hash_to_bytes(h)
+                for h in session.get_hashes(key.start, key.end)
+            ]
+            if not chunk_hashes:
+                return result
+            tokens_in_range = list(key.token_ids)[key.start : key.end]
+            start_chunk_idx = 1 if key.start == 0 else 0
+            job = (tokens_in_range, chunk_hashes, start_chunk_idx, key.start)
+            with self._pending_fp_lock:
+                self._pending_fp_hashes.update(chunk_hashes[start_chunk_idx:])
+            entry = self._transfer_module.get_and_touch_context_entry(instance_id)
+            gpu_ctx = entry.cache_context if entry is not None else None
+            if gpu_ctx is not None and gpu_ctx.cupy_stream is not None:
+                gpu_ctx.cupy_stream.launch_host_func(
+                    self._fingerprint_queue.put_nowait, job
+                )
+            else:
+                self._fingerprint_queue.put_nowait(job)
+        except Exception:
+            logger.exception(
+                "CB fingerprint enqueue failed for request %s "
+                "(does not affect store correctness)",
+                key.request_id,
+            )
+
+        if self._coordinator is not None:
+            self._publish_fingerprints(key, chunk_hashes, tokens_in_range)
+
+        return result
+
+    def _publish_fingerprints(
+        self,
+        key: IPCCacheServerKey,
+        chunk_hashes: list[bytes],
+        tokens_in_range: list[int],
+    ) -> None:
+        """Publish this stored range's chunk fingerprints to the coordinator.
+
+        Best-effort and fire-and-forget (enqueue only): one wire
+        ``ChunkFingerprint`` per stored chunk -- its content poly-hash (the same
+        ``chunk_hash_windows_numba`` the match probes, with the fleet base), its
+        shared-L2 ``object_key`` (the chunk storage key ``th``), and its token
+        position. Never raises into the store path.
+
+        Args:
+            key: The store request key (model/scope/positions).
+            chunk_hashes: Per-chunk storage keys (``th``) for the range.
+            tokens_in_range: The stored tokens ``token_ids[start:end]``.
+        """
+        coordinator = self._coordinator
+        if coordinator is None or not chunk_hashes:
+            return
+        try:
+            model_scope = key.model_name
+            store_range = {
+                "model_scope": model_scope,
+                "tokens": list(tokens_in_range),
+                "object_keys": [h.hex() for h in chunk_hashes],
+                "old_st_base": key.start,
+            }
+            coordinator.enqueue_register([store_range])
+        except Exception:
+            logger.warning(
+                "CB coordinator publish build failed for request %s "
+                "(does not affect store correctness)",
+                key.request_id,
+            )
+
+    def _submit_coordinator_match(self, key: IPCCacheServerKey) -> bool:
+        """Issue a fleet directory match query for this request (best-effort).
+
+        Args:
+            key: The lookup request key.
+
+        Returns:
+            ``True`` if a query was submitted (so the finalize step should poll
+            for it), ``False`` when there is no coordinator or submission failed.
+        """
+        coordinator = self._coordinator
+        if coordinator is None:
+            return False
+        try:
+            tokens = list(key.token_ids)
+            if len(tokens) < self._ctx.chunk_size:
+                return False
+            coordinator.submit_match(key.request_id, key.model_name, tokens)
+            return True
+        except Exception:
+            logger.warning(
+                "CB coordinator match submit failed for request %s", key.request_id
+            )
+            return False
+
+    def _poll_coordinator_match(
+        self, job: "_CBUnifiedJob", rid: str
+    ) -> "list[CBMatchResult] | None":
+        """Poll the coordinator match result, deferring until it resolves.
+
+        Mirrors the prefix/sparse legs: ``return None`` to defer while pending.
+        A per-lookup wall-clock deadline (``job.coord_deadline``) bounds the
+        total wait, including queue/pool time. Past the deadline the leg is
+        abandoned and the lookup proceeds local-only (the client's later fill,
+        if any, is dropped via ``take_match``).
+
+        Args:
+            job: The per-request poll state.
+            rid: Request id.
+
+        Returns:
+            The global segments (possibly empty) once resolved or timed out, or
+            ``None`` to defer (still in flight and within the deadline).
+        """
+        coordinator = self._coordinator
+        if coordinator is None or not job.coord_submitted:
+            return []
+        poll = coordinator.poll_match(rid)
+        if poll is PENDING:
+            if time.monotonic() < job.coord_deadline:
+                return None  # defer; bounded by job.coord_deadline
+            coordinator.take_match(rid)
+            logger.warning(
+                "CB coordinator match deadline exceeded for %s; local-only", rid
+            )
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.CB_COORDINATOR_MATCH_END,
+                    session_id=rid,
+                    metadata={"matches": 0, "timed_out": True},
+                )
+            )
+            return []
+        coordinator.take_match(rid)
+        segments = self._build_global_segments(poll) if isinstance(poll, list) else []
+        self._event_bus.publish(
+            Event(
+                event_type=EventType.CB_COORDINATOR_MATCH_END,
+                session_id=rid,
+                metadata={"matches": len(segments), "timed_out": False},
+            )
+        )
+        return segments
+
+    def _build_global_segments(
+        self, matches: "list[RemoteMatch]"
+    ) -> list[CBMatchResult]:
+        """Convert coordinator matches into chunk-granular retrievable segments.
+
+        Each coordinator ``object_key`` is the hex of the chunk's content hash
+        (the same ``th`` a local ``CBMatchResult.hash`` holds), so the matches
+        are returned as ``CBMatchResult`` directly: the retrieve path then
+        expands ``hash`` to per-rank shared-L2 object keys via
+        ``ipc_key_to_object_keys``, identical to local matches.
+
+        Args:
+            matches: Matched chunks returned by the coordinator client.
+
+        Returns:
+            One :class:`CBMatchResult` per matched chunk (request order).
+        """
+        chunk_size = self._ctx.chunk_size
+        return [
+            CBMatchResult(
+                old_st=m.old_st,
+                old_ed=m.old_st + chunk_size,
+                cur_st=m.cur_st,
+                cur_ed=m.cur_st + chunk_size,
+                hash=bytes.fromhex(m.object_key),
+            )
+            for m in matches
+        ]
+
+    def _drain_fingerprint_queue(self) -> None:
+        """Best-effort background drainer for _fingerprint_queue."""
+        while not self._fingerprint_stop.is_set():
+            try:
+                job = self._fingerprint_queue.get(timeout=0.1)
+            except QueueEmpty:
+                continue
+            tokens_in_range, chunk_hashes, start_chunk_idx, position_offset = job
+            try:
+                self._token_range_matcher.on_new_token_hashes(
+                    tokens_in_range,
+                    chunk_hashes,
+                    start_chunk_idx=start_chunk_idx,
+                    position_offset=position_offset,
+                )
+            except Exception:
+                logger.exception("CB fingerprint registration failed (async)")
+            finally:
+                with self._pending_fp_lock:
+                    self._pending_fp_hashes.difference_update(
+                        chunk_hashes[start_chunk_idx:]
+                    )
+
+    def _apply_cb_rope_batched(
+        self,
+        gpu_context: BaseCacheContext,
+        rope_state: _CBRopeState,
+        batch_len: int,
+        slots_to_rope: list[tuple[int, int, int]],
+    ) -> None:
+        """Re-RoPE the given tmp-pool slots in place (K-only, per kernel group).
+
+        Args:
+            gpu_context (GPUCacheContext): The instance's GPU cache context.
+            rope_state (_CBRopeState): Cached cos/sin + head layout.
+            batch_len (int): Number of tmp slots staged for this batch.
+            slots_to_rope (list[tuple[int, int, int]]): ``(slot_idx, old_st,
+                cur_st)`` per shifted slot — re-RoPE K from stored position
+                ``old_st`` to new position ``cur_st``.
+
+        Raises:
+            RuntimeError: On a compressed (compress_ratio != 1) or MLA
+                (kv_size != 2) layout, or a head_size/hidden_dim mismatch.
+        """
+        if not slots_to_rope:
+            return
+        num_groups = gpu_context.kv_layer_groups_manager.num_kernel_groups
+        for group_idx in range(num_groups):
+            group = gpu_context.kv_layer_groups_manager.kernel_groups[group_idx]
+            if group.tokens_per_block != group.slots_per_block:
+                raise RuntimeError(
+                    f"CB v3: group {group_idx} is compressed "
+                    f"(tokens_per_block={group.tokens_per_block}, "
+                    f"slots_per_block={group.slots_per_block}); "
+                    f"compressed layouts unsupported."
+                )
+            all_slots = [
+                gpu_context.get_temp_kernel_group_buffer(slot_idx, group_idx)
+                for slot_idx in range(batch_len)
+            ]
+            if all_slots[0].shape[0] != 2:
+                raise RuntimeError(
+                    f"CB v3: group {group_idx} has kv_size={all_slots[0].shape[0]}; "
+                    "MLA layouts unsupported."
+                )
+            num_layers, slots, hidden_dim = all_slots[0].shape[1:]
+            n_heads = hidden_dim // rope_state.head_size
+            if n_heads * rope_state.head_size != hidden_dim:
+                raise RuntimeError(
+                    f"CB rope: group {group_idx} hidden_dim ({hidden_dim}) "
+                    f"not a multiple of head_size ({rope_state.head_size})."
+                )
+            # Per-group rope cache: dual-RoPE models rotate each
+            # kernel group with its own theta's cos/sin.
+            group_cos_sin = rope_state.cache_for_group(group.engine_group_idx)
+            # slot ramp tiled across layers is invariant per (num_layers,
+            # slots) — cache it; each shifted slot then just adds its offset.
+            device = all_slots[0].device
+            sp_key = (str(device), num_layers, slots)
+            sp_cache = getattr(self, "_cb_sp_rep_cache", None)
+            if sp_cache is None:
+                sp_cache = {}
+                self._cb_sp_rep_cache = sp_cache
+            slot_positions_rep = sp_cache.get(sp_key)
+            if slot_positions_rep is None:
+                slot_positions_rep = torch.arange(
+                    slots, device=device, dtype=torch.long
+                ).repeat(num_layers)
+                sp_cache[sp_key] = slot_positions_rep
+            for slot_idx, old_st, cur_st in slots_to_rope:
+                # reshape returns an in-place view (tmp slots are contiguous).
+                k_view = all_slots[slot_idx][0].reshape(
+                    num_layers * slots, n_heads, rope_state.head_size
+                )
+                lmc_ops.rotary_embedding_k_fused(
+                    old_st + slot_positions_rep,
+                    cur_st + slot_positions_rep,
+                    k_view,
+                    rope_state.head_size,
+                    group_cos_sin,
+                    rope_state.is_neox_style,
+                )
+
+    def cb_retrieve_pre_computed(
+        self,
+        key: IPCCacheServerKey,
+        cb_match_result: list[CBMatchResult],
+        gpu_block_ids: list[list[int]],
+        instance_id: int,
+        event_ipc_handle: bytes,
+    ) -> tuple[bytes, bool]:
+        """Scatter every matched token range into the request's paged KV.
+
+        Reuses the lookup's prefetched chunks: fills tmp slots, K-only re-RoPEs
+        the shifted (non-prefix) subset, then writes per-token via the slot
+        kernel — so non-block-aligned matches and partial vLLM blocks shared
+        with recomputed tokens are written correctly (no block-alignment trim).
+        Only matches past the currently allocated slots are dropped (vLLM may
+        call this twice: partial- then full-block alloc).
+
+        Args:
+            key (IPCCacheServerKey): The request key.
+            cb_match_result (list[CBMatchResult]): Matched ranges to scatter
+                (prefix-hit and shifted), any order.
+            gpu_block_ids (list[list[int]]): This request's paged block table
+                per engine (kernel) group; single-group models pass [[...]].
+                Mirrors the engine RETRIEVE/STORE per-group block-id contract.
+            instance_id (int): Target KV-cache instance.
+            event_ipc_handle (bytes): IPC handle to the forward's CUDA event.
+
+        Returns:
+            tuple[bytes, bool]: The scatter-complete event handle and whether
+            the scatter ran (False if the prefetched objects were unavailable).
+
+        Raises:
+            ValueError: If the instance has no registered KV cache or rope
+                state. MLA layouts are unsupported (raised during re-RoPE).
+        """
+        entry = self._transfer_module.get_and_touch_context_entry(instance_id)
+        if entry is None:
+            raise ValueError(
+                f"Instance {instance_id} not registered for paged KV cache"
+            )
+        if instance_id not in self._cb_rope_state:
+            raise ValueError(
+                f"Instance {instance_id} has no CB rope state; "
+                "send CB_REGISTER_ROPE_V3 before CB_RETRIEVE_PRE_COMPUTED_V3."
+            )
+        gpu_context = entry.cache_context
+        rope_state = self._cb_rope_state[instance_id]
+        chunk_size = self._ctx.chunk_size
+
+        _retrieve_t0 = time.perf_counter()
+        cb_match_result = sorted(cb_match_result, key=lambda r: r.cur_st)
+        # L2 opt: reuse lookup's obj_keys cache; fall back to re-resolve.
+        with self._lookup_obj_keys_lock:
+            cached = self._lookup_obj_keys_cache.pop(key.request_id, None)
+        if cached is not None and all(r.hash in cached for r in cb_match_result):
+            # The lookup cached all-ranks obj keys (world_size per hash). This
+            # retrieve is per-worker, so select THIS rank's key -> M objects, not
+            # M*world_size (else the zip below silently truncates and mispairs
+            # ranks at TP>1). Mirrors the non-cached path's per-worker resolve.
+            if key.worker_id is not None and key.world_size > 1:
+                all_obj_keys = [cached[r.hash][key.worker_id] for r in cb_match_result]
+            else:
+                all_obj_keys = [k for r in cb_match_result for k in cached[r.hash]]
+        else:
+            all_obj_keys = ipc_key_to_object_keys(
+                key, [r.hash for r in cb_match_result], [0]
+            )[0]
+
+        # Lookup read-locked the full found set, but the connector may have
+        # dropped some matches (parent-covered / misaligned) before retrieve,
+        # leaking their per-key read locks. Release those orphans now (disjoint
+        # from all_obj_keys, which retrieve still consumes; needs the key cache).
+        if cached is not None:
+            retrieved_hashes = {r.hash for r in cb_match_result}
+            orphan_keys = [
+                k for h, ks in cached.items() if h not in retrieved_hashes for k in ks
+            ]
+            if orphan_keys:
+                self._ctx.storage_manager.finish_read_prefetched(orphan_keys)
+                logger.debug(
+                    "CB V3 released %d prefetched-but-unretrieved keys (req=%s)",
+                    len(orphan_keys),
+                    key.request_id,
+                )
+
+        # Non-prefix sparse hits split by re-rope need (not prefix coverage).
+        n_non_shifted = sum(1 for r in cb_match_result if r.old_st == r.cur_st)
+        n_shifted = len(cb_match_result) - n_non_shifted
+
+        if not all_obj_keys:
+            self._event_bus.publish(
+                Event(
+                    event_type=EventType.CB_REQUEST_END,
+                    session_id=key.request_id,
+                )
+            )
+            return event_ipc_handle, True
+
+        logger.debug("CB V3 retrieving object keys: %s", all_obj_keys)
+
+        # CB v3 only supports uncompressed single-block-id-space layouts
+        # (enforced per group in ``_apply_cb_rope_batched``), so the first
+        # kernel group's chunk geometry is representative.
+        tokens_per_block = gpu_context.kv_layer_groups_manager.kernel_groups[
+            0
+        ].tokens_per_block
+        if chunk_size % tokens_per_block != 0:
+            raise ValueError(
+                f"chunk_size {chunk_size} must be a multiple of "
+                f"tokens_per_block {tokens_per_block}"
+            )
+        num_groups = gpu_context.kv_layer_groups_manager.num_kernel_groups
+
+        with (
+            torch_dev.device(gpu_context.device),
+            torch_dev.stream(gpu_context.stream),
+        ):
+            check_interprocess_event_support()
+            event = torch_dev.Event(interprocess=True)
+
+            # One staged block-id tensor per engine group, indexed by group.
+            block_ids_per_group_gpu = gpu_context.stage_block_ids(gpu_block_ids)
+
+            # Resolve each kernel group's block table + block size once. Select
+            # by engine_group_idx (kernel groups may share one, e.g. MiniMax-M3).
+            kgm = gpu_context.kv_layer_groups_manager
+            resolved_groups: list[tuple[torch.Tensor, int]] = []
+            for group_idx in range(num_groups):
+                eg_idx = kgm.kernel_groups[group_idx].engine_group_idx
+                if eg_idx >= len(block_ids_per_group_gpu):
+                    # Engine groups have independent block tables under HMA;
+                    # substituting another group's table would scatter KV into
+                    # the wrong physical blocks (silent corruption).
+                    raise ValueError(
+                        f"CB retrieve: kernel group {group_idx} maps to engine "
+                        f"group {eg_idx}, but only "
+                        f"{len(block_ids_per_group_gpu)} block table(s) were "
+                        "provided."
+                    )
+                resolved_groups.append(
+                    (
+                        block_ids_per_group_gpu[eg_idx],
+                        kgm.kernel_groups[group_idx].tokens_per_block,
+                    )
+                )
+
+            self._event_bus.publish_on_stream(
+                gpu_context.cupy_stream,
+                Event(
+                    event_type=EventType.CB_RETRIEVE_START,
+                    session_id=key.request_id,
+                    metadata={
+                        "num_chunks": len(cb_match_result),
+                        "model_name": key.model_name,
+                    },
+                ),
+            )
+
+            if not hasattr(torch_dev.Event, "from_ipc_handle"):
+                raise RuntimeError(
+                    f"Backend '{torch_device_type}' does not support IPC "
+                    "event handles (Event.from_ipc_handle not available). "
+                    "Multiprocess IPC requires CUDA."
+                )
+            vllm_event = torch_dev.Event.from_ipc_handle(
+                gpu_context.device, event_ipc_handle
+            )
+            vllm_event.wait(stream=gpu_context.stream)
+
+            try:
+                with self._ctx.storage_manager.read_prefetched_results(
+                    all_obj_keys
+                ) as memory_objs:
+                    if memory_objs is None:
+                        return event_ipc_handle, False
+
+                    # Per-token scatter handles any cur_st; just bound the
+                    # matched range to the allocated slots.
+                    pairs: list[tuple[CBMatchResult, Any]] = []
+                    # Bound by the smallest group: under HMA the sliding group
+                    # has fewer blocks than the full group, so [0] isn't safe.
+                    num_slots = min(
+                        int(block_ids.numel()) * group_bs
+                        for block_ids, group_bs in resolved_groups
+                    )
+                    for r, memory_obj in zip(cb_match_result, memory_objs, strict=True):
+                        if r.cur_ed > num_slots:
+                            logger.warning(
+                                "Dropping CB match cur_st=%d cur_ed=%d: exceeds "
+                                "%d slots. Request %s.",
+                                r.cur_st,
+                                r.cur_ed,
+                                num_slots,
+                                key.request_id,
+                            )
+                            continue
+                        pairs.append((r, memory_obj))
+
+                    # cb.scatter span (GPU): the L1->paged write of every
+                    # applied match. Re-RoPE is folded in (n_shifted) — it is
+                    # interleaved per-batch, so not a separate span.
+                    self._event_bus.publish_on_stream(
+                        gpu_context.cupy_stream,
+                        Event(
+                            event_type=EventType.CB_SCATTER_START,
+                            session_id=key.request_id,
+                            metadata={
+                                "scattered_tokens": sum(
+                                    r.cur_ed - r.cur_st for r, _ in pairs
+                                ),
+                                "n_prefix": sum(
+                                    1 for r, _ in pairs if r.old_st == r.cur_st
+                                ),
+                                "n_shifted": sum(
+                                    1 for r, _ in pairs if r.old_st != r.cur_st
+                                ),
+                                "dropped": len(cb_match_result) - len(pairs),
+                            },
+                        ),
+                    )
+
+                    # Consecutive matches → one batched scatter per group.
+                    runs: list[list[tuple[CBMatchResult, Any]]] = []
+                    for r_obj in pairs:
+                        r = r_obj[0]
+                        if runs and runs[-1][-1][0].cur_ed == r.cur_st:
+                            runs[-1].append(r_obj)
+                        else:
+                            runs.append([r_obj])
+
+                    max_batch = gpu_context.max_batch_size
+                    for run in runs:
+                        for batch_start in range(0, len(run), max_batch):
+                            batch = run[batch_start : batch_start + max_batch]
+                            batch_len = len(batch)
+
+                            # (a) H2D fill into per-chunk tmp slots.
+                            for slot_idx, (_, memory_obj) in enumerate(batch):
+                                # Single object group => object_group_idx=0.
+                                flat_slot = gpu_context.get_temp_object_group_buffer(
+                                    slot_idx, 0
+                                )
+                                lmcache_memcpy_async_h2d(memory_obj, flat_slot)
+
+                            # (b) Re-RoPE shifted (non-prefix) slots in place.
+                            slots_to_rope = [
+                                (slot_idx, r.old_st, r.cur_st)
+                                for slot_idx, (r, _) in enumerate(batch)
+                                if r.old_st != r.cur_st
+                            ]
+                            self._apply_cb_rope_batched(
+                                gpu_context, rope_state, batch_len, slots_to_rope
+                            )
+
+                            # (c) Per-token slot scatter: partial vLLM blocks
+                            # shared with recomputed tokens stay disjoint.
+                            pos = torch.cat(
+                                [
+                                    torch.arange(
+                                        r.cur_st,
+                                        r.cur_ed,
+                                        device=gpu_context.device,
+                                        dtype=torch.long,
+                                    )
+                                    for (r, _) in batch
+                                ]
+                            )
+                            for group_idx in range(num_groups):
+                                # This group's block table + size (resolved above).
+                                group_block_ids, group_bs = resolved_groups[group_idx]
+                                # Per-group block count: under HMA the sliding
+                                # group has fewer blocks than the full group, so
+                                # gpu_context.num_blocks (group 0's) would
+                                # truncate the other groups' bounds check.
+                                page_buffer_size = (
+                                    kgm.kernel_groups[group_idx].shape_desc.nb
+                                    * group_bs
+                                )
+                                slot_mapping = group_block_ids[
+                                    pos // group_bs
+                                ] * group_bs + (pos % group_bs)
+                                tmp_buffers = [
+                                    gpu_context.get_temp_kernel_group_buffer(
+                                        slot_idx, group_idx
+                                    )
+                                    for slot_idx in range(batch_len)
+                                ]
+                                key_value = torch.cat(tmp_buffers, dim=2)
+                                lmc_ops.multi_layer_kv_transfer(
+                                    key_value,
+                                    gpu_context.get_kernel_group_kv_pointers(group_idx),
+                                    slot_mapping,
+                                    gpu_context.device,
+                                    page_buffer_size,
+                                    lmc_ops.TransferDirection.H2D,
+                                    gpu_context.get_engine_kv_format(group_idx),
+                                    block_size=group_bs,
+                                    head_size=rope_state.head_size,
+                                )
+
+                    self._event_bus.publish_on_stream(
+                        gpu_context.cupy_stream,
+                        Event(
+                            event_type=EventType.CB_SCATTER_END,
+                            session_id=key.request_id,
+                        ),
+                    )
+            except Exception:
+                logger.exception("Error during retrieving prefetched results")
+                self._event_bus.publish_on_stream(
+                    gpu_context.cupy_stream,
+                    Event(
+                        event_type=EventType.CB_RETRIEVE_END,
+                        session_id=key.request_id,
+                        metadata={"success": False},
+                    ),
+                )
+                self._event_bus.publish_on_stream(
+                    gpu_context.cupy_stream,
+                    Event(
+                        event_type=EventType.CB_REQUEST_END,
+                        session_id=key.request_id,
+                    ),
+                )
+                return event_ipc_handle, False
+
+            event.record()
+            self._event_bus.publish_on_stream(
+                gpu_context.cupy_stream,
+                Event(
+                    event_type=EventType.CB_RETRIEVE_END,
+                    session_id=key.request_id,
+                    metadata={"success": True},
+                ),
+            )
+
+        _scatter_ms = (time.perf_counter() - _retrieve_t0) * 1000
+        logger.info(
+            "Retrieved pre-computed for %d match results into request %s "
+            "paged blocks (scatter_ms=%.2f, non_shifted=%d shifted=%d)",
+            len(cb_match_result),
+            key.request_id,
+            _scatter_ms,
+            n_non_shifted,
+            n_shifted,
+        )
+        self._event_bus.publish_on_stream(
+            gpu_context.cupy_stream,
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=key.request_id,
+            ),
+        )
+        return event.ipc_handle(), True
diff --git a/lmcache/v1/multiprocess/modules/engine_driven_transfer.py b/lmcache/v1/multiprocess/modules/engine_driven_transfer.py
new file mode 100644
index 0000000..6a43c90
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/engine_driven_transfer.py
@@ -0,0 +1,535 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Engine-driven KV cache transfer operations for the MPCacheServer."""
+
+# Standard
+from dataclasses import dataclass
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+)
+from lmcache.v1.multiprocess.custom_types import (
+    IPCCacheServerKey,
+    RegisterEngineDrivenContextPayload,
+)
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext, ShmPoolInfo
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    InstanceLivenessTarget,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.protocols.base import RequestType
+from lmcache.v1.multiprocess.protocols.engine import (
+    PrepareRetrieveResponse,
+    PrepareStoreResponse,
+    RegisterEngineDrivenContextResponse,
+)
+from lmcache.v1.multiprocess.transfer_context.base import EngineDrivenContextMetadata
+
+# Local
+from .server_transfer import (
+    TransferStrategy,
+    create_transfer_strategy,
+)
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class EngineDrivenContextEntry:
+    """Registered non-GPU context metadata for a single worker instance.
+
+    Attributes:
+        metadata: Layout metadata describing the non-CUDA chunk format.
+        model_name: The name of the model associated with this context.
+        world_size: The world size associated with this context.
+        last_seen: ``time.monotonic()`` of the most recent activity from this
+            instance (register, PING, prepare/commit). Drives reaping.
+        has_liveness_signal: True once the instance has sent at least one
+            PING. Selects the reap window. Latched only by PING.
+    """
+
+    metadata: EngineDrivenContextMetadata
+    model_name: str
+    world_size: int
+    last_seen: float = 0.0
+    has_liveness_signal: bool = False
+
+
+class EngineDrivenTransferModule(InstanceLivenessTarget):
+    """Handles Engine-driven KV cache transfer operations.
+
+    Owns non-GPU context registrations and provides handlers for
+    register, unregister, prepare/commit store, and prepare/commit retrieve
+    of CPU-serialized KV caches.
+
+    Args:
+        ctx: The shared engine context.
+    """
+
+    def __init__(self, ctx: MPCacheServerContext) -> None:
+        self._ctx = ctx
+        self._engine_driven_contexts: dict[int, EngineDrivenContextEntry] = {}
+        self._strategies: dict[int, TransferStrategy] = {}
+        # Guards _engine_driven_contexts and _strategies together (the reaper
+        # mutates them off the MQ main loop). Leaf lock, never held with
+        # _pending_shm_lock.
+        self._lock = threading.Lock()
+        self._pending_shm_writes: dict[
+            tuple[int, IPCCacheServerKey], list[ObjectKey]
+        ] = {}
+        self._pending_shm_reads: dict[
+            tuple[int, IPCCacheServerKey], list[ObjectKey]
+        ] = {}
+        self._pending_shm_lock = threading.Lock()
+        self._shm_pool_info: ShmPoolInfo = self._ctx.shm_pool_info
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        return self._ctx
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves.
+
+        Returns:
+            A list of HandlerSpec entries mapping request types to
+            their handler callables and thread pool assignments.
+        """
+        return [
+            HandlerSpec(
+                RequestType.REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT,
+                self.register_kv_cache_engine_driven_context,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT,
+                self.unregister_kv_cache,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.PREPARE_STORE,
+                self.prepare_store,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.COMMIT_STORE,
+                self.commit_store,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.PREPARE_RETRIEVE,
+                self.prepare_retrieve,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.COMMIT_RETRIEVE,
+                self.commit_retrieve,
+                ThreadPoolType.AFFINITY,
+            ),
+        ]
+
+    def report_status(self) -> dict:
+        """Return non-GPU transfer module status information.
+
+        Returns:
+            A dict containing registered non-CUDA instance IDs and
+            per-instance context metadata.
+        """
+        registered_non_cuda_ids: list[int] = []
+        non_cuda_context_meta: dict[str, dict] = {}
+
+        with self._lock:
+            entries = dict(self._engine_driven_contexts)
+        for instance_id, entry in entries.items():
+            registered_non_cuda_ids.append(instance_id)
+            non_cuda_context_meta[str(instance_id)] = {
+                "model_name": entry.model_name,
+                "world_size": entry.world_size,
+                "block_size": entry.metadata.block_size,
+                "use_mla": entry.metadata.use_mla,
+            }
+
+        return {
+            "registered_non_cuda_instance_ids": registered_non_cuda_ids,
+            "non_cuda_context_meta": non_cuda_context_meta,
+        }
+
+    def close(self) -> None:
+        """Release resources owned by this module."""
+        with self._lock:
+            self._engine_driven_contexts.clear()
+            self._strategies.clear()
+
+    def touch_instance(self, instance_id: int) -> None:
+        """Refresh the worker's last-seen time and mark it ping-proven.
+
+        A no-op if the instance is not tracked.
+
+        Args:
+            instance_id: The worker instance ID.
+        """
+        now = time.monotonic()
+        with self._lock:
+            entry = self._engine_driven_contexts.get(instance_id)
+            if entry is not None:
+                entry.last_seen = now
+                entry.has_liveness_signal = True
+
+    def tracked_instance_count(self) -> int:
+        """Return the number of currently registered non-GPU instances."""
+        with self._lock:
+            return len(self._engine_driven_contexts)
+
+    def reap_stale_instances(
+        self, reap_timeout_s: float, registration_grace_s: float
+    ) -> list[int]:
+        """Reap non-GPU registrations that have gone silent.
+
+        A ping-proven instance is judged against ``reap_timeout_s``; one that
+        has never pinged against the larger ``registration_grace_s``.
+
+        Args:
+            reap_timeout_s: Silence budget for ping-proven instances.
+            registration_grace_s: Silence budget for never-pinged instances.
+
+        Returns:
+            The instance IDs reaped this scan.
+        """
+        now = time.monotonic()
+        reaped: list[tuple[int, EngineDrivenContextEntry]] = []
+        with self._lock:
+            stale_ids = [
+                iid
+                for iid, entry in self._engine_driven_contexts.items()
+                if now - entry.last_seen
+                > (
+                    reap_timeout_s
+                    if entry.has_liveness_signal
+                    else registration_grace_s
+                )
+            ]
+            for iid in stale_ids:
+                entry = self._engine_driven_contexts.pop(iid)
+                self._strategies.pop(iid, None)
+                reaped.append((iid, entry))
+        for iid, entry in reaped:
+            self._release_entry(iid, entry)
+            logger.warning(
+                "Reaped non-GPU instance %d: silent for %.1fs (pinged=%s)",
+                iid,
+                now - entry.last_seen,
+                entry.has_liveness_signal,
+            )
+        return [iid for iid, _ in reaped]
+
+    def _resolve_for_transfer(
+        self, instance_id: int
+    ) -> tuple[EngineDrivenContextEntry, TransferStrategy]:
+        """Return (entry, strategy) for a transfer, refreshing last_seen.
+
+        Pair-atomicity guarantees the entry exists whenever the strategy
+        does. Refreshes last_seen (no latch) so an active worker is not
+        reaped mid-transfer.
+
+        Args:
+            instance_id: The worker instance ID.
+
+        Returns:
+            The entry and its transfer strategy.
+
+        Raises:
+            ValueError: If the instance is not registered (or was reaped).
+        """
+        now = time.monotonic()
+        with self._lock:
+            entry = self._engine_driven_contexts.get(instance_id)
+            strategy = self._strategies.get(instance_id)
+            if entry is None or strategy is None:
+                raise ValueError(
+                    "non-GPU context not registered (or reaped) for "
+                    f"instance ID {instance_id}"
+                )
+            entry.last_seen = now
+            return entry, strategy
+
+    def _release_entry(self, instance_id: int, entry: EngineDrivenContextEntry) -> None:
+        """Release resources for a popped entry (run outside the lock).
+
+        Sweeps the instance's pending SHM transfers and unregisters its
+        layout descriptor.
+
+        Args:
+            instance_id: The popped instance ID.
+            entry: The popped entry.
+        """
+        with self._pending_shm_lock:
+            stale_writes = [k for k in self._pending_shm_writes if k[0] == instance_id]
+            stale_reads = [k for k in self._pending_shm_reads if k[0] == instance_id]
+            write_obj_keys = [self._pending_shm_writes.pop(k) for k in stale_writes]
+            read_obj_keys = [self._pending_shm_reads.pop(k) for k in stale_reads]
+
+        for obj_keys in write_obj_keys:
+            if obj_keys:
+                self._ctx.storage_manager.finish_write(obj_keys)
+        for obj_keys in read_obj_keys:
+            if obj_keys:
+                self._ctx.storage_manager.finish_read_prefetched(obj_keys)
+
+        self._ctx.layout_desc_registry.unregister(entry.model_name, entry.world_size)
+
+    @staticmethod
+    def _make_transfer_key(
+        key: IPCCacheServerKey, instance_id: int
+    ) -> tuple[int, IPCCacheServerKey]:
+        return (instance_id, key)
+
+    def _resolve_single_group_obj_keys(self, key: IPCCacheServerKey) -> list[ObjectKey]:
+        """Resolve object keys for the single object group used by
+        non-GPU transfers."""
+        return self._ctx.resolve_obj_keys(key, [0])[0]
+
+    def register_kv_cache_engine_driven_context(
+        self,
+        payload: RegisterEngineDrivenContextPayload,
+    ) -> RegisterEngineDrivenContextResponse:
+        """Register non-CUDA KV layout metadata for non-GPU context mode.
+
+        Args:
+            payload: Struct containing all registration fields
+                (instance_id, model_name, world_size, block_size,
+                num_layers, hidden_dim_size, dtype_str, use_mla).
+
+        Raises:
+            ValueError: If ``payload.dtype_str`` is not a valid torch dtype name.
+        """
+        shm_name = self._shm_pool_info["shm_name"]
+        pool_size = self._shm_pool_info["pool_size"]
+
+        now = time.monotonic()
+        with self._lock:
+            existing = self._engine_driven_contexts.get(payload.instance_id)
+            if existing is not None:
+                existing.last_seen = now
+                logger.info(
+                    "Instance %d already registered (non-GPU); refreshing liveness",
+                    payload.instance_id,
+                )
+                return RegisterEngineDrivenContextResponse(
+                    shm_name=shm_name, pool_size=pool_size
+                )
+
+        dtype = getattr(torch, payload.dtype_str, None)
+        if dtype is None or not isinstance(dtype, torch.dtype):
+            raise ValueError(
+                f"Invalid dtype_str '{payload.dtype_str}': must be a valid torch dtype "
+                "attribute name (e.g. 'float16' for torch.float16, "
+                "'bfloat16' for torch.bfloat16, 'float32' for torch.float32)."
+            )
+
+        shape = (
+            torch.Size(
+                [payload.num_layers, self._ctx.chunk_size, payload.hidden_dim_size]
+            )
+            if payload.use_mla
+            else torch.Size(
+                [2, payload.num_layers, self._ctx.chunk_size, payload.hidden_dim_size]
+            )
+        )
+        layout_desc = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+        metadata = EngineDrivenContextMetadata(
+            layout_desc=layout_desc,
+            block_size=payload.block_size,
+            use_mla=payload.use_mla,
+        )
+        # Build the entry and strategy outside the lock, then insert the pair
+        # atomically so a concurrent reap can never strand one without the
+        # other. REGISTER is SYNC-serialized, so it is the sole inserter.
+        entry = EngineDrivenContextEntry(
+            metadata=metadata,
+            model_name=payload.model_name,
+            world_size=payload.world_size,
+            last_seen=now,
+            has_liveness_signal=False,
+        )
+        strategy: TransferStrategy = create_transfer_strategy(
+            self._ctx.storage_manager,
+            shm_name=shm_name,
+            pool_size=pool_size,
+            pending_writes=self._pending_shm_writes,
+            pending_reads=self._pending_shm_reads,
+            pending_lock=self._pending_shm_lock,
+            transfer_key_factory=self._make_transfer_key,
+        )
+        with self._lock:
+            self._engine_driven_contexts[payload.instance_id] = entry
+            self._strategies[payload.instance_id] = strategy
+
+        logger.info(
+            "Registered non-GPU context for instance %d (model=%s, world_size=%d)",
+            payload.instance_id,
+            payload.model_name,
+            payload.world_size,
+        )
+
+        self._ctx.layout_desc_registry.register(
+            payload.model_name, payload.world_size, layout_desc
+        )
+        return RegisterEngineDrivenContextResponse(
+            shm_name=shm_name, pool_size=pool_size
+        )
+
+    def unregister_kv_cache(self, instance_id: int) -> None:
+        """Unregister a non-GPU KV cache context for the given instance ID.
+
+        Args:
+            instance_id: The worker instance identifier.
+        """
+        with self._lock:
+            entry = self._engine_driven_contexts.pop(instance_id, None)
+            if entry is not None:
+                self._strategies.pop(instance_id, None)
+        if entry is None:
+            logger.warning(
+                "No registered non-GPU context found for instance ID %d",
+                instance_id,
+            )
+            return
+
+        self._release_entry(instance_id, entry)
+        logger.info("Unregistered non-CUDA context for instance ID %d", instance_id)
+
+    @_lmcache_nvtx_annotate
+    def prepare_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+    ) -> PrepareStoreResponse:
+        """Prepare a store operation.
+
+        Args:
+            key: Cache key for the token range to store.
+            instance_id: Worker instance identifier.
+
+        Returns:
+            PrepareStoreResponse with empty slots for pickle mode.
+        """
+        entry, strategy = self._resolve_for_transfer(instance_id)
+        response = strategy.prepare_store(
+            key=key,
+            instance_id=instance_id,
+            context=entry.metadata,
+            resolve_obj_keys=self._resolve_single_group_obj_keys,
+        )
+        session = self._ctx.session_manager.get_or_create(key.request_id)
+        session.extras["store_start_time"] = time.perf_counter()
+        return response
+
+    @_lmcache_nvtx_annotate
+    def commit_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        cpu_data: bytes,
+    ) -> bool:
+        """Commit serialized CPU chunks to storage.
+
+        Args:
+            key: Cache key for the token range to store.
+            instance_id: Worker instance identifier.
+            cpu_data: Pickled list of CPU tensors produced by the worker.
+
+        Returns:
+            ``True`` when all reserved objects are written, otherwise ``False``.
+
+        Raises:
+            ValueError: If no non-GPU context is registered for the given
+                instance ID.
+        """
+        entry, strategy = self._resolve_for_transfer(instance_id)
+        session = self._ctx.session_manager.get_or_create(key.request_id)
+        st = session.extras.pop("store_start_time", None)
+        result = strategy.commit_store(
+            key=key,
+            instance_id=instance_id,
+            cpu_data=cpu_data,
+            context=entry.metadata,
+            resolve_obj_keys=self._resolve_single_group_obj_keys,
+        )
+        if st is not None and result:
+            num_tokens = (
+                len(self._resolve_single_group_obj_keys(key)) * self._ctx.chunk_size
+            )
+            logger.info(
+                "Stored %d tokens in %.3f seconds",
+                num_tokens,
+                time.perf_counter() - st,
+            )
+        return result
+
+    @_lmcache_nvtx_annotate
+    def prepare_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+    ) -> PrepareRetrieveResponse:
+        """Retrieve prefetched chunks and return serialized CPU tensors.
+
+        Args:
+            key: Cache key for the token range to retrieve.
+            instance_id: Worker instance identifier.
+
+        Returns:
+            PrepareRetrieveResponse with serialized data on hit.
+
+        Raises:
+            ValueError: If no non-GPU context is registered for the given
+                instance ID.
+        """
+        _, strategy = self._resolve_for_transfer(instance_id)
+        response = strategy.prepare_retrieve(
+            key=key,
+            instance_id=instance_id,
+            resolve_obj_keys=self._resolve_single_group_obj_keys,
+        )
+        session = self._ctx.session_manager.get_or_create(key.request_id)
+        session.extras["retrieve_start_time"] = time.perf_counter()
+        return response
+
+    @_lmcache_nvtx_annotate
+    def commit_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+    ) -> bool:
+        """Finalize a retrieve operation.
+
+        Args:
+            key: Cache key (unused for pickle).
+            instance_id: Worker instance identifier (unused for pickle).
+
+        Returns:
+            Always ``True``.
+        """
+        _, strategy = self._resolve_for_transfer(instance_id)
+        session = self._ctx.session_manager.get_or_create(key.request_id)
+        st = session.extras.pop("retrieve_start_time", None)
+        result = strategy.commit_retrieve(key=key, instance_id=instance_id)
+        if st is not None:
+            num_tokens = (
+                len(self._resolve_single_group_obj_keys(key)) * self._ctx.chunk_size
+            )
+            logger.info(
+                "Retrieved %d tokens in %.3f seconds",
+                num_tokens,
+                time.perf_counter() - st,
+            )
+        return result
diff --git a/lmcache/v1/multiprocess/modules/lmcache_driven_transfer.py b/lmcache/v1/multiprocess/modules/lmcache_driven_transfer.py
new file mode 100644
index 0000000..a1bcc64
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/lmcache_driven_transfer.py
@@ -0,0 +1,1288 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LMCache-driven KV cache transfer operations for the MPCacheServer."""
+
+# Standard
+from dataclasses import dataclass
+from itertools import islice
+from typing import Generator, Sequence
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    EngineType,
+    _lmcache_nvtx_annotate,
+    check_interprocess_event_support,
+)
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+)
+from lmcache.v1.gpu_connector.gpu_ops import (
+    build_staging_copies,
+    lmcache_memcpy_async_d2h,
+    lmcache_memcpy_async_h2d,
+)
+from lmcache.v1.gpu_connector.utils import LayoutHints
+from lmcache.v1.memory_allocators.lazy_memory_allocator import LazyMemoryAllocator
+from lmcache.v1.memory_management import GDSMemoryObject, MemoryObj
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.multiprocess.custom_types import (
+    IPCCacheServerKey,
+    KVCache,
+)
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    InstanceLivenessTarget,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+from lmcache.v1.multiprocess.native_completion import (
+    DeviceHostFuncDispatcher,
+    submit_callback_to_stream,
+)
+from lmcache.v1.multiprocess.protocols.base import RequestType
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+from lmcache.v1.platform.cache_context import create_cache_context
+import lmcache.c_ops as lmc_ops
+import lmcache.python_ops_fallback as _python_ops_fallback
+
+logger = init_logger(__name__)
+_HAS_NATIVE_OBJECT_GROUP_TRANSFER: bool = (
+    lmc_ops.execute_object_group_transfer
+    is not _python_ops_fallback.execute_object_group_transfer
+)
+
+
+def get_layout_desc(
+    cache_context: BaseCacheContext,
+    num_tokens: int,
+    object_group_id: int,
+) -> MemoryLayoutDesc:
+    """Get the memory layout description for a specific object group.
+
+    The returned layout describes the single memory object that backs
+    ``object_group_id``: one (shape, dtype) entry per kernel group in that
+    object group, in the kernel groups' declared layout order. Kernel groups
+    may have different shapes and dtypes.
+
+    Args:
+        cache_context: The cache context containing the KV cache information.
+        num_tokens: The number of tokens to determine the layout for.
+        object_group_id: Index of the object group whose layout to build.
+
+    Returns:
+        MemoryLayoutDesc: The memory layout description containing shapes and
+        dtypes, one entry per kernel group in the object group.
+    """
+    object_group = cache_context.kv_layer_groups_manager.object_groups[object_group_id]
+    shapes_and_dtypes = [
+        cache_context.get_kernel_group_shape_dtype(num_tokens, kernel_group_idx)
+        for kernel_group_idx in object_group.kernel_group_indices
+    ]
+    shapes, dtypes = zip(*shapes_and_dtypes, strict=False)
+    return MemoryLayoutDesc(shapes=list(shapes), dtypes=list(dtypes))
+
+
+def batched_iteration_with_skip(
+    lst: Sequence,
+    batch_size: int,
+    skip_count: int,
+) -> Generator[tuple[int, tuple], None, None]:
+    """Utility function to iterate over a list in batches with an initial skip.
+
+    Args:
+        lst: The list to iterate over.
+        batch_size: The size of each batch.
+        skip_count: The number of items to skip at the start of the list.
+
+    Yields:
+        Tuples of (batch_start_idx, batch) where batch is a tuple of items
+        from the list, and batch_start_idx is the "original" index of the first
+        item in the batch.
+
+    Raises:
+        ValueError: If batch_size is less than 1 or skip_count is negative.
+
+    Note:
+        Batch_idx is the index of the batch in the original list, accounting
+        for the skipped items. For example, if skip_count is 10 and batch_size
+        is 5, the first yielded batch will have batch_start_idx=10.
+    """
+    if batch_size < 1:
+        raise ValueError("batch size must be at least one")
+    if skip_count < 0:
+        raise ValueError("skip_count must be non-negative")
+
+    it = iter(lst)
+    # Skip the initial items
+    for _ in range(skip_count):
+        next(it, None)
+    batch_start_idx = skip_count
+    while batch := tuple(islice(it, batch_size)):
+        yield batch_start_idx, batch
+        batch_start_idx += len(batch)
+
+
+def downsample_and_stage_block_ids(
+    cache_context: BaseCacheContext,
+    block_ids: list[list[int]],
+) -> list[torch.Tensor]:
+    """Cut the block id lists to skip the unneeded blocks in a chunk and
+    stage it into GPU tensors for later use.
+
+    This mainly targets the case where a portion of the blocks are not
+    needed for every chunk, such as deepseek v4's swa cache.
+
+    Note that the we do NOT do any object-level skipping here.
+
+    Args:
+        cache_context: The cache context containing the KV cache information.
+        block_ids: The original block id lists, indexed by LMCache KV group index.
+
+    Returns:
+        The cut block id lists, indexed by LMCache KV group index.
+
+    Note:
+        This function has some coupled logic with transfer_kv_per_object_group below.
+        The caller need to make sure that the block ids seen by
+        transfer_kv_per_object_group are produced by this function.
+
+    Example:
+        If a model have 2 kernel groups, one is full attention with block size 32,
+        one is swa attention with block size 32 and sliding window size 64, and
+        LMCache has a chunk size of 128. And there are 2 chunks in total (256 tokens).
+
+        The input will be:
+        [
+          [1, 2, 3, 4, 5, 6, 7, 8],  # block ids for the full attention group
+          [11, 12, 13, 14, 15, 16, 17, 18], # block ids for the swa attention group
+        ]
+
+        The output will be
+        [
+          [1, 2, 3, 4, 5, 6, 7, 8],  # full attention group still needs all block ids
+          [13, 14, 17, 18], # swa attention group only needs the last 2 block per chunk
+        ]
+    """
+    num_kernel_groups = cache_context.kv_layer_groups_manager.num_kernel_groups
+    for kernel_group_id in range(num_kernel_groups):
+        subchunk_sw_size_tokens = (
+            cache_context.kv_layer_groups_manager.get_subchunk_sw_size_tokens(
+                kernel_group_id
+            )
+        )
+        tokens_per_chunk = min(
+            cache_context.lmcache_tokens_per_chunk, subchunk_sw_size_tokens
+        )
+        keep_blocks_per_chunk = cache_context.calculate_num_blocks(
+            tokens_per_chunk, kernel_group_id
+        )
+        total_blocks_per_chunk = cache_context.calculate_num_blocks(
+            cache_context.lmcache_tokens_per_chunk, kernel_group_id
+        )
+
+        new_block_ids = []
+        old_block_ids = block_ids[kernel_group_id]
+        assert len(old_block_ids) % total_blocks_per_chunk == 0, (
+            f"len(block_ids[{kernel_group_id}]) should be a multiple "
+            f"of total_blocks_per_chunk ({total_blocks_per_chunk}), but got "
+            f"{len(old_block_ids)}"
+        )
+
+        for i in range(0, len(old_block_ids), total_blocks_per_chunk):
+            chunk_block_ids = old_block_ids[i : i + total_blocks_per_chunk]
+            new_block_ids.extend(chunk_block_ids[-keep_blocks_per_chunk:])
+
+        block_ids[kernel_group_id] = new_block_ids
+
+    # Stage the cut block ids into GPU tensors
+    block_ids_gpu = cache_context.stage_block_ids(block_ids)
+    return block_ids_gpu
+
+
+def _recalculate_blocks_to_skip(
+    blocks_per_chunk: int,
+    blocks_per_window: int,
+    blocks_to_skip: int,
+) -> int:
+    """Re-calculate the number of blocks to skip for a batch of chunks based
+    on the blocks per chunk and blocks per sliding window WHEN the window
+    size is smaller than the lmcache chunk size.
+
+    Args:
+        blocks_per_chunk: The total number of blocks in one chunk for the
+            current group.
+        blocks_per_window: The number of blocks in the sliding window
+            for the current group. Should be less than or equal to
+            blocks_per_chunk.
+        blocks_to_skip: The number of blocks to skip.
+
+    Returns:
+        The re-calculated number of blocks to skip for the current batch of
+        chunks.
+    """
+    if blocks_per_chunk == blocks_per_window:
+        return blocks_to_skip
+
+    full_windows_to_skip = blocks_to_skip // blocks_per_chunk
+    tail_blocks = blocks_to_skip % blocks_per_chunk
+    tail_blocks_to_skip = tail_blocks - (blocks_per_chunk - blocks_per_window)
+    return full_windows_to_skip * blocks_per_window + max(0, tail_blocks_to_skip)
+
+
+def _run_object_group_transfer_plan(
+    cache_context: BaseCacheContext,
+    block_ids_gpu: list[torch.Tensor],
+    memory_objs: Sequence[MemoryObj | None],
+    object_group_id: int,
+    batch_size: int,
+    skip_first_n_tokens: int,
+    direction: "lmc_ops.TransferDirection",
+) -> None:
+    """Plan and execute one object group's transfer in a single native call.
+
+    This is the fast path of :func:`transfer_kv_per_object_group`: it runs the
+    same batched-iteration / skip logic, but instead of issuing each staging
+    copy and kernel launch immediately (each a GIL release/re-acquire), it
+    resolves every argument to plain pointers/scalars (the "planner", GIL held
+    throughout) and hands the whole plan to ``execute_object_group_transfer``,
+    which issues all of it on the stream within a single GIL release.
+
+    Requires every object to be non-GDS (staged through the lazy-allocator
+    path); the caller skips groups that contain any GDS-backed object.
+
+    Args:
+        cache_context: The GPU cache context containing the KV cache information.
+        block_ids_gpu: GPU block IDs, indexed by LMCache KV group index.
+        memory_objs: The MemoryObj instances to copy. None entries are only
+            valid for D2H (the batch is skipped); H2D raises.
+        object_group_id: Index of the object group being copied.
+        batch_size: Number of memory objects per batched copy.
+        skip_first_n_tokens: Tokens to skip writing at the start of the range.
+        direction: H2D (retrieve) or D2H (store).
+
+    Raises:
+        ValueError: If a None entry is found in memory_objs when direction is
+            H2D, or if an object's size does not match its GPU staging buffer.
+    """
+    lmcache_chunk_size = cache_context.lmcache_tokens_per_chunk
+    kv_groups_manager = cache_context.kv_layer_groups_manager
+    object_group = kv_groups_manager.object_groups[object_group_id]
+    kernel_group_ids = object_group.kernel_group_indices
+    is_h2d = direction == lmc_ops.TransferDirection.H2D
+    max_batch_size = cache_context.max_batch_size
+
+    # --- Per-kernel-group invariants, resolved once (vs. every batch before) ---
+    kernel_group_specs: list["lmc_ops.KernelGroupSpec"] = []
+    spec_index_by_kg: dict[int, int] = {}
+    blocks_per_chunk_by_kg: dict[int, int] = {}
+    blocks_per_window_by_kg: dict[int, int] = {}
+    for kernel_group_id in kernel_group_ids:
+        blocks_per_chunk = cache_context.calculate_num_blocks(
+            lmcache_chunk_size, kernel_group_id
+        )
+        tokens_per_window = min(
+            lmcache_chunk_size,
+            kv_groups_manager.get_subchunk_sw_size_tokens(kernel_group_id),
+        )
+        blocks_per_window = cache_context.calculate_num_blocks(
+            tokens_per_window, kernel_group_id
+        )
+        blocks_per_chunk_by_kg[kernel_group_id] = blocks_per_chunk
+        blocks_per_window_by_kg[kernel_group_id] = blocks_per_window
+
+        paged_ptrs = cache_context.get_kernel_group_kv_pointers(kernel_group_id)
+        block_ids_tensor = block_ids_gpu[kernel_group_id]
+        temp_buffers = [
+            cache_context.get_temp_kernel_group_buffer(slot, kernel_group_id)
+            for slot in range(max_batch_size)
+        ]
+
+        spec_index_by_kg[kernel_group_id] = len(kernel_group_specs)
+        kernel_group_specs.append(
+            lmc_ops.KernelGroupSpec(
+                paged_ptrs.data_ptr(),
+                [buffer.data_ptr() for buffer in temp_buffers],
+                cache_context.get_shape_desc(kernel_group_id),
+                cache_context.get_slots_per_chunk_in_sw(kernel_group_id),
+                cache_context.get_engine_kv_format(kernel_group_id),
+                block_ids_tensor.data_ptr(),
+                block_ids_tensor.numel(),
+            )
+        )
+
+    # Temp object-group staging buffers (reused per batch slot, like above).
+    object_group_buffers = [
+        cache_context.get_temp_object_group_buffer(slot, object_group_id)
+        for slot in range(max_batch_size)
+    ]
+
+    attn_desc = kv_groups_manager.get_attn_desc()
+    num_objects_to_skip = 0
+    if not attn_desc.is_full_attention(object_group_id) and is_h2d:
+        sw_size_chunks = attn_desc.num_chunks_in_sw[object_group_id]
+        num_objects_to_skip = max(0, len(memory_objs) - sw_size_chunks)
+        logger.debug(
+            "Detected sliding window for object group %d: "
+            "skipping the first %d objects in the batch",
+            object_group_id,
+            num_objects_to_skip,
+        )
+
+    # --- Walk the batches in order, emitting staging + launch work per step ---
+    batch_steps: list["lmc_ops.BatchStep"] = []
+    for start_object_idx, memory_object_batch in batched_iteration_with_skip(
+        memory_objs, batch_size, skip_count=num_objects_to_skip
+    ):
+        if any(mo is None for mo in memory_object_batch):
+            if is_h2d:
+                raise ValueError(
+                    "MemoryObj is None for some objects in the batch, cannot "
+                    "perform H2D copy. memory_object_batch: "
+                    f"{memory_object_batch}"
+                )
+            else:
+                continue
+
+        batch_len = len(memory_object_batch)
+        batch_start_token = start_object_idx * lmcache_chunk_size
+        batch_end_token = batch_start_token + batch_len * lmcache_chunk_size
+
+        effective_start = max(batch_start_token, skip_first_n_tokens)
+        if effective_start >= batch_end_token:
+            continue
+
+        skip_tokens_in_chunk = effective_start - batch_start_token
+
+        staging = build_staging_copies(
+            memory_object_batch,
+            object_group_buffers[:batch_len],
+            is_h2d,
+        )
+
+        launches: list["lmc_ops.LaunchVar"] = []
+        for kernel_group_id in kernel_group_ids:
+            blocks_per_chunk = blocks_per_chunk_by_kg[kernel_group_id]
+            blocks_per_window = blocks_per_window_by_kg[kernel_group_id]
+
+            start_block_pos = start_object_idx * blocks_per_window
+            end_block_pos = (start_object_idx + batch_len) * blocks_per_window
+
+            orig_skip_blocks = cache_context.calculate_num_blocks(
+                skip_tokens_in_chunk, kernel_group_id
+            )
+            recalculated_skip_blocks = _recalculate_blocks_to_skip(
+                blocks_per_chunk,
+                blocks_per_window,
+                orig_skip_blocks,
+            )
+
+            launches.append(
+                lmc_ops.LaunchVar(
+                    spec_index_by_kg[kernel_group_id],
+                    start_block_pos,
+                    end_block_pos - start_block_pos,
+                    batch_len,
+                    recalculated_skip_blocks,
+                )
+            )
+
+        batch_steps.append(lmc_ops.BatchStep(staging, launches))
+
+    if not batch_steps:
+        return
+
+    lmc_ops.execute_object_group_transfer(
+        direction,
+        cache_context.device,
+        LazyMemoryAllocator.PIN_CHUNK_SIZE,
+        kernel_group_specs,
+        batch_steps,
+    )
+
+
+def transfer_kv_per_object_group(
+    cache_context: BaseCacheContext,
+    block_ids_gpu: list[torch.Tensor],
+    memory_objs: Sequence[MemoryObj | None],
+    object_group_id: int,
+    batch_size: int,
+    skip_first_n_tokens: int,
+    direction: "lmc_ops.TransferDirection",
+) -> None:
+    """Helper function to transfer memory objects of a single object group
+    to/from GPU, with batching support.
+
+    Args:
+        cache_context: The GPU cache context containing the KV cache information.
+        block_ids_gpu: GPU block IDs to retrieve into, indexed by LMCache KV group
+            index. It should satisfy `len(block_ids_gpu[i]) == len(memory_objs) *
+            blocks_per_chunk[i]` for each group `i`.
+            Note that the block IDs list are already on GPU.
+        memory_objs: The list of MemoryObj instances to copy from. It could be
+            None when allocation or retrieval fails. For store (D2H), it should
+            ignore the None entry and continue copying the rest. For retrieve
+            (H2D), it should raise the error and stop copying.
+        object_group_id: Index of the object group being copied.
+        batch_size: The number of memory objects to perform batched copy
+        skip_first_n_tokens: Number of tokens to skip writing at the start of
+            the retrieve range. This avoids overwriting APC-shared GPU blocks that
+            may be read concurrently by other requests.
+        direction: The transfer direction, H2D (retrieve) or D2H (store).
+
+    Raises:
+        ValueError: If it founds None entry in memory_objs when direction is H2D.
+    Note:
+        This function expects the caller to stage the block ids (list[list[int]])
+        into GPU tensors and pass them in as `block_ids_gpu`.
+    """
+    if _HAS_NATIVE_OBJECT_GROUP_TRANSFER and not any(
+        isinstance(mo, GDSMemoryObject) for mo in memory_objs
+    ):
+        _run_object_group_transfer_plan(
+            cache_context,
+            block_ids_gpu,
+            memory_objs,
+            object_group_id,
+            batch_size,
+            skip_first_n_tokens,
+            direction,
+        )
+        return
+
+    lmcache_chunk_size = cache_context.lmcache_tokens_per_chunk
+    kv_groups_manager = cache_context.kv_layer_groups_manager
+    object_group = kv_groups_manager.object_groups[object_group_id]
+    kernel_group_ids = object_group.kernel_group_indices
+    is_h2d = direction == lmc_ops.TransferDirection.H2D
+
+    attn_desc = kv_groups_manager.get_attn_desc()
+    num_objects_to_skip = 0
+    if not attn_desc.is_full_attention(object_group_id) and is_h2d:
+        sw_size_chunks = attn_desc.num_chunks_in_sw[object_group_id]
+        num_objects_to_skip = max(0, len(memory_objs) - sw_size_chunks)
+        logger.debug(
+            "Detected sliding window for object group %d: "
+            "skipping the first %d objects in the batch",
+            object_group_id,
+            num_objects_to_skip,
+        )
+
+    for start_object_idx, memory_object_batch in batched_iteration_with_skip(
+        memory_objs, batch_size, skip_count=num_objects_to_skip
+    ):
+        if any(mo is None for mo in memory_object_batch):
+            if is_h2d:
+                raise ValueError(
+                    "MemoryObj is None for some objects in the batch, cannot "
+                    "perform H2D copy. memory_object_batch: "
+                    f"{memory_object_batch}"
+                )
+            else:
+                continue
+
+        batch_len = len(memory_object_batch)
+        batch_start_token = start_object_idx * lmcache_chunk_size
+        batch_end_token = batch_start_token + batch_len * lmcache_chunk_size
+
+        effective_start = max(batch_start_token, skip_first_n_tokens)
+        if effective_start >= batch_end_token:
+            continue
+
+        skip_tokens_in_chunk = effective_start - batch_start_token
+
+        # For H2D, copy from CPU to GPU tmp buffers before the kernel launch
+        if is_h2d:
+            for chunk_idx, memory_obj in enumerate(memory_object_batch):
+                lmcache_memcpy_async_h2d(
+                    memory_obj,
+                    cache_context.get_temp_object_group_buffer(
+                        chunk_idx, object_group_id
+                    ),
+                )
+
+        # Do paged KV copy
+        for kernel_group_id in kernel_group_ids:
+            blocks_per_chunk = cache_context.calculate_num_blocks(
+                lmcache_chunk_size, kernel_group_id
+            )
+            tokens_per_window = min(
+                lmcache_chunk_size,
+                kv_groups_manager.get_subchunk_sw_size_tokens(kernel_group_id),
+            )
+            blocks_per_window = cache_context.calculate_num_blocks(
+                tokens_per_window, kernel_group_id
+            )
+
+            # Get the block ids for this chunk
+            start_block_pos = start_object_idx * blocks_per_window
+            end_block_pos = (start_object_idx + batch_len) * blocks_per_window
+
+            block_ids_curr_batch = block_ids_gpu[kernel_group_id][
+                start_block_pos:end_block_pos
+            ]
+
+            # Re-calculate the skip blocks for this kernel group
+            orig_skip_blocks = cache_context.calculate_num_blocks(
+                skip_tokens_in_chunk, kernel_group_id
+            )
+            recalculated_skip_blocks = _recalculate_blocks_to_skip(
+                blocks_per_chunk,
+                blocks_per_window,
+                orig_skip_blocks,
+            )
+
+            # Launch kernel
+            group_kv_pointers = cache_context.get_kernel_group_kv_pointers(
+                kernel_group_id
+            )
+            group_lmcache_chunk_size = cache_context.get_slots_per_chunk_in_sw(
+                kernel_group_id
+            )
+            tmp_gpu_buffers_batched = [
+                cache_context.get_temp_kernel_group_buffer(
+                    i, kernel_group_id
+                ).data_ptr()
+                for i in range(batch_len)
+            ]
+            lmc_ops.multi_layer_block_kv_transfer(
+                group_kv_pointers,
+                tmp_gpu_buffers_batched,
+                block_ids_curr_batch,
+                cache_context.device,
+                direction,
+                cache_context.get_shape_desc(kernel_group_id),
+                group_lmcache_chunk_size,
+                cache_context.get_engine_kv_format(kernel_group_id),
+                recalculated_skip_blocks,
+            )
+
+        # For D2H, copy from GPU tmp buffers to CPU after the kernel launch
+        if not is_h2d:
+            for chunk_idx, memory_obj in enumerate(memory_object_batch):
+                lmcache_memcpy_async_d2h(
+                    cache_context.get_temp_object_group_buffer(
+                        chunk_idx, object_group_id
+                    ),
+                    memory_obj,
+                )
+
+
+@dataclass
+class ContextEntry:
+    """Registered cache context metadata for a single worker instance.
+
+    The concrete type is whatever :func:`create_cache_context` returned
+    for the wrapper list at registration time -- a
+    :class:`GPUCacheContext` for CUDA-IPC wrappers, a
+    :class:`CPUCacheContext` for POSIX-SHM wrappers. Both expose
+    the same ``kv_tensors`` / ``engine_kv_format`` / ``num_layers`` / ...
+    duck-typed surface, so downstream consumers stay agnostic.
+
+    Args:
+        cache_context: Platform cache context (GPU or CPU) managing
+            shape and pointers to the registered KV cache tensors.
+        model_name: The name of the model associated with this KV cache.
+        world_size: The world size associated with this KV cache.
+        last_seen: ``time.monotonic()`` of the most recent activity from
+            this instance (register, PING, store, or retrieve). Drives reaping.
+        has_liveness_signal: True once the instance has sent at least one
+            PING. Selects the reap window (timeout vs registration grace).
+            Latched only by PING, never by traffic.
+    """
+
+    cache_context: BaseCacheContext
+    model_name: str
+    world_size: int
+    last_seen: float = 0.0
+    has_liveness_signal: bool = False
+
+
+class LMCacheDrivenTransferModule(InstanceLivenessTarget):
+    """Handles LMCache-driven KV cache transfer operations.
+
+    Owns GPU context registrations and provides handlers for
+    register, unregister, store, and retrieve of GPU KV caches.
+
+    Args:
+        ctx: The shared engine context.
+    """
+
+    def __init__(self, ctx: MPCacheServerContext) -> None:
+        self._ctx = ctx
+        self._cache_contexts: dict[int, ContextEntry] = {}
+        # Guards all reads/writes of _cache_contexts. The reaper mutates it
+        # off the MQ main loop, so register/unregister/store/retrieve and
+        # report_status all serialize through this lock. Held only for dict
+        # ops -- never across context creation, layout-registry calls, or
+        # empty_cache (leaf-lock invariant: no thread holds two locks).
+        self._lock = threading.Lock()
+
+        # Route finish_write / finish_read_prefetched through a C++ host
+        # callback so the driver thread doesn't acquire the GIL.
+        self._device_host_func_dispatcher = DeviceHostFuncDispatcher()
+        self._device_host_func_dispatcher.register(
+            "finish_write",
+            self._ctx.storage_manager.finish_write,
+            payload_type=list[ObjectKey],
+        )
+        self._device_host_func_dispatcher.register(
+            "finish_read_prefetched",
+            self._ctx.storage_manager.finish_read_prefetched,
+            payload_type=list[ObjectKey],
+        )
+        self._device_host_func_dispatcher.start()
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        return self._ctx
+
+    def get_and_touch_context_entry(self, instance_id: int) -> ContextEntry | None:
+        """Return the entry for ``instance_id``, refreshing its last-seen time.
+
+        The refresh keeps an actively transferring worker from being reaped
+        even if its PINGs are briefly delayed. Does not latch the
+        ping-proven flag -- only PINGs do that.
+
+        Args:
+            instance_id: The worker instance ID.
+
+        Returns:
+            The entry, or None if the instance is not (or no longer) tracked.
+        """
+        now = time.monotonic()
+        with self._lock:
+            entry = self._cache_contexts.get(instance_id)
+            if entry is not None:
+                entry.last_seen = now
+            return entry
+
+    def context_entries_snapshot(self) -> dict[int, ContextEntry]:
+        """Return a shallow copy of the registry for iteration or status.
+
+        Returns:
+            A new dict mapping instance ID to entry; does not refresh
+            last-seen times.
+        """
+        with self._lock:
+            return dict(self._cache_contexts)
+
+    def touch_instance(self, instance_id: int) -> None:
+        """Refresh the worker's last-seen time and mark it ping-proven.
+
+        A no-op if the instance is not tracked.
+
+        Args:
+            instance_id: The worker instance ID.
+        """
+        now = time.monotonic()
+        with self._lock:
+            entry = self._cache_contexts.get(instance_id)
+            if entry is not None:
+                entry.last_seen = now
+                entry.has_liveness_signal = True
+
+    def tracked_instance_count(self) -> int:
+        """Return the number of currently registered instances."""
+        with self._lock:
+            return len(self._cache_contexts)
+
+    def reap_stale_instances(
+        self, reap_timeout_s: float, registration_grace_s: float
+    ) -> list[int]:
+        """Reap GPU registrations that have gone silent.
+
+        A ping-proven instance is judged against ``reap_timeout_s``; one
+        that has never pinged against the larger ``registration_grace_s``.
+
+        Args:
+            reap_timeout_s: Silence budget for ping-proven instances.
+            registration_grace_s: Silence budget for never-pinged instances.
+
+        Returns:
+            The instance IDs reaped this scan.
+        """
+        now = time.monotonic()
+        reaped: list[tuple[int, ContextEntry]] = []
+        with self._lock:
+            stale_ids = [
+                iid
+                for iid, entry in self._cache_contexts.items()
+                if now - entry.last_seen
+                > (
+                    reap_timeout_s
+                    if entry.has_liveness_signal
+                    else registration_grace_s
+                )
+            ]
+            for iid in stale_ids:
+                reaped.append((iid, self._cache_contexts.pop(iid)))
+        for iid, entry in reaped:
+            self._release_entry(entry)
+            logger.warning(
+                "Reaped GPU instance %d: silent for %.1fs (pinged=%s)",
+                iid,
+                now - entry.last_seen,
+                entry.has_liveness_signal,
+            )
+        return [iid for iid, _ in reaped]
+
+    def _release_entry(self, entry: ContextEntry) -> None:
+        """Release resources for a popped entry (run outside the lock).
+
+        Args:
+            entry: The entry removed from the registry.
+        """
+        entry.cache_context.close()
+        self._ctx.layout_desc_registry.unregister(entry.model_name, entry.world_size)
+        torch_dev.empty_cache()
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves.
+
+        Returns:
+            A list of HandlerSpec entries mapping request types to
+            their handler callables and thread pool assignments.
+        """
+        return [
+            HandlerSpec(
+                RequestType.REGISTER_KV_CACHE,
+                self.register_kv_cache,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.UNREGISTER_KV_CACHE,
+                self.unregister_kv_cache,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(
+                RequestType.STORE,
+                self.store,
+                ThreadPoolType.AFFINITY,
+            ),
+            HandlerSpec(
+                RequestType.RETRIEVE,
+                self.retrieve,
+                ThreadPoolType.AFFINITY,
+            ),
+        ]
+
+    def report_status(self) -> dict:
+        """Return GPU transfer module status information.
+
+        Returns:
+            A dict containing registered GPU instance IDs and
+            per-instance KV cache layout metadata.
+        """
+        registered_gpu_ids: list[int] = []
+        cache_context_meta: dict[str, dict] = {}
+
+        for instance_id, entry in self.context_entries_snapshot().items():
+            registered_gpu_ids.append(instance_id)
+            ctx = entry.cache_context
+            cache_context_meta[str(instance_id)] = {
+                "model_name": entry.model_name,
+                "world_size": entry.world_size,
+                "kv_cache_layout": ctx.report_status(),
+            }
+
+        return {
+            "registered_gpu_ids": registered_gpu_ids,
+            "cache_context_meta": cache_context_meta,
+        }
+
+    def close(self) -> None:
+        """Release GPU resources owned by this module."""
+        # Stop the drain thread before storage_manager.close() so any
+        # in-flight completions reach a live storage manager.
+        self._device_host_func_dispatcher.stop()
+
+        with self._lock:
+            entries = list(self._cache_contexts.values())
+            self._cache_contexts.clear()
+        for entry in entries:
+            entry.cache_context.close()
+        if entries:
+            torch_dev.empty_cache()
+
+    def register_kv_cache(
+        self,
+        instance_id: int,
+        kv_caches: KVCache,
+        model_name: str,
+        world_size: int,
+        engine_type: EngineType,
+        layout_hints: LayoutHints,
+        engine_group_infos: list[EngineGroupInfo],
+    ) -> None:
+        """Register the KV cache tensors for a given GPU instance ID.
+
+        Args:
+            instance_id: The GPU instance ID (such as PID).
+            kv_caches: The KV cache tensor wrappers from the
+                serving engine.
+            model_name: The name of the model associated with this KV cache.
+            world_size: The world size associated with this KV cache.
+            engine_type: Which serving engine produced the caches.
+                Forwarded to GPUCacheContext for format detection.
+            layout_hints: See LayoutHints.  Forwarded to
+                GPUCacheContext for GPU KV format detection.
+            engine_group_infos: Engine-neutral KV cache group metadata
+                (already msgspec-decoded by the message queue).
+        """
+        now = time.monotonic()
+        # NOOP-register: an already-registered instance (e.g. a recovering
+        # worker re-registering on its first ping) refreshes its last-seen
+        # time so a stale entry is not reaped right after recovery. REGISTER
+        # is SYNC-serialized on the MQ main loop, so it is the sole inserter.
+        with self._lock:
+            existing = self._cache_contexts.get(instance_id)
+            if existing is not None:
+                existing.last_seen = now
+                logger.info(
+                    "Instance %d already registered; refreshing liveness",
+                    instance_id,
+                )
+                return
+
+        # Build the context and layout descriptor outside the lock.
+        cache_context = create_cache_context(
+            kv_caches,
+            self._ctx.chunk_size,
+            layout_hints=layout_hints or None,
+            engine_group_infos=engine_group_infos,
+            engine_type=engine_type,
+            separate_object_groups=self._ctx.separate_object_groups,
+            full_sw_kv=self._ctx.full_sw_kv,
+        )
+        layout_desc = get_layout_desc(
+            cache_context, self._ctx.chunk_size, object_group_id=0
+        )
+        kv_groups_manager = cache_context.kv_layer_groups_manager
+        attn_desc = kv_groups_manager.get_attn_desc()
+        self._ctx.layout_desc_registry.register(
+            model_name, world_size, layout_desc, attn_desc
+        )
+
+        with self._lock:
+            self._cache_contexts[instance_id] = ContextEntry(
+                cache_context=cache_context,
+                model_name=model_name,
+                world_size=world_size,
+                last_seen=now,
+                has_liveness_signal=False,
+            )
+
+        logger.info(
+            "Registered KV cache for GPU ID %d with %d layers",
+            instance_id,
+            cache_context.num_layers,
+        )
+
+    def unregister_kv_cache(self, instance_id: int) -> None:
+        """Unregister the KV cache tensors for a given GPU instance ID.
+
+        Args:
+            instance_id: The GPU instance ID (such as PID).
+        """
+        with self._lock:
+            entry = self._cache_contexts.pop(instance_id, None)
+        if entry is None:
+            logger.warning(
+                "No registered GPU context found for instance ID %d", instance_id
+            )
+            return
+
+        self._release_entry(entry)
+        logger.info("Unregistered KV cache for GPU ID %d", instance_id)
+
+    @_lmcache_nvtx_annotate
+    def store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        gpu_block_ids: list[list[int]],
+        event_ipc_handle: bytes,
+    ) -> tuple[bytes, bool]:
+        """Store the GPU KV cache blocks to CPU.
+
+        Args:
+            key: The IPC key for the KV cache blocks.
+                Must have worker_id != None (worker store operation).
+            instance_id: The GPU instance ID (such as PID).
+            gpu_block_ids: GPU block IDs to store, indexed by LMCache KV
+                group index.
+            event_ipc_handle: The IPC handle of the event to wait on.
+
+        Returns:
+            A tuple where the first element is the IPC handle of the event
+            that signals the completion of the store operation, and the second
+            element indicates whether the store operation completed without a
+            fatal error (not whether every requested chunk was stored; see
+            Notes).
+
+        Raises:
+            ValueError: If no GPU context is registered for the given instance ID.
+            RuntimeError: If the backend does not support IPC event handles.
+
+        Notes:
+            All-or-nothing. If ``gpu_block_ids`` do not fully cover every chunk
+            ``key`` resolves to for every LMCache group (e.g. a caller/protocol
+            bug), or a copy fails, the whole store is skipped and nothing is
+            committed (logged at WARNING); a subsequent retrieve simply misses
+            and the engine recomputes. The boolean result reports whether the
+            store completed without such a failure.
+        """
+        st = time.perf_counter()
+
+        entry = self.get_and_touch_context_entry(instance_id)
+        if entry is None:
+            raise ValueError(f"No GPU context registered for instance ID {instance_id}")
+        cache_context = entry.cache_context
+        model_name = entry.model_name
+
+        num_object_groups = cache_context.kv_layer_groups_manager.num_object_groups
+        obj_keys_per_obj_group = self._ctx.resolve_obj_keys(
+            key, list(range(num_object_groups))
+        )
+        num_chunks = len(obj_keys_per_obj_group[0])
+
+        # NOTE: different engine groups may have different block sizes, so
+        # ``blocks_per_chunk[i]`` is the number of blocks in one chunk for
+        # group ``i``.
+        blocks_per_chunk = [
+            cache_context.calculate_num_blocks(self._ctx.chunk_size, group_idx)
+            for group_idx in range(
+                cache_context.kv_layer_groups_manager.num_kernel_groups
+            )
+        ]
+
+        with (
+            torch_dev.device(cache_context.device),
+            torch_dev.stream(cache_context.stream),
+        ):
+            check_interprocess_event_support()
+            event = torch_dev.Event(interprocess=True)
+
+            # Fail closed: every LMCache group must have block IDs covering all
+            # chunks. A short list (e.g. a caller/protocol bug) would otherwise
+            # drive the transfer kernel to read out-of-bounds GPU memory, so skip
+            # the whole store and commit nothing rather than caching a partial or
+            # garbage entry. A later request can store it once the block IDs are
+            # complete. Checked on the raw block ids, before cutting drops the
+            # per-chunk blocks that sliding-window groups do not need.
+            if any(
+                len(group_block_ids) < num_chunks * bpc
+                for group_block_ids, bpc in zip(
+                    gpu_block_ids, blocks_per_chunk, strict=True
+                )
+            ):
+                logger.warning(
+                    "STORE block ID underflow for request_id=%s: each group needs "
+                    "num_chunks * blocks_per_chunk block IDs for %d chunks "
+                    "(per-group blocks_per_chunk=%s); skipping the store.",
+                    key.request_id,
+                    num_chunks,
+                    blocks_per_chunk,
+                )
+                event.record()
+                return event.ipc_handle(), False
+
+            block_ids_per_group_gpu = downsample_and_stage_block_ids(
+                cache_context, gpu_block_ids
+            )
+
+            if not hasattr(torch_dev.Event, "from_ipc_handle"):
+                raise RuntimeError(
+                    f"Backend '{torch_device_type}' does not support IPC event "
+                    "handles (Event.from_ipc_handle not available). "
+                    "Multiprocess IPC requires CUDA."
+                )
+            vllm_event = torch_dev.Event.from_ipc_handle(
+                cache_context.device, event_ipc_handle
+            )
+            vllm_event.wait(stream=cache_context.stream)
+
+            # CPU-synchronous sentinel: a GPU store is about to be enqueued.
+            # Must be published via publish() (not publish_on_stream) so the
+            # drain thread sees it before MP_REQUEST_END can race MP_STORE_END.
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.MP_STORE_SUBMITTED,
+                    session_id=key.request_id,
+                    metadata={"device": str(cache_context.device)},
+                )
+            )
+
+            self._ctx.event_bus.publish_on_stream(
+                cache_context.cupy_stream,
+                Event(
+                    event_type=EventType.MP_STORE_START,
+                    session_id=key.request_id,
+                    metadata={
+                        "device": str(cache_context.device),
+                        "engine_id": instance_id,
+                        "model_name": model_name,
+                    },
+                ),
+            )
+
+            reserved_dict: dict[ObjectKey, MemoryObj] = {}
+            all_dict: dict[ObjectKey, MemoryObj] = {}
+            total_bytes: int = 0
+            store_succeeded = False
+            try:
+                for obj_group_id in range(num_object_groups):
+                    obj_keys = obj_keys_per_obj_group[obj_group_id]
+                    layout_desc = get_layout_desc(
+                        cache_context,
+                        self._ctx.chunk_size,
+                        object_group_id=obj_group_id,
+                    )
+                    reserved_dict = self._ctx.storage_manager.reserve_write(
+                        obj_keys, layout_desc, "new"
+                    )
+                    all_dict.update(reserved_dict)
+                    if reserved_dict:
+                        total_bytes += next(
+                            iter(reserved_dict.values())
+                        ).get_size() * len(reserved_dict)
+
+                    # Keys not in reserved_dict (skipped by the storage manager)
+                    # become None entries; the helper skips them for D2H.
+                    memory_objs: list[MemoryObj | None] = [
+                        reserved_dict.get(obj_key) for obj_key in obj_keys
+                    ]
+
+                    # NOTE: batch_size must stay 1 for store.
+                    transfer_kv_per_object_group(
+                        cache_context,
+                        block_ids_per_group_gpu,
+                        memory_objs,
+                        object_group_id=obj_group_id,
+                        batch_size=1,
+                        skip_first_n_tokens=0,
+                        direction=lmc_ops.TransferDirection.D2H,
+                    )
+
+                store_succeeded = True
+            except Exception:
+                logger.exception("Cannot store keys due to exception")
+                return event.ipc_handle(), False
+            finally:
+                event.record()
+                # Fail closed: commit the reserved objects only when every chunk
+                # copied successfully; otherwise the whole store is skipped.
+                stored_count = len(all_dict) if store_succeeded else 0
+                if stored_count:
+                    submit_callback_to_stream(
+                        cache_context.cupy_stream,
+                        "finish_write",
+                        list(all_dict.keys()),
+                    )
+                else:
+                    total_bytes = 0
+                self._ctx.event_bus.publish_on_stream(
+                    cache_context.cupy_stream,
+                    Event(
+                        event_type=EventType.MP_STORE_END,
+                        session_id=key.request_id,
+                        metadata={
+                            "stored_count": stored_count,
+                            "device": str(cache_context.device),
+                            "engine_id": instance_id,
+                            "model_name": model_name,
+                            "total_bytes": total_bytes,
+                        },
+                    ),
+                )
+
+        ed = time.perf_counter()
+        if stored_count:
+            logger.info(
+                "Stored %d tokens in %.3f seconds",
+                num_chunks * self._ctx.chunk_size,
+                ed - st,
+            )
+        return event.ipc_handle(), True
+
+    @_lmcache_nvtx_annotate
+    def retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        gpu_block_ids: list[list[int]],
+        event_ipc_handle: bytes,
+        skip_first_n_tokens: int = 0,
+    ) -> tuple[bytes, bool]:
+        """Retrieve the CPU KV cache and put into GPU blocks.
+
+        Args:
+            key: The IPC key for the KV cache blocks.
+                Must have worker_id != None (worker retrieve operation).
+            instance_id: The GPU instance ID (such as PID).
+            gpu_block_ids: GPU block IDs to retrieve into, indexed by LMCache
+                KV group index.
+            event_ipc_handle: The IPC handle of the event to wait on.
+            skip_first_n_tokens: Number of tokens to skip writing at
+                the start of the retrieve range. This avoids overwriting
+                APC-shared GPU blocks that may be read concurrently by other
+                requests.
+
+        Returns:
+            A tuple where the first element is the IPC handle of the event
+            that signals the completion of the retrieve operation, and the
+            second element indicates whether the key was successfully retrieved.
+
+        Raises:
+            ValueError: If no GPU context is registered for the given instance ID.
+        """
+        st = time.perf_counter()
+
+        entry = self.get_and_touch_context_entry(instance_id)
+        if entry is None:
+            raise ValueError(f"No GPU context registered for instance ID {instance_id}")
+        cache_context = entry.cache_context
+        model_name = entry.model_name
+
+        num_object_groups = cache_context.kv_layer_groups_manager.num_object_groups
+        obj_keys_per_obj_group = self._ctx.resolve_obj_keys(
+            key, list(range(num_object_groups))
+        )
+        num_chunks = len(obj_keys_per_obj_group[0])
+
+        # CPU-synchronous sentinel: a GPU retrieve is about to be enqueued.
+        # Must be published via publish() (not publish_on_stream) so the
+        # drain thread sees it before MP_REQUEST_END can race MP_RETRIEVE_END.
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_SUBMITTED,
+                session_id=key.request_id,
+                metadata={"device": str(cache_context.device)},
+            )
+        )
+
+        self._ctx.event_bus.publish_on_stream(
+            cache_context.cupy_stream,
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id=key.request_id,
+                metadata={
+                    "device": str(cache_context.device),
+                    "engine_id": instance_id,
+                    "model_name": model_name,
+                },
+            ),
+        )
+
+        blocks_per_chunk = [
+            cache_context.calculate_num_blocks(self._ctx.chunk_size, group_idx)
+            for group_idx in range(
+                cache_context.kv_layer_groups_manager.num_kernel_groups
+            )
+        ]
+
+        with (
+            torch_dev.device(cache_context.device),
+            torch_dev.stream(cache_context.stream),
+        ):
+            check_interprocess_event_support()
+            event = torch_dev.Event(interprocess=True)
+
+            # Fail closed: a short block-id list would drive the transfer
+            # kernel to write out-of-bounds GPU memory. Checked on the raw
+            # block ids, before cutting drops the per-chunk blocks that
+            # sliding-window groups do not need.
+            if any(
+                len(group_block_ids) < num_chunks * bpc
+                for group_block_ids, bpc in zip(
+                    gpu_block_ids, blocks_per_chunk, strict=True
+                )
+            ):
+                logger.error(
+                    "RETRIEVE block ID underflow for request_id=%s: each group "
+                    "needs num_chunks * blocks_per_chunk block IDs for %d "
+                    "chunks (per-group blocks_per_chunk=%s); skipping the "
+                    "retrieve.",
+                    key.request_id,
+                    num_chunks,
+                    blocks_per_chunk,
+                )
+                event.record()
+                return event.ipc_handle(), False
+
+            # Cut and stage all block_ids to GPU once before the transfer
+            block_ids_per_group_gpu = downsample_and_stage_block_ids(
+                cache_context, gpu_block_ids
+            )
+
+            prefetched_keys: list[ObjectKey] = []
+            total_bytes = 0
+            try:
+                for obj_group_id in range(num_object_groups):
+                    obj_keys = obj_keys_per_obj_group[obj_group_id]
+                    with self._ctx.storage_manager.read_prefetched_results(
+                        obj_keys
+                    ) as memory_objs:
+                        if not memory_objs or len(memory_objs) != len(obj_keys):
+                            logger.error("Some keys not found during retrieve!")
+                            return event.ipc_handle(), False
+
+                        total_bytes += sum(mo.get_size() for mo in memory_objs)
+
+                        transfer_kv_per_object_group(
+                            cache_context,
+                            block_ids_per_group_gpu,
+                            memory_objs,
+                            object_group_id=obj_group_id,
+                            batch_size=cache_context.max_batch_size,
+                            skip_first_n_tokens=skip_first_n_tokens,
+                            direction=lmc_ops.TransferDirection.H2D,
+                        )
+                        # Extend only after the copy is enqueued: on exception,
+                        # read_prefetched_results releases this group's locks
+                        # itself, and a key must not be released twice.
+                        prefetched_keys.extend(obj_keys)
+            except Exception:
+                logger.exception("Cannot retrieve keys due to exception")
+                return event.ipc_handle(), False
+            finally:
+                event.record()
+                if prefetched_keys:
+                    submit_callback_to_stream(
+                        cache_context.cupy_stream,
+                        "finish_read_prefetched",
+                        prefetched_keys,
+                    )
+                self._ctx.event_bus.publish_on_stream(
+                    cache_context.cupy_stream,
+                    Event(
+                        event_type=EventType.MP_RETRIEVE_END,
+                        session_id=key.request_id,
+                        metadata={
+                            "retrieved_count": len(prefetched_keys),
+                            "device": str(cache_context.device),
+                            "engine_id": instance_id,
+                            "model_name": model_name,
+                            "cache_salt": key.cache_salt,
+                            "total_bytes": total_bytes,
+                        },
+                    ),
+                )
+        tokens_retrieved = num_chunks * self._ctx.chunk_size
+        ed = time.perf_counter()
+        logger.info(
+            "Retrieved %d tokens in %.3f seconds",
+            tokens_retrieved,
+            ed - st,
+        )
+
+        return event.ipc_handle(), True
diff --git a/lmcache/v1/multiprocess/modules/lookup.py b/lmcache/v1/multiprocess/modules/lookup.py
new file mode 100644
index 0000000..d2dd10d
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/lookup.py
@@ -0,0 +1,605 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LookupModule: lookup, prefetch polling, and session lifecycle."""
+
+# Standard
+from dataclasses import dataclass
+from functools import partial
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import (
+    ObjectKey,
+    PrefetchHandle,
+    ipc_key_to_object_keys,
+)
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.otel_init import register_gauge
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.protocol import RequestType
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+
+logger = init_logger(__name__)
+
+
+def compute_extra_count(
+    tp_size: int,
+    world_size: int,
+) -> int:
+    """Compute extra count for MLA multi-reader locking.
+
+    Non-MLA: each TP worker owns a distinct KV shard,
+      so each ObjectKey is retrieved by exactly 1
+      worker -> extra_count = 0.
+    MLA: TP does not split KV caches, all TP workers
+      share the same object. vLLM passes world_size
+      already divided by tp_size (e.g. world_size=1
+      for TP=4 PP=1), so ipc_keys_to_object_keys
+      only produces 1 ObjectKey per chunk.  All TP
+      workers retrieve that same ObjectKey, hence
+      extra_count = tp_size - 1.
+
+    Detection: tp > world_size means MLA (world_size
+    was divided by tp on the vLLM side).
+
+    Fallback: old vLLM (<= 0.8.5) does not send
+    tp_size (defaults to 1); we fall back to
+    world_size which gives extra_count = 0
+    (safe but may under-lock for MLA).
+
+    TODO: world_size currently carries an overloaded
+    meaning (total ranks for non-MLA vs total/tp for
+    MLA). Consider a dedicated field in the future.
+
+    Args:
+        tp_size: Tensor-parallel size from the client.
+        world_size: World size from the cache key.
+
+    Returns:
+        Number of extra count (0 for non-MLA).
+    """
+    tp = tp_size if tp_size > 1 else world_size
+    return tp - 1 if tp > world_size else 0
+
+
+def _get_prefix_hit_length(
+    found_prefix_len: int,
+    world_size: int,
+    num_object_groups: int,
+) -> int:
+    """Return the prefix hit length in chunks.
+
+    The chunk-major key layout packs ``world_size * num_object_groups`` keys per
+    chunk, so a fully-present prefix of ``found_prefix_len`` keys hits
+    ``found_prefix_len // (world_size * num_object_groups)`` chunks.
+
+    Args:
+        found_prefix_len: Length, in keys, of the contiguous found-key prefix.
+        world_size: Number of kv_rank shards per chunk.
+        num_object_groups: Number of object groups in the chunk-major layout.
+
+    Returns:
+        The prefix hit length in chunks (fully-present chunks of the prefix).
+
+    Example (2 object groups ``g0,g1``; 2 kv_ranks ``r0,r1`` -> 4 keys per
+    chunk). A found-key prefix of 6 keys covers one full chunk plus half the
+    next::
+
+        [c0g0r0, c0g0r1, c0g1r0, c0g1r1,   # chunk 0: fully present
+         c1g0r0, c1g0r1]                    # chunk 1: 2 of 4 -> partial, dropped
+
+    so ``found_prefix_len=6`` hits ``6 // (2 * 2) = 1`` whole chunk.
+
+    Note:
+        Correct only under full attention -- every object group present for
+        every hit chunk. Once sliding-window prefetch lands, the hit is no
+        longer a uniform contiguous key prefix and the hit length must come
+        from the fold's reported hit length instead.
+    """
+    return found_prefix_len // (world_size * num_object_groups)
+
+
+@dataclass
+class _PrefetchJob:
+    handle: PrefetchHandle
+    world_size: int
+    request_id: str
+    # Number of tokens submitted for lookup (denominator for the L1+L2
+    # token-level hit-rate metric).  Equals ``len(chunk_hashes) * chunk_size``
+    # on the happy path; 0 for early-exit paths (no GPU context matches
+    # or chunk_hashes is empty).  Consumed at ``MP_LOOKUP_PREFETCH_END``
+    # emission time in ``query_prefetch_status``.
+    requested_tokens: int
+    num_object_groups: int = 1
+    # Captured at lookup time so the ``MP_LOOKUP_PREFETCH_END`` event can
+    # carry them as labels.  ``model_name`` lets dashboards slice hit rate
+    # per model in multi-model deployments; ``cache_salt`` slices per
+    # tenant / isolation domain (an empty string means no salt set).
+    model_name: str = ""
+    cache_salt: str = ""
+
+
+class LookupModule:
+    """Handles lookup, prefetch polling, lock release, and session lifecycle.
+
+    Owns the prefetch-job bookkeeping (``_prefetch_jobs``) and exposes
+    handlers for the LOOKUP, QUERY_PREFETCH_STATUS,
+    QUERY_PREFETCH_LOOKUP_HITS, FREE_LOOKUP_LOCKS, and END_SESSION
+    request types.
+
+    Args:
+        ctx: Shared engine context providing storage manager, token hasher,
+            session manager, event bus, layout descriptor registry, and
+            chunk size.
+    """
+
+    def __init__(self, ctx: MPCacheServerContext) -> None:
+        self._ctx = ctx
+        self._prefetch_jobs: dict[str, _PrefetchJob] = {}
+        self._prefetch_job_lock = threading.Lock()
+        self._setup_metrics()
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        return self._ctx
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves.
+
+        Returns:
+            List of handler specs for lookup-related request types.
+        """
+        return [
+            HandlerSpec(RequestType.LOOKUP, self.lookup, ThreadPoolType.NORMAL),
+            HandlerSpec(
+                RequestType.QUERY_PREFETCH_STATUS,
+                self.query_prefetch_status,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.WAIT_PREFETCH_STATUS,
+                self.wait_prefetch_status,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.QUERY_PREFETCH_LOOKUP_HITS,
+                self.query_prefetch_lookup_hits,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.FREE_LOOKUP_LOCKS,
+                self.free_lookup_locks,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.END_SESSION,
+                self.end_session,
+                ThreadPoolType.NORMAL,
+            ),
+        ]
+
+    def report_status(self) -> dict[str, int]:
+        """Return module-specific status information.
+
+        Returns:
+            Dictionary with the count of active prefetch jobs.
+        """
+        return {
+            "active_prefetch_jobs": self._active_prefetch_count(),
+        }
+
+    def close(self) -> None:
+        """Release resources owned by this module (no-op)."""
+        pass
+
+    # -----------------------------------------------------------------
+    # Handlers
+    # -----------------------------------------------------------------
+
+    def lookup(
+        self,
+        key: IPCCacheServerKey,
+        tp_size: int,
+    ) -> None:
+        """Submit a prefix lookup.
+
+        Hashes the key, submits a prefetch task to the storage manager,
+        and registers the job under ``key.request_id`` for later polling
+        via query_prefetch_status.
+
+        Args:
+            key: Cache key with request_id embedded.
+            tp_size: Tensor-parallel size for MLA multi-reader locking.
+        """
+        model_name, world_size = key.model_name, key.world_size
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_START,
+                session_id=key.request_id,
+            )
+        )
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_START,
+                session_id=key.request_id,
+            )
+        )
+
+        layout_desc = self._ctx.layout_desc_registry.find(model_name, world_size)
+        if layout_desc is None:
+            logger.error(
+                "No GPU context found for model %s with world size %d during lookup!",
+                model_name,
+                world_size,
+            )
+            self._register_prefetch_job(
+                _PrefetchJob(
+                    handle=PrefetchHandle(
+                        prefetch_request_id=-1,
+                        external_request_id=key.request_id,
+                        l1_found_indices=(),
+                        total_requested_keys=0,
+                        submit_time=time.monotonic(),
+                    ),
+                    world_size=1,
+                    request_id=key.request_id,
+                    requested_tokens=0,
+                    model_name=model_name,
+                    cache_salt=key.cache_salt,
+                )
+            )
+            return
+
+        extra_count = compute_extra_count(tp_size, world_size)
+
+        chunk_hashes = self._ctx.token_hasher.compute_chunk_hashes(list(key.token_ids))
+        if not chunk_hashes:
+            self._register_prefetch_job(
+                _PrefetchJob(
+                    handle=PrefetchHandle(
+                        prefetch_request_id=-1,
+                        external_request_id=key.request_id,
+                        l1_found_indices=(),
+                        total_requested_keys=0,
+                        submit_time=time.monotonic(),
+                    ),
+                    world_size=1,
+                    request_id=key.request_id,
+                    requested_tokens=0,
+                    model_name=model_name,
+                    cache_salt=key.cache_salt,
+                )
+            )
+            return
+
+        # Total chunk-aligned tokens submitted for lookup; surfaces as the
+        # denominator of the L1+L2 token-level hit-rate via the
+        # ``requested_tokens`` field on ``MP_LOOKUP_PREFETCH_END``.  Sub-chunk
+        # trailing tokens are intentionally excluded — they cannot hit at
+        # chunk granularity.
+        requested_tokens = len(chunk_hashes) * self._ctx.chunk_size
+
+        # Guard with has_subscribers() to avoid allocating the metadata dict
+        # (including dtype/shape list comprehensions) when no subscriber is
+        # listening (e.g. lookup hash logger is disabled).
+        if self._ctx.event_bus.has_subscribers(EventType.MP_LOOKUP):
+            self._ctx.event_bus.publish(
+                Event(
+                    event_type=EventType.MP_LOOKUP,
+                    session_id=key.request_id,
+                    metadata={
+                        "request_id": key.request_id,
+                        "chunk_hashes": chunk_hashes,
+                        "model_name": model_name,
+                        "chunk_size": self._ctx.chunk_size,
+                        "seq_len": len(key.token_ids),
+                        "dtypes": [str(d) for d in layout_desc.dtypes],
+                        "shapes": [list(s) for s in layout_desc.shapes],
+                    },
+                )
+            )
+
+        session = self._ctx.session_manager.get_or_create(key.request_id)
+        session.set_tokens(list(key.token_ids))
+        session.lookup_ipc_key = key
+
+        # Lay keys out chunk-major across object groups (see
+        # _chunk_major_object_keys); pass the windows to the prefetch policy.
+        attn_desc = self._ctx.layout_desc_registry.find_attn_desc(
+            model_name, world_size
+        )
+        obj_keys = self._chunk_major_object_keys(key, chunk_hashes)
+
+        handle = self._ctx.storage_manager.submit_prefetch_task(
+            obj_keys,
+            layout_desc,
+            extra_count=extra_count,
+            external_request_id=key.request_id,
+            attn_desc=attn_desc,
+        )
+        self._register_prefetch_job(
+            _PrefetchJob(
+                handle=handle,
+                world_size=key.world_size,
+                request_id=key.request_id,
+                requested_tokens=requested_tokens,
+                num_object_groups=attn_desc.num_object_groups,
+                model_name=model_name,
+                cache_salt=key.cache_salt,
+            )
+        )
+
+    def query_prefetch_lookup_hits(
+        self,
+        request_id: str,
+    ) -> int | None:
+        """Query the number of hits for a prefetch request before it's finished.
+
+        Args:
+            request_id: The external request ID passed in the lookup key.
+
+        Returns:
+            The number of hits for the prefetched keys if the lookup phase is
+            done. None if the lookup phase is still in progress. 0 if the
+            request_id is unknown (already completed and consumed, or invalid).
+        """
+        with self._prefetch_job_lock:
+            job = self._prefetch_jobs.get(request_id)
+
+        if job is None:
+            logger.warning(
+                "Prefetch job for request %s not found (already completed or invalid)",
+                request_id,
+            )
+            return 0
+
+        found = self._ctx.storage_manager.query_prefetch_lookup_hits(job.handle)
+        if found is None:
+            return None
+
+        return _get_prefix_hit_length(found, job.world_size, job.num_object_groups)
+
+    def query_prefetch_status(
+        self,
+        request_id: str,
+    ) -> int | None:
+        """Poll the status of a prefetch job by request_id.
+
+        Returns the chunk count when the prefetch is complete, or None
+        if it is still in progress.  The job entry is automatically
+        removed once a non-None result is returned (exactly-once
+        semantics).
+
+        Args:
+            request_id: The external request ID passed in the lookup key.
+
+        Returns:
+            Chunk count (int) when done, None if still in progress,
+            0 if the request_id is unknown (already completed and consumed,
+            or invalid).
+        """
+        with self._prefetch_job_lock:
+            job = self._prefetch_jobs.get(request_id)
+        if job is None:
+            logger.warning(
+                "Prefetch job for request %s not found (already completed or invalid)",
+                request_id,
+            )
+            return 0
+
+        found = self._ctx.storage_manager.query_prefetch_status(job.handle)
+        if found is None:
+            return None
+
+        # NOTE(Kuntai): this assumes two things:
+        # 1. the world size is the same between keys
+        # 2. the lookup sort the keys in prefix order and breaks at the
+        #    first failure
+        found_count = _get_prefix_hit_length(
+            found.count_leading_ones(), job.world_size, job.num_object_groups
+        )
+
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id=job.request_id,
+                metadata={
+                    "found_count": found_count,
+                    "requested_tokens": job.requested_tokens,
+                    "hit_tokens": found_count * self._ctx.chunk_size,
+                    "model_name": job.model_name,
+                    "cache_salt": job.cache_salt,
+                },
+            )
+        )
+
+        with self._prefetch_job_lock:
+            self._prefetch_jobs.pop(request_id, None)
+
+        return found_count
+
+    def wait_prefetch_status(
+        self,
+        request_id: str,
+        timeout: float,
+    ) -> int | None:
+        """Block until a prefetch job completes, then return its chunk count.
+
+        Like query_prefetch_status, but waits for the daemon to publish the
+        result instead of returning None while the prefetch is still in
+        progress, so the caller does not have to busy-poll. The job entry is
+        removed once a non-None result is returned (exactly-once semantics).
+
+        Args:
+            request_id: The external request ID passed in the lookup key.
+            timeout: Maximum number of seconds to wait for the prefetch.
+
+        Returns:
+            Chunk count (int) when done, None if the wait timed out, 0 if the
+            request_id is unknown (already completed and consumed, or invalid).
+        """
+        with self._prefetch_job_lock:
+            job = self._prefetch_jobs.get(request_id)
+        if job is None:
+            logger.warning(
+                "Prefetch job for request %s not found (already completed or invalid)",
+                request_id,
+            )
+            return 0
+
+        if not self._ctx.storage_manager.wait_prefetch_status(job.handle, timeout):
+            return None
+        return self.query_prefetch_status(request_id)
+
+    def free_lookup_locks(
+        self,
+        key: IPCCacheServerKey,
+        tp_size: int,
+    ) -> None:
+        """Release read locks acquired during lookup.
+
+        Hashes are computed only for chunks in ``[start, end)`` to avoid
+        unnecessary work on tokens outside that range.
+        ``start`` and ``end`` must be aligned to ``chunk_size``; it is the
+        caller's responsibility to align the boundaries as desired.
+
+        Computes the extra reader count from ``tp_size`` and
+        ``world_size`` the same way :meth:`lookup` does, so
+        the correct number of locks is released.
+
+        Args:
+            key: Cache key whose read locks should be released.
+            tp_size: Tensor-parallel size for MLA
+                multi-reader locking.
+        """
+        chunk_hashes = self._ctx.token_hasher.compute_chunk_hashes(
+            list(key.token_ids), start=key.start, end=key.end
+        )
+        if not chunk_hashes:
+            return
+        # Release across every object group, mirroring lookup, which locks keys
+        # in every group; releasing only group 0 would leak the rest.
+        #
+        # NOTE: correct only for full attention, where every locked chunk is a
+        # hit chunk. Sliding-window groups do not retain chunks outside their
+        # window, so once SWA prefetch lands this must skip those chunks instead
+        # of releasing every one -- otherwise chunks the engine still holds can
+        # be over-released (e.g. window=512, LMCache hit 1024, vLLM hit 768 ->
+        # chunks 512..768 may leak). Revisit when sliding-window prefetch is on.
+        obj_keys = self._chunk_major_object_keys(key, chunk_hashes)
+
+        extra_count = compute_extra_count(tp_size, key.world_size)
+
+        self._ctx.storage_manager.finish_read_prefetched(
+            obj_keys, extra_count=extra_count
+        )
+
+    def end_session(self, request_id: str) -> None:
+        """Remove the session for a finished request.
+
+        Args:
+            request_id: The request ID whose session should be removed.
+        """
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_VLLM_END_SESSION,
+                metadata={"request_id": request_id},
+            )
+        )
+        session = self._ctx.session_manager.remove(request_id)
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=request_id,
+            )
+        )
+        if session is None:
+            logger.warning("Session %s not found, skipping touch", request_id)
+            return
+        if session.lookup_ipc_key is None:
+            logger.warning(
+                "Session %s has no lookup ipc key, skipping touch",
+                request_id,
+            )
+            return
+
+        chunk_hashes = [TokenHasher.hash_to_bytes(h) for h in session.get_hashes(0)]
+        obj_keys = self._chunk_major_object_keys(session.lookup_ipc_key, chunk_hashes)
+        # unified touch of all keys, which include retrieved and stored keys
+        # TODO(chunxiaozheng): when l2 is enabled, the prefetched keys from l2 are temp
+        #  and will be deleted after finish_read_prefetched, when we touch all keys,
+        #  these keys has been deleted and will not be touched.
+        self._ctx.storage_manager.touch_l1_keys(obj_keys)
+
+    # -----------------------------------------------------------------
+    # Internal helpers
+    # -----------------------------------------------------------------
+
+    def _chunk_major_object_keys(
+        self,
+        key: IPCCacheServerKey,
+        chunk_hashes: list[bytes],
+    ) -> list[ObjectKey]:
+        """Resolve the flat object-key list across all object groups,
+        chunk-major.
+
+        The object-group count is read from the layout registry for
+        ``key``'s ``(model_name, world_size)``. The keys are ordered
+        ``chunk -> object group -> kv_rank`` so that all keys belonging to one
+        chunk are contiguous; a leading-ones prefix over the flat list then maps
+        directly to a whole-chunk hit count. Callers that need the full key set
+        regardless of order (lock release, touch) use this too.
+
+        Example (2 chunks ``c0,c1``; 2 groups ``g0,g1``; 2 kv_ranks ``r0,r1``)::
+
+            [c0g0r0, c0g0r1, c0g1r0, c0g1r1,   # chunk 0: all groups, all ranks
+             c1g0r0, c1g0r1, c1g1r0, c1g1r1]   # chunk 1: ...
+
+        Args:
+            key: The IPC key (model/world/worker, salt).
+            chunk_hashes: Chunk hashes to resolve keys for.
+
+        Returns:
+            The chunk-major flattened list of object keys across all groups.
+        """
+        num_groups = self._ctx.layout_desc_registry.find_attn_desc(
+            key.model_name, key.world_size
+        ).num_object_groups
+        per_group = ipc_key_to_object_keys(key, chunk_hashes, list(range(num_groups)))
+        if num_groups == 1:
+            return per_group[0]
+        # Each per-group list is chunk-major / rank-minor of length
+        # len(chunk_hashes) * num_ranks; recover num_ranks to slice per chunk.
+        num_ranks = len(per_group[0]) // len(chunk_hashes) if chunk_hashes else 0
+        obj_keys: list[ObjectKey] = []
+        for chunk_idx in range(len(chunk_hashes)):
+            lo = chunk_idx * num_ranks
+            hi = lo + num_ranks
+            for group_keys in per_group:
+                obj_keys.extend(group_keys[lo:hi])
+        return obj_keys
+
+    def _register_prefetch_job(self, job: _PrefetchJob) -> None:
+        with self._prefetch_job_lock:
+            self._prefetch_jobs[job.request_id] = job
+
+    def _active_prefetch_count(self) -> int:
+        """Return the number of active prefetch jobs (thread-safe)."""
+        with self._prefetch_job_lock:
+            return len(self._prefetch_jobs)
+
+    def _setup_metrics(self) -> None:
+        """Register OTel observable gauges for lookup module metrics."""
+        _gauge = partial(register_gauge, "lmcache.mp_server")
+        _gauge(
+            "lmcache_mp.active_prefetch_jobs",
+            "Number of active prefetch jobs",
+            self._active_prefetch_count,
+        )
diff --git a/lmcache/v1/multiprocess/modules/management.py b/lmcache/v1/multiprocess/modules/management.py
new file mode 100644
index 0000000..6a6c49b
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/management.py
@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Management and utility operations for the MPCacheServer."""
+
+# Standard
+from collections.abc import Sequence
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.multiprocess.custom_types import BlockAllocationRecord
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    InstanceLivenessTarget,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.protocols.base import RequestType
+from lmcache.v1.periodic_thread import (
+    PeriodicThread,
+    ThreadLevel,
+    ThreadRunSummary,
+    create_periodic_thread,
+)
+
+logger = init_logger(__name__)
+
+
+class ManagementModule:
+    """Handles management and utility operations for the cache engine.
+
+    Owns the lock used during cache clearing and provides handlers for
+    ping, chunk-size queries, clear, debug, and block-allocation reporting.
+    Also owns the periodic reaper that evicts workers which have gone
+    silent, driving the injected liveness targets.
+
+    Args:
+        ctx: The shared engine context.
+        liveness_targets: Modules the reaper drives -- the transfer modules
+            whose per-instance registrations are refreshed on PING and scanned
+            for staleness, plus any state mirror (e.g. ``BlendV3Module``)
+            notified via ``drop_instance_state`` when an instance is reaped.
+        worker_reap_timeout_seconds: Silence budget for a ping-proven worker;
+            0 disables reaping (no thread is started).
+        worker_registration_grace_seconds: Silence budget for a worker that
+            registered but never pinged.
+    """
+
+    def __init__(
+        self,
+        ctx: MPCacheServerContext,
+        liveness_targets: Sequence[InstanceLivenessTarget] = (),
+        worker_reap_timeout_seconds: float = 0.0,
+        worker_registration_grace_seconds: float = 0.0,
+    ) -> None:
+        self._ctx = ctx
+        self._clear_lock = threading.Lock()
+        self._liveness_targets = tuple(liveness_targets)
+        self._reap_timeout = worker_reap_timeout_seconds
+        self._reap_grace = worker_registration_grace_seconds
+
+        # Periodic reaper, started only when reaping is enabled and there is
+        # something to scan. Scans every reap_timeout/4, so an instance is
+        # reaped between timeout and timeout + interval after its last signal.
+        self._reaper: PeriodicThread | None = None
+        if self._reap_timeout > 0 and self._liveness_targets:
+            reaper = create_periodic_thread(
+                name="lmcache-mp-worker-reaper",
+                interval=self._reap_timeout / 4,
+                execute_fn=self._reap_cycle,
+                level=ThreadLevel.MEDIUM,
+            )
+            reaper.start()
+            self._reaper = reaper
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        return self._ctx
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves.
+
+        Returns:
+            A list of HandlerSpec entries mapping request types to
+            their handler callables and thread pool assignments.
+        """
+        return [
+            HandlerSpec(RequestType.CLEAR, self.clear, ThreadPoolType.NORMAL),
+            HandlerSpec(
+                RequestType.GET_CHUNK_SIZE,
+                self.get_chunk_size,
+                ThreadPoolType.SYNC,
+            ),
+            HandlerSpec(RequestType.PING, self.ping, ThreadPoolType.NORMAL),
+            HandlerSpec(RequestType.NOOP, self.debug, ThreadPoolType.SYNC),
+            HandlerSpec(
+                RequestType.REPORT_BLOCK_ALLOCATION,
+                self.report_block_allocations,
+                ThreadPoolType.NORMAL,
+            ),
+        ]
+
+    def report_status(self) -> dict:
+        """Return module-specific status information.
+
+        Returns:
+            A dict with a ``worker_liveness`` summary when reaping targets
+            are present, otherwise empty.
+        """
+        if not self._liveness_targets:
+            return {}
+        tracked = sum(t.tracked_instance_count() for t in self._liveness_targets)
+        return {
+            "worker_liveness": {
+                "enabled": self._reaper is not None,
+                "reap_timeout_seconds": self._reap_timeout,
+                "registration_grace_seconds": self._reap_grace,
+                "tracked_instances": tracked,
+            }
+        }
+
+    def close(self) -> None:
+        """Stop the reaper, if one is running."""
+        if self._reaper is not None:
+            self._reaper.stop()
+
+    def ping(self, instance_id: int | None) -> bool:
+        """Respond to a ping and refresh the sender's liveness.
+
+        Args:
+            instance_id: The sender's worker instance ID, or None for an
+                untracked prober (the scheduler adapter). When not None, the
+                worker's last-seen time is refreshed on every liveness target.
+
+        Returns:
+            Always True.
+        """
+        if instance_id is not None:
+            for target in self._liveness_targets:
+                target.touch_instance(instance_id)
+        return True
+
+    def _reap_cycle(self) -> ThreadRunSummary:
+        """Run one reaper scan: reap stale workers, drop mirrored state.
+
+        Each reaped instance id is passed to ``drop_instance_state`` on every
+        target; it is a no-op for targets that mirror nothing for that id.
+
+        Returns:
+            A summary recording how many instances were reaped this scan.
+        """
+        reaped: list[int] = []
+        for target in self._liveness_targets:
+            reaped.extend(
+                target.reap_stale_instances(self._reap_timeout, self._reap_grace)
+            )
+        for instance_id in reaped:
+            for target in self._liveness_targets:
+                target.drop_instance_state(instance_id)
+        return ThreadRunSummary(success=True, message=f"reaped={len(reaped)}")
+
+    def get_chunk_size(self) -> int:
+        """Return the chunk size used for KV cache operations.
+
+        Returns:
+            The chunk size.
+        """
+        return self._ctx.chunk_size
+
+    def clear(self) -> None:
+        """Clear all stored KV cache data from the storage manager."""
+        with self._clear_lock:
+            self._ctx.storage_manager.memcheck()
+            self._ctx.storage_manager.clear(force=True)
+            self._ctx.storage_manager.memcheck()
+
+    def debug(self) -> str:
+        """Return a simple health-check string.
+
+        Returns:
+            The literal string ``"OK"``.
+        """
+        return "OK"
+
+    def report_block_allocations(
+        self,
+        instance_id: int,
+        model_name: str,
+        records: list[BlockAllocationRecord],
+    ) -> None:
+        """Publish vLLM block allocation records to the EventBus.
+
+        Args:
+            instance_id: The scheduler instance ID.
+            model_name: The model name from the adapter.
+            records: List of BlockAllocationRecord with per-request
+                block and token allocation deltas.
+        """
+        self._ctx.event_bus.publish(
+            Event(
+                event_type=EventType.MP_VLLM_BLOCK_ALLOCATION,
+                metadata={
+                    "instance_id": instance_id,
+                    "model_name": model_name,
+                    "records": records,
+                },
+            )
+        )
diff --git a/lmcache/v1/multiprocess/modules/p2p_controller.py b/lmcache/v1/multiprocess/modules/p2p_controller.py
new file mode 100644
index 0000000..7895d90
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/p2p_controller.py
@@ -0,0 +1,573 @@
+# SPDX-License-Identifier: Apache-2.0
+"""P2PController: peer discovery, adapter lifecycle, and lookup serving."""
+
+# Standard
+from dataclasses import dataclass
+from enum import Enum
+from functools import partial
+import threading
+
+# Third Party
+import httpx
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchHandle,
+)
+from lmcache.v1.distributed.l2_adapters.p2p_l2_adapter import P2PL2AdapterConfig
+from lmcache.v1.distributed.transfer_channel import (
+    delete_transfer_channel_context,
+    initialize_transfer_channel_context,
+)
+from lmcache.v1.distributed.transfer_channel.api import TransferChannelAddress
+from lmcache.v1.mp_observability.otel_init import register_gauge
+from lmcache.v1.multiprocess.config import CoordinatorConfig, P2PConfig
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    HandlerSpec,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.protocol import RequestType
+from lmcache.v1.periodic_thread import (
+    PeriodicThread,
+    ThreadLevel,
+    ThreadRunSummary,
+    create_periodic_thread,
+)
+
+logger = init_logger(__name__)
+
+# Sentinel address for keys that were not found (or fell past the L1 prefix).
+_INVALID_ADDRESS = TransferChannelAddress(offset=-1, size=0)
+
+# Consecutive missed polls a peer may be absent before its adapter is removed.
+_MAX_MISSES = 3
+
+
+class _P2PState(Enum):
+    """Registration state of this instance as seen by the coordinator."""
+
+    REGISTERED = "registered"
+    DISCONNECTED = "disconnected"
+    UNREGISTERED = "unregistered"
+
+
+@dataclass
+class _PeerInstance:
+    """A peer's P2P-relevant connection info parsed from ``GET /instances``."""
+
+    instance_id: str
+    ip: str
+    p2p_advertised_url: str
+    mq_port: int
+
+
+@dataclass
+class _PeerAdapter:
+    """Bookkeeping for a P2P L2 adapter created for a single peer."""
+
+    adapter_id: int
+    ip: str
+    p2p_advertised_url: str
+    mq_port: int
+    consecutive_misses: int = 0
+
+
+@dataclass
+class _P2PLookupJob:
+    handle: PrefetchHandle
+    """ The handle returned by the storage manager """
+
+    keys: list[ObjectKey]
+    """ The object keys submitted for this lookup, in request order """
+
+
+class P2PController:
+    """Serves lookup requests from peers and maintains one L2 adapter per peer.
+
+    P2P is enabled when ``p2p_config`` carries an advertise URL; otherwise the
+    controller only answers lookup/unlock RPCs.
+
+    Args:
+        ctx: Shared engine context providing the storage manager and friends.
+        p2p_config: Peer-to-peer configuration; inert when its advertise URL is
+            empty.
+        coordinator_config: Coordinator connection used for peer discovery.
+        instance_id: Stable id of this instance, used to exclude itself from the
+            discovered peer set.
+    """
+
+    def __init__(
+        self,
+        ctx: MPCacheServerContext,
+        p2p_config: P2PConfig,
+        coordinator_config: CoordinatorConfig,
+        instance_id: str,
+    ) -> None:
+        self._ctx = ctx
+        self._p2p_config = p2p_config
+        self._instance_id = instance_id
+        self._next_task_id = 0
+        self._jobs: dict[int, _P2PLookupJob] = {}
+        self._job_lock = threading.Lock()
+
+        # Orchestration state (guarded by _orch_lock; written only by the poll
+        # thread, read by report_status).
+        self._orch_lock = threading.Lock()
+        self._state = _P2PState.UNREGISTERED
+        self._adapters: dict[str, _PeerAdapter] = {}
+
+        self._instances_url = ""
+        self._http_client: httpx.Client | None = None
+        self._poll_thread: PeriodicThread | None = None
+
+        if p2p_config.enabled:
+            self._start_orchestration(coordinator_config)
+
+        self._setup_metrics()
+
+    def _start_orchestration(self, coordinator_config: CoordinatorConfig) -> None:
+        """Initialize the transfer channel and start the peer-poll thread.
+
+        Args:
+            coordinator_config: Coordinator connection used for peer discovery.
+        """
+        initialize_transfer_channel_context(
+            self._p2p_config.transfer_engine,
+            self._ctx.storage_manager.l1_memory_desc,
+            listen_url=self._p2p_config.effective_listen_url,
+            advertise_url=self._p2p_config.advertise_url,
+        )
+        self._instances_url = coordinator_config.url.rstrip("/") + "/instances"
+        timeout = max(1.0, coordinator_config.heartbeat_interval)
+        self._http_client = httpx.Client(timeout=timeout)
+        self._poll_thread = create_periodic_thread(
+            name="p2p-controller-thread",
+            interval=coordinator_config.heartbeat_interval,
+            execute_fn=self._poll_cycle,
+            level=ThreadLevel.MEDIUM,
+        )
+        self._poll_thread.start()
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context. Exposed for testing only."""
+        return self._ctx
+
+    def get_handlers(self) -> list[HandlerSpec]:
+        """Return handler specs for all request types this module serves.
+
+        Returns:
+            List of handler specs for lookup-related request types.
+        """
+        return [
+            HandlerSpec(
+                RequestType.P2P_LOOKUP_AND_LOCK,
+                self.p2p_lookup_and_lock,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.P2P_QUERY_LOOKUP_RESULTS,
+                self.p2p_query_lookup_results,
+                ThreadPoolType.NORMAL,
+            ),
+            HandlerSpec(
+                RequestType.P2P_UNLOCK_OBJECTS,
+                self.p2p_unlock_objects,
+                ThreadPoolType.NORMAL,
+            ),
+        ]
+
+    def report_status(self) -> dict[str, object]:
+        """Return module-specific status information.
+
+        Returns:
+            Dictionary with the active lookup-job count, the P2P registration
+            state, and the set of connected peer instance ids.
+        """
+        with self._orch_lock:
+            state = self._state.value
+            peers = sorted(self._adapters.keys())
+        return {
+            "active_p2p_lookup_jobs": self._active_job_count(),
+            "p2p_enabled": self._p2p_config.enabled,
+            "p2p_state": state,
+            "p2p_peer_count": len(peers),
+            "p2p_peers": peers,
+        }
+
+    def close(self) -> None:
+        """Stop the poll thread and release peer adapters and the channel."""
+        if self._poll_thread is not None:
+            self._poll_thread.stop()
+            self._poll_thread = None
+
+        for peer_id in list(self._adapters.keys()):
+            self._remove_adapter(peer_id)
+
+        if self._http_client is not None:
+            self._http_client.close()
+            self._http_client = None
+
+        if self._p2p_config.enabled:
+            delete_transfer_channel_context()
+
+    # -----------------------------------------------------------------
+    # RPC Handlers
+    # -----------------------------------------------------------------
+
+    def p2p_lookup_and_lock(
+        self,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+    ) -> int:
+        """Submit a lookup and lock.
+
+        After L2 prefetch is enabled, the found chunks will be feteched
+        from L2 to L1.
+
+        Args:
+            keys: the list of object keys to look up and lock.
+            layout_desc: memory layout description of the objects.
+
+        Returns:
+            A unique task id (int) for querying the lookup status later
+        """
+        with self._job_lock:
+            task_id = self._next_task_id
+            self._next_task_id += 1
+
+        # NOTE: skip_l2=True -- only objects already resident in L1 are locked.
+        handle = self._ctx.storage_manager.submit_prefetch_task(
+            keys,
+            layout_desc,
+            external_request_id=f"p2p-{task_id}",
+            skip_l2=True,
+        )
+
+        with self._job_lock:
+            self._jobs[task_id] = _P2PLookupJob(handle=handle, keys=keys)
+
+        logger.debug(
+            "P2P lookup submitted: task_id=%d, %d keys, %d L1 prefix hits",
+            task_id,
+            len(keys),
+            len(handle.l1_found_indices),
+        )
+        return task_id
+
+    def p2p_query_lookup_results(
+        self,
+        task_id: int,
+    ) -> list[TransferChannelAddress] | None:
+        """Query the results of the lookup request specified by the task ID.
+
+        Returning a list of TransferChannelAddress objects indicates when the
+        lookup is completed. None indicates the lookup has not completed yet.
+
+        The returned list will always have the same length as the number of
+        keys submitted in the corresponding p2p_lookup_and_lock call. For
+        objects that is not found, the corresponding TransferChannelAddress
+        will have an invalid offset (negative value).
+
+        Args:
+            task_id: The unique task ID returned by p2p_lookup_and_lock.
+
+        Returns:
+            A list of TransferChannelAddress objects if the lookup is complete,
+            or None if the lookup is still in progress or the result has been
+            queried. (Exactly once request)
+        """
+        with self._job_lock:
+            job = self._jobs.get(task_id)
+        if job is None:
+            logger.warning(
+                "P2P lookup job %d not found (already consumed or invalid)",
+                task_id,
+            )
+            return None
+
+        found = self._ctx.storage_manager.query_prefetch_status(job.handle)
+        if found is None:
+            # Still in progress (only possible once L2 prefetch is enabled).
+            return None
+
+        addresses = self._build_addresses(job, found.count_leading_ones())
+
+        with self._job_lock:
+            self._jobs.pop(task_id, None)
+        return addresses
+
+    def p2p_unlock_objects(
+        self,
+        keys: list[ObjectKey],
+    ) -> None:
+        """Unlock the specified object keys.
+
+        Args:
+            keys: the list of object keys to unlock.
+        """
+        if not keys:
+            return
+        self._ctx.storage_manager.finish_read_prefetched(keys)
+
+    # -----------------------------------------------------------------
+    # Internal helpers
+    # -----------------------------------------------------------------
+
+    def _build_addresses(
+        self,
+        job: _P2PLookupJob,
+        hit_count: int,
+    ) -> list[TransferChannelAddress]:
+        """Build the per-key transfer addresses for a completed lookup.
+
+        The first ``hit_count`` keys form the locked L1 prefix; their addresses
+        are read via ``unsafe_read``. Every remaining key gets an invalid
+        address.
+        """
+        addresses = [_INVALID_ADDRESS] * len(job.keys)
+        if hit_count == 0:
+            return addresses
+
+        found_keys = job.keys[:hit_count]
+        good_keys, good_objs = self._ctx.storage_manager.unsafe_read(found_keys)
+        obj_by_key = dict(zip(good_keys, good_objs, strict=True))
+
+        for i, key in enumerate(found_keys):
+            obj = obj_by_key.get(key)
+            if obj is None:
+                # Locked but unreadable (e.g. evicted under a race); leave it
+                # marked invalid so the peer skips it.
+                continue
+            addresses[i] = TransferChannelAddress(
+                offset=obj.shm_offset,
+                size=obj.shm_byte_length,
+            )
+        return addresses
+
+    # -----------------------------------------------------------------
+    # Orchestration (poll thread)
+    # -----------------------------------------------------------------
+
+    def _poll_cycle(self) -> ThreadRunSummary:
+        """Run one discovery cycle: poll the coordinator and reconcile adapters.
+
+        Returns:
+            A summary of the cycle's resulting state and adapter changes.
+        """
+        try:
+            instances = self._fetch_instances()
+        except httpx.TimeoutException:
+            return self._apply_state(_P2PState.DISCONNECTED, {})
+        except (httpx.HTTPError, ValueError) as e:
+            logger.warning("P2P instance discovery failed: %s", e)
+            return self._apply_state(_P2PState.UNREGISTERED, {})
+        except Exception:
+            logger.exception("Unexpected error during P2P instance discovery")
+            return self._apply_state(_P2PState.UNREGISTERED, {})
+
+        if not self._is_self_registered(instances):
+            return self._apply_state(_P2PState.UNREGISTERED, {})
+
+        upstream = {
+            inst.instance_id: inst
+            for inst in instances
+            if inst.instance_id != self._instance_id
+            and inst.p2p_advertised_url
+            and inst.ip
+            and inst.mq_port
+        }
+        return self._apply_state(_P2PState.REGISTERED, upstream)
+
+    def _fetch_instances(self) -> list[_PeerInstance]:
+        """Fetch and parse the coordinator's active-instance list.
+
+        Returns:
+            The parsed peer instances.
+
+        Raises:
+            httpx.HTTPError: If the request fails or returns a non-2xx status.
+            ValueError: If the response body is not the expected shape.
+        """
+        assert self._http_client is not None
+        response = self._http_client.get(self._instances_url)
+        response.raise_for_status()
+        body = response.json()
+        if not isinstance(body, dict) or not isinstance(body.get("instances"), list):
+            raise ValueError("malformed /instances response")
+        instances: list[_PeerInstance] = []
+        for raw in body["instances"]:
+            instance_id = raw.get("instance_id", "")
+            if not instance_id:
+                continue
+            instances.append(
+                _PeerInstance(
+                    instance_id=instance_id,
+                    ip=raw.get("ip", ""),
+                    p2p_advertised_url=raw.get("p2p_advertised_url", ""),
+                    mq_port=int(raw.get("mq_port", 0) or 0),
+                )
+            )
+        return instances
+
+    def _is_self_registered(self, instances: list[_PeerInstance]) -> bool:
+        """Return whether this instance appears in ``instances`` with our URL.
+
+        Args:
+            instances: The peer instances parsed from the coordinator.
+
+        Returns:
+            ``True`` if our instance id is present and advertises our URL.
+        """
+        return any(
+            inst.instance_id == self._instance_id
+            and inst.p2p_advertised_url == self._p2p_config.advertise_url
+            for inst in instances
+        )
+
+    def _apply_state(
+        self,
+        state: _P2PState,
+        upstream: dict[str, _PeerInstance],
+    ) -> ThreadRunSummary:
+        """Record the new state and reconcile adapters against ``upstream``.
+
+        Args:
+            state: The registration state derived from this cycle.
+            upstream: Peer instances to maintain adapters for (empty unless
+                registered).
+
+        Returns:
+            A summary describing the state and adapter changes this cycle.
+        """
+        with self._orch_lock:
+            self._state = state
+        added, removed = self._reconcile(upstream)
+        return ThreadRunSummary(
+            success=True,
+            message=(
+                f"state={state.value} peers={len(upstream)} "
+                f"added={added} removed={removed}"
+            ),
+        )
+
+    def _reconcile(self, upstream: dict[str, _PeerInstance]) -> tuple[int, int]:
+        """Bring the local peer adapters in line with ``upstream``.
+
+        Args:
+            upstream: The peers that should each have a live adapter.
+
+        Returns:
+            A ``(added, removed)`` count of adapter changes this cycle.
+        """
+        added = 0
+        removed = 0
+        for peer_id, inst in upstream.items():
+            current = self._adapters.get(peer_id)
+            if current is None:
+                if self._add_adapter(inst):
+                    added += 1
+            elif self._peer_changed(current, inst):
+                self._remove_adapter(peer_id)
+                removed += 1
+                if self._add_adapter(inst):
+                    added += 1
+            else:
+                current.consecutive_misses = 0
+
+        for peer_id in list(self._adapters.keys()):
+            if peer_id in upstream:
+                continue
+            adapter = self._adapters[peer_id]
+            adapter.consecutive_misses += 1
+            if adapter.consecutive_misses > _MAX_MISSES:
+                self._remove_adapter(peer_id)
+                removed += 1
+        return added, removed
+
+    @staticmethod
+    def _peer_changed(adapter: _PeerAdapter, inst: _PeerInstance) -> bool:
+        """Return whether a peer's advertised connection info changed.
+
+        Args:
+            adapter: The currently tracked adapter for the peer.
+            inst: The peer's freshly discovered info.
+
+        Returns:
+            ``True`` if any connection field differs.
+        """
+        return (
+            adapter.p2p_advertised_url != inst.p2p_advertised_url
+            or adapter.ip != inst.ip
+            or adapter.mq_port != inst.mq_port
+        )
+
+    def _add_adapter(self, inst: _PeerInstance) -> bool:
+        """Create and register a peer L2 adapter for ``inst``.
+
+        Args:
+            inst: The peer to connect to.
+
+        Returns:
+            ``True`` if the adapter was created and tracked.
+        """
+        config = P2PL2AdapterConfig(
+            peer_mq_server_url=f"tcp://{inst.ip}:{inst.mq_port}",
+            peer_transfer_channel_server_url=inst.p2p_advertised_url,
+            lookup_timeout_s=self._p2p_config.lookup_timeout,
+            load_timeout_s=self._p2p_config.load_timeout,
+        )
+        try:
+            adapter_id = self._ctx.storage_manager.add_l2_adapter(config)
+        except Exception:
+            logger.exception("Failed to add P2P adapter for peer %s", inst.instance_id)
+            return False
+        with self._orch_lock:
+            self._adapters[inst.instance_id] = _PeerAdapter(
+                adapter_id=adapter_id,
+                ip=inst.ip,
+                p2p_advertised_url=inst.p2p_advertised_url,
+                mq_port=inst.mq_port,
+            )
+        logger.debug(
+            "Added P2P adapter %d for peer %s (%s)",
+            adapter_id,
+            inst.instance_id,
+            inst.p2p_advertised_url,
+        )
+        return True
+
+    def _remove_adapter(self, peer_id: str) -> None:
+        """Drain and remove the peer L2 adapter for ``peer_id``.
+
+        Args:
+            peer_id: Instance id of the peer whose adapter to remove.
+        """
+        with self._orch_lock:
+            adapter = self._adapters.pop(peer_id, None)
+        if adapter is None:
+            return
+        try:
+            self._ctx.storage_manager.delete_l2_adapter(adapter.adapter_id)
+        except Exception:
+            logger.exception("Failed to remove P2P adapter for peer %s", peer_id)
+            return
+        logger.debug("Removed P2P adapter for peer %s", peer_id)
+
+    def _active_job_count(self) -> int:
+        """Return the number of active P2P lookup jobs (thread-safe)."""
+        with self._job_lock:
+            return len(self._jobs)
+
+    def _setup_metrics(self) -> None:
+        """Register OTel observable gauges for P2P controller metrics."""
+        _gauge = partial(register_gauge, "lmcache.mp_server")
+        _gauge(
+            "lmcache_mp.active_p2p_lookup_jobs",
+            "Number of active P2P lookup jobs",
+            self._active_job_count,
+        )
diff --git a/lmcache/v1/multiprocess/modules/server_transfer.py b/lmcache/v1/multiprocess/modules/server_transfer.py
new file mode 100644
index 0000000..1d08f06
--- /dev/null
+++ b/lmcache/v1/multiprocess/modules/server_transfer.py
@@ -0,0 +1,440 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Transfer strategy implementations for non-GPU transport paths."""
+
+# Standard
+from _thread import LockType
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+import abc
+import pickle
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.protocols.engine import (
+    PrepareRetrieveResponse,
+    PrepareStoreResponse,
+)
+from lmcache.v1.multiprocess.transfer_context.base import EngineDrivenContextMetadata
+from lmcache.v1.multiprocess.transfer_context.shm import ShmSlotDescriptor
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.storage_manager import StorageManager
+
+logger = init_logger(__name__)
+
+
+def _dtype_to_name(dtype: torch.dtype) -> str:
+    """Return a stable torch dtype name without module prefix."""
+    return str(dtype).split(".")[-1]
+
+
+def create_transfer_strategy(
+    storage_manager: "StorageManager",
+    *,
+    shm_name: str,
+    pool_size: int,
+    pending_writes: dict[tuple[int, IPCCacheServerKey], list[ObjectKey]],
+    pending_reads: dict[tuple[int, IPCCacheServerKey], list[ObjectKey]],
+    pending_lock: LockType,
+    transfer_key_factory: Callable[
+        [IPCCacheServerKey, int], tuple[int, IPCCacheServerKey]
+    ],
+) -> "TransferStrategy":
+    """Create the non-GPU transfer strategy for a registered context.
+
+    Args:
+        storage_manager: Storage manager used by the selected strategy.
+        shm_name: Shared-memory pool name advertised to workers.
+        pool_size: Shared-memory pool size in bytes.
+        pending_writes: Map of pending SHM write reservations keyed by transfer key.
+        pending_reads: Map of pending SHM read reservations keyed by transfer key.
+        pending_lock: Lock guarding shared pending SHM reservation state.
+        transfer_key_factory: Factory that builds the `(instance_id, key)` lookup key
+            used in the pending SHM reservation maps.
+
+    Returns:
+        ``ShmTransferStrategy`` when SHM is configured with a non-empty pool name and
+        positive pool size, otherwise ``PickleTransferStrategy``.
+    """
+    if shm_name and pool_size > 0:
+        logger.info("Using shm non-GPU transfer strategy")
+        return ShmTransferStrategy(
+            storage_manager=storage_manager,
+            pending_writes=pending_writes,
+            pending_reads=pending_reads,
+            pending_lock=pending_lock,
+            transfer_key_factory=transfer_key_factory,
+            fallback_strategy=PickleTransferStrategy(storage_manager),
+        )
+
+    logger.info("Using pickle non-GPU transfer strategy")
+    return PickleTransferStrategy(storage_manager)
+
+
+class TransferStrategy(abc.ABC):
+    """Contract for non-GPU transport backends used by the server.
+
+    Implementations encapsulate the transport-specific prepare/commit lifecycle for
+    store and retrieve operations, allowing the server to use either pickle-based or
+    shared-memory-based transfers behind a common interface.
+    """
+
+    @abc.abstractmethod
+    def prepare_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        context: EngineDrivenContextMetadata,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> PrepareStoreResponse:
+        """Prepare destination resources for a store request.
+
+        Args:
+            key: Cache key identifying the requested token range.
+            instance_id: Worker instance identifier.
+            context: Non-GPU transfer metadata for the instance.
+            resolve_obj_keys: Callable that resolves object keys from ``key``.
+
+        Returns:
+            Transport-specific store preparation response.
+        """
+
+    @abc.abstractmethod
+    def commit_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        cpu_data: bytes,
+        context: EngineDrivenContextMetadata,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> bool:
+        """Finalize a store request.
+
+        Args:
+            key: Cache key identifying the requested token range.
+            instance_id: Worker instance identifier.
+            cpu_data: Serialized payload from the worker.
+            context: Non-GPU transfer metadata for the instance.
+            resolve_obj_keys: Callable that resolves object keys from ``key``.
+
+        Returns:
+            ``True`` when the strategy successfully commits the store request.
+        """
+
+    @abc.abstractmethod
+    def prepare_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> PrepareRetrieveResponse:
+        """Prepare source resources for a retrieve request.
+
+        Args:
+            key: Cache key identifying the requested token range.
+            instance_id: Worker instance identifier.
+            resolve_obj_keys: Callable that resolves object keys from ``key``.
+
+        Returns:
+            Transport-specific retrieve preparation response.
+        """
+
+    @abc.abstractmethod
+    def commit_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+    ) -> bool:
+        """Finalize a retrieve request.
+
+        Args:
+            key: Cache key identifying the requested token range.
+            instance_id: Worker instance identifier.
+
+        Returns:
+            ``True`` when retrieve finalization succeeds.
+        """
+
+
+class PickleTransferStrategy(TransferStrategy):
+    """Pickle-based transport for non-GPU transfer requests.
+
+    This is the default transport when SHM is unavailable, and it is also used as a
+    fallback by the SHM strategy when the worker sends an inline serialized payload.
+    ``prepare_store`` returns an empty context, while ``commit_store`` deserializes
+    the pickle payload and writes the resulting tensors into reserved objects.
+    """
+
+    def __init__(
+        self,
+        storage_manager: "StorageManager",
+    ) -> None:
+        """Initialize pickle transfer strategy.
+
+        Args:
+            storage_manager: Storage manager used for reserve/read/finish calls.
+        """
+        self._storage_manager = storage_manager
+
+    def prepare_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        context: EngineDrivenContextMetadata,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> PrepareStoreResponse:
+        """Return empty store context for pickle mode.
+
+        Pickle transport does not pre-allocate SHM slots during prepare.
+        """
+        return PrepareStoreResponse(context={})
+
+    def commit_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        cpu_data: bytes,
+        context: EngineDrivenContextMetadata,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> bool:
+        """Deserialize and write pickled chunks into reserved objects.
+
+        Returns:
+            ``True`` when every reserved object is written successfully.
+        """
+        obj_keys = resolve_obj_keys(key)
+        chunks: list[torch.Tensor] = pickle.loads(cpu_data)
+        reserved_dict = self._storage_manager.reserve_write(
+            obj_keys, context.layout_desc, "new"
+        )
+        written_keys: list[ObjectKey] = []
+        try:
+            for idx, obj_key in enumerate(obj_keys):
+                if obj_key not in reserved_dict:
+                    continue
+                if idx >= len(chunks):
+                    continue
+                memory_obj = reserved_dict[obj_key]
+                if memory_obj.tensor is None:
+                    continue
+                chunk_cpu = chunks[idx]
+                if chunk_cpu.shape != memory_obj.tensor.shape:
+                    continue
+                memory_obj.tensor.copy_(chunk_cpu)
+                written_keys.append(obj_key)
+        finally:
+            if written_keys:
+                self._storage_manager.finish_write(written_keys)
+
+        return len(written_keys) == len(reserved_dict)
+
+    def prepare_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> PrepareRetrieveResponse:
+        """Read prefetched objects and return serialized pickle payload."""
+        obj_keys = resolve_obj_keys(key)
+        prefetched_keys: list[ObjectKey] = []
+        try:
+            read_ctx = self._storage_manager.read_prefetched_results(obj_keys)
+            with read_ctx as maybe_memory_objs:
+                if not maybe_memory_objs or len(maybe_memory_objs) != len(obj_keys):
+                    return PrepareRetrieveResponse(success=False, data=b"", context={})
+                prefetched_keys = obj_keys[: len(maybe_memory_objs)]
+                chunks = []
+                for memory_obj in maybe_memory_objs:
+                    if memory_obj.tensor is None:
+                        return PrepareRetrieveResponse(
+                            success=False, data=b"", context={}
+                        )
+                    chunks.append(memory_obj.tensor.cpu().clone())
+                return PrepareRetrieveResponse(
+                    success=True, data=pickle.dumps(chunks), context={}
+                )
+        finally:
+            if prefetched_keys:
+                self._storage_manager.finish_read_prefetched(prefetched_keys)
+
+    def commit_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+    ) -> bool:
+        """No-op for pickle mode; data was already copied during prepare."""
+        return True
+
+
+class ShmTransferStrategy(TransferStrategy):
+    """Shared-memory transport for non-GPU transfer requests.
+
+    This strategy exposes SHM slot descriptors during ``prepare_store`` and
+    ``prepare_retrieve`` so workers can access storage buffers directly. It tracks
+    pending SHM reservations until the matching commit step releases them, and it
+    falls back to pickle-based commit handling when ``cpu_data`` is non-empty.
+    """
+
+    def __init__(
+        self,
+        storage_manager: "StorageManager",
+        pending_writes: dict[tuple[int, IPCCacheServerKey], list[ObjectKey]],
+        pending_reads: dict[tuple[int, IPCCacheServerKey], list[ObjectKey]],
+        pending_lock: LockType,
+        transfer_key_factory: Callable[
+            [IPCCacheServerKey, int], tuple[int, IPCCacheServerKey]
+        ],
+        fallback_strategy: PickleTransferStrategy,
+    ) -> None:
+        """Initialize SHM transfer strategy.
+
+        Args:
+            storage_manager: Storage manager used for reserve/read/finish calls.
+            pending_writes: Shared pending SHM write reservations map.
+            pending_reads: Shared pending SHM read reservations map.
+            pending_lock: Lock guarding shared pending SHM maps.
+            transfer_key_factory: Factory to build `(instance_id, key)` transfer keys.
+            fallback_strategy: Pickle fallback for non-empty ``cpu_data`` payloads.
+        """
+        self._storage_manager = storage_manager
+        self._pending_writes = pending_writes
+        self._pending_reads = pending_reads
+        self._pending_lock = pending_lock
+        self._transfer_key_factory = transfer_key_factory
+        self._fallback_strategy = fallback_strategy
+
+    def prepare_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        context: EngineDrivenContextMetadata,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> PrepareStoreResponse:
+        """Reserve SHM-backed objects and return slot descriptors.
+
+        Returns:
+            Context with ``slots`` and ``chunk_indices``.
+        """
+        obj_keys = resolve_obj_keys(key)
+        reserved = self._storage_manager.reserve_write(
+            obj_keys, context.layout_desc, "new"
+        )
+        slots: list[dict[str, Any]] = []
+        chunk_indices: list[int] = []
+        reserved_keys: list[ObjectKey] = []
+        try:
+            for idx, obj_key in enumerate(obj_keys):
+                memory_obj = reserved.get(obj_key)
+                if memory_obj is None or memory_obj.tensor is None:
+                    continue
+                slots.append(
+                    ShmSlotDescriptor(
+                        offset=memory_obj.shm_offset,
+                        length=memory_obj.shm_byte_length,
+                        shape=list(memory_obj.tensor.shape),
+                        dtype=_dtype_to_name(memory_obj.tensor.dtype),
+                    ).to_dict()
+                )
+                chunk_indices.append(idx)
+                reserved_keys.append(obj_key)
+        finally:
+            reserved_keys_set = set(reserved_keys)
+            unused_keys = [
+                obj_key for obj_key in reserved if obj_key not in reserved_keys_set
+            ]
+            if unused_keys:
+                self._storage_manager.finish_write(unused_keys)
+        if not reserved_keys:
+            return PrepareStoreResponse(context={"slots": [], "chunk_indices": []})
+        transfer_key = self._transfer_key_factory(key, instance_id)
+        with self._pending_lock:
+            self._pending_writes[transfer_key] = reserved_keys
+        return PrepareStoreResponse(
+            context={"slots": slots, "chunk_indices": chunk_indices}
+        )
+
+    def commit_store(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        cpu_data: bytes,
+        context: EngineDrivenContextMetadata,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> bool:
+        """Finalize SHM store write locks or fallback to pickle commit.
+
+        Returns:
+            ``True`` when pending SHM reservation is committed successfully.
+        """
+        if cpu_data != b"":
+            return self._fallback_strategy.commit_store(
+                key=key,
+                instance_id=instance_id,
+                cpu_data=cpu_data,
+                context=context,
+                resolve_obj_keys=resolve_obj_keys,
+            )
+        transfer_key = self._transfer_key_factory(key, instance_id)
+        with self._pending_lock:
+            reserved_keys = self._pending_writes.pop(transfer_key, None)
+        if reserved_keys is None:
+            return False
+        if reserved_keys:
+            self._storage_manager.finish_write(reserved_keys)
+        return True
+
+    def prepare_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+        resolve_obj_keys: Callable[[IPCCacheServerKey], list[ObjectKey]],
+    ) -> PrepareRetrieveResponse:
+        """Read SHM objects and return slot descriptors for worker access."""
+        obj_keys = resolve_obj_keys(key)
+        shm_prefetched_keys, shm_memory_objs = self._storage_manager.unsafe_read(
+            obj_keys
+        )
+        if (
+            not shm_memory_objs
+            or len(shm_prefetched_keys) != len(obj_keys)
+            or len(shm_memory_objs) != len(obj_keys)
+        ):
+            if shm_prefetched_keys:
+                self._storage_manager.finish_read_prefetched(shm_prefetched_keys)
+            return PrepareRetrieveResponse(success=False, data=b"", context={})
+        slots: list[dict[str, Any]] = []
+        for memory_obj in shm_memory_objs:
+            if memory_obj.tensor is None:
+                self._storage_manager.finish_read_prefetched(shm_prefetched_keys)
+                return PrepareRetrieveResponse(success=False, data=b"", context={})
+            slots.append(
+                ShmSlotDescriptor(
+                    offset=memory_obj.shm_offset,
+                    length=memory_obj.shm_byte_length,
+                    shape=list(memory_obj.tensor.shape),
+                    dtype=_dtype_to_name(memory_obj.tensor.dtype),
+                ).to_dict()
+            )
+        transfer_key = self._transfer_key_factory(key, instance_id)
+        with self._pending_lock:
+            self._pending_reads[transfer_key] = shm_prefetched_keys
+        return PrepareRetrieveResponse(success=True, data=b"", context={"slots": slots})
+
+    def commit_retrieve(
+        self,
+        key: IPCCacheServerKey,
+        instance_id: int,
+    ) -> bool:
+        """Release pending SHM read locks for the completed retrieve request."""
+        transfer_key = self._transfer_key_factory(key, instance_id)
+        with self._pending_lock:
+            prefetched_keys = self._pending_reads.pop(transfer_key, [])
+        if prefetched_keys:
+            self._storage_manager.finish_read_prefetched(prefetched_keys)
+        return True
diff --git a/lmcache/v1/multiprocess/mp_runtime_plugin_launcher.py b/lmcache/v1/multiprocess/mp_runtime_plugin_launcher.py
new file mode 100644
index 0000000..6293d28
--- /dev/null
+++ b/lmcache/v1/multiprocess/mp_runtime_plugin_launcher.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Runtime plugin launcher for multiprocess (MP) mode.
+
+Unlike the non-MP RuntimePluginLauncher which receives a single
+LMCacheEngineConfig, the MP mode has multiple independent config
+dataclasses (MPServerConfig, StorageManagerConfig,
+ObservabilityConfig, etc.).  This launcher aggregates them all
+into a single JSON blob so plugins get the full server config
+via the LMCACHE_RUNTIME_PLUGIN_CONFIG environment variable.
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+import json
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.plugin.runtime_plugin_launcher import (
+    RuntimePluginLauncher,
+)
+from lmcache.v1.utils.json_utils import make_json_safe, safe_asdict
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.multiprocess.config import (
+        RuntimePluginConfig,
+    )
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class _MPPluginConfig:
+    """Thin wrapper that satisfies RuntimePluginLauncher's
+    config duck-type contract (runtime_plugin_locations +
+    to_json)."""
+
+    runtime_plugin_locations: list[str]
+    extra_config: dict[str, Any]
+    configs_dict: dict[str, Any]
+
+    def to_json(self) -> str:
+        merged = dict(self.configs_dict)
+        if self.extra_config:
+            merged["runtime_plugin_extra_config"] = make_json_safe(self.extra_config)
+        return json.dumps(merged)
+
+
+class MPRuntimePluginLauncher:
+    """Launch runtime plugins in MP mode with all server
+    configs serialized into the environment.
+
+    Usage::
+
+        launcher = MPRuntimePluginLauncher(
+            runtime_plugin_config=runtime_plugin_config,
+            mp_config=mp_config,
+            storage_manager_config=sm_config,
+            obs_config=obs_config,
+        )
+        launcher.launch_plugins()
+        # ... on shutdown ...
+        launcher.stop_plugins()
+    """
+
+    def __init__(
+        self,
+        runtime_plugin_config: "RuntimePluginConfig",
+        **configs: object,
+    ) -> None:
+        """Initialize the MP runtime plugin launcher.
+
+        Aggregates arbitrary dataclass configs into a single
+        JSON blob and delegates to RuntimePluginLauncher.
+
+        Args:
+            runtime_plugin_config: RuntimePluginConfig with
+                locations and extra_config fields.
+            **configs: Dataclass config objects to serialize
+                and pass to plugins via environment variable.
+        """
+        # Build the aggregated JSON dict from all configs
+        aggregated: dict = {}
+        for name, cfg in configs.items():
+            aggregated[name] = safe_asdict(cfg)
+
+        wrapper = _MPPluginConfig(
+            runtime_plugin_locations=runtime_plugin_config.locations,
+            extra_config=getattr(runtime_plugin_config, "extra_config", {}),
+            configs_dict=aggregated,
+        )
+        self._inner = RuntimePluginLauncher(
+            config=wrapper,
+            role=None,
+            worker_count=1,
+            worker_id=0,
+        )
+        logger.info("MPRuntimePluginLauncher initialized with %s", wrapper)
+
+    def launch_plugins(self) -> None:
+        """Launch all configured plugins."""
+        self._inner.launch_plugins()
+
+    def stop_plugins(self) -> None:
+        """Terminate all plugin processes."""
+        self._inner.stop_plugins()
diff --git a/lmcache/v1/multiprocess/mq.py b/lmcache/v1/multiprocess/mq.py
new file mode 100644
index 0000000..271ff93
--- /dev/null
+++ b/lmcache/v1/multiprocess/mq.py
@@ -0,0 +1,875 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import Any, Callable, Generic, Optional, TypeVar, get_type_hints
+import enum
+import inspect
+import itertools
+import queue
+import threading
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.multiprocess.affinity_pool import AffinityThreadPool
+from lmcache.v1.multiprocess.custom_types import (
+    DeviceIPCWrapper,
+    get_customized_decoder,
+    get_customized_encoder,
+)
+from lmcache.v1.multiprocess.futures import (
+    MessagingFuture,
+)
+from lmcache.v1.multiprocess.protocol import (
+    HandlerType,
+    RequestType,
+    get_payload_classes,
+    get_response_class,
+)
+from lmcache.v1.platform import EventNotifier, create_event_notifier
+
+logger = init_logger(__name__)
+
+T = TypeVar("T")
+
+# Internal type used for the client-server communication
+RequestUID = int
+
+
+# Helper functions
+def encode_request_uid(uid: RequestUID) -> bytes:
+    return msgspec.msgpack.encode(uid)
+
+
+def decode_request_uid(b_uid: bytes) -> RequestUID:
+    return msgspec.msgpack.decode(b_uid, type=RequestUID)
+
+
+def unwrap_request_payloads(
+    b_payloads: list[bytes], payload_clss: list[Any]
+) -> list[Any]:
+    if len(b_payloads) != len(payload_clss):
+        raise ValueError("Payload count does not match expected count")
+
+    decoded_payloads = [
+        msgspec_decode(payload, cls=cls)
+        for payload, cls in zip(b_payloads, payload_clss, strict=False)
+    ]
+    return decoded_payloads
+
+
+_SPECIAL_ENCODER_DECODERS = {
+    DeviceIPCWrapper: (
+        get_customized_encoder(DeviceIPCWrapper),
+        get_customized_decoder(DeviceIPCWrapper),
+    ),
+    list[DeviceIPCWrapper]: (
+        get_customized_encoder(list[DeviceIPCWrapper]),
+        get_customized_decoder(list[DeviceIPCWrapper]),
+    ),
+    MemoryLayoutDesc: (
+        get_customized_encoder(MemoryLayoutDesc),
+        get_customized_decoder(MemoryLayoutDesc),
+    ),
+}
+
+
+def msgspec_encode(obj: Any, cls: Any) -> bytes:
+    # Handle special cases
+    if cls in _SPECIAL_ENCODER_DECODERS:
+        encoder, _ = _SPECIAL_ENCODER_DECODERS[cls]
+        return encoder.encode(obj)
+    # Defensive guard: coerce obj to the declared cls so that
+    # e.g. a bool passed as int (or vice-versa) is encoded in the
+    # wire format that msgspec_decode expects for that cls.
+    if cls in (bool, int):
+        obj = cls(obj)
+    return msgspec.msgpack.encode(obj)
+
+
+def msgspec_decode(b_obj: bytes, cls: Any) -> Any:
+    # Handle special cases
+    if cls in _SPECIAL_ENCODER_DECODERS:
+        _, decoder = _SPECIAL_ENCODER_DECODERS[cls]
+        return decoder.decode(b_obj)
+    # Defensive guard: msgspec strict-validates wire format
+    # (bool ≠ int in msgpack), but runtime type may not match
+    # declared cls. Decode untyped, then coerce.
+    if cls in (bool, int):
+        return cls(msgspec.msgpack.decode(b_obj))
+    return msgspec.msgpack.decode(b_obj, type=cls)
+
+
+# Shared polling loop for MessageQueueClient instances
+
+
+class _OpKind(enum.Enum):
+    REGISTER = "register"
+    UNREGISTER = "unregister"
+
+
+@dataclass
+class _PollOp:
+    kind: _OpKind
+    client: "MessageQueueClient"
+    done: threading.Event
+
+
+class ClientPollingLoop:
+    """Singleton polling loop shared by all MessageQueueClient instances.
+
+    Instead of each client running its own daemon thread and zmq.Poller,
+    a single loop polls all clients' DEALER sockets and dispatches
+    inbound/outbound work.
+
+    Use ``get_instance()`` / ``release_instance()`` for lifecycle
+    management — the loop starts lazily on first client and stops
+    automatically when the last client releases.
+    """
+
+    _instance: "ClientPollingLoop | None" = None
+    _instance_lock: threading.Lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._ref_count: int = 0
+        self._is_finished = threading.Event()
+        self._notifier: EventNotifier = create_event_notifier()
+        self._ops_queue: queue.Queue[_PollOp] = queue.Queue()
+        self._poller = zmq.Poller()
+        self._poller.register(self._notifier.fileno(), zmq.POLLIN)
+        self._socket_to_client: dict[zmq.Socket, "MessageQueueClient"] = {}
+        self._thread = threading.Thread(
+            target=self._main_loop, daemon=True, name="mq-client-shared-loop"
+        )
+        self._thread.start()
+
+    @classmethod
+    def get_instance(cls) -> "ClientPollingLoop":
+        """Get or create the singleton, incrementing the ref count.
+
+        Returns:
+            ClientPollingLoop: The shared polling loop instance.
+        """
+        with cls._instance_lock:
+            if cls._instance is None:
+                cls._instance = ClientPollingLoop()
+            cls._instance._ref_count += 1
+            return cls._instance
+
+    @classmethod
+    def release_instance(cls) -> None:
+        """Decrement the ref count; tear down the loop when it reaches 0."""
+        with cls._instance_lock:
+            inst = cls._instance
+            if inst is None:
+                return
+            inst._ref_count -= 1
+            if inst._ref_count > 0:
+                return
+            inst._is_finished.set()
+            inst._notifier.notify()
+            cls._instance = None
+
+        inst._thread.join()
+        inst._notifier.close()
+        logger.debug("ClientPollingLoop shut down")
+
+    def register(self, client: "MessageQueueClient") -> None:
+        """Register a client's DEALER socket with the shared poller.
+
+        Blocks until the loop thread has completed the registration.
+
+        Args:
+            client: The MessageQueueClient to register.
+        """
+        done = threading.Event()
+        self._ops_queue.put(_PollOp(kind=_OpKind.REGISTER, client=client, done=done))
+        self._notifier.notify()
+        done.wait()
+
+    def unregister(self, client: "MessageQueueClient") -> None:
+        """Unregister a client's DEALER socket from the shared poller.
+
+        Blocks until the loop thread has completed the unregistration.
+
+        Args:
+            client: The MessageQueueClient to unregister.
+        """
+        done = threading.Event()
+        self._ops_queue.put(_PollOp(kind=_OpKind.UNREGISTER, client=client, done=done))
+        self._notifier.notify()
+        done.wait()
+
+    def notify(self) -> None:
+        """Wake the polling loop to process outbound tasks."""
+        self._notifier.notify()
+
+    def _process_ops(self) -> None:
+        """Drain the ops queue and apply register/unregister to the poller."""
+        try:
+            while True:
+                op = self._ops_queue.get_nowait()
+                if op.kind is _OpKind.REGISTER:
+                    self._poller.register(op.client.socket, zmq.POLLIN)
+                    self._socket_to_client[op.client.socket] = op.client
+                    logger.debug("Registered client socket %s", op.client.socket)
+                elif op.kind is _OpKind.UNREGISTER:
+                    self._poller.unregister(op.client.socket)
+                    self._socket_to_client.pop(op.client.socket, None)
+                    logger.debug("Unregistered client socket %s", op.client.socket)
+                op.done.set()
+        except queue.Empty:
+            pass
+
+    def _main_loop(self) -> None:
+        """Unified poll loop for all registered clients."""
+        notifier_fd = self._notifier.fileno()
+
+        while not self._is_finished.is_set():
+            self._process_ops()
+
+            socks = dict(self._poller.poll(1000))
+
+            # Outbound: shared notifier woke us — drain it, then flush
+            # all clients' output queues.
+            if socks.get(notifier_fd) and socks[notifier_fd] & zmq.POLLIN:
+                self._notifier.consume()
+                for client in self._socket_to_client.values():
+                    client.process_outbound_task()
+
+            # Inbound: dispatch each ready DEALER socket to its client.
+            for sock, event in socks.items():
+                if sock is notifier_fd:
+                    continue
+                if event & zmq.POLLIN:
+                    owner = self._socket_to_client.get(sock)
+                    if owner is not None:
+                        owner.process_inbound()
+
+        # Drain remaining ops so any waiting threads unblock.
+        self._process_ops()
+
+
+# Main classes
+class MessageQueueClient:
+    @dataclass
+    class WrappedRequest:
+        request_uid: RequestUID
+        future: MessagingFuture[Any]
+        request_type: RequestType
+        request_payloads: list[Any]
+
+    def __init__(self, server_url: str, context: zmq.Context):
+        # Socket
+        self.ctx = context
+        self.socket = self.ctx.socket(zmq.DEALER)
+        self.socket.connect(server_url)
+
+        # Input queue
+        self.input_queue: queue.Queue = queue.Queue()
+
+        # Pending job's futures
+        self._request_counter = itertools.count()
+        self.pending_futures: dict[int, MessagingFuture[Any]] = {}
+
+        # Register with the shared polling loop
+        self._polling_loop = ClientPollingLoop.get_instance()
+        self._polling_loop.register(self)
+
+    def process_outbound_task(self):
+        try:
+            while wrapped_request := self.input_queue.get_nowait():
+                # wrapped_request = self.input_queue.get_nowait()
+
+                # Update the pending futures
+                request_uid = wrapped_request.request_uid
+                self.pending_futures[request_uid] = wrapped_request.future
+
+                # Send the request
+                b_request_uid = msgspec_encode(request_uid, cls=RequestUID)
+                b_request_type = msgspec_encode(
+                    wrapped_request.request_type, cls=RequestType
+                )
+                payload_classes = get_payload_classes(wrapped_request.request_type)
+                if len(payload_classes) != len(wrapped_request.request_payloads):
+                    expected_classes = [cls.__name__ for cls in payload_classes]
+                    actual_classes = [
+                        type(p).__name__ for p in wrapped_request.request_payloads
+                    ]
+                    raise ValueError(
+                        f"Payload count mismatch for request "
+                        f"{wrapped_request.request_type}: "
+                        f"expected {len(payload_classes)} payloads "
+                        f"{expected_classes}, "
+                        f"got {len(wrapped_request.request_payloads)} payloads "
+                        f"{actual_classes}. "
+                        f"This is likely caused by a version mismatch between "
+                        f"the lmcache client and lmcache server."
+                    )
+
+                b_payloads = [
+                    msgspec_encode(payload, cls=cls)
+                    for payload, cls in zip(
+                        wrapped_request.request_payloads,
+                        payload_classes,
+                        strict=False,
+                    )
+                ]
+                self.socket.send_multipart([b_request_uid, b_request_type] + b_payloads)
+        except queue.Empty:
+            pass
+
+    def process_inbound(self) -> None:
+        """Process one inbound response from the server.
+
+        Called by the shared ClientPollingLoop when the DEALER socket
+        is readable.  Only touches ``pending_futures``, which is
+        exclusively accessed from the loop thread.
+        """
+        msg = self.socket.recv_multipart()
+        if len(msg) < 2:
+            logger.error(
+                "Malformed response: expected at least 2 message parts "
+                "[request_uid, request_type, *response], got %d",
+                len(msg),
+            )
+            return
+        b_request_uid, b_request_type, *b_response = msg
+        request_uid = msgspec_decode(b_request_uid, cls=RequestUID)
+        request_type = msgspec_decode(b_request_type, cls=RequestType)
+        response_cls = get_response_class(request_type)
+
+        if request_uid in self.pending_futures:
+            future = self.pending_futures.pop(request_uid)
+            if b_response:
+                response = msgspec_decode(b_response[0], cls=response_cls)
+                future.set_result(response)
+            else:
+                future.set_result(None)
+
+    def submit_request(
+        self,
+        request_type: RequestType,
+        request_payloads: list[Any],
+        response_cls: Optional[T] = None,
+    ) -> MessagingFuture[T]:
+        """Submit a request to the server.
+
+        Args:
+            request_type (RequestType): The type of the request.
+            request_payloads (list[Any]): The payloads of the request.
+            response_cls (Optional[T]): The expected response class.
+                This should be get from `get_response_class(request_type)`.
+
+        Returns:
+            MessagingFuture[T]: A future that will hold the response.
+        """
+        future: MessagingFuture[T] = MessagingFuture()
+        request_uid = next(self._request_counter)
+        self.input_queue.put(
+            MessageQueueClient.WrappedRequest(
+                request_uid=request_uid,
+                future=future,
+                request_type=request_type,
+                request_payloads=request_payloads,
+            )
+        )
+        self._polling_loop.notify()
+        return future
+
+    def close(self) -> None:
+        self._polling_loop.unregister(self)
+        ClientPollingLoop.release_instance()
+        self.socket.close()
+
+
+ResponseType = TypeVar("ResponseType", covariant=True)
+StateType = TypeVar("StateType", covariant=True)
+
+
+class RequestHandlerBase(Generic[ResponseType]):
+    def __call__(self, payloads: list[bytes]):
+        raise NotImplementedError
+
+    def get_response_class(self) -> ResponseType:
+        raise NotImplementedError
+
+    def get_handler_type(self) -> HandlerType:
+        raise NotImplementedError
+
+
+class SyncRequestHandler(RequestHandlerBase[ResponseType]):
+    """
+    The handler for those "fast" functions that can be executed in the main loop
+    """
+
+    def __init__(
+        self,
+        payload_clss: list[Any],
+        response_cls: ResponseType,
+        handler: Callable[..., ResponseType],
+    ):
+        self.payload_clss = payload_clss
+        self.response_cls = response_cls
+        self.handler = handler
+
+    def __call__(self, payloads: list[bytes]) -> ResponseType:
+        return self.handler(*unwrap_request_payloads(payloads, self.payload_clss))
+
+    def get_response_class(self) -> ResponseType:
+        return self.response_cls
+
+    def get_handler_type(self) -> HandlerType:
+        return HandlerType.SYNC
+
+
+class BlockingRequestHandler(RequestHandlerBase[ResponseType]):
+    """
+    Returns the future of the response.
+
+    The ``executor`` field is initially ``None`` and must be assigned via
+    :meth:`MessageQueueServer.add_normal_thread_pool` or
+    :meth:`MessageQueueServer.add_affinity_thread_pool` before the server
+    is started.
+    """
+
+    def __init__(
+        self,
+        payload_clss: list[Any],
+        response_cls: ResponseType,
+        handler: Callable[..., ResponseType],
+    ):
+        self.executor: ThreadPoolExecutor | AffinityThreadPool | None = None
+        self.payload_clss = payload_clss
+        self.handler = handler
+        self.response_cls = response_cls
+
+    def __call__(
+        self, payloads: list[bytes], affinity_key: int = 0
+    ) -> Future[ResponseType]:
+        assert self.executor is not None, (
+            "BlockingRequestHandler has no executor assigned. "
+            "Call add_normal_thread_pool or add_affinity_thread_pool first."
+        )
+        decoded_payloads = unwrap_request_payloads(payloads, self.payload_clss)
+        if isinstance(self.executor, AffinityThreadPool):
+            return self.executor.submit(
+                self.handler, *decoded_payloads, affinity_key=affinity_key
+            )
+        return self.executor.submit(self.handler, *decoded_payloads)
+
+    def get_response_class(self) -> ResponseType:
+        return self.response_cls
+
+    def get_handler_type(self) -> HandlerType:
+        return HandlerType.BLOCKING
+
+
+class NonBlockingRequestHandler(Generic[ResponseType, StateType]):
+    """
+    The handler for the "fire and probe" functions that launch async tasks
+    and have special mechanism to probe the task status.
+
+    It requires 2 callables as the input:
+    - the first one is to launch the async task. This function should return
+        a 'state handle' that can be used to probe the task status later.
+    - the second one is to probe the task status and get the return value
+        with the 'state handle' returned by the first function.
+    """
+
+    # TODO: implement this in the future versions if needed
+    pass
+
+
+class MessageQueueServer:
+    def __init__(self, bind_url: str, context: zmq.Context):
+        # Socket
+        self.ctx = context
+        self.socket = self.ctx.socket(zmq.ROUTER)
+        self.socket.bind(bind_url)
+        # Use a cross-platform Notifier instead of zmq PUSH/PULL sockets
+        # because blocking handler callbacks run on ThreadPoolExecutor
+        # threads, and zmq sockets are not thread-safe. Notifier.notify()
+        # is atomic (eventfd on Linux, self-pipe elsewhere).
+        self._output_efd = create_event_notifier()
+        self.output_queue: queue.Queue = queue.Queue()
+
+        # Poller
+        self.poller = zmq.Poller()
+        self.poller.register(self.socket, zmq.POLLIN)
+        self.poller.register(self._output_efd.fileno(), zmq.POLLIN)
+
+        # Main loop thread
+        self.is_finished = threading.Event()
+        self.worker_thread = threading.Thread(
+            target=self._main_loop, daemon=True, name="mq-server-thread"
+        )
+
+        # Registered handlers: request_type -> (payload_cls, handler)
+        self.handlers: dict[RequestType, RequestHandlerBase[Any]] = {}
+
+        # Thread pools assigned via add_normal_thread_pool / add_affinity_thread_pool
+        self.extra_pools: list[ThreadPoolExecutor | AffinityThreadPool] = []
+
+    def _call_sync_handler(
+        self,
+        handler_entry: SyncRequestHandler[Any],
+        payloads: list[bytes],
+        prefix_frames: list[bytes],
+    ) -> Any:
+        """
+        Call the sync handler and send the response back to the client.
+
+        Args:
+            handler_entry (SyncRequestHandler[Any]): The handler entry.
+            payloads (list[bytes]): The payloads of the request.
+            prefix_frames (list[bytes]): The prefix frames to send back.
+        """
+        response = handler_entry(payloads)
+        response_cls = handler_entry.get_response_class()
+        b_response = msgspec_encode(response, cls=response_cls)
+        if response is not None:
+            self.socket.send_multipart(prefix_frames + [b_response])
+        else:
+            self.socket.send_multipart(prefix_frames)
+
+    def _call_blocking_handler(
+        self,
+        handler_entry: BlockingRequestHandler[Any],
+        payloads: list[bytes],
+        prefix_frames: list[bytes],
+    ) -> Any:
+        """
+        Call the blocking handler in a separate thread and send the response
+        back to the client.
+
+        Args:
+            handler_entry (BlockingRequestHandler[Any]): The handler entry.
+            payloads (list[bytes]): The payloads of the request.
+            prefix_frames (list[bytes]): The prefix frames to send back.
+                prefix_frames[0] is the zmq identity used as affinity key.
+        """
+        affinity_key = hash(prefix_frames[0])
+        future = handler_entry(payloads, affinity_key=affinity_key)
+
+        def _notify_response(fut: Future):
+            try:
+                response = fut.result()
+                response_cls = handler_entry.get_response_class()
+                b_response = msgspec_encode(response, cls=response_cls)
+                frames_to_send = (
+                    prefix_frames + [b_response]
+                    if response is not None
+                    else prefix_frames
+                )
+
+                self.output_queue.put(frames_to_send)
+                self._output_efd.notify()
+
+            except Exception:
+                logger.exception("Error in blocking handler")
+
+        future.add_done_callback(_notify_response)
+
+    def _call_handler(
+        self,
+        handler_entry: RequestHandlerBase[Any],
+        payloads: list[bytes],
+        prefix_frames: list[bytes],
+    ) -> Any:
+        match handler_entry.get_handler_type():
+            case HandlerType.SYNC:
+                assert isinstance(handler_entry, SyncRequestHandler)
+                self._call_sync_handler(handler_entry, payloads, prefix_frames)
+            case HandlerType.BLOCKING:
+                assert isinstance(handler_entry, BlockingRequestHandler)
+                self._call_blocking_handler(handler_entry, payloads, prefix_frames)
+            case HandlerType.NON_BLOCKING:
+                raise NotImplementedError("Non-blocking handler is not supported yet")
+            case _:
+                raise ValueError("Unknown handler type")
+
+    def _main_loop(self):
+        output_fd = self._output_efd.fileno()
+        while not self.is_finished.is_set():
+            socks = dict(self.poller.poll(1000))
+            inbound_state = socks.get(self.socket, None)
+            outbound_state = socks.get(output_fd, None)
+
+            # Process the incoming requests
+            if inbound_state and inbound_state & zmq.POLLIN:
+                msg = self.socket.recv_multipart()
+                assert len(msg) >= 3, (
+                    "Expected at least 3 message parts "
+                    "[identity, request_uid, request_type, *payloads]"
+                )
+
+                identity, b_request_uid, b_request_type, *payloads = msg
+                request_type = msgspec_decode(b_request_type, cls=RequestType)
+
+                if handler_entry := self.handlers.get(request_type):
+                    try:
+                        self._call_handler(
+                            handler_entry=handler_entry,
+                            payloads=payloads,
+                            prefix_frames=[identity, b_request_uid, b_request_type],
+                        )
+                    except Exception:
+                        logger.exception("Error handling request %s", request_type)
+                else:
+                    logger.error(
+                        "No handler registered for request type %s", request_type
+                    )
+                    logger.error("Available handlers: %s", list(self.handlers.keys()))
+
+            # Send the responses
+            if outbound_state and outbound_state & zmq.POLLIN:
+                # Consume the notifier counter (resets atomically)
+                self._output_efd.consume()
+
+                # Process the output tasks
+                try:
+                    while frames_to_send := self.output_queue.get_nowait():
+                        self.socket.send_multipart(frames_to_send)
+                except queue.Empty:
+                    pass
+
+    def _inspect_handler_signature(self, request_type: RequestType, handler) -> bool:
+        """Inspect the handler signature to ensure it matches the expected
+        payload classes.
+
+        Args:
+            handler (callable): The handler function.
+
+        Returns:
+            bool: True if the signature matches, False otherwise.
+        """
+
+        def same_type(a, b) -> bool:
+            if a is None:
+                a = type(None)
+            if b is None:
+                b = type(None)
+            return a == b
+
+        sig = inspect.signature(handler)
+        hints = get_type_hints(handler)
+        params = [
+            p
+            for p in sig.parameters.values()
+            if p.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ]
+
+        payload_clss = get_payload_classes(request_type)
+        if len(params) != len(payload_clss):
+            logger.error(
+                "Handler for %s expects %d arguments, but got %d",
+                request_type,
+                len(payload_clss),
+                len(params),
+            )
+            return False
+
+        for i, (param, expected_cls) in enumerate(
+            zip(params, payload_clss, strict=False)
+        ):
+            ann = hints.get(param.name, param.annotation)
+            if not same_type(ann, expected_cls):
+                logger.error(
+                    "Handler for %s argument %d expects type %s, but got %s",
+                    request_type,
+                    i,
+                    expected_cls,
+                    ann,
+                )
+                return False
+
+        return_ann = hints.get("return", sig.return_annotation)
+        expected_return_cls = get_response_class(request_type)
+        if not same_type(return_ann, expected_return_cls):
+            logger.error(
+                "Handler for %s expects return type %s, but got %s",
+                request_type,
+                expected_return_cls,
+                return_ann,
+            )
+            return False
+        return True
+
+    def add_handler(
+        self,
+        request_type: RequestType,
+        payload_clss: list[Any],
+        handler_type: HandlerType,
+        handler,
+    ) -> None:
+        """Register a handler for a specific request type.
+
+        Args:
+            request_type (RequestType): The type of the request to handle.
+            payload_clss (list[Any]): The expected payload classes for the request.
+                This should be get from `get_payload_classes(request_type)`.
+            handler (callable): The handler function that takes the payloads
+                as arguments.
+        """
+        if not self._inspect_handler_signature(request_type, handler):
+            raise ValueError(
+                f"Handler signature does not match for request type: {request_type}"
+            )
+
+        match handler_type:
+            case HandlerType.SYNC:
+                self.add_sync_handler(request_type, payload_clss, handler)
+            case HandlerType.BLOCKING:
+                self.add_blocking_handler(request_type, payload_clss, handler)
+            case HandlerType.NON_BLOCKING:
+                raise NotImplementedError("Non-blocking handler is not supported yet")
+            case _:
+                raise ValueError(f"Unknown handler type: {handler_type}")
+
+    def add_sync_handler(
+        self, request_type: RequestType, payload_clss: list[Any], handler
+    ) -> None:
+        response_cls = get_response_class(request_type)
+        self.handlers[request_type] = SyncRequestHandler(
+            payload_clss, response_cls, handler
+        )
+
+    def add_blocking_handler(
+        self, request_type: RequestType, payload_clss: list[Any], handler
+    ) -> None:
+        response_cls = get_response_class(request_type)
+        self.handlers[request_type] = BlockingRequestHandler(
+            payload_clss, response_cls, handler
+        )
+
+    def add_nonblocking_handler(
+        self, request_type: RequestType, payload_clss: list[Any], handler
+    ) -> None:
+        raise NotImplementedError
+
+    def _validate_blocking_handlers(
+        self,
+        request_types: list[RequestType],
+        method_name: str,
+    ) -> None:
+        """Validate that all request types are registered BlockingRequestHandlers."""
+        for request_type in request_types:
+            handler = self.handlers.get(request_type)
+            if handler is None:
+                raise ValueError(
+                    f"No handler registered for request type: {request_type}. "
+                    f"Register handlers before calling {method_name}."
+                )
+            if not isinstance(handler, BlockingRequestHandler):
+                raise TypeError(
+                    f"Handler for {request_type} is "
+                    f"{type(handler).__name__}, not BlockingRequestHandler. "
+                    f"Only blocking handlers can use thread pools."
+                )
+
+    def add_normal_thread_pool(
+        self,
+        request_types: list[RequestType],
+        max_workers: int,
+    ) -> None:
+        """Assign a ThreadPoolExecutor to specific request types.
+
+        Use this for non-GPU blocking handlers (e.g. LOOKUP, END_SESSION).
+
+        Must be called after the handlers are registered (via add_handler /
+        add_blocking_handler) and before start().  Each request_type must
+        already be registered as a BlockingRequestHandler; otherwise a
+        ValueError or TypeError is raised.
+
+        Args:
+            request_types: The request types that should use this pool.
+            max_workers: Number of worker threads in the pool.
+        """
+        self._validate_blocking_handlers(request_types, "add_normal_thread_pool")
+        if not request_types:
+            return
+
+        pool = ThreadPoolExecutor(
+            max_workers=max_workers,
+            thread_name_prefix=f"normal-pool-{len(self.extra_pools)}",
+        )
+        self.extra_pools.append(pool)
+        for request_type in request_types:
+            handler = self.handlers[request_type]
+            assert isinstance(handler, BlockingRequestHandler)
+            handler.executor = pool
+
+        logger.debug(
+            "Created normal thread pool (max_workers=%d) for request types: %s",
+            max_workers,
+            [rt.name for rt in request_types],
+        )
+
+    def add_affinity_thread_pool(
+        self,
+        request_types: list[RequestType],
+        max_workers: int,
+    ) -> None:
+        """Assign an AffinityThreadPool to specific request types.
+
+        Use this for GPU-bound blocking handlers (e.g. STORE, RETRIEVE).
+        Requests from the same zmq client identity are always dispatched
+        to the same worker thread, eliminating the need for per-instance
+        GPU transfer locks.
+
+        Must be called after the handlers are registered (via add_handler /
+        add_blocking_handler) and before start().
+
+        Args:
+            request_types: The request types that should use this pool.
+            max_workers: Number of worker threads in the pool.
+        """
+        self._validate_blocking_handlers(request_types, "add_affinity_thread_pool")
+        if not request_types:
+            return
+
+        pool = AffinityThreadPool(
+            max_workers=max_workers,
+            thread_name_prefix=f"affinity-pool-{len(self.extra_pools)}",
+        )
+        self.extra_pools.append(pool)
+        for request_type in request_types:
+            handler = self.handlers[request_type]
+            assert isinstance(handler, BlockingRequestHandler)
+            handler.executor = pool
+
+        logger.debug(
+            "Created affinity thread pool (max_workers=%d) for request types: %s",
+            max_workers,
+            [rt.name for rt in request_types],
+        )
+
+    def start(self):
+        # Validate all blocking handlers have an executor assigned
+        for rt, handler in self.handlers.items():
+            if isinstance(handler, BlockingRequestHandler) and handler.executor is None:
+                raise RuntimeError(
+                    f"BlockingRequestHandler for {rt} has no thread pool "
+                    f"assigned. Call add_normal_thread_pool or "
+                    f"add_affinity_thread_pool before start()."
+                )
+        self.worker_thread.start()
+
+    def close(self) -> None:
+        self.is_finished.set()
+        if self.worker_thread.is_alive():
+            self.worker_thread.join()
+        self.socket.close()
+        for pool in self.extra_pools:
+            pool.shutdown(wait=False)
+        self._output_efd.close()
diff --git a/lmcache/v1/multiprocess/native_completion.py b/lmcache/v1/multiprocess/native_completion.py
new file mode 100644
index 0000000..36f0ef9
--- /dev/null
+++ b/lmcache/v1/multiprocess/native_completion.py
@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Dispatch device-stream-ordered host callbacks without GIL contention.
+
+Call graph::
+
+    Server.store / Server.retrieve  (Python, holds GIL)
+        |
+        v
+    submit_callback_to_stream(stream, kind, payload)
+        |
+        v  Python: msgspec.msgpack.encode(payload)
+        v  C++:    record_completion_on_stream (gil_scoped_release)
+        v  C++:    cudaLaunchHostFunc / hipLaunchHostFunc
+        |
+        v  -------- on the CUDA/HIP driver thread (no GIL) --------
+        v  completion_host_callback: append PendingCompletion to buffer
+        |
+        v  -------- on DeviceHostFuncDispatcher drain thread (Python) --
+        v  drain_recorded_completions  (returns list of (kind, bytes))
+        v  msgspec.msgpack.decode(bytes) with the kind's registered type
+        v  handler(decoded_payload)  ← finish_write / finish_read_prefetched
+
+Payload round-trips as a single opaque blob. For multi-arg handlers, wrap
+the args in a tuple/struct matching the registered ``payload_type``.
+
+Extends PR #2952's AB-BA fix (GIL x driver lock) to Server.store/retrieve.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any, Callable
+import threading
+
+# Third Party
+import msgspec
+import torch  # noqa: F401 — must be imported before lmcache.c_ops
+
+# First Party
+from lmcache.logging import init_logger
+import lmcache.c_ops as _lmc_ops
+
+logger = init_logger(__name__)
+
+# Runs on dispatcher thread with the decoded payload for one submission.
+DeviceHostFunc = Callable[[Any], None]
+
+
+class _Registration(msgspec.Struct):
+    handler: DeviceHostFunc
+    decoder: msgspec.msgpack.Decoder
+
+
+class DeviceHostFuncDispatcher:
+    """Drain buffered C++ completions and dispatch each payload to the handler
+    registered for its ``kind``. One instance per process; owned by
+    ``MPCacheServer``."""
+
+    def __init__(self, drain_interval_seconds: float = 0.005) -> None:
+        self._registry: dict[str, _Registration] = {}
+        self._lock = threading.Lock()
+        self._stop_flag = threading.Event()
+        self._wake = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._drain_interval = drain_interval_seconds
+        self._dispatched_count = 0
+        self._exception_counts: dict[str, int] = {}
+
+    def register(self, kind: str, handler: DeviceHostFunc, payload_type: Any) -> None:
+        """Register *handler* for *kind*. ``payload_type`` is the msgspec
+        decode type for the whole payload (e.g. ``list[ObjectKey]``)."""
+        with self._lock:
+            self._registry[kind] = _Registration(
+                handler=handler,
+                decoder=msgspec.msgpack.Decoder(type=payload_type),
+            )
+
+    def start(self) -> None:
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop_flag.clear()
+        self._thread = threading.Thread(
+            target=self._run,
+            daemon=True,
+            name="DeviceHostFuncDispatcher",
+        )
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop_flag.set()
+        self._wake.set()
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join()
+        self._drain_once()
+
+    def dispatched_count(self) -> int:
+        return self._dispatched_count  # single-writer; read is GIL-atomic
+
+    def handler_exception_counts(self) -> dict[str, int]:
+        with self._lock:
+            return dict(self._exception_counts)
+
+    def _run(self) -> None:
+        while not self._stop_flag.is_set():
+            self._wake.wait(timeout=self._drain_interval)
+            self._wake.clear()
+            self._drain_once()
+
+    def _drain_once(self) -> None:
+        # Broad except keeps the drain thread alive across native/handler errors.
+        try:
+            completions = _lmc_ops.drain_recorded_completions()
+        except Exception:
+            logger.exception("DeviceHostFuncDispatcher: drain failed")
+            return
+        if not completions:
+            return
+        with self._lock:
+            registry = dict(self._registry)
+        for kind, encoded_payload in completions:
+            reg = registry.get(kind)
+            if reg is None:
+                logger.warning(
+                    "DeviceHostFuncDispatcher: no handler for kind=%r (dropped)",
+                    kind,
+                )
+                continue
+            try:
+                decoded = reg.decoder.decode(encoded_payload)
+                reg.handler(decoded)
+                self._dispatched_count += 1
+            except Exception:
+                with self._lock:
+                    self._exception_counts[kind] = (
+                        self._exception_counts.get(kind, 0) + 1
+                    )
+                logger.exception(
+                    "DeviceHostFuncDispatcher: handler for %r raised", kind
+                )
+
+
+def submit_callback_to_stream(stream: Any, kind: str, payload: Any) -> None:
+    """Schedule a stream-ordered host callback for *kind* with *payload*.
+    Runs on the dispatcher worker registered for *kind*; never acquires the
+    GIL on the driver thread. ``payload`` is delivered to the handler as a
+    single argument."""
+    encoded = msgspec.msgpack.encode(payload)
+    _lmc_ops.record_completion_on_stream(stream.ptr, kind, encoded)
diff --git a/lmcache/v1/multiprocess/posix_shm.py b/lmcache/v1/multiprocess/posix_shm.py
new file mode 100644
index 0000000..9445021
--- /dev/null
+++ b/lmcache/v1/multiprocess/posix_shm.py
@@ -0,0 +1,273 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared-memory primitives shared by SHM-based transports.
+
+Thin POSIX-SHM facade exposing the legacy
+``shm_create_readwrite`` / ``shm_map_readwrite`` / ``shm_munmap`` /
+``shm_unlink`` / ``shm_open_pool_as_mmap`` quartet, so the CPU
+KV-cache wrapper, the MP non-GPU SHM transport, and the existing
+tests keep working unchanged.
+
+We deliberately route through CPython's bundled ``_posixshmem`` C
+extension (used internally by :mod:`multiprocessing.shared_memory`)
+rather than the higher-level :class:`SharedMemory` wrapper. The
+wrapper keeps an internal ``memoryview`` over its own ``mmap``;
+when callers also export a buffer (via
+``ctypes.c_uint8.from_buffer(shm.buf)`` / ``torch.frombuffer(...)``),
+:meth:`SharedMemory.close` invoked from ``__del__`` at interpreter
+shutdown raises ``BufferError: cannot close exported pointers
+exist``. Owning the ``mmap`` ourselves and pairing every alloc with
+an explicit ``shm_munmap`` keeps shutdown silent on macOS and Linux
+alike.
+
+The previous hand-rolled libc/librt implementation tripped over
+macOS' shm_open MAC label propagation when certain native
+extensions (torch + a few others) were already loaded in the
+parent process, producing spurious ``errno=13 / EACCES`` failures
+on the child side. Routing through ``_posixshmem.shm_open`` -- the
+same underlying entry point CPython's stdlib uses -- fixes that
+and is identical on Linux.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+import atexit
+import ctypes
+import logging
+import mmap as _mmap
+import os
+import threading
+
+# Third Party
+import _posixshmem  # type: ignore[import-not-found]
+
+logger = logging.getLogger(__name__)
+
+
+def _strip_leading_slash(name: str) -> str:
+    """Normalise a name to the bare form (no leading ``/``).
+
+    Callers historically embed the POSIX leading slash; we keep the
+    on-wire name slash-prefixed but feed the bare form to
+    ``_posixshmem.shm_open``-derived helpers that prepend it again.
+    """
+    return name[1:] if name.startswith("/") else name
+
+
+def _slashed(name: str) -> str:
+    """Inverse of :func:`_strip_leading_slash` for shm_open calls."""
+    return name if name.startswith("/") else "/" + name
+
+
+# Per-process registry mapping the public ``int`` address back to the
+# ``mmap`` object that owns the mapping, so a later ``shm_munmap`` can
+# call ``mmap.close()`` exactly once and avoid leaking pages. Owners
+# (creators) also remember the name so ``shm_unlink`` can find it
+# without a re-open round-trip.
+_REGISTRY_LOCK = threading.Lock()
+_ADDR_TO_MMAP: dict[int, _mmap.mmap] = {}
+_OWNED_NAMES: set[str] = set()
+
+
+def _open_and_mmap(name: str, nbytes: int, *, create: bool) -> tuple[_mmap.mmap, int]:
+    """Open (or create) a POSIX SHM segment and ``mmap`` it.
+
+    Returns a ``(mmap_obj, base_addr)`` pair. The fd is always closed
+    before returning so we don't leak descriptors; the kernel keeps
+    the mapping alive as long as ``mmap_obj`` stays alive.
+    """
+    flags = os.O_RDWR | (os.O_CREAT | os.O_EXCL if create else 0)
+    fd = _posixshmem.shm_open(_slashed(name), flags, mode=0o600)
+    mm: _mmap.mmap | None = None
+    try:
+        if create:
+            os.ftruncate(fd, nbytes)
+        mm = _mmap.mmap(fd, nbytes, access=_mmap.ACCESS_WRITE)
+        addr = _addr_of_mmap(mm)
+    except BaseException:
+        if mm is not None:
+            mm.close()
+        if create:
+            try:
+                _posixshmem.shm_unlink(_slashed(name))
+            except OSError:
+                logger.warning(
+                    "shm_unlink failed during cleanup of %s",
+                    name,
+                    exc_info=True,
+                )
+        raise
+    finally:
+        os.close(fd)
+    return mm, addr
+
+
+def _addr_of_mmap(mm: _mmap.mmap) -> int:
+    """Return the base address of an ``mmap`` without leaking a buffer view.
+
+    A single-byte ctypes view is created just long enough to read the
+    base address, then dropped before this function returns; once it is
+    out of scope the mmap has no exported pointers, so a later
+    ``mm.close()`` can complete cleanly.  A 1-byte view is sufficient
+    -- ``ctypes.addressof`` returns the start of the buffer regardless
+    of its declared length.
+    """
+    view = (ctypes.c_uint8 * 1).from_buffer(mm)
+    addr = ctypes.addressof(view)
+    del view
+    return addr
+
+
+def shm_create_readwrite(name: str, nbytes: int) -> int:
+    """Create a new shared-memory segment and return its mmap address.
+
+    Mirrors the previous ``shm_open(O_CREAT|O_EXCL) + ftruncate +
+    mmap`` sequence: collisions raise ``OSError`` (``FileExistsError``
+    is a subclass), and a failure mid-way fully tears down what was
+    allocated.
+
+    Args:
+        name: The name of the shared-memory segment.
+        nbytes: The size of the segment in bytes.
+
+    Returns:
+        The virtual address of the mapped segment.
+
+    Raises:
+        OSError: If the segment already exists or creation fails.
+    """
+    sm_name = _strip_leading_slash(name)
+    mm, addr = _open_and_mmap(sm_name, nbytes, create=True)
+    with _REGISTRY_LOCK:
+        _ADDR_TO_MMAP[addr] = mm
+        _OWNED_NAMES.add(sm_name)
+    return addr
+
+
+def shm_map_readwrite(name: str, nbytes: int) -> int:
+    """Open an existing shared-memory segment and return its address.
+
+    ``nbytes`` must match the segment's actual size; ``mmap`` will
+    raise on a mismatch.
+
+    Args:
+        name: The name of the shared-memory segment.
+        nbytes: The size of the segment in bytes.
+
+    Returns:
+        The virtual address of the mapped segment.
+
+    Raises:
+        OSError: If the segment cannot be opened or mapped.
+    """
+    sm_name = _strip_leading_slash(name)
+    mm, addr = _open_and_mmap(sm_name, nbytes, create=False)
+    with _REGISTRY_LOCK:
+        _ADDR_TO_MMAP[addr] = mm
+    return addr
+
+
+def shm_munmap(addr: int, nbytes: int = 0) -> None:
+    """Best-effort release of a previously mapped segment by address.
+
+    The underlying mmap is closed exactly once; subsequent calls with
+    the same address are no-ops.
+
+    Args:
+        addr: The virtual address of the mapped segment.
+        nbytes: Unused; kept for API compatibility so callers that
+            already pass the size do not need to be updated.
+    """
+    if not addr:
+        return
+    with _REGISTRY_LOCK:
+        mm = _ADDR_TO_MMAP.pop(addr, None)
+    if mm is None:
+        return
+    try:
+        mm.close()
+    except (BufferError, ValueError) as exc:
+        # ``BufferError`` means callers still hold an exported view
+        # (e.g. a torch tensor backed by this mmap); they will release
+        # the mapping themselves on GC. ``ValueError`` means already
+        # closed -- treat both as best-effort no-ops.
+        logger.warning(
+            "shm_munmap: mmap.close() skipped for addr=%#x: %s",
+            addr,
+            exc,
+        )
+
+
+def shm_unlink(name: str) -> None:
+    """Best-effort segment removal.
+
+    Idempotent: a missing segment is treated as a successful
+    no-op so callers can blindly call this on shutdown.
+
+    Args:
+        name: The name of the shared-memory segment to unlink.
+    """
+    sm_name = _strip_leading_slash(name)
+    with _REGISTRY_LOCK:
+        _OWNED_NAMES.discard(sm_name)
+    try:
+        _posixshmem.shm_unlink(_slashed(sm_name))
+    except FileNotFoundError:
+        logger.debug("shm_unlink: segment %s already removed", sm_name)
+    except OSError:
+        # Mirrors the historical "best effort" contract -- e.g.
+        # double-unlink on shutdown should never raise.
+        logger.warning(
+            "shm_unlink: failed to unlink %s",
+            sm_name,
+            exc_info=True,
+        )
+
+
+def _atexit_cleanup() -> None:
+    """Unlink and munmap any SHM segments still owned by this process."""
+    with _REGISTRY_LOCK:
+        names = list(_OWNED_NAMES)
+        mmaps = list(_ADDR_TO_MMAP.values())
+        _ADDR_TO_MMAP.clear()
+        _OWNED_NAMES.clear()
+    for mm in mmaps:
+        try:
+            mm.close()
+        except (BufferError, OSError) as exc:
+            logger.warning("atexit: mmap.close() failed: %s", exc)
+    for n in names:
+        try:
+            _posixshmem.shm_unlink(_slashed(n))
+        except OSError as exc:
+            logger.warning("atexit: shm_unlink(%s) failed: %s", n, exc)
+
+
+atexit.register(_atexit_cleanup)
+
+
+def shm_open_pool_as_mmap(name: str, nbytes: int) -> _mmap.mmap:
+    """Open an existing segment as an independent ``mmap.mmap`` object.
+
+    Convenience helper for non-GPU SHM transports that consume the
+    segment via ``torch.frombuffer(mmap_obj, ...)`` rather than a raw
+    address. The returned mmap is independent of any registry entry,
+    so the caller takes ownership and is responsible for closing it.
+
+    Args:
+        name: The name of the shared-memory segment.
+        nbytes: The size of the segment in bytes.
+
+    Returns:
+        An independent ``mmap.mmap`` object backed by the segment.
+
+    Raises:
+        OSError: If the segment cannot be opened or mapped.
+    """
+    sm_name = _strip_leading_slash(name)
+    fd = _posixshmem.shm_open(_slashed(sm_name), os.O_RDWR, mode=0o600)
+    try:
+        return _mmap.mmap(fd, nbytes, access=_mmap.ACCESS_WRITE)
+    finally:
+        os.close(fd)
diff --git a/lmcache/v1/multiprocess/protocol.py b/lmcache/v1/multiprocess/protocol.py
new file mode 100644
index 0000000..7cad4bb
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocol.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Main RPC protocol for the LMCache core server and clients.
+
+This module serves as the main entry point for the protocol system.
+All protocol definitions are now organized in the protocols/ subdirectory:
+- protocols/base.py: RequestType enum, HandlerType, ProtocolDefinition
+- protocols/engine.py: Core KV cache operations (REGISTER, STORE, RETRIEVE, etc.)
+- protocols/controller.py: Cache management operations (CLEAR, GET_CHUNK_SIZE)
+- protocols/debug.py: Debug and testing operations (NOOP)
+
+The protocol definitions are loaded and validated during initialization.
+"""
+
+# Standard
+from typing import Any, Optional
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.protocols import initialize_protocols
+from lmcache.v1.multiprocess.protocols.base import HandlerType, RequestType
+
+# Initialize the protocol system
+# This loads all protocol definitions and validates them against the RequestType enum
+_PROTOCOL_DEFINITIONS = initialize_protocols()
+
+# Type aliases for backwards compatibility
+InstanceID = int
+KeyType = IPCCacheServerKey
+
+
+def get_payload_classes(req_type: RequestType) -> list[Any]:
+    """
+    Get the expected payload classes for a request type.
+
+    Args:
+        req_type: The request type to look up
+
+    Returns:
+        List of expected payload classes in order
+
+    Raises:
+        ValueError: If the request type is not recognized
+    """
+    if pd := _PROTOCOL_DEFINITIONS.get(req_type, None):
+        return pd.payload_classes
+    else:
+        raise ValueError(f"Invalid request type: {req_type}")
+
+
+def get_response_class(req_type: RequestType) -> Optional[Any]:
+    """
+    Get the expected response class for a request type.
+
+    Args:
+        req_type: The request type to look up
+
+    Returns:
+        Expected response class, or None if no response
+
+    Raises:
+        ValueError: If the request type is not recognized
+    """
+    if pd := _PROTOCOL_DEFINITIONS.get(req_type, None):
+        return pd.response_class
+    else:
+        raise ValueError(f"Invalid request type: {req_type}")
+
+
+def get_handler_type(req_type: RequestType) -> HandlerType:
+    """
+    Get the handler type for a request type.
+
+    Args:
+        req_type: The request type to look up
+
+    Returns:
+        The handler type (SYNC, BLOCKING, or NON_BLOCKING)
+
+    Raises:
+        ValueError: If the request type is not recognized
+    """
+    if pd := _PROTOCOL_DEFINITIONS.get(req_type, None):
+        return pd.handler_type
+    else:
+        raise ValueError(f"Invalid request type: {req_type}")
diff --git a/lmcache/v1/multiprocess/protocols/README.md b/lmcache/v1/multiprocess/protocols/README.md
new file mode 100644
index 0000000..5c7c049
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/README.md
@@ -0,0 +1,213 @@
+# Modular Protocol System
+
+This directory contains the modular protocol definitions for the LMCache multiprocess system.
+
+## Directory Structure
+
+```
+protocols/
+├── README.md           # This file
+├── __init__.py        # Protocol initialization and registration
+├── base.py            # Common types (HandlerType, ProtocolDefinition)
+├── engine.py          # Engine operations (STORE, RETRIEVE, etc.)
+├── controller.py      # Controller operations (CLEAR, GET_CHUNK_SIZE)
+└── debug.py           # Debug operations (NOOP)
+```
+
+## Design Overview
+
+The protocol system is designed to be modular, extensible, and IDE-friendly:
+
+1. **Static Enum with Validation**: The `RequestType` enum is defined statically in `base.py`:
+   - Provides perfect IDE autocomplete and type checking
+   - All request types visible to static analysis tools
+   - Validation ensures enum stays in sync with protocol definitions
+
+2. **Protocol Modules**: Each module (engine, controller, debug) defines:
+   - `REQUEST_NAMES`: List of request type names (for validation)
+   - `get_protocol_definitions()`: Returns dict of name → ProtocolDefinition
+
+3. **Validated Initialization**: The `__init__.py` module:
+   - Collects all protocol definitions from modules
+   - Validates each `RequestType` enum member has a definition
+   - Validates each definition has a corresponding enum member
+   - Ensures no duplicates or mismatches
+
+4. **Main Entry Point**: The `protocol.py` file:
+   - Calls `initialize_protocols()` on import
+   - Provides backwards-compatible API
+   - Exports `RequestType`, helper functions, and types
+
+## Adding New Protocols
+
+To add new protocol operations:
+
+### Option 1: Add to Existing Module
+
+If your operation fits an existing category (engine/controller/debug):
+
+1. **Add to the enum** in `protocols/base.py`:
+   ```python
+   class RequestType(enum.Enum):
+       # ... existing members ...
+       YOUR_NEW_OP = enum.auto()  # Add here
+   ```
+
+2. **Edit the appropriate protocol file** (e.g., `engine.py`):
+   - Add the request name to `REQUEST_NAMES`:
+     ```python
+     REQUEST_NAMES = [
+         "EXISTING_OP",
+         "YOUR_NEW_OP",  # Add here
+     ]
+     ```
+
+3. **Add the protocol definition** in `get_protocol_definitions()`:
+   ```python
+   def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+       return {
+           # ... existing definitions ...
+           "YOUR_NEW_OP": ProtocolDefinition(
+               payload_classes=[int, str],  # Your payload types
+               response_class=bool,          # Your response type
+               handler_type=HandlerType.SYNC,  # or BLOCKING
+           ),
+       }
+   ```
+
+4. **Done!** The validation system will verify everything matches on import.
+
+### Option 2: Create New Protocol Module
+
+If you're adding a new category of operations:
+
+1. **Add enum members** in `protocols/base.py`:
+   ```python
+   class RequestType(enum.Enum):
+       # ... existing members ...
+       
+       # Monitoring operations
+       HEALTH_CHECK = enum.auto()
+       GET_STATS = enum.auto()
+   ```
+
+2. **Create a new protocol file** (e.g., `monitoring.py`):
+   ```python
+   # SPDX-License-Identifier: Apache-2.0
+   """
+   Monitoring protocol definitions.
+   
+   This module defines protocols for:
+   - HEALTH_CHECK: Check server health status
+   - GET_STATS: Get cache statistics
+   """
+   from lmcache.v1.multiprocess.protocols.base import ProtocolDefinition, HandlerType
+
+   REQUEST_NAMES = [
+       "HEALTH_CHECK",
+       "GET_STATS",
+   ]
+
+   def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+       return {
+           "HEALTH_CHECK": ProtocolDefinition(
+               payload_classes=[],
+               response_class=dict,
+               handler_type=HandlerType.SYNC,
+           ),
+           "GET_STATS": ProtocolDefinition(
+               payload_classes=[],
+               response_class=dict,
+               handler_type=HandlerType.SYNC,
+           ),
+       }
+   ```
+
+3. **Register the module** in `__init__.py`:
+   ```python
+   from lmcache.v1.multiprocess.protocols import monitoring  # Import your module
+
+   def initialize_protocols():
+       protocol_modules = [
+           ("engine", engine),
+           ("controller", controller),
+           ("debug", debug),
+           ("monitoring", monitoring),  # Add here
+       ]
+       # ... rest of initialization ...
+   ```
+
+4. **Done!** The new operations are now available as:
+   - `RequestType.HEALTH_CHECK` (with full IDE autocomplete!)
+   - `RequestType.GET_STATS`
+
+## Using the Protocol System
+
+From any module in the codebase:
+
+```python
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    HandlerType,
+    get_payload_classes,
+    get_response_class,
+    get_handler_type,
+)
+
+# Use request types
+req_type = RequestType.STORE
+
+# Get protocol information
+payloads = get_payload_classes(req_type)
+response = get_response_class(req_type)
+handler = get_handler_type(req_type)
+```
+
+## Validation
+
+The initialization system validates at startup:
+
+1. **Enum-Definition Sync**: Every `RequestType` enum member must have a protocol definition
+2. **Definition-Enum Sync**: Every protocol definition must have a corresponding enum member
+3. **No duplicates**: Same request name cannot be defined in multiple modules
+4. **Complete definitions**: All names in `REQUEST_NAMES` must have definitions in `get_protocol_definitions()`
+
+If validation fails, `ProtocolInitializationError` is raised with a descriptive message pointing to the issue.
+
+### Example Error Messages
+
+```python
+# If you add RequestType.NEW_OP but forget the definition:
+ProtocolInitializationError: RequestType enum members {'NEW_OP'} have no protocol definitions.
+Add definitions to the appropriate protocol module or remove from the enum.
+
+# If you add a definition but forget the enum member:
+ProtocolInitializationError: Protocol definition 'NEW_OP' in module 'engine'
+has no corresponding RequestType enum member. Add 'RequestType.NEW_OP' to protocols/base.py
+```
+
+## Current Protocol Groups
+
+### Engine Operations (`engine.py`)
+Core KV cache operations:
+- `REGISTER_KV_CACHE`: Register a KV cache instance
+- `UNREGISTER_KV_CACHE`: Unregister a KV cache instance
+- `STORE`: Store KV cache blocks to the server
+- `RETRIEVE`: Retrieve KV cache blocks from the server
+- `LOOKUP`: Check if keys exist in the cache
+- `END_SESSION`: End a session and clean up resources
+
+### Controller Operations (`controller.py`)
+Cache management and configuration:
+- `CLEAR`: Clear all caches in the server
+- `GET_CHUNK_SIZE`: Get the chunk size configuration
+
+### Debug Operations (`debug.py`)
+Testing and monitoring:
+- `NOOP`: No-operation command for testing/heartbeat
+
+## Handler Types
+
+- `HandlerType.SYNC`: Fast operations that run directly in the main loop
+- `HandlerType.BLOCKING`: Operations that may block, run in a thread pool
+- `HandlerType.NON_BLOCKING`: Not yet supported (for future async handlers)
diff --git a/lmcache/v1/multiprocess/protocols/__init__.py b/lmcache/v1/multiprocess/protocols/__init__.py
new file mode 100644
index 0000000..aa8f151
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/__init__.py
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Protocol initialization and registration system.
+
+This module provides the initialize_protocols() function that:
+1. Collects protocol definitions from all protocol modules
+2. Validates that the static RequestType enum matches protocol definitions
+3. Ensures all enum members have definitions and vice versa
+"""
+
+# First Party
+from lmcache.v1.multiprocess.protocols import (
+    blend,
+    blend_v2,
+    blend_v3,
+    controller,
+    debug,
+    engine,
+    observability,
+    p2p,
+)
+from lmcache.v1.multiprocess.protocols.base import (
+    HandlerType,
+    ProtocolDefinition,
+    RequestType,
+)
+
+
+class ProtocolInitializationError(Exception):
+    """Raised when there's an error during protocol initialization."""
+
+    pass
+
+
+_PROTOCOL_MODULES = [
+    ("engine", engine),
+    ("controller", controller),
+    ("debug", debug),
+    ("blend", blend),
+    ("blend_v2", blend_v2),
+    ("blend_v3", blend_v3),
+    ("observability", observability),
+    ("p2p", p2p),
+]
+
+
+def initialize_protocols() -> dict[RequestType, ProtocolDefinition]:
+    """
+    Initialize the protocol system by collecting all protocol definitions
+    and validating them against the RequestType enum.
+
+    This function:
+    1. Collects protocol definitions from all protocol modules
+    2. Validates that each RequestType enum member has a definition
+    3. Validates that each definition has a corresponding enum member
+    4. Ensures no duplicate or orphaned definitions
+
+    Returns:
+        protocol_definitions: Dict mapping RequestType enum values to
+        ProtocolDefinition
+
+    Raises:
+        ProtocolInitializationError: If there are mismatches between enum and
+        definitions
+    """
+    # Protocol modules to load
+    global _PROTOCOL_MODULES
+
+    # Step 1: Collect protocol definitions from all modules
+    protocol_definitions = {}
+    defined_names = set()
+    name_to_module: dict[str, str] = {}
+
+    for module_name, module in _PROTOCOL_MODULES:
+        module_defs = module.get_protocol_definitions()
+
+        # Check for duplicates across modules
+        for name in module_defs.keys():
+            if name in name_to_module:
+                raise ProtocolInitializationError(
+                    f"Duplicate protocol definition '{name}' found in modules "
+                    f"'{name_to_module[name]}' and '{module_name}'"
+                )
+            name_to_module[name] = module_name
+
+        # Validate that all names in REQUEST_NAMES have definitions
+        for name in module.REQUEST_NAMES:
+            if name not in module_defs:
+                raise ProtocolInitializationError(
+                    f"Request name '{name}' in module '{module_name}' "
+                    f"is listed in REQUEST_NAMES but has no protocol definition"
+                )
+            defined_names.add(name)
+
+        # Convert string names to enum values and store definitions
+        for name, definition in module_defs.items():
+            try:
+                enum_value = RequestType[name]
+                protocol_definitions[enum_value] = definition
+            except KeyError as err:
+                raise ProtocolInitializationError(
+                    f"Protocol definition '{name}' in module '{module_name}' "
+                    f"has no corresponding RequestType enum member. "
+                    f"Add 'RequestType.{name}' to protocols/base.py"
+                ) from err
+
+    # Step 2: Validate that all enum members have definitions
+    all_enum_names = {member.name for member in RequestType}
+    missing_definitions = all_enum_names - defined_names
+
+    if missing_definitions:
+        raise ProtocolInitializationError(
+            f"RequestType enum members {missing_definitions} have no protocol "
+            "definitions. Add definitions to the appropriate protocol module or "
+            "remove from the enum."
+        )
+
+    # Step 3: Validate that all definitions have enum members (already done in step 1)
+    # This is implicitly checked when we do RequestType[name]
+
+    return protocol_definitions
+
+
+# Export the base types for convenience
+__all__ = [
+    "initialize_protocols",
+    "RequestType",
+    "ProtocolDefinition",
+    "HandlerType",
+    "ProtocolInitializationError",
+]
diff --git a/lmcache/v1/multiprocess/protocols/base.py b/lmcache/v1/multiprocess/protocols/base.py
new file mode 100644
index 0000000..fc0b4f9
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/base.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Base types and classes for the multiprocess protocol system.
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import Any, Optional
+import enum
+
+
+class HandlerType(enum.Enum):
+    """
+    Defines how a protocol handler should be executed.
+
+    - SYNC: Handler runs directly in the main loop (fast, non-blocking operations)
+    - BLOCKING: Handler may block, run in a thread pool (I/O, slow operations)
+    - NON_BLOCKING: Not supported yet (for future async handlers)
+    """
+
+    SYNC = enum.auto()
+    BLOCKING = enum.auto()
+    NON_BLOCKING = enum.auto()
+
+
+class RequestType(enum.Enum):
+    """
+    Enum of all available request types in the protocol system.
+
+    When adding a new request type:
+    1. Add the enum member here
+    2. Add the protocol definition in the appropriate protocols/*.py file
+    3. The validation system will ensure they stay in sync
+
+    Organized by category:
+    - Engine operations: Core KV cache operations
+    - Controller operations: Cache management and configuration
+    - Debug operations: Testing and monitoring
+    """
+
+    # Engine operations
+    REGISTER_KV_CACHE = enum.auto()
+    UNREGISTER_KV_CACHE = enum.auto()
+    STORE = enum.auto()
+    RETRIEVE = enum.auto()
+    LOOKUP = enum.auto()
+    QUERY_PREFETCH_STATUS = enum.auto()
+    WAIT_PREFETCH_STATUS = enum.auto()
+    QUERY_PREFETCH_LOOKUP_HITS = enum.auto()
+    FREE_LOOKUP_LOCKS = enum.auto()
+    END_SESSION = enum.auto()
+    REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT = enum.auto()
+    UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT = enum.auto()
+    PREPARE_STORE = enum.auto()
+    COMMIT_STORE = enum.auto()
+    PREPARE_RETRIEVE = enum.auto()
+    COMMIT_RETRIEVE = enum.auto()
+
+    # Controller operations
+    CLEAR = enum.auto()
+    GET_CHUNK_SIZE = enum.auto()
+    PING = enum.auto()
+
+    # Observability operations
+    REPORT_BLOCK_ALLOCATION = enum.auto()
+
+    # Debug operations
+    NOOP = enum.auto()
+
+    # Blend operations
+    CB_REGISTER_KV_CACHE = enum.auto()
+    CB_UNREGISTER_KV_CACHE = enum.auto()
+    CB_STORE_PRE_COMPUTED = enum.auto()
+    CB_LOOKUP_PRE_COMPUTED = enum.auto()
+    CB_RETRIEVE_PRE_COMPUTED = enum.auto()
+    CB_STORE_FINAL = enum.auto()
+
+    # Blend V2 operations (use CBMatchResult instead of list[tuple[int, int]])
+    CB_LOOKUP_PRE_COMPUTED_V2 = enum.auto()
+    CB_RETRIEVE_PRE_COMPUTED_V2 = enum.auto()
+
+    # Blend V3 — paged-aware CB.
+    CB_REGISTER_ROPE_V3 = enum.auto()
+    CB_UNREGISTER_ROPE_V3 = enum.auto()
+    CB_RETRIEVE_PRE_COMPUTED_V3 = enum.auto()
+    CB_UNIFIED_LOOKUP = enum.auto()
+
+    # P2P operations
+    P2P_LOOKUP_AND_LOCK = enum.auto()
+    P2P_QUERY_LOOKUP_RESULTS = enum.auto()
+    P2P_UNLOCK_OBJECTS = enum.auto()
+
+
+@dataclass
+class ProtocolDefinition:
+    """
+    Defines the structure and behavior of a protocol request.
+
+    Attributes:
+        payload_classes: List of expected payload types in order
+        response_class: Expected response type, or None if no response
+        handler_type: How the handler should be executed (SYNC/BLOCKING/NON_BLOCKING)
+    """
+
+    payload_classes: list[Any]
+    response_class: Optional[Any]
+    handler_type: HandlerType
diff --git a/lmcache/v1/multiprocess/protocols/blend.py b/lmcache/v1/multiprocess/protocols/blend.py
new file mode 100644
index 0000000..2695937
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/blend.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Debug protocol definitions for testing and monitoring.
+
+This module defines the protocol for:
+- NOOP: No-operation command for testing connectivity and as a heartbeat
+"""
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey, KVCache
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "CB_LOOKUP_PRE_COMPUTED",
+    "CB_STORE_PRE_COMPUTED",
+    "CB_RETRIEVE_PRE_COMPUTED",
+    "CB_STORE_FINAL",
+    "CB_REGISTER_KV_CACHE",
+    "CB_UNREGISTER_KV_CACHE",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for debug operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # Lookup pre-computed chunks
+        # Payload:
+        #   - key: IPCCacheServerKey - The key containing the token ids
+        # Returns: List of tuples (start, end) indicating the match ranges
+        "CB_LOOKUP_PRE_COMPUTED": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey],
+            response_class=list[tuple[int, int]],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Store pre-computed chunks
+        # Payload:
+        #   - key: IPCCacheServerKey - The key containing the token ids
+        #   - offset: int - The starting offset in the CB KV cache buffer
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - event_ipc_handle: bytes - IPC handle for event notification
+        #                       when the pre-computed chunks are ready
+        # Returns:
+        #   - IPC handle bytes
+        #   - boolean flag indicating if the store is successful
+        "CB_STORE_PRE_COMPUTED": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey, int, int, bytes],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Retrieve pre-computed chunks
+        # Payload:
+        #   - key: IPCCacheServerKey - The key containing the token ids
+        #   - ranges: List[tuple[int, int]] - List of tuples (start, end) indicating
+        #                                     the match ranges to retrieve
+        #   - offset: int - The starting offset in the CB KV cache buffer
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - event_ipc_handle: bytes - IPC handle for event notification when the
+        #                       retrieval is complete
+        # Returns:
+        #   - IPC handle bytes
+        #   - boolean flag indicating if the retrieval is successful
+        "CB_RETRIEVE_PRE_COMPUTED": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey, list[tuple[int, int]], int, int, bytes],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Store final chunks after processing
+        # Payload:
+        #   - key: IPCCacheServerKey - The key containing the token ids
+        #   - offset: int - The starting offset in the CB KV cache buffer
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - event_ipc_handle: bytes - IPC handle for event notification
+        #                       when the final chunks are stored
+        # Returns:
+        #   - IPC handle bytes
+        #   - boolean flag indicating if the store is successful
+        "CB_STORE_FINAL": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey, int, int, bytes],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Register CB KV Cache
+        # Payload:
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - kv_cache: KVCache - The CB KV cache configuration
+        #   - model_name: str - Name of the model associated with the engine
+        #   - world_size: int - World size of the engine
+        # Returns: None
+        "CB_REGISTER_KV_CACHE": ProtocolDefinition(
+            payload_classes=[int, KVCache, str, int],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Unregister CB KV Cache
+        # Payload:
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        # Returns: None
+        "CB_UNREGISTER_KV_CACHE": ProtocolDefinition(
+            payload_classes=[int],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/blend_v2.py b/lmcache/v1/multiprocess/protocols/blend_v2.py
new file mode 100644
index 0000000..1d34b48
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/blend_v2.py
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Blend V2 protocol definitions.
+
+This module defines the V2 variants of blend lookup/retrieve protocols that use
+CBMatchResult instead of plain (start, end) integer tuples.  CBMatchResult carries
+old/cur position ranges plus the pre-computed chunk hash, enabling direct storage
+key lookup without re-hashing on the server side.
+"""
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import CBMatchResult, IPCCacheServerKey
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "CB_LOOKUP_PRE_COMPUTED_V2",
+    "CB_RETRIEVE_PRE_COMPUTED_V2",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for blend V2 lookup/retrieve operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # Lookup pre-computed chunks (V2)
+        # Payload:
+        #   - key: IPCCacheServerKey - The key containing the token ids
+        # Returns: List of CBMatchResult with match positions and chunk hashes
+        "CB_LOOKUP_PRE_COMPUTED_V2": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey],
+            response_class=list[CBMatchResult],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Retrieve pre-computed chunks (V2)
+        # Payload:
+        #   - key: IPCCacheServerKey - The key containing the token ids
+        #   - cb_match_result: list[CBMatchResult] - Match results returned by
+        #                      CB_LOOKUP_PRE_COMPUTED_V2, with per-chunk hashes
+        #                      and query positions
+        #   - offset: int - The starting offset in the CB KV cache buffer
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - event_ipc_handle: bytes - IPC handle for event notification when the
+        #                       retrieval is complete
+        # Returns:
+        #   - IPC handle bytes
+        #   - boolean flag indicating if the retrieval is successful
+        "CB_RETRIEVE_PRE_COMPUTED_V2": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey, list[CBMatchResult], int, int, bytes],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/blend_v3.py b/lmcache/v1/multiprocess/protocols/blend_v3.py
new file mode 100644
index 0000000..c128b6c
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/blend_v3.py
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Blend V3 protocol definitions."""
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import (
+    CBMatchResult,
+    CBUnifiedLookupResult,
+    DeviceIPCWrapper,
+    IPCCacheServerKey,
+)
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+REQUEST_NAMES = [
+    "CB_REGISTER_ROPE_V3",
+    "CB_UNREGISTER_ROPE_V3",
+    "CB_RETRIEVE_PRE_COMPUTED_V3",
+    "CB_UNIFIED_LOOKUP",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """Return V3 blend protocol definitions."""
+    return {
+        # Register rope state on a previously-registered instance.
+        # Payload: (instance_id, cos_sin_caches_ipc, head_size, is_neox_style,
+        #           group_to_cache).
+        # cos_sin_caches_ipc: one IPC handle per distinct rope (dual-RoPE
+        # models send two); group_to_cache maps engine group
+        # idx -> cache idx (empty = all groups use cache 0). Returns: None.
+        "CB_REGISTER_ROPE_V3": ProtocolDefinition(
+            payload_classes=[int, list[DeviceIPCWrapper], int, bool, list[int]],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Drop rope state (paged KV cache lives on; use UNREGISTER_KV_CACHE).
+        # Payload: (instance_id,). Returns: None.
+        "CB_UNREGISTER_ROPE_V3": ProtocolDefinition(
+            payload_classes=[int],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Retrieve pre-computed chunks into the request's paged blocks.
+        # Payload: (key, cb_match_result, gpu_block_ids, instance_id,
+        #           event_ipc_handle).
+        # gpu_block_ids is per engine group (list[list[int]]).
+        "CB_RETRIEVE_PRE_COMPUTED_V3": ProtocolDefinition(
+            payload_classes=[
+                IPCCacheServerKey,
+                list[CBMatchResult],
+                list[list[int]],
+                int,
+                bytes,
+            ],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Unified lookup: server runs prefix lookup + non-prefix fingerprint
+        # match in one RPC, reconciles, and prefetches only the complement.
+        # Payload:
+        #   - key: IPCCacheServerKey carrying the query token IDs.
+        #   - tp_size: tensor-parallel size (for MLA multi-reader locking,
+        #     mirrors LOOKUP).
+        # Returns: CBUnifiedLookupResult(prefix_coverage_tokens,
+        #          non_prefix_segments).
+        "CB_UNIFIED_LOOKUP": ProtocolDefinition(
+            payload_classes=[IPCCacheServerKey, int],
+            # Nullable: handler returns None to defer until both the prefix and
+            # the sparse chunks are in L1 (mirrors dense QUERY_PREFETCH_STATUS).
+            response_class=CBUnifiedLookupResult | None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/controller.py b/lmcache/v1/multiprocess/protocols/controller.py
new file mode 100644
index 0000000..ddd0aa3
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/controller.py
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Controller protocol definitions for cache management and configuration.
+
+This module defines the protocol for:
+- CLEAR: Clear all caches in the server
+- GET_CHUNK_SIZE: Get the chunk size configuration from the server
+"""
+
+# First Party
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "CLEAR",
+    "GET_CHUNK_SIZE",
+    "PING",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for controller operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # Clear all caches
+        # Payload: None
+        # Returns: None
+        "CLEAR": ProtocolDefinition(
+            payload_classes=[],
+            response_class=None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Get chunk size configuration
+        # Payload: None
+        # Returns: int - The chunk size value
+        "GET_CHUNK_SIZE": ProtocolDefinition(
+            payload_classes=[],
+            response_class=int,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Ping
+        # Payload: [instance_id] -- the sender's worker instance ID, or None
+        #   for an untracked prober (the scheduler adapter).
+        # Returns: bool - Always True
+        # BLOCKING on the NORMAL pool: keeps PING off the MQ main loop (where a
+        # slow SYNC REGISTER_KV_CACHE would stall it) and lets pool saturation
+        # surface as worker degraded mode.
+        "PING": ProtocolDefinition(
+            payload_classes=[int | None],
+            response_class=bool,
+            handler_type=HandlerType.BLOCKING,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/debug.py b/lmcache/v1/multiprocess/protocols/debug.py
new file mode 100644
index 0000000..68363b0
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/debug.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Debug protocol definitions for testing and monitoring.
+
+This module defines the protocol for:
+- NOOP: No-operation command for testing connectivity and as a heartbeat
+"""
+
+# First Party
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "NOOP",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for debug operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # No-operation (for testing/heartbeat)
+        # Payload: None
+        # Returns: str - A confirmation message
+        "NOOP": ProtocolDefinition(
+            payload_classes=[],
+            response_class=str,
+            handler_type=HandlerType.SYNC,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/engine.py b/lmcache/v1/multiprocess/protocols/engine.py
new file mode 100644
index 0000000..1b03820
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/engine.py
@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Engine protocol definitions for core KV cache operations.
+
+This module defines the protocol for:
+- REGISTER_KV_CACHE: Register a KV cache instance with the server
+- UNREGISTER_KV_CACHE: Unregister a KV cache instance (GPU path)
+- UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT: Unregister a non-GPU KV cache context
+- STORE: Store KV cache blocks to the server
+- RETRIEVE: Retrieve KV cache blocks from the server
+- LOOKUP: Submit a prefix lookup and return a prefetch job ID
+- QUERY_PREFETCH_STATUS: Poll a prefetch job for its result
+- END_SESSION: End a session and clean up associated resources
+"""
+
+# Standard
+from dataclasses import dataclass, field
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.utils import LayoutHints
+from lmcache.v1.multiprocess.custom_types import (
+    IPCCacheServerKey,
+    KVCache,
+    RegisterEngineDrivenContextPayload,
+)
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+
+@dataclass
+class PrepareStoreResponse:
+    """Response for PREPARE_STORE."""
+
+    context: dict = field(
+        default_factory=dict
+    )  # pickle: {}, shm will put slot info here
+
+
+@dataclass
+class PrepareRetrieveResponse:
+    """Response for PREPARE_RETRIEVE."""
+
+    success: bool
+    data: bytes = b""
+    context: dict = field(
+        default_factory=dict
+    )  # pickle: {}, shm will put slot info here
+
+
+@dataclass
+class RegisterEngineDrivenContextResponse:
+    """Response for REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT."""
+
+    shm_name: str = ""
+    pool_size: int = 0
+
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "REGISTER_KV_CACHE",
+    "UNREGISTER_KV_CACHE",
+    "STORE",
+    "RETRIEVE",
+    "LOOKUP",
+    "QUERY_PREFETCH_STATUS",
+    "WAIT_PREFETCH_STATUS",
+    "QUERY_PREFETCH_LOOKUP_HITS",
+    "FREE_LOOKUP_LOCKS",
+    "END_SESSION",
+    "REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT",
+    "UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT",
+    "PREPARE_STORE",
+    "COMMIT_STORE",
+    "PREPARE_RETRIEVE",
+    "COMMIT_RETRIEVE",
+]
+
+# Type alias for cache keys
+KeyType = IPCCacheServerKey
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for engine operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # Register KV Cache
+        # Payload:
+        #   - instance_id: int - Unique identifier for the engine instance
+        #   - kv_cache: KVCache - The KV cache configuration
+        #   - model_name: str - Name of the model associated with the engine
+        #   - world_size: int - World size of the engine
+        #   - engine_type: EngineType - Which serving engine produced the
+        #     caches (vLLM, SGLang, ...). Drives format detection.
+        #   - layout_hints: LayoutHints - See custom_types.LayoutHints.
+        #   - engine_group_infos: list[EngineGroupInfo] - Engine-neutral KV cache
+        #     group metadata (msgspec-encoded by the message queue).
+        # Returns: None
+        "REGISTER_KV_CACHE": ProtocolDefinition(
+            payload_classes=[
+                int,
+                KVCache,
+                str,
+                int,
+                EngineType,
+                LayoutHints,
+                list[EngineGroupInfo],
+            ],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Unregister KV Cache
+        # Payload:
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        # Returns: None
+        "UNREGISTER_KV_CACHE": ProtocolDefinition(
+            payload_classes=[int],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Store KV cache blocks
+        # Payload:
+        #   - key: KeyType - Cache key to store
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - gpu_block_ids: list[list[int]] - GPU block IDs containing the
+        #     data, indexed by LMCache KV group index.
+        #   - event_ipc_handle: bytes - CUDA event IPC handle for synchronization
+        # Returns: tuple[bytes, bool] - (CUDA event handle, success flag)
+        "STORE": ProtocolDefinition(
+            payload_classes=[KeyType, int, list[list[int]], bytes],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Retrieve KV cache blocks
+        # Payload:
+        #   - key: KeyType - Cache key to retrieve
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        #   - gpu_block_ids: list[list[int]] - GPU block IDs to store
+        #     retrieved data, indexed by LMCache KV group index.
+        #   - event_ipc_handle: bytes - CUDA event IPC handle for synchronization
+        #   - skip_first_n_tokens: int - Number of tokens to skip writing at the
+        #     start of the retrieve range (to avoid overwriting APC-shared blocks)
+        # Returns: tuple[bytes, bool] - (CUDA event handle, success flag)
+        "RETRIEVE": ProtocolDefinition(
+            payload_classes=[KeyType, int, list[list[int]], bytes, int],
+            response_class=tuple[bytes, bool],
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Submit a prefix lookup; job is tracked server-side by request_id
+        # Payload:
+        #   - key: KeyType - Cache key to look up
+        #   - tp_size: int - Tensor-parallel size for
+        #       MLA multi-reader locking
+        # Returns: None
+        "LOOKUP": ProtocolDefinition(
+            payload_classes=[KeyType, int],
+            response_class=None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Query the status of a prefetch job by request_id
+        # Payload:
+        #   - request_id: str - The external request ID passed in the lookup key
+        # Returns: int | None - Chunk count when done, None if still in progress
+        "QUERY_PREFETCH_STATUS": ProtocolDefinition(
+            payload_classes=[str],
+            response_class=int | None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Block until a prefetch job completes, then return its result
+        # Payload:
+        #   - request_id: str - The external request ID passed in the lookup key
+        #   - timeout: float - Max seconds to wait for the prefetch to finish
+        # Returns: int | None - Chunk count when done, None if the wait timed out
+        "WAIT_PREFETCH_STATUS": ProtocolDefinition(
+            payload_classes=[str, float],
+            response_class=int | None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Query the lookup hit chunks before the prefetch is done
+        # Payload:
+        #   - request_id: str - The external request ID passed in the lookup key
+        # Returns: int | None - Chunk count if lookup is done, None if still in progress
+        "QUERY_PREFETCH_LOOKUP_HITS": ProtocolDefinition(
+            payload_classes=[str],
+            response_class=int | None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Free locks (release read locks without a full RETRIEVE)
+        # Payload:
+        #   - key: KeyType - Cache key whose read locks
+        #       to release
+        #   - tp_size: int - Tensor-parallel size for
+        #       MLA multi-reader locking
+        # Returns: None
+        "FREE_LOOKUP_LOCKS": ProtocolDefinition(
+            payload_classes=[KeyType, int],
+            response_class=None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # End session
+        # Payload:
+        #   - request_id: str - Request ID of the session to end
+        # Returns: None
+        "END_SESSION": ProtocolDefinition(
+            payload_classes=[str],
+            response_class=None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Unregister non-GPU KV cache context
+        # Payload:
+        #   - instance_id: int - Unique identifier for the vLLM instance
+        # Returns: None
+        "UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT": ProtocolDefinition(
+            payload_classes=[int],
+            response_class=None,
+            handler_type=HandlerType.SYNC,
+        ),
+        # Register non-GPU KV cache context
+        # Payload:
+        #   - RegisterEngineDrivenContextPayload - all metadata fields in one struct
+        # Returns: RegisterEngineDrivenContextResponse
+        "REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT": ProtocolDefinition(
+            payload_classes=[RegisterEngineDrivenContextPayload],
+            response_class=RegisterEngineDrivenContextResponse,
+            handler_type=HandlerType.SYNC,
+        ),
+        "PREPARE_STORE": ProtocolDefinition(
+            payload_classes=[KeyType, int],
+            response_class=PrepareStoreResponse,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        "COMMIT_STORE": ProtocolDefinition(
+            payload_classes=[KeyType, int, bytes],
+            response_class=bool,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        "PREPARE_RETRIEVE": ProtocolDefinition(
+            payload_classes=[KeyType, int],
+            response_class=PrepareRetrieveResponse,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        "COMMIT_RETRIEVE": ProtocolDefinition(
+            payload_classes=[KeyType, int],
+            response_class=bool,
+            handler_type=HandlerType.BLOCKING,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/observability.py b/lmcache/v1/multiprocess/protocols/observability.py
new file mode 100644
index 0000000..7c6950e
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/observability.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Observability protocol definitions.
+
+This module defines protocols for:
+- REPORT_BLOCK_ALLOCATION: Report vLLM GPU block allocation events
+  (fire-and-forget, no response)
+"""
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import BlockAllocationRecord
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "REPORT_BLOCK_ALLOCATION",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for observability operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # Report vLLM block allocation
+        # Payload:
+        #   - instance_id: int - scheduler instance ID
+        #   - model_name: str - model name from the adapter
+        #   - records: list[BlockAllocationRecord] - allocation records
+        # Returns: None (fire-and-forget)
+        "REPORT_BLOCK_ALLOCATION": ProtocolDefinition(
+            payload_classes=[int, str, list[BlockAllocationRecord]],
+            response_class=None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/protocols/p2p.py b/lmcache/v1/multiprocess/protocols/p2p.py
new file mode 100644
index 0000000..0339657
--- /dev/null
+++ b/lmcache/v1/multiprocess/protocols/p2p.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+P2P protocol definitions for peer lookup-and-lock operations.
+
+This module defines the protocol for:
+- P2P_LOOKUP_AND_LOCK: Look up and read-lock the locally cached prefix
+- P2P_QUERY_LOOKUP_RESULTS: Poll the transfer addresses of a lookup
+- P2P_UNLOCK_OBJECTS: Release the read locks held by a peer
+"""
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.transfer_channel.api import TransferChannelAddress
+from lmcache.v1.multiprocess.protocols.base import HandlerType, ProtocolDefinition
+
+# Define request names for this protocol group
+REQUEST_NAMES = [
+    "P2P_LOOKUP_AND_LOCK",
+    "P2P_QUERY_LOOKUP_RESULTS",
+    "P2P_UNLOCK_OBJECTS",
+]
+
+
+def get_protocol_definitions() -> dict[str, ProtocolDefinition]:
+    """
+    Returns protocol definitions for P2P operations.
+
+    Returns:
+        Dictionary mapping request names to their protocol definitions
+    """
+    return {
+        # Look up and read-lock the locally cached prefix of the given keys
+        # Payload:
+        #   - keys: list[ObjectKey] - Object keys to look up and lock
+        #   - layout_desc: MemoryLayoutDesc - Memory layout of the objects
+        # Returns: int - Task id for querying the lookup status later
+        "P2P_LOOKUP_AND_LOCK": ProtocolDefinition(
+            payload_classes=[list[ObjectKey], MemoryLayoutDesc],
+            response_class=int,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Query the transfer addresses for a lookup task
+        # Payload:
+        #   - task_id: int - Task id returned by P2P_LOOKUP_AND_LOCK
+        # Returns: list[TransferChannelAddress] | None - Addresses when the
+        #   lookup is complete, None if still in progress or already consumed
+        "P2P_QUERY_LOOKUP_RESULTS": ProtocolDefinition(
+            payload_classes=[int],
+            response_class=list[TransferChannelAddress] | None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+        # Release the read locks held on the given keys
+        # Payload:
+        #   - keys: list[ObjectKey] - Object keys to unlock
+        # Returns: None
+        "P2P_UNLOCK_OBJECTS": ProtocolDefinition(
+            payload_classes=[list[ObjectKey]],
+            response_class=None,
+            handler_type=HandlerType.BLOCKING,
+        ),
+    }
diff --git a/lmcache/v1/multiprocess/server.py b/lmcache/v1/multiprocess/server.py
new file mode 100644
index 0000000..5c5a9c8
--- /dev/null
+++ b/lmcache/v1/multiprocess/server.py
@@ -0,0 +1,447 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MPCacheServer compositor and unified cache server entry point."""
+
+# Standard
+import argparse
+import shutil
+import sys
+import time
+
+# Third Party
+import zmq
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.usage_telemetry.mp import InitializeMPUsageContext
+from lmcache.v1.distributed.config import (
+    StorageManagerConfig,
+    add_storage_manager_args,
+    parse_args_to_config,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.mp_observability.config import (
+    ObservabilityConfig,
+    add_observability_args,
+    init_observability,
+    parse_args_to_observability_config,
+)
+from lmcache.v1.mp_observability.trace import maybe_initialize_trace_recorder
+from lmcache.v1.multiprocess.config import (
+    DEFAULT_COORDINATOR_CONFIG,
+    CoordinatorConfig,
+    MPServerConfig,
+    add_mp_server_args,
+    parse_args_to_mp_server_config,
+)
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+from lmcache.v1.multiprocess.engine_module import (
+    EngineModule,
+    HandlerSpec,
+    InstanceLivenessTarget,
+    ThreadPoolType,
+)
+from lmcache.v1.multiprocess.modules.engine_driven_transfer import (
+    EngineDrivenTransferModule,
+)
+from lmcache.v1.multiprocess.modules.lmcache_driven_transfer import (
+    LMCacheDrivenTransferModule,
+)
+from lmcache.v1.multiprocess.modules.lookup import LookupModule
+from lmcache.v1.multiprocess.modules.management import ManagementModule
+from lmcache.v1.multiprocess.modules.p2p_controller import P2PController
+from lmcache.v1.multiprocess.mq import MessageQueueServer
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    get_handler_type,
+    get_payload_classes,
+)
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+
+logger = init_logger(__name__)
+
+
+class MPCacheServer:
+    """Compositor that assembles pluggable engine modules.
+
+    Holds the shared :class:`MPCacheServerContext` and a list of
+    :class:`EngineModule` instances.  Provides aggregated
+    ``report_status()`` and ``close()`` across all modules.
+
+    Args:
+        context: The shared engine context.
+        modules: List of engine modules to compose.
+    """
+
+    def __init__(
+        self,
+        context: MPCacheServerContext,
+        modules: list[EngineModule],
+    ) -> None:
+        self._context = context
+        self._modules = modules
+
+    @property
+    def context(self) -> MPCacheServerContext:
+        """Return the shared engine context."""
+        return self._context
+
+    def report_status(self) -> dict:
+        """Return an aggregated status dict from all modules.
+
+        Returns:
+            Combined status from the storage manager, engine metadata,
+            and each module's ``report_status()`` output.
+        """
+        sm = self._context.storage_manager.report_status()
+        status: dict = {
+            "is_healthy": sm["is_healthy"],
+            "engine_type": self.__class__.__name__,
+            "chunk_size": self._context.chunk_size,
+            "hash_algorithm": self._context.token_hasher.hash_algorithm_name,
+            "active_sessions": self._context.session_manager.active_count(),
+            "storage_manager": sm,
+        }
+        for module in self._modules:
+            status.update(module.report_status())
+        return status
+
+    def close(self) -> None:
+        """Close all modules and release shared resources."""
+        for module in self._modules:
+            module.close()
+        self._context.close()
+        logger.info("MPCacheServer closed")
+
+    # HTTP-layer passthroughs lost in the engine refactor.
+
+    @property
+    def storage_manager(self) -> StorageManager:
+        """Used by ``/quota/*``."""
+        return self._context.storage_manager
+
+    @property
+    def cache_contexts(self) -> dict[int, BaseCacheContext] | None:
+        """Used by ``/cache/checksums``; unwraps :class:`ContextEntry`."""
+        for module in self._modules:
+            if isinstance(module, LMCacheDrivenTransferModule):
+                return {
+                    i: e.cache_context
+                    for i, e in module.context_entries_snapshot().items()
+                }
+        return None
+
+    def clear(self) -> None:
+        """Used by ``/cache/clear``; delegates to :class:`ManagementModule`."""
+        for module in self._modules:
+            if isinstance(module, ManagementModule):
+                module.clear()
+                return
+        raise RuntimeError("MPCacheServer.clear: no ManagementModule registered")
+
+
+def add_handler_helper(
+    server: MessageQueueServer, request_type: RequestType, handler_function
+):
+    """Register a handler with the message queue server.
+
+    Args:
+        server: The message queue server.
+        request_type: The request type to handle.
+        handler_function: The handler callable.
+    """
+    payload_classes = get_payload_classes(request_type)
+    handler_type = get_handler_type(request_type)
+    server.add_handler(
+        request_type,
+        payload_classes,
+        handler_type,
+        handler_function,
+    )
+
+
+def _build_modules(
+    ctx: MPCacheServerContext,
+    mp_config: MPServerConfig,
+    coordinator_config: CoordinatorConfig,
+) -> list[EngineModule]:
+    """Assemble the list of engine modules based on configuration.
+
+    Args:
+        ctx: The shared engine context.
+        mp_config: Server configuration determining which modules to load.
+        coordinator_config: Coordinator connection used by the P2P controller
+            for peer discovery.
+
+    Returns:
+        List of initialized engine modules.
+
+    Raises:
+        ValueError: If blend engine is requested with
+        supported_transfer_mode="engine_driven".
+    """
+    lookup_module = LookupModule(ctx)
+    p2p_controller = P2PController(
+        ctx,
+        mp_config.p2p_config,
+        coordinator_config,
+        mp_config.instance_id,
+    )
+
+    # Build the transfer and blend modules first so the ManagementModule can
+    # be constructed with them as liveness targets / reap listeners. They are
+    # the InstanceLivenessTargets the reaper scans.
+    transfer_modules: list[EngineModule] = []
+    if mp_config.supported_transfer_mode == "lmcache_driven":
+        transfer_modules.append(LMCacheDrivenTransferModule(ctx))
+    elif mp_config.supported_transfer_mode == "engine_driven":
+        transfer_modules.append(EngineDrivenTransferModule(ctx))
+    elif mp_config.supported_transfer_mode == "auto":
+        transfer_modules.append(LMCacheDrivenTransferModule(ctx))
+        transfer_modules.append(EngineDrivenTransferModule(ctx))
+    else:
+        raise ValueError(
+            f"Unsupported supported_transfer_mode '{mp_config.supported_transfer_mode}'"
+        )
+
+    logger.info("Supported transfer mode: %s", mp_config.supported_transfer_mode)
+
+    # Targets the reaper scans (and reap-notifies). The transfer modules own
+    # per-instance liveness; BlendV3Module is appended below as a state mirror.
+    liveness_targets: list[InstanceLivenessTarget] = [
+        m
+        for m in transfer_modules
+        if isinstance(m, (LMCacheDrivenTransferModule, EngineDrivenTransferModule))
+    ]
+
+    # At most one blend module is ever built (engine_type selects one).
+    blend_module: EngineModule | None = None
+
+    if mp_config.engine_type == "blend_legacy":
+        if mp_config.supported_transfer_mode == "engine_driven":
+            raise ValueError(
+                "Legacy blend engine requires supported_transfer_mode to be "
+                f"'lmcache_driven' or 'auto', got "
+                f"'{mp_config.supported_transfer_mode}'"
+            )
+        # First Party
+        from lmcache.v1.multiprocess.modules.blend import BlendModule
+
+        blend_module = BlendModule(ctx)
+
+    # "blend" selects CacheBlend V3 (the current implementation).
+    if mp_config.engine_type == "blend":
+        if mp_config.supported_transfer_mode == "engine_driven":
+            raise ValueError(
+                "blend (V3) engine requires supported_transfer_mode "
+                f"'lmcache_driven' or 'auto', got "
+                f"'{mp_config.supported_transfer_mode}'"
+            )
+        # First Party
+        from lmcache.v1.mp_coordinator.blend_client import (
+            BlendCoordinatorClient,
+        )
+        from lmcache.v1.multiprocess.modules.blend_v3 import BlendV3Module
+
+        transfer_module = next(
+            m for m in transfer_modules if isinstance(m, LMCacheDrivenTransferModule)
+        )
+        # Opt-in: enabled only when LMCACHE_COORDINATOR_URL is set; otherwise
+        # None and the blend module matches purely locally.
+        coordinator = BlendCoordinatorClient.maybe_from_env()
+        blend_v3 = BlendV3Module(
+            ctx,
+            transfer_module,
+            coordinator=coordinator,
+            enable_segmented_prefix=mp_config.enable_segmented_prefix,
+        )
+        blend_module = blend_v3
+        # blend_v3 mirrors per-instance CB rope state, so the reaper must
+        # notify it via drop_instance_state when an instance is reaped.
+        liveness_targets.append(blend_v3)
+
+    management = ManagementModule(
+        ctx,
+        liveness_targets=liveness_targets,
+        worker_reap_timeout_seconds=mp_config.worker_reap_timeout_seconds,
+        worker_registration_grace_seconds=mp_config.worker_registration_grace_seconds,
+    )
+
+    # ManagementModule precedes the transfer/blend modules so close() stops
+    # and joins the reaper before those modules clear their state and before
+    # storage_manager.close() runs.
+    blend_modules = [blend_module] if blend_module is not None else []
+    return [
+        lookup_module,
+        p2p_controller,
+        management,
+        *transfer_modules,
+        *blend_modules,
+    ]
+
+
+def run_cache_server(
+    mp_config: MPServerConfig,
+    storage_manager_config: StorageManagerConfig,
+    obs_config: ObservabilityConfig,
+    return_engine: bool = False,
+    start_prometheus_http_server: bool = True,
+    coordinator_config: CoordinatorConfig = DEFAULT_COORDINATOR_CONFIG,
+) -> tuple[MessageQueueServer, MPCacheServer] | None:
+    """Run the LMCache cache server with ZMQ message queue.
+
+    Args:
+        mp_config: Configuration for the ZMQ multiprocess server.
+        storage_manager_config: Configuration for the storage manager.
+        obs_config: Configuration for the observability stack.
+        coordinator_config: Coordinator connection used by the P2P controller
+            for peer discovery.
+        return_engine: If True, return (server, engine) after starting;
+                       if False, run blocking loop to keep server alive.
+        start_prometheus_http_server: Whether to start a standalone
+            Prometheus HTTP server in a background thread.  Set to
+            ``False`` when an external HTTP framework already serves
+            ``/metrics`` to avoid port conflicts or redundant servers.
+
+    Returns:
+        If return_engine is True: tuple of (MessageQueueServer, MPCacheServer).
+        If return_engine is False: None (blocks until interrupted).
+    """
+    # mp_config.instance_id is this server's single source of identity (set via
+    # --instance-id, else a random UUID v4). Project it onto the OTel
+    # service.instance.id unless observability set that attribute explicitly, so
+    # metrics/traces and coordinator membership all key on the same id.
+    if obs_config.service_instance_id is None:
+        obs_config.service_instance_id = mp_config.instance_id
+
+    event_bus = init_observability(
+        obs_config, start_prometheus_http_server=start_prometheus_http_server
+    )
+
+    maybe_initialize_trace_recorder(event_bus, obs_config, storage_manager_config)
+
+    # When the engine-driven path is loaded (auto or engine_driven):
+    # apply shm_name from mp_config and verify capacity.
+    if mp_config.supported_transfer_mode != "lmcache_driven":
+        mem_cfg = storage_manager_config.l1_manager_config.memory_config
+        if mp_config.shm_name is not None:
+            mem_cfg.shm_name = mp_config.shm_name
+        if mem_cfg.shm_name and sys.platform.startswith("linux"):
+            logger.info("Checking if shm capacity is larger than L1 request")
+            try:
+                free_bytes = shutil.disk_usage("/dev/shm").free
+                if free_bytes < mem_cfg.size_in_bytes:
+                    logger.warning(
+                        "Insufficient /dev/shm capacity: need %d bytes, have %d bytes. "
+                        "Disabling SHM, falling back to pickle.",
+                        mem_cfg.size_in_bytes,
+                        free_bytes,
+                    )
+                    mem_cfg.shm_name = ""
+            except OSError:
+                logger.warning(
+                    "Cannot verify /dev/shm capacity; disabling SHM.",
+                    exc_info=True,
+                )
+                mem_cfg.shm_name = ""
+
+    # blend engine: single object group + full per-chunk SWA KV
+    is_blend = mp_config.engine_type == "blend"
+
+    ctx = MPCacheServerContext(
+        storage_manager_config=storage_manager_config,
+        chunk_size=mp_config.chunk_size,
+        hash_algorithm=mp_config.hash_algorithm,
+        separate_object_groups=mp_config.separate_object_groups and not is_blend,
+        full_sw_kv=is_blend,
+    )
+
+    modules = _build_modules(ctx, mp_config, coordinator_config)
+    engine = MPCacheServer(ctx, modules)
+
+    InitializeMPUsageContext(mp_config, storage_manager_config)
+
+    zmq_context = zmq.Context.instance()
+    server = MessageQueueServer(
+        bind_url=f"tcp://{mp_config.host}:{mp_config.port}",
+        context=zmq_context,
+    )
+
+    all_specs: list[HandlerSpec] = []
+    for module in modules:
+        all_specs.extend(module.get_handlers())
+
+    for spec in all_specs:
+        add_handler_helper(server, spec.request_type, spec.handler)
+
+    affinity_types = [
+        s.request_type for s in all_specs if s.pool == ThreadPoolType.AFFINITY
+    ]
+    normal_types = [
+        s.request_type for s in all_specs if s.pool == ThreadPoolType.NORMAL
+    ]
+    if affinity_types:
+        server.add_affinity_thread_pool(
+            affinity_types, max_workers=mp_config.max_gpu_workers
+        )
+    if normal_types:
+        server.add_normal_thread_pool(
+            normal_types, max_workers=mp_config.max_cpu_workers
+        )
+
+    logger.info(
+        "LMCache ZMQ cache server is running on tcp://%s:%d",
+        mp_config.host,
+        mp_config.port,
+    )
+
+    if not hasattr(torch_dev, "init"):
+        logger.warning(
+            "Backend '%s' does not support init(), skipping device init",
+            torch_device_type,
+        )
+    else:
+        torch_dev.init()
+    server.start()
+
+    logger.info("LMCache cache server is running...")
+
+    if return_engine:
+        return server, engine
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        logger.info("Shutting down server...")
+        event_bus.stop()
+        server.close()
+        engine.close()
+    return None
+
+
+def parse_args():
+    """Parse command line arguments for the cache server.
+
+    Returns:
+        Parsed arguments namespace.
+    """
+    parser = argparse.ArgumentParser(
+        description="LMCache ZMQ Cache Server (without HTTP)"
+    )
+    add_mp_server_args(parser)
+    add_storage_manager_args(parser)
+    add_observability_args(parser)
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    mp_config = parse_args_to_mp_server_config(args)
+    storage_manager_config = parse_args_to_config(args)
+    obs_config = parse_args_to_observability_config(args)
+    run_cache_server(
+        mp_config=mp_config,
+        storage_manager_config=storage_manager_config,
+        obs_config=obs_config,
+    )
diff --git a/lmcache/v1/multiprocess/session.py b/lmcache/v1/multiprocess/session.py
new file mode 100644
index 0000000..22a76fe
--- /dev/null
+++ b/lmcache/v1/multiprocess/session.py
@@ -0,0 +1,234 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Session and SessionManager for tracking per-request state
+in the multiprocess cache server.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Any, Optional, overload
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+from lmcache.v1.periodic_thread import (
+    PeriodicThread,
+    PeriodicThreadRegistry,
+    ThreadLevel,
+    ThreadRunSummary,
+    create_periodic_thread,
+)
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class Session:
+    """Tracks accumulated token IDs and computed chunk hashes for a request.
+
+    Thread-safe: all public methods are protected by an internal lock
+    to allow concurrent access from multiple TP worker threads.
+    """
+
+    request_id: str
+    hasher: TokenHasher
+    token_ids: list[int] = field(default_factory=list)
+    chunk_hashes: list = field(default_factory=list)
+    last_prefix_hash: Any = None
+    num_chunks_processed: int = 0
+    created_at: float = field(default_factory=time.time)
+    lookup_ipc_key: Optional[IPCCacheServerKey] = None
+    extras: dict[str, Any] = field(default_factory=dict)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def set_tokens(self, full_token_ids: list[int]) -> None:
+        """Update the token sequence (idempotent, replaces not extends).
+
+        Args:
+            full_token_ids: Complete token sequence.
+        """
+        with self._lock:
+            self.token_ids = full_token_ids
+
+    @overload
+    def get_hashes(self, start: int, end: int) -> list: ...
+
+    @overload
+    def get_hashes(self, start: int) -> list: ...
+
+    def get_hashes(self, start: int, end: int | None = None) -> list:
+        """Compute and return chunk hashes for the [start, end) token range.
+
+        Internally computes rolling hashes up to end_chunk, skipping
+        already-computed chunks.
+
+        Two calling conventions are supported (declared via ``@overload``)::
+
+            get_hashes(start, end)  # explicit end
+            get_hashes(start)       # end = last full-chunk boundary
+
+        Args:
+            start: Start token index (must be aligned to chunk_size).
+            end: End token index (must be aligned to chunk_size).
+                When omitted (``None``), automatically set to the last
+                full-chunk boundary of the current token sequence.
+
+        Returns:
+            List of hash values for chunks in [start_chunk, end_chunk).
+        """
+        chunk_size = self.hasher.chunk_size
+        assert start % chunk_size == 0, (
+            f"start ({start}) must be a multiple of chunk_size ({chunk_size})"
+        )
+        start_chunk = start // chunk_size
+
+        with self._lock:
+            if end is None:
+                # No explicit end: use the last full-chunk boundary.
+                # Lock must be held here because `self.token_ids` may be
+                # concurrently replaced by `set_tokens` from another thread.
+                end = len(self.token_ids) - (len(self.token_ids) % chunk_size)
+            assert end % chunk_size == 0, (
+                f"end ({end}) must be a multiple of chunk_size ({chunk_size})"
+            )
+            end_chunk = end // chunk_size
+            self._compute_hash(end_chunk)
+            return self.chunk_hashes[start_chunk:end_chunk]
+
+    def _compute_hash(self, end_chunk: int) -> None:
+        """Compute rolling hashes up to end_chunk.
+
+        Uses cached state to skip already-computed chunks.
+
+        Args:
+            end_chunk: Compute hashes up to (but not including) this chunk.
+        """
+        chunk_size = self.hasher.chunk_size
+
+        while self.num_chunks_processed < end_chunk:
+            cs = self.num_chunks_processed * chunk_size
+            ce = cs + chunk_size
+            chunk = self.token_ids[cs:ce]
+
+            prefix = (
+                self.last_prefix_hash
+                if self.last_prefix_hash is not None
+                else self.hasher.none_hash
+            )
+            h = self.hasher.hash_tokens(chunk, prefix)
+            self.last_prefix_hash = h
+            self.chunk_hashes.append(h)
+            self.num_chunks_processed += 1
+
+
+class SessionManager:
+    """Thread-safe manager for per-request sessions."""
+
+    DEFAULT_SESSION_TTL = 600  # 10 minutes
+    DEFAULT_CLEANUP_INTERVAL = 60.0
+
+    def __init__(
+        self,
+        hasher: TokenHasher,
+        ttl: float = DEFAULT_SESSION_TTL,
+        cleanup_interval: float | None = DEFAULT_CLEANUP_INTERVAL,
+    ) -> None:
+        self._hasher = hasher
+        self._ttl = ttl
+        self._sessions: dict[str, Session] = {}
+        self._lock = threading.Lock()
+        self._cleanup_interval = cleanup_interval
+        self._cleanup_thread: PeriodicThread | None = None
+        if cleanup_interval is not None and cleanup_interval > 0:
+            self._cleanup_thread = self._create_cleanup_thread(cleanup_interval)
+            self._cleanup_thread.start()
+
+    def get_or_create(self, request_id: str) -> Session:
+        """Get existing session or create a new one.
+
+        Args:
+            request_id: Unique request identifier.
+
+        Returns:
+            The Session for this request_id.
+        """
+        with self._lock:
+            if request_id not in self._sessions:
+                self._sessions[request_id] = Session(
+                    request_id=request_id, hasher=self._hasher
+                )
+                logger.debug("Created session for request_id=%s", request_id)
+            return self._sessions[request_id]
+
+    def remove(self, request_id: str) -> Optional[Session]:
+        """Remove a session by request_id.
+
+        Args:
+            request_id: Unique request identifier.
+
+        Returns:
+            The removed session, or None if no session was found.
+        """
+        with self._lock:
+            if request_id in self._sessions:
+                session = self._sessions[request_id]
+                del self._sessions[request_id]
+                logger.debug("Removed session for request_id=%s", request_id)
+                return session
+            return None
+
+    def cleanup_expired(self) -> int:
+        """Remove sessions that have exceeded their TTL.
+
+        Returns:
+            Number of sessions removed.
+        """
+        now = time.time()
+        expired = []
+        with self._lock:
+            for rid, session in self._sessions.items():
+                if now - session.created_at > self._ttl:
+                    expired.append(rid)
+            for rid in expired:
+                del self._sessions[rid]
+
+        if expired:
+            logger.info("Cleaned up %d expired sessions", len(expired))
+        return len(expired)
+
+    def active_count(self) -> int:
+        """Return the number of active sessions.
+
+        Returns:
+            Number of currently tracked sessions.
+        """
+        with self._lock:
+            return len(self._sessions)
+
+    def close(self) -> None:
+        """Stop the background cleanup thread and unregister it."""
+        if self._cleanup_thread is None:
+            return
+
+        PeriodicThreadRegistry.get_instance().unregister(self._cleanup_thread.name)
+        self._cleanup_thread.stop()
+        self._cleanup_thread = None
+
+    def _create_cleanup_thread(self, cleanup_interval: float) -> PeriodicThread:
+        def execute_cleanup() -> ThreadRunSummary:
+            removed = self.cleanup_expired()
+            return ThreadRunSummary(
+                success=True,
+                message=f"Removed {removed} expired sessions",
+                extra_info={"removed_sessions": str(removed)},
+            )
+
+        return create_periodic_thread(
+            name=f"SessionManager-cleanup-thread-{id(self):x}",
+            interval=cleanup_interval,
+            execute_fn=execute_cleanup,
+            level=ThreadLevel.MEDIUM,
+        )
diff --git a/lmcache/v1/multiprocess/token_hasher.py b/lmcache/v1/multiprocess/token_hasher.py
new file mode 100644
index 0000000..ee1613c
--- /dev/null
+++ b/lmcache/v1/multiprocess/token_hasher.py
@@ -0,0 +1,450 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+TokenHasher: Standalone hash computation for the multiprocess server.
+
+Hash function loading logic is adapted from token_database.py to avoid
+coupling with TokenDatabase's config/metadata dependencies.
+
+vLLM compatibility notes:
+- PR#20511: Introduced kv_cache_utils.init_none_hash()
+- PR#23673: Renamed sha256_cbor_64bit to sha256_cbor
+- PR#27151: Moved hash functions to vllm.utils.hashing module
+"""
+
+# Standard
+from typing import Any, Callable
+import os
+
+# Third Party
+from numba import njit
+import numpy as np
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def _make_blake3_hash_func() -> Callable:
+    """Create a blake3-based hash function compatible with the
+    (prefix_hash, tuple(tokens), None) calling convention."""
+    # Standard
+    import struct
+
+    # Third Party
+    import blake3 as _blake3
+
+    def blake3_hash(args):
+        prefix_hash, tokens, _ = args
+        h = _blake3.blake3()
+        # Serialize prefix hash
+        if isinstance(prefix_hash, bytes):
+            h.update(prefix_hash)
+        elif isinstance(prefix_hash, int):
+            h.update(prefix_hash.to_bytes(8, byteorder="big", signed=True))
+        else:
+            h.update(bytes(prefix_hash))
+        # Serialize token IDs in one batch
+        h.update(struct.pack(f">{len(tokens)}I", *tokens))
+        return h.digest()  # 32 bytes
+
+    return blake3_hash
+
+
+class TokenHasher:
+    """Computes rolling prefix hashes for token chunks.
+
+    This class encapsulates the hash function loading and hash computation
+    logic needed by the multiprocess server to convert token IDs into
+    chunk hashes compatible with IPCCacheServerKey (hash mode).
+    """
+
+    def __init__(self, chunk_size: int = 256, hash_algorithm: str = "blake3"):
+        self.chunk_size = chunk_size
+        self.hash_algorithm_name = hash_algorithm
+        self.hash_func = self._get_hash_func(hash_algorithm)
+        self.none_hash = self._init_none_hash()
+        logger.info(
+            "TokenHasher initialized: chunk_size=%d, hash_algorithm=%s",
+            chunk_size,
+            hash_algorithm,
+        )
+
+    def _get_hash_func(self, hash_algorithm: str) -> Callable:
+        """Load hash function with vLLM version compatibility.
+
+        Adapted from TokenDatabase._get_vllm_hash_func (token_database.py:97-168).
+        """
+        if hash_algorithm == "blake3":
+            logger.info("Using blake3 hash function")
+            return _make_blake3_hash_func()
+
+        # Try get_hash_fn_by_name from both locations (PR#27151)
+        for module_path in ["vllm.utils.hashing", "vllm.utils"]:
+            try:
+                module = __import__(module_path, fromlist=["get_hash_fn_by_name"])
+                get_hash_fn_by_name = module.get_hash_fn_by_name
+                return self._try_get_hash(
+                    get_hash_fn_by_name, hash_algorithm, module_path
+                )
+            except (ImportError, AttributeError, ValueError):
+                continue
+
+        # Try direct imports as fallback (for older vLLM versions)
+        func_names = (
+            ["sha256_cbor", "sha256_cbor_64bit"]
+            if hash_algorithm in ("sha256_cbor", "sha256_cbor_64bit")
+            else [hash_algorithm]
+        )
+        for module_path in ["vllm.utils.hashing", "vllm.utils"]:
+            for func_name in func_names:
+                try:
+                    module = __import__(module_path, fromlist=[func_name])
+                    hash_func = getattr(module, func_name)
+                    logger.info(
+                        "Loaded '%s' from %s (direct import)", func_name, module_path
+                    )
+                    return hash_func
+                except (ImportError, AttributeError):
+                    continue
+
+        # Fallback to builtin hash
+        logger.warning(
+            "Could not load '%s' from vLLM. Using builtin hash. "
+            "This may cause inconsistencies in distributed caching.",
+            hash_algorithm,
+        )
+
+        # Check PYTHONHASHSEED when using builtin hash
+        if os.getenv("PYTHONHASHSEED") is None:
+            logger.warning(
+                "Using builtin hash without PYTHONHASHSEED set. "
+                "For production environments (non-testing scenarios), you MUST set "
+                "PYTHONHASHSEED to ensure consistent hashing across processes. "
+                "Example: export PYTHONHASHSEED=0"
+            )
+
+        return hash
+
+    def _try_get_hash(
+        self, get_hash_fn_by_name: Callable, hash_algorithm: str, module_name: str
+    ) -> Callable:
+        """Try to get hash function, handling sha256_cbor_64bit rename.
+
+        Adapted from TokenDatabase._try_get_hash (token_database.py:152-168).
+        """
+        # Handle sha256_cbor_64bit -> sha256_cbor rename (PR#23673)
+        names_to_try = (
+            ["sha256_cbor", "sha256_cbor_64bit"]
+            if hash_algorithm in ("sha256_cbor", "sha256_cbor_64bit")
+            else [hash_algorithm]
+        )
+
+        for name in names_to_try:
+            try:
+                hash_func = get_hash_fn_by_name(name)
+                logger.info("Loaded '%s' from %s", name, module_name)
+                return hash_func
+            except ValueError:
+                continue
+        raise ValueError(f"Hash function '{hash_algorithm}' not found in {module_name}")
+
+    def _init_none_hash(self) -> Any:
+        """Initialize NONE_HASH.
+
+        Adapted from TokenDatabase.__init__ (token_database.py:64-82).
+        """
+        if self.hash_algorithm_name != "blake3":
+            try:
+                # Third Party
+                from vllm.v1.core import kv_cache_utils
+
+                if hasattr(kv_cache_utils, "init_none_hash"):
+                    kv_cache_utils.init_none_hash(self.hash_func)
+                    none_hash = kv_cache_utils.NONE_HASH
+                    logger.info("Initialized NONE_HASH=%s from vLLM", none_hash)
+                    return none_hash
+            except (
+                ImportError,
+                AttributeError,
+                ValueError,
+                RuntimeError,
+                # torch._dynamo.device_interface raises AssertionError
+                # when CudaInterface is defined on non-CUDA platforms.
+                AssertionError,
+            ):
+                pass
+
+        # Fallback: compute none_hash using our hash function
+        none_hash = self.hash_func((0, (0,), None))
+        logger.info("Computed NONE_HASH=%s using hash function", none_hash)
+        return none_hash
+
+    def hash_tokens(self, tokens: list[int], prefix_hash: Any = None) -> Any:
+        """Hash one chunk with rolling prefix.
+
+        Returns int or bytes depending on hash_func.
+        """
+        if prefix_hash is None:
+            prefix_hash = self.none_hash
+        return self.hash_func((prefix_hash, tuple(tokens), None))
+
+    def compute_chunk_hashes(
+        self,
+        token_ids: list[int],
+        prefix_hash: Any = None,
+        start: int = 0,
+        end: int | None = None,
+    ) -> list[bytes]:
+        """Compute rolling prefix hashes for complete chunks in a token range.
+
+        The rolling hash is always computed from the beginning of
+        ``token_ids`` (since each chunk's hash depends on all previous
+        chunks), but only hashes for chunks within ``[start, end)`` are
+        returned, and hashing stops at ``end`` to avoid unnecessary work.
+
+        ``start`` and ``end`` are token-level indices and must be
+        multiples of ``chunk_size``. Partial chunks are discarded.
+
+        Args:
+            token_ids: Full token sequence.
+            prefix_hash: Optional initial prefix hash (defaults to none_hash).
+            start: Token-level start index (must be chunk-aligned).
+                Chunks before this index are computed but not returned.
+            end: Token-level end index (must be chunk-aligned). When
+                provided, hashing stops at this index.
+
+        Returns:
+            List of ``bytes`` hash values for chunks in ``[start, end)``.
+        """
+        hashes: list[bytes] = []
+        prefix_hash = self.none_hash if prefix_hash is None else prefix_hash
+        effective_len = min(len(token_ids), end) if end is not None else len(token_ids)
+        num_complete = effective_len - effective_len % self.chunk_size
+        for i in range(0, num_complete, self.chunk_size):
+            prefix_hash = self.hash_tokens(
+                token_ids[i : i + self.chunk_size], prefix_hash
+            )
+            if i >= start:
+                hashes.append(self.hash_to_bytes(prefix_hash))
+        return hashes
+
+    @staticmethod
+    def hash_to_bytes(hash_val: Any) -> bytes:
+        """Convert hash value to bytes for ObjectKey.chunk_hash.
+
+        Handles both bytes (sha256_cbor) and int (builtin hash) return types.
+        """
+        if isinstance(hash_val, bytes):
+            return hash_val  # sha256_cbor already returns bytes
+        return hash_val.to_bytes(8, byteorder="big", signed=True)
+
+
+### Functions for fast rolling/chunk hash and dict lookup
+
+
+@njit(cache=True)
+def rolling_hash_windows_numba(
+    arr_u64: np.ndarray, k: int, base: np.uint64
+) -> np.ndarray:
+    """
+    Compute rolling polynomial hashes over a uint64 array.
+
+    This function computes a polynomial rolling hash over a sliding window
+    of size `k` across the input array `arr_u64`. Arithmetic is performed
+    in uint64 with natural overflow, which is equivalent to computing
+    modulo 2^64.
+
+    Hash definition for a window [x0, x1, ..., x_{k-1}]:
+
+        H = x0 * base^(k-1) + x1 * base^(k-2) + ... + x_{k-1}
+
+    For each subsequent window the hash is updated in O(1):
+
+        H_new = (H - x_old * base^(k-1)) * base + x_new
+
+    Parameters
+    ----------
+    arr_u64 : np.ndarray[np.uint64]
+        Input array of integers encoded as uint64 values.
+
+    k : int
+        Sliding window size.
+
+    base : np.uint64
+        Base of the polynomial hash. Typically a random odd 64-bit number.
+
+    Returns
+    -------
+    np.ndarray[np.uint64]
+        Array of rolling hash values of length:
+
+            len(arr_u64) - k + 1
+
+        Each element corresponds to the hash of one window.
+    """
+    n = arr_u64.shape[0]
+    out = np.empty(n - k + 1, dtype=np.uint64)
+
+    power = np.uint64(1)
+    for _ in range(k - 1):
+        power = power * base  # uint64 overflow = mod 2^64
+
+    h = np.uint64(0)
+    for i in range(k):
+        h = h * base + arr_u64[i]
+    out[0] = h
+
+    j = 1
+    for i in range(k, n):
+        old = arr_u64[i - k]
+        new = arr_u64[i]
+        h = h - old * power
+        h = h * base + new
+        out[j] = h
+        j += 1
+
+    return out
+
+
+@njit(cache=True)
+def chunk_hash_windows_numba(arr_u64, k, base):
+    """Compute polynomial hashes over non-overlapping (chunked) windows.
+
+    Unlike the rolling-hash variant, each window's hash is computed
+    independently from scratch, which is efficient when stride equals the
+    window size (i.e., windows do not overlap).
+
+    The hash for a window starting at position ``s`` is:
+
+        h = arr[s]*base^(k-1) + arr[s+1]*base^(k-2) + ... + arr[s+k-1]
+
+    computed with natural ``uint64`` overflow (mod 2^64).
+
+    Parameters
+    ----------
+    arr_u64 : np.ndarray[np.uint64]
+        1-D array of token values cast to ``uint64``.
+    k : int
+        Window (chunk) size.
+    base : np.uint64
+        Base of the polynomial hash.
+
+    Returns
+    -------
+    np.ndarray[np.uint64]
+        Array of length ``len(arr_u64) // k`` containing one hash per
+        non-overlapping chunk. Trailing tokens that do not fill a
+        complete chunk are ignored.
+    """
+    n = arr_u64.shape[0]
+    num_windows = n // k
+    out = np.empty(num_windows, dtype=np.uint64)
+
+    for w in range(num_windows):
+        h = np.uint64(0)
+        start = w * k
+        # Compute fresh hash for this block
+        for i in range(start, start + k):
+            h = h * base + arr_u64[i]
+        out[w] = h
+    return out
+
+
+@njit(cache=True)
+def update_table_id_numba(
+    hashes_u64: np.ndarray,
+    table_id_i64: np.ndarray,
+    vals_to_update: np.ndarray,
+):
+    """
+    Update the direct-address table with new ID values for given hashes.
+
+    For each hash in `hashes_u64`, compute the index as:
+
+        idx = hash & (table_id_i64.size - 1)
+
+    and update `table_id_i64[idx]` with the corresponding value from
+    `vals_to_update`.
+
+    Parameters
+    ----------
+    hashes_u64 : np.ndarray[np.uint64]
+        Array of hash values to update.
+
+    table_id_i64 : np.ndarray[np.int64]
+        Direct-address lookup table mapping index → ID. This array is
+        modified in-place.
+
+    vals_to_update : np.ndarray[np.int64]
+        Array of new ID values to write into the table. Must have the same
+        length as `hashes_u64`.
+    """
+    n = hashes_u64.shape[0]
+    m = table_id_i64.shape[0]
+
+    for i in range(n):
+        idx = hashes_u64[i] & (m - 1)  # Assuming m is a power of 2
+        table_id_i64[idx] = vals_to_update[i]
+
+
+@njit(cache=True)
+def unique_hits_direct_id_numba(
+    hashes_u64: np.ndarray, table_id_i64: np.ndarray, mask_u64: np.uint64, num_ids: int
+) -> np.ndarray:
+    """
+    Perform direct-address lookup with deduplication of results.
+
+    This function looks up each hash in a direct-address table using
+    the lower bits of the hash:
+
+        idx = hash & mask
+
+    The lookup table maps each index to an integer ID.
+
+    The function returns **unique IDs only**, meaning that if the same
+    ID appears multiple times across the hash stream it will be returned
+    only once.
+
+    Parameters
+    ----------
+    hashes_u64 : np.ndarray[np.uint64]
+        Array of rolling hash values.
+
+    table_id_i64 : np.ndarray[np.int64]
+        Direct-address lookup table mapping index → ID.
+        Values of -1 represent "no entry".
+
+    mask_u64 : np.uint64
+        Bitmask used to compute the index:
+
+            idx = hash & mask_u64
+
+        Typically mask = (2^bits - 1).
+
+    num_ids : int
+        Maximum possible ID value + 1. This determines the size of the
+        internal `seen` array used for deduplication.
+
+    Returns
+    -------
+    np.ndarray[np.int64]
+        Array containing the unique IDs encountered in the lookup stream.
+        Length ≤ len(hashes_u64).
+    """
+
+    # TODO(Jiayi): These allocations can be avoided by pre-allocations
+    seen = np.zeros(num_ids, dtype=np.uint8)  # 1 byte per possible id
+    out = np.empty(hashes_u64.shape[0], dtype=np.int64)
+
+    m = 0
+    for i in range(hashes_u64.shape[0]):
+        idx = hashes_u64[i] & mask_u64
+        hit = table_id_i64[idx]
+
+        if hit != -1 and seen[hit] == 0:
+            seen[hit] = 1
+            out[m] = hit
+            m += 1
+
+    return out[:m]
diff --git a/lmcache/v1/multiprocess/transfer_context/__init__.py b/lmcache/v1/multiprocess/transfer_context/__init__.py
new file mode 100644
index 0000000..1ecc6a0
--- /dev/null
+++ b/lmcache/v1/multiprocess/transfer_context/__init__.py
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Transport package for non-GPU KV data transfer in multiprocess mode.
+
+Re-exports all public symbols from the sub-modules so that existing imports
+from ``lmcache.v1.multiprocess.transfer_context`` work without specifying the
+sub-module.
+"""
+
+# Local
+from .async_engine_driven import AsyncEngineDrivenTransferContext
+from .base import (
+    EngineDrivenContext,
+    EngineDrivenContextMetadata,
+    compute_kv_layout,
+    create_engine_driven_context,
+    gather_paged_kv_to_cpu,
+    scatter_cpu_to_paged_kv,
+)
+from .pickle import EngineDrivenContextPickle
+from .shm import EngineDrivenContextShm, ShmSlotDescriptor
+from .worker_transfer import (
+    EngineDrivenTransferContext,
+    LMCacheDrivenTransferContext,
+    MPTransferMode,
+    TransferContext,
+    create_transfer_context,
+)
+
+__all__ = [
+    "AsyncEngineDrivenTransferContext",
+    "EngineDrivenTransferContext",
+    "LMCacheDrivenTransferContext",
+    "MPTransferMode",
+    "EngineDrivenContext",
+    "EngineDrivenContextMetadata",
+    "EngineDrivenContextPickle",
+    "EngineDrivenContextShm",
+    "ShmSlotDescriptor",
+    "TransferContext",
+    "compute_kv_layout",
+    "create_engine_driven_context",
+    "create_transfer_context",
+    "gather_paged_kv_to_cpu",
+    "scatter_cpu_to_paged_kv",
+]
diff --git a/lmcache/v1/multiprocess/transfer_context/async_engine_driven.py b/lmcache/v1/multiprocess/transfer_context/async_engine_driven.py
new file mode 100644
index 0000000..fd3499b
--- /dev/null
+++ b/lmcache/v1/multiprocess/transfer_context/async_engine_driven.py
@@ -0,0 +1,369 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Async engine-driven data transfer context for multiprocess worker adapters."""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.v1.multiprocess.futures import MessagingFuture
+from lmcache.v1.multiprocess.transfer_context.base import gather_paged_kv_to_cpu
+from lmcache.v1.multiprocess.transfer_context.worker_transfer import (
+    EngineDrivenTransferContext,
+    IPCEvent,
+    _single_group_block_ids,
+)
+
+logger = init_logger(__name__)
+
+# Number of background threads used to run commit (CPU->server) work for the
+# async engine-driven store path. >1 so that a slow gather for one store does
+# not block the commit of another store whose gather already finished.
+DEFAULT_ENGINE_DRIVEN_COMMIT_WORKERS = 4
+
+
+# TODO: async retrieve path TBD, but benefit might be very limited
+class AsyncEngineDrivenTransferContext(EngineDrivenTransferContext):
+    """Fully async engine-driven data transfer context (store-only async).
+
+    "Store-only async" means ``submit_store`` returns an *unresolved* future
+    that resolves only after the deferred gather (GPU->CPU copy) and commit
+    (CPU->server) both complete off the forward thread, while
+    ``submit_retrieve`` stays synchronous and returns an already-resolved
+    future exactly as on the base context.
+
+    Inherits :class:`EngineDrivenTransferContext` and reuses its
+    ``register()`` (layout / SHM registration, no stream dependency) and
+    ``submit_retrieve()`` (this path does not change retrieve). Only the store
+    is made async.
+
+    Store is three-phase, all executed entirely in a background thread:
+
+    1. prepare: call prepare_store() to negotiate buffers with the server
+       (the costliest step in pickle mode due to the synchronous RPC round-trip).
+    2. gather: wait for the forward event on the copy stream, then enqueue
+       GPU->CPU copies. When SHM buffers are available, gather writes directly
+       into SHM views (matching the synchronous path). Otherwise, gather
+       targets pinned staging buffers.
+    3. commit: wait for gather completion (via a recorded CUDA event), then
+       perform commit_store() and resolve the returned future.
+
+    ``submit_store`` performs only O(1) work on the forward thread (registration
+    check and block-id flattening) before submitting all three phases to the
+    background ``commit_executor``, so the forward thread is never blocked by
+    the RPC round-trip or gather kernel launch latency.
+
+    This class is only instantiated by the factory when the device is
+    async-capable, so the constructor creates async resources unconditionally;
+    there is no ``self._async_capable`` flag.
+    """
+
+    def __init__(
+        self,
+        commit_workers: int = DEFAULT_ENGINE_DRIVEN_COMMIT_WORKERS,
+    ) -> None:
+        """Initialize the async context and create its async resources.
+
+        Args:
+            commit_workers: Number of background threads used to run commit
+                (CPU->server) work. >1 so a slow gather for one store does not
+                block the commit of another whose gather is already done.
+        """
+        super().__init__()
+        self._commit_workers = max(1, int(commit_workers))
+        self._copy_stream: Any = torch_dev.Stream()
+        self._commit_executor: ThreadPoolExecutor = ThreadPoolExecutor(
+            max_workers=self._commit_workers,
+            thread_name_prefix="lmcache_engine_driven_commit",
+        )
+        self._inflight_lock = threading.Lock()
+        self._inflight_gather_events: set[Any] = set()
+        # Tracks gather tasks that have been submitted to _commit_executor but
+        # have not yet recorded their CUDA event. flush_inflight_stores waits
+        # on all of these before synchronizing _inflight_gather_events, closing
+        # the window where preemption could overwrite paged KV blocks before an
+        # in-flight gather has had a chance to record its CUDA event.
+        self._pending_stores: set[threading.Event] = set()
+        # Serializes commit_store calls across worker threads, since the
+        # underlying ZMQ socket is not thread-safe and commit_workers defaults
+        # to >1.
+        self._commit_lock = threading.Lock()
+        self._staging_pool: dict[
+            tuple[tuple[int, ...], torch.dtype], list[torch.Tensor]
+        ] = {}
+        self._is_closing = False
+
+    def _alloc_pinned_staging(
+        self, shape: torch.Size, dtype: torch.dtype, count: int
+    ) -> list[torch.Tensor]:
+        """Allocate pinned (page-locked) staging tensors for GPU->CPU copies.
+
+        Tensors are reused from the pool when available to avoid repeated
+        allocations on the hot path.
+
+        Args:
+            shape: Tensor shape to allocate.
+            dtype: Tensor dtype to allocate.
+            count: Number of tensors needed.
+
+        Returns:
+            List of ``count`` pinned CPU tensors.
+        """
+        key = (tuple(shape), dtype)
+        with self._inflight_lock:
+            pooled = self._staging_pool.setdefault(key, [])
+            staged = [pooled.pop() for _ in range(min(len(pooled), count))]
+        if len(staged) == count:
+            return staged
+
+        missing = count - len(staged)
+        for _ in range(missing):
+            try:
+                staged.append(
+                    torch.empty(shape, dtype=dtype, device="cpu", pin_memory=True)
+                )
+            except RuntimeError:
+                # Graceful fallback for CPU-only / pin-memory-disabled setups.
+                logger.warning(
+                    "Falling back to non-pinned CPU staging buffer "
+                    "(shape=%s, dtype=%s)",
+                    tuple(shape),
+                    dtype,
+                )
+                staged.append(torch.empty(shape, dtype=dtype, device="cpu"))
+        return staged
+
+    def _release_staging(self, chunks: list[torch.Tensor]) -> None:
+        """Return staging tensors to the pool for reuse.
+
+        Args:
+            chunks: Tensors previously obtained from :meth:`_alloc_pinned_staging`.
+        """
+        if not chunks:
+            return
+        key = (tuple(chunks[0].shape), chunks[0].dtype)
+        with self._inflight_lock:
+            self._staging_pool.setdefault(key, []).extend(chunks)
+
+    def submit_store(
+        self,
+        _request_id: str,
+        key: Any,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        _event: IPCEvent,
+        blocks_in_chunk: int,
+    ) -> MessagingFuture:
+        """Three-phase async store (prepare, gather and commit all in background).
+
+        Performs only O(1) work on the forward thread (registration check and
+        block-id flattening), then submits all three phases — prepare_store,
+        gather (GPU->CPU), and commit — to the background ``commit_executor``.
+        Returns an unresolved future that resolves only after all three phases
+        complete.
+
+        Args:
+            _request_id: External request identifier (used for logging).
+            key: LMCache key object for the store range.
+            instance_id: Worker process instance identifier.
+            kv_caches: Worker KV cache tensors keyed by layer name.
+            block_ids: vLLM block IDs to store, indexed by LMCache KV group id.
+            _event: Synchronization event; ``wait()`` is called in background.
+            blocks_in_chunk: Number of vLLM blocks per LMCache chunk.
+
+        Returns:
+            An unresolved :class:`MessagingFuture` that resolves to ``True``
+            on success, ``False`` on failure.
+
+        Raises:
+            RuntimeError: If register() was not called first.
+        """
+        if self._engine_driven_context is None:
+            raise RuntimeError(
+                "Engine-driven transfer context is not registered. "
+                "Call register() before submit_store()."
+            )
+        completion: MessagingFuture[bool] = MessagingFuture()
+        engine_driven_context = self._engine_driven_context
+        commit_executor = self._commit_executor
+
+        # Signals when this task has recorded its CUDA event (or exited early),
+        # allowing flush_inflight_stores to safely proceed.
+        gather_launched = threading.Event()
+        try:
+            with self._inflight_lock:
+                if self._is_closing:
+                    completion.set_result(False)
+                    return completion
+                self._pending_stores.add(gather_launched)
+
+            full_block_ids = _single_group_block_ids(block_ids)
+
+            def _prepare_gather_and_commit() -> None:
+                gather_done: Any | None = None
+                ok = False
+                # Whether we gathered directly into SHM views (True) or into
+                # pinned staging buffers that need to be released later (False).
+                used_shm_direct = False
+                staged_chunks: list[torch.Tensor] = []
+                try:
+                    # --- Phase 1: prepare_store ---
+                    # In pickle mode this is the costliest step (sync RPC
+                    # round-trip).  Running it here keeps the forward thread free.
+                    result = engine_driven_context.prepare_store(key, instance_id)
+                    out_buffers, chunk_indices = (
+                        result if result is not None else (None, None)
+                    )
+
+                    if chunk_indices is not None and len(chunk_indices) == 0:
+                        # All chunks are already in cache: no gather, no commit.
+                        ok = True
+                        return
+
+                    num_chunks = (
+                        len(chunk_indices)
+                        if chunk_indices is not None
+                        else len(full_block_ids) // blocks_in_chunk
+                    )
+
+                    # Determine gather target:
+                    # - SHM path (out_buffers available): gather into SHM views
+                    # - Pickle path (no out_buffers): gather into pinned staging
+                    if out_buffers is not None:
+                        gather_target = out_buffers
+                        used_shm_direct = True
+                    else:
+                        layout_desc = engine_driven_context.layout_desc
+                        if not layout_desc.shapes:
+                            raise RuntimeError(
+                                "engine-driven layout_desc.shapes is empty"
+                            )
+                        if not layout_desc.dtypes:
+                            raise RuntimeError(
+                                "engine-driven layout_desc.dtypes is empty"
+                            )
+                        staged_chunks = self._alloc_pinned_staging(
+                            layout_desc.shapes[0],
+                            layout_desc.dtypes[0],
+                            num_chunks,
+                        )
+                        gather_target = staged_chunks
+
+                    # --- Phase 2: gather (GPU->CPU copy on copy stream) ---
+                    with torch.inference_mode(), torch_dev.stream(self._copy_stream):
+                        _event.wait(stream=self._copy_stream)
+
+                        gather_paged_kv_to_cpu(
+                            kv_caches,
+                            full_block_ids,
+                            blocks_in_chunk,
+                            layout_hints=self._layout_hints,
+                            engine_kv_format=self._engine_kv_format,
+                            out=gather_target,
+                            chunk_indices=chunk_indices,
+                        )
+
+                        gather_done = torch_dev.Event()
+                        gather_done.record(self._copy_stream)
+
+                    with self._inflight_lock:
+                        if gather_done is not None:
+                            self._inflight_gather_events.add(gather_done)
+                        self._pending_stores.discard(gather_launched)
+                    gather_launched.set()
+
+                    if gather_done is not None:
+                        gather_done.synchronize()
+
+                    # --- Phase 3: commit ---
+                    with self._commit_lock:
+                        ok = engine_driven_context.commit_store(
+                            key, instance_id, gather_target
+                        )
+
+                    if not ok:
+                        logger.error(
+                            "Async engine-driven commit_store failed for request_id=%s",
+                            _request_id,
+                        )
+                except Exception:
+                    logger.exception(
+                        "Async engine-driven store failed for request_id=%s",
+                        _request_id,
+                    )
+                    ok = False
+                finally:
+                    if not used_shm_direct:
+                        self._release_staging(staged_chunks)
+                    with self._inflight_lock:
+                        if gather_done is not None:
+                            self._inflight_gather_events.discard(gather_done)
+                        self._pending_stores.discard(gather_launched)
+                    gather_launched.set()
+                    completion.set_result(ok)
+
+            # Submitting the task is the ownership-transfer point: once it
+            # succeeds, the closure is solely responsible for releasing staging
+            # buffers and resolving the future. The except below therefore only
+            # handles failures that occur *before* this submit.
+            commit_executor.submit(_prepare_gather_and_commit)
+        except Exception:
+            logger.exception("Failed to submit async engine-driven store")
+            with self._inflight_lock:
+                self._pending_stores.discard(gather_launched)
+            gather_launched.set()
+            completion.set_result(False)
+            return completion
+
+        return completion
+
+    def flush_inflight_stores(self) -> None:
+        """Synchronize all in-flight gather (GPU->CPU) events.
+
+        Called at preemption/eviction time so that vLLM cannot overwrite
+        paged KV blocks before a deferred gather has finished reading them.
+
+        Waits for all submitted-but-not-yet-launched stores to record their
+        CUDA events before synchronizing those events, preventing a race where
+        ``flush_inflight_stores`` returns before a background gather has
+        started.
+        """
+        with self._inflight_lock:
+            pending = list(self._pending_stores)
+        for ev in pending:
+            ev.wait()
+        self._sync_gather_events(suppress_errors=False)
+
+    def close(self) -> None:
+        """Drain in-flight gather/commit work before closing the base context."""
+        with self._inflight_lock:
+            self._is_closing = True
+            pending = list(self._pending_stores)
+        for ev in pending:
+            ev.wait()
+        self._sync_gather_events(suppress_errors=True)
+        self._commit_executor.shutdown(wait=True, cancel_futures=False)
+        super().close()
+
+    def _sync_gather_events(self, suppress_errors: bool = False) -> None:
+        """Synchronize all in-flight gather (GPU->CPU) events.
+
+        Args:
+            suppress_errors: If True, log exceptions instead of propagating.
+        """
+        with self._inflight_lock:
+            gather_events = list(self._inflight_gather_events)
+        for event in gather_events:
+            try:
+                event.synchronize()
+            except Exception:
+                if not suppress_errors:
+                    raise
+                logger.exception("Failed while draining gather events")
diff --git a/lmcache/v1/multiprocess/transfer_context/base.py b/lmcache/v1/multiprocess/transfer_context/base.py
new file mode 100644
index 0000000..e3ceae6
--- /dev/null
+++ b/lmcache/v1/multiprocess/transfer_context/base.py
@@ -0,0 +1,714 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Non-GPU context abstractions and utilities for multiprocess transport.
+
+This module provides:
+- ``EngineDrivenContextMetadata``: layout metadata dataclass for non-CUDA workers.
+- ``EngineDrivenContext``: abstract base class with a two-phase prepare/commit
+  interface for CPU-side KV data transfer. Concrete implementations (e.g.
+  ``EngineDrivenContextPickle``) each decide *how* data is serialised and transported.
+- ``create_engine_driven_context()``: factory that returns the appropriate
+  ``EngineDrivenContext`` subclass.
+- ``compute_kv_layout``, ``gather_paged_kv_to_cpu``, ``scatter_cpu_to_paged_kv``:
+  shared gather/scatter utilities used by all concrete implementations.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+import inspect
+
+# Third Party
+import numpy as np
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.gpu_connector.utils import LayoutHints
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+
+if TYPE_CHECKING:
+    # First Party
+    import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Global capability flag: does lmc_ops.multi_layer_block_kv_transfer accept
+# list[torch.Tensor] directly for lmcache_objects_ptrs, or only list[int]?
+#
+# We inspect the function signature once at import time. If the annotation
+# for ``lmcache_objects_ptrs`` includes ``Tensor``, the op can handle tensors
+# natively and we pass them through. Otherwise (annotation is list[int], or
+# inspect fails entirely) we must convert tensors to data pointers before
+# calling.
+# ---------------------------------------------------------------------------
+def _detect_block_transfer_accepts_tensor() -> bool:
+    """Return True if lmc_ops.multi_layer_block_kv_transfer accepts
+    list[torch.Tensor] for its lmcache_objects_ptrs parameter."""
+    try:
+        # First Party
+        import lmcache.c_ops as _lmc_ops
+
+        fn = _lmc_ops.multi_layer_block_kv_transfer
+
+        # Attempt: use inspect.signature (works on newer pybind11 builds)
+        # Assumptions: if lmcache_objects_ptrs accepts tensors,
+        # it's fallback path, and we do not convert tensors to ptrs explicitly.
+        # TODO: String matching on annotations is fragile. Wait for lmc_ops to
+        # expose a direct version flag (e.g., lmc_ops.__version__) or
+        # an explicit capability boolean.
+        try:
+            sig = inspect.signature(fn)
+            param = sig.parameters.get("lmcache_objects_ptrs")
+            if param is not None and param.annotation is not inspect.Parameter.empty:
+                ann_str = str(param.annotation)
+                if "Tensor" in ann_str:
+                    return True
+                # Annotation exists but no Tensor mention → ptr-only
+                return False
+        except (ValueError, TypeError):
+            pass
+
+    except Exception:
+        # Import failed or any other error → conservative: assume ptr-only
+        pass
+
+    # Default: inspect failed or lmc_ops not available → assume ptr-only
+    return False
+
+
+_LMC_OPS_BLOCK_TRANSFER_ACCEPTS_TENSOR: bool = _detect_block_transfer_accepts_tensor()
+"""If True, ``lmc_ops.multi_layer_block_kv_transfer`` accepts
+``list[torch.Tensor]`` directly for ``lmcache_objects_ptrs``.
+If False, callers must convert tensors to ``list[int]`` data pointers."""
+
+logger.info(
+    "multi_layer_block_kv_transfer mode: %s",
+    "tensor" if _LMC_OPS_BLOCK_TRANSFER_ACCEPTS_TENSOR else "ptr",
+)
+
+
+def _tensors_to_ptrs(tensors: list[torch.Tensor]) -> list[int]:
+    """Convert a list of tensors to a list of their data_ptr() values."""
+    return [t.data_ptr() for t in tensors]
+
+
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EngineDrivenContextMetadata:
+    """Non-GPU context layout metadata for non-CUDA workers.
+
+    Attributes:
+        layout_desc: Memory layout descriptor used to interpret chunk payloads.
+        block_size: Number of tokens per paged block.
+        use_mla: Whether the worker KV format is MLA.
+    """
+
+    layout_desc: MemoryLayoutDesc
+    block_size: int
+    use_mla: bool
+
+
+class EngineDrivenContext(ABC):
+    """Abstract base class for CPU-side KV data transfer contexts.
+
+    All concrete implementations share a common message-queue client and
+    expose a uniform two-phase ``prepare/commit`` interface so that the
+    worker adapter is implementation-agnostic.
+
+    Args:
+        metadata: Layout metadata describing the chunk format.
+        mq_client: Message-queue client used for server communication.
+        mq_timeout: Timeout in seconds for blocking MQ requests.
+    """
+
+    def __init__(
+        self,
+        metadata: EngineDrivenContextMetadata,
+        mq_client: MessageQueueClient,
+        mq_timeout: float,
+    ) -> None:
+        self.metadata = metadata
+        self.mq_client = mq_client
+        self.mq_timeout = mq_timeout
+
+    @property
+    def layout_desc(self) -> MemoryLayoutDesc:
+        """The memory layout descriptor for this context."""
+        return self.metadata.layout_desc
+
+    @abstractmethod
+    def prepare_store(
+        self, key: IPCCacheServerKey, instance_id: int
+    ) -> tuple[list[torch.Tensor], list[int]] | None:
+        """Prepare SHM buffers for a store operation.
+
+        Returns:
+            None: pickle mode — no pre-allocated buffers. Caller gathers all
+                chunks to CPU itself and sends the serialized data via
+                commit_store.
+            ([], []): SHM mode but all chunks already cached. Caller should
+                skip gather and commit entirely.
+            (tensors, chunk_indices): SHM mode with new chunks to write.
+                - tensors[i] is a writable SHM-backed buffer for one chunk.
+                - chunk_indices[i] is the position of that chunk in the full
+                  block_ids sequence (e.g. [0, 2] means only chunks 0 and 2
+                  need writing; chunk 1 is already cached).
+                Caller gathers only these chunks into the provided tensors,
+                then calls commit_store with empty payload.
+        """
+        ...
+
+    @abstractmethod
+    def commit_store(
+        self, key: IPCCacheServerKey, instance_id: int, chunks: list[torch.Tensor]
+    ) -> bool:
+        """Commit store. Pickle: serialize and send. Shm: notify server."""
+        ...
+
+    @abstractmethod
+    def prepare_retrieve(
+        self, key: IPCCacheServerKey, instance_id: int
+    ) -> list[torch.Tensor] | None:
+        """Prepare retrieve. Returns chunks or shm views, or None on miss."""
+        ...
+
+    @abstractmethod
+    def commit_retrieve(self, key: IPCCacheServerKey, instance_id: int) -> bool:
+        """Commit retrieve. Pickle: no-op. Shm: release read locks."""
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release any resources held by this context."""
+        ...
+
+
+def create_engine_driven_context(
+    metadata: EngineDrivenContextMetadata,
+    mq_client: MessageQueueClient,
+    mq_timeout: float,
+    shm_name: str,
+    pool_size: int,
+    *,
+    use_pickle: bool = False,
+) -> EngineDrivenContext:
+    """Factory that returns the appropriate :class:`EngineDrivenContext` implementation.
+
+    Returns SHM-based implementation when shared-memory pool information is
+    available; otherwise falls back to the pickle-based implementation.
+    If SHM initialization fails for any reason (e.g. segment not found,
+    permission error), gracefully falls back to pickle transport.
+
+    Args:
+        metadata: Layout metadata for the non-GPU context.
+        mq_client: Message-queue client for server communication.
+        mq_timeout: Timeout in seconds for blocking MQ requests.
+        shm_name: Shared-memory segment name. Empty values force pickle mode.
+        pool_size: Shared-memory pool size in bytes. Non-positive values force
+            pickle mode.
+        use_pickle: Explicitly use pickle transport even when SHM info is
+            available.
+
+    Returns:
+        A concrete :class:`EngineDrivenContext` instance.
+    """
+    if not shm_name or pool_size <= 0:
+        use_pickle = True
+
+    if not use_pickle:
+        # Local
+        from .shm import EngineDrivenContextShm
+
+        try:
+            logger.info(
+                "Creating EngineDrivenContextShm (shm_name=%s, pool_size=%d)",
+                shm_name,
+                pool_size,
+            )
+            return EngineDrivenContextShm(
+                metadata, mq_client, mq_timeout, shm_name, pool_size
+            )
+        except Exception:
+            logger.warning(
+                "Failed to initialize SHM context (shm_name=%s), "
+                "falling back to pickle transport",
+                shm_name,
+                exc_info=True,
+            )
+
+    # Local
+    from .pickle import EngineDrivenContextPickle
+
+    logger.info("Creating EngineDrivenContextPickle (pickle transport)")
+    return EngineDrivenContextPickle(metadata, mq_client, mq_timeout)
+
+
+# ---------------------------------------------------------------------------
+# Shared gather / scatter utilities
+# ---------------------------------------------------------------------------
+
+
+def compute_kv_layout(
+    kv_caches: dict[str, torch.Tensor],
+    layout_hints: LayoutHints | None = None,
+) -> tuple[int, int, int, str, "lmc_ops.EngineKVFormat"]:
+    """Compute KV layout metadata from KV tensors.
+
+    Args:
+        kv_caches: Per-layer KV tensor mapping.
+        layout_hints: Optional engine layout hints.
+
+    Returns:
+        Tuple of ``(block_size, num_layers, hidden_dim_size, dtype_str,``
+        ``engine_kv_format)``.
+
+    Raises:
+        ValueError: If ``kv_caches`` is empty.
+    """
+    # First Party
+    from lmcache.v1.gpu_connector.utils import (
+        get_block_size,
+        get_hidden_dim_size,
+        get_num_layers,
+        normalize_kv_and_discover_format,
+    )
+
+    tensors = list(kv_caches.values())
+    if not tensors:
+        raise ValueError("kv_caches is empty. Cannot compute KV layout.")
+
+    engine_kv_format, normalized = normalize_kv_and_discover_format(
+        tensors, EngineType.VLLM, layout_hints=layout_hints
+    )
+    block_size = get_block_size(normalized, engine_kv_format)
+    num_layers = get_num_layers(normalized, engine_kv_format)
+    hidden_dim_size = get_hidden_dim_size(normalized, engine_kv_format)
+    dtype_str = str(tensors[0].dtype).replace("torch.", "")
+    return block_size, num_layers, hidden_dim_size, dtype_str, engine_kv_format
+
+
+def gather_paged_kv_to_cpu(
+    kv_caches: dict[str, torch.Tensor],
+    block_ids: list[int],
+    blocks_per_chunk: int,
+    layout_hints: LayoutHints | None = None,
+    engine_kv_format: "lmc_ops.EngineKVFormat" | None = None,
+    out: list[torch.Tensor] | None = None,
+    chunk_indices: list[int] | None = None,
+) -> list[torch.Tensor]:
+    """Gather paged KV blocks into CPU chunk tensors.
+
+    Args:
+        kv_caches: Per-layer KV tensor mapping.
+        block_ids: Flattened block IDs for all chunks.
+        blocks_per_chunk: Number of paged blocks in one LMCache chunk.
+        layout_hints: Optional engine layout hints.
+        engine_kv_format: Optional pre-detected KV format.
+        out: Optional pre-allocated output tensors.  If provided, length
+            must be at least ``len(chunk_indices)`` when ``chunk_indices``
+            is given, or the total number of chunks otherwise.  Any extra
+            buffers beyond the number of gathered chunks are ignored.
+        chunk_indices: Optional list of chunk positions (into the full
+            ``block_ids`` sequence) to gather.  When provided together with
+            ``out``, only those chunks are gathered and written into
+            ``out[i]`` in order.  When ``None``, all chunks are gathered
+            (backward-compatible behaviour).
+
+    Returns:
+        List of CPU tensors, one per chunk. For non-MLA each chunk has shape
+        ``[2, num_layers, chunk_tokens, hidden_dim]`` where dimension ``0``
+        stores ``(K, V)``. For MLA (multi-head latent attention) each chunk
+        has shape ``[num_layers, chunk_tokens, hidden_dim]``.
+
+    Raises:
+        ValueError: If ``out`` is provided with fewer buffers than the number
+            of gathered chunks.
+    """
+    # First Party
+    from lmcache.v1.gpu_connector.utils import (
+        get_block_size,
+        get_hidden_dim_size,
+        get_num_blocks,
+        get_num_layers,
+        is_mla,
+        make_page_buffer_shape_desc,
+        normalize_kv_and_discover_format,
+    )
+    import lmcache.c_ops as lmc_ops
+
+    tensors = list(kv_caches.values())
+    fmt, normalized = normalize_kv_and_discover_format(
+        tensors, EngineType.VLLM, layout_hints=layout_hints
+    )
+    if engine_kv_format is None:
+        engine_kv_format = fmt
+
+    block_size = get_block_size(normalized, engine_kv_format)
+    num_layers = get_num_layers(normalized, engine_kv_format)
+    hidden_dim_size = get_hidden_dim_size(normalized, engine_kv_format)
+    num_blocks = get_num_blocks(normalized, engine_kv_format)
+    num_chunks = len(block_ids) // blocks_per_chunk
+    chunk_tokens = blocks_per_chunk * block_size
+
+    shape_desc = make_page_buffer_shape_desc(
+        normalized,
+        engine_kv_format,
+        layer_idx=0,
+        num_layers_in_group=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+    )
+
+    iter_indices = (
+        list(chunk_indices) if chunk_indices is not None else list(range(num_chunks))
+    )
+    # Require at least one output buffer per gathered chunk. Extra trailing
+    # buffers are ignored (see ``chunks = out[: len(iter_indices)]`` below),
+    # mirroring the scatter-side length check for consistency.
+    if out is not None and len(out) < len(iter_indices):
+        raise ValueError(
+            f"out length ({len(out)}) must be at least the number of "
+            f"gathered chunks ({len(iter_indices)})"
+        )
+
+    # Determine if pinned memory is strictly required
+    # (only for the compiled C++ path which does not accept tensor)
+    requires_pinned = not _LMC_OPS_BLOCK_TRANSFER_ACCEPTS_TENSOR
+    needs_staging = False
+    staged_chunks = []
+
+    if out is None:
+        use_mla = is_mla(engine_kv_format)
+        if use_mla:
+            chunks = [
+                torch.empty(
+                    (num_layers, chunk_tokens, hidden_dim_size),
+                    dtype=tensors[0].dtype,
+                    device=torch.device("cpu"),
+                    pin_memory=requires_pinned,
+                )
+                for _ in iter_indices
+            ]
+        else:
+            chunks = [
+                torch.empty(
+                    (2, num_layers, chunk_tokens, hidden_dim_size),
+                    dtype=tensors[0].dtype,
+                    device=torch.device("cpu"),
+                    pin_memory=requires_pinned,
+                )
+                for _ in iter_indices
+            ]
+    else:
+        _target_out = out[: len(iter_indices)]
+
+        if requires_pinned and not all(t.is_pinned() for t in _target_out):
+            # Core fallback: Unpinned memory (e.g., IPC Shared Memory) detected.
+            # We cannot dynamically call `.pin_memory()` on `out` because it
+            # would allocate new tensors, breaking the caller's expectation
+            # of an in-place update. Instead, we allocate a temporary pinned
+            # staging buffer for the C++ kernel to write to safely.
+            logger.warning(
+                "Unpinned memory detected in 'out' during "
+                "gather_paged_kv_to_cpu (likely Shared Memory). "
+                "Using an internal pinned staging buffer, which "
+                "adds a CPU memory copy overhead."
+            )
+            needs_staging = True
+            staged_chunks = [torch.empty_like(t, pin_memory=True) for t in _target_out]
+            chunks = (
+                staged_chunks  # Point to the safe staging buffer for the H2D transfer
+            )
+        else:
+            # Ideal case: Memory is pinned, or we are using Python fallback.
+            # Ignore any extra trailing buffers beyond what we actually gather so
+            # the kernel's ``total_blocks % num_objects`` invariant still holds.
+            # Return ``out`` unchanged when no trimming is needed so the in-place
+            # fill contract (result is out) is preserved.
+            if len(out) == len(iter_indices):
+                chunks = out
+            else:
+                chunks = out[: len(iter_indices)]
+
+    selected_block_ids: list[int] = []
+    for chunk_idx in iter_indices:
+        selected_block_ids.extend(
+            block_ids[chunk_idx * blocks_per_chunk : (chunk_idx + 1) * blocks_per_chunk]
+        )
+
+    if selected_block_ids:
+        if _LMC_OPS_BLOCK_TRANSFER_ACCEPTS_TENSOR:
+            # Python fallback: accepts tensor list directly for all params.
+            paged_arg = normalized
+            objs_arg = chunks
+            block_ids_arg = selected_block_ids
+
+            # call kernel in one shot
+            lmc_ops.multi_layer_block_kv_transfer(
+                paged_arg,
+                objs_arg,
+                block_ids_arg,
+                tensors[0].device,
+                lmc_ops.TransferDirection.D2H,
+                shape_desc,
+                chunk_tokens,
+                engine_kv_format,
+                0,
+            )
+
+        else:
+            # Compiled C++/CUDA/XPU: requires int64 pointer tensor and list[int].
+            _ptrs_np = np.array(
+                [t.data_ptr() for t in normalized],  # type: ignore[union-attr]
+                dtype=np.uint64,
+            ).view(np.int64)
+            paged_arg = torch.from_numpy(_ptrs_np).to(device=tensors[0].device)
+
+            # This safely points to either the pre-pinned chunks
+            # OR the temporary staged_chunks
+            objs_arg = _tensors_to_ptrs(chunks)
+
+            block_ids_arg = torch.tensor(
+                selected_block_ids, dtype=torch.int64, device=tensors[0].device
+            )
+
+            # Split transfer to respect CUDA kernel's object count limitation
+            MAX_OBJECTS = 4
+            req_blocks_per_obj = blocks_per_chunk
+            total_objects = len(objs_arg)
+
+            for i in range(0, total_objects, MAX_OBJECTS):
+                # Slice object pointers and corresponding block IDs
+                batch_objs_ptrs = objs_arg[i : i + MAX_OBJECTS]
+
+                start_block = i * req_blocks_per_obj
+                end_block = min(
+                    (i + MAX_OBJECTS) * req_blocks_per_obj, len(selected_block_ids)
+                )
+                batch_blocks = block_ids_arg[start_block:end_block]
+
+                # Execute batched transfer
+                lmc_ops.multi_layer_block_kv_transfer(
+                    paged_arg,
+                    batch_objs_ptrs,
+                    batch_blocks,
+                    tensors[0].device,
+                    lmc_ops.TransferDirection.D2H,
+                    shape_desc,
+                    chunk_tokens,
+                    engine_kv_format,
+                    0,
+                )
+
+    # --- Final reconciliation ---
+    # If we used a staging buffer to protect unpinned shared memory,
+    # we now copy the gathered data back into the caller's original tensors.
+    if needs_staging:
+        assert out is not None
+        # The CPU MUST block and wait for the GPU ONLY when a temporary
+        # staging buffer is used. This is because the CPU needs to immediately
+        # read this data for the memory copy below.
+        torch_dev.synchronize()
+
+        for dst, src in zip(_target_out, staged_chunks, strict=False):
+            dst.copy_(src)  # High-speed CPU-to-CPU memory copy
+
+        if len(out) == len(iter_indices):
+            chunks = out
+        else:
+            chunks = _target_out
+
+    # Fast path: The async GPU copy might still be in progress.
+    # We intentionally omit synchronization here for performance.
+    # WARNING: The caller MUST explicitly call `torch_dev.synchronize()`
+    # before consuming these chunks to ensure data validity.
+
+    return chunks
+
+
+def scatter_cpu_to_paged_kv(
+    kv_caches: dict[str, torch.Tensor],
+    block_ids: list[int],
+    chunks: list[torch.Tensor],
+    blocks_per_chunk: int,
+    skip_first_n_tokens: int = 0,
+    layout_hints: LayoutHints | None = None,
+    engine_kv_format: "lmc_ops.EngineKVFormat" | None = None,
+) -> None:
+    """Scatter CPU chunk tensors back into paged KV tensors.
+
+    Args:
+        kv_caches: Per-layer KV tensor mapping to write into.
+        block_ids: Flattened destination block IDs for all chunks.  Length
+            must be at least ``len(chunks) * blocks_per_chunk``; any extra
+            trailing block IDs are ignored.
+        chunks: List of CPU chunk tensors (as returned by
+            :func:`gather_paged_kv_to_cpu`).
+        blocks_per_chunk: Number of paged blocks in one LMCache chunk.
+        skip_first_n_tokens: Token prefix to skip when scattering.  Must be a
+            multiple of ``block_size``; non-aligned values are rounded down
+            to the nearest whole block and an error is logged (matching the
+            GPU transfer path).
+        layout_hints: Optional engine layout hints.
+        engine_kv_format: Optional pre-detected KV format.
+
+    Raises:
+        ValueError: If ``block_ids`` is shorter than
+            ``len(chunks) * blocks_per_chunk``.
+    """
+    # First Party
+    from lmcache.v1.gpu_connector.utils import (
+        get_block_size,
+        get_num_blocks,
+        get_num_layers,
+        make_page_buffer_shape_desc,
+        normalize_kv_and_discover_format,
+    )
+    import lmcache.c_ops as lmc_ops
+
+    if not chunks:
+        return
+    # Require enough block IDs to cover every chunk. Extra trailing block IDs
+    # are ignored by the per-chunk slicing below, mirroring the gather-side
+    # ``out`` length check for consistency.
+    if len(block_ids) < len(chunks) * blocks_per_chunk:
+        raise ValueError(
+            f"block_ids length ({len(block_ids)}) must be at least "
+            f"len(chunks) ({len(chunks)}) * blocks_per_chunk "
+            f"({blocks_per_chunk})"
+        )
+
+    tensors = list(kv_caches.values())
+    fmt, normalized = normalize_kv_and_discover_format(
+        tensors, EngineType.VLLM, layout_hints=layout_hints
+    )
+    if engine_kv_format is None:
+        engine_kv_format = fmt
+
+    block_size = get_block_size(normalized, engine_kv_format)
+    num_layers = get_num_layers(normalized, engine_kv_format)
+    num_blocks = get_num_blocks(normalized, engine_kv_format)
+    chunk_tokens = blocks_per_chunk * block_size
+
+    # Block-level transfer can only skip whole blocks. A non-aligned prefix is
+    # rounded down to the nearest block (matching the lmcache-driven path in
+    # lmcache_driven_transfer.py) rather than raising, so a slightly misaligned skip
+    # degrades gracefully instead of failing the whole retrieve.
+    if skip_first_n_tokens % block_size != 0:
+        logger.error(
+            "skip_first_n_tokens (%d) is not block-aligned (block_size=%d); "
+            "rounding down to %d blocks",
+            skip_first_n_tokens,
+            block_size,
+            skip_first_n_tokens // block_size,
+        )
+    skip_prefix_n_blocks = skip_first_n_tokens // block_size
+
+    shape_desc = make_page_buffer_shape_desc(
+        normalized,
+        engine_kv_format,
+        layer_idx=0,
+        num_layers_in_group=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+    )
+
+    selected_block_ids: list[int] = []
+    for chunk_idx in range(len(chunks)):
+        selected_block_ids.extend(
+            block_ids[chunk_idx * blocks_per_chunk : (chunk_idx + 1) * blocks_per_chunk]
+        )
+
+    if not selected_block_ids:
+        return
+
+    if _LMC_OPS_BLOCK_TRANSFER_ACCEPTS_TENSOR:
+        # Python fallback: accepts tensor list directly for all params.
+        paged_arg = normalized
+        objs_arg = chunks
+        block_ids_arg = selected_block_ids
+
+        lmc_ops.multi_layer_block_kv_transfer(
+            paged_arg,
+            objs_arg,
+            block_ids_arg,
+            tensors[0].device,
+            lmc_ops.TransferDirection.H2D,
+            shape_desc,
+            chunk_tokens,
+            engine_kv_format,
+            skip_prefix_n_blocks,
+        )
+    else:
+        # assuming this is c ops path which requires pin memory
+        # TODO: may have a better approach here
+        # Defensive check: Ensure all incoming CPU chunks are pinned memory.
+        # Otherwise, the underlying CUDA kernel may throw an Illegal
+        # Memory Access error during H2D transfer.
+        if not all(chunk.is_pinned() for chunk in chunks):
+            logger.warning(
+                "Received unpinned CPU tensors in scatter_cpu_to_paged_kv. "
+                "Dynamically pinning memory now, which may incur additional"
+                "synchronization overhead."
+            )
+            chunks = [
+                chunk.pin_memory() if not chunk.is_pinned() else chunk
+                for chunk in chunks
+            ]
+
+        # Compiled C++/CUDA/XPU: requires int64 pointer tensor and list[int].
+        _ptrs_np = np.array(
+            [t.data_ptr() for t in normalized],  # type: ignore[union-attr]
+            dtype=np.uint64,
+        ).view(np.int64)
+        paged_arg = torch.from_numpy(_ptrs_np).to(device=tensors[0].device)
+        objs_arg = _tensors_to_ptrs(chunks)
+        block_ids_arg = torch.tensor(
+            selected_block_ids, dtype=torch.int64, device=tensors[0].device
+        )
+
+        # Batched transfer to satisfy cuda's limitation (max 4 objects)
+        MAX_OBJECTS = 4
+        req_blocks_per_obj = (
+            blocks_per_chunk  # Each chunk corresponds to one object's blocks
+        )
+        total_chunks = len(chunks)
+
+        for i in range(0, total_chunks, MAX_OBJECTS):
+            # Slice objects and block IDs for this batch
+            batch_objs_ptrs = objs_arg[i : i + MAX_OBJECTS]
+
+            start_block = i * req_blocks_per_obj
+            end_block = min(
+                (i + MAX_OBJECTS) * req_blocks_per_obj, len(selected_block_ids)
+            )
+            batch_blocks = block_ids_arg[start_block:end_block]
+
+            # Execute transfer for this batch
+            lmc_ops.multi_layer_block_kv_transfer(
+                paged_arg,
+                batch_objs_ptrs,
+                batch_blocks,
+                tensors[0].device,
+                lmc_ops.TransferDirection.H2D,
+                shape_desc,
+                chunk_tokens,
+                engine_kv_format,
+                skip_prefix_n_blocks if i == 0 else 0,
+            )
+    # Fast path: The async GPU copy might still be in progress.
+    # We intentionally omit synchronization here for performance.
+    # WARNING: The caller MUST explicitly call `torch_dev.synchronize()`
+    # before consuming these chunks to ensure data validity.
diff --git a/lmcache/v1/multiprocess/transfer_context/pickle.py b/lmcache/v1/multiprocess/transfer_context/pickle.py
new file mode 100644
index 0000000..9fbae76
--- /dev/null
+++ b/lmcache/v1/multiprocess/transfer_context/pickle.py
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pickle-based EngineDrivenContext implementation for multiprocess mode."""
+
+# Standard
+import pickle
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import RequestType, get_response_class
+from lmcache.v1.multiprocess.transfer_context.base import (
+    EngineDrivenContext,
+    EngineDrivenContextMetadata,
+)
+
+
+class EngineDrivenContextPickle(EngineDrivenContext):
+    """Pickle-based implementation of :class:`EngineDrivenContext`.
+
+    Transport mechanism:
+    - **Store**: ``prepare_store`` sends ``PREPARE_STORE`` (returns empty slots
+      for pickle mode); ``commit_store`` serialises chunks and sends
+      ``COMMIT_STORE``.
+    - **Retrieve**: ``prepare_retrieve`` sends ``PREPARE_RETRIEVE`` and
+      deserialises the returned bytes; ``commit_retrieve`` sends
+      ``COMMIT_RETRIEVE`` (no-op for pickle).
+    """
+
+    def __init__(
+        self,
+        metadata: EngineDrivenContextMetadata,
+        mq_client: MessageQueueClient,
+        mq_timeout: float,
+    ) -> None:
+        super().__init__(metadata, mq_client, mq_timeout)
+
+    def prepare_store(
+        self, key: IPCCacheServerKey, instance_id: int
+    ) -> tuple[list[torch.Tensor], list[int]] | None:
+        """Send PREPARE_STORE RPC. For pickle, returns no pre-allocated buffers."""
+        future = self.mq_client.submit_request(
+            RequestType.PREPARE_STORE,
+            [key, instance_id],
+            get_response_class(RequestType.PREPARE_STORE),
+        )
+        try:
+            future.result(timeout=self.mq_timeout)
+        except TimeoutError:
+            pass
+        return None
+
+    def commit_store(
+        self, key: IPCCacheServerKey, instance_id: int, chunks: list[torch.Tensor]
+    ) -> bool:
+        """Serialize chunks and send via COMMIT_STORE.
+
+        Returns:
+            ``True`` on success, ``False`` on failure or timeout.
+        """
+        serialised = pickle.dumps(chunks)
+        future = self.mq_client.submit_request(
+            RequestType.COMMIT_STORE,
+            [key, instance_id, serialised],
+            get_response_class(RequestType.COMMIT_STORE),
+        )
+        try:
+            return bool(future.result(timeout=self.mq_timeout))
+        except TimeoutError:
+            return False
+
+    def prepare_retrieve(
+        self, key: IPCCacheServerKey, instance_id: int
+    ) -> list[torch.Tensor] | None:
+        """Send PREPARE_RETRIEVE and deserialize the response data.
+
+        Returns:
+            Chunks on hit, or None on miss/timeout.
+        """
+        future = self.mq_client.submit_request(
+            RequestType.PREPARE_RETRIEVE,
+            [key, instance_id],
+            get_response_class(RequestType.PREPARE_RETRIEVE),
+        )
+        try:
+            response = future.result(timeout=self.mq_timeout)
+        except TimeoutError:
+            return None
+        if not response.success or not response.data:
+            return None
+        chunks: list[torch.Tensor] = pickle.loads(response.data)
+        return chunks
+
+    def commit_retrieve(self, key: IPCCacheServerKey, instance_id: int) -> bool:
+        """Send COMMIT_RETRIEVE (no-op for pickle path)."""
+        future = self.mq_client.submit_request(
+            RequestType.COMMIT_RETRIEVE,
+            [key, instance_id],
+            get_response_class(RequestType.COMMIT_RETRIEVE),
+        )
+        try:
+            future.result(timeout=self.mq_timeout)
+        except TimeoutError:
+            pass
+        return True
+
+    def close(self) -> None:
+        """No-op: the pickle path holds no persistent resources."""
diff --git a/lmcache/v1/multiprocess/transfer_context/shm.py b/lmcache/v1/multiprocess/transfer_context/shm.py
new file mode 100644
index 0000000..117e5a7
--- /dev/null
+++ b/lmcache/v1/multiprocess/transfer_context/shm.py
@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared-memory EngineDrivenContext implementation for multiprocess mode."""
+
+# Standard
+from dataclasses import dataclass
+from multiprocessing import shared_memory
+from multiprocessing.resource_tracker import unregister
+from typing import Any
+import ctypes
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.v1.mp_observability.errors import LMCacheTimeoutError
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import RequestType, get_response_class
+from lmcache.v1.multiprocess.transfer_context.base import (
+    EngineDrivenContext,
+    EngineDrivenContextMetadata,
+)
+from lmcache.v1.platform import current_device_spec
+
+logger = init_logger(__name__)
+
+
+@dataclass(frozen=True)
+class ShmSlotDescriptor:
+    """Describe one tensor slot in the shared-memory pool.
+
+    Args:
+        offset: Byte offset into the shared-memory pool.
+        length: Byte length of the slot.
+        shape: Logical tensor shape to view at the slot.
+        dtype: Torch dtype attribute name, such as ``"bfloat16"``.
+    """
+
+    offset: int
+    length: int
+    shape: list[int]
+    dtype: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the slot descriptor into the MQ context schema.
+
+        Returns:
+            Dict payload shared between the server and worker for one SHM slot.
+        """
+        return {
+            "offset": self.offset,
+            "length": self.length,
+            "shape": self.shape,
+            "dtype": self.dtype,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> "ShmSlotDescriptor":
+        """Parse a slot descriptor from the MQ context schema.
+
+        Args:
+            d: Mapping containing ``offset``, ``length``, ``shape``, and
+                ``dtype`` fields.
+
+        Returns:
+            Parsed immutable slot descriptor.
+
+        Raises:
+            KeyError: If any required field is missing.
+            TypeError: If ``shape`` cannot be converted with ``list(...)``.
+            ValueError: If numeric fields cannot be coerced to integers.
+        """
+        return cls(
+            offset=int(d["offset"]),
+            length=int(d["length"]),
+            shape=list(d["shape"]),
+            dtype=str(d["dtype"]),
+        )
+
+
+class EngineDrivenContextShm(EngineDrivenContext):
+    """Shared-memory implementation of :class:`EngineDrivenContext`."""
+
+    def __init__(
+        self,
+        metadata: EngineDrivenContextMetadata,
+        mq_client: MessageQueueClient,
+        mq_timeout: float,
+        shm_name: str,
+        pool_size: int,
+    ) -> None:
+        super().__init__(metadata, mq_client, mq_timeout)
+        if not shm_name or pool_size <= 0:
+            raise ValueError("shm_name must be non-empty and pool_size must be > 0")
+
+        self._shm_name = shm_name
+        self._pool_size = pool_size
+        self._shm: shared_memory.SharedMemory | None = None
+        self._shm_buffer: memoryview | None = None
+        self._pinned = False
+        self._pinned_ptr = 0
+        self._pinned_size = 0
+        try:
+            self._shm = shared_memory.SharedMemory(
+                name=shm_name.lstrip("/"), create=False
+            )
+            # The SHM segment is owned by the server process. Unregister it
+            # from this worker's resource tracker so that Python does not
+            # unlink the segment when this worker exits.
+            unregister(f"/{self._shm.name}", "shared_memory")
+            self._shm_buffer = self._shm.buf
+            # pin memory is per process
+            # the shm might be pinned on lmcache server side already
+            # pin memory here is for worker side for fast DMA copy
+            self._pin_shm_buffer()
+            logger.info("SHM pinned=%s for shm_name=%s", self._pinned, self._shm_name)
+        except Exception:
+            self._shm = None
+            self._shm_buffer = None
+            raise
+
+    def _make_tensor_view(
+        self,
+        offset: int,
+        length: int,
+        shape: list[int],
+        dtype_str: str,
+    ) -> torch.Tensor:
+        """Create a tensor view over a SHM slot via ``torch.frombuffer``."""
+        dtype = getattr(torch, dtype_str, None)
+        if dtype is None or not isinstance(dtype, torch.dtype):
+            raise ValueError(f"Invalid torch dtype string: {dtype_str}")
+        itemsize = torch.empty((), dtype=dtype).element_size()
+        if itemsize <= 0:
+            raise ValueError(f"Invalid dtype size for {dtype_str}")
+        count = length // itemsize
+        if self._shm_buffer is None:
+            raise RuntimeError(
+                f"Shared memory buffer not initialized for shm_name={self._shm_name}"
+            )
+        tensor_1d = torch.frombuffer(
+            self._shm_buffer, dtype=dtype, count=count, offset=offset
+        )
+        return tensor_1d.view(torch.Size(shape))
+
+    def _build_slot_tensors(self, slots: list[dict[str, Any]]) -> list[torch.Tensor]:
+        descriptors = [ShmSlotDescriptor.from_dict(slot) for slot in slots]
+        return [
+            self._make_tensor_view(
+                offset=descriptor.offset,
+                length=descriptor.length,
+                shape=descriptor.shape,
+                dtype_str=descriptor.dtype,
+            )
+            for descriptor in descriptors
+        ]
+
+    def prepare_store(
+        self, key: IPCCacheServerKey, instance_id: int
+    ) -> tuple[list[torch.Tensor], list[int]] | None:
+        future = self.mq_client.submit_request(
+            RequestType.PREPARE_STORE,
+            [key, instance_id],
+            get_response_class(RequestType.PREPARE_STORE),
+        )
+        # wait() first so a timeout raises exactly one LMCacheTimeoutError
+        # (one event); result() then returns without its own timeout.
+        if not future.wait(timeout=self.mq_timeout):
+            raise LMCacheTimeoutError(
+                f"PREPARE_STORE timed out for instance_id={instance_id} "
+                f"after {self.mq_timeout}s",
+                session_id=key.request_id,
+            )
+        response = future.result()
+        context = response.context if isinstance(response.context, dict) else {}
+        slots = context.get("slots")
+        if not isinstance(slots, list):
+            return None
+        if not slots:
+            # Server explicitly signals all chunks are already cached.
+            return [], []
+        chunk_indices: list[int] = context["chunk_indices"]
+        return self._build_slot_tensors(slots), chunk_indices
+
+    def commit_store(
+        self, key: IPCCacheServerKey, instance_id: int, _chunks: list[torch.Tensor]
+    ) -> bool:
+        future = self.mq_client.submit_request(
+            RequestType.COMMIT_STORE,
+            [key, instance_id, b""],
+            get_response_class(RequestType.COMMIT_STORE),
+        )
+        try:
+            return bool(future.result(timeout=self.mq_timeout))
+        except TimeoutError:
+            return False
+
+    def prepare_retrieve(
+        self, key: IPCCacheServerKey, instance_id: int
+    ) -> list[torch.Tensor] | None:
+        future = self.mq_client.submit_request(
+            RequestType.PREPARE_RETRIEVE,
+            [key, instance_id],
+            get_response_class(RequestType.PREPARE_RETRIEVE),
+        )
+        try:
+            response = future.result(timeout=self.mq_timeout)
+        except TimeoutError:
+            return None
+        if not response.success:
+            return None
+        slots = response.context.get("slots", [])
+        return self._build_slot_tensors(slots) if slots else None
+
+    def commit_retrieve(self, key: IPCCacheServerKey, instance_id: int) -> bool:
+        future = self.mq_client.submit_request(
+            RequestType.COMMIT_RETRIEVE,
+            [key, instance_id],
+            get_response_class(RequestType.COMMIT_RETRIEVE),
+        )
+        try:
+            return bool(future.result(timeout=self.mq_timeout))
+        except TimeoutError:
+            return False
+
+    def close(self) -> None:
+        if self._shm is None:
+            return
+        self._unpin_shm_buffer()
+        try:
+            self._shm.close()
+        finally:
+            self._shm = None
+            self._shm_buffer = None
+
+    def _pin_shm_buffer(self) -> None:
+        """Pin the SHM buffer as page-locked host memory via cudaHostRegister.
+
+        Enables faster async D2H CUDA copies to the SHM region. If pinning is
+        not available or fails, logs a warning and continues without pinning.
+        """
+        if self._shm_buffer is None or not torch_dev.is_available():
+            return
+        try:
+            ptr = ctypes.addressof(ctypes.c_char.from_buffer(self._shm_buffer))
+        except Exception as exc:
+            logger.warning(
+                "Failed to get pointer for shm_name=%s: %r; "
+                "D2H copies will be synchronous",
+                self._shm_name,
+                exc,
+            )
+            return
+        if current_device_spec.pin_memory(ptr, self._pool_size):
+            self._pinned = True
+            self._pinned_ptr = ptr
+            self._pinned_size = self._pool_size
+        else:
+            logger.warning(
+                "pin_memory failed for shm_name=%s ptr=%#x size=%d; "
+                "D2H copies will be synchronous",
+                self._shm_name,
+                ptr,
+                self._pool_size,
+            )
+
+    def _unpin_shm_buffer(self) -> None:
+        """Unpin the SHM buffer if it was previously pinned via cudaHostRegister."""
+        if not self._pinned or self._pinned_ptr == 0:
+            return
+        current_device_spec.unpin_memory(self._pinned_ptr)
+        self._pinned = False
+        self._pinned_ptr = 0
+        self._pinned_size = 0
diff --git a/lmcache/v1/multiprocess/transfer_context/worker_transfer.py b/lmcache/v1/multiprocess/transfer_context/worker_transfer.py
new file mode 100644
index 0000000..409ca03
--- /dev/null
+++ b/lmcache/v1/multiprocess/transfer_context/worker_transfer.py
@@ -0,0 +1,653 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Transfer context abstractions for LMCache multiprocess worker adapters."""
+
+# Standard
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from enum import Enum
+from typing import Any, Callable, Protocol
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.utils import EngineType, init_logger
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.gpu_connector.utils import LayoutHints, is_mla
+from lmcache.v1.multiprocess.custom_types import RegisterEngineDrivenContextPayload
+from lmcache.v1.multiprocess.futures import MessagingFuture
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import RequestType
+from lmcache.v1.multiprocess.protocols.engine import RegisterEngineDrivenContextResponse
+from lmcache.v1.multiprocess.transfer_context.base import (
+    EngineDrivenContext,
+    EngineDrivenContextMetadata,
+    compute_kv_layout,
+    create_engine_driven_context,
+    gather_paged_kv_to_cpu,
+    scatter_cpu_to_paged_kv,
+)
+from lmcache.v1.platform import _registry as platform_registry
+from lmcache.v1.platform import get_device_spec
+
+logger = init_logger(__name__)
+
+# Environment variable that lets the user override the default routing
+# performed by :func:`create_transfer_context`. Accepted values match the
+# string values of :class:`MPTransferMode` (``auto`` / ``engine_driven`` /
+# ``lmcache_driven``); ``auto`` reproduces the historical device-type-based
+# dispatch.
+ENV_MP_TRANSFER_MODE = "LMCACHE_MP_TRANSFER_MODE"
+
+
+# Helper functions
+def _supports_async_primitives() -> bool:
+    """Probe whether the worker device supports the async store primitives.
+
+    The async engine-driven store path needs a stream, an event exposing
+    ``record``/``synchronize``/``wait``, and pinned (page-locked) host memory.
+    When any of these is unavailable (e.g. a CPU-only backend), the factory
+    falls back to the synchronous :class:`EngineDrivenTransferContext`. This
+    dispatch is internal and capability-based; there is no user-facing
+    async/sync flag.
+
+    Returns:
+        True if all required async primitives are available, else False.
+    """
+    if not hasattr(torch_dev, "Stream") or not hasattr(torch_dev, "Event"):
+        return False
+    # CPU-only stub exposes Stream/Event but has no real async capability.
+    if hasattr(torch_dev, "is_available") and not torch_dev.is_available():
+        return False
+    try:
+        stream = torch_dev.Stream()
+        event = torch_dev.Event()
+    except Exception:
+        return False
+    for attr in ("record", "synchronize", "wait"):
+        if not callable(getattr(event, attr, None)):
+            del stream, event
+            return False
+    del stream, event
+    try:
+        probe = torch.empty(1, dtype=torch.uint8, device="cpu", pin_memory=True)
+        del probe
+    except (RuntimeError, TypeError):
+        return False
+    return True
+
+
+def _build_engine_driven_context() -> "TransferContext":
+    """Build the engine-driven context, async when device-capable else sync.
+
+    Routes the ``ENGINE_DRIVEN`` and AUTO branches through a single capability
+    check. ``AsyncEngineDrivenTransferContext`` is imported lazily to avoid an
+    import cycle and to keep the synchronous path free of stream/event
+    dependencies.
+
+    Returns:
+        ``AsyncEngineDrivenTransferContext`` when async primitives are
+        available, otherwise ``EngineDrivenTransferContext``.
+    """
+    if _supports_async_primitives():
+        # First Party
+        from lmcache.v1.multiprocess.transfer_context.async_engine_driven import (
+            AsyncEngineDrivenTransferContext,
+        )
+
+        logger.info("Using AsyncEngineDrivenTransferContext for store path")
+        return AsyncEngineDrivenTransferContext()
+
+    logger.info("Using EngineDrivenTransferContext (sync) for store path")
+    return EngineDrivenTransferContext()
+
+
+class MPTransferMode(str, Enum):
+    """Routing mode used by :func:`create_transfer_context`.
+
+    * ``AUTO``: dispatch by ``tensor.device.type`` (CUDA -> lmcache-driven,
+      others -> engine-driven). Preserves the historical behaviour.
+    * ``ENGINE_DRIVEN``: force :class:`EngineDrivenTransferContext`
+      (worker-side gather / scatter copy path).
+    * ``LMCACHE_DRIVEN``: force :class:`LMCacheDrivenTransferContext`
+      (IPC / SHM zero-copy path). Requires a registered KV-wrapper factory
+      for the device.
+    """
+
+    AUTO = "auto"
+    ENGINE_DRIVEN = "engine_driven"
+    LMCACHE_DRIVEN = "lmcache_driven"
+
+
+def _resolve_mode(mode: "str | MPTransferMode | None") -> MPTransferMode:
+    """Coerce ``mode`` into :class:`MPTransferMode`, falling back to env."""
+    raw = (
+        mode
+        if mode is not None
+        else os.environ.get(ENV_MP_TRANSFER_MODE, MPTransferMode.AUTO.value)
+    )
+    if isinstance(raw, MPTransferMode):
+        return raw
+    try:
+        return MPTransferMode(str(raw).lower())
+    except ValueError as exc:
+        valid = ", ".join(m.value for m in MPTransferMode)
+        raise ValueError(
+            "Invalid MP transfer mode %r (valid: %s)" % (raw, valid)
+        ) from exc
+
+
+def _build_lmcache_driven_context(device_type: str) -> "TransferContext":
+    """Build a :class:`LMCacheDrivenTransferContext` after capability check."""
+    try:
+        platform_registry.get_kv_wrapper_factory(device_type)
+    except ValueError as exc:
+        raise ValueError(
+            "MP transfer mode 'lmcache_driven' is not supported for device type "
+            "%r: no KV-cache wrapper factory is registered. "
+            "Use mode 'engine_driven' or 'auto' instead." % device_type
+        ) from exc
+    device_spec = get_device_spec(device_type)
+    if device_spec and not device_spec.is_handle_transfer_available():
+        raise ValueError(
+            "MP transfer mode 'lmcache_driven' is not available for device type "
+            "%r: required platform capability checks failed. "
+            "Use mode 'engine_driven' or 'auto' instead." % device_type
+        )
+    return LMCacheDrivenTransferContext()
+
+
+class IPCEvent(Protocol):
+    """Protocol for IPC-capable CUDA events used by transport operations."""
+
+    def ipc_handle(self) -> object:
+        """Return an IPC handle consumable by the multiprocess server."""
+
+    def wait(self, stream: object | None = None) -> None:
+        """Make ``stream`` wait for this event (async ordering primitive)."""
+
+
+SendRequest = Callable[[MessageQueueClient, RequestType, list[object]], MessagingFuture]
+
+
+def _single_group_block_ids(block_ids: list[list[int]]) -> list[int]:
+    """Return the flat block-id list for transports without HMA support."""
+    if len(block_ids) != 1:
+        raise RuntimeError(
+            "engine-driven transfer does not support hybrid KV cache groups"
+        )
+    return block_ids[0]
+
+
+class TransferContext(ABC):
+    """Abstract transport layer for worker-side KV transfer.
+
+    Concrete implementations encapsulate how worker-side store/retrieve
+    operations are transmitted to the multiprocess server. CUDA paths return
+    CUDA-aware futures backed by MQ requests, while CPU paths may perform
+    gather/scatter synchronously and return already-resolved futures.
+    """
+
+    @abstractmethod
+    def register(
+        self,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        model_name: str,
+        world_size: int,
+        blocks_in_chunk: int,
+        mq_client: MessageQueueClient,
+        mq_timeout: float,
+        send_request: SendRequest,
+        layout_hints: LayoutHints | None = None,
+        engine_group_infos: Sequence[EngineGroupInfo] = (),
+    ) -> None:
+        """Register KV caches with the server and wait for ACK.
+
+        Args:
+            instance_id: Worker process instance identifier.
+            kv_caches: Worker KV cache tensors keyed by layer name.
+            model_name: Model name used by cache keys.
+            world_size: KV world size.
+            blocks_in_chunk: Number of vLLM blocks per LMCache chunk.
+            mq_client: Message queue client used to communicate with server.
+            mq_timeout: Timeout in seconds for synchronous request wait.
+            send_request: Request sender callable used to issue MQ requests.
+            layout_hints: Optional inference-engine-provided layout hints.
+            engine_group_infos: LMCache-owned engine KV cache group metadata.
+
+        Raises:
+            TimeoutError: If server registration does not complete before
+                ``mq_timeout``.
+            RuntimeError: If a concrete context cannot initialize.
+        """
+
+    @abstractmethod
+    def submit_store(
+        self,
+        request_id: str,
+        key: Any,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        event: IPCEvent,
+        blocks_in_chunk: int,
+    ) -> MessagingFuture:
+        """Submit a store request and return a completion future.
+
+        Args:
+            request_id: External request identifier.
+            key: LMCache key object for the store range.
+            instance_id: Worker process instance identifier.
+            kv_caches: Worker KV cache tensors keyed by layer name.
+            block_ids: vLLM block IDs to store, indexed by LMCache KV group id.
+            event: Synchronization event object.
+            blocks_in_chunk: Number of vLLM blocks per LMCache chunk.
+
+        Returns:
+            A future compatible with adapter-side ``query()``/``result()`` flow.
+
+        Raises:
+            RuntimeError: If register() was not called first.
+        """
+
+    @abstractmethod
+    def submit_retrieve(
+        self,
+        request_id: str,
+        key: Any,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        event: IPCEvent,
+        blocks_in_chunk: int,
+        skip_first_n_tokens: int = 0,
+    ) -> MessagingFuture:
+        """Submit a retrieve request and return a completion future.
+
+        Args:
+            request_id: External request identifier.
+            key: LMCache key object for the retrieve range.
+            instance_id: Worker process instance identifier.
+            kv_caches: Worker KV cache tensors keyed by layer name.
+            block_ids: vLLM block IDs to retrieve into, indexed by LMCache KV
+                group id.
+            event: Synchronization event object.
+            blocks_in_chunk: Number of vLLM blocks per LMCache chunk.
+            skip_first_n_tokens: Number of initial tokens to skip when writing.
+
+        Returns:
+            A future compatible with adapter-side ``query()``/``result()`` flow.
+
+        Raises:
+            RuntimeError: If register() was not called first.
+        """
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release resources held by this context."""
+
+    @abstractmethod
+    def flush_inflight_stores(self) -> None:
+        """Synchronize any in-flight gather operations.
+
+        Subclasses must implement this method. Contexts with no deferred
+        operations should implement it as a no-op. Async contexts that
+        defer GPU->CPU gather work must block until all in-flight stores
+        have completed, so that vLLM cannot overwrite paged KV blocks
+        before they are read.
+        """
+
+
+class LMCacheDrivenTransferContext(TransferContext):
+    """LMCache-driven IPC + MQ future transport context.
+
+    In this mode the serving engine provides device handles (IPC for CUDA,
+    SHM wrappers for CPU with CUDA-IPC-like semantics) and the LMCache
+    server performs direct device-side data transfer.
+    """
+
+    def __init__(self) -> None:
+        self._mq_client: MessageQueueClient | None = None
+        self._send_request: SendRequest | None = None
+
+    def register(
+        self,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        model_name: str,
+        world_size: int,
+        _blocks_in_chunk: int,
+        mq_client: MessageQueueClient,
+        mq_timeout: float,
+        send_request: SendRequest,
+        layout_hints: LayoutHints | None = None,
+        engine_group_infos: Sequence[EngineGroupInfo] = (),
+    ) -> None:
+        # First Party
+        from lmcache.integration.vllm.vllm_multi_process_adapter import wrap_kv_caches
+
+        self._mq_client = mq_client
+        self._send_request = send_request
+        future = send_request(
+            mq_client,
+            RequestType.REGISTER_KV_CACHE,
+            [
+                instance_id,
+                wrap_kv_caches(kv_caches),
+                model_name,
+                world_size,
+                EngineType.VLLM,
+                layout_hints,
+                list(engine_group_infos),
+            ],
+        )
+        future.result(timeout=mq_timeout)
+
+    def submit_store(
+        self,
+        _request_id: str,
+        key: Any,
+        instance_id: int,
+        _kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        event: IPCEvent,
+        _blocks_in_chunk: int,
+    ) -> MessagingFuture:
+        if self._mq_client is None or self._send_request is None:
+            raise RuntimeError(
+                "LMCache-driven transfer context is not registered. "
+                "Call register() before submit_store()."
+            )
+        return self._send_request(
+            self._mq_client,
+            RequestType.STORE,
+            [key, instance_id, block_ids, event.ipc_handle()],
+        ).to_cuda_future()
+
+    def submit_retrieve(
+        self,
+        _request_id: str,
+        key: Any,
+        instance_id: int,
+        _kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        event: IPCEvent,
+        _blocks_in_chunk: int,
+        skip_first_n_tokens: int = 0,
+    ) -> MessagingFuture:
+        if self._mq_client is None or self._send_request is None:
+            raise RuntimeError(
+                "LMCache-driven transfer context is not registered. "
+                "Call register() before submit_retrieve()."
+            )
+        return self._send_request(
+            self._mq_client,
+            RequestType.RETRIEVE,
+            [key, instance_id, block_ids, event.ipc_handle(), skip_first_n_tokens],
+        ).to_cuda_future()
+
+    def close(self) -> None:
+        self._mq_client = None
+        self._send_request = None
+
+    def flush_inflight_stores(self) -> None:
+        pass
+
+
+class EngineDrivenTransferContext(TransferContext):
+    """Engine-driven transfer context for non-CUDA workers.
+
+    In this mode the engine (worker side) owns the data movement: the
+    worker adapter gathers/packs KV into CPU buffers, commits via
+    message-queue, and the server side persists/rehydrates from storage.
+    """
+
+    def __init__(self) -> None:
+        self._engine_driven_context: EngineDrivenContext | None = None
+        self._layout_hints: LayoutHints | None = None
+        self._engine_kv_format: Any = None
+
+    @property
+    def engine_driven_context(self) -> EngineDrivenContext:
+        """Return the underlying SHM/pickle context created by ``register``.
+
+        Raises:
+            RuntimeError: If accessed before ``register`` has run.
+        """
+        if self._engine_driven_context is None:
+            raise RuntimeError(
+                "EngineDrivenTransferContext is not registered, call register() first."
+            )
+        return self._engine_driven_context
+
+    def register(
+        self,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        model_name: str,
+        world_size: int,
+        blocks_in_chunk: int,
+        mq_client: MessageQueueClient,
+        mq_timeout: float,
+        send_request: SendRequest,
+        layout_hints: LayoutHints | None = None,
+        engine_group_infos: Sequence[EngineGroupInfo] = (),
+    ) -> None:
+        """Register KV caches with the non-GPU context server.
+
+        ``engine_group_infos`` is accepted to satisfy the base interface but
+        is currently a no-op: the non-GPU transfer path does not support
+        hybrid KV cache groups and rejects multi-group transfers at store /
+        retrieve time (see ``_single_group_block_ids``).
+        """
+        # TODO: per-group compression (EngineGroupInfo.tokens_per_block vs
+        # the tensor-detected slot count, e.g. DeepSeek V4) is only handled
+        # on the CUDA path. The non-CUDA path is yet to be implemented.
+        (
+            block_size,
+            num_layers,
+            hidden_dim_size,
+            dtype_str,
+            engine_kv_format,
+        ) = compute_kv_layout(kv_caches, layout_hints=layout_hints)
+        self._layout_hints = layout_hints
+        self._engine_kv_format = engine_kv_format
+
+        use_mla_flag = is_mla(engine_kv_format)
+        shape = (
+            torch.Size([num_layers, blocks_in_chunk * block_size, hidden_dim_size])
+            if use_mla_flag
+            else torch.Size(
+                [2, num_layers, blocks_in_chunk * block_size, hidden_dim_size]
+            )
+        )
+        dtype = getattr(torch, dtype_str)
+        layout_desc = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+
+        future = send_request(
+            mq_client,
+            RequestType.REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT,
+            [
+                RegisterEngineDrivenContextPayload(
+                    instance_id=instance_id,
+                    model_name=model_name,
+                    world_size=world_size,
+                    block_size=block_size,
+                    num_layers=num_layers,
+                    hidden_dim_size=hidden_dim_size,
+                    dtype_str=dtype_str,
+                    use_mla=use_mla_flag,
+                )
+            ],
+        )
+        response = future.result(timeout=mq_timeout)
+        shm_name = ""
+        pool_size = 0
+        if isinstance(response, RegisterEngineDrivenContextResponse):
+            shm_name = response.shm_name
+            pool_size = response.pool_size
+
+        metadata = EngineDrivenContextMetadata(
+            layout_desc=layout_desc,
+            block_size=block_size,
+            use_mla=use_mla_flag,
+        )
+        self._engine_driven_context = create_engine_driven_context(
+            metadata,
+            mq_client,
+            mq_timeout,
+            shm_name=shm_name,
+            pool_size=pool_size,
+        )
+        supported_transfer_mode = "SHM" if shm_name and pool_size > 0 else "pickle"
+        logger.info(
+            "Worker non-GPU transfer context registered (instance_id=%d, mode=%s)",
+            instance_id,
+            supported_transfer_mode,
+        )
+
+    def submit_store(
+        self,
+        _request_id: str,
+        key: Any,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        _event: IPCEvent,
+        blocks_in_chunk: int,
+    ) -> MessagingFuture:
+        if self._engine_driven_context is None:
+            raise RuntimeError(
+                "Engine-driven transfer context is not registered. "
+                "Call register() before submit_store()."
+            )
+
+        torch_dev.synchronize()
+        result = self._engine_driven_context.prepare_store(key, instance_id)
+        out_buffers, chunk_indices = result if result is not None else (None, None)
+        # All chunks already in cache — nothing to gather or commit.
+        if chunk_indices is not None and len(chunk_indices) == 0:
+            future: MessagingFuture[bool] = MessagingFuture()
+            future.set_result(True)
+            return future
+        cpu_chunks = gather_paged_kv_to_cpu(
+            kv_caches,
+            _single_group_block_ids(block_ids),
+            blocks_in_chunk,
+            layout_hints=self._layout_hints,
+            engine_kv_format=self._engine_kv_format,
+            out=out_buffers,
+            chunk_indices=chunk_indices,
+        )
+        if out_buffers is not None:
+            # SHM path uses async device->CPU copies; complete them before commit.
+            torch_dev.synchronize()
+        ok = self._engine_driven_context.commit_store(key, instance_id, cpu_chunks)
+
+        future = MessagingFuture()
+        future.set_result(ok)
+        return future
+
+    def submit_retrieve(
+        self,
+        _request_id: str,
+        key: Any,
+        instance_id: int,
+        kv_caches: dict[str, torch.Tensor],
+        block_ids: list[list[int]],
+        _event: IPCEvent,
+        blocks_in_chunk: int,
+        skip_first_n_tokens: int = 0,
+    ) -> MessagingFuture:
+        if self._engine_driven_context is None:
+            raise RuntimeError(
+                "Engine-driven transfer context is not registered. "
+                "Call register() before submit_retrieve()."
+            )
+
+        src_buffers = self._engine_driven_context.prepare_retrieve(key, instance_id)
+        ok = src_buffers is not None
+        if src_buffers is not None:
+            try:
+                scatter_cpu_to_paged_kv(
+                    kv_caches,
+                    _single_group_block_ids(block_ids),
+                    src_buffers,
+                    blocks_in_chunk,
+                    skip_first_n_tokens=skip_first_n_tokens,
+                    layout_hints=self._layout_hints,
+                    engine_kv_format=self._engine_kv_format,
+                )
+            except (RuntimeError, ValueError, TypeError, IndexError):
+                logger.exception("Failed to scatter retrieved CPU context chunks")
+                ok = False
+            # SHM path: ensure all device writes are complete before releasing
+            # the SHM slot (server may immediately reuse it after commit_retrieve).
+            torch_dev.synchronize()
+        self._engine_driven_context.commit_retrieve(key, instance_id)
+
+        future: MessagingFuture[bool] = MessagingFuture()
+        future.set_result(ok)
+        return future
+
+    def close(self) -> None:
+        if self._engine_driven_context is not None:
+            self._engine_driven_context.close()
+            self._engine_driven_context = None
+
+    def flush_inflight_stores(self) -> None:
+        pass
+
+
+def create_transfer_context(
+    kv_caches: dict[str, torch.Tensor],
+    mode: "str | MPTransferMode | None" = None,
+    **_kwargs: Any,
+) -> TransferContext:
+    """Create a transfer context from KV cache device type.
+
+    The device check is intentionally centralized here. Routing can be
+    overridden via the ``mode`` argument or the ``LMCACHE_MP_TRANSFER_MODE``
+    environment variable; see :class:`MPTransferMode` for accepted values.
+
+    Args:
+        kv_caches: Worker KV cache tensors keyed by layer name.
+        mode: Optional routing override. When ``None`` the value of
+            ``LMCACHE_MP_TRANSFER_MODE`` is consulted, defaulting to
+            :attr:`MPTransferMode.AUTO`.
+        **kwargs: Unused placeholder for forward-compatible factory extension.
+
+    Returns:
+        A concrete :class:`TransferContext` implementation.
+
+    Raises:
+        ValueError: If ``kv_caches`` is empty, has mixed device types, the
+            requested mode string is unknown, or the requested mode is not
+            supported for the worker device.
+    """
+    if not kv_caches:
+        raise ValueError("kv_caches is empty")
+    device_types = {tensor.device.type for tensor in kv_caches.values()}
+    if len(device_types) != 1:
+        raise ValueError(
+            f"All KV cache tensors must share one device type, got {device_types}"
+        )
+    device_type = next(iter(device_types))
+    resolved_mode = _resolve_mode(mode)
+    logger.info(
+        "Creating transfer context (device_type=%s, mode=%s)",
+        device_type,
+        resolved_mode.value,
+    )
+    if resolved_mode is MPTransferMode.LMCACHE_DRIVEN:
+        return _build_lmcache_driven_context(device_type)
+    if resolved_mode is MPTransferMode.ENGINE_DRIVEN:
+        return _build_engine_driven_context()
+    # AUTO: dispatch by device type (CUDA -> handle path, else -> data path).
+    if device_type == "cuda":
+        return LMCacheDrivenTransferContext()
+    return _build_engine_driven_context()
diff --git a/lmcache/v1/multiprocess/warm_prefetch.py b/lmcache/v1/multiprocess/warm_prefetch.py
new file mode 100644
index 0000000..3c3d355
--- /dev/null
+++ b/lmcache/v1/multiprocess/warm_prefetch.py
@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Warm-prefetch job table for the MP server.
+
+A *warm* prefetch loads a caller-supplied set of keys from L2 into L1 and leaves
+them resident, retained, and unpinned, so a subsequent real lookup hits L1. It
+loads every requested key not already in L1, and pins nothing -- there is no
+downstream reader to pin for.
+
+The table tracks in-flight warm prefetches: ``submit`` starts one and returns an
+opaque request id; ``poll`` reports its status (pending, then completed) and
+drops it once the load finishes. Status is observed reactively by the caller --
+there is no background polling -- and these calls do not block. A job whose
+status is never polled to completion simply lingers until a later cleanup drops
+it; since nothing is pinned, no L1 is held.
+"""
+
+# Standard
+from dataclasses import dataclass
+import threading
+import uuid
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchHandle,
+    PrefetchMode,
+    TrimPolicy,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+logger = init_logger(__name__)
+
+# Job states reported by :meth:`WarmPrefetchJobs.poll`.
+PENDING = "pending"
+COMPLETED = "completed"
+UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class WarmStatus:
+    """Outcome of a status poll.
+
+    Attributes:
+        state: ``"pending"`` (load still running), ``"completed"`` (loaded), or
+            ``"unknown"`` (no such request id -- already completed-and-consumed,
+            or never submitted).
+        found_keys: Keys loaded into L1 (only meaningful when ``completed``).
+        total_keys: Keys originally requested (only meaningful when
+            ``completed``).
+    """
+
+    state: str
+    found_keys: int = 0
+    total_keys: int = 0
+
+
+class WarmPrefetchJobs:
+    """Thread-safe table of in-flight warm-prefetch jobs (``request_id ->
+    handle``).
+
+    ``submit`` starts a no-lock retain prefetch and returns an opaque request
+    id; ``poll`` reports progress and, on completion, drops the job
+    (exactly-once: a subsequent poll for the same id returns ``UNKNOWN``).
+    Since the warm holds no read lock, there is nothing to release on
+    completion.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty table."""
+        self._lock = threading.Lock()
+        self._jobs: dict[str, PrefetchHandle] = {}
+
+    def submit(
+        self,
+        storage_manager: StorageManager,
+        keys: list[ObjectKey],
+        layout_desc: MemoryLayoutDesc,
+    ) -> str:
+        """Start a no-lock retain prefetch and register its handle.
+
+        Args:
+            storage_manager: The MP server's storage manager.
+            keys: Object keys to load from L2 into L1.
+            layout_desc: Memory layout for the L1 write buffers.
+
+        Returns:
+            An opaque request id to pass to :meth:`poll`.
+        """
+        handle = storage_manager.submit_prefetch_task(
+            keys,
+            layout_desc,
+            mode=PrefetchMode.WARM,
+            policy=TrimPolicy.SPARSE,
+        )
+        request_id = uuid.uuid4().hex
+        with self._lock:
+            self._jobs[request_id] = handle
+        return request_id
+
+    def poll(
+        self,
+        storage_manager: StorageManager,
+        request_id: str,
+    ) -> WarmStatus:
+        """Report a job's status; drop it once the load completes.
+
+        Args:
+            storage_manager: The MP server's storage manager.
+            request_id: The id returned by :meth:`submit`.
+
+        Returns:
+            A :class:`WarmStatus`. The first poll that observes completion drops
+            the job (and pops the controller's result bookkeeping), so later
+            polls for the same id return ``UNKNOWN``.
+        """
+        with self._lock:
+            handle = self._jobs.get(request_id)
+        if handle is None:
+            return WarmStatus(state=UNKNOWN)
+
+        found = storage_manager.query_prefetch_status(handle)
+        if found is None:
+            return WarmStatus(state=PENDING)
+
+        with self._lock:
+            self._jobs.pop(request_id, None)
+        found_keys = found.popcount()
+        logger.info(
+            "Warm prefetch %s completed: %d/%d keys loaded into L1",
+            request_id,
+            found_keys,
+            handle.total_requested_keys,
+        )
+        return WarmStatus(
+            state=COMPLETED,
+            found_keys=found_keys,
+            total_keys=handle.total_requested_keys,
+        )
diff --git a/lmcache/v1/offload_server/__init__.py b/lmcache/v1/offload_server/__init__.py
new file mode 100644
index 0000000..bcb066a
--- /dev/null
+++ b/lmcache/v1/offload_server/__init__.py
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.factory import LookupClientFactory
+from lmcache.v1.lookup_client.lmcache_lookup_client import (
+    LMCacheLookupClient,
+    LMCacheLookupServer,
+)
+from lmcache.v1.lookup_client.mooncake_lookup_client import MooncakeLookupClient
+
+__all__ = [
+    "LookupClientInterface",
+    "LookupClientFactory",
+    "MooncakeLookupClient",
+    "LMCacheLookupClient",
+    "LMCacheLookupServer",
+]
diff --git a/lmcache/v1/offload_server/abstract_server.py b/lmcache/v1/offload_server/abstract_server.py
new file mode 100644
index 0000000..4bd13bd
--- /dev/null
+++ b/lmcache/v1/offload_server/abstract_server.py
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, List
+import abc
+
+if TYPE_CHECKING:
+    # Third Party
+    pass
+
+
+class OffloadServerInterface(metaclass=abc.ABCMeta):
+    """Abstract interface for offload server."""
+
+    @abc.abstractmethod
+    def offload(
+        self,
+        hashes: List[int],
+        slot_mapping: List[int],
+        offsets: List[int],
+    ) -> bool:
+        """
+        Perform offload for the given hashes and block IDs.
+
+        Args:
+            hashes: The hashes to offload.
+            slot_mapping: The slot ids to offload.
+            offsets: Number of tokens in each block.
+
+        Returns:
+            Whether the offload was successful.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close the offload server and clean up resources."""
+        raise NotImplementedError
diff --git a/lmcache/v1/offload_server/message.py b/lmcache/v1/offload_server/message.py
new file mode 100644
index 0000000..4c3e71f
--- /dev/null
+++ b/lmcache/v1/offload_server/message.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List
+
+# Third Party
+import msgspec
+
+
+class OffloadMsg(msgspec.Struct):
+    """Message for Offloading"""
+
+    hashes: List[int]
+    slot_mapping: List[int]
+    offsets: List[int]
+
+    def describe(self) -> str:
+        return (
+            f"OffloadMsg(hashes={self.hashes}, "
+            f"slot_mapping={self.slot_mapping}, "
+            f"offsets={self.offsets})"
+        )
+
+
+class OffloadRetMsg(msgspec.Struct):
+    """Return message for Offloading"""
+
+    success: bool
+
+    def describe(self) -> str:
+        return f"OffloadRetMsg(success={self.success})"
diff --git a/lmcache/v1/offload_server/zmq_server.py b/lmcache/v1/offload_server/zmq_server.py
new file mode 100644
index 0000000..1b66354
--- /dev/null
+++ b/lmcache/v1/offload_server/zmq_server.py
@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List
+import os
+import threading
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.offload_server.abstract_server import OffloadServerInterface
+from lmcache.v1.offload_server.message import OffloadMsg, OffloadRetMsg
+from lmcache.v1.rpc_utils import (
+    get_zmq_context,
+    get_zmq_rpc_path_lmcache,
+    get_zmq_socket,
+)
+
+
+class ZMQOffloadServer(OffloadServerInterface):
+    def __init__(
+        self,
+        lmcache_engine: LMCacheEngine,
+        tp_rank: int,
+    ):
+        metadata = lmcache_engine.metadata
+        self.ctx = get_zmq_context(use_asyncio=False)
+        offload_rpc_port = int(os.environ.get("LMCACHE_OFFLOAD_RPC_PORT", 100))
+        engine_id = metadata.engine_id or "default"
+        socket_path = get_zmq_rpc_path_lmcache(
+            engine_id, "offload", offload_rpc_port, tp_rank
+        )
+        self.socket = get_zmq_socket(
+            self.ctx,
+            socket_path,
+            "ipc",
+            zmq.REP,  # type: ignore[attr-defined]
+            "bind",
+        )
+
+        self.lmcache_engine = lmcache_engine
+        self.running = True
+
+        def process_request():
+            # First Party
+            from lmcache.logging import init_logger
+
+            logger = init_logger(__name__)
+
+            while self.running:
+                try:
+                    frame = self.socket.recv(copy=False)
+                    offload_msg = msgspec.msgpack.decode(frame, type=OffloadMsg)
+                    result = self.offload(
+                        offload_msg.hashes,
+                        offload_msg.slot_mapping,
+                        offload_msg.offsets,
+                    )
+                    response = OffloadRetMsg(success=result)
+                    response = msgspec.msgpack.encode(response)
+                    self.socket.send(response)
+                except zmq.ZMQError as e:
+                    # Socket was closed, exit gracefully
+                    if not self.running:
+                        logger.info("ZMQ socket closed, exiting offload server thread")
+                        break
+                    logger.error(f"ZMQ error in offload server: {e}")
+                    break
+                except Exception as e:
+                    logger.error(f"Unexpected error in offload server: {e}")
+                    if not self.running:
+                        break
+
+        self.thread = threading.Thread(
+            target=process_request, daemon=True, name="offload-server-thread"
+        )
+        self.thread.start()
+
+    def offload(
+        self,
+        hashes: List[int],
+        slot_mapping: List[int],
+        offsets: List[int],
+    ) -> bool:
+        self.lmcache_engine.store(
+            hashes=hashes, slot_mapping=slot_mapping, offsets=offsets
+        )
+        return True
+
+    def close(self) -> None:
+        # First Party
+        from lmcache.logging import init_logger
+
+        logger = init_logger(__name__)
+
+        logger.info("Closing ZMQOffloadServer...")
+        self.running = False
+
+        # Close socket to interrupt blocking recv()
+        try:
+            self.socket.close(linger=0)
+            logger.info("ZMQ socket closed")
+        except Exception as e:
+            logger.warning(f"Error closing ZMQ socket: {e}")
+
+        # Wait for thread with timeout to prevent deadlock
+        if self.thread.is_alive():
+            logger.info("Waiting for offload server thread to finish...")
+            self.thread.join(timeout=5.0)
+
+            if self.thread.is_alive():
+                logger.warning(
+                    "Offload server thread did not terminate within timeout. "
+                    "Thread may be stuck in blocking recv(). "
+                    "Proceeding with shutdown anyway."
+                )
+            else:
+                logger.info("Offload server thread terminated successfully")
+        else:
+            logger.info("Offload server thread already stopped")
diff --git a/lmcache/v1/periodic_thread.py b/lmcache/v1/periodic_thread.py
new file mode 100644
index 0000000..225462e
--- /dev/null
+++ b/lmcache/v1/periodic_thread.py
@@ -0,0 +1,584 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unified PeriodicThread abstraction for LMCache background threads.
+
+This module provides a standardized way to create and manage periodic
+background threads with proper naming, monitoring, and lifecycle management.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.exceptions import IrrecoverableException
+
+if TYPE_CHECKING:
+    # First Party
+    pass
+
+logger = init_logger(__name__)
+
+
+class ThreadLevel(Enum):
+    """
+    Thread importance level.
+
+    CRITICAL: Thread failure causes severe system degradation or data loss.
+              Examples: health-monitor-thread, PinMonitor-thread
+
+    HIGH: Thread failure significantly impacts performance or functionality.
+          Examples: storage-manager-event-loop, lookup-server threads
+
+    MEDIUM: Thread failure causes noticeable degradation but system remains functional.
+            Examples: stats-logger-thread, batched-message-sender-thread
+
+    LOW: Thread failure has minimal impact on system operation.
+         Examples: lazy-memory-expand-thread
+    """
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+@dataclass
+class ThreadRunSummary:
+    """Summary of a single thread execution cycle."""
+
+    timestamp: float = 0.0
+    duration_ms: float = 0.0
+    success: bool = True
+    message: str = ""
+    extra_info: Dict[str, str] = field(default_factory=dict)
+
+
+class PeriodicThread(ABC):
+    """
+    Abstract base class for periodic background threads.
+
+    This class provides a standardized framework for creating periodic
+    background threads with proper naming, monitoring, and lifecycle management.
+
+    Attributes:
+        name: Human-readable name of the thread
+        interval: Time interval between executions in seconds
+        level: Importance level of the thread
+        init_wait: Initial wait time before first execution in seconds
+
+    Features:
+        - Named threads for easy identification
+        - Configurable execution interval
+        - Initial wait time before first execution
+        - Automatic tracking of last run time and summary
+        - Thread level classification for monitoring
+        - Interruptible sleep for graceful shutdown
+
+    Usage:
+        class MyPeriodicThread(PeriodicThread):
+            def __init__(self):
+                super().__init__(
+                    name="my-periodic-thread",
+                    interval=30.0,
+                    level=ThreadLevel.MEDIUM,
+                    init_wait=5.0,
+                )
+
+            def _execute(self) -> ThreadRunSummary:
+                # Perform periodic work
+                return ThreadRunSummary(
+                    timestamp=time.time(),
+                    success=True,
+                    message="Completed successfully"
+                )
+
+        thread = MyPeriodicThread()
+        thread.start()
+        # ... later ...
+        thread.stop()
+    """
+
+    def __init__(
+        self,
+        name: str,
+        interval: float,
+        level: ThreadLevel = ThreadLevel.MEDIUM,
+        init_wait: float = 0.0,
+    ):
+        """
+        Initialize a PeriodicThread.
+
+        Args:
+            name: Thread name for identification
+            interval: Execution interval in seconds
+            level: Thread importance level
+            init_wait: Initial wait time before first execution in seconds
+        """
+        self._name = name
+        self._interval = interval
+        self._level = level
+        self._init_wait = init_wait
+
+        # Thread state
+        self._thread: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._running = False
+
+        # Execution tracking
+        self._last_run_time: float = 0.0
+        self._last_summary: Optional[ThreadRunSummary] = None
+        self._total_runs: int = 0
+        self._failed_runs: int = 0
+        self._lock = threading.RLock()
+
+        # Start time (set when thread starts)
+        self._start_time: float = 0.0
+
+    @property
+    def name(self) -> str:
+        """Get the thread name."""
+        return self._name
+
+    @property
+    def interval(self) -> float:
+        """Get the execution interval in seconds."""
+        return self._interval
+
+    @property
+    def level(self) -> ThreadLevel:
+        """Get the thread importance level."""
+        return self._level
+
+    @property
+    def init_wait(self) -> float:
+        """Get the initial wait time in seconds."""
+        return self._init_wait
+
+    @property
+    def last_run_time(self) -> float:
+        """Get the timestamp of the last execution."""
+        with self._lock:
+            return self._last_run_time
+
+    @property
+    def last_summary(self) -> Optional[ThreadRunSummary]:
+        """Get the summary of the last execution."""
+        with self._lock:
+            return self._last_summary
+
+    @property
+    def total_runs(self) -> int:
+        """Get the total number of executions."""
+        with self._lock:
+            return self._total_runs
+
+    @property
+    def failed_runs(self) -> int:
+        """Get the number of failed executions."""
+        with self._lock:
+            return self._failed_runs
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the thread is currently running."""
+        return self._running and self._thread is not None and self._thread.is_alive()
+
+    @property
+    def stop_requested(self) -> bool:
+        """Whether a stop has been requested (set by stop, reset by start)."""
+        return self._stop_event.is_set()
+
+    @property
+    def is_active(self) -> bool:
+        """
+        Check if the thread is active (running and recently executed).
+
+        A thread is considered active if:
+        1. It is running
+        2. The time since last run is less than 3 * interval
+
+        Returns:
+            bool: True if active, False otherwise
+        """
+        if not self.is_running:
+            return False
+
+        with self._lock:
+            if self._last_run_time == 0:
+                # Thread started but hasn't run yet
+                # Consider active if within init_wait + 3 * interval from start
+                time_since_start = time.time() - self._start_time
+                return time_since_start < self._init_wait + 3 * self._interval
+
+            time_since_last_run = time.time() - self._last_run_time
+            return time_since_last_run < 3 * self._interval
+
+    def start(self) -> Optional[threading.Thread]:
+        """
+        Start the periodic thread.
+
+        Returns:
+            Optional[threading.Thread]: The started thread, or None if already running
+        """
+        if self._running:
+            logger.warning("PeriodicThread %s is already running", self._name)
+            return None
+
+        self._stop_event.clear()
+        self._running = True
+        self._start_time = time.time()
+
+        self._thread = threading.Thread(
+            target=self._run_loop,
+            daemon=True,
+            name=self._name,
+        )
+        self._thread.start()
+
+        logger.info(
+            "Started PeriodicThread: %s (level=%s, interval=%.1fs, init_wait=%.1fs)",
+            self._name,
+            self._level.value,
+            self._interval,
+            self._init_wait,
+        )
+        return self._thread
+
+    def stop(self, timeout: float = 5.0) -> None:
+        """
+        Stop the periodic thread.
+
+        Args:
+            timeout: Maximum time to wait for thread termination in seconds
+        """
+        if not self._running:
+            return
+
+        logger.info("Stopping PeriodicThread: %s", self._name)
+        self._running = False
+        self._stop_event.set()
+
+        if self._thread is not None and self._thread.is_alive():
+            self._thread.join(timeout=timeout)
+            if self._thread.is_alive():
+                logger.warning(
+                    "PeriodicThread %s did not terminate within %.1fs timeout",
+                    self._name,
+                    timeout,
+                )
+
+    def _run_loop(self) -> None:
+        """Main thread loop."""
+        # Initial wait
+        if self._init_wait > 0:
+            if self._stop_event.wait(timeout=self._init_wait):
+                logger.info("PeriodicThread %s stopped during init_wait", self._name)
+                return
+
+        logger.info(
+            "PeriodicThread %s entering main loop (interval=%.1fs)",
+            self._name,
+            self._interval,
+        )
+
+        while not self._stop_event.is_set():
+            start_time = time.time()
+
+            try:
+                summary = self._execute()
+                summary.timestamp = start_time
+                summary.duration_ms = (time.time() - start_time) * 1000
+
+                with self._lock:
+                    self._last_run_time = start_time
+                    self._last_summary = summary
+                    self._total_runs += 1
+                    if not summary.success:
+                        self._failed_runs += 1
+
+            except IrrecoverableException as e:
+                logger.error(
+                    "IrrecoverableException in PeriodicThread %s: %s",
+                    self._name,
+                    e,
+                    exc_info=True,
+                )
+                summary = ThreadRunSummary(
+                    timestamp=start_time,
+                    duration_ms=(time.time() - start_time) * 1000,
+                    success=False,
+                    message=str(e),
+                )
+                with self._lock:
+                    self._last_run_time = start_time
+                    self._last_summary = summary
+                    self._total_runs += 1
+                    self._failed_runs += 1
+                # Stop the loop on irrecoverable exceptions
+                logger.info(
+                    "PeriodicThread %s stopping due to IrrecoverableException",
+                    self._name,
+                )
+                break
+            except Exception as e:
+                logger.error(
+                    "Error in PeriodicThread %s: %s", self._name, e, exc_info=True
+                )
+                summary = ThreadRunSummary(
+                    timestamp=start_time,
+                    duration_ms=(time.time() - start_time) * 1000,
+                    success=False,
+                    message=str(e),
+                )
+                with self._lock:
+                    self._last_run_time = start_time
+                    self._last_summary = summary
+                    self._total_runs += 1
+                    self._failed_runs += 1
+
+            # Wait for next interval
+            if self._stop_event.wait(timeout=self._interval):
+                break
+
+        logger.info("PeriodicThread %s loop stopped", self._name)
+
+    @abstractmethod
+    def _execute(self) -> ThreadRunSummary:
+        """
+        Execute one cycle of the periodic task.
+
+        This method should be overridden by subclasses to implement
+        the actual periodic work.
+
+        Returns:
+            ThreadRunSummary: Summary of this execution cycle
+        """
+        pass
+
+    def get_status(self) -> Dict:
+        """
+        Get the current status of the thread.
+
+        Returns:
+            Dict: Thread status information
+        """
+        with self._lock:
+            last_summary_dict = None
+            if self._last_summary:
+                last_summary_dict = {
+                    "timestamp": self._last_summary.timestamp,
+                    "duration_ms": self._last_summary.duration_ms,
+                    "success": self._last_summary.success,
+                    "message": self._last_summary.message,
+                    "extra_info": self._last_summary.extra_info,
+                }
+
+            return {
+                "name": self._name,
+                "level": self._level.value,
+                "interval": self._interval,
+                "init_wait": self._init_wait,
+                "is_running": self.is_running,
+                "is_active": self.is_active,
+                "last_run_time": self._last_run_time,
+                "last_run_ago": time.time() - self._last_run_time
+                if self._last_run_time > 0
+                else None,
+                "total_runs": self._total_runs,
+                "failed_runs": self._failed_runs,
+                "success_rate": (
+                    (self._total_runs - self._failed_runs) / self._total_runs * 100
+                    if self._total_runs > 0
+                    else None
+                ),
+                "last_summary": last_summary_dict,
+            }
+
+
+class PeriodicThreadRegistry:
+    """
+    Global registry for all PeriodicThread instances.
+
+    This class provides a centralized way to track and manage all
+    periodic threads in the system.
+    """
+
+    _instance: Optional["PeriodicThreadRegistry"] = None
+    _lock = threading.Lock()
+
+    def __init__(self):
+        self._threads: Dict[str, PeriodicThread] = {}
+        self._registry_lock = threading.RLock()
+
+    @classmethod
+    def get_instance(cls) -> "PeriodicThreadRegistry":
+        """Get or create the singleton instance."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = PeriodicThreadRegistry()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance. Mainly for testing."""
+        with cls._lock:
+            if cls._instance is not None:
+                cls._instance.unregister_all()
+            cls._instance = None
+
+    def register(self, thread: PeriodicThread) -> None:
+        """
+        Register a periodic thread.
+
+        Args:
+            thread: The PeriodicThread to register
+        """
+        with self._registry_lock:
+            if thread.name in self._threads:
+                logger.warning(
+                    "PeriodicThread %s is already registered, replacing",
+                    thread.name,
+                )
+            self._threads[thread.name] = thread
+            logger.debug("Registered PeriodicThread: %s", thread.name)
+
+    def unregister(self, name: str) -> Optional[PeriodicThread]:
+        """
+        Unregister a periodic thread by name.
+
+        Args:
+            name: The name of the thread to unregister
+
+        Returns:
+            The unregistered thread, or None if not found
+        """
+        with self._registry_lock:
+            thread = self._threads.pop(name, None)
+            if thread:
+                logger.debug("Unregistered PeriodicThread: %s", name)
+            return thread
+
+    def unregister_all(self) -> None:
+        """Unregister all periodic threads."""
+        with self._registry_lock:
+            self._threads.clear()
+            logger.debug("Unregistered all PeriodicThreads")
+
+    def get(self, name: str) -> Optional[PeriodicThread]:
+        """Get a registered thread by name."""
+        with self._registry_lock:
+            return self._threads.get(name)
+
+    def get_all(self) -> List[PeriodicThread]:
+        """Get all registered threads."""
+        with self._registry_lock:
+            return list(self._threads.values())
+
+    def get_by_level(self, level: ThreadLevel) -> List[PeriodicThread]:
+        """Get all threads with the specified level."""
+        with self._registry_lock:
+            return [t for t in self._threads.values() if t.level == level]
+
+    def get_running_count(self) -> int:
+        """Get the count of running threads."""
+        with self._registry_lock:
+            return sum(1 for t in self._threads.values() if t.is_running)
+
+    def get_active_count(self) -> int:
+        """Get the count of active threads."""
+        with self._registry_lock:
+            return sum(1 for t in self._threads.values() if t.is_active)
+
+    def get_count_by_level(self, level: ThreadLevel) -> Dict[str, int]:
+        """
+        Get counts of threads for a specific level.
+
+        Returns:
+            Dict with keys: total, running, active
+        """
+        with self._registry_lock:
+            threads = [t for t in self._threads.values() if t.level == level]
+            return {
+                "total": len(threads),
+                "running": sum(1 for t in threads if t.is_running),
+                "active": sum(1 for t in threads if t.is_active),
+            }
+
+    def get_summary(self) -> Dict:
+        """
+        Get a summary of all registered threads.
+
+        Returns:
+            Dict containing:
+                - total_count: Total number of registered threads
+                - running_count: Number of running threads
+                - active_count: Number of active threads
+                - by_level: Counts by thread level
+                - threads: List of thread statuses
+        """
+        with self._registry_lock:
+            by_level = {}
+            for level in ThreadLevel:
+                by_level[level.value] = self.get_count_by_level(level)
+
+            return {
+                "total_count": len(self._threads),
+                "running_count": self.get_running_count(),
+                "active_count": self.get_active_count(),
+                "by_level": by_level,
+                "threads": [t.get_status() for t in self._threads.values()],
+            }
+
+
+def create_periodic_thread(
+    name: str,
+    interval: float,
+    execute_fn: Callable[[], ThreadRunSummary],
+    level: ThreadLevel = ThreadLevel.MEDIUM,
+    init_wait: float = 0.0,
+    auto_register: bool = True,
+) -> PeriodicThread:
+    """
+    Factory function to create a simple PeriodicThread.
+
+    This is a convenience function for creating periodic threads
+    without needing to define a subclass.
+
+    Args:
+        name: Thread name
+        interval: Execution interval in seconds
+        execute_fn: Function to execute on each cycle
+        level: Thread importance level
+        init_wait: Initial wait time before first execution
+        auto_register: Whether to automatically register with the global registry
+
+    Returns:
+        PeriodicThread: The created thread instance
+    """
+
+    class SimplePeriodicThread(PeriodicThread):
+        def __init__(self):
+            super().__init__(
+                name=name,
+                interval=interval,
+                level=level,
+                init_wait=init_wait,
+            )
+            self._execute_fn = execute_fn
+
+        def _execute(self) -> ThreadRunSummary:
+            return self._execute_fn()
+
+    thread = SimplePeriodicThread()
+
+    if auto_register:
+        PeriodicThreadRegistry.get_instance().register(thread)
+
+    return thread
diff --git a/lmcache/v1/pin_monitor.py b/lmcache/v1/pin_monitor.py
new file mode 100644
index 0000000..863f35c
--- /dev/null
+++ b/lmcache/v1/pin_monitor.py
@@ -0,0 +1,260 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import nullcontext
+from typing import TYPE_CHECKING, Optional
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor, PrometheusLogger
+from lmcache.v1.periodic_thread import (
+    PeriodicThread,
+    PeriodicThreadRegistry,
+    ThreadLevel,
+    ThreadRunSummary,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.memory_management import MemoryObj
+    from lmcache.v1.metadata import LMCacheMetadata
+
+
+logger = init_logger(__name__)
+
+
+class PinMonitor(PeriodicThread):
+    """
+    Global monitor (singleton per process, shared across all cache engines)
+    for pinned TensorMemoryObj instances to handle timeout detection.
+    This class runs a background thread that periodically checks for pinned objects
+    that have exceeded their timeout duration.
+    """
+
+    _instance = None
+    _instance_lock = threading.Lock()  # Class-level lock for singleton pattern
+
+    def __init__(self, config: "LMCacheEngineConfig") -> None:
+        # Initialize PeriodicThread base class
+        super().__init__(
+            name="PinMonitor-thread",
+            interval=config.pin_check_interval_sec,
+            level=ThreadLevel.CRITICAL,
+            init_wait=0.0,
+        )
+
+        # obj_id is the virtual memory address given by Python's id() function
+        self._pinned_objects: dict[
+            int, tuple["MemoryObj", float]
+        ] = {}  # {obj_id: (memory_obj, register_time)}
+        self._objects_lock = threading.Lock()
+        self._check_interval = config.pin_check_interval_sec
+        self._pin_timeout_sec = config.pin_timeout_sec
+
+        # Register with the global registry
+        PeriodicThreadRegistry.get_instance().register(self)
+
+        # Auto-start the monitor on first instance creation
+        self.start_monitoring()
+
+    @staticmethod
+    def GetOrCreate(
+        config: Optional["LMCacheEngineConfig"] = None,
+        metadata: Optional["LMCacheMetadata"] = None,
+    ) -> "PinMonitor":
+        """Get or create the singleton instance.
+
+        Args:
+            config: Required for first-time initialization.
+                Optional for subsequent calls.
+            metadata: Metadata for the label view that should publish
+                PinMonitor metrics.
+
+        Raises:
+            ValueError: If config is None when creating the instance
+                for the first time.
+        """
+        if PinMonitor._instance is None:
+            with PinMonitor._instance_lock:
+                if PinMonitor._instance is None:
+                    assert config is not None, "config is required"
+                    PinMonitor._instance = PinMonitor(config)
+        instance = PinMonitor._instance
+        assert instance is not None
+        if metadata is not None:
+            assert config is not None, "config is required to set up metrics"
+            instance._setup_metrics(config, metadata)
+        return instance
+
+    def on_pin(self, memory_obj: "MemoryObj"):
+        """Register a pinned memory object for timeout monitoring.
+
+        Note: The same memory_obj can be pinned multiple times, so this
+        function may be called multiple times with the same object.
+        Each call updates the register time, effectively resetting the
+        timeout countdown.
+        """
+        obj_id = id(memory_obj)
+        with self._objects_lock:
+            current_time = time.time()
+            self._pinned_objects[obj_id] = (memory_obj, current_time)
+            logger.debug(
+                "Registered pinned object %s for timeout monitoring at time %.2f",
+                obj_id,
+                current_time,
+            )
+
+    def on_unpin(self, memory_obj: "MemoryObj"):
+        """Unregister a memory object from timeout monitoring."""
+        obj_id = id(memory_obj)
+        with self._objects_lock:
+            if obj_id in self._pinned_objects:
+                del self._pinned_objects[obj_id]
+                logger.debug(
+                    "Unregistered pinned object %s from timeout monitoring",
+                    obj_id,
+                )
+
+    def _check_timeouts(self) -> tuple[int, int, int]:
+        """Check all registered pinned objects for timeout.
+
+        Returns:
+            tuple: (pinned_count, timeout_count, force_unpin_success_count)
+        """
+        current_time = time.time()
+        timeout_objects = []
+
+        with self._objects_lock:
+            pinned_count = len(self._pinned_objects)
+            for obj_id, (memory_obj, register_time) in list(
+                self._pinned_objects.items()
+            ):
+                # Check if object is still pinned and has exceeded timeout
+                if memory_obj.meta.pin_count > 0:
+                    elapsed_time = current_time - register_time
+                    if elapsed_time > self._pin_timeout_sec:
+                        timeout_objects.append((memory_obj, elapsed_time))
+
+        # Force unpin timeout objects outside the lock to avoid deadlocks
+        force_unpin_success_count = 0
+        for memory_obj, elapsed_time in timeout_objects:
+            try:
+                self._force_unpin_timeout_object(memory_obj, elapsed_time)
+                force_unpin_success_count += 1
+            except Exception as e:
+                logger.error(
+                    "Error forcing unpin for timeout object %s: %s", id(memory_obj), e
+                )
+        if force_unpin_success_count > 0:
+            logger.warning(
+                "Force unpinned %d timeout objects in %d pinned_objects "
+                "within %d seconds",
+                force_unpin_success_count,
+                pinned_count,
+                self._pin_timeout_sec,
+            )
+        else:
+            logger.debug(
+                "PinMonitor check: pinned_objects=%d, timeout_objects=%d, "
+                "force_unpin_success=%d",
+                pinned_count,
+                len(timeout_objects),
+                force_unpin_success_count,
+            )
+
+        return pinned_count, len(timeout_objects), force_unpin_success_count
+
+    def _force_unpin_timeout_object(self, memory_obj: "MemoryObj", elapsed_time: float):
+        """Force unpin a timeout object and log the event."""
+        # Get current pin_count without holding the lock for unpin calls
+        # Use nullcontext if memory_obj doesn't have a lock attribute
+        obj_lock = getattr(memory_obj, "lock", None) or nullcontext()
+        with obj_lock:
+            current_pin_count = memory_obj.meta.pin_count
+            if current_pin_count <= 0:
+                return
+
+            logger.warning(
+                "Pin timeout detected for MemoryObj %s. "
+                "Pin count: %s, Elapsed time: %.2fs. Forcing unpin to 0.",
+                memory_obj.meta.address,
+                current_pin_count,
+                elapsed_time,
+            )
+
+        # Update forced unpin statistics
+        LMCStatsMonitor.GetOrCreate().update_forced_unpin_count(1)
+
+        # Call unpin() while pin_count > 0 to properly release resources
+        while memory_obj.meta.pin_count > 0:
+            memory_obj.unpin()
+
+    def _execute(self) -> ThreadRunSummary:
+        """
+        Execute one pin monitor check cycle.
+
+        This method is called by the PeriodicThread base class.
+
+        Returns:
+            ThreadRunSummary: Summary of the check cycle
+        """
+        pinned_count, timeout_count, force_unpin_count = self._check_timeouts()
+
+        return ThreadRunSummary(
+            success=True,
+            message=f"Checked {pinned_count} objects, {timeout_count} timeouts, "
+            f"{force_unpin_count} force unpinned",
+            extra_info={
+                "pinned_count": str(pinned_count),
+                "timeout_count": str(timeout_count),
+                "force_unpin_count": str(force_unpin_count),
+            },
+        )
+
+    def start_monitoring(self) -> None:
+        """Start the background monitoring thread."""
+        if self.is_running:
+            return
+
+        # Use base class start method
+        self.start()
+        logger.info("PinMonitor started")
+
+    def _setup_metrics(
+        self,
+        config: "LMCacheEngineConfig",
+        metadata: "LMCacheMetadata",
+    ) -> None:
+        prometheus_logger = PrometheusLogger.GetOrCreate(metadata, config=config)
+        prometheus_logger.pin_monitor_pinned_objects_count.set_function(
+            lambda: len(self._pinned_objects)
+        )
+
+    def stop_monitoring(self):
+        """Stop the background monitoring thread."""
+        if not self.is_running:
+            return
+
+        # Unregister from the global registry
+        PeriodicThreadRegistry.get_instance().unregister(self.name)
+
+        # Use base class stop method
+        self.stop()
+        logger.info("PinMonitor stopped")
+
+    def get_monitored_count(self) -> int:
+        """Get the number of currently monitored pinned objects."""
+        with self._objects_lock:
+            return len(self._pinned_objects)
+
+    @staticmethod
+    def DestroyInstance():
+        """Destroy the singleton instance and stop monitoring.
+        This is mainly used for testing to ensure clean state between tests.
+        """
+        with PinMonitor._instance_lock:
+            if PinMonitor._instance is not None:
+                PinMonitor._instance.stop_monitoring()
+                PinMonitor._instance = None
diff --git a/lmcache/v1/platform/__init__.py b/lmcache/v1/platform/__init__.py
new file mode 100644
index 0000000..5a068b1
--- /dev/null
+++ b/lmcache/v1/platform/__init__.py
@@ -0,0 +1,225 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cross-platform abstraction layer for LMCache.
+
+This package centralizes platform-specific primitives. It currently
+exposes :class:`EventNotifier` -- a thin wake-up primitive used to
+signal background loops from other threads.  On Linux it is backed by
+``os.eventfd``; on macOS / other POSIX systems it falls back to
+``os.pipe``.  Callers never touch ``os.eventfd`` directly.
+
+Accelerator- and OS-specific implementations live in dedicated sub-
+packages so each can evolve independently:
+
+* :mod:`lmcache.v1.platform.cuda` -- CUDA-backed implementations.
+* :mod:`lmcache.v1.platform.cpu`  -- CPU-only fallbacks.
+
+KV-cache IPC wrappers and ``BaseCacheContext`` subclasses are
+discovered separately on first use via
+:mod:`lmcache.v1.utils.subclass_discovery`, keyed by each subclass'
+``device_type`` ClassVar.  Adding a new accelerator therefore
+requires *zero* edits to this module -- drop a new
+``platform/<backend>/`` package and it will be picked up
+automatically.
+"""
+
+# Standard
+from typing import Any
+import importlib
+import os
+import types
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.platform.base_device_spec import DeviceSpec
+from lmcache.v1.platform.event_notifier import HAS_EVENTFD as HAS_EVENTFD
+from lmcache.v1.platform.event_notifier import EventfdNotifier as EventfdNotifier
+from lmcache.v1.platform.event_notifier import EventNotifier as EventNotifier
+from lmcache.v1.platform.event_notifier import PipeNotifier as PipeNotifier
+from lmcache.v1.platform.event_notifier import consume_fd as consume_fd
+from lmcache.v1.platform.event_notifier import (
+    create_event_notifier as create_event_notifier,
+)
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+logger = init_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Device spec registry
+# ---------------------------------------------------------------------------
+
+
+_DEVICE_REGISTRY: dict[str, DeviceSpec] = {
+    spec.device_type: spec
+    for spec in [
+        cls()
+        for cls in discover_subclasses(
+            "lmcache.v1.platform",
+            DeviceSpec,  # type: ignore[type-abstract]
+            module_filter=lambda name: not name.startswith(("_", "base")),
+            require_defined_in_module=True,
+            on_import_error=lambda name, exc: None,
+        )
+    ]
+}
+
+
+# ---------------------------------------------------------------------------
+# Device detection
+# ---------------------------------------------------------------------------
+
+
+def _detect_device() -> tuple[Any, str]:
+    """Detect the available accelerator via the device registry.
+
+    Returns:
+        tuple[Any, str]: A tuple of (torch_device_module, device_type_string).
+            When torch is not installed (CLI-only mode), returns
+            ``(None, "cpu")``.
+    """
+    try:
+        # Third Party
+        import torch
+    except ImportError as e:
+        logger.warning("load torch failed, error is %s", e)
+        return None, "cpu"  # fallback for CLI-only environments
+
+    # Check DEVICE_TYPE environment variable for forced device selection.
+    env_device_type = os.environ.get("DEVICE_TYPE")
+    if env_device_type is not None:
+        env_device_type = env_device_type.strip().lower()
+        spec = _DEVICE_REGISTRY.get(env_device_type)
+        if spec is not None and spec.is_available():
+            torch_module = getattr(torch, spec.torch_module_name, None)
+            if torch_module is not None:
+                return torch_module, spec.device_type
+            else:
+                logger.warning(
+                    "DEVICE_TYPE=%r is available but torch module [%s] not found, "
+                    "falling back to auto-detection.",
+                    env_device_type,
+                    spec.torch_module_name,
+                )
+        else:
+            logger.warning(
+                "DEVICE_TYPE=%r is not available or not registered, "
+                "falling back to auto-detection.",
+                env_device_type,
+            )
+
+    for spec in _DEVICE_REGISTRY.values():
+        if not spec.is_available():
+            continue
+
+        torch_module = getattr(torch, spec.torch_module_name, None)
+        if torch_module is not None:
+            return torch_module, spec.device_type
+        else:
+            logger.warning(
+                "device [%s] is available, but torch module [%s] is not found.",
+                spec.device_type,
+                spec.torch_module_name,
+            )
+
+    # No accelerator found -- fall back to CPU stub
+    # First Party
+    from lmcache.v1.platform.cpu.stub_cpu_device import StubCPUDevice
+
+    return StubCPUDevice("cpu"), "cpu"
+
+
+# ---------------------------------------------------------------------------
+# Get device spec
+# ---------------------------------------------------------------------------
+def get_device_spec(device_type: str) -> DeviceSpec | None:
+    """Get the DeviceSpec for the given device type.
+
+    Args:
+        device_type: The device type string (e.g. ``"cuda"``).
+
+    Returns:
+        The DeviceSpec for the given device type, or None if not found.
+    """
+    return _DEVICE_REGISTRY.get(device_type)
+
+
+# ---------------------------------------------------------------------------
+# Dynamic backend selection
+# ---------------------------------------------------------------------------
+
+
+def get_backend(device_type: str) -> Any | None:
+    """Select the ops backend for the given device type.
+
+    Looks up the :class:`DeviceSpec` for *device_type* in the registry
+    and loads/merges its ops module on top of the Python fallback.
+
+    Args:
+        device_type: The detected device type string (e.g. ``"cuda"``).
+
+    Returns:
+        A merged :class:`types.ModuleType` (fallback + hw-specific ops),
+        or ``None`` if torch / dependencies are unavailable.
+    """
+    try:
+        # Third Party
+        import torch  # noqa: F401
+    except (ImportError, ModuleNotFoundError) as e:
+        logger.warning("load torch failed, error is %s", e)
+        return None
+
+    try:
+        default_module = importlib.import_module("lmcache.python_ops_fallback")
+    except (ImportError, ModuleNotFoundError) as e:
+        logger.warning("Cannot load python_ops_fallback: %s", e)
+        return None
+
+    spec = _DEVICE_REGISTRY.get(device_type)
+    if spec is None:
+        logger.info("No DeviceSpec registered for %r, using fallback ops.", device_type)
+        return default_module
+
+    if not spec.is_available():
+        logger.warning("Device %s is not available, using fallback ops.", device_type)
+        return default_module
+
+    if not spec.ops_module:
+        # Device has no custom ops -- use fallback
+        logger.info(
+            "Custom ops not supported for device: %s, using fallback ops.", device_type
+        )
+        return default_module
+
+    try:
+        backend_module = importlib.import_module(spec.ops_module)
+        merged_module = types.ModuleType("lmcache.c_ops")
+        merged_module.__dict__.update(default_module.__dict__)
+        merged_module.__dict__.update(backend_module.__dict__)
+        logger.info("Using backend: %s", spec.ops_module)
+        return merged_module
+    except Exception as e:
+        logger.warning("Failed to import backend %s: %s", spec.ops_module, e)
+
+    return default_module
+
+
+torch_dev, torch_device_type = _detect_device()
+
+logger.info("torch_dev=%s, torch_device_type=%s", torch_dev, torch_device_type)
+
+
+# Resolve the DeviceSpec for the detected device so callers can use
+# platform-specific capabilities (e.g. ``current_device_spec.pin_memory(...)``)
+# without touching the torch device module.  When no accelerator sub-
+# package matches, fall back to a bare ``DeviceSpec()`` -- its default
+# implementation provides "no-op / all False" semantics.
+_registered_device_spec = _DEVICE_REGISTRY.get(torch_device_type)
+if _registered_device_spec is None:
+    if torch_device_type != "cpu":
+        logger.warning(
+            "No DeviceSpec registered for %r; using fallback with no-op capabilities.",
+            torch_device_type,
+        )
+    current_device_spec: DeviceSpec = DeviceSpec()
+else:
+    current_device_spec = _registered_device_spec
diff --git a/lmcache/v1/platform/_registry.py b/lmcache/v1/platform/_registry.py
new file mode 100644
index 0000000..e2bd50d
--- /dev/null
+++ b/lmcache/v1/platform/_registry.py
@@ -0,0 +1,223 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Platform backend registry.
+
+Each accelerator sub-package (``platform/cuda``, ``platform/cpu``,
+future ``platform/xpu`` ...) ships a concrete
+:class:`~lmcache.v1.platform.base_ipc_wrapper.DeviceIPCWrapper`
+subclass with a ``device_type`` ClassVar and a ``wrap`` factory
+classmethod.  :func:`_discover_wrappers_once` scans the ``platform``
+package for those subclasses at run-time and populates the factory
+table -- no static ``register_kv_wrapper`` calls needed.
+
+The :func:`get_kv_wrapper_factory` lookup keys on
+``tensor.device.type`` so the call site in
+:mod:`lmcache.integration.vllm.vllm_multi_process_adapter` stays free
+of any if/elif chain.  Adding a new accelerator therefore requires
+*zero* changes to the dispatcher; it only needs to ship its own
+sub-package with a ``DeviceIPCWrapper`` subclass that sets
+``device_type`` and ``wrap``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any, Callable, Dict
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+# Public sentinel used by callers who want the always-available
+# fall-back regardless of the running ``torch_device_type``.
+DEFAULT_BACKEND: str = "cpu"
+
+
+# KV-cache IPC wrapper factory per device type.  Populated lazily on
+# first :func:`get_kv_wrapper_factory` call by scanning the
+# ``platform`` package for
+# :class:`~lmcache.v1.platform.base_ipc_wrapper.DeviceIPCWrapper`
+# subclasses.  Tests substitute entries via
+# :func:`snapshot` / :func:`restore`.
+_KV_WRAPPER_FACTORIES: Dict[str, Callable[..., Any]] = {}
+
+# Guard so discovery only runs once (lazy init).  The lock plus the
+# double-checked flag below keep the first concurrent caller from
+# racing a second one through the scan and emitting duplicate
+# "multiple wrappers claim device_type=..." warnings.
+_WRAPPERS_DISCOVERED: bool = False
+_DISCOVERY_LOCK = threading.Lock()
+
+
+def _discover_wrappers_once() -> None:
+    """Populate :data:`_KV_WRAPPER_FACTORIES` on first use.
+
+    Walks ``lmcache.v1.platform`` two levels deep for
+    :class:`~lmcache.v1.platform.base_ipc_wrapper.DeviceIPCWrapper`
+    subclasses.  Each subclass is indexed by its *device_type*
+    ClassVar, and its *wrap* factory is stored as the KV-wrapper
+    factory — but only when ``_is_default_wrapper`` is ``True``
+    (so e.g. :class:`~lmcache.v1.platform.cuda.ipc_wrapper.RawCudaIPCWrapper`
+    is skipped in favour of
+    :class:`~lmcache.v1.platform.cuda.ipc_wrapper.CudaIPCWrapper`).
+
+    Subclasses with an empty *device_type* or ``_is_default_wrapper ==
+    False`` are skipped.  Multiple subclasses claiming the same
+    *device_type* trigger a warning; the first one wins.
+    """
+    global _WRAPPERS_DISCOVERED
+    # Fast path: avoid the lock once discovery is done (the common case).
+    if _WRAPPERS_DISCOVERED:
+        return
+
+    with _DISCOVERY_LOCK:
+        # Re-check under the lock: another thread may have run the
+        # scan while we were waiting.
+        if _WRAPPERS_DISCOVERED:
+            return
+
+        # First Party
+        from lmcache.v1.platform.base_ipc_wrapper import DeviceIPCWrapper
+        from lmcache.v1.utils.subclass_discovery import discover_subclasses
+        import lmcache.v1.platform as platform_pkg
+
+        for cls in discover_subclasses(
+            platform_pkg,
+            DeviceIPCWrapper,  # type: ignore[type-abstract]
+            levels=[2, 2],
+        ):
+            _register_discovered_wrapper(cls)
+
+        _WRAPPERS_DISCOVERED = True
+
+
+def _register_discovered_wrapper(cls: type) -> None:
+    """Index *cls* in :data:`_KV_WRAPPER_FACTORIES` by its device_type.
+
+    Only registers when ``_is_default_wrapper`` is ``True`` so sibling
+    subclasses (e.g. ``RawCudaIPCWrapper`` vs ``CudaIPCWrapper``) can
+    share a ``device_type`` without colliding.
+    """
+    if not getattr(cls, "_is_default_wrapper", False):
+        return
+
+    device_type: str = getattr(cls, "device_type", "")
+    if not device_type:
+        logger.warning(
+            "Skipping %s: empty device_type ClassVar; concrete "
+            "DeviceIPCWrapper subclasses must override it.",
+            cls.__name__,
+        )
+        return
+
+    factory = getattr(cls, "wrap", cls)
+    existing = _KV_WRAPPER_FACTORIES.get(device_type)
+    if existing is not None and existing is not factory:
+        logger.warning(
+            "Multiple KV-wrapper classes claim device_type=%r "
+            "(%s vs %s); keeping the first.",
+            device_type,
+            getattr(existing, "__name__", str(existing)),
+            cls.__name__,
+        )
+        return
+
+    _KV_WRAPPER_FACTORIES[device_type] = factory
+
+
+def register_kv_wrapper(device_type: str, factory: Callable[..., Any]) -> None:
+    """Register a KV-cache IPC wrapper factory for ``device_type``.
+
+    This is the manual registration path kept for backward
+    compatibility.  New backends should instead set ``device_type``
+    and ``wrap`` on their :class:`DeviceIPCWrapper` subclass and let
+    :func:`_discover_wrappers_once` handle registration.
+
+    Args:
+        device_type: The device type string (e.g., ``"cuda"``).
+        factory: A callable that takes a single ``torch.Tensor`` and
+            returns a wrapper instance ready for the multiprocess wire.
+    """
+    _KV_WRAPPER_FACTORIES[device_type] = factory
+
+
+def get_kv_wrapper_factory(device_type: str) -> Callable[..., Any]:
+    """Pick the KV-cache wrapper factory for ``device_type``.
+
+    Triggers lazy auto-discovery on first call (see
+    :func:`_discover_wrappers_once`).  A missing entry means no
+    :class:`~lmcache.v1.platform.base_ipc_wrapper.DeviceIPCWrapper`
+    subclass declared *device_type* for the requested backend.
+
+    Args:
+        device_type: The device type string (e.g., ``"cuda"``).
+
+    Returns:
+        The registered KV-cache wrapper factory for the device type.
+
+    Raises:
+        ValueError: If no factory is registered for the device type.
+    """
+    _discover_wrappers_once()
+    factory = _KV_WRAPPER_FACTORIES.get(device_type)
+    if factory is None:
+        raise ValueError(
+            "No KV-cache wrapper factory registered for device type %r" % device_type
+        )
+    return factory
+
+
+def snapshot() -> Dict[str, Any]:
+    """Return a deep-copy of the registry tables.
+
+    Test suites use this to install backend overrides without leaking
+    state across tests; pair with :func:`restore` in a ``finally`` /
+    fixture teardown clause.
+
+    The lazy-discovery flag is captured alongside the tables: if a test
+    snapshots *before* discovery runs and restores *after*, the next
+    caller still re-runs discovery and picks up the auto-registered
+    backends, instead of seeing a stale "already discovered, table is
+    empty" view.
+
+    Returns:
+        A dict with keys ``"kv_wrapper"``, and ``"discovered"``.
+    """
+    return {
+        "kv_wrapper": dict(_KV_WRAPPER_FACTORIES),
+        "discovered": _WRAPPERS_DISCOVERED,
+    }
+
+
+def restore(state: Dict[str, Any]) -> None:
+    """Restore registry tables to a previously :func:`snapshot`-ed state.
+
+    Args:
+        state: A snapshot dict as returned by :func:`snapshot`.
+    """
+    global _WRAPPERS_DISCOVERED
+    _KV_WRAPPER_FACTORIES.clear()
+    _KV_WRAPPER_FACTORIES.update(state.get("kv_wrapper", {}))
+    _WRAPPERS_DISCOVERED = bool(state.get("discovered", False))
+
+
+def reset_for_tests() -> None:
+    """Wipe registry tables and force re-discovery on next access.
+
+    Intended **only** for test fixtures: clears every registered KV
+    wrapper and flips
+    :data:`_WRAPPERS_DISCOVERED` back to ``False`` so the next
+    :func:`get_kv_wrapper_factory` call re-runs the
+    :func:`_discover_wrappers_once` scan and re-populates the table
+    from the live ``platform`` sub-packages.
+
+    This is the recommended replacement for callers that previously
+    hand-mutated module-private globals; pair with an ``autouse``
+    pytest fixture to guarantee every test starts and ends with a
+    clean slate (see ``tests/v1/multiprocess/conftest.py``).
+    """
+    global _WRAPPERS_DISCOVERED
+    _KV_WRAPPER_FACTORIES.clear()
+    _WRAPPERS_DISCOVERED = False
diff --git a/lmcache/v1/platform/base_cache_context.py b/lmcache/v1/platform/base_cache_context.py
new file mode 100644
index 0000000..f5e1367
--- /dev/null
+++ b/lmcache/v1/platform/base_cache_context.py
@@ -0,0 +1,345 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract base class for platform cache contexts.
+
+Defines the common interface shared by :class:`GPUCacheContext` and
+:class:`CPUCacheContext`.  Concrete subclasses provide
+device-specific implementations of stream / buffer / copy primitives
+while the base class owns layout-agnostic helpers (shape calculation,
+status reporting, block-ID staging).
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, ClassVar
+import array
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.utils import (
+    get_attention_backend,
+    get_concrete_engine_kv_shape_from_shape_desc,
+    get_engine_kv_shape_description,
+    is_mla,
+)
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+
+if TYPE_CHECKING:
+    # First Party
+    import lmcache.c_ops as lmc_ops
+
+
+class BaseCacheContext(ABC):
+    """Abstract base for GPU and CPU cache contexts.
+
+    Subclasses call :meth:`__init__` after computing the common
+    layout parameters and before setting up device-specific state.
+    All keyword arguments are required so the contract is explicit.
+
+    Concrete subclasses MUST set :attr:`device_type` to the
+    ``torch.device.type`` string they handle (``"cuda"``, ``"cpu"``,
+    ...). The platform-agnostic :func:`create_cache_context` factory
+    uses this attribute (via the platform registry) to pick the right
+    subclass without any ``isinstance`` / ``if-elif`` chain.
+    """
+
+    #: ``torch.device.type`` string the subclass handles. Concrete
+    #: subclasses MUST override this.
+    device_type: ClassVar[str] = ""
+
+    def __init__(
+        self,
+        *,
+        kv_caches: list[torch.Tensor],
+        device: torch.device,
+        num_layers: int,
+        kv_layer_groups_manager: KVLayerGroupsManager,
+        block_ids_buffer: torch.Tensor,
+        lmcache_tokens_per_chunk: int,
+    ) -> None:
+        self.kv_caches_ = kv_caches
+        self.device_ = device
+        self.num_layers_ = num_layers
+        self.kv_layer_groups_manager_ = kv_layer_groups_manager
+        self.block_ids_buffer_ = block_ids_buffer
+        self.lmcache_tokens_per_chunk = lmcache_tokens_per_chunk
+
+    # ------------------------------------------------------------------
+    # Abstract -- subclasses MUST implement
+    # ------------------------------------------------------------------
+
+    @property
+    @abstractmethod
+    def stream(self) -> Any:
+        """Returns the device-specific stream for async operations."""
+        ...
+
+    @property
+    @abstractmethod
+    def cupy_stream(self) -> Any:
+        """Returns the cupy ExternalStream wrapping *stream*."""
+        ...
+
+    @property
+    @abstractmethod
+    def max_batch_size(self) -> int:
+        """Returns the maximum number of concurrent batches."""
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release device-specific resources (GDS staging buffers, etc.)."""
+        ...
+
+    @abstractmethod
+    def get_kernel_group_kv_pointers(self, kernel_group_idx: int) -> torch.Tensor:
+        """Returns the KV-cache pointer tensor for *kernel_group_idx*."""
+        ...
+
+    @abstractmethod
+    def get_temp_kernel_group_buffer(
+        self, batch_idx: int, kernel_group_idx: int
+    ) -> torch.Tensor:
+        """Returns a typed temp-buffer view for a (batch, kernel-group)
+        pair."""
+        ...
+
+    @abstractmethod
+    def get_temp_object_group_buffer(
+        self, batch_idx: int, object_group_idx: int
+    ) -> torch.Tensor:
+        """Returns a flat uint8 temp-buffer view for a (batch, object-group)
+        pair."""
+        ...
+
+    @abstractmethod
+    def get_kernel_group_shape_dtype(
+        self,
+        num_tokens: int,
+        kernel_group_idx: int,
+    ) -> tuple[torch.Size, torch.dtype]:
+        """Returns ``(shape, dtype)`` for *kernel_group_idx*."""
+        ...
+
+    @abstractmethod
+    def cache_size_per_token(self) -> int:
+        """Returns cache size per logical token in bytes (all groups)."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Concrete -- shared implementations
+    # ------------------------------------------------------------------
+
+    @property
+    def device(self) -> torch.device:
+        """Returns the device where KV-cache tensors live."""
+        return self.device_
+
+    @property
+    def kv_tensors(self) -> list[torch.Tensor]:
+        """Returns the list of per-layer KV cache tensors."""
+        return self.kv_caches_
+
+    @property
+    def num_layers(self) -> int:
+        """Returns the number of layers in the model."""
+        return self.num_layers_
+
+    @property
+    def num_blocks(self) -> int:
+        """Returns the number of blocks in the KV cache.
+
+        Sourced from the kernel groups (one shared block-id space), not a
+        representative-format computation.
+        """
+        return self.kv_layer_groups_manager_.num_blocks
+
+    @property
+    def hidden_dim_sizes(self) -> list[int]:
+        """Returns hidden dimension sizes per KV layer group."""
+        return [
+            group.hidden_dim_size
+            for group in self.kv_layer_groups_manager.kv_layer_groups
+        ]
+
+    @property
+    def kv_layer_groups_manager(self) -> KVLayerGroupsManager:
+        """Returns the KV layer groups manager."""
+        return self.kv_layer_groups_manager_
+
+    def calculate_num_blocks(self, num_tokens: int, kernel_group_idx: int) -> int:
+        """Calculate the number of blocks for *num_tokens* in a kernel
+        group."""
+        return self.kv_layer_groups_manager.calculate_num_blocks(
+            kernel_group_idx, num_tokens
+        )
+
+    def get_shape_desc(self, group_idx: int) -> "lmc_ops.PageBufferShapeDesc":
+        """Returns the PageBufferShapeDesc for *group_idx*."""
+        return self.kv_layer_groups_manager.get_shape_desc(group_idx)
+
+    def get_engine_kv_format(self, kernel_group_idx: int) -> "lmc_ops.EngineKVFormat":
+        """Returns the Engine KV format of kernel *kernel_group_idx*.
+
+        Raises:
+            ValueError: If the group has no format (a bookkeeping group built by
+                ``parse_kvcache_shape_spec`` should never reach the transfer
+                path; detection-built groups always carry one).
+        """
+        groups = self.kv_layer_groups_manager.kv_layer_groups
+        engine_kv_format = groups[kernel_group_idx].engine_kv_format
+        if engine_kv_format is None:
+            raise ValueError(
+                f"kernel group {kernel_group_idx} has no engine_kv_format; a "
+                "formatless bookkeeping group reached the transfer path"
+            )
+        return engine_kv_format
+
+    def engine_kv_formats(self) -> list["lmc_ops.EngineKVFormat"]:
+        """Returns the Engine KV format of each kernel group, in group order."""
+        num_groups = len(self.kv_layer_groups_manager.kernel_groups)
+        return [self.get_engine_kv_format(idx) for idx in range(num_groups)]
+
+    def engine_kv_format_per_layer(self) -> list["lmc_ops.EngineKVFormat | None"]:
+        """Returns each layer's Engine KV format, indexed by layer index.
+
+        Formats differ across layers for a mixed-format model. ``None`` marks a
+        layer in no kernel group (a cross-layer KV-sharing layer).
+        """
+        formats: list["lmc_ops.EngineKVFormat | None"] = [None] * len(self.kv_caches_)
+        for kernel_group_idx, group in enumerate(
+            self.kv_layer_groups_manager.kernel_groups
+        ):
+            fmt = self.get_engine_kv_format(kernel_group_idx)
+            for layer_idx in group.layer_indices:
+                formats[layer_idx] = fmt
+        return formats
+
+    def get_slots_per_chunk_in_sw(self, kernel_group_idx: int) -> int:
+        """Returns the number of slots per lmcache chunk for D/H
+        transfer."""
+        return self.kv_layer_groups_manager.get_slots_per_chunk_in_sw(kernel_group_idx)
+
+    def get_kv_buffer_shape(
+        self, logical_num_tokens: int, group_idx: int = 0
+    ) -> torch.Size:
+        """Returns the KV buffer shape for *logical_num_tokens*."""
+        group = self.kv_layer_groups_manager.kv_layer_groups[group_idx]
+        compress_ratio = group.tokens_per_block // group.slots_per_block
+        if logical_num_tokens % compress_ratio != 0:
+            raise ValueError(
+                "logical_num_tokens (%d) is not a multiple of "
+                "compress_ratio (%d) for group %d"
+                % (logical_num_tokens, compress_ratio, group_idx)
+            )
+        num_slots = logical_num_tokens // compress_ratio
+        sd = group.shape_desc
+        return torch.Size(
+            (sd.kv_size, group.num_layers, num_slots, group.hidden_dim_size)
+        )
+
+    def stage_block_ids(
+        self, block_ids_per_group: list[list[int]]
+    ) -> list[torch.Tensor]:
+        """Stage per-group block IDs into the shared staging buffer.
+
+        Returns one non-overlapping view per LMCache group.
+        """
+        offsets = [0]
+        flat: array.array = array.array("q")
+        for view_block_ids in block_ids_per_group:
+            flat.extend(view_block_ids)
+            offsets.append(len(flat))
+
+        total = offsets[-1]
+        if total > self.block_ids_buffer_.shape[0]:
+            raise ValueError(
+                "block ID total %d exceeds the pre-allocated buffer "
+                "size %d" % (total, self.block_ids_buffer_.shape[0])
+            )
+        if total:
+            cpu_tensor = torch.frombuffer(flat, dtype=torch.long)
+            self.block_ids_buffer_[:total].copy_(cpu_tensor, non_blocking=True)
+
+        return [
+            self.block_ids_buffer_[offsets[i] : offsets[i + 1]]
+            for i in range(len(block_ids_per_group))
+        ]
+
+    # ------------------------------------------------------------------
+    # Derived properties (pure helpers)
+    # ------------------------------------------------------------------
+
+    @property
+    def concrete_engine_kv_shape(self) -> str:
+        """Returns the engine KV shape with actual numeric values."""
+        group = self.kv_layer_groups_manager.kv_layer_groups[0]
+        return get_concrete_engine_kv_shape_from_shape_desc(
+            group.shape_desc, group.engine_kv_format
+        )
+
+    # ------------------------------------------------------------------
+    # Shared report_status
+    # ------------------------------------------------------------------
+
+    def _build_group_report_map(self) -> dict[int, int]:
+        """Map each kernel-group index to its owning object-group index."""
+        return {
+            kg_idx: og_idx
+            for og_idx, og in enumerate(self.kv_layer_groups_manager.object_groups)
+            for kg_idx in og.kernel_group_indices
+        }
+
+    def _build_single_group_report(
+        self,
+        kernel_group_idx: int,
+        group: Any,
+        group_map: dict[int, int],
+    ) -> dict:
+        """Build a status dict for a single kernel group.
+
+        Override this in subclasses to inject extra per-group fields
+        without duplicating the whole :meth:`report_status` method.
+        """
+        engine_kv_format = self.get_engine_kv_format(kernel_group_idx)
+        return {
+            "kernel_group_idx": kernel_group_idx,
+            "engine_group_idx": group.engine_group_idx,
+            "object_group_idx": group_map.get(kernel_group_idx, 0),
+            "num_layers": group.num_layers,
+            "layer_indices": list(group.layer_indices),
+            "tokens_per_block": group.tokens_per_block,
+            "slots_per_block": group.slots_per_block,
+            "dtype": str(group.dtype),
+            "engine_kv_concrete_shape": (
+                get_concrete_engine_kv_shape_from_shape_desc(
+                    group.shape_desc, engine_kv_format
+                )
+            ),
+            "is_mla": is_mla(engine_kv_format),
+            "engine_kv_format": engine_kv_format.name,
+            "engine_kv_shape": get_engine_kv_shape_description(engine_kv_format),
+            "attention_backend": get_attention_backend(engine_kv_format),
+        }
+
+    def report_status(self) -> dict:
+        """Return this context's KV cache layout metadata."""
+        manager = self.kv_layer_groups_manager
+        kernel_groups = manager.kernel_groups
+        group_map = self._build_group_report_map()
+
+        group_reports = [
+            self._build_single_group_report(kernel_group_idx, group, group_map)
+            for kernel_group_idx, group in enumerate(kernel_groups)
+        ]
+
+        return {
+            "num_layers": self.num_layers,
+            "num_blocks": self.num_blocks,
+            "cache_size_per_token": self.cache_size_per_token(),
+            "kernel_groups": group_reports,
+        }
diff --git a/lmcache/v1/platform/base_device_spec.py b/lmcache/v1/platform/base_device_spec.py
new file mode 100644
index 0000000..9d40a70
--- /dev/null
+++ b/lmcache/v1/platform/base_device_spec.py
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base class for platform device specification.
+
+Each accelerator sub-package (``platform/cuda``, ``platform/musa``, ...)
+provides a concrete :class:`DeviceSpec` subclass that describes how to
+detect the device and which ops backend to load.
+
+The :mod:`~lmcache.v1.platform` module discovers these
+subclasses automatically at import time via ``pkgutil.iter_modules``:
+it imports each sub-package, inspects its module namespace for
+:class:`DeviceSpec` subclasses, instantiates them, and uses the
+resulting objects for device detection and backend selection.
+
+No manual registration (e.g. ``DEVICE_SPEC = ...``) is required --
+simply defining the subclass in the sub-package's ``__init__.py`` is
+enough.
+
+:class:`DeviceSpec` itself is instantiable and doubles as the fallback
+implementation used when no accelerator sub-package matches the
+detected device: all capabilities default to a safe "no-op / False"
+behaviour, and ``device_type`` / ``torch_module_name`` default to
+``"cpu"``.
+"""
+
+# First Party
+from lmcache.v1.platform.base_pin_memory import PinMemoryBackend
+
+
+# TODO(chunxiaozheng): bind `DeviceIPCWrapper` with `DeviceSpec`?
+class DeviceSpec:
+    """Description of a hardware accelerator backend.
+
+    Subclasses override the properties / methods below to describe a
+    concrete accelerator.  Defining a concrete subclass in a platform
+    sub-package's ``__init__.py`` is sufficient for auto-discovery.
+
+    Instantiating :class:`DeviceSpec` directly yields the fallback
+    implementation with "no-op / all False" semantics -- this is the
+    behaviour used for CPU-only or unknown device types.
+    """
+
+    # Cached pin-memory backend instance (lazy-initialized).
+    _pin_backend_cache: PinMemoryBackend | None = None
+
+    @property
+    def device_type(self) -> str:
+        """Device type string (e.g. ``"cuda"``, ``"musa"``, ``"mlu"``).
+
+        Defaults to ``"cpu"`` for the fallback implementation.
+        """
+        return "cpu"
+
+    @property
+    def torch_module_name(self) -> str:
+        """Attribute name on the ``torch`` package for the device module.
+
+        For example, ``"cuda"`` corresponds to ``torch.cuda``.  Defaults
+        to ``"cpu"`` for the fallback implementation.
+        """
+        return "cpu"
+
+    @property
+    def ops_module(self) -> str | None:
+        """Fully-qualified module path for the compiled ops backend.
+
+        Return ``None`` if no custom ops are available (fallback only).
+        """
+        return None
+
+    def is_available(self) -> bool:
+        """Return ``True`` when the device is usable on this system.
+
+        This method must NOT import from ``lmcache.__init__`` to avoid
+        circular dependencies.  Use ``import torch`` directly instead.
+        The fallback implementation always returns ``False`` so that
+        auto-detection never picks it up.
+        """
+        return False
+
+    def is_handle_transfer_available(self) -> bool:
+        """Return ``True`` when the device is usable for handle transfer."""
+        # TODO(chunxiaozheng): implement on subclasses
+        return True
+
+    @property
+    def pin_memory_backend(self) -> type[PinMemoryBackend] | None:
+        """PinMemoryBackend subclass for this device, or None for default.
+
+        Subclasses that support host-memory pinning should override this
+        property and return the appropriate backend class.  Use a lazy
+        import inside the property body to avoid heavy imports at class
+        definition time.
+        """
+        return None
+
+    def _get_pin_backend(self) -> PinMemoryBackend:
+        """Return the cached pin-memory backend, instantiating on first use."""
+        backend = self._pin_backend_cache
+        if backend is None:
+            backend_cls = self.pin_memory_backend or PinMemoryBackend
+            backend = backend_cls()
+            self._pin_backend_cache = backend
+        return backend
+
+    def pin_memory(self, ptr: int, size: int, flags: int = 0) -> bool:
+        """Pin a host memory region for DMA access.
+
+        Args:
+            ptr: Raw pointer (data_ptr) to the memory region.
+            size: Size in bytes of the region to pin.
+            flags: Platform-specific registration flags (e.g.
+                ``cudaHostRegisterDefault = 0``).
+
+        Returns:
+            True if pinning succeeded, False otherwise.
+        """
+        return self._get_pin_backend().pin_memory(ptr, size, flags)
+
+    def unpin_memory(self, ptr: int) -> bool:
+        """Unpin a previously pinned host memory region.
+
+        Args:
+            ptr: Raw pointer (data_ptr) to the memory region.
+
+        Returns:
+            True if unpinning succeeded, False otherwise.
+        """
+        return self._get_pin_backend().unpin_memory(ptr)
+
+    @property
+    def is_pin_supported(self) -> bool:
+        """Whether the current platform supports memory pinning."""
+        return self._get_pin_backend().is_pin_supported
diff --git a/lmcache/v1/platform/base_ipc_wrapper.py b/lmcache/v1/platform/base_ipc_wrapper.py
new file mode 100644
index 0000000..15fc7ec
--- /dev/null
+++ b/lmcache/v1/platform/base_ipc_wrapper.py
@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base class for device IPC wrappers.
+
+:class:`DeviceIPCWrapper` is the abstract base for KV-cache IPC wrapper
+implementations.  Every concrete wrapper (e.g. :class:`~.cpu.shm.CpuShmTensorWrapper`,
+:class:`~.cuda.ipc_wrapper.CudaIPCWrapper`) subclasses it so they share
+the single msgspec ext code (1) -- pickle preserves the concrete
+subclass identity across the wire so ``to_tensor`` dispatches correctly
+on the receiving side.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any, Tuple
+import pickle
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+
+
+class DeviceIPCWrapper:
+    """Base class for KV-cache IPC wrapper.
+
+    Holds the device-agnostic mechanism shared by all transports: the
+    interface fields (``dtype``/``shape``/``stride``/``storage_offset``/
+    ``device_uuid``), UUID<->ordinal discovery via the ``torch_dev``
+    abstraction, equality, and pickle-based (de)serialization.
+
+    Every wire-level wrapper subclasses this so they share the single
+    msgspec ext code (1) registered for ``DeviceIPCWrapper``: pickle
+    preserves the concrete subclass identity across the wire so
+    ``to_tensor`` dispatches correctly on the receiving side.
+
+    Subclasses implement ``__init__`` (populate the interface fields from a
+    tensor) and ``to_tensor`` (reconstruct the tensor from the handle).
+
+    Concrete subclasses set ``_is_default_wrapper = True`` (a ``ClassVar``)
+    to mark themselves as the default factory for their ``device_type``;
+    auto-discovery in :mod:`lmcache.v1.platform._registry` reads it via
+    ``getattr(cls, "_is_default_wrapper", False)`` so the attribute is
+    intentionally not declared on the base class.
+    """
+
+    # Interface fields populated by each concrete subclass's
+    # ``__init__``.  Declared here so the base-class ``__eq__`` (and
+    # type-checkers) can see them; ``handle`` is intentionally typed as
+    # ``Any`` because each backend stores a different opaque payload
+    # (``tuple`` for CUDA shared-storage IPC, ``None`` for the SHM /
+    # raw-CUDA paths that override ``to_tensor``).
+    handle: Any
+    dtype: torch.dtype
+    shape: Tuple[int, ...]
+    stride: Tuple[int, ...]
+    storage_offset: int
+    device_uuid: str
+
+    _discovered_device_mapping: dict[str, int] = {}
+    _device_mapping_lock = threading.Lock()
+
+    @classmethod
+    def _get_device_uuid(cls, device_index: int) -> str:
+        """Get the UUID of a device given its index."""
+        return str(torch_dev.get_device_properties(device_index).uuid)
+
+    @classmethod
+    def _discover_devices(cls) -> None:
+        """Discover all available accelerator devices and map their UUIDs
+        to the physical device ordinals.
+        """
+        if not torch_dev.is_available():
+            return
+
+        num_devices = torch_dev.device_count()
+        with DeviceIPCWrapper._device_mapping_lock:
+            if DeviceIPCWrapper._discovered_device_mapping:
+                return  # Already discovered
+
+            for i in range(num_devices):
+                device_uuid = cls._get_device_uuid(i)
+                DeviceIPCWrapper._discovered_device_mapping[device_uuid] = i
+
+    @classmethod
+    def _get_device_index_from_uuid(cls, device_uuid: str) -> int:
+        """Get the physical device ordinal from its UUID."""
+        cls._discover_devices()
+
+        with DeviceIPCWrapper._device_mapping_lock:
+            device_index = DeviceIPCWrapper._discovered_device_mapping.get(
+                device_uuid, None
+            )
+
+        if device_index is None:
+            raise RuntimeError(
+                f"Device UUID {device_uuid} not found in the discovered "
+                "devices. Please make sure the process can see all the "
+                "accelerator devices"
+            )
+        return device_index
+
+    def to_tensor(self) -> torch.Tensor:
+        """Reconstruct the tensor in this process from the IPC handle.
+
+        Subclasses implement the transport-specific reconstruction.
+        """
+        raise NotImplementedError
+
+    def __eq__(self, other: object) -> bool:
+        # ``isinstance`` first so type-checkers can narrow ``other`` to
+        # ``DeviceIPCWrapper`` before we touch its attributes; the
+        # exact-type check that follows then enforces that, e.g., a
+        # ``CudaIPCWrapper`` is never considered equal to a
+        # ``RawCudaIPCWrapper`` even though they share a base class.
+        if not isinstance(other, DeviceIPCWrapper):
+            return False
+        if type(self) is not type(other):
+            return False
+        return (
+            self.handle == other.handle
+            and self.dtype == other.dtype
+            and self.shape == other.shape
+            and self.stride == other.stride
+            and self.storage_offset == other.storage_offset
+            and self.device_uuid == other.device_uuid
+        )
+
+    @staticmethod
+    def Serialize(obj: "DeviceIPCWrapper") -> bytes:
+        """Pickle ``obj`` for the multiprocess wire.
+
+        Pickle (rather than msgspec) is used so the concrete subclass
+        identity round-trips: every wrapper shares the single msgspec
+        ext code (1), and the receiver relies on the unpickled type to
+        dispatch ``to_tensor`` correctly.
+
+        Args:
+            obj: The wrapper instance to serialize.
+
+        Returns:
+            The pickled bytes payload.
+        """
+        return pickle.dumps(obj)
+
+    @staticmethod
+    def Deserialize(data: bytes) -> "DeviceIPCWrapper":
+        """Inverse of :meth:`Serialize`.
+
+        Args:
+            data: The pickled bytes payload produced by :meth:`Serialize`.
+
+        Returns:
+            The reconstructed wrapper instance, with its concrete
+            subclass identity preserved.
+        """
+        return pickle.loads(data)
diff --git a/lmcache/v1/platform/base_pin_memory.py b/lmcache/v1/platform/base_pin_memory.py
new file mode 100644
index 0000000..bd8ca23
--- /dev/null
+++ b/lmcache/v1/platform/base_pin_memory.py
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Platform-abstraction base classes.
+
+This module defines abstract base classes for platform-specific capabilities.
+:class:`PinMemoryBackend` is the first; future platform abstractions should
+be added here as well.
+"""
+
+
+class PinMemoryBackend:
+    """Base class for host-memory pinning per platform.
+
+    The default implementation is a no-op that always returns ``False``,
+    so platforms that do not support pinning do not need to subclass this.
+    """
+
+    def pin_memory(self, ptr: int, size: int, flags: int = 0) -> bool:
+        """Pin a host memory region for DMA access.
+
+        Args:
+            ptr: Raw pointer (data_ptr) to the memory region.
+            size: Size in bytes of the region to pin.
+            flags: Platform-specific registration flags (e.g.
+                ``cudaHostRegisterDefault = 0``).
+
+        Returns:
+            True if pinning succeeded, False otherwise.
+        """
+        return False
+
+    def unpin_memory(self, ptr: int) -> bool:
+        """Unpin a previously pinned host memory region.
+
+        Args:
+            ptr: Raw pointer (data_ptr) to the memory region.
+
+        Returns:
+            True if unpinning succeeded, False otherwise.
+        """
+        return False
+
+    @property
+    def is_pin_supported(self) -> bool:
+        """Whether the current platform supports memory pinning.
+
+        Returns:
+            True if pinning is supported, False otherwise.
+        """
+        return False
diff --git a/lmcache/v1/platform/cache_context.py b/lmcache/v1/platform/cache_context.py
new file mode 100644
index 0000000..ae54c16
--- /dev/null
+++ b/lmcache/v1/platform/cache_context.py
@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Platform-agnostic cache-context factory.
+
+The concrete implementations live in their respective sub-packages:
+
+* :class:`~lmcache.v1.platform.cuda.cache_context.GPUCacheContext` --
+  CUDA-backed.
+* :class:`~lmcache.v1.platform.cpu.cache_context.CPUCacheContext` --
+  CPU-only fallback (POSIX-SHM-backed KV tensors).
+
+:func:`create_cache_context` keeps the dispatch out of the call site
+in :mod:`lmcache.v1.multiprocess.server`. Selection is data-driven:
+each backend sub-package ships its own
+:class:`~lmcache.v1.platform.base_cache_context.BaseCacheContext`
+subclass under ``platform/<backend>/cache_context.py`` and declares
+the ``torch.device.type`` it handles via the
+:attr:`BaseCacheContext.device_type` ClassVar. The first
+:func:`create_cache_context` call discovers those subclasses with
+:func:`lmcache.v1.utils.subclass_discovery.discover_subclasses` and
+memoises the resulting ``device_type -> class`` map. Adding a new
+accelerator therefore requires *zero* edits to this module -- just
+drop a new ``platform/<backend>/cache_context.py`` whose subclass
+sets ``device_type``.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.utils import LayoutHints
+from lmcache.v1.multiprocess.custom_types import KVCache
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+
+logger = init_logger(__name__)
+
+# ``device_type -> BaseCacheContext`` subclass.  Populated lazily on
+# the first :func:`create_cache_context` call by scanning the
+# ``platform`` package for ``cache_context`` leaf modules at depth 2
+# (i.e. ``platform/<backend>/cache_context.py``).  Tests substitute
+# entries via :func:`snapshot_backends` / :func:`restore_backends`.
+#
+# The value type is the loose ``type`` (rather than
+# ``type[BaseCacheContext]``) so callers can instantiate it with the
+# concrete subclass' positional ``__init__`` signature without mypy
+# resolving the abstract-base ``__init__`` instead.
+_BACKENDS: dict[str, type] = {}
+_BACKENDS_DISCOVERED: bool = False
+
+
+def _discover_backends_once() -> None:
+    """Populate :data:`_BACKENDS` on first use.
+
+    Walks ``lmcache.v1.platform`` two levels deep (``platform`` ->
+    ``<backend>`` -> ``cache_context``) and indexes every concrete
+    :class:`BaseCacheContext` subclass by its ``device_type``
+    ClassVar.  Subclasses with an empty ``device_type`` are skipped
+    with a warning so a missing override surfaces loudly instead of
+    silently shadowing a real backend.
+    """
+    global _BACKENDS_DISCOVERED
+    if _BACKENDS_DISCOVERED:
+        return
+
+    # First Party
+    import lmcache.v1.platform as platform_pkg
+
+    for cls in discover_subclasses(
+        platform_pkg,
+        BaseCacheContext,  # type: ignore[type-abstract]
+        module_filter=lambda short_name: short_name == "cache_context",
+        levels=[2, 2],
+    ):
+        device_type = getattr(cls, "device_type", "")
+        if not device_type:
+            logger.warning(
+                "Skipping %s: empty device_type ClassVar; concrete "
+                "BaseCacheContext subclasses must override it.",
+                cls.__name__,
+            )
+            continue
+        existing = _BACKENDS.get(device_type)
+        if existing is not None and existing is not cls:
+            logger.warning(
+                "Multiple cache-context classes claim device_type=%r "
+                "(%s vs %s); keeping the first.",
+                device_type,
+                existing.__name__,
+                cls.__name__,
+            )
+            continue
+        _BACKENDS[device_type] = cls
+
+    _BACKENDS_DISCOVERED = True
+
+
+def _resolve_backend(device_type: str) -> type:
+    _discover_backends_once()
+    cls = _BACKENDS.get(device_type)
+    if cls is None:
+        raise ValueError(
+            "No cache-context class registered for device type %r. "
+            "Make sure ``lmcache.v1.platform.<backend>.cache_context`` "
+            "ships a BaseCacheContext subclass with the matching "
+            "``device_type`` ClassVar." % device_type
+        )
+    return cls
+
+
+def snapshot_backends() -> dict[str, type]:
+    """Return a shallow copy of the backend table.
+
+    Pair with :func:`restore_backends` in test fixtures so installing
+    fakes for one test does not leak into the next.
+    """
+    _discover_backends_once()
+    return dict(_BACKENDS)
+
+
+def restore_backends(state: dict[str, type]) -> None:
+    """Replace the backend table with *state*.
+
+    Marks the table as already-discovered so further calls do not
+    re-trigger filesystem scanning and overwrite the test's fakes.
+    """
+    global _BACKENDS_DISCOVERED
+    _BACKENDS.clear()
+    _BACKENDS.update(state)
+    _BACKENDS_DISCOVERED = True
+
+
+def _detect_device_type(kv_caches: KVCache) -> str:
+    """Return the ``torch.device.type`` describing *kv_caches*.
+
+    All wrappers in *kv_caches* must materialize tensors on the same
+    device type; mixed-device batches are not supported by any
+    downstream cache-context implementation.
+    """
+    device_types = {w.to_tensor().device.type for w in kv_caches}
+    if len(device_types) != 1:
+        raise ValueError(
+            "create_cache_context requires all kv_caches to share one "
+            "device type, got %r" % sorted(device_types)
+        )
+    return next(iter(device_types))
+
+
+def create_cache_context(
+    kv_caches: KVCache,
+    lmcache_tokens_per_chunk: int = 256,
+    layout_hints: LayoutHints | None = None,
+    engine_group_infos: "Sequence[EngineGroupInfo]" = (),
+    engine_type: EngineType = EngineType.VLLM,
+    separate_object_groups: bool = True,
+    full_sw_kv: bool = False,
+) -> BaseCacheContext:
+    """Create the appropriate cache context for *kv_caches*.
+
+    The signature mirrors :class:`GPUCacheContext` so callers can
+    forward their kwargs verbatim and stay agnostic of the active
+    backend.
+
+    Selection is driven by ``tensor.device.type`` of *kv_caches*:
+    on first use the platform package is scanned for
+    ``BaseCacheContext`` subclasses and the one whose
+    ``device_type`` ClassVar matches is instantiated.  ``"cuda"``,
+    ``"cpu"``, future ``"xpu"`` ... all resolve through the same
+    code path -- no ``isinstance`` / ``if-elif`` chain.
+
+    Args:
+        kv_caches: KV cache tensor wrappers from the serving engine.
+            Must be non-empty.
+        lmcache_tokens_per_chunk: Number of tokens per LMCache chunk.
+        layout_hints: Optional hints for KV format detection.
+            Forwarded verbatim to the concrete context constructor.
+        engine_group_infos: Engine-neutral KV cache group metadata.
+        engine_type: Which serving engine produced the caches.
+        separate_object_groups: When True (default), split kernel groups into
+            one object group per sliding-window size; when False, a single
+            full-attention object group.
+        full_sw_kv: When True, sliding-window groups store/transfer full
+            per-chunk KV (no sub-chunk window cutting) so chunks stay valid for
+            reuse at any position; see
+            :meth:`KVLayerGroupsManager.enable_full_sw_kv`.
+
+    Returns:
+        A concrete cache context instance.
+
+    Raises:
+        ValueError: If *kv_caches* is empty, mixes device types, or
+            targets a device type with no registered backend.
+    """
+    if not kv_caches:
+        raise ValueError("create_cache_context requires a non-empty kv_caches list")
+
+    device_type = _detect_device_type(kv_caches)
+    cls = _resolve_backend(device_type)
+    return cls(
+        kv_caches,
+        lmcache_tokens_per_chunk,
+        layout_hints,
+        engine_group_infos,
+        engine_type,
+        separate_object_groups,
+        full_sw_kv,
+    )
diff --git a/lmcache/v1/platform/cpu/__init__.py b/lmcache/v1/platform/cpu/__init__.py
new file mode 100644
index 0000000..d42b9e7
--- /dev/null
+++ b/lmcache/v1/platform/cpu/__init__.py
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CPU-specific platform primitives.
+
+:class:`~lmcache.v1.platform.cpu.shm.CpuShmTensorWrapper` carries a
+``device_type`` ClassVar and a ``wrap`` factory classmethod, which
+:func:`~lmcache.v1.platform._registry._discover_wrappers_once` picks
+up at run-time -- no static ``register_kv_wrapper`` needed.
+"""
diff --git a/lmcache/v1/platform/cpu/cache_context.py b/lmcache/v1/platform/cpu/cache_context.py
new file mode 100644
index 0000000..c41a304
--- /dev/null
+++ b/lmcache/v1/platform/cpu/cache_context.py
@@ -0,0 +1,439 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CPU-only cache context for platforms without CUDA GPUs.
+
+This module sits next to :mod:`lmcache.v1.platform.cuda.cache_context`
+under :mod:`lmcache.v1.platform` and provides the same public API as
+:class:`~lmcache.v1.platform.cuda.cache_context.GPUCacheContext` but
+keeps all tensors on CPU. Stream / Event objects are provided by
+:class:`~lmcache.v1.platform.cpu.stub_cpu_device.StubStream` so
+CPU-only hosts never import ``cupy`` or instantiate a real CUDA
+stream object.
+
+The platform-agnostic dispatcher ``create_cache_context`` lives in
+:mod:`lmcache.v1.platform.cache_context`.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.utils import (
+    LayoutHints,
+    get_group_data_ptrs,
+    normalize_and_discover_per_layer_formats,
+)
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+from lmcache.v1.multiprocess.custom_types import KVCache
+from lmcache.v1.multiprocess.group_view import engine_group_layer_indices
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+from lmcache.v1.platform.cpu.stub_cpu_device import StubStream
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+
+logger = init_logger(__name__)
+
+
+class CPUCacheContext(BaseCacheContext):
+    """CPU-only cache context with the same public API as
+    :class:`GPUCacheContext`.
+
+    All tensors live on CPU. CUDA streams and cupy streams are
+    replaced by :class:`StubStream` no-op objects so callers can keep
+    using ``stream.synchronize()`` / ``wait_event(...)`` etc. without
+    branching on the active backend.
+
+    KV cache tensors are reconstructed from the
+    :class:`CpuShmTensorWrapper` instances sent by the client over
+    POSIX shared memory -- the server does **not** allocate the KV
+    cache itself. This mirrors the GPU-mode CUDA-IPC flow where the
+    client owns the buffers and the server only maps them.
+    """
+
+    device_type = "cpu"
+
+    def __init__(
+        self,
+        kv_caches: KVCache,
+        lmcache_tokens_per_chunk: int = 256,
+        layout_hints: LayoutHints | None = None,
+        engine_group_infos: "Sequence[EngineGroupInfo]" = (),
+        engine_type: EngineType = EngineType.VLLM,
+        separate_object_groups: bool = True,
+        full_sw_kv: bool = False,
+    ) -> None:
+        if not kv_caches:
+            raise ValueError(
+                "CPUCacheContext requires a non-empty list of "
+                "CpuShmTensorWrapper; the legacy server-side "
+                "self-allocation path has been removed."
+            )
+
+        # First Party
+        from lmcache.v1.platform.cuda.cache_context import (
+            unwrap_kv_cache_tensors,
+        )
+
+        unwrapped = unwrap_kv_cache_tensors(kv_caches)
+        self.device_ = torch.device("cpu")
+
+        # Discover layout & build KV layer groups via the same path
+        # GPUCacheContext uses, so we don't need to hand-roll any
+        # PageBufferShapeDesc here. ``layout_hints`` / ``engine_type``
+        # are forwarded so the signature matches GPUCacheContext.
+        (
+            kv_caches_normalized,
+            engine_kv_formats,
+        ) = normalize_and_discover_per_layer_formats(
+            unwrapped,
+            engine_group_layer_indices(engine_group_infos),
+            engine_type,
+            layout_hints,
+        )
+        kv_caches_list: list[torch.Tensor] = list(kv_caches_normalized)
+        num_layers_val = len(engine_kv_formats)
+        kv_layer_groups_manager = KVLayerGroupsManager(
+            kv_caches_list,
+            engine_kv_formats=engine_kv_formats,
+            engine_group_infos=engine_group_infos,
+            lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+            separate_object_groups=separate_object_groups,
+        )
+        # Set full_sw_kv before the temp buffer / object groups are sized so
+        # both use the full (un-windowed) per-chunk geometry (mirrors
+        # GPUCacheContext).
+        if full_sw_kv:
+            kv_layer_groups_manager.enable_full_sw_kv()
+
+        # Pre-allocated block IDs buffer (CPU).
+        _MAX_BLOCK_IDS = 1_000_000
+        block_ids_buffer = torch.empty(_MAX_BLOCK_IDS, dtype=torch.long)
+
+        super().__init__(
+            kv_caches=kv_caches_list,
+            device=self.device_,
+            num_layers=num_layers_val,
+            kv_layer_groups_manager=kv_layer_groups_manager,
+            block_ids_buffer=block_ids_buffer,
+            lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+        )
+
+        # Per-group KV pointer tensors (CPU). Reuse the same helper
+        # GPUCacheContext relies on so the layout matches exactly.
+        self.group_kv_pointers_: list[torch.Tensor] = [
+            torch.tensor(
+                get_group_data_ptrs(
+                    self.kv_caches_,
+                    self.get_engine_kv_format(idx),
+                    group.layer_indices,
+                ),
+                dtype=torch.long,
+            )
+            for idx, group in enumerate(self.kv_layer_groups_manager_.kv_layer_groups)
+        ]
+
+        self.kv_cache_pointers_ = torch.tensor(
+            [t.data_ptr() for t in self.kv_caches_], dtype=torch.long
+        )
+
+        # Temporary buffer for transfers (same layout as
+        # GPUCacheContext but on CPU).
+        self._max_batch_size = 4
+        self.tmp_chunk_group_offsets_: list[int] = [0]
+        for group_idx, group in enumerate(
+            self.kv_layer_groups_manager_.kv_layer_groups
+        ):
+            shape = self.get_kv_buffer_shape(lmcache_tokens_per_chunk, group_idx)
+            byte_size = shape.numel() * group.dtype.itemsize
+            self.tmp_chunk_group_offsets_.append(
+                self.tmp_chunk_group_offsets_[-1] + byte_size
+            )
+        self.tmp_chunk_bytes_ = self.tmp_chunk_group_offsets_[-1]
+        # Buffer lives on CPU; keep the attribute name aligned with the
+        # context to avoid GPU-prefixed naming bleeding into a CPU-only
+        # class. The public ``get_tmp_gpu_buffer_flat`` method name is
+        # preserved so ``server.py`` can duck-type across backends.
+        self.tmp_cpu_buffer_ = torch.empty(
+            self.tmp_chunk_bytes_ * self.max_batch_size,
+            dtype=torch.uint8,
+        )
+
+        # Mock streams. ``StubStream`` already implements the small
+        # subset of the API server-side code uses (``synchronize``,
+        # ``wait_event``, ``record_event`` ...), so we never import
+        # cupy or instantiate a real CUDA stream object here.
+        self.cuda_stream_: StubStream = StubStream(device="cpu")
+        self.cupy_stream_: StubStream = self.cuda_stream_
+        self.high_priority_cuda_stream_: StubStream = StubStream(
+            device="cpu", priority=0
+        )
+        self.high_priority_cupy_stream_: StubStream = self.high_priority_cuda_stream_
+
+        # Sanity-check: warn if /dev/shm looks too small for the
+        # registered KV cache. Only meaningful on Linux where
+        # /dev/shm is the default tmpfs backing POSIX SHM.
+        self._check_shm_capacity()
+
+        logger.info(
+            "CPUCacheContext: %d layers, %d blocks, dtype=%s (shm-backed)",
+            self.num_layers_,
+            self.num_blocks,
+            self.kv_caches_[0].dtype,
+        )
+
+    # -- Internal helpers --
+
+    _SHM_PATH = "/dev/shm"
+
+    def _check_shm_capacity(self) -> None:
+        """Warn if /dev/shm free space is smaller than the KV cache."""
+        if not os.path.isdir(self._SHM_PATH):
+            return
+        try:
+            st = os.statvfs(self._SHM_PATH)
+        except OSError:
+            return
+        free_bytes = st.f_bavail * st.f_frsize
+        kv_bytes = sum(t.numel() * t.element_size() for t in self.kv_caches_)
+        if kv_bytes > free_bytes:
+            logger.warning(
+                "Insufficient /dev/shm space for CPU KV cache: "
+                "need %d bytes but only %d bytes available. "
+                "Consider increasing the size of /dev/shm "
+                "(e.g. mount -o remount,size=<N>G /dev/shm).",
+                kv_bytes,
+                free_bytes,
+            )
+
+    def close(self) -> None:
+        """Release resources. No-op for CPU context (no GDS staging buffer)."""
+        pass
+
+    # -- Properties (same API as GPUCacheContext) --
+
+    @property
+    def max_batch_size(self) -> int:
+        """Returns the maximum number of concurrent batches."""
+        return self._max_batch_size
+
+    @property
+    def kv_pointers(self) -> torch.Tensor:
+        """Returns a tensor of KV cache data pointers."""
+        return self.kv_cache_pointers_
+
+    @property
+    def stream(self) -> StubStream:
+        """Returns the (mock) CUDA stream."""
+        return self.cuda_stream_
+
+    @property
+    def cupy_stream(self) -> StubStream:
+        """Returns the (mock) external stream."""
+        return self.cupy_stream_
+
+    @property
+    def high_priority_stream(self) -> StubStream:
+        """Returns the (mock) high-priority CUDA stream."""
+        return self.high_priority_cuda_stream_
+
+    @property
+    def high_priority_cupy_stream(self) -> StubStream:
+        """Returns the (mock) high-priority external stream."""
+        return self.high_priority_cupy_stream_
+
+    @property
+    def block_size(self) -> int:
+        """Returns the block size (tokens per block)."""
+        return self.kv_layer_groups_manager_.kv_layer_groups[0].shape_desc.bs
+
+    @property
+    def group_slots_per_blocks(self) -> list[int]:
+        """Per-group physical slot count (``shape_desc.bs``) in group
+        order."""
+        return [
+            group.shape_desc.bs
+            for group in self.kv_layer_groups_manager_.kv_layer_groups
+        ]
+
+    def blocks_for_tokens(self, num_logical_tokens: int, group_idx: int) -> int:
+        """Number of blocks that span *num_logical_tokens* for a group.
+
+        Mirrors :meth:`GPUCacheContext.blocks_for_tokens`.
+        """
+        group = self.kv_layer_groups_manager_.kv_layer_groups[group_idx]
+        physical_slots = (
+            num_logical_tokens * group.slots_per_block // group.tokens_per_block
+        )
+        return physical_slots // group.shape_desc.bs
+
+    def get_group_kv_pointers(self, group_idx: int) -> torch.Tensor:
+        """Returns the KV cache pointer tensor for the given group."""
+        return self.group_kv_pointers_[group_idx]
+
+    def get_kernel_group_kv_pointers(self, kernel_group_idx: int) -> torch.Tensor:
+        """Returns the KV pointer tensor for the given kernel group.
+
+        Mirrors :meth:`GPUCacheContext.get_kernel_group_kv_pointers`.
+        """
+        return self.group_kv_pointers_[kernel_group_idx]
+
+    def get_kernel_group_shape_dtype(
+        self,
+        num_tokens: int,
+        kernel_group_idx: int,
+    ) -> tuple[torch.Size, torch.dtype]:
+        """Returns the shape and dtype for the given kernel group index and
+        number of tokens.
+
+        Mirrors :meth:`GPUCacheContext.get_kernel_group_shape_dtype` so
+        callers such as ``lmcache_driven_transfer.get_layout_desc`` can duck-type
+        across GPU and CPU backends.
+
+        Args:
+            num_tokens: Number of tokens.
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            A ``(shape, dtype)`` tuple for the given kernel group.
+        """
+        group = self.kv_layer_groups_manager_.kv_layer_groups[kernel_group_idx]
+        compress_ratio = group.tokens_per_block // group.slots_per_block
+        if num_tokens % compress_ratio != 0:
+            raise ValueError(
+                "num_tokens (%d) is not a multiple of compress_ratio (%d) "
+                "for kernel_group_idx %d"
+                % (num_tokens, compress_ratio, kernel_group_idx)
+            )
+        num_slots = num_tokens // compress_ratio
+        sd = group.shape_desc
+        shape = torch.Size(
+            (sd.kv_size, group.num_layers, num_slots, group.hidden_dim_size)
+        )
+        return shape, group.dtype
+
+    def get_tmp_gpu_buffer_flat(self, chunk_idx: int) -> torch.Tensor:
+        """Returns the flat uint8 temp buffer for the given chunk."""
+        if chunk_idx >= self.max_batch_size:
+            raise ValueError(
+                "chunk_idx %d >= max_batch_size %d" % (chunk_idx, self.max_batch_size)
+            )
+        start = chunk_idx * self.tmp_chunk_bytes_
+        return self.tmp_cpu_buffer_[start : start + self.tmp_chunk_bytes_]
+
+    def get_temp_kernel_group_buffer(
+        self, batch_idx: int, kernel_group_idx: int
+    ) -> torch.Tensor:
+        """Returns the typed temp buffer for the given batch and kernel group.
+
+        Mirrors :meth:`GPUCacheContext.get_temp_kernel_group_buffer`.
+
+        Args:
+            batch_idx: Batch slot index (0 <= batch_idx < max_batch_size).
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            A typed tensor view with the correct shape and dtype.
+        """
+        if batch_idx >= self.max_batch_size:
+            raise ValueError(
+                "batch_idx %d >= max_batch_size %d" % (batch_idx, self.max_batch_size)
+            )
+        group = self.kv_layer_groups_manager_.kv_layer_groups[kernel_group_idx]
+        shape = self.get_kv_buffer_shape(
+            self.lmcache_tokens_per_chunk, kernel_group_idx
+        )
+        g_start = self.tmp_chunk_group_offsets_[kernel_group_idx]
+        g_end = self.tmp_chunk_group_offsets_[kernel_group_idx + 1]
+        chunk = self.tmp_chunk_bytes_
+        return (
+            self.tmp_cpu_buffer_[
+                batch_idx * chunk + g_start : batch_idx * chunk + g_end
+            ]
+            .view(group.dtype)
+            .view(shape)
+        )
+
+    def get_temp_object_group_buffer(
+        self, batch_idx: int, object_group_idx: int
+    ) -> torch.Tensor:
+        """Returns the flat uint8 temp buffer for the given batch and object
+        group.
+
+        Mirrors :meth:`GPUCacheContext.get_temp_object_group_buffer`.
+
+        Args:
+            batch_idx: Batch slot index (0 <= batch_idx < max_batch_size).
+            object_group_idx: Index of the object group.
+
+        Returns:
+            A flat uint8 tensor view covering the object group's byte range.
+        """
+        if batch_idx >= self.max_batch_size:
+            raise ValueError(
+                "batch_idx %d >= max_batch_size %d" % (batch_idx, self.max_batch_size)
+            )
+        manager = self.kv_layer_groups_manager_
+        object_group = manager.object_groups[object_group_idx]
+        kg_indices = object_group.kernel_group_indices
+        # Object group spans from the first to the last kernel group's range.
+        g_start = self.tmp_chunk_group_offsets_[kg_indices[0]]
+        g_end = self.tmp_chunk_group_offsets_[kg_indices[-1] + 1]
+        chunk = self.tmp_chunk_bytes_
+        return self.tmp_cpu_buffer_[
+            batch_idx * chunk + g_start : batch_idx * chunk + g_end
+        ]
+
+    def get_tmp_chunk_gpu_buffer(self, group_idx: int = 0) -> torch.Tensor:
+        """Returns a typed view of the temp buffer for one chunk."""
+        group = self.kv_layer_groups_manager_.kv_layer_groups[group_idx]
+        shape = self.get_kv_buffer_shape(self.lmcache_tokens_per_chunk, group_idx)
+        start = self.tmp_chunk_group_offsets_[group_idx]
+        end = self.tmp_chunk_group_offsets_[group_idx + 1]
+        return self.tmp_cpu_buffer_[start:end].view(group.dtype).view(shape)
+
+    def get_tmp_chunk_gpu_buffer_batched(
+        self, batch_size: int, group_idx: int = 0
+    ) -> list[torch.Tensor]:
+        """Returns a list of non-overlapping temp buffer views."""
+        if batch_size > self.max_batch_size:
+            raise ValueError(
+                "batch_size %d > max_batch_size %d" % (batch_size, self.max_batch_size)
+            )
+        group = self.kv_layer_groups_manager_.kv_layer_groups[group_idx]
+        shape = self.get_kv_buffer_shape(self.lmcache_tokens_per_chunk, group_idx)
+        g_start = self.tmp_chunk_group_offsets_[group_idx]
+        g_end = self.tmp_chunk_group_offsets_[group_idx + 1]
+        chunk = self.tmp_chunk_bytes_
+        return [
+            self.tmp_cpu_buffer_[i * chunk + g_start : i * chunk + g_end]
+            .view(group.dtype)
+            .view(shape)
+            for i in range(batch_size)
+        ]
+
+    def cache_size_per_token(self) -> int:
+        """Returns cache size per *logical* token in bytes,
+        summed across all groups.
+
+        Mirrors :meth:`GPUCacheContext.cache_size_per_token`.
+        """
+        total = 0
+        for group_idx, group in enumerate(
+            self.kv_layer_groups_manager_.kv_layer_groups
+        ):
+            compress_ratio = group.tokens_per_block // group.slots_per_block
+            numels = self.get_kv_buffer_shape(compress_ratio, group_idx).numel()
+            slot_bytes = numels * group.dtype.itemsize
+            total += slot_bytes // compress_ratio
+        return total
diff --git a/lmcache/v1/platform/cpu/shm.py b/lmcache/v1/platform/cpu/shm.py
new file mode 100644
index 0000000..87dcec6
--- /dev/null
+++ b/lmcache/v1/platform/cpu/shm.py
@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CPU-only KV-cache IPC wrapper backed by POSIX shared memory.
+
+Mirrors the GPU-mode CUDA-IPC zero-copy semantics for hosts without an
+accelerator: client and LMCache mp server map the **same** physical
+pages so transfers are pointer-shuffles rather than memcpys.
+
+Self-registers a ``"cpu"`` factory with
+:mod:`lmcache.v1.platform._registry` at import time, so the
+multiprocess adapter can dispatch by ``tensor.device.type`` without
+any if/elif chain.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import ClassVar
+import ctypes
+import itertools
+import os
+import threading
+import weakref
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.multiprocess.posix_shm import (
+    shm_create_readwrite,
+    shm_map_readwrite,
+    shm_munmap,
+    shm_unlink,
+)
+from lmcache.v1.platform.base_ipc_wrapper import DeviceIPCWrapper
+
+logger = init_logger(__name__)
+
+# Re-export POSIX-SHM primitives so existing callers keep working.
+# The canonical home is :mod:`lmcache.v1.multiprocess.posix_shm`; new
+# code (e.g. the MP non-GPU SHM transport) should import from there.
+__all__ = [
+    "CpuShmTensorWrapper",
+    "inject_stale_cache_entry_for_test",
+    "migrate_to_shm_and_wrap",
+    "shm_create_readwrite",
+    "shm_map_readwrite",
+    "shm_munmap",
+    "shm_unlink",
+]
+
+# ---------------------------------------------------------------------------
+# Wrapper class                                                             #
+# ---------------------------------------------------------------------------
+
+
+class CpuShmTensorWrapper(DeviceIPCWrapper):
+    """IPC wrapper for CPU tensors backed by POSIX shared memory.
+
+    Used by the ``lmcache bench kvcache --mode cpu`` path and the
+    vLLM CPU integration so that the client and the LMCache mp server
+    map the **same** physical pages for the KV cache, mirroring the
+    GPU-mode CUDA-IPC zero-copy semantics.
+
+    Subclassing :class:`DeviceIPCWrapper` is load-bearing for the same
+    reason :class:`RawCudaIPCWrapper` does it: msgspec does not
+    support unions of custom ext-encoded types, so all wire-level
+    KV-cache wrappers must share the single ext code (1) registered
+    for ``DeviceIPCWrapper``. Pickle preserves the subclass identity
+    so ``to_tensor`` dispatches correctly on both sides.
+    """
+
+    #: ``torch.device.type`` this wrapper handles (used by auto-discovery
+    #: in :func:`~lmcache.v1.platform._registry._discover_wrappers_once`).
+    device_type: ClassVar[str] = "cpu"
+
+    #: Marked ``True`` so auto-discovery picks this as the default
+    #: factory for ``"cpu"``.
+    _is_default_wrapper: ClassVar[bool] = True
+
+    # POSIX shared-memory name (``/lmcache_...``) -- leading ``/`` is
+    # required by ``shm_open(3)`` on both Linux and macOS.
+    SHM_NAME_PREFIX = "/lmcache_kv_"
+
+    @classmethod
+    def wrap(cls, tensor: torch.Tensor) -> "CpuShmTensorWrapper":
+        """Factory used by
+        :func:`~lmcache.v1.platform._registry._discover_wrappers_once`.
+
+        Delegates to :func:`migrate_to_shm_and_wrap`, which migrates the
+        tensor's storage to a POSIX SHM segment so the LMCache mp server
+        can map the same physical pages.
+
+        Args:
+            tensor: A contiguous CPU tensor to migrate and wrap.
+
+        Returns:
+            A new :class:`CpuShmTensorWrapper` referencing the SHM
+            segment that now backs ``tensor``.
+        """
+        return migrate_to_shm_and_wrap(tensor)
+
+    def __init__(self, tensor: torch.Tensor, shm_name: str) -> None:
+        if tensor.device.type != "cpu":
+            raise ValueError(
+                "CpuShmTensorWrapper requires a CPU tensor, got %s" % tensor.device
+            )
+        if not tensor.is_contiguous():
+            raise ValueError("CpuShmTensorWrapper requires a contiguous tensor")
+
+        self.shm_name = shm_name
+        # ``numel * element_size`` is the correct logical byte size; the
+        # underlying storage may be larger when the tensor is a view.
+        self.nbytes = tensor.numel() * tensor.element_size()
+
+        # DeviceIPCWrapper interface fields. ``handle`` / ``device_uuid``
+        # are unused on the CPU path but kept to satisfy the base
+        # contract used by equality checks.
+        self.handle = None
+        self.dtype = tensor.dtype
+        self.shape = tuple(tensor.shape)
+        self.stride = tuple(tensor.stride())
+        self.storage_offset = int(tensor.storage_offset())
+        self.device_uuid = "cpu"
+
+    def to_tensor(self) -> torch.Tensor:
+        """Reconstruct the tensor by mapping the same SHM segment.
+
+        The returned tensor owns the mmap: a ``weakref.finalize`` hook
+        runs ``munmap`` once the tensor (and any views derived from it)
+        is garbage-collected, so the per-process virtual address space
+        does not leak across repeated ``to_tensor`` calls.
+
+        We rebuild the view through ``as_strided`` so the original
+        memory layout (stride / storage_offset / memory_format) is
+        replayed faithfully on the receiving side; reshape would
+        silently re-coalesce strides and lose, e.g., channels_last.
+        """
+        # Empty tensors carry no SHM segment (mmap with length 0 is
+        # undefined / EINVAL on POSIX); rebuild the empty view in-process.
+        if self.nbytes == 0:
+            return torch.empty(self.shape, dtype=self.dtype)
+        addr = shm_map_readwrite(self.shm_name, self.nbytes)
+        # ``torch.frombuffer`` requires a writable buffer; build one
+        # via ctypes so the resulting torch tensor shares storage
+        # with the SHM mapping (zero copy across processes).
+        buf_type = ctypes.c_uint8 * self.nbytes
+        buf = buf_type.from_address(addr)
+        flat = torch.frombuffer(buf, dtype=torch.uint8)
+        typed = flat.view(self.dtype)
+        out = torch.as_strided(typed, self.shape, self.stride, self.storage_offset)
+        # Pin the mmap to the *storage*, not the outer tensor: views
+        # (reshape / slicing) create new tensor objects that share the
+        # storage but do not inherit Python attributes, so a finalizer
+        # attached to ``out`` would munmap as soon as ``out`` is GC'd
+        # even when a view is still reading the SHM segment.
+        # ``UntypedStorage`` is shared across views, so finalizing on it
+        # only fires once every view is also dropped.
+        storage = out.untyped_storage()
+        _CPU_SHM_KEEP_ALIVE[id(storage)] = flat
+        weakref.finalize(storage, _release_shm_segment, id(storage), addr, self.nbytes)
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Migrate-and-wrap factory (used by the multiprocess adapter)              #
+# ---------------------------------------------------------------------------
+
+# Per-process registry of SHM segments we have created, so the same
+# tensor object is only migrated to SHM once even if the factory is
+# called multiple times.
+#
+# Keyed by ``id(tensor)`` for cheap O(1) lookup, but each entry also
+# holds a ``weakref.ref`` to the original tensor and we *verify the
+# referent is still that exact object* before reusing the cached SHM
+# name. CPython recycles object IDs, so a fresh tensor allocated at
+# the same address as a previously migrated (now garbage-collected)
+# one would otherwise inherit a stale name -- and because
+# :func:`shm_create_readwrite` uses ``O_EXCL``, the next migration
+# would crash with ``EEXIST`` ("File exists"). The weakref-validated
+# lookup below makes that race impossible: a stale entry can only
+# point at a dead referent, which we treat as a miss.
+_CPU_SHM_NAMES: dict[int, tuple["weakref.ReferenceType[torch.Tensor]", str]] = {}
+_CPU_SHM_LOCK = threading.Lock()
+_CPU_SHM_COUNTER = itertools.count()
+
+
+# Process-level registry that pins the base ``flat`` buffer of every live
+# ``to_tensor()`` mmap until its storage is finalized. Keyed by ``id(storage)``,
+# which is stable across views because PyTorch caches the storage Python
+# wrapper (so reshape / slicing returns the same ``UntypedStorage`` object).
+_CPU_SHM_KEEP_ALIVE: dict[int, torch.Tensor] = {}
+
+
+def _release_shm_segment(storage_id: int, addr: int, nbytes: int) -> None:
+    """Drop the pinned base buffer and ``munmap`` the mapping.
+
+    Invoked by ``weakref.finalize`` on the tensor's ``UntypedStorage`` once
+    every view of the mapping is gone, so views (e.g. ``reshape`` returning
+    a new tensor without ``_lmcache_shm_buf``) cannot trigger a premature
+    unmap that would turn into a use-after-free in the next read.
+    """
+    _CPU_SHM_KEEP_ALIVE.pop(storage_id, None)
+    shm_munmap(addr, nbytes)
+
+
+def _cleanup_shm_segment(tid: int, shm_name: str, addr: int, nbytes: int) -> None:
+    """Release the mmap, unlink, and forget the cached SHM name."""
+    with _CPU_SHM_LOCK:
+        # Only drop the entry if it still points at *this* segment;
+        # a future tensor reusing ``tid`` may already have replaced it.
+        cached = _CPU_SHM_NAMES.get(tid)
+        if cached is not None and cached[1] == shm_name:
+            _CPU_SHM_NAMES.pop(tid, None)
+    shm_munmap(addr, nbytes)
+    shm_unlink(shm_name)
+
+
+def migrate_to_shm_and_wrap(tensor: torch.Tensor) -> CpuShmTensorWrapper:
+    """Re-point ``tensor``'s storage at a POSIX SHM segment, then wrap.
+
+    Used as the registered ``"cpu"`` KV-wrapper factory: the LMCache mp
+    server can mmap the same physical pages on the receiving side.
+    Idempotent per tensor identity (validated via a stored weakref so
+    Python's id-recycling cannot produce a stale-name hit). The SHM
+    segment is released (``munmap`` + ``shm_unlink``) automatically
+    when the migrated tensor is garbage-collected.
+    """
+    # First Party
+    from lmcache.v1.gpu_connector.kv_format.contiguity import (
+        attempt_permute_to_contiguous_view,
+    )
+
+    # Validate and normalise the tensor *before* touching the registry
+    # or mutating storage, so a bad input never leaves things half-done.
+    tensor = attempt_permute_to_contiguous_view(tensor)
+    if tensor.device.type != "cpu":
+        raise ValueError(
+            "migrate_to_shm_and_wrap requires a CPU tensor, got %s" % tensor.device
+        )
+    if not tensor.is_contiguous():
+        raise ValueError("migrate_to_shm_and_wrap requires a contiguous tensor")
+
+    tid = id(tensor)
+
+    # Fast path: check the registry under the lock, return early if the
+    # tensor has already been migrated.
+    with _CPU_SHM_LOCK:
+        cached = _CPU_SHM_NAMES.get(tid)
+        if cached is not None:
+            ref, cached_name = cached
+            if ref() is tensor:
+                return CpuShmTensorWrapper(tensor, cached_name)
+            # Stale entry from a GC'd tensor whose id has been
+            # reused; drop it and fall through to allocate fresh.
+        _CPU_SHM_NAMES.pop(tid, None)
+
+    nbytes = tensor.numel() * tensor.element_size()
+    assert tensor.storage_offset() == 0, (
+        "migrate_to_shm_and_wrap: SHM segment is sized to "
+        "numel*elem_size; a nonzero storage_offset would cause "
+        "OOB access. Got offset=%d" % tensor.storage_offset()
+    )
+    if nbytes == 0:
+        # No SHM segment for empty tensors: ``mmap`` with length 0
+        # is undefined / EINVAL on POSIX. ``to_tensor`` rebuilds an
+        # empty view directly when ``shm_name`` is empty.
+        return CpuShmTensorWrapper(tensor, "")
+
+    shm_name = "%s%d_%d" % (
+        CpuShmTensorWrapper.SHM_NAME_PREFIX,
+        os.getpid(),
+        next(_CPU_SHM_COUNTER),
+    )
+    # Perform the heavy work (syscall + tensor mutation) outside the lock
+    # to keep the critical section small.
+    addr = shm_create_readwrite(shm_name, nbytes)
+    try:
+        buf_type = ctypes.c_uint8 * nbytes
+        buf = buf_type.from_address(addr)
+        shm_storage = torch.frombuffer(buf, dtype=torch.uint8).untyped_storage()
+        tensor.set_(
+            shm_storage,
+            tensor.storage_offset(),
+            tensor.shape,
+            tensor.stride(),
+        )
+    except Exception:
+        # Make sure the SHM resources don't leak if migration fails
+        # part-way (e.g. ``set_`` rejects an unusual stride).
+        shm_munmap(addr, nbytes)
+        shm_unlink(shm_name)
+        raise
+
+    with _CPU_SHM_LOCK:
+        _CPU_SHM_NAMES[tid] = (weakref.ref(tensor), shm_name)
+    weakref.finalize(tensor, _cleanup_shm_segment, tid, shm_name, addr, nbytes)
+    logger.info(
+        "Migrated CPU KV cache tensor (nbytes=%d) to SHM %s",
+        nbytes,
+        shm_name,
+    )
+    return CpuShmTensorWrapper(tensor, shm_name)
+
+
+def inject_stale_cache_entry_for_test(
+    tensor: torch.Tensor,
+    dead_ref: "weakref.ReferenceType[torch.Tensor]",
+    stale_shm_name: str,
+) -> None:
+    """Test-only hook: pre-seed the registry with a stale entry.
+
+    Lets unit tests reproduce the CPython id-reuse race -- where a
+    fresh tensor lands on the same id as a previously migrated and
+    garbage-collected one -- without the per-test global-state
+    surgery that would otherwise have to reach into the module's
+    private dict / lock.
+    """
+    with _CPU_SHM_LOCK:
+        _CPU_SHM_NAMES[id(tensor)] = (dead_ref, stale_shm_name)
diff --git a/lmcache/v1/platform/cpu/stub_cpu_device.py b/lmcache/v1/platform/cpu/stub_cpu_device.py
new file mode 100644
index 0000000..8c5e6ea
--- /dev/null
+++ b/lmcache/v1/platform/cpu/stub_cpu_device.py
@@ -0,0 +1,338 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from contextlib import nullcontext
+from typing import Any
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class StubDeviceProperties:
+    """Stub for torch_dev.get_device_properties() return value."""
+
+    def __init__(self) -> None:
+        self.name = "StubCPU"
+        self.major = 0
+        self.minor = 0
+        self.total_memory = 0
+        self.multi_processor_count = 0
+        self.uuid = "stub-0000-0000-0000-000000000000"
+
+    def __repr__(self) -> str:
+        return f"StubDeviceProperties(name={self.name!r})"
+
+
+class StubEvent:
+    """Stub for a CUDA event, used in CPU-only test environments."""
+
+    def __init__(
+        self,
+        enable_timing: bool = False,
+        blocking: bool = False,
+        interprocess: bool = False,
+    ) -> None:
+        self.enable_timing = enable_timing
+        self.blocking = blocking
+        self.interprocess = interprocess
+        self._recorded = False
+        self._handle = b"stub_ipc_handle"
+
+    def record(self, stream: Any = None) -> None:
+        """Mark this event as recorded on the given stream.
+
+        Args:
+            stream: The stream to record on. If None, uses the
+                current stream.
+        """
+        self._recorded = True
+
+    def wait(self, stream: Any = None) -> None:
+        """Make the given stream wait until this event completes.
+
+        Args:
+            stream: The stream that should wait. If None, uses the
+                current stream.
+        """
+        return None
+
+    def query(self) -> bool:
+        """Check whether the event has completed.
+
+        Returns:
+            True always, since the stub has no real work.
+        """
+        return True
+
+    def synchronize(self) -> None:
+        """Block the host until this event completes.
+
+        No-op in the stub implementation.
+        """
+        return None
+
+    def elapsed_time(self, end_event: "StubEvent") -> float:
+        """Return elapsed time in milliseconds between this event and *end_event*.
+
+        Args:
+            end_event: The ending event to measure against.
+
+        Returns:
+            Elapsed time in milliseconds. Always 0.0 for the stub.
+        """
+        return 0.0
+
+    def ipc_handle(self) -> bytes:
+        """Return an IPC handle for cross-process sharing.
+
+        Returns:
+            A bytes object representing the IPC handle.
+        """
+        return self._handle
+
+    @classmethod
+    def from_ipc_handle(cls, device: Any, handle: bytes) -> "StubEvent":
+        """Reconstruct a StubEvent from an IPC handle.
+
+        Args:
+            device: The device to associate with the event.
+            handle: The IPC handle bytes obtained from
+                :meth:`ipc_handle`.
+
+        Returns:
+            A new StubEvent with interprocess=True and the given handle.
+        """
+        ev = cls(interprocess=True)
+        ev._handle = handle
+        return ev
+
+    def __repr__(self) -> str:
+        return f"StubEvent(interprocess={self.interprocess}, recorded={self._recorded})"
+
+
+class StubStream:
+    """Stub for a CUDA stream, used in CPU-only test environments."""
+
+    def __init__(self, device: Any = "cpu", priority: int = 0, **kwargs: Any) -> None:
+        self.device = device
+        self.priority = priority
+        self.cuda_stream = 0
+        # Mirrors the ``ptr`` attribute exposed by ``cupy.cuda.Stream``
+        # so callers (e.g. ``mp_observability.event_bus``) that pass a
+        # raw stream pointer to native recorders accept this stub
+        # without an isinstance check.
+        self.ptr = 0
+
+    def launch_host_func(self, callback: Any, arg: Any = None) -> None:
+        """Run ``callback(arg)`` synchronously.
+
+        ``cupy.cuda.Stream.launch_host_func`` schedules the callback
+        on the GPU stream's host-side completion queue; with no real
+        stream there's nothing to wait for, so we just invoke it
+        immediately. Exceptions are swallowed to mirror the cupy
+        contract (callbacks are best-effort and must not propagate).
+        """
+        try:
+            callback(arg)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("launch_host_func callback raised: %s", e)
+
+    def synchronize(self) -> None:
+        """Block the host until all kernels on this stream complete.
+
+        No-op in the stub implementation.
+        """
+        return None
+
+    def wait_event(self, event: StubEvent) -> None:
+        """Make this stream wait until *event* completes.
+
+        Args:
+            event: The event this stream should wait for.
+        """
+        return None
+
+    def wait_stream(self, stream: "StubStream") -> None:
+        """Make this stream wait until all kernels on *stream* complete.
+
+        Args:
+            stream: The stream whose pending work must finish before
+                this stream continues.
+        """
+        return None
+
+    def record_event(self, event: StubEvent | None = None) -> StubEvent:
+        """Record an event on this stream and return it.
+
+        Args:
+            event: An existing event to record. If None, a new
+                StubEvent is created.
+
+        Returns:
+            The recorded StubEvent.
+        """
+        event = event or StubEvent()
+        event.record(self)
+        return event
+
+    def query(self) -> bool:
+        """Check whether all kernels on this stream have completed.
+
+        Returns:
+            True always, since the stub has no real work.
+        """
+        return True
+
+    @staticmethod
+    def priority_range() -> tuple[int, int]:
+        """Return the range of stream priorities.
+
+        Returns:
+            A tuple of (lowest_priority, highest_priority). Always
+            (0, 0) for the stub.
+        """
+        return (0, 0)
+
+    def __repr__(self) -> str:
+        return f"StubStream(device={self.device}, priority={self.priority})"
+
+
+class StubCPUDevice:
+    """Stub stand-in for torch_dev in CPU-only test environments."""
+
+    def __init__(self, device_type: str = "cpu") -> None:
+        self._device_type = device_type
+        self._stream = StubStream(device=device_type)
+
+        self.Event = StubEvent
+        self.Stream = StubStream
+
+    def is_available(self) -> bool:
+        """Check whether the device backend is available.
+
+        Returns:
+            False always, since this is a CPU-only stub.
+        """
+        return False
+
+    def init(self) -> None:
+        """Initialize the device backend.
+
+        No-op in the stub implementation.
+        """
+        return None
+
+    def device(self, device: Any = None) -> Any:
+        """Return a context manager that sets the current device.
+
+        Args:
+            device: The device to select. Ignored in the stub.
+
+        Returns:
+            A no-op context manager.
+        """
+        return nullcontext()
+
+    def current_stream(self, device: Any = None) -> StubStream:
+        """Return the current stream for the given device.
+
+        Args:
+            device: The device to query. Ignored in the stub.
+
+        Returns:
+            The current StubStream.
+        """
+        return self._stream
+
+    def default_stream(self, device: Any = None) -> StubStream:
+        """Return the default stream for the given device.
+
+        Args:
+            device: The device to query. Ignored in the stub.
+
+        Returns:
+            The default StubStream.
+        """
+        return self._stream
+
+    def stream(self, stream: StubStream | None = None) -> Any:
+        """Return a context manager that sets the active stream.
+
+        Args:
+            stream: The stream to activate. If None, uses the
+                current stream.
+
+        Returns:
+            A context manager yielding the active StubStream.
+        """
+        return nullcontext(stream or self._stream)
+
+    def synchronize(self, device: Any = None) -> None:
+        """Wait for all streams on the given device to complete.
+
+        Args:
+            device: The device to synchronize. Ignored in the stub.
+        """
+        return None
+
+    def set_stream(self, stream: StubStream) -> None:
+        """Set the current stream.
+
+        Args:
+            stream: The stream to make current.
+        """
+        self._stream = stream
+
+    def device_count(self) -> int:
+        """Return the number of available devices.
+
+        Returns:
+            1 always for the stub.
+        """
+        return 1
+
+    def current_device(self) -> int:
+        """Return the index of the currently selected device.
+
+        Returns:
+            0 always for the stub.
+        """
+        return 0
+
+    def set_device(self, device: Any) -> None:
+        """Select the given device.
+
+        Args:
+            device: The device index or identifier to select.
+                Ignored in the stub.
+        """
+        return None
+
+    def get_device_properties(self, device: Any = 0) -> StubDeviceProperties:
+        """Return device properties for the given device.
+
+        Args:
+            device: The device index or identifier to query.
+                Ignored in the stub.
+
+        Returns:
+            A StubDeviceProperties instance with default values.
+        """
+        return StubDeviceProperties()
+
+    def empty_cache(self) -> None:
+        """Release all unoccupied cached memory.
+
+        No-op in the stub implementation.
+        """
+        return None
+
+    def __getattr__(self, name: str) -> Any:
+        raise AttributeError(f"StubCPUDevice does not implement '{name}'")
+
+    def __repr__(self) -> str:
+        return f"StubCPUDevice(device_type={self._device_type})"
diff --git a/lmcache/v1/platform/cuda/__init__.py b/lmcache/v1/platform/cuda/__init__.py
new file mode 100644
index 0000000..0f13f04
--- /dev/null
+++ b/lmcache/v1/platform/cuda/__init__.py
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CUDA-specific platform primitives."""
+
+# First Party
+from lmcache.v1.platform.base_device_spec import DeviceSpec
+from lmcache.v1.platform.base_pin_memory import PinMemoryBackend
+from lmcache.v1.platform.cuda.pin_memory import CudaPinMemoryBackend
+
+# ---------------------------------------------------------------------------
+# Device detection registry entry
+# ---------------------------------------------------------------------------
+
+
+class CudaDeviceSpec(DeviceSpec):
+    """CUDA device specification for the detection registry."""
+
+    @property
+    def device_type(self) -> str:
+        return "cuda"
+
+    @property
+    def torch_module_name(self) -> str:
+        return "cuda"
+
+    @property
+    def ops_module(self) -> str | None:
+        return "lmcache.c_ops"
+
+    @property
+    def pin_memory_backend(self) -> type[PinMemoryBackend] | None:
+        return CudaPinMemoryBackend
+
+    def is_available(self) -> bool:
+        """Check CUDA availability without importing lmcache.__init__."""
+        try:
+            # Third Party
+            import torch
+
+            return torch.cuda.is_available()
+        except Exception:
+            return False
diff --git a/lmcache/v1/platform/cuda/cache_context.py b/lmcache/v1/platform/cuda/cache_context.py
new file mode 100644
index 0000000..b552bec
--- /dev/null
+++ b/lmcache/v1/platform/cuda/cache_context.py
@@ -0,0 +1,628 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+GPU Cache Context management for LMCache multiprocessing.
+
+This module provides GPU-side KV cache management functionality, including:
+- GPUCacheContext: Manages shape and pointers to vLLM GPU KV cache tensors
+- Helper functions for tensor operations and key resolution
+"""
+
+# Standard
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+import array
+
+# Third Party
+import torch
+
+if TYPE_CHECKING:
+    # Third Party
+    import cupy
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.gds_context import get_gds_context
+from lmcache.v1.gpu_connector.utils import (
+    LayoutHints,
+    get_device,
+    get_group_data_ptrs,
+    normalize_and_discover_per_layer_formats,
+)
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+from lmcache.v1.multiprocess.custom_types import KVCache
+from lmcache.v1.multiprocess.group_view import (
+    EngineGroupInfo,
+    engine_group_layer_indices,
+)
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+
+logger = init_logger(__name__)
+
+
+def unwrap_kv_cache_tensors(kv_caches: KVCache) -> list[torch.Tensor]:
+    unwrapped_tensors = []
+    for ipc_wrapper in kv_caches:
+        tensor = ipc_wrapper.to_tensor()
+        unwrapped_tensors.append(tensor)
+    return unwrapped_tensors
+
+
+def list_to_gpu_tensor(lis: list[int], device: torch.device) -> torch.Tensor:
+    return torch.frombuffer(array.array("q", lis), dtype=torch.long).to(
+        device, non_blocking=True
+    )
+
+
+class _TempGPUBuffer:
+    """
+    Manages the temporary GPU buffer for GPUCacheContext
+
+    The logical layout of the temp GPU buffer is (batch size,
+    object group, kernel group).
+
+    Here is an example of batch size = 4, with 2 object groups,
+    and 2 kernel groups per object group:
+    [
+        batch 0:
+            - object group 0: kernel group 0 | kernel group 1 | ...
+            - object group 1: kernel group 2 | kernel group 3 | ...
+
+        batch 1:
+            - object group 0: kernel group 0 | kernel group 1 | ...
+            - object group 1: kernel group 2 | kernel group 3 | ...
+
+        batch 2:
+            - object group 0: kernel group 0 | kernel group 1 | ...
+            - object group 1: kernel group 2 | kernel group 3 | ...
+
+        batch 3:
+            - object group 0: kernel group 0 | kernel group 1 | ...
+            - object group 1: kernel group 2 | kernel group 3 | ...
+    ]
+
+    During the multi-layer copy kernel launch, we will do it at kernel
+    group level, which means we will have:
+    ```
+    gpu_buffers = [
+        get_temp_kernel_group_buffer(batch_idx, kernel_group_idx)
+        for batch_idx in range(batch_size)
+    ]
+    ```
+
+    During the lmcache_memcpy_async launch, we will do it at the object group
+    level, which will be:
+    ```
+    for i in range(batch_size):
+        gpu_buffer = get_temp_object_group_buffer(batch_idx, object_group_idx)
+        lmcache_memcpy_async(...)
+    ```
+    """
+
+    def __init__(
+        self,
+        kv_layer_groups_manager: KVLayerGroupsManager,
+        lmcache_tokens_per_chunk: int,
+        device: torch.device,
+        max_batch_size: int = 4,
+    ) -> None:
+        self._kv_groups_manager = kv_layer_groups_manager
+        self._lmcache_tokens_per_chunk = lmcache_tokens_per_chunk
+        self._max_batch_size = max_batch_size
+
+        self._temp_buffer = torch.empty(
+            self._get_size_for_single_batch() * max_batch_size,
+            dtype=torch.uint8,
+            device=device,
+        )
+
+        # Offset map: (batch_idx, object_group_idx, kernel_group_idx) ->
+        # (byte offset in the temp buffer, size of the buffer in bytes)
+        self._offset_map: dict[tuple[int, int, int], tuple[int, int]] = {}
+
+        # (batch_idx, kernel_group_idx) -> (byte offset for the kernel group,
+        # size of the buffer in bytes).
+        self._offset_map_kernel_group_only: dict[tuple[int, int], tuple[int, int]] = {}
+
+        # (batch_idx, object_group_idx) -> (byte offset for the object group,
+        # size of the buffer in bytes)
+        self._offset_map_object_group_only: dict[tuple[int, int], tuple[int, int]] = {}
+
+        offset = 0
+        for batch_idx in range(max_batch_size):
+            for object_group_idx in range(self._kv_groups_manager.num_object_groups):
+                object_group_size = 0
+                object_group_start_offset = offset
+
+                for kernel_group_idx in self._kv_groups_manager.object_groups[
+                    object_group_idx
+                ].kernel_group_indices:
+                    key = (batch_idx, object_group_idx, kernel_group_idx)
+                    key2 = (batch_idx, kernel_group_idx)
+
+                    size = self._get_size_for_kernel_group(kernel_group_idx)
+                    self._offset_map[key] = (offset, size)
+                    self._offset_map_kernel_group_only[key2] = (offset, size)
+
+                    offset += size
+                    object_group_size += size
+
+                key3 = (batch_idx, object_group_idx)
+                self._offset_map_object_group_only[key3] = (
+                    object_group_start_offset,
+                    object_group_size,
+                )
+
+        # Shape/dtype cache for kernel groups
+        self._shape_cache_kernel_group: dict[int, tuple[torch.Size, torch.dtype]] = {}
+        for kernel_group_idx in range(self._kv_groups_manager.num_kernel_groups):
+            shape = self._get_shape_for_kernel_group(
+                self._lmcache_tokens_per_chunk, kernel_group_idx
+            )
+            group = self._kv_groups_manager.kernel_groups[kernel_group_idx]
+            dtype = group.dtype
+            self._shape_cache_kernel_group[kernel_group_idx] = (shape, dtype)
+
+    # Public APIs
+    @property
+    def max_batch_size(self) -> int:
+        """Maximum number of chunks (batch slots) the buffer holds."""
+        return self._max_batch_size
+
+    @property
+    def buffer(self) -> torch.Tensor:
+        """The flat staging tensor (for GDS cuFile registration)."""
+        return self._temp_buffer
+
+    def get_temp_kernel_group_buffer(
+        self, batch_idx: int, kernel_group_idx: int
+    ) -> torch.Tensor:
+        """
+        Returns the temp GPU buffer for the given batch index and kernel group index.
+        The returned buffer is with the correct shape and dtype for the kernel group.
+
+        Args:
+            batch_idx: Index of the batch (0 <= batch_idx < max_batch_size)
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            The temp GPU buffer for the given batch index and kernel group index.
+
+        Raises:
+            ValueError: If the batch_idx or kernel_group_idx is out of range.
+        """
+        key = (batch_idx, kernel_group_idx)
+        if key not in self._offset_map_kernel_group_only:
+            raise ValueError(
+                f"Invalid batch_idx {batch_idx} or kernel_group_idx {kernel_group_idx}"
+            )
+
+        offset, size = self._offset_map_kernel_group_only[key]
+        shape, dtype = self._shape_cache_kernel_group[kernel_group_idx]
+        return self._temp_buffer[offset : offset + size].view(dtype).view(shape)
+
+    def get_temp_object_group_buffer(
+        self, batch_idx: int, object_group_idx: int
+    ) -> torch.Tensor:
+        """
+        Returns the temp GPU buffer for the given batch index and object group index
+        The returned buffer is a flat uint8 raw tensor.
+
+        Args:
+            batch_idx: Index of the batch (0 <= batch_idx < max_batch_size)
+            object_group_idx: Index of the object group.
+
+        Returns:
+            The temp GPU buffer for the given batch index and object group index.
+        """
+        key = (batch_idx, object_group_idx)
+        if key not in self._offset_map_object_group_only:
+            raise ValueError(
+                f"Invalid batch_idx {batch_idx} or object_group_idx {object_group_idx}"
+            )
+
+        offset, size = self._offset_map_object_group_only[key]
+        return self._temp_buffer[offset : offset + size]
+
+    def get_kernel_group_shape_dtype(
+        self,
+        num_tokens: int,
+        kernel_group_idx: int,
+    ) -> tuple[torch.Size, torch.dtype]:
+        """
+        Returns the shape and dtype for the given kernel group index and
+        number of tokens.
+
+        Will be exported by GPUCacheContext and used to construct the
+        MemoryLayoutDesc
+
+        Args:
+            num_tokens: Number of tokens. Must be a whole number of lmcache
+                chunk size.
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            The shape and dtype for the given kernel group index and
+            number of tokens.
+        """
+        _, dtype = self._shape_cache_kernel_group[kernel_group_idx]
+        shape = self._get_shape_for_kernel_group(num_tokens, kernel_group_idx)
+
+        return shape, dtype
+
+    def get_cache_size_per_token(self) -> int:
+        """
+        Returns the cache size per token (in bytes), summed across all kernel groups.
+        """
+        return self._get_size_for_single_batch() // self._lmcache_tokens_per_chunk
+
+    # Helper functions
+    def _get_shape_for_kernel_group(
+        self,
+        num_tokens: int,
+        kernel_group_idx: int,
+    ) -> torch.Size:
+        """
+        Returns the shape of the temp GPU buffer for the given kernel group index
+
+        Args:
+            num_tokens: Number of tokens
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            The shape of the temp GPU buffer for the given kernel group index.
+
+        Raises:
+            ValueError: If ``num_tokens`` is not a whole number of LMCache
+                chunks.
+        """
+        if num_tokens % self._lmcache_tokens_per_chunk != 0:
+            raise ValueError(
+                f"num_tokens ({num_tokens}) must be a multiple of "
+                f"lmcache_tokens_per_chunk ({self._lmcache_tokens_per_chunk})"
+            )
+
+        group = self._kv_groups_manager.kernel_groups[kernel_group_idx]
+        sd = group.shape_desc
+
+        num_chunks = num_tokens // self._lmcache_tokens_per_chunk
+        num_slots = (
+            self._kv_groups_manager.get_slots_per_chunk_in_sw(kernel_group_idx)
+            * num_chunks
+        )
+
+        return torch.Size(
+            (sd.kv_size, group.num_layers, num_slots, group.hidden_dim_size)
+        )
+
+    def _get_size_for_kernel_group(self, kernel_group_idx: int) -> int:
+        """
+        Returns the size in bytes of the temp GPU buffer for the given kernel group
+        index
+
+        **Assumes the size is lmcache_tokens_per_chunk
+
+        Will only be called during initialization
+        """
+        shape = self._get_shape_for_kernel_group(
+            self._lmcache_tokens_per_chunk, kernel_group_idx
+        )
+        kernel_group = self._kv_groups_manager.kernel_groups[kernel_group_idx]
+        dtype = kernel_group.dtype
+        return shape.numel() * dtype.itemsize
+
+    def _get_size_for_object_group(self, object_group_idx: int) -> int:
+        """
+        Returns the size in bytes of the temp GPU buffer for the given object group
+
+        **Assumes the size is lmcache_tokens_per_chunk
+
+        Will only be called during initialization
+        """
+        object_group = self._kv_groups_manager.object_groups[object_group_idx]
+        return sum(
+            self._get_size_for_kernel_group(kernel_group_idx)
+            for kernel_group_idx in object_group.kernel_group_indices
+        )
+
+    def _get_size_for_single_batch(self) -> int:
+        """
+        Returns the size in bytes of the temp GPU buffer for a single batch
+        (i.e., a single chunk)
+
+        **Assumes the size is lmcache_tokens_per_chunk
+        """
+        return sum(
+            self._get_size_for_object_group(object_group_idx)
+            for object_group_idx in range(self._kv_groups_manager.num_object_groups)
+        )
+
+
+class GPUCacheContext(BaseCacheContext):
+    """
+    Manages the shape and pointers to vLLM GPU KV cache tensors.
+    """
+
+    device_type = "cuda"
+
+    def __init__(
+        self,
+        kv_caches: KVCache,
+        lmcache_tokens_per_chunk: int = 256,
+        layout_hints: LayoutHints | None = None,
+        engine_group_infos: Sequence[EngineGroupInfo] = (),
+        engine_type: EngineType = EngineType.VLLM,
+        separate_object_groups: bool = True,
+        full_sw_kv: bool = False,
+    ):
+        unwrapped = unwrap_kv_cache_tensors(kv_caches)
+        kv_caches_norm, engine_kv_formats = normalize_and_discover_per_layer_formats(
+            unwrapped,
+            engine_group_layer_indices(engine_group_infos),
+            engine_type,
+            layout_hints,
+        )
+        self.device_ = get_device(kv_caches_norm)
+        num_layers_val = len(engine_kv_formats)
+
+        kv_layer_groups_manager = KVLayerGroupsManager(
+            kv_caches_norm,
+            engine_kv_formats=engine_kv_formats,
+            engine_group_infos=engine_group_infos,
+            lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+            separate_object_groups=separate_object_groups,
+        )
+        # Set full_sw_kv before the temp buffer / object groups are built so
+        # both are sized for the full (un-windowed) per-chunk geometry.
+        if full_sw_kv:
+            kv_layer_groups_manager.enable_full_sw_kv()
+
+        # Pre-allocated GPU buffer for block IDs (up to 1M elements).
+        # The caller copies block_ids into this buffer before launching the
+        # block-level kernel. Single-thread assumption: no lock needed.
+        _MAX_BLOCK_IDS = 1 << 20
+        block_ids_buffer = torch.empty(
+            _MAX_BLOCK_IDS, dtype=torch.long, device=self.device_
+        )
+
+        super().__init__(
+            kv_caches=kv_caches_norm,
+            device=self.device_,
+            num_layers=num_layers_val,
+            kv_layer_groups_manager=kv_layer_groups_manager,
+            block_ids_buffer=block_ids_buffer,
+            lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+        )
+
+        self.group_kv_pointers_: list[torch.Tensor] = []
+        for idx, group in enumerate(self.kv_layer_groups_manager_.kv_layer_groups):
+            ptrs = get_group_data_ptrs(
+                self.kv_caches_, self.get_engine_kv_format(idx), group.layer_indices
+            )
+            self.group_kv_pointers_.append(list_to_gpu_tensor(ptrs, self.device_))
+
+        # Temporary GPU buffer for transfers — a single flat uint8 buffer
+        self._temp_buffer = _TempGPUBuffer(
+            kv_layer_groups_manager=self.kv_layer_groups_manager_,
+            lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+            device=self.device_,
+            max_batch_size=4,
+        )
+
+        # GPU streams
+        self.cuda_stream_ = torch_dev.Stream(device=self.device_)
+
+        # Register the staging buffer with the GDS cuFile context on the
+        # context's CUDA stream.
+        with torch_dev.stream(self.cuda_stream_):
+            get_gds_context().register_gpu_buffer(self._temp_buffer.buffer)
+
+        # Third Party
+        import cupy
+
+        self.cupy_stream_: "cupy.cuda.Stream" = cupy.cuda.ExternalStream(
+            self.cuda_stream_.cuda_stream, self.device_.index
+        )
+
+        # Extra initialization
+        self.cupy_stream_.launch_host_func(
+            lambda logger: logger.info(
+                "Initialized cuda stream on device %s", str(self.device_)
+            ),
+            logger,
+        )
+
+    def close(self) -> None:
+        """
+        Deregister this context's GDS staging buffer (reverse of __init__).
+        """
+        with torch_dev.stream(self.cuda_stream_):
+            get_gds_context().deregister_gpu_buffer(self._temp_buffer.buffer)
+
+    @property
+    def stream(self) -> Any:
+        """
+        Returns the GPU stream for KV cache operations
+        """
+        return self.cuda_stream_
+
+    @property
+    def cupy_stream(self) -> "cupy.cuda.Stream":
+        return self.cupy_stream_
+
+    def get_kernel_group_kv_pointers(self, kernel_group_idx: int) -> torch.Tensor:
+        """Returns the pre-computed GPU tensor of KV cache pointers for the
+        given kernel group index.
+        """
+        return self.group_kv_pointers_[kernel_group_idx]
+
+    def get_temp_kernel_group_buffer(
+        self, batch_idx: int, kernel_group_idx: int
+    ) -> torch.Tensor:
+        """Returns the temporary GPU buffer for the given batch index and kernel
+        group index, with the correct shape and dtype for the kernel group.
+
+        Args:
+            batch_idx: Index of the batch (0 <= batch_idx < max_batch_size)
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            The temp GPU buffer for the given batch index and kernel group index.
+        """
+        return self._temp_buffer.get_temp_kernel_group_buffer(
+            batch_idx, kernel_group_idx
+        )
+
+    @property
+    def max_batch_size(self) -> int:
+        """Maximum number of chunks processed concurrently in one batch."""
+        return self._temp_buffer.max_batch_size
+
+    def get_temp_object_group_buffer(
+        self, batch_idx: int, object_group_idx: int
+    ) -> torch.Tensor:
+        """Returns the temporary GPU buffer for the given batch index and object
+        group index, as a flat uint8 tensor.
+
+        Args:
+            batch_idx: Index of the batch (0 <= batch_idx < max_batch_size)
+            object_group_idx: Index of the object group.
+
+        Returns:
+            The temp GPU buffer for the given batch index and object group index.
+        """
+        return self._temp_buffer.get_temp_object_group_buffer(
+            batch_idx, object_group_idx
+        )
+
+    def get_kernel_group_shape_dtype(
+        self,
+        num_tokens: int,
+        kernel_group_idx: int,
+    ) -> tuple[torch.Size, torch.dtype]:
+        """Returns the shape and dtype for the given kernel group index and number
+        of tokens.
+        Will be exported by GPUCacheContext and used to construct the MemoryLayoutDesc
+
+        Args:
+            num_tokens: Number of tokens. Must be a whole number of lmcache
+                chunk size.
+            kernel_group_idx: Index of the kernel group.
+
+        Returns:
+            The shape and dtype for the given kernel group index and number of tokens.
+        """
+        return self._temp_buffer.get_kernel_group_shape_dtype(
+            num_tokens, kernel_group_idx
+        )
+
+    def cache_size_per_token(self) -> int:
+        """
+        Returns the cache size per *logical* token (in bytes), summed
+        across all groups. For a compressed group, one physical slot
+        stores ``compress_ratio`` logical tokens, so the per-logical-token
+        contribution is ``physical_slot_bytes // compress_ratio``.
+
+        Reporting-only metric (surfaced via the ``/api/status`` HTTP
+        endpoint and the ``lmcache describe`` CLI); sub-byte truncation
+        from integer division is acceptable.
+        """
+        return self._temp_buffer.get_cache_size_per_token()
+
+
+class PlainGPUCacheContext:
+    """
+    A plain GPU cache context that have a single contiguous 2LTD buffer
+    """
+
+    def __init__(self, kv_caches: KVCache, lmcache_tokens_per_chunk: int = 256):
+        assert len(kv_caches) == 1, (
+            "PlainGPUCacheContext only supports a single KV cache tensor"
+        )
+
+        # KV cache basics
+        self._kv_cache = unwrap_kv_cache_tensors(kv_caches)[0]
+        self._device = self._kv_cache.device
+
+        # Shape related
+        shape = self._kv_cache.shape
+        assert len(shape) == 4, "Expected [2, L, T, D] for plain GPU cache"
+
+        self._num_layers = shape[1]
+        self._num_tokens = shape[2]
+        self._hidden_dim_size = shape[3]
+
+        # Temporary buffer
+        tmp_buffer_shape = self.get_kv_buffer_shape(lmcache_tokens_per_chunk)
+        self._tmp_gpu_buffer = torch.empty(
+            tmp_buffer_shape, dtype=self.dtype, device=self.device
+        )
+
+        # GPU streams
+        self._cuda_stream = torch_dev.Stream(device=self._device)
+        # Third Party
+        import cupy
+
+        self._cupy_stream: "cupy.cuda.Stream" = cupy.cuda.ExternalStream(
+            self._cuda_stream.cuda_stream, self._device.index
+        )
+
+        # Extra initialization
+        self._cupy_stream.launch_host_func(
+            lambda logger: logger.info(
+                "Initialized cuda stream on device %s", str(self._device)
+            ),
+            logger,
+        )
+
+    def get_kv_buffer_shape(self, num_tokens: int) -> torch.Size:
+        """
+        Returns the shape of the KV buffer for the given number of tokens
+        """
+        return torch.Size((2, self._num_layers, num_tokens, self._hidden_dim_size))
+
+    def get_tmp_gpu_buffer(self, num_tokens: int) -> torch.Tensor:
+        """
+        Returns the temporary GPU buffer for transfers
+        """
+        return self._tmp_gpu_buffer[:, :, :num_tokens, :]
+
+    def slice_kv_cache_on_tokens(self, start: int, end: int) -> torch.Tensor:
+        """
+        Slices the KV cache tensor on the token dimension
+        """
+        return self._kv_cache[:, :, start:end, :]
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return self._kv_cache.dtype
+
+    @property
+    def device(self) -> torch.device:
+        return self._device
+
+    @property
+    def stream(self) -> Any:
+        """Returns the device-specific GPU stream (e.g., torch_dev.Stream)."""
+        return self._cuda_stream
+
+    @property
+    def cupy_stream(self) -> "cupy.cuda.Stream":
+        return self._cupy_stream
+
+    @property
+    def num_layers(self) -> int:
+        return self._num_layers
+
+    @property
+    def num_tokens(self) -> int:
+        return self._num_tokens
+
+    @property
+    def hidden_dim_size(self) -> int:
+        return self._hidden_dim_size
+
+    @property
+    def kv_cache_tensor(self) -> torch.Tensor:
+        return self._kv_cache
diff --git a/lmcache/v1/platform/cuda/ipc_wrapper.py b/lmcache/v1/platform/cuda/ipc_wrapper.py
new file mode 100644
index 0000000..83b5187
--- /dev/null
+++ b/lmcache/v1/platform/cuda/ipc_wrapper.py
@@ -0,0 +1,189 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CUDA IPC wrapper implementations.
+
+:class:`CudaIPCWrapper` handles tensors backed by PyTorch's caching
+allocator (vLLM default).  :class:`RawCudaIPCWrapper` handles tensors
+allocated outside PyTorch (e.g. TRT-LLM's ``cudaMalloc``'d pool).
+
+Both carry ``device_type = "cuda"`` so
+:func:`~lmcache.v1.platform._registry._discover_wrappers_once` can
+index them; :class:`RawCudaIPCWrapper` sets ``_is_default_wrapper =
+False`` so only :class:`CudaIPCWrapper` auto-registers as the default
+factory.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import ClassVar
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.v1.platform.base_ipc_wrapper import DeviceIPCWrapper
+
+
+class CudaIPCWrapper(DeviceIPCWrapper):
+    #: ``torch.device.type`` this wrapper handles (used by auto-discovery).
+    device_type: ClassVar[str] = "cuda"
+
+    #: Marked ``True`` so auto-discovery picks this as the default
+    #: factory for ``"cuda"``.
+    _is_default_wrapper: ClassVar[bool] = True
+
+    @classmethod
+    def wrap(cls, tensor: torch.Tensor) -> "CudaIPCWrapper":
+        """Factory used by
+        :func:`~lmcache.v1.platform._registry._discover_wrappers_once`.
+
+        Args:
+            tensor: A CUDA tensor backed by PyTorch's caching allocator.
+
+        Returns:
+            A new :class:`CudaIPCWrapper` wrapping ``tensor`` for the
+            multiprocess wire.
+        """
+        return cls(tensor)
+
+    def __init__(self, tensor: torch.Tensor) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.kv_format.contiguity import (
+            attempt_permute_to_contiguous_view,
+        )
+
+        # Permute any non-contiguous view (e.g. vLLM's NHD-over-HND) so the
+        # shape/stride we encode across IPC reflects the physical layout.
+        # Offset is preserved by the wrapper's storage_offset field.
+        tensor = attempt_permute_to_contiguous_view(tensor)
+
+        storage = tensor.untyped_storage()
+        handle = storage._share_cuda_()
+
+        self.handle = handle
+        self.dtype = tensor.dtype
+        self.shape = tuple(tensor.shape)
+        self.stride = tuple(tensor.stride())
+        self.storage_offset = int(tensor.storage_offset())
+
+        device_index = tensor.device.index
+        self.device_uuid = self._get_device_uuid(device_index)
+
+    def to_tensor(self) -> torch.Tensor:
+        """
+        Note:
+            This function may break if the accelerator is not initialized.
+            We should call ``torch_dev.init()`` before using this function
+            (guarded by hasattr since not all backends expose init()).
+        """
+        device_index = self._get_device_index_from_uuid(self.device_uuid)
+
+        storage = torch.UntypedStorage._new_shared_cuda(  # noqa: SLF001
+            device_index, *self.handle[1:]
+        )
+
+        t = torch.empty(
+            (), device=f"{torch_device_type}:{device_index}", dtype=self.dtype
+        )
+        t.set_(storage, self.storage_offset, self.shape, self.stride)
+        return t
+
+
+class RawCudaIPCWrapper(DeviceIPCWrapper):
+    """IPC wrapper for CUDA tensors allocated outside PyTorch's caching
+    allocator.
+
+    PyTorch's ``UntypedStorage._share_cuda_()`` only works for tensors
+    backed by its own caching allocator. TRT-LLM publishes its KV pool
+    via ``at::for_blob`` over a ``cudaMalloc``'d buffer, which raises in
+    ``_share_cuda_()``. This subclass bypasses that path: it calls
+    ``cudaIpcGetMemHandle`` on the raw data pointer, then reconstructs
+    the tensor on the receiving side via ``cudaIpcOpenMemHandle`` plus
+    a CuPy ``UnownedMemory`` → DLPack → ``torch`` round-trip.
+
+    Sharing the ``DeviceIPCWrapper`` base (rather than introducing a
+    parallel class with its own msgspec ext code) is load-bearing —
+    msgspec does not support unions of custom ext-encoded types. With a
+    common base, ``KVCache = list[DeviceIPCWrapper]`` type-checks, the
+    single ext code 1 round-trips every wrapper, and pickle preserves
+    the concrete subclass identity through the wire so ``to_tensor``
+    dispatches correctly.
+    """
+
+    #: Same ``torch.device.type`` as ``CudaIPCWrapper``, but
+    #: ``_is_default_wrapper = False`` so auto-discovery skips this
+    #: class — callers (TRT-LLM adapter) instantiate it directly.
+    device_type: ClassVar[str] = "cuda"
+    _is_default_wrapper: ClassVar[bool] = False
+
+    def __init__(self, tensor: torch.Tensor) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import assert_contiguous
+
+        assert_contiguous(tensor)
+
+        try:
+            # Third Party
+            from cuda.bindings import runtime as cudart
+        except ImportError:
+            # Third Party
+            from cuda import cudart
+
+        data_ptr = tensor.data_ptr()
+        err, ipc_handle = cudart.cudaIpcGetMemHandle(data_ptr)
+        if err != cudart.cudaError_t.cudaSuccess:
+            raise RuntimeError(
+                f"cudaIpcGetMemHandle failed: {err} (ptr=0x{data_ptr:x})"
+            )
+
+        # Store only what's needed for reconstruction.
+        self._ipc_handle_reserved = bytes(ipc_handle.reserved)
+        self._nbytes = tensor.untyped_storage().nbytes()
+
+        # DeviceIPCWrapper interface fields. ``handle`` is unused —
+        # ``to_tensor`` is overridden to bypass it — but kept (None) so
+        # the base-class equality check has a value to compare.
+        self.handle = None
+        self.dtype = tensor.dtype
+        self.shape = tuple(tensor.shape)
+        self.stride = tuple(tensor.stride())
+        self.storage_offset = int(tensor.storage_offset())
+
+        device_index = tensor.device.index
+        self.device_uuid = self._get_device_uuid(device_index)
+
+    def to_tensor(self) -> torch.Tensor:
+        """Reconstruct the tensor in this process via raw CUDA IPC."""
+        # Third Party
+        import cupy
+
+        try:
+            # Third Party
+            from cuda.bindings import runtime as cudart
+        except ImportError:
+            # Third Party
+            from cuda import cudart
+
+        device_index = self._get_device_index_from_uuid(self.device_uuid)
+
+        handle = cudart.cudaIpcMemHandle_t()
+        handle.reserved = self._ipc_handle_reserved
+        err, ptr = cudart.cudaIpcOpenMemHandle(
+            handle, cudart.cudaIpcMemLazyEnablePeerAccess
+        )
+        if err != cudart.cudaError_t.cudaSuccess:
+            raise RuntimeError(f"cudaIpcOpenMemHandle failed: {err}")
+
+        # Wrap as a flat ``uint8`` CuPy array, DLPack to torch, then view
+        # as the original dtype/shape. ``uint8`` avoids dtype-conversion
+        # gaps (bfloat16, fp8 have no direct CuPy/NumPy equivalent without
+        # ml_dtypes).
+        with cupy.cuda.Device(device_index):
+            mem = cupy.cuda.UnownedMemory(ptr, self._nbytes, owner=self)
+            memptr = cupy.cuda.MemoryPointer(mem, 0)
+            cp_flat = cupy.ndarray(self._nbytes, dtype=cupy.uint8, memptr=memptr)
+
+        raw = torch.from_dlpack(cp_flat)
+        return raw.view(self.dtype).reshape(self.shape)
diff --git a/lmcache/v1/platform/cuda/pin_memory.py b/lmcache/v1/platform/cuda/pin_memory.py
new file mode 100644
index 0000000..7789fb7
--- /dev/null
+++ b/lmcache/v1/platform/cuda/pin_memory.py
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CUDA memory pinning: try torch cudart first, then libcudart via ctypes."""
+
+# Standard
+import ctypes
+import ctypes.util
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.platform.base_pin_memory import PinMemoryBackend
+
+logger = init_logger(__name__)
+
+
+def _load_libcudart() -> ctypes.CDLL | None:
+    """Try to load ``libcudart`` and bind the CUDA pinning symbols.
+
+    The loaded library is configured with the ``cudaHostRegister(void*, size_t,
+    unsigned int)`` and ``cudaHostUnregister(void*)`` signatures expected by
+    the backend.
+
+    Returns:
+        The loaded ``ctypes.CDLL`` library with bound symbols on success, or
+        ``None`` if the library cannot be found or loaded.
+
+    Notes:
+        Missing symbols or load failures are treated as an unavailable
+        fallback path and cause this helper to return ``None``.
+    """
+    path = ctypes.util.find_library("cudart") or "libcudart.so"
+
+    try:
+        lib = ctypes.CDLL(path)
+        lib.cudaHostRegister.restype = ctypes.c_int
+        lib.cudaHostRegister.argtypes = [
+            ctypes.c_void_p,
+            ctypes.c_size_t,
+            ctypes.c_uint,
+        ]
+        lib.cudaHostUnregister.restype = ctypes.c_int
+        lib.cudaHostUnregister.argtypes = [ctypes.c_void_p]
+        return lib
+    except (AttributeError, OSError) as exc:
+        logger.debug("CudaPinMemoryBackend: failed to load libcudart: %s", exc)
+        return None
+
+
+class CudaPinMemoryBackend(PinMemoryBackend):
+    """CUDA memory pinning backend.
+
+    Pinning prefers ``torch.cuda.cudart()``. When the torch binding is
+    unavailable, the backend falls back to loading ``libcudart`` directly.
+
+    Attributes:
+        _cudart: Torch cudart binding when ``torch.cuda.cudart()`` succeeds.
+        _libcudart: ``ctypes``-loaded CUDA runtime when torch cudart is
+            unavailable.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the backend with torch-first, libcudart-second fallback.
+
+        The backend first tries ``torch.cuda.cudart()`` because it is the
+        lightest path when torch already exposes the CUDA runtime binding. If
+        that import or lookup fails, it falls back to loading ``libcudart``
+        directly via :mod:`ctypes`.
+
+        Notes:
+            Import and cudart lookup failures are handled internally. When both
+            the torch path and the ``libcudart`` fallback fail, the backend
+            stays in an unsupported state and ``is_pin_supported`` returns
+            ``False``.
+        """
+        self._cudart = None
+        self._libcudart = None
+
+        try:
+            # Third Party
+            import torch
+        except ImportError as exc:
+            logger.debug(
+                "CudaPinMemoryBackend: torch import failed, "
+                "attempting libcudart fallback: %s",
+                exc,
+            )
+        else:
+            try:
+                self._cudart = torch.cuda.cudart()
+                logger.info("CudaPinMemoryBackend: using torch cudart")
+                # Torch cudart succeeded, so there is no need to attempt the
+                # libcudart fallback path.
+                return
+            except (AttributeError, RuntimeError) as exc:
+                logger.debug(
+                    "CudaPinMemoryBackend: torch cudart unavailable, "
+                    "attempting libcudart fallback: %s",
+                    exc,
+                )
+
+        self._libcudart = _load_libcudart()
+        if self._libcudart is not None:
+            logger.info("CudaPinMemoryBackend: using libcudart via ctypes")
+        else:
+            logger.warning(
+                "CudaPinMemoryBackend: neither torch cudart nor libcudart is available"
+            )
+
+    def pin_memory(self, ptr: int, size: int, flags: int = 0) -> bool:
+        """Pin a host memory region using ``cudaHostRegister``.
+
+        Args:
+            ptr: Raw pointer (data_ptr) to the memory region.
+            size: Size in bytes of the region to pin.
+            flags: ``cudaHostRegister`` flags. Defaults to ``0``
+                (``cudaHostRegisterDefault``). Pass ``0x02``
+                (``cudaHostRegisterMapped``) to additionally map the region
+                into the device address space.
+
+        Returns:
+            True if ``cudaHostRegister`` succeeded, False otherwise.
+        """
+        try:
+            if self._cudart is not None:
+                err = self._cudart.cudaHostRegister(ptr, size, flags)
+                return int(err) == 0
+
+            if self._libcudart is not None:
+                err = self._libcudart.cudaHostRegister(
+                    ctypes.c_void_p(ptr),
+                    ctypes.c_size_t(size),
+                    ctypes.c_uint(flags),
+                )
+                return err == 0
+        except Exception as exc:
+            logger.warning(
+                "cudaHostRegister failed for ptr=%#x size=%d: %s", ptr, size, exc
+            )
+
+        return False
+
+    def unpin_memory(self, ptr: int) -> bool:
+        """Unpin a previously pinned host memory region.
+
+        Args:
+            ptr: Raw pointer (data_ptr) to the memory region.
+
+        Returns:
+            True if ``cudaHostUnregister`` succeeded, False otherwise.
+        """
+        try:
+            if self._cudart is not None:
+                err = self._cudart.cudaHostUnregister(ptr)
+                return int(err) == 0
+
+            if self._libcudart is not None:
+                err = self._libcudart.cudaHostUnregister(ctypes.c_void_p(ptr))
+                return err == 0
+        except Exception as exc:
+            logger.warning("cudaHostUnregister failed for ptr=%#x: %s", ptr, exc)
+
+        return False
+
+    @property
+    def is_pin_supported(self) -> bool:
+        """Whether CUDA memory pinning is supported.
+
+        Returns:
+            True if either the torch cudart binding or ``libcudart`` is
+            available, False otherwise.
+        """
+        return self._cudart is not None or self._libcudart is not None
diff --git a/lmcache/v1/platform/event_notifier.py b/lmcache/v1/platform/event_notifier.py
new file mode 100644
index 0000000..027d0fc
--- /dev/null
+++ b/lmcache/v1/platform/event_notifier.py
@@ -0,0 +1,259 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Cross-platform event notification abstraction.
+
+Provides a unified ``EventNotifier`` interface for signaling between
+threads using poll-able file descriptors.  On Linux (Python 3.10+),
+uses ``os.eventfd``; on other platforms (macOS, etc.), falls back to
+``os.pipe`` with non-blocking I/O.
+
+Usage::
+
+    from lmcache.v1.platform import create_event_notifier
+
+    notifier = create_event_notifier()
+    notifier.notify()          # signal
+    notifier.consume()         # drain
+    fd = notifier.fileno()     # for select.poll()
+    notifier.close()           # release resources
+
+Or as a context manager::
+
+    with create_event_notifier() as notifier:
+        notifier.notify()
+        notifier.consume()
+
+Exception contract:
+    ``consume()`` / ``consume_fd()`` only swallow
+    :class:`BlockingIOError` (i.e. "no data pending").  All other
+    :class:`OSError` subclasses - most importantly ``EBADF`` from a
+    stale / closed fd - propagate to the caller so bugs surface
+    instead of being silently absorbed.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from types import TracebackType
+import os
+
+#: True when :func:`os.eventfd` is available (Linux + Python 3.10+).
+#: Single source of truth for platform capability detection; exposed
+#: via :mod:`lmcache.v1.platform` for external callers.
+HAS_EVENTFD: bool = hasattr(os, "eventfd")
+
+
+class EventNotifier(ABC):
+    """Abstract base class for cross-platform event notification.
+
+    An ``EventNotifier`` models a **binary signal**: calling
+    ``notify()`` makes the notifier readable via ``poll()``/
+    ``select()``, and ``consume()`` resets it.  Multiple
+    ``notify()`` calls before a ``consume()`` are coalesced.
+    """
+
+    @abstractmethod
+    def fileno(self) -> int:
+        """Return a poll-able file descriptor.
+
+        The fd becomes readable after ``notify()`` is called.
+        """
+
+    @abstractmethod
+    def notify(self) -> None:
+        """Signal the notifier (idempotent if already signaled)."""
+
+    @abstractmethod
+    def consume(self) -> None:
+        """Consume the pending signal (non-blocking).
+
+        Only :class:`BlockingIOError` (no data pending) is
+        swallowed; other OS errors propagate.
+        """
+
+    @abstractmethod
+    def notify_fileno(self) -> int:
+        """Return the fd to write to for signaling.
+
+        For eventfd this is the same as ``fileno()``.  For pipes
+        this is the *write* end (``fileno()`` returns the read end).
+        """
+
+    @abstractmethod
+    def close(self) -> None:
+        """Release underlying OS resources.  Idempotent."""
+
+    # Context manager support
+
+    def __enter__(self) -> "EventNotifier":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+if HAS_EVENTFD:
+
+    class EventfdNotifier(EventNotifier):
+        """Linux eventfd-based notifier (Python 3.10+).
+
+        Invariants:
+            ``self._efd`` holds the live eventfd while open and is
+            set to ``-1`` once :meth:`close` has released it.  All
+            other methods treat ``-1`` as "already closed".
+        """
+
+        def __init__(self) -> None:
+            self._efd: int = os.eventfd(
+                0,
+                os.EFD_NONBLOCK | os.EFD_CLOEXEC,
+            )
+
+        def fileno(self) -> int:
+            return self._efd
+
+        def notify(self) -> None:
+            os.eventfd_write(self._efd, 1)
+
+        def notify_fileno(self) -> int:
+            return self._efd
+
+        def consume(self) -> None:
+            try:
+                os.eventfd_read(self._efd)
+            except BlockingIOError:
+                pass  # no pending signal
+
+        def close(self) -> None:
+            if self._efd >= 0:
+                try:
+                    os.close(self._efd)
+                except OSError:
+                    pass
+                self._efd = -1
+else:
+
+    class EventfdNotifier(EventNotifier):  # type: ignore[no-redef]
+        """Placeholder - eventfd unavailable on this platform."""
+
+        def __init__(self) -> None:
+            raise RuntimeError(
+                "EventfdNotifier requires os.eventfd (Linux + "
+                "Python 3.10+); use PipeNotifier instead."
+            )
+
+        def fileno(self) -> int:  # pragma: no cover
+            raise RuntimeError("unreachable")
+
+        def notify(self) -> None:  # pragma: no cover
+            raise RuntimeError("unreachable")
+
+        def notify_fileno(self) -> int:  # pragma: no cover
+            raise RuntimeError("unreachable")
+
+        def consume(self) -> None:  # pragma: no cover
+            raise RuntimeError("unreachable")
+
+        def close(self) -> None:  # pragma: no cover
+            raise RuntimeError("unreachable")
+
+
+class PipeNotifier(EventNotifier):
+    """Pipe-based fallback notifier for non-Linux platforms.
+
+    Invariants:
+        ``self._read_fd`` / ``self._write_fd`` hold the live pipe
+        ends while open and are both set to ``-1`` once
+        :meth:`close` has released them.
+    """
+
+    def __init__(self) -> None:
+        # ``os.pipe()`` on Python 3.4+ creates descriptors with
+        # ``FD_CLOEXEC`` already set (PEP 446), so we only need to
+        # flip them to non-blocking.  ``os.set_blocking`` is the
+        # portable way to do this and improves future portability
+        # (e.g. to Windows pipes).
+        r, w = os.pipe()
+        try:
+            os.set_blocking(r, False)
+            os.set_blocking(w, False)
+        except OSError:
+            os.close(r)
+            os.close(w)
+            raise
+        self._read_fd: int = r
+        self._write_fd: int = w
+
+    def fileno(self) -> int:
+        return self._read_fd
+
+    def notify(self) -> None:
+        try:
+            os.write(self._write_fd, b"\x01")
+        except BlockingIOError:
+            pass  # pipe buffer full - signal already pending
+
+    def notify_fileno(self) -> int:
+        return self._write_fd
+
+    def consume(self) -> None:
+        while True:
+            try:
+                # ``os.read`` returns ``b''`` at EOF (write end
+                # closed); treat that as drained so background
+                # loops cannot spin forever on a dead pipe.
+                if not os.read(self._read_fd, 4096):
+                    return
+            except BlockingIOError:
+                return  # drained
+
+    def close(self) -> None:
+        for attr in ("_read_fd", "_write_fd"):
+            fd = getattr(self, attr, -1)
+            if fd >= 0:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+                setattr(self, attr, -1)
+
+
+def create_event_notifier() -> EventNotifier:
+    """Create a platform-appropriate EventNotifier.
+
+    On Linux (Python 3.10+), returns an ``EventfdNotifier``.
+    On other platforms, returns a ``PipeNotifier``.
+    """
+    if HAS_EVENTFD:
+        return EventfdNotifier()
+    return PipeNotifier()
+
+
+def consume_fd(fd: int) -> None:
+    """Consume a pending signal from a raw file descriptor.
+
+    This is a convenience function for code that only has a
+    raw fd (e.g., obtained from ``adapter.get_store_event_fd()``)
+    and needs to drain it after ``poll()`` reports it readable.
+
+    On Linux, uses ``os.eventfd_read()``; on other platforms,
+    drains all bytes via ``os.read()``.
+
+    Only :class:`BlockingIOError` (no data pending) is swallowed;
+    other OS errors propagate.
+    """
+    if HAS_EVENTFD:
+        try:
+            os.eventfd_read(fd)
+        except BlockingIOError:
+            pass
+        return
+    while True:
+        try:
+            if not os.read(fd, 4096):
+                return  # EOF -- write end closed; stop draining
+        except BlockingIOError:
+            return
diff --git a/lmcache/v1/platform/hpu/__init__.py b/lmcache/v1/platform/hpu/__init__.py
new file mode 100644
index 0000000..245f25d
--- /dev/null
+++ b/lmcache/v1/platform/hpu/__init__.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HPU (Habana Gaudi) platform helpers."""
+
+# First Party
+from lmcache.v1.platform.base_device_spec import DeviceSpec
+
+# ---------------------------------------------------------------------------
+# Device detection registry entry
+# ---------------------------------------------------------------------------
+
+
+class HpuDeviceSpec(DeviceSpec):
+    """HPU device specification for the detection registry."""
+
+    @property
+    def device_type(self) -> str:
+        return "hpu"
+
+    @property
+    def torch_module_name(self) -> str:
+        return "hpu"
+
+    @property
+    def ops_module(self) -> str | None:
+        return None
+
+    def is_available(self) -> bool:
+        """Check HPU availability without importing lmcache.__init__."""
+        try:
+            # Third Party
+            import torch
+
+            return hasattr(torch, "hpu") and torch.hpu.is_available()
+        except Exception:
+            return False
diff --git a/lmcache/v1/platform/musa/__init__.py b/lmcache/v1/platform/musa/__init__.py
new file mode 100644
index 0000000..9132986
--- /dev/null
+++ b/lmcache/v1/platform/musa/__init__.py
@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MUSA-specific platform primitives."""
+
+# First Party
+from lmcache.v1.platform.base_device_spec import DeviceSpec
+
+# ---------------------------------------------------------------------------
+# Device detection registry entry
+# ---------------------------------------------------------------------------
+
+
+class MusaDeviceSpec(DeviceSpec):
+    """MUSA device specification for the detection registry."""
+
+    @property
+    def device_type(self) -> str:
+        return "musa"
+
+    @property
+    def torch_module_name(self) -> str:
+        return "musa"
+
+    @property
+    def ops_module(self) -> str | None:
+        return "lmcache.v1.platform.musa.ops"
+
+    def is_available(self) -> bool:
+        """Check MUSA availability without importing lmcache.__init__."""
+        try:
+            # Third Party
+            import torch
+
+            return hasattr(torch, "musa") and torch.musa.is_available()  # type: ignore[attr-defined]
+        except Exception:
+            return False
+
+    def is_handle_transfer_available(self) -> bool:
+        # First Party
+        from lmcache.v1.platform.musa.ipc import is_musa_handle_transfer_available
+
+        return is_musa_handle_transfer_available()
diff --git a/lmcache/v1/platform/musa/ipc.py b/lmcache/v1/platform/musa/ipc.py
new file mode 100644
index 0000000..cf940ea
--- /dev/null
+++ b/lmcache/v1/platform/musa/ipc.py
@@ -0,0 +1,318 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Optional MUSA IPC wrapper used by the Stage4 MP handle path.
+
+The MUSA handle path is deliberately fail-closed. This module exposes a
+``DeviceIPCWrapper`` subclass for the platform registry to auto-discover, but
+it only constructs wrappers when the user explicitly enables the path and every
+required handle-path capability is present.
+"""
+
+# Standard
+from typing import ClassVar, Protocol, cast
+import importlib
+import inspect
+import os
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.contiguity import (
+    attempt_permute_to_contiguous_view,
+)
+from lmcache.v1.gpu_connector.utils import assert_contiguous
+from lmcache.v1.platform.base_ipc_wrapper import DeviceIPCWrapper
+
+ENV_MUSA_HANDLE_TRANSFER = "LMCACHE_MUSA_HANDLE_TRANSFER"
+
+_REQUIRED_TORCH_MUSA_IPC_SYMBOLS = (
+    "ipc_get_mem_handle",
+    "ipc_open_mem_handle",
+)
+
+
+class _TorchMusaIPCModule(Protocol):
+    """TorchMUSA surface required by the Stage4.1 handle capability gate."""
+
+    def ipc_get_mem_handle(self, tensor: torch.Tensor) -> object:
+        """Export a MUSA tensor as a process-portable IPC handle."""
+
+    def ipc_open_mem_handle(
+        self,
+        handle: bytes,
+        nbytes: int,
+        device_index: int,
+    ) -> object:
+        """Import a MUSA IPC handle in the current process."""
+
+
+def is_musa_handle_transfer_enabled() -> bool:
+    """Return whether users opted into the experimental MUSA handle path."""
+    return os.environ.get(ENV_MUSA_HANDLE_TRANSFER, "").lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+
+
+def is_torch_musa_available() -> bool:
+    """Return whether TorchMUSA is importable and reports a visible device."""
+    torch_musa = get_torch_musa_module()
+    if torch_musa is None:
+        return False
+    is_available = getattr(torch_musa, "is_available", None)
+    if not callable(is_available):
+        return False
+    try:
+        return bool(is_available())
+    except Exception:
+        return False
+
+
+def get_torch_musa_module() -> object | None:
+    """Return the TorchMUSA module when this PyTorch build exposes it.
+
+    Returns:
+        ``torch.musa`` when present, otherwise ``None``.
+    """
+    if not hasattr(torch, "musa"):
+        # torch_musa registers torch.musa as an import side effect.
+        try:
+            importlib.import_module("torch_musa")
+        except ImportError:
+            pass
+    if not hasattr(torch, "musa"):
+        return None
+    return torch.musa  # type: ignore[attr-defined]
+
+
+def check_torch_musa_ipc_support(torch_musa: object) -> bool:
+    """Return whether TorchMUSA exposes memory IPC primitives."""
+    return all(
+        callable(getattr(torch_musa, symbol, None))
+        for symbol in _REQUIRED_TORCH_MUSA_IPC_SYMBOLS
+    )
+
+
+def check_torch_musa_event_support(torch_musa: object) -> bool:
+    """Return whether TorchMUSA exposes IPC event ordering primitives."""
+    event_cls = getattr(torch_musa, "Event", None)
+    if event_cls is None or not hasattr(event_cls, "from_ipc_handle"):
+        return False
+    return _has_interprocess_parameter(event_cls) or _has_interprocess_parameter(
+        getattr(event_cls, "__new__", None)
+    )
+
+
+def is_musa_block_transfer_available() -> bool:
+    """Return whether server-side MUSA block transfer is production-ready.
+
+    Stage4.1 only adds the safe integration boundary. Until Stage4.3 wires and
+    validates the server-side MUSA block-transfer primitive, forced MUSA handle
+    mode must remain unavailable even if TorchMUSA memory/event IPC exists.
+    """
+    return False
+
+
+def is_musa_handle_transfer_available() -> bool:
+    """Return whether forced MUSA MP handle mode may be selected.
+
+    Availability requires all four conditions:
+    - explicit user opt-in through :data:`ENV_MUSA_HANDLE_TRANSFER`;
+    - a visible TorchMUSA runtime;
+    - TorchMUSA memory IPC and interprocess event support;
+    - a validated server-side MUSA block-transfer primitive.
+    """
+    if not is_musa_handle_transfer_enabled():
+        return False
+    if not is_torch_musa_available():
+        return False
+    torch_musa = get_torch_musa_module()
+    return (
+        torch_musa is not None
+        and check_torch_musa_ipc_support(torch_musa)
+        and check_torch_musa_event_support(torch_musa)
+        and is_musa_block_transfer_available()
+    )
+
+
+class MusaIPCWrapper(DeviceIPCWrapper):
+    """Wire-compatible wrapper for MUSA memory IPC handles.
+
+    The class subclasses :class:`DeviceIPCWrapper` so it shares the
+    device-agnostic ``KVCache = list[DeviceIPCWrapper]`` msgspec wire type with
+    CUDA and CPU wrappers. Pickle preserves the subclass identity, and the
+    receiver calls this class's :meth:`to_tensor` implementation to reconstruct
+    a MUSA tensor.
+    """
+
+    #: ``torch.device.type`` this wrapper handles (used by auto-discovery).
+    device_type: ClassVar[str] = "musa"
+
+    #: Marked ``True`` so auto-discovery picks this as the default factory.
+    _is_default_wrapper: ClassVar[bool] = True
+
+    _discovered_device_mapping: dict[str, int] = {}
+    _device_mapping_lock = threading.Lock()
+
+    @classmethod
+    def wrap(cls, tensor: torch.Tensor) -> "MusaIPCWrapper":
+        """Factory used by the platform registry auto-discovery.
+
+        Args:
+            tensor: A MUSA tensor to export through TorchMUSA IPC.
+
+        Returns:
+            A new :class:`MusaIPCWrapper` wrapping ``tensor`` for the
+            multiprocess wire.
+        """
+        return cls(tensor)
+
+    def __init__(self, tensor: torch.Tensor) -> None:
+        """Export a MUSA tensor through the TorchMUSA IPC runtime.
+
+        Args:
+            tensor: A contiguous MUSA tensor to export.
+
+        Raises:
+            ValueError: If ``tensor`` is not a MUSA tensor or cannot be
+                represented as a zero-offset contiguous view.
+            RuntimeError: If the Stage4 MUSA handle capability is unavailable.
+        """
+        tensor_view = attempt_permute_to_contiguous_view(tensor)
+        if (
+            not isinstance(tensor_view, torch.Tensor)
+            or tensor_view.device.type != "musa"
+        ):
+            raise ValueError("expected a MUSA tensor for MusaIPCWrapper")
+        tensor = tensor_view
+        assert_contiguous(tensor)
+
+        module = _torch_musa_module_if_ready()
+        if module is None:
+            raise RuntimeError(
+                "MUSA IPC handle transfer is not available. Set "
+                f"{ENV_MUSA_HANDLE_TRANSFER}=1 with compatible TorchMUSA "
+                "memory/event IPC support and a validated MUSA block-transfer "
+                "backend, or use MP transfer mode 'engine_driven' or 'auto'."
+            )
+
+        self._musa_ipc_handle = _coerce_ipc_handle(module.ipc_get_mem_handle(tensor))
+        self._nbytes = tensor.untyped_storage().nbytes()
+
+        self.handle = None
+        self.dtype = tensor.dtype
+        self.shape = tuple(tensor.shape)
+        self.stride = tuple(tensor.stride())
+        self.storage_offset = int(tensor.storage_offset())
+
+        device_index = tensor.device.index
+        self.device_uuid = self._get_device_uuid(
+            0 if device_index is None else device_index
+        )
+
+    def to_tensor(self) -> torch.Tensor:
+        """Reconstruct the MUSA tensor in this process."""
+        module = _torch_musa_module_if_ready()
+        if module is None:
+            raise RuntimeError(
+                "MUSA IPC handle transfer is not available in the receiver process."
+            )
+
+        device_index = self._get_device_index_from_uuid(self.device_uuid)
+        raw = module.ipc_open_mem_handle(
+            self._musa_ipc_handle,
+            self._nbytes,
+            device_index,
+        )
+        if isinstance(raw, torch.Tensor):
+            tensor = raw
+        else:
+            tensor = torch.from_dlpack(raw)
+
+        if tensor.dtype == torch.uint8 and self.dtype != torch.uint8:
+            tensor = tensor.view(self.dtype)
+        return tensor.as_strided(self.shape, self.stride, self.storage_offset)
+
+    @classmethod
+    def _get_device_uuid(cls, device_index: int) -> str:
+        """Return a stable MUSA device identifier for ``device_index``."""
+        props = torch.musa.get_device_properties(device_index)  # type: ignore[attr-defined]
+        uuid = getattr(props, "uuid", None)
+        if uuid is not None:
+            return str(uuid)
+        pci_bus_id = getattr(props, "pci_bus_id", None)
+        if pci_bus_id is not None:
+            return str(pci_bus_id)
+        name = getattr(props, "name", "musa")
+        return f"{name}:{device_index}"
+
+    @classmethod
+    def _discover_devices(cls) -> None:
+        """Discover visible MUSA devices and cache their identifiers."""
+        if not is_torch_musa_available():
+            return
+
+        with cls._device_mapping_lock:
+            if cls._discovered_device_mapping:
+                return
+
+            for i in range(torch.musa.device_count()):  # type: ignore[attr-defined]
+                device_uuid = cls._get_device_uuid(i)
+                cls._discovered_device_mapping[device_uuid] = i
+
+    @classmethod
+    def _get_device_index_from_uuid(cls, device_uuid: str) -> int:
+        """Resolve the sender's MUSA device identifier in this process."""
+        cls._discover_devices()
+
+        with cls._device_mapping_lock:
+            device_index = cls._discovered_device_mapping.get(device_uuid)
+
+        if device_index is None:
+            raise RuntimeError(
+                f"MUSA device UUID {device_uuid} not found in visible devices. "
+                "Please make sure the worker and server see the same MUSA devices."
+            )
+        return device_index
+
+
+def _torch_musa_module_if_ready() -> _TorchMusaIPCModule | None:
+    """Return TorchMUSA when all handle-path capability gates pass."""
+    if not is_musa_handle_transfer_enabled():
+        return None
+    if not is_torch_musa_available():
+        return None
+    module = get_torch_musa_module()
+    if (
+        module is None
+        or not check_torch_musa_ipc_support(module)
+        or not check_torch_musa_event_support(module)
+        or not is_musa_block_transfer_available()
+    ):
+        return None
+    return cast(_TorchMusaIPCModule, module)
+
+
+def _coerce_ipc_handle(handle: object) -> bytes:
+    """Normalize a MUSA IPC handle into bytes for pickle/msgspec transport."""
+    if isinstance(handle, bytes):
+        return handle
+    if isinstance(handle, bytearray):
+        return bytes(handle)
+    if isinstance(handle, memoryview):
+        return handle.tobytes()
+    raise TypeError("MUSA IPC handle must be bytes-like")
+
+
+def _has_interprocess_parameter(obj: object) -> bool:
+    """Return whether ``obj`` accepts the ``interprocess`` event parameter."""
+    if not callable(obj):
+        return False
+    try:
+        signature = inspect.signature(obj)
+    except (TypeError, ValueError):
+        return False
+    return "interprocess" in signature.parameters
diff --git a/lmcache/v1/platform/musa/native_kv_transfer.py b/lmcache/v1/platform/musa/native_kv_transfer.py
new file mode 100644
index 0000000..1bd6214
--- /dev/null
+++ b/lmcache/v1/platform/musa/native_kv_transfer.py
@@ -0,0 +1,486 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Optional native MUSA KV-transfer adapter for LMCache.
+
+The adapter is deliberately fail-closed. It never makes ``musa_aiter`` a
+required dependency and returns ``False`` whenever native dispatch is not
+available, so callers can keep using the torch implementation as the fallback.
+"""
+
+# Standard
+from importlib import import_module
+from typing import Any
+import os
+
+# Third Party
+import torch
+
+ENV_MUSA_NATIVE_KV_TRANSFER = "LMCACHE_MUSA_NATIVE_KV_TRANSFER"
+NATIVE_LMCACHE_KV_TRANSFER_ABI_VERSION = 1
+
+_REQUIRED_NATIVE_SYMBOLS = (
+    "native_lmcache_kv_transfer_abi_version",
+    "lmcache_kv_paged_to_buffer",
+    "lmcache_kv_buffer_to_paged",
+    "lmcache_mla_paged_to_buffer",
+    "lmcache_mla_buffer_to_paged",
+)
+
+_SUPPORTED_BLOCK_TRANSFER_FORMATS = {
+    "NL_X_TWO_NB_BS_NH_HS",
+    "NL_X_NB_BS_HS",
+}
+_MLA_BLOCK_TRANSFER_FORMATS = {"NL_X_NB_BS_HS"}
+_TRANSFER_DIRECTION_H2D = 0
+_TRANSFER_DIRECTION_D2H = 1
+
+
+def is_native_musa_kv_transfer_enabled() -> bool:
+    """Return whether LMCache should try optional native MUSA KV transfer."""
+    return os.environ.get(ENV_MUSA_NATIVE_KV_TRANSFER, "").lower() in {
+        "1",
+        "true",
+        "yes",
+    }
+
+
+def load_native_musa_module() -> Any | None:
+    """Import optional ``musa_aiter``, returning ``None`` when unavailable."""
+    try:
+        return import_module("musa_aiter")
+    except Exception:
+        return None
+
+
+def check_native_abi(module: Any) -> bool:
+    """Return whether ``module`` exposes the Stage2 LMCache KV-transfer ABI."""
+    for name in _REQUIRED_NATIVE_SYMBOLS:
+        if not callable(getattr(module, name, None)):
+            return False
+    try:
+        version = int(module.native_lmcache_kv_transfer_abi_version())
+    except Exception:
+        return False
+    return version == NATIVE_LMCACHE_KV_TRANSFER_ABI_VERSION
+
+
+def _is_musa_contiguous_tensor(tensor: torch.Tensor) -> bool:
+    """Return whether a tensor can be passed directly to MUSA native kernels."""
+    return tensor.device.type == "musa" and tensor.is_contiguous()
+
+
+def _native_tensors_ready(
+    memory_tensor: torch.Tensor,
+    kvcaches: list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+) -> bool:
+    """Return whether native MUSA dispatch can consume these tensors directly."""
+    return (
+        _is_musa_contiguous_tensor(memory_tensor)
+        and _is_musa_contiguous_tensor(slot_mapping)
+        and all(_is_musa_contiguous_tensor(kvcache) for kvcache in kvcaches)
+    )
+
+
+def try_native_multi_layer_block_kv_transfer(
+    *,
+    paged_layers: Any,
+    object_tensors: list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    direction: Any,
+    shape_desc: Any,
+    lmcache_chunk_size: int,
+    engine_kv_format: Any,
+    skip_prefix_n_blocks: int,
+) -> bool:
+    """Try native MUSA acceleration for block-based paged-KV transfer.
+
+    This is the optional native fast path used by
+    ``lmcache.v1.platform.musa.ops`` behind
+    ``lmc_ops.multi_layer_block_kv_transfer``. It hides the MUSA-specific
+    eligibility checks, slot mapping, and CPU staging from the generic
+    multiprocess transfer context.
+
+    Args:
+        paged_layers: Normalized per-layer paged KV tensors.
+        object_tensors: LMCache chunk tensors.
+        block_ids: Engine block IDs in object order.
+        direction: Transfer direction enum or integer.
+        shape_desc: Page buffer shape descriptor.
+        lmcache_chunk_size: Tokens per LMCache object.
+        engine_kv_format: Engine KV layout enum.
+        skip_prefix_n_blocks: Whole blocks to skip before H2D scatter.
+
+    Returns:
+        ``True`` when native dispatch completed and the caller should skip the
+        torch fallback. ``False`` when the transfer is unsupported, disabled,
+        unavailable, or rejected by the native module.
+    """
+    if not is_native_musa_kv_transfer_enabled():
+        return False
+    if not object_tensors or lmcache_chunk_size <= 0:
+        return False
+    if not _is_supported_musa_block_transfer_format(engine_kv_format):
+        return False
+    if not _is_musa_block_transfer_candidate(paged_layers):
+        return False
+
+    is_d2h = int(direction) == _TRANSFER_DIRECTION_D2H
+    is_h2d = int(direction) == _TRANSFER_DIRECTION_H2D
+    if not (is_d2h or is_h2d):
+        return False
+    if is_d2h and skip_prefix_n_blocks != 0:
+        return False
+
+    block_size = int(getattr(shape_desc, "bs", 0))
+    if block_size <= 0 or lmcache_chunk_size % block_size != 0:
+        return False
+    blocks_per_object = lmcache_chunk_size // block_size
+    block_id_list = _to_block_id_list(block_ids)
+
+    layer_tensors = _as_tensor_list(paged_layers)
+    if layer_tensors is None:
+        return False
+    use_mla = _is_mla_block_transfer_format(engine_kv_format)
+    native_dims = _native_transfer_dims(layer_tensors, shape_desc, use_mla)
+    if native_dims is None:
+        return False
+    num_heads, head_size = native_dims
+
+    if is_d2h:
+        return _try_native_block_transfer_from_gpu(
+            layer_tensors=layer_tensors,
+            object_tensors=object_tensors,
+            block_ids=block_id_list,
+            blocks_per_object=blocks_per_object,
+            block_size=block_size,
+            use_mla=use_mla,
+            num_heads=num_heads,
+            head_size=head_size,
+        )
+    return _try_native_block_transfer_to_gpu(
+        layer_tensors=layer_tensors,
+        object_tensors=object_tensors,
+        block_ids=block_id_list,
+        blocks_per_object=blocks_per_object,
+        block_size=block_size,
+        use_mla=use_mla,
+        num_heads=num_heads,
+        head_size=head_size,
+        skip_prefix_n_blocks=skip_prefix_n_blocks,
+    )
+
+
+def try_native_to_gpu(
+    *,
+    use_mla: bool,
+    memory_tensor: torch.Tensor,
+    kvcaches: list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+    start: int,
+    end: int,
+    skip_prefix_n_tokens: int,
+    block_size: int,
+    num_heads: int,
+    head_size: int,
+) -> bool:
+    """Try native contiguous-buffer-to-paged-KV scatter.
+
+    Args:
+        use_mla: Whether the active layout is MLA.
+        memory_tensor: LMCache contiguous memory object tensor.
+        kvcaches: vLLM paged KV tensors.
+        slot_mapping: Full vLLM slot mapping tensor.
+        start: Inclusive token start for this transfer.
+        end: Exclusive token end for this transfer.
+        skip_prefix_n_tokens: Prefix tokens already cached by vLLM.
+        block_size: vLLM paged KV block size.
+        num_heads: Number of KV heads for non-MLA layouts.
+        head_size: KV head size or MLA hidden size.
+
+    Returns:
+        ``True`` when native dispatch completed and the caller should skip the
+        torch fallback. ``False`` when native dispatch is disabled, unavailable,
+        ABI-incompatible, when tensors are not contiguous MUSA tensors, or when
+        the native module rejects the transfer.
+    """
+    module = _native_module_if_ready()
+    if module is None:
+        return False
+
+    transfer_start = start + skip_prefix_n_tokens
+    if transfer_start >= end:
+        return True
+    if not _native_tensors_ready(memory_tensor, kvcaches, slot_mapping):
+        return False
+
+    slot_slice = slot_mapping[transfer_start:end]
+    try:
+        if use_mla:
+            return bool(
+                module.lmcache_mla_buffer_to_paged(
+                    memory_tensor,
+                    kvcaches,
+                    slot_slice,
+                    skip_prefix_n_tokens,
+                    block_size,
+                    head_size,
+                )
+            )
+        return bool(
+            module.lmcache_kv_buffer_to_paged(
+                memory_tensor,
+                kvcaches,
+                slot_slice,
+                skip_prefix_n_tokens,
+                block_size,
+                num_heads,
+                head_size,
+            )
+        )
+    except Exception:
+        return False
+
+
+def try_native_from_gpu(
+    *,
+    use_mla: bool,
+    memory_tensor: torch.Tensor,
+    kvcaches: list[torch.Tensor],
+    slot_mapping: torch.Tensor,
+    start: int,
+    end: int,
+    block_size: int,
+    num_heads: int,
+    head_size: int,
+) -> bool:
+    """Try native paged-KV-to-contiguous-buffer gather.
+
+    Args:
+        use_mla: Whether the active layout is MLA.
+        memory_tensor: LMCache contiguous memory object tensor to populate.
+        kvcaches: vLLM paged KV tensors.
+        slot_mapping: Full vLLM slot mapping tensor.
+        start: Inclusive token start for this transfer.
+        end: Exclusive token end for this transfer.
+        block_size: vLLM paged KV block size.
+        num_heads: Number of KV heads for non-MLA layouts.
+        head_size: KV head size or MLA hidden size.
+
+    Returns:
+        ``True`` when native dispatch completed and the caller should skip the
+        torch fallback. ``False`` when native dispatch is unavailable, when
+        tensors are not contiguous MUSA tensors, or when native dispatch fails.
+    """
+    module = _native_module_if_ready()
+    if module is None:
+        return False
+    if start >= end:
+        return True
+    if not _native_tensors_ready(memory_tensor, kvcaches, slot_mapping):
+        return False
+
+    slot_slice = slot_mapping[start:end]
+    try:
+        if use_mla:
+            return bool(
+                module.lmcache_mla_paged_to_buffer(
+                    kvcaches,
+                    memory_tensor,
+                    slot_slice,
+                    block_size,
+                    head_size,
+                )
+            )
+        return bool(
+            module.lmcache_kv_paged_to_buffer(
+                kvcaches,
+                memory_tensor,
+                slot_slice,
+                block_size,
+                num_heads,
+                head_size,
+            )
+        )
+    except Exception:
+        return False
+
+
+def _native_module_if_ready() -> Any | None:
+    """Return a usable native module when opt-in and ABI-compatible."""
+    if not is_native_musa_kv_transfer_enabled():
+        return None
+    module = load_native_musa_module()
+    if module is None or not check_native_abi(module):
+        return None
+    return module
+
+
+def _engine_kv_format_name(engine_kv_format: Any) -> str:
+    """Return a stable enum member name for Python and pybind enum values."""
+    name = getattr(engine_kv_format, "name", None)
+    if isinstance(name, str):
+        return name
+    return str(engine_kv_format).rsplit(".", maxsplit=1)[-1]
+
+
+def _is_supported_musa_block_transfer_format(engine_kv_format: Any) -> bool:
+    """Return whether the native MUSA block path supports ``engine_kv_format``."""
+    return _engine_kv_format_name(engine_kv_format) in _SUPPORTED_BLOCK_TRANSFER_FORMATS
+
+
+def _is_mla_block_transfer_format(engine_kv_format: Any) -> bool:
+    """Return whether ``engine_kv_format`` is a native-supported MLA layout."""
+    return _engine_kv_format_name(engine_kv_format) in _MLA_BLOCK_TRANSFER_FORMATS
+
+
+def _as_tensor_list(value: Any) -> list[torch.Tensor] | None:
+    """Return ``value`` as a flat tensor list, or ``None`` when unsupported."""
+    if not isinstance(value, list) or not value:
+        return None
+    if not all(isinstance(tensor, torch.Tensor) for tensor in value):
+        return None
+    return value
+
+
+def _is_musa_block_transfer_candidate(paged_layers: Any) -> bool:
+    """Return whether normalized paged layers can use native MUSA kernels."""
+    layer_tensors = _as_tensor_list(paged_layers)
+    return layer_tensors is not None and all(
+        _is_musa_contiguous_tensor(tensor) for tensor in layer_tensors
+    )
+
+
+def _to_block_id_list(block_ids: torch.Tensor | list[int]) -> list[int]:
+    """Convert block IDs from tensor/list form into Python integers."""
+    if isinstance(block_ids, torch.Tensor):
+        return [int(x) for x in block_ids.to(dtype=torch.int64).cpu().tolist()]
+    return [int(x) for x in block_ids]
+
+
+def _native_transfer_dims(
+    layer_tensors: list[torch.Tensor],
+    shape_desc: Any,
+    use_mla: bool,
+) -> tuple[int, int] | None:
+    """Return ``(num_heads, head_size)`` for native MUSA transfer."""
+    if use_mla:
+        head_size = int(getattr(shape_desc, "hs", 0)) or int(layer_tensors[0].shape[-1])
+        return 1, head_size
+    num_heads = int(getattr(shape_desc, "nh", 0))
+    head_size = int(getattr(shape_desc, "hs", 0))
+    if num_heads <= 0 or head_size <= 0:
+        sample = layer_tensors[0][0]
+        if sample.ndim < 4:
+            return None
+        num_heads = int(sample.shape[-2])
+        head_size = int(sample.shape[-1])
+    return num_heads, head_size
+
+
+def _block_ids_to_slot_mapping(
+    block_ids: list[int],
+    block_size: int,
+    device: torch.device,
+) -> torch.Tensor:
+    """Expand paged block IDs into token slot IDs on ``device``."""
+    block_ids_tensor = torch.tensor(block_ids, dtype=torch.long, device=device)
+    token_offsets = torch.arange(block_size, dtype=torch.long, device=device)
+    return (block_ids_tensor.unsqueeze(1) * block_size + token_offsets).flatten()
+
+
+def _object_block_ids(
+    block_ids: list[int],
+    object_idx: int,
+    blocks_per_object: int,
+) -> list[int]:
+    """Return block IDs belonging to one LMCache object."""
+    start = object_idx * blocks_per_object
+    end = min(start + blocks_per_object, len(block_ids))
+    return block_ids[start:end]
+
+
+def _try_native_block_transfer_from_gpu(
+    *,
+    layer_tensors: list[torch.Tensor],
+    object_tensors: list[torch.Tensor],
+    block_ids: list[int],
+    blocks_per_object: int,
+    block_size: int,
+    use_mla: bool,
+    num_heads: int,
+    head_size: int,
+) -> bool:
+    """Try native paged-KV-to-object gather for each LMCache object."""
+    device = layer_tensors[0].device
+    for object_idx, object_tensor in enumerate(object_tensors):
+        chunk_block_ids = _object_block_ids(block_ids, object_idx, blocks_per_object)
+        if not chunk_block_ids:
+            continue
+        slot_mapping = _block_ids_to_slot_mapping(chunk_block_ids, block_size, device)
+        memory_tensor = (
+            object_tensor
+            if _is_musa_contiguous_tensor(object_tensor)
+            else torch.empty_like(object_tensor, device=device)
+        )
+        if not try_native_from_gpu(
+            use_mla=use_mla,
+            memory_tensor=memory_tensor,
+            kvcaches=layer_tensors,
+            slot_mapping=slot_mapping,
+            start=0,
+            end=int(slot_mapping.numel()),
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+        ):
+            return False
+        if memory_tensor is not object_tensor:
+            object_tensor.copy_(
+                memory_tensor.to(object_tensor.device), non_blocking=True
+            )
+    return True
+
+
+def _try_native_block_transfer_to_gpu(
+    *,
+    layer_tensors: list[torch.Tensor],
+    object_tensors: list[torch.Tensor],
+    block_ids: list[int],
+    blocks_per_object: int,
+    block_size: int,
+    use_mla: bool,
+    num_heads: int,
+    head_size: int,
+    skip_prefix_n_blocks: int,
+) -> bool:
+    """Try native object-to-paged-KV scatter for each LMCache object."""
+    device = layer_tensors[0].device
+    for object_idx, object_tensor in enumerate(object_tensors):
+        chunk_block_ids = _object_block_ids(block_ids, object_idx, blocks_per_object)
+        if not chunk_block_ids:
+            continue
+        object_start_block = object_idx * blocks_per_object
+        chunk_skip_blocks = max(0, skip_prefix_n_blocks - object_start_block)
+        if chunk_skip_blocks >= len(chunk_block_ids):
+            continue
+
+        memory_tensor = object_tensor.to(device, non_blocking=True)
+        if memory_tensor is object_tensor:
+            memory_tensor = object_tensor.clone()
+        elif not memory_tensor.is_contiguous():
+            memory_tensor = memory_tensor.contiguous()
+        slot_mapping = _block_ids_to_slot_mapping(chunk_block_ids, block_size, device)
+        if not try_native_to_gpu(
+            use_mla=use_mla,
+            memory_tensor=memory_tensor,
+            kvcaches=layer_tensors,
+            slot_mapping=slot_mapping,
+            start=0,
+            end=int(slot_mapping.numel()),
+            skip_prefix_n_tokens=chunk_skip_blocks * block_size,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+        ):
+            return False
+    return True
diff --git a/lmcache/v1/platform/musa/ops.py b/lmcache/v1/platform/musa/ops.py
new file mode 100644
index 0000000..085b7fd
--- /dev/null
+++ b/lmcache/v1/platform/musa/ops.py
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MUSA ops backend assembled into ``lmcache.c_ops`` at import time.
+
+The package initializer merges this module over ``python_ops_fallback`` when
+MUSA is the active device. Functions not defined here continue to use the
+generic Python fallback implementation.
+"""
+
+# Future
+from __future__ import annotations
+
+# Third Party
+import torch
+
+# First Party
+import lmcache.python_ops_fallback as py_ops
+
+
+def _tensor_list(value: object) -> list[torch.Tensor] | None:
+    """Return ``value`` as ``list[torch.Tensor]`` when it is tensor-backed."""
+    if not isinstance(value, list):
+        return None
+    if not all(isinstance(item, torch.Tensor) for item in value):
+        return None
+    return value
+
+
+def multi_layer_block_kv_transfer(
+    paged_buffer_ptrs_tensor: torch.Tensor | list,
+    lmcache_objects_ptrs: list[int] | list[torch.Tensor],
+    block_ids: torch.Tensor | list[int],
+    device: torch.device | str,
+    direction: py_ops.TransferDirection,
+    shape_desc: py_ops.PageBufferShapeDesc,
+    lmcache_chunk_size: int,
+    engine_kv_format: py_ops.EngineKVFormat,
+    skip_prefix_n_blocks: int,
+) -> None:
+    """MUSA block-based multi-layer KV transfer.
+
+    This function intentionally mirrors ``lmcache.c_ops`` and
+    ``python_ops_fallback`` so upper layers can call ``lmcache.c_ops`` without
+    caring which device backend was selected during package initialization.
+
+    Args:
+        paged_buffer_ptrs_tensor: Paged buffer pointers or normalized tensors.
+        lmcache_objects_ptrs: LMCache object pointers or chunk tensors.
+        block_ids: Ordered engine block IDs for the transfer.
+        device: Target device for the transfer.
+        direction: Transfer direction (H2D or D2H).
+        shape_desc: Shape descriptor of the page buffer.
+        lmcache_chunk_size: Chunk size of LMCache objects.
+        engine_kv_format: Engine KV cache format.
+        skip_prefix_n_blocks: Number of leading blocks to skip.
+
+    Returns:
+        None
+
+    Raises:
+        ValueError: Propagated from the Python fallback when inputs are invalid.
+        TypeError: Propagated from the Python fallback when input types are invalid.
+    """
+    # First Party
+    from lmcache.v1.platform.musa.native_kv_transfer import (
+        try_native_multi_layer_block_kv_transfer,
+    )
+
+    object_tensors = _tensor_list(lmcache_objects_ptrs)
+    if object_tensors is not None and try_native_multi_layer_block_kv_transfer(
+        paged_layers=paged_buffer_ptrs_tensor,
+        object_tensors=object_tensors,
+        block_ids=block_ids,
+        direction=direction,
+        shape_desc=shape_desc,
+        lmcache_chunk_size=lmcache_chunk_size,
+        engine_kv_format=engine_kv_format,
+        skip_prefix_n_blocks=skip_prefix_n_blocks,
+    ):
+        return
+
+    py_ops.multi_layer_block_kv_transfer(
+        paged_buffer_ptrs_tensor,
+        lmcache_objects_ptrs,
+        block_ids,
+        device,
+        direction,
+        shape_desc,
+        lmcache_chunk_size,
+        engine_kv_format,
+        skip_prefix_n_blocks,
+    )
diff --git a/lmcache/v1/platform/xpu/__init__.py b/lmcache/v1/platform/xpu/__init__.py
new file mode 100644
index 0000000..8edfee2
--- /dev/null
+++ b/lmcache/v1/platform/xpu/__init__.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+"""XPU (Intel SYCL) platform helpers."""
+
+# First Party
+from lmcache.v1.platform.base_device_spec import DeviceSpec
+
+# ---------------------------------------------------------------------------
+# Device detection registry entry
+# ---------------------------------------------------------------------------
+
+
+class XpuDeviceSpec(DeviceSpec):
+    """XPU device specification for the detection registry."""
+
+    @property
+    def device_type(self) -> str:
+        return "xpu"
+
+    @property
+    def torch_module_name(self) -> str:
+        return "xpu"
+
+    @property
+    def ops_module(self) -> str | None:
+        return "lmcache.xpu_ops"
+
+    def is_available(self) -> bool:
+        """Check XPU availability without importing lmcache.__init__."""
+        try:
+            # Third Party
+            import torch
+
+            return hasattr(torch, "xpu") and torch.xpu.is_available()
+        except Exception:
+            return False
diff --git a/lmcache/v1/plugin/__init__.py b/lmcache/v1/plugin/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/lmcache/v1/plugin/runtime_plugin_launcher.py b/lmcache/v1/plugin/runtime_plugin_launcher.py
new file mode 100644
index 0000000..5de212e
--- /dev/null
+++ b/lmcache/v1/plugin/runtime_plugin_launcher.py
@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+import atexit
+import os
+import shutil
+import subprocess
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class RuntimePluginLauncher:
+    def __init__(
+        self,
+        config,
+        role: str | None,
+        worker_count: int,
+        worker_id: int,
+    ):
+        self.config = config
+        self.role = role
+        self.worker_count = worker_count
+        self.worker_id = worker_id
+        self.plugin_processes: list[subprocess.Popen] = []
+        # Register cleanup handler
+        atexit.register(self.stop_plugins)
+
+    def launch_plugins(self):
+        """Launch all configured plugins"""
+        if not self.config.runtime_plugin_locations:
+            return
+
+        for loc in self.config.runtime_plugin_locations:
+            self._launch_plugins(loc)
+
+    def _launch_plugins(self, loc: str):
+        """Launch plugins from specified location"""
+        path = Path(loc)
+        if not path.exists():
+            logger.warning(f"Runtime plugin location {loc} does not exist")
+            return
+
+        files = []
+        if path.is_file():
+            files = [path]
+        elif path.is_dir():
+            # Recursively find all .py and .sh files
+            for ext in ["*.py", "*.sh"]:
+                files.extend(path.rglob(ext))
+
+        for file in files:
+            self._launch_plugin(file)
+
+    def _should_skip_plugin(self, file: Path, parts: list[str]) -> bool:
+        """Determine if plugin should be skipped based on role/worker ID.
+
+        The naming convention is ROLE_WORKERID_NAME (e.g. server_0_foo.py).
+        When role is None (MP mode), this convention does not apply,
+        so both role and worker ID filtering are skipped entirely.
+        """
+        if len(parts) < 2:
+            return False
+
+        # When role is None, skip all role/worker-based filtering
+        # (e.g. MP mode has no role concept)
+        if self.role is None:
+            return False
+
+        plugin_role = parts[0].upper()
+        if plugin_role != "ALL" and plugin_role != self.role.upper():
+            logger.info(
+                "Skipping %s: requires role %s",
+                file,
+                plugin_role,
+            )
+            return True
+
+        # Check worker ID match (parts[1] in ROLE_WORKERID_NAME)
+        if len(parts) > 2 and parts[1].isdigit():
+            plugin_worker_id = int(parts[1])
+            if plugin_worker_id != self.worker_id:
+                logger.info(
+                    "worker %d is skipping plugin %s, which is only for worker ID %d",
+                    self.worker_id,
+                    file,
+                    plugin_worker_id,
+                )
+                return True
+
+        return False
+
+    def _launch_plugin(self, file: Path):
+        """Launch a plugin"""
+        try:
+            filename = file.stem.lower()
+            parts = filename.split("_")
+
+            if self._should_skip_plugin(file, parts):
+                return
+
+            # Get interpreter from first line (shebang)
+            interpreter = self._get_interpreter(file)
+
+            # Pass role and config as environment variables
+            env = os.environ.copy()
+            role_str = self.role or ""
+            env["LMCACHE_RUNTIME_PLUGIN_ROLE"] = role_str
+            env["LMCACHE_RUNTIME_PLUGIN_CONFIG"] = self.config.to_json()
+            env["LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT"] = str(self.worker_count)
+            env["LMCACHE_RUNTIME_PLUGIN_WORKER_ID"] = str(self.worker_id)
+
+            # TODO: For backwards compatibility, remove when applicable
+            env["LMCACHE_PLUGIN_ROLE"] = role_str
+            env["LMCACHE_PLUGIN_CONFIG"] = self.config.to_json()
+            env["LMCACHE_PLUGIN_WORKER_COUNT"] = str(self.worker_count)
+            env["LMCACHE_PLUGIN_WORKER_ID"] = str(self.worker_id)
+
+            # Force line-buffered stdout for Python sub-processes
+            # so that output is captured in real-time rather than
+            # being held in the block buffer until exit.
+            env["PYTHONUNBUFFERED"] = "1"
+
+            proc = subprocess.Popen(
+                [interpreter, str(file)],
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+            )
+            self.plugin_processes.append(proc)
+            logger.info(f"Launched runtime plugin: {file} with {interpreter}")
+
+            # Start thread to capture output continuously
+            threading.Thread(
+                target=self._capture_plugin_output, args=(proc, str(file)), daemon=True
+            ).start()
+        except Exception as e:
+            logger.error(f"Failed to launch plugin {file}: {e}")
+
+    def _get_interpreter(self, file: Path) -> str:
+        """Get interpreter from first line comment"""
+        interpreters = []
+        try:
+            with open(file, "r", encoding="utf-8") as f:
+                first_line = f.readline().strip()
+                if first_line.startswith("#!"):
+                    # Extract interpreter
+                    interpreter_str = first_line[2:].strip()
+                    interpreters.append(interpreter_str)
+        except Exception as e:
+            logger.error(
+                f"Error reading interpreter from runtime plugin file {file} - "
+                f"using default interpreters: {e}"
+            )
+            pass
+
+        # Fallback to default interpreters
+        if file.suffix == ".py":
+            interpreters.append("python")
+            interpreters.append("python3")
+        elif file.suffix == ".sh":
+            interpreters.append("bash")
+        else:
+            raise ValueError(f"Plugin type {file.suffix} not supported ")
+
+        # Try each interpreter until we find one that exists
+        for interpreter in interpreters:
+            interpreter = interpreter.strip()
+            resolved_interpreter = shutil.which(interpreter)
+            if resolved_interpreter:
+                return resolved_interpreter
+
+        raise ValueError(f"No valid interpreter found for {file} from {interpreters}")
+
+    def _capture_plugin_output(self, proc: subprocess.Popen, plugin_name: str):
+        """Continuously capture and log plugin output"""
+        try:
+            assert proc.stdout is not None, (
+                "The runtime plugin subprocess does not have stdout"
+            )
+            while True:
+                line = proc.stdout.readline()
+                if not line:
+                    break
+                logger.info(f"[{plugin_name}] {line.strip()}")
+
+            proc.wait()
+            logger.info(
+                f"Runtime plugin {plugin_name} exited with code {proc.returncode}"
+            )
+        except Exception as e:
+            logger.error(f"Error capturing output for {plugin_name}: {e}")
+
+    def stop_plugins(self):
+        """Terminate all plugin processes.
+
+        Note: This method may be called via atexit during interpreter shutdown,
+        when the logging system may already be closed. We avoid using logger
+        here to prevent "I/O operation on closed file" errors.
+        """
+        for proc in self.plugin_processes:
+            try:
+                if proc.poll() is None:
+                    proc.terminate()
+            except Exception:
+                # Silently ignore errors during shutdown
+                pass
diff --git a/lmcache/v1/protocol.py b/lmcache/v1/protocol.py
new file mode 100644
index 0000000..d90cbcf
--- /dev/null
+++ b/lmcache/v1/protocol.py
@@ -0,0 +1,317 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from enum import IntEnum, auto
+from typing import Optional, Union
+import struct
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey, LayerCacheEngineKey, parse_cache_key
+from lmcache.v1.memory_management import MemoryFormat
+
+logger = init_logger(__name__)
+
+
+MAX_KEY_LENGTH = 150
+REMOTE_METADATA_FMT: Optional[str] = None
+REMOTE_METADATA_BYTES: Optional[int] = None
+
+
+class ClientCommand(IntEnum):
+    PUT = auto()
+    GET = auto()
+    EXIST = auto()
+    LIST = auto()
+    HEALTH = auto()
+
+
+class ServerReturnCode(IntEnum):
+    SUCCESS = 200
+    FAIL = 400
+
+
+DTYPE_TO_INT = {
+    None: 0,
+    torch.half: 1,
+    torch.float16: 2,
+    torch.bfloat16: 3,
+    torch.float: 4,
+    torch.float32: 4,
+    torch.float64: 5,
+    torch.double: 5,
+    torch.uint8: 6,
+    torch.float8_e4m3fn: 7,
+    torch.float8_e5m2: 8,
+}
+
+INT_TO_DTYPE = {
+    0: None,
+    1: torch.half,
+    2: torch.float16,
+    3: torch.bfloat16,
+    4: torch.float,
+    5: torch.float64,
+    6: torch.uint8,
+    7: torch.float8_e4m3fn,
+    8: torch.float8_e5m2,
+}
+
+# TODO (Jiayi): Add more backends
+LOCATION_TO_INT = {
+    None: 0,
+    "LocalCPUBackend": 1,
+    "LocalDiskBackend": 2,
+}
+
+INT_TO_LOCATION = {
+    0: None,
+    1: "LocalCPUBackend",
+    2: "LocalDiskBackend",
+}
+
+
+def init_remote_metadata_info(num_groups: int):
+    global REMOTE_METADATA_FMT
+    global REMOTE_METADATA_BYTES
+    # length, fmt, (dtype, shape0, shape1, shape2, shape3) * num_groups
+    fmt_length = 2 + 5 * num_groups
+    REMOTE_METADATA_FMT = "i" * fmt_length
+    REMOTE_METADATA_BYTES = 4 * fmt_length
+    logger.info(
+        "init remote metadata info with groups: %s, "
+        "remote metadata fmt: %s, remote metadata bytes: %s",
+        num_groups,
+        REMOTE_METADATA_FMT,
+        REMOTE_METADATA_BYTES,
+    )
+
+
+def get_remote_metadata_bytes():
+    global REMOTE_METADATA_BYTES
+    assert REMOTE_METADATA_BYTES is not None
+    return REMOTE_METADATA_BYTES
+
+
+def pad_shape_to_4d(shape: torch.Size) -> list[int]:
+    """Pad a shape with fewer than 4 dimensions to 4D using trailing
+    zeros.
+
+    Shapes that are already 4D are returned as-is.  For shapes with
+    fewer dimensions the missing trailing slots are filled with ``0``.
+    This is consistent with the convention used by
+    :class:`BinaryMemoryObj` (``[length, 0, 0, 0]``).
+
+    Args:
+        shape: The original tensor shape (1-D to 4-D).
+
+    Returns:
+        A list of exactly 4 integers representing the padded shape.
+
+    Raises:
+        AssertionError: If the shape has more than 4 dimensions.
+    """
+    assert len(shape) <= 4, (
+        f"Shape dimension must be <= 4 for serialization, got {len(shape)}"
+    )
+    if len(shape) == 4:
+        return list(shape)
+
+    padded = list(shape) + [0] * (4 - len(shape))
+    return padded
+
+
+def strip_shape_padding(
+    dims: list[int],
+    fmt: Optional[MemoryFormat] = MemoryFormat.UNDEFINED,
+) -> torch.Size:
+    """Strip trailing-zero padding that was added by
+    :func:`pad_shape_to_4d`.
+
+    Trailing zeros are removed so that the original dimensionality is
+    restored.  At least one dimension is always preserved.
+
+    For ``BINARY`` and ``BINARY_BUFFER`` formats, the shape is returned
+    as-is because these formats inherently use 4-D shapes with zero
+    padding (e.g., ``[length, 0, 0, 0]``).
+
+    Args:
+        dims: A list of 4 integers read from the serialized format.
+        fmt: The memory format of the serialized data.
+
+    Returns:
+        A :class:`torch.Size` with the padding removed.
+    """
+    if fmt in (MemoryFormat.BINARY, MemoryFormat.BINARY_BUFFER):
+        # These formats use 4D shapes with legitimate zero dimensions.
+        # Skip stripping to preserve the original shape.
+        return torch.Size(dims)
+
+    end = len(dims)
+    while end > 1 and dims[end - 1] == 0:
+        end -= 1
+    return torch.Size(dims[:end])
+
+
+@dataclass
+class RemoteMetadata:
+    length: int
+    shapes: list[torch.Size]
+    dtypes: list[torch.dtype]
+    fmt: MemoryFormat
+
+    def _prepare_params(self):
+        params = [self.length, int(self.fmt.value)]
+        for shape, dtype in zip(self.shapes, self.dtypes, strict=True):
+            padded = pad_shape_to_4d(shape)
+            params.append(DTYPE_TO_INT[dtype])
+            params.extend(padded)
+        return params
+
+    def serialize_into(self, buffer):
+        assert REMOTE_METADATA_FMT is not None
+        params = self._prepare_params()
+        struct.pack_into(REMOTE_METADATA_FMT, buffer, 0, *params)
+
+    def serialize(self) -> bytes:
+        assert REMOTE_METADATA_FMT is not None
+        params = self._prepare_params()
+        packed_bytes = struct.pack(REMOTE_METADATA_FMT, *params)
+        return packed_bytes
+
+    @staticmethod
+    def deserialize(s: bytes) -> "RemoteMetadata":
+        assert REMOTE_METADATA_FMT is not None
+        # length, fmt, (dtype, shape0, shape1, shape2, shape3) * num_groups
+        result = struct.unpack_from(REMOTE_METADATA_FMT, s)
+        length = result[0]
+        memory_fmt = MemoryFormat(result[1])
+        shapes = []
+        dtypes = []
+        for i in range(2, len(result), 5):
+            dims = list(result[i + 1 : i + 5])
+            shapes.append(strip_shape_padding(dims, memory_fmt))
+            dtypes.append(INT_TO_DTYPE[result[i]])
+
+        return RemoteMetadata(
+            length,
+            shapes,
+            dtypes,
+            memory_fmt,
+        )
+
+
+# TODO(Jiayi): Server and client message can be merged into one.
+
+
+@dataclass
+class ClientMetaMessage:
+    """
+    Request message from LMCache workers or servers.
+    """
+
+    command: ClientCommand
+    key: Union[CacheEngineKey, LayerCacheEngineKey]
+    length: int
+    fmt: MemoryFormat
+    dtype: Optional[torch.dtype]
+    shape: torch.Size
+    location: Optional[str] = None
+
+    def serialize(self) -> bytes:
+        key_str = self.key.to_string()
+        assert len(key_str) <= MAX_KEY_LENGTH, (
+            f"Key length {len(key_str)} exceeds maximum {MAX_KEY_LENGTH}"
+        )
+
+        # NOTE(Jiayi): 4 is the maximum dimension of memory object.
+        # Pass in shape [x, 0, 0, 0] if it is a bytes memory object
+        padded = pad_shape_to_4d(self.shape)
+
+        packed_bytes = struct.pack(
+            f"iiiiiiiii{MAX_KEY_LENGTH}s",
+            self.command.value,
+            self.length,
+            int(self.fmt.value),
+            DTYPE_TO_INT[self.dtype],
+            LOCATION_TO_INT[self.location],
+            padded[0],
+            padded[1],
+            padded[2],
+            padded[3],
+            key_str.encode().ljust(MAX_KEY_LENGTH),
+        )
+        return packed_bytes
+
+    @staticmethod
+    def deserialize(s: bytes) -> "ClientMetaMessage":
+        command, length, fmt, dtype, location, shape0, shape1, shape2, shape3, key = (
+            struct.unpack(f"iiiiiiiii{MAX_KEY_LENGTH}s", s)
+        )
+        shape = strip_shape_padding([shape0, shape1, shape2, shape3], MemoryFormat(fmt))
+        return ClientMetaMessage(
+            ClientCommand(command),
+            parse_cache_key(key.decode().strip()),
+            length,
+            MemoryFormat(fmt),
+            INT_TO_DTYPE[dtype],
+            shape,
+            INT_TO_LOCATION[location],
+        )
+
+    @staticmethod
+    def packlength() -> int:
+        # NOTE: 9 is the number of integers
+        return 4 * 9 + MAX_KEY_LENGTH
+
+
+@dataclass
+class ServerMetaMessage:
+    """
+    Reply message from LMCache workers or servers.
+    """
+
+    code: ServerReturnCode
+    length: int
+    fmt: MemoryFormat
+    dtype: Optional[torch.dtype]
+    shape: torch.Size
+    location: Optional[str] = None
+
+    def serialize(self) -> bytes:
+        padded = pad_shape_to_4d(self.shape)
+        packed_bytes = struct.pack(
+            "iiiiiiiii",
+            self.code.value,
+            self.length,
+            int(self.fmt.value),
+            DTYPE_TO_INT[self.dtype],
+            padded[0],
+            padded[1],
+            padded[2],
+            padded[3],
+            LOCATION_TO_INT[self.location],
+        )
+        return packed_bytes
+
+    @staticmethod
+    def packlength() -> int:
+        return 4 * 9
+
+    @staticmethod
+    def deserialize(s: bytes) -> "ServerMetaMessage":
+        code, length, fmt, dtype, shape0, shape1, shape2, shape3, location = (
+            struct.unpack("iiiiiiiii", s)
+        )
+        shape = strip_shape_padding([shape0, shape1, shape2, shape3], MemoryFormat(fmt))
+        return ServerMetaMessage(
+            ServerReturnCode(code),
+            length,
+            MemoryFormat(fmt),
+            INT_TO_DTYPE[dtype],
+            shape,
+            INT_TO_LOCATION[location],
+        )
diff --git a/lmcache/v1/rpc/__init__.py b/lmcache/v1/rpc/__init__.py
new file mode 100644
index 0000000..d00e9a9
--- /dev/null
+++ b/lmcache/v1/rpc/__init__.py
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.rpc.transport import (
+    RpcClientTransport,
+    RpcServerTransport,
+)
+from lmcache.v1.rpc.zmq_transport import (
+    ZmqReqRepClientTransport,
+    ZmqRouterServerTransport,
+)
+
+__all__ = [
+    "RpcClientTransport",
+    "RpcServerTransport",
+    "ZmqReqRepClientTransport",
+    "ZmqRouterServerTransport",
+]
diff --git a/lmcache/v1/rpc/transport.py b/lmcache/v1/rpc/transport.py
new file mode 100644
index 0000000..3057f97
--- /dev/null
+++ b/lmcache/v1/rpc/transport.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Abstract transport interfaces for RPC communication.
+
+These interfaces decouple the lookup client/server business logic
+from the underlying communication mechanism (e.g., ZMQ, gRPC).
+
+The transport layer is responsible for serialization/deserialization
+of structured data, so that upper-layer business logic only works
+with Python objects (no raw bytes).
+
+TODO: Implement async transport interfaces for
+LMCacheAsyncLookupClient/Server.
+"""
+
+# Standard
+from typing import Any
+import abc
+
+
+class RpcClientTransport(abc.ABC):
+    """Abstract transport for RPC client-side communication.
+
+    Handles sending requests to multiple server ranks and
+    collecting responses. The transport is responsible for
+    connection management, retries, and error recovery.
+    """
+
+    @abc.abstractmethod
+    def send_and_recv_all(
+        self,
+        msg: list[Any],
+    ) -> list[bytes]:
+        """Send structured data to all ranks and collect
+        responses.
+
+        The transport is responsible for serializing each
+        element of msg before sending and deserializing
+        responses.
+
+        Args:
+            msg: List of Python objects to send as
+                message frames. Each element will be
+                serialized by the transport's codec.
+
+        Returns:
+            List of raw response bytes, one per rank.
+
+        Raises:
+            RpcTransportError: If communication fails
+                after retries.
+        """
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def world_size(self) -> int:
+        """Return the number of server ranks."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close the transport and release resources."""
+        raise NotImplementedError
+
+
+class RpcServerTransport(abc.ABC):
+    """Abstract transport for RPC server-side communication.
+
+    Handles receiving requests and sending responses back.
+    """
+
+    @abc.abstractmethod
+    def recv_request(
+        self,
+    ) -> tuple[bytes, list[Any]] | None:
+        """Receive a request from a client.
+
+        The transport deserializes each data frame into
+        a Python object before returning.
+
+        Returns:
+            A tuple of (identity, data_frames) on success
+            where data_frames contains deserialized Python
+            objects, or None on timeout / no data available.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def send_response(
+        self,
+        identity: bytes,
+        response: bytes,
+    ) -> None:
+        """Send a response back to the client.
+
+        Args:
+            identity: The client identity from recv_request.
+            response: The raw response bytes to send.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """Close the transport and release resources."""
+        raise NotImplementedError
diff --git a/lmcache/v1/rpc/zmq_transport.py b/lmcache/v1/rpc/zmq_transport.py
new file mode 100644
index 0000000..3bfa650
--- /dev/null
+++ b/lmcache/v1/rpc/zmq_transport.py
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+"""ZMQ-based transport implementations for RPC communication.
+
+TODO: Implement ZmqPushTransport and ZmqPullTransport for
+LMCacheAsyncLookupClient/Server.
+"""
+
+# Standard
+from collections import namedtuple
+from typing import Any
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.rpc.transport import (
+    RpcClientTransport,
+    RpcServerTransport,
+)
+from lmcache.v1.rpc_utils import (
+    get_zmq_context,
+    get_zmq_socket,
+)
+
+logger = init_logger(__name__)
+
+SocketParams = namedtuple("SocketParams", ["socket_path", "rank"])
+
+
+class ZmqReqRepClientTransport(RpcClientTransport):
+    """ZMQ REQ socket transport for synchronous RPC clients.
+
+    Manages multiple REQ sockets (one per server rank) and
+    provides send/recv with timeout + automatic socket
+    recreation on failure.
+    """
+
+    def __init__(
+        self,
+        socket_params: list[SocketParams],
+        timeout_ms: int,
+    ):
+        self.ctx = get_zmq_context(use_asyncio=False)
+        self.socket_params = socket_params
+        self.timeout_ms = timeout_ms
+        self._world_size = len(socket_params)
+        self.encoder = msgspec.msgpack.Encoder()
+
+        self.sockets: list[zmq.Socket] = []
+        for params in self.socket_params:
+            logger.info(
+                "Transport connecting to rank %s with socket path %s",
+                params.rank,
+                params.socket_path,
+            )
+            socket = self._create_socket(params)
+            self.sockets.append(socket)
+
+    def _create_socket(self, params: SocketParams) -> zmq.Socket:
+        """Create and configure a REQ socket."""
+        socket = get_zmq_socket(
+            self.ctx,
+            params.socket_path,
+            "ipc",
+            zmq.REQ,
+            "connect",
+        )
+        socket.setsockopt(zmq.RCVTIMEO, self.timeout_ms)
+        socket.setsockopt(zmq.SNDTIMEO, self.timeout_ms)
+        return socket
+
+    def _recreate_all_sockets(self) -> None:
+        """Recreate all sockets after a failure."""
+        for rank_idx in range(self._world_size):
+            old_socket = self.sockets[rank_idx]
+            if old_socket is not None:
+                try:
+                    old_socket.close(linger=0)
+                except zmq.ZMQError as e:
+                    logger.warning(
+                        "ZMQ error closing old socket for rank %s: %s",
+                        rank_idx,
+                        e,
+                    )
+                except AttributeError:
+                    pass
+
+            params = self.socket_params[rank_idx]
+            logger.info(
+                "Recreating socket for rank %s with path %s",
+                params.rank,
+                params.socket_path,
+            )
+            self.sockets[rank_idx] = self._create_socket(params)
+
+    def send_and_recv_all(
+        self,
+        msg: list[Any],
+    ) -> list[bytes]:
+        """Send msg to all ranks and collect responses.
+
+        Each element of msg is serialized via msgpack before
+        sending. On timeout or ZMQ error, recreates all
+        sockets and returns an empty list.
+        """
+        encoded = [self.encoder.encode(m) for m in msg]
+        results: list[bytes] = []
+        failed_rank = -1
+        try:
+            for i in range(self._world_size):
+                failed_rank = i
+                self.sockets[i].send_multipart(encoded, copy=False)
+
+            for i in range(self._world_size):
+                failed_rank = i
+                resp = self.sockets[i].recv()
+                results.append(resp)
+        except zmq.Again as e:
+            logger.error(
+                "Timeout occurred for rank %s, recreating all sockets. Error: %s",
+                failed_rank,
+                e,
+            )
+            self._recreate_all_sockets()
+            return []
+        except zmq.ZMQError as e:
+            logger.error(
+                "ZMQ error for rank %s: %s, recreating all sockets",
+                failed_rank,
+                e,
+            )
+            self._recreate_all_sockets()
+            return []
+
+        return results
+
+    @property
+    def world_size(self) -> int:
+        return self._world_size
+
+    def close(self) -> None:
+        for socket in self.sockets:
+            try:
+                socket.close(linger=0)
+            except Exception as e:
+                logger.warning("Error closing socket: %s", e)
+        try:
+            if self.ctx:
+                self.ctx.term()
+        except Exception as e:
+            logger.warning("Error terminating ZMQ context: %s", e)
+
+
+class ZmqRouterServerTransport(RpcServerTransport):
+    """ZMQ ROUTER socket transport for synchronous RPC servers.
+
+    Listens for incoming requests and sends responses back
+    using ROUTER socket identity-based routing.
+    """
+
+    def __init__(
+        self,
+        socket_path: str,
+        recv_timeout_ms: int = 1000,
+    ):
+        self.decoder = msgspec.msgpack.Decoder()
+        self.ctx = zmq.Context()  # type: ignore[attr-defined]
+        self.socket = get_zmq_socket(
+            self.ctx,
+            socket_path,
+            "ipc",
+            zmq.ROUTER,  # type: ignore[attr-defined]
+            "bind",
+        )
+        self.socket.setsockopt(zmq.RCVTIMEO, recv_timeout_ms)
+        self.socket_path = socket_path
+
+    def recv_request(
+        self,
+    ) -> tuple[bytes, list[Any]] | None:
+        """Receive a request.
+
+        Returns (identity, data_frames) or None on timeout.
+        Each data frame is deserialized via msgpack.
+        ROUTER socket frames:
+          [0] = identity, [1] = empty delimiter, [2:] = data
+        """
+        try:
+            frames = self.socket.recv_multipart(copy=False)
+        except zmq.Again:
+            return None
+
+        identity = frames[0].bytes
+        # frames[1] is the empty delimiter from REQ socket
+        raw_frames = frames[2:]
+        if len(raw_frames) < 3:
+            logger.warning("Malformed request received: not enough frames.")
+            return None
+        data_frames = [self.decoder.decode(f) for f in raw_frames]
+        return (identity, data_frames)
+
+    def send_response(
+        self,
+        identity: bytes,
+        response: bytes,
+    ) -> None:
+        """Send response back via ROUTER socket."""
+        self.socket.send_multipart([identity, b"", response])
+
+    def close(self) -> None:
+        self.socket.close(linger=0)
diff --git a/lmcache/v1/rpc_utils.py b/lmcache/v1/rpc_utils.py
new file mode 100644
index 0000000..48b4d25
--- /dev/null
+++ b/lmcache/v1/rpc_utils.py
@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Literal, Optional
+import os
+import socket
+
+# Third Party
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+ServiceKind = Literal["lookup", "offload", "lookup_worker", "lookup_scheduler"]
+
+# Default timeout constants for socket operations (in milliseconds)
+DEFAULT_SOCKET_RECV_TIMEOUT_MS = 30000
+DEFAULT_SOCKET_SEND_TIMEOUT_MS = 10000
+
+
+def get_zmq_context(use_asyncio: bool = True):
+    if use_asyncio:
+        return zmq.asyncio.Context.instance()
+    else:
+        return zmq.Context.instance()
+
+
+def get_zmq_socket(
+    context, socket_path: str, protocol: str, role, bind_or_connect: str
+):
+    """
+    Create a ZeroMQ socket with the specified protocol and role.
+    """
+    socket_addr = f"{protocol}://{socket_path}"
+    socket = context.socket(role)
+    if bind_or_connect == "bind":
+        socket.bind(socket_addr)
+    elif bind_or_connect == "connect":
+        socket.connect(socket_addr)
+    else:
+        raise ValueError(f"Invalid bind_or_connect: {bind_or_connect}")
+
+    return socket
+
+
+def get_zmq_socket_with_timeout(
+    context,
+    socket_path: str,
+    protocol: str,
+    role,
+    bind_or_connect: str,
+    recv_timeout_ms: int,
+    send_timeout_ms: int,
+) -> zmq.asyncio.Socket:
+    """
+    Create a ZeroMQ socket with timeout settings.
+    """
+    socket = get_zmq_socket(
+        context,
+        socket_path,
+        protocol,
+        role,
+        bind_or_connect,
+    )
+    # Only set RCVTIMEO for client role connect sockets
+    if bind_or_connect == "connect":
+        socket.setsockopt(zmq.RCVTIMEO, recv_timeout_ms)
+    socket.setsockopt(zmq.SNDTIMEO, send_timeout_ms)
+    return socket
+
+
+def close_zmq_socket(socket: zmq.asyncio.Socket, linger: int = 0) -> None:
+    """
+    Close a ZeroMQ socket cleanly.
+
+    :param socket: The zmq.Socket to be closed.
+    :param linger: LINGER period (in milliseconds).
+    Default is 0 (drop immediately).
+    """
+    try:
+        socket.setsockopt(zmq.LINGER, linger)  # type: ignore[attr-defined]
+        socket.close()
+    except Exception as e:
+        logger.error("Warning: Failed to close socket cleanly: %s", e)
+
+
+def get_ip():
+    """
+    Get the local IP address of the machine.
+    """
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        # "Connect" to a public IP — just to determine local IP
+        s.connect(("8.8.8.8", 80))
+        return s.getsockname()[0]
+    except Exception:
+        logger.warning(
+            "Failed to get local IP address. Falling back to loopback address."
+        )
+        return "127.0.0.1"  # Fallback to loopback
+    finally:
+        s.close()
+
+
+def get_zmq_rpc_path_lmcache(
+    engine_id: str,
+    service_name: ServiceKind = "lookup",
+    rpc_port: int = 0,
+    rank: int = 0,
+    base_url: Optional[str] = None,
+) -> str:
+    """Get the ZMQ RPC path for LMCache lookup and offload communication.
+
+    Args:
+        engine_id: The engine ID for the RPC path.
+        service_name: The service name, one of 'lookup', 'offload',
+            'lookup_worker', 'lookup_scheduler'.
+        rpc_port: The RPC port number.
+        rank: The rank of the worker.
+        base_url: Optional base URL for the socket path. If not provided,
+            will try to use VLLM_RPC_BASE_PATH or fallback to /tmp/vllm_rpc.
+
+    Returns:
+        The ZMQ socket path string.
+    """
+    if base_url is None:
+        # Try to import vllm.envs, fallback to default if not available
+        try:
+            # Third Party
+            import vllm.envs as envs
+
+            base_url = envs.VLLM_RPC_BASE_PATH
+        except (ImportError, ModuleNotFoundError):
+            # Fallback for testing environments without vllm
+            base_url = "/tmp/vllm_rpc"
+            logger.debug("vllm not available, using default base_url: %s", base_url)
+            # Ensure the directory exists for IPC socket
+            os.makedirs(base_url, exist_ok=True)
+
+    if service_name not in {"lookup", "offload", "lookup_worker", "lookup_scheduler"}:
+        raise ValueError(
+            f"service_name must be 'lookup' or 'offload', got {service_name!r}"
+        )
+
+    if isinstance(rpc_port, str):
+        rpc_port = rpc_port + str(rank)
+    else:
+        rpc_port += rank
+
+    logger.debug(
+        "Base URL: %s, Engine: %s, Service Name: %s, RPC Port: %s",
+        base_url,
+        engine_id,
+        service_name,
+        rpc_port,
+    )
+
+    socket_path = (
+        f"{base_url}/engine_{engine_id}_service_{service_name}_"
+        f"lmcache_rpc_port_{rpc_port}"
+    )
+
+    return socket_path
diff --git a/lmcache/v1/server/__init__.py b/lmcache/v1/server/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/lmcache/v1/server/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/lmcache/v1/server/__main__.py b/lmcache/v1/server/__main__.py
new file mode 100644
index 0000000..030ae8c
--- /dev/null
+++ b/lmcache/v1/server/__main__.py
@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import socket
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.protocol import (
+    ClientCommand,
+    ClientMetaMessage,
+    ServerMetaMessage,
+    ServerReturnCode,
+)
+from lmcache.v1.server.storage_backend import CreateStorageBackend
+
+logger = init_logger(__name__)
+
+
+class LMCacheServer:
+    def __init__(self, host, port, device):
+        self.host = host
+        self.port = port
+        # self.data_store = {}
+        self.data_store = CreateStorageBackend(device)
+        self.server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.server_socket.bind((host, port))
+        self.server_socket.listen()
+
+    def receive_all(self, client_socket, n):
+        data = bytearray()
+        while len(data) < n:
+            packet = client_socket.recv(n - len(data))
+            if not packet:
+                return None
+            data.extend(packet)
+        return data
+
+    def handle_client(self, client_socket):
+        try:
+            while True:
+                logger.debug("Waiting for command")
+                header = self.receive_all(client_socket, ClientMetaMessage.packlength())
+                if not header:
+                    break
+                meta = ClientMetaMessage.deserialize(header)
+                logger.debug(f"Received command: {meta.command}")
+                match meta.command:
+                    case ClientCommand.PUT:
+                        t0 = time.perf_counter()
+                        s = self.receive_all(client_socket, meta.length)
+                        t1 = time.perf_counter()
+                        self.data_store.put(meta, s)
+                        t2 = time.perf_counter()
+                        logger.debug(
+                            f"Time to receive data: {t1 - t0}, time to store "
+                            f"data: {t2 - t1}"
+                        )
+
+                    case ClientCommand.GET:
+                        t0 = time.perf_counter()
+                        lms_memory_obj = self.data_store.get(meta.key)
+                        t1 = time.perf_counter()
+                        if lms_memory_obj is not None:
+                            client_socket.sendall(
+                                ServerMetaMessage(
+                                    ServerReturnCode.SUCCESS,
+                                    lms_memory_obj.length,
+                                    lms_memory_obj.fmt,
+                                    lms_memory_obj.dtype,
+                                    lms_memory_obj.shape,
+                                ).serialize()
+                            )
+                            t2 = time.perf_counter()
+                            client_socket.sendall(lms_memory_obj.data)
+                            t3 = time.perf_counter()
+                            logger.debug(
+                                f"Time to get data: {t1 - t0}, time to send "
+                                f"meta: {t2 - t1}, time to send data: {t3 - t2}"
+                            )
+                        else:
+                            client_socket.sendall(
+                                ServerMetaMessage(
+                                    ServerReturnCode.FAIL,
+                                    0,
+                                    MemoryFormat(1),
+                                    torch.float16,
+                                    torch.Size((0, 0, 0, 0)),
+                                ).serialize()
+                            )
+
+                    case ClientCommand.EXIST:
+                        code = (
+                            ServerReturnCode.SUCCESS
+                            if self.data_store.contains(meta.key)
+                            else ServerReturnCode.FAIL
+                        )
+                        logger.debug(f"Key exists: {code}")
+                        client_socket.sendall(
+                            ServerMetaMessage(
+                                code,
+                                0,
+                                MemoryFormat(1),
+                                torch.float16,
+                                torch.Size((0, 0, 0, 0)),
+                            ).serialize()
+                        )
+                    case ClientCommand.HEALTH:
+                        client_socket.sendall(
+                            ServerMetaMessage(
+                                ServerReturnCode.SUCCESS,
+                                0,
+                                MemoryFormat(1),
+                                torch.float16,
+                                torch.Size((0, 0, 0, 0)),
+                            ).serialize()
+                        )
+                        logger.debug("Health check successful")
+
+                    # TODO(Jiayi): Implement List
+                    # case ClientCommand.LIST:
+                    #     keys = list(self.data_store.list_keys())
+                    #     data = "\n".join(keys).encode()
+                    #     client_socket.sendall(
+                    #         ServerMetaMessage(ServerReturnCode.SUCCESS,
+                    #                           len(data)).serialize())
+                    #     client_socket.sendall(data)
+
+        finally:
+            logger.info("Client disconnected")
+            client_socket.close()
+
+    def run(self):
+        logger.info(f"Server started at {self.host}:{self.port}")
+        try:
+            while True:
+                client_socket, addr = self.server_socket.accept()
+                logger.info(f"Connected by {addr}")
+                threading.Thread(
+                    target=self.handle_client, args=(client_socket,)
+                ).start()
+        finally:
+            self.server_socket.close()
+
+
+def main():
+    # Standard
+    import sys
+
+    if len(sys.argv) not in [3, 4]:
+        logger.error(f"Usage: {sys.argv[0]} <host> <port> <storage>(default:cpu)")
+        exit(1)
+
+    host = sys.argv[1]
+    port = int(sys.argv[2])
+    if len(sys.argv) == 4:
+        device = sys.argv[3]
+    else:
+        device = "cpu"
+
+    server = LMCacheServer(host, port, device)
+    server.run()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/v1/server/storage_backend/__init__.py b/lmcache/v1/server/storage_backend/__init__.py
new file mode 100644
index 0000000..10613bf
--- /dev/null
+++ b/lmcache/v1/server/storage_backend/__init__.py
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.server.storage_backend.abstract_backend import LMSBackendInterface
+from lmcache.v1.server.storage_backend.local_backend import LMSLocalBackend
+
+logger = init_logger(__name__)
+
+
+def CreateStorageBackend(device: str) -> LMSBackendInterface:
+    match device:
+        case "cpu":
+            # cpu only
+            logger.info("Initializing cpu-only cache server")
+            return LMSLocalBackend()
+        case _:
+            raise ValueError(f"Unsupported device: {device}")
+        # TODO(Jiayi): please implement hierarchical remote storage
+        # case _:
+        #    logger.info("Initializing disk-only cache server")
+        #    return LMSLocalDiskBackend(path=device)
diff --git a/lmcache/v1/server/storage_backend/abstract_backend.py b/lmcache/v1/server/storage_backend/abstract_backend.py
new file mode 100644
index 0000000..f82371b
--- /dev/null
+++ b/lmcache/v1/server/storage_backend/abstract_backend.py
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional
+import abc
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.protocol import ClientMetaMessage
+from lmcache.v1.server.utils import LMSMemoryObj
+
+logger = init_logger(__name__)
+
+
+class LMSBackendInterface(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def put(
+        self,
+        client_meta: ClientMetaMessage,
+        kv_chunk_bytes: bytearray,
+    ) -> None:
+        """
+        Store the KV cache of the tokens into the cache server.
+
+        Args:
+            key: the key of the token chunk, in the format of CacheEngineKey
+            client_meta: metadata sent by the client
+            kv_chunk_bytes: the kv cache (bytearray) of the token chunk
+
+        Returns:
+            None
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def contains(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        """
+        Query if a key is in the cache or not
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[LMSMemoryObj]:
+        """
+        Retrieve LMSMemoryObj by the given key
+
+        Input:
+            key: the CacheEngineKey
+
+        Output:
+            An LMSMemoryObj object that contains the KV cache bytearray
+            with the some metadata
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def list_keys(
+        self,
+    ) -> List[CacheEngineKey]:
+        """
+        List all keys in the cache server
+
+        Output:
+            All keys in the cache server
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self):
+        """
+        Do the cleanup things
+        Children classes should override this method if necessary
+        """
+        pass
diff --git a/lmcache/v1/server/storage_backend/local_backend.py b/lmcache/v1/server/storage_backend/local_backend.py
new file mode 100644
index 0000000..9c552ae
--- /dev/null
+++ b/lmcache/v1/server/storage_backend/local_backend.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from typing import List, Optional
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey, _lmcache_nvtx_annotate
+from lmcache.v1.protocol import ClientMetaMessage
+from lmcache.v1.server.storage_backend.abstract_backend import LMSBackendInterface
+from lmcache.v1.server.utils import LMSMemoryObj
+
+logger = init_logger(__name__)
+
+
+class LMSLocalBackend(LMSBackendInterface):
+    def __init__(
+        self,
+    ) -> None:
+        self.dict: OrderedDict[CacheEngineKey, LMSMemoryObj] = OrderedDict()
+
+        self.lock = threading.Lock()
+
+        # TODO(Jiayi): please add evictor
+
+    # TODO
+    def list_keys(self) -> List[CacheEngineKey]:
+        with self.lock:
+            return list(self.dict.keys())
+
+    def contains(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        with self.lock:
+            return key in self.dict
+
+    # TODO
+    def remove(
+        self,
+        key: CacheEngineKey,
+    ) -> None:
+        with self.lock:
+            self.dict.pop(key)
+
+    def put(
+        self,
+        client_meta: ClientMetaMessage,
+        kv_chunk_bytes: bytearray,
+    ) -> None:
+        with self.lock:
+            self.dict[client_meta.key] = LMSMemoryObj(
+                kv_chunk_bytes,
+                client_meta.length,
+                client_meta.fmt,
+                client_meta.dtype,
+                client_meta.shape,
+            )
+
+    @_lmcache_nvtx_annotate
+    def get(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[LMSMemoryObj]:
+        with self.lock:
+            return self.dict.get(key, None)
+
+    def close(self):
+        pass
+
+
+# TODO(Jiayi): please implement the remote disk backend
+# class LMSLocalDiskBackend(LMSBackendInterface):
+#    pass
diff --git a/lmcache/v1/server/utils.py b/lmcache/v1/server/utils.py
new file mode 100644
index 0000000..349ba34
--- /dev/null
+++ b/lmcache/v1/server/utils.py
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.memory_management import MemoryFormat
+
+
+# TODO(Jiayi): Maybe move the memory management in remote
+# cache server to `memory_management.py` as well.
+@dataclass
+class LMSMemoryObj:
+    data: bytearray
+    length: int
+    fmt: MemoryFormat
+    dtype: Optional[torch.dtype]
+    shape: torch.Size
diff --git a/lmcache/v1/standalone/__init__.py b/lmcache/v1/standalone/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/standalone/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/standalone/__main__.py b/lmcache/v1/standalone/__main__.py
new file mode 100644
index 0000000..ff5cc53
--- /dev/null
+++ b/lmcache/v1/standalone/__main__.py
@@ -0,0 +1,584 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+LMCache Standalone Starter
+
+A standalone starter for LMCacheEngine that:
+- Loads configuration from YAML file or environment variables
+- Supports command-line parameter overrides
+- Starts a real LMCacheEngine instance
+- Works without vLLM or GPU
+- Supports all backend types (CPU, Disk, P2P, Remote, etc.)
+- Optionally starts internal API server for remote access
+"""
+
+# Standard
+from typing import Any, Dict, List, Optional, Tuple
+import argparse
+import ast
+import asyncio
+import os
+import signal
+import sys
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import get_size_bytes, lmcache_get_or_create_config
+from lmcache.logging import init_logger
+from lmcache.utils import EngineType, mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.config_base import parse_command_line_extra_params
+from lmcache.v1.gpu_connector import CreateGPUConnector
+from lmcache.v1.kv_layer_groups import DEFAULT_LAYER_NAME_PREFIX
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.standalone.manager import StandaloneLMCacheManager
+
+# Third Party - Platform detection
+try:
+    # Third Party
+    from vllm.platforms import current_platform
+except ImportError:
+    # Fallback for when vLLM is not available
+    current_platform = None
+
+logger = init_logger(__name__)
+
+dtype_map = {
+    "float16": torch.float16,
+    "float32": torch.float32,
+    "bfloat16": torch.bfloat16,
+    "uint8": torch.uint8,
+}
+
+
+class LayerGroupSpec:
+    """Specification for a layer group with KV shape and dtype
+
+    Attributes:
+        layer_count: Number of layers in this group
+        shape: Shape as tuple of integers
+         may be (num_layers, kv_dim, num_blocks, num_heads, head_size)
+        dtype: Data type for this layer group
+    """
+
+    def __init__(
+        self,
+        layer_count: int,
+        shape: Tuple[int, ...],
+        dtype: torch.dtype,
+    ):
+        self.layer_count = layer_count
+        # May be (num_layers, kv_dim, num_blocks, num_heads, head_size)
+        self.shape = shape
+        self.dtype = dtype
+
+    def __repr__(self) -> str:
+        return f"LayerGroupSpec({self.shape}):{self.dtype}:{self.layer_count}"
+
+
+def parse_kvcache_shape_spec(spec_str: str) -> List[LayerGroupSpec]:
+    """Parse KV shape specification with multiple layer groups.
+
+    Format examples:
+    - "(2,2,256,4,16):float16:2" (single group)
+    - "(2,2,256,4,16):float16:2;(3,2,256,4,4):bfloat16:2" (two groups)
+
+    Note: The shape string (inside parentheses) is not parsed and kept as string
+    to support different Attention implementations with varying shapes.
+
+    Returns a list of LayerGroupSpec objects.
+    """
+    if not spec_str:
+        raise ValueError("KV shape specification cannot be empty")
+
+    groups = []
+
+    # Split by semicolon to get individual group specifications
+    group_specs = spec_str.split(";")
+
+    for group_spec in group_specs:
+        group_spec = group_spec.strip()
+        if not group_spec:
+            continue
+
+        # Parse format: (shape_string):dtype:layer_count
+        if not (group_spec.startswith("(") and "):" in group_spec):
+            raise ValueError(f"Invalid group specification format: {group_spec}")
+
+        # Extract shape string inside parentheses and parse it
+        shape_end = group_spec.find(")")
+        shape_str = group_spec[1:shape_end]
+
+        # Extract dtype and layer_count after the shape
+        remaining = group_spec[shape_end + 2 :]  # Skip "):"
+        parts = remaining.split(":")
+
+        if len(parts) != 2:
+            raise ValueError(f"Invalid group specification format: {group_spec}")
+
+        dtype_str = parts[0].strip()
+        layer_count_str = parts[1].strip()
+
+        try:
+            # Parse shape tuple - support arbitrary dimensions
+            shape_parts = shape_str.split(",")
+            shape = tuple(int(part.strip()) for part in shape_parts)
+            layer_count = int(layer_count_str)
+            dtype = dtype_map.get(dtype_str.strip().lower(), torch.float16)
+
+            # Create LayerGroupSpec with parsed shape
+            groups.append(LayerGroupSpec(layer_count, shape, dtype))
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid number format in group specification: {group_spec}"
+            ) from e
+
+    if not groups:
+        raise ValueError("No valid layer groups found in specification")
+
+    return groups
+
+
+def calculate_composite_kv_cache_shape(
+    layer_groups: List[LayerGroupSpec],
+) -> Tuple[int, int, int, int, int]:
+    """Calculate composite KV cache shape from multiple layer groups.
+
+    Returns a shape that represents the KV cache structure:
+    - num_layers: sum of all layer counts
+    - kv_dim: from first group's shape (assumed consistent)
+    - num_blocks: from first group's shape (assumed consistent)
+    - num_heads: maximum num_heads across groups
+    - head_size: maximum head_size across groups
+
+    Note: This returns the KV cache shape, where the third dimension is num_blocks.
+    For metadata KV shape, the third dimension should be chunk_size instead.
+    """
+    if not layer_groups:
+        raise ValueError("No layer groups provided")
+
+    # Get base dimensions from first group's shape
+    first_shape = layer_groups[0].shape
+    base_num_layers, base_kv_dim, base_num_blocks, base_num_heads, base_head_size = (
+        first_shape
+    )
+
+    total_layers = sum(group.layer_count for group in layer_groups)
+
+    # Find maximum num_heads and head_size across all groups
+    max_num_heads = base_num_heads
+    max_head_size = base_head_size
+
+    for group in layer_groups[1:]:
+        shape = group.shape
+        num_heads = shape[3]
+        head_size = shape[4]
+        max_num_heads = max(max_num_heads, num_heads)
+        max_head_size = max(max_head_size, head_size)
+
+    return (total_layers, base_kv_dim, base_num_blocks, max_num_heads, max_head_size)
+
+
+def get_composite_kv_dtype(layer_groups: List[LayerGroupSpec]) -> torch.dtype:
+    """Get a representative dtype for composite KV cache.
+
+    Returns the dtype of the first layer group for compatibility.
+    """
+    if not layer_groups:
+        raise ValueError("No layer groups provided")
+    return layer_groups[0].dtype
+
+
+class LMCacheStandaloneStarter:
+    """Standalone starter for LMCacheEngine"""
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        layer_groups: List[LayerGroupSpec],
+        device: str = "cpu",
+    ):
+        self.config = config
+        self.metadata = metadata
+        self.layer_groups = layer_groups
+        self.device = device
+
+        gpu_connector = CreateGPUConnector(config, metadata, EngineType.MOCK)
+
+        # Create standalone manager directly
+        self._manager = StandaloneLMCacheManager(
+            config=config,
+            metadata=metadata,
+            gpu_connector=gpu_connector,
+            broadcast_fn=mock_up_broadcast_fn,
+            broadcast_object_fn=mock_up_broadcast_object_fn,
+            connector=self,
+        )
+
+        self.running = False
+
+    @property
+    def lmcache_engine(self) -> LMCacheEngine:
+        """Get the LMCache engine instance."""
+        # Directly access engine from standalone manager
+        engine = self._manager.lmcache_engine
+        assert engine is not None, "LMCache engine not initialized yet"
+        return engine
+
+    @property
+    def api_server(self):
+        """Get the API server instance."""
+        return self._manager.api_server
+
+    def _generate_fixed_kvcaches(self, device: str = "cpu") -> dict:
+        """Generate fixed pattern kvcaches for testing and MD5 verification.
+
+        Supports both single group and multiple layer groups.
+
+        Args:
+            device: Device to create tensors on (default: "cpu")
+        """
+        return self._generate_multi_group_kvcaches(device=device)
+
+    def _generate_multi_group_kvcaches(self, device: str = "cpu") -> dict:
+        """Generate kvcaches for multiple layer groups configuration
+
+        Args:
+            device: Device to create tensors on (default: "cpu")
+        """
+        if not self.layer_groups:
+            raise ValueError("No layer groups specified for multi-group generation")
+
+        kvcaches = {}
+        current_layer = 0
+
+        for group_idx, group in enumerate(self.layer_groups):
+            # group.shape is already the final tensor shape
+            tensor_shape = list(group.shape)
+
+            for layer_in_group in range(group.layer_count):
+                layer_idx = current_layer + layer_in_group
+                torch.manual_seed(42 + layer_idx)
+                tensor = torch.rand(tensor_shape, dtype=group.dtype, device=device)
+                layer_name = f"{DEFAULT_LAYER_NAME_PREFIX}{layer_idx}"
+                kvcaches[layer_name] = tensor
+
+            current_layer += group.layer_count
+            logger.info(
+                "Generated layer group %d: %d layers, shape=%s, dtype=%s, device=%s",
+                group_idx,
+                group.layer_count,
+                tensor_shape,
+                group.dtype,
+                device,
+            )
+
+        total_layers = current_layer
+        logger.info(
+            "Generated multi-group kvcaches: %d total layers across %d groups, "
+            "device=%s",
+            total_layers,
+            len(self.layer_groups),
+            device,
+        )
+        return kvcaches
+
+    def start(self) -> LMCacheEngine:
+        """Start the LMCache engine"""
+        logger.info("=" * 80)
+        logger.info("Starting LMCache Standalone Engine")
+        logger.info("=" * 80)
+
+        logger.info("Configuration: %s", self.config)
+        logger.info("Metadata: %s", self.metadata)
+
+        if self.layer_groups:
+            logger.info("Layer groups: %s", self.layer_groups)
+
+        # Calculate and log chunk storage size
+        chunk_size = self.config.chunk_size
+        num_layers, kv_dim, _, num_heads, head_size = self.metadata.kv_shape
+        chunk_shape = torch.Size([num_layers, kv_dim, chunk_size, num_heads, head_size])
+        chunk_storage_bytes = get_size_bytes([chunk_shape], [self.metadata.kv_dtype])
+        chunk_storage_mb = chunk_storage_bytes / (1024 * 1024)
+        logger.info(
+            "Chunk storage size: %d bytes (%.2f MB) for chunk_size=%d",
+            chunk_storage_bytes,
+            chunk_storage_mb,
+            chunk_size,
+        )
+
+        instance_id = self.config.lmcache_instance_id
+        logger.info("Starting LMCache engine with instance ID: %s", instance_id)
+
+        # Generate fixed pattern kvcaches for testing
+        kv_caches = self._generate_fixed_kvcaches(device=self.device)
+        self.kv_caches = kv_caches
+
+        # Post-initialize with kvcaches and start API server
+        self._manager.post_init()
+        logger.info("LMCache engine post-initialized with fixed kvcaches")
+
+        self._manager.start_services()
+
+        self.running = True
+        logger.info("LMCache engine started successfully")
+        return self.lmcache_engine
+
+    def stop(self):
+        """Stop the LMCache engine"""
+        if not self.running:
+            return
+
+        logger.info("Stopping LMCache engine...")
+        self.running = False
+
+        self._manager.stop_services()
+
+        logger.info("LMCache engine stopped")
+
+    async def run_forever(self):
+        """Keep the engine running"""
+        logger.info("=" * 80)
+        logger.info("LMCache engine is running")
+        logger.info("Press Ctrl+C to stop")
+        logger.info("=" * 80)
+
+        try:
+            while self.running:
+                await asyncio.sleep(1)
+        except KeyboardInterrupt:
+            logger.info("Received interrupt signal")
+        finally:
+            self.stop()
+
+
+def load_config(config_file: Optional[str] = None) -> LMCacheEngineConfig:
+    """Load configuration from file or environment"""
+    config_file = config_file or os.getenv("LMCACHE_CONFIG_FILE")
+
+    if config_file:
+        logger.info(f"Loading configuration from file: {config_file}")
+        config = LMCacheEngineConfig.from_file(config_file)
+    else:
+        logger.info("No config file specified, loading from environment variables")
+        config = LMCacheEngineConfig.from_env()
+
+    config.validate()
+    config.log_config()
+
+    return config
+
+
+def override_config_from_dict(config: LMCacheEngineConfig, overrides: Dict[str, Any]):
+    """Override configuration with dictionary"""
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            old_value = getattr(config, key)
+            if key == "extra_config":
+                # convert to dict
+                value = ast.literal_eval(value)
+                setattr(config, key, value)
+            else:
+                setattr(config, key, value)
+            if old_value != value:
+                logger.info(f"Override config: {key} = {value} (was {old_value})")
+        else:
+            logger.warning(f"Unknown config key: {key}, ignoring")
+
+
+def parse_kv_shape(shape_str: str) -> Tuple[int, int, int, int, int]:
+    """Parse KV shape from string like '32,2,256,32,128'"""
+    try:
+        parts = tuple(int(x.strip()) for x in shape_str.split(","))
+        if len(parts) != 5:
+            raise ValueError(
+                f"kv_shape must have exactly 5 dimensions, got {len(parts)}"
+            )
+        return parts  # type: ignore[return-value]
+    except ValueError as e:
+        raise ValueError(f"Invalid kv_shape format: {shape_str}. Error: {e}") from e
+
+
+def setup_signal_handlers(starter: LMCacheStandaloneStarter):
+    """Setup signal handlers for graceful shutdown"""
+
+    def signal_handler(signum, frame):
+        logger.info(f"Received signal {signum}")
+        starter.stop()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command-line arguments"""
+    parser = argparse.ArgumentParser(
+        description="LMCache Standalone Starter",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    parser.add_argument(
+        "--config",
+        type=str,
+        help="Path to LMCache configuration file",
+    )
+    parser.add_argument(
+        "--model-name",
+        type=str,
+        default="standalone_model",
+        help="Model name for cache identification",
+    )
+    parser.add_argument(
+        "--worker-id",
+        type=int,
+        default=0,
+        help="Worker ID for distributed setup",
+    )
+    parser.add_argument(
+        "--world-size",
+        type=int,
+        default=1,
+        help="Total number of workers",
+    )
+    parser.add_argument(
+        "--kv-dtype",
+        type=str,
+        choices=["float16", "float32", "bfloat16", "uint8"],
+        default="float16",
+        help="KV cache data type",
+    )
+    parser.add_argument(
+        "--kv-shape",
+        type=str,
+        default="2,2,256,4,16",
+        help=(
+            "KV cache shape as comma-separated integers "
+            "(num_layer, 2 or 1, chunk_size, num_kv_head, head_size). "
+            "num_layers: number of transformer layers, "
+            "kv_dim: dimension for K/V (usually 2), "
+            "chunk_size: number of memory chunks, "
+            "num_heads: number of attention heads, "
+            "head_size: size of each attention head. "
+            "Example: '2,2,256,4,16' means 2 layers, 2 for K/V, "
+            "256 chunks, 4 heads, 16 head size"
+        ),
+    )
+    parser.add_argument(
+        "--kvcache-shape-spec",
+        type=str,
+        default="(2,2,256,4,16):float16:2",
+        help=(
+            "KV cache shape specification with multiple layer groups. "
+            "Format: '(shape_string):dtype:layer_count;[...]'. "
+            "shape_string: comma-separated shape (e.g., '2,2,256,4,16'). "
+            "Examples: '(2,2,256,4,16):float16:2' (single group), "
+            "'(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3' (two groups)"
+        ),
+    )
+    parser.add_argument(
+        "--use-mla",
+        action="store_true",
+        help="Enable MLA (Multi-Level Attention)",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cpu",
+        help="Device to run on (default: cpu)",
+    )
+
+    args, extra = parser.parse_known_args()
+    args.extra_params = parse_command_line_extra_params(extra)
+
+    return args
+
+
+def main():
+    """Main entry point"""
+    args = parse_args()
+
+    logger.info("=" * 80)
+    logger.info("LMCache Standalone Starter")
+    logger.info("=" * 80)
+
+    try:
+        config_path = args.config
+        if config_path:
+            logger.info("Loading LMCache config file: %s", config_path)
+            config = LMCacheEngineConfig.from_file(config_path)
+            # Allow environment variables to override file settings
+            config.update_config_from_env()
+        else:
+            logger.info("No config file specified, loading from environment variables.")
+            config = lmcache_get_or_create_config()
+        # Override with any extra command-line parameters
+        if args.extra_params:
+            override_config_from_dict(config, args.extra_params)
+
+        # Handle KV shape specification
+        if not args.kvcache_shape_spec:
+            logger.error("--kvcache-shape-spec is required")
+            sys.exit(1)
+        else:
+            # Use new multi-group specification
+            layer_groups = parse_kvcache_shape_spec(args.kvcache_shape_spec)
+            logger.info("Using KV shape specification: %s", args.kvcache_shape_spec)
+            for i, group in enumerate(layer_groups):
+                logger.info(
+                    "  Group %d: %d layers, shape=%s, dtype=%s",
+                    i,
+                    group.layer_count,
+                    group.shape,
+                    group.dtype,
+                )
+
+        # Use single group specification - kv-shape directly assigned to metadata
+        kv_dtype = dtype_map.get(args.kv_dtype, torch.float16)
+        kv_shape = parse_kv_shape(args.kv_shape)
+
+        logger.info("Using KV shape: %s", kv_shape)
+        logger.info(
+            "  num_layers=%d, kv_dim=%d, num_blocks=%d, num_heads=%d, head_size=%d",
+            kv_shape[0],
+            kv_shape[1],
+            kv_shape[2],
+            kv_shape[3],
+            kv_shape[4],
+        )
+
+        metadata = LMCacheMetadata(
+            model_name=args.model_name,
+            world_size=args.world_size,
+            local_world_size=args.world_size,
+            worker_id=args.worker_id,
+            local_worker_id=args.worker_id,
+            kv_dtype=kv_dtype,
+            kv_shape=kv_shape,
+            use_mla=args.use_mla,
+            role="worker",
+        )
+
+        starter = LMCacheStandaloneStarter(config, metadata, layer_groups, args.device)
+        setup_signal_handlers(starter)
+
+        starter.start()
+        asyncio.run(starter.run_forever())
+
+    except KeyboardInterrupt:
+        logger.info("Interrupted by user")
+    except Exception as e:
+        logger.error(f"Fatal error: {e}", exc_info=True)
+        sys.exit(1)
+
+    logger.info("=" * 80)
+    logger.info("LMCache Standalone Starter stopped")
+    logger.info("=" * 80)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/lmcache/v1/standalone/manager.py b/lmcache/v1/standalone/manager.py
new file mode 100644
index 0000000..805ddce
--- /dev/null
+++ b/lmcache/v1/standalone/manager.py
@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+StandaloneLMCacheManager: A specialized manager for LMCache standalone mode.
+
+Uses a StandaloneServiceFactory to handle standalone mode specifically,
+removing vLLM dependencies and simplifying the initialization logic.
+"""
+
+# Standard
+from typing import Any, Callable, Optional
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.manager import LMCacheManager
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.standalone.standalone_service_factory import StandaloneServiceFactory
+
+logger = init_logger(__name__)
+
+
+class StandaloneLMCacheManager(LMCacheManager):
+    """
+    LMCacheManager specialized for standalone mode.
+
+    Uses StandaloneServiceFactory to create components without
+    vLLM dependencies.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        gpu_connector: Any,
+        broadcast_fn: Callable,
+        broadcast_object_fn: Callable,
+        connector: Optional[Any] = None,
+    ):
+        """
+        Initialize StandaloneLMCacheManager.
+
+        Args:
+            config: LMCache engine configuration
+            metadata: Pre-constructed LMCacheMetadata
+            gpu_connector: GPU connector instance
+            broadcast_fn: Broadcast function for tensor parallel
+            broadcast_object_fn: Broadcast function for objects
+            connector: Reference to connector for internal API server
+        """
+        service_factory = StandaloneServiceFactory(
+            config=config,
+            metadata=metadata,
+            gpu_connector=gpu_connector,
+            broadcast_fn=broadcast_fn,
+            broadcast_object_fn=broadcast_object_fn,
+        )
+
+        super().__init__(
+            config=config,
+            service_factory=service_factory,
+            connector=connector,
+        )
+
+    def post_init(self) -> None:
+        """Post-initialization for standalone mode."""
+        if self._init_failed:
+            if self._lmcache_engine is not None:
+                self._lmcache_engine.mark_init_failed(self._init_failed_reason)
+            logger.warning("Skipping post_init due to previous initialization failure")
+            return
+
+        try:
+            if self._lmcache_engine is not None:
+                # Standalone mode post-init (no async_lookup_server)
+                self._lmcache_engine.post_init()
+
+            # Initialize health monitor after engine post_init
+            self._init_health_monitor()
+        except Exception as e:
+            self._handle_post_init_failure(e)
diff --git a/lmcache/v1/standalone/standalone_service_factory.py b/lmcache/v1/standalone/standalone_service_factory.py
new file mode 100644
index 0000000..44d9624
--- /dev/null
+++ b/lmcache/v1/standalone/standalone_service_factory.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+StandaloneServiceFactory: Service factory for LMCache standalone mode.
+
+Creates LMCache service components without vLLM dependencies.
+"""
+
+# Standard
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+# First Party
+from lmcache.integration.base_service_factory import BaseServiceFactory
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.health_monitor.base import HealthMonitor
+from lmcache.v1.internal_api_server.api_server import InternalAPIServer
+from lmcache.v1.metadata import LMCacheMetadata
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.manager import LMCacheManager
+
+
+class StandaloneServiceFactory(BaseServiceFactory):
+    """Service factory for standalone LMCache mode (no vLLM)."""
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        gpu_connector: Any,
+        broadcast_fn: Callable,
+        broadcast_object_fn: Callable,
+    ):
+        self._config = config
+        self._metadata = metadata
+        self._gpu_connector = gpu_connector
+        self._broadcast_fn = broadcast_fn
+        self._broadcast_object_fn = broadcast_object_fn
+        self._engine: Optional[LMCacheEngine] = None
+
+    def get_engine_instance_id(self) -> str:
+        return self._config.lmcache_instance_id
+
+    def get_or_create_metadata(self) -> Optional[LMCacheMetadata]:
+        return self._metadata
+
+    def get_or_create_lmcache_engine(self) -> Optional[LMCacheEngine]:
+        if self._engine is not None:
+            return self._engine
+
+        instance_id = self._config.lmcache_instance_id
+        self._engine = LMCacheEngineBuilder.get_or_create(
+            instance_id=instance_id,
+            config=self._config,
+            metadata=self._metadata,
+            gpu_connector=self._gpu_connector,
+            broadcast_fn=self._broadcast_fn,
+            broadcast_object_fn=self._broadcast_object_fn,
+        )
+        return self._engine
+
+    def maybe_create_lookup_client(self):
+        return None
+
+    def maybe_create_prometheus_logger(self):
+        return None
+
+    def maybe_create_lookup_server(self):
+        return None
+
+    def maybe_create_offload_server(self):
+        return None
+
+    def maybe_create_runtime_plugin_launcher(self):
+        return None
+
+    def maybe_create_internal_api_server(
+        self, lmcache_manager: "LMCacheManager"
+    ) -> Optional[InternalAPIServer]:
+        return InternalAPIServer(lmcache_manager)
+
+    def maybe_create_health_monitor(
+        self, lmcache_manager: "LMCacheManager"
+    ) -> Optional[HealthMonitor]:
+        return self._create_health_monitor(lmcache_manager, self._config, self._engine)
diff --git a/lmcache/v1/storage_backend/__init__.py b/lmcache/v1/storage_backend/__init__.py
new file mode 100644
index 0000000..6e0f354
--- /dev/null
+++ b/lmcache/v1/storage_backend/__init__.py
@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from typing import TYPE_CHECKING, AbstractSet, Optional
+import asyncio
+import importlib  # Added for dynamic import
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+from lmcache.v1.storage_backend.gds_backend import GdsBackend
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.local_disk_backend import LocalDiskBackend
+from lmcache.v1.storage_backend.p2p_backend import P2PBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend  # noqa: F401
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+logger = init_logger(__name__)
+
+
+def is_cuda_worker(metadata: LMCacheMetadata) -> bool:
+    """
+    Check if the current role is worker and a GPU accelerator is available.
+
+    Args:
+        metadata: The LMCache engine metadata.
+
+    Returns:
+        True if the worker is not a scheduler and a GPU accelerator is available.
+    """
+    return metadata.role != "scheduler" and torch_dev.is_available()
+
+
+def storage_plugin_launcher(
+    config: LMCacheEngineConfig,
+    metadata: LMCacheMetadata,
+    loop: asyncio.AbstractEventLoop,
+    local_cpu_backend: Optional[LocalCPUBackend],
+    dst_device: str,
+    storage_backends: OrderedDict[str, StorageBackendInterface],
+) -> None:
+    """
+    Loads custom storage backends based on configuration.
+
+    Looks for backend configurations in config.extra_config and instantiates
+    them using the specified module and class names.
+    """
+    # Get the list of allowed external backends if configured
+    storage_plugins = set(config.storage_plugins) if config.storage_plugins else set()
+    if storage_plugins and not config.extra_config:
+        logger.warning(
+            "storage_plugins=%s is set but extra_config is empty; "
+            "plugin settings must be provided under extra_config, e.g. "
+            "extra_config.storage_plugin.<name>.module_path/class_name",
+            sorted(storage_plugins),
+        )
+        return
+    if not config.extra_config:
+        return
+
+    for storage_plugin in storage_plugins:
+        try:
+            module_path = config.extra_config.get(
+                f"storage_plugin.{storage_plugin}.module_path"
+            )
+            class_name = config.extra_config.get(
+                f"storage_plugin.{storage_plugin}.class_name"
+            )
+
+            if not module_path or not class_name:
+                logger.warning(
+                    f"Backend {storage_plugin} missing module_path or class_name"
+                )
+                continue
+
+            logger.warning(
+                "The 'memory_allocator' argument is deprecated and will "
+                "be ignored. Storage backends now manage their own memory "
+                "allocators since PR "
+                "https://github.com/LMCache/LMCache/pull/1578"
+            )
+
+            # Dynamically import the module
+            module = importlib.import_module(module_path)
+            # Get the class from the module
+            backend_class = getattr(module, class_name)
+
+            # Create the backend instance
+            backend_instance = backend_class(
+                config=config,
+                dst_device=dst_device,
+                metadata=metadata,
+                local_cpu_backend=local_cpu_backend,
+                loop=loop,
+            )
+
+            # Add to storage backends
+            storage_backends[storage_plugin] = backend_instance
+            logger.info(f"Created dynamic backend: {storage_plugin}")
+
+        except Exception as e:
+            logger.error(f"Failed to create backend {storage_plugin}: {str(e)}")
+
+
+def CreateStorageBackends(
+    config: LMCacheEngineConfig,
+    metadata: LMCacheMetadata,
+    loop: asyncio.AbstractEventLoop,
+    dst_device: str = torch_device_type,
+    lmcache_worker: Optional["LMCacheWorker"] = None,
+    skip_backends: Optional[AbstractSet[str]] = None,
+    existing_backends: Optional[OrderedDict[str, StorageBackendInterface]] = None,
+) -> OrderedDict[str, StorageBackendInterface]:
+    if is_cuda_worker(metadata):
+        dst_device = f"{torch_device_type}:{torch_dev.current_device()}"
+    else:
+        dst_device = "cpu"
+    storage_backends: OrderedDict[str, StorageBackendInterface] = OrderedDict()
+    _skip = skip_backends or set()
+
+    extra_config = config.extra_config
+    enable_nixl_storage = extra_config is not None and extra_config.get(
+        "enable_nixl_storage"
+    )
+
+    if config.enable_pd and "PDBackend" not in _skip:
+        # First Party
+        if config.pd_backend_mode == "async":
+            # First Party
+            from lmcache.v1.storage_backend.pd_backend_async import PDBackendAsync
+
+            storage_backends["PDBackend"] = PDBackendAsync(config, metadata)
+        else:
+            # First Party
+            from lmcache.v1.storage_backend.pd_backend import PDBackend
+
+            storage_backends["PDBackend"] = PDBackend(config, metadata)
+
+    # TODO(Jiayi): The hierarchy is fixed for now
+    # NOTE(Jiayi): The local_cpu backend is always created because
+    # other backends might need it as a buffer.
+    # Reuse existing LocalCPUBackend when available so that
+    # dependent backends (disk, remote, p2p, …) keep working.
+    local_cpu_backend: Optional[LocalCPUBackend] = None
+    if existing_backends and "LocalCPUBackend" in existing_backends:
+        _existing_cpu = existing_backends["LocalCPUBackend"]
+        if isinstance(_existing_cpu, LocalCPUBackend):
+            local_cpu_backend = _existing_cpu
+
+    if metadata.role == "scheduler":
+        # For scheduler role, local_cpu_backend is None. NIXL CPU mode shares
+        # LocalCPUBackend's pinned pool, which is not created for the scheduler,
+        # so the backend cannot be constructed here. Reject early with a clear
+        # error instead of letting NixlStorageBackend.__init__ raise deep in the
+        # stack. (The scheduler only needs contains(), which never allocates, so
+        # a query-only NIXL agent could in principle support this; it is not
+        # worth the surface area while the separate scheduler process is being
+        # removed in multiprocess mode.)
+        if enable_nixl_storage and config.nixl_buffer_device == "cpu":
+            raise ValueError(
+                "nixl_buffer_device='cpu' is not supported in the scheduler "
+                "role (e.g. enable_scheduler_bypass_lookup=True): the shared "
+                "LocalCPUBackend pool is not created for the scheduler. Use "
+                "nixl_buffer_device='cuda', or disable "
+                "enable_scheduler_bypass_lookup."
+            )
+    elif (
+        not config.enable_pd
+        or config.local_cpu
+        or (enable_nixl_storage and config.nixl_buffer_device == "cpu")
+    ):
+        if "LocalCPUBackend" in _skip:
+            pass  # Skipped — already exists
+        elif config.max_local_cpu_size > 0:
+            local_cpu_backend = LocalCPUBackend(
+                config,
+                metadata,
+                dst_device,
+                lmcache_worker,
+            )
+            backend_name = str(local_cpu_backend)
+            storage_backends[backend_name] = local_cpu_backend
+        else:
+            logger.info("No cpu memory is allocated as max_local_cpu_size <= 0")
+
+    if config.enable_p2p and "P2PBackend" not in _skip:
+        assert local_cpu_backend is not None
+        assert lmcache_worker is not None
+        p2p_backend = P2PBackend(
+            config,
+            metadata,
+            loop,
+            local_cpu_backend,
+            lmcache_worker,
+        )
+        backend_name = str(p2p_backend)
+        storage_backends[backend_name] = p2p_backend
+
+    if enable_nixl_storage and "NixlStorageBackend" not in _skip:
+        # First Party
+        from lmcache.v1.storage_backend.nixl_storage_backend import (
+            NixlStorageBackend,
+        )
+
+        storage_backends["NixlStorageBackend"] = (
+            NixlStorageBackend.CreateNixlStorageBackend(
+                config, loop, metadata, local_cpu_backend
+            )
+        )
+
+    if (
+        config.local_disk
+        and config.max_local_disk_size > 0
+        and "LocalDiskBackend" not in _skip
+    ):
+        assert local_cpu_backend is not None
+        local_disk_backend = LocalDiskBackend(
+            config,
+            loop,
+            local_cpu_backend,
+            dst_device,
+            lmcache_worker,
+            metadata,
+        )
+
+        backend_name = str(local_disk_backend)
+        storage_backends[backend_name] = local_disk_backend
+
+    if config.gds_path is not None and "GdsBackend" not in _skip:
+        gds_backend = GdsBackend(
+            config,
+            metadata,
+            loop,
+            dst_device,
+        )
+        storage_backends[str(gds_backend)] = gds_backend
+
+    if config.maru_path is not None and "MaruBackend" not in _skip:
+        try:
+            # First Party
+            from lmcache.v1.storage_backend.maru_backend import MaruBackend
+        except ImportError as e:
+            raise ImportError(
+                "The 'maru' and 'maru_lmcache' packages are required "
+                "to use MaruBackend. Please install them according to "
+                "the Maru setup documentation."
+            ) from e
+
+        maru_backend = MaruBackend(config, metadata, loop, dst_device)
+        storage_backends[str(maru_backend)] = maru_backend
+
+    # Handle remote storage plugins (new way)
+    if config.remote_storage_plugins and "RemoteBackend" not in _skip:
+        for plugin_name in config.remote_storage_plugins:
+            assert local_cpu_backend is not None, (
+                "Remote backend requires local CPU backend as a buffer."
+                "Please turn on local cpu backend with max_local_cpu_size > 0"
+            )
+            try:
+                remote_backend = RemoteBackend(
+                    config,
+                    metadata,
+                    loop,
+                    local_cpu_backend,
+                    dst_device,
+                    plugin_name=plugin_name,
+                )
+                backend_name = "RemoteBackend-%s" % plugin_name
+                storage_backends[backend_name] = remote_backend
+                logger.info(
+                    "Created remote backend for plugin: %s",
+                    plugin_name,
+                )
+            except Exception as e:
+                logger.error(
+                    "Failed to create remote backend for plugin %s: %s",
+                    plugin_name,
+                    e,
+                )
+
+    # Handle legacy remote_url (deprecated but still supported)
+    if config.remote_url is not None and "RemoteBackend" not in _skip:
+        # Log deprecation warning
+        logger.warning(
+            "remote_url is deprecated and will be removed in a future release. "
+            "Please use remote_storage_plugins instead."
+        )
+        remote_backend = RemoteBackend(
+            config,
+            metadata,
+            loop,
+            local_cpu_backend,
+            dst_device,
+        )
+        backend_name = str(remote_backend)
+        storage_backends[backend_name] = remote_backend
+
+    if not config.enable_pd or config.local_cpu:
+        # Load storage backends from configuration
+        storage_plugin_launcher(
+            config,
+            metadata,
+            loop,
+            local_cpu_backend,
+            dst_device,
+            storage_backends,
+        )
+
+    # Only wrap if audit is enabled in config
+    if config.extra_config is not None and config.extra_config.get(
+        "audit_backend_enabled", False
+    ):
+        # First Party
+        from lmcache.v1.storage_backend.audit_backend import AuditBackend
+
+        # Conditionally wrap backends with audit logging if enabled in config
+        audited_backends: OrderedDict[str, StorageBackendInterface] = OrderedDict()
+        for name, backend in storage_backends.items():
+            # Wrap each normal backend with AuditBackend
+            if not isinstance(backend, LocalCPUBackend):
+                audited_backend = AuditBackend(backend)
+                audited_backends[name] = audited_backend
+                logger.info(f"Wrapped {name} with AuditBackend")
+            else:
+                audited_backends[name] = backend
+                logger.info(f"Do not wrap {name} as it is a LocalCPUBackend")
+        return audited_backends
+    else:
+        # If audit is not enabled, use the original backends
+        return storage_backends
diff --git a/lmcache/v1/storage_backend/abstract_backend.py b/lmcache/v1/storage_backend/abstract_backend.py
new file mode 100644
index 0000000..1b7b15a
--- /dev/null
+++ b/lmcache/v1/storage_backend/abstract_backend.py
@@ -0,0 +1,460 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from concurrent.futures import Future
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Sequence, Union
+import abc
+import asyncio
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.storage_backend import LocalCPUBackend
+
+
+class StorageBackendInterface(metaclass=abc.ABCMeta):
+    def __init__(
+        self,
+        dst_device: str = torch_device_type,
+    ):
+        """
+        Initialize the storage backend.
+
+        :param dst_device: the device where the blocking retrieved KV is stored,
+            could be either "cpu", "cuda", or "cuda:0", "cuda:1", etc.
+
+        :raise: RuntimeError if the device is not valid
+        """
+        try:
+            torch.device(dst_device)
+        except RuntimeError:
+            raise
+
+        self.dst_device = dst_device
+
+    @abc.abstractmethod
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """
+        Check whether key is in the storage backend.
+
+        :param CacheEngineKey key: The key of the MemoryObj.
+
+        :param bool pin: Whether to pin the key.
+            If True, the corresponding KV cache will be
+            pinned in the storage backend.
+
+        :return: True if the key exists, False otherwise.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """
+        Check whether key is in the ongoing put tasks.
+        """
+        raise NotImplementedError
+
+    # NOTE (Jiayi): Using batched interface allows the underlying implementation
+    # have more flexibility to do optimizations.
+    @abc.abstractmethod
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Union[List[Future], None]:
+        """
+        An async function to put the MemoryObj into the storage backend.
+
+        :param List[CacheEngineKey] keys: The keys of the MemoryObjs.
+        :param List[MemoryObj] objs: The MemoryObjs to be stored.
+        :param Any transfer_spec: Optional transfer specification.
+        :param on_complete_callback: Optional callback invoked once per key
+            after the backend finishes persisting the KV chunk for that key.
+            For batched puts, the callback is invoked separately for each key
+            when that key completes (not once per batch). Callback exceptions
+            are caught and logged. Backends that cannot use this callback may
+            ignore it.
+
+        :return:  Union[List[Future], None]: A list of `Future` objects if the
+        storage persistence operation is asynchronous and is successful.
+        `None` if the operation is synchronous, or the asynchronous fails
+        or is skipped.
+
+        :note: This function will have the side effect that modifies the
+            underlying key-value mappings in the storage backend. The side
+            effect may change the result of lookup and get.
+        """
+        raise NotImplementedError
+
+    async def async_batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        An async version of batched_submit_put_task.
+
+        :param on_complete_callback: Optional callback invoked once per key
+            after the backend finishes persisting the KV chunk for that key.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        """
+        A blocking function to get the kv cache from the storage backend.
+
+        :param CacheEngineKey key: The key of the MemoryObj.
+
+        :return: MemoryObj. None if the key does not exist.
+        """
+        raise NotImplementedError
+
+    def get_non_blocking(
+        self,
+        key: CacheEngineKey,
+        location: Optional[str] = None,
+    ) -> Optional[Future]:
+        """
+        A non-blocking function to get the kv cache from the storage backend.
+        """
+        raise NotImplementedError
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """
+        Check whether keys are in the storage backend.
+
+        :param List[CacheEngineKey] keys: The keys of the MemoryObjs.
+
+        :param bool pin: Whether to pin the keys.
+            If True, the corresponding KV caches will be
+            pinned in the storage backend.
+
+        :return: The number of keys that exist in the storage backend.
+        """
+        raise NotImplementedError
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        """
+        A non-blocking function to get the kv cache from the storage backend.
+
+        :param list[CacheEngineKey] keys: The keys of the list of MemoryObjs.
+
+        :return: a list of MemoryObj.
+        """
+        raise NotImplementedError
+
+    # NOTE(Jiayi): Please re-implement this method if the storage backend
+    # can benefit from batched get.
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """
+        A blocking function to get the kv cache from the storage backend.
+
+        :param List[CacheEngineKey] keys: The keys of the MemoryObjs.
+
+        :return: a list of memory objects.
+        """
+        mem_objs = []
+        for key in keys:
+            mem_objs.append(self.get_blocking(key))
+        return mem_objs
+
+    @abc.abstractmethod
+    def pin(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        """
+        Pin a memory object so it will not be evicted.
+
+        :param CacheEngineKey key: The key of the MemoryObj.
+
+        :return: a bool indicates whether pin is successful.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def unpin(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        """
+        Unpin a memory object so it can be evicted.
+
+        :param CacheEngineKey key: The key of the MemoryObj.
+
+        :return: a bool indicates whether unpin is successful.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        """
+        remove a memory object.
+
+        :param CacheEngineKey key: The key of the MemoryObj.
+        :param bool force: Whether to it is a forced remove from the external.
+
+        :return: a bool indicates whether remove is successful.
+        """
+        raise NotImplementedError
+
+    # TODO(Jiayi): Optimize batched remove
+    def batched_remove(
+        self,
+        keys: list[CacheEngineKey],
+        force: bool = True,
+    ) -> int:
+        """
+        Remove a list of memory objects.
+
+        :param list[CacheEngineKey] keys: The keys of the MemoryObjs.
+        :param bool force: Whether to force remove the memory objects.
+
+        :return: a int indicates the number of removed memory objects.
+        """
+        num_removed = 0
+        for key in keys:
+            num_removed += self.remove(key, force=force)
+        return num_removed
+
+    @abc.abstractmethod
+    def get_allocator_backend(self) -> "AllocatorBackendInterface":
+        """
+        Get the allocator backend that is used by the current storage backend
+        to allocate memory objects during `get` operations.
+
+        :return: an instance of AllocateBackendInterface
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(
+        self,
+    ) -> None:
+        """
+        Close the storage backend.
+        """
+        raise NotImplementedError
+
+    def batched_contains(
+        self,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """
+        Check whether the keys are in the storage backend.
+
+        :param List[CacheEngineKey] keys: The keys of the MemoryObj.
+
+        :param bool pin: Whether to pin the key.
+            If True, the corresponding KV cache will be
+            pinned in the storage backend.
+
+        :return: Return hit chunks by prefix match.
+        """
+        hit_chunks = 0
+        for key in keys:
+            if not self.contains(key, pin):
+                break
+            hit_chunks += 1
+        return hit_chunks
+
+    def touch_cache(self) -> None:
+        """
+        Update cache policy with keys that were accessed during a request.
+
+        This method is called to update the cache eviction policy with the
+        keys that were accessed in the most recent request, typically to
+        implement LRU or similar eviction strategies.
+
+        Default implementation does nothing. Backends that support
+        cache eviction policies should override this method.
+
+        :return: None
+        """
+        raise NotImplementedError
+
+    def cancel_request(self, req_id: str) -> None:
+        """
+        Cancel an in-flight or pending request.
+
+        This method is used by backends that track per-request state
+        (e.g., PDBackendAsync for disaggregation). For backends that
+        do not track request state, this method is a no-op.
+
+        :param str req_id: The request identifier to cancel.
+        :return: None
+        """
+        # Default implementation is no-op
+        return
+
+
+class AllocatorBackendInterface(StorageBackendInterface):
+    """
+    AllocatorBackendInterface extends the StorageBackendInterface with
+    the ability to actively allocate the memory objects.
+    """
+
+    @abc.abstractmethod
+    def initialize_allocator(
+        self, config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ) -> MemoryAllocatorInterface:
+        """
+        Create the correct memory allocator for the current storage backend
+
+        Args:
+            config: The cache engine config
+            metadata: the cache engine metadata
+
+        Returns:
+            The memory allocator for this storage backend
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_memory_allocator(self) -> MemoryAllocatorInterface:
+        """
+        Returns:
+            The underlying memory allocator
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        """
+        Allocates memory in the backend to hold a tensor of the given shape.
+
+        :param Union[torch.Size, list[torch.Size]] shapes:
+            The shape of the tensor to allocate.
+        :param Union[torch.dtype, list[torch.dtype]] dtypes:
+            The dtype of the tensor to allocate.
+        :param MemoryFormat fmt: The format of the memory to allocate.
+        :param bool eviction: whether to enable eviction when allocating.
+        :param bool busy_loop: whether to enable a busy loop to wait
+            for in-progress store operations to finish and release the
+            memory space for retrieve.
+
+        :return: A MemoryObj wrapping the allocated memory. Returns
+            None if the allocation failed.
+
+        :rtype: Optional[MemoryObj]
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[list[MemoryObj]]:
+        """
+        Allocates memory in the backend to hold a tensor of the given shape
+        in a batched manner. The allocated memory objects will have the same
+        shape, dtype, and format.
+
+        :param Union[torch.Size, list[torch.Size]] shapes:
+            The shape of the tensor to allocate.
+        :param Union[torch.dtype, list[torch.dtype]] dtypes:
+            The dtype of the tensor to allocate.
+        :param int batch_size: The number of memory objects to allocate.
+        :param MemoryFormat fmt: The format of the memory to allocate.
+        :param bool eviction: whether to enable eviction when allocating.
+        :param bool busy_loop: whether to enable a busy loop to wait
+            for in-progress store operations to finish and release the
+            memory space for retrieve.
+
+        :return: A MemoryObj wrapping the allocated memory. Returns
+            None if the allocation failed.
+
+        :rtype: Optional[MemoryObj]
+        """
+        raise NotImplementedError
+
+    def calculate_chunk_budget(self) -> int:
+        """
+        Calculate the chunk budget for the allocator backend.
+        """
+        raise NotImplementedError
+
+
+class StoragePluginInterface(StorageBackendInterface):
+    """The Configurable Storage Backend Interface needs to be implemented
+    when you want to add a storage backend in a configurable or plug and play
+    fashion."""
+
+    def __init__(
+        self,
+        dst_device: str = torch_device_type,
+        config: Optional[LMCacheEngineConfig] = None,
+        metadata: Optional[LMCacheMetadata] = None,
+        local_cpu_backend: Optional["LocalCPUBackend"] = None,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ):
+        """
+        Initialize a configurable storage backend. This constructor will be called
+        when loading the configurable storage backends from the configuration file.
+
+        :param str dst_device: The target device for tensor operations
+            (e.g., "cuda" or "cpu").
+        :param LMCacheEngineConfig config: Optional configuration object for the
+            cache engine.
+        :param LMCacheMetadata metadata: Optional metadata describing the cache
+            engine state or version.
+        :param LocalCPUBackend local_cpu_backend: Optional backend for local CPU-based
+            inference or caching.
+        :param asyncio.AbstractEventLoop loop: Optional asyncio event loop for
+            asynchronous operations.
+        """
+        super().__init__(dst_device=dst_device)
+        self.config = config
+        self.metadata = metadata
+        self.local_cpu_backend = local_cpu_backend
+        self.loop = loop
+
+
+# TODO: Alias for backwards compatibility - remove when applicable
+ConfigurableStorageBackendInterface = StoragePluginInterface
diff --git a/lmcache/v1/storage_backend/audit_backend.py b/lmcache/v1/storage_backend/audit_backend.py
new file mode 100644
index 0000000..1b6a3e4
--- /dev/null
+++ b/lmcache/v1/storage_backend/audit_backend.py
@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Any, Callable, List, Optional, Sequence
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+
+logger = init_logger(__name__)
+
+
+class AuditBackend(StorageBackendInterface):
+    """
+    Audit wrapper for StorageBackend that logs operations and measures performance.
+    """
+
+    def __init__(self, real_backend: StorageBackendInterface) -> None:
+        """Wrap *real_backend* with operation logging and timing."""
+        super().__init__(dst_device=real_backend.dst_device)
+        self.real_backend = real_backend
+        self.logger = logger.getChild("audit")
+        self.logger.info(
+            "[AUDIT_BACKEND] Initialized for backend: %s", str(real_backend)
+        )
+
+    def _log_operation(
+        self,
+        op_name: str,
+        start_time: float,
+        key: Optional[CacheEngineKey] = None,
+        success: bool = True,
+        result=None,
+        error=None,
+        size=None,
+    ) -> None:
+        """Helper method to log operation results."""
+        cost = (time.perf_counter() - start_time) * 1000
+        backend_name = str(self.real_backend)
+
+        if error:
+            self.logger.error(
+                "[AUDIT_BACKEND][%s]:%s|FAILED|Key:%s|Error:%s",
+                backend_name,
+                op_name,
+                key,
+                str(error),
+            )
+        elif success:
+            log_msg = "[AUDIT_BACKEND][%s]:%s|SUCCESS|Cost:%.2fms"
+            log_args = [backend_name, op_name, cost]
+            if key:
+                log_msg += "|Key:%s"
+                log_args.append(key)
+            if size is not None:
+                log_msg += "|Size:%s"
+                log_args.append(size)
+            if result is not None:
+                log_msg += "|Result:%s"
+                log_args.append(result)
+            self.logger.info(log_msg, *log_args)
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """Check key existence with audit logging."""
+        self.logger.debug("[AUDIT_BACKEND] Checking contains for key: %s", key)
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.contains(key, pin)
+            self._log_operation("CONTAINS", start_time, key, True, result)
+            return result
+        except Exception as e:
+            self._log_operation("CONTAINS", start_time, key, False, error=e)
+            raise
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Retrieve data with audit logging."""
+        self.logger.debug("[AUDIT_BACKEND] Getting data for key: %s", key)
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.get_blocking(key)
+            size = len(result.byte_array) if result else 0
+            self._log_operation(
+                "GET", start_time, key, True, result=result is not None, size=size
+            )
+            return result
+        except Exception as e:
+            self._log_operation("GET", start_time, key, False, error=e)
+            raise
+
+    def close(self) -> None:
+        """Close backend with audit logging."""
+        self.logger.debug("[AUDIT_BACKEND] Closing backend")
+        start_time = time.perf_counter()
+        try:
+            self.real_backend.close()
+            self._log_operation("CLOSE", start_time, None, True)
+        except Exception as e:
+            self._log_operation("CLOSE", start_time, None, False, error=e)
+            raise
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """Check if *key* is in pending put tasks."""
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.exists_in_put_tasks(key)
+            self._log_operation("EXISTS_IN_PUT_TASKS", start_time, key, True, result)
+            return result
+        except Exception as e:
+            self._log_operation("EXISTS_IN_PUT_TASKS", start_time, key, False, error=e)
+            raise
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """Batched submit put task with audit logging."""
+        sizes = [len(obj.byte_array) for obj in memory_objs]
+        start_time = time.perf_counter()
+        try:
+            self.real_backend.batched_submit_put_task(
+                keys, memory_objs, transfer_spec, on_complete_callback
+            )
+            self._log_operation(
+                "BATCHED_SUBMIT_PUT_TASK", start_time, None, True, size=sum(sizes)
+            )
+        except Exception as e:
+            self._log_operation(
+                "BATCHED_SUBMIT_PUT_TASK", start_time, None, False, error=e
+            )
+            raise
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        """Batched non-blocking get with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = await self.real_backend.batched_get_non_blocking(
+                lookup_id, keys, transfer_spec
+            )
+            self._log_operation("BATCHED_GET_NON_BLOCKING", start_time, None, True)
+            return result
+        except Exception as e:
+            self._log_operation(
+                "BATCHED_GET_NON_BLOCKING", start_time, None, False, error=e
+            )
+            raise
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Batched async contains with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = await self.real_backend.batched_async_contains(
+                lookup_id, keys, pin
+            )
+            self._log_operation("BATCHED_ASYNC_CONTAINS", start_time, None, True)
+            return result
+        except Exception as e:
+            self._log_operation(
+                "BATCHED_ASYNC_CONTAINS", start_time, None, False, error=e
+            )
+            raise
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        """Pin *key* in cache with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.pin(key)
+            self._log_operation("PIN", start_time, key, True, result)
+            return result
+        except Exception as e:
+            self._log_operation("PIN", start_time, key, False, error=e)
+            raise
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        """Unpin *key* with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.unpin(key)
+            self._log_operation("UNPIN", start_time, key, True, result)
+            return result
+        except Exception as e:
+            self._log_operation("UNPIN", start_time, key, False, error=e)
+            raise
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """Batched blocking get with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.batched_get_blocking(keys)
+            self._log_operation(
+                "BATCHED_GET_BLOCKING",
+                start_time,
+                None,
+                True,
+                result=len(result) if result is not None else 0,
+            )
+            return result
+        except Exception as e:
+            self._log_operation(
+                "BATCHED_GET_BLOCKING", start_time, None, False, error=e
+            )
+            raise
+
+    def remove(self, key: CacheEngineKey, free_obj: bool = True) -> bool:
+        """Remove *key* from cache with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.remove(key, free_obj)
+            self._log_operation("REMOVE", start_time, key, True, result)
+            return result
+        except Exception as e:
+            self._log_operation("REMOVE", start_time, key, False, error=e)
+            raise
+
+    def batched_remove(
+        self,
+        keys: list[CacheEngineKey],
+        free_obj: bool = True,
+    ) -> int:
+        """Batched remove with audit logging."""
+        start_time = time.perf_counter()
+        try:
+            result = self.real_backend.batched_remove(keys, free_obj)
+            self._log_operation("BATCHED_REMOVE", start_time, None, True, result)
+            return result
+        except Exception as e:
+            self._log_operation("BATCHED_REMOVE", start_time, None, False, error=e)
+            raise
+
+    def get_allocator_backend(self):  # type: ignore[no-untyped-def]
+        """Delegate to real backend."""
+        return self.real_backend.get_allocator_backend()
diff --git a/lmcache/v1/storage_backend/batched_message_sender.py b/lmcache/v1/storage_backend/batched_message_sender.py
new file mode 100644
index 0000000..c0b1bc0
--- /dev/null
+++ b/lmcache/v1/storage_backend/batched_message_sender.py
@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, List, Optional
+import queue
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import PrometheusLogger
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    KVOpEvent,
+    OpType,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+logger = init_logger(__name__)
+
+
+class BatchedMessageSender:
+    """
+    Batched message sender for KVOperation.
+
+    This class accumulates KV admit/evict messages and sends them in batches
+    to reduce communication overhead. Messages are flushed when either:
+    1. The batch size threshold is reached (default: 50 messages)
+    2. The timeout period expires (default: 0.01 seconds)
+
+    Each message is assigned a unique, monotonically increasing sequence number
+    to enable the receiver to detect missing or out-of-order messages.
+
+    Design rationale:
+    - Uses a SINGLE queue for both admit and evict messages to maintain strict
+      order consistency. This is critical because operations like
+      admit(key) -> evict(key) -> admit(key) must be processed in exact order
+      to avoid race conditions and state inconsistencies on the receiver side.
+
+    Thread-safe: Uses locks to protect internal queue and sequence counter.
+
+    Args:
+        metadata: Metadata for the worker
+        config: Configuration for the worker
+        location: Location of the worker
+        lmcache_worker: The worker to send messages to. If None, batching is disabled.
+    """
+
+    def __init__(
+        self,
+        metadata: LMCacheMetadata,
+        config: LMCacheEngineConfig,
+        location: str,
+        lmcache_worker: "LMCacheWorker",
+    ) -> None:
+        self.batch_size = config.get_extra_config_value("kv_msg_batch_size", 50)
+        self.batch_timeout = config.get_extra_config_value("kv_msg_batch_timeout", 0.01)
+        self.lmcache_worker = lmcache_worker
+        self.metadata = metadata
+        self.config = config
+
+        # Common fields shared by all operations in the batch
+        self.instance_id = config.lmcache_instance_id
+        self.worker_id = metadata.worker_id
+        self.location = location
+
+        # Use thread-safe queue for producer-consumer pattern
+        self.message_queue: queue.Queue[KVOpEvent] = queue.Queue()
+        self.sequence_number = 0
+        self.sequence_lock = threading.Lock()
+
+        # Condition variable for coordinating producer and consumer
+        self.cv = threading.Condition()
+        self.running = False
+        self.thread: Optional[threading.Thread] = None
+
+        self._start_background_thread()
+
+        self._setup_metrics()
+
+    def _setup_metrics(self) -> None:
+        """Setup metrics for monitoring queue size."""
+        prometheus_logger = PrometheusLogger.GetOrCreate(
+            self.metadata,
+            config=self.config,
+        )
+        prometheus_logger.kv_msg_queue_size.set_function(
+            lambda: self.message_queue.qsize()
+        )
+
+    def _start_background_thread(self):
+        """Start background thread for periodic flushing."""
+        self.running = True
+        self.thread = threading.Thread(
+            target=self._consumer_loop, daemon=True, name="batched-msg-sender-thread"
+        )
+        self.thread.start()
+
+    def _consumer_loop(self):
+        """Consumer loop that drains queue and sends batched messages."""
+        while self.running:
+            with self.cv:
+                # Wait for timeout or notification from producer
+                self.cv.wait(timeout=self.batch_timeout)
+
+                # Check if we have messages to process while holding the lock
+                # This prevents race conditions but we'll release lock
+                # before blocking operations
+                if self.message_queue.empty():
+                    continue
+
+            # Drain the queue without holding the lock to avoid blocking producers
+            # This improves performance during the actual message processing
+            self._drain_and_send()
+
+    def _get_next_sequence_number(self) -> int:
+        """Get next sequence number for message tracking.
+
+        Thread-safe: Uses dedicated lock for sequence number generation.
+        """
+        with self.sequence_lock:
+            seq = self.sequence_number
+            self.sequence_number += 1
+            return seq
+
+    def add_kv_op(
+        self,
+        op_type: OpType,
+        key: int,
+    ):
+        """Add a KV operation to the batch queue.
+
+        Producer method: Adds operation to queue and notifies consumer
+        when batch size threshold is reached.
+
+        Args:
+            op_type: Operation type (ADMIT or EVICT)
+            key: Chunk hash key
+        """
+        # Create operation without sequence number (will be assigned during drain)
+        op = KVOpEvent(op_type=op_type, key=key, seq_num=-1)
+
+        # Thread-safe queue put
+        self.message_queue.put(op)
+
+        # Notify consumer if batch size threshold is reached
+        if self.message_queue.qsize() >= self.batch_size:
+            with self.cv:
+                self.cv.notify()
+
+    def _drain_and_send(self):
+        """Drain the queue and send all messages in a batch.
+
+        This method is called by the consumer thread to collect all pending
+        operations from the queue and send them as a single batched message.
+        """
+        ops_to_send: List[KVOpEvent] = []
+
+        # Drain all messages from the queue using blocking get with timeout
+        # This ensures we don't miss any messages due to race conditions
+        while True:
+            try:
+                # Use a small timeout to avoid blocking indefinitely
+                op = self.message_queue.get(timeout=0.001)
+                # Assign sequence number at drain time to ensure strict ordering
+                op.seq_num = self._get_next_sequence_number()
+                ops_to_send.append(op)
+            except queue.Empty:
+                # Queue is empty, break the loop
+                break
+
+        if not ops_to_send:
+            return
+
+        try:
+            # Ensure common fields are set
+            assert self.instance_id is not None, "instance_id must be set"
+            assert self.worker_id is not None, "worker_id must be set"
+            assert self.location is not None, "location must be set"
+
+            # Create batched message with common fields and lightweight operations
+            # This reduces redundancy: common fields are sent once instead of N times
+            batched_msg = BatchedKVOperationMsg(
+                instance_id=self.instance_id,
+                worker_id=self.worker_id,
+                location=self.location,
+                operations=ops_to_send,
+            )
+            self.lmcache_worker.put_msg(batched_msg)
+        finally:
+            # Mark all tasks as done regardless of success/failure
+            # This ensures flush() doesn't hang if put_msg fails
+            for _ in ops_to_send:
+                self.message_queue.task_done()
+
+    def flush(self):
+        """Manually flush all pending messages.
+
+        This method ensures all pending messages in the queue are processed
+        before returning. It triggers the consumer thread and waits for the
+        queue to be empty.
+        """
+        with self.cv:
+            self.cv.notify()
+
+        self.message_queue.join()
+
+    def close(self):
+        """Close the batched message sender and flush remaining messages."""
+        self.flush()
+        self.running = False
+
+        # Wake up consumer thread to exit
+        with self.cv:
+            self.cv.notify()
+
+        # Wait for thread to finish
+        if self.thread is not None and self.thread.is_alive():
+            self.thread.join(timeout=1.0)
+            if self.thread.is_alive():
+                logger.warning(
+                    "Batched message sender thread did not terminate within timeout"
+                )
diff --git a/lmcache/v1/storage_backend/cache_policy/__init__.py b/lmcache/v1/storage_backend/cache_policy/__init__.py
new file mode 100644
index 0000000..5a9d56e
--- /dev/null
+++ b/lmcache/v1/storage_backend/cache_policy/__init__.py
@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Dict, Type
+
+# First Party
+from lmcache.v1.storage_backend.cache_policy.base_policy import BaseCachePolicy
+from lmcache.v1.storage_backend.cache_policy.fifo import FIFOCachePolicy
+from lmcache.v1.storage_backend.cache_policy.lfu import LFUCachePolicy
+from lmcache.v1.storage_backend.cache_policy.lru import LRUCachePolicy
+from lmcache.v1.storage_backend.cache_policy.mru import MRUCachePolicy
+
+# Cache policy mapping
+POLICY_MAPPING: Dict[str, Type[BaseCachePolicy]] = {
+    "LRU": LRUCachePolicy,
+    "LFU": LFUCachePolicy,
+    "FIFO": FIFOCachePolicy,
+    "MRU": MRUCachePolicy,
+}
+
+
+def get_cache_policy(policy_name: str) -> BaseCachePolicy:
+    """
+    Factory function to get the cache policy instance based on the policy name.
+
+    Args:
+        policy_name: Name of the cache policy (case-insensitive, e.g., "LRU", "lru").
+
+    Returns:
+        Instance of the corresponding cache policy.
+
+    Raises:
+        ValueError: If the policy name is not supported.
+    """
+    if not policy_name:
+        raise ValueError("Cache policy name cannot be empty")
+
+    upper_policy_name = policy_name.upper()
+
+    try:
+        return POLICY_MAPPING[upper_policy_name]()
+    except KeyError:
+        raise ValueError(
+            f"Unknown cache policy: {upper_policy_name}."
+            f" Supported policies are: {list(POLICY_MAPPING.keys())}"
+        ) from None
diff --git a/lmcache/v1/storage_backend/cache_policy/base_policy.py b/lmcache/v1/storage_backend/cache_policy/base_policy.py
new file mode 100644
index 0000000..aef9b43
--- /dev/null
+++ b/lmcache/v1/storage_backend/cache_policy/base_policy.py
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections.abc import MutableMapping
+from typing import Generic, TypeVar
+import abc
+
+KeyType = TypeVar("KeyType")
+MapType = TypeVar("MapType", bound=MutableMapping)
+
+
+class BaseCachePolicy(Generic[KeyType, MapType], metaclass=abc.ABCMeta):
+    """
+    Interface for cache policy.
+    """
+
+    @abc.abstractmethod
+    def init_mutable_mapping(self) -> MapType:
+        """
+        Initialize a mutable mapping for cache storage.
+
+        Return:
+            A mutable mapping that can be used to store cache entries.
+        """
+        raise NotImplementedError
+
+    # TODO(Jiayi): we need to unify the `Any` type in the `MutableMapping`
+    @abc.abstractmethod
+    def update_on_hit(
+        self,
+        key: KeyType,
+        cache_dict: MapType,
+    ) -> None:
+        """
+        Update cache_dict and internal states when a cache is used
+
+        Input:
+            key: an object of KeyType
+            cache_dict: a dict consists of current cache
+        """
+        raise NotImplementedError
+
+    # TODO(Jiayi): we need to unify the `Any` type in the `MutableMapping`
+    @abc.abstractmethod
+    def update_on_put(
+        self,
+        key: KeyType,
+    ) -> None:
+        """
+        Update cache_dict and internal states when a cache is stored
+
+        Input:
+            key: an object of KeyType
+        """
+        raise NotImplementedError
+
+    # TODO(Jiayi): we need to unify the `Any` type in the `MutableMapping`
+    @abc.abstractmethod
+    def update_on_force_evict(
+        self,
+        key: KeyType,
+    ) -> None:
+        """
+        Update internal states when a cache is force evicted
+
+        Input:
+            key: an object of KeyType
+        """
+        raise NotImplementedError
+
+    # TODO(Jiayi): we need to unify the `Any` type in the `MutableMapping`
+    @abc.abstractmethod
+    def get_evict_candidates(
+        self,
+        cache_dict: MapType,
+        num_candidates: int = 1,
+    ) -> list[KeyType]:
+        """
+        Evict cache when a new cache comes and the storage is full
+
+        Input:
+            cache_dict: a dict consists of current cache
+            num_candidates: number of candidates to be evicted
+
+        Return:
+            return a list of keys to be evicted
+        """
+        raise NotImplementedError
diff --git a/lmcache/v1/storage_backend/cache_policy/fifo.py b/lmcache/v1/storage_backend/cache_policy/fifo.py
new file mode 100644
index 0000000..527d5e1
--- /dev/null
+++ b/lmcache/v1/storage_backend/cache_policy/fifo.py
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.cache_policy.base_policy import BaseCachePolicy, KeyType
+
+logger = init_logger(__name__)
+
+
+class FIFOCachePolicy(BaseCachePolicy[KeyType, dict[KeyType, Any]]):
+    """
+    FIFO cache policy.
+    """
+
+    def __init__(self):
+        logger.info("Initializing FIFOCachePolicy")
+
+    def init_mutable_mapping(self) -> dict[KeyType, Any]:
+        # NOTE(Jiayi): python dict maintains insertion order.
+        return {}
+
+    def update_on_hit(
+        self,
+        key: KeyType,
+        cache_dict: dict[KeyType, Any],
+    ) -> None:
+        pass
+
+    def update_on_put(
+        self,
+        key: KeyType,
+    ) -> None:
+        pass
+
+    def update_on_force_evict(
+        self,
+        key: KeyType,
+    ) -> None:
+        pass
+
+    # NOTE(Jiayi): We do best effort to get eviction candidates so the number
+    # of returned keys might be smaller than num_candidates.
+    def get_evict_candidates(
+        self,
+        cache_dict: dict[KeyType, Any],
+        num_candidates: int = 1,
+    ) -> list[KeyType]:
+        evict_keys = []
+        for key, cache in cache_dict.items():
+            if not cache.can_evict:
+                continue
+            evict_keys.append(key)
+            if len(evict_keys) == num_candidates:
+                break
+
+        return evict_keys
diff --git a/lmcache/v1/storage_backend/cache_policy/lfu.py b/lmcache/v1/storage_backend/cache_policy/lfu.py
new file mode 100644
index 0000000..f036884
--- /dev/null
+++ b/lmcache/v1/storage_backend/cache_policy/lfu.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Any
+
+# Third Party
+from sortedcontainers import SortedDict
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.cache_policy.base_policy import BaseCachePolicy, KeyType
+
+logger = init_logger(__name__)
+
+
+class LFUCachePolicy(BaseCachePolicy[KeyType, dict[KeyType, Any]]):
+    """
+    LFU cache policy.
+    """
+
+    # NOTE(Jiayi): We use `sorted dict` + `bucket` to implement LFU.
+    # NOTE(Jiayi): We use FIFO for entries with the same frequency.
+    def __init__(self):
+        # TODO(Jiayi): `SortedDict` is log(N).
+        # A way to make it O(1) is to use a dict and keep track min freuency.
+        # However, this requires us keep another data structures to keep track
+        # of the pinned keys.
+        self.freq_to_keys = SortedDict()
+
+        # TODO(Jiayi): We can optimize this a bit by using `key_to_val_freq`
+        self.key_to_freq = {}
+
+        logger.info("Initializing LFUCachePolicy")
+
+    def init_mutable_mapping(self) -> dict[KeyType, Any]:
+        return {}
+
+    def update_on_hit(
+        self,
+        key: KeyType,
+        cache_dict: dict[KeyType, Any],
+    ) -> None:
+        curr_freq = self.key_to_freq[key]
+        self.freq_to_keys[curr_freq].pop(key)
+        if not self.freq_to_keys[curr_freq]:
+            self.freq_to_keys.pop(curr_freq)
+
+        curr_freq += 1
+        self.key_to_freq[key] = curr_freq
+
+        if curr_freq not in self.freq_to_keys:
+            self.freq_to_keys[curr_freq] = {key: None}
+        else:
+            self.freq_to_keys[curr_freq][key] = None
+
+    def update_on_put(
+        self,
+        key: KeyType,
+    ) -> None:
+        # Initialize the frequency for the new key.
+        self.key_to_freq[key] = 1
+        if 1 not in self.freq_to_keys:
+            self.freq_to_keys[1] = {key: None}
+        else:
+            self.freq_to_keys[1][key] = None
+
+    def update_on_force_evict(
+        self,
+        key: KeyType,
+    ) -> None:
+        freq = self.key_to_freq.pop(key, None)
+        if not freq:
+            return
+        self.freq_to_keys[freq].pop(key)
+        if not self.freq_to_keys[freq]:
+            self.freq_to_keys.pop(freq)
+
+    # NOTE(Jiayi): We do best effort to get eviction candidates so the number
+    # of returned keys might be smaller than num_candidates.
+    def get_evict_candidates(
+        self,
+        cache_dict: dict[KeyType, Any],
+        num_candidates: int = 1,
+    ) -> list[KeyType]:
+        evict_keys = []
+        evict_freqs = []
+        for curr_min_freq, fifo_keys in self.freq_to_keys.items():
+            for key in fifo_keys:
+                if not cache_dict[key].can_evict:
+                    continue
+                evict_keys.append(key)
+                evict_freqs.append(curr_min_freq)
+                self.key_to_freq.pop(key)
+                if len(evict_keys) == num_candidates:
+                    break
+
+            if len(evict_keys) == num_candidates:
+                break
+
+        for freq, key in zip(evict_freqs, evict_keys, strict=False):
+            self.freq_to_keys[freq].pop(key)
+            if not self.freq_to_keys[freq]:
+                self.freq_to_keys.pop(freq)
+
+        return evict_keys
diff --git a/lmcache/v1/storage_backend/cache_policy/lru.py b/lmcache/v1/storage_backend/cache_policy/lru.py
new file mode 100644
index 0000000..ab45530
--- /dev/null
+++ b/lmcache/v1/storage_backend/cache_policy/lru.py
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from typing import Any, Dict
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.storage_backend.cache_policy.base_policy import BaseCachePolicy, KeyType
+
+logger = init_logger(__name__)
+
+
+class LRUCachePolicy(BaseCachePolicy[KeyType, OrderedDict[KeyType, Any]]):
+    """
+    LRU cache policy.
+    """
+
+    def __init__(self):
+        logger.info("Initializing LRUCachePolicy")
+        self.chunk_hash_to_init_timestamp: Dict[Any, float] = {}
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+        self.max_num_chunk_hash = 12500000
+
+    def init_mutable_mapping(self) -> OrderedDict[KeyType, Any]:
+        return OrderedDict()
+
+    def update_chunk_hash_dict(self, key: KeyType) -> None:
+        curr_time = time.time()
+        # HACK: doing type conversion here
+        key_hash: Any = key
+        if isinstance(key, CacheEngineKey):
+            key_hash = key.chunk_hash
+
+        if init_timestamp := self.chunk_hash_to_init_timestamp.get(key_hash, None):
+            time_interval = curr_time - init_timestamp
+            self.stats_monitor.on_chunk_reuse(time_interval)
+        else:
+            if len(self.chunk_hash_to_init_timestamp) >= self.max_num_chunk_hash:
+                self.chunk_hash_to_init_timestamp.clear()
+            self.chunk_hash_to_init_timestamp[key_hash] = curr_time
+
+    def update_on_hit(
+        self,
+        key: KeyType,
+        cache_dict: OrderedDict[KeyType, Any],
+    ) -> None:
+        self.update_chunk_hash_dict(key)
+        cache_dict.move_to_end(key)
+
+    def update_on_put(
+        self,
+        key: KeyType,
+    ) -> None:
+        self.update_chunk_hash_dict(key)
+        pass
+
+    def update_on_force_evict(
+        self,
+        key: KeyType,
+    ) -> None:
+        pass
+
+    # NOTE(Jiayi): We do best effort to get eviction candidates so the number
+    # of returned keys might be smaller than num_candidates.
+    def get_evict_candidates(
+        self,
+        cache_dict: OrderedDict[KeyType, Any],
+        num_candidates: int = 1,
+    ) -> list[KeyType]:
+        evict_keys = []
+        for key, cache in cache_dict.items():
+            if not cache.can_evict:
+                continue
+            evict_keys.append(key)
+            if len(evict_keys) == num_candidates:
+                break
+
+        return evict_keys
diff --git a/lmcache/v1/storage_backend/cache_policy/mru.py b/lmcache/v1/storage_backend/cache_policy/mru.py
new file mode 100644
index 0000000..f17e3c5
--- /dev/null
+++ b/lmcache/v1/storage_backend/cache_policy/mru.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from typing import Any
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.cache_policy.base_policy import BaseCachePolicy, KeyType
+
+logger = init_logger(__name__)
+
+
+class MRUCachePolicy(BaseCachePolicy[KeyType, OrderedDict[KeyType, Any]]):
+    """
+    MRU cache policy.
+    """
+
+    def __init__(self):
+        logger.info("Initializing MRUCachePolicy")
+
+    def init_mutable_mapping(self) -> OrderedDict[KeyType, Any]:
+        return OrderedDict()
+
+    def update_on_hit(
+        self,
+        key: KeyType,
+        cache_dict: OrderedDict[KeyType, Any],
+    ) -> None:
+        # since MRU evicts from the back, the logic is same as LRU.
+        cache_dict.move_to_end(key, last=True)
+
+    def update_on_put(
+        self,
+        key: KeyType,
+    ) -> None:
+        # No action needed for MRU on put, as the key is already at the back.
+        pass
+
+    def update_on_force_evict(
+        self,
+        key: KeyType,
+    ) -> None:
+        pass
+
+    # NOTE(Jiayi): We do best effort to get eviction candidates so the number
+    # of returned keys might be smaller than num_candidates.
+    def get_evict_candidates(
+        self,
+        cache_dict: OrderedDict[KeyType, Any],
+        num_candidates: int = 1,
+    ) -> list[KeyType]:
+        evict_keys = []
+        # Since the most recent object is at the end, we reverse the order here
+        for key, cache in reversed(cache_dict.items()):
+            if not cache.can_evict:
+                continue
+            evict_keys.append(key)
+            if len(evict_keys) == num_candidates:
+                break
+
+        return evict_keys
diff --git a/lmcache/v1/storage_backend/connector/__init__.py b/lmcache/v1/storage_backend/connector/__init__.py
new file mode 100644
index 0000000..ac78efc
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/__init__.py
@@ -0,0 +1,423 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+from urllib.parse import parse_qs, urlparse
+import asyncio
+import importlib
+import inspect
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.connector.instrumented_connector import (
+    InstrumentedRemoteConnector,
+)
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class ParsedRemoteURL:
+    """
+    The parsed URL of the format:
+        <host>:<port>[/path][?query]
+    """
+
+    host: str
+    port: int
+    path: str
+    username: Optional[str] = None
+    password: Optional[str] = None
+    query_params: Dict[str, List[str]] = field(default_factory=dict)
+
+
+def parse_remote_url(url: str) -> ParsedRemoteURL:
+    """
+    Parses the remote URL into its constituent parts with support for:
+    - Multiple hosts (comma-separated)
+    - Path and query parameters in each host definition
+    - Forward compatibility with legacy format
+
+    Args:
+        url: The URL to parse
+
+    Returns:
+        ParsedRemoteURL: The parsed URL components
+
+    Raises:
+        ValueError: If the URL is invalid
+    """
+
+    logger.debug(f"Parsing remote URL: {url}")
+    parsed = urlparse(url)
+
+    username = parsed.username
+    password = parsed.password
+    host = parsed.hostname
+    port = parsed.port
+    path = parsed.path if parsed.path else ""
+    query = parse_qs(parsed.query) if parsed.query else {}
+
+    assert host is not None, f"Invalid URL {url}: missing host"
+    assert port is not None, f"Invalid URL {url}: missing port"
+    return ParsedRemoteURL(
+        host=host,
+        port=port,
+        path=path,
+        username=username,
+        password=password,
+        query_params=query,
+    )
+
+
+class SafeLocalCPUBackend(LocalCPUBackend):
+    """
+    A safe stub for LocalCPUBackend that can be used when local_cpu_backend is None.
+    """
+
+    def __init__(self, config: LMCacheEngineConfig):
+        pass
+
+    def allocate(self, *args, **kwargs):
+        raise RuntimeError(
+            "SafeLocalCPUBackend.allocate() should never be called. "
+            "This indicates a bug where scheduler role is trying to allocate memory."
+        )
+
+    def __str__(self):
+        return "SafeLocalCPUBackend(dummy)"
+
+
+def extract_plugin_type(plugin_name: str) -> str:
+    """Extract the type portion from a plugin name.
+
+    Plugin name format: ``{type}`` or ``{type}.{instance}``.
+    Returns the *type* part so that adapters can match by type.
+
+    Examples:
+        >>> extract_plugin_type("fs")
+        'fs'
+        >>> extract_plugin_type("fs.primary")
+        'fs'
+    """
+    return plugin_name.split(".", 1)[0]
+
+
+class ConnectorContext:
+    """
+    Context for creating a connector.
+
+    Attributes:
+        url: The remote URL
+        loop: The asyncio event loop
+        local_cpu_backend: The local CPU backend
+            (wrapped as SafeLocalCPUBackend if None)
+        config: Optional LMCache engine configuration
+        plugin_name: Optional plugin instance name
+            (e.g. "fs", "fs.primary")
+    """
+
+    def __init__(
+        self,
+        url: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: Optional[LocalCPUBackend],
+        config: Optional[LMCacheEngineConfig],
+        metadata: Optional[LMCacheMetadata],
+        plugin_name: Optional[str] = None,
+    ):
+        self.url = url
+        self.loop = loop
+        # Wrap None as SafeLocalCPUBackend to satisfy type requirements
+        # The SafeLocalCPUBackend will raise an error if allocate() is called
+        self.local_cpu_backend: LocalCPUBackend = (
+            local_cpu_backend
+            if local_cpu_backend is not None
+            else SafeLocalCPUBackend(config)
+        )
+        self.config = config
+        self.metadata = metadata
+        self.plugin_name = plugin_name
+
+    def get_full_chunk_size_bytes(self) -> int:
+        """
+        return the number of bytes in a full chunk
+        useful for S3Connector where we need to preallocate filesystem buffers
+        in ramfs for zero-copy transfers
+        """
+        return self.local_cpu_backend.get_full_chunk_size_bytes()
+
+
+class ConnectorAdapter(ABC):
+    """Base class for connector adapters."""
+
+    def __init__(self, schema: str = "") -> None:
+        self.schema = schema
+
+    def can_parse(self, url: str) -> bool:
+        return self.schema != "" and url.startswith(self.schema)
+
+    @abstractmethod
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """
+        Create a connector using the given context.
+        """
+        pass
+
+
+class DynamicConnectorAdapter(ConnectorAdapter):
+    """Adapter that wraps a RemoteConnector class loaded
+    dynamically from plugin config.
+
+    When ``class_name`` points to a ``RemoteConnector`` subclass
+    rather than a ``ConnectorAdapter``, this wrapper is used to
+    instantiate the connector with the proper context.
+    """
+
+    def __init__(
+        self,
+        plugin_name: str,
+        connector_class: type,
+    ) -> None:
+        schema = "plugin://%s" % extract_plugin_type(plugin_name)
+        super().__init__(schema)
+        self._plugin_name = plugin_name
+        self._connector_class = connector_class
+
+    def can_parse(self, url: str) -> bool:
+        if url.startswith(self.schema):
+            return True
+        if url.startswith("plugin://"):
+            pname = url[len("plugin://") :]
+            return extract_plugin_type(pname) == extract_plugin_type(self._plugin_name)
+        return False
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        logger.info(
+            "Creating dynamic connector %s via %s",
+            self._plugin_name,
+            self._connector_class.__name__,
+        )
+        return self._connector_class(
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            config=context.config,
+        )
+
+
+class ConnectorManager:
+    """
+    Manager for creating connectors based on URL.
+
+    This class maintains a registry of connector adapters and creates
+    the appropriate connector based on the URL.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: Optional[LocalCPUBackend],
+        config: Optional[LMCacheEngineConfig] = None,
+        metadata: Optional[LMCacheMetadata] = None,
+        plugin_name: Optional[str] = None,
+    ) -> None:
+        logger.info("Initializing ConnectorManager")
+        self.context = ConnectorContext(
+            url=url,
+            loop=loop,
+            local_cpu_backend=local_cpu_backend,
+            config=config,
+            metadata=metadata,
+            plugin_name=plugin_name,
+        )
+        self.adapters: List[ConnectorAdapter] = []
+        self._remote_adapters_builtin_launcher()
+        self._remote_adapters_plugin_launcher(config)
+
+    def _remote_adapters_builtin_launcher(self) -> None:
+        """Automatically load all builtin remote connector adapters."""
+        for cls in discover_subclasses(
+            "lmcache.v1.storage_backend.connector",
+            ConnectorAdapter,  # type: ignore[type-abstract]
+            module_filter=lambda name: (
+                not name.startswith("_") and name.endswith("_adapter")
+            ),
+            require_defined_in_module=False,
+        ):
+            try:
+                self.adapters.append(cls())
+                logger.info(f"Discovered adapter: {cls.__name__}")
+            except Exception as e:
+                logger.error(f"Failed to instantiate adapter {cls.__name__}: {str(e)}")
+
+    def _remote_adapters_plugin_launcher(self, config: LMCacheEngineConfig) -> None:
+        """Automatically load all plug and play remote connector adapters."""
+
+        if config is None:
+            logger.warning(
+                "Configuration not available to parse remote connector adapters."
+            )
+            return
+
+        # Get the list of allowed remote connector adapters if configured
+        remote_storage_plugins = (
+            set(config.remote_storage_plugins)
+            if config.remote_storage_plugins
+            else set()
+        )
+
+        for remote_storage_plugin in remote_storage_plugins:
+            try:
+                extra_config = config.extra_config
+
+                module_path = (
+                    extra_config.get(
+                        "remote_storage_plugin.%s.module_path" % remote_storage_plugin
+                    )
+                    if extra_config
+                    else None
+                )
+                class_name = (
+                    extra_config.get(
+                        "remote_storage_plugin.%s.class_name" % remote_storage_plugin
+                    )
+                    if extra_config
+                    else None
+                )
+
+                if not module_path or not class_name:
+                    # Skip silently when a builtin adapter
+                    # already handles this plugin type.
+                    plugin_url = "plugin://%s" % remote_storage_plugin
+                    if any(a.can_parse(plugin_url) for a in self.adapters):
+                        continue
+                    logger.warning(
+                        "Remote connector %s missing adapter module_path or class_name",
+                        remote_storage_plugin,
+                    )
+                    continue
+
+                # Dynamically import the module
+                module = importlib.import_module(module_path)
+                # Get the class from the module
+                loaded_class = getattr(module, class_name)
+
+                if inspect.isclass(loaded_class) and issubclass(
+                    loaded_class, ConnectorAdapter
+                ):
+                    adapter_instance = loaded_class()
+                elif inspect.isclass(loaded_class) and issubclass(
+                    loaded_class, RemoteConnector
+                ):
+                    adapter_instance = DynamicConnectorAdapter(
+                        plugin_name=remote_storage_plugin,
+                        connector_class=loaded_class,
+                    )
+                else:
+                    logger.warning(
+                        "Remote connector %s class %s is "
+                        "neither a ConnectorAdapter nor a "
+                        "RemoteConnector subclass",
+                        remote_storage_plugin,
+                        class_name,
+                    )
+                    continue
+                self.adapters.append(adapter_instance)
+                logger.info(
+                    "Discovered adapter: %s",
+                    loaded_class.__name__,
+                )
+            except (ImportError, AttributeError) as e:
+                logger.error(
+                    f"Failed to load remote connector {remote_storage_plugin} due to "
+                    f"import/attribute error: {e}"
+                )
+            except Exception as e:
+                logger.error(
+                    f"Failed to create remote connector {remote_storage_plugin} "
+                    f"adapter: {str(e)}"
+                )
+
+    def create_connector(self) -> RemoteConnector:
+        for adapter in self.adapters:
+            if adapter.can_parse(self.context.url):
+                logger.info(f"Creating connector for URL: {self.context.url}")
+                connector = adapter.create_connector(self.context)
+                return connector
+
+        raise ValueError(f"No adapter found for URL: {self.context.url}")
+
+
+def CreateConnector(
+    url: str,
+    loop: asyncio.AbstractEventLoop,
+    local_cpu_backend: Optional[LocalCPUBackend],
+    config: Optional[LMCacheEngineConfig] = None,
+    metadata: Optional[LMCacheMetadata] = None,
+    plugin_name: Optional[str] = None,
+) -> InstrumentedRemoteConnector:
+    """
+    Create a remote connector from the given URL.
+
+    Supported URL formats:
+    - redis://[[username]:[password]@]host[:port][/database][?option=value]
+    - rediss://[[username]:[password]@]host[:port][/database][?option=value] (SSL)
+    - redis-sentinel://[[username]:[password]@]host1:port1[,host2:port2,...]/service_name
+    - lm://host:port
+    - infinistore://host:port[?device=device_name]
+    - mooncakestore://host:port[?device=device_name]
+    - blackhole://[any_text]
+    - audit://host:port[?verify=true|false]
+    - fs://[host:port]/path
+    - s3://[bucket].s3express-[az_id].[region].amazonaws.com"
+    - mock://[capacity]/?peeking_latency=[ms]&read_throughput=[GB/s]&write_throughput=[GB/s]
+    or
+    - s3://[bucket].s3.[region].amazonaws.com
+
+    Examples:
+    - redis://localhost:6379
+    - rediss://user:password@redis.example.com:6380/0
+    - redis-sentinel://user:password@sentinel1:26379,sentinel2:26379/mymaster
+    - lm://localhost:65432
+    - infinistore://127.0.0.1:12345?device=mlx5_0
+    - mooncakestore://127.0.0.1:50051
+    - blackhole://
+    - audit://localhost:8080?verify=true
+    - fs:///tmp/lmcache
+    - external://host:0/external_log_connector.lmc_external_log_connector/?connector_name=ExternalLogConnector
+    - s3://fakefile--use1-az4--x-s3.s3express-use1-az4.us-east-1.amazonaws.com
+    - mock://100/?peeking_latency=1&read_throughput=2&write_throughput=2
+    or
+    - s3://fakefile--use1-az4--x-s3.s3.us-east-1.amazonaws.com
+
+    Args:
+        url: The remote URL
+        loop: The asyncio event loop
+        local_cpu_backend: The local CPU backend (can be None for scheduler role)
+        config: Optional LMCache engine configuration
+        metadata: Optional LMCache engine metadata
+
+    Returns:
+        RemoteConnector: The created connector
+
+    Raises:
+        ValueError: If the connector cannot be created
+    """
+
+    # Basic URL validation - check for scheme
+    if "://" not in url:
+        raise ValueError(f"Invalid remote url {url}: missing scheme")
+
+    manager = ConnectorManager(
+        url, loop, local_cpu_backend, config, metadata, plugin_name
+    )
+    connector = manager.create_connector()
+
+    return InstrumentedRemoteConnector(connector)
diff --git a/lmcache/v1/storage_backend/connector/audit_adapter.py b/lmcache/v1/storage_backend/connector/audit_adapter.py
new file mode 100644
index 0000000..681aefb
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/audit_adapter.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    CreateConnector,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class AuditConnectorAdapter(ConnectorAdapter):
+    """Adapter for Audit connectors (for debugging and verification)."""
+
+    def __init__(self) -> None:
+        super().__init__("audit://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .audit_connector import AuditConnector
+
+        """
+        Create an Audit connector. This connector wraps another connector
+        and audits all operations.
+        
+        extra_config:
+        - audit_actual_remote_url: The actual remote URL to connect to.
+        - audit_calc_checksum: Whether to calculate checksums.
+        - audit_verify_checksum: Whether to verify checksums.
+
+        URL format:
+        - audit://host:port[?verify=true|false]
+
+        Examples:
+        - audit://localhost:8080
+        - audit://audit-server.example.com:8080?verify=true
+        - audit://127.0.0.1:8080?verify=false
+        """
+        logger.info(f"Creating Audit connector for URL: {context.url}")
+        hosts = context.url.split(",")
+        if len(hosts) > 1:
+            raise ValueError(
+                f"Only one host is supported for audit connector, but got {hosts}"
+            )
+        if not context.config:
+            raise ValueError("Config is not set")
+
+        parse_url = parse_remote_url(context.url)
+        # (Deprecated) verify URL parameter will be removed in future versions
+        # Use the extra config instead
+        verify_param = parse_url.query_params.get("verify", ["false"])[0]
+        verify_checksum = verify_param.lower() in ("true", "1", "yes")
+        # Get the actual remote URL from the extra config first to keep consistency
+        real_url = context.config.extra_config.get(
+            "audit_actual_remote_url", context.config.audit_actual_remote_url
+        )
+        if not real_url:
+            raise ValueError(
+                "audit_actual_remote_url is not set in the config or extra_config"
+            )
+        # Store verify_checksum in extra_config if not already set
+        if context.config.extra_config is None:
+            context.config.extra_config = {}
+        if "audit_verify_checksum" not in context.config.extra_config:
+            context.config.extra_config["audit_verify_checksum"] = verify_checksum
+        connector = CreateConnector(
+            real_url,
+            context.loop,
+            context.local_cpu_backend,
+            context.config,
+            context.metadata,
+        )
+        # Metaclass dynamically implements all abstract methods at runtime
+        return AuditConnector(connector.getWrappedConnector(), context.config)  # type: ignore[abstract]
diff --git a/lmcache/v1/storage_backend/connector/audit_connector.py b/lmcache/v1/storage_backend/connector/audit_connector.py
new file mode 100644
index 0000000..4ac33d8
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/audit_connector.py
@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from threading import Lock
+from typing import Dict, Optional
+import abc
+import asyncio
+import functools
+import hashlib
+import logging
+import time
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = logging.getLogger(__name__)
+
+
+class AuditConnectorMeta(abc.ABCMeta):
+    """Metaclass that dynamically generates wrapper methods for all
+    RemoteConnector methods
+    """
+
+    def __new__(mcs, name, bases, namespace):
+        # Get all methods from RemoteConnector including abstract methods
+        # We need to check both the class dict and inherited methods
+        all_methods = {}
+
+        # Collect methods from RemoteConnector and its bases
+        for base in RemoteConnector.__mro__:
+            for method_name, method_obj in base.__dict__.items():
+                if method_name not in all_methods and callable(method_obj):
+                    all_methods[method_name] = method_obj
+
+        for method_name, method in all_methods.items():
+            # Skip private methods and methods already defined in namespace
+            if method_name.startswith("_") or method_name in namespace:
+                continue
+
+            # Skip class methods, static methods, and properties
+            if isinstance(method, (classmethod, staticmethod, property)):
+                continue
+
+            # Check if method is marked with @NotAudit
+            is_not_audit = getattr(method, "_not_audit", False)
+
+            # Determine if method is async
+            is_async = asyncio.iscoroutinefunction(method)
+
+            # Create appropriate wrapper and add to namespace
+            if is_not_audit:
+                if is_async:
+                    namespace[method_name] = mcs._create_passthrough_async_method(
+                        method_name, method
+                    )
+                else:
+                    namespace[method_name] = mcs._create_passthrough_sync_method(
+                        method_name, method
+                    )
+            else:
+                if is_async:
+                    namespace[method_name] = mcs._create_audit_async_method(
+                        method_name, method
+                    )
+                else:
+                    namespace[method_name] = mcs._create_audit_sync_method(
+                        method_name, method
+                    )
+
+        # Create the class with all methods in namespace
+        cls = super().__new__(mcs, name, bases, namespace)
+
+        # Clear abstract methods since we've implemented them all via wrappers
+        # The wrappers delegate to real_connector which has the actual implementations
+        if hasattr(cls, "__abstractmethods__"):
+            cls.__abstractmethods__ = frozenset()
+
+        return cls
+
+    @staticmethod
+    def _create_passthrough_async_method(method_name: str, original_method):
+        """Create a pass-through async method without logging"""
+
+        @functools.wraps(original_method)
+        async def wrapper(self, *args, **kwargs):
+            real_method = getattr(self.real_connector, method_name)
+            return await real_method(*args, **kwargs)
+
+        wrapper.__name__ = method_name
+        wrapper.__qualname__ = f"AuditConnector.{method_name}"
+        return wrapper
+
+    @staticmethod
+    def _create_passthrough_sync_method(method_name: str, original_method):
+        """Create a pass-through sync method without logging"""
+
+        @functools.wraps(original_method)
+        def wrapper(self, *args, **kwargs):
+            real_method = getattr(self.real_connector, method_name)
+            return real_method(*args, **kwargs)
+
+        wrapper.__name__ = method_name
+        wrapper.__qualname__ = f"AuditConnector.{method_name}"
+        return wrapper
+
+    @staticmethod
+    def _create_audit_async_method(method_name: str, original_method):
+        """Create an audit async method with logging"""
+
+        @functools.wraps(original_method)
+        async def wrapper(self, *args, **kwargs):
+            # Special handling for put/get methods with checksum
+            if method_name == "put":
+                return await self._audit_put(*args, **kwargs)
+            elif method_name == "get":
+                return await self._audit_get(*args, **kwargs)
+
+            # Check if method is in excluded commands
+            if hasattr(self, "excluded_cmds") and method_name in self.excluded_cmds:
+                real_method = getattr(self.real_connector, method_name)
+                return await real_method(*args, **kwargs)
+
+            # Generic audit logging
+            self.logger.debug(
+                f"[REMOTE_AUDIT][{self.real_connector}]:{method_name.upper()}|START"
+            )
+            t1 = time.perf_counter()
+            try:
+                real_method = getattr(self.real_connector, method_name)
+                result = await real_method(*args, **kwargs)
+                t2 = time.perf_counter()
+                cost = (t2 - t1) * 1000
+                self.logger.info(
+                    f"[REMOTE_AUDIT][{self.real_connector}]:{method_name.upper()}|"
+                    f"SUCCESS|Cost:{cost:.6f}ms"
+                )
+                return result
+            except Exception as e:
+                self.logger.error(
+                    f"[REMOTE_AUDIT][{self.real_connector}]:{method_name.upper()}|"
+                    f"FAILED|Error: {str(e)}"
+                )
+                raise
+
+        wrapper.__name__ = method_name
+        wrapper.__qualname__ = f"AuditConnector.{method_name}"
+        return wrapper
+
+    @staticmethod
+    def _create_audit_sync_method(method_name: str, original_method):
+        """Create an audit sync method with logging"""
+
+        @functools.wraps(original_method)
+        def wrapper(self, *args, **kwargs):
+            # Check if method is in excluded commands
+            if hasattr(self, "excluded_cmds") and method_name in self.excluded_cmds:
+                real_method = getattr(self.real_connector, method_name)
+                return real_method(*args, **kwargs)
+
+            self.logger.debug(
+                f"[REMOTE_AUDIT][{self.real_connector}]:{method_name.upper()}|START"
+            )
+            t1 = time.perf_counter()
+            try:
+                real_method = getattr(self.real_connector, method_name)
+                result = real_method(*args, **kwargs)
+                t2 = time.perf_counter()
+                cost = (t2 - t1) * 1000
+                self.logger.info(
+                    f"[REMOTE_AUDIT][{self.real_connector}]:{method_name.upper()}|"
+                    f"SUCCESS|Cost:{cost:.6f}ms"
+                )
+                return result
+            except Exception as e:
+                self.logger.error(
+                    f"[REMOTE_AUDIT][{self.real_connector}]:{method_name.upper()}|"
+                    f"FAILED|Error: {str(e)}"
+                )
+                raise
+
+        wrapper.__name__ = method_name
+        wrapper.__qualname__ = f"AuditConnector.{method_name}"
+        return wrapper
+
+
+class AuditConnector(RemoteConnector, metaclass=AuditConnectorMeta):
+    """Audit wrapper for RemoteConnector that dynamically wraps all methods.
+
+    Features:
+    - Automatically wraps all RemoteConnector methods
+    - Methods marked with @NotAudit are forwarded without logging
+    - Configurable checksum verification via URL parameter
+    - Logs all operations with timestamps
+    - Optional checksum validation for put/get operations
+    """
+
+    def __init__(
+        self, real_connector: RemoteConnector, lmcache_config: LMCacheEngineConfig
+    ):
+        self.real_connector = real_connector
+        self.verify_checksum = (
+            lmcache_config.extra_config is not None
+            and "audit_verify_checksum" in lmcache_config.extra_config
+            and lmcache_config.extra_config["audit_verify_checksum"]
+        )
+        self.calc_checksum = (
+            lmcache_config.extra_config is not None
+            and "audit_calc_checksum" in lmcache_config.extra_config
+            and lmcache_config.extra_config["audit_calc_checksum"]
+        )
+        self.checksum_registry: Dict[CacheEngineKey, str] = {}
+        self.registry_lock = Lock() if self.verify_checksum else None
+
+        # Parse audit exclude commands
+        self.excluded_cmds = set()
+        if (
+            lmcache_config.extra_config
+            and "audit_exclude_cmds" in lmcache_config.extra_config
+        ):
+            exclude_cmds = lmcache_config.extra_config["audit_exclude_cmds"]
+            if exclude_cmds:
+                self.excluded_cmds = {cmd.strip() for cmd in exclude_cmds.split(",")}
+
+        self.logger = logger.getChild("audit")
+
+        logger.info(
+            f"[REMOTE_AUDIT][{self.real_connector}]:INITIALIZED|"
+            f"Calc Checksum:{self.calc_checksum}｜"
+            f"Verify Checksum: {self.verify_checksum}|"
+            f"Excluded Cmds: {self.excluded_cmds}"
+        )
+
+    def _calculate_checksum(self, data: bytes) -> str:
+        """Calculate SHA-256 checksum for data validation"""
+        return hashlib.sha256(data).hexdigest()
+
+    async def _audit_put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Store data with optional checksum tracking"""
+        data = memory_obj.byte_array
+        checksum = self._calculate_checksum(data) if self.calc_checksum else "N/A"
+        data_size = len(data)
+        self.logger.debug(
+            f"[REMOTE_AUDIT][{self.real_connector}]:PUT|START|Size:{data_size}|"
+            f"Checksum:{checksum[:8]}|Saved:{len(self.checksum_registry)}|Key:{key}"
+        )
+
+        try:
+            t1 = time.perf_counter()
+            await self.real_connector.put(key, memory_obj)
+            t2 = time.perf_counter()
+            cost = (t2 - t1) * 1000
+            if self.registry_lock:
+                with self.registry_lock:
+                    self.checksum_registry[key] = checksum
+            self.logger.info(
+                f"[REMOTE_AUDIT][{self.real_connector}]:PUT|SUCCESS|Size:{data_size}|"
+                f"Checksum:{checksum[:8]}|Cost:{cost:.6f}ms|Saved:"
+                f"{len(self.checksum_registry)}|Key:{key}"
+            )
+
+        except Exception as e:
+            self.logger.error(
+                f"[REMOTE_AUDIT][{self.real_connector}]:PUT|FAILED|Size:{data_size}|"
+                f"Key:{key}|Error: {str(e)}"
+            )
+            raise
+
+    async def _audit_get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Retrieve data with optional integrity check"""
+        self.logger.debug(
+            f"[REMOTE_AUDIT][{self.real_connector}]:GET|START|"
+            f"Saved:{len(self.checksum_registry)}|Key:{key}"
+        )
+
+        try:
+            t1 = time.perf_counter()
+            result = await self.real_connector.get(key)
+            t2 = time.perf_counter()
+            if result is None:
+                self.logger.info(
+                    f"[REMOTE_AUDIT][{self.real_connector}]:GET|MISS|Key:{key}|"
+                    f"Saved: {len(self.checksum_registry)}"
+                )
+                return None
+
+            current_data = result.byte_array
+            current_checksum = (
+                self._calculate_checksum(current_data) if self.calc_checksum else "N/A"
+            )
+            data_size = len(current_data)
+
+            if self.registry_lock:
+                with self.registry_lock:
+                    expected_checksum = self.checksum_registry.get(key)
+
+                if expected_checksum and current_checksum != expected_checksum:
+                    self.logger.error(
+                        f"[REMOTE_AUDIT][{self.real_connector}]:"
+                        f"GET|MISMATCH|Size:{data_size}|"
+                        f"Expected:<{expected_checksum[:8]}>|"
+                        f"Actual:<{current_checksum[:8]}>|Key:{key}"
+                    )
+                    return None
+
+            cost = (t2 - t1) * 1000
+            self.logger.info(
+                f"[REMOTE_AUDIT][{self.real_connector}]:GET|SUCCESS|"
+                f"Checksum:{current_checksum[:8]}|"
+                f"Cost:{cost:.6f}ms|Saved:{len(self.checksum_registry)}|Key:{key}"
+            )
+            return result
+
+        except Exception as e:
+            self.logger.error(
+                f"[REMOTE_AUDIT][{self.real_connector}]:GET|"
+                f"FAILED|Key:{key}|Error: {str(e)}"
+            )
+            raise
diff --git a/lmcache/v1/storage_backend/connector/azure_adapter.py b/lmcache/v1/storage_backend/connector/azure_adapter.py
new file mode 100644
index 0000000..8224648
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/azure_adapter.py
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class AzureConnectorAdapter(ConnectorAdapter):
+    """Adapter for native Azure Blob Storage connectors.
+
+    URL format:
+        azure://<container_name>
+
+    Auth and account settings are read from ``config.extra_config``:
+        - azure_account_url     (https://<account>.blob.core.windows.net)
+        - azure_connection_string
+        - azure_account_key
+        - azure_sas_token
+    If none of the credential fields are set, DefaultAzureCredential is used.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("azure://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """Create an :class:`AzureConnector` from the given context.
+
+        Args:
+            context: The connector context carrying the URL, event loop,
+                local CPU backend, config, and metadata.
+
+        Returns:
+            A configured :class:`AzureConnector`.
+
+        Raises:
+            ValueError: If ``context.config`` is missing, ``context.metadata``
+                is missing, or the URL does not include a container name.
+        """
+        # Local
+        from .azure_connector import AzureConnector
+
+        config = context.config
+        if config is None:
+            raise ValueError("config is required for AzureConnectorAdapter")
+        extra_config = config.extra_config if config.extra_config is not None else {}
+
+        if context.metadata is None:
+            raise ValueError("metadata is required for AzureConnector")
+
+        container = context.url.removeprefix("azure://").strip("/")
+        if not container:
+            raise ValueError(
+                "Azure url must include a container: azure://<container_name>"
+            )
+
+        logger.info(f"Creating Azure connector for container: {container}")
+
+        return AzureConnector(
+            container=container,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            account_url=extra_config.get("azure_account_url"),
+            connection_string=extra_config.get("azure_connection_string"),
+            account_key=extra_config.get("azure_account_key"),
+            sas_token=extra_config.get("azure_sas_token"),
+        )
diff --git a/lmcache/v1/storage_backend/connector/azure_connector.py b/lmcache/v1/storage_backend/connector/azure_connector.py
new file mode 100644
index 0000000..bb634a6
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/azure_connector.py
@@ -0,0 +1,316 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, List, Optional
+from urllib.parse import quote as url_quote
+import asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+if TYPE_CHECKING:
+    # Third Party
+    from azure.storage.blob.aio import ContainerClient
+
+logger = init_logger(__name__)
+
+
+class AzureConnector(RemoteConnector):
+    """
+    Native Azure Blob Storage remote connector.
+
+    Mirrors the S3Connector contract but talks to Azure Blob Storage via
+    ``azure-storage-blob`` (async client). The SDK is imported lazily inside
+    ``__init__`` so that ``azure-storage-blob`` remains an optional dependency.
+
+    Keys are flattened into a single blob name per chunk (slashes replaced and
+    URL-encoded), matching the flat layout S3Connector uses.
+    """
+
+    def __init__(
+        self,
+        container: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        account_url: Optional[str] = None,
+        connection_string: Optional[str] = None,
+        account_key: Optional[str] = None,
+        sas_token: Optional[str] = None,
+    ) -> None:
+        """Initialize the Azure Blob connector.
+
+        Exactly one credential path is used, resolved most-explicit-first:
+        ``connection_string`` wins; otherwise ``account_url`` is required and
+        is paired with ``account_key``, then ``sas_token``, then (if neither is
+        given) ``DefaultAzureCredential``.
+
+        Args:
+            container: The target blob container name.
+            loop: The asyncio event loop the connector runs its I/O on.
+            local_cpu_backend: Backend used to allocate MemoryObj buffers.
+            account_url: Storage account URL, e.g.
+                ``https://<account>.blob.core.windows.net``. Required unless
+                ``connection_string`` is provided.
+            connection_string: Full Azure Storage connection string.
+            account_key: Storage account shared key.
+            sas_token: Shared Access Signature token.
+
+        Raises:
+            ImportError: If ``azure-storage-blob`` is not installed, or if
+                ``azure-identity`` is not installed when falling back to
+                ``DefaultAzureCredential``.
+            ValueError: If neither ``connection_string`` nor ``account_url``
+                is provided.
+        """
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        # Lazy import keeps azure-storage-blob optional.
+        try:
+            # Third Party
+            from azure.storage.blob.aio import BlobServiceClient
+        except ImportError as e:
+            raise ImportError(
+                "azure-storage-blob is required for the Azure connector. "
+                "Install it with `pip install azure-storage-blob`."
+            ) from e
+
+        self.container = container
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+        self.part_size = self.full_chunk_size_bytes
+
+        # ---- Auth resolution (most explicit first) ----------------------
+        if connection_string:
+            logger.info("AzureConnector: authenticating via connection string")
+            self.service_client = BlobServiceClient.from_connection_string(
+                connection_string
+            )
+        else:
+            if account_url is None:
+                raise ValueError(
+                    "AzureConnector requires either `connection_string` or "
+                    "`account_url` (e.g. https://<account>.blob.core.windows.net)."
+                )
+            if account_key:
+                logger.info("AzureConnector: authenticating via account key")
+                credential: object = account_key
+            elif sas_token:
+                logger.info("AzureConnector: authenticating via SAS token")
+                credential = sas_token
+            else:
+                logger.info(
+                    "AzureConnector: no explicit credential, "
+                    "falling back to DefaultAzureCredential"
+                )
+                try:
+                    # Third Party
+                    from azure.identity.aio import DefaultAzureCredential
+                except ImportError as e:
+                    raise ImportError(
+                        "azure-identity is required to use "
+                        "DefaultAzureCredential. Install it with "
+                        "`pip install azure-identity`, or provide an "
+                        "explicit credential (connection_string, account_key, "
+                        "or sas_token)."
+                    ) from e
+
+                credential = DefaultAzureCredential()
+            self.service_client = BlobServiceClient(
+                account_url=account_url, credential=credential
+            )
+
+        self.container_client: "ContainerClient" = (
+            self.service_client.get_container_client(container)
+        )
+
+        # Cache of known blob sizes (read-only assumption, like S3Connector).
+        self.object_size_cache: dict[str, int] = {}
+
+    # ------------------------------------------------------------------ #
+    # helpers
+    # ------------------------------------------------------------------ #
+    def _blob_name(self, key_str: str) -> str:
+        """Flatten a key into a safe blob name."""
+        return url_quote(key_str.replace("/", "_"), safe="")
+
+    async def _get_blob_size_async(self, key_str: str) -> int:
+        """Return the blob size in bytes for ``key_str``, or 0 if the blob is
+        absent or its properties cannot be read.
+        """
+        # Third Party
+        from azure.core.exceptions import ResourceNotFoundError
+
+        blob = self.container_client.get_blob_client(self._blob_name(key_str))
+        try:
+            props = await blob.get_blob_properties()
+            return props.size or 0
+        except ResourceNotFoundError:
+            logger.debug(f"Blob not found: {key_str}")
+            return 0
+        except Exception as e:
+            logger.warning(f"Azure HEAD/properties error for {key_str}: {e}")
+            return 0
+
+    # ------------------------------------------------------------------ #
+    # exists
+    # ------------------------------------------------------------------ #
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """Check whether a chunk for ``key`` exists in the container.
+
+        Consults the local blob-size cache first to avoid a network round-trip
+        when the size is already known.
+
+        Args:
+            key: The cache engine key to look up.
+
+        Returns:
+            True if a blob for the key exists, False otherwise.
+        """
+        key_str = key.to_string()
+        cached = self.object_size_cache.get(key_str)
+        if cached is not None:
+            return cached > 0
+        size = await self._get_blob_size_async(key_str)
+        # Cache misses too (size 0) so repeated lookups of an absent key
+        # don't trigger a network round-trip each time, matching get().
+        self.object_size_cache[key_str] = size
+        return size > 0
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Synchronous variant of :meth:`exists`.
+
+        Drives the async :meth:`exists` coroutine to completion on the
+        connector's event loop, since the aio client exposes no sync API.
+
+        Args:
+            key: The cache engine key to look up.
+
+        Returns:
+            True if a blob for the key exists, False otherwise.
+        """
+        # The async aio client has no sync path; drive the coroutine on the loop.
+        return asyncio.run_coroutine_threadsafe(self.exists(key), self.loop).result()
+
+    # ------------------------------------------------------------------ #
+    # get
+    # ------------------------------------------------------------------ #
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Download the chunk for ``key`` into a freshly allocated MemoryObj.
+
+        The blob is streamed directly into the preallocated buffer (zero-copy).
+
+        Args:
+            key: The cache engine key to fetch.
+
+        Returns:
+            The populated MemoryObj, or None on a cache miss, allocation
+            failure, a size mismatch against the current model/chunk
+            configuration, or any download error.
+        """
+        key_str = key.to_string()
+
+        obj_size = self.object_size_cache.get(key_str)
+        if obj_size is None:
+            obj_size = await self._get_blob_size_async(key_str)
+            if obj_size <= 0:
+                self.object_size_cache[key_str] = 0
+                return None
+            self.object_size_cache[key_str] = obj_size
+
+        memory_obj = self.local_cpu_backend.allocate(
+            self.meta_shapes,
+            self.meta_dtypes,
+            self.meta_fmt,
+        )
+        if memory_obj is None:
+            return None
+
+        if obj_size != memory_obj.get_size():
+            logger.error(
+                f"Size mismatch for {key_str}: Azure has {obj_size} bytes, "
+                f"but current config expects {memory_obj.get_size()} bytes. "
+                f"This usually means the data was stored with a different "
+                f"chunk_size or model configuration."
+            )
+            memory_obj.ref_count_down()
+            return None
+
+        try:
+            blob = self.container_client.get_blob_client(self._blob_name(key_str))
+            downloader = await blob.download_blob()
+            # Zero-copy: stream straight into the preallocated buffer.
+            await downloader.readinto(memory_obj.byte_array)
+            return memory_obj
+        except Exception as e:
+            logger.error(f"Failed to download {key_str} from Azure: {e}")
+            memory_obj.ref_count_down()
+            return None
+
+    # ------------------------------------------------------------------ #
+    # put
+    # ------------------------------------------------------------------ #
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        """Upload ``memory_obj`` to the container under ``key``.
+
+        Only full chunks are supported: a chunk whose physical size does not
+        match the connector's expected part size is skipped with an error log.
+        Existing blobs with the same name are overwritten.
+
+        Note:
+            The caller (``InstrumentedRemoteConnector.put``) owns the reference
+            count of ``memory_obj`` and decrements it after this returns; this
+            method must not call ``ref_count_down`` itself, matching
+            ``S3Connector``.
+
+        Args:
+            key: The cache engine key to store under.
+            memory_obj: The memory object holding the chunk bytes.
+        """
+        key_str = key.to_string()
+
+        if memory_obj.get_physical_size() != self.part_size:
+            logger.error(
+                f"Cannot upload {key_str}: chunk size "
+                f"{memory_obj.get_physical_size()} bytes does not match expected "
+                f"part size {self.part_size} bytes. "
+                f"Partial/unfull chunks are not supported."
+            )
+            return
+
+        try:
+            blob = self.container_client.get_blob_client(self._blob_name(key_str))
+            # Pass the memoryview directly (zero-copy); bytes() would copy the
+            # whole chunk.
+            await blob.upload_blob(
+                memory_obj.byte_array,
+                overwrite=True,
+                length=memory_obj.get_physical_size(),
+            )
+            self.object_size_cache[key_str] = memory_obj.get_physical_size()
+            logger.debug(f"Uploaded {key_str} to Azure successfully")
+        except Exception as e:
+            logger.error(f"Failed to upload {key_str} to Azure: {e}")
+
+    # ------------------------------------------------------------------ #
+    # list / close
+    # ------------------------------------------------------------------ #
+    async def list(self) -> List[str]:
+        """List the names of all blobs currently in the container.
+
+        Returns:
+            A list of blob names.
+        """
+        names: List[str] = []
+        async for blob in self.container_client.list_blobs():
+            names.append(blob.name)
+        return names
+
+    async def close(self) -> None:
+        """Close the underlying Azure Blob service client and release its
+        network resources.
+        """
+        await self.service_client.close()
diff --git a/lmcache/v1/storage_backend/connector/base_connector.py b/lmcache/v1/storage_backend/connector/base_connector.py
new file mode 100644
index 0000000..405780d
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/base_connector.py
@@ -0,0 +1,379 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional
+import abc
+import asyncio
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.protocol import get_remote_metadata_bytes, init_remote_metadata_info
+
+logger = init_logger(__name__)
+
+
+def NotAudit(func):
+    """
+    Decorator to mark methods that should not be audited.
+    These methods will be directly forwarded to the real connector without logging.
+    """
+    func._not_audit = True
+    return func
+
+
+class RemoteConnector(metaclass=abc.ABCMeta):
+    """
+    Interface for remote connector
+    """
+
+    def __init__(
+        self, config: LMCacheEngineConfig, metadata: Optional[LMCacheMetadata]
+    ):
+        """
+        Initialize some common attributes, which will be used in the subclasses.
+        - `save_chunk_meta` is a flag to indicate whether to save the chunk meta info.
+        - `meta_shapes` is a list of shapes of lmcache full chunk.
+        - `meta_dtypes` is a list of dtypes of lmcache chunk.
+        - `meta_fmt` is the memory format of the lmcache chunk.
+        - `full_chunk_size_bytes` is the size of the lmcache full chunk.
+        - `single_token_size` is the size of a single token.`
+        - `remote_metadata_bytes` is the size of the remote metadata.
+
+        Input:
+            config: the lmcache engine config
+            metadata: the lmcache engine metadata
+        """
+        # TODO(chunxiaozheng): support layerwise here
+        assert metadata is not None
+        self.save_chunk_meta: bool = (
+            config.extra_config is None
+            or config.extra_config.get("save_chunk_meta", True)
+            or config.use_layerwise
+        )
+        self.meta_shapes: list[torch.Size] = metadata.get_shapes()
+        self.meta_dtypes: list[torch.dtype] = metadata.get_dtypes()
+        self.meta_fmt: MemoryFormat = (
+            MemoryFormat.KV_MLA_FMT if metadata.use_mla else MemoryFormat.KV_2LTD
+        )
+        self.full_chunk_size_bytes: int = get_size_bytes(
+            self.meta_shapes, self.meta_dtypes
+        )
+        assert self.full_chunk_size_bytes % metadata.chunk_size == 0
+        self.single_token_size = self.full_chunk_size_bytes // metadata.chunk_size
+
+        # init remote metadata info
+        init_remote_metadata_info(metadata.get_num_groups())
+        self.remote_metadata_bytes = get_remote_metadata_bytes()
+        logger.info(
+            "init remote connector metadata info, shapes: %s, dtypes: %s, fmt: %s, "
+            "full chunk size: %s, single token size: %s, remote metadata bytes: %s",
+            self.meta_shapes,
+            self.meta_dtypes,
+            self.meta_fmt,
+            self.full_chunk_size_bytes,
+            self.single_token_size,
+            self.remote_metadata_bytes,
+        )
+
+    @NotAudit
+    def reshape_partial_chunk(
+        self,
+        memory_obj: MemoryObj,
+        bytes_read: int,
+    ) -> MemoryObj:
+        assert self.full_chunk_size_bytes is not None
+        assert self.single_token_size is not None
+        if (
+            bytes_read == 0
+            or bytes_read % self.single_token_size != 0
+            or bytes_read > self.full_chunk_size_bytes
+        ):
+            raise ValueError(
+                f"bytes_read: {bytes_read} is illegal, "
+                f"single_token_size: {self.single_token_size}, "
+                f"full_chunk_size_bytes: {self.full_chunk_size_bytes}"
+            )
+
+        if bytes_read == self.full_chunk_size_bytes:
+            # full chunk, return directly
+            return memory_obj
+
+        # NOTE: for unfull chunk, we have no way to verify
+        shape_list = list(memory_obj.meta.shape)
+        if len(shape_list) == 4:
+            # Standard: [2, num_layers, num_tokens, hidden_dim]
+            # or MLA:   [1, num_layers, num_tokens, hidden_dim]
+            token_dim = 2
+            num_tokens = bytes_read // self.single_token_size
+        else:
+            # Layerwise 3D: [num_tokens, 2, hidden_dim]
+            # Layerwise MLA 2D: [num_tokens, hidden_dim]
+            token_dim = 0
+            # single_token_size spans ALL layers, but bytes_read is
+            # for a single layer.  Compute per-layer token size from
+            # the non-token dimensions of the shape.
+            elements_per_token = 1
+            for i in range(1, len(shape_list)):
+                elements_per_token *= shape_list[i]
+            assert memory_obj.meta.dtype is not None
+            dtype_size = memory_obj.meta.dtype.itemsize
+            per_layer_token_size = elements_per_token * dtype_size
+            num_tokens = bytes_read // per_layer_token_size
+        shape_list[token_dim] = num_tokens
+        actual_shape = torch.Size(shape_list)
+        memory_obj.raw_data = memory_obj.raw_data[:bytes_read]
+        memory_obj.meta.shape = actual_shape
+        # Sync group_prefix_sum so that get_size() / byte_array reflect the
+        # truncated size rather than the original full-chunk size.
+        if hasattr(memory_obj, "group_prefix_sum"):
+            memory_obj.group_prefix_sum = [0, bytes_read]  # type: ignore[attr-defined]
+
+        return memory_obj
+
+    @NotAudit
+    def post_init(self):
+        """
+        Post-initialization method to be called after the connector is created.
+        This can be used to perform any additional setup required by the connector.
+        """
+        logger.info("Dummy post-initializing remote connector")
+
+    @abc.abstractmethod
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """
+        Check if the remote server contains the key
+
+        Input:
+            key: a CacheEngineKey
+
+        Returns:
+            True if the cache engine contains the key, False otherwise
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """
+        Check if the remote server contains the key synchronized
+
+        Input:
+            key: a CacheEngineKey
+
+        Returns:
+            True if the cache engine contains the key, False otherwise
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """
+        Get the memory_obj of the corresponding key
+
+        Input:
+            key: the key of the corresponding object
+
+        Returns:
+            The memory_obj of the corresponding key
+            Return None if the key does not exist
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """
+        Send the memory_obj with the corresponding key directly
+        to the remote server. Will decrease the ref count after
+        send finishes.
+
+        Input:
+            key: the CacheEngine key
+            memory_obj: the memory_obj of the corresponding key
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def list(self) -> List[str]:
+        """
+        List all keys in the remote server
+
+        Returns:
+            A list of keys in the remote server
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def close(self):
+        """
+        Close remote server
+
+        """
+        raise NotImplementedError
+
+    def support_ping(self) -> bool:
+        """
+        Check if the connector supports ping operation
+
+        Returns:
+            True if ping is supported, False otherwise
+        """
+        return False
+
+    async def ping(self) -> int:
+        """
+        Ping the remote server
+
+        Returns:
+            The error code, 0 means success
+        """
+        raise NotImplementedError
+
+    def support_batched_get(self) -> bool:
+        """
+        Check if the connector supports batched get
+
+        Returns:
+            True if batched get is supported, False otherwise
+        """
+        return False
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """
+        Batched get the memory_objs of the corresponding keys
+
+        Input:
+            keys: the keys of the corresponding objects
+
+        Returns:
+            The memory_objs of the corresponding keys
+            Return None if the key does not exist
+        """
+        raise NotImplementedError
+
+    def support_batched_put(self) -> bool:
+        """
+        Check if the connector supports batched put
+        Returns:
+            True if batched put is supported, False otherwise
+        """
+        return False
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        """
+        Batched put the memory_objs with the corresponding keys
+        Input:
+            keys: the keys of the corresponding objects
+            memory_objs: the memory_objs of the corresponding keys
+        """
+        raise NotImplementedError
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Check how many keys exist in file system in batch
+
+        Args:
+            lookup_id: Identifier for this lookup operation
+            keys: List of keys to check
+            pin: Whether to pin the keys (not used in FS connector)
+
+        Returns:
+            Number of consecutive keys that exist, starting from the first key
+        """
+        tasks = [self.exists(key) for key in keys]
+        results = await asyncio.gather(*tasks)
+        if False in results:
+            return results.index(False)
+        return len(results)
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        """Batched get the memory_objs of the corresponding keys (non-blocking)
+
+        This method returns only the consecutive prefix of successfully retrieved
+        memory objects. Once a key is not found (None) or an exception occurs,
+        all subsequent memory objects (even if successfully retrieved) will be
+        released to avoid memory leaks, and only the prefix before the first
+        failure will be returned.
+
+        Args:
+            lookup_id: Identifier for this lookup operation
+            keys: List of keys to get
+
+        Returns:
+            List of consecutive memory objects from the beginning until the first
+            failure (None or Exception). Empty list if the first key fails.
+        """
+        # Use asyncio.gather to fetch all keys concurrently
+        results = await asyncio.gather(
+            *(self.get(key) for key in keys), return_exceptions=True
+        )
+
+        # Only return consecutive prefix of valid memory objects
+        memory_objs = []
+        found_failure = False
+        for result in results:
+            if found_failure:
+                # Release subsequent memory objects to avoid memory leak
+                if isinstance(result, MemoryObj):
+                    result.ref_count_down()
+            elif isinstance(result, MemoryObj):
+                memory_objs.append(result)
+            else:
+                # First failure encountered (None or Exception)
+                if isinstance(result, Exception):
+                    logger.warning(f"Exception during batched get: {result}")
+                found_failure = True
+
+        return memory_objs
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        """
+        Remove a memory object.
+
+        :param CacheEngineKey key: The key of the MemoryObj.
+
+        :return: a bool indicates whether remove is successful.
+        """
+        raise NotImplementedError
+
+    def batched_contains(self, keys: List[CacheEngineKey]) -> int:
+        """
+        Batched contains.
+
+        :param List[CacheEngineKey] keys: The keys to check.
+
+        :return: Return hit chunks by prefix match.
+        """
+        raise NotImplementedError
+
+    def support_batched_contains(self) -> bool:
+        """
+        Is supported batched_contains
+        """
+        return False
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}>"
diff --git a/lmcache/v1/storage_backend/connector/bigtable_adapter.py b/lmcache/v1/storage_backend/connector/bigtable_adapter.py
new file mode 100644
index 0000000..f6e0da0
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/bigtable_adapter.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.storage_backend.connector import ConnectorAdapter, ConnectorContext
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+# Local
+from .bigtable_connector import BigtableConnector
+
+
+class BigtableConnectorAdapter(ConnectorAdapter):
+    """Adapter for BigtableConnector to integrate natively with LMCache
+    built-in connectors.
+
+    Supports both 'plugin://bigtable' and 'bigtable://' URL schemas.
+    """
+
+    def __init__(self):
+        super().__init__("plugin://bigtable")
+
+    def can_parse(self, url: str) -> bool:
+        return url.startswith(self.schema) or url.startswith("bigtable://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        return BigtableConnector(
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            config=context.config,
+            plugin_name=context.plugin_name,
+        )
diff --git a/lmcache/v1/storage_backend/connector/bigtable_config.py b/lmcache/v1/storage_backend/connector/bigtable_config.py
new file mode 100644
index 0000000..5b88848
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/bigtable_config.py
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class BigtablePluginConfig:
+    project_id: str
+    instance_id: str
+    table_name: str
+    app_profile_id: Optional[str] = None
+    read_timeout_sec: float = 0.2
+    write_timeout_sec: float = 0.5
+    exists_cache_ttl_seconds: float = 30.0
+    exists_cache_size: int = 10000
+    thread_pool_size: int = 16
+    row_key_template: str = "hash#model"
+    credentials_path: Optional[str] = None
+    max_retries: int = 3
+    max_chunk_size_mb: float = 90.0
+    family_name: str = "cf"
+    column_name: str = "data"
+
+    @classmethod
+    def from_extra_config(
+        cls, extra_config: Dict[str, Any], plugin_name: Optional[str] = None
+    ) -> "BigtablePluginConfig":
+        # Standard
+        import os
+
+        def get_val(key: str, default: Any = None) -> Any:
+            if plugin_name:
+                full_key = f"remote_storage_plugin.{plugin_name}.{key}"
+                if full_key in extra_config:
+                    return extra_config[full_key]
+            return extra_config.get(key, default)
+
+        project_id = get_val("bigtable_project_id") or os.environ.get("BT_PROJECT_ID")
+        instance_id = get_val("bigtable_instance_id") or os.environ.get(
+            "BT_INSTANCE_ID"
+        )
+        table_name = get_val("bigtable_table_name") or os.environ.get("BT_TABLE_NAME")
+
+        if not project_id or not instance_id or not table_name:
+            raise ValueError(
+                f"Bigtable out-of-tree connector requires bigtable_project_id, "
+                f"bigtable_instance_id, and bigtable_table_name (or BT_* env vars). "
+                f"Got project={project_id}, instance={instance_id}, table={table_name}"
+            )
+
+        return cls(
+            project_id=project_id,
+            instance_id=instance_id,
+            table_name=table_name,
+            app_profile_id=get_val(
+                "bigtable_app_profile",
+                get_val("app_profile", os.environ.get("BT_APP_PROFILE")),
+            ),
+            read_timeout_sec=float(
+                get_val(
+                    "bigtable_read_timeout_ms",
+                    get_val(
+                        "read_timeout_ms",
+                        os.environ.get("BT_READ_TIMEOUT_MS", 200.0),
+                    ),
+                )
+            )
+            / 1000.0,
+            write_timeout_sec=float(
+                get_val(
+                    "bigtable_write_timeout_ms",
+                    get_val(
+                        "write_timeout_ms",
+                        os.environ.get("BT_WRITE_TIMEOUT_MS", 500.0),
+                    ),
+                )
+            )
+            / 1000.0,
+            exists_cache_ttl_seconds=float(
+                get_val(
+                    "bigtable_exists_cache_ttl_seconds",
+                    get_val(
+                        "exists_cache_ttl_seconds",
+                        os.environ.get("BT_EXISTS_CACHE_TTL_SECONDS", 30.0),
+                    ),
+                )
+            ),
+            exists_cache_size=int(
+                get_val(
+                    "bigtable_exists_cache_size",
+                    get_val(
+                        "exists_cache_size",
+                        os.environ.get("BT_EXISTS_CACHE_SIZE", 10000),
+                    ),
+                )
+            ),
+            thread_pool_size=int(
+                get_val(
+                    "bigtable_thread_pool_size",
+                    get_val(
+                        "thread_pool_size", os.environ.get("BT_THREAD_POOL_SIZE", 16)
+                    ),
+                )
+            ),
+            row_key_template=get_val(
+                "bigtable_row_key_template",
+                get_val(
+                    "row_key_template",
+                    os.environ.get("BT_ROW_KEY_TEMPLATE", "hash#model"),
+                ),
+            ),
+            credentials_path=get_val(
+                "bigtable_credentials_path",
+                get_val("credentials_path", os.environ.get("BT_CREDENTIALS_PATH")),
+            ),
+            max_retries=int(
+                get_val(
+                    "bigtable_max_retries",
+                    get_val("max_retries", os.environ.get("BT_MAX_RETRIES", 3)),
+                )
+            ),
+            max_chunk_size_mb=float(
+                get_val(
+                    "bigtable_max_chunk_size_mb",
+                    os.environ.get("BT_MAX_CHUNK_SIZE_MB", 90.0),
+                )
+            ),
+            family_name=get_val(
+                "bigtable_family_name", os.environ.get("BT_FAMILY_NAME", "cf")
+            ),
+            column_name=get_val(
+                "bigtable_column_name", os.environ.get("BT_COLUMN_NAME", "data")
+            ),
+        )
diff --git a/lmcache/v1/storage_backend/connector/bigtable_connector.py b/lmcache/v1/storage_backend/connector/bigtable_connector.py
new file mode 100644
index 0000000..fe3d712
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/bigtable_connector.py
@@ -0,0 +1,929 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from enum import IntEnum, auto
+from typing import List, Optional
+import asyncio
+import inspect
+import threading
+
+# Third Party
+from cachetools import TTLCache as _TTLCache  # type: ignore
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+# Local
+from .bigtable_config import BigtablePluginConfig
+from .bigtable_schema import BigtableSchema
+
+logger = init_logger(__name__)
+
+
+class Priorities(IntEnum):
+    PEEK = auto()
+    PREFETCH = auto()
+    GET = auto()
+    PUT = auto()
+
+
+class TTLCache:
+    """Thread-safe wrapper around cachetools.TTLCache for existence checks."""
+
+    def __init__(self, max_size: int, ttl_seconds: float):
+        self.cache: _TTLCache = _TTLCache(maxsize=max_size, ttl=ttl_seconds)
+        self.lock = threading.RLock()
+
+    def get(self, key: str) -> Optional[bool]:
+        with self.lock:
+            return self.cache.get(key)
+
+    def put(self, key: str, val: bool):
+        with self.lock:
+            self.cache[key] = val
+
+    def invalidate(self, key: str):
+        with self.lock:
+            self.cache.pop(key, None)
+
+
+class BigtableConnector(RemoteConnector):
+    """
+    Native Bigtable remote connector integrated into LMCache.
+    Tier Agnostic Design: serves all tier roles driven by per-instance configuration.
+    """
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        config: LMCacheEngineConfig,
+        plugin_name: Optional[str] = None,
+    ):
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        extra_config = config.extra_config if config.extra_config is not None else {}
+        self.cfg = BigtablePluginConfig.from_extra_config(extra_config, plugin_name)
+        self.schema = BigtableSchema(
+            self.cfg.row_key_template, self.cfg.family_name, self.cfg.column_name
+        )
+
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.exists_cache = TTLCache(
+            max_size=self.cfg.exists_cache_size,
+            ttl_seconds=self.cfg.exists_cache_ttl_seconds,
+        )
+
+        # Independent gRPC client pool initialized lazily on first operation
+        self._client = None
+        self._table = None
+
+        # Use native AsyncPQExecutor to run pure coroutines directly on the event loop
+        self.pq_executor = AsyncPQExecutor(loop, max_workers=self.cfg.thread_pool_size)
+
+        logger.info(
+            f"Initialized Bigtable remote connector for project={self.cfg.project_id}, "
+            f"instance={self.cfg.instance_id}, table={self.cfg.table_name}"
+        )
+
+    def _get_client(self):
+        """Lazy initialization of independent Bigtable async data client."""
+        if self._client is not None:
+            return self._client
+
+        try:
+            # Third Party
+            from google.api_core import exceptions as google_exceptions
+            from google.api_core.gapic_v1.client_info import ClientInfo
+            from google.cloud.bigtable.data import BigtableDataClientAsync
+
+            self.google_exceptions = google_exceptions
+
+            logger.info(
+                f"Lazily initializing Bigtable async client "
+                f"for project={self.cfg.project_id}, "
+                f"instance={self.cfg.instance_id}, "
+                f"table={self.cfg.table_name}"
+            )
+
+            client_info = ClientInfo(user_agent="lmcache")
+
+            if self.cfg.credentials_path:
+                # Third Party
+                from google.oauth2 import service_account
+                import google.auth.exceptions
+
+                try:
+                    credentials = service_account.Credentials.from_service_account_file(
+                        self.cfg.credentials_path
+                    )
+                    self._client = BigtableDataClientAsync(
+                        project=self.cfg.project_id,
+                        credentials=credentials,
+                        client_info=client_info,
+                    )
+                except (
+                    OSError,
+                    ValueError,
+                    google.auth.exceptions.GoogleAuthError,
+                ) as e:
+                    logger.warning(
+                        f"Failed to load credentials from "
+                        f"{self.cfg.credentials_path} due to {e}. "
+                        f"Falling back to Application Default Credentials."
+                    )
+                    self._client = BigtableDataClientAsync(
+                        project=self.cfg.project_id,
+                        client_info=client_info,
+                    )
+            else:
+                self._client = BigtableDataClientAsync(
+                    project=self.cfg.project_id,
+                    client_info=client_info,
+                )
+
+            return self._client
+        except Exception as e:
+            logger.error(f"Failed to initialize Bigtable async client: {e}")
+            raise
+
+    def _get_table(self):
+        """Lazy initialization and caching of TableAsync instance."""
+        if self._table is not None:
+            return self._table
+
+        client = self._get_client()
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError as e:
+            raise RuntimeError(
+                "TableAsync must be retrieved within an async event loop context."
+            ) from e
+
+        self._table = client.get_table(self.cfg.instance_id, self.cfg.table_name)
+        return self._table
+
+    def _get_row_filters_module(self):
+        try:
+            # Third Party
+            from google.cloud.bigtable.data import row_filters
+
+            return row_filters
+        except ImportError:
+            # Third Party
+            from google.cloud.bigtable import row_filters
+
+            return row_filters
+
+    async def _exists_internal(self, key: CacheEngineKey) -> bool:
+        key_str = key.to_string()
+        cached_val = self.exists_cache.get(key_str)
+        if cached_val is not None:
+            return cached_val
+
+        row_key = self.schema.get_row_key(key)
+
+        row_filters = self._get_row_filters_module()
+        row_filter = getattr(
+            row_filters, "StripValueTransformerFilter", lambda flag: None
+        )(True)
+
+        retries = 0
+        while True:
+            try:
+                kwargs = {}
+                if row_filter is not None:
+                    kwargs["row_filter"] = row_filter
+                if self.cfg.app_profile_id:
+                    kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+                table = self._get_table()
+                row = await table.read_row(
+                    row_key,
+                    operation_timeout=self.cfg.read_timeout_sec,
+                    **kwargs,
+                )
+                exists = row is not None
+                self.exists_cache.put(key_str, exists)
+                return exists
+            except (
+                self.google_exceptions.DeadlineExceeded,
+                TimeoutError,
+            ) as e:
+                logger.warning(
+                    f"Bigtable async timeout in exists: {e}. Treating as miss."
+                )
+                return False
+            except (
+                self.google_exceptions.PermissionDenied,
+                self.google_exceptions.Unauthenticated,
+            ) as e:
+                logger.error(f"Bigtable permission/auth error in exists: {e}")
+                raise
+            except self.google_exceptions.NotFound as e:
+                logger.error(f"Bigtable NotFound in exists: {e}")
+                raise
+            except self.google_exceptions.ResourceExhausted:
+                if retries < self.cfg.max_retries:
+                    sleep_time = 0.5 * (2**retries)
+                    logger.warning(
+                        f"Bigtable ResourceExhausted. Retrying in {sleep_time}s."
+                    )
+                    await asyncio.sleep(sleep_time)
+                    retries += 1
+                else:
+                    logger.warning(
+                        "Bigtable ResourceExhausted max retries reached in exists."
+                    )
+                    return False
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return await self.pq_executor.submit_job(
+            self._exists_internal, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        future = asyncio.run_coroutine_threadsafe(self.exists(key), self.loop)
+        return bool(future.result())
+
+    async def _get_internal(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+        row_key = self.schema.get_row_key(key)
+
+        row_filters = self._get_row_filters_module()
+        row_filter = getattr(row_filters, "CellsColumnLimitFilter", lambda n: None)(1)
+
+        retries = 0
+        while True:
+            try:
+                kwargs = {}
+                if row_filter is not None:
+                    kwargs["row_filter"] = row_filter
+                if self.cfg.app_profile_id:
+                    kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+                table = self._get_table()
+                row = await table.read_row(
+                    row_key,
+                    operation_timeout=self.cfg.read_timeout_sec,
+                    **kwargs,
+                )
+                if row is None:
+                    self.exists_cache.put(key_str, False)
+                    return None
+
+                self.exists_cache.put(key_str, True)
+
+                cell_value = self.schema.extract_cell_value(row)
+                if cell_value is None:
+                    return None
+
+                memory_obj = self.local_cpu_backend.allocate(
+                    self.meta_shapes,
+                    self.meta_dtypes,
+                    self.meta_fmt,
+                )
+                if memory_obj is None:
+                    logger.warning("Failed to allocate memory during Bigtable receive")
+                    return None
+
+                view = memory_obj.byte_array
+                if not isinstance(view, memoryview):
+                    view = memoryview(view)
+
+                if isinstance(view.format, str) and view.format == "<B":
+                    view = view.cast("B")
+
+                if len(cell_value) > len(view):
+                    logger.warning(
+                        f"Bigtable cell size {len(cell_value)} exceeds "
+                        f"allocated view size {len(view)}"
+                    )
+                    memory_obj.ref_count_down()
+                    return None
+
+                view[: len(cell_value)] = cell_value
+                if len(cell_value) < len(view):
+                    memory_obj = self.reshape_partial_chunk(memory_obj, len(cell_value))
+                return memory_obj
+
+            except (
+                self.google_exceptions.DeadlineExceeded,
+                TimeoutError,
+            ) as e:
+                logger.warning(f"Bigtable async timeout in get: {e}. Treating as miss.")
+                return None
+            except (
+                self.google_exceptions.PermissionDenied,
+                self.google_exceptions.Unauthenticated,
+            ) as e:
+                logger.error(f"Bigtable permission/auth error in get: {e}")
+                raise
+            except self.google_exceptions.NotFound as e:
+                logger.error(f"Bigtable NotFound in get: {e}")
+                raise
+            except self.google_exceptions.ResourceExhausted:
+                if retries < self.cfg.max_retries:
+                    sleep_time = 0.5 * (2**retries)
+                    logger.warning(
+                        f"Bigtable ResourceExhausted. Retrying in {sleep_time}s."
+                    )
+                    await asyncio.sleep(sleep_time)
+                    retries += 1
+                else:
+                    logger.warning(
+                        "Bigtable ResourceExhausted max retries reached in get."
+                    )
+                    return None
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._get_internal, key=key, priority=Priorities.GET
+        )
+
+    async def _put_internal(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        try:
+            key_str = key.to_string()
+            blob = memory_obj.byte_array
+            blob_size_mb = len(blob) / (1024 * 1024)
+
+            if blob_size_mb > self.cfg.max_chunk_size_mb:
+                logger.warning(
+                    f"Bigtable chunk size {blob_size_mb:.2f} MB exceeds "
+                    f"threshold {self.cfg.max_chunk_size_mb} MB. "
+                    f"Skipping write to prevent hard failures."
+                )
+                return
+
+            row_key = self.schema.get_row_key(key)
+            data_bytes = (
+                bytes(blob) if not isinstance(blob, (bytes, bytearray)) else blob
+            )
+
+            # Third Party
+            from google.cloud.bigtable.data import SetCell
+
+            mutation = SetCell(self.cfg.family_name, self.cfg.column_name, data_bytes)
+
+            retries = 0
+            while True:
+                try:
+                    kwargs = {}
+                    if self.cfg.app_profile_id:
+                        kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+                    table = self._get_table()
+                    await table.mutate_row(
+                        row_key,
+                        mutation,
+                        operation_timeout=self.cfg.write_timeout_sec,
+                        **kwargs,
+                    )
+                    self.exists_cache.put(key_str, True)
+                    logger.debug(
+                        f"Successfully wrote "
+                        f"{row_key.decode('utf-8', errors='ignore')} "
+                        f"via async Bigtable"
+                    )
+                    return
+                except (
+                    self.google_exceptions.DeadlineExceeded,
+                    TimeoutError,
+                ) as e:
+                    logger.warning(
+                        f"Bigtable async timeout in put: {e}. Skipping write."
+                    )
+                    return
+                except (
+                    self.google_exceptions.PermissionDenied,
+                    self.google_exceptions.Unauthenticated,
+                ) as e:
+                    logger.error(f"Bigtable permission/auth error in put: {e}")
+                    raise
+                except self.google_exceptions.NotFound as e:
+                    logger.error(f"Bigtable NotFound in put: {e}")
+                    raise
+                except self.google_exceptions.ResourceExhausted:
+                    if retries < self.cfg.max_retries:
+                        sleep_time = 0.5 * (2**retries)
+                        logger.warning(
+                            f"Bigtable ResourceExhausted. Retrying in {sleep_time}s."
+                        )
+                        await asyncio.sleep(sleep_time)
+                        retries += 1
+                    else:
+                        logger.warning(
+                            "Bigtable ResourceExhausted max retries reached in put."
+                        )
+                        return
+        finally:
+            memory_obj.ref_count_down()
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        await self.pq_executor.submit_job(
+            self._put_internal,
+            key=key,
+            memory_obj=memory_obj,
+            priority=Priorities.PUT,
+        )
+
+    def support_batched_get(self) -> bool:
+        return True
+
+    async def _batched_get_internal(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        # Third Party
+        from google.cloud.bigtable.data import ReadRowsQuery
+
+        row_keys: List[str | bytes] = [self.schema.get_row_key(k) for k in keys]
+        row_filters = self._get_row_filters_module()
+        row_filter = getattr(row_filters, "CellsColumnLimitFilter", lambda n: None)(1)
+
+        query = ReadRowsQuery(row_keys=row_keys, row_filter=row_filter)
+
+        retries = 0
+        while True:
+            try:
+                kwargs = {}
+                if self.cfg.app_profile_id:
+                    kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+                table = self._get_table()
+                rows_gen = await table.read_rows(
+                    query=query,
+                    operation_timeout=self.cfg.read_timeout_sec,
+                    **kwargs,
+                )
+
+                row_dict = {}
+                for row in rows_gen:
+                    row_dict[row.row_key] = row
+
+                memory_objs: List[Optional[MemoryObj]] = []
+                for key, rk in zip(keys, row_keys, strict=False):
+                    key_str = key.to_string()
+                    row = row_dict.get(rk)
+                    if row is None:
+                        self.exists_cache.put(key_str, False)
+                        memory_objs.append(None)
+                        continue
+
+                    self.exists_cache.put(key_str, True)
+                    cell_value = self.schema.extract_cell_value(row)
+                    if cell_value is None:
+                        memory_objs.append(None)
+                        continue
+
+                    memory_obj = self.local_cpu_backend.allocate(
+                        self.meta_shapes,
+                        self.meta_dtypes,
+                        self.meta_fmt,
+                    )
+                    if memory_obj is None:
+                        logger.warning(
+                            "Failed to allocate memory during batched Bigtable receive"
+                        )
+                        memory_objs.append(None)
+                        continue
+
+                    view = memory_obj.byte_array
+                    if not isinstance(view, memoryview):
+                        view = memoryview(view)
+                    if isinstance(view.format, str) and view.format == "<B":
+                        view = view.cast("B")
+
+                    if len(cell_value) > len(view):
+                        logger.warning(
+                            f"Bigtable cell size {len(cell_value)} "
+                            f"exceeds allocated view size {len(view)}"
+                        )
+                        memory_obj.ref_count_down()
+                        memory_objs.append(None)
+                        continue
+
+                    view[: len(cell_value)] = cell_value
+                    if len(cell_value) < len(view):
+                        memory_obj = self.reshape_partial_chunk(
+                            memory_obj, len(cell_value)
+                        )
+                    memory_objs.append(memory_obj)
+
+                return memory_objs
+
+            except (
+                self.google_exceptions.DeadlineExceeded,
+                TimeoutError,
+            ) as e:
+                logger.warning(
+                    f"Bigtable async timeout in batched_get: {e}. Treating as miss."
+                )
+                return [None] * len(keys)
+            except (
+                self.google_exceptions.PermissionDenied,
+                self.google_exceptions.Unauthenticated,
+            ) as e:
+                logger.error(f"Bigtable permission/auth error in batched_get: {e}")
+                raise
+            except self.google_exceptions.NotFound as e:
+                logger.error(f"Bigtable NotFound in batched_get: {e}")
+                raise
+            except self.google_exceptions.ResourceExhausted:
+                if retries < self.cfg.max_retries:
+                    sleep_time = 0.5 * (2**retries)
+                    logger.warning(
+                        f"Bigtable ResourceExhausted. Retrying in {sleep_time}s."
+                    )
+                    await asyncio.sleep(sleep_time)
+                    retries += 1
+                else:
+                    logger.warning(
+                        "Bigtable ResourceExhausted max retries reached in batched_get."
+                    )
+                    return [None] * len(keys)
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        return await self.pq_executor.submit_job(
+            self._batched_get_internal, keys=keys, priority=Priorities.GET
+        )
+
+    def support_batched_put(self) -> bool:
+        return True
+
+    async def _batched_put_internal(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        try:
+            # Third Party
+            from google.cloud.bigtable.data import RowMutationEntry, SetCell
+
+            current_batch: List[RowMutationEntry] = []
+            current_batch_keys: List[str] = []
+            current_batch_size = 0
+            MAX_BATCH_SIZE_BYTES = 30 * 1024 * 1024  # 30MB safety limit
+
+            table = self._get_table()
+            kwargs = {}
+            if self.cfg.app_profile_id:
+                kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+            async def flush_batch(batch, batch_keys):
+                if not batch:
+                    return
+                retries = 0
+                while True:
+                    try:
+                        await table.bulk_mutate_rows(
+                            batch,
+                            operation_timeout=self.cfg.write_timeout_sec,
+                            **kwargs,
+                        )
+                        for k_str in batch_keys:
+                            self.exists_cache.put(k_str, True)
+                        logger.debug(
+                            f"Successfully batched put {len(batch)} rows "
+                            f"via async Bigtable"
+                        )
+                        return
+                    except (
+                        self.google_exceptions.DeadlineExceeded,
+                        TimeoutError,
+                    ) as e:
+                        logger.warning(
+                            f"Bigtable async timeout in batched_put: {e}. Skipping."
+                        )
+                        return
+                    except (
+                        self.google_exceptions.PermissionDenied,
+                        self.google_exceptions.Unauthenticated,
+                    ) as e:
+                        logger.error(
+                            f"Bigtable permission/auth error in batched_put: {e}"
+                        )
+                        raise
+                    except self.google_exceptions.NotFound as e:
+                        logger.error(f"Bigtable NotFound in batched_put: {e}")
+                        raise
+                    except self.google_exceptions.ResourceExhausted:
+                        if retries < self.cfg.max_retries:
+                            sleep_time = 0.5 * (2**retries)
+                            logger.warning(f"Retrying Bigtable in {sleep_time}s.")
+                            await asyncio.sleep(sleep_time)
+                            retries += 1
+                        else:
+                            logger.warning(
+                                "Bigtable ResourceExhausted max retries reached "
+                                "in batched_put."
+                            )
+                            return
+                    except Exception as e:
+                        logger.error(
+                            f"Unexpected error in Bigtable "
+                            f"_batched_put_internal flush: {e}",
+                            exc_info=True,
+                        )
+                        raise
+
+            for key, memory_obj in zip(keys, memory_objs, strict=False):
+                if memory_obj is None:
+                    continue
+                blob = memory_obj.byte_array
+                blob_size = len(blob)
+                blob_size_mb = blob_size / (1024 * 1024)
+
+                if blob_size_mb > self.cfg.max_chunk_size_mb:
+                    logger.warning(
+                        f"Bigtable chunk size {blob_size_mb:.2f} MB exceeds "
+                        f"threshold {self.cfg.max_chunk_size_mb} MB. "
+                        f"Skipping write for key {key.to_string()}."
+                    )
+                    continue
+
+                if (
+                    current_batch_size + blob_size > MAX_BATCH_SIZE_BYTES
+                    and current_batch
+                ):
+                    await flush_batch(current_batch, current_batch_keys)
+                    current_batch = []
+                    current_batch_keys = []
+                    current_batch_size = 0
+
+                row_key = self.schema.get_row_key(key)
+                data_bytes = (
+                    bytes(blob) if not isinstance(blob, (bytes, bytearray)) else blob
+                )
+
+                mutation = SetCell(
+                    self.cfg.family_name, self.cfg.column_name, data_bytes
+                )
+                entry = RowMutationEntry(row_key, mutation)
+                current_batch.append(entry)
+                current_batch_keys.append(key.to_string())
+                current_batch_size += blob_size
+
+            if current_batch:
+                await flush_batch(current_batch, current_batch_keys)
+        finally:
+            for memory_obj in memory_objs:
+                if memory_obj is not None:
+                    memory_obj.ref_count_down()
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        await self.pq_executor.submit_job(
+            self._batched_put_internal,
+            keys=keys,
+            memory_objs=memory_objs,
+            priority=Priorities.PUT,
+        )
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def _batched_contains_internal(self, keys: List[CacheEngineKey]) -> int:
+        count = 0
+        missing_keys = []
+        for key in keys:
+            val = self.exists_cache.get(key.to_string())
+            if val is False:
+                return count
+            elif val is None:
+                missing_keys = keys[count:]
+                break
+            count += 1
+
+        if not missing_keys:
+            return count
+
+        # Third Party
+        from google.cloud.bigtable.data import ReadRowsQuery
+
+        row_keys_missing: List[str | bytes] = [
+            self.schema.get_row_key(k) for k in missing_keys
+        ]
+        row_filters = self._get_row_filters_module()
+        row_filter = getattr(
+            row_filters, "StripValueTransformerFilter", lambda flag: None
+        )(True)
+
+        query = ReadRowsQuery(row_keys=row_keys_missing, row_filter=row_filter)
+
+        retries = 0
+        while True:
+            try:
+                kwargs = {}
+                if self.cfg.app_profile_id:
+                    kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+                table = self._get_table()
+                rows_gen = await table.read_rows(
+                    query=query,
+                    operation_timeout=self.cfg.read_timeout_sec,
+                    **kwargs,
+                )
+
+                existing_rk_set = set()
+                for row in rows_gen:
+                    existing_rk_set.add(row.row_key)
+
+                for k, rk in zip(missing_keys, row_keys_missing, strict=False):
+                    exists = rk in existing_rk_set
+                    self.exists_cache.put(k.to_string(), exists)
+                    if not exists:
+                        return count
+                    count += 1
+
+                return count
+
+            except (
+                self.google_exceptions.DeadlineExceeded,
+                TimeoutError,
+            ) as e:
+                logger.warning(f"Bigtable async timeout in batched_contains: {e}")
+                return count
+            except (
+                self.google_exceptions.PermissionDenied,
+                self.google_exceptions.Unauthenticated,
+            ) as e:
+                logger.error(f"Bigtable auth error in batched_contains: {e}")
+                raise
+            except self.google_exceptions.NotFound as e:
+                logger.error(f"Bigtable NotFound in batched_contains: {e}")
+                raise
+            except self.google_exceptions.ResourceExhausted:
+                if retries < self.cfg.max_retries:
+                    sleep_time = 0.5 * (2**retries)
+                    logger.warning(
+                        f"Bigtable ResourceExhausted. Retrying in {sleep_time}s."
+                    )
+                    await asyncio.sleep(sleep_time)
+                    retries += 1
+                else:
+                    logger.warning(
+                        "Bigtable ResourceExhausted max retries reached "
+                        "in batched_contains."
+                    )
+                    return count
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        return await self.pq_executor.submit_job(
+            self._batched_contains_internal,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        try:
+            self.exists_cache.invalidate(key.to_string())
+            # Third Party
+            from google.cloud.bigtable.data import DeleteAllFromRow
+
+            row_key = self.schema.get_row_key(key)
+
+            kwargs = {}
+            if self.cfg.app_profile_id:
+                kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+            async def _do_remove():
+                try:
+                    table = self._get_table()
+                    await table.mutate_row(
+                        row_key,
+                        DeleteAllFromRow(),
+                        operation_timeout=self.cfg.write_timeout_sec,
+                        **kwargs,
+                    )
+                except Exception as e:
+                    logger.warning(
+                        f"Failed to remove key {key} from Bigtable in background: {e}"
+                    )
+
+            asyncio.run_coroutine_threadsafe(
+                _do_remove(),
+                self.loop,
+            )
+            return True
+        except Exception as e:
+            logger.warning(
+                f"Failed to schedule removal of key {key} from Bigtable: {e}"
+            )
+            return False
+
+    async def _list_internal(self) -> List[str]:
+        # Third Party
+        from google.cloud.bigtable.data import ReadRowsQuery
+
+        row_filters = self._get_row_filters_module()
+        row_filter = getattr(
+            row_filters, "StripValueTransformerFilter", lambda flag: None
+        )(True)
+        query = ReadRowsQuery(row_filter=row_filter)
+
+        kwargs = {}
+        if self.cfg.app_profile_id:
+            kwargs["app_profile_id"] = self.cfg.app_profile_id
+
+        table = self._get_table()
+        rows_gen = await table.read_rows(
+            query=query,
+            operation_timeout=self.cfg.read_timeout_sec,
+            **kwargs,
+        )
+
+        res = []
+        for row in rows_gen:
+            rk_str = row.row_key.decode("utf-8")
+            parts_split = rk_str.split("#", 1)
+            if len(parts_split) != 2:
+                continue
+            p1, p2 = parts_split
+            if "@" in p1:
+                fingerprint, chunk_hash_hex = p1, p2
+            else:
+                chunk_hash_hex, fingerprint = p1, p2
+            parts = fingerprint.split("@")
+            if len(parts) < 4:
+                continue
+            model_name = parts[0]
+            world_size = parts[1]
+            worker_id = parts[2]
+            dtype_str = parts[3]
+
+            std_str = (
+                f"{model_name}@{world_size}@{worker_id}@{chunk_hash_hex}@{dtype_str}"
+            )
+            if len(parts) > 4:
+                std_str += "@" + "@".join(parts[4:])
+            res.append(std_str)
+        return res
+
+    async def list(self) -> List[str]:
+        return await self.pq_executor.submit_job(
+            self._list_internal, priority=Priorities.GET
+        )
+
+    async def close(self):
+        await self.pq_executor.shutdown_async(wait=False)
+        if getattr(self, "_table", None) is not None:
+            try:
+                res = self._table.close()
+                if inspect.isawaitable(res):
+                    await res
+            except Exception as e:
+                logger.warning(f"Failed to close Bigtable table cleanly: {e}")
+            self._table = None
+        if getattr(self, "_client", None) is not None:
+            try:
+                res = self._client.close()
+                if inspect.isawaitable(res):
+                    await res
+            except AttributeError:
+                pass
+        logger.info("Closed Bigtable connector cleanly.")
+
+    def support_batched_contains(self) -> bool:
+        return True
+
+    def batched_contains(self, keys: List[CacheEngineKey]) -> int:
+        future = asyncio.run_coroutine_threadsafe(
+            self.batched_async_contains("sync_lookup", keys), self.loop
+        )
+        return int(future.result())
+
+    def support_ping(self) -> bool:
+        return True
+
+    async def ping(self) -> int:
+        try:
+            client = self._get_client()
+            kwargs = {}
+            if self.cfg.app_profile_id:
+                kwargs["app_profile_id"] = self.cfg.app_profile_id
+            iterator = await client.execute_query(
+                "SELECT 1;",
+                self.cfg.instance_id,
+                operation_timeout=self.cfg.read_timeout_sec,
+                **kwargs,
+            )
+            async for _ in iterator:
+                pass
+            return 0
+        except Exception as e:
+            logger.warning(f"Bigtable ping failed: {e}")
+            return 1
diff --git a/lmcache/v1/storage_backend/connector/bigtable_schema.py b/lmcache/v1/storage_backend/connector/bigtable_schema.py
new file mode 100644
index 0000000..f21ad67
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/bigtable_schema.py
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.utils import CacheEngineKey
+
+
+class BigtableSchema:
+    def __init__(self, row_key_template: str, family_name: str, column_name: str):
+        self.row_key_template = row_key_template
+        self.family_name = family_name
+        self.column_name = column_name
+
+    def get_row_key(self, key: "CacheEngineKey") -> bytes:
+        fingerprint = (
+            f"{key.model_name}@{key.world_size}@{key.worker_id}@{key._dtype_str}"
+        )
+        if key.tags is not None and len(key.tags) != 0:
+            tags_str = "@".join([f"{k}%{v}" for k, v in key.tags])
+            fingerprint += f"@{tags_str}"
+
+        template = self.row_key_template
+        if "{hash}" in template:
+            row_key_str = template.replace("{hash}", key.chunk_hash_hex)
+        else:
+            row_key_str = template.replace("hash", key.chunk_hash_hex)
+
+        if "{model}" in row_key_str:
+            row_key_str = row_key_str.replace("{model}", fingerprint)
+        else:
+            row_key_str = row_key_str.replace("model", fingerprint)
+
+        return row_key_str.encode("utf-8")
+
+    def extract_cell_value(self, row: Any) -> Optional[bytes]:
+        if row is None or not hasattr(row, "cells"):
+            return None
+
+        col_bytes = (
+            self.column_name.encode("utf-8")
+            if isinstance(self.column_name, str)
+            else self.column_name
+        )
+
+        # Handle dict access (classic) or list access (v2 data client) flexibly
+        if isinstance(row.cells, dict):
+            cells_dict = row.cells.get(self.family_name, {})
+            col_cells = cells_dict.get(col_bytes, [])
+            if col_cells:
+                return col_cells[0].value
+        else:
+            for cell in row.cells:
+                if cell.family == self.family_name and cell.qualifier == col_bytes:
+                    return cell.value
+        return None
diff --git a/lmcache/v1/storage_backend/connector/blackhole_adapter.py b/lmcache/v1/storage_backend/connector/blackhole_adapter.py
new file mode 100644
index 0000000..0716316
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/blackhole_adapter.py
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import ConnectorAdapter, ConnectorContext
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class BlackholeConnectorAdapter(ConnectorAdapter):
+    """Adapter for Blackhole connectors (for testing)."""
+
+    def __init__(self) -> None:
+        super().__init__("blackhole://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .blackhole_connector import BlackholeConnector
+
+        logger.info(f"Creating Blackhole connector for URL: {context.url}")
+        return BlackholeConnector()
diff --git a/lmcache/v1/storage_backend/connector/blackhole_connector.py b/lmcache/v1/storage_backend/connector/blackhole_connector.py
new file mode 100644
index 0000000..d762ed8
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/blackhole_connector.py
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional, no_type_check
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+
+# reuse
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class BlackholeConnector(RemoteConnector):
+    def __init__(self):
+        pass
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return False
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return False
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return None
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        pass
+
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        logger.info("Closed the blackhole connection")
diff --git a/lmcache/v1/storage_backend/connector/eic_adapter.py b/lmcache/v1/storage_backend/connector/eic_adapter.py
new file mode 100644
index 0000000..95561fc
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/eic_adapter.py
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class EICConnectorAdapter(ConnectorAdapter):
+    """Adapter for EIC connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("eic://")
+
+    def can_parse(self, url: str) -> bool:
+        return url.startswith(self.schema)
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .eic_connector import EICConnector
+
+        logger.info(f"Creating EIC connector for URL: {context.url}")
+        return EICConnector(
+            endpoint=context.url,
+            loop=context.loop,
+            memory_allocator=context.local_cpu_backend,
+        )
diff --git a/lmcache/v1/storage_backend/connector/eic_connector.py b/lmcache/v1/storage_backend/connector/eic_connector.py
new file mode 100644
index 0000000..6490820
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/eic_connector.py
@@ -0,0 +1,758 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from enum import IntEnum, auto
+from typing import List, Optional, Union, no_type_check
+import asyncio
+import ctypes
+import os
+import random
+import string
+import time
+
+# Third Party
+import eic
+import yaml
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey, _lmcache_nvtx_annotate
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+class Priorities(IntEnum):
+    PEEK = auto()
+    PREFETCH = auto()
+    GET = auto()
+    PUT = auto()
+
+
+class PerformanceTimer:
+    def __init__(self, key, op):
+        self.key = key
+        self.size = 0
+        self.op = op
+        self.start_times = {}
+        self.elapsed_times = {}
+
+    def set_size(self, size):
+        self.size = size
+
+    def start(self, operation_name):
+        self.start_times[operation_name] = time.perf_counter()
+
+    # unit: us
+    def stop(self, operation_name):
+        if operation_name not in self.start_times:
+            raise ValueError(f"operation {operation_name} not found")
+
+        end_time = time.perf_counter()
+        start_time = self.start_times[operation_name]
+        elapsed_time = end_time - start_time
+        self.elapsed_times[operation_name] = elapsed_time * 1000000
+        del self.start_times[operation_name]
+        return elapsed_time
+
+    def get_elapsed_time(self, operation_name):
+        return self.elapsed_times.get(operation_name)
+
+    def get_all_elapsed_times(self):
+        return self.elapsed_times
+
+    def debug_all_elapsed_times(self):
+        logger.debug(f"== Perf key:{self.key} =========")
+        logger.debug(f"== Perf op {self.op} size {self.size} =========")
+        for op, item in self.elapsed_times.items():
+            logger.debug(f"Step: {op} cost {item:.2f} us")
+        logger.debug(f"== Perf op {self.op} size {self.size} =========")
+
+
+class FlexibleDRAMMemoryPool:
+    def __init__(self, conn):
+        self._init = False
+        self.connection = conn
+        self.used_mem = {}
+
+    def allocate(self, size):
+        ptr = self.connection.allocate_managed_buffer(size)
+        if ptr == 0:
+            logger.error(f"fail to allocate dram pool, ptr {ptr}, size {size}")
+            return ptr
+        logger.debug(f"allocate dram pool: ptr {ptr}, size {size}")
+        self.used_mem[ptr] = size
+        return ptr
+
+    def deallocate(self, ptr):
+        size = self.used_mem.get(ptr)
+        if size is not None:
+            logger.debug(f"deallocate dram pool: ptr {ptr}, size {size}")
+            self.connection.free_managed_buffer(ptr, size)
+            del self.used_mem[ptr]
+
+
+def _make_dir(path: str):
+    try:
+        if not os.path.exists(path):
+            os.makedirs(path)
+        logger.info(f"create dir '{path}' success")
+    except OSError as e:
+        logger.error(f"create dir '{path}' error {e}")
+
+
+class EICConnector(RemoteConnector):
+    """
+    The remote url should start with "eic://" and only have one host-port pair
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        loop: asyncio.AbstractEventLoop,
+        memory_allocator: LocalCPUBackend,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(memory_allocator.config, memory_allocator.metadata)
+
+        logger.info("init EICConnector")
+        logger.info(f"try connect to eic: {endpoint}")
+
+        self.loop = loop
+        self.memory_allocator = memory_allocator
+
+        # Initialize pq_executor early to avoid AttributeError
+        try:
+            self.pq_executor = AsyncPQExecutor(loop)
+            logger.info("AsyncPQExecutor initialized successfully")
+        except Exception as e:
+            logger.error(f"Failed to initialize AsyncPQExecutor: {e}")
+            raise
+
+        self.cudaError_t = ctypes.c_int
+        self.cudaMemcpyDeviceToHost = 2
+        self.cudaMemcpyHostToDevice = 1
+        self.cuda_lib = ctypes.CDLL("libcudart.so")
+        self.cuda_lib.cudaMemcpy.argtypes = [
+            ctypes.c_void_p,
+            ctypes.c_void_p,
+            ctypes.c_size_t,
+            ctypes.c_int,
+        ]
+        self.cuda_lib.cudaMemcpy.restype = self.cudaError_t
+
+        self.enable_compare = False
+
+        config_file = os.getenv("LMCACHE_CONFIG_FILE")
+        if config_file is None:
+            raise ValueError("LMCACHE_CONFIG_FILE environment variable is not set")
+        with open(config_file, "r") as fin:
+            config = yaml.safe_load(fin)
+
+        remote_url = config.get("remote_url", None)
+        logger.info(f"eic remote_url: {remote_url}")
+
+        eic_instance_id = config.get("eic_instance_id", None)
+        logger.info(f"eic instance_id: {eic_instance_id}")
+
+        eic_thread_num = config.get("eic_thread_num", 6)
+        logger.info(f"eic thread_num: {eic_thread_num}")
+
+        eic_log_dir = config.get("eic_log_dir", None)
+        logger.info(f"eic log_dir: {eic_log_dir}")
+
+        eic_log_level = config.get("eic_log_level", 1)
+        logger.info(f"eic log_level: {eic_log_level}")
+
+        eic_trans_type = config.get("eic_trans_type", 3)
+        logger.info(f"eic trans_type: {eic_trans_type}")
+
+        self.eic_kv_ttl = config.get("eic_kv_ttl", -1)
+        logger.info(f"eic eic_kv_ttl: {self.eic_kv_ttl}")
+
+        self.eic_kv_ns = config.get("eic_kv_ns", "")
+        logger.info(f"eic eic_kv_ns: {self.eic_kv_ns}")
+
+        eic_flag_file = config.get("eic_flag_file", None)
+        logger.info(f"eic flag_file: {eic_flag_file}")
+
+        _make_dir(eic_log_dir)
+
+        self.connection = eic.Client()
+        init_option = eic.InitOption()
+        init_option.log_dir = eic_log_dir
+        init_option.log_level = eic.LogLevel(eic_log_level)
+        init_option.transport_type = eic.TransportType(eic_trans_type)
+        init_option.flag_file = eic_flag_file
+        endpoint = endpoint.removeprefix("eic://").removesuffix("/")
+        ret = self.connection.init(eic_instance_id, endpoint, init_option)
+        if ret != 0:
+            logger.error(f"fail to init eic client, ret: {ret}")
+            raise RuntimeError(
+                f"Failed to initialize eic client with error code: {ret}"
+            )
+        else:
+            logger.info(f"init eic client success, ret: {ret}")
+
+        self.trans_type = eic.TransportType(eic_trans_type)
+
+        # Register memory in rdma and gdr scenarios
+        if self.trans_type == eic.TransportType.TRANSPORT_GDR:
+            if not isinstance(self.memory_allocator, LocalCPUBackend):
+                raise RuntimeError("memory_allocator must be LocalCPUBackend")
+            allocator = self.memory_allocator.memory_allocator
+            if not isinstance(allocator, MixedMemoryAllocator):
+                raise RuntimeError(
+                    "memory_allocator.memory_allocator must be MixedMemoryAllocator"
+                )
+
+            if hasattr(allocator, "pin_allocator") and hasattr(
+                allocator.pin_allocator, "buffer"
+            ):
+                mem_pool = allocator.pin_allocator.buffer
+                meminfo = eic.MemoryInfo()
+                meminfo.type = eic.MemoryType.MEMORY_CUDA
+                meminfo.cuda_id = 0
+
+                vals = eic.IOBuffers()
+                vals.append(
+                    mem_pool.data_ptr(),
+                    mem_pool.numel() * mem_pool.element_size(),
+                    True,
+                )
+
+                if self.connection.register_memory(vals, meminfo):
+                    logger.info("register mixed memory pin buffer success")
+                else:
+                    logger.error("fail to register mixed memory pin buffer")
+                    exit(1)
+            else:
+                logger.error("mixed memory pin buffer is None")
+                exit(1)
+        self.prebuilt_connection()
+
+    def prebuilt_connection(self) -> None:
+        def random_string(N):
+            return self.eic_kv_ns.join(
+                random.choices(string.ascii_uppercase + string.digits, k=N)
+            )
+
+        try:
+            for i in range(2048):
+                key = random_string(30)
+                self._exists_sync(key)
+            logger.info("eic prebuilt connection finish")
+        except Exception as e:
+            logger.error(f"Error in prebuilt connection thread: {e}")
+
+    def delete_sync(self, key: str) -> bool:
+        keys = eic.StringVector()
+        keys.append(key)
+        status_code, _ = self.connection.mdel(keys)
+        if status_code != eic.StatusCode.SUCCESS:
+            logger.debug(f"eic delete {key} failed, status_code {status_code}")
+            return False
+        return True
+
+    def _exists_sync(self, key_str: str) -> bool:
+        keys = eic.StringVector()
+        keys.append(key_str)
+        exist_option = eic.ExistOption()
+        status_code, exist_outcome = self.connection.mexist(keys, exist_option)
+        if status_code != eic.StatusCode.SUCCESS:
+            logger.debug(f"eic exists {key_str} failed, status_code {status_code}")
+            return False
+
+        err_code = exist_outcome.status_codes[0]
+        success = err_code == eic.StatusCode.SUCCESS
+        if success:
+            logger.debug(f"eic exists {key_str} success")
+        else:
+            logger.debug(
+                f"eic exists {key_str} failed, status_code {status_code} "
+                "err_code {err_code}"
+            )
+        return success
+
+    async def _exists(self, key: CacheEngineKey) -> bool:
+        return self._exists_sync(key.to_string())
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        return await self.pq_executor.submit_job(
+            self._exists, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return self._exists_sync(key.to_string())
+
+    async def get_meta(self, key_str: str) -> Optional[RemoteMetadata]:
+        perf_timer = PerformanceTimer(key_str, "get_meta")
+        perf_timer.start("total_cost")
+
+        # Get Meta: generate meta keys and vals
+        meta_keys = eic.StringVector()
+        meta_vals = eic.IOBuffers()
+
+        # Get Meta: generate meta buffer tensor
+        perf_timer.start("alloc_mem")
+        meta_key = key_str + "_meta"
+        meta_size = self.remote_metadata_bytes
+        meta_bytes = bytearray(meta_size)
+        meta_bytes_ptr = self.bytes_get_ptr(meta_bytes)
+
+        meta_keys.append(meta_key)
+        meta_vals.append(meta_bytes_ptr, meta_size, False)
+
+        perf_timer.set_size(meta_size)
+        perf_timer.stop("alloc_mem")
+
+        # Get Meta: recv meta buffer tensor
+        perf_timer.start("eic_mget")
+        get_option = eic.GetOption()
+        get_option.ns = self.eic_kv_ns
+        status_code, meta_vals, get_outcome = self.connection.mget(
+            meta_keys, get_option, meta_vals
+        )
+        err_code = get_outcome.status_codes[0]
+        if status_code != eic.StatusCode.SUCCESS or err_code != eic.StatusCode.SUCCESS:
+            if err_code == eic.StatusCode.KEY_NOT_EXIST:
+                logger.debug(
+                    f"eic mget meta {key_str} failed, status_code {status_code}"
+                    " err_code {err_code}"
+                )
+            else:
+                logger.error(
+                    f"eic mget meta {key_str} failed, status_code {status_code}"
+                    " err_code {err_code}"
+                )
+            return None
+        else:
+            logger.debug(f"eic mget meta {key_str} success")
+
+        perf_timer.stop("eic_mget")
+
+        perf_timer.start("serialize")
+        meta = RemoteMetadata.deserialize(meta_bytes[:meta_size])
+        perf_timer.stop("serialize")
+
+        perf_timer.stop("total_cost")
+        perf_timer.debug_all_elapsed_times()
+
+        return meta
+
+    async def get_data(self, key_str: str, meta: RemoteMetadata) -> Optional[MemoryObj]:
+        perf_timer = PerformanceTimer(key_str, "get_data")
+        perf_timer.start("total_cost")
+        perf_timer.start("alloc_obj")
+        memory_obj = self.memory_allocator.allocate(
+            meta.shapes,
+            meta.dtypes,
+            meta.fmt,
+        )
+        if memory_obj is None:
+            logger.error(
+                f"fail to allocate memory during remote receive key {key_str} length"
+                " {meta.length}"
+            )
+            return None
+        perf_timer.stop("alloc_obj")
+
+        perf_timer.start("alloc_mem")
+        obj_size = memory_obj.get_size()
+        data_ptr = memory_obj.tensor.data_ptr()
+        data_keys = eic.StringVector()
+        data_vals = eic.IOBuffers()
+        data_keys.append(key_str)
+
+        perf_timer.set_size(obj_size)
+        perf_timer.stop("alloc_mem")
+
+        try:
+            if self.trans_type == eic.TransportType.TRANSPORT_GDR:
+                data_vals.append(data_ptr, obj_size, True)
+            else:
+                data_vals.append(data_ptr, obj_size, False)
+
+            perf_timer.start("eic_mget")
+            get_option = eic.GetOption()
+            get_option.ns = self.eic_kv_ns
+            status_code, data_vals, get_outcome = self.connection.mget(
+                data_keys, get_option, data_vals
+            )
+            err_code = get_outcome.status_codes[0]
+            if (
+                status_code != eic.StatusCode.SUCCESS
+                or err_code != eic.StatusCode.SUCCESS
+            ):
+                logger.error(
+                    f"eic mget data {key_str} failed, status_code {status_code} "
+                    f"err_code {err_code}"
+                )
+                memory_obj.ref_count_down()
+                return None
+            else:
+                logger.debug(f"eic mget data {key_str} success")
+        except Exception as e:
+            logger.error(
+                f"eic mget data {key_str} raised exception: {e}", exc_info=True
+            )
+            memory_obj.ref_count_down()
+            return None
+
+        perf_timer.stop("eic_mget")
+
+        perf_timer.stop("total_cost")
+        perf_timer.debug_all_elapsed_times()
+
+        return memory_obj
+
+    async def _get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+        meta = await self.get_meta(key_str)
+        if meta is None:
+            return None
+        data = await self.get_data(key_str, meta)
+        return data
+
+    @_lmcache_nvtx_annotate
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        return await self.pq_executor.submit_job(
+            self._get, key=key, priority=Priorities.GET
+        )
+
+    def bytes_get_ptr(self, mv: Union[bytearray, memoryview, bytes]) -> int:
+        if isinstance(mv, bytes):
+            pointer = ctypes.cast(ctypes.c_char_p(mv), ctypes.POINTER(ctypes.c_char))
+            ptr = ctypes.addressof(pointer.contents)
+            return ptr
+        return ctypes.addressof(ctypes.c_char.from_buffer(mv))
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        return self._put_sync(key, memory_obj)
+
+    def _put_sync(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        key_str = key.to_string()
+        logger.debug(f"eic put {key_str}")
+
+        perf_timer = PerformanceTimer(key_str, "put_data")
+        perf_timer.start("total_cost")
+        kv_bytes = memory_obj.byte_array
+        kv_tensor = memory_obj.tensor
+        kv_shapes = memory_obj.get_shapes()
+        kv_dtypes = memory_obj.get_dtypes()
+        memory_format = memory_obj.get_memory_format()
+        value_size = memory_obj.get_physical_size()
+
+        logger.debug(
+            f"eic put {key_str} data len {len(kv_bytes)} value_size {value_size}"
+        )
+
+        if kv_tensor is None:
+            logger.error(f"Memory object tensor is None for key {key_str}")
+            return
+
+        perf_timer.start("serialize")
+
+        # generate meta bytes
+        remote_meta = RemoteMetadata(
+            self.remote_metadata_bytes, kv_shapes, kv_dtypes, memory_format
+        )
+
+        logger.debug(f"eic meta {key_str} remote_meta{remote_meta}")
+
+        meta_bytes = remote_meta.serialize()
+
+        perf_timer.stop("serialize")
+
+        perf_timer.start("trans_address")
+        # generate meta & data ptr
+        meta_ptr = self.bytes_get_ptr(meta_bytes)
+        meta_size = len(meta_bytes)
+        data_ptr = kv_tensor.data_ptr()
+        data_size = len(kv_bytes)
+        perf_timer.set_size(data_size)
+        perf_timer.stop("trans_address")
+
+        logger.debug(
+            f"eic put {key_str} meta ptr {meta_ptr} len {meta_size} data ptr {data_ptr}"
+            " len {data_size}"
+        )
+
+        perf_timer.start("eic_mset")
+        keys = eic.StringVector()
+        vals = eic.IOBuffers()
+
+        # set meta key & value
+        meta_key = key_str + "_meta"
+        keys.append(meta_key)
+        vals.append(meta_ptr, meta_size, False)
+
+        # set data key & value
+        keys.append(key_str)
+        if self.trans_type == eic.TransportType.TRANSPORT_GDR:
+            vals.append(data_ptr, data_size, True)
+        else:
+            vals.append(data_ptr, data_size, False)
+
+        # set options
+        set_option = eic.SetOption()
+        set_option.ns = self.eic_kv_ns
+        set_option.ttl_second = self.eic_kv_ttl
+
+        status_code, set_outcome = self.connection.mset(keys, vals, set_option)
+        if status_code != eic.StatusCode.SUCCESS:
+            logger.error(f"eic mset {key_str} failed, status_code {status_code}")
+
+        err_code = set_outcome.status_codes[0]
+        if err_code == eic.StatusCode.SUCCESS:
+            logger.debug(f"eic put meta key {meta_key} success")
+        else:
+            logger.error(f"eic put meta key {meta_key} failed, err_code {err_code}")
+
+        err_code = set_outcome.status_codes[1]
+        if err_code == eic.StatusCode.SUCCESS:
+            logger.debug(f"eic put data key {key_str} success")
+        else:
+            logger.error(f"eic put data key {key_str} failed, err_code {err_code}")
+
+        perf_timer.stop("eic_mset")
+        perf_timer.stop("total_cost")
+        perf_timer.debug_all_elapsed_times()
+
+    async def _batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        if not keys or not memory_objs:
+            return
+
+        # Prepare all keys and values for batch mset
+        eic_keys = eic.StringVector()
+        eic_vals = eic.IOBuffers()
+        # Keep references to meta_bytes to prevent dangling pointers
+        meta_list = []
+        for key, memory_obj in zip(keys, memory_objs, strict=False):
+            key_str = key.to_string()
+            logger.debug(f"eic batched_put processing {key_str}")
+
+            # Get memory object data
+            kv_bytes = memory_obj.byte_array
+            kv_tensor = memory_obj.tensor
+            kv_shapes = memory_obj.get_shapes()
+            kv_dtypes = memory_obj.get_dtypes()
+            memory_format = memory_obj.get_memory_format()
+            if kv_tensor is None:
+                logger.error(f"Memory object tensor is None for key {key_str}")
+                return
+
+            remote_meta = RemoteMetadata(
+                self.remote_metadata_bytes, kv_shapes, kv_dtypes, memory_format
+            )
+            meta_bytes = remote_meta.serialize()
+            meta_list.append(meta_bytes)
+            meta_ptr = self.bytes_get_ptr(meta_bytes)
+            meta_size = len(meta_bytes)
+            data_ptr = kv_tensor.data_ptr()
+            data_size = len(kv_bytes)
+
+            logger.info(
+                "eic batched_put %s, shapes: %s, dtypes: %s, fmt: %s",
+                key_str,
+                kv_shapes,
+                kv_dtypes,
+                memory_format,
+            )
+
+            # Add meta key & value
+            meta_key = key_str + "_meta"
+            eic_keys.append(meta_key)
+            eic_vals.append(meta_ptr, meta_size, False)
+            # Add data key & value
+            eic_keys.append(key_str)
+            if self.trans_type == eic.TransportType.TRANSPORT_GDR:
+                eic_vals.append(data_ptr, data_size, True)
+            else:
+                eic_vals.append(data_ptr, data_size, False)
+
+        set_option = eic.SetOption()
+        set_option.ns = self.eic_kv_ns
+        set_option.ttl_second = self.eic_kv_ttl
+
+        set_status_code, set_outcome = self.connection.mset(
+            eic_keys, eic_vals, set_option
+        )
+
+        if set_status_code != eic.StatusCode.SUCCESS:
+            logger.error(
+                f"eic batched_put mset data failed, status_code {set_status_code}"
+            )
+            return
+        for i, key_str in enumerate(eic_keys):
+            meta_key = key_str + "_meta"
+
+            outcome_err_code = set_outcome.status_codes[i]
+            log_key = meta_key if i % 2 == 0 else key_str
+            if outcome_err_code == eic.StatusCode.SUCCESS:
+                logger.debug(f"eic batched_put {log_key} success")
+            else:
+                logger.error(
+                    f"eic batched_put {log_key} failed, err_code {outcome_err_code}"
+                )
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        return await self.pq_executor.submit_job(
+            self._put, key=key, memory_obj=memory_obj, priority=Priorities.PUT
+        )
+
+    def support_batched_put(self) -> bool:
+        return False
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        await self.pq_executor.submit_job(
+            self._batched_put,
+            keys=keys,
+            memory_objs=memory_objs,
+            priority=Priorities.PUT,
+        )
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def _batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        if not keys:
+            return 0
+
+        # Convert all keys to strings at once
+        key_strings = eic.StringVector()
+        for key in keys:
+            key_strings.append(key.to_string())
+
+        # Use mexist to check all keys at once
+        exist_option = eic.ExistOption()
+        status_code, exist_outcome = self.connection.mexist(key_strings, exist_option)
+
+        if status_code != eic.StatusCode.SUCCESS:
+            logger.error(
+                f"eic batched_async_contains mexist failed, status_code {status_code}"
+            )
+            return 0
+
+        # Count consecutive hits from the beginning
+        num_hit_counts = 0
+        for i, key in enumerate(keys):
+            status_code = exist_outcome.status_codes[i]
+            if status_code != eic.StatusCode.SUCCESS:
+                logger.debug(
+                    f"eic batched_async_contains {key.to_string()} miss,"
+                    " err_code {status_code}"
+                )
+                break
+            num_hit_counts += 1
+        return num_hit_counts
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains,
+            lookup_id=lookup_id,
+            keys=keys,
+            pin=pin,
+            priority=Priorities.PEEK,
+        )
+
+    def support_batched_get(self) -> bool:
+        return True
+
+    async def _batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        # calling self.get will create a circular dependency
+        results = await asyncio.gather(*(self._get(key) for key in keys))
+        return results
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        return await self.pq_executor.submit_job(
+            self._batched_get,
+            keys=keys,
+            priority=Priorities.GET,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def _batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        # calling self.get will create a circular dependency
+        results = await asyncio.gather(*(self._get(key) for key in keys))
+        return [r for r in results if r is not None]
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        if not hasattr(self, "pq_executor") or self.pq_executor is None:
+            logger.error("pq_executor is not initialized in EICConnector")
+            raise AttributeError("pq_executor is not initialized")
+
+        return await self.pq_executor.submit_job(
+            self._batched_get_non_blocking,
+            lookup_id=lookup_id,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+    async def close(self):
+        if hasattr(self, "pq_executor") and self.pq_executor is not None:
+            await self.pq_executor.shutdown(wait=True)
+        if self.connection:
+            self.connection = None
+        logger.info("closed the eic connection")
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
diff --git a/lmcache/v1/storage_backend/connector/external_adapter.py b/lmcache/v1/storage_backend/connector/external_adapter.py
new file mode 100644
index 0000000..65aaf96
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/external_adapter.py
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class ExternalConnectorAdapter(ConnectorAdapter):
+    """Adapter for External connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("external://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """
+        Create an External connector. This connector stores data
+        in the key-value store.
+        URL format:
+        - external://host:port/module_path/?connector_name=ConnectorName
+        Examples:
+        - external://host:0/external_log_connector.lmc_external_log_connector/?connector_name=ExternalLogConnector
+        """
+        logger.info(f"Creating External connector for URL: {context.url}")
+        logger.warning(
+            "External connector is due for deprecation in release v0.5.0. "
+            "Please use the Remote Storage Plugin Framework instead."
+        )
+        hosts = context.url.split(",")
+        if len(hosts) > 1:
+            raise ValueError(
+                f"Only one host is supported for external connector, but got {hosts}"
+            )
+
+        parse_url = parse_remote_url(context.url)
+
+        # Get the module path and connector name
+        module_path = parse_url.path.strip("/")
+        connector_name = parse_url.query_params.get("connector_name", [""])[0]
+        if not connector_name:
+            raise ValueError(
+                "External connector requires 'connector_name' in query parameters"
+            )
+
+        # Lazily import the module and get the connector class
+        # Standard
+        import importlib
+
+        try:
+            module = importlib.import_module(module_path)
+            connector_class = getattr(module, connector_name)
+
+            # Verify that it's a subclass of RemoteConnector
+            if not issubclass(connector_class, RemoteConnector):
+                raise TypeError(
+                    f"{connector_name} must be a subclass of RemoteConnector"
+                )
+
+            # Create the connector instance
+            connector = connector_class(
+                loop=context.loop,
+                local_cpu_backend=context.local_cpu_backend,
+                config=context.config,
+            )
+            logger.info(f"Loaded external connector: {module_path}.{connector_name}")
+            return connector
+        except ImportError as e:
+            raise ImportError(
+                f"Could not import module '{module_path}', error: {e}"
+            ) from e
+        except AttributeError as e:
+            raise AttributeError(
+                f"Module '{module_path}' has no class '{connector_name}', error: {e}"
+            ) from e
diff --git a/lmcache/v1/storage_backend/connector/fs_adapter.py b/lmcache/v1/storage_backend/connector/fs_adapter.py
new file mode 100644
index 0000000..3e27151
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/fs_adapter.py
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    extract_plugin_type,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import (
+    RemoteConnector,
+)
+
+logger = init_logger(__name__)
+
+PLUGIN_TYPE = "fs"
+
+
+class FsConnectorAdapter(ConnectorAdapter):
+    """Adapter for Filesystem connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("fs://")
+
+    def can_parse(self, url: str) -> bool:
+        if url.startswith(self.schema):
+            return True
+        if url.startswith("plugin://"):
+            pname = url[len("plugin://") :]
+            return extract_plugin_type(pname) == PLUGIN_TYPE
+        return False
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .fs_connector import FSConnector
+
+        logger.info("Creating FS connector")
+
+        # Legacy URL mode: extract base_path from URL
+        base_paths_str = None
+        if context.plugin_name is None:
+            parsed = parse_remote_url(context.url)
+            base_paths_str = parsed.path
+
+        return FSConnector(
+            context.loop,
+            context.local_cpu_backend,
+            context.config,
+            plugin_name=context.plugin_name,
+            base_paths_str=base_paths_str,
+        )
diff --git a/lmcache/v1/storage_backend/connector/fs_connector.py b/lmcache/v1/storage_backend/connector/fs_connector.py
new file mode 100644
index 0000000..f1fad48
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/fs_connector.py
@@ -0,0 +1,409 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+from typing import List, Optional, Tuple, no_type_check
+import asyncio
+import os
+
+# Third Party
+import aiofiles
+import aiofiles.os
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+class FSConnector(RemoteConnector):
+    """File system based connector that stores data in local files.
+
+    Data is stored in the following format:
+    - Each key is stored as a separate file
+    - File content: metadata (remote_metadata_bytes) + serialized data
+    """
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        config: Optional[LMCacheEngineConfig],
+        plugin_name: Optional[str] = None,
+        base_paths_str: Optional[str] = None,
+    ):
+        """
+        Args:
+            loop: Asyncio event loop
+            local_cpu_backend: Memory allocator interface
+            config: Lmcache engine config
+            plugin_name: Plugin instance name
+                (e.g. "fs", "fs.primary")
+            base_paths_str: Comma-separated base paths
+                (legacy, passed from adapter when using
+                fs:// URL)
+        """
+        # initialize base class
+        super().__init__(
+            local_cpu_backend.config,
+            local_cpu_backend.metadata,
+        )
+
+        base_path = base_paths_str
+        if base_path is None:
+            # Resolve from extra_config
+            extra_config = config.extra_config if config else None
+            if extra_config is not None:
+                key_prefix = plugin_name or "fs"
+                base_path = extra_config.get(
+                    "remote_storage_plugin.%s.base_path" % key_prefix
+                )
+            if base_path is None:
+                if extra_config is not None:
+                    base_path = extra_config.get("fs_base_path")
+            if base_path is None:
+                raise ValueError(
+                    "FS connector requires base_path via URL or extra_config"
+                )
+
+        # Parse comma separated paths
+        self.base_paths = (
+            [Path(p.strip()) for p in base_path.split(",")]
+            if "," in base_path
+            else [Path(base_path)]
+        )
+
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        relative_tmp_dir = (
+            None
+            if config is None
+            else config.get_extra_config_value("fs_connector_relative_tmp_dir", None)
+        )
+        self.relative_tmp_dir = None
+        if relative_tmp_dir is not None:
+            self.relative_tmp_dir = Path(relative_tmp_dir)
+            assert not self.relative_tmp_dir.is_absolute()
+
+        self.read_ahead_size = (
+            None
+            if config is None
+            else config.get_extra_config_value("fs_connector_read_ahead_size", None)
+        )
+
+        self.use_odirect = (
+            False
+            if config is None
+            else config.get_extra_config_value("fs_connector_use_odirect", False)
+        )
+        self.os_disk_bs = 0
+        if self.use_odirect:
+            # save_chunk_meta is useful if save_unfull_chunk is True, since partial
+            # chunk will be saved. When loading partial chunk, we need to know
+            # data size and shape. However, chunk meta is short (28 bytes) which
+            # is not aligned to disk block size (512 or 4096).
+            # Therefore, we disable O_DIRECT if save_chunk_meta is True.
+            # TODO: support O_DIRECT for save_chunk_meta by
+            # padding meta data to 4096.
+            if self.save_chunk_meta:
+                logger.warning("Cannot use O_DIRECT if save_chunk_meta enabled.")
+                self.use_odirect = False
+            else:
+                stat = os.statvfs(self.base_paths[0])
+                self.os_disk_bs = stat.f_bsize
+
+        logger.info(
+            "Initialized FSConnector with base paths %s, "
+            "relative tmp dir: %s, "
+            "read ahead size: %s, "
+            "use O_DIRECT: %s",
+            self.base_paths,
+            self.relative_tmp_dir,
+            self.read_ahead_size,
+            self.use_odirect,
+        )
+        # Create directories for all paths
+        for path in self.base_paths:
+            path.mkdir(parents=True, exist_ok=True)
+            if self.relative_tmp_dir is not None:
+                (path / self.relative_tmp_dir).mkdir(parents=False, exist_ok=True)
+
+    def _get_base_path(self, key: CacheEngineKey) -> Path:
+        """Get file base path for the given key"""
+        if len(self.base_paths) == 1:
+            base_path = self.base_paths[0]
+        else:
+            # Calculate hash value and modulo to select path
+            hash_val = abs(key.chunk_hash)
+            idx = hash_val % len(self.base_paths)
+            base_path = self.base_paths[idx]
+
+        return base_path
+
+    def _get_file_name(self, key: CacheEngineKey) -> str:
+        return key.to_string().replace("/", "-SEP-") + ".data"
+
+    def _get_file_path(self, key: CacheEngineKey) -> Path:
+        """Get file path for the given key"""
+        base_path = self._get_base_path(key)
+        file_name = self._get_file_name(key)
+        return base_path / file_name
+
+    def _get_file_and_tmp_path(self, key: CacheEngineKey) -> Tuple[Path, Path]:
+        """Get file and tmp path for the given key"""
+        base_path = self._get_base_path(key)
+        file_name = self._get_file_name(key)
+        file_path = base_path / file_name
+        if self.relative_tmp_dir is not None:
+            tmp_path = base_path / self.relative_tmp_dir / file_name
+        else:
+            tmp_path = file_path.with_suffix(".tmp")
+        return file_path, tmp_path
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """Check if key exists in file system"""
+        file_path = self._get_file_path(key)
+        return await aiofiles.os.path.exists(file_path)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Check if key exists in file system synchronized"""
+        file_path = self._get_file_path(key)
+        return os.path.exists(file_path)
+
+    def _get_with_odirect(self, file_path: Path) -> Optional[MemoryObj]:
+        """Synchronous direct IO read, executed in a thread."""
+        fd = -1
+        memory_obj: Optional[MemoryObj] = None
+        try:
+            memory_obj = self.local_cpu_backend.allocate(
+                self.meta_shapes, self.meta_dtypes, self.meta_fmt
+            )
+            if memory_obj is None:
+                logger.debug("Memory allocation failed.")
+                return None
+
+            buffer = memory_obj.byte_array
+            size = len(buffer)
+
+            fblock_aligned = (
+                self.os_disk_bs is not None
+                and self.os_disk_bs > 0
+                and size % self.os_disk_bs == 0
+            )
+            if not fblock_aligned:
+                logger.warning(
+                    "Cannot use O_DIRECT for %s, size is not aligned.", file_path
+                )
+                with open(file_path, "rb") as f:
+                    num_read = f.readinto(buffer)
+            else:
+                fd = os.open(file_path, os.O_RDONLY | getattr(os, "O_DIRECT", 0))
+                with os.fdopen(fd, "rb", buffering=0) as fdo:
+                    # The fd is now managed by the file object, so we "forget" it
+                    # to prevent closing it in the finally block.
+                    fd = -1
+                    num_read = fdo.readinto(buffer)
+
+            memory_obj = self.reshape_partial_chunk(memory_obj, num_read)
+            return memory_obj
+
+        except Exception as e:
+            logger.error("Failed to read from file %s: %s", file_path, str(e))
+            if memory_obj is not None:
+                memory_obj.ref_count_down()
+            return None
+        finally:
+            if fd >= 0:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Get data from file system"""
+        file_path = self._get_file_path(key)
+
+        if self.use_odirect and not self.save_chunk_meta:
+            return await self.loop.run_in_executor(
+                None, self._get_with_odirect, file_path
+            )
+
+        memory_obj = None
+        try:
+            async with aiofiles.open(file_path, "rb") as f:
+                if self.save_chunk_meta:
+                    # Read metadata buffer first to get shape, dtype, fmt
+                    # to be able to allocate memory object for the data and read into it
+                    md_buffer = bytearray(self.remote_metadata_bytes)
+                    num_read = await f.readinto(md_buffer)
+                    if num_read != len(md_buffer):
+                        raise RuntimeError(
+                            f"Partial read meta {len(md_buffer)} got {num_read}"
+                        )
+
+                    # Deserialize metadata and allocate memory
+                    metadata = RemoteMetadata.deserialize(md_buffer)
+                    memory_obj = self.local_cpu_backend.allocate(
+                        metadata.shapes, metadata.dtypes, metadata.fmt
+                    )
+                else:
+                    memory_obj = self.local_cpu_backend.allocate(
+                        self.meta_shapes, self.meta_dtypes, self.meta_fmt
+                    )
+                if memory_obj is None:
+                    logger.debug("Memory allocation failed during async disk load.")
+                    return None
+
+                # Read the actual data into allocated memory
+                buffer = memory_obj.byte_array
+                if self.save_chunk_meta:
+                    # if save chunk meta, read meta will trigger
+                    # read ahead if fs supported
+                    num_read = await f.readinto(buffer)
+                    if num_read != len(buffer):
+                        raise RuntimeError(
+                            f"Partial read data {len(buffer)} got {num_read}"
+                        )
+                else:
+                    if self.read_ahead_size is None:
+                        num_read = await f.readinto(buffer)
+                    else:
+                        if not isinstance(buffer, memoryview):
+                            buffer = memoryview(buffer)
+
+                        # trigger read head if fs supported
+                        num_read_ahead = await f.readinto(
+                            buffer[: self.read_ahead_size]
+                        )
+                        assert num_read_ahead <= self.read_ahead_size
+
+                        # if num_read_ahead == self.read_ahead_size,
+                        # means there may still be some remaining content
+                        if num_read_ahead == self.read_ahead_size:
+                            num_read_tail = await f.readinto(
+                                buffer[self.read_ahead_size :]
+                            )
+                            assert num_read_tail is not None
+                            num_read = num_read_ahead + num_read_tail
+                        else:
+                            num_read = num_read_ahead
+                    # reshape and check
+                    assert num_read is not None
+                    memory_obj = self.reshape_partial_chunk(memory_obj, num_read)
+
+            return memory_obj
+
+        except Exception as e:
+            if not isinstance(e, FileNotFoundError):
+                logger.error("Failed to read from file %s: %s", file_path, str(e))
+            if memory_obj is not None:
+                memory_obj.ref_count_down()
+            return None
+
+    def _put_with_odirect(self, file_path: Path, buffer: bytes) -> None:
+        fd = -1
+        try:
+            fd = os.open(
+                str(file_path),
+                os.O_CREAT | os.O_WRONLY | getattr(os, "O_DIRECT", 0),
+                0o644,
+            )
+            os.write(fd, buffer)
+        except Exception as e:
+            logger.error("Failed to write to file %s: %s", file_path, e)
+            raise
+        finally:
+            if fd >= 0:
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Store data to file system"""
+        final_path, temp_path = self._get_file_and_tmp_path(key)
+
+        try:
+            # Prepare metadata
+            buffer = memory_obj.byte_array
+            metadata = (
+                RemoteMetadata(
+                    len(buffer),
+                    memory_obj.get_shapes(),
+                    memory_obj.get_dtypes(),
+                    memory_obj.get_memory_format(),
+                )
+                if self.save_chunk_meta
+                else None
+            )
+
+            size = len(buffer)
+            do_use_odirect = self.use_odirect
+            if do_use_odirect:
+                fblock_aligned = self.os_disk_bs > 0 and size % self.os_disk_bs == 0
+                if not fblock_aligned:
+                    logger.warning(
+                        "Cannot use O_DIRECT for writing size %s, "
+                        "which is not aligned to block size %s.",
+                        size,
+                        self.os_disk_bs,
+                    )
+                    do_use_odirect = False
+
+            if do_use_odirect:
+                # Use Direct I/O
+                await self.loop.run_in_executor(
+                    None, self._put_with_odirect, temp_path, buffer
+                )
+            else:
+                # Use standard async I/O
+                # Write to file (metadata + data)
+                async with aiofiles.open(temp_path, "wb") as f:
+                    if metadata is not None:
+                        await f.write(metadata.serialize())
+                    await f.write(buffer)
+
+            # Atomically rename temp file to final destination
+            await aiofiles.os.replace(temp_path, final_path)
+
+        except Exception as e:
+            logger.error("Failed to write file %s: %s", final_path, str(e))
+            if await aiofiles.os.path.exists(temp_path):
+                await aiofiles.os.unlink(temp_path)  # Remove corrupted file
+            raise
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        """
+        Remove the file associated with the given key.
+
+        Args:
+            key: The key to remove.
+
+        Returns:
+            bool: True if the file was successfully removed, False otherwise.
+        """
+        file_path = self._get_file_path(key)
+        try:
+            os.remove(file_path)
+            return True
+        except OSError as e:
+            logger.error("Failed to remove file %s: %s", file_path, e)
+            return False
+
+    @no_type_check
+    async def list(self) -> List[str]:
+        """List all keys in file system"""
+        keys = []
+        for base_path in self.base_paths:
+            keys.extend([f.stem for f in base_path.glob("*.data")])
+        return keys
+
+    async def close(self):
+        """Clean up resources"""
+        logger.info("Closed the file system connector")
diff --git a/lmcache/v1/storage_backend/connector/hf3fs_adapter.py b/lmcache/v1/storage_backend/connector/hf3fs_adapter.py
new file mode 100644
index 0000000..a81c309
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/hf3fs_adapter.py
@@ -0,0 +1,275 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Samsung Electronics Co., Ltd.All Rights Reserved
+# Authors:
+#   Ruyi Zhang <ruyi.zhang@samsung.com>
+#   Wenwen Chen <wenwen.chen@samsung.com>
+
+# Standard
+from pathlib import Path
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    extract_plugin_type,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+PLUGIN_TYPE = "hf3fs"
+
+
+class HF3fsConnectorAdapter(ConnectorAdapter):
+    """Adapter for HF3fsconnector which access data by 3FS Usrbio interfaces."""
+
+    def __init__(self) -> None:
+        super().__init__("hf3fs://")
+
+    def can_parse(self, url: str) -> bool:
+        if url.startswith(self.schema):
+            return True
+        if url.startswith("plugin://"):
+            pname = url[len("plugin://") :]
+            return extract_plugin_type(pname) == PLUGIN_TYPE
+        return False
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .hf3fs_connector import HF3fsConnector
+
+        if context.config is None:
+            raise ValueError("The config is not set.")
+        if context.config.extra_config is None:
+            raise ValueError("The extra config is not set.")
+
+        # Get config from extra_config
+        self.extra_config = context.config.extra_config
+
+        self.base_paths_str = None
+        # Legacy URL mode: extract base_paths_str from URL
+        if context.plugin_name is None:
+            self.base_paths_str = context.url[len(self.schema) :]
+            logger.info(f"Extract base_path from URL: {context.url}")
+        # Plugin mode: extract base_paths_str from extra_config
+        else:
+            key_prefix = context.plugin_name or PLUGIN_TYPE
+            item = f"remote_storage_plugin.{key_prefix}.base_path"
+            self.base_paths_str = self.extra_config.get(item)
+            if self.base_paths_str is not None:
+                logger.info(f"Extract base_path from extra_config by {item}")
+            else:
+                self.base_paths_str = self.extra_config.get("hf3fs_base_path")
+                logger.info("Extract base_path from extra_config by hf3fs_base_path")
+            if self.base_paths_str is None:
+                raise ValueError(
+                    "HF3fSConnector requires base_path via URL or extra_config"
+                )
+
+        self.hf3fs_mount_point = self.extra_config.get("hf3fs_mount_point", None)
+        self.hf3fs_iov_size = self._get_positive_int(
+            "hf3fs_iov_size", 209715200
+        )  # default 200M
+        self.hf3fs_ior_entries = self._get_positive_int("hf3fs_ior_entries", 256)
+        self.hf3fs_io_depth = self._get_int("hf3fs_io_depth", 0)
+        self.hf3fs_numa_id = self._get_int("hf3fs_numa_id", -1)
+        self.hf3fs_io_thread_num = self._get_positive_int("hf3fs_io_thread_num", 4)
+
+        logger.info(
+            f"HF3fSConnector Config:\n"
+            f"base_paths_str = {self.base_paths_str}\n"
+            f"hf3fs_mount_point = {self.hf3fs_mount_point}\n"
+            f"hf3fs_iov_size = {self.hf3fs_iov_size}\n"
+            f"hf3fs_ior_entries = {self.hf3fs_ior_entries}\n"
+            f"hf3fs_io_depth = {self.hf3fs_io_depth}\n"
+            f"hf3fs_numa_id = {self.hf3fs_numa_id}\n"
+            f"hf3fs_io_thread_num = {self.hf3fs_io_thread_num}\n"
+        )
+
+        # check config
+        if not self._validate_config():
+            logger.error("Invalid configuration of HF3fsConnector")
+            raise ValueError("Invalid configuration of hf3fsConnector")
+
+        logger.info(f"Creating HF3fsConnector by base_paths: {self.base_paths_str}")
+        return HF3fsConnector(
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            mount_point=self.hf3fs_mount_point,
+            iov_size=self.hf3fs_iov_size,
+            ior_entries=self.hf3fs_ior_entries,
+            io_depth=self.hf3fs_io_depth,
+            numa_id=self.hf3fs_numa_id,
+            io_thread_num=self.hf3fs_io_thread_num,
+            plugin_name=context.plugin_name,
+            base_paths_str=self.base_paths_str,
+        )
+
+    def _get_positive_int(self, key: str, default: int) -> int:
+        """
+        Extract a positive integer from config with validation.
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+        Returns:
+            Validated positive integer
+        Raises:
+            ValueError: If value is not a positive integer
+        """
+        value = self.extra_config.get(key, default)
+        try:
+            int_value = int(value)
+            if int_value <= 0:
+                logger.error(f"{key} must be positive, got {int_value}")
+                raise ValueError(f"{key} must be positive, got {int_value}")
+            return int_value
+        except (TypeError, ValueError) as e:
+            logger.error(f"Invalid value for {key}: {value}, must be positive integer")
+            raise ValueError(
+                f"Invalid value for {key}: {value}, must be positive integer"
+            ) from e
+
+    def _get_int(self, key: str, default: int) -> int:
+        """
+        Extract a positive integer from config
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+        Returns:
+            Validated integer
+        Raises:
+            ValueError: If value is not an integer
+        """
+        value = self.extra_config.get(key, default)
+        try:
+            int_value = int(value)
+            return int_value
+        except (TypeError, ValueError) as e:
+            raise ValueError(
+                f"Invalid value for {key}: {value}, must be integer"
+            ) from e
+
+    def _validate_config(self) -> bool:
+        """
+        Validate the configuration.
+        Returns:
+            True if valid, False otherwise
+        """
+        result = True
+        if not 128 <= self.hf3fs_ior_entries <= 1024:
+            logger.error("hf3fs_ior_entries must in range [128, 1024]")
+            result = False
+
+        if not (100 * 1024 * 1024) <= self.hf3fs_iov_size <= (2 * 1024 * 1024 * 1024):
+            logger.error(
+                f"hf3fs_iov_size must in range [{100 * 1024 * 1024}(100MB), "
+                f"{2 * 1024 * 1024 * 1024}(2GB)]"
+            )
+            result = False
+
+        if not -128 <= self.hf3fs_io_depth <= 128:
+            logger.error("hf3fs_io_depth must in range [-128, 128]")
+            result = False
+
+        max_numa_id = self._get_numa_node_count() - 1
+        if not -1 <= self.hf3fs_numa_id <= max_numa_id:
+            logger.error(
+                f"hf3fs_numa_id must in range [-1, {max_numa_id}] in current server"
+            )
+            result = False
+
+        if not 2 <= self.hf3fs_io_thread_num <= 16:
+            logger.error("hf3fs_io_thread_num must in range [2, 16]")
+            result = False
+
+        if not self._validate_paths(self.base_paths_str, self.hf3fs_mount_point):
+            result = False
+        return result
+
+    def _validate_paths(self, base_paths_str, mount_point_path_str) -> bool:
+        """parse the base_paths_str which separated by comma, and validate
+        the paths are subdirectory of mount point path"""
+        try:
+            parent_path = Path(mount_point_path_str).resolve()
+            if not parent_path.exists():
+                logger.error(
+                    f"Invalid mount point:{mount_point_path_str} which is not exist"
+                )
+                return False
+
+            if not parent_path.is_dir():
+                logger.error(
+                    f"Invalid mount point:{mount_point_path_str} which is not dir"
+                )
+                return False
+        except Exception as e:
+            # invalidate path
+            logger.error(f"Invalid mount point:{mount_point_path_str}, {e}")
+            return False
+
+        try:
+            if "," in base_paths_str:
+                # multiple paths
+                paths = base_paths_str.split(",")
+                self.base_paths = [Path(p.strip()) for p in paths]
+            else:
+                # single path
+                self.base_paths = [Path(base_paths_str.strip())]
+        except Exception as e:
+            # invalidate path
+            logger.error(f"Invalid base_paths_str:{base_paths_str}, {e}")
+            return False
+
+        for path in self.base_paths:
+            try:
+                # convert relative path to absolute
+                resolved = path.resolve()
+                if not resolved.is_relative_to(parent_path):
+                    logger.error(
+                        f"Invalid path:{str(path)}, is not subdirectory of "
+                        f"mount point:{mount_point_path_str}"
+                    )
+                    return False
+            except Exception as e:
+                logger.error(f"Invalid path {str(path)}, {e}")
+                return False
+        return True
+
+    def _get_numa_node_count(self) -> int:
+        # Standard
+        import glob
+        import os
+        import subprocess
+
+        # method 1:  /sys/devices/system/node/
+        node_paths = glob.glob("/sys/devices/system/node/node[0-9]*")
+        count = len([p for p in node_paths if os.path.isdir(p)])
+        if count > 0:
+            return count
+
+        # method 2: numactl command
+        try:
+            result = subprocess.run(
+                ["numactl", "--hardware"], capture_output=True, text=True, timeout=5
+            )
+            for line in result.stdout.split("\n"):
+                if line.startswith("available:"):
+                    return int(line.split()[1])
+        except (
+            FileNotFoundError,
+            subprocess.TimeoutExpired,
+            subprocess.SubprocessError,
+        ):
+            pass
+
+        # method 3: psutil
+        try:
+            # Third Party
+            import psutil
+
+            if hasattr(psutil, "sensors_numa"):
+                numa_info = psutil.sensors_numa()
+                return max(len(numa_info), 1)
+        except ImportError:
+            pass
+        return 1
diff --git a/lmcache/v1/storage_backend/connector/hf3fs_connector.py b/lmcache/v1/storage_backend/connector/hf3fs_connector.py
new file mode 100644
index 0000000..0bb4a73
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/hf3fs_connector.py
@@ -0,0 +1,622 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Samsung Electronics Co., Ltd.All Rights Reserved
+# Authors:
+#   Wenwen Chen <wenwen.chen@samsung.com>
+#   Ruyi Zhang <ruyi.zhang@samsung.com>
+
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+from multiprocessing.shared_memory import SharedMemory
+from pathlib import Path
+from typing import Optional
+import asyncio
+import os
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.fs_connector import FSConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+HF3FS_AVAILABLE = True
+try:
+    # Third Party
+    from hf3fs_fuse.io import (
+        deregister_fd,
+        extract_mount_point,
+        make_ioring,
+        make_iovec,
+        register_fd,
+    )
+except ImportError:
+    HF3FS_AVAILABLE = False
+
+logger = init_logger(__name__)
+
+
+class HF3fsConnector(FSConnector):
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        mount_point: str,
+        iov_size: int,
+        ior_entries: int,
+        io_depth: int,
+        numa_id: int,
+        io_thread_num: int,
+        plugin_name: Optional[str] = None,
+        base_paths_str: Optional[str] = None,
+    ):
+        """
+        Args:
+            loop: Asyncio event loop
+            local_cpu_backend: Memory allocator interface
+            mount_point: Mount point of 3FS
+            iov_size: Shared memory size for Iov
+            ior_entries: Max num of concurrent requests that can be submitted in Ior
+            io_depth: Control with I/O depth in ior
+            numa_id:  NUMA ID for Ior shared memory
+            io_thread_num: Number of io thread
+            plugin_name: Plugin instance name
+                (e.g. "hf3fs", "hf3fs.primary")
+            base_paths_str: Comma-separated base paths
+                (legacy, passed from adapter when using hf3fs://URL)
+        """
+        if not HF3FS_AVAILABLE:
+            logger.error(
+                "hf3fs_fuse.io is not available. Please install the hf3fs_fuse package"
+            )
+            raise ImportError(
+                "hf3fs_fuse.io is not available. Please install the hf3fs_fuse package."
+            )
+        super().__init__(
+            loop,
+            local_cpu_backend,
+            local_cpu_backend.config,
+            plugin_name,
+            base_paths_str,
+        )
+
+        self.config = Hf3fsClientConfig(
+            mount_point=mount_point,
+            iov_size=iov_size,
+            ior_entries=ior_entries,
+            io_depth=io_depth,
+            numa_id=numa_id,
+        )
+
+        # check mount point
+        try:
+            hf3fs_mount_point = extract_mount_point(mount_point)
+        except Exception as e:
+            logger.error(f"Failed to extract 3FS mount point: {e}")
+            raise Exception(f"Failed to extract 3FS mount point: {e}") from e
+
+        if hf3fs_mount_point != mount_point:
+            logger.error(
+                f"Invalid 3FS mount point, config:{mount_point},"
+                f" extract:{hf3fs_mount_point}"
+            )
+            raise Exception(
+                f"Invalid 3FS mount point, config:{mount_point},"
+                f" extract:{hf3fs_mount_point}"
+            )
+
+        self.io_executor = ThreadPoolExecutor(
+            max_workers=io_thread_num, thread_name_prefix="HF3fsConnector_executor"
+        )
+        # create Hf3fsClient instance in main thread
+        self.client = Hf3fsClient.get_instance(self.config)
+
+    def get_client(self):
+        return Hf3fsClient.get_instance(self.config)
+
+    def _close(self):
+        if hasattr(self, "client") and self.client is not None:
+            try:
+                self.client.close()
+            except Exception as e:
+                logger.error(f"Failed to close HF3fsConnector,{e}")
+
+        if hasattr(self, "io_executor") and self.io_executor is not None:
+            try:
+                self.io_executor.shutdown(wait=True)
+            except Exception as e:
+                logger.error(f"Failed to close HF3fsConnector,{e}")
+
+    async def close(self):
+        await asyncio.to_thread(self._close)
+        logger.info("Finish close HF3fsConnector")
+
+    def __del__(self) -> None:
+        self._close()
+        logger.info("Finish delete HF3fsConnector")
+
+    def support_batched_get(self) -> bool:
+        return False
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return await self.loop.run_in_executor(self.io_executor, self.sync_get, key)
+
+    def sync_get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Get data from file system"""
+        file_path = self._get_file_path(key)
+        client = self.get_client()
+        memory_obj = None
+
+        try:
+            with Hf3fsFile(file_path, os.O_RDONLY, client) as f:
+                meta_len = None
+                data_len = None
+                if self.save_chunk_meta:
+                    # Read metadata buffer first to get shape, dtype, fmt
+                    # to be able to allocate memory object for the data and read into it
+                    md_buffer = bytearray(self.remote_metadata_bytes)
+                    md_view = memoryview(md_buffer)
+                    meta_len = f.read(md_view, len(md_view), 0)
+                    if meta_len != len(md_view):
+                        raise RuntimeError(
+                            f"Partial read meta {len(md_view)} got {meta_len}"
+                        )
+
+                    # Deserialize metadata and allocate memory
+                    metadata = RemoteMetadata.deserialize(md_buffer)
+                    memory_obj = self.local_cpu_backend.allocate(
+                        metadata.shapes, metadata.dtypes, metadata.fmt
+                    )
+                else:
+                    memory_obj = self.local_cpu_backend.allocate(
+                        self.meta_shapes, self.meta_dtypes, self.meta_fmt
+                    )
+                if memory_obj is None:
+                    logger.debug("Memory allocation failed during async disk load.")
+                    return None
+
+                # Read the actual data into allocated memory
+                data_buffer = memory_obj.byte_array
+                if isinstance(data_buffer, memoryview):
+                    data_view = memory_obj.byte_array
+                    if data_view.format == "<B":
+                        data_view = data_view.cast("B")
+                        logger.debug("convert memory_obj.byte_array format to B")
+                else:
+                    data_view = memoryview(data_buffer)
+                    logger.debug("convert memory_obj.byte_array to memoryview")
+
+                if self.save_chunk_meta:
+                    data_len = f.read(data_view, len(data_view), meta_len)
+                    if data_len != len(data_view):
+                        raise RuntimeError(
+                            f"Partial read data {len(data_view)} got {data_len}"
+                        )
+                else:
+                    # logger.info("get, before read", file_path)
+                    data_len = f.read(data_view, len(data_view), 0)
+
+                memory_obj = self.reshape_partial_chunk(memory_obj, data_len)
+            return memory_obj
+
+        except Exception as e:
+            if not isinstance(e, FileNotFoundError):
+                logger.error(f"Failed to read from file {file_path}: {str(e)}")
+            if memory_obj is not None:
+                memory_obj.ref_count_down()
+            return None
+
+    def support_batched_put(self) -> bool:
+        return False
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return False
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        return await self.loop.run_in_executor(
+            self.io_executor, self.sync_put, key, memory_obj
+        )
+
+    def sync_put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Store data to file system"""
+        final_path, temp_path = self._get_file_and_tmp_path(key)
+        client = self.get_client()
+
+        try:
+            # Prepare metadata
+            buffer = memoryview(memory_obj.byte_array)
+            metadata = (
+                RemoteMetadata(
+                    len(buffer),
+                    memory_obj.get_shapes(),
+                    memory_obj.get_dtypes(),
+                    memory_obj.get_memory_format(),
+                )
+                if self.save_chunk_meta
+                else None
+            )
+
+            size = len(buffer)
+            # Use standard sync I/O
+            # Write to file (metadata + data)
+            with Hf3fsFile(
+                temp_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, client
+            ) as f:
+                md_len = 0
+                if metadata is not None:
+                    md = metadata.serialize()
+                    md_len = len(md)
+                    # write metadata
+                    f.write(md, md_len, 0)
+
+                # write data
+                f.write(buffer.tobytes(), size, md_len)
+                # logger.info(f"num_write = {size}, key chunk_hash={key.chunk_hash}")
+
+                # Atomically rename temp file to final destination
+                Hf3fsFile.rename(temp_path, final_path)
+        except Exception as e:
+            logger.error(f"Failed to write file {final_path}: {str(e)}")
+            Hf3fsFile.remove(temp_path)  # Remove corrupted file
+            raise
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        file_path = self._get_file_path(key)
+        return Hf3fsFile.remove(file_path)
+
+    def support_batched_contains(self) -> bool:
+        return False
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """Check if key exists in file system"""
+        file_path = self._get_file_path(key)
+        return Hf3fsFile.exists(file_path)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Check if key exists in file system synchronized"""
+        file_path = self._get_file_path(key)
+        return Hf3fsFile.exists(file_path)
+
+
+class Hf3fsClientConfig:
+    def __init__(
+        self,
+        mount_point: str,
+        iov_size: int = 200 * (1 << 20),  # 200MB
+        ior_entries: int = 256,
+        io_depth: int = 0,
+        timeout: int = 200,
+        numa_id: int = -1,
+    ):
+        self.mount_point = mount_point
+        self.iov_size = iov_size
+        self.ior_entries = ior_entries
+        self.io_depth = io_depth
+        self.timeout = timeout
+        self.numa_id = numa_id
+
+
+class Hf3fsClient:
+    """Singleton mode, a instance per thread"""
+
+    _thread_local = threading.local()
+
+    @classmethod
+    def get_instance(cls, config: Hf3fsClientConfig):
+        """Initialize the HF3FS client"""
+
+        # check whether the instance exist
+        if not hasattr(cls._thread_local, "_instance"):
+            # init the instance
+            cls._thread_local._instance = cls(config)
+            logger.info(
+                f"Create {cls._thread_local._instance.client_name} instance success"
+            )
+        else:
+            logger.debug(
+                f"Hf3fsClient instance already exist in {threading.get_ident()}"
+            )
+        return cls._thread_local._instance
+
+    def __init__(self, config: Hf3fsClientConfig):
+        self.config = config
+        self.client_name = f"3FSClient_{os.getpid()}_{threading.get_ident()}"
+        self._closed = False  #
+        # shared memory
+        try:
+            self.shm_read = SharedMemory(
+                name=f"{self.client_name}_rd", size=self.config.iov_size, create=True
+            )
+            self.shm_write = SharedMemory(
+                name=f"{self.client_name}_wt", size=self.config.iov_size, create=True
+            )
+        except Exception as e:
+            logger.error(f"{self.client_name} failed to create share memory {e}")
+            self.close()
+            raise
+        logger.debug(f"{self.client_name} create share memory successfully")
+
+        try:
+            self.iov_read = make_iovec(
+                shm=self.shm_read,
+                hf3fs_mount_point=self.config.mount_point,
+                numa=self.config.numa_id,
+            )
+            self.iov_write = make_iovec(
+                shm=self.shm_write,
+                hf3fs_mount_point=self.config.mount_point,
+                numa=self.config.numa_id,
+            )
+        except Exception as e:
+            logger.error(f"{self.client_name} failed to create iov: {e}")
+            self.close()
+            raise
+        logger.debug(f"{self.client_name} create iov successfully")
+
+        # read I/O ring
+        try:
+            self.ior_read = make_ioring(
+                self.config.mount_point,
+                self.config.ior_entries,
+                for_read=True,
+                timeout=self.config.timeout,
+                numa=self.config.numa_id,
+            )
+        except Exception as e:
+            logger.error(f"{self.client_name} failed to create ior_read: {e}")
+            self.close()
+            raise
+        logger.debug(f"{self.client_name} create ior_read successfully")
+
+        # write I/O ring
+        try:
+            self.ior_write = make_ioring(
+                self.config.mount_point,
+                self.config.ior_entries,
+                for_read=False,
+                timeout=self.config.timeout,
+                numa=self.config.numa_id,
+            )
+        except Exception as e:
+            logger.error(f"{self.client_name} failed to create ior_write: {e}")
+            self.close()
+            raise
+
+        logger.debug(f"{self.client_name} create ior_write successfully")
+        # lock for read and write
+        self.lock_read = threading.RLock()
+        self.lock_write = threading.RLock()
+        logger.debug(f"{self.client_name} initialized end ")
+
+    def close(self):
+        if self._closed:
+            logger.debug(f"{self.client_name} already closed, skip")
+            return
+        logger.debug(f"{self.client_name} close begin")
+        try:
+            #  clear I/O resource first, then share memory
+            if hasattr(self, "ior_read") and self.ior_read is not None:
+                del self.ior_read
+                self.ior_read = None
+            if hasattr(self, "ior_write") and self.ior_write is not None:
+                del self.ior_write
+                self.ior_write = None
+            if hasattr(self, "iov_read") and self.iov_read is not None:
+                del self.iov_read
+                self.iov_read = None
+            if hasattr(self, "iov_write") and self.iov_write is not None:
+                del self.iov_write
+                self.iov_write = None
+
+            # clear share memory
+            if hasattr(self, "shm_read") and self.shm_read is not None:
+                try:
+                    self.shm_read.close()
+                    self.shm_read.unlink()
+                except FileNotFoundError:
+                    # already release, ignore it
+                    logger.debug(f"{self.client_name} shm_read already unlinked")
+                except Exception as e:
+                    logger.error(f"{self.client_name} error closing shm_read: {e}")
+                finally:
+                    self.shm_read = None
+            if hasattr(self, "shm_write") and self.shm_write is not None:
+                try:
+                    self.shm_write.close()
+                    self.shm_write.unlink()
+                except FileNotFoundError:
+                    # already release, ignore it
+                    logger.debug(f"{self.client_name} shm_write already unlinked")
+                except Exception as e:
+                    logger.error(f"{self.client_name} error closing shm_write: {e}")
+                finally:
+                    self.shm_write = None
+
+            self._closed = True
+            logger.info(f"{self.client_name} release successfully")
+        except Exception as e:
+            logger.error(f"{self.client_name} error during close: {e}")
+            self._closed = True  # Mark this flag even it exception
+
+    def __del__(self):
+        try:
+            logger.debug(f"{self.client_name} __del__ begin")
+            self.close()
+        except Exception as e:
+            # do not throw exception in __del__
+            logger.error(f"{self.client_name} error in __del__: {e}")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """auto close when exit"""
+        self.close()
+        return False  # False, exceptions are not suppressed
+
+    def _read(self, fd: int, buffer: memoryview, length: int, file_offset: int) -> int:
+        assert length <= self.config.iov_size
+        total_bytes_read = 0
+
+        # prepare
+        self.ior_read.prepare(self.iov_read[:length], True, fd, file_offset)
+        # submit
+        try:
+            done = self.ior_read.submit().wait(min_results=1)[0]
+        except Exception as e:
+            logger.error(f"{self.client_name} read submit failed: {e}")
+            raise RuntimeError(f"{self.client_name} read submit failed") from e
+
+        total_bytes_read = done.result
+
+        # read from shm
+        buffer[:total_bytes_read] = self.shm_read.buf[:total_bytes_read]
+        return total_bytes_read
+
+    def read(self, fd: int, buffer: memoryview, length: int, start: int = 0) -> int:
+        with self.lock_read:
+            offset = 0
+            total_bytes_read = 0
+            iov_size = self.config.iov_size
+
+            while offset < length:
+                sub_len = min(iov_size, length - offset)
+                bytes_read = self._read(
+                    fd, buffer[offset : offset + sub_len], sub_len, offset + start
+                )
+                if bytes_read > 0:
+                    total_bytes_read += bytes_read
+                    offset += bytes_read
+                if bytes_read != sub_len:
+                    break
+            if total_bytes_read != length:
+                logger.warning(
+                    f"{self.client_name} read: requested {length}, "
+                    f"got {total_bytes_read}"
+                )
+            return total_bytes_read
+
+    def _write(self, fd: int, buffer: memoryview, length: int, file_offset: int) -> int:
+        assert length <= self.config.iov_size
+        total_bytes_written = 0
+
+        # write shm
+        self.shm_write.buf[:length] = buffer[:length]
+
+        # prepare
+        self.ior_write.prepare(self.iov_write[:length], False, fd, file_offset)
+        # userdata= buffer)
+        # submit
+        try:
+            done = self.ior_write.submit().wait(min_results=1)[0]
+        except Exception as e:
+            logger.error(f"{self.client_name} write submit failed: {e}")
+            raise RuntimeError(f"{self.client_name} write submit failed") from e
+
+        total_bytes_written = done.result
+        return total_bytes_written
+
+    def write(self, fd: int, buffer: memoryview, length: int, start: int = 0) -> int:
+        with self.lock_write:
+            offset = 0
+            total_bytes_written = 0
+            iov_size = self.config.iov_size
+
+            while offset < length:
+                sub_len = min(iov_size, length - offset)
+                written = self._write(
+                    fd, buffer[offset : offset + sub_len], sub_len, offset + start
+                )
+                if written > 0:
+                    total_bytes_written += written
+                    offset += written
+                if written != sub_len:
+                    break
+            if total_bytes_written != length:
+                logger.error(
+                    f"{self.client_name} write: requested {length}, "
+                    f"got {total_bytes_written}"
+                )
+                raise RuntimeError(
+                    f"{self.client_name} write: requested {length}, "
+                    f"got {total_bytes_written}"
+                )
+
+            return total_bytes_written
+
+
+class Hf3fsFile:
+    def __init__(self, fname: Path, flags: int, client: Hf3fsClient):
+        self.fd = -1
+        self.fname = fname
+        self.flags = flags
+        self.client = client
+
+    def open(self):
+        try:
+            self.fd = os.open(self.fname, self.flags)
+            register_fd(self.fd)
+            logger.debug(f"Open file {self.fname} with flag {self.flags} successfully")
+        except Exception as e:
+            logger.error(f"Open file {self.fname} with flag {self.flags} failed {e}")
+            raise
+
+    def close(self):
+        if not hasattr(self, "fd") or self.fd == -1:
+            return
+        try:
+            deregister_fd(self.fd)
+            os.close(self.fd)
+            logger.debug(f"Close file ({self.fname}) successfully")
+        except Exception as e:
+            logger.error(f"Close file {self.fname} failed {e}")
+            raise
+        self.fd = -1
+        self.fname = ""
+
+    def __del__(self):
+        self.close()
+
+    def __enter__(self):
+        self.open()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        if exc_type:
+            logger.error(f"Hf3fsFile closed with exception: {exc_val}")
+        return False  # False, exceptions are not suppressed
+
+    @staticmethod
+    def exists(fname: Path) -> bool:
+        # check if file exists
+        return os.path.exists(fname)
+
+    @staticmethod
+    def remove(fname: Path) -> bool:
+        try:
+            os.remove(fname)
+            return True
+        except OSError as e:
+            logger.error(f"Failed to remove file {fname}: {e}")
+            return False
+
+    @staticmethod
+    def rename(old_fname: Path, new_fname: Path):
+        try:
+            os.rename(old_fname, new_fname)
+        except OSError as e:
+            logger.warning(f"rename {old_fname} to {new_fname} failed, {e}")
+            raise
+        return
+
+    def write(self, data: memoryview, length: int, file_offset: int = 0) -> int:
+        return self.client.write(self.fd, data, length, file_offset)
+
+    def read(self, buffer: memoryview, length: int, file_offset: int = 0) -> int:
+        return self.client.read(self.fd, buffer, length, file_offset)
+
+    def get_client_name(self) -> str:
+        return self.client.client_name
diff --git a/lmcache/v1/storage_backend/connector/hfbucket_adapter.py b/lmcache/v1/storage_backend/connector/hfbucket_adapter.py
new file mode 100644
index 0000000..1c384ea
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/hfbucket_adapter.py
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    extract_plugin_type,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.connector.hfbucket_connector import (
+    PLUGIN_TYPE,
+    HFBucketConnector,
+    resolve_hfbucket_connector_config,
+)
+
+logger = init_logger(__name__)
+
+
+class HFBucketConnectorAdapter(ConnectorAdapter):
+    """Adapter for Hugging Face Buckets remote storage."""
+
+    def __init__(self) -> None:
+        super().__init__("plugin://")
+
+    def can_parse(self, url: str) -> bool:
+        """Match plugin URLs for the built-in ``hfbucket`` connector type."""
+        if not url.startswith(self.schema):
+            return False
+        plugin_name = url[len(self.schema) :]
+        return extract_plugin_type(plugin_name) == PLUGIN_TYPE
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """Create a configured ``HFBucketConnector`` for the given context."""
+        if context.config is None:
+            raise ValueError("config is required for HFBucketConnector")
+        if context.metadata is None:
+            raise ValueError("metadata is required for HFBucketConnector")
+
+        plugin_name = context.plugin_name or PLUGIN_TYPE
+        connector_config = resolve_hfbucket_connector_config(
+            context.config,
+            plugin_name=plugin_name,
+        )
+
+        logger.info(
+            "Creating HFBucket connector for plugin %s and bucket %s",
+            plugin_name,
+            connector_config.bucket_location.bucket_id,
+        )
+        return HFBucketConnector(
+            local_cpu_backend=context.local_cpu_backend,
+            config=context.config,
+            metadata=context.metadata,
+            connector_config=connector_config,
+        )
diff --git a/lmcache/v1/storage_backend/connector/hfbucket_connector.py b/lmcache/v1/storage_backend/connector/hfbucket_connector.py
new file mode 100644
index 0000000..b04c916
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/hfbucket_connector.py
@@ -0,0 +1,965 @@
+# SPDX-License-Identifier: Apache-2.0
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Sequence
+from copy import copy
+from dataclasses import dataclass
+from pathlib import Path
+from threading import Lock
+from typing import Protocol
+from urllib.parse import quote, unquote
+import asyncio
+import builtins
+import os
+import shutil
+import tempfile
+import time
+
+# Third Party
+from huggingface_hub import HfApi
+from packaging.version import InvalidVersion, Version
+import huggingface_hub
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+PLUGIN_TYPE = "hfbucket"
+_HFBUCKET_HANDLE_PREFIX = "hf://buckets/"
+_MIN_HUGGINGFACE_HUB_VERSION = Version("1.5.0")
+_DEFAULT_DOWNLOAD_TMP_DIR = Path(tempfile.gettempdir()) / "lmcache-hfbucket"
+_METADATA_CACHE_PRUNE_INTERVAL = 128
+
+
+@dataclass(frozen=True)
+class HFBucketLocation:
+    """Parsed Hugging Face bucket location.
+
+    Args:
+        bucket_id: Hugging Face bucket identifier in ``namespace/bucket`` format.
+        object_prefix: Optional object prefix inside the bucket.
+    """
+
+    bucket_id: str
+    object_prefix: str
+
+
+@dataclass(frozen=True)
+class HFBucketConnectorConfig:
+    """Resolved HFBucket connector configuration.
+
+    Args:
+        plugin_name: Full LMCache plugin name, including any instance suffix.
+        bucket_location: Parsed bucket handle and prefix information.
+        token_env: Environment variable name used to resolve the access token.
+        token: Optional direct token override used when ``token_env`` is unset.
+        create_bucket_if_missing: Whether writes should lazily create the bucket.
+        download_tmp_dir: Root directory for per-connector temporary downloads.
+        metadata_cache_ttl_secs: TTL for cached object sizes and misses.
+    """
+
+    plugin_name: str
+    bucket_location: HFBucketLocation
+    token_env: str
+    token: str | None
+    create_bucket_if_missing: bool
+    download_tmp_dir: Path
+    metadata_cache_ttl_secs: float
+
+
+@dataclass(frozen=True)
+class _CachedObjectMetadata:
+    """Cached object size entry with expiration metadata."""
+
+    size_bytes: int
+    expires_at: float
+
+
+class HFBucketClientInterface(Protocol):
+    """Protocol for synchronous Hugging Face bucket clients used by the connector."""
+
+    def create_bucket(self, bucket_id: str) -> None:
+        """Create a bucket if needed."""
+
+    def bucket_info(self, bucket_id: str) -> object:
+        """Fetch lightweight bucket metadata."""
+
+    def get_paths_info(self, bucket_id: str, paths: Sequence[str]) -> list[object]:
+        """Fetch exact metadata for bucket paths."""
+
+    def list_tree(self, bucket_id: str, prefix: str) -> list[object]:
+        """List bucket entries under the provided prefix."""
+
+    def upload_files(
+        self,
+        bucket_id: str,
+        add: Sequence[tuple[bytes, str]],
+    ) -> None:
+        """Upload files to a bucket in one batch call."""
+
+    def download_files(
+        self,
+        bucket_id: str,
+        files: Sequence[tuple[str, str]],
+    ) -> None:
+        """Download files from a bucket to local paths."""
+
+    def delete_files(
+        self,
+        bucket_id: str,
+        delete: Sequence[str],
+    ) -> None:
+        """Delete files from a bucket in one batch call."""
+
+
+class HFBucketClient(HFBucketClientInterface):
+    """Thin synchronous wrapper around ``huggingface_hub`` bucket APIs."""
+
+    def __init__(self, token: str | None) -> None:
+        _validate_huggingface_hub_support()
+        self._api = HfApi(token=token)
+
+    def create_bucket(self, bucket_id: str) -> None:
+        """Create the bucket if it does not already exist."""
+        self._api.create_bucket(bucket_id, exist_ok=True)
+
+    def bucket_info(self, bucket_id: str) -> object:
+        """Return bucket metadata for auth and health checks."""
+        return self._api.bucket_info(bucket_id)
+
+    def get_paths_info(self, bucket_id: str, paths: Sequence[str]) -> list[object]:
+        """Return exact metadata entries for the requested paths."""
+        if not paths:
+            return []
+        return list(self._api.get_bucket_paths_info(bucket_id, list(paths)))
+
+    def list_tree(self, bucket_id: str, prefix: str) -> list[object]:
+        """Return recursive bucket tree entries under ``prefix``."""
+        return list(
+            self._api.list_bucket_tree(bucket_id, recursive=True, prefix=prefix)
+        )
+
+    def upload_files(
+        self,
+        bucket_id: str,
+        add: Sequence[tuple[bytes, str]],
+    ) -> None:
+        """Upload files in a single batch operation."""
+        self._api.batch_bucket_files(bucket_id, add=list(add))
+
+    def download_files(
+        self,
+        bucket_id: str,
+        files: Sequence[tuple[str, str]],
+    ) -> None:
+        """Download files in a single batch operation."""
+        self._api.download_bucket_files(bucket_id, files=list(files))
+
+    def delete_files(
+        self,
+        bucket_id: str,
+        delete: Sequence[str],
+    ) -> None:
+        """Delete files in a single batch operation."""
+        self._api.batch_bucket_files(bucket_id, delete=list(delete))
+
+
+class HFBucketConnector(RemoteConnector):
+    """LMCache remote connector backed by Hugging Face Buckets."""
+
+    def __init__(
+        self,
+        local_cpu_backend: LocalCPUBackend,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        connector_config: HFBucketConnectorConfig,
+        bucket_client: HFBucketClientInterface | None = None,
+    ) -> None:
+        """Initialize the HFBucket connector.
+
+        Args:
+            local_cpu_backend: Local CPU backend used to allocate
+                ``MemoryObj`` instances for downloaded chunks.
+            config: LMCache engine config. ``save_unfull_chunk`` must be
+                ``False``; an omitted ``save_chunk_meta`` is treated as
+                ``False`` by this connector.
+            metadata: LMCache engine metadata used to derive the expected
+                full-chunk layout.
+            connector_config: Resolved plugin-scoped configuration, including
+                the bucket handle, token source, and metadata cache TTL.
+            bucket_client: Optional test seam. When ``None`` (the default), a
+                real ``HFBucketClient`` is constructed from the resolved
+                token.
+
+        Raises:
+            ValueError: If ``save_chunk_meta`` is ``True`` or
+                ``save_unfull_chunk`` is ``True``. This backend only supports
+                full chunks without inline chunk metadata.
+        """
+        normalized_config = _normalize_save_chunk_meta_config(config)
+        super().__init__(normalized_config, metadata)
+
+        if self.save_chunk_meta:
+            raise ValueError("save_chunk_meta must be False for hfbucket")
+        if config.save_unfull_chunk:
+            raise ValueError("save_unfull_chunk must be False for hfbucket")
+
+        self.local_cpu_backend = local_cpu_backend
+        self.plugin_name = connector_config.plugin_name
+        self.bucket_id = connector_config.bucket_location.bucket_id
+        self.object_prefix = connector_config.bucket_location.object_prefix
+        self.create_bucket_if_missing = connector_config.create_bucket_if_missing
+        self.metadata_cache_ttl_secs = connector_config.metadata_cache_ttl_secs
+
+        if bucket_client is None:
+            resolved_token = _resolve_hf_token(
+                connector_config.token_env,
+                connector_config.token,
+            )
+            self._bucket_client: HFBucketClientInterface = HFBucketClient(
+                token=resolved_token
+            )
+        else:
+            self._bucket_client = bucket_client
+
+        self._metadata_cache: dict[str, _CachedObjectMetadata] = {}
+        self._metadata_cache_lock = Lock()
+        self._metadata_cache_updates = 0
+
+        self._bucket_create_lock = Lock()
+        self._bucket_create_checked = False
+
+        self._download_tmp_root = connector_config.download_tmp_dir.expanduser()
+        self._download_tmp_root.mkdir(parents=True, exist_ok=True)
+        self._download_session_dir = Path(
+            tempfile.mkdtemp(
+                prefix=f"{PLUGIN_TYPE}-{self.plugin_name.replace('.', '-')}-",
+                dir=self._download_tmp_root,
+            )
+        )
+
+        logger.info(
+            "Initialized HFBucketConnector for bucket %s with prefix '%s'",
+            self.bucket_id,
+            self.object_prefix,
+        )
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """Return whether a full LMCache chunk exists for ``key``."""
+        return await asyncio.to_thread(self.exists_sync, key)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Synchronously return whether a full LMCache chunk exists for ``key``."""
+        object_size = self._get_object_size_bytes(key.to_string())
+        return object_size == self.full_chunk_size_bytes
+
+    async def get(self, key: CacheEngineKey) -> MemoryObj | None:
+        """Retrieve the full chunk associated with ``key``."""
+        memory_objs = await self.batched_get([key])
+        return memory_objs[0]
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        """Store a full chunk in Hugging Face Buckets."""
+        await self.batched_put([key], [memory_obj])
+
+    async def list(self) -> builtins.list[str]:
+        """List LMCache keys currently stored under this connector prefix."""
+        return await asyncio.to_thread(self._list_sync)
+
+    async def close(self) -> None:
+        """Release connector-local resources and remove temporary downloads."""
+        with self._metadata_cache_lock:
+            self._metadata_cache.clear()
+        await asyncio.to_thread(
+            shutil.rmtree,
+            self._download_session_dir,
+            True,
+        )
+
+    def support_ping(self) -> bool:
+        """Report support for lightweight connectivity checks."""
+        return True
+
+    async def ping(self) -> int:
+        """Check basic access to the configured bucket."""
+        return await asyncio.to_thread(self._ping_sync)
+
+    def support_batched_put(self) -> bool:
+        """Report support for batch uploads."""
+        return True
+
+    async def batched_put(
+        self,
+        keys: builtins.list[CacheEngineKey],
+        memory_objs: builtins.list[MemoryObj],
+    ) -> None:
+        """Upload multiple full chunks in a single Hugging Face batch call."""
+        if len(keys) != len(memory_objs):
+            raise ValueError(
+                "keys and memory_objs must have the same length for batched_put"
+            )
+
+        await asyncio.to_thread(self._batched_put_sync, keys, memory_objs)
+
+    def support_batched_get(self) -> bool:
+        """Report support for batch downloads."""
+        return True
+
+    async def batched_get(
+        self,
+        keys: builtins.list[CacheEngineKey],
+    ) -> builtins.list[MemoryObj | None]:
+        """Download multiple chunks while preserving input order."""
+        if not keys:
+            return []
+
+        key_strings = [key.to_string() for key in keys]
+        object_sizes = await asyncio.to_thread(self._resolve_object_sizes, key_strings)
+
+        downloads: builtins.list[tuple[int, str]] = []
+        results: builtins.list[MemoryObj | None] = [None] * len(keys)
+
+        for index, (key_str, object_size) in enumerate(
+            zip(key_strings, object_sizes, strict=False)
+        ):
+            if object_size == 0:
+                continue
+
+            if object_size != self.full_chunk_size_bytes:
+                logger.error(
+                    "Size mismatch for %s: bucket has %d bytes, expected %d bytes. "
+                    "Rejecting the load because hfbucket only supports full chunks.",
+                    key_str,
+                    object_size,
+                    self.full_chunk_size_bytes,
+                )
+                continue
+
+            downloads.append((index, self._key_string_to_object_path(key_str)))
+
+        downloaded_data = await asyncio.to_thread(self._download_objects, downloads)
+
+        try:
+            for index, data in downloaded_data.items():
+                if data is None:
+                    continue
+
+                if len(data) != self.full_chunk_size_bytes:
+                    key_str = key_strings[index]
+                    logger.error(
+                        "Downloaded object for %s has %d bytes, expected %d bytes. "
+                        "Rejecting the load because hfbucket only supports full "
+                        "chunks.",
+                        key_str,
+                        len(data),
+                        self.full_chunk_size_bytes,
+                    )
+                    self._set_cached_object_size(key_str, len(data))
+                    continue
+
+                memory_obj = self.local_cpu_backend.allocate(
+                    self.meta_shapes,
+                    self.meta_dtypes,
+                    self.meta_fmt,
+                )
+                if memory_obj is None:
+                    logger.debug(
+                        "Memory allocation failed while downloading from hfbucket."
+                    )
+                    continue
+
+                try:
+                    buffer = memory_obj.byte_array.cast("B")
+                    if len(buffer) < len(data):
+                        raise RuntimeError(
+                            "Allocated buffer is smaller than downloaded "
+                            "hfbucket object"
+                        )
+                    buffer[: len(data)] = data
+                    results[index] = memory_obj
+                except Exception:
+                    memory_obj.ref_count_down()
+                    raise
+        except Exception:
+            for existing in results:
+                if existing is not None:
+                    existing.ref_count_down()
+            raise
+
+        return results
+
+    def support_batched_contains(self) -> bool:
+        """Report support for synchronous prefix contains checks."""
+        return True
+
+    def batched_contains(self, keys: builtins.list[CacheEngineKey]) -> int:
+        """Return the number of consecutive prefix keys that exist as full chunks."""
+        key_strings = [key.to_string() for key in keys]
+        object_sizes = self._resolve_object_sizes(key_strings)
+        hit_count = 0
+        for object_size in object_sizes:
+            if object_size != self.full_chunk_size_bytes:
+                return hit_count
+            hit_count += 1
+        return hit_count
+
+    def support_batched_async_contains(self) -> bool:
+        """Report support for async prefix contains checks."""
+        return True
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: builtins.list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Asynchronously return the number of consecutive prefix hits."""
+        del lookup_id
+        del pin
+        return await asyncio.to_thread(self.batched_contains, keys)
+
+    def support_batched_get_non_blocking(self) -> bool:
+        """Report support for non-blocking batch loads."""
+        return True
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: builtins.list[CacheEngineKey],
+    ) -> builtins.list[MemoryObj]:
+        """Return the successful prefix of ``batched_get`` results."""
+        del lookup_id
+        results = await self.batched_get(keys)
+        prefix_results: builtins.list[MemoryObj] = []
+        found_failure = False
+        for result in results:
+            if found_failure:
+                if result is not None:
+                    result.ref_count_down()
+                continue
+
+            if result is None:
+                found_failure = True
+                continue
+
+            prefix_results.append(result)
+        return prefix_results
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        """Synchronously remove a bucket object for ``key``."""
+        key_str = key.to_string()
+        object_path = self._key_string_to_object_path(key_str)
+        try:
+            self._bucket_client.delete_files(self.bucket_id, [object_path])
+        except Exception as exc:
+            if _is_not_found_error(exc):
+                self._set_cached_object_size(key_str, 0)
+                return True
+            logger.error("Failed to delete %s from hfbucket: %s", key_str, exc)
+            return False
+
+        self._set_cached_object_size(key_str, 0)
+        return True
+
+    def __repr__(self) -> str:
+        return (
+            f"<HFBucketConnector bucket_id={self.bucket_id} "
+            f"prefix={self.object_prefix!r}>"
+        )
+
+    def _ping_sync(self) -> int:
+        """Perform the synchronous bucket health check used by ``ping``."""
+        try:
+            self._bucket_client.bucket_info(self.bucket_id)
+            return 0
+        except Exception as exc:
+            logger.warning("Failed to ping hfbucket %s: %s", self.bucket_id, exc)
+            return 1
+
+    def _batched_put_sync(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: Sequence[MemoryObj],
+    ) -> None:
+        """Upload all provided chunks using a single batch request."""
+        self._ensure_bucket_for_writes()
+
+        additions: builtins.list[tuple[bytes, str]] = []
+        key_strings: builtins.list[str] = []
+        for key, memory_obj in zip(keys, memory_objs, strict=True):
+            key_str = key.to_string()
+            self._validate_full_chunk_for_upload(key_str, memory_obj)
+            additions.append(
+                (
+                    bytes(memory_obj.byte_array),
+                    self._key_string_to_object_path(key_str),
+                )
+            )
+            key_strings.append(key_str)
+
+        try:
+            self._bucket_client.upload_files(self.bucket_id, additions)
+        except Exception:
+            refreshed_sizes = self._fetch_object_sizes_sync(key_strings)
+            for refreshed_key, refreshed_size in refreshed_sizes.items():
+                self._set_cached_object_size(refreshed_key, refreshed_size)
+            raise
+
+        for key_str in key_strings:
+            self._set_cached_object_size(key_str, self.full_chunk_size_bytes)
+
+    def _ensure_bucket_for_writes(self) -> None:
+        """Create the bucket on demand when configured to do so."""
+        if not self.create_bucket_if_missing or self._bucket_create_checked:
+            return
+
+        with self._bucket_create_lock:
+            if self._bucket_create_checked:
+                return
+            self._bucket_client.create_bucket(self.bucket_id)
+            self._bucket_create_checked = True
+
+    def _validate_full_chunk_for_upload(
+        self,
+        key_str: str,
+        memory_obj: MemoryObj,
+    ) -> None:
+        """Reject partial or metadata-bearing uploads for the conservative MVP."""
+        physical_size = memory_obj.get_physical_size()
+        if physical_size != self.full_chunk_size_bytes:
+            raise ValueError(
+                f"Cannot upload {key_str}: chunk size {physical_size} bytes does not "
+                f"match expected full chunk size {self.full_chunk_size_bytes} bytes. "
+                "Partial/unfull chunks are not supported by hfbucket."
+            )
+
+    def _list_sync(self) -> builtins.list[str]:
+        """Return LMCache key strings discovered under the configured prefix."""
+        try:
+            entries = self._bucket_client.list_tree(self.bucket_id, self.object_prefix)
+        except Exception as exc:
+            if _is_not_found_error(exc):
+                return []
+            raise
+
+        keys: builtins.list[str] = []
+        for entry in entries:
+            if _get_object_type(entry) != "file":
+                continue
+
+            object_path = _get_object_path(entry)
+            relative_path = self._relative_object_path(object_path)
+            if relative_path is None or "/" in relative_path:
+                continue
+
+            key_str = decode_hfbucket_object_name(relative_path)
+            keys.append(key_str)
+            self._set_cached_object_size(key_str, _get_object_size(entry))
+
+        return keys
+
+    def _download_objects(
+        self,
+        downloads: Sequence[tuple[int, str]],
+    ) -> dict[int, bytes | None]:
+        """Download requested object paths and return their bytes by result index."""
+        if not downloads:
+            return {}
+
+        batch_dir = Path(
+            tempfile.mkdtemp(prefix="download-", dir=self._download_session_dir)
+        )
+        local_mappings: builtins.list[tuple[int, Path]] = []
+        files: builtins.list[tuple[str, str]] = []
+        for index, object_path in downloads:
+            local_path = batch_dir / f"{index}.bin"
+            local_mappings.append((index, local_path))
+            files.append((object_path, str(local_path)))
+
+        try:
+            try:
+                self._bucket_client.download_files(self.bucket_id, files)
+            except Exception as exc:
+                if not _is_not_found_error(exc):
+                    logger.warning("Batch download from hfbucket raised: %s", exc)
+
+            results: dict[int, bytes | None] = {}
+            for index, local_path in local_mappings:
+                if not local_path.exists():
+                    results[index] = None
+                    continue
+
+                with open(local_path, "rb") as file_handle:
+                    results[index] = file_handle.read()
+            return results
+        finally:
+            shutil.rmtree(batch_dir, ignore_errors=True)
+
+    def _get_object_size_bytes(self, key_str: str) -> int:
+        """Return the cached or fetched size for a specific LMCache key string."""
+        cached_size = self._get_cached_object_size(key_str)
+        if cached_size is not None:
+            return cached_size
+
+        object_sizes = self._fetch_object_sizes_sync([key_str])
+        object_size = object_sizes.get(key_str, 0)
+        self._set_cached_object_size(key_str, object_size)
+        return object_size
+
+    def _resolve_object_sizes(self, key_strings: Sequence[str]) -> builtins.list[int]:
+        """Resolve cached and uncached object sizes while preserving order."""
+        cached_results: dict[str, int] = {}
+        unresolved: builtins.list[str] = []
+
+        for key_str in key_strings:
+            cached_size = self._get_cached_object_size(key_str)
+            if cached_size is None:
+                unresolved.append(key_str)
+            else:
+                cached_results[key_str] = cached_size
+
+        if unresolved:
+            fetched_sizes = self._fetch_object_sizes_sync(unresolved)
+            for key_str, size in fetched_sizes.items():
+                self._set_cached_object_size(key_str, size)
+            cached_results.update(fetched_sizes)
+
+        return [cached_results.get(key_str, 0) for key_str in key_strings]
+
+    def _fetch_object_sizes_sync(
+        self,
+        key_strings: Sequence[str],
+    ) -> dict[str, int]:
+        """Fetch exact object sizes for ``key_strings`` in one metadata request."""
+        if not key_strings:
+            return {}
+
+        object_paths = [
+            self._key_string_to_object_path(key_str) for key_str in key_strings
+        ]
+        try:
+            path_infos = self._bucket_client.get_paths_info(
+                self.bucket_id, object_paths
+            )
+        except Exception as exc:
+            if _is_not_found_error(exc):
+                return {key_str: 0 for key_str in key_strings}
+            raise
+
+        # Match by path, not by request order: the HF API does not document
+        # any ordering guarantee, and assuming positional correspondence can
+        # silently cache zero sizes (= "missing") for existing objects when
+        # the server reorders the response.
+        size_by_path: dict[str, int] = {}
+        for path_info in path_infos:
+            path = _get_object_path(path_info)
+            if path:
+                size_by_path[path] = _extract_exact_object_size(
+                    path_info,
+                    expected_path=path,
+                )
+
+        return {
+            key_str: size_by_path.get(object_path, 0)
+            for key_str, object_path in zip(key_strings, object_paths, strict=False)
+        }
+
+    def _get_cached_object_size(self, key_str: str) -> int | None:
+        """Return a live cache entry, pruning expired metadata opportunistically."""
+        now = time.monotonic()
+        with self._metadata_cache_lock:
+            cache_entry = self._metadata_cache.get(key_str)
+            if cache_entry is None:
+                return None
+            if cache_entry.expires_at <= now:
+                self._metadata_cache.pop(key_str, None)
+                return None
+            return cache_entry.size_bytes
+
+    def _set_cached_object_size(self, key_str: str, object_size: int) -> None:
+        """Store an object size in the TTL cache."""
+        expires_at = time.monotonic() + self.metadata_cache_ttl_secs
+        with self._metadata_cache_lock:
+            self._metadata_cache[key_str] = _CachedObjectMetadata(
+                size_bytes=object_size,
+                expires_at=expires_at,
+            )
+            self._metadata_cache_updates += 1
+            if self._metadata_cache_updates % _METADATA_CACHE_PRUNE_INTERVAL == 0:
+                self._prune_expired_cache_entries_locked(time.monotonic())
+
+    def _prune_expired_cache_entries_locked(self, now: float) -> None:
+        """Remove expired cache entries while holding ``_metadata_cache_lock``."""
+        expired_keys: builtins.list[str] = [
+            key_str
+            for key_str, cache_entry in self._metadata_cache.items()
+            if cache_entry.expires_at <= now
+        ]
+        for key_str in expired_keys:
+            self._metadata_cache.pop(key_str, None)
+
+    def _key_string_to_object_path(self, key_str: str) -> str:
+        """Return the bucket object path for a serialized LMCache key."""
+        encoded_key = encode_hfbucket_object_name(key_str)
+        if self.object_prefix:
+            return f"{self.object_prefix}/{encoded_key}"
+        return encoded_key
+
+    def _relative_object_path(self, object_path: str) -> str | None:
+        """Return the path relative to the configured LMCache prefix."""
+        normalized_path = object_path.strip("/")
+        if not self.object_prefix:
+            return normalized_path
+
+        prefix_with_separator = f"{self.object_prefix}/"
+        if not normalized_path.startswith(prefix_with_separator):
+            return None
+        return normalized_path[len(prefix_with_separator) :]
+
+
+def parse_hfbucket_handle(bucket_handle: str) -> HFBucketLocation:
+    """Parse a Hugging Face bucket handle into bucket id and prefix.
+
+    Args:
+        bucket_handle: Handle in ``hf://buckets/<namespace>/<bucket>/<prefix>`` form.
+
+    Returns:
+        Parsed bucket location containing the ``namespace/bucket`` bucket id and the
+        optional LMCache object prefix.
+
+    Raises:
+        ValueError: If the handle is not a valid Hugging Face bucket handle.
+    """
+    normalized_handle = bucket_handle.strip()
+    if not normalized_handle.startswith(_HFBUCKET_HANDLE_PREFIX):
+        raise ValueError(
+            "bucket_handle must start with 'hf://buckets/' for the hfbucket plugin"
+        )
+
+    path = normalized_handle[len(_HFBUCKET_HANDLE_PREFIX) :].strip("/")
+    path_parts = [part for part in path.split("/") if part]
+    if len(path_parts) < 2:
+        raise ValueError(
+            "bucket_handle must be in the form "
+            "'hf://buckets/<namespace>/<bucket>[/<prefix>]'"
+        )
+
+    bucket_id = f"{path_parts[0]}/{path_parts[1]}"
+    object_prefix = "/".join(path_parts[2:])
+    return HFBucketLocation(
+        bucket_id=bucket_id,
+        object_prefix=object_prefix,
+    )
+
+
+def resolve_hfbucket_connector_config(
+    config: LMCacheEngineConfig,
+    plugin_name: str,
+) -> HFBucketConnectorConfig:
+    """Resolve plugin-scoped configuration for the HFBucket connector.
+
+    Args:
+        config: LMCache engine config used to resolve ``extra_config`` values.
+        plugin_name: Full plugin name, such as ``hfbucket`` or ``hfbucket.prod``.
+
+    Returns:
+        Parsed connector configuration for the requested plugin instance.
+
+    Raises:
+        ValueError: If required configuration keys are missing or malformed.
+    """
+    extra_config = config.extra_config or {}
+    config_prefix = f"remote_storage_plugin.{plugin_name}"
+
+    bucket_handle_obj = extra_config.get(f"{config_prefix}.bucket_handle")
+    if not isinstance(bucket_handle_obj, str) or not bucket_handle_obj:
+        raise ValueError(
+            f"HFBucket connector '{plugin_name}' requires "
+            f"'{config_prefix}.bucket_handle'"
+        )
+
+    token_env_obj = extra_config.get(f"{config_prefix}.token_env", "HF_TOKEN")
+    token_env = token_env_obj if isinstance(token_env_obj, str) else "HF_TOKEN"
+
+    token_obj = extra_config.get(f"{config_prefix}.token")
+    token = token_obj if isinstance(token_obj, str) and token_obj else None
+
+    create_bucket_if_missing = _coerce_bool(
+        extra_config.get(f"{config_prefix}.create_bucket_if_missing", False)
+    )
+    download_tmp_dir_value = extra_config.get(
+        f"{config_prefix}.download_tmp_dir",
+        str(_DEFAULT_DOWNLOAD_TMP_DIR),
+    )
+    download_tmp_dir = Path(
+        download_tmp_dir_value
+        if isinstance(download_tmp_dir_value, str)
+        else str(_DEFAULT_DOWNLOAD_TMP_DIR)
+    )
+    metadata_cache_ttl_secs = _coerce_float(
+        extra_config.get(f"{config_prefix}.metadata_cache_ttl_secs", 30.0)
+    )
+
+    return HFBucketConnectorConfig(
+        plugin_name=plugin_name,
+        bucket_location=parse_hfbucket_handle(bucket_handle_obj),
+        token_env=token_env,
+        token=token,
+        create_bucket_if_missing=create_bucket_if_missing,
+        download_tmp_dir=download_tmp_dir,
+        metadata_cache_ttl_secs=metadata_cache_ttl_secs,
+    )
+
+
+def encode_hfbucket_object_name(key_str: str) -> str:
+    """Encode a serialized LMCache key into a reversible bucket object name."""
+    return quote(key_str, safe="")
+
+
+def decode_hfbucket_object_name(object_name: str) -> str:
+    """Decode a reversible bucket object name back into an LMCache key string."""
+    return unquote(object_name)
+
+
+def _normalize_save_chunk_meta_config(
+    config: LMCacheEngineConfig,
+) -> LMCacheEngineConfig:
+    """Clone config and default ``save_chunk_meta`` to ``False`` for hfbucket.
+
+    The generic ``RemoteConnector`` base defaults ``save_chunk_meta`` to ``True``
+    when the key is absent. The hfbucket connector is intentionally a full-chunk-only
+    backend and treats an omitted key as ``False`` so users can configure it with only
+    plugin-scoped fields.
+    """
+    if config.extra_config is not None and "save_chunk_meta" in config.extra_config:
+        return config
+
+    normalized_config = copy(config)
+    normalized_extra_config = (
+        dict(config.extra_config) if config.extra_config is not None else {}
+    )
+    normalized_extra_config["save_chunk_meta"] = False
+    normalized_config.extra_config = normalized_extra_config
+    return normalized_config
+
+
+def _resolve_hf_token(token_env: str, token: str | None) -> str | None:
+    """Resolve the Hugging Face access token from env-first configuration."""
+    env_token = os.environ.get(token_env, "") if token_env else ""
+    if env_token:
+        return env_token
+    return token
+
+
+def _validate_huggingface_hub_support() -> None:
+    """Raise a clear error when the installed ``huggingface_hub`` is too old.
+
+    Assumes ``huggingface_hub`` is importable (guaranteed by the declared
+    dependency). Validates that the version is recent enough to expose the
+    Buckets APIs used by this connector.
+    """
+    version_value = getattr(huggingface_hub, "__version__", None)
+    if isinstance(version_value, str):
+        try:
+            version = Version(version_value)
+        except InvalidVersion:
+            pass
+        else:
+            if version < _MIN_HUGGINGFACE_HUB_VERSION:
+                raise _build_huggingface_hub_error(
+                    "huggingface_hub version is too old for Buckets support; "
+                    "install huggingface_hub>=1.5.0"
+                )
+
+    required_methods = (
+        "batch_bucket_files",
+        "download_bucket_files",
+        "list_bucket_tree",
+        "bucket_info",
+        "create_bucket",
+        "get_bucket_paths_info",
+    )
+    missing = [name for name in required_methods if not hasattr(HfApi, name)]
+    if missing:
+        raise _build_huggingface_hub_error(
+            "huggingface_hub does not expose required Buckets APIs: "
+            + ", ".join(missing)
+        )
+
+
+def _build_huggingface_hub_error(message: str) -> RuntimeError:
+    """Create a consistent runtime error for unsupported ``huggingface_hub``."""
+    return RuntimeError(
+        f"{message}. LMCache HFBucket support requires huggingface_hub>=1.5.0."
+    )
+
+
+def _extract_exact_object_size(path_info: object, expected_path: str) -> int:
+    """Extract a file size from an exact path info object."""
+    if _get_object_type(path_info) != "file":
+        return 0
+
+    object_path = _get_object_path(path_info)
+    if object_path and object_path != expected_path:
+        return 0
+
+    return _get_object_size(path_info)
+
+
+def _get_object_path(path_info: object) -> str:
+    """Safely read the ``path`` attribute from a Hugging Face path object."""
+    path = getattr(path_info, "path", "")
+    return path if isinstance(path, str) else ""
+
+
+def _get_object_type(path_info: object) -> str:
+    """Safely read the ``type`` attribute from a Hugging Face path object."""
+    obj_type = getattr(path_info, "type", "")
+    return obj_type if isinstance(obj_type, str) else ""
+
+
+def _get_object_size(path_info: object) -> int:
+    """Safely read the ``size`` attribute from a Hugging Face path object."""
+    size_obj = getattr(path_info, "size", 0)
+    return size_obj if isinstance(size_obj, int) else 0
+
+
+def _is_not_found_error(exc: Exception) -> bool:
+    """Return whether the exception represents a missing bucket or object."""
+    response = getattr(exc, "response", None)
+    status_code = getattr(response, "status_code", None)
+    if isinstance(status_code, int):
+        return status_code == 404
+
+    direct_status_code = getattr(exc, "status_code", None)
+    if isinstance(direct_status_code, int):
+        return direct_status_code == 404
+
+    return "404" in str(exc)
+
+
+def _coerce_bool(value: object) -> bool:
+    """Coerce config values that may arrive as bools or strings."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def _coerce_float(value: object) -> float:
+    """Coerce config values that may arrive as numeric strings."""
+    if isinstance(value, (float, int)):
+        return float(value)
+    if isinstance(value, str):
+        return float(value)
+    raise ValueError(f"Expected float-compatible value, got {type(value).__name__}")
diff --git a/lmcache/v1/storage_backend/connector/infinistore_adapter.py b/lmcache/v1/storage_backend/connector/infinistore_adapter.py
new file mode 100644
index 0000000..0f64c53
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/infinistore_adapter.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class InfinistoreConnectorAdapter(ConnectorAdapter):
+    """Adapter for Infinistore connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("infinistore://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Third Party
+        import infinistore
+
+        # Local
+        from .infinistore_connector import InfinistoreConnector
+
+        logger.info(f"Creating Infinistore connector for URL: {context.url}")
+        hosts = context.url.split(",")
+        if len(hosts) > 1:
+            raise ValueError(
+                f"Only one host is supported for infinistore, but got {hosts}"
+            )
+
+        parse_url = parse_remote_url(context.url)
+        device_name = parse_url.query_params.get("device", ["mlx5_0"])[0]
+
+        link_type_str = "LINK_ETHERNET"
+        if context.config and context.config.extra_config:
+            link_type_str = context.config.extra_config.get(
+                "infinistore_link_type", link_type_str
+            )
+
+        link_type_str = link_type_str.upper()
+        try:
+            link_type = getattr(infinistore, link_type_str)
+        except AttributeError as e:
+            raise ValueError(f"Invalid link_type: {link_type_str}") from e
+
+        return InfinistoreConnector(
+            host=parse_url.host,
+            port=parse_url.port,
+            dev_name=device_name,
+            link_type=link_type,
+            loop=context.loop,
+            memory_allocator=context.local_cpu_backend,
+        )
diff --git a/lmcache/v1/storage_backend/connector/infinistore_connector.py b/lmcache/v1/storage_backend/connector/infinistore_connector.py
new file mode 100644
index 0000000..537dd54
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/infinistore_connector.py
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from functools import reduce
+from typing import List, Optional, Union, no_type_check
+import asyncio
+import ctypes
+import operator
+
+# Third Party
+import infinistore
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+
+# reuse
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+MAX_BUFFER_SIZE = 40 << 20  # 40MB
+METADATA_BYTES_LEN = 28
+MAX_BUFFER_CNT = 16
+
+
+def _get_ptr(mv: Union[bytearray, memoryview]) -> int:
+    return ctypes.addressof(ctypes.c_char.from_buffer(mv))
+
+
+class InfinistoreConnector(RemoteConnector):
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        dev_name: str,
+        link_type: str,
+        loop: asyncio.AbstractEventLoop,
+        memory_allocator: LocalCPUBackend,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(memory_allocator.config, memory_allocator.metadata)
+
+        config = infinistore.ClientConfig(
+            host_addr=host,
+            service_port=port,
+            log_level="info",
+            connection_type=infinistore.TYPE_RDMA,
+            ib_port=1,
+            link_type=link_type,
+            dev_name=dev_name,
+        )
+
+        self.rdma_conn = infinistore.InfinityConnection(config)
+
+        self.loop = loop
+        self.rdma_conn.connect()
+
+        self.send_buffers = []
+        self.recv_buffers = []
+        self.send_queue: asyncio.Queue[int] = asyncio.Queue(maxsize=MAX_BUFFER_CNT)
+        self.recv_queue: asyncio.Queue[int] = asyncio.Queue(maxsize=MAX_BUFFER_CNT)
+
+        self.buffer_size = MAX_BUFFER_SIZE
+        self.memory_allocator = memory_allocator
+
+        for i in range(MAX_BUFFER_CNT):
+            send_buffer = bytearray(self.buffer_size)
+            self.rdma_conn.register_mr(_get_ptr(send_buffer), self.buffer_size)
+            self.send_buffers.append(send_buffer)
+            self.send_queue.put_nowait(i)
+
+            recv_buffer = bytearray(self.buffer_size)
+            self.rdma_conn.register_mr(_get_ptr(recv_buffer), self.buffer_size)
+            self.recv_buffers.append(recv_buffer)
+            self.recv_queue.put_nowait(i)
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        def blocking_io():
+            return self.rdma_conn.check_exist(key.to_string())
+
+        return await self.loop.run_in_executor(None, blocking_io)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return self.rdma_conn.check_exist(key.to_string())
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+
+        buf_idx = await self.recv_queue.get()
+        buffer = self.recv_buffers[buf_idx]
+        try:
+            await self.rdma_conn.rdma_read_cache_async(
+                [(key_str, 0)], self.buffer_size, _get_ptr(buffer)
+            )
+        except Exception as e:
+            logger.warning(f"get failed: {e}")
+            self.recv_queue.put_nowait(buf_idx)
+            return None
+
+        metadata = RemoteMetadata.deserialize(buffer)
+
+        num_elements = reduce(operator.mul, metadata.shapes[0])
+        assert len(metadata.dtypes) == 1
+        temp_tensor = torch.frombuffer(
+            buffer,
+            dtype=metadata.dtypes[0],
+            offset=METADATA_BYTES_LEN,
+            count=num_elements,
+        ).reshape(metadata.shapes[0])
+
+        memory_obj = self.memory_allocator.allocate(
+            metadata.shapes[0],
+            metadata.dtypes[0],
+            metadata.fmt,
+        )
+
+        assert memory_obj is not None
+        assert memory_obj.tensor is not None
+
+        # deep copy to pinned memory
+        # and hot cache will reference this memory obj
+        memory_obj.tensor.copy_(temp_tensor)
+
+        logger.debug(f"get key: {key_str} done, {memory_obj.get_shape()}")
+        self.recv_queue.put_nowait(buf_idx)
+
+        return memory_obj
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        key_str = key.to_string()
+
+        kv_bytes = memory_obj.byte_array
+        kv_shapes = memory_obj.get_shapes()
+        kv_dtypes = memory_obj.get_dtypes()
+        memory_format = memory_obj.get_memory_format()
+
+        buf_idx = await self.send_queue.get()
+        buffer = self.send_buffers[buf_idx]
+
+        RemoteMetadata(
+            len(kv_bytes), kv_shapes, kv_dtypes, memory_format
+        ).serialize_into(buffer)
+
+        buffer[METADATA_BYTES_LEN : METADATA_BYTES_LEN + len(kv_bytes)] = kv_bytes
+
+        size = memory_obj.get_physical_size()
+
+        if size + METADATA_BYTES_LEN > self.buffer_size:
+            raise ValueError(
+                f"Value size ({size + METADATA_BYTES_LEN} bytes)"
+                f"exceeds the maximum allowed size"
+                f"({self.buffer_size} bytes). Please decrease chunk_size."
+            )
+        try:
+            await self.rdma_conn.rdma_write_cache_async(
+                [(key_str, 0)], METADATA_BYTES_LEN + size, _get_ptr(buffer)
+            )
+        except Exception as e:
+            logger.warning(f"exception happens in rdma_write_cache_async kv_bytes {e}")
+            return
+        finally:
+            self.send_queue.put_nowait(buf_idx)
+
+        logger.debug(f"put key: {key.to_string()}, {memory_obj.get_shape()}")
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        self.rdma_conn.close()
+        logger.info("Closed the infinistore connection")
diff --git a/lmcache/v1/storage_backend/connector/instrumented_connector.py b/lmcache/v1/storage_backend/connector/instrumented_connector.py
new file mode 100644
index 0000000..6917ecf
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/instrumented_connector.py
@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class InstrumentedRemoteConnector(RemoteConnector):
+    """
+    A connector that instruments the underlying connector with
+    metrics collection and logging capabilities.
+    """
+
+    def __init__(self, connector: RemoteConnector):
+        self._connector = connector
+        self._stats_monitor = LMCStatsMonitor.GetOrCreate()
+        self.name = self.__repr__()
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        obj_size = memory_obj.get_size()
+        begin = time.perf_counter()
+        try:
+            await self._connector.put(key, memory_obj)
+        finally:
+            # Ensure reference count is decreased even if exception occurs
+            memory_obj.ref_count_down()
+
+        end = time.perf_counter()
+        self._stats_monitor.update_interval_remote_time_to_put((end - begin) * 1000)
+        self._stats_monitor.update_interval_remote_write_metrics(obj_size)
+        logger.debug(
+            "[%s]Bytes offloaded: %.3f MBytes in %.3f ms",
+            self.name,
+            obj_size / 1e6,
+            (end - begin) * 1000,
+        )
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        begin = time.perf_counter()
+        memory_obj = await self._connector.get(key)
+        end = time.perf_counter()
+        duration = end - begin
+
+        retrieve_stats = self._stats_monitor.get_current_retrieve_stats()
+        if (
+            retrieve_stats is not None
+            and "remote_backend_individual_get_stats" in retrieve_stats.detailed_metrics
+        ):
+            retrieve_stats.detailed_metrics["remote_backend_individual_get_stats"][
+                key
+            ] = {"instrumented_connector_get_time": duration}
+
+        if memory_obj is not None:
+            obj_size = memory_obj.get_size()
+            self._stats_monitor.update_interval_remote_read_metrics(obj_size)
+            logger.debug(
+                "[%s]Bytes loaded: %.3f MBytes in %.3f ms",
+                self.name,
+                obj_size / 1e6,
+                duration * 1000,
+            )
+        return memory_obj
+
+    # Delegate all other methods to the underlying connector
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return await self._connector.exists(key)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return self._connector.exists_sync(key)
+
+    async def list(self) -> List[str]:
+        return await self._connector.list()
+
+    async def close(self) -> None:
+        await self._connector.close()
+
+    def getWrappedConnector(self) -> RemoteConnector:
+        return self._connector
+
+    def support_ping(self) -> bool:
+        return self._connector.support_ping()
+
+    async def ping(self) -> int:
+        return await self._connector.ping()
+
+    def support_batched_put(self) -> bool:
+        return self._connector.support_batched_put()
+
+    def support_batched_get(self) -> bool:
+        return self._connector.support_batched_get()
+
+    def support_batched_async_contains(self) -> bool:
+        return self._connector.support_batched_async_contains()
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        return await self._connector.batched_async_contains(lookup_id, keys, pin)
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return self._connector.support_batched_get_non_blocking()
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        begin = time.perf_counter()
+        memory_objs = await self._connector.batched_get_non_blocking(lookup_id, keys)
+        end = time.perf_counter()
+        duration = end - begin
+
+        total_size = sum(
+            memory_obj.get_size()
+            for memory_obj in memory_objs
+            if memory_obj is not None
+        )
+        if total_size > 0:
+            self._stats_monitor.update_interval_remote_read_metrics(total_size)
+            logger.debug(
+                "[%s]Bytes loaded: %.3f MBytes in %.3f ms",
+                self.name,
+                total_size / 1e6,
+                duration * 1000,
+            )
+        return memory_objs
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        begin = time.perf_counter()
+        memory_objs = await self._connector.batched_get(keys)
+        end = time.perf_counter()
+        duration = end - begin
+        self._stats_monitor.update_interval_remote_time_to_get(duration * 1000)
+
+        retrieve_stats = self._stats_monitor.get_current_retrieve_stats()
+        if retrieve_stats is not None:
+            retrieve_stats.detailed_metrics[
+                "instrumented_connector_batched_get_time"
+            ] = (
+                retrieve_stats.detailed_metrics.get(
+                    "instrumented_connector_batched_get_time", 0.0
+                )
+                + duration
+            )
+
+        total_size = sum(
+            memory_obj.get_size()
+            for memory_obj in memory_objs
+            if memory_obj is not None
+        )
+        if total_size > 0:
+            self._stats_monitor.update_interval_remote_read_metrics(total_size)
+            logger.debug(
+                "[%s]Bytes loaded: %.3f MBytes in %.3f ms",
+                self.name,
+                total_size / 1e6,
+                duration * 1000,
+            )
+        return memory_objs
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        total_size = sum(
+            memory_obj.get_size()
+            for memory_obj in memory_objs
+            if memory_obj is not None
+        )
+        begin = time.perf_counter()
+        try:
+            await self._connector.batched_put(keys, memory_objs)
+        except Exception as e:
+            logger.warning(f"batched put error: {e}")
+        finally:
+            for memory_obj in memory_objs:
+                memory_obj.ref_count_down()
+
+        end = time.perf_counter()
+        self._stats_monitor.update_interval_remote_time_to_put((end - begin) * 1000)
+        self._stats_monitor.update_interval_remote_write_metrics(total_size)
+        logger.debug(
+            "[%s]Bytes offloaded: %.3f MBytes in %.3f ms",
+            self.name,
+            total_size / 1e6,
+            (end - begin) * 1000,
+        )
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        return self._connector.remove_sync(key)
+
+    def batched_contains(self, keys: List[CacheEngineKey]) -> int:
+        return self._connector.batched_contains(keys)
+
+    def support_batched_contains(self) -> bool:
+        return self._connector.support_batched_contains()
+
+    def reshape_partial_chunk(
+        self, memory_obj: MemoryObj, bytes_read: int
+    ) -> MemoryObj:
+        return self._connector.reshape_partial_chunk(memory_obj, bytes_read)
+
+    def post_init(self):
+        return self._connector.post_init()
+
+    def __repr__(self) -> str:
+        return f"InstrumentedRemoteConnector({self._connector})"
diff --git a/lmcache/v1/storage_backend/connector/lm_adapter.py b/lmcache/v1/storage_backend/connector/lm_adapter.py
new file mode 100644
index 0000000..1b23056
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/lm_adapter.py
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class LMServerConnectorAdapter(ConnectorAdapter):
+    """Adapter for LM Server connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("lm://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .lm_connector import LMCServerConnector
+
+        logger.info(f"Creating LM Server connector for URL: {context.url}")
+        parse_url = parse_remote_url(context.url)
+        return LMCServerConnector(
+            host=parse_url.host,
+            port=parse_url.port,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+        )
diff --git a/lmcache/v1/storage_backend/connector/lm_connector.py b/lmcache/v1/storage_backend/connector/lm_connector.py
new file mode 100644
index 0000000..03af80a
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/lm_connector.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional, no_type_check
+import asyncio
+import socket
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey, _lmcache_nvtx_annotate
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.protocol import (
+    ClientCommand,
+    ClientMetaMessage,
+    ServerMetaMessage,
+    ServerReturnCode,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+# TODO: performance optimization for this class, consider using C/C++/Rust
+# for communication + deserialization
+class LMCServerConnector(RemoteConnector):
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ):
+        # NOTE(Jiayi): According to Python documentation:
+        # https://docs.python.org/3/library/asyncio-eventloop.html
+        # In general, protocol implementations that use transport-based APIs
+        # such as loop.create_connection() and loop.create_server() are faster
+        # than implementations that work with sockets.
+        # However, we use socket here as we need to use the socket.recv_into()
+        # to reduce memory copy.
+
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        self.client_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.client_socket.connect((host, port))
+        # loop.sock_recv_into(sock, buf)
+
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.async_socket_lock = asyncio.Lock()
+
+    # TODO(Jiayi): This should be an async function
+    def receive_all(self, meta: ServerMetaMessage) -> Optional[MemoryObj]:
+        received = 0
+        n = meta.length
+
+        # TODO(Jiayi): Format will be used once we support
+        # compressed memory format
+        memory_obj = self.local_cpu_backend.allocate(
+            meta.shape,
+            meta.dtype,
+            meta.fmt,
+        )
+        if memory_obj is None:
+            logger.warning("Failed to allocate memory during remote receive")
+            return None
+
+        buffer = memory_obj.byte_array
+        view = memoryview(buffer)
+
+        while received < n:
+            num_bytes = self.client_socket.recv_into(view[received:], n - received)
+            if num_bytes == 0:
+                return None
+            received += num_bytes
+
+        return memory_obj
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        # logger.debug("Call to exists()!")
+
+        async with self.async_socket_lock:
+            self.client_socket.sendall(
+                ClientMetaMessage(
+                    ClientCommand.EXIST,
+                    key,
+                    0,
+                    MemoryFormat(1),
+                    torch.float16,
+                    torch.Size([0, 0, 0, 0]),
+                ).serialize()
+            )
+
+            response = self.client_socket.recv(ServerMetaMessage.packlength())
+
+        return ServerMetaMessage.deserialize(response).code == ServerReturnCode.SUCCESS
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        future = asyncio.run_coroutine_threadsafe(self.exists(key), self.loop)
+        try:
+            res = future.result()
+            return res
+        except Exception as e:
+            logger.warning(f"lm connector failed in exists: {e}")
+            return False
+
+    async def put(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+    ):
+        # logger.debug("Async call to put()!")
+
+        kv_bytes = memory_obj.byte_array
+        kv_shape = memory_obj.get_shape()
+        kv_dtype = memory_obj.get_dtype()
+        memory_format = memory_obj.get_memory_format()
+
+        async with self.async_socket_lock:
+            await self.loop.sock_sendall(
+                self.client_socket,
+                ClientMetaMessage(
+                    ClientCommand.PUT,
+                    key,
+                    len(kv_bytes),
+                    memory_format,
+                    kv_dtype,
+                    kv_shape,
+                ).serialize(),
+            )
+
+            await self.loop.sock_sendall(self.client_socket, kv_bytes)
+
+    # TODO(Jiayi): This should be an async function
+    @_lmcache_nvtx_annotate
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        # NOTE(Jiayi): Not using any await in the following as
+        # we don't want to yield control to other tasks which could
+        # sacrifice the performance loading to trade the performance of
+        # saving
+        async with self.async_socket_lock:
+            self.client_socket.sendall(
+                ClientMetaMessage(
+                    ClientCommand.GET,
+                    key,
+                    0,
+                    MemoryFormat(1),
+                    torch.float16,
+                    torch.Size([0, 0, 0, 0]),
+                ).serialize()
+            )
+
+            data = self.client_socket.recv(ServerMetaMessage.packlength())
+
+        meta = ServerMetaMessage.deserialize(data)
+        if meta.code != ServerReturnCode.SUCCESS:
+            return None
+
+        async with self.async_socket_lock:
+            memory_obj = self.receive_all(meta)
+
+        return memory_obj
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        async with self.async_socket_lock:
+            self.client_socket.close()
+        logger.info("Closed the lmserver connection")
diff --git a/lmcache/v1/storage_backend/connector/mock_adapter.py b/lmcache/v1/storage_backend/connector/mock_adapter.py
new file mode 100644
index 0000000..274cb80
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/mock_adapter.py
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from urllib.parse import parse_qs, urlparse
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class MockConnectorAdapter(ConnectorAdapter):
+    """Adapter for Mock Connector"""
+
+    def __init__(self) -> None:
+        super().__init__("mock://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local import to avoid circular dependencies
+        # Local
+        from .mock_connector import MockConnector
+
+        logger.info(f"Creating Mock connector for URL: {context.url}")
+
+        parsed = urlparse(context.url)
+        # capacity is provided as the netloc in URLs like: mock://100/?...
+        if not parsed.netloc:
+            raise ValueError(
+                "mock connector requires capacity in GB as netloc, e.g. mock://100/?..."
+            )
+        try:
+            capacity_gb = int(parsed.netloc)
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid capacity '{parsed.netloc}' for",
+                " mock connector; must be an integer (GB).",
+            ) from e
+
+        params = parse_qs(parsed.query) if parsed.query else {}
+        # Defaults
+        peeking_latency_ms = float(params.get("peeking_latency", ["1"])[0])
+        read_throughput_gbps = float(params.get("read_throughput", ["2"])[0])
+        write_throughput_gbps = float(params.get("write_throughput", ["2"])[0])
+
+        return MockConnector(
+            url=context.url,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            capacity=capacity_gb,
+            read_throughput=read_throughput_gbps,
+            write_throughput=write_throughput_gbps,
+            peeking_latency=peeking_latency_ms,
+        )
diff --git a/lmcache/v1/storage_backend/connector/mock_connector.py b/lmcache/v1/storage_backend/connector/mock_connector.py
new file mode 100644
index 0000000..1c44e1b
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/mock_connector.py
@@ -0,0 +1,349 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+
+# Standard
+from collections import OrderedDict
+from dataclasses import dataclass
+from enum import IntEnum, auto
+from typing import List, Optional
+import asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj, MemoryObjMetadata, TensorMemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+class Priorities(IntEnum):
+    PEEK = auto()
+    PREFETCH = auto()
+    GET = auto()
+    PUT = auto()
+
+
+@dataclass
+class MockMemoryObj:
+    metadata: MemoryObjMetadata
+    num_bytes: int
+
+    @staticmethod
+    def from_tensor_memory_obj(tensor_memory_obj: MemoryObj) -> "MockMemoryObj":
+        assert isinstance(tensor_memory_obj, TensorMemoryObj)
+        return MockMemoryObj(
+            metadata=tensor_memory_obj.metadata,
+            num_bytes=len(tensor_memory_obj.byte_array),
+        )
+
+
+class AsyncLRU:
+    """
+    the async lock protects against race conditions while mimicking synchronization
+    being done on a remote server (async client)
+    """
+
+    def __init__(self, capacity: int):
+        self.lock = asyncio.Lock()
+        # current size in bytes
+        self.size = 0
+        self.capacity = capacity * 1024**3
+        self.dict: OrderedDict[CacheEngineKey, MockMemoryObj] = OrderedDict()
+
+    async def exists(self, key: CacheEngineKey):
+        async with self.lock:
+            if key in self.dict:
+                self.dict.move_to_end(key)
+                return True
+            return False
+
+    async def get(self, key: CacheEngineKey) -> Optional[MockMemoryObj]:
+        async with self.lock:
+            if key not in self.dict:
+                return None
+            self.dict.move_to_end(key)
+            return self.dict[key]
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MockMemoryObj]]:
+        async with self.lock:
+            return [self.dict.get(key, None) for key in keys]
+
+    async def put(self, key: CacheEngineKey, mock_obj: MockMemoryObj):
+        async with self.lock:
+            alloc_size = mock_obj.num_bytes
+            if alloc_size > self.capacity:
+                raise ValueError(
+                    f"Allocation size {alloc_size} is",
+                    " greater than capacity {self.capacity}",
+                )
+            if key in self.dict:
+                self.dict.move_to_end(key)
+                return None
+            self.dict[key] = mock_obj
+            while self.size + alloc_size > self.capacity:
+                _, mock_obj = self.dict.popitem(last=False)
+                self.size -= mock_obj.num_bytes
+            self.size += alloc_size
+
+    async def list(self) -> List[CacheEngineKey]:
+        async with self.lock:
+            return list(self.dict.keys())
+
+    async def close(self):
+        async with self.lock:
+            self.dict.clear()
+
+
+class PressureManager:
+    """
+    Manage I/O pressure of the mock connector
+    Assumption: Read and Write throughput are independent
+    Locks control overall backend throughput, not per-operation throughput
+    """
+
+    def __init__(
+        self,
+        peeking_latency: float,
+        read_throughput: float,
+        write_throughput: float,
+    ):
+        # seconds
+        self.peeking_latency = peeking_latency / 1000
+        # seconds / byte
+        self.read_latency_per_byte = (1 / read_throughput) / 1024**3
+        self.write_latency_per_byte = (1 / write_throughput) / 1024**3
+
+        self.read_lock = asyncio.Lock()
+        self.write_lock = asyncio.Lock()
+
+    async def on_exists(self):
+        # exists latency will delay everyone
+        logger.debug(f"waiting {self.peeking_latency} seconds to peek")
+        if self.peeking_latency > 0:
+            await asyncio.sleep(self.peeking_latency)
+
+    async def on_put(self, mock_obj: MockMemoryObj):
+        total_wait_time = self.write_latency_per_byte * mock_obj.num_bytes
+        logger.debug(
+            f"waiting {total_wait_time} seconds to put {mock_obj.num_bytes} bytes"
+        )
+        async with self.write_lock:
+            await asyncio.sleep(total_wait_time)
+
+    async def on_get(self, mock_obj: MockMemoryObj):
+        total_wait_time = self.read_latency_per_byte * mock_obj.num_bytes
+        logger.debug(
+            f"waiting {total_wait_time} seconds to get {mock_obj.num_bytes} bytes"
+        )
+        async with self.read_lock:
+            await asyncio.sleep(total_wait_time)
+
+    async def on_batched_get(self, mock_objs: List[Optional[MockMemoryObj]]):
+        total_bytes = 0
+        for mock_obj in mock_objs:
+            if mock_obj is None:
+                continue
+            total_bytes += mock_obj.num_bytes
+        total_wait_time = self.read_latency_per_byte * total_bytes
+        logger.debug(f"waiting {total_wait_time} seconds to get {total_bytes} bytes")
+        async with self.read_lock:
+            await asyncio.sleep(total_wait_time)
+
+
+class MockConnector(RemoteConnector):
+    """
+    A CPU "remote" backend that doesn't actually go through any network/DB layers and
+    let's you manually set R/W throughput and peek latency
+    """
+
+    def __init__(
+        self,
+        url: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        capacity: int,
+        peeking_latency: float = 1.0,
+        read_throughput: float = 2.0,
+        write_throughput: float = 2.0,
+    ):
+        """
+        peeking_latency: latency for peeking a key (ms)
+        capacity: capacity in GB
+        read_throughput: GB/s for reading
+        write_throughput: GB/s for writing
+        """
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.lru_store = AsyncLRU(capacity)
+
+        self.pressure_manager = PressureManager(
+            peeking_latency=peeking_latency,
+            read_throughput=read_throughput,
+            write_throughput=write_throughput,
+        )
+
+        # only for the __repr__ string
+        self.capacity = capacity
+        self.peeking_latency = peeking_latency
+        self.read_throughput = read_throughput
+        self.write_throughput = write_throughput
+
+        # only for the async loading codepath
+        # MockConnector is naturally async so we don't need to use a thread pool
+        # for avoiding R-W interference
+        self.pq_executor = AsyncPQExecutor(loop)
+
+    async def _exists(self, key: CacheEngineKey) -> bool:
+        await self.pressure_manager.on_exists()
+        return await self.lru_store.exists(key)
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return await self.pq_executor.submit_job(
+            self._exists, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Synchronous exists check without async lock (for testing purposes)"""
+        return key in self.lru_store.dict
+
+    async def _get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        mock_obj = await self.lru_store.get(key)
+        if mock_obj is None:
+            return None
+        await self.pressure_manager.on_get(mock_obj)
+        metadata = mock_obj.metadata
+        memory_obj = self.local_cpu_backend.allocate(
+            metadata.shape,
+            metadata.dtype,
+            metadata.fmt,
+        )
+
+        if memory_obj is None:
+            logger.warning("Failed to allocate memory during remote receive")
+            return None
+        return memory_obj
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._get, key=key, priority=Priorities.GET
+        )
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        mock_obj = MockMemoryObj.from_tensor_memory_obj(memory_obj)
+        await self.lru_store.put(key, mock_obj)
+        await self.pressure_manager.on_put(mock_obj)
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        await self.pq_executor.submit_job(
+            self._put, key=key, memory_obj=memory_obj, priority=Priorities.PUT
+        )
+
+    async def list(self) -> List[str]:
+        keys = await self.lru_store.list()
+        return [k.to_string() for k in keys]
+
+    def support_batched_get(self) -> bool:
+        return True
+
+    async def _batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        mock_objs = await self.lru_store.batched_get(keys)
+        await self.pressure_manager.on_batched_get(mock_objs)
+        memory_objs = []
+
+        for i, mock_obj in enumerate(mock_objs):
+            if mock_obj is None:
+                logger.warning(
+                    f"Mock object is None on {i}",
+                    f" out of {len(mock_objs)} objects",
+                )
+                break
+            metadata = mock_obj.metadata
+            memory_obj = self.local_cpu_backend.allocate(
+                metadata.shape,
+                metadata.dtype,
+                metadata.fmt,
+            )
+            if memory_obj is None:
+                logger.warning(
+                    "Failed to allocate memory even with",
+                    f" busy loop on {i} out of {len(mock_objs)} objects",
+                )
+                break
+            memory_objs.append(memory_obj)
+
+        return memory_objs
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        return await self.pq_executor.submit_job(
+            self._batched_get, keys=keys, priority=Priorities.GET
+        )
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def _batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        num_hit_counts = 0
+        for key in keys:
+            await self.pressure_manager.on_exists()
+            if not await self.lru_store.exists(key):
+                return num_hit_counts
+            num_hit_counts += 1
+        return num_hit_counts
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains,
+            lookup_id=lookup_id,
+            keys=keys,
+            pin=pin,
+            priority=Priorities.PEEK,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        # batched get is already async and the non-blocking element is handled
+        # in the StorageManager
+        return await self.pq_executor.submit_job(
+            self._batched_get, keys=keys, priority=Priorities.PREFETCH
+        )
+
+    async def close(self):
+        await self.lru_store.close()
+        await self.pq_executor.shutdown(wait=True)
+
+    def __repr__(self) -> str:
+        return (
+            f"MockConnector(capacity={self.capacity}GB, "
+            f"peeking_latency={self.peeking_latency}ms, "
+            f"read_throughput={self.read_throughput}GB/s, "
+            f"write_throughput={self.write_throughput}GB/s)"
+        )
diff --git a/lmcache/v1/storage_backend/connector/mooncakestore_adapter.py b/lmcache/v1/storage_backend/connector/mooncakestore_adapter.py
new file mode 100644
index 0000000..21de105
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/mooncakestore_adapter.py
@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    extract_plugin_type,
+)
+from lmcache.v1.storage_backend.connector.base_connector import (
+    RemoteConnector,
+)
+
+logger = init_logger(__name__)
+
+PLUGIN_TYPE = "mooncakestore"
+
+
+class MooncakestoreConnectorAdapter(ConnectorAdapter):
+    """Adapter for Mooncakestore connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("mooncakestore://")
+
+    def can_parse(self, url: str) -> bool:
+        if url.startswith(self.schema):
+            return True
+        if url.startswith("plugin://"):
+            pname = url[len("plugin://") :]
+            return extract_plugin_type(pname) == PLUGIN_TYPE
+        return False
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .mooncakestore_connector import MooncakestoreConnector
+
+        logger.info("Creating Mooncakestore connector")
+
+        return MooncakestoreConnector(
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            lmcache_config=context.config,
+            plugin_name=context.plugin_name,
+        )
diff --git a/lmcache/v1/storage_backend/connector/mooncakestore_connector.py b/lmcache/v1/storage_backend/connector/mooncakestore_connector.py
new file mode 100644
index 0000000..2f78c9b
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/mooncakestore_connector.py
@@ -0,0 +1,830 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Dict, List, Optional, no_type_check
+import asyncio
+import json
+import os
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.system_detection import NUMADetector
+
+logger = init_logger(__name__)
+
+# TODO(baoloongmao): Remove these in the future
+# Legacy positional-arg key order for old mooncake setup API
+_LEGACY_SETUP_KEYS = [
+    "local_hostname",
+    "metadata_server",
+    "global_segment_size",
+    "local_buffer_size",
+    "protocol",
+    "device_name",
+    "master_server_address",
+]
+
+
+# Legacy keys that must be passed as ``int`` to the old
+# positional-arg ``store.setup()`` API (C++/pybind11).
+_LEGACY_INT_KEYS = {"global_segment_size", "local_buffer_size"}
+
+# Keys whose values may contain credentials and must be
+# redacted when the setup dict is logged.
+_SENSITIVE_SETUP_KEYS = {"metadata_server", "master_server_address"}
+
+
+def _sanitize_setup_config(
+    setup_config: Dict[str, str],
+) -> Dict[str, str]:
+    """Return a copy of *setup_config* with sensitive values
+    redacted, safe for logging."""
+    sanitized: Dict[str, str] = {}
+    for k, v in setup_config.items():
+        lower_k = k.lower()
+        if (
+            k in _SENSITIVE_SETUP_KEYS
+            or "password" in lower_k
+            or "token" in lower_k
+            or "secret" in lower_k
+            or "key" in lower_k
+        ):
+            sanitized[k] = "***REDACTED***"
+        else:
+            sanitized[k] = v
+    return sanitized
+
+
+def setup_mooncake_store(
+    store: Any,
+    config: "MooncakeStoreConfig",
+) -> None:
+    """Initialize a MooncakeDistributedStore instance.
+
+    Calls ``store.setup()`` using the dict-based API introduced
+    in Mooncake PR #1445 when available, and transparently falls
+    back to the legacy positional-arg API otherwise.  This lets
+    LMCache work with both new and old mooncake builds without
+    requiring callers to know which API is present.
+
+    Args:
+        store: A MooncakeDistributedStore instance (already
+            constructed but not yet setup).  Must expose a
+            ``setup()`` method.
+        config: A :class:`MooncakeStoreConfig` carrying the
+            setup parameters in ``config.setup_config``.
+
+    Returns:
+        None.  ``store`` is mutated in place.
+
+    Raises:
+        Exception: Any exception raised by ``store.setup()``
+            other than :class:`TypeError` is propagated to the
+            caller (``TypeError`` is caught and used as the
+            signal to fall back to the legacy API).
+    """
+    setup_dict = config.setup_config
+    try:
+        # New API (Mooncake PR #1445): setup(config: dict)
+        store.setup(setup_dict)
+        logger.info("Using dict-based setup API (new)")
+    except TypeError:
+        # Legacy API: setup with positional arguments.
+        # Some keys (e.g. ``global_segment_size``) must be int.
+        logger.info(
+            "Dict-based setup not available, "
+            "falling back to positional-arg API (legacy)"
+        )
+        args: List[Any] = []
+        for k in _LEGACY_SETUP_KEYS:
+            v: Any = setup_dict.get(k, "")
+            if k in _LEGACY_INT_KEYS:
+                try:
+                    v = int(v) if v != "" else 0
+                except (TypeError, ValueError):
+                    v = 0
+            args.append(v)
+        store.setup(*args)
+
+
+# Prefix for keys that should be forwarded to mooncake setup.
+# e.g. ``mooncake_local_hostname`` -> ``local_hostname``
+_MOONCAKE_PREFIX = "mooncake_"
+
+# Keys that are consumed by LMCache only (never sent to mooncake).
+_LMCACHE_ONLY_KEYS = {
+    "transfer_timeout",
+    "storage_root_dir",
+    "prefer_local_alloc",
+    "mooncake_transfer_timeout",
+    "mooncake_storage_root_dir",
+    "mooncake_prefer_local_alloc",
+}
+
+# Legacy keys that are forwarded without prefix (for compat).
+_LEGACY_PASSTHROUGH_KEYS = {
+    "local_hostname",
+    "metadata_server",
+    "global_segment_size",
+    "local_buffer_size",
+    "protocol",
+    "device_name",
+    "master_server_address",
+}
+
+# Default values for mooncake setup keys
+_SETUP_DEFAULTS: Dict[str, str] = {
+    "global_segment_size": "3355443200",
+    "local_buffer_size": "1073741824",
+    "protocol": "tcp",
+    "device_name": "",
+}
+
+
+class MooncakeStoreConfig:
+    """Configuration for MooncakeDistributedStore.
+
+    Mooncake setup keys are stored in ``setup_config`` dict
+    and passed through to ``store.setup()`` as-is.  This
+    means LMCache does **not** need to change when mooncake
+    adds or removes setup keys.
+
+    LMCache-only knobs (``transfer_timeout``,
+    ``storage_root_dir``, ``prefer_local_alloc``) are kept
+    as explicit attributes.
+    """
+
+    def __init__(
+        self,
+        setup_config: Dict[str, str],
+        transfer_timeout: int = 1,
+        storage_root_dir: str = "",
+        prefer_local_alloc: bool = False,
+    ):
+        self.setup_config = dict(setup_config)
+        self.transfer_timeout = transfer_timeout
+        self.storage_root_dir = storage_root_dir
+        self.prefer_local_alloc = prefer_local_alloc
+
+    def __repr__(self) -> str:
+        # Redact sensitive values to keep logs safe.
+        return (
+            "MooncakeStoreConfig("
+            "setup_config=%r, "
+            "transfer_timeout=%r, "
+            "storage_root_dir=%r, "
+            "prefer_local_alloc=%r)"
+            % (
+                _sanitize_setup_config(self.setup_config),
+                self.transfer_timeout,
+                self.storage_root_dir,
+                self.prefer_local_alloc,
+            )
+        )
+
+    # ----------------------------------------------------------
+    # Deprecated attribute-style accessors for backward compat
+    # ----------------------------------------------------------
+    def _get_setup_key(self, key: str) -> str:
+        return self.setup_config.get(key, "")
+
+    def _set_setup_key(self, key: str, value: str) -> None:
+        self.setup_config[key] = value
+
+    @property
+    def local_hostname(self) -> str:  # deprecated
+        return self._get_setup_key("local_hostname")
+
+    @property
+    def metadata_server(self) -> str:  # deprecated
+        return self._get_setup_key("metadata_server")
+
+    @property
+    def global_segment_size(self) -> str:  # deprecated
+        return self._get_setup_key("global_segment_size")
+
+    @property
+    def local_buffer_size(self) -> str:  # deprecated
+        return self._get_setup_key("local_buffer_size")
+
+    @property
+    def protocol(self) -> str:  # deprecated
+        return self._get_setup_key("protocol")
+
+    @property
+    def device_name(self) -> str:  # deprecated
+        return self._get_setup_key("device_name")
+
+    @device_name.setter
+    def device_name(self, value: str) -> None:  # deprecated
+        self._set_setup_key("device_name", value)
+
+    @property
+    def master_server_address(self) -> str:  # deprecated
+        return self._get_setup_key("master_server_address")
+
+    @master_server_address.setter
+    def master_server_address(  # deprecated
+        self, value: str
+    ) -> None:
+        self._set_setup_key("master_server_address", value)
+
+    # ----------------------------------------------------------
+    # Factory methods
+    # ----------------------------------------------------------
+    @staticmethod
+    def _build_setup_dict(
+        raw: Dict[str, Any],
+    ) -> Dict[str, str]:
+        """Extract mooncake setup keys from *raw* config dict.
+
+        Rules (evaluated in order):
+        1. Keys in ``_LMCACHE_ONLY_KEYS`` are skipped.
+        2. Keys starting with ``mooncake_`` have the prefix
+           stripped and are forwarded (highest priority).
+        3. Keys in ``_LEGACY_PASSTHROUGH_KEYS`` are forwarded
+           as-is (backward compat, lower priority).
+        4. All other keys are ignored.
+
+        Missing keys with known defaults are filled in.
+        """
+        setup: Dict[str, str] = {}
+        # Prefixed keys have higher priority than legacy keys;
+        # collect them separately and apply last.
+        prefixed_setup: Dict[str, str] = {}
+        prefix_len = len(_MOONCAKE_PREFIX)
+
+        for k, v in raw.items():
+            if k in _LMCACHE_ONLY_KEYS or v is None:
+                continue
+            if k.startswith(_MOONCAKE_PREFIX):
+                stripped = k[prefix_len:]
+                if stripped:
+                    prefixed_setup[stripped] = str(v)
+            elif k in _LEGACY_PASSTHROUGH_KEYS:
+                setup[k] = str(v)
+
+        # Prefixed keys override legacy keys on conflict.
+        setup.update(prefixed_setup)
+
+        # Apply defaults for keys not provided
+        for k, default_v in _SETUP_DEFAULTS.items():
+            setup.setdefault(k, default_v)
+        return setup
+
+    @staticmethod
+    def from_file(
+        file_path: str,
+    ) -> "MooncakeStoreConfig":
+        """Load the config from a JSON file."""
+        with open(file_path) as fin:
+            raw = json.load(fin)
+        return MooncakeStoreConfig(
+            setup_config=MooncakeStoreConfig._build_setup_dict(raw),
+            transfer_timeout=raw.get("transfer_timeout", 1),
+            storage_root_dir=raw.get("storage_root_dir", ""),
+            prefer_local_alloc=raw.get("mooncake_prefer_local_alloc", False),
+        )
+
+    @staticmethod
+    def load_from_env() -> "MooncakeStoreConfig":
+        """Load config from MOONCAKE_CONFIG_PATH env var."""
+        config_file_path = os.getenv("MOONCAKE_CONFIG_PATH")
+        if config_file_path is None:
+            raise ValueError(
+                "The environment variable 'MOONCAKE_CONFIG_PATH' is not set."
+            )
+        return MooncakeStoreConfig.from_file(config_file_path)
+
+    @staticmethod
+    def load_from_lmcache_config(
+        config: "LMCacheEngineConfig",
+    ) -> "MooncakeStoreConfig":
+        """Load config from LMCacheEngineConfig.extra_config."""
+        extra_config = config.extra_config
+        if extra_config is None:
+            raise ValueError("The extra config is not set.")
+        return MooncakeStoreConfig(
+            setup_config=MooncakeStoreConfig._build_setup_dict(extra_config),
+            transfer_timeout=extra_config.get("transfer_timeout", 1),
+            storage_root_dir=extra_config.get("storage_root_dir", ""),
+            prefer_local_alloc=extra_config.get("mooncake_prefer_local_alloc", False),
+        )
+
+
+class MooncakestoreConnector(RemoteConnector):
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        lmcache_config: Optional[LMCacheEngineConfig],
+        plugin_name: Optional[str] = None,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        try:
+            # Third Party
+            from mooncake.store import (
+                MooncakeDistributedStore,
+                ReplicateConfig,
+            )
+        except ImportError as e:
+            raise ImportError(
+                "Please install mooncake by following the instructions at "
+                "https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md "  # noqa: E501
+                "to run vLLM with MooncakeConnector."
+            ) from e
+
+        try:
+            self.store = MooncakeDistributedStore()
+            config_file_path = os.getenv("MOONCAKE_CONFIG_PATH")
+            if config_file_path is not None:
+                self.config = MooncakeStoreConfig.from_file(config_file_path)
+            elif lmcache_config is not None:
+                self.config = MooncakeStoreConfig.load_from_lmcache_config(
+                    lmcache_config
+                )
+            else:
+                raise ValueError("MOONCAKE_CONFIG_PATH/lmcache_config must be provided")
+
+            logger.info("Mooncake Configuration loaded. config: %s", self.config)
+
+            # Check if storage_root_dir exists and set env var
+            if self.config.storage_root_dir:
+                os.environ["MOONCAKE_STORAGE_ROOT_DIR"] = self.config.storage_root_dir
+                logger.info(
+                    "Set MOONCAKE_STORAGE_ROOT_DIR to: %s",
+                    self.config.storage_root_dir,
+                )
+
+            logger.info(
+                "Setting up Mooncake store with setup_config: %s",
+                _sanitize_setup_config(self.config.setup_config),
+            )
+
+            try:
+                numa_mapping = getattr(
+                    local_cpu_backend.memory_allocator, "numa_mapping", None
+                )
+                if numa_mapping is None and lmcache_config is not None:
+                    numa_mapping = NUMADetector.get_numa_mapping(lmcache_config)
+
+                if numa_mapping:
+                    current_device_id = torch_dev.current_device()
+                    gpu_to_numa = getattr(numa_mapping, "gpu_to_numa_mapping", {})
+                    numa_id = gpu_to_numa.get(current_device_id)
+                    logger.info(
+                        f"NUMA mapping detected (pre-Mooncake setup): {gpu_to_numa}"
+                    )
+                    try:
+                        # Third Party
+                        from mooncake.store import bind_to_numa_node
+
+                        if numa_id is not None:
+                            bind_to_numa_node(numa_id)
+                            logger.info(
+                                f"GPU {current_device_id}, "
+                                f"NUMA node {numa_id} binding done"
+                            )
+                        else:
+                            logger.info(
+                                f"NUMA mapping not found for GPU {current_device_id}"
+                            )
+                    except ImportError:
+                        logger.warning(
+                            "unable to import bind_to_numa_node from mooncake.store"
+                        )
+                else:
+                    logger.info("NUMA mapping unavailable or disabled")
+            except Exception as e:
+                logger.warning(
+                    f"Failed to determine NUMA mapping before Mooncake setup: {e}"
+                )
+
+            setup_mooncake_store(self.store, self.config)
+            logger.info("Mooncake store setup completed successfully")
+
+        except ValueError as e:
+            logger.error("Configuration loading failed: %s", e)
+            raise
+        except Exception as exc:
+            logger.error("An error occurred while loading the configuration: %s", exc)
+            raise
+
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+        self.registered_buffer_ptr = None
+
+        # Initialize ReplicateConfig
+        self.replica_config = ReplicateConfig()
+        self.replica_config.replica_num = 1
+
+        # Set preferred_segment based on configuration
+        if self.config.prefer_local_alloc:
+            self.replica_config.preferred_segment = self.store.get_hostname()
+
+        # Register CPU buffer for zero-copy operations
+        self._register_cpu_buffer()
+
+        logger.info("MooncakeConnector initialized successfully.")
+
+    def _register_cpu_buffer(self):
+        """Register CPU buffer for zero-copy operations."""
+        try:
+            allocator = self.local_cpu_backend.memory_allocator
+            if hasattr(allocator, "pin_allocator") and hasattr(
+                allocator.pin_allocator, "buffer"
+            ):
+                buffer = allocator.pin_allocator.buffer
+                self.registered_buffer_ptr = buffer.data_ptr()
+                result = self.store.register_buffer(buffer.data_ptr(), buffer.numel())
+                if result == 0:
+                    logger.info(
+                        f"Registered: {hex(buffer.data_ptr())}, {buffer.numel()} bytes"
+                    )
+                else:
+                    logger.warning(f"Buffer registration failed: error={result}")
+                    self.registered_buffer_ptr = None
+            else:
+                self.registered_buffer_ptr = None
+        except Exception as e:
+            logger.error(f"Buffer registration error: {e}")
+            self.registered_buffer_ptr = None
+
+    def _unregister_cpu_buffer(self):
+        """Unregister CPU buffer."""
+        if self.registered_buffer_ptr is not None:
+            result = self.store.unregister_buffer(self.registered_buffer_ptr)
+            if result == 0:
+                logger.info(f"Unregistered buffer: {hex(self.registered_buffer_ptr)}")
+            else:
+                logger.warning(f"Buffer unregistration failed: error={result}")
+            self.registered_buffer_ptr = None
+
+    def support_batched_get(self) -> bool:
+        """
+        Check if the connector supports batched get
+
+        Returns:
+            True if batched get is supported, False otherwise
+        """
+        return True
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return self.store.is_exist(key.to_string())
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return self.store.is_exist(key.to_string())
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """
+        Batch get operation - the only supported get method.
+        Uses batch_get_into (with metadata) or batch_get_buffer (without metadata).
+        """
+        if not keys:
+            return []
+
+        # Check if we have metadata for zero-copy operations
+        if self.save_chunk_meta:
+            # Use legacy mode with metadata stored in remote
+            return await self._batch_get_buffer(keys)
+        else:
+            # Use optimized mode with local metadata
+            return await self._batch_get_into(keys)
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        num_hit_counts = 0
+        for key in keys:
+            if not self.store.is_exist(key.to_string()):
+                break
+            num_hit_counts += 1
+        return num_hit_counts
+
+    async def _batch_get_into(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """
+        Zero-copy batch get using batch_get_into when metadata is available locally.
+        This is used when save_chunk_meta=False (metadata not stored remotely).
+        """
+        if not self.meta_shapes or not self.meta_dtypes or not self.meta_fmt:
+            logger.error(
+                f"Metadata required for batch_get_into but not available: "
+                f"meta_shapes={self.meta_shapes}, "
+                f"meta_dtypes={self.meta_dtypes}, "
+                f"meta_fmt={self.meta_fmt}"
+            )
+            return [None] * len(keys)
+
+        logger.debug(f"Using batch_get_into for {len(keys)} keys (zero-copy mode)")
+
+        # Reserve a buffer for every requested chunk
+        memory_objs: list[Optional[MemoryObj]] = []
+        valid_idx: list[int] = []
+
+        key_strs: list[str] = []
+        buffer_ptrs: list[int] = []
+        buffer_sizes: list[int] = []
+
+        for i, _ in enumerate(keys):
+            obj = self.local_cpu_backend.allocate(
+                self.meta_shapes, self.meta_dtypes, self.meta_fmt
+            )
+            memory_objs.append(obj)
+            if obj is not None and obj.raw_tensor is not None:
+                valid_idx.append(i)
+
+                # Prepare the argument lists for the C++ call
+                key_strs.append(keys[i].to_string())
+                buffer_ptrs.append(obj.data_ptr)
+                buffer_sizes.append(obj.get_size())
+
+        if not valid_idx:
+            logger.warning("Batch-get aborted: unable to allocate any buffers.")
+            return [None] * len(keys)
+
+        try:
+            # Single RPC call for multiple chunks
+            logger.debug(f"Calling batch_get_into with {len(key_strs)} keys")
+            bytes_read_list = await asyncio.to_thread(
+                self.store.batch_get_into, key_strs, buffer_ptrs, buffer_sizes
+            )
+            logger.debug(f"batch_get_into returned: {bytes_read_list}")
+
+            # Assemble the final result list
+            results: list[Optional[MemoryObj]] = [None] * len(keys)
+
+            for i, n_read in zip(valid_idx, bytes_read_list, strict=False):
+                if n_read <= 0:
+                    logger.warning(
+                        f"batch_get_into failed for key {keys[i]} (code={n_read})"
+                    )
+                    memory_objs[i].ref_count_down()  # type: ignore
+                    continue
+
+                try:
+                    results[i] = self.reshape_partial_chunk(
+                        memory_objs[i],  # type: ignore
+                        n_read,
+                    )
+                except Exception as exc:
+                    logger.error(f"Reshape failed for key {keys[i]}: {exc}")
+                    memory_objs[i].ref_count_down()  # type: ignore
+
+            return results
+
+        except Exception as exc:
+            logger.error(f"batch_get_into threw exception: {str(exc)}")
+            # Release any buffers we successfully allocated
+            for i in valid_idx:
+                memory_objs[i].ref_count_down()  # type: ignore
+            return [None] * len(keys)
+
+    async def _batch_get_buffer(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """
+        Batch get using batch_get_buffer when metadata is stored remotely.
+        This is used when save_chunk_meta=True (metadata stored with data).
+        """
+        key_strs = [key.to_string() for key in keys]
+
+        try:
+            buffers = await asyncio.to_thread(self.store.batch_get_buffer, key_strs)
+        except Exception as e:
+            logger.error(f"batch_get_buffer failed: {str(e)}")
+            return [None] * len(keys)
+
+        results: list[Optional[MemoryObj]] = []
+        for i, buffer in enumerate(buffers):
+            if buffer is None:
+                logger.warning(f"Buffer {i} is None for key {key_strs[i]}")
+                results.append(None)
+                continue
+            try:
+                memory_obj = self._process_buffer_with_metadata(buffer)
+                results.append(memory_obj)
+            except Exception as e:
+                logger.error(
+                    f"Failed to process buffer {i} for key {key_strs[i]}: {str(e)}"
+                )
+                results.append(None)
+        return results
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """
+        Single get method - NOT SUPPORTED.
+        Use batched_get instead for all operations.
+        """
+        logger.error("Single get operation is not supported. Use batched_get instead.")
+        raise NotImplementedError(
+            "Single get is not supported. Use batched_get([key]) instead."
+        )
+
+    def _process_buffer_with_metadata(self, buffer: bytes) -> Optional[MemoryObj]:
+        """
+        Process buffer that contains metadata + data.
+        Used when save_chunk_meta=True (metadata stored remotely).
+        """
+        retrieved_view = memoryview(buffer)
+        metadata_bytes = retrieved_view[: self.remote_metadata_bytes]
+        if metadata_bytes is None or len(metadata_bytes) != self.remote_metadata_bytes:
+            return None
+
+        metadata = RemoteMetadata.deserialize(metadata_bytes)
+
+        memory_obj = self.local_cpu_backend.allocate(
+            metadata.shapes,
+            metadata.dtypes,
+            metadata.fmt,
+        )
+        assert len(retrieved_view) == metadata.length + self.remote_metadata_bytes
+
+        if memory_obj is None:
+            logger.warning("Failed to allocate memory during remote receive")
+            return None
+
+        if memory_obj.raw_tensor is not None:
+            temp_tensor = torch.frombuffer(
+                buffer,
+                dtype=torch.uint8,
+                offset=self.remote_metadata_bytes,
+                count=metadata.length,
+            )
+
+            memory_obj.raw_tensor.copy_(temp_tensor)
+            return memory_obj
+        else:
+            return None
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """
+        Put operation with metadata-consistent handling.
+        Uses put_from (without metadata) or
+        put_parts (with metadata) to match get behavior.
+        """
+        key_str = key.to_string()
+
+        # Check metadata handling mode to match get behavior
+        if self.save_chunk_meta:
+            # Use put_parts with metadata stored remotely
+            await self._put_with_metadata(key_str, memory_obj)
+        else:
+            # Use put_from without metadata (zero-copy)
+            await self._put_without_metadata(key_str, memory_obj)
+
+    def support_batched_put(self) -> bool:
+        return True
+
+    async def batched_put(
+        self,
+        keys: List[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+    ):
+        """
+        Batched put with clear split by metadata mode.
+        - save_chunk_meta False: use Mooncake's batch_put_from (zero-copy).
+        - save_chunk_meta True: no batch API; fall back to sequential put_parts.
+        """
+        if not keys:
+            return
+
+        if self.save_chunk_meta:
+            await self._batched_put_with_metadata(keys, memory_objs)
+        else:
+            await self._batched_put_zero_copy(keys, memory_objs)
+
+    async def _batched_put_zero_copy(
+        self,
+        keys: List[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+    ) -> None:
+        key_strs = [k.to_string() for k in keys]
+        buffer_ptrs: list[int] = []
+        buffer_sizes: list[int] = []
+        for obj in memory_objs:
+            assert obj.raw_tensor is not None
+            buffer_ptrs.append(obj.data_ptr)
+            buffer_sizes.append(obj.get_size())
+
+        try:
+            await asyncio.wait_for(
+                asyncio.to_thread(
+                    self.store.batch_put_from,
+                    key_strs,
+                    buffer_ptrs,
+                    buffer_sizes,
+                    self.replica_config,
+                ),
+                timeout=self.config.transfer_timeout,
+            )
+        except asyncio.TimeoutError:
+            logger.warning(
+                "Timeout during batch_put_from; some decoders may redo prefill."
+            )
+
+    async def _batched_put_with_metadata(
+        self,
+        keys: List[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+    ) -> None:
+        for key, obj in zip(keys, memory_objs, strict=False):
+            await self._put_with_metadata(key.to_string(), obj)
+
+    async def _put_without_metadata(self, key_str: str, memory_obj: MemoryObj):
+        """
+        Zero-copy put using put_from when metadata is not stored remotely.
+        This is used when save_chunk_meta=False (matches _batch_get_into).
+        """
+        try:
+            assert memory_obj.raw_tensor is not None
+            buffer_ptr = memory_obj.data_ptr
+            buffer_size = memory_obj.get_size()
+
+            await asyncio.wait_for(
+                asyncio.to_thread(
+                    self.store.put_from,
+                    key_str,
+                    buffer_ptr,
+                    buffer_size,
+                    self.replica_config,
+                ),
+                timeout=self.config.transfer_timeout,
+            )
+        except asyncio.TimeoutError:
+            logger.warning(
+                f"Timeout when putting key {key_str} using put_from. "
+                "Decode instance may redo prefill."
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to put key {key_str} using put_from: "
+                f"{type(e).__name__}: {str(e)}"
+            )
+            raise
+
+    async def _put_with_metadata(self, key_str: str, memory_obj: MemoryObj):
+        """
+        Put using put_parts when metadata is stored remotely.
+        This is used when save_chunk_meta=True (matches _batch_get_buffer).
+        """
+        try:
+            # Serialize data and metadata
+            kv_bytes = memory_obj.byte_array
+            kv_shapes = memory_obj.get_shapes()
+            kv_dtypes = memory_obj.get_dtypes()
+            memory_format = memory_obj.get_memory_format()
+
+            metadata_bytes = RemoteMetadata(
+                len(kv_bytes), kv_shapes, kv_dtypes, memory_format
+            ).serialize()
+            assert len(metadata_bytes) == self.remote_metadata_bytes
+
+            await asyncio.wait_for(
+                asyncio.to_thread(
+                    self.store.put_parts, key_str, metadata_bytes, kv_bytes
+                ),
+                timeout=self.config.transfer_timeout,
+            )
+        except asyncio.TimeoutError:
+            logger.warning(
+                f"Timeout when putting key {key_str} using put_parts. "
+                "Decode instance may redo prefill."
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to put key {key_str} using put_parts: "
+                f"{type(e).__name__}: {str(e)}"
+            )
+            raise
+
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        # Unregister buffer before closing the store
+        self._unregister_cpu_buffer()
+
+        self.store.close()
+        logger.info("Closed the mooncake store connection")
diff --git a/lmcache/v1/storage_backend/connector/redis_adapter.py b/lmcache/v1/storage_backend/connector/redis_adapter.py
new file mode 100644
index 0000000..32ed99c
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/redis_adapter.py
@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Dict, List, Tuple
+import os
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class RESPConnectorAdapter(ConnectorAdapter):
+    """Adapter for RESP connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("resp://")
+
+    def can_parse(self, url: str) -> bool:
+        return url.startswith(self.schema)
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .redis_connector import RESPConnector
+
+        config = context.config
+        assert config is not None
+
+        # Get config from extra_config with defaults
+        extra_config = config.extra_config if config.extra_config is not None else {}
+
+        # Validate that save_chunk_meta and save_unfull_chunk are False for RESP
+        self.save_chunk_meta = bool(extra_config.get("save_chunk_meta", False))
+        assert not self.save_chunk_meta, "save_chunk_meta must be False for RESP"
+
+        assert not config.save_unfull_chunk, "save_unfull_chunk must be False for RESP"
+
+        # Get number of threads for RESP connection pool (default is 8)
+        self.resp_num_threads = int(extra_config.get("resp_num_threads", 8))
+
+        # Config/CLI args take precedence over environment variables,
+        # which serve as defaults. This keeps secrets out of logged
+        # config while allowing explicit overrides.
+        cfg_username = str(extra_config.get("username", ""))
+        cfg_password = str(extra_config.get("password", ""))
+        username = cfg_username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+        password = cfg_password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+        parsed_url = parse_remote_url(context.url)
+
+        # Config/URL values take precedence; env vars are fallback
+        host = parsed_url.host or os.environ.get("LMCACHE_RESP_HOST", "")
+        port = (
+            parsed_url.port
+            if parsed_url.port
+            else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+        )
+
+        logger.info("Creating RESP connector for %s:%d", host, port)
+        return RESPConnector(
+            host=host,
+            port=port,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            num_threads=self.resp_num_threads,
+            username=username,
+            password=password,
+        )
+
+
+class RedisConnectorAdapter(ConnectorAdapter):
+    """Adapter for Redis connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("redis://")
+
+    def can_parse(self, url: str) -> bool:
+        return url.startswith((self.schema, "rediss://", "unix://", "plugin://redis"))
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .redis_connector import RedisConnector
+
+        url = context.url
+        if url.startswith("plugin://redis"):
+            extra_config: Dict[str, Any] = {}
+            remote_url = None
+            if context.config is not None:
+                extra_config = (
+                    context.config.extra_config
+                    if context.config.extra_config is not None
+                    else {}
+                )
+                remote_url = context.config.remote_url
+            cfg_redis_url = extra_config.get(
+                "remote_storage_plugin.redis.redis_url"
+            ) or extra_config.get("redis_url")
+            url = cfg_redis_url or remote_url or "redis://localhost:6379"
+
+        logger.info(f"Creating Redis connector for URL: {url}")
+        return RedisConnector(
+            url=url,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+        )
+
+
+class RedisSentinelConnectorAdapter(ConnectorAdapter):
+    """Adapter for Redis Sentinel connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("redis-sentinel://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .redis_connector import RedisSentinelConnector
+
+        logger.info(f"Creating Redis Sentinel connector for URL: {context.url}")
+        url = context.url[len(self.schema) :]
+
+        # Parse username and password
+        username: str = ""
+        password: str = ""
+        if "@" in url:
+            auth, url = url.split("@", 1)
+            if ":" in auth:
+                username, password = auth.split(":", 1)
+            else:
+                username = auth
+
+        # Parse host and port
+        hosts_and_ports: List[Tuple[str, int]] = []
+        assert self.schema is not None
+        for sub_url in url.split(","):
+            if not sub_url.startswith(self.schema):
+                sub_url = self.schema + sub_url
+
+            parsed_url = parse_remote_url(sub_url)
+            hosts_and_ports.append((parsed_url.host, parsed_url.port))
+
+        return RedisSentinelConnector(
+            hosts_and_ports=hosts_and_ports,
+            username=username,
+            password=password,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+        )
+
+
+class RedisClusterConnectorAdapter(ConnectorAdapter):
+    """Adapter for Redis Cluster connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("redis-cluster://")
+
+    def can_parse(self, url: str) -> bool:
+        return url.startswith(self.schema)
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .redis_connector import RedisClusterConnector
+
+        logger.info(f"Creating Redis Cluster connector for URL: {context.url}")
+        url = context.url[len(self.schema) :]
+
+        # Parse username and password
+        username: str = ""
+        password: str = ""
+        if "@" in url:
+            auth, url = url.split("@", 1)
+            if ":" in auth:
+                username, password = auth.split(":", 1)
+            else:
+                username = auth
+
+        # Parse host and port
+        hosts_and_ports: List[Tuple[str, int]] = []
+        assert self.schema is not None
+        for sub_url in url.split(","):
+            if not sub_url.startswith(self.schema):
+                sub_url = self.schema + sub_url
+
+            parsed_url = parse_remote_url(sub_url)
+            hosts_and_ports.append((parsed_url.host, parsed_url.port))
+
+        return RedisClusterConnector(
+            hosts_and_ports=hosts_and_ports,
+            username=username,
+            password=password,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+        )
diff --git a/lmcache/v1/storage_backend/connector/redis_connector.py b/lmcache/v1/storage_backend/connector/redis_connector.py
new file mode 100644
index 0000000..e0c2c94
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/redis_connector.py
@@ -0,0 +1,828 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from enum import IntEnum, auto
+from typing import List, Optional, Tuple, no_type_check
+import asyncio
+import inspect
+import os
+
+# Third Party
+from redis.asyncio.cluster import ClusterNode, RedisCluster
+import redis.asyncio as redis
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.native_clients.resp_client import RESPClient
+
+logger = init_logger(__name__)
+
+# TODO(Jiayi): Use `redis.asyncio`
+# NOTE(Jiayi): `redis-py` supports async operations, but data copy
+# cannot be avoided. `hiredis` is more lower-level but asyncio is
+# not supported.
+
+
+class Priorities(IntEnum):
+    PEEK = auto()
+    PREFETCH = auto()
+    GET = auto()
+    PUT = auto()
+
+
+class RESPConnector(RemoteConnector):
+    """
+    The remote url should start with "resp://" and only have one host-port pair
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        num_threads: int = 8,
+        username: str = "",
+        password: str = "",
+    ):
+        # this gives us access to self.full_chunk_size_bytes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        self.host = host
+        self.port = port
+        self.num_threads = num_threads
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.client = RESPClient(host, port, num_threads, loop, username, password)
+        self.pq_executor = AsyncPQExecutor(loop)
+
+    async def _exists(self, key: CacheEngineKey) -> bool:
+        return await self.client.exists(key.to_string())
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return await self.pq_executor.submit_job(
+            self._exists, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return self.client.exists_sync(key.to_string())
+
+    async def _get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+        memory_obj = self.local_cpu_backend.allocate(
+            self.meta_shapes,
+            self.meta_dtypes,
+            self.meta_fmt,
+        )
+
+        # byte array view of tensor
+        recv_buf = memory_obj.byte_array
+        if not isinstance(recv_buf, memoryview):
+            recv_buf = memoryview(recv_buf)
+        await self.client.get(key_str, recv_buf)
+        return memory_obj
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._get, key=key, priority=Priorities.GET
+        )
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        key_str = key.to_string()
+        send_buf = memory_obj.byte_array
+        if not isinstance(send_buf, memoryview):
+            send_buf = memoryview(send_buf)
+        await self.client.set(key_str, send_buf)
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        await self.pq_executor.submit_job(
+            self._put, key=key, memory_obj=memory_obj, priority=Priorities.PUT
+        )
+
+    def support_batched_put(self) -> bool:
+        return True
+
+    async def _batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        key_strs = [key.to_string() for key in keys]
+        send_bufs = [
+            memory_obj.byte_array
+            if isinstance(memory_obj.byte_array, memoryview)
+            else memoryview(memory_obj.byte_array)
+            for memory_obj in memory_objs
+        ]
+        await self.client.batch_set(key_strs, send_bufs)
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        await self.pq_executor.submit_job(
+            self._batched_put,
+            keys=keys,
+            memory_objs=memory_objs,
+            priority=Priorities.PUT,
+        )
+
+    def support_batched_get(self) -> bool:
+        return True
+
+    async def _batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        key_strs = [key.to_string() for key in keys]
+        memory_objs = [
+            self.local_cpu_backend.allocate(
+                self.meta_shapes,
+                self.meta_dtypes,
+                self.meta_fmt,
+            )
+            for _ in keys
+        ]
+        recv_bufs = [
+            memory_obj.byte_array
+            if isinstance(memory_obj.byte_array, memoryview)
+            else memoryview(memory_obj.byte_array)
+            for memory_obj in memory_objs
+        ]
+        await self.client.batch_get(key_strs, recv_bufs)
+        return memory_objs
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        return await self.pq_executor.submit_job(
+            self._batched_get, keys=keys, priority=Priorities.GET
+        )
+
+    def support_batched_contains(self) -> bool:
+        return True
+
+    def batched_contains(self, keys: List[CacheEngineKey]) -> int:
+        """Synchronous batched contains - checks consecutive prefix existence."""
+        key_strs = [key.to_string() for key in keys]
+        results = self.client.batch_exists_sync(key_strs)
+        count = 0
+        # we only want the prefixes
+        for result in results:
+            if not result:
+                return count
+            count += 1
+        return count
+
+    async def _batched_async_contains(self, keys: List[CacheEngineKey]) -> int:
+        key_strs = [key.to_string() for key in keys]
+        results = await self.client.batch_exists(key_strs)
+        count = 0
+        # we only want the prefixes
+        for result in results:
+            if not result:
+                return count
+            count += 1
+        return count
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Check how many keys exist in file system in batch
+
+        Args:
+            lookup_id: Identifier for this lookup operation
+            keys: List of keys to check
+            pin: Whether to pin the keys (not used in FS connector)
+
+        Returns:
+            Number of consecutive keys that exist, starting from the first key
+        """
+        # prefetch priority
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains, keys=keys, priority=Priorities.PREFETCH
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        # prefetch priority
+        return await self.pq_executor.submit_job(
+            self._batched_get, keys=keys, priority=Priorities.PREFETCH
+        )
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        await self.pq_executor.shutdown(wait=True)
+        self.client.close()
+        logger.info("Closed the RESP connection")
+
+
+class RedisConnector(RemoteConnector):
+    """
+    The remote url should start with "redis://" and only have one host-port pair
+    """
+
+    def __init__(
+        self,
+        url: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        # set a large max
+        self.max_connections = 150
+        # redis will crash if we have more than max_connections connections
+        self.sem = asyncio.Semaphore(self.max_connections)
+        self.pool = redis.ConnectionPool.from_url(
+            url, max_connections=self.max_connections
+        )
+        self.connection = redis.Redis.from_pool(self.pool)
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.pq_executor = AsyncPQExecutor(loop)
+
+    async def _exists(self, key: CacheEngineKey) -> bool:
+        async with self.sem:
+            return bool(await self.connection.exists(key.to_string() + "metadata"))
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return await self.pq_executor.submit_job(
+            self._exists, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        future = asyncio.run_coroutine_threadsafe(self.exists(key), self.loop)
+        return bool(future.result())
+
+    async def _get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+        async with self.sem:
+            metadata_bytes = await self.connection.get(key_str + "metadata")
+
+            if metadata_bytes is None:
+                return None
+
+            assert not inspect.isawaitable(metadata_bytes)
+
+            metadata = RemoteMetadata.deserialize(memoryview(metadata_bytes))
+
+            memory_obj = self.local_cpu_backend.allocate(
+                metadata.shapes,
+                metadata.dtypes,
+                metadata.fmt,
+            )
+            if memory_obj is None:
+                logger.warning("Failed to allocate memory during remote receive")
+                return None
+
+            # TODO(Jiayi): Find a way to do `get` inplace
+            kv_bytes = await self.connection.get(key_str + "kv_bytes")
+        assert not inspect.isawaitable(kv_bytes)
+
+        if kv_bytes is None:
+            # TODO (Jiayi): We might need a way to better handle
+            # consistency issues.
+            # TODO (Jiayi): A better way is to aggregate metadata
+            # and kv cache in one key.
+            logger.warning(
+                "Key exists but KV cache does not exist."
+                "Might happen when the cache is evicted by redis."
+            )
+            async with self.sem:
+                await self.connection.delete(key_str + "metadata")
+            return None
+
+        if isinstance(memory_obj.byte_array, memoryview):
+            view = memory_obj.byte_array
+            if view.format == "<B":
+                view = view.cast("B")
+        else:
+            view = memoryview(memory_obj.byte_array)
+
+        if isinstance(kv_bytes, (bytes, bytearray)):
+            view[: metadata.length] = kv_bytes
+        elif isinstance(kv_bytes, str):
+            converted = kv_bytes.encode("utf-8")
+            view[: metadata.length] = converted
+        else:
+            converted = bytes(kv_bytes)
+            view[: metadata.length] = converted
+
+        return memory_obj
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._get, key=key, priority=Priorities.GET
+        )
+
+    def support_batched_put(self) -> bool:
+        return True
+
+    async def _batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        # calling self.put will create a circular dependency
+        await asyncio.gather(
+            *(
+                self._put(key, memory_obj)
+                for key, memory_obj in zip(keys, memory_objs, strict=False)
+            )
+        )
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        await self.pq_executor.submit_job(
+            self._batched_put,
+            keys=keys,
+            memory_objs=memory_objs,
+            priority=Priorities.PUT,
+        )
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        # TODO(Jiayi): The following code is ugly.
+        # Please use a function like `memory_obj.to_meta()`.
+        kv_bytes = memory_obj.byte_array
+        kv_shapes = memory_obj.get_shapes()
+        kv_dtypes = memory_obj.get_dtypes()
+        memory_format = memory_obj.get_memory_format()
+
+        metadata_bytes = RemoteMetadata(
+            len(kv_bytes), kv_shapes, kv_dtypes, memory_format
+        ).serialize()
+
+        key_str = key.to_string()
+        # kv bytes needs to be set first to avoid race condition
+        async with self.sem:
+            await self.connection.set(key_str + "kv_bytes", kv_bytes)
+            await self.connection.set(key_str + "metadata", metadata_bytes)
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        await self.pq_executor.submit_job(
+            self._put, key=key, memory_obj=memory_obj, priority=Priorities.PUT
+        )
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        await self.pq_executor.shutdown(wait=True)
+        await self.connection.close()
+        logger.info("Closed the redis connection")
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def _batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        num_hit_counts = 0
+        for key in keys:
+            async with self.sem:
+                if not await self.connection.exists(key.to_string() + "metadata"):
+                    return num_hit_counts
+            num_hit_counts += 1
+        return num_hit_counts
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains,
+            lookup_id=lookup_id,
+            keys=keys,
+            pin=pin,
+            priority=Priorities.PEEK,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def _batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        # calling self.get will create a circular dependency
+        results = await asyncio.gather(*(self._get(key) for key in keys))
+        return [r for r in results if r is not None]
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._batched_get_non_blocking,
+            lookup_id=lookup_id,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+
+class RedisSentinelConnector(RemoteConnector):
+    """
+    Uses redis.Sentinel to connect to a Redis cluster.
+    The hosts are specified in the config file, started with "redis-sentinel://"
+    and separated by commas.
+
+    Example:
+        remote_url: "redis-sentinel://localhost:26379,localhost:26380,localhost:26381"
+
+    Extra environment variables:
+    - REDIS_SERVICE_NAME (required) -- service name for redis.
+    - REDIS_TIMEOUT (optional) -- Timeout in seconds, default is 1 if not set
+    """
+
+    ENV_REDIS_TIMEOUT = "REDIS_TIMEOUT"
+    ENV_REDIS_SERVICE_NAME = "REDIS_SERVICE_NAME"
+
+    def __init__(
+        self,
+        hosts_and_ports: List[Tuple[str, int]],
+        username: str,
+        password: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        # Get service name
+        match os.environ.get(self.ENV_REDIS_SERVICE_NAME):
+            case None:
+                logger.warning(
+                    f"Environment variable {self.ENV_REDIS_SERVICE_NAME} is "
+                    f"not found, using default value 'redismaster'"
+                )
+                service_name = "redismaster"
+            case value:
+                service_name = value
+
+        timeout: float = -1000.0
+
+        # Get timeout
+        match os.environ.get(self.ENV_REDIS_TIMEOUT):
+            case None:
+                timeout = 1
+            case value:
+                timeout = float(value)
+
+        logger.info(f"Host and ports: {hosts_and_ports}")
+        self.sentinel = redis.Sentinel(hosts_and_ports, socket_timeout=timeout)
+        self.master = self.sentinel.master_for(
+            service_name, socket_timeout=timeout, username=username, password=password
+        )
+        self.slave = self.sentinel.slave_for(
+            service_name, socket_timeout=timeout, username=username, password=password
+        )
+
+        self.local_cpu_backend = local_cpu_backend
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return bool(self.slave.exists(key.to_string() + "metadata"))
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return bool(self.slave.exists(key.to_string() + "metadata"))
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+        metadata_bytes = self.slave.get(key_str + "metadata")
+
+        if metadata_bytes is None:
+            return None
+
+        assert not inspect.isawaitable(metadata_bytes)
+
+        metadata = RemoteMetadata.deserialize(metadata_bytes)
+
+        memory_obj = self.local_cpu_backend.allocate(
+            metadata.shapes,
+            metadata.dtypes,
+            metadata.fmt,
+        )
+        if memory_obj is None:
+            logger.warning("Failed to allocate memory during remote receive")
+            return None
+
+        # TODO(Jiayi): Find a way to do `get` inplace
+        kv_bytes = self.slave.get(key_str + "kv_bytes")
+
+        assert not inspect.isawaitable(kv_bytes)
+
+        if kv_bytes is None:
+            # TODO (Jiayi): We might need a way to better handle
+            # consistency issues.
+            # TODO (Jiayi): A background sweeper might be better
+            # for the sake of performance.
+            logger.warning(
+                "Key exists but KV cache does not exist."
+                "Might happen when the cache is evicted by redis."
+            )
+            self.master.delete(key_str + "metadata")
+            return None
+
+        if isinstance(memory_obj.byte_array, memoryview):
+            view = memory_obj.byte_array
+            if view.format == "<B":
+                view = view.cast("B")
+        else:
+            view = memoryview(memory_obj.byte_array)
+
+        if isinstance(kv_bytes, (bytes, bytearray)):
+            view[0 : metadata.length] = kv_bytes
+        elif isinstance(kv_bytes, str):
+            converted = kv_bytes.encode("utf-8")
+            view[0 : metadata.length] = converted
+        else:
+            converted = bytes(kv_bytes)
+            view[0 : metadata.length] = converted
+
+        return memory_obj
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        # TODO(Jiayi): The following code is ugly.
+        # Please use a function like `memory_obj.to_meta()`.
+        kv_bytes = memory_obj.byte_array
+        kv_shapes = memory_obj.get_shapes()
+        kv_dtypes = memory_obj.get_dtypes()
+        memory_format = memory_obj.get_memory_format()
+
+        metadata_bytes = RemoteMetadata(
+            len(kv_bytes), kv_shapes, kv_dtypes, memory_format
+        ).serialize()
+
+        key_str = key.to_string()
+        # kv bytes needs to be set first to avoid race condition
+        self.master.set(key_str + "kv_bytes", kv_bytes)
+        self.master.set(key_str + "metadata", metadata_bytes)
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        self.master.close()
+        self.slave.close()
+
+
+class RedisClusterConnector(RemoteConnector):
+    """
+    The remote url starts with "redis-cluster:// and can include one or
+    multiple hosts:ports, separated by commas.
+
+    Example:
+        remote_url: "redis-cluster://host1:7000,host2:7000,host3:7000"
+
+    Extra environment variables:
+    - REDIS_TIMEOUT (optional) -- Timeout in seconds, default is 1 if not set
+    """
+
+    def __init__(
+        self,
+        hosts_and_ports: List[Tuple[str, int]],
+        username: str,
+        password: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        # Convert hosts_and_ports to startup_nodes format expected by RedisCluster
+        startup_nodes = [ClusterNode(h, p) for (h, p) in hosts_and_ports]
+
+        # set a large max
+        self.max_connections = 150
+        # redis will crash if we have more than max_connections connections
+        self.sem = asyncio.Semaphore(self.max_connections)
+
+        # Initialize cluster connection
+        self.cluster = RedisCluster(
+            startup_nodes=startup_nodes,
+            username=username,
+            password=password,
+            max_connections=self.max_connections,
+            decode_responses=False,
+        )
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.pq_executor = AsyncPQExecutor(loop)
+
+    async def _exists(self, key: CacheEngineKey) -> bool:
+        async with self.sem:
+            return bool(await self.cluster.exists(key.to_string() + "metadata"))
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return await self.pq_executor.submit_job(
+            self._exists, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        future = asyncio.run_coroutine_threadsafe(self.exists(key), self.loop)
+        return bool(future.result())
+
+    async def _get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        key_str = key.to_string()
+        async with self.sem:
+            metadata_bytes = await self.cluster.get(key_str + "metadata")
+
+            if metadata_bytes is None:
+                return None
+
+            assert not inspect.isawaitable(metadata_bytes)
+
+            metadata = RemoteMetadata.deserialize(memoryview(metadata_bytes))
+
+            memory_obj = self.local_cpu_backend.allocate(
+                metadata.shapes,
+                metadata.dtypes,
+                metadata.fmt,
+            )
+            if memory_obj is None:
+                logger.warning("Failed to allocate memory during remote receive")
+                return None
+
+            # TODO(Jiayi): Find a way to do `get` inplace
+            kv_bytes = await self.cluster.get(key_str + "kv_bytes")
+
+        assert not inspect.isawaitable(kv_bytes)
+
+        if kv_bytes is None:
+            # TODO (Jiayi): We might need a way to better handle
+            # consistency issues.
+            # TODO (Jiayi): A better way is to aggregate metadata
+            # and kv cache in one key.
+            logger.warning(
+                "Key exists but KV cache does not exist."
+                "Might happen when the cache is evicted by redis."
+            )
+            async with self.sem:
+                await self.cluster.delete(key_str + "metadata")
+            return None
+
+        if isinstance(memory_obj.byte_array, memoryview):
+            view = memory_obj.byte_array
+            if view.format == "<B":
+                view = view.cast("B")
+        else:
+            view = memoryview(memory_obj.byte_array)
+
+        if isinstance(kv_bytes, (bytes, bytearray)):
+            view[: metadata.length] = kv_bytes
+        elif isinstance(kv_bytes, str):
+            converted = kv_bytes.encode("utf-8")
+            view[: metadata.length] = converted
+        else:
+            converted = bytes(kv_bytes)
+            view[: metadata.length] = converted
+
+        return memory_obj
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._get, key=key, priority=Priorities.GET
+        )
+
+    def support_batched_put(self) -> bool:
+        return True
+
+    async def _batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        # calling self.put will create a circular dependency
+        await asyncio.gather(
+            *(
+                self._put(key, memory_obj)
+                for key, memory_obj in zip(keys, memory_objs, strict=False)
+            )
+        )
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        await self.pq_executor.submit_job(
+            self._batched_put,
+            keys=keys,
+            memory_objs=memory_objs,
+            priority=Priorities.PUT,
+        )
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        # TODO(Jiayi): The following code is ugly.
+        # Please use a function like `memory_obj.to_meta()`.
+        kv_bytes = memory_obj.byte_array
+        kv_shapes = memory_obj.get_shapes()
+        kv_dtypes = memory_obj.get_dtypes()
+        memory_format = memory_obj.get_memory_format()
+
+        metadata_bytes = RemoteMetadata(
+            len(kv_bytes), kv_shapes, kv_dtypes, memory_format
+        ).serialize()
+
+        key_str = key.to_string()
+        # kv bytes needs to be set first to avoid race condition
+        async with self.sem:
+            await self.cluster.set(key_str + "kv_bytes", kv_bytes)
+            await self.cluster.set(key_str + "metadata", metadata_bytes)
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        await self.pq_executor.submit_job(
+            self._put, key=key, memory_obj=memory_obj, priority=Priorities.PUT
+        )
+
+    # TODO
+    @no_type_check
+    async def list(self) -> List[str]:
+        pass
+
+    async def close(self):
+        await self.pq_executor.shutdown(wait=True)
+        await self.cluster.close()
+        logger.info("Closed the redis cluster connection")
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def _batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        num_hit_counts = 0
+        for key in keys:
+            async with self.sem:
+                if not await self.cluster.exists(key.to_string() + "metadata"):
+                    return num_hit_counts
+            num_hit_counts += 1
+        return num_hit_counts
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains,
+            lookup_id=lookup_id,
+            keys=keys,
+            pin=pin,
+            priority=Priorities.PEEK,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def _batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        # calling self.get will create a circular dependency
+        results = await asyncio.gather(*(self._get(key) for key in keys))
+        return [r for r in results if r is not None]
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._batched_get_non_blocking,
+            lookup_id=lookup_id,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
diff --git a/lmcache/v1/storage_backend/connector/s3_adapter.py b/lmcache/v1/storage_backend/connector/s3_adapter.py
new file mode 100644
index 0000000..45503fe
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/s3_adapter.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class S3ConnectorAdapter(ConnectorAdapter):
+    """Adapter for S3 Server connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("s3://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        # Local
+        from .s3_connector import S3Connector
+
+        config = context.config
+        assert config is not None
+
+        # Get config from extra_config with defaults
+        extra_config = config.extra_config if config.extra_config is not None else {}
+
+        self.save_chunk_meta = bool(extra_config.get("save_chunk_meta", False))
+        assert not self.save_chunk_meta, "save_chunk_meta must be False for S3"
+
+        self.s3_num_io_threads = int(extra_config.get("s3_num_io_threads", 64))
+        self.s3_prefer_http2 = bool(extra_config.get("s3_prefer_http2", True))
+        self.s3_region = extra_config.get("s3_region", None)
+        assert self.s3_region is not None, "s3_region is required"
+        self.s3_region = str(self.s3_region)
+        self.s3_enable_s3express = bool(extra_config.get("s3_enable_s3express", False))
+        self.disable_tls = bool(extra_config.get("disable_tls", False))
+        self.aws_access_key_id = extra_config.get("aws_access_key_id", None)
+        self.aws_secret_access_key = extra_config.get("aws_secret_access_key", None)
+        if context.metadata is None:
+            raise ValueError("metadata is required for S3Connector")
+
+        logger.info(f"Creating S3 connector for URL: {context.url}")
+
+        s3_endpoint = context.url
+
+        return S3Connector(
+            s3_endpoint=s3_endpoint,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            s3_num_io_threads=self.s3_num_io_threads,
+            s3_prefer_http2=self.s3_prefer_http2,
+            s3_region=self.s3_region,
+            s3_enable_s3express=self.s3_enable_s3express,
+            disable_tls=self.disable_tls,
+            aws_access_key_id=self.aws_access_key_id,
+            aws_secret_access_key=self.aws_secret_access_key,
+        )
diff --git a/lmcache/v1/storage_backend/connector/s3_connector.py b/lmcache/v1/storage_backend/connector/s3_connector.py
new file mode 100644
index 0000000..b859e27
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/s3_connector.py
@@ -0,0 +1,699 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from enum import IntEnum, auto
+from typing import List, Optional
+from urllib.parse import quote as url_quote
+import asyncio
+import ctypes
+
+# Third Party
+from awscrt import auth, io, s3
+from awscrt.http import HttpHeaders, HttpRequest
+from awscrt.io import ClientTlsContext, TlsConnectionOptions, TlsContextOptions
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+class Priorities(IntEnum):
+    PEEK = auto()
+    PREFETCH = auto()
+    GET = auto()
+    PUT = auto()
+
+
+# zero copy helper for S3 upload
+class MemoryViewStream:
+    def __init__(self, mv: bytes):
+        # casting does not copy
+        # we just get a uint8 view
+        self.mv = memoryview(mv).cast("B")
+        self.offset = 0
+
+    def read(self, size=None):
+        if size is None:
+            size = len(self.mv) - self.offset
+        if size < 0:
+            size = 0
+
+        end = min(self.offset + size, len(self.mv))
+        result = self.mv[self.offset : end]
+        self.offset = end
+        # CRT/Python accepts memoryview
+        return result
+
+    def seek(self, offset, whence=0):
+        if whence == 0:
+            self.offset = offset
+        elif whence == 1:
+            self.offset += offset
+        elif whence == 2:
+            self.offset = len(self.mv) + offset
+        return self.offset
+
+    def tell(self):
+        return self.offset
+
+    def __len__(self):
+        return len(self.mv)
+
+
+class S3Connector(RemoteConnector):
+    """
+    S3 remote connector
+    """
+
+    def __init__(
+        self,
+        s3_endpoint: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        s3_num_io_threads: int,
+        s3_prefer_http2: bool,
+        s3_region: str,
+        s3_enable_s3express: bool,
+        disable_tls: bool,
+        aws_access_key_id: Optional[str] = None,
+        aws_secret_access_key: Optional[str] = None,
+    ):
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        if not s3_endpoint.startswith("s3://"):
+            raise ValueError("S3 url must start with 's3://'")
+
+        self.s3_part_size = self.full_chunk_size_bytes
+
+        self.s3_endpoint = s3_endpoint.removeprefix("s3://")
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self.s3_num_io_threads = s3_num_io_threads
+        self.s3_prefer_http2 = s3_prefer_http2
+        self.s3_region = s3_region
+        self.s3_enable_s3express = s3_enable_s3express
+
+        event_loop_group = io.EventLoopGroup(s3_num_io_threads)
+        host_resolver = io.DefaultHostResolver(event_loop_group)
+        client_bootstrap = io.ClientBootstrap(event_loop_group, host_resolver)
+        if aws_access_key_id and aws_secret_access_key:
+            logger.info("Using explicit AWS credentials passed to S3Connector")
+            self.credentials_provider = auth.AwsCredentialsProvider.new_static(
+                aws_access_key_id,
+                aws_secret_access_key,
+            )
+        else:
+            logger.info(
+                "No credentials provider, trying to use credentials from environment"
+            )
+            self.credentials_provider = auth.AwsCredentialsProvider.new_default_chain(
+                client_bootstrap
+            )
+
+        tls_opts = None
+
+        if self.s3_prefer_http2:
+            # Use HTTP/2 multiplexing if possible.
+            tls_ctx = ClientTlsContext(TlsContextOptions())
+            tls_opts = TlsConnectionOptions(tls_ctx)
+            try:
+                tls_opts.set_alpn_list(["h2", "http/1.1"])
+            except Exception:
+                tls_opts = None
+
+        signing_config = None
+        if self.s3_enable_s3express:
+            signing_config = auth.AwsSigningConfig(
+                algorithm=auth.AwsSigningAlgorithm.V4_S3EXPRESS,
+                region=self.s3_region,
+                service="s3",
+                credentials_provider=self.credentials_provider,
+            )
+
+        # turn off TLS for non-AWS services
+        # regular and directory/express buckets both use TLS by default
+        turn_off_tls = (
+            s3.S3RequestTlsMode.DISABLED if disable_tls else s3.S3RequestTlsMode.ENABLED
+        )
+        logger.info("Initializing S3 client")
+        self.s3_client = s3.S3Client(
+            bootstrap=client_bootstrap,
+            region=s3_region,
+            enable_s3express=s3_enable_s3express,
+            tls_connection_options=tls_opts,
+            tls_mode=turn_off_tls,
+            signing_config=signing_config,
+        )
+
+        # TODO(Jiayi): We need to handle cache consistency issues in a systematic way
+        # across all connectors.
+        # We assume S3 cache is never evicted and read-only for now.
+        # the object size cache does not need protection because
+        # asyncio scheduling is cooperative and not preemptive
+        self.object_size_cache: dict[str, int] = {}
+
+        # Circuit breaker for connection failures
+        self.connection_failures = 0
+        self.max_connection_failures = 3
+        self.connection_disabled = False
+
+        self.pq_executor = AsyncPQExecutor(loop)
+
+    def _format_safe_path(self, key_str: str) -> str:
+        """
+        Generate a safe HTTP path for the S3 key.
+        Flattens the key by replacing slashes with underscores and URL-encodes
+        any special characters.
+        """
+        flat_key_str = key_str.replace("/", "_")
+        return "/" + url_quote(flat_key_str)
+
+    # TODO(Jiayi): optimize this with async
+    def _get_object_size(self, key_str: str) -> int:
+        headers = HttpHeaders()
+        headers.add("Host", self.s3_endpoint)
+        req = HttpRequest("HEAD", self._format_safe_path(key_str), headers)
+
+        got = {"len": None, "status": None, "err": None}
+
+        def on_headers(status_code, headers, **kwargs):
+            got["status"] = status_code
+            for name, value in headers:
+                if name.lower() == "content-length":
+                    try:
+                        got["len"] = int(value)
+                    except Exception:
+                        pass
+
+        def on_done(error=None, **kwargs):
+            got["err"] = error
+
+        s3_req = s3.S3Request(
+            client=self.s3_client,
+            type=s3.S3RequestType.DEFAULT,
+            request=req,
+            operation_name="HeadObject",
+            on_headers=on_headers,
+            on_done=on_done,
+            credential_provider=self.credentials_provider,
+            region=self.s3_region,
+        )
+
+        try:
+            s3_req.finished_future.result()
+        except Exception as e:
+            # 404 (not found) is expected when checking if object exists
+            if got["status"] == 404:
+                logger.debug("Object not found: %s", key_str)
+            else:
+                logger.debug("Exception in `_get_object_size`: %s", e)
+            return 0
+        if got["err"] or got["status"] != 200:
+            if got["status"] != 404:  # Don't warn for 404, it's expected
+                logger.warning(
+                    "Encountering error in S3 HEAD request "
+                    f"with error code: {got['status']}"
+                )
+            return 0
+        return got["len"] if got["len"] is not None else 0
+
+    # exactly the same as _get_object_size just awaiting an asyncio.Future
+    # instead of a concurrent.futures.Future
+    async def _get_object_size_async(self, key_str: str) -> int:
+        headers = HttpHeaders()
+        headers.add("Host", self.s3_endpoint)
+        req = HttpRequest("HEAD", self._format_safe_path(key_str), headers)
+
+        got = {"len": None, "status": None, "err": None}
+
+        def on_headers(status_code, headers, **kwargs):
+            got["status"] = status_code
+            for name, value in headers:
+                if name.lower() == "content-length":
+                    try:
+                        got["len"] = int(value)
+                    except Exception:
+                        pass
+
+        def on_done(error=None, **kwargs):
+            got["err"] = error
+
+        s3_req = s3.S3Request(
+            client=self.s3_client,
+            type=s3.S3RequestType.DEFAULT,
+            request=req,
+            operation_name="HeadObject",
+            on_headers=on_headers,
+            on_done=on_done,
+            credential_provider=self.credentials_provider,
+            region=self.s3_region,
+        )
+
+        try:
+            await asyncio.wrap_future(s3_req.finished_future)
+        except Exception as e:
+            # 404 (not found) is expected when checking if object exists
+            if got["status"] == 404:
+                logger.debug("Object not found: %s", key_str)
+            else:
+                logger.debug("Exception in `_get_object_size_async`: %s", e)
+            return 0
+        if got["err"] or got["status"] != 200:
+            if got["status"] != 404:  # Don't warn for 404, it's expected
+                logger.warning(
+                    "Encountering error in S3 HEAD request "
+                    f"with error code: {got['status']}"
+                )
+            return 0
+        return got["len"] if got["len"] is not None else 0
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return self.exists_sync(key)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        # Circuit breaker: if connection is disabled, return False
+        if self.connection_disabled:
+            return False
+
+        key_str = key.to_string()
+        if key_str in self.object_size_cache:
+            return self.object_size_cache[key_str] > 0
+        cache_size = self._get_object_size(key_str)
+        if cache_size > 0:
+            self.object_size_cache[key_str] = cache_size
+            return True
+        return False
+
+    def _write_mem_obj(self, mem_obj: MemoryObj, data: bytes, offset: int):
+        ctypes.memmove(mem_obj.data_ptr + offset, data, len(data))
+
+    def _s3_download(
+        self,
+        key_str: str,
+        mem_obj: MemoryObj,
+    ) -> "s3.S3Request":
+        """
+        Download a file from S3.
+        """
+        headers = HttpHeaders()
+        headers.add("Host", self.s3_endpoint)
+
+        # TODO(Jiayi): Enable more finegrained data partition
+        # range_header = f"bytes={start_byte}-{end_byte}"
+        # headers.add("Range", range_header)
+
+        req = HttpRequest("GET", self._format_safe_path(key_str), headers)
+
+        def on_body(chunk, offset, **kwargs):
+            # Directly write chunk to the memory object at the correct offset
+            self._write_mem_obj(mem_obj, chunk, offset)
+
+        # NOTE(Jiayi): Run in crt threads (not this thread) with GIL
+        # See https://github.com/awslabs/aws-crt-python/blob/4250709624119de1af3ca86816e1a154fcac7cc8/source/common.c#L51
+        def on_done(error=None, status_code=None, **kwargs):
+            ok = (status_code in (200, 206)) or (status_code is None)
+            if error or not ok:
+                raise RuntimeError(
+                    f"Failed to download {key_str} from S3: {error or status_code}"
+                )
+
+        # TODO(Jiayi): Need to support offset to enable zero-copy
+        # More concretely, we need to get the shared memory offset.
+        s3_req = s3.S3Request(
+            client=self.s3_client,
+            type=s3.S3RequestType.GET_OBJECT,
+            request=req,
+            on_body=on_body,
+            credential_provider=self.credentials_provider,
+            region=self.s3_region,
+            on_done=on_done,
+        )
+
+        return s3_req
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        # Circuit breaker: if connection is disabled, return None immediately
+        if self.connection_disabled:
+            logger.debug(
+                f"S3 connection disabled. Skipping download for {key.to_string()}"
+            )
+            return None
+
+        key_str = key.to_string()
+
+        obj_size = self.object_size_cache.get(key_str, None)
+
+        if obj_size is None:
+            obj_size = await self._get_object_size_async(key_str)
+            if obj_size <= 0:
+                self.object_size_cache[key_str] = 0
+                return None
+            self.object_size_cache[key_str] = obj_size
+
+        memory_obj = self.local_cpu_backend.allocate(
+            self.meta_shapes,
+            self.meta_dtypes,
+            self.meta_fmt,
+        )
+
+        if memory_obj is None:
+            return None
+
+        # Check if stored size matches expected size
+        if obj_size != memory_obj.get_size():
+            logger.error(
+                f"Size mismatch for {key_str}: S3 has {obj_size} bytes, "
+                f"but current config expects {memory_obj.get_size()} bytes. "
+                f"This usually means the data was stored with different chunk_size "
+                f"or model configuration. Please use matching config or clear S3."
+            )
+            memory_obj.ref_count_down()
+            return None
+
+        s3_req = self._s3_download(
+            key_str=key_str,
+            mem_obj=memory_obj,
+        )
+
+        try:
+            # use blocking_timeout_sec in config to control the timeout
+            await asyncio.wrap_future(s3_req.finished_future)
+
+            # Reset failure counter on success
+            self._reset_connection_failures()
+
+            return memory_obj
+        except Exception as e:
+            error_msg = str(e)
+
+            # Update connection failures and check if it's a connection error
+            is_connection_error = self._update_connection_failures(error_msg)
+
+            if not is_connection_error:
+                # Log non-connection errors
+                logger.error("Failed to download %s from S3: %s", key_str, e)
+
+            memory_obj.ref_count_down()
+            return None
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        # Circuit breaker: if connection is disabled, return all None
+        if self.connection_disabled:
+            logger.debug(
+                f"S3 connection disabled. "
+                f"Skipping batched download for {len(keys)} keys"
+            )
+            return [None] * len(keys)
+
+        memory_objs: List[Optional[MemoryObj]] = []
+        futures = []
+        future_to_memobj_idx = []
+
+        for idx, key in enumerate(keys):
+            key_str = key.to_string()
+
+            obj_size = self.object_size_cache.get(key_str, None)
+
+            if obj_size is None:
+                obj_size = await self._get_object_size_async(key_str)
+                if obj_size <= 0:
+                    self.object_size_cache[key_str] = 0
+                    memory_objs.append(None)
+                    continue
+                self.object_size_cache[key_str] = obj_size
+
+            memory_obj = self.local_cpu_backend.allocate(
+                self.meta_shapes,
+                self.meta_dtypes,
+                self.meta_fmt,
+            )
+
+            if not memory_obj:
+                memory_objs.append(None)
+                continue
+
+            # Check if stored size matches expected size
+            if obj_size != memory_obj.get_size():
+                logger.error(
+                    f"Size mismatch for {key_str}: S3 has {obj_size} bytes, "
+                    f"but current config expects {memory_obj.get_size()} bytes. "
+                    f"Skipping this key."
+                )
+                memory_obj.ref_count_down()
+                memory_objs.append(None)
+                continue
+
+            memory_objs.append(memory_obj)
+
+            s3_req = self._s3_download(
+                key_str=key_str,
+                mem_obj=memory_obj,
+            )
+            fut = asyncio.wrap_future(s3_req.finished_future)
+            futures.append(fut)
+            future_to_memobj_idx.append(len(memory_objs) - 1)
+
+        # Use return_exceptions to prevent one failure from stopping all downloads
+        results = await asyncio.gather(*futures, return_exceptions=True)
+
+        had_success = False
+
+        for future_idx, result in enumerate(results):
+            memobj_idx = future_to_memobj_idx[future_idx]
+
+            if isinstance(result, Exception):
+                error_msg = str(result)
+
+                is_connection_error = self._update_connection_failures(error_msg)
+
+                if not is_connection_error:
+                    # Log non-connection errors
+                    logger.error(
+                        f"Failed to download key at index {memobj_idx}: {error_msg}"
+                    )
+                # Release the memory object for failed download
+                memobj = memory_objs[memobj_idx]
+                if memobj is not None:
+                    memobj.ref_count_down()
+                    memory_objs[memobj_idx] = None
+            else:
+                had_success = True
+
+        if had_success:
+            self._reset_connection_failures()
+
+        return memory_objs
+
+    def _s3_upload(
+        self,
+        key_str: str,
+        memory_obj: MemoryObj,
+    ) -> "s3.S3Request":
+        """
+        Upload a file to S3.
+        """
+        # Zero-copy approach using MemoryViewStream
+        stream = MemoryViewStream(memory_obj.byte_array)
+        # Calculate total length from the memoryview
+        total_len = len(stream)
+
+        headers = HttpHeaders()
+        headers.add("Host", self.s3_endpoint)
+        headers.add("Content-Length", str(total_len))
+        headers.add("Content-Type", "application/octet-stream")
+
+        req = HttpRequest(
+            "PUT", self._format_safe_path(key_str), headers, body_stream=stream
+        )
+
+        done = {"err": None, "status": None}
+
+        def on_done(error=None, status_code=None, **kwargs):
+            done["err"] = error
+            done["status"] = status_code
+
+            if done["err"] or done["status"] not in (200, 201):
+                raise RuntimeError(f"Upload failed in S3Connector: {done}")
+
+        s3_req = s3.S3Request(
+            client=self.s3_client,
+            type=s3.S3RequestType.PUT_OBJECT,
+            request=req,
+            credential_provider=self.credentials_provider,
+            region=self.s3_region,
+            on_done=on_done,
+        )
+        return s3_req
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """
+        Store data to S3
+        """
+        # Circuit breaker: if connection is disabled, just log and return
+        if self.connection_disabled:
+            logger.debug(
+                f"S3 connection disabled due to repeated failures. "
+                f"Skipping upload for {key.to_string()}"
+            )
+            return
+
+        key_str = key.to_string()
+
+        # Check if the chunk size matches expected S3 part size
+        if memory_obj.get_physical_size() != self.s3_part_size:
+            logger.error(
+                f"Cannot upload {key_str}: chunk size {memory_obj.get_physical_size()} "
+                f"bytes does not match S3 part size {self.s3_part_size} bytes. "
+                f"Partial/unfull chunks are not supported."
+            )
+            return
+
+        try:
+            logger.debug("Uploading %s to S3", key_str)
+            s3_req = self._s3_upload(key_str, memory_obj)
+            await asyncio.wrap_future(s3_req.finished_future)
+
+            self.object_size_cache[key_str] = memory_obj.get_physical_size()
+            logger.debug("Uploaded %s to S3 successfully", key_str)
+
+            # Reset failure counter on success
+            self._reset_connection_failures()
+        except Exception as e:
+            error_msg = str(e)
+
+            # Update connection failures and check if it's a connection error
+            is_connection_error = self._update_connection_failures(error_msg)
+
+            if not is_connection_error:
+                # Log non-connection errors
+                logger.error("Failed to upload %s to S3: %s", key_str, e)
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        return await self.pq_executor.submit_job(
+            self._put,
+            key=key,
+            memory_obj=memory_obj,
+            priority=Priorities.PUT,
+        )
+
+    def support_batched_async_contains(self) -> bool:
+        return True
+
+    async def _batched_async_contains(
+        self, lookup_id: str, keys: List[CacheEngineKey], pin: bool = False
+    ) -> int:
+        # Circuit breaker: if connection is disabled, return 0
+        if self.connection_disabled:
+            return 0
+
+        num_hit_counts = 0
+        for key in keys:
+            key_str = key.to_string()
+            cached_size = self.object_size_cache.get(key_str, None)
+            if cached_size is not None:
+                if cached_size > 0:
+                    num_hit_counts += 1
+                    continue
+                else:
+                    return num_hit_counts
+
+            obj_size = await self._get_object_size_async(key_str)
+            if not obj_size > 0:
+                self.object_size_cache[key_str] = 0
+                return num_hit_counts
+
+            self.object_size_cache[key_str] = obj_size
+            num_hit_counts += 1
+
+        return num_hit_counts
+
+    async def batched_async_contains(
+        self, lookup_id: str, keys: List[CacheEngineKey], pin: bool = False
+    ) -> int:
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains,
+            lookup_id=lookup_id,
+            keys=keys,
+            pin=pin,
+            priority=Priorities.PEEK,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        return True
+
+    async def _batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        # batched get is already a coroutine
+        result = await self.batched_get(keys)
+        return [r for r in result if r is not None]
+
+    async def batched_get_non_blocking(
+        self, lookup_id: str, keys: List[CacheEngineKey]
+    ) -> List[MemoryObj]:
+        return await self.pq_executor.submit_job(
+            self._batched_get_non_blocking,
+            lookup_id=lookup_id,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+    async def list(self) -> List[str]:
+        raise NotImplementedError
+
+    def support_ping(self) -> bool:
+        return False
+
+    # TODO(Jiayi): This needs to be implemented.
+    async def ping(self) -> int:
+        raise NotImplementedError
+
+    def support_batched_get(self) -> bool:
+        return True
+
+    def _update_connection_failures(self, error_msg: str) -> bool:
+        # Check if it's a connection error
+        is_connection_error = (
+            "CONNECTION_REFUSED" in error_msg
+            or "SOCKET" in error_msg
+            or "DNS" in error_msg
+            or "TIMEOUT" in error_msg
+        )
+
+        if is_connection_error:
+            self.connection_failures += 1
+            logger.error(
+                f"S3 connection error ({self.connection_failures}/"
+                f"{self.max_connection_failures}): {error_msg}"
+            )
+
+            if self.connection_failures >= self.max_connection_failures:
+                self.connection_disabled = True
+                logger.error(
+                    f"S3 connection disabled after "
+                    f"{self.max_connection_failures} "
+                    f"consecutive failures. "
+                    f"All future S3 operations will be skipped."
+                )
+
+        return is_connection_error
+
+    def _reset_connection_failures(self):
+        """Reset connection failure counter on successful operation."""
+        if self.connection_failures > 0:
+            logger.info("S3 connection recovered")
+            self.connection_failures = 0
+
+    async def close(self):
+        await self.pq_executor.shutdown(wait=True)
diff --git a/lmcache/v1/storage_backend/connector/sagemaker_hyperpod_adapter.py b/lmcache/v1/storage_backend/connector/sagemaker_hyperpod_adapter.py
new file mode 100644
index 0000000..830d0dd
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/sagemaker_hyperpod_adapter.py
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Dict
+import os
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class SageMakerHyperPodConnectorAdapter(ConnectorAdapter):
+    """Adapter for SageMaker HyperPod connectors."""
+
+    def __init__(self) -> None:
+        super().__init__("sagemaker-hyperpod://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """
+        Create a SageMaker HyperPod connector from the given context.
+
+        Args:
+            context: Connector context containing configuration
+
+        Returns:
+            Initialized SageMaker HyperPod connector
+
+        Raises:
+            ValueError: If configuration is invalid
+            RuntimeError: If shared memory initialization fails
+        """
+        # Local import to avoid circular dependencies
+        # Local
+        from .sagemaker_hyperpod_connector import SageMakerHyperPodConnector
+
+        config = context.config
+        assert config is not None, "Config must not be None"
+        assert context.loop is not None, "context.loop must not be None"
+        assert context.local_cpu_backend is not None, (
+            "context.local_cpu_backend must not be None"
+        )
+
+        # Default configuration values with type hints
+        defaults: Dict[str, Any] = {
+            "bucket": "lmcache",
+            "shared_memory_name": "shared_memory",
+            "max_concurrent_requests": 100,
+            "max_connections": 256,
+            "max_connections_per_host": 128,
+            "timeout_ms": 5000,
+            "lease_ttl_s": 30.0,
+            "put_stream_chunk_bytes": 65536,
+            "use_https": False,
+            "max_lease_size_mb": None,
+        }
+
+        # Extract and validate configuration
+        extra_config = config.extra_config or {}
+
+        bucket_name = str(
+            extra_config.get("sagemaker_hyperpod_bucket", defaults["bucket"])
+        )
+        shared_memory_name = extra_config.get(
+            "sagemaker_hyperpod_shared_memory_name", defaults["shared_memory_name"]
+        )
+        max_concurrent_requests = self._get_positive_int(
+            extra_config,
+            "sagemaker_hyperpod_max_concurrent_requests",
+            int(defaults["max_concurrent_requests"]),  # Cast to int
+        )
+        max_connections = self._get_positive_int(
+            extra_config,
+            "sagemaker_hyperpod_max_connections",
+            int(defaults["max_connections"]),  # Cast to int
+        )
+        max_connections_per_host = self._get_positive_int(
+            extra_config,
+            "sagemaker_hyperpod_max_connections_per_host",
+            int(defaults["max_connections_per_host"]),  # Cast to int
+        )
+        timeout_ms = self._get_positive_int(
+            extra_config,
+            "sagemaker_hyperpod_timeout_ms",
+            int(defaults["timeout_ms"]),  # Cast to int
+        )
+        lease_ttl_s = self._get_positive_float(
+            extra_config,
+            "sagemaker_hyperpod_lease_ttl_s",
+            float(defaults["lease_ttl_s"]),  # Cast to float
+        )
+        put_stream_chunk_bytes = self._get_positive_int(
+            extra_config,
+            "sagemaker_hyperpod_put_stream_chunk_bytes",
+            int(defaults["put_stream_chunk_bytes"]),  # Cast to int
+        )
+        use_https = bool(
+            extra_config.get("sagemaker_hyperpod_use_https", defaults["use_https"])
+        )
+        max_lease_size_mb = extra_config.get(
+            "sagemaker_hyperpod_max_lease_size_mb", defaults["max_lease_size_mb"]
+        )
+
+        if max_lease_size_mb is not None:
+            try:
+                max_lease_size_mb = float(max_lease_size_mb)
+                if max_lease_size_mb <= 0:
+                    raise ValueError(
+                        f"sagemaker_hyperpod_max_lease_size_mb must be positive,"
+                        f" got {max_lease_size_mb}"
+                    )
+            except (TypeError, ValueError) as e:
+                raise ValueError(
+                    f"Invalid value for sagemaker_hyperpod_max_lease_size_mb:"
+                    f" {max_lease_size_mb}"
+                ) from e
+
+        # Parse and construct URL
+        url = self._parse_url(context.url, use_https)
+
+        logger.info(
+            f"Creating SageMaker HyperPod connector: url={url}, "
+            f"bucket={bucket_name}, shared_memory={shared_memory_name}, "
+            f"max_connections={max_connections}, "
+            f"max_concurrent_requests={max_concurrent_requests}, "
+            f"timeout_ms={timeout_ms}, lease_ttl_s={lease_ttl_s}s"
+            f"max_lease_size_mb="
+            f"{max_lease_size_mb if max_lease_size_mb else 'unlimited'}"
+        )
+
+        # Create connector instance
+        connector = SageMakerHyperPodConnector(
+            sagemaker_hyperpod_url=url,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            bucket_name=bucket_name,
+            shared_memory_name=shared_memory_name,
+            max_concurrent_requests=max_concurrent_requests,
+            max_connections=max_connections,
+            max_connections_per_host=max_connections_per_host,
+            timeout_ms=timeout_ms,
+            lease_ttl_s=lease_ttl_s,
+            put_stream_chunk_bytes=put_stream_chunk_bytes,
+            max_lease_size_mb=max_lease_size_mb,
+        )
+
+        logger.info("SageMaker HyperPod connector created successfully")
+        return connector
+
+    @staticmethod
+    def _parse_url(url: str, use_https: bool) -> str:
+        """
+        Parse and normalize the SageMaker HyperPod URL.
+
+        Args:
+            url: Raw URL from context (e.g., "sagemaker-hyperpod://127.0.0.1:9200")
+            use_https: Whether to use HTTPS protocol
+
+        Returns:
+            Normalized HTTP/HTTPS URL
+        """
+        assert url, "SageMaker HyperPod URL must not be empty"
+
+        expanded_url = os.path.expandvars(url)
+
+        # Strip the sagemaker-hyperpod:// prefix
+        raw_url = expanded_url.removeprefix("sagemaker-hyperpod://")
+
+        assert raw_url, (
+            "SageMaker HyperPod URL must contain host information after 'sagemaker-hyperpod://'"
+        )
+
+        # If URL already has protocol, use it as-is
+        if raw_url.startswith("http://") or raw_url.startswith("https://"):
+            return raw_url
+
+        # Otherwise, add appropriate protocol
+        protocol = "https" if use_https else "http"
+        return f"{protocol}://{raw_url}"
+
+    @staticmethod
+    def _get_positive_int(config_dict: dict, key: str, default: int) -> int:
+        """
+        Extract a positive integer from config with validation.
+
+        Args:
+            config_dict: Configuration dictionary
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Validated positive integer
+
+        Raises:
+            ValueError: If value is not a positive integer
+        """
+        value = config_dict.get(key, default)
+        try:
+            int_value = int(value)
+            if int_value <= 0:
+                raise ValueError(f"{key} must be positive, got {int_value}")
+            return int_value
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Invalid value for {key}: {value}") from e
+
+    @staticmethod
+    def _get_positive_float(config_dict: dict, key: str, default: float) -> float:
+        """
+        Extract a positive float from config with validation.
+
+        Args:
+            config_dict: Configuration dictionary
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Validated positive float
+
+        Raises:
+            ValueError: If value is not a positive float
+        """
+        value = config_dict.get(key, default)
+        try:
+            float_value = float(value)
+            if float_value <= 0:
+                raise ValueError(f"{key} must be positive, got {float_value}")
+            return float_value
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Invalid value for {key}: {value}") from e
diff --git a/lmcache/v1/storage_backend/connector/sagemaker_hyperpod_connector.py b/lmcache/v1/storage_backend/connector/sagemaker_hyperpod_connector.py
new file mode 100644
index 0000000..f64202c
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/sagemaker_hyperpod_connector.py
@@ -0,0 +1,987 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from enum import IntEnum, auto
+from multiprocessing import shared_memory
+from typing import AsyncIterator, List, Optional, Tuple
+import asyncio
+import json
+import time
+import urllib.parse
+
+# Third Party
+import aiohttp
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+
+# Constants
+METADATA_SIZE_BYTES = 28  # RemoteMetadata is 7 int32 fields
+METADATA_SHAPE_DIMS = 4  # Number of shape dimensions in metadata
+DEFAULT_CHUNK_SIZE_BYTES = 65536  # 64KB default for streaming
+HTTP_OK = 200
+HTTP_NO_CONTENT = 204
+HTTP_NOT_FOUND = 404
+HTTP_CONFLICT = 409
+
+
+class Priorities(IntEnum):
+    """Priority levels for job execution in the priority queue."""
+
+    LEASE = 0  # Highest priority - lease acquisition/release
+    PREFETCH = auto()  # Medium priority - prefetching data
+    PUT = auto()  # Lower priority - storing data
+
+
+@dataclass
+class LeaseInfo:
+    """Information about a lease obtained from ai-toolkit daemon.
+
+    A lease represents temporary exclusive access to cached data in shared memory.
+    The daemon manages leases to prevent data from being evicted while in use.
+    """
+
+    lease_id: str
+    offsets: List[Tuple[int, int]]  # (offset, length) pairs in shared memory
+
+
+class SageMakerHyperPodConnector(RemoteConnector):
+    """
+    SageMaker HyperPod remote connector for communicating with KV cache daemon
+     in SageMaker HyperPod.
+
+    This connector provides high-performance access to KV cache data stored in
+    a remote SageMaker HyperPod service using:
+    - Shared memory (data plane) - zero-copy access via shared memory segment
+    - HTTP (control plane) - lease acquisition, release, and PUT operations
+
+    The connector uses a lease-based protocol with immediate release after all reads
+    """
+
+    def __init__(
+        self,
+        sagemaker_hyperpod_url: str,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        bucket_name: str,
+        shared_memory_name: Optional[str],
+        max_concurrent_requests: int,
+        max_connections: int,
+        max_connections_per_host: int,
+        timeout_ms: int,
+        lease_ttl_s: float = 10.0,
+        put_stream_chunk_bytes: int = DEFAULT_CHUNK_SIZE_BYTES,
+        max_lease_size_mb: Optional[float] = None,
+        **kwargs,  # Accept and ignore unused legacy parameters
+    ):
+        """
+        Initialize SageMaker HyperPod connector.
+
+        Args:
+            sagemaker_hyperpod_url: Base URL of the ai-toolkit daemon
+            loop: Event loop for async operations
+            local_cpu_backend: Backend for local memory allocation
+            bucket_name: Bucket name for KV storage namespace
+            shared_memory_name: Name of shared memory segment
+            (if None, shared memory disabled)
+            max_concurrent_requests: Maximum concurrent control plane requests
+            max_connections: Maximum total HTTP connections in pool
+            max_connections_per_host: Maximum HTTP connections per host
+            timeout_ms: Timeout for lease acquisition requests
+            lease_ttl_s: Server-side lease timeout (default: 10s)
+            put_stream_chunk_bytes: Chunk size for
+            streaming PUT requests (default: 64KB)
+            **kwargs: Unused legacy parameters (ignored for backward compatibility)
+        """
+        # initialize base class, which includes some common attributes
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        # Core configuration
+        self.base_url = sagemaker_hyperpod_url.rstrip("/")
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+        self.bucket_name = bucket_name
+        self.shared_memory_name = shared_memory_name
+        self.lease_ttl_s = lease_ttl_s
+        self.put_stream_chunk_bytes = max(1024, put_stream_chunk_bytes)  # Minimum 1KB
+        self.max_lease_size_bytes = (
+            int(max_lease_size_mb * 1024 * 1024) if max_lease_size_mb else None
+        )
+
+        # HTTP configuration
+        self.max_concurrent_requests = max(1, max_concurrent_requests)
+        self.max_connections = max(1, max_connections)
+        self.max_connections_per_host = max(1, max_connections_per_host)
+        self.timeout_ms = max(100, timeout_ms)  # Minimum 100ms
+
+        # HTTP session (lazy initialized)
+        self.http_session: Optional[aiohttp.ClientSession] = None
+        self.session_lock = asyncio.Lock()
+
+        # Concurrency control
+        self.control_inflight = asyncio.Semaphore(self.max_concurrent_requests)
+        self.put_inflight = asyncio.Semaphore(self.max_concurrent_requests)
+        self.pq_executor = AsyncPQExecutor(loop)
+
+        # Shared memory
+        self.shared_memory_obj: Optional[shared_memory.SharedMemory] = None
+        self.shared_memory_map: Optional[memoryview] = None
+        if self.shared_memory_name:
+            self._init_shared_memory()
+
+        # Observability
+        self._stats_monitor = LMCStatsMonitor.GetOrCreate()
+
+        # Statistics for monitoring
+        self.stats = {
+            "get_success": 0,
+            "get_failure": 0,
+            "put_success": 0,
+            "put_failure": 0,
+            "lease_acquired": 0,
+            "lease_released": 0,
+            "lease_release_failed": 0,
+        }
+
+        logger.info(
+            f"SageMaker HyperPod Connector initialized: url={self.base_url}, "
+            f"bucket={self.bucket_name}, shared_memory={self.shared_memory_name}, "
+            f"connections={self.max_connections}, lease_ttl={lease_ttl_s}s"
+        )
+
+    def _init_shared_memory(self):
+        """Initialize shared memory connection to ai-toolkit daemon."""
+        try:
+            self.shared_memory_obj = shared_memory.SharedMemory(
+                name=self.shared_memory_name, create=False
+            )
+            self.shared_memory_map = memoryview(self.shared_memory_obj.buf)
+            size_mb = len(self.shared_memory_map) / (1024**2)
+            logger.info(
+                f"Shared memory opened: {self.shared_memory_name} ({size_mb:.2f} MB)"
+            )
+        except FileNotFoundError:
+            logger.error(
+                f"Shared memory segment '{self.shared_memory_name}' not found. "
+                "Ensure ai-toolkit daemon is running."
+            )
+            self.shared_memory_map = None
+            raise
+        except Exception as e:
+            logger.error(f"Failed to initialize shared memory: {e}")
+            self.shared_memory_map = None
+            raise
+
+    async def _ensure_http_session(self) -> aiohttp.ClientSession:
+        """Ensure HTTP session with connection pooling is initialized."""
+        if self.http_session is None:
+            async with self.session_lock:
+                if self.http_session is None:  # Double-check locking
+                    connector = aiohttp.TCPConnector(
+                        limit=self.max_connections,
+                        limit_per_host=self.max_connections_per_host,
+                        ttl_dns_cache=300,
+                        use_dns_cache=True,
+                        keepalive_timeout=30,
+                        enable_cleanup_closed=True,
+                    )
+
+                    timeout = aiohttp.ClientTimeout(
+                        total=30,
+                        connect=5,
+                        sock_read=10,
+                    )
+
+                    self.http_session = aiohttp.ClientSession(
+                        connector=connector,
+                        timeout=timeout,
+                        headers={"User-Agent": "LMCache-SageMaker-HyperPod/1.0"},
+                    )
+                    logger.info(
+                        f"HTTP session created with {self.max_connections} "
+                        f"max connections"
+                    )
+
+        return self.http_session
+
+    async def _http_request(
+        self,
+        method: str,
+        url: str,
+        data=None,
+        params=None,
+        timeout: float = 5.0,
+        headers=None,
+        gate: Optional[asyncio.Semaphore] = None,
+    ):
+        """Execute HTTP request with optional semaphore gate."""
+        if gate is None:
+            return await self._http_request_impl(
+                method, url, data=data, params=params, timeout=timeout, headers=headers
+            )
+        async with gate:
+            return await self._http_request_impl(
+                method, url, data=data, params=params, timeout=timeout, headers=headers
+            )
+
+    async def _http_request_impl(
+        self,
+        method: str,
+        url: str,
+        data=None,
+        params=None,
+        timeout: float = 5.0,
+        headers=None,
+    ):
+        """Execute HTTP request with connection pooling and error handling."""
+        try:
+            session = await self._ensure_http_session()
+            request_timeout = aiohttp.ClientTimeout(total=timeout)
+
+            async with session.request(
+                method,
+                url,
+                data=data,
+                params=params,
+                timeout=request_timeout,
+                headers=headers,
+            ) as response:
+                # Parse JSON response if available
+                body_json = None
+                content_type = response.headers.get("Content-Type", "")
+                if content_type.startswith("application/json"):
+                    try:
+                        body_json = await response.json()
+                    except aiohttp.ContentTypeError as e:
+                        logger.warning(
+                            f"JSON parsing failed for {method} {url}:"
+                            f"invalid content-type - {e}"
+                        )
+                    except json.JSONDecodeError as e:
+                        logger.warning(
+                            f"JSON parsing failed for {method} {url}:"
+                            f"malformed JSON - {e}"
+                        )
+                    except Exception as e:
+                        logger.warning(f"JSON parsing failed for {method} {url}: {e}")
+
+                return {
+                    "status": response.status,
+                    "json": body_json,
+                }
+
+        except asyncio.TimeoutError:
+            logger.warning(f"HTTP {method} timeout: {url}")
+            return None
+        except aiohttp.ClientError as e:
+            logger.error(f"HTTP {method} client error: {url} - {e}")
+            return None
+        except Exception as e:
+            logger.error(f"HTTP {method} failed: {url} - {e}")
+            return None
+
+    def _key_to_string(self, key: CacheEngineKey) -> str:
+        """Convert CacheEngineKey to URL-safe string format."""
+        key_str = key.to_string()
+        return urllib.parse.quote(key_str, safe="")
+
+    async def _release_lease(self, key: CacheEngineKey, lease_id: str) -> bool:
+        """
+        Release a lease to free server resources immediately.
+
+        Args:
+            key: The cache key
+            lease_id: The lease ID to release
+
+        Returns:
+            True if release successful, False on error
+        """
+        key_str = self._key_to_string(key)
+        url = f"{self.base_url}/v1/leases/{lease_id}/release"
+
+        try:
+            result = await self._http_request(
+                "POST",
+                url,
+                timeout=5.0,
+                gate=self.control_inflight,
+            )
+
+            if result and result["status"] == HTTP_OK:
+                self.stats["lease_released"] += 1
+                logger.debug(f"Lease released: key={key_str}, lease_id={lease_id}")
+                return True
+            else:
+                status = result["status"] if result else "TIMEOUT"
+                self.stats["lease_release_failed"] += 1
+                logger.warning(
+                    f"Lease release failed: key={key_str}, lease_id={lease_id}, "
+                    f"status={status}"
+                )
+                return False
+
+        except Exception as e:
+            self.stats["lease_release_failed"] += 1
+            logger.warning(
+                f"Lease release error: key={key_str}, lease_id={lease_id} - {e}"
+            )
+            return False
+
+    async def _acquire_lease(self, key: CacheEngineKey) -> Optional[LeaseInfo]:
+        """
+        Acquire a lease for the given key.
+
+        A lease prevents the daemon from evicting data while we're reading it.
+        The response includes offset information for shared memory access.
+
+        Args:
+            key: The cache key to acquire lease for
+
+        Returns:
+            LeaseInfo if successful, None otherwise
+        """
+        key_str = self._key_to_string(key)
+        url = f"{self.base_url}/v1/kv/{self.bucket_name}/{key_str}/leases"
+        params = {
+            "timeout_ms": self.timeout_ms,
+            "ttl_s": self.lease_ttl_s,
+        }
+
+        result = await self._http_request(
+            "POST",
+            url,
+            params=params,
+            timeout=self.timeout_ms / 1000.0,
+            gate=self.control_inflight,
+        )
+
+        if not result or result["status"] != HTTP_OK or not result["json"]:
+            logger.debug(f"Lease acquisition failed: key={key_str}")
+            return None
+
+        lease_data = result["json"]
+        offsets = [(o["offset"], o["len"]) for o in lease_data.get("offsets", [])]
+
+        if not offsets:
+            logger.debug(f"Lease has no offsets: key={key_str}")
+            return None
+
+        lease_info = LeaseInfo(
+            lease_id=lease_data["id"],
+            offsets=offsets,
+        )
+
+        total_size = sum(length for _, length in offsets)
+
+        if (
+            self.max_lease_size_bytes is not None
+            and total_size > self.max_lease_size_bytes
+        ):
+            logger.warning(
+                f"Lease size {total_size / 1024:.2f} KB exceeds limit "
+                f"{self.max_lease_size_bytes / 1024:.2f} KB, releasing"
+            )
+            await self._release_lease(key, lease_info.lease_id)
+            return None
+
+        self.stats["lease_acquired"] += 1
+
+        logger.debug(
+            f"Lease acquired: key={key_str}, lease_id={lease_info.lease_id}, "
+            f"size={total_size / 1024:.2f} KB, blocks={len(offsets)}"
+        )
+
+        return lease_info
+
+    async def _executor_submit_lease_acquisition(
+        self, key: CacheEngineKey
+    ) -> Optional[LeaseInfo]:
+        """Submit lease acquisition to priority executor."""
+        return await self.pq_executor.submit_job(
+            self._acquire_lease,
+            key=key,
+            priority=Priorities.LEASE,
+        )
+
+    def _read_from_shared_memory(
+        self, key: CacheEngineKey, lease_info: LeaseInfo
+    ) -> Optional[MemoryObj]:
+        """
+        Read data from shared memory using lease offsets.
+
+        Data format: [RemoteMetadata header (28 bytes)] + [KV cache payload]
+        Data may be fragmented across multiple blocks in shared memory.
+
+        Args:
+            key: The cache key being read
+            lease_info: Lease information with memory offsets
+
+        Returns:
+            MemoryObj containing the data, or None on error
+        """
+        if self.shared_memory_map is None:
+            logger.error("Shared memory not available")
+            return None
+
+        if not lease_info.offsets:
+            logger.error("No offsets in lease")
+            return None
+
+        shm_size = len(self.shared_memory_map)
+        for offset, length in lease_info.offsets:
+            if offset < 0 or length < 0:
+                logger.error(
+                    f"Invalid offset or length: offset={offset}, length={length}"
+                )
+                return None
+            if offset + length > shm_size:
+                logger.error(
+                    f"Offset out of bounds: offset={offset}, length={length}, "
+                    f"shm_size={shm_size}"
+                )
+                return None
+
+        memory_obj = None
+        try:
+            # Validate total size
+            total_size = sum(length for _, length in lease_info.offsets)
+            if total_size < METADATA_SIZE_BYTES:
+                logger.error(f"Insufficient data for metadata: {total_size} bytes")
+                return None
+
+            # Read metadata header (may span multiple blocks)
+            header = self._read_bytes_from_offsets(
+                lease_info.offsets, 0, METADATA_SIZE_BYTES
+            )
+            if len(header) < METADATA_SIZE_BYTES:
+                logger.error("Failed to read complete metadata header")
+                return None
+
+            # Parse metadata
+            metadata = RemoteMetadata.deserialize(header)
+            if metadata.length <= 0:
+                logger.error(f"Invalid payload length: {metadata.length}")
+                return None
+
+            # Restore original shape (remove padding zeros)
+            actual_shape = self._parse_shape(metadata.shapes[0])
+
+            # Allocate local CPU memory
+            memory_obj = self.local_cpu_backend.allocate(
+                actual_shape,
+                metadata.dtypes[0],
+                metadata.fmt,
+            )
+            if memory_obj is None:
+                logger.error(f"Failed to allocate memory for key {key.to_string()}")
+                return None
+
+            # Get writable view
+            view = self._get_writable_view(memory_obj.byte_array)
+
+            # Copy payload data from shared memory (skip header)
+            copied = self._copy_bytes_from_offsets(
+                lease_info.offsets, METADATA_SIZE_BYTES, metadata.length, view
+            )
+
+            if copied != metadata.length:
+                logger.error(
+                    f"Data size mismatch: expected {metadata.length}, got {copied}"
+                )
+                memory_obj.ref_count_down()
+                return None
+
+            logger.debug(
+                "Read from shared memory: key=%s, shape=%s, dtype=%s, size=%s bytes",
+                key.to_string(),
+                actual_shape,
+                metadata.dtypes[0],
+                metadata.length,
+            )
+
+            return memory_obj
+
+        except Exception as e:
+            logger.error(
+                f"Error reading from shared memory: key={key.to_string()} - {e}"
+            )
+            if memory_obj is not None:
+                memory_obj.ref_count_down()
+            return None
+
+    def _read_bytes_from_offsets(
+        self, offsets: List[Tuple[int, int]], skip_bytes: int, read_bytes: int
+    ) -> bytearray:
+        """Read bytes from shared memory offsets, skipping initial bytes."""
+        if self.shared_memory_map is None:
+            logger.error("Shared memory not available")
+            return bytearray()
+
+        result = bytearray(read_bytes)
+        filled = 0
+        bytes_to_skip = skip_bytes
+        shm_size = len(self.shared_memory_map)
+
+        for offset, length in offsets:
+            if filled >= read_bytes:
+                break
+
+            # Skip header bytes in first chunk(s)
+            if bytes_to_skip > 0:
+                if length <= bytes_to_skip:
+                    bytes_to_skip -= length
+                    continue
+                offset += bytes_to_skip
+                length -= bytes_to_skip
+                bytes_to_skip = 0
+
+            if length <= 0:
+                continue
+
+            take = min(read_bytes - filled, length)
+
+            if offset < 0 or take <= 0:
+                logger.error(f"Invalid read parameters: offset={offset}, take={take}")
+                break
+            if offset + take > shm_size:
+                logger.error(
+                    f"Read would exceed shared memory bounds: "
+                    f"offset={offset}, take={take}, shm_size={shm_size}"
+                )
+                break
+
+            result[filled : filled + take] = self.shared_memory_map[
+                offset : offset + take
+            ]
+            filled += take
+
+        return result
+
+    def _copy_bytes_from_offsets(
+        self,
+        offsets: List[Tuple[int, int]],
+        skip_bytes: int,
+        copy_bytes: int,
+        dest_view: memoryview,
+    ) -> int:
+        """Copy bytes from shared memory offsets to destination view."""
+        if self.shared_memory_map is None:
+            logger.error("Shared memory not available")
+            return 0
+
+        copied = 0
+        bytes_to_skip = skip_bytes
+        shm_size = len(self.shared_memory_map)
+
+        for offset, length in offsets:
+            if copied >= copy_bytes:
+                break
+
+            # Skip header bytes
+            if bytes_to_skip > 0:
+                if length <= bytes_to_skip:
+                    bytes_to_skip -= length
+                    continue
+                offset += bytes_to_skip
+                length -= bytes_to_skip
+                bytes_to_skip = 0
+
+            if length <= 0:
+                continue
+
+            take = min(copy_bytes - copied, length)
+
+            if offset < 0 or take <= 0:
+                logger.error(f"Invalid copy parameters: offset={offset}, take={take}")
+                break
+            if offset + take > shm_size:
+                logger.error(
+                    f"Copy would exceed shared memory bounds: "
+                    f"offset={offset}, take={take}, shm_size={shm_size}"
+                )
+                break
+
+            dest_view[copied : copied + take] = self.shared_memory_map[
+                offset : offset + take
+            ]
+            copied += take
+
+        return copied
+
+    @staticmethod
+    def _parse_shape(shape: torch.Size) -> torch.Size:
+        """Parse shape from metadata, removing padding zeros."""
+        actual_shape_list: List[int] = []
+        for dim in shape:
+            if dim == 0 and len(actual_shape_list) > 0:
+                break
+            actual_shape_list.append(dim)
+        return torch.Size(actual_shape_list) if actual_shape_list else torch.Size([1])
+
+    @staticmethod
+    def _get_writable_view(byte_array) -> memoryview:
+        """Get a writable memoryview from byte array."""
+        if isinstance(byte_array, memoryview):
+            view = byte_array
+            if getattr(view, "format", None) == "<B":
+                view = view.cast("B")
+        else:
+            view = memoryview(byte_array)
+        return view
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """
+        Check if a key exists in remote storage.
+
+        Acquires a lease, checks existence, then releases immediately.
+        """
+        lease = await self._executor_submit_lease_acquisition(key)
+        if lease is None:
+            return False
+
+        try:
+            return True
+        finally:
+            await self._release_lease(key, lease.lease_id)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Check if a key exists in remote storage (sync wrapper)."""
+        future = asyncio.run_coroutine_threadsafe(self.exists(key), self.loop)
+        return bool(future.result())
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """
+        Retrieve KV cache data for the given key with metrics reporting.
+
+        Flow:
+        1. Acquire a new lease
+        2. Read from shared memory using lease offsets
+        3. Release lease immediately (in finally block)
+        4. Report metrics
+
+        Args:
+            key: The cache key to retrieve
+
+        Returns:
+            MemoryObj containing the KV cache data, or None if not found
+        """
+        begin = time.perf_counter()
+
+        lease_info = await self._executor_submit_lease_acquisition(key)
+
+        if lease_info is None:
+            self.stats["get_failure"] += 1
+            logger.debug(f"GET failed (no lease): key={key.to_string()}")
+            return None
+
+        try:
+            memory_obj = self._read_from_shared_memory(key, lease_info)
+
+            if memory_obj is not None:
+                end = time.perf_counter()
+                obj_size = memory_obj.get_size()
+
+                # Report metrics for successful get
+                self._stats_monitor.update_interval_remote_time_to_get(
+                    (end - begin) * 1000
+                )
+                self._stats_monitor.update_interval_remote_read_metrics(obj_size)
+
+                self.stats["get_success"] += 1
+                logger.debug(
+                    f"GET success: key={key.to_string()}, "
+                    f"shape={memory_obj.get_shape()}, "
+                    f"size={obj_size / 1e6:.3f} MBytes in {(end - begin) * 1000:.3f}ms"
+                )
+            else:
+                self.stats["get_failure"] += 1
+                logger.error(
+                    f"Failed to read from shared memory: key={key.to_string()}"
+                )
+
+            return memory_obj
+
+        except Exception as e:
+            self.stats["get_failure"] += 1
+            logger.error(f"GET error: key={key.to_string()} - {e}")
+            return None
+
+        finally:
+            # Always release lease immediately after read
+            await self._release_lease(key, lease_info.lease_id)
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """Get multiple keys in parallel. Metrics reported per individual get."""
+        tasks = [self.get(key) for key in keys]
+        return await asyncio.gather(*tasks)
+
+    def support_batched_put(self) -> bool:
+        """Indicate support for batched PUT operations."""
+        return True
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ):
+        """Store multiple objects in parallel. Metrics reported per individual put."""
+        await asyncio.gather(
+            *(self.put(key, mem) for key, mem in zip(keys, memory_objs, strict=True))
+        )
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Store data to ai-toolkit (queued with priority)."""
+        return await self.pq_executor.submit_job(
+            self._put,
+            key=key,
+            memory_obj=memory_obj,
+            priority=Priorities.PUT,
+        )
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Internal PUT operation - sends data via HTTP streaming."""
+        key_str = self._key_to_string(key)
+        url = f"{self.base_url}/v1/kv/{self.bucket_name}/{key_str}"
+
+        begin = time.perf_counter()
+
+        try:
+            # Build streaming payload (header + data)
+            payload_len, payload_iter = self._build_put_stream(memory_obj)
+
+            logger.debug(
+                f"PUT: key={key_str}, size={payload_len / 1024:.2f} KB, "
+                f"shape={memory_obj.get_shape()}"
+            )
+
+            # Send HTTP PUT request with streaming
+            result = await self._http_request(
+                "PUT",
+                url,
+                data=payload_iter,
+                timeout=self.timeout_ms / 1000.0,
+                headers={"Content-Length": str(payload_len)},
+                gate=self.put_inflight,
+            )
+
+            end = time.perf_counter()
+
+            if result and result["status"] == HTTP_OK:
+                self.stats["put_success"] += 1
+
+                # Report metrics for successful put
+                self._stats_monitor.update_interval_remote_time_to_put(
+                    (end - begin) * 1000
+                )
+                self._stats_monitor.update_interval_remote_write_metrics(payload_len)
+
+                logger.info(
+                    f"PUT success: key={key_str}, size={payload_len / 1024:.2f} KB "
+                    f"in {(end - begin) * 1000:.3f}ms"
+                )
+            elif result and result["status"] == HTTP_CONFLICT:
+                # 409 Conflict = key already exists (not an error)
+                self.stats["put_success"] += 1
+
+                # Still report metrics for conflict case
+                self._stats_monitor.update_interval_remote_time_to_put(
+                    (end - begin) * 1000
+                )
+                self._stats_monitor.update_interval_remote_write_metrics(payload_len)
+
+                logger.debug(f"PUT skipped (already exists): key={key_str}")
+            else:
+                status = result["status"] if result else "TIMEOUT"
+                self.stats["put_failure"] += 1
+                logger.error(f"PUT failed: key={key_str}, status={status}")
+
+        except Exception as e:
+            self.stats["put_failure"] += 1
+            logger.error(f"PUT exception: key={key_str} - {e}")
+
+    def _build_put_stream(self, memory_obj: MemoryObj) -> Tuple[int, AsyncIterator]:
+        """
+        Build streaming payload: [RemoteMetadata (28 bytes)] + [KV cache data]
+
+        Args:
+            memory_obj: The memory object to stream
+
+        Returns:
+            Tuple of (total_length, async_generator)
+        """
+        # Prepare data view
+        kv_view = self._get_writable_view(memory_obj.byte_array)
+        kv_len = len(kv_view)
+
+        # Prepare metadata
+        shape = list(memory_obj.get_shape())
+        padded_shape = (shape + [0] * METADATA_SHAPE_DIMS)[:METADATA_SHAPE_DIMS]
+
+        metadata = RemoteMetadata(
+            kv_len,
+            [torch.Size(padded_shape)],
+            [memory_obj.get_dtype()],
+            memory_obj.get_memory_format(),
+        )
+
+        # Serialize metadata header
+        header = bytearray(METADATA_SIZE_BYTES)
+        metadata.serialize_into(header)
+        header_bytes = bytes(header)
+
+        total_len = len(header_bytes) + kv_len
+        chunk_size = self.put_stream_chunk_bytes
+
+        async def generator() -> AsyncIterator:
+            # First yield header
+            yield header_bytes
+            # Then yield data in chunks
+            offset = 0
+            while offset < kv_len:
+                next_offset = min(kv_len, offset + chunk_size)
+                yield kv_view[offset:next_offset]
+                offset = next_offset
+
+        return total_len, generator()
+
+    def support_batched_async_contains(self) -> bool:
+        """Indicate support for batched async contains operation."""
+        return True
+
+    async def _batched_async_contains(
+        self, lookup_id: str, keys: List[CacheEngineKey], pin: bool = False
+    ) -> int:
+        """
+        Check existence of keys sequentially until first miss.
+
+        Args:
+            lookup_id: Lookup identifier (for logging/tracking)
+            keys: List of keys to check
+            pin: Whether to pin data (unused, for API compatibility)
+
+        Returns:
+            Number of consecutive hits from the start
+        """
+        num_hits = 0
+        for key in keys:
+            lease = None
+            try:
+                lease = await self._executor_submit_lease_acquisition(key)
+                if lease is None:
+                    break
+
+                num_hits += 1
+
+            except Exception as exc:
+                logger.debug(f"Lease acquisition failed for {key}: {exc}")
+                break
+            finally:
+                if lease is not None:
+                    await self._release_lease(key, lease.lease_id)
+
+        return num_hits
+
+    async def batched_async_contains(
+        self, lookup_id: str, keys: List[CacheEngineKey], pin: bool = False
+    ) -> int:
+        """Check existence of multiple keys (queued with priority)."""
+        return await self.pq_executor.submit_job(
+            self._batched_async_contains,
+            lookup_id=lookup_id,
+            keys=keys,
+            pin=pin,
+            priority=Priorities.LEASE,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        """Indicate support for non-blocking batched GET."""
+        return True
+
+    async def _batched_get_non_blocking(
+        self, lookup_id: str, keys: List[CacheEngineKey]
+    ) -> List[MemoryObj]:
+        """Prefetch multiple keys and filter out None results."""
+        results = await self.batched_get(keys)
+        return [r for r in results if r is not None]
+
+    async def batched_get_non_blocking(
+        self, lookup_id: str, keys: List[CacheEngineKey]
+    ) -> List[MemoryObj]:
+        """Prefetch multiple keys (queued with priority)."""
+        return await self.pq_executor.submit_job(
+            self._batched_get_non_blocking,
+            lookup_id=lookup_id,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+    def support_batched_get(self) -> bool:
+        """Indicate support for batched GET operations."""
+        return True
+
+    async def list(self) -> List[str]:
+        """List operation not supported by ai-toolkit."""
+        return []
+
+    def remove_sync(self, key: CacheEngineKey) -> bool:
+        """Remove operation not supported by ai-toolkit."""
+        return True
+
+    def support_ping(self) -> bool:
+        """Indicate ping operation is not supported."""
+        return False
+
+    async def ping(self) -> int:
+        """Ping operation not implemented."""
+        raise NotImplementedError(
+            "Ping operation not supported by SageMaker HyperPod connector"
+        )
+
+    async def close(self):
+        """Clean up all resources and log statistics."""
+        # Log final statistics
+        logger.info(
+            f"SageMaker HyperPod Connector Statistics: "
+            f"GET(ok/fail)={self.stats['get_success']}/{self.stats['get_failure']}, "
+            f"PUT(ok/fail)={self.stats['put_success']}/{self.stats['put_failure']}, "
+            f"leases(acq/rel/fail)={self.stats['lease_acquired']}/"
+            f"{self.stats['lease_released']}/{self.stats['lease_release_failed']}"
+        )
+
+        # Shutdown priority queue executor
+        try:
+            await self.pq_executor.shutdown(wait=True)
+        except Exception as e:
+            logger.warning(f"Error shutting down executor: {e}")
+
+        # Close HTTP session
+        if self.http_session is not None:
+            try:
+                await self.http_session.close()
+            except Exception as e:
+                logger.warning(f"Error closing HTTP session: {e}")
+            self.http_session = None
+
+        # Release shared memory
+        if self.shared_memory_map is not None:
+            self.shared_memory_map = None
+
+        if self.shared_memory_obj is not None:
+            try:
+                self.shared_memory_obj.close()
+            except Exception as e:
+                logger.warning(f"Error closing shared memory object: {e}")
+            self.shared_memory_obj = None
+
+        logger.info("SageMaker HyperPod connector closed")
diff --git a/lmcache/v1/storage_backend/connector/valkey_adapter.py b/lmcache/v1/storage_backend/connector/valkey_adapter.py
new file mode 100644
index 0000000..6ff57bb
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/valkey_adapter.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config_base import _to_bool
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    parse_remote_url,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+logger = init_logger(__name__)
+
+
+class ValkeyConnectorAdapter(ConnectorAdapter):
+    """Adapter for the ValkeyConnector (``valkey://`` scheme).
+
+    Uses the GLIDE sync client with a ThreadPoolExecutor for
+    high-throughput KV cache transfer.  Supports both standalone
+    (default) and cluster modes via ``valkey_mode`` config.
+
+    Optionally sets a per-key TTL (``valkey_enable_ttl`` + ``valkey_ttl_sec``) so
+    Valkey/Redis ``volatile-*`` eviction policies can reclaim L2 cache keys
+    under memory pressure.
+
+    Like ``RESPConnectorAdapter``, this adapter uses single-key, fixed-size
+    storage with no per-chunk metadata, so partial/unfull chunks are not
+    supported: ``save_chunk_meta`` and ``save_unfull_chunk`` must both be
+    ``False``.
+
+    Requires ``valkey-glide`` 2.3+.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("valkey://")
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """Create a ValkeyConnector from the given context.
+
+        Args:
+            context: Connector creation context containing URL, config,
+                event loop, and local CPU backend.
+
+        Returns:
+            A configured ValkeyConnector instance.
+        """
+        # Local
+        from .valkey_connector import (
+            DEFAULT_CONNECTION_TIMEOUT_SECS,
+            DEFAULT_REQUEST_TIMEOUT_SECS,
+            DEFAULT_TTL_SECS,
+            ValkeyConnector,
+        )
+
+        config = context.config
+        extra_config = (
+            config.extra_config
+            if config is not None and config.extra_config is not None
+            else {}
+        )
+
+        # Single-key fixed-size storage (like RESP) carries no per-chunk
+        # metadata, so partial/unfull chunks are unsupported. save_chunk_meta
+        # comes from free-form extra_config, so coerce it (a string like
+        # "false" would otherwise be truthy).
+        if _to_bool(extra_config.get("save_chunk_meta", False)):
+            raise ValueError("save_chunk_meta must be False for Valkey glide connector")
+        if config is not None and config.save_unfull_chunk:
+            raise ValueError(
+                "save_unfull_chunk must be False for Valkey glide connector"
+            )
+
+        num_workers = int(
+            extra_config.get(
+                "valkey_num_workers",
+                extra_config.get("valkey_sync_num_workers", 8),
+            )
+        )
+        username = str(extra_config.get("valkey_username", ""))
+        password = str(extra_config.get("valkey_password", ""))
+        tls_enable = _to_bool(extra_config.get("tls_enable", False))
+
+        # Timeouts
+        request_timeout = float(
+            extra_config.get(
+                "request_timeout",
+                config.blocking_timeout_secs
+                if config is not None and config.blocking_timeout_secs is not None
+                else DEFAULT_REQUEST_TIMEOUT_SECS,
+            )
+        )
+        connection_timeout = float(
+            extra_config.get("connection_timeout", DEFAULT_CONNECTION_TIMEOUT_SECS)
+        )
+
+        # Mode: "standalone" (default) or "cluster"
+        valkey_mode = str(extra_config.get("valkey_mode", "standalone"))
+        cluster_mode = valkey_mode == "cluster"
+
+        # Database ID (standalone only — cluster always uses DB 0)
+        database_id: Optional[int] = None
+        raw_db = extra_config.get("valkey_database", None)
+        if raw_db is not None:
+            database_id = int(raw_db)
+            if cluster_mode:
+                logger.warning(
+                    "valkey_database=%s is ignored in cluster mode "
+                    "(Valkey cluster always uses DB 0).",
+                    database_id,
+                )
+                database_id = None
+
+        # TTL feature flag (volatile-* eviction support).
+        #
+        # Without a TTL, keys are persisted indefinitely; a Valkey/Redis node
+        # using a ``volatile-lru``/``volatile-lfu`` eviction policy will never
+        # evict them and the L2 remote cache chokes once ``maxmemory`` is hit.
+        # Enabling ``valkey_enable_ttl`` makes every key expire after
+        # ``valkey_ttl_sec`` seconds so the eviction policy can reclaim memory.
+        ttl_seconds: Optional[int] = None
+        if _to_bool(extra_config.get("valkey_enable_ttl", False)):
+            raw_ttl = extra_config.get("valkey_ttl_sec", None)
+            if raw_ttl is None:
+                ttl_seconds = DEFAULT_TTL_SECS
+                logger.warning(
+                    "valkey_enable_ttl is enabled but valkey_ttl_sec is not set; "
+                    "defaulting key TTL to %d seconds.",
+                    ttl_seconds,
+                )
+            else:
+                # bool is a subclass of int, so a boolean (e.g. ``True``)
+                # would otherwise coerce to a 1-second TTL — reject it.
+                if isinstance(raw_ttl, bool):
+                    raise ValueError(
+                        f"valkey_ttl_sec must be a positive integer number of "
+                        f"seconds, got {raw_ttl!r}."
+                    )
+                try:
+                    ttl_seconds = int(float(raw_ttl))
+                except (ValueError, TypeError) as e:
+                    raise ValueError(
+                        f"valkey_ttl_sec must be a positive integer number of "
+                        f"seconds, got {raw_ttl!r}."
+                    ) from e
+                if ttl_seconds <= 0:
+                    raise ValueError(
+                        f"valkey_ttl_sec must be a positive number of seconds, "
+                        f"got {ttl_seconds}."
+                    )
+
+        parsed_url = parse_remote_url(context.url)
+        logger.info(
+            "Creating Valkey connector for %s:%d (mode=%s, ttl_seconds=%s)",
+            parsed_url.host,
+            parsed_url.port,
+            valkey_mode,
+            ttl_seconds,
+        )
+        return ValkeyConnector(
+            host=parsed_url.host,
+            port=parsed_url.port,
+            loop=context.loop,
+            local_cpu_backend=context.local_cpu_backend,
+            num_workers=num_workers,
+            username=username,
+            password=password,
+            request_timeout=request_timeout,
+            connection_timeout=connection_timeout,
+            tls_enable=tls_enable,
+            cluster_mode=cluster_mode,
+            database_id=database_id,
+            ttl_seconds=ttl_seconds,
+        )
diff --git a/lmcache/v1/storage_backend/connector/valkey_connector.py b/lmcache/v1/storage_backend/connector/valkey_connector.py
new file mode 100644
index 0000000..0e6bf0e
--- /dev/null
+++ b/lmcache/v1/storage_backend/connector/valkey_connector.py
@@ -0,0 +1,724 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+ValkeyConnector — high-throughput Valkey connector using the GLIDE sync
+client (standalone or cluster) with a ThreadPoolExecutor and per-thread clients.
+
+This replaces the legacy async ValkeyConnector / ValkeyClusterConnector
+that used the async GLIDE client with 2-key storage.  The implementation
+is shared with ``sync_valkey_connector.SyncValkeyConnector`` (which
+registers on the ``valkey-sync://`` scheme as a backward-compat alias).
+
+Design choices:
+- N worker threads, each with its own GLIDE sync client
+  (``GlideClient`` in standalone mode, ``GlideClusterClient`` in cluster mode)
+  via ``threading.local()``, enabling true parallel I/O when the GIL is
+  released during FFI calls.
+- Direct ``memoryview`` access to pinned CPU memory — no shared-memory
+  arena or cross-process copies needed since threads share the parent's
+  address space.
+- Single-key storage (like RESPConnector) to halve Valkey round-trips
+  compared to the legacy 2-key metadata/kv_bytes split.
+- Priority scheduling via ``AsyncPQExecutor`` (PEEK > PREFETCH > GET > PUT)
+  ensures latency-sensitive lookups are not delayed behind bulk writes,
+  matching the priority scheme used by ``RESPConnector``.
+
+Migration notes from the old ValkeyConnector:
+- Standalone mode (default) uses ``GlideClient`` and supports ``database_id``.
+- Cluster mode (``valkey_mode: "cluster"``) uses ``GlideClusterClient`` which
+  auto-discovers cluster topology from a single seed node.
+
+Requires ``valkey-glide`` with PRs #5492 (zero-copy SET) and #5493 (buffer GET).
+"""
+
+# Standard
+from concurrent.futures import Future, ThreadPoolExecutor
+from enum import IntEnum, auto
+from typing import TYPE_CHECKING, List, Optional
+import asyncio
+import inspect
+import threading
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.job_executor.pq_executor import AsyncPQExecutor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+if TYPE_CHECKING:
+    # Third Party
+    import glide_sync  # type: ignore[import-untyped]
+
+logger = init_logger(__name__)
+
+#: Default request timeout (seconds).
+DEFAULT_REQUEST_TIMEOUT_SECS: float = 5.0
+#: Default connection timeout (seconds).
+DEFAULT_CONNECTION_TIMEOUT_SECS: float = 10.0
+#: Default key TTL (seconds) used when the TTL feature flag is enabled but no
+#: explicit ``valkey_ttl_sec`` is configured (24 hours).
+DEFAULT_TTL_SECS: int = 86400
+
+
+class Priorities(IntEnum):
+    """Operation priorities for the ``AsyncPQExecutor``.
+
+    Lower numeric value = higher priority.  Matches the scheme used by
+    ``RESPConnector`` so that exists/peek checks run before bulk writes.
+    """
+
+    PEEK = auto()
+    PREFETCH = auto()
+    GET = auto()
+    PUT = auto()
+
+
+class _ThreadWorkerPool:
+    """Manages a pool of threads, each with its own GLIDE sync client.
+
+    Each thread gets an independent GLIDE sync client
+    (``GlideClient`` or ``GlideClusterClient``) via
+    ``threading.local()``, enabling true parallel I/O when the GIL is
+    released during FFI calls.
+
+    Args:
+        host: Valkey server hostname.
+        port: Valkey server port.
+        num_workers: Number of worker threads.
+        username: Valkey authentication username.
+        password: Valkey authentication password.
+        request_timeout: Timeout in seconds for GLIDE requests and
+            Future.result() calls.
+        connection_timeout: Timeout in seconds for initial GLIDE client
+            connections and thread pool warmup.
+        tls_enable: Whether to use TLS for Valkey connections.
+        cluster_mode: If True, use GlideClusterClient; else GlideClient.
+        database_id: Database ID for standalone mode (ignored in cluster).
+        ttl_seconds: If set, every key is written with this expiry (in
+            seconds) so Valkey/Redis ``volatile-*`` eviction policies can
+            reclaim L2 cache keys under memory pressure. ``None`` (default)
+            disables TTL — keys are persisted without expiry.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        num_workers: int,
+        username: str,
+        password: str,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT_SECS,
+        connection_timeout: float = DEFAULT_CONNECTION_TIMEOUT_SECS,
+        tls_enable: bool = False,
+        cluster_mode: bool = False,
+        database_id: Optional[int] = None,
+        ttl_seconds: Optional[int] = None,
+    ):
+        self.num_workers = num_workers
+        self._host = host
+        self._port = port
+        self._username = username
+        self._password = password
+        self._request_timeout = request_timeout
+        self._request_timeout_ms = int(request_timeout * 1000)
+        self._connection_timeout_ms = int(connection_timeout * 1000)
+        self._tls_enable = tls_enable
+        self._cluster_mode = cluster_mode
+        self._database_id = database_id
+        self._ttl_seconds = ttl_seconds
+        self._expiry_obj = None  # lazily built ExpirySet (see _do_set)
+        self._local = threading.local()
+        self._has_buffer_get: Optional[bool] = None
+
+        self._executor = ThreadPoolExecutor(
+            max_workers=num_workers,
+            thread_name_prefix="valkey",
+        )
+        # Warm up: create a client on each thread
+        futs = [self._executor.submit(self._get_client) for _ in range(num_workers)]
+        for f in futs:
+            f.result(timeout=connection_timeout)
+        mode_str = "cluster" if cluster_mode else "standalone"
+        logger.info(
+            "Valkey thread pool: %d threads, mode=%s, per-thread clients, "
+            "buffer_get=%s, ttl_seconds=%s",
+            num_workers,
+            mode_str,
+            self._has_buffer_get,
+            ttl_seconds,
+        )
+
+    def _get_client(self):  # type: ignore[no-untyped-def]
+        """Get or create the per-thread GLIDE sync client.
+
+        Creates a ``GlideClusterClient`` (cluster mode) or ``GlideClient``
+        (standalone mode) depending on the ``cluster_mode`` flag.
+        """
+        # Third Party
+        import glide_sync  # type: ignore[import-untyped]
+
+        client = getattr(self._local, "client", None)
+        if client is not None:
+            return client
+
+        credentials = None
+        if self._username or self._password:
+            credentials = glide_sync.ServerCredentials(self._username, self._password)
+
+        address = glide_sync.NodeAddress(self._host, self._port)
+
+        if self._cluster_mode:
+            advanced = glide_sync.AdvancedGlideClusterClientConfiguration(
+                connection_timeout=self._connection_timeout_ms,
+            )
+            config_kwargs: dict = {
+                "addresses": [address],
+                "request_timeout": self._request_timeout_ms,
+                "use_tls": self._tls_enable,
+                "advanced_config": advanced,
+            }
+            if credentials is not None:
+                config_kwargs["credentials"] = credentials
+            config = glide_sync.GlideClusterClientConfiguration(**config_kwargs)
+            client = glide_sync.GlideClusterClient.create(config)
+        else:
+            # Standalone mode — supports database_id and advanced config
+            advanced = glide_sync.AdvancedGlideClientConfiguration(
+                connection_timeout=self._connection_timeout_ms,
+            )
+            config_kwargs = {
+                "addresses": [address],
+                "request_timeout": self._request_timeout_ms,
+                "use_tls": self._tls_enable,
+                "advanced_config": advanced,
+            }
+            if credentials is not None:
+                config_kwargs["credentials"] = credentials
+            if self._database_id is not None:
+                config_kwargs["database_id"] = self._database_id
+            config = glide_sync.GlideClientConfiguration(**config_kwargs)
+            client = glide_sync.GlideClient.create(config)
+
+        self._local.client = client
+
+        if self._has_buffer_get is None:
+            self._has_buffer_get = "buffer" in inspect.signature(client.get).parameters
+
+        return client
+
+    @property
+    def has_buffer_get(self) -> bool:
+        """Whether the GLIDE client supports buffer GET."""
+        if self._has_buffer_get is None:
+            self._executor.submit(self._get_client).result(
+                timeout=self._connection_timeout_ms / 1000
+            )
+        return bool(self._has_buffer_get)
+
+    def _build_expiry(self) -> "glide_sync.ExpirySet":
+        """Lazily build (and cache) the GLIDE ``ExpirySet`` for SET calls.
+
+        Built lazily so ``glide_sync`` is only imported on worker threads
+        (matching ``_get_client``). The resulting ``ExpirySet`` is an
+        immutable value object, so it is safe to share across threads; a
+        benign race during lazy init just rebuilds an equivalent object.
+        """
+        exp = self._expiry_obj
+        if exp is None:
+            if self._ttl_seconds is None:
+                raise ValueError("ttl_seconds must be set to build an ExpirySet")
+            # Third Party
+            import glide_sync  # type: ignore[import-untyped]
+
+            exp = glide_sync.ExpirySet(glide_sync.ExpiryType.SEC, self._ttl_seconds)
+            self._expiry_obj = exp
+        return exp
+
+    def _do_set(self, key_str: str, data: bytes) -> None:
+        """SET a key (runs on a worker thread).
+
+        When a TTL is configured (``ttl_seconds`` is not None), the key is
+        written with an expiry so that Valkey/Redis ``volatile-*`` eviction
+        policies can reclaim it once the node reaches ``maxmemory``. Without
+        a TTL the key is persisted indefinitely (legacy behavior).
+        """
+        expiry = self._build_expiry() if self._ttl_seconds is not None else None
+        self._get_client().set(key_str.encode(), data, expiry=expiry)
+
+    def _get_scratch(self, size: int) -> bytearray:
+        """Per-thread reusable staging buffer for buffer-GET (issue #6215).
+
+        GLIDE writes into this thread-private bytearray (not slab memory),
+        then we copy into the destination under the GIL.  Eliminates the
+        dangling-slot race without pinning or touching ref_count/pin_count.
+        The buffer is grown on demand and reused across GETs on the same
+        worker thread, so there is no per-call allocation.
+        """
+        buf = getattr(self._local, "scratch", None)
+        if buf is None or len(buf) < size:
+            buf = bytearray(size)
+            self._local.scratch = buf
+        return buf
+
+    def _do_get_into(self, key_str: str, buf: memoryview) -> bool:
+        """GET a key into a buffer (runs on a worker thread).
+
+        Safety (issue #6215): GLIDE's native buffer-GET writes with the GIL
+        released, so it must never write directly into ``buf`` when ``buf``
+        aliases slab-allocator memory that another thread could recycle
+        mid-write.  We stage into a thread-private scratch buffer and copy
+        into ``buf`` under the GIL.
+        """
+        client = self._get_client()
+        if self._has_buffer_get:
+            size = buf.nbytes
+            scratch = self._get_scratch(size)
+            scratch_view = memoryview(scratch)[:size]
+            result = client.get(key_str.encode(), buffer=scratch_view)
+            if result is None:
+                return False
+            n = int(result)
+            if n != size:
+                # Fixed-size KV chunks must round-trip exactly. A short read
+                # signals a size mismatch / corrupt or stale-format entry;
+                # treat it as a miss rather than leaving stale tail bytes in
+                # buf[n:] and reporting success.
+                logger.warning(
+                    "Valkey GET size mismatch for key %s: read %d bytes, "
+                    "expected %d; treating as miss.",
+                    key_str,
+                    n,
+                    size,
+                )
+                return False
+            buf[:n] = scratch_view[:n]
+            return True
+        else:
+            data = client.get(key_str.encode())
+            if data is None:
+                return False
+            if len(data) != buf.nbytes:
+                logger.warning(
+                    "Valkey GET size mismatch for key %s: read %d bytes, "
+                    "expected %d; treating as miss.",
+                    key_str,
+                    len(data),
+                    buf.nbytes,
+                )
+                return False
+            buf[: len(data)] = data
+            return True
+
+    def _do_exists(self, key_str: str) -> bool:
+        """Check if a key exists (runs on a worker thread)."""
+        return bool(self._get_client().exists([key_str.encode()]))
+
+    def submit_set(self, key_str: str, data: bytes) -> Future:
+        """Submit a SET operation."""
+        return self._executor.submit(self._do_set, key_str, data)
+
+    def submit_get_into(self, key_str: str, buf: memoryview) -> Future:
+        """Submit a GET-into-buffer operation."""
+        return self._executor.submit(self._do_get_into, key_str, buf)
+
+    def submit_exists(self, key_str: str) -> Future:
+        """Submit an EXISTS check."""
+        return self._executor.submit(self._do_exists, key_str)
+
+    def _close_client(self) -> None:
+        """Close the per-thread GLIDE client (runs on a worker thread)."""
+        client = getattr(self._local, "client", None)
+        if client is not None:
+            try:
+                client.close()
+            except Exception as exc:
+                logger.debug("Error closing per-thread GLIDE client: %s", exc)
+            self._local.client = None
+
+    def close(self) -> None:
+        """Shut down all per-thread GLIDE clients and the thread pool."""
+        close_futs = [
+            self._executor.submit(self._close_client) for _ in range(self.num_workers)
+        ]
+        for f in close_futs:
+            try:
+                f.result(timeout=self._request_timeout)
+            except Exception as exc:
+                logger.debug("Error during client close: %s", exc)
+        self._executor.shutdown(wait=True, cancel_futures=False)
+        logger.info("Valkey thread pool closed")
+
+
+class ValkeyConnector(RemoteConnector):
+    """High-throughput Valkey connector using GLIDE sync cluster client with
+    per-thread clients, ThreadPoolExecutor, and priority scheduling.
+
+    Uses N worker threads, each with its own GLIDE sync client, and
+    direct memoryview access for zero-copy data transfer.  Single-key
+    storage halves Valkey round-trips compared to the legacy 2-key split.
+
+    Operations are dispatched through an ``AsyncPQExecutor`` with priority
+    levels (PEEK > PREFETCH > GET > PUT) so that latency-sensitive lookups
+    are not delayed behind bulk writes.
+
+    Args:
+        host: Valkey server hostname.
+        port: Valkey server port.
+        loop: Asyncio event loop (used for PQ executor and wrap_future).
+        local_cpu_backend: Backend for allocating CPU memory objects.
+        num_workers: Number of worker threads (default 8).
+        username: Valkey authentication username.
+        password: Valkey authentication password.
+        request_timeout: Timeout in seconds for requests and
+            Future.result() calls (default 5).
+        connection_timeout: Timeout in seconds for initial client
+            connections (default 10).
+        tls_enable: Whether to use TLS for Valkey connections.
+        cluster_mode: If True, use GlideClusterClient; else GlideClient.
+        database_id: Database ID for standalone mode (ignored in cluster).
+        ttl_seconds: If set, keys are written with this expiry (seconds) so
+            ``volatile-*`` eviction policies can reclaim them. ``None``
+            (default) disables TTL.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        num_workers: int = 8,
+        username: str = "",
+        password: str = "",
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT_SECS,
+        connection_timeout: float = DEFAULT_CONNECTION_TIMEOUT_SECS,
+        tls_enable: bool = False,
+        cluster_mode: bool = False,
+        database_id: Optional[int] = None,
+        ttl_seconds: Optional[int] = None,
+    ):
+        super().__init__(local_cpu_backend.config, local_cpu_backend.metadata)
+
+        self.host = host
+        self.port = port
+        self.num_workers = num_workers
+        self._request_timeout = request_timeout
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        self._pool = _ThreadWorkerPool(
+            host,
+            port,
+            num_workers,
+            username,
+            password,
+            request_timeout=request_timeout,
+            connection_timeout=connection_timeout,
+            tls_enable=tls_enable,
+            cluster_mode=cluster_mode,
+            database_id=database_id,
+            ttl_seconds=ttl_seconds,
+        )
+        self._pq_executor = AsyncPQExecutor(loop)
+
+    # ── EXISTS ───────────────────────────────────────────────────────────
+
+    async def _exists(self, key: CacheEngineKey) -> bool:
+        """Internal: check if a key exists in Valkey."""
+        return await asyncio.wrap_future(self._pool.submit_exists(key.to_string()))
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """Check if a key exists in Valkey."""
+        return await self._pq_executor.submit_job(
+            self._exists, key=key, priority=Priorities.PEEK
+        )
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Synchronously check if a key exists in Valkey."""
+        return self._pool.submit_exists(key.to_string()).result(
+            timeout=self._request_timeout
+        )
+
+    # ── GET ──────────────────────────────────────────────────────────────
+
+    async def _get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Internal: retrieve a memory object from Valkey by key."""
+        memory_obj = self.local_cpu_backend.allocate(
+            self.meta_shapes, self.meta_dtypes, self.meta_fmt
+        )
+        if memory_obj is None:
+            logger.warning("Failed to allocate memory during remote receive")
+            return None
+
+        dst = memory_obj.byte_array
+        if not isinstance(dst, memoryview):
+            dst = memoryview(dst)
+        if dst.format != "B":
+            dst = dst.cast("B")
+
+        try:
+            found = await asyncio.wrap_future(
+                self._pool.submit_get_into(key.to_string(), dst)
+            )
+        except Exception:
+            memory_obj.ref_count_down()
+            raise
+
+        if not found:
+            memory_obj.ref_count_down()
+            return None
+        return memory_obj
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Retrieve a memory object from Valkey by key."""
+        return await self._pq_executor.submit_job(
+            self._get, key=key, priority=Priorities.GET
+        )
+
+    # ── PUT ──────────────────────────────────────────────────────────────
+
+    async def _put(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        """Internal: store a memory object in Valkey.
+
+        Note: This method does NOT call ``ref_count_down()`` on the memory
+        object.  Reference counting is managed by the caller
+        (``RemoteBackend.submit_put_task``), which increments before
+        submitting and decrements in the done callback.
+        """
+        await asyncio.wrap_future(
+            self._pool.submit_set(key.to_string(), memory_obj.byte_array)
+        )
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        """Store a memory object in Valkey."""
+        await self._pq_executor.submit_job(
+            self._put, key=key, memory_obj=memory_obj, priority=Priorities.PUT
+        )
+
+    # ── BATCHED PUT ──────────────────────────────────────────────────────
+
+    def support_batched_put(self) -> bool:
+        """Returns True — batched put is supported."""
+        return True
+
+    async def _batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ) -> None:
+        """Internal: store multiple memory objects in Valkey in parallel."""
+        n = len(keys)
+        key_strs = [k.to_string() for k in keys]
+
+        futures = [
+            self._pool.submit_set(key_strs[i], memory_objs[i].byte_array)
+            for i in range(n)
+        ]
+        wrapped = [asyncio.wrap_future(f) for f in futures]
+        await asyncio.gather(*wrapped)
+
+    async def batched_put(
+        self, keys: List[CacheEngineKey], memory_objs: List[MemoryObj]
+    ) -> None:
+        """Store multiple memory objects in Valkey in parallel."""
+        await self._pq_executor.submit_job(
+            self._batched_put,
+            keys=keys,
+            memory_objs=memory_objs,
+            priority=Priorities.PUT,
+        )
+
+    # ── BATCHED GET ──────────────────────────────────────────────────────
+
+    def support_batched_get(self) -> bool:
+        """Returns True — batched get is supported."""
+        return True
+
+    async def _batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """Internal: retrieve multiple memory objects from Valkey in parallel.
+
+        Note: Once an allocation failure occurs, all subsequent slots are
+        set to ``None`` (intentional — memory pressure means further
+        allocations would also fail).
+        """
+        n = len(keys)
+        key_strs = [k.to_string() for k in keys]
+
+        memory_objs: List[Optional[MemoryObj]] = []
+        dst_bufs: List[Optional[memoryview]] = []
+        alloc_failed = False
+
+        for _ in keys:
+            if alloc_failed:
+                memory_objs.append(None)
+                dst_bufs.append(None)
+                continue
+
+            mobj = self.local_cpu_backend.allocate(
+                self.meta_shapes, self.meta_dtypes, self.meta_fmt
+            )
+            if mobj is None:
+                logger.warning(
+                    "Failed to allocate memory during batched remote receive"
+                )
+                alloc_failed = True
+                memory_objs.append(None)
+                dst_bufs.append(None)
+                continue
+
+            memory_objs.append(mobj)
+            dst = mobj.byte_array
+            if not isinstance(dst, memoryview):
+                dst = memoryview(dst)
+            if dst.format != "B":
+                dst = dst.cast("B")
+            dst_bufs.append(dst)
+
+        # Submit GET futures for allocated slots; track which indices have
+        # real futures vs None (allocation failed).
+        live_indices: List[int] = []
+        live_futures: List[asyncio.Future] = []
+        for i in range(n):
+            if memory_objs[i] is not None and dst_bufs[i] is not None:
+                live_indices.append(i)
+                live_futures.append(
+                    asyncio.wrap_future(
+                        self._pool.submit_get_into(
+                            key_strs[i],
+                            dst_bufs[i],  # type: ignore[arg-type]
+                        )
+                    )
+                )
+
+        try:
+            results = await asyncio.gather(*live_futures)
+            for idx, found in zip(live_indices, results, strict=True):
+                if not found:
+                    memory_objs[idx].ref_count_down()  # type: ignore[union-attr]
+                    memory_objs[idx] = None
+        except Exception:
+            for mobj in memory_objs:
+                if mobj is not None:
+                    mobj.ref_count_down()
+            raise
+
+        return memory_objs
+
+    async def batched_get(
+        self, keys: List[CacheEngineKey]
+    ) -> List[Optional[MemoryObj]]:
+        """Retrieve multiple memory objects from Valkey in parallel."""
+        return await self._pq_executor.submit_job(
+            self._batched_get, keys=keys, priority=Priorities.GET
+        )
+
+    # ── BATCHED CONTAINS ─────────────────────────────────────────────────
+
+    def support_batched_contains(self) -> bool:
+        """Returns True — synchronous batched contains is supported."""
+        return True
+
+    def _count_consecutive_exists(self, keys: List[CacheEngineKey]) -> int:
+        """Check how many consecutive keys exist (prefix match).
+
+        Fans out individual EXISTS checks across the thread pool for
+        parallel round-trips: wall-clock time is roughly
+        ``ceil(N / num_workers) * RTT`` instead of ``N * RTT``.
+        """
+        key_strs = [k.to_string() for k in keys]
+        futures = [self._pool.submit_exists(k) for k in key_strs]
+        for i, fut in enumerate(futures):
+            if not fut.result(timeout=self._request_timeout):
+                return i
+        return len(futures)
+
+    def batched_contains(self, keys: List[CacheEngineKey]) -> int:
+        """Synchronously check how many consecutive keys exist."""
+        return self._count_consecutive_exists(keys)
+
+    def support_batched_async_contains(self) -> bool:
+        """Returns True — async batched contains is supported."""
+        return True
+
+    async def _batched_async_contains(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> int:
+        """Internal: asynchronously check how many consecutive keys exist.
+
+        Fans out individual EXISTS checks across the thread pool.
+        """
+        key_strs = [k.to_string() for k in keys]
+        wrapped = [asyncio.wrap_future(self._pool.submit_exists(k)) for k in key_strs]
+        results = await asyncio.gather(*wrapped)
+        for i, r in enumerate(results):
+            if not r:
+                return i
+        return len(results)
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Asynchronously check how many consecutive keys exist."""
+        return await self._pq_executor.submit_job(
+            self._batched_async_contains,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+    def support_batched_get_non_blocking(self) -> bool:
+        """Returns True — non-blocking batched get is supported."""
+        return True
+
+    async def _batched_get_non_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        """Internal: non-blocking batched get returning the consecutive prefix.
+
+        Only the consecutive prefix of non-None memory objects (from the
+        beginning) is returned.  Once a ``None`` (missing key or allocation
+        failure) is encountered, all subsequent objects — even if they were
+        successfully retrieved — are released and excluded.  This matches
+        the base-class contract.
+        """
+        all_results = await self._batched_get(keys)
+
+        prefix: List[MemoryObj] = []
+        found_failure = False
+        for result in all_results:
+            if found_failure:
+                if result is not None:
+                    result.ref_count_down()
+            elif result is not None:
+                prefix.append(result)
+            else:
+                found_failure = True
+
+        return prefix
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+    ) -> List[MemoryObj]:
+        """Non-blocking batched get returning the consecutive prefix."""
+        return await self._pq_executor.submit_job(
+            self._batched_get_non_blocking,
+            keys=keys,
+            priority=Priorities.PREFETCH,
+        )
+
+    async def list(self) -> List[str]:
+        """List all keys (not implemented)."""
+        return []
+
+    async def close(self) -> None:
+        """Shut down the PQ executor and the thread pool."""
+        await self._pq_executor.shutdown_async(wait=True)
+        self._pool.close()
+        logger.info("Closed ValkeyConnector")
diff --git a/lmcache/v1/storage_backend/dax/__init__.py b/lmcache/v1/storage_backend/dax/__init__.py
new file mode 100644
index 0000000..59dae5f
--- /dev/null
+++ b/lmcache/v1/storage_backend/dax/__init__.py
@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Local
+from .core import DaxCore, DaxReadReservation
+
+__all__ = [
+    "DaxCore",
+    "DaxReadReservation",
+]
diff --git a/lmcache/v1/storage_backend/dax/core.py b/lmcache/v1/storage_backend/dax/core.py
new file mode 100644
index 0000000..6185340
--- /dev/null
+++ b/lmcache/v1/storage_backend/dax/core.py
@@ -0,0 +1,1094 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import Callable, Generic, Hashable, Optional, TypeVar
+import ctypes
+import enum
+import mmap
+import os
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import DiskCacheMetadata
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+
+logger = init_logger(__name__)
+
+KeyT = TypeVar("KeyT", bound=Hashable)
+_CopyFn = Callable[[int, MemoryObj, int], None]
+
+
+class DaxPutFromPtrResult(enum.Enum):
+    """Result of copying a reserved source payload into a DAX slot."""
+
+    INSERTED = enum.auto()
+    ALREADY_EXISTS = enum.auto()
+    INFLIGHT = enum.auto()
+    NO_SPACE = enum.auto()
+    CLOSED = enum.auto()
+    INVALID = enum.auto()
+    COPY_FAILED = enum.auto()
+
+
+@dataclass
+class _Entry:
+    offset: int
+    meta: DiskCacheMetadata
+    slot_id: int
+    generation: int
+
+
+@dataclass
+class _Inflight:
+    offset: int
+    meta: DiskCacheMetadata
+    slot_id: int
+    generation: int
+    canceled: bool = False
+
+
+@dataclass
+class _SlotState:
+    generation: int
+    committed: bool = False
+    borrow_count: int = 0
+    pending_free: bool = False
+
+
+@dataclass(frozen=True)
+class DaxReadReservation(Generic[KeyT]):
+    """A committed DAX entry reserved for a read or restore operation."""
+
+    result_index: int
+    key: KeyT
+    offset: int
+    size: int
+    shape: torch.Size
+    dtype: torch.dtype
+    fmt: MemoryFormat
+    cached_positions: Optional[torch.Tensor]
+    slot_id: int
+    generation: int
+
+
+class DaxCore(Generic[KeyT]):
+    """Thread-safe shared core for DAX-backed fixed-slot storage.
+
+    ``DaxCore`` owns the mapped arena, in-memory key index, slot allocator,
+    external lock refcounts, and read borrow counts. Eviction policy is owned
+    by LMCache controllers, not by the DAX core.
+    """
+
+    def __init__(
+        self,
+        *,
+        device_path: str,
+        max_dax_size_bytes: int,
+        slot_bytes: int,
+    ) -> None:
+        """Open and map a DAX arena.
+
+        Args:
+            device_path: Path to the mmap-able DAX device or file.
+            max_dax_size_bytes: Number of bytes to map from the device.
+            slot_bytes: Fixed slot size used for each stored object.
+
+        Raises:
+            ValueError: If the path is empty, sizes are non-positive, or the
+                arena cannot fit at least one slot.
+            RuntimeError: If the device cannot be opened or mapped, or if
+                ``max_dax_size_bytes`` exceeds the reported device capacity.
+        """
+        self._device_path = device_path
+        self._arena_bytes = max_dax_size_bytes
+        self._slot_bytes = slot_bytes
+
+        if not self._device_path:
+            raise ValueError("device_path must be a non-empty string")
+        if self._arena_bytes <= 0:
+            raise ValueError("max_dax_size_bytes must be > 0")
+        if self._slot_bytes <= 0:
+            raise ValueError("slot_bytes must be > 0")
+
+        self._fd: Optional[int] = None
+        self._mmap_obj: Optional[mmap.mmap] = None
+        self._arena_view: Optional[memoryview] = None
+        self._base_ptr: int = 0
+
+        self._state_lock = threading.RLock()
+        self._state_condition = threading.Condition(self._state_lock)
+
+        self._index: dict[KeyT, _Entry] = {}
+        self._external_lock_counts: dict[KeyT, int] = {}
+        self._inflight: dict[KeyT, _Inflight] = {}
+        self._slot_states: dict[int, _SlotState] = {}
+
+        self._next_slot = 0
+        self._free_slots: set[int] = set()
+        self._active_writes = 0
+        self._active_reads = 0
+        self._closing = False
+        self._closed = False
+
+        self._open_arena()
+        self._max_slots = self._arena_bytes // self._slot_bytes
+        if self._max_slots <= 0:
+            self.close()
+            raise ValueError("configured arena does not fit even one slot")
+
+    @property
+    def device_path(self) -> str:
+        """Return the path used to open the DAX arena."""
+        return self._device_path
+
+    @property
+    def arena_bytes(self) -> int:
+        """Return the mapped arena size in bytes."""
+        return self._arena_bytes
+
+    @property
+    def slot_bytes(self) -> int:
+        """Return the fixed slot size in bytes."""
+        return self._slot_bytes
+
+    @property
+    def max_slots(self) -> int:
+        """Return the maximum number of slots in the arena."""
+        return self._max_slots
+
+    @property
+    def fd(self) -> Optional[int]:
+        """Return the open device file descriptor, or ``None`` after close."""
+        return self._fd
+
+    @property
+    def mmap_obj(self) -> Optional[mmap.mmap]:
+        """Return the active mmap object, or ``None`` after close."""
+        return self._mmap_obj
+
+    @property
+    def arena_view(self) -> Optional[memoryview]:
+        """Return the active arena memoryview, or ``None`` after close."""
+        return self._arena_view
+
+    @property
+    def base_ptr(self) -> int:
+        """Return the base virtual address of the mapped arena."""
+        return self._base_ptr
+
+    def is_closing(self) -> bool:
+        """Check whether the core is closing or already closed.
+
+        Returns:
+            ``True`` after close has begun, otherwise ``False``.
+        """
+        with self._state_lock:
+            return self._closing or self._closed
+
+    def has_inflight(self, key: KeyT) -> bool:
+        """Check whether a key currently has an uncommitted write.
+
+        Args:
+            key: Key to check.
+
+        Returns:
+            ``True`` if a write reservation exists for ``key``.
+        """
+        with self._state_lock:
+            return key in self._inflight
+
+    def put_many(
+        self,
+        keys: list[KeyT],
+        objs: list[MemoryObj],
+    ) -> list[bool]:
+        """Store multiple memory objects in DAX slots.
+
+        Existing committed or in-flight keys are treated as no-op successes.
+        Unsupported multi-tensor objects, oversized objects, copy failures,
+        and closing state produce ``False`` for the affected key.
+
+        Args:
+            keys: Keys to store.
+            objs: Memory objects whose contents are copied into DAX.
+
+        Returns:
+            Per-key success flags aligned with ``keys``.
+
+        Raises:
+            ValueError: If ``keys`` and ``objs`` have different lengths.
+        """
+        if len(keys) != len(objs):
+            raise ValueError(
+                "keys and objs must have the same length, "
+                f"got {len(keys)} and {len(objs)}"
+            )
+
+        results: list[bool] = []
+        for key, obj in zip(keys, objs, strict=True):
+            results.append(
+                self._put_one(
+                    key,
+                    obj,
+                    raise_on_full=False,
+                    raise_on_write_failure=False,
+                )
+            )
+        return results
+
+    def put_one(
+        self,
+        key: KeyT,
+        obj: MemoryObj,
+        *,
+        writer: Optional[_CopyFn] = None,
+    ) -> bool:
+        """Store one memory object in a DAX slot.
+
+        This method exists for wrappers that need the existing non-MP
+        single-object error semantics. Slot exhaustion and copy failures raise
+        ``RuntimeError``. MP code should generally use ``put_many`` to
+        preserve per-key success reporting.
+
+        Args:
+            key: Key to store.
+            obj: Memory object whose contents are copied into DAX.
+            writer: Optional copy function accepting
+                ``(dax_offset, memory_obj, size)``. If omitted, direct
+                ``ctypes.memmove`` is used.
+
+        Returns:
+            ``True`` if the key was committed or was already committed or
+            in-flight; ``False`` if the object could not be stored.
+
+        Raises:
+            RuntimeError: If no slot can be allocated or the copy fails.
+        """
+        return self._put_one(
+            key,
+            obj,
+            raise_on_full=True,
+            raise_on_write_failure=True,
+            writer=writer,
+        )
+
+    def exists_many(
+        self,
+        keys: list[KeyT],
+        lock: bool = False,
+    ) -> list[bool]:
+        """Check whether keys exist, optionally acquiring external locks.
+
+        Args:
+            keys: Keys to look up.
+            lock: If ``True``, increment the external lock refcount for each
+                found key.
+
+        Returns:
+            Per-key hit flags aligned with ``keys``.
+        """
+        results = [False] * len(keys)
+        with self._state_lock:
+            if self._closing or self._closed:
+                return results
+
+            for i, key in enumerate(keys):
+                entry = self._index.get(key)
+                if entry is None:
+                    continue
+                if self._get_committed_state_locked(entry) is None:
+                    continue
+                results[i] = True
+                if lock:
+                    self._external_lock_counts[key] = (
+                        self._external_lock_counts.get(key, 0) + 1
+                    )
+        return results
+
+    def load_many_into(
+        self,
+        keys: list[KeyT],
+        objs: list[MemoryObj],
+    ) -> list[bool]:
+        """Load DAX entries directly into caller-provided buffers.
+
+        Args:
+            keys: Keys to load.
+            objs: Destination memory objects. Each destination must have
+                enough capacity for the corresponding stored payload.
+
+        Returns:
+            Per-key success flags aligned with ``keys``.
+
+        Raises:
+            ValueError: If ``keys`` and ``objs`` have different lengths.
+        """
+        if len(keys) != len(objs):
+            raise ValueError(
+                "keys and objs must have the same length, "
+                f"got {len(keys)} and {len(objs)}"
+            )
+
+        reservations, _ = self.reserve_reads(keys, prefix_only=False)
+        results = [False] * len(keys)
+        touched_keys: set[KeyT] = set()
+
+        try:
+            for reservation in reservations:
+                obj = objs[reservation.result_index]
+                if len(obj.get_shapes()) > 1:
+                    continue
+                if int(obj.get_size()) < reservation.size:
+                    continue
+
+                try:
+                    self._default_do_read(reservation.offset, obj, reservation.size)
+                except Exception:
+                    logger.exception(
+                        "Failed to load DAX key %s into caller buffer",
+                        reservation.key,
+                    )
+                    continue
+
+                obj.metadata.cached_positions = reservation.cached_positions
+                results[reservation.result_index] = True
+                touched_keys.add(reservation.key)
+        finally:
+            self.finalize_reads(reservations, touched_keys)
+
+        return results
+
+    def snapshot_keys(self) -> list[KeyT]:
+        """Return committed keys currently indexed by this DAX arena.
+
+        Returns:
+            A snapshot list of keys whose slots are committed and readable at
+            the time of the call. Later writes, deletes, or migration steps do
+            not mutate the returned list.
+        """
+        with self._state_lock:
+            if self._closing or self._closed:
+                return []
+
+            return [
+                key
+                for key, entry in self._index.items()
+                if self._get_committed_state_locked(entry) is not None
+            ]
+
+    def reserve_reads_for_keys(
+        self,
+        keys: list[KeyT],
+    ) -> list[DaxReadReservation[KeyT]]:
+        """Reserve readable slots for explicit keys.
+
+        Args:
+            keys: Keys to reserve for a lock-safe read or migration copy.
+
+        Returns:
+            Reservations for keys that were present and readable. The caller
+            must pass the returned reservations to ``finalize_reads``.
+        """
+        reservations, _ = self.reserve_reads(keys, prefix_only=False)
+        return reservations
+
+    def put_reserved_from_ptr(
+        self,
+        key: KeyT,
+        src_ptr: int,
+        size: int,
+        shape: torch.Size,
+        dtype: torch.dtype,
+        fmt: MemoryFormat,
+        cached_positions: torch.Tensor | None,
+    ) -> DaxPutFromPtrResult:
+        """Store one key by copying from an already reserved source pointer.
+
+        Args:
+            key: Destination key to commit.
+            src_ptr: Source memory address. The caller is responsible for
+                keeping this pointer valid until the call returns.
+            size: Number of bytes to copy.
+            shape: Tensor shape to record for future reads.
+            dtype: Tensor dtype to record for future reads.
+            fmt: Memory format to record for future reads.
+            cached_positions: Optional cached-position metadata.
+
+        Returns:
+            A ``DaxPutFromPtrResult`` describing whether the payload was newly
+            inserted, already present, full, closed, invalid, or failed.
+        """
+        if size <= 0 or size > self._slot_bytes:
+            return DaxPutFromPtrResult.INVALID
+        if src_ptr <= 0:
+            return DaxPutFromPtrResult.INVALID
+
+        with self._state_lock:
+            if self._closing or self._closed:
+                return DaxPutFromPtrResult.CLOSED
+            if key in self._index:
+                return DaxPutFromPtrResult.ALREADY_EXISTS
+            if key in self._inflight:
+                return DaxPutFromPtrResult.INFLIGHT
+
+            try:
+                slot_id = self._allocate_slot_locked()
+            except RuntimeError:
+                return DaxPutFromPtrResult.NO_SPACE
+
+            offset = slot_id * self._slot_bytes
+            generation = self._reserve_slot_state_locked(slot_id)
+            meta = DiskCacheMetadata(
+                path=f"{self._device_path}@{offset}",
+                size=size,
+                shape=shape,
+                dtype=dtype,
+                cached_positions=cached_positions,
+                fmt=fmt,
+                pin_count=0,
+            )
+            self._inflight[key] = _Inflight(
+                offset=offset,
+                meta=meta,
+                slot_id=slot_id,
+                generation=generation,
+            )
+            self._active_writes += 1
+            dst_ptr = self._base_ptr + offset
+
+        write_failed = False
+        try:
+            ctypes.memmove(
+                ctypes.c_void_p(dst_ptr),
+                ctypes.c_void_p(src_ptr),
+                size,
+            )
+        except Exception:
+            logger.exception("Failed to copy reserved DAX payload for key %s", key)
+            write_failed = True
+
+        if self._finalize_put(key, write_failed=write_failed):
+            return DaxPutFromPtrResult.INSERTED
+        return DaxPutFromPtrResult.COPY_FAILED
+
+    def unlock_many(self, keys: list[KeyT]) -> None:
+        """Release external locks for keys.
+
+        Args:
+            keys: Keys whose external lock refcount should be decremented.
+        """
+        with self._state_lock:
+            for key in keys:
+                count = self._external_lock_counts.get(key, 0)
+                if count <= 1:
+                    self._external_lock_counts.pop(key, None)
+                else:
+                    self._external_lock_counts[key] = count - 1
+
+    def delete_many(
+        self,
+        keys: list[KeyT],
+        *,
+        force: bool = False,
+    ) -> list[bool]:
+        """Delete keys from the in-memory DAX index.
+
+        When ``force`` is ``False``, externally locked and in-flight keys are
+        skipped. Slots borrowed by active reads are marked for later reclaim
+        and become reusable after ``finalize_reads`` drains the borrow count.
+
+        Args:
+            keys: Keys to delete.
+            force: If ``True``, remove externally locked keys and cancel
+                in-flight writes. This is used by the non-MP wrapper to keep
+                its existing force-remove behavior.
+
+        Returns:
+            Per-key deletion flags aligned with ``keys``.
+        """
+        results = [False] * len(keys)
+        with self._state_lock:
+            if self._closed:
+                return results
+
+            for i, key in enumerate(keys):
+                inflight = self._inflight.get(key)
+                if inflight is not None:
+                    if not force:
+                        continue
+                    inflight.canceled = True
+                    self._external_lock_counts.pop(key, None)
+                    results[i] = True
+                    continue
+
+                entry = self._index.get(key)
+                if entry is None:
+                    continue
+
+                if not force and self._external_lock_counts.get(key, 0) > 0:
+                    continue
+
+                self._index.pop(key, None)
+                self._external_lock_counts.pop(key, None)
+                self._schedule_slot_reclaim_locked(entry.slot_id, entry.generation)
+                results[i] = True
+
+        return results
+
+    def usage(self) -> tuple[float, float]:
+        """Return current and post-eviction slot usage fractions.
+
+        Returns:
+            ``(current_usage, usage_after_ongoing_eviction)`` where both values
+            are fractions of total slots. The second value subtracts slots
+            already removed from the index but still waiting for read borrows
+            to drain.
+        """
+        with self._state_lock:
+            if self._max_slots <= 0:
+                return (0.0, 0.0)
+
+            live_slot_count = self._next_slot - len(self._free_slots)
+            pending_reclaim_count = sum(
+                1 for state in self._slot_states.values() if state.pending_free
+            )
+            current_usage = live_slot_count / self._max_slots
+            post_eviction_slots = max(0, live_slot_count - pending_reclaim_count)
+            usage_after_eviction = post_eviction_slots / self._max_slots
+            return (current_usage, usage_after_eviction)
+
+    def reserve_reads(
+        self,
+        keys: list[KeyT],
+        *,
+        prefix_only: bool,
+    ) -> tuple[list[DaxReadReservation[KeyT]], list[bool]]:
+        """Reserve committed entries for a read pipeline.
+
+        Each reservation increments the slot borrow count so eviction can
+        remove the key from the index without recycling the slot until
+        ``finalize_reads`` is called.
+
+        Args:
+            keys: Keys to reserve.
+            prefix_only: If ``True``, stop at the first missing or unreadable
+                key. If ``False``, continue and leave holes in the result
+                bitmap.
+
+        Returns:
+            A tuple of read reservations and per-key hit flags aligned with
+            ``keys``.
+        """
+        reservations: list[DaxReadReservation[KeyT]] = []
+        results = [False] * len(keys)
+
+        with self._state_lock:
+            if self._closing or self._closed:
+                return reservations, results
+
+            for i, key in enumerate(keys):
+                entry = self._index.get(key)
+                if entry is None:
+                    if prefix_only:
+                        break
+                    continue
+
+                meta = entry.meta
+                if meta.shape is None or meta.dtype is None or meta.fmt is None:
+                    if prefix_only:
+                        break
+                    continue
+
+                state = self._get_committed_state_locked(entry)
+                if state is None:
+                    if prefix_only:
+                        break
+                    continue
+
+                state.borrow_count += 1
+                reservations.append(
+                    DaxReadReservation(
+                        result_index=i,
+                        key=key,
+                        offset=entry.offset,
+                        size=int(meta.size),
+                        shape=meta.shape,
+                        dtype=meta.dtype,
+                        fmt=meta.fmt,
+                        cached_positions=meta.cached_positions,
+                        slot_id=entry.slot_id,
+                        generation=entry.generation,
+                    )
+                )
+                results[i] = True
+
+            if reservations:
+                self._active_reads += 1
+
+        return reservations, results
+
+    def finalize_reads(
+        self,
+        reservations: list[DaxReadReservation[KeyT]],
+        touched_keys: set[KeyT],
+    ) -> None:
+        """Release read reservations.
+
+        Args:
+            reservations: Reservations previously returned by
+                ``reserve_reads``.
+            touched_keys: Subset of reservation keys whose data was
+                successfully copied. Kept for callers that already track
+                successful reads; DAX core does not own eviction recency.
+        """
+        del touched_keys
+        if not reservations:
+            return
+
+        with self._state_lock:
+            if self._active_reads > 0:
+                self._active_reads -= 1
+            else:
+                logger.warning("DaxCore active read count underflow")
+
+            for reservation in reservations:
+                state = self._slot_states.get(reservation.slot_id)
+                if state is None or state.generation != reservation.generation:
+                    continue
+
+                if state.borrow_count > 0:
+                    state.borrow_count -= 1
+
+                if state.pending_free and state.borrow_count == 0:
+                    state.pending_free = False
+                    self._free_slot_locked(reservation.slot_id)
+
+            self._state_condition.notify_all()
+
+    def can_shrink_to(self, new_max_slots: int) -> bool:
+        """Check whether every live or borrowed slot fits below a new limit.
+
+        Args:
+            new_max_slots: Candidate slot count after a shrink.
+
+        Returns:
+            ``True`` if remapping to ``new_max_slots`` would not invalidate
+            committed, in-flight, or borrowed slot state.
+        """
+        if new_max_slots <= 0:
+            return False
+
+        with self._state_lock:
+            if self._closed:
+                return False
+
+            for entry in self._index.values():
+                if (
+                    self._get_committed_state_locked(entry) is not None
+                    and entry.slot_id >= new_max_slots
+                ):
+                    return False
+            for inflight in self._inflight.values():
+                if inflight.slot_id >= new_max_slots and not inflight.canceled:
+                    return False
+            for slot_id, state in self._slot_states.items():
+                if slot_id >= new_max_slots and state.borrow_count > 0:
+                    return False
+            return True
+
+    def remap(self, new_max_dax_size_bytes: int) -> None:
+        """Remap this arena to a new byte size while preserving metadata.
+
+        Args:
+            new_max_dax_size_bytes: New number of bytes to map.
+
+        Raises:
+            ValueError: If the new size cannot fit at least one slot or would
+                cut off live slot metadata.
+            RuntimeError: If the arena is closed or the mmap operation fails.
+        """
+        if new_max_dax_size_bytes <= 0:
+            raise ValueError("new_max_dax_size_bytes must be > 0")
+        new_max_slots = new_max_dax_size_bytes // self._slot_bytes
+        if new_max_slots <= 0:
+            raise ValueError("new DAX arena does not fit even one slot")
+
+        old_fd: Optional[int] = None
+        old_mmap_obj: Optional[mmap.mmap] = None
+        old_arena_view: Optional[memoryview] = None
+
+        with self._state_lock:
+            if self._closed:
+                raise RuntimeError("DaxCore is closed")
+
+            while self._active_writes > 0 or self._active_reads > 0:
+                if not self._state_condition.wait(timeout=30.0):
+                    logger.warning(
+                        "DaxCore remap: still waiting for %d writes, %d reads",
+                        self._active_writes,
+                        self._active_reads,
+                    )
+
+            if not self.can_shrink_to(new_max_slots):
+                raise ValueError("new DAX arena would cut off live slots")
+
+            old_fd = self._fd
+            old_mmap_obj = self._mmap_obj
+            old_arena_view = self._arena_view
+            old_arena_bytes = self._arena_bytes
+            old_max_slots = self._max_slots
+            old_base_ptr = self._base_ptr
+
+            self._fd = None
+            self._mmap_obj = None
+            self._arena_view = None
+            self._base_ptr = 0
+            self._arena_bytes = new_max_dax_size_bytes
+            self._max_slots = new_max_slots
+
+            try:
+                self._open_arena()
+            except Exception:
+                self._fd = old_fd
+                self._mmap_obj = old_mmap_obj
+                self._arena_view = old_arena_view
+                self._arena_bytes = old_arena_bytes
+                self._max_slots = old_max_slots
+                self._base_ptr = old_base_ptr
+                raise
+
+            self._free_slots = {
+                slot_id for slot_id in self._free_slots if slot_id < new_max_slots
+            }
+            self._next_slot = min(self._next_slot, new_max_slots)
+            self._state_condition.notify_all()
+
+        self._release_arena_resources(old_fd, old_mmap_obj, old_arena_view)
+
+    def close(self) -> None:
+        """Close the DAX arena after active reads and writes finish.
+
+        The call is idempotent. It marks the core as closing, waits for active
+        operations to drain, clears volatile in-memory indexes, and releases
+        the mmap, memoryview, and file descriptor.
+        """
+        fd = None
+        mmap_obj = None
+        arena_view = None
+
+        with self._state_lock:
+            if self._closed:
+                return
+
+            self._closing = True
+            while self._active_writes > 0 or self._active_reads > 0:
+                if not self._state_condition.wait(timeout=30.0):
+                    logger.warning(
+                        "DaxCore close: still waiting for %d writes, %d reads",
+                        self._active_writes,
+                        self._active_reads,
+                    )
+
+            if self._closed:
+                return
+
+            self._closed = True
+            self._index.clear()
+            self._external_lock_counts.clear()
+            self._inflight.clear()
+            self._slot_states.clear()
+            self._free_slots.clear()
+            self._next_slot = 0
+
+            fd = self._fd
+            mmap_obj = self._mmap_obj
+            arena_view = self._arena_view
+            self._fd = None
+            self._mmap_obj = None
+            self._arena_view = None
+            self._base_ptr = 0
+
+        self._release_arena_resources(fd, mmap_obj, arena_view)
+
+    def report_status(self) -> dict:
+        """Return a status snapshot for health and observability.
+
+        Returns:
+            Dictionary containing health, capacity, slot occupancy, external
+            lock count, borrowed slot count, close state, and restart-recovery
+            support.
+        """
+        with self._state_lock:
+            live_slot_count = self._next_slot - len(self._free_slots)
+            borrowed_slot_count = sum(
+                1 for state in self._slot_states.values() if state.borrow_count > 0
+            )
+            return {
+                "is_healthy": not self._closed and self._mmap_obj is not None,
+                "device_path": self._device_path,
+                "max_dax_size_bytes": self._arena_bytes,
+                "slot_bytes": self._slot_bytes,
+                "max_slots": self._max_slots,
+                "live_slot_count": live_slot_count,
+                "locked_key_count": len(self._external_lock_counts),
+                "borrowed_slot_count": borrowed_slot_count,
+                "active_read_count": self._active_reads,
+                "active_write_count": self._active_writes,
+                "closing": self._closing or self._closed,
+                "supports_restart_recovery": False,
+            }
+
+    def _put_one(
+        self,
+        key: KeyT,
+        obj: MemoryObj,
+        *,
+        raise_on_full: bool,
+        raise_on_write_failure: bool,
+        writer: Optional[_CopyFn] = None,
+    ) -> bool:
+        if len(obj.get_shapes()) > 1:
+            logger.error(
+                "DaxCore does not support multi-tensor allocations for key %s",
+                key,
+            )
+            return False
+
+        size = int(obj.get_size())
+        if size > self._slot_bytes:
+            return False
+
+        reserve_result = self._reserve_put(
+            key,
+            obj,
+            size,
+            raise_on_full=raise_on_full,
+        )
+        if reserve_result is None:
+            return False
+        if reserve_result is True:
+            return True
+
+        assert isinstance(reserve_result, _Inflight)
+        copy_fn = writer or self._default_do_write
+        write_failed = False
+        write_error: Optional[Exception] = None
+        try:
+            copy_fn(reserve_result.offset, obj, size)
+        except Exception as exc:
+            write_failed = True
+            write_error = exc
+
+        committed = self._finalize_put(key, write_failed=write_failed)
+        if write_error is not None and raise_on_write_failure:
+            raise RuntimeError(
+                f"DAX write failed for key {key}: {write_error}"
+            ) from write_error
+        return committed
+
+    def _reserve_put(
+        self,
+        key: KeyT,
+        obj: MemoryObj,
+        size: int,
+        *,
+        raise_on_full: bool,
+    ) -> _Inflight | bool | None:
+        with self._state_lock:
+            if self._closing or self._closed:
+                return None
+
+            if key in self._index or key in self._inflight:
+                return True
+
+            try:
+                slot_id = self._allocate_slot_locked()
+            except RuntimeError:
+                if raise_on_full:
+                    raise
+                return None
+
+            offset = slot_id * self._slot_bytes
+            generation = self._reserve_slot_state_locked(slot_id)
+            meta = DiskCacheMetadata(
+                path=f"{self._device_path}@{offset}",
+                size=size,
+                shape=obj.metadata.shape,
+                dtype=obj.metadata.dtype,
+                cached_positions=obj.metadata.cached_positions,
+                fmt=obj.metadata.fmt,
+                pin_count=0,
+            )
+            inflight = _Inflight(
+                offset=offset,
+                meta=meta,
+                slot_id=slot_id,
+                generation=generation,
+            )
+            self._inflight[key] = inflight
+            self._active_writes += 1
+            return inflight
+
+    def _finalize_put(self, key: KeyT, *, write_failed: bool) -> bool:
+        with self._state_lock:
+            committed = self._finalize_inflight_locked(key, write_failed=write_failed)
+            if self._active_writes > 0:
+                self._active_writes -= 1
+            else:
+                logger.warning("DaxCore active write count underflow for key %s", key)
+            self._state_condition.notify_all()
+            return committed
+
+    def _reserve_slot_state_locked(self, slot_id: int) -> int:
+        existing = self._slot_states.get(slot_id)
+        new_generation = (existing.generation if existing is not None else 0) + 1
+        self._slot_states[slot_id] = _SlotState(generation=new_generation)
+        return new_generation
+
+    def _mark_slot_committed_locked(self, slot_id: int, generation: int) -> None:
+        state = self._slot_states.get(slot_id)
+        if state is None or state.generation != generation:
+            return
+        state.committed = True
+        state.pending_free = False
+
+    def _schedule_slot_reclaim_locked(self, slot_id: int, generation: int) -> None:
+        state = self._slot_states.get(slot_id)
+        if state is None or state.generation != generation:
+            return
+        state.committed = False
+        if state.borrow_count == 0:
+            state.pending_free = False
+            self._free_slot_locked(slot_id)
+        else:
+            state.pending_free = True
+
+    def _get_committed_state_locked(self, entry: _Entry) -> Optional[_SlotState]:
+        state = self._slot_states.get(entry.slot_id)
+        if state is None or state.generation != entry.generation or not state.committed:
+            return None
+        return state
+
+    def _finalize_inflight_locked(self, key: KeyT, *, write_failed: bool) -> bool:
+        inflight = self._inflight.pop(key, None)
+        if inflight is None:
+            return False
+
+        if inflight.canceled or write_failed:
+            self._schedule_slot_reclaim_locked(inflight.slot_id, inflight.generation)
+            return False
+
+        self._mark_slot_committed_locked(inflight.slot_id, inflight.generation)
+        self._index[key] = _Entry(
+            offset=inflight.offset,
+            meta=inflight.meta,
+            slot_id=inflight.slot_id,
+            generation=inflight.generation,
+        )
+        return True
+
+    def _allocate_slot_locked(self) -> int:
+        if self._free_slots:
+            return self._free_slots.pop()
+        if self._next_slot < self._max_slots:
+            slot_id = self._next_slot
+            self._next_slot += 1
+            return slot_id
+        raise RuntimeError("No free slots available; eviction required")
+
+    def _free_slot_locked(self, slot_id: int) -> None:
+        if slot_id >= 0:
+            self._free_slots.add(slot_id)
+
+    def _default_do_write(self, offset: int, memory_obj: MemoryObj, size: int) -> None:
+        ctypes.memmove(
+            ctypes.c_void_p(self._base_ptr + offset),
+            ctypes.c_void_p(memory_obj.data_ptr),
+            size,
+        )
+
+    def _default_do_read(self, offset: int, memory_obj: MemoryObj, size: int) -> None:
+        ctypes.memmove(
+            ctypes.c_void_p(memory_obj.data_ptr),
+            ctypes.c_void_p(self._base_ptr + offset),
+            size,
+        )
+
+    def _open_arena(self) -> None:
+        fd: Optional[int] = None
+        mmap_obj: Optional[mmap.mmap] = None
+        arena_view: Optional[memoryview] = None
+
+        try:
+            fd = os.open(self._device_path, os.O_RDWR)
+        except OSError as exc:
+            raise RuntimeError(
+                f"Failed to open dax device {self._device_path}: {exc}"
+            ) from exc
+
+        try:
+            try:
+                capacity_bytes = os.fstat(fd).st_size
+                if capacity_bytes > 0 and self._arena_bytes > capacity_bytes:
+                    raise RuntimeError(
+                        f"max_dax_size_bytes ({self._arena_bytes} bytes) exceeds "
+                        f"device capacity ({capacity_bytes} bytes)"
+                    )
+            except OSError:
+                logger.warning(
+                    "Could not determine DAX device capacity via fstat; "
+                    "skipping max_dax_size_bytes validation"
+                )
+
+            mmap_obj = mmap.mmap(
+                fd,
+                self._arena_bytes,
+                flags=mmap.MAP_SHARED,
+                prot=mmap.PROT_READ | mmap.PROT_WRITE,
+            )
+            base_ptr = ctypes.addressof(ctypes.c_char.from_buffer(mmap_obj))
+            arena_view = memoryview(mmap_obj)
+            self._fd = fd
+            self._mmap_obj = mmap_obj
+            self._arena_view = arena_view
+            self._base_ptr = base_ptr
+        except Exception as exc:
+            self._release_arena_resources(fd, mmap_obj, arena_view)
+            if isinstance(exc, RuntimeError):
+                raise
+            raise RuntimeError(
+                f"Failed to mmap dax arena ({self._arena_bytes} bytes) from "
+                f"{self._device_path}: {exc}"
+            ) from exc
+
+    @staticmethod
+    def _release_arena_resources(
+        fd: Optional[int],
+        mmap_obj: Optional[mmap.mmap],
+        arena_view: Optional[memoryview],
+    ) -> None:
+        if arena_view is not None:
+            try:
+                arena_view.release()
+            except Exception as exc:
+                logger.warning("Failed to release DAX memoryview: %s", exc)
+
+        if mmap_obj is not None:
+            try:
+                mmap_obj.close()
+            except Exception as exc:
+                logger.warning("Failed to close DAX mmap: %s", exc)
+
+        if fd is not None:
+            try:
+                os.close(fd)
+            except Exception as exc:
+                logger.warning("Failed to close DAX fd: %s", exc)
diff --git a/lmcache/v1/storage_backend/gds_backend.py b/lmcache/v1/storage_backend/gds_backend.py
new file mode 100644
index 0000000..975da0d
--- /dev/null
+++ b/lmcache/v1/storage_backend/gds_backend.py
@@ -0,0 +1,1272 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from concurrent.futures import Future, ThreadPoolExecutor
+from typing import Any, Callable, List, Optional, Sequence, Tuple, Union
+import asyncio
+import ctypes
+import ctypes.util
+import json
+import mmap
+import os
+import struct
+import threading
+import time
+import urllib.parse
+import uuid
+
+# Third Party
+import aiofile
+import numpy as np
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    CacheEngineKey,
+    DiskCacheMetadata,
+    _lmcache_nvtx_annotate,
+    parse_cache_key,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.cu_file_memory_allocator import CuFileMemoryAllocator
+from lmcache.v1.memory_allocators.hip_file_memory_allocator import (
+    HipFileMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+from lmcache.v1.storage_backend.path_sharder import PathSharder
+
+logger = init_logger(__name__)
+
+_METADATA_FILE_SUFFIX = ".metadata"
+_DATA_FILE_SUFFIX = ".kvcache.safetensors"
+_WEKA_DATA_FILE_SUFFIX = ".weka1"
+_METADATA_VERSION = 1
+_METADATA_MAX_SIZE = 4096  # reserve 4K for metadata.
+# TODO: It is possible to read this 4KB block without triggering read-ahead by
+# various means.
+_DEFAULT_THREAD_COUNT = 4
+
+
+class UnsupportedMetadataVersion(Exception):
+    pass
+
+
+torch_dtypes = {
+    torch.half: "F16",
+    torch.bfloat16: "BF16",
+    torch.float32: "F32",
+    torch.float64: "F64",
+    torch.uint8: "U8",
+    torch.uint16: "U16",
+    torch.uint32: "U32",
+    torch.uint64: "U64",
+    torch.int8: "I8",
+    torch.int16: "I16",
+    torch.int32: "I32",
+    torch.int64: "I64",
+    torch.float8_e4m3fn: "F8E4M3FN",
+    torch.float8_e5m2: "F8E5M2",
+}
+
+torch_dtypes_inverse = dict([(v, k) for k, v in torch_dtypes.items()])
+
+
+def get_fstype(path):
+    with open("/proc/mounts", "r") as f:
+        lines = f.readlines()
+
+    # Find the best matching mount point
+    best_match = ""
+    best_fstype = ""
+    for line in lines:
+        parts = line.split()
+        if len(parts) >= 3:
+            _, mount_point, fstype = parts[0], parts[1], parts[2]
+            if path.startswith(mount_point) and len(mount_point) > len(best_match):
+                best_match = mount_point
+                best_fstype = fstype
+
+    if not best_fstype:
+        raise RuntimeError(f"Unable to detect fstype for {path}")
+
+    return best_fstype
+
+
+def pack_metadata(tensor, fmt: MemoryFormat, **extra_metadata) -> bytes:
+    if tensor.dtype not in torch_dtypes:
+        raise RuntimeError(f"unhandled dtype {tensor.dtype}")
+
+    # Metadata
+    data_size = tensor.numel() * tensor.element_size()
+    tensor_meta = {
+        "dtype": torch_dtypes[tensor.dtype],
+        "shape": list(tensor.size()),
+        "data_offsets": [0, data_size],
+        "fmt": fmt.value,
+        "__metadata__": extra_metadata,
+    }
+    meta = {"kvcache": tensor_meta}
+    str_meta = json.dumps(meta).encode("utf-8")
+    meta_len = len(str_meta)
+    assert meta_len <= _METADATA_MAX_SIZE - 8
+
+    # Align to _METADATA_MAX_SIZE - 8
+    str_meta += b" " * (_METADATA_MAX_SIZE - 8 - meta_len)
+
+    # Pack it all up so it is sized _METADATA_MAX_SIZE exactly.
+    return struct.pack("<Q", len(str_meta)) + str_meta
+
+
+def unpack_metadata(buffer: bytes):
+    meta_len = struct.unpack("<Q", buffer[:8])[0]
+
+    str_meta = buffer[8 : 8 + meta_len]
+    json_meta = str_meta.rstrip(b" ")
+
+    meta = json.loads(json_meta.decode("utf-8"))
+    tensor_meta = meta["kvcache"]
+
+    shape = tensor_meta["shape"]
+    dtype_str = tensor_meta["dtype"]
+    data_offsets = tensor_meta["data_offsets"]
+    fmt = MemoryFormat(tensor_meta["fmt"])
+
+    nbytes = data_offsets[1] - data_offsets[0]
+    dtype = torch_dtypes_inverse[dtype_str]
+
+    return torch.Size(shape), dtype, nbytes, fmt, tensor_meta["__metadata__"]
+
+
+def rand_suffix(n: int):
+    # Generates a random UUID hex string (e.g. "a8098c1a")
+    return uuid.uuid4().hex[:n]
+
+
+async def save_metadata(path: str, tmp: str, metadata: bytes):
+    tmp_path = path + tmp
+    async with aiofile.async_open(tmp_path, "wb") as f:
+        await f.write(metadata)
+    os.rename(tmp_path, path)
+
+
+def get_extra_config_bool(key, config: LMCacheEngineConfig) -> bool | None:
+    """Extract a boolean value from the config's extra_config dict.
+
+    Args:
+        key: The key to look up in extra_config.
+        config: The LMCacheEngineConfig instance.
+
+    Returns:
+        The boolean value if present, or None if not set.
+
+    Raises:
+        RuntimeError: If the value is not a valid boolean representation.
+    """
+    value = config.extra_config.get(key, None)
+    if value is None:
+        return None
+
+    if isinstance(value, str):
+        bool_value = value.lower() == "true"
+    elif value in [False, True]:
+        bool_value = value
+    else:
+        raise RuntimeError(f"Invalid value `{value}` for `{key}` in extra_config")
+
+    logger.info(f"Getting {key} = {bool_value} from extra_config")
+    return bool_value
+
+
+def _load_gpu_memcpy() -> Callable:
+    """Load the GPU runtime ``memcpy`` symbol (CUDA or ROCm).
+
+    Tries ``libcudart`` first, then ``libamdhip64``. On CUDA the symbol is
+    ``cudaMemcpy``; on ROCm it is ``hipMemcpy`` — both share the same
+    ``(dst, src, count, kind)`` C signature.
+
+    Returns:
+        A ``ctypes`` function pointer to the GPU ``memcpy`` symbol.
+
+    Raises:
+        RuntimeError: If neither CUDA nor ROCm runtime can be loaded.
+    """
+    candidates: list[tuple[str, str, str]] = [
+        ("cudart", "libcudart.so", "cudaMemcpy"),
+        ("amdhip64", "libamdhip64.so", "hipMemcpy"),
+    ]
+    for lib_name, fallback_path, symbol in candidates:
+        try:
+            path = ctypes.util.find_library(lib_name) or fallback_path
+            lib = ctypes.CDLL(path)
+            fn = getattr(lib, symbol)
+            logger.info("Loaded GPU runtime '%s' (symbol: %s)", path, symbol)
+            return fn
+        except (OSError, AttributeError):
+            continue
+    raise RuntimeError(
+        "GDS POSIX fallback requires a GPU runtime library "
+        "(libcudart.so or libamdhip64.so) but neither could be loaded"
+    )
+
+
+class GdsBackend(AllocatorBackendInterface):
+    """
+    Originally based on the open sourced WekaGdsBackend, this is a backend that
+    leverages GPU Direct Storage APIs to issue GDS requests directly to the
+    GDS-supported remote filesystem.  In order to use it, users need to specify
+    `gds_path` and `gds_buffer_size` in their LMCache config.
+
+    The GDS library to use is controlled by the `gds_backend` config field
+    (default: ``"cufile"``). Setting ``use_gds=False`` disables the GDS API
+    and falls back to POSIX I/O via the GPU runtime (CUDA or ROCm).
+
+    Cache Directory Structure created by this Backend:
+    /{gds_path}/{first_level}/{second_level}/{data & metadata} This structure
+    is semi-arbitrary. We create two levels in the directory hierarchy to
+    parallelize loading the data during initialization in the Python code.
+
+    NOTE: If GPUDirect is not supported on that other filesystem, then the GDS
+    library will fall back to POSIX I/O.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        dst_device: str = "cuda",
+    ):
+        assert dst_device.startswith("cuda")
+        super().__init__(dst_device=dst_device)
+
+        self.config = config
+        self.loop = loop
+        self.dst_device = dst_device
+
+        assert config.gds_path is not None, "Need to specify gds_path for GdsBackend"
+
+        sharder = PathSharder(
+            raw_csv=config.gds_path,
+            strategy=config.gds_path_sharding,
+            dst_device=dst_device,
+        )
+        self.gds_paths = sharder.all_paths
+        self.gds_path = sharder.selected
+        self.fstype = get_fstype(self.gds_path)
+
+        # Log the fstype - this is useful in reports and varying optimizations
+        # based on the kind of fstype used.
+        logger.info(
+            f"GDS backend using fstype '{self.fstype}' on path '{self.gds_path}'"
+            f" ({len(self.gds_paths)} path(s) configured)"
+        )
+
+        self.use_gds = config.use_gds
+        self.gds_backend = config.gds_backend
+        # _user_set_keys is populated by LMCacheEngineConfig when a field is
+        # explicitly provided via a config file, environment variable, or
+        # keyword argument — as opposed to falling back to its default value.
+        # We check it here so that the tmpfs/overlayfs auto-disable logic
+        # below can distinguish "the user never mentioned use_gds (default
+        # True)" from "the user explicitly wrote use_gds: true".  In the
+        # first case we auto-disable GDS on unsupported filesystems; in the
+        # second we respect the user's explicit intent and leave it enabled.
+        user_set_keys: set[str] = getattr(config, "_user_set_keys", set())
+        use_gds_explicitly_set = "use_gds" in user_set_keys
+
+        # Now initialize the memory allocator
+        self.memory_allocator = self.initialize_allocator(config, metadata)
+
+        self.data_suffix = _DATA_FILE_SUFFIX
+        self._thread_pool = None
+
+        if self.fstype in ["tmpfs", "overlayfs"]:
+            # TODO: we can replace the auto-detection of unsupported GDS
+            # file systems by doing a small GDS API test on them. If a
+            # read/write test fails, we can fallback to not using GDS APIs.
+            if use_gds_explicitly_set:
+                logger.warning("No automatic disabling of GDS usage due to fstype")
+            else:
+                logger.info("Automatic disabling of GDS usage due to fstype")
+                self.use_gds = False
+        elif self.fstype == "wekafs":
+            logger.info("Weka filesystem detected, GDS usage is enforced")
+            assert self.use_gds
+            self.data_suffix = _WEKA_DATA_FILE_SUFFIX
+
+        # Always enable the thread pool for parallel I/O
+        self.use_thread_pool = self.use_gds
+
+        if self.use_thread_pool:
+            thread_count = _DEFAULT_THREAD_COUNT
+            if config.extra_config is not None:
+                if "disk_io_threads" in config.extra_config:
+                    thread_count = config.extra_config["disk_io_threads"]
+                elif "gds_io_threads" in config.extra_config:
+                    logger.warning(
+                        "extra_config.gds_io_threads is deprecated; "
+                        "use disk_io_threads instead."
+                    )
+                    thread_count = config.extra_config["gds_io_threads"]
+            self._thread_pool = ThreadPoolExecutor(
+                max_workers=thread_count, thread_name_prefix="gds-io"
+            )
+
+        if self.use_gds:
+            logger.info("Using GDS backend '%s'", self.gds_backend)
+            if self.gds_backend == "cufile":
+                # HACK(Jiayi): cufile import is buggy on some hardware
+                # (e.g., without GPUDirect), so it's temporarily put here.
+                # Third Party
+                import cufile
+
+                self._gpu_memcpy = None
+                self.gds_module = cufile
+                self._gds_driver = self.gds_module.CuFileDriver()
+            elif self.gds_backend == "hipfile":
+                # HACK: hipfile import may be buggy on some hardware
+                # (e.g., without GPUDirect), so it's temporarily put here.
+                # First Party
+                from lmcache.v1.storage_backend import hipfile_shim
+
+                self._gpu_memcpy = None
+                self.gds_module = hipfile_shim
+                self._gds_driver = self.gds_module.CuFileDriver()
+            else:
+                raise ValueError(f"Unsupported gds_backend '{self.gds_backend}'")
+        else:
+            logger.info("GDS disabled, using POSIX fallback")
+            self.gds_module = None
+            self._gpu_memcpy = _load_gpu_memcpy()
+
+        self.use_direct_io = False
+
+        # Values for retrying allocations and loads in case of failures potentially
+        # due to memory pressure
+        self.max_alloc_attempts = (config.extra_config or {}).get(
+            "max_alloc_attempts", 10
+        )
+        self.alloc_attempt_delay_secs = (config.extra_config or {}).get(
+            "allocation_attempt_delay_secs", 0.1
+        )
+
+        if config.extra_config is not None:
+            use_direct_io = get_extra_config_bool("use_direct_io", config)
+            if use_direct_io is not None:
+                self.use_direct_io = use_direct_io
+
+        for p in self.gds_paths:
+            os.makedirs(p, exist_ok=True)
+
+        self.stats = None  # TODO: plug into LMCache Statistics
+
+        self.hot_lock = threading.Lock()
+        self.hot_cache: OrderedDict[CacheEngineKey, DiskCacheMetadata] = OrderedDict()
+        self.metadata_dirs: set[str] = set()
+
+        self.put_lock = threading.Lock()
+        self.put_tasks: set[CacheEngineKey] = set()
+
+        if hasattr(self.memory_allocator, "base_pointer"):
+            logger.debug(f"Using base pointer {self.memory_allocator.base_pointer}")
+            self.gds_base_pointer = self.memory_allocator.base_pointer
+        else:
+            logger.info("No base pointer found, GDS will use bounce buffers")
+            self.gds_base_pointer = None
+        self._scan_metadata_future = asyncio.run_coroutine_threadsafe(
+            self._scan_metadata(), self.loop
+        )
+        self.save_metadata_tasks: set[asyncio.Task] = set()
+
+        # flag for extra assertions to catch bugs but harm performance
+        self._debug_asserts = False
+        # flag to use O_NOATIME during metadata file read for performance improvement
+        self._use_noatime = True
+
+    async def _scan_metadata(self):
+        # TODO: even though we only run it once on startup, this is still
+        # not super scalable - test whether Rust code will be faster here, or
+        # whether we can serialize meta-data in groups for faster loading.
+        tasks = []
+        start = time.perf_counter()
+        for p in self.gds_paths:
+            with os.scandir(p) as it:
+                for entry in it:
+                    if not entry.is_dir():
+                        continue
+                    l1_dir = os.path.basename(entry.name)
+                    if len(l1_dir) != 2:
+                        continue
+                    tasks.append(
+                        asyncio.to_thread(
+                            self._scan_metadata_subdir,
+                            os.path.join(p, l1_dir),
+                            l1_dir,
+                        )
+                    )
+        # TODO: If Python 3.11+, can we use TaskGroup instead?
+        await asyncio.gather(*tasks)
+        end = time.perf_counter()
+        logger.info(
+            f"Read {len(self.hot_cache)} cache entries from persistent "
+            f"storage in {end - start:.2f} seconds"
+        )
+
+    def _scan_metadata_subdir(self, path, l1_dir):
+        target_suffix = self.data_suffix + _METADATA_FILE_SUFFIX
+        with os.scandir(path) as it:
+            for entry in it:
+                if not entry.is_dir():
+                    continue
+                l2_dir = os.path.basename(entry.name)
+                if len(l2_dir) != 2:
+                    continue
+                with os.scandir(os.path.join(path, l2_dir)) as it2:
+                    for fentry in it2:
+                        if not fentry.is_file():
+                            continue
+                        if not fentry.name.endswith(target_suffix):
+                            continue
+                        filename = os.path.basename(fentry.name)
+                        key_str = urllib.parse.unquote(filename[: -len(target_suffix)])
+                        try:
+                            key = parse_cache_key(key_str)
+                        except ValueError as e:
+                            logger.error(
+                                f"Filename {filename} can't be converted "
+                                f"back into cache key: {e}"
+                            )
+                            continue
+                        try:
+                            self._read_metadata(key, fentry.path, l1_dir + l2_dir)
+                        except UnsupportedMetadataVersion:
+                            logger.error(
+                                "Unsupported metadata version for %s; "
+                                "ignoring during GDS start",
+                                fentry.path,
+                            )
+                        except Exception:
+                            logger.error(
+                                "Failed to read metadata file %s during GDS start; "
+                                "raising the error to fail startup",
+                                fentry.path,
+                                exc_info=True,
+                            )
+                            raise
+
+    def _read_metadata_info(self, filename: str):
+        # Use O_NOATIME to prevent updating access time and improve performance
+        # Instead of using Python's open() and read(), we use the OS's open() and
+        # read() because it is faster - the metadata file is small and we don't
+        # need any buffering.
+        # Additionally, we use O_NOATIME to improve performance
+        if self._use_noatime:
+            try:
+                fd = os.open(filename, os.O_RDONLY | os.O_NOATIME)
+            except (
+                # PermissionError: User doesn't own the file
+                # AttributeError: O_NOATIME not available on this platform
+                # OSError: Filesystem doesn't support O_NOATIME (EINVAL)
+                PermissionError,
+                AttributeError,
+                OSError,
+            ):  # fallback to normal open if O_NOATIME is not supported
+                self._use_noatime = False
+                logger.info(
+                    "O_NOATIME flag not supported during metadata file read, "
+                    "falling back to normal open"
+                )
+                fd = os.open(filename, os.O_RDONLY)
+        else:
+            fd = os.open(filename, os.O_RDONLY)
+        try:
+            buf = os.read(fd, _METADATA_MAX_SIZE)
+        finally:
+            os.close(fd)
+        return unpack_metadata(buf)
+
+    def _read_metadata(
+        self,
+        key: CacheEngineKey,
+        filename: str,
+        subdir_key: str,
+    ):
+        shape, dtype, size, fmt, extra_metadata = self._read_metadata_info(filename)
+        if extra_metadata["lmcache_version"] != str(_METADATA_VERSION):
+            raise UnsupportedMetadataVersion("unhandled lmcache metadata")
+        logger.debug(
+            f"Read metadata for {key} from {filename}: "
+            f"shape={shape}, dtype={dtype}, size={size}, fmt={fmt}, "
+            f"extra_metadata={extra_metadata}"
+        )
+        # TODO(extra_metadata)
+        # TODO(Jiayi): need to support `cached_positions`.
+        # Currently we just fill it as None.
+        metadata = DiskCacheMetadata(
+            filename.removesuffix(_METADATA_FILE_SUFFIX),
+            size,
+            shape,
+            dtype,
+            None,
+            fmt,
+        )
+        with self.hot_lock:
+            self.metadata_dirs.add(subdir_key)
+            self.hot_cache[key] = metadata
+        return metadata
+
+    def __str__(self):
+        return self.__class__.__name__
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        # TODO: implement pin() semantics
+        with self.hot_lock:
+            res = key in self.hot_cache
+        if res:
+            return True
+        if self._try_to_read_metadata(key):
+            return True
+        return False
+
+    def _try_to_read_metadata(self, key: CacheEngineKey) -> Optional[DiskCacheMetadata]:
+        for p in self.gds_paths:
+            path, subdir_key, _, _ = self._key_to_path(key, base_path=p)
+            path += _METADATA_FILE_SUFFIX
+            if os.path.exists(path):
+                try:
+                    return self._read_metadata(key, path, subdir_key)
+                except FileNotFoundError:
+                    logger.warning(
+                        f"[GDS] File not found for key {key.to_string()} "
+                        f"at expected path {path}, returning None"
+                    )
+                except PermissionError:
+                    logger.warning(
+                        f"[GDS]: Permission Denied for PID {os.getpid()} on {path},"
+                        f" returning None"
+                    )
+                except UnsupportedMetadataVersion:
+                    logger.error(f"Unsupported metadata version for {path}, ignoring")
+                except (OSError, IOError) as e:
+                    logger.error(
+                        f"Failed to read metadata file {path}: {type(e).__name__}: "
+                        f"{e}. File may be corrupted or inaccessible. "
+                        f"Ignoring cache entry for key {key.to_string()}."
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Unexpected error reading metadata file {path}: "
+                        f"{type(e).__name__}: {e}. Ignoring cache entry for key "
+                        f"{key.to_string()}."
+                    )
+
+        return None
+
+    def _key_to_path(
+        self,
+        key: CacheEngineKey,
+        base_path: Optional[str] = None,
+    ) -> Tuple[str, str, str, str]:
+        hash = str(key.chunk_hash)
+        l1_dir = hash[:2]
+        l2_dir = hash[2:4]
+        key_str = key.to_string()
+        if base_path is None:
+            base_path = self.gds_path
+        return (
+            os.path.join(
+                base_path,
+                l1_dir,
+                l2_dir,
+                urllib.parse.quote(key_str, safe="") + self.data_suffix,
+            ),
+            l1_dir + l2_dir,
+            l1_dir,
+            l2_dir,
+        )
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        with self.put_lock:
+            return key in self.put_tasks
+
+    def submit_put_task(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Future:
+        """
+        Submit a put task to store KV cache to GDS asynchronously.
+
+        :param on_complete_callback: Optional callback invoked after the GDS
+            write completes. Callback exceptions are caught and logged.
+        """
+        assert memory_obj.tensor is not None
+        memory_obj.ref_count_up()
+
+        with self.put_lock:
+            self.put_tasks.add(key)
+
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_save_bytes_to_disk(key, memory_obj, on_complete_callback),
+            self.loop,
+        )
+        return future
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Union[List[Future], None]:
+        """
+        Submit batched put tasks to store KV caches to GDS asynchronously.
+
+        :param on_complete_callback: Optional callback invoked once per key
+            after that key's write completes (not once per batch).
+        """
+        futures = []
+        for key, memory_obj in zip(keys, memory_objs, strict=False):
+            future = self.submit_put_task(
+                key, memory_obj, on_complete_callback=on_complete_callback
+            )
+            futures.append(future)
+        return futures
+
+    async def _async_save_bytes_to_disk(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        Convert KV to bytes and async store bytes to disk.
+
+        :param on_complete_callback: Optional callback invoked after the GDS
+            write completes for this key. Callback exceptions are caught.
+        """
+        try:
+            kv_chunk = memory_obj.tensor
+            assert kv_chunk is not None
+            path, subdir_key, l1_dir, l2_dir = self._key_to_path(key)
+            # TODO: maybe remove `metadata_dirs` and insert mkdir calls
+            # only for the case where creating the CuFile fails on ENOENT. It
+            # also makes the code more resilient to out-of-band deletions
+            if subdir_key not in self.metadata_dirs:
+                os.makedirs(os.path.join(self.gds_path, l1_dir, l2_dir), exist_ok=True)
+                self.metadata_dirs.add(subdir_key)
+            tmp = ".tmp" + rand_suffix(8)
+            fmt = memory_obj.metadata.fmt
+            try:
+                metadata = await asyncio.to_thread(
+                    self._save_gds,
+                    path,
+                    tmp,
+                    kv_chunk,
+                    fmt,
+                    self.gds_base_pointer,
+                    memory_obj.metadata.address,
+                )
+            except Exception as e:
+                logger.error(
+                    f"GDS write operation failed for key {key.to_string()} at "
+                    f"path {path}: tensor_shape={kv_chunk.shape}, "
+                    f"tensor_dtype={kv_chunk.dtype}, "
+                    f"tensor_size_bytes={kv_chunk.nbytes}, error={e}",
+                    exc_info=True,
+                )
+                return
+
+            # Register key in cache
+            logger.debug(
+                f"Saved {kv_chunk.numel()} elements of {kv_chunk.dtype} "
+                f"to {path} with metadata {metadata}"
+            )
+            self.insert_key(key, memory_obj)
+            try:
+                task = asyncio.create_task(
+                    save_metadata(path + _METADATA_FILE_SUFFIX, tmp, metadata)
+                )
+                self.save_metadata_tasks.add(task)
+                task.add_done_callback(self.save_metadata_tasks.discard)
+                # Add callback to check for exceptions during task execution
+                task.add_done_callback(
+                    lambda t: self._handle_metadata_write_completion(t, key, path)
+                )
+            except Exception as e:
+                logger.error(
+                    f"POSIX metadata write operation failed for key {key.to_string()} "
+                    f"at path {path + _METADATA_FILE_SUFFIX}: "
+                    f"metadata_size_bytes={len(metadata)}, "
+                    f"tmp_suffix={tmp}, error={e}",
+                    exc_info=True,
+                )
+                with self.hot_lock:
+                    self.hot_cache.pop(key, None)
+                return
+        finally:
+            memory_obj.ref_count_down()
+            with self.put_lock:
+                self.put_tasks.discard(key)
+
+        # Call the completion callback if provided
+        if on_complete_callback is not None:
+            try:
+                on_complete_callback(key)
+            except Exception as e:
+                logger.error(
+                    f"on_complete_callback failed for key {key.to_string()}: {e}",
+                    exc_info=True,
+                )
+
+    def _handle_metadata_write_completion(
+        self, task: asyncio.Task, key: CacheEngineKey, path: str
+    ) -> None:
+        """Handle completion of metadata write task, checking for exceptions."""
+        try:
+            # Retrieve exception if task failed
+            exception = task.exception()
+            if exception is not None:
+                logger.error(
+                    f"Metadata write task failed for key {key.to_string()} "
+                    f"at path {path + _METADATA_FILE_SUFFIX}: {exception}",
+                    exc_info=exception,
+                )
+                with self.hot_lock:
+                    self.hot_cache.pop(key, None)
+        except Exception as e:
+            # Exception calling task.exception() (e.g., task was cancelled)
+            logger.error(
+                f"Error checking metadata write task status for key "
+                f"{key.to_string()}: {e}",
+                exc_info=True,
+            )
+
+    def insert_key(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        path, _, _, _ = self._key_to_path(key)
+        size = memory_obj.get_physical_size()
+        shape = memory_obj.metadata.shape
+        dtype = memory_obj.metadata.dtype
+        fmt = memory_obj.metadata.fmt
+        with self.hot_lock:
+            # TODO(Jiayi): need to support `cached_positions`.
+            self.hot_cache[key] = DiskCacheMetadata(path, size, shape, dtype, None, fmt)
+
+    def submit_prefetch_task(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        # with self.hot_lock:
+        #     entry = self.hot_cache.get(key)
+        # if entry is None:
+        #     return None
+
+        # path = entry.path
+        # dtype = entry.dtype
+        # shape = entry.shape
+        # fmt = entry.fmt
+        # assert dtype is not None
+        # assert shape is not None
+        # assert fmt is not None
+        # return asyncio.run_coroutine_threadsafe(
+        #     self._async_load_bytes_from_disk(key, path, dtype, shape，fmt), self.loop
+        # )
+
+        # TODO(Jiayi): Need to modify this when prefetch interface is determined.
+
+        # TODO(Jiayi): add `test_gds_backend_sanity` back after implementing this
+        return False
+
+    async def _async_load_bytes_from_disk(
+        self,
+        key: CacheEngineKey,
+        path: str,
+        dtype: torch.dtype,
+        shape: torch.Size,
+        fmt: MemoryFormat,
+    ) -> Optional[MemoryObj]:
+        return self._load_bytes_from_disk_with_allocation(
+            key, path, dtype, shape, fmt=fmt
+        )
+
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        with self.hot_lock:
+            entry = self.hot_cache.get(key)
+        if entry is None:
+            return None
+
+        path = entry.path
+        dtype = entry.dtype
+        shape = entry.shape
+        fmt = entry.fmt
+        logger.warning(entry)
+        assert dtype is not None
+        assert shape is not None
+        assert fmt is not None
+        return self._load_bytes_from_disk_with_allocation(
+            key, path, dtype=dtype, shape=shape, fmt=fmt
+        )
+
+    def _load_bytes_from_disk_with_allocation(
+        self,
+        key: CacheEngineKey,
+        path: str,
+        dtype: torch.dtype,
+        shape: torch.Size,
+        fmt: MemoryFormat,
+    ) -> Optional[MemoryObj]:
+        """
+        Load byte array from disk by first allocating memory, then loading.
+
+        Args:
+            key: Cache key for error handling
+            path: File path to load from
+            dtype: Data type for memory allocation
+            shape: Shape for memory allocation
+
+        Returns:
+            A new memory object with loaded data, or None if allocation or
+            loading failed
+        """
+        memory_obj = self.memory_allocator.allocate(shape, dtype, fmt=fmt)
+        if memory_obj is None:
+            logger.error("Memory allocation failed during sync disk load.")
+            return None
+        if self._debug_asserts:
+            assert memory_obj.tensor is not None
+            assert memory_obj.tensor.is_cuda
+            assert torch.device(self.dst_device) == torch.device(
+                memory_obj.tensor.device
+            )
+
+        return self._load_bytes_from_disk_with_memory(key, path, memory_obj)
+
+    def _load_bytes_from_disk_with_memory(
+        self,
+        key: CacheEngineKey,
+        path: str,
+        memory_obj: Optional[MemoryObj],
+    ) -> Optional[MemoryObj]:
+        """
+        Load byte array from disk into a pre-allocated memory object.
+
+        Args:
+            key: Cache key for error handling
+            path: File path to load from
+            memory_obj: Pre-allocated memory object to load data into
+
+        Returns:
+            The memory object with loaded data, or None if loading failed
+        """
+        if memory_obj is None or not memory_obj.is_valid():
+            return None
+
+        offset = _METADATA_MAX_SIZE
+        if self.gds_base_pointer is None:
+            tensor = memory_obj.tensor
+            assert tensor is not None
+            if self._debug_asserts:
+                assert tensor.is_cuda
+                assert torch.device(self.dst_device) == torch.device(tensor.device)
+            addr = ctypes.c_void_p(tensor.data_ptr())
+            dev_offset = 0
+        else:
+            addr = ctypes.c_void_p(self.gds_base_pointer)
+            dev_offset = memory_obj.metadata.address
+        ret = self._load_gds(path, offset, addr, memory_obj.get_size(), dev_offset)
+        if ret != memory_obj.get_size():
+            if ret < 0:
+                logger.error(
+                    f"Error loading {path}: ret: {ret} removing entry from cache"
+                )
+                with self.hot_lock:
+                    self.hot_cache.pop(key)
+            else:
+                # TODO: we should probably count errors and
+                # remove the entry if it's a persistent problem.
+                logger.error(
+                    f"Error loading {path}: got only {ret} bytes "
+                    f"out of {memory_obj.get_size()}, ignoring"
+                )
+            memory_obj.ref_count_down()
+            return None
+        return memory_obj
+
+    def get_non_blocking(
+        self,
+        key: CacheEngineKey,
+        location: Optional[str] = None,
+    ) -> Optional[Future]:
+        # TODO: Using a dummy wrapper around prefetch for now.
+        if not self.submit_prefetch_task(key):
+            return None
+        return Future()
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        if self.use_thread_pool:
+            logger.debug("Using batched_get_blocking with thread pool implementation")
+            return self._batched_get_blocking_by_thread_pool_impl(keys)
+        else:
+            return super().batched_get_blocking(keys)
+
+    def _batched_get_blocking_by_thread_pool_impl(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> list[MemoryObj | None]:
+        paths: list[str | None] = []
+        dtypes: list[torch.dtype | None] = []
+        shapes: list[torch.Size | None] = []
+        fmts: list[MemoryFormat | None] = []
+        with self.hot_lock:
+            for key in keys:
+                entry = self.hot_cache.get(key)
+                if entry is None:
+                    logger.error(f"Lookup failed during get_blocking for {key}")
+                    paths.append(None)
+                    dtypes.append(None)
+                    shapes.append(None)
+                    fmts.append(None)
+                    continue
+                paths.append(entry.path)
+                dtypes.append(entry.dtype)
+                shapes.append(entry.shape)
+                fmts.append(entry.fmt)
+
+        memory_objs: list[MemoryObj | None] = []
+        gds_reads, gds_read_bytes = 0, 0
+        for dtype, shape, path, fmt in zip(dtypes, shapes, paths, fmts, strict=True):
+            if path is None:
+                memory_objs.append(None)
+                continue
+            memory_obj = self.memory_allocator.allocate(shape, dtype, fmt=fmt)
+            if memory_obj is None:
+                logger.error(f"Memory allocation failed during get_blocking for {path}")
+            else:
+                gds_reads += 1
+                gds_read_bytes += memory_obj.get_size()
+            memory_objs.append(memory_obj)
+
+        start_time = time.perf_counter()
+        assert self._thread_pool is not None
+        results = list(
+            self._thread_pool.map(
+                self._load_bytes_from_disk_with_memory, keys, paths, memory_objs
+            )
+        )
+        total_time = time.perf_counter() - start_time
+        logger.info(
+            f"Time taken for batched_get_blocking: {total_time:.3f}s |"
+            f" {gds_read_bytes / 1024 / 1024}MiB | {gds_reads} ops."
+        )
+        return results
+
+    @_lmcache_nvtx_annotate
+    @torch.inference_mode()
+    def _save_gds(
+        self,
+        path: str,
+        tmp: str,
+        kv_chunk: torch.Tensor,
+        fmt: MemoryFormat,
+        base_pointer: int,
+        device_offset: int,
+    ):
+        if base_pointer is None:
+            addr = ctypes.c_void_p(kv_chunk.data_ptr())
+            dev_offset = 0
+        else:
+            addr = ctypes.c_void_p(base_pointer)
+            dev_offset = device_offset
+        tmp_path = path + tmp
+        offset = _METADATA_MAX_SIZE
+        # TODO: We can add the chunk's metadata here, e.g. Tensor parallelism shard
+        # and pipeline parallelism index.
+        metadata = pack_metadata(
+            kv_chunk, fmt=fmt, lmcache_version=str(_METADATA_VERSION)
+        )
+        try:
+            with open(tmp_path, "wb") as f:
+                f.write(metadata)
+            if self.gds_module:
+                with self.gds_module.CuFile(
+                    tmp_path, "r+", use_direct_io=self.use_direct_io
+                ) as f:
+                    f.write(
+                        addr, kv_chunk.nbytes, file_offset=offset, dev_offset=dev_offset
+                    )
+            elif self._gpu_memcpy:
+                # mmap the file
+                fd = os.open(tmp_path, os.O_RDWR)
+                nbytes = kv_chunk.nbytes
+                os.ftruncate(fd, nbytes + offset)
+                mm = mmap.mmap(
+                    fd, nbytes + offset, prot=mmap.PROT_WRITE, flags=mmap.MAP_SHARED
+                )
+                os.close(fd)
+
+                # get mapped file address
+                arr = np.frombuffer(mm, dtype=np.uint8)
+                buf_addr = arr.__array_interface__["data"][0]
+
+                assert addr.value is not None
+                res = self._gpu_memcpy(
+                    ctypes.c_void_p(buf_addr + offset),
+                    ctypes.c_void_p(int(addr.value) + device_offset),
+                    ctypes.c_size_t(nbytes),
+                    ctypes.c_int(2),
+                )
+                if res:
+                    raise RuntimeError(f"GPU memcpy failed {res}")
+                del arr
+                mm.close()
+
+        except Exception as e:
+            logger.error(f"Error saving {tmp_path}: {e}", exc_info=True)
+            raise e
+        os.rename(tmp_path, path)
+        return metadata
+
+    def _load_gds(
+        self,
+        gds_path: str,
+        file_offset: int,
+        gpu_pointer: ctypes.c_void_p,
+        size_in_bytes: int,
+        dev_offset: int,
+    ) -> int:
+        """Read data from disk into a GPU buffer"""
+        try:
+            if self.gds_module:
+                with self.gds_module.CuFile(
+                    gds_path, "r", use_direct_io=self.use_direct_io
+                ) as f:
+                    return f.read(
+                        gpu_pointer,
+                        size_in_bytes,
+                        file_offset=file_offset,
+                        dev_offset=dev_offset,
+                    )
+            elif self._gpu_memcpy:
+                fd = os.open(gds_path, os.O_RDONLY)
+                file_size = os.fstat(fd).st_size
+
+                # Check if file is large enough for the requested read
+                if file_size < file_offset + size_in_bytes:
+                    os.close(fd)
+                    logger.error(
+                        f"File {gds_path} is too small: size={file_size}, "
+                        f"but need at least {file_offset + size_in_bytes} bytes "
+                        f"(offset={file_offset}, requested={size_in_bytes})"
+                    )
+                    return -1
+
+                mm = mmap.mmap(
+                    fd,
+                    file_size,
+                    prot=mmap.PROT_READ,
+                    flags=mmap.MAP_PRIVATE | mmap.MAP_POPULATE,  # type: ignore [attr-defined]
+                )
+                os.close(fd)
+
+                arr = np.frombuffer(mm, dtype=np.uint8)
+                addr = arr.__array_interface__["data"][0]
+
+                assert gpu_pointer.value is not None
+                res = self._gpu_memcpy(
+                    ctypes.c_void_p(int(gpu_pointer.value) + dev_offset),
+                    ctypes.c_void_p(addr + file_offset),
+                    ctypes.c_size_t(size_in_bytes),
+                    ctypes.c_int(1),
+                )
+
+                if res != 0:
+                    raise RuntimeError(f"GPU memcpy failed with code {res}")
+                del arr
+                mm.close()
+                return size_in_bytes
+            else:
+                raise RuntimeError(
+                    "Both gds_module and _gpu_memcpy are None, this should not happen"
+                )
+        except Exception as e:
+            # return -1 on any exception, and log the error.
+            # The caller will handle the error by removing the cache entry and
+            # returning None.
+            logger.error(f"GDS read failed for {gds_path}: {e}", exc_info=True)
+            return -1
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        # NOTE (ApostaC): Since gds doesn't have eviction now, we don't need
+        # to implement pin and unpin
+        return False
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        # NOTE (ApostaC): Since gds doesn't have eviction now, we don't need
+        # to implement pin and unpin
+        return False
+
+    def remove(self, key: CacheEngineKey, force: bool = True):
+        raise NotImplementedError("Remote backend does not support remove now.")
+
+    def initialize_allocator(
+        self, config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ) -> Union[CuFileMemoryAllocator, HipFileMemoryAllocator]:
+        assert config.gds_buffer_size is not None
+        allocator_cls = (
+            HipFileMemoryAllocator
+            if self.gds_backend == "hipfile"
+            else CuFileMemoryAllocator
+        )
+        return allocator_cls(config.gds_buffer_size * 1024**2)
+
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        """
+        Allocate a memory object of shape and dtype
+        """
+        if eviction:
+            logger.warning("GDS Backend does not support eviction")
+
+        logger.debug(f"Allocating memory with busy loop: {busy_loop}")
+
+        max_attempts = self.max_alloc_attempts if busy_loop else 1
+        num_attempts = 0
+
+        # try up to max_attempts
+        while True:
+            memory_obj = self.memory_allocator.allocate(shapes, dtypes, fmt)
+            if memory_obj is not None:  # success
+                return memory_obj
+
+            num_attempts += 1
+            if num_attempts < max_attempts:  # keep trying until max attempts is reached
+                logger.debug(
+                    f"Unable to allocate memory object after {num_attempts} "
+                    f"attempt(s) of GDS backend allocate(). "
+                    f"Waiting {self.alloc_attempt_delay_secs} seconds before retrying."
+                )
+                if self.alloc_attempt_delay_secs > 0:
+                    time.sleep(self.alloc_attempt_delay_secs)
+            else:  # break to failure case after max attempts is reached
+                break
+
+        logger.warning(
+            f"GDS allocation failed after {num_attempts} attempt(s). Returning None."
+        )
+        if not self.memory_allocator.memcheck():
+            logger.error(
+                "GDS allocation failed and memory allocator "
+                "is inconsistent. This is a bug in the memory allocator."
+            )
+        return None
+
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[list[MemoryObj]]:
+        """
+        Batched allocate `batch_size` memory objects of shape and dtype
+        """
+        if eviction:
+            logger.warning("GDS Backend does not support eviction")
+
+        logger.debug(
+            f"Batched allocating memory in GDS backend with busy loop: {busy_loop}"
+        )
+
+        max_attempts = self.max_alloc_attempts if busy_loop else 1
+        num_attempts = 0
+
+        # try up to max_attempts
+        while True:
+            memory_objs = self.memory_allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt
+            )
+            if memory_objs is not None:  # success
+                return memory_objs
+
+            num_attempts += 1
+            if num_attempts < max_attempts:  # keep trying until max attempts is reached
+                logger.debug(
+                    f"Unable to allocate memory object after {num_attempts} "
+                    f"attempt(s) of GDS backend batched_allocate(). "
+                    f"Waiting {self.alloc_attempt_delay_secs} seconds before retrying."
+                )
+                if self.alloc_attempt_delay_secs > 0:
+                    time.sleep(self.alloc_attempt_delay_secs)
+            else:  # break to failure case after max attempts is reached
+                break
+
+        logger.warning(
+            f"GDS batched allocation failed after {num_attempts} "
+            f"attempt(s). Returning None."
+        )
+        if not self.memory_allocator.memcheck():
+            logger.error(
+                "GDS batched allocation failed and memory allocator "
+                "is inconsistent. This is a bug in the memory allocator."
+            )
+        return None
+
+    def get_allocator_backend(self):
+        return self
+
+    def get_memory_allocator(self):
+        return self.memory_allocator
+
+    def close(self) -> None:
+        # Wait for initial metadata scan to complete
+        try:
+            self._scan_metadata_future.result(timeout=30)
+        except Exception as e:
+            logger.warning(
+                f"Exception while waiting for metadata scan: {e}",
+                exc_info=True,
+            )
+        # Wait for pending metadata write tasks to finish before tearing down
+        # the allocator and thread pool..
+        if self.save_metadata_tasks:
+
+            async def _drain_tasks() -> None:
+                await asyncio.gather(*self.save_metadata_tasks, return_exceptions=True)
+                self.save_metadata_tasks.clear()
+
+            try:
+                drain: Future = asyncio.run_coroutine_threadsafe(
+                    _drain_tasks(),
+                    self.loop,
+                )
+                drain.result(timeout=30)
+            except Exception as e:
+                logger.warning(
+                    f"Exception while draining metadata write tasks: {e}",
+                    exc_info=True,
+                )
+        self.memory_allocator.close()
+        if self._thread_pool is not None:
+            self._thread_pool.shutdown(wait=True)
+        logger.info("GDS backend closed.")
diff --git a/lmcache/v1/storage_backend/hipfile_shim.py b/lmcache/v1/storage_backend/hipfile_shim.py
new file mode 100644
index 0000000..dbc992d
--- /dev/null
+++ b/lmcache/v1/storage_backend/hipfile_shim.py
@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shim that exposes hipfile behind compatible names for cufile-python.
+
+This module wraps ``hipfile.Driver``, ``hipfile.FileHandle``, and
+``hipfile.Buffer`` so that callers written against the cufile-python API
+(``CuFileDriver`` / ``CuFile``) can use hipfile without any code changes.
+"""
+
+# Standard
+from collections.abc import Callable
+from types import TracebackType
+from typing import Any
+import ctypes
+import os
+
+# Third Party
+from hipfile import Buffer, Driver, FileHandle
+
+
+def _os_flags(mode: str) -> int:
+    """Translate a Python-style mode string to ``os.open`` flags."""
+    flags_map: dict[str, int] = {
+        "r": os.O_RDONLY,
+        "r+": os.O_RDWR,
+        "w": os.O_CREAT | os.O_WRONLY | os.O_TRUNC,
+        "w+": os.O_CREAT | os.O_RDWR | os.O_TRUNC,
+        "a": os.O_CREAT | os.O_WRONLY | os.O_APPEND,
+        "a+": os.O_CREAT | os.O_RDWR | os.O_APPEND,
+    }
+    return flags_map[mode]
+
+
+def _singleton(cls: type) -> Callable:
+    """Decorator that turns *cls* into a singleton."""
+    _instances: dict[type, object] = {}
+
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        if cls not in _instances:
+            _instances[cls] = cls(*args, **kwargs)
+        return _instances[cls]
+
+    return wrapper
+
+
+@_singleton
+class CuFileDriver:
+    """Singleton wrapper around :class:`hipfile.Driver`.
+
+    Matches the cufile-python ``CuFileDriver`` interface: the driver is opened
+    on first instantiation and closed when the singleton is destroyed.
+    """
+
+    def __init__(self) -> None:
+        self._driver = Driver()
+        self._driver.open()
+
+    def __del__(self) -> None:
+        self._driver.close()
+
+
+class CuFile:
+    """Wrapper around :class:`hipfile.FileHandle` with cufile-python semantics.
+
+    Args:
+        path: Filesystem path to open.
+        mode: Python-style mode string (``"r"``, ``"r+"``, ``"w"``, etc.).
+        use_direct_io: If ``True``, ``O_DIRECT`` is ORed into the flags.
+    """
+
+    def __init__(
+        self,
+        path: str,
+        mode: str = "r",
+        use_direct_io: bool = False,
+    ) -> None:
+        flags = _os_flags(mode)
+        if use_direct_io:
+            flags |= os.O_DIRECT
+        self._file_handle = FileHandle(path, flags)
+
+    @property
+    def is_open(self) -> bool:
+        """Return ``True`` if the underlying handle has been opened."""
+        return self._file_handle.handle is not None
+
+    def open(self) -> None:
+        """Open the file and register the hipfile handle."""
+        if self.is_open:
+            return
+        self._file_handle.open()
+
+    def close(self) -> None:
+        """Deregister the handle and close the file."""
+        if not self.is_open:
+            return
+        self._file_handle.close()
+
+    def __enter__(self) -> "CuFile":
+        self.open()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        if self.is_open:
+            self.close()
+
+    def read(
+        self,
+        dest: ctypes.c_void_p,
+        size: int,
+        file_offset: int = 0,
+        dev_offset: int = 0,
+    ) -> int:
+        """Read from the file into a GPU buffer.
+
+        Args:
+            dest: Device pointer (``ctypes.c_void_p``) to read into.
+            size: Number of bytes to read.
+            file_offset: Byte offset in the file.
+            dev_offset: Byte offset in the device buffer.
+
+        Returns:
+            Number of bytes actually read.
+
+        Raises:
+            IOError: If the file is not open.
+        """
+        if not self.is_open:
+            raise IOError("File is not open.")
+        buf = Buffer.from_ctypes_void_p(dest, size, flags=0)
+        return self._file_handle.read(buf, size, file_offset, dev_offset)
+
+    def write(
+        self,
+        src: ctypes.c_void_p,
+        size: int,
+        file_offset: int = 0,
+        dev_offset: int = 0,
+    ) -> int:
+        """Write from a GPU buffer into the file.
+
+        Args:
+            src: Device pointer (``ctypes.c_void_p``) to write from.
+            size: Number of bytes to write.
+            file_offset: Byte offset in the file.
+            dev_offset: Byte offset in the device buffer.
+
+        Returns:
+            Number of bytes actually written.
+
+        Raises:
+            IOError: If the file is not open.
+        """
+        if not self.is_open:
+            raise IOError("File is not open.")
+        buf = Buffer.from_ctypes_void_p(src, size, flags=0)
+        return self._file_handle.write(buf, size, file_offset, dev_offset)
+
+
+__all__ = ["CuFile", "CuFileDriver"]
diff --git a/lmcache/v1/storage_backend/job_executor/__init__.py b/lmcache/v1/storage_backend/job_executor/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/lmcache/v1/storage_backend/job_executor/base_executor.py b/lmcache/v1/storage_backend/job_executor/base_executor.py
new file mode 100644
index 0000000..f6c2e10
--- /dev/null
+++ b/lmcache/v1/storage_backend/job_executor/base_executor.py
@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Awaitable, Callable
+import abc
+
+
+class BaseJobExecutor(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    async def submit_job(
+        self,
+        fn: Callable[..., Awaitable[Any]] | Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Submit a job to the executor.
+
+        :param fn: The function to execute.
+        :param args: The positional arguments to pass to the function.
+        :param kwargs: The keyword arguments to pass to the function (e.g., priority).
+
+        :return: Return type aligned with the function being executed.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def shutdown(self, wait: bool = True) -> None:
+        """
+        Clean up the executor, optionally waiting for currently running jobs to finish.
+
+        :param wait: If True, wait for currently running jobs to finish before
+        returning.
+        """
+        raise NotImplementedError
diff --git a/lmcache/v1/storage_backend/job_executor/pq_executor.py b/lmcache/v1/storage_backend/job_executor/pq_executor.py
new file mode 100644
index 0000000..a75e5e5
--- /dev/null
+++ b/lmcache/v1/storage_backend/job_executor/pq_executor.py
@@ -0,0 +1,235 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from asyncio import CancelledError
+from concurrent.futures import Future
+from typing import Any, Awaitable, Callable
+import asyncio
+import itertools
+
+# First Party
+from lmcache.v1.storage_backend.job_executor.base_executor import BaseJobExecutor
+
+_SENTINEL = object()
+
+
+class AsyncPQExecutor(BaseJobExecutor):
+    """Execute async functions with a priority queue and using event loop"""
+
+    def __init__(self, loop: asyncio.AbstractEventLoop, max_workers: int = 4):
+        max_size = 0  # infinite
+        self.loop = loop
+        # (priority, time_id, fn, args, kwargs, done_future)
+        self._queue: asyncio.PriorityQueue[
+            tuple[
+                int,
+                int,
+                Callable[..., Awaitable[Any]] | object,
+                Any,
+                dict[str, Any],
+                asyncio.Future[Any] | None,
+            ]
+        ] = asyncio.PriorityQueue(maxsize=max_size)
+        # counter breaks ties for equal priority items (FCFS)
+        self._counter = itertools.count()
+        self.max_workers = max_workers
+        # we don't use asyncio.create_task so that PQ executor can be invoked
+        # from sync code
+        self._workers: list[Future] = [
+            asyncio.run_coroutine_threadsafe(self._worker(), loop)
+            for _ in range(max_workers)
+        ]
+        self._closed = False
+
+    async def submit_job(
+        self,
+        fn: Callable[..., Awaitable[Any]],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        # Assign highest priority by default
+        priority = kwargs.pop("priority", 0)
+        done: asyncio.Future[Any] = self.loop.create_future()
+        await self._queue.put((priority, next(self._counter), fn, args, kwargs, done))
+        return await done
+
+    async def _worker(self):
+        while True:
+            try:
+                item = await self._queue.get()
+            except GeneratorExit:
+                # GeneratorExit means the generator/coroutine is being closed,
+                # likely during interpreter shutdown.
+                # Just exit without calling task_done()
+                break
+            except CancelledError:
+                # Task cancellation, we should exit cleanly
+                break
+            except Exception:
+                # Any other exception, break the loop
+                break
+
+            # Detect sentinel both as raw object and wrapped tuple
+            if item is _SENTINEL or (
+                isinstance(item, tuple) and len(item) >= 3 and item[2] is _SENTINEL
+            ):
+                self._queue.task_done()
+                break
+
+            _, _, fn, args, kwargs, done = item
+            try:
+                result = await fn(*args, **kwargs)
+                done.set_result(result)
+            except Exception as e:
+                done.set_exception(e)
+            finally:
+                # decrement task count
+                # join needs to wait until task count is zero
+                self._queue.task_done()
+
+    async def shutdown_async(self, wait: bool = True) -> None:
+        """Async shutdown — safe to call from a coroutine on the event loop.
+
+        Args:
+            wait: If True, drain the queue before shutting down.
+        """
+        if self._closed:
+            return
+        self._closed = True
+
+        # Enqueue comparable sentinel tuples with the highest priority value so
+        # that outstanding work drains before shutdown signals are consumed.
+        # Use a very large integer to satisfy the typed queue's expected int priority
+        sentinel_priority = 2**31 - 1
+
+        # Push sentinel for each worker
+        for _ in range(self.max_workers):
+            await self._queue.put(
+                (sentinel_priority, next(self._counter), _SENTINEL, None, {}, None)
+            )
+
+        # Cancel all worker futures to ensure they stop
+        # Even when wait=False, we should cancel workers to prevent hanging coroutines
+        for fut in self._workers:
+            if not fut.done():
+                fut.cancel()
+
+        if wait:
+            # Let workers drain tasks and exit gracefully
+            await self._queue.join()
+            # Wait for all workers to complete (with cancellation handling)
+            await asyncio.gather(
+                *[asyncio.wrap_future(fut, loop=self.loop) for fut in self._workers],
+                return_exceptions=True,
+            )
+
+    def shutdown(self, wait: bool = True) -> None:
+        """Sync shutdown — blocks the calling thread until shutdown is complete."""
+        future = asyncio.run_coroutine_threadsafe(self.shutdown_async(wait), self.loop)
+        if wait:
+            # Propagate exceptions if any
+            future.result()
+
+
+class AsyncPQThreadPoolExecutor(AsyncPQExecutor):
+    """Execute sync functions with a priority queue and using threadpool"""
+
+    def __init__(self, loop: asyncio.AbstractEventLoop, max_workers: int = 4):
+        max_size = 0  # infinite
+        self.loop = loop
+        self._queue: asyncio.PriorityQueue[
+            tuple[
+                int,
+                int,
+                Callable[..., Any] | object,
+                Any,
+                dict[str, Any],
+                asyncio.Future[Any] | None,
+            ]
+        ] = asyncio.PriorityQueue(maxsize=max_size)
+        # counter breaks ties for equal priority items (FCFS)
+        self._counter = itertools.count()
+        self.max_workers = max_workers
+        self._workers = []
+        for _ in range(max_workers):
+            self._workers.append(
+                asyncio.run_coroutine_threadsafe(self._worker(), self.loop)
+            )
+        self._closed = False
+
+    async def _worker(self):
+        while True:
+            try:
+                item = await self._queue.get()
+            except GeneratorExit:
+                # GeneratorExit means the generator/coroutine is being closed,
+                # likely during interpreter shutdown.
+                # Just exit without calling task_done()
+                break
+            except CancelledError:
+                # Task cancellation, we should exit cleanly
+                break
+            except Exception:
+                # Any other exception, break the loop
+                break
+
+            # Detect sentinel both as raw object and wrapped tuple
+            if item is _SENTINEL or (
+                isinstance(item, tuple) and len(item) >= 3 and item[2] is _SENTINEL
+            ):
+                self._queue.task_done()
+                break
+
+            _, _, fn, args, kwargs, done = item
+            try:
+                result = await asyncio.to_thread(fn, *args, **kwargs)
+                done.set_result(result)
+            except Exception as e:
+                done.set_exception(e)
+            finally:
+                # decrement task count
+                # join needs to wait until task count is zero
+                self._queue.task_done()
+
+    async def shutdown_async(self, wait: bool = True) -> None:
+        """Async shutdown — safe to call from a coroutine on the event loop.
+
+        Args:
+            wait: If True, drain the queue before shutting down.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        # Enqueue comparable sentinel tuples with the highest priority value so
+        # that outstanding work drains before shutdown signals are consumed.
+        # Use a very large integer to satisfy the typed queue's expected int priority
+        sentinel_priority = 2**31 - 1
+        for _ in range(self.max_workers):
+            await self._queue.put(
+                (sentinel_priority, next(self._counter), _SENTINEL, None, {}, None)
+            )
+
+        if wait:
+            # Let workers drain tasks and exit gracefully
+            await self._queue.join()
+            # Cancel all worker futures after queue is drained
+            for fut in self._workers:
+                if not fut.done():
+                    fut.cancel()
+            # Wait for all workers to complete (with cancellation handling)
+            await asyncio.gather(
+                *[asyncio.wrap_future(fut, loop=self.loop) for fut in self._workers],
+                return_exceptions=True,
+            )
+        else:
+            # When wait=False, just cancel workers immediately
+            # This may cause RuntimeError if loop is closed, but that's expected
+            for fut in self._workers:
+                if not fut.done():
+                    fut.cancel()
+
+    def shutdown(self, wait: bool = True) -> None:
+        """Sync shutdown — blocks the calling thread until shutdown is complete."""
+        future = asyncio.run_coroutine_threadsafe(self.shutdown_async(wait), self.loop)
+        if wait:
+            # Propagate exceptions if any
+            future.result()
diff --git a/lmcache/v1/storage_backend/local_cpu_backend.py b/lmcache/v1/storage_backend/local_cpu_backend.py
new file mode 100644
index 0000000..8c0a963
--- /dev/null
+++ b/lmcache/v1/storage_backend/local_cpu_backend.py
@@ -0,0 +1,966 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from concurrent.futures import Future
+from contextlib import nullcontext
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Sequence, Union
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor, PrometheusLogger
+from lmcache.utils import CacheEngineKey, _lmcache_nvtx_annotate
+from lmcache.v1.cache_controller.message import OpType
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_allocators.paged_cpu_gpu_memory_allocator import (
+    PagedCpuGpuMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+from lmcache.v1.storage_backend.batched_message_sender import BatchedMessageSender
+from lmcache.v1.storage_backend.cache_policy import get_cache_policy
+from lmcache.v1.system_detection import NUMADetector, SystemMemoryDetector
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+logger = init_logger(__name__)
+
+
+class LocalCPUBackend(AllocatorBackendInterface):
+    """
+    Even if local_cpu is False (the hot_cache is not used), contains(),
+    insert_key(), remove(), get_blocking(), get_keys(), and clear()
+    are still callable by the storage manager.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: Optional[LMCacheMetadata] = None,
+        dst_device: str = torch_device_type,
+        lmcache_worker: Optional["LMCacheWorker"] = None,
+        memory_allocator: Optional[MemoryAllocatorInterface] = None,
+    ):
+        if torch_dev.is_available():
+            super().__init__(dst_device)
+        else:
+            super().__init__("cpu")
+
+        self.cache_policy = get_cache_policy(config.cache_policy)
+        self.hot_cache = self.cache_policy.init_mutable_mapping()
+
+        self.use_hot = config.local_cpu
+        # NOTE: we keep the memory allocator argument for temporary
+        # test compatibility
+        # TODO: fix the tests to get rid the memory allocator
+        assert metadata is not None or memory_allocator is not None
+        self.memory_allocator = (
+            self.initialize_allocator(config, metadata)  # type: ignore
+            if memory_allocator is None
+            else memory_allocator
+        )
+        self.lmcache_worker = lmcache_worker
+        self.instance_id = config.lmcache_instance_id
+        self.cpu_lock = threading.Lock()
+
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+
+        self.layerwise = config.use_layerwise
+        self.enable_blending = config.enable_blending
+
+        # Store config and metadata for chunk budget calculation
+        self.config = config
+        self.metadata = metadata
+
+        # to help maintain suffix -> prefix order in the dict
+        # assumption: only one request is looked up at a time
+        # (only one worker per cache engine)
+        self.keys_in_request: List[CacheEngineKey] = []
+
+        # Batched message sender for controller communication
+        self.batched_msg_sender: Optional[BatchedMessageSender] = None
+
+        # Initialize batched message sender
+        if lmcache_worker and metadata is not None:
+            self.batched_msg_sender = BatchedMessageSender(
+                metadata=metadata,
+                config=config,
+                location=str(self),  # Backend location
+                lmcache_worker=lmcache_worker,
+            )
+        else:
+            logger.warning("Controller message sender is not initialized")
+
+        self._setup_metrics()
+
+    def _setup_metrics(self) -> None:
+        if self.metadata is None:
+            return
+
+        prometheus_logger = PrometheusLogger.GetOrCreate(
+            self.metadata,
+            config=self.config,
+        )
+        prometheus_logger.local_cpu_hot_cache_count.set_function(
+            lambda: len(self.hot_cache)
+        )
+        prometheus_logger.local_cpu_keys_in_request_count.set_function(
+            lambda: len(self.keys_in_request)
+        )
+
+    def __str__(self):
+        return self.__class__.__name__
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        with self.cpu_lock:
+            if key not in self.hot_cache:
+                return False
+            if pin:
+                self.hot_cache[key].pin()
+                # vllm lookup sets pin to True
+                self.keys_in_request.append(key)
+            return True
+
+    def touch_cache(self):
+        # flip the order of the keys in the request
+        with self.cpu_lock:
+            for key in reversed(self.keys_in_request):
+                self.cache_policy.update_on_hit(key, self.hot_cache)
+            self.keys_in_request = []
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """
+        contains() and exists_in_put_tasks() should be checked together
+        """
+        return False
+
+    def submit_put_task(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Optional[Future]:
+        """
+        Synchronously put the MemoryObj into the local cpu backend.
+
+        :param on_complete_callback: Optional callback invoked after the
+            synchronous put completes. Callback exceptions are caught and logged.
+        """
+        stored = False
+        with self.cpu_lock:
+            if key in self.hot_cache:
+                return None
+
+            memory_obj.ref_count_up()
+            self.hot_cache[key] = memory_obj
+
+            self.cache_policy.update_on_put(key)
+
+            # Push kv admit msg with batching
+            if self.batched_msg_sender is not None:
+                self.batched_msg_sender.add_kv_op(
+                    op_type=OpType.ADMIT,
+                    key=key.chunk_hash,
+                )
+            stored = True
+
+        # Call callback after put completes (outside lock)
+        if stored and on_complete_callback is not None:
+            try:
+                on_complete_callback(key)
+            except Exception as e:
+                logger.warning("on_complete_callback failed for key %s: %s", key, e)
+
+        return None
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        Synchronously put the MemoryObjs into the local cpu backend.
+
+        :param on_complete_callback: Optional callback invoked once per key
+            after that key's put completes (not once per batch).
+        """
+        if not self.use_hot:
+            return
+
+        # TODO(Jiayi): optimize this with batching
+        for key, memory_obj in zip(keys, memory_objs, strict=False):
+            self.submit_put_task(
+                key, memory_obj, on_complete_callback=on_complete_callback
+            )
+
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        with self.cpu_lock:
+            if key not in self.hot_cache:
+                return None
+            memory_obj = self.hot_cache[key]
+            # ref count up for caller to avoid situation where the memory_obj
+            # is evicted from the local cpu backend before the caller calls
+            # ref count up themselves
+            memory_obj.ref_count_up()
+            return memory_obj
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        mem_objs = []
+        with self.cpu_lock:
+            for key in keys:
+                mem_obj = self.hot_cache[key]
+                mem_obj.ref_count_up()
+                mem_objs.append(mem_obj)
+        return mem_objs
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        # NOTE(Jiayi): Only prefix chunks are counted.
+        num_hit_chunks = 0
+        with self.cpu_lock:
+            for key in keys:
+                if key not in self.hot_cache:
+                    return num_hit_chunks
+                if pin:
+                    self.hot_cache[key].pin()
+                    # vllm lookup sets pin to True
+                    self.keys_in_request.append(key)
+                num_hit_chunks += 1
+        return num_hit_chunks
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        with self.cpu_lock:
+            if key not in self.hot_cache:
+                return False
+            memory_obj = self.hot_cache[key]
+            memory_obj.pin()
+            return True
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        with self.cpu_lock:
+            if key not in self.hot_cache:
+                return False
+            memory_obj = self.hot_cache[key]
+            memory_obj.unpin()
+            return True
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        lock_context = self.cpu_lock if force else nullcontext()
+        with lock_context:
+            if key not in self.hot_cache:
+                return False
+
+            memory_obj = self.hot_cache.pop(key)
+            memory_obj.ref_count_down()
+
+            if force:
+                self.cache_policy.update_on_force_evict(key)
+
+        if self.batched_msg_sender is not None:
+            self.batched_msg_sender.add_kv_op(
+                op_type=OpType.EVICT,
+                key=key.chunk_hash,
+            )
+        # NOTE (Jiayi): This `return True` might not accurately reflect
+        # whether the key is removed from the actual memory because
+        # other backends might still (temporarily) hold the memory object.
+        return True
+
+    def _calculate_effective_cpu_size(
+        self,
+        configured_cpu_size: float,
+        config: LMCacheEngineConfig,
+        metadata: Optional[LMCacheMetadata] = None,
+    ) -> float:
+        """
+        Calculate the effective CPU memory size based on system available memory
+        and reserve memory configuration.
+
+        Args:
+            configured_cpu_size: The configured CPU memory size in GB
+            config: The LMCache engine configuration
+            metadata: Optional metadata for first rank handling
+
+        Returns:
+            The effective CPU memory size in GB
+        """
+
+        save_only_first_rank = (
+            metadata is not None
+            and config.get_extra_config_value("save_only_first_rank", metadata.use_mla)
+            and metadata.use_mla
+        )
+        if not save_only_first_rank:
+            # Do not adjust cpu_size if save_only_first_rank is False for now
+            return configured_cpu_size
+
+        # Get the system available memory and calculate effective cpu_size
+        system_available_memory_gb = SystemMemoryDetector.get_available_memory_gb()
+        # Get reserve memory size from config
+        reserve_cpu_size = config.reserve_local_cpu_size
+
+        # TODO(baoloongmao): For disable save_only_first_rank case,
+        #  we need to avoid multi-rank race condition in future.
+        #  But for enable save_only_first_rank case,
+        #  we can handle reserve memory simply since non-first ranks
+        #  do not allocate memory.
+        # Effective memory: min(configured_size, available_memory - reserve_size)
+        if system_available_memory_gb > 0:
+            max_usable_memory = max(0, system_available_memory_gb - reserve_cpu_size)
+            effective_cpu_size = min(configured_cpu_size, max_usable_memory)
+            logger.info(
+                "Adjusted CPU memory size from %.2f GB "
+                "to %.2f GB "
+                "(system available: %.2f GB, "
+                "reserve: %.2f GB)",
+                configured_cpu_size,
+                effective_cpu_size,
+                system_available_memory_gb,
+                reserve_cpu_size,
+            )
+            assert effective_cpu_size > 0
+            return effective_cpu_size
+        else:
+            logger.warning(
+                "Could not determine system available memory, using configured cpu_size"
+            )
+            return configured_cpu_size
+
+    def initialize_allocator(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: Optional[LMCacheMetadata] = None,
+    ) -> MemoryAllocatorInterface:
+        cpu_size = config.max_local_cpu_size
+        use_hugepages = config.local_cpu_use_hugepages
+
+        if metadata is not None:
+            # save_only_first_rank only works when use mla
+            save_only_first_rank = (
+                config.get_extra_config_value("save_only_first_rank", metadata.use_mla)
+                and metadata.use_mla
+            )
+
+            if save_only_first_rank and metadata.is_first_rank():
+                # Only the first rank will save the cache,
+                # so we need to set it larger than other ranks
+                cpu_size = config.get_extra_config_value(
+                    "first_rank_max_local_cpu_size", cpu_size
+                )
+
+        # Detect the numa mapping
+        numa_mapping = NUMADetector.get_numa_mapping(config)
+        logger.info("NUMA mapping %s", numa_mapping)
+
+        # Calculate effective CPU memory size
+        cpu_size = self._calculate_effective_cpu_size(cpu_size, config, metadata)
+        cpu_size_bytes = int(cpu_size * 1024**3)
+
+        allocator_align_bytes = self._resolve_local_cpu_allocator_alignment(config)
+        if allocator_align_bytes is not None:
+            logger.info(
+                "LocalCPUBackend: using pinned allocation alignment=%d bytes",
+                allocator_align_bytes,
+            )
+
+        if config.enable_p2p:
+            if use_hugepages:
+                raise ValueError("Hugepages are not supported with P2P mode")
+
+            # TODO(baoloongmao): Add lazy memory allocator support for P2P mode
+            # For now, keep the original P2P implementation
+            assert metadata is not None
+            shapes = metadata.get_shapes()
+            dtypes = metadata.get_dtypes()
+
+            paged_mem_allocator = PagedCpuGpuMemoryAllocator()
+            chunk_size_bytes = get_size_bytes(shapes, dtypes)
+            origin_cpu_size_bytes = cpu_size_bytes
+            align_cpu_size_bytes = (
+                origin_cpu_size_bytes // chunk_size_bytes * chunk_size_bytes
+            )
+            logger.info(
+                "Auto align cpu size bytes, origin: %s, aligned: %s, chunk size: %s",
+                origin_cpu_size_bytes,
+                align_cpu_size_bytes,
+                chunk_size_bytes,
+            )
+            paged_mem_allocator.init_cpu_memory_allocator(
+                align_cpu_size_bytes,
+                shapes=shapes,
+                dtypes=dtypes,
+                fmt=MemoryFormat.KV_2LTD,  # TODO: remove this hardcode
+                numa_mapping=numa_mapping,
+            )
+            return paged_mem_allocator
+        else:
+            extra_config = config.extra_config
+            nixl_cpu_enabled = (
+                extra_config is not None
+                and extra_config.get("enable_nixl_storage")
+                and config.nixl_buffer_device == "cpu"
+            )
+
+            if nixl_cpu_enabled:
+                if metadata is None:
+                    raise ValueError("metadata required for NIXL CPU mode")
+                chunk_bytes = get_size_bytes(
+                    metadata.get_shapes(), metadata.get_dtypes()
+                )
+                aligned_size = (cpu_size_bytes // chunk_bytes) * chunk_bytes
+                if aligned_size == 0:
+                    raise ValueError(
+                        f"max_local_cpu_size ({cpu_size_bytes} bytes) is smaller than "
+                        f"one chunk ({chunk_bytes} bytes); cannot initialize NIXL CPU "
+                        f"shared pool"
+                    )
+                if aligned_size != cpu_size_bytes:
+                    logger.warning(
+                        "max_local_cpu_size not a multiple of chunk size; "
+                        "rounding down from %d to %d bytes for NIXL shared pool",
+                        cpu_size_bytes,
+                        aligned_size,
+                    )
+                return MixedMemoryAllocator(
+                    aligned_size,
+                    use_paging=True,
+                    use_hugepages=use_hugepages,
+                    numa_mapping=numa_mapping,
+                    shapes=metadata.get_shapes(),
+                    dtypes=metadata.get_dtypes(),
+                    fmt=MemoryFormat.KV_2LTD,
+                )
+
+            # Check if io_uring is enabled for fixed buffer support
+            io_engine = str(
+                config.get_extra_config_value("rust_raw_block.io_engine", "") or ""
+            ).lower()
+            use_uring = (
+                io_engine == "io_uring"
+                or bool(
+                    config.get_extra_config_value("rust_raw_block.use_iouring", False)
+                )
+                or bool(
+                    config.get_extra_config_value("rust_raw_block.use_uring", False)
+                )
+            )
+
+            # Check if lazy memory allocator should be enabled
+            use_lazy = (
+                config.enable_lazy_memory_allocator
+                and cpu_size > config.lazy_memory_safe_size
+            )
+            if use_lazy:
+                logger.warning(
+                    "LazyMixedMemoryAllocator is temporarily unavailable; "
+                    "falling back to MixedMemoryAllocator with full allocation. "
+                    "Disable enable_lazy_memory_allocator or reduce "
+                    "max_local_cpu_size to avoid large pinned allocations."
+                )
+            elif config.enable_lazy_memory_allocator:
+                logger.info(
+                    "LazyMixedMemoryAllocator is disabled because "
+                    "cpu_size (%.2f GB) does not exceed "
+                    "lazy_memory_safe_size "
+                    "(%.2f GB). "
+                    "Using MixedMemoryAllocator instead.",
+                    cpu_size,
+                    config.lazy_memory_safe_size,
+                )
+
+            # For io_uring, use paged memory allocator so that fixed buffer support
+            # can be enabled
+            if use_uring and metadata is not None:
+                shapes = metadata.get_shapes()
+                dtypes = metadata.get_dtypes()
+                # Determine memory format based on layerwise and blending settings
+                if config.use_layerwise:
+                    if config.enable_blending:
+                        fmt = MemoryFormat.KV_2TD
+                    else:
+                        fmt = MemoryFormat.KV_T2D
+                else:
+                    fmt = MemoryFormat.KV_2LTD
+
+                # Calculate chunk size for alignment
+                chunk_size_bytes = get_size_bytes(shapes, dtypes)
+                origin_cpu_size_bytes = cpu_size_bytes
+                # Align cpu_size_bytes to be a multiple of chunk_size_bytes
+                align_cpu_size_bytes = (
+                    origin_cpu_size_bytes // chunk_size_bytes * chunk_size_bytes
+                )
+                logger.info(
+                    "LocalCPUBackend: using MixedMemoryAllocator with use_paging=True "
+                    "for io_uring fixed buffer support. "
+                    "Auto align cpu size bytes, origin: %s, "
+                    "aligned: %s, chunk size: %s",
+                    origin_cpu_size_bytes,
+                    align_cpu_size_bytes,
+                    chunk_size_bytes,
+                )
+
+                kwargs = {
+                    "numa_mapping": numa_mapping,
+                    "shapes": shapes,
+                    "dtypes": dtypes,
+                    "fmt": fmt,
+                    **(
+                        {"align_bytes": allocator_align_bytes}
+                        if allocator_align_bytes is not None
+                        else {}
+                    ),
+                }
+                return MixedMemoryAllocator(
+                    align_cpu_size_bytes,
+                    use_paging=True,
+                    use_hugepages=False,
+                    **kwargs,
+                )
+
+            # Default: use non-paged allocator
+            if allocator_align_bytes is not None:
+                return MixedMemoryAllocator(
+                    cpu_size_bytes,
+                    numa_mapping=numa_mapping,
+                    align_bytes=allocator_align_bytes,
+                    use_hugepages=use_hugepages,
+                )
+            return MixedMemoryAllocator(
+                cpu_size_bytes,
+                numa_mapping=numa_mapping,
+                config=config,
+                use_hugepages=use_hugepages,
+            )
+
+    @staticmethod
+    def _is_power_of_two(value: int) -> bool:
+        return value > 0 and (value & (value - 1)) == 0
+
+    def _resolve_local_cpu_allocator_alignment(
+        self, config: LMCacheEngineConfig
+    ) -> Optional[int]:
+        """
+        Determine pinned-memory alignment for LocalCPUBackend allocator.
+
+        Precedence:
+        1) explicit override: extra_config["local_cpu.pinned_align_bytes"]
+        2) rust raw block auto mode:
+           - rust_raw_block.device_path is set
+           - rust_raw_block.use_odirect is true or rust_raw_block.use_uring is true
+           - rust_raw_block.align_local_cpu_allocator is true (default)
+           -> use rust_raw_block.block_align
+        3) None (use allocator default)
+        """
+        extra = config.extra_config or {}
+
+        explicit_align = extra.get("local_cpu.pinned_align_bytes")
+        if explicit_align is not None:
+            align = int(explicit_align)
+            if not self._is_power_of_two(align):
+                raise ValueError(
+                    "extra_config['local_cpu.pinned_align_bytes'] must be "
+                    "a positive power of two"
+                )
+            return align
+
+        rust_device_path = extra.get("rust_raw_block.device_path")
+        rust_use_odirect = bool(extra.get("rust_raw_block.use_odirect", False))
+        rust_io_engine = str(extra.get("rust_raw_block.io_engine", "") or "").lower()
+        rust_use_uring = (
+            rust_io_engine == "io_uring"
+            or bool(extra.get("rust_raw_block.use_iouring", False))
+            or bool(extra.get("rust_raw_block.use_uring", False))
+        )
+        rust_auto_align = bool(
+            extra.get("rust_raw_block.align_local_cpu_allocator", True)
+        )
+
+        if not rust_device_path:
+            return None
+
+        # Alignment is needed if either O_DIRECT is set or io_uring is enabled
+        if not rust_use_odirect and not rust_use_uring:
+            return None
+
+        # For non io_uring_case, respect the auto_align flag
+        if not rust_use_uring and not rust_auto_align:
+            return None
+
+        rust_block_align = int(extra.get("rust_raw_block.block_align", 4096))
+        if not self._is_power_of_two(rust_block_align):
+            raise ValueError(
+                "extra_config['rust_raw_block.block_align'] must be a positive "
+                "power of two when O_DIRECT or io_uring alignment is enabled"
+            )
+        return rust_block_align
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: Optional[MemoryFormat] = None,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        """
+        Allocate a memory object of shape and dtype
+        evict if necessary. Storage manager should always call
+        local_cpu_backend.allocate() to get memory objects
+        regardless of whether local_cpu is True or False
+
+        busy_loop should only be used for retrieve
+        the reasoning is that:
+
+        1. synchronous case
+        - many stores happen concurrently (if they busy_loop, deadlock happens)
+        - one retrieve at a time (okay to busy loop because stores will clear)
+
+        2. asynchronous case
+        - many stores happen concurrently (if they busy_loop, deadlock happens)
+        - many retrieves happen concurrently
+        (we use the async serializer to handle this)
+        """
+        logger.debug(
+            "Allocating memory in local cpu backend with busy loop: %s", busy_loop
+        )
+        if fmt is None:
+            if self.layerwise:
+                if self.enable_blending:
+                    fmt = MemoryFormat.KV_2TD
+                else:
+                    fmt = MemoryFormat.KV_T2D
+            else:
+                fmt = MemoryFormat.KV_2LTD
+
+        memory_obj = self.memory_allocator.allocate(shapes, dtypes, fmt)
+        if memory_obj is not None or not eviction:
+            return memory_obj
+
+        evict_keys_count = 0
+        num_attempts = 0
+        while True:
+            # whether or not this request needs to wait or other requests
+            wait_other_requests = True
+            if self.use_hot:
+                # TODO(Jiayi): optimize `num_candidates` with estimation.
+                # Accurate estimation is hard due to fragmentation
+                num_candidates = 1
+                evict_keys = None
+                with self.cpu_lock:
+                    evict_keys = self.cache_policy.get_evict_candidates(
+                        self.hot_cache, num_candidates=num_candidates
+                    )
+                    if evict_keys:
+                        # we can continue trying to evict from the hot_cache
+                        # and don't need to wait for other requests yet
+                        wait_other_requests = False
+                        logger.debug(
+                            "Evicting %d chunks from cpu memory", len(evict_keys)
+                        )
+                        # remove
+                        self.batched_remove(evict_keys, force=False)
+                        evict_keys_count += len(evict_keys)
+                    else:
+                        self.stats_monitor.update_local_cpu_evict_failed_count(
+                            num_candidates
+                        )
+
+            if wait_other_requests:
+                if not busy_loop:
+                    logger.debug(
+                        "Not busy looping because we are not immediately able to evict"
+                    )
+                    break
+
+                # TODO: make time_to_wait a config
+                time_to_wait = 0.1
+                logger.warning(
+                    "No eviction candidates found in local cpu backend. "
+                    "Local cpu memory is under pressure. "
+                    "Waiting for %s seconds before retrying.",
+                    time_to_wait,
+                )
+                # self.memory_allocator.memcheck()
+                # do not hold the lock during sleep
+                time.sleep(time_to_wait)
+
+            memory_obj = self.memory_allocator.allocate(shapes, dtypes, fmt)
+            if memory_obj is not None:
+                break
+
+            num_attempts += 1
+            logger.debug(
+                "Unable to allocate memory object after %d"
+                " attempts of local cpu backend allocate()",
+                num_attempts,
+            )
+
+        self.stats_monitor.update_local_cpu_evict_metrics(evict_keys_count)
+        return memory_obj
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: Optional[MemoryFormat] = None,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[List[MemoryObj]]:
+        """
+        Batched allocate `batch_size` memory objects of shape and dtype
+        evict if necessary. Storage manager should always call
+        local_cpu_backend.allocate() to get memory objects
+        regardless of whether local_cpu is True or False
+
+        busy_loop should only be used for retrieve
+        the reasoning is that:
+
+        1. synchronous case
+        - many stores happen concurrently (if they busy_loop, deadlock happens)
+        - one retrieve at a time (okay to busy loop because stores will clear)
+
+        2. asynchronous case
+        - many stores happen concurrently (if they busy_loop, deadlock happens)
+        - many retrieves happen concurrently
+        (we use the async serializer to handle this)
+        """
+        logger.debug(
+            "Batched allocating memory in local cpu backend with busy loop: %s",
+            busy_loop,
+        )
+        if fmt is None:
+            if self.layerwise:
+                if self.enable_blending:
+                    fmt = MemoryFormat.KV_2TD
+                else:
+                    fmt = MemoryFormat.KV_T2D
+            else:
+                fmt = MemoryFormat.KV_2LTD
+
+        memory_objs = self.memory_allocator.batched_allocate(
+            shapes, dtypes, batch_size, fmt
+        )
+
+        if memory_objs is not None or not eviction:
+            return memory_objs
+
+        assert isinstance(self.memory_allocator, MixedMemoryAllocator)
+
+        evict_keys_count = 0
+        num_attempts = 0
+        while True:
+            wait_other_requests = True
+            if self.use_hot:
+                # TODO(Jiayi): optimize `num_candidates` with estimation.
+                # Accurate estimation is hard due to fragmentation
+                num_candidates = min(64, max(1, len(self.hot_cache)))
+                evict_keys = None
+                with self.cpu_lock:
+                    evict_keys = self.cache_policy.get_evict_candidates(
+                        self.hot_cache, num_candidates=num_candidates
+                    )
+
+                    # HACK: We assume batch_size=num_layers here.
+                    # FIXME: We also assume if the one layer's ref_count > 1 or pinned,
+                    # then the other layers are also ref_count > 1 or
+                    # pinned in the cpu memory. This might not be true.
+                    if evict_keys:
+                        for evict_key in evict_keys:
+                            evict_key_all_layer = evict_key.split_layers(batch_size)
+
+                            # TODO(Jiayi): batched allocate is not supported through
+                            # `batched_remove`. Therefore, features like usage tracking
+                            # is not supported.
+                            old_mem_objs: list[MemoryObj] = []
+                            for key in evict_key_all_layer:
+                                old_mem_obj = self.hot_cache.get(key)
+                                if old_mem_obj is None or not old_mem_obj.can_evict:
+                                    old_mem_objs = []
+                                    break
+                                old_mem_objs.append(old_mem_obj)
+
+                            if not old_mem_objs:
+                                continue
+
+                            wait_other_requests = False
+                            evict_keys_count += len(old_mem_objs)
+                            for key in evict_key_all_layer:
+                                self.cache_policy.update_on_force_evict(key)
+                                self.hot_cache.pop(key, None)
+
+                            self.memory_allocator.batched_free(old_mem_objs)
+
+                            logger.debug(
+                                "Evicting %d chunks from cpu memory", len(old_mem_objs)
+                            )
+                            break
+                    if wait_other_requests:
+                        self.stats_monitor.update_local_cpu_evict_failed_count(
+                            num_candidates
+                        )
+
+            if wait_other_requests:
+                if not busy_loop:
+                    logger.debug(
+                        "Not busy looping because we are not immediately able to evict"
+                    )
+                    break
+
+                # TODO: make time_to_wait a config
+                time_to_wait = 0.1
+                logger.warning(
+                    "No eviction candidates found in local cpu backend. "
+                    "Local cpu memory is under pressure. "
+                    "Waiting for %s seconds before retrying.",
+                    time_to_wait,
+                )
+                # self.memory_allocator.memcheck()
+                # do not hold the lock during sleep
+                time.sleep(time_to_wait)
+
+            memory_objs = self.memory_allocator.batched_allocate(
+                shapes, dtypes, batch_size, fmt
+            )
+            if memory_objs is not None:
+                break
+
+            num_attempts += 1
+            logger.debug(
+                "Unable to allocate memory object after %d"
+                " attempts of local cpu backend batched_allocate()",
+                num_attempts,
+            )
+        self.stats_monitor.update_local_cpu_evict_metrics(evict_keys_count)
+        return memory_objs
+
+    def get_full_chunk_size_bytes(self) -> int:
+        logger.info("Calculating the size of a single LMCache chunk")
+        assert self.metadata is not None, (
+            "metadata required for chunk budget calculation"
+        )
+
+        chunk_tokens = self.config.chunk_size
+        # already accounted for parallelism
+        kv_shape = (
+            self.metadata.kv_shape
+        )  # [num_layers, kv_size, chunk_size, num_heads, head_size]
+        num_layers = kv_shape[0]
+        kv_size = kv_shape[1]  # 1 for MLA, 2 for regular
+        # per gpu
+        num_heads = kv_shape[3]
+        head_size = kv_shape[4]
+        hidden_dim = num_heads * head_size
+        dtype_size = self.metadata.kv_dtype.itemsize
+
+        if self.layerwise:
+            # layerwise: [chunk_tokens, kv_size, hidden_dim]
+            chunk_bytes = chunk_tokens * kv_size * hidden_dim * dtype_size
+        else:
+            # full: [kv_size, num_layers, chunk_tokens, hidden_dim]
+            chunk_bytes = kv_size * num_layers * chunk_tokens * hidden_dim * dtype_size
+        logger.debug(
+            "Stats received: num_layers=%s, kv_size=%s, "
+            "chunk_tokens=%s, head_dim=%s, "
+            "dtype_size=%s, "
+            "hidden_dim=%s",
+            num_layers,
+            kv_size,
+            chunk_tokens,
+            head_size,
+            dtype_size,
+            hidden_dim,
+        )
+        logger.debug("Calculated bytes per chunk per rank: %s", chunk_bytes)
+        return chunk_bytes
+
+    def calculate_chunk_budget(self) -> int:
+        """
+        Calculate the maximum number of chunks that can be allocated concurrently
+        without causing memory deadlocks in the async loading system.
+
+        Returns:
+            int: The estimated chunk budget for concurrent allocations
+        """
+        total_memory = int(self.config.max_local_cpu_size * 1024**3)
+        chunk_bytes = self.get_full_chunk_size_bytes()
+        # add alignment overhead
+        # (MixedMemoryAllocator uses TensorMemoryAllocator with 4KB alignment)
+        assert hasattr(self.memory_allocator, "align_bytes")
+        alignment = self.memory_allocator.align_bytes
+        aligned_chunk_bytes = ((chunk_bytes + alignment - 1) // alignment) * alignment
+
+        # calculate budget with safety margin
+        max_chunks = total_memory // aligned_chunk_bytes
+
+        return max_chunks
+
+    def get_keys(self) -> List[CacheEngineKey]:
+        """
+        array ordering of keys from LRU to MRU
+        """
+        with self.cpu_lock:
+            return list(self.hot_cache.keys())
+
+    def clear(self) -> int:
+        """
+        counts the number of memory objects removed
+        """
+        if not self.use_hot:
+            return 0
+        clear_keys = []
+        num_cleared_tokens = 0
+        with self.cpu_lock:
+            for key in self.hot_cache:
+                memory_obj = self.hot_cache[key]
+                if not memory_obj.can_evict:
+                    continue
+                clear_keys.append(key)
+                num_cleared_tokens += memory_obj.get_num_tokens()
+
+        # TODO(Jiayi): might not be accurate if we don't calculate
+        # `num_cleared_token` and remove the keys in an atomic way.
+        self.batched_remove(clear_keys)
+
+        return num_cleared_tokens
+
+    def get_allocator_backend(self):
+        return self
+
+    def get_memory_allocator(self):
+        return self.memory_allocator
+
+    def close(self) -> None:
+        if self.batched_msg_sender is not None:
+            self.batched_msg_sender.close()
+        self.memory_allocator.close()
+        self.clear()
diff --git a/lmcache/v1/storage_backend/local_disk_backend.py b/lmcache/v1/storage_backend/local_disk_backend.py
new file mode 100644
index 0000000..0b2230b
--- /dev/null
+++ b/lmcache/v1/storage_backend/local_disk_backend.py
@@ -0,0 +1,774 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from concurrent.futures import Future, ThreadPoolExecutor
+from contextlib import nullcontext
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Sequence
+import asyncio
+import os
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey, DiskCacheMetadata, _lmcache_nvtx_annotate
+from lmcache.v1.cache_controller.message import OpType
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+from lmcache.v1.storage_backend.batched_message_sender import BatchedMessageSender
+from lmcache.v1.storage_backend.cache_policy import get_cache_policy
+from lmcache.v1.storage_backend.job_executor.pq_executor import (
+    AsyncPQThreadPoolExecutor,
+)
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.path_sharder import PathSharder
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+
+logger = init_logger(__name__)
+
+_DEFAULT_THREAD_COUNT = 4
+
+
+# TODO(Jiayi): handle cases where cache is repetitvely prefetched.
+class LocalDiskWorker:
+    def __init__(
+        self, loop: asyncio.AbstractEventLoop, max_workers: int = _DEFAULT_THREAD_COUNT
+    ) -> None:
+        self.put_lock = threading.Lock()
+        self.put_tasks: List[CacheEngineKey] = []
+
+        self.prefetch_lock = threading.Lock()
+        self.prefetch_tasks: dict[CacheEngineKey, Future] = {}
+
+        self.executor = AsyncPQThreadPoolExecutor(loop, max_workers=max_workers)
+        self.loop = loop
+        self._closed = False
+
+    async def submit_task(
+        self,
+        task_type: str,
+        task: Callable,
+        *args,
+        **kwargs,
+    ) -> Any:
+        if task_type == "prefetch":
+            priority = 0
+            # self.insert_prefetch_task(kwargs["key"], None)
+        elif task_type == "delete":
+            priority = 1
+        elif task_type == "put":
+            priority = 2
+        else:
+            raise ValueError(f"Unknown task type: {task_type}")
+
+        return await self.executor.submit_job(
+            task,
+            *args,
+            priority=priority,
+            **kwargs,
+        )
+
+    def remove_put_task(self, key: CacheEngineKey):
+        with self.put_lock:
+            if key in self.put_tasks:
+                self.put_tasks.remove(key)
+            else:
+                logger.warning(f"Key {key} not found in put tasks.")
+
+    def insert_put_task(self, key: CacheEngineKey):
+        with self.put_lock:
+            self.put_tasks.append(key)
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        with self.put_lock:
+            return key in self.put_tasks
+
+    def close(self):
+        # Gracefully shut down the executor
+        if self._closed:
+            return
+        self._closed = True
+        self.executor.shutdown(wait=True)
+
+
+class LocalDiskBackend(StorageBackendInterface):
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        dst_device: str = torch_device_type,
+        lmcache_worker: Optional["LMCacheWorker"] = None,
+        metadata: Optional[LMCacheMetadata] = None,
+    ):
+        if torch_dev.is_available():
+            super().__init__(dst_device)
+        else:
+            super().__init__("cpu")
+
+        self.cache_policy = get_cache_policy(config.cache_policy)
+        self.dict = self.cache_policy.init_mutable_mapping()
+
+        self.dst_device = dst_device
+
+        self.local_cpu_backend = local_cpu_backend
+
+        self.disk_lock = threading.Lock()
+
+        assert config.local_disk is not None
+
+        sharder = PathSharder(
+            raw_csv=config.local_disk,
+            strategy=config.local_disk_path_sharding,
+            dst_device=dst_device,
+            create_dirs=True,
+        )
+        self.path: str = sharder.selected
+
+        logger.info(
+            "Local disk cache path: %s (device %s, %d path(s) configured)",
+            self.path,
+            dst_device,
+            len(sharder.all_paths),
+        )
+
+        self.loop = loop
+
+        self.use_local_cpu = config.local_cpu
+
+        # Block size (for file system I/O)
+        stat = os.statvfs(self.path)
+        self.os_disk_bs = stat.f_bsize
+        self.use_odirect = False
+
+        if config.extra_config is not None:
+            self.use_odirect = config.extra_config.get("use_odirect", False)
+        logger.info("Using O_DIRECT for disk I/O: %s", self.use_odirect)
+
+        thread_count = config.get_extra_config_value(
+            "disk_io_threads", _DEFAULT_THREAD_COUNT
+        )
+        self.disk_worker = LocalDiskWorker(loop, max_workers=thread_count)
+
+        # Plain ThreadPoolExecutor for batched_get_blocking (concurrent
+        # synchronous reads).  The existing AsyncPQThreadPoolExecutor in
+        # disk_worker is async/priority-queue based and only serves writes
+        # and prefetches; a simple pool is a better fit for the blocking
+        # read path where we want ThreadPoolExecutor.map() semantics.
+        self._read_thread_pool = ThreadPoolExecutor(
+            max_workers=thread_count,
+            thread_name_prefix="disk-read",
+        )
+
+        # TODO(Jiayi): We need a disk space allocator to avoid fragmentation
+        # and hide the following details away from the backend.
+        self.max_cache_size = int(config.max_local_disk_size * 1024**3)
+        self.current_cache_size = 0.0
+
+        # to help maintain suffix -> prefix order in the dict
+        # assumption: only one request is looked up at a time
+        # (only one worker per cache engine)
+        self.keys_in_request: List[CacheEngineKey] = []
+
+        self.lmcache_worker = lmcache_worker
+        self.instance_id = config.lmcache_instance_id
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+        self.usage = 0
+
+        # Batched message sender for controller communication
+        self.batched_msg_sender: Optional[BatchedMessageSender] = None
+
+        # Initialize batched message sender
+        if lmcache_worker and metadata is not None:
+            self.batched_msg_sender = BatchedMessageSender(
+                metadata=metadata,
+                config=config,
+                location=str(self),
+                lmcache_worker=lmcache_worker,
+            )
+        else:
+            logger.warning("Controller message sender is not initialized")
+
+    def __str__(self) -> str:
+        return "LocalDiskBackend"
+
+    def _key_to_path(
+        self,
+        key: CacheEngineKey,
+    ) -> str:
+        return os.path.join(self.path, key.to_string().replace("/", "-") + ".pt")
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        with self.disk_lock:
+            if key not in self.dict:
+                return False
+            if pin:
+                self.dict[key].pin()
+                # vllm lookup sets pin to True
+                self.keys_in_request.append(key)
+            return True
+
+    def touch_cache(self):
+        # flip the order of the keys in the request
+        with self.disk_lock:
+            for key in reversed(self.keys_in_request):
+                self.cache_policy.update_on_hit(key, self.dict)
+            self.keys_in_request = []
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        return self.disk_worker.exists_in_put_tasks(key)
+
+    def pin(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        with self.disk_lock:
+            if key in self.dict:
+                self.dict[key].pin()
+                return True
+            else:
+                return False
+
+    def unpin(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        with self.disk_lock:
+            if key in self.dict:
+                self.dict[key].unpin()
+                return True
+            else:
+                return False
+
+    def remove(
+        self,
+        key: CacheEngineKey,
+        force: bool = True,
+    ) -> bool:
+        lock_context = self.disk_lock if force else nullcontext()
+        with lock_context:
+            if not (meta := self.dict.pop(key, None)):
+                return False
+
+            path = meta.path
+            size = meta.size
+            self.usage -= size
+            self.stats_monitor.update_local_storage_usage(self.usage)
+
+            # NOTE: The following code will cause deadlock
+            # res = asyncio.run_coroutine_threadsafe(
+            #     self.disk_worker.submit_task("delete", os.remove, path),
+            #     self.loop,
+            # )
+            # res.result()
+
+            os.remove(path)
+
+            if force:
+                self.cache_policy.update_on_force_evict(key)
+
+        # Push kv evict msg with batching
+        if self.batched_msg_sender is not None:
+            self.batched_msg_sender.add_kv_op(
+                op_type=OpType.EVICT,
+                key=key.chunk_hash,
+            )
+
+        return True
+
+    def insert_key(
+        self,
+        key: CacheEngineKey,
+        size: int,
+        shape: torch.Size,
+        dtype: torch.dtype,
+        fmt: MemoryFormat,
+        cached_positions: Optional[torch.Tensor] = None,
+    ) -> None:
+        path = self._key_to_path(key)
+
+        has_stored = False
+        with self.disk_lock:
+            if key in self.dict:
+                # Update cache recency
+                self.cache_policy.update_on_hit(key, self.dict)
+                has_stored = True
+            else:
+                self.dict[key] = DiskCacheMetadata(
+                    path, size, shape, dtype, cached_positions, fmt, 0
+                )
+
+        # Push kv admit msg with batching
+        if self.batched_msg_sender is not None and not has_stored:
+            self.batched_msg_sender.add_kv_op(
+                op_type=OpType.ADMIT,
+                key=key.chunk_hash,
+            )
+
+    def submit_put_task(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ):
+        """
+        Submit a single put task to store KV cache to disk asynchronously.
+
+        :param key: The cache key for this KV chunk.
+        :param memory_obj: The memory object containing the KV data.
+        :param on_complete_callback: Optional callback invoked once per key
+            after the disk write completes. Callback exceptions are caught
+            and logged.
+        """
+        assert memory_obj.tensor is not None
+
+        # skip repeated save
+        if self.exists_in_put_tasks(key):
+            logger.debug(f"Put task for {key} is already in progress.")
+            return None
+
+        self.disk_worker.insert_put_task(key)
+
+        # TODO(Jiayi): Fragmentation is not considered here.
+        required_size = memory_obj.get_physical_size()
+        all_evict_keys = []
+        evict_success = True
+        with self.disk_lock:
+            while self.current_cache_size + required_size > self.max_cache_size:
+                evict_keys = self.cache_policy.get_evict_candidates(
+                    self.dict, num_candidates=1
+                )
+                if not evict_keys:
+                    logger.warning(
+                        "No eviction candidates found. Disk space under pressure."
+                    )
+                    evict_success = False
+                    break
+
+                for evict_key in evict_keys:
+                    self.current_cache_size -= self.dict[evict_key].size
+
+                self.batched_remove(evict_keys, force=False)
+
+                all_evict_keys.extend(evict_keys)
+            if evict_success:
+                self.current_cache_size += required_size
+                self.cache_policy.update_on_put(key)
+
+        if not evict_success:
+            return None
+
+        memory_obj.ref_count_up()
+
+        asyncio.run_coroutine_threadsafe(
+            self.disk_worker.submit_task(
+                "put",
+                self.async_save_bytes_to_disk,
+                key=key,
+                memory_obj=memory_obj,
+                on_complete_callback=on_complete_callback,
+            ),
+            self.loop,
+        )
+
+    # TODO(Jiayi): enable real batching
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        Submit batched put tasks to store KV caches to disk asynchronously.
+
+        :param keys: The cache keys for the KV chunks.
+        :param memory_objs: The memory objects containing the KV data.
+        :param transfer_spec: Optional transfer specification (unused).
+        :param on_complete_callback: Optional callback invoked once per key
+            after that key's disk write completes (not once per batch).
+            Callback exceptions are caught and logged.
+        """
+        for key, memory_obj in zip(keys, memory_objs, strict=False):
+            self.submit_put_task(
+                key, memory_obj, on_complete_callback=on_complete_callback
+            )
+
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        """
+        Load a cached KV chunk from disk synchronously.
+
+        The cache policy is updated only after a successful load so that a
+        failed load (``load_bytes_from_disk`` returning ``None``) does not
+        record a phantom cache hit and skew future eviction decisions.
+
+        :param key: The cache key identifying the KV chunk.
+        :returns: A ``MemoryObj`` containing the loaded KV data, or ``None``
+            if the key is not present or the load fails.
+        """
+        with self.disk_lock:
+            if key not in self.dict:
+                return None
+
+            disk_meta = self.dict[key]
+            path = disk_meta.path
+            dtype = disk_meta.dtype
+            shape = disk_meta.shape
+            fmt = disk_meta.fmt
+            assert dtype is not None
+            assert shape is not None
+
+        # Load is performed outside the lock: it can block for a non-trivial
+        # amount of time (CPU staging pool allocation + memcpy from disk) and
+        # must not hold disk_lock while waiting, or concurrent insert/evict
+        # operations would deadlock.
+        memory_obj = self.load_bytes_from_disk(
+            key, path, dtype=dtype, shape=shape, fmt=fmt
+        )
+
+        if memory_obj is not None:
+            # Re-acquire the lock to update the eviction policy.  The key
+            # membership check guards against the entry being evicted between
+            # the two lock regions — in that case the policy state is already
+            # consistent and no update is needed.
+            with self.disk_lock:
+                if key in self.dict:
+                    self.cache_policy.update_on_hit(key, self.dict)
+
+        return memory_obj
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """Load multiple KV chunks from disk with concurrent I/O.
+
+        Metadata lookup and memory allocation are performed sequentially
+        under the disk lock, then all file reads are dispatched to a
+        ``ThreadPoolExecutor`` so they run in parallel.  The GIL is
+        released during the underlying ``readinto`` syscall, so threads
+        achieve true I/O parallelism.
+
+        :param keys: Cache keys identifying the KV chunks to load.
+        :returns: A list of ``MemoryObj`` (or ``None`` for missing keys),
+            in the same order as *keys*.
+        """
+        if len(keys) <= 1:
+            return [self.get_blocking(k) for k in keys]
+
+        # --- 1. Batch metadata lookup (single lock acquisition) -----------
+        with self.disk_lock:
+            metas = [self.dict.get(key) for key in keys]
+
+        # --- 2. Pre-allocate staging buffers (sequential) -----------------
+        memory_objs = [
+            self.local_cpu_backend.allocate(m.shape, m.dtype, m.fmt)
+            if m is not None
+            else None
+            for m in metas
+        ]
+
+        # --- 3. Concurrent file reads via thread pool ---------------------
+        paths = [m.path if m is not None else None for m in metas]
+        results: List[Optional[MemoryObj]] = list(
+            self._read_thread_pool.map(
+                self._load_chunk_into_memory, keys, paths, memory_objs
+            )
+        )
+
+        # --- 4. Update cache policy for successful loads ------------------
+        with self.disk_lock:
+            for key, mem_obj in zip(keys, results, strict=True):
+                if mem_obj is not None and key in self.dict:
+                    self.cache_policy.update_on_hit(key, self.dict)
+
+        return results
+
+    def _load_chunk_into_memory(
+        self,
+        key: CacheEngineKey,
+        path: Optional[str],
+        memory_obj: Optional[MemoryObj],
+    ) -> Optional[MemoryObj]:
+        """Read a single chunk from disk into a pre-allocated ``MemoryObj``.
+
+        Designed to be called from a thread pool — each invocation is
+        independent and performs a single blocking ``readinto`` syscall.
+
+        :param key: Cache key (used for metadata recovery and error logging).
+        :param path: File path to read from, or ``None`` if the key was not
+            found during the metadata lookup phase.
+        :param memory_obj: Pre-allocated staging buffer, or ``None`` if
+            allocation failed.
+        :returns: The populated ``MemoryObj``, or ``None`` on any failure.
+        """
+        if path is None or memory_obj is None:
+            return None
+
+        try:
+            buffer = memory_obj.byte_array
+            self.read_file(key, buffer, path)
+
+            # Recover metadata (mirrors load_bytes_from_disk).
+            with self.disk_lock:
+                disk_meta = self.dict.get(key)
+                if disk_meta is None:
+                    memory_obj.ref_count_down()
+                    return None
+                memory_obj.metadata.cached_positions = disk_meta.cached_positions
+
+            return memory_obj
+        except Exception as e:
+            logger.error("Failed to load chunk from disk for key %s: %s", key, e)
+            memory_obj.ref_count_down()
+            return None
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        mem_objs: list[MemoryObj] = []
+        paths: list[str] = []
+
+        logger.debug(f"lookup_id: {lookup_id}; Prefetching {len(keys)} keys from disk.")
+        for key in keys:
+            self.disk_lock.acquire()
+            assert key in self.dict, f"Key {key} not found in disk cache after pinning"
+
+            path = self.dict[key].path
+            dtype = self.dict[key].dtype
+            shape = self.dict[key].shape
+            fmt = self.dict[key].fmt
+
+            assert dtype is not None
+            assert shape is not None
+
+            # busy_loop=False prevents spinning on the event loop thread;
+            # if staging memory is exhausted the caller will get a logged
+            # error rather than a silent deadlock.
+            memory_obj = self.local_cpu_backend.allocate(
+                shape,
+                dtype,
+                fmt,
+                busy_loop=False,
+            )
+
+            if memory_obj is None:
+                logger.error(
+                    "Memory allocation failed during async disk load for key %s. "
+                    "CPU staging pool may be exhausted (unpin() not called after "
+                    "a previous retrieve). Returning partial results.",
+                    key,
+                )
+                return mem_objs
+
+            self.dict[key].pin()
+
+            # NOTE(Jiayi): Currently, we consider prefetch as cache hit.
+            # Update cache recency
+            self.cache_policy.update_on_hit(key, self.dict)
+
+            self.disk_lock.release()
+            logger.debug(f"Prefetching {key} from disk.")
+            memory_obj.pin()
+            mem_objs.append(memory_obj)
+            paths.append(path)
+
+        return await self.disk_worker.submit_task(
+            "prefetch",
+            self.batched_async_load_bytes_from_disk,
+            paths=paths,
+            keys=keys,
+            memory_objs=mem_objs,
+        )
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        num_hit_counts = 0
+        with self.disk_lock:
+            for key in keys:
+                if key not in self.dict:
+                    return num_hit_counts
+                if pin:
+                    self.dict[key].pin()
+                    self.keys_in_request.append(key)
+                num_hit_counts += 1
+        return num_hit_counts
+
+    @_lmcache_nvtx_annotate
+    @torch.inference_mode()
+    def async_save_bytes_to_disk(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        Convert KV to bytes and async store bytes to disk.
+
+        :param on_complete_callback: Optional callback invoked after the disk
+            write completes for this key. Callback exceptions are caught and
+            logged.
+        """
+        kv_chunk = memory_obj.tensor
+        assert kv_chunk is not None
+        buffer = memory_obj.byte_array
+        path = self._key_to_path(key)
+
+        size = len(buffer)
+        self.usage += size
+        self.stats_monitor.update_local_storage_usage(self.usage)
+
+        # TODO(Jiayi): need to add ref count in disk memory object
+        self.write_file(buffer, path)
+
+        # ref count down here because there's a ref_count_up in
+        # `submit_put_task` above.
+        # Ref count down better be before `insert_key` for testing
+        # purposes (e.g., testing mem_leak).
+        # TODO(Jiayi): This could be problematic if the
+        # freed memory object is immediately reused.
+        size = memory_obj.get_physical_size()
+        shape = memory_obj.metadata.shape
+        dtype = memory_obj.metadata.dtype
+        fmt = memory_obj.metadata.fmt
+        cached_positions = memory_obj.metadata.cached_positions
+        memory_obj.ref_count_down()
+
+        self.insert_key(key, size, shape, dtype, fmt, cached_positions=cached_positions)
+
+        self.disk_worker.remove_put_task(key)
+
+        # Call the completion callback if provided
+        if on_complete_callback is not None:
+            try:
+                on_complete_callback(key)
+            except Exception as e:
+                logger.warning(f"on_complete_callback failed for key {key}: {e}")
+
+    @_lmcache_nvtx_annotate
+    def batched_async_load_bytes_from_disk(
+        self,
+        paths: list[str],
+        keys: list[CacheEngineKey],
+        memory_objs: list[MemoryObj],
+        write_back: bool = False,
+    ) -> list[MemoryObj]:
+        """
+        Async load bytearray from disk.
+        """
+
+        logger.debug("Executing `async_load_bytes` from disk.")
+        # TODO (Jiayi): handle the case where loading fails.
+        for path, key, mem_obj in zip(paths, keys, memory_objs, strict=False):
+            buffer = mem_obj.byte_array
+            self.read_file(key, buffer, path)
+
+            # TODO(Jiayi): Please recover the metadata in a more
+            # elegant way in the future.
+            cached_positions = self.dict[key].cached_positions
+            mem_obj.metadata.cached_positions = cached_positions
+
+            with self.disk_lock:
+                self.dict[key].unpin()
+
+        return memory_objs
+
+    def load_bytes_from_disk(
+        self,
+        key: CacheEngineKey,
+        path: str,
+        dtype: torch.dtype,
+        shape: torch.Size,
+        fmt: MemoryFormat,
+    ) -> Optional[MemoryObj]:
+        """
+        Load bytearray from disk.
+        """
+
+        memory_obj = self.local_cpu_backend.allocate(shape, dtype, fmt)
+        assert memory_obj is not None, "Memory allocation failed during disk load."
+
+        buffer = memory_obj.byte_array
+        self.read_file(key, buffer, path)
+
+        # TODO(Jiayi): Please recover the metadata in a more
+        # elegant way in the future.
+        cached_positions = self.dict[key].cached_positions
+        memory_obj.metadata.cached_positions = cached_positions
+
+        return memory_obj
+
+    def write_file(self, buffer, path):
+        start_time = time.time()
+        size = len(buffer)
+        if size % self.os_disk_bs != 0 or not self.use_odirect:
+            with open(path, "wb") as f:
+                f.write(buffer)
+        else:
+            fd = os.open(path, os.O_CREAT | os.O_WRONLY | os.O_DIRECT, 0o644)
+            os.write(fd, buffer)
+            os.close(fd)
+        disk_write_time = time.time() - start_time
+        logger.debug(
+            f"Disk write size: {size} bytes, "
+            f"Bandwidth: {size / disk_write_time / 1e6:.2f} MB/s"
+        )
+
+    @_lmcache_nvtx_annotate
+    def read_file(self, key, buffer, path):
+        start_time = time.time()
+        size = len(buffer)
+        fblock_aligned = size % self.os_disk_bs == 0
+        if not fblock_aligned and self.use_odirect:
+            logger.warning(
+                "Cannot use O_DIRECT for this file, "
+                "size is not aligned to disk block size."
+            )
+
+        try:
+            if not fblock_aligned or not self.use_odirect:
+                with open(path, "rb") as f:
+                    f.readinto(buffer)
+            else:
+                fd = os.open(path, os.O_RDONLY | os.O_DIRECT)
+                with os.fdopen(fd, "rb", buffering=0) as fdo:
+                    fdo.readinto(buffer)
+        except FileNotFoundError:
+            logger.warning(f"File not found on disk: {path}")
+            if self.dict.get(key, None):
+                self.dict.pop(key)
+            return
+
+        disk_read_time = time.time() - start_time
+        logger.debug(
+            f"Disk read size: {size} bytes, "
+            f"Bandwidth: {size / disk_read_time / 1e6:.2f} MB/s"
+        )
+
+    def get_allocator_backend(self) -> LocalCPUBackend:
+        return self.local_cpu_backend
+
+    def close(self) -> None:
+        if self.batched_msg_sender is not None:
+            self.batched_msg_sender.close()
+        self._read_thread_pool.shutdown(wait=True)
+        self.disk_worker.close()
diff --git a/lmcache/v1/storage_backend/maru_backend.py b/lmcache/v1/storage_backend/maru_backend.py
new file mode 100644
index 0000000..f9134aa
--- /dev/null
+++ b/lmcache/v1/storage_backend/maru_backend.py
@@ -0,0 +1,735 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from concurrent.futures import Future
+from typing import Any, Callable, List, Optional, Sequence, Union
+import asyncio
+import threading
+import time
+
+# Third Party
+from maru import MaruConfig, MaruHandler
+from maru_lmcache import CxlMemoryAdapter
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import (
+    MemoryAllocatorInterface,
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+
+logger = init_logger(__name__)
+
+
+class MaruBackend(AllocatorBackendInterface):
+    """Maru CXL shared memory storage backend.
+
+    Implements AllocatorBackendInterface with its own CxlMemoryAdapter.
+    No LocalCPUBackend needed — data lives directly in CXL mmap memory.
+
+    Put is async (Future): metadata registration via RPC.
+    Get is sync: CXL memory direct read (no network I/O).
+
+    Args:
+        config: LMCache engine configuration. Must have maru_path set.
+        metadata: LMCache engine metadata.
+        loop: asyncio event loop for async put tasks.
+        dst_device: Target device string (unused for CXL, kept for interface).
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        dst_device: str = torch_device_type,
+    ):
+        super().__init__(dst_device=dst_device)
+
+        if config.use_layerwise:
+            raise NotImplementedError(
+                "MaruBackend does not yet support layerwise KV cache."
+            )
+
+        # 1. Config
+        self.config = config
+        self.loop = loop
+
+        self._full_chunk_size_bytes: int = get_size_bytes(
+            metadata.get_shapes(), metadata.get_dtypes()
+        )
+        assert self._full_chunk_size_bytes % metadata.chunk_size == 0
+        self._single_token_size: int = (
+            self._full_chunk_size_bytes // metadata.chunk_size
+        )
+
+        self._mla_worker_id_as0_mode: bool = (
+            config.get_extra_config_value(
+                "remote_enable_mla_worker_id_as0", metadata.use_mla
+            )
+            and metadata.use_mla
+            and metadata.world_size > 1
+            and metadata.worker_id != 0
+        )
+
+        # 2. Handler
+        self._handler = self._create_handler(config)
+
+        # 3. Allocator
+        self.memory_allocator = self.initialize_allocator(config, metadata)
+
+        # 4. State
+        self.put_lock = threading.Lock()
+        self.put_tasks: set[CacheEngineKey] = set()
+
+    def __str__(self) -> str:
+        return self.__class__.__name__
+
+    @staticmethod
+    def _pool_size_gb_to_bytes(size_gb: float) -> int:
+        """Convert pool size in GB to bytes."""
+        return int(size_gb * 1024**3)
+
+    # =========================================================================
+    # Initialization helpers
+    # =========================================================================
+
+    def _create_handler(
+        self,
+        config: LMCacheEngineConfig,
+    ) -> "MaruHandler":
+        """Create and connect a MaruHandler.
+
+        Args:
+            config: LMCache engine configuration.
+
+        Returns:
+            Connected MaruHandler instance.
+
+        Raises:
+            RuntimeError: If MaruHandler connection fails.
+        """
+        assert config.maru_path is not None, "maru_path must be set for MaruBackend"
+
+        # Convert maru:// scheme to tcp:// for ZMQ
+        server_url = config.maru_path
+        if server_url.startswith("maru://"):
+            server_url = "tcp://" + server_url[len("maru://") :]
+
+        extra = config.extra_config or {}
+        maru_config = MaruConfig(
+            server_url=server_url,
+            instance_id=extra.get("maru_instance_id"),
+            pool_size=self._pool_size_gb_to_bytes(config.maru_pool_size),
+            chunk_size_bytes=self._full_chunk_size_bytes,
+            auto_connect=False,
+            timeout_ms=extra.get("maru_timeout_ms", 5000),
+            use_async_rpc=extra.get("maru_use_async_rpc", True),
+            max_inflight=extra.get("maru_max_inflight", 64),
+            eager_map=extra.get("maru_eager_map", True),
+        )
+
+        handler = MaruHandler(maru_config)
+        if not handler.connect():
+            raise RuntimeError(f"Failed to connect MaruHandler to {config.maru_path}")
+        logger.debug("[Maru] Connected to %s", config.maru_path)
+        return handler
+
+    # =========================================================================
+    # AllocatorBackendInterface
+    # =========================================================================
+
+    def initialize_allocator(
+        self, config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ) -> MemoryAllocatorInterface:
+        """Create CxlMemoryAdapter backed by the connected handler.
+
+        Args:
+            config: LMCache engine configuration.
+            metadata: LMCache engine metadata.
+
+        Returns:
+            CxlMemoryAdapter instance.
+        """
+        shapes = metadata.get_shapes()
+        dtypes = metadata.get_dtypes()
+        fmt = MemoryFormat.KV_MLA_FMT if metadata.use_mla else MemoryFormat.KV_2LTD
+        chunk_size = self._handler.get_chunk_size()
+
+        return CxlMemoryAdapter(
+            handler=self._handler,
+            shapes=shapes,
+            dtypes=dtypes,
+            fmt=fmt,
+            chunk_size=chunk_size,
+        )
+
+    def get_memory_allocator(self) -> MemoryAllocatorInterface:
+        """Returns the underlying CxlMemoryAdapter."""
+        return self.memory_allocator
+
+    def get_allocator_backend(self) -> "MaruBackend":
+        """Returns self as the allocator backend."""
+        return self
+
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        """Allocate CXL-backed memory via CxlMemoryAdapter.
+
+        Args:
+            shapes: Tensor shape(s).
+            dtypes: Tensor dtype(s).
+            fmt: Memory format.
+            eviction: Unused.
+            busy_loop: Unused.
+
+        Returns:
+            MemoryObj backed by CXL memory, or None on failure.
+        """
+        obj = self.memory_allocator.allocate(shapes, dtypes, fmt)
+        if obj is not None:
+            logger.debug(
+                "[Maru] allocate rid=%d pid=%d",
+                *CxlMemoryAdapter.decode_address(obj.metadata.address),
+            )
+        else:
+            logger.debug("[Maru] allocate failed shapes=%s dtypes=%s", shapes, dtypes)
+        return obj
+
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[list[MemoryObj]]:
+        """Allocate multiple CXL-backed MemoryObjs.
+
+        Args:
+            shapes: Tensor shape(s) (same for each allocation).
+            dtypes: Tensor dtype(s) (same for each allocation).
+            batch_size: Number of allocations.
+            fmt: Memory format.
+            eviction: Unused.
+            busy_loop: Unused.
+
+        Returns:
+            List of MemoryObj, or None if any allocation fails.
+        """
+        return self.memory_allocator.batched_allocate(shapes, dtypes, batch_size, fmt)
+
+    # =========================================================================
+    # Put (async)
+    # =========================================================================
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """Check whether key is in ongoing put tasks.
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            True if the key has a pending put task.
+        """
+        with self.put_lock:
+            return key in self.put_tasks
+
+    @staticmethod
+    def _create_immediate_empty_future() -> Future:
+        """Create a Future that is already resolved with None."""
+        f: Future = Future()
+        f.set_result(None)
+        return f
+
+    def submit_put_task(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Future:
+        """Submit a put task to register KV metadata with MaruServer.
+
+        Data is already in CXL memory (zero-copy). This only registers
+        the key -> location metadata via RPC.
+
+        Args:
+            key: The cache key.
+            memory_obj: MemoryObj with data already written to CXL.
+            on_complete_callback: Optional callback after registration.
+
+        Returns:
+            Future that completes when metadata is registered.
+        """
+        # If MLA worker id as 0 mode is enabled, skip put tasks
+        if self._mla_worker_id_as0_mode:
+            return self._create_immediate_empty_future()
+
+        assert memory_obj.tensor is not None
+
+        # Keep CXL page alive: ref_count_down is only called on failure.
+        # On success the ref is retained so the CXL memory is not reclaimed.
+        memory_obj.ref_count_up()
+
+        with self.put_lock:
+            self.put_tasks.add(key)
+
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_store(key, memory_obj, on_complete_callback),
+            self.loop,
+        )
+        return future
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Union[List[Future], None]:
+        """Submit batched put tasks via single batch_store RPC.
+
+        Args:
+            keys: The cache keys.
+            memory_objs: MemoryObjs with data already in CXL.
+            transfer_spec: Unused.
+            on_complete_callback: Optional per-key callback.
+
+        Returns:
+            List containing a single Future for the entire batch.
+        """
+        # If MLA worker id as 0 mode is enabled, skip put tasks
+        if self._mla_worker_id_as0_mode:
+            return None
+
+        for memory_obj in memory_objs:
+            assert memory_obj.tensor is not None
+            memory_obj.ref_count_up()
+
+        with self.put_lock:
+            self.put_tasks.update(keys)
+
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_batch_store(list(keys), memory_objs, on_complete_callback),
+            self.loop,
+        )
+        return [future]
+
+    async def _async_store(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """Register KV metadata with MaruServer (runs in event loop).
+
+        Uses CxlMemoryAdapter.create_store_handle() to extract
+        (region_id, page_index) from the MemoryObj's encoded address.
+
+        Args:
+            key: The cache key.
+            memory_obj: MemoryObj backed by CXL memory.
+            on_complete_callback: Optional callback after registration.
+        """
+        success = False
+        try:
+            allocator = self.memory_allocator
+            assert isinstance(allocator, CxlMemoryAdapter)
+            handle = allocator.create_store_handle(memory_obj)
+            key_str = key.to_string()
+
+            success = await asyncio.to_thread(self._handler.store, key_str, handle)
+
+            logger.debug(
+                "[Maru] store key=%s rid=%d pid=%d",
+                key,
+                handle.region_id,
+                handle.page_index,
+            )
+
+        except Exception as e:
+            logger.error("[Maru] store failed key=%s: %s", key, e)
+            raise
+        finally:
+            with self.put_lock:
+                self.put_tasks.discard(key)
+
+            if not success:
+                memory_obj.ref_count_down()
+
+            if success and on_complete_callback is not None:
+                try:
+                    on_complete_callback(key)
+                except Exception as e:
+                    logger.warning("on_complete_callback failed for key %s: %s", key, e)
+
+    async def _async_batch_store(
+        self,
+        keys: List[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """Register multiple KV metadata entries via single batch_store RPC."""
+        results: Optional[list[bool]] = None
+        try:
+            allocator = self.memory_allocator
+            assert isinstance(allocator, CxlMemoryAdapter)
+
+            key_strs = [k.to_string() for k in keys]
+            handles = [allocator.create_store_handle(m) for m in memory_objs]
+
+            results = await asyncio.to_thread(
+                self._handler.batch_store, key_strs, handles
+            )
+            if results is not None:
+                logger.debug("[Maru] batch_store %d/%d ok", sum(results), len(results))
+        except Exception as e:
+            logger.error("[Maru] batch_store failed: %s", e)
+            raise
+        finally:
+            with self.put_lock:
+                self.put_tasks.difference_update(keys)
+
+            # Release ref_count for failed stores
+            for i, memory_obj in enumerate(memory_objs):
+                succeeded = results is not None and i < len(results) and results[i]
+                if not succeeded:
+                    memory_obj.ref_count_down()
+
+            if on_complete_callback is not None:
+                for i, key in enumerate(keys):
+                    if results is not None and i < len(results) and results[i]:
+                        try:
+                            on_complete_callback(key)
+                        except Exception as e:
+                            logger.warning(
+                                "on_complete_callback failed for key %s: %s",
+                                key,
+                                e,
+                            )
+
+    # =========================================================================
+    # Get (sync)
+    # =========================================================================
+
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        """Blocking get: read KV cache directly from CXL memory.
+
+        Queries MaruServer for metadata, then returns a MemoryObj
+        via CxlMemoryAdapter.get_by_location().
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            MemoryObj backed by CXL memory, or None if not found.
+        """
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+
+        key_str = key.to_string()
+        mem_info = self._handler.retrieve(key_str)
+        if mem_info is None:
+            logger.debug("[Maru] get_blocking miss key=%s", key)
+            return None
+
+        allocator = self.memory_allocator
+        assert isinstance(allocator, CxlMemoryAdapter)
+
+        memory_obj = allocator.get_by_location(
+            region_id=mem_info.region_id,
+            page_index=mem_info.page_index,
+            actual_size=len(mem_info.view),
+            single_token_size=self._single_token_size,
+        )
+        if memory_obj is None:
+            logger.debug(
+                "[Maru] get_blocking pool miss rid=%d pid=%d",
+                mem_info.region_id,
+                mem_info.page_index,
+            )
+            return None
+
+        memory_obj.ref_count_up()
+
+        logger.debug(
+            "[Maru] get_blocking rid=%d pid=%d size=%d",
+            mem_info.region_id,
+            mem_info.page_index,
+            len(mem_info.view),
+        )
+        return memory_obj
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """Blocking batched get via single batch_retrieve RPC.
+
+        Args:
+            keys: The cache keys.
+
+        Returns:
+            List of MemoryObj (None for misses).
+        """
+        if self._mla_worker_id_as0_mode:
+            keys = [k.with_new_worker_id(0) for k in keys]
+
+        key_strs = [k.to_string() for k in keys]
+        mem_infos = self._handler.batch_retrieve(key_strs)
+
+        allocator = self.memory_allocator
+        assert isinstance(allocator, CxlMemoryAdapter)
+
+        results: List[Optional[MemoryObj]] = []
+        for mem_info in mem_infos:
+            if mem_info is None:
+                results.append(None)
+                continue
+            memory_obj = allocator.get_by_location(
+                region_id=mem_info.region_id,
+                page_index=mem_info.page_index,
+                actual_size=len(mem_info.view),
+                single_token_size=self._single_token_size,
+            )
+            if memory_obj is None:
+                results.append(None)
+                continue
+            memory_obj.ref_count_up()
+            results.append(memory_obj)
+
+        hits = sum(1 for r in results if r is not None)
+        logger.debug("[Maru] batch_retrieve %d/%d hits", hits, len(results))
+        return results
+
+    # =========================================================================
+    # Async lookup API (used by StorageManager.async_lookup_and_prefetch)
+    # =========================================================================
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Check how many prefix keys exist via single batch_exists RPC.
+
+        Returns the count of contiguous keys starting from index 0
+        that exist. Stops at first miss.
+
+        Args:
+            lookup_id: Unique request identifier.
+            keys: Keys to check in prefix order.
+            pin: If True, atomically check and pin via batch_pin RPC.
+
+        Returns:
+            Number of prefix-contiguous keys that exist.
+        """
+        return await asyncio.to_thread(self.batched_contains, keys, pin)
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        """Non-blocking batched get via single batch_retrieve RPC.
+
+        Uses handler.batch_retrieve() for a single RPC call, then
+        resolves each MemoryInfo to a MemoryObj via CxlMemoryAdapter.
+        Stops at first miss and returns the prefix.
+
+        Args:
+            lookup_id: Unique request identifier.
+            keys: Keys to retrieve (already confirmed by contains).
+            transfer_spec: Unused.
+
+        Returns:
+            List of MemoryObjs backed by CXL memory.
+        """
+
+        def _batch_get() -> list[MemoryObj]:
+            if self._mla_worker_id_as0_mode:
+                actual_keys = [k.with_new_worker_id(0) for k in keys]
+            else:
+                actual_keys = list(keys)
+
+            key_strs = [k.to_string() for k in actual_keys]
+            mem_infos = self._handler.batch_retrieve(key_strs)
+
+            allocator = self.memory_allocator
+            assert isinstance(allocator, CxlMemoryAdapter)
+
+            results: list[MemoryObj] = []
+            for mem_info in mem_infos:
+                if mem_info is None:
+                    break
+                memory_obj = allocator.get_by_location(
+                    region_id=mem_info.region_id,
+                    page_index=mem_info.page_index,
+                    actual_size=len(mem_info.view),
+                    single_token_size=self._single_token_size,
+                )
+                if memory_obj is None:
+                    break
+                memory_obj.ref_count_up()
+                memory_obj.pin()
+                results.append(memory_obj)
+
+            logger.debug(
+                "[Maru] batch_get_non_blocking %d/%d hits", len(results), len(keys)
+            )
+            return results
+
+        return await asyncio.to_thread(_batch_get)
+
+    # =========================================================================
+    # Contains / Pin / Unpin / Remove
+    # =========================================================================
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """Check if key exists on MaruServer.
+
+        Args:
+            key: The cache key.
+            pin: If True, atomically check existence and pin the entry
+                 to protect it from eviction.
+
+        Returns:
+            True if key exists.
+        """
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+
+        key_str = key.to_string()
+        if pin:
+            return self._handler.pin(key_str)
+        return self._handler.exists(key_str)
+
+    def batched_contains(
+        self,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Check how many prefix keys exist via single batch_exists RPC.
+
+        Args:
+            keys: Keys to check in prefix order.
+            pin: If True, atomically check and pin via
+                 batch_pin RPC.
+
+        Returns:
+            Number of prefix-contiguous keys that exist.
+        """
+        if self._mla_worker_id_as0_mode:
+            keys = [k.with_new_worker_id(0) for k in keys]
+
+        key_strs = [k.to_string() for k in keys]
+        if pin:
+            results = self._handler.batch_pin(key_strs)
+        else:
+            results = self._handler.batch_exists(key_strs)
+        num_hit = 0
+        for exists in results:
+            if not exists:
+                break
+            num_hit += 1
+        return num_hit
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        """Pin a key to prevent eviction on MaruServer.
+
+        Increments the server-side pin_count.
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            True if pinned successfully.
+        """
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+        return self._handler.pin(key.to_string())
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        """Unpin a key to allow eviction on MaruServer.
+
+        Decrements the server-side pin_count. When pin_count reaches 0,
+        the entry becomes eligible for eviction.
+
+        Args:
+            key: The cache key.
+
+        Returns:
+            True if unpinned successfully.
+        """
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+        return self._handler.unpin(key.to_string())
+
+    def batched_unpin(self, keys: List[CacheEngineKey]) -> None:
+        """Batch-unpin keys via single RPC.
+
+        Decrements server-side pin_count for each key. When pin_count
+        reaches 0, the entry becomes eligible for eviction.
+
+        Args:
+            keys: The cache keys to unpin.
+        """
+        if not keys:
+            return
+        if self._mla_worker_id_as0_mode:
+            keys = [k.with_new_worker_id(0) for k in keys]
+        key_strs = [k.to_string() for k in keys]
+        self._handler.batch_unpin(key_strs)
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        """Remove a key from MaruServer.
+
+        Args:
+            key: The cache key.
+            force: Whether to force removal.
+
+        Returns:
+            True if removed successfully.
+        """
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+        key_str = key.to_string()
+        result = self._handler.delete(key_str)
+        logger.debug("[Maru] remove key=%s success=%s", key, result)
+        return result
+
+    # =========================================================================
+    # Lifecycle
+    # =========================================================================
+
+    def close(self) -> None:
+        """Close the backend and underlying MaruHandler."""
+        while True:
+            with self.put_lock:
+                if not self.put_tasks:
+                    break
+            time.sleep(0.1)
+
+        self.memory_allocator.close()
+        self._handler.close()
+        logger.info("MaruBackend closed.")
diff --git a/lmcache/v1/storage_backend/naive_serde/__init__.py b/lmcache/v1/storage_backend/naive_serde/__init__.py
new file mode 100644
index 0000000..ede2a35
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/__init__.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Tuple
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.naive_serde.cachegen_decoder import CacheGenDeserializer
+from lmcache.v1.storage_backend.naive_serde.cachegen_encoder import CacheGenSerializer
+from lmcache.v1.storage_backend.naive_serde.kivi_serde import (
+    KIVIDeserializer,
+    KIVISerializer,
+)
+from lmcache.v1.storage_backend.naive_serde.naive_serde import (
+    NaiveDeserializer,
+    NaiveSerializer,
+)
+from lmcache.v1.storage_backend.naive_serde.serde import Deserializer, Serializer
+
+
+def CreateSerde(
+    serde_type: str,
+    metadata: LMCacheMetadata,
+    config: LMCacheEngineConfig,
+) -> Tuple[Serializer, Deserializer]:
+    s: Optional[Serializer] = None
+    d: Optional[Deserializer] = None
+
+    if serde_type == "naive":
+        s, d = NaiveSerializer(), NaiveDeserializer()
+    elif serde_type == "kivi":
+        s, d = KIVISerializer(), KIVIDeserializer()
+    elif serde_type == "cachegen":
+        s, d = (
+            CacheGenSerializer(config, metadata),
+            CacheGenDeserializer(config, metadata),
+        )
+    else:
+        raise ValueError(f"Invalid type: {serde_type}")
+
+    return s, d
+
+
+__all__ = [
+    "Serializer",
+    "Deserializer",
+    "KIVISerializer",
+    "KIVIDeserializer",
+    "CreateSerde",
+]
diff --git a/lmcache/v1/storage_backend/naive_serde/cachegen_basics.py b/lmcache/v1/storage_backend/naive_serde/cachegen_basics.py
new file mode 100644
index 0000000..9cb3511
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/cachegen_basics.py
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import List
+
+# Third Party
+from transformers import AutoConfig
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.storage_backend.serde.cachegen_basics import QuantizationSpec
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class CacheGenConfig:
+    # TODO: move this class to another file like "cachegen_basics.py"
+    nlayers: int
+    kspecs: List[QuantizationSpec]
+    vspecs: List[QuantizationSpec]
+
+    def __getitem__(self, key: str) -> int:
+        return getattr(self, key)
+
+    @staticmethod
+    def from_model_name(model_name: str) -> "CacheGenConfig":
+        family_7b = [
+            "mistralai/Mistral-7B-Instruct-v0.2",
+            "lmsys/longchat-7b-16k",
+            "Qwen/Qwen-7B",
+        ]
+        family_8b = ["meta-llama/Llama-3.1-8B-Instruct"]
+        family_9b = ["THUDM/glm-4-9b-chat"]
+        if model_name in family_7b:
+            return CacheGenConfig(
+                nlayers=32,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=32, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=32, bins=16),
+                ],
+            )
+        elif model_name in family_8b:
+            return CacheGenConfig(
+                nlayers=32,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=32, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=32, bins=16),
+                ],
+            )
+        # TODO(Jiayi): needs tuning for better quality
+        elif model_name in family_9b:
+            return CacheGenConfig(
+                nlayers=40,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=40, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=40, bins=16),
+                ],
+            )
+        elif model_name == "test_model":
+            return CacheGenConfig(
+                nlayers=32,
+                kspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                    QuantizationSpec(start_layer=10, end_layer=32, bins=16),
+                ],
+                vspecs=[
+                    QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                    QuantizationSpec(start_layer=2, end_layer=32, bins=16),
+                ],
+            )
+        else:
+            try:
+                config = AutoConfig.from_pretrained(model_name)
+                # Default name caught by num_hidden_layers
+                if config.num_hidden_layers is None:
+                    raise ValueError(
+                        f"num_hidden_layers is None for model {model_name}"
+                    )
+                if config.num_hidden_layers < 10:
+                    return CacheGenConfig(
+                        nlayers=config.num_hidden_layers,
+                        kspecs=[
+                            QuantizationSpec(
+                                start_layer=0,
+                                end_layer=config.num_hidden_layers,
+                                bins=32,
+                            ),
+                        ],
+                        vspecs=[
+                            QuantizationSpec(
+                                start_layer=0,
+                                end_layer=config.num_hidden_layers,
+                                bins=32,
+                            ),
+                        ],
+                    )
+                else:
+                    return CacheGenConfig(
+                        nlayers=config.num_hidden_layers,
+                        kspecs=[
+                            QuantizationSpec(start_layer=0, end_layer=10, bins=32),
+                            QuantizationSpec(
+                                start_layer=10,
+                                end_layer=config.num_hidden_layers,
+                                bins=16,
+                            ),
+                        ],
+                        vspecs=[
+                            QuantizationSpec(start_layer=0, end_layer=2, bins=32),
+                            QuantizationSpec(
+                                start_layer=2,
+                                end_layer=config.num_hidden_layers,
+                                bins=16,
+                            ),
+                        ],
+                    )
+            except Exception as e:
+                raise ValueError(
+                    f"Model {model_name} not supported by CacheGenConfig"
+                ) from e
diff --git a/lmcache/v1/storage_backend/naive_serde/cachegen_decoder.py b/lmcache/v1/storage_backend/naive_serde/cachegen_decoder.py
new file mode 100644
index 0000000..97eff31
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/cachegen_decoder.py
@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.logging import init_logger
+from lmcache.storage_backend.serde.cachegen_basics import (
+    CacheGenGPUEncoderOutput,
+)
+from lmcache.storage_backend.serde.cachegen_decoder import (
+    decode_function_gpu,
+    do_dequantize,
+)
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import (
+    BytesBufferMemoryObj,
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.naive_serde.cachegen_basics import CacheGenConfig
+from lmcache.v1.storage_backend.naive_serde.serde import Deserializer
+
+logger = init_logger(__name__)
+
+
+class CacheGenDeserializer(Deserializer):
+    def __init__(self, config: LMCacheEngineConfig, metadata: LMCacheMetadata):
+        self.dtype = metadata.kv_dtype
+        self.cachegen_config = CacheGenConfig.from_model_name(metadata.model_name)
+        self.chunk_size = config.chunk_size
+        self.output_buffer: Optional[torch.Tensor] = None
+        self.key_bins = self.make_key_bins(self.cachegen_config)
+        self.value_bins = self.make_value_bins(self.cachegen_config)
+
+    def make_key_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.kspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    def make_value_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.vspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    def get_output_buffer(self, nlayers: int, nchannels: int, ntokens: int):
+        if (
+            self.output_buffer is None
+            or self.output_buffer.shape[1] != 2 * nlayers * nchannels
+        ):
+            self.output_buffer = torch.zeros(
+                (self.chunk_size, 2 * nlayers * nchannels), dtype=torch.uint8
+            ).to(torch_device_type)
+        return self.output_buffer[:ntokens, :]
+
+    # TODO(Jiayi): A lot of memory copies can be avoided in this function.
+    @_lmcache_nvtx_annotate
+    def deserialize(self, buffer_memory_obj: BytesBufferMemoryObj) -> MemoryObj:
+        encoder_output = CacheGenGPUEncoderOutput.from_bytes(
+            buffer_memory_obj.byte_array
+        )
+
+        encoder_output.max_tensors_key = encoder_output.max_tensors_key.to(
+            torch_device_type
+        )
+        encoder_output.max_tensors_value = encoder_output.max_tensors_value.to(
+            torch_device_type
+        )
+
+        ntokens = encoder_output.max_tensors_key.shape[1]
+        layers_in_key = encoder_output.max_tensors_key.shape[0]
+        key, value = decode_function_gpu(
+            encoder_output.cdf,
+            encoder_output.data_chunks,
+            layers_in_key,
+            ntokens,
+            self.get_output_buffer(
+                encoder_output.cdf.shape[0] // 2,
+                encoder_output.cdf.shape[1],
+                ntokens,
+            ),
+        )
+
+        # Temporary fix for #83: change the device of key_bins and value_bins
+        # to the device of key and value
+        # This requires a long-term fix in the future. Currently,
+        # CacheGenGPUEncoderOutput has implicit device in itself.
+        # More specifically, if the encoder encodes the tensor on GPU0, the
+        # from_bytes will also return a tensor on GPU0
+        # We may want to dynamically configure the device based on config and
+        # metadata in the future
+        if self.key_bins.device != key.device:
+            self.key_bins = self.key_bins.to(key.device)
+
+        if self.value_bins.device != value.device:
+            self.value_bins = self.value_bins.to(torch_device_type)
+
+        key = do_dequantize(key, self.key_bins, encoder_output.max_tensors_key)
+        value = do_dequantize(value, self.value_bins, encoder_output.max_tensors_value)
+        """ merge key and value back and reshape """
+        nlayers, ntokens, nchannels = key.shape
+        blob = torch.stack([key, value])  # [2, nlayers, ntokens, nchannels]
+        blob = blob.reshape(
+            (
+                2,
+                nlayers,
+                ntokens,
+                encoder_output.num_heads,
+                encoder_output.head_size,
+            )
+        )
+
+        hidden_dim = blob.shape[-1] * blob.shape[-2]
+        kv_chunk = blob.reshape(*blob.shape[:-2], hidden_dim).to(
+            self.dtype
+        )  # [nlayers, 2, ntokens, num_heads, head_size]
+
+        memory_obj = TensorMemoryObj(
+            raw_data=kv_chunk,
+            metadata=MemoryObjMetadata(
+                shape=kv_chunk.shape,
+                dtype=kv_chunk.dtype,
+                address=-1,
+                phy_size=kv_chunk.numel() * kv_chunk.element_size(),
+                ref_count=-1,  # HACK: avoid mis-free
+                fmt=MemoryFormat.KV_2LTD,
+            ),
+            parent_allocator=None,
+        )
+
+        return memory_obj
diff --git a/lmcache/v1/storage_backend/naive_serde/cachegen_encoder.py b/lmcache/v1/storage_backend/naive_serde/cachegen_encoder.py
new file mode 100644
index 0000000..111de15
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/cachegen_encoder.py
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.storage_backend.serde.cachegen_encoder import encode_function
+from lmcache.utils import _lmcache_nvtx_annotate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import BytesBufferMemoryObj, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.naive_serde.cachegen_basics import CacheGenConfig
+from lmcache.v1.storage_backend.naive_serde.serde import Serializer
+
+logger = init_logger(__name__)
+
+
+class CacheGenSerializer(Serializer):
+    def __init__(self, config: LMCacheEngineConfig, metadata: LMCacheMetadata):
+        self.cachegen_config = CacheGenConfig.from_model_name(metadata.model_name)
+        self.chunk_size = config.chunk_size
+        self.key_bins = self.make_key_bins(self.cachegen_config)
+        self.value_bins = self.make_value_bins(self.cachegen_config)
+
+        self.kv_shape = metadata.kv_shape
+
+    def make_key_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.kspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    def make_value_bins(self, config: CacheGenConfig) -> torch.Tensor:
+        ret = torch.zeros(config.nlayers)
+        for spec in config.vspecs:
+            ret[spec.start_layer : spec.end_layer] = spec.bins
+        return ret.to(torch_device_type)
+
+    # TODO(Jiayi): A lot of memory copies can be avoided in this function.
+    @_lmcache_nvtx_annotate
+    def serialize(self, memory_obj: MemoryObj) -> BytesBufferMemoryObj:
+        """
+        Serialize a KV_2LTD MemoryObj to CACHEGEN_BINARY MemoryObj.
+
+        Input:
+            memory_obj: the memory object to be serialized.
+
+        Returns:
+            MemoryObj: the serialized binary memory object.
+        """
+
+        # TODO(Jiayi): please avoid this copy by directly performing
+        # serialization inside gpu connector.
+        assert memory_obj.tensor is not None
+        tensor = memory_obj.tensor.to(torch_device_type)
+
+        # Temporary fix for issue #83: encoder will have the default device 0
+        # on all the ray workers. Need to set it to the correct device.
+        # Also need to figure out why this happens.
+        if torch_dev.current_device() != tensor.device.index:
+            torch_dev.set_device(tensor.device)
+        if tensor.device != self.key_bins.device:
+            self.key_bins = self.key_bins.to(tensor.device)
+        if tensor.device != self.value_bins.device:
+            self.value_bins = self.value_bins.to(tensor.device)
+
+        # tensor is [2, num_layers, num_tokens, hidden_size]
+        tensor = tensor.view(*tensor.shape[:-1], self.kv_shape[-2], self.kv_shape[-1])
+        tensor = tensor.permute([1, 0, 2, 3, 4])
+
+        # TODO(Jiayi): remove hardcoded "2"
+        """ expecting a tensor of shape 
+        [num_layers, 2, num_tokens, num_heads, head_size] """
+        ntokens = tensor.shape[2]
+        output_dict = encode_function(
+            tensor,
+            self.cachegen_config,
+            self.key_bins,
+            self.value_bins,
+            ntokens,
+        )
+
+        return BytesBufferMemoryObj(output_dict.to_bytes())
diff --git a/lmcache/v1/storage_backend/naive_serde/kivi_serde.py b/lmcache/v1/storage_backend/naive_serde/kivi_serde.py
new file mode 100644
index 0000000..8c212c8
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/kivi_serde.py
@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.naive_serde.serde import Deserializer, Serializer
+
+
+class KIVISerializer(Serializer):
+    def __init__(self):
+        pass
+
+    def serialize(self, memory_obj: MemoryObj) -> MemoryObj:
+        # TODO(Yuhan)
+        return memory_obj
+
+
+class KIVIDeserializer(Deserializer):
+    def __init__(self):
+        pass
+
+    def deserialize(self, memory_obj: MemoryObj) -> MemoryObj:
+        # TODO(Yuhan)
+        return memory_obj
diff --git a/lmcache/v1/storage_backend/naive_serde/naive_serde.py b/lmcache/v1/storage_backend/naive_serde/naive_serde.py
new file mode 100644
index 0000000..16203e8
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/naive_serde.py
@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.naive_serde.serde import Deserializer, Serializer
+
+
+class NaiveSerializer(Serializer):
+    def __init__(self):
+        pass
+
+    def serialize(self, memory_obj: MemoryObj) -> MemoryObj:
+        memory_obj.ref_count_up()
+        return memory_obj
+
+
+class NaiveDeserializer(Deserializer):
+    def deserialize(self, memory_obj: MemoryObj) -> MemoryObj:
+        return memory_obj
diff --git a/lmcache/v1/storage_backend/naive_serde/serde.py b/lmcache/v1/storage_backend/naive_serde/serde.py
new file mode 100644
index 0000000..4005a09
--- /dev/null
+++ b/lmcache/v1/storage_backend/naive_serde/serde.py
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import abc
+
+# First Party
+from lmcache.v1.memory_management import MemoryObj
+
+
+class Serializer(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def serialize(self, memory_obj: MemoryObj) -> MemoryObj:
+        """
+        Serialize/compress the memory object.
+
+        Input:
+            memory_obj: the memory object to be serialized/compressed.
+
+        Returns:
+            MemoryObj: the serialized/compressed memory object.
+        """
+        raise NotImplementedError
+
+
+class Deserializer(metaclass=abc.ABCMeta):
+    @abc.abstractmethod
+    def deserialize(self, memory_obj: MemoryObj) -> MemoryObj:
+        """
+        Deserialize/decompress the memory object.
+
+        Input:
+            memory_obj: the memory object to be deserialized/decompressed.
+
+        Returns:
+            MemoryObj: the deserialized/decompressed memory object.
+            None: if the memory allocation fails.
+        """
+        raise NotImplementedError
diff --git a/lmcache/v1/storage_backend/native_clients/aerospike_client.py b/lmcache/v1/storage_backend/native_clients/aerospike_client.py
new file mode 100644
index 0000000..c254b84
--- /dev/null
+++ b/lmcache/v1/storage_backend/native_clients/aerospike_client.py
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+import asyncio
+
+# Local
+from .connector_client_base import ConnectorClientBase
+
+try:
+    # First Party
+    from lmcache.lmcache_aerospike import LMCacheAerospikeClient
+
+    AEROSPIKE_AVAILABLE = True
+except ImportError:
+    AEROSPIKE_AVAILABLE = False
+    LMCacheAerospikeClient = None  # type: ignore
+
+
+class AerospikeClient(ConnectorClientBase["LMCacheAerospikeClient"]):
+    """Non-MP remote backend client wrapping ``LMCacheAerospikeClient``."""
+
+    def __init__(
+        self,
+        hosts: str,
+        namespace: str,
+        set_name: str,
+        num_workers: int,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        read_timeout_ms: int = 1000,
+        write_timeout_ms: int = 2000,
+        default_ttl_seconds: int = 86400,
+        target_segment_bytes: int = 0,
+        max_record_bytes: int = 0,
+        username: str = "",
+        password: str = "",
+    ) -> None:
+        """Create a client backed by the native Aerospike connector.
+
+        Args:
+            hosts: Seed hosts as ``host:port[,host:port...]``.
+            namespace: Aerospike namespace.
+            set_name: Aerospike set name.
+            num_workers: C++ worker threads for I/O.
+            loop: Optional asyncio loop for async wrappers.
+            read_timeout_ms: Read timeout in milliseconds.
+            write_timeout_ms: Write timeout in milliseconds.
+            default_ttl_seconds: Record TTL (0 = namespace default).
+            target_segment_bytes: Shard target (0 = use discovered cap).
+            max_record_bytes: Override server record cap (0 = discover).
+            username: Optional auth username.
+            password: Optional auth password.
+
+        Raises:
+            RuntimeError: If the C++ Aerospike extension is not built.
+        """
+        if not AEROSPIKE_AVAILABLE:
+            raise RuntimeError(
+                "AerospikeClient requires the C++ Aerospike extension. "
+                "Build with: BUILD_AEROSPIKE=1 pip install -e ."
+            )
+        native_client = LMCacheAerospikeClient(
+            hosts,
+            namespace,
+            set_name,
+            num_workers,
+            read_timeout_ms,
+            write_timeout_ms,
+            default_ttl_seconds,
+            target_segment_bytes,
+            max_record_bytes,
+            username,
+            password,
+        )
+        super().__init__(native_client, loop)
diff --git a/lmcache/v1/storage_backend/native_clients/connector_client_base.py b/lmcache/v1/storage_backend/native_clients/connector_client_base.py
new file mode 100644
index 0000000..7d5dbbe
--- /dev/null
+++ b/lmcache/v1/storage_backend/native_clients/connector_client_base.py
@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Dict, Generic, Optional, Tuple, TypeVar, Union
+import asyncio
+import concurrent.futures
+
+NativeClientT = TypeVar("NativeClientT")
+
+
+class ConnectorClientBase(Generic[NativeClientT]):
+    def __init__(
+        self,
+        native_client: NativeClientT,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ):
+        self.loop = loop or asyncio.get_running_loop()
+        self._client: NativeClientT = native_client
+        self._fd = int(self._client.event_fd())  # type: ignore[attr-defined]
+        self._closed = False
+        # Keepalive refs prevent buffers passed to native code from being
+        # garbage-collected while C++ worker threads still hold raw pointers.
+        self._pending: Dict[
+            int,
+            Tuple[
+                Union[asyncio.Future, concurrent.futures.Future], str, Tuple[Any, ...]
+            ],
+        ] = {}
+        self.loop.add_reader(self._fd, self._on_ready)
+
+    def _on_ready(self) -> None:
+        if self._closed:
+            return
+
+        try:
+            while True:
+                items = self._client.drain_completions()  # type: ignore[attr-defined]
+                if not items:
+                    return
+
+                for future_id, ok, error, result_bools in items:
+                    fid = int(future_id)
+                    entry = self._pending.pop(fid, None)
+                    if entry is None:
+                        continue
+
+                    fut, op, _keepalive = entry
+                    if fut.done():
+                        continue
+
+                    if ok:
+                        if op == "exists":
+                            if result_bools is not None and len(result_bools) > 0:
+                                fut.set_result(bool(result_bools[0]))
+                            else:
+                                fut.set_result(False)
+                        elif op == "batch_exists":
+                            if result_bools is not None:
+                                fut.set_result(list(result_bools))
+                            else:
+                                fut.set_result([])
+                        else:
+                            fut.set_result(None)
+                    else:
+                        fut.set_exception(RuntimeError(str(error)))
+        except Exception as e:
+            self._fail_all(RuntimeError(f"native drain_completions failed: {e}"))
+            self._shutdown_native(best_effort=True)
+
+    def _fail_all(self, exc: Exception) -> None:
+        for fid, (fut, _, _keepalive) in list(self._pending.items()):
+            if not fut.done():
+                fut.set_exception(exc)
+        self._pending.clear()
+
+    def _shutdown_native(self, best_effort: bool = False) -> None:
+        try:
+            self._closed = True
+            self.loop.remove_reader(self._fd)
+        except Exception:
+            if not best_effort:
+                raise
+
+    def _register_future_async(
+        self, op: str, future_id: int, keepalive: Tuple[Any, ...] = ()
+    ) -> asyncio.Future:
+        fut = self.loop.create_future()
+        self._pending[int(future_id)] = (fut, op, keepalive)
+        return fut
+
+    def _register_future_sync(
+        self, op: str, future_id: int, keepalive: Tuple[Any, ...] = ()
+    ) -> concurrent.futures.Future:
+        fut: concurrent.futures.Future = concurrent.futures.Future()
+        self._pending[int(future_id)] = (fut, op, keepalive)
+        return fut
+
+    async def get(self, key: str, buf: memoryview) -> None:
+        return await self.batch_get([key], [buf])
+
+    async def set(self, key: str, buf: memoryview) -> None:
+        return await self.batch_set([key], [buf])
+
+    async def exists(self, key: str) -> bool:
+        results = await self.batch_exists([key])
+        return results[0]
+
+    async def batch_get(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_get(keys, bufs))  # type: ignore[attr-defined]
+        fut = self._register_future_async("batch_get", future_id, (keys, tuple(bufs)))
+        return await fut
+
+    async def batch_set(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_set(keys, bufs))  # type: ignore[attr-defined]
+        fut = self._register_future_async("batch_set", future_id, (keys, tuple(bufs)))
+        return await fut
+
+    async def batch_exists(self, keys: list[str]) -> list[bool]:
+        future_id = int(self._client.submit_batch_exists(keys))  # type: ignore[attr-defined]
+        fut = self._register_future_async("batch_exists", future_id)
+        return await fut
+
+    async def batched_exists(self, keys: list[str]) -> list[bool]:
+        return await self.batch_exists(keys)
+
+    def get_sync(self, key: str, buf: memoryview) -> None:
+        return self.batch_get_sync([key], [buf])
+
+    def set_sync(self, key: str, buf: memoryview) -> None:
+        return self.batch_set_sync([key], [buf])
+
+    def exists_sync(self, key: str) -> bool:
+        results = self.batch_exists_sync([key])
+        return results[0]
+
+    def batch_get_sync(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_get(keys, bufs))  # type: ignore[attr-defined]
+        fut = self._register_future_sync("batch_get", future_id, (keys, tuple(bufs)))
+        return fut.result()
+
+    def batch_set_sync(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_set(keys, bufs))  # type: ignore[attr-defined]
+        fut = self._register_future_sync("batch_set", future_id, (keys, tuple(bufs)))
+        return fut.result()
+
+    def batch_exists_sync(self, keys: list[str]) -> list[bool]:
+        future_id = int(self._client.submit_batch_exists(keys))  # type: ignore[attr-defined]
+        fut = self._register_future_sync("batch_exists", future_id)
+        return fut.result()
+
+    def batched_exists_sync(self, keys: list[str]) -> list[bool]:
+        return self.batch_exists_sync(keys)
+
+    def close(self) -> None:
+        if not self._closed:
+            self._shutdown_native(best_effort=True)
+            self._fail_all(RuntimeError("Client closed"))
+            self._client.close()  # type: ignore[attr-defined]
diff --git a/lmcache/v1/storage_backend/native_clients/resp_client.py b/lmcache/v1/storage_backend/native_clients/resp_client.py
new file mode 100644
index 0000000..e91df0a
--- /dev/null
+++ b/lmcache/v1/storage_backend/native_clients/resp_client.py
@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+import asyncio
+
+# Local
+from .connector_client_base import ConnectorClientBase
+
+try:
+    # First Party
+    from lmcache.lmcache_redis import LMCacheRedisClient
+
+    REDIS_AVAILABLE = True
+except ImportError:
+    REDIS_AVAILABLE = False
+    LMCacheRedisClient = None  # type: ignore
+
+
+class RESPClient(ConnectorClientBase[LMCacheRedisClient]):
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        num_workers: int,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        username: str = "",
+        password: str = "",
+    ):
+        if not REDIS_AVAILABLE:
+            raise RuntimeError(
+                "RESPClient requires the C++ Redis extension. "
+                "Build with: pip install -e ."
+            )
+        native_client = LMCacheRedisClient(host, port, num_workers, username, password)
+        super().__init__(native_client, loop)
diff --git a/lmcache/v1/storage_backend/nixl_storage_backend.py b/lmcache/v1/storage_backend/nixl_storage_backend.py
new file mode 100644
index 0000000..196a6e5
--- /dev/null
+++ b/lmcache/v1/storage_backend/nixl_storage_backend.py
@@ -0,0 +1,2183 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2025 LMCache Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Standard
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    List,
+    Optional,
+    Sequence,
+    Set,
+    Tuple,
+    Union,
+    cast,
+)
+from urllib.parse import quote as url_quote
+import asyncio
+import hashlib
+import os
+import threading
+import time
+import uuid
+
+# Third Party
+from nixl._api import nixl_agent as NixlAgent
+from nixl._api import nixl_agent_config as NixlAgentConfig
+from nixl._api import nixl_prepped_dlist_handle as NixlDlistHandle
+
+try:
+    # Third Party
+    from nixl._api import (
+        nixl_thread_sync_t,
+    )
+
+    _NIXL_SYNC_MODE_SUPPORTED = True
+    _NIXL_SYNC_MODE_DEFAULT = nixl_thread_sync_t.NIXL_THREAD_SYNC_STRICT
+except ImportError:
+    nixl_thread_sync_t = None  # type: ignore[assignment]
+    _NIXL_SYNC_MODE_SUPPORTED = False
+    _NIXL_SYNC_MODE_DEFAULT = None
+# Third Party
+from nixl._api import nixl_xfer_handle as NixlXferHandle
+from nixl._api import (
+    nixlBind,
+)
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    _allocate_cpu_memory,
+    _allocate_gpu_memory,
+    _free_cpu_memory,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+from lmcache.v1.storage_backend.cache_policy import get_cache_policy
+from lmcache.v1.storage_backend.path_sharder import PathSharder
+from lmcache.v1.transfer_channel.transfer_utils import get_correct_device
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+logger = init_logger(__name__)
+
+# POSIX permission mode for files created via ``os.open()`` with ``O_CREAT``.
+# 0o644 = rw-r--r-- (owner read/write, group/others read-only).
+DEFAULT_FILE_CREATE_MODE = 0o644
+
+# Max concurrency for parallel S3 HEAD requests in batched_contains().
+_CONTAINS_BATCH_SIZE = 16
+
+# Max static b128 pool size: the slot index occupies 8 hex chars (32 bits) of
+# the 32-hex-char (128-bit) name, so the index must be <= 0xffffffff.
+B128_MAX_POOL_SIZE = 0x100000000  # 2**32
+
+
+@dataclass
+class NixlStorageConfig:
+    buffer_size: int
+    pool_size: int
+    buffer_device: str
+    backend: str
+    backend_params: dict[str, str]
+    dynamic_storage: bool
+    enable_presence_cache: bool
+    enable_async_put: bool
+    use_direct_io: bool
+    path: Union[str, List[str]]
+    use_hugepages: bool
+    enable_prog_thread: bool
+    sync_mode: Optional[Any]  # nixl_thread_sync_t, None if unsupported
+    presence_cache_only: bool
+    path_sharding: str
+
+    @staticmethod
+    def validate_nixl_backend(backend: str, device: str) -> bool:
+        device = device.split(":", 1)[0]
+        if backend in ("GDS", "GDS_MT", "OBJ"):
+            return device == "cpu" or device == "cuda"
+        elif backend in ("POSIX", "HF3FS", "AZURE_BLOB", "DOCA_MEMOS"):
+            return device == "cpu"
+        else:
+            return False
+
+    @staticmethod
+    def from_cache_engine_config(
+        config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ):
+        assert config.nixl_buffer_device is not None
+        if config.nixl_buffer_device != "cpu":
+            assert config.nixl_buffer_size is not None
+
+        extra_config = config.extra_config
+        assert extra_config is not None
+        assert extra_config.get("enable_nixl_storage")
+
+        enable_presence_cache = extra_config.get("nixl_presence_cache", False)
+        enable_async_put = extra_config.get("nixl_async_put", False)
+        backend_params = dict(extra_config.get("nixl_backend_params", {}))
+        use_direct_io = extra_config.get("use_direct_io", False)
+        pool_size = extra_config.get("nixl_pool_size")
+
+        backend = extra_config.get("nixl_backend")
+
+        # Per-worker endpoint distribution: if nixl_endpoint_list is set,
+        # override endpoint_override so each TP worker targets a different
+        # object-storage endpoint (round-robin by local_worker_id).
+        endpoint_list = extra_config.get("nixl_endpoint_list")
+        if endpoint_list is not None and len(endpoint_list) == 0:
+            raise ValueError("nixl_endpoint_list is set but empty")
+        if backend == "OBJ" and endpoint_list:
+            if "endpoint_override" in backend_params:
+                logger.warning(
+                    "nixl_endpoint_list is set; ignoring "
+                    "nixl_backend_params.endpoint_override (%s)",
+                    backend_params["endpoint_override"],
+                )
+            ep = endpoint_list[metadata.local_worker_id % len(endpoint_list)]
+            if not ep.startswith(("http://", "https://")):
+                raise ValueError(
+                    f"nixl_endpoint_list entry {ep!r} is not a valid URL "
+                    "(must start with 'http://' or 'https://')"
+                )
+            backend_params["endpoint_override"] = ep
+            logger.info(
+                "Worker %d using endpoint %s (from %d endpoints)",
+                metadata.local_worker_id,
+                ep,
+                len(endpoint_list),
+            )
+        path = extra_config.get("nixl_path")
+        use_hugepages = extra_config.get("nixl_use_hugepages", False)
+        enable_prog_thread = extra_config.get("nixl_enable_prog_thread", True)
+        sync_mode_str = extra_config.get("nixl_sync_mode", None)
+        if sync_mode_str is not None and not _NIXL_SYNC_MODE_SUPPORTED:
+            raise ValueError(
+                "nixl_sync_mode is set in config but this NIXL version does not "
+                "support the sync_mode argument in NixlAgentConfig "
+                "(requires ai-dynamo/nixl#1501). Remove nixl_sync_mode from config "
+                "or upgrade NIXL."
+            )
+        sync_mode = _NIXL_SYNC_MODE_DEFAULT
+        if sync_mode_str is not None:
+            attr_name = f"NIXL_THREAD_SYNC_{sync_mode_str.upper()}"
+            if not hasattr(nixl_thread_sync_t, attr_name):
+                raise ValueError(
+                    f"Invalid nixl_sync_mode '{sync_mode_str}'. "
+                    f"Valid values are the suffixes of NIXL_THREAD_SYNC_* "
+                    f"in nixl_thread_sync_t."
+                )
+            sync_mode = getattr(nixl_thread_sync_t, attr_name)
+        presence_cache_only = extra_config.get("nixl_presence_cache_only", False)
+
+        path_sharding = extra_config.get("nixl_path_sharding", "by_gpu")
+
+        assert pool_size is not None
+        assert backend is not None
+        assert use_direct_io in [False, True]
+
+        dynamic_storage = pool_size == 0
+        if dynamic_storage:
+            assert not config.save_unfull_chunk, (
+                "save_unfull_chunk should be set to False when using dynamic storage"
+            )
+
+        corrected_device = get_correct_device(
+            config.nixl_buffer_device, metadata.worker_id
+        )
+
+        # align the buffer size to have the required alignment. In CPU mode the
+        # pool is owned by LocalCPUBackend (sized by max_local_cpu_size) and the
+        # nixl_buffer_size config field is unused; the buffer_size on the
+        # resulting NixlStorageConfig is left as 0.
+        if config.nixl_buffer_device == "cpu":
+            buffer_size = 0
+        else:
+            align_bytes = get_size_bytes(
+                [torch.Size(metadata.kv_shape)], [metadata.kv_dtype]
+            )
+            if config.nixl_buffer_size % align_bytes != 0:
+                buffer_size = (
+                    (config.nixl_buffer_size + align_bytes - 1) // align_bytes
+                ) * align_bytes
+                logger.warning(
+                    f"Nixl buffer size {config.nixl_buffer_size} is not a multiple of "
+                    f"align bytes {align_bytes}, auto aligned to {buffer_size}"
+                )
+                config.nixl_buffer_size = buffer_size
+            else:
+                buffer_size = config.nixl_buffer_size
+
+        assert NixlStorageConfig.validate_nixl_backend(
+            backend, config.nixl_buffer_device
+        ), "Invalid NIXL backend & device combination"
+
+        if backend in ("GDS", "GDS_MT", "POSIX", "HF3FS"):
+            assert path is not None, f"nixl_path must be provided for {backend} backend"
+
+        return NixlStorageConfig(
+            buffer_size=buffer_size,
+            pool_size=pool_size,
+            buffer_device=corrected_device,
+            backend=backend,
+            backend_params=backend_params,
+            dynamic_storage=dynamic_storage,
+            enable_presence_cache=enable_presence_cache,
+            enable_async_put=enable_async_put,
+            use_direct_io=use_direct_io,
+            path=path,
+            use_hugepages=use_hugepages,
+            enable_prog_thread=enable_prog_thread,
+            sync_mode=sync_mode,
+            presence_cache_only=presence_cache_only,
+            path_sharding=path_sharding,
+        )
+
+
+class NixlDescPool(ABC):
+    def __init__(self, size: int):
+        self.lock = threading.Lock()
+        self.size: int = size
+        self.indices: List[int] = []
+        self.indices.extend(reversed(range(size)))
+
+    def get_num_available_descs(self) -> int:
+        with self.lock:
+            return len(self.indices)
+
+    def pop(self) -> int:
+        with self.lock:
+            assert len(self.indices) > 0
+            return self.indices.pop()
+
+    def push(self, index: int):
+        with self.lock:
+            assert len(self.indices) < self.size
+            self.indices.append(index)
+
+    @abstractmethod
+    def close(self):
+        pass
+
+
+class NixlFilePool(NixlDescPool):
+    def __init__(
+        self,
+        size: int,
+        sharder: PathSharder,
+        use_direct_io: bool,
+    ):
+        super().__init__(size)
+        self.fds: List[int] = []
+
+        flags = os.O_CREAT | os.O_RDWR
+        if use_direct_io:
+            if hasattr(os, "O_DIRECT"):
+                flags |= os.O_DIRECT
+            else:
+                logger.warning(
+                    "use_direct_io is True, but O_DIRECT is not available on "
+                    "this system. Falling back to buffered I/O."
+                )
+        base_path = sharder.selected
+
+        for i in reversed(range(size)):
+            filename = f"obj_{i}_{uuid.uuid4().hex[0:4]}.bin"
+            tmp_path = os.path.join(base_path, filename)
+            fd = os.open(tmp_path, flags)
+            self.fds.append(fd)
+
+    def close(self):
+        # TODO: do we need to delete the files?
+        with self.lock:
+            assert len(self.fds) == self.size
+            for fd in self.fds:
+                os.close(fd)
+
+
+class NixlObjectPool(NixlDescPool):
+    def __init__(self, size: int, b128: bool = False) -> None:
+        """Create a pool of ``size`` NIXL object slot names.
+
+        Args:
+            size: Number of object slots to pre-generate.
+            b128: If True, generate 128-bit hex slot names (32 hex chars) for
+                the DOCA_MEMOS backend instead of the default ``obj_{i}_{uuid}``
+                names.
+
+        Raises:
+            ValueError: If ``b128`` is True and ``size`` exceeds
+                ``B128_MAX_POOL_SIZE`` (the slot index would no longer fit in
+                8 hex chars).
+        """
+        if b128 and size > B128_MAX_POOL_SIZE:
+            raise ValueError(
+                "b128 object pool supports at most 2**32 slots "
+                f"(got {size}); the slot index must fit in 8 hex chars"
+            )
+        super().__init__(size)
+        self.keys: List[str] = []
+
+        for i in reversed(range(size)):
+            if b128:
+                # DOCA_MEMOS requires slot names that fit in 128 bits and are
+                # hex-decodable (the NIXL plugin hex-decodes the name on the
+                # other side). 8 hex chars (32 bits) encode the slot index for
+                # in-pool uniqueness; 24 hex chars (96 bits) of randomness avoid
+                # collisions across LMCache instances on the shared backend.
+                key = f"{i:08x}{uuid.uuid4().hex[:24]}"
+            else:
+                key = f"obj_{i}_{uuid.uuid4().hex[0:4]}"
+            self.keys.append(key)
+
+    def close(self):
+        pass
+
+
+class SetPresenceCache:
+    """Default presence cache using a thread-safe Python set."""
+
+    def __init__(self) -> None:
+        self._keys: set[int] = set()
+
+    def add(self, key: int) -> None:
+        self._keys.add(key)
+
+    def discard(self, key: int) -> None:
+        self._keys.discard(key)
+
+    def contains(self, key: int) -> bool:
+        return key in self._keys
+
+
+PresenceCache = Union[SetPresenceCache]
+
+
+@dataclass
+class NixlDesc:
+    device_id: int
+    meta_info: str
+    path: Optional[str] = None
+
+
+def _close_file_descs(descs: List[NixlDesc]) -> None:
+    """Best-effort close of the FDs in descs."""
+    for d in descs:
+        try:
+            os.close(d.device_id)
+        except OSError:
+            pass
+
+
+def _unlink_file_descs(descs: List[NixlDesc]) -> None:
+    """
+    Best-effort unlink of every desc whose ``path`` is set.
+
+    Called only on FILE-write failure paths to remove the (empty or
+    partially-written) file we created with ``O_CREAT``.
+    """
+    for d in descs:
+        if d.path is None:
+            continue
+        try:
+            os.unlink(d.path)
+        except OSError:
+            pass
+
+
+@dataclass
+class NixlKeyMetadata:
+    index: int
+    shape: Optional[torch.Size] = None
+    dtype: Optional[torch.dtype] = None
+    fmt: Optional[MemoryFormat] = None
+    pin_count: int = 0
+
+    def pin(self) -> bool:
+        self.pin_count += 1
+        return True
+
+    def unpin(self) -> bool:
+        self.pin_count -= 1
+        return True
+
+    @property
+    def is_pinned(self) -> bool:
+        return self.pin_count > 0
+
+    @property
+    def can_evict(self) -> bool:
+        """
+        Check if the related key can be evicted.
+        """
+        return not self.is_pinned
+
+
+class NixlStorageAgent(ABC):
+    agent_name: str
+    nixl_agent: NixlAgent
+    mem_reg_descs: nixlBind.nixlRegDList
+    mem_xfer_handler: NixlDlistHandle
+
+    def __init__(
+        self,
+        allocator: PagedTensorMemoryAllocator,
+        device: str,
+        backend: str,
+        backend_params: dict[str, str],
+        enable_prog_thread: bool,
+        sync_mode: Optional[Any] = None,
+    ):
+        buffer_ptr = allocator.buffer_ptr
+        buffer_size = allocator.buffer_size
+        page_size = allocator.align_bytes
+
+        self.backend = backend
+        self.agent_name = "NixlAgent_" + str(uuid.uuid4())
+        nixl_conf_kwargs: dict[str, Any] = {
+            "backends": [],
+            "enable_prog_thread": enable_prog_thread,
+        }
+        if sync_mode is not None:
+            nixl_conf_kwargs["sync_mode"] = sync_mode
+        nixl_conf = NixlAgentConfig(**nixl_conf_kwargs)
+        self.nixl_agent = NixlAgent(self.agent_name, nixl_conf)
+        self.nixl_agent.create_backend(backend, backend_params)
+
+        device_id = torch_dev.current_device()
+        self.init_mem_handlers(device, buffer_ptr, buffer_size, page_size, device_id)
+
+    def init_mem_handlers(self, device, buffer_ptr, buffer_size, page_size, device_id):
+        # Break the registration into page size chunks to ensure the maximum buffer size
+        # of the underlying plugin is not exceeded
+        reg_list = [
+            (base_addr, page_size, device_id, "")
+            for base_addr in range(buffer_ptr, buffer_ptr + buffer_size, page_size)
+        ]
+        xfer_desc = [
+            (base_addr, page_size, device_id)
+            for base_addr in range(buffer_ptr, buffer_ptr + buffer_size, page_size)
+        ]
+
+        if device == "cpu":
+            mem_type = "DRAM"
+        else:
+            mem_type = "VRAM"
+
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type=mem_type)
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type=mem_type)
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            "", xfer_descs, mem_type=mem_type
+        )
+
+        self.mem_reg_descs = reg_descs
+        self.mem_xfer_handler = xfer_handler
+
+    def get_mem_to_storage_handle(
+        self, mem_indices, storage_xfer_handler, storage_indices
+    ) -> NixlXferHandle:
+        return self.nixl_agent.make_prepped_xfer(
+            "WRITE",
+            self.mem_xfer_handler,
+            mem_indices,
+            storage_xfer_handler,
+            storage_indices,
+        )
+
+    def get_storage_to_mem_handle(
+        self, mem_indices, storage_xfer_handler, storage_indices
+    ) -> NixlXferHandle:
+        return self.nixl_agent.make_prepped_xfer(
+            "READ",
+            self.mem_xfer_handler,
+            mem_indices,
+            storage_xfer_handler,
+            storage_indices,
+        )
+
+    def post_blocking(self, handle: NixlXferHandle):
+        state = self.nixl_agent.transfer(handle)
+
+        # time.sleep here is acceptable for now:
+        # - Dynamic backend writes: async_mode=True uses post_async + asyncio.sleep
+        #   instead, so post_blocking is only reached with async_mode=False (sync puts).
+        # - Dynamic backend reads: batched_get_non_blocking calls storage_to_mem
+        #   synchronously, but async reads are broken regardless.
+        while state != "DONE" and state != "ERR":
+            try:
+                state = self.nixl_agent.check_xfer_state(handle)
+            except nixlBind.nixlBackendError:
+                raise
+            if state != "DONE" and state != "ERR":
+                time.sleep(0.001)
+
+        if state == "ERR":
+            raise RuntimeError("NIXL transfer failed")
+
+    def release_handle(self, handle):
+        self.nixl_agent.release_xfer_handle(handle)
+
+    @abstractmethod
+    def close(self):
+        pass
+
+
+class NixlStaticStorageAgent(NixlStorageAgent):
+    pool: NixlDescPool
+    storage_reg_descs: nixlBind.nixlRegDList
+    storage_xfer_descs: nixlBind.nixlXferDList
+    storage_xfer_handler: NixlDlistHandle
+
+    def __init__(
+        self,
+        allocator: PagedTensorMemoryAllocator,
+        pool: NixlDescPool,
+        device: str,
+        backend: str,
+        backend_params: dict[str, str],
+        enable_prog_thread: bool,
+        sync_mode: Optional[Any] = None,
+    ):
+        super().__init__(
+            allocator, device, backend, backend_params, enable_prog_thread, sync_mode
+        )
+
+        page_size = allocator.align_bytes
+
+        if isinstance(pool, NixlFilePool):
+            self.init_storage_handlers_file(page_size, pool.fds)
+        elif isinstance(pool, NixlObjectPool):
+            self.init_storage_handlers_object(page_size, pool.keys)
+        else:
+            raise TypeError(f"Unsupported pool type: {type(pool).__name__}")
+
+    def init_storage_handlers_file(self, page_size, fds):
+        reg_list = []
+        xfer_desc = []
+        for fd in fds:
+            reg_list.append((0, page_size, fd, ""))
+            xfer_desc.append((0, page_size, fd))
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type="FILE")
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type="FILE")
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            self.agent_name, xfer_desc, mem_type="FILE"
+        )
+
+        self.storage_reg_descs = reg_descs
+        self.storage_xfer_descs = xfer_descs
+        self.storage_xfer_handler = xfer_handler
+
+    def init_storage_handlers_object(self, page_size, keys):
+        reg_list = []
+        xfer_desc = []
+        for i, key in enumerate(keys):
+            reg_list.append((0, page_size, i, key))
+            xfer_desc.append((0, page_size, i))
+        reg_descs = self.nixl_agent.register_memory(reg_list, mem_type="OBJ")
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, mem_type="OBJ")
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            self.agent_name, xfer_desc, mem_type="OBJ"
+        )
+
+        self.storage_reg_descs = reg_descs
+        self.storage_xfer_descs = xfer_descs
+        self.storage_xfer_handler = xfer_handler
+
+    def get_mem_to_storage_handle(self, mem_indices, storage_indices) -> NixlXferHandle:  # type: ignore[override]
+        return super().get_mem_to_storage_handle(
+            mem_indices, self.storage_xfer_handler, storage_indices
+        )
+
+    def get_storage_to_mem_handle(self, mem_indices, storage_indices) -> NixlXferHandle:  # type: ignore[override]
+        return super().get_storage_to_mem_handle(
+            mem_indices, self.storage_xfer_handler, storage_indices
+        )
+
+    def close(self):
+        self.nixl_agent.release_dlist_handle(self.storage_xfer_handler)
+        self.nixl_agent.release_dlist_handle(self.mem_xfer_handler)
+        self.nixl_agent.deregister_memory(self.storage_reg_descs)
+        self.nixl_agent.deregister_memory(self.mem_reg_descs)
+
+
+class NixlDynamicStorageAgent(NixlStorageAgent):
+    def __init__(
+        self,
+        allocator: PagedTensorMemoryAllocator,
+        device: str,
+        backend: str,
+        backend_params: dict[str, str],
+        enable_prog_thread: bool,
+        sync_mode: Optional[Any] = None,
+    ):
+        super().__init__(
+            allocator, device, backend, backend_params, enable_prog_thread, sync_mode
+        )
+
+        if backend in ("OBJ", "AZURE_BLOB", "DOCA_MEMOS"):
+            self.mem_type = "OBJ"
+        else:
+            self.mem_type = "FILE"
+
+    def create_batched_storage_handler(self, descs: list[NixlDesc], page_size: int):
+        reg_list = []
+        xfer_desc = []
+
+        for i in range(len(descs)):
+            reg_list.append((0, page_size, descs[i].device_id, descs[i].meta_info))
+            xfer_desc.append((0, page_size, descs[i].device_id))
+
+        reg_descs = self.nixl_agent.register_memory(reg_list, self.mem_type)
+        xfer_descs = self.nixl_agent.get_xfer_descs(xfer_desc, self.mem_type)
+        xfer_handler = self.nixl_agent.prep_xfer_dlist(
+            self.agent_name, xfer_descs, mem_type=self.mem_type
+        )
+        return reg_descs, xfer_handler
+
+    def post_async(self, handle: NixlXferHandle):
+        """Non-blocking async post for WRITE operations."""
+        state = self.nixl_agent.transfer(handle)
+        return state
+
+    def release_storage_handler(
+        self,
+        reg_descs: nixlBind.nixlRegDList,
+        xfer_handler: NixlDlistHandle,
+        descs: List[NixlDesc],
+    ) -> None:
+        """
+        Release storage handler resources.
+
+        :param reg_descs: Memory descriptors to deregister.
+        :param xfer_handler: Transfer dlist handle to release.
+        :param descs: Descriptors used for this transfer.
+        """
+        self.nixl_agent.release_dlist_handle(xfer_handler)
+        self.nixl_agent.deregister_memory(reg_descs)
+        if self.mem_type == "FILE":
+            _close_file_descs(descs)
+
+    def nixl_desc_exists(self, meta_info: str, path: str) -> bool:
+        """
+        Check whether a NIXL descriptor exists in storage.
+
+        :param meta_info: Descriptor key (file basename for FILE backends,
+            object key for OBJ backends).
+        :param path: Directory for FILE backends; ignored for OBJ.
+        :return: ``True`` if present, ``False`` otherwise.
+        """
+        if self.mem_type == "FILE":
+            return os.path.exists(os.path.join(path, meta_info))
+
+        reg_list = [(0, 0, 0, meta_info)]
+        try:
+            resp = self.nixl_agent.query_memory(
+                reg_list, self.backend, mem_type=self.mem_type
+            )
+            # nixl api query_memory returns a list of nixlRegDesc
+            if resp[0] is None:
+                return False
+            return True
+        except Exception as exc:
+            logger.warning(f"NIXL Desc {meta_info} query failed: {exc}")
+            return False
+
+    def batched_nixl_desc_exists(
+        self, reg_list: List[tuple[int, int, int, str]], path: Optional[str] = None
+    ) -> int:
+        """Check if multiple descriptors exist from the start of ``reg_list``.
+
+        :param reg_list: List of tuples ``(0, 0, 0, meta_info)`` where
+            *meta_info* is the formatted object-key string.
+        :param path: Directory for FILE backends (required for FILE; ignored
+            for OBJ). FILE existence is resolved on the filesystem, since NIXL
+            ``query_memory`` only answers for object stores.
+        :return: Number of consecutive descriptors that exist from the
+            start of the list.
+        :raises ValueError: If ``path`` is ``None`` for a FILE backend.
+        :raises: Errors from the underlying ``query_memory`` call (OBJ
+            backends) are caught internally and logged as warnings; the
+            method returns ``0`` in that case.
+        """
+        if not reg_list:
+            return 0
+
+        # FILE backends are not resolvable via NIXL ``query_memory`` (it only
+        # answers for object stores), so reuse the single-key
+        # ``nixl_desc_exists`` -- which already handles FILE via os.path.exists.
+        # Without this, FILE/POSIX dynamic backends always return 0 here, so
+        # every batched lookup misses and the cache is never reused.
+        if self.mem_type == "FILE":
+            if path is None:
+                raise ValueError("path must be provided for FILE backends")
+            consecutive_count = 0
+            for _, _, _, meta_info in reg_list:
+                if self.nixl_desc_exists(meta_info, path):
+                    consecutive_count += 1
+                else:
+                    break
+            return consecutive_count
+
+        try:
+            resp = self.nixl_agent.query_memory(
+                reg_list, self.backend, mem_type=self.mem_type
+            )
+            # nixl api query_memory returns a list of nixlRegDesc
+            # Count consecutive descriptors that exist (resp[i] is not None)
+            consecutive_count = 0
+            for reg_desc in resp:
+                if reg_desc is not None:
+                    consecutive_count += 1
+                else:
+                    break
+
+            return consecutive_count
+        except Exception as exc:
+            logger.warning(f"NIXL batched query failed: {exc}")
+            return 0
+
+    def close(self):
+        self.nixl_agent.release_dlist_handle(self.mem_xfer_handler)
+        self.nixl_agent.deregister_memory(self.mem_reg_descs)
+
+
+class NixlStorageBackend(AllocatorBackendInterface, ABC):
+    """
+    Implementation of the StorageBackendInterface for Nixl.
+
+    Currently, the put is synchronized and blocking, to simplify the
+    implementation.
+    """
+
+    def __init__(
+        self,
+        nixl_config: NixlStorageConfig,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: Optional["LocalCPUBackend"] = None,
+    ):
+        """
+        Initialize the Nixl storage backend.
+
+        :param nixl_config: The Nixl storage configuration.
+        :param config: The LMCache engine configuration.
+        :param metadata: The LMCache metadata.
+        :param loop: The asyncio event loop.
+        :param local_cpu_backend: The LocalCPUBackend whose MixedMemoryAllocator
+            (with use_paging=True) will be shared with this NIXL backend in CPU
+            mode.  Must be provided (and non-None) when nixl_config.buffer_device
+            is ``"cpu"``.  Ignored in GPU mode.
+        :raises RuntimeError: In CPU mode, if *local_cpu_backend* is None, or if
+            its allocator is not a MixedMemoryAllocator wrapping a
+            PagedTensorMemoryAllocator.
+        """
+        super().__init__(dst_device=nixl_config.buffer_device)
+
+        self.loop = loop
+        self.key_lock = threading.RLock()
+
+        self.progress_lock = threading.RLock()
+        self.progress_set: Set[CacheEngineKey] = set()
+
+        self.nixl_config = nixl_config
+        self._local_cpu_backend: Optional["LocalCPUBackend"] = None
+
+        if nixl_config.buffer_device != "cpu":
+            # GPU mode: allocate own staging buffer now
+            self.memory_allocator: PagedTensorMemoryAllocator = (
+                self.initialize_allocator(config, metadata)
+            )
+        else:
+            # CPU mode: share the LocalCPUBackend's PagedTensorMemoryAllocator
+            if local_cpu_backend is None:
+                raise RuntimeError(
+                    "nixl_buffer_device=cpu requires a LocalCPUBackend staging buffer "
+                    "(set max_local_cpu_size > 0)"
+                )
+            allocator = local_cpu_backend.get_memory_allocator()
+            if not isinstance(allocator, MixedMemoryAllocator) or not isinstance(
+                allocator.pin_allocator, PagedTensorMemoryAllocator
+            ):
+                raise RuntimeError(
+                    "LocalCPUBackend must use MixedMemoryAllocator(use_paging=True) "
+                    "when NIXL CPU mode is enabled. Ensure enable_nixl_storage + "
+                    "nixl_buffer_device=cpu triggered the paged allocator path in "
+                    "LocalCPUBackend.initialize_allocator()."
+                )
+            self.memory_allocator = allocator.pin_allocator
+            self._local_cpu_backend = local_cpu_backend
+            self.free_pinned_buffer = False
+            logger.debug(
+                "nixl_buffer_device=cpu: NIXL sharing LocalCPUBackend's pool "
+                "(sized by max_local_cpu_size=%.2f GiB)",
+                config.max_local_cpu_size,
+            )
+
+    def initialize_allocator(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ) -> PagedTensorMemoryAllocator:
+        extra_config = config.extra_config
+        enable_nixl_storage = extra_config is not None and extra_config.get(
+            "enable_nixl_storage"
+        )
+        assert enable_nixl_storage
+
+        corrected_device = get_correct_device(
+            config.nixl_buffer_device,
+            metadata.worker_id,
+        )
+
+        self.use_hugepages = self.nixl_config.use_hugepages
+        self.buffer_size = config.nixl_buffer_size
+        if corrected_device == "cpu":
+            self.buffer = _allocate_cpu_memory(
+                config.nixl_buffer_size, use_hugepages=self.use_hugepages
+            )
+            self.free_pinned_buffer = True
+        else:
+            if self.use_hugepages:
+                logger.warning("Hugepages are not supported for GPU memory allocation")
+                self.use_hugepages = False
+            base_buffer, self.buffer = _allocate_gpu_memory(
+                config.nixl_buffer_size, corrected_device
+            )
+            torch_dev.set_device(corrected_device)
+            self.base_buffer = base_buffer  # Prevents early GC of the aligned tensor.
+            self.free_pinned_buffer = False
+
+        return PagedTensorMemoryAllocator(
+            self.buffer,
+            [torch.Size(metadata.kv_shape)],
+            [metadata.kv_dtype],
+            MemoryFormat.KV_2LTD,
+        )
+
+    def get_memory_allocator(self):
+        if self._local_cpu_backend is not None:
+            return self._local_cpu_backend.get_memory_allocator()
+        return self.memory_allocator
+
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        if busy_loop:
+            logger.warning("NixlStorageBackend does not support busy loop for now")
+
+        if self._local_cpu_backend is not None:
+            return self._local_cpu_backend.allocate(
+                shapes, dtypes, fmt, eviction=eviction, busy_loop=False
+            )
+        return self.memory_allocator.allocate(shapes, dtypes, fmt)
+
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[list[MemoryObj]]:
+        if busy_loop:
+            logger.warning("NixlStorageBackend does not support busy loop for now")
+
+        if self._local_cpu_backend is not None:
+            return self._local_cpu_backend.batched_allocate(
+                shapes, dtypes, batch_size, fmt, eviction=eviction, busy_loop=False
+            )
+        return self.memory_allocator.batched_allocate(shapes, dtypes, batch_size, fmt)
+
+    def get_allocator_backend(self):
+        if self._local_cpu_backend is not None:
+            return self._local_cpu_backend
+        return self
+
+    @abstractmethod
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        pass
+
+    @abstractmethod
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        pass
+
+    @abstractmethod
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        pass
+
+    @abstractmethod
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        pass
+
+    @abstractmethod
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        pass
+
+    @abstractmethod
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        pass
+
+    @abstractmethod
+    def pin(self, key: CacheEngineKey) -> bool:
+        pass
+
+    @abstractmethod
+    def unpin(self, key: CacheEngineKey) -> bool:
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        pass
+
+    @staticmethod
+    def CreateNixlStorageBackend(
+        config: LMCacheEngineConfig,
+        loop: asyncio.AbstractEventLoop,
+        metadata: LMCacheMetadata,
+        local_cpu_backend: Optional["LocalCPUBackend"] = None,
+    ):
+        """
+        Create a Nixl backend with the given configuration.
+
+        :param config: The LMCache engine configuration.
+        :param loop: The asyncio event loop.
+        :param metadata: The LMCache metadata.
+        :param local_cpu_backend: The LocalCPUBackend whose MixedMemoryAllocator
+            (with use_paging=True) will be shared with this NIXL backend in CPU
+            mode.  Required when ``config.nixl_buffer_device == "cpu"``.
+
+        :return: A NixlBackend instance.
+        """
+        # Create the Nixl config
+        nixl_config = NixlStorageConfig.from_cache_engine_config(config, metadata)
+        # Create the Nixl backend
+        if nixl_config.dynamic_storage:
+            return NixlDynamicStorageBackend(
+                nixl_config, config, metadata, loop, local_cpu_backend
+            )
+        else:
+            return NixlStaticStorageBackend(
+                nixl_config, config, metadata, loop, local_cpu_backend
+            )
+
+
+class NixlStaticStorageBackend(NixlStorageBackend):
+    def __init__(
+        self,
+        nixl_config: NixlStorageConfig,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: Optional["LocalCPUBackend"] = None,
+    ):
+        super().__init__(nixl_config, config, metadata, loop, local_cpu_backend)
+
+        self.cache_policy = get_cache_policy(config.cache_policy)
+        self.key_dict = self.cache_policy.init_mutable_mapping()
+
+        self.pool = self.createPool(
+            nixl_config.backend,
+            nixl_config.pool_size,
+            nixl_config.path,
+            nixl_config.use_direct_io,
+            nixl_config.path_sharding,
+            f"cuda:{metadata.worker_id}",
+        )
+        assert self.pool is not None
+
+        # In CPU mode self.memory_allocator was set by the base __init__
+        # (from local_cpu_backend); in GPU mode it was allocated there too.
+        # Either way it is ready here.
+        self.agent: NixlStaticStorageAgent = NixlStaticStorageAgent(
+            self.memory_allocator,
+            self.pool,
+            nixl_config.buffer_device,
+            nixl_config.backend,
+            nixl_config.backend_params,
+            nixl_config.enable_prog_thread,
+            nixl_config.sync_mode,
+        )
+
+    @staticmethod
+    def createPool(
+        backend: str,
+        size: int,
+        path: Union[str, List[str]],
+        use_direct_io: bool,
+        path_sharding: str,
+        dst_device: str,
+    ) -> NixlDescPool:
+        """Create a NIXL descriptor pool with path sharding support.
+
+        Args:
+            backend: Backend type (e.g., "GDS", "POSIX", "OBJ").
+            size: Pool size.
+            path: Single path string or list of paths for sharding.
+            use_direct_io: Whether to use direct I/O.
+            path_sharding: Sharding strategy (e.g., "by_gpu").
+            dst_device: Device string for path selection.
+
+        Returns:
+            NixlDescPool: The created descriptor pool.
+
+        Raises:
+            ValueError: If backend is unsupported or path is invalid.
+
+        Note:
+            When *path* is provided as a list, entries containing commas will be
+            split when joined for PathSharder. Avoid commas in path entries to
+            prevent unintended sharding.
+        """
+
+        if backend in ("GDS", "GDS_MT", "POSIX", "HF3FS"):
+            if isinstance(path, list) and any("," in p for p in path):
+                logger.warning(
+                    "nixl_path entries contain commas; joining for PathSharder may "
+                    "cause unintended sharding. Consider paths without commas or a "
+                    "single comma-separated string."
+                )
+            sharder = PathSharder(
+                raw_csv=path if isinstance(path, str) else ",".join(path),
+                strategy=path_sharding,
+                dst_device=dst_device,
+                create_dirs=True,
+            )
+            return NixlFilePool(size, sharder, use_direct_io)
+        elif backend in ("OBJ", "AZURE_BLOB", "DOCA_MEMOS"):
+            return NixlObjectPool(size, b128=(backend == "DOCA_MEMOS"))
+        else:
+            raise ValueError(f"Unsupported NIXL backend: {backend}")
+
+    def add_key_to_dict(
+        self, key: CacheEngineKey, obj: MemoryObjMetadata, index: int
+    ) -> None:
+        with self.key_lock:
+            assert key not in self.key_dict
+            self.key_dict[key] = NixlKeyMetadata(
+                shape=obj.shape,
+                dtype=obj.dtype,
+                fmt=obj.fmt,
+                index=index,
+            )
+            self.cache_policy.update_on_put(key)
+
+    async def mem_to_storage(
+        self, keys: Sequence[CacheEngineKey], mem_objs: List[MemoryObj]
+    ) -> None:
+        mem_indices = [mem_obj.meta.address for mem_obj in mem_objs]
+
+        storage_indices = []
+        for i in range(len(keys)):
+            index = self.pool.pop()
+            storage_indices.append(index)
+            self.add_key_to_dict(keys[i], mem_objs[i].meta, index)
+
+        handle = self.agent.get_mem_to_storage_handle(mem_indices, storage_indices)
+        self.agent.post_blocking(handle)
+        self.agent.release_handle(handle)
+
+        for key in keys:
+            with self.progress_lock:
+                self.progress_set.discard(key)
+
+    def _collect_metadata_with_lock(
+        self, keys: list[CacheEngineKey]
+    ) -> list[Optional[NixlKeyMetadata]]:
+        """
+        Fast metadata collection with lock.
+        Returns metadata for each key, None if key doesn't exist.
+        """
+        metadata_list: list[Optional[NixlKeyMetadata]] = []
+        with self.key_lock:
+            for key in keys:
+                metadata = self.key_dict.get(key)
+                if metadata is not None:
+                    self.cache_policy.update_on_hit(key, self.key_dict)
+                metadata_list.append(metadata)
+        return metadata_list
+
+    async def _nixl_transfer_async(
+        self, metadata_list: list[Optional[NixlKeyMetadata]]
+    ) -> list[Optional[MemoryObj]]:
+        """
+        Memory allocation and NIXL transfer without locks.
+        Can run async and in parallel with other transfers.
+        """
+        obj_list: list[Optional[MemoryObj]] = []
+        mem_indices = []
+        storage_indices = []
+
+        # Memory allocation outside lock
+        for metadata in metadata_list:
+            if metadata is None:
+                obj_list.append(None)
+                continue
+
+            dtype = metadata.dtype
+            shape = metadata.shape
+            fmt = metadata.fmt
+            assert dtype is not None
+            assert shape is not None
+            assert fmt is not None
+
+            if self._local_cpu_backend is not None:
+                obj = self._local_cpu_backend.allocate(
+                    shape, dtype, fmt, eviction=True, busy_loop=False
+                )
+            else:
+                obj = self.memory_allocator.allocate(shape, dtype, fmt)
+            if obj is None:
+                if self._local_cpu_backend is not None:
+                    logger.warning(
+                        "Failed to allocate from the NIXL/LocalCPUBackend "
+                        "shared pool — all pages are pinned. Consider "
+                        "increasing `max_local_cpu_size`."
+                    )
+                else:
+                    logger.warning(
+                        "Failed to allocate memory, consider increasing the "
+                        "`nixl_buffer_size` value"
+                    )
+                break
+
+            obj_list.append(obj)
+            mem_indices.append(obj.meta.address)
+            storage_indices.append(metadata.index)
+
+        if not mem_indices:
+            return obj_list
+
+        handle = self.agent.get_storage_to_mem_handle(mem_indices, storage_indices)
+        self.agent.post_blocking(handle)
+        self.agent.release_handle(handle)
+
+        return obj_list
+
+    async def storage_to_mem(
+        self, keys: list[CacheEngineKey]
+    ) -> list[Optional[MemoryObj]]:
+        """
+        Combined method: collect metadata with lock, then do NIXL transfer.
+        """
+        metadata_list = self._collect_metadata_with_lock(keys)
+        return await self._nixl_transfer_async(metadata_list)
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """
+        Check whether key is in the storage backend.
+
+        :param key: The key to check
+        :param pin: Whether to pin the object in the backend.
+
+        :return: True if the key exists, False otherwise
+        """
+        if self.exists_in_put_tasks(key):
+            return False
+
+        with self.key_lock:
+            if key in self.key_dict:
+                if pin:
+                    self.key_dict[key].pin()
+                return True
+            else:
+                return False
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """
+        Check whether key is in the ongoing submit_put_task tasks.
+
+        :param key: The key to check
+        :return: True if the key exists in put tasks, False otherwise
+        """
+        with self.progress_lock:
+            return key in self.progress_set
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        :param on_complete_callback: Optional callback (not yet supported for
+            NixlCacheBackend async operations).
+        """
+        # contains() reports in-flight puts as absent, so the store path can
+        # re-submit a key whose put is still running.
+        with self.key_lock, self.progress_lock:
+            if not self.progress_set.isdisjoint(keys):
+                kept_keys = []
+                kept_objs = []
+                for key, obj in zip(keys, memory_objs, strict=False):
+                    if key not in self.progress_set:
+                        kept_keys.append(key)
+                        kept_objs.append(obj)
+                if not kept_keys:
+                    return
+                keys, memory_objs = kept_keys, kept_objs
+
+            available_descs = self.pool.get_num_available_descs()
+            num_evict = len(keys) - available_descs
+            if num_evict > 0:
+                evict_keys = self.cache_policy.get_evict_candidates(
+                    self.key_dict, num_candidates=num_evict
+                )
+
+                if not evict_keys:
+                    logger.warning(
+                        "No eviction candidates found. Backend under pressure."
+                    )
+                    return None
+
+                self.batched_remove(evict_keys, force=False)
+
+            self.progress_set.update(keys)
+
+        asyncio.run_coroutine_threadsafe(
+            self.mem_to_storage(keys, memory_objs), self.loop
+        )
+        # TODO: Add callback support for async NIXL operations
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """
+        A blocking function to get the kv cache from the storage backend.
+
+        :param key: The key of the MemoryObj.
+
+        :return: MemoryObj. None if the key does not exist.
+        """
+
+        future = asyncio.run_coroutine_threadsafe(self.storage_to_mem([key]), self.loop)
+
+        obj_list = future.result()
+        return obj_list[0] if obj_list else None
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """
+        A blocking function to get the kv cache from the storage backend.
+
+        :param List[CacheEngineKey] keys: The keys of the MemoryObjs.
+
+        :return: a list of memory objects.
+        """
+
+        if not keys:
+            return []
+
+        future = asyncio.run_coroutine_threadsafe(self.storage_to_mem(keys), self.loop)
+
+        obj_list = future.result()
+        return obj_list
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        obj_list = await self.storage_to_mem(keys)
+        for i, obj in enumerate(obj_list):
+            if obj is None:
+                for tail_obj in obj_list[i + 1 :]:
+                    if tail_obj is not None:
+                        tail_obj.ref_count_down()
+                return cast(list[MemoryObj], obj_list[:i])
+        return cast(list[MemoryObj], obj_list)
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        """
+        Remove the key from the storage backend.
+
+        :param key: The key to remove.
+        """
+
+        with self.key_lock:
+            metadata = self.key_dict.pop(key, None)
+            if metadata is None:
+                return False
+            if force:
+                self.cache_policy.update_on_force_evict(key)
+
+        self.pool.push(metadata.index)
+        return True
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        with self.key_lock:
+            if key in self.key_dict:
+                self.key_dict[key].pin()
+                return True
+            else:
+                return False
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        with self.key_lock:
+            if key in self.key_dict:
+                self.key_dict[key].unpin()
+                return True
+            else:
+                return False
+
+    def close(self) -> None:
+        """
+        Close the storage backend.
+        """
+        if self.agent is not None:
+            self.agent.close()
+        self.pool.close()
+        # In CPU mode the allocator is owned by LocalCPUBackend; do not close it here.
+        if self._local_cpu_backend is None and self.memory_allocator is not None:
+            self.memory_allocator.close()
+
+        if self.free_pinned_buffer:
+            _free_cpu_memory(
+                self.buffer, self.buffer_size, use_hugepages=self.use_hugepages
+            )
+
+
+class NixlDynamicStorageBackend(NixlStorageBackend):
+    def __init__(
+        self,
+        nixl_config: NixlStorageConfig,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: Optional["LocalCPUBackend"] = None,
+        cache_policy: Optional[PresenceCache] = None,
+    ) -> None:
+        super().__init__(nixl_config, config, metadata, loop, local_cpu_backend)
+
+        self.async_mode = nixl_config.enable_async_put
+        self.enable_presence_cache = nixl_config.enable_presence_cache
+        self.presence_cache_only = nixl_config.presence_cache_only
+        # The dynamic backend uses ``self.path`` directly as a single directory
+        # (see ``_build_descs``/``key_exists``). Path sharding across multiple
+        # paths is only supported for static pools via ``PathSharder``, so reject
+        # a list here rather than silently mishandling it later.
+        if isinstance(nixl_config.path, list):
+            raise ValueError(
+                "NixlDynamicStorageBackend (nixl_pool_size=0) does not support "
+                "multiple nixl_path entries; provide a single path string. "
+                "Path sharding across multiple paths is only available for "
+                "static pools."
+            )
+        self.path: str = nixl_config.path
+        self.direct_io_flag = 0
+        if nixl_config.use_direct_io:
+            if hasattr(os, "O_DIRECT"):
+                self.direct_io_flag = os.O_DIRECT
+            else:
+                logger.warning(
+                    "use_direct_io is True, but O_DIRECT is not available on "
+                    "this system. Falling back to buffered I/O."
+                )
+        # DOCA_MEMOS needs object names that fit into 128 bits; other OBJ
+        # backends use URL-safe names. See _format_object_key.
+        self._use_b128_object_keys = nixl_config.backend == "DOCA_MEMOS"
+        # Presence cache to reduce query_memory contains checks
+        self.hit_counter = 0
+        self.total_counter = 0
+        self.key_presence_cache: Optional[PresenceCache] = None
+        if self.enable_presence_cache:
+            self.key_presence_cache = (
+                cache_policy if cache_policy is not None else SetPresenceCache()
+            )
+
+        # Initialize metadata from config
+        self.meta_shape: Optional[torch.Size] = None
+        self.meta_dtype: Optional[torch.dtype] = None
+        self.meta_fmt: Optional[MemoryFormat] = None
+        self.init_chunk_meta(metadata)
+
+        # Monotonically increasing counter for OBJ device_id values.
+        # Each register/deregister cycle must use globally unique IDs to
+        # avoid a race where an async PUT deregister erases a concurrent
+        # GET registration in NIXL's devIdToObjKey_ map.
+        self._device_id_counter = 0
+        self._device_id_lock = threading.Lock()
+
+        # In CPU mode self.memory_allocator was set by the base __init__
+        # (from local_cpu_backend); in GPU mode it was allocated there too.
+        # Either way it is ready here.
+        self.agent: NixlDynamicStorageAgent = NixlDynamicStorageAgent(
+            self.memory_allocator,
+            nixl_config.buffer_device,
+            nixl_config.backend,
+            nixl_config.backend_params,
+            nixl_config.enable_prog_thread,
+            nixl_config.sync_mode,
+        )
+
+    def set_presence_cache(self, cache: PresenceCache) -> None:
+        """Configure a custom cache policy for key presence tracking."""
+        if self.enable_presence_cache:
+            self.key_presence_cache = cache
+
+    def _alloc_device_ids(self, count: int) -> list[int]:
+        """Allocate ``count`` globally unique OBJ device_id values.
+
+        The NIXL OBJ backend indexes registrations by device_id in a flat
+        unordered_map with no reference counting.  If two concurrent
+        operations (e.g. async PUT cleanup + sync GET) use the same
+        device_id sequence (0, 1, 2, ...), the PUT deregister can erase
+        the GET entry and cause ``prepXfer``/``postXfer`` to fail with
+        NIXL_ERR_INVALID_PARAM.  Using a monotonic counter ensures every
+        register/deregister cycle gets its own ID range.
+        """
+        with self._device_id_lock:
+            start = self._device_id_counter
+            self._device_id_counter += count
+        return list(range(start, start + count))
+
+    def _cache_contains(self, chunk_hash: int) -> bool:
+        if not self.enable_presence_cache or self.key_presence_cache is None:
+            return False
+        found = self.key_presence_cache.contains(chunk_hash)
+        self.hit_counter += 1 if found else 0
+        self.total_counter += 1
+        if self.total_counter % 100 == 0:
+            logger.debug(f"Cache hit: {self.hit_counter} vs {self.total_counter}")
+        return found
+
+    def _cache_add(self, chunk_hash: int) -> None:
+        if not self.enable_presence_cache or self.key_presence_cache is None:
+            return
+        self.key_presence_cache.add(chunk_hash)
+
+    def _cache_discard(self, chunk_hash: int) -> None:
+        if not self.enable_presence_cache or self.key_presence_cache is None:
+            return
+        self.key_presence_cache.discard(chunk_hash)
+
+    def init_chunk_meta(
+        self,
+        metadata: Optional[LMCacheMetadata],
+    ) -> None:
+        """Initialize chunk metadata similar to base_connector.init_chunk_meta()"""
+        if metadata is None:
+            return
+
+        self.meta_shape = torch.Size(
+            [
+                metadata.kv_shape[1],
+                metadata.kv_shape[0],
+                metadata.kv_shape[2],
+                metadata.kv_shape[3] * metadata.kv_shape[4],
+            ]
+        )
+        self.meta_dtype = metadata.kv_dtype
+        self.meta_fmt = (
+            MemoryFormat.KV_MLA_FMT if metadata.use_mla else MemoryFormat.KV_2LTD
+        )
+        logger.info(
+            f"Initialized nixl object backend metadata: "
+            f"shape: {self.meta_shape}, "
+            f"dtype: {self.meta_dtype}, "
+            f"fmt: {self.meta_fmt}"
+        )
+
+    def _format_object_key(self, key: CacheEngineKey) -> str:
+        """Format the NIXL object name for ``key`` per the configured backend."""
+        if self._use_b128_object_keys:
+            return self._format_object_key_b128(key)
+        return self._format_object_key_url_safe(key)
+
+    def _format_object_key_b128(self, key: CacheEngineKey) -> str:
+        """
+        Generate a 128-bit object key for the DOCA_MEMOS backend.
+
+        Returns a 32-char hex string (sha256 truncated to 128 bits). Hex encoding
+        is required because the key is passed via NIXL metadata as a string; the
+        NIXL plugin hex-decodes it on the other side.
+        """
+        return hashlib.sha256(key.to_string().encode("utf-8")).hexdigest()[:32]
+
+    def _format_object_key_url_safe(self, key: CacheEngineKey) -> str:
+        """
+        Generate a URL-safe object key for non-DOCA_MEMOS backends.
+
+        Replaces slashes and @ signs with underscores, then percent-encodes
+        the result for safe use as an object storage key.
+        """
+        key_str = key.to_string()
+        # Replace slashes with underscores to make it safe for object storage/FS
+        flat_key_str = key_str.replace("/", "_").replace("@", "_")
+        # URL encode for safety
+        return url_quote(flat_key_str, safe="")
+
+    def _build_descs(
+        self, keys: Sequence[CacheEngineKey], *, write: bool
+    ) -> List[NixlDesc]:
+        """
+        Build NixlDescs for ``keys``. For FILE backends this opens one fd per
+        key; the caller owns FD lifetime once this method returns successfully.
+        On mid-loop failure, every already-opened fd is closed before the exception
+        is re-raised (for write paths, files are also unlinked).
+
+        :param write: If True, opens with O_CREAT | O_RDWR (mem_to_storage).
+            If False, opens with O_RDONLY (storage_to_mem).
+        """
+        if self.agent.mem_type == "OBJ":
+            device_ids = self._alloc_device_ids(len(keys))
+            return [
+                NixlDesc(device_id=device_ids[i], meta_info=self._format_object_key(k))
+                for i, k in enumerate(keys)
+            ]
+        if self.agent.mem_type == "FILE":
+            flags = (os.O_CREAT | os.O_RDWR) if write else os.O_RDONLY
+            flags |= self.direct_io_flag
+            mode_args = (DEFAULT_FILE_CREATE_MODE,) if write else ()
+            descs: List[NixlDesc] = []
+            try:
+                for k in keys:
+                    path = os.path.join(self.path, self._format_object_key(k))
+                    fd = os.open(path, flags, *mode_args)
+                    descs.append(
+                        NixlDesc(
+                            device_id=fd,
+                            meta_info="",
+                            path=path if write else None,
+                        )
+                    )
+                return descs
+            except OSError:
+                _close_file_descs(descs)
+                _unlink_file_descs(descs)
+                raise
+        # Already validated in validate_nixl_backend
+        raise ValueError(f"unexpected mem_type: {self.agent.mem_type}")
+
+    def _acquire_storage_handle(
+        self,
+        keys: Sequence[CacheEngineKey],
+        mem_indices: List[int],
+        storage_indices: Sequence[int],
+        page_size: int,
+        write: bool,
+    ) -> Tuple[
+        List[NixlDesc],
+        nixlBind.nixlRegDList,
+        NixlDlistHandle,
+        NixlXferHandle,
+    ]:
+        """Open FDs, register the storage handler, and build the transfer handle.
+
+        On any failure, releases everything already acquired (FDs, NIXL
+        state, and any FILE-write files created with ``O_CREAT``) before
+        re-raising, so the caller either gets a fully-acquired tuple or
+        an exception with nothing leaked.
+        """
+        descs = self._build_descs(keys, write=write)
+        try:
+            reg_descs, xfer_handler = self.agent.create_batched_storage_handler(
+                descs, page_size
+            )
+        except Exception:
+            if self.agent.mem_type == "FILE":
+                _close_file_descs(descs)
+                _unlink_file_descs(descs)
+            raise
+
+        try:
+            if write:
+                handle = self.agent.get_mem_to_storage_handle(
+                    mem_indices, xfer_handler, storage_indices
+                )
+            else:
+                handle = self.agent.get_storage_to_mem_handle(
+                    mem_indices, xfer_handler, storage_indices
+                )
+        except Exception:
+            # release_storage_handler closes the FDs and releases the dlist.
+            self.agent.release_storage_handler(reg_descs, xfer_handler, descs)
+            if self.agent.mem_type == "FILE":
+                _unlink_file_descs(descs)
+            raise
+
+        return descs, reg_descs, xfer_handler, handle
+
+    def key_exists(self, key: CacheEngineKey) -> bool:
+        meta_info = self._format_object_key(key)
+
+        return self.agent.nixl_desc_exists(meta_info, self.path)
+
+    def _allocate_for_read(
+        self, keys: Sequence[CacheEngineKey]
+    ) -> Tuple[Optional[List[MemoryObj]], List[int], List[int]]:
+        """Allocate one MemoryObj per key.
+
+        Returns ``(None, [], [])`` if any allocation fails, after freeing
+        what was already taken; otherwise returns the allocated objects
+        and the parallel mem/storage index lists.
+        """
+        assert self.meta_shape is not None
+        assert self.meta_dtype is not None
+        assert self.meta_fmt is not None
+        obj_list: List[MemoryObj] = []
+        mem_indices: List[int] = []
+        storage_indices: List[int] = []
+        for idx in range(len(keys)):
+            if self._local_cpu_backend is not None:
+                obj = self._local_cpu_backend.allocate(
+                    self.meta_shape,
+                    self.meta_dtype,
+                    self.meta_fmt,
+                    eviction=True,
+                    busy_loop=False,
+                )
+            else:
+                obj = self.memory_allocator.allocate(
+                    self.meta_shape, self.meta_dtype, self.meta_fmt
+                )
+            if obj is None:
+                if self._local_cpu_backend is not None:
+                    logger.warning(
+                        "Failed to allocate from the NIXL/LocalCPUBackend "
+                        "shared pool — all pages are pinned. Consider "
+                        "increasing `max_local_cpu_size`."
+                    )
+                else:
+                    logger.warning(
+                        "Failed to allocate memory, consider increasing the "
+                        "`nixl_buffer_size` value"
+                    )
+                for obj in obj_list:
+                    if obj is not None:
+                        obj.ref_count_down()
+                return None, [], []
+            obj_list.append(obj)
+            mem_indices.append(obj.meta.address)
+            storage_indices.append(idx)
+        return obj_list, mem_indices, storage_indices
+
+    def storage_to_mem(
+        self, keys: list[CacheEngineKey], pin: bool = False
+    ) -> list[Optional[MemoryObj]]:
+        page_size = self.memory_allocator.align_bytes
+        start_time = time.time()
+
+        obj_list, mem_indices, storage_indices = self._allocate_for_read(keys)
+        if obj_list is None:
+            return [None] * len(keys)
+
+        try:
+            descs, reg_descs, xfer_handler, handle = self._acquire_storage_handle(
+                keys, mem_indices, storage_indices, page_size, write=False
+            )
+        except FileNotFoundError:
+            # FILE backend: at least one key's file does not exist,
+            # treat the whole batch as a miss.
+            logger.warning("storage_to_mem: missing file in FILE backend")
+            for obj in obj_list:
+                if obj is not None:
+                    obj.ref_count_down()
+            for key in keys:
+                self._cache_discard(key.chunk_hash)
+            return [None] * len(keys)
+
+        try:
+            try:
+                self.agent.post_blocking(handle)
+                xfer_state = True
+            except nixlBind.nixlBackendError as exc:
+                logger.warning(f"Batch Transfer failed: {exc}")
+                # Treat transfer failures (not found, timeout, etc.) as a
+                # miss rather than raising and terminating the program.
+                xfer_state = False
+            finally:
+                self.agent.release_handle(handle)
+                self.agent.release_storage_handler(reg_descs, xfer_handler, descs)
+        except Exception:
+            # Acquisition or transfer raised; return the allocated MemoryObj
+            # slots to the allocator so they aren't leaked.
+            for obj in obj_list:
+                if obj is not None:
+                    obj.ref_count_down()
+            raise
+
+        if not xfer_state:
+            for obj in obj_list:
+                if obj is not None:
+                    obj.ref_count_down()
+            for key in keys:
+                self._cache_discard(key.chunk_hash)
+            return [None] * len(keys)
+
+        for key in keys:
+            self._cache_add(key.chunk_hash)
+        duration = time.time() - start_time
+        logger.debug(
+            f"storage_to_mem for {len(keys)} objects size "
+            f"{page_size * len(keys)} took {duration:.6f} seconds"
+        )
+        return cast(list[Optional[MemoryObj]], obj_list)
+
+    async def _wait_for_transfer(
+        self,
+        handle: NixlXferHandle,
+        initial_state: str,
+        keys: Sequence[CacheEngineKey],
+        storage_reg_descs: nixlBind.nixlRegDList,
+        storage_xfer_handler: NixlDlistHandle,
+        descs: List[NixlDesc],
+        mem_objs: List[MemoryObj],
+    ):
+        """Asynchronously wait for transfer to complete without blocking.
+
+        On any non-DONE outcome (``ERR`` or earlier exception), unlink any
+        FILE-write files just created at the final key path so that
+        ``contains()`` does not observe them as bogus hits.
+        """
+        state = ""
+        try:
+            state = initial_state
+            while state != "DONE" and state != "ERR":
+                state = self.agent.nixl_agent.check_xfer_state(handle)
+                await asyncio.sleep(0.001)  # Avoid busy-waiting, yield to event loop
+            if state == "ERR":
+                raise RuntimeError("NIXL transfer failed")
+
+        finally:
+            # Release the handle after transfer completes (success or failure)
+            self.agent.release_handle(handle)
+            self.agent.release_storage_handler(
+                storage_reg_descs, storage_xfer_handler, descs
+            )
+
+            if state == "DONE":
+                for key in keys:
+                    with self.progress_lock:
+                        self.progress_set.discard(key)
+                    self._cache_add(key.chunk_hash)
+            elif self.agent.mem_type == "FILE":
+                _unlink_file_descs(descs)
+
+            for mem_obj in mem_objs:
+                mem_obj.ref_count_down()
+
+    async def mem_to_storage(
+        self, keys: Sequence[CacheEngineKey], mem_objs: List[MemoryObj]
+    ) -> None:
+        if not keys:
+            return
+
+        page_size = self.memory_allocator.align_bytes
+        storage_indices = range(len(keys))
+        mem_indices = [mem_obj.meta.address for mem_obj in mem_objs]
+
+        descs, reg_descs, xfer_handler, handle = self._acquire_storage_handle(
+            keys, mem_indices, storage_indices, page_size, write=True
+        )
+
+        if self.async_mode:
+            self._submit_async_mem_to_storage(
+                handle, keys, reg_descs, xfer_handler, descs, mem_objs
+            )
+        else:
+            self._run_sync_mem_to_storage(
+                handle, keys, reg_descs, xfer_handler, descs, page_size
+            )
+
+    def _submit_async_mem_to_storage(
+        self,
+        handle: NixlXferHandle,
+        keys: Sequence[CacheEngineKey],
+        reg_descs: nixlBind.nixlRegDList,
+        xfer_handler: NixlDlistHandle,
+        descs: List[NixlDesc],
+        mem_objs: List[MemoryObj],
+    ) -> None:
+        """Post the transfer and hand cleanup off to a background task.
+
+        On any failure before the task is scheduled, ownership has not
+        transferred, so we release everything ourselves -- including any
+        FILE-write files just created at the final key path.
+        """
+        try:
+            initial_state = self.agent.post_async(handle)
+            asyncio.create_task(
+                self._wait_for_transfer(
+                    handle,
+                    initial_state,
+                    keys,
+                    reg_descs,
+                    xfer_handler,
+                    descs,
+                    mem_objs,
+                )
+            )
+        except Exception:
+            self.agent.release_handle(handle)
+            self.agent.release_storage_handler(reg_descs, xfer_handler, descs)
+            if self.agent.mem_type == "FILE":
+                _unlink_file_descs(descs)
+            raise
+
+    def _run_sync_mem_to_storage(
+        self,
+        handle: NixlXferHandle,
+        keys: Sequence[CacheEngineKey],
+        reg_descs: nixlBind.nixlRegDList,
+        xfer_handler: NixlDlistHandle,
+        descs: List[NixlDesc],
+        page_size: int,
+    ) -> None:
+        start_time = time.time()
+        try:
+            self.agent.post_blocking(handle)
+        except Exception:
+            if self.agent.mem_type == "FILE":
+                _unlink_file_descs(descs)
+            raise
+        finally:
+            self.agent.release_handle(handle)
+            self.agent.release_storage_handler(reg_descs, xfer_handler, descs)
+
+        duration = time.time() - start_time
+        logger.debug(
+            f"mem_to_storage for {len(keys)} objects size "
+            f"{page_size * len(keys)} took {duration:.3f} seconds"
+        )
+        for key in keys:
+            with self.progress_lock:
+                self.progress_set.discard(key)
+            self._cache_add(key.chunk_hash)
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """
+        Check whether key is in the ongoing submit_put_task tasks.
+
+        :param key: The key to check
+        :return: True if the key exists in put tasks, False otherwise
+        """
+        with self.progress_lock:
+            return key in self.progress_set
+
+    def _exists_in_put_tasks_or_cache(self, key: CacheEngineKey) -> tuple[bool, bool]:
+        """Check whether key exists in put tasks or presence cache.
+
+        This method only checks the local data structures and does not
+        call the expensive key_exists operation.
+
+        :param key: The key to check
+        :return: Tuple of (found, result) where:
+                - found: True if we determined the result locally
+                - result: True if key exists, False if key doesn't exist
+                  (in put tasks)
+        """
+        # Check if already in progress
+        if self.exists_in_put_tasks(key):
+            logger.debug(f"Key {key.chunk_hash:x} is in put tasks")
+            return True, False
+
+        # Check presence cache before issuing a query_memory call if not prefetching
+        if self._cache_contains(key.chunk_hash):
+            return True, True
+
+        return False, False
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """
+        Check whether key is in the storage backend.
+
+        Normally this checks local put-task state and the presence cache, then
+        falls back to a NIXL ``query_memory`` (queryMem) call for keys not known
+        locally; a hit from that call is added to the presence cache.
+
+        When ``presence_cache_only`` is enabled (the ``nixl_presence_cache_only``
+        config option), local put-task state and the presence cache are treated
+        as authoritative: a key not known locally reports a miss and the queryMem
+        call is skipped (DRAM-only metadata semantics).
+
+        :param key: The key to check
+        :param pin: Whether to pin the object in the backend
+            (Not Implemented)
+
+        :return: True if the key exists, False otherwise
+        """
+        # Check local data structures first
+        found, local_result = self._exists_in_put_tasks_or_cache(key)
+        if found:
+            return local_result
+
+        if self.presence_cache_only:
+            return False
+
+        xfer_state = self.key_exists(key)
+        if xfer_state:
+            self._cache_add(key.chunk_hash)
+
+        return xfer_state
+
+    def batched_contains(
+        self,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Check whether the keys are in the storage backend.
+
+        Overrides the sequential base-class implementation to issue a
+        single batched ``query_memory`` call for the keys that cannot
+        be resolved from local data structures (put-task set and
+        presence cache).
+
+        When ``presence_cache_only`` is enabled (the ``nixl_presence_cache_only``
+        config option), the batched queryMem call is skipped: the method returns
+        the count of leading keys resolved from local data structures and treats
+        the first locally-unknown key as a miss (DRAM-only metadata semantics).
+
+        :param List[CacheEngineKey] keys: The keys of the MemoryObj.
+        :param bool pin: Whether to pin the key (not implemented).
+        :return: Number of contiguous hit chunks from the start of *keys*.
+        :raises: No exceptions are raised. Errors from the underlying
+            NIXL batched query are caught internally and logged as
+            warnings.
+        """
+        if not keys:
+            return 0
+
+        # First, do fast sequential check of local data structures
+        true_count = 0
+        for key in keys:
+            found, result = self._exists_in_put_tasks_or_cache(key)
+            if found:
+                if result:
+                    true_count += 1
+                else:
+                    # Found in put tasks (False), stop the loop
+                    return true_count
+            else:
+                # Not found locally, break to do expensive checks
+                break
+
+        # If we checked all keys locally, return the count
+        if true_count == len(keys):
+            return true_count
+
+        # DRAM-only metadata semantics: keys not already in the presence cache
+        # are treated as misses without issuing a query_memory call.
+        if self.presence_cache_only:
+            return true_count
+
+        # For remaining keys, use the new batched_nixl_desc_exists method
+        remaining_keys = keys[true_count:]
+        reg_list = [(0, 0, 0, self._format_object_key(key)) for key in remaining_keys]
+
+        # Use the agent's batched_nixl_desc_exists method
+        consecutive_hits = self.agent.batched_nixl_desc_exists(reg_list, self.path)
+
+        # Update cache for the hits and return total count
+        for i in range(consecutive_hits):
+            self._cache_add(remaining_keys[i].chunk_hash)
+
+        return true_count + consecutive_hits
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        if not keys:
+            return 0
+        """
+        Nixl API query_memory also supports batched query. However when there
+        are hundreds of keys to be queried and keys in the first few places
+        don't exist, the batched query has to be failed fast.
+        Therefore we implement batched contains() in a managed thread pool,
+        which fails fast when a key doesn't exist.
+        """
+        n = len(keys)
+        idx = 0
+        batch_size = _CONTAINS_BATCH_SIZE
+
+        while idx < n:
+            batch = keys[idx : idx + batch_size]
+            tasks = [asyncio.to_thread(self.contains, k, pin) for k in batch]
+            results = await asyncio.gather(*tasks, return_exceptions=False)
+
+            # Stop at the first miss
+            for j, ok in enumerate(results):
+                if not ok:
+                    return idx + j
+            idx += len(batch)
+
+        return n
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        :param on_complete_callback: Optional callback invoked once per key
+            after transfer completes. Only supported in sync mode (async_mode=False).
+        """
+        with self.progress_lock:
+            for key in keys:
+                self.progress_set.add(key)
+
+        if self.async_mode:
+            for mem_obj in memory_objs:
+                mem_obj.ref_count_up()
+            asyncio.run_coroutine_threadsafe(
+                self.mem_to_storage(keys, memory_objs), self.loop
+            )
+            # Note: callback not supported in async mode
+        else:
+            future = asyncio.run_coroutine_threadsafe(
+                self.mem_to_storage(keys, memory_objs), self.loop
+            )
+            future.result()
+
+            # Call completion callback for sync mode
+            if on_complete_callback is not None:
+                for key in keys:
+                    try:
+                        on_complete_callback(key)
+                    except Exception as e:
+                        logger.warning(
+                            f"on_complete_callback failed for key {key}: {e}"
+                        )
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """
+        A blocking function to get the kv cache from the storage backend.
+
+        :param key: The key of the MemoryObj.
+
+        :return: MemoryObj. None if the key does not exist.
+        """
+        obj_list = self.storage_to_mem([key], False)
+        return obj_list[0]
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """
+        A blocking function to get the kv cache from the storage backend.
+        :param List[CacheEngineKey] keys: The keys of the MemoryObjs.
+        :return: a list of memory objects.
+        """
+        if not keys:
+            return []
+
+        obj_list = self.storage_to_mem(keys, False)
+        return obj_list
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        """
+        Non blocking interface to get the kv cache from the storage backend.
+        :param List[CacheEngineKey] keys: The keys of the MemoryObjs.
+        :return: a list of memory objects.
+        """
+        obj_list = self.storage_to_mem(keys, False)
+        for i, obj in enumerate(obj_list):
+            if obj is None:
+                for tail_obj in obj_list[i + 1 :]:
+                    if tail_obj is not None:
+                        tail_obj.ref_count_down()
+                return cast(list[MemoryObj], obj_list[:i])
+        return cast(list[MemoryObj], obj_list)
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        """
+        Remove the key from the storage backend.
+
+        :param key: The key to remove.
+        :param force: Whether to force removal (not used in this implementation)
+        :return: True if the key is removed, False otherwise.
+        """
+        self._cache_discard(key.chunk_hash)
+        if self.agent.mem_type == "FILE":
+            try:
+                os.unlink(os.path.join(self.path, self._format_object_key(key)))
+            except FileNotFoundError:
+                return False
+
+        return True
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        """
+        Not implemented yet
+        """
+        return False
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        """
+        Not implemented yet
+        """
+        return False
+
+    def close(self) -> None:
+        """
+        Close the storage backend.
+        """
+        if self.agent is not None:
+            self.agent.close()
+        # In CPU mode the allocator is owned by LocalCPUBackend; do not close it here.
+        if self._local_cpu_backend is None and self.memory_allocator is not None:
+            self.memory_allocator.close()
+
+        if self.free_pinned_buffer:
+            _free_cpu_memory(
+                self.buffer, self.buffer_size, use_hugepages=self.use_hugepages
+            )
diff --git a/lmcache/v1/storage_backend/p2p_backend.py b/lmcache/v1/storage_backend/p2p_backend.py
new file mode 100644
index 0000000..4f17286
--- /dev/null
+++ b/lmcache/v1/storage_backend/p2p_backend.py
@@ -0,0 +1,790 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable, List, Optional, Sequence, Union
+import asyncio
+import enum
+
+# Third Party
+import msgspec
+import torch
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.cache_controller.message import (
+    BatchedP2PLookupMsg,
+    BatchedP2PLookupRetMsg,
+    ErrorMsg,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.paged_cpu_gpu_memory_allocator import (
+    PagedCpuGpuMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc_utils import (
+    DEFAULT_SOCKET_RECV_TIMEOUT_MS,
+    DEFAULT_SOCKET_SEND_TIMEOUT_MS,
+    get_zmq_context,
+    get_zmq_socket_with_timeout,
+)
+from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.transfer_channel import CreateTransferChannel
+from lmcache.v1.transfer_channel.transfer_utils import (
+    P2PInitSideMsg,
+    P2PInitSideRetMsg,
+)
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller import LMCacheWorker
+
+logger = init_logger(__name__)
+
+
+class P2PMsgBase(msgspec.Struct, tag=True):
+    """Base class for all P2P-related messages"""
+
+    pass
+
+
+class BatchedLookupAndGetMsg(P2PMsgBase):
+    """Lookup and retrieve message"""
+
+    lookup_id: str
+
+    receiver_id: str
+
+    # CacheEngineKey in string form
+    keys: list[str]
+
+    # Indexes (remote) of allocated memory objects (to be written)
+    mem_indexes: list[int]
+
+
+class BatchedLookupAndGetRetMsg(P2PMsgBase):
+    """Lookup and retrieve message"""
+
+    # Number of hit chunks
+    num_hit_chunks: int
+
+
+class BatchedLookupAndPutMsg(P2PMsgBase):
+    """Lookup and retrieve message"""
+
+    sender_id: str
+
+    # CacheEngineKey in string form
+    keys: list[str]
+
+    # Number of tokens for each chunk
+    offsets: list[int]
+
+    # Indexes (remote) of allocated memory objects (to be read)
+    mem_indexes: list[int]
+
+
+class BatchedLookupAndPutRetMsg(P2PMsgBase):
+    """Lookup and retrieve message"""
+
+    # Number of read chunks
+    num_read_chunks: int
+
+
+class P2PErrorCode(enum.Enum):
+    """P2P error codes enumeration"""
+
+    P2P_SERVER_ERROR = enum.auto()
+    UNKNOWN_MSG_TYPE = enum.auto()
+    REMOTE_XFER_HANDLER_NOT_INITIALIZED = enum.auto()
+
+
+class P2PErrorMsg(P2PMsgBase):
+    """
+    Error message, return error code to client.
+
+    -1 represents unknown msg type;
+    -2 represents remote xfer handler not initialized,
+        call `_ensure_peer_connection` first;
+    -3 represents p2p peer_request_handler error;
+    """
+
+    error_code: P2PErrorCode
+
+
+P2PMsg = Union[
+    BatchedLookupAndGetMsg,
+    BatchedLookupAndGetRetMsg,
+    BatchedLookupAndPutMsg,
+    BatchedLookupAndPutRetMsg,
+    P2PErrorMsg,
+]
+
+
+@dataclass
+class PeerInfo:
+    """Peer information"""
+
+    peer_init_url: str  # peer id
+    peer_lookup_url: str
+    lookup_lock: asyncio.Lock
+    lookup_socket: zmq.asyncio.Socket
+
+    def update_peer_lookup_url(self, new_peer_lookup_url: str):
+        if self.peer_lookup_url != new_peer_lookup_url:
+            logger.info(
+                "Target peer %s lookup url changed from %s to %s",
+                self.peer_init_url,
+                self.peer_lookup_url,
+                new_peer_lookup_url,
+            )
+            self.peer_lookup_url = new_peer_lookup_url
+
+    def update_lookup_socket(self, new_lookup_socket: zmq.asyncio.Socket):
+        try:
+            self.lookup_socket.close(linger=0)
+        except Exception as e:
+            logger.error("Failed to close peer %s lookup socket", self.peer_init_url, e)
+        self.lookup_socket = new_lookup_socket
+
+
+# TODO(Jiayi): handle asymmetric TP.
+class P2PBackend(StorageBackendInterface):
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        lmcache_worker: "LMCacheWorker",
+    ):
+        self.config = config
+        self.loop = loop
+        self.lmcache_worker = lmcache_worker
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+        assert config.p2p_host is not None, "p2p_host must be specified"
+        assert config.p2p_init_ports is not None, "p2p_init_ports must be specified"
+        assert config.p2p_lookup_ports is not None, "p2p_lookup_ports must be specified"
+
+        # Load timeout configurations from extra_config (in milliseconds)
+        self.socket_recv_timeout_ms = config.get_extra_config_value(
+            "p2p_socket_recv_timeout_ms", DEFAULT_SOCKET_RECV_TIMEOUT_MS
+        )
+        self.socket_send_timeout_ms = config.get_extra_config_value(
+            "p2p_socket_send_timeout_ms", DEFAULT_SOCKET_SEND_TIMEOUT_MS
+        )
+
+        # Load max retry count from extra_config
+        self.max_retry_count = config.get_extra_config_value("p2p_max_retry_count", 3)
+
+        # tp rank is worker id for now
+        self.tp_rank = metadata.worker_id
+
+        self.peer_host = config.p2p_host
+        self.peer_init_port = config.p2p_init_ports[self.tp_rank]
+        self.peer_init_url = f"{self.peer_host}:{self.peer_init_port}"
+
+        self.peer_lookup_port = config.p2p_lookup_ports[self.tp_rank]
+        self.peer_lookup_url = f"{self.peer_host}:{self.peer_lookup_port}"
+
+        self.lmcache_instance_id = config.lmcache_instance_id
+
+        # A CacheEngineKey (in int form) -> a list of
+        # (peer_init_url, peer_lookup_url, location)
+        self.local_lookup_cache: dict[int, tuple[str, str, str]] = {}
+        # the target peer info mapping
+        self.target_peer_info_mapping: dict[str, PeerInfo] = {}
+        # the lock for updating target peer info mapping
+        self.update_peer_lock = asyncio.Lock()
+
+        # A lookup_id -> (peer_init_url, location)
+        # TODO(chunxiaozheng): location is not used for now
+        self.lookup_id_to_peer_mapping: dict[str, tuple[str, str]] = {}
+
+        # TODO(Jiayi): support gpu and local storage p2p as well.
+        self.local_cpu_backend = local_cpu_backend
+        self.memory_allocator = local_cpu_backend.get_memory_allocator()
+        assert isinstance(self.memory_allocator, PagedCpuGpuMemoryAllocator)
+
+        self.full_size_shapes = self.memory_allocator.cpu_allocator.shapes
+        self.dtypes = self.memory_allocator.cpu_allocator.dtypes
+        self.fmt: MemoryFormat = (
+            MemoryFormat.KV_MLA_FMT if metadata.use_mla else MemoryFormat.KV_2LTD
+        )
+        self.chunk_size = config.chunk_size
+
+        device_type = (
+            "cpu" if config.nixl_buffer_device is None else config.nixl_buffer_device
+        )
+        self.transfer_channel = CreateTransferChannel(
+            channel_type=config.transfer_channel,
+            async_mode=True,
+            role="both",
+            buffer_ptr=self.memory_allocator.cpu_allocator.buffer_ptr,
+            buffer_size=self.memory_allocator.cpu_allocator.buffer_size,
+            align_bytes=self.memory_allocator.cpu_allocator.align_bytes,
+            tp_rank=self.tp_rank,
+            peer_init_url=self.peer_init_url,
+            peer_lookup_url=self.peer_lookup_url,
+            backends=config.nixl_backends,
+            event_loop=loop,
+            device=device_type,
+        )
+
+        self.running = asyncio.Event()
+        self.running.set()
+        self.async_context: Optional[zmq.asyncio.Context] = None
+        self.async_peer_socket: Optional[zmq.asyncio.Socket] = None
+        asyncio.run_coroutine_threadsafe(
+            self._run_peer_request_handler_with_recovery(), loop
+        )
+
+    def __str__(self) -> str:
+        return "P2PBackend"
+
+    async def _run_peer_request_handler_with_recovery(self) -> None:
+        """
+        Wrapper method that runs _handle_peer_requests with exception handling.
+        This ensures the handler keeps running even if unexpected errors occur.
+        """
+        while self.running.is_set():
+            try:
+                await self._handle_peer_requests()
+                # If _handle_peer_requests exits normally, break the loop
+                break
+            except asyncio.CancelledError:
+                logger.info("Peer request handler cancelled, shutting down")
+                break
+            except Exception as e:
+                logger.error(
+                    "Peer request handler crashed: %s",
+                    e,
+                    exc_info=True,
+                )
+                # Fast failure: log error but continue running
+                # Add small delay to prevent tight error loop
+                await asyncio.sleep(0.1)
+                if self.async_peer_socket is not None:
+                    logger.warning("Closing async peer socket.")
+                    try:
+                        self.async_peer_socket.close(linger=0)
+                    except Exception as e:
+                        logger.warning(
+                            "Failed to close peer socket: %s",
+                            e,
+                            exc_info=True,
+                        )
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        # Convert to hashes (int form)
+        hashes = [key.chunk_hash for key in keys]
+
+        # Tier 1 lookup: local lookup cache
+        # TODO(Jiayi): Please implement the local lookup cache.
+
+        # Tier 2 lookup in controller
+        msg = BatchedP2PLookupMsg(
+            instance_id=self.lmcache_instance_id,
+            worker_id=self.tp_rank,
+            hashes=hashes,
+        )
+        ret_msg = await self.lmcache_worker.async_put_and_wait_msg(msg)
+
+        if isinstance(ret_msg, ErrorMsg):
+            logger.error(
+                "Controller returned error for batched P2P lookup: %s",
+                ret_msg.error,
+            )
+            return 0
+
+        assert isinstance(ret_msg, BatchedP2PLookupRetMsg), (
+            f"Expected BatchedP2PLookupRetMsg, got {type(ret_msg)}"
+        )
+
+        # NOTE(Jiayi): For now we only support one peer hit.
+        layout_info = ret_msg.layout_info[0]
+        _, location, num_hit_chunks, target_peer_init_url = layout_info
+
+        logger.info(f"Got layout info from controller: {layout_info}")
+
+        if num_hit_chunks > 0:
+            try:
+                await self._ensure_peer_connection(target_peer_init_url)
+                self.lookup_id_to_peer_mapping[lookup_id] = (
+                    target_peer_init_url,
+                    location,
+                )
+            except Exception as e:
+                logger.error(
+                    "Failed to ensure peer connection for lookup_id %s: %s",
+                    lookup_id,
+                    e,
+                    exc_info=True,
+                )
+                return 0
+
+        # TODO(Jiayi): We could potentially update the local cache here.
+        # Or we can update after tier 3 lookup.
+
+        # NOTE(Jiayi): Tier 3 lookup is batched together with get
+        # in function `batched_get_non_blocking`.
+
+        return num_hit_chunks
+
+    async def _handle_peer_requests(self):
+        """
+        Handle `BatchedLookupAndGetMsg` issued by peers in `batched_get_non_blocking`.
+        """
+
+        logger.info(
+            "Starting P2P backend batched get handler at %s", self.peer_lookup_url
+        )
+        self.async_context = get_zmq_context()
+        self.async_peer_socket = get_zmq_socket_with_timeout(
+            self.async_context,
+            self.peer_lookup_url,
+            "tcp",
+            zmq.REP,
+            "bind",
+            self.socket_recv_timeout_ms,
+            self.socket_send_timeout_ms,
+        )
+
+        while self.running.is_set():
+            msg_bytes = await self.async_peer_socket.recv()
+            msg = msgspec.msgpack.decode(msg_bytes, type=P2PMsg)
+
+            num_tokens = len(msg.mem_indexes) * self.chunk_size
+            monitor_req_id = self.stats_monitor.on_p2p_transfer_request(num_tokens)
+
+            if isinstance(msg, BatchedLookupAndGetMsg):
+                ret_msg = await self._handle_batched_lookup_and_get(msg)
+            elif isinstance(msg, BatchedLookupAndPutMsg):
+                ret_msg = await self._handle_batched_lookup_and_put(msg)
+            else:
+                logger.error("Unknown message type: %s", type(msg))
+                ret_msg = P2PErrorMsg(error_code=P2PErrorCode.UNKNOWN_MSG_TYPE)
+
+            logger.info(f"P2P transfer finished for request {monitor_req_id}")
+            self.stats_monitor.on_p2p_transfer_finished(monitor_req_id)
+
+            await self.async_peer_socket.send(msgspec.msgpack.encode(ret_msg))
+
+    async def _handle_batched_lookup_and_get(
+        self, msg: BatchedLookupAndGetMsg
+    ) -> P2PMsgBase:
+        lookup_id = msg.lookup_id
+        mem_objs = None
+        try:
+            logger.info(
+                "Received P2P batched lookup and get msg, lookup_id: %s", lookup_id
+            )
+            receiver_id = msg.receiver_id
+            if not self.transfer_channel.remote_xfer_handler_exists(receiver_id):
+                logger.error(
+                    "Receiver %s does not exist in transfer channel",
+                    receiver_id,
+                )
+                return P2PErrorMsg(
+                    error_code=P2PErrorCode.REMOTE_XFER_HANDLER_NOT_INITIALIZED
+                )
+
+            remote_mem_indexes = msg.mem_indexes
+            keys = [CacheEngineKey.from_string(key) for key in msg.keys]
+
+            # TODO(Jiayi): Optimally, there's no need to use async call
+            # for some backends (e.g., local cpu) as there's overhead for
+            # async function call.
+            num_hit_chunks = await self.local_cpu_backend.batched_async_contains(
+                lookup_id=lookup_id,
+                keys=keys,
+                pin=True,
+            )
+
+            mem_objs = await self.local_cpu_backend.batched_get_non_blocking(
+                lookup_id=lookup_id,
+                keys=keys[:num_hit_chunks],
+            )
+
+            channel_transfer_spec = {
+                "receiver_id": receiver_id,
+                "remote_indexes": remote_mem_indexes[:num_hit_chunks],
+            }
+            await self.transfer_channel.async_batched_write(
+                objects=mem_objs,
+                transfer_spec=channel_transfer_spec,
+            )
+
+            return BatchedLookupAndGetRetMsg(num_hit_chunks=num_hit_chunks)
+        except Exception as e:
+            logger.error(
+                "Error during P2P batched lookup and get operation "
+                "for lookup_id %s: %s",
+                lookup_id,
+                e,
+                exc_info=True,
+            )
+            return P2PErrorMsg(error_code=P2PErrorCode.P2P_SERVER_ERROR)
+        finally:
+            if mem_objs is not None:
+                for mem_obj in mem_objs:
+                    mem_obj.ref_count_down()
+                    mem_obj.unpin()
+
+    async def _handle_batched_lookup_and_put(
+        self, msg: BatchedLookupAndPutMsg
+    ) -> BatchedLookupAndPutRetMsg:
+        try:
+            logger.info("Received P2P batched lookup and put msg")
+            sender_id = msg.sender_id
+            r_mem_indexes = msg.mem_indexes
+            keys = [CacheEngineKey.from_string(key) for key in msg.keys]
+            offsets = msg.offsets
+
+            # TODO(Jiayi): Need to support more backend
+            r_mem_indexes_to_read = []
+            keys_to_read = []
+            local_mem_objs = []
+            keys_len = len(keys)
+            for idx, key in enumerate(keys):
+                if self.local_cpu_backend.contains(key, pin=False):
+                    continue
+                r_mem_indexes_to_read.append(r_mem_indexes[idx])
+                if not self.config.save_unfull_chunk or idx < keys_len - 1:
+                    shapes = self.full_size_shapes
+                else:
+                    shapes = self._get_unfull_chunk_shapes(offsets[idx])
+                local_mem_obj = self.local_cpu_backend.allocate(
+                    shapes, self.dtypes, self.fmt
+                )
+                local_mem_objs.append(local_mem_obj)
+                keys_to_read.append(key)
+
+            channel_transfer_spec = {
+                "sender_id": sender_id,
+                "remote_indexes": r_mem_indexes_to_read,
+            }
+            await self.transfer_channel.async_batched_read(
+                buffers=local_mem_objs,
+                transfer_spec=channel_transfer_spec,
+            )
+
+            self.local_cpu_backend.batched_submit_put_task(
+                keys=keys_to_read,
+                memory_objs=local_mem_objs,
+            )
+
+            return BatchedLookupAndPutRetMsg(num_read_chunks=len(local_mem_objs))
+        except Exception as e:
+            logger.error(
+                "Error during P2P batched lookup and put operation: %s",
+                e,
+                exc_info=True,
+            )
+            return BatchedLookupAndPutRetMsg(num_read_chunks=0)
+
+    async def _ensure_peer_connection(
+        self,
+        target_peer_init_url: str,
+        force_update: bool = False,
+    ) -> None:
+        if not force_update and target_peer_init_url in self.target_peer_info_mapping:
+            return
+
+        async with self.update_peer_lock:
+            # double check
+            if (
+                not force_update
+                and target_peer_init_url in self.target_peer_info_mapping
+            ):
+                return
+
+            init_side_msg = P2PInitSideMsg()
+            init_ret_msg = await self.transfer_channel.async_lazy_init_peer_connection(
+                local_id=self.peer_init_url,
+                peer_id=target_peer_init_url,
+                peer_init_url=target_peer_init_url,
+                init_side_msg=init_side_msg,
+            )
+            assert isinstance(init_ret_msg, P2PInitSideRetMsg)
+
+            peer_lookup_url = init_ret_msg.peer_lookup_url
+            peer_info = self.target_peer_info_mapping.get(target_peer_init_url, None)
+            lookup_socket = get_zmq_socket_with_timeout(
+                self.async_context,
+                peer_lookup_url,
+                "tcp",
+                zmq.REQ,
+                "connect",
+                self.socket_recv_timeout_ms,
+                self.socket_send_timeout_ms,
+            )
+            if peer_info is not None:
+                peer_info.update_peer_lookup_url(peer_lookup_url)
+                peer_info.update_lookup_socket(lookup_socket)
+            else:
+                self.target_peer_info_mapping[target_peer_init_url] = PeerInfo(
+                    peer_init_url=target_peer_init_url,
+                    peer_lookup_url=peer_lookup_url,
+                    lookup_lock=asyncio.Lock(),
+                    lookup_socket=lookup_socket,
+                )
+
+        logger.info(
+            "Established connection to peer_init_url: %s, peer_lookup_url: %s",
+            target_peer_init_url,
+            peer_lookup_url,
+        )
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        target_peer_init_url, _ = self.lookup_id_to_peer_mapping.pop(lookup_id)
+
+        assert isinstance(transfer_spec, dict)
+        cum_chunk_lengths = transfer_spec.get("cum_chunk_lengths", None)
+        assert cum_chunk_lengths is not None, "cum_chunk_lengths must be provided"
+        assert isinstance(cum_chunk_lengths, list), "cum_chunk_lengths must be a list"
+
+        mem_objs = []
+        str_keys = []
+        keys_len = len(keys)
+        for idx, key in enumerate(keys):
+            if not self.config.save_unfull_chunk or idx < keys_len - 1:
+                shapes = self.full_size_shapes
+            else:
+                shapes = self._get_unfull_chunk_shapes(
+                    cum_chunk_lengths[idx + 1] - cum_chunk_lengths[idx]
+                )
+            mem_obj = self.local_cpu_backend.allocate(shapes, self.dtypes, self.fmt)
+            mem_objs.append(mem_obj)
+            str_keys.append(key.to_string())
+
+        local_indexes = self.transfer_channel.get_local_mem_indices(mem_objs)
+
+        # NOTE(Jiayi): Tier 3 lookup is batched with retrieval.
+        msg = BatchedLookupAndGetMsg(
+            lookup_id=lookup_id,
+            receiver_id=self.peer_init_url,
+            keys=str_keys,
+            mem_indexes=local_indexes,
+        )
+
+        retry_count = 0
+        while retry_count < self.max_retry_count:
+            peer_info = self.target_peer_info_mapping[target_peer_init_url]
+            lookup_lock = peer_info.lookup_lock
+            async with lookup_lock:
+                lookup_socket = peer_info.lookup_socket
+                try:
+                    retry_count += 1
+                    await lookup_socket.send(msgspec.msgpack.encode(msg))
+                    ret_msg_bytes = await lookup_socket.recv()
+                    ret_msg = msgspec.msgpack.decode(ret_msg_bytes, type=P2PMsg)
+                    if (
+                        isinstance(ret_msg, P2PErrorMsg)
+                        and ret_msg.error_code
+                        == P2PErrorCode.REMOTE_XFER_HANDLER_NOT_INITIALIZED
+                    ):
+                        logger.warning(
+                            "Peer connection not initialized for lookup_id %s, "
+                            "ensure peer connection first, retry count: %s",
+                            lookup_id,
+                            retry_count,
+                        )
+                        await self._ensure_peer_connection(target_peer_init_url, True)
+                    else:
+                        break
+                except zmq.ZMQError as e:
+                    logger.error(
+                        "ZMQ error occurred for lookup_id %s. Error: %s",
+                        lookup_id,
+                        e,
+                    )
+                    await self._ensure_peer_connection(target_peer_init_url, True)
+                    if retry_count == self.max_retry_count:
+                        logger.error(
+                            "Max retry count reached for lookup_id %s",
+                            lookup_id,
+                        )
+                        self._cleanup_memory_objects(mem_objs)
+                        return []
+                except Exception as e:
+                    logger.error(
+                        "Error during P2P get operation for lookup_id %s: %s",
+                        lookup_id,
+                        e,
+                        exc_info=True,
+                    )
+                    self._cleanup_memory_objects(mem_objs)
+                    return []
+
+        if isinstance(ret_msg, P2PErrorMsg):
+            logger.error(
+                "P2P error for lookup_id %s, error code: %s",
+                lookup_id,
+                ret_msg.error_code,
+            )
+            num_hit_chunks = 0
+        else:
+            num_hit_chunks = ret_msg.num_hit_chunks
+
+        hit_mem_objs = mem_objs[:num_hit_chunks]
+        for hit_mem_obj in hit_mem_objs:
+            hit_mem_obj.pin()
+        for missed_mem_obj in mem_objs[num_hit_chunks:]:
+            missed_mem_obj.ref_count_down()
+        return hit_mem_objs
+
+    def _get_unfull_chunk_shapes(self, num_tokens: int) -> list[torch.Size]:
+        shapes = []
+        for shape in self.full_size_shapes:
+            shape_list = list(shape)
+            shape_list[self.fmt.token_dim()] = num_tokens
+            shapes.append(torch.Size(shape_list))
+        return shapes
+
+    # NOTE: put-related functions are not supported for now.
+    async def async_batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        # TODO(baoloongmao): Add exception handling for socket operations
+        # Code path for `move` operation in controller.
+        assert isinstance(transfer_spec, dict)
+        assert "target_peer_init_url" in transfer_spec
+        assert "offsets" in transfer_spec
+
+        target_peer_init_url = transfer_spec["target_peer_init_url"]
+        offsets = transfer_spec["offsets"]
+
+        await self._ensure_peer_connection(transfer_spec["target_peer_init_url"])
+
+        str_keys = [key.to_string() for key in keys]
+        local_indexes = self.transfer_channel.get_local_mem_indices(objs)
+
+        msg = BatchedLookupAndPutMsg(
+            sender_id=self.peer_init_url,
+            keys=str_keys,
+            offsets=offsets,
+            mem_indexes=local_indexes,
+        )
+
+        peer_info = self.target_peer_info_mapping[target_peer_init_url]
+        lookup_lock = peer_info.lookup_lock
+        async with lookup_lock:
+            lookup_socket = peer_info.lookup_socket
+            await lookup_socket.send(msgspec.msgpack.encode(msg))
+            ret_msg_bytes = await lookup_socket.recv()
+        ret_msg = msgspec.msgpack.decode(ret_msg_bytes, type=P2PMsg)
+
+        return ret_msg.num_read_chunks
+
+    def get_allocator_backend(self):
+        return self.local_cpu_backend
+
+    def _cleanup_memory_objects(self, mem_objs: list[MemoryObj]) -> None:
+        """Safely cleanup memory objects by decrementing reference counts"""
+        for mem_obj in mem_objs:
+            try:
+                mem_obj.ref_count_down()
+            except Exception as e:
+                logger.error("Error cleaning up memory object: %s", e)
+
+    def close(
+        self,
+    ) -> None:
+        """
+        Close the P2P backend and cleanup resources.
+        """
+        logger.info("Closing P2P backend")
+        self.running.clear()
+
+        # Close all lookup sockets
+        for peer_info in self.target_peer_info_mapping.values():
+            try:
+                peer_info.lookup_socket.close(linger=0)
+            except Exception as e:
+                logger.warning("Failed to close lookup socket: %s", e)
+        self.target_peer_info_mapping.clear()
+
+        # Close async peer socket
+        if self.async_peer_socket is not None:
+            try:
+                self.async_peer_socket.close(linger=0)
+            except Exception as e:
+                logger.warning("Failed to close async peer socket: %s", e)
+            self.async_peer_socket = None
+
+        # Close transfer channel
+        if hasattr(self, "transfer_channel") and self.transfer_channel is not None:
+            try:
+                self.transfer_channel.close()
+            except Exception as e:
+                logger.warning("Failed to close transfer channel: %s", e)
+
+    ############################################################
+    # Not-supported functions
+    ############################################################
+
+    # NOTE: synchronous contain is not supported for now.
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        return False
+
+    # NOTE: put-related functions are not supported for now.
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        raise NotImplementedError
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """P2P backend does not support put operations."""
+        pass
+
+    # NOTE: Synchronous get is not supported for now.
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        raise NotImplementedError
+
+    # NOTE: pin is useless for P2P backend now.
+    def pin(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        return False
+
+    # NOTE: unpin is useless for P2P backend now.
+    def unpin(
+        self,
+        key: CacheEngineKey,
+    ) -> bool:
+        return False
+
+    # NOTE: remove is useless for P2P backend now.
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        return False
diff --git a/lmcache/v1/storage_backend/path_sharder.py b/lmcache/v1/storage_backend/path_sharder.py
new file mode 100644
index 0000000..3933eb4
--- /dev/null
+++ b/lmcache/v1/storage_backend/path_sharder.py
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared path-sharding logic for multi-path storage backends.
+
+A :class:`PathSharder` takes a comma-separated list of directory paths
+and a sharding strategy, then selects a single path for the current
+worker.  Both :class:`LocalDiskBackend` and :class:`GdsBackend` delegate
+path selection to this module so the policy lives in one place.
+"""
+
+# Standard
+from typing import List
+import os
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def _resolve_device_id(dst_device: str) -> int:
+    """Derive an integer device index from *dst_device*.
+
+    Args:
+        dst_device: Device string such as ``"cuda:2"``, ``"cuda"``,
+            or ``"cpu"``.
+
+    Returns:
+        Integer device index.  Falls back to
+        :func:`torch_dev.current_device` when the string carries no
+        explicit index, or ``0`` when the accelerator is unavailable.
+    """
+    if ":" in dst_device:
+        try:
+            return int(dst_device.split(":", 1)[1])
+        except ValueError:
+            logger.warning(f"Invalid device index in '{dst_device}', falling back.")
+    if torch_dev.is_available() and dst_device != "cpu":
+        return torch_dev.current_device()
+    return 0
+
+
+class PathSharder:
+    """Select one path from a comma-separated list using a sharding policy.
+
+    Args:
+        raw_csv: Comma-separated directory paths (e.g.
+            ``"/mnt/nvme0/cache,/mnt/nvme1/cache"``).
+        strategy: Sharding strategy name.  Currently only ``"by_gpu"``
+            is supported, which selects ``paths[device_id % len(paths)]``.
+        dst_device: Device string used to derive the worker index
+            (e.g. ``"cuda:0"``, ``"cuda"``, ``"cpu"``).
+        create_dirs: If ``True``, create **all** directories in the
+            list at construction time (not just the selected one).
+
+    Raises:
+        ValueError: If *raw_csv* is empty or contains no valid paths.
+        ValueError: If *strategy* is not a supported sharding mode.
+
+    Example::
+
+        sharder = PathSharder(
+            "/mnt/nvme0/cache,/mnt/nvme1/cache",
+            strategy="by_gpu",
+            dst_device="cuda:1",
+        )
+        sharder.selected   # "/mnt/nvme1/cache"
+        sharder.all_paths  # ["/mnt/nvme0/cache", "/mnt/nvme1/cache"]
+    """
+
+    _SUPPORTED_STRATEGIES = ("by_gpu",)
+
+    def __init__(
+        self,
+        raw_csv: str,
+        strategy: str,
+        dst_device: str,
+        create_dirs: bool = False,
+    ) -> None:
+        paths = [p.strip() for p in raw_csv.split(",") if p.strip()]
+        if not paths:
+            raise ValueError("At least one path must be provided")
+
+        if strategy not in self._SUPPORTED_STRATEGIES:
+            raise ValueError(
+                f"Unsupported path sharding strategy '{strategy}'. "
+                f"Supported: {', '.join(self._SUPPORTED_STRATEGIES)}"
+            )
+
+        device_id = _resolve_device_id(dst_device)
+
+        self._all_paths: List[str] = paths
+        self._strategy: str = strategy
+        self._selected: str = paths[device_id % len(paths)]
+
+        if create_dirs:
+            for p in paths:
+                os.makedirs(p, exist_ok=True)
+
+    # -- public read-only properties -----------------------------------------
+
+    @property
+    def selected(self) -> str:
+        """The single path chosen for this worker."""
+        return self._selected
+
+    @property
+    def all_paths(self) -> List[str]:
+        """All configured paths (unmodified order)."""
+        return list(self._all_paths)
+
+    @property
+    def strategy(self) -> str:
+        """Name of the active sharding strategy."""
+        return self._strategy
diff --git a/lmcache/v1/storage_backend/pd_backend.py b/lmcache/v1/storage_backend/pd_backend.py
new file mode 100644
index 0000000..8bde3b3
--- /dev/null
+++ b/lmcache/v1/storage_backend/pd_backend.py
@@ -0,0 +1,1087 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from concurrent.futures import Future
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, Sequence, Union
+import threading
+import time
+
+# Third Party
+import msgspec
+import torch
+import zmq
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    STR_DTYPE_TO_TORCH_DTYPE,
+    TORCH_DTYPE_TO_STR_DTYPE,
+    CacheEngineKey,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.paged_cpu_gpu_memory_allocator import (
+    PagedCpuGpuMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc_utils import get_zmq_context, get_zmq_socket
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+from lmcache.v1.transfer_channel import CreateTransferChannel
+from lmcache.v1.transfer_channel.transfer_utils import get_correct_device
+
+logger = init_logger(__name__)
+
+
+class PDMsgBase(msgspec.Struct, tag=True):
+    """Base class for all PD-related messages"""
+
+    pass
+
+
+class AllocRequest(PDMsgBase):
+    """Allocation request message"""
+
+    keys: list[str]  # len(keys) indicates num_chunks
+    fmt: int
+    shape: list[int]  # The shape of the memory objects
+    dtype: str
+    last_chunk_toks: int
+
+
+class AllocResponse(PDMsgBase):
+    """Allocation response message"""
+
+    # Indexes (local) of already sent memory objects
+    already_sent_indexes: list[int]
+
+    # Indexes (remote) of allocated memory objects (to be written)
+    remote_indexes: list[int]
+
+
+class ProxyNotif(PDMsgBase):
+    req_id: str  # The request UUID to notify the proxy
+
+
+class CacheQueryRequest(PDMsgBase):
+    """Query decoder for cached block keys matching a prefix."""
+
+    keys: list[str]  # Keys to check on the decoder
+
+
+class CacheQueryResponse(PDMsgBase):
+    """Response with which keys are cached and their remote memory indices."""
+
+    cached_keys: list[str]  # Keys that exist on the decoder
+    cached_indexes: list[int]  # Remote memory indices for cached keys
+
+
+PDMsg = Union[
+    AllocRequest, AllocResponse, ProxyNotif, CacheQueryRequest, CacheQueryResponse
+]
+
+
+@dataclass
+class PDConfig:
+    role: str
+
+    peer_host: str
+    peer_init_port: int
+    peer_alloc_port: int
+    peer_query_port: Optional[int]
+
+    buffer_size: int
+    buffer_device: str
+
+    proxy_host: Optional[str] = None
+    proxy_port: Optional[int] = None
+    skip_proxy_notification: bool = False
+
+    @staticmethod
+    def from_cache_engine_config(
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        tp_rank: int,
+    ) -> "PDConfig":
+        """Convert the LMCacheEngineConfig to PDConfig"""
+
+        role = config.pd_role
+
+        # Support bidirectional mode: "both" means this instance can
+        # read cached KV from peers AND write new KV to peers.
+        assert role in ["sender", "receiver", "both"], (
+            f"Invalid role: {config.pd_role}, must be sender, receiver, or both"
+        )
+
+        assert config.pd_buffer_size is not None
+        assert config.pd_buffer_device is not None
+
+        if role == "receiver":
+            assert config.pd_peer_host is not None
+            assert config.pd_peer_init_port is not None
+            assert config.pd_peer_alloc_port is not None
+        elif role == "sender":
+            if not config.pd_skip_proxy_notification:
+                assert config.pd_proxy_host is not None
+                assert config.pd_proxy_port is not None
+        elif role == "both":
+            # "both" role needs peer info (to read from decoder)
+            # AND proxy info (to notify after write)
+            assert config.pd_peer_host is not None
+            assert config.pd_peer_init_port is not None
+            assert config.pd_peer_alloc_port is not None
+            if config.pd_proxy_host is not None:
+                pass  # proxy notification is optional for "both"
+
+        corrected_device = get_correct_device(
+            config.pd_buffer_device, metadata.worker_id
+        )
+
+        if config.pd_peer_alloc_port is not None:
+            pd_peer_alloc_port = config.pd_peer_alloc_port[tp_rank]
+        else:
+            pd_peer_alloc_port = None
+
+        if config.pd_peer_init_port is not None:
+            pd_peer_init_port = config.pd_peer_init_port[tp_rank]
+        else:
+            pd_peer_init_port = None
+
+        if config.pd_peer_query_port is not None:
+            pd_peer_query_port = config.pd_peer_query_port[tp_rank]
+        else:
+            pd_peer_query_port = None
+
+        return PDConfig(
+            role=role,
+            peer_host=config.pd_peer_host,
+            peer_init_port=pd_peer_init_port,
+            peer_alloc_port=pd_peer_alloc_port,
+            peer_query_port=pd_peer_query_port,
+            proxy_host=config.pd_proxy_host,
+            proxy_port=config.pd_proxy_port,
+            buffer_size=config.pd_buffer_size,
+            buffer_device=corrected_device,
+            skip_proxy_notification=config.pd_skip_proxy_notification,
+        )
+
+
+class PDBackend(AllocatorBackendInterface):
+    """
+    Implementation of the StorageBackendInterface for PD Disaggregation.
+
+    At the sender side, it will never save anything but directly write the data
+    to the receiver side.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ):
+        self.running = True
+
+        self.tp_rank = metadata.worker_id
+        self.config = config
+
+        self.pd_config = PDConfig.from_cache_engine_config(
+            config, metadata, self.tp_rank
+        )
+
+        self.corrected_device = get_correct_device(
+            config.pd_buffer_device,
+            metadata.worker_id,
+        )
+
+        # NOTE(Jiayi): sender/prefiller will not use this pool;
+        # only receiver/decoder will.
+        self.data: dict[CacheEngineKey, MemoryObj] = {}
+        self.data_lock = threading.Lock()
+
+        # Async transfer support: use a dedicated NIXL worker thread with a
+        # queue so the vLLM worker thread is not blocked during KV transfer.
+        # All NIXL GPU operations run on this single thread to avoid CUDA
+        # context contention. This prevents RPC timeouts in vLLM v0.19.0's
+        # multiprocess executor.
+        # Standard
+        import queue as queue_mod
+
+        self._nixl_queue: queue_mod.Queue = queue_mod.Queue()
+        # Started after transfer_channel init
+        self._nixl_thread: threading.Thread | None = None
+        # Serializes all mutations and reads of the NIXL agent state
+        # (peer handshake, xfer handlers, batched_write, batched_read).
+        # The worker thread holds it around each GPU op; the main thread
+        # holds it around peer-connection setup so the two never touch
+        # nixl_agent concurrently.
+        self._nixl_agent_lock = threading.Lock()
+
+        self.memory_allocator = self.initialize_allocator(config, metadata)
+        assert isinstance(self.memory_allocator, PagedCpuGpuMemoryAllocator)
+
+        # TODO(Jiayi): add async zmq context if we want better asynchrony.
+        self.zmq_context = get_zmq_context(use_asyncio=False)
+        self.running_threads: list[threading.Thread] = []
+        self.side_channels: list[zmq.Socket] = []
+
+        # Initialize transfer channel
+        peer_init_url = None
+        self.local_id = ""
+        # The receiver binds a listener on peer_init_url so senders can connect.
+        # The sender (and "both" role) connects lazily via _ensure_peer_connection,
+        # so they should NOT start a listener on the decoder's address.
+        if (
+            self.pd_config.peer_init_port is not None
+            and self.pd_config.role == "receiver"
+        ):
+            peer_init_url = (
+                f"{self.pd_config.peer_host}:{self.pd_config.peer_init_port}"
+            )
+            self.local_id = self.pd_config.peer_host + str(
+                self.pd_config.peer_init_port
+            )
+
+        allocator = (
+            self.memory_allocator.cpu_allocator
+            if self.corrected_device == "cpu"
+            else self.memory_allocator.gpu_allocator
+        )
+        self.transfer_channel = CreateTransferChannel(
+            async_mode=False,
+            channel_type=config.transfer_channel,
+            role=self.pd_config.role,
+            buffer_ptr=allocator.buffer_ptr,
+            buffer_size=allocator.buffer_size,
+            align_bytes=allocator.align_bytes,
+            tp_rank=self.tp_rank,
+            peer_init_url=peer_init_url,  # type: ignore[arg-type]
+            backends=config.nixl_backends,
+            device=self.corrected_device,
+        )
+        self._nixl_backends = config.nixl_backends or ["UCX"]
+
+        # Start the NIXL worker thread now that transfer_channel is ready
+        self._nixl_thread = threading.Thread(
+            target=self._nixl_worker_loop,
+            name=f"nixl-worker-tp{metadata.worker_id}",
+            daemon=True,
+        )
+        self._nixl_thread.start()
+        self.running_threads.append(self._nixl_thread)
+
+        # Shared state for sender and "both" roles
+        self.initialized_peers: set[str] = set()
+        self.mem_alloc_sockets: dict[str, zmq.Socket] = {}
+        self.cache_query_sockets: dict[str, zmq.Socket] = {}
+
+        if self.pd_config.role == "sender":
+            self._init_sender()
+        elif self.pd_config.role == "receiver":
+            self._init_receiver()
+        elif self.pd_config.role == "both":
+            # Bidirectional: init sender capabilities (write to decoder)
+            # AND ability to read cached KV from decoder
+            self._init_sender()
+        else:
+            raise ValueError("Invalid PD role.")
+
+        self.full_chunk_size_bytes = config.chunk_size
+
+    def __str__(self):
+        return self.__class__.__name__
+
+    def initialize_allocator(
+        self, config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ) -> PagedCpuGpuMemoryAllocator:
+        if self.corrected_device != "cpu":
+            logger.info(f"Setting device to {self.corrected_device} ")
+            torch_dev.set_device(self.corrected_device)
+
+        paged_mem_allocator = PagedCpuGpuMemoryAllocator()
+
+        init_func = (
+            paged_mem_allocator.init_cpu_memory_allocator
+            if self.corrected_device == "cpu"
+            else paged_mem_allocator.init_gpu_memory_allocator
+        )
+
+        # Calculate the chunk size (align_bytes) and align buffer size
+        shapes = [torch.Size(metadata.kv_shape)]
+        dtypes = [metadata.kv_dtype]
+        chunk_size_bytes = get_size_bytes(shapes, dtypes)
+        origin_buffer_size = config.pd_buffer_size
+        aligned_buffer_size = origin_buffer_size // chunk_size_bytes * chunk_size_bytes
+
+        if aligned_buffer_size == 0 and origin_buffer_size > 0:
+            raise ValueError(
+                f"pd_buffer_size ({origin_buffer_size}) is smaller than a "
+                f"single chunk ({chunk_size_bytes}), resulting in an aligned "
+                f"buffer of size 0. Please increase pd_buffer_size to be at "
+                f"least {chunk_size_bytes}."
+            )
+
+        if aligned_buffer_size != origin_buffer_size:
+            logger.info(
+                f"Auto align pd_buffer_size, origin: {origin_buffer_size}, "
+                f"aligned: {aligned_buffer_size}, chunk size: {chunk_size_bytes}. "
+                f"The remaining {origin_buffer_size - aligned_buffer_size} bytes "
+                f"will not be allocated."
+            )
+
+        init_func(
+            aligned_buffer_size,
+            shapes,
+            dtypes,
+            MemoryFormat.KV_2LTD,  # TODO: remove this hardcode
+        )
+
+        return paged_mem_allocator
+
+    def get_memory_allocator(self) -> PagedCpuGpuMemoryAllocator:
+        return self.memory_allocator
+
+    def get_allocator_backend(self):
+        return self
+
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        if fmt is None:
+            fmt = MemoryFormat.KV_2LTD
+        # NOTE: no eviction and busy_loop in PD
+        alloc_type = "cpu" if self.corrected_device == "cpu" else "gpu"
+        return self.memory_allocator.allocate(
+            shapes, dtypes, fmt=fmt, allocator_type=alloc_type
+        )
+
+    # TODO(Jiayi): Please implement batched allocate to reduce memory
+    # allocation overhead.
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ):
+        if fmt is None:
+            fmt = MemoryFormat.KV_2LTD
+        alloc_type = "cpu" if self.corrected_device == "cpu" else "gpu"
+        return self.memory_allocator.batched_allocate(
+            shapes, dtypes, batch_size, fmt, allocator_type=alloc_type
+        )
+
+    # NOTE(Jiayi): If two requests have overlapped keys, will
+    # the later one cause any problems here?
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        assert isinstance(key, CacheEngineKey)
+        with self.data_lock:
+            if mem_obj := self.data.get(key, None):
+                if pin:
+                    mem_obj.ref_count_up()
+                return True
+            return False
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        return False
+
+    ############################################################
+    # Prefiller functions
+    ############################################################
+    def _init_sender(self):
+        if self.pd_config.skip_proxy_notification:
+            logger.info(
+                "pd_skip_proxy_notification=True, "
+                "skipping ZMQ PUSH proxy notification setup. "
+                "This mode is for external orchestrators only "
+                "(e.g., vLLM Production Stack router). "
+                "Do not use with LMCache's built-in disagg proxy."
+            )
+            self.proxy_side_channel = None
+        else:
+            proxy_url = f"{self.pd_config.proxy_host}:{self.pd_config.proxy_port}"
+            self.proxy_side_channel = get_zmq_socket(
+                self.zmq_context,
+                proxy_url,
+                "tcp",
+                zmq.PUSH,
+                "connect",
+            )
+
+    def _ensure_peer_connection(
+        self,
+        receiver_id: str,
+        receiver_host: str,
+        receiver_init_port: int,
+        receiver_alloc_port: int,
+    ) -> None:
+        if receiver_id in self.initialized_peers:
+            return
+
+        receiver_init_url = f"{receiver_host}:{receiver_init_port}"
+        receiver_mem_alloc_url = f"{receiver_host}:{receiver_alloc_port}"
+
+        # lazy_init_peer_connection mutates nixl_agent state
+        # (remote_xfer_handlers_dict) that the worker thread also touches,
+        # so serialize with the worker's GPU ops.
+        with self._nixl_agent_lock:
+            self.transfer_channel.lazy_init_peer_connection(
+                local_id=self.local_id,
+                peer_id=receiver_id,
+                peer_init_url=receiver_init_url,
+            )
+
+        # Set up the memory allocation socket
+        mem_alloc_socket = get_zmq_socket(
+            self.zmq_context,
+            receiver_mem_alloc_url,
+            "tcp",
+            zmq.REQ,
+            "connect",
+        )
+        self.mem_alloc_sockets[receiver_id] = mem_alloc_socket
+
+        self.initialized_peers.add(receiver_id)
+
+    def _remote_allocate(
+        self, receiver_id: str, alloc_request: AllocRequest
+    ) -> AllocResponse:
+        side_channel = self.mem_alloc_sockets[receiver_id]
+        side_channel.send(msgspec.msgpack.encode(alloc_request))
+        msg = side_channel.recv()
+        alloc_response = msgspec.msgpack.decode(msg, type=PDMsg)
+
+        return alloc_response
+
+    def _get_remote_alloc_request(
+        self, keys: Sequence[CacheEngineKey], mem_objs: List[MemoryObj]
+    ) -> AllocRequest:
+        """
+        Get the allocation request given the keys and memory objects.
+
+        Let's say there are N memory objects in total.
+        We have the following assumptions:
+        - The first N-1 memory objects are full chunks, each with
+        `full_chunk_size_bytes` tokens.
+        - The last memory object can be a partial chunk, which has
+        `last_chunk_toks` tokens.
+        """
+
+        fmt = mem_objs[0].meta.fmt
+        shape = mem_objs[0].meta.shape
+        dtype = TORCH_DTYPE_TO_STR_DTYPE[mem_objs[0].meta.dtype]
+        token_dim = fmt.token_dim()
+        last_chunk_toks = mem_objs[-1].meta.shape[token_dim]
+
+        str_keys = [key.to_string() for key in keys]
+
+        return AllocRequest(
+            keys=str_keys,
+            fmt=fmt.value,
+            shape=list(shape),
+            dtype=dtype,
+            last_chunk_toks=last_chunk_toks,
+        )
+
+    # TODO(Jiayi): make this async in the future
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Optional[List[Future]]:
+        """
+        Submit batched put tasks to transfer KV caches to peer.
+
+        The NIXL transfer is offloaded to a background thread to avoid blocking
+        the vLLM worker thread (which would cause RPC timeouts in vLLM v0.19.0's
+        multiprocess executor).
+
+        :param on_complete_callback: Optional callback invoked once per key
+            after the transfer completes. Callback exceptions are caught and logged.
+        :return: A single-element list containing a Future that resolves to the
+            number of objects written once the NIXL RDMA transfer completes and
+            the proxy notification has been sent. ``result()`` raises if the
+            transfer fails. Returns ``None`` for local (no-transfer) requests.
+            Callers can ignore it for fire-and-forget semantics or ``result()``
+            it for synchronous completion.
+        """
+        # Skip PD transfer for local requests (no transfer_spec).
+        # With conditional routing, direct-to-decoder requests have no disagg_spec.
+        if transfer_spec is None:
+            return None
+
+        for mem_obj in memory_objs:
+            mem_obj.ref_count_up()
+
+        receiver_init_port = transfer_spec.receiver_init_port[self.tp_rank]
+        receiver_alloc_port = transfer_spec.receiver_alloc_port[self.tp_rank]
+        receiver_id = transfer_spec.receiver_host + str(receiver_init_port)
+        receiver_host = transfer_spec.receiver_host
+
+        self._ensure_peer_connection(
+            receiver_id=receiver_id,
+            receiver_host=receiver_host,
+            receiver_init_port=receiver_init_port,
+            receiver_alloc_port=receiver_alloc_port,
+        )
+
+        # Allocate remote memory objects
+        alloc_request = self._get_remote_alloc_request(keys, memory_objs)
+        alloc_response = self._remote_allocate(receiver_id, alloc_request)
+        already_sent_indexes = alloc_response.already_sent_indexes
+        remote_indexes = alloc_response.remote_indexes
+
+        # Filter out already sent memory objects and free them
+        mem_objs_to_send = []
+        for idx, mem_obj in enumerate(memory_objs):
+            if idx in already_sent_indexes:
+                mem_obj.ref_count_down()
+            else:
+                mem_objs_to_send.append(mem_obj)
+
+        completion_future: Future = Future()
+
+        if mem_objs_to_send:
+            # Construct transfer spec
+            channel_transfer_spec = {
+                "receiver_id": receiver_id,
+                "remote_indexes": remote_indexes,
+            }
+
+            # Submit to the dedicated NIXL worker thread via queue.
+            # The worker thread handles the blocking batched_write() call.
+            self._nixl_queue.put(
+                (
+                    "write",
+                    mem_objs_to_send,
+                    channel_transfer_spec,
+                    keys,
+                    on_complete_callback,
+                    transfer_spec,
+                    completion_future,
+                )
+            )
+        else:
+            logger.debug(
+                "All memory objects have been already sent to the remote peer."
+                " Skipping transfer."
+            )
+            # Route notification through worker thread to avoid ZMQ
+            # thread-safety issues (all socket access on one thread).
+            if transfer_spec.is_last_prefill or on_complete_callback is not None:
+                self._nixl_queue.put(
+                    (
+                        "notify_only",
+                        keys,
+                        on_complete_callback,
+                        transfer_spec,
+                        completion_future,
+                    )
+                )
+            else:
+                # Nothing to do — resolve immediately with 0 writes.
+                completion_future.set_result(0)
+
+        return [completion_future]
+
+    def _nixl_worker_loop(self) -> None:
+        """Dedicated NIXL worker thread. Processes transfer requests from queue.
+
+        All NIXL GPU operations (batched_write, batched_read) run on this
+        single thread to avoid CUDA context contention with the vLLM worker.
+        """
+        # Standard
+        import queue as queue_mod
+
+        while self.running:
+            try:
+                item = self._nixl_queue.get(timeout=1.0)
+            except queue_mod.Empty:
+                continue
+
+            if item is None:
+                break  # Shutdown signal
+
+            op_type = item[0]
+            if op_type == "write":
+                (
+                    _,
+                    mem_objs,
+                    channel_spec,
+                    keys,
+                    callback,
+                    transfer_spec,
+                    completion_future,
+                ) = item
+                success = False
+                write_error: Optional[BaseException] = None
+                num_written = 0
+                try:
+                    with self._nixl_agent_lock:
+                        num_written = self.transfer_channel.batched_write(
+                            objects=mem_objs,
+                            transfer_spec=channel_spec,
+                        )
+                    success = True
+                except Exception as e:
+                    write_error = e
+                    logger.error(f"NIXL write failed in worker thread: {e}")
+                finally:
+                    for mem_obj in mem_objs:
+                        mem_obj.ref_count_down()
+
+                if success and transfer_spec.is_last_prefill:
+                    if self.proxy_side_channel is not None:
+                        notif_msg = ProxyNotif(req_id=transfer_spec.req_id)
+                        notif_msg_bytes = msgspec.msgpack.encode(notif_msg)
+                        self.proxy_side_channel.send(notif_msg_bytes)
+
+                if success and callback is not None:
+                    for key in keys:
+                        try:
+                            callback(key)
+                        except Exception as e:
+                            logger.warning(
+                                f"on_complete_callback failed for key {key}: {e}"
+                            )
+
+                # Resolve the Future AFTER proxy notification + callbacks so
+                # that future.result() returning means everything downstream
+                # has observed the completion.
+                if success:
+                    completion_future.set_result(num_written)
+                else:
+                    completion_future.set_exception(
+                        write_error or RuntimeError("NIXL write failed")
+                    )
+            elif op_type == "notify_only":
+                _, keys, callback, transfer_spec, completion_future = item
+                try:
+                    if transfer_spec.is_last_prefill:
+                        if self.proxy_side_channel is not None:
+                            notif_msg = ProxyNotif(req_id=transfer_spec.req_id)
+                            notif_msg_bytes = msgspec.msgpack.encode(notif_msg)
+                            self.proxy_side_channel.send(notif_msg_bytes)
+                    if callback is not None:
+                        for key in keys:
+                            try:
+                                callback(key)
+                            except Exception as e:
+                                logger.warning(
+                                    f"on_complete_callback failed for key {key}: {e}"
+                                )
+                    completion_future.set_result(0)
+                except Exception as e:
+                    completion_future.set_exception(e)
+            elif op_type == "read":
+                _, buffers, channel_spec, completion_future = item
+                try:
+                    with self._nixl_agent_lock:
+                        num_read = self.transfer_channel.batched_read(
+                            buffers=buffers,
+                            transfer_spec=channel_spec,
+                        )
+                    completion_future.set_result(num_read)
+                except Exception as e:
+                    logger.error(f"NIXL read failed in worker thread: {e}")
+                    completion_future.set_exception(e)
+
+    ############################################################
+    # Prefiller functions end
+    ############################################################
+
+    ############################################################
+    # Bidirectional NIXL: Prefiller reads cached KV from decoder
+    ############################################################
+
+    def _ensure_cache_query_connection(
+        self,
+        receiver_id: str,
+        receiver_host: str,
+        receiver_query_port: int,
+    ) -> None:
+        """Set up ZMQ socket for querying decoder's cache."""
+        if receiver_id in self.cache_query_sockets:
+            return
+
+        query_url = f"{receiver_host}:{receiver_query_port}"
+        query_socket = get_zmq_socket(
+            self.zmq_context,
+            query_url,
+            "tcp",
+            zmq.REQ,
+            "connect",
+        )
+        self.cache_query_sockets[receiver_id] = query_socket
+
+    def query_remote_cache(
+        self,
+        receiver_id: str,
+        keys: Sequence[CacheEngineKey],
+    ) -> CacheQueryResponse:
+        """
+        Query the decoder for which keys are cached in its GPU memory.
+
+        Returns a CacheQueryResponse with cached_keys and cached_indexes.
+        Uses a timeout to avoid blocking the vLLM worker indefinitely.
+        On timeout, the REQ socket is closed and removed so it will be
+        recreated on the next call (REQ requires strict send/recv
+        alternation — a missed recv leaves the socket in an unusable state).
+        """
+        query_socket = self.cache_query_sockets[receiver_id]
+        str_keys = [key.to_string() for key in keys]
+        query = CacheQueryRequest(keys=str_keys)
+        query_socket.send(msgspec.msgpack.encode(query))
+        # Use poll with timeout to avoid blocking indefinitely
+        if query_socket.poll(timeout=5000):  # 5 second timeout
+            resp_bytes = query_socket.recv()
+        else:
+            logger.warning(
+                "Cache query timed out after 5s for receiver %s, resetting socket",
+                receiver_id,
+            )
+            # Close the stuck socket — REQ socket is in recv-expected
+            # state after send() without recv(), making it unusable.
+            query_socket.close()
+            del self.cache_query_sockets[receiver_id]
+            return CacheQueryResponse(cached_keys=[], cached_indexes=[])
+        resp = msgspec.msgpack.decode(resp_bytes, type=PDMsg)
+        assert isinstance(resp, CacheQueryResponse)
+        return resp
+
+    def batched_submit_read_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        local_memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+    ) -> int:
+        """
+        Read cached KV blocks from the decoder's GPU memory into local buffers.
+
+        This is the bidirectional NIXL read path: the prefiller queries the
+        decoder for cached blocks, allocates local buffers, and reads the
+        cached KV data via NIXL READ (RDMA).
+
+        Args:
+            keys: Cache keys to check on the decoder.
+            local_memory_objs: Pre-allocated local MemoryObj buffers to read into.
+            transfer_spec: Must contain receiver_host, receiver_init_port,
+                receiver_alloc_port, and receiver_query_port.
+
+        Returns:
+            Number of blocks successfully read from the decoder.
+        """
+        # Skip read for local requests (no transfer_spec)
+        if transfer_spec is None:
+            return 0
+
+        receiver_init_port = transfer_spec.receiver_init_port[self.tp_rank]
+        receiver_alloc_port = transfer_spec.receiver_alloc_port[self.tp_rank]
+        receiver_query_port = transfer_spec.receiver_query_port[self.tp_rank]
+        receiver_id = transfer_spec.receiver_host + str(receiver_init_port)
+        receiver_host = transfer_spec.receiver_host
+
+        # Ensure NIXL peer connection is established
+        self._ensure_peer_connection(
+            receiver_id=receiver_id,
+            receiver_host=receiver_host,
+            receiver_init_port=receiver_init_port,
+            receiver_alloc_port=receiver_alloc_port,
+        )
+
+        # Ensure cache query connection
+        self._ensure_cache_query_connection(
+            receiver_id=receiver_id,
+            receiver_host=receiver_host,
+            receiver_query_port=receiver_query_port,
+        )
+
+        # Query decoder for cached blocks
+        cache_resp = self.query_remote_cache(receiver_id, keys)
+
+        if not cache_resp.cached_keys:
+            logger.debug("No cached blocks found on decoder for this prefix.")
+            return 0
+
+        # Map cached keys to local buffer indices
+        key_to_local_idx = {}
+        for idx, key in enumerate(keys):
+            key_to_local_idx[key.to_string()] = idx
+
+        local_objs_to_read = []
+        remote_indexes = []
+        for cached_key, remote_idx in zip(
+            cache_resp.cached_keys,
+            cache_resp.cached_indexes,
+            strict=False,
+        ):
+            local_idx = key_to_local_idx.get(cached_key)
+            if local_idx is not None and local_idx < len(local_memory_objs):
+                local_objs_to_read.append(local_memory_objs[local_idx])
+                remote_indexes.append(remote_idx)
+
+        if not local_objs_to_read:
+            logger.debug("No matching local buffers for cached remote blocks.")
+            return 0
+
+        # Perform NIXL READ on the worker thread so that writes, reads,
+        # and peer-handshake never touch nixl_agent concurrently.
+        channel_transfer_spec = {
+            "sender_id": receiver_id,
+            "remote_indexes": remote_indexes,
+        }
+
+        read_future: Future = Future()
+        self._nixl_queue.put(
+            (
+                "read",
+                local_objs_to_read,
+                channel_transfer_spec,
+                read_future,
+            )
+        )
+        num_read = read_future.result()
+
+        logger.info(
+            "Bidirectional NIXL: read %d/%d cached blocks from decoder %s",
+            num_read,
+            len(keys),
+            receiver_id,
+        )
+
+        return num_read
+
+    ############################################################
+    # Bidirectional NIXL end
+    ############################################################
+
+    ############################################################
+    # Decoder functions
+    ############################################################
+    def _init_receiver(self):
+        # Initialize initialization side channels
+        receiver_alloc_url = (
+            f"{self.pd_config.peer_host}:{self.pd_config.peer_alloc_port}"
+        )
+        self.alloc_side_channel = get_zmq_socket(
+            self.zmq_context, receiver_alloc_url, "tcp", zmq.REP, "bind"
+        )
+        self.side_channels.append(self.alloc_side_channel)
+
+        # Start the memory allocation thread
+        self.mem_alloc_thread = threading.Thread(
+            target=self._mem_alloc_loop, daemon=True
+        )
+        self.mem_alloc_thread.start()
+        self.running_threads.append(self.mem_alloc_thread)
+
+        # Start cache query listener if query port is configured
+        # (enables bidirectional NIXL: prefiller can query decoder's cache)
+        if self.pd_config.peer_query_port is not None:
+            query_url = f"{self.pd_config.peer_host}:{self.pd_config.peer_query_port}"
+            self.query_side_channel = get_zmq_socket(
+                self.zmq_context, query_url, "tcp", zmq.REP, "bind"
+            )
+            self.side_channels.append(self.query_side_channel)
+
+            self.cache_query_thread = threading.Thread(
+                target=self._cache_query_loop, daemon=True
+            )
+            self.cache_query_thread.start()
+            self.running_threads.append(self.cache_query_thread)
+            logger.info(
+                "Bidirectional NIXL: cache query listener started on %s",
+                query_url,
+            )
+
+    def _allocate_and_put(self, alloc_request: AllocRequest) -> AllocResponse:
+        total_allocs = len(alloc_request.keys)
+        fmt = MemoryFormat(alloc_request.fmt)
+        dtype = STR_DTYPE_TO_TORCH_DTYPE[alloc_request.dtype]
+        shape = alloc_request.shape
+
+        alloc_indexes = []
+        already_send_indexes = []
+
+        for idx, key_str in enumerate(alloc_request.keys):
+            key = CacheEngineKey.from_string(key_str)
+            if self.contains(key, pin=True):
+                already_send_indexes.append(idx)
+                continue
+
+            if idx == total_allocs - 1:
+                num_alloc_tokens = alloc_request.last_chunk_toks
+                token_dim = fmt.token_dim()
+                shape[token_dim] = num_alloc_tokens
+            else:
+                num_alloc_tokens = self.full_chunk_size_bytes
+
+            mem_obj = self.allocate(torch.Size(shape), dtype, fmt)
+
+            # TODO(Jiayi): make busy loop allocation part of
+            # memory allocator instead of backend as both PD
+            # and CPU offloading might need this.
+            wait_time = 0.01
+            while mem_obj is None:
+                logger.warning(
+                    "Failed to allocate memory object, retrying...",
+                )
+                time.sleep(wait_time)
+                mem_obj = self.allocate(torch.Size(shape), dtype, fmt)
+
+            alloc_indexes.append(mem_obj.meta.address)
+
+            self.put(key, mem_obj)
+
+        return AllocResponse(
+            already_sent_indexes=already_send_indexes, remote_indexes=alloc_indexes
+        )
+
+    def _mem_alloc_loop(self):
+        """
+        Running the memory allocation loop.
+        """
+        while self.running:
+            try:
+                # receive alloc request
+                alloc_req_bytes = self.alloc_side_channel.recv()
+                alloc_req = msgspec.msgpack.decode(alloc_req_bytes, type=PDMsg)
+                assert isinstance(alloc_req, AllocRequest), (
+                    "The request from the remote peer is not a AllocRequest"
+                )
+
+                # NOTE: it's okay to put the memory objs into the storage backend
+                # first because decode vllm will not be able to see the decode
+                # request until proxy receives the ack.
+                alloc_resp = self._allocate_and_put(alloc_req)
+
+                # send back response
+                self.alloc_side_channel.send(msgspec.msgpack.encode(alloc_resp))
+
+            except Exception as e:
+                logger.error("Failed to process mem alloc loop: %s", str(e))
+                if self.running:
+                    time.sleep(0.01)
+
+    def put(
+        self,
+        key: CacheEngineKey,
+        mem_obj: MemoryObj,
+    ):
+        with self.data_lock:
+            self.data[key] = mem_obj
+
+    def _cache_query_loop(self):
+        """
+        Listen for cache query requests from prefiller (bidirectional NIXL).
+        The prefiller sends a list of keys and the decoder responds with
+        which keys are cached and their memory indices.
+        """
+        while self.running:
+            try:
+                query_bytes = self.query_side_channel.recv()
+            except Exception as e:
+                if self.running:
+                    logger.error("Cache query recv failed: %s", str(e))
+                    time.sleep(0.01)
+                continue
+
+            # After recv, we MUST send a reply (ZMQ REP pattern).
+            # If processing fails, send an empty response.
+            try:
+                query = msgspec.msgpack.decode(query_bytes, type=PDMsg)
+                assert isinstance(query, CacheQueryRequest), (
+                    f"Expected CacheQueryRequest, got {type(query)}"
+                )
+
+                cached_keys = []
+                cached_indexes = []
+                with self.data_lock:
+                    for key_str in query.keys:
+                        key = CacheEngineKey.from_string(key_str)
+                        if mem_obj := self.data.get(key, None):
+                            cached_keys.append(key_str)
+                            cached_indexes.append(mem_obj.meta.address)
+
+                resp = CacheQueryResponse(
+                    cached_keys=cached_keys,
+                    cached_indexes=cached_indexes,
+                )
+                self.query_side_channel.send(msgspec.msgpack.encode(resp))
+
+                logger.info(
+                    "Cache query: %d/%d keys cached",
+                    len(cached_keys),
+                    len(query.keys),
+                )
+
+            except Exception as e:
+                logger.error("Failed to process cache query: %s", str(e))
+                # Send empty response to unblock the REP socket
+                try:
+                    empty_resp = CacheQueryResponse(cached_keys=[], cached_indexes=[])
+                    self.query_side_channel.send(msgspec.msgpack.encode(empty_resp))
+                except Exception:
+                    pass  # Socket may be broken, nothing we can do
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        with self.data_lock:
+            # NOTE(Jiayi): we assume that the key must be in local data
+            # because we are using a push-based transfer
+            mem_obj = self.data.get(key, None)
+            assert mem_obj is not None, f"Key {key} not found in local data."
+            return mem_obj
+
+    def remove(
+        self,
+        key: CacheEngineKey,
+        force: bool = True,
+    ) -> bool:
+        """
+        Remove the key from the storage backend.
+
+        :param key: The key to remove.
+        """
+        # TODO(Jiayi): The logic here is confusing. Ref count down
+        # will be done after this function call in cache engine.
+        with self.data_lock:
+            if mem_obj := self.data.get(key, None):
+                if mem_obj.get_ref_count() == 1:
+                    del self.data[key]
+                return True
+            return False
+
+    ############################################################
+    # Decoder functions end
+    ############################################################
+
+    def close(self) -> None:
+        """
+        Close the storage backend.
+        """
+        self.running = False
+        # Signal the NIXL worker thread to exit
+        self._nixl_queue.put(None)
+        for thread in self.running_threads:
+            thread.join(timeout=5.0)
+        self.transfer_channel.close()
+        self.zmq_context.term()
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        return True
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        return True
diff --git a/lmcache/v1/storage_backend/pd_backend_async.py b/lmcache/v1/storage_backend/pd_backend_async.py
new file mode 100644
index 0000000..2119ccc
--- /dev/null
+++ b/lmcache/v1/storage_backend/pd_backend_async.py
@@ -0,0 +1,1705 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, Sequence, Union
+import asyncio
+import os
+import threading
+import time
+import traceback
+import uuid
+
+# Third Party
+import msgspec
+import torch
+import zmq
+import zmq.asyncio
+
+# First Party
+from lmcache import torch_dev
+from lmcache.integration.vllm.utils import get_size_bytes
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    STR_DTYPE_TO_TORCH_DTYPE,
+    TORCH_DTYPE_TO_STR_DTYPE,
+    CacheEngineKey,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.paged_cpu_gpu_memory_allocator import (
+    PagedCpuGpuMemoryAllocator,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.rpc_utils import get_zmq_context
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+from lmcache.v1.transfer_channel import CreateTransferChannel
+from lmcache.v1.transfer_channel.transfer_utils import get_correct_device
+
+logger = init_logger(__name__)
+
+
+class PDMsgBase(msgspec.Struct, tag=True):
+    """Base class for all PD-related messages"""
+
+    pass
+
+
+class AllocRequest(PDMsgBase):
+    """Allocation request message"""
+
+    keys: list[str]  # len(keys) indicates num_chunks
+    fmt: int
+    shape: list[int]  # The shape of the memory objects
+    dtype: str
+    last_chunk_toks: int
+    # req_id is used by the receiver for per-request chunk accounting and
+    # fail-fast detection when C_req > total_chunks.  An empty string
+    # means the sender does not provide an identifier (backwards-compatible);
+    # in that case per-request chunk accounting and fail-fast detection are
+    # skipped for this allocation request.
+    req_id: str = ""
+    # is_last_batch signals the final batch for this req_id so the receiver
+    # can release admission and clean up per-request tracking.
+    is_last_batch: bool = False
+    total_chunks: int = 0  # total chunks for this request (for receiver reservation)
+
+
+class AllocResponse(PDMsgBase):
+    """Allocation response message"""
+
+    # Indexes (remote) of allocated memory objects (to be written).
+    # One entry per key in the request; -1 means allocation failed for that slot.
+    remote_indexes: list[int]
+
+    # Indexes (local) of already sent memory objects.
+    # Always empty for PDBackendAsync (no dedup), but included for
+    # wire-compatibility with sync PDBackend senders that expect this field.
+    already_sent_indexes: list[int] = []
+
+
+class ProxyNotif(PDMsgBase):
+    req_id: str  # The request id to notify the proxy
+
+
+class CancelNotif(PDMsgBase):
+    """Sent from sender to receiver when a request is aborted."""
+
+    req_id: str
+    keys: list[str]  # keys that receiver should release
+
+
+PDMsg = Union[AllocRequest, AllocResponse, ProxyNotif, CancelNotif]
+
+
+class ReservationManager:
+    """
+    Manages reservation-based admission control for the receiver PD buffer.
+
+    Prevents deadlock where N concurrent requests each allocate partial chunks,
+    fill the buffer, and none can complete. When a request is admitted, its
+    total_chunks are reserved upfront. Subsequent physical allocations draw
+    from that reservation.
+
+    Used exclusively on the receiver side via asyncio primitives.
+    """
+
+    def __init__(
+        self,
+        total_chunks: int,
+        allocation_timeout: float,
+        condition_poll_interval: float,
+    ) -> None:
+        """Initialize the ReservationManager.
+
+        :param total_chunks: Total number of chunks in the buffer.
+        :param allocation_timeout: Max seconds to wait for admission.
+        :param condition_poll_interval: Poll interval for condition waits.
+        """
+        self._total_chunks = total_chunks
+        self._allocation_timeout = allocation_timeout
+        self._condition_poll_interval = condition_poll_interval
+
+        # Shared data
+        self._reservations: dict[str, int] = {}  # req_id -> reserved chunks
+        self._total_reserved: int = 0
+
+        # Asyncio variant (receiver, created lazily on receiver event loop)
+        self._async_admit_condition: asyncio.Condition | None = None
+
+    def init_async_admit_condition(self) -> None:
+        """Create asyncio.Condition bound to the current event loop.
+
+        Must be called from within the target event loop.
+        """
+        self._async_admit_condition = asyncio.Condition()
+
+    async def async_try_admit(self, req_id: str, total_chunks: int) -> bool:
+        """Async (asyncio) admission for receiver.
+
+        :param req_id: The request identifier to admit.
+        :param total_chunks: Number of chunks to reserve.
+        :return: True if admitted, False if timed out.
+        """
+        assert self._async_admit_condition is not None
+        async with self._async_admit_condition:
+            deadline = asyncio.get_running_loop().time() + self._allocation_timeout
+            while True:
+                available = self._total_chunks - self._total_reserved
+                if available >= total_chunks:
+                    self._reservations[req_id] = total_chunks
+                    self._total_reserved += total_chunks
+                    logger.debug(
+                        "[ADMIT] req=%s admitted (async), reserved=%d, "
+                        "total_reserved=%d/%d",
+                        req_id,
+                        total_chunks,
+                        self._total_reserved,
+                        self._total_chunks,
+                    )
+                    return True
+                remaining = deadline - asyncio.get_running_loop().time()
+                if remaining <= 0:
+                    logger.warning(
+                        "[ADMIT] req=%s async admission timed out: need=%d, "
+                        "available=%d, total_reserved=%d/%d",
+                        req_id,
+                        total_chunks,
+                        available,
+                        self._total_reserved,
+                        self._total_chunks,
+                    )
+                    return False
+                try:
+                    await asyncio.wait_for(
+                        self._async_admit_condition.wait(),
+                        timeout=min(remaining, self._condition_poll_interval),
+                    )
+                except asyncio.TimeoutError:
+                    pass
+
+    async def async_release_reservation(self, req_id: str) -> None:
+        """Release reservation (asyncio variant). Notifies all waiters.
+
+        :param req_id: The request identifier whose reservation to release.
+        """
+        assert self._async_admit_condition is not None
+        async with self._async_admit_condition:
+            count = self._reservations.pop(req_id, 0)
+            if count > 0:
+                self._total_reserved -= count
+                logger.debug(
+                    "[ADMIT] req=%s reservation released (async), freed=%d, "
+                    "total_reserved=%d/%d",
+                    req_id,
+                    count,
+                    self._total_reserved,
+                    self._total_chunks,
+                )
+                self._async_admit_condition.notify_all()
+
+    def get_total_chunks(self) -> int:
+        """Return the total buffer capacity in chunks.
+
+        :return: Total number of chunks this manager was initialised with.
+        :rtype: int
+        """
+        return self._total_chunks
+
+
+@dataclass
+class PDConfig:
+    role: str
+
+    peer_host: str
+    peer_init_port: int
+    peer_alloc_port: int
+
+    proxy_host: str
+    proxy_port: int
+
+    buffer_size: int
+    buffer_device: str
+
+    allocation_timeout_sec: float
+    shutdown_timeout_sec: float
+    condition_poll_interval_sec: float
+
+    @staticmethod
+    def from_cache_engine_config(
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        tp_rank: int,
+    ) -> "PDConfig":
+        """Convert the LMCacheEngineConfig to PDConfig"""
+
+        role = config.pd_role
+
+        # TODO(Jiayi): Could be both if we want to do dynamic role switch.
+        assert role in ["sender", "receiver"], (
+            f"Invalid role: {config.pd_role}, must be either sender or receiver"
+        )
+
+        assert config.pd_buffer_size is not None
+        assert config.pd_buffer_device is not None
+
+        if role == "receiver":
+            assert config.pd_peer_host is not None
+            assert config.pd_peer_init_port is not None
+            assert config.pd_peer_alloc_port is not None
+        elif role == "sender":
+            assert config.pd_proxy_host is not None
+            assert config.pd_proxy_port is not None
+
+        corrected_device = get_correct_device(
+            config.pd_buffer_device, metadata.worker_id
+        )
+
+        if config.pd_peer_alloc_port is not None:
+            pd_peer_alloc_port = config.pd_peer_alloc_port[tp_rank]
+        else:
+            pd_peer_alloc_port = None
+
+        if config.pd_peer_init_port is not None:
+            pd_peer_init_port = config.pd_peer_init_port[tp_rank]
+        else:
+            pd_peer_init_port = None
+
+        return PDConfig(
+            role=role,
+            peer_host=config.pd_peer_host,
+            peer_init_port=pd_peer_init_port,
+            peer_alloc_port=pd_peer_alloc_port,
+            proxy_host=config.pd_proxy_host,
+            proxy_port=config.pd_proxy_port,
+            buffer_size=config.pd_buffer_size,
+            buffer_device=corrected_device,
+            allocation_timeout_sec=config.pd_allocation_timeout_sec,
+            shutdown_timeout_sec=config.pd_shutdown_timeout_sec,
+            condition_poll_interval_sec=config.pd_condition_poll_interval_sec,
+        )
+
+
+class PDBackendAsync(AllocatorBackendInterface):
+    """
+    Implementation of the StorageBackendInterface for PD Disaggregation.
+
+    At the sender side, it will never save anything but directly write the data
+    to the receiver side.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+    ):
+        self.running = True
+
+        self.tp_rank = metadata.worker_id
+
+        self.pd_config = PDConfig.from_cache_engine_config(
+            config, metadata, self.tp_rank
+        )
+
+        # Cache timing config values as instance attributes for convenient access.
+        self._allocation_timeout = self.pd_config.allocation_timeout_sec
+        self._condition_poll_interval = self.pd_config.condition_poll_interval_sec
+
+        self.corrected_device = get_correct_device(
+            config.pd_buffer_device,
+            metadata.worker_id,
+        )
+
+        # NOTE(Jiayi): sender/prefiller will not use this pool;
+        # only receiver/decoder will.
+        self.data: dict[CacheEngineKey, MemoryObj] = {}
+        self.data_lock = threading.Lock()
+
+        self.memory_allocator = self.initialize_allocator(config, metadata)
+        assert isinstance(self.memory_allocator, PagedCpuGpuMemoryAllocator)
+
+        self.zmq_context = get_zmq_context(use_asyncio=False)
+        self.running_threads: list[threading.Thread] = []
+        self.side_channels: list[zmq.Socket] = []
+
+        # Initialize transfer channel
+        peer_init_url = None
+        self.local_id = ""
+        # TODO(Jiayi): both sender and receiver have to have
+        # peer_init_url if they want to do instance flip.
+        if self.pd_config.peer_init_port is not None:
+            peer_init_url = (
+                f"{self.pd_config.peer_host}:{self.pd_config.peer_init_port}"
+            )
+            self.local_id = self.pd_config.peer_host + str(
+                self.pd_config.peer_init_port
+            )
+
+        # Fallback: ensure local_id is never empty so DEALER identity is unique.
+        # Senders typically don't set pd_peer_init_port. In xP1D deployments
+        # multiple Prefillers may share the same proxy, so proxy_host:proxy_port
+        # alone is NOT unique. We include os.getpid() and a UUID fragment to
+        # guarantee a globally unique identity.
+        if not self.local_id:
+            self.local_id = f"sender-pid{os.getpid()}-{uuid.uuid4().hex[:8]}"
+
+        # Create the event loop before the transfer channel so it can be passed
+        # into the channel constructor for async_mode initialization.
+        if self.pd_config.role == "sender":
+            self._sender_loop = asyncio.new_event_loop()
+            self._sender_thread = threading.Thread(
+                target=self._sender_loop.run_forever,
+                daemon=True,
+                name="pd-sender-async",
+            )
+            self._sender_thread.start()
+            event_loop = self._sender_loop
+        elif self.pd_config.role == "receiver":
+            self._recv_loop = asyncio.new_event_loop()
+            self._recv_thread = threading.Thread(
+                target=self._recv_loop.run_forever,
+                daemon=True,
+                name="pd-receiver-async",
+            )
+            self._recv_thread.start()
+            event_loop = self._recv_loop
+        else:
+            raise ValueError("Invalid PD role.")
+
+        allocator = (
+            self.memory_allocator.cpu_allocator
+            if self.corrected_device == "cpu"
+            else self.memory_allocator.gpu_allocator
+        )
+        self.transfer_channel = CreateTransferChannel(
+            async_mode=True,
+            channel_type=config.transfer_channel,
+            role=self.pd_config.role,
+            buffer_ptr=allocator.buffer_ptr,
+            buffer_size=allocator.buffer_size,
+            align_bytes=allocator.align_bytes,
+            tp_rank=self.tp_rank,
+            peer_init_url=peer_init_url,
+            backends=config.nixl_backends,
+            device=self.corrected_device,
+            event_loop=event_loop,
+        )
+
+        if self.pd_config.role == "sender":
+            self.initialized_peers: set[str] = set()
+            self._peer_connection_lock = threading.Lock()
+            # Separate async ZMQ context for sender coroutines
+            self._async_zmq_context = zmq.asyncio.Context()
+            self._async_alloc_sockets: dict[str, zmq.asyncio.Socket] = {}
+            self._async_alloc_locks: dict[str, asyncio.Lock] = {}
+            # Physical memory wait condition (woken when RDMA completes and
+            # ref_count_down() frees buffer slots).
+            self._staging_lock = threading.Lock()
+            self._staging_condition = threading.Condition(self._staging_lock)
+            # Per-request tracking for ProxyNotif ordering and abort.
+            # All accessed only from coroutines on _sender_loop (no extra lock).
+            self._completed_chunks: dict[str, int] = {}
+            self._req_has_last: dict[str, bool] = {}
+            self._req_total_chunks: dict[str, int] = {}
+            self._sent_keys: dict[str, list[str]] = {}
+            self._req_receiver: dict[str, str] = {}
+            self._init_sender()
+        elif self.pd_config.role == "receiver":
+            total_chunks = self._aligned_buffer_size // self._chunk_size_bytes
+            # Reservation-based admission control for receiver.
+            self._recv_reservation_mgr = ReservationManager(
+                total_chunks,
+                self._allocation_timeout,
+                self._condition_poll_interval,
+            )
+            # The asyncio primitives must be created on the receiver event loop.
+            future = asyncio.run_coroutine_threadsafe(
+                self._create_recv_primitives(), self._recv_loop
+            )
+            future.result(timeout=5)
+            logger.info(
+                "PDBackendAsync receiver: reservation-based admission control "
+                "initialized with total_chunks=%d "
+                "(buffer=%d bytes, chunk=%d bytes)",
+                total_chunks,
+                self._aligned_buffer_size,
+                self._chunk_size_bytes,
+            )
+            # Per-request key tracking for rollback.
+            # Maps req_id → list of key strings allocated across all batches.
+            self._req_allocated_keys: dict[str, list[str]] = {}
+            self._init_receiver()
+
+        self.full_chunk_size_bytes = config.chunk_size
+
+    def __str__(self):
+        return "PDBackend"
+
+    def initialize_allocator(
+        self, config: LMCacheEngineConfig, metadata: LMCacheMetadata
+    ) -> PagedCpuGpuMemoryAllocator:
+        if self.corrected_device != "cpu":
+            logger.info(f"Setting cuda device to {self.corrected_device} ")
+            torch_dev.set_device(self.corrected_device)
+
+        paged_mem_allocator = PagedCpuGpuMemoryAllocator()
+
+        init_func = (
+            paged_mem_allocator.init_cpu_memory_allocator
+            if self.corrected_device == "cpu"
+            else paged_mem_allocator.init_gpu_memory_allocator
+        )
+
+        # Calculate the chunk size (align_bytes) and align buffer size
+        shapes = [torch.Size(metadata.kv_shape)]
+        dtypes = [metadata.kv_dtype]
+        chunk_size_bytes = get_size_bytes(shapes, dtypes)
+        origin_buffer_size = config.pd_buffer_size
+        aligned_buffer_size = origin_buffer_size // chunk_size_bytes * chunk_size_bytes
+
+        if aligned_buffer_size == 0 and origin_buffer_size > 0:
+            raise ValueError(
+                f"pd_buffer_size ({origin_buffer_size}) is smaller than a "
+                f"single chunk ({chunk_size_bytes}), resulting in an aligned "
+                f"buffer of size 0. Please increase pd_buffer_size to be at "
+                f"least {chunk_size_bytes}."
+            )
+
+        if aligned_buffer_size != origin_buffer_size:
+            logger.info(
+                f"Auto align pd_buffer_size, origin: {origin_buffer_size}, "
+                f"aligned: {aligned_buffer_size}, chunk size: {chunk_size_bytes}. "
+                f"The remaining {origin_buffer_size - aligned_buffer_size} bytes "
+                f"will not be allocated."
+            )
+
+        self._chunk_size_bytes = chunk_size_bytes
+        self._aligned_buffer_size = aligned_buffer_size
+        # Number of tokens per chunk (used for capacity checks).
+        self._chunk_token_size = metadata.kv_shape[MemoryFormat.KV_2LTD.token_dim()]
+
+        pd_max_prefill_len = config.pd_max_prefill_len
+        if pd_max_prefill_len > 0:
+            capacity_tokens = (
+                aligned_buffer_size // chunk_size_bytes
+            ) * self._chunk_token_size
+            if capacity_tokens < pd_max_prefill_len:
+                raise ValueError(
+                    f"PD buffer too small for the configured pd_max_prefill_len "
+                    f"(role={self.pd_config.role}): "
+                    f"capacity_tokens={capacity_tokens} < "
+                    f"pd_max_prefill_len={pd_max_prefill_len}. "
+                    f"Inputs: aligned_buffer_size={aligned_buffer_size}, "
+                    f"chunk_size={chunk_size_bytes}, "
+                    f"chunk_token_size={self._chunk_token_size}. "
+                    f"Increase pd_buffer_size so that the buffer holds at least "
+                    f"pd_max_prefill_len={pd_max_prefill_len} tokens."
+                )
+
+        init_func(
+            aligned_buffer_size,
+            shapes,
+            dtypes,
+            MemoryFormat.KV_2LTD,  # TODO: remove this hardcode
+        )
+
+        return paged_mem_allocator
+
+    def get_memory_allocator(self) -> PagedCpuGpuMemoryAllocator:
+        """Return the underlying paged CPU/GPU memory allocator.
+
+        :return: The memory allocator instance used by this backend.
+        :rtype: PagedCpuGpuMemoryAllocator
+        """
+        return self.memory_allocator
+
+    def get_allocator_backend(self) -> "PDBackendAsync":
+        """Return the allocator backend instance (self).
+
+        :return: This backend instance, which implements AllocatorBackendInterface.
+        :rtype: PDBackendAsync
+        """
+        return self
+
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ) -> Optional[MemoryObj]:
+        """Allocate a single memory object from the PD buffer.
+
+        For the sender role, this method enforces staging buffer flow control:
+        it blocks until inflight chunks drop below the threshold, then attempts
+        allocation with a configurable timeout. For the receiver role, allocation
+        is delegated directly to the underlying memory allocator.
+
+        Note: ``eviction`` and ``busy_loop`` parameters are accepted for interface
+        compatibility but are not used in the PD backend.
+
+        :param shapes: Shape(s) of the KV tensors to allocate.
+        :param dtypes: Data type(s) of the KV tensors.
+        :param fmt: Memory format, defaults to KV_2LTD.
+        :param eviction: Unused; kept for interface compatibility.
+        :param busy_loop: Unused; kept for interface compatibility.
+        :return: The allocated MemoryObj, or None if allocation failed or the
+            backend is shutting down.
+        :rtype: Optional[MemoryObj]
+        """
+        if fmt is None:
+            fmt = MemoryFormat.KV_2LTD
+        # NOTE: no eviction and busy_loop in PD
+        alloc_type = "cpu" if self.corrected_device == "cpu" else "gpu"
+
+        if self.pd_config.role == "sender":
+            # Fast path: try allocation immediately.
+            mem_obj = self.memory_allocator.allocate(
+                shapes, dtypes, fmt=fmt, allocator_type=alloc_type
+            )
+            if mem_obj is not None:
+                return mem_obj
+            # Slow path: staging buffer physically full; wait for RDMA
+            # completions to free slots.  _notify_staging_freed() wakes us
+            # whenever ref_count_down() returns a slot.
+            deadline = time.monotonic() + self._allocation_timeout
+            with self._staging_condition:
+                while True:
+                    if not self.running:
+                        return None
+                    mem_obj = self.memory_allocator.allocate(
+                        shapes, dtypes, fmt=fmt, allocator_type=alloc_type
+                    )
+                    if mem_obj is not None:
+                        return mem_obj
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0:
+                        break
+                    self._staging_condition.wait(
+                        timeout=min(remaining, self._condition_poll_interval)
+                    )
+            logger.error("Sender staging allocation failed after timeout")
+            return None
+        else:
+            return self.memory_allocator.allocate(
+                shapes, dtypes, fmt=fmt, allocator_type=alloc_type
+            )
+
+    # allocation overhead.
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction: bool = True,
+        busy_loop: bool = True,
+    ):
+        """Allocate a batch of memory objects from the PD buffer.
+
+        Delegates directly to the underlying memory allocator without sender
+        flow control. Currently a thin wrapper; see the TODO for planned
+        improvements.
+
+        :param shapes: Shape(s) of the KV tensors to allocate.
+        :param dtypes: Data type(s) of the KV tensors.
+        :param batch_size: Number of memory objects to allocate.
+        :param fmt: Memory format, defaults to KV_2LTD.
+        :param eviction: Unused; kept for interface compatibility.
+        :param busy_loop: Unused; kept for interface compatibility.
+        :return: A list of allocated MemoryObj instances, or None for slots
+            that failed to allocate.
+        :rtype: list[Optional[MemoryObj]]
+        """
+        if fmt is None:
+            fmt = MemoryFormat.KV_2LTD
+
+        if self.pd_config.role == "sender":
+            return [
+                self.allocate(shapes, dtypes, fmt, eviction, busy_loop)
+                for _ in range(batch_size)
+            ]
+
+        alloc_type = "cpu" if self.corrected_device == "cpu" else "gpu"
+        return self.memory_allocator.batched_allocate(
+            shapes, dtypes, batch_size, fmt, allocator_type=alloc_type
+        )
+
+    # NOTE(Jiayi): If two requests have overlapped keys, will
+    # the later one cause any problems here?
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """Check whether the given key exists in the local data store.
+
+        :param key: The cache engine key to look up.
+        :param pin: If True and the key exists, increment the memory object's
+            reference count to prevent it from being freed.
+        :return: True if the key is present, False otherwise.
+        :rtype: bool
+        :raises AssertionError: If ``key`` is not a CacheEngineKey instance.
+        """
+        assert isinstance(key, CacheEngineKey)
+        with self.data_lock:
+            if mem_obj := self.data.get(key, None):
+                if pin:
+                    mem_obj.ref_count_up()
+                return True
+            return False
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """Check whether the key is pending in any in-flight put task.
+
+        PDBackendAsync does not maintain a put task queue, so this always
+        returns False.
+
+        :param key: The cache engine key to check.
+        :return: Always False.
+        :rtype: bool
+        """
+        return False
+
+    ############################################################
+    # Prefiller functions
+    ############################################################
+    def _init_sender(self) -> None:
+        """Initialize sender-side sockets and locks on the sender event loop."""
+        proxy_url = f"{self.pd_config.proxy_host}:{self.pd_config.proxy_port}"
+        future = asyncio.run_coroutine_threadsafe(
+            self._async_init_proxy_socket(proxy_url),
+            self._sender_loop,
+        )
+        future.result(timeout=10)
+
+    async def _async_init_proxy_socket(self, proxy_url: str) -> None:
+        """Create the async ZMQ PUSH socket for ProxyNotif messages.
+
+        Must run on the sender event loop so the socket is loop-bound.
+
+        :param proxy_url: The proxy host:port string.
+        """
+        self._async_proxy_socket = self._async_zmq_context.socket(zmq.PUSH)
+        self._async_proxy_socket.connect(f"tcp://{proxy_url}")
+        self._proxy_send_lock = asyncio.Lock()
+
+    def _ensure_peer_connection(
+        self,
+        receiver_id: str,
+        receiver_host: str,
+        receiver_init_port: int,
+        receiver_alloc_port: int,
+    ) -> None:
+        # Fast path: no lock required if already connected.
+        if receiver_id in self.initialized_peers:
+            return
+        with self._peer_connection_lock:
+            # Double-check under the lock to prevent duplicate connections when
+            # multiple vLLM worker threads call this concurrently.
+            if receiver_id in self.initialized_peers:
+                return
+
+            receiver_init_url = f"{receiver_host}:{receiver_init_port}"
+            receiver_mem_alloc_url = f"{receiver_host}:{receiver_alloc_port}"
+
+            # Establish the connection with the receiver/decoder.
+            # The transfer channel uses an async ZMQ context (async_mode=True), so
+            # we must call the async version scheduled on the sender event loop.
+            future = asyncio.run_coroutine_threadsafe(
+                self.transfer_channel.async_lazy_init_peer_connection(
+                    local_id=self.local_id,
+                    peer_id=receiver_id,
+                    peer_init_url=receiver_init_url,
+                ),
+                self._sender_loop,
+            )
+            future.result()  # Block until connection is established
+
+            # Schedule socket creation on the sender event loop to avoid
+            # cross-thread issues
+            future = asyncio.run_coroutine_threadsafe(
+                self._async_create_alloc_socket(receiver_id, receiver_mem_alloc_url),
+                self._sender_loop,
+            )
+            future.result(timeout=10)  # Wait for socket to be created
+
+            self.initialized_peers.add(receiver_id)
+
+    async def _async_create_alloc_socket(
+        self, receiver_id: str, receiver_mem_alloc_url: str
+    ):
+        async_alloc_socket = self._async_zmq_context.socket(zmq.DEALER)
+        # Use a sender-unique identity so multiple Senders connecting to the
+        # same Receiver ROUTER have distinct identities (avoids undefined ZMQ
+        # behavior when two DEALER sockets share the same identity string).
+        sender_identity = f"{self.local_id}-to-{receiver_id}".encode()
+        async_alloc_socket.setsockopt(zmq.IDENTITY, sender_identity)
+        async_alloc_socket.connect(f"tcp://{receiver_mem_alloc_url}")
+        self._async_alloc_sockets[receiver_id] = async_alloc_socket
+
+    async def _async_remote_allocate(
+        self, receiver_id: str, alloc_request: "Union[AllocRequest, CancelNotif]"
+    ) -> AllocResponse:
+        """Send an allocation or cancellation request to the remote receiver.
+
+        :param receiver_id: The remote receiver identifier.
+        :param alloc_request: AllocRequest for allocation or CancelNotif for abort.
+        :return: AllocResponse from the receiver.
+        """
+        if receiver_id not in self._async_alloc_locks:
+            self._async_alloc_locks[receiver_id] = asyncio.Lock()
+        async with self._async_alloc_locks[receiver_id]:
+            socket = self._async_alloc_sockets[receiver_id]
+            await socket.send_multipart([b"", msgspec.msgpack.encode(alloc_request)])
+            frames = await socket.recv_multipart()
+            msg = frames[-1]
+        alloc_response = msgspec.msgpack.decode(msg, type=PDMsg)
+        return alloc_response
+
+    def _get_remote_alloc_request(
+        self,
+        keys: Sequence[CacheEngineKey],
+        mem_objs: List[MemoryObj],
+        req_id: str = "",
+        is_last_batch: bool = False,
+        total_chunks: int = 0,
+    ) -> AllocRequest:
+        """
+        Get the allocation request given the keys and memory objects.
+
+        Let's say there are N memory objects in total.
+        We have the following assumptions:
+        - The first N-1 memory objects are full chunks, each with
+        `full_chunk_size_bytes` tokens.
+        - The last memory object can be a partial chunk, which has
+        `last_chunk_toks` tokens.
+        """
+
+        fmt = mem_objs[0].meta.fmt
+        shape = mem_objs[0].meta.shape
+        dtype = TORCH_DTYPE_TO_STR_DTYPE[mem_objs[0].meta.dtype]
+        token_dim = fmt.token_dim()
+        last_chunk_toks = mem_objs[-1].meta.shape[token_dim]
+
+        str_keys = [key.to_string() for key in keys]
+
+        return AllocRequest(
+            keys=str_keys,
+            fmt=fmt.value,
+            shape=list(shape),
+            dtype=dtype,
+            last_chunk_toks=last_chunk_toks,
+            req_id=req_id,
+            is_last_batch=is_last_batch,
+            total_chunks=total_chunks,
+        )
+
+    async def _async_transfer_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        receiver_id: str,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]],
+        transfer_spec: Any = None,
+    ) -> None:
+        """Perform a single-batch KV transfer: remote alloc → RDMA write → callbacks.
+
+        Runs as an independent concurrent coroutine on _sender_loop. Multiple
+        batches for the same request may execute concurrently. ProxyNotif is
+        sent only after ALL batches for a request have completed.
+
+        :param keys: Cache keys for this batch.
+        :param memory_objs: Memory objects to transfer (already ref_count_up'd).
+        :param receiver_id: Remote receiver identifier.
+        :param on_complete_callback: Optional per-key completion callback.
+        :param transfer_spec: Carries req_id, is_last_prefill, etc.
+        """
+        completed_indexes: set[int] = set()
+        num_chunks = len(memory_objs)
+
+        req_id: str = (
+            getattr(transfer_spec, "req_id", "") if transfer_spec is not None else ""
+        )
+        is_last_batch: bool = (
+            getattr(transfer_spec, "is_last_prefill", False)
+            if transfer_spec is not None
+            else False
+        )
+
+        # Track which receiver this request is going to (for abort).
+        if req_id:
+            self._req_receiver[req_id] = receiver_id
+
+        # Lazily initialize per-request tracking on first batch seen by the
+        # sender loop.
+        if req_id and req_id not in self._req_total_chunks:
+            tc = (
+                getattr(transfer_spec, "total_chunks", 0)
+                if transfer_spec is not None
+                else 0
+            )
+            self._req_total_chunks[req_id] = tc
+            self._completed_chunks[req_id] = 0
+            self._req_has_last[req_id] = False
+            self._sent_keys[req_id] = []
+
+        try:
+            alloc_request = self._get_remote_alloc_request(
+                keys,
+                memory_objs,
+                req_id=req_id,
+                is_last_batch=is_last_batch,
+                total_chunks=self._req_total_chunks.get(req_id, 0),
+            )
+            alloc_response = await self._async_remote_allocate(
+                receiver_id, alloc_request
+            )
+            already_sent_indexes = set(alloc_response.already_sent_indexes)
+            remote_indexes = alloc_response.remote_indexes
+
+            num_keys = len(keys)
+            if already_sent_indexes:
+                if (
+                    min(already_sent_indexes) < 0
+                    or max(already_sent_indexes) >= num_keys
+                ):
+                    raise RuntimeError(
+                        f"Invalid already_sent_indexes from receiver: "
+                        f"{alloc_response.already_sent_indexes}, "
+                        f"valid range [0, {num_keys})"
+                    )
+
+            expected_send_count = num_keys - len(already_sent_indexes)
+            if len(remote_indexes) != expected_send_count:
+                raise RuntimeError(
+                    f"AllocResponse inconsistency: total_keys={num_keys}, "
+                    f"already_sent={len(already_sent_indexes)}, "
+                    f"remote_indexes={len(remote_indexes)}, "
+                    f"expected={expected_send_count}"
+                )
+
+            mem_objs_to_send: list[MemoryObj] = []
+            keys_to_send: list[CacheEngineKey] = []
+            for idx, (key, mem_obj) in enumerate(zip(keys, memory_objs, strict=True)):
+                if idx in already_sent_indexes:
+                    mem_obj.ref_count_down()
+                    completed_indexes.add(idx)
+                else:
+                    mem_objs_to_send.append(mem_obj)
+                    keys_to_send.append(key)
+
+            # Abort if any remote slot failed to allocate.
+            for idx, (mem_obj, remote_addr) in enumerate(
+                zip(mem_objs_to_send, remote_indexes, strict=True)
+            ):
+                if remote_addr == -1:
+                    logger.warning(
+                        "Receiver allocation failed for key %s (idx=%d), "
+                        "aborting entire request.",
+                        keys_to_send[idx],
+                        idx,
+                    )
+                    for j, mo in enumerate(memory_objs):
+                        if j not in completed_indexes:
+                            mo.ref_count_down()
+                            completed_indexes.add(j)
+                    if req_id:
+                        await self._abort_request(req_id)
+                    return
+
+            # Track all keys (including deduped) for abort cleanup.
+            if req_id:
+                sent = self._sent_keys.setdefault(req_id, [])
+                sent.extend(k.to_string() for k in keys)
+
+            if mem_objs_to_send:
+                channel_transfer_spec = {
+                    "receiver_id": receiver_id,
+                    "remote_indexes": remote_indexes,
+                }
+
+                await self.transfer_channel.async_batched_write(
+                    objects=mem_objs_to_send,
+                    transfer_spec=channel_transfer_spec,
+                )
+                for idx, mem_obj in enumerate(memory_objs):
+                    if idx in completed_indexes:
+                        continue
+                    before = mem_obj.get_ref_count()
+                    mem_obj.ref_count_down()
+                    logger.debug(
+                        "[SENDER] chunk %d ref_count: %d -> %d",
+                        idx,
+                        before,
+                        before - 1,
+                    )
+                    completed_indexes.add(idx)
+                logger.debug(
+                    "[SENDER] req=%s batch done, freed %d chunks, free_chunks=%d",
+                    req_id,
+                    num_chunks,
+                    self._get_free_chunks(),
+                )
+
+            # Update per-request completion tracking.
+            if req_id:
+                self._completed_chunks[req_id] = (
+                    self._completed_chunks.get(req_id, 0) + num_chunks
+                )
+                if is_last_batch:
+                    self._req_has_last[req_id] = True
+                await self._check_and_send_proxy_notif(req_id, transfer_spec)
+            elif is_last_batch:
+                # Legacy path: no req_id, send ProxyNotif immediately.
+                await self._send_proxy_notif(transfer_spec)
+
+            if on_complete_callback is not None:
+                for key in keys:
+                    try:
+                        on_complete_callback(key)
+                    except Exception as e:
+                        logger.warning(
+                            "on_complete_callback failed for key %s: %s", key, e
+                        )
+        except BaseException as e:
+            if not isinstance(e, asyncio.CancelledError):
+                logger.error(
+                    "Async transfer task failed: %s\n%s",
+                    str(e),
+                    traceback.format_exc(),
+                )
+            for idx, mem_obj in enumerate(memory_objs):
+                if idx not in completed_indexes:
+                    try:
+                        mem_obj.ref_count_down()
+                    except Exception:
+                        pass
+            # Abort the entire request so ProxyNotif is never sent
+            # for data that was never written to the receiver.
+            if req_id and not isinstance(e, asyncio.CancelledError):
+                await self._abort_request(req_id)
+            if isinstance(e, asyncio.CancelledError):
+                raise
+        finally:
+            self._notify_staging_freed()
+
+    def _notify_staging_freed(self) -> None:
+        """Wake threads blocked in allocate() so they can retry after RDMA frees memory.
+
+        Called from _async_transfer_task finally block (on sender event loop)
+        after ref_count_down() has returned buffer slots to the allocator.
+        threading.Condition.notify_all() is non-blocking and safe to call from
+        an asyncio coroutine.
+        """
+        if self.pd_config.role == "sender":
+            with self._staging_condition:
+                self._staging_condition.notify_all()
+
+    async def _check_and_send_proxy_notif(
+        self, req_id: str, transfer_spec: Any
+    ) -> None:
+        """Send ProxyNotif once all RDMA batches for req_id are complete.
+
+        Fires only when both conditions hold:
+        1. All reserved chunks have completed RDMA (completed >= total), OR
+           total_chunks==0 (legacy sender without reservation).
+        2. The is_last_prefill batch has been seen (_req_has_last is True).
+
+        :param req_id: The request identifier.
+        :param transfer_spec: Used to extract req_id for the notification.
+        """
+        total = self._req_total_chunks.get(req_id, 0)
+        completed = self._completed_chunks.get(req_id, 0)
+        has_last = self._req_has_last.get(req_id, False)
+
+        if has_last and (total == 0 or completed >= total):
+            await self._send_proxy_notif(transfer_spec)
+            # Release sender reservation now that RDMA is complete.
+            # Clean up per-request state.
+            self._completed_chunks.pop(req_id, None)
+            self._req_has_last.pop(req_id, None)
+            self._req_total_chunks.pop(req_id, None)
+            self._sent_keys.pop(req_id, None)
+            self._req_receiver.pop(req_id, None)
+
+    async def _send_proxy_notif(self, transfer_spec: Any) -> None:
+        """Encode and send a ProxyNotif to the proxy side channel.
+
+        :param transfer_spec: Provides the req_id for the notification.
+        """
+        req_id = getattr(transfer_spec, "req_id", "") if transfer_spec else ""
+        if not req_id:
+            return
+        try:
+            notif_msg = ProxyNotif(req_id=req_id)
+            notif_msg_bytes = msgspec.msgpack.encode(notif_msg)
+            async with self._proxy_send_lock:
+                await self._async_proxy_socket.send(notif_msg_bytes)
+        except Exception as e:
+            logger.error("Failed to send ProxyNotif for req %s: %s", req_id, e)
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """Submit a transfer batch as a concurrent coroutine on the sender loop.
+
+        Each batch runs as an independent concurrent coroutine — no per-receiver
+        serialization. ProxyNotif is sent after all batches for a request
+        complete (tracked via _completed_chunks and _req_has_last).
+
+        :param keys: Cache keys for this batch.
+        :param memory_objs: Memory objects to transfer.
+        :param transfer_spec: Transfer specification (carries req_id, etc.).
+        :param on_complete_callback: Optional per-key completion callback.
+        """
+        for mem_obj in memory_objs:
+            mem_obj.ref_count_up()
+
+        try:
+            receiver_init_port = transfer_spec.receiver_init_port[self.tp_rank]
+            receiver_alloc_port = transfer_spec.receiver_alloc_port[self.tp_rank]
+            receiver_id = transfer_spec.receiver_host + str(receiver_init_port)
+            receiver_host = transfer_spec.receiver_host
+
+            self._ensure_peer_connection(
+                receiver_id=receiver_id,
+                receiver_host=receiver_host,
+                receiver_init_port=receiver_init_port,
+                receiver_alloc_port=receiver_alloc_port,
+            )
+
+            asyncio.run_coroutine_threadsafe(
+                self._async_transfer_task(
+                    keys=list(keys),
+                    memory_objs=list(memory_objs),
+                    receiver_id=receiver_id,
+                    on_complete_callback=on_complete_callback,
+                    transfer_spec=transfer_spec,
+                ),
+                self._sender_loop,
+            )
+        except Exception as e:
+            for mem_obj in memory_objs:
+                try:
+                    mem_obj.ref_count_down()
+                except Exception:
+                    pass
+            logger.error(
+                "batched_submit_put_task failed, ref counts rolled back: %s", e
+            )
+            raise
+
+    def cancel_request(self, req_id: str) -> None:
+        """Cancel an in-flight or pending request.
+
+        Wakes staging allocate() waiters and schedules cleanup on
+        the sender event loop.
+
+        :param req_id: The request identifier to cancel.
+        """
+        logger.info("[CANCEL] req=%s cancel_request called", req_id)
+        if hasattr(self, "_staging_condition"):
+            with self._staging_condition:
+                self._staging_condition.notify_all()
+        if hasattr(self, "_sender_loop"):
+            asyncio.run_coroutine_threadsafe(
+                self._abort_request(req_id), self._sender_loop
+            )
+
+    async def _abort_request(self, req_id: str) -> None:
+        """Clean up request state and notify receiver of cancellation.
+
+        Sends CancelNotif to the receiver so it can release allocated
+        keys and reservation. Then clears all per-request tracking.
+
+        :param req_id: The request identifier to abort.
+        """
+        logger.info("[ABORT] req=%s _abort_request starting", req_id)
+        sent_keys = self._sent_keys.get(req_id, [])
+        if sent_keys:
+            receiver_id = self._req_receiver.get(req_id)
+            if receiver_id:
+                try:
+                    cancel_notif = CancelNotif(req_id=req_id, keys=sent_keys)
+                    await self._async_remote_allocate(receiver_id, cancel_notif)
+                except Exception as e:
+                    logger.warning(
+                        "[ABORT] req=%s failed to send CancelNotif: %s",
+                        req_id,
+                        e,
+                    )
+
+        # Clean up per-request state.
+        self._completed_chunks.pop(req_id, None)
+        self._req_has_last.pop(req_id, None)
+        self._req_total_chunks.pop(req_id, None)
+        self._sent_keys.pop(req_id, None)
+        self._req_receiver.pop(req_id, None)
+
+    ############################################################
+    # Prefiller functions end
+    ############################################################
+
+    ############################################################
+    # Decoder functions
+    ############################################################
+    async def _create_recv_primitives(self) -> None:
+        """Create asyncio primitives bound to the receiver event loop.
+
+        Must be called from within the receiver event loop.
+        """
+        self._router_send_lock = asyncio.Lock()
+        self._pending_alloc_tasks: set[asyncio.Task] = set()
+        # Initialize the async condition for reservation-based admission.
+        self._recv_reservation_mgr.init_async_admit_condition()
+        # Condition notified when remove() frees a chunk, allowing blocked
+        # allocation retries to wake up immediately instead of polling.
+        self._alloc_freed_condition: asyncio.Condition = asyncio.Condition()
+
+    def _init_receiver(self):
+        """
+        Launch the async memory allocation server coroutine on the already-running
+        receiver event loop (self._recv_loop, created before the transfer channel).
+        """
+        asyncio.run_coroutine_threadsafe(
+            self._async_mem_alloc_server(), self._recv_loop
+        )
+
+    async def _async_mem_alloc_server(self):
+        """
+        Async ZMQ ROUTER server for memory allocation requests.
+        Replaces the blocking _mem_alloc_loop / _mem_alloc_thread.
+        Uses a ROUTER socket instead of REP so that multiple concurrent
+        senders (xP1D topology) can each have their requests received and
+        dispatched independently — admission control inside
+        ``_handle_alloc_request`` only blocks the per-request coroutine, not
+        the receive loop.
+        """
+        async_ctx = zmq.asyncio.Context()
+        socket = async_ctx.socket(zmq.ROUTER)
+        alloc_port = self.pd_config.peer_alloc_port
+        socket.bind(f"tcp://*:{alloc_port}")
+        logger.info(f"Async mem alloc server listening on port {alloc_port}")
+        try:
+            while self.running:
+                try:
+                    frames = await socket.recv_multipart()
+                    # ROUTER frames: [identity, empty_delimiter, payload]
+                    identity = frames[0]
+                    payload = frames[-1]
+                    task = asyncio.create_task(
+                        self._handle_alloc_request(socket, identity, payload)
+                    )
+                    self._pending_alloc_tasks.add(task)
+                    task.add_done_callback(self._pending_alloc_tasks.discard)
+                except asyncio.CancelledError:
+                    break
+                except Exception as e:
+                    logger.error("Failed to process async mem alloc: %s", str(e))
+                    if self.running:
+                        await asyncio.sleep(0.01)
+        except asyncio.CancelledError:
+            pass
+        finally:
+            socket.close()
+            async_ctx.term()
+
+    async def _handle_alloc_request(
+        self,
+        socket: zmq.asyncio.Socket,
+        identity: bytes,
+        payload: bytes,
+    ) -> None:
+        """Handle a single allocation or cancellation request from a sender.
+
+        Dispatches AllocRequest to _async_allocate_and_put. CancelNotif
+        releases allocated keys and the receiver reservation for the request.
+
+        On any exception, sends an error AllocResponse so the sender is
+        never left waiting on recv_multipart.
+
+        :param socket: The ROUTER socket to send the response on.
+        :param identity: The sender identity frame.
+        :param payload: The raw msgpack-encoded message bytes.
+        """
+        n_keys = 0
+        try:
+            msg = msgspec.msgpack.decode(payload, type=PDMsg)
+
+            if isinstance(msg, CancelNotif):
+                # Release keys and reservation for the cancelled request.
+                req_id = msg.req_id
+                for key_str in msg.keys:
+                    try:
+                        key = CacheEngineKey.from_string(key_str)
+                        self.remove(key)
+                    except Exception as exc:
+                        logger.warning(
+                            "Failed to remove key %s during cancel for req %s: %s",
+                            key_str,
+                            req_id,
+                            exc,
+                        )
+                await self._recv_reservation_mgr.async_release_reservation(req_id)
+                self._req_allocated_keys.pop(req_id, None)
+                # Send a no-op response so the sender's recv_multipart unblocks.
+                resp = AllocResponse(remote_indexes=[])
+                async with self._router_send_lock:
+                    await socket.send_multipart(
+                        [identity, b"", msgspec.msgpack.encode(resp)]
+                    )
+                return
+
+            if not isinstance(msg, AllocRequest):
+                raise ValueError(
+                    f"Expected AllocRequest from remote peer, got {type(msg).__name__}"
+                )
+            n_keys = len(msg.keys)
+            alloc_resp = await self._async_allocate_and_put(msg)
+            resp_bytes = msgspec.msgpack.encode(alloc_resp)
+            async with self._router_send_lock:
+                await socket.send_multipart([identity, b"", resp_bytes])
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.error(
+                "Failed to process alloc request from %s: %s",
+                identity,
+                str(e),
+            )
+            try:
+                error_resp = AllocResponse(remote_indexes=[-1] * max(n_keys, 1))
+                async with self._router_send_lock:
+                    await socket.send_multipart(
+                        [identity, b"", msgspec.msgpack.encode(error_resp)]
+                    )
+            except Exception:
+                logger.warning("Failed to send error response to %s", identity)
+
+    async def _async_allocate_and_put(
+        self, alloc_request: AllocRequest
+    ) -> AllocResponse:
+        """Allocate remote memory slots and register KV objects.
+
+        Uses reservation-based admission: on the first batch for a request,
+        reserves total_chunks upfront so the buffer is never over-committed.
+        Subsequent batches draw against the existing reservation.
+
+        :param alloc_request: The allocation request from the sender.
+        :return: AllocResponse with one remote_index per key (-1 on failure).
+        :raises RuntimeError: On fail-fast overflow or allocation timeout.
+        """
+        total_allocs = len(alloc_request.keys)
+        req_id = alloc_request.req_id
+
+        # Reservation-based admission: admit on first batch for this req_id.
+        is_first_batch = req_id and (req_id not in self._req_allocated_keys)
+        if is_first_batch:
+            if alloc_request.total_chunks == 0:
+                raise RuntimeError(
+                    f"Receiver requires total_chunks > 0 for req {req_id}. "
+                    f"Legacy senders (total_chunks=0) are no longer supported."
+                )
+            admitted = await self._recv_reservation_mgr.async_try_admit(
+                req_id, alloc_request.total_chunks
+            )
+            if not admitted:
+                raise RuntimeError(
+                    f"Receiver reservation admission timed out or was aborted "
+                    f"for req {req_id} (total_chunks={alloc_request.total_chunks}). "
+                    f"Buffer may be over-subscribed."
+                )
+
+        # Fail-fast: detect if cumulative chunks exceed declared total_chunks.
+        if req_id:
+            prev_count = len(self._req_allocated_keys.get(req_id, []))
+            new_total = prev_count + total_allocs
+
+            if new_total > alloc_request.total_chunks:
+                # Rollback any prior batches
+                prior_keys = self._req_allocated_keys.get(req_id, [])
+                for prior_key_str in prior_keys:
+                    try:
+                        self.remove(CacheEngineKey.from_string(prior_key_str))
+                    except Exception as e:
+                        logger.warning(
+                            "Rollback failed for key %s: %s", prior_key_str, e
+                        )
+
+                # Clean up tracking and release reservation
+                self._req_allocated_keys.pop(req_id, None)
+                await self._recv_reservation_mgr.async_release_reservation(req_id)
+                raise RuntimeError(
+                    f"Request {req_id} protocol violation: declared total_chunks="
+                    f"{alloc_request.total_chunks} but attempting {new_total} chunks."
+                )
+        else:
+            logger.debug(
+                "AllocRequest has no req_id — per-request chunk accounting "
+                "is disabled for this batch"
+            )
+
+        fmt = MemoryFormat(alloc_request.fmt)
+        dtype = STR_DTYPE_TO_TORCH_DTYPE[alloc_request.dtype]
+        shape = list(alloc_request.shape)
+
+        alloc_indexes: list[int] = []
+        already_sent_indexes: list[int] = []
+        current_batch_keys: list[str] = []
+
+        try:
+            for idx, key_str in enumerate(alloc_request.keys):
+                key = CacheEngineKey.from_string(key_str)
+                if self.contains(key, pin=True):
+                    already_sent_indexes.append(idx)
+                    current_batch_keys.append(key_str)
+                    continue
+
+                if idx == total_allocs - 1:
+                    token_dim = fmt.token_dim()
+                    shape[token_dim] = alloc_request.last_chunk_toks
+
+                mem_obj = self.allocate(torch.Size(shape), dtype, fmt)
+                deadline = asyncio.get_running_loop().time() + self._allocation_timeout
+                while mem_obj is None:
+                    remaining = deadline - asyncio.get_running_loop().time()
+                    if remaining <= 0:
+                        raise RuntimeError(
+                            f"Failed to allocate memory for key {key} after "
+                            f"timeout (~{self._allocation_timeout:.0f}s). "
+                            f"req_id={req_id}, key_index={idx}/{total_allocs}."
+                        )
+                    async with self._alloc_freed_condition:
+                        try:
+                            await asyncio.wait_for(
+                                self._alloc_freed_condition.wait(),
+                                timeout=min(remaining, self._condition_poll_interval),
+                            )
+                        except asyncio.TimeoutError:
+                            pass
+                    mem_obj = self.allocate(torch.Size(shape), dtype, fmt)
+
+                alloc_indexes.append(mem_obj.meta.address)
+                self.put(key, mem_obj)
+                logger.debug(
+                    "[RECEIVER] alloc key=%s addr=%d ref_count=%d",
+                    key_str,
+                    mem_obj.meta.address,
+                    mem_obj.get_ref_count(),
+                )
+
+                current_batch_keys.append(key_str)
+                logger.debug(
+                    "[PD-ALLOC] req=%s alloc chunk %d/%d, free_chunks=%d, data_size=%d",
+                    req_id,
+                    idx + 1,
+                    total_allocs,
+                    self._get_free_chunks(),
+                    len(self.data),
+                )
+        except BaseException:
+            # Rollback: remove chunks from the current batch.
+            for rollback_key_str in current_batch_keys:
+                try:
+                    rollback_key = CacheEngineKey.from_string(rollback_key_str)
+                    self.remove(rollback_key)
+                except Exception as re:
+                    logger.warning(
+                        "Rollback remove failed for key %s: %s",
+                        rollback_key_str,
+                        re,
+                    )
+
+            # If this request has prior successful batches, clean them up too.
+            # Any batch failure means the entire request is invalid since the
+            # decoder needs all chunks to proceed.
+            if req_id:
+                prior_keys = self._req_allocated_keys.get(req_id, [])
+                if prior_keys:
+                    logger.warning(
+                        "[PD-ALLOC] req=%s batch failed, rolling back %d chunks "
+                        "from prior batches",
+                        req_id,
+                        len(prior_keys),
+                    )
+                    for prior_key_str in prior_keys:
+                        try:
+                            prior_key = CacheEngineKey.from_string(prior_key_str)
+                            self.remove(prior_key)
+                        except Exception as re:
+                            logger.warning(
+                                "Rollback remove failed for prior key %s: %s",
+                                prior_key_str,
+                                re,
+                            )
+
+                # Clean up tracking and release reservation.
+                self._req_allocated_keys.pop(req_id, None)
+                await self._recv_reservation_mgr.async_release_reservation(req_id)
+            raise
+
+        # All allocations succeeded.
+        if req_id:
+            if req_id not in self._req_allocated_keys:
+                self._req_allocated_keys[req_id] = []
+            self._req_allocated_keys[req_id].extend(current_batch_keys)
+            if alloc_request.is_last_batch:
+                self._req_allocated_keys.pop(req_id, None)
+                await self._recv_reservation_mgr.async_release_reservation(req_id)
+
+        return AllocResponse(
+            remote_indexes=alloc_indexes, already_sent_indexes=already_sent_indexes
+        )
+
+    def put(
+        self,
+        key: CacheEngineKey,
+        mem_obj: MemoryObj,
+    ) -> None:
+        """Store a memory object in the local data dictionary."""
+        with self.data_lock:
+            if key in self.data:
+                logger.info(
+                    "Duplicate put for key %s in PDBackendAsync.put(); "
+                    "dropping new object.",
+                    key,
+                )
+                mem_obj.ref_count_down()
+                return
+            self.data[key] = mem_obj
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Retrieve the memory object for the given key (blocking).
+
+        Since PDBackendAsync uses push-based transfer, the key is expected to
+        already be present in local data.
+
+        :param key: The cache engine key to retrieve.
+        :return: The corresponding MemoryObj.
+        :rtype: MemoryObj
+        :raises AssertionError: If the key is not found in local data.
+        """
+        with self.data_lock:
+            # NOTE(Jiayi): we assume that the key must be in local data
+            # because we are using a push-based transfer
+            mem_obj = self.data.get(key, None)
+            assert mem_obj is not None, f"Key {key} not found in local data."
+            return mem_obj
+
+    def remove(
+        self,
+        key: CacheEngineKey,
+        force: bool = True,
+    ) -> bool:
+        """
+        Remove the key from the storage backend.
+
+        :param key: The key to remove.
+        """
+        with self.data_lock:
+            mem_obj = self.data.get(key, None)
+            if mem_obj is not None:
+                before_rc = mem_obj.get_ref_count()
+                mem_obj.ref_count_down()
+                deleted = False
+                if mem_obj.get_ref_count() == 0:
+                    del self.data[key]
+                    logger.debug(
+                        "[PD-FREE] remove key=%s, addr=%d, ref_count_before=%d, "
+                        "data_size=%d, free_chunks_before=%d",
+                        key,
+                        mem_obj.meta.address,
+                        before_rc,
+                        len(self.data),
+                        self._get_free_chunks(),
+                    )
+                    deleted = True
+                # Notify any coroutines blocked waiting for free memory.
+                # _alloc_freed_condition and _recv_loop only exist on the
+                # receiver; remove() is also called on the sender, so the
+                # hasattr guards are intentional.  run_coroutine_threadsafe is
+                # used because remove() may be called from any OS thread while
+                # the receiver event loop runs on a dedicated thread.
+                if (
+                    deleted
+                    and hasattr(self, "_alloc_freed_condition")
+                    and hasattr(self, "_recv_loop")
+                ):
+                    loop = self._recv_loop
+                    if loop.is_running():
+
+                        async def _notify_freed() -> None:
+                            async with self._alloc_freed_condition:
+                                self._alloc_freed_condition.notify_all()
+
+                        asyncio.run_coroutine_threadsafe(_notify_freed(), loop)
+                return True
+            logger.debug("[PD-FREE] remove: key=%s NOT FOUND", key)
+            return False
+
+    def _get_free_chunks(self) -> int:
+        """Return number of free chunks in the PD buffer allocator.
+
+        Reads ``free_blocks`` from the appropriate underlying allocator
+        (CPU or GPU depending on ``corrected_device``).  This is a
+        best-effort diagnostic value: it is read without holding any
+        additional lock, so the count may be stale by the time it is logged.
+
+        :return: Number of currently free blocks in the allocator, or -1 if
+            the allocator does not expose a ``free_blocks`` attribute.
+        :rtype: int
+        """
+        alloc = (
+            self.memory_allocator.cpu_allocator
+            if self.corrected_device == "cpu"
+            else self.memory_allocator.gpu_allocator
+        )
+        try:
+            return len(alloc.free_blocks)
+        except AttributeError:
+            return -1
+
+    def _get_total_chunks(self) -> int:
+        """Return total number of chunks in the PD buffer.
+
+        Computed as ``_aligned_buffer_size // _chunk_size_bytes``.
+
+        :return: Total number of fixed-size chunks in the PD buffer.
+        :rtype: int
+        """
+        return self._aligned_buffer_size // self._chunk_size_bytes
+
+    ############################################################
+    # Decoder functions end
+    ############################################################
+
+    @staticmethod
+    def _shutdown_loop(
+        loop: asyncio.AbstractEventLoop,
+        thread: threading.Thread,
+        timeout: float = 5.0,
+    ) -> None:
+        """Cancel all pending tasks on *loop*, stop it, and join the thread.
+
+        Uses a ``threading.Event`` to synchronize shutdown completion so that
+        ``thread.join`` is only called after the loop has actually stopped,
+        preventing thread or resource leaks when the loop takes time to drain.
+
+        :param loop: The event loop to shut down.
+        :param thread: The thread running the event loop.
+        :param timeout: Maximum seconds to wait for shutdown and thread join.
+        """
+        shutdown_done = threading.Event()
+
+        async def _cancel_and_stop() -> None:
+            tasks = [
+                t
+                for t in asyncio.all_tasks(loop)
+                if t is not asyncio.current_task() and not t.done()
+            ]
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            loop.stop()
+            shutdown_done.set()
+
+        if loop.is_running():
+            loop.call_soon_threadsafe(loop.create_task, _cancel_and_stop())
+            shutdown_done.wait(timeout=timeout)
+        thread.join(timeout=timeout)
+        if thread.is_alive():
+            logger.warning(
+                "Event loop thread %s did not terminate within %.1fs timeout.",
+                thread.name,
+                timeout,
+            )
+
+    def close(self) -> None:
+        """
+        Close the storage backend.
+        """
+        self.running = False
+        # Wake up any threads blocked on the sender staging condition so they
+        # can observe running=False and exit cleanly.
+        if hasattr(self, "_staging_condition"):
+            with self._staging_condition:
+                self._staging_condition.notify_all()
+        for thread in self.running_threads:
+            thread.join()
+        # Shut down sender async loop if present
+        if hasattr(self, "_sender_loop"):
+            self._shutdown_loop(
+                self._sender_loop,
+                self._sender_thread,
+                timeout=self.pd_config.shutdown_timeout_sec,
+            )
+            # Close async alloc sockets
+            for sock in self._async_alloc_sockets.values():
+                try:
+                    sock.close()
+                except Exception:
+                    pass
+            try:
+                self._async_zmq_context.term()
+            except Exception:
+                pass
+        # Shut down receiver async loop if present
+        if hasattr(self, "_recv_loop"):
+            # Wait for any in-flight allocation tasks to finish gracefully
+            # before tearing down the loop.
+            if hasattr(self, "_pending_alloc_tasks"):
+                try:
+
+                    async def _wait_pending() -> None:
+                        """Await all pending alloc tasks with a timeout."""
+                        pending = list(self._pending_alloc_tasks)
+                        if pending:
+                            await asyncio.wait(
+                                pending,
+                                timeout=self.pd_config.shutdown_timeout_sec,
+                            )
+
+                    future = asyncio.run_coroutine_threadsafe(
+                        _wait_pending(), self._recv_loop
+                    )
+                    future.result(timeout=self.pd_config.shutdown_timeout_sec + 1)
+                except Exception:
+                    logger.debug(
+                        "Timed out waiting for pending alloc tasks during shutdown"
+                    )
+            self._shutdown_loop(
+                self._recv_loop,
+                self._recv_thread,
+                timeout=self.pd_config.shutdown_timeout_sec,
+            )
+        self.transfer_channel.close()
+        self.zmq_context.term()
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        """Pin the memory object for the given key to prevent eviction.
+
+        PDBackendAsync has no eviction mechanism, so this is a no-op that
+        always returns True.
+
+        :param key: The cache engine key to pin.
+        :return: Always True.
+        :rtype: bool
+        """
+        return True
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        """Unpin the memory object for the given key.
+
+        PDBackendAsync has no eviction mechanism, so this is a no-op that
+        always returns True.
+
+        :param key: The cache engine key to unpin.
+        :return: Always True.
+        :rtype: bool
+        """
+        return True
diff --git a/lmcache/v1/storage_backend/plugins/dax_backend.py b/lmcache/v1/storage_backend/plugins/dax_backend.py
new file mode 100644
index 0000000..bbcf940
--- /dev/null
+++ b/lmcache/v1/storage_backend/plugins/dax_backend.py
@@ -0,0 +1,917 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections import OrderedDict
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional, Sequence, cast
+import asyncio
+import ctypes
+import os
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import StoragePluginInterface
+from lmcache.v1.storage_backend.dax.core import DaxCore
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+import lmcache.c_ops as lmc_ops
+
+logger = init_logger(__name__)
+
+
+def _to_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return False
+    return str(value).strip().lower() in {"true", "1", "yes", "on"}
+
+
+@dataclass
+class _RestoreItem:
+    """Reserved DAX read metadata for one item in a batched restore."""
+
+    result_index: int
+    key: CacheEngineKey
+    offset: int
+    size: int
+    shape: torch.Size
+    dtype: torch.dtype
+    fmt: MemoryFormat
+    cached_positions: Optional[torch.Tensor]
+    slot_id: int
+    generation: int
+    memory_obj: Optional[MemoryObj] = None
+    slab_offset: int = 0
+
+
+@dataclass
+class _RestoreSpan:
+    """One contiguous source span copied from DAX into the staging slab."""
+
+    src_offset: int
+    slab_offset: int
+    size: int
+
+
+@dataclass
+class _RestoreRegion:
+    """One restore region executed by a persistent worker."""
+
+    region_index: int
+    slab_offset: int
+    total_bytes: int
+    items: list[_RestoreItem]
+    spans: list[_RestoreSpan]
+
+
+@dataclass
+class _RestoreWave:
+    """One wave of region work against the fixed-size retrieve slab."""
+
+    regions: list[_RestoreRegion]
+
+
+class DaxBackend(StoragePluginInterface):
+    """Storage plugin backend for /dev/dax mmap-backed KV cache."""
+
+    def __init__(
+        self,
+        config: Optional[LMCacheEngineConfig] = None,
+        metadata: Optional[LMCacheMetadata] = None,
+        local_cpu_backend: Optional[LocalCPUBackend] = None,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        dst_device: str = "cpu",
+    ) -> None:
+        """Initialize a non-MP DAX storage backend.
+
+        Args:
+            config: LMCache engine config containing ``dax.*`` extra config.
+            metadata: Runtime metadata used to validate TP and KV layout.
+            local_cpu_backend: CPU allocator used for restore outputs.
+            loop: Event loop used when ``dax.async_put`` is enabled.
+            dst_device: Destination device name passed to the base backend.
+
+        Raises:
+            ValueError: If required config, metadata, local CPU backend, or
+                DAX options are missing or unsupported.
+            RuntimeError: If the DAX arena cannot be opened or mapped.
+        """
+        super().__init__(
+            dst_device=dst_device,
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop,
+        )
+        if self.config is None:
+            raise ValueError("DaxBackend requires config")
+        if self.metadata is None:
+            raise ValueError("DaxBackend requires metadata")
+
+        if self.metadata.world_size != 1:
+            raise ValueError(
+                "DaxBackend currently only supports TP=1 "
+                f"(world_size={self.metadata.world_size})"
+            )
+        if self.metadata.get_num_groups() != 1:
+            raise ValueError(
+                "DaxBackend currently supports only single-group KV layout"
+            )
+
+        extra = self.config.extra_config or {}
+        self.device_path = str(extra.get("dax.device_path", "")).strip()
+        if not self.device_path:
+            raise ValueError("extra_config['dax.device_path'] is required")
+
+        self.async_put = _to_bool(extra.get("dax.async_put", False))
+        if self.async_put and self.loop is None:
+            raise ValueError("DaxBackend async_put=true requires an asyncio event loop")
+
+        self.max_dax_size = float(extra.get("dax.max_dax_size", 0))
+        if self.max_dax_size <= 0:
+            raise ValueError("extra_config['dax.max_dax_size'] must be > 0")
+
+        if self.local_cpu_backend is None:
+            raise ValueError("DaxBackend requires local_cpu_backend")
+
+        self._close_lock = threading.Lock()
+        self._closing = False
+        self._closed = False
+
+        self._restore_executor: Optional[ThreadPoolExecutor] = None
+        self._restore_dispatch_executor: Optional[ThreadPoolExecutor] = None
+        self._retrieve_staging_slab_ptr: int = 0
+        self._retrieve_staging_slab_bytes: int = 0
+        self._restore_region_bytes: int = 0
+        self._restore_workers: int = 0
+        self._restore_max_regions: int = 0
+
+        full_chunk_size = int(self.local_cpu_backend.get_full_chunk_size_bytes())
+        self._core = DaxCore[CacheEngineKey](
+            device_path=self.device_path,
+            max_dax_size_bytes=int(self.max_dax_size * 1024**3),
+            slot_bytes=max(1, full_chunk_size),
+        )
+        self.slot_bytes = self._core.slot_bytes
+        self._arena_bytes = self._core.arena_bytes
+        self._max_slots = self._core.max_slots
+
+        try:
+            default_restore_workers = min(8, max(1, os.cpu_count() or 1))
+            self._restore_workers = self._get_positive_int_extra(
+                extra,
+                "dax.restore_workers",
+                default_restore_workers,
+            )
+            self._restore_max_regions = self._get_positive_int_extra(
+                extra,
+                "dax.restore_max_regions",
+                self._restore_workers,
+            )
+            default_staging_slab_bytes = max(
+                256 * 1024 * 1024,
+                self._restore_max_regions * self.slot_bytes,
+            )
+            self._retrieve_staging_slab_bytes = self._get_positive_int_extra(
+                extra,
+                "dax.retrieve_staging_slab_bytes",
+                default_staging_slab_bytes,
+            )
+            min_required_slab = self._restore_max_regions * self.slot_bytes
+            if self._retrieve_staging_slab_bytes < min_required_slab:
+                raise ValueError(
+                    "extra_config['dax.retrieve_staging_slab_bytes'] must be at "
+                    f"least {min_required_slab} bytes"
+                )
+            self._restore_region_bytes = (
+                self._retrieve_staging_slab_bytes // self._restore_max_regions
+            )
+            if self._restore_region_bytes < self.slot_bytes:
+                raise ValueError(
+                    "dax.retrieve_staging_slab_bytes does not leave enough space "
+                    "per restore region for one full chunk"
+                )
+
+            self._retrieve_staging_slab_ptr = int(
+                lmc_ops.alloc_pinned_ptr(self._retrieve_staging_slab_bytes, 0)
+            )
+            self._restore_executor = ThreadPoolExecutor(
+                max_workers=self._restore_workers,
+                thread_name_prefix="dax-restore",
+            )
+            self._restore_dispatch_executor = ThreadPoolExecutor(
+                max_workers=1,
+                thread_name_prefix="dax-restore-dispatch",
+            )
+        except Exception:
+            self._release_restore_resources()
+            self._core.close()
+            raise
+
+        logger.info(
+            "DaxBackend init: device=%s dax_size=%d slot=%d max_slots=%d "
+            "restore_workers=%d restore_regions=%d restore_slab=%d",
+            self.device_path,
+            self._arena_bytes,
+            self.slot_bytes,
+            self._max_slots,
+            self._restore_workers,
+            self._restore_max_regions,
+            self._retrieve_staging_slab_bytes,
+        )
+
+    def __str__(self) -> str:
+        return "DaxBackend"
+
+    @property
+    def _fd(self) -> Optional[int]:
+        return self._core.fd
+
+    @property
+    def _mmap_obj(self):
+        return self._core.mmap_obj
+
+    @property
+    def _base_ptr(self) -> int:
+        return self._core.base_ptr
+
+    @property
+    def _arena_view(self) -> Optional[memoryview]:
+        return self._core.arena_view
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """Check whether ``key`` exists in the backend.
+
+        Args:
+            key: The cache key to look up.
+            pin: If ``True`` and the key is present, atomically
+                increment its external lock count.
+
+        Returns:
+            ``True`` if the key is present, ``False`` otherwise.
+        """
+        return self._core.exists_many([key], lock=pin)[0]
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """Check whether ``key`` is tracked as an in-flight put task.
+
+        Args:
+            key: The cache key to check.
+
+        Returns:
+            ``True`` if ``key`` is in the in-flight put task set.
+        """
+        return self._core.has_inflight(key)
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        """Increment the external lock count for ``key`` if it exists.
+
+        Args:
+            key: The cache key to pin.
+
+        Returns:
+            ``True`` if the key was found and pinned, ``False`` otherwise.
+        """
+        return self._core.exists_many([key], lock=True)[0]
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        """Decrement the external lock count for ``key``.
+
+        Args:
+            key: The cache key to unpin.
+
+        Returns:
+            ``True`` if ``key`` is present in the backend after the
+            operation, ``False`` otherwise.
+        """
+        self._core.unlock_many([key])
+        return self._core.exists_many([key], lock=False)[0]
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        """Remove ``key`` from the backend if present.
+
+        If the key is in-flight, it is marked canceled. If it is
+        committed, its slot is scheduled for reclamation according to
+        the current slot state.
+
+        Args:
+            key: The cache key to remove.
+            force: If ``False``, pinned keys are left untouched. If
+                ``True``, the key is removed even when externally locked.
+
+        Returns:
+            ``True`` if the key was present or in-flight and removal was
+            scheduled, ``False`` otherwise.
+        """
+        return self._core.delete_many([key], force=force)[0]
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Optional[List[Future]]:
+        """Store a batch of memory objects in the DAX arena.
+
+        Args:
+            keys: Cache keys to store.
+            objs: Memory objects whose contents are copied into DAX slots.
+            transfer_spec: Transfer hint accepted for interface compatibility
+                and ignored by this backend.
+            on_complete_callback: Optional callback invoked for each key that
+                is newly committed.
+
+        Returns:
+            Async put futures when ``dax.async_put`` schedules work on the
+            configured event loop; otherwise ``None``.
+
+        Raises:
+            ValueError: If input lengths differ or an object exceeds the slot
+                size.
+            RuntimeError: If the backend is closing or a synchronous DAX write
+                cannot be committed.
+        """
+        del transfer_spec
+        if len(keys) != len(objs):
+            raise ValueError(
+                "keys and objs must have the same length, "
+                f"got {len(keys)} and {len(objs)}"
+            )
+        if self._is_closed_or_closing():
+            raise RuntimeError("DaxBackend is closing")
+
+        futures: list[Future] = []
+        for key, obj in zip(keys, objs, strict=True):
+            num_shapes = len(obj.get_shapes())
+            if num_shapes > 1:
+                logger.error(
+                    "DaxBackend does not support multi-tensor allocations: "
+                    "key=%s has %d tensors. "
+                    "Use single-tensor format or extend metadata.",
+                    key,
+                    num_shapes,
+                )
+                continue
+
+            size = int(obj.get_size())
+            if size > self.slot_bytes:
+                raise ValueError(
+                    f"DaxBackend: object size {size} for key {key} "
+                    f"exceeds slot size {self.slot_bytes}"
+                )
+
+            # Preserve current overwrite posture: duplicates are a no-op success
+            # without firing completion callbacks.
+            if self.contains(key) or self.exists_in_put_tasks(key):
+                continue
+
+            if self.async_put and self.loop is not None and self.loop.is_running():
+                obj.ref_count_up()
+                try:
+                    future = asyncio.run_coroutine_threadsafe(
+                        self._submit_write(
+                            key=key,
+                            memory_obj=obj,
+                            on_complete_callback=on_complete_callback,
+                        ),
+                        self.loop,
+                    )
+                except Exception:
+                    obj.ref_count_down()
+                    raise
+                futures.append(future)
+                continue
+
+            committed = self._core.put_one(
+                key,
+                obj,
+                writer=lambda offset, memory_obj, copy_size: self._do_write(
+                    offset,
+                    memory_obj,
+                    copy_size,
+                ),
+            )
+            if committed:
+                self._invoke_on_complete_callback(key, on_complete_callback)
+
+        return futures or None
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Load one key from DAX into a CPU memory object.
+
+        Args:
+            key: Cache key to retrieve.
+
+        Returns:
+            Restored ``MemoryObj`` if the key is present and can be read;
+            otherwise ``None``.
+
+        Raises:
+            RuntimeError: If CPU allocation or DAX copy fails after the key is
+                reserved.
+        """
+        if self._is_closed_or_closing():
+            return None
+
+        reservations, _ = self._core.reserve_reads([key], prefix_only=False)
+        if not reservations:
+            return None
+
+        reservation = reservations[0]
+        assert self.local_cpu_backend is not None
+
+        memory_obj: Optional[MemoryObj] = None
+        touched_keys: set[CacheEngineKey] = set()
+        try:
+            memory_obj = self.local_cpu_backend.allocate(
+                reservation.shape,
+                reservation.dtype,
+                reservation.fmt,
+            )
+            if memory_obj is None:
+                return None
+
+            self._do_read(reservation.offset, memory_obj, reservation.size)
+            memory_obj.metadata.cached_positions = reservation.cached_positions
+            touched_keys.add(key)
+            return memory_obj
+        except Exception:
+            if memory_obj is not None:
+                memory_obj.ref_count_down()
+            raise
+        finally:
+            self._core.finalize_reads(reservations, touched_keys)
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Return the number of consecutive keys present in the index.
+
+        Iterates ``keys`` in order and stops at the first miss.
+
+        Args:
+            lookup_id: Caller-supplied identifier (not used by this backend).
+            keys: Ordered list of cache keys to check.
+            pin: If ``True``, externally lock each found key.
+
+        Returns:
+            The count of consecutive hits from the start of ``keys``.
+        """
+        del lookup_id
+        return self.batched_contains(keys, pin=pin)
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        """Retrieve memory objects for consecutive keys asynchronously.
+
+        Schedules one batched restore job on the persistent dispatch
+        executor and returns only the consecutive hit prefix. Stops at the
+        first key that is not found or is no longer readable.
+
+        Args:
+            lookup_id: Caller-supplied identifier (not used by this backend).
+            keys: Ordered list of cache keys to retrieve.
+            transfer_spec: Transfer hint (not used by this backend).
+
+        Returns:
+            A list of ``MemoryObj`` instances for the consecutive hits.
+        """
+        del lookup_id, transfer_spec
+        if not keys or self._is_closed_or_closing():
+            return []
+
+        dispatch_executor = self._restore_dispatch_executor
+        if dispatch_executor is None:
+            raise RuntimeError("DaxBackend restore dispatch executor is not available")
+
+        loop = asyncio.get_running_loop()
+        result = await loop.run_in_executor(
+            dispatch_executor,
+            self._restore_batch,
+            list(keys),
+            True,
+        )
+        return cast(list[MemoryObj], result)
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """Restore a batch of DAX-backed cache entries synchronously.
+
+        The returned list preserves the input order. Entries that are missing
+        or no longer readable remain ``None`` so callers keep positional
+        alignment with ``keys``.
+
+        Args:
+            keys: Ordered cache keys to restore from the DAX arena.
+
+        Returns:
+            A list aligned with ``keys`` containing restored ``MemoryObj``
+            instances or ``None`` for entries that could not be read.
+        """
+        if not keys or self._is_closed_or_closing():
+            return []
+
+        dispatch_executor = self._restore_dispatch_executor
+        if dispatch_executor is None:
+            raise RuntimeError("DaxBackend restore dispatch executor is not available")
+
+        batch_keys = list(keys)
+        if threading.current_thread().name.startswith("dax-restore-dispatch"):
+            return cast(
+                List[Optional[MemoryObj]],
+                self._restore_batch(batch_keys, False),
+            )
+
+        future = dispatch_executor.submit(self._restore_batch, batch_keys, False)
+        return cast(List[Optional[MemoryObj]], future.result())
+
+    def batched_contains(
+        self,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        """Return the number of consecutive keys present in the index.
+
+        Synchronous variant of :meth:`batched_async_contains`.
+
+        Args:
+            keys: Ordered list of cache keys to check.
+            pin: If ``True``, externally lock each found key.
+
+        Returns:
+            The count of consecutive hits from the start of ``keys``.
+        """
+        hit_count = 0
+        for key in keys:
+            if not self._core.exists_many([key], lock=pin)[0]:
+                break
+            hit_count += 1
+        return hit_count
+
+    def batched_remove(
+        self,
+        keys: list[CacheEngineKey],
+        force: bool = True,
+    ) -> int:
+        """Remove multiple keys from the backend.
+
+        Args:
+            keys: The cache keys to remove.
+            force: Passed through to :meth:`remove`.
+
+        Returns:
+            The number of keys that were actually present and removed.
+        """
+        return sum(self._core.delete_many(keys, force=force))
+
+    def get_allocator_backend(self) -> LocalCPUBackend:
+        """Return the CPU allocator backend used for read buffers.
+
+        Raises:
+            RuntimeError: If no ``local_cpu_backend`` is available.
+        """
+        if self.local_cpu_backend is None:
+            raise RuntimeError("DaxBackend has no allocator backend available")
+        return self.local_cpu_backend
+
+    def close(self) -> None:
+        """Release restore workers, staging buffers, and DAX resources."""
+        with self._close_lock:
+            if self._closed:
+                return
+            self._closing = True
+
+        self._release_restore_resources()
+        self._core.close()
+
+        with self._close_lock:
+            self._closed = True
+
+    @staticmethod
+    def _get_positive_int_extra(
+        extra_config: dict[str, Any],
+        key: str,
+        default: int,
+    ) -> int:
+        value = extra_config.get(key, default)
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"extra_config['{key}'] must be a positive integer"
+            ) from exc
+        if parsed <= 0:
+            raise ValueError(f"extra_config['{key}'] must be a positive integer")
+        return parsed
+
+    def _is_closed_or_closing(self) -> bool:
+        with self._close_lock:
+            return self._closing or self._closed
+
+    def _release_restore_resources(self) -> None:
+        dispatch_executor = self._restore_dispatch_executor
+        self._restore_dispatch_executor = None
+        if dispatch_executor is not None:
+            dispatch_executor.shutdown(wait=True)
+
+        restore_executor = self._restore_executor
+        self._restore_executor = None
+        if restore_executor is not None:
+            restore_executor.shutdown(wait=True)
+
+        if self._retrieve_staging_slab_ptr:
+            try:
+                lmc_ops.free_pinned_ptr(self._retrieve_staging_slab_ptr)
+            except Exception as exc:
+                logger.warning("Failed to free DAX retrieve slab: %s", exc)
+
+        self._retrieve_staging_slab_ptr = 0
+        self._retrieve_staging_slab_bytes = 0
+        self._restore_region_bytes = 0
+
+    def _invoke_on_complete_callback(
+        self,
+        key: CacheEngineKey,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]],
+    ) -> None:
+        if on_complete_callback is None:
+            return
+        try:
+            on_complete_callback(key)
+        except Exception as exc:
+            logger.warning("on_complete_callback failed for key %s: %s", key, exc)
+
+    def _do_write(self, offset: int, memory_obj: MemoryObj, size: int) -> None:
+        ctypes.memmove(
+            ctypes.c_void_p(self._base_ptr + offset),
+            ctypes.c_void_p(memory_obj.data_ptr),
+            size,
+        )
+
+    def _do_read(self, offset: int, memory_obj: MemoryObj, size: int) -> None:
+        ctypes.memmove(
+            ctypes.c_void_p(memory_obj.data_ptr),
+            ctypes.c_void_p(self._base_ptr + offset),
+            size,
+        )
+
+    def _batched_memcpy(
+        self,
+        src_ptrs: Sequence[int],
+        dst_ptrs: Sequence[int],
+        sizes: Sequence[int],
+    ) -> None:
+        if not src_ptrs:
+            return
+        if hasattr(lmc_ops, "batched_memcpy"):
+            lmc_ops.batched_memcpy(list(src_ptrs), list(dst_ptrs), list(sizes))
+            return
+
+        for src_ptr, dst_ptr, size in zip(src_ptrs, dst_ptrs, sizes, strict=True):
+            ctypes.memmove(
+                ctypes.c_void_p(dst_ptr),
+                ctypes.c_void_p(src_ptr),
+                size,
+            )
+
+    def _allocate_restore_outputs(self, reserved: Sequence[_RestoreItem]) -> None:
+        assert self.local_cpu_backend is not None
+
+        grouped_items: OrderedDict[
+            tuple[tuple[int, ...], torch.dtype, MemoryFormat], list[_RestoreItem]
+        ] = OrderedDict()
+        for item in reserved:
+            grouped_items.setdefault(
+                (tuple(item.shape), item.dtype, item.fmt),
+                [],
+            ).append(item)
+
+        for group_items in grouped_items.values():
+            first = group_items[0]
+            outputs: Optional[list[MemoryObj]] = None
+            if len(group_items) > 1:
+                outputs = self.local_cpu_backend.batched_allocate(
+                    first.shape,
+                    first.dtype,
+                    len(group_items),
+                    first.fmt,
+                )
+
+            if outputs is None:
+                outputs = []
+                for _ in group_items:
+                    memory_obj = self.local_cpu_backend.allocate(
+                        first.shape,
+                        first.dtype,
+                        first.fmt,
+                    )
+                    if memory_obj is None:
+                        for allocated in outputs:
+                            allocated.ref_count_down()
+                        raise RuntimeError(
+                            "DaxBackend batched restore allocation failed"
+                        )
+                    outputs.append(memory_obj)
+
+            for item, memory_obj in zip(group_items, outputs, strict=True):
+                item.memory_obj = memory_obj
+
+    def _build_restore_waves(
+        self,
+        reserved: Sequence[_RestoreItem],
+    ) -> list[_RestoreWave]:
+        if not reserved:
+            return []
+
+        sorted_items = sorted(reserved, key=lambda item: item.offset)
+        waves: list[_RestoreWave] = []
+        next_item_idx = 0
+
+        while next_item_idx < len(sorted_items):
+            regions: list[_RestoreRegion] = []
+            for region_index in range(self._restore_max_regions):
+                if next_item_idx >= len(sorted_items):
+                    break
+
+                region_items: list[_RestoreItem] = []
+                region_spans: list[_RestoreSpan] = []
+                used_bytes = 0
+
+                while next_item_idx < len(sorted_items):
+                    item = sorted_items[next_item_idx]
+                    if item.size > self._restore_region_bytes:
+                        raise RuntimeError(
+                            f"DaxBackend restore item size {item.size} exceeds "
+                            "region capacity "
+                            f"{self._restore_region_bytes}"
+                        )
+                    if (
+                        used_bytes > 0
+                        and used_bytes + item.size > self._restore_region_bytes
+                    ):
+                        break
+
+                    item.slab_offset = used_bytes
+                    region_items.append(item)
+                    if (
+                        region_spans
+                        and region_spans[-1].src_offset + region_spans[-1].size
+                        == item.offset
+                        and region_spans[-1].slab_offset + region_spans[-1].size
+                        == item.slab_offset
+                    ):
+                        region_spans[-1].size += item.size
+                    else:
+                        region_spans.append(
+                            _RestoreSpan(
+                                src_offset=item.offset,
+                                slab_offset=item.slab_offset,
+                                size=item.size,
+                            )
+                        )
+
+                    used_bytes += item.size
+                    next_item_idx += 1
+
+                regions.append(
+                    _RestoreRegion(
+                        region_index=region_index,
+                        slab_offset=region_index * self._restore_region_bytes,
+                        total_bytes=used_bytes,
+                        items=region_items,
+                        spans=region_spans,
+                    )
+                )
+
+            waves.append(_RestoreWave(regions=regions))
+
+        return waves
+
+    def _restore_region(self, region: _RestoreRegion) -> None:
+        if region.total_bytes <= 0 or not region.items:
+            return
+        if self._retrieve_staging_slab_ptr == 0:
+            raise RuntimeError("DaxBackend retrieve slab is not allocated")
+
+        slab_base_ptr = self._retrieve_staging_slab_ptr + region.slab_offset
+        dax_src_ptrs = [self._base_ptr + span.src_offset for span in region.spans]
+        slab_dst_ptrs = [slab_base_ptr + span.slab_offset for span in region.spans]
+        dax_copy_sizes = [span.size for span in region.spans]
+        self._batched_memcpy(dax_src_ptrs, slab_dst_ptrs, dax_copy_sizes)
+
+        slab_src_ptrs = [slab_base_ptr + item.slab_offset for item in region.items]
+        dst_ptrs = [cast(MemoryObj, item.memory_obj).data_ptr for item in region.items]
+        out_sizes = [item.size for item in region.items]
+        self._batched_memcpy(slab_src_ptrs, dst_ptrs, out_sizes)
+
+    def _run_restore_waves(self, waves: Sequence[_RestoreWave]) -> None:
+        restore_executor = self._restore_executor
+        if restore_executor is None:
+            raise RuntimeError("DaxBackend restore executor is not available")
+
+        for wave in waves:
+            futures = [
+                restore_executor.submit(self._restore_region, region)
+                for region in wave.regions
+                if region.items
+            ]
+            for future in futures:
+                future.result()
+
+    def _cleanup_restore_outputs(self, reserved: Sequence[_RestoreItem]) -> None:
+        for item in reserved:
+            if item.memory_obj is not None:
+                item.memory_obj.ref_count_down()
+                item.memory_obj = None
+
+    def _restore_batch(
+        self,
+        keys: list[CacheEngineKey],
+        prefix_only: bool,
+    ) -> list[Optional[MemoryObj]]:
+        reservations, _ = self._core.reserve_reads(keys, prefix_only=prefix_only)
+        results: list[Optional[MemoryObj]] = [None] * len(keys)
+        if not reservations:
+            return [] if prefix_only else results
+
+        reserved_items = [
+            _RestoreItem(
+                result_index=reservation.result_index,
+                key=reservation.key,
+                offset=reservation.offset,
+                size=reservation.size,
+                shape=reservation.shape,
+                dtype=reservation.dtype,
+                fmt=reservation.fmt,
+                cached_positions=reservation.cached_positions,
+                slot_id=reservation.slot_id,
+                generation=reservation.generation,
+            )
+            for reservation in reservations
+        ]
+
+        touched_keys: set[CacheEngineKey] = set()
+        try:
+            self._allocate_restore_outputs(reserved_items)
+            waves = self._build_restore_waves(reserved_items)
+            self._run_restore_waves(waves)
+            for item in reserved_items:
+                memory_obj = cast(MemoryObj, item.memory_obj)
+                memory_obj.metadata.cached_positions = item.cached_positions
+                results[item.result_index] = memory_obj
+                touched_keys.add(item.key)
+        except Exception:
+            self._cleanup_restore_outputs(reserved_items)
+            self._core.finalize_reads(reservations, set())
+            raise
+
+        self._core.finalize_reads(reservations, touched_keys)
+        if prefix_only:
+            prefix_results = [
+                cast(MemoryObj, results[item.result_index]) for item in reserved_items
+            ]
+            return cast(
+                list[Optional[MemoryObj]],
+                prefix_results,
+            )
+        return results
+
+    async def _submit_write(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        try:
+            committed = await asyncio.to_thread(
+                self._core.put_one,
+                key,
+                memory_obj,
+                writer=lambda offset, obj, size: self._do_write(offset, obj, size),
+            )
+            if committed:
+                self._invoke_on_complete_callback(key, on_complete_callback)
+        finally:
+            memory_obj.ref_count_down()
diff --git a/lmcache/v1/storage_backend/plugins/rust_raw_block_backend.py b/lmcache/v1/storage_backend/plugins/rust_raw_block_backend.py
new file mode 100644
index 0000000..7250972
--- /dev/null
+++ b/lmcache/v1/storage_backend/plugins/rust_raw_block_backend.py
@@ -0,0 +1,699 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Mapping
+from concurrent.futures import Future
+from typing import Any, Callable, List, Optional, Sequence
+import asyncio
+import threading
+import time
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.abstract_backend import (
+    AllocatorBackendInterface,
+    StoragePluginInterface,
+)
+from lmcache.v1.storage_backend.raw_block import (
+    DEFAULT_IOURING_QUEUE_DEPTH,
+    RawBlockCore,
+    RawBlockCoreConfig,
+    RawBlockKeySpec,
+    decode_legacy_key,
+    encode_legacy_key,
+    normalize_raw_block_io_engine,
+    round_up,
+    validate_raw_block_io_options,
+)
+
+logger = init_logger(__name__)
+
+_DEFAULT_META_MAGIC = b"LMCIDX01"
+_DEFAULT_META_VERSION = 1
+
+TPRankKey = int | str
+PerTPDevicePaths = Mapping[TPRankKey, str]
+
+
+def _validate_per_tp_device_paths(per_tp_devices: PerTPDevicePaths) -> None:
+    """Validate that each TP rank uses a distinct raw-block device path.
+
+    Args:
+        per_tp_devices: Mapping from TP rank to raw-block device path.
+
+    Raises:
+        ValueError: If the same device path is assigned to multiple ranks.
+    """
+    values = list(per_tp_devices.values())
+    if len(values) != len(set(values)):
+        raise ValueError(
+            "Duplicate device path configured in rust_raw_block.per_tp_device_paths"
+        )
+
+
+def _get_per_tp_device_path(
+    per_tp_devices: PerTPDevicePaths, tp_rank: int
+) -> Optional[str]:
+    """Return the device path configured for a TP rank.
+
+    Args:
+        per_tp_devices: Mapping with string or integer rank keys.
+        tp_rank: Tensor-parallel rank to look up.
+
+    Returns:
+        The configured path, or None when the rank is absent.
+    """
+    return per_tp_devices.get(str(tp_rank), per_tp_devices.get(tp_rank))
+
+
+class RustRawBlockBackend(StoragePluginInterface):
+    """
+    Legacy raw-block storage plugin wrapper.
+
+    The durable raw-device/index/checkpoint logic now lives in RawBlockCore.
+    This wrapper preserves the existing non-MP interface and prefix semantics:
+    - TP>1 still uses explicit per-TP device partitions
+    - batched_async_contains reports only the leading hit prefix
+    - batched_get_{blocking,non_blocking} load only the leading hit prefix
+    """
+
+    def __init__(
+        self,
+        config=None,
+        metadata=None,
+        local_cpu_backend=None,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        dst_device: str = "cpu",
+    ):
+        super().__init__(
+            dst_device=dst_device,
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop,
+        )
+        if self.loop is None:
+            raise ValueError("RustRawBlockBackend requires an asyncio event loop")
+        if self.local_cpu_backend is None:
+            raise ValueError("RustRawBlockBackend requires local_cpu_backend")
+        if self.config is None:
+            raise ValueError("RustRawBlockBackend requires config")
+
+        extra = self.config.extra_config or {}
+
+        self.device_path: str
+        if self.metadata is not None and self.metadata.world_size > 1:
+            tp_rank = self.metadata.worker_id
+            per_tp_devices = extra.get("rust_raw_block.per_tp_device_paths", {})
+            if not isinstance(per_tp_devices, Mapping):
+                raise ValueError(
+                    "rust_raw_block.per_tp_device_paths must be a mapping from "
+                    "TP rank to device path"
+                )
+            if not per_tp_devices:
+                raise ValueError(
+                    "For TP > 1, rust_raw_block.per_tp_device_paths is required. "
+                    "Each TP worker must have an explicit device path configured."
+                )
+            _validate_per_tp_device_paths(per_tp_devices)
+            device_path = _get_per_tp_device_path(per_tp_devices, tp_rank)
+            if not device_path:
+                raise ValueError(
+                    f"No device path configured for TP rank {tp_rank}. "
+                    f"Available ranks: {list(per_tp_devices.keys())}"
+                )
+            self.device_path = device_path
+        else:
+            self.device_path = str(extra.get("rust_raw_block.device_path", "") or "")
+            if not self.device_path:
+                raise ValueError(
+                    "extra_config['rust_raw_block.device_path'] is required"
+                )
+
+        self._core = RawBlockCore(
+            self._build_core_config(extra),
+            key_namespace="legacy",
+        )
+        if self._core.io_engine == "io_uring":
+            try:
+                self._core.register_fixed_buffers_from_allocator(
+                    self.local_cpu_backend.get_memory_allocator()
+                )
+            except Exception as e:
+                logger.warning(
+                    "RustRawBlockBackend: failed to register io_uring fixed "
+                    "buffers: %s. Falling back to non-fixed buffer mode.",
+                    e,
+                )
+        self._warn_if_loaded_metadata_looks_cross_rank()
+
+        self._put_lock = threading.Lock()
+        self._put_tasks: set[CacheEngineKey] = set()
+        self._pin_lock = threading.Lock()
+        self._pinned_keys: set[str] = set()
+
+    def __str__(self) -> str:
+        return "RustRawBlockBackend"
+
+    @property
+    def capacity_bytes(self) -> int:
+        """Return the effective raw-block capacity in bytes."""
+        return int(self._core.capacity_bytes)
+
+    @property
+    def block_align(self) -> int:
+        """Return the configured raw-device block alignment."""
+        return int(self._core.block_align)
+
+    @property
+    def header_bytes(self) -> int:
+        """Return the per-slot header reservation in bytes."""
+        return int(self._core.header_bytes)
+
+    @property
+    def slot_bytes(self) -> int:
+        """Return the configured raw-block slot size in bytes."""
+        return int(self._core.slot_bytes)
+
+    @property
+    def meta_total_bytes(self) -> int:
+        """Return the reserved metadata checkpoint region size."""
+        return int(self._core.meta_total_bytes)
+
+    @property
+    def meta_magic_text(self) -> str:
+        """Return the ASCII metadata checkpoint magic."""
+        return str(self._core.meta_magic_text)
+
+    @property
+    def meta_version(self) -> int:
+        """Return the metadata checkpoint format version."""
+        return int(self._core.meta_version)
+
+    @property
+    def data_base_offset(self) -> int:
+        """Return the byte offset where data slots begin."""
+        return self._core.data_base_offset()
+
+    @property
+    def _raw(self) -> Any:
+        """Return the raw device handle for legacy test compatibility."""
+        return self._core.raw_device()
+
+    @_raw.setter
+    def _raw(self, raw_device: Any) -> None:
+        """Replace the raw device handle for legacy test compatibility."""
+        self._core.set_raw_device_for_testing(raw_device)
+
+    def lock_refcount(self, encoded_key: str) -> int:
+        """Return the L2 lock refcount for a legacy encoded key."""
+        return self._core.lock_refcount(encoded_key)
+
+    def inflight_io_count(self) -> int:
+        """Return the number of active raw-device I/O operations."""
+        return self._core.inflight_io_count()
+
+    def indexed_key_count(self) -> int:
+        """Return the number of keys currently indexed by raw-block."""
+        return self._core.indexed_key_count()
+
+    def entry_offset(self, key: CacheEngineKey) -> int | None:
+        """Return the raw-block slot offset for a legacy key."""
+        return self._core.entry_offset(encode_legacy_key(key).encoded)
+
+    def metadata_container_offsets(self) -> list[int]:
+        """Return checkpoint metadata container offsets in bytes."""
+        return self._core.metadata_container_offsets()
+
+    def apply_loaded_state(self, data: dict[str, Any]) -> bool:
+        """Validate and apply a raw-block metadata checkpoint payload."""
+        return self._core.apply_loaded_state(data)
+
+    def _build_core_config(self, extra: Mapping[str, Any]) -> RawBlockCoreConfig:
+        block_align = int(extra.get("rust_raw_block.block_align", 4096))
+        header_bytes = int(extra.get("rust_raw_block.header_bytes", 4096))
+        use_odirect = bool(extra.get("rust_raw_block.use_odirect", False))
+        enable_zero_copy = bool(extra.get("rust_raw_block.enable_zero_copy", True))
+        capacity_bytes = int(extra.get("rust_raw_block.capacity_bytes", 0))
+        io_engine = normalize_raw_block_io_engine(
+            extra.get("rust_raw_block.io_engine"),
+            use_iouring=extra.get("rust_raw_block.use_iouring"),
+            use_uring=extra.get("rust_raw_block.use_uring"),
+        )
+        iouring_queue_depth = int(
+            extra.get("rust_raw_block.iouring_queue_depth", DEFAULT_IOURING_QUEUE_DEPTH)
+        )
+        use_uring_cmd = bool(extra.get("rust_raw_block.use_uring_cmd", False))
+        max_data_transfer_size = int(
+            extra.get("rust_raw_block.max_data_transfer_size", 0)
+        )
+        validate_raw_block_io_options(
+            iouring_queue_depth=iouring_queue_depth,
+        )
+        meta_total_bytes = int(
+            extra.get("rust_raw_block.meta_total_bytes", 128 * 1024 * 1024)
+        )
+        meta_magic_raw = extra.get("rust_raw_block.meta_magic", "LMCIDX01")
+        if isinstance(meta_magic_raw, str):
+            meta_magic = meta_magic_raw.encode("ascii")
+        elif isinstance(meta_magic_raw, bytes):
+            meta_magic = meta_magic_raw
+        else:
+            raise ValueError("rust_raw_block.meta_magic must be str or bytes")
+
+        get_full_chunk_size_bytes = getattr(
+            self.local_cpu_backend, "get_full_chunk_size_bytes", None
+        )
+        if callable(get_full_chunk_size_bytes):
+            full_chunk_bytes = int(get_full_chunk_size_bytes())
+        else:
+            get_full_chunk_size = getattr(
+                self.local_cpu_backend, "get_full_chunk_size", None
+            )
+            if not callable(get_full_chunk_size):
+                raise ValueError(
+                    "local_cpu_backend must expose get_full_chunk_size_bytes() "
+                    "or get_full_chunk_size()"
+                )
+            full_chunk_bytes = int(get_full_chunk_size())
+        default_slot_bytes = round_up(header_bytes + full_chunk_bytes, block_align)
+        slot_bytes = int(extra.get("rust_raw_block.slot_bytes", default_slot_bytes))
+
+        return RawBlockCoreConfig(
+            device_path=self.device_path,
+            capacity_bytes=capacity_bytes,
+            block_align=block_align,
+            header_bytes=header_bytes,
+            slot_bytes=slot_bytes,
+            use_odirect=use_odirect,
+            enable_zero_copy=enable_zero_copy,
+            meta_total_bytes=meta_total_bytes,
+            meta_magic=meta_magic,
+            meta_version=int(
+                extra.get("rust_raw_block.meta_version", _DEFAULT_META_VERSION)
+            ),
+            meta_checkpoint_interval_sec=int(
+                extra.get("rust_raw_block.meta_checkpoint_interval_sec", 60)
+            ),
+            meta_idle_quiet_ms=int(extra.get("rust_raw_block.meta_idle_quiet_ms", 100)),
+            meta_enable_periodic=bool(
+                extra.get("rust_raw_block.meta_enable_periodic", True)
+            ),
+            load_checkpoint_on_init=bool(
+                extra.get("rust_raw_block.load_checkpoint_on_init", True)
+            ),
+            meta_verify_on_load=bool(
+                extra.get("rust_raw_block.meta_verify_on_load", True)
+            ),
+            max_data_transfer_size=max_data_transfer_size,
+            io_engine=io_engine,
+            iouring_queue_depth=iouring_queue_depth,
+            use_uring_cmd=use_uring_cmd,
+        )
+
+    def _warn_if_loaded_metadata_looks_cross_rank(self) -> None:
+        if self.metadata is None:
+            return
+        first_encoded_key = self._core.first_encoded_key()
+        if first_encoded_key is None:
+            return
+        try:
+            first_loaded_key = decode_legacy_key(first_encoded_key)
+        except Exception:
+            return
+        expected_worker_id = int(self.metadata.worker_id)
+        loaded_worker_id = int(first_loaded_key.worker_id)
+        if loaded_worker_id == expected_worker_id:
+            return
+        logger.warning(
+            "RustRawBlockBackend: loaded metadata may belong to another "
+            "worker (device=%s, current_worker_id=%d, "
+            "first_entry_worker_id=%d, first_entry_key=%s)",
+            self.device_path,
+            expected_worker_id,
+            loaded_worker_id,
+            first_loaded_key.to_string(),
+        )
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        spec = encode_legacy_key(key)
+        return (
+            self._pin_if_needed(spec.encoded)
+            if pin
+            else self._core.contains_key(
+                spec.encoded,
+                lock=False,
+            )
+        )
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        with self._put_lock:
+            return key in self._put_tasks
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        spec = encode_legacy_key(key)
+        return self._pin_if_needed(spec.encoded)
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        spec = encode_legacy_key(key)
+        return self._unpin_if_needed(spec.encoded)
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        spec = encode_legacy_key(key)
+        with self._pin_lock:
+            removed = self._core.delete_many([spec.encoded], force=force)[0]
+            if removed:
+                self._pinned_keys.discard(spec.encoded)
+        return removed
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,  # noqa: ARG002
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> list[Future] | None:
+        del transfer_spec
+        loop = self.loop
+        if loop is None:
+            raise RuntimeError("RustRawBlockBackend requires an asyncio event loop")
+
+        pending: list[tuple[CacheEngineKey, RawBlockKeySpec, MemoryObj]] = []
+        for key, obj in zip(keys, objs, strict=False):
+            with self._put_lock:
+                if key in self._put_tasks:
+                    continue
+                self._put_tasks.add(key)
+
+            spec = encode_legacy_key(key)
+            exists = self._core.contains_key(
+                spec.encoded,
+                lock=False,
+            ) or self._core.exists_inflight(spec.encoded)
+            if exists:
+                with self._put_lock:
+                    self._put_tasks.discard(key)
+                continue
+
+            obj.ref_count_up()
+            pending.append((key, spec, obj))
+
+        if not pending:
+            return None
+
+        # On scheduling failure, roll back unscheduled items; scheduled ones
+        # release their ref / put-task entry in their coroutine's finally.
+        scheduled_count = 0
+        try:
+            if self._core.io_engine == "io_uring" and len(pending) > 1:
+                coro = self._submit_put_many(pending, on_complete_callback)
+                try:
+                    fut = asyncio.run_coroutine_threadsafe(coro, loop)
+                except Exception:
+                    coro.close()
+                    raise
+                return [fut]
+
+            futures: list[Future] = []
+            for key, spec, obj in pending:
+                coro = self._submit_put_one(key, spec, obj, on_complete_callback)
+                try:
+                    fut = asyncio.run_coroutine_threadsafe(coro, loop)
+                except Exception:
+                    coro.close()
+                    raise
+                futures.append(fut)
+                scheduled_count += 1
+            return futures
+        except Exception:
+            for _, _, obj in pending[scheduled_count:]:
+                obj.ref_count_down()
+            with self._put_lock:
+                for key, _, _ in pending[scheduled_count:]:
+                    self._put_tasks.discard(key)
+            raise
+
+    async def _submit_put_one(
+        self,
+        key: CacheEngineKey,
+        spec: RawBlockKeySpec,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]],
+    ) -> None:
+        try:
+            put_result = await asyncio.to_thread(
+                self._core.put_many,
+                [spec],
+                [memory_obj],
+            )
+            if not put_result.results or not put_result.results[0]:
+                raise RuntimeError(f"Failed to persist raw-block key {spec.encoded}")
+            if on_complete_callback is not None:
+                try:
+                    on_complete_callback(key)
+                except Exception as e:
+                    logger.warning("on_complete_callback failed for key %s: %s", key, e)
+        finally:
+            memory_obj.ref_count_down()
+            with self._put_lock:
+                self._put_tasks.discard(key)
+
+    async def _submit_put_many(
+        self,
+        pending: Sequence[tuple[CacheEngineKey, RawBlockKeySpec, MemoryObj]],
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]],
+    ) -> None:
+        """Persist multiple legacy raw-block keys in one background batch.
+
+        Args:
+            pending: Ordered ``(key, spec, memory_obj)`` tuples to persist.
+            on_complete_callback: Optional per-key completion callback.
+
+        Raises:
+            RuntimeError: If any key fails to persist.
+            Exception: Propagates raw-device write failures from the core.
+        """
+        keys = [item[0] for item in pending]
+        specs = [item[1] for item in pending]
+        memory_objs = [item[2] for item in pending]
+        try:
+            put_result = await asyncio.to_thread(
+                self._core.put_many,
+                specs,
+                memory_objs,
+            )
+            if len(put_result.results) != len(pending) or not all(put_result.results):
+                failed = []
+
+                for key, spec, ok in zip(keys, specs, put_result.results, strict=False):
+                    if ok:
+                        if on_complete_callback is not None:
+                            try:
+                                on_complete_callback(key)
+                            except Exception as e:
+                                logger.warning(
+                                    "on_complete_callback failed for key %s: %s", key, e
+                                )
+                    else:
+                        failed.append(spec.encoded)
+
+                if failed:
+                    raise RuntimeError(
+                        "Failed to persist raw-block keys: " + ", ".join(failed)
+                    )
+            if on_complete_callback is not None:
+                for key in keys:
+                    try:
+                        on_complete_callback(key)
+                    except Exception as e:
+                        logger.warning(
+                            "on_complete_callback failed for key %s: %s", key, e
+                        )
+        finally:
+            for key, _spec, memory_obj in pending:
+                memory_obj.ref_count_down()
+                with self._put_lock:
+                    self._put_tasks.discard(key)
+
+    def _batched_get_prefix(
+        self,
+        keys: Sequence[CacheEngineKey],
+    ) -> list[MemoryObj]:
+        if not keys:
+            return []
+
+        specs = [encode_legacy_key(key) for key in keys]
+        encoded_keys = [spec.encoded for spec in specs]
+        allocated: list[MemoryObj] = []
+        locked_specs: list[RawBlockKeySpec] = []
+        with self._pin_lock:
+            prefix_metas = self._core.get_metadata_prefix(
+                encoded_keys,
+                lock=True,
+                skip_locked=self._pinned_keys,
+            )
+            prefix_specs = specs[: len(prefix_metas)]
+            locked_specs = [
+                spec for spec in prefix_specs if spec.encoded not in self._pinned_keys
+            ]
+
+        if not prefix_specs:
+            return []
+
+        try:
+            for spec, meta in zip(prefix_specs, prefix_metas, strict=False):
+                if meta.shape is None or meta.dtype is None:
+                    logger.warning(
+                        "Raw-block metadata missing shape/dtype for key %s; "
+                        "aborting prefix load",
+                        spec.encoded,
+                    )
+                    break
+                if self.local_cpu_backend is None:
+                    raise RuntimeError("RustRawBlockBackend requires local_cpu_backend")
+                memory_obj = self.local_cpu_backend.allocate(
+                    meta.shape,
+                    meta.dtype,
+                    meta.fmt,
+                )
+                if memory_obj is None:
+                    logger.error("Failed to allocate memory for key %s", spec.encoded)
+                    break
+                allocated.append(memory_obj)
+
+            if not allocated:
+                return []
+
+            load_specs = prefix_specs[: len(allocated)]
+            load_results = self._core.load_many_into(
+                [spec.encoded for spec in load_specs],
+                allocated,
+                raise_on_error=True,
+            )
+            loaded_count = 0
+            for ok in load_results:
+                if not ok:
+                    break
+                loaded_count += 1
+            if loaded_count == len(allocated):
+                return allocated
+
+            for obj in allocated[loaded_count:]:
+                obj.ref_count_down()
+            return allocated[:loaded_count]
+        except Exception:
+            for obj in allocated:
+                obj.ref_count_down()
+            raise
+        finally:
+            self._core.unlock_many([spec.encoded for spec in locked_specs])
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        loaded = self._batched_get_prefix([key])
+        return loaded[0] if loaded else None
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        """Synchronously load the leading raw-block hit prefix.
+
+        Args:
+            keys: Ordered legacy cache keys to load.
+
+        Returns:
+            A list aligned with ``keys`` containing loaded memory objects for
+            the contiguous hit prefix and ``None`` for the remaining suffix.
+
+        Raises:
+            RuntimeError: If the local CPU allocator backend is unavailable.
+            Exception: Propagates raw-device load failures from the core.
+        """
+        if not keys:
+            return []
+        loaded = self._batched_get_prefix(keys)
+        return [*loaded, *([None] * (len(keys) - len(loaded)))]
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        del lookup_id
+        specs = [encode_legacy_key(key) for key in keys]
+        encoded_keys = [spec.encoded for spec in specs]
+        results = self._core.exists_many(encoded_keys, lock=False)
+        prefix_hits = 0
+        for ok in results:
+            if not ok:
+                break
+            prefix_hits += 1
+        if pin and prefix_hits > 0:
+            pinned_hits = 0
+            for encoded_key in encoded_keys[:prefix_hits]:
+                if not self._pin_if_needed(encoded_key):
+                    break
+                pinned_hits += 1
+            prefix_hits = pinned_hits
+        return prefix_hits
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> list[MemoryObj]:
+        """Asynchronously load the leading raw-block hit prefix.
+
+        Args:
+            lookup_id: Lookup identifier supplied by the storage manager.
+            keys: Ordered legacy cache keys to load.
+            transfer_spec: Optional transfer metadata; unused by raw-block.
+
+        Returns:
+            Loaded memory objects for the contiguous hit prefix only.
+
+        Raises:
+            RuntimeError: If the local CPU allocator backend is unavailable.
+            Exception: Propagates raw-device load failures from the core.
+        """
+        del lookup_id, transfer_spec
+        return await asyncio.to_thread(self._batched_get_prefix, keys)
+
+    def get_allocator_backend(self) -> AllocatorBackendInterface:
+        if self.local_cpu_backend is None:
+            raise RuntimeError("RustRawBlockBackend requires local_cpu_backend")
+        return self.local_cpu_backend
+
+    def close(self) -> None:
+        deadline = time.monotonic() + 10.0
+        while True:
+            with self._put_lock:
+                pending = len(self._put_tasks)
+            if pending == 0 or time.monotonic() >= deadline:
+                break
+            time.sleep(0.01)
+        self._core.close()
+
+    def _pin_if_needed(self, encoded_key: str) -> bool:
+        with self._pin_lock:
+            if encoded_key in self._pinned_keys:
+                return True
+            if not self._core.exists_many([encoded_key], lock=True)[0]:
+                return False
+            self._pinned_keys.add(encoded_key)
+            return True
+
+    def _unpin_if_needed(self, encoded_key: str) -> bool:
+        with self._pin_lock:
+            if encoded_key in self._pinned_keys:
+                self._core.unlock_many([encoded_key])
+                self._pinned_keys.discard(encoded_key)
+                return True
+            return self._core.contains_key(encoded_key, lock=False)
diff --git a/lmcache/v1/storage_backend/raw_block/__init__.py b/lmcache/v1/storage_backend/raw_block/__init__.py
new file mode 100644
index 0000000..388d022
--- /dev/null
+++ b/lmcache/v1/storage_backend/raw_block/__init__.py
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.storage_backend.raw_block.core import (
+    DEFAULT_IOURING_QUEUE_DEPTH,
+    RAW_BLOCK_IO_ENGINES,
+    RawBlockCore,
+    RawBlockCoreConfig,
+    RawBlockPutManyResult,
+    normalize_raw_block_io_engine,
+    round_up,
+    validate_raw_block_io_options,
+)
+from lmcache.v1.storage_backend.raw_block.key_codec import (
+    RawBlockKeyNamespace,
+    RawBlockKeySpec,
+    decode_legacy_key,
+    decode_object_key,
+    encode_legacy_key,
+    encode_object_key,
+    object_key_to_string,
+    slot_identity_from_encoded_key,
+)
+
+__all__ = [
+    "RawBlockCore",
+    "RawBlockCoreConfig",
+    "RAW_BLOCK_IO_ENGINES",
+    "DEFAULT_IOURING_QUEUE_DEPTH",
+    "RawBlockKeyNamespace",
+    "RawBlockKeySpec",
+    "RawBlockPutManyResult",
+    "decode_legacy_key",
+    "decode_object_key",
+    "encode_legacy_key",
+    "encode_object_key",
+    "object_key_to_string",
+    "normalize_raw_block_io_engine",
+    "round_up",
+    "slot_identity_from_encoded_key",
+    "validate_raw_block_io_options",
+]
diff --git a/lmcache/v1/storage_backend/raw_block/core.py b/lmcache/v1/storage_backend/raw_block/core.py
new file mode 100644
index 0000000..d48e5e1
--- /dev/null
+++ b/lmcache/v1/storage_backend/raw_block/core.py
@@ -0,0 +1,1946 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Optional
+import ctypes
+import json
+import os
+import re
+import stat
+import struct
+import threading
+import time
+import zlib
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import (
+    STR_DTYPE_TO_TORCH_DTYPE,
+    TORCH_DTYPE_TO_STR_DTYPE,
+    DiskCacheMetadata,
+)
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.storage_backend.raw_block.key_codec import (
+    RawBlockKeyNamespace,
+    RawBlockKeySpec,
+    decode_legacy_key,
+    slot_identity_from_encoded_key,
+)
+
+logger = init_logger(__name__)
+
+
+_DEFAULT_META_MAGIC = b"LMCIDX01"
+_DEFAULT_META_VERSION = 1
+_META_HEADER_STRUCT = struct.Struct("<8sIQQI")
+RAW_BLOCK_IO_ENGINES = frozenset({"posix", "io_uring"})
+DEFAULT_IOURING_QUEUE_DEPTH = 256
+
+
+def round_up(x: int, align: int) -> int:
+    """Round a value up to the nearest alignment boundary.
+
+    Args:
+        x: Value to align.
+        align: Positive alignment in bytes.
+
+    Returns:
+        ``x`` rounded up to a multiple of ``align``.
+    """
+    return ((x + align - 1) // align) * align
+
+
+def normalize_raw_block_io_engine(
+    io_engine: Any = None,
+    *,
+    use_iouring: Any = None,
+    use_uring: Any = None,
+) -> str:
+    """Normalize raw-block I/O engine config with legacy compatibility.
+
+    Args:
+        io_engine: Explicit engine string. Valid values are ``"posix"``,
+            and ``"io_uring"``.
+        use_iouring: Legacy boolean knob. Used only when ``io_engine`` is not
+            set.
+        use_uring: Legacy boolean alias. Used only when ``io_engine`` is not
+            set.
+
+    Returns:
+        The normalized engine string.
+
+    Raises:
+        ValueError: If ``io_engine`` names an unsupported engine.
+    """
+    if io_engine is None or io_engine == "":
+        if bool(use_iouring) or bool(use_uring):
+            return "io_uring"
+        return "posix"
+    normalized = str(io_engine).lower()
+    if normalized not in RAW_BLOCK_IO_ENGINES:
+        allowed = ", ".join(sorted(RAW_BLOCK_IO_ENGINES))
+        raise ValueError(f"io_engine must be one of: {allowed}")
+    return normalized
+
+
+def validate_raw_block_io_options(
+    *,
+    iouring_queue_depth: int,
+) -> None:
+    """Validate numeric raw-block I/O engine options.
+
+    Args:
+        iouring_queue_depth: Queue depth for the Rust io_uring path.
+
+    Raises:
+        ValueError: If any numeric option is not positive.
+    """
+    if int(iouring_queue_depth) <= 0:
+        raise ValueError("iouring_queue_depth must be > 0")
+
+
+def _resolve_sysfs_queue_dir(device_path: str) -> Optional[str]:
+    """Resolve sysfs queue directory for NVMe character device paths."""
+    base_name = os.path.basename(device_path)
+    match = re.fullmatch(r"ng(\d+)n(\d+)", base_name)
+    if match:
+        ctrl, nsid = match.groups()
+        return f"/sys/block/nvme{ctrl}n{nsid}/queue"
+    return None
+
+
+def _read_sysfs_int(path: str) -> Optional[int]:
+    """Read an integer value from sysfs and return None on failure."""
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return int(f.read().strip())
+    except Exception:
+        return None
+
+
+@dataclass(frozen=True)
+class RawBlockCoreConfig:
+    """Configuration for RawBlockCore device layout, I/O, and checkpoints."""
+
+    device_path: str
+    capacity_bytes: int
+    block_align: int
+    header_bytes: int
+    slot_bytes: int
+    use_odirect: bool
+    enable_zero_copy: bool
+    meta_total_bytes: int
+    meta_magic: bytes
+    meta_version: int
+    meta_checkpoint_interval_sec: int
+    meta_idle_quiet_ms: int
+    meta_enable_periodic: bool
+    meta_verify_on_load: bool
+    max_data_transfer_size: int = 0
+    load_checkpoint_on_init: bool = True
+    io_engine: str = "posix"
+    iouring_queue_depth: int = DEFAULT_IOURING_QUEUE_DEPTH
+    use_uring_cmd: bool = False
+
+
+@dataclass
+class _Entry:
+    offset: int
+    size: int
+    meta: DiskCacheMetadata
+
+
+@dataclass
+class _Inflight:
+    offset: int
+    meta: DiskCacheMetadata
+    canceled: bool = False
+
+
+@dataclass(frozen=True)
+class RawBlockPutManyResult:
+    """Result of a RawBlockCore batched write."""
+
+    results: list[bool]
+    stored_keys: list[str]
+
+
+class RawBlockCore:
+    """
+    Shared raw-block storage engine used by both legacy non-MP and MP L2 paths.
+
+    This class owns the raw-device I/O path, slot allocation, checkpoint/recovery,
+    and lock refcounts that protect slots from deletion while in use.
+    """
+
+    def __init__(
+        self,
+        config: RawBlockCoreConfig,
+        *,
+        key_namespace: RawBlockKeyNamespace,
+    ):
+        """Initialize the raw-block storage engine.
+
+        Args:
+            config: Raw-block device, layout, I/O, and checkpoint settings.
+            key_namespace: Encoding namespace used by keys stored in this core.
+
+        Raises:
+            ValueError: If the supplied configuration is invalid.
+            RuntimeError: If the raw device cannot be opened or the computed
+                layout cannot fit metadata and at least one data slot.
+
+        Notes:
+            If initialization opens the device and a later recovery step fails,
+            the partially opened resources are closed before the exception is
+            re-raised.
+        """
+        self.device_path = config.device_path
+        self.capacity_bytes = int(config.capacity_bytes)
+        self.block_align = int(config.block_align)
+        self.header_bytes = int(config.header_bytes)
+        self.slot_bytes = int(config.slot_bytes)
+        self.use_odirect = bool(config.use_odirect)
+        self.enable_zero_copy = bool(config.enable_zero_copy)
+
+        self.meta_total_bytes = int(config.meta_total_bytes)
+        self.meta_magic = bytes(config.meta_magic)
+        self.meta_version = int(config.meta_version)
+        self.meta_checkpoint_interval_sec = int(config.meta_checkpoint_interval_sec)
+        self.meta_idle_quiet_ms = int(config.meta_idle_quiet_ms)
+        self.meta_enable_periodic = bool(config.meta_enable_periodic)
+        self.load_checkpoint_on_init = bool(config.load_checkpoint_on_init)
+        self.meta_verify_on_load = bool(config.meta_verify_on_load)
+        self.io_engine = normalize_raw_block_io_engine(config.io_engine)
+        self.iouring_queue_depth = int(config.iouring_queue_depth)
+        self.use_uring_cmd = bool(config.use_uring_cmd)
+        if self.use_uring_cmd and self.use_odirect:
+            logger.warning(
+                "RawBlockCore: use_odirect is ignored for NVMe namespace "
+                "character devices when use_uring_cmd=true"
+            )
+            self.use_odirect = False
+        self.key_namespace = key_namespace
+
+        if not self.device_path:
+            raise ValueError("RawBlockCore requires a non-empty device_path")
+        if self.block_align <= 0:
+            raise ValueError("block_align must be > 0")
+        if self.header_bytes < 24:
+            raise ValueError("header_bytes must be >= 24")
+        if self.header_bytes % self.block_align != 0:
+            raise ValueError("header_bytes must be a multiple of block_align")
+        if self.slot_bytes < self.header_bytes + 1:
+            raise ValueError("slot_bytes must be >= header_bytes + 1")
+        if self.slot_bytes % self.block_align != 0:
+            raise ValueError("slot_bytes must be a multiple of block_align")
+        if self.meta_total_bytes <= self.block_align:
+            raise ValueError("meta_total_bytes must provide room for metadata header")
+        if self.meta_total_bytes % self.block_align != 0:
+            raise ValueError("meta_total_bytes must be a multiple of block_align")
+        if len(self.meta_magic) != 8:
+            raise ValueError("meta_magic must be exactly 8 bytes")
+        if self.meta_version <= 0:
+            raise ValueError("meta_version must be > 0")
+        validate_raw_block_io_options(
+            iouring_queue_depth=self.iouring_queue_depth,
+        )
+        if self.use_uring_cmd and self.io_engine != "io_uring":
+            raise ValueError("use_uring_cmd requires io_uring as io_engine")
+        if self.use_uring_cmd:
+            try:
+                mode = os.stat(self.device_path).st_mode
+            except OSError as e:
+                raise ValueError(
+                    "use_uring_cmd requires an existing NVMe namespace "
+                    f"character device path, got {self.device_path!r}"
+                ) from e
+            if not stat.S_ISCHR(mode):
+                raise ValueError(
+                    "use_uring_cmd requires an NVMe namespace character device "
+                    f"(for example /dev/ng0n1), got {self.device_path!r}"
+                )
+            # Validate NVMe generic namespace naming pattern (ng<ctrl>n<ns>)
+            basename = os.path.basename(self.device_path)
+            if not re.match(r"^ng\d+n\d+$", basename):
+                raise ValueError(
+                    "use_uring_cmd requires an NVMe generic namespace character device "
+                    f"with naming pattern ng<ctrl>n<ns> (for example /dev/ng0n1), "
+                    f"got {self.device_path!r}"
+                )
+
+        # Maximum data transfer size for a single I/O request.
+        # Default is 0 (no splitting).
+        # > 0 : explicit manual split size
+        # <= 0: opt-in auto-detect from device queue limits
+        if self.use_uring_cmd:
+            self.max_data_transfer_size = self._resolve_max_data_transfer_size(
+                config.max_data_transfer_size
+            )
+
+        try:
+            self.meta_magic_text = self.meta_magic.decode("ascii")
+        except UnicodeDecodeError as e:
+            raise ValueError("meta_magic must be ASCII bytes") from e
+
+        self._meta_copy_count: int = 2
+        self._meta_container_bytes: int = (
+            (self.meta_total_bytes // self._meta_copy_count) // self.block_align
+        ) * self.block_align
+        if self._meta_container_bytes <= self.block_align:
+            raise ValueError(
+                "meta_total_bytes must provide room for at least two metadata copies"
+            )
+
+        self._lock = threading.Lock()
+        self._index: dict[str, _Entry] = {}
+        self._lock_refcnt: dict[str, int] = {}
+        self._inflight: dict[str, _Inflight] = {}
+
+        self._next_slot: int = 0
+        self._free_slots: list[int] = []
+        self._max_slots: int = 0
+        self._effective_capacity_bytes: int = 0
+        self._data_base_offset: int = 0
+
+        self._raw = None
+        self._closed = False
+
+        self._meta_seq: int = 0
+        self._meta_dirty_total: int = 0
+        self._meta_persisted: int = 0
+        self._inflight_io_count: int = 0
+        self._last_io_ts: float = time.monotonic()
+        self._meta_stop_evt = threading.Event()
+        self._meta_thread: Optional[threading.Thread] = None
+
+        try:
+            self._ensure_capacity_and_layout()
+            if self.load_checkpoint_on_init:
+                self._load_checkpoint_from_device()
+            else:
+                logger.info("RawBlockCore: skipping on-device metadata checkpoint load")
+
+            if self.meta_enable_periodic:
+                self._meta_thread = threading.Thread(
+                    target=self._checkpoint_loop,
+                    daemon=True,
+                    name="raw-block-core-checkpoint",
+                )
+                self._meta_thread.start()
+        except Exception:
+            self._cleanup_after_init_failure()
+            raise
+
+    @property
+    def _requires_transfer_alignment(self) -> bool:
+        """Return whether I/O transfers require block alignment.
+
+        Returns:
+            True when transfers must be aligned to ``self.block_align``.
+            This is required for O_DIRECT I/O and for io_uring_cmd operations.
+        """
+        return self.use_odirect or self.use_uring_cmd
+
+    def _resolve_max_data_transfer_size(self, configured_size: int) -> int:
+        """Resolve transfer split size from config or NVMe sysfs queue limits.
+
+        Args:
+            configured_size: Explicitly configured max data transfer size in bytes.
+                If > 0, this value is used directly. If <= 0, the size is
+                auto-detected from device queue limits.
+
+        Returns:
+            The resolved max data transfer size in bytes, guaranteed to be
+            a multiple of ``self.block_align``.
+
+        Raises:
+            ValueError: If ``configured_size`` is > 0 but not a multiple of
+                ``self.block_align``.
+        """
+        if configured_size > 0:
+            if configured_size % self.block_align != 0:
+                raise ValueError(
+                    f"max_data_transfer_size ({configured_size}) must be a "
+                    f"multiple of block_align ({self.block_align})"
+                )
+            return configured_size
+
+        queue_dir = _resolve_sysfs_queue_dir(self.device_path)
+        if queue_dir is None:
+            raise RuntimeError(
+                "RustRawBlockBackend: unable to derive NVMe sysfs queue path from "
+                "NVMe character device path "
+                f"{self.device_path} for auto max_data_transfer_size"
+            )
+
+        max_hw_sectors_kb = _read_sysfs_int(f"{queue_dir}/max_hw_sectors_kb")
+        if max_hw_sectors_kb is None or max_hw_sectors_kb <= 0:
+            raise RuntimeError(
+                "RustRawBlockBackend: failed to read max_hw_sectors_kb from "
+                f"{queue_dir} for auto max_data_transfer_size"
+            )
+
+        resolved_bytes = max_hw_sectors_kb * 1024
+        aligned_bytes = (resolved_bytes // self.block_align) * self.block_align
+        if aligned_bytes <= 0:
+            aligned_bytes = self.block_align
+
+        logger.info(
+            "RustRawBlockBackend: auto max_data_transfer_size=%d bytes "
+            "(device=%s, max_hw_sectors_kb=%s)",
+            aligned_bytes,
+            self.device_path,
+            max_hw_sectors_kb,
+        )
+        return aligned_bytes
+
+    def _rawdev(self):
+        """Return the lazily opened Rust raw-block device binding."""
+        if self._raw is None:
+            try:
+                # Third Party
+                from lmcache_rust_raw_block_io import RawBlockDevice  # type: ignore
+            except Exception as e:
+                raise RuntimeError(
+                    "Rust raw-block extension is not installed. "
+                    "Install / build `rust_raw_block_io` and retry."
+                ) from e
+            self._raw = RawBlockDevice(
+                self.device_path,
+                writable=True,
+                use_odirect=self.use_odirect,
+                alignment=self.block_align,
+                io_engine=self.io_engine,
+                iouring_queue_depth=self.iouring_queue_depth,
+                use_uring_cmd=self.use_uring_cmd,
+            )
+        return self._raw
+
+    def raw_device(self) -> Any:
+        """Return the lazily opened Rust raw-block device.
+
+        Returns:
+            The underlying Rust ``RawBlockDevice`` object.
+
+        Raises:
+            Exception: Propagates raw-device open errors from the Rust binding.
+        """
+        return self._rawdev()
+
+    def set_raw_device_for_testing(self, raw_device: Any) -> None:
+        """Replace the raw device handle used by this core.
+
+        Args:
+            raw_device: Object implementing the Rust raw-device methods.
+        """
+        self._raw = raw_device
+
+    def register_fixed_buffers_from_allocator(self, memory_allocator: Any) -> None:
+        """Register allocator pages with io_uring when the allocator exposes them.
+
+        Args:
+            memory_allocator: Local CPU allocator that may expose
+                ``get_paged_buffers()``.
+
+        Raises:
+            Exception: Propagates Rust registration errors after logging.
+        """
+        if self.io_engine != "io_uring":
+            return
+        paged_buffers = getattr(memory_allocator, "get_paged_buffers", None)
+        if not callable(paged_buffers):
+            logger.warning(
+                "RawBlockCore: allocator does not expose paged buffers; "
+                "io_uring fixed-buffer zero-copy is disabled"
+            )
+            return
+        buffers = paged_buffers()
+        if not buffers:
+            logger.warning(
+                "RawBlockCore: allocator returned no paged buffers; "
+                "io_uring fixed-buffer zero-copy is disabled"
+            )
+            return
+        buffer_ptrs = [buf.data_ptr() for buf in buffers]
+        buffer_sizes = [buf.numel() * buf.element_size() for buf in buffers]
+        self._rawdev().register_fixed_buffers(buffer_ptrs, buffer_sizes)
+        logger.info(
+            "RawBlockCore: registered %d paged buffers for io_uring fixed I/O",
+            len(buffers),
+        )
+
+    def contains_key(self, encoded_key: str, *, lock: bool = False) -> bool:
+        """Return whether one encoded key is present in the raw-block index.
+
+        Args:
+            encoded_key: Encoded raw-block key string.
+            lock: If true, increment the key's L2 lock refcount on hit.
+
+        Returns:
+            True when the key is indexed and available for load.
+        """
+        return self.exists_many([encoded_key], lock=lock)[0]
+
+    def exists_inflight(self, encoded_key: str) -> bool:
+        """Return whether a key currently has an in-flight write.
+
+        Args:
+            encoded_key: Encoded raw-block key string.
+
+        Returns:
+            True when the key is being written but not committed yet.
+        """
+        with self._lock:
+            return encoded_key in self._inflight
+
+    def get_metadata_many(
+        self, encoded_keys: Sequence[str]
+    ) -> list[DiskCacheMetadata | None]:
+        """Return metadata for encoded keys without loading payload bytes.
+
+        Args:
+            encoded_keys: Ordered encoded raw-block keys to inspect.
+
+        Returns:
+            A metadata-or-None list aligned with ``encoded_keys``.
+        """
+        with self._lock:
+            metas: list[DiskCacheMetadata | None] = []
+            for encoded_key in encoded_keys:
+                entry = self._index.get(encoded_key)
+                metas.append(entry.meta if entry is not None else None)
+            return metas
+
+    def get_metadata_prefix(
+        self,
+        encoded_keys: Sequence[str],
+        *,
+        lock: bool = False,
+        skip_locked: set[str] | None = None,
+    ) -> list[DiskCacheMetadata]:
+        """Return leading-hit metadata and optionally lock those entries.
+
+        Args:
+            encoded_keys: Ordered encoded raw-block keys to inspect.
+            lock: If true, increment L2 lock refcounts for every returned
+                metadata entry while holding the index lock.
+            skip_locked: Encoded keys that are already protected by the caller
+                and should not receive an additional lock refcount.
+
+        Returns:
+            Metadata for the contiguous leading hit prefix. The returned list
+            stops at the first missing key.
+        """
+        with self._lock:
+            metas: list[DiskCacheMetadata] = []
+            for encoded_key in encoded_keys:
+                entry = self._index.get(encoded_key)
+                if entry is None:
+                    break
+                metas.append(entry.meta)
+                if lock and (skip_locked is None or encoded_key not in skip_locked):
+                    self._lock_refcnt[encoded_key] = (
+                        self._lock_refcnt.get(encoded_key, 0) + 1
+                    )
+            return metas
+
+    def first_encoded_key(self) -> str | None:
+        """Return one indexed encoded key for diagnostics.
+
+        Returns:
+            The first indexed key according to dictionary iteration order, or
+            None if the recovered/indexed metadata is empty.
+        """
+        with self._lock:
+            return next(iter(self._index), None)
+
+    def lock_refcount(self, encoded_key: str) -> int:
+        """Return the L2 lock refcount for an encoded key.
+
+        Args:
+            encoded_key: Encoded raw-block key string.
+
+        Returns:
+            Current lock refcount, or zero when the key is unlocked or absent.
+        """
+        with self._lock:
+            return int(self._lock_refcnt.get(encoded_key, 0))
+
+    def inflight_io_count(self) -> int:
+        """Return the number of currently active raw-device I/O operations."""
+        with self._lock:
+            return int(self._inflight_io_count)
+
+    def indexed_key_count(self) -> int:
+        """Return the number of entries currently present in the key index."""
+        with self._lock:
+            return len(self._index)
+
+    def snapshot_indexed_keys(self) -> list[str]:
+        """Return a detached snapshot of encoded keys currently in the index."""
+        with self._lock:
+            return list(self._index.keys())
+
+    def entry_offset(self, encoded_key: str) -> int | None:
+        """Return the raw-device slot offset for an indexed key.
+
+        Args:
+            encoded_key: Encoded raw-block key string.
+
+        Returns:
+            Slot offset in bytes, or None when the key is not indexed.
+        """
+        with self._lock:
+            entry = self._index.get(encoded_key)
+            return None if entry is None else int(entry.offset)
+
+    def metadata_container_offsets(self) -> list[int]:
+        """Return checkpoint metadata container offsets in bytes."""
+        return self._meta_container_offsets()
+
+    def data_base_offset(self) -> int:
+        """Return the byte offset where raw-block data slots begin."""
+        return int(self._data_base_offset)
+
+    def put_many(
+        self,
+        keys: Sequence[RawBlockKeySpec],
+        objs: Sequence[MemoryObj],
+    ) -> RawBlockPutManyResult:
+        """Persist a batch of memory objects into raw-block slots.
+
+        Args:
+            keys: Ordered raw-block key specs corresponding to ``objs``.
+            objs: Memory objects whose byte buffers should be written.
+
+        Returns:
+            Per-key success results and newly stored encoded keys. If no free
+            raw-block slot is available, that key is reported as failed; slot
+            reclamation is owned by the adapter/controller calling
+            ``delete_many``.
+
+        Raises:
+            ValueError: If either sequence is empty or the sequence lengths do
+                not match.
+        """
+        if not keys or not objs:
+            raise ValueError("keys and objs must be non-empty")
+        if len(keys) != len(objs):
+            raise ValueError("keys and objs must have the same length")
+
+        results = [False] * len(keys)
+        stored_keys: list[str] = []
+
+        for i, (key, obj) in enumerate(zip(keys, objs, strict=False)):
+            if self._closed:
+                break
+
+            with self._lock:
+                if key.encoded in self._index:
+                    results[i] = True
+                    continue
+                if key.encoded in self._inflight:
+                    continue
+
+                try:
+                    offset = self._allocate_slot_locked()
+                except RuntimeError:
+                    logger.warning(
+                        "RawBlockCore: no free slot available for key %s",
+                        key.encoded,
+                    )
+                    continue
+
+                meta = DiskCacheMetadata(
+                    path=f"{self.device_path}@{offset}",
+                    size=len(obj.byte_array),
+                    shape=obj.metadata.shape,
+                    dtype=obj.metadata.dtype,
+                    cached_positions=obj.metadata.cached_positions,
+                    fmt=obj.metadata.fmt,
+                    pin_count=0,
+                )
+                self._inflight[key.encoded] = _Inflight(offset=offset, meta=meta)
+
+            success = self._write_one(key, obj, offset)
+
+            with self._lock:
+                inflight = self._inflight.pop(key.encoded, None)
+                if inflight is None:
+                    results[i] = False
+                    continue
+                if inflight.canceled or not success:
+                    self._append_free_slot_locked(
+                        self._offset_to_slot(int(inflight.offset))
+                    )
+                    self._meta_dirty_total += 1
+                    results[i] = False
+                    continue
+
+                self._index[key.encoded] = _Entry(
+                    offset=inflight.offset,
+                    size=inflight.meta.size,
+                    meta=inflight.meta,
+                )
+                self._meta_dirty_total += 1
+                results[i] = True
+                stored_keys.append(key.encoded)
+
+        return RawBlockPutManyResult(
+            results=results,
+            stored_keys=stored_keys,
+        )
+
+    def exists_many(
+        self,
+        encoded_keys: Sequence[str],
+        *,
+        lock: bool = False,
+    ) -> list[bool]:
+        """Return a full hit bitmap as booleans for encoded keys.
+
+        Args:
+            encoded_keys: Ordered encoded raw-block keys to check.
+            lock: If true, increment L2 lock refcounts for every hit.
+
+        Returns:
+            A list of booleans aligned with ``encoded_keys``.
+        """
+        results: list[bool] = []
+        with self._lock:
+            for encoded_key in encoded_keys:
+                found = encoded_key in self._index
+                results.append(found)
+                if found and lock:
+                    self._lock_refcnt[encoded_key] = (
+                        self._lock_refcnt.get(encoded_key, 0) + 1
+                    )
+        return results
+
+    def load_many_into(
+        self,
+        encoded_keys: Sequence[str],
+        objs: Sequence[MemoryObj],
+        *,
+        raise_on_error: bool = False,
+    ) -> list[bool]:
+        """Load raw-block payloads into caller-provided memory objects.
+
+        Args:
+            encoded_keys: Ordered encoded raw-block keys to load.
+            objs: Destination memory objects. Buffers must remain valid until
+                this method returns.
+            raise_on_error: If true, re-raise the first load exception instead
+                of logging it and returning ``False`` for that key.
+
+        Returns:
+            A list of per-key load success booleans aligned with
+            ``encoded_keys``.
+
+        Raises:
+            ValueError: If either sequence is empty or the sequence lengths do
+                not match.
+            Exception: Re-raises load errors when ``raise_on_error`` is true.
+        """
+        if not encoded_keys or not objs:
+            raise ValueError("encoded_keys and objs must be non-empty")
+        if len(encoded_keys) != len(objs):
+            raise ValueError("encoded_keys and objs must have the same length")
+
+        with self._lock:
+            items = [
+                (encoded_key, self._index.get(encoded_key))
+                for encoded_key in encoded_keys
+            ]
+            self._inflight_io_count += 1
+
+        results = [False] * len(encoded_keys)
+        try:
+            for i, (encoded_key, entry) in enumerate(items):
+                if entry is None:
+                    continue
+                try:
+                    payload_len = int(entry.size)
+                    total_len = (
+                        round_up(payload_len, self.block_align)
+                        if self._requires_transfer_alignment
+                        else payload_len
+                    )
+                    buf = memoryview(objs[i].byte_array)
+                    try:
+                        buf = buf.cast("B")
+                    except Exception:
+                        pass
+
+                    direct_view = self._build_direct_odirect_view(
+                        memory_obj=objs[i],
+                        payload_len=payload_len,
+                        total_len=total_len,
+                        buffer_len=len(buf),
+                        zero_tail=False,
+                    )
+                    if direct_view is not None:
+                        self._read_buffers(
+                            [entry.offset + self.header_bytes],
+                            [direct_view],
+                            [
+                                total_len
+                                if len(direct_view) >= total_len
+                                else payload_len
+                            ],
+                            [total_len],
+                        )
+                    else:
+                        self._read_buffers(
+                            [entry.offset + self.header_bytes],
+                            [buf],
+                            [payload_len],
+                            [total_len],
+                        )
+                    objs[i].metadata.cached_positions = entry.meta.cached_positions
+                    results[i] = True
+                except Exception as e:
+                    if raise_on_error:
+                        raise
+                    logger.error("RawBlockCore load failed for %s: %s", encoded_key, e)
+        finally:
+            with self._lock:
+                self._inflight_io_count -= 1
+                self._last_io_ts = time.monotonic()
+        return results
+
+    def unlock_many(self, encoded_keys: Sequence[str]) -> None:
+        """Release L2 lock references for encoded keys.
+
+        Args:
+            encoded_keys: Encoded raw-block keys whose lock refcounts should be
+                decremented. Missing keys and underflow are treated as no-ops.
+        """
+        with self._lock:
+            for encoded_key in encoded_keys:
+                refcnt = self._lock_refcnt.get(encoded_key, 0)
+                if refcnt <= 1:
+                    self._lock_refcnt.pop(encoded_key, None)
+                else:
+                    self._lock_refcnt[encoded_key] = refcnt - 1
+
+    def delete_many(
+        self,
+        encoded_keys: Sequence[str],
+        *,
+        force: bool = False,
+    ) -> list[bool]:
+        """Delete indexed keys and recycle their slots when allowed.
+
+        Args:
+            encoded_keys: Ordered encoded raw-block keys to delete.
+            force: If true, delete locked keys as well. Normal MP eviction uses
+                false so locked entries are preserved.
+
+        Returns:
+            A list of per-key deletion booleans aligned with ``encoded_keys``.
+        """
+        deleted: list[bool] = []
+        with self._lock:
+            for encoded_key in encoded_keys:
+                entry = self._index.get(encoded_key)
+                locked = self._lock_refcnt.get(encoded_key, 0) > 0
+                if entry is not None and locked and not force:
+                    deleted.append(False)
+                    continue
+
+                removed_entry = self._index.pop(encoded_key, None)
+                inflight = self._inflight.get(encoded_key)
+                if inflight is not None:
+                    inflight.canceled = True
+                self._lock_refcnt.pop(encoded_key, None)
+                if removed_entry is not None:
+                    self._append_free_slot_locked(
+                        self._offset_to_slot(int(removed_entry.offset))
+                    )
+                    self._meta_dirty_total += 1
+                deleted.append(removed_entry is not None or inflight is not None)
+        return deleted
+
+    def usage(self) -> tuple[float, float]:
+        """Return current raw-block slot usage fractions.
+
+        Returns:
+            ``(current_usage, projected_usage)``. Raw-block has no separate
+            projected value, so both values are identical. ``(-1.0, -1.0)``
+            indicates that usable capacity is unknown.
+        """
+        with self._lock:
+            usable_capacity = self._max_slots * self.slot_bytes
+            if usable_capacity <= 0:
+                return (-1.0, -1.0)
+            used_slots = len(self._index) + len(self._inflight)
+            usage = (used_slots * self.slot_bytes) / usable_capacity
+            return (usage, usage)
+
+    def checkpoint_now(self) -> None:
+        """Synchronously write a metadata checkpoint."""
+        self._checkpoint_once(force=True)
+
+    def apply_loaded_state(self, data: dict[str, Any]) -> bool:
+        """Validate and apply a recovered metadata checkpoint payload.
+
+        Args:
+            data: Decoded checkpoint dictionary.
+
+        Returns:
+            True when the payload shape and layout match this core and all
+            valid entries were applied. Invalid per-entry records are skipped.
+        """
+        return self._apply_loaded_state(data)
+
+    def report_status(self) -> dict:
+        """Return raw-block health, layout, metadata, and in-flight counters."""
+        with self._lock:
+            return {
+                "is_healthy": not self._closed,
+                "type": "RawBlockCore",
+                "key_namespace": self.key_namespace,
+                "device_path": self.device_path,
+                "block_align": self.block_align,
+                "header_bytes": self.header_bytes,
+                "slot_bytes": self.slot_bytes,
+                "meta_total_bytes": self.meta_total_bytes,
+                "usable_capacity_bytes": self._max_slots * self.slot_bytes,
+                "indexed_key_count": len(self._index),
+                "inflight_key_count": len(self._inflight),
+                "locked_key_count": sum(
+                    1 for refcnt in self._lock_refcnt.values() if refcnt > 0
+                ),
+                "free_slot_count": len(self._free_slots),
+                "next_slot": self._next_slot,
+                "max_slots": self._max_slots,
+                "metadata_seq": self._meta_seq,
+                "metadata_dirty_total": self._meta_dirty_total,
+                "metadata_persisted": self._meta_persisted,
+                "inflight_io_count": self._inflight_io_count,
+                "use_odirect": self.use_odirect,
+                "enable_zero_copy": self.enable_zero_copy,
+                "io_engine": self.io_engine,
+                "iouring_queue_depth": self.iouring_queue_depth,
+                "use_uring_cmd": self.use_uring_cmd,
+            }
+
+    def close(self) -> None:
+        """Stop checkpointing, write a final checkpoint, and close the device."""
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+
+        self._meta_stop_evt.set()
+        if self._meta_thread is not None:
+            self._meta_thread.join(timeout=5)
+            self._meta_thread = None
+
+        try:
+            self._checkpoint_once(force=True)
+        except Exception as e:
+            logger.warning("RawBlockCore final checkpoint failed: %s", e)
+
+        if self._raw is not None:
+            try:
+                self._raw.close()
+            except Exception as e:
+                logger.warning(
+                    "Failed to close raw block device %s: %s", self.device_path, e
+                )
+            finally:
+                self._raw = None
+
+    def _cleanup_after_init_failure(self) -> None:
+        """Close resources that may have been opened before init failed."""
+        self._meta_stop_evt.set()
+        if self._meta_thread is not None:
+            self._meta_thread.join(timeout=5)
+            self._meta_thread = None
+        if self._raw is not None:
+            try:
+                self._raw.close()
+            except Exception as e:
+                logger.warning(
+                    "Failed to close raw block device %s: %s", self.device_path, e
+                )
+            finally:
+                self._raw = None
+        self._closed = True
+
+    def _byte_view(self, buf: Any) -> memoryview:
+        """Return a byte-addressable memoryview over a Python buffer.
+
+        Args:
+            buf: Object implementing the Python buffer protocol.
+
+        Returns:
+            A memoryview with one-byte elements.
+
+        Raises:
+            TypeError: If ``buf`` does not expose a compatible contiguous buffer.
+        """
+        view = buf if isinstance(buf, memoryview) else memoryview(buf)
+        if view.itemsize == 1 and view.format in ("B", "b", "c"):
+            return view
+        return view.cast("B")
+
+    def _is_buffer_aligned(self, buf: Any) -> bool:
+        """Check if a buffer is aligned to the block alignment boundary.
+
+        Args:
+            buf: Object implementing the Python buffer protocol.
+
+        Returns:
+            True if the buffer is aligned, False otherwise.
+        """
+        if not self.use_odirect:
+            return True
+        view = self._byte_view(buf)
+        # Check if the buffer pointer is aligned
+        ptr = ctypes.addressof((ctypes.c_byte * 1).from_buffer(view))
+        return ptr % self.block_align == 0
+
+    def _build_direct_odirect_view(
+        self,
+        memory_obj: MemoryObj,
+        payload_len: int,
+        total_len: int,
+        buffer_len: int,
+        *,
+        zero_tail: bool,
+    ) -> Optional[memoryview]:
+        """Build an aligned memoryview for direct O_DIRECT I/O when possible.
+
+        Args:
+            memory_obj: Memory object whose backing allocation may be aligned.
+            payload_len: Logical payload length in bytes.
+            total_len: I/O length after any O_DIRECT padding.
+            buffer_len: Available buffer length in bytes.
+            zero_tail: Whether to zero any padded tail bytes before writing.
+
+        Returns:
+            A direct memoryview over the allocation, or None when the memory
+            object is unsuitable for direct I/O.
+        """
+        if not self.use_odirect or not self.enable_zero_copy:
+            return None
+
+        ptr_val = getattr(memory_obj, "data_ptr", None)
+        if callable(ptr_val):
+            try:
+                ptr_val = ptr_val()
+            except Exception:
+                ptr_val = None
+        if ptr_val is None:
+            return None
+        if buffer_len <= 0:
+            return None
+
+        ptr = int(ptr_val)
+        if ptr <= 0 or ptr % self.block_align != 0:
+            return None
+        if buffer_len < payload_len:
+            return None
+
+        view_len = min(buffer_len, total_len)
+        if view_len < payload_len:
+            return None
+
+        try:
+            raw = (ctypes.c_ubyte * view_len).from_address(ptr)
+            view = memoryview(raw)
+            if zero_tail and total_len > payload_len and view_len >= total_len:
+                ctypes.memset(ptr + payload_len, 0, total_len - payload_len)
+            return view
+        except Exception:
+            return None
+
+    def _prepare_write_payload(self, memory_obj: MemoryObj) -> tuple[Any, int, int]:
+        """Prepare the payload buffer and lengths for a raw-block write.
+
+        Args:
+            memory_obj: Source object to persist.
+
+        Returns:
+            A tuple of ``(buffer, payload_len, total_len)`` where ``total_len``
+            includes any O_DIRECT padding.
+
+        Raises:
+            RuntimeError: If the aligned payload would exceed slot capacity.
+        """
+        buf = memory_obj.byte_array
+        if hasattr(buf, "cast"):
+            buf = buf.cast("B")
+        payload_len = len(memory_obj.byte_array)
+        payload_capacity = self.slot_bytes - self.header_bytes
+        if payload_len > payload_capacity:
+            raise RuntimeError(
+                f"RawBlockCore payload {payload_len} exceeds slot capacity "
+                f"{payload_capacity}"
+            )
+        total_len = payload_len
+        if self._requires_transfer_alignment:
+            total_len = round_up(payload_len, self.block_align)
+            if total_len > payload_capacity:
+                raise RuntimeError(
+                    f"Aligned payload {total_len} exceeds slot capacity "
+                    f"{payload_capacity}"
+                )
+            direct_view = self._build_direct_odirect_view(
+                memory_obj=memory_obj,
+                payload_len=payload_len,
+                total_len=total_len,
+                buffer_len=len(buf),
+                zero_tail=True,
+            )
+            if direct_view is not None:
+                buf = direct_view
+        return buf, payload_len, total_len
+
+    def _validate_uring_cmd_chunk(self, offset: int, total_len: int) -> None:
+        """Validate one NVMe raw-command transfer range.
+
+        Args:
+            offset: Device byte offset for the transfer.
+            total_len: Transfer size in bytes.
+
+        Raises:
+            ValueError: If either value is not block aligned.
+        """
+        if offset % self.block_align != 0:
+            raise ValueError("io_uring_cmd requires aligned offsets")
+        if total_len % self.block_align != 0:
+            raise ValueError("io_uring_cmd requires aligned transfer lengths")
+
+    def _write_uring_cmd_buffers(
+        self,
+        offsets: Sequence[int],
+        buffers: Sequence[Any],
+        payload_lens: Sequence[int],
+        total_lens: Sequence[int],
+    ) -> None:
+        """Write buffers as bounded NVMe raw-command chunks.
+
+        Args:
+            offsets: Device offsets for each logical write.
+            buffers: Source buffers.
+            payload_lens: Logical source byte counts.
+            total_lens: Physical transfer sizes, including padding.
+
+        Raises:
+            ValueError: If lengths are inconsistent or unaligned.
+            Exception: Propagates Rust raw-device write errors.
+        """
+        raw_dev = self._rawdev()
+        chunk_offsets: list[int] = []
+        chunk_buffers: list[memoryview] = []
+        chunk_lens: list[int] = []
+        keepalive: list[memoryview] = []
+
+        for offset, buf, payload_len, total_len in zip(
+            offsets, buffers, payload_lens, total_lens, strict=True
+        ):
+            offset = int(offset)
+            payload_len = int(payload_len)
+            total_len = int(total_len)
+            self._validate_uring_cmd_chunk(offset, total_len)
+
+            view = self._byte_view(buf)
+            if len(view) < total_len:
+                if len(view) < payload_len:
+                    raise ValueError("input buffer shorter than payload_len")
+                padded = bytearray(total_len)
+                padded[:payload_len] = view[:payload_len]
+                view = memoryview(padded)
+            else:
+                view = view[:total_len]
+            keepalive.append(view)
+
+            cursor = 0
+            while cursor < total_len:
+                chunk_len = min(self.max_data_transfer_size, total_len - cursor)
+                self._validate_uring_cmd_chunk(offset + cursor, chunk_len)
+                chunk_offsets.append(offset + cursor)
+                chunk_buffers.append(view[cursor : cursor + chunk_len])
+                chunk_lens.append(chunk_len)
+                cursor += chunk_len
+
+        if not chunk_offsets:
+            return
+        batch_id = raw_dev.batched_write(
+            chunk_offsets,
+            chunk_buffers,
+            chunk_lens,
+        )
+        raw_dev.wait_iouring(batch_id)
+        keepalive.clear()
+
+    def _read_uring_cmd_buffers(
+        self,
+        offsets: Sequence[int],
+        buffers: Sequence[Any],
+        payload_lens: Sequence[int],
+        total_lens: Sequence[int],
+    ) -> None:
+        """Read buffers as bounded NVMe raw-command chunks.
+
+        Args:
+            offsets: Device offsets for each logical read.
+            buffers: Destination buffers.
+            payload_lens: Logical bytes to expose to callers.
+            total_lens: Physical transfer sizes, including padding.
+
+        Raises:
+            ValueError: If lengths are inconsistent or unaligned.
+            Exception: Propagates Rust raw-device read errors.
+        """
+        raw_dev = self._rawdev()
+        read_uring = raw_dev.read_uring
+
+        for offset, buf, payload_len, total_len in zip(
+            offsets, buffers, payload_lens, total_lens, strict=True
+        ):
+            offset = int(offset)
+            payload_len = int(payload_len)
+            total_len = int(total_len)
+            self._validate_uring_cmd_chunk(offset, total_len)
+
+            dst = self._byte_view(buf)
+            if len(dst) < total_len:
+                if len(dst) < payload_len:
+                    raise ValueError("output buffer shorter than payload_len")
+                target = memoryview(bytearray(total_len))
+                copy_back = True
+            else:
+                target = dst[:total_len]
+                copy_back = False
+
+            cursor = 0
+            while cursor < total_len:
+                chunk_len = min(self.max_data_transfer_size, total_len - cursor)
+                self._validate_uring_cmd_chunk(offset + cursor, chunk_len)
+                read_uring(
+                    offset + cursor,
+                    target[cursor : cursor + chunk_len],
+                    chunk_len,
+                    chunk_len,
+                )
+                cursor += chunk_len
+
+            if copy_back:
+                dst[:payload_len] = target[:payload_len]
+
+    def _write_buffers(
+        self,
+        offsets: Sequence[int],
+        buffers: Sequence[Any],
+        payload_lens: Sequence[int],
+        total_lens: Sequence[int],
+    ) -> None:
+        """Write one or more buffers through the configured Rust I/O path.
+
+        Args:
+            offsets: Device offsets for each write.
+            buffers: Python buffers to write.
+            payload_lens: Logical payload lengths for each buffer.
+            total_lens: Physical I/O lengths for each buffer.
+
+        Raises:
+            RuntimeError: If the requested io_uring mode is unavailable.
+            Exception: Propagates Rust raw-device write errors.
+        """
+        raw_dev = self._rawdev()
+        if self.io_engine != "io_uring":
+            for offset, buf, payload_len, total_len in zip(
+                offsets, buffers, payload_lens, total_lens, strict=True
+            ):
+                raw_dev.pwrite_from_buffer(offset, buf, payload_len, total_len)
+            return
+
+        if self.use_uring_cmd:
+            self._write_uring_cmd_buffers(
+                offsets,
+                buffers,
+                payload_lens,
+                total_lens,
+            )
+            return
+
+        can_batch = all(
+            int(payload_len) == int(total_len)
+            for payload_len, total_len in zip(payload_lens, total_lens, strict=True)
+        )
+        if can_batch:
+            batch_id = raw_dev.batched_write(
+                [int(offset) for offset in offsets],
+                list(buffers),
+                [int(total_len) for total_len in total_lens],
+            )
+            raw_dev.wait_iouring(batch_id)
+            return
+
+        for offset, buf, payload_len, total_len in zip(
+            offsets, buffers, payload_lens, total_lens, strict=True
+        ):
+            raw_dev.write_uring(int(offset), buf, int(payload_len), int(total_len))
+
+    def _read_buffers(
+        self,
+        offsets: Sequence[int],
+        buffers: Sequence[Any],
+        payload_lens: Sequence[int],
+        total_lens: Sequence[int],
+    ) -> None:
+        """Read one or more buffers through the configured Rust I/O path.
+
+        Args:
+            offsets: Device offsets for each read.
+            buffers: Destination Python buffers.
+            payload_lens: Logical payload lengths to expose to callers.
+            total_lens: Physical I/O lengths for each read.
+
+        Raises:
+            RuntimeError: If the requested io_uring mode is unavailable.
+            Exception: Propagates Rust raw-device read errors.
+        """
+        raw_dev = self._rawdev()
+        if self.io_engine != "io_uring":
+            for offset, buf, payload_len, total_len in zip(
+                offsets, buffers, payload_lens, total_lens, strict=True
+            ):
+                raw_dev.pread_into(offset, buf, payload_len, total_len)
+            return
+
+        if self.use_uring_cmd:
+            self._read_uring_cmd_buffers(offsets, buffers, payload_lens, total_lens)
+            return
+
+        can_batch = all(
+            int(payload_len) == int(total_len)
+            for payload_len, total_len in zip(payload_lens, total_lens, strict=True)
+        )
+        # batched_read requires aligned buffers when O_DIRECT is enabled
+        # Check alignment before using batched_read
+        if can_batch and all(self._is_buffer_aligned(buf) for buf in buffers):
+            batch_id = raw_dev.batched_read(
+                [int(offset) for offset in offsets],
+                list(buffers),
+                [int(total_len) for total_len in total_lens],
+            )
+            raw_dev.wait_iouring(batch_id)
+            return
+
+        for offset, buf, payload_len, total_len in zip(
+            offsets, buffers, payload_lens, total_lens, strict=True
+        ):
+            raw_dev.read_uring(int(offset), buf, int(payload_len), int(total_len))
+
+    def _write_one(
+        self, key: RawBlockKeySpec, memory_obj: MemoryObj, offset: int
+    ) -> bool:
+        """Write one object header and payload into a raw-block slot.
+
+        Args:
+            key: Raw-block key spec with the slot-header identity.
+            memory_obj: Source object to write.
+            offset: Slot byte offset on the raw device.
+
+        Returns:
+            True when both header and payload writes complete; false otherwise.
+        """
+        try:
+            header = self._encode_header(key.slot_identity, len(memory_obj.byte_array))
+            buf, payload_len, total_len = self._prepare_write_payload(memory_obj)
+
+            with self._lock:
+                self._inflight_io_count += 1
+            try:
+                hdr_total = (
+                    round_up(len(header), self.block_align)
+                    if self._requires_transfer_alignment
+                    else len(header)
+                )
+                header_buf: Any = header
+                if self.io_engine != "io_uring" and len(header) < hdr_total:
+                    padded_header = bytearray(header)
+                    padded_header.extend(b"\x00" * (hdr_total - len(header)))
+                    header_buf = padded_header
+                self._write_buffers(
+                    [offset, offset + self.header_bytes],
+                    [header_buf, buf],
+                    [
+                        hdr_total if self.io_engine == "io_uring" else len(header),
+                        payload_len,
+                    ],
+                    [hdr_total, total_len],
+                )
+            finally:
+                with self._lock:
+                    self._inflight_io_count -= 1
+                    self._last_io_ts = time.monotonic()
+            return True
+        except Exception as e:
+            logger.error("RawBlockCore write failed for %s: %s", key.encoded, e)
+            return False
+
+    def _encode_header(self, slot_identity: int, payload_len: int) -> bytes:
+        """Encode a fixed-size raw-block slot header."""
+        hdr = bytearray(self.header_bytes)
+        hdr[0:8] = b"LMCBLK01"
+        hdr[8:16] = int(slot_identity & ((1 << 64) - 1)).to_bytes(
+            8,
+            "little",
+            signed=False,
+        )
+        hdr[16:24] = int(payload_len).to_bytes(8, "little", signed=False)
+        return bytes(hdr)
+
+    def _decode_slot_header(self, hdr: bytes) -> Optional[tuple[int, int]]:
+        """Decode a raw-block slot header into identity and payload length."""
+        if len(hdr) < 24 or hdr[0:8] != b"LMCBLK01":
+            return None
+        slot_identity = int.from_bytes(hdr[8:16], "little", signed=False)
+        payload_len = int.from_bytes(hdr[16:24], "little", signed=False)
+        return slot_identity, payload_len
+
+    def _read_slot_header(self, offset: int) -> Optional[tuple[int, int]]:
+        """Read and decode the slot header at a raw-device offset."""
+        buf = bytearray(self.header_bytes)
+        try:
+            with self._lock:
+                self._inflight_io_count += 1
+            self._read_buffers(
+                [offset],
+                [buf],
+                [self.header_bytes],
+                [self.header_bytes],
+            )
+            return self._decode_slot_header(buf)
+        except Exception:
+            return None
+        finally:
+            with self._lock:
+                self._inflight_io_count -= 1
+                self._last_io_ts = time.monotonic()
+
+    def _ensure_capacity_and_layout(self) -> None:
+        """Open the device if needed and compute metadata/data layout."""
+        if self._effective_capacity_bytes > 0 and self._max_slots > 0:
+            return
+
+        device_size = int(self._rawdev().size_bytes())
+        requested = self.capacity_bytes if self.capacity_bytes > 0 else device_size
+        self._effective_capacity_bytes = min(requested, device_size)
+        self.capacity_bytes = self._effective_capacity_bytes
+
+        if self.meta_total_bytes >= self._effective_capacity_bytes:
+            raise RuntimeError("metadata region exceeds usable device capacity")
+
+        self._data_base_offset = self.meta_total_bytes
+        data_bytes = self._effective_capacity_bytes - self._data_base_offset
+        self._max_slots = data_bytes // self.slot_bytes
+        if self._max_slots <= 0:
+            raise RuntimeError(
+                "raw block capacity too small for slot size after metadata"
+            )
+
+    def _slot_to_offset(self, slot: int) -> int:
+        """Convert a data-slot index to its byte offset."""
+        return self._data_base_offset + slot * self.slot_bytes
+
+    def _offset_to_slot(self, offset: int) -> int:
+        """Convert a data-slot byte offset to its slot index."""
+        return (offset - self._data_base_offset) // self.slot_bytes
+
+    def _allocate_slot_locked(self) -> int:
+        """Allocate a slot offset while ``self._lock`` is held."""
+        self._ensure_capacity_and_layout()
+        if self._free_slots:
+            return self._slot_to_offset(self._free_slots.pop())
+        if self._next_slot < self._max_slots:
+            slot = self._next_slot
+            self._next_slot += 1
+            return self._slot_to_offset(slot)
+        raise RuntimeError("No free slots available")
+
+    def _append_free_slot_locked(self, slot: int) -> None:
+        """Add a slot to the free list while ``self._lock`` is held."""
+        if slot < 0 or slot >= self._max_slots:
+            return
+        if slot in self._free_slots:
+            return
+        self._free_slots.append(slot)
+
+    def _checkpoint_loop(self) -> None:
+        """Periodically checkpoint dirty metadata until shutdown."""
+        interval = max(1, self.meta_checkpoint_interval_sec)
+        while not self._meta_stop_evt.wait(interval):
+            try:
+                self._checkpoint_once(force=False)
+            except Exception as e:
+                logger.warning("Periodic raw-block metadata checkpoint failed: %s", e)
+
+    def _meta_payload_capacity(self) -> int:
+        """Return usable bytes in one metadata checkpoint payload area."""
+        return self._meta_container_bytes - self.block_align
+
+    def _meta_container_offsets(self) -> list[int]:
+        """Return byte offsets for mirrored metadata checkpoint containers."""
+        return [
+            idx * self._meta_container_bytes for idx in range(self._meta_copy_count)
+        ]
+
+    def _read_meta_header(self, container_offset: int) -> Optional[dict[str, int]]:
+        """Read and validate a metadata checkpoint header."""
+        buf = bytearray(self.block_align)
+        try:
+            self._read_buffers(
+                [container_offset],
+                [buf],
+                [self.block_align],
+                [self.block_align],
+            )
+        except Exception:
+            return None
+
+        hdr = bytes(buf[: _META_HEADER_STRUCT.size])
+        magic, version, seq, payload_len, crc = _META_HEADER_STRUCT.unpack(hdr)
+        if magic != self.meta_magic or version != self.meta_version:
+            return None
+
+        payload_cap = self._meta_payload_capacity()
+        if payload_len <= 0 or payload_len > payload_cap:
+            return None
+        return {
+            "seq": int(seq),
+            "payload_len": int(payload_len),
+            "crc": int(crc),
+            "container_offset": int(container_offset),
+        }
+
+    def _load_meta_payload(self, header: dict[str, int]) -> Optional[bytes]:
+        """Load and CRC-validate a checkpoint payload for a metadata header."""
+        payload_len = int(header["payload_len"])
+        payload_off = int(header["container_offset"]) + self.block_align
+        total_len = round_up(payload_len, self.block_align)
+        buf = bytearray(total_len)
+        try:
+            self._read_buffers([payload_off], [buf], [payload_len], [total_len])
+        except Exception:
+            return None
+
+        payload = bytes(buf[:payload_len])
+        crc = zlib.crc32(payload) & 0xFFFFFFFF
+        if crc != int(header["crc"]):
+            return None
+        return payload
+
+    def _select_latest_checkpoint(
+        self,
+    ) -> tuple[Optional[dict[str, int]], Optional[bytes]]:
+        """Return the newest valid checkpoint header and payload."""
+        best_header: Optional[dict[str, int]] = None
+        best_payload: Optional[bytes] = None
+        for offset in self._meta_container_offsets():
+            header = self._read_meta_header(offset)
+            if header is None:
+                continue
+            payload = self._load_meta_payload(header)
+            if payload is None:
+                continue
+            if best_header is None or int(header["seq"]) > int(best_header["seq"]):
+                best_header = header
+                best_payload = payload
+        return best_header, best_payload
+
+    def _snapshot_state(self) -> tuple[dict[str, Any], int]:
+        """Build a JSON-serializable checkpoint state snapshot."""
+        with self._lock:
+            dirty_total = self._meta_dirty_total
+            snapshot = {
+                "version": 1,
+                "device_path": self.device_path,
+                "capacity_bytes": self.capacity_bytes,
+                "block_align": self.block_align,
+                "header_bytes": self.header_bytes,
+                "slot_bytes": self.slot_bytes,
+                "meta_total_bytes": self.meta_total_bytes,
+                "meta_magic": self.meta_magic_text,
+                "meta_version": self.meta_version,
+                "data_base_offset": self._data_base_offset,
+                "next_slot": self._next_slot,
+                "free_slots": list(self._free_slots),
+                "entries": {
+                    encoded_key: {
+                        "offset": entry.offset,
+                        "size": entry.meta.size,
+                        "shape": list(entry.meta.shape)
+                        if entry.meta.shape is not None
+                        else None,
+                        "dtype": self._checkpoint_dtype_name(entry.meta.dtype),
+                        "fmt": (
+                            entry.meta.fmt.name
+                            if entry.meta.fmt is not None
+                            and hasattr(entry.meta.fmt, "name")
+                            else str(entry.meta.fmt)
+                            if entry.meta.fmt is not None
+                            else None
+                        ),
+                        "cached_positions": (
+                            entry.meta.cached_positions.tolist()
+                            if entry.meta.cached_positions is not None
+                            and hasattr(entry.meta.cached_positions, "tolist")
+                            else None
+                        ),
+                    }
+                    for encoded_key, entry in self._index.items()
+                },
+            }
+        return snapshot, dirty_total
+
+    def _checkpoint_dtype_name(self, dtype: torch.dtype | None) -> str | None:
+        """Return a durable checkpoint string for a torch dtype.
+
+        Args:
+            dtype: Torch dtype from recovered or live memory metadata.
+
+        Returns:
+            Stable LMCache dtype name when known, ``str(dtype)`` for unknown
+            torch dtypes, or None when no dtype is available.
+        """
+        if dtype is None:
+            return None
+        return TORCH_DTYPE_TO_STR_DTYPE.get(dtype, str(dtype))
+
+    def _write_checkpoint(self, payload: bytes, dirty_total_snapshot: int) -> bool:
+        """Write one checkpoint copy and advance persisted metadata counters."""
+        payload_cap = self._meta_payload_capacity()
+        if len(payload) > payload_cap:
+            logger.warning(
+                "RawBlockCore metadata payload too large (%d > %d), "
+                "skipping checkpoint",
+                len(payload),
+                payload_cap,
+            )
+            return False
+
+        next_seq = self._meta_seq + 1
+        target_idx = int((next_seq - 1) % self._meta_copy_count)
+        target = self._meta_container_offsets()[target_idx]
+
+        payload_len = len(payload)
+        payload_total_len = round_up(payload_len, self.block_align)
+        payload_off = target + self.block_align
+        crc = zlib.crc32(payload) & 0xFFFFFFFF
+
+        header_block = bytearray(self.block_align)
+        header_block[: _META_HEADER_STRUCT.size] = _META_HEADER_STRUCT.pack(
+            self.meta_magic,
+            self.meta_version,
+            int(next_seq),
+            int(payload_len),
+            int(crc),
+        )
+
+        self._write_buffers(
+            [payload_off, target],
+            [payload, header_block],
+            [payload_len, self.block_align],
+            [payload_total_len, self.block_align],
+        )
+
+        with self._lock:
+            self._meta_seq = int(next_seq)
+            self._meta_persisted = max(self._meta_persisted, int(dirty_total_snapshot))
+        return True
+
+    def _checkpoint_once(self, force: bool) -> bool:
+        """Write a metadata checkpoint when dirty and sufficiently idle."""
+        with self._lock:
+            dirty = self._meta_dirty_total > self._meta_persisted
+            idle_ok = self._inflight_io_count == 0 and (
+                time.monotonic() - self._last_io_ts
+            ) >= (self.meta_idle_quiet_ms / 1000.0)
+
+        if not dirty:
+            return False
+        if not force and not idle_ok:
+            return False
+
+        snapshot, dirty_total_snapshot = self._snapshot_state()
+        payload = json.dumps(snapshot, separators=(",", ":"), ensure_ascii=True).encode(
+            "utf-8"
+        )
+        return self._write_checkpoint(payload, dirty_total_snapshot)
+
+    def _is_valid_checkpoint_entry(self, offset: int, size: int) -> bool:
+        """Return whether a checkpoint entry references a valid data slot."""
+        if offset < self._data_base_offset:
+            return False
+        rel = offset - self._data_base_offset
+        if rel % self.slot_bytes != 0:
+            return False
+        slot = rel // self.slot_bytes
+        if slot >= self._max_slots:
+            return False
+        return 0 < size <= (self.slot_bytes - self.header_bytes)
+
+    def _apply_loaded_state(self, data: dict[str, Any]) -> bool:
+        """Apply decoded checkpoint state after validating layout fields."""
+        if not isinstance(data, dict):
+            return False
+        if int(data.get("version", 0)) != 1:
+            return False
+        checkpoint_device_path = data.get("device_path")
+        if checkpoint_device_path and checkpoint_device_path != self.device_path:
+            logger.warning("Device metadata device_path mismatch; ignoring metadata")
+            return False
+        if int(data.get("slot_bytes", self.slot_bytes)) != self.slot_bytes:
+            logger.warning("Device metadata slot_bytes mismatch; ignoring metadata")
+            return False
+        if (
+            int(data.get("meta_total_bytes", self.meta_total_bytes))
+            != self.meta_total_bytes
+        ):
+            logger.warning(
+                "Device metadata meta_total_bytes mismatch; ignoring metadata"
+            )
+            return False
+        if str(data.get("meta_magic", self.meta_magic_text)) != self.meta_magic_text:
+            logger.warning("Device metadata meta_magic mismatch; ignoring metadata")
+            return False
+        if int(data.get("meta_version", self.meta_version)) != self.meta_version:
+            logger.warning("Device metadata meta_version mismatch; ignoring metadata")
+            return False
+
+        try:
+            next_slot = int(data.get("next_slot", 0))
+        except Exception:
+            logger.warning("Device metadata next_slot is invalid; ignoring metadata")
+            return False
+        if next_slot < 0 or next_slot > self._max_slots:
+            logger.warning(
+                "Device metadata next_slot out of range (%d); ignoring metadata",
+                next_slot,
+            )
+            return False
+
+        raw_free_slots = data.get("free_slots", [])
+        if not isinstance(raw_free_slots, list):
+            logger.warning("Device metadata free_slots is invalid; ignoring metadata")
+            return False
+        free_slots: list[int] = []
+        seen_slots: set[int] = set()
+        for raw_slot in raw_free_slots:
+            try:
+                slot = int(raw_slot)
+            except Exception:
+                logger.warning(
+                    "Device metadata free_slots contains non-integer; ignoring metadata"
+                )
+                return False
+            if slot < 0 or slot >= self._max_slots:
+                logger.warning(
+                    "Device metadata free_slots contains out-of-range slot %d; "
+                    "ignoring metadata",
+                    slot,
+                )
+                return False
+            if slot in seen_slots:
+                continue
+            seen_slots.add(slot)
+            free_slots.append(slot)
+
+        with self._lock:
+            self._next_slot = next_slot
+            self._free_slots = free_slots
+            self._index.clear()
+            self._lock_refcnt.clear()
+
+            entries = data.get("entries", {})
+            if isinstance(entries, dict):
+                for encoded_key, entry in entries.items():
+                    if not isinstance(entry, dict):
+                        continue
+
+                    offset = int(entry.get("offset", 0))
+                    size = int(entry.get("size", 0))
+                    shape_list = entry.get("shape")
+                    fmt_name = entry.get("fmt")
+                    cached_positions_list = entry.get("cached_positions")
+                    dtype_name = entry.get("dtype")
+
+                    if not self._is_valid_checkpoint_entry(offset, size):
+                        continue
+
+                    shape = (
+                        torch.Size(list(shape_list)) if shape_list is not None else None
+                    )
+                    fmt = (
+                        MemoryFormat[fmt_name]
+                        if isinstance(fmt_name, str)
+                        and fmt_name in MemoryFormat.__members__
+                        else MemoryFormat.UNDEFINED
+                    )
+                    cached_positions = (
+                        torch.tensor(cached_positions_list, dtype=torch.long)
+                        if cached_positions_list is not None
+                        else None
+                    )
+                    dtype = self._recover_checkpoint_dtype(
+                        str(encoded_key),
+                        dtype_name,
+                    )
+
+                    meta = DiskCacheMetadata(
+                        path=f"{self.device_path}@{offset}",
+                        size=size,
+                        shape=shape,
+                        dtype=dtype,
+                        cached_positions=cached_positions,
+                        fmt=fmt,
+                        pin_count=0,
+                    )
+                    self._index[encoded_key] = _Entry(
+                        offset=offset, size=size, meta=meta
+                    )
+
+            used_slots = {
+                self._offset_to_slot(int(entry.offset))
+                for entry in self._index.values()
+            }
+            self._free_slots = [
+                slot for slot in self._free_slots if slot not in used_slots
+            ]
+
+            self._meta_dirty_total = 0
+            self._meta_persisted = 0
+
+        if self.meta_verify_on_load:
+            self._validate_loaded_entries()
+        return True
+
+    def _recover_checkpoint_dtype(
+        self,
+        encoded_key: str,
+        dtype_name: Any,
+    ) -> torch.dtype | None:
+        """Recover checkpoint dtype from entry metadata or legacy key strings.
+
+        Args:
+            encoded_key: Encoded raw-block key from the checkpoint entry.
+            dtype_name: Raw dtype value stored in the checkpoint entry.
+
+        Returns:
+            A torch dtype when recovery succeeds, otherwise None.
+        """
+        if isinstance(dtype_name, str):
+            dtype = STR_DTYPE_TO_TORCH_DTYPE.get(dtype_name)
+            if dtype is not None:
+                return dtype
+
+            torch_prefix = "torch."
+            if dtype_name.startswith(torch_prefix):
+                dtype_attr = dtype_name.removeprefix(torch_prefix)
+                dtype = STR_DTYPE_TO_TORCH_DTYPE.get(dtype_attr)
+                if dtype is not None:
+                    return dtype
+                torch_dtype = getattr(torch, dtype_attr, None)
+                if isinstance(torch_dtype, torch.dtype):
+                    return torch_dtype
+
+        if self.key_namespace != "legacy":
+            return None
+
+        try:
+            return decode_legacy_key(encoded_key).dtype
+        except Exception:
+            logger.debug(
+                "Unable to recover dtype from legacy raw-block key %s",
+                encoded_key,
+                exc_info=True,
+            )
+            return None
+
+    def _validate_loaded_entries(self) -> None:
+        """Drop recovered entries whose slot headers do not match metadata."""
+        to_drop: list[str] = []
+        with self._lock:
+            items = list(self._index.items())
+
+        for encoded_key, entry in items:
+            slot_hdr = self._read_slot_header(int(entry.offset))
+            if slot_hdr is None:
+                to_drop.append(encoded_key)
+                continue
+            try:
+                expected_identity = slot_identity_from_encoded_key(
+                    encoded_key,
+                    self.key_namespace,
+                )
+            except Exception:
+                to_drop.append(encoded_key)
+                continue
+            slot_identity, payload_len = slot_hdr
+            if int(slot_identity) != int(expected_identity):
+                to_drop.append(encoded_key)
+                continue
+            if int(payload_len) != int(entry.size):
+                to_drop.append(encoded_key)
+
+        if not to_drop:
+            return
+
+        with self._lock:
+            for encoded_key in to_drop:
+                removed_entry = self._index.pop(encoded_key, None)
+                self._lock_refcnt.pop(encoded_key, None)
+                if removed_entry is not None:
+                    self._append_free_slot_locked(
+                        self._offset_to_slot(int(removed_entry.offset))
+                    )
+            self._meta_dirty_total += 1
+
+        logger.warning(
+            "RawBlockCore dropped %d stale metadata entries after "
+            "slot-header validation",
+            len(to_drop),
+        )
+
+    def _load_checkpoint_from_device(self) -> None:
+        """Load the newest valid checkpoint from the raw device if present."""
+        header, payload = self._select_latest_checkpoint()
+        if header is None:
+            logger.info("RawBlockCore: no valid on-device metadata checkpoint found")
+            return
+        if payload is None:
+            logger.warning("RawBlockCore: checkpoint header had no payload")
+            return
+        try:
+            data = json.loads(payload.decode("utf-8"))
+        except Exception:
+            logger.warning("RawBlockCore: failed to decode metadata payload")
+            return
+        if not self.apply_loaded_state(data):
+            logger.warning("RawBlockCore: metadata payload rejected by checks")
+            return
+        self._meta_seq = int(header["seq"])
+        logger.info(
+            "RawBlockCore loaded checkpoint (entries=%d next_slot=%d seq=%d device=%s)",
+            len(self._index),
+            self._next_slot,
+            self._meta_seq,
+            self.device_path,
+        )
diff --git a/lmcache/v1/storage_backend/raw_block/key_codec.py b/lmcache/v1/storage_backend/raw_block/key_codec.py
new file mode 100644
index 0000000..5b59601
--- /dev/null
+++ b/lmcache/v1/storage_backend/raw_block/key_codec.py
@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import Literal
+import hashlib
+import urllib.parse
+
+# First Party
+from lmcache.utils import CacheEngineKey, LayerCacheEngineKey, parse_cache_key
+from lmcache.v1.distributed.api import ObjectKey
+
+RawBlockKeyNamespace = Literal["legacy", "object"]
+
+_KEY_SEP = "@"
+_UINT64_MASK = (1 << 64) - 1
+
+
+@dataclass(frozen=True)
+class RawBlockKeySpec:
+    """Encoded raw-block key plus stable slot-header identity."""
+
+    encoded: str
+    slot_identity: int
+
+
+def object_key_to_string(key: ObjectKey) -> str:
+    """Serialize an ObjectKey using raw-block's reversible key shape.
+
+    Args:
+        key: Object key supplied by the MP storage layer.
+
+    Returns:
+        A stable string containing model name, KV rank, object group id,
+        chunk hash, and optional cache salt.
+
+    Raises:
+        AttributeError: If ``key`` does not expose the ObjectKey fields.
+    """
+    safe_model = urllib.parse.quote(key.model_name, safe="")
+    base = (
+        f"{safe_model}{_KEY_SEP}{key.kv_rank:#010x}"
+        f"{_KEY_SEP}{key.object_group_id:x}{_KEY_SEP}{key.chunk_hash.hex()}"
+    )
+    if key.cache_salt:
+        return f"{base}{_KEY_SEP}{key.cache_salt}"
+    return base
+
+
+def decode_object_key(encoded: str) -> ObjectKey:
+    """Deserialize an ObjectKey from raw-block's reversible encoding.
+
+    Args:
+        encoded: Encoded key string produced by ``object_key_to_string``.
+
+    Returns:
+        The reconstructed ``ObjectKey``.
+
+    Raises:
+        ValueError: If the encoded string has an unexpected shape or invalid
+            hexadecimal chunk hash.
+    """
+    parts = encoded.split(_KEY_SEP)
+    if len(parts) == 4:
+        safe_model, kv_rank_str, object_group_str, chunk_hash_hex = parts
+        cache_salt = ""
+    elif len(parts) == 5:
+        safe_model, kv_rank_str, object_group_str, chunk_hash_hex, cache_salt = parts
+    else:
+        raise ValueError(f"Invalid raw-block ObjectKey encoding: {encoded!r}")
+
+    return ObjectKey(
+        chunk_hash=bytes.fromhex(chunk_hash_hex),
+        model_name=urllib.parse.unquote(safe_model),
+        kv_rank=int(kv_rank_str, 16),
+        object_group_id=int(object_group_str, 16),
+        cache_salt=cache_salt,
+    )
+
+
+def encode_object_key(key: ObjectKey) -> RawBlockKeySpec:
+    """Encode an MP ObjectKey for raw-block storage.
+
+    Args:
+        key: Object key supplied by the MP storage layer.
+
+    Returns:
+        Encoded key and deterministic slot-header identity.
+    """
+    encoded = object_key_to_string(key)
+    return RawBlockKeySpec(
+        encoded=encoded,
+        slot_identity=_object_slot_identity(encoded),
+    )
+
+
+def decode_legacy_key(encoded: str) -> CacheEngineKey | LayerCacheEngineKey:
+    """Deserialize a legacy non-MP cache key string.
+
+    Args:
+        encoded: String produced by ``CacheEngineKey.to_string`` or
+            ``LayerCacheEngineKey.to_string``.
+
+    Returns:
+        Parsed legacy cache key.
+
+    Raises:
+        TypeError: If parsing returns an unsupported key type.
+    """
+    parsed = parse_cache_key(encoded)
+    if not isinstance(parsed, (CacheEngineKey, LayerCacheEngineKey)):
+        raise TypeError(
+            "parse_cache_key returned unsupported key type "
+            f"{type(parsed).__name__} for {encoded!r}"
+        )
+    return parsed
+
+
+def encode_legacy_key(key: CacheEngineKey | LayerCacheEngineKey) -> RawBlockKeySpec:
+    """Encode a legacy non-MP cache key for raw-block storage.
+
+    Args:
+        key: Legacy cache key from the non-MP storage plugin path.
+
+    Returns:
+        Encoded key and slot-header identity derived from the chunk hash.
+    """
+    return RawBlockKeySpec(
+        encoded=key.to_string(),
+        slot_identity=int(key.chunk_hash) & _UINT64_MASK,
+    )
+
+
+def slot_identity_from_encoded_key(
+    encoded: str,
+    namespace: RawBlockKeyNamespace,
+) -> int:
+    """Return the stable slot-header identity for an encoded key.
+
+    Args:
+        encoded: Encoded raw-block key string.
+        namespace: Key namespace used when the key was encoded.
+
+    Returns:
+        Unsigned 64-bit identity stored in the per-slot header.
+
+    Raises:
+        ValueError: If ``namespace`` is unsupported.
+        TypeError: If legacy key parsing returns an unsupported key type.
+    """
+    if namespace == "legacy":
+        key = decode_legacy_key(encoded)
+        return int(key.chunk_hash) & _UINT64_MASK
+    if namespace == "object":
+        return _object_slot_identity(encoded)
+    raise ValueError(f"Unsupported raw-block key namespace: {namespace!r}")
+
+
+def _object_slot_identity(encoded: str) -> int:
+    """Return the stable 64-bit slot identity for an encoded ObjectKey.
+
+    Args:
+        encoded: Raw-block ObjectKey string produced by ``object_key_to_string``.
+
+    Returns:
+        Unsigned 64-bit identity stored in the raw-block slot header.
+    """
+    digest = hashlib.blake2b(encoded.encode("utf-8"), digest_size=8).digest()
+    return int.from_bytes(digest, "little", signed=False)
diff --git a/lmcache/v1/storage_backend/remote_backend.py b/lmcache/v1/storage_backend/remote_backend.py
new file mode 100644
index 0000000..26b3054
--- /dev/null
+++ b/lmcache/v1/storage_backend/remote_backend.py
@@ -0,0 +1,625 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from concurrent.futures import Future, TimeoutError
+from typing import Any, Callable, List, Optional, Sequence, Set
+import asyncio
+import threading
+import time
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.logging import init_logger
+from lmcache.observability import LMCStatsMonitor, PrometheusLogger
+from lmcache.utils import CacheEngineKey, _lmcache_nvtx_annotate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.exceptions import IrrecoverableException
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+from lmcache.v1.storage_backend.connector import CreateConnector
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.naive_serde import CreateSerde
+
+logger = init_logger(__name__)
+
+
+class RemoteBackend(StorageBackendInterface):
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: Optional[LocalCPUBackend],
+        dst_device: str = torch_device_type,
+        plugin_name: Optional[str] = None,
+    ):
+        super().__init__(dst_device=dst_device)
+        self.put_tasks: Set[CacheEngineKey] = set()
+        self.lock = threading.Lock()
+
+        self.plugin_name = plugin_name
+
+        # Determine if we're using legacy remote_url or new plugin-based approach
+        if plugin_name is not None:
+            # Using plugin-based approach
+            self.remote_url = f"plugin://{plugin_name}"
+            logger.info("Creating RemoteBackend for plugin: %s", plugin_name)
+        else:
+            # Legacy remote_url approach
+            if config.remote_url is None:
+                raise ValueError(
+                    "remote_url must be provided when not using plugin_name"
+                )
+            self.remote_url = config.remote_url
+
+        self.local_cpu_backend = local_cpu_backend
+
+        self.loop = loop
+        self.config = config
+        self.metadata = metadata
+
+        # Re-establish connection only when the connection
+        # has been lost for 10 secs
+        self.connection: Optional[RemoteConnector] = None
+        self.min_reconnect_interval = 10
+        self.failure_time = -1000000.0
+        self.init_connection()
+
+        assert config.remote_serde is not None
+        self.serializer, self.deserializer = CreateSerde(
+            config.remote_serde, metadata, config
+        )
+
+        # Precompute MLA mode status
+        self._mla_worker_id_as0_mode = (
+            config.get_extra_config_value(
+                "remote_enable_mla_worker_id_as0", metadata.use_mla
+            )
+            and metadata.use_mla
+            and metadata.world_size > 1
+            and metadata.worker_id != 0
+        )
+        logger.info("metadata=%s", metadata)
+        logger.info(
+            "Connected to remote storage at %s, remote_mla_worker_id_as_0 mode: %s",
+            config.remote_url,
+            self._mla_worker_id_as0_mode,
+        )
+
+        # TODO(Jiayi): If we want to have cache admission policies,
+        # we must make decision (whether to send or not) at the local side
+
+        self.stats_monitor = LMCStatsMonitor.GetOrCreate()
+
+        # NOTE: Health monitoring is now handled at the LMCacheEngine level
+        # through HealthMonitor. RemoteBackend no longer manages its own
+        # health monitoring. The HealthMonitor in LMCacheEngine will
+        # register RemoteBackendHealthCheck for each RemoteBackend.
+
+        self._get_blocking_failed_count = 0
+        self._put_failed_count = 0
+
+        self._setup_metrics()
+
+    def _setup_metrics(self) -> None:
+        prometheus_logger = PrometheusLogger.GetOrCreate(
+            self.metadata,
+            config=self.config,
+        )
+        prometheus_logger.remote_put_task_num.set_function(lambda: len(self.put_tasks))
+        prometheus_logger.get_blocking_failed_count.set_function(
+            lambda: self._get_blocking_failed_count
+        )
+        prometheus_logger.put_failed_count.set_function(lambda: self._put_failed_count)
+
+    def __str__(self):
+        return self.__class__.__name__
+
+    def init_connection(self):
+        # Initialize connection
+        if self.connection is not None:
+            return
+        if (time.time() - self.failure_time) < self.min_reconnect_interval:
+            logger.warning(
+                "Connection will not be re-established yet "
+                "since it has not been long enough since "
+                "the last failure"
+            )
+            return
+        try:
+            # Determine the URL to use for connection
+            if self.plugin_name is not None:
+                # Using plugin-based approach
+                # Create a virtual URL that the adapter can recognize
+                url = f"plugin://{self.plugin_name}"
+                logger.info("Creating connector for plugin: %s", self.plugin_name)
+            else:
+                # Legacy remote_url approach
+                if self.config.remote_url is None:
+                    raise ValueError(
+                        "remote_url must be provided when not using plugin_name"
+                    )
+                url = self.config.remote_url
+
+            self.connection = CreateConnector(
+                url,
+                self.loop,
+                self.local_cpu_backend,
+                self.config,
+                self.metadata,
+                plugin_name=self.plugin_name,
+            )
+            logger.info("Connection initialized/re-established at %s", url)
+        except IrrecoverableException:
+            logger.error("Irrecoverable error during connection initialization")
+            raise
+        except Exception as e:
+            with self.lock:
+                self.failure_time = time.time()
+            logger.warning("Failed to initialize/re-establish remote connection: %s", e)
+            self.connection = None
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        if self.connection is None:
+            logger.warning("Connection is None in contains, returning False")
+            return False
+
+        # For MLA worker id as 0 mode, use worker_id 0
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+
+        try:
+            if self.config.extra_config is not None and self.config.extra_config.get(
+                "use_exists_sync", False
+            ):
+                return self.connection.exists_sync(key)
+            else:
+                future = asyncio.run_coroutine_threadsafe(
+                    self.connection.exists(key), self.loop
+                )
+                res = future.result()
+                return res
+        except Exception as e:
+            logger.warning("Remote connection failed in contains: %s", e)
+            logger.warning("Returning False")
+            return False
+
+    def batched_contains(
+        self,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        if self.connection is None:
+            logger.warning("Connection is None in batched_contains, returning 0")
+            return 0
+
+        if not self.connection.support_batched_contains():
+            return super().batched_contains(keys, pin)
+
+        if self._mla_worker_id_as0_mode:
+            keys = [key.with_new_worker_id(0) for key in keys]
+
+        try:
+            return self.connection.batched_contains(keys)
+        except Exception as e:
+            logger.warning("Remote connection failed in batched_contains: %s", e)
+            return 0
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        with self.lock:
+            return key in self.put_tasks
+
+    def put_callback(self, future: Future, key: CacheEngineKey):
+        with self.lock:
+            self.put_tasks.discard(key)
+        try:
+            future.result()
+        except Exception as e:
+            self._put_failed_count += 1
+            logger.error("Put task failed for key %s: %s", key, e)
+
+    def submit_put_task(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> Future:
+        """
+        Submit a put task to store KV cache to remote storage asynchronously.
+
+        :param on_complete_callback: Optional callback invoked after the remote
+            write completes. Callback exceptions are caught and logged.
+        """
+
+        def create_immediate_empty_future() -> Future:
+            f: Future = Future()
+            f.set_result(None)
+            return f
+
+        if self.connection is None:
+            logger.warning("Connection is None in submit_put_task, returning None")
+            return create_immediate_empty_future()
+
+        # If MLA worker id as 0 mode is enabled, skip put tasks
+        if self._mla_worker_id_as0_mode:
+            return create_immediate_empty_future()
+
+        if self.exists_in_put_tasks(key):
+            return create_immediate_empty_future()
+
+        memory_obj.ref_count_up()
+
+        with self.lock:
+            self.put_tasks.add(key)
+
+        compressed_memory_obj = self.serializer.serialize(memory_obj)
+        memory_obj.ref_count_down()
+
+        def put_done_callback(f: Future) -> None:
+            self.put_callback(f, key)
+            if on_complete_callback is not None:
+                try:
+                    on_complete_callback(key)
+                except Exception as e:
+                    logger.warning("on_complete_callback failed for key %s: %s", key, e)
+
+        # NOTE: No need to do error handling here
+        # since the `future` is never waited
+        future = asyncio.run_coroutine_threadsafe(
+            self.connection.put(key, compressed_memory_obj), self.loop
+        )
+        future.add_done_callback(put_done_callback)
+        return future
+
+    def batched_put_callback(self, future: Future, keys: List[CacheEngineKey]):
+        """
+        Callback function for batched put tasks.
+        """
+        with self.lock:
+            self.put_tasks.difference_update(keys)
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """
+        Submit batched put tasks to store KV caches to remote storage.
+
+        :param on_complete_callback: Optional callback invoked once per key
+            after that key's write completes (not once per batch).
+        """
+        if self.connection is None:
+            logger.warning(
+                "Connection is None in batched_submit_put_task, returning None"
+            )
+            return
+        if self.connection.support_batched_put():
+            if self._mla_worker_id_as0_mode:
+                return
+
+            # First, increment reference counts for all objects
+            for memory_obj in memory_objs:
+                memory_obj.ref_count_up()
+
+            compressed_memory_objs = []
+            try:
+                for memory_obj in memory_objs:
+                    compressed_memory_objs.append(self.serializer.serialize(memory_obj))
+            finally:
+                # Always decrement reference counts for all objects,
+                # regardless of whether serialization succeeded or failed
+                for memory_obj in memory_objs:
+                    memory_obj.ref_count_down()
+
+            def batched_done_callback(f: Future) -> None:
+                self.batched_put_callback(f, list(keys))
+                # Invoke per-key callback for each key in the batch
+                if on_complete_callback is not None:
+                    for key in keys:
+                        try:
+                            on_complete_callback(key)
+                        except Exception as e:
+                            logger.warning(
+                                "on_complete_callback failed for key %s: %s", key, e
+                            )
+
+            future = asyncio.run_coroutine_threadsafe(
+                self.connection.batched_put(keys, compressed_memory_objs),  # type: ignore
+                self.loop,
+            )
+            future.add_done_callback(batched_done_callback)
+        else:
+            for key, memory_obj in zip(keys, memory_objs, strict=False):
+                self.submit_put_task(
+                    key, memory_obj, on_complete_callback=on_complete_callback
+                )
+
+    @_lmcache_nvtx_annotate
+    def get_blocking(
+        self,
+        key: CacheEngineKey,
+    ) -> Optional[MemoryObj]:
+        """
+        Blocking get function.
+        """
+        # Check if local_cpu_backend is available (required for memory allocation)
+        if self.local_cpu_backend is None:
+            logger.warning(
+                "local_cpu_backend is None in get_blocking "
+                "(likely scheduler role), returning None"
+            )
+            return None
+
+        if self.connection is None:
+            logger.warning("Connection is None in get_blocking, returning None")
+            return None
+        # For MLA worker id as 0 mode, use worker_id 0
+        if self._mla_worker_id_as0_mode:
+            key = key.with_new_worker_id(0)
+        t1 = time.perf_counter()
+        future = asyncio.run_coroutine_threadsafe(self.connection.get(key), self.loop)
+
+        try:
+            memory_obj = future.result(self.config.blocking_timeout_secs)
+        except Exception as e:
+            if isinstance(e, TimeoutError):
+                logger.warning("get blocking timeout, trigger cancel the future task")
+                future.cancel()
+            logger.warning("Error occurred in get_blocking: %s, return None", e)
+            memory_obj = None
+
+        t2 = time.perf_counter()
+        self.stats_monitor.update_interval_remote_time_to_get_sync((t2 - t1) * 1000)
+        if memory_obj is None:
+            self._get_blocking_failed_count += 1
+            return None
+        decompressed_memory_obj = self.deserializer.deserialize(memory_obj)
+        t3 = time.perf_counter()
+        logger.debug(
+            "Get takes %.6f msec, deserialization takes %.6f msec",
+            (t2 - t1) * 1000,
+            (t3 - t2) * 1000,
+        )
+        return decompressed_memory_obj
+
+    @property
+    def get_blocking_failed_count(self):
+        return self._get_blocking_failed_count
+
+    @property
+    def put_failed_count(self):
+        return self._put_failed_count
+
+    def batched_get_blocking(
+        self,
+        keys: List[CacheEngineKey],
+    ) -> List[Optional[MemoryObj]]:
+        # Check if local_cpu_backend is available (required for memory allocation)
+        if self.local_cpu_backend is None:
+            logger.warning(
+                "local_cpu_backend is None in batched_get_blocking "
+                "(likely scheduler role), returning None list"
+            )
+            return [None] * len(keys)
+
+        if self.connection is None:
+            logger.warning("Connection is None in batched_get_blocking, returning None")
+            return [None] * len(keys)
+
+        # For MLA worker id as 0 mode, use worker_id 0
+        if self._mla_worker_id_as0_mode:
+            keys = [key.with_new_worker_id(0) for key in keys]
+
+        t1 = time.perf_counter()
+        # batched get
+        if self.connection.support_batched_get():
+            future = asyncio.run_coroutine_threadsafe(
+                self.connection.batched_get(keys), self.loop
+            )
+            try:
+                memory_objs = future.result(self.config.blocking_timeout_secs)
+            except Exception as e:
+                if isinstance(e, TimeoutError):
+                    logger.warning(
+                        "batched get blocking timeout, trigger cancel the future task"
+                    )
+                    future.cancel()
+                else:
+                    logger.warning(
+                        "Error occurred in batched_get_blocking: %s, "
+                        "returning None list",
+                        e,
+                    )
+                memory_objs = [None] * len(keys)
+        else:
+            remote_backend_individual_get_stats: dict[
+                CacheEngineKey, dict[str, float]
+            ] = {}
+            retrieve_stats = self.stats_monitor.get_current_retrieve_stats()
+            if retrieve_stats is not None:
+                retrieve_stats.detailed_metrics[
+                    "remote_backend_individual_get_stats"
+                ] = remote_backend_individual_get_stats
+
+            futures = [
+                asyncio.run_coroutine_threadsafe(self.connection.get(key), self.loop)
+                for key in keys
+            ]
+            memory_objs = []
+            failed = False
+            for fut in futures:
+                if not failed:
+                    try:
+                        memory_obj = fut.result(self.config.blocking_timeout_secs)
+                    except Exception as e:
+                        failed = True
+                        if isinstance(e, TimeoutError):
+                            logger.warning(
+                                "get blocking timeout, trigger cancel the future task"
+                            )
+                            fut.cancel()
+                        else:
+                            logger.warning(
+                                "Error occurred in get_blocking: %s, returning None", e
+                            )
+                        memory_obj = None
+                    memory_objs.append(memory_obj)
+                else:
+                    memory_objs.append(None)
+                    fut.cancel()
+
+        t2 = time.perf_counter()
+        duration = t2 - t1
+        self.stats_monitor.update_interval_remote_time_to_get_sync(duration * 1000)
+
+        retrieve_stats = self.stats_monitor.get_current_retrieve_stats()
+        if retrieve_stats is not None:
+            retrieve_stats.detailed_metrics[
+                "remote_backend_batched_get_blocking_time"
+            ] = (
+                retrieve_stats.detailed_metrics.get(
+                    "remote_backend_batched_get_blocking_time", 0.0
+                )
+                + duration
+            )
+        decompressed_memory_objs: list[Optional[MemoryObj]] = []
+        error_happened = False
+        for memory_obj in memory_objs:
+            if memory_obj is None:
+                error_happened = True
+                decompressed_memory_objs.append(None)
+            else:
+                decompressed_memory_objs.append(
+                    self.deserializer.deserialize(memory_obj)
+                )
+        if error_happened:
+            self._get_blocking_failed_count += 1
+
+        assert len(decompressed_memory_objs) == len(keys), (
+            f"keys length: {len(keys)}, "
+            f"decompressed memory objs length: {len(decompressed_memory_objs)}"
+        )
+        return decompressed_memory_objs
+
+    async def support_batched_async_contains(self) -> bool:
+        return (
+            self.connection is not None
+            and self.connection.support_batched_async_contains()
+        )
+
+    async def batched_async_contains(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        if self.connection is None:
+            logger.warning("Connection is None in batched_async_contains, returning 0")
+            return 0
+        if self._mla_worker_id_as0_mode:
+            keys = [key.with_new_worker_id(0) for key in keys]
+
+        try:
+            assert self.connection.support_batched_async_contains(), (
+                f"Connector {self.connection} does not support batched async contains"
+            )
+            # warning, this timeout will not actually stop the
+            # scheduler from waiting for the result
+            return await asyncio.wait_for(
+                self.connection.batched_async_contains(lookup_id, keys, pin),
+                self.config.blocking_timeout_secs,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("batched_async_contains timed out")
+            return 0
+        except Exception as e:
+            logger.warning("Error occurred in batched_async_contains: %s", e)
+            return 0
+
+    async def support_batched_get_non_blocking(self) -> bool:
+        return (
+            self.connection is not None
+            and self.connection.support_batched_get_non_blocking()
+        )
+
+    async def batched_get_non_blocking(
+        self,
+        lookup_id: str,
+        keys: List[CacheEngineKey],
+        transfer_spec: Any = None,
+    ) -> List[MemoryObj]:
+        # Check if local_cpu_backend is available (required for memory allocation)
+        if self.local_cpu_backend is None:
+            logger.warning(
+                "local_cpu_backend is None in batched_get_non_blocking "
+                "(likely scheduler role), returning empty list"
+            )
+            return []
+
+        if self.connection is None:
+            logger.warning(
+                "Connection is None in batched_get_non_blocking, returning empty list"
+            )
+            return []
+        try:
+            # warning, this timeout will not actually stop the
+            # scheduler from waiting for the result
+            return await asyncio.wait_for(
+                self.connection.batched_get_non_blocking(lookup_id, keys),
+                self.config.blocking_timeout_secs,
+            )
+        except asyncio.TimeoutError:
+            logger.warning("batched_get_non_blocking timed out")
+            return []
+        except Exception as e:
+            logger.warning("Error occurred in batched_get_non_blocking: %s", e)
+            return []
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        logger.debug(
+            "Remote backend does not support pin. "
+            "This method is a no-op and will return True."
+        )
+        return True
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        logger.debug(
+            "Remote backend does not support unpin. "
+            "This method is a no-op and will return True."
+        )
+        return True
+
+    def remove(self, key, force=True):
+        if self.connection is None:
+            logger.warning("Connection is None in remove, returning False")
+            return False
+
+        try:
+            return self.connection.remove_sync(key)
+        except Exception as e:
+            logger.exception(
+                "Failed to remove key %s from remote backend, error: %s", key, e
+            )
+            return False
+
+    def get_allocator_backend(self):
+        assert self.local_cpu_backend is not None, (
+            "local_cpu_backend is required for get_allocator_backend, "
+            "should not be called in scheduler role"
+        )
+        return self.local_cpu_backend
+
+    def close(self):
+        try:
+            assert self.connection is not None
+            future = asyncio.run_coroutine_threadsafe(
+                self.connection.close(), self.loop
+            )
+            future.result()
+            logger.info("Remote backend closed.")
+        except Exception as e:
+            logger.warning("Error occurred when closing remote connection: %s", e)
diff --git a/lmcache/v1/storage_backend/resp_client.py b/lmcache/v1/storage_backend/resp_client.py
new file mode 100644
index 0000000..7faf9db
--- /dev/null
+++ b/lmcache/v1/storage_backend/resp_client.py
@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Single source of truth for the RESPClient class.
+
+This module provides a sync and asyncio wrapper around the LMCacheRedisClient,
+which is a C++ extension built with PyTorch. The pybinding interface allows
+working with both sync and async code seamlessly.
+
+Used by:
+- lmcache/v1/storage_backend/connector/redis_connector.py (RESPConnector)
+- examples/kv_cache_reuse/remote_backends/resp/example_resp_client.py (benchmarks)
+"""
+
+# Standard
+from typing import Dict, Optional, Tuple, Union
+import asyncio
+import concurrent.futures
+
+try:
+    # First Party
+    from lmcache.lmcache_redis import LMCacheRedisClient
+
+    REDIS_AVAILABLE = True
+except ImportError:
+    # C++ extension not built (e.g., in non-CUDA CI environments)
+    # This is fine - RESP tests will be skipped
+    REDIS_AVAILABLE = False
+    LMCacheRedisClient = None  # type: ignore
+
+
+class RESPClient:
+    """
+    Sync and asyncio wrapper around the native LMCacheRedisClient.
+
+    This class bridges the C++ RESP client with Python's asyncio event loop,
+    allowing for efficient async I/O operations with Redis using the RESP protocol.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        num_workers: int,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+        username: str = "",
+        password: str = "",
+    ):
+        if not REDIS_AVAILABLE:
+            raise RuntimeError(
+                "RESPClient requires the C++ Redis extension. "
+                "Build with: pip install -e ."
+            )
+        self.loop = loop or asyncio.get_running_loop()
+        self._client = LMCacheRedisClient(host, port, num_workers, username, password)
+        self._fd = int(self._client.event_fd())
+        self._closed = False
+
+        # future_id -> (Future, op_name)
+        # we support both types of futures since we only their basic interface
+        self._pending: Dict[
+            int, Tuple[Union[asyncio.Future, concurrent.futures.Future], str]
+        ] = {}
+
+        self.loop.add_reader(self._fd, self._on_ready)
+
+    def _on_ready(self) -> None:
+        if self._closed:
+            return
+
+        try:
+            # drain until empty; completions can race in while processing
+            while True:
+                items = self._client.drain_completions()
+                if not items:
+                    return
+
+                for future_id, ok, error, result_bools in items:
+                    fid = int(future_id)
+                    entry = self._pending.pop(fid, None)
+                    if entry is None:
+                        continue
+
+                    fut, op = entry
+                    # fut can be asyncio.Future OR concurrent.future.Future
+                    # the .done() and .set_result() and .set_exception()
+                    # interface is the same
+                    if fut.done():
+                        continue
+
+                    if ok:
+                        if op == "exists":
+                            # result_bools is a list with 1 element for single
+                            # exists
+                            if result_bools is not None and len(result_bools) > 0:
+                                fut.set_result(bool(result_bools[0]))
+                            else:
+                                # should not happen but handle gracefully
+                                fut.set_result(False)
+                        elif op == "batch_exists":
+                            # result_bools is a list of booleans (or None if empty)
+                            if result_bools is not None:
+                                fut.set_result(list(result_bools))
+                            else:
+                                fut.set_result([])
+                        else:
+                            fut.set_result(None)
+                    else:
+                        fut.set_exception(RuntimeError(str(error)))
+
+        except Exception as e:
+            # Native layer is likely broken; fail everything and tear down.
+            self._fail_all(RuntimeError(f"native drain_completions failed: {e}"))
+            self._shutdown_native(best_effort=True)
+
+    def _fail_all(self, exc: Exception) -> None:
+        """Fail all pending futures with the given exception."""
+        for fid, (fut, _) in list(self._pending.items()):
+            if not fut.done():
+                fut.set_exception(exc)
+        self._pending.clear()
+
+    def _shutdown_native(self, best_effort: bool = False) -> None:
+        """Shutdown the native client and cleanup resources."""
+        try:
+            self._closed = True
+            self.loop.remove_reader(self._fd)
+        except Exception:
+            if not best_effort:
+                raise
+
+    def _register_future_async(self, op: str, future_id: int) -> asyncio.Future:
+        fut = self.loop.create_future()
+        self._pending[int(future_id)] = (fut, op)
+        return fut
+
+    def _register_future_sync(
+        self, op: str, future_id: int
+    ) -> concurrent.futures.Future:
+        fut: concurrent.futures.Future = concurrent.futures.Future()
+        self._pending[int(future_id)] = (fut, op)
+        return fut
+
+    async def get(self, key: str, buf: memoryview) -> None:
+        future_id = int(self._client.submit_get(key, buf))
+        fut = self._register_future_async("get", future_id)
+        return await fut
+
+    def get_sync(self, key: str, buf: memoryview) -> None:
+        future_id = int(self._client.submit_get(key, buf))
+        fut = self._register_future_sync("get", future_id)
+        return fut.result()
+
+    async def set(self, key: str, buf: memoryview) -> None:
+        future_id = int(self._client.submit_set(key, buf))
+        fut = self._register_future_async("set", future_id)
+        return await fut
+
+    def set_sync(self, key: str, buf: memoryview) -> None:
+        future_id = int(self._client.submit_set(key, buf))
+        fut = self._register_future_sync("set", future_id)
+        return fut.result()
+
+    async def exists(self, key: str) -> bool:
+        future_id = int(self._client.submit_exists(key))
+        fut = self._register_future_async("exists", future_id)
+        return await fut
+
+    def exists_sync(self, key: str) -> bool:
+        future_id = int(self._client.submit_exists(key))
+        fut = self._register_future_sync("exists", future_id)
+        return fut.result()
+
+    async def batch_get(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_get(keys, bufs))
+        fut = self._register_future_async("batch_get", future_id)
+        return await fut
+
+    def batch_get_sync(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_get(keys, bufs))
+        fut = self._register_future_sync("batch_get", future_id)
+        return fut.result()
+
+    async def batch_set(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_set(keys, bufs))
+        fut = self._register_future_async("batch_set", future_id)
+        return await fut
+
+    def batch_set_sync(self, keys: list[str], bufs: list[memoryview]) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        future_id = int(self._client.submit_batch_set(keys, bufs))
+        fut = self._register_future_sync("batch_set", future_id)
+        return fut.result()
+
+    async def batch_exists(self, keys: list[str]) -> list[bool]:
+        """Check existence of multiple keys in a single batch operation."""
+        future_id = int(self._client.submit_batch_exists(keys))
+        fut = self._register_future_async("batch_exists", future_id)
+        return await fut
+
+    def batch_exists_sync(self, keys: list[str]) -> list[bool]:
+        """Check existence of multiple keys in a single
+        batch operation (sync version)."""
+        future_id = int(self._client.submit_batch_exists(keys))
+        fut = self._register_future_sync("batch_exists", future_id)
+        return fut.result()
+
+    async def batched_exists(self, keys: list[str]) -> list[bool]:
+        """Alias for batch_exists."""
+        return await self.batch_exists(keys)
+
+    def batched_exists_sync(self, keys: list[str]) -> list[bool]:
+        """Alias for batch_exists_sync."""
+        return self.batch_exists_sync(keys)
+
+    def close(self) -> None:
+        """Close the client and cleanup resources."""
+        if not self._closed:
+            self._shutdown_native(best_effort=True)
+            self._fail_all(RuntimeError("Client closed"))
+            self._client.close()
diff --git a/lmcache/v1/storage_backend/storage_backend_listener.py b/lmcache/v1/storage_backend/storage_backend_listener.py
new file mode 100644
index 0000000..bff4947
--- /dev/null
+++ b/lmcache/v1/storage_backend/storage_backend_listener.py
@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import TYPE_CHECKING, List
+import abc
+
+# First Party
+from lmcache.utils import CacheEngineKey
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.storage_backend.abstract_backend import StorageBackendInterface
+
+
+class StorageBackendListener(metaclass=abc.ABCMeta):
+    """Listener for events happen inside storage backend."""
+
+    @abc.abstractmethod
+    def on_evict(self, backend: "StorageBackendInterface", keys: List[CacheEngineKey]):
+        pass
diff --git a/lmcache/v1/storage_backend/storage_manager.py b/lmcache/v1/storage_backend/storage_manager.py
new file mode 100644
index 0000000..96633b0
--- /dev/null
+++ b/lmcache/v1/storage_backend/storage_manager.py
@@ -0,0 +1,1425 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from concurrent.futures import Future
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Coroutine,
+    Dict,
+    Generator,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+    cast,
+)
+import asyncio
+import functools
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.logging import init_logger
+from lmcache.observability import PrometheusLogger
+from lmcache.utils import (
+    CacheEngineKey,
+    _lmcache_nvtx_annotate,
+    start_loop_in_thread_with_exceptions,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventManager, EventStatus, EventType
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend import CreateStorageBackends, is_cuda_worker
+from lmcache.v1.storage_backend.abstract_backend import (
+    AllocatorBackendInterface,
+    StorageBackendInterface,
+)
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.cache_controller.worker import LMCacheWorker
+    from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+        LMCacheAsyncLookupServer,
+    )
+
+logger = init_logger(__name__)
+
+
+# Helper function to get the class name of the backend
+def get_backend_cname(backend: StorageBackendInterface) -> str:
+    return backend.__class__.__name__
+
+
+# Helper function to allocate and copy memory objects between D and H
+def allocate_and_copy_objects(
+    allocator_backend: AllocatorBackendInterface,
+    keys: Sequence[CacheEngineKey],
+    src_memory_objs: list[MemoryObj],
+    stream: Any,
+) -> tuple[Sequence[CacheEngineKey], list[MemoryObj]]:
+    """
+    Allocate the memory objects and copy the data from src_memory_objs to
+    the newly allocated memory objects
+
+    Args:
+        allocator_backend: the allocator backend to allocate the new memory
+          objects
+        keys: the cache engine keys corresponding to the memory objects
+        src_memory_objs: the memory objects to copy from
+        stream: the device-specific GPU stream to run the copy in
+            (e.g., torch_dev.Stream on CUDA or XPU)
+
+    Returns:
+        - list of cache engine keys that corresponds to the memory objects
+          that has been successfully allocated
+        - list of the memory objects that has been successfully allocated
+    """
+    allocated_objects = []
+    for key, src_memory_obj in zip(keys, src_memory_objs, strict=False):
+        if allocator_backend.contains(key):
+            continue
+        memory_obj = allocator_backend.allocate(
+            src_memory_obj.get_shape(),
+            src_memory_obj.get_dtype(),
+            fmt=src_memory_obj.meta.fmt,
+            eviction=True,
+            busy_loop=False,
+        )
+
+        if memory_obj is None:
+            break
+
+        if memory_obj.tensor is None:
+            # This should not happen with current implementation,
+            # but handle it defensively to avoid memory leak
+            logger.warning(
+                "Allocated MemoryObj has None tensor, this is unexpected. "
+                "Releasing the memory object."
+            )
+            memory_obj.ref_count_down()
+            break
+
+        with torch_dev.stream(stream):
+            memory_obj.tensor.copy_(src_memory_obj.tensor, non_blocking=True)
+        allocated_objects.append(memory_obj)
+
+    if stream is not None:
+        stream.synchronize()
+    return keys[: len(allocated_objects)], allocated_objects
+
+
+class WeightedSemaphore:
+    def __init__(self, chunk_budget: int):
+        # it is physically impossible to have more fragmentation than 50%
+        # when all of the chunks are of the same size (save_unfull_chunk=False)
+        # so we can safely allocate half of the chunk budget for concurrent requests
+        self._concurrent_budget_cap = chunk_budget // 2
+        self._chunk_budget_cap = chunk_budget
+        self._current_chunks = self._concurrent_budget_cap
+        self._cond = asyncio.Condition()
+
+    async def acquire(self, n: int = 1) -> None:
+        if n > self._chunk_budget_cap:
+            raise ValueError(
+                f"Trying to acquire {n} chunks, "
+                f"Cannot acquire more than {self._chunk_budget_cap} chunks"
+                "Please set the max local cpu size to a larger value"
+            )
+
+        async with self._cond:
+            logger.debug("WeightedSemaphore: Attempting to acquire %d chunks", n)
+            if n <= self._concurrent_budget_cap:
+                await self._cond.wait_for(lambda: self._current_chunks >= n)
+                self._current_chunks -= n
+            else:
+                # Oversized case: require exclusive access
+                await self._cond.wait_for(
+                    lambda: self._current_chunks == self._concurrent_budget_cap
+                )
+                # Reserve everything
+                self._current_chunks = 0
+            logger.debug(
+                "WeightedSemaphore: Acquired %d chunks, remaining chunks: %d",
+                n,
+                self._current_chunks,
+            )
+
+    async def release(self, n: int = 1) -> None:
+        async with self._cond:
+            if n <= self._concurrent_budget_cap:
+                self._current_chunks += n
+            else:
+                self._current_chunks = self._concurrent_budget_cap
+            self._cond.notify_all()
+
+
+class AsyncMultiSerializer:
+    """
+    Prevent race conditions where multiple batched_get's cause the local CPU
+    backend to allocate memory objects in parallel and get deadlocked.
+    Make the assumption that the save_unfull_chunk is False so that we
+    can assume that we can always use 50% of the given memory
+    """
+
+    def __init__(
+        self,
+        allocator_backend: AllocatorBackendInterface,
+        loop: asyncio.AbstractEventLoop,
+    ):
+        self.chunk_budget = allocator_backend.calculate_chunk_budget()
+        self._sem = WeightedSemaphore(self.chunk_budget)
+        self.loop = loop
+
+    async def run(
+        self,
+        coro_fn: Coroutine[Any, Any, Any],
+        num_chunks: int,
+    ) -> Any:
+        await self._sem.acquire(num_chunks)
+        try:
+            return await coro_fn
+        finally:
+            await self._sem.release(num_chunks)
+
+
+class AsyncSingleSerializer:
+    """
+    Prevent race conditions in a naive way by forcing each request that
+    is passed through to be serialized
+    """
+
+    def __init__(self, loop: asyncio.AbstractEventLoop):
+        self.loop = loop
+        # lazy init in run
+        self.lock: Optional[asyncio.Lock] = None
+
+    async def run(self, coro_fn: Coroutine[Any, Any, Any], *args, **kwargs) -> Any:
+        # we need to lazily initialize the lock to
+        # place it on the calling event loop
+        if self.lock is None:
+            self.lock = asyncio.Lock()
+        async with self.lock:  # type: ignore
+            return await coro_fn
+
+
+AsyncSerializer = Union[AsyncSingleSerializer, AsyncMultiSerializer]
+
+
+# TODO: extend this class to implement caching policies and eviction policies
+class StorageManager:
+    """
+    The StorageManager is responsible for managing the storage backends.
+    """
+
+    def __init__(
+        self,
+        config: LMCacheEngineConfig,
+        metadata: LMCacheMetadata,
+        event_manager: EventManager,
+        lmcache_worker: Optional["LMCacheWorker"] = None,
+        async_lookup_server: Optional["LMCacheAsyncLookupServer"] = None,
+    ):
+        self.config = config
+        self.metadata = metadata
+        self.loop = asyncio.new_event_loop()
+
+        self.thread = threading.Thread(
+            target=start_loop_in_thread_with_exceptions,
+            args=(self.loop,),
+            name="storage-manager-event-loop",
+        )
+        self.thread.start()
+
+        self.storage_backends: OrderedDict[str, StorageBackendInterface] = OrderedDict()
+        self.manager_lock = threading.Lock()
+        self.lmcache_worker = lmcache_worker
+
+        # Use the unified create path so that init and
+        # dynamic creation share the same logic.
+        self.create_backends()
+
+        # the backend used for actual storage
+        self.non_allocator_backends = self.get_non_allocator_backends()
+
+        self.enable_pd = config.enable_pd
+
+        self.allocator_backend = None
+        if metadata.role != "scheduler":
+            self.allocator_backend = self._get_allocator_backend(config)
+
+        self.local_cpu_backend = self.storage_backends.get("LocalCPUBackend", None)
+
+        self.instance_id = config.lmcache_instance_id
+        self.worker_id = metadata.worker_id
+
+        self.event_manager = event_manager
+
+        self.async_lookup_server: Optional["LMCacheAsyncLookupServer"] = (
+            async_lookup_server
+        )
+        self.async_serializer: Optional[AsyncSerializer] = None
+
+        # The GPU stream for internal copies during put
+        if is_cuda_worker(metadata):
+            self.internal_copy_stream = torch_dev.Stream()
+        else:
+            self.internal_copy_stream = None
+
+        # freeze mode: only use local_cpu backend for retrieval
+        self._freeze = False
+        self._freeze_lock = threading.RLock()
+
+        # Backend bypass mode: skip specific backends during health check failures
+        self._bypassed_backends: set[str] = set()
+        self._bypass_lock = threading.RLock()
+
+        if not self.enable_pd and self.config.enable_async_loading:
+            assert self.allocator_backend is not None
+            self.async_serializer = AsyncSingleSerializer(self.loop)
+
+        self._setup_metrics()
+
+    def _setup_metrics(self) -> None:
+        prometheus_logger = PrometheusLogger.GetOrCreate(
+            self.metadata,
+            config=self.config,
+        )
+
+        metric_map = {
+            "storage_events_ongoing_count": EventStatus.ONGOING,
+            "storage_events_done_count": EventStatus.DONE,
+            "storage_events_not_found_count": EventStatus.NOT_FOUND,
+        }
+
+        for metric_name, status in metric_map.items():
+            metric = getattr(prometheus_logger, metric_name)
+            metric.set_function(
+                lambda s=status: self.event_manager.get_events_count_by_status(
+                    EventType.LOADING, s
+                )
+            )
+
+    def _get_allocator_backend(
+        self, config: LMCacheEngineConfig
+    ) -> AllocatorBackendInterface:
+        if self.enable_pd:
+            allocator_backend = self.storage_backends["PDBackend"]
+        elif "MaruBackend" in self.storage_backends:
+            if "LocalCPUBackend" in self.storage_backends:
+                allocator_backend = self.storage_backends["LocalCPUBackend"]
+            else:
+                allocator_backend = self.storage_backends["MaruBackend"]
+        else:
+            allocator_backend = self.storage_backends["LocalCPUBackend"]
+        assert isinstance(allocator_backend, AllocatorBackendInterface)
+        return allocator_backend
+
+    @_lmcache_nvtx_annotate
+    def allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction=True,
+        busy_loop=True,
+    ) -> Optional[MemoryObj]:
+        """
+        Allocate memory object with memory allocator.
+        Use LRU evictor if eviction is enabled.
+        """
+        # TODO (Jiayi): We might need to pre-allocate and management
+        # disk in a similar way as CPU.
+        assert self.allocator_backend is not None
+        return self.allocator_backend.allocate(
+            shapes, dtypes, fmt, eviction=eviction, busy_loop=busy_loop
+        )
+
+    @_lmcache_nvtx_annotate
+    def batched_allocate(
+        self,
+        shapes: Union[torch.Size, list[torch.Size]],
+        dtypes: Union[torch.dtype, list[torch.dtype]],
+        batch_size: int,
+        fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+        eviction=True,
+        busy_loop=True,
+    ) -> Optional[list[MemoryObj]]:
+        """
+        Batched allocate memory object with memory allocator.
+        Use LRU evictor if eviction is enabled.
+        """
+        # TODO (Jiayi): We might need to pre-allocate and management
+        # disk in a similar way as CPU.
+        if self.allocator_backend is None:
+            raise RuntimeError("Allocator backend not available for scheduler role")
+        return self.allocator_backend.batched_allocate(
+            shapes, dtypes, batch_size, fmt, eviction=eviction, busy_loop=busy_loop
+        )
+
+    def put(
+        self,
+        key: CacheEngineKey,
+        memory_obj: MemoryObj,
+        location: Optional[str] = None,
+    ) -> None:
+        """
+        Non-blocking function to put the memory object into the storages.
+        Do not store if the same object is being stored (handled here by
+        storage manager) or has been stored (handled by storage backend).
+        """
+        raise RuntimeError(
+            "StorageManager.put is deprecated and should not be called anymore"
+        )
+
+    def batched_put(
+        self,
+        keys: Sequence[CacheEngineKey],
+        memory_objs: List[MemoryObj],
+        transfer_spec=None,
+        location: Optional[str] = None,
+    ) -> None:
+        """
+        Non-blocking function to batched put the memory objects into the
+        storage backends.
+        Do not store if the same object is being stored (handled here by
+        storage manager) or has been stored (handled by storage backend).
+        """
+        # The dictionary from backend cname to objects and keys
+        obj_dict: dict[
+            str,
+            tuple[Sequence[CacheEngineKey], list[MemoryObj]],
+        ] = {}
+        if self.allocator_backend is None:
+            # For scheduler role, no allocator backend available
+            raise RuntimeError("Batched put not available for scheduler role")
+        obj_dict[get_backend_cname(self.allocator_backend)] = (
+            keys,
+            memory_objs,
+        )
+
+        for backend_name, backend in self.storage_backends.items():
+            if location and backend_name != location:
+                continue
+            # Skip bypassed backends
+            with self._bypass_lock:
+                if backend_name in self._bypassed_backends:
+                    continue
+
+            allocator_backend = backend.get_allocator_backend()
+            cname = get_backend_cname(allocator_backend)
+            if cname not in obj_dict:
+                new_keys, new_objs = allocate_and_copy_objects(
+                    allocator_backend, keys, memory_objs, self.internal_copy_stream
+                )
+                obj_dict[cname] = (new_keys, new_objs)
+
+            # NOTE: the handling of exists_in_put_tasks
+            # is done in the backend
+            ks, objs = obj_dict[cname]
+            backend.batched_submit_put_task(ks, objs, transfer_spec=transfer_spec)
+
+        for cname, (ks, objs) in obj_dict.items():
+            for memory_obj in objs:
+                memory_obj.ref_count_down()
+
+    def get(
+        self,
+        key: CacheEngineKey,
+        location: Optional[str] = None,
+    ) -> Optional[MemoryObj]:
+        """
+        Blocking function to get the memory object from the storages.
+        """
+
+        # Search all backends for blocking get
+        for backend_name, backend in self.get_active_storage_backends(location):
+            # TODO(Jiayi): need to make sure all memory_objs returned
+            # are allocated by the allocator backend.
+            memory_obj = backend.get_blocking(key)
+            if memory_obj:
+                if (
+                    backend_name not in ["LocalCPUBackend", "PDBackend", "MaruBackend"]
+                    and "LocalCPUBackend" in self.storage_backends
+                ):
+                    local_cpu_backend = self.storage_backends["LocalCPUBackend"]
+                    assert isinstance(local_cpu_backend, LocalCPUBackend)
+                    local_cpu_backend.submit_put_task(key, memory_obj)
+                return memory_obj
+
+        return None
+
+    def get_non_blocking(
+        self,
+        key: CacheEngineKey,
+        location: Optional[str] = None,
+    ) -> Optional[Future]:
+        """
+        Non-blocking function to get the memory object from the storages.
+        """
+        # TODO (Jiayi): incorporate prefetching here
+
+        # Search all backends for non-blocking get
+        for backend_name, backend in self.get_active_storage_backends(location):
+            # NOTE(Jiayi): bypass the allocator for now
+            task = backend.get_non_blocking(key)
+            if task:
+                # TODO (Jiayi): add write-back logic here
+                return task
+        return None
+
+    def batched_get(
+        self,
+        keys: List[CacheEngineKey],
+        location: Optional[str] = None,
+    ) -> List[Optional[MemoryObj]]:
+        """
+        Blocking function to get the memory objects from the storages.
+        """
+        # TODO (ApostaC): remove the nested optional here
+        for backend_name, storage_backend in self.get_active_storage_backends(location):
+            memory_objs = storage_backend.batched_get_blocking(keys)
+            if memory_objs:
+                # Align with single-key `get()` logic:
+                # auto-write remote data to local CPU cache
+                if (
+                    backend_name not in ["LocalCPUBackend", "PDBackend", "MaruBackend"]
+                    and "LocalCPUBackend" in self.storage_backends
+                    and None not in memory_objs
+                ):
+                    logger.debug(
+                        "Storing %s objects from %s to LocalCPUBackend",
+                        len(keys),
+                        backend_name,
+                    )
+                    local_cpu_backend = self.storage_backends["LocalCPUBackend"]
+                    assert isinstance(local_cpu_backend, LocalCPUBackend)
+                    # Type cast: Safe (we verified no Nones above)
+                    # `batched_submit_put_task` expects list[MemoryObj]
+                    # TODO (lisiG9): Refactor this write-back logic into caching
+                    #  policy module
+                    memory_objs_no_none = cast(List[MemoryObj], memory_objs)
+                    local_cpu_backend.batched_submit_put_task(keys, memory_objs_no_none)
+                return memory_objs
+        return [None] * len(keys)
+
+    def layerwise_batched_get(
+        self,
+        keys: List[List[CacheEngineKey]],
+        location: Optional[str] = None,
+    ) -> Generator[Future, None, None]:
+        """
+        Non-blocking function to get the memory objects into the storages
+        in a layerwise manner.
+        Do not store if the same object is being stored (handled here by
+        storage manager) or has been stored (handled by storage backend).
+
+        :param List[List[CacheEngineKey]] keys: The keys to get. The first
+            dimension corresponds to the number of layers, and the second
+            dimension corresponds to the number of chunks.
+
+        :return: A generator that yields a future for each layer.
+        """
+        if location is None:
+            location = "LocalCPUBackend"
+        for keys_multi_chunk in keys:
+            # Retrieve all chunks for one layer
+            backend = self.storage_backends[location]
+            # TODO(Jiayi): need to make async loading and layerwise compatible
+            coro = backend.batched_get_non_blocking("fake_lookup_id", keys_multi_chunk)
+            task = asyncio.run_coroutine_threadsafe(coro, self.loop)
+            yield task
+
+    def prefetch_single_done_callback(
+        self,
+        future: asyncio.Future,
+        keys: list[CacheEngineKey],
+        backend_name: str,
+    ) -> None:
+        """
+        Callback function when a single prefetch task
+        (i.e., prefetching from a single backend) is done.
+        """
+        # TODO(Jiayi): support write-back policy here
+        pass
+
+    def prefetch_all_done_callback(
+        self,
+        task: asyncio.Future,
+        lookup_id: str,
+        cum_chunk_lengths_total: list[int],
+        tier_expected_chunks: list[int],
+        keys_per_chunk: int = 1,
+    ) -> None:
+        """
+        Callback function when all prefetch tasks
+        (i.e., prefetching from all backends for the entire request) are done.
+
+        :param int keys_per_chunk: Number of storage keys per logical chunk
+            (``num_layers`` for layerwise mode, ``1`` otherwise). Used to
+            convert each tier's per-key result count back to chunk units.
+        """
+        assert self.async_lookup_server is not None
+        self.event_manager.update_event_status(
+            EventType.LOADING, lookup_id, status=EventStatus.DONE
+        )
+        res = task.result()
+
+        # Calculate total retrieved chunks across all tiers based on actual results
+        # from batched_get_non_blocking, not the batched_async_contains results.
+        # This handles the case where chunks may be evicted between contains check
+        # and actual retrieval.
+        #
+        # Example: chunk_size=256, 7 chunks total (1792 tokens) across 3 tiers
+        #   cum_chunk_lengths_total = [0, 256, 512, 768, 1024, 1280, 1536, 1792]
+        #   tier_expected_chunks = [3, 2, 2]  # Tier 0: 3, Tier 1: 2, Tier 2: 2
+        #
+        #   Chunks:
+        #   [0 1 2 3 4 5 6]
+        #   |-----|          <--- stored in Tier0, tier_expected_chunks[0]==3
+        #         |---|      <--- stored in Tier1, tier_expected_chunks[1]==2
+        #             |---|  <--- stored in Tier2, tier_expected_chunks[2]==2
+        #
+        # Case 1: All chunks retrieved successfully
+        #   [0 1 2 3 4 5 6]
+        #   |-----|          <--- Tier0: retrieved 3 chunks (obj0, obj1, obj2)
+        #         |---|      <--- Tier1: retrieved 2 chunks (obj3, obj4)
+        #             |---|  <--- Tier2: retrieved 2 chunks (obj5, obj6)
+        #   res = [[obj0, obj1, obj2], [obj3, obj4], [obj5, obj6]]
+        #   total_retrieved_chunks = 7
+        #   retrieved_length = cum_chunk_lengths_total[7] = 1792
+        #
+        # Case 2: Tier 1 only got 1 chunk (eviction), Tier 2 got all 2 chunks
+        #   [0 1 2 3 4 5 6]
+        #   |-----|          <--- Tier0: retrieved 3 chunks (obj0, obj1, obj2)
+        #         |-|X|      <--- Tier1: retrieved 1 chunk (obj3), missing obj4
+        #             |---|  <--- Tier2: retrieved 2 chunks (obj5, obj6) - IGNORED
+        #   res = [[obj0, obj1, obj2], [obj3], [obj5, obj6]]
+        #   total_retrieved_chunks = 4 (stop at tier 1, tier 2 chunks ignored)
+        #   retrieved_length = cum_chunk_lengths_total[4] = 1024
+        #   Note: Even though tier 2 successfully retrieved 2 chunks, they are
+        #   not counted because tier 1 has a gap, breaking prefix continuity.
+        #
+        # Case 3: Tier 0 only got 2 chunks (eviction), other tiers got all
+        #   [0 1 2 3 4 5 6]
+        #   |---|X|          <--- Tier0: retrieved 2 chunks (obj0, obj1), missing obj2
+        #         |---|      <--- Tier1: retrieved 2 chunks (obj3, obj4) - IGNORED
+        #             |---|  <--- Tier2: retrieved 2 chunks (obj5, obj6) - IGNORED
+        #   res = [[obj0, obj1], [obj3, obj4], [obj5, obj6]]
+        #   total_retrieved_chunks = 2 (stop at tier 0, all subsequent ignored)
+        #   retrieved_length = cum_chunk_lengths_total[2] = 512
+        total_retrieved_chunks = 0
+        for tier_idx, tier_result in enumerate(res):
+            # `tier_result` is a list of (key, mem_obj) pairs, one per
+            # storage key. With layerwise on, each logical chunk maps to
+            # keys_per_chunk per-layer keys, so divide to get chunk count.
+            # We round down so a partially-retrieved chunk (e.g., one
+            # layer evicted) is treated as a miss.
+            actual_chunks = len(tier_result) // keys_per_chunk
+            expected_chunks = tier_expected_chunks[tier_idx]
+            total_retrieved_chunks += actual_chunks
+
+            # Release the tail rounded off by actual_chunks; else staging buffer leaks.
+            tail_start = actual_chunks * keys_per_chunk
+            for _, mem_obj in tier_result[tail_start:]:
+                mem_obj.ref_count_down()
+
+            # If a tier retrieved fewer chunks than expected, we stop counting
+            # because subsequent chunks are not contiguous
+            if actual_chunks < expected_chunks:
+                # Release all chunks in subsequent tiers since they won't be used
+                for subsequent_tier in res[tier_idx + 1 :]:
+                    for _, mem_obj in subsequent_tier:
+                        mem_obj.ref_count_down()
+                break
+
+        retrieved_length = cum_chunk_lengths_total[total_retrieved_chunks]
+        logger.info(
+            "Responding to scheduler for lookup id %s with retrieved length %s",
+            lookup_id,
+            retrieved_length,
+        )
+        self.async_lookup_server.send_response_to_scheduler(lookup_id, retrieved_length)
+
+    async def async_lookup_and_prefetch(
+        self,
+        lookup_id: str,
+        keys: list[CacheEngineKey],
+        cum_chunk_lengths: list[int],
+        search_range: Optional[list[str]] = None,
+        pin: bool = False,
+        keys_per_chunk: int = 1,
+    ) -> None:
+        """
+        Perform asynchronous lookup and prefetching across all storage backends.
+
+        :param str lookup_id: The unique id (e.g., request id) for the request.
+        :param list[CacheEngineKey] keys: The keys to lookup and prefetch.
+        :param list[int] cum_chunk_lengths: The cumulative token lengths of the chunks.
+            This is a list where cum_chunk_lengths[i] represents the total number of
+            tokens from chunk 0 to chunk i-1 (inclusive).
+            Example: If chunk_size=256 and we have 3 chunks:
+                - chunk 0: 256 tokens (tokens 0-255)
+                - chunk 1: 256 tokens (tokens 256-511)
+                - chunk 2: 128 tokens (tokens 512-639)
+            Then cum_chunk_lengths = [0, 256, 512, 640]
+            Note: len(cum_chunk_lengths) = (len(keys) // keys_per_chunk) + 1
+        :param Optional[list[str]] search_range: The range of storage backends
+        to search in. Should be a subset of ["LocalCPUBackend",
+        "LocalDiskBackend"] for now. If None, search in all backends.
+        :param bool pin: Whether to pin the keys.
+        :param int keys_per_chunk: Number of storage keys per logical chunk.
+            For non-layerwise mode this is 1 (one key per chunk). For
+            layerwise mode the caller passes num_layers, since each chunk
+            is stored as num_layers per-layer keys (LayerCacheEngineKey).
+            All chunk-level accounting below is derived from
+            num_hit_keys // keys_per_chunk so that hit counts and
+            cum_chunk_lengths indexing stay in chunk units even though the
+            backend operates on per-layer keys.
+        """
+
+        # NOTE(Jiayi): Currently, the retrieval pattern is always
+        # prefix-based. That is, we retrieve 0-t1 tokens from backend 1
+        # and retrieve t1-t2 tokens from backend 2, etc. The assumption
+        # here is that the suffix chunks are more likely to be evicted
+        # than the prefix chunks.
+        # TODO(Jiayi): We need to change/optimize this for non-prefix
+        # based retrieval patterns or cases where middle chunks are missing.
+
+        # NOTE(Jiayi): We can tolerate the last tier to have fewer loaded
+        # chunks than its lookup result indicated. This is especially helpful
+        # for P2PBackend.
+
+        # All chunk-level accounting (num_total_chunks, num_total_hit_chunks,
+        # tier_expected_chunks, cum_chunk_lengths indexing) is in *chunk*
+        # units, while raw key indexing into `keys` is in *key* units.
+        # When keys_per_chunk == 1 these are identical; when layerwise is
+        # on, each chunk corresponds to num_layers keys.
+        if keys_per_chunk < 1:
+            raise ValueError(f"keys_per_chunk must be >= 1, got {keys_per_chunk}")
+        if len(keys) % keys_per_chunk != 0:
+            raise ValueError(
+                f"len(keys)={len(keys)} is not a multiple of "
+                f"keys_per_chunk={keys_per_chunk}"
+            )
+        num_total_chunks = len(keys) // keys_per_chunk
+        num_total_hit_chunks = 0
+        # cum_chunk_lengths_total: A copy of the original cumulative chunk lengths
+        # for all chunks. This is preserved to calculate the final token count
+        # based on the actual retrieved chunks.
+        # Example: If chunk_size=256 and we have 3 chunks with total 640 tokens:
+        #     cum_chunk_lengths_total = [0, 256, 512, 640]
+        # If we retrieve 2 chunks, the retrieved token count is:
+        #     cum_chunk_lengths_total[2] = 512 tokens
+        cum_chunk_lengths_total = cum_chunk_lengths[:]
+        loading_tasks = []
+        tier_expected_chunks = []
+        # we also keep track of the keys for each tier and each chunk
+        loading_task_keys: list[list[CacheEngineKey]] = []
+        for backend_name, backend in self.get_active_storage_backends(
+            search_range=search_range
+        ):
+            num_hit_keys_raw = await backend.batched_async_contains(
+                lookup_id, keys, pin
+            )
+            # Round down to a whole-chunk boundary. If a backend has only
+            # some of a chunk's per-layer keys (e.g., partial eviction),
+            # we treat the chunk as a miss to keep the chunk-level
+            # invariant required by the prefix-match retrieval pattern.
+            num_hit_chunks = num_hit_keys_raw // keys_per_chunk
+            num_hit_keys = num_hit_chunks * keys_per_chunk
+
+            # `pin=True` pins every matching key inside batched_async_contains.
+            # The rounded-off tail (keys[num_hit_keys:num_hit_keys_raw]) is
+            # dropped from backend_keys and never retrieved, so release those
+            # pins here to avoid leaking refcount budget.
+            if pin and num_hit_keys < num_hit_keys_raw:
+                for k in keys[num_hit_keys:num_hit_keys_raw]:
+                    backend.unpin(k)
+
+            if num_hit_chunks == 0:
+                continue
+
+            num_total_hit_chunks += num_hit_chunks
+            tier_expected_chunks.append(num_hit_chunks)
+
+            backend_keys = keys[:num_hit_keys]
+            loading_task_keys.append(backend_keys)
+
+            assert self.async_serializer is not None, (
+                "Async serializer must be initialized via post_init before using "
+                "async_lookup_and_prefetch."
+            )
+            # num_hit_chunks is only used for the multi serializer
+            get_coro = self.async_serializer.run(
+                backend.batched_get_non_blocking(
+                    lookup_id,
+                    backend_keys,
+                    {"cum_chunk_lengths": cum_chunk_lengths[: num_hit_chunks + 1]},
+                ),
+                num_hit_chunks,
+            )
+            loading_task = asyncio.create_task(get_coro)
+            loading_task.add_done_callback(
+                functools.partial(
+                    self.prefetch_single_done_callback,
+                    keys=keys,
+                    backend_name=backend_name,
+                )
+            )
+
+            loading_tasks.append(loading_task)
+
+            cum_chunk_lengths = cum_chunk_lengths[num_hit_chunks:]
+
+            if num_total_hit_chunks == num_total_chunks:
+                break
+            keys = keys[num_hit_keys:]
+
+        # If no chunks were hit across all backends, respond immediately and return.
+        if num_total_hit_chunks == 0:
+            if self.async_lookup_server is not None:
+                self.async_lookup_server.send_response_to_scheduler(lookup_id, 0)
+            return
+
+        # gather_with_keys() here make a pair of (key, memory_obj) for each chunk
+        # in each tier. The all_done result's layout is like following and
+        # will be processed in _async_process_tokens_internal()
+        # Tier 0:
+        #  Tuple(loading_task_keys[0][0] : MemoryObj0)
+        #  Tuple(loading_task_keys[0][1] : MemoryObj1)
+        # Tier 1:
+        #  Tuple(loading_task_keys[1][0] : MemoryObj2)
+        #  Tuple(loading_task_keys[1][1] : MemoryObj3)
+        async def gather_with_keys() -> list[list[tuple[CacheEngineKey, MemoryObj]]]:
+            loading_results = await asyncio.gather(*loading_tasks)
+            return [
+                list(zip(keys, results, strict=False))
+                for keys, results in zip(
+                    loading_task_keys, loading_results, strict=False
+                )
+            ]
+
+        all_done = asyncio.create_task(gather_with_keys())
+        # Register the event before adding the callback to avoid race conditions
+        self.event_manager.add_event(
+            EventType.LOADING,
+            lookup_id,
+            all_done,
+        )
+
+        all_done.add_done_callback(
+            lambda future: self.prefetch_all_done_callback(
+                future,
+                lookup_id,
+                cum_chunk_lengths_total,
+                tier_expected_chunks,
+                keys_per_chunk=keys_per_chunk,
+            )
+        )
+
+    def set_hot_cache(self, enabled: bool) -> None:
+        """
+        Dynamically enable or disable the hot cache on LocalCPUBackend.
+
+        When disabled, the existing hot cache entries will be cleared
+        and no new data will be written to the hot cache.
+
+        Args:
+            enabled: True to enable hot cache, False to disable
+        """
+        backend = self.local_cpu_backend
+        if not isinstance(backend, LocalCPUBackend):
+            logger.warning("Cannot set hot_cache: LocalCPUBackend not available")
+            return
+
+        if not enabled:
+            backend.clear()
+        backend.use_hot = enabled
+        logger.info("LocalCPUBackend hot_cache set to %s", enabled)
+
+    def is_hot_cache_enabled(self) -> bool:
+        """
+        Get the current hot cache status of LocalCPUBackend.
+
+        Returns:
+            bool: True if hot cache is enabled, False otherwise
+        """
+        backend = self.local_cpu_backend
+        if not isinstance(backend, LocalCPUBackend):
+            return False
+        return backend.use_hot
+
+    def set_freeze(self, enabled: bool) -> None:
+        """
+        Set freeze mode.
+
+        When enabled, only local_cpu backend will be used for retrieval.
+        """
+        with self._freeze_lock:
+            self._freeze = enabled
+        logger.info("StorageManager freeze mode set to %s", enabled)
+
+    def is_frozen(self) -> bool:
+        """
+        Get freeze mode status.
+
+        Returns:
+            bool: True if freeze mode is enabled, False otherwise
+        """
+        with self._freeze_lock:
+            return self._freeze
+
+    def set_backend_bypass(self, backend_name: str, bypassed: bool) -> None:
+        """
+        Set bypass mode for a specific backend.
+
+        When a backend is bypassed:
+        - It will be skipped during contains/put/get operations
+        - This is typically used when a health check fails with LOCAL_CPU fallback
+
+        Args:
+            backend_name: The name of the backend to bypass (e.g., "RemoteBackend")
+            bypassed: True to bypass, False to restore normal operation
+        """
+        with self._bypass_lock:
+            if bypassed:
+                self._bypassed_backends.add(backend_name)
+                logger.info("StorageManager: Backend %s is now bypassed", backend_name)
+            else:
+                self._bypassed_backends.discard(backend_name)
+                logger.info(
+                    "StorageManager: Backend %s bypass removed, "
+                    "restored to normal operation",
+                    backend_name,
+                )
+
+    def is_backend_bypassed(self, backend_name: str) -> bool:
+        """
+        Check if a backend is currently bypassed.
+
+        Args:
+            backend_name: The name of the backend to check
+
+        Returns:
+            bool: True if the backend is bypassed, False otherwise
+        """
+        with self._bypass_lock:
+            return backend_name in self._bypassed_backends
+
+    def get_bypassed_backends(self) -> List[str]:
+        """
+        Get the list of currently bypassed backend names.
+
+        Returns:
+            List[str]: List of bypassed backend names
+        """
+        with self._bypass_lock:
+            return list(self._bypassed_backends)
+
+    def get_all_backend_names(self) -> List[str]:
+        """
+        Get the list of all registered backend names.
+
+        Returns:
+            List[str]: List of all backend names
+        """
+        return list(self.storage_backends.keys())
+
+    def contains(
+        self,
+        key: CacheEngineKey,
+        search_range: Optional[List[str]] = None,
+        pin: bool = False,
+    ) -> Optional[str]:
+        """
+        Check whether the key exists in the storage backend.
+
+        :param CacheEngineKey key: The key to check.
+
+        :param Optional[List[str]] search_range: The range of storage backends
+        to search in. Should be a subset of ["LocalCPUBackend",
+        "LocalDiskBackend"] for now.
+        If None, search in all backends.
+
+        :param bool pin: Whether to pin the key.
+
+        return: True if the key exists in the specified storage backends.
+        """
+
+        for backend_name, backend in self.get_active_storage_backends(
+            search_range=search_range
+        ):
+            # NOTE(Jiayi): We do not pin for PDBackend
+            pin_in_backend = pin if backend_name != "PDBackend" else False
+
+            if backend.contains(key, pin_in_backend):
+                return backend_name
+
+        return None
+
+    def batched_contains(
+        self,
+        keys: List[CacheEngineKey],
+        search_range: Optional[List[str]] = None,
+        pin: bool = False,
+    ) -> tuple[int, dict]:
+        """
+        Check whether the key exists in the storage backend.
+
+        :param List[CacheEngineKey] keys: The keys to check.
+
+        :param Optional[List[str]] search_range: The range of storage backends
+        to search in. Should be a subset of ["LocalCPUBackend",
+        "LocalDiskBackend"] for now.
+        If None, search in all backends.
+
+        :param bool pin: Whether to pin the key.
+
+        return: Return hit chunks and block mapping by prefix match.
+        """
+        total_keys = len(keys)
+        total_hit_chunks = 0
+        block_mapping = {}
+        for backend_name, backend in self.get_active_storage_backends(
+            search_range=search_range
+        ):
+            # NOTE(Jiayi): We do not pin for PDBackend
+            pin_in_backend = pin if backend_name != "PDBackend" else False
+
+            hit_chunks = backend.batched_contains(keys, pin_in_backend)
+            if hit_chunks == 0:
+                continue
+            block_mapping[backend_name] = keys[:hit_chunks]
+            total_hit_chunks += hit_chunks
+            if total_hit_chunks == total_keys:
+                break
+            keys = keys[hit_chunks:]
+
+        return total_hit_chunks, block_mapping
+
+    def get_block_mapping(
+        self, chunk_infos: List[Tuple[CacheEngineKey, int, int]]
+    ) -> Dict[str, List[Tuple[CacheEngineKey, int, int]]]:
+        """
+        Get block mapping for the given chunk infos, works by prefix match.
+
+        :param List[Tuple[CacheEngineKey, int, int]] chunk_infos:
+        List of chunk infos, each tuple contains (key, begin, end)
+
+        :return: Dict[str, List[Tuple[CacheEngineKey, int, int]]]:
+        Block mapping for the given chunk infos, each key is the backend name,
+        each value is a list of chunk infos in the backend.
+        """
+        keys = [chunk_info[0] for chunk_info in chunk_infos]
+        total_keys = len(keys)
+        block_mapping = {}
+        total_hit_chunks = 0
+        for backend_name, backend in self.get_active_storage_backends():
+            hit_chunks = backend.batched_contains(keys)
+            if hit_chunks == 0:
+                continue
+            block_mapping[backend_name] = chunk_infos[
+                total_hit_chunks : total_hit_chunks + hit_chunks
+            ]
+            total_hit_chunks += hit_chunks
+            if total_hit_chunks == total_keys:
+                break
+            keys = keys[hit_chunks:]
+        return block_mapping
+
+    def touch_cache(self) -> None:
+        for backend_name, backend in self.storage_backends.items():
+            if backend_name == "LocalCPUBackend" or backend_name == "LocalDiskBackend":
+                backend.touch_cache()
+
+    def remove(
+        self,
+        key: CacheEngineKey,
+        locations: Optional[List[str]] = None,
+    ) -> int:
+        """
+        Remove the key and the corresponding cache in the specified
+        locations.
+
+        :param CacheEngineKey key: The key to remove.
+
+        :param Optional[List[str]] locations: The range of storage backends
+        to perform `remove` in.
+        Should be a subset of ["LocalCPUBackend", "LocalDiskBackend"] for now.
+        If None, perform `remove` in all backends.
+
+        return: Total number of removed caches in the specified
+        storage backends.
+        """
+
+        num_removed = 0
+        for backend_name, backend in self.storage_backends.items():
+            # TODO(Jiayi): need to handle remove in non-cpu backends
+            if locations is None or backend_name in locations:
+                num_removed += backend.remove(key)
+
+        return num_removed
+
+    def batched_remove(
+        self,
+        keys: List[CacheEngineKey],
+        locations: Optional[List[str]] = None,
+    ) -> int:
+        """
+        Batched remove the keys and the corresponding cache in the specified
+        locations.
+
+        :param List[CacheEngineKey] keys: The keys to remove.
+
+        :param Optional[List[str]] locations: The range of storage backends
+        to perform `remove` in.
+        Should be a subset of ["LocalCPUBackend", "LocalDiskBackend"] for now.
+        If None, perform `remove` in all backends.
+
+        return: Total number of removed caches in the specified
+        storage backends.
+        """
+        num_removed = 0
+        for backend_name, backend in self.storage_backends.items():
+            if locations is None or backend_name in locations:
+                num_removed += backend.batched_remove(keys)
+
+        return num_removed
+
+    def batched_unpin(
+        self,
+        keys: List[CacheEngineKey],
+        locations: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Unpin the keys in the specified locations.
+
+        :param List[CacheEngineKey] keys: The keys to unpin.
+
+        :param Optional[List[str]] locations: The range of storage backends
+        to perform `unpin` in.
+        Should be a subset of ["LocalCPUBackend", "LocalDiskBackend"] for now.
+        If None, perform `unpin` in all backends.
+        """
+        for backend_name, backend in self.storage_backends.items():
+            if locations is None or backend_name in locations:
+                for key in keys:
+                    backend.unpin(key)
+
+    def clear(
+        self,
+        locations: Optional[List[str]] = None,
+    ) -> int:
+        """
+        Clear all caches in the specified locations.
+
+        :param Optional[List[str]] locations: The range of storage backends
+        to perform `clear` in.
+        Should be a subset of ["LocalCPUBackend", "LocalDiskBackend"] for now.
+        If None, perform `clear` in all backends.
+
+        return: Total number of cleared tokens in the specified
+        storage backends.
+        """
+
+        num_cleared_tokens = 0
+        for backend_name, backend in self.storage_backends.items():
+            # TODO(Jiayi): need to handle remove in non-cpu backends
+            if locations is None or backend_name in locations:
+                if hasattr(backend, "clear"):
+                    num_cleared_tokens += backend.clear()
+                else:
+                    logger.warning(
+                        "Storage backend %s does not support "
+                        "clear operation. Skipping.",
+                        backend_name,
+                    )
+
+        return num_cleared_tokens
+
+    def memcheck(self) -> bool:
+        """
+        Check the integrity of the underlying storage backend's
+        memory allocators
+
+        Returns:
+            True if everything is good otherwise False
+        """
+        for backend in self.storage_backends.values():
+            if not isinstance(backend, AllocatorBackendInterface):
+                continue
+            if not backend.get_memory_allocator().memcheck():
+                return False
+        return True
+
+    def get_active_storage_backends(
+        self,
+        location: Optional[str] = None,
+        search_range: Optional[List[str]] = None,
+    ) -> Generator[Tuple[str, StorageBackendInterface], None, None]:
+        """
+        Get the active storage backends based on freeze mode, bypass mode, and filters.
+
+        :param Optional[str] location: If specified, only yield backends
+            matching this exact name.
+        :param Optional[List[str]] search_range: If specified, only yield
+            backends whose names are in this list.
+
+        :return: Generator of (backend_name, backend) tuples.
+        """
+        for backend_name, backend in self.storage_backends.items():
+            # In freeze mode, only use local_cpu backend
+            with self._freeze_lock:
+                if self._freeze and backend_name != "LocalCPUBackend":
+                    continue
+            # Skip bypassed backends
+            with self._bypass_lock:
+                if backend_name in self._bypassed_backends:
+                    continue
+            if location and backend_name != location:
+                continue
+            if search_range and backend_name not in search_range:
+                continue
+            yield backend_name, backend
+
+    def get_non_allocator_backends(self) -> List[str]:
+        """
+        Get the names of the actual storage backends. Some backends,
+        such as LocalCPUBackend and PDBackend, in some cases, only
+        serve as a backend for allocation.
+        """
+        storage_names = []
+        for backend_name, backend in self.storage_backends.items():
+            if "LocalCPUBackend" == backend_name and not self.config.local_cpu:
+                # if local_cpu is False, means LocalCPUBackend is only a allocator
+                continue
+            if "PDBackend" == backend_name and backend.pd_config.role == "sender":  # type: ignore
+                # if pd_config.role is sender, means PDBackend is only a allocator
+                continue
+            storage_names.append(backend_name)
+        return storage_names
+
+    def list_backends(self) -> Dict[str, str]:
+        """
+        List all active storage backends.
+
+        Returns:
+            Dict mapping backend name to its class name.
+        """
+        with self.manager_lock:
+            return {
+                name: type(backend).__name__
+                for name, backend in self.storage_backends.items()
+            }
+
+    def close_backend(self, backend_name: str) -> bool:
+        """
+        Close and remove a specific storage backend by name.
+
+        The backend will be closed and removed from the internal
+        dict so that no stale references remain.
+
+        Args:
+            backend_name: The name of the backend to close.
+
+        Returns:
+            True if the backend was found and closed, False
+            otherwise.
+        """
+        with self.manager_lock:
+            backend = self.storage_backends.get(backend_name)
+            if backend is None:
+                logger.warning(
+                    "Backend %s not found, cannot close",
+                    backend_name,
+                )
+                return False
+
+            try:
+                logger.info("Closing backend: %s", backend_name)
+                backend.close()
+            except Exception:
+                logger.exception("Error closing backend %s", backend_name)
+
+            del self.storage_backends[backend_name]
+
+            # Update derived references
+            self.non_allocator_backends = self.get_non_allocator_backends()
+            if backend_name == "LocalCPUBackend":
+                self.local_cpu_backend = None
+            logger.info("Backend %s closed and removed", backend_name)
+            return True
+
+    def create_backends(self) -> Dict[str, str]:
+        """
+        Create new storage backends based on current config.
+
+        Backends that are already present will be skipped
+        **before** instantiation so that no unnecessary
+        resources are allocated.  This allows callers to close
+        a subset of backends, update config via ``/conf``,
+        and then call this method to bring up only the missing
+        backends.
+
+        Returns:
+            Dict mapping newly created backend name to its
+            class name.
+        """
+        with self.manager_lock:
+            existing_names = set(self.storage_backends)
+            new_backends = CreateStorageBackends(
+                self.config,
+                self.metadata,
+                self.loop,
+                dst_device=(
+                    torch_device_type if is_cuda_worker(self.metadata) else "cpu"
+                ),
+                lmcache_worker=self.lmcache_worker,
+                skip_backends=existing_names,
+                existing_backends=self.storage_backends,
+            )
+
+            created: Dict[str, str] = {}
+            for name, backend in new_backends.items():
+                self.storage_backends[name] = backend
+                created[name] = type(backend).__name__
+                logger.info(
+                    "Created backend: %s (%s)",
+                    name,
+                    created[name],
+                )
+
+            # Refresh derived references
+            self.non_allocator_backends = self.get_non_allocator_backends()
+            cpu = self.storage_backends.get("LocalCPUBackend")
+            if cpu is not None:
+                self.local_cpu_backend = cpu
+
+            return created
+
+    def recreate_backend(self, backend_name: str) -> Dict[str, str]:
+        """
+        Close a backend and recreate it from current config.
+
+        This is an atomic close-then-create operation that
+        combines :meth:`close_backend` and :meth:`create_backends`
+        into a single step.
+
+        Args:
+            backend_name: Name of the backend to recreate
+                (e.g. ``RemoteBackend``).
+
+        Returns:
+            Dict mapping newly created backend name to its
+            class name.
+
+        Raises:
+            KeyError: If *backend_name* does not exist.
+        """
+        with self.manager_lock:
+            backend = self.storage_backends.get(backend_name)
+            if backend is None:
+                raise KeyError("Backend %s not found" % backend_name)
+
+            # --- close ---
+            try:
+                logger.info("Closing backend: %s", backend_name)
+                backend.close()
+            except Exception:
+                logger.exception("Error closing backend %s", backend_name)
+            del self.storage_backends[backend_name]
+
+            # --- create ---
+            existing_names = set(self.storage_backends)
+            new_backends = CreateStorageBackends(
+                self.config,
+                self.metadata,
+                self.loop,
+                dst_device=(
+                    torch_device_type if is_cuda_worker(self.metadata) else "cpu"
+                ),
+                lmcache_worker=self.lmcache_worker,
+                skip_backends=existing_names,
+                existing_backends=self.storage_backends,
+            )
+
+            created: Dict[str, str] = {}
+            for name, be in new_backends.items():
+                self.storage_backends[name] = be
+                created[name] = type(be).__name__
+                logger.info(
+                    "Recreated backend: %s (%s)",
+                    name,
+                    created[name],
+                )
+
+            # Refresh derived references
+            self.non_allocator_backends = self.get_non_allocator_backends()
+            cpu = self.storage_backends.get("LocalCPUBackend")
+            if cpu is not None:
+                self.local_cpu_backend = cpu
+            elif backend_name == "LocalCPUBackend":
+                self.local_cpu_backend = None
+
+            return created
+
+    def cancel_request(self, req_id: str) -> None:
+        """
+        Cancel an in-flight or pending request.
+
+        Delegates to all storage backends. Backends that track per-request
+        state will cancel the request; others will no-op.
+
+        :param str req_id: The request identifier to cancel.
+        :return: None
+        """
+        for backend in self.storage_backends.values():
+            backend.cancel_request(req_id)
+
+    def close(self):
+        logger.info("Closing StorageManager...")
+
+        # Close all backends
+        for name, backend in self.storage_backends.items():
+            try:
+                logger.info("Closing storage backend: %s", name)
+                backend.close()
+                logger.info("Storage backend %s closed successfully", name)
+            except Exception as e:
+                logger.error("Error closing backend %s: %s", name, e)
+
+        # Stop event loop
+        try:
+            if self.loop.is_running():
+                logger.info("Stopping event loop...")
+                self.loop.call_soon_threadsafe(self.loop.stop)
+                logger.info("Event loop stop signaled")
+        except Exception as e:
+            logger.error("Error stopping event loop: %s", e)
+
+        # Wait for thread with timeout
+        if self.thread.is_alive():
+            logger.info("Waiting for storage manager thread to finish...")
+            self.thread.join(timeout=10.0)
+
+            if self.thread.is_alive():
+                logger.warning(
+                    "Storage manager thread did not terminate within 10s timeout. "
+                    "Proceeding with shutdown anyway."
+                )
+            else:
+                logger.info("Storage manager thread terminated successfully")
+        else:
+            logger.info("Storage manager thread already stopped")
+
+        logger.info("Storage manager closed.")
diff --git a/lmcache/v1/system_detection.py b/lmcache/v1/system_detection.py
new file mode 100644
index 0000000..133a3cd
--- /dev/null
+++ b/lmcache/v1/system_detection.py
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+import platform
+
+# Third Party
+import psutil
+
+try:
+    # First Party
+    from lmcache.c_ops import get_gpu_pci_bus_id
+except ImportError:
+    # Fallback if c_ops is not available
+    get_gpu_pci_bus_id = None
+
+# First Party
+from lmcache import torch_dev
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class NUMAMapping:
+    gpu_to_numa_mapping: dict[int, int]
+
+
+class SystemMemoryDetector:
+    @staticmethod
+    def get_available_memory_gb() -> float:
+        """
+        Get system available memory in GB using psutil.
+        This method is cross-platform and doesn't require subprocess calls.
+
+        Returns:
+            Available memory in GB, or 0.0 if detection fails.
+        """
+        try:
+            # Use psutil to get virtual memory information
+            memory = psutil.virtual_memory()
+            available_gb = memory.available / (1024**3)
+
+            system = platform.system()
+            logger.info("%s system available memory: %.2f GB", system, available_gb)
+            return available_gb
+
+        except Exception as e:
+            logger.warning("Failed to get system available memory using psutil: %s", e)
+            return 0.0
+
+
+class NUMADetector:
+    @staticmethod
+    def get_numa_mapping(config: LMCacheEngineConfig) -> Optional[NUMAMapping]:
+        """
+        Get NUMA mapping.
+        """
+        assert config.numa_mode in ["manual", "auto", None], (
+            "NUMA mode must be either 'auto',  'manual', or None."
+            f" Current mode: {config.numa_mode}"
+        )
+
+        numa_mapping: Optional[NUMAMapping] = None
+        if config.numa_mode == "manual":
+            numa_mapping = NUMADetector._read_from_config(config)
+        elif config.numa_mode == "auto":
+            numa_mapping = NUMADetector._read_from_sys()
+
+        return numa_mapping
+
+    @staticmethod
+    def _read_from_config(config) -> NUMAMapping:
+        """
+        Read NUMA mapping from the LMCache configuration.
+        """
+
+        assert config.extra_config is not None, (
+            "NUMA mode is set but extra_config is None. "
+            "Please ensure the configuration is properly set."
+        )
+
+        assert "gpu_to_numa_mapping" in config.extra_config, (
+            "NUMA mode is set to `manual` but gpu_to_numa_mapping is None. "
+            "Please ensure the configuration is properly set."
+        )
+
+        gpu_to_numa_mapping = config.extra_config.get("gpu_to_numa_mapping")
+
+        return NUMAMapping(gpu_to_numa_mapping)
+
+    @staticmethod
+    def _read_from_sys() -> Optional[NUMAMapping]:
+        """
+        Read NUMA mapping from system configuration.
+        """
+
+        try:
+            device_index = torch_dev.current_device()
+            pci_bus_id = get_gpu_pci_bus_id(device_index).lower()
+
+            numa_node_file = f"/sys/bus/pci/devices/{pci_bus_id}/numa_node"
+            with open(numa_node_file) as f:
+                numa_node = int(f.read())
+
+            return NUMAMapping(gpu_to_numa_mapping={device_index: numa_node})
+        except Exception as e:
+            logger.warning("Failed to auto read NUMA mapping from system: %s", e)
+            return None
diff --git a/lmcache/v1/token_database.py b/lmcache/v1/token_database.py
new file mode 100644
index 0000000..ff9e5a2
--- /dev/null
+++ b/lmcache/v1/token_database.py
@@ -0,0 +1,580 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+vLLM compatibility notes:
+- PR#20511: Introduced kv_cache_utils.init_none_hash()
+  https://github.com/vllm-project/vllm/pull/20511
+- PR#23673: Renamed sha256_cbor_64bit to sha256_cbor
+  https://github.com/vllm-project/vllm/pull/23673
+- PR#27151: Moved hash functions to vllm.utils.hashing module
+  https://github.com/vllm-project/vllm/pull/27151
+
+TODO(baoloongmao): Move this to vllm_v1_adapter to decouple from vLLM
+"""
+
+# Standard
+from typing import Any, Iterable, List, Optional, Tuple, Union
+import abc
+import os
+
+# Third Party
+from transformers import AutoTokenizer
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey, _lmcache_nvtx_annotate
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+NONE_HASH = 0
+
+
+def _normalize_hash_to_int(hash_value: Union[int, bytes]) -> int:
+    """Normalize hash outputs to LMCache's int chunk-hash representation.
+
+    This function is triggered when vLLM's ``sha256_cbor`` hash function is
+    used because it returns a 32-byte digest. vLLM's
+    ``kv_cache_utils.init_none_hash`` can therefore initialize ``NONE_HASH`` as
+    bytes, and direct hash calls for token chunks can also return bytes.
+
+    LMCache stores chunk hashes in ``CacheEngineKey`` and serializes them with
+    msgpack, so byte digests must be folded into uint64-compatible ints before
+    they enter the prefix hash chain. This also keeps ``NONE_HASH`` and later
+    prefix hashes using the same structural type for CBOR hashing.
+
+    Args:
+        hash_value: Hash output from vLLM or Python's builtin hash.
+
+    Returns:
+        The original int hash value, or the first eight bytes of a digest as a
+        big-endian int.
+    """
+    if isinstance(hash_value, bytes):
+        return int.from_bytes(hash_value[:8], "big")
+    return hash_value
+
+
+# Type alias for process_tokens return value
+# (start_index, end_index, cache_engine_key｜hash)
+ProcessTokensResult = Tuple[int, int, Union[CacheEngineKey, int]]
+
+
+class TokenDatabase(metaclass=abc.ABCMeta):
+    """TokenDatabase is used to convert input tokens into list of
+    cache engine keys. There are multiple ways to implement this:
+
+    - ChunkedTokenDatabase: It processes tokens into chunks and convert
+    each chunk into a cache engine key using prefix hash.
+
+    - SegmentTokenDatabase: It processes tokens into segments based on
+    special separators and convert each segment into a cache engine key.
+    """
+
+    @abc.abstractmethod
+    def __init__(
+        self,
+        config: Optional[LMCacheEngineConfig] = None,
+        metadata: Optional[LMCacheMetadata] = None,
+    ):
+        global NONE_HASH
+
+        hash_algorithm: str = (
+            config.pre_caching_hash_algorithm if config is not None else "builtin"
+        )
+
+        # Get hash function with vLLM version compatibility
+        self.hash_func = self._get_vllm_hash_func(hash_algorithm)
+
+        # Initialize NONE_HASH (vLLM >= PR#20511)
+        # NOTE: For centralized cache sharing, ensure PYTHONHASHSEED is
+        # set consistently across all processes (e.g., export PYTHONHASHSEED=0).
+        try:
+            # Third Party
+            from vllm.v1.core import kv_cache_utils
+
+            if hasattr(kv_cache_utils, "init_none_hash"):
+                kv_cache_utils.init_none_hash(self.hash_func)
+                NONE_HASH = _normalize_hash_to_int(kv_cache_utils.NONE_HASH)
+                logger.info(
+                    "Initialized NONE_HASH=%s from vLLM (>= PR#20511)", NONE_HASH
+                )
+            else:
+                NONE_HASH = 0
+                logger.info("Using default NONE_HASH=0 (vLLM < PR#20511)")
+        except (ImportError, AttributeError):
+            NONE_HASH = 0
+            logger.info("Using default NONE_HASH=0 (vLLM not available)")
+
+        logger.info("Using hash algorithm: %s", hash_algorithm)
+        self.metadata = metadata
+        # Whether only the first rank should save cache. This flag is also used
+        # to control the logical world_size embedded into CacheEngineKey.
+        self.save_only_first_rank = False
+        if config is not None and metadata is not None:
+            # save_only_first_rank only works when use MLA, follow the same
+            # semantics as LMCacheEngine and memory allocator.
+            self.save_only_first_rank = (
+                config.get_extra_config_value("save_only_first_rank", metadata.use_mla)
+                and metadata.use_mla
+            )
+
+    def _get_vllm_hash_func(self, hash_algorithm: str):
+        """Get hash function from vLLM with version compatibility.
+
+        Tries multiple import paths to support different vLLM versions:
+        - vllm.utils.hashing.get_hash_fn_by_name (>= PR#27151)
+        - vllm.utils.get_hash_fn_by_name (< PR#27151)
+        - Direct imports as fallback
+        - sha256_cbor_64bit -> sha256_cbor rename (PR#23673)
+        """
+        # Try get_hash_fn_by_name from both locations (PR#27151)
+        for module_path in ["vllm.utils.hashing", "vllm.utils"]:
+            try:
+                module = __import__(module_path, fromlist=["get_hash_fn_by_name"])
+                get_hash_fn_by_name = module.get_hash_fn_by_name
+                return self._try_get_hash(
+                    get_hash_fn_by_name, hash_algorithm, module_path
+                )
+            except (ImportError, AttributeError, ValueError):
+                continue
+
+        # Try direct imports as fallback (for older vLLM versions)
+        func_names = (
+            ["sha256_cbor", "sha256_cbor_64bit"]
+            if hash_algorithm in ("sha256_cbor", "sha256_cbor_64bit")
+            else [hash_algorithm]
+        )
+        for module_path in ["vllm.utils.hashing", "vllm.utils"]:
+            for func_name in func_names:
+                try:
+                    module = __import__(module_path, fromlist=[func_name])
+                    hash_func = getattr(module, func_name)
+                    logger.info(
+                        "Loaded '%s' from %s (direct import)", func_name, module_path
+                    )
+                    return hash_func
+                except (ImportError, AttributeError):
+                    continue
+
+        # Fallback to builtin hash
+        logger.warning(
+            "Could not load '%s' from vLLM. Using builtin hash. "
+            "This may cause inconsistencies in distributed caching.",
+            hash_algorithm,
+        )
+
+        # Check PYTHONHASHSEED when using builtin hash
+        if os.getenv("PYTHONHASHSEED") is None:
+            logger.warning(
+                "Using builtin hash without PYTHONHASHSEED set. "
+                "For production environments (non-testing scenarios), you MUST set "
+                "PYTHONHASHSEED to ensure consistent hashing across processes. "
+                "Example: export PYTHONHASHSEED=0"
+            )
+
+        return hash
+
+    def _try_get_hash(self, get_hash_fn_by_name, hash_algorithm: str, module_name: str):
+        """Try to get hash function, handling sha256_cbor_64bit rename."""
+        # Handle sha256_cbor_64bit -> sha256_cbor rename (PR#23673)
+        names_to_try = (
+            ["sha256_cbor", "sha256_cbor_64bit"]
+            if hash_algorithm in ("sha256_cbor", "sha256_cbor_64bit")
+            else [hash_algorithm]
+        )
+
+        for name in names_to_try:
+            try:
+                hash_func = get_hash_fn_by_name(name)
+                logger.info("Loaded '%s' from %s", name, module_name)
+                return hash_func
+            except ValueError:
+                continue
+        raise ValueError(f"Hash function '{hash_algorithm}' not found in {module_name}")
+
+    @abc.abstractmethod
+    def process_tokens(
+        self,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        hashes: Optional[List[int]] = None,
+        offsets: Optional[List[int]] = None,
+        mask: Optional[torch.Tensor] = None,
+        make_key: bool = True,
+        request_configs: Optional[dict] = None,
+    ) -> Iterable[ProcessTokensResult]:
+        """Process the tokens and return the corresponding cache engine keys.
+
+        :param Optional[Union[torch.Tensor, List[int]]] tokens: The tokens to process.
+
+        :param Optional[List[int]] hashes: The hashes to process. If provided,
+            it will be used instead of tokens to generate cache engine keys.
+
+        :param Optional[List[int]] offsets: The number of tokens in each chunk.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched,
+            and the Falses will ALWAYS be at the PREFIX of the tensor.
+
+        :param bool make_key: Whether to make the cache engine key or not.
+            If False, the hash value will be returned instead.
+
+        :param Optional[dict] request_configs: The configs of the request.
+
+        :returns: A iterable of tuples with three elements. The first element
+            is the start index of the tokens for the key. The second element
+            is the end index of the tokens for the key. The third element is
+            the cache engine key (or hash) for the tokens.
+        """
+
+        raise NotImplementedError
+
+    def _make_key_by_hash(
+        self, chunk_hash: int, request_configs: Optional[dict] = None
+    ):
+        assert self.metadata is not None
+        # When save_only_first_rank is enabled (for MLA), we deliberately
+        # collapse the CacheEngineKey.world_size to 1 so that cache keys
+        # become world-size agnostic across compatible deployments.
+        return CacheEngineKey(
+            self.metadata.model_name,
+            self.metadata.world_size if not self.save_only_first_rank else 1,
+            self.metadata.worker_id,
+            chunk_hash,
+            self.metadata.kv_dtype,
+            request_configs,
+        )
+
+    def _canonicalize_hash_inputs(
+        self,
+        prefix_hash: Optional[int],
+        tokens_tuple: Tuple[int, ...],
+        extra_keys: Optional[List[Any]],
+    ) -> Tuple[int, Tuple[int, ...], Tuple[Any, ...]]:
+        """
+        Canonicalize hash inputs so that semantically identical requests
+        produce structurally identical hash inputs across instances.
+        - prefix_hash: int or NONE_HASH if None
+        - tokens_tuple: tuple of token IDs
+        - extra_keys: tuple of additional keys, empty if None
+        """
+        return (
+            prefix_hash if prefix_hash is not None else NONE_HASH,
+            tokens_tuple,
+            tuple(extra_keys) if extra_keys is not None else (),
+        )
+
+    def _hash_tokens(
+        self,
+        tokens: Union[torch.Tensor, List[int]],
+        prefix_hash: Optional[int] = None,
+        extra_keys: Optional[list[Any]] = None,
+    ) -> int:
+        if isinstance(tokens, torch.Tensor):
+            tokens_tuple = tuple(tokens.cpu().tolist())
+        elif isinstance(tokens, list):
+            tokens_tuple = tuple(tokens)
+        else:
+            raise ValueError(f"Unsupported tokens type: {type(tokens)}")
+
+        # Ignore extra keys for now
+        # Extra keys are for multi-modal inputs and
+        # request specific metadata (e.g., LoRA ID).
+        # Use default values for None to maintain a fixed tuple structure for hashing.
+
+        # Use helper to canonicalize inputs to ensure consistent hashing
+        # This replaces the logic that was causing inconsistency
+        canon_prefix, canon_tokens, canon_extra = self._canonicalize_hash_inputs(
+            prefix_hash, tokens_tuple, extra_keys
+        )
+
+        return _normalize_hash_to_int(
+            self.hash_func((canon_prefix, canon_tokens, canon_extra))
+        )
+
+
+class ChunkedTokenDatabase(TokenDatabase):
+    def __init__(
+        self,
+        config: Optional[LMCacheEngineConfig] = None,
+        metadata: Optional[LMCacheMetadata] = None,
+    ):
+        super(ChunkedTokenDatabase, self).__init__(config, metadata)
+
+        if config is not None:
+            self.config = config
+            self.chunk_size = config.chunk_size
+
+            # Check for cross-process cache sharing setup
+            if os.getenv("PYTHONHASHSEED") is None:
+                if config.remote_url is not None:
+                    logger.warning(
+                        "Centralized cache sharing detected "
+                        "but PYTHONHASHSEED not set. "
+                        "For consistent caching, set: export PYTHONHASHSEED=0 "
+                        "before the engine starts."
+                    )
+                if config.enable_pd:
+                    logger.error(
+                        "P/D Disaggregation detected "
+                        "but PYTHONHASHSEED not set. "
+                        "For consistent caching, set: export PYTHONHASHSEED=0 "
+                        "before the engine starts. "
+                        "This will cause incorrect KV cache transfer."
+                    )
+        else:  # Default values
+            self.config = None
+            self.chunk_size = 256
+
+    def _get_init_hash(self) -> int:
+        return NONE_HASH
+
+    def _chunk_tokens(
+        self,
+        tokens: Union[torch.Tensor, List[int]],
+    ) -> Iterable[Union[torch.Tensor, List[int]]]:
+        """
+        Chunk the tokens into chunks of size self.chunk_size.
+
+        :param tokens: the input tokens, with shape [seq_len]
+            device: the target device after chunking
+
+        :return: a generator of chunks of tokens, each with
+                shape [chunk_size]
+        """
+        save_unfull_chunk = (
+            self.config.save_unfull_chunk if self.config is not None else True
+        )
+        end = (
+            len(tokens)
+            if save_unfull_chunk
+            else (len(tokens) - len(tokens) % self.chunk_size)
+        )
+        for i in range(0, end, self.chunk_size):
+            yield tokens[i : i + self.chunk_size]
+
+    def _prefix_hash(
+        self,
+        token_chunks: Iterable[Union[torch.Tensor, List[int]]],
+    ) -> Iterable[int]:
+        prefix_hash = self._get_init_hash()
+        for token_chunk in token_chunks:
+            prefix_hash = self._hash_tokens(token_chunk, prefix_hash)
+            yield prefix_hash
+
+    @_lmcache_nvtx_annotate
+    def process_tokens(
+        self,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        hashes: Optional[List[int]] = None,
+        offsets: Optional[List[int]] = None,
+        mask: Optional[torch.Tensor] = None,
+        make_key: bool = True,
+        request_configs: Optional[dict] = None,
+    ) -> Iterable[ProcessTokensResult]:
+        """Process the tokens/hashes and return the corresponding cache engine keys.
+
+        :param Optional[Union[torch.Tensor, List[int]]] tokens: The tokens to process.
+
+        :param Optional[List[int]] hashes: The hashes to process. If provided,
+            it will be used instead of tokens to generate cache engine keys.
+
+        :param Optional[List[int]] offsets: The number of tokens in each chunk.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched,
+            and the Falses will ALWAYS be at the PREFIX of the tensor.
+
+        :param bool make_key: Whether to make the cache engine key or not.
+            If False, the hash value will be returned instead.
+
+        :param Optional[dict] request_configs: The configs of the request.
+
+        :returns: A iterable of tuples with three elements. The first element
+            is the start index of the tokens for the key. The second element
+            is the end index of the tokens for the key. The third element is
+            the cache engine key (or hash) for the tokens.
+
+        :raises: ValueError if the number of Falses in the mask is not a
+            multiple of the chunk size.
+        """
+        if mask is not None:
+            num_falses = mask.numel() - mask.long().sum().item()
+        else:
+            num_falses = 0
+
+        if num_falses % self.chunk_size != 0:
+            raise ValueError(
+                "The number of Falses in the mask is not a multiple of the chunk size."
+            )
+
+        if tokens is not None:
+            total_len = len(tokens)
+            token_chunks = self._chunk_tokens(tokens)
+            prefix_hashes = self._prefix_hash(token_chunks)
+            for chunk_id, hash_val in enumerate(prefix_hashes):
+                start_idx = chunk_id * self.chunk_size
+                end_idx = min(start_idx + self.chunk_size, total_len)
+                if start_idx < num_falses:
+                    continue
+                else:
+                    if make_key:
+                        yield (
+                            start_idx,
+                            end_idx,
+                            self._make_key_by_hash(hash_val, request_configs),
+                        )
+                    else:
+                        yield start_idx, end_idx, hash_val
+        elif hashes is not None:
+            assert offsets is not None, (
+                "If hashes are provided, offsets must also be provided."
+            )
+            start_idx = 0
+            for hash_val, offset in zip(hashes, offsets, strict=False):
+                end_idx = start_idx + offset
+                if make_key:
+                    yield (
+                        start_idx,
+                        end_idx,
+                        self._make_key_by_hash(hash_val, request_configs),
+                    )
+                else:
+                    yield start_idx, end_idx, hash_val
+                start_idx = end_idx
+        else:
+            raise ValueError("Either tokens or hashes must be provided.")
+
+
+class SegmentTokenDatabase(TokenDatabase):
+    """
+    Currently, we still use special separators to identify chunks.
+    In the future, we might need to implement a fast substring match.
+    """
+
+    def __init__(self, config: LMCacheEngineConfig, metadata: LMCacheMetadata):
+        super(SegmentTokenDatabase, self).__init__(config, metadata)
+
+        self.tokenizer = AutoTokenizer.from_pretrained(metadata.model_name)
+
+        # TODO (Jiayi): figure out how to decide when
+        # to use `1:` (whether there's a special starting token
+        # in the beginning)
+        self.sep_tokens = self.tokenizer.encode(config.blend_special_str)[1:]
+        self.sep_tokens = torch.tensor(self.sep_tokens, device="cpu")
+        self.sep_len = len(self.sep_tokens)
+
+    def _fast_split_by_subtensor(self, tokens: torch.Tensor) -> Iterable[torch.Tensor]:
+        """Match the `sep_tokens` with sliding windows"""
+
+        if self.sep_len == 0 or len(tokens) < self.sep_len:
+            yield tokens
+
+        # Unfold into sliding windows
+        # shape: (num_tokens-sep_len+1, sep_len)
+        windows = tokens.unfold(0, self.sep_len, 1)
+
+        # Compare each window with sep_tokens
+        matches = (
+            (windows == self.sep_tokens).all(dim=1).nonzero(as_tuple=True)[0].tolist()
+        )
+
+        # Split based on matches
+        start = 0
+        for idx in matches:
+            yield tokens[start:idx]
+            start = idx + self.sep_len
+        # yield last chunk
+        yield tokens[start:]
+
+    def process_tokens(
+        self,
+        tokens: Optional[Union[torch.Tensor, List[int]]] = None,
+        hashes: Optional[List[int]] = None,
+        offsets: Optional[List[int]] = None,
+        mask: Optional[torch.Tensor] = None,
+        make_key: bool = True,
+        request_configs: Optional[dict] = None,
+    ) -> Iterable[ProcessTokensResult]:
+        """Process the tokens and return the corresponding cache engine keys.
+
+        :param Union[torch.Tensor, List[int]] tokens: The tokens to process.
+
+        :param Optional[List[int]] hashes: The hashes to process. If provided,
+            it will be used instead of tokens to generate cache engine keys.
+
+        :param Optional[List[int]] offsets: The number of tokens in each chunk.
+
+        :param Optional[torch.Tensor] mask: The mask for the tokens. Should
+            have the same length as tokens. And the mask should ALWAYS be like
+            FFFFFTTTTTTT, where True means the tokens needs to be matched,
+            and the Falses will ALWAYS be at the PREFIX of the tensor.
+
+        :param bool make_key: Whether to make the cache engine key or not.
+            If False, the hash value will be returned instead.
+
+        :param Optional[dict] request_configs: The configs of the request.
+
+        :returns: A iterable of tuples with three elements. The first element
+            is the start index of the tokens for the key. The second element
+            is the end index of the tokens for the key. The third element is
+            the cache engine key for the tokens.
+
+        """
+
+        if tokens is not None:
+            if not isinstance(tokens, torch.Tensor):
+                tokens = torch.tensor(tokens, dtype=torch.long, device="cpu")
+            else:
+                tokens = tokens.to(device="cpu", dtype=torch.long)
+
+            if mask is not None:
+                num_falses = mask.numel() - mask.long().sum().item()
+            else:
+                num_falses = 0
+            assert num_falses < len(tokens), (
+                "The number of Falses in the mask shouldn't "
+                "be less than the length of tokens."
+            )
+
+            token_chunks = self._fast_split_by_subtensor(tokens)
+            start_idx = 0
+            for idx, token_chunk in enumerate(token_chunks):
+                token_chunk_len = len(token_chunk)
+                end_idx = start_idx + token_chunk_len
+                if idx > 0:
+                    start_idx += self.sep_len
+                    end_idx += self.sep_len
+                if start_idx >= num_falses:
+                    if make_key:
+                        yield (
+                            start_idx,
+                            end_idx,
+                            self._make_key_by_hash(
+                                self._hash_tokens(token_chunk), request_configs
+                            ),
+                        )
+                    else:
+                        yield start_idx, end_idx, self._hash_tokens(token_chunk)
+                start_idx = end_idx
+        elif hashes is not None:
+            assert offsets is not None, (
+                "If hashes are provided, offsets must also be provided."
+            )
+            start_idx = 0
+            for hash_val, offset in zip(hashes, offsets, strict=False):
+                end_idx = start_idx + offset
+                if make_key:
+                    yield (
+                        start_idx,
+                        end_idx,
+                        self._make_key_by_hash(hash_val, request_configs),
+                    )
+                else:
+                    yield start_idx, end_idx, hash_val
+                start_idx = end_idx
+        else:
+            raise ValueError("Either tokens or hashes must be provided.")
diff --git a/lmcache/v1/transfer_channel/__init__.py b/lmcache/v1/transfer_channel/__init__.py
new file mode 100644
index 0000000..b6a23d4
--- /dev/null
+++ b/lmcache/v1/transfer_channel/__init__.py
@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+
+# First Party
+from lmcache.v1.transfer_channel.abstract import BaseTransferChannel
+
+
+# TODO(Jiayi): Refactor this function when we support more channels.
+def CreateTransferChannel(
+    channel_type: str,
+    async_mode: bool,
+    role: str,
+    buffer_ptr: int,
+    buffer_size: int,
+    align_bytes: int,
+    tp_rank: int,
+    peer_init_url: str,
+    device: Optional[str] = None,
+    **kwargs,
+) -> BaseTransferChannel:
+    """
+    Create a transfer channel based on the specified channel type.
+    Supports "nixl" and "mock_memory" channel types.
+    If nixl is not available, automatically falls back to mock_memory
+    which is a mock implementation for testing purposes.
+
+    :param channel_type: Type of the transfer channel (e.g., "nixl", "mock_memory").
+    :param async_mode: Whether to operate in asynchronous mode.
+    :param role: Role of the channel (e.g., "both", "sender" or "receiver").
+    :param buffer_ptr: Pointer to the pre-allocated buffer.
+    :param buffer_size: Size of the pre-allocated buffer in bytes.
+    :param align_bytes: Alignment requirement in bytes.
+    :param tp_rank: Tensor parallel rank of the current process.
+    :param peer_init_url: Initialization URL for the peer.
+    :kwargs: Additional keyword arguments specific to the channel type.
+
+    :return: An instance of the specified transfer channel.
+    """
+
+    assert channel_type in ["nixl", "mock_memory"], (
+        f"Unsupported channel type: {channel_type}"
+    )
+
+    if channel_type == "nixl":
+        # First Party
+        from lmcache.v1.transfer_channel.nixl_channel import NixlChannel
+
+        assert "backends" in kwargs, (
+            "`backends` must be provided to create nixl transfer channel."
+        )
+        transfer_channel = NixlChannel(
+            async_mode=async_mode,
+            role=role,
+            buffer_ptr=buffer_ptr,
+            buffer_size=buffer_size,
+            align_bytes=align_bytes,
+            tp_rank=tp_rank,
+            peer_init_url=peer_init_url,
+            device=device,
+            **kwargs,
+        )
+        return transfer_channel
+
+    if channel_type == "mock_memory":
+        # First Party
+        from lmcache.v1.transfer_channel.mock_memory_channel import (
+            MockMemoryChannel,
+        )
+
+        mock_memory_channel: BaseTransferChannel = MockMemoryChannel(
+            async_mode=async_mode,
+            role=role,
+            buffer_ptr=buffer_ptr,
+            buffer_size=buffer_size,
+            align_bytes=align_bytes,
+            tp_rank=tp_rank,
+            peer_init_url=peer_init_url,
+            **kwargs,
+        )
+        return mock_memory_channel
+
+    raise ValueError(f"Unsupported channel type: {channel_type}")
diff --git a/lmcache/v1/transfer_channel/abstract.py b/lmcache/v1/transfer_channel/abstract.py
new file mode 100644
index 0000000..2878190
--- /dev/null
+++ b/lmcache/v1/transfer_channel/abstract.py
@@ -0,0 +1,285 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+import abc
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.transfer_channel.transfer_utils import (
+    InitSideMsgBase,
+    InitSideRetMsgBase,
+    P2PInitSideMsg,
+    P2PInitSideRetMsg,
+    SideMsg,
+)
+
+
+class BaseTransferChannel(metaclass=abc.ABCMeta):
+    ### Initialization-related functions ###
+    @abc.abstractmethod
+    def lazy_init_peer_connection(
+        self,
+        local_id: str,
+        peer_id: str,
+        peer_init_url: str,
+        init_side_msg: Optional[InitSideMsgBase] = None,
+    ) -> Optional[InitSideRetMsgBase]:
+        """
+        Lazily initialize the connection to a peer.
+
+        :param local_id: The ID of itself.
+        peer_id: The ID of the peer to connect to.
+        peer_init_url: The URL used to initialize the connection.
+        init_side_msg: An optional side message to be sent to the peer
+        during initialization.
+
+        :return: An optional side message received from the peer.
+        """
+
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def async_lazy_init_peer_connection(
+        self,
+        local_id: str,
+        peer_id: str,
+        peer_init_url: str,
+        init_side_msg: Optional[InitSideMsgBase] = None,
+    ) -> Optional[InitSideRetMsgBase]:
+        """
+        Async version of `lazy_init_peer_connection`.
+        """
+
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def remote_xfer_handler_exists(self, receiver_or_sender_id: str) -> bool:
+        """
+        Check if the remote transfer handler exists.
+
+        :param receiver_or_sender_id: The ID of the receiver or sender.
+
+        :return: True if the remote transfer handler exists, False otherwise.
+        """
+        raise NotImplementedError
+
+    def handle_init_side_msg(
+        self,
+        req: InitSideMsgBase,
+    ) -> InitSideRetMsgBase:
+        """
+        Handle side messages during initialization.
+
+        :param req: The initialization-related side message
+        received from the peer.
+
+        :return: A side message to be sent back to the peer.
+        """
+        if isinstance(req, P2PInitSideMsg):
+            assert hasattr(self, "peer_lookup_url"), (
+                "P2PInitSideMsg requires `peer_lookup_url` attribute."
+            )
+            return P2PInitSideRetMsg(
+                peer_lookup_url=self.peer_lookup_url,
+            )
+        else:
+            raise ValueError(f"Unsupported InitSideMsg type: {type(req)}")
+
+    def send_init_side_msg(
+        self,
+        init_tmp_socket: zmq.Socket,
+        init_side_msg: InitSideMsgBase,
+    ) -> InitSideRetMsgBase:
+        """
+        Send side messages during initialization.
+
+        :param socket: The ZMQ socket used for sending the message.
+        :param init_side_msg: The initialization-related side message
+        to be sent to the peer.
+
+        :return: A side message received from the peer.
+        """
+        init_msg_bytes = msgspec.msgpack.encode(init_side_msg)
+        init_tmp_socket.send(init_msg_bytes)
+
+        init_ret_msg_bytes = init_tmp_socket.recv()
+        init_ret_msg = msgspec.msgpack.decode(
+            init_ret_msg_bytes,
+            type=SideMsg,
+        )
+
+        return init_ret_msg
+
+    async def async_send_init_side_msg(
+        self,
+        init_tmp_socket: zmq.Socket,
+        init_side_msg: InitSideMsgBase,
+    ) -> InitSideRetMsgBase:
+        """
+        Async version of send_init_side_msg.
+        """
+        init_msg_bytes = msgspec.msgpack.encode(init_side_msg)
+        await init_tmp_socket.send(init_msg_bytes)
+
+        init_ret_msg_bytes = await init_tmp_socket.recv()
+        init_ret_msg = msgspec.msgpack.decode(
+            init_ret_msg_bytes,
+            type=SideMsg,
+        )
+
+        return init_ret_msg
+
+    ### Utility functions ###
+    @abc.abstractmethod
+    def get_local_mem_indices(
+        self, objects: Union[list[bytes], list[MemoryObj]]
+    ) -> list[int]:
+        """
+        Get the memory indices of objects.
+
+        :param objects: A list of bytes or MemoryObj to be checked.
+
+        :return: The memory indices of the objects.
+        """
+        raise NotImplementedError
+
+    ### Send and Recv must be called in pair ###
+    @abc.abstractmethod
+    def batched_send(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Send a batch of data through the channel.
+
+        :param objects: A list of bytes or MemoryObj to be sent.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_recv(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Receive a batch of data through the channel.
+
+        :param buffer: A list of bytes or MemoryObj to store the received data.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def async_batched_send(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Async send a batch of data through the channel.
+
+        :param objects: A list of bytes or MemoryObj to be sent.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def async_batched_recv(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Async receive a batch of data through the channel.
+
+        :param buffers: A list of bytes or MemoryObj to store the received data.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    ### Read and Write only need to be called on one side ###
+    @abc.abstractmethod
+    def batched_write(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Write a batch of data through the channel.
+
+        :param objects: A list of bytes or MemoryObj to be written.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def batched_read(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Read a batch of data through the channel.
+
+        :param buffers: A list of bytes or MemoryObj to store the read data.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def async_batched_write(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Async write a batch of data through the channel.
+
+        :param objects: A list of bytes or MemoryObj to be written.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def async_batched_read(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Async read a batch of data through the channel.
+
+        :param buffers: A list of bytes or MemoryObj to store the read data.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def close(self) -> None:
+        """
+        Close the transfer channel and release any resources.
+        """
+        raise NotImplementedError
diff --git a/lmcache/v1/transfer_channel/mock_memory_channel.py b/lmcache/v1/transfer_channel/mock_memory_channel.py
new file mode 100644
index 0000000..595f377
--- /dev/null
+++ b/lmcache/v1/transfer_channel/mock_memory_channel.py
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional, Union
+import asyncio
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.transfer_channel.py_socket_channel import PySocketChannel
+
+logger = init_logger(__name__)
+
+
+# Data plane: Global shared data store for simulating data transfer
+# within a single process. This is a process-local Python dict,
+# NOT shared across processes or machines.
+_GLOBAL_DATA_STORE: dict[str, dict[int, torch.Tensor]] = {}
+
+
+class MockMemoryChannel(PySocketChannel):
+    """
+    Mock memory-based transfer channel for single-process testing.
+
+    Control plane: Inherits ZMQ-based handshake from PySocketChannel.
+    Data plane: Uses global dict to simulate tensor transfer.
+
+    Only works within a single process. For production use NixlChannel.
+    """
+
+    def __init__(
+        self,
+        async_mode: bool = False,
+        **kwargs,
+    ):
+        super().__init__(async_mode=async_mode, **kwargs)
+
+    ############################################################
+    # Data plane: Override hook to initialize global data store
+    ############################################################
+    def _on_peer_connected(self, peer_url: str):
+        """Initialize data store when a peer connects"""
+        if peer_url not in _GLOBAL_DATA_STORE:
+            _GLOBAL_DATA_STORE[peer_url] = {}
+
+    ############################################################
+    # Data plane: Utility functions
+    ############################################################
+    def get_local_mem_indices(
+        self, objects: Union[list[bytes], list[MemoryObj]]
+    ) -> list[int]:
+        local_indices = []
+        if isinstance(objects[0], MemoryObj):
+            for mem_obj in objects:
+                assert isinstance(mem_obj, MemoryObj)
+                local_indices.append(mem_obj.meta.address)
+        elif isinstance(objects[0], bytes):
+            raise NotImplementedError(
+                "Sending raw bytes is not supported in MockMemoryChannel"
+            )
+        return local_indices
+
+    ############################################################
+    # Data plane: Send/Recv functions (not implemented)
+    ############################################################
+    def batched_send(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    def batched_recv(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    async def async_batched_send(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    async def async_batched_recv(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    ############################################################
+    # Data plane: Read/Write functions (global dict simulation)
+    ############################################################
+    def remote_xfer_handler_exists(self, receiver_or_sender_id: str) -> bool:
+        return True
+
+    def batched_write(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError("Sync mode not supported in MockMemoryChannel")
+
+    def batched_read(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError("Sync mode not supported in MockMemoryChannel")
+
+    async def async_batched_write(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """Write tensors to global dict to simulate data transfer"""
+        assert transfer_spec is not None
+
+        receiver_id = transfer_spec["receiver_id"]
+        remote_indexes = transfer_spec["remote_indexes"]
+
+        for obj, remote_idx in zip(objects, remote_indexes, strict=True):
+            if isinstance(obj, MemoryObj) and obj.tensor is not None:
+                if receiver_id not in _GLOBAL_DATA_STORE:
+                    _GLOBAL_DATA_STORE[receiver_id] = {}
+                _GLOBAL_DATA_STORE[receiver_id][remote_idx] = obj.tensor.clone()
+
+        await asyncio.sleep(0.001)
+        return len(objects)
+
+    async def async_batched_read(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """Read tensors from global dict to simulate data transfer"""
+        assert transfer_spec is not None
+
+        sender_id = transfer_spec["sender_id"]
+        remote_indexes = transfer_spec["remote_indexes"]
+
+        for buf, remote_idx in zip(buffers, remote_indexes, strict=True):
+            if isinstance(buf, MemoryObj) and buf.tensor is not None:
+                if (
+                    sender_id in _GLOBAL_DATA_STORE
+                    and remote_idx in _GLOBAL_DATA_STORE[sender_id]
+                ):
+                    buf.tensor.copy_(_GLOBAL_DATA_STORE[sender_id][remote_idx])
+
+        await asyncio.sleep(0.001)
+        return len(buffers)
diff --git a/lmcache/v1/transfer_channel/nixl_channel.py b/lmcache/v1/transfer_channel/nixl_channel.py
new file mode 100644
index 0000000..275b64c
--- /dev/null
+++ b/lmcache/v1/transfer_channel/nixl_channel.py
@@ -0,0 +1,688 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional, Union
+import asyncio
+import threading
+import time
+import uuid
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.memory_management import (
+    MemoryObj,
+)
+
+if TYPE_CHECKING:
+    # Third Party
+    from nixl._api import NixlAgent
+
+# First Party
+from lmcache.v1.rpc_utils import get_zmq_context, get_zmq_socket
+from lmcache.v1.transfer_channel.abstract import BaseTransferChannel
+from lmcache.v1.transfer_channel.transfer_utils import (
+    InitSideMsgBase,
+    InitSideRetMsgBase,
+    SideMsg,
+)
+
+logger = init_logger(__name__)
+
+
+class NixlMsgBase(msgspec.Struct, tag=True):
+    """Base class for all nixl-related messages"""
+
+    pass
+
+
+class NixlInitRequest(NixlMsgBase):
+    local_meta_bytes: bytes  # Metadata from the sender nixl agent
+
+
+class NixlMemRegRequest(NixlMsgBase):
+    remote_agent_name: bytes
+    local_id: str
+    local_xfer_dlist_bytes: bytes
+
+
+class NixlInitResponse(NixlMsgBase):
+    remote_agent_name: bytes
+    remote_meta_bytes: bytes  # Metadata from the receiver nixl agent
+
+
+class NixlMemRegResponse(NixlMsgBase):
+    remote_xfer_dlist_bytes: bytes  # Serialized transfer descriptors for the receiver
+
+
+NixlMsg = Union[
+    NixlInitRequest, NixlInitResponse, NixlMemRegRequest, NixlMemRegResponse
+]
+
+
+class NixlChannel(BaseTransferChannel):
+    def __init__(
+        self,
+        async_mode: bool = False,
+        device: Optional[str] = None,
+        **kwargs,
+    ):
+        assert "role" in kwargs
+        assert "buffer_ptr" in kwargs
+        assert "buffer_size" in kwargs
+        assert "align_bytes" in kwargs
+        assert "tp_rank" in kwargs
+        assert "peer_init_url" in kwargs
+
+        if "backends" in kwargs:
+            backends = kwargs["backends"]
+        else:
+            backends = ["UCX"]
+
+        self.role = kwargs["role"]
+
+        self.nixl_wrapper = NixlAgentWrapper(
+            buffer_ptr=kwargs["buffer_ptr"],
+            buffer_size=kwargs["buffer_size"],
+            page_size=kwargs["align_bytes"],
+            tp_rank=kwargs["tp_rank"],
+            backends=backends,
+            device=device,
+        )
+        self.nixl_agent = self.nixl_wrapper.agent
+
+        # Used for P2P
+        self.peer_lookup_url = kwargs.get("peer_lookup_url", None)
+
+        self.running = True
+        self.remote_xfer_handlers_dict: dict[
+            str, NixlAgent.nixl_prepped_dlist_handle
+        ] = {}
+
+        self.side_channels: list[zmq.Socket] = []
+        self.running_threads: list[threading.Thread] = []
+
+        self.async_mode = async_mode
+        if self.async_mode:
+            self.zmq_context = get_zmq_context(use_asyncio=True)
+        else:
+            self.zmq_context = get_zmq_context(use_asyncio=False)
+        self.peer_init_url = kwargs["peer_init_url"]
+        self.event_loop = kwargs.get("event_loop", None)
+
+        self._init_side_channels()
+
+    ############################################################
+    # Initialization functions
+    ############################################################
+    def lazy_init_peer_connection(
+        self,
+        local_id: str,
+        peer_id: str,
+        peer_init_url: str,
+        init_side_msg: Optional[InitSideMsgBase] = None,
+    ) -> Optional[InitSideRetMsgBase]:
+        # Initialize temporary socket for nixl initialization
+        init_tmp_socket = get_zmq_socket(
+            self.zmq_context,
+            peer_init_url,
+            "tcp",
+            zmq.REQ,
+            "connect",
+        )
+
+        # Build and send init request
+        nixl_init_req = NixlInitRequest(
+            local_meta_bytes=self.nixl_agent.get_agent_metadata(),
+        )
+        init_tmp_socket.send(msgspec.msgpack.encode(nixl_init_req))
+
+        # Wait remote agent metadata and register remote agent
+        nixl_init_resp_bytes = init_tmp_socket.recv()
+        nixl_init_resp = msgspec.msgpack.decode(nixl_init_resp_bytes, type=NixlMsg)
+        remote_meta_bytes = nixl_init_resp.remote_meta_bytes
+        remote_agent_name = self.nixl_agent.add_remote_agent(remote_meta_bytes)
+
+        # Register remote memory
+        local_xfer_dlist_bytes = self.nixl_agent.get_serialized_descs(
+            self.nixl_wrapper.xfer_descs
+        )
+        nixl_mem_reg_req = NixlMemRegRequest(
+            remote_agent_name=nixl_init_resp.remote_agent_name,
+            local_id=local_id,
+            local_xfer_dlist_bytes=local_xfer_dlist_bytes,
+        )
+        init_tmp_socket.send(msgspec.msgpack.encode(nixl_mem_reg_req))
+        nixl_mem_reg_resp_bytes = init_tmp_socket.recv()
+        nixl_mem_reg_resp = msgspec.msgpack.decode(
+            nixl_mem_reg_resp_bytes, type=NixlMsg
+        )
+
+        remote_xfer_dlist_bytes = nixl_mem_reg_resp.remote_xfer_dlist_bytes
+        remote_xfer_dlist = self.nixl_agent.deserialize_descs(remote_xfer_dlist_bytes)
+        remote_xfer_handlers = self.nixl_agent.prep_xfer_dlist(
+            remote_agent_name, remote_xfer_dlist
+        )
+        self.remote_xfer_handlers_dict[peer_id] = remote_xfer_handlers
+
+        # Send side message if any
+        init_ret_msg: Optional[InitSideRetMsgBase] = None
+        if init_side_msg is not None:
+            init_ret_msg = self.send_init_side_msg(
+                init_tmp_socket,
+                init_side_msg,
+            )
+
+        init_tmp_socket.close()
+        return init_ret_msg
+
+    async def async_lazy_init_peer_connection(
+        self,
+        local_id: str,
+        peer_id: str,
+        peer_init_url: str,
+        init_side_msg: Optional[InitSideMsgBase] = None,
+    ) -> Optional[InitSideRetMsgBase]:
+        # Initialize temporary socket for nixl initialization
+        init_tmp_socket = get_zmq_socket(
+            self.zmq_context,
+            peer_init_url,
+            "tcp",
+            zmq.REQ,
+            "connect",
+        )
+        # Build and send init request
+        nixl_init_req = NixlInitRequest(
+            local_meta_bytes=self.nixl_agent.get_agent_metadata(),
+        )
+        await init_tmp_socket.send(msgspec.msgpack.encode(nixl_init_req))
+        # Wait remote agent metadata and register remote agent
+        nixl_init_resp_bytes = await init_tmp_socket.recv()
+        nixl_init_resp = msgspec.msgpack.decode(nixl_init_resp_bytes, type=NixlMsg)
+        remote_meta_bytes = nixl_init_resp.remote_meta_bytes
+        remote_agent_name = self.nixl_agent.add_remote_agent(remote_meta_bytes)
+
+        # Register remote memory
+        local_xfer_dlist_bytes = self.nixl_agent.get_serialized_descs(
+            self.nixl_wrapper.xfer_descs
+        )
+        nixl_mem_reg_req = NixlMemRegRequest(
+            remote_agent_name=nixl_init_resp.remote_agent_name,
+            local_id=local_id,
+            local_xfer_dlist_bytes=local_xfer_dlist_bytes,
+        )
+
+        await init_tmp_socket.send(msgspec.msgpack.encode(nixl_mem_reg_req))
+        nixl_mem_reg_resp_bytes = await init_tmp_socket.recv()
+        nixl_mem_reg_resp = msgspec.msgpack.decode(
+            nixl_mem_reg_resp_bytes, type=NixlMsg
+        )
+
+        remote_xfer_dlist_bytes = nixl_mem_reg_resp.remote_xfer_dlist_bytes
+        remote_xfer_dlist = self.nixl_agent.deserialize_descs(remote_xfer_dlist_bytes)
+        remote_xfer_handlers = self.nixl_agent.prep_xfer_dlist(
+            remote_agent_name, remote_xfer_dlist
+        )
+        self.remote_xfer_handlers_dict[peer_id] = remote_xfer_handlers
+
+        # Send side message if any
+        init_ret_msg: Optional[InitSideRetMsgBase] = None
+        if init_side_msg is not None:
+            init_ret_msg = await self.async_send_init_side_msg(
+                init_tmp_socket,
+                init_side_msg,
+            )
+
+        init_tmp_socket.close()
+        return init_ret_msg
+
+    def remote_xfer_handler_exists(self, receiver_or_sender_id: str) -> bool:
+        return receiver_or_sender_id in self.remote_xfer_handlers_dict
+
+    def _init_side_channels(self):
+        if self.peer_init_url is None:
+            return
+
+        if self.async_mode:
+            # Start listening coroutine for initialization side channel
+            asyncio.run_coroutine_threadsafe(self._async_init_loop(), self.event_loop)
+        else:
+            # Start listening thread for initialization side channel
+            self.init_thread = threading.Thread(target=self._init_loop, daemon=True)
+            self.init_thread.start()
+            self.running_threads.append(self.init_thread)
+
+    def _handle_init_msg(
+        self, req: Union[NixlMsg, InitSideMsgBase]
+    ) -> Union[NixlMsg, InitSideRetMsgBase]:
+        resp: Union[NixlMsg, InitSideRetMsgBase]
+        if isinstance(req, NixlInitRequest):
+            agent_name = self.nixl_agent.add_remote_agent(req.local_meta_bytes)
+
+            resp = NixlInitResponse(
+                remote_agent_name=agent_name,
+                remote_meta_bytes=self.nixl_agent.get_agent_metadata(),
+            )
+
+            logger.info("Replying initialization response")
+
+        elif isinstance(req, NixlMemRegRequest):
+            local_xfer_descs = self.nixl_agent.get_serialized_descs(
+                self.nixl_wrapper.xfer_descs
+            )
+
+            remote_xfer_dlist_bytes = req.local_xfer_dlist_bytes
+            remote_xfer_dlist = self.nixl_agent.deserialize_descs(
+                remote_xfer_dlist_bytes
+            )
+            remote_xfer_handlers = self.nixl_agent.prep_xfer_dlist(
+                req.remote_agent_name, remote_xfer_dlist
+            )
+            self.remote_xfer_handlers_dict[req.local_id] = remote_xfer_handlers
+
+            resp = NixlMemRegResponse(
+                remote_xfer_dlist_bytes=local_xfer_descs,
+            )
+
+            logger.info("Replying mem register response")
+        elif isinstance(req, InitSideMsgBase):
+            resp = self.handle_init_side_msg(req)
+            logger.info("Replying P2P init side response")
+        else:
+            raise ValueError(f"Unsupported InitMsg type: {type(req)}")
+
+        return resp
+
+    def _init_loop(self):
+        # Initialize initialization side channels
+        self.init_side_channel = get_zmq_socket(
+            self.zmq_context,
+            self.peer_init_url,
+            "tcp",
+            zmq.REP,
+            "bind",
+        )
+        self.side_channels.append(self.init_side_channel)
+
+        # NOTE: Initialization has to be two stages:
+        # (1) Exchanging the metadata.
+        # (2) Registering the memory descriptors.
+        # Otherwise, there's a chance that nixl got stuck
+        # (handle always give "PROC" status) during the first request.
+        # (3) Exchanging side messages if any. This depends on the backend
+        # that uses the channel.
+        while self.running:
+            try:
+                req_bytes = self.init_side_channel.recv()
+
+                logger.info("Received initialization request")
+
+                req = msgspec.msgpack.decode(req_bytes, type=Union[NixlMsg, SideMsg])
+
+                resp = self._handle_init_msg(req)
+
+                self.init_side_channel.send(msgspec.msgpack.encode(resp))
+
+            except Exception as e:
+                logger.error("Failed to process initialization loop: %s", str(e))
+                if self.running:
+                    time.sleep(0.01)
+
+    async def _async_init_loop(self):
+        # Initialize initialization side channels
+        self.init_side_channel = get_zmq_socket(
+            self.zmq_context,
+            self.peer_init_url,
+            "tcp",
+            zmq.REP,
+            "bind",
+        )
+        self.side_channels.append(self.init_side_channel)
+        logger.info("Starting async initialization loop")
+
+        while self.running:
+            try:
+                req_bytes = await self.init_side_channel.recv()
+
+                logger.info("Received initialization request")
+
+                req = msgspec.msgpack.decode(req_bytes, type=Union[NixlMsg, SideMsg])
+
+                resp = self._handle_init_msg(req)
+
+                await self.init_side_channel.send(msgspec.msgpack.encode(resp))
+
+            except Exception as e:
+                logger.error("Failed to process initialization loop: %s", str(e))
+                if self.running:
+                    time.sleep(0.01)
+
+    ############################################################
+    # Utility functions
+    ############################################################
+
+    def get_local_mem_indices(
+        self, objects: Union[list[bytes], list[MemoryObj]]
+    ) -> list[int]:
+        local_indices = []
+        if isinstance(objects[0], MemoryObj):
+            for mem_obj in objects:
+                assert isinstance(mem_obj, MemoryObj)
+                local_indices.append(mem_obj.meta.address)
+        elif isinstance(objects[0], bytes):
+            raise NotImplementedError(
+                "Sending raw bytes is not supported in NIXL channel"
+            )
+        return local_indices
+
+    ############################################################
+    # Send/Recv functions
+    ############################################################
+
+    ### Send and Recv must be called in pair ###
+    def batched_send(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    def batched_recv(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    async def async_batched_send(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    async def async_batched_recv(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        raise NotImplementedError
+
+    ############################################################
+    # Read/Write functions
+    ############################################################
+
+    ### Read and Write only need to be called on one side ###
+    def batched_write(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Write a batch of data through the nixl channel.
+
+        :param objects: A list of bytes or MemoryObj to be written.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: Number of successfully transferred objects.
+        """
+        assert transfer_spec is not None
+
+        handle = self.nixl_agent.make_prepped_xfer(
+            "WRITE",
+            self.nixl_wrapper.xfer_handler,
+            self.get_local_mem_indices(objects),
+            self.remote_xfer_handlers_dict[transfer_spec["receiver_id"]],
+            transfer_spec["remote_indexes"],
+        )
+
+        self.nixl_agent.transfer(handle)
+
+        # TODO(Jiayi) tune hyperparameters
+        wait_time = 0.001
+        while True:
+            status = self.nixl_agent.check_xfer_state(handle)
+            logger.debug(f"Transfer status: {status}")
+
+            if status == "ERR":
+                logger.error("Error in send operation")
+                raise RuntimeError("Failed to send objects to remote peer")
+            elif status == "PROC":
+                time.sleep(wait_time)  # Avoid busy waiting
+                continue
+            assert status == "DONE", f"Transfer status is {status}, expected DONE"
+            # self._proxy_side_channel.send(notif_msg_bytes)
+            break
+
+        return len(objects)
+
+    def batched_read(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Read a batch of data from a remote peer through the nixl channel.
+
+        This is the reverse of batched_write: the local side initiates a READ
+        from the remote peer's memory into local buffers.
+
+        :param buffers: A list of MemoryObj to store the read data.
+        :param transfer_spec: Must contain 'sender_id' and 'remote_indexes'.
+
+        :return: Number of successfully transferred objects.
+        """
+        assert transfer_spec is not None
+
+        handle = self.nixl_agent.make_prepped_xfer(
+            "READ",
+            self.nixl_wrapper.xfer_handler,
+            self.get_local_mem_indices(buffers),
+            self.remote_xfer_handlers_dict[transfer_spec["sender_id"]],
+            transfer_spec["remote_indexes"],
+        )
+
+        self.nixl_agent.transfer(handle)
+
+        # Poll for completion
+        wait_time = 0.001
+        while True:
+            status = self.nixl_agent.check_xfer_state(handle)
+            logger.debug(f"Read transfer status: {status}")
+
+            if status == "ERR":
+                logger.error("Error in read operation")
+                raise RuntimeError("Failed to read objects from remote peer")
+            elif status == "PROC":
+                time.sleep(wait_time)
+                continue
+            assert status == "DONE", f"Transfer status is {status}, expected DONE"
+            break
+
+        return len(buffers)
+
+    async def async_batched_write(
+        self,
+        objects: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Write a batch of data through the channel.
+
+        :param objects: A list of bytes or MemoryObj to be written.
+        :param transfer_spec: Additional specifications for the transfer.
+            Should contain 'receiver_id' and 'remote_indexes'.
+
+        :return: Number of successfully transferred objects.
+        """
+
+        assert transfer_spec is not None
+
+        handle = self.nixl_agent.make_prepped_xfer(
+            "WRITE",
+            self.nixl_wrapper.xfer_handler,
+            self.get_local_mem_indices(objects),
+            self.remote_xfer_handlers_dict[transfer_spec["receiver_id"]],
+            transfer_spec["remote_indexes"],
+        )
+        self.nixl_agent.transfer(handle)
+
+        # TODO(Jiayi) tune hyperparameters
+        wait_time = 0.001
+        while True:
+            status = self.nixl_agent.check_xfer_state(handle)
+            logger.debug(f"Transfer status: {status}")
+
+            if status == "ERR":
+                logger.error("Error in send operation")
+                raise RuntimeError("Failed to send objects to remote peer")
+            elif status == "PROC":
+                await asyncio.sleep(wait_time)  # Avoid busy waiting
+                continue
+            assert status == "DONE", f"Transfer status is {status}, expected DONE"
+            # self._proxy_side_channel.send(notif_msg_bytes)
+            break
+        return len(objects)
+
+    async def async_batched_read(
+        self,
+        buffers: Union[list[bytes], list[MemoryObj]],
+        transfer_spec: Optional[dict] = None,
+    ) -> int:
+        """
+        Read a batch of data through the channel.
+
+        :param buffers: A list of bytes or MemoryObj to store the read data.
+        :param transfer_spec: Additional specifications for the transfer.
+
+        :return: True if the send operation is successful.
+        """
+
+        assert transfer_spec is not None
+
+        handle = self.nixl_agent.make_prepped_xfer(
+            "READ",
+            self.nixl_wrapper.xfer_handler,
+            self.get_local_mem_indices(buffers),
+            self.remote_xfer_handlers_dict[transfer_spec["sender_id"]],
+            transfer_spec["remote_indexes"],
+        )
+        self.nixl_agent.transfer(handle)
+
+        # TODO(Jiayi) tune hyperparameters
+        wait_time = 0.001
+        while True:
+            status = self.nixl_agent.check_xfer_state(handle)
+            logger.debug(f"Transfer status: {status}")
+
+            if status == "ERR":
+                logger.error("Error in send operation")
+                raise RuntimeError("Failed to send objects to remote peer")
+            elif status == "PROC":
+                await asyncio.sleep(wait_time)  # Avoid busy waiting
+                continue
+            assert status == "DONE", f"Transfer status is {status}, expected DONE"
+            # self._proxy_side_channel.send(notif_msg_bytes)
+            break
+        return len(buffers)
+
+    ############################################################
+    # Cleanup-related functions
+    ############################################################
+
+    def close(self):
+        self.running = False
+        for thread in self.running_threads:
+            thread.join()
+        self.zmq_context.term()
+        self.nixl_agent.deregister_memory(self.nixl_wrapper.reg_descs)
+        self.nixl_agent.release_dlist_handle(self.nixl_wrapper.xfer_handler)
+
+        for remote_xfer_handler in self.remote_xfer_handlers_dict.values():
+            self.nixl_agent.release_dlist_handle(remote_xfer_handler)
+
+
+@dataclass
+class NixlAgentWrapper:
+    agent: "NixlAgent"
+    reg_descs: Any
+    xfer_descs: Any
+    xfer_handler: Any
+
+    def __init__(
+        self,
+        buffer_ptr: int,
+        buffer_size: int,
+        page_size: int,
+        tp_rank: int,
+        backends: list[str],
+        device: Optional[str] = None,
+    ):
+        """
+        Initialize the NIXL agent.
+
+        Args:
+            buffer_size (int): The size of the buffer.
+            buffer_ptr (int): The pointer to the buffer.
+            page_size (int): The page size of NIXL and
+                the lmcache memory allocator.
+            tp_rank (int): The tensor parallel rank.
+            backends (list[str]): The list of backends to use.
+
+        Returns:
+            NixlWrapper: The NIXL agent.
+            reg_dlist: the registered memory descriptor list.
+            xfer_dlist: the local transfer descriptor list.
+            prepped_xfer_handler: the prepped transfer handler.
+        """
+        try:
+            # Third Party
+            from nixl._api import nixl_agent as NixlAgent
+            from nixl._api import nixl_agent_config
+        except ImportError as err:
+            raise RuntimeError("NIXL is not available") from err
+
+        # Handle None backends by setting default to ["UCX"]
+        if backends is None:
+            backends = ["UCX"]
+
+        # Create a NIXL agent
+        nixl_agent = NixlAgent(
+            str(uuid.uuid4()),
+            nixl_agent_config(backends=backends),
+        )
+
+        # Register the memory
+        # The four fields are (base_addr, length, dev_id, meta_info)
+        # https://github.com/ai-dynamo/nixl/blob/main/src/api/cpp/nixl_descriptors.h#L152
+        memory_desc = [(buffer_ptr, buffer_size, tp_rank, "")]
+        _VRAM_DEVICE_TYPES = {"cuda", "xpu", "hpu"}
+
+        device_type = str(device).split(":")[0]
+        if device_type == "cpu":
+            mem_type = "cpu"
+        elif device_type in _VRAM_DEVICE_TYPES:
+            mem_type = "VRAM"
+        else:
+            raise ValueError(
+                f"Unsupported device type '{device_type}' for NIXL. "
+                f"Supported accelerators: {_VRAM_DEVICE_TYPES}"
+            )
+
+        reg_descs = nixl_agent.get_reg_descs(memory_desc, mem_type=mem_type)
+        nixl_agent.register_memory(reg_descs)
+
+        # Create xfer handlers
+        xfer_desc = []
+        for base_addr in range(buffer_ptr, buffer_ptr + buffer_size, page_size):
+            xfer_desc.append((base_addr, page_size, tp_rank))
+
+        xfer_descs = nixl_agent.get_xfer_descs(xfer_desc, mem_type=mem_type)
+        xfer_handler = nixl_agent.prep_xfer_dlist("", xfer_descs, mem_type=mem_type)
+        self.agent = nixl_agent
+        self.reg_descs = reg_descs
+        self.xfer_descs = xfer_descs
+        self.xfer_handler = xfer_handler
diff --git a/lmcache/v1/transfer_channel/py_socket_channel.py b/lmcache/v1/transfer_channel/py_socket_channel.py
new file mode 100644
index 0000000..2beaabb
--- /dev/null
+++ b/lmcache/v1/transfer_channel/py_socket_channel.py
@@ -0,0 +1,260 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# TODO(baoloongmao): This module contains the control plane implementation
+# for socket-based channels. Currently, it provides the base class with
+# ZMQ-based handshake and initialization logic. In the future, this can
+# be extended to a complete channel with data plane using native sockets.
+
+# Standard
+from typing import Optional, Union
+import asyncio
+import threading
+import time
+
+# Third Party
+import msgspec
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.rpc_utils import get_zmq_context, get_zmq_socket
+from lmcache.v1.transfer_channel.abstract import BaseTransferChannel
+from lmcache.v1.transfer_channel.transfer_utils import (
+    InitSideMsgBase,
+    InitSideRetMsgBase,
+    SideMsg,
+)
+
+logger = init_logger(__name__)
+
+
+class PySocketMsgBase(msgspec.Struct, tag=True):
+    """Base class for all py-socket-related messages"""
+
+    pass
+
+
+class PySocketInitRequest(PySocketMsgBase):
+    """Initialization request, peer_init_url is used as peer identifier"""
+
+    peer_init_url: str
+
+
+class PySocketInitResponse(PySocketMsgBase):
+    """Initialization response"""
+
+    status: str
+
+
+PySocketMsg = Union[
+    PySocketInitRequest,
+    PySocketInitResponse,
+]
+
+
+class PySocketChannel(BaseTransferChannel):
+    """
+    Base class for socket-based transfer channels.
+
+    Control plane: Uses ZMQ sockets for handshake and initialization.
+    Data plane: To be implemented by subclasses.
+
+    Provides common control plane logic for different channel types.
+    """
+
+    def __init__(
+        self,
+        async_mode: bool = False,
+        **kwargs,
+    ):
+        assert "role" in kwargs
+        assert "buffer_ptr" in kwargs
+        assert "buffer_size" in kwargs
+        assert "align_bytes" in kwargs
+        assert "tp_rank" in kwargs
+        assert "peer_init_url" in kwargs
+
+        self.role = kwargs["role"]
+        self.buffer_ptr = kwargs["buffer_ptr"]
+        self.buffer_size = kwargs["buffer_size"]
+        self.align_bytes = kwargs["align_bytes"]
+        self.tp_rank = kwargs["tp_rank"]
+
+        self.peer_lookup_url = kwargs.get("peer_lookup_url", None)
+
+        self.running = True
+        self.remote_connections: dict[str, dict] = {}
+
+        self.side_channel: Optional[zmq.Socket] = None
+        self.running_threads: list[threading.Thread] = []
+
+        self.async_mode = async_mode
+        if self.async_mode:
+            self.zmq_context = get_zmq_context(use_asyncio=True)
+        else:
+            self.zmq_context = get_zmq_context(use_asyncio=False)
+        self.peer_init_url = kwargs["peer_init_url"]
+        self.event_loop = kwargs.get("event_loop", None)
+
+        self._init_side_channels()
+
+    ############################################################
+    # Control plane: Initialization functions
+    ############################################################
+
+    def lazy_init_peer_connection(
+        self,
+        local_id: str,
+        peer_id: str,
+        peer_init_url: str,
+        init_side_msg: Optional[InitSideMsgBase] = None,
+    ) -> Optional[InitSideRetMsgBase]:
+        raise NotImplementedError("Sync mode not supported in PySocketChannel")
+
+    async def async_lazy_init_peer_connection(
+        self,
+        local_id: str,
+        peer_id: str,
+        peer_init_url: str,
+        init_side_msg: Optional[InitSideMsgBase] = None,
+    ) -> Optional[InitSideRetMsgBase]:
+        """
+        Initialize connection to a peer using ZMQ sockets for handshake.
+
+        Note: peer_id is expected to be peer_init_url in this implementation.
+        """
+        init_tmp_socket = get_zmq_socket(
+            self.zmq_context,
+            peer_init_url,
+            "tcp",
+            zmq.REQ,
+            "connect",
+        )
+
+        init_req = PySocketInitRequest(peer_init_url=self.peer_init_url)
+        await init_tmp_socket.send(msgspec.msgpack.encode(init_req))
+
+        init_resp_bytes = await init_tmp_socket.recv()
+        _ = msgspec.msgpack.decode(init_resp_bytes, type=PySocketMsg)
+
+        self.remote_connections[peer_id] = {
+            "peer_init_url": peer_init_url,
+        }
+
+        init_ret_msg: Optional[InitSideRetMsgBase] = None
+        if init_side_msg is not None:
+            init_ret_msg = await self.async_send_init_side_msg(
+                init_tmp_socket,
+                init_side_msg,
+            )
+
+        init_tmp_socket.close()
+        return init_ret_msg
+
+    def _init_side_channels(self):
+        """Initialize side channel for handling incoming connections"""
+        if self.peer_init_url is None:
+            return
+
+        self.side_channel = get_zmq_socket(
+            self.zmq_context,
+            self.peer_init_url,
+            "tcp",
+            zmq.REP,
+            "bind",
+        )
+
+        if self.async_mode:
+            asyncio.run_coroutine_threadsafe(self._async_init_loop(), self.event_loop)
+        else:
+            self.init_thread = threading.Thread(target=self._init_loop, daemon=True)
+            self.init_thread.start()
+            self.running_threads.append(self.init_thread)
+
+    def _handle_init_msg(
+        self, req: Union[PySocketMsg, InitSideMsgBase]
+    ) -> Union[PySocketMsg, InitSideRetMsgBase]:
+        """Handle initialization messages from peers"""
+        resp: Union[PySocketMsg, InitSideRetMsgBase]
+        if isinstance(req, PySocketInitRequest):
+            peer_url = req.peer_init_url
+
+            self.remote_connections[peer_url] = {
+                "peer_init_url": peer_url,
+            }
+
+            self._on_peer_connected(peer_url)
+
+            resp = PySocketInitResponse(status="ok")
+            logger.info("Replying initialization response")
+
+        elif isinstance(req, InitSideMsgBase):
+            resp = self.handle_init_side_msg(req)
+            logger.info("Replying P2P init side response")
+        else:
+            raise ValueError(f"Unsupported InitMsg type: {type(req)}")
+
+        return resp
+
+    def _on_peer_connected(self, peer_url: str):
+        """Hook for subclasses to perform additional setup when a peer connects"""
+        pass
+
+    def _init_loop(self):
+        """Synchronous initialization loop for handling incoming connections"""
+        while self.running:
+            try:
+                req_bytes = self.side_channel.recv()
+
+                logger.info("Received initialization request")
+
+                req = msgspec.msgpack.decode(
+                    req_bytes, type=Union[PySocketMsg, SideMsg]
+                )
+
+                resp = self._handle_init_msg(req)
+
+                self.side_channel.send(msgspec.msgpack.encode(resp))
+
+            except Exception as e:
+                logger.error("Failed to process initialization loop: %s", str(e))
+                if self.running:
+                    time.sleep(0.01)
+
+    async def _async_init_loop(self):
+        """Asynchronous initialization loop for handling incoming connections"""
+        logger.info("Starting async initialization loop")
+
+        while self.running:
+            try:
+                req_bytes = await self.side_channel.recv()
+
+                logger.info("Received initialization request")
+
+                req = msgspec.msgpack.decode(
+                    req_bytes, type=Union[PySocketMsg, SideMsg]
+                )
+
+                resp = self._handle_init_msg(req)
+
+                await self.side_channel.send(msgspec.msgpack.encode(resp))
+
+            except Exception as e:
+                logger.error("Failed to process initialization loop: %s", str(e))
+                if self.running:
+                    await asyncio.sleep(0.01)
+
+    ############################################################
+    # Cleanup-related functions
+    ############################################################
+
+    def close(self):
+        """Close all sockets and cleanup resources"""
+        self.running = False
+        for thread in self.running_threads:
+            thread.join()
+
+        if self.side_channel is not None:
+            self.side_channel.close()
+
+        self.zmq_context.term()
diff --git a/lmcache/v1/transfer_channel/transfer_utils.py b/lmcache/v1/transfer_channel/transfer_utils.py
new file mode 100644
index 0000000..085e6df
--- /dev/null
+++ b/lmcache/v1/transfer_channel/transfer_utils.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Union
+
+# Third Party
+import msgspec
+
+
+def get_correct_device(device: str, worker_id: int) -> str:
+    """
+    Get the correct device based on the given device string.
+
+    Args:
+        device (str): The device string, could be cpu or the accelerator type.
+        worker_id (int): The worker id to determine the accelerator device.
+
+    Returns:
+        str: The correct device string with device id.
+    """
+    if device == "cpu":
+        return "cpu"
+    base_device = device.split(":")[0]
+    return f"{base_device}:{worker_id}"
+
+
+class SideMsgBase(msgspec.Struct, tag=True):
+    """Base class for all side-related messages during initialization"""
+
+    pass
+
+
+# Side messages during initialization
+class InitSideMsgBase(SideMsgBase):
+    """Base class for all side-related messages during initialization"""
+
+    pass
+
+
+class P2PInitSideMsg(InitSideMsgBase):
+    """P2P specific initialization message"""
+
+    pass
+
+
+# Side return messages during initialization
+class InitSideRetMsgBase(SideMsgBase):
+    """Base class for all side-related messages during initialization"""
+
+    pass
+
+
+class P2PInitSideRetMsg(InitSideRetMsgBase):
+    """P2P specific initialization return message"""
+
+    peer_lookup_url: str
+
+
+SideMsg = Union[
+    P2PInitSideMsg,
+    P2PInitSideRetMsg,
+]
diff --git a/lmcache/v1/utils/__init__.py b/lmcache/v1/utils/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/lmcache/v1/utils/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/lmcache/v1/utils/bloom_filter.py b/lmcache/v1/utils/bloom_filter.py
new file mode 100644
index 0000000..ee739b0
--- /dev/null
+++ b/lmcache/v1/utils/bloom_filter.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Union
+import array
+import hashlib
+import math
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+class BloomFilter:
+    """Bloom Filter for memory-efficient."""
+
+    def __init__(
+        self, expected_elements: int = 1000000, false_positive_rate: float = 0.01
+    ):
+        self.size = self._optimal_size(expected_elements, false_positive_rate)
+        self.hash_count = self._optimal_hash_count(self.size, expected_elements)
+        array_size = (self.size + 31) // 32
+        self.bit_array = array.array("I", [0] * array_size)
+        self.item_count = 0
+        self.expected_elements = expected_elements
+        self.false_positive_rate = false_positive_rate
+
+    @staticmethod
+    def _optimal_size(n: int, p: float) -> int:
+        return int(-(n * math.log(p)) / (math.log(2) ** 2))
+
+    @staticmethod
+    def _optimal_hash_count(m: int, n: int) -> int:
+        return max(1, int((m / n) * math.log(2)))
+
+    def _hashes(self, item: Union[str, int]) -> list[int]:
+        result = []
+        if isinstance(item, int):
+            for i in range(self.hash_count):
+                h = hashlib.sha256(
+                    item.to_bytes((item.bit_length() + 7) // 8, "big", signed=False)
+                    + i.to_bytes(4, "big")
+                ).digest()
+                result.append(int.from_bytes(h[:4], "big") % self.size)
+        else:
+            for i in range(self.hash_count):
+                h = hashlib.sha256(f"{item}_{i}".encode()).digest()
+                result.append(int.from_bytes(h[:4], "big") % self.size)
+        return result
+
+    def add(self, item: Union[str, int]) -> None:
+        for pos in self._hashes(item):
+            self.bit_array[pos >> 5] |= 1 << (pos & 31)
+        self.item_count += 1
+
+    def add_batch_with_hashes_and_check(self, positions_list: list[list[int]]) -> int:
+        """Add multiple sets of hash positions and return count of new items.
+
+        Args:
+            positions_list: List of lists, where each inner list contains
+            hash positions for one item
+
+        Returns:
+            Number of new items that were actually added
+        """
+        unique_count = 0
+        for positions in positions_list:
+            is_new = any(
+                not (self.bit_array[pos >> 5] & (1 << (pos & 31))) for pos in positions
+            )
+            if is_new:
+                for pos in positions:
+                    self.bit_array[pos >> 5] |= 1 << (pos & 31)
+                unique_count += 1
+        self.item_count += unique_count
+        return unique_count
+
+    def contains(self, item: Union[str, int]) -> bool:
+        for pos in self._hashes(item):
+            if not (self.bit_array[pos >> 5] & (1 << (pos & 31))):
+                return False
+        return True
+
+    def clear(self) -> None:
+        self.bit_array = array.array("I", [0] * ((self.size + 31) // 32))
+        self.item_count = 0
+
+    def get_memory_usage_bytes(self) -> int:
+        return self.size // 8
+
+    def get_bit_set(self) -> int:
+        return sum(val.bit_count() for val in self.bit_array)
+
+    def get_fill_rate(self) -> float:
+        bits_set = self.get_bit_set()
+        return bits_set / self.size if self.size > 0 else 0.0
+
+    def get_statistics(self) -> dict:
+        bits_set = self.get_bit_set()
+        return {
+            "size_mb": self.get_memory_usage_bytes() / 1024 / 1024,
+            "hash_count": self.hash_count,
+            "item_count": self.item_count,
+            "bits_set": bits_set,
+            "fill_rate": bits_set / self.size if self.size > 0 else 0.0,
+            "expected_elements": self.expected_elements,
+            "false_positive_rate": self.false_positive_rate,
+        }
diff --git a/lmcache/v1/utils/cache_utils.py b/lmcache/v1/utils/cache_utils.py
new file mode 100644
index 0000000..c18300a
--- /dev/null
+++ b/lmcache/v1/utils/cache_utils.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Callable, Generic, Optional, TypeVar
+import threading
+import time
+
+T = TypeVar("T")
+
+
+class TTLListCache(Generic[T]):
+    """
+    Generic list cache with TTL (Time-To-Live) support.
+
+    This cache stores a list of items of type T and automatically refreshes
+    when the cache expires.
+    """
+
+    def __init__(self, timeout_seconds: float = 30.0):
+        """
+        Initialize the cache.
+
+        Args:
+            timeout_seconds: Default TTL in seconds for cache entries.
+        """
+        self.cache: list[T] = []
+        self.cache_time: float = 0.0
+        self.cache_lock = threading.Lock()
+        self.timeout_seconds = timeout_seconds
+
+    def get_cached(
+        self,
+        get_fresh_data: Callable[[], list[T]],
+        timeout_override: Optional[float] = None,
+    ) -> list[T]:
+        """
+        Get cached data, refreshing if expired.
+
+        Args:
+            get_fresh_data: Function to get fresh data when cache is expired
+            timeout_override: Optional timeout override in seconds.
+                If None, use instance timeout_seconds.
+                If 0: cache immediately expires, always get fresh data and update cache.
+                If > 0: use specified timeout.
+
+        Returns:
+            List of cached items, either from cache or fresh data
+        """
+        current_time = time.time()
+
+        # Fast path: check cache without lock
+        if not self.is_expired(timeout_override, current_time):
+            return self.cache
+
+        # Slow path: refresh cache with lock
+        with self.cache_lock:
+            # Double-check after acquiring lock
+            if not self.is_expired(timeout_override, current_time):
+                return self.cache
+
+            # Refresh cache
+            self.cache = get_fresh_data()
+            self.cache_time = current_time
+            return self.cache
+
+    def clear(self) -> None:
+        """Clear the cache."""
+        with self.cache_lock:
+            self.cache.clear()
+            self.cache_time = 0.0
+
+    def is_expired(
+        self,
+        timeout_override: Optional[float] = None,
+        current_time: Optional[float] = None,
+    ) -> bool:
+        """
+        Check if the cache is expired without refreshing it.
+
+        Args:
+            timeout_override: Optional timeout override in seconds.
+                If None, use instance timeout_seconds.
+                If 0: always considered expired.
+                If > 0: use specified timeout.
+            current_time: Optional current time. If None, use time.time().
+
+        Returns:
+            True if cache is expired or uninitialized, False otherwise
+        """
+        if self.cache_time == 0.0:
+            return True
+
+        effective_timeout = (
+            timeout_override if timeout_override is not None else self.timeout_seconds
+        )
+        if current_time is None:
+            current_time = time.time()
+
+        return current_time - self.cache_time >= effective_timeout
+
+    def get_cache_age(self) -> float:
+        """
+        Get the age of the cache in seconds.
+
+        Returns:
+            Age in seconds. Returns float('inf') if cache is uninitialized.
+        """
+        if self.cache_time == 0.0:
+            return float("inf")
+        return time.time() - self.cache_time
+
+    def __len__(self) -> int:
+        """Get the number of items in cache (without checking expiration)."""
+        return len(self.cache)
+
+    def __repr__(self) -> str:
+        """String representation of the cache."""
+        age = self.get_cache_age()
+        if age == float("inf"):
+            age_str = "uninitialized"
+        else:
+            age_str = f"{age:.2f}s old"
+        return (
+            f"TTLListCache(cache_items={len(self)}, age={age_str}, "
+            f"timeout={self.timeout_seconds}s)"
+        )
diff --git a/lmcache/v1/utils/json_utils.py b/lmcache/v1/utils/json_utils.py
new file mode 100644
index 0000000..96f07b8
--- /dev/null
+++ b/lmcache/v1/utils/json_utils.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared helpers for serializing arbitrary Python values to
+JSON-compatible structures.
+
+These utilities are used by HTTP API endpoints and runtime
+plugin launchers that need to emit server configs (which are
+dataclasses potentially containing non-JSON-native values) as
+plain JSON payloads.
+"""
+
+# Standard
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+
+def make_json_safe(obj: Any) -> Any:
+    """Recursively convert ``obj`` into a JSON-serializable value.
+
+    Dicts, lists and tuples are traversed; primitive JSON types are
+    returned unchanged; any other value falls back to ``str(obj)``.
+
+    Args:
+        obj: Arbitrary Python object to sanitize.
+
+    Returns:
+        A value composed solely of ``dict`` / ``list`` /
+        ``str`` / ``int`` / ``float`` / ``bool`` / ``None``.
+
+    Exceptions:
+        None.
+    """
+    if isinstance(obj, dict):
+        return {k: make_json_safe(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [make_json_safe(v) for v in obj]
+    if isinstance(obj, (str, int, float, bool, type(None))):
+        return obj
+    return str(obj)
+
+
+def safe_asdict(obj: Any) -> dict[str, Any]:
+    """Convert a dataclass instance to a JSON-safe ``dict``.
+
+    Args:
+        obj: A dataclass instance.
+
+    Returns:
+        Dictionary with all fields recursively sanitized via
+        :func:`make_json_safe`.
+
+    Exceptions:
+        TypeError: If ``obj`` is not a dataclass instance.
+    """
+    if not is_dataclass(obj) or isinstance(obj, type):
+        raise TypeError("Expected a dataclass instance, got %s" % type(obj).__name__)
+    return make_json_safe(asdict(obj))  # type: ignore[return-value]
diff --git a/lmcache/v1/utils/router_discovery.py b/lmcache/v1/utils/router_discovery.py
new file mode 100644
index 0000000..8d7304d
--- /dev/null
+++ b/lmcache/v1/utils/router_discovery.py
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+from typing import Iterable, List, Optional
+import importlib
+import pkgutil
+
+# Third Party
+from fastapi import APIRouter
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+
+def discover_api_routers(
+    search_path: Path,
+    package_name: str,
+    suffix: str = "_api",
+    exclude: Optional[Iterable[str]] = None,
+) -> List[APIRouter]:
+    """Scan *search_path* for modules whose name ends with *suffix*
+    and return every ``router`` attribute that is an
+    :class:`~fastapi.APIRouter`.
+
+    Args:
+        search_path: Filesystem directory to scan.
+        package_name: Fully-qualified Python package name that
+            corresponds to *search_path* (used by
+            :func:`importlib.import_module`).
+        suffix: Only modules whose name ends with this string
+            are considered.  Defaults to ``"_api"``.
+        exclude: Optional iterable of module base names to skip
+            (e.g. ``{"run_script_api"}``).  Useful when a host
+            package only wants a subset of the available routers.
+
+    Returns:
+        A list of discovered :class:`~fastapi.APIRouter` instances.
+    """
+    excluded = set(exclude or ())
+    routers: List[APIRouter] = []
+    for _, module_name, _ in pkgutil.iter_modules([str(search_path)]):
+        if not module_name.endswith(suffix):
+            continue
+        if module_name in excluded:
+            logger.info("Skipping excluded API module: %s", module_name)
+            continue
+        full_name = f"{package_name}.{module_name}"
+        module = importlib.import_module(full_name)
+        if hasattr(module, "router") and isinstance(module.router, APIRouter):
+            routers.append(module.router)
+            logger.info("Discovered API module: %s", module_name)
+    return routers
diff --git a/lmcache/v1/utils/subclass_discovery.py b/lmcache/v1/utils/subclass_discovery.py
new file mode 100644
index 0000000..804dd8c
--- /dev/null
+++ b/lmcache/v1/utils/subclass_discovery.py
@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Generic helper for plugin-style auto-discovery of concrete subclasses.
+
+This module centralises the boilerplate that several packages used to
+duplicate (CLI commands, controller-benchmark handlers, lookup-client
+record strategies, health-monitor checks, remote connector adapters,
+...).  Each of those packages walks its own submodules with
+``pkgutil.iter_modules``, imports them, then iterates classes via
+``inspect.getmembers`` to locate concrete subclasses of a given base
+class.  ``discover_subclasses`` captures that pattern in a single
+well-tested place so callers stay tiny and behave consistently.
+"""
+
+# Standard
+from types import ModuleType
+from typing import Callable, Iterator, Optional, Sequence, TypeVar, Union
+import importlib
+import inspect
+import pkgutil
+
+# First Party
+from lmcache.logging import init_logger
+
+logger = init_logger(__name__)
+
+T = TypeVar("T")
+
+# Sentinel meaning "scan recursively without any depth limit".
+_UNLIMITED = 0
+
+
+def _resolve_package(package: Union[ModuleType, str]) -> ModuleType:
+    if isinstance(package, str):
+        return importlib.import_module(package)
+    return package
+
+
+def _normalize_levels(levels: Optional[Sequence[int]]) -> tuple[int, int]:
+    """Normalize the ``levels`` argument to a ``(min_depth, max_depth)``
+    pair. ``max_depth == 0`` is the sentinel for "no upper bound".
+
+    Accepted forms:
+
+    * ``None``                          -> ``(1, 1)`` (legacy behavior).
+    * ``[]`` or ``[0, 0]``              -> ``(1, 0)`` -> unlimited depth.
+    * ``[lo, hi]`` with ``1 <= lo <= hi`` -> ``(lo, hi)``.
+
+    Any other shape raises ``ValueError`` so misconfigurations surface
+    immediately at the call site instead of silently scanning the wrong
+    set of modules.
+    """
+    if levels is None:
+        return 1, 1
+    if len(levels) == 0:
+        return 1, _UNLIMITED
+    if len(levels) != 2:
+        raise ValueError(
+            "levels must be either None, an empty sequence, or a "
+            "two-element sequence [min, max]; got %r" % (list(levels),)
+        )
+    lo, hi = int(levels[0]), int(levels[1])
+    if lo == 0 and hi == 0:
+        return 1, _UNLIMITED
+    if lo < 1 or hi < 1 or lo > hi:
+        raise ValueError(
+            "levels must satisfy 1 <= min <= max (or be [0, 0] for "
+            "unlimited); got %r" % (list(levels),)
+        )
+    return lo, hi
+
+
+def discover_subclasses(
+    package: Union[ModuleType, str],
+    base_class: type[T],
+    *,
+    module_filter: Optional[Callable[[str], bool]] = None,
+    include_abstract: bool = False,
+    require_defined_in_module: bool = True,
+    on_import_error: Optional[Callable[[str, Exception], None]] = None,
+    levels: Optional[Sequence[int]] = None,
+) -> Iterator[type[T]]:
+    """Yield concrete subclasses of *base_class* found by walking the
+    submodules of *package*.
+
+    Each subclass is yielded **at most once**, even when re-exported
+    from several modules.
+
+    Args:
+        package: The package to scan, either as a module object or its
+            fully-qualified dotted name.
+        base_class: The base class whose concrete subclasses to collect.
+        module_filter: Optional predicate over the *short* module name
+            (i.e. without the package prefix).  Modules for which the
+            predicate returns ``False`` are skipped.  Sub-packages are
+            still descended into so a deep scan can keep filtering by
+            leaf module name.  Defaults to ``None`` which keeps every
+            module.
+        include_abstract: When ``False`` (default) classes with
+            unimplemented abstract methods are skipped.
+        require_defined_in_module: When ``True`` (default) classes that
+            were merely imported (re-exported) into a module are
+            ignored; only classes whose ``__module__`` matches the
+            module being scanned are yielded.  Set to ``False`` to keep
+            the historical behaviour of accepting re-exported classes.
+        on_import_error: Optional callback invoked as
+            ``on_import_error(full_module_name, exc)`` when a submodule
+            fails to import.  When omitted the error is logged at
+            ``warning`` level and discovery proceeds with the next
+            module.
+        levels: Optional ``[min_depth, max_depth]`` window controlling
+            which levels of submodules contribute classes.  *package*
+            itself is depth ``0``; its direct submodules are depth
+            ``1``; etc.  ``None`` (default) and ``[1, 1]`` are
+            equivalent and only inspect direct children -- the
+            historical behavior.  ``[1, 2]`` inspects direct children
+            and grand-children, ``[2, 2]`` only the grand-children, and
+            ``[]`` / ``[0, 0]`` recurse without any depth limit.
+            A sub-package's ``__init__.py`` is scanned at the depth
+            where the sub-package itself sits (e.g. ``bench/__init__.py``
+            is depth 1), matching the pre-levels behavior where
+            sub-packages were treated as ordinary modules.
+
+    Raises:
+        TypeError: If *package* is not a real package (no ``__path__``).
+        ValueError: If *levels* is malformed; see :func:`_normalize_levels`.
+    """
+    pkg = _resolve_package(package)
+    pkg_path = getattr(pkg, "__path__", None)
+    if pkg_path is None:
+        raise TypeError(
+            "discover_subclasses requires a package (with __path__), got %r" % (pkg,)
+        )
+
+    min_depth, max_depth = _normalize_levels(levels)
+    seen: set[type] = set()
+
+    def _walk(
+        current_pkg: ModuleType,
+        current_path: Sequence[str],
+        depth: int,
+    ) -> Iterator[type[T]]:
+        # Stop descending once we are past the requested upper bound.
+        if max_depth != _UNLIMITED and depth > max_depth:
+            return
+
+        def _scan_module(module: ModuleType) -> Iterator[type[T]]:
+            """Yield classes from *module* that match all filters."""
+            for _, obj in inspect.getmembers(module, inspect.isclass):
+                try:
+                    if not issubclass(obj, base_class) or obj is base_class:
+                        continue
+                except TypeError:
+                    # typing.GenericAlias (e.g. ``list[Foo]``) passes
+                    # inspect.isclass on Python < 3.12 but issubclass
+                    # raises on ABCs; skip silently.
+                    continue
+                if not include_abstract and inspect.isabstract(obj):
+                    continue
+                if require_defined_in_module and (obj.__module__ != module.__name__):
+                    continue
+                if obj in seen:
+                    continue
+                seen.add(obj)
+                yield obj
+
+        for _, short_name, is_pkg in pkgutil.iter_modules(current_path):
+            full_name = "%s.%s" % (current_pkg.__name__, short_name)
+            if is_pkg:
+                # Recurse into sub-packages so their leaf modules can
+                # still be reached.  The sub-package ``__init__.py`` is
+                # also scanned at the current depth -- this preserves
+                # the pre-levels behaviour where sub-package init files
+                # were treated just like ordinary leaf modules.
+                can_scan_init = depth >= min_depth and (
+                    max_depth == _UNLIMITED or depth <= max_depth
+                )
+                can_recurse = max_depth == _UNLIMITED or depth + 1 <= max_depth
+                if not can_scan_init and not can_recurse:
+                    continue
+                try:
+                    sub_pkg = importlib.import_module(full_name)
+                except Exception as exc:
+                    _report_import_error(full_name, exc)
+                    continue
+                sub_path = getattr(sub_pkg, "__path__", None)
+                if sub_path is None:
+                    continue
+                if can_scan_init:
+                    if module_filter is None or module_filter(short_name):
+                        yield from _scan_module(sub_pkg)
+                if can_recurse:
+                    yield from _walk(sub_pkg, sub_path, depth + 1)
+                continue
+
+            # Leaf module: apply depth window + caller's name filter.
+            if depth < min_depth:
+                continue
+            if max_depth != _UNLIMITED and depth > max_depth:
+                continue
+            if module_filter is not None and not module_filter(short_name):
+                continue
+            try:
+                module = importlib.import_module(full_name)
+            except Exception as exc:
+                _report_import_error(full_name, exc)
+                continue
+            yield from _scan_module(module)
+
+    def _report_import_error(full_name: str, exc: Exception) -> None:
+        if on_import_error is not None:
+            on_import_error(full_name, exc)
+        else:
+            logger.warning(
+                "Failed to import module %s during subclass discovery: %s",
+                full_name,
+                exc,
+            )
+
+    yield from _walk(pkg, pkg_path, depth=1)
diff --git a/operator/.custom-gcl.yml b/operator/.custom-gcl.yml
new file mode 100644
index 0000000..6ef11b3
--- /dev/null
+++ b/operator/.custom-gcl.yml
@@ -0,0 +1,11 @@
+# This file configures golangci-lint with module plugins.
+# When you run 'make lint', it will automatically build a custom golangci-lint binary
+# with all the plugins listed below.
+#
+# See: https://golangci-lint.run/plugins/module-plugins/
+version: v2.8.0
+plugins:
+  # logcheck validates structured logging calls and parameters (e.g., balanced key-value pairs)
+  - module: "sigs.k8s.io/logtools"
+    import: "sigs.k8s.io/logtools/logcheck/gclplugin"
+    version: latest
diff --git a/operator/.devcontainer/devcontainer.json b/operator/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..985ea0a
--- /dev/null
+++ b/operator/.devcontainer/devcontainer.json
@@ -0,0 +1,35 @@
+{
+  "name": "Kubebuilder DevContainer",
+  "image": "golang:1.25",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "moby": false,
+      "dockerDefaultAddressPool": "base=172.30.0.0/16,size=24"
+    },
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "upgradePackages": true
+    }
+  },
+
+  "runArgs": ["--privileged", "--init"],
+
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "terminal.integrated.shell.linux": "/bin/bash"
+      },
+      "extensions": [
+        "ms-kubernetes-tools.vscode-kubernetes-tools",
+        "ms-azuretools.vscode-docker"
+      ]
+    }
+  },
+
+  "remoteEnv": {
+    "GO111MODULE": "on"
+  },
+
+  "onCreateCommand": "bash operator/.devcontainer/post-install.sh"
+}
+
diff --git a/operator/.devcontainer/post-install.sh b/operator/.devcontainer/post-install.sh
new file mode 100644
index 0000000..6d75a49
--- /dev/null
+++ b/operator/.devcontainer/post-install.sh
@@ -0,0 +1,153 @@
+#!/bin/bash
+set -euo pipefail
+
+echo "===================================="
+echo "Kubebuilder DevContainer Setup"
+echo "===================================="
+
+# Verify running as root (required for installing to /usr/local/bin and /etc)
+if [ "$(id -u)" -ne 0 ]; then
+  echo "ERROR: This script must be run as root"
+  exit 1
+fi
+
+echo ""
+echo "Detecting system architecture..."
+# Detect architecture using uname
+MACHINE=$(uname -m)
+case "${MACHINE}" in
+  x86_64)
+    ARCH="amd64"
+    ;;
+  aarch64|arm64)
+    ARCH="arm64"
+    ;;
+  *)
+    echo "WARNING: Unsupported architecture ${MACHINE}, defaulting to amd64"
+    ARCH="amd64"
+    ;;
+esac
+echo "Architecture: ${ARCH}"
+
+echo ""
+echo "------------------------------------"
+echo "Setting up bash completion..."
+echo "------------------------------------"
+
+BASH_COMPLETIONS_DIR="/usr/share/bash-completion/completions"
+
+# Enable bash-completion in root's .bashrc (devcontainer runs as root)
+if ! grep -q "source /usr/share/bash-completion/bash_completion" ~/.bashrc 2>/dev/null; then
+  echo 'source /usr/share/bash-completion/bash_completion' >> ~/.bashrc
+  echo "Added bash-completion to .bashrc"
+fi
+
+echo ""
+echo "------------------------------------"
+echo "Installing development tools..."
+echo "------------------------------------"
+
+# Install kind
+if ! command -v kind &> /dev/null; then
+  echo "Installing kind..."
+  curl -Lo /usr/local/bin/kind "https://kind.sigs.k8s.io/dl/latest/kind-linux-${ARCH}"
+  chmod +x /usr/local/bin/kind
+  echo "kind installed successfully"
+fi
+
+# Generate kind bash completion
+if command -v kind &> /dev/null; then
+  if kind completion bash > "${BASH_COMPLETIONS_DIR}/kind" 2>/dev/null; then
+    echo "kind completion installed"
+  else
+    echo "WARNING: Failed to generate kind completion"
+  fi
+fi
+
+# Install kubebuilder
+if ! command -v kubebuilder &> /dev/null; then
+  echo "Installing kubebuilder..."
+  curl -Lo /usr/local/bin/kubebuilder "https://go.kubebuilder.io/dl/latest/linux/${ARCH}"
+  chmod +x /usr/local/bin/kubebuilder
+  echo "kubebuilder installed successfully"
+fi
+
+# Generate kubebuilder bash completion
+if command -v kubebuilder &> /dev/null; then
+  if kubebuilder completion bash > "${BASH_COMPLETIONS_DIR}/kubebuilder" 2>/dev/null; then
+    echo "kubebuilder completion installed"
+  else
+    echo "WARNING: Failed to generate kubebuilder completion"
+  fi
+fi
+
+# Install kubectl
+if ! command -v kubectl &> /dev/null; then
+  echo "Installing kubectl..."
+  KUBECTL_VERSION=$(curl -Ls https://dl.k8s.io/release/stable.txt)
+  curl -Lo /usr/local/bin/kubectl "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/${ARCH}/kubectl"
+  chmod +x /usr/local/bin/kubectl
+  echo "kubectl installed successfully"
+fi
+
+# Generate kubectl bash completion
+if command -v kubectl &> /dev/null; then
+  if kubectl completion bash > "${BASH_COMPLETIONS_DIR}/kubectl" 2>/dev/null; then
+    echo "kubectl completion installed"
+  else
+    echo "WARNING: Failed to generate kubectl completion"
+  fi
+fi
+
+# Generate Docker bash completion
+if command -v docker &> /dev/null; then
+  if docker completion bash > "${BASH_COMPLETIONS_DIR}/docker" 2>/dev/null; then
+    echo "docker completion installed"
+  else
+    echo "WARNING: Failed to generate docker completion"
+  fi
+fi
+
+echo ""
+echo "------------------------------------"
+echo "Configuring Docker environment..."
+echo "------------------------------------"
+
+# Wait for Docker to be ready
+echo "Waiting for Docker to be ready..."
+for i in {1..30}; do
+  if docker info >/dev/null 2>&1; then
+    echo "Docker is ready"
+    break
+  fi
+  if [ "$i" -eq 30 ]; then
+    echo "WARNING: Docker not ready after 30s"
+  fi
+  sleep 1
+done
+
+# Create kind network (ignore if already exists)
+if ! docker network inspect kind >/dev/null 2>&1; then
+  if docker network create kind >/dev/null 2>&1; then
+    echo "Created kind network"
+  else
+    echo "WARNING: Failed to create kind network (may already exist)"
+  fi
+fi
+
+echo ""
+echo "------------------------------------"
+echo "Verifying installations..."
+echo "------------------------------------"
+kind version
+kubebuilder version
+kubectl version --client
+docker --version
+go version
+
+echo ""
+echo "===================================="
+echo "DevContainer ready!"
+echo "===================================="
+echo "All development tools installed successfully."
+echo "You can now start building Kubernetes operators."
diff --git a/operator/.dockerignore b/operator/.dockerignore
new file mode 100644
index 0000000..9af8280
--- /dev/null
+++ b/operator/.dockerignore
@@ -0,0 +1,11 @@
+# More info: https://docs.docker.com/engine/reference/builder/#dockerignore-file
+# Ignore everything by default and re-include only needed files
+**
+
+# Re-include Go source files (but not *_test.go)
+!**/*.go
+**/*_test.go
+
+# Re-include Go module files
+!go.mod
+!go.sum
diff --git a/operator/.golangci.yml b/operator/.golangci.yml
new file mode 100644
index 0000000..f966bb1
--- /dev/null
+++ b/operator/.golangci.yml
@@ -0,0 +1,61 @@
+version: "2"
+run:
+  allow-parallel-runners: true
+linters:
+  default: none
+  enable:
+    - copyloopvar
+    - dupl
+    - errcheck
+    - ginkgolinter
+    - goconst
+    - gocyclo
+    - govet
+    - ineffassign
+    - lll
+    - modernize
+    - misspell
+    - nakedret
+    - prealloc
+    - revive
+    - staticcheck
+    - unconvert
+    - unparam
+    - unused
+    - logcheck
+  settings:
+    custom:
+      logcheck:
+        type: "module"
+        description: Checks Go logging calls for Kubernetes logging conventions.
+    revive:
+      rules:
+        - name: comment-spacings
+        - name: import-shadowing
+    modernize:
+      disable:
+        - omitzero
+  exclusions:
+    generated: lax
+    rules:
+      - linters:
+          - lll
+        path: api/*
+      - linters:
+          - dupl
+          - lll
+        path: internal/*
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+formatters:
+  enable:
+    - gofmt
+    - goimports
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
diff --git a/operator/.pre-commit-config.yaml b/operator/.pre-commit-config.yaml
new file mode 100644
index 0000000..954e5f4
--- /dev/null
+++ b/operator/.pre-commit-config.yaml
@@ -0,0 +1,32 @@
+# Pre-commit hooks for the operator (Go).
+# These are NOT part of the repo-root pre-commit config so that
+# non-operator contributors don't need Go installed.
+#
+# Operator devs: install with "cd operator && make install-hooks"
+# Run manually: pre-commit run --all-files -c operator/.pre-commit-config.yaml
+
+repos:
+  - repo: local
+    hooks:
+      - id: gofmt
+        name: gofmt
+        entry: gofmt -l -d
+        language: system
+        types: [go]
+        files: ^operator/
+
+      - id: go-vet
+        name: go vet
+        entry: bash -c 'cd operator && go vet ./...'
+        language: system
+        types: [go]
+        files: ^operator/
+        pass_filenames: false
+
+      - id: golangci-lint
+        name: golangci-lint
+        entry: bash -c 'cd operator && "$(git rev-parse --show-toplevel)/operator/bin/golangci-lint" run --timeout 5m'
+        language: system
+        types: [go]
+        files: ^operator/
+        pass_filenames: false
diff --git a/operator/AGENTS.md b/operator/AGENTS.md
new file mode 100644
index 0000000..30c2b36
--- /dev/null
+++ b/operator/AGENTS.md
@@ -0,0 +1,628 @@
+# operator - AI Agent Guide
+
+## Smoke Test Suite
+
+The smoke suite under `test/e2e/` validates the operator end-to-end against
+a real Kubernetes cluster. It is all-Go, built on Ginkgo/Gomega, and gated
+by Go build tags so unit tests run without it.
+
+### Naming convention
+
+Targets follow a consistent `-kind` / `-cluster` suffix:
+
+| Suffix | What it means |
+|---|---|
+| `-kind` | Self-contained: the target creates a fresh Kind cluster, runs the suite, and deletes the cluster on exit. |
+| `-cluster` | Uses whatever cluster the current `KUBECONFIG` / context points at (OpenShift, EKS, k3s, an existing Kind cluster, …). Requires `IMG=` pointing at a registry the cluster can pull from. |
+
+### Targets (M1, no-GPU)
+
+```bash
+make test-e2e-kind                                                                  # local Kind, ~5 min
+make test-e2e-cluster IMG=<registry>/<repo>:<tag>                                   # existing cluster
+```
+
+### Targets (M2, GPU)
+
+```bash
+make test-e2e-gpu-kind                                                              # local Kind, ~30 min
+make test-e2e-gpu-cluster IMG=<registry>/<repo>:<tag>                               # existing GPU cluster
+```
+
+Both run the M1 + M2 specs (M2 = runtime `/conf` round-trip + vLLM
+integration, under the `e2e_gpu` build tag). Pick `test-e2e-gpu-kind`
+when you have GPUs on the dev box and want a self-contained Kind
+cluster; pick `test-e2e-gpu-cluster` when you're targeting an
+existing OpenShift / EKS / GKE GPU cluster. See *GPU tier* below for
+details.
+
+#### `test-e2e-kind` — local Kind run
+
+Builds the manager image, loads it into a dedicated Kind cluster
+(`operator-test-e2e-<id>` by default), installs CRDs, deploys the controller,
+runs every `//go:build e2e` spec under `test/e2e/`, then tears the
+cluster down. No prereqs beyond Kind + Docker on `$PATH` (plus network
+egress to GitHub).
+
+The suite installs **cert-manager** into the cluster before deploying the
+controller — it issues the mutating webhook's serving cert and injects the
+CA bundle (see `config/certmanager`), so the controller-manager Deployment
+never reaches `Available` without it. Install is skipped when the cluster
+already ships cert-manager (e.g. an existing OpenShift/EKS cluster), and
+the suite only uninstalls what it installed. Override the release with
+`CERT_MANAGER_VERSION` (default `v1.16.3`).
+
+#### `test-e2e-cluster` — existing cluster (OpenShift, EKS, k3s, …)
+
+For when you already have a cluster running and just want the suite to
+install/deploy → test → undeploy against it. Prereqs:
+
+1. **Image pushed to a reachable registry.** The cluster nodes must be
+   able to `docker pull` `$IMG`. On OpenShift the simplest path is the
+   internal registry — see *Pushing to OpenShift's internal registry*
+   below.
+2. **`KUBECONFIG` / current-context** points at the target cluster.
+3. Pass the in-cluster pull URL via `IMG=`. The target fails fast if
+   `IMG` is missing or still the default `controller:latest`.
+
+```bash
+oc config use-context admin                                                          # or kubectl config use-context <name>
+export IMG=image-registry.openshift-image-registry.svc:5000/lmcache-operator-system/operator:v0.0.1
+make test-e2e-cluster IMG=$IMG
+```
+
+Under the hood this sets `SMOKE_SKIP_IMAGE_LOAD=true` so the suite
+neither rebuilds nor `kind load`s. The cluster is left intact after
+the run.
+
+#### Pushing to OpenShift's internal registry
+
+```bash
+# One-time per cluster: expose the registry on a default route
+oc patch configs.imageregistry.operator.openshift.io/cluster \
+  --type merge -p '{"spec":{"defaultRoute":true}}'
+
+# Log Docker into the registry using your oc session
+oc registry login --to=$HOME/.docker/config.json --skip-check
+
+# Build, tag, push
+oc create namespace lmcache-operator-system --dry-run=client -o yaml | oc apply -f -
+export OCP_REGISTRY=$(oc get route default-route -n openshift-image-registry -o jsonpath='{.spec.host}')
+make docker-build IMG=controller:latest
+docker tag controller:latest $OCP_REGISTRY/lmcache-operator-system/operator:v0.0.1
+docker push                  $OCP_REGISTRY/lmcache-operator-system/operator:v0.0.1
+```
+
+The push uses the external route; pods inside the cluster pull via the
+in-cluster service name (`image-registry.openshift-image-registry.svc:5000/...`).
+Both names point at the same image; only the hostnames differ.
+
+#### OpenShift caveats
+
+- **PodSecurity admission**: test namespaces are pre-labeled
+  `pod-security.kubernetes.io/enforce=privileged` so the operator's
+  DaemonSet (which always sets `hostIPC=true`, and `privileged=true` only
+  when `spec.privileged` is enabled) is accepted at admission time.
+  `hostIPC=true` alone is rejected by the `baseline`/`restricted` profiles,
+  so the label is required regardless of `privileged`. Harmless on clusters
+  that don't enforce PodSecurity.
+- **SCC (Security Context Constraints)**: M1 smokes never wait for
+  DaemonSet pods to schedule, so SCC isn't a blocker. If you need pods
+  to actually run later (M2/M3 GPU tier), grant the LMCache
+  ServiceAccount the `privileged` SCC explicitly.
+
+### Specs included in M1
+
+| Spec file | Coverage |
+|---|---|
+| `crd_smoke_test.go` | harness sanity check + minimal-CR shape + custom-port propagation |
+| `lifecycle_smoke_test.go` | port update propagation, delete + ownerRef GC, invalid `sizeGB` rejection |
+| `field_coverage_smoke_test.go` | ServiceMonitor (auto-skipped if CRD absent), `extraArgs` override, `resourceOverrides` |
+| `auth_smoke_test.go` | cross-namespace `authSecretRef` mirroring + env-var injection |
+
+### Specs included in M2 (GPU, build tag `e2e_gpu`)
+
+| Spec file | Coverage |
+|---|---|
+| `runtime_smoke_test.go` | HTTP `/conf` round-trip — proves CR field values reach the live LMCache server (not just the K8s objects) by asserting `mp.port` / `mp.chunk_size` / `mp.max_workers` / `mp.hash_algorithm` / `http.http_port` against the running pod's `/conf` payload. |
+| `vllm_integration_smoke_test.go` | vLLM + LMCache round-trip — spins up a vLLM `Deployment` configured against the operator's `<engine>-connection` ConfigMap with `--no-enable-prefix-caching`, sends the same long prompt twice, and asserts `lmcache:num_hit_tokens` on the LMCache `/metrics` endpoint increments on the second call. |
+| `cacheblend_integration_smoke_test.go` | vLLM + CacheBlendEngine round-trip — reconciles a `CacheBlendEngine` (blend server DaemonSet), creates an args-only vLLM `Deployment` that opts into CacheBlend injection (label `lmcache.ai/cacheblend-inject` + engine annotation), and asserts: the mutating webhook stamped `cacheblend-injected=true` and injected `--attention-backend CUSTOM`; vLLM logs the CUSTOM backend banner and serves `/v1/models`; the engine logs `Registered CB rope state for instance N` after a completion; the completion returns HTTP 200. Pulls the PRIVATE payload image via a `dockerconfigjson` Secret built from `CACHEBLEND_REGISTRY_USER`/`CACHEBLEND_REGISTRY_TOKEN` — **Skips** if those are unset. |
+
+### Prerequisites
+
+What you need to install / configure before each target. The "Host
+config" column is **only needed once per host** — subsequent runs
+reuse it. Detailed rationale for each item lives in the per-target
+sections below; this table is the quick-reference.
+
+| Target | Tools | Host config | Cluster reqs |
+|---|---|---|---|
+| `test-e2e-kind` | `kind`, `kubectl`, `docker` | — | (cluster created fresh) |
+| `test-e2e-cluster` | `kubectl` | — | `KUBECONFIG` → target cluster; pass `IMG=` (registry the cluster can pull from) |
+| `test-e2e-gpu-kind` | `kind`, `kubectl`, `docker`, `helm` | NVIDIA driver + `nvidia-container-toolkit` installed, **plus** the two `nvidia-ctk` commands below | (cluster created fresh) |
+| `test-e2e-gpu-cluster` | `kubectl`, `helm` | — | `KUBECONFIG` → GPU cluster; GPU node labeled `nvidia.com/gpu.present=true`; `nvidia` `RuntimeClass` installed; pass `IMG=` |
+
+#### Tool install hints
+
+```bash
+# kind
+go install sigs.k8s.io/kind/cmd/kind@latest
+
+# kubectl   — distro-specific; e.g. `curl -LO https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl`
+# helm v3   — https://helm.sh/docs/intro/install/
+# docker    — distro-specific
+```
+
+#### GPU host one-time setup (only for `test-e2e-gpu-kind`)
+
+```bash
+# Configure docker to default to the nvidia runtime, then toggle the
+# volume-mount-marker mechanism the inline Kind config uses to inject
+# GPUs into the worker container. Restart docker once at the end.
+sudo nvidia-ctk runtime configure --runtime=docker --set-as-default --cdi.enabled
+sudo nvidia-ctk config --set accept-nvidia-visible-devices-as-volume-mounts=true --in-place
+sudo systemctl restart docker
+```
+
+The target fails fast with a copy-pasteable fix command if either
+piece of host config is missing.
+
+**Not needed**: `nvkind`. An earlier iteration used it; the current
+target uses the NVIDIA GPU Operator instead and gets GPU passthrough
+via an inline Kind config. See `make/e2e-gpu.mk` for the rationale.
+
+### Helper library (`test/utils/`)
+
+| File | Purpose |
+|---|---|
+| `lmc.go` | `ApplyLMC`, `WaitLMCReconciled`, `WaitLMCPhase`, `WaitLMCReady`, `GetConnectionConfig` (typed parser), `PatchLMCSpec`, `DeleteLMCAndWaitGC` |
+| `portforward.go` | `PortForward(spec, ports...)` — wraps `kubectl port-forward`, waits for the local port to accept TCP |
+| `fixtures.go` | `go:embed`-backed fixture/golden loader |
+| `runner.go` | `RunMake` / `RunFromOperator` — runs commands from the operator/ root **without** `os.Chdir` |
+| `utils.go` | Legacy exec helpers retained for the kubebuilder-template Manager spec |
+
+### Adding a new smoke spec
+
+1. Drop the YAML under `test/utils/fixtures/<name>.yaml`.
+2. Use `utils.NewLMCFromFixture(...)` to load and override `name`/`namespace`.
+3. Call the helpers above; do **not** call `os.Chdir` or read paths
+   relative to the working directory — fixtures resolve via `go:embed`,
+   and shell commands accept their working directory through `cmd.Dir`.
+4. Wrap the spec body with `recordOnFailure(nsName)` in `AfterEach` so
+   failures dump controller logs, events, pod descriptions, and the CR yaml.
+
+### GPU tier (M2)
+
+Two entry points share the same `e2e_gpu`-tagged specs:
+
+#### `test-e2e-gpu-kind` — self-contained Kind cluster
+
+Best when you have GPUs on the dev box and don't want to wire up an
+external cluster. The target hand-rolls a Kind cluster config that
+mounts `/dev/null` at `/var/run/nvidia-container-devices/all` in the
+worker — combined with the host setup below,
+nvidia-container-runtime sees that marker and injects all GPU
+devices + driver libraries into the Kind worker container. Then the
+target installs the
+[NVIDIA GPU Operator](https://github.com/NVIDIA/gpu-operator), which
+runs a toolkit daemonset that installs nvidia-container-toolkit
+*inside the Kind node* and registers a `nvidia` containerd runtime
+handler. After that, pods with `runtimeClassName: nvidia` (which the
+LMCache DaemonSet and the test-side vLLM Deployment already use)
+get NVML / libcuda injected. The cluster is auto-deleted on exit —
+same trap pattern as `test-e2e-kind`. All in-cluster manifests
+(including the Kind config) are inlined into the Makefile.
+
+We explored several alternatives before settling on GPU Operator:
+the bare device plugin alone fails with `Failed to initialize NVML:
+ERROR_LIBRARY_NOT_FOUND` because pods scheduled by Kind's inner
+containerd don't inherit the worker's library mounts; manually
+apt-installing the toolkit via `docker exec` works but breaks if
+the kindest/node image changes; nvkind didn't reliably produce
+GPU-passthrough markers on the target host. GPU Operator does the
+toolkit install as a Kubernetes-native DaemonSet, which is the most
+robust path. Trade-off: helm install takes ~10 min (operator +
+ClusterPolicy + 5 daemonsets), versus ~30 s for the bare plugin
+when it works.
+
+Host one-time setup (NOT automated):
+
+```bash
+# 1. NVIDIA driver + nvidia-container-toolkit installed (distro-specific).
+
+# 2. Configure docker + nvidia-container-runtime:
+sudo nvidia-ctk runtime configure --runtime=docker --set-as-default --cdi.enabled
+sudo nvidia-ctk config --set accept-nvidia-visible-devices-as-volume-mounts=true --in-place
+sudo systemctl restart docker
+
+# 3. helm + kubectl + kind on PATH.
+```
+
+Then:
+
+```bash
+make test-e2e-gpu-kind
+```
+
+The Makefile target fails fast with a copy-pasteable fix command if
+either `Default Runtime: nvidia` is missing from `docker info` or
+`accept-nvidia-visible-devices-as-volume-mounts=true` is missing
+from `/etc/nvidia-container-runtime/config.toml`.
+
+Single-node is intentional: the LMCache DaemonSet and the test-side
+vLLM Deployment both schedule onto the same (only) worker, which is
+what the kv-cache transfer needs anyway (hostIPC + cudaIPC require
+colocation).
+
+**Side effect of step 2 to be aware of**: after the flip, every
+docker container on the host — not just Kind workers — starts
+through nvidia-container-runtime. Non-GPU workloads still work but
+go through one extra hook on startup.
+
+The `nvidia` RuntimeClass is registered by nvkind. Pods that need
+GPU access (the LMCache DaemonSet, the test-side vLLM Deployment)
+already reference `runtimeClassName: nvidia`.
+
+#### `test-e2e-gpu-cluster` — existing GPU cluster
+
+Use when targeting OpenShift / EKS / GKE GPU clusters. Prerequisites:
+
+1. At least one node has `nvidia.com/gpu.present=true` and the
+   `nvidia` RuntimeClass installed.
+2. `KUBECONFIG` points at that cluster, the operator image is pushed
+   to a registry the cluster can pull from, and `IMG=` references it.
+3. The cluster can pull `lmcache/vllm-openai:latest` (default for
+   both the LMCache DaemonSet and the test-side vLLM workload).
+   Override with `VLLM_IMAGE=` if you mirror it elsewhere.
+4. Internet egress for Hugging Face model downloads, OR the model is
+   already on the node. Default model is `Qwen/Qwen2.5-0.5B`; override
+   with `VLLM_MODEL=<org>/<model>`.
+5. To run only the `/conf` spec and skip the heavyweight vLLM
+   round-trip, set `SKIP_VLLM_INTEGRATION=true`.
+
+Timeout is 60 min — cold image pulls + model download routinely eat
+20+ min before the first inference.
+
+#### CacheBlend integration knobs
+
+`cacheblend_integration_smoke_test.go` pulls a **private** payload image
+(`tensormesh/cacheblend-plugin:latest-nightly`). It builds a
+`dockerconfigjson` pull Secret in the test namespace from env credentials, so
+set these (in Buildkite: pipeline secrets, same mechanism as `HF_TOKEN`):
+
+- `CACHEBLEND_REGISTRY_USER` / `CACHEBLEND_REGISTRY_TOKEN` — registry username +
+  read-only PAT. **Unset ⇒ the spec Skips** (keeps credential-less clusters green).
+- `CACHEBLEND_REGISTRY_SERVER` — registry server (default
+  `https://index.docker.io/v1/` for Docker Hub).
+- `CACHEBLEND_PAYLOAD_IMAGE` — override the private plugin image (default
+  `tensormesh/cacheblend-plugin:latest-nightly`).
+- `CACHEBLEND_ENGINE_IMAGE` — blend server image (default
+  `lmcache/vllm-openai:latest-nightly`). `VLLM_IMAGE` (also defaults to
+  `latest-nightly` for this spec) / `VLLM_MODEL` apply as above. Engine, vLLM,
+  and the latest-nightly payload plugin must share a compatibility window.
+- `CACHEBLEND_BACKEND_LOG_PATTERN` — regex proving vLLM loaded the CUSTOM
+  attention backend (default `Using AttentionBackendEnum\.CUSTOM backend`).
+- `SKIP_CACHEBLEND_INTEGRATION=true` — skip this spec.
+
+---
+
+## Project Structure
+
+**Single-group layout (default):**
+```
+cmd/main.go                    Manager entry (registers controllers/webhooks)
+api/<version>/*_types.go       CRD schemas (+kubebuilder markers)
+api/<version>/zz_generated.*   Auto-generated (DO NOT EDIT)
+internal/controller/*          Reconciliation logic
+internal/webhook/*             Validation/defaulting (if present)
+config/crd/bases/*             Generated CRDs (DO NOT EDIT)
+config/rbac/role.yaml          Generated RBAC (DO NOT EDIT)
+config/samples/*               Example CRs (edit these)
+Makefile                       Top-level orchestrator: vars + `include make/*.mk`
+make/*.mk                      Targets by concern (dev / e2e / e2e-gpu / lint / build / deploy / tools)
+PROJECT                        Kubebuilder metadata Auto-generated (DO NOT EDIT)
+```
+
+**Multi-group layout** (for projects with multiple API groups):
+```
+api/<group>/<version>/*_types.go       CRD schemas by group
+internal/controller/<group>/*          Controllers by group
+internal/webhook/<group>/<version>/*   Webhooks by group and version (if present)
+```
+
+Multi-group layout organizes APIs by group name (e.g., `batch`, `apps`). Check the `PROJECT` file for `multigroup: true`.
+
+**To convert to multi-group layout:**
+1. Run: `kubebuilder edit --multigroup=true`
+2. Move APIs: `mkdir -p api/<group> && mv api/<version> api/<group>/`
+3. Move controllers: `mkdir -p internal/controller/<group> && mv internal/controller/*.go internal/controller/<group>/`
+4. Move webhooks (if present): `mkdir -p internal/webhook/<group> && mv internal/webhook/<version> internal/webhook/<group>/`
+5. Update import paths in all files
+6. Fix `path` in `PROJECT` file for each resource
+7. Update test suite CRD paths (add one more `..` to relative paths)
+
+## Critical Rules
+
+### Never Edit These (Auto-Generated)
+- `config/crd/bases/*.yaml` - from `make manifests`
+- `config/rbac/role.yaml` - from `make manifests`
+- `config/webhook/manifests.yaml` - from `make manifests`
+- `**/zz_generated.*.go` - from `make generate`
+- `PROJECT` - from `kubebuilder [OPTIONS]`
+
+### Never Remove Scaffold Markers
+Do NOT delete `// +kubebuilder:scaffold:*` comments. CLI injects code at these markers.
+
+### Keep Project Structure
+Do not move files around. The CLI expects files in specific locations.
+
+### Always Use CLI Commands
+Always use `kubebuilder create api` and `kubebuilder create webhook` to scaffold. Do NOT create files manually.
+
+### E2E Tests Require an Isolated Kind Cluster
+The e2e tests are designed to validate the solution in an isolated environment (similar to GitHub Actions CI).
+Ensure you run them against a dedicated [Kind](https://kind.sigs.k8s.io/) cluster (not your “real” dev/prod cluster).
+
+## After Making Changes
+
+**After editing `*_types.go` or markers:**
+```
+make manifests  # Regenerate CRDs/RBAC from markers
+make generate   # Regenerate DeepCopy methods
+```
+
+**After editing `*.go` files:**
+```
+make lint-fix   # Auto-fix code style
+make test       # Run unit tests
+```
+
+## CLI Commands Cheat Sheet
+
+### Create API (your own types)
+```bash
+kubebuilder create api --group <group> --version <version> --kind <Kind>
+```
+
+
+### Deploy Image Plugin (scaffold to deploy/manage ANY container image)
+
+Generate a controller that deploys and manages a container image (nginx, redis, memcached, your app, etc.):
+
+```bash
+# Example: deploying memcached
+kubebuilder create api --group example.com --version v1alpha1 --kind Memcached \
+  --image=memcached:alpine \
+  --plugins=deploy-image.go.kubebuilder.io/v1-alpha
+```
+
+Scaffolds good-practice code: reconciliation logic, status conditions, finalizers, RBAC. Use as a reference implementation.
+
+
+### Create Webhooks
+```bash
+# Validation + defaulting
+kubebuilder create webhook --group <group> --version <version> --kind <Kind> \
+  --defaulting --programmatic-validation
+
+# Conversion webhook (for multi-version APIs)
+kubebuilder create webhook --group <group> --version v1 --kind <Kind> \
+  --conversion --spoke v2
+```
+
+### Controller for Core Kubernetes Types
+```bash
+# Watch Pods
+kubebuilder create api --group core --version v1 --kind Pod \
+  --controller=true --resource=false
+
+# Watch Deployments
+kubebuilder create api --group apps --version v1 --kind Deployment \
+  --controller=true --resource=false
+```
+
+### Controller for External Types (e.g., from other operators)
+
+Watch resources from external APIs (cert-manager, Argo CD, Istio, etc.):
+
+```bash
+# Example: watching cert-manager Certificate resources
+kubebuilder create api \
+  --group cert-manager --version v1 --kind Certificate \
+  --controller=true --resource=false \
+  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
+  --external-api-domain=io \
+  --external-api-module=github.com/cert-manager/cert-manager
+```
+
+**Note:** Use `--external-api-module=<module>@<version>` only if you need a specific version. Otherwise, omit `@<version>` to use what's in go.mod.
+
+### Webhook for External Types
+
+```bash
+# Example: validating external resources
+kubebuilder create webhook \
+  --group cert-manager --version v1 --kind Issuer \
+  --defaulting \
+  --external-api-path=github.com/cert-manager/cert-manager/pkg/apis/certmanager/v1 \
+  --external-api-domain=io \
+  --external-api-module=github.com/cert-manager/cert-manager
+```
+
+## Testing & Development
+
+```bash
+make test              # Run unit tests (uses envtest: real K8s API + etcd)
+make run               # Run locally (uses current kubeconfig context)
+```
+
+Tests use **Ginkgo + Gomega** (BDD style). Check `suite_test.go` for setup.
+
+## Deployment Workflow
+
+```bash
+# 1. Regenerate manifests
+make manifests generate
+
+# 2. Build & deploy
+export IMG=<registry>/<project>:tag
+make docker-build docker-push IMG=$IMG  # Or: kind load docker-image $IMG --name <cluster>
+make deploy IMG=$IMG
+
+# 3. Test
+kubectl apply -k config/samples/
+
+# 4. Debug
+kubectl logs -n <project>-system deployment/<project>-controller-manager -c manager -f
+```
+
+### API Design
+
+**Key markers for** `api/<version>/*_types.go`:
+
+```go
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:scope=Namespaced
+// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=".status.conditions[?(@.type=='Ready')].status"
+
+// On fields:
+// +kubebuilder:validation:Required
+// +kubebuilder:validation:Minimum=1
+// +kubebuilder:validation:MaxLength=100
+// +kubebuilder:validation:Pattern="^[a-z]+$"
+// +kubebuilder:default="value"
+```
+
+- **Use** `metav1.Condition` for status (not custom string fields)
+- **Use predefined types**: `metav1.Time` instead of `string` for dates
+- **Follow K8s API conventions**: Standard field names (`spec`, `status`, `metadata`)
+
+### Controller Design
+
+**RBAC markers in** `internal/controller/*_controller.go`:
+
+```go
+// +kubebuilder:rbac:groups=mygroup.example.com,resources=mykinds,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=mygroup.example.com,resources=mykinds/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=mygroup.example.com,resources=mykinds/finalizers,verbs=update
+// +kubebuilder:rbac:groups=events.k8s.io,resources=events,verbs=create;patch
+// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
+```
+
+**Implementation rules:**
+- **Idempotent reconciliation**: Safe to run multiple times
+- **Re-fetch before updates**: `r.Get(ctx, req.NamespacedName, obj)` before `r.Update` to avoid conflicts
+- **Structured logging**: `log := log.FromContext(ctx); log.Info("msg", "key", val)`
+- **Owner references**: Enable automatic garbage collection (`SetControllerReference`)
+- **Watch secondary resources**: Use `.Owns()` or `.Watches()`, not just `RequeueAfter`
+- **Finalizers**: Clean up external resources (buckets, VMs, DNS entries)
+
+### Logging
+
+**Follow Kubernetes logging message style guidelines:**
+
+- Start from a capital letter
+- Do not end the message with a period
+- Active voice: subject present (`"Deployment could not create Pod"`) or omitted (`"Could not create Pod"`)
+- Past tense: `"Could not delete Pod"` not `"Cannot delete Pod"`
+- Specify object type: `"Deleted Pod"` not `"Deleted"`
+- Balanced key-value pairs
+
+```go
+log.Info("Starting reconciliation")
+log.Info("Created Deployment", "name", deploy.Name)
+log.Error(err, "Failed to create Pod", "name", name)
+```
+
+**Reference:** https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#message-style-guidelines
+
+### Webhooks
+- **Create all types together**: `--defaulting --programmatic-validation --conversion`
+- **When`--force`is used**: Backup custom logic first, then restore after scaffolding
+- **For multi-version APIs**: Use hub-and-spoke pattern (`--conversion --spoke v2`)
+  - Hub version: Usually oldest stable version (v1)
+  - Spoke versions: Newer versions that convert to/from hub (v2, v3)
+  - Example: `--group crew --version v1 --kind Captain --conversion --spoke v2` (v1 is hub, v2 is spoke)
+
+### Learning from Examples
+
+The **deploy-image plugin** scaffolds a complete controller following good practices. Use it as a reference implementation:
+
+```bash
+kubebuilder create api --group example --version v1alpha1 --kind MyApp \
+  --image=<your-image> --plugins=deploy-image.go.kubebuilder.io/v1-alpha
+```
+
+Generated code includes: status conditions (`metav1.Condition`), finalizers, owner references, events, idempotent reconciliation.
+
+## Distribution Options
+
+### Option 1: YAML Bundle (Kustomize)
+
+```bash
+# Generate dist/install.yaml from Kustomize manifests
+make build-installer IMG=<registry>/<project>:tag
+```
+
+**Key points:**
+- The `dist/install.yaml` is generated from Kustomize manifests (CRDs, RBAC, Deployment)
+- Commit this file to your repository for easy distribution
+- Users only need `kubectl` to install (no additional tools required)
+
+**Example:** Users install with a single command:
+```bash
+kubectl apply -f https://raw.githubusercontent.com/<org>/<repo>/<tag>/dist/install.yaml
+```
+
+### Option 2: Helm Chart
+
+```bash
+kubebuilder edit --plugins=helm/v2-alpha                      # Generates dist/chart/ (default)
+kubebuilder edit --plugins=helm/v2-alpha --output-dir=charts  # Generates charts/chart/
+```
+
+**For development:**
+```bash
+make helm-deploy IMG=<registry>/<project>:<tag>          # Deploy manager via Helm
+make helm-deploy IMG=$IMG HELM_EXTRA_ARGS="--set ..."    # Deploy with custom values
+make helm-status                                         # Show release status
+make helm-uninstall                                      # Remove release
+make helm-history                                        # View release history
+make helm-rollback                                       # Rollback to previous version
+```
+
+**For end users/production:**
+```bash
+helm install my-release ./<output-dir>/chart/ --namespace <ns> --create-namespace
+```
+
+**Important:** If you add webhooks or modify manifests after initial chart generation:
+1. Backup any customizations in `<output-dir>/chart/values.yaml` and `<output-dir>/chart/manager/manager.yaml`
+2. Re-run: `kubebuilder edit --plugins=helm/v2-alpha --force` (use same `--output-dir` if customized)
+3. Manually restore your custom values from the backup
+
+### Publish Container Image
+
+```bash
+export IMG=<registry>/<project>:<version>
+make docker-build docker-push IMG=$IMG
+```
+
+## References
+
+### Essential Reading
+- **Kubebuilder Book**: https://book.kubebuilder.io (comprehensive guide)
+- **controller-runtime FAQ**: https://github.com/kubernetes-sigs/controller-runtime/blob/main/FAQ.md (common patterns and questions)
+- **Good Practices**: https://book.kubebuilder.io/reference/good-practices.html (why reconciliation is idempotent, status conditions, etc.)
+- **Logging Conventions**: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md#message-style-guidelines (message style, verbosity levels)
+
+### API Design & Implementation
+- **API Conventions**: https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md
+- **Operator Pattern**: https://kubernetes.io/docs/concepts/extend-kubernetes/operator/
+- **Markers Reference**: https://book.kubebuilder.io/reference/markers.html
+
+### Tools & Libraries
+- **controller-runtime**: https://github.com/kubernetes-sigs/controller-runtime
+- **controller-tools**: https://github.com/kubernetes-sigs/controller-tools
+- **Kubebuilder Repo**: https://github.com/kubernetes-sigs/kubebuilder
diff --git a/operator/DESIGN.md b/operator/DESIGN.md
new file mode 100644
index 0000000..2fcff45
--- /dev/null
+++ b/operator/DESIGN.md
@@ -0,0 +1,596 @@
+# LMCache Kubernetes Operator Design
+
+## Overview
+
+LMCache multiprocess mode runs as a separate server process that vLLM instances connect to for KV cache offloading. Today this is deployed manually via raw K8s manifests (a DaemonSet for LMCache + a Deployment for vLLM). A K8s operator would automate lifecycle management, enforce best practices (`hostIPC`, resource sizing), and expose connection info for vLLM discovery.
+
+### Current Pain Points the Operator Solves
+
+- Manual `hostIPC` setup and node-local service discovery
+- No automated connection info propagation to vLLM
+- No Prometheus ServiceMonitor integration
+- No validation of configuration parameters
+
+### How the Operator Addresses These
+
+The operator introduces a single CRD (`LMCacheEngine`) that declaratively captures the full LMCache server configuration. The controller reconciles this CR into the underlying K8s resources (DaemonSet, Service, ConfigMap, ServiceMonitor), automatically injecting the required pod-level settings that are easy to forget in hand-written manifests.
+
+**Auto-injected pod settings eliminate manual boilerplate.** The controller always sets `hostIPC: true` and `--host 0.0.0.0` — settings that the current `lmcache-daemonset.yaml` requires users to specify by hand. Getting any of these wrong (e.g., forgetting `hostIPC`) causes silent connectivity failures or CUDA IPC errors that are hard to debug.
+
+**A node-local Service with connection ConfigMap provides a stable discovery contract for vLLM.** The operator creates a ClusterIP Service with `internalTrafficPolicy=Local`, which ensures kube-proxy routes traffic only to the LMCache pod on the same node. A ConfigMap (`<name>-connection`) contains the `kv-transfer-config` JSON pointing to this service's cluster DNS name. vLLM deployments simply mount the ConfigMap — no downward API or shell substitution needed. When the LMCache CR changes, the ConfigMap updates automatically and vLLM pods pick up the new values on restart.
+
+**Prometheus integration is declarative.** When `prometheus.serviceMonitor.enabled` is set, the operator creates a ServiceMonitor CR that the Prometheus Operator discovers automatically. Without the operator, users must manually create ServiceMonitor resources and keep labels/ports in sync with the DaemonSet.
+
+**CRD validation catches misconfigurations at apply time.** OpenAPI schema validation and a validating webhook enforce constraints (e.g., `l1.sizeGB > 0`, `eviction.triggerWatermark` in `(0.0, 1.0]`) before any pods are created. Today, invalid CLI flags only surface as runtime crashes inside the container.
+
+**Resource sizing is auto-computed from the L1 cache size.** The operator derives `memoryRequest` (`l1.sizeGB + 5 GiB`) and `memoryLimit` (`1.5x request`) automatically, eliminating the mental math that currently leads to either OOM kills (under-provisioned) or wasted node capacity (over-provisioned). Users can override with explicit values.
+
+---
+
+## API Group & CRD
+
+```yaml
+apiVersion: lmcache.ai/v1alpha1
+kind: LMCacheEngine
+```
+
+- **Group** `lmcache.ai`
+- **v1alpha1** — alpha maturity; shape will evolve as L2 backends stabilize
+- **LMCacheEngine** — represents the per-node cache engine. Future CRDs can
+cover other concerns (e.g., `LMCacheKeyManager` for global key management,
+`LMCacheMonitor` for engine state monitoring)
+
+---
+
+## CRD Spec (Complete)
+
+```yaml
+apiVersion: lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: string
+  namespace: string
+spec:
+  # -- Container image --
+  image:
+    repository: string        # default: "lmcache/standalone"
+    tag: string               # default: "nightly"
+    pullPolicy: string        # default: IfNotPresent
+  imagePullSecrets: []LocalObjectReference
+
+  # -- Server config (maps to server.py argparse) --
+  server:
+    port: int                 # default: 5555
+    chunkSize: int            # default: 256 tokens
+    maxWorkers: int           # default: 1
+    hashAlgorithm: string     # default: blake3 (builtin | sha256_cbor | blake3)
+
+  # -- L1 cache (maps to L1MemoryManagerConfig + L1ManagerConfig) --
+  # Internal tuning knobs (useLazy, alignBytes, writeTTLSeconds,
+  # readTTLSeconds) use server defaults and can be overridden via the
+  # env escape hatch if needed.
+  l1:
+    sizeGB: float             # REQUIRED
+
+  # -- Eviction (maps to EvictionConfig) --
+  eviction:
+    policy: string            # default: "LRU" (only supported value)
+    triggerWatermark: float   # default: 0.8 (range 0.0-1.0)
+    evictionRatio: float      # default: 0.2 (range 0.0-1.0)
+
+  # -- Monitoring (maps to PrometheusConfig from mp_observability/config.py) --
+  # Note: the CRD uses `enabled: true` by default; the CLI equivalent is
+  # the absence of the `--disable-prometheus` flag.
+  prometheus:
+    enabled: bool             # default: true  (CLI: omit --disable-prometheus)
+    port: int                 # default: 9090
+    serviceMonitor:
+      enabled: bool           # default: false
+      interval: string        # default: "30s"
+      labels: map[string]string
+  # ServiceMonitor is a CRD from the Prometheus Operator (kube-prometheus-stack).
+  # When enabled, the operator creates a ServiceMonitor resource that tells
+  # Prometheus to automatically discover and scrape LMCache metrics endpoints.
+  # Without it, you'd need to manually configure Prometheus scrape targets.
+  # If you don't use the Prometheus Operator, leave serviceMonitor.enabled=false
+  # and use the pod annotations (prometheus.io/scrape, prometheus.io/port) instead.
+
+  # -- L2 storage backend (single adapter) --
+  # Currently only one L2 adapter is supported at a time.
+  # LMCache MP mode supports multiple adapters, but this is not yet
+  # fully tested. Once validated, the operator will support multiple.
+  # Exactly one of resp or raw must be set.
+  l2Backend:
+    # Option A: Native RESP (Redis/Valkey) adapter
+    resp:
+      host: string              # REQUIRED
+      port: int                 # REQUIRED, 1-65535
+      numWorkers: int           # default: 8
+      maxCapacityGB: float      # default: 0 (disabled)
+      authSecretRef:            # optional, Secret with "username"/"password" keys
+        name: string
+    # Option B: Raw escape hatch for other adapter types
+    raw:
+      type: string              # adapter type name (nixl_store, fs, mock, raw_block, etc.)
+      config: map[string]any    # type-specific config as free-form map
+
+  # -- Connection-injection webhook defaults (optional) --
+  # Read by the LMCache mutating webhook for pods bound to this engine. When
+  # unset, the webhook wires only the connection (--kv-transfer-config, hostIPC,
+  # PYTHONHASHSEED). Set injection.payloadImage to ALSO stage an lmcache code
+  # tree into the vLLM container (emptyDir + init container + readOnly mount +
+  # PYTHONPATH=/lmcache-payload), reusing the CacheBlend payload-staging
+  # mechanism so the vLLM client and the engine server run one lmcache build.
+  injection:
+    payloadImage:               # SEPARATE image: ships lmcache under /payload
+      repository: string        # REQUIRED (no valid default)
+      tag: string               # default: latest
+      pullPolicy: string        # default: IfNotPresent
+    imagePullSecrets: []LocalObjectReference  # for a private payload image
+    targetContainer: string     # default: first container
+
+  # -- Resources (auto-computed, no user input needed) --
+  # The operator derives resource requests/limits from l1.sizeGB:
+  #   memoryRequest = ceil(l1.sizeGB + 5) Gi
+  #   memoryLimit   = ceil(memoryRequest * 1.5) Gi
+  #   cpuRequest    = "4"
+  # To override, use the resourceOverrides escape hatch below.
+  resourceOverrides: ResourceRequirements  # optional, raw K8s resources override
+
+  # -- Logging --
+  logLevel: string            # default: INFO (DEBUG|INFO|WARNING|ERROR)
+
+  # -- Scheduling --
+  nodeSelector: map[string]string
+  affinity: Affinity
+  tolerations: []Toleration
+  # nodeSelector determines which nodes get an LMCache instance.
+  # Use nodeSelector: {nvidia.com/gpu.present: "true"} to target all GPU
+  # nodes. When new GPU nodes join the cluster, the DaemonSet controller
+  # automatically schedules an LMCache pod on them.
+
+  # -- Overrides --
+  env: []EnvVar               # additional environment variables
+  volumes: []Volume           # additional volumes (e.g. for L2 disk backend)
+  volumeMounts: []VolumeMount
+  podAnnotations: map[string]string
+  podLabels: map[string]string
+  serviceAccountName: string
+  priorityClassName: string
+
+  # -- Security --
+  privileged: bool            # default: false; run the engine container in
+                              # privileged mode. Needed only on clusters where
+                              # the engine cannot see the node GPUs otherwise
+                              # (see "Auto-managed Pod Settings" below).
+
+  # -- Extra CLI flags --
+  extraArgs: []string         # appended last, can override any auto-generated flag
+```
+
+---
+
+## Auto-managed Pod Settings (not in CRD spec)
+
+The operator always injects these into the pod spec:
+
+- **`hostIPC: true`** — **required for CUDA IPC between LMCache and vLLM.** LMCache uses `CudaIPCWrapper` which calls PyTorch's `_share_cuda_()` to get a GPU driver-level IPC handle. The handle is serialized and sent over ZMQ TCP. The receiving process reconstructs the tensor via `cudaIpcOpenMemHandle` at the driver level. This call requires both processes to share the same IPC namespace — without `hostIPC: true`, `cudaIpcOpenMemHandle` fails with `cudaErrorMapBufferObjectFailed`. **Both the LMCache pods and vLLM pods must have `hostIPC: true`.**
+- **`runtimeClassName: nvidia`** — uses the NVIDIA container runtime, which injects the host's NVIDIA driver libraries and device files into the container. This is required for CUDA to function inside the pod.
+- **`NVIDIA_VISIBLE_DEVICES=all`** — gives the engine access to all GPUs on the node for CUDA IPC and custom data transfer kernels without claiming any via `nvidia.com/gpu` resource requests (which would make those GPUs unavailable to the serving engine). The combination of `runtimeClassName: nvidia` + `NVIDIA_VISIBLE_DEVICES=all` lets the container see all GPUs without consuming device-plugin resources, so the serving engine (e.g., vLLM) can still request all GPUs on the node. On most clusters this is sufficient; on some, the engine cannot see the GPUs unless the pod is also privileged — set `spec.privileged: true` to run the engine container privileged (default `false`).
+- **`NVIDIA_VISIBLE_DEVICES=all`** and **`NVIDIA_DRIVER_CAPABILITIES=all`** — env vars that instruct the NVIDIA container runtime to expose all GPUs and all driver capabilities to the container.
+- **`--host 0.0.0.0`** — always passed as a container arg. The server defaults to `--host localhost` which only binds to loopback; the server must bind to all interfaces so the node-local Service can route traffic to it.
+- **No `hostNetwork`** — the operator does **not** use `hostNetwork`. Instead, it creates a ClusterIP Service with `internalTrafficPolicy=Local`. kube-proxy ensures that traffic to the service is routed only to the LMCache pod on the same node. This avoids occupying host ports and reduces the privileged surface area.
+- **No `/dev/shm` emptyDir mount** — the operator intentionally does *not* mount an emptyDir at `/dev/shm`. With `hostIPC: true`, the container already sees the host's `/dev/shm`. Mounting an emptyDir would shadow the host's `/dev/shm` with a private tmpfs, breaking CUDA IPC (`cudaIpcOpenMemHandle` fails because IPC handles written by one pod are invisible to others). If your workload needs a larger `/dev/shm` for non-IPC purposes, add it via `spec.volumes` / `spec.volumeMounts`.
+
+> **Security implications:** The LMCache pods run with `hostIPC: true` (required for CUDA IPC), which exposes the host's IPC namespace. When `spec.privileged: true` is set they additionally run privileged, granting full device access to the container. Only deploy in trusted environments. Clusters using Pod Security Standards must allow the `privileged` profile for the LMCache namespace whenever `hostIPC`/`privileged` are in use — the `baseline` and `restricted` profiles reject these settings.
+
+---
+
+## Validation Rules
+
+| Field | Rule |
+|---|---|
+| `l1.sizeGB` | Required, must be `> 0` |
+| `eviction.policy` | Must be `"LRU"` (if set) |
+| `eviction.triggerWatermark` | Must be in `(0.0, 1.0]` |
+| `eviction.evictionRatio` | Must be in `(0.0, 1.0]` |
+| `server.port` | Must be in `[1024, 65535]` |
+
+---
+
+## CRD Status
+
+```yaml
+status:
+  phase: Pending | Running | Degraded | Failed
+  observedGeneration: int64
+
+  desiredInstances: int
+  readyInstances: int
+
+  # Per-node connection info (for kubectl visibility)
+  endpoints:
+    - nodeName: string
+      hostIP: string
+      podName: string
+      port: int
+      metricsPort: int
+      ready: bool
+
+  # Standard conditions
+  conditions:
+    - type: Available          # at least one instance ready
+    - type: AllInstancesReady  # all desired instances ready
+    - type: ConfigValid        # spec validation passed
+  # Connection ConfigMap is always named <metadata.name>-connection;
+  # no need to store the ref in status.
+```
+
+---
+
+## Examples
+
+### Minimal Deployment
+
+```yaml
+apiVersion: lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: my-cache
+spec:
+  l1:
+    sizeGB: 60
+```
+
+This deploys a DaemonSet with 60GB L1 cache, LRU eviction, blake3 hashing, port 5555, auto-computed 65Gi memory request / 98Gi limit, Prometheus on 9090, and a connection ConfigMap for vLLM. The operator auto-injects `hostIPC` and `--host 0.0.0.0`, and creates a node-local Service for vLLM discovery.
+
+### Production Deployment (all GPU nodes)
+
+```yaml
+apiVersion: lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: production-cache
+  namespace: llm-serving
+spec:
+  # Target all GPU nodes — new GPU nodes automatically get an LMCache pod
+  nodeSelector:
+    nvidia.com/gpu.present: "true"
+
+  image:
+    repository: lmcache/standalone
+    tag: v0.1.0
+    pullPolicy: IfNotPresent
+
+  server:
+    port: 6555
+    chunkSize: 256
+    maxWorkers: 4
+    hashAlgorithm: blake3
+
+  l1:
+    sizeGB: 60
+
+  eviction:
+    triggerWatermark: 0.8
+    evictionRatio: 0.2
+
+  prometheus:
+    enabled: true
+    port: 9090
+    serviceMonitor:
+      enabled: true
+      labels:
+        release: kube-prometheus-stack
+
+  logLevel: INFO
+  podAnnotations:
+    prometheus.io/scrape: "true"
+    prometheus.io/port: "9090"
+  priorityClassName: system-node-critical
+```
+
+---
+
+## Resources Created by the Operator
+
+For `LMCacheEngine` named `production-cache`:
+
+| Resource | Name | Purpose |
+|---|---|---|
+| DaemonSet | `production-cache` | Runs LMCache server pods |
+| Service (ClusterIP, `internalTrafficPolicy=Local`) | `production-cache` | Node-local service discovery for vLLM |
+| ConfigMap | `production-cache-connection` | kv-transfer-config JSON pointing to the lookup Service |
+| Service (headless) | `production-cache-metrics` | Prometheus scrape target |
+| ServiceMonitor (optional) | `production-cache` | Prometheus Operator integration |
+
+### ConfigMap Content (for vLLM discovery)
+
+```json
+{
+  "kv_connector": "LMCacheMPConnector",
+  "kv_connector_module_path": "lmcache.integration.vllm.lmcache_mp_connector",
+  "kv_role": "kv_both",
+  "kv_connector_extra_config": {
+    "lmcache.mp.host": "tcp://<name>.<namespace>.svc.cluster.local",
+    "lmcache.mp.port": "<spec.server.port, default 5555>"
+  }
+}
+```
+
+The ConfigMap uses the lookup Service's cluster DNS name. Because the Service has `internalTrafficPolicy=Local`, kube-proxy routes traffic only to the LMCache pod on the same node as the vLLM pod. vLLM pods mount this ConfigMap and pass the JSON to `--kv-transfer-config` — no downward API or shell variable substitution required. The explicit `kv_connector_module_path` makes the external LMCache MP connector path load-bearing and avoids silent fallback to an older vendored builtin connector path.
+
+---
+
+## Auto-injected Pod Template Details
+
+In addition to the auto-managed pod settings above (`hostIPC`, `--host 0.0.0.0`),
+the operator injects:
+
+- Container command: `/opt/venv/bin/lmcache server`
+- Container args: serialized from spec fields
+- Env: `LMCACHE_LOG_LEVEL` from `spec.logLevel`
+- Probes:
+  - **Startup:** TCP on server port, `initialDelay=5s`, `period=5s`, `failureThreshold=30`
+  - **Liveness:** TCP on server port, `period=10s`
+  - **Readiness:** TCP on server port, `period=5s`
+
+---
+
+## Reconciliation Logic
+
+```
+OnEvent(LMCacheEngine create/update/delete):
+
+1. VALIDATE spec -> set condition ConfigValid
+2. COMPUTE derived values (unless overridden):
+   - memoryRequest = ceil(l1.sizeGB + 5) Gi
+   - memoryLimit = ceil(memoryRequest * 1.5) Gi
+   - containerArgs from all spec fields
+3. RECONCILE DaemonSet (CreateOrUpdate, ownerRef)
+   - Always inject: hostIPC, runtimeClassName: nvidia, NVIDIA_VISIBLE_DEVICES=all, --host 0.0.0.0 (privileged only when spec.privileged=true)
+4. RECONCILE node-local lookup Service (internalTrafficPolicy=Local)
+5. RECONCILE headless Service for metrics
+6. RECONCILE connection ConfigMap
+7. RECONCILE ServiceMonitor (if enabled)
+8. UPDATE status:
+   - Query workload for ready/desired counts
+   - Enumerate pods -> build endpoints list
+   - Set phase: Running | Degraded | Pending | Failed
+   - Set conditions, observedGeneration
+```
+
+**Secondary watches:** DaemonSet, Pods (readiness changes → update endpoints), Nodes (new GPU node → DaemonSet auto-schedules)
+
+**Deletion / cleanup**: every child resource the operator creates
+(DaemonSet, lookup Service, metrics Service, connection ConfigMap,
+managed RESP auth Secret, optional ServiceMonitor) carries an
+`ownerReference` to the LMCacheEngine, so Kubernetes garbage
+collection cascade-deletes them when the CR goes away. **No finalizer
+is used.** An earlier design added a `lmcache.ai/cleanup` finalizer
+to mirror that GC behavior, but it was a no-op that only created
+deadlocks when the controller pod was not running (e.g. during
+cluster issues or a single-step `kubectl delete -k config/default`).
+The reconciler now actively strips that legacy finalizer from any CR
+it sees, so migration from older operator versions is automatic.
+Finalizers will return when we need to clean up state K8s GC cannot
+reach (Redis L2 keys, federation deregistration, etc.).
+
+---
+
+## CacheBlend: `CacheBlendEngine` CRD + Injection Webhook
+
+CacheBlend reuses cached KV at shifted positions. It has two halves the operator
+manages together: a **GPU-resident blend engine** (server side) and a
+**vLLM-side plugin** that must be loaded into the serving container. The operator
+ships both as a second CRD plus a mutating admission webhook.
+
+> This implements what was previously deferred as a future `blend.enabled` field
+> on `LMCacheEngine`. It is instead a **separate `CacheBlendEngine` kind** (with
+> its own controller) plus an injection webhook — cleaner separation, and no
+> behavior change to `LMCacheEngine`.
+
+### `CacheBlendEngine` CRD
+
+Group `lmcache.lmcache.ai`, `v1alpha1`, kind `CacheBlendEngine` (shortName `cbe`).
+The spec **mirrors `LMCacheEngineSpec`** (image, server, l1, eviction, prometheus,
+l2Backend, scheduling, overrides, imagePullSecrets) and adds:
+
+- `blend.checkLayer` (default 1) and `blend.recompRatio` (default 0.15) — CB
+  tunables fed to the vLLM connector.
+- `injection` — what the webhook injects into vLLM pods: `payloadImage` (an
+  `ImageSpec` — `repository`/`tag`/`pullPolicy`, like `spec.image` — for the
+  private `lmcache-cacheblend` init-container image; set `repository` explicitly,
+  the inherited engine-image default is not a valid payload), `imagePullSecrets`
+  (appended to the vLLM pod so the private payload image can pull — the Secret
+  must exist in the vLLM pod's namespace), `targetContainer` (default: first
+  container), and `cudagraph` (`eager`|`piecewise`|`full_decode_only`, default
+  `eager`).
+- `server.chunkSize` defaults to **256** and is validated to equal 256 (the blend
+  matcher requires `chunk_size == vLLM --block-size * 4`).
+
+### The blend engine (controller)
+
+`CacheBlendEngineReconciler` mirrors `LMCacheEngineReconciler` and reconciles a
+DaemonSet running `lmcache server --engine-type blend` (plus
+`--l1-align-bytes 16777216`), a node-local lookup Service, a metrics Service, and
+a `<name>-connection` ConfigMap. **GPU model is identical to `LMCacheEngine`**:
+`runtimeClassName: nvidia` + `NVIDIA_VISIBLE_DEVICES=all` + `hostIPC: true` (and
+`privileged` when `spec.privileged=true`), with **no `nvidia.com/gpu`
+device-plugin claim** — the engine
+*shares* the vLLM GPU rather than reserving one, because the blend server scatters
+re-RoPE'd KV directly into vLLM's paged KV over **same-device CUDA IPC**. The
+engine resource builders are the same name/spec-keyed cores used by
+`LMCacheEngine`.
+
+The `<name>-connection` ConfigMap carries the **`CBKVConnector`**
+`kv-transfer-config` (vs `LMCacheMPConnector` for `LMCacheEngine`) — same node-local
+`tcp://` host/port shape, plus the `cb.*` tunables:
+
+```json
+{
+  "kv_connector": "CBKVConnector",
+  "kv_connector_module_path": "lmcache_cacheblend.connector",
+  "kv_role": "kv_both",
+  "kv_connector_extra_config": {
+    "lmcache.mp.host": "tcp://<name>.<namespace>.svc.cluster.local",
+    "lmcache.mp.port": "<server.port>",
+    "cb.check_layer": <blend.checkLayer>,
+    "cb.recomp_ratio": <blend.recompRatio>
+  }
+}
+```
+
+Co-location works exactly like `LMCacheEngine`: one engine per GPU node
+(DaemonSet), and the node-local Service (`internalTrafficPolicy: Local`) routes a
+vLLM pod to the same-node engine. The control-plane RPC is TCP via that Service;
+the data-plane KV write is CUDA IPC on the shared GPU.
+
+### The injection webhook
+
+A mutating admission webhook (`/mutate--v1-pod`, `CREATE`, `failurePolicy: Ignore`)
+injects the `lmcache-cacheblend` plugin into opted-in pods so a **stock vLLM image
+needs no rebuild**. A pod opts in with label `lmcache.ai/cacheblend-inject: "true"`
+and binds to an engine with annotation `lmcache.ai/cacheblend-engine: <name>`. The
+webhook then applies:
+
+| Mutation | What |
+|---|---|
+| pod `hostIPC: true` | required for CUDA IPC with the node-local engine |
+| `cb-plugin` emptyDir + payload init container | the busybox payload `cp -a`'s the pure-Python plugin tree onto the shared volume |
+| readOnly mount + `PYTHONPATH=/cb-plugin` on the vLLM container | vLLM discovers the plugin via its `vllm.general_plugins` entry point |
+| append required vLLM args | `--attention-backend CUSTOM`, `--kv-transfer-config <from the connection ConfigMap>`, `--block-size 64`, `--pipeline-parallel-size 1`, `--no-enable-chunked-prefill`, `--no-async-scheduling`, `--enforce-eager` (or the configured cudagraph) |
+| append `injection.imagePullSecrets` | so the private payload image can pull |
+| stamp `lmcache.ai/cacheblend-injected: "true"` | idempotency guard |
+
+The webhook **skips** (stamping `lmcache.ai/cacheblend-skip-reason`) when: the
+target container overrides `command` (a `sh -c` wrapper — appended args wouldn't
+reach `vllm serve`); the user already supplies `--kv-transfer-config` (not
+clobbered); the named engine's connection ConfigMap doesn't exist; the engine's
+`injection.payloadImage` resolves to an empty reference (`payload-image-unset`);
+or the requested `targetContainer`/`cacheblend-container` annotation names a
+container that does not exist on the pod (`target-container-not-found`). It does
+**not** gate on engine readiness — like `LMCacheEngine`, the connector connects
+when the engine comes up. Args are emitted in two-token form
+(`--attention-backend CUSTOM`); the replace-not-duplicate dedup still recognizes a
+user-supplied `--flag=value`.
+
+> **Shared with the LMCache injector.** The emptyDir + payload init container +
+> readOnly mount + `PYTHONPATH` staging (rows 2–3 above) is generic — the standard
+> `LMCacheEngine` injector (`/mutate-lmcache--v1-pod`) reuses it (under
+> `internal/webhook/payload_staging.go`) to optionally stage an `lmcache` build
+> when `LMCacheEngine.spec.injection.payloadImage` is set. There the staging is
+> **additive and optional**: the connection wiring always runs, and an unset (or
+> absent) `injection.payloadImage` simply stages nothing — it never skips the
+> whole injection. The LMCache staging uses its own names (`lmcache-payload`
+> volume, `/lmcache-payload` mount) so both injectors can fire on one pod.
+
+### Prerequisites
+
+- **cert-manager** — the webhook's serving cert is a cert-manager `Issuer` +
+  `Certificate` (caBundle injected via `inject-ca-from`); install it before
+  `make deploy`.
+- **`make deploy`, not `make run`** — `make run` sets `ENABLE_WEBHOOKS=false` and
+  installs no `MutatingWebhookConfiguration`; it is controller-only. The webhook
+  needs the operator running as an in-cluster pod.
+- **Pod Security Standards** — the injected `hostIPC`/`privileged` is rejected by
+  the `baseline`/`restricted` profiles, so the engine's and the vLLM pod's
+  namespaces must be labeled `pod-security.kubernetes.io/enforce=privileged`.
+
+### Resources created (for a `CacheBlendEngine` named `cb`)
+
+| Resource | Name | Purpose |
+|---|---|---|
+| DaemonSet | `cb` | `lmcache server --engine-type blend` on GPU nodes |
+| Service (node-local) | `cb` | same-node discovery for vLLM (`CBKVConnector`) |
+| Service (headless) | `cb-metrics` | Prometheus scrape target |
+| ConfigMap | `cb-connection` | `CBKVConnector` kv-transfer-config |
+| MutatingWebhookConfiguration | (operator-wide) | injects the plugin into opted-in vLLM pods |
+
+---
+
+## Coordinator: `LMCacheCoordinator` CRD
+
+The **coordinator** (`lmcache/v1/mp_coordinator/`) is the fleet-level HTTP service
+that engine servers register/heartbeat against, and which drives L2 quota
+eviction and global CacheBlend lookups. Unlike the engines (one DaemonSet pod per
+GPU node), the coordinator is a single fleet-wide service, so `LMCacheCoordinator`
+reconciles a **Deployment + ClusterIP Service** instead of a DaemonSet. The
+controller carries no finalizer — owner-reference GC cascade-deletes the children.
+
+### `LMCacheCoordinatorSpec`
+
+The spec mirrors `MPCoordinatorConfig` (`lmcache/v1/mp_coordinator/config.py`); the
+controller renders each field into the matching `lmcache coordinator` CLI flag:
+`host`, `port` (9300), `instanceTimeout` (30), `healthCheckInterval` (10),
+`evictionCheckInterval` (5), `evictionRatio` (0.2), `triggerWatermark` (1.0),
+`blendChunkSize` (256), `blendProbeStride` (1). It also carries `replicas`,
+`image`, `prometheus`, and the usual pod-shaping fields (resources, scheduling,
+env, etc.).
+
+The global-CacheBlend knobs (`blendChunkSize`, `blendProbeStride`) render into the
+`--blend-chunk-size` / `--blend-probe-stride` flags and default to 256 / 1. Note
+`blendChunkSize` **must equal** the blend servers' chunk size.
+
+> **Metrics caveat:** the coordinator process exposes only `/healthz`, not a
+> Prometheus `/metrics` endpoint. ServiceMonitor support is wired for parity but
+> defaults **disabled**; enabling it is only useful once a metrics endpoint is
+> added to the coordinator app.
+
+### Connecting engines to a coordinator
+
+`LMCacheEngineSpec` and `CacheBlendEngineSpec` gained a `coordinator` block
+(`CoordinatorConnectionSpec`) that maps to the server's coordinator-client flags
+(`lmcache/v1/multiprocess/config.py`: `add_coordinator_args`):
+
+- `ref` — name of an `LMCacheCoordinator` in the same namespace. The controller
+  resolves it to the coordinator's Service URL (`http://<name>.<ns>.svc:<port>`)
+  before building the DaemonSet, so `BuildContainerArgs` stays a pure function.
+- `url` — explicit escape hatch for a coordinator the operator does not manage.
+  Exactly one of `ref`/`url` is required (enforced in validation).
+- `advertiseIP` — **do not set this in almost every case.** It defaults to the
+  pod IP via the downward API env `LMCACHE_COORDINATOR_ADVERTISE_IP`, which is
+  correct for normal in-cluster deployments. Only override it if you know exactly
+  what you are doing (e.g. the coordinator runs outside the cluster and must
+  reach the server through a specific externally-routable address); an incorrect
+  value silently breaks coordinator-to-server connectivity.
+- `heartbeatInterval`, `l2EventReporting`, `l2EventFlushInterval`.
+
+When `coordinator` is unset, the server emits no `--coordinator-url` and does not
+register (unchanged behavior).
+
+### Resources created (for an `LMCacheCoordinator` named `coord`)
+
+| Resource | Name | Purpose |
+|---|---|---|
+| Deployment | `coord` | `lmcache coordinator` HTTP server (port 9300) |
+| Service (ClusterIP) | `coord` | fleet-wide discovery endpoint for engines |
+| Service (headless) | `coord-metrics` | Prometheus scrape target (only if `prometheus.serviceMonitor.enabled`) |
+| ServiceMonitor | `coord` | Prometheus scrape config (gated, disabled by default) |
+
+---
+
+## Future Extensibility
+
+- **L2 backends:** The RESP (Redis/Valkey) adapter is natively supported with typed CRD fields and Secret-based auth injection. Other adapter types (nixl_store, fs, mock, mooncake_store, raw_block) can be configured via the `raw` escape hatch. Currently only a single L2 adapter is supported at a time. LMCache MP mode is designed to support multiple adapters in cascade, but this is not yet fully tested — once validated, the operator will support multiple adapters.
+- **Blend mode:** Implemented as the separate `CacheBlendEngine` CRD + injection webhook — see [CacheBlend](#cacheblend-cacheblendengine-crd--injection-webhook) above. (This supersedes the earlier idea of a `blend.enabled` field on `LMCacheEngine`.)
+- **Update strategy:** Future `spec.updateStrategy` field for `RollingUpdate`/`OnDelete` control on the DaemonSet.
+- **Coordinator:** Implemented as the separate `LMCacheCoordinator` CRD (Deployment + Service) with engine-side `coordinator` connection wiring — see [Coordinator](#coordinator-lmcachecoordinator-crd) above.
+- **Additional CRDs:** `LMCacheKeyManager` (global key management), `LMCacheMonitor` (engine state monitoring), `LMCacheFederation` (cross-cluster P2P topology).
+
+---
+
+## Key Source Files Referenced
+
+| File | What it defines |
+|---|---|
+| `lmcache/v1/distributed/config.py` | `L1MemoryManagerConfig`, `L1ManagerConfig`, `EvictionConfig`, `StorageManagerConfig`, argparse |
+| `lmcache/v1/mp_observability/config.py` | `PrometheusConfig`, `add_prometheus_args`, `parse_args_to_prometheus_config` |
+| `lmcache/v1/multiprocess/server.py` | `MPCacheServer`, server CLI entry point, argparse (lines 629–653) |
+| `lmcache/v1/multiprocess/http_server.py` | HTTP server with `/healthcheck` endpoint (FastAPI + ZMQ) |
+| `lmcache/v1/mp_coordinator/config.py` | `MPCoordinatorConfig` (coordinator knobs mapped by `LMCacheCoordinator`) |
+| `lmcache/cli/commands/coordinator.py` | `lmcache coordinator` CLI (flags rendered into the coordinator Deployment) |
+| `lmcache/v1/multiprocess/config.py` | `add_coordinator_args` (engine `coordinator` connection flags) |
+| `lmcache/v1/distributed/l2_adapters/config.py` | L2 adapter registry pattern, `L2AdapterConfigBase`, `L2AdaptersConfig` |
+| `examples/multi_process/lmcache-daemonset.yaml` | Reference DaemonSet manifest |
+| `examples/multi_process/vllm-deployment.yaml` | Reference vLLM deployment with kv-transfer-config |
diff --git a/operator/Dockerfile b/operator/Dockerfile
new file mode 100644
index 0000000..a022882
--- /dev/null
+++ b/operator/Dockerfile
@@ -0,0 +1,31 @@
+# Build the manager binary
+FROM golang:1.25 AS builder
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /workspace
+# Copy the Go Modules manifests
+COPY go.mod go.mod
+COPY go.sum go.sum
+# cache deps before building and copying source so that we don't need to re-download as much
+# and so that source changes don't invalidate our downloaded layer
+RUN go mod download
+
+# Copy the Go source (relies on .dockerignore to filter)
+COPY . .
+
+# Build
+# the GOARCH has no default value to allow the binary to be built according to the host where the command
+# was called. For example, if we call make docker-build in a local env which has the Apple Silicon M1 SO
+# the docker BUILDPLATFORM arg will be linux/arm64 when for Apple x86 it will be linux/amd64. Therefore,
+# by leaving it empty we can ensure that the container and binary shipped on it will have the same platform.
+RUN CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build -a -o manager cmd/main.go
+
+# Use distroless as minimal base image to package the manager binary
+# Refer to https://github.com/GoogleContainerTools/distroless for more details
+FROM gcr.io/distroless/static:nonroot
+WORKDIR /
+COPY --from=builder /workspace/manager .
+USER 65532:65532
+
+ENTRYPOINT ["/manager"]
diff --git a/operator/Makefile b/operator/Makefile
new file mode 100644
index 0000000..e0a99ea
--- /dev/null
+++ b/operator/Makefile
@@ -0,0 +1,55 @@
+# Top-level Makefile orchestrator. Targets and their recipes live in
+# make/*.mk by concern (dev / e2e / e2e-gpu / lint / build / deploy /
+# tools). Each sub-file carries its own `##@ Category` header so the
+# `make help` awk command groups them correctly.
+
+# Image URL to use all building/pushing image targets
+IMG ?= controller:latest
+
+# Get the currently used golang install path (in GOPATH/bin, unless GOBIN is set)
+ifeq (,$(shell go env GOBIN))
+GOBIN=$(shell go env GOPATH)/bin
+else
+GOBIN=$(shell go env GOBIN)
+endif
+
+# CONTAINER_TOOL defines the container tool to be used for building images.
+# Be aware that the target commands are only tested with Docker which is
+# scaffolded by default. However, you might want to replace it to use other
+# tools. (i.e. podman)
+CONTAINER_TOOL ?= docker
+
+# Setting SHELL to bash allows bash commands to be executed by recipes.
+# Options are set to exit when a recipe line exits non-zero or a piped command fails.
+SHELL = /usr/bin/env bash -o pipefail
+.SHELLFLAGS = -ec
+
+.PHONY: all
+all: build
+
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. Categories come from `##@ <name>` lines, targets
+# from `<name>: ... ## <description>`. $(MAKEFILE_LIST) expands to this
+# Makefile + every included sub-file, so all sub-files are scanned.
+.PHONY: help
+help: ## Display this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+# Order matters only when one file uses a macro `define`d in another:
+#   - tools.mk defines `gomodver` + `go-install-tool` (used by every
+#     tool-fetcher target it ships).
+#   - dev/e2e/e2e-gpu/lint reference $(KIND), $(KUBECTL), etc. defined
+#     in tools.mk — but those are simple variable references and Make
+#     resolves them lazily, so include order doesn't matter for that.
+# Listing tools.mk first is just stylistic so readers see the
+# variables before the targets that consume them.
+include make/tools.mk
+include make/dev.mk
+include make/unit.mk
+include make/build.mk
+include make/deploy.mk
+include make/lint.mk
+include make/e2e.mk
+include make/e2e-gpu.mk
diff --git a/operator/PROJECT b/operator/PROJECT
new file mode 100644
index 0000000..86421dd
--- /dev/null
+++ b/operator/PROJECT
@@ -0,0 +1,39 @@
+# Code generated by tool. DO NOT EDIT.
+# This file is used to track the info used to scaffold your project
+# and allow the plugins properly work.
+# More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: 4.13.0
+domain: lmcache.ai
+layout:
+- go.kubebuilder.io/v4
+projectName: operator
+repo: github.com/LMCache/LMCache
+resources:
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: lmcache.ai
+  group: lmcache
+  kind: LMCacheEngine
+  path: github.com/LMCache/LMCache/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: lmcache.ai
+  group: lmcache
+  kind: CacheBlendEngine
+  path: github.com/LMCache/LMCache/api/v1alpha1
+  version: v1alpha1
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: lmcache.ai
+  group: lmcache
+  kind: LMCacheCoordinator
+  path: github.com/LMCache/LMCache/api/v1alpha1
+  version: v1alpha1
+version: "3"
diff --git a/operator/README.md b/operator/README.md
new file mode 100644
index 0000000..eab2bf6
--- /dev/null
+++ b/operator/README.md
@@ -0,0 +1,356 @@
+# LMCache Kubernetes Operator
+
+A Kubernetes operator that automates the deployment and lifecycle management of [LMCache](https://github.com/LMCache/LMCache) multiprocess cache servers. It manages a single CRD (`LMCacheEngine`) and reconciles it into a DaemonSet, ConfigMap, Service, and optional ServiceMonitor.
+
+See [DESIGN.md](DESIGN.md) for architecture details, reconciliation logic, and CRD spec reference.
+
+## Prerequisites
+
+- Kubernetes 1.20+
+- `kubectl` configured to access your cluster
+- For NVIDIA GPUs (default): NVIDIA GPU Operator with the `nvidia` RuntimeClass available on GPU nodes
+- For AMD GPUs: set `spec.gpuVendor: amd` in your `LMCacheEngine` (see [AMD GPUs (ROCm)](#amd-gpus-rocm) below)
+- (Optional) [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator) for ServiceMonitor support
+- (CacheBlend only) [cert-manager](https://cert-manager.io) for the injection webhook's serving cert — see [CacheBlend](#cacheblend) below
+
+> [!IMPORTANT]
+> By default the operator runs LMCache pods with `runtimeClassName: nvidia` and `NVIDIA_VISIBLE_DEVICES=all` to gain GPU visibility without consuming GPU resources via the device plugin. This allows the serving engine (e.g., vLLM) to claim all GPUs on the node. On most clusters that is enough; on some, the engine cannot see the GPUs unless the pod is also privileged. Set `spec.privileged: true` to run the engine container in privileged mode (default `false`). When it is enabled, clusters using Pod Security Standards must allow the `privileged` profile for the LMCache namespace.
+>
+> On AMD ROCm clusters, `spec.gpuVendor: amd` omits `runtimeClassName` and skips NVIDIA-specific env vars.
+
+> [!WARNING]
+> **Upgrade note:** earlier operator versions always ran the engine container privileged. `spec.privileged` now defaults to `false`. Upgrading rewrites the DaemonSet pod template (forcing a rolling pod replacement), and on any cluster where privileged was load-bearing for GPU visibility the engine pods will come back up **without** GPU access. If your cluster relied on privileged mode (always the case for `gpuVendor: amd`), set `spec.privileged: true` on existing CRs before upgrading.
+
+## Quick Start
+
+### 1. Install the Operator
+
+**Option A: One-line install from release (recommended)**
+
+Install the latest stable release:
+
+```bash
+kubectl apply -f https://github.com/LMCache/LMCache/releases/download/operator-latest/install.yaml
+```
+
+Or use the nightly build from the `dev` branch:
+
+```bash
+kubectl apply -f https://github.com/LMCache/LMCache/releases/download/operator-nightly-latest/install.yaml
+```
+
+**Option B: Build from source**
+
+```bash
+cd operator
+make build
+make install
+make deploy IMG=<your-registry>/lmcache-operator:latest
+```
+
+### 2. Deploy an LMCacheEngine
+
+The minimal CR just needs `l1.sizeGB`. Apply the sample (a fully-commented field reference covering every option):
+
+```bash
+kubectl apply -f config/samples/lmcache_v1alpha1_lmcacheengine.yaml
+```
+
+The operator automatically handles `hostIPC`, GPU visibility (`runtimeClassName: nvidia`, `NVIDIA_VISIBLE_DEVICES=all`; set `spec.privileged: true` if your cluster also needs privileged mode), node-local service routing, resource sizing, and Prometheus metrics — see [DESIGN.md](DESIGN.md) for details.
+
+### 3. Connect vLLM to LMCache
+
+The operator creates a ConfigMap named `<engine-name>-connection` with the `kv-transfer-config` JSON vLLM needs. A **mutating webhook** injects it into an opted-in vLLM pod automatically — see [Connection injection](#connection-injection) and the sample [`config/samples/vllm_lmcache_deployment.yaml`](config/samples/vllm_lmcache_deployment.yaml).
+
+Key points for vLLM pods:
+
+- **`hostIPC: true` is required** — CUDA IPC (`cudaIpcOpenMemHandle`) needs a shared IPC namespace between vLLM and LMCache. Without this, GPU memory mapping fails.
+- **ConfigMap mount** — the `$(cat ...)` pattern reads the connection JSON and passes it inline to `--kv-transfer-config`. The ConfigMap name is always `<LMCacheEngine name>-connection`.
+- **External LMCache connector required** — the operator-generated config now sets `kv_connector_module_path=lmcache.integration.vllm.lmcache_mp_connector` so vLLM loads the external LMCache MP connector instead of silently resolving a vendored builtin path.
+- **No `hostNetwork` needed** — the operator creates a ClusterIP Service with `internalTrafficPolicy=Local`. kube-proxy routes traffic to the LMCache pod on the same node automatically. The ConfigMap points to the service DNS name, so neither LMCache nor vLLM pods need `hostNetwork`.
+
+> [!IMPORTANT]
+> Use a pinned vLLM image that is new enough to honor `kv_connector_module_path` for KV connector loading. In practice, that means a build that includes the external-module selection fix from vLLM PR #38301 (merged April 7, 2026). Builds that also include vLLM PR #42596 (merged May 15, 2026) are preferred because they default LMCache MP to the external connector with builtin fallback. If your existing vLLM build predates those changes or you are unsure, upgrade it before enabling this operator path.
+
+> [!WARNING]
+> **Do NOT mount an emptyDir at `/dev/shm`** on either LMCache or vLLM pods. With `hostIPC: true`, both pods share the host's `/dev/shm`. Mounting an emptyDir (even with `medium: Memory`) shadows it with a private tmpfs, breaking CUDA IPC — `cudaIpcOpenMemHandle` fails because IPC handles from one pod become invisible to the other.
+
+### 4. Verify the Deployment
+
+```bash
+# Check LMCacheEngine status
+kubectl get lmc
+```
+
+```
+NAME       PHASE     READY   DESIRED   AGE
+my-cache   Running   3       3         5m
+```
+
+```bash
+# Check the connection ConfigMap
+kubectl get configmap my-cache-connection -o yaml
+
+# Check LMCache pods
+kubectl get pods -l app.kubernetes.io/managed-by=lmcache-operator
+
+# Check detailed status with endpoints
+kubectl describe lmc my-cache
+```
+
+## Examples
+
+Every scenario has a ready-to-edit manifest under [`config/samples/`](config/samples/) (`kubectl apply -f config/samples/<file>`):
+
+| Scenario | Sample |
+|---|---|
+| Minimal + **full commented field reference** (GPU `nodeSelector`, custom `server.port`, L2 `raw`/`raw_block`, `resourceOverrides`, …) | [`lmcache_v1alpha1_lmcacheengine.yaml`](config/samples/lmcache_v1alpha1_lmcacheengine.yaml) |
+| Production: Prometheus `ServiceMonitor`, custom port, `priorityClassName` | [`lmcache_v1alpha1_lmcacheengine_production.yaml`](config/samples/lmcache_v1alpha1_lmcacheengine_production.yaml) |
+| L2 storage: Redis/Valkey (optional Secret auth) | [`lmcache_v1alpha1_lmcacheengine_l2_redis.yaml`](config/samples/lmcache_v1alpha1_lmcacheengine_l2_redis.yaml) |
+| AMD GPUs (ROCm) | [`lmcache_v1alpha1_lmcacheengine_amd.yaml`](config/samples/lmcache_v1alpha1_lmcacheengine_amd.yaml) |
+| vLLM Deployment wired to an LMCacheEngine — webhook-injected (see [Connection injection](#connection-injection)) | [`vllm_lmcache_deployment.yaml`](config/samples/vllm_lmcache_deployment.yaml) |
+| CacheBlend engine + opted-in vLLM (see [CacheBlend](#cacheblend)) | [`lmcache_v1alpha1_cacheblendengine.yaml`](config/samples/lmcache_v1alpha1_cacheblendengine.yaml), [`vllm_cacheblend_deployment.yaml`](config/samples/vllm_cacheblend_deployment.yaml) |
+| MP coordinator (fleet-wide registry, L2 quota eviction, global CacheBlend directory) + **commented field reference** | [`lmcache_v1alpha1_lmcachecoordinator.yaml`](config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml) |
+
+Notes:
+
+- **GPU targeting** — `nodeSelector: {nvidia.com/gpu.present: "true"}` runs LMCache only on GPU nodes; new GPU nodes auto-get a pod.
+- **AMD (ROCm)** — `spec.gpuVendor: amd` omits `runtimeClassName` and the NVIDIA env vars; vLLM connects via HIP IPC over `hostIPC` the same way (`PYTHONHASHSEED=0` still required). Supply a `nodeSelector` matching your platform's AMD label and a ROCm-built `spec.image`. AMD has no RuntimeClass-based device injection, so set `spec.privileged: true` to let the engine reach `/dev/kfd`/`/dev/dri` (see the [AMD sample](config/samples/lmcache_v1alpha1_lmcacheengine_amd.yaml)).
+- **Custom port** — set `server.port`; the connection ConfigMap updates automatically and vLLM picks it up on restart.
+- **L2 adapters** — only one at a time today. Redis/Valkey is natively typed; cross-namespace auth Secrets are copied automatically and injected via env (never in args or `kubectl describe`). Other types (`nixl_store`, `fs`, `mock`, `raw_block`) use the `raw` escape hatch — see the commented blocks in the minimal sample. For `raw_block` with `use_odirect: true`, `--l1-align-bytes` must be ≥ `block_align`.
+- **Resources** auto-compute from `l1.sizeGB`; override with `resourceOverrides`.
+
+## Connection injection
+
+Wiring a vLLM Deployment to an LMCacheEngine by hand means mounting the
+`<engine>-connection` ConfigMap and passing
+`--kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"`. A **mutating
+webhook** can do this for you so the vLLM manifest stays clean.
+
+Opt a vLLM pod in with the label `lmcache.ai/lmcache-inject: "true"` and the
+annotation `lmcache.ai/lmcache-engine: "<engine>"` on its pod template, launching
+vLLM via the image ENTRYPOINT (args-only — a `sh -c` wrapper is skipped). At pod
+CREATE the webhook injects, reading the engine's `<engine>-connection` ConfigMap:
+
+- `--kv-transfer-config <JSON>` — the `LMCacheMPConnector` config, inlined onto
+  the vLLM container args (no volume mount needed);
+- `hostIPC: true` — CUDA IPC with the node-local LMCache server;
+- `PYTHONHASHSEED=0` — deterministic prefix hashing (only if you didn't set it).
+
+### Optional: code-payload staging
+
+By default the webhook only wires the connection — vLLM runs whatever `lmcache`
+is baked into its image. To instead pin the vLLM pod to a specific `lmcache`
+build (so the vLLM client and the engine server share one version), set
+`spec.injection.payloadImage` on the `LMCacheEngine`. The webhook then also
+stages that image's `lmcache` tree into the vLLM container, mirroring CacheBlend:
+
+- a shared `emptyDir` (`lmcache-payload`) + a payload **init container** that
+  copies the image's `/payload` tree into it (busybox `cp -a`, no command
+  override);
+- a read-only mount of that volume on the vLLM container;
+- `PYTHONPATH=/lmcache-payload` prepended so vLLM imports the staged `lmcache`;
+- the engine's `injection.imagePullSecrets` merged onto the pod (override per-pod
+  with the `lmcache.ai/lmcache-image-pull-secrets` annotation) for private images.
+
+`payloadImage` is a **separate, purpose-built** image: it must ship the unpacked
+`lmcache` tree under `/payload` and copy it to `$SHARED_DIR` on start (the same
+contract as the CacheBlend payload image). Its `repository` has no valid default,
+so you must set it explicitly; leave `injection` unset for connection-only wiring.
+
+Editable sample: [`config/samples/vllm_lmcache_deployment.yaml`](config/samples/vllm_lmcache_deployment.yaml).
+
+> [!IMPORTANT]
+> The webhook needs `make deploy` (not `make run`) + cert-manager, and the vLLM
+> pod's namespace labeled `pod-security.kubernetes.io/enforce=privileged` (the
+> injected `hostIPC` is rejected by `baseline`/`restricted`). The engine must
+> already be reconciled in the same namespace (its `<engine>-connection`
+> ConfigMap must exist — the webhook reads it).
+
+The webhook mutates **Pods**, not the Deployment, so verify on a pod
+(`kubectl get pod -l app=vllm-lmcache -o yaml | grep -E "hostIPC|kv-transfer-config|lmcache-injected"`).
+If nothing was injected, check the pod's `lmcache.ai/lmcache-skip-reason`
+annotation (`command-override`, `kv-transfer-config-present`, `engine-not-found`,
+or `target-container-not-found`).
+
+## CacheBlend
+
+CacheBlend reuses cached KV at shifted positions. The operator manages it as a
+second CRD (`CacheBlendEngine`) plus a **mutating webhook** that injects the
+`lmcache-cacheblend` plugin into your vLLM pods — no vLLM image rebuild. See
+[DESIGN.md](DESIGN.md#cacheblend-cacheblendengine-crd--injection-webhook) for the
+architecture and the full field reference.
+
+Quick start: deploy an engine, then opt a vLLM pod in with the label
+`lmcache.ai/cacheblend-inject: "true"` and the annotation
+`lmcache.ai/cacheblend-engine: "<engine>"` on its pod template (launch vLLM via the
+image ENTRYPOINT — a `sh -c` wrapper is skipped). Editable samples:
+
+- [`config/samples/lmcache_v1alpha1_cacheblendengine.yaml`](config/samples/lmcache_v1alpha1_cacheblendengine.yaml) — the `CacheBlendEngine`
+- [`config/samples/vllm_cacheblend_deployment.yaml`](config/samples/vllm_cacheblend_deployment.yaml) — an opted-in vLLM Deployment
+
+> [!IMPORTANT]
+> CacheBlend needs the **webhook**, so deploy with `make deploy` (not `make run`,
+> which is controller-only) and install **cert-manager** first
+> (`kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml`).
+> If Pod Security Standards are enforced, label the engine's and the vLLM pod's
+> namespaces `pod-security.kubernetes.io/enforce=privileged` — the webhook injects
+> `hostIPC`/`privileged`, which `baseline`/`restricted` reject.
+
+> [!IMPORTANT]
+> CacheBlend is still in early stage development and under heavy testing. Its
+> docker image will not be publicly released until we are confident that it is
+> ready to be shipped for general use cases. If you would like to try it first,
+> please contact us in Slack Channel.
+
+The webhook mutates **Pods**, not the Deployment, so verify on a pod
+(`kubectl get pod -l app=vllm-cacheblend -o yaml | grep -E "cb-plugin|cacheblend-injected|skip-reason"`).
+If nothing was injected, check the pod's `lmcache.ai/cacheblend-skip-reason`
+annotation (`command-override`, `kv-transfer-config-present`, `engine-not-found`,
+`payload-image-unset`, or `target-container-not-found`).
+
+## Development
+
+```bash
+make generate     # Generate DeepCopy methods
+make manifests    # Generate CRD YAML + RBAC
+make build        # Compile operator binary
+make fmt          # go fmt
+make vet          # go vet
+make test         # Run unit tests (envtest, CPU-only)
+make lint         # Run golangci-lint
+```
+
+### End-to-End Tests
+
+Four `make` targets cover the e2e tiers. The `-kind` variants create
+a throwaway Kind cluster and tear it down on exit; the `-cluster`
+variants run against whatever your current `KUBECONFIG` points at.
+M2 (GPU) targets additionally run a runtime HTTP check against the
+LMCache server and a vLLM round-trip that proves the KV cache
+stores on the first request and retrieves on the second.
+
+```bash
+make test-e2e-kind                                   # local Kind, no GPU, ~5 min
+make test-e2e-cluster        IMG=<registry/image:tag>  # existing cluster, no GPU
+make test-e2e-gpu-kind                               # local Kind, GPU, ~30 min
+make test-e2e-gpu-cluster    IMG=<registry/image:tag>  # existing GPU cluster
+```
+
+#### Tool prerequisites
+
+| Target | Tools to install |
+|---|---|
+| `test-e2e-kind` | `kind`, `kubectl`, `docker` |
+| `test-e2e-cluster` | `kubectl` (cluster access via `KUBECONFIG`) |
+| `test-e2e-gpu-kind` | `kind`, `kubectl`, `docker`, `helm` (v3) |
+| `test-e2e-gpu-cluster` | `kubectl`, `helm` (cluster access via `KUBECONFIG`) |
+
+```bash
+# Install kind (the other tools are distro-specific)
+go install sigs.k8s.io/kind/cmd/kind@latest
+```
+
+#### One-time host setup for `test-e2e-gpu-kind`
+
+Beyond the tools above, your host needs the NVIDIA driver and
+`nvidia-container-toolkit` installed (distro-specific), plus two
+`nvidia-ctk` commands that flip docker's default runtime to `nvidia`
+and toggle the volume-mount-based GPU injection mechanism the
+target's inline Kind config relies on:
+
+```bash
+sudo nvidia-ctk runtime configure --runtime=docker --set-as-default --cdi.enabled
+sudo nvidia-ctk config --set accept-nvidia-visible-devices-as-volume-mounts=true --in-place
+sudo systemctl restart docker
+```
+
+The target fails fast with a copy-pasteable fix command if either
+piece of host config is missing. Note that flipping docker's default
+runtime is a **host-wide** change — every container on the host then
+starts through `nvidia-container-runtime`. Non-GPU workloads still
+work but go through one extra hook.
+
+The target installs the [NVIDIA GPU Operator](https://github.com/NVIDIA/gpu-operator)
+inside the Kind cluster to handle the toolkit / containerd reconfig
+that lets pods scheduled by Kind's inner containerd see the driver
+libraries. That install takes 5-10 min, which is the bulk of the
+`test-e2e-gpu-kind` runtime. (`nvkind` is **not** required — we
+tried it and the current target uses a hand-rolled Kind config
+instead.)
+
+#### Cluster prerequisites for `test-e2e-gpu-cluster`
+
+The existing cluster must have:
+
+- at least one node labeled `nvidia.com/gpu.present=true`
+- the `nvidia` `RuntimeClass` installed (GPU Operator or equivalent)
+- the operator image pushed to a registry the cluster's image puller can reach (pass as `IMG=…`)
+
+#### Knobs (env vars)
+
+| Variable | Default | Used by |
+|---|---|---|
+| `KIND_CLUSTER` | `operator-test-e2e-<id>` | `test-e2e-kind` — set to target an existing Kind cluster |
+| `GPU_KIND_CLUSTER` | `operator-test-e2e-gpu-<id>` | `test-e2e-gpu-kind` — same idea |
+| `KEEP_CLUSTER_ON_FAILURE` | unset | `test-e2e-gpu-kind` — set to `1` to keep the cluster alive after a failure for live debugging |
+| `VLLM_MODEL` | `Qwen/Qwen2.5-0.5B` | vLLM integration spec — Hugging Face model id |
+| `VLLM_IMAGE` | `lmcache/vllm-openai:latest` | vLLM integration spec |
+| `SKIP_VLLM_INTEGRATION` | unset | set to `true` to skip the heavyweight vLLM spec but still run the runtime HTTP check |
+
+If a GPU run fails during setup, use the diagnostic target:
+
+```bash
+make diagnose-test-e2e-gpu-kind GPU_KIND_CLUSTER=<name>
+```
+
+It dumps `ClusterPolicy` status, GPU-Operator pod state, events,
+toolkit/device-plugin daemonset logs, `/dev/nvidia*` inside the Kind
+worker, and the `nvidia` stanza of the worker's containerd config.
+
+For deeper design notes (why GPU Operator over the bare device plugin,
+how the volume-mount marker propagates GPUs into the Kind worker, the
+test specs themselves), see [`AGENTS.md`](./AGENTS.md).
+
+### Pushing a Custom Operator Image
+
+```bash
+# Docker Hub
+docker login
+make docker-build docker-push IMG=docker.io/<your-user>/lmcache-operator:latest
+make deploy IMG=docker.io/<your-user>/lmcache-operator:latest
+
+# Private registry
+docker login <your-registry>
+make docker-build docker-push IMG=<your-registry>/lmcache-operator:latest
+make deploy IMG=<your-registry>/lmcache-operator:latest
+
+# Multi-platform (amd64 + arm64)
+make docker-buildx IMG=<your-registry>/lmcache-operator:latest
+```
+
+If your cluster needs pull credentials, create a secret and reference it in `config/manager/manager.yaml`:
+
+```bash
+kubectl create secret docker-registry regcred \
+  --docker-server=<your-registry> \
+  --docker-username=<username> \
+  --docker-password=<password> \
+  -n lmcache-operator-system
+```
+
+## License
+
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
diff --git a/operator/api/v1alpha1/cacheblendengine_defaults.go b/operator/api/v1alpha1/cacheblendengine_defaults.go
new file mode 100644
index 0000000..eb823d6
--- /dev/null
+++ b/operator/api/v1alpha1/cacheblendengine_defaults.go
@@ -0,0 +1,85 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+// SetDefaults applies defaults that cannot be expressed purely via kubebuilder
+// markers. It mirrors LMCacheEngine.SetDefaults and additionally pins the blend
+// tunables, injection defaults, and the CacheBlend-required chunk size of 256.
+func (e *CacheBlendEngine) SetDefaults() {
+	spec := &e.Spec
+
+	// Default logLevel to INFO if unset (belt-and-suspenders with kubebuilder default).
+	if spec.LogLevel == nil {
+		info := defaultLogLevel
+		spec.LogLevel = &info
+	}
+
+	if spec.GPUVendor == nil {
+		v := GPUVendorNvidia
+		spec.GPUVendor = &v
+	}
+
+	if spec.NodeSelector == nil && *spec.GPUVendor == GPUVendorNvidia {
+		spec.NodeSelector = map[string]string{
+			"nvidia.com/gpu.present": labelValueTrue,
+		}
+	}
+
+	// CacheBlend requires chunk_size == 256 (block_size 64 * 4). Default the
+	// server block and pin chunkSize to 256 if unset.
+	if spec.Server == nil {
+		spec.Server = &ServerSpec{}
+	}
+	if spec.Server.ChunkSize == nil {
+		cs := CacheBlendChunkSize
+		spec.Server.ChunkSize = &cs
+	}
+
+	// Blend tunables.
+	if spec.Blend == nil {
+		spec.Blend = &BlendSpec{}
+	}
+	if spec.Blend.CheckLayer == nil {
+		cl := int32(1)
+		spec.Blend.CheckLayer = &cl
+	}
+	if spec.Blend.RecompRatio == nil {
+		rr := 0.15
+		spec.Blend.RecompRatio = &rr
+	}
+
+	// Injection defaults.
+	if spec.Injection == nil {
+		spec.Injection = &InjectionSpec{}
+	}
+	// payloadImage tag/pullPolicy default when the image is set; repository is
+	// required (no cluster-wide default for the private payload image).
+	if spec.Injection.PayloadImage != nil {
+		if spec.Injection.PayloadImage.Tag == nil {
+			t := "latest"
+			spec.Injection.PayloadImage.Tag = &t
+		}
+		if spec.Injection.PayloadImage.PullPolicy == nil {
+			pp := "IfNotPresent"
+			spec.Injection.PayloadImage.PullPolicy = &pp
+		}
+	}
+	if spec.Injection.Cudagraph == nil {
+		cg := CudagraphEager
+		spec.Injection.Cudagraph = &cg
+	}
+}
diff --git a/operator/api/v1alpha1/cacheblendengine_test.go b/operator/api/v1alpha1/cacheblendengine_test.go
new file mode 100644
index 0000000..b679017
--- /dev/null
+++ b/operator/api/v1alpha1/cacheblendengine_test.go
@@ -0,0 +1,559 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	"testing"
+)
+
+// ptr is defined in lmcacheengine_test.go (same package); reuse it here.
+
+// --- SetDefaults tests ---
+
+func TestCBSetDefaults_LogLevelNil(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.LogLevel == nil || *e.Spec.LogLevel != defaultLogLevel {
+		t.Fatalf("expected LogLevel=INFO, got %v", e.Spec.LogLevel)
+	}
+}
+
+func TestCBSetDefaults_LogLevelPreserved(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:       L1BackendSpec{SizeGB: 10},
+		LogLevel: ptr("DEBUG"),
+	}}
+	e.SetDefaults()
+	if *e.Spec.LogLevel != "DEBUG" {
+		t.Fatalf("expected LogLevel=DEBUG, got %s", *e.Spec.LogLevel)
+	}
+}
+
+func TestCBSetDefaults_NodeSelectorDefaultGPU(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector == nil {
+		t.Fatal("expected default NodeSelector, got nil")
+	}
+	if e.Spec.NodeSelector["nvidia.com/gpu.present"] != labelValueTrue {
+		t.Fatalf("expected nvidia.com/gpu.present=true, got %v", e.Spec.NodeSelector)
+	}
+}
+
+func TestCBSetDefaults_NodeSelectorPreserved(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:           L1BackendSpec{SizeGB: 10},
+		NodeSelector: map[string]string{"custom": "label"},
+	}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector["custom"] != "label" {
+		t.Fatal("expected custom node selector preserved")
+	}
+	if _, ok := e.Spec.NodeSelector["nvidia.com/gpu.present"]; ok {
+		t.Fatal("default should not override user-provided NodeSelector")
+	}
+}
+
+func TestCBSetDefaults_GPUVendorDefaultNvidia(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.GPUVendor == nil || *e.Spec.GPUVendor != GPUVendorNvidia {
+		t.Fatalf("expected GPUVendor=nvidia, got %v", e.Spec.GPUVendor)
+	}
+}
+
+func TestCBSetDefaults_GPUVendorAMDSkipsNodeSelectorDefault(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		GPUVendor: ptr(GPUVendorAMD),
+	}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector != nil {
+		t.Fatalf("expected nil NodeSelector for AMD vendor, got %v", e.Spec.NodeSelector)
+	}
+}
+
+func TestCBSetDefaults_ChunkSizeDefault256(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.Server == nil || e.Spec.Server.ChunkSize == nil {
+		t.Fatal("expected Server.ChunkSize to be defaulted, got nil")
+	}
+	if *e.Spec.Server.ChunkSize != CacheBlendChunkSize {
+		t.Fatalf("expected ChunkSize=256, got %d", *e.Spec.Server.ChunkSize)
+	}
+}
+
+func TestCBSetDefaults_ChunkSizePreserved(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:     L1BackendSpec{SizeGB: 10},
+		Server: &ServerSpec{ChunkSize: ptr(int32(512))},
+	}}
+	e.SetDefaults()
+	if *e.Spec.Server.ChunkSize != 512 {
+		t.Fatalf("expected ChunkSize preserved at 512, got %d", *e.Spec.Server.ChunkSize)
+	}
+}
+
+func TestCBSetDefaults_BlendDefaults(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.Blend == nil {
+		t.Fatal("expected Blend to be defaulted, got nil")
+	}
+	if e.Spec.Blend.CheckLayer == nil || *e.Spec.Blend.CheckLayer != 1 {
+		t.Fatalf("expected CheckLayer=1, got %v", e.Spec.Blend.CheckLayer)
+	}
+	if e.Spec.Blend.RecompRatio == nil || *e.Spec.Blend.RecompRatio != 0.15 {
+		t.Fatalf("expected RecompRatio=0.15, got %v", e.Spec.Blend.RecompRatio)
+	}
+}
+
+func TestCBSetDefaults_BlendPreserved(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:    L1BackendSpec{SizeGB: 10},
+		Blend: &BlendSpec{CheckLayer: ptr(int32(3)), RecompRatio: ptr(0.5)},
+	}}
+	e.SetDefaults()
+	if *e.Spec.Blend.CheckLayer != 3 {
+		t.Fatalf("expected CheckLayer preserved at 3, got %d", *e.Spec.Blend.CheckLayer)
+	}
+	if *e.Spec.Blend.RecompRatio != 0.5 {
+		t.Fatalf("expected RecompRatio preserved at 0.5, got %v", *e.Spec.Blend.RecompRatio)
+	}
+}
+
+func TestCBSetDefaults_InjectionDefaults(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.Injection == nil {
+		t.Fatal("expected Injection to be defaulted, got nil")
+	}
+	if e.Spec.Injection.Cudagraph == nil || *e.Spec.Injection.Cudagraph != CudagraphEager {
+		t.Fatalf("expected Cudagraph=eager, got %v", e.Spec.Injection.Cudagraph)
+	}
+	// payloadImage was not set, so it stays nil (no cluster-wide default).
+	if e.Spec.Injection.PayloadImage != nil {
+		t.Fatalf("expected PayloadImage nil when unset, got %v", e.Spec.Injection.PayloadImage)
+	}
+
+	// When payloadImage is set, tag and pullPolicy default.
+	e2 := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: &InjectionSpec{PayloadImage: &ImageSpec{Repository: ptr("myreg/cacheblend-plugin")}},
+	}}
+	e2.SetDefaults()
+	pi := e2.Spec.Injection.PayloadImage
+	if pi.Tag == nil || *pi.Tag != "latest" {
+		t.Fatalf("expected payloadImage.Tag=latest, got %v", pi.Tag)
+	}
+	if pi.PullPolicy == nil || *pi.PullPolicy != "IfNotPresent" {
+		t.Fatalf("expected payloadImage.PullPolicy=IfNotPresent, got %v", pi.PullPolicy)
+	}
+}
+
+func TestCBSetDefaults_InjectionPreserved(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		Injection: &InjectionSpec{
+			PayloadImage: &ImageSpec{Repository: ptr("myreg/cacheblend-plugin"), Tag: ptr("v1"), PullPolicy: ptr("Always")},
+			Cudagraph:    ptr(CudagraphFullDecodeOnly),
+		},
+	}}
+	e.SetDefaults()
+	if *e.Spec.Injection.PayloadImage.PullPolicy != "Always" {
+		t.Fatalf("expected payloadImage.PullPolicy preserved at Always, got %s", *e.Spec.Injection.PayloadImage.PullPolicy)
+	}
+	if *e.Spec.Injection.PayloadImage.Tag != "v1" {
+		t.Fatalf("expected payloadImage.Tag preserved at v1, got %s", *e.Spec.Injection.PayloadImage.Tag)
+	}
+	if *e.Spec.Injection.Cudagraph != CudagraphFullDecodeOnly {
+		t.Fatalf("expected Cudagraph preserved at full_decode_only, got %s", *e.Spec.Injection.Cudagraph)
+	}
+}
+
+// --- ValidateSpec tests ---
+
+// validCBInjection returns the minimal injection block ValidateSpec requires
+// (injection.payloadImage.repository). Tests that exercise other fields include
+// it so the injection requirement does not perturb their expected error counts.
+func validCBInjection() *InjectionSpec {
+	return &InjectionSpec{PayloadImage: &ImageSpec{Repository: ptr("myreg/cacheblend-plugin")}}
+}
+
+func TestCBValidateSpec_ValidMinimal(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestCBValidateSpec_ValidDefaulted(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+	}}
+	e.SetDefaults()
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors after SetDefaults, got %v", errs)
+	}
+}
+
+func TestCBValidateSpec_InjectionRequired(t *testing.T) {
+	// A spec with no injection block is invalid: the webhook has no payload
+	// image to inject.
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if errs[0].Field != "spec.injection" {
+		t.Fatalf("expected field spec.injection, got %s", errs[0].Field)
+	}
+}
+
+func TestCBValidateSpec_InjectionPayloadRepositoryRequired(t *testing.T) {
+	// injection present but payloadImage.repository empty is invalid.
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: &InjectionSpec{PayloadImage: &ImageSpec{Repository: ptr("")}},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if errs[0].Field != "spec.injection.payloadImage.repository" {
+		t.Fatalf("expected field spec.injection.payloadImage.repository, got %s", errs[0].Field)
+	}
+}
+
+func TestCBValidateSpec_SizeGBZero(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 0},
+		Injection: validCBInjection(),
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if errs[0].Field != "spec.l1.sizeGB" {
+		t.Fatalf("expected field spec.l1.sizeGB, got %s", errs[0].Field)
+	}
+}
+
+func TestCBValidateSpec_SizeGBNegative(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: -1},
+		Injection: validCBInjection(),
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d", len(errs))
+	}
+}
+
+func TestCBValidateSpec_EvictionPolicyInvalid(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+		Eviction:  &EvictionSpec{Policy: ptr("FIFO")},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestCBValidateSpec_EvictionPolicyLRU(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+		Eviction:  &EvictionSpec{Policy: ptr("LRU")},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestCBValidateSpec_TriggerWatermarkBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   float64
+		wantErr bool
+	}{
+		{"zero", 0.0, true},
+		{"negative", -0.1, true},
+		{"valid_low", 0.01, false},
+		{"valid_mid", 0.5, false},
+		{"valid_one", 1.0, false},
+		{"above_one", 1.1, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+				L1:        L1BackendSpec{SizeGB: 10},
+				Injection: validCBInjection(),
+				Eviction:  &EvictionSpec{TriggerWatermark: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestCBValidateSpec_EvictionRatioBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   float64
+		wantErr bool
+	}{
+		{"zero", 0.0, true},
+		{"negative", -0.5, true},
+		{"valid_low", 0.1, false},
+		{"valid_one", 1.0, false},
+		{"above_one", 1.5, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+				L1:        L1BackendSpec{SizeGB: 10},
+				Injection: validCBInjection(),
+				Eviction:  &EvictionSpec{EvictionRatio: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestCBValidateSpec_ServerPort(t *testing.T) {
+	tests := []struct {
+		name    string
+		port    int32
+		wantErr bool
+	}{
+		{"below_min", 80, true},
+		{"min_valid", 1024, false},
+		{"max_valid", 65535, false},
+		{"above_max", 65536, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+				L1:        L1BackendSpec{SizeGB: 10},
+				Injection: validCBInjection(),
+				Server:    &ServerSpec{Port: ptr(tt.port), ChunkSize: ptr(CacheBlendChunkSize)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestCBValidateSpec_ChunkSize(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   int32
+		wantErr bool
+	}{
+		{"valid_256", 256, false},
+		{"too_small", 128, true},
+		{"too_large", 512, true},
+		{"zero", 0, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+				L1:        L1BackendSpec{SizeGB: 10},
+				Injection: validCBInjection(),
+				Server:    &ServerSpec{ChunkSize: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestCBValidateSpec_CheckLayerBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   int32
+		wantErr bool
+	}{
+		{"zero", 0, false},
+		{"positive", 5, false},
+		{"negative", -1, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+				L1:        L1BackendSpec{SizeGB: 10},
+				Injection: validCBInjection(),
+				Blend:     &BlendSpec{CheckLayer: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestCBValidateSpec_RecompRatioBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   float64
+		wantErr bool
+	}{
+		{"zero", 0.0, true},
+		{"negative", -0.1, true},
+		{"valid_low", 0.01, false},
+		{"valid_default", 0.15, false},
+		{"valid_one", 1.0, false},
+		{"above_one", 1.1, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+				L1:        L1BackendSpec{SizeGB: 10},
+				Injection: validCBInjection(),
+				Blend:     &BlendSpec{RecompRatio: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestCBValidateSpec_MultipleErrors(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 0},
+		Injection: validCBInjection(),
+		Server:    &ServerSpec{Port: ptr(int32(80)), ChunkSize: ptr(int32(128))},
+		Eviction: &EvictionSpec{
+			Policy:           ptr("FIFO"),
+			TriggerWatermark: ptr(0.0),
+			EvictionRatio:    ptr(0.0),
+		},
+		Blend: &BlendSpec{CheckLayer: ptr(int32(-1)), RecompRatio: ptr(2.0)},
+	}}
+	errs := e.ValidateSpec()
+	// sizeGB, port, chunkSize, policy, watermark, ratio, checkLayer, recompRatio = 8 errors
+	if len(errs) != 8 {
+		t.Fatalf("expected 8 errors, got %d: %v", len(errs), errs)
+	}
+}
+
+// --- L2 Backend validation tests ---
+
+func TestCBValidateSpec_L2RESPValid(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{
+				Host: "redis.default.svc",
+				Port: 6379,
+			},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestCBValidateSpec_L2RESPEmptyHost(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{
+				Host: "",
+				Port: 6379,
+			},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if errs[0].Field != "spec.l2Backend.resp.host" {
+		t.Fatalf("expected field spec.l2Backend.resp.host, got %s", errs[0].Field)
+	}
+}
+
+func TestCBValidateSpec_L2NoneSet(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+		L2Backend: &L2BackendSpec{},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestCBValidateSpec_L2BothSet(t *testing.T) {
+	e := &CacheBlendEngine{Spec: CacheBlendEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		Injection: validCBInjection(),
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{Host: "redis", Port: 6379},
+			Raw:  &RawL2AdapterSpec{Type: "mock"},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
diff --git a/operator/api/v1alpha1/cacheblendengine_types.go b/operator/api/v1alpha1/cacheblendengine_types.go
new file mode 100644
index 0000000..0ffc3be
--- /dev/null
+++ b/operator/api/v1alpha1/cacheblendengine_types.go
@@ -0,0 +1,280 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// CacheBlendChunkSize is the only chunk size CacheBlend supports. The blend
+// matcher requires chunk_size == vLLM --block-size (64) * 4 == 256, so the
+// CacheBlendEngine server is locked to this value (see design §4).
+const CacheBlendChunkSize int32 = 256
+
+// Cudagraph mode constants for CacheBlendEngine injection.
+const (
+	// CudagraphEager forces eager execution (--enforce-eager). Default.
+	CudagraphEager = "eager"
+	// CudagraphPiecewise enables piecewise CUDA graph capture.
+	CudagraphPiecewise = "piecewise"
+	// CudagraphFullDecodeOnly enables full CUDA graphs for decode only.
+	CudagraphFullDecodeOnly = "full_decode_only"
+)
+
+// BlendSpec defines the CacheBlend tunables injected into the vLLM connect-config.
+type BlendSpec struct {
+	// checkLayer is the layer index used by CacheBlend to decide which tokens
+	// to recompute. It is surfaced to the connector as
+	// kv_connector_extra_config["cb.check_layer"].
+	// +optional
+	// +kubebuilder:default=1
+	// +kubebuilder:validation:Minimum=0
+	CheckLayer *int32 `json:"checkLayer,omitempty"`
+
+	// recompRatio is the fraction of tokens CacheBlend recomputes. It is
+	// surfaced to the connector as kv_connector_extra_config["cb.recomp_ratio"]
+	// and must be in (0, 1].
+	// +optional
+	// +kubebuilder:default=0.15
+	RecompRatio *float64 `json:"recompRatio,omitempty"`
+}
+
+// InjectionSpec defines the defaults the mutating webhook reads when injecting
+// the CacheBlend payload into vLLM pods bound to this engine (see design §7, §8).
+type InjectionSpec struct {
+	// payloadImage is the init-container image (repository/tag/pullPolicy, like
+	// spec.image) that stages the lmcache-cacheblend vLLM plugin into a shared
+	// emptyDir. It is a SEPARATE, usually PRIVATE image: set
+	// payloadImage.repository to your cacheblend-plugin image — the repository
+	// default inherited from ImageSpec is the engine image and is NOT a valid
+	// payload. For private registries, imagePullSecrets must reference Secret(s)
+	// that exist in the vLLM pod's namespace.
+	// +optional
+	PayloadImage *ImageSpec `json:"payloadImage,omitempty"`
+
+	// imagePullSecrets are appended to the vLLM pod's spec.imagePullSecrets so
+	// the PRIVATE payload init-container image can pull. The referenced
+	// Secret(s) must already exist in the vLLM pod's namespace; the operator
+	// does not copy them cross-namespace.
+	// +optional
+	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
+
+	// targetContainer is the name of the vLLM container to inject into. Empty
+	// (the default) selects the first container; a per-pod annotation may
+	// override it.
+	// +optional
+	TargetContainer *string `json:"targetContainer,omitempty"`
+
+	// cudagraph selects the CUDA graph mode injected into the vLLM args. "eager"
+	// (default) maps to --enforce-eager; "full_decode_only" enables decode-only
+	// graphs. Full graphs are never used.
+	// +optional
+	// +kubebuilder:default="eager"
+	// +kubebuilder:validation:Enum=eager;piecewise;full_decode_only
+	Cudagraph *string `json:"cudagraph,omitempty"`
+}
+
+// CacheBlendEngineSpec defines the desired state of CacheBlendEngine. It mirrors
+// LMCacheEngineSpec (reusing its shared sub-structs) and adds the blend tunables
+// and injection defaults specific to CacheBlend.
+type CacheBlendEngineSpec struct {
+	// gpuVendor selects the GPU vendor. "nvidia" (default) requires the NVIDIA
+	// GPU Operator's "nvidia" RuntimeClass; "amd" runs on the default container
+	// runtime.
+	// +optional
+	// +kubebuilder:default="nvidia"
+	// +kubebuilder:validation:Enum=nvidia;amd
+	GPUVendor *string `json:"gpuVendor,omitempty"`
+
+	// image defines the container image to use for the blend_v3 engine. This
+	// may be a PRIVATE image; use imagePullSecrets to pull it.
+	// +optional
+	Image *ImageSpec `json:"image,omitempty"`
+
+	// imagePullSecrets is a list of references to secrets for pulling the
+	// engine image.
+	// +optional
+	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
+
+	// server defines server configuration. chunkSize defaults to 256 because
+	// CacheBlend requires chunk_size == 256.
+	// +optional
+	Server *ServerSpec `json:"server,omitempty"`
+
+	// l1 defines the L1 memory cache configuration.
+	L1 L1BackendSpec `json:"l1"`
+
+	// eviction defines the cache eviction configuration.
+	// +optional
+	Eviction *EvictionSpec `json:"eviction,omitempty"`
+
+	// prometheus defines Prometheus monitoring configuration.
+	// +optional
+	Prometheus *PrometheusSpec `json:"prometheus,omitempty"`
+
+	// l2Backend defines the L2 storage backend.
+	// Currently only a single adapter is supported.
+	// +optional
+	L2Backend *L2BackendSpec `json:"l2Backend,omitempty"`
+
+	// coordinator configures registration with an MP coordinator. When unset,
+	// the server does not register with any coordinator.
+	// +optional
+	Coordinator *CoordinatorConnectionSpec `json:"coordinator,omitempty"`
+
+	// blend defines the CacheBlend tunables injected into the vLLM connect-config.
+	// +optional
+	Blend *BlendSpec `json:"blend,omitempty"`
+
+	// injection defines the defaults the mutating webhook reads for pods bound
+	// to this engine.
+	// +optional
+	Injection *InjectionSpec `json:"injection,omitempty"`
+
+	// resourceOverrides allows overriding auto-computed resource requirements.
+	// +optional
+	ResourceOverrides *corev1.ResourceRequirements `json:"resourceOverrides,omitempty"`
+
+	// logLevel is the log level for the LMCache server.
+	// +optional
+	// +kubebuilder:default="INFO"
+	// +kubebuilder:validation:Enum=DEBUG;INFO;WARNING;ERROR
+	LogLevel *string `json:"logLevel,omitempty"`
+
+	// nodeSelector determines which nodes get a CacheBlend engine instance.
+	// +optional
+	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
+
+	// affinity defines pod scheduling affinity rules.
+	// +optional
+	Affinity *corev1.Affinity `json:"affinity,omitempty"`
+
+	// tolerations defines pod tolerations.
+	// +optional
+	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
+
+	// env defines additional environment variables.
+	// +optional
+	Env []corev1.EnvVar `json:"env,omitempty"`
+
+	// volumes defines additional volumes.
+	// +optional
+	Volumes []corev1.Volume `json:"volumes,omitempty"`
+
+	// volumeMounts defines additional volume mounts.
+	// +optional
+	VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"`
+
+	// podAnnotations are additional annotations added to pods.
+	// +optional
+	PodAnnotations map[string]string `json:"podAnnotations,omitempty"`
+
+	// podLabels are additional labels added to pods.
+	// +optional
+	PodLabels map[string]string `json:"podLabels,omitempty"`
+
+	// serviceAccountName is the name of the ServiceAccount to use.
+	// +optional
+	ServiceAccountName string `json:"serviceAccountName,omitempty"`
+
+	// priorityClassName is the priority class for the pods.
+	// +optional
+	PriorityClassName string `json:"priorityClassName,omitempty"`
+
+	// privileged runs the engine container in privileged mode. On some clusters
+	// this is required for the engine to see all node GPUs (for CUDA IPC) without
+	// claiming any via the nvidia.com/gpu device plugin; on many clusters
+	// NVIDIA_VISIBLE_DEVICES=all already grants that visibility without it, so it
+	// defaults to false. Set it to true only on clusters where the engine cannot
+	// otherwise see the GPUs.
+	// +optional
+	// +kubebuilder:default=false
+	Privileged *bool `json:"privileged,omitempty"`
+
+	// extraArgs are additional CLI flags appended to the server command.
+	// They are appended last and can override any auto-generated flag.
+	// +optional
+	ExtraArgs []string `json:"extraArgs,omitempty"`
+}
+
+// CacheBlendEngineStatus defines the observed state of CacheBlendEngine.
+type CacheBlendEngineStatus struct {
+	// phase is the overall phase of the CacheBlendEngine.
+	// +optional
+	Phase string `json:"phase,omitempty"`
+
+	// observedGeneration is the most recent generation observed.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// desiredInstances is the number of desired instances.
+	// +optional
+	DesiredInstances int32 `json:"desiredInstances,omitempty"`
+
+	// readyInstances is the number of ready instances.
+	// +optional
+	ReadyInstances int32 `json:"readyInstances,omitempty"`
+
+	// endpoints lists per-node connection info.
+	// +optional
+	Endpoints []EndpointStatus `json:"endpoints,omitempty"`
+
+	// conditions represent the current state of the CacheBlendEngine resource.
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName=cbe
+// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
+// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyInstances`
+// +kubebuilder:printcolumn:name="Desired",type=integer,JSONPath=`.status.desiredInstances`
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// CacheBlendEngine is the Schema for the cacheblendengines API.
+type CacheBlendEngine struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata.
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitzero"`
+
+	// spec defines the desired state of CacheBlendEngine.
+	// +required
+	Spec CacheBlendEngineSpec `json:"spec"`
+
+	// status defines the observed state of CacheBlendEngine.
+	// +optional
+	Status CacheBlendEngineStatus `json:"status,omitzero"`
+}
+
+// +kubebuilder:object:root=true
+
+// CacheBlendEngineList contains a list of CacheBlendEngine.
+type CacheBlendEngineList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitzero"`
+	Items           []CacheBlendEngine `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&CacheBlendEngine{}, &CacheBlendEngineList{})
+}
diff --git a/operator/api/v1alpha1/cacheblendengine_validation.go b/operator/api/v1alpha1/cacheblendengine_validation.go
new file mode 100644
index 0000000..9cccf44
--- /dev/null
+++ b/operator/api/v1alpha1/cacheblendengine_validation.go
@@ -0,0 +1,92 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+// ValidateSpec validates the CacheBlendEngineSpec and returns any validation
+// errors. It mirrors LMCacheEngine.ValidateSpec and additionally enforces the
+// CacheBlend invariants: chunkSize == 256, recompRatio in (0, 1], and
+// checkLayer >= 0.
+func (e *CacheBlendEngine) ValidateSpec() field.ErrorList {
+	var errs field.ErrorList
+	spec := &e.Spec
+
+	// l1.sizeGB must be > 0
+	if spec.L1.SizeGB <= 0 {
+		errs = append(errs, field.Invalid(field.NewPath("spec", "l1", "sizeGB"), spec.L1.SizeGB, "must be greater than 0"))
+	}
+
+	errs = append(errs, validateEvictionSpec(spec.Eviction)...)
+
+	// Server validation
+	if spec.Server != nil {
+		serverPath := field.NewPath("spec", "server")
+
+		if spec.Server.Port != nil {
+			port := *spec.Server.Port
+			if port < 1024 || port > 65535 {
+				errs = append(errs, field.Invalid(serverPath.Child("port"), port, "must be in [1024, 65535]"))
+			}
+		}
+
+		// CacheBlend requires chunk_size == 256 (block_size 64 * 4).
+		if spec.Server.ChunkSize != nil && *spec.Server.ChunkSize != CacheBlendChunkSize {
+			errs = append(errs, field.Invalid(serverPath.Child("chunkSize"), *spec.Server.ChunkSize,
+				"must be 256 for CacheBlend (chunk_size == block_size 64 * 4)"))
+		}
+	}
+
+	// Blend validation
+	if spec.Blend != nil {
+		blendPath := field.NewPath("spec", "blend")
+
+		if spec.Blend.CheckLayer != nil && *spec.Blend.CheckLayer < 0 {
+			errs = append(errs, field.Invalid(blendPath.Child("checkLayer"), *spec.Blend.CheckLayer, "must be >= 0"))
+		}
+
+		if spec.Blend.RecompRatio != nil {
+			rr := *spec.Blend.RecompRatio
+			if rr <= 0.0 || rr > 1.0 {
+				errs = append(errs, field.Invalid(blendPath.Child("recompRatio"), rr, "must be in (0.0, 1.0]"))
+			}
+		}
+	}
+
+	// Injection validation. injection.payloadImage.repository is functionally
+	// required: the mutating webhook needs it to inject a valid init container.
+	// Without it the webhook would produce a Pod with an empty init-container
+	// image, which the API server rejects at Pod creation. Enforce it here so
+	// the misconfiguration is caught at `kubectl apply` time instead.
+	injPath := field.NewPath("spec", "injection")
+	if spec.Injection == nil {
+		errs = append(errs, field.Required(injPath, "must be specified for CacheBlend injection"))
+	} else if spec.Injection.PayloadImage == nil {
+		errs = append(errs, field.Required(injPath.Child("payloadImage"),
+			"must be specified for CacheBlend injection"))
+	} else if spec.Injection.PayloadImage.Repository == nil || *spec.Injection.PayloadImage.Repository == "" {
+		errs = append(errs, field.Required(injPath.Child("payloadImage", "repository"),
+			"must be a non-empty string"))
+	}
+
+	errs = append(errs, validateL2BackendSpec(spec.L2Backend)...)
+	errs = append(errs, validateCoordinatorConnectionSpec(spec.Coordinator)...)
+
+	return errs
+}
diff --git a/operator/api/v1alpha1/groupversion_info.go b/operator/api/v1alpha1/groupversion_info.go
new file mode 100644
index 0000000..63e1368
--- /dev/null
+++ b/operator/api/v1alpha1/groupversion_info.go
@@ -0,0 +1,36 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package v1alpha1 contains API Schema definitions for the lmcache v1alpha1 API group.
+// +kubebuilder:object:generate=true
+// +groupName=lmcache.lmcache.ai
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/scheme"
+)
+
+var (
+	// GroupVersion is group version used to register these objects.
+	GroupVersion = schema.GroupVersion{Group: "lmcache.lmcache.ai", Version: "v1alpha1"}
+
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme.
+	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
+
+	// AddToScheme adds the types in this group-version to the given scheme.
+	AddToScheme = SchemeBuilder.AddToScheme
+)
diff --git a/operator/api/v1alpha1/lmcachecoordinator_defaults.go b/operator/api/v1alpha1/lmcachecoordinator_defaults.go
new file mode 100644
index 0000000..7f5a38f
--- /dev/null
+++ b/operator/api/v1alpha1/lmcachecoordinator_defaults.go
@@ -0,0 +1,38 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+// defaultCoordinatorReplicas is the replica count applied when spec.replicas is
+// unset (belt-and-suspenders with the kubebuilder default).
+const defaultCoordinatorReplicas int32 = 1
+
+// SetDefaults applies defaults that cannot be expressed purely via kubebuilder
+// markers. The numeric coordinator knobs (port, timeouts, ratios) are defaulted
+// by their kubebuilder markers, matching MPCoordinatorConfig.
+func (c *LMCacheCoordinator) SetDefaults() {
+	spec := &c.Spec
+
+	if spec.LogLevel == nil {
+		info := defaultLogLevel
+		spec.LogLevel = &info
+	}
+
+	if spec.Replicas == nil {
+		r := defaultCoordinatorReplicas
+		spec.Replicas = &r
+	}
+}
diff --git a/operator/api/v1alpha1/lmcachecoordinator_types.go b/operator/api/v1alpha1/lmcachecoordinator_types.go
new file mode 100644
index 0000000..5659371
--- /dev/null
+++ b/operator/api/v1alpha1/lmcachecoordinator_types.go
@@ -0,0 +1,238 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// LMCacheCoordinatorSpec defines the desired state of LMCacheCoordinator. The
+// fields mirror the coordinator's MPCoordinatorConfig (see
+// lmcache/v1/mp_coordinator/config.py); the controller renders them into the
+// matching `lmcache coordinator` CLI flags.
+type LMCacheCoordinatorSpec struct {
+	// image defines the container image to use. The coordinator runs the same
+	// lmcache binary as the engines, so it shares the default image.
+	// +optional
+	Image *ImageSpec `json:"image,omitempty"`
+
+	// imagePullSecrets is a list of references to secrets for pulling the image.
+	// +optional
+	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
+
+	// replicas is the number of coordinator pods. The coordinator's in-memory
+	// registry is per-process, so running more than one replica only makes sense
+	// behind a shared durable backend; the default of 1 fits the common case.
+	// +optional
+	// +kubebuilder:default=1
+	// +kubebuilder:validation:Minimum=0
+	Replicas *int32 `json:"replicas,omitempty"`
+
+	// host is the address the coordinator's HTTP server binds to.
+	// +optional
+	// +kubebuilder:default="0.0.0.0"
+	Host *string `json:"host,omitempty"`
+
+	// port is the port the coordinator's HTTP server binds to.
+	// +optional
+	// +kubebuilder:default=9300
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=65535
+	Port *int32 `json:"port,omitempty"`
+
+	// instanceTimeout is the seconds without a heartbeat after which an instance
+	// is evicted. Must be > 0.
+	// +optional
+	// +kubebuilder:default=30
+	InstanceTimeout *float64 `json:"instanceTimeout,omitempty"`
+
+	// healthCheckInterval is the seconds between health-check sweeps. 0 disables
+	// the loop.
+	// +optional
+	// +kubebuilder:default=10
+	HealthCheckInterval *float64 `json:"healthCheckInterval,omitempty"`
+
+	// evictionCheckInterval is the seconds between L2 eviction sweeps. 0 disables
+	// the loop.
+	// +optional
+	// +kubebuilder:default=5
+	EvictionCheckInterval *float64 `json:"evictionCheckInterval,omitempty"`
+
+	// evictionRatio is the fraction of tracked keys (by count) to evict per
+	// cycle, in [0.0, 1.0].
+	// +optional
+	// +kubebuilder:default=0.2
+	EvictionRatio *float64 `json:"evictionRatio,omitempty"`
+
+	// triggerWatermark is the usage fraction of the quota that fires eviction,
+	// in (0.0, 1.0].
+	// +optional
+	// +kubebuilder:default=1
+	TriggerWatermark *float64 `json:"triggerWatermark,omitempty"`
+
+	// blendChunkSize is the tokens per chunk for the global CacheBlend directory
+	// (the match unit). It MUST equal the LMCache chunk size the blend servers
+	// use, so the coordinator chunks published/queried tokens the same way.
+	// When unset the coordinator image applies its own default (256); the
+	// operator only passes --blend-chunk-size when this is explicitly set, so it
+	// stays compatible with images whose CLI predates the flag.
+	// +optional
+	// +kubebuilder:validation:Minimum=1
+	BlendChunkSize *int32 `json:"blendChunkSize,omitempty"`
+
+	// blendProbeStride is the number of positions between CacheBlend match
+	// probes. With partial-fill reuse any offset is usable, so 1 (probe every
+	// offset) gives full recall; raise it only to trade recall for coordinator
+	// CPU. When unset the coordinator image applies its own default (1); the
+	// operator only passes --blend-probe-stride when this is explicitly set, so
+	// it stays compatible with images whose CLI predates the flag.
+	// +optional
+	// +kubebuilder:validation:Minimum=1
+	BlendProbeStride *int32 `json:"blendProbeStride,omitempty"`
+
+	// prometheus defines Prometheus monitoring configuration. The coordinator
+	// process does not yet expose a /metrics endpoint, so the ServiceMonitor is
+	// disabled by default; enabling it is only useful once metrics are added.
+	// +optional
+	Prometheus *PrometheusSpec `json:"prometheus,omitempty"`
+
+	// resourceOverrides allows overriding the coordinator pod's resource
+	// requirements.
+	// +optional
+	ResourceOverrides *corev1.ResourceRequirements `json:"resourceOverrides,omitempty"`
+
+	// logLevel is the log level for the coordinator process.
+	// +optional
+	// +kubebuilder:default="INFO"
+	// +kubebuilder:validation:Enum=DEBUG;INFO;WARNING;ERROR
+	LogLevel *string `json:"logLevel,omitempty"`
+
+	// nodeSelector constrains which nodes the coordinator runs on.
+	// +optional
+	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
+
+	// affinity defines pod scheduling affinity rules.
+	// +optional
+	Affinity *corev1.Affinity `json:"affinity,omitempty"`
+
+	// tolerations defines pod tolerations.
+	// +optional
+	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
+
+	// env defines additional environment variables.
+	// +optional
+	Env []corev1.EnvVar `json:"env,omitempty"`
+
+	// volumes defines additional volumes.
+	// +optional
+	Volumes []corev1.Volume `json:"volumes,omitempty"`
+
+	// volumeMounts defines additional volume mounts.
+	// +optional
+	VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"`
+
+	// podAnnotations are additional annotations added to the coordinator pod.
+	// +optional
+	PodAnnotations map[string]string `json:"podAnnotations,omitempty"`
+
+	// podLabels are additional labels added to the coordinator pod.
+	// +optional
+	PodLabels map[string]string `json:"podLabels,omitempty"`
+
+	// serviceAccountName is the name of the ServiceAccount to use.
+	// +optional
+	ServiceAccountName string `json:"serviceAccountName,omitempty"`
+
+	// priorityClassName is the priority class for the coordinator pod.
+	// +optional
+	PriorityClassName string `json:"priorityClassName,omitempty"`
+
+	// extraArgs are additional CLI flags appended to the coordinator command.
+	// They are appended last and can override any auto-generated flag.
+	// +optional
+	ExtraArgs []string `json:"extraArgs,omitempty"`
+}
+
+// LMCacheCoordinatorStatus defines the observed state of LMCacheCoordinator.
+type LMCacheCoordinatorStatus struct {
+	// phase is the overall phase of the LMCacheCoordinator.
+	// +optional
+	Phase string `json:"phase,omitempty"`
+
+	// observedGeneration is the most recent generation observed.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// replicas is the number of desired coordinator pods.
+	// +optional
+	Replicas int32 `json:"replicas,omitempty"`
+
+	// readyReplicas is the number of ready coordinator pods.
+	// +optional
+	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
+
+	// endpoint is the in-cluster URL other components use to reach the
+	// coordinator, e.g. http://<name>.<namespace>.svc:9300.
+	// +optional
+	Endpoint string `json:"endpoint,omitempty"`
+
+	// conditions represent the current state of the LMCacheCoordinator resource.
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName=lmcc
+// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
+// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyReplicas`
+// +kubebuilder:printcolumn:name="Replicas",type=integer,JSONPath=`.status.replicas`
+// +kubebuilder:printcolumn:name="Endpoint",type=string,JSONPath=`.status.endpoint`
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// LMCacheCoordinator is the Schema for the lmcachecoordinators API.
+type LMCacheCoordinator struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata.
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitzero"`
+
+	// spec defines the desired state of LMCacheCoordinator.
+	// +required
+	Spec LMCacheCoordinatorSpec `json:"spec"`
+
+	// status defines the observed state of LMCacheCoordinator.
+	// +optional
+	Status LMCacheCoordinatorStatus `json:"status,omitzero"`
+}
+
+// +kubebuilder:object:root=true
+
+// LMCacheCoordinatorList contains a list of LMCacheCoordinator.
+type LMCacheCoordinatorList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitzero"`
+	Items           []LMCacheCoordinator `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&LMCacheCoordinator{}, &LMCacheCoordinatorList{})
+}
diff --git a/operator/api/v1alpha1/lmcachecoordinator_validation.go b/operator/api/v1alpha1/lmcachecoordinator_validation.go
new file mode 100644
index 0000000..14dce7b
--- /dev/null
+++ b/operator/api/v1alpha1/lmcachecoordinator_validation.go
@@ -0,0 +1,78 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+// ValidateSpec validates the LMCacheCoordinatorSpec and returns any validation
+// errors. The checks mirror MPCoordinatorConfig.__post_init__
+// (lmcache/v1/mp_coordinator/config.py) so an invalid spec is rejected before
+// the coordinator pod would fail to start.
+func (c *LMCacheCoordinator) ValidateSpec() field.ErrorList {
+	var errs field.ErrorList
+	spec := &c.Spec
+	specPath := field.NewPath("spec")
+
+	if spec.Port != nil {
+		port := *spec.Port
+		if port < 1 || port > 65535 {
+			errs = append(errs, field.Invalid(specPath.Child("port"), port, "must be in [1, 65535]"))
+		}
+	}
+
+	if spec.Replicas != nil && *spec.Replicas < 0 {
+		errs = append(errs, field.Invalid(specPath.Child("replicas"), *spec.Replicas, "must be >= 0"))
+	}
+
+	if spec.InstanceTimeout != nil && *spec.InstanceTimeout <= 0 {
+		errs = append(errs, field.Invalid(specPath.Child("instanceTimeout"), *spec.InstanceTimeout, "must be greater than 0"))
+	}
+
+	if spec.HealthCheckInterval != nil && *spec.HealthCheckInterval < 0 {
+		errs = append(errs, field.Invalid(specPath.Child("healthCheckInterval"), *spec.HealthCheckInterval, "must be >= 0"))
+	}
+
+	if spec.EvictionCheckInterval != nil && *spec.EvictionCheckInterval < 0 {
+		errs = append(errs, field.Invalid(specPath.Child("evictionCheckInterval"), *spec.EvictionCheckInterval, "must be >= 0"))
+	}
+
+	if spec.EvictionRatio != nil {
+		er := *spec.EvictionRatio
+		if er < 0.0 || er > 1.0 {
+			errs = append(errs, field.Invalid(specPath.Child("evictionRatio"), er, "must be in [0.0, 1.0]"))
+		}
+	}
+
+	if spec.TriggerWatermark != nil {
+		tw := *spec.TriggerWatermark
+		if tw <= 0.0 || tw > 1.0 {
+			errs = append(errs, field.Invalid(specPath.Child("triggerWatermark"), tw, "must be in (0.0, 1.0]"))
+		}
+	}
+
+	if spec.BlendChunkSize != nil && *spec.BlendChunkSize < 1 {
+		errs = append(errs, field.Invalid(specPath.Child("blendChunkSize"), *spec.BlendChunkSize, "must be > 0"))
+	}
+
+	if spec.BlendProbeStride != nil && *spec.BlendProbeStride < 1 {
+		errs = append(errs, field.Invalid(specPath.Child("blendProbeStride"), *spec.BlendProbeStride, "must be > 0"))
+	}
+
+	return errs
+}
diff --git a/operator/api/v1alpha1/lmcacheengine_defaults.go b/operator/api/v1alpha1/lmcacheengine_defaults.go
new file mode 100644
index 0000000..0c910e4
--- /dev/null
+++ b/operator/api/v1alpha1/lmcacheengine_defaults.go
@@ -0,0 +1,47 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+// defaultLogLevel is the log level applied when spec.logLevel is unset (it
+// mirrors the kubebuilder default on both engine kinds).
+const defaultLogLevel = "INFO"
+
+// labelValueTrue is the string value of boolean-style node-selector labels
+// (e.g. nvidia.com/gpu.present: "true").
+const labelValueTrue = "true"
+
+// SetDefaults applies defaults that cannot be expressed purely via kubebuilder markers.
+func (e *LMCacheEngine) SetDefaults() {
+	spec := &e.Spec
+
+	// Default logLevel to INFO if unset (belt-and-suspenders with kubebuilder default).
+	if spec.LogLevel == nil {
+		info := defaultLogLevel
+		spec.LogLevel = &info
+	}
+
+	if spec.GPUVendor == nil {
+		v := GPUVendorNvidia
+		spec.GPUVendor = &v
+	}
+
+	if spec.NodeSelector == nil && *spec.GPUVendor == GPUVendorNvidia {
+		spec.NodeSelector = map[string]string{
+			"nvidia.com/gpu.present": labelValueTrue,
+		}
+	}
+}
diff --git a/operator/api/v1alpha1/lmcacheengine_test.go b/operator/api/v1alpha1/lmcacheengine_test.go
new file mode 100644
index 0000000..2efcf9c
--- /dev/null
+++ b/operator/api/v1alpha1/lmcacheengine_test.go
@@ -0,0 +1,378 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	"testing"
+)
+
+// --- helpers ---
+
+func ptr[T any](v T) *T { return &v }
+
+// --- SetDefaults tests ---
+
+func TestSetDefaults_LogLevelNil(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.LogLevel == nil || *e.Spec.LogLevel != defaultLogLevel {
+		t.Fatalf("expected LogLevel=INFO, got %v", e.Spec.LogLevel)
+	}
+}
+
+func TestSetDefaults_LogLevelPreserved(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:       L1BackendSpec{SizeGB: 10},
+		LogLevel: ptr("DEBUG"),
+	}}
+	e.SetDefaults()
+	if *e.Spec.LogLevel != "DEBUG" {
+		t.Fatalf("expected LogLevel=DEBUG, got %s", *e.Spec.LogLevel)
+	}
+}
+
+func TestSetDefaults_NodeSelectorDefaultGPU(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector == nil {
+		t.Fatal("expected default NodeSelector, got nil")
+	}
+	if e.Spec.NodeSelector["nvidia.com/gpu.present"] != labelValueTrue {
+		t.Fatalf("expected nvidia.com/gpu.present=true, got %v", e.Spec.NodeSelector)
+	}
+}
+
+func TestSetDefaults_NodeSelectorPreserved(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:           L1BackendSpec{SizeGB: 10},
+		NodeSelector: map[string]string{"custom": "label"},
+	}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector["custom"] != "label" {
+		t.Fatal("expected custom node selector preserved")
+	}
+	if _, ok := e.Spec.NodeSelector["nvidia.com/gpu.present"]; ok {
+		t.Fatal("default should not override user-provided NodeSelector")
+	}
+}
+
+func TestSetDefaults_GPUVendorDefaultNvidia(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	e.SetDefaults()
+	if e.Spec.GPUVendor == nil || *e.Spec.GPUVendor != GPUVendorNvidia {
+		t.Fatalf("expected GPUVendor=nvidia, got %v", e.Spec.GPUVendor)
+	}
+}
+
+func TestSetDefaults_GPUVendorAMDSkipsNodeSelectorDefault(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		GPUVendor: ptr(GPUVendorAMD),
+	}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector != nil {
+		t.Fatalf("expected nil NodeSelector for AMD vendor, got %v", e.Spec.NodeSelector)
+	}
+}
+
+func TestSetDefaults_GPUVendorAMDPreservesUserNodeSelector(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:           L1BackendSpec{SizeGB: 10},
+		GPUVendor:    ptr(GPUVendorAMD),
+		NodeSelector: map[string]string{"feature.node.kubernetes.io/amd-gpu": labelValueTrue},
+	}}
+	e.SetDefaults()
+	if e.Spec.NodeSelector["feature.node.kubernetes.io/amd-gpu"] != labelValueTrue {
+		t.Fatalf("expected user-supplied AMD NodeSelector preserved, got %v", e.Spec.NodeSelector)
+	}
+}
+
+// --- ValidateSpec tests ---
+
+func TestValidateSpec_ValidMinimal(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{L1: L1BackendSpec{SizeGB: 10}}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestValidateSpec_SizeGBZero(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{L1: L1BackendSpec{SizeGB: 0}}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if errs[0].Field != "spec.l1.sizeGB" {
+		t.Fatalf("expected field spec.l1.sizeGB, got %s", errs[0].Field)
+	}
+}
+
+func TestValidateSpec_SizeGBNegative(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{L1: L1BackendSpec{SizeGB: -1}}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d", len(errs))
+	}
+}
+
+func TestValidateSpec_EvictionPolicyInvalid(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:       L1BackendSpec{SizeGB: 10},
+		Eviction: &EvictionSpec{Policy: ptr("FIFO")},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestValidateSpec_EvictionPolicyLRU(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:       L1BackendSpec{SizeGB: 10},
+		Eviction: &EvictionSpec{Policy: ptr("LRU")},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestValidateSpec_TriggerWatermarkBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   float64
+		wantErr bool
+	}{
+		{"zero", 0.0, true},
+		{"negative", -0.1, true},
+		{"valid_low", 0.01, false},
+		{"valid_mid", 0.5, false},
+		{"valid_one", 1.0, false},
+		{"above_one", 1.1, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+				L1:       L1BackendSpec{SizeGB: 10},
+				Eviction: &EvictionSpec{TriggerWatermark: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestValidateSpec_EvictionRatioBounds(t *testing.T) {
+	tests := []struct {
+		name    string
+		value   float64
+		wantErr bool
+	}{
+		{"zero", 0.0, true},
+		{"negative", -0.5, true},
+		{"valid_low", 0.1, false},
+		{"valid_one", 1.0, false},
+		{"above_one", 1.5, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+				L1:       L1BackendSpec{SizeGB: 10},
+				Eviction: &EvictionSpec{EvictionRatio: ptr(tt.value)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestValidateSpec_ServerPort(t *testing.T) {
+	tests := []struct {
+		name    string
+		port    int32
+		wantErr bool
+	}{
+		{"below_min", 80, true},
+		{"min_valid", 1024, false},
+		{"max_valid", 65535, false},
+		{"above_max", 65536, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+				L1:     L1BackendSpec{SizeGB: 10},
+				Server: &ServerSpec{Port: ptr(tt.port)},
+			}}
+			errs := e.ValidateSpec()
+			if tt.wantErr && len(errs) == 0 {
+				t.Fatal("expected error, got none")
+			}
+			if !tt.wantErr && len(errs) != 0 {
+				t.Fatalf("expected no error, got %v", errs)
+			}
+		})
+	}
+}
+
+func TestValidateSpec_MultipleErrors(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:     L1BackendSpec{SizeGB: 0},
+		Server: &ServerSpec{Port: ptr(int32(80))},
+		Eviction: &EvictionSpec{
+			Policy:           ptr("FIFO"),
+			TriggerWatermark: ptr(0.0),
+			EvictionRatio:    ptr(0.0),
+		},
+	}}
+	errs := e.ValidateSpec()
+	// sizeGB, port, policy, watermark, ratio = 5 errors
+	if len(errs) != 5 {
+		t.Fatalf("expected 5 errors, got %d: %v", len(errs), errs)
+	}
+}
+
+// --- L2 Backend validation tests ---
+
+func TestValidateSpec_L2RESPValid(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{
+				Host: "redis.default.svc",
+				Port: 6379,
+			},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestValidateSpec_L2RESPEmptyHost(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{
+				Host: "",
+				Port: 6379,
+			},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+	if errs[0].Field != "spec.l2Backend.resp.host" {
+		t.Fatalf("expected field spec.l2Backend.resp.host, got %s", errs[0].Field)
+	}
+}
+
+func TestValidateSpec_L2RESPInvalidPort(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{
+				Host: "redis",
+				Port: 0,
+			},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestValidateSpec_L2RESPAuthSecretEmpty(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{
+				Host:          "redis",
+				Port:          6379,
+				AuthSecretRef: &SecretReference{Name: ""},
+			},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestValidateSpec_L2RawValid(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			Raw: &RawL2AdapterSpec{Type: "mock"},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 0 {
+		t.Fatalf("expected no errors, got %v", errs)
+	}
+}
+
+func TestValidateSpec_L2RawEmptyType(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			Raw: &RawL2AdapterSpec{Type: ""},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestValidateSpec_L2NoneSet(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1:        L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
+
+func TestValidateSpec_L2BothSet(t *testing.T) {
+	e := &LMCacheEngine{Spec: LMCacheEngineSpec{
+		L1: L1BackendSpec{SizeGB: 10},
+		L2Backend: &L2BackendSpec{
+			RESP: &RESPL2AdapterSpec{Host: "redis", Port: 6379},
+			Raw:  &RawL2AdapterSpec{Type: "mock"},
+		},
+	}}
+	errs := e.ValidateSpec()
+	if len(errs) != 1 {
+		t.Fatalf("expected 1 error, got %d: %v", len(errs), errs)
+	}
+}
diff --git a/operator/api/v1alpha1/lmcacheengine_types.go b/operator/api/v1alpha1/lmcacheengine_types.go
new file mode 100644
index 0000000..b79b57c
--- /dev/null
+++ b/operator/api/v1alpha1/lmcacheengine_types.go
@@ -0,0 +1,538 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	corev1 "k8s.io/api/core/v1"
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// Phase constants for LMCacheEngine status.
+const (
+	PhasePending  = "Pending"
+	PhaseRunning  = "Running"
+	PhaseDegraded = "Degraded"
+	PhaseFailed   = "Failed"
+)
+
+const (
+	GPUVendorNvidia = "nvidia"
+	GPUVendorAMD    = "amd"
+)
+
+// Condition type constants.
+const (
+	ConditionAvailable         = "Available"
+	ConditionAllInstancesReady = "AllInstancesReady"
+	ConditionConfigValid       = "ConfigValid"
+)
+
+// ImageSpec defines the container image to use.
+type ImageSpec struct {
+	// repository is the container image repository.
+	// +optional
+	// +kubebuilder:default="lmcache/vllm-openai"
+	Repository *string `json:"repository,omitempty"`
+
+	// tag is the container image tag.
+	// +optional
+	// +kubebuilder:default="latest"
+	Tag *string `json:"tag,omitempty"`
+
+	// pullPolicy is the image pull policy.
+	// +optional
+	// +kubebuilder:default="IfNotPresent"
+	// +kubebuilder:validation:Enum=Always;Never;IfNotPresent
+	PullPolicy *string `json:"pullPolicy,omitempty"`
+}
+
+// LMCacheInjectionSpec configures optional lmcache code-payload staging for vLLM
+// pods bound to this engine. When payloadImage is unset the webhook wires only
+// the connection (--kv-transfer-config); when set it also copies the payload
+// tree into the vLLM container and prepends PYTHONPATH so vLLM imports that
+// lmcache instead of the one baked into its image, keeping the vLLM client and
+// the engine server on one build.
+type LMCacheInjectionSpec struct {
+	// payloadImage is a purpose-built init-container image (repository/tag/
+	// pullPolicy, like spec.image) that ships an unpacked lmcache tree under
+	// /payload and copies it to $SHARED_DIR on start (see
+	// docker/Dockerfile.payload); the vLLM container imports it via PYTHONPATH.
+	//
+	// repository has no usable default — the ImageSpec default
+	// (lmcache/vllm-openai) is NOT a payload — so it must be set explicitly. For
+	// private registries, imagePullSecrets must reference Secret(s) in the vLLM
+	// pod's namespace.
+	// +optional
+	PayloadImage *ImageSpec `json:"payloadImage,omitempty"`
+
+	// imagePullSecrets are appended to the vLLM pod's spec.imagePullSecrets so a
+	// PRIVATE payload init-container image can pull. The referenced Secret(s)
+	// must already exist in the vLLM pod's namespace; the operator does not copy
+	// them cross-namespace.
+	// +optional
+	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
+
+	// targetContainer is the name of the vLLM container to inject into. Empty
+	// (the default) selects the first container; a per-pod annotation may
+	// override it.
+	// +optional
+	TargetContainer *string `json:"targetContainer,omitempty"`
+}
+
+// ServerSpec defines server configuration mapping to server.py argparse.
+type ServerSpec struct {
+	// port is the server listening port.
+	// +optional
+	// +kubebuilder:default=5555
+	// +kubebuilder:validation:Minimum=1024
+	// +kubebuilder:validation:Maximum=65535
+	Port *int32 `json:"port,omitempty"`
+
+	// chunkSize is the token chunk size.
+	// +optional
+	// +kubebuilder:default=256
+	ChunkSize *int32 `json:"chunkSize,omitempty"`
+
+	// maxWorkers is the number of worker threads.
+	// +optional
+	// +kubebuilder:default=1
+	MaxWorkers *int32 `json:"maxWorkers,omitempty"`
+
+	// hashAlgorithm is the hash algorithm used for token hashing.
+	// +optional
+	// +kubebuilder:default="blake3"
+	// +kubebuilder:validation:Enum=builtin;sha256_cbor;blake3
+	HashAlgorithm *string `json:"hashAlgorithm,omitempty"`
+
+	// httpPort is the HTTP frontend port (health checks, cache admin).
+	// +optional
+	// +kubebuilder:default=8080
+	// +kubebuilder:validation:Minimum=1024
+	// +kubebuilder:validation:Maximum=65535
+	HTTPPort *int32 `json:"httpPort,omitempty"`
+}
+
+// L1BackendSpec defines the L1 memory cache configuration.
+type L1BackendSpec struct {
+	// sizeGB is the L1 cache size in gigabytes. Required, must be > 0.
+	// The CRD-level constraint (exclusiveMinimum=0) rejects invalid values
+	// at admission time so the controller never sees them; the in-Go
+	// ValidateSpec keeps the same rule for defense in depth.
+	// +kubebuilder:validation:Minimum=0
+	// +kubebuilder:validation:ExclusiveMinimum=true
+	SizeGB float64 `json:"sizeGB"`
+}
+
+// EvictionSpec defines the cache eviction configuration.
+type EvictionSpec struct {
+	// policy is the eviction policy. LRU or noop.
+	// +optional
+	// +kubebuilder:default="LRU"
+	// +kubebuilder:validation:Enum=LRU;noop
+	Policy *string `json:"policy,omitempty"`
+
+	// triggerWatermark is the cache usage ratio that triggers eviction.
+	// +optional
+	// +kubebuilder:default=0.8
+	TriggerWatermark *float64 `json:"triggerWatermark,omitempty"`
+
+	// evictionRatio is the fraction of cache to evict when triggered.
+	// +optional
+	// +kubebuilder:default=0.2
+	EvictionRatio *float64 `json:"evictionRatio,omitempty"`
+}
+
+// ServiceMonitorSpec defines Prometheus ServiceMonitor configuration.
+type ServiceMonitorSpec struct {
+	// enabled controls whether a ServiceMonitor CR is created.
+	// +optional
+	// +kubebuilder:default=false
+	Enabled *bool `json:"enabled,omitempty"`
+
+	// interval is the Prometheus scrape interval.
+	// +optional
+	// +kubebuilder:default="30s"
+	Interval *string `json:"interval,omitempty"`
+
+	// labels are additional labels added to the ServiceMonitor.
+	// +optional
+	Labels map[string]string `json:"labels,omitempty"`
+}
+
+// PrometheusSpec defines Prometheus monitoring configuration.
+type PrometheusSpec struct {
+	// enabled controls whether Prometheus metrics are exposed.
+	// +optional
+	// +kubebuilder:default=true
+	Enabled *bool `json:"enabled,omitempty"`
+
+	// port is the Prometheus metrics port.
+	// +optional
+	// +kubebuilder:default=9090
+	Port *int32 `json:"port,omitempty"`
+
+	// serviceMonitor configures the Prometheus ServiceMonitor.
+	// +optional
+	ServiceMonitor *ServiceMonitorSpec `json:"serviceMonitor,omitempty"`
+}
+
+// L2BackendSpec defines the L2 storage backend.
+// Exactly one of RESP or Raw must be set.
+type L2BackendSpec struct {
+	// resp configures a Redis/Valkey RESP L2 adapter backed by the
+	// native C++ connector.
+	// +optional
+	RESP *RESPL2AdapterSpec `json:"resp,omitempty"`
+
+	// raw is an escape hatch for adapter types not yet natively
+	// supported by the operator (e.g. nixl_store, fs, mock).
+	// The JSON is passed through to --l2-adapter as-is.
+	// +optional
+	Raw *RawL2AdapterSpec `json:"raw,omitempty"`
+
+	// storePolicy controls how keys flow from L1 to L2.
+	// "default" stores all keys to the adapter and keeps L1.
+	// "skip_l1" stores all keys to the adapter and deletes them from L1
+	// (buffer-only mode — pair with eviction.policy=noop).
+	// +optional
+	// +kubebuilder:default="default"
+	// +kubebuilder:validation:Enum=default;skip_l1
+	StorePolicy *string `json:"storePolicy,omitempty"`
+
+	// prefetchPolicy controls how keys flow from L2 back to L1 on
+	// cache misses. "default" picks the first adapter that has the key.
+	// +optional
+	// +kubebuilder:default="default"
+	// +kubebuilder:validation:Enum=default;retain
+	PrefetchPolicy *string `json:"prefetchPolicy,omitempty"`
+
+	// prefetchMaxInFlight limits the number of concurrent prefetch
+	// (L2→L1 load) requests, preventing excessive L1 memory pressure.
+	// +optional
+	// +kubebuilder:default=8
+	// +kubebuilder:validation:Minimum=1
+	PrefetchMaxInFlight *int32 `json:"prefetchMaxInFlight,omitempty"`
+}
+
+// RESPL2AdapterSpec configures a RESP (Redis/Valkey) L2 adapter.
+type RESPL2AdapterSpec struct {
+	// host is the Redis/Valkey server hostname or IP.
+	Host string `json:"host"`
+
+	// port is the Redis/Valkey server port.
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=65535
+	Port int32 `json:"port"`
+
+	// numWorkers is the number of C++ worker threads for I/O.
+	// +optional
+	// +kubebuilder:default=8
+	// +kubebuilder:validation:Minimum=1
+	NumWorkers *int32 `json:"numWorkers,omitempty"`
+
+	// maxCapacityGB is the max L2 capacity in GB for usage tracking
+	// and eviction. 0 means disabled.
+	// +optional
+	// +kubebuilder:default=0
+	MaxCapacityGB *float64 `json:"maxCapacityGB,omitempty"`
+
+	// authSecretRef is a reference to a Secret containing "username"
+	// and "password" keys for Redis authentication.
+	// The Secret may live in a different namespace; the operator will
+	// create a managed copy in the LMCacheEngine's namespace.
+	// The credentials are injected via environment variables so they
+	// do not appear in container args or kubectl describe output.
+	// +optional
+	AuthSecretRef *SecretReference `json:"authSecretRef,omitempty"`
+}
+
+// SecretReference is a reference to a Secret that supports cross-namespace access.
+type SecretReference struct {
+	// name is the name of the Secret.
+	Name string `json:"name"`
+
+	// namespace is the namespace of the Secret.
+	// If empty, defaults to the namespace of the LMCacheEngine resource.
+	// +optional
+	Namespace string `json:"namespace,omitempty"`
+}
+
+// RawL2AdapterSpec is a pass-through escape hatch for adapter types
+// not natively supported by the operator. The type and config fields
+// are merged into a flat JSON object and passed to --l2-adapter.
+type RawL2AdapterSpec struct {
+	// type is the adapter type name (e.g. "nixl_store", "fs", "mock").
+	Type string `json:"type"`
+
+	// config is type-specific configuration as a free-form map.
+	// +optional
+	Config map[string]apiextensionsv1.JSON `json:"config,omitempty"`
+}
+
+// CoordinatorConnectionSpec configures how an engine server registers with an
+// MP coordinator. It maps to the server's coordinator-client flags
+// (lmcache/v1/multiprocess/config.py: add_coordinator_args). Exactly one of
+// ref or url must be set.
+type CoordinatorConnectionSpec struct {
+	// ref names an LMCacheCoordinator in the same namespace. The operator
+	// resolves it to the coordinator's in-cluster Service URL.
+	// +optional
+	Ref *corev1.LocalObjectReference `json:"ref,omitempty"`
+
+	// url is an explicit coordinator base URL (e.g. http://coordinator:9300),
+	// used to target a coordinator the operator does not manage.
+	// +optional
+	URL *string `json:"url,omitempty"`
+
+	// advertiseIP is the IP the coordinator should reach this server at.
+	//
+	// DO NOT SET THIS IN ALMOST EVERY CASE. When unset, the server's pod IP is
+	// injected automatically via the downward API, which is the correct value
+	// for normal in-cluster deployments. Only set this if you know exactly what
+	// you are doing -- e.g. the coordinator runs outside the cluster and must
+	// reach the server through a specific externally-routable address. An
+	// incorrect value silently breaks coordinator-to-server connectivity.
+	// +optional
+	AdvertiseIP *string `json:"advertiseIP,omitempty"`
+
+	// heartbeatInterval is the seconds between heartbeats; must be > 0.
+	// +optional
+	// +kubebuilder:default=5
+	HeartbeatInterval *float64 `json:"heartbeatInterval,omitempty"`
+
+	// l2EventReporting enables reporting L2 store/lookup events to the
+	// coordinator for fleet-wide usage tracking and eviction.
+	// +optional
+	// +kubebuilder:default=false
+	L2EventReporting *bool `json:"l2EventReporting,omitempty"`
+
+	// l2EventFlushInterval is the seconds between L2 event flush attempts; must
+	// be > 0.
+	// +optional
+	// +kubebuilder:default=1
+	L2EventFlushInterval *float64 `json:"l2EventFlushInterval,omitempty"`
+}
+
+// LMCacheEngineSpec defines the desired state of LMCacheEngine.
+type LMCacheEngineSpec struct {
+	// gpuVendor selects the GPU vendor. "nvidia" (default) requires the NVIDIA
+	// GPU Operator's "nvidia" RuntimeClass; "amd" runs on the default container
+	// runtime.
+	// +optional
+	// +kubebuilder:default="nvidia"
+	// +kubebuilder:validation:Enum=nvidia;amd
+	GPUVendor *string `json:"gpuVendor,omitempty"`
+
+	// image defines the container image to use.
+	// +optional
+	Image *ImageSpec `json:"image,omitempty"`
+
+	// imagePullSecrets is a list of references to secrets for pulling the image.
+	// +optional
+	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
+
+	// server defines server configuration.
+	// +optional
+	Server *ServerSpec `json:"server,omitempty"`
+
+	// l1 defines the L1 memory cache configuration.
+	L1 L1BackendSpec `json:"l1"`
+
+	// eviction defines the cache eviction configuration.
+	// +optional
+	Eviction *EvictionSpec `json:"eviction,omitempty"`
+
+	// prometheus defines Prometheus monitoring configuration.
+	// +optional
+	Prometheus *PrometheusSpec `json:"prometheus,omitempty"`
+
+	// l2Backend defines the L2 storage backend.
+	// Currently only a single adapter is supported.
+	// +optional
+	L2Backend *L2BackendSpec `json:"l2Backend,omitempty"`
+
+	// coordinator configures registration with an MP coordinator. When unset,
+	// the server does not register with any coordinator.
+	// +optional
+	Coordinator *CoordinatorConnectionSpec `json:"coordinator,omitempty"`
+
+	// injection defines the defaults the LMCache mutating webhook reads for pods
+	// bound to this engine. When unset, the webhook wires only the connection;
+	// set injection.payloadImage to also stage an lmcache code payload.
+	// +optional
+	Injection *LMCacheInjectionSpec `json:"injection,omitempty"`
+
+	// resourceOverrides allows overriding auto-computed resource requirements.
+	// +optional
+	ResourceOverrides *corev1.ResourceRequirements `json:"resourceOverrides,omitempty"`
+
+	// logLevel is the log level for the LMCache server.
+	// +optional
+	// +kubebuilder:default="INFO"
+	// +kubebuilder:validation:Enum=DEBUG;INFO;WARNING;ERROR
+	LogLevel *string `json:"logLevel,omitempty"`
+
+	// nodeSelector determines which nodes get an LMCache instance.
+	// +optional
+	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
+
+	// affinity defines pod scheduling affinity rules.
+	// +optional
+	Affinity *corev1.Affinity `json:"affinity,omitempty"`
+
+	// tolerations defines pod tolerations.
+	// +optional
+	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
+
+	// env defines additional environment variables.
+	// +optional
+	Env []corev1.EnvVar `json:"env,omitempty"`
+
+	// volumes defines additional volumes.
+	// +optional
+	Volumes []corev1.Volume `json:"volumes,omitempty"`
+
+	// volumeMounts defines additional volume mounts.
+	// +optional
+	VolumeMounts []corev1.VolumeMount `json:"volumeMounts,omitempty"`
+
+	// podAnnotations are additional annotations added to pods.
+	// +optional
+	PodAnnotations map[string]string `json:"podAnnotations,omitempty"`
+
+	// podLabels are additional labels added to pods.
+	// +optional
+	PodLabels map[string]string `json:"podLabels,omitempty"`
+
+	// serviceAccountName is the name of the ServiceAccount to use.
+	// +optional
+	ServiceAccountName string `json:"serviceAccountName,omitempty"`
+
+	// priorityClassName is the priority class for the pods.
+	// +optional
+	PriorityClassName string `json:"priorityClassName,omitempty"`
+
+	// hostNetwork runs the pod in the host's network namespace. When true the
+	// operator also sets dnsPolicy to ClusterFirstWithHostNet so cluster DNS
+	// still works. Default: false.
+	// +optional
+	// +kubebuilder:default=false
+	HostNetwork *bool `json:"hostNetwork,omitempty"`
+
+	// privileged runs the engine container in privileged mode. On some clusters
+	// this is required for the engine to see all node GPUs (for CUDA IPC) without
+	// claiming any via the nvidia.com/gpu device plugin; on many clusters
+	// NVIDIA_VISIBLE_DEVICES=all already grants that visibility without it, so it
+	// defaults to false.
+	// +optional
+	// +kubebuilder:default=false
+	Privileged *bool `json:"privileged,omitempty"`
+
+	// extraArgs are additional CLI flags appended to the server command.
+	// They are appended last and can override any auto-generated flag.
+	// +optional
+	ExtraArgs []string `json:"extraArgs,omitempty"`
+}
+
+// EndpointStatus represents a single LMCache instance endpoint.
+type EndpointStatus struct {
+	// nodeName is the name of the node running this instance.
+	NodeName string `json:"nodeName"`
+
+	// hostIP is the IP address of the host.
+	HostIP string `json:"hostIP"`
+
+	// podName is the name of the pod.
+	PodName string `json:"podName"`
+
+	// port is the server port.
+	Port int32 `json:"port"`
+
+	// metricsPort is the Prometheus metrics port.
+	MetricsPort int32 `json:"metricsPort"`
+
+	// ready indicates whether this instance is ready.
+	Ready bool `json:"ready"`
+}
+
+// LMCacheEngineStatus defines the observed state of LMCacheEngine.
+type LMCacheEngineStatus struct {
+	// phase is the overall phase of the LMCacheEngine.
+	// +optional
+	Phase string `json:"phase,omitempty"`
+
+	// observedGeneration is the most recent generation observed.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
+	// desiredInstances is the number of desired instances.
+	// +optional
+	DesiredInstances int32 `json:"desiredInstances,omitempty"`
+
+	// readyInstances is the number of ready instances.
+	// +optional
+	ReadyInstances int32 `json:"readyInstances,omitempty"`
+
+	// endpoints lists per-node connection info.
+	// +optional
+	Endpoints []EndpointStatus `json:"endpoints,omitempty"`
+
+	// conditions represent the current state of the LMCacheEngine resource.
+	// +listType=map
+	// +listMapKey=type
+	// +optional
+	Conditions []metav1.Condition `json:"conditions,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+// +kubebuilder:subresource:status
+// +kubebuilder:resource:shortName=lmc
+// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
+// +kubebuilder:printcolumn:name="Ready",type=integer,JSONPath=`.status.readyInstances`
+// +kubebuilder:printcolumn:name="Desired",type=integer,JSONPath=`.status.desiredInstances`
+// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
+
+// LMCacheEngine is the Schema for the lmcacheengines API.
+type LMCacheEngine struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata is a standard object metadata.
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitzero"`
+
+	// spec defines the desired state of LMCacheEngine.
+	// +required
+	Spec LMCacheEngineSpec `json:"spec"`
+
+	// status defines the observed state of LMCacheEngine.
+	// +optional
+	Status LMCacheEngineStatus `json:"status,omitzero"`
+}
+
+// +kubebuilder:object:root=true
+
+// LMCacheEngineList contains a list of LMCacheEngine.
+type LMCacheEngineList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitzero"`
+	Items           []LMCacheEngine `json:"items"`
+}
+
+func init() {
+	SchemeBuilder.Register(&LMCacheEngine{}, &LMCacheEngineList{})
+}
diff --git a/operator/api/v1alpha1/lmcacheengine_validation.go b/operator/api/v1alpha1/lmcacheengine_validation.go
new file mode 100644
index 0000000..5d1240d
--- /dev/null
+++ b/operator/api/v1alpha1/lmcacheengine_validation.go
@@ -0,0 +1,158 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	"k8s.io/apimachinery/pkg/util/validation/field"
+)
+
+// ValidateSpec validates the LMCacheEngineSpec and returns any validation errors.
+func (e *LMCacheEngine) ValidateSpec() field.ErrorList {
+	var errs field.ErrorList
+	spec := &e.Spec
+
+	// l1.sizeGB must be > 0
+	if spec.L1.SizeGB <= 0 {
+		errs = append(errs, field.Invalid(field.NewPath("spec", "l1", "sizeGB"), spec.L1.SizeGB, "must be greater than 0"))
+	}
+
+	errs = append(errs, validateEvictionSpec(spec.Eviction)...)
+
+	// Server port validation
+	if spec.Server != nil && spec.Server.Port != nil {
+		port := *spec.Server.Port
+		if port < 1024 || port > 65535 {
+			errs = append(errs, field.Invalid(field.NewPath("spec", "server", "port"), port, "must be in [1024, 65535]"))
+		}
+	}
+
+	errs = append(errs, validateL2BackendSpec(spec.L2Backend)...)
+	errs = append(errs, validateCoordinatorConnectionSpec(spec.Coordinator)...)
+
+	return errs
+}
+
+// validateCoordinatorConnectionSpec validates the shared coordinator connection
+// configuration used by both LMCacheEngine and CacheBlendEngine. A nil spec is
+// valid (registration is disabled). Exactly one of ref or url must be set, and
+// the intervals must be positive. Errors are rooted at spec.coordinator.
+func validateCoordinatorConnectionSpec(conn *CoordinatorConnectionSpec) field.ErrorList {
+	var errs field.ErrorList
+	if conn == nil {
+		return errs
+	}
+	connPath := field.NewPath("spec", "coordinator")
+
+	refSet := conn.Ref != nil && conn.Ref.Name != ""
+	urlSet := conn.URL != nil && *conn.URL != ""
+	switch {
+	case refSet && urlSet:
+		errs = append(errs, field.Invalid(connPath, "", "exactly one of ref or url must be set, got both"))
+	case !refSet && !urlSet:
+		errs = append(errs, field.Required(connPath, "exactly one of ref or url must be set"))
+	}
+
+	if conn.HeartbeatInterval != nil && *conn.HeartbeatInterval <= 0 {
+		errs = append(errs, field.Invalid(connPath.Child("heartbeatInterval"), *conn.HeartbeatInterval, "must be greater than 0"))
+	}
+	if conn.L2EventFlushInterval != nil && *conn.L2EventFlushInterval <= 0 {
+		errs = append(errs, field.Invalid(connPath.Child("l2EventFlushInterval"), *conn.L2EventFlushInterval, "must be greater than 0"))
+	}
+
+	return errs
+}
+
+// validateEvictionSpec validates the shared eviction configuration used by both
+// LMCacheEngine and CacheBlendEngine. A nil eviction is valid (defaults apply).
+// Returned errors are rooted at spec.eviction.
+func validateEvictionSpec(eviction *EvictionSpec) field.ErrorList {
+	var errs field.ErrorList
+	if eviction == nil {
+		return errs
+	}
+	evPath := field.NewPath("spec", "eviction")
+
+	if eviction.Policy != nil && *eviction.Policy != "LRU" {
+		errs = append(errs, field.NotSupported(evPath.Child("policy"), *eviction.Policy, []string{"LRU"}))
+	}
+
+	if eviction.TriggerWatermark != nil {
+		tw := *eviction.TriggerWatermark
+		if tw <= 0.0 || tw > 1.0 {
+			errs = append(errs, field.Invalid(evPath.Child("triggerWatermark"), tw, "must be in (0.0, 1.0]"))
+		}
+	}
+
+	if eviction.EvictionRatio != nil {
+		er := *eviction.EvictionRatio
+		if er <= 0.0 || er > 1.0 {
+			errs = append(errs, field.Invalid(evPath.Child("evictionRatio"), er, "must be in (0.0, 1.0]"))
+		}
+	}
+
+	return errs
+}
+
+// validateL2BackendSpec validates the shared L2 backend configuration used by
+// both LMCacheEngine and CacheBlendEngine. A nil backend is valid (L2 is
+// optional). Returned errors are rooted at spec.l2Backend.
+func validateL2BackendSpec(b *L2BackendSpec) field.ErrorList {
+	var errs field.ErrorList
+	if b == nil {
+		return errs
+	}
+	l2Path := field.NewPath("spec", "l2Backend")
+
+	setCount := 0
+	if b.RESP != nil {
+		setCount++
+	}
+	if b.Raw != nil {
+		setCount++
+	}
+	// For now we only support one kind at each LMCache server. LMCache
+	// MP mode is designed to support multiple ones at the same time
+	// but tests and performance validation is needed before we ship
+	// it into operator.
+	if setCount == 0 {
+		errs = append(errs, field.Required(l2Path, "exactly one of resp or raw must be set"))
+	} else if setCount > 1 {
+		errs = append(errs, field.Invalid(l2Path, "", "exactly one of resp or raw must be set, got multiple"))
+	}
+
+	if b.RESP != nil {
+		respPath := l2Path.Child("resp")
+		if b.RESP.Host == "" {
+			errs = append(errs, field.Required(respPath.Child("host"), "must be a non-empty string"))
+		}
+		if b.RESP.Port < 1 || b.RESP.Port > 65535 {
+			errs = append(errs, field.Invalid(respPath.Child("port"), b.RESP.Port, "must be in [1, 65535]"))
+		}
+		if b.RESP.AuthSecretRef != nil && b.RESP.AuthSecretRef.Name == "" {
+			errs = append(errs, field.Required(respPath.Child("authSecretRef", "name"), "must be non-empty"))
+		}
+	}
+
+	if b.Raw != nil {
+		rawPath := l2Path.Child("raw")
+		if b.Raw.Type == "" {
+			errs = append(errs, field.Required(rawPath.Child("type"), "must be a non-empty string"))
+		}
+	}
+
+	return errs
+}
diff --git a/operator/api/v1alpha1/zz_generated.deepcopy.go b/operator/api/v1alpha1/zz_generated.deepcopy.go
new file mode 100644
index 0000000..5c21317
--- /dev/null
+++ b/operator/api/v1alpha1/zz_generated.deepcopy.go
@@ -0,0 +1,1144 @@
+//go:build !ignore_autogenerated
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Code generated by controller-gen. DO NOT EDIT.
+
+package v1alpha1
+
+import (
+	"k8s.io/api/core/v1"
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	runtime "k8s.io/apimachinery/pkg/runtime"
+)
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *BlendSpec) DeepCopyInto(out *BlendSpec) {
+	*out = *in
+	if in.CheckLayer != nil {
+		in, out := &in.CheckLayer, &out.CheckLayer
+		*out = new(int32)
+		**out = **in
+	}
+	if in.RecompRatio != nil {
+		in, out := &in.RecompRatio, &out.RecompRatio
+		*out = new(float64)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new BlendSpec.
+func (in *BlendSpec) DeepCopy() *BlendSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(BlendSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *CacheBlendEngine) DeepCopyInto(out *CacheBlendEngine) {
+	*out = *in
+	out.TypeMeta = in.TypeMeta
+	in.ObjectMeta.DeepCopyInto(&out.ObjectMeta)
+	in.Spec.DeepCopyInto(&out.Spec)
+	in.Status.DeepCopyInto(&out.Status)
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CacheBlendEngine.
+func (in *CacheBlendEngine) DeepCopy() *CacheBlendEngine {
+	if in == nil {
+		return nil
+	}
+	out := new(CacheBlendEngine)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
+func (in *CacheBlendEngine) DeepCopyObject() runtime.Object {
+	if c := in.DeepCopy(); c != nil {
+		return c
+	}
+	return nil
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *CacheBlendEngineList) DeepCopyInto(out *CacheBlendEngineList) {
+	*out = *in
+	out.TypeMeta = in.TypeMeta
+	in.ListMeta.DeepCopyInto(&out.ListMeta)
+	if in.Items != nil {
+		in, out := &in.Items, &out.Items
+		*out = make([]CacheBlendEngine, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CacheBlendEngineList.
+func (in *CacheBlendEngineList) DeepCopy() *CacheBlendEngineList {
+	if in == nil {
+		return nil
+	}
+	out := new(CacheBlendEngineList)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
+func (in *CacheBlendEngineList) DeepCopyObject() runtime.Object {
+	if c := in.DeepCopy(); c != nil {
+		return c
+	}
+	return nil
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *CacheBlendEngineSpec) DeepCopyInto(out *CacheBlendEngineSpec) {
+	*out = *in
+	if in.GPUVendor != nil {
+		in, out := &in.GPUVendor, &out.GPUVendor
+		*out = new(string)
+		**out = **in
+	}
+	if in.Image != nil {
+		in, out := &in.Image, &out.Image
+		*out = new(ImageSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ImagePullSecrets != nil {
+		in, out := &in.ImagePullSecrets, &out.ImagePullSecrets
+		*out = make([]v1.LocalObjectReference, len(*in))
+		copy(*out, *in)
+	}
+	if in.Server != nil {
+		in, out := &in.Server, &out.Server
+		*out = new(ServerSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	out.L1 = in.L1
+	if in.Eviction != nil {
+		in, out := &in.Eviction, &out.Eviction
+		*out = new(EvictionSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Prometheus != nil {
+		in, out := &in.Prometheus, &out.Prometheus
+		*out = new(PrometheusSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.L2Backend != nil {
+		in, out := &in.L2Backend, &out.L2Backend
+		*out = new(L2BackendSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Coordinator != nil {
+		in, out := &in.Coordinator, &out.Coordinator
+		*out = new(CoordinatorConnectionSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Blend != nil {
+		in, out := &in.Blend, &out.Blend
+		*out = new(BlendSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Injection != nil {
+		in, out := &in.Injection, &out.Injection
+		*out = new(InjectionSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ResourceOverrides != nil {
+		in, out := &in.ResourceOverrides, &out.ResourceOverrides
+		*out = new(v1.ResourceRequirements)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.LogLevel != nil {
+		in, out := &in.LogLevel, &out.LogLevel
+		*out = new(string)
+		**out = **in
+	}
+	if in.NodeSelector != nil {
+		in, out := &in.NodeSelector, &out.NodeSelector
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.Affinity != nil {
+		in, out := &in.Affinity, &out.Affinity
+		*out = new(v1.Affinity)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Tolerations != nil {
+		in, out := &in.Tolerations, &out.Tolerations
+		*out = make([]v1.Toleration, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.Env != nil {
+		in, out := &in.Env, &out.Env
+		*out = make([]v1.EnvVar, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.Volumes != nil {
+		in, out := &in.Volumes, &out.Volumes
+		*out = make([]v1.Volume, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.VolumeMounts != nil {
+		in, out := &in.VolumeMounts, &out.VolumeMounts
+		*out = make([]v1.VolumeMount, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.PodAnnotations != nil {
+		in, out := &in.PodAnnotations, &out.PodAnnotations
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.PodLabels != nil {
+		in, out := &in.PodLabels, &out.PodLabels
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.Privileged != nil {
+		in, out := &in.Privileged, &out.Privileged
+		*out = new(bool)
+		**out = **in
+	}
+	if in.ExtraArgs != nil {
+		in, out := &in.ExtraArgs, &out.ExtraArgs
+		*out = make([]string, len(*in))
+		copy(*out, *in)
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CacheBlendEngineSpec.
+func (in *CacheBlendEngineSpec) DeepCopy() *CacheBlendEngineSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(CacheBlendEngineSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *CacheBlendEngineStatus) DeepCopyInto(out *CacheBlendEngineStatus) {
+	*out = *in
+	if in.Endpoints != nil {
+		in, out := &in.Endpoints, &out.Endpoints
+		*out = make([]EndpointStatus, len(*in))
+		copy(*out, *in)
+	}
+	if in.Conditions != nil {
+		in, out := &in.Conditions, &out.Conditions
+		*out = make([]metav1.Condition, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CacheBlendEngineStatus.
+func (in *CacheBlendEngineStatus) DeepCopy() *CacheBlendEngineStatus {
+	if in == nil {
+		return nil
+	}
+	out := new(CacheBlendEngineStatus)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *CoordinatorConnectionSpec) DeepCopyInto(out *CoordinatorConnectionSpec) {
+	*out = *in
+	if in.Ref != nil {
+		in, out := &in.Ref, &out.Ref
+		*out = new(v1.LocalObjectReference)
+		**out = **in
+	}
+	if in.URL != nil {
+		in, out := &in.URL, &out.URL
+		*out = new(string)
+		**out = **in
+	}
+	if in.AdvertiseIP != nil {
+		in, out := &in.AdvertiseIP, &out.AdvertiseIP
+		*out = new(string)
+		**out = **in
+	}
+	if in.HeartbeatInterval != nil {
+		in, out := &in.HeartbeatInterval, &out.HeartbeatInterval
+		*out = new(float64)
+		**out = **in
+	}
+	if in.L2EventReporting != nil {
+		in, out := &in.L2EventReporting, &out.L2EventReporting
+		*out = new(bool)
+		**out = **in
+	}
+	if in.L2EventFlushInterval != nil {
+		in, out := &in.L2EventFlushInterval, &out.L2EventFlushInterval
+		*out = new(float64)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new CoordinatorConnectionSpec.
+func (in *CoordinatorConnectionSpec) DeepCopy() *CoordinatorConnectionSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(CoordinatorConnectionSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *EndpointStatus) DeepCopyInto(out *EndpointStatus) {
+	*out = *in
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EndpointStatus.
+func (in *EndpointStatus) DeepCopy() *EndpointStatus {
+	if in == nil {
+		return nil
+	}
+	out := new(EndpointStatus)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *EvictionSpec) DeepCopyInto(out *EvictionSpec) {
+	*out = *in
+	if in.Policy != nil {
+		in, out := &in.Policy, &out.Policy
+		*out = new(string)
+		**out = **in
+	}
+	if in.TriggerWatermark != nil {
+		in, out := &in.TriggerWatermark, &out.TriggerWatermark
+		*out = new(float64)
+		**out = **in
+	}
+	if in.EvictionRatio != nil {
+		in, out := &in.EvictionRatio, &out.EvictionRatio
+		*out = new(float64)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new EvictionSpec.
+func (in *EvictionSpec) DeepCopy() *EvictionSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(EvictionSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *ImageSpec) DeepCopyInto(out *ImageSpec) {
+	*out = *in
+	if in.Repository != nil {
+		in, out := &in.Repository, &out.Repository
+		*out = new(string)
+		**out = **in
+	}
+	if in.Tag != nil {
+		in, out := &in.Tag, &out.Tag
+		*out = new(string)
+		**out = **in
+	}
+	if in.PullPolicy != nil {
+		in, out := &in.PullPolicy, &out.PullPolicy
+		*out = new(string)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ImageSpec.
+func (in *ImageSpec) DeepCopy() *ImageSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(ImageSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *InjectionSpec) DeepCopyInto(out *InjectionSpec) {
+	*out = *in
+	if in.PayloadImage != nil {
+		in, out := &in.PayloadImage, &out.PayloadImage
+		*out = new(ImageSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ImagePullSecrets != nil {
+		in, out := &in.ImagePullSecrets, &out.ImagePullSecrets
+		*out = make([]v1.LocalObjectReference, len(*in))
+		copy(*out, *in)
+	}
+	if in.TargetContainer != nil {
+		in, out := &in.TargetContainer, &out.TargetContainer
+		*out = new(string)
+		**out = **in
+	}
+	if in.Cudagraph != nil {
+		in, out := &in.Cudagraph, &out.Cudagraph
+		*out = new(string)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new InjectionSpec.
+func (in *InjectionSpec) DeepCopy() *InjectionSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(InjectionSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *L1BackendSpec) DeepCopyInto(out *L1BackendSpec) {
+	*out = *in
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new L1BackendSpec.
+func (in *L1BackendSpec) DeepCopy() *L1BackendSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(L1BackendSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *L2BackendSpec) DeepCopyInto(out *L2BackendSpec) {
+	*out = *in
+	if in.RESP != nil {
+		in, out := &in.RESP, &out.RESP
+		*out = new(RESPL2AdapterSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Raw != nil {
+		in, out := &in.Raw, &out.Raw
+		*out = new(RawL2AdapterSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.StorePolicy != nil {
+		in, out := &in.StorePolicy, &out.StorePolicy
+		*out = new(string)
+		**out = **in
+	}
+	if in.PrefetchPolicy != nil {
+		in, out := &in.PrefetchPolicy, &out.PrefetchPolicy
+		*out = new(string)
+		**out = **in
+	}
+	if in.PrefetchMaxInFlight != nil {
+		in, out := &in.PrefetchMaxInFlight, &out.PrefetchMaxInFlight
+		*out = new(int32)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new L2BackendSpec.
+func (in *L2BackendSpec) DeepCopy() *L2BackendSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(L2BackendSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheCoordinator) DeepCopyInto(out *LMCacheCoordinator) {
+	*out = *in
+	out.TypeMeta = in.TypeMeta
+	in.ObjectMeta.DeepCopyInto(&out.ObjectMeta)
+	in.Spec.DeepCopyInto(&out.Spec)
+	in.Status.DeepCopyInto(&out.Status)
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheCoordinator.
+func (in *LMCacheCoordinator) DeepCopy() *LMCacheCoordinator {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheCoordinator)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
+func (in *LMCacheCoordinator) DeepCopyObject() runtime.Object {
+	if c := in.DeepCopy(); c != nil {
+		return c
+	}
+	return nil
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheCoordinatorList) DeepCopyInto(out *LMCacheCoordinatorList) {
+	*out = *in
+	out.TypeMeta = in.TypeMeta
+	in.ListMeta.DeepCopyInto(&out.ListMeta)
+	if in.Items != nil {
+		in, out := &in.Items, &out.Items
+		*out = make([]LMCacheCoordinator, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheCoordinatorList.
+func (in *LMCacheCoordinatorList) DeepCopy() *LMCacheCoordinatorList {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheCoordinatorList)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
+func (in *LMCacheCoordinatorList) DeepCopyObject() runtime.Object {
+	if c := in.DeepCopy(); c != nil {
+		return c
+	}
+	return nil
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheCoordinatorSpec) DeepCopyInto(out *LMCacheCoordinatorSpec) {
+	*out = *in
+	if in.Image != nil {
+		in, out := &in.Image, &out.Image
+		*out = new(ImageSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ImagePullSecrets != nil {
+		in, out := &in.ImagePullSecrets, &out.ImagePullSecrets
+		*out = make([]v1.LocalObjectReference, len(*in))
+		copy(*out, *in)
+	}
+	if in.Replicas != nil {
+		in, out := &in.Replicas, &out.Replicas
+		*out = new(int32)
+		**out = **in
+	}
+	if in.Host != nil {
+		in, out := &in.Host, &out.Host
+		*out = new(string)
+		**out = **in
+	}
+	if in.Port != nil {
+		in, out := &in.Port, &out.Port
+		*out = new(int32)
+		**out = **in
+	}
+	if in.InstanceTimeout != nil {
+		in, out := &in.InstanceTimeout, &out.InstanceTimeout
+		*out = new(float64)
+		**out = **in
+	}
+	if in.HealthCheckInterval != nil {
+		in, out := &in.HealthCheckInterval, &out.HealthCheckInterval
+		*out = new(float64)
+		**out = **in
+	}
+	if in.EvictionCheckInterval != nil {
+		in, out := &in.EvictionCheckInterval, &out.EvictionCheckInterval
+		*out = new(float64)
+		**out = **in
+	}
+	if in.EvictionRatio != nil {
+		in, out := &in.EvictionRatio, &out.EvictionRatio
+		*out = new(float64)
+		**out = **in
+	}
+	if in.TriggerWatermark != nil {
+		in, out := &in.TriggerWatermark, &out.TriggerWatermark
+		*out = new(float64)
+		**out = **in
+	}
+	if in.BlendChunkSize != nil {
+		in, out := &in.BlendChunkSize, &out.BlendChunkSize
+		*out = new(int32)
+		**out = **in
+	}
+	if in.BlendProbeStride != nil {
+		in, out := &in.BlendProbeStride, &out.BlendProbeStride
+		*out = new(int32)
+		**out = **in
+	}
+	if in.Prometheus != nil {
+		in, out := &in.Prometheus, &out.Prometheus
+		*out = new(PrometheusSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ResourceOverrides != nil {
+		in, out := &in.ResourceOverrides, &out.ResourceOverrides
+		*out = new(v1.ResourceRequirements)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.LogLevel != nil {
+		in, out := &in.LogLevel, &out.LogLevel
+		*out = new(string)
+		**out = **in
+	}
+	if in.NodeSelector != nil {
+		in, out := &in.NodeSelector, &out.NodeSelector
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.Affinity != nil {
+		in, out := &in.Affinity, &out.Affinity
+		*out = new(v1.Affinity)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Tolerations != nil {
+		in, out := &in.Tolerations, &out.Tolerations
+		*out = make([]v1.Toleration, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.Env != nil {
+		in, out := &in.Env, &out.Env
+		*out = make([]v1.EnvVar, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.Volumes != nil {
+		in, out := &in.Volumes, &out.Volumes
+		*out = make([]v1.Volume, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.VolumeMounts != nil {
+		in, out := &in.VolumeMounts, &out.VolumeMounts
+		*out = make([]v1.VolumeMount, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.PodAnnotations != nil {
+		in, out := &in.PodAnnotations, &out.PodAnnotations
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.PodLabels != nil {
+		in, out := &in.PodLabels, &out.PodLabels
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.ExtraArgs != nil {
+		in, out := &in.ExtraArgs, &out.ExtraArgs
+		*out = make([]string, len(*in))
+		copy(*out, *in)
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheCoordinatorSpec.
+func (in *LMCacheCoordinatorSpec) DeepCopy() *LMCacheCoordinatorSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheCoordinatorSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheCoordinatorStatus) DeepCopyInto(out *LMCacheCoordinatorStatus) {
+	*out = *in
+	if in.Conditions != nil {
+		in, out := &in.Conditions, &out.Conditions
+		*out = make([]metav1.Condition, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheCoordinatorStatus.
+func (in *LMCacheCoordinatorStatus) DeepCopy() *LMCacheCoordinatorStatus {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheCoordinatorStatus)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheEngine) DeepCopyInto(out *LMCacheEngine) {
+	*out = *in
+	out.TypeMeta = in.TypeMeta
+	in.ObjectMeta.DeepCopyInto(&out.ObjectMeta)
+	in.Spec.DeepCopyInto(&out.Spec)
+	in.Status.DeepCopyInto(&out.Status)
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheEngine.
+func (in *LMCacheEngine) DeepCopy() *LMCacheEngine {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheEngine)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
+func (in *LMCacheEngine) DeepCopyObject() runtime.Object {
+	if c := in.DeepCopy(); c != nil {
+		return c
+	}
+	return nil
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheEngineList) DeepCopyInto(out *LMCacheEngineList) {
+	*out = *in
+	out.TypeMeta = in.TypeMeta
+	in.ListMeta.DeepCopyInto(&out.ListMeta)
+	if in.Items != nil {
+		in, out := &in.Items, &out.Items
+		*out = make([]LMCacheEngine, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheEngineList.
+func (in *LMCacheEngineList) DeepCopy() *LMCacheEngineList {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheEngineList)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
+func (in *LMCacheEngineList) DeepCopyObject() runtime.Object {
+	if c := in.DeepCopy(); c != nil {
+		return c
+	}
+	return nil
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheEngineSpec) DeepCopyInto(out *LMCacheEngineSpec) {
+	*out = *in
+	if in.GPUVendor != nil {
+		in, out := &in.GPUVendor, &out.GPUVendor
+		*out = new(string)
+		**out = **in
+	}
+	if in.Image != nil {
+		in, out := &in.Image, &out.Image
+		*out = new(ImageSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ImagePullSecrets != nil {
+		in, out := &in.ImagePullSecrets, &out.ImagePullSecrets
+		*out = make([]v1.LocalObjectReference, len(*in))
+		copy(*out, *in)
+	}
+	if in.Server != nil {
+		in, out := &in.Server, &out.Server
+		*out = new(ServerSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	out.L1 = in.L1
+	if in.Eviction != nil {
+		in, out := &in.Eviction, &out.Eviction
+		*out = new(EvictionSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Prometheus != nil {
+		in, out := &in.Prometheus, &out.Prometheus
+		*out = new(PrometheusSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.L2Backend != nil {
+		in, out := &in.L2Backend, &out.L2Backend
+		*out = new(L2BackendSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Coordinator != nil {
+		in, out := &in.Coordinator, &out.Coordinator
+		*out = new(CoordinatorConnectionSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Injection != nil {
+		in, out := &in.Injection, &out.Injection
+		*out = new(LMCacheInjectionSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ResourceOverrides != nil {
+		in, out := &in.ResourceOverrides, &out.ResourceOverrides
+		*out = new(v1.ResourceRequirements)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.LogLevel != nil {
+		in, out := &in.LogLevel, &out.LogLevel
+		*out = new(string)
+		**out = **in
+	}
+	if in.NodeSelector != nil {
+		in, out := &in.NodeSelector, &out.NodeSelector
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.Affinity != nil {
+		in, out := &in.Affinity, &out.Affinity
+		*out = new(v1.Affinity)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.Tolerations != nil {
+		in, out := &in.Tolerations, &out.Tolerations
+		*out = make([]v1.Toleration, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.Env != nil {
+		in, out := &in.Env, &out.Env
+		*out = make([]v1.EnvVar, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.Volumes != nil {
+		in, out := &in.Volumes, &out.Volumes
+		*out = make([]v1.Volume, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.VolumeMounts != nil {
+		in, out := &in.VolumeMounts, &out.VolumeMounts
+		*out = make([]v1.VolumeMount, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+	if in.PodAnnotations != nil {
+		in, out := &in.PodAnnotations, &out.PodAnnotations
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.PodLabels != nil {
+		in, out := &in.PodLabels, &out.PodLabels
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+	if in.HostNetwork != nil {
+		in, out := &in.HostNetwork, &out.HostNetwork
+		*out = new(bool)
+		**out = **in
+	}
+	if in.Privileged != nil {
+		in, out := &in.Privileged, &out.Privileged
+		*out = new(bool)
+		**out = **in
+	}
+	if in.ExtraArgs != nil {
+		in, out := &in.ExtraArgs, &out.ExtraArgs
+		*out = make([]string, len(*in))
+		copy(*out, *in)
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheEngineSpec.
+func (in *LMCacheEngineSpec) DeepCopy() *LMCacheEngineSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheEngineSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheEngineStatus) DeepCopyInto(out *LMCacheEngineStatus) {
+	*out = *in
+	if in.Endpoints != nil {
+		in, out := &in.Endpoints, &out.Endpoints
+		*out = make([]EndpointStatus, len(*in))
+		copy(*out, *in)
+	}
+	if in.Conditions != nil {
+		in, out := &in.Conditions, &out.Conditions
+		*out = make([]metav1.Condition, len(*in))
+		for i := range *in {
+			(*in)[i].DeepCopyInto(&(*out)[i])
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheEngineStatus.
+func (in *LMCacheEngineStatus) DeepCopy() *LMCacheEngineStatus {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheEngineStatus)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *LMCacheInjectionSpec) DeepCopyInto(out *LMCacheInjectionSpec) {
+	*out = *in
+	if in.PayloadImage != nil {
+		in, out := &in.PayloadImage, &out.PayloadImage
+		*out = new(ImageSpec)
+		(*in).DeepCopyInto(*out)
+	}
+	if in.ImagePullSecrets != nil {
+		in, out := &in.ImagePullSecrets, &out.ImagePullSecrets
+		*out = make([]v1.LocalObjectReference, len(*in))
+		copy(*out, *in)
+	}
+	if in.TargetContainer != nil {
+		in, out := &in.TargetContainer, &out.TargetContainer
+		*out = new(string)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new LMCacheInjectionSpec.
+func (in *LMCacheInjectionSpec) DeepCopy() *LMCacheInjectionSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(LMCacheInjectionSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *PrometheusSpec) DeepCopyInto(out *PrometheusSpec) {
+	*out = *in
+	if in.Enabled != nil {
+		in, out := &in.Enabled, &out.Enabled
+		*out = new(bool)
+		**out = **in
+	}
+	if in.Port != nil {
+		in, out := &in.Port, &out.Port
+		*out = new(int32)
+		**out = **in
+	}
+	if in.ServiceMonitor != nil {
+		in, out := &in.ServiceMonitor, &out.ServiceMonitor
+		*out = new(ServiceMonitorSpec)
+		(*in).DeepCopyInto(*out)
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new PrometheusSpec.
+func (in *PrometheusSpec) DeepCopy() *PrometheusSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(PrometheusSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *RESPL2AdapterSpec) DeepCopyInto(out *RESPL2AdapterSpec) {
+	*out = *in
+	if in.NumWorkers != nil {
+		in, out := &in.NumWorkers, &out.NumWorkers
+		*out = new(int32)
+		**out = **in
+	}
+	if in.MaxCapacityGB != nil {
+		in, out := &in.MaxCapacityGB, &out.MaxCapacityGB
+		*out = new(float64)
+		**out = **in
+	}
+	if in.AuthSecretRef != nil {
+		in, out := &in.AuthSecretRef, &out.AuthSecretRef
+		*out = new(SecretReference)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RESPL2AdapterSpec.
+func (in *RESPL2AdapterSpec) DeepCopy() *RESPL2AdapterSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(RESPL2AdapterSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *RawL2AdapterSpec) DeepCopyInto(out *RawL2AdapterSpec) {
+	*out = *in
+	if in.Config != nil {
+		in, out := &in.Config, &out.Config
+		*out = make(map[string]apiextensionsv1.JSON, len(*in))
+		for key, val := range *in {
+			(*out)[key] = *val.DeepCopy()
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RawL2AdapterSpec.
+func (in *RawL2AdapterSpec) DeepCopy() *RawL2AdapterSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(RawL2AdapterSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *SecretReference) DeepCopyInto(out *SecretReference) {
+	*out = *in
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SecretReference.
+func (in *SecretReference) DeepCopy() *SecretReference {
+	if in == nil {
+		return nil
+	}
+	out := new(SecretReference)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *ServerSpec) DeepCopyInto(out *ServerSpec) {
+	*out = *in
+	if in.Port != nil {
+		in, out := &in.Port, &out.Port
+		*out = new(int32)
+		**out = **in
+	}
+	if in.ChunkSize != nil {
+		in, out := &in.ChunkSize, &out.ChunkSize
+		*out = new(int32)
+		**out = **in
+	}
+	if in.MaxWorkers != nil {
+		in, out := &in.MaxWorkers, &out.MaxWorkers
+		*out = new(int32)
+		**out = **in
+	}
+	if in.HashAlgorithm != nil {
+		in, out := &in.HashAlgorithm, &out.HashAlgorithm
+		*out = new(string)
+		**out = **in
+	}
+	if in.HTTPPort != nil {
+		in, out := &in.HTTPPort, &out.HTTPPort
+		*out = new(int32)
+		**out = **in
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServerSpec.
+func (in *ServerSpec) DeepCopy() *ServerSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(ServerSpec)
+	in.DeepCopyInto(out)
+	return out
+}
+
+// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.
+func (in *ServiceMonitorSpec) DeepCopyInto(out *ServiceMonitorSpec) {
+	*out = *in
+	if in.Enabled != nil {
+		in, out := &in.Enabled, &out.Enabled
+		*out = new(bool)
+		**out = **in
+	}
+	if in.Interval != nil {
+		in, out := &in.Interval, &out.Interval
+		*out = new(string)
+		**out = **in
+	}
+	if in.Labels != nil {
+		in, out := &in.Labels, &out.Labels
+		*out = make(map[string]string, len(*in))
+		for key, val := range *in {
+			(*out)[key] = val
+		}
+	}
+}
+
+// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ServiceMonitorSpec.
+func (in *ServiceMonitorSpec) DeepCopy() *ServiceMonitorSpec {
+	if in == nil {
+		return nil
+	}
+	out := new(ServiceMonitorSpec)
+	in.DeepCopyInto(out)
+	return out
+}
diff --git a/operator/cmd/main.go b/operator/cmd/main.go
new file mode 100644
index 0000000..9428841
--- /dev/null
+++ b/operator/cmd/main.go
@@ -0,0 +1,237 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"crypto/tls"
+	"flag"
+	"os"
+
+	// Import all Kubernetes client auth plugins (e.g. Azure, GCP, OIDC, etc.)
+	// to ensure that exec-entrypoint and run can make use of them.
+	_ "k8s.io/client-go/plugin/pkg/client/auth"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
+	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/healthz"
+	"sigs.k8s.io/controller-runtime/pkg/log/zap"
+	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
+	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
+	"sigs.k8s.io/controller-runtime/pkg/webhook"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/controller"
+	cbwebhook "github.com/LMCache/LMCache/internal/webhook"
+	// +kubebuilder:scaffold:imports
+)
+
+var (
+	scheme   = runtime.NewScheme()
+	setupLog = ctrl.Log.WithName("setup")
+)
+
+func init() {
+	utilruntime.Must(clientgoscheme.AddToScheme(scheme))
+
+	utilruntime.Must(lmcachev1alpha1.AddToScheme(scheme))
+	utilruntime.Must(monitoringv1.AddToScheme(scheme))
+	// +kubebuilder:scaffold:scheme
+}
+
+// nolint:gocyclo
+func main() {
+	var metricsAddr string
+	var metricsCertPath, metricsCertName, metricsCertKey string
+	var webhookCertPath, webhookCertName, webhookCertKey string
+	var enableLeaderElection bool
+	var probeAddr string
+	var secureMetrics bool
+	var enableHTTP2 bool
+	var tlsOpts []func(*tls.Config)
+	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. "+
+		"Use :8443 for HTTPS or :8080 for HTTP, or leave as 0 to disable the metrics service.")
+	flag.StringVar(&probeAddr, "health-probe-bind-address", ":8081", "The address the probe endpoint binds to.")
+	flag.BoolVar(&enableLeaderElection, "leader-elect", false,
+		"Enable leader election for controller manager. "+
+			"Enabling this will ensure there is only one active controller manager.")
+	flag.BoolVar(&secureMetrics, "metrics-secure", true,
+		"If set, the metrics endpoint is served securely via HTTPS. Use --metrics-secure=false to use HTTP instead.")
+	flag.StringVar(&webhookCertPath, "webhook-cert-path", "", "The directory that contains the webhook certificate.")
+	flag.StringVar(&webhookCertName, "webhook-cert-name", "tls.crt", "The name of the webhook certificate file.")
+	flag.StringVar(&webhookCertKey, "webhook-cert-key", "tls.key", "The name of the webhook key file.")
+	flag.StringVar(&metricsCertPath, "metrics-cert-path", "",
+		"The directory that contains the metrics server certificate.")
+	flag.StringVar(&metricsCertName, "metrics-cert-name", "tls.crt", "The name of the metrics server certificate file.")
+	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
+	flag.BoolVar(&enableHTTP2, "enable-http2", false,
+		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
+	opts := zap.Options{
+		Development: true,
+	}
+	opts.BindFlags(flag.CommandLine)
+	flag.Parse()
+
+	ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))
+
+	// if the enable-http2 flag is false (the default), http/2 should be disabled
+	// due to its vulnerabilities. More specifically, disabling http/2 will
+	// prevent from being vulnerable to the HTTP/2 Stream Cancellation and
+	// Rapid Reset CVEs. For more information see:
+	// - https://github.com/advisories/GHSA-qppj-fm5r-hxr3
+	// - https://github.com/advisories/GHSA-4374-p667-p6c8
+	disableHTTP2 := func(c *tls.Config) {
+		setupLog.Info("Disabling HTTP/2")
+		c.NextProtos = []string{"http/1.1"}
+	}
+
+	if !enableHTTP2 {
+		tlsOpts = append(tlsOpts, disableHTTP2)
+	}
+
+	// Initial webhook TLS options
+	webhookTLSOpts := tlsOpts
+	webhookServerOptions := webhook.Options{
+		TLSOpts: webhookTLSOpts,
+	}
+
+	if len(webhookCertPath) > 0 {
+		setupLog.Info("Initializing webhook certificate watcher using provided certificates",
+			"webhook-cert-path", webhookCertPath, "webhook-cert-name", webhookCertName, "webhook-cert-key", webhookCertKey)
+
+		webhookServerOptions.CertDir = webhookCertPath
+		webhookServerOptions.CertName = webhookCertName
+		webhookServerOptions.KeyName = webhookCertKey
+	}
+
+	webhookServer := webhook.NewServer(webhookServerOptions)
+
+	// Metrics endpoint is enabled in 'config/default/kustomization.yaml'. The Metrics options configure the server.
+	// More info:
+	// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.23.1/pkg/metrics/server
+	// - https://book.kubebuilder.io/reference/metrics.html
+	metricsServerOptions := metricsserver.Options{
+		BindAddress:   metricsAddr,
+		SecureServing: secureMetrics,
+		TLSOpts:       tlsOpts,
+	}
+
+	if secureMetrics {
+		// FilterProvider is used to protect the metrics endpoint with authn/authz.
+		// These configurations ensure that only authorized users and service accounts
+		// can access the metrics endpoint. The RBAC are configured in 'config/rbac/kustomization.yaml'. More info:
+		// https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.23.1/pkg/metrics/filters#WithAuthenticationAndAuthorization
+		metricsServerOptions.FilterProvider = filters.WithAuthenticationAndAuthorization
+	}
+
+	// If the certificate is not specified, controller-runtime will automatically
+	// generate self-signed certificates for the metrics server. While convenient for development and testing,
+	// this setup is not recommended for production.
+	//
+	// TODO(user): If you enable certManager, uncomment the following lines:
+	// - [METRICS-WITH-CERTS] at config/default/kustomization.yaml to generate and use certificates
+	// managed by cert-manager for the metrics server.
+	// - [PROMETHEUS-WITH-CERTS] at config/prometheus/kustomization.yaml for TLS certification.
+	if len(metricsCertPath) > 0 {
+		setupLog.Info("Initializing metrics certificate watcher using provided certificates",
+			"metrics-cert-path", metricsCertPath, "metrics-cert-name", metricsCertName, "metrics-cert-key", metricsCertKey)
+
+		metricsServerOptions.CertDir = metricsCertPath
+		metricsServerOptions.CertName = metricsCertName
+		metricsServerOptions.KeyName = metricsCertKey
+	}
+
+	mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
+		Scheme:                 scheme,
+		Metrics:                metricsServerOptions,
+		WebhookServer:          webhookServer,
+		HealthProbeBindAddress: probeAddr,
+		LeaderElection:         enableLeaderElection,
+		LeaderElectionID:       "f517be84.lmcache.ai",
+		// LeaderElectionReleaseOnCancel defines if the leader should step down voluntarily
+		// when the Manager ends. This requires the binary to immediately end when the
+		// Manager is stopped, otherwise, this setting is unsafe. Setting this significantly
+		// speeds up voluntary leader transitions as the new leader don't have to wait
+		// LeaseDuration time first.
+		//
+		// In the default scaffold provided, the program ends immediately after
+		// the manager stops, so would be fine to enable this option. However,
+		// if you are doing or is intended to do any operation such as perform cleanups
+		// after the manager stops then its usage might be unsafe.
+		// LeaderElectionReleaseOnCancel: true,
+	})
+	if err != nil {
+		setupLog.Error(err, "Failed to start manager")
+		os.Exit(1)
+	}
+
+	if err := (&controller.LMCacheEngineReconciler{
+		Client: mgr.GetClient(),
+		Scheme: mgr.GetScheme(),
+	}).SetupWithManager(mgr); err != nil {
+		setupLog.Error(err, "Failed to create controller", "controller", "LMCacheEngine")
+		os.Exit(1)
+	}
+	if err := (&controller.CacheBlendEngineReconciler{
+		Client: mgr.GetClient(),
+		Scheme: mgr.GetScheme(),
+	}).SetupWithManager(mgr); err != nil {
+		setupLog.Error(err, "Failed to create controller", "controller", "CacheBlendEngine")
+		os.Exit(1)
+	}
+	if err := (&controller.LMCacheCoordinatorReconciler{
+		Client: mgr.GetClient(),
+		Scheme: mgr.GetScheme(),
+	}).SetupWithManager(mgr); err != nil {
+		setupLog.Error(err, "Failed to create controller", "controller", "LMCacheCoordinator")
+		os.Exit(1)
+	}
+	// ENABLE_WEBHOOKS=false skips registering the pod-mutating webhook, so a
+	// local `make run` (which has no serving certs on the host) can start the
+	// controller without the webhook server failing on a missing tls.crt. The
+	// deployed manager leaves it unset, so the webhook is on by default.
+	if os.Getenv("ENABLE_WEBHOOKS") != "false" {
+		mgr.GetWebhookServer().Register("/mutate--v1-pod", &webhook.Admission{Handler: &cbwebhook.CacheBlendPodInjector{
+			Client:  mgr.GetClient(),
+			Decoder: admission.NewDecoder(mgr.GetScheme()),
+		}})
+		mgr.GetWebhookServer().Register("/mutate-lmcache--v1-pod", &webhook.Admission{Handler: &cbwebhook.LMCachePodInjector{
+			Client:  mgr.GetClient(),
+			Decoder: admission.NewDecoder(mgr.GetScheme()),
+		}})
+	}
+	// +kubebuilder:scaffold:builder
+
+	if err := mgr.AddHealthzCheck("healthz", healthz.Ping); err != nil {
+		setupLog.Error(err, "Failed to set up health check")
+		os.Exit(1)
+	}
+	if err := mgr.AddReadyzCheck("readyz", healthz.Ping); err != nil {
+		setupLog.Error(err, "Failed to set up ready check")
+		os.Exit(1)
+	}
+
+	setupLog.Info("Starting manager")
+	if err := mgr.Start(ctrl.SetupSignalHandler()); err != nil {
+		setupLog.Error(err, "Failed to run manager")
+		os.Exit(1)
+	}
+}
diff --git a/operator/config/certmanager/certificate.yaml b/operator/config/certmanager/certificate.yaml
new file mode 100644
index 0000000..41c2259
--- /dev/null
+++ b/operator/config/certmanager/certificate.yaml
@@ -0,0 +1,26 @@
+# The serving certificate for the mutating admission webhook. cert-manager writes the
+# resulting key pair into the secret named by secretName, which the controller-manager
+# Deployment mounts at /tmp/k8s-webhook-server/serving-certs (see manager_webhook_patch.yaml).
+# The MutatingWebhookConfiguration's cert-manager.io/inject-ca-from annotation points at
+# this Certificate so the caBundle is injected and rotated automatically (design §10).
+#
+# The dnsNames carry a placeholder Service name/namespace; the config/default overlay
+# rewrites the SERVICE_NAME / SERVICE_NAMESPACE segments via kustomize replacements so the
+# rendered SAN matches the actual (namePrefix-ed, namespaced) Service.
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: serving-cert
+  namespace: system
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+spec:
+  dnsNames:
+  # SERVICE_NAME and SERVICE_NAMESPACE will be substituted by kustomize replacements.
+  - SERVICE_NAME.SERVICE_NAMESPACE.svc
+  - SERVICE_NAME.SERVICE_NAMESPACE.svc.cluster.local
+  issuerRef:
+    kind: Issuer
+    name: selfsigned-issuer
+  secretName: webhook-server-cert
diff --git a/operator/config/certmanager/issuer.yaml b/operator/config/certmanager/issuer.yaml
new file mode 100644
index 0000000..e1fd502
--- /dev/null
+++ b/operator/config/certmanager/issuer.yaml
@@ -0,0 +1,12 @@
+# A self-signed Issuer used to mint the webhook serving certificate. cert-manager must
+# be installed in the cluster (it is a hard prerequisite for the webhook, per design §10).
+apiVersion: cert-manager.io/v1
+kind: Issuer
+metadata:
+  name: selfsigned-issuer
+  namespace: system
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+spec:
+  selfSigned: {}
diff --git a/operator/config/certmanager/kustomization.yaml b/operator/config/certmanager/kustomization.yaml
new file mode 100644
index 0000000..3d0c656
--- /dev/null
+++ b/operator/config/certmanager/kustomization.yaml
@@ -0,0 +1,6 @@
+resources:
+- issuer.yaml
+- certificate.yaml
+
+configurations:
+- kustomizeconfig.yaml
diff --git a/operator/config/certmanager/kustomizeconfig.yaml b/operator/config/certmanager/kustomizeconfig.yaml
new file mode 100644
index 0000000..ddc1f90
--- /dev/null
+++ b/operator/config/certmanager/kustomizeconfig.yaml
@@ -0,0 +1,8 @@
+# This configuration is for teaching kustomize how to update name ref substitution.
+nameReference:
+- kind: Issuer
+  group: cert-manager.io
+  fieldSpecs:
+  - kind: Certificate
+    group: cert-manager.io
+    path: spec/issuerRef/name
diff --git a/operator/config/crd/bases/lmcache.lmcache.ai_cacheblendengines.yaml b/operator/config/crd/bases/lmcache.lmcache.ai_cacheblendengines.yaml
new file mode 100644
index 0000000..5b4ddd9
--- /dev/null
+++ b/operator/config/crd/bases/lmcache.lmcache.ai_cacheblendengines.yaml
@@ -0,0 +1,3782 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.20.1
+  name: cacheblendengines.lmcache.lmcache.ai
+spec:
+  group: lmcache.lmcache.ai
+  names:
+    kind: CacheBlendEngine
+    listKind: CacheBlendEngineList
+    plural: cacheblendengines
+    shortNames:
+    - cbe
+    singular: cacheblendengine
+  scope: Namespaced
+  versions:
+  - additionalPrinterColumns:
+    - jsonPath: .status.phase
+      name: Phase
+      type: string
+    - jsonPath: .status.readyInstances
+      name: Ready
+      type: integer
+    - jsonPath: .status.desiredInstances
+      name: Desired
+      type: integer
+    - jsonPath: .metadata.creationTimestamp
+      name: Age
+      type: date
+    name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: CacheBlendEngine is the Schema for the cacheblendengines API.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: spec defines the desired state of CacheBlendEngine.
+            properties:
+              affinity:
+                description: affinity defines pod scheduling affinity rules.
+                properties:
+                  nodeAffinity:
+                    description: Describes node affinity scheduling rules for the
+                      pod.
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and adding
+                          "weight" to the sum if the node matches the corresponding matchExpressions; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: |-
+                            An empty preferred scheduling term matches all objects with implicit weight 0
+                            (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op).
+                          properties:
+                            preference:
+                              description: A node selector term, associated with the
+                                corresponding weight.
+                              properties:
+                                matchExpressions:
+                                  description: A list of node selector requirements
+                                    by node's labels.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchFields:
+                                  description: A list of node selector requirements
+                                    by node's fields.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            weight:
+                              description: Weight associated with matching the corresponding
+                                nodeSelectorTerm, in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - preference
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to an update), the system
+                          may or may not try to eventually evict the pod from its node.
+                        properties:
+                          nodeSelectorTerms:
+                            description: Required. A list of node selector terms.
+                              The terms are ORed.
+                            items:
+                              description: |-
+                                A null or empty node selector term matches no objects. The requirements of
+                                them are ANDed.
+                                The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.
+                              properties:
+                                matchExpressions:
+                                  description: A list of node selector requirements
+                                    by node's labels.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchFields:
+                                  description: A list of node selector requirements
+                                    by node's fields.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            type: array
+                            x-kubernetes-list-type: atomic
+                        required:
+                        - nodeSelectorTerms
+                        type: object
+                        x-kubernetes-map-type: atomic
+                    type: object
+                  podAffinity:
+                    description: Describes pod affinity scheduling rules (e.g. co-locate
+                      this pod in the same node, zone, etc. as some other pod(s)).
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and adding
+                          "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: The weights of all of the matched WeightedPodAffinityTerm
+                            fields are added per-node to find the most preferred node(s)
+                          properties:
+                            podAffinityTerm:
+                              description: Required. A pod affinity term, associated
+                                with the corresponding weight.
+                              properties:
+                                labelSelector:
+                                  description: |-
+                                    A label query over a set of resources, in this case pods.
+                                    If it's null, this PodAffinityTerm matches with no Pods.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                matchLabelKeys:
+                                  description: |-
+                                    MatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                    Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                mismatchLabelKeys:
+                                  description: |-
+                                    MismatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                    Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                namespaceSelector:
+                                  description: |-
+                                    A label query over the set of namespaces that the term applies to.
+                                    The term is applied to the union of the namespaces selected by this field
+                                    and the ones listed in the namespaces field.
+                                    null selector and null or empty namespaces list means "this pod's namespace".
+                                    An empty selector ({}) matches all namespaces.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                namespaces:
+                                  description: |-
+                                    namespaces specifies a static list of namespace names that the term applies to.
+                                    The term is applied to the union of the namespaces listed in this field
+                                    and the ones selected by namespaceSelector.
+                                    null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                topologyKey:
+                                  description: |-
+                                    This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                    the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                    whose value of the label with key topologyKey matches that of any node on which any of the
+                                    selected pods is running.
+                                    Empty topologyKey is not allowed.
+                                  type: string
+                              required:
+                              - topologyKey
+                              type: object
+                            weight:
+                              description: |-
+                                weight associated with matching the corresponding podAffinityTerm,
+                                in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - podAffinityTerm
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to a pod label update), the
+                          system may or may not try to eventually evict the pod from its node.
+                          When there are multiple elements, the lists of nodes corresponding to each
+                          podAffinityTerm are intersected, i.e. all terms must be satisfied.
+                        items:
+                          description: |-
+                            Defines a set of pods (namely those matching the labelSelector
+                            relative to the given namespace(s)) that this pod should be
+                            co-located (affinity) or not co-located (anti-affinity) with,
+                            where co-located is defined as running on a node whose value of
+                            the label with key <topologyKey> matches that of any node on which
+                            a pod of the set of pods is running
+                          properties:
+                            labelSelector:
+                              description: |-
+                                A label query over a set of resources, in this case pods.
+                                If it's null, this PodAffinityTerm matches with no Pods.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            matchLabelKeys:
+                              description: |-
+                                MatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            mismatchLabelKeys:
+                              description: |-
+                                MismatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            namespaceSelector:
+                              description: |-
+                                A label query over the set of namespaces that the term applies to.
+                                The term is applied to the union of the namespaces selected by this field
+                                and the ones listed in the namespaces field.
+                                null selector and null or empty namespaces list means "this pod's namespace".
+                                An empty selector ({}) matches all namespaces.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            namespaces:
+                              description: |-
+                                namespaces specifies a static list of namespace names that the term applies to.
+                                The term is applied to the union of the namespaces listed in this field
+                                and the ones selected by namespaceSelector.
+                                null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            topologyKey:
+                              description: |-
+                                This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                whose value of the label with key topologyKey matches that of any node on which any of the
+                                selected pods is running.
+                                Empty topologyKey is not allowed.
+                              type: string
+                          required:
+                          - topologyKey
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                    type: object
+                  podAntiAffinity:
+                    description: Describes pod anti-affinity scheduling rules (e.g.
+                      avoid putting this pod in the same node, zone, etc. as some
+                      other pod(s)).
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the anti-affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling anti-affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and subtracting
+                          "weight" from the sum if the node has pods which matches the corresponding podAffinityTerm; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: The weights of all of the matched WeightedPodAffinityTerm
+                            fields are added per-node to find the most preferred node(s)
+                          properties:
+                            podAffinityTerm:
+                              description: Required. A pod affinity term, associated
+                                with the corresponding weight.
+                              properties:
+                                labelSelector:
+                                  description: |-
+                                    A label query over a set of resources, in this case pods.
+                                    If it's null, this PodAffinityTerm matches with no Pods.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                matchLabelKeys:
+                                  description: |-
+                                    MatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                    Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                mismatchLabelKeys:
+                                  description: |-
+                                    MismatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                    Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                namespaceSelector:
+                                  description: |-
+                                    A label query over the set of namespaces that the term applies to.
+                                    The term is applied to the union of the namespaces selected by this field
+                                    and the ones listed in the namespaces field.
+                                    null selector and null or empty namespaces list means "this pod's namespace".
+                                    An empty selector ({}) matches all namespaces.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                namespaces:
+                                  description: |-
+                                    namespaces specifies a static list of namespace names that the term applies to.
+                                    The term is applied to the union of the namespaces listed in this field
+                                    and the ones selected by namespaceSelector.
+                                    null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                topologyKey:
+                                  description: |-
+                                    This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                    the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                    whose value of the label with key topologyKey matches that of any node on which any of the
+                                    selected pods is running.
+                                    Empty topologyKey is not allowed.
+                                  type: string
+                              required:
+                              - topologyKey
+                              type: object
+                            weight:
+                              description: |-
+                                weight associated with matching the corresponding podAffinityTerm,
+                                in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - podAffinityTerm
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the anti-affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the anti-affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to a pod label update), the
+                          system may or may not try to eventually evict the pod from its node.
+                          When there are multiple elements, the lists of nodes corresponding to each
+                          podAffinityTerm are intersected, i.e. all terms must be satisfied.
+                        items:
+                          description: |-
+                            Defines a set of pods (namely those matching the labelSelector
+                            relative to the given namespace(s)) that this pod should be
+                            co-located (affinity) or not co-located (anti-affinity) with,
+                            where co-located is defined as running on a node whose value of
+                            the label with key <topologyKey> matches that of any node on which
+                            a pod of the set of pods is running
+                          properties:
+                            labelSelector:
+                              description: |-
+                                A label query over a set of resources, in this case pods.
+                                If it's null, this PodAffinityTerm matches with no Pods.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            matchLabelKeys:
+                              description: |-
+                                MatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            mismatchLabelKeys:
+                              description: |-
+                                MismatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            namespaceSelector:
+                              description: |-
+                                A label query over the set of namespaces that the term applies to.
+                                The term is applied to the union of the namespaces selected by this field
+                                and the ones listed in the namespaces field.
+                                null selector and null or empty namespaces list means "this pod's namespace".
+                                An empty selector ({}) matches all namespaces.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            namespaces:
+                              description: |-
+                                namespaces specifies a static list of namespace names that the term applies to.
+                                The term is applied to the union of the namespaces listed in this field
+                                and the ones selected by namespaceSelector.
+                                null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            topologyKey:
+                              description: |-
+                                This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                whose value of the label with key topologyKey matches that of any node on which any of the
+                                selected pods is running.
+                                Empty topologyKey is not allowed.
+                              type: string
+                          required:
+                          - topologyKey
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                    type: object
+                type: object
+              blend:
+                description: blend defines the CacheBlend tunables injected into the
+                  vLLM connect-config.
+                properties:
+                  checkLayer:
+                    default: 1
+                    description: |-
+                      checkLayer is the layer index used by CacheBlend to decide which tokens
+                      to recompute. It is surfaced to the connector as
+                      kv_connector_extra_config["cb.check_layer"].
+                    format: int32
+                    minimum: 0
+                    type: integer
+                  recompRatio:
+                    default: 0.15
+                    description: |-
+                      recompRatio is the fraction of tokens CacheBlend recomputes. It is
+                      surfaced to the connector as kv_connector_extra_config["cb.recomp_ratio"]
+                      and must be in (0, 1].
+                    type: number
+                type: object
+              coordinator:
+                description: |-
+                  coordinator configures registration with an MP coordinator. When unset,
+                  the server does not register with any coordinator.
+                properties:
+                  advertiseIP:
+                    description: |-
+                      advertiseIP is the IP the coordinator should reach this server at.
+
+                      DO NOT SET THIS IN ALMOST EVERY CASE. When unset, the server's pod IP is
+                      injected automatically via the downward API, which is the correct value
+                      for normal in-cluster deployments. Only set this if you know exactly what
+                      you are doing -- e.g. the coordinator runs outside the cluster and must
+                      reach the server through a specific externally-routable address. An
+                      incorrect value silently breaks coordinator-to-server connectivity.
+                    type: string
+                  heartbeatInterval:
+                    default: 5
+                    description: heartbeatInterval is the seconds between heartbeats;
+                      must be > 0.
+                    type: number
+                  l2EventFlushInterval:
+                    default: 1
+                    description: |-
+                      l2EventFlushInterval is the seconds between L2 event flush attempts; must
+                      be > 0.
+                    type: number
+                  l2EventReporting:
+                    default: false
+                    description: |-
+                      l2EventReporting enables reporting L2 store/lookup events to the
+                      coordinator for fleet-wide usage tracking and eviction.
+                    type: boolean
+                  ref:
+                    description: |-
+                      ref names an LMCacheCoordinator in the same namespace. The operator
+                      resolves it to the coordinator's in-cluster Service URL.
+                    properties:
+                      name:
+                        default: ""
+                        description: |-
+                          Name of the referent.
+                          This field is effectively required, but due to backwards compatibility is
+                          allowed to be empty. Instances of this type with an empty value here are
+                          almost certainly wrong.
+                          More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                        type: string
+                    type: object
+                    x-kubernetes-map-type: atomic
+                  url:
+                    description: |-
+                      url is an explicit coordinator base URL (e.g. http://coordinator:9300),
+                      used to target a coordinator the operator does not manage.
+                    type: string
+                type: object
+              env:
+                description: env defines additional environment variables.
+                items:
+                  description: EnvVar represents an environment variable present in
+                    a Container.
+                  properties:
+                    name:
+                      description: |-
+                        Name of the environment variable.
+                        May consist of any printable ASCII characters except '='.
+                      type: string
+                    value:
+                      description: |-
+                        Variable references $(VAR_NAME) are expanded
+                        using the previously defined environment variables in the container and
+                        any service environment variables. If a variable cannot be resolved,
+                        the reference in the input string will be unchanged. Double $$ are reduced
+                        to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.
+                        "$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
+                        Escaped references will never be expanded, regardless of whether the variable
+                        exists or not.
+                        Defaults to "".
+                      type: string
+                    valueFrom:
+                      description: Source for the environment variable's value. Cannot
+                        be used if value is not empty.
+                      properties:
+                        configMapKeyRef:
+                          description: Selects a key of a ConfigMap.
+                          properties:
+                            key:
+                              description: The key to select.
+                              type: string
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                            optional:
+                              description: Specify whether the ConfigMap or its key
+                                must be defined
+                              type: boolean
+                          required:
+                          - key
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        fieldRef:
+                          description: |-
+                            Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`,
+                            spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
+                          properties:
+                            apiVersion:
+                              description: Version of the schema the FieldPath is
+                                written in terms of, defaults to "v1".
+                              type: string
+                            fieldPath:
+                              description: Path of the field to select in the specified
+                                API version.
+                              type: string
+                          required:
+                          - fieldPath
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        fileKeyRef:
+                          description: |-
+                            FileKeyRef selects a key of the env file.
+                            Requires the EnvFiles feature gate to be enabled.
+                          properties:
+                            key:
+                              description: |-
+                                The key within the env file. An invalid key will prevent the pod from starting.
+                                The keys defined within a source may consist of any printable ASCII characters except '='.
+                                During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.
+                              type: string
+                            optional:
+                              default: false
+                              description: |-
+                                Specify whether the file or its key must be defined. If the file or key
+                                does not exist, then the env var is not published.
+                                If optional is set to true and the specified key does not exist,
+                                the environment variable will not be set in the Pod's containers.
+
+                                If optional is set to false and the specified key does not exist,
+                                an error will be returned during Pod creation.
+                              type: boolean
+                            path:
+                              description: |-
+                                The path within the volume from which to select the file.
+                                Must be relative and may not contain the '..' path or start with '..'.
+                              type: string
+                            volumeName:
+                              description: The name of the volume mount containing
+                                the env file.
+                              type: string
+                          required:
+                          - key
+                          - path
+                          - volumeName
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        resourceFieldRef:
+                          description: |-
+                            Selects a resource of the container: only resources limits and requests
+                            (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
+                          properties:
+                            containerName:
+                              description: 'Container name: required for volumes,
+                                optional for env vars'
+                              type: string
+                            divisor:
+                              anyOf:
+                              - type: integer
+                              - type: string
+                              description: Specifies the output format of the exposed
+                                resources, defaults to "1"
+                              pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                              x-kubernetes-int-or-string: true
+                            resource:
+                              description: 'Required: resource to select'
+                              type: string
+                          required:
+                          - resource
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        secretKeyRef:
+                          description: Selects a key of a secret in the pod's namespace
+                          properties:
+                            key:
+                              description: The key of the secret to select from.  Must
+                                be a valid secret key.
+                              type: string
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                            optional:
+                              description: Specify whether the Secret or its key must
+                                be defined
+                              type: boolean
+                          required:
+                          - key
+                          type: object
+                          x-kubernetes-map-type: atomic
+                      type: object
+                  required:
+                  - name
+                  type: object
+                type: array
+              eviction:
+                description: eviction defines the cache eviction configuration.
+                properties:
+                  evictionRatio:
+                    default: 0.2
+                    description: evictionRatio is the fraction of cache to evict when
+                      triggered.
+                    type: number
+                  policy:
+                    default: LRU
+                    description: policy is the eviction policy. LRU or noop.
+                    enum:
+                    - LRU
+                    - noop
+                    type: string
+                  triggerWatermark:
+                    default: 0.8
+                    description: triggerWatermark is the cache usage ratio that triggers
+                      eviction.
+                    type: number
+                type: object
+              extraArgs:
+                description: |-
+                  extraArgs are additional CLI flags appended to the server command.
+                  They are appended last and can override any auto-generated flag.
+                items:
+                  type: string
+                type: array
+              gpuVendor:
+                default: nvidia
+                description: |-
+                  gpuVendor selects the GPU vendor. "nvidia" (default) requires the NVIDIA
+                  GPU Operator's "nvidia" RuntimeClass; "amd" runs on the default container
+                  runtime.
+                enum:
+                - nvidia
+                - amd
+                type: string
+              image:
+                description: |-
+                  image defines the container image to use for the blend_v3 engine. This
+                  may be a PRIVATE image; use imagePullSecrets to pull it.
+                properties:
+                  pullPolicy:
+                    default: IfNotPresent
+                    description: pullPolicy is the image pull policy.
+                    enum:
+                    - Always
+                    - Never
+                    - IfNotPresent
+                    type: string
+                  repository:
+                    default: lmcache/vllm-openai
+                    description: repository is the container image repository.
+                    type: string
+                  tag:
+                    default: latest
+                    description: tag is the container image tag.
+                    type: string
+                type: object
+              imagePullSecrets:
+                description: |-
+                  imagePullSecrets is a list of references to secrets for pulling the
+                  engine image.
+                items:
+                  description: |-
+                    LocalObjectReference contains enough information to let you locate the
+                    referenced object inside the same namespace.
+                  properties:
+                    name:
+                      default: ""
+                      description: |-
+                        Name of the referent.
+                        This field is effectively required, but due to backwards compatibility is
+                        allowed to be empty. Instances of this type with an empty value here are
+                        almost certainly wrong.
+                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      type: string
+                  type: object
+                  x-kubernetes-map-type: atomic
+                type: array
+              injection:
+                description: |-
+                  injection defines the defaults the mutating webhook reads for pods bound
+                  to this engine.
+                properties:
+                  cudagraph:
+                    default: eager
+                    description: |-
+                      cudagraph selects the CUDA graph mode injected into the vLLM args. "eager"
+                      (default) maps to --enforce-eager; "full_decode_only" enables decode-only
+                      graphs. Full graphs are never used.
+                    enum:
+                    - eager
+                    - piecewise
+                    - full_decode_only
+                    type: string
+                  imagePullSecrets:
+                    description: |-
+                      imagePullSecrets are appended to the vLLM pod's spec.imagePullSecrets so
+                      the PRIVATE payload init-container image can pull. The referenced
+                      Secret(s) must already exist in the vLLM pod's namespace; the operator
+                      does not copy them cross-namespace.
+                    items:
+                      description: |-
+                        LocalObjectReference contains enough information to let you locate the
+                        referenced object inside the same namespace.
+                      properties:
+                        name:
+                          default: ""
+                          description: |-
+                            Name of the referent.
+                            This field is effectively required, but due to backwards compatibility is
+                            allowed to be empty. Instances of this type with an empty value here are
+                            almost certainly wrong.
+                            More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                          type: string
+                      type: object
+                      x-kubernetes-map-type: atomic
+                    type: array
+                  payloadImage:
+                    description: |-
+                      payloadImage is the init-container image (repository/tag/pullPolicy, like
+                      spec.image) that stages the lmcache-cacheblend vLLM plugin into a shared
+                      emptyDir. It is a SEPARATE, usually PRIVATE image: set
+                      payloadImage.repository to your cacheblend-plugin image — the repository
+                      default inherited from ImageSpec is the engine image and is NOT a valid
+                      payload. For private registries, imagePullSecrets must reference Secret(s)
+                      that exist in the vLLM pod's namespace.
+                    properties:
+                      pullPolicy:
+                        default: IfNotPresent
+                        description: pullPolicy is the image pull policy.
+                        enum:
+                        - Always
+                        - Never
+                        - IfNotPresent
+                        type: string
+                      repository:
+                        default: lmcache/vllm-openai
+                        description: repository is the container image repository.
+                        type: string
+                      tag:
+                        default: latest
+                        description: tag is the container image tag.
+                        type: string
+                    type: object
+                  targetContainer:
+                    description: |-
+                      targetContainer is the name of the vLLM container to inject into. Empty
+                      (the default) selects the first container; a per-pod annotation may
+                      override it.
+                    type: string
+                type: object
+              l1:
+                description: l1 defines the L1 memory cache configuration.
+                properties:
+                  sizeGB:
+                    description: |-
+                      sizeGB is the L1 cache size in gigabytes. Required, must be > 0.
+                      The CRD-level constraint (exclusiveMinimum=0) rejects invalid values
+                      at admission time so the controller never sees them; the in-Go
+                      ValidateSpec keeps the same rule for defense in depth.
+                    exclusiveMinimum: true
+                    minimum: 0
+                    type: number
+                required:
+                - sizeGB
+                type: object
+              l2Backend:
+                description: |-
+                  l2Backend defines the L2 storage backend.
+                  Currently only a single adapter is supported.
+                properties:
+                  prefetchMaxInFlight:
+                    default: 8
+                    description: |-
+                      prefetchMaxInFlight limits the number of concurrent prefetch
+                      (L2→L1 load) requests, preventing excessive L1 memory pressure.
+                    format: int32
+                    minimum: 1
+                    type: integer
+                  prefetchPolicy:
+                    default: default
+                    description: |-
+                      prefetchPolicy controls how keys flow from L2 back to L1 on
+                      cache misses. "default" picks the first adapter that has the key.
+                    enum:
+                    - default
+                    - retain
+                    type: string
+                  raw:
+                    description: |-
+                      raw is an escape hatch for adapter types not yet natively
+                      supported by the operator (e.g. nixl_store, fs, mock).
+                      The JSON is passed through to --l2-adapter as-is.
+                    properties:
+                      config:
+                        additionalProperties:
+                          x-kubernetes-preserve-unknown-fields: true
+                        description: config is type-specific configuration as a free-form
+                          map.
+                        type: object
+                      type:
+                        description: type is the adapter type name (e.g. "nixl_store",
+                          "fs", "mock").
+                        type: string
+                    required:
+                    - type
+                    type: object
+                  resp:
+                    description: |-
+                      resp configures a Redis/Valkey RESP L2 adapter backed by the
+                      native C++ connector.
+                    properties:
+                      authSecretRef:
+                        description: |-
+                          authSecretRef is a reference to a Secret containing "username"
+                          and "password" keys for Redis authentication.
+                          The Secret may live in a different namespace; the operator will
+                          create a managed copy in the LMCacheEngine's namespace.
+                          The credentials are injected via environment variables so they
+                          do not appear in container args or kubectl describe output.
+                        properties:
+                          name:
+                            description: name is the name of the Secret.
+                            type: string
+                          namespace:
+                            description: |-
+                              namespace is the namespace of the Secret.
+                              If empty, defaults to the namespace of the LMCacheEngine resource.
+                            type: string
+                        required:
+                        - name
+                        type: object
+                      host:
+                        description: host is the Redis/Valkey server hostname or IP.
+                        type: string
+                      maxCapacityGB:
+                        default: 0
+                        description: |-
+                          maxCapacityGB is the max L2 capacity in GB for usage tracking
+                          and eviction. 0 means disabled.
+                        type: number
+                      numWorkers:
+                        default: 8
+                        description: numWorkers is the number of C++ worker threads
+                          for I/O.
+                        format: int32
+                        minimum: 1
+                        type: integer
+                      port:
+                        description: port is the Redis/Valkey server port.
+                        format: int32
+                        maximum: 65535
+                        minimum: 1
+                        type: integer
+                    required:
+                    - host
+                    - port
+                    type: object
+                  storePolicy:
+                    default: default
+                    description: |-
+                      storePolicy controls how keys flow from L1 to L2.
+                      "default" stores all keys to the adapter and keeps L1.
+                      "skip_l1" stores all keys to the adapter and deletes them from L1
+                      (buffer-only mode — pair with eviction.policy=noop).
+                    enum:
+                    - default
+                    - skip_l1
+                    type: string
+                type: object
+              logLevel:
+                default: INFO
+                description: logLevel is the log level for the LMCache server.
+                enum:
+                - DEBUG
+                - INFO
+                - WARNING
+                - ERROR
+                type: string
+              nodeSelector:
+                additionalProperties:
+                  type: string
+                description: nodeSelector determines which nodes get a CacheBlend
+                  engine instance.
+                type: object
+              podAnnotations:
+                additionalProperties:
+                  type: string
+                description: podAnnotations are additional annotations added to pods.
+                type: object
+              podLabels:
+                additionalProperties:
+                  type: string
+                description: podLabels are additional labels added to pods.
+                type: object
+              priorityClassName:
+                description: priorityClassName is the priority class for the pods.
+                type: string
+              privileged:
+                default: false
+                description: |-
+                  privileged runs the engine container in privileged mode. On some clusters
+                  this is required for the engine to see all node GPUs (for CUDA IPC) without
+                  claiming any via the nvidia.com/gpu device plugin; on many clusters
+                  NVIDIA_VISIBLE_DEVICES=all already grants that visibility without it, so it
+                  defaults to false. Set it to true only on clusters where the engine cannot
+                  otherwise see the GPUs. For gpuVendor "amd" this is effectively required:
+                  there is no NVIDIA-style RuntimeClass device injection, so privileged mode
+                  is the only way the engine reaches /dev/kfd and /dev/dri. Clusters using Pod
+                  Security Standards must allow the privileged profile for this namespace when
+                  it is enabled. Default: false.
+                type: boolean
+              prometheus:
+                description: prometheus defines Prometheus monitoring configuration.
+                properties:
+                  enabled:
+                    default: true
+                    description: enabled controls whether Prometheus metrics are exposed.
+                    type: boolean
+                  port:
+                    default: 9090
+                    description: port is the Prometheus metrics port.
+                    format: int32
+                    type: integer
+                  serviceMonitor:
+                    description: serviceMonitor configures the Prometheus ServiceMonitor.
+                    properties:
+                      enabled:
+                        default: false
+                        description: enabled controls whether a ServiceMonitor CR
+                          is created.
+                        type: boolean
+                      interval:
+                        default: 30s
+                        description: interval is the Prometheus scrape interval.
+                        type: string
+                      labels:
+                        additionalProperties:
+                          type: string
+                        description: labels are additional labels added to the ServiceMonitor.
+                        type: object
+                    type: object
+                type: object
+              resourceOverrides:
+                description: resourceOverrides allows overriding auto-computed resource
+                  requirements.
+                properties:
+                  claims:
+                    description: |-
+                      Claims lists the names of resources, defined in spec.resourceClaims,
+                      that are used by this container.
+
+                      This field depends on the
+                      DynamicResourceAllocation feature gate.
+
+                      This field is immutable. It can only be set for containers.
+                    items:
+                      description: ResourceClaim references one entry in PodSpec.ResourceClaims.
+                      properties:
+                        name:
+                          description: |-
+                            Name must match the name of one entry in pod.spec.resourceClaims of
+                            the Pod where this field is used. It makes that resource available
+                            inside a container.
+                          type: string
+                        request:
+                          description: |-
+                            Request is the name chosen for a request in the referenced claim.
+                            If empty, everything from the claim is made available, otherwise
+                            only the result of this request.
+                          type: string
+                      required:
+                      - name
+                      type: object
+                    type: array
+                    x-kubernetes-list-map-keys:
+                    - name
+                    x-kubernetes-list-type: map
+                  limits:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Limits describes the maximum amount of compute resources allowed.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                  requests:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Requests describes the minimum amount of compute resources required.
+                      If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                      otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                type: object
+              server:
+                description: |-
+                  server defines server configuration. chunkSize defaults to 256 because
+                  CacheBlend requires chunk_size == 256.
+                properties:
+                  chunkSize:
+                    default: 256
+                    description: chunkSize is the token chunk size.
+                    format: int32
+                    type: integer
+                  hashAlgorithm:
+                    default: blake3
+                    description: hashAlgorithm is the hash algorithm used for token
+                      hashing.
+                    enum:
+                    - builtin
+                    - sha256_cbor
+                    - blake3
+                    type: string
+                  httpPort:
+                    default: 8080
+                    description: httpPort is the HTTP frontend port (health checks,
+                      cache admin).
+                    format: int32
+                    maximum: 65535
+                    minimum: 1024
+                    type: integer
+                  maxWorkers:
+                    default: 1
+                    description: maxWorkers is the number of worker threads.
+                    format: int32
+                    type: integer
+                  port:
+                    default: 5555
+                    description: port is the server listening port.
+                    format: int32
+                    maximum: 65535
+                    minimum: 1024
+                    type: integer
+                type: object
+              serviceAccountName:
+                description: serviceAccountName is the name of the ServiceAccount
+                  to use.
+                type: string
+              tolerations:
+                description: tolerations defines pod tolerations.
+                items:
+                  description: |-
+                    The pod this Toleration is attached to tolerates any taint that matches
+                    the triple <key,value,effect> using the matching operator <operator>.
+                  properties:
+                    effect:
+                      description: |-
+                        Effect indicates the taint effect to match. Empty means match all taint effects.
+                        When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.
+                      type: string
+                    key:
+                      description: |-
+                        Key is the taint key that the toleration applies to. Empty means match all taint keys.
+                        If the key is empty, operator must be Exists; this combination means to match all values and all keys.
+                      type: string
+                    operator:
+                      description: |-
+                        Operator represents a key's relationship to the value.
+                        Valid operators are Exists, Equal, Lt, and Gt. Defaults to Equal.
+                        Exists is equivalent to wildcard for value, so that a pod can
+                        tolerate all taints of a particular category.
+                        Lt and Gt perform numeric comparisons (requires feature gate TaintTolerationComparisonOperators).
+                      type: string
+                    tolerationSeconds:
+                      description: |-
+                        TolerationSeconds represents the period of time the toleration (which must be
+                        of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default,
+                        it is not set, which means tolerate the taint forever (do not evict). Zero and
+                        negative values will be treated as 0 (evict immediately) by the system.
+                      format: int64
+                      type: integer
+                    value:
+                      description: |-
+                        Value is the taint value the toleration matches to.
+                        If the operator is Exists, the value should be empty, otherwise just a regular string.
+                      type: string
+                  type: object
+                type: array
+              volumeMounts:
+                description: volumeMounts defines additional volume mounts.
+                items:
+                  description: VolumeMount describes a mounting of a Volume within
+                    a container.
+                  properties:
+                    mountPath:
+                      description: |-
+                        Path within the container at which the volume should be mounted.  Must
+                        not contain ':'.
+                      type: string
+                    mountPropagation:
+                      description: |-
+                        mountPropagation determines how mounts are propagated from the host
+                        to container and the other way around.
+                        When not set, MountPropagationNone is used.
+                        This field is beta in 1.10.
+                        When RecursiveReadOnly is set to IfPossible or to Enabled, MountPropagation must be None or unspecified
+                        (which defaults to None).
+                      type: string
+                    name:
+                      description: This must match the Name of a Volume.
+                      type: string
+                    readOnly:
+                      description: |-
+                        Mounted read-only if true, read-write otherwise (false or unspecified).
+                        Defaults to false.
+                      type: boolean
+                    recursiveReadOnly:
+                      description: |-
+                        RecursiveReadOnly specifies whether read-only mounts should be handled
+                        recursively.
+
+                        If ReadOnly is false, this field has no meaning and must be unspecified.
+
+                        If ReadOnly is true, and this field is set to Disabled, the mount is not made
+                        recursively read-only.  If this field is set to IfPossible, the mount is made
+                        recursively read-only, if it is supported by the container runtime.  If this
+                        field is set to Enabled, the mount is made recursively read-only if it is
+                        supported by the container runtime, otherwise the pod will not be started and
+                        an error will be generated to indicate the reason.
+
+                        If this field is set to IfPossible or Enabled, MountPropagation must be set to
+                        None (or be unspecified, which defaults to None).
+
+                        If this field is not specified, it is treated as an equivalent of Disabled.
+                      type: string
+                    subPath:
+                      description: |-
+                        Path within the volume from which the container's volume should be mounted.
+                        Defaults to "" (volume's root).
+                      type: string
+                    subPathExpr:
+                      description: |-
+                        Expanded path within the volume from which the container's volume should be mounted.
+                        Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment.
+                        Defaults to "" (volume's root).
+                        SubPathExpr and SubPath are mutually exclusive.
+                      type: string
+                  required:
+                  - mountPath
+                  - name
+                  type: object
+                type: array
+              volumes:
+                description: volumes defines additional volumes.
+                items:
+                  description: Volume represents a named volume in a pod that may
+                    be accessed by any container in the pod.
+                  properties:
+                    awsElasticBlockStore:
+                      description: |-
+                        awsElasticBlockStore represents an AWS Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree
+                        awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: string
+                        partition:
+                          description: |-
+                            partition is the partition in the volume that you want to mount.
+                            If omitted, the default is to mount by volume name.
+                            Examples: For volume /dev/sda1, you specify the partition as "1".
+                            Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty).
+                          format: int32
+                          type: integer
+                        readOnly:
+                          description: |-
+                            readOnly value true will force the readOnly setting in VolumeMounts.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: boolean
+                        volumeID:
+                          description: |-
+                            volumeID is unique ID of the persistent disk resource in AWS (Amazon EBS volume).
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    azureDisk:
+                      description: |-
+                        azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod.
+                        Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type
+                        are redirected to the disk.csi.azure.com CSI driver.
+                      properties:
+                        cachingMode:
+                          description: 'cachingMode is the Host Caching mode: None,
+                            Read Only, Read Write.'
+                          type: string
+                        diskName:
+                          description: diskName is the Name of the data disk in the
+                            blob storage
+                          type: string
+                        diskURI:
+                          description: diskURI is the URI of data disk in the blob
+                            storage
+                          type: string
+                        fsType:
+                          default: ext4
+                          description: |-
+                            fsType is Filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        kind:
+                          description: 'kind expected values are Shared: multiple
+                            blob disks per storage account  Dedicated: single blob
+                            disk per storage account  Managed: azure managed data
+                            disk (only in managed availability set). defaults to shared'
+                          type: string
+                        readOnly:
+                          default: false
+                          description: |-
+                            readOnly Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                      required:
+                      - diskName
+                      - diskURI
+                      type: object
+                    azureFile:
+                      description: |-
+                        azureFile represents an Azure File Service mount on the host and bind mount to the pod.
+                        Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type
+                        are redirected to the file.csi.azure.com CSI driver.
+                      properties:
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretName:
+                          description: secretName is the  name of secret that contains
+                            Azure Storage Account Name and Key
+                          type: string
+                        shareName:
+                          description: shareName is the azure share Name
+                          type: string
+                      required:
+                      - secretName
+                      - shareName
+                      type: object
+                    cephfs:
+                      description: |-
+                        cephFS represents a Ceph FS mount on the host that shares a pod's lifetime.
+                        Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported.
+                      properties:
+                        monitors:
+                          description: |-
+                            monitors is Required: Monitors is a collection of Ceph monitors
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        path:
+                          description: 'path is Optional: Used as the mounted root,
+                            rather than the full Ceph tree, default is /'
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: boolean
+                        secretFile:
+                          description: |-
+                            secretFile is Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: string
+                        secretRef:
+                          description: |-
+                            secretRef is Optional: SecretRef is reference to the authentication secret for User, default is empty.
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        user:
+                          description: |-
+                            user is optional: User is the rados user name, default is admin
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: string
+                      required:
+                      - monitors
+                      type: object
+                    cinder:
+                      description: |-
+                        cinder represents a cinder volume attached and mounted on kubelets host machine.
+                        Deprecated: Cinder is deprecated. All operations for the in-tree cinder type
+                        are redirected to the cinder.csi.openstack.org CSI driver.
+                        More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is optional: points to a secret object containing parameters used to connect
+                            to OpenStack.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        volumeID:
+                          description: |-
+                            volumeID used to identify the volume in cinder.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    configMap:
+                      description: configMap represents a configMap that should populate
+                        this volume
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode is optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: |-
+                            items if unspecified, each key-value pair in the Data field of the referenced
+                            ConfigMap will be projected into the volume as a file whose name is the
+                            key and content is the value. If specified, the listed keys will be
+                            projected into the specified paths, and unlisted keys will not be
+                            present. If a key is specified which is not present in the ConfigMap,
+                            the volume setup will error unless it is marked optional. Paths must be
+                            relative and may not contain the '..' path or start with '..'.
+                          items:
+                            description: Maps a string key to a path within a volume.
+                            properties:
+                              key:
+                                description: key is the key to project.
+                                type: string
+                              mode:
+                                description: |-
+                                  mode is Optional: mode bits used to set permissions on this file.
+                                  Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: |-
+                                  path is the relative path of the file to map the key to.
+                                  May not be an absolute path.
+                                  May not contain the path element '..'.
+                                  May not start with the string '..'.
+                                type: string
+                            required:
+                            - key
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        name:
+                          default: ""
+                          description: |-
+                            Name of the referent.
+                            This field is effectively required, but due to backwards compatibility is
+                            allowed to be empty. Instances of this type with an empty value here are
+                            almost certainly wrong.
+                            More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                          type: string
+                        optional:
+                          description: optional specify whether the ConfigMap or its
+                            keys must be defined
+                          type: boolean
+                      type: object
+                      x-kubernetes-map-type: atomic
+                    csi:
+                      description: csi (Container Storage Interface) represents ephemeral
+                        storage that is handled by certain external CSI drivers.
+                      properties:
+                        driver:
+                          description: |-
+                            driver is the name of the CSI driver that handles this volume.
+                            Consult with your admin for the correct name as registered in the cluster.
+                          type: string
+                        fsType:
+                          description: |-
+                            fsType to mount. Ex. "ext4", "xfs", "ntfs".
+                            If not provided, the empty value is passed to the associated CSI driver
+                            which will determine the default filesystem to apply.
+                          type: string
+                        nodePublishSecretRef:
+                          description: |-
+                            nodePublishSecretRef is a reference to the secret object containing
+                            sensitive information to pass to the CSI driver to complete the CSI
+                            NodePublishVolume and NodeUnpublishVolume calls.
+                            This field is optional, and  may be empty if no secret is required. If the
+                            secret object contains more than one secret, all secret references are passed.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        readOnly:
+                          description: |-
+                            readOnly specifies a read-only configuration for the volume.
+                            Defaults to false (read/write).
+                          type: boolean
+                        volumeAttributes:
+                          additionalProperties:
+                            type: string
+                          description: |-
+                            volumeAttributes stores driver-specific properties that are passed to the CSI
+                            driver. Consult your driver's documentation for supported values.
+                          type: object
+                      required:
+                      - driver
+                      type: object
+                    downwardAPI:
+                      description: downwardAPI represents downward API about the pod
+                        that should populate this volume
+                      properties:
+                        defaultMode:
+                          description: |-
+                            Optional: mode bits to use on created files by default. Must be a
+                            Optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: Items is a list of downward API volume file
+                          items:
+                            description: DownwardAPIVolumeFile represents information
+                              to create the file containing the pod field
+                            properties:
+                              fieldRef:
+                                description: 'Required: Selects a field of the pod:
+                                  only annotations, labels, name, namespace and uid
+                                  are supported.'
+                                properties:
+                                  apiVersion:
+                                    description: Version of the schema the FieldPath
+                                      is written in terms of, defaults to "v1".
+                                    type: string
+                                  fieldPath:
+                                    description: Path of the field to select in the
+                                      specified API version.
+                                    type: string
+                                required:
+                                - fieldPath
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              mode:
+                                description: |-
+                                  Optional: mode bits used to set permissions on this file, must be an octal value
+                                  between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: 'Required: Path is  the relative path
+                                  name of the file to be created. Must not be absolute
+                                  or contain the ''..'' path. Must be utf-8 encoded.
+                                  The first item of the relative path must not start
+                                  with ''..'''
+                                type: string
+                              resourceFieldRef:
+                                description: |-
+                                  Selects a resource of the container: only resources limits and requests
+                                  (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.
+                                properties:
+                                  containerName:
+                                    description: 'Container name: required for volumes,
+                                      optional for env vars'
+                                    type: string
+                                  divisor:
+                                    anyOf:
+                                    - type: integer
+                                    - type: string
+                                    description: Specifies the output format of the
+                                      exposed resources, defaults to "1"
+                                    pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                    x-kubernetes-int-or-string: true
+                                  resource:
+                                    description: 'Required: resource to select'
+                                    type: string
+                                required:
+                                - resource
+                                type: object
+                                x-kubernetes-map-type: atomic
+                            required:
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    emptyDir:
+                      description: |-
+                        emptyDir represents a temporary directory that shares a pod's lifetime.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                      properties:
+                        medium:
+                          description: |-
+                            medium represents what type of storage medium should back this directory.
+                            The default is "" which means to use the node's default medium.
+                            Must be an empty string (default) or Memory.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                          type: string
+                        sizeLimit:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          description: |-
+                            sizeLimit is the total amount of local storage required for this EmptyDir volume.
+                            The size limit is also applicable for memory medium.
+                            The maximum usage on memory medium EmptyDir would be the minimum value between
+                            the SizeLimit specified here and the sum of memory limits of all containers in a pod.
+                            The default is nil which means that the limit is undefined.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                          pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                          x-kubernetes-int-or-string: true
+                      type: object
+                    ephemeral:
+                      description: |-
+                        ephemeral represents a volume that is handled by a cluster storage driver.
+                        The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts,
+                        and deleted when the pod is removed.
+
+                        Use this if:
+                        a) the volume is only needed while the pod runs,
+                        b) features of normal volumes like restoring from snapshot or capacity
+                           tracking are needed,
+                        c) the storage driver is specified through a storage class, and
+                        d) the storage driver supports dynamic volume provisioning through
+                           a PersistentVolumeClaim (see EphemeralVolumeSource for more
+                           information on the connection between this volume type
+                           and PersistentVolumeClaim).
+
+                        Use PersistentVolumeClaim or one of the vendor-specific
+                        APIs for volumes that persist for longer than the lifecycle
+                        of an individual pod.
+
+                        Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to
+                        be used that way - see the documentation of the driver for
+                        more information.
+
+                        A pod can use both types of ephemeral volumes and
+                        persistent volumes at the same time.
+                      properties:
+                        volumeClaimTemplate:
+                          description: |-
+                            Will be used to create a stand-alone PVC to provision the volume.
+                            The pod in which this EphemeralVolumeSource is embedded will be the
+                            owner of the PVC, i.e. the PVC will be deleted together with the
+                            pod.  The name of the PVC will be `<pod name>-<volume name>` where
+                            `<volume name>` is the name from the `PodSpec.Volumes` array
+                            entry. Pod validation will reject the pod if the concatenated name
+                            is not valid for a PVC (for example, too long).
+
+                            An existing PVC with that name that is not owned by the pod
+                            will *not* be used for the pod to avoid using an unrelated
+                            volume by mistake. Starting the pod is then blocked until
+                            the unrelated PVC is removed. If such a pre-created PVC is
+                            meant to be used by the pod, the PVC has to updated with an
+                            owner reference to the pod once the pod exists. Normally
+                            this should not be necessary, but it may be useful when
+                            manually reconstructing a broken cluster.
+
+                            This field is read-only and no changes will be made by Kubernetes
+                            to the PVC after it has been created.
+
+                            Required, must not be nil.
+                          properties:
+                            metadata:
+                              description: |-
+                                May contain labels and annotations that will be copied into the PVC
+                                when creating it. No other fields are allowed and will be rejected during
+                                validation.
+                              type: object
+                            spec:
+                              description: |-
+                                The specification for the PersistentVolumeClaim. The entire content is
+                                copied unchanged into the PVC that gets created from this
+                                template. The same fields as in a PersistentVolumeClaim
+                                are also valid here.
+                              properties:
+                                accessModes:
+                                  description: |-
+                                    accessModes contains the desired access modes the volume should have.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                dataSource:
+                                  description: |-
+                                    dataSource field can be used to specify either:
+                                    * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot)
+                                    * An existing PVC (PersistentVolumeClaim)
+                                    If the provisioner or an external controller can support the specified data source,
+                                    it will create a new volume based on the contents of the specified data source.
+                                    When the AnyVolumeDataSource feature gate is enabled, dataSource contents will be copied to dataSourceRef,
+                                    and dataSourceRef contents will be copied to dataSource when dataSourceRef.namespace is not specified.
+                                    If the namespace is specified, then dataSourceRef will not be copied to dataSource.
+                                  properties:
+                                    apiGroup:
+                                      description: |-
+                                        APIGroup is the group for the resource being referenced.
+                                        If APIGroup is not specified, the specified Kind must be in the core API group.
+                                        For any other third-party types, APIGroup is required.
+                                      type: string
+                                    kind:
+                                      description: Kind is the type of resource being
+                                        referenced
+                                      type: string
+                                    name:
+                                      description: Name is the name of resource being
+                                        referenced
+                                      type: string
+                                  required:
+                                  - kind
+                                  - name
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                dataSourceRef:
+                                  description: |-
+                                    dataSourceRef specifies the object from which to populate the volume with data, if a non-empty
+                                    volume is desired. This may be any object from a non-empty API group (non
+                                    core object) or a PersistentVolumeClaim object.
+                                    When this field is specified, volume binding will only succeed if the type of
+                                    the specified object matches some installed volume populator or dynamic
+                                    provisioner.
+                                    This field will replace the functionality of the dataSource field and as such
+                                    if both fields are non-empty, they must have the same value. For backwards
+                                    compatibility, when namespace isn't specified in dataSourceRef,
+                                    both fields (dataSource and dataSourceRef) will be set to the same
+                                    value automatically if one of them is empty and the other is non-empty.
+                                    When namespace is specified in dataSourceRef,
+                                    dataSource isn't set to the same value and must be empty.
+                                    There are three important differences between dataSource and dataSourceRef:
+                                    * While dataSource only allows two specific types of objects, dataSourceRef
+                                      allows any non-core object, as well as PersistentVolumeClaim objects.
+                                    * While dataSource ignores disallowed values (dropping them), dataSourceRef
+                                      preserves all values, and generates an error if a disallowed value is
+                                      specified.
+                                    * While dataSource only allows local objects, dataSourceRef allows objects
+                                      in any namespaces.
+                                    (Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled.
+                                    (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled.
+                                  properties:
+                                    apiGroup:
+                                      description: |-
+                                        APIGroup is the group for the resource being referenced.
+                                        If APIGroup is not specified, the specified Kind must be in the core API group.
+                                        For any other third-party types, APIGroup is required.
+                                      type: string
+                                    kind:
+                                      description: Kind is the type of resource being
+                                        referenced
+                                      type: string
+                                    name:
+                                      description: Name is the name of resource being
+                                        referenced
+                                      type: string
+                                    namespace:
+                                      description: |-
+                                        Namespace is the namespace of resource being referenced
+                                        Note that when a namespace is specified, a gateway.networking.k8s.io/ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details.
+                                        (Alpha) This field requires the CrossNamespaceVolumeDataSource feature gate to be enabled.
+                                      type: string
+                                  required:
+                                  - kind
+                                  - name
+                                  type: object
+                                resources:
+                                  description: |-
+                                    resources represents the minimum resources the volume should have.
+                                    Users are allowed to specify resource requirements
+                                    that are lower than previous value but must still be higher than capacity recorded in the
+                                    status field of the claim.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources
+                                  properties:
+                                    limits:
+                                      additionalProperties:
+                                        anyOf:
+                                        - type: integer
+                                        - type: string
+                                        pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                        x-kubernetes-int-or-string: true
+                                      description: |-
+                                        Limits describes the maximum amount of compute resources allowed.
+                                        More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                                      type: object
+                                    requests:
+                                      additionalProperties:
+                                        anyOf:
+                                        - type: integer
+                                        - type: string
+                                        pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                        x-kubernetes-int-or-string: true
+                                      description: |-
+                                        Requests describes the minimum amount of compute resources required.
+                                        If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                                        otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                                        More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                                      type: object
+                                  type: object
+                                selector:
+                                  description: selector is a label query over volumes
+                                    to consider for binding.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                storageClassName:
+                                  description: |-
+                                    storageClassName is the name of the StorageClass required by the claim.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1
+                                  type: string
+                                volumeAttributesClassName:
+                                  description: |-
+                                    volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim.
+                                    If specified, the CSI driver will create or update the volume with the attributes defined
+                                    in the corresponding VolumeAttributesClass. This has a different purpose than storageClassName,
+                                    it can be changed after the claim is created. An empty string or nil value indicates that no
+                                    VolumeAttributesClass will be applied to the claim. If the claim enters an Infeasible error state,
+                                    this field can be reset to its previous value (including nil) to cancel the modification.
+                                    If the resource referred to by volumeAttributesClass does not exist, this PersistentVolumeClaim will be
+                                    set to a Pending state, as reflected by the modifyVolumeStatus field, until such as a resource
+                                    exists.
+                                    More info: https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/
+                                  type: string
+                                volumeMode:
+                                  description: |-
+                                    volumeMode defines what type of volume is required by the claim.
+                                    Value of Filesystem is implied when not included in claim spec.
+                                  type: string
+                                volumeName:
+                                  description: volumeName is the binding reference
+                                    to the PersistentVolume backing this claim.
+                                  type: string
+                              type: object
+                          required:
+                          - spec
+                          type: object
+                      type: object
+                    fc:
+                      description: fc represents a Fibre Channel resource that is
+                        attached to a kubelet's host machine and then exposed to the
+                        pod.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        lun:
+                          description: 'lun is Optional: FC target lun number'
+                          format: int32
+                          type: integer
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        targetWWNs:
+                          description: 'targetWWNs is Optional: FC target worldwide
+                            names (WWNs)'
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        wwids:
+                          description: |-
+                            wwids Optional: FC volume world wide identifiers (wwids)
+                            Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously.
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    flexVolume:
+                      description: |-
+                        flexVolume represents a generic volume resource that is
+                        provisioned/attached using an exec based plugin.
+                        Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead.
+                      properties:
+                        driver:
+                          description: driver is the name of the driver to use for
+                            this volume.
+                          type: string
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script.
+                          type: string
+                        options:
+                          additionalProperties:
+                            type: string
+                          description: 'options is Optional: this field holds extra
+                            command options if any.'
+                          type: object
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is Optional: secretRef is reference to the secret object containing
+                            sensitive information to pass to the plugin scripts. This may be
+                            empty if no secret object is specified. If the secret object
+                            contains more than one secret, all secrets are passed to the plugin
+                            scripts.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                      required:
+                      - driver
+                      type: object
+                    flocker:
+                      description: |-
+                        flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running.
+                        Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported.
+                      properties:
+                        datasetName:
+                          description: |-
+                            datasetName is Name of the dataset stored as metadata -> name on the dataset for Flocker
+                            should be considered as deprecated
+                          type: string
+                        datasetUUID:
+                          description: datasetUUID is the UUID of the dataset. This
+                            is unique identifier of a Flocker dataset
+                          type: string
+                      type: object
+                    gcePersistentDisk:
+                      description: |-
+                        gcePersistentDisk represents a GCE Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree
+                        gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: string
+                        partition:
+                          description: |-
+                            partition is the partition in the volume that you want to mount.
+                            If omitted, the default is to mount by volume name.
+                            Examples: For volume /dev/sda1, you specify the partition as "1".
+                            Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty).
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          format: int32
+                          type: integer
+                        pdName:
+                          description: |-
+                            pdName is unique name of the PD resource in GCE. Used to identify the disk in GCE.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: boolean
+                      required:
+                      - pdName
+                      type: object
+                    gitRepo:
+                      description: |-
+                        gitRepo represents a git repository at a particular revision.
+                        Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an
+                        EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir
+                        into the Pod's container.
+                      properties:
+                        directory:
+                          description: |-
+                            directory is the target directory name.
+                            Must not contain or start with '..'.  If '.' is supplied, the volume directory will be the
+                            git repository.  Otherwise, if specified, the volume will contain the git repository in
+                            the subdirectory with the given name.
+                          type: string
+                        repository:
+                          description: repository is the URL
+                          type: string
+                        revision:
+                          description: revision is the commit hash for the specified
+                            revision.
+                          type: string
+                      required:
+                      - repository
+                      type: object
+                    glusterfs:
+                      description: |-
+                        glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime.
+                        Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported.
+                      properties:
+                        endpoints:
+                          description: endpoints is the endpoint name that details
+                            Glusterfs topology.
+                          type: string
+                        path:
+                          description: |-
+                            path is the Glusterfs volume path.
+                            More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the Glusterfs volume to be mounted with read-only permissions.
+                            Defaults to false.
+                            More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod
+                          type: boolean
+                      required:
+                      - endpoints
+                      - path
+                      type: object
+                    hostPath:
+                      description: |-
+                        hostPath represents a pre-existing file or directory on the host
+                        machine that is directly exposed to the container. This is generally
+                        used for system agents or other privileged things that are allowed
+                        to see the host machine. Most containers will NOT need this.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                      properties:
+                        path:
+                          description: |-
+                            path of the directory on the host.
+                            If the path is a symlink, it will follow the link to the real path.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                          type: string
+                        type:
+                          description: |-
+                            type for HostPath Volume
+                            Defaults to ""
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                          type: string
+                      required:
+                      - path
+                      type: object
+                    image:
+                      description: |-
+                        image represents an OCI object (a container image or artifact) pulled and mounted on the kubelet's host machine.
+                        The volume is resolved at pod startup depending on which PullPolicy value is provided:
+
+                        - Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
+                        - Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
+                        - IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
+
+                        The volume gets re-resolved if the pod gets deleted and recreated, which means that new remote content will become available on pod recreation.
+                        A failure to resolve or pull the image during pod startup will block containers from starting and may add significant latency. Failures will be retried using normal volume backoff and will be reported on the pod reason and message.
+                        The types of objects that may be mounted by this volume are defined by the container runtime implementation on a host machine and at minimum must include all valid types supported by the container image field.
+                        The OCI object gets mounted in a single directory (spec.containers[*].volumeMounts.mountPath) by merging the manifest layers in the same way as for container images.
+                        The volume will be mounted read-only (ro) and non-executable files (noexec).
+                        Sub path mounts for containers are not supported (spec.containers[*].volumeMounts.subpath) before 1.33.
+                        The field spec.securityContext.fsGroupChangePolicy has no effect on this volume type.
+                      properties:
+                        pullPolicy:
+                          description: |-
+                            Policy for pulling OCI objects. Possible values are:
+                            Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
+                            Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
+                            IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
+                            Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
+                          type: string
+                        reference:
+                          description: |-
+                            Required: Image or artifact reference to be used.
+                            Behaves in the same way as pod.spec.containers[*].image.
+                            Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
+                            More info: https://kubernetes.io/docs/concepts/containers/images
+                            This field is optional to allow higher level config management to default or override
+                            container images in workload controllers like Deployments and StatefulSets.
+                          type: string
+                      type: object
+                    iscsi:
+                      description: |-
+                        iscsi represents an ISCSI Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes/#iscsi
+                      properties:
+                        chapAuthDiscovery:
+                          description: chapAuthDiscovery defines whether support iSCSI
+                            Discovery CHAP authentication
+                          type: boolean
+                        chapAuthSession:
+                          description: chapAuthSession defines whether support iSCSI
+                            Session CHAP authentication
+                          type: boolean
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi
+                          type: string
+                        initiatorName:
+                          description: |-
+                            initiatorName is the custom iSCSI Initiator Name.
+                            If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface
+                            <target portal>:<volume name> will be created for the connection.
+                          type: string
+                        iqn:
+                          description: iqn is the target iSCSI Qualified Name.
+                          type: string
+                        iscsiInterface:
+                          default: default
+                          description: |-
+                            iscsiInterface is the interface Name that uses an iSCSI transport.
+                            Defaults to 'default' (tcp).
+                          type: string
+                        lun:
+                          description: lun represents iSCSI Target Lun number.
+                          format: int32
+                          type: integer
+                        portals:
+                          description: |-
+                            portals is the iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port
+                            is other than default (typically TCP ports 860 and 3260).
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                          type: boolean
+                        secretRef:
+                          description: secretRef is the CHAP Secret for iSCSI target
+                            and initiator authentication
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        targetPortal:
+                          description: |-
+                            targetPortal is iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port
+                            is other than default (typically TCP ports 860 and 3260).
+                          type: string
+                      required:
+                      - iqn
+                      - lun
+                      - targetPortal
+                      type: object
+                    name:
+                      description: |-
+                        name of the volume.
+                        Must be a DNS_LABEL and unique within the pod.
+                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      type: string
+                    nfs:
+                      description: |-
+                        nfs represents an NFS mount on the host that shares a pod's lifetime
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                      properties:
+                        path:
+                          description: |-
+                            path that is exported by the NFS server.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the NFS export to be mounted with read-only permissions.
+                            Defaults to false.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: boolean
+                        server:
+                          description: |-
+                            server is the hostname or IP address of the NFS server.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: string
+                      required:
+                      - path
+                      - server
+                      type: object
+                    persistentVolumeClaim:
+                      description: |-
+                        persistentVolumeClaimVolumeSource represents a reference to a
+                        PersistentVolumeClaim in the same namespace.
+                        More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
+                      properties:
+                        claimName:
+                          description: |-
+                            claimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume.
+                            More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly Will force the ReadOnly setting in VolumeMounts.
+                            Default false.
+                          type: boolean
+                      required:
+                      - claimName
+                      type: object
+                    photonPersistentDisk:
+                      description: |-
+                        photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine.
+                        Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        pdID:
+                          description: pdID is the ID that identifies Photon Controller
+                            persistent disk
+                          type: string
+                      required:
+                      - pdID
+                      type: object
+                    portworxVolume:
+                      description: |-
+                        portworxVolume represents a portworx volume attached and mounted on kubelets host machine.
+                        Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type
+                        are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate
+                        is on.
+                      properties:
+                        fsType:
+                          description: |-
+                            fSType represents the filesystem type to mount
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        volumeID:
+                          description: volumeID uniquely identifies a Portworx volume
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    projected:
+                      description: projected items for all in one resources secrets,
+                        configmaps, and downward API
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode are the mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        sources:
+                          description: |-
+                            sources is the list of volume projections. Each entry in this list
+                            handles one source.
+                          items:
+                            description: |-
+                              Projection that may be projected along with other supported volume types.
+                              Exactly one of these fields must be set.
+                            properties:
+                              clusterTrustBundle:
+                                description: |-
+                                  ClusterTrustBundle allows a pod to access the `.spec.trustBundle` field
+                                  of ClusterTrustBundle objects in an auto-updating file.
+
+                                  Alpha, gated by the ClusterTrustBundleProjection feature gate.
+
+                                  ClusterTrustBundle objects can either be selected by name, or by the
+                                  combination of signer name and a label selector.
+
+                                  Kubelet performs aggressive normalization of the PEM contents written
+                                  into the pod filesystem.  Esoteric PEM features such as inter-block
+                                  comments and block headers are stripped.  Certificates are deduplicated.
+                                  The ordering of certificates within the file is arbitrary, and Kubelet
+                                  may change the order over time.
+                                properties:
+                                  labelSelector:
+                                    description: |-
+                                      Select all ClusterTrustBundles that match this label selector.  Only has
+                                      effect if signerName is set.  Mutually-exclusive with name.  If unset,
+                                      interpreted as "match nothing".  If set but empty, interpreted as "match
+                                      everything".
+                                    properties:
+                                      matchExpressions:
+                                        description: matchExpressions is a list of
+                                          label selector requirements. The requirements
+                                          are ANDed.
+                                        items:
+                                          description: |-
+                                            A label selector requirement is a selector that contains values, a key, and an operator that
+                                            relates the key and values.
+                                          properties:
+                                            key:
+                                              description: key is the label key that
+                                                the selector applies to.
+                                              type: string
+                                            operator:
+                                              description: |-
+                                                operator represents a key's relationship to a set of values.
+                                                Valid operators are In, NotIn, Exists and DoesNotExist.
+                                              type: string
+                                            values:
+                                              description: |-
+                                                values is an array of string values. If the operator is In or NotIn,
+                                                the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                                the values array must be empty. This array is replaced during a strategic
+                                                merge patch.
+                                              items:
+                                                type: string
+                                              type: array
+                                              x-kubernetes-list-type: atomic
+                                          required:
+                                          - key
+                                          - operator
+                                          type: object
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                      matchLabels:
+                                        additionalProperties:
+                                          type: string
+                                        description: |-
+                                          matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                          map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                          operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                        type: object
+                                    type: object
+                                    x-kubernetes-map-type: atomic
+                                  name:
+                                    description: |-
+                                      Select a single ClusterTrustBundle by object name.  Mutually-exclusive
+                                      with signerName and labelSelector.
+                                    type: string
+                                  optional:
+                                    description: |-
+                                      If true, don't block pod startup if the referenced ClusterTrustBundle(s)
+                                      aren't available.  If using name, then the named ClusterTrustBundle is
+                                      allowed not to exist.  If using signerName, then the combination of
+                                      signerName and labelSelector is allowed to match zero
+                                      ClusterTrustBundles.
+                                    type: boolean
+                                  path:
+                                    description: Relative path from the volume root
+                                      to write the bundle.
+                                    type: string
+                                  signerName:
+                                    description: |-
+                                      Select all ClusterTrustBundles that match this signer name.
+                                      Mutually-exclusive with name.  The contents of all selected
+                                      ClusterTrustBundles will be unified and deduplicated.
+                                    type: string
+                                required:
+                                - path
+                                type: object
+                              configMap:
+                                description: configMap information about the configMap
+                                  data to project
+                                properties:
+                                  items:
+                                    description: |-
+                                      items if unspecified, each key-value pair in the Data field of the referenced
+                                      ConfigMap will be projected into the volume as a file whose name is the
+                                      key and content is the value. If specified, the listed keys will be
+                                      projected into the specified paths, and unlisted keys will not be
+                                      present. If a key is specified which is not present in the ConfigMap,
+                                      the volume setup will error unless it is marked optional. Paths must be
+                                      relative and may not contain the '..' path or start with '..'.
+                                    items:
+                                      description: Maps a string key to a path within
+                                        a volume.
+                                      properties:
+                                        key:
+                                          description: key is the key to project.
+                                          type: string
+                                        mode:
+                                          description: |-
+                                            mode is Optional: mode bits used to set permissions on this file.
+                                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: |-
+                                            path is the relative path of the file to map the key to.
+                                            May not be an absolute path.
+                                            May not contain the path element '..'.
+                                            May not start with the string '..'.
+                                          type: string
+                                      required:
+                                      - key
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                  name:
+                                    default: ""
+                                    description: |-
+                                      Name of the referent.
+                                      This field is effectively required, but due to backwards compatibility is
+                                      allowed to be empty. Instances of this type with an empty value here are
+                                      almost certainly wrong.
+                                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                    type: string
+                                  optional:
+                                    description: optional specify whether the ConfigMap
+                                      or its keys must be defined
+                                    type: boolean
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              downwardAPI:
+                                description: downwardAPI information about the downwardAPI
+                                  data to project
+                                properties:
+                                  items:
+                                    description: Items is a list of DownwardAPIVolume
+                                      file
+                                    items:
+                                      description: DownwardAPIVolumeFile represents
+                                        information to create the file containing
+                                        the pod field
+                                      properties:
+                                        fieldRef:
+                                          description: 'Required: Selects a field
+                                            of the pod: only annotations, labels,
+                                            name, namespace and uid are supported.'
+                                          properties:
+                                            apiVersion:
+                                              description: Version of the schema the
+                                                FieldPath is written in terms of,
+                                                defaults to "v1".
+                                              type: string
+                                            fieldPath:
+                                              description: Path of the field to select
+                                                in the specified API version.
+                                              type: string
+                                          required:
+                                          - fieldPath
+                                          type: object
+                                          x-kubernetes-map-type: atomic
+                                        mode:
+                                          description: |-
+                                            Optional: mode bits used to set permissions on this file, must be an octal value
+                                            between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: 'Required: Path is  the relative
+                                            path name of the file to be created. Must
+                                            not be absolute or contain the ''..''
+                                            path. Must be utf-8 encoded. The first
+                                            item of the relative path must not start
+                                            with ''..'''
+                                          type: string
+                                        resourceFieldRef:
+                                          description: |-
+                                            Selects a resource of the container: only resources limits and requests
+                                            (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.
+                                          properties:
+                                            containerName:
+                                              description: 'Container name: required
+                                                for volumes, optional for env vars'
+                                              type: string
+                                            divisor:
+                                              anyOf:
+                                              - type: integer
+                                              - type: string
+                                              description: Specifies the output format
+                                                of the exposed resources, defaults
+                                                to "1"
+                                              pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                              x-kubernetes-int-or-string: true
+                                            resource:
+                                              description: 'Required: resource to
+                                                select'
+                                              type: string
+                                          required:
+                                          - resource
+                                          type: object
+                                          x-kubernetes-map-type: atomic
+                                      required:
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                type: object
+                              podCertificate:
+                                description: |-
+                                  Projects an auto-rotating credential bundle (private key and certificate
+                                  chain) that the pod can use either as a TLS client or server.
+
+                                  Kubelet generates a private key and uses it to send a
+                                  PodCertificateRequest to the named signer.  Once the signer approves the
+                                  request and issues a certificate chain, Kubelet writes the key and
+                                  certificate chain to the pod filesystem.  The pod does not start until
+                                  certificates have been issued for each podCertificate projected volume
+                                  source in its spec.
+
+                                  Kubelet will begin trying to rotate the certificate at the time indicated
+                                  by the signer using the PodCertificateRequest.Status.BeginRefreshAt
+                                  timestamp.
+
+                                  Kubelet can write a single file, indicated by the credentialBundlePath
+                                  field, or separate files, indicated by the keyPath and
+                                  certificateChainPath fields.
+
+                                  The credential bundle is a single file in PEM format.  The first PEM
+                                  entry is the private key (in PKCS#8 format), and the remaining PEM
+                                  entries are the certificate chain issued by the signer (typically,
+                                  signers will return their certificate chain in leaf-to-root order).
+
+                                  Prefer using the credential bundle format, since your application code
+                                  can read it atomically.  If you use keyPath and certificateChainPath,
+                                  your application must make two separate file reads. If these coincide
+                                  with a certificate rotation, it is possible that the private key and leaf
+                                  certificate you read may not correspond to each other.  Your application
+                                  will need to check for this condition, and re-read until they are
+                                  consistent.
+
+                                  The named signer controls chooses the format of the certificate it
+                                  issues; consult the signer implementation's documentation to learn how to
+                                  use the certificates it issues.
+                                properties:
+                                  certificateChainPath:
+                                    description: |-
+                                      Write the certificate chain at this path in the projected volume.
+
+                                      Most applications should use credentialBundlePath.  When using keyPath
+                                      and certificateChainPath, your application needs to check that the key
+                                      and leaf certificate are consistent, because it is possible to read the
+                                      files mid-rotation.
+                                    type: string
+                                  credentialBundlePath:
+                                    description: |-
+                                      Write the credential bundle at this path in the projected volume.
+
+                                      The credential bundle is a single file that contains multiple PEM blocks.
+                                      The first PEM block is a PRIVATE KEY block, containing a PKCS#8 private
+                                      key.
+
+                                      The remaining blocks are CERTIFICATE blocks, containing the issued
+                                      certificate chain from the signer (leaf and any intermediates).
+
+                                      Using credentialBundlePath lets your Pod's application code make a single
+                                      atomic read that retrieves a consistent key and certificate chain.  If you
+                                      project them to separate files, your application code will need to
+                                      additionally check that the leaf certificate was issued to the key.
+                                    type: string
+                                  keyPath:
+                                    description: |-
+                                      Write the key at this path in the projected volume.
+
+                                      Most applications should use credentialBundlePath.  When using keyPath
+                                      and certificateChainPath, your application needs to check that the key
+                                      and leaf certificate are consistent, because it is possible to read the
+                                      files mid-rotation.
+                                    type: string
+                                  keyType:
+                                    description: |-
+                                      The type of keypair Kubelet will generate for the pod.
+
+                                      Valid values are "RSA3072", "RSA4096", "ECDSAP256", "ECDSAP384",
+                                      "ECDSAP521", and "ED25519".
+                                    type: string
+                                  maxExpirationSeconds:
+                                    description: |-
+                                      maxExpirationSeconds is the maximum lifetime permitted for the
+                                      certificate.
+
+                                      Kubelet copies this value verbatim into the PodCertificateRequests it
+                                      generates for this projection.
+
+                                      If omitted, kube-apiserver will set it to 86400(24 hours). kube-apiserver
+                                      will reject values shorter than 3600 (1 hour).  The maximum allowable
+                                      value is 7862400 (91 days).
+
+                                      The signer implementation is then free to issue a certificate with any
+                                      lifetime *shorter* than MaxExpirationSeconds, but no shorter than 3600
+                                      seconds (1 hour).  This constraint is enforced by kube-apiserver.
+                                      `kubernetes.io` signers will never issue certificates with a lifetime
+                                      longer than 24 hours.
+                                    format: int32
+                                    type: integer
+                                  signerName:
+                                    description: Kubelet's generated CSRs will be
+                                      addressed to this signer.
+                                    type: string
+                                  userAnnotations:
+                                    additionalProperties:
+                                      type: string
+                                    description: |-
+                                      userAnnotations allow pod authors to pass additional information to
+                                      the signer implementation.  Kubernetes does not restrict or validate this
+                                      metadata in any way.
+
+                                      These values are copied verbatim into the `spec.unverifiedUserAnnotations` field of
+                                      the PodCertificateRequest objects that Kubelet creates.
+
+                                      Entries are subject to the same validation as object metadata annotations,
+                                      with the addition that all keys must be domain-prefixed. No restrictions
+                                      are placed on values, except an overall size limitation on the entire field.
+
+                                      Signers should document the keys and values they support. Signers should
+                                      deny requests that contain keys they do not recognize.
+                                    type: object
+                                required:
+                                - keyType
+                                - signerName
+                                type: object
+                              secret:
+                                description: secret information about the secret data
+                                  to project
+                                properties:
+                                  items:
+                                    description: |-
+                                      items if unspecified, each key-value pair in the Data field of the referenced
+                                      Secret will be projected into the volume as a file whose name is the
+                                      key and content is the value. If specified, the listed keys will be
+                                      projected into the specified paths, and unlisted keys will not be
+                                      present. If a key is specified which is not present in the Secret,
+                                      the volume setup will error unless it is marked optional. Paths must be
+                                      relative and may not contain the '..' path or start with '..'.
+                                    items:
+                                      description: Maps a string key to a path within
+                                        a volume.
+                                      properties:
+                                        key:
+                                          description: key is the key to project.
+                                          type: string
+                                        mode:
+                                          description: |-
+                                            mode is Optional: mode bits used to set permissions on this file.
+                                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: |-
+                                            path is the relative path of the file to map the key to.
+                                            May not be an absolute path.
+                                            May not contain the path element '..'.
+                                            May not start with the string '..'.
+                                          type: string
+                                      required:
+                                      - key
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                  name:
+                                    default: ""
+                                    description: |-
+                                      Name of the referent.
+                                      This field is effectively required, but due to backwards compatibility is
+                                      allowed to be empty. Instances of this type with an empty value here are
+                                      almost certainly wrong.
+                                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                    type: string
+                                  optional:
+                                    description: optional field specify whether the
+                                      Secret or its key must be defined
+                                    type: boolean
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              serviceAccountToken:
+                                description: serviceAccountToken is information about
+                                  the serviceAccountToken data to project
+                                properties:
+                                  audience:
+                                    description: |-
+                                      audience is the intended audience of the token. A recipient of a token
+                                      must identify itself with an identifier specified in the audience of the
+                                      token, and otherwise should reject the token. The audience defaults to the
+                                      identifier of the apiserver.
+                                    type: string
+                                  expirationSeconds:
+                                    description: |-
+                                      expirationSeconds is the requested duration of validity of the service
+                                      account token. As the token approaches expiration, the kubelet volume
+                                      plugin will proactively rotate the service account token. The kubelet will
+                                      start trying to rotate the token if the token is older than 80 percent of
+                                      its time to live or if the token is older than 24 hours.Defaults to 1 hour
+                                      and must be at least 10 minutes.
+                                    format: int64
+                                    type: integer
+                                  path:
+                                    description: |-
+                                      path is the path relative to the mount point of the file to project the
+                                      token into.
+                                    type: string
+                                required:
+                                - path
+                                type: object
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    quobyte:
+                      description: |-
+                        quobyte represents a Quobyte mount on the host that shares a pod's lifetime.
+                        Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported.
+                      properties:
+                        group:
+                          description: |-
+                            group to map volume access to
+                            Default is no group
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the Quobyte volume to be mounted with read-only permissions.
+                            Defaults to false.
+                          type: boolean
+                        registry:
+                          description: |-
+                            registry represents a single or multiple Quobyte Registry services
+                            specified as a string as host:port pair (multiple entries are separated with commas)
+                            which acts as the central registry for volumes
+                          type: string
+                        tenant:
+                          description: |-
+                            tenant owning the given Quobyte volume in the Backend
+                            Used with dynamically provisioned Quobyte volumes, value is set by the plugin
+                          type: string
+                        user:
+                          description: |-
+                            user to map volume access to
+                            Defaults to serivceaccount user
+                          type: string
+                        volume:
+                          description: volume is a string that references an already
+                            created Quobyte volume by name.
+                          type: string
+                      required:
+                      - registry
+                      - volume
+                      type: object
+                    rbd:
+                      description: |-
+                        rbd represents a Rados Block Device mount on the host that shares a pod's lifetime.
+                        Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd
+                          type: string
+                        image:
+                          description: |-
+                            image is the rados image name.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        keyring:
+                          default: /etc/ceph/keyring
+                          description: |-
+                            keyring is the path to key ring for RBDUser.
+                            Default is /etc/ceph/keyring.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        monitors:
+                          description: |-
+                            monitors is a collection of Ceph monitors.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        pool:
+                          default: rbd
+                          description: |-
+                            pool is the rados pool name.
+                            Default is rbd.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is name of the authentication secret for RBDUser. If provided
+                            overrides keyring.
+                            Default is nil.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        user:
+                          default: admin
+                          description: |-
+                            user is the rados user name.
+                            Default is admin.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                      required:
+                      - image
+                      - monitors
+                      type: object
+                    scaleIO:
+                      description: |-
+                        scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes.
+                        Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported.
+                      properties:
+                        fsType:
+                          default: xfs
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs".
+                            Default is "xfs".
+                          type: string
+                        gateway:
+                          description: gateway is the host address of the ScaleIO
+                            API Gateway.
+                          type: string
+                        protectionDomain:
+                          description: protectionDomain is the name of the ScaleIO
+                            Protection Domain for the configured storage.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef references to the secret for ScaleIO user and other
+                            sensitive information. If this is not provided, Login operation will fail.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        sslEnabled:
+                          description: sslEnabled Flag enable/disable SSL communication
+                            with Gateway, default false
+                          type: boolean
+                        storageMode:
+                          default: ThinProvisioned
+                          description: |-
+                            storageMode indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned.
+                            Default is ThinProvisioned.
+                          type: string
+                        storagePool:
+                          description: storagePool is the ScaleIO Storage Pool associated
+                            with the protection domain.
+                          type: string
+                        system:
+                          description: system is the name of the storage system as
+                            configured in ScaleIO.
+                          type: string
+                        volumeName:
+                          description: |-
+                            volumeName is the name of a volume already created in the ScaleIO system
+                            that is associated with this volume source.
+                          type: string
+                      required:
+                      - gateway
+                      - secretRef
+                      - system
+                      type: object
+                    secret:
+                      description: |-
+                        secret represents a secret that should populate this volume.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode is Optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values
+                            for mode bits. Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: |-
+                            items If unspecified, each key-value pair in the Data field of the referenced
+                            Secret will be projected into the volume as a file whose name is the
+                            key and content is the value. If specified, the listed keys will be
+                            projected into the specified paths, and unlisted keys will not be
+                            present. If a key is specified which is not present in the Secret,
+                            the volume setup will error unless it is marked optional. Paths must be
+                            relative and may not contain the '..' path or start with '..'.
+                          items:
+                            description: Maps a string key to a path within a volume.
+                            properties:
+                              key:
+                                description: key is the key to project.
+                                type: string
+                              mode:
+                                description: |-
+                                  mode is Optional: mode bits used to set permissions on this file.
+                                  Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: |-
+                                  path is the relative path of the file to map the key to.
+                                  May not be an absolute path.
+                                  May not contain the path element '..'.
+                                  May not start with the string '..'.
+                                type: string
+                            required:
+                            - key
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        optional:
+                          description: optional field specify whether the Secret or
+                            its keys must be defined
+                          type: boolean
+                        secretName:
+                          description: |-
+                            secretName is the name of the secret in the pod's namespace to use.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
+                          type: string
+                      type: object
+                    storageos:
+                      description: |-
+                        storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes.
+                        Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef specifies the secret to use for obtaining the StorageOS API
+                            credentials.  If not specified, default values will be attempted.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        volumeName:
+                          description: |-
+                            volumeName is the human-readable name of the StorageOS volume.  Volume
+                            names are only unique within a namespace.
+                          type: string
+                        volumeNamespace:
+                          description: |-
+                            volumeNamespace specifies the scope of the volume within StorageOS.  If no
+                            namespace is specified then the Pod's namespace will be used.  This allows the
+                            Kubernetes name scoping to be mirrored within StorageOS for tighter integration.
+                            Set VolumeName to any name to override the default behaviour.
+                            Set to "default" if you are not using namespaces within StorageOS.
+                            Namespaces that do not pre-exist within StorageOS will be created.
+                          type: string
+                      type: object
+                    vsphereVolume:
+                      description: |-
+                        vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine.
+                        Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type
+                        are redirected to the csi.vsphere.vmware.com CSI driver.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        storagePolicyID:
+                          description: storagePolicyID is the storage Policy Based
+                            Management (SPBM) profile ID associated with the StoragePolicyName.
+                          type: string
+                        storagePolicyName:
+                          description: storagePolicyName is the storage Policy Based
+                            Management (SPBM) profile name.
+                          type: string
+                        volumePath:
+                          description: volumePath is the path that identifies vSphere
+                            volume vmdk
+                          type: string
+                      required:
+                      - volumePath
+                      type: object
+                  required:
+                  - name
+                  type: object
+                type: array
+            required:
+            - l1
+            type: object
+          status:
+            description: status defines the observed state of CacheBlendEngine.
+            properties:
+              conditions:
+                description: conditions represent the current state of the CacheBlendEngine
+                  resource.
+                items:
+                  description: Condition contains details for one aspect of the current
+                    state of this API Resource.
+                  properties:
+                    lastTransitionTime:
+                      description: |-
+                        lastTransitionTime is the last time the condition transitioned from one status to another.
+                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
+                      format: date-time
+                      type: string
+                    message:
+                      description: |-
+                        message is a human readable message indicating details about the transition.
+                        This may be an empty string.
+                      maxLength: 32768
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
+                        with respect to the current state of the instance.
+                      format: int64
+                      minimum: 0
+                      type: integer
+                    reason:
+                      description: |-
+                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        Producers of specific condition types may define expected values and meanings for this field,
+                        and whether the values are considered a guaranteed API.
+                        The value should be a CamelCase string.
+                        This field may not be empty.
+                      maxLength: 1024
+                      minLength: 1
+                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      type: string
+                    status:
+                      description: status of the condition, one of True, False, Unknown.
+                      enum:
+                      - "True"
+                      - "False"
+                      - Unknown
+                      type: string
+                    type:
+                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
+                      maxLength: 316
+                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
+                      type: string
+                  required:
+                  - lastTransitionTime
+                  - message
+                  - reason
+                  - status
+                  - type
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - type
+                x-kubernetes-list-type: map
+              desiredInstances:
+                description: desiredInstances is the number of desired instances.
+                format: int32
+                type: integer
+              endpoints:
+                description: endpoints lists per-node connection info.
+                items:
+                  description: EndpointStatus represents a single LMCache instance
+                    endpoint.
+                  properties:
+                    hostIP:
+                      description: hostIP is the IP address of the host.
+                      type: string
+                    metricsPort:
+                      description: metricsPort is the Prometheus metrics port.
+                      format: int32
+                      type: integer
+                    nodeName:
+                      description: nodeName is the name of the node running this instance.
+                      type: string
+                    podName:
+                      description: podName is the name of the pod.
+                      type: string
+                    port:
+                      description: port is the server port.
+                      format: int32
+                      type: integer
+                    ready:
+                      description: ready indicates whether this instance is ready.
+                      type: boolean
+                  required:
+                  - hostIP
+                  - metricsPort
+                  - nodeName
+                  - podName
+                  - port
+                  - ready
+                  type: object
+                type: array
+              observedGeneration:
+                description: observedGeneration is the most recent generation observed.
+                format: int64
+                type: integer
+              phase:
+                description: phase is the overall phase of the CacheBlendEngine.
+                type: string
+              readyInstances:
+                description: readyInstances is the number of ready instances.
+                format: int32
+                type: integer
+            type: object
+        required:
+        - spec
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}
diff --git a/operator/config/crd/bases/lmcache.lmcache.ai_lmcachecoordinators.yaml b/operator/config/crd/bases/lmcache.lmcache.ai_lmcachecoordinators.yaml
new file mode 100644
index 0000000..11d392f
--- /dev/null
+++ b/operator/config/crd/bases/lmcache.lmcache.ai_lmcachecoordinators.yaml
@@ -0,0 +1,3481 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.20.1
+  name: lmcachecoordinators.lmcache.lmcache.ai
+spec:
+  group: lmcache.lmcache.ai
+  names:
+    kind: LMCacheCoordinator
+    listKind: LMCacheCoordinatorList
+    plural: lmcachecoordinators
+    shortNames:
+    - lmcc
+    singular: lmcachecoordinator
+  scope: Namespaced
+  versions:
+  - additionalPrinterColumns:
+    - jsonPath: .status.phase
+      name: Phase
+      type: string
+    - jsonPath: .status.readyReplicas
+      name: Ready
+      type: integer
+    - jsonPath: .status.replicas
+      name: Replicas
+      type: integer
+    - jsonPath: .status.endpoint
+      name: Endpoint
+      type: string
+    - jsonPath: .metadata.creationTimestamp
+      name: Age
+      type: date
+    name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: LMCacheCoordinator is the Schema for the lmcachecoordinators
+          API.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: spec defines the desired state of LMCacheCoordinator.
+            properties:
+              affinity:
+                description: affinity defines pod scheduling affinity rules.
+                properties:
+                  nodeAffinity:
+                    description: Describes node affinity scheduling rules for the
+                      pod.
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and adding
+                          "weight" to the sum if the node matches the corresponding matchExpressions; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: |-
+                            An empty preferred scheduling term matches all objects with implicit weight 0
+                            (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op).
+                          properties:
+                            preference:
+                              description: A node selector term, associated with the
+                                corresponding weight.
+                              properties:
+                                matchExpressions:
+                                  description: A list of node selector requirements
+                                    by node's labels.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchFields:
+                                  description: A list of node selector requirements
+                                    by node's fields.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            weight:
+                              description: Weight associated with matching the corresponding
+                                nodeSelectorTerm, in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - preference
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to an update), the system
+                          may or may not try to eventually evict the pod from its node.
+                        properties:
+                          nodeSelectorTerms:
+                            description: Required. A list of node selector terms.
+                              The terms are ORed.
+                            items:
+                              description: |-
+                                A null or empty node selector term matches no objects. The requirements of
+                                them are ANDed.
+                                The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.
+                              properties:
+                                matchExpressions:
+                                  description: A list of node selector requirements
+                                    by node's labels.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchFields:
+                                  description: A list of node selector requirements
+                                    by node's fields.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            type: array
+                            x-kubernetes-list-type: atomic
+                        required:
+                        - nodeSelectorTerms
+                        type: object
+                        x-kubernetes-map-type: atomic
+                    type: object
+                  podAffinity:
+                    description: Describes pod affinity scheduling rules (e.g. co-locate
+                      this pod in the same node, zone, etc. as some other pod(s)).
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and adding
+                          "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: The weights of all of the matched WeightedPodAffinityTerm
+                            fields are added per-node to find the most preferred node(s)
+                          properties:
+                            podAffinityTerm:
+                              description: Required. A pod affinity term, associated
+                                with the corresponding weight.
+                              properties:
+                                labelSelector:
+                                  description: |-
+                                    A label query over a set of resources, in this case pods.
+                                    If it's null, this PodAffinityTerm matches with no Pods.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                matchLabelKeys:
+                                  description: |-
+                                    MatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                    Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                mismatchLabelKeys:
+                                  description: |-
+                                    MismatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                    Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                namespaceSelector:
+                                  description: |-
+                                    A label query over the set of namespaces that the term applies to.
+                                    The term is applied to the union of the namespaces selected by this field
+                                    and the ones listed in the namespaces field.
+                                    null selector and null or empty namespaces list means "this pod's namespace".
+                                    An empty selector ({}) matches all namespaces.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                namespaces:
+                                  description: |-
+                                    namespaces specifies a static list of namespace names that the term applies to.
+                                    The term is applied to the union of the namespaces listed in this field
+                                    and the ones selected by namespaceSelector.
+                                    null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                topologyKey:
+                                  description: |-
+                                    This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                    the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                    whose value of the label with key topologyKey matches that of any node on which any of the
+                                    selected pods is running.
+                                    Empty topologyKey is not allowed.
+                                  type: string
+                              required:
+                              - topologyKey
+                              type: object
+                            weight:
+                              description: |-
+                                weight associated with matching the corresponding podAffinityTerm,
+                                in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - podAffinityTerm
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to a pod label update), the
+                          system may or may not try to eventually evict the pod from its node.
+                          When there are multiple elements, the lists of nodes corresponding to each
+                          podAffinityTerm are intersected, i.e. all terms must be satisfied.
+                        items:
+                          description: |-
+                            Defines a set of pods (namely those matching the labelSelector
+                            relative to the given namespace(s)) that this pod should be
+                            co-located (affinity) or not co-located (anti-affinity) with,
+                            where co-located is defined as running on a node whose value of
+                            the label with key <topologyKey> matches that of any node on which
+                            a pod of the set of pods is running
+                          properties:
+                            labelSelector:
+                              description: |-
+                                A label query over a set of resources, in this case pods.
+                                If it's null, this PodAffinityTerm matches with no Pods.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            matchLabelKeys:
+                              description: |-
+                                MatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            mismatchLabelKeys:
+                              description: |-
+                                MismatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            namespaceSelector:
+                              description: |-
+                                A label query over the set of namespaces that the term applies to.
+                                The term is applied to the union of the namespaces selected by this field
+                                and the ones listed in the namespaces field.
+                                null selector and null or empty namespaces list means "this pod's namespace".
+                                An empty selector ({}) matches all namespaces.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            namespaces:
+                              description: |-
+                                namespaces specifies a static list of namespace names that the term applies to.
+                                The term is applied to the union of the namespaces listed in this field
+                                and the ones selected by namespaceSelector.
+                                null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            topologyKey:
+                              description: |-
+                                This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                whose value of the label with key topologyKey matches that of any node on which any of the
+                                selected pods is running.
+                                Empty topologyKey is not allowed.
+                              type: string
+                          required:
+                          - topologyKey
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                    type: object
+                  podAntiAffinity:
+                    description: Describes pod anti-affinity scheduling rules (e.g.
+                      avoid putting this pod in the same node, zone, etc. as some
+                      other pod(s)).
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the anti-affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling anti-affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and subtracting
+                          "weight" from the sum if the node has pods which matches the corresponding podAffinityTerm; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: The weights of all of the matched WeightedPodAffinityTerm
+                            fields are added per-node to find the most preferred node(s)
+                          properties:
+                            podAffinityTerm:
+                              description: Required. A pod affinity term, associated
+                                with the corresponding weight.
+                              properties:
+                                labelSelector:
+                                  description: |-
+                                    A label query over a set of resources, in this case pods.
+                                    If it's null, this PodAffinityTerm matches with no Pods.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                matchLabelKeys:
+                                  description: |-
+                                    MatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                    Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                mismatchLabelKeys:
+                                  description: |-
+                                    MismatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                    Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                namespaceSelector:
+                                  description: |-
+                                    A label query over the set of namespaces that the term applies to.
+                                    The term is applied to the union of the namespaces selected by this field
+                                    and the ones listed in the namespaces field.
+                                    null selector and null or empty namespaces list means "this pod's namespace".
+                                    An empty selector ({}) matches all namespaces.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                namespaces:
+                                  description: |-
+                                    namespaces specifies a static list of namespace names that the term applies to.
+                                    The term is applied to the union of the namespaces listed in this field
+                                    and the ones selected by namespaceSelector.
+                                    null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                topologyKey:
+                                  description: |-
+                                    This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                    the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                    whose value of the label with key topologyKey matches that of any node on which any of the
+                                    selected pods is running.
+                                    Empty topologyKey is not allowed.
+                                  type: string
+                              required:
+                              - topologyKey
+                              type: object
+                            weight:
+                              description: |-
+                                weight associated with matching the corresponding podAffinityTerm,
+                                in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - podAffinityTerm
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the anti-affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the anti-affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to a pod label update), the
+                          system may or may not try to eventually evict the pod from its node.
+                          When there are multiple elements, the lists of nodes corresponding to each
+                          podAffinityTerm are intersected, i.e. all terms must be satisfied.
+                        items:
+                          description: |-
+                            Defines a set of pods (namely those matching the labelSelector
+                            relative to the given namespace(s)) that this pod should be
+                            co-located (affinity) or not co-located (anti-affinity) with,
+                            where co-located is defined as running on a node whose value of
+                            the label with key <topologyKey> matches that of any node on which
+                            a pod of the set of pods is running
+                          properties:
+                            labelSelector:
+                              description: |-
+                                A label query over a set of resources, in this case pods.
+                                If it's null, this PodAffinityTerm matches with no Pods.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            matchLabelKeys:
+                              description: |-
+                                MatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            mismatchLabelKeys:
+                              description: |-
+                                MismatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            namespaceSelector:
+                              description: |-
+                                A label query over the set of namespaces that the term applies to.
+                                The term is applied to the union of the namespaces selected by this field
+                                and the ones listed in the namespaces field.
+                                null selector and null or empty namespaces list means "this pod's namespace".
+                                An empty selector ({}) matches all namespaces.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            namespaces:
+                              description: |-
+                                namespaces specifies a static list of namespace names that the term applies to.
+                                The term is applied to the union of the namespaces listed in this field
+                                and the ones selected by namespaceSelector.
+                                null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            topologyKey:
+                              description: |-
+                                This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                whose value of the label with key topologyKey matches that of any node on which any of the
+                                selected pods is running.
+                                Empty topologyKey is not allowed.
+                              type: string
+                          required:
+                          - topologyKey
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                    type: object
+                type: object
+              blendChunkSize:
+                description: |-
+                  blendChunkSize is the tokens per chunk for the global CacheBlend directory
+                  (the match unit). It MUST equal the LMCache chunk size the blend servers
+                  use, so the coordinator chunks published/queried tokens the same way.
+                  When unset the coordinator image applies its own default (256); the
+                  operator only passes --blend-chunk-size when this is explicitly set, so it
+                  stays compatible with images whose CLI predates the flag.
+                format: int32
+                minimum: 1
+                type: integer
+              blendProbeStride:
+                description: |-
+                  blendProbeStride is the number of positions between CacheBlend match
+                  probes. With partial-fill reuse any offset is usable, so 1 (probe every
+                  offset) gives full recall; raise it only to trade recall for coordinator
+                  CPU. When unset the coordinator image applies its own default (1); the
+                  operator only passes --blend-probe-stride when this is explicitly set, so
+                  it stays compatible with images whose CLI predates the flag.
+                format: int32
+                minimum: 1
+                type: integer
+              env:
+                description: env defines additional environment variables.
+                items:
+                  description: EnvVar represents an environment variable present in
+                    a Container.
+                  properties:
+                    name:
+                      description: |-
+                        Name of the environment variable.
+                        May consist of any printable ASCII characters except '='.
+                      type: string
+                    value:
+                      description: |-
+                        Variable references $(VAR_NAME) are expanded
+                        using the previously defined environment variables in the container and
+                        any service environment variables. If a variable cannot be resolved,
+                        the reference in the input string will be unchanged. Double $$ are reduced
+                        to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.
+                        "$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
+                        Escaped references will never be expanded, regardless of whether the variable
+                        exists or not.
+                        Defaults to "".
+                      type: string
+                    valueFrom:
+                      description: Source for the environment variable's value. Cannot
+                        be used if value is not empty.
+                      properties:
+                        configMapKeyRef:
+                          description: Selects a key of a ConfigMap.
+                          properties:
+                            key:
+                              description: The key to select.
+                              type: string
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                            optional:
+                              description: Specify whether the ConfigMap or its key
+                                must be defined
+                              type: boolean
+                          required:
+                          - key
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        fieldRef:
+                          description: |-
+                            Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`,
+                            spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
+                          properties:
+                            apiVersion:
+                              description: Version of the schema the FieldPath is
+                                written in terms of, defaults to "v1".
+                              type: string
+                            fieldPath:
+                              description: Path of the field to select in the specified
+                                API version.
+                              type: string
+                          required:
+                          - fieldPath
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        fileKeyRef:
+                          description: |-
+                            FileKeyRef selects a key of the env file.
+                            Requires the EnvFiles feature gate to be enabled.
+                          properties:
+                            key:
+                              description: |-
+                                The key within the env file. An invalid key will prevent the pod from starting.
+                                The keys defined within a source may consist of any printable ASCII characters except '='.
+                                During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.
+                              type: string
+                            optional:
+                              default: false
+                              description: |-
+                                Specify whether the file or its key must be defined. If the file or key
+                                does not exist, then the env var is not published.
+                                If optional is set to true and the specified key does not exist,
+                                the environment variable will not be set in the Pod's containers.
+
+                                If optional is set to false and the specified key does not exist,
+                                an error will be returned during Pod creation.
+                              type: boolean
+                            path:
+                              description: |-
+                                The path within the volume from which to select the file.
+                                Must be relative and may not contain the '..' path or start with '..'.
+                              type: string
+                            volumeName:
+                              description: The name of the volume mount containing
+                                the env file.
+                              type: string
+                          required:
+                          - key
+                          - path
+                          - volumeName
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        resourceFieldRef:
+                          description: |-
+                            Selects a resource of the container: only resources limits and requests
+                            (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
+                          properties:
+                            containerName:
+                              description: 'Container name: required for volumes,
+                                optional for env vars'
+                              type: string
+                            divisor:
+                              anyOf:
+                              - type: integer
+                              - type: string
+                              description: Specifies the output format of the exposed
+                                resources, defaults to "1"
+                              pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                              x-kubernetes-int-or-string: true
+                            resource:
+                              description: 'Required: resource to select'
+                              type: string
+                          required:
+                          - resource
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        secretKeyRef:
+                          description: Selects a key of a secret in the pod's namespace
+                          properties:
+                            key:
+                              description: The key of the secret to select from.  Must
+                                be a valid secret key.
+                              type: string
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                            optional:
+                              description: Specify whether the Secret or its key must
+                                be defined
+                              type: boolean
+                          required:
+                          - key
+                          type: object
+                          x-kubernetes-map-type: atomic
+                      type: object
+                  required:
+                  - name
+                  type: object
+                type: array
+              evictionCheckInterval:
+                default: 5
+                description: |-
+                  evictionCheckInterval is the seconds between L2 eviction sweeps. 0 disables
+                  the loop.
+                type: number
+              evictionRatio:
+                default: 0.2
+                description: |-
+                  evictionRatio is the fraction of tracked keys (by count) to evict per
+                  cycle, in [0.0, 1.0].
+                type: number
+              extraArgs:
+                description: |-
+                  extraArgs are additional CLI flags appended to the coordinator command.
+                  They are appended last and can override any auto-generated flag.
+                items:
+                  type: string
+                type: array
+              healthCheckInterval:
+                default: 10
+                description: |-
+                  healthCheckInterval is the seconds between health-check sweeps. 0 disables
+                  the loop.
+                type: number
+              host:
+                default: 0.0.0.0
+                description: host is the address the coordinator's HTTP server binds
+                  to.
+                type: string
+              image:
+                description: |-
+                  image defines the container image to use. The coordinator runs the same
+                  lmcache binary as the engines, so it shares the default image.
+                properties:
+                  pullPolicy:
+                    default: IfNotPresent
+                    description: pullPolicy is the image pull policy.
+                    enum:
+                    - Always
+                    - Never
+                    - IfNotPresent
+                    type: string
+                  repository:
+                    default: lmcache/vllm-openai
+                    description: repository is the container image repository.
+                    type: string
+                  tag:
+                    default: latest
+                    description: tag is the container image tag.
+                    type: string
+                type: object
+              imagePullSecrets:
+                description: imagePullSecrets is a list of references to secrets for
+                  pulling the image.
+                items:
+                  description: |-
+                    LocalObjectReference contains enough information to let you locate the
+                    referenced object inside the same namespace.
+                  properties:
+                    name:
+                      default: ""
+                      description: |-
+                        Name of the referent.
+                        This field is effectively required, but due to backwards compatibility is
+                        allowed to be empty. Instances of this type with an empty value here are
+                        almost certainly wrong.
+                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      type: string
+                  type: object
+                  x-kubernetes-map-type: atomic
+                type: array
+              instanceTimeout:
+                default: 30
+                description: |-
+                  instanceTimeout is the seconds without a heartbeat after which an instance
+                  is evicted. Must be > 0.
+                type: number
+              logLevel:
+                default: INFO
+                description: logLevel is the log level for the coordinator process.
+                enum:
+                - DEBUG
+                - INFO
+                - WARNING
+                - ERROR
+                type: string
+              nodeSelector:
+                additionalProperties:
+                  type: string
+                description: nodeSelector constrains which nodes the coordinator runs
+                  on.
+                type: object
+              podAnnotations:
+                additionalProperties:
+                  type: string
+                description: podAnnotations are additional annotations added to the
+                  coordinator pod.
+                type: object
+              podLabels:
+                additionalProperties:
+                  type: string
+                description: podLabels are additional labels added to the coordinator
+                  pod.
+                type: object
+              port:
+                default: 9300
+                description: port is the port the coordinator's HTTP server binds
+                  to.
+                format: int32
+                maximum: 65535
+                minimum: 1
+                type: integer
+              priorityClassName:
+                description: priorityClassName is the priority class for the coordinator
+                  pod.
+                type: string
+              prometheus:
+                description: |-
+                  prometheus defines Prometheus monitoring configuration. The coordinator
+                  process does not yet expose a /metrics endpoint, so the ServiceMonitor is
+                  disabled by default; enabling it is only useful once metrics are added.
+                properties:
+                  enabled:
+                    default: true
+                    description: enabled controls whether Prometheus metrics are exposed.
+                    type: boolean
+                  port:
+                    default: 9090
+                    description: port is the Prometheus metrics port.
+                    format: int32
+                    type: integer
+                  serviceMonitor:
+                    description: serviceMonitor configures the Prometheus ServiceMonitor.
+                    properties:
+                      enabled:
+                        default: false
+                        description: enabled controls whether a ServiceMonitor CR
+                          is created.
+                        type: boolean
+                      interval:
+                        default: 30s
+                        description: interval is the Prometheus scrape interval.
+                        type: string
+                      labels:
+                        additionalProperties:
+                          type: string
+                        description: labels are additional labels added to the ServiceMonitor.
+                        type: object
+                    type: object
+                type: object
+              replicas:
+                default: 1
+                description: |-
+                  replicas is the number of coordinator pods. The coordinator's in-memory
+                  registry is per-process, so running more than one replica only makes sense
+                  behind a shared durable backend; the default of 1 fits the common case.
+                format: int32
+                minimum: 0
+                type: integer
+              resourceOverrides:
+                description: |-
+                  resourceOverrides allows overriding the coordinator pod's resource
+                  requirements.
+                properties:
+                  claims:
+                    description: |-
+                      Claims lists the names of resources, defined in spec.resourceClaims,
+                      that are used by this container.
+
+                      This field depends on the
+                      DynamicResourceAllocation feature gate.
+
+                      This field is immutable. It can only be set for containers.
+                    items:
+                      description: ResourceClaim references one entry in PodSpec.ResourceClaims.
+                      properties:
+                        name:
+                          description: |-
+                            Name must match the name of one entry in pod.spec.resourceClaims of
+                            the Pod where this field is used. It makes that resource available
+                            inside a container.
+                          type: string
+                        request:
+                          description: |-
+                            Request is the name chosen for a request in the referenced claim.
+                            If empty, everything from the claim is made available, otherwise
+                            only the result of this request.
+                          type: string
+                      required:
+                      - name
+                      type: object
+                    type: array
+                    x-kubernetes-list-map-keys:
+                    - name
+                    x-kubernetes-list-type: map
+                  limits:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Limits describes the maximum amount of compute resources allowed.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                  requests:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Requests describes the minimum amount of compute resources required.
+                      If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                      otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                type: object
+              serviceAccountName:
+                description: serviceAccountName is the name of the ServiceAccount
+                  to use.
+                type: string
+              tolerations:
+                description: tolerations defines pod tolerations.
+                items:
+                  description: |-
+                    The pod this Toleration is attached to tolerates any taint that matches
+                    the triple <key,value,effect> using the matching operator <operator>.
+                  properties:
+                    effect:
+                      description: |-
+                        Effect indicates the taint effect to match. Empty means match all taint effects.
+                        When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.
+                      type: string
+                    key:
+                      description: |-
+                        Key is the taint key that the toleration applies to. Empty means match all taint keys.
+                        If the key is empty, operator must be Exists; this combination means to match all values and all keys.
+                      type: string
+                    operator:
+                      description: |-
+                        Operator represents a key's relationship to the value.
+                        Valid operators are Exists, Equal, Lt, and Gt. Defaults to Equal.
+                        Exists is equivalent to wildcard for value, so that a pod can
+                        tolerate all taints of a particular category.
+                        Lt and Gt perform numeric comparisons (requires feature gate TaintTolerationComparisonOperators).
+                      type: string
+                    tolerationSeconds:
+                      description: |-
+                        TolerationSeconds represents the period of time the toleration (which must be
+                        of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default,
+                        it is not set, which means tolerate the taint forever (do not evict). Zero and
+                        negative values will be treated as 0 (evict immediately) by the system.
+                      format: int64
+                      type: integer
+                    value:
+                      description: |-
+                        Value is the taint value the toleration matches to.
+                        If the operator is Exists, the value should be empty, otherwise just a regular string.
+                      type: string
+                  type: object
+                type: array
+              triggerWatermark:
+                default: 1
+                description: |-
+                  triggerWatermark is the usage fraction of the quota that fires eviction,
+                  in (0.0, 1.0].
+                type: number
+              volumeMounts:
+                description: volumeMounts defines additional volume mounts.
+                items:
+                  description: VolumeMount describes a mounting of a Volume within
+                    a container.
+                  properties:
+                    mountPath:
+                      description: |-
+                        Path within the container at which the volume should be mounted.  Must
+                        not contain ':'.
+                      type: string
+                    mountPropagation:
+                      description: |-
+                        mountPropagation determines how mounts are propagated from the host
+                        to container and the other way around.
+                        When not set, MountPropagationNone is used.
+                        This field is beta in 1.10.
+                        When RecursiveReadOnly is set to IfPossible or to Enabled, MountPropagation must be None or unspecified
+                        (which defaults to None).
+                      type: string
+                    name:
+                      description: This must match the Name of a Volume.
+                      type: string
+                    readOnly:
+                      description: |-
+                        Mounted read-only if true, read-write otherwise (false or unspecified).
+                        Defaults to false.
+                      type: boolean
+                    recursiveReadOnly:
+                      description: |-
+                        RecursiveReadOnly specifies whether read-only mounts should be handled
+                        recursively.
+
+                        If ReadOnly is false, this field has no meaning and must be unspecified.
+
+                        If ReadOnly is true, and this field is set to Disabled, the mount is not made
+                        recursively read-only.  If this field is set to IfPossible, the mount is made
+                        recursively read-only, if it is supported by the container runtime.  If this
+                        field is set to Enabled, the mount is made recursively read-only if it is
+                        supported by the container runtime, otherwise the pod will not be started and
+                        an error will be generated to indicate the reason.
+
+                        If this field is set to IfPossible or Enabled, MountPropagation must be set to
+                        None (or be unspecified, which defaults to None).
+
+                        If this field is not specified, it is treated as an equivalent of Disabled.
+                      type: string
+                    subPath:
+                      description: |-
+                        Path within the volume from which the container's volume should be mounted.
+                        Defaults to "" (volume's root).
+                      type: string
+                    subPathExpr:
+                      description: |-
+                        Expanded path within the volume from which the container's volume should be mounted.
+                        Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment.
+                        Defaults to "" (volume's root).
+                        SubPathExpr and SubPath are mutually exclusive.
+                      type: string
+                  required:
+                  - mountPath
+                  - name
+                  type: object
+                type: array
+              volumes:
+                description: volumes defines additional volumes.
+                items:
+                  description: Volume represents a named volume in a pod that may
+                    be accessed by any container in the pod.
+                  properties:
+                    awsElasticBlockStore:
+                      description: |-
+                        awsElasticBlockStore represents an AWS Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree
+                        awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: string
+                        partition:
+                          description: |-
+                            partition is the partition in the volume that you want to mount.
+                            If omitted, the default is to mount by volume name.
+                            Examples: For volume /dev/sda1, you specify the partition as "1".
+                            Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty).
+                          format: int32
+                          type: integer
+                        readOnly:
+                          description: |-
+                            readOnly value true will force the readOnly setting in VolumeMounts.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: boolean
+                        volumeID:
+                          description: |-
+                            volumeID is unique ID of the persistent disk resource in AWS (Amazon EBS volume).
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    azureDisk:
+                      description: |-
+                        azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod.
+                        Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type
+                        are redirected to the disk.csi.azure.com CSI driver.
+                      properties:
+                        cachingMode:
+                          description: 'cachingMode is the Host Caching mode: None,
+                            Read Only, Read Write.'
+                          type: string
+                        diskName:
+                          description: diskName is the Name of the data disk in the
+                            blob storage
+                          type: string
+                        diskURI:
+                          description: diskURI is the URI of data disk in the blob
+                            storage
+                          type: string
+                        fsType:
+                          default: ext4
+                          description: |-
+                            fsType is Filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        kind:
+                          description: 'kind expected values are Shared: multiple
+                            blob disks per storage account  Dedicated: single blob
+                            disk per storage account  Managed: azure managed data
+                            disk (only in managed availability set). defaults to shared'
+                          type: string
+                        readOnly:
+                          default: false
+                          description: |-
+                            readOnly Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                      required:
+                      - diskName
+                      - diskURI
+                      type: object
+                    azureFile:
+                      description: |-
+                        azureFile represents an Azure File Service mount on the host and bind mount to the pod.
+                        Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type
+                        are redirected to the file.csi.azure.com CSI driver.
+                      properties:
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretName:
+                          description: secretName is the  name of secret that contains
+                            Azure Storage Account Name and Key
+                          type: string
+                        shareName:
+                          description: shareName is the azure share Name
+                          type: string
+                      required:
+                      - secretName
+                      - shareName
+                      type: object
+                    cephfs:
+                      description: |-
+                        cephFS represents a Ceph FS mount on the host that shares a pod's lifetime.
+                        Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported.
+                      properties:
+                        monitors:
+                          description: |-
+                            monitors is Required: Monitors is a collection of Ceph monitors
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        path:
+                          description: 'path is Optional: Used as the mounted root,
+                            rather than the full Ceph tree, default is /'
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: boolean
+                        secretFile:
+                          description: |-
+                            secretFile is Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: string
+                        secretRef:
+                          description: |-
+                            secretRef is Optional: SecretRef is reference to the authentication secret for User, default is empty.
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        user:
+                          description: |-
+                            user is optional: User is the rados user name, default is admin
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: string
+                      required:
+                      - monitors
+                      type: object
+                    cinder:
+                      description: |-
+                        cinder represents a cinder volume attached and mounted on kubelets host machine.
+                        Deprecated: Cinder is deprecated. All operations for the in-tree cinder type
+                        are redirected to the cinder.csi.openstack.org CSI driver.
+                        More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is optional: points to a secret object containing parameters used to connect
+                            to OpenStack.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        volumeID:
+                          description: |-
+                            volumeID used to identify the volume in cinder.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    configMap:
+                      description: configMap represents a configMap that should populate
+                        this volume
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode is optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: |-
+                            items if unspecified, each key-value pair in the Data field of the referenced
+                            ConfigMap will be projected into the volume as a file whose name is the
+                            key and content is the value. If specified, the listed keys will be
+                            projected into the specified paths, and unlisted keys will not be
+                            present. If a key is specified which is not present in the ConfigMap,
+                            the volume setup will error unless it is marked optional. Paths must be
+                            relative and may not contain the '..' path or start with '..'.
+                          items:
+                            description: Maps a string key to a path within a volume.
+                            properties:
+                              key:
+                                description: key is the key to project.
+                                type: string
+                              mode:
+                                description: |-
+                                  mode is Optional: mode bits used to set permissions on this file.
+                                  Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: |-
+                                  path is the relative path of the file to map the key to.
+                                  May not be an absolute path.
+                                  May not contain the path element '..'.
+                                  May not start with the string '..'.
+                                type: string
+                            required:
+                            - key
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        name:
+                          default: ""
+                          description: |-
+                            Name of the referent.
+                            This field is effectively required, but due to backwards compatibility is
+                            allowed to be empty. Instances of this type with an empty value here are
+                            almost certainly wrong.
+                            More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                          type: string
+                        optional:
+                          description: optional specify whether the ConfigMap or its
+                            keys must be defined
+                          type: boolean
+                      type: object
+                      x-kubernetes-map-type: atomic
+                    csi:
+                      description: csi (Container Storage Interface) represents ephemeral
+                        storage that is handled by certain external CSI drivers.
+                      properties:
+                        driver:
+                          description: |-
+                            driver is the name of the CSI driver that handles this volume.
+                            Consult with your admin for the correct name as registered in the cluster.
+                          type: string
+                        fsType:
+                          description: |-
+                            fsType to mount. Ex. "ext4", "xfs", "ntfs".
+                            If not provided, the empty value is passed to the associated CSI driver
+                            which will determine the default filesystem to apply.
+                          type: string
+                        nodePublishSecretRef:
+                          description: |-
+                            nodePublishSecretRef is a reference to the secret object containing
+                            sensitive information to pass to the CSI driver to complete the CSI
+                            NodePublishVolume and NodeUnpublishVolume calls.
+                            This field is optional, and  may be empty if no secret is required. If the
+                            secret object contains more than one secret, all secret references are passed.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        readOnly:
+                          description: |-
+                            readOnly specifies a read-only configuration for the volume.
+                            Defaults to false (read/write).
+                          type: boolean
+                        volumeAttributes:
+                          additionalProperties:
+                            type: string
+                          description: |-
+                            volumeAttributes stores driver-specific properties that are passed to the CSI
+                            driver. Consult your driver's documentation for supported values.
+                          type: object
+                      required:
+                      - driver
+                      type: object
+                    downwardAPI:
+                      description: downwardAPI represents downward API about the pod
+                        that should populate this volume
+                      properties:
+                        defaultMode:
+                          description: |-
+                            Optional: mode bits to use on created files by default. Must be a
+                            Optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: Items is a list of downward API volume file
+                          items:
+                            description: DownwardAPIVolumeFile represents information
+                              to create the file containing the pod field
+                            properties:
+                              fieldRef:
+                                description: 'Required: Selects a field of the pod:
+                                  only annotations, labels, name, namespace and uid
+                                  are supported.'
+                                properties:
+                                  apiVersion:
+                                    description: Version of the schema the FieldPath
+                                      is written in terms of, defaults to "v1".
+                                    type: string
+                                  fieldPath:
+                                    description: Path of the field to select in the
+                                      specified API version.
+                                    type: string
+                                required:
+                                - fieldPath
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              mode:
+                                description: |-
+                                  Optional: mode bits used to set permissions on this file, must be an octal value
+                                  between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: 'Required: Path is  the relative path
+                                  name of the file to be created. Must not be absolute
+                                  or contain the ''..'' path. Must be utf-8 encoded.
+                                  The first item of the relative path must not start
+                                  with ''..'''
+                                type: string
+                              resourceFieldRef:
+                                description: |-
+                                  Selects a resource of the container: only resources limits and requests
+                                  (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.
+                                properties:
+                                  containerName:
+                                    description: 'Container name: required for volumes,
+                                      optional for env vars'
+                                    type: string
+                                  divisor:
+                                    anyOf:
+                                    - type: integer
+                                    - type: string
+                                    description: Specifies the output format of the
+                                      exposed resources, defaults to "1"
+                                    pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                    x-kubernetes-int-or-string: true
+                                  resource:
+                                    description: 'Required: resource to select'
+                                    type: string
+                                required:
+                                - resource
+                                type: object
+                                x-kubernetes-map-type: atomic
+                            required:
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    emptyDir:
+                      description: |-
+                        emptyDir represents a temporary directory that shares a pod's lifetime.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                      properties:
+                        medium:
+                          description: |-
+                            medium represents what type of storage medium should back this directory.
+                            The default is "" which means to use the node's default medium.
+                            Must be an empty string (default) or Memory.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                          type: string
+                        sizeLimit:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          description: |-
+                            sizeLimit is the total amount of local storage required for this EmptyDir volume.
+                            The size limit is also applicable for memory medium.
+                            The maximum usage on memory medium EmptyDir would be the minimum value between
+                            the SizeLimit specified here and the sum of memory limits of all containers in a pod.
+                            The default is nil which means that the limit is undefined.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                          pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                          x-kubernetes-int-or-string: true
+                      type: object
+                    ephemeral:
+                      description: |-
+                        ephemeral represents a volume that is handled by a cluster storage driver.
+                        The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts,
+                        and deleted when the pod is removed.
+
+                        Use this if:
+                        a) the volume is only needed while the pod runs,
+                        b) features of normal volumes like restoring from snapshot or capacity
+                           tracking are needed,
+                        c) the storage driver is specified through a storage class, and
+                        d) the storage driver supports dynamic volume provisioning through
+                           a PersistentVolumeClaim (see EphemeralVolumeSource for more
+                           information on the connection between this volume type
+                           and PersistentVolumeClaim).
+
+                        Use PersistentVolumeClaim or one of the vendor-specific
+                        APIs for volumes that persist for longer than the lifecycle
+                        of an individual pod.
+
+                        Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to
+                        be used that way - see the documentation of the driver for
+                        more information.
+
+                        A pod can use both types of ephemeral volumes and
+                        persistent volumes at the same time.
+                      properties:
+                        volumeClaimTemplate:
+                          description: |-
+                            Will be used to create a stand-alone PVC to provision the volume.
+                            The pod in which this EphemeralVolumeSource is embedded will be the
+                            owner of the PVC, i.e. the PVC will be deleted together with the
+                            pod.  The name of the PVC will be `<pod name>-<volume name>` where
+                            `<volume name>` is the name from the `PodSpec.Volumes` array
+                            entry. Pod validation will reject the pod if the concatenated name
+                            is not valid for a PVC (for example, too long).
+
+                            An existing PVC with that name that is not owned by the pod
+                            will *not* be used for the pod to avoid using an unrelated
+                            volume by mistake. Starting the pod is then blocked until
+                            the unrelated PVC is removed. If such a pre-created PVC is
+                            meant to be used by the pod, the PVC has to updated with an
+                            owner reference to the pod once the pod exists. Normally
+                            this should not be necessary, but it may be useful when
+                            manually reconstructing a broken cluster.
+
+                            This field is read-only and no changes will be made by Kubernetes
+                            to the PVC after it has been created.
+
+                            Required, must not be nil.
+                          properties:
+                            metadata:
+                              description: |-
+                                May contain labels and annotations that will be copied into the PVC
+                                when creating it. No other fields are allowed and will be rejected during
+                                validation.
+                              type: object
+                            spec:
+                              description: |-
+                                The specification for the PersistentVolumeClaim. The entire content is
+                                copied unchanged into the PVC that gets created from this
+                                template. The same fields as in a PersistentVolumeClaim
+                                are also valid here.
+                              properties:
+                                accessModes:
+                                  description: |-
+                                    accessModes contains the desired access modes the volume should have.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                dataSource:
+                                  description: |-
+                                    dataSource field can be used to specify either:
+                                    * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot)
+                                    * An existing PVC (PersistentVolumeClaim)
+                                    If the provisioner or an external controller can support the specified data source,
+                                    it will create a new volume based on the contents of the specified data source.
+                                    When the AnyVolumeDataSource feature gate is enabled, dataSource contents will be copied to dataSourceRef,
+                                    and dataSourceRef contents will be copied to dataSource when dataSourceRef.namespace is not specified.
+                                    If the namespace is specified, then dataSourceRef will not be copied to dataSource.
+                                  properties:
+                                    apiGroup:
+                                      description: |-
+                                        APIGroup is the group for the resource being referenced.
+                                        If APIGroup is not specified, the specified Kind must be in the core API group.
+                                        For any other third-party types, APIGroup is required.
+                                      type: string
+                                    kind:
+                                      description: Kind is the type of resource being
+                                        referenced
+                                      type: string
+                                    name:
+                                      description: Name is the name of resource being
+                                        referenced
+                                      type: string
+                                  required:
+                                  - kind
+                                  - name
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                dataSourceRef:
+                                  description: |-
+                                    dataSourceRef specifies the object from which to populate the volume with data, if a non-empty
+                                    volume is desired. This may be any object from a non-empty API group (non
+                                    core object) or a PersistentVolumeClaim object.
+                                    When this field is specified, volume binding will only succeed if the type of
+                                    the specified object matches some installed volume populator or dynamic
+                                    provisioner.
+                                    This field will replace the functionality of the dataSource field and as such
+                                    if both fields are non-empty, they must have the same value. For backwards
+                                    compatibility, when namespace isn't specified in dataSourceRef,
+                                    both fields (dataSource and dataSourceRef) will be set to the same
+                                    value automatically if one of them is empty and the other is non-empty.
+                                    When namespace is specified in dataSourceRef,
+                                    dataSource isn't set to the same value and must be empty.
+                                    There are three important differences between dataSource and dataSourceRef:
+                                    * While dataSource only allows two specific types of objects, dataSourceRef
+                                      allows any non-core object, as well as PersistentVolumeClaim objects.
+                                    * While dataSource ignores disallowed values (dropping them), dataSourceRef
+                                      preserves all values, and generates an error if a disallowed value is
+                                      specified.
+                                    * While dataSource only allows local objects, dataSourceRef allows objects
+                                      in any namespaces.
+                                    (Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled.
+                                    (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled.
+                                  properties:
+                                    apiGroup:
+                                      description: |-
+                                        APIGroup is the group for the resource being referenced.
+                                        If APIGroup is not specified, the specified Kind must be in the core API group.
+                                        For any other third-party types, APIGroup is required.
+                                      type: string
+                                    kind:
+                                      description: Kind is the type of resource being
+                                        referenced
+                                      type: string
+                                    name:
+                                      description: Name is the name of resource being
+                                        referenced
+                                      type: string
+                                    namespace:
+                                      description: |-
+                                        Namespace is the namespace of resource being referenced
+                                        Note that when a namespace is specified, a gateway.networking.k8s.io/ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details.
+                                        (Alpha) This field requires the CrossNamespaceVolumeDataSource feature gate to be enabled.
+                                      type: string
+                                  required:
+                                  - kind
+                                  - name
+                                  type: object
+                                resources:
+                                  description: |-
+                                    resources represents the minimum resources the volume should have.
+                                    Users are allowed to specify resource requirements
+                                    that are lower than previous value but must still be higher than capacity recorded in the
+                                    status field of the claim.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources
+                                  properties:
+                                    limits:
+                                      additionalProperties:
+                                        anyOf:
+                                        - type: integer
+                                        - type: string
+                                        pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                        x-kubernetes-int-or-string: true
+                                      description: |-
+                                        Limits describes the maximum amount of compute resources allowed.
+                                        More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                                      type: object
+                                    requests:
+                                      additionalProperties:
+                                        anyOf:
+                                        - type: integer
+                                        - type: string
+                                        pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                        x-kubernetes-int-or-string: true
+                                      description: |-
+                                        Requests describes the minimum amount of compute resources required.
+                                        If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                                        otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                                        More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                                      type: object
+                                  type: object
+                                selector:
+                                  description: selector is a label query over volumes
+                                    to consider for binding.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                storageClassName:
+                                  description: |-
+                                    storageClassName is the name of the StorageClass required by the claim.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1
+                                  type: string
+                                volumeAttributesClassName:
+                                  description: |-
+                                    volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim.
+                                    If specified, the CSI driver will create or update the volume with the attributes defined
+                                    in the corresponding VolumeAttributesClass. This has a different purpose than storageClassName,
+                                    it can be changed after the claim is created. An empty string or nil value indicates that no
+                                    VolumeAttributesClass will be applied to the claim. If the claim enters an Infeasible error state,
+                                    this field can be reset to its previous value (including nil) to cancel the modification.
+                                    If the resource referred to by volumeAttributesClass does not exist, this PersistentVolumeClaim will be
+                                    set to a Pending state, as reflected by the modifyVolumeStatus field, until such as a resource
+                                    exists.
+                                    More info: https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/
+                                  type: string
+                                volumeMode:
+                                  description: |-
+                                    volumeMode defines what type of volume is required by the claim.
+                                    Value of Filesystem is implied when not included in claim spec.
+                                  type: string
+                                volumeName:
+                                  description: volumeName is the binding reference
+                                    to the PersistentVolume backing this claim.
+                                  type: string
+                              type: object
+                          required:
+                          - spec
+                          type: object
+                      type: object
+                    fc:
+                      description: fc represents a Fibre Channel resource that is
+                        attached to a kubelet's host machine and then exposed to the
+                        pod.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        lun:
+                          description: 'lun is Optional: FC target lun number'
+                          format: int32
+                          type: integer
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        targetWWNs:
+                          description: 'targetWWNs is Optional: FC target worldwide
+                            names (WWNs)'
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        wwids:
+                          description: |-
+                            wwids Optional: FC volume world wide identifiers (wwids)
+                            Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously.
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    flexVolume:
+                      description: |-
+                        flexVolume represents a generic volume resource that is
+                        provisioned/attached using an exec based plugin.
+                        Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead.
+                      properties:
+                        driver:
+                          description: driver is the name of the driver to use for
+                            this volume.
+                          type: string
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script.
+                          type: string
+                        options:
+                          additionalProperties:
+                            type: string
+                          description: 'options is Optional: this field holds extra
+                            command options if any.'
+                          type: object
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is Optional: secretRef is reference to the secret object containing
+                            sensitive information to pass to the plugin scripts. This may be
+                            empty if no secret object is specified. If the secret object
+                            contains more than one secret, all secrets are passed to the plugin
+                            scripts.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                      required:
+                      - driver
+                      type: object
+                    flocker:
+                      description: |-
+                        flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running.
+                        Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported.
+                      properties:
+                        datasetName:
+                          description: |-
+                            datasetName is Name of the dataset stored as metadata -> name on the dataset for Flocker
+                            should be considered as deprecated
+                          type: string
+                        datasetUUID:
+                          description: datasetUUID is the UUID of the dataset. This
+                            is unique identifier of a Flocker dataset
+                          type: string
+                      type: object
+                    gcePersistentDisk:
+                      description: |-
+                        gcePersistentDisk represents a GCE Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree
+                        gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: string
+                        partition:
+                          description: |-
+                            partition is the partition in the volume that you want to mount.
+                            If omitted, the default is to mount by volume name.
+                            Examples: For volume /dev/sda1, you specify the partition as "1".
+                            Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty).
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          format: int32
+                          type: integer
+                        pdName:
+                          description: |-
+                            pdName is unique name of the PD resource in GCE. Used to identify the disk in GCE.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: boolean
+                      required:
+                      - pdName
+                      type: object
+                    gitRepo:
+                      description: |-
+                        gitRepo represents a git repository at a particular revision.
+                        Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an
+                        EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir
+                        into the Pod's container.
+                      properties:
+                        directory:
+                          description: |-
+                            directory is the target directory name.
+                            Must not contain or start with '..'.  If '.' is supplied, the volume directory will be the
+                            git repository.  Otherwise, if specified, the volume will contain the git repository in
+                            the subdirectory with the given name.
+                          type: string
+                        repository:
+                          description: repository is the URL
+                          type: string
+                        revision:
+                          description: revision is the commit hash for the specified
+                            revision.
+                          type: string
+                      required:
+                      - repository
+                      type: object
+                    glusterfs:
+                      description: |-
+                        glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime.
+                        Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported.
+                      properties:
+                        endpoints:
+                          description: endpoints is the endpoint name that details
+                            Glusterfs topology.
+                          type: string
+                        path:
+                          description: |-
+                            path is the Glusterfs volume path.
+                            More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the Glusterfs volume to be mounted with read-only permissions.
+                            Defaults to false.
+                            More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod
+                          type: boolean
+                      required:
+                      - endpoints
+                      - path
+                      type: object
+                    hostPath:
+                      description: |-
+                        hostPath represents a pre-existing file or directory on the host
+                        machine that is directly exposed to the container. This is generally
+                        used for system agents or other privileged things that are allowed
+                        to see the host machine. Most containers will NOT need this.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                      properties:
+                        path:
+                          description: |-
+                            path of the directory on the host.
+                            If the path is a symlink, it will follow the link to the real path.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                          type: string
+                        type:
+                          description: |-
+                            type for HostPath Volume
+                            Defaults to ""
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                          type: string
+                      required:
+                      - path
+                      type: object
+                    image:
+                      description: |-
+                        image represents an OCI object (a container image or artifact) pulled and mounted on the kubelet's host machine.
+                        The volume is resolved at pod startup depending on which PullPolicy value is provided:
+
+                        - Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
+                        - Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
+                        - IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
+
+                        The volume gets re-resolved if the pod gets deleted and recreated, which means that new remote content will become available on pod recreation.
+                        A failure to resolve or pull the image during pod startup will block containers from starting and may add significant latency. Failures will be retried using normal volume backoff and will be reported on the pod reason and message.
+                        The types of objects that may be mounted by this volume are defined by the container runtime implementation on a host machine and at minimum must include all valid types supported by the container image field.
+                        The OCI object gets mounted in a single directory (spec.containers[*].volumeMounts.mountPath) by merging the manifest layers in the same way as for container images.
+                        The volume will be mounted read-only (ro) and non-executable files (noexec).
+                        Sub path mounts for containers are not supported (spec.containers[*].volumeMounts.subpath) before 1.33.
+                        The field spec.securityContext.fsGroupChangePolicy has no effect on this volume type.
+                      properties:
+                        pullPolicy:
+                          description: |-
+                            Policy for pulling OCI objects. Possible values are:
+                            Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
+                            Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
+                            IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
+                            Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
+                          type: string
+                        reference:
+                          description: |-
+                            Required: Image or artifact reference to be used.
+                            Behaves in the same way as pod.spec.containers[*].image.
+                            Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
+                            More info: https://kubernetes.io/docs/concepts/containers/images
+                            This field is optional to allow higher level config management to default or override
+                            container images in workload controllers like Deployments and StatefulSets.
+                          type: string
+                      type: object
+                    iscsi:
+                      description: |-
+                        iscsi represents an ISCSI Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes/#iscsi
+                      properties:
+                        chapAuthDiscovery:
+                          description: chapAuthDiscovery defines whether support iSCSI
+                            Discovery CHAP authentication
+                          type: boolean
+                        chapAuthSession:
+                          description: chapAuthSession defines whether support iSCSI
+                            Session CHAP authentication
+                          type: boolean
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi
+                          type: string
+                        initiatorName:
+                          description: |-
+                            initiatorName is the custom iSCSI Initiator Name.
+                            If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface
+                            <target portal>:<volume name> will be created for the connection.
+                          type: string
+                        iqn:
+                          description: iqn is the target iSCSI Qualified Name.
+                          type: string
+                        iscsiInterface:
+                          default: default
+                          description: |-
+                            iscsiInterface is the interface Name that uses an iSCSI transport.
+                            Defaults to 'default' (tcp).
+                          type: string
+                        lun:
+                          description: lun represents iSCSI Target Lun number.
+                          format: int32
+                          type: integer
+                        portals:
+                          description: |-
+                            portals is the iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port
+                            is other than default (typically TCP ports 860 and 3260).
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                          type: boolean
+                        secretRef:
+                          description: secretRef is the CHAP Secret for iSCSI target
+                            and initiator authentication
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        targetPortal:
+                          description: |-
+                            targetPortal is iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port
+                            is other than default (typically TCP ports 860 and 3260).
+                          type: string
+                      required:
+                      - iqn
+                      - lun
+                      - targetPortal
+                      type: object
+                    name:
+                      description: |-
+                        name of the volume.
+                        Must be a DNS_LABEL and unique within the pod.
+                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      type: string
+                    nfs:
+                      description: |-
+                        nfs represents an NFS mount on the host that shares a pod's lifetime
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                      properties:
+                        path:
+                          description: |-
+                            path that is exported by the NFS server.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the NFS export to be mounted with read-only permissions.
+                            Defaults to false.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: boolean
+                        server:
+                          description: |-
+                            server is the hostname or IP address of the NFS server.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: string
+                      required:
+                      - path
+                      - server
+                      type: object
+                    persistentVolumeClaim:
+                      description: |-
+                        persistentVolumeClaimVolumeSource represents a reference to a
+                        PersistentVolumeClaim in the same namespace.
+                        More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
+                      properties:
+                        claimName:
+                          description: |-
+                            claimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume.
+                            More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly Will force the ReadOnly setting in VolumeMounts.
+                            Default false.
+                          type: boolean
+                      required:
+                      - claimName
+                      type: object
+                    photonPersistentDisk:
+                      description: |-
+                        photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine.
+                        Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        pdID:
+                          description: pdID is the ID that identifies Photon Controller
+                            persistent disk
+                          type: string
+                      required:
+                      - pdID
+                      type: object
+                    portworxVolume:
+                      description: |-
+                        portworxVolume represents a portworx volume attached and mounted on kubelets host machine.
+                        Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type
+                        are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate
+                        is on.
+                      properties:
+                        fsType:
+                          description: |-
+                            fSType represents the filesystem type to mount
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        volumeID:
+                          description: volumeID uniquely identifies a Portworx volume
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    projected:
+                      description: projected items for all in one resources secrets,
+                        configmaps, and downward API
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode are the mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        sources:
+                          description: |-
+                            sources is the list of volume projections. Each entry in this list
+                            handles one source.
+                          items:
+                            description: |-
+                              Projection that may be projected along with other supported volume types.
+                              Exactly one of these fields must be set.
+                            properties:
+                              clusterTrustBundle:
+                                description: |-
+                                  ClusterTrustBundle allows a pod to access the `.spec.trustBundle` field
+                                  of ClusterTrustBundle objects in an auto-updating file.
+
+                                  Alpha, gated by the ClusterTrustBundleProjection feature gate.
+
+                                  ClusterTrustBundle objects can either be selected by name, or by the
+                                  combination of signer name and a label selector.
+
+                                  Kubelet performs aggressive normalization of the PEM contents written
+                                  into the pod filesystem.  Esoteric PEM features such as inter-block
+                                  comments and block headers are stripped.  Certificates are deduplicated.
+                                  The ordering of certificates within the file is arbitrary, and Kubelet
+                                  may change the order over time.
+                                properties:
+                                  labelSelector:
+                                    description: |-
+                                      Select all ClusterTrustBundles that match this label selector.  Only has
+                                      effect if signerName is set.  Mutually-exclusive with name.  If unset,
+                                      interpreted as "match nothing".  If set but empty, interpreted as "match
+                                      everything".
+                                    properties:
+                                      matchExpressions:
+                                        description: matchExpressions is a list of
+                                          label selector requirements. The requirements
+                                          are ANDed.
+                                        items:
+                                          description: |-
+                                            A label selector requirement is a selector that contains values, a key, and an operator that
+                                            relates the key and values.
+                                          properties:
+                                            key:
+                                              description: key is the label key that
+                                                the selector applies to.
+                                              type: string
+                                            operator:
+                                              description: |-
+                                                operator represents a key's relationship to a set of values.
+                                                Valid operators are In, NotIn, Exists and DoesNotExist.
+                                              type: string
+                                            values:
+                                              description: |-
+                                                values is an array of string values. If the operator is In or NotIn,
+                                                the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                                the values array must be empty. This array is replaced during a strategic
+                                                merge patch.
+                                              items:
+                                                type: string
+                                              type: array
+                                              x-kubernetes-list-type: atomic
+                                          required:
+                                          - key
+                                          - operator
+                                          type: object
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                      matchLabels:
+                                        additionalProperties:
+                                          type: string
+                                        description: |-
+                                          matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                          map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                          operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                        type: object
+                                    type: object
+                                    x-kubernetes-map-type: atomic
+                                  name:
+                                    description: |-
+                                      Select a single ClusterTrustBundle by object name.  Mutually-exclusive
+                                      with signerName and labelSelector.
+                                    type: string
+                                  optional:
+                                    description: |-
+                                      If true, don't block pod startup if the referenced ClusterTrustBundle(s)
+                                      aren't available.  If using name, then the named ClusterTrustBundle is
+                                      allowed not to exist.  If using signerName, then the combination of
+                                      signerName and labelSelector is allowed to match zero
+                                      ClusterTrustBundles.
+                                    type: boolean
+                                  path:
+                                    description: Relative path from the volume root
+                                      to write the bundle.
+                                    type: string
+                                  signerName:
+                                    description: |-
+                                      Select all ClusterTrustBundles that match this signer name.
+                                      Mutually-exclusive with name.  The contents of all selected
+                                      ClusterTrustBundles will be unified and deduplicated.
+                                    type: string
+                                required:
+                                - path
+                                type: object
+                              configMap:
+                                description: configMap information about the configMap
+                                  data to project
+                                properties:
+                                  items:
+                                    description: |-
+                                      items if unspecified, each key-value pair in the Data field of the referenced
+                                      ConfigMap will be projected into the volume as a file whose name is the
+                                      key and content is the value. If specified, the listed keys will be
+                                      projected into the specified paths, and unlisted keys will not be
+                                      present. If a key is specified which is not present in the ConfigMap,
+                                      the volume setup will error unless it is marked optional. Paths must be
+                                      relative and may not contain the '..' path or start with '..'.
+                                    items:
+                                      description: Maps a string key to a path within
+                                        a volume.
+                                      properties:
+                                        key:
+                                          description: key is the key to project.
+                                          type: string
+                                        mode:
+                                          description: |-
+                                            mode is Optional: mode bits used to set permissions on this file.
+                                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: |-
+                                            path is the relative path of the file to map the key to.
+                                            May not be an absolute path.
+                                            May not contain the path element '..'.
+                                            May not start with the string '..'.
+                                          type: string
+                                      required:
+                                      - key
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                  name:
+                                    default: ""
+                                    description: |-
+                                      Name of the referent.
+                                      This field is effectively required, but due to backwards compatibility is
+                                      allowed to be empty. Instances of this type with an empty value here are
+                                      almost certainly wrong.
+                                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                    type: string
+                                  optional:
+                                    description: optional specify whether the ConfigMap
+                                      or its keys must be defined
+                                    type: boolean
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              downwardAPI:
+                                description: downwardAPI information about the downwardAPI
+                                  data to project
+                                properties:
+                                  items:
+                                    description: Items is a list of DownwardAPIVolume
+                                      file
+                                    items:
+                                      description: DownwardAPIVolumeFile represents
+                                        information to create the file containing
+                                        the pod field
+                                      properties:
+                                        fieldRef:
+                                          description: 'Required: Selects a field
+                                            of the pod: only annotations, labels,
+                                            name, namespace and uid are supported.'
+                                          properties:
+                                            apiVersion:
+                                              description: Version of the schema the
+                                                FieldPath is written in terms of,
+                                                defaults to "v1".
+                                              type: string
+                                            fieldPath:
+                                              description: Path of the field to select
+                                                in the specified API version.
+                                              type: string
+                                          required:
+                                          - fieldPath
+                                          type: object
+                                          x-kubernetes-map-type: atomic
+                                        mode:
+                                          description: |-
+                                            Optional: mode bits used to set permissions on this file, must be an octal value
+                                            between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: 'Required: Path is  the relative
+                                            path name of the file to be created. Must
+                                            not be absolute or contain the ''..''
+                                            path. Must be utf-8 encoded. The first
+                                            item of the relative path must not start
+                                            with ''..'''
+                                          type: string
+                                        resourceFieldRef:
+                                          description: |-
+                                            Selects a resource of the container: only resources limits and requests
+                                            (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.
+                                          properties:
+                                            containerName:
+                                              description: 'Container name: required
+                                                for volumes, optional for env vars'
+                                              type: string
+                                            divisor:
+                                              anyOf:
+                                              - type: integer
+                                              - type: string
+                                              description: Specifies the output format
+                                                of the exposed resources, defaults
+                                                to "1"
+                                              pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                              x-kubernetes-int-or-string: true
+                                            resource:
+                                              description: 'Required: resource to
+                                                select'
+                                              type: string
+                                          required:
+                                          - resource
+                                          type: object
+                                          x-kubernetes-map-type: atomic
+                                      required:
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                type: object
+                              podCertificate:
+                                description: |-
+                                  Projects an auto-rotating credential bundle (private key and certificate
+                                  chain) that the pod can use either as a TLS client or server.
+
+                                  Kubelet generates a private key and uses it to send a
+                                  PodCertificateRequest to the named signer.  Once the signer approves the
+                                  request and issues a certificate chain, Kubelet writes the key and
+                                  certificate chain to the pod filesystem.  The pod does not start until
+                                  certificates have been issued for each podCertificate projected volume
+                                  source in its spec.
+
+                                  Kubelet will begin trying to rotate the certificate at the time indicated
+                                  by the signer using the PodCertificateRequest.Status.BeginRefreshAt
+                                  timestamp.
+
+                                  Kubelet can write a single file, indicated by the credentialBundlePath
+                                  field, or separate files, indicated by the keyPath and
+                                  certificateChainPath fields.
+
+                                  The credential bundle is a single file in PEM format.  The first PEM
+                                  entry is the private key (in PKCS#8 format), and the remaining PEM
+                                  entries are the certificate chain issued by the signer (typically,
+                                  signers will return their certificate chain in leaf-to-root order).
+
+                                  Prefer using the credential bundle format, since your application code
+                                  can read it atomically.  If you use keyPath and certificateChainPath,
+                                  your application must make two separate file reads. If these coincide
+                                  with a certificate rotation, it is possible that the private key and leaf
+                                  certificate you read may not correspond to each other.  Your application
+                                  will need to check for this condition, and re-read until they are
+                                  consistent.
+
+                                  The named signer controls chooses the format of the certificate it
+                                  issues; consult the signer implementation's documentation to learn how to
+                                  use the certificates it issues.
+                                properties:
+                                  certificateChainPath:
+                                    description: |-
+                                      Write the certificate chain at this path in the projected volume.
+
+                                      Most applications should use credentialBundlePath.  When using keyPath
+                                      and certificateChainPath, your application needs to check that the key
+                                      and leaf certificate are consistent, because it is possible to read the
+                                      files mid-rotation.
+                                    type: string
+                                  credentialBundlePath:
+                                    description: |-
+                                      Write the credential bundle at this path in the projected volume.
+
+                                      The credential bundle is a single file that contains multiple PEM blocks.
+                                      The first PEM block is a PRIVATE KEY block, containing a PKCS#8 private
+                                      key.
+
+                                      The remaining blocks are CERTIFICATE blocks, containing the issued
+                                      certificate chain from the signer (leaf and any intermediates).
+
+                                      Using credentialBundlePath lets your Pod's application code make a single
+                                      atomic read that retrieves a consistent key and certificate chain.  If you
+                                      project them to separate files, your application code will need to
+                                      additionally check that the leaf certificate was issued to the key.
+                                    type: string
+                                  keyPath:
+                                    description: |-
+                                      Write the key at this path in the projected volume.
+
+                                      Most applications should use credentialBundlePath.  When using keyPath
+                                      and certificateChainPath, your application needs to check that the key
+                                      and leaf certificate are consistent, because it is possible to read the
+                                      files mid-rotation.
+                                    type: string
+                                  keyType:
+                                    description: |-
+                                      The type of keypair Kubelet will generate for the pod.
+
+                                      Valid values are "RSA3072", "RSA4096", "ECDSAP256", "ECDSAP384",
+                                      "ECDSAP521", and "ED25519".
+                                    type: string
+                                  maxExpirationSeconds:
+                                    description: |-
+                                      maxExpirationSeconds is the maximum lifetime permitted for the
+                                      certificate.
+
+                                      Kubelet copies this value verbatim into the PodCertificateRequests it
+                                      generates for this projection.
+
+                                      If omitted, kube-apiserver will set it to 86400(24 hours). kube-apiserver
+                                      will reject values shorter than 3600 (1 hour).  The maximum allowable
+                                      value is 7862400 (91 days).
+
+                                      The signer implementation is then free to issue a certificate with any
+                                      lifetime *shorter* than MaxExpirationSeconds, but no shorter than 3600
+                                      seconds (1 hour).  This constraint is enforced by kube-apiserver.
+                                      `kubernetes.io` signers will never issue certificates with a lifetime
+                                      longer than 24 hours.
+                                    format: int32
+                                    type: integer
+                                  signerName:
+                                    description: Kubelet's generated CSRs will be
+                                      addressed to this signer.
+                                    type: string
+                                  userAnnotations:
+                                    additionalProperties:
+                                      type: string
+                                    description: |-
+                                      userAnnotations allow pod authors to pass additional information to
+                                      the signer implementation.  Kubernetes does not restrict or validate this
+                                      metadata in any way.
+
+                                      These values are copied verbatim into the `spec.unverifiedUserAnnotations` field of
+                                      the PodCertificateRequest objects that Kubelet creates.
+
+                                      Entries are subject to the same validation as object metadata annotations,
+                                      with the addition that all keys must be domain-prefixed. No restrictions
+                                      are placed on values, except an overall size limitation on the entire field.
+
+                                      Signers should document the keys and values they support. Signers should
+                                      deny requests that contain keys they do not recognize.
+                                    type: object
+                                required:
+                                - keyType
+                                - signerName
+                                type: object
+                              secret:
+                                description: secret information about the secret data
+                                  to project
+                                properties:
+                                  items:
+                                    description: |-
+                                      items if unspecified, each key-value pair in the Data field of the referenced
+                                      Secret will be projected into the volume as a file whose name is the
+                                      key and content is the value. If specified, the listed keys will be
+                                      projected into the specified paths, and unlisted keys will not be
+                                      present. If a key is specified which is not present in the Secret,
+                                      the volume setup will error unless it is marked optional. Paths must be
+                                      relative and may not contain the '..' path or start with '..'.
+                                    items:
+                                      description: Maps a string key to a path within
+                                        a volume.
+                                      properties:
+                                        key:
+                                          description: key is the key to project.
+                                          type: string
+                                        mode:
+                                          description: |-
+                                            mode is Optional: mode bits used to set permissions on this file.
+                                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: |-
+                                            path is the relative path of the file to map the key to.
+                                            May not be an absolute path.
+                                            May not contain the path element '..'.
+                                            May not start with the string '..'.
+                                          type: string
+                                      required:
+                                      - key
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                  name:
+                                    default: ""
+                                    description: |-
+                                      Name of the referent.
+                                      This field is effectively required, but due to backwards compatibility is
+                                      allowed to be empty. Instances of this type with an empty value here are
+                                      almost certainly wrong.
+                                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                    type: string
+                                  optional:
+                                    description: optional field specify whether the
+                                      Secret or its key must be defined
+                                    type: boolean
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              serviceAccountToken:
+                                description: serviceAccountToken is information about
+                                  the serviceAccountToken data to project
+                                properties:
+                                  audience:
+                                    description: |-
+                                      audience is the intended audience of the token. A recipient of a token
+                                      must identify itself with an identifier specified in the audience of the
+                                      token, and otherwise should reject the token. The audience defaults to the
+                                      identifier of the apiserver.
+                                    type: string
+                                  expirationSeconds:
+                                    description: |-
+                                      expirationSeconds is the requested duration of validity of the service
+                                      account token. As the token approaches expiration, the kubelet volume
+                                      plugin will proactively rotate the service account token. The kubelet will
+                                      start trying to rotate the token if the token is older than 80 percent of
+                                      its time to live or if the token is older than 24 hours.Defaults to 1 hour
+                                      and must be at least 10 minutes.
+                                    format: int64
+                                    type: integer
+                                  path:
+                                    description: |-
+                                      path is the path relative to the mount point of the file to project the
+                                      token into.
+                                    type: string
+                                required:
+                                - path
+                                type: object
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    quobyte:
+                      description: |-
+                        quobyte represents a Quobyte mount on the host that shares a pod's lifetime.
+                        Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported.
+                      properties:
+                        group:
+                          description: |-
+                            group to map volume access to
+                            Default is no group
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the Quobyte volume to be mounted with read-only permissions.
+                            Defaults to false.
+                          type: boolean
+                        registry:
+                          description: |-
+                            registry represents a single or multiple Quobyte Registry services
+                            specified as a string as host:port pair (multiple entries are separated with commas)
+                            which acts as the central registry for volumes
+                          type: string
+                        tenant:
+                          description: |-
+                            tenant owning the given Quobyte volume in the Backend
+                            Used with dynamically provisioned Quobyte volumes, value is set by the plugin
+                          type: string
+                        user:
+                          description: |-
+                            user to map volume access to
+                            Defaults to serivceaccount user
+                          type: string
+                        volume:
+                          description: volume is a string that references an already
+                            created Quobyte volume by name.
+                          type: string
+                      required:
+                      - registry
+                      - volume
+                      type: object
+                    rbd:
+                      description: |-
+                        rbd represents a Rados Block Device mount on the host that shares a pod's lifetime.
+                        Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd
+                          type: string
+                        image:
+                          description: |-
+                            image is the rados image name.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        keyring:
+                          default: /etc/ceph/keyring
+                          description: |-
+                            keyring is the path to key ring for RBDUser.
+                            Default is /etc/ceph/keyring.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        monitors:
+                          description: |-
+                            monitors is a collection of Ceph monitors.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        pool:
+                          default: rbd
+                          description: |-
+                            pool is the rados pool name.
+                            Default is rbd.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is name of the authentication secret for RBDUser. If provided
+                            overrides keyring.
+                            Default is nil.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        user:
+                          default: admin
+                          description: |-
+                            user is the rados user name.
+                            Default is admin.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                      required:
+                      - image
+                      - monitors
+                      type: object
+                    scaleIO:
+                      description: |-
+                        scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes.
+                        Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported.
+                      properties:
+                        fsType:
+                          default: xfs
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs".
+                            Default is "xfs".
+                          type: string
+                        gateway:
+                          description: gateway is the host address of the ScaleIO
+                            API Gateway.
+                          type: string
+                        protectionDomain:
+                          description: protectionDomain is the name of the ScaleIO
+                            Protection Domain for the configured storage.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef references to the secret for ScaleIO user and other
+                            sensitive information. If this is not provided, Login operation will fail.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        sslEnabled:
+                          description: sslEnabled Flag enable/disable SSL communication
+                            with Gateway, default false
+                          type: boolean
+                        storageMode:
+                          default: ThinProvisioned
+                          description: |-
+                            storageMode indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned.
+                            Default is ThinProvisioned.
+                          type: string
+                        storagePool:
+                          description: storagePool is the ScaleIO Storage Pool associated
+                            with the protection domain.
+                          type: string
+                        system:
+                          description: system is the name of the storage system as
+                            configured in ScaleIO.
+                          type: string
+                        volumeName:
+                          description: |-
+                            volumeName is the name of a volume already created in the ScaleIO system
+                            that is associated with this volume source.
+                          type: string
+                      required:
+                      - gateway
+                      - secretRef
+                      - system
+                      type: object
+                    secret:
+                      description: |-
+                        secret represents a secret that should populate this volume.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode is Optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values
+                            for mode bits. Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: |-
+                            items If unspecified, each key-value pair in the Data field of the referenced
+                            Secret will be projected into the volume as a file whose name is the
+                            key and content is the value. If specified, the listed keys will be
+                            projected into the specified paths, and unlisted keys will not be
+                            present. If a key is specified which is not present in the Secret,
+                            the volume setup will error unless it is marked optional. Paths must be
+                            relative and may not contain the '..' path or start with '..'.
+                          items:
+                            description: Maps a string key to a path within a volume.
+                            properties:
+                              key:
+                                description: key is the key to project.
+                                type: string
+                              mode:
+                                description: |-
+                                  mode is Optional: mode bits used to set permissions on this file.
+                                  Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: |-
+                                  path is the relative path of the file to map the key to.
+                                  May not be an absolute path.
+                                  May not contain the path element '..'.
+                                  May not start with the string '..'.
+                                type: string
+                            required:
+                            - key
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        optional:
+                          description: optional field specify whether the Secret or
+                            its keys must be defined
+                          type: boolean
+                        secretName:
+                          description: |-
+                            secretName is the name of the secret in the pod's namespace to use.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
+                          type: string
+                      type: object
+                    storageos:
+                      description: |-
+                        storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes.
+                        Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef specifies the secret to use for obtaining the StorageOS API
+                            credentials.  If not specified, default values will be attempted.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        volumeName:
+                          description: |-
+                            volumeName is the human-readable name of the StorageOS volume.  Volume
+                            names are only unique within a namespace.
+                          type: string
+                        volumeNamespace:
+                          description: |-
+                            volumeNamespace specifies the scope of the volume within StorageOS.  If no
+                            namespace is specified then the Pod's namespace will be used.  This allows the
+                            Kubernetes name scoping to be mirrored within StorageOS for tighter integration.
+                            Set VolumeName to any name to override the default behaviour.
+                            Set to "default" if you are not using namespaces within StorageOS.
+                            Namespaces that do not pre-exist within StorageOS will be created.
+                          type: string
+                      type: object
+                    vsphereVolume:
+                      description: |-
+                        vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine.
+                        Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type
+                        are redirected to the csi.vsphere.vmware.com CSI driver.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        storagePolicyID:
+                          description: storagePolicyID is the storage Policy Based
+                            Management (SPBM) profile ID associated with the StoragePolicyName.
+                          type: string
+                        storagePolicyName:
+                          description: storagePolicyName is the storage Policy Based
+                            Management (SPBM) profile name.
+                          type: string
+                        volumePath:
+                          description: volumePath is the path that identifies vSphere
+                            volume vmdk
+                          type: string
+                      required:
+                      - volumePath
+                      type: object
+                  required:
+                  - name
+                  type: object
+                type: array
+            type: object
+          status:
+            description: status defines the observed state of LMCacheCoordinator.
+            properties:
+              conditions:
+                description: conditions represent the current state of the LMCacheCoordinator
+                  resource.
+                items:
+                  description: Condition contains details for one aspect of the current
+                    state of this API Resource.
+                  properties:
+                    lastTransitionTime:
+                      description: |-
+                        lastTransitionTime is the last time the condition transitioned from one status to another.
+                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
+                      format: date-time
+                      type: string
+                    message:
+                      description: |-
+                        message is a human readable message indicating details about the transition.
+                        This may be an empty string.
+                      maxLength: 32768
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
+                        with respect to the current state of the instance.
+                      format: int64
+                      minimum: 0
+                      type: integer
+                    reason:
+                      description: |-
+                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        Producers of specific condition types may define expected values and meanings for this field,
+                        and whether the values are considered a guaranteed API.
+                        The value should be a CamelCase string.
+                        This field may not be empty.
+                      maxLength: 1024
+                      minLength: 1
+                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      type: string
+                    status:
+                      description: status of the condition, one of True, False, Unknown.
+                      enum:
+                      - "True"
+                      - "False"
+                      - Unknown
+                      type: string
+                    type:
+                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
+                      maxLength: 316
+                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
+                      type: string
+                  required:
+                  - lastTransitionTime
+                  - message
+                  - reason
+                  - status
+                  - type
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - type
+                x-kubernetes-list-type: map
+              endpoint:
+                description: |-
+                  endpoint is the in-cluster URL other components use to reach the
+                  coordinator, e.g. http://<name>.<namespace>.svc:9300.
+                type: string
+              observedGeneration:
+                description: observedGeneration is the most recent generation observed.
+                format: int64
+                type: integer
+              phase:
+                description: phase is the overall phase of the LMCacheCoordinator.
+                type: string
+              readyReplicas:
+                description: readyReplicas is the number of ready coordinator pods.
+                format: int32
+                type: integer
+              replicas:
+                description: replicas is the number of desired coordinator pods.
+                format: int32
+                type: integer
+            type: object
+        required:
+        - spec
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}
diff --git a/operator/config/crd/bases/lmcache.lmcache.ai_lmcacheengines.yaml b/operator/config/crd/bases/lmcache.lmcache.ai_lmcacheengines.yaml
new file mode 100644
index 0000000..6d60333
--- /dev/null
+++ b/operator/config/crd/bases/lmcache.lmcache.ai_lmcacheengines.yaml
@@ -0,0 +1,3754 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.20.1
+  name: lmcacheengines.lmcache.lmcache.ai
+spec:
+  group: lmcache.lmcache.ai
+  names:
+    kind: LMCacheEngine
+    listKind: LMCacheEngineList
+    plural: lmcacheengines
+    shortNames:
+    - lmc
+    singular: lmcacheengine
+  scope: Namespaced
+  versions:
+  - additionalPrinterColumns:
+    - jsonPath: .status.phase
+      name: Phase
+      type: string
+    - jsonPath: .status.readyInstances
+      name: Ready
+      type: integer
+    - jsonPath: .status.desiredInstances
+      name: Desired
+      type: integer
+    - jsonPath: .metadata.creationTimestamp
+      name: Age
+      type: date
+    name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: LMCacheEngine is the Schema for the lmcacheengines API.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: spec defines the desired state of LMCacheEngine.
+            properties:
+              affinity:
+                description: affinity defines pod scheduling affinity rules.
+                properties:
+                  nodeAffinity:
+                    description: Describes node affinity scheduling rules for the
+                      pod.
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and adding
+                          "weight" to the sum if the node matches the corresponding matchExpressions; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: |-
+                            An empty preferred scheduling term matches all objects with implicit weight 0
+                            (i.e. it's a no-op). A null preferred scheduling term matches no objects (i.e. is also a no-op).
+                          properties:
+                            preference:
+                              description: A node selector term, associated with the
+                                corresponding weight.
+                              properties:
+                                matchExpressions:
+                                  description: A list of node selector requirements
+                                    by node's labels.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchFields:
+                                  description: A list of node selector requirements
+                                    by node's fields.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            weight:
+                              description: Weight associated with matching the corresponding
+                                nodeSelectorTerm, in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - preference
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to an update), the system
+                          may or may not try to eventually evict the pod from its node.
+                        properties:
+                          nodeSelectorTerms:
+                            description: Required. A list of node selector terms.
+                              The terms are ORed.
+                            items:
+                              description: |-
+                                A null or empty node selector term matches no objects. The requirements of
+                                them are ANDed.
+                                The TopologySelectorTerm type implements a subset of the NodeSelectorTerm.
+                              properties:
+                                matchExpressions:
+                                  description: A list of node selector requirements
+                                    by node's labels.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchFields:
+                                  description: A list of node selector requirements
+                                    by node's fields.
+                                  items:
+                                    description: |-
+                                      A node selector requirement is a selector that contains values, a key, and an operator
+                                      that relates the key and values.
+                                    properties:
+                                      key:
+                                        description: The label key that the selector
+                                          applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          Represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists, DoesNotExist. Gt, and Lt.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          An array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. If the operator is Gt or Lt, the values
+                                          array must have a single element, which will be interpreted as an integer.
+                                          This array is replaced during a strategic merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            type: array
+                            x-kubernetes-list-type: atomic
+                        required:
+                        - nodeSelectorTerms
+                        type: object
+                        x-kubernetes-map-type: atomic
+                    type: object
+                  podAffinity:
+                    description: Describes pod affinity scheduling rules (e.g. co-locate
+                      this pod in the same node, zone, etc. as some other pod(s)).
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and adding
+                          "weight" to the sum if the node has pods which matches the corresponding podAffinityTerm; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: The weights of all of the matched WeightedPodAffinityTerm
+                            fields are added per-node to find the most preferred node(s)
+                          properties:
+                            podAffinityTerm:
+                              description: Required. A pod affinity term, associated
+                                with the corresponding weight.
+                              properties:
+                                labelSelector:
+                                  description: |-
+                                    A label query over a set of resources, in this case pods.
+                                    If it's null, this PodAffinityTerm matches with no Pods.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                matchLabelKeys:
+                                  description: |-
+                                    MatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                    Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                mismatchLabelKeys:
+                                  description: |-
+                                    MismatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                    Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                namespaceSelector:
+                                  description: |-
+                                    A label query over the set of namespaces that the term applies to.
+                                    The term is applied to the union of the namespaces selected by this field
+                                    and the ones listed in the namespaces field.
+                                    null selector and null or empty namespaces list means "this pod's namespace".
+                                    An empty selector ({}) matches all namespaces.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                namespaces:
+                                  description: |-
+                                    namespaces specifies a static list of namespace names that the term applies to.
+                                    The term is applied to the union of the namespaces listed in this field
+                                    and the ones selected by namespaceSelector.
+                                    null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                topologyKey:
+                                  description: |-
+                                    This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                    the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                    whose value of the label with key topologyKey matches that of any node on which any of the
+                                    selected pods is running.
+                                    Empty topologyKey is not allowed.
+                                  type: string
+                              required:
+                              - topologyKey
+                              type: object
+                            weight:
+                              description: |-
+                                weight associated with matching the corresponding podAffinityTerm,
+                                in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - podAffinityTerm
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to a pod label update), the
+                          system may or may not try to eventually evict the pod from its node.
+                          When there are multiple elements, the lists of nodes corresponding to each
+                          podAffinityTerm are intersected, i.e. all terms must be satisfied.
+                        items:
+                          description: |-
+                            Defines a set of pods (namely those matching the labelSelector
+                            relative to the given namespace(s)) that this pod should be
+                            co-located (affinity) or not co-located (anti-affinity) with,
+                            where co-located is defined as running on a node whose value of
+                            the label with key <topologyKey> matches that of any node on which
+                            a pod of the set of pods is running
+                          properties:
+                            labelSelector:
+                              description: |-
+                                A label query over a set of resources, in this case pods.
+                                If it's null, this PodAffinityTerm matches with no Pods.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            matchLabelKeys:
+                              description: |-
+                                MatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            mismatchLabelKeys:
+                              description: |-
+                                MismatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            namespaceSelector:
+                              description: |-
+                                A label query over the set of namespaces that the term applies to.
+                                The term is applied to the union of the namespaces selected by this field
+                                and the ones listed in the namespaces field.
+                                null selector and null or empty namespaces list means "this pod's namespace".
+                                An empty selector ({}) matches all namespaces.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            namespaces:
+                              description: |-
+                                namespaces specifies a static list of namespace names that the term applies to.
+                                The term is applied to the union of the namespaces listed in this field
+                                and the ones selected by namespaceSelector.
+                                null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            topologyKey:
+                              description: |-
+                                This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                whose value of the label with key topologyKey matches that of any node on which any of the
+                                selected pods is running.
+                                Empty topologyKey is not allowed.
+                              type: string
+                          required:
+                          - topologyKey
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                    type: object
+                  podAntiAffinity:
+                    description: Describes pod anti-affinity scheduling rules (e.g.
+                      avoid putting this pod in the same node, zone, etc. as some
+                      other pod(s)).
+                    properties:
+                      preferredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          The scheduler will prefer to schedule pods to nodes that satisfy
+                          the anti-affinity expressions specified by this field, but it may choose
+                          a node that violates one or more of the expressions. The node that is
+                          most preferred is the one with the greatest sum of weights, i.e.
+                          for each node that meets all of the scheduling requirements (resource
+                          request, requiredDuringScheduling anti-affinity expressions, etc.),
+                          compute a sum by iterating through the elements of this field and subtracting
+                          "weight" from the sum if the node has pods which matches the corresponding podAffinityTerm; the
+                          node(s) with the highest sum are the most preferred.
+                        items:
+                          description: The weights of all of the matched WeightedPodAffinityTerm
+                            fields are added per-node to find the most preferred node(s)
+                          properties:
+                            podAffinityTerm:
+                              description: Required. A pod affinity term, associated
+                                with the corresponding weight.
+                              properties:
+                                labelSelector:
+                                  description: |-
+                                    A label query over a set of resources, in this case pods.
+                                    If it's null, this PodAffinityTerm matches with no Pods.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                matchLabelKeys:
+                                  description: |-
+                                    MatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                    Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                mismatchLabelKeys:
+                                  description: |-
+                                    MismatchLabelKeys is a set of pod label keys to select which pods will
+                                    be taken into consideration. The keys are used to lookup values from the
+                                    incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                    to select the group of existing pods which pods will be taken into consideration
+                                    for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                    pod labels will be ignored. The default value is empty.
+                                    The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                    Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                namespaceSelector:
+                                  description: |-
+                                    A label query over the set of namespaces that the term applies to.
+                                    The term is applied to the union of the namespaces selected by this field
+                                    and the ones listed in the namespaces field.
+                                    null selector and null or empty namespaces list means "this pod's namespace".
+                                    An empty selector ({}) matches all namespaces.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                namespaces:
+                                  description: |-
+                                    namespaces specifies a static list of namespace names that the term applies to.
+                                    The term is applied to the union of the namespaces listed in this field
+                                    and the ones selected by namespaceSelector.
+                                    null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                topologyKey:
+                                  description: |-
+                                    This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                    the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                    whose value of the label with key topologyKey matches that of any node on which any of the
+                                    selected pods is running.
+                                    Empty topologyKey is not allowed.
+                                  type: string
+                              required:
+                              - topologyKey
+                              type: object
+                            weight:
+                              description: |-
+                                weight associated with matching the corresponding podAffinityTerm,
+                                in the range 1-100.
+                              format: int32
+                              type: integer
+                          required:
+                          - podAffinityTerm
+                          - weight
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                      requiredDuringSchedulingIgnoredDuringExecution:
+                        description: |-
+                          If the anti-affinity requirements specified by this field are not met at
+                          scheduling time, the pod will not be scheduled onto the node.
+                          If the anti-affinity requirements specified by this field cease to be met
+                          at some point during pod execution (e.g. due to a pod label update), the
+                          system may or may not try to eventually evict the pod from its node.
+                          When there are multiple elements, the lists of nodes corresponding to each
+                          podAffinityTerm are intersected, i.e. all terms must be satisfied.
+                        items:
+                          description: |-
+                            Defines a set of pods (namely those matching the labelSelector
+                            relative to the given namespace(s)) that this pod should be
+                            co-located (affinity) or not co-located (anti-affinity) with,
+                            where co-located is defined as running on a node whose value of
+                            the label with key <topologyKey> matches that of any node on which
+                            a pod of the set of pods is running
+                          properties:
+                            labelSelector:
+                              description: |-
+                                A label query over a set of resources, in this case pods.
+                                If it's null, this PodAffinityTerm matches with no Pods.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            matchLabelKeys:
+                              description: |-
+                                MatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key in (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both matchLabelKeys and labelSelector.
+                                Also, matchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            mismatchLabelKeys:
+                              description: |-
+                                MismatchLabelKeys is a set of pod label keys to select which pods will
+                                be taken into consideration. The keys are used to lookup values from the
+                                incoming pod labels, those key-value labels are merged with `labelSelector` as `key notin (value)`
+                                to select the group of existing pods which pods will be taken into consideration
+                                for the incoming pod's pod (anti) affinity. Keys that don't exist in the incoming
+                                pod labels will be ignored. The default value is empty.
+                                The same key is forbidden to exist in both mismatchLabelKeys and labelSelector.
+                                Also, mismatchLabelKeys cannot be set when labelSelector isn't set.
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            namespaceSelector:
+                              description: |-
+                                A label query over the set of namespaces that the term applies to.
+                                The term is applied to the union of the namespaces selected by this field
+                                and the ones listed in the namespaces field.
+                                null selector and null or empty namespaces list means "this pod's namespace".
+                                An empty selector ({}) matches all namespaces.
+                              properties:
+                                matchExpressions:
+                                  description: matchExpressions is a list of label
+                                    selector requirements. The requirements are ANDed.
+                                  items:
+                                    description: |-
+                                      A label selector requirement is a selector that contains values, a key, and an operator that
+                                      relates the key and values.
+                                    properties:
+                                      key:
+                                        description: key is the label key that the
+                                          selector applies to.
+                                        type: string
+                                      operator:
+                                        description: |-
+                                          operator represents a key's relationship to a set of values.
+                                          Valid operators are In, NotIn, Exists and DoesNotExist.
+                                        type: string
+                                      values:
+                                        description: |-
+                                          values is an array of string values. If the operator is In or NotIn,
+                                          the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                          the values array must be empty. This array is replaced during a strategic
+                                          merge patch.
+                                        items:
+                                          type: string
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                    required:
+                                    - key
+                                    - operator
+                                    type: object
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                matchLabels:
+                                  additionalProperties:
+                                    type: string
+                                  description: |-
+                                    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                    map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                    operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                  type: object
+                              type: object
+                              x-kubernetes-map-type: atomic
+                            namespaces:
+                              description: |-
+                                namespaces specifies a static list of namespace names that the term applies to.
+                                The term is applied to the union of the namespaces listed in this field
+                                and the ones selected by namespaceSelector.
+                                null or empty namespaces list and null namespaceSelector means "this pod's namespace".
+                              items:
+                                type: string
+                              type: array
+                              x-kubernetes-list-type: atomic
+                            topologyKey:
+                              description: |-
+                                This pod should be co-located (affinity) or not co-located (anti-affinity) with the pods matching
+                                the labelSelector in the specified namespaces, where co-located is defined as running on a node
+                                whose value of the label with key topologyKey matches that of any node on which any of the
+                                selected pods is running.
+                                Empty topologyKey is not allowed.
+                              type: string
+                          required:
+                          - topologyKey
+                          type: object
+                        type: array
+                        x-kubernetes-list-type: atomic
+                    type: object
+                type: object
+              coordinator:
+                description: |-
+                  coordinator configures registration with an MP coordinator. When unset,
+                  the server does not register with any coordinator.
+                properties:
+                  advertiseIP:
+                    description: |-
+                      advertiseIP is the IP the coordinator should reach this server at.
+
+                      DO NOT SET THIS IN ALMOST EVERY CASE. When unset, the server's pod IP is
+                      injected automatically via the downward API, which is the correct value
+                      for normal in-cluster deployments. Only set this if you know exactly what
+                      you are doing -- e.g. the coordinator runs outside the cluster and must
+                      reach the server through a specific externally-routable address. An
+                      incorrect value silently breaks coordinator-to-server connectivity.
+                    type: string
+                  heartbeatInterval:
+                    default: 5
+                    description: heartbeatInterval is the seconds between heartbeats;
+                      must be > 0.
+                    type: number
+                  l2EventFlushInterval:
+                    default: 1
+                    description: |-
+                      l2EventFlushInterval is the seconds between L2 event flush attempts; must
+                      be > 0.
+                    type: number
+                  l2EventReporting:
+                    default: false
+                    description: |-
+                      l2EventReporting enables reporting L2 store/lookup events to the
+                      coordinator for fleet-wide usage tracking and eviction.
+                    type: boolean
+                  ref:
+                    description: |-
+                      ref names an LMCacheCoordinator in the same namespace. The operator
+                      resolves it to the coordinator's in-cluster Service URL.
+                    properties:
+                      name:
+                        default: ""
+                        description: |-
+                          Name of the referent.
+                          This field is effectively required, but due to backwards compatibility is
+                          allowed to be empty. Instances of this type with an empty value here are
+                          almost certainly wrong.
+                          More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                        type: string
+                    type: object
+                    x-kubernetes-map-type: atomic
+                  url:
+                    description: |-
+                      url is an explicit coordinator base URL (e.g. http://coordinator:9300),
+                      used to target a coordinator the operator does not manage.
+                    type: string
+                type: object
+              env:
+                description: env defines additional environment variables.
+                items:
+                  description: EnvVar represents an environment variable present in
+                    a Container.
+                  properties:
+                    name:
+                      description: |-
+                        Name of the environment variable.
+                        May consist of any printable ASCII characters except '='.
+                      type: string
+                    value:
+                      description: |-
+                        Variable references $(VAR_NAME) are expanded
+                        using the previously defined environment variables in the container and
+                        any service environment variables. If a variable cannot be resolved,
+                        the reference in the input string will be unchanged. Double $$ are reduced
+                        to a single $, which allows for escaping the $(VAR_NAME) syntax: i.e.
+                        "$$(VAR_NAME)" will produce the string literal "$(VAR_NAME)".
+                        Escaped references will never be expanded, regardless of whether the variable
+                        exists or not.
+                        Defaults to "".
+                      type: string
+                    valueFrom:
+                      description: Source for the environment variable's value. Cannot
+                        be used if value is not empty.
+                      properties:
+                        configMapKeyRef:
+                          description: Selects a key of a ConfigMap.
+                          properties:
+                            key:
+                              description: The key to select.
+                              type: string
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                            optional:
+                              description: Specify whether the ConfigMap or its key
+                                must be defined
+                              type: boolean
+                          required:
+                          - key
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        fieldRef:
+                          description: |-
+                            Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`,
+                            spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.
+                          properties:
+                            apiVersion:
+                              description: Version of the schema the FieldPath is
+                                written in terms of, defaults to "v1".
+                              type: string
+                            fieldPath:
+                              description: Path of the field to select in the specified
+                                API version.
+                              type: string
+                          required:
+                          - fieldPath
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        fileKeyRef:
+                          description: |-
+                            FileKeyRef selects a key of the env file.
+                            Requires the EnvFiles feature gate to be enabled.
+                          properties:
+                            key:
+                              description: |-
+                                The key within the env file. An invalid key will prevent the pod from starting.
+                                The keys defined within a source may consist of any printable ASCII characters except '='.
+                                During Alpha stage of the EnvFiles feature gate, the key size is limited to 128 characters.
+                              type: string
+                            optional:
+                              default: false
+                              description: |-
+                                Specify whether the file or its key must be defined. If the file or key
+                                does not exist, then the env var is not published.
+                                If optional is set to true and the specified key does not exist,
+                                the environment variable will not be set in the Pod's containers.
+
+                                If optional is set to false and the specified key does not exist,
+                                an error will be returned during Pod creation.
+                              type: boolean
+                            path:
+                              description: |-
+                                The path within the volume from which to select the file.
+                                Must be relative and may not contain the '..' path or start with '..'.
+                              type: string
+                            volumeName:
+                              description: The name of the volume mount containing
+                                the env file.
+                              type: string
+                          required:
+                          - key
+                          - path
+                          - volumeName
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        resourceFieldRef:
+                          description: |-
+                            Selects a resource of the container: only resources limits and requests
+                            (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.
+                          properties:
+                            containerName:
+                              description: 'Container name: required for volumes,
+                                optional for env vars'
+                              type: string
+                            divisor:
+                              anyOf:
+                              - type: integer
+                              - type: string
+                              description: Specifies the output format of the exposed
+                                resources, defaults to "1"
+                              pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                              x-kubernetes-int-or-string: true
+                            resource:
+                              description: 'Required: resource to select'
+                              type: string
+                          required:
+                          - resource
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        secretKeyRef:
+                          description: Selects a key of a secret in the pod's namespace
+                          properties:
+                            key:
+                              description: The key of the secret to select from.  Must
+                                be a valid secret key.
+                              type: string
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                            optional:
+                              description: Specify whether the Secret or its key must
+                                be defined
+                              type: boolean
+                          required:
+                          - key
+                          type: object
+                          x-kubernetes-map-type: atomic
+                      type: object
+                  required:
+                  - name
+                  type: object
+                type: array
+              eviction:
+                description: eviction defines the cache eviction configuration.
+                properties:
+                  evictionRatio:
+                    default: 0.2
+                    description: evictionRatio is the fraction of cache to evict when
+                      triggered.
+                    type: number
+                  policy:
+                    default: LRU
+                    description: policy is the eviction policy. LRU or noop.
+                    enum:
+                    - LRU
+                    - noop
+                    type: string
+                  triggerWatermark:
+                    default: 0.8
+                    description: triggerWatermark is the cache usage ratio that triggers
+                      eviction.
+                    type: number
+                type: object
+              extraArgs:
+                description: |-
+                  extraArgs are additional CLI flags appended to the server command.
+                  They are appended last and can override any auto-generated flag.
+                items:
+                  type: string
+                type: array
+              gpuVendor:
+                default: nvidia
+                description: |-
+                  gpuVendor selects the GPU vendor. "nvidia" (default) requires the NVIDIA
+                  GPU Operator's "nvidia" RuntimeClass; "amd" runs on the default container
+                  runtime.
+                enum:
+                - nvidia
+                - amd
+                type: string
+              hostNetwork:
+                default: false
+                description: |-
+                  hostNetwork runs the pod in the host's network namespace. When true the
+                  operator also sets dnsPolicy to ClusterFirstWithHostNet so cluster DNS
+                  still works. Default: false.
+                type: boolean
+              image:
+                description: image defines the container image to use.
+                properties:
+                  pullPolicy:
+                    default: IfNotPresent
+                    description: pullPolicy is the image pull policy.
+                    enum:
+                    - Always
+                    - Never
+                    - IfNotPresent
+                    type: string
+                  repository:
+                    default: lmcache/vllm-openai
+                    description: repository is the container image repository.
+                    type: string
+                  tag:
+                    default: latest
+                    description: tag is the container image tag.
+                    type: string
+                type: object
+              imagePullSecrets:
+                description: imagePullSecrets is a list of references to secrets for
+                  pulling the image.
+                items:
+                  description: |-
+                    LocalObjectReference contains enough information to let you locate the
+                    referenced object inside the same namespace.
+                  properties:
+                    name:
+                      default: ""
+                      description: |-
+                        Name of the referent.
+                        This field is effectively required, but due to backwards compatibility is
+                        allowed to be empty. Instances of this type with an empty value here are
+                        almost certainly wrong.
+                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      type: string
+                  type: object
+                  x-kubernetes-map-type: atomic
+                type: array
+              injection:
+                description: |-
+                  injection defines the defaults the LMCache mutating webhook reads for pods
+                  bound to this engine. When unset, the webhook wires only the connection;
+                  set injection.payloadImage to also stage an lmcache code payload.
+                properties:
+                  imagePullSecrets:
+                    description: |-
+                      imagePullSecrets are appended to the vLLM pod's spec.imagePullSecrets so a
+                      PRIVATE payload init-container image can pull. The referenced Secret(s)
+                      must already exist in the vLLM pod's namespace; the operator does not copy
+                      them cross-namespace.
+                    items:
+                      description: |-
+                        LocalObjectReference contains enough information to let you locate the
+                        referenced object inside the same namespace.
+                      properties:
+                        name:
+                          default: ""
+                          description: |-
+                            Name of the referent.
+                            This field is effectively required, but due to backwards compatibility is
+                            allowed to be empty. Instances of this type with an empty value here are
+                            almost certainly wrong.
+                            More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                          type: string
+                      type: object
+                      x-kubernetes-map-type: atomic
+                    type: array
+                  payloadImage:
+                    description: |-
+                      payloadImage is a purpose-built init-container image (repository/tag/
+                      pullPolicy, like spec.image) that ships an unpacked lmcache tree under
+                      /payload and copies it to $SHARED_DIR on start (see
+                      docker/Dockerfile.payload); the vLLM container imports it via PYTHONPATH.
+
+                      repository has no usable default — the ImageSpec default
+                      (lmcache/vllm-openai) is NOT a payload — so it must be set explicitly. For
+                      private registries, imagePullSecrets must reference Secret(s) in the vLLM
+                      pod's namespace.
+                    properties:
+                      pullPolicy:
+                        default: IfNotPresent
+                        description: pullPolicy is the image pull policy.
+                        enum:
+                        - Always
+                        - Never
+                        - IfNotPresent
+                        type: string
+                      repository:
+                        default: lmcache/vllm-openai
+                        description: repository is the container image repository.
+                        type: string
+                      tag:
+                        default: latest
+                        description: tag is the container image tag.
+                        type: string
+                    type: object
+                  targetContainer:
+                    description: |-
+                      targetContainer is the name of the vLLM container to inject into. Empty
+                      (the default) selects the first container; a per-pod annotation may
+                      override it.
+                    type: string
+                type: object
+              l1:
+                description: l1 defines the L1 memory cache configuration.
+                properties:
+                  sizeGB:
+                    description: |-
+                      sizeGB is the L1 cache size in gigabytes. Required, must be > 0.
+                      The CRD-level constraint (exclusiveMinimum=0) rejects invalid values
+                      at admission time so the controller never sees them; the in-Go
+                      ValidateSpec keeps the same rule for defense in depth.
+                    exclusiveMinimum: true
+                    minimum: 0
+                    type: number
+                required:
+                - sizeGB
+                type: object
+              l2Backend:
+                description: |-
+                  l2Backend defines the L2 storage backend.
+                  Currently only a single adapter is supported.
+                properties:
+                  prefetchMaxInFlight:
+                    default: 8
+                    description: |-
+                      prefetchMaxInFlight limits the number of concurrent prefetch
+                      (L2→L1 load) requests, preventing excessive L1 memory pressure.
+                    format: int32
+                    minimum: 1
+                    type: integer
+                  prefetchPolicy:
+                    default: default
+                    description: |-
+                      prefetchPolicy controls how keys flow from L2 back to L1 on
+                      cache misses. "default" picks the first adapter that has the key.
+                    enum:
+                    - default
+                    - retain
+                    type: string
+                  raw:
+                    description: |-
+                      raw is an escape hatch for adapter types not yet natively
+                      supported by the operator (e.g. nixl_store, fs, mock).
+                      The JSON is passed through to --l2-adapter as-is.
+                    properties:
+                      config:
+                        additionalProperties:
+                          x-kubernetes-preserve-unknown-fields: true
+                        description: config is type-specific configuration as a free-form
+                          map.
+                        type: object
+                      type:
+                        description: type is the adapter type name (e.g. "nixl_store",
+                          "fs", "mock").
+                        type: string
+                    required:
+                    - type
+                    type: object
+                  resp:
+                    description: |-
+                      resp configures a Redis/Valkey RESP L2 adapter backed by the
+                      native C++ connector.
+                    properties:
+                      authSecretRef:
+                        description: |-
+                          authSecretRef is a reference to a Secret containing "username"
+                          and "password" keys for Redis authentication.
+                          The Secret may live in a different namespace; the operator will
+                          create a managed copy in the LMCacheEngine's namespace.
+                          The credentials are injected via environment variables so they
+                          do not appear in container args or kubectl describe output.
+                        properties:
+                          name:
+                            description: name is the name of the Secret.
+                            type: string
+                          namespace:
+                            description: |-
+                              namespace is the namespace of the Secret.
+                              If empty, defaults to the namespace of the LMCacheEngine resource.
+                            type: string
+                        required:
+                        - name
+                        type: object
+                      host:
+                        description: host is the Redis/Valkey server hostname or IP.
+                        type: string
+                      maxCapacityGB:
+                        default: 0
+                        description: |-
+                          maxCapacityGB is the max L2 capacity in GB for usage tracking
+                          and eviction. 0 means disabled.
+                        type: number
+                      numWorkers:
+                        default: 8
+                        description: numWorkers is the number of C++ worker threads
+                          for I/O.
+                        format: int32
+                        minimum: 1
+                        type: integer
+                      port:
+                        description: port is the Redis/Valkey server port.
+                        format: int32
+                        maximum: 65535
+                        minimum: 1
+                        type: integer
+                    required:
+                    - host
+                    - port
+                    type: object
+                  storePolicy:
+                    default: default
+                    description: |-
+                      storePolicy controls how keys flow from L1 to L2.
+                      "default" stores all keys to the adapter and keeps L1.
+                      "skip_l1" stores all keys to the adapter and deletes them from L1
+                      (buffer-only mode — pair with eviction.policy=noop).
+                    enum:
+                    - default
+                    - skip_l1
+                    type: string
+                type: object
+              logLevel:
+                default: INFO
+                description: logLevel is the log level for the LMCache server.
+                enum:
+                - DEBUG
+                - INFO
+                - WARNING
+                - ERROR
+                type: string
+              nodeSelector:
+                additionalProperties:
+                  type: string
+                description: nodeSelector determines which nodes get an LMCache instance.
+                type: object
+              podAnnotations:
+                additionalProperties:
+                  type: string
+                description: podAnnotations are additional annotations added to pods.
+                type: object
+              podLabels:
+                additionalProperties:
+                  type: string
+                description: podLabels are additional labels added to pods.
+                type: object
+              priorityClassName:
+                description: priorityClassName is the priority class for the pods.
+                type: string
+              privileged:
+                default: false
+                description: |-
+                  privileged runs the engine container in privileged mode. On some clusters
+                  this is required for the engine to see all node GPUs (for CUDA IPC) without
+                  claiming any via the nvidia.com/gpu device plugin; on many clusters
+                  NVIDIA_VISIBLE_DEVICES=all already grants that visibility without it, so it
+                  defaults to false. Set it to true only on clusters where the engine cannot
+                  otherwise see the GPUs. For gpuVendor "amd" this is effectively required:
+                  there is no NVIDIA-style RuntimeClass device injection, so privileged mode
+                  is the only way the engine reaches /dev/kfd and /dev/dri. Clusters using Pod
+                  Security Standards must allow the privileged profile for this namespace when
+                  it is enabled. Default: false.
+                type: boolean
+              prometheus:
+                description: prometheus defines Prometheus monitoring configuration.
+                properties:
+                  enabled:
+                    default: true
+                    description: enabled controls whether Prometheus metrics are exposed.
+                    type: boolean
+                  port:
+                    default: 9090
+                    description: port is the Prometheus metrics port.
+                    format: int32
+                    type: integer
+                  serviceMonitor:
+                    description: serviceMonitor configures the Prometheus ServiceMonitor.
+                    properties:
+                      enabled:
+                        default: false
+                        description: enabled controls whether a ServiceMonitor CR
+                          is created.
+                        type: boolean
+                      interval:
+                        default: 30s
+                        description: interval is the Prometheus scrape interval.
+                        type: string
+                      labels:
+                        additionalProperties:
+                          type: string
+                        description: labels are additional labels added to the ServiceMonitor.
+                        type: object
+                    type: object
+                type: object
+              resourceOverrides:
+                description: resourceOverrides allows overriding auto-computed resource
+                  requirements.
+                properties:
+                  claims:
+                    description: |-
+                      Claims lists the names of resources, defined in spec.resourceClaims,
+                      that are used by this container.
+
+                      This field depends on the
+                      DynamicResourceAllocation feature gate.
+
+                      This field is immutable. It can only be set for containers.
+                    items:
+                      description: ResourceClaim references one entry in PodSpec.ResourceClaims.
+                      properties:
+                        name:
+                          description: |-
+                            Name must match the name of one entry in pod.spec.resourceClaims of
+                            the Pod where this field is used. It makes that resource available
+                            inside a container.
+                          type: string
+                        request:
+                          description: |-
+                            Request is the name chosen for a request in the referenced claim.
+                            If empty, everything from the claim is made available, otherwise
+                            only the result of this request.
+                          type: string
+                      required:
+                      - name
+                      type: object
+                    type: array
+                    x-kubernetes-list-map-keys:
+                    - name
+                    x-kubernetes-list-type: map
+                  limits:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Limits describes the maximum amount of compute resources allowed.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                  requests:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Requests describes the minimum amount of compute resources required.
+                      If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                      otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                type: object
+              server:
+                description: server defines server configuration.
+                properties:
+                  chunkSize:
+                    default: 256
+                    description: chunkSize is the token chunk size.
+                    format: int32
+                    type: integer
+                  hashAlgorithm:
+                    default: blake3
+                    description: hashAlgorithm is the hash algorithm used for token
+                      hashing.
+                    enum:
+                    - builtin
+                    - sha256_cbor
+                    - blake3
+                    type: string
+                  httpPort:
+                    default: 8080
+                    description: httpPort is the HTTP frontend port (health checks,
+                      cache admin).
+                    format: int32
+                    maximum: 65535
+                    minimum: 1024
+                    type: integer
+                  maxWorkers:
+                    default: 1
+                    description: maxWorkers is the number of worker threads.
+                    format: int32
+                    type: integer
+                  port:
+                    default: 5555
+                    description: port is the server listening port.
+                    format: int32
+                    maximum: 65535
+                    minimum: 1024
+                    type: integer
+                type: object
+              serviceAccountName:
+                description: serviceAccountName is the name of the ServiceAccount
+                  to use.
+                type: string
+              tolerations:
+                description: tolerations defines pod tolerations.
+                items:
+                  description: |-
+                    The pod this Toleration is attached to tolerates any taint that matches
+                    the triple <key,value,effect> using the matching operator <operator>.
+                  properties:
+                    effect:
+                      description: |-
+                        Effect indicates the taint effect to match. Empty means match all taint effects.
+                        When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute.
+                      type: string
+                    key:
+                      description: |-
+                        Key is the taint key that the toleration applies to. Empty means match all taint keys.
+                        If the key is empty, operator must be Exists; this combination means to match all values and all keys.
+                      type: string
+                    operator:
+                      description: |-
+                        Operator represents a key's relationship to the value.
+                        Valid operators are Exists, Equal, Lt, and Gt. Defaults to Equal.
+                        Exists is equivalent to wildcard for value, so that a pod can
+                        tolerate all taints of a particular category.
+                        Lt and Gt perform numeric comparisons (requires feature gate TaintTolerationComparisonOperators).
+                      type: string
+                    tolerationSeconds:
+                      description: |-
+                        TolerationSeconds represents the period of time the toleration (which must be
+                        of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default,
+                        it is not set, which means tolerate the taint forever (do not evict). Zero and
+                        negative values will be treated as 0 (evict immediately) by the system.
+                      format: int64
+                      type: integer
+                    value:
+                      description: |-
+                        Value is the taint value the toleration matches to.
+                        If the operator is Exists, the value should be empty, otherwise just a regular string.
+                      type: string
+                  type: object
+                type: array
+              volumeMounts:
+                description: volumeMounts defines additional volume mounts.
+                items:
+                  description: VolumeMount describes a mounting of a Volume within
+                    a container.
+                  properties:
+                    mountPath:
+                      description: |-
+                        Path within the container at which the volume should be mounted.  Must
+                        not contain ':'.
+                      type: string
+                    mountPropagation:
+                      description: |-
+                        mountPropagation determines how mounts are propagated from the host
+                        to container and the other way around.
+                        When not set, MountPropagationNone is used.
+                        This field is beta in 1.10.
+                        When RecursiveReadOnly is set to IfPossible or to Enabled, MountPropagation must be None or unspecified
+                        (which defaults to None).
+                      type: string
+                    name:
+                      description: This must match the Name of a Volume.
+                      type: string
+                    readOnly:
+                      description: |-
+                        Mounted read-only if true, read-write otherwise (false or unspecified).
+                        Defaults to false.
+                      type: boolean
+                    recursiveReadOnly:
+                      description: |-
+                        RecursiveReadOnly specifies whether read-only mounts should be handled
+                        recursively.
+
+                        If ReadOnly is false, this field has no meaning and must be unspecified.
+
+                        If ReadOnly is true, and this field is set to Disabled, the mount is not made
+                        recursively read-only.  If this field is set to IfPossible, the mount is made
+                        recursively read-only, if it is supported by the container runtime.  If this
+                        field is set to Enabled, the mount is made recursively read-only if it is
+                        supported by the container runtime, otherwise the pod will not be started and
+                        an error will be generated to indicate the reason.
+
+                        If this field is set to IfPossible or Enabled, MountPropagation must be set to
+                        None (or be unspecified, which defaults to None).
+
+                        If this field is not specified, it is treated as an equivalent of Disabled.
+                      type: string
+                    subPath:
+                      description: |-
+                        Path within the volume from which the container's volume should be mounted.
+                        Defaults to "" (volume's root).
+                      type: string
+                    subPathExpr:
+                      description: |-
+                        Expanded path within the volume from which the container's volume should be mounted.
+                        Behaves similarly to SubPath but environment variable references $(VAR_NAME) are expanded using the container's environment.
+                        Defaults to "" (volume's root).
+                        SubPathExpr and SubPath are mutually exclusive.
+                      type: string
+                  required:
+                  - mountPath
+                  - name
+                  type: object
+                type: array
+              volumes:
+                description: volumes defines additional volumes.
+                items:
+                  description: Volume represents a named volume in a pod that may
+                    be accessed by any container in the pod.
+                  properties:
+                    awsElasticBlockStore:
+                      description: |-
+                        awsElasticBlockStore represents an AWS Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        Deprecated: AWSElasticBlockStore is deprecated. All operations for the in-tree
+                        awsElasticBlockStore type are redirected to the ebs.csi.aws.com CSI driver.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: string
+                        partition:
+                          description: |-
+                            partition is the partition in the volume that you want to mount.
+                            If omitted, the default is to mount by volume name.
+                            Examples: For volume /dev/sda1, you specify the partition as "1".
+                            Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty).
+                          format: int32
+                          type: integer
+                        readOnly:
+                          description: |-
+                            readOnly value true will force the readOnly setting in VolumeMounts.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: boolean
+                        volumeID:
+                          description: |-
+                            volumeID is unique ID of the persistent disk resource in AWS (Amazon EBS volume).
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    azureDisk:
+                      description: |-
+                        azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod.
+                        Deprecated: AzureDisk is deprecated. All operations for the in-tree azureDisk type
+                        are redirected to the disk.csi.azure.com CSI driver.
+                      properties:
+                        cachingMode:
+                          description: 'cachingMode is the Host Caching mode: None,
+                            Read Only, Read Write.'
+                          type: string
+                        diskName:
+                          description: diskName is the Name of the data disk in the
+                            blob storage
+                          type: string
+                        diskURI:
+                          description: diskURI is the URI of data disk in the blob
+                            storage
+                          type: string
+                        fsType:
+                          default: ext4
+                          description: |-
+                            fsType is Filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        kind:
+                          description: 'kind expected values are Shared: multiple
+                            blob disks per storage account  Dedicated: single blob
+                            disk per storage account  Managed: azure managed data
+                            disk (only in managed availability set). defaults to shared'
+                          type: string
+                        readOnly:
+                          default: false
+                          description: |-
+                            readOnly Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                      required:
+                      - diskName
+                      - diskURI
+                      type: object
+                    azureFile:
+                      description: |-
+                        azureFile represents an Azure File Service mount on the host and bind mount to the pod.
+                        Deprecated: AzureFile is deprecated. All operations for the in-tree azureFile type
+                        are redirected to the file.csi.azure.com CSI driver.
+                      properties:
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretName:
+                          description: secretName is the  name of secret that contains
+                            Azure Storage Account Name and Key
+                          type: string
+                        shareName:
+                          description: shareName is the azure share Name
+                          type: string
+                      required:
+                      - secretName
+                      - shareName
+                      type: object
+                    cephfs:
+                      description: |-
+                        cephFS represents a Ceph FS mount on the host that shares a pod's lifetime.
+                        Deprecated: CephFS is deprecated and the in-tree cephfs type is no longer supported.
+                      properties:
+                        monitors:
+                          description: |-
+                            monitors is Required: Monitors is a collection of Ceph monitors
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        path:
+                          description: 'path is Optional: Used as the mounted root,
+                            rather than the full Ceph tree, default is /'
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: boolean
+                        secretFile:
+                          description: |-
+                            secretFile is Optional: SecretFile is the path to key ring for User, default is /etc/ceph/user.secret
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: string
+                        secretRef:
+                          description: |-
+                            secretRef is Optional: SecretRef is reference to the authentication secret for User, default is empty.
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        user:
+                          description: |-
+                            user is optional: User is the rados user name, default is admin
+                            More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it
+                          type: string
+                      required:
+                      - monitors
+                      type: object
+                    cinder:
+                      description: |-
+                        cinder represents a cinder volume attached and mounted on kubelets host machine.
+                        Deprecated: Cinder is deprecated. All operations for the in-tree cinder type
+                        are redirected to the cinder.csi.openstack.org CSI driver.
+                        More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is optional: points to a secret object containing parameters used to connect
+                            to OpenStack.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        volumeID:
+                          description: |-
+                            volumeID used to identify the volume in cinder.
+                            More info: https://examples.k8s.io/mysql-cinder-pd/README.md
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    configMap:
+                      description: configMap represents a configMap that should populate
+                        this volume
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode is optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: |-
+                            items if unspecified, each key-value pair in the Data field of the referenced
+                            ConfigMap will be projected into the volume as a file whose name is the
+                            key and content is the value. If specified, the listed keys will be
+                            projected into the specified paths, and unlisted keys will not be
+                            present. If a key is specified which is not present in the ConfigMap,
+                            the volume setup will error unless it is marked optional. Paths must be
+                            relative and may not contain the '..' path or start with '..'.
+                          items:
+                            description: Maps a string key to a path within a volume.
+                            properties:
+                              key:
+                                description: key is the key to project.
+                                type: string
+                              mode:
+                                description: |-
+                                  mode is Optional: mode bits used to set permissions on this file.
+                                  Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: |-
+                                  path is the relative path of the file to map the key to.
+                                  May not be an absolute path.
+                                  May not contain the path element '..'.
+                                  May not start with the string '..'.
+                                type: string
+                            required:
+                            - key
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        name:
+                          default: ""
+                          description: |-
+                            Name of the referent.
+                            This field is effectively required, but due to backwards compatibility is
+                            allowed to be empty. Instances of this type with an empty value here are
+                            almost certainly wrong.
+                            More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                          type: string
+                        optional:
+                          description: optional specify whether the ConfigMap or its
+                            keys must be defined
+                          type: boolean
+                      type: object
+                      x-kubernetes-map-type: atomic
+                    csi:
+                      description: csi (Container Storage Interface) represents ephemeral
+                        storage that is handled by certain external CSI drivers.
+                      properties:
+                        driver:
+                          description: |-
+                            driver is the name of the CSI driver that handles this volume.
+                            Consult with your admin for the correct name as registered in the cluster.
+                          type: string
+                        fsType:
+                          description: |-
+                            fsType to mount. Ex. "ext4", "xfs", "ntfs".
+                            If not provided, the empty value is passed to the associated CSI driver
+                            which will determine the default filesystem to apply.
+                          type: string
+                        nodePublishSecretRef:
+                          description: |-
+                            nodePublishSecretRef is a reference to the secret object containing
+                            sensitive information to pass to the CSI driver to complete the CSI
+                            NodePublishVolume and NodeUnpublishVolume calls.
+                            This field is optional, and  may be empty if no secret is required. If the
+                            secret object contains more than one secret, all secret references are passed.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        readOnly:
+                          description: |-
+                            readOnly specifies a read-only configuration for the volume.
+                            Defaults to false (read/write).
+                          type: boolean
+                        volumeAttributes:
+                          additionalProperties:
+                            type: string
+                          description: |-
+                            volumeAttributes stores driver-specific properties that are passed to the CSI
+                            driver. Consult your driver's documentation for supported values.
+                          type: object
+                      required:
+                      - driver
+                      type: object
+                    downwardAPI:
+                      description: downwardAPI represents downward API about the pod
+                        that should populate this volume
+                      properties:
+                        defaultMode:
+                          description: |-
+                            Optional: mode bits to use on created files by default. Must be a
+                            Optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: Items is a list of downward API volume file
+                          items:
+                            description: DownwardAPIVolumeFile represents information
+                              to create the file containing the pod field
+                            properties:
+                              fieldRef:
+                                description: 'Required: Selects a field of the pod:
+                                  only annotations, labels, name, namespace and uid
+                                  are supported.'
+                                properties:
+                                  apiVersion:
+                                    description: Version of the schema the FieldPath
+                                      is written in terms of, defaults to "v1".
+                                    type: string
+                                  fieldPath:
+                                    description: Path of the field to select in the
+                                      specified API version.
+                                    type: string
+                                required:
+                                - fieldPath
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              mode:
+                                description: |-
+                                  Optional: mode bits used to set permissions on this file, must be an octal value
+                                  between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: 'Required: Path is  the relative path
+                                  name of the file to be created. Must not be absolute
+                                  or contain the ''..'' path. Must be utf-8 encoded.
+                                  The first item of the relative path must not start
+                                  with ''..'''
+                                type: string
+                              resourceFieldRef:
+                                description: |-
+                                  Selects a resource of the container: only resources limits and requests
+                                  (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.
+                                properties:
+                                  containerName:
+                                    description: 'Container name: required for volumes,
+                                      optional for env vars'
+                                    type: string
+                                  divisor:
+                                    anyOf:
+                                    - type: integer
+                                    - type: string
+                                    description: Specifies the output format of the
+                                      exposed resources, defaults to "1"
+                                    pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                    x-kubernetes-int-or-string: true
+                                  resource:
+                                    description: 'Required: resource to select'
+                                    type: string
+                                required:
+                                - resource
+                                type: object
+                                x-kubernetes-map-type: atomic
+                            required:
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    emptyDir:
+                      description: |-
+                        emptyDir represents a temporary directory that shares a pod's lifetime.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                      properties:
+                        medium:
+                          description: |-
+                            medium represents what type of storage medium should back this directory.
+                            The default is "" which means to use the node's default medium.
+                            Must be an empty string (default) or Memory.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                          type: string
+                        sizeLimit:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          description: |-
+                            sizeLimit is the total amount of local storage required for this EmptyDir volume.
+                            The size limit is also applicable for memory medium.
+                            The maximum usage on memory medium EmptyDir would be the minimum value between
+                            the SizeLimit specified here and the sum of memory limits of all containers in a pod.
+                            The default is nil which means that the limit is undefined.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir
+                          pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                          x-kubernetes-int-or-string: true
+                      type: object
+                    ephemeral:
+                      description: |-
+                        ephemeral represents a volume that is handled by a cluster storage driver.
+                        The volume's lifecycle is tied to the pod that defines it - it will be created before the pod starts,
+                        and deleted when the pod is removed.
+
+                        Use this if:
+                        a) the volume is only needed while the pod runs,
+                        b) features of normal volumes like restoring from snapshot or capacity
+                           tracking are needed,
+                        c) the storage driver is specified through a storage class, and
+                        d) the storage driver supports dynamic volume provisioning through
+                           a PersistentVolumeClaim (see EphemeralVolumeSource for more
+                           information on the connection between this volume type
+                           and PersistentVolumeClaim).
+
+                        Use PersistentVolumeClaim or one of the vendor-specific
+                        APIs for volumes that persist for longer than the lifecycle
+                        of an individual pod.
+
+                        Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to
+                        be used that way - see the documentation of the driver for
+                        more information.
+
+                        A pod can use both types of ephemeral volumes and
+                        persistent volumes at the same time.
+                      properties:
+                        volumeClaimTemplate:
+                          description: |-
+                            Will be used to create a stand-alone PVC to provision the volume.
+                            The pod in which this EphemeralVolumeSource is embedded will be the
+                            owner of the PVC, i.e. the PVC will be deleted together with the
+                            pod.  The name of the PVC will be `<pod name>-<volume name>` where
+                            `<volume name>` is the name from the `PodSpec.Volumes` array
+                            entry. Pod validation will reject the pod if the concatenated name
+                            is not valid for a PVC (for example, too long).
+
+                            An existing PVC with that name that is not owned by the pod
+                            will *not* be used for the pod to avoid using an unrelated
+                            volume by mistake. Starting the pod is then blocked until
+                            the unrelated PVC is removed. If such a pre-created PVC is
+                            meant to be used by the pod, the PVC has to updated with an
+                            owner reference to the pod once the pod exists. Normally
+                            this should not be necessary, but it may be useful when
+                            manually reconstructing a broken cluster.
+
+                            This field is read-only and no changes will be made by Kubernetes
+                            to the PVC after it has been created.
+
+                            Required, must not be nil.
+                          properties:
+                            metadata:
+                              description: |-
+                                May contain labels and annotations that will be copied into the PVC
+                                when creating it. No other fields are allowed and will be rejected during
+                                validation.
+                              type: object
+                            spec:
+                              description: |-
+                                The specification for the PersistentVolumeClaim. The entire content is
+                                copied unchanged into the PVC that gets created from this
+                                template. The same fields as in a PersistentVolumeClaim
+                                are also valid here.
+                              properties:
+                                accessModes:
+                                  description: |-
+                                    accessModes contains the desired access modes the volume should have.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#access-modes-1
+                                  items:
+                                    type: string
+                                  type: array
+                                  x-kubernetes-list-type: atomic
+                                dataSource:
+                                  description: |-
+                                    dataSource field can be used to specify either:
+                                    * An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot)
+                                    * An existing PVC (PersistentVolumeClaim)
+                                    If the provisioner or an external controller can support the specified data source,
+                                    it will create a new volume based on the contents of the specified data source.
+                                    When the AnyVolumeDataSource feature gate is enabled, dataSource contents will be copied to dataSourceRef,
+                                    and dataSourceRef contents will be copied to dataSource when dataSourceRef.namespace is not specified.
+                                    If the namespace is specified, then dataSourceRef will not be copied to dataSource.
+                                  properties:
+                                    apiGroup:
+                                      description: |-
+                                        APIGroup is the group for the resource being referenced.
+                                        If APIGroup is not specified, the specified Kind must be in the core API group.
+                                        For any other third-party types, APIGroup is required.
+                                      type: string
+                                    kind:
+                                      description: Kind is the type of resource being
+                                        referenced
+                                      type: string
+                                    name:
+                                      description: Name is the name of resource being
+                                        referenced
+                                      type: string
+                                  required:
+                                  - kind
+                                  - name
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                dataSourceRef:
+                                  description: |-
+                                    dataSourceRef specifies the object from which to populate the volume with data, if a non-empty
+                                    volume is desired. This may be any object from a non-empty API group (non
+                                    core object) or a PersistentVolumeClaim object.
+                                    When this field is specified, volume binding will only succeed if the type of
+                                    the specified object matches some installed volume populator or dynamic
+                                    provisioner.
+                                    This field will replace the functionality of the dataSource field and as such
+                                    if both fields are non-empty, they must have the same value. For backwards
+                                    compatibility, when namespace isn't specified in dataSourceRef,
+                                    both fields (dataSource and dataSourceRef) will be set to the same
+                                    value automatically if one of them is empty and the other is non-empty.
+                                    When namespace is specified in dataSourceRef,
+                                    dataSource isn't set to the same value and must be empty.
+                                    There are three important differences between dataSource and dataSourceRef:
+                                    * While dataSource only allows two specific types of objects, dataSourceRef
+                                      allows any non-core object, as well as PersistentVolumeClaim objects.
+                                    * While dataSource ignores disallowed values (dropping them), dataSourceRef
+                                      preserves all values, and generates an error if a disallowed value is
+                                      specified.
+                                    * While dataSource only allows local objects, dataSourceRef allows objects
+                                      in any namespaces.
+                                    (Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled.
+                                    (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled.
+                                  properties:
+                                    apiGroup:
+                                      description: |-
+                                        APIGroup is the group for the resource being referenced.
+                                        If APIGroup is not specified, the specified Kind must be in the core API group.
+                                        For any other third-party types, APIGroup is required.
+                                      type: string
+                                    kind:
+                                      description: Kind is the type of resource being
+                                        referenced
+                                      type: string
+                                    name:
+                                      description: Name is the name of resource being
+                                        referenced
+                                      type: string
+                                    namespace:
+                                      description: |-
+                                        Namespace is the namespace of resource being referenced
+                                        Note that when a namespace is specified, a gateway.networking.k8s.io/ReferenceGrant object is required in the referent namespace to allow that namespace's owner to accept the reference. See the ReferenceGrant documentation for details.
+                                        (Alpha) This field requires the CrossNamespaceVolumeDataSource feature gate to be enabled.
+                                      type: string
+                                  required:
+                                  - kind
+                                  - name
+                                  type: object
+                                resources:
+                                  description: |-
+                                    resources represents the minimum resources the volume should have.
+                                    Users are allowed to specify resource requirements
+                                    that are lower than previous value but must still be higher than capacity recorded in the
+                                    status field of the claim.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources
+                                  properties:
+                                    limits:
+                                      additionalProperties:
+                                        anyOf:
+                                        - type: integer
+                                        - type: string
+                                        pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                        x-kubernetes-int-or-string: true
+                                      description: |-
+                                        Limits describes the maximum amount of compute resources allowed.
+                                        More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                                      type: object
+                                    requests:
+                                      additionalProperties:
+                                        anyOf:
+                                        - type: integer
+                                        - type: string
+                                        pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                        x-kubernetes-int-or-string: true
+                                      description: |-
+                                        Requests describes the minimum amount of compute resources required.
+                                        If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                                        otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                                        More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                                      type: object
+                                  type: object
+                                selector:
+                                  description: selector is a label query over volumes
+                                    to consider for binding.
+                                  properties:
+                                    matchExpressions:
+                                      description: matchExpressions is a list of label
+                                        selector requirements. The requirements are
+                                        ANDed.
+                                      items:
+                                        description: |-
+                                          A label selector requirement is a selector that contains values, a key, and an operator that
+                                          relates the key and values.
+                                        properties:
+                                          key:
+                                            description: key is the label key that
+                                              the selector applies to.
+                                            type: string
+                                          operator:
+                                            description: |-
+                                              operator represents a key's relationship to a set of values.
+                                              Valid operators are In, NotIn, Exists and DoesNotExist.
+                                            type: string
+                                          values:
+                                            description: |-
+                                              values is an array of string values. If the operator is In or NotIn,
+                                              the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                              the values array must be empty. This array is replaced during a strategic
+                                              merge patch.
+                                            items:
+                                              type: string
+                                            type: array
+                                            x-kubernetes-list-type: atomic
+                                        required:
+                                        - key
+                                        - operator
+                                        type: object
+                                      type: array
+                                      x-kubernetes-list-type: atomic
+                                    matchLabels:
+                                      additionalProperties:
+                                        type: string
+                                      description: |-
+                                        matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                        map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                        operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                      type: object
+                                  type: object
+                                  x-kubernetes-map-type: atomic
+                                storageClassName:
+                                  description: |-
+                                    storageClassName is the name of the StorageClass required by the claim.
+                                    More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#class-1
+                                  type: string
+                                volumeAttributesClassName:
+                                  description: |-
+                                    volumeAttributesClassName may be used to set the VolumeAttributesClass used by this claim.
+                                    If specified, the CSI driver will create or update the volume with the attributes defined
+                                    in the corresponding VolumeAttributesClass. This has a different purpose than storageClassName,
+                                    it can be changed after the claim is created. An empty string or nil value indicates that no
+                                    VolumeAttributesClass will be applied to the claim. If the claim enters an Infeasible error state,
+                                    this field can be reset to its previous value (including nil) to cancel the modification.
+                                    If the resource referred to by volumeAttributesClass does not exist, this PersistentVolumeClaim will be
+                                    set to a Pending state, as reflected by the modifyVolumeStatus field, until such as a resource
+                                    exists.
+                                    More info: https://kubernetes.io/docs/concepts/storage/volume-attributes-classes/
+                                  type: string
+                                volumeMode:
+                                  description: |-
+                                    volumeMode defines what type of volume is required by the claim.
+                                    Value of Filesystem is implied when not included in claim spec.
+                                  type: string
+                                volumeName:
+                                  description: volumeName is the binding reference
+                                    to the PersistentVolume backing this claim.
+                                  type: string
+                              type: object
+                          required:
+                          - spec
+                          type: object
+                      type: object
+                    fc:
+                      description: fc represents a Fibre Channel resource that is
+                        attached to a kubelet's host machine and then exposed to the
+                        pod.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        lun:
+                          description: 'lun is Optional: FC target lun number'
+                          format: int32
+                          type: integer
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        targetWWNs:
+                          description: 'targetWWNs is Optional: FC target worldwide
+                            names (WWNs)'
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        wwids:
+                          description: |-
+                            wwids Optional: FC volume world wide identifiers (wwids)
+                            Either wwids or combination of targetWWNs and lun must be set, but not both simultaneously.
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    flexVolume:
+                      description: |-
+                        flexVolume represents a generic volume resource that is
+                        provisioned/attached using an exec based plugin.
+                        Deprecated: FlexVolume is deprecated. Consider using a CSIDriver instead.
+                      properties:
+                        driver:
+                          description: driver is the name of the driver to use for
+                            this volume.
+                          type: string
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". The default filesystem depends on FlexVolume script.
+                          type: string
+                        options:
+                          additionalProperties:
+                            type: string
+                          description: 'options is Optional: this field holds extra
+                            command options if any.'
+                          type: object
+                        readOnly:
+                          description: |-
+                            readOnly is Optional: defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is Optional: secretRef is reference to the secret object containing
+                            sensitive information to pass to the plugin scripts. This may be
+                            empty if no secret object is specified. If the secret object
+                            contains more than one secret, all secrets are passed to the plugin
+                            scripts.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                      required:
+                      - driver
+                      type: object
+                    flocker:
+                      description: |-
+                        flocker represents a Flocker volume attached to a kubelet's host machine. This depends on the Flocker control service being running.
+                        Deprecated: Flocker is deprecated and the in-tree flocker type is no longer supported.
+                      properties:
+                        datasetName:
+                          description: |-
+                            datasetName is Name of the dataset stored as metadata -> name on the dataset for Flocker
+                            should be considered as deprecated
+                          type: string
+                        datasetUUID:
+                          description: datasetUUID is the UUID of the dataset. This
+                            is unique identifier of a Flocker dataset
+                          type: string
+                      type: object
+                    gcePersistentDisk:
+                      description: |-
+                        gcePersistentDisk represents a GCE Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        Deprecated: GCEPersistentDisk is deprecated. All operations for the in-tree
+                        gcePersistentDisk type are redirected to the pd.csi.storage.gke.io CSI driver.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: string
+                        partition:
+                          description: |-
+                            partition is the partition in the volume that you want to mount.
+                            If omitted, the default is to mount by volume name.
+                            Examples: For volume /dev/sda1, you specify the partition as "1".
+                            Similarly, the volume partition for /dev/sda is "0" (or you can leave the property empty).
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          format: int32
+                          type: integer
+                        pdName:
+                          description: |-
+                            pdName is unique name of the PD resource in GCE. Used to identify the disk in GCE.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk
+                          type: boolean
+                      required:
+                      - pdName
+                      type: object
+                    gitRepo:
+                      description: |-
+                        gitRepo represents a git repository at a particular revision.
+                        Deprecated: GitRepo is deprecated. To provision a container with a git repo, mount an
+                        EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir
+                        into the Pod's container.
+                      properties:
+                        directory:
+                          description: |-
+                            directory is the target directory name.
+                            Must not contain or start with '..'.  If '.' is supplied, the volume directory will be the
+                            git repository.  Otherwise, if specified, the volume will contain the git repository in
+                            the subdirectory with the given name.
+                          type: string
+                        repository:
+                          description: repository is the URL
+                          type: string
+                        revision:
+                          description: revision is the commit hash for the specified
+                            revision.
+                          type: string
+                      required:
+                      - repository
+                      type: object
+                    glusterfs:
+                      description: |-
+                        glusterfs represents a Glusterfs mount on the host that shares a pod's lifetime.
+                        Deprecated: Glusterfs is deprecated and the in-tree glusterfs type is no longer supported.
+                      properties:
+                        endpoints:
+                          description: endpoints is the endpoint name that details
+                            Glusterfs topology.
+                          type: string
+                        path:
+                          description: |-
+                            path is the Glusterfs volume path.
+                            More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the Glusterfs volume to be mounted with read-only permissions.
+                            Defaults to false.
+                            More info: https://examples.k8s.io/volumes/glusterfs/README.md#create-a-pod
+                          type: boolean
+                      required:
+                      - endpoints
+                      - path
+                      type: object
+                    hostPath:
+                      description: |-
+                        hostPath represents a pre-existing file or directory on the host
+                        machine that is directly exposed to the container. This is generally
+                        used for system agents or other privileged things that are allowed
+                        to see the host machine. Most containers will NOT need this.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                      properties:
+                        path:
+                          description: |-
+                            path of the directory on the host.
+                            If the path is a symlink, it will follow the link to the real path.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                          type: string
+                        type:
+                          description: |-
+                            type for HostPath Volume
+                            Defaults to ""
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath
+                          type: string
+                      required:
+                      - path
+                      type: object
+                    image:
+                      description: |-
+                        image represents an OCI object (a container image or artifact) pulled and mounted on the kubelet's host machine.
+                        The volume is resolved at pod startup depending on which PullPolicy value is provided:
+
+                        - Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
+                        - Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
+                        - IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
+
+                        The volume gets re-resolved if the pod gets deleted and recreated, which means that new remote content will become available on pod recreation.
+                        A failure to resolve or pull the image during pod startup will block containers from starting and may add significant latency. Failures will be retried using normal volume backoff and will be reported on the pod reason and message.
+                        The types of objects that may be mounted by this volume are defined by the container runtime implementation on a host machine and at minimum must include all valid types supported by the container image field.
+                        The OCI object gets mounted in a single directory (spec.containers[*].volumeMounts.mountPath) by merging the manifest layers in the same way as for container images.
+                        The volume will be mounted read-only (ro) and non-executable files (noexec).
+                        Sub path mounts for containers are not supported (spec.containers[*].volumeMounts.subpath) before 1.33.
+                        The field spec.securityContext.fsGroupChangePolicy has no effect on this volume type.
+                      properties:
+                        pullPolicy:
+                          description: |-
+                            Policy for pulling OCI objects. Possible values are:
+                            Always: the kubelet always attempts to pull the reference. Container creation will fail If the pull fails.
+                            Never: the kubelet never pulls the reference and only uses a local image or artifact. Container creation will fail if the reference isn't present.
+                            IfNotPresent: the kubelet pulls if the reference isn't already present on disk. Container creation will fail if the reference isn't present and the pull fails.
+                            Defaults to Always if :latest tag is specified, or IfNotPresent otherwise.
+                          type: string
+                        reference:
+                          description: |-
+                            Required: Image or artifact reference to be used.
+                            Behaves in the same way as pod.spec.containers[*].image.
+                            Pull secrets will be assembled in the same way as for the container image by looking up node credentials, SA image pull secrets, and pod spec image pull secrets.
+                            More info: https://kubernetes.io/docs/concepts/containers/images
+                            This field is optional to allow higher level config management to default or override
+                            container images in workload controllers like Deployments and StatefulSets.
+                          type: string
+                      type: object
+                    iscsi:
+                      description: |-
+                        iscsi represents an ISCSI Disk resource that is attached to a
+                        kubelet's host machine and then exposed to the pod.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes/#iscsi
+                      properties:
+                        chapAuthDiscovery:
+                          description: chapAuthDiscovery defines whether support iSCSI
+                            Discovery CHAP authentication
+                          type: boolean
+                        chapAuthSession:
+                          description: chapAuthSession defines whether support iSCSI
+                            Session CHAP authentication
+                          type: boolean
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#iscsi
+                          type: string
+                        initiatorName:
+                          description: |-
+                            initiatorName is the custom iSCSI Initiator Name.
+                            If initiatorName is specified with iscsiInterface simultaneously, new iSCSI interface
+                            <target portal>:<volume name> will be created for the connection.
+                          type: string
+                        iqn:
+                          description: iqn is the target iSCSI Qualified Name.
+                          type: string
+                        iscsiInterface:
+                          default: default
+                          description: |-
+                            iscsiInterface is the interface Name that uses an iSCSI transport.
+                            Defaults to 'default' (tcp).
+                          type: string
+                        lun:
+                          description: lun represents iSCSI Target Lun number.
+                          format: int32
+                          type: integer
+                        portals:
+                          description: |-
+                            portals is the iSCSI Target Portal List. The portal is either an IP or ip_addr:port if the port
+                            is other than default (typically TCP ports 860 and 3260).
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                          type: boolean
+                        secretRef:
+                          description: secretRef is the CHAP Secret for iSCSI target
+                            and initiator authentication
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        targetPortal:
+                          description: |-
+                            targetPortal is iSCSI Target Portal. The Portal is either an IP or ip_addr:port if the port
+                            is other than default (typically TCP ports 860 and 3260).
+                          type: string
+                      required:
+                      - iqn
+                      - lun
+                      - targetPortal
+                      type: object
+                    name:
+                      description: |-
+                        name of the volume.
+                        Must be a DNS_LABEL and unique within the pod.
+                        More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                      type: string
+                    nfs:
+                      description: |-
+                        nfs represents an NFS mount on the host that shares a pod's lifetime
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                      properties:
+                        path:
+                          description: |-
+                            path that is exported by the NFS server.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the NFS export to be mounted with read-only permissions.
+                            Defaults to false.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: boolean
+                        server:
+                          description: |-
+                            server is the hostname or IP address of the NFS server.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs
+                          type: string
+                      required:
+                      - path
+                      - server
+                      type: object
+                    persistentVolumeClaim:
+                      description: |-
+                        persistentVolumeClaimVolumeSource represents a reference to a
+                        PersistentVolumeClaim in the same namespace.
+                        More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
+                      properties:
+                        claimName:
+                          description: |-
+                            claimName is the name of a PersistentVolumeClaim in the same namespace as the pod using this volume.
+                            More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly Will force the ReadOnly setting in VolumeMounts.
+                            Default false.
+                          type: boolean
+                      required:
+                      - claimName
+                      type: object
+                    photonPersistentDisk:
+                      description: |-
+                        photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine.
+                        Deprecated: PhotonPersistentDisk is deprecated and the in-tree photonPersistentDisk type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        pdID:
+                          description: pdID is the ID that identifies Photon Controller
+                            persistent disk
+                          type: string
+                      required:
+                      - pdID
+                      type: object
+                    portworxVolume:
+                      description: |-
+                        portworxVolume represents a portworx volume attached and mounted on kubelets host machine.
+                        Deprecated: PortworxVolume is deprecated. All operations for the in-tree portworxVolume type
+                        are redirected to the pxd.portworx.com CSI driver when the CSIMigrationPortworx feature-gate
+                        is on.
+                      properties:
+                        fsType:
+                          description: |-
+                            fSType represents the filesystem type to mount
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        volumeID:
+                          description: volumeID uniquely identifies a Portworx volume
+                          type: string
+                      required:
+                      - volumeID
+                      type: object
+                    projected:
+                      description: projected items for all in one resources secrets,
+                        configmaps, and downward API
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode are the mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        sources:
+                          description: |-
+                            sources is the list of volume projections. Each entry in this list
+                            handles one source.
+                          items:
+                            description: |-
+                              Projection that may be projected along with other supported volume types.
+                              Exactly one of these fields must be set.
+                            properties:
+                              clusterTrustBundle:
+                                description: |-
+                                  ClusterTrustBundle allows a pod to access the `.spec.trustBundle` field
+                                  of ClusterTrustBundle objects in an auto-updating file.
+
+                                  Alpha, gated by the ClusterTrustBundleProjection feature gate.
+
+                                  ClusterTrustBundle objects can either be selected by name, or by the
+                                  combination of signer name and a label selector.
+
+                                  Kubelet performs aggressive normalization of the PEM contents written
+                                  into the pod filesystem.  Esoteric PEM features such as inter-block
+                                  comments and block headers are stripped.  Certificates are deduplicated.
+                                  The ordering of certificates within the file is arbitrary, and Kubelet
+                                  may change the order over time.
+                                properties:
+                                  labelSelector:
+                                    description: |-
+                                      Select all ClusterTrustBundles that match this label selector.  Only has
+                                      effect if signerName is set.  Mutually-exclusive with name.  If unset,
+                                      interpreted as "match nothing".  If set but empty, interpreted as "match
+                                      everything".
+                                    properties:
+                                      matchExpressions:
+                                        description: matchExpressions is a list of
+                                          label selector requirements. The requirements
+                                          are ANDed.
+                                        items:
+                                          description: |-
+                                            A label selector requirement is a selector that contains values, a key, and an operator that
+                                            relates the key and values.
+                                          properties:
+                                            key:
+                                              description: key is the label key that
+                                                the selector applies to.
+                                              type: string
+                                            operator:
+                                              description: |-
+                                                operator represents a key's relationship to a set of values.
+                                                Valid operators are In, NotIn, Exists and DoesNotExist.
+                                              type: string
+                                            values:
+                                              description: |-
+                                                values is an array of string values. If the operator is In or NotIn,
+                                                the values array must be non-empty. If the operator is Exists or DoesNotExist,
+                                                the values array must be empty. This array is replaced during a strategic
+                                                merge patch.
+                                              items:
+                                                type: string
+                                              type: array
+                                              x-kubernetes-list-type: atomic
+                                          required:
+                                          - key
+                                          - operator
+                                          type: object
+                                        type: array
+                                        x-kubernetes-list-type: atomic
+                                      matchLabels:
+                                        additionalProperties:
+                                          type: string
+                                        description: |-
+                                          matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels
+                                          map is equivalent to an element of matchExpressions, whose key field is "key", the
+                                          operator is "In", and the values array contains only "value". The requirements are ANDed.
+                                        type: object
+                                    type: object
+                                    x-kubernetes-map-type: atomic
+                                  name:
+                                    description: |-
+                                      Select a single ClusterTrustBundle by object name.  Mutually-exclusive
+                                      with signerName and labelSelector.
+                                    type: string
+                                  optional:
+                                    description: |-
+                                      If true, don't block pod startup if the referenced ClusterTrustBundle(s)
+                                      aren't available.  If using name, then the named ClusterTrustBundle is
+                                      allowed not to exist.  If using signerName, then the combination of
+                                      signerName and labelSelector is allowed to match zero
+                                      ClusterTrustBundles.
+                                    type: boolean
+                                  path:
+                                    description: Relative path from the volume root
+                                      to write the bundle.
+                                    type: string
+                                  signerName:
+                                    description: |-
+                                      Select all ClusterTrustBundles that match this signer name.
+                                      Mutually-exclusive with name.  The contents of all selected
+                                      ClusterTrustBundles will be unified and deduplicated.
+                                    type: string
+                                required:
+                                - path
+                                type: object
+                              configMap:
+                                description: configMap information about the configMap
+                                  data to project
+                                properties:
+                                  items:
+                                    description: |-
+                                      items if unspecified, each key-value pair in the Data field of the referenced
+                                      ConfigMap will be projected into the volume as a file whose name is the
+                                      key and content is the value. If specified, the listed keys will be
+                                      projected into the specified paths, and unlisted keys will not be
+                                      present. If a key is specified which is not present in the ConfigMap,
+                                      the volume setup will error unless it is marked optional. Paths must be
+                                      relative and may not contain the '..' path or start with '..'.
+                                    items:
+                                      description: Maps a string key to a path within
+                                        a volume.
+                                      properties:
+                                        key:
+                                          description: key is the key to project.
+                                          type: string
+                                        mode:
+                                          description: |-
+                                            mode is Optional: mode bits used to set permissions on this file.
+                                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: |-
+                                            path is the relative path of the file to map the key to.
+                                            May not be an absolute path.
+                                            May not contain the path element '..'.
+                                            May not start with the string '..'.
+                                          type: string
+                                      required:
+                                      - key
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                  name:
+                                    default: ""
+                                    description: |-
+                                      Name of the referent.
+                                      This field is effectively required, but due to backwards compatibility is
+                                      allowed to be empty. Instances of this type with an empty value here are
+                                      almost certainly wrong.
+                                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                    type: string
+                                  optional:
+                                    description: optional specify whether the ConfigMap
+                                      or its keys must be defined
+                                    type: boolean
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              downwardAPI:
+                                description: downwardAPI information about the downwardAPI
+                                  data to project
+                                properties:
+                                  items:
+                                    description: Items is a list of DownwardAPIVolume
+                                      file
+                                    items:
+                                      description: DownwardAPIVolumeFile represents
+                                        information to create the file containing
+                                        the pod field
+                                      properties:
+                                        fieldRef:
+                                          description: 'Required: Selects a field
+                                            of the pod: only annotations, labels,
+                                            name, namespace and uid are supported.'
+                                          properties:
+                                            apiVersion:
+                                              description: Version of the schema the
+                                                FieldPath is written in terms of,
+                                                defaults to "v1".
+                                              type: string
+                                            fieldPath:
+                                              description: Path of the field to select
+                                                in the specified API version.
+                                              type: string
+                                          required:
+                                          - fieldPath
+                                          type: object
+                                          x-kubernetes-map-type: atomic
+                                        mode:
+                                          description: |-
+                                            Optional: mode bits used to set permissions on this file, must be an octal value
+                                            between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: 'Required: Path is  the relative
+                                            path name of the file to be created. Must
+                                            not be absolute or contain the ''..''
+                                            path. Must be utf-8 encoded. The first
+                                            item of the relative path must not start
+                                            with ''..'''
+                                          type: string
+                                        resourceFieldRef:
+                                          description: |-
+                                            Selects a resource of the container: only resources limits and requests
+                                            (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.
+                                          properties:
+                                            containerName:
+                                              description: 'Container name: required
+                                                for volumes, optional for env vars'
+                                              type: string
+                                            divisor:
+                                              anyOf:
+                                              - type: integer
+                                              - type: string
+                                              description: Specifies the output format
+                                                of the exposed resources, defaults
+                                                to "1"
+                                              pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                                              x-kubernetes-int-or-string: true
+                                            resource:
+                                              description: 'Required: resource to
+                                                select'
+                                              type: string
+                                          required:
+                                          - resource
+                                          type: object
+                                          x-kubernetes-map-type: atomic
+                                      required:
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                type: object
+                              podCertificate:
+                                description: |-
+                                  Projects an auto-rotating credential bundle (private key and certificate
+                                  chain) that the pod can use either as a TLS client or server.
+
+                                  Kubelet generates a private key and uses it to send a
+                                  PodCertificateRequest to the named signer.  Once the signer approves the
+                                  request and issues a certificate chain, Kubelet writes the key and
+                                  certificate chain to the pod filesystem.  The pod does not start until
+                                  certificates have been issued for each podCertificate projected volume
+                                  source in its spec.
+
+                                  Kubelet will begin trying to rotate the certificate at the time indicated
+                                  by the signer using the PodCertificateRequest.Status.BeginRefreshAt
+                                  timestamp.
+
+                                  Kubelet can write a single file, indicated by the credentialBundlePath
+                                  field, or separate files, indicated by the keyPath and
+                                  certificateChainPath fields.
+
+                                  The credential bundle is a single file in PEM format.  The first PEM
+                                  entry is the private key (in PKCS#8 format), and the remaining PEM
+                                  entries are the certificate chain issued by the signer (typically,
+                                  signers will return their certificate chain in leaf-to-root order).
+
+                                  Prefer using the credential bundle format, since your application code
+                                  can read it atomically.  If you use keyPath and certificateChainPath,
+                                  your application must make two separate file reads. If these coincide
+                                  with a certificate rotation, it is possible that the private key and leaf
+                                  certificate you read may not correspond to each other.  Your application
+                                  will need to check for this condition, and re-read until they are
+                                  consistent.
+
+                                  The named signer controls chooses the format of the certificate it
+                                  issues; consult the signer implementation's documentation to learn how to
+                                  use the certificates it issues.
+                                properties:
+                                  certificateChainPath:
+                                    description: |-
+                                      Write the certificate chain at this path in the projected volume.
+
+                                      Most applications should use credentialBundlePath.  When using keyPath
+                                      and certificateChainPath, your application needs to check that the key
+                                      and leaf certificate are consistent, because it is possible to read the
+                                      files mid-rotation.
+                                    type: string
+                                  credentialBundlePath:
+                                    description: |-
+                                      Write the credential bundle at this path in the projected volume.
+
+                                      The credential bundle is a single file that contains multiple PEM blocks.
+                                      The first PEM block is a PRIVATE KEY block, containing a PKCS#8 private
+                                      key.
+
+                                      The remaining blocks are CERTIFICATE blocks, containing the issued
+                                      certificate chain from the signer (leaf and any intermediates).
+
+                                      Using credentialBundlePath lets your Pod's application code make a single
+                                      atomic read that retrieves a consistent key and certificate chain.  If you
+                                      project them to separate files, your application code will need to
+                                      additionally check that the leaf certificate was issued to the key.
+                                    type: string
+                                  keyPath:
+                                    description: |-
+                                      Write the key at this path in the projected volume.
+
+                                      Most applications should use credentialBundlePath.  When using keyPath
+                                      and certificateChainPath, your application needs to check that the key
+                                      and leaf certificate are consistent, because it is possible to read the
+                                      files mid-rotation.
+                                    type: string
+                                  keyType:
+                                    description: |-
+                                      The type of keypair Kubelet will generate for the pod.
+
+                                      Valid values are "RSA3072", "RSA4096", "ECDSAP256", "ECDSAP384",
+                                      "ECDSAP521", and "ED25519".
+                                    type: string
+                                  maxExpirationSeconds:
+                                    description: |-
+                                      maxExpirationSeconds is the maximum lifetime permitted for the
+                                      certificate.
+
+                                      Kubelet copies this value verbatim into the PodCertificateRequests it
+                                      generates for this projection.
+
+                                      If omitted, kube-apiserver will set it to 86400(24 hours). kube-apiserver
+                                      will reject values shorter than 3600 (1 hour).  The maximum allowable
+                                      value is 7862400 (91 days).
+
+                                      The signer implementation is then free to issue a certificate with any
+                                      lifetime *shorter* than MaxExpirationSeconds, but no shorter than 3600
+                                      seconds (1 hour).  This constraint is enforced by kube-apiserver.
+                                      `kubernetes.io` signers will never issue certificates with a lifetime
+                                      longer than 24 hours.
+                                    format: int32
+                                    type: integer
+                                  signerName:
+                                    description: Kubelet's generated CSRs will be
+                                      addressed to this signer.
+                                    type: string
+                                  userAnnotations:
+                                    additionalProperties:
+                                      type: string
+                                    description: |-
+                                      userAnnotations allow pod authors to pass additional information to
+                                      the signer implementation.  Kubernetes does not restrict or validate this
+                                      metadata in any way.
+
+                                      These values are copied verbatim into the `spec.unverifiedUserAnnotations` field of
+                                      the PodCertificateRequest objects that Kubelet creates.
+
+                                      Entries are subject to the same validation as object metadata annotations,
+                                      with the addition that all keys must be domain-prefixed. No restrictions
+                                      are placed on values, except an overall size limitation on the entire field.
+
+                                      Signers should document the keys and values they support. Signers should
+                                      deny requests that contain keys they do not recognize.
+                                    type: object
+                                required:
+                                - keyType
+                                - signerName
+                                type: object
+                              secret:
+                                description: secret information about the secret data
+                                  to project
+                                properties:
+                                  items:
+                                    description: |-
+                                      items if unspecified, each key-value pair in the Data field of the referenced
+                                      Secret will be projected into the volume as a file whose name is the
+                                      key and content is the value. If specified, the listed keys will be
+                                      projected into the specified paths, and unlisted keys will not be
+                                      present. If a key is specified which is not present in the Secret,
+                                      the volume setup will error unless it is marked optional. Paths must be
+                                      relative and may not contain the '..' path or start with '..'.
+                                    items:
+                                      description: Maps a string key to a path within
+                                        a volume.
+                                      properties:
+                                        key:
+                                          description: key is the key to project.
+                                          type: string
+                                        mode:
+                                          description: |-
+                                            mode is Optional: mode bits used to set permissions on this file.
+                                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                            YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                            If not specified, the volume defaultMode will be used.
+                                            This might be in conflict with other options that affect the file
+                                            mode, like fsGroup, and the result can be other mode bits set.
+                                          format: int32
+                                          type: integer
+                                        path:
+                                          description: |-
+                                            path is the relative path of the file to map the key to.
+                                            May not be an absolute path.
+                                            May not contain the path element '..'.
+                                            May not start with the string '..'.
+                                          type: string
+                                      required:
+                                      - key
+                                      - path
+                                      type: object
+                                    type: array
+                                    x-kubernetes-list-type: atomic
+                                  name:
+                                    default: ""
+                                    description: |-
+                                      Name of the referent.
+                                      This field is effectively required, but due to backwards compatibility is
+                                      allowed to be empty. Instances of this type with an empty value here are
+                                      almost certainly wrong.
+                                      More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                                    type: string
+                                  optional:
+                                    description: optional field specify whether the
+                                      Secret or its key must be defined
+                                    type: boolean
+                                type: object
+                                x-kubernetes-map-type: atomic
+                              serviceAccountToken:
+                                description: serviceAccountToken is information about
+                                  the serviceAccountToken data to project
+                                properties:
+                                  audience:
+                                    description: |-
+                                      audience is the intended audience of the token. A recipient of a token
+                                      must identify itself with an identifier specified in the audience of the
+                                      token, and otherwise should reject the token. The audience defaults to the
+                                      identifier of the apiserver.
+                                    type: string
+                                  expirationSeconds:
+                                    description: |-
+                                      expirationSeconds is the requested duration of validity of the service
+                                      account token. As the token approaches expiration, the kubelet volume
+                                      plugin will proactively rotate the service account token. The kubelet will
+                                      start trying to rotate the token if the token is older than 80 percent of
+                                      its time to live or if the token is older than 24 hours.Defaults to 1 hour
+                                      and must be at least 10 minutes.
+                                    format: int64
+                                    type: integer
+                                  path:
+                                    description: |-
+                                      path is the path relative to the mount point of the file to project the
+                                      token into.
+                                    type: string
+                                required:
+                                - path
+                                type: object
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                      type: object
+                    quobyte:
+                      description: |-
+                        quobyte represents a Quobyte mount on the host that shares a pod's lifetime.
+                        Deprecated: Quobyte is deprecated and the in-tree quobyte type is no longer supported.
+                      properties:
+                        group:
+                          description: |-
+                            group to map volume access to
+                            Default is no group
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the Quobyte volume to be mounted with read-only permissions.
+                            Defaults to false.
+                          type: boolean
+                        registry:
+                          description: |-
+                            registry represents a single or multiple Quobyte Registry services
+                            specified as a string as host:port pair (multiple entries are separated with commas)
+                            which acts as the central registry for volumes
+                          type: string
+                        tenant:
+                          description: |-
+                            tenant owning the given Quobyte volume in the Backend
+                            Used with dynamically provisioned Quobyte volumes, value is set by the plugin
+                          type: string
+                        user:
+                          description: |-
+                            user to map volume access to
+                            Defaults to serivceaccount user
+                          type: string
+                        volume:
+                          description: volume is a string that references an already
+                            created Quobyte volume by name.
+                          type: string
+                      required:
+                      - registry
+                      - volume
+                      type: object
+                    rbd:
+                      description: |-
+                        rbd represents a Rados Block Device mount on the host that shares a pod's lifetime.
+                        Deprecated: RBD is deprecated and the in-tree rbd type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type of the volume that you want to mount.
+                            Tip: Ensure that the filesystem type is supported by the host operating system.
+                            Examples: "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#rbd
+                          type: string
+                        image:
+                          description: |-
+                            image is the rados image name.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        keyring:
+                          default: /etc/ceph/keyring
+                          description: |-
+                            keyring is the path to key ring for RBDUser.
+                            Default is /etc/ceph/keyring.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        monitors:
+                          description: |-
+                            monitors is a collection of Ceph monitors.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          items:
+                            type: string
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        pool:
+                          default: rbd
+                          description: |-
+                            pool is the rados pool name.
+                            Default is rbd.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly here will force the ReadOnly setting in VolumeMounts.
+                            Defaults to false.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef is name of the authentication secret for RBDUser. If provided
+                            overrides keyring.
+                            Default is nil.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        user:
+                          default: admin
+                          description: |-
+                            user is the rados user name.
+                            Default is admin.
+                            More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it
+                          type: string
+                      required:
+                      - image
+                      - monitors
+                      type: object
+                    scaleIO:
+                      description: |-
+                        scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes.
+                        Deprecated: ScaleIO is deprecated and the in-tree scaleIO type is no longer supported.
+                      properties:
+                        fsType:
+                          default: xfs
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs".
+                            Default is "xfs".
+                          type: string
+                        gateway:
+                          description: gateway is the host address of the ScaleIO
+                            API Gateway.
+                          type: string
+                        protectionDomain:
+                          description: protectionDomain is the name of the ScaleIO
+                            Protection Domain for the configured storage.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly Defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef references to the secret for ScaleIO user and other
+                            sensitive information. If this is not provided, Login operation will fail.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        sslEnabled:
+                          description: sslEnabled Flag enable/disable SSL communication
+                            with Gateway, default false
+                          type: boolean
+                        storageMode:
+                          default: ThinProvisioned
+                          description: |-
+                            storageMode indicates whether the storage for a volume should be ThickProvisioned or ThinProvisioned.
+                            Default is ThinProvisioned.
+                          type: string
+                        storagePool:
+                          description: storagePool is the ScaleIO Storage Pool associated
+                            with the protection domain.
+                          type: string
+                        system:
+                          description: system is the name of the storage system as
+                            configured in ScaleIO.
+                          type: string
+                        volumeName:
+                          description: |-
+                            volumeName is the name of a volume already created in the ScaleIO system
+                            that is associated with this volume source.
+                          type: string
+                      required:
+                      - gateway
+                      - secretRef
+                      - system
+                      type: object
+                    secret:
+                      description: |-
+                        secret represents a secret that should populate this volume.
+                        More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
+                      properties:
+                        defaultMode:
+                          description: |-
+                            defaultMode is Optional: mode bits used to set permissions on created files by default.
+                            Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                            YAML accepts both octal and decimal values, JSON requires decimal values
+                            for mode bits. Defaults to 0644.
+                            Directories within the path are not affected by this setting.
+                            This might be in conflict with other options that affect the file
+                            mode, like fsGroup, and the result can be other mode bits set.
+                          format: int32
+                          type: integer
+                        items:
+                          description: |-
+                            items If unspecified, each key-value pair in the Data field of the referenced
+                            Secret will be projected into the volume as a file whose name is the
+                            key and content is the value. If specified, the listed keys will be
+                            projected into the specified paths, and unlisted keys will not be
+                            present. If a key is specified which is not present in the Secret,
+                            the volume setup will error unless it is marked optional. Paths must be
+                            relative and may not contain the '..' path or start with '..'.
+                          items:
+                            description: Maps a string key to a path within a volume.
+                            properties:
+                              key:
+                                description: key is the key to project.
+                                type: string
+                              mode:
+                                description: |-
+                                  mode is Optional: mode bits used to set permissions on this file.
+                                  Must be an octal value between 0000 and 0777 or a decimal value between 0 and 511.
+                                  YAML accepts both octal and decimal values, JSON requires decimal values for mode bits.
+                                  If not specified, the volume defaultMode will be used.
+                                  This might be in conflict with other options that affect the file
+                                  mode, like fsGroup, and the result can be other mode bits set.
+                                format: int32
+                                type: integer
+                              path:
+                                description: |-
+                                  path is the relative path of the file to map the key to.
+                                  May not be an absolute path.
+                                  May not contain the path element '..'.
+                                  May not start with the string '..'.
+                                type: string
+                            required:
+                            - key
+                            - path
+                            type: object
+                          type: array
+                          x-kubernetes-list-type: atomic
+                        optional:
+                          description: optional field specify whether the Secret or
+                            its keys must be defined
+                          type: boolean
+                        secretName:
+                          description: |-
+                            secretName is the name of the secret in the pod's namespace to use.
+                            More info: https://kubernetes.io/docs/concepts/storage/volumes#secret
+                          type: string
+                      type: object
+                    storageos:
+                      description: |-
+                        storageOS represents a StorageOS volume attached and mounted on Kubernetes nodes.
+                        Deprecated: StorageOS is deprecated and the in-tree storageos type is no longer supported.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is the filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        readOnly:
+                          description: |-
+                            readOnly defaults to false (read/write). ReadOnly here will force
+                            the ReadOnly setting in VolumeMounts.
+                          type: boolean
+                        secretRef:
+                          description: |-
+                            secretRef specifies the secret to use for obtaining the StorageOS API
+                            credentials.  If not specified, default values will be attempted.
+                          properties:
+                            name:
+                              default: ""
+                              description: |-
+                                Name of the referent.
+                                This field is effectively required, but due to backwards compatibility is
+                                allowed to be empty. Instances of this type with an empty value here are
+                                almost certainly wrong.
+                                More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names
+                              type: string
+                          type: object
+                          x-kubernetes-map-type: atomic
+                        volumeName:
+                          description: |-
+                            volumeName is the human-readable name of the StorageOS volume.  Volume
+                            names are only unique within a namespace.
+                          type: string
+                        volumeNamespace:
+                          description: |-
+                            volumeNamespace specifies the scope of the volume within StorageOS.  If no
+                            namespace is specified then the Pod's namespace will be used.  This allows the
+                            Kubernetes name scoping to be mirrored within StorageOS for tighter integration.
+                            Set VolumeName to any name to override the default behaviour.
+                            Set to "default" if you are not using namespaces within StorageOS.
+                            Namespaces that do not pre-exist within StorageOS will be created.
+                          type: string
+                      type: object
+                    vsphereVolume:
+                      description: |-
+                        vsphereVolume represents a vSphere volume attached and mounted on kubelets host machine.
+                        Deprecated: VsphereVolume is deprecated. All operations for the in-tree vsphereVolume type
+                        are redirected to the csi.vsphere.vmware.com CSI driver.
+                      properties:
+                        fsType:
+                          description: |-
+                            fsType is filesystem type to mount.
+                            Must be a filesystem type supported by the host operating system.
+                            Ex. "ext4", "xfs", "ntfs". Implicitly inferred to be "ext4" if unspecified.
+                          type: string
+                        storagePolicyID:
+                          description: storagePolicyID is the storage Policy Based
+                            Management (SPBM) profile ID associated with the StoragePolicyName.
+                          type: string
+                        storagePolicyName:
+                          description: storagePolicyName is the storage Policy Based
+                            Management (SPBM) profile name.
+                          type: string
+                        volumePath:
+                          description: volumePath is the path that identifies vSphere
+                            volume vmdk
+                          type: string
+                      required:
+                      - volumePath
+                      type: object
+                  required:
+                  - name
+                  type: object
+                type: array
+            required:
+            - l1
+            type: object
+          status:
+            description: status defines the observed state of LMCacheEngine.
+            properties:
+              conditions:
+                description: conditions represent the current state of the LMCacheEngine
+                  resource.
+                items:
+                  description: Condition contains details for one aspect of the current
+                    state of this API Resource.
+                  properties:
+                    lastTransitionTime:
+                      description: |-
+                        lastTransitionTime is the last time the condition transitioned from one status to another.
+                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
+                      format: date-time
+                      type: string
+                    message:
+                      description: |-
+                        message is a human readable message indicating details about the transition.
+                        This may be an empty string.
+                      maxLength: 32768
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
+                        with respect to the current state of the instance.
+                      format: int64
+                      minimum: 0
+                      type: integer
+                    reason:
+                      description: |-
+                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        Producers of specific condition types may define expected values and meanings for this field,
+                        and whether the values are considered a guaranteed API.
+                        The value should be a CamelCase string.
+                        This field may not be empty.
+                      maxLength: 1024
+                      minLength: 1
+                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      type: string
+                    status:
+                      description: status of the condition, one of True, False, Unknown.
+                      enum:
+                      - "True"
+                      - "False"
+                      - Unknown
+                      type: string
+                    type:
+                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
+                      maxLength: 316
+                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
+                      type: string
+                  required:
+                  - lastTransitionTime
+                  - message
+                  - reason
+                  - status
+                  - type
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - type
+                x-kubernetes-list-type: map
+              desiredInstances:
+                description: desiredInstances is the number of desired instances.
+                format: int32
+                type: integer
+              endpoints:
+                description: endpoints lists per-node connection info.
+                items:
+                  description: EndpointStatus represents a single LMCache instance
+                    endpoint.
+                  properties:
+                    hostIP:
+                      description: hostIP is the IP address of the host.
+                      type: string
+                    metricsPort:
+                      description: metricsPort is the Prometheus metrics port.
+                      format: int32
+                      type: integer
+                    nodeName:
+                      description: nodeName is the name of the node running this instance.
+                      type: string
+                    podName:
+                      description: podName is the name of the pod.
+                      type: string
+                    port:
+                      description: port is the server port.
+                      format: int32
+                      type: integer
+                    ready:
+                      description: ready indicates whether this instance is ready.
+                      type: boolean
+                  required:
+                  - hostIP
+                  - metricsPort
+                  - nodeName
+                  - podName
+                  - port
+                  - ready
+                  type: object
+                type: array
+              observedGeneration:
+                description: observedGeneration is the most recent generation observed.
+                format: int64
+                type: integer
+              phase:
+                description: phase is the overall phase of the LMCacheEngine.
+                type: string
+              readyInstances:
+                description: readyInstances is the number of ready instances.
+                format: int32
+                type: integer
+            type: object
+        required:
+        - spec
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}
diff --git a/operator/config/crd/kustomization.yaml b/operator/config/crd/kustomization.yaml
new file mode 100644
index 0000000..4209d64
--- /dev/null
+++ b/operator/config/crd/kustomization.yaml
@@ -0,0 +1,18 @@
+# This kustomization.yaml is not intended to be run by itself,
+# since it depends on service name and namespace that are out of this kustomize package.
+# It should be run by config/default
+resources:
+- bases/lmcache.lmcache.ai_lmcacheengines.yaml
+- bases/lmcache.lmcache.ai_cacheblendengines.yaml
+- bases/lmcache.lmcache.ai_lmcachecoordinators.yaml
+# +kubebuilder:scaffold:crdkustomizeresource
+
+patches:
+# [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix.
+# patches here are for enabling the conversion webhook for each CRD
+# +kubebuilder:scaffold:crdkustomizewebhookpatch
+
+# [WEBHOOK] To enable webhook, uncomment the following section
+# the following config is for teaching kustomize how to do kustomization for CRDs.
+configurations:
+- kustomizeconfig.yaml
diff --git a/operator/config/crd/kustomizeconfig.yaml b/operator/config/crd/kustomizeconfig.yaml
new file mode 100644
index 0000000..61361ff
--- /dev/null
+++ b/operator/config/crd/kustomizeconfig.yaml
@@ -0,0 +1,12 @@
+# This file is for teaching kustomize how to substitute name and namespace reference in CRD
+nameReference:
+- kind: Service
+  version: v1
+  fieldSpecs:
+  - kind: CustomResourceDefinition
+    version: v1
+    group: apiextensions.k8s.io
+    path: spec/conversion/webhook/clientConfig/service/name
+
+varReference:
+- path: metadata/annotations
diff --git a/operator/config/default/cert_metrics_manager_patch.yaml b/operator/config/default/cert_metrics_manager_patch.yaml
new file mode 100644
index 0000000..d975015
--- /dev/null
+++ b/operator/config/default/cert_metrics_manager_patch.yaml
@@ -0,0 +1,30 @@
+# This patch adds the args, volumes, and ports to allow the manager to use the metrics-server certs.
+
+# Add the volumeMount for the metrics-server certs
+- op: add
+  path: /spec/template/spec/containers/0/volumeMounts/-
+  value:
+    mountPath: /tmp/k8s-metrics-server/metrics-certs
+    name: metrics-certs
+    readOnly: true
+
+# Add the --metrics-cert-path argument for the metrics server
+- op: add
+  path: /spec/template/spec/containers/0/args/-
+  value: --metrics-cert-path=/tmp/k8s-metrics-server/metrics-certs
+
+# Add the metrics-server certs volume configuration
+- op: add
+  path: /spec/template/spec/volumes/-
+  value:
+    name: metrics-certs
+    secret:
+      secretName: metrics-server-cert
+      optional: false
+      items:
+        - key: ca.crt
+          path: ca.crt
+        - key: tls.crt
+          path: tls.crt
+        - key: tls.key
+          path: tls.key
diff --git a/operator/config/default/kustomization.yaml b/operator/config/default/kustomization.yaml
new file mode 100644
index 0000000..19bf3c8
--- /dev/null
+++ b/operator/config/default/kustomization.yaml
@@ -0,0 +1,234 @@
+# Adds namespace to all resources.
+namespace: lmcache-operator-system
+
+# Value of this field is prepended to the
+# names of all resources, e.g. a deployment named
+# "wordpress" becomes "alices-wordpress".
+# Note that it should also match with the prefix (text before '-') of the namespace
+# field above.
+namePrefix: lmcache-operator-
+
+# Labels to add to all resources and selectors.
+#labels:
+#- includeSelectors: true
+#  pairs:
+#    someName: someValue
+
+resources:
+- ../crd
+- ../rbac
+- ../manager
+# [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix including the one in
+# crd/kustomization.yaml
+- ../webhook
+# [CERTMANAGER] To enable cert-manager, uncomment all sections with 'CERTMANAGER'. 'WEBHOOK' components are required.
+- ../certmanager
+# [PROMETHEUS] To enable prometheus monitor, uncomment all sections with 'PROMETHEUS'.
+#- ../prometheus
+# [METRICS] Expose the controller manager metrics service.
+- metrics_service.yaml
+# [NETWORK POLICY] Protect the /metrics endpoint and Webhook Server with NetworkPolicy.
+# Only Pod(s) running a namespace labeled with 'metrics: enabled' will be able to gather the metrics.
+# Only CR(s) which requires webhooks and are applied on namespaces labeled with 'webhooks: enabled' will
+# be able to communicate with the Webhook Server.
+#- ../network-policy
+
+# Uncomment the patches line if you enable Metrics
+patches:
+# [METRICS] The following patch will enable the metrics endpoint using HTTPS and the port :8443.
+# More info: https://book.kubebuilder.io/reference/metrics
+- path: manager_metrics_patch.yaml
+  target:
+    kind: Deployment
+
+# Uncomment the patches line if you enable Metrics and CertManager
+# [METRICS-WITH-CERTS] To enable metrics protected with certManager, uncomment the following line.
+# This patch will protect the metrics with certManager self-signed certs.
+#- path: cert_metrics_manager_patch.yaml
+#  target:
+#    kind: Deployment
+
+# [WEBHOOK] To enable webhook, uncomment all the sections with [WEBHOOK] prefix including the one in
+# crd/kustomization.yaml
+- path: manager_webhook_patch.yaml
+  target:
+    kind: Deployment
+
+# [CERTMANAGER] To enable cert-manager, uncomment all sections with 'CERTMANAGER' prefix.
+# Uncomment the following replacements to add the cert-manager CA injection annotations
+replacements:
+# - source: # Uncomment the following block to enable certificates for metrics
+#     kind: Service
+#     version: v1
+#     name: controller-manager-metrics-service
+#     fieldPath: metadata.name
+#   targets:
+#     - select:
+#         kind: Certificate
+#         group: cert-manager.io
+#         version: v1
+#         name: metrics-certs
+#       fieldPaths:
+#         - spec.dnsNames.0
+#         - spec.dnsNames.1
+#       options:
+#         delimiter: '.'
+#         index: 0
+#         create: true
+#     - select: # Uncomment the following to set the Service name for TLS config in Prometheus ServiceMonitor
+#         kind: ServiceMonitor
+#         group: monitoring.coreos.com
+#         version: v1
+#         name: controller-manager-metrics-monitor
+#       fieldPaths:
+#         - spec.endpoints.0.tlsConfig.serverName
+#       options:
+#         delimiter: '.'
+#         index: 0
+#         create: true
+
+# - source:
+#     kind: Service
+#     version: v1
+#     name: controller-manager-metrics-service
+#     fieldPath: metadata.namespace
+#   targets:
+#     - select:
+#         kind: Certificate
+#         group: cert-manager.io
+#         version: v1
+#         name: metrics-certs
+#       fieldPaths:
+#         - spec.dnsNames.0
+#         - spec.dnsNames.1
+#       options:
+#         delimiter: '.'
+#         index: 1
+#         create: true
+#     - select: # Uncomment the following to set the Service namespace for TLS in Prometheus ServiceMonitor
+#         kind: ServiceMonitor
+#         group: monitoring.coreos.com
+#         version: v1
+#         name: controller-manager-metrics-monitor
+#       fieldPaths:
+#         - spec.endpoints.0.tlsConfig.serverName
+#       options:
+#         delimiter: '.'
+#         index: 1
+#         create: true
+
+- source: # Uncomment the following block if you have any webhook
+    kind: Service
+    version: v1
+    name: webhook-service
+    fieldPath: .metadata.name # Name of the service
+  targets:
+    - select:
+        kind: Certificate
+        group: cert-manager.io
+        version: v1
+        name: serving-cert
+      fieldPaths:
+        - .spec.dnsNames.0
+        - .spec.dnsNames.1
+      options:
+        delimiter: '.'
+        index: 0
+        create: true
+- source:
+    kind: Service
+    version: v1
+    name: webhook-service
+    fieldPath: .metadata.namespace # Namespace of the service
+  targets:
+    - select:
+        kind: Certificate
+        group: cert-manager.io
+        version: v1
+        name: serving-cert
+      fieldPaths:
+        - .spec.dnsNames.0
+        - .spec.dnsNames.1
+      options:
+        delimiter: '.'
+        index: 1
+        create: true
+
+# - source: # Uncomment the following block if you have a ValidatingWebhook (--programmatic-validation)
+#     kind: Certificate
+#     group: cert-manager.io
+#     version: v1
+#     name: serving-cert # This name should match the one in certificate.yaml
+#     fieldPath: .metadata.namespace # Namespace of the certificate CR
+#   targets:
+#     - select:
+#         kind: ValidatingWebhookConfiguration
+#       fieldPaths:
+#         - .metadata.annotations.[cert-manager.io/inject-ca-from]
+#       options:
+#         delimiter: '/'
+#         index: 0
+#         create: true
+# - source:
+#     kind: Certificate
+#     group: cert-manager.io
+#     version: v1
+#     name: serving-cert
+#     fieldPath: .metadata.name
+#   targets:
+#     - select:
+#         kind: ValidatingWebhookConfiguration
+#       fieldPaths:
+#         - .metadata.annotations.[cert-manager.io/inject-ca-from]
+#       options:
+#         delimiter: '/'
+#         index: 1
+#         create: true
+
+- source: # Uncomment the following block if you have a DefaultingWebhook (--defaulting )
+    kind: Certificate
+    group: cert-manager.io
+    version: v1
+    name: serving-cert
+    fieldPath: .metadata.namespace # Namespace of the certificate CR
+  targets:
+    - select:
+        kind: MutatingWebhookConfiguration
+      fieldPaths:
+        - .metadata.annotations.[cert-manager.io/inject-ca-from]
+      options:
+        delimiter: '/'
+        index: 0
+        create: true
+- source:
+    kind: Certificate
+    group: cert-manager.io
+    version: v1
+    name: serving-cert
+    fieldPath: .metadata.name
+  targets:
+    - select:
+        kind: MutatingWebhookConfiguration
+      fieldPaths:
+        - .metadata.annotations.[cert-manager.io/inject-ca-from]
+      options:
+        delimiter: '/'
+        index: 1
+        create: true
+
+# - source: # Uncomment the following block if you have a ConversionWebhook (--conversion)
+#     kind: Certificate
+#     group: cert-manager.io
+#     version: v1
+#     name: serving-cert
+#     fieldPath: .metadata.namespace # Namespace of the certificate CR
+#   targets: # Do not remove or uncomment the following scaffold marker; required to generate code for target CRD.
+# +kubebuilder:scaffold:crdkustomizecainjectionns
+# - source:
+#     kind: Certificate
+#     group: cert-manager.io
+#     version: v1
+#     name: serving-cert
+#     fieldPath: .metadata.name
+#   targets: # Do not remove or uncomment the following scaffold marker; required to generate code for target CRD.
+# +kubebuilder:scaffold:crdkustomizecainjectionname
diff --git a/operator/config/default/manager_metrics_patch.yaml b/operator/config/default/manager_metrics_patch.yaml
new file mode 100644
index 0000000..2aaef65
--- /dev/null
+++ b/operator/config/default/manager_metrics_patch.yaml
@@ -0,0 +1,4 @@
+# This patch adds the args to allow exposing the metrics endpoint using HTTPS
+- op: add
+  path: /spec/template/spec/containers/0/args/0
+  value: --metrics-bind-address=:8443
diff --git a/operator/config/default/manager_webhook_patch.yaml b/operator/config/default/manager_webhook_patch.yaml
new file mode 100644
index 0000000..bc918a3
--- /dev/null
+++ b/operator/config/default/manager_webhook_patch.yaml
@@ -0,0 +1,20 @@
+# This patch wires the webhook serving certificate into the controller-manager Deployment:
+# it tells the manager where to read the cert (the --webhook-cert-path arg consumed by
+# cmd/main.go), and mounts the cert-manager-managed secret (webhook-server-cert) read-only
+# at that path. The default cert file names (tls.crt / tls.key) match cmd/main.go's
+# --webhook-cert-name / --webhook-cert-key defaults.
+- op: add
+  path: /spec/template/spec/containers/0/args/-
+  value: --webhook-cert-path=/tmp/k8s-webhook-server/serving-certs
+- op: add
+  path: /spec/template/spec/containers/0/volumeMounts/-
+  value:
+    name: webhook-certs
+    mountPath: /tmp/k8s-webhook-server/serving-certs
+    readOnly: true
+- op: add
+  path: /spec/template/spec/volumes/-
+  value:
+    name: webhook-certs
+    secret:
+      secretName: webhook-server-cert
diff --git a/operator/config/default/metrics_service.yaml b/operator/config/default/metrics_service.yaml
new file mode 100644
index 0000000..1f4155a
--- /dev/null
+++ b/operator/config/default/metrics_service.yaml
@@ -0,0 +1,18 @@
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    control-plane: controller-manager
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: controller-manager-metrics-service
+  namespace: system
+spec:
+  ports:
+  - name: https
+    port: 8443
+    protocol: TCP
+    targetPort: 8443
+  selector:
+    control-plane: controller-manager
+    app.kubernetes.io/name: operator
diff --git a/operator/config/manager/kustomization.yaml b/operator/config/manager/kustomization.yaml
new file mode 100644
index 0000000..480fe25
--- /dev/null
+++ b/operator/config/manager/kustomization.yaml
@@ -0,0 +1,8 @@
+resources:
+- manager.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+images:
+- name: controller
+  newName: lmcache/lmcache-operator
+  newTag: v0.1.1
diff --git a/operator/config/manager/manager.yaml b/operator/config/manager/manager.yaml
new file mode 100644
index 0000000..e8bc25f
--- /dev/null
+++ b/operator/config/manager/manager.yaml
@@ -0,0 +1,99 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  labels:
+    control-plane: controller-manager
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: system
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: controller-manager
+  namespace: system
+  labels:
+    control-plane: controller-manager
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+spec:
+  selector:
+    matchLabels:
+      control-plane: controller-manager
+      app.kubernetes.io/name: operator
+  replicas: 1
+  template:
+    metadata:
+      annotations:
+        kubectl.kubernetes.io/default-container: manager
+      labels:
+        control-plane: controller-manager
+        app.kubernetes.io/name: operator
+    spec:
+      # TODO(user): Uncomment the following code to configure the nodeAffinity expression
+      # according to the platforms which are supported by your solution.
+      # It is considered best practice to support multiple architectures. You can
+      # build your manager image using the makefile target docker-buildx.
+      # affinity:
+      #   nodeAffinity:
+      #     requiredDuringSchedulingIgnoredDuringExecution:
+      #       nodeSelectorTerms:
+      #         - matchExpressions:
+      #           - key: kubernetes.io/arch
+      #             operator: In
+      #             values:
+      #               - amd64
+      #               - arm64
+      #               - ppc64le
+      #               - s390x
+      #           - key: kubernetes.io/os
+      #             operator: In
+      #             values:
+      #               - linux
+      securityContext:
+        # Projects are configured by default to adhere to the "restricted" Pod Security Standards.
+        # This ensures that deployments meet the highest security requirements for Kubernetes.
+        # For more details, see: https://kubernetes.io/docs/concepts/security/pod-security-standards/#restricted
+        runAsNonRoot: true
+        seccompProfile:
+          type: RuntimeDefault
+      containers:
+      - command:
+        - /manager
+        args:
+          - --leader-elect
+          - --health-probe-bind-address=:8081
+        image: controller:latest
+        name: manager
+        ports: []
+        securityContext:
+          readOnlyRootFilesystem: true
+          allowPrivilegeEscalation: false
+          capabilities:
+            drop:
+            - "ALL"
+        livenessProbe:
+          httpGet:
+            path: /healthz
+            port: 8081
+          initialDelaySeconds: 15
+          periodSeconds: 20
+        readinessProbe:
+          httpGet:
+            path: /readyz
+            port: 8081
+          initialDelaySeconds: 5
+          periodSeconds: 10
+        # TODO(user): Configure the resources accordingly based on the project requirements.
+        # More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+        resources:
+          limits:
+            cpu: 500m
+            memory: 128Mi
+          requests:
+            cpu: 10m
+            memory: 64Mi
+        volumeMounts: []
+      volumes: []
+      serviceAccountName: controller-manager
+      terminationGracePeriodSeconds: 10
diff --git a/operator/config/network-policy/allow-metrics-traffic.yaml b/operator/config/network-policy/allow-metrics-traffic.yaml
new file mode 100644
index 0000000..d3ac983
--- /dev/null
+++ b/operator/config/network-policy/allow-metrics-traffic.yaml
@@ -0,0 +1,27 @@
+# This NetworkPolicy allows ingress traffic
+# with Pods running on namespaces labeled with 'metrics: enabled'. Only Pods on those
+# namespaces are able to gather data from the metrics endpoint.
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: allow-metrics-traffic
+  namespace: system
+spec:
+  podSelector:
+    matchLabels:
+      control-plane: controller-manager
+      app.kubernetes.io/name: operator
+  policyTypes:
+    - Ingress
+  ingress:
+    # This allows ingress traffic from any namespace with the label metrics: enabled
+    - from:
+      - namespaceSelector:
+          matchLabels:
+            metrics: enabled  # Only from namespaces with this label
+      ports:
+        - port: 8443
+          protocol: TCP
diff --git a/operator/config/network-policy/kustomization.yaml b/operator/config/network-policy/kustomization.yaml
new file mode 100644
index 0000000..ec0fb5e
--- /dev/null
+++ b/operator/config/network-policy/kustomization.yaml
@@ -0,0 +1,2 @@
+resources:
+- allow-metrics-traffic.yaml
diff --git a/operator/config/prometheus/kustomization.yaml b/operator/config/prometheus/kustomization.yaml
new file mode 100644
index 0000000..fdc5481
--- /dev/null
+++ b/operator/config/prometheus/kustomization.yaml
@@ -0,0 +1,11 @@
+resources:
+- monitor.yaml
+
+# [PROMETHEUS-WITH-CERTS] The following patch configures the ServiceMonitor in ../prometheus
+# to securely reference certificates created and managed by cert-manager.
+# Additionally, ensure that you uncomment the [METRICS WITH CERTMANAGER] patch under config/default/kustomization.yaml
+# to mount the "metrics-server-cert" secret in the Manager Deployment.
+#patches:
+#  - path: monitor_tls_patch.yaml
+#    target:
+#      kind: ServiceMonitor
diff --git a/operator/config/prometheus/monitor.yaml b/operator/config/prometheus/monitor.yaml
new file mode 100644
index 0000000..b73583e
--- /dev/null
+++ b/operator/config/prometheus/monitor.yaml
@@ -0,0 +1,27 @@
+# Prometheus Monitor Service (Metrics)
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  labels:
+    control-plane: controller-manager
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: controller-manager-metrics-monitor
+  namespace: system
+spec:
+  endpoints:
+    - path: /metrics
+      port: https # Ensure this is the name of the port that exposes HTTPS metrics
+      scheme: https
+      bearerTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
+      tlsConfig:
+        # TODO(user): The option insecureSkipVerify: true is not recommended for production since it disables
+        # certificate verification, exposing the system to potential man-in-the-middle attacks.
+        # For production environments, it is recommended to use cert-manager for automatic TLS certificate management.
+        # To apply this configuration, enable cert-manager and use the patch located at config/prometheus/servicemonitor_tls_patch.yaml,
+        # which securely references the certificate from the 'metrics-server-cert' secret.
+        insecureSkipVerify: true
+  selector:
+    matchLabels:
+      control-plane: controller-manager
+      app.kubernetes.io/name: operator
diff --git a/operator/config/prometheus/monitor_tls_patch.yaml b/operator/config/prometheus/monitor_tls_patch.yaml
new file mode 100644
index 0000000..5bf84ce
--- /dev/null
+++ b/operator/config/prometheus/monitor_tls_patch.yaml
@@ -0,0 +1,19 @@
+# Patch for Prometheus ServiceMonitor to enable secure TLS configuration
+# using certificates managed by cert-manager
+- op: replace
+  path: /spec/endpoints/0/tlsConfig
+  value:
+    # SERVICE_NAME and SERVICE_NAMESPACE will be substituted by kustomize
+    serverName: SERVICE_NAME.SERVICE_NAMESPACE.svc
+    insecureSkipVerify: false
+    ca:
+      secret:
+        name: metrics-server-cert
+        key: ca.crt
+    cert:
+      secret:
+        name: metrics-server-cert
+        key: tls.crt
+    keySecret:
+      name: metrics-server-cert
+      key: tls.key
diff --git a/operator/config/rbac/kustomization.yaml b/operator/config/rbac/kustomization.yaml
new file mode 100644
index 0000000..abad38f
--- /dev/null
+++ b/operator/config/rbac/kustomization.yaml
@@ -0,0 +1,28 @@
+resources:
+# All RBAC will be applied under this service account in
+# the deployment namespace. You may comment out this resource
+# if your manager will use a service account that exists at
+# runtime. Be sure to update RoleBinding and ClusterRoleBinding
+# subjects if changing service account names.
+- service_account.yaml
+- role.yaml
+- role_binding.yaml
+- leader_election_role.yaml
+- leader_election_role_binding.yaml
+# The following RBAC configurations are used to protect
+# the metrics endpoint with authn/authz. These configurations
+# ensure that only authorized users and service accounts
+# can access the metrics endpoint. Comment the following
+# permissions if you want to disable this protection.
+# More info: https://book.kubebuilder.io/reference/metrics.html
+- metrics_auth_role.yaml
+- metrics_auth_role_binding.yaml
+- metrics_reader_role.yaml
+# For each CRD, "Admin", "Editor" and "Viewer" roles are scaffolded by
+# default, aiding admins in cluster management. Those roles are
+# not used by the operator itself. You can comment the following lines
+# if you do not want those helpers be installed with your Project.
+- lmcacheengine_admin_role.yaml
+- lmcacheengine_editor_role.yaml
+- lmcacheengine_viewer_role.yaml
+
diff --git a/operator/config/rbac/leader_election_role.yaml b/operator/config/rbac/leader_election_role.yaml
new file mode 100644
index 0000000..507e52b
--- /dev/null
+++ b/operator/config/rbac/leader_election_role.yaml
@@ -0,0 +1,40 @@
+# permissions to do leader election.
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: leader-election-role
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - configmaps
+  verbs:
+  - get
+  - list
+  - watch
+  - create
+  - update
+  - patch
+  - delete
+- apiGroups:
+  - coordination.k8s.io
+  resources:
+  - leases
+  verbs:
+  - get
+  - list
+  - watch
+  - create
+  - update
+  - patch
+  - delete
+- apiGroups:
+  - ""
+  resources:
+  - events
+  verbs:
+  - create
+  - patch
diff --git a/operator/config/rbac/leader_election_role_binding.yaml b/operator/config/rbac/leader_election_role_binding.yaml
new file mode 100644
index 0000000..c60ecc7
--- /dev/null
+++ b/operator/config/rbac/leader_election_role_binding.yaml
@@ -0,0 +1,15 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: leader-election-rolebinding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: leader-election-role
+subjects:
+- kind: ServiceAccount
+  name: controller-manager
+  namespace: system
diff --git a/operator/config/rbac/lmcacheengine_admin_role.yaml b/operator/config/rbac/lmcacheengine_admin_role.yaml
new file mode 100644
index 0000000..71f709e
--- /dev/null
+++ b/operator/config/rbac/lmcacheengine_admin_role.yaml
@@ -0,0 +1,27 @@
+# This rule is not used by the project operator itself.
+# It is provided to allow the cluster admin to help manage permissions for users.
+#
+# Grants full permissions ('*') over lmcache.lmcache.ai.
+# This role is intended for users authorized to modify roles and bindings within the cluster,
+# enabling them to delegate specific permissions to other users or groups as needed.
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: lmcacheengine-admin-role
+rules:
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - lmcacheengines
+  verbs:
+  - '*'
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - lmcacheengines/status
+  verbs:
+  - get
diff --git a/operator/config/rbac/lmcacheengine_editor_role.yaml b/operator/config/rbac/lmcacheengine_editor_role.yaml
new file mode 100644
index 0000000..862bd99
--- /dev/null
+++ b/operator/config/rbac/lmcacheengine_editor_role.yaml
@@ -0,0 +1,33 @@
+# This rule is not used by the project operator itself.
+# It is provided to allow the cluster admin to help manage permissions for users.
+#
+# Grants permissions to create, update, and delete resources within the lmcache.lmcache.ai.
+# This role is intended for users who need to manage these resources
+# but should not control RBAC or manage permissions for others.
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: lmcacheengine-editor-role
+rules:
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - lmcacheengines
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - lmcacheengines/status
+  verbs:
+  - get
diff --git a/operator/config/rbac/lmcacheengine_viewer_role.yaml b/operator/config/rbac/lmcacheengine_viewer_role.yaml
new file mode 100644
index 0000000..d36809f
--- /dev/null
+++ b/operator/config/rbac/lmcacheengine_viewer_role.yaml
@@ -0,0 +1,29 @@
+# This rule is not used by the project operator itself.
+# It is provided to allow the cluster admin to help manage permissions for users.
+#
+# Grants read-only access to lmcache.lmcache.ai resources.
+# This role is intended for users who need visibility into these resources
+# without permissions to modify them. It is ideal for monitoring purposes and limited-access viewing.
+
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: lmcacheengine-viewer-role
+rules:
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - lmcacheengines
+  verbs:
+  - get
+  - list
+  - watch
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - lmcacheengines/status
+  verbs:
+  - get
diff --git a/operator/config/rbac/metrics_auth_role.yaml b/operator/config/rbac/metrics_auth_role.yaml
new file mode 100644
index 0000000..32d2e4e
--- /dev/null
+++ b/operator/config/rbac/metrics_auth_role.yaml
@@ -0,0 +1,17 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: metrics-auth-role
+rules:
+- apiGroups:
+  - authentication.k8s.io
+  resources:
+  - tokenreviews
+  verbs:
+  - create
+- apiGroups:
+  - authorization.k8s.io
+  resources:
+  - subjectaccessreviews
+  verbs:
+  - create
diff --git a/operator/config/rbac/metrics_auth_role_binding.yaml b/operator/config/rbac/metrics_auth_role_binding.yaml
new file mode 100644
index 0000000..e775d67
--- /dev/null
+++ b/operator/config/rbac/metrics_auth_role_binding.yaml
@@ -0,0 +1,12 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: metrics-auth-rolebinding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: metrics-auth-role
+subjects:
+- kind: ServiceAccount
+  name: controller-manager
+  namespace: system
diff --git a/operator/config/rbac/metrics_reader_role.yaml b/operator/config/rbac/metrics_reader_role.yaml
new file mode 100644
index 0000000..51a75db
--- /dev/null
+++ b/operator/config/rbac/metrics_reader_role.yaml
@@ -0,0 +1,9 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: metrics-reader
+rules:
+- nonResourceURLs:
+  - "/metrics"
+  verbs:
+  - get
diff --git a/operator/config/rbac/role.yaml b/operator/config/rbac/role.yaml
new file mode 100644
index 0000000..10a149f
--- /dev/null
+++ b/operator/config/rbac/role.yaml
@@ -0,0 +1,85 @@
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: manager-role
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - configmaps
+  - secrets
+  - services
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - ""
+  resources:
+  - pods
+  verbs:
+  - get
+  - list
+  - watch
+- apiGroups:
+  - apps
+  resources:
+  - daemonsets
+  - deployments
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - cacheblendengines
+  - lmcachecoordinators
+  - lmcacheengines
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - cacheblendengines/finalizers
+  - lmcachecoordinators/finalizers
+  - lmcacheengines/finalizers
+  verbs:
+  - update
+- apiGroups:
+  - lmcache.lmcache.ai
+  resources:
+  - cacheblendengines/status
+  - lmcachecoordinators/status
+  - lmcacheengines/status
+  verbs:
+  - get
+  - patch
+  - update
+- apiGroups:
+  - monitoring.coreos.com
+  resources:
+  - servicemonitors
+  verbs:
+  - create
+  - delete
+  - get
+  - list
+  - patch
+  - update
+  - watch
diff --git a/operator/config/rbac/role_binding.yaml b/operator/config/rbac/role_binding.yaml
new file mode 100644
index 0000000..5d27960
--- /dev/null
+++ b/operator/config/rbac/role_binding.yaml
@@ -0,0 +1,15 @@
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: manager-rolebinding
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: manager-role
+subjects:
+- kind: ServiceAccount
+  name: controller-manager
+  namespace: system
diff --git a/operator/config/rbac/service_account.yaml b/operator/config/rbac/service_account.yaml
new file mode 100644
index 0000000..3567d2f
--- /dev/null
+++ b/operator/config/rbac/service_account.yaml
@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+  name: controller-manager
+  namespace: system
diff --git a/operator/config/samples/kustomization.yaml b/operator/config/samples/kustomization.yaml
new file mode 100644
index 0000000..5bdf0ff
--- /dev/null
+++ b/operator/config/samples/kustomization.yaml
@@ -0,0 +1,6 @@
+## Append samples of your project ##
+resources:
+- lmcache_v1alpha1_lmcacheengine.yaml
+- lmcache_v1alpha1_cacheblendengine.yaml
+- lmcache_v1alpha1_lmcachecoordinator.yaml
+# +kubebuilder:scaffold:manifestskustomizesamples
diff --git a/operator/config/samples/lmcache_v1alpha1_cacheblendengine.yaml b/operator/config/samples/lmcache_v1alpha1_cacheblendengine.yaml
new file mode 100644
index 0000000..fb78ed3
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_cacheblendengine.yaml
@@ -0,0 +1,94 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: CacheBlendEngine
+metadata:
+  name: my-cacheblend
+  namespace: default
+spec:
+  # -- Container image (the LMCache blend_v3 ENGINE image) --
+  # The engine runs `lmcache server --engine-type blend`. If this image lives
+  # in a PRIVATE registry, set imagePullSecrets (the Secret must exist in this
+  # namespace).
+  image:
+    repository: lmcache/vllm-openai # default
+    tag: latest-nightly # default
+    pullPolicy: IfNotPresent # Always | Never | IfNotPresent
+  # imagePullSecrets:
+  #   - name: my-registry-secret
+
+  # -- Server config --
+  # server:
+  #   port: 6566                  # MP port the CB connector dials (default 6566)
+  #   httpPort: 8080              # HTTP frontend port (health, admin)
+  #   chunkSize: 256              # FIXED at 256 (must equal vLLM --block-size * 4)
+  #   maxWorkers: 1               # default, worker threads
+  #   hashAlgorithm: blake3       # builtin | sha256_cbor | blake3
+
+  # -- L1 cache (REQUIRED) --
+  l1:
+    sizeGB: 60
+
+  # -- CacheBlend tunables (injected into the vLLM connector config) --
+  # blend:
+  #   checkLayer: 1               # default, cb.check_layer
+  #   recompRatio: 0.15           # default, cb.recomp_ratio
+
+  # -- Injection: how the webhook injects the plugin into annotated vLLM pods --
+  injection:
+    # payloadImage is the PRIVATE cacheblend-plugin init-container image (not
+    # open-source) — repository/tag/pullPolicy, like spec.image. Set repository
+    # to YOUR cacheblend-plugin image and pin the tag to the target vLLM/lmcache
+    # window. The webhook injects it as an init container into vLLM pods.
+    payloadImage:
+      repository: lmcache/cacheblend-plugin
+      tag: latest
+      pullPolicy: IfNotPresent             # Always | Never | IfNotPresent
+    # imagePullSecrets pulls the PRIVATE payload image. The webhook appends these
+    # to the vLLM pod's spec.imagePullSecrets — the Secret(s) must exist in the
+    # vLLM pod's namespace.
+    # imagePullSecrets:
+    #   - name: my-registry-secret
+    # targetContainer: ""          # default: first container; name the vLLM container
+    # cudagraph: eager             # eager | piecewise | full_decode_only (never full)
+
+  # -- Eviction --
+  # eviction:
+  #   policy: LRU                 # default (only supported value)
+  #   triggerWatermark: 0.8       # default, range (0.0, 1.0]
+  #   evictionRatio: 0.2          # default, range (0.0, 1.0]
+
+  # -- Prometheus monitoring --
+  # prometheus:
+  #   enabled: true               # default
+  #   port: 9090                  # default
+  #   serviceMonitor:
+  #     enabled: false            # default, requires Prometheus Operator
+
+  # -- Scheduling (place one engine per GPU node; vLLM pods must land on these nodes) --
+  # nodeSelector:
+  #   nvidia.com/gpu.present: "true"
+
+  # -- Logging --
+  # logLevel: INFO                # DEBUG | INFO | WARNING | ERROR
+
+  # -- Security --
+  # Run the engine container in privileged mode. Defaults to false. Set to true
+  # only on clusters where the engine cannot see the node GPUs otherwise
+  # (runtimeClassName: nvidia + NVIDIA_VISIBLE_DEVICES=all is enough on most).
+  # privileged: false
+
+# ---------------------------------------------------------------------------
+# To enable CacheBlend on a vLLM pod, label it for the webhook and annotate it
+# with this engine's name. The pod (and this engine) must run in a namespace
+# labeled `pod-security.kubernetes.io/enforce=privileged` (hostIPC is injected).
+#
+#   metadata:
+#     labels:
+#       lmcache.ai/cacheblend-inject: "true"
+#     annotations:
+#       lmcache.ai/cacheblend-engine: "my-cacheblend"
+#       # lmcache.ai/cacheblend-container: "vllm"          # optional
+#       # lmcache.ai/cacheblend-image-pull-secrets: "..."  # optional override
+#
+# The vLLM container must launch via the image ENTRYPOINT (args-only) — a
+# `command: ["/bin/sh","-c", ...]` wrapper is skipped (injection cannot reach it).
+# ---------------------------------------------------------------------------
diff --git a/operator/config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml b/operator/config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml
new file mode 100644
index 0000000..866b6eb
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_lmcachecoordinator.yaml
@@ -0,0 +1,67 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheCoordinator
+metadata:
+  name: my-coordinator
+  namespace: default
+spec:
+  # -- Container image (runs the same lmcache binary as the engines) --
+  image:
+    repository: lmcache/vllm-openai   # default
+    tag: latest                       # default
+    pullPolicy: IfNotPresent          # Always | Never | IfNotPresent
+  # imagePullSecrets:
+  #   - name: my-registry-secret
+
+  # -- Topology --
+  # replicas: 1                   # default
+
+  # -- HTTP server (maps to `lmcache coordinator` flags / MPCoordinatorConfig) --
+  # host: 0.0.0.0                 # default
+  # port: 9300                    # default, [1, 65535]
+
+  # -- Membership / health --
+  # instanceTimeout: 30           # default, seconds; must be > 0
+  # healthCheckInterval: 10       # default, seconds; 0 disables the loop
+
+  # -- L2 quota eviction --
+  # evictionCheckInterval: 5      # default, seconds; 0 disables the loop
+  # evictionRatio: 0.2            # default, range [0.0, 1.0]
+  # triggerWatermark: 1.0         # default, range (0.0, 1.0]
+
+  # -- Global CacheBlend directory --
+  # blendChunkSize: 256           # default; MUST equal the blend servers' chunk size
+  # blendProbeStride: 1           # default; 1 probes every offset for full recall
+
+  # -- Prometheus monitoring (coordinator has no /metrics endpoint yet) --
+  # prometheus:
+  #   enabled: false              # default
+  #   port: 9090                  # default
+  #   serviceMonitor:
+  #     enabled: false            # default, requires Prometheus Operator
+  #     interval: 30s             # default
+
+  # -- Resource requests/limits (no defaults; coordinator is CPU/memory light) --
+  # resourceOverrides:
+  #   requests:
+  #     cpu: "1"
+  #     memory: 1Gi
+  #   limits:
+  #     memory: 2Gi
+
+  # -- Logging --
+  # logLevel: INFO                # DEBUG | INFO | WARNING | ERROR
+
+  # -- Scheduling / pod overrides --
+  # nodeSelector: {}
+  # affinity: {}
+  # tolerations: []
+  # env: []
+  # volumes: []
+  # volumeMounts: []
+  # podAnnotations: {}
+  # podLabels: {}
+  # serviceAccountName: ""
+  # priorityClassName: ""
+
+  # -- Extra CLI flags (appended last, can override any auto-generated flag) --
+  # extraArgs: []
diff --git a/operator/config/samples/lmcache_v1alpha1_lmcacheengine.yaml b/operator/config/samples/lmcache_v1alpha1_lmcacheengine.yaml
new file mode 100644
index 0000000..daf315f
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_lmcacheengine.yaml
@@ -0,0 +1,126 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: my-cache
+  namespace: default
+spec:
+  # -- Container image --
+  # image:
+  #   repository: lmcache/vllm-openai   # default
+  #   tag: latest                        # default
+  #   pullPolicy: IfNotPresent           # Always | Never | IfNotPresent
+  # imagePullSecrets:
+  #   - name: my-registry-secret
+
+  # -- Server config --
+  # server:
+  #   port: 5555                  # default, ZMQ server port [1024, 65535]
+  #   httpPort: 8080              # default, HTTP frontend port (health, admin)
+  #   chunkSize: 256              # default, token chunk size
+  #   maxWorkers: 1               # default, worker threads
+  #   hashAlgorithm: blake3       # builtin | sha256_cbor | blake3
+
+  # -- L1 cache (REQUIRED) --
+  l1:
+    sizeGB: 60
+
+  # -- Eviction --
+  # eviction:
+  #   policy: LRU                 # default (only supported value)
+  #   triggerWatermark: 0.8       # default, range (0.0, 1.0]
+  #   evictionRatio: 0.2          # default, range (0.0, 1.0]
+
+  # -- Prometheus monitoring --
+  # prometheus:
+  #   enabled: true               # default
+  #   port: 9090                  # default
+  #   serviceMonitor:
+  #     enabled: false            # default, requires Prometheus Operator
+  #     interval: 30s             # default
+  #     labels:
+  #       release: kube-prometheus-stack
+
+  # -- L2 storage backend (single adapter) --
+  # l2Backend:
+  #   # Option A: Redis/Valkey (native RESP connector)
+  #   resp:
+  #     host: redis.default.svc.cluster.local
+  #     port: 6379
+  #     numWorkers: 8             # default, C++ I/O threads
+  #     maxCapacityGB: 0          # default (0 = no eviction tracking)
+  #     authSecretRef:            # optional, Secret with "username"/"password" keys
+  #       name: redis-auth
+  #       namespace: redis        # omit if same namespace as LMCacheEngine
+  #
+  #   # Option B: Raw escape hatch (for nixl_store, fs, mock, etc.)
+  #   # raw:
+  #   #   type: nixl_store
+  #   #   config:
+  #   #     backend: "POSIX"
+  #   #     backend_params:
+  #   #       file_path: "/data/lmcache/l2"
+  #   #       use_direct_io: "false"
+  #   #     pool_size: 64
+  #
+  #   # L2 policies
+  #   storePolicy: default        # default | skip_l1 (buffer-only mode)
+  #   prefetchPolicy: default     # default
+  #   prefetchMaxInFlight: 8      # default, max concurrent L2->L1 loads
+
+  # -- Connection-injection webhook defaults (optional) --
+  # The mutating webhook always wires opted-in vLLM pods to this engine
+  # (--kv-transfer-config, hostIPC, PYTHONHASHSEED). Set injection.payloadImage to
+  # ALSO stage an lmcache code tree into the vLLM container (emptyDir + init
+  # container + read-only mount + PYTHONPATH), pinning vLLM's lmcache to a
+  # specific build so client and server match. Leave unset for connection-only.
+  # injection:
+  #   payloadImage:                 # SEPARATE image: ships lmcache under /payload,
+  #     repository: registry.example.com/lmcache/lmcache-payload  # REQUIRED (no default)
+  #     tag: pinned                 # default: latest
+  #     pullPolicy: IfNotPresent    # Always | Never | IfNotPresent
+  #   imagePullSecrets:             # for a private payload image
+  #     - name: lmcache-payload-pull
+  #   targetContainer: vllm         # default: first container
+
+  # -- Resource overrides (auto-computed from l1.sizeGB if omitted) --
+  # resourceOverrides:
+  #   requests:
+  #     memory: 70Gi
+  #     cpu: "4"
+  #   limits:
+  #     memory: 100Gi
+
+  # -- Logging --
+  # logLevel: INFO                # DEBUG | INFO | WARNING | ERROR
+
+  # -- Scheduling --
+  # nodeSelector:                 # defaults to nvidia.com/gpu.present: "true"
+  #   nvidia.com/gpu.present: "true"
+  # affinity: {}
+  # tolerations: []
+
+  # -- Pod overrides --
+  # WARNING: Do NOT mount an emptyDir (or any volume) at /dev/shm. The operator
+  # sets hostIPC: true so the container shares the host's /dev/shm. Mounting an
+  # emptyDir would shadow the host's /dev/shm with a private tmpfs, breaking
+  # CUDA IPC between LMCache and vLLM pods (cudaIpcOpenMemHandle fails because
+  # IPC handles from one pod become invisible to the other). The same applies
+  # to vLLM pods that connect to this LMCache instance.
+  # env: []
+  # volumes: []
+  # volumeMounts: []
+  # podAnnotations: {}
+  # podLabels: {}
+  # serviceAccountName: ""
+  # priorityClassName: ""
+
+  # -- Security --
+  # Run the engine container in privileged mode. Defaults to false. On most
+  # clusters runtimeClassName: nvidia + NVIDIA_VISIBLE_DEVICES=all is enough for
+  # the engine to see all GPUs; set this to true only on clusters where it
+  # cannot see them otherwise. Requires the namespace to allow the privileged
+  # Pod Security Standard.
+  # privileged: false
+
+  # -- Extra CLI flags (appended last, can override any auto-generated flag) --
+  # extraArgs: []
diff --git a/operator/config/samples/lmcache_v1alpha1_lmcacheengine_amd.yaml b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_amd.yaml
new file mode 100644
index 0000000..8c3f0ac
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_amd.yaml
@@ -0,0 +1,16 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: amd-cache
+spec:
+  gpuVendor: amd
+  # AMD has no NVIDIA-style RuntimeClass to inject GPU device files, so the ROCm
+  # engine needs privileged mode to reach /dev/kfd and /dev/dri. (privileged
+  # defaults to false, which suits NVIDIA clusters where NVIDIA_VISIBLE_DEVICES
+  # already exposes the GPUs.) The namespace must allow the privileged Pod
+  # Security Standard.
+  privileged: true
+  nodeSelector:
+    feature.node.kubernetes.io/amd-gpu: "true"
+  l1:
+    sizeGB: 60
diff --git a/operator/config/samples/lmcache_v1alpha1_lmcacheengine_injection.yaml b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_injection.yaml
new file mode 100644
index 0000000..2af3bf3
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_injection.yaml
@@ -0,0 +1,41 @@
+# LMCacheEngine that pins injected vLLM pods to a specific lmcache build.
+#
+# On top of the usual connection wiring (--kv-transfer-config, hostIPC,
+# PYTHONHASHSEED), spec.injection.payloadImage makes the webhook stage an lmcache
+# payload into every opted-in vLLM pod (emptyDir + init container + read-only
+# mount + PYTHONPATH=/lmcache-payload), so vLLM imports THAT lmcache instead of
+# the one baked into its image — an older vLLM image can run the newest lmcache,
+# and the vLLM client stays on the engine server's build. The payload's lmcache
+# must be ABI-compatible (Python minor + torch) with the vLLM image; see
+# docker/Dockerfile.payload.
+#
+# Pair with an opted-in vLLM Deployment
+# (config/samples/vllm_lmcache_injection_deployment.yaml): pod-template label
+# `lmcache.ai/lmcache-inject: "true"` + annotation
+# `lmcache.ai/lmcache-engine: "my-cache-versioned"`.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: my-cache-versioned
+  namespace: default
+spec:
+  # -- L1 cache (REQUIRED) --
+  l1:
+    sizeGB: 60
+  image:
+    repository: lmcache/vllm-openai # default
+    tag: dev # default
+    pullPolicy: IfNotPresent # Always | Never | IfNotPresent
+
+  # -- Code-payload injection --
+  injection:
+    payloadImage:
+      repository: lmcache/lmcache-payload
+      tag: dev
+      pullPolicy: IfNotPresent
+    # Private payload registry only — the Secret(s) must exist in the vLLM pod's
+    # namespace (the operator does not copy them cross-namespace):
+    # imagePullSecrets:
+    #   - name: my-registry-secret
+    # Name the vLLM container if it is not the first one in the pod:
+    # targetContainer: vllm
diff --git a/operator/config/samples/lmcache_v1alpha1_lmcacheengine_l2_redis.yaml b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_l2_redis.yaml
new file mode 100644
index 0000000..c698301
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_l2_redis.yaml
@@ -0,0 +1,36 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: my-cache-with-redis
+  namespace: default
+spec:
+  image:
+    tag: "nightly-2026-04-06"
+
+  nodeSelector:
+    nvidia.com/gpu.present: "true"
+
+  server:
+    port: 5555
+    maxWorkers: 4
+
+  l1:
+    sizeGB: 100
+
+  eviction:
+    triggerWatermark: 0.8
+    evictionRatio: 0.2
+
+  # Redis/Valkey L2 adapter backed by the native C++ RESP connector.
+  l2Backend:
+    resp:
+      host: redb.redis.svc.cluster.local
+      port: 14084
+      numWorkers: 8
+      # Optional: reference a Secret with "username" and "password" keys.
+      # Credentials are injected as env vars and never appear in pod args.
+      # The Secret can live in a different namespace — the operator creates
+      # a managed copy in this LMCacheEngine's namespace automatically.
+      authSecretRef:
+        name: redb-redb
+        namespace: redis # omit if the Secret is in the same namespace
diff --git a/operator/config/samples/lmcache_v1alpha1_lmcacheengine_production.yaml b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_production.yaml
new file mode 100644
index 0000000..8c330e9
--- /dev/null
+++ b/operator/config/samples/lmcache_v1alpha1_lmcacheengine_production.yaml
@@ -0,0 +1,40 @@
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: production-cache
+  namespace: llm-serving
+spec:
+  nodeSelector:
+    nvidia.com/gpu.present: "true"
+
+  image:
+    repository: lmcache/standalone
+    tag: v0.1.0
+    pullPolicy: IfNotPresent
+
+  server:
+    port: 6555
+    chunkSize: 256
+    maxWorkers: 4
+    hashAlgorithm: blake3
+
+  l1:
+    sizeGB: 60
+
+  eviction:
+    triggerWatermark: 0.8
+    evictionRatio: 0.2
+
+  prometheus:
+    enabled: true
+    port: 9090
+    serviceMonitor:
+      enabled: true
+      labels:
+        release: kube-prometheus-stack
+
+  logLevel: INFO
+  podAnnotations:
+    prometheus.io/scrape: "true"
+    prometheus.io/port: "9090"
+  priorityClassName: system-node-critical
diff --git a/operator/config/samples/vllm_cacheblend_deployment.yaml b/operator/config/samples/vllm_cacheblend_deployment.yaml
new file mode 100644
index 0000000..c1d4bc8
--- /dev/null
+++ b/operator/config/samples/vllm_cacheblend_deployment.yaml
@@ -0,0 +1,86 @@
+# Sample vLLM Deployment that OPTS IN to CacheBlend dependency injection.
+#
+# The mutating webhook injects everything CacheBlend needs at pod CREATE — you
+# only supply the two highlighted bits below (the opt-in label + the engine
+# annotation) and a normal, args-only vLLM launch. After admission the webhook
+# adds: pod hostIPC=true; the `cb-plugin` emptyDir + payload init container;
+# a readOnly mount + PYTHONPATH on the vLLM container; the required vLLM flags
+# (--attention-backend CUSTOM, --kv-transfer-config <node-local engine>,
+# --block-size 64, --pipeline-parallel-size 1, --no-enable-chunked-prefill,
+# --no-async-scheduling, --enforce-eager); and the private-payload imagePullSecrets.
+#
+# PREREQUISITES (else injection silently no-ops or the pod is rejected):
+#   1. A CacheBlendEngine named below exists IN THIS NAMESPACE and is reconciled
+#      (its `<name>-connection` ConfigMap exists — the webhook reads it).
+#   2. This namespace is labeled pod-security.kubernetes.io/enforce=privileged
+#      (the injected hostIPC/privileged is rejected by baseline/restricted PSS).
+#   3. The vLLM container launches via the image ENTRYPOINT (["vllm","serve"])
+#      with args ONLY. Do NOT use `command: ["/bin/sh","-c", ...]` — a command
+#      override makes the webhook SKIP injection (appended args can't reach
+#      `vllm serve`); it stamps lmcache.ai/cacheblend-skip-reason=command-override.
+#   4. The private payload image's pull secret exists in THIS namespace
+#      (referenced by the engine's injection.imagePullSecrets, or overridden via
+#      the annotation below).
+#
+# Verify after creation:
+#   kubectl get pod -l app=vllm-cacheblend -o yaml | grep -E "hostIPC|cb-plugin|PYTHONPATH|attention-backend|cacheblend-injected"
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-cacheblend
+  namespace: default            # must match the CacheBlendEngine's namespace + be PSS-privileged
+  labels:
+    app: vllm-cacheblend
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-cacheblend
+  template:
+    metadata:
+      labels:
+        app: vllm-cacheblend
+        # (1) OPT-IN — the webhook's objectSelector matches this label.
+        lmcache.ai/cacheblend-inject: "true"
+      annotations:
+        # (2) BIND — names the CacheBlendEngine (same namespace) to inject for.
+        lmcache.ai/cacheblend-engine: "my-cacheblend"
+        # Optional: name the vLLM container if it is not the first one.
+        # lmcache.ai/cacheblend-container: "vllm"
+        # Optional: override the engine's payload imagePullSecrets (comma-separated).
+        # lmcache.ai/cacheblend-image-pull-secrets: "my-registry-secret"
+    spec:
+      # Needed for GPU access unless `nvidia` is the default containerd runtime.
+      # The blend engine shares THIS pod's GPU via CUDA IPC (it does not claim
+      # its own), so the engine + this pod must land on the same GPU node.
+      runtimeClassName: nvidia
+      # NOTE: do NOT set hostIPC here or mount an emptyDir at /dev/shm — the
+      # webhook injects hostIPC=true, which shares the host's /dev/shm for CUDA
+      # IPC; an emptyDir would shadow it and break cudaIpcOpenMemHandle.
+      containers:
+        - name: vllm
+          image: lmcache/vllm-openai:latest-nightly # vLLM + lmcache; must be in the cacheblend-supported version window
+          env:
+            # Deterministic prefix hashing across processes — required by LMCache.
+            - name: PYTHONHASHSEED
+              value: "0"
+          # Args-only launch (image ENTRYPOINT is ["vllm","serve"]). Put the
+          # model + your NON-CacheBlend serving flags here; the webhook APPENDS
+          # the CacheBlend flags. Do NOT add --attention-backend / --kv-transfer-config
+          # yourself (a user-supplied --kv-transfer-config makes the webhook skip it).
+          args:
+            - "Qwen/Qwen3-4B-Instruct-2507"
+            - "--port"
+            - "8000"
+            - "--gpu-memory-utilization"
+            - "0.8"
+            - "--load-format"        # uncomment for a weightless smoke test
+            - "dummy"
+          ports:
+            - name: http
+              containerPort: 8000
+          resources:
+            limits:
+              # vLLM claims its GPU normally; the blend engine (NVIDIA_VISIBLE_DEVICES=all)
+              # opens CUDA IPC handles on whichever GPU this pod is assigned.
+              nvidia.com/gpu: "1"
diff --git a/operator/config/samples/vllm_lmcache_deployment.yaml b/operator/config/samples/vllm_lmcache_deployment.yaml
new file mode 100644
index 0000000..ebe152f
--- /dev/null
+++ b/operator/config/samples/vllm_lmcache_deployment.yaml
@@ -0,0 +1,80 @@
+# Sample vLLM Deployment that OPTS IN to LMCacheEngine dependency injection.
+#
+# The webhook-injected alternative to vllm_deployment.yaml (which wires vLLM to
+# the engine by hand). You supply only the opt-in label + engine annotation and a
+# normal, args-only vLLM launch; at pod CREATE the webhook adds:
+#   - pod hostIPC=true (CUDA IPC with the node-local LMCache server);
+#   - --kv-transfer-config <inline JSON> on the vLLM container (read verbatim from
+#     the engine's <name>-connection ConfigMap — injected inline, no volume mount);
+#   - PYTHONHASHSEED=0 env (deterministic prefix hashing, set only if you didn't).
+#
+# If the LMCacheEngine sets spec.injection.payloadImage, the webhook ALSO stages
+# that lmcache build into this container — see
+# vllm_lmcache_injection_deployment.yaml.
+#
+# PREREQUISITES (else injection silently no-ops or the pod is rejected):
+#   1. An LMCacheEngine named below exists IN THIS NAMESPACE and is reconciled
+#      (its `<name>-connection` ConfigMap exists — the webhook reads it).
+#   2. The webhook is deployed: `make deploy` (not `make run`) + cert-manager.
+#   3. This namespace is labeled pod-security.kubernetes.io/enforce=privileged
+#      (the injected hostIPC is rejected by baseline/restricted PSS).
+#   4. The vLLM container launches via the image ENTRYPOINT (["vllm","serve"])
+#      with args ONLY. Do NOT use `command: ["/bin/sh","-c", ...]` — a command
+#      override makes the webhook SKIP injection (appended args can't reach
+#      `vllm serve`); it stamps lmcache.ai/lmcache-skip-reason=command-override.
+#
+# Verify after creation (the webhook mutates the POD, not the Deployment):
+#   kubectl get pod -l app=vllm-lmcache -o yaml | grep -E "hostIPC|kv-transfer-config|lmcache-injected|lmcache-payload|PYTHONPATH"
+# If nothing was injected, check lmcache.ai/lmcache-skip-reason on the pod
+# (command-override, kv-transfer-config-present, engine-not-found, or
+# target-container-not-found).
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-lmcache
+  namespace: default # must match the LMCacheEngine's namespace + be PSS-privileged
+  labels:
+    app: vllm-lmcache
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-lmcache
+  template:
+    metadata:
+      labels:
+        app: vllm-lmcache
+        # (1) OPT-IN — the webhook's objectSelector matches this label.
+        lmcache.ai/lmcache-inject: "true"
+      annotations:
+        # (2) BIND — names the LMCacheEngine (same namespace) to inject for.
+        lmcache.ai/lmcache-engine: "my-cache"
+        # Optional: name the vLLM container if it is not the first one.
+        # lmcache.ai/lmcache-container: "vllm"
+    spec:
+      # Needed for GPU access unless `nvidia` is the default containerd runtime.
+      runtimeClassName: nvidia
+      # NOTE: do NOT set hostIPC here or mount an emptyDir at /dev/shm — the
+      # webhook injects hostIPC=true, which shares the host's /dev/shm for CUDA
+      # IPC; an emptyDir would shadow it and break cudaIpcOpenMemHandle.
+      containers:
+        - name: vllm
+          image: lmcache/vllm-openai:latest-nightly # vLLM + lmcache
+          # Args-only launch (image ENTRYPOINT is ["vllm","serve"]). Put the
+          # model + your serving flags here; the webhook APPENDS --kv-transfer-config.
+          # Do NOT add --kv-transfer-config yourself (a user-supplied one makes the
+          # webhook skip it). --no-enable-prefix-caching keeps vLLM's APC from
+          # shadowing LMCache lookups.
+          args:
+            - "Qwen/Qwen3-4B-Instruct-2507"
+            - "--port"
+            - "8000"
+            - "--no-enable-prefix-caching"
+            - "--gpu-memory-utilization"
+            - "0.8"
+          ports:
+            - name: http
+              containerPort: 8000
+          resources:
+            limits:
+              nvidia.com/gpu: "1"
diff --git a/operator/config/samples/vllm_lmcache_injection_deployment.yaml b/operator/config/samples/vllm_lmcache_injection_deployment.yaml
new file mode 100644
index 0000000..4777a56
--- /dev/null
+++ b/operator/config/samples/vllm_lmcache_injection_deployment.yaml
@@ -0,0 +1,90 @@
+# Sample vLLM Deployment that OPTS IN to LMCacheEngine injection AND receives a
+# pinned lmcache code payload — companion to
+# lmcache_v1alpha1_lmcacheengine_injection.yaml (engine "my-cache-versioned").
+#
+# Because that engine sets spec.injection.payloadImage, the webhook does TWO
+# things to this pod at CREATE:
+#   1. Connection wiring (as in vllm_lmcache_deployment.yaml): hostIPC=true,
+#      --kv-transfer-config on the vLLM container, PYTHONHASHSEED=0.
+#   2. Payload staging: a `lmcache-payload` emptyDir + an init container that
+#      copies the payload image's lmcache tree in, a readOnly mount, and
+#      PYTHONPATH=/lmcache-payload so vLLM imports the STAGED lmcache.
+# Net: this pod can run an OLDER vLLM image yet execute the engine's lmcache
+# build (which must be ABI-compatible — Python minor + torch — with this image).
+#
+# PREREQUISITES (else injection silently no-ops or the pod is rejected):
+#   1. The "my-cache-versioned" LMCacheEngine exists IN THIS NAMESPACE and is
+#      reconciled (its `<name>-connection` ConfigMap exists — the webhook reads it).
+#   2. The webhook is deployed: `make deploy` (not `make run`) + cert-manager.
+#   3. This namespace is labeled pod-security.kubernetes.io/enforce=privileged
+#      (the injected hostIPC is rejected by baseline/restricted PSS).
+#   4. The vLLM container launches via the image ENTRYPOINT (["vllm","serve"])
+#      with args ONLY. Do NOT use `command: ["/bin/sh","-c", ...]` — a command
+#      override makes the webhook SKIP injection (it stamps
+#      lmcache.ai/lmcache-skip-reason=command-override).
+#
+# Verify the swap after creation (the webhook mutates the POD, not the Deployment):
+#   kubectl get pod -l app=vllm-lmcache-versioned -o yaml \
+#     | grep -E "hostIPC|kv-transfer-config|lmcache-injected|lmcache-payload|PYTHONPATH"
+#   # runtime proof — which lmcache the pod actually imports vs the baked-in one:
+#   POD=$(kubectl get pod -l app=vllm-lmcache-versioned -o name | head -1)
+#   kubectl exec $POD -c vllm -- python3 -c "import lmcache; print(lmcache.__version__, lmcache.__file__)"
+#   #   -> staged version, /lmcache-payload/lmcache/__init__.py
+#   kubectl exec $POD -c vllm -- env -u PYTHONPATH python3 -c "import lmcache; print(lmcache.__version__, lmcache.__file__)"
+#   #   -> the image's baked-in version, from site-packages
+# If nothing was injected, check lmcache.ai/lmcache-skip-reason on the pod.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-lmcache-versioned
+  namespace: default # must match the LMCacheEngine's namespace + be PSS-privileged
+  labels:
+    app: vllm-lmcache-versioned
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-lmcache-versioned
+  template:
+    metadata:
+      labels:
+        app: vllm-lmcache-versioned
+        # (1) OPT-IN — the webhook's objectSelector matches this label.
+        lmcache.ai/lmcache-inject: "true"
+      annotations:
+        # (2) BIND — names the LMCacheEngine (same namespace) to inject for.
+        lmcache.ai/lmcache-engine: "my-cache-versioned"
+        # Optional: name the vLLM container if it is not the first one.
+        # lmcache.ai/lmcache-container: "vllm"
+        # Optional: override the engine's payload imagePullSecrets (comma-separated).
+        # lmcache.ai/lmcache-image-pull-secrets: "my-registry-secret"
+    spec:
+      # Needed for GPU access unless `nvidia` is the default containerd runtime.
+      runtimeClassName: nvidia
+      # NOTE: do NOT set hostIPC here or mount an emptyDir at /dev/shm — the
+      # webhook injects hostIPC=true, which shares the host's /dev/shm for CUDA
+      # IPC; an emptyDir would shadow it and break cudaIpcOpenMemHandle.
+      containers:
+        - name: vllm
+          # An OLDER vLLM image on purpose: the engine's injection.payloadImage
+          # overrides whatever lmcache is baked in here. Pin your own older tag.
+          image: lmcache/vllm-openai:v0.4.3
+          # Args-only launch (image ENTRYPOINT is ["vllm","serve"]). The webhook
+          # APPENDS --kv-transfer-config; do NOT add it yourself (a user-supplied
+          # one makes the webhook skip it). --no-enable-prefix-caching keeps
+          # vLLM's APC from shadowing LMCache lookups.
+          args:
+            - "Qwen/Qwen3-4B-Instruct-2507"
+            - "--port"
+            - "8000"
+            - "--no-enable-prefix-caching"
+            - "--gpu-memory-utilization"
+            - "0.8"
+            - "--load-format"
+            - "dummy"
+          ports:
+            - name: http
+              containerPort: 8000
+          resources:
+            limits:
+              nvidia.com/gpu: "1"
diff --git a/operator/config/webhook/kustomization.yaml b/operator/config/webhook/kustomization.yaml
new file mode 100644
index 0000000..9f1267c
--- /dev/null
+++ b/operator/config/webhook/kustomization.yaml
@@ -0,0 +1,15 @@
+resources:
+- manifests.yaml
+- service.yaml
+
+# The generated manifests.yaml only carries the fields controller-gen can emit
+# (path/failurePolicy/sideEffects/reinvocationPolicy/rules). controller-gen cannot
+# emit arbitrary objectSelector/namespaceSelector matchExpressions, so the
+# blast-radius gating is layered on here as a strategic-merge patch. Never edit the
+# generated manifests.yaml directly.
+patches:
+- path: mutating_webhook_selectors_patch.yaml
+
+# the following config is for teaching kustomize how to do var substitution
+configurations:
+- kustomizeconfig.yaml
diff --git a/operator/config/webhook/kustomizeconfig.yaml b/operator/config/webhook/kustomizeconfig.yaml
new file mode 100644
index 0000000..a78df75
--- /dev/null
+++ b/operator/config/webhook/kustomizeconfig.yaml
@@ -0,0 +1,25 @@
+# the following config is for teaching kustomize where to look at when substituting nameReference.
+# It requires kustomize v2.1.0 or newer to work properly.
+nameReference:
+- kind: Service
+  version: v1
+  fieldSpecs:
+  - kind: MutatingWebhookConfiguration
+    group: admissionregistration.k8s.io
+    path: webhooks/clientConfig/service/name
+  - kind: ValidatingWebhookConfiguration
+    group: admissionregistration.k8s.io
+    path: webhooks/clientConfig/service/name
+
+namespace:
+- kind: MutatingWebhookConfiguration
+  group: admissionregistration.k8s.io
+  path: webhooks/clientConfig/service/namespace
+  create: true
+- kind: ValidatingWebhookConfiguration
+  group: admissionregistration.k8s.io
+  path: webhooks/clientConfig/service/namespace
+  create: true
+
+varReference:
+- path: metadata/annotations
diff --git a/operator/config/webhook/manifests.yaml b/operator/config/webhook/manifests.yaml
new file mode 100644
index 0000000..b8c5d26
--- /dev/null
+++ b/operator/config/webhook/manifests.yaml
@@ -0,0 +1,46 @@
+---
+apiVersion: admissionregistration.k8s.io/v1
+kind: MutatingWebhookConfiguration
+metadata:
+  name: mutating-webhook-configuration
+webhooks:
+- admissionReviewVersions:
+  - v1
+  clientConfig:
+    service:
+      name: webhook-service
+      namespace: system
+      path: /mutate--v1-pod
+  failurePolicy: Ignore
+  name: mcacheblendpod.lmcache.ai
+  reinvocationPolicy: Never
+  rules:
+  - apiGroups:
+    - ""
+    apiVersions:
+    - v1
+    operations:
+    - CREATE
+    resources:
+    - pods
+  sideEffects: None
+- admissionReviewVersions:
+  - v1
+  clientConfig:
+    service:
+      name: webhook-service
+      namespace: system
+      path: /mutate-lmcache--v1-pod
+  failurePolicy: Ignore
+  name: mlmcachepod.lmcache.ai
+  reinvocationPolicy: Never
+  rules:
+  - apiGroups:
+    - ""
+    apiVersions:
+    - v1
+    operations:
+    - CREATE
+    resources:
+    - pods
+  sideEffects: None
diff --git a/operator/config/webhook/mutating_webhook_selectors_patch.yaml b/operator/config/webhook/mutating_webhook_selectors_patch.yaml
new file mode 100644
index 0000000..d8084f4
--- /dev/null
+++ b/operator/config/webhook/mutating_webhook_selectors_patch.yaml
@@ -0,0 +1,40 @@
+# Strategic-merge patch adding the blast-radius selectors that controller-gen
+# cannot express. Webhooks are merged by their `name`, so each entry only patches
+# the matching webhook (mcacheblendpod.lmcache.ai = CacheBlend, mlmcachepod.lmcache.ai =
+# LMCache). Each injector has its own opt-in label so the two never cross-fire.
+#
+# - objectSelector: only mutate pods carrying the injector's opt-in label
+#   (lmcache.ai/cacheblend-inject / lmcache.ai/lmcache-inject = "true"); keeps the
+#   cluster-wide CREATE-pods rule from touching unrelated workloads.
+# - namespaceSelector: never mutate pods in kube-system / kube-public / the operator
+#   namespace (which runs under the "restricted" PSS profile and would reject the
+#   injected hostIPC), per design §10.
+apiVersion: admissionregistration.k8s.io/v1
+kind: MutatingWebhookConfiguration
+metadata:
+  name: mutating-webhook-configuration
+webhooks:
+- name: mcacheblendpod.lmcache.ai
+  objectSelector:
+    matchLabels:
+      lmcache.ai/cacheblend-inject: "true"
+  namespaceSelector:
+    matchExpressions:
+    - key: kubernetes.io/metadata.name
+      operator: NotIn
+      values:
+      - kube-system
+      - kube-public
+      - lmcache-operator-system
+- name: mlmcachepod.lmcache.ai
+  objectSelector:
+    matchLabels:
+      lmcache.ai/lmcache-inject: "true"
+  namespaceSelector:
+    matchExpressions:
+    - key: kubernetes.io/metadata.name
+      operator: NotIn
+      values:
+      - kube-system
+      - kube-public
+      - lmcache-operator-system
diff --git a/operator/config/webhook/service.yaml b/operator/config/webhook/service.yaml
new file mode 100644
index 0000000..79879ea
--- /dev/null
+++ b/operator/config/webhook/service.yaml
@@ -0,0 +1,16 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: webhook-service
+  namespace: system
+  labels:
+    app.kubernetes.io/name: operator
+    app.kubernetes.io/managed-by: kustomize
+spec:
+  ports:
+    - port: 443
+      protocol: TCP
+      targetPort: 9443
+  selector:
+    control-plane: controller-manager
+    app.kubernetes.io/name: operator
diff --git a/operator/go.mod b/operator/go.mod
new file mode 100644
index 0000000..808a1d4
--- /dev/null
+++ b/operator/go.mod
@@ -0,0 +1,101 @@
+module github.com/LMCache/LMCache
+
+go 1.25.3
+
+require (
+	github.com/evanphx/json-patch/v5 v5.9.11
+	github.com/onsi/ginkgo/v2 v2.27.2
+	github.com/onsi/gomega v1.38.2
+	github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring v0.89.0
+	k8s.io/api v0.35.0
+	k8s.io/apiextensions-apiserver v0.35.0
+	k8s.io/apimachinery v0.35.0
+	k8s.io/client-go v0.35.0
+	sigs.k8s.io/controller-runtime v0.23.1
+	sigs.k8s.io/yaml v1.6.0
+)
+
+require (
+	cel.dev/expr v0.24.0 // indirect
+	github.com/Masterminds/semver/v3 v3.4.0 // indirect
+	github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/blang/semver/v4 v4.0.0 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/emicklei/go-restful/v3 v3.12.2 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-logr/zapr v1.3.0 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
+	github.com/google/btree v1.1.3 // indirect
+	github.com/google/cel-go v0.26.0 // indirect
+	github.com/google/gnostic-models v0.7.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3 // indirect
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/prometheus/client_golang v1.23.2 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
+	github.com/spf13/cobra v1.10.0 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/stoewer/go-strcase v1.3.0 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect
+	go.opentelemetry.io/otel v1.41.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.34.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0 // indirect
+	go.opentelemetry.io/otel/metric v1.41.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.36.0 // indirect
+	go.opentelemetry.io/otel/trace v1.41.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.5.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	go.uber.org/zap v1.27.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.3 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
+	golang.org/x/mod v0.29.0 // indirect
+	golang.org/x/net v0.47.0 // indirect
+	golang.org/x/oauth2 v0.30.0 // indirect
+	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/term v0.37.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
+	golang.org/x/time v0.9.0 // indirect
+	golang.org/x/tools v0.38.0 // indirect
+	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20250303144028-a0af3efb3deb // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20250528174236-200df99c418a // indirect
+	google.golang.org/grpc v1.72.2 // indirect
+	google.golang.org/protobuf v1.36.8 // indirect
+	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/apiserver v0.35.0 // indirect
+	k8s.io/component-base v0.35.0 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 // indirect
+	k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 // indirect
+	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2 // indirect
+	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
+	sigs.k8s.io/randfill v1.0.0 // indirect
+	sigs.k8s.io/structured-merge-diff/v6 v6.3.2-0.20260122202528-d9cc6641c482 // indirect
+)
diff --git a/operator/go.sum b/operator/go.sum
new file mode 100644
index 0000000..e69fa79
--- /dev/null
+++ b/operator/go.sum
@@ -0,0 +1,257 @@
+cel.dev/expr v0.24.0 h1:56OvJKSH3hDGL0ml5uSxZmz3/3Pq4tJ+fb1unVLAFcY=
+cel.dev/expr v0.24.0/go.mod h1:hLPLo1W4QUmuYdA72RBX06QTs6MXw941piREPl3Yfiw=
+github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
+github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/antlr4-go/antlr/v4 v4.13.0 h1:lxCg3LAv+EUK6t1i0y1V6/SLeUi0eKEKdhQAlS8TVTI=
+github.com/antlr4-go/antlr/v4 v4.13.0/go.mod h1:pfChB/xh/Unjila75QW7+VU4TSnWnnk9UTnmpPaOR2g=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/blang/semver/v4 v4.0.0 h1:1PFHFE6yCCTv8C1TeyNNarDzntLi7wMI5i/pzqYIsAM=
+github.com/blang/semver/v4 v4.0.0/go.mod h1:IbckMUScFkM3pff0VJDNKRiT6TG/YpiHIM2yvyW5YoQ=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/emicklei/go-restful/v3 v3.12.2 h1:DhwDP0vY3k8ZzE0RunuJy8GhNpPL6zqLkDf9B/a0/xU=
+github.com/emicklei/go-restful/v3 v3.12.2/go.mod h1:6n3XBCmQQb25CM2LCACGz8ukIrRry+4bhvbpWn3mrbc=
+github.com/evanphx/json-patch v0.5.2 h1:xVCHIVMUu1wtM/VkR9jVZ45N3FhZfYMMYGorLCR8P3k=
+github.com/evanphx/json-patch v0.5.2/go.mod h1:ZWS5hhDbVDyob71nXKNL0+PWn6ToqBHMikGIFbs31qQ=
+github.com/evanphx/json-patch/v5 v5.9.11 h1:/8HVnzMq13/3x9TPvjG08wUGqBTmZBsCWzjTM0wiaDU=
+github.com/evanphx/json-patch/v5 v5.9.11/go.mod h1:3j+LviiESTElxA4p3EMKAB9HXj3/XEtnUf6OZxqIQTM=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
+github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
+github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=
+github.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
+github.com/gkampitakis/ciinfo v0.3.2 h1:JcuOPk8ZU7nZQjdUhctuhQofk7BGHuIy0c9Ez8BNhXs=
+github.com/gkampitakis/ciinfo v0.3.2/go.mod h1:1NIwaOcFChN4fa/B0hEBdAb6npDlFL8Bwx4dfRLRqAo=
+github.com/gkampitakis/go-diff v1.3.2 h1:Qyn0J9XJSDTgnsgHRdz9Zp24RaJeKMUHg2+PDZZdC4M=
+github.com/gkampitakis/go-diff v1.3.2/go.mod h1:LLgOrpqleQe26cte8s36HTWcTmMEur6OPYerdAAS9tk=
+github.com/gkampitakis/go-snaps v0.5.15 h1:amyJrvM1D33cPHwVrjo9jQxX8g/7E2wYdZ+01KS3zGE=
+github.com/gkampitakis/go-snaps v0.5.15/go.mod h1:HNpx/9GoKisdhw9AFOBT1N7DBs9DiHo/hGheFGBZ+mc=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-logr/zapr v1.3.0 h1:XGdV8XW8zdwFiwOA2Dryh1gj2KRQyOOoNmBy4EplIcQ=
+github.com/go-logr/zapr v1.3.0/go.mod h1:YKepepNBd1u/oyhd/yQmtjVXmm9uML4IXUgMOwR8/Gg=
+github.com/go-openapi/jsonpointer v0.19.6/go.mod h1:osyAmYz/mB/C3I+WsTTSgw1ONzaLJoLCyoi6/zppojs=
+github.com/go-openapi/jsonpointer v0.21.0 h1:YgdVicSA9vH5RiHs9TZW5oyafXZFc6+2Vc1rr/O9oNQ=
+github.com/go-openapi/jsonpointer v0.21.0/go.mod h1:IUyH9l/+uyhIYQ/PXVA41Rexl+kOkAPDdXEYns6fzUY=
+github.com/go-openapi/jsonreference v0.20.2 h1:3sVjiK66+uXK/6oQ8xgcRKcFgQ5KXa2KvnJRumpMGbE=
+github.com/go-openapi/jsonreference v0.20.2/go.mod h1:Bl1zwGIM8/wsvqjsOQLJ/SH+En5Ap4rVB5KVcIDZG2k=
+github.com/go-openapi/swag v0.22.3/go.mod h1:UzaqsxGiab7freDnrUUra0MwWfN/q7tE4j+VcZ0yl14=
+github.com/go-openapi/swag v0.23.0 h1:vsEVJDUo2hPJ2tu0/Xc+4noaxyEffXNIs3cOULZ+GrE=
+github.com/go-openapi/swag v0.23.0/go.mod h1:esZ8ITTYEsH1V2trKHjAN8Ai7xHb8RV+YSZ577vPjgQ=
+github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
+github.com/go-task/slim-sprig/v3 v3.0.0/go.mod h1:W848ghGpv3Qj3dhTPRyJypKRiqCdHZiAzKg9hl15HA8=
+github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=
+github.com/goccy/go-yaml v1.18.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/btree v1.1.3 h1:CVpQJjYgC4VbzxeGVHfvZrv1ctoYCAI8vbl07Fcxlyg=
+github.com/google/btree v1.1.3/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
+github.com/google/cel-go v0.26.0 h1:DPGjXackMpJWH680oGY4lZhYjIameYmR+/6RBdDGmaI=
+github.com/google/cel-go v0.26.0/go.mod h1:A9O8OU9rdvrK5MQyrqfIxo1a0u4g3sF8KB6PUIaryMM=
+github.com/google/gnostic-models v0.7.0 h1:qwTtogB15McXDaNqTZdzPJRHvaVJlAl+HVQnLmJEJxo=
+github.com/google/gnostic-models v0.7.0/go.mod h1:whL5G0m6dmc5cPxKc5bdKdEN3UjI7OUGxBlw57miDrQ=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0=
+github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/google/pprof v0.0.0-20250403155104-27863c87afa6 h1:BHT72Gu3keYf3ZEu2J0b1vyeLSOYI8bm5wbJM/8yDe8=
+github.com/google/pprof v0.0.0-20250403155104-27863c87afa6/go.mod h1:boTsfXsheKC2y+lKOCMpSfarhxDeIzfZG1jqGcPl3cA=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3 h1:5ZPtiqj0JL5oKWmcsq4VMaAW5ukBEgSGXEN89zeH1Jo=
+github.com/grpc-ecosystem/grpc-gateway/v2 v2.26.3/go.mod h1:ndYquD05frm2vACXE1nsccT4oJzjhw2arTS2cpUD1PI=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
+github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
+github.com/joshdk/go-junit v1.0.0 h1:S86cUKIdwBHWwA6xCmFlf3RTLfVXYQfvanM5Uh+K6GE=
+github.com/joshdk/go-junit v1.0.0/go.mod h1:TiiV0PqkaNfFXjEiyjWM3XXrhVyCa1K4Zfga6W52ung=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0=
+github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc=
+github.com/maruel/natural v1.1.1 h1:Hja7XhhmvEFhcByqDoHz9QZbkWey+COd9xWfCfn1ioo=
+github.com/maruel/natural v1.1.1/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg=
+github.com/mfridman/tparse v0.18.0 h1:wh6dzOKaIwkUGyKgOntDW4liXSo37qg5AXbIhkMV3vE=
+github.com/mfridman/tparse v0.18.0/go.mod h1:gEvqZTuCgEhPbYk/2lS3Kcxg1GmTxxU7kTC8DvP0i/A=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFdJifH4BDsTlE89Zl93FEloxaWZfGcifgq8=
+github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/onsi/ginkgo/v2 v2.27.2 h1:LzwLj0b89qtIy6SSASkzlNvX6WktqurSHwkk2ipF/Ns=
+github.com/onsi/ginkgo/v2 v2.27.2/go.mod h1:ArE1D/XhNXBXCBkKOLkbsb2c81dQHCRcF5zwn/ykDRo=
+github.com/onsi/gomega v1.38.2 h1:eZCjf2xjZAqe+LeWvKb5weQ+NcPwX84kqJ0cZNxok2A=
+github.com/onsi/gomega v1.38.2/go.mod h1:W2MJcYxRGV63b418Ai34Ud0hEdTVXq9NW9+Sx6uXf3k=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring v0.89.0 h1:nZ9Ov2SbA8pWcyWKpf6AbQipG5Negg5CfDKWOEtnnwc=
+github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring v0.89.0/go.mod h1:IJwk1oNs212afqGbNnE84GAB95OHtJR/BuI1rKESiYk=
+github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
+github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
+github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
+github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
+github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.0 h1:a5/WeUlSDCvV5a45ljW2ZFtV0bTDpkfSAj3uqB6Sc+0=
+github.com/spf13/cobra v1.10.0/go.mod h1:9dhySC7dnTtEiqzmqfkLj47BslqLCUPMXjG2lj/NgoE=
+github.com/spf13/pflag v1.0.8/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stoewer/go-strcase v1.3.0 h1:g0eASXYtp+yvN9fK8sH94oCIk0fau9uV1/ZdJ0AVEzs=
+github.com/stoewer/go-strcase v1.3.0/go.mod h1:fAH5hQ5pehh+j3nZfvwdk2RgEgQjAoM8wodgtPmh1xo=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tidwall/gjson v1.18.0 h1:FIDeeyB800efLX89e5a8Y0BNH+LOngJyGrIWxG2FKQY=
+github.com/tidwall/gjson v1.18.0/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
+github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
+github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 h1:F7Jx+6hwnZ41NSFTO5q4LYDtJRXBf2PD0rNBkeB/lus=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0/go.mod h1:UHB22Z8QsdRDrnAtX4PntOl36ajSxcdUMt1sF7Y6E7Q=
+go.opentelemetry.io/otel v1.41.0 h1:YlEwVsGAlCvczDILpUXpIpPSL/VPugt7zHThEMLce1c=
+go.opentelemetry.io/otel v1.41.0/go.mod h1:Yt4UwgEKeT05QbLwbyHXEwhnjxNO6D8L5PQP51/46dE=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.34.0 h1:OeNbIYk/2C15ckl7glBlOBp5+WlYsOElzTNmiPW/x60=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.34.0/go.mod h1:7Bept48yIeqxP2OZ9/AqIpYS94h2or0aB4FypJTc8ZM=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0 h1:tgJ0uaNS4c98WRNUEx5U3aDlrDOI5Rs+1Vifcw4DJ8U=
+go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.34.0/go.mod h1:U7HYyW0zt/a9x5J1Kjs+r1f/d4ZHnYFclhYY2+YbeoE=
+go.opentelemetry.io/otel/metric v1.41.0 h1:rFnDcs4gRzBcsO9tS8LCpgR0dxg4aaxWlJxCno7JlTQ=
+go.opentelemetry.io/otel/metric v1.41.0/go.mod h1:xPvCwd9pU0VN8tPZYzDZV/BMj9CM9vs00GuBjeKhJps=
+go.opentelemetry.io/otel/sdk v1.36.0 h1:b6SYIuLRs88ztox4EyrvRti80uXIFy+Sqzoh9kFULbs=
+go.opentelemetry.io/otel/sdk v1.36.0/go.mod h1:+lC+mTgD+MUWfjJubi2vvXWcVxyr9rmlshZni72pXeY=
+go.opentelemetry.io/otel/sdk/metric v1.36.0 h1:r0ntwwGosWGaa0CrSt8cuNuTcccMXERFwHX4dThiPis=
+go.opentelemetry.io/otel/sdk/metric v1.36.0/go.mod h1:qTNOhFDfKRwX0yXOqJYegL5WRaW376QbB7P4Pb0qva4=
+go.opentelemetry.io/otel/trace v1.41.0 h1:Vbk2co6bhj8L59ZJ6/xFTskY+tGAbOnCtQGVVa9TIN0=
+go.opentelemetry.io/otel/trace v1.41.0/go.mod h1:U1NU4ULCoxeDKc09yCWdWe+3QoyweJcISEVa1RBzOis=
+go.opentelemetry.io/proto/otlp v1.5.0 h1:xJvq7gMzB31/d406fB8U5CBdyQGw4P399D1aQWU/3i4=
+go.opentelemetry.io/proto/otlp v1.5.0/go.mod h1:keN8WnHxOy8PG0rQZjJJ5A2ebUoafqWp0eVQ4yIXvJ4=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
+go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
+go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
+go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8=
+golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
+golang.org/x/mod v0.29.0 h1:HV8lRxZC4l2cr3Zq1LvtOsi/ThTgWnUk/y64QSs8GwA=
+golang.org/x/mod v0.29.0/go.mod h1:NyhrlYXJ2H4eJiRy/WDBO6HMqZQ6q9nk4JzS3NuCK+w=
+golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
+golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
+golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
+golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
+golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
+golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.37.0 h1:8EGAD0qCmHYZg6J17DvsMy9/wJ7/D/4pV/wfnld5lTU=
+golang.org/x/term v0.37.0/go.mod h1:5pB4lxRNYYVZuTLmy8oR2BH8dflOR+IbTYFD8fi3254=
+golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
+golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/time v0.9.0 h1:EsRrnYcQiGH+5FfbgvV4AP7qEZstoyrHB0DzarOQ4ZY=
+golang.org/x/time v0.9.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
+golang.org/x/tools v0.38.0 h1:Hx2Xv8hISq8Lm16jvBZ2VQf+RLmbd7wVUsALibYI/IQ=
+golang.org/x/tools v0.38.0/go.mod h1:yEsQ/d/YK8cjh0L6rZlY8tgtlKiBNTL14pGDJPJpYQs=
+gomodules.xyz/jsonpatch/v2 v2.4.0 h1:Ci3iUJyx9UeRx7CeFN8ARgGbkESwJK+KB9lLcWxY/Zw=
+gomodules.xyz/jsonpatch/v2 v2.4.0/go.mod h1:AH3dM2RI6uoBZxn3LVrfvJ3E0/9dG4cSrbuBJT4moAY=
+google.golang.org/genproto/googleapis/api v0.0.0-20250303144028-a0af3efb3deb h1:p31xT4yrYrSM/G4Sn2+TNUkVhFCbG9y8itM2S6Th950=
+google.golang.org/genproto/googleapis/api v0.0.0-20250303144028-a0af3efb3deb/go.mod h1:jbe3Bkdp+Dh2IrslsFCklNhweNTBgSYanP1UXhJDhKg=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20250528174236-200df99c418a h1:v2PbRU4K3llS09c7zodFpNePeamkAwG3mPrAery9VeE=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20250528174236-200df99c418a/go.mod h1:qQ0YXyHHx3XkvlzUtpXDkS29lDSafHMZBAZDc03LQ3A=
+google.golang.org/grpc v1.72.2 h1:TdbGzwb82ty4OusHWepvFWGLgIbNo1/SUynEN0ssqv8=
+google.golang.org/grpc v1.72.2/go.mod h1:wH5Aktxcg25y1I3w7H69nHfXdOG3UiadoBtjh3izSDM=
+google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
+google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/evanphx/json-patch.v4 v4.13.0 h1:czT3CmqEaQ1aanPc5SdlgQrrEIb8w/wwCvWWnfEbYzo=
+gopkg.in/evanphx/json-patch.v4 v4.13.0/go.mod h1:p8EYWUEYMpynmqDbY58zCKCFZw8pRWMG4EsWvDvM72M=
+gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
+gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+k8s.io/api v0.35.0 h1:iBAU5LTyBI9vw3L5glmat1njFK34srdLmktWwLTprlY=
+k8s.io/api v0.35.0/go.mod h1:AQ0SNTzm4ZAczM03QH42c7l3bih1TbAXYo0DkF8ktnA=
+k8s.io/apiextensions-apiserver v0.35.0 h1:3xHk2rTOdWXXJM+RDQZJvdx0yEOgC0FgQ1PlJatA5T4=
+k8s.io/apiextensions-apiserver v0.35.0/go.mod h1:E1Ahk9SADaLQ4qtzYFkwUqusXTcaV2uw3l14aqpL2LU=
+k8s.io/apimachinery v0.35.0 h1:Z2L3IHvPVv/MJ7xRxHEtk6GoJElaAqDCCU0S6ncYok8=
+k8s.io/apimachinery v0.35.0/go.mod h1:jQCgFZFR1F4Ik7hvr2g84RTJSZegBc8yHgFWKn//hns=
+k8s.io/apiserver v0.35.0 h1:CUGo5o+7hW9GcAEF3x3usT3fX4f9r8xmgQeCBDaOgX4=
+k8s.io/apiserver v0.35.0/go.mod h1:QUy1U4+PrzbJaM3XGu2tQ7U9A4udRRo5cyxkFX0GEds=
+k8s.io/client-go v0.35.0 h1:IAW0ifFbfQQwQmga0UdoH0yvdqrbwMdq9vIFEhRpxBE=
+k8s.io/client-go v0.35.0/go.mod h1:q2E5AAyqcbeLGPdoRB+Nxe3KYTfPce1Dnu1myQdqz9o=
+k8s.io/component-base v0.35.0 h1:+yBrOhzri2S1BVqyVSvcM3PtPyx5GUxCK2tinZz1G94=
+k8s.io/component-base v0.35.0/go.mod h1:85SCX4UCa6SCFt6p3IKAPej7jSnF3L8EbfSyMZayJR0=
+k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
+k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
+k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 h1:Y3gxNAuB0OBLImH611+UDZcmKS3g6CthxToOb37KgwE=
+k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912/go.mod h1:kdmbQkyfwUagLfXIad1y2TdrjPFWp2Q89B3qkRwf/pQ=
+k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 h1:SjGebBtkBqHFOli+05xYbK8YF1Dzkbzn+gDM4X9T4Ck=
+k8s.io/utils v0.0.0-20251002143259-bc988d571ff4/go.mod h1:OLgZIPagt7ERELqWJFomSt595RzquPNLL48iOWgYOg0=
+sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2 h1:jpcvIRr3GLoUoEKRkHKSmGjxb6lWwrBlJsXc+eUYQHM=
+sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2/go.mod h1:Ve9uj1L+deCXFrPOk1LpFXqTg7LCFzFso6PA48q/XZw=
+sigs.k8s.io/controller-runtime v0.23.1 h1:TjJSM80Nf43Mg21+RCy3J70aj/W6KyvDtOlpKf+PupE=
+sigs.k8s.io/controller-runtime v0.23.1/go.mod h1:B6COOxKptp+YaUT5q4l6LqUJTRpizbgf9KSRNdQGns0=
+sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 h1:IpInykpT6ceI+QxKBbEflcR5EXP7sU1kvOlxwZh5txg=
+sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730/go.mod h1:mdzfpAEoE6DHQEN0uh9ZbOCuHbLK5wOm7dK4ctXE9Tg=
+sigs.k8s.io/randfill v1.0.0 h1:JfjMILfT8A6RbawdsK2JXGBR5AQVfd+9TbzrlneTyrU=
+sigs.k8s.io/randfill v1.0.0/go.mod h1:XeLlZ/jmk4i1HRopwe7/aU3H5n1zNUcX6TM94b3QxOY=
+sigs.k8s.io/structured-merge-diff/v6 v6.3.2-0.20260122202528-d9cc6641c482 h1:2WOzJpHUBVrrkDjU4KBT8n5LDcj824eX0I5UKcgeRUs=
+sigs.k8s.io/structured-merge-diff/v6 v6.3.2-0.20260122202528-d9cc6641c482/go.mod h1:M3W8sfWvn2HhQDIbGWj3S099YozAsymCo/wrT5ohRUE=
+sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
+sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=
diff --git a/operator/hack/boilerplate.go.txt b/operator/hack/boilerplate.go.txt
new file mode 100644
index 0000000..9786798
--- /dev/null
+++ b/operator/hack/boilerplate.go.txt
@@ -0,0 +1,15 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
\ No newline at end of file
diff --git a/operator/hack/pre-commit b/operator/hack/pre-commit
new file mode 100755
index 0000000..b5e675a
--- /dev/null
+++ b/operator/hack/pre-commit
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Pre-commit hook: checks format, lint, and spelling on staged Go files.
+# Install with: make install-hooks
+set -euo pipefail
+
+# Only run if Go files are staged.
+STAGED_GO=$(git diff --cached --name-only --diff-filter=ACM -- '*.go' || true)
+if [ -z "$STAGED_GO" ]; then
+  exit 0
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+LOCALBIN="${REPO_ROOT}/operator/bin"
+GOLANGCI_LINT="${LOCALBIN}/golangci-lint"
+
+printf '==> Checking format (go fmt)...\n'
+UNFMT=$(gofmt -l $STAGED_GO)
+if [ -n "$UNFMT" ]; then
+  printf 'ERROR: The following files are not formatted:\n'
+  printf '  %s\n' $UNFMT
+  printf 'Run "go fmt ./..." to fix.\n'
+  exit 1
+fi
+
+printf '==> Running go vet...\n'
+go vet ./...
+
+printf '==> Running golangci-lint (lint + spelling)...\n'
+if [ ! -x "$GOLANGCI_LINT" ]; then
+  printf 'golangci-lint not found. Run "make golangci-lint" first.\n'
+  exit 1
+fi
+"$GOLANGCI_LINT" run --timeout 5m
+
+printf 'All pre-commit checks passed.\n'
diff --git a/operator/internal/controller/cacheblend_reconcile_helpers.go b/operator/internal/controller/cacheblend_reconcile_helpers.go
new file mode 100644
index 0000000..519e9a3
--- /dev/null
+++ b/operator/internal/controller/cacheblend_reconcile_helpers.go
@@ -0,0 +1,443 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+	"fmt"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+// validateAndSetCondition runs validation and updates the ConfigValid condition.
+// Returns an error if validation fails (to stop reconciliation).
+func (r *CacheBlendEngineReconciler) validateAndSetCondition(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	errs := engine.ValidateSpec()
+
+	if len(errs) > 0 {
+		// Re-fetch to get the latest resourceVersion before status update.
+		generation := engine.Generation
+		if err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, engine); err != nil {
+			return fmt.Errorf("failed to re-fetch engine for status update: %w", err)
+		}
+		meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+			Type:               lmcachev1alpha1.ConditionConfigValid,
+			Status:             metav1.ConditionFalse,
+			Reason:             "ValidationFailed",
+			Message:            errs.ToAggregate().Error(),
+			ObservedGeneration: generation,
+		})
+		engine.Status.Phase = lmcachev1alpha1.PhaseFailed
+		engine.Status.ObservedGeneration = generation
+		if err := r.Status().Update(ctx, engine); err != nil {
+			return fmt.Errorf("failed to update status after validation failure: %w", err)
+		}
+		return fmt.Errorf("spec validation failed: %s", errs.ToAggregate().Error())
+	}
+
+	// ConfigValid=True condition is set in updateStatus (after re-fetch)
+	// to avoid resourceVersion conflicts.
+	return nil
+}
+
+// reconcileDaemonSet creates or updates the blend_v3 engine DaemonSet.
+func (r *CacheBlendEngineReconciler) reconcileDaemonSet(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	// Resolve the coordinator connection (ref -> Service URL) so the DaemonSet
+	// builder emits --coordinator-url for server registration.
+	conn, err := resources.ResolveCoordinatorConnection(ctx, r.Client, engine.Namespace, engine.Spec.Coordinator)
+	if err != nil {
+		return err
+	}
+	engine.Spec.Coordinator = conn
+
+	desired := resources.BuildCBEngineDaemonSet(engine)
+
+	existing := &appsv1.DaemonSet{}
+	err = r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	// Preserve immutable selector
+	desired.Spec.Selector = existing.Spec.Selector
+	desired.Spec.Template.Labels = resources.MergeLabels(
+		existing.Spec.Selector.MatchLabels,
+		desired.Spec.Template.Labels,
+	)
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Template = desired.Spec.Template
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileLookupService creates or updates the node-local lookup Service.
+func (r *CacheBlendEngineReconciler) reconcileLookupService(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	desired := resources.BuildCBEngineLookupService(engine)
+
+	existing := &corev1.Service{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Ports = desired.Spec.Ports
+	existing.Spec.InternalTrafficPolicy = desired.Spec.InternalTrafficPolicy
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileMetricsService creates or updates the headless metrics Service.
+func (r *CacheBlendEngineReconciler) reconcileMetricsService(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	desired := resources.BuildCBEngineMetricsService(engine)
+
+	existing := &corev1.Service{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Ports = desired.Spec.Ports
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileConnectionConfigMap creates or updates the <engine>-connection ConfigMap.
+func (r *CacheBlendEngineReconciler) reconcileConnectionConfigMap(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	desired := resources.BuildCBConnectionConfigMap(engine)
+
+	existing := &corev1.ConfigMap{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Data = desired.Data
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileServiceMonitor creates, updates, or deletes the ServiceMonitor.
+func (r *CacheBlendEngineReconciler) reconcileServiceMonitor(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	log := logf.FromContext(ctx)
+
+	if !resources.CBServiceMonitorEnabled(engine) {
+		// Delete ServiceMonitor if it exists
+		existing := &monitoringv1.ServiceMonitor{}
+		err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, existing)
+		if err != nil {
+			if apierrors.IsNotFound(err) {
+				return nil
+			}
+			// If the CRD is not installed, ignore the error
+			if meta.IsNoMatchError(err) {
+				return nil
+			}
+			return err
+		}
+		log.Info("Deleting ServiceMonitor", "name", engine.Name)
+		return r.Delete(ctx, existing)
+	}
+
+	desired := resources.BuildCBServiceMonitor(engine)
+
+	existing := &monitoringv1.ServiceMonitor{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		if meta.IsNoMatchError(err) {
+			log.Info("ServiceMonitor CRD not available, skipping")
+			return nil
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec = desired.Spec
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// updateStatus queries the DaemonSet and pods to compute status fields.
+// It re-fetches the engine to get the latest resourceVersion, avoiding
+// conflicts from watch events triggered by earlier reconcile steps.
+func (r *CacheBlendEngineReconciler) updateStatus(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	// Re-fetch to get the latest resourceVersion, avoiding conflicts
+	// from watch events triggered by earlier reconcile steps (e.g.
+	// DaemonSet/Service creation fires Owns watches).
+	if err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, engine); err != nil {
+		return err
+	}
+
+	// ConfigValid condition (set here after re-fetch so it's not lost).
+	meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionConfigValid,
+		Status:             metav1.ConditionTrue,
+		Reason:             "Valid",
+		Message:            "Spec validation passed",
+		ObservedGeneration: engine.Generation,
+	})
+
+	ds := &appsv1.DaemonSet{}
+	err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, ds)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			engine.Status.Phase = lmcachev1alpha1.PhasePending
+			engine.Status.DesiredInstances = 0
+			engine.Status.ReadyInstances = 0
+			engine.Status.ObservedGeneration = engine.Generation
+			return r.Status().Update(ctx, engine)
+		}
+		return err
+	}
+
+	engine.Status.DesiredInstances = ds.Status.DesiredNumberScheduled
+	engine.Status.ReadyInstances = ds.Status.NumberReady
+	engine.Status.ObservedGeneration = engine.Generation
+
+	// Compute phase
+	switch {
+	case ds.Status.DesiredNumberScheduled == 0:
+		engine.Status.Phase = lmcachev1alpha1.PhasePending
+	case ds.Status.NumberReady == ds.Status.DesiredNumberScheduled:
+		engine.Status.Phase = lmcachev1alpha1.PhaseRunning
+	case ds.Status.NumberReady > 0:
+		engine.Status.Phase = lmcachev1alpha1.PhaseDegraded
+	default:
+		engine.Status.Phase = lmcachev1alpha1.PhasePending
+	}
+
+	// Set conditions
+	meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionAvailable,
+		Status:             conditionBool(ds.Status.NumberReady > 0),
+		Reason:             reasonFromReady(ds.Status.NumberReady > 0, "AtLeastOneReady", "NoReadyInstances"),
+		Message:            fmt.Sprintf("%d/%d instances ready", ds.Status.NumberReady, ds.Status.DesiredNumberScheduled),
+		ObservedGeneration: engine.Generation,
+	})
+
+	allReady := ds.Status.NumberReady == ds.Status.DesiredNumberScheduled && ds.Status.DesiredNumberScheduled > 0
+	meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionAllInstancesReady,
+		Status:             conditionBool(allReady),
+		Reason:             reasonFromReady(allReady, "AllReady", "NotAllReady"),
+		Message:            fmt.Sprintf("%d/%d instances ready", ds.Status.NumberReady, ds.Status.DesiredNumberScheduled),
+		ObservedGeneration: engine.Generation,
+	})
+
+	// Build endpoints from pods
+	serverPort := int32(5555)
+	if engine.Spec.Server != nil && engine.Spec.Server.Port != nil {
+		serverPort = *engine.Spec.Server.Port
+	}
+	metricsPort := int32(9090)
+	if engine.Spec.Prometheus != nil && engine.Spec.Prometheus.Port != nil {
+		metricsPort = *engine.Spec.Prometheus.Port
+	}
+
+	podList := &corev1.PodList{}
+	if err := r.List(ctx, podList,
+		client.InNamespace(engine.Namespace),
+		client.MatchingLabels(resources.SelectorLabels(engine.Name)),
+	); err != nil {
+		return err
+	}
+
+	endpoints := make([]lmcachev1alpha1.EndpointStatus, 0, len(podList.Items))
+	for i := range podList.Items {
+		pod := &podList.Items[i]
+		ready := false
+		for _, cond := range pod.Status.Conditions {
+			if cond.Type == corev1.PodReady && cond.Status == corev1.ConditionTrue {
+				ready = true
+				break
+			}
+		}
+		endpoints = append(endpoints, lmcachev1alpha1.EndpointStatus{
+			NodeName:    pod.Spec.NodeName,
+			HostIP:      pod.Status.HostIP,
+			PodName:     pod.Name,
+			Port:        serverPort,
+			MetricsPort: metricsPort,
+			Ready:       ready,
+		})
+	}
+	engine.Status.Endpoints = endpoints
+
+	return r.Status().Update(ctx, engine)
+}
+
+// reconcileRESPAuthSecret ensures a local copy of the RESP auth secret exists in
+// the engine's namespace. It mirrors the LMCacheEngine path: a no-op unless
+// spec.l2Backend.RESP.authSecretRef is set, otherwise it reads the source secret
+// (possibly cross-namespace) and creates/updates a managed copy owned by the CR.
+func (r *CacheBlendEngineReconciler) reconcileRESPAuthSecret(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	log := logf.FromContext(ctx)
+	spec := &engine.Spec
+
+	// No RESP auth configured — clean up any stale managed secret.
+	if spec.L2Backend == nil || spec.L2Backend.RESP == nil || spec.L2Backend.RESP.AuthSecretRef == nil {
+		return r.deleteRESPAuthSecretIfExists(ctx, engine)
+	}
+
+	ref := spec.L2Backend.RESP.AuthSecretRef
+	sourceNS := ref.Namespace
+	if sourceNS == "" {
+		sourceNS = engine.Namespace
+	}
+	localName := resources.RESPAuthSecretName(engine.Name)
+
+	// Read the source secret.
+	source := &corev1.Secret{}
+	if err := r.Get(ctx, types.NamespacedName{Name: ref.Name, Namespace: sourceNS}, source); err != nil {
+		return fmt.Errorf("failed to read RESP auth secret %s/%s: %w", sourceNS, ref.Name, err)
+	}
+
+	// Validate that the source secret contains the required "password" key.
+	password, ok := source.Data["password"]
+	if !ok || len(password) == 0 {
+		return fmt.Errorf("RESP auth secret %s/%s is missing required 'password' key", sourceNS, ref.Name)
+	}
+
+	// Build the local managed copy.
+	// Only "password" is required; "username" is optional (Redis Enterprise
+	// often uses password-only auth).
+	secretData := map[string][]byte{
+		"password": password,
+	}
+	if u, ok := source.Data["username"]; ok {
+		secretData["username"] = u
+	}
+	desired := &corev1.Secret{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      localName,
+			Namespace: engine.Namespace,
+			Labels:    resources.StandardLabels(engine.Name),
+		},
+		Data: secretData,
+	}
+
+	existing := &corev1.Secret{}
+	err := r.Get(ctx, types.NamespacedName{Name: localName, Namespace: engine.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			log.Info("Creating managed RESP auth secret", "name", localName, "source", sourceNS+"/"+ref.Name)
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	// Update existing — apply ownerRef, data, and labels.
+	if err := ctrl.SetControllerReference(engine, existing, r.Scheme); err != nil {
+		return err
+	}
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Data = desired.Data
+	existing.Labels = desired.Labels
+	return r.Patch(ctx, existing, patch)
+}
+
+// deleteRESPAuthSecretIfExists removes the managed RESP auth secret if it exists
+// (e.g. when authSecretRef is removed from the spec).
+func (r *CacheBlendEngineReconciler) deleteRESPAuthSecretIfExists(ctx context.Context, engine *lmcachev1alpha1.CacheBlendEngine) error {
+	secret := &corev1.Secret{}
+	name := resources.RESPAuthSecretName(engine.Name)
+	err := r.Get(ctx, types.NamespacedName{Name: name, Namespace: engine.Namespace}, secret)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			return nil
+		}
+		return err
+	}
+	// Only delete if we own it.
+	if metav1.IsControlledBy(secret, engine) {
+		return r.Delete(ctx, secret)
+	}
+	return nil
+}
diff --git a/operator/internal/controller/cacheblendengine_controller.go b/operator/internal/controller/cacheblendengine_controller.go
new file mode 100644
index 0000000..c30a8db
--- /dev/null
+++ b/operator/internal/controller/cacheblendengine_controller.go
@@ -0,0 +1,128 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/runtime"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// CacheBlendEngineReconciler reconciles a CacheBlendEngine object. It mirrors
+// LMCacheEngineReconciler but targets the blend_v3 engine workload and carries
+// no finalizer of its own: a brand-new CRD has no legacy CRs to migrate, so
+// owner-reference garbage collection alone cascade-deletes the child DaemonSet,
+// Services, ConfigMap, and managed Secret when the CR is removed.
+type CacheBlendEngineReconciler struct {
+	client.Client
+	Scheme *runtime.Scheme
+}
+
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=cacheblendengines,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=cacheblendengines/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=cacheblendengines/finalizers,verbs=update
+
+// Reconcile reconciles the CacheBlendEngine CR. It applies defaults, validates
+// the spec, then converges the RESP auth Secret (only when RESP auth is
+// configured), the blend_v3 DaemonSet, the node-local lookup Service, the
+// headless metrics Service, the <engine>-connection ConfigMap, and the optional
+// ServiceMonitor before updating status. Every child carries a controller
+// reference for cascade deletion.
+func (r *CacheBlendEngineReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+	log := logf.FromContext(ctx)
+
+	// 1. Fetch CR
+	engine := &lmcachev1alpha1.CacheBlendEngine{}
+	if err := r.Get(ctx, req.NamespacedName, engine); err != nil {
+		if apierrors.IsNotFound(err) {
+			return ctrl.Result{}, nil
+		}
+		return ctrl.Result{}, err
+	}
+
+	// 2. Set defaults
+	engine.SetDefaults()
+
+	// 3. Validate
+	if err := r.validateAndSetCondition(ctx, engine); err != nil {
+		return ctrl.Result{}, err
+	}
+
+	// 4. Reconcile RESP auth secret (cross-namespace copy if needed)
+	if err := r.reconcileRESPAuthSecret(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile RESP auth secret")
+		return ctrl.Result{}, err
+	}
+
+	// 5. Reconcile DaemonSet
+	if err := r.reconcileDaemonSet(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile DaemonSet")
+		return ctrl.Result{}, err
+	}
+
+	// 6. Reconcile lookup Service (node-local discovery for vLLM)
+	if err := r.reconcileLookupService(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile lookup Service")
+		return ctrl.Result{}, err
+	}
+
+	// 7. Reconcile metrics Service
+	if err := r.reconcileMetricsService(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile metrics Service")
+		return ctrl.Result{}, err
+	}
+
+	// 8. Reconcile ConfigMap
+	if err := r.reconcileConnectionConfigMap(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile ConfigMap")
+		return ctrl.Result{}, err
+	}
+
+	// 9. Reconcile ServiceMonitor
+	if err := r.reconcileServiceMonitor(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile ServiceMonitor")
+		return ctrl.Result{}, err
+	}
+
+	// 10. Update status
+	if err := r.updateStatus(ctx, engine); err != nil {
+		log.Error(err, "Failed to update status")
+		return ctrl.Result{}, err
+	}
+
+	return ctrl.Result{}, nil
+}
+
+// SetupWithManager sets up the controller with the Manager.
+func (r *CacheBlendEngineReconciler) SetupWithManager(mgr ctrl.Manager) error {
+	return ctrl.NewControllerManagedBy(mgr).
+		For(&lmcachev1alpha1.CacheBlendEngine{}).
+		Owns(&appsv1.DaemonSet{}).
+		Owns(&corev1.ConfigMap{}).
+		Owns(&corev1.Service{}).
+		Owns(&corev1.Secret{}).
+		Named("cacheblendengine").
+		Complete(r)
+}
diff --git a/operator/internal/controller/cacheblendengine_controller_test.go b/operator/internal/controller/cacheblendengine_controller_test.go
new file mode 100644
index 0000000..e804f62
--- /dev/null
+++ b/operator/internal/controller/cacheblendengine_controller_test.go
@@ -0,0 +1,212 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/reconcile"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// cbeResourceName is the name of the CacheBlendEngine fixture reconciled by the
+// controller tests; the owner-reference helper checks against it.
+const cbeResourceName = "test-cbe"
+
+// argsContainFlagValue reports whether the ["--flag", "value", ...] slice
+// contains the given two-token flag/value pair.
+func argsContainFlagValue(args []string, flag, value string) bool {
+	for i := 0; i < len(args)-1; i++ {
+		if args[i] == flag && args[i+1] == value {
+			return true
+		}
+	}
+	return false
+}
+
+// ownedBy reports whether owners contains a controller reference to the
+// CacheBlendEngine test fixture (cbeResourceName).
+func ownedBy(owners []metav1.OwnerReference) bool {
+	for _, o := range owners {
+		if o.Kind == "CacheBlendEngine" && o.Name == cbeResourceName && o.Controller != nil && *o.Controller {
+			return true
+		}
+	}
+	return false
+}
+
+var _ = Describe("CacheBlendEngine Controller", func() {
+	Context("When reconciling a resource", func() {
+		const resourceName = cbeResourceName
+
+		ctx := context.Background()
+
+		typeNamespacedName := types.NamespacedName{
+			Name:      resourceName,
+			Namespace: "default",
+		}
+
+		BeforeEach(func() {
+			By("creating the custom resource for the Kind CacheBlendEngine")
+			engine := &lmcachev1alpha1.CacheBlendEngine{}
+			err := k8sClient.Get(ctx, typeNamespacedName, engine)
+			if err != nil && errors.IsNotFound(err) {
+				// injection.payloadImage.repository is required by ValidateSpec
+				// (the webhook needs it to inject a valid init container).
+				payloadRepo := "lmcache/cacheblend-plugin"
+				resource := &lmcachev1alpha1.CacheBlendEngine{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      resourceName,
+						Namespace: "default",
+					},
+					Spec: lmcachev1alpha1.CacheBlendEngineSpec{
+						L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+						Injection: &lmcachev1alpha1.InjectionSpec{
+							PayloadImage: &lmcachev1alpha1.ImageSpec{Repository: &payloadRepo},
+						},
+					},
+				}
+				Expect(k8sClient.Create(ctx, resource)).To(Succeed())
+			}
+		})
+
+		AfterEach(func() {
+			resource := &lmcachev1alpha1.CacheBlendEngine{}
+			err := k8sClient.Get(ctx, typeNamespacedName, resource)
+			Expect(err).NotTo(HaveOccurred())
+
+			By("Cleanup the specific resource instance CacheBlendEngine")
+			Expect(k8sClient.Delete(ctx, resource)).To(Succeed())
+
+			// Drain child resources so a subsequent test starts clean (envtest
+			// has no GC controller, so ownerRef cascade deletion does not run).
+			// The lookup Service shares the engine's name (no suffix).
+			_ = k8sClient.Delete(ctx, &appsv1.DaemonSet{ObjectMeta: metav1.ObjectMeta{Name: resourceName, Namespace: "default"}})
+			_ = k8sClient.Delete(ctx, &corev1.Service{ObjectMeta: metav1.ObjectMeta{Name: resourceName, Namespace: "default"}})
+			_ = k8sClient.Delete(ctx, &corev1.Service{ObjectMeta: metav1.ObjectMeta{Name: resourceName + "-metrics", Namespace: "default"}})
+			_ = k8sClient.Delete(ctx, &corev1.ConfigMap{ObjectMeta: metav1.ObjectMeta{Name: resourceName + "-connection", Namespace: "default"}})
+		})
+
+		It("should reconcile to a blend_v3 DaemonSet, Services, and connection ConfigMap with ownerRefs", func() {
+			controllerReconciler := &CacheBlendEngineReconciler{
+				Client: k8sClient,
+				Scheme: k8sClient.Scheme(),
+			}
+
+			By("Reconciling the created resource")
+			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
+				NamespacedName: typeNamespacedName,
+			})
+			Expect(err).NotTo(HaveOccurred())
+
+			By("Verifying the blend_v3 DaemonSet")
+			ds := &appsv1.DaemonSet{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, ds)).To(Succeed())
+			Expect(ownedBy(ds.OwnerReferences)).To(BeTrue())
+
+			podSpec := ds.Spec.Template.Spec
+			Expect(podSpec.HostIPC).To(BeTrue())
+			Expect(podSpec.Containers).To(HaveLen(1))
+			engineContainer := podSpec.Containers[0]
+
+			Expect(argsContainFlagValue(engineContainer.Args, "--engine-type", "blend")).To(BeTrue())
+			Expect(argsContainFlagValue(engineContainer.Args, "--l1-align-bytes", "16777216")).To(BeTrue())
+
+			By("Verifying there is no GPU resource claim")
+			_, hasGPU := engineContainer.Resources.Limits["nvidia.com/gpu"]
+			Expect(hasGPU).To(BeFalse())
+
+			By("Verifying the lookup Service is node-local (named after the engine)")
+			lookupSvc := &corev1.Service{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, lookupSvc)).To(Succeed())
+			Expect(ownedBy(lookupSvc.OwnerReferences)).To(BeTrue())
+			Expect(lookupSvc.Spec.InternalTrafficPolicy).NotTo(BeNil())
+			Expect(*lookupSvc.Spec.InternalTrafficPolicy).To(Equal(corev1.ServiceInternalTrafficPolicyLocal))
+
+			By("Verifying the headless metrics Service")
+			metricsSvc := &corev1.Service{}
+			Expect(k8sClient.Get(ctx, types.NamespacedName{Name: resourceName + "-metrics", Namespace: "default"}, metricsSvc)).To(Succeed())
+			Expect(ownedBy(metricsSvc.OwnerReferences)).To(BeTrue())
+			Expect(metricsSvc.Spec.ClusterIP).To(Equal(corev1.ClusterIPNone))
+
+			By("Verifying the connection ConfigMap carries CBKVConnector JSON")
+			cm := &corev1.ConfigMap{}
+			Expect(k8sClient.Get(ctx, types.NamespacedName{Name: resourceName + "-connection", Namespace: "default"}, cm)).To(Succeed())
+			Expect(ownedBy(cm.OwnerReferences)).To(BeTrue())
+			jsonStr, ok := cm.Data["kv-transfer-config.json"]
+			Expect(ok).To(BeTrue())
+			Expect(strings.Contains(jsonStr, "CBKVConnector")).To(BeTrue())
+
+			config := map[string]any{}
+			Expect(json.Unmarshal([]byte(jsonStr), &config)).To(Succeed())
+			Expect(config["kv_connector"]).To(Equal("CBKVConnector"))
+
+			// design §7: the connector must dial the node-local Service over TCP
+			// (the key correction vs the single-machine model card), and carry the
+			// blend tunables.
+			extra, ok := config["kv_connector_extra_config"].(map[string]any)
+			Expect(ok).To(BeTrue())
+			Expect(extra["lmcache.mp.host"]).To(Equal(
+				fmt.Sprintf("tcp://%s.default.svc.cluster.local", resourceName)))
+			Expect(extra).To(HaveKey("lmcache.mp.port"))
+			Expect(extra).To(HaveKey("cb.check_layer"))
+			Expect(extra).To(HaveKey("cb.recomp_ratio"))
+		})
+
+		It("should converge status with ConfigValid=True after reconcile", func() {
+			controllerReconciler := &CacheBlendEngineReconciler{
+				Client: k8sClient,
+				Scheme: k8sClient.Scheme(),
+			}
+
+			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
+				NamespacedName: typeNamespacedName,
+			})
+			Expect(err).NotTo(HaveOccurred())
+
+			updated := &lmcachev1alpha1.CacheBlendEngine{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, updated)).To(Succeed())
+
+			By("Verifying the ConfigValid condition is True")
+			var found bool
+			for _, cond := range updated.Status.Conditions {
+				if cond.Type == lmcachev1alpha1.ConditionConfigValid {
+					found = true
+					Expect(cond.Status).To(Equal(metav1.ConditionTrue))
+				}
+			}
+			Expect(found).To(BeTrue())
+
+			By("Verifying the observed generation tracks the spec")
+			Expect(updated.Status.ObservedGeneration).To(Equal(updated.Generation))
+			// envtest has no kubelet, so no instances are scheduled: phase Pending.
+			Expect(updated.Status.Phase).To(Equal(lmcachev1alpha1.PhasePending))
+		})
+	})
+})
diff --git a/operator/internal/controller/coordinator_reconcile_helpers.go b/operator/internal/controller/coordinator_reconcile_helpers.go
new file mode 100644
index 0000000..7ddaa69
--- /dev/null
+++ b/operator/internal/controller/coordinator_reconcile_helpers.go
@@ -0,0 +1,291 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+	"fmt"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+// validateAndSetCondition runs validation and updates the ConfigValid condition.
+// Returns an error if validation fails (to stop reconciliation).
+func (r *LMCacheCoordinatorReconciler) validateAndSetCondition(ctx context.Context, coordinator *lmcachev1alpha1.LMCacheCoordinator) error {
+	errs := coordinator.ValidateSpec()
+
+	if len(errs) > 0 {
+		generation := coordinator.Generation
+		if err := r.Get(ctx, types.NamespacedName{Name: coordinator.Name, Namespace: coordinator.Namespace}, coordinator); err != nil {
+			return fmt.Errorf("failed to re-fetch coordinator for status update: %w", err)
+		}
+		meta.SetStatusCondition(&coordinator.Status.Conditions, metav1.Condition{
+			Type:               lmcachev1alpha1.ConditionConfigValid,
+			Status:             metav1.ConditionFalse,
+			Reason:             "ValidationFailed",
+			Message:            errs.ToAggregate().Error(),
+			ObservedGeneration: generation,
+		})
+		coordinator.Status.Phase = lmcachev1alpha1.PhaseFailed
+		coordinator.Status.ObservedGeneration = generation
+		if err := r.Status().Update(ctx, coordinator); err != nil {
+			return fmt.Errorf("failed to update status after validation failure: %w", err)
+		}
+		return fmt.Errorf("spec validation failed: %s", errs.ToAggregate().Error())
+	}
+
+	return nil
+}
+
+// reconcileDeployment creates or updates the coordinator Deployment.
+func (r *LMCacheCoordinatorReconciler) reconcileDeployment(ctx context.Context, coordinator *lmcachev1alpha1.LMCacheCoordinator) error {
+	desired := resources.BuildCoordinatorDeployment(coordinator)
+
+	existing := &appsv1.Deployment{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(coordinator, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	// Preserve immutable selector.
+	desired.Spec.Selector = existing.Spec.Selector
+
+	if err := ctrl.SetControllerReference(coordinator, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Replicas = desired.Spec.Replicas
+	existing.Spec.Template = desired.Spec.Template
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileCoordinatorService creates or updates the ClusterIP Service.
+func (r *LMCacheCoordinatorReconciler) reconcileCoordinatorService(ctx context.Context, coordinator *lmcachev1alpha1.LMCacheCoordinator) error {
+	desired := resources.BuildCoordinatorService(coordinator)
+
+	existing := &corev1.Service{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(coordinator, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(coordinator, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Ports = desired.Spec.Ports
+	existing.Spec.Selector = desired.Spec.Selector
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileCoordinatorServiceMonitor converges the headless metrics Service and
+// the ServiceMonitor when prometheus is enabled, and deletes them otherwise.
+func (r *LMCacheCoordinatorReconciler) reconcileCoordinatorServiceMonitor(ctx context.Context, coordinator *lmcachev1alpha1.LMCacheCoordinator) error {
+	log := logf.FromContext(ctx)
+
+	if !resources.CoordinatorServiceMonitorEnabled(coordinator) {
+		if err := r.deleteCoordinatorMetricsServiceIfExists(ctx, coordinator); err != nil {
+			return err
+		}
+		// Delete ServiceMonitor if it exists.
+		existing := &monitoringv1.ServiceMonitor{}
+		err := r.Get(ctx, types.NamespacedName{Name: coordinator.Name, Namespace: coordinator.Namespace}, existing)
+		if err != nil {
+			if apierrors.IsNotFound(err) || meta.IsNoMatchError(err) {
+				return nil
+			}
+			return err
+		}
+		log.Info("Deleting coordinator ServiceMonitor", "name", coordinator.Name)
+		return r.Delete(ctx, existing)
+	}
+
+	// Metrics Service.
+	desiredSvc := resources.BuildCoordinatorMetricsService(coordinator)
+	existingSvc := &corev1.Service{}
+	err := r.Get(ctx, types.NamespacedName{Name: desiredSvc.Name, Namespace: desiredSvc.Namespace}, existingSvc)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(coordinator, desiredSvc, r.Scheme); err != nil {
+				return err
+			}
+			if err := r.Create(ctx, desiredSvc); err != nil {
+				return err
+			}
+		} else {
+			return err
+		}
+	} else {
+		if err := ctrl.SetControllerReference(coordinator, desiredSvc, r.Scheme); err != nil {
+			return err
+		}
+		patch := client.MergeFrom(existingSvc.DeepCopy())
+		existingSvc.Spec.Ports = desiredSvc.Spec.Ports
+		existingSvc.Spec.Selector = desiredSvc.Spec.Selector
+		existingSvc.Labels = desiredSvc.Labels
+		if err := r.Patch(ctx, existingSvc, patch); err != nil {
+			return err
+		}
+	}
+
+	// ServiceMonitor.
+	desired := resources.BuildCoordinatorServiceMonitor(coordinator)
+	existing := &monitoringv1.ServiceMonitor{}
+	err = r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(coordinator, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		if meta.IsNoMatchError(err) {
+			log.Info("ServiceMonitor CRD not available, skipping")
+			return nil
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(coordinator, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec = desired.Spec
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// deleteCoordinatorMetricsServiceIfExists removes the headless metrics Service
+// if it exists and is owned by this coordinator (e.g. when prometheus is
+// disabled after being enabled).
+func (r *LMCacheCoordinatorReconciler) deleteCoordinatorMetricsServiceIfExists(ctx context.Context, coordinator *lmcachev1alpha1.LMCacheCoordinator) error {
+	svc := &corev1.Service{}
+	name := fmt.Sprintf("%s-metrics", coordinator.Name)
+	err := r.Get(ctx, types.NamespacedName{Name: name, Namespace: coordinator.Namespace}, svc)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			return nil
+		}
+		return err
+	}
+	if metav1.IsControlledBy(svc, coordinator) {
+		return r.Delete(ctx, svc)
+	}
+	return nil
+}
+
+// updateStatus queries the Deployment to compute status fields. It re-fetches
+// the coordinator to get the latest resourceVersion, avoiding conflicts from
+// watch events triggered by earlier reconcile steps.
+func (r *LMCacheCoordinatorReconciler) updateStatus(ctx context.Context, coordinator *lmcachev1alpha1.LMCacheCoordinator) error {
+	if err := r.Get(ctx, types.NamespacedName{Name: coordinator.Name, Namespace: coordinator.Namespace}, coordinator); err != nil {
+		return err
+	}
+
+	meta.SetStatusCondition(&coordinator.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionConfigValid,
+		Status:             metav1.ConditionTrue,
+		Reason:             "Valid",
+		Message:            "Spec validation passed",
+		ObservedGeneration: coordinator.Generation,
+	})
+
+	coordinator.Status.Endpoint = resources.CoordinatorEndpoint(coordinator)
+	coordinator.Status.ObservedGeneration = coordinator.Generation
+
+	deploy := &appsv1.Deployment{}
+	err := r.Get(ctx, types.NamespacedName{Name: coordinator.Name, Namespace: coordinator.Namespace}, deploy)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			coordinator.Status.Phase = lmcachev1alpha1.PhasePending
+			coordinator.Status.Replicas = 0
+			coordinator.Status.ReadyReplicas = 0
+			return r.Status().Update(ctx, coordinator)
+		}
+		return err
+	}
+
+	desired := int32(0)
+	if deploy.Spec.Replicas != nil {
+		desired = *deploy.Spec.Replicas
+	}
+	ready := deploy.Status.ReadyReplicas
+	coordinator.Status.Replicas = desired
+	coordinator.Status.ReadyReplicas = ready
+
+	switch {
+	case desired == 0:
+		coordinator.Status.Phase = lmcachev1alpha1.PhasePending
+	case ready == desired:
+		coordinator.Status.Phase = lmcachev1alpha1.PhaseRunning
+	case ready > 0:
+		coordinator.Status.Phase = lmcachev1alpha1.PhaseDegraded
+	default:
+		coordinator.Status.Phase = lmcachev1alpha1.PhasePending
+	}
+
+	meta.SetStatusCondition(&coordinator.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionAvailable,
+		Status:             conditionBool(ready > 0),
+		Reason:             reasonFromReady(ready > 0, "AtLeastOneReady", "NoReadyReplicas"),
+		Message:            fmt.Sprintf("%d/%d replicas ready", ready, desired),
+		ObservedGeneration: coordinator.Generation,
+	})
+
+	allReady := ready == desired && desired > 0
+	meta.SetStatusCondition(&coordinator.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionAllInstancesReady,
+		Status:             conditionBool(allReady),
+		Reason:             reasonFromReady(allReady, "AllReady", "NotAllReady"),
+		Message:            fmt.Sprintf("%d/%d replicas ready", ready, desired),
+		ObservedGeneration: coordinator.Generation,
+	})
+
+	return r.Status().Update(ctx, coordinator)
+}
diff --git a/operator/internal/controller/lmcachecoordinator_controller.go b/operator/internal/controller/lmcachecoordinator_controller.go
new file mode 100644
index 0000000..afca27c
--- /dev/null
+++ b/operator/internal/controller/lmcachecoordinator_controller.go
@@ -0,0 +1,107 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/runtime"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// LMCacheCoordinatorReconciler reconciles a LMCacheCoordinator object. It mirrors
+// the engine reconcilers but targets the fleet coordinator service: it converges
+// a Deployment (not a DaemonSet) plus a ClusterIP Service, and carries no
+// finalizer of its own since owner-reference garbage collection cascade-deletes
+// the children when the CR is removed.
+type LMCacheCoordinatorReconciler struct {
+	client.Client
+	Scheme *runtime.Scheme
+}
+
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=lmcachecoordinators,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=lmcachecoordinators/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=lmcachecoordinators/finalizers,verbs=update
+// +kubebuilder:rbac:groups=apps,resources=deployments,verbs=get;list;watch;create;update;patch;delete
+
+// Reconcile reconciles the LMCacheCoordinator CR. It applies defaults, validates
+// the spec, then converges the coordinator Deployment, the ClusterIP Service,
+// and the optional ServiceMonitor before updating status. Every child carries a
+// controller reference for cascade deletion.
+func (r *LMCacheCoordinatorReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+	log := logf.FromContext(ctx)
+
+	// 1. Fetch CR
+	coordinator := &lmcachev1alpha1.LMCacheCoordinator{}
+	if err := r.Get(ctx, req.NamespacedName, coordinator); err != nil {
+		if apierrors.IsNotFound(err) {
+			return ctrl.Result{}, nil
+		}
+		return ctrl.Result{}, err
+	}
+
+	// 2. Set defaults
+	coordinator.SetDefaults()
+
+	// 3. Validate
+	if err := r.validateAndSetCondition(ctx, coordinator); err != nil {
+		return ctrl.Result{}, err
+	}
+
+	// 4. Reconcile Deployment
+	if err := r.reconcileDeployment(ctx, coordinator); err != nil {
+		log.Error(err, "Failed to reconcile Deployment")
+		return ctrl.Result{}, err
+	}
+
+	// 5. Reconcile Service
+	if err := r.reconcileCoordinatorService(ctx, coordinator); err != nil {
+		log.Error(err, "Failed to reconcile Service")
+		return ctrl.Result{}, err
+	}
+
+	// 6. Reconcile metrics Service + ServiceMonitor (gated on prometheus)
+	if err := r.reconcileCoordinatorServiceMonitor(ctx, coordinator); err != nil {
+		log.Error(err, "Failed to reconcile ServiceMonitor")
+		return ctrl.Result{}, err
+	}
+
+	// 7. Update status
+	if err := r.updateStatus(ctx, coordinator); err != nil {
+		log.Error(err, "Failed to update status")
+		return ctrl.Result{}, err
+	}
+
+	return ctrl.Result{}, nil
+}
+
+// SetupWithManager sets up the controller with the Manager.
+func (r *LMCacheCoordinatorReconciler) SetupWithManager(mgr ctrl.Manager) error {
+	return ctrl.NewControllerManagedBy(mgr).
+		For(&lmcachev1alpha1.LMCacheCoordinator{}).
+		Owns(&appsv1.Deployment{}).
+		Owns(&corev1.Service{}).
+		Named("lmcachecoordinator").
+		Complete(r)
+}
diff --git a/operator/internal/controller/lmcachecoordinator_controller_test.go b/operator/internal/controller/lmcachecoordinator_controller_test.go
new file mode 100644
index 0000000..169909d
--- /dev/null
+++ b/operator/internal/controller/lmcachecoordinator_controller_test.go
@@ -0,0 +1,183 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/reconcile"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// lmccResourceName is the name of the LMCacheCoordinator fixture reconciled by
+// the controller tests.
+const lmccResourceName = "test-coordinator"
+
+// ownedByCoordinator reports whether owners contains a controller reference to
+// the LMCacheCoordinator test fixture.
+func ownedByCoordinator(owners []metav1.OwnerReference) bool {
+	for _, o := range owners {
+		if o.Kind == "LMCacheCoordinator" && o.Name == lmccResourceName && o.Controller != nil && *o.Controller {
+			return true
+		}
+	}
+	return false
+}
+
+var _ = Describe("LMCacheCoordinator Controller", func() {
+	Context("When reconciling a resource", func() {
+		const resourceName = lmccResourceName
+
+		ctx := context.Background()
+
+		typeNamespacedName := types.NamespacedName{
+			Name:      resourceName,
+			Namespace: "default",
+		}
+
+		BeforeEach(func() {
+			By("creating the custom resource for the Kind LMCacheCoordinator")
+			coordinator := &lmcachev1alpha1.LMCacheCoordinator{}
+			err := k8sClient.Get(ctx, typeNamespacedName, coordinator)
+			if err != nil && errors.IsNotFound(err) {
+				resource := &lmcachev1alpha1.LMCacheCoordinator{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      resourceName,
+						Namespace: "default",
+					},
+					Spec: lmcachev1alpha1.LMCacheCoordinatorSpec{},
+				}
+				Expect(k8sClient.Create(ctx, resource)).To(Succeed())
+			}
+		})
+
+		AfterEach(func() {
+			resource := &lmcachev1alpha1.LMCacheCoordinator{}
+			err := k8sClient.Get(ctx, typeNamespacedName, resource)
+			Expect(err).NotTo(HaveOccurred())
+
+			By("Cleanup the specific resource instance LMCacheCoordinator")
+			Expect(k8sClient.Delete(ctx, resource)).To(Succeed())
+
+			// envtest has no GC controller, so drain children manually.
+			_ = k8sClient.Delete(ctx, &appsv1.Deployment{ObjectMeta: metav1.ObjectMeta{Name: resourceName, Namespace: "default"}})
+			_ = k8sClient.Delete(ctx, &corev1.Service{ObjectMeta: metav1.ObjectMeta{Name: resourceName, Namespace: "default"}})
+		})
+
+		It("should reconcile to a Deployment and Service with ownerRefs and config flags", func() {
+			controllerReconciler := &LMCacheCoordinatorReconciler{
+				Client: k8sClient,
+				Scheme: k8sClient.Scheme(),
+			}
+
+			By("Reconciling the created resource")
+			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
+				NamespacedName: typeNamespacedName,
+			})
+			Expect(err).NotTo(HaveOccurred())
+
+			By("Verifying the Deployment")
+			deploy := &appsv1.Deployment{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, deploy)).To(Succeed())
+			Expect(ownedByCoordinator(deploy.OwnerReferences)).To(BeTrue())
+
+			podSpec := deploy.Spec.Template.Spec
+			Expect(podSpec.Containers).To(HaveLen(1))
+			container := podSpec.Containers[0]
+			Expect(container.Command).To(ContainElement("coordinator"))
+			Expect(argsContainFlagValue(container.Args, "--port", "9300")).To(BeTrue())
+			// Blend knobs are omitted when unset so the coordinator image
+			// applies its own defaults (and older images stay compatible).
+			Expect(container.Args).NotTo(ContainElement("--blend-chunk-size"))
+			Expect(container.Args).NotTo(ContainElement("--blend-probe-stride"))
+
+			By("Verifying the probe targets /healthz")
+			Expect(container.ReadinessProbe).NotTo(BeNil())
+			Expect(container.ReadinessProbe.HTTPGet).NotTo(BeNil())
+			Expect(container.ReadinessProbe.HTTPGet.Path).To(Equal("/healthz"))
+
+			By("Verifying the ClusterIP Service exposes the coordinator port")
+			svc := &corev1.Service{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, svc)).To(Succeed())
+			Expect(ownedByCoordinator(svc.OwnerReferences)).To(BeTrue())
+			Expect(svc.Spec.Ports).To(HaveLen(1))
+			Expect(svc.Spec.Ports[0].Port).To(Equal(int32(9300)))
+		})
+
+		It("should converge status with ConfigValid=True and a resolved endpoint", func() {
+			controllerReconciler := &LMCacheCoordinatorReconciler{
+				Client: k8sClient,
+				Scheme: k8sClient.Scheme(),
+			}
+
+			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
+				NamespacedName: typeNamespacedName,
+			})
+			Expect(err).NotTo(HaveOccurred())
+
+			updated := &lmcachev1alpha1.LMCacheCoordinator{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, updated)).To(Succeed())
+
+			By("Verifying the ConfigValid condition is True")
+			var found bool
+			for _, cond := range updated.Status.Conditions {
+				if cond.Type == lmcachev1alpha1.ConditionConfigValid {
+					found = true
+					Expect(cond.Status).To(Equal(metav1.ConditionTrue))
+				}
+			}
+			Expect(found).To(BeTrue())
+
+			By("Verifying status fields")
+			Expect(updated.Status.ObservedGeneration).To(Equal(updated.Generation))
+			Expect(updated.Status.Endpoint).To(Equal("http://test-coordinator.default.svc:9300"))
+			// envtest has no kubelet, so no replicas are ready: phase Pending.
+			Expect(updated.Status.Phase).To(Equal(lmcachev1alpha1.PhasePending))
+		})
+
+		It("should reject an invalid spec via status", func() {
+			By("Setting an out-of-range evictionRatio")
+			resource := &lmcachev1alpha1.LMCacheCoordinator{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, resource)).To(Succeed())
+			bad := 2.0
+			resource.Spec.EvictionRatio = &bad
+			Expect(k8sClient.Update(ctx, resource)).To(Succeed())
+
+			controllerReconciler := &LMCacheCoordinatorReconciler{
+				Client: k8sClient,
+				Scheme: k8sClient.Scheme(),
+			}
+			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
+				NamespacedName: typeNamespacedName,
+			})
+			Expect(err).To(HaveOccurred())
+
+			updated := &lmcachev1alpha1.LMCacheCoordinator{}
+			Expect(k8sClient.Get(ctx, typeNamespacedName, updated)).To(Succeed())
+			Expect(updated.Status.Phase).To(Equal(lmcachev1alpha1.PhaseFailed))
+		})
+	})
+})
diff --git a/operator/internal/controller/lmcacheengine_controller.go b/operator/internal/controller/lmcacheengine_controller.go
new file mode 100644
index 0000000..f64c518
--- /dev/null
+++ b/operator/internal/controller/lmcacheengine_controller.go
@@ -0,0 +1,136 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/runtime"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+const finalizerName = "lmcache.ai/cleanup"
+
+// LMCacheEngineReconciler reconciles a LMCacheEngine object.
+type LMCacheEngineReconciler struct {
+	client.Client
+	Scheme *runtime.Scheme
+}
+
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=lmcacheengines,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=lmcacheengines/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=lmcache.lmcache.ai,resources=lmcacheengines/finalizers,verbs=update
+// +kubebuilder:rbac:groups=apps,resources=daemonsets,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups="",resources=configmaps,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups="",resources=services,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups="",resources=pods,verbs=get;list;watch
+// +kubebuilder:rbac:groups="",resources=secrets,verbs=get;list;watch;create;update;patch;delete
+// +kubebuilder:rbac:groups=monitoring.coreos.com,resources=servicemonitors,verbs=get;list;watch;create;update;patch;delete
+
+// Reconcile reconciles the LMCacheEngine CR.
+func (r *LMCacheEngineReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+	log := logf.FromContext(ctx)
+
+	// 1. Fetch CR
+	engine := &lmcachev1alpha1.LMCacheEngine{}
+	if err := r.Get(ctx, req.NamespacedName, engine); err != nil {
+		if apierrors.IsNotFound(err) {
+			return ctrl.Result{}, nil
+		}
+		return ctrl.Result{}, err
+	}
+
+	// 2. Handle finalizer
+	if err, done := r.handleFinalizer(ctx, engine); done {
+		return ctrl.Result{}, err
+	}
+
+	// 3. Set defaults
+	engine.SetDefaults()
+
+	// 4. Validate
+	if err := r.validateAndSetCondition(ctx, engine); err != nil {
+		return ctrl.Result{}, err
+	}
+
+	// 5. Reconcile RESP auth secret (cross-namespace copy if needed)
+	if err := r.reconcileRESPAuthSecret(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile RESP auth secret")
+		return ctrl.Result{}, err
+	}
+
+	// 6. Reconcile DaemonSet
+	if err := r.reconcileDaemonSet(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile DaemonSet")
+		return ctrl.Result{}, err
+	}
+
+	// 7. Reconcile lookup Service (node-local discovery for vLLM)
+	if err := r.reconcileLookupService(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile lookup Service")
+		return ctrl.Result{}, err
+	}
+
+	// 8. Reconcile metrics Service
+	if err := r.reconcileMetricsService(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile metrics Service")
+		return ctrl.Result{}, err
+	}
+
+	// 9. Reconcile ConfigMap
+	if err := r.reconcileConnectionConfigMap(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile ConfigMap")
+		return ctrl.Result{}, err
+	}
+
+	// 10. Reconcile ServiceMonitor
+	if err := r.reconcileServiceMonitor(ctx, engine); err != nil {
+		log.Error(err, "Failed to reconcile ServiceMonitor")
+		return ctrl.Result{}, err
+	}
+
+	// 11. Update status
+	if err := r.updateStatus(ctx, engine); err != nil {
+		log.Error(err, "Failed to update status")
+		return ctrl.Result{}, err
+	}
+
+	return ctrl.Result{}, nil
+}
+
+// SetupWithManager sets up the controller with the Manager.
+func (r *LMCacheEngineReconciler) SetupWithManager(mgr ctrl.Manager) error {
+	return ctrl.NewControllerManagedBy(mgr).
+		For(&lmcachev1alpha1.LMCacheEngine{}).
+		Owns(&appsv1.DaemonSet{}).
+		Owns(&corev1.ConfigMap{}).
+		Owns(&corev1.Service{}).
+		Owns(&corev1.Secret{}).
+		Named("lmcacheengine").
+		Complete(r)
+}
+
+// Ensure resources package is used (for linter).
+var _ = resources.StandardLabels
diff --git a/operator/internal/controller/lmcacheengine_controller_test.go b/operator/internal/controller/lmcacheengine_controller_test.go
new file mode 100644
index 0000000..e9b44b9
--- /dev/null
+++ b/operator/internal/controller/lmcacheengine_controller_test.go
@@ -0,0 +1,86 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+	"k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/reconcile"
+
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+var _ = Describe("LMCacheEngine Controller", func() {
+	Context("When reconciling a resource", func() {
+		const resourceName = "test-resource"
+
+		ctx := context.Background()
+
+		typeNamespacedName := types.NamespacedName{
+			Name:      resourceName,
+			Namespace: "default", // TODO(user):Modify as needed
+		}
+		lmcacheengine := &lmcachev1alpha1.LMCacheEngine{}
+
+		BeforeEach(func() {
+			By("creating the custom resource for the Kind LMCacheEngine")
+			err := k8sClient.Get(ctx, typeNamespacedName, lmcacheengine)
+			if err != nil && errors.IsNotFound(err) {
+				resource := &lmcachev1alpha1.LMCacheEngine{
+					ObjectMeta: metav1.ObjectMeta{
+						Name:      resourceName,
+						Namespace: "default",
+					},
+					Spec: lmcachev1alpha1.LMCacheEngineSpec{
+						L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+					},
+				}
+				Expect(k8sClient.Create(ctx, resource)).To(Succeed())
+			}
+		})
+
+		AfterEach(func() {
+			// TODO(user): Cleanup logic after each test, like removing the resource instance.
+			resource := &lmcachev1alpha1.LMCacheEngine{}
+			err := k8sClient.Get(ctx, typeNamespacedName, resource)
+			Expect(err).NotTo(HaveOccurred())
+
+			By("Cleanup the specific resource instance LMCacheEngine")
+			Expect(k8sClient.Delete(ctx, resource)).To(Succeed())
+		})
+		It("should successfully reconcile the resource", func() {
+			By("Reconciling the created resource")
+			controllerReconciler := &LMCacheEngineReconciler{
+				Client: k8sClient,
+				Scheme: k8sClient.Scheme(),
+			}
+
+			_, err := controllerReconciler.Reconcile(ctx, reconcile.Request{
+				NamespacedName: typeNamespacedName,
+			})
+			Expect(err).NotTo(HaveOccurred())
+			// TODO(user): Add more specific assertions depending on your controller's reconciliation logic.
+			// Example: If you expect a certain status condition after reconciliation, verify it here.
+		})
+	})
+})
diff --git a/operator/internal/controller/reconcile_helpers.go b/operator/internal/controller/reconcile_helpers.go
new file mode 100644
index 0000000..82b5bd1
--- /dev/null
+++ b/operator/internal/controller/reconcile_helpers.go
@@ -0,0 +1,508 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+	"fmt"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+// handleFinalizer migrates any LMCacheEngine carrying the legacy
+// "lmcache.ai/cleanup" finalizer off of it. Owner references on every
+// child resource (DaemonSet, Services, ConfigMap, managed Secret)
+// already cause K8s garbage collection to cascade-delete them when
+// the CR goes away, so no finalizer work is necessary today.
+//
+// Why this changed: a no-op finalizer blocks CR deletion whenever the
+// controller pod isn't running (e.g. during cluster issues or a
+// `kubectl delete -k config/default` that takes down the operator
+// alongside the CRDs), with no upside since GC already does the work.
+// See discussion in https://github.com/LMCache/LMCache/issues/2693.
+//
+// We may re-introduce a finalizer in the future for state K8s GC
+// can't reach — e.g. evicting L2 Redis keys on CR delete, federation
+// deregistration. When that happens, this function will grow real
+// cleanup work alongside the legacy migration.
+//
+// Returns (err, done). If done is true the caller must return.
+func (r *LMCacheEngineReconciler) handleFinalizer(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) (error, bool) {
+	// On the deletion path we still need to clear the legacy finalizer
+	// if a CR created by an older operator version is being deleted,
+	// otherwise K8s would block on it forever.
+	if engine.DeletionTimestamp != nil {
+		if controllerutil.ContainsFinalizer(engine, finalizerName) {
+			controllerutil.RemoveFinalizer(engine, finalizerName)
+			if err := r.Update(ctx, engine); err != nil {
+				return err, true
+			}
+		}
+		return nil, true
+	}
+
+	// Pro-active migration on the create/update path: strip the
+	// legacy finalizer from any CR that still has it from a prior
+	// operator version, so future deletes don't deadlock.
+	if controllerutil.ContainsFinalizer(engine, finalizerName) {
+		controllerutil.RemoveFinalizer(engine, finalizerName)
+		if err := r.Update(ctx, engine); err != nil {
+			return err, true
+		}
+		// Return done=true so the controller requeues with a fresh
+		// Get; continuing here would race with the resourceVersion
+		// bump the Update just produced on the server.
+		return nil, true
+	}
+
+	return nil, false
+}
+
+// validateAndSetCondition runs validation and updates the ConfigValid condition.
+// Returns an error if validation fails (to stop reconciliation).
+func (r *LMCacheEngineReconciler) validateAndSetCondition(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	errs := engine.ValidateSpec()
+
+	if len(errs) > 0 {
+		// Re-fetch to get the latest resourceVersion before status update.
+		generation := engine.Generation
+		if err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, engine); err != nil {
+			return fmt.Errorf("failed to re-fetch engine for status update: %w", err)
+		}
+		meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+			Type:               lmcachev1alpha1.ConditionConfigValid,
+			Status:             metav1.ConditionFalse,
+			Reason:             "ValidationFailed",
+			Message:            errs.ToAggregate().Error(),
+			ObservedGeneration: generation,
+		})
+		engine.Status.Phase = lmcachev1alpha1.PhaseFailed
+		engine.Status.ObservedGeneration = generation
+		if err := r.Status().Update(ctx, engine); err != nil {
+			return fmt.Errorf("failed to update status after validation failure: %w", err)
+		}
+		return fmt.Errorf("spec validation failed: %s", errs.ToAggregate().Error())
+	}
+
+	// ConfigValid=True condition is set in updateStatus (after re-fetch)
+	// to avoid resourceVersion conflicts.
+	return nil
+}
+
+// reconcileDaemonSet creates or updates the DaemonSet.
+func (r *LMCacheEngineReconciler) reconcileDaemonSet(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	// Resolve the coordinator connection (ref -> Service URL) so the DaemonSet
+	// builder emits --coordinator-url for server registration.
+	conn, err := resources.ResolveCoordinatorConnection(ctx, r.Client, engine.Namespace, engine.Spec.Coordinator)
+	if err != nil {
+		return err
+	}
+	engine.Spec.Coordinator = conn
+
+	desired := resources.BuildDaemonSet(engine)
+
+	existing := &appsv1.DaemonSet{}
+	err = r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	// Preserve immutable selector
+	desired.Spec.Selector = existing.Spec.Selector
+	desired.Spec.Template.Labels = resources.MergeLabels(
+		existing.Spec.Selector.MatchLabels,
+		desired.Spec.Template.Labels,
+	)
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Template = desired.Spec.Template
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileLookupService creates or updates the node-local lookup Service.
+func (r *LMCacheEngineReconciler) reconcileLookupService(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	desired := resources.BuildLookupService(engine)
+
+	existing := &corev1.Service{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Ports = desired.Spec.Ports
+	existing.Spec.InternalTrafficPolicy = desired.Spec.InternalTrafficPolicy
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileMetricsService creates or updates the headless metrics Service.
+func (r *LMCacheEngineReconciler) reconcileMetricsService(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	desired := resources.BuildMetricsService(engine)
+
+	existing := &corev1.Service{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec.Ports = desired.Spec.Ports
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileConnectionConfigMap creates or updates the connection ConfigMap.
+func (r *LMCacheEngineReconciler) reconcileConnectionConfigMap(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	desired := resources.BuildConnectionConfigMap(engine)
+
+	existing := &corev1.ConfigMap{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Data = desired.Data
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// reconcileServiceMonitor creates, updates, or deletes the ServiceMonitor.
+func (r *LMCacheEngineReconciler) reconcileServiceMonitor(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	log := logf.FromContext(ctx)
+
+	if !resources.ServiceMonitorEnabled(&engine.Spec) {
+		// Delete ServiceMonitor if it exists
+		existing := &monitoringv1.ServiceMonitor{}
+		err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, existing)
+		if err != nil {
+			if apierrors.IsNotFound(err) {
+				return nil
+			}
+			// If the CRD is not installed, ignore the error
+			if meta.IsNoMatchError(err) {
+				return nil
+			}
+			return err
+		}
+		log.Info("Deleting ServiceMonitor", "name", engine.Name)
+		return r.Delete(ctx, existing)
+	}
+
+	desired := resources.BuildServiceMonitor(engine)
+
+	existing := &monitoringv1.ServiceMonitor{}
+	err := r.Get(ctx, types.NamespacedName{Name: desired.Name, Namespace: desired.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			return r.Create(ctx, desired)
+		}
+		if meta.IsNoMatchError(err) {
+			log.Info("ServiceMonitor CRD not available, skipping")
+			return nil
+		}
+		return err
+	}
+
+	if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+		return err
+	}
+
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec = desired.Spec
+	existing.Labels = desired.Labels
+
+	return r.Patch(ctx, existing, patch)
+}
+
+// updateStatus queries the DaemonSet and pods to compute status fields.
+// It re-fetches the engine to get the latest resourceVersion, avoiding
+// conflicts from watch events triggered by earlier reconcile steps.
+func (r *LMCacheEngineReconciler) updateStatus(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	// Re-fetch to get the latest resourceVersion, avoiding conflicts
+	// from watch events triggered by earlier reconcile steps (e.g.
+	// DaemonSet/Service creation fires Owns watches).
+	if err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, engine); err != nil {
+		return err
+	}
+
+	// ConfigValid condition (set here after re-fetch so it's not lost).
+	meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionConfigValid,
+		Status:             metav1.ConditionTrue,
+		Reason:             "Valid",
+		Message:            "Spec validation passed",
+		ObservedGeneration: engine.Generation,
+	})
+
+	ds := &appsv1.DaemonSet{}
+	err := r.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: engine.Namespace}, ds)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			engine.Status.Phase = lmcachev1alpha1.PhasePending
+			engine.Status.DesiredInstances = 0
+			engine.Status.ReadyInstances = 0
+			engine.Status.ObservedGeneration = engine.Generation
+			return r.Status().Update(ctx, engine)
+		}
+		return err
+	}
+
+	engine.Status.DesiredInstances = ds.Status.DesiredNumberScheduled
+	engine.Status.ReadyInstances = ds.Status.NumberReady
+	engine.Status.ObservedGeneration = engine.Generation
+
+	// Compute phase
+	switch {
+	case ds.Status.DesiredNumberScheduled == 0:
+		engine.Status.Phase = lmcachev1alpha1.PhasePending
+	case ds.Status.NumberReady == ds.Status.DesiredNumberScheduled:
+		engine.Status.Phase = lmcachev1alpha1.PhaseRunning
+	case ds.Status.NumberReady > 0:
+		engine.Status.Phase = lmcachev1alpha1.PhaseDegraded
+	default:
+		engine.Status.Phase = lmcachev1alpha1.PhasePending
+	}
+
+	// Set conditions
+	meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionAvailable,
+		Status:             conditionBool(ds.Status.NumberReady > 0),
+		Reason:             reasonFromReady(ds.Status.NumberReady > 0, "AtLeastOneReady", "NoReadyInstances"),
+		Message:            fmt.Sprintf("%d/%d instances ready", ds.Status.NumberReady, ds.Status.DesiredNumberScheduled),
+		ObservedGeneration: engine.Generation,
+	})
+
+	allReady := ds.Status.NumberReady == ds.Status.DesiredNumberScheduled && ds.Status.DesiredNumberScheduled > 0
+	meta.SetStatusCondition(&engine.Status.Conditions, metav1.Condition{
+		Type:               lmcachev1alpha1.ConditionAllInstancesReady,
+		Status:             conditionBool(allReady),
+		Reason:             reasonFromReady(allReady, "AllReady", "NotAllReady"),
+		Message:            fmt.Sprintf("%d/%d instances ready", ds.Status.NumberReady, ds.Status.DesiredNumberScheduled),
+		ObservedGeneration: engine.Generation,
+	})
+
+	// Build endpoints from pods
+	serverPort := int32(5555)
+	if engine.Spec.Server != nil && engine.Spec.Server.Port != nil {
+		serverPort = *engine.Spec.Server.Port
+	}
+	metricsPort := int32(9090)
+	if engine.Spec.Prometheus != nil && engine.Spec.Prometheus.Port != nil {
+		metricsPort = *engine.Spec.Prometheus.Port
+	}
+
+	podList := &corev1.PodList{}
+	if err := r.List(ctx, podList,
+		client.InNamespace(engine.Namespace),
+		client.MatchingLabels(resources.SelectorLabels(engine.Name)),
+	); err != nil {
+		return err
+	}
+
+	endpoints := make([]lmcachev1alpha1.EndpointStatus, 0, len(podList.Items))
+	for i := range podList.Items {
+		pod := &podList.Items[i]
+		ready := false
+		for _, cond := range pod.Status.Conditions {
+			if cond.Type == corev1.PodReady && cond.Status == corev1.ConditionTrue {
+				ready = true
+				break
+			}
+		}
+		endpoints = append(endpoints, lmcachev1alpha1.EndpointStatus{
+			NodeName:    pod.Spec.NodeName,
+			HostIP:      pod.Status.HostIP,
+			PodName:     pod.Name,
+			Port:        serverPort,
+			MetricsPort: metricsPort,
+			Ready:       ready,
+		})
+	}
+	engine.Status.Endpoints = endpoints
+
+	return r.Status().Update(ctx, engine)
+}
+
+func conditionBool(b bool) metav1.ConditionStatus {
+	if b {
+		return metav1.ConditionTrue
+	}
+	return metav1.ConditionFalse
+}
+
+func reasonFromReady(ready bool, trueReason, falseReason string) string {
+	if ready {
+		return trueReason
+	}
+	return falseReason
+}
+
+// reconcileRESPAuthSecret ensures a local copy of the RESP auth secret
+// exists in the engine's namespace. If the source secret is in the same
+// namespace, the DaemonSet references it directly via a managed copy.
+// If cross-namespace, the operator reads the source and creates/updates
+// a managed copy with ownerRef on the engine.
+func (r *LMCacheEngineReconciler) reconcileRESPAuthSecret(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	log := logf.FromContext(ctx)
+	spec := &engine.Spec
+
+	// No RESP auth configured — clean up any stale managed secret.
+	if spec.L2Backend == nil || spec.L2Backend.RESP == nil || spec.L2Backend.RESP.AuthSecretRef == nil {
+		return r.deleteRESPAuthSecretIfExists(ctx, engine)
+	}
+
+	ref := spec.L2Backend.RESP.AuthSecretRef
+	sourceNS := ref.Namespace
+	if sourceNS == "" {
+		sourceNS = engine.Namespace
+	}
+	localName := resources.RESPAuthSecretName(engine.Name)
+
+	// Read the source secret.
+	source := &corev1.Secret{}
+	if err := r.Get(ctx, types.NamespacedName{Name: ref.Name, Namespace: sourceNS}, source); err != nil {
+		return fmt.Errorf("failed to read RESP auth secret %s/%s: %w", sourceNS, ref.Name, err)
+	}
+
+	// Validate that the source secret contains the required "password" key.
+	password, ok := source.Data["password"]
+	if !ok || len(password) == 0 {
+		return fmt.Errorf("RESP auth secret %s/%s is missing required 'password' key", sourceNS, ref.Name)
+	}
+
+	// Build the local managed copy.
+	// Only "password" is required; "username" is optional (Redis Enterprise
+	// often uses password-only auth).
+	secretData := map[string][]byte{
+		"password": password,
+	}
+	if u, ok := source.Data["username"]; ok {
+		secretData["username"] = u
+	}
+	desired := &corev1.Secret{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      localName,
+			Namespace: engine.Namespace,
+			Labels:    resources.StandardLabels(engine.Name),
+		},
+		Data: secretData,
+	}
+
+	existing := &corev1.Secret{}
+	err := r.Get(ctx, types.NamespacedName{Name: localName, Namespace: engine.Namespace}, existing)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			if err := ctrl.SetControllerReference(engine, desired, r.Scheme); err != nil {
+				return err
+			}
+			log.Info("Creating managed RESP auth secret", "name", localName, "source", sourceNS+"/"+ref.Name)
+			return r.Create(ctx, desired)
+		}
+		return err
+	}
+
+	// Update existing — apply ownerRef, data, and labels.
+	if err := ctrl.SetControllerReference(engine, existing, r.Scheme); err != nil {
+		return err
+	}
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Data = desired.Data
+	existing.Labels = desired.Labels
+	return r.Patch(ctx, existing, patch)
+}
+
+// deleteRESPAuthSecretIfExists removes the managed RESP auth secret
+// if it exists (e.g. when authSecretRef is removed from the spec).
+func (r *LMCacheEngineReconciler) deleteRESPAuthSecretIfExists(ctx context.Context, engine *lmcachev1alpha1.LMCacheEngine) error {
+	secret := &corev1.Secret{}
+	name := resources.RESPAuthSecretName(engine.Name)
+	err := r.Get(ctx, types.NamespacedName{Name: name, Namespace: engine.Namespace}, secret)
+	if err != nil {
+		if apierrors.IsNotFound(err) {
+			return nil
+		}
+		return err
+	}
+	// Only delete if we own it.
+	if metav1.IsControlledBy(secret, engine) {
+		return r.Delete(ctx, secret)
+	}
+	return nil
+}
diff --git a/operator/internal/controller/reconcile_helpers_test.go b/operator/internal/controller/reconcile_helpers_test.go
new file mode 100644
index 0000000..a822a4e
--- /dev/null
+++ b/operator/internal/controller/reconcile_helpers_test.go
@@ -0,0 +1,741 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"fmt"
+	"sync/atomic"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+// nsSeq is a monotonic counter appended to every generated namespace
+// name so concurrent specs (or repeated runs against the same envtest
+// API server within a suite) never collide. envtest doesn't garbage-
+// collect a deleted namespace's children, so per-spec namespaces
+// double as a cheap form of test isolation.
+var nsSeq atomic.Int64
+
+// uniqueNS returns a fresh namespace name unique within this test
+// process. The prefix makes it easy to spot the source of a stray
+// object if a test crashes mid-flight.
+func uniqueNS(prefix string) string {
+	return fmt.Sprintf("%s-%d", prefix, nsSeq.Add(1))
+}
+
+// mustCreateNS creates a namespace and registers cleanup. Returns the
+// name so callers can put resources in it. We don't rely on namespace
+// teardown to clean the contents — envtest leaves them as Terminating
+// without ever finalising the delete — so individual tests still must
+// register cleanup for each resource they create.
+func mustCreateNS(name string) string {
+	GinkgoHelper()
+	ns := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: name}}
+	Expect(k8sClient.Create(ctx, ns)).To(Succeed())
+	DeferCleanup(func() {
+		// Best-effort namespace delete. Don't fail the test on errors
+		// — the suite tears down the whole apiserver after AfterSuite
+		// anyway.
+		_ = k8sClient.Delete(ctx, ns)
+	})
+	return name
+}
+
+// newEngine builds an LMCacheEngine fixture and Creates it in the
+// cluster (which populates APIVersion / Kind / UID — required for
+// ctrl.SetControllerReference to work in the function-under-test).
+// Returns the Created object so callers can mutate Spec further.
+func newEngine(namespace, name string) *lmcachev1alpha1.LMCacheEngine {
+	GinkgoHelper()
+	e := &lmcachev1alpha1.LMCacheEngine{
+		ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: namespace},
+		Spec:       lmcachev1alpha1.LMCacheEngineSpec{L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10}},
+	}
+	Expect(k8sClient.Create(ctx, e)).To(Succeed())
+	DeferCleanup(func() { _ = k8sClient.Delete(ctx, e) })
+	// Re-fetch so TypeMeta is populated for SetControllerReference.
+	Expect(k8sClient.Get(ctx, types.NamespacedName{Name: name, Namespace: namespace}, e)).To(Succeed())
+	return e
+}
+
+// newReconciler wires a LMCacheEngineReconciler around the suite's
+// envtest client. Kept as a one-liner because every spec needs one.
+func newReconciler() *LMCacheEngineReconciler {
+	return &LMCacheEngineReconciler{Client: k8sClient, Scheme: k8sClient.Scheme()}
+}
+
+// ----- pure helpers (no envtest) -----------------------------------
+
+var _ = Describe("conditionBool", func() {
+	It("maps true → ConditionTrue and false → ConditionFalse", func() {
+		Expect(conditionBool(true)).To(Equal(metav1.ConditionTrue))
+		Expect(conditionBool(false)).To(Equal(metav1.ConditionFalse))
+	})
+})
+
+var _ = Describe("reasonFromReady", func() {
+	It("returns the true-reason when ready, the false-reason otherwise", func() {
+		Expect(reasonFromReady(true, "Ready", "NotReady")).To(Equal("Ready"))
+		Expect(reasonFromReady(false, "Ready", "NotReady")).To(Equal("NotReady"))
+	})
+})
+
+// ----- reconcileRESPAuthSecret -------------------------------------
+
+var _ = Describe("reconcileRESPAuthSecret", func() {
+	var (
+		r          *LMCacheEngineReconciler
+		nsName     string
+		engineName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("resp-auth"))
+		engineName = "test-engine"
+	})
+
+	It("no-ops when authSecretRef is nil", func() {
+		// Cover the early-return branch: L2Backend.RESP.AuthSecretRef
+		// nil means there's nothing to mirror, AND the call should
+		// also clean up any stale managed secret (delegated to
+		// deleteRESPAuthSecretIfExists).
+		engine := newEngine(nsName, engineName)
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		// No managed secret should have been created.
+		got := &corev1.Secret{}
+		err := k8sClient.Get(ctx, types.NamespacedName{
+			Name:      resources.RESPAuthSecretName(engineName),
+			Namespace: nsName,
+		}, got)
+		Expect(apierrors.IsNotFound(err)).To(BeTrue(), "expected NotFound, got %v", err)
+	})
+
+	It("deletes a stale managed secret when authSecretRef is removed", func() {
+		// Pre-create a managed secret owned by the engine, simulating
+		// a previous reconcile that wired up auth. Then drop the spec
+		// reference and confirm the helper cleans up. Use the
+		// controllerutil helper to wire the OwnerReference via the
+		// scheme — manually-built refs miss APIVersion/Kind because
+		// envtest's client doesn't populate TypeMeta on Get.
+		engine := newEngine(nsName, engineName)
+		stale := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      resources.RESPAuthSecretName(engineName),
+				Namespace: nsName,
+			},
+			Data: map[string][]byte{"password": []byte("old")},
+		}
+		Expect(controllerutil.SetControllerReference(engine, stale, k8sClient.Scheme())).To(Succeed())
+		Expect(k8sClient.Create(ctx, stale)).To(Succeed())
+
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		// Stale managed secret must be gone.
+		err := k8sClient.Get(ctx, types.NamespacedName{Name: stale.Name, Namespace: nsName}, &corev1.Secret{})
+		Expect(apierrors.IsNotFound(err)).To(BeTrue(), "expected stale managed secret to be deleted, got err=%v", err)
+	})
+
+	It("leaves a non-owned secret of the same name alone", func() {
+		// Defensive: if an admin pre-created a Secret at the managed
+		// name without an ownerRef, the operator must NOT delete it
+		// — that's user data. deleteRESPAuthSecretIfExists checks
+		// IsControlledBy and bails out on false.
+		engine := newEngine(nsName, engineName)
+		unrelated := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      resources.RESPAuthSecretName(engineName),
+				Namespace: nsName,
+				// No OwnerReferences: this Secret is not "owned" by anyone.
+			},
+			Data: map[string][]byte{"password": []byte("user-owned")},
+		}
+		Expect(k8sClient.Create(ctx, unrelated)).To(Succeed())
+		DeferCleanup(func() { _ = k8sClient.Delete(ctx, unrelated) })
+
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		// Still there.
+		got := &corev1.Secret{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: unrelated.Name, Namespace: nsName}, got)).To(Succeed())
+		Expect(got.Data["password"]).To(Equal([]byte("user-owned")))
+	})
+
+	It("creates a managed copy when the source secret exists (same-namespace)", func() {
+		engine := newEngine(nsName, engineName)
+		source := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{Name: "redis-auth", Namespace: nsName},
+			Data: map[string][]byte{
+				"username": []byte("admin"),
+				"password": []byte("s3cret"), // pragma: allowlist secret
+			},
+		}
+		Expect(k8sClient.Create(ctx, source)).To(Succeed())
+		DeferCleanup(func() { _ = k8sClient.Delete(ctx, source) })
+
+		engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host:          "redis",
+				Port:          6379,
+				AuthSecretRef: &lmcachev1alpha1.SecretReference{Name: "redis-auth"},
+			},
+		}
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		got := &corev1.Secret{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{
+			Name:      resources.RESPAuthSecretName(engineName),
+			Namespace: nsName,
+		}, got)).To(Succeed())
+		Expect(got.Data).To(HaveKeyWithValue("password", []byte("s3cret")))
+		Expect(got.Data).To(HaveKeyWithValue("username", []byte("admin")))
+		Expect(metav1.IsControlledBy(got, engine)).To(BeTrue(), "managed secret must be owned by the engine")
+	})
+
+	It("creates a managed copy from a cross-namespace source", func() {
+		// The whole point of this helper — pulling a Secret from
+		// another namespace and mirroring it. Use a separate source
+		// namespace to prove the cross-NS read path executes.
+		sourceNS := mustCreateNS(uniqueNS("resp-auth-src"))
+		engine := newEngine(nsName, engineName)
+		source := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{Name: "shared-redis-auth", Namespace: sourceNS},
+			Data:       map[string][]byte{"password": []byte("xns-pw")}, // pragma: allowlist secret
+		}
+		Expect(k8sClient.Create(ctx, source)).To(Succeed())
+		DeferCleanup(func() { _ = k8sClient.Delete(ctx, source) })
+
+		engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis",
+				Port: 6379,
+				AuthSecretRef: &lmcachev1alpha1.SecretReference{
+					Name:      "shared-redis-auth",
+					Namespace: sourceNS,
+				},
+			},
+		}
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		got := &corev1.Secret{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{
+			Name:      resources.RESPAuthSecretName(engineName),
+			Namespace: nsName, // mirror lands in the engine's namespace, not the source's
+		}, got)).To(Succeed())
+		Expect(got.Data).To(HaveKeyWithValue("password", []byte("xns-pw")))
+		Expect(got.Data).NotTo(HaveKey("username"), "username should be absent when source omits it")
+	})
+
+	It("updates an existing managed copy when the source password changes", func() {
+		// First reconcile establishes the mirror; second reconcile
+		// after a source-side rotation must update the managed copy.
+		// This exercises the Patch path (separate from the Create
+		// path the previous spec covers).
+		engine := newEngine(nsName, engineName)
+		source := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{Name: "rotate-auth", Namespace: nsName},
+			Data:       map[string][]byte{"password": []byte("v1")},
+		}
+		Expect(k8sClient.Create(ctx, source)).To(Succeed())
+		DeferCleanup(func() { _ = k8sClient.Delete(ctx, source) })
+
+		engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis", Port: 6379,
+				AuthSecretRef: &lmcachev1alpha1.SecretReference{Name: "rotate-auth"},
+			},
+		}
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		// Rotate the source.
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: "rotate-auth", Namespace: nsName}, source)).To(Succeed())
+		source.Data["password"] = []byte("v2")
+		Expect(k8sClient.Update(ctx, source)).To(Succeed())
+
+		// Re-reconcile should propagate.
+		Expect(r.reconcileRESPAuthSecret(ctx, engine)).To(Succeed())
+
+		got := &corev1.Secret{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{
+			Name:      resources.RESPAuthSecretName(engineName),
+			Namespace: nsName,
+		}, got)).To(Succeed())
+		Expect(got.Data).To(HaveKeyWithValue("password", []byte("v2")))
+	})
+
+	It("errors when the source secret is missing", func() {
+		engine := newEngine(nsName, engineName)
+		engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis", Port: 6379,
+				AuthSecretRef: &lmcachev1alpha1.SecretReference{Name: "does-not-exist"},
+			},
+		}
+		err := r.reconcileRESPAuthSecret(ctx, engine)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("does-not-exist"))
+	})
+
+	It("errors when the source secret is missing the password key", func() {
+		// Defensive against operator mis-configuration: a Secret
+		// pointed at by authSecretRef MUST have a "password" entry.
+		// If it doesn't, surface a clear error rather than write a
+		// broken managed copy.
+		engine := newEngine(nsName, engineName)
+		source := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{Name: "wrong-keys", Namespace: nsName},
+			// "password" missing; only "user" provided.
+			Data: map[string][]byte{"user": []byte("admin")},
+		}
+		Expect(k8sClient.Create(ctx, source)).To(Succeed())
+		DeferCleanup(func() { _ = k8sClient.Delete(ctx, source) })
+
+		engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis", Port: 6379,
+				AuthSecretRef: &lmcachev1alpha1.SecretReference{Name: "wrong-keys"},
+			},
+		}
+		err := r.reconcileRESPAuthSecret(ctx, engine)
+		Expect(err).To(HaveOccurred())
+		Expect(err.Error()).To(ContainSubstring("password"))
+	})
+})
+
+// ----- handleFinalizer ---------------------------------------------
+
+var _ = Describe("handleFinalizer", func() {
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("finalizer"))
+	})
+
+	It("is a no-op on a fresh CR without the legacy finalizer", func() {
+		engine := newEngine(nsName, "fresh")
+		err, done := r.handleFinalizer(ctx, engine)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(done).To(BeFalse(), "fresh CR should not short-circuit reconcile")
+	})
+
+	It("strips the legacy finalizer on the create/update path and requeues", func() {
+		// Old-operator CRs may still carry the lmcache.ai/cleanup
+		// finalizer. handleFinalizer must remove it so future
+		// deletes don't deadlock. Per the source comment, the
+		// function returns done=true after the strip so the caller
+		// re-fetches with the new resourceVersion.
+		engine := newEngine(nsName, "legacy")
+		engine.Finalizers = []string{finalizerName}
+		Expect(k8sClient.Update(ctx, engine)).To(Succeed())
+		// Re-fetch to pick up the resourceVersion bump.
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)).To(Succeed())
+
+		err, done := r.handleFinalizer(ctx, engine)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(done).To(BeTrue(), "expected the caller to short-circuit after the migration")
+
+		// Confirm the finalizer is gone in the server's view.
+		out := &lmcachev1alpha1.LMCacheEngine{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, out)).To(Succeed())
+		Expect(out.Finalizers).NotTo(ContainElement(finalizerName))
+	})
+
+	It("clears the legacy finalizer on the deletion path", func() {
+		// envtest's API server enforces the same "blocks deletion
+		// while finalizers exist" semantics as a real cluster. So
+		// Create with the legacy finalizer, Delete (which sets
+		// DeletionTimestamp but does not actually remove the
+		// object), then call handleFinalizer and verify the
+		// finalizer is cleared so the API server can finish the GC.
+		engine := newEngine(nsName, "deleting")
+		engine.Finalizers = []string{finalizerName}
+		Expect(k8sClient.Update(ctx, engine)).To(Succeed())
+		Expect(k8sClient.Delete(ctx, engine)).To(Succeed())
+
+		// Re-fetch — the object is still there (Terminating), with
+		// DeletionTimestamp set, because the finalizer blocks GC.
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)).To(Succeed())
+		Expect(engine.DeletionTimestamp).NotTo(BeNil())
+
+		err, done := r.handleFinalizer(ctx, engine)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(done).To(BeTrue(), "on the deletion path the caller must short-circuit")
+
+		// After the finalizer is removed the API server reaps the
+		// object; the Get may either return NotFound or, if envtest
+		// is mid-flight, the object with an empty finalizer list.
+		// Either is acceptable.
+		out := &lmcachev1alpha1.LMCacheEngine{}
+		err = k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, out)
+		if err == nil {
+			Expect(out.Finalizers).NotTo(ContainElement(finalizerName))
+		} else {
+			Expect(apierrors.IsNotFound(err)).To(BeTrue())
+		}
+	})
+
+	It("is a no-op on the deletion path when no legacy finalizer is present", func() {
+		// Newer CRs that never had the legacy finalizer should still
+		// short-circuit the rest of reconcile on the deletion path,
+		// but without an Update call.
+		engine := newEngine(nsName, "del-clean")
+		Expect(k8sClient.Delete(ctx, engine)).To(Succeed())
+
+		// On envtest without finalizers, the object may already be
+		// gone after Delete. Re-fetch tolerantly.
+		err := k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)
+		if apierrors.IsNotFound(err) {
+			Skip("envtest GC'd the object before we could run handleFinalizer; nothing to assert")
+		}
+		Expect(err).NotTo(HaveOccurred())
+		Expect(engine.DeletionTimestamp).NotTo(BeNil())
+
+		err, done := r.handleFinalizer(ctx, engine)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(done).To(BeTrue())
+	})
+})
+
+// ----- validateAndSetCondition -------------------------------------
+
+var _ = Describe("validateAndSetCondition", func() {
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("validate"))
+	})
+
+	It("returns nil and does NOT set ConfigValid for a valid spec", func() {
+		// Per the source comment, on the happy path the helper does
+		// NOT set ConfigValid=True itself — that happens later in
+		// updateStatus to avoid a resourceVersion conflict. So a
+		// valid spec leaves the condition list untouched here.
+		engine := newEngine(nsName, "good")
+		Expect(r.validateAndSetCondition(ctx, engine)).To(Succeed())
+
+		got := &lmcachev1alpha1.LMCacheEngine{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, got)).To(Succeed())
+		Expect(meta.FindStatusCondition(got.Status.Conditions, lmcachev1alpha1.ConditionConfigValid)).To(BeNil())
+	})
+
+	It("sets ConfigValid=False with ValidationFailed reason on an invalid spec", func() {
+		// Build a CR that bypasses kubebuilder's CRD-level checks
+		// (otherwise the API server would reject it at admission)
+		// but trips ValidateSpec's L2-backend rule.
+		engine := newEngine(nsName, "bad")
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)).To(Succeed())
+		engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+			// Both RESP and Raw set — ValidateSpec rejects this as
+			// "exactly one of resp or raw must be set, got multiple".
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{Host: "redis", Port: 6379},
+			Raw:  &lmcachev1alpha1.RawL2AdapterSpec{Type: "mock"},
+		}
+		Expect(k8sClient.Update(ctx, engine)).To(Succeed())
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)).To(Succeed())
+
+		err := r.validateAndSetCondition(ctx, engine)
+		Expect(err).To(HaveOccurred(), "expected validateAndSetCondition to return the validation error")
+
+		// Status condition must be set to False with the documented
+		// reason; phase moves to Failed.
+		got := &lmcachev1alpha1.LMCacheEngine{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, got)).To(Succeed())
+		cond := meta.FindStatusCondition(got.Status.Conditions, lmcachev1alpha1.ConditionConfigValid)
+		Expect(cond).NotTo(BeNil())
+		Expect(cond.Status).To(Equal(metav1.ConditionFalse))
+		Expect(cond.Reason).To(Equal("ValidationFailed"))
+		Expect(got.Status.Phase).To(Equal(lmcachev1alpha1.PhaseFailed))
+		Expect(got.Status.ObservedGeneration).To(Equal(got.Generation))
+	})
+})
+
+// ----- reconcileServiceMonitor -------------------------------------
+
+var _ = Describe("reconcileServiceMonitor", func() {
+	// NOTE: envtest in this suite does NOT install the
+	// monitoring.coreos.com ServiceMonitor CRD (CRDDirectoryPaths
+	// only points at config/crd/bases, which is just the
+	// LMCacheEngine CRD). So we exercise the two branches that
+	// don't require the CRD: (a) ServiceMonitor disabled and
+	// nothing to clean up, and (b) ServiceMonitor enabled but the
+	// CRD is absent (the meta.IsNoMatchError branch). The
+	// create / update / delete paths against a real ServiceMonitor
+	// are covered by the e2e suite (S-3 / ServiceMonitor spec).
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("smon"))
+	})
+
+	It("no-ops when ServiceMonitor is disabled and nothing exists", func() {
+		engine := newEngine(nsName, "no-mon")
+		// Default spec has prometheus.serviceMonitor.enabled = nil
+		// (i.e. disabled), so the helper enters the "delete if
+		// exists" branch, hits NotFound or NoMatch, and returns nil.
+		Expect(r.reconcileServiceMonitor(ctx, engine)).To(Succeed())
+	})
+
+	It("returns nil when ServiceMonitor is enabled but the CRD is absent", func() {
+		// On clusters without prometheus-operator the create path
+		// must short-circuit cleanly so the rest of reconcile
+		// continues. The CRD-absent case surfaces as
+		// meta.IsNoMatchError, which the helper swallows.
+		engine := newEngine(nsName, "enabled-no-crd")
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)).To(Succeed())
+		enabled := true
+		engine.Spec.Prometheus = &lmcachev1alpha1.PrometheusSpec{
+			Enabled: &enabled,
+			ServiceMonitor: &lmcachev1alpha1.ServiceMonitorSpec{
+				Enabled: &enabled,
+			},
+		}
+		Expect(k8sClient.Update(ctx, engine)).To(Succeed())
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, engine)).To(Succeed())
+
+		Expect(r.reconcileServiceMonitor(ctx, engine)).To(Succeed())
+	})
+})
+
+// ----- resource-reconcile helpers (Create + Patch) -----------------
+//
+// All four functions (reconcileDaemonSet / reconcileLookupService /
+// reconcileMetricsService / reconcileConnectionConfigMap) share the
+// same shape:
+//
+//   1. Build desired via resources.BuildX(engine).
+//   2. r.Get the existing — if NotFound, Create with ownerRef.
+//   3. Otherwise Patch the subset of fields the helper owns.
+//
+// Each Describe below pairs a "create on first reconcile" spec with
+// a "patch on second reconcile after a spec change" spec — that pair
+// covers both branches and proves the diff actually propagates to
+// the child resource (the helper isn't a no-op patch).
+
+var _ = Describe("reconcileDaemonSet", func() {
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("ds"))
+	})
+
+	It("creates a DaemonSet on first reconcile", func() {
+		engine := newEngine(nsName, "ds-create")
+		Expect(r.reconcileDaemonSet(ctx, engine)).To(Succeed())
+
+		got := &appsv1.DaemonSet{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, got)).To(Succeed())
+		Expect(metav1.IsControlledBy(got, engine)).To(BeTrue(), "DaemonSet must be owned by the engine")
+		Expect(got.Spec.Template.Spec.Containers).To(HaveLen(1))
+		// Default port flows through to the container args.
+		Expect(got.Spec.Template.Spec.Containers[0].Args).To(ContainElements("--port", "5555"))
+	})
+
+	It("patches the DaemonSet when spec.server.port changes", func() {
+		engine := newEngine(nsName, "ds-patch")
+		Expect(r.reconcileDaemonSet(ctx, engine)).To(Succeed())
+
+		// Mutate the local engine — reconcileDaemonSet works off the
+		// passed-in object, no need to round-trip through Update.
+		newPort := int32(6555)
+		engine.Spec.Server = &lmcachev1alpha1.ServerSpec{Port: &newPort}
+		Expect(r.reconcileDaemonSet(ctx, engine)).To(Succeed())
+
+		got := &appsv1.DaemonSet{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, got)).To(Succeed())
+		Expect(got.Spec.Template.Spec.Containers[0].Args).To(ContainElements("--port", "6555"))
+		// Existing object's selector is preserved across the patch
+		// (DaemonSet selectors are immutable; reconcileDaemonSet
+		// copies it onto desired before patching).
+		Expect(got.Spec.Selector).NotTo(BeNil())
+	})
+})
+
+var _ = Describe("reconcileLookupService", func() {
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("svc-lookup"))
+	})
+
+	It("creates the lookup Service on first reconcile", func() {
+		engine := newEngine(nsName, "svc-create")
+		Expect(r.reconcileLookupService(ctx, engine)).To(Succeed())
+
+		got := &corev1.Service{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, got)).To(Succeed())
+		Expect(metav1.IsControlledBy(got, engine)).To(BeTrue())
+		Expect(got.Spec.InternalTrafficPolicy).NotTo(BeNil())
+		Expect(*got.Spec.InternalTrafficPolicy).To(Equal(corev1.ServiceInternalTrafficPolicyLocal))
+		// Default port is exposed under a port named "server".
+		hasServerPort := false
+		for _, p := range got.Spec.Ports {
+			if p.Name == "server" && p.Port == 5555 {
+				hasServerPort = true
+			}
+		}
+		Expect(hasServerPort).To(BeTrue(), "expected a 'server' port at 5555, got %+v", got.Spec.Ports)
+	})
+
+	It("patches the lookup Service when spec.server.port changes", func() {
+		engine := newEngine(nsName, "svc-patch")
+		Expect(r.reconcileLookupService(ctx, engine)).To(Succeed())
+
+		newPort := int32(7777)
+		engine.Spec.Server = &lmcachev1alpha1.ServerSpec{Port: &newPort}
+		Expect(r.reconcileLookupService(ctx, engine)).To(Succeed())
+
+		got := &corev1.Service{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name, Namespace: nsName}, got)).To(Succeed())
+		hasNewPort := false
+		for _, p := range got.Spec.Ports {
+			if p.Name == "server" && p.Port == newPort {
+				hasNewPort = true
+			}
+		}
+		Expect(hasNewPort).To(BeTrue(), "expected 'server' port to reflect the new value, got %+v", got.Spec.Ports)
+	})
+})
+
+var _ = Describe("reconcileMetricsService", func() {
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("svc-metrics"))
+	})
+
+	It("creates the metrics Service on first reconcile", func() {
+		engine := newEngine(nsName, "metrics-create")
+		Expect(r.reconcileMetricsService(ctx, engine)).To(Succeed())
+
+		// resources.BuildMetricsService names the service
+		// "<engine>-metrics" (see internal/resources/service.go).
+		got := &corev1.Service{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{
+			Name:      engine.Name + "-metrics",
+			Namespace: nsName,
+		}, got)).To(Succeed())
+		Expect(metav1.IsControlledBy(got, engine)).To(BeTrue())
+		hasMetricsPort := false
+		for _, p := range got.Spec.Ports {
+			if p.Port == 9090 {
+				hasMetricsPort = true
+			}
+		}
+		Expect(hasMetricsPort).To(BeTrue(), "expected port 9090, got %+v", got.Spec.Ports)
+	})
+
+	It("patches the metrics Service when spec.prometheus.port changes", func() {
+		engine := newEngine(nsName, "metrics-patch")
+		Expect(r.reconcileMetricsService(ctx, engine)).To(Succeed())
+
+		newPort := int32(9191)
+		engine.Spec.Prometheus = &lmcachev1alpha1.PrometheusSpec{Port: &newPort}
+		Expect(r.reconcileMetricsService(ctx, engine)).To(Succeed())
+
+		got := &corev1.Service{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{Name: engine.Name + "-metrics", Namespace: nsName}, got)).To(Succeed())
+		hasNewPort := false
+		for _, p := range got.Spec.Ports {
+			if p.Port == newPort {
+				hasNewPort = true
+			}
+		}
+		Expect(hasNewPort).To(BeTrue(), "expected port %d, got %+v", newPort, got.Spec.Ports)
+	})
+})
+
+var _ = Describe("reconcileConnectionConfigMap", func() {
+	var (
+		r      *LMCacheEngineReconciler
+		nsName string
+	)
+
+	BeforeEach(func() {
+		r = newReconciler()
+		nsName = mustCreateNS(uniqueNS("cm"))
+	})
+
+	It("creates the connection ConfigMap on first reconcile", func() {
+		engine := newEngine(nsName, "cm-create")
+		Expect(r.reconcileConnectionConfigMap(ctx, engine)).To(Succeed())
+
+		got := &corev1.ConfigMap{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{
+			Name:      engine.Name + "-connection",
+			Namespace: nsName,
+		}, got)).To(Succeed())
+		Expect(metav1.IsControlledBy(got, engine)).To(BeTrue())
+		Expect(got.Data).To(HaveKey("kv-transfer-config.json"))
+		// Default port (5555) shows up in the JSON blob.
+		Expect(got.Data["kv-transfer-config.json"]).To(ContainSubstring("5555"))
+	})
+
+	It("patches the ConfigMap when spec.server.port changes", func() {
+		engine := newEngine(nsName, "cm-patch")
+		Expect(r.reconcileConnectionConfigMap(ctx, engine)).To(Succeed())
+
+		newPort := int32(6555)
+		engine.Spec.Server = &lmcachev1alpha1.ServerSpec{Port: &newPort}
+		Expect(r.reconcileConnectionConfigMap(ctx, engine)).To(Succeed())
+
+		got := &corev1.ConfigMap{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName{
+			Name:      engine.Name + "-connection",
+			Namespace: nsName,
+		}, got)).To(Succeed())
+		Expect(got.Data["kv-transfer-config.json"]).To(ContainSubstring("6555"))
+		Expect(got.Data["kv-transfer-config.json"]).NotTo(ContainSubstring("\"5555\""),
+			"old port should be replaced, not appended")
+	})
+})
diff --git a/operator/internal/controller/suite_test.go b/operator/internal/controller/suite_test.go
new file mode 100644
index 0000000..67d2489
--- /dev/null
+++ b/operator/internal/controller/suite_test.go
@@ -0,0 +1,122 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package controller
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	"k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/client-go/rest"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/envtest"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+	"sigs.k8s.io/controller-runtime/pkg/log/zap"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	// +kubebuilder:scaffold:imports
+)
+
+// These tests use Ginkgo (BDD-style Go testing framework). Refer to
+// http://onsi.github.io/ginkgo/ to learn more about Ginkgo.
+
+var (
+	ctx       context.Context
+	cancel    context.CancelFunc
+	testEnv   *envtest.Environment
+	cfg       *rest.Config
+	k8sClient client.Client
+)
+
+func TestControllers(t *testing.T) {
+	RegisterFailHandler(Fail)
+
+	RunSpecs(t, "Controller Suite")
+}
+
+var _ = BeforeSuite(func() {
+	logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))
+
+	ctx, cancel = context.WithCancel(context.TODO())
+
+	var err error
+	err = lmcachev1alpha1.AddToScheme(scheme.Scheme)
+	Expect(err).NotTo(HaveOccurred())
+
+	err = monitoringv1.AddToScheme(scheme.Scheme)
+	Expect(err).NotTo(HaveOccurred())
+
+	// +kubebuilder:scaffold:scheme
+
+	By("bootstrapping test environment")
+	testEnv = &envtest.Environment{
+		CRDDirectoryPaths:     []string{filepath.Join("..", "..", "config", "crd", "bases")},
+		ErrorIfCRDPathMissing: true,
+	}
+
+	// Retrieve the first found binary directory to allow running tests from IDEs
+	if getFirstFoundEnvTestBinaryDir() != "" {
+		testEnv.BinaryAssetsDirectory = getFirstFoundEnvTestBinaryDir()
+	}
+
+	// cfg is defined in this file globally.
+	cfg, err = testEnv.Start()
+	Expect(err).NotTo(HaveOccurred())
+	Expect(cfg).NotTo(BeNil())
+
+	k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
+	Expect(err).NotTo(HaveOccurred())
+	Expect(k8sClient).NotTo(BeNil())
+})
+
+var _ = AfterSuite(func() {
+	By("tearing down the test environment")
+	cancel()
+	Eventually(func() error {
+		return testEnv.Stop()
+	}, time.Minute, time.Second).Should(Succeed())
+})
+
+// getFirstFoundEnvTestBinaryDir locates the first binary in the specified path.
+// ENVTEST-based tests depend on specific binaries, usually located in paths set by
+// controller-runtime. When running tests directly (e.g., via an IDE) without using
+// Makefile targets, the 'BinaryAssetsDirectory' must be explicitly configured.
+//
+// This function streamlines the process by finding the required binaries, similar to
+// setting the 'KUBEBUILDER_ASSETS' environment variable. To ensure the binaries are
+// properly set up, run 'make setup-envtest' beforehand.
+func getFirstFoundEnvTestBinaryDir() string {
+	basePath := filepath.Join("..", "..", "bin", "k8s")
+	entries, err := os.ReadDir(basePath)
+	if err != nil {
+		logf.Log.Error(err, "Failed to read directory", "path", basePath)
+		return ""
+	}
+	for _, entry := range entries {
+		if entry.IsDir() {
+			return filepath.Join(basePath, entry.Name())
+		}
+	}
+	return ""
+}
diff --git a/operator/internal/resources/cacheblend_engine.go b/operator/internal/resources/cacheblend_engine.go
new file mode 100644
index 0000000..b27e16d
--- /dev/null
+++ b/operator/internal/resources/cacheblend_engine.go
@@ -0,0 +1,187 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+const (
+	// cbEngineType is the value of the --engine-type flag that selects the
+	// CacheBlend V3 engine on the lmcache server binary. The server maps the
+	// value "blend" to BlendV3Module; "blend_v3" is no longer recognized
+	// (lmcache/v1/multiprocess/server.py).
+	cbEngineType = "blend"
+
+	// cbL1AlignBytes is the value of the --l1-align-bytes flag required by the
+	// blend server (blend_server.sh:31).
+	cbL1AlignBytes = "16777216"
+
+	// cbDefaultImageRepo is the default engine image repository. CacheBlend runs
+	// the same lmcache server binary as LMCacheEngine, so it shares the default
+	// image; a private blend image is set via spec.image.
+	cbDefaultImageRepo = "lmcache/vllm-openai"
+
+	// cbKVConnector is the connector name injected into vLLM pods bound to a
+	// CacheBlendEngine (design §7).
+	cbKVConnector = "CBKVConnector"
+
+	// cbKVConnectorModulePath is the import path of the CacheBlend connector
+	// (cacheblend-plugin/README.md:66).
+	cbKVConnectorModulePath = "lmcache_cacheblend.connector"
+)
+
+// cbSpecToEngineSpec projects a CacheBlendEngineSpec onto an LMCacheEngineSpec so
+// the shared, spec-keyed resource builders (ComputeResources, BuildContainerArgs,
+// and the buildDaemonSetCore/buildLookupServiceCore/buildMetricsServiceCore
+// scaffolding) can be reused without duplicating the GPU/security pod template.
+//
+// CacheBlendEngineSpec deliberately reuses the same shared sub-structs as
+// LMCacheEngineSpec (ServerSpec, L1BackendSpec, EvictionSpec, PrometheusSpec,
+// L2BackendSpec, ImageSpec, etc.), so every field consumed by the shared builders
+// maps across one-to-one. The CacheBlend-only fields (Blend, Injection) are not
+// consumed by the engine builders and are intentionally dropped here; they are
+// surfaced separately (Blend via BuildCBConnectionConfigMap, Injection via the
+// admission webhook).
+func cbSpecToEngineSpec(spec *lmcachev1alpha1.CacheBlendEngineSpec) *lmcachev1alpha1.LMCacheEngineSpec {
+	return &lmcachev1alpha1.LMCacheEngineSpec{
+		GPUVendor:          spec.GPUVendor,
+		Image:              spec.Image,
+		ImagePullSecrets:   spec.ImagePullSecrets,
+		Server:             spec.Server,
+		L1:                 spec.L1,
+		Eviction:           spec.Eviction,
+		Prometheus:         spec.Prometheus,
+		L2Backend:          spec.L2Backend,
+		Coordinator:        spec.Coordinator,
+		ResourceOverrides:  spec.ResourceOverrides,
+		LogLevel:           spec.LogLevel,
+		NodeSelector:       spec.NodeSelector,
+		Affinity:           spec.Affinity,
+		Tolerations:        spec.Tolerations,
+		Env:                spec.Env,
+		Volumes:            spec.Volumes,
+		VolumeMounts:       spec.VolumeMounts,
+		PodAnnotations:     spec.PodAnnotations,
+		PodLabels:          spec.PodLabels,
+		ServiceAccountName: spec.ServiceAccountName,
+		PriorityClassName:  spec.PriorityClassName,
+		Privileged:         spec.Privileged,
+		ExtraArgs:          spec.ExtraArgs,
+	}
+}
+
+// BuildCBEngineArgs returns the server CLI args for the blend_v3 engine: the
+// proven LMCacheEngine serialization (--host/--port/--l1-size-gb/--chunk-size/
+// eviction/prometheus/L2) plus the CacheBlend-specific --engine-type blend and
+// --l1-align-bytes flags. The blend flags are inserted before the user-supplied
+// extraArgs so a user can still override them.
+func BuildCBEngineArgs(spec *lmcachev1alpha1.CacheBlendEngineSpec) []string {
+	// Serialize the base server args WITHOUT the user extraArgs, append the blend
+	// flags, then append extraArgs last so they retain their override precedence.
+	base := cbSpecToEngineSpec(spec)
+	base.ExtraArgs = nil
+	args := BuildContainerArgs(base)
+	args = append(args,
+		"--engine-type", cbEngineType,
+		"--l1-align-bytes", cbL1AlignBytes,
+	)
+	args = append(args, spec.ExtraArgs...)
+	return args
+}
+
+// BuildCBEngineDaemonSet constructs the DaemonSet for the blend_v3 engine of the
+// given CacheBlendEngine. It reuses the shared GPU/security pod-template
+// scaffolding (hostIPC, runtimeClassName=nvidia, NVIDIA_VISIBLE_DEVICES=all,
+// privileged only when spec.privileged=true (default false), CPU+memory-only
+// resources with no nvidia.com/gpu claim) so the engine shares the node's GPU
+// via CUDA IPC, and adds the blend-specific server args.
+func BuildCBEngineDaemonSet(engine *lmcachev1alpha1.CacheBlendEngine) *appsv1.DaemonSet {
+	engineSpec := cbSpecToEngineSpec(&engine.Spec)
+	return buildDaemonSetCore(
+		engine.Name,
+		engine.Namespace,
+		engineSpec,
+		BuildCBEngineArgs(&engine.Spec),
+		cbDefaultImageRepo,
+	)
+}
+
+// BuildCBEngineLookupService creates the node-local lookup Service
+// (internalTrafficPolicy=Local) for the CacheBlendEngine, so opted-in vLLM pods
+// reach the blend_v3 engine on their own node.
+func BuildCBEngineLookupService(engine *lmcachev1alpha1.CacheBlendEngine) *corev1.Service {
+	return buildLookupServiceCore(engine.Name, engine.Namespace, cbSpecToEngineSpec(&engine.Spec))
+}
+
+// BuildCBEngineMetricsService creates the headless metrics Service for the
+// CacheBlendEngine.
+func BuildCBEngineMetricsService(engine *lmcachev1alpha1.CacheBlendEngine) *corev1.Service {
+	return buildMetricsServiceCore(engine.Name, engine.Namespace, cbSpecToEngineSpec(&engine.Spec))
+}
+
+// BuildCBConnectionConfigMap creates the <engine>-connection ConfigMap carrying
+// the CBKVConnector kv-transfer-config JSON (design §7). The JSON points vLLM at
+// the node-local Service (lmcache.mp.host) and carries the blend tunables
+// cb.check_layer and cb.recomp_ratio read from spec.Blend (defaults are pinned by
+// SetDefaults: checkLayer=1, recompRatio=0.15).
+func BuildCBConnectionConfigMap(engine *lmcachev1alpha1.CacheBlendEngine) *corev1.ConfigMap {
+	spec := &engine.Spec
+	// Use the same default (5555) as BuildContainerArgs/getServerPort so the
+	// connection ConfigMap's lmcache.mp.port always matches the engine's actual
+	// --port; the two artifacts must never drift (design §9.10).
+	port := derefInt32(getServerPort(cbSpecToEngineSpec(spec)), 5555)
+
+	checkLayer := int32(1)
+	recompRatio := 0.15
+	if spec.Blend != nil {
+		checkLayer = derefInt32(spec.Blend.CheckLayer, 1)
+		recompRatio = derefFloat64(spec.Blend.RecompRatio, 0.15)
+	}
+
+	extra := map[string]any{
+		"cb.check_layer":  checkLayer,
+		"cb.recomp_ratio": recompRatio,
+	}
+
+	return buildConnectionConfigMapCore(
+		engine.Name,
+		engine.Namespace,
+		cbKVConnector,
+		cbKVConnectorModulePath,
+		port,
+		extra,
+	)
+}
+
+// CBServiceMonitorEnabled reports whether a ServiceMonitor should be created for
+// the given CacheBlendEngine. It reuses the shared spec-keyed predicate since
+// CacheBlendEngineSpec embeds the same PrometheusSpec sub-struct.
+func CBServiceMonitorEnabled(engine *lmcachev1alpha1.CacheBlendEngine) bool {
+	return ServiceMonitorEnabled(cbSpecToEngineSpec(&engine.Spec))
+}
+
+// BuildCBServiceMonitor creates the ServiceMonitor CR for the CacheBlendEngine,
+// reusing the shared name/namespace/spec-keyed core. Callers must ensure
+// CBServiceMonitorEnabled(engine) is true.
+func BuildCBServiceMonitor(engine *lmcachev1alpha1.CacheBlendEngine) *monitoringv1.ServiceMonitor {
+	return buildServiceMonitorCore(engine.Name, engine.Namespace, cbSpecToEngineSpec(&engine.Spec))
+}
diff --git a/operator/internal/resources/cacheblend_engine_test.go b/operator/internal/resources/cacheblend_engine_test.go
new file mode 100644
index 0000000..7795f28
--- /dev/null
+++ b/operator/internal/resources/cacheblend_engine_test.go
@@ -0,0 +1,392 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// minimalCBEngine returns a CacheBlendEngine with only the required L1 size set,
+// then applies SetDefaults so blend/injection/chunk-size defaults are pinned —
+// matching how the controller hands the object to the builders.
+func minimalCBEngine() *lmcachev1alpha1.CacheBlendEngine {
+	e := &lmcachev1alpha1.CacheBlendEngine{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      testEngineName,
+			Namespace: testNamespace,
+		},
+		Spec: lmcachev1alpha1.CacheBlendEngineSpec{
+			L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		},
+	}
+	e.SetDefaults()
+	return e
+}
+
+// ===========================
+// BuildCBEngineArgs
+// ===========================
+
+func TestBuildCBEngineArgs_BlendFlags(t *testing.T) {
+	args := BuildCBEngineArgs(&minimalCBEngine().Spec)
+
+	// Blend-specific flags.
+	assertArg(t, args, "--engine-type", "blend")
+	assertArg(t, args, "--l1-align-bytes", "16777216")
+
+	// Reuses the proven LMCacheEngine serialization (NOT --l1-size).
+	assertArg(t, args, "--l1-size-gb", "10.0")
+	assertNoArg(t, args, "--l1-size")
+
+	// chunk-size pinned to 256 by SetDefaults.
+	assertArg(t, args, "--chunk-size", "256")
+
+	// Standard server args carried over.
+	assertArg(t, args, "--host", "0.0.0.0")
+	assertArg(t, args, "--port", "5555")
+	assertArg(t, args, "--hash-algorithm", "blake3")
+}
+
+func TestBuildCBEngineArgs_ExtraArgsAfterBlendFlags(t *testing.T) {
+	engine := minimalCBEngine()
+	engine.Spec.ExtraArgs = []string{"--engine-type", "override-me"}
+
+	args := BuildCBEngineArgs(&engine.Spec)
+
+	// The user's extraArgs are appended last so they can override the blend
+	// defaults; assert the override value appears after the operator-set one.
+	firstIdx := slices.Index(args, "--engine-type")
+	lastIdx := -1
+	for i, a := range args {
+		if a == "--engine-type" {
+			lastIdx = i
+		}
+	}
+	if firstIdx == lastIdx {
+		t.Fatalf("expected --engine-type to appear twice, got args=%v", args)
+	}
+	if args[firstIdx+1] != "blend" {
+		t.Fatalf("expected operator-set --engine-type blend first, got %s", args[firstIdx+1])
+	}
+	if args[lastIdx+1] != "override-me" {
+		t.Fatalf("expected user --engine-type override-me last, got %s", args[lastIdx+1])
+	}
+}
+
+// ===========================
+// BuildCBEngineDaemonSet
+// ===========================
+
+func TestBuildCBEngineDaemonSet_GPUAndSecurity(t *testing.T) {
+	engine := minimalCBEngine()
+	ds := BuildCBEngineDaemonSet(engine)
+
+	if ds.Name != testEngineName {
+		t.Fatalf("expected name %s, got %s", testEngineName, ds.Name)
+	}
+	if ds.Namespace != testNamespace {
+		t.Fatalf("expected namespace %s, got %s", testNamespace, ds.Namespace)
+	}
+
+	podSpec := ds.Spec.Template.Spec
+
+	// hostIPC required for CUDA IPC with the node-local engine.
+	if !podSpec.HostIPC {
+		t.Fatal("expected HostIPC=true")
+	}
+	// runtimeClassName=nvidia for the default (nvidia) vendor.
+	if podSpec.RuntimeClassName == nil || *podSpec.RuntimeClassName != nvidiaRuntimeClass {
+		t.Fatalf("expected RuntimeClassName=nvidia, got %v", podSpec.RuntimeClassName)
+	}
+
+	if len(podSpec.Containers) != 1 {
+		t.Fatalf("expected 1 container, got %d", len(podSpec.Containers))
+	}
+	c := podSpec.Containers[0]
+
+	// privileged defaults to false (opt-in via spec.privileged).
+	if c.SecurityContext == nil || c.SecurityContext.Privileged == nil || *c.SecurityContext.Privileged {
+		t.Fatal("expected privileged=false by default")
+	}
+
+	// NVIDIA env exposes all GPUs without a device-plugin claim.
+	if !hasEnvAll(c.Env, "NVIDIA_VISIBLE_DEVICES") {
+		t.Fatal("missing NVIDIA_VISIBLE_DEVICES=all")
+	}
+	if !hasEnvAll(c.Env, "NVIDIA_DRIVER_CAPABILITIES") {
+		t.Fatal("missing NVIDIA_DRIVER_CAPABILITIES=all")
+	}
+
+	// Command is the same lmcache server binary as LMCacheEngine.
+	if len(c.Command) < 2 || c.Command[0] != lmcacheServerBinary || c.Command[1] != serverSubcommand {
+		t.Fatalf("expected lmcache server command, got %v", c.Command)
+	}
+
+	// Blend args present on the container.
+	assertArg(t, c.Args, "--engine-type", "blend")
+	assertArg(t, c.Args, "--l1-align-bytes", "16777216")
+}
+
+func TestBuildCBEngineDaemonSet_PrivilegedEnabled(t *testing.T) {
+	engine := minimalCBEngine()
+	engine.Spec.Privileged = ptr(true)
+	ds := BuildCBEngineDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	// spec.privileged=true threads through to the container security context.
+	if c.SecurityContext == nil || c.SecurityContext.Privileged == nil || !*c.SecurityContext.Privileged {
+		t.Fatal("expected privileged=true when spec.privileged=true")
+	}
+}
+
+func TestBuildCBEngineDaemonSet_NoGPUResourceClaim(t *testing.T) {
+	engine := minimalCBEngine()
+	ds := BuildCBEngineDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	// The engine shares vLLM's GPU via CUDA IPC; it must NOT claim a
+	// device-plugin GPU (nvidia.com/gpu) in requests or limits.
+	const gpuResource = corev1.ResourceName("nvidia.com/gpu")
+	if _, ok := c.Resources.Requests[gpuResource]; ok {
+		t.Fatal("nvidia.com/gpu must not be in resource requests")
+	}
+	if _, ok := c.Resources.Limits[gpuResource]; ok {
+		t.Fatal("nvidia.com/gpu must not be in resource limits")
+	}
+
+	// CPU + memory ARE present (auto-computed from L1 size = 10).
+	if c.Resources.Requests.Cpu().IsZero() {
+		t.Fatal("expected a CPU request")
+	}
+	if c.Resources.Requests.Memory().IsZero() {
+		t.Fatal("expected a memory request")
+	}
+}
+
+func TestBuildCBEngineDaemonSet_ImagePullSecrets(t *testing.T) {
+	engine := minimalCBEngine()
+	engine.Spec.ImagePullSecrets = []corev1.LocalObjectReference{{Name: "private-engine-reg"}}
+
+	ds := BuildCBEngineDaemonSet(engine)
+
+	secrets := ds.Spec.Template.Spec.ImagePullSecrets
+	if len(secrets) != 1 || secrets[0].Name != "private-engine-reg" {
+		t.Fatalf("expected engine imagePullSecrets wired onto the pod, got %v", secrets)
+	}
+}
+
+func TestBuildCBEngineDaemonSet_DefaultImage(t *testing.T) {
+	engine := minimalCBEngine()
+	ds := BuildCBEngineDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	if c.Image != "lmcache/vllm-openai:latest" {
+		t.Fatalf("expected default image lmcache/vllm-openai:latest, got %s", c.Image)
+	}
+}
+
+func TestBuildCBEngineDaemonSet_AMDNoRuntimeClass(t *testing.T) {
+	engine := minimalCBEngine()
+	engine.Spec.GPUVendor = ptr(lmcachev1alpha1.GPUVendorAMD)
+
+	ds := BuildCBEngineDaemonSet(engine)
+	podSpec := ds.Spec.Template.Spec
+
+	if podSpec.RuntimeClassName != nil {
+		t.Fatalf("expected nil RuntimeClassName for AMD, got %q", *podSpec.RuntimeClassName)
+	}
+	// hostIPC is still injected for AMD (privileged stays at its default false
+	// here since the fixture does not opt in).
+	if !podSpec.HostIPC {
+		t.Fatal("expected HostIPC=true even for AMD")
+	}
+}
+
+// ===========================
+// BuildCBEngineLookupService / MetricsService
+// ===========================
+
+func TestBuildCBEngineLookupService_Local(t *testing.T) {
+	engine := minimalCBEngine()
+	svc := BuildCBEngineLookupService(engine)
+
+	if svc.Name != testEngineName {
+		t.Fatalf("expected name %s, got %s", testEngineName, svc.Name)
+	}
+	if svc.Spec.ClusterIP == corev1.ClusterIPNone {
+		t.Fatal("lookup service must not be headless")
+	}
+	if svc.Spec.InternalTrafficPolicy == nil ||
+		*svc.Spec.InternalTrafficPolicy != corev1.ServiceInternalTrafficPolicyLocal {
+		t.Fatal("expected internalTrafficPolicy=Local")
+	}
+	if svc.Spec.Ports[0].Port != 5555 {
+		t.Fatalf("expected server port 5555, got %d", svc.Spec.Ports[0].Port)
+	}
+}
+
+func TestBuildCBEngineMetricsService_Headless(t *testing.T) {
+	engine := minimalCBEngine()
+	svc := BuildCBEngineMetricsService(engine)
+
+	if svc.Name != testEngineName+"-metrics" {
+		t.Fatalf("expected name %s-metrics, got %s", testEngineName, svc.Name)
+	}
+	if svc.Spec.ClusterIP != corev1.ClusterIPNone {
+		t.Fatal("expected headless metrics service (ClusterIP=None)")
+	}
+	if svc.Spec.Ports[0].Port != 9090 {
+		t.Fatalf("expected metrics port 9090, got %d", svc.Spec.Ports[0].Port)
+	}
+}
+
+// ===========================
+// BuildCBConnectionConfigMap
+// ===========================
+
+// parseCBConnectionConfig unmarshals the CBKVConnector kv-transfer-config JSON
+// from the connection ConfigMap and returns the top-level config plus the
+// kv_connector_extra_config submap.
+func parseCBConnectionConfig(t *testing.T, cm *corev1.ConfigMap) (map[string]any, map[string]any) {
+	t.Helper()
+	jsonStr, ok := cm.Data["kv-transfer-config.json"]
+	if !ok {
+		t.Fatal("missing kv-transfer-config.json key")
+	}
+	var config map[string]any
+	if err := json.Unmarshal([]byte(jsonStr), &config); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+	extra, ok := config["kv_connector_extra_config"].(map[string]any)
+	if !ok {
+		t.Fatal("missing kv_connector_extra_config map")
+	}
+	return config, extra
+}
+
+func TestBuildCBConnectionConfigMap_Default(t *testing.T) {
+	engine := minimalCBEngine()
+	cm := BuildCBConnectionConfigMap(engine)
+
+	if cm.Name != "test-engine-connection" {
+		t.Fatalf("expected name test-engine-connection, got %s", cm.Name)
+	}
+	if cm.Namespace != testNamespace {
+		t.Fatalf("expected namespace %s, got %s", testNamespace, cm.Namespace)
+	}
+
+	config, extra := parseCBConnectionConfig(t, cm)
+
+	if config["kv_connector"] != "CBKVConnector" {
+		t.Fatalf("expected kv_connector=CBKVConnector, got %v", config["kv_connector"])
+	}
+	if config["kv_connector_module_path"] != "lmcache_cacheblend.connector" {
+		t.Fatalf("expected kv_connector_module_path=lmcache_cacheblend.connector, got %v",
+			config["kv_connector_module_path"])
+	}
+	if config["kv_role"] != "kv_both" {
+		t.Fatalf("expected kv_role=kv_both, got %v", config["kv_role"])
+	}
+
+	if extra["lmcache.mp.host"] != "tcp://test-engine.default.svc.cluster.local" {
+		t.Fatalf("expected tcp:// node-local Service host, got %v", extra["lmcache.mp.host"])
+	}
+	if extra["lmcache.mp.port"] != "5555" {
+		t.Fatalf("expected lmcache.mp.port=5555, got %v", extra["lmcache.mp.port"])
+	}
+
+	// Blend tunables from SetDefaults (checkLayer=1, recompRatio=0.15). JSON
+	// numbers decode to float64.
+	if extra["cb.check_layer"] != float64(1) {
+		t.Fatalf("expected cb.check_layer=1, got %v", extra["cb.check_layer"])
+	}
+	if extra["cb.recomp_ratio"] != 0.15 {
+		t.Fatalf("expected cb.recomp_ratio=0.15, got %v", extra["cb.recomp_ratio"])
+	}
+}
+
+func TestBuildCBConnectionConfigMap_CustomBlendAndPort(t *testing.T) {
+	engine := minimalCBEngine()
+	engine.Spec.Server.Port = ptr(int32(6566))
+	engine.Spec.Blend = &lmcachev1alpha1.BlendSpec{
+		CheckLayer:  ptr(int32(3)),
+		RecompRatio: ptr(0.5),
+	}
+
+	cm := BuildCBConnectionConfigMap(engine)
+	_, extra := parseCBConnectionConfig(t, cm)
+
+	if extra["lmcache.mp.port"] != "6566" {
+		t.Fatalf("expected lmcache.mp.port=6566, got %v", extra["lmcache.mp.port"])
+	}
+	if extra["cb.check_layer"] != float64(3) {
+		t.Fatalf("expected cb.check_layer=3, got %v", extra["cb.check_layer"])
+	}
+	if extra["cb.recomp_ratio"] != 0.5 {
+		t.Fatalf("expected cb.recomp_ratio=0.5, got %v", extra["cb.recomp_ratio"])
+	}
+}
+
+// TestBuildCBConnectionConfigMap_PortMatchesEngineArgs asserts the connection
+// ConfigMap's lmcache.mp.port and the engine DaemonSet's --port never drift, for
+// both the default and a user-set port.
+func TestBuildCBConnectionConfigMap_PortMatchesEngineArgs(t *testing.T) {
+	tests := []struct {
+		name     string
+		port     *int32
+		wantPort string
+	}{
+		{name: "default", port: nil, wantPort: "5555"},
+		{name: "custom", port: ptr(int32(6566)), wantPort: "6566"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			engine := minimalCBEngine()
+			engine.Spec.Server.Port = tt.port
+
+			args := BuildCBEngineArgs(&engine.Spec)
+			cm := BuildCBConnectionConfigMap(engine)
+			_, extra := parseCBConnectionConfig(t, cm)
+
+			assertArg(t, args, "--port", tt.wantPort)
+			if extra["lmcache.mp.port"] != tt.wantPort {
+				t.Fatalf("connection port %v != engine --port %s", extra["lmcache.mp.port"], tt.wantPort)
+			}
+		})
+	}
+}
+
+// TestBuildCBEngine_ChunkSizeConsistency asserts the engine's chunk-size is 256
+// (the only value CacheBlend supports — block_size 64 * 4), matching the locked
+// CacheBlendChunkSize constant, so it cannot drift from the injected --block-size.
+func TestBuildCBEngine_ChunkSizeConsistency(t *testing.T) {
+	engine := minimalCBEngine()
+	args := BuildCBEngineArgs(&engine.Spec)
+
+	assertArg(t, args, "--chunk-size", "256")
+	if lmcachev1alpha1.CacheBlendChunkSize != 256 {
+		t.Fatalf("CacheBlendChunkSize constant must be 256, got %d", lmcachev1alpha1.CacheBlendChunkSize)
+	}
+}
diff --git a/operator/internal/resources/compute.go b/operator/internal/resources/compute.go
new file mode 100644
index 0000000..7d073bb
--- /dev/null
+++ b/operator/internal/resources/compute.go
@@ -0,0 +1,222 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"encoding/json"
+	"fmt"
+	"math"
+
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/resource"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// ComputeResources returns resource requirements, either from overrides or auto-computed from L1 size.
+func ComputeResources(spec *lmcachev1alpha1.LMCacheEngineSpec) corev1.ResourceRequirements {
+	if spec.ResourceOverrides != nil {
+		return *spec.ResourceOverrides
+	}
+
+	// memoryRequest = ceil(l1.sizeGB + 5) Gi
+	memReqGi := int64(math.Ceil(spec.L1.SizeGB + 5))
+	// memoryLimit = ceil(memoryRequest * 1.5) Gi
+	memLimGi := int64(math.Ceil(float64(memReqGi) * 1.5))
+
+	return corev1.ResourceRequirements{
+		Requests: corev1.ResourceList{
+			corev1.ResourceCPU:    resource.MustParse("4"),
+			corev1.ResourceMemory: resource.MustParse(fmt.Sprintf("%dGi", memReqGi)),
+		},
+		Limits: corev1.ResourceList{
+			corev1.ResourceMemory: resource.MustParse(fmt.Sprintf("%dGi", memLimGi)),
+		},
+	}
+}
+
+// BuildContainerArgs maps CRD spec fields to server.py CLI flags.
+func BuildContainerArgs(spec *lmcachev1alpha1.LMCacheEngineSpec) []string {
+	args := []string{
+		"--host", "0.0.0.0",
+		"--port", fmt.Sprintf("%d", derefInt32(getServerPort(spec), 5555)),
+		"--http-port", fmt.Sprintf("%d", getHTTPPort(spec)),
+		"--l1-size-gb", fmt.Sprintf("%.1f", spec.L1.SizeGB),
+		"--chunk-size", fmt.Sprintf("%d", getChunkSize(spec)),
+		"--max-workers", fmt.Sprintf("%d", getMaxWorkers(spec)),
+		"--hash-algorithm", getHashAlgorithm(spec),
+	}
+
+	// Eviction args
+	evPolicy := "LRU"
+	evTrigger := 0.8
+	evRatio := 0.2
+	if spec.Eviction != nil {
+		evPolicy = derefString(spec.Eviction.Policy, "LRU")
+		evTrigger = derefFloat64(spec.Eviction.TriggerWatermark, 0.8)
+		evRatio = derefFloat64(spec.Eviction.EvictionRatio, 0.2)
+	}
+	args = append(args,
+		"--eviction-policy", evPolicy,
+		"--eviction-trigger-watermark", fmt.Sprintf("%.2f", evTrigger),
+		"--eviction-ratio", fmt.Sprintf("%.2f", evRatio),
+	)
+
+	// Prometheus args
+	promEnabled := true
+	if spec.Prometheus != nil {
+		promEnabled = derefBool(spec.Prometheus.Enabled, true)
+	}
+	if !promEnabled {
+		args = append(args, "--disable-prometheus")
+	} else {
+		promPort := int32(9090)
+		if spec.Prometheus != nil {
+			promPort = derefInt32(spec.Prometheus.Port, 9090)
+		}
+		args = append(args, "--prometheus-port", fmt.Sprintf("%d", promPort))
+	}
+
+	// L2 backend
+	if spec.L2Backend != nil {
+		l2JSON := buildL2AdapterJSON(spec.L2Backend)
+		if l2JSON != "" {
+			args = append(args, "--l2-adapter", l2JSON)
+		}
+
+		// L2 policies
+		args = append(args,
+			"--l2-store-policy", derefString(spec.L2Backend.StorePolicy, "default"),
+			"--l2-prefetch-policy", derefString(spec.L2Backend.PrefetchPolicy, "default"),
+			"--l2-prefetch-max-in-flight", fmt.Sprintf("%d", derefInt32(spec.L2Backend.PrefetchMaxInFlight, 8)),
+		)
+	}
+
+	// Coordinator registration. The URL is resolved by the controller (from a
+	// coordinator ref or an explicit url) before this builder runs; an empty URL
+	// means registration is disabled. The advertise IP falls back to the pod IP
+	// via the LMCACHE_COORDINATOR_ADVERTISE_IP env var injected by the DaemonSet
+	// builder, so it is only emitted as a flag when explicitly set.
+	if c := spec.Coordinator; c != nil {
+		if url := derefString(c.URL, ""); url != "" {
+			args = append(args, "--coordinator-url", url)
+			if c.AdvertiseIP != nil && *c.AdvertiseIP != "" {
+				args = append(args, "--coordinator-advertise-ip", *c.AdvertiseIP)
+			}
+			args = append(args,
+				"--coordinator-heartbeat-interval", formatFloat(derefFloat64(c.HeartbeatInterval, 5.0)),
+			)
+			if derefBool(c.L2EventReporting, false) {
+				args = append(args, "--coordinator-l2-event-reporting")
+			}
+			args = append(args,
+				"--coordinator-l2-event-flush-interval", formatFloat(derefFloat64(c.L2EventFlushInterval, 1.0)),
+			)
+		}
+	}
+
+	// User-supplied extra args (appended last so they can override defaults)
+	args = append(args, spec.ExtraArgs...)
+
+	return args
+}
+
+// buildL2AdapterJSON serializes an L2BackendSpec into the --l2-adapter JSON string.
+// For RESP adapters with authSecretRef, username/password are set to env var
+// placeholders that get interpolated by the shell wrapper (see BuildShellCommand).
+func buildL2AdapterJSON(backend *lmcachev1alpha1.L2BackendSpec) string {
+	if backend.RESP != nil {
+		return buildRESPL2JSON(backend.RESP)
+	}
+	if backend.Raw != nil {
+		return buildRawL2JSON(backend.Raw)
+	}
+	return ""
+}
+
+func buildRESPL2JSON(resp *lmcachev1alpha1.RESPL2AdapterSpec) string {
+	flat := map[string]any{
+		"type":        "resp",
+		"host":        resp.Host,
+		"port":        resp.Port,
+		"num_workers": derefInt32(resp.NumWorkers, 8),
+	}
+	if resp.MaxCapacityGB != nil && *resp.MaxCapacityGB > 0 {
+		flat["max_capacity_gb"] = *resp.MaxCapacityGB
+	}
+	// Auth credentials are passed via LMCACHE_RESP_USERNAME /
+	// LMCACHE_RESP_PASSWORD env vars (injected by the DaemonSet builder),
+	// not in the JSON config.
+	b, err := json.Marshal(flat)
+	if err != nil {
+		return ""
+	}
+	return string(b)
+}
+
+func buildRawL2JSON(raw *lmcachev1alpha1.RawL2AdapterSpec) string {
+	flat := make(map[string]any)
+	flat["type"] = raw.Type
+	for k, v := range raw.Config {
+		var parsed any
+		if err := json.Unmarshal(v.Raw, &parsed); err != nil {
+			flat[k] = string(v.Raw)
+		} else {
+			flat[k] = parsed
+		}
+	}
+	b, err := json.Marshal(flat)
+	if err != nil {
+		return ""
+	}
+	return string(b)
+}
+
+func getServerPort(spec *lmcachev1alpha1.LMCacheEngineSpec) *int32 {
+	if spec.Server != nil {
+		return spec.Server.Port
+	}
+	return nil
+}
+
+func getHTTPPort(spec *lmcachev1alpha1.LMCacheEngineSpec) int32 {
+	if spec.Server != nil {
+		return derefInt32(spec.Server.HTTPPort, 8080)
+	}
+	return 8080
+}
+
+func getChunkSize(spec *lmcachev1alpha1.LMCacheEngineSpec) int32 {
+	if spec.Server != nil {
+		return derefInt32(spec.Server.ChunkSize, 256)
+	}
+	return 256
+}
+
+func getMaxWorkers(spec *lmcachev1alpha1.LMCacheEngineSpec) int32 {
+	if spec.Server != nil {
+		return derefInt32(spec.Server.MaxWorkers, 1)
+	}
+	return 1
+}
+
+func getHashAlgorithm(spec *lmcachev1alpha1.LMCacheEngineSpec) string {
+	if spec.Server != nil {
+		return derefString(spec.Server.HashAlgorithm, "blake3")
+	}
+	return "blake3"
+}
diff --git a/operator/internal/resources/configmap.go b/operator/internal/resources/configmap.go
new file mode 100644
index 0000000..db4a2a6
--- /dev/null
+++ b/operator/internal/resources/configmap.go
@@ -0,0 +1,102 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"encoding/json"
+	"fmt"
+	"maps"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// LookupServiceName returns the name of the node-local lookup Service for discovery.
+func LookupServiceName(engineName string) string {
+	return engineName
+}
+
+// ConnectionConfigMapName returns the name of the <engine>-connection ConfigMap.
+func ConnectionConfigMapName(engineName string) string {
+	return fmt.Sprintf("%s-connection", engineName)
+}
+
+// BuildConnectionConfigMap creates the <name>-connection ConfigMap with kv-transfer-config JSON.
+func BuildConnectionConfigMap(engine *lmcachev1alpha1.LMCacheEngine) *corev1.ConfigMap {
+	port := derefInt32(getServerPort(&engine.Spec), 5555)
+
+	return buildConnectionConfigMapCore(
+		engine.Name,
+		engine.Namespace,
+		"LMCacheMPConnector",
+		"lmcache.integration.vllm.lmcache_mp_connector",
+		port,
+		nil,
+	)
+}
+
+// buildConnectionConfigMapCore is the shared core for the <engine>-connection
+// ConfigMap that both engine controllers emit. It produces the kv-transfer-config
+// JSON with the node-local Service host/port and lets the caller select the
+// connector name, its module path, and any connector-specific extra config keys
+// (e.g. CacheBlend's cb.check_layer / cb.recomp_ratio).
+//
+// Parameters:
+//   - name, namespace: the owning engine's identity (drives the ConfigMap name,
+//     labels, and the node-local Service DNS host).
+//   - connectorName: the kv_connector value (e.g. "LMCacheMPConnector" or
+//     "CBKVConnector").
+//   - modulePath: the kv_connector_module_path value.
+//   - port: the engine server port, emitted as lmcache.mp.port (string).
+//   - extraConfig: additional kv_connector_extra_config keys merged on top of the
+//     base lmcache.mp.host / lmcache.mp.port entries; nil for the default
+//     connector.
+func buildConnectionConfigMapCore(
+	name, namespace, connectorName, modulePath string,
+	port int32,
+	extraConfig map[string]any,
+) *corev1.ConfigMap {
+	svcHost := fmt.Sprintf("%s.%s.svc.cluster.local", LookupServiceName(name), namespace)
+
+	extra := map[string]any{
+		"lmcache.mp.host": fmt.Sprintf("tcp://%s", svcHost),
+		"lmcache.mp.port": fmt.Sprintf("%d", port),
+	}
+	maps.Copy(extra, extraConfig)
+
+	config := map[string]any{
+		"kv_connector":              connectorName,
+		"kv_connector_module_path":  modulePath,
+		"kv_role":                   "kv_both",
+		"kv_connector_extra_config": extra,
+	}
+
+	configJSON, _ := json.MarshalIndent(config, "", "  ")
+
+	return &corev1.ConfigMap{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      ConnectionConfigMapName(name),
+			Namespace: namespace,
+			Labels:    StandardLabels(name),
+		},
+		Data: map[string]string{
+			"kv-transfer-config.json": string(configJSON),
+		},
+	}
+}
diff --git a/operator/internal/resources/coordinator_deployment.go b/operator/internal/resources/coordinator_deployment.go
new file mode 100644
index 0000000..2db4b7e
--- /dev/null
+++ b/operator/internal/resources/coordinator_deployment.go
@@ -0,0 +1,238 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"fmt"
+	"strconv"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/util/intstr"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+const (
+	// coordinatorSubcommand is the `lmcache coordinator` subcommand that starts
+	// the fleet coordinator HTTP server.
+	coordinatorSubcommand = "coordinator"
+
+	// coordinatorDefaultImageRepo is the default coordinator image repository.
+	// The coordinator runs the same lmcache binary as the engines.
+	coordinatorDefaultImageRepo = "lmcache/vllm-openai"
+
+	// coordinatorPortName is the name of the coordinator's HTTP port on the
+	// container and Service.
+	coordinatorPortName = "http"
+
+	// coordinatorDefaultPort is the default HTTP port (mirrors
+	// MPCoordinatorConfig.port).
+	coordinatorDefaultPort int32 = 9300
+
+	// coordinatorHealthPath is the liveness/readiness probe path served by the
+	// coordinator (lmcache/v1/mp_coordinator/http_apis/health_api.py).
+	coordinatorHealthPath = "/healthz"
+
+	// coordinatorComponentLabel is the app.kubernetes.io/component value for
+	// coordinator-owned resources, distinguishing them from cache-engine pods.
+	coordinatorComponentLabel = "coordinator"
+)
+
+// CoordinatorSelectorLabels returns the immutable label subset used for the
+// coordinator's pod/Service selectors. It carries a distinct
+// app.kubernetes.io/name so a coordinator never cross-selects engine pods that
+// happen to share its name.
+func CoordinatorSelectorLabels(name string) map[string]string {
+	return map[string]string{
+		"app.kubernetes.io/name":       "lmcache-coordinator",
+		"app.kubernetes.io/instance":   name,
+		"app.kubernetes.io/managed-by": "lmcache-operator",
+	}
+}
+
+// CoordinatorStandardLabels returns the full label set for coordinator-owned
+// resources.
+func CoordinatorStandardLabels(name string) map[string]string {
+	labels := CoordinatorSelectorLabels(name)
+	labels["app.kubernetes.io/component"] = coordinatorComponentLabel
+	return labels
+}
+
+// CoordinatorPort returns the coordinator's HTTP port, applying the default.
+func CoordinatorPort(spec *lmcachev1alpha1.LMCacheCoordinatorSpec) int32 {
+	return derefInt32(spec.Port, coordinatorDefaultPort)
+}
+
+// BuildCoordinatorArgs maps the LMCacheCoordinatorSpec config fields to the
+// `lmcache coordinator` CLI flags. User-supplied extraArgs are appended last so
+// they retain override precedence.
+//
+// The global-CacheBlend knobs (blend_chunk_size / blend_probe_stride) are
+// rendered via their `--blend-chunk-size` / `--blend-probe-stride` flags only
+// when the spec sets them explicitly. When unset, the operator omits the flags
+// and the coordinator image falls back to its own MPCoordinatorConfig defaults
+// (256 / 1) -- this keeps the operator compatible with images whose CLI
+// predates these flags. blendChunkSize MUST equal the chunk size the blend
+// servers use.
+func BuildCoordinatorArgs(spec *lmcachev1alpha1.LMCacheCoordinatorSpec) []string {
+	// 7 always-on two-token flags, up to 2 optional blend flags, plus extras.
+	args := make([]string, 0, 18+len(spec.ExtraArgs))
+	args = append(args,
+		"--host", derefString(spec.Host, "0.0.0.0"),
+		"--port", fmt.Sprintf("%d", CoordinatorPort(spec)),
+		"--instance-timeout", formatFloat(derefFloat64(spec.InstanceTimeout, 30.0)),
+		"--health-check-interval", formatFloat(derefFloat64(spec.HealthCheckInterval, 10.0)),
+		"--eviction-check-interval", formatFloat(derefFloat64(spec.EvictionCheckInterval, 5.0)),
+		"--eviction-ratio", formatFloat(derefFloat64(spec.EvictionRatio, 0.2)),
+		"--trigger-watermark", formatFloat(derefFloat64(spec.TriggerWatermark, 1.0)),
+	)
+	if spec.BlendChunkSize != nil {
+		args = append(args, "--blend-chunk-size", fmt.Sprintf("%d", *spec.BlendChunkSize))
+	}
+	if spec.BlendProbeStride != nil {
+		args = append(args, "--blend-probe-stride", fmt.Sprintf("%d", *spec.BlendProbeStride))
+	}
+	args = append(args, spec.ExtraArgs...)
+	return args
+}
+
+// formatFloat renders a float flag value with the minimal decimal
+// representation (e.g. 30.0 -> "30", 0.2 -> "0.2").
+func formatFloat(v float64) string {
+	return strconv.FormatFloat(v, 'f', -1, 64)
+}
+
+// BuildCoordinatorDeployment constructs the Deployment for the given
+// LMCacheCoordinator. Unlike the engine DaemonSets, the coordinator is a plain
+// fleet-wide service: no GPU runtime class, hostIPC, or privileged container.
+func BuildCoordinatorDeployment(coordinator *lmcachev1alpha1.LMCacheCoordinator) *appsv1.Deployment {
+	spec := &coordinator.Spec
+	name := coordinator.Name
+	namespace := coordinator.Namespace
+
+	selectorLabels := CoordinatorSelectorLabels(name)
+	podLabels := MergeLabels(CoordinatorStandardLabels(name), spec.PodLabels)
+
+	port := CoordinatorPort(spec)
+
+	imgRepo := coordinatorDefaultImageRepo
+	imgTag := "latest"
+	imgPullPolicy := corev1.PullIfNotPresent
+	if spec.Image != nil {
+		imgRepo = derefString(spec.Image.Repository, imgRepo)
+		imgTag = derefString(spec.Image.Tag, imgTag)
+		switch derefString(spec.Image.PullPolicy, "IfNotPresent") {
+		case "Always":
+			imgPullPolicy = corev1.PullAlways
+		case "Never":
+			imgPullPolicy = corev1.PullNever
+		default:
+			imgPullPolicy = corev1.PullIfNotPresent
+		}
+	}
+
+	envVars := make([]corev1.EnvVar, 0, 1+len(spec.Env))
+	envVars = append(envVars, corev1.EnvVar{
+		Name:  "LMCACHE_LOG_LEVEL",
+		Value: derefString(spec.LogLevel, "INFO"),
+	})
+	envVars = append(envVars, spec.Env...)
+
+	containerPorts := []corev1.ContainerPort{
+		{
+			Name:          coordinatorPortName,
+			ContainerPort: port,
+			Protocol:      corev1.ProtocolTCP,
+		},
+	}
+	if coordinatorPrometheusEnabled(spec) {
+		containerPorts = append(containerPorts, corev1.ContainerPort{
+			Name:          "metrics",
+			ContainerPort: coordinatorMetricsPort(spec),
+			Protocol:      corev1.ProtocolTCP,
+		})
+	}
+
+	httpProbe := func(period, failure int32) *corev1.Probe {
+		return &corev1.Probe{
+			ProbeHandler: corev1.ProbeHandler{
+				HTTPGet: &corev1.HTTPGetAction{
+					Path: coordinatorHealthPath,
+					Port: intstr.FromInt32(port),
+				},
+			},
+			PeriodSeconds:    period,
+			FailureThreshold: failure,
+		}
+	}
+	startupProbe := httpProbe(5, 30)
+	startupProbe.InitialDelaySeconds = 5
+	livenessProbe := httpProbe(10, 3)
+	readinessProbe := httpProbe(5, 3)
+
+	var resourceReqs corev1.ResourceRequirements
+	if spec.ResourceOverrides != nil {
+		resourceReqs = *spec.ResourceOverrides
+	}
+
+	return &appsv1.Deployment{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      name,
+			Namespace: namespace,
+			Labels:    CoordinatorStandardLabels(name),
+		},
+		Spec: appsv1.DeploymentSpec{
+			Replicas: spec.Replicas,
+			Selector: &metav1.LabelSelector{
+				MatchLabels: selectorLabels,
+			},
+			Template: corev1.PodTemplateSpec{
+				ObjectMeta: metav1.ObjectMeta{
+					Labels:      podLabels,
+					Annotations: spec.PodAnnotations,
+				},
+				Spec: corev1.PodSpec{
+					ServiceAccountName: spec.ServiceAccountName,
+					PriorityClassName:  spec.PriorityClassName,
+					NodeSelector:       spec.NodeSelector,
+					Affinity:           spec.Affinity,
+					Tolerations:        spec.Tolerations,
+					ImagePullSecrets:   spec.ImagePullSecrets,
+					Containers: []corev1.Container{
+						{
+							Name:            coordinatorSubcommand,
+							Image:           fmt.Sprintf("%s:%s", imgRepo, imgTag),
+							ImagePullPolicy: imgPullPolicy,
+							Command:         []string{lmcacheServerBinary, coordinatorSubcommand},
+							Args:            BuildCoordinatorArgs(spec),
+							Ports:           containerPorts,
+							Env:             envVars,
+							Resources:       resourceReqs,
+							StartupProbe:    startupProbe,
+							LivenessProbe:   livenessProbe,
+							ReadinessProbe:  readinessProbe,
+							VolumeMounts:    spec.VolumeMounts,
+						},
+					},
+					Volumes: spec.Volumes,
+				},
+			},
+		},
+	}
+}
diff --git a/operator/internal/resources/coordinator_resolve.go b/operator/internal/resources/coordinator_resolve.go
new file mode 100644
index 0000000..66f2b4e
--- /dev/null
+++ b/operator/internal/resources/coordinator_resolve.go
@@ -0,0 +1,63 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"context"
+	"fmt"
+
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// ResolveCoordinatorConnection returns a copy of conn with URL populated. When
+// conn references an LMCacheCoordinator (Ref), it is looked up in the given
+// namespace and its in-cluster Service endpoint is used. An explicit URL is
+// returned unchanged. A nil conn returns nil. The resolved copy is passed to the
+// resource builders so BuildContainerArgs can emit --coordinator-url without a
+// cluster read.
+func ResolveCoordinatorConnection(
+	ctx context.Context,
+	c client.Client,
+	namespace string,
+	conn *lmcachev1alpha1.CoordinatorConnectionSpec,
+) (*lmcachev1alpha1.CoordinatorConnectionSpec, error) {
+	if conn == nil {
+		return nil, nil
+	}
+
+	resolved := *conn
+	if conn.URL != nil && *conn.URL != "" {
+		return &resolved, nil
+	}
+	if conn.Ref == nil || conn.Ref.Name == "" {
+		// Validation already rejects this; return unchanged so the builder emits
+		// no coordinator flags rather than a malformed URL.
+		return &resolved, nil
+	}
+
+	coordinator := &lmcachev1alpha1.LMCacheCoordinator{}
+	if err := c.Get(ctx, types.NamespacedName{Name: conn.Ref.Name, Namespace: namespace}, coordinator); err != nil {
+		return nil, fmt.Errorf("failed to resolve coordinator ref %q: %w", conn.Ref.Name, err)
+	}
+
+	url := CoordinatorEndpoint(coordinator)
+	resolved.URL = &url
+	return &resolved, nil
+}
diff --git a/operator/internal/resources/coordinator_service.go b/operator/internal/resources/coordinator_service.go
new file mode 100644
index 0000000..0f8ffd4
--- /dev/null
+++ b/operator/internal/resources/coordinator_service.go
@@ -0,0 +1,157 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"fmt"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// coordinatorDefaultMetricsPort is the metrics port used when prometheus is
+// enabled but no port is configured (mirrors the engine default).
+const coordinatorDefaultMetricsPort int32 = 9090
+
+// CoordinatorServiceName returns the name of the ClusterIP Service that fronts
+// the coordinator. It equals the CR name so the in-cluster endpoint is the
+// deterministic http://<name>.<namespace>.svc:<port>, which engines resolve from
+// a coordinator reference.
+func CoordinatorServiceName(name string) string {
+	return name
+}
+
+// CoordinatorEndpoint returns the in-cluster base URL other components use to
+// reach the coordinator.
+func CoordinatorEndpoint(coordinator *lmcachev1alpha1.LMCacheCoordinator) string {
+	return fmt.Sprintf(
+		"http://%s.%s.svc:%d",
+		CoordinatorServiceName(coordinator.Name),
+		coordinator.Namespace,
+		CoordinatorPort(&coordinator.Spec),
+	)
+}
+
+// coordinatorPrometheusEnabled reports whether prometheus metrics are enabled
+// for the coordinator. Unlike the engines, the coordinator defaults to disabled
+// because it does not yet serve a /metrics endpoint.
+func coordinatorPrometheusEnabled(spec *lmcachev1alpha1.LMCacheCoordinatorSpec) bool {
+	if spec.Prometheus == nil {
+		return false
+	}
+	return derefBool(spec.Prometheus.Enabled, false)
+}
+
+// coordinatorMetricsPort returns the configured metrics port (default 9090).
+func coordinatorMetricsPort(spec *lmcachev1alpha1.LMCacheCoordinatorSpec) int32 {
+	if spec.Prometheus == nil {
+		return coordinatorDefaultMetricsPort
+	}
+	return derefInt32(spec.Prometheus.Port, coordinatorDefaultMetricsPort)
+}
+
+// CoordinatorServiceMonitorEnabled reports whether a ServiceMonitor should be
+// created for the coordinator.
+func CoordinatorServiceMonitorEnabled(coordinator *lmcachev1alpha1.LMCacheCoordinator) bool {
+	spec := &coordinator.Spec
+	if spec.Prometheus == nil || spec.Prometheus.ServiceMonitor == nil {
+		return false
+	}
+	return derefBool(spec.Prometheus.ServiceMonitor.Enabled, false)
+}
+
+// BuildCoordinatorService creates the ClusterIP Service that exposes the
+// coordinator's HTTP port for fleet-wide discovery.
+func BuildCoordinatorService(coordinator *lmcachev1alpha1.LMCacheCoordinator) *corev1.Service {
+	name := coordinator.Name
+	port := CoordinatorPort(&coordinator.Spec)
+
+	return &corev1.Service{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      CoordinatorServiceName(name),
+			Namespace: coordinator.Namespace,
+			Labels:    CoordinatorStandardLabels(name),
+		},
+		Spec: corev1.ServiceSpec{
+			Selector: CoordinatorSelectorLabels(name),
+			Ports: []corev1.ServicePort{
+				{
+					Name:     coordinatorPortName,
+					Port:     port,
+					Protocol: corev1.ProtocolTCP,
+				},
+			},
+		},
+	}
+}
+
+// BuildCoordinatorMetricsService creates a headless Service for Prometheus
+// scraping of the coordinator. Callers must ensure prometheus is enabled.
+func BuildCoordinatorMetricsService(coordinator *lmcachev1alpha1.LMCacheCoordinator) *corev1.Service {
+	name := coordinator.Name
+
+	return &corev1.Service{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      fmt.Sprintf("%s-metrics", name),
+			Namespace: coordinator.Namespace,
+			Labels:    CoordinatorStandardLabels(name),
+		},
+		Spec: corev1.ServiceSpec{
+			ClusterIP: corev1.ClusterIPNone,
+			Selector:  CoordinatorSelectorLabels(name),
+			Ports: []corev1.ServicePort{
+				{
+					Name:     "metrics",
+					Port:     coordinatorMetricsPort(&coordinator.Spec),
+					Protocol: corev1.ProtocolTCP,
+				},
+			},
+		},
+	}
+}
+
+// BuildCoordinatorServiceMonitor creates the ServiceMonitor CR for the
+// coordinator. Callers must ensure CoordinatorServiceMonitorEnabled is true.
+func BuildCoordinatorServiceMonitor(coordinator *lmcachev1alpha1.LMCacheCoordinator) *monitoringv1.ServiceMonitor {
+	name := coordinator.Name
+	smSpec := coordinator.Spec.Prometheus.ServiceMonitor
+
+	interval := monitoringv1.Duration(derefString(smSpec.Interval, "30s"))
+	labels := MergeLabels(CoordinatorStandardLabels(name), smSpec.Labels)
+
+	return &monitoringv1.ServiceMonitor{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      name,
+			Namespace: coordinator.Namespace,
+			Labels:    labels,
+		},
+		Spec: monitoringv1.ServiceMonitorSpec{
+			Selector: metav1.LabelSelector{
+				MatchLabels: CoordinatorSelectorLabels(name),
+			},
+			Endpoints: []monitoringv1.Endpoint{
+				{
+					Port:     "metrics",
+					Interval: interval,
+				},
+			},
+		},
+	}
+}
diff --git a/operator/internal/resources/coordinator_test.go b/operator/internal/resources/coordinator_test.go
new file mode 100644
index 0000000..10a4868
--- /dev/null
+++ b/operator/internal/resources/coordinator_test.go
@@ -0,0 +1,175 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"slices"
+	"testing"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+func minimalCoordinator() *lmcachev1alpha1.LMCacheCoordinator {
+	return &lmcachev1alpha1.LMCacheCoordinator{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      "test-coordinator",
+			Namespace: testNamespace,
+		},
+		Spec: lmcachev1alpha1.LMCacheCoordinatorSpec{},
+	}
+}
+
+func TestBuildCoordinatorArgs_Defaults(t *testing.T) {
+	args := BuildCoordinatorArgs(&minimalCoordinator().Spec)
+
+	if got := findArgValue(t, args, "--host"); got != "0.0.0.0" {
+		t.Errorf("--host = %q, want 0.0.0.0", got)
+	}
+	if got := findArgValue(t, args, "--port"); got != "9300" {
+		t.Errorf("--port = %q, want 9300", got)
+	}
+	if got := findArgValue(t, args, "--instance-timeout"); got != "30" {
+		t.Errorf("--instance-timeout = %q, want 30", got)
+	}
+	if got := findArgValue(t, args, "--eviction-ratio"); got != "0.2" {
+		t.Errorf("--eviction-ratio = %q, want 0.2", got)
+	}
+	// Unset blend knobs are omitted so the coordinator image applies its own
+	// defaults; emitting them would break images whose CLI predates the flags.
+	if slices.Contains(args, "--blend-chunk-size") {
+		t.Errorf("--blend-chunk-size should be omitted when unset, got args %v", args)
+	}
+	if slices.Contains(args, "--blend-probe-stride") {
+		t.Errorf("--blend-probe-stride should be omitted when unset, got args %v", args)
+	}
+}
+
+func TestBuildCoordinatorArgs_Overrides(t *testing.T) {
+	c := minimalCoordinator()
+	c.Spec.Port = ptr(int32(9400))
+	c.Spec.EvictionRatio = ptr(0.5)
+	c.Spec.BlendChunkSize = ptr(int32(512))
+	c.Spec.BlendProbeStride = ptr(int32(4))
+	c.Spec.ExtraArgs = []string{"--port", "1234"}
+
+	args := BuildCoordinatorArgs(&c.Spec)
+
+	if got := findArgValue(t, args, "--eviction-ratio"); got != "0.5" {
+		t.Errorf("--eviction-ratio = %q, want 0.5", got)
+	}
+	if got := findArgValue(t, args, "--blend-chunk-size"); got != "512" {
+		t.Errorf("--blend-chunk-size = %q, want 512", got)
+	}
+	if got := findArgValue(t, args, "--blend-probe-stride"); got != "4" {
+		t.Errorf("--blend-probe-stride = %q, want 4", got)
+	}
+	// ExtraArgs are appended last so they win when re-specifying a flag.
+	if args[len(args)-2] != "--port" || args[len(args)-1] != "1234" {
+		t.Errorf("expected extraArgs appended last, got tail %v", args[len(args)-2:])
+	}
+}
+
+func TestBuildCoordinatorDeployment_Basics(t *testing.T) {
+	c := minimalCoordinator()
+	c.Spec.Replicas = ptr(int32(2))
+	deploy := BuildCoordinatorDeployment(c)
+
+	if deploy.Spec.Replicas == nil || *deploy.Spec.Replicas != 2 {
+		t.Errorf("expected replicas 2 to pass through to the Deployment")
+	}
+
+	podSpec := deploy.Spec.Template.Spec
+	if len(podSpec.Containers) != 1 {
+		t.Fatalf("expected 1 container, got %d", len(podSpec.Containers))
+	}
+	container := podSpec.Containers[0]
+	if !slices.Contains(container.Command, "coordinator") {
+		t.Errorf("expected coordinator subcommand in command %v", container.Command)
+	}
+	if container.ReadinessProbe == nil || container.ReadinessProbe.HTTPGet == nil ||
+		container.ReadinessProbe.HTTPGet.Path != "/healthz" {
+		t.Errorf("expected readiness probe on /healthz")
+	}
+	if len(container.Ports) != 1 || container.Ports[0].ContainerPort != 9300 {
+		t.Errorf("expected single container port 9300, got %v", container.Ports)
+	}
+	// No GPU / privileged scaffolding for the coordinator.
+	if podSpec.RuntimeClassName != nil {
+		t.Errorf("coordinator should not set a runtime class")
+	}
+}
+
+func TestBuildCoordinatorService_ClusterIP(t *testing.T) {
+	c := minimalCoordinator()
+	svc := BuildCoordinatorService(c)
+
+	if svc.Name != "test-coordinator" {
+		t.Errorf("service name = %q, want test-coordinator", svc.Name)
+	}
+	if len(svc.Spec.Ports) != 1 || svc.Spec.Ports[0].Port != 9300 {
+		t.Errorf("expected single service port 9300, got %v", svc.Spec.Ports)
+	}
+	if svc.Spec.ClusterIP == corev1.ClusterIPNone {
+		t.Errorf("main coordinator service must not be headless")
+	}
+}
+
+func TestCoordinatorEndpoint(t *testing.T) {
+	c := minimalCoordinator()
+	c.Spec.Port = ptr(int32(9400))
+	want := "http://test-coordinator.default.svc:9400"
+	if got := CoordinatorEndpoint(c); got != want {
+		t.Errorf("CoordinatorEndpoint = %q, want %q", got, want)
+	}
+}
+
+func TestBuildContainerArgs_CoordinatorURL(t *testing.T) {
+	engine := minimalEngine()
+	url := "http://my-coordinator.default.svc:9300"
+	engine.Spec.Coordinator = &lmcachev1alpha1.CoordinatorConnectionSpec{
+		URL:              ptr(url),
+		L2EventReporting: ptr(true),
+	}
+
+	args := BuildContainerArgs(&engine.Spec)
+
+	if got := findArgValue(t, args, "--coordinator-url"); got != url {
+		t.Errorf("--coordinator-url = %q, want %q", got, url)
+	}
+	if got := findArgValue(t, args, "--coordinator-heartbeat-interval"); got != "5" {
+		t.Errorf("--coordinator-heartbeat-interval = %q, want 5", got)
+	}
+	if !slices.Contains(args, "--coordinator-l2-event-reporting") {
+		t.Errorf("expected --coordinator-l2-event-reporting flag")
+	}
+}
+
+func TestBuildContainerArgs_CoordinatorDisabledWithoutURL(t *testing.T) {
+	engine := minimalEngine()
+	// Only a ref is set (unresolved); the builder must not emit a malformed flag.
+	engine.Spec.Coordinator = &lmcachev1alpha1.CoordinatorConnectionSpec{
+		Ref: &corev1.LocalObjectReference{Name: "my-coordinator"},
+	}
+
+	args := BuildContainerArgs(&engine.Spec)
+	if slices.Contains(args, "--coordinator-url") {
+		t.Errorf("expected no --coordinator-url when URL unresolved, got %v", args)
+	}
+}
diff --git a/operator/internal/resources/daemonset.go b/operator/internal/resources/daemonset.go
new file mode 100644
index 0000000..59c8252
--- /dev/null
+++ b/operator/internal/resources/daemonset.go
@@ -0,0 +1,300 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"fmt"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/util/intstr"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+const (
+	// nvidiaRuntimeClass is the RuntimeClass name registered by the NVIDIA GPU
+	// Operator; engine pods request it when gpuVendor is nvidia.
+	nvidiaRuntimeClass = "nvidia"
+
+	// lmcacheServerBinary is the entrypoint binary for the LMCache server inside
+	// the engine image.
+	lmcacheServerBinary = "/opt/venv/bin/lmcache"
+
+	// serverSubcommand is the `lmcache server` subcommand that starts the engine.
+	serverSubcommand = "server"
+
+	// serverPortName is the name of the engine's serving port on the container
+	// and the node-local Service.
+	serverPortName = "server"
+)
+
+// BuildDaemonSet constructs a DaemonSet for the given LMCacheEngine.
+func BuildDaemonSet(engine *lmcachev1alpha1.LMCacheEngine) *appsv1.DaemonSet {
+	return buildDaemonSetCore(engine.Name, engine.Namespace, &engine.Spec, BuildContainerArgs(&engine.Spec), "lmcache/vllm-openai")
+}
+
+// buildDaemonSetCore constructs the DaemonSet shared by the LMCacheEngine and
+// CacheBlendEngine controllers. It is the single source of truth for the
+// GPU/security pod-template scaffolding (hostIPC, runtimeClassName, optional
+// privileged (default false, via spec.Privileged), NVIDIA_VISIBLE_DEVICES,
+// resources without a device-plugin GPU claim) so those settings cannot drift
+// between the two engines.
+//
+// Parameters:
+//   - name, namespace: the owning object's identity, used for labels and metadata.
+//   - spec: the engine spec (LMCacheEngine and CacheBlendEngine reuse the same
+//     shared sub-structs, so callers project the CacheBlendEngine spec into an
+//     *LMCacheEngineSpec before calling).
+//   - containerArgs: the fully serialized server CLI args (callers append any
+//     engine-specific flags such as --engine-type before passing them in).
+//   - defaultImageRepo: the container image repository to use when spec.Image
+//     does not set one.
+func buildDaemonSetCore(
+	name, namespace string,
+	spec *lmcachev1alpha1.LMCacheEngineSpec,
+	containerArgs []string,
+	defaultImageRepo string,
+) *appsv1.DaemonSet {
+	selectorLabels := SelectorLabels(name)
+	podLabels := MergeLabels(StandardLabels(name), spec.PodLabels)
+	podAnnotations := spec.PodAnnotations
+
+	gpuVendor := derefString(spec.GPUVendor, lmcachev1alpha1.GPUVendorNvidia)
+	var runtimeClassName *string
+	if gpuVendor == lmcachev1alpha1.GPUVendorNvidia {
+		rc := nvidiaRuntimeClass
+		runtimeClassName = &rc
+	}
+	privileged := derefBool(spec.Privileged, false)
+
+	serverPort := derefInt32(getServerPort(spec), 5555)
+	imgRepo := defaultImageRepo
+	imgTag := "latest"
+	imgPullPolicy := corev1.PullIfNotPresent
+	if spec.Image != nil {
+		imgRepo = derefString(spec.Image.Repository, imgRepo)
+		imgTag = derefString(spec.Image.Tag, imgTag)
+		switch derefString(spec.Image.PullPolicy, "IfNotPresent") {
+		case "Always":
+			imgPullPolicy = corev1.PullAlways
+		case "Never":
+			imgPullPolicy = corev1.PullNever
+		default:
+			imgPullPolicy = corev1.PullIfNotPresent
+		}
+	}
+
+	// Build env vars
+	envVars := make([]corev1.EnvVar, 0, 5+len(spec.Env))
+	envVars = append(envVars,
+		corev1.EnvVar{
+			Name:  "LMCACHE_LOG_LEVEL",
+			Value: derefString(spec.LogLevel, "INFO"),
+		},
+	)
+	if gpuVendor == lmcachev1alpha1.GPUVendorNvidia {
+		// Expose all GPUs without consuming device plugin resources.
+		// LMCache needs GPU visibility for CUDA IPC, not compute ownership.
+		envVars = append(envVars,
+			corev1.EnvVar{
+				Name:  "NVIDIA_VISIBLE_DEVICES",
+				Value: "all",
+			},
+			corev1.EnvVar{
+				Name:  "NVIDIA_DRIVER_CAPABILITIES",
+				Value: "all",
+			},
+		)
+	}
+	// Inject RESP auth credentials from Secret as env vars so they
+	// don't appear in container args or kubectl describe output.
+	// The DaemonSet references the local (same-namespace) managed copy
+	// created by the controller via reconcileRESPAuthSecret.
+	if spec.L2Backend != nil && spec.L2Backend.RESP != nil && spec.L2Backend.RESP.AuthSecretRef != nil {
+		secretName := RESPAuthSecretName(name)
+		optional := true
+		envVars = append(envVars,
+			corev1.EnvVar{
+				Name: "LMCACHE_RESP_PASSWORD",
+				ValueFrom: &corev1.EnvVarSource{
+					SecretKeyRef: &corev1.SecretKeySelector{
+						LocalObjectReference: corev1.LocalObjectReference{Name: secretName},
+						Key:                  "password",
+					},
+				},
+			},
+			corev1.EnvVar{
+				// Optional: if the managed secret has no "username" key
+				// (password-only auth), this env var is simply not set.
+				Name: "LMCACHE_RESP_USERNAME",
+				ValueFrom: &corev1.EnvVarSource{
+					SecretKeyRef: &corev1.SecretKeySelector{
+						LocalObjectReference: corev1.LocalObjectReference{Name: secretName},
+						Key:                  "username",
+						Optional:             &optional,
+					},
+				},
+			},
+		)
+	}
+	// Inject the pod IP as the coordinator advertise address (downward API)
+	// when registration is enabled and no explicit advertiseIP is set, so the
+	// coordinator can reach this server. The server's --coordinator-advertise-ip
+	// flag falls back to this env var.
+	if spec.Coordinator != nil && derefString(spec.Coordinator.URL, "") != "" &&
+		(spec.Coordinator.AdvertiseIP == nil || *spec.Coordinator.AdvertiseIP == "") {
+		envVars = append(envVars, corev1.EnvVar{
+			Name: "LMCACHE_COORDINATOR_ADVERTISE_IP",
+			ValueFrom: &corev1.EnvVarSource{
+				FieldRef: &corev1.ObjectFieldSelector{
+					FieldPath: "status.podIP",
+				},
+			},
+		})
+	}
+	envVars = append(envVars, spec.Env...)
+
+	// No emptyDir /dev/shm mount — hostIPC: true exposes the host's /dev/shm
+	// directly. An emptyDir mount would shadow it and break CUDA IPC between
+	// LMCache and vLLM pods (cudaIpcOpenMemHandle requires shared /dev/shm).
+	volumes := append([]corev1.Volume{}, spec.Volumes...)
+	volumeMounts := append([]corev1.VolumeMount{}, spec.VolumeMounts...)
+
+	// Build container args. Auth credentials are handled via env vars
+	// (LMCACHE_RESP_USERNAME / LMCACHE_RESP_PASSWORD) injected above,
+	// so no shell wrapper is needed.
+	containerCommand := []string{
+		lmcacheServerBinary,
+		serverSubcommand,
+	}
+
+	// Probes
+	tcpProbe := &corev1.TCPSocketAction{
+		Port: intstr.FromInt32(serverPort),
+	}
+
+	startupProbe := &corev1.Probe{
+		ProbeHandler: corev1.ProbeHandler{
+			TCPSocket: tcpProbe,
+		},
+		InitialDelaySeconds: 5,
+		PeriodSeconds:       5,
+		FailureThreshold:    30,
+	}
+
+	livenessProbe := &corev1.Probe{
+		ProbeHandler: corev1.ProbeHandler{
+			TCPSocket: tcpProbe,
+		},
+		PeriodSeconds: 10,
+	}
+
+	readinessProbe := &corev1.Probe{
+		ProbeHandler: corev1.ProbeHandler{
+			TCPSocket: tcpProbe,
+		},
+		PeriodSeconds: 5,
+	}
+
+	// Container ports
+	httpPort := getHTTPPort(spec)
+	containerPorts := []corev1.ContainerPort{
+		{
+			Name:          serverPortName,
+			ContainerPort: serverPort,
+			Protocol:      corev1.ProtocolTCP,
+		},
+		{
+			Name:          "http",
+			ContainerPort: httpPort,
+			Protocol:      corev1.ProtocolTCP,
+		},
+	}
+
+	// Add metrics port if prometheus is enabled
+	promEnabled := true
+	promPort := int32(9090)
+	if spec.Prometheus != nil {
+		promEnabled = derefBool(spec.Prometheus.Enabled, true)
+		promPort = derefInt32(spec.Prometheus.Port, 9090)
+	}
+	if promEnabled {
+		containerPorts = append(containerPorts, corev1.ContainerPort{
+			Name:          "metrics",
+			ContainerPort: promPort,
+			Protocol:      corev1.ProtocolTCP,
+		})
+	}
+
+	ds := &appsv1.DaemonSet{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      name,
+			Namespace: namespace,
+			Labels:    StandardLabels(name),
+		},
+		Spec: appsv1.DaemonSetSpec{
+			Selector: &metav1.LabelSelector{
+				MatchLabels: selectorLabels,
+			},
+			Template: corev1.PodTemplateSpec{
+				ObjectMeta: metav1.ObjectMeta{
+					Labels:      podLabels,
+					Annotations: podAnnotations,
+				},
+				Spec: corev1.PodSpec{
+					HostIPC:            true,
+					HostNetwork:        derefBool(spec.HostNetwork, false),
+					RuntimeClassName:   runtimeClassName,
+					ServiceAccountName: spec.ServiceAccountName,
+					PriorityClassName:  spec.PriorityClassName,
+					NodeSelector:       spec.NodeSelector,
+					Affinity:           spec.Affinity,
+					Tolerations:        spec.Tolerations,
+					ImagePullSecrets:   spec.ImagePullSecrets,
+					Containers: []corev1.Container{
+						{
+							Name:            "lmcache",
+							Image:           fmt.Sprintf("%s:%s", imgRepo, imgTag),
+							ImagePullPolicy: imgPullPolicy,
+							Command:         containerCommand,
+							Args:            containerArgs,
+							Ports:           containerPorts,
+							Env:             envVars,
+							Resources:       ComputeResources(spec),
+							SecurityContext: &corev1.SecurityContext{
+								Privileged: &privileged,
+							},
+							VolumeMounts:   volumeMounts,
+							StartupProbe:   startupProbe,
+							LivenessProbe:  livenessProbe,
+							ReadinessProbe: readinessProbe,
+						},
+					},
+					Volumes: volumes,
+				},
+			},
+		},
+	}
+
+	if derefBool(spec.HostNetwork, false) {
+		ds.Spec.Template.Spec.DNSPolicy = corev1.DNSClusterFirstWithHostNet
+	}
+
+	return ds
+}
diff --git a/operator/internal/resources/helpers.go b/operator/internal/resources/helpers.go
new file mode 100644
index 0000000..a1d026c
--- /dev/null
+++ b/operator/internal/resources/helpers.go
@@ -0,0 +1,55 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+// derefInt32 returns the value pointed to by p, or def if p is nil.
+func derefInt32(p *int32, def int32) int32 {
+	if p != nil {
+		return *p
+	}
+	return def
+}
+
+// derefString returns the value pointed to by p, or def if p is nil.
+func derefString(p *string, def string) string {
+	if p != nil {
+		return *p
+	}
+	return def
+}
+
+// derefBool returns the value pointed to by p, or def if p is nil.
+func derefBool(p *bool, def bool) bool {
+	if p != nil {
+		return *p
+	}
+	return def
+}
+
+// derefFloat64 returns the value pointed to by p, or def if p is nil.
+func derefFloat64(p *float64, def float64) float64 {
+	if p != nil {
+		return *p
+	}
+	return def
+}
+
+// RESPAuthSecretName returns the name of the managed local copy of the
+// RESP auth secret for a given LMCacheEngine.
+func RESPAuthSecretName(engineName string) string {
+	return engineName + "-resp-auth"
+}
diff --git a/operator/internal/resources/labels.go b/operator/internal/resources/labels.go
new file mode 100644
index 0000000..c7b3ab2
--- /dev/null
+++ b/operator/internal/resources/labels.go
@@ -0,0 +1,44 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import "maps"
+
+// SelectorLabels returns the immutable label subset used for pod selectors.
+func SelectorLabels(name string) map[string]string {
+	return map[string]string{
+		"app.kubernetes.io/name":       "lmcache",
+		"app.kubernetes.io/instance":   name,
+		"app.kubernetes.io/managed-by": "lmcache-operator",
+	}
+}
+
+// StandardLabels returns the full label set for all owned resources.
+func StandardLabels(name string) map[string]string {
+	labels := SelectorLabels(name)
+	labels["app.kubernetes.io/component"] = "cache-engine"
+	return labels
+}
+
+// MergeLabels merges multiple label maps. Later maps take precedence.
+func MergeLabels(labelMaps ...map[string]string) map[string]string {
+	result := make(map[string]string)
+	for _, m := range labelMaps {
+		maps.Copy(result, m)
+	}
+	return result
+}
diff --git a/operator/internal/resources/resources_test.go b/operator/internal/resources/resources_test.go
new file mode 100644
index 0000000..f53d100
--- /dev/null
+++ b/operator/internal/resources/resources_test.go
@@ -0,0 +1,1187 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"encoding/json"
+	"slices"
+	"testing"
+
+	corev1 "k8s.io/api/core/v1"
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	"k8s.io/apimachinery/pkg/api/resource"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+const (
+	testEngineName = "test-engine"
+	testNamespace  = "default"
+)
+
+// --- helpers ---
+
+func ptr[T any](v T) *T { return &v }
+
+func findArgValue(t *testing.T, args []string, flag string) string { //nolint:unparam // test helper, flag varies by caller
+	t.Helper()
+	for i, a := range args {
+		if a == flag && i+1 < len(args) {
+			return args[i+1]
+		}
+	}
+	t.Fatalf("expected %s flag in args", flag)
+	return ""
+}
+
+func minimalEngine() *lmcachev1alpha1.LMCacheEngine {
+	return &lmcachev1alpha1.LMCacheEngine{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      testEngineName,
+			Namespace: testNamespace,
+		},
+		Spec: lmcachev1alpha1.LMCacheEngineSpec{
+			L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		},
+	}
+}
+
+// ===========================
+// Deref helpers
+// ===========================
+
+func TestDerefInt32(t *testing.T) {
+	if v := derefInt32(ptr(int32(42)), 0); v != 42 {
+		t.Fatalf("expected 42, got %d", v)
+	}
+	if v := derefInt32(nil, 99); v != 99 {
+		t.Fatalf("expected 99, got %d", v)
+	}
+}
+
+func TestDerefString(t *testing.T) {
+	if v := derefString(ptr("hello"), "x"); v != "hello" {
+		t.Fatalf("expected hello, got %s", v)
+	}
+	if v := derefString(nil, testNamespace); v != testNamespace {
+		t.Fatalf("expected default, got %s", v)
+	}
+}
+
+func TestDerefBool(t *testing.T) {
+	if v := derefBool(ptr(true), false); !v {
+		t.Fatal("expected true")
+	}
+	if v := derefBool(nil, true); !v {
+		t.Fatal("expected true (default)")
+	}
+	if v := derefBool(nil, false); v {
+		t.Fatal("expected false (default)")
+	}
+}
+
+func TestDerefFloat64(t *testing.T) {
+	if v := derefFloat64(ptr(3.14), 0); v != 3.14 {
+		t.Fatalf("expected 3.14, got %f", v)
+	}
+	if v := derefFloat64(nil, 2.71); v != 2.71 {
+		t.Fatalf("expected 2.71, got %f", v)
+	}
+}
+
+// ===========================
+// Labels
+// ===========================
+
+func TestSelectorLabels(t *testing.T) {
+	labels := SelectorLabels("my-cache")
+	expected := map[string]string{
+		"app.kubernetes.io/name":       "lmcache",
+		"app.kubernetes.io/instance":   "my-cache",
+		"app.kubernetes.io/managed-by": "lmcache-operator",
+	}
+	if len(labels) != len(expected) {
+		t.Fatalf("expected %d labels, got %d", len(expected), len(labels))
+	}
+	for k, v := range expected {
+		if labels[k] != v {
+			t.Errorf("label %s: expected %s, got %s", k, v, labels[k])
+		}
+	}
+}
+
+func TestStandardLabels(t *testing.T) {
+	labels := StandardLabels("my-cache")
+	if labels["app.kubernetes.io/component"] != "cache-engine" {
+		t.Fatal("missing component label")
+	}
+	// Should include selector labels too
+	if labels["app.kubernetes.io/instance"] != "my-cache" {
+		t.Fatal("missing instance label")
+	}
+}
+
+func TestMergeLabels(t *testing.T) {
+	a := map[string]string{"k1": "v1", "k2": "v2"}
+	b := map[string]string{"k2": "override", "k3": "v3"}
+	merged := MergeLabels(a, b)
+
+	if merged["k1"] != "v1" {
+		t.Error("k1 should be v1")
+	}
+	if merged["k2"] != "override" {
+		t.Error("k2 should be overridden to 'override'")
+	}
+	if merged["k3"] != "v3" {
+		t.Error("k3 should be v3")
+	}
+}
+
+func TestMergeLabels_Empty(t *testing.T) {
+	merged := MergeLabels()
+	if len(merged) != 0 {
+		t.Fatal("expected empty map")
+	}
+}
+
+func TestMergeLabels_NilMaps(t *testing.T) {
+	merged := MergeLabels(nil, map[string]string{"k": "v"}, nil)
+	if merged["k"] != "v" {
+		t.Fatal("expected k=v")
+	}
+}
+
+// ===========================
+// ComputeResources
+// ===========================
+
+func TestComputeResources_AutoComputed(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+	}
+	res := ComputeResources(spec)
+
+	// memReq = ceil(10+5) = 15Gi
+	expectedReq := resource.MustParse("15Gi")
+	if !res.Requests.Memory().Equal(expectedReq) {
+		t.Fatalf("expected memory request 15Gi, got %s", res.Requests.Memory())
+	}
+
+	// memLim = ceil(15*1.5) = 23Gi
+	expectedLim := resource.MustParse("23Gi")
+	if !res.Limits.Memory().Equal(expectedLim) {
+		t.Fatalf("expected memory limit 23Gi, got %s", res.Limits.Memory())
+	}
+
+	// CPU request = 4
+	expectedCPU := resource.MustParse("4")
+	if !res.Requests.Cpu().Equal(expectedCPU) {
+		t.Fatalf("expected cpu request 4, got %s", res.Requests.Cpu())
+	}
+}
+
+func TestComputeResources_FractionalSizeGB(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 0.5},
+	}
+	res := ComputeResources(spec)
+
+	// memReq = ceil(0.5+5) = 6Gi
+	expectedReq := resource.MustParse("6Gi")
+	if !res.Requests.Memory().Equal(expectedReq) {
+		t.Fatalf("expected memory request 6Gi, got %s", res.Requests.Memory())
+	}
+
+	// memLim = ceil(6*1.5) = 9Gi
+	expectedLim := resource.MustParse("9Gi")
+	if !res.Limits.Memory().Equal(expectedLim) {
+		t.Fatalf("expected memory limit 9Gi, got %s", res.Limits.Memory())
+	}
+}
+
+func TestComputeResources_Override(t *testing.T) {
+	override := &corev1.ResourceRequirements{
+		Requests: corev1.ResourceList{
+			corev1.ResourceMemory: resource.MustParse("1Gi"),
+		},
+	}
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1:                lmcachev1alpha1.L1BackendSpec{SizeGB: 100},
+		ResourceOverrides: override,
+	}
+	res := ComputeResources(spec)
+	if !res.Requests.Memory().Equal(resource.MustParse("1Gi")) {
+		t.Fatalf("expected override to apply, got %s", res.Requests.Memory())
+	}
+}
+
+// ===========================
+// BuildContainerArgs
+// ===========================
+
+func TestBuildContainerArgs_Defaults(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+	}
+	args := BuildContainerArgs(spec)
+
+	assertArg(t, args, "--host", "0.0.0.0")
+	assertArg(t, args, "--port", "5555")
+	assertArg(t, args, "--l1-size-gb", "10.0")
+	assertArg(t, args, "--chunk-size", "256")
+	assertArg(t, args, "--max-workers", "1")
+	assertArg(t, args, "--hash-algorithm", "blake3")
+	assertArg(t, args, "--eviction-policy", "LRU")
+	assertArg(t, args, "--eviction-trigger-watermark", "0.80")
+	assertArg(t, args, "--eviction-ratio", "0.20")
+	assertArg(t, args, "--prometheus-port", "9090")
+	assertNoArg(t, args, "--disable-prometheus")
+}
+
+func TestBuildContainerArgs_CustomServer(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 5},
+		Server: &lmcachev1alpha1.ServerSpec{
+			Port:          ptr(int32(8080)),
+			ChunkSize:     ptr(int32(512)),
+			MaxWorkers:    ptr(int32(4)),
+			HashAlgorithm: ptr("sha256_cbor"),
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	assertArg(t, args, "--port", "8080")
+	assertArg(t, args, "--chunk-size", "512")
+	assertArg(t, args, "--max-workers", "4")
+	assertArg(t, args, "--hash-algorithm", "sha256_cbor")
+}
+
+func TestBuildContainerArgs_CustomEviction(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		Eviction: &lmcachev1alpha1.EvictionSpec{
+			Policy:           ptr("LRU"),
+			TriggerWatermark: ptr(0.9),
+			EvictionRatio:    ptr(0.3),
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	assertArg(t, args, "--eviction-policy", "LRU")
+	assertArg(t, args, "--eviction-trigger-watermark", "0.90")
+	assertArg(t, args, "--eviction-ratio", "0.30")
+}
+
+func TestBuildContainerArgs_PrometheusDisabled(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		Prometheus: &lmcachev1alpha1.PrometheusSpec{
+			Enabled: ptr(false),
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	assertHasArg(t, args, "--disable-prometheus")
+	assertNoArg(t, args, "--prometheus-port")
+}
+
+func TestBuildContainerArgs_CustomPrometheusPort(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		Prometheus: &lmcachev1alpha1.PrometheusSpec{
+			Enabled: ptr(true),
+			Port:    ptr(int32(8888)),
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	assertArg(t, args, "--prometheus-port", "8888")
+}
+
+func TestBuildContainerArgs_L2RESP(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		L2Backend: &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis.default.svc",
+				Port: 6379,
+			},
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	// Default policies should be present
+	assertArg(t, args, "--l2-store-policy", "default")
+	assertArg(t, args, "--l2-prefetch-policy", "default")
+	assertArg(t, args, "--l2-prefetch-max-in-flight", "8")
+
+	l2JSON := findArgValue(t, args, "--l2-adapter")
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(l2JSON), &parsed); err != nil {
+		t.Fatalf("failed to parse L2 JSON: %v", err)
+	}
+	if parsed["type"] != "resp" {
+		t.Fatalf("expected type=resp, got %v", parsed["type"])
+	}
+	if parsed["host"] != "redis.default.svc" {
+		t.Fatalf("expected host=redis.default.svc, got %v", parsed["host"])
+	}
+	if parsed["port"] != float64(6379) {
+		t.Fatalf("expected port=6379, got %v", parsed["port"])
+	}
+	if parsed["num_workers"] != float64(8) {
+		t.Fatalf("expected num_workers=8, got %v", parsed["num_workers"])
+	}
+	// No auth — username/password should be absent
+	if _, ok := parsed["username"]; ok {
+		t.Fatal("expected no username without authSecretRef")
+	}
+}
+
+func TestBuildContainerArgs_L2RESPWithAuth(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		L2Backend: &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis",
+				Port: 6379,
+				AuthSecretRef: &lmcachev1alpha1.SecretReference{
+					Name: "redis-auth",
+				},
+			},
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	l2JSON := findArgValue(t, args, "--l2-adapter")
+
+	// Credentials should NOT be in the JSON — they are passed via env vars.
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(l2JSON), &parsed); err != nil {
+		t.Fatalf("failed to parse L2 JSON: %v", err)
+	}
+	if _, ok := parsed["username"]; ok {
+		t.Fatal("username should not be in L2 JSON — it is passed via env var")
+	}
+	if _, ok := parsed["password"]; ok {
+		t.Fatal("password should not be in L2 JSON — it is passed via env var")
+	}
+}
+
+func TestBuildContainerArgs_L2RESPCustomWorkers(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		L2Backend: &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host:          "redis",
+				Port:          6379,
+				NumWorkers:    ptr(int32(16)),
+				MaxCapacityGB: ptr(50.0),
+			},
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	l2JSON := findArgValue(t, args, "--l2-adapter")
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(l2JSON), &parsed); err != nil {
+		t.Fatalf("failed to parse L2 JSON: %v", err)
+	}
+	if parsed["num_workers"] != float64(16) {
+		t.Fatalf("expected num_workers=16, got %v", parsed["num_workers"])
+	}
+	if parsed["max_capacity_gb"] != float64(50) {
+		t.Fatalf("expected max_capacity_gb=50, got %v", parsed["max_capacity_gb"])
+	}
+}
+
+func TestBuildContainerArgs_L2Raw(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		L2Backend: &lmcachev1alpha1.L2BackendSpec{
+			Raw: &lmcachev1alpha1.RawL2AdapterSpec{
+				Type: "mock",
+				Config: map[string]apiextensionsv1.JSON{
+					"max_size_gb":       {Raw: []byte(`256`)},
+					"mock_bandwidth_gb": {Raw: []byte(`10`)},
+				},
+			},
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	l2JSON := findArgValue(t, args, "--l2-adapter")
+
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(l2JSON), &parsed); err != nil {
+		t.Fatalf("failed to parse L2 JSON: %v", err)
+	}
+	if parsed["type"] != "mock" {
+		t.Fatalf("expected type=mock, got %v", parsed["type"])
+	}
+	if parsed["max_size_gb"] != float64(256) {
+		t.Fatalf("expected max_size_gb=256, got %v", parsed["max_size_gb"])
+	}
+}
+
+func TestBuildContainerArgs_L2CustomPolicies(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		L2Backend: &lmcachev1alpha1.L2BackendSpec{
+			RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+				Host: "redis",
+				Port: 6379,
+			},
+			StorePolicy:         ptr("skip_l1"),
+			PrefetchPolicy:      ptr("default"),
+			PrefetchMaxInFlight: ptr(int32(16)),
+		},
+	}
+	args := BuildContainerArgs(spec)
+
+	assertArg(t, args, "--l2-store-policy", "skip_l1")
+	assertArg(t, args, "--l2-prefetch-policy", "default")
+	assertArg(t, args, "--l2-prefetch-max-in-flight", "16")
+}
+
+func TestBuildContainerArgs_NoL2Backend(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+	}
+	args := BuildContainerArgs(spec)
+
+	for _, a := range args {
+		if a == "--l2-adapter" {
+			t.Fatal("expected no --l2-adapter flag when L2Backend is nil")
+		}
+		if a == "--l2-store-policy" {
+			t.Fatal("expected no --l2-store-policy flag when L2Backend is nil")
+		}
+	}
+}
+
+func TestBuildContainerArgs_ExtraArgs(t *testing.T) {
+	spec := &lmcachev1alpha1.LMCacheEngineSpec{
+		L1:        lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+		ExtraArgs: []string{"--l1-init-size-gb", "5", "--custom-flag", "value"},
+	}
+	args := BuildContainerArgs(spec)
+
+	// extraArgs should be appended at the end
+	assertArg(t, args, "--l1-init-size-gb", "5")
+	assertArg(t, args, "--custom-flag", "value")
+}
+
+// ===========================
+// BuildDaemonSet
+// ===========================
+
+func TestBuildDaemonSet_Minimal(t *testing.T) {
+	engine := minimalEngine()
+	ds := BuildDaemonSet(engine)
+
+	if ds.Name != testEngineName {
+		t.Fatalf("expected name test-engine, got %s", ds.Name)
+	}
+	if ds.Namespace != testNamespace {
+		t.Fatalf("expected namespace default, got %s", ds.Namespace)
+	}
+
+	// Should have selector labels
+	sel := ds.Spec.Selector.MatchLabels
+	if sel["app.kubernetes.io/instance"] != testEngineName {
+		t.Fatal("missing instance selector label")
+	}
+
+	// Should NOT have HostNetwork (uses Service with internalTrafficPolicy=Local instead)
+	if ds.Spec.Template.Spec.HostNetwork {
+		t.Fatal("expected HostNetwork=false")
+	}
+
+	// Should have HostIPC=true (required for CUDA IPC)
+	if !ds.Spec.Template.Spec.HostIPC {
+		t.Fatal("expected HostIPC=true")
+	}
+
+	// Should have exactly 1 container
+	if len(ds.Spec.Template.Spec.Containers) != 1 {
+		t.Fatalf("expected 1 container, got %d", len(ds.Spec.Template.Spec.Containers))
+	}
+
+	c := ds.Spec.Template.Spec.Containers[0]
+	if c.Name != "lmcache" {
+		t.Fatalf("expected container name lmcache, got %s", c.Name)
+	}
+	if c.Image != "lmcache/vllm-openai:latest" {
+		t.Fatalf("expected default image, got %s", c.Image)
+	}
+	if c.ImagePullPolicy != corev1.PullIfNotPresent {
+		t.Fatalf("expected PullIfNotPresent, got %s", c.ImagePullPolicy)
+	}
+
+	// Should have probes
+	if c.StartupProbe == nil {
+		t.Fatal("missing startup probe")
+	}
+	if c.LivenessProbe == nil {
+		t.Fatal("missing liveness probe")
+	}
+	if c.ReadinessProbe == nil {
+		t.Fatal("missing readiness probe")
+	}
+
+	// Should NOT have emptyDir /dev/shm volume (hostIPC provides host's /dev/shm)
+	for _, v := range ds.Spec.Template.Spec.Volumes {
+		if v.Name == "dshm" {
+			t.Fatal("dshm emptyDir volume should not be present — it shadows host /dev/shm and breaks CUDA IPC")
+		}
+	}
+
+	// Should have no volumes by default (no user-specified volumes)
+	if len(ds.Spec.Template.Spec.Volumes) != 0 {
+		t.Fatalf("expected 0 volumes, got %d", len(ds.Spec.Template.Spec.Volumes))
+	}
+
+	// Should have no volume mounts by default
+	if len(c.VolumeMounts) != 0 {
+		t.Fatalf("expected 0 volume mounts, got %d", len(c.VolumeMounts))
+	}
+
+	// Should have LMCACHE_LOG_LEVEL env var
+	foundLogLevel := false
+	foundVisibleDevices := false
+	for _, e := range c.Env {
+		if e.Name == "LMCACHE_LOG_LEVEL" && e.Value == "INFO" {
+			foundLogLevel = true
+		}
+		if e.Name == "NVIDIA_VISIBLE_DEVICES" && e.Value == "all" {
+			foundVisibleDevices = true
+		}
+	}
+	if !foundLogLevel {
+		t.Fatal("missing LMCACHE_LOG_LEVEL env var")
+	}
+	if !foundVisibleDevices {
+		t.Fatal("missing NVIDIA_VISIBLE_DEVICES env var")
+	}
+
+	// Should have 3 ports (server + http + metrics) by default
+	if len(c.Ports) != 3 {
+		t.Fatalf("expected 3 container ports, got %d", len(c.Ports))
+	}
+}
+
+func TestBuildDaemonSet_CustomImage(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Image = &lmcachev1alpha1.ImageSpec{
+		Repository: ptr("custom/image"),
+		Tag:        ptr("v1.0"),
+		PullPolicy: ptr("Always"),
+	}
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	if c.Image != "custom/image:v1.0" {
+		t.Fatalf("expected custom/image:v1.0, got %s", c.Image)
+	}
+	if c.ImagePullPolicy != corev1.PullAlways {
+		t.Fatalf("expected PullAlways, got %s", c.ImagePullPolicy)
+	}
+}
+
+func TestBuildDaemonSet_NeverPullPolicy(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Image = &lmcachev1alpha1.ImageSpec{
+		PullPolicy: ptr("Never"),
+	}
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+	if c.ImagePullPolicy != corev1.PullNever {
+		t.Fatalf("expected PullNever, got %s", c.ImagePullPolicy)
+	}
+}
+
+func TestBuildDaemonSet_PrometheusDisabled(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Prometheus = &lmcachev1alpha1.PrometheusSpec{
+		Enabled: ptr(false),
+	}
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	// Should have server + http ports, no metrics port
+	if len(c.Ports) != 2 {
+		t.Fatalf("expected 2 container ports, got %d", len(c.Ports))
+	}
+	if c.Ports[0].Name != serverPortName {
+		t.Fatalf("expected port name 'server', got %s", c.Ports[0].Name)
+	}
+}
+
+func TestBuildDaemonSet_CustomEnvAndVolumes(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Env = []corev1.EnvVar{
+		{Name: "CUSTOM_VAR", Value: "custom_value"},
+	}
+	engine.Spec.Volumes = []corev1.Volume{
+		{Name: "extra-vol", VolumeSource: corev1.VolumeSource{EmptyDir: &corev1.EmptyDirVolumeSource{}}},
+	}
+	engine.Spec.VolumeMounts = []corev1.VolumeMount{
+		{Name: "extra-vol", MountPath: "/extra"},
+	}
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	// Should have LMCACHE_LOG_LEVEL + NVIDIA_VISIBLE_DEVICES + NVIDIA_DRIVER_CAPABILITIES + CUSTOM_VAR
+	if len(c.Env) != 4 {
+		t.Fatalf("expected 4 env vars, got %d", len(c.Env))
+	}
+
+	// Should have only user-specified extra-vol (no built-in dshm)
+	if len(ds.Spec.Template.Spec.Volumes) != 1 {
+		t.Fatalf("expected 1 volume, got %d", len(ds.Spec.Template.Spec.Volumes))
+	}
+
+	// Should have only user-specified extra mount
+	if len(c.VolumeMounts) != 1 {
+		t.Fatalf("expected 1 volume mount, got %d", len(c.VolumeMounts))
+	}
+}
+
+func TestBuildDaemonSet_NodeSelectorAndTolerations(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.NodeSelector = map[string]string{"nvidia.com/gpu.present": "true"}
+	engine.Spec.Tolerations = []corev1.Toleration{
+		{Key: "gpu", Operator: corev1.TolerationOpExists, Effect: corev1.TaintEffectNoSchedule},
+	}
+	engine.Spec.ServiceAccountName = "my-sa"
+	engine.Spec.PriorityClassName = "high-priority"
+
+	ds := BuildDaemonSet(engine)
+	podSpec := ds.Spec.Template.Spec
+
+	if podSpec.NodeSelector["nvidia.com/gpu.present"] != "true" {
+		t.Fatal("missing node selector")
+	}
+	if len(podSpec.Tolerations) != 1 {
+		t.Fatal("missing tolerations")
+	}
+	if podSpec.ServiceAccountName != "my-sa" {
+		t.Fatalf("expected SA my-sa, got %s", podSpec.ServiceAccountName)
+	}
+	if podSpec.PriorityClassName != "high-priority" {
+		t.Fatalf("expected priority class high-priority, got %s", podSpec.PriorityClassName)
+	}
+}
+
+func TestBuildDaemonSet_PodLabelsAndAnnotations(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.PodLabels = map[string]string{"custom": "label"}
+	engine.Spec.PodAnnotations = map[string]string{"anno": "value"}
+
+	ds := BuildDaemonSet(engine)
+
+	if ds.Spec.Template.Labels["custom"] != "label" {
+		t.Fatal("missing custom pod label")
+	}
+	if ds.Spec.Template.Annotations["anno"] != "value" {
+		t.Fatal("missing custom pod annotation")
+	}
+}
+
+func TestBuildDaemonSet_RESPNoAuth(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+		RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+			Host: "redis",
+			Port: 6379,
+		},
+	}
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	// Should use direct command, not shell wrapper
+	if c.Command[0] != lmcacheServerBinary || c.Command[1] != serverSubcommand {
+		t.Fatalf("expected lmcache server command, got %v", c.Command)
+	}
+
+	// Should have --l2-adapter in args
+	if !slices.Contains(c.Args, "--l2-adapter") {
+		t.Fatal("expected --l2-adapter in args")
+	}
+
+	// Should NOT have RESP auth env vars
+	for _, e := range c.Env {
+		if e.Name == "LMCACHE_RESP_USERNAME" || e.Name == "LMCACHE_RESP_PASSWORD" {
+			t.Fatalf("unexpected auth env var %s without authSecretRef", e.Name)
+		}
+	}
+}
+
+func TestBuildDaemonSet_RESPWithAuth(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.L2Backend = &lmcachev1alpha1.L2BackendSpec{
+		RESP: &lmcachev1alpha1.RESPL2AdapterSpec{
+			Host: "redis",
+			Port: 6379,
+			AuthSecretRef: &lmcachev1alpha1.SecretReference{
+				Name: "redis-auth",
+			},
+		},
+	}
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	// Should use direct python command (no shell wrapper needed)
+	if c.Command[0] != lmcacheServerBinary || c.Command[1] != serverSubcommand {
+		t.Fatalf("expected lmcache server command, got %v", c.Command)
+	}
+
+	// Should have RESP auth env vars from secret
+	foundUser := false
+	foundPass := false
+	for _, e := range c.Env {
+		if e.Name == "LMCACHE_RESP_USERNAME" {
+			foundUser = true
+			if e.ValueFrom == nil || e.ValueFrom.SecretKeyRef == nil {
+				t.Fatal("expected secretKeyRef for LMCACHE_RESP_USERNAME")
+			}
+			expectedSecret := RESPAuthSecretName(testEngineName)
+			if e.ValueFrom.SecretKeyRef.Name != expectedSecret {
+				t.Fatalf("expected secret name %s, got %s", expectedSecret, e.ValueFrom.SecretKeyRef.Name)
+			}
+			if e.ValueFrom.SecretKeyRef.Key != "username" {
+				t.Fatalf("expected key username, got %s", e.ValueFrom.SecretKeyRef.Key)
+			}
+		}
+		if e.Name == "LMCACHE_RESP_PASSWORD" {
+			foundPass = true
+			if e.ValueFrom == nil || e.ValueFrom.SecretKeyRef == nil {
+				t.Fatal("expected secretKeyRef for LMCACHE_RESP_PASSWORD")
+			}
+			if e.ValueFrom.SecretKeyRef.Key != "password" {
+				t.Fatalf("expected key password, got %s", e.ValueFrom.SecretKeyRef.Key)
+			}
+		}
+	}
+	if !foundUser {
+		t.Fatal("missing LMCACHE_RESP_USERNAME env var")
+	}
+	if !foundPass {
+		t.Fatal("missing LMCACHE_RESP_PASSWORD env var")
+	}
+}
+
+// ===========================
+// BuildLookupService
+// ===========================
+
+func TestBuildLookupService_Default(t *testing.T) {
+	engine := minimalEngine()
+	svc := BuildLookupService(engine)
+
+	if svc.Name != testEngineName {
+		t.Fatalf("expected name test-engine, got %s", svc.Name)
+	}
+	if svc.Namespace != testNamespace {
+		t.Fatalf("expected namespace default, got %s", svc.Namespace)
+	}
+	// Should NOT be headless — needs a ClusterIP for kube-proxy routing
+	if svc.Spec.ClusterIP == corev1.ClusterIPNone {
+		t.Fatal("lookup service should not be headless")
+	}
+	// Should have internalTrafficPolicy=Local
+	if svc.Spec.InternalTrafficPolicy == nil || *svc.Spec.InternalTrafficPolicy != corev1.ServiceInternalTrafficPolicyLocal {
+		t.Fatal("expected internalTrafficPolicy=Local")
+	}
+	if len(svc.Spec.Ports) != 2 {
+		t.Fatalf("expected 2 ports, got %d", len(svc.Spec.Ports))
+	}
+	if svc.Spec.Ports[0].Port != 5555 {
+		t.Fatalf("expected server port 5555, got %d", svc.Spec.Ports[0].Port)
+	}
+	if svc.Spec.Ports[0].Name != serverPortName {
+		t.Fatalf("expected port name server, got %s", svc.Spec.Ports[0].Name)
+	}
+	if svc.Spec.Ports[1].Port != 8080 {
+		t.Fatalf("expected http port 8080, got %d", svc.Spec.Ports[1].Port)
+	}
+	if svc.Spec.Ports[1].Name != "http" {
+		t.Fatalf("expected port name http, got %s", svc.Spec.Ports[1].Name)
+	}
+
+	sel := svc.Spec.Selector
+	if sel["app.kubernetes.io/instance"] != testEngineName {
+		t.Fatal("missing instance selector")
+	}
+}
+
+func TestBuildLookupService_CustomPort(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Server = &lmcachev1alpha1.ServerSpec{
+		Port: ptr(int32(8080)),
+	}
+	svc := BuildLookupService(engine)
+
+	if svc.Spec.Ports[0].Port != 8080 {
+		t.Fatalf("expected port 8080, got %d", svc.Spec.Ports[0].Port)
+	}
+}
+
+// ===========================
+// BuildMetricsService
+// ===========================
+
+func TestBuildMetricsService_Default(t *testing.T) {
+	engine := minimalEngine()
+	svc := BuildMetricsService(engine)
+
+	if svc.Name != testEngineName+"-metrics" {
+		t.Fatalf("expected name test-engine-metrics, got %s", svc.Name)
+	}
+	if svc.Namespace != testNamespace {
+		t.Fatalf("expected namespace default, got %s", svc.Namespace)
+	}
+	if svc.Spec.ClusterIP != corev1.ClusterIPNone {
+		t.Fatal("expected headless service (ClusterIP=None)")
+	}
+	if len(svc.Spec.Ports) != 1 {
+		t.Fatalf("expected 1 port, got %d", len(svc.Spec.Ports))
+	}
+	if svc.Spec.Ports[0].Port != 9090 {
+		t.Fatalf("expected port 9090, got %d", svc.Spec.Ports[0].Port)
+	}
+	if svc.Spec.Ports[0].Name != "metrics" {
+		t.Fatalf("expected port name metrics, got %s", svc.Spec.Ports[0].Name)
+	}
+
+	// Selector should match SelectorLabels
+	sel := svc.Spec.Selector
+	if sel["app.kubernetes.io/instance"] != testEngineName {
+		t.Fatal("missing instance selector")
+	}
+}
+
+func TestBuildMetricsService_CustomPort(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Prometheus = &lmcachev1alpha1.PrometheusSpec{
+		Port: ptr(int32(8888)),
+	}
+	svc := BuildMetricsService(engine)
+
+	if svc.Spec.Ports[0].Port != 8888 {
+		t.Fatalf("expected port 8888, got %d", svc.Spec.Ports[0].Port)
+	}
+}
+
+// ===========================
+// BuildConnectionConfigMap
+// ===========================
+
+func TestBuildConnectionConfigMap_Default(t *testing.T) {
+	engine := minimalEngine()
+	cm := BuildConnectionConfigMap(engine)
+
+	if cm.Name != "test-engine-connection" {
+		t.Fatalf("expected name test-engine-connection, got %s", cm.Name)
+	}
+	if cm.Namespace != testNamespace {
+		t.Fatalf("expected namespace default, got %s", cm.Namespace)
+	}
+
+	jsonStr, ok := cm.Data["kv-transfer-config.json"]
+	if !ok {
+		t.Fatal("missing kv-transfer-config.json key")
+	}
+
+	var config map[string]any
+	if err := json.Unmarshal([]byte(jsonStr), &config); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+
+	if config["kv_connector"] != "LMCacheMPConnector" {
+		t.Fatalf("expected kv_connector=LMCacheMPConnector, got %v", config["kv_connector"])
+	}
+	if config["kv_connector_module_path"] != "lmcache.integration.vllm.lmcache_mp_connector" {
+		t.Fatalf(
+			"expected kv_connector_module_path=lmcache.integration.vllm.lmcache_mp_connector, got %v",
+			config["kv_connector_module_path"],
+		)
+	}
+	if config["kv_role"] != "kv_both" {
+		t.Fatalf("expected kv_role=kv_both, got %v", config["kv_role"])
+	}
+
+	extra := config["kv_connector_extra_config"].(map[string]any)
+	if extra["lmcache.mp.host"] != "tcp://test-engine.default.svc.cluster.local" {
+		t.Fatalf("expected service DNS host, got %v", extra["lmcache.mp.host"])
+	}
+	if extra["lmcache.mp.port"] != "5555" {
+		t.Fatalf("expected port 5555, got %v", extra["lmcache.mp.port"])
+	}
+}
+
+func TestBuildConnectionConfigMap_CustomPort(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Server = &lmcachev1alpha1.ServerSpec{
+		Port: ptr(int32(8080)),
+	}
+	cm := BuildConnectionConfigMap(engine)
+
+	jsonStr := cm.Data["kv-transfer-config.json"]
+	var config map[string]any
+	if err := json.Unmarshal([]byte(jsonStr), &config); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+	extra := config["kv_connector_extra_config"].(map[string]any)
+	if extra["lmcache.mp.port"] != "8080" {
+		t.Fatalf("expected port 8080, got %v", extra["lmcache.mp.port"])
+	}
+}
+
+// ===========================
+// ServiceMonitor
+// ===========================
+
+func TestServiceMonitorEnabled(t *testing.T) {
+	tests := []struct {
+		name string
+		spec lmcachev1alpha1.LMCacheEngineSpec
+		want bool
+	}{
+		{
+			name: "nil prometheus",
+			spec: lmcachev1alpha1.LMCacheEngineSpec{L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10}},
+			want: false,
+		},
+		{
+			name: "nil service monitor",
+			spec: lmcachev1alpha1.LMCacheEngineSpec{
+				L1:         lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+				Prometheus: &lmcachev1alpha1.PrometheusSpec{},
+			},
+			want: false,
+		},
+		{
+			name: "disabled",
+			spec: lmcachev1alpha1.LMCacheEngineSpec{
+				L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+				Prometheus: &lmcachev1alpha1.PrometheusSpec{
+					ServiceMonitor: &lmcachev1alpha1.ServiceMonitorSpec{Enabled: ptr(false)},
+				},
+			},
+			want: false,
+		},
+		{
+			name: "enabled",
+			spec: lmcachev1alpha1.LMCacheEngineSpec{
+				L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+				Prometheus: &lmcachev1alpha1.PrometheusSpec{
+					ServiceMonitor: &lmcachev1alpha1.ServiceMonitorSpec{Enabled: ptr(true)},
+				},
+			},
+			want: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ServiceMonitorEnabled(&tt.spec)
+			if got != tt.want {
+				t.Fatalf("expected %v, got %v", tt.want, got)
+			}
+		})
+	}
+}
+
+func TestBuildServiceMonitor(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Prometheus = &lmcachev1alpha1.PrometheusSpec{
+		ServiceMonitor: &lmcachev1alpha1.ServiceMonitorSpec{
+			Enabled:  ptr(true),
+			Interval: ptr("15s"),
+			Labels:   map[string]string{"release": "prom"},
+		},
+	}
+
+	sm := BuildServiceMonitor(engine)
+
+	if sm.Name != testEngineName {
+		t.Fatalf("expected name test-engine, got %s", sm.Name)
+	}
+	if sm.Namespace != testNamespace {
+		t.Fatalf("expected namespace default, got %s", sm.Namespace)
+	}
+
+	// Labels should include standard + custom
+	if sm.Labels["release"] != "prom" {
+		t.Fatal("missing custom label 'release'")
+	}
+	if sm.Labels["app.kubernetes.io/instance"] != testEngineName {
+		t.Fatal("missing standard label")
+	}
+
+	// Endpoints
+	if len(sm.Spec.Endpoints) != 1 {
+		t.Fatalf("expected 1 endpoint, got %d", len(sm.Spec.Endpoints))
+	}
+	if string(sm.Spec.Endpoints[0].Interval) != "15s" {
+		t.Fatalf("expected interval 15s, got %s", sm.Spec.Endpoints[0].Interval)
+	}
+	if sm.Spec.Endpoints[0].Port != "metrics" {
+		t.Fatalf("expected port name metrics, got %s", sm.Spec.Endpoints[0].Port)
+	}
+
+	// Selector
+	if sm.Spec.Selector.MatchLabels["app.kubernetes.io/instance"] != testEngineName {
+		t.Fatal("missing selector label")
+	}
+}
+
+// ===========================
+// Test helpers
+// ===========================
+
+func assertArg(t *testing.T, args []string, flag, value string) {
+	t.Helper()
+	for i, a := range args {
+		if a == flag {
+			if i+1 < len(args) && args[i+1] == value {
+				return
+			}
+			t.Fatalf("flag %s found but value is %s, expected %s", flag, args[i+1], value)
+		}
+	}
+	t.Fatalf("flag %s not found in args: %v", flag, args)
+}
+
+func assertHasArg(t *testing.T, args []string, flag string) {
+	t.Helper()
+	if !slices.Contains(args, flag) {
+		t.Fatalf("flag %s not found in args: %v", flag, args)
+	}
+}
+
+func assertNoArg(t *testing.T, args []string, flag string) {
+	t.Helper()
+	for _, a := range args {
+		if a == flag {
+			t.Fatalf("flag %s should not be present in args", flag)
+		}
+	}
+}
+
+// --- GPUVendor tests ---
+
+func TestBuildDaemonSet_GPUVendorNvidiaDefault(t *testing.T) {
+	engine := minimalEngine()
+	engine.SetDefaults()
+
+	ds := BuildDaemonSet(engine)
+	podSpec := ds.Spec.Template.Spec
+
+	if podSpec.RuntimeClassName == nil || *podSpec.RuntimeClassName != nvidiaRuntimeClass {
+		t.Fatalf("expected RuntimeClassName=nvidia, got %v", podSpec.RuntimeClassName)
+	}
+
+	c := podSpec.Containers[0]
+	if !hasEnvAll(c.Env, "NVIDIA_VISIBLE_DEVICES") {
+		t.Fatal("missing NVIDIA_VISIBLE_DEVICES=all on default (nvidia) vendor")
+	}
+	if !hasEnvAll(c.Env, "NVIDIA_DRIVER_CAPABILITIES") {
+		t.Fatal("missing NVIDIA_DRIVER_CAPABILITIES=all on default (nvidia) vendor")
+	}
+}
+
+func TestBuildDaemonSet_GPUVendorAMD(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.GPUVendor = ptr(lmcachev1alpha1.GPUVendorAMD)
+	engine.SetDefaults()
+
+	ds := BuildDaemonSet(engine)
+	podSpec := ds.Spec.Template.Spec
+
+	if podSpec.RuntimeClassName != nil {
+		t.Fatalf("expected nil RuntimeClassName for AMD, got %q", *podSpec.RuntimeClassName)
+	}
+
+	c := podSpec.Containers[0]
+	for _, e := range c.Env {
+		if e.Name == "NVIDIA_VISIBLE_DEVICES" || e.Name == "NVIDIA_DRIVER_CAPABILITIES" {
+			t.Fatalf("unexpected NVIDIA env var on AMD vendor: %s=%s", e.Name, e.Value)
+		}
+	}
+}
+
+func TestBuildDaemonSet_HostNetworkEnabled(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.HostNetwork = ptr(true)
+	engine.SetDefaults()
+
+	ds := BuildDaemonSet(engine)
+	podSpec := ds.Spec.Template.Spec
+
+	if !podSpec.HostNetwork {
+		t.Fatal("expected HostNetwork=true")
+	}
+	if podSpec.DNSPolicy != corev1.DNSClusterFirstWithHostNet {
+		t.Fatalf("expected DNSPolicy=ClusterFirstWithHostNet, got %s", podSpec.DNSPolicy)
+	}
+}
+
+func TestBuildDaemonSet_PrivilegedDefaultFalse(t *testing.T) {
+	// minimalEngine leaves spec.Privileged nil; the operator must not run the
+	// container privileged unless explicitly opted in.
+	ds := BuildDaemonSet(minimalEngine())
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	if c.SecurityContext == nil || c.SecurityContext.Privileged == nil || *c.SecurityContext.Privileged {
+		t.Fatal("expected privileged=false by default")
+	}
+}
+
+func TestBuildDaemonSet_PrivilegedEnabled(t *testing.T) {
+	engine := minimalEngine()
+	engine.Spec.Privileged = ptr(true)
+
+	ds := BuildDaemonSet(engine)
+	c := ds.Spec.Template.Spec.Containers[0]
+
+	if c.SecurityContext == nil || c.SecurityContext.Privileged == nil || !*c.SecurityContext.Privileged {
+		t.Fatal("expected privileged=true when spec.privileged=true")
+	}
+}
+
+// hasEnvAll reports whether envs contains an env var named name set to the
+// literal "all" (the value the GPU passthrough vars are always set to).
+func hasEnvAll(envs []corev1.EnvVar, name string) bool {
+	for _, e := range envs {
+		if e.Name == name && e.Value == "all" {
+			return true
+		}
+	}
+	return false
+}
diff --git a/operator/internal/resources/service.go b/operator/internal/resources/service.go
new file mode 100644
index 0000000..2fbc3c5
--- /dev/null
+++ b/operator/internal/resources/service.go
@@ -0,0 +1,99 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	"fmt"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// BuildLookupService creates a ClusterIP Service with internalTrafficPolicy=Local
+// for node-local service discovery. vLLM pods connect to this service and kube-proxy
+// routes traffic only to the LMCache pod on the same node.
+func BuildLookupService(engine *lmcachev1alpha1.LMCacheEngine) *corev1.Service {
+	return buildLookupServiceCore(engine.Name, engine.Namespace, &engine.Spec)
+}
+
+// buildLookupServiceCore is the name/namespace/spec-keyed core shared by the
+// LMCacheEngine and CacheBlendEngine lookup-Service builders. The node-local
+// internalTrafficPolicy=Local routing guarantee is owned here so it cannot drift.
+func buildLookupServiceCore(name, namespace string, spec *lmcachev1alpha1.LMCacheEngineSpec) *corev1.Service {
+	serverPort := derefInt32(getServerPort(spec), 5555)
+	httpPort := getHTTPPort(spec)
+	localPolicy := corev1.ServiceInternalTrafficPolicyLocal
+
+	return &corev1.Service{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      LookupServiceName(name),
+			Namespace: namespace,
+			Labels:    StandardLabels(name),
+		},
+		Spec: corev1.ServiceSpec{
+			Selector:              SelectorLabels(name),
+			InternalTrafficPolicy: &localPolicy,
+			Ports: []corev1.ServicePort{
+				{
+					Name:     serverPortName,
+					Port:     serverPort,
+					Protocol: corev1.ProtocolTCP,
+				},
+				{
+					Name:     "http",
+					Port:     httpPort,
+					Protocol: corev1.ProtocolTCP,
+				},
+			},
+		},
+	}
+}
+
+// BuildMetricsService creates a headless Service for Prometheus scraping.
+func BuildMetricsService(engine *lmcachev1alpha1.LMCacheEngine) *corev1.Service {
+	return buildMetricsServiceCore(engine.Name, engine.Namespace, &engine.Spec)
+}
+
+// buildMetricsServiceCore is the name/namespace/spec-keyed core shared by the
+// LMCacheEngine and CacheBlendEngine metrics-Service builders.
+func buildMetricsServiceCore(name, namespace string, spec *lmcachev1alpha1.LMCacheEngineSpec) *corev1.Service {
+	promPort := int32(9090)
+	if spec.Prometheus != nil {
+		promPort = derefInt32(spec.Prometheus.Port, 9090)
+	}
+
+	return &corev1.Service{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      fmt.Sprintf("%s-metrics", name),
+			Namespace: namespace,
+			Labels:    StandardLabels(name),
+		},
+		Spec: corev1.ServiceSpec{
+			ClusterIP: corev1.ClusterIPNone,
+			Selector:  SelectorLabels(name),
+			Ports: []corev1.ServicePort{
+				{
+					Name:     "metrics",
+					Port:     promPort,
+					Protocol: corev1.ProtocolTCP,
+				},
+			},
+		},
+	}
+}
diff --git a/operator/internal/resources/servicemonitor.go b/operator/internal/resources/servicemonitor.go
new file mode 100644
index 0000000..898af2e
--- /dev/null
+++ b/operator/internal/resources/servicemonitor.go
@@ -0,0 +1,68 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package resources
+
+import (
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// ServiceMonitorEnabled returns true if the ServiceMonitor should be created.
+func ServiceMonitorEnabled(spec *lmcachev1alpha1.LMCacheEngineSpec) bool {
+	if spec.Prometheus == nil || spec.Prometheus.ServiceMonitor == nil {
+		return false
+	}
+	return derefBool(spec.Prometheus.ServiceMonitor.Enabled, false)
+}
+
+// BuildServiceMonitor creates a ServiceMonitor CR for Prometheus Operator integration.
+func BuildServiceMonitor(engine *lmcachev1alpha1.LMCacheEngine) *monitoringv1.ServiceMonitor {
+	return buildServiceMonitorCore(engine.Name, engine.Namespace, &engine.Spec)
+}
+
+// buildServiceMonitorCore is the name/namespace/spec-keyed core shared by the
+// LMCacheEngine and CacheBlendEngine ServiceMonitor builders. Callers must
+// ensure ServiceMonitorEnabled(spec) is true (spec.Prometheus.ServiceMonitor is
+// dereferenced here).
+func buildServiceMonitorCore(name, namespace string, spec *lmcachev1alpha1.LMCacheEngineSpec) *monitoringv1.ServiceMonitor {
+	smSpec := spec.Prometheus.ServiceMonitor
+
+	interval := monitoringv1.Duration(derefString(smSpec.Interval, "30s"))
+
+	labels := MergeLabels(StandardLabels(name), smSpec.Labels)
+
+	return &monitoringv1.ServiceMonitor{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      name,
+			Namespace: namespace,
+			Labels:    labels,
+		},
+		Spec: monitoringv1.ServiceMonitorSpec{
+			Selector: metav1.LabelSelector{
+				MatchLabels: SelectorLabels(name),
+			},
+			Endpoints: []monitoringv1.Endpoint{
+				{
+					Port:     "metrics",
+					Interval: interval,
+				},
+			},
+		},
+	}
+}
diff --git a/operator/internal/webhook/cacheblend_inject_builders.go b/operator/internal/webhook/cacheblend_inject_builders.go
new file mode 100644
index 0000000..02e5f6f
--- /dev/null
+++ b/operator/internal/webhook/cacheblend_inject_builders.go
@@ -0,0 +1,250 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package webhook implements the CacheBlend mutating admission webhook that
+// injects the lmcache-cacheblend vLLM plugin into opted-in vLLM pods (see
+// design §7). This file holds the pure, side-effect-free mutation builders; the
+// admission handler that orchestrates them lives in pod_injector.go.
+package webhook
+
+import (
+	corev1 "k8s.io/api/core/v1"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+const (
+	// cbPluginVolumeName is the name of the shared emptyDir volume that the init
+	// container stages the lmcache-cacheblend plugin tree into and the vLLM
+	// container reads it back from (design §7 M1/M2/M3).
+	cbPluginVolumeName = "cb-plugin"
+
+	// cbPluginMountPath is the in-container path the cb-plugin volume mounts at,
+	// in both the init container (read-write, the cp target) and the vLLM
+	// container (read-only). It is also the vLLM container's prepended PYTHONPATH
+	// entry, so the two stay in lockstep (design §9.5).
+	cbPluginMountPath = "/cb-plugin"
+
+	// cbSharedDirEnvName is the env var the payload init container reads to learn
+	// where to copy the plugin tree (cacheblend-plugin docker/Dockerfile:22-29).
+	cbSharedDirEnvName = "SHARED_DIR"
+
+	// cbInitContainerName is the name of the injected payload init container.
+	cbInitContainerName = "cb-plugin-stage"
+)
+
+// cbStaging is the CacheBlend injector's payload-staging parameters, consumed by
+// the shared payloadStaging builders. The vLLM container's prepended PYTHONPATH
+// equals cbPluginMountPath so the staged plugin is discoverable (design §7 M4).
+var cbStaging = payloadStaging{
+	volumeName:   cbPluginVolumeName,
+	mountPath:    cbPluginMountPath,
+	initName:     cbInitContainerName,
+	sharedDirEnv: cbSharedDirEnvName,
+}
+
+// CacheBlend-required vLLM flag names and fixed values (design §7 M5). The
+// CacheBlend matcher and connector hard-require these; several fail loudly,
+// --no-async-scheduling fails silently (MoE garble).
+const (
+	cbFlagAttentionBackend = "--attention-backend"
+	cbValAttentionBackend  = "CUSTOM"
+
+	cbFlagKVTransferConfig = "--kv-transfer-config"
+
+	cbFlagNoChunkedPrefill = "--no-enable-chunked-prefill"
+
+	cbFlagBlockSize = "--block-size"
+	cbValBlockSize  = "64"
+
+	cbFlagPipelineParallelSize = "--pipeline-parallel-size"
+	cbValPipelineParallelSize  = "1"
+
+	cbFlagNoAsyncScheduling = "--no-async-scheduling"
+
+	// cudagraph mode flags. Eager (default) forces --enforce-eager; full
+	// decode-only enables decode graphs while never using full graphs in prefill
+	// (design §4, §7 M5).
+	cbFlagEnforceEager      = "--enforce-eager"
+	cbFlagCompilationConfig = "--compilation-config"
+)
+
+// BuildCBPluginVolume returns the shared emptyDir volume the init container
+// stages the plugin into and the vLLM container reads it back from (M1).
+func BuildCBPluginVolume() corev1.Volume {
+	return cbStaging.volume()
+}
+
+// BuildCBInitContainer returns the payload init container (M2). It mounts the
+// cb-plugin volume read-write at /cb-plugin, sets SHARED_DIR=/cb-plugin, and runs
+// the payload image's own ENTRYPOINT (busybox `cp -a`) with no command override.
+//
+// Parameters:
+//   - payloadImage: the (possibly private) image that ships the unpacked
+//     lmcache_cacheblend plugin tree under /payload.
+//   - pullPolicy: the image pull policy for that image.
+func BuildCBInitContainer(payloadImage string, pullPolicy corev1.PullPolicy) corev1.Container {
+	return cbStaging.initContainer(payloadImage, pullPolicy)
+}
+
+// BuildCBVolumeMount returns the read-only mount of the cb-plugin volume added to
+// the target vLLM container (M3).
+func BuildCBVolumeMount() corev1.VolumeMount {
+	return cbStaging.volumeMount()
+}
+
+// BuildCBPodEnv returns the env list for the target vLLM container with
+// PYTHONPATH set to (or prepended with) /cb-plugin (M4). It is set on the
+// container, never the pod, so every spawned worker inherits it; it never sets
+// VLLM_PLUGINS (design §9.8). An existing PYTHONPATH is prepended, not replaced,
+// so /cb-plugin:<existing> keeps the plugin discoverable without dropping the
+// user's path entries.
+//
+// Parameters:
+//   - existing: the target container's current env list (may be nil).
+//
+// Returns a new env list; the input is not mutated.
+func BuildCBPodEnv(existing []corev1.EnvVar) []corev1.EnvVar {
+	return cbStaging.prependPythonPath(existing)
+}
+
+// cudagraphArgs returns the cudagraph-mode flag set for the given mode. "eager"
+// (and any unrecognized value) maps to --enforce-eager; "full_decode_only"
+// enables decode-only CUDA graphs without ever using full graphs in prefill;
+// "piecewise" enables piecewise capture (no --enforce-eager).
+func cudagraphArgs(cudagraph string) []string {
+	switch cudagraph {
+	case lmcachev1alpha1.CudagraphPiecewise:
+		// Piecewise graph capture: do not force eager. vLLM's default
+		// compilation already does piecewise capture, so no extra flag is
+		// emitted; we simply omit --enforce-eager.
+		return nil
+	case lmcachev1alpha1.CudagraphFullDecodeOnly:
+		// Decode-only full graphs: enable cudagraph for decode but never full
+		// graphs in prefill (CacheBlend re-RoPE happens in prefill).
+		return []string{cbFlagCompilationConfig, `{"cudagraph_mode":"FULL_DECODE_ONLY"}`}
+	default:
+		// eager (default): force --enforce-eager.
+		return []string{cbFlagEnforceEager}
+	}
+}
+
+// BuildCBArgs returns the target vLLM container's args with the CacheBlend
+// required flag set applied (M5). Each flag is appended-or-replaced (design §9.1):
+// a user-supplied --flag value (in either "--flag v" or "--flag=v" form) is
+// overwritten in place rather than duplicated, and a flag the user never set is
+// appended.
+//
+// The --kv-transfer-config flag is included here only when the caller passes a
+// non-empty kvTransferConfigJSON; the handler skips it (and stamps a reason)
+// when the user already supplied their own --kv-transfer-config (design §9.2),
+// in which case it passes "" so this builder leaves the user's value untouched.
+//
+// Parameters:
+//   - existingArgs: the target container's current args (may be nil).
+//   - kvTransferConfigJSON: the CBKVConnector JSON from the engine's connection
+//     ConfigMap, or "" to skip injecting/replacing --kv-transfer-config.
+//   - cudagraph: the cudagraph mode (eager|piecewise|full_decode_only).
+//
+// Returns a new args slice; the input is not mutated.
+func BuildCBArgs(existingArgs []string, kvTransferConfigJSON, cudagraph string) []string {
+	args := make([]string, len(existingArgs))
+	copy(args, existingArgs)
+
+	args = applyArg(args, cbFlagAttentionBackend, cbValAttentionBackend)
+	if kvTransferConfigJSON != "" {
+		args = applyArg(args, cbFlagKVTransferConfig, kvTransferConfigJSON)
+	}
+	args = applyBareFlag(args, cbFlagNoChunkedPrefill)
+	args = applyArg(args, cbFlagBlockSize, cbValBlockSize)
+	args = applyArg(args, cbFlagPipelineParallelSize, cbValPipelineParallelSize)
+	args = applyBareFlag(args, cbFlagNoAsyncScheduling)
+
+	// cudagraphArgs returns either a single bare flag (--enforce-eager), a
+	// [flag, value] pair (full_decode_only), or nil (piecewise). Apply with
+	// append-or-replace semantics so a user's pre-existing value is overwritten.
+	switch cg := cudagraphArgs(cudagraph); len(cg) {
+	case 1:
+		args = applyBareFlag(args, cg[0])
+	case 2:
+		args = applyArg(args, cg[0], cg[1])
+	}
+
+	return args
+}
+
+// applyArg appends-or-replaces a "--flag value" pair in args (design §9.1). It
+// recognizes both the two-token form ["--flag", "value"] and the single-token
+// form ["--flag=value"]; a match is overwritten in place (preserving the form),
+// otherwise the two-token pair is appended. Returns a new slice.
+func applyArg(args []string, flag, value string) []string {
+	eqPrefix := flag + "="
+	for i := range len(args) {
+		if args[i] == flag {
+			// Two-token form: overwrite the following value token if present,
+			// else append the value after the flag.
+			if i+1 < len(args) {
+				args[i+1] = value
+				return args
+			}
+			return append(args, value)
+		}
+		if len(args[i]) >= len(eqPrefix) && args[i][:len(eqPrefix)] == eqPrefix {
+			// Single-token --flag=value form: overwrite in place.
+			args[i] = eqPrefix + value
+			return args
+		}
+	}
+	return append(args, flag, value)
+}
+
+// applyBareFlag appends a valueless flag (e.g. --no-enable-chunked-prefill) if it
+// is not already present in either bare or --flag=... form. Returns a new slice.
+func applyBareFlag(args []string, flag string) []string {
+	eqPrefix := flag + "="
+	for _, a := range args {
+		if a == flag {
+			return args
+		}
+		if len(a) >= len(eqPrefix) && a[:len(eqPrefix)] == eqPrefix {
+			return args
+		}
+	}
+	return append(args, flag)
+}
+
+// MergeImagePullSecrets returns existing with injected appended, deduplicated by
+// secret name (M7). A secret already present in existing is not duplicated, and
+// the order of existing is preserved with new secrets appended in injected order.
+// Returns a new slice; the inputs are not mutated.
+func MergeImagePullSecrets(
+	existing, injected []corev1.LocalObjectReference,
+) []corev1.LocalObjectReference {
+	seen := make(map[string]struct{}, len(existing))
+	out := make([]corev1.LocalObjectReference, 0, len(existing)+len(injected))
+	for _, ref := range existing {
+		out = append(out, ref)
+		seen[ref.Name] = struct{}{}
+	}
+	for _, ref := range injected {
+		if _, ok := seen[ref.Name]; ok {
+			continue
+		}
+		seen[ref.Name] = struct{}{}
+		out = append(out, ref)
+	}
+	return out
+}
diff --git a/operator/internal/webhook/cacheblend_pod_injector.go b/operator/internal/webhook/cacheblend_pod_injector.go
new file mode 100644
index 0000000..eabb524
--- /dev/null
+++ b/operator/internal/webhook/cacheblend_pod_injector.go
@@ -0,0 +1,297 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	"context"
+	"net/http"
+	"strings"
+
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// CacheBlend annotation keys the webhook reads and stamps (design §8).
+const (
+	// AnnotationEngine binds a pod to a CacheBlendEngine. Its presence is the
+	// opt-in signal; its value is the engine name, optionally namespace-qualified
+	// as "<namespace>/<name>" to bind a shared engine in ANOTHER namespace. A
+	// bare name resolves in the pod's own namespace.
+	AnnotationEngine = "lmcache.ai/cacheblend-engine"
+
+	// AnnotationContainer optionally names the target vLLM container; empty or
+	// absent selects the first container.
+	AnnotationContainer = "lmcache.ai/cacheblend-container"
+
+	// AnnotationImagePullSecrets optionally overrides the engine's
+	// injection.imagePullSecrets with a comma-separated list of Secret names
+	// appended to the pod's spec.imagePullSecrets for the private payload image.
+	AnnotationImagePullSecrets = "lmcache.ai/cacheblend-image-pull-secrets"
+
+	// AnnotationInjected is the idempotency guard stamped after a successful
+	// injection; a re-admitted pod carrying it is allowed unchanged.
+	AnnotationInjected = "lmcache.ai/cacheblend-injected"
+
+	// AnnotationSkipReason records why injection was skipped (fail-open).
+	AnnotationSkipReason = "lmcache.ai/cacheblend-skip-reason"
+)
+
+// CacheBlendLabelInject is the opt-in label the MutatingWebhookConfiguration's
+// objectSelector matches (mutating_webhook_selectors_patch.yaml). It gates which
+// pods reach the webhook; the handler itself gates on AnnotationEngine.
+const CacheBlendLabelInject = "lmcache.ai/cacheblend-inject"
+
+// SkipReasonPayloadImageUnset is stamped when the engine's
+// injection.payloadImage resolves to an empty reference (no repository). The
+// webhook skips rather than inject an init container with an empty image, which
+// the API server would reject. CRD validation normally prevents this. This skip
+// reason is CacheBlend-only (the shared reasons live in pod_inject_common.go).
+const SkipReasonPayloadImageUnset = "payload-image-unset"
+
+// cacheBlendKeys is the CacheBlend injector's annotation key set, consumed by
+// the shared gate / skip / stamp helpers.
+var cacheBlendKeys = injectionKeys{
+	engine:     AnnotationEngine,
+	container:  AnnotationContainer,
+	injected:   AnnotationInjected,
+	skipReason: AnnotationSkipReason,
+}
+
+// +kubebuilder:webhook:path=/mutate--v1-pod,mutating=true,failurePolicy=ignore,sideEffects=None,groups="",resources=pods,verbs=create,versions=v1,name=mcacheblendpod.lmcache.ai,admissionReviewVersions=v1,reinvocationPolicy=Never
+
+// CacheBlendPodInjector is the mutating admission handler that injects the
+// lmcache-cacheblend vLLM plugin into opted-in pods (design §7). It is gated by
+// the CacheBlendEngine CR: it mutates a pod only when the pod's
+// lmcache.ai/cacheblend-engine annotation names an engine whose connection
+// ConfigMap exists. It fails open (failurePolicy: Ignore) and is idempotent.
+type CacheBlendPodInjector struct {
+	// Client reads the named CacheBlendEngine and its connection ConfigMap. It
+	// uses the shared manager ServiceAccount, whose RBAC already grants
+	// cacheblendengines get and configmaps get (design §7 RBAC note).
+	Client client.Client
+
+	// Decoder decodes the admission request's raw pod object.
+	Decoder admission.Decoder
+}
+
+// Handle implements admission.Handler. It applies mutations M0–M7 to an opted-in
+// pod whose named CacheBlendEngine connection ConfigMap exists, then returns a
+// JSON patch. It short-circuits to an unchanged Allowed response for non-opted-in
+// or already-injected pods, and stamps a skip-reason annotation (still Allowed,
+// fail-open) when it declines to mutate (engine missing, command override,
+// payload image unset, target container missing, or user-supplied
+// --kv-transfer-config).
+func (p *CacheBlendPodInjector) Handle(ctx context.Context, req admission.Request) admission.Response {
+	log := ctrl.LoggerFrom(ctx)
+
+	pod, engineRef, podNamespace, resp, handled := cacheBlendKeys.gate(p.Decoder, req)
+	if handled {
+		return resp
+	}
+
+	// Resolve an optional "<namespace>/<name>" engine reference. A bare name
+	// resolves in the pod's namespace (the same-namespace default); a namespaced
+	// ref targets a shared engine in another namespace.
+	engineNamespace, engineName := parseEngineRef(engineRef, podNamespace)
+
+	// (3a) Resolve the engine CR (in the engine's namespace) for its injection
+	// defaults.
+	engine := &lmcachev1alpha1.CacheBlendEngine{}
+	if err := p.Client.Get(ctx, types.NamespacedName{Name: engineName, Namespace: engineNamespace}, engine); err != nil {
+		if apierrors.IsNotFound(err) {
+			log.Info("Skipped CacheBlend injection: engine not found",
+				"engine", engineName, "namespace", engineNamespace)
+			return cacheBlendKeys.skip(req, pod, SkipReasonEngineNotFound)
+		}
+		return admission.Errored(http.StatusInternalServerError, err)
+	}
+	engine.SetDefaults()
+
+	// (3b/6/4) Read the connection ConfigMap (in the engine's namespace), resolve
+	// the target container, and apply the command-override gate (shared with the
+	// LMCache injector).
+	kvTransferConfigJSON, containerIdx, resp, ok := prepareInjection(
+		ctx, p.Client, req, pod, cacheBlendKeys, engineName, engineNamespace,
+		engine.Spec.Injection.TargetContainer)
+	if !ok {
+		return resp
+	}
+	target := &pod.Spec.Containers[containerIdx]
+
+	// (5) user --kv-transfer-config gate: skip that flag (do not clobber the
+	// user's structured JSON) but still apply the rest of the mutation.
+	userHasKVTransferConfig := argsHasFlag(target.Args, cbFlagKVTransferConfig)
+
+	// --- Apply mutations M0–M7 ---
+
+	// M0: pod hostIPC for CUDA IPC with the node-local engine.
+	pod.Spec.HostIPC = true
+
+	// M1: shared emptyDir volume.
+	pod.Spec.Volumes = appendVolumeIfAbsent(pod.Spec.Volumes, BuildCBPluginVolume())
+
+	// M2: payload init container (payloadImage is an ImageSpec: repo/tag/policy).
+	// Fail open if the image resolves to empty (no repository) rather than inject
+	// an init container with an empty image, which the API server would reject.
+	payloadRef, payloadPullPolicy := resolvePayloadImage(engine.Spec.Injection.PayloadImage)
+	if payloadRef == "" {
+		log.Info("Skipped CacheBlend injection: payload image repository is unset",
+			"engine", engineName)
+		return cacheBlendKeys.skip(req, pod, SkipReasonPayloadImageUnset)
+	}
+	pod.Spec.InitContainers = appendInitContainerIfAbsent(pod.Spec.InitContainers,
+		BuildCBInitContainer(payloadRef, payloadPullPolicy))
+
+	// M3: read-only mount on the target container.
+	target.VolumeMounts = appendVolumeMountIfAbsent(target.VolumeMounts, BuildCBVolumeMount())
+
+	// M4: PYTHONPATH on the target container.
+	target.Env = BuildCBPodEnv(target.Env)
+
+	// M5: required vLLM args. Pass "" for the kv-transfer-config JSON when the
+	// user already supplies one so BuildCBArgs leaves their value untouched.
+	kvForArgs := kvTransferConfigJSON
+	if userHasKVTransferConfig {
+		kvForArgs = ""
+	}
+	cudagraph := deref(engine.Spec.Injection.Cudagraph)
+	target.Args = BuildCBArgs(target.Args, kvForArgs, cudagraph)
+
+	// M7: append injection pull secrets (annotation override wins) to the pod's
+	// imagePullSecrets, deduped (private payload image).
+	injectedSecrets := resolveInjectedPullSecrets(engine.Spec.Injection.ImagePullSecrets,
+		pod.Annotations[AnnotationImagePullSecrets])
+	pod.Spec.ImagePullSecrets = MergeImagePullSecrets(pod.Spec.ImagePullSecrets, injectedSecrets)
+
+	// M6: stamp the idempotency guard (+ skip reason if --kv-transfer-config was
+	// user-supplied) and return the patch.
+	log.Info("Injected CacheBlend plugin", "engine", engineName, "container", target.Name)
+	return cacheBlendKeys.stampInjected(req, pod, userHasKVTransferConfig)
+}
+
+// resolveInjectedPullSecrets returns the pull-secret references to inject: the
+// per-pod annotation override (a comma-separated list of Secret names) when
+// present, otherwise the engine's injection.imagePullSecrets.
+//
+// Parameters:
+//   - specSecrets: the engine's injection.imagePullSecrets.
+//   - annotationCSV: the cacheblend-image-pull-secrets annotation value.
+func resolveInjectedPullSecrets(
+	specSecrets []corev1.LocalObjectReference,
+	annotationCSV string,
+) []corev1.LocalObjectReference {
+	csv := strings.TrimSpace(annotationCSV)
+	if csv == "" {
+		return specSecrets
+	}
+	out := make([]corev1.LocalObjectReference, 0)
+	for part := range strings.SplitSeq(csv, ",") {
+		name := strings.TrimSpace(part)
+		if name == "" {
+			continue
+		}
+		out = append(out, corev1.LocalObjectReference{Name: name})
+	}
+	return out
+}
+
+// parseEngineRef splits an engine reference of the form "<namespace>/<name>"
+// into its parts. A bare "<name>" (no slash) resolves in defaultNS — the pod's
+// namespace — preserving the same-namespace default. A blank namespace (e.g.
+// "/name") also falls back to defaultNS. Returns (namespace, name).
+func parseEngineRef(ref, defaultNS string) (namespace, name string) {
+	namespace, name = defaultNS, strings.TrimSpace(ref)
+	if ns, n, found := strings.Cut(name, "/"); found {
+		namespace, name = strings.TrimSpace(ns), strings.TrimSpace(n)
+	}
+	if namespace == "" {
+		namespace = defaultNS
+	}
+	return namespace, name
+}
+
+// appendVolumeIfAbsent appends v to volumes unless a volume of the same name is
+// already present (idempotency within a single Handle call). Returns the slice.
+func appendVolumeIfAbsent(volumes []corev1.Volume, v corev1.Volume) []corev1.Volume {
+	for i := range volumes {
+		if volumes[i].Name == v.Name {
+			return volumes
+		}
+	}
+	return append(volumes, v)
+}
+
+// appendInitContainerIfAbsent appends c to initContainers unless one of the same
+// name is already present. Returns the slice.
+func appendInitContainerIfAbsent(
+	initContainers []corev1.Container,
+	c corev1.Container,
+) []corev1.Container {
+	for i := range initContainers {
+		if initContainers[i].Name == c.Name {
+			return initContainers
+		}
+	}
+	return append(initContainers, c)
+}
+
+// appendVolumeMountIfAbsent appends m to mounts unless one of the same name is
+// already present. Returns the slice.
+func appendVolumeMountIfAbsent(
+	mounts []corev1.VolumeMount,
+	m corev1.VolumeMount,
+) []corev1.VolumeMount {
+	for i := range mounts {
+		if mounts[i].Name == m.Name {
+			return mounts
+		}
+	}
+	return append(mounts, m)
+}
+
+// deref returns the value pointed to by s, or "" if s is nil.
+func deref(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}
+
+// resolvePayloadImage builds the "<repository>:<tag>" reference and pull policy
+// for the payload init container from the engine's injection.payloadImage. Tag
+// and pull policy fall back to "latest" / IfNotPresent when unset; repository is
+// taken as-is (it has no sensible cluster-wide default — see InjectionSpec docs).
+func resolvePayloadImage(img *lmcachev1alpha1.ImageSpec) (string, corev1.PullPolicy) {
+	if img == nil || deref(img.Repository) == "" {
+		return "", corev1.PullIfNotPresent
+	}
+	tag := deref(img.Tag)
+	if tag == "" {
+		tag = "latest"
+	}
+	policy := corev1.PullPolicy(deref(img.PullPolicy))
+	if policy == "" {
+		policy = corev1.PullIfNotPresent
+	}
+	return deref(img.Repository) + ":" + tag, policy
+}
diff --git a/operator/internal/webhook/cacheblend_pod_injector_envtest_test.go b/operator/internal/webhook/cacheblend_pod_injector_envtest_test.go
new file mode 100644
index 0000000..9a9dbf2
--- /dev/null
+++ b/operator/internal/webhook/cacheblend_pod_injector_envtest_test.go
@@ -0,0 +1,178 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+// These specs exercise the FULL admission pipeline: a pod CREATE goes to the
+// envtest API server, which calls the registered CacheBlendPodInjector webhook over TLS,
+// and we read the persisted (mutated) pod back. This validates the wiring the
+// fake-client unit tests cannot: the generated webhook manifest path, the
+// decoder, and PatchResponseFromRaw round-tripping through the API server.
+var _ = Describe("CacheBlendPodInjector webhook (envtest)", Ordered, func() {
+	BeforeAll(func() {
+		By("creating the target namespace")
+		ns := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: testNamespace}}
+		Expect(client.IgnoreAlreadyExists(k8sClient.Create(envtestCtx, ns))).To(Succeed())
+
+		By("creating the CacheBlendEngine and its connection ConfigMap")
+		engine := newTestEngine(nil)
+		Expect(k8sClient.Create(envtestCtx, engine)).To(Succeed())
+		Expect(k8sClient.Create(envtestCtx, resources.BuildCBConnectionConfigMap(engine))).To(Succeed())
+	})
+
+	It("injects the plugin, flags, hostIPC, and private-image pull secret into an annotated pod", func() {
+		pod := vllmPod(func(p *corev1.Pod) {
+			p.Name = "vllm-injected"
+			if p.Labels == nil {
+				p.Labels = map[string]string{}
+			}
+			p.Labels["lmcache.ai/cacheblend-inject"] = valueTrue
+		})
+		Expect(k8sClient.Create(envtestCtx, pod)).To(Succeed())
+
+		got := &corev1.Pod{}
+		Expect(k8sClient.Get(envtestCtx,
+			types.NamespacedName{Name: "vllm-injected", Namespace: testNamespace}, got)).To(Succeed())
+
+		By("the idempotency annotation is stamped")
+		Expect(got.Annotations).To(HaveKeyWithValue(AnnotationInjected, valueTrue))
+
+		By("M0: hostIPC is set on the pod")
+		Expect(got.Spec.HostIPC).To(BeTrue())
+
+		By("M1/M2: the cb-plugin emptyDir volume and payload init container are present")
+		Expect(hasPluginVolume(got)).To(BeTrue())
+		Expect(got.Spec.InitContainers).NotTo(BeEmpty())
+		init := got.Spec.InitContainers[0]
+		Expect(init.Image).To(Equal("registry.example.com/lmcache/cacheblend-payload:pinned"))
+
+		By("M3/M4: the vLLM container has the readOnly mount and PYTHONPATH")
+		c := findContainer(got, "vllm")
+		Expect(c).NotTo(BeNil())
+		Expect(hasReadOnlyMount(c, "cb-plugin")).To(BeTrue())
+		Expect(envValue(c, "PYTHONPATH")).To(ContainSubstring("/cb-plugin"))
+
+		By("M5: every required vLLM flag is present, with the node-local CBKVConnector config")
+		// Form-agnostic: the handler may emit two-token (--flag value) or
+		// =-token (--flag=value) forms; argsHasFlagValue handles both.
+		Expect(argsHasFlagValue(c.Args, "--attention-backend", "CUSTOM")).To(BeTrue())
+		Expect(argsHasFlagValue(c.Args, "--block-size", "64")).To(BeTrue())
+		Expect(argsHasFlagValue(c.Args, "--pipeline-parallel-size", "1")).To(BeTrue())
+		Expect(c.Args).To(ContainElement("--no-enable-chunked-prefill"))
+		Expect(c.Args).To(ContainElement("--no-async-scheduling"))
+		kv := argsFlagValue(c.Args, "--kv-transfer-config")
+		Expect(kv).To(ContainSubstring("CBKVConnector"))
+		Expect(kv).To(ContainSubstring("tcp://" + testEngineName + "." + testNamespace + ".svc"))
+
+		By("M7: the private payload pull secret is appended to the pod")
+		Expect(pullSecretNames(got)).To(ContainElement("cb-payload-pull"))
+	})
+
+	It("leaves a pod without the engine annotation untouched", func() {
+		pod := vllmPod(func(p *corev1.Pod) {
+			p.Name = "vllm-no-annotation"
+			p.Annotations = nil
+		})
+		Expect(k8sClient.Create(envtestCtx, pod)).To(Succeed())
+
+		got := &corev1.Pod{}
+		Expect(k8sClient.Get(envtestCtx,
+			types.NamespacedName{Name: "vllm-no-annotation", Namespace: testNamespace}, got)).To(Succeed())
+
+		Expect(got.Annotations).NotTo(HaveKey(AnnotationInjected))
+		Expect(got.Spec.HostIPC).To(BeFalse())
+		Expect(hasPluginVolume(got)).To(BeFalse())
+		Expect(got.Spec.InitContainers).To(BeEmpty())
+	})
+
+	It("skips a pod whose target container overrides command, stamping a skip reason", func() {
+		pod := vllmPod(func(p *corev1.Pod) {
+			p.Name = "vllm-wrapped"
+			p.Spec.Containers[0].Command = []string{"/bin/sh", "-c", "exec vllm serve"}
+		})
+		Expect(k8sClient.Create(envtestCtx, pod)).To(Succeed())
+
+		got := &corev1.Pod{}
+		Expect(k8sClient.Get(envtestCtx,
+			types.NamespacedName{Name: "vllm-wrapped", Namespace: testNamespace}, got)).To(Succeed())
+
+		Expect(got.Annotations).To(HaveKeyWithValue(AnnotationSkipReason, SkipReasonCommandOverride))
+		Expect(got.Annotations).NotTo(HaveKey(AnnotationInjected))
+		Expect(hasPluginVolume(got)).To(BeFalse())
+	})
+
+	It("injects across namespaces via a namespace-qualified engine reference", func() {
+		const consumerNS = "cb-consumer"
+		By("creating the consumer namespace")
+		Expect(client.IgnoreAlreadyExists(k8sClient.Create(envtestCtx,
+			&corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: consumerNS}}))).To(Succeed())
+
+		// Pod in another namespace, namespace-qualified ref to the engine in
+		// testNamespace. Cross-namespace binds need no engine-side config: the
+		// webhook resolves the engine + connection ConfigMap from the engine's
+		// namespace and injects.
+		pod := vllmPod(func(p *corev1.Pod) {
+			p.Name = "vllm-xns"
+			p.Namespace = consumerNS
+			p.Annotations[AnnotationEngine] = testNamespace + "/" + testEngineName
+		})
+		Expect(k8sClient.Create(envtestCtx, pod)).To(Succeed())
+
+		got := &corev1.Pod{}
+		Expect(k8sClient.Get(envtestCtx,
+			types.NamespacedName{Name: "vllm-xns", Namespace: consumerNS}, got)).To(Succeed())
+
+		By("the pod is injected using the engine + ConfigMap from the engine's namespace")
+		Expect(got.Annotations).To(HaveKeyWithValue(AnnotationInjected, valueTrue))
+		Expect(got.Spec.HostIPC).To(BeTrue())
+		Expect(hasPluginVolume(got)).To(BeTrue())
+		Expect(got.Spec.InitContainers).NotTo(BeEmpty())
+		c := findContainer(got, "vllm")
+		Expect(c).NotTo(BeNil())
+		kv := argsFlagValue(c.Args, "--kv-transfer-config")
+		Expect(kv).To(ContainSubstring("tcp://" + testEngineName + "." + testNamespace + ".svc"))
+	})
+})
+
+func hasPluginVolume(pod *corev1.Pod) bool {
+	for _, v := range pod.Spec.Volumes {
+		if v.Name == "cb-plugin" {
+			return true
+		}
+	}
+	return false
+}
+
+func hasReadOnlyMount(c *corev1.Container, name string) bool {
+	for _, m := range c.VolumeMounts {
+		if m.Name == name && m.ReadOnly {
+			return true
+		}
+	}
+	return false
+}
diff --git a/operator/internal/webhook/cacheblend_pod_injector_test.go b/operator/internal/webhook/cacheblend_pod_injector_test.go
new file mode 100644
index 0000000..bd6538e
--- /dev/null
+++ b/operator/internal/webhook/cacheblend_pod_injector_test.go
@@ -0,0 +1,575 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	jsonpatch "github.com/evanphx/json-patch/v5"
+	admissionv1 "k8s.io/api/admission/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
+	"sigs.k8s.io/controller-runtime/pkg/client/fake"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+const (
+	testEngineName = "cb"
+	testNamespace  = "vllm-ns"
+	testPodName    = "vllm-pod"
+	testSvcHost    = "tcp://cb.vllm-ns.svc.cluster.local"
+)
+
+// newTestScheme returns a scheme with clientgo + the lmcache v1alpha1 types.
+func newTestScheme() *runtime.Scheme {
+	s := runtime.NewScheme()
+	Expect(clientgoscheme.AddToScheme(s)).To(Succeed())
+	Expect(lmcachev1alpha1.AddToScheme(s)).To(Succeed())
+	return s
+}
+
+// newTestEngine returns a defaulted CacheBlendEngine with the given injection
+// overrides applied via mutate (nil = pure defaults).
+func newTestEngine(mutate func(*lmcachev1alpha1.CacheBlendEngine)) *lmcachev1alpha1.CacheBlendEngine {
+	payloadRepo := "registry.example.com/lmcache/cacheblend-payload"
+	payloadTag := "pinned"
+	engine := &lmcachev1alpha1.CacheBlendEngine{
+		ObjectMeta: metav1.ObjectMeta{Name: testEngineName, Namespace: testNamespace},
+		Spec: lmcachev1alpha1.CacheBlendEngineSpec{
+			L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10},
+			Injection: &lmcachev1alpha1.InjectionSpec{
+				PayloadImage: &lmcachev1alpha1.ImageSpec{Repository: &payloadRepo, Tag: &payloadTag},
+				ImagePullSecrets: []corev1.LocalObjectReference{
+					{Name: "cb-payload-pull"},
+				},
+			},
+		},
+	}
+	engine.SetDefaults()
+	if mutate != nil {
+		mutate(engine)
+	}
+	return engine
+}
+
+// newPodInjector returns a CacheBlendPodInjector backed by a fake client seeded
+// with the given objects, plus the engine's connection ConfigMap when seedConn
+// is true.
+func newPodInjector(
+	engine *lmcachev1alpha1.CacheBlendEngine,
+	seedConn bool,
+) *CacheBlendPodInjector {
+	scheme := newTestScheme()
+	builder := fake.NewClientBuilder().WithScheme(scheme)
+	objs := []runtime.Object{engine}
+	if seedConn {
+		objs = append(objs, resources.BuildCBConnectionConfigMap(engine))
+	}
+	builder = builder.WithRuntimeObjects(objs...)
+	return &CacheBlendPodInjector{
+		Client:  builder.Build(),
+		Decoder: admission.NewDecoder(scheme),
+	}
+}
+
+// makeRequest builds a CREATE admission.Request carrying the given pod as raw
+// JSON in req.Object.
+func makeRequest(pod *corev1.Pod) admission.Request {
+	pod.TypeMeta = metav1.TypeMeta{APIVersion: "v1", Kind: "Pod"}
+	if pod.Namespace == "" {
+		pod.Namespace = testNamespace
+	}
+	raw, err := json.Marshal(pod)
+	Expect(err).NotTo(HaveOccurred())
+	return admission.Request{
+		AdmissionRequest: admissionv1.AdmissionRequest{
+			Operation: admissionv1.Create,
+			Namespace: pod.Namespace,
+			Object:    runtime.RawExtension{Raw: raw},
+		},
+	}
+}
+
+// applyResponse applies the response's JSON patches to the original pod JSON and
+// returns the mutated pod. It asserts the response is Allowed.
+func applyResponse(original *corev1.Pod, resp admission.Response) *corev1.Pod {
+	Expect(resp.Allowed).To(BeTrue(), "expected the response to be Allowed")
+
+	origRaw, err := json.Marshal(original)
+	Expect(err).NotTo(HaveOccurred())
+
+	if len(resp.Patches) == 0 {
+		out := &corev1.Pod{}
+		Expect(json.Unmarshal(origRaw, out)).To(Succeed())
+		return out
+	}
+
+	patchRaw, err := json.Marshal(resp.Patches)
+	Expect(err).NotTo(HaveOccurred())
+	patch, err := jsonpatch.DecodePatch(patchRaw)
+	Expect(err).NotTo(HaveOccurred())
+	mutatedRaw, err := patch.Apply(origRaw)
+	Expect(err).NotTo(HaveOccurred())
+
+	out := &corev1.Pod{}
+	Expect(json.Unmarshal(mutatedRaw, out)).To(Succeed())
+	return out
+}
+
+// vllmPod returns a minimal args-only vLLM pod (no command override) bound to
+// the test engine via annotation. mutate may further customize it.
+func vllmPod(mutate func(*corev1.Pod)) *corev1.Pod {
+	pod := &corev1.Pod{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      testPodName,
+			Namespace: testNamespace,
+			Annotations: map[string]string{
+				AnnotationEngine: testEngineName,
+			},
+		},
+		Spec: corev1.PodSpec{
+			Containers: []corev1.Container{
+				{
+					Name:  "vllm",
+					Image: "vllm/vllm-openai:latest",
+					Args:  []string{"--model", "Qwen/Qwen2.5-0.5B"},
+				},
+			},
+		},
+	}
+	if mutate != nil {
+		mutate(pod)
+	}
+	return pod
+}
+
+// findContainer returns the named container from the pod, or nil.
+func findContainer(pod *corev1.Pod, name string) *corev1.Container {
+	for i := range pod.Spec.Containers {
+		if pod.Spec.Containers[i].Name == name {
+			return &pod.Spec.Containers[i]
+		}
+	}
+	return nil
+}
+
+// envValue returns the value of the named env var on the container, or "".
+func envValue(c *corev1.Container, name string) string {
+	for _, e := range c.Env {
+		if e.Name == name {
+			return e.Value
+		}
+	}
+	return ""
+}
+
+// pullSecretNames returns the names in the pod's imagePullSecrets.
+func pullSecretNames(pod *corev1.Pod) []string {
+	out := make([]string, 0, len(pod.Spec.ImagePullSecrets))
+	for _, s := range pod.Spec.ImagePullSecrets {
+		out = append(out, s.Name)
+	}
+	return out
+}
+
+var _ = Describe("CacheBlendPodInjector", func() {
+	ctx := context.Background()
+
+	Describe("full M0–M7 injection", func() {
+		It("injects all required mutations for an opted-in pod", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			By("M0: hostIPC")
+			Expect(out.Spec.HostIPC).To(BeTrue())
+
+			By("M1: cb-plugin emptyDir volume")
+			var vol *corev1.Volume
+			for i := range out.Spec.Volumes {
+				if out.Spec.Volumes[i].Name == cbPluginVolumeName {
+					vol = &out.Spec.Volumes[i]
+				}
+			}
+			Expect(vol).NotTo(BeNil())
+			Expect(vol.EmptyDir).NotTo(BeNil())
+
+			By("M2: payload init container with image + pull policy + SHARED_DIR")
+			Expect(out.Spec.InitContainers).To(HaveLen(1))
+			init := out.Spec.InitContainers[0]
+			Expect(init.Image).To(Equal("registry.example.com/lmcache/cacheblend-payload:pinned"))
+			Expect(init.ImagePullPolicy).To(Equal(corev1.PullIfNotPresent))
+			Expect(init.Command).To(BeEmpty())
+			Expect(envValue(&init, cbSharedDirEnvName)).To(Equal(cbPluginMountPath))
+			Expect(init.VolumeMounts).To(HaveLen(1))
+			Expect(init.VolumeMounts[0].Name).To(Equal(cbPluginVolumeName))
+			Expect(init.VolumeMounts[0].MountPath).To(Equal(cbPluginMountPath))
+			Expect(init.VolumeMounts[0].ReadOnly).To(BeFalse())
+
+			c := findContainer(out, "vllm")
+			Expect(c).NotTo(BeNil())
+
+			By("M3: read-only mount on the target container")
+			var mount *corev1.VolumeMount
+			for i := range c.VolumeMounts {
+				if c.VolumeMounts[i].Name == cbPluginVolumeName {
+					mount = &c.VolumeMounts[i]
+				}
+			}
+			Expect(mount).NotTo(BeNil())
+			Expect(mount.ReadOnly).To(BeTrue())
+			Expect(mount.MountPath).To(Equal(cbPluginMountPath))
+
+			By("M4: PYTHONPATH on the container")
+			Expect(envValue(c, pythonPathEnvName)).To(Equal(cbPluginMountPath))
+
+			By("M5: required vLLM args asserted individually")
+			Expect(argsHasFlagValue(c.Args, cbFlagAttentionBackend, cbValAttentionBackend)).To(BeTrue(),
+				"--attention-backend=CUSTOM")
+			Expect(argsHasFlag(c.Args, cbFlagNoChunkedPrefill)).To(BeTrue(),
+				"--no-enable-chunked-prefill")
+			Expect(argsHasFlagValue(c.Args, cbFlagBlockSize, cbValBlockSize)).To(BeTrue(),
+				"--block-size=64")
+			Expect(argsHasFlagValue(c.Args, cbFlagPipelineParallelSize, cbValPipelineParallelSize)).To(BeTrue(),
+				"--pipeline-parallel-size=1")
+			Expect(argsHasFlag(c.Args, cbFlagNoAsyncScheduling)).To(BeTrue(),
+				"--no-async-scheduling")
+			Expect(argsHasFlag(c.Args, cbFlagEnforceEager)).To(BeTrue(),
+				"default cudagraph eager -> --enforce-eager")
+
+			By("M5: --kv-transfer-config carries CBKVConnector + tcp:// host")
+			kv := argsFlagValue(c.Args, cbFlagKVTransferConfig)
+			Expect(kv).NotTo(BeEmpty())
+			Expect(kv).To(ContainSubstring("CBKVConnector"))
+			Expect(kv).To(ContainSubstring(testSvcHost))
+
+			By("M7: injection.imagePullSecrets appended to spec.imagePullSecrets")
+			Expect(pullSecretNames(out)).To(ContainElement("cb-payload-pull"))
+
+			By("M6: idempotency annotation stamped")
+			Expect(out.Annotations[AnnotationInjected]).To(Equal(valueTrue))
+			Expect(out.Annotations).NotTo(HaveKey(AnnotationSkipReason))
+		})
+	})
+
+	Describe("M7 image pull secrets", func() {
+		It("does not duplicate a secret the pod already lists", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.ImagePullSecrets = []corev1.LocalObjectReference{{Name: "cb-payload-pull"}}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(pullSecretNames(out)).To(Equal([]string{"cb-payload-pull"}))
+		})
+
+		It("honors the cacheblend-image-pull-secrets annotation override", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Annotations[AnnotationImagePullSecrets] = "override-a, override-b"
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			names := pullSecretNames(out)
+			Expect(names).To(ContainElements("override-a", "override-b"))
+			Expect(names).NotTo(ContainElement("cb-payload-pull"))
+		})
+	})
+
+	Describe("gating", func() {
+		It("allows a pod with no engine annotation unchanged", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				delete(p.Annotations, AnnotationEngine)
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			Expect(resp.Allowed).To(BeTrue())
+			Expect(resp.Patches).To(BeEmpty())
+		})
+
+		It("skips + stamps engine-not-found when the connection ConfigMap is absent", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, false) // no connection ConfigMap seeded
+			pod := vllmPod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[AnnotationSkipReason]).To(Equal(SkipReasonEngineNotFound))
+			Expect(out.Annotations).NotTo(HaveKey(AnnotationInjected))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+			Expect(out.Spec.InitContainers).To(BeEmpty())
+		})
+
+		It("skips + stamps engine-not-found when the engine CR is absent", func() {
+			engine := newTestEngine(nil)
+			// Seed an injector whose engine name differs from the pod's annotation.
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Annotations[AnnotationEngine] = "does-not-exist"
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[AnnotationSkipReason]).To(Equal(SkipReasonEngineNotFound))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+		})
+
+		It("allows an already-injected pod as a no-op", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Annotations[AnnotationInjected] = valueTrue
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			Expect(resp.Allowed).To(BeTrue())
+			Expect(resp.Patches).To(BeEmpty())
+		})
+
+		It("skips + stamps command-override when the target container overrides command", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Command = []string{"/bin/sh", "-c", "exec vllm serve"}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[AnnotationSkipReason]).To(Equal(SkipReasonCommandOverride))
+			Expect(out.Annotations).NotTo(HaveKey(AnnotationInjected))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+			Expect(out.Spec.InitContainers).To(BeEmpty())
+		})
+	})
+
+	Describe("append-or-replace arg semantics", func() {
+		It("replaces a pre-existing --attention-backend value", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Args = []string{"--attention-backend", "FLASH_ATTN", "--model", "m"}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, "vllm")
+
+			Expect(argsHasFlagValue(c.Args, cbFlagAttentionBackend, cbValAttentionBackend)).To(BeTrue())
+			Expect(argsHasFlagValue(c.Args, cbFlagAttentionBackend, "FLASH_ATTN")).To(BeFalse())
+			// Not duplicated.
+			Expect(countFlag(c.Args, cbFlagAttentionBackend)).To(Equal(1))
+		})
+
+		It("replaces a pre-existing --attention-backend=value (single-token form)", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Args = []string{"--attention-backend=FLASH_ATTN", "--model", "m"}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, "vllm")
+
+			Expect(c.Args).To(ContainElement("--attention-backend=CUSTOM"))
+			Expect(c.Args).NotTo(ContainElement("--attention-backend=FLASH_ATTN"))
+		})
+
+		It("skips + stamps when the user already supplies --kv-transfer-config", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Args = []string{"--kv-transfer-config", `{"kv_connector":"Other"}`}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, "vllm")
+
+			By("the user's kv-transfer-config JSON is untouched")
+			Expect(argsFlagValue(c.Args, cbFlagKVTransferConfig)).To(Equal(`{"kv_connector":"Other"}`))
+			Expect(argsFlagValue(c.Args, cbFlagKVTransferConfig)).NotTo(ContainSubstring("CBKVConnector"))
+
+			By("the skip reason is stamped but the rest of the injection still applies")
+			Expect(out.Annotations[AnnotationSkipReason]).To(Equal(SkipReasonKVTransferConfigPresent))
+			Expect(out.Annotations[AnnotationInjected]).To(Equal(valueTrue))
+			Expect(out.Spec.HostIPC).To(BeTrue())
+			Expect(argsHasFlagValue(c.Args, cbFlagBlockSize, cbValBlockSize)).To(BeTrue())
+		})
+
+		It("prepends to a pre-existing PYTHONPATH", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Env = []corev1.EnvVar{
+					{Name: "PYTHONPATH", Value: "/opt/extra"},
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, "vllm")
+
+			Expect(envValue(c, pythonPathEnvName)).To(Equal("/cb-plugin:/opt/extra"))
+		})
+	})
+
+	Describe("target container resolution", func() {
+		It("injects into the annotation-named non-first container", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Annotations[AnnotationContainer] = "vllm"
+				p.Spec.Containers = []corev1.Container{
+					{Name: "sidecar", Image: "busybox", Args: []string{"sleep"}},
+					{Name: "vllm", Image: "vllm/vllm-openai:latest", Args: []string{"--model", "m"}},
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			By("the vLLM container is mutated")
+			vllm := findContainer(out, "vllm")
+			Expect(envValue(vllm, pythonPathEnvName)).To(Equal(cbPluginMountPath))
+			Expect(argsHasFlagValue(vllm.Args, cbFlagAttentionBackend, cbValAttentionBackend)).To(BeTrue())
+
+			By("the sidecar container is untouched")
+			sidecar := findContainer(out, "sidecar")
+			Expect(envValue(sidecar, pythonPathEnvName)).To(BeEmpty())
+			Expect(sidecar.Args).To(Equal([]string{"sleep"}))
+		})
+
+		It("uses the engine injection.targetContainer default when set", func() {
+			named := "vllm"
+			engine := newTestEngine(func(e *lmcachev1alpha1.CacheBlendEngine) {
+				e.Spec.Injection.TargetContainer = &named
+			})
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Spec.Containers = []corev1.Container{
+					{Name: "sidecar", Image: "busybox", Args: []string{"sleep"}},
+					{Name: "vllm", Image: "vllm/vllm-openai:latest", Args: []string{"--model", "m"}},
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			vllm := findContainer(out, "vllm")
+			Expect(argsHasFlagValue(vllm.Args, cbFlagAttentionBackend, cbValAttentionBackend)).To(BeTrue())
+			sidecar := findContainer(out, "sidecar")
+			Expect(sidecar.Args).To(Equal([]string{"sleep"}))
+		})
+
+		It("skips + stamps target-container-not-found for an unknown container name", func() {
+			engine := newTestEngine(nil)
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(func(p *corev1.Pod) {
+				p.Annotations[AnnotationContainer] = "does-not-exist"
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[AnnotationSkipReason]).To(Equal(SkipReasonTargetContainerNotFound))
+			Expect(out.Annotations).NotTo(HaveKey(AnnotationInjected))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+			Expect(out.Spec.InitContainers).To(BeEmpty())
+			By("the original vLLM container is left untouched")
+			vllm := findContainer(out, "vllm")
+			Expect(envValue(vllm, pythonPathEnvName)).To(BeEmpty())
+		})
+	})
+
+	Describe("cudagraph modes", func() {
+		It("emits decode-only compilation config for full_decode_only", func() {
+			mode := lmcachev1alpha1.CudagraphFullDecodeOnly
+			engine := newTestEngine(func(e *lmcachev1alpha1.CacheBlendEngine) {
+				e.Spec.Injection.Cudagraph = &mode
+			})
+			injector := newPodInjector(engine, true)
+			pod := vllmPod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, "vllm")
+
+			Expect(argsHasFlag(c.Args, cbFlagEnforceEager)).To(BeFalse())
+			Expect(argsFlagValue(c.Args, cbFlagCompilationConfig)).To(ContainSubstring("FULL_DECODE_ONLY"))
+		})
+	})
+})
+
+// --- test arg helpers (mirror the package's two-token / =-token recognition) ---
+
+// argsHasFlagValue reports whether args carries flag with the given value in
+// either the two-token or single-token form.
+func argsHasFlagValue(args []string, flag, value string) bool {
+	return argsFlagValue(args, flag) == value
+}
+
+// argsFlagValue returns the value bound to flag in args (two-token or
+// single-token form), or "" if the flag is absent.
+func argsFlagValue(args []string, flag string) string {
+	eqPrefix := flag + "="
+	for i := range len(args) {
+		if args[i] == flag && i+1 < len(args) {
+			return args[i+1]
+		}
+		if after, ok := strings.CutPrefix(args[i], eqPrefix); ok {
+			return after
+		}
+	}
+	return ""
+}
+
+// countFlag returns how many times flag appears (two-token or single-token).
+func countFlag(args []string, flag string) int {
+	eqPrefix := flag + "="
+	n := 0
+	for _, a := range args {
+		if a == flag || strings.HasPrefix(a, eqPrefix) {
+			n++
+		}
+	}
+	return n
+}
diff --git a/operator/internal/webhook/lmcache_inject_builders.go b/operator/internal/webhook/lmcache_inject_builders.go
new file mode 100644
index 0000000..b5e84fc
--- /dev/null
+++ b/operator/internal/webhook/lmcache_inject_builders.go
@@ -0,0 +1,118 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	corev1 "k8s.io/api/core/v1"
+)
+
+// LMCache vLLM flag / env names injected into an opted-in pod. Unlike the
+// CacheBlend injector, the standard LMCacheEngine path needs no plugin staging,
+// init container, or fixed flag battery: a vLLM only needs the connector JSON
+// (--kv-transfer-config) and deterministic prefix hashing (PYTHONHASHSEED).
+const (
+	// lmcFlagKVTransferConfig is the vLLM flag carrying the connector JSON. The
+	// value is the LMCacheMPConnector config read verbatim from the engine's
+	// <engine>-connection ConfigMap.
+	lmcFlagKVTransferConfig = "--kv-transfer-config"
+
+	// pythonHashSeedEnvName pins Python's hash seed so prefix-chunk hashes are
+	// identical across the vLLM process and the LMCache server; without it a
+	// repeated prompt would hash differently and miss the cache.
+	pythonHashSeedEnvName = "PYTHONHASHSEED"
+
+	// pythonHashSeedValue is the deterministic seed value injected when the user
+	// has not already set PYTHONHASHSEED.
+	pythonHashSeedValue = "0"
+)
+
+// LMCache code-payload staging names. These mirror the CacheBlend staging
+// constants with an lmcache- discriminator so the two injectors never collide on
+// the same pod (distinct volume / mount path / init-container names). Staging is
+// applied only when the engine's injection.payloadImage is set.
+const (
+	// lmcPayloadVolumeName is the shared emptyDir volume the init container stages
+	// the lmcache package tree into and the vLLM container reads it back from.
+	lmcPayloadVolumeName = "lmcache-payload"
+
+	// lmcPayloadMountPath is the in-container path the lmcache-payload volume
+	// mounts at (read-write in the init container, read-only in the vLLM
+	// container). It is also the vLLM container's prepended PYTHONPATH entry.
+	lmcPayloadMountPath = "/lmcache-payload"
+
+	// lmcPayloadInitName is the name of the injected payload init container.
+	lmcPayloadInitName = "lmcache-payload-stage"
+
+	// lmcSharedDirEnvName is the env var the payload init container reads to learn
+	// where to copy the tree (its busybox `cp -a /payload $SHARED_DIR` ENTRYPOINT).
+	// It matches the CacheBlend payload contract so one payload-image convention
+	// serves both injectors.
+	lmcSharedDirEnvName = "SHARED_DIR"
+)
+
+// lmcStaging is the LMCache injector's payload-staging parameters, consumed by
+// the shared payloadStaging builders.
+var lmcStaging = payloadStaging{
+	volumeName:   lmcPayloadVolumeName,
+	mountPath:    lmcPayloadMountPath,
+	initName:     lmcPayloadInitName,
+	sharedDirEnv: lmcSharedDirEnvName,
+}
+
+// BuildLMCacheArgs returns the target vLLM container's args with the LMCache
+// --kv-transfer-config flag applied (append-or-replace via applyArg, shared with
+// the CacheBlend builders). The flag is injected only when kvTransferConfigJSON
+// is non-empty; the handler passes "" when the user already supplied their own
+// --kv-transfer-config so this builder leaves the user's value untouched.
+//
+// Parameters:
+//   - existingArgs: the target container's current args (may be nil).
+//   - kvTransferConfigJSON: the LMCacheMPConnector JSON from the engine's
+//     connection ConfigMap, or "" to skip injecting/replacing the flag.
+//
+// Returns a new args slice; the input is not mutated.
+func BuildLMCacheArgs(existingArgs []string, kvTransferConfigJSON string) []string {
+	args := make([]string, len(existingArgs))
+	copy(args, existingArgs)
+
+	if kvTransferConfigJSON != "" {
+		args = applyArg(args, lmcFlagKVTransferConfig, kvTransferConfigJSON)
+	}
+	return args
+}
+
+// BuildLMCacheEnv returns the target vLLM container's env with PYTHONHASHSEED set
+// to "0" when it is absent. It is set on the container, never the pod, so every
+// spawned worker inherits the deterministic seed. A user-supplied PYTHONHASHSEED
+// (any value, including a valueFrom) is respected and left untouched — the user
+// has opted into their own hashing scheme.
+//
+// Parameters:
+//   - existing: the target container's current env list (may be nil).
+//
+// Returns the env list to assign; the input is not mutated.
+func BuildLMCacheEnv(existing []corev1.EnvVar) []corev1.EnvVar {
+	for i := range existing {
+		if existing[i].Name == pythonHashSeedEnvName {
+			return existing
+		}
+	}
+	out := make([]corev1.EnvVar, 0, len(existing)+1)
+	out = append(out, existing...)
+	out = append(out, corev1.EnvVar{Name: pythonHashSeedEnvName, Value: pythonHashSeedValue})
+	return out
+}
diff --git a/operator/internal/webhook/lmcache_pod_injector.go b/operator/internal/webhook/lmcache_pod_injector.go
new file mode 100644
index 0000000..c0494a7
--- /dev/null
+++ b/operator/internal/webhook/lmcache_pod_injector.go
@@ -0,0 +1,209 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	"context"
+	"net/http"
+
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// LMCache annotation keys the webhook reads and stamps. They mirror the
+// CacheBlend keys (cacheblend_pod_injector.go) with an lmcache- discriminator so
+// the two injectors never cross-fire on the same pod.
+const (
+	// LMCacheAnnotationEngine binds a pod to an LMCacheEngine in the same
+	// namespace. Its presence is the opt-in signal; its value is the engine name.
+	LMCacheAnnotationEngine = "lmcache.ai/lmcache-engine"
+
+	// LMCacheAnnotationContainer optionally names the target vLLM container;
+	// empty or absent selects the first container.
+	LMCacheAnnotationContainer = "lmcache.ai/lmcache-container"
+
+	// LMCacheAnnotationImagePullSecrets optionally overrides the engine's
+	// injection.imagePullSecrets with a comma-separated list of Secret names
+	// appended to the pod's spec.imagePullSecrets for the private payload image.
+	LMCacheAnnotationImagePullSecrets = "lmcache.ai/lmcache-image-pull-secrets"
+
+	// LMCacheAnnotationInjected is the idempotency guard stamped after a
+	// successful injection; a re-admitted pod carrying it is allowed unchanged.
+	LMCacheAnnotationInjected = "lmcache.ai/lmcache-injected"
+
+	// LMCacheAnnotationSkipReason records why injection was skipped (fail-open).
+	LMCacheAnnotationSkipReason = "lmcache.ai/lmcache-skip-reason"
+)
+
+// LMCacheLabelInject is the opt-in label the MutatingWebhookConfiguration's
+// objectSelector matches (mutating_webhook_selectors_patch.yaml). It gates which
+// pods reach the webhook; the handler itself gates on LMCacheAnnotationEngine.
+const LMCacheLabelInject = "lmcache.ai/lmcache-inject"
+
+// lmCacheKeys is the LMCache injector's annotation key set, consumed by the
+// shared gate / skip / stamp helpers.
+var lmCacheKeys = injectionKeys{
+	engine:     LMCacheAnnotationEngine,
+	container:  LMCacheAnnotationContainer,
+	injected:   LMCacheAnnotationInjected,
+	skipReason: LMCacheAnnotationSkipReason,
+}
+
+// +kubebuilder:webhook:path=/mutate-lmcache--v1-pod,mutating=true,failurePolicy=ignore,sideEffects=None,groups="",resources=pods,verbs=create,versions=v1,name=mlmcachepod.lmcache.ai,admissionReviewVersions=v1,reinvocationPolicy=Never
+
+// LMCachePodInjector is the mutating admission handler that wires an opted-in
+// vLLM pod to an LMCacheEngine so the user no longer has to hand-write the
+// --kv-transfer-config flag, hostIPC, and PYTHONHASHSEED. It is gated by the
+// engine's connection ConfigMap: it mutates a pod only when the pod's
+// lmcache.ai/lmcache-engine annotation names an engine whose <engine>-connection
+// ConfigMap exists. It fails open (failurePolicy: Ignore) and is idempotent.
+//
+// It additionally reads the LMCacheEngine CR for its optional injection sub-spec:
+// when injection.payloadImage is set it stages that lmcache code payload into the
+// vLLM container (emptyDir + init container + read-only mount + PYTHONPATH),
+// mirroring the CacheBlend injector. The connection wiring always runs; the
+// payload staging is additive and skipped when no CR / payloadImage is present.
+type LMCachePodInjector struct {
+	// Client reads the engine's connection ConfigMap and the LMCacheEngine CR. It
+	// uses the shared manager ServiceAccount, whose RBAC already grants
+	// configmaps get and lmcacheengines get.
+	Client client.Client
+
+	// Decoder decodes the admission request's raw pod object.
+	Decoder admission.Decoder
+}
+
+// Handle implements admission.Handler. It applies the LMCache connection
+// mutations (hostIPC, --kv-transfer-config, PYTHONHASHSEED) to an opted-in pod
+// whose named LMCacheEngine connection ConfigMap exists, optionally followed by
+// code-payload staging when the engine's injection.payloadImage is set, then
+// returns a JSON patch. It short-circuits to an unchanged Allowed response for
+// non-opted-in or already-injected pods, and stamps a skip-reason annotation
+// (still Allowed, fail-open) when it declines to mutate (engine missing, command
+// override, target container missing, or user-supplied --kv-transfer-config).
+func (p *LMCachePodInjector) Handle(ctx context.Context, req admission.Request) admission.Response {
+	log := ctrl.LoggerFrom(ctx)
+
+	pod, engineName, namespace, resp, handled := lmCacheKeys.gate(p.Decoder, req)
+	if handled {
+		return resp
+	}
+
+	// Read the engine CR for its optional injection defaults (payload staging +
+	// target-container default). Fail open: a missing CR or absent injection
+	// sub-spec just means connection-only injection — the connection ConfigMap
+	// (read below) remains the real gate, so existing behavior is unchanged.
+	engine := &lmcachev1alpha1.LMCacheEngine{}
+	var targetDefault *string
+	if err := p.Client.Get(ctx, types.NamespacedName{Name: engineName, Namespace: namespace}, engine); err != nil {
+		if !apierrors.IsNotFound(err) {
+			return admission.Errored(http.StatusInternalServerError, err)
+		}
+		// CR absent: engine.Spec.Injection stays nil → stage nothing, wire the
+		// connection only (the connection ConfigMap below remains the gate).
+	} else {
+		engine.SetDefaults()
+		if engine.Spec.Injection != nil {
+			targetDefault = engine.Spec.Injection.TargetContainer
+		}
+	}
+
+	// Read the connection ConfigMap (existence gate), resolve the target
+	// container, and apply the command-override gate (shared with CacheBlend).
+	kvTransferConfigJSON, containerIdx, resp, ok := prepareInjection(
+		ctx, p.Client, req, pod, lmCacheKeys, engineName, namespace, targetDefault)
+	if !ok {
+		return resp
+	}
+	target := &pod.Spec.Containers[containerIdx]
+
+	// user --kv-transfer-config gate: do not clobber the user's structured JSON.
+	userHasKVTransferConfig := argsHasFlag(target.Args, lmcFlagKVTransferConfig)
+
+	// --- Connection wiring (always applied) ---
+
+	// M0: pod hostIPC for CUDA IPC with the node-local engine.
+	pod.Spec.HostIPC = true
+
+	// Args: inject --kv-transfer-config unless the user already supplied one.
+	kvForArgs := kvTransferConfigJSON
+	if userHasKVTransferConfig {
+		kvForArgs = ""
+	}
+	target.Args = BuildLMCacheArgs(target.Args, kvForArgs)
+
+	// Env: deterministic prefix hashing (set-if-absent).
+	target.Env = BuildLMCacheEnv(target.Env)
+
+	// --- Code-payload staging (only when injection.payloadImage is set) ---
+	if engine.Spec.Injection != nil {
+		stagePayload(ctx, pod, target, engine.Spec.Injection)
+	}
+
+	log.Info("Injected LMCache connection", "engine", engineName, "container", target.Name)
+	return lmCacheKeys.stampInjected(req, pod, userHasKVTransferConfig)
+}
+
+// stagePayload applies the lmcache code-payload mutations to pod/target when the
+// injection sub-spec resolves a non-empty payload image: a shared emptyDir, the
+// payload init container, a read-only mount on the target vLLM container, a
+// prepended PYTHONPATH, and the merged image-pull secrets (annotation override
+// wins) for the private payload image. It is a no-op when payloadImage is unset,
+// leaving the pod connection-wired only. All appends are idempotent within a
+// single Handle call.
+//
+// Parameters:
+//   - ctx: the request context (carries the logger).
+//   - pod: the decoded pod (mutated in place: volumes, init containers, pull secrets).
+//   - target: the resolved vLLM container (mutated in place: volume mount, env).
+//   - injection: the engine's injection sub-spec (non-nil).
+func stagePayload(
+	ctx context.Context,
+	pod *corev1.Pod,
+	target *corev1.Container,
+	injection *lmcachev1alpha1.LMCacheInjectionSpec,
+) {
+	payloadRef, payloadPullPolicy := resolvePayloadImage(injection.PayloadImage)
+	if payloadRef == "" {
+		return // No payload image configured: connection-only injection.
+	}
+	// NOTE: an empty payloadImage object (injection.payloadImage: {}) is NOT the
+	// same as omitting it — the API server defaults repository to the shared
+	// ImageSpec default (lmcache/vllm-openai), which is not a valid payload, so
+	// staging it would run a non-payload image and stall the pod. This footgun is
+	// inherited from the shared ImageSpec default and is identical for CacheBlend;
+	// the field doc warns to set repository explicitly. Left unguarded to stay in
+	// scope + in parity with CacheBlend (revisit if it materializes in practice).
+
+	pod.Spec.Volumes = appendVolumeIfAbsent(pod.Spec.Volumes, lmcStaging.volume())
+	pod.Spec.InitContainers = appendInitContainerIfAbsent(pod.Spec.InitContainers,
+		lmcStaging.initContainer(payloadRef, payloadPullPolicy))
+	target.VolumeMounts = appendVolumeMountIfAbsent(target.VolumeMounts, lmcStaging.volumeMount())
+	target.Env = lmcStaging.prependPythonPath(target.Env)
+
+	injectedSecrets := resolveInjectedPullSecrets(injection.ImagePullSecrets,
+		pod.Annotations[LMCacheAnnotationImagePullSecrets])
+	pod.Spec.ImagePullSecrets = MergeImagePullSecrets(pod.Spec.ImagePullSecrets, injectedSecrets)
+
+	ctrl.LoggerFrom(ctx).Info("Staged LMCache payload", "image", payloadRef, "container", target.Name)
+}
diff --git a/operator/internal/webhook/lmcache_pod_injector_test.go b/operator/internal/webhook/lmcache_pod_injector_test.go
new file mode 100644
index 0000000..16e97c5
--- /dev/null
+++ b/operator/internal/webhook/lmcache_pod_injector_test.go
@@ -0,0 +1,474 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	"context"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client/fake"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+const (
+	// testContainerVLLM is the default target container name in these specs.
+	testContainerVLLM = "vllm"
+	// testUnknownContainer names a container that does not exist on the pod.
+	testUnknownContainer = "does-not-exist"
+	// testPayloadRepo is the payload image repository used in staging specs.
+	testPayloadRepo = "registry.example.com/lmcache/lmcache-payload"
+	// testPayloadPullSecret is the engine's default payload pull secret name.
+	testPayloadPullSecret = "lmcache-payload-pull"
+)
+
+// newLMCacheInjector returns an LMCachePodInjector backed by a fake client,
+// seeded with the test engine's connection ConfigMap when seedConn is true. The
+// LMCacheEngine CR itself is not seeded — the injector reads only the ConfigMap.
+func newLMCacheInjector(seedConn bool) *LMCachePodInjector {
+	scheme := newTestScheme()
+	builder := fake.NewClientBuilder().WithScheme(scheme)
+	if seedConn {
+		engine := &lmcachev1alpha1.LMCacheEngine{
+			ObjectMeta: metav1.ObjectMeta{Name: testEngineName, Namespace: testNamespace},
+		}
+		builder = builder.WithRuntimeObjects(runtime.Object(resources.BuildConnectionConfigMap(engine)))
+	}
+	return &LMCachePodInjector{
+		Client:  builder.Build(),
+		Decoder: admission.NewDecoder(scheme),
+	}
+}
+
+// lmcacheEngineWithInjection returns an LMCacheEngine whose name/namespace match
+// the connection ConfigMap the injector reads. When payloadRepo is non-empty the
+// engine carries an injection sub-spec with that payload image (tag "pinned") and
+// a default payload pull secret; an empty payloadRepo yields injection=nil.
+func lmcacheEngineWithInjection(payloadRepo string) *lmcachev1alpha1.LMCacheEngine {
+	engine := &lmcachev1alpha1.LMCacheEngine{
+		ObjectMeta: metav1.ObjectMeta{Name: testEngineName, Namespace: testNamespace},
+		Spec:       lmcachev1alpha1.LMCacheEngineSpec{L1: lmcachev1alpha1.L1BackendSpec{SizeGB: 10}},
+	}
+	if payloadRepo != "" {
+		tag := "pinned"
+		engine.Spec.Injection = &lmcachev1alpha1.LMCacheInjectionSpec{
+			PayloadImage:     &lmcachev1alpha1.ImageSpec{Repository: &payloadRepo, Tag: &tag},
+			ImagePullSecrets: []corev1.LocalObjectReference{{Name: testPayloadPullSecret}},
+		}
+	}
+	return engine
+}
+
+// newLMCacheInjectorForEngine returns an injector seeded with the given engine CR
+// and its connection ConfigMap. Unlike newLMCacheInjector this seeds the CR
+// itself, exercising the injection sub-spec the injector reads.
+func newLMCacheInjectorForEngine(engine *lmcachev1alpha1.LMCacheEngine) *LMCachePodInjector {
+	scheme := newTestScheme()
+	builder := fake.NewClientBuilder().WithScheme(scheme).WithRuntimeObjects(
+		engine, resources.BuildConnectionConfigMap(engine),
+	)
+	return &LMCachePodInjector{
+		Client:  builder.Build(),
+		Decoder: admission.NewDecoder(scheme),
+	}
+}
+
+// findVolume returns the named volume from the pod, or nil.
+func findVolume(pod *corev1.Pod, name string) *corev1.Volume {
+	for i := range pod.Spec.Volumes {
+		if pod.Spec.Volumes[i].Name == name {
+			return &pod.Spec.Volumes[i]
+		}
+	}
+	return nil
+}
+
+// findVolumeMount returns the named volume mount from the container, or nil.
+func findVolumeMount(c *corev1.Container, name string) *corev1.VolumeMount {
+	for i := range c.VolumeMounts {
+		if c.VolumeMounts[i].Name == name {
+			return &c.VolumeMounts[i]
+		}
+	}
+	return nil
+}
+
+// lmcachePod returns a minimal args-only vLLM pod (no command override) opted in
+// to LMCache injection via annotation. mutate may further customize it.
+func lmcachePod(mutate func(*corev1.Pod)) *corev1.Pod {
+	pod := &corev1.Pod{
+		ObjectMeta: metav1.ObjectMeta{
+			Name:      testPodName,
+			Namespace: testNamespace,
+			Annotations: map[string]string{
+				LMCacheAnnotationEngine: testEngineName,
+			},
+		},
+		Spec: corev1.PodSpec{
+			Containers: []corev1.Container{
+				{
+					Name:  testContainerVLLM,
+					Image: "vllm/vllm-openai:latest",
+					Args:  []string{"--model", "Qwen/Qwen2.5-0.5B"},
+				},
+			},
+		},
+	}
+	if mutate != nil {
+		mutate(pod)
+	}
+	return pod
+}
+
+var _ = Describe("LMCachePodInjector", func() {
+	ctx := context.Background()
+
+	Describe("full injection", func() {
+		It("injects hostIPC, --kv-transfer-config, and PYTHONHASHSEED for an opted-in pod", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			By("hostIPC")
+			Expect(out.Spec.HostIPC).To(BeTrue())
+
+			c := findContainer(out, testContainerVLLM)
+			Expect(c).NotTo(BeNil())
+
+			By("--kv-transfer-config carries LMCacheMPConnector + tcp:// host")
+			kv := argsFlagValue(c.Args, lmcFlagKVTransferConfig)
+			Expect(kv).NotTo(BeEmpty())
+			Expect(kv).To(ContainSubstring("LMCacheMPConnector"))
+			Expect(kv).To(ContainSubstring(testSvcHost))
+
+			By("the original --model arg is preserved")
+			Expect(argsFlagValue(c.Args, "--model")).To(Equal("Qwen/Qwen2.5-0.5B"))
+
+			By("PYTHONHASHSEED set to 0")
+			Expect(envValue(c, pythonHashSeedEnvName)).To(Equal(pythonHashSeedValue))
+
+			By("idempotency annotation stamped, no skip reason")
+			Expect(out.Annotations[LMCacheAnnotationInjected]).To(Equal(valueTrue))
+			Expect(out.Annotations).NotTo(HaveKey(LMCacheAnnotationSkipReason))
+		})
+
+		It("respects a user-set PYTHONHASHSEED", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Env = []corev1.EnvVar{
+					{Name: pythonHashSeedEnvName, Value: "42"},
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, testContainerVLLM)
+
+			Expect(envValue(c, pythonHashSeedEnvName)).To(Equal("42"))
+		})
+	})
+
+	Describe("gating", func() {
+		It("allows a pod with no engine annotation unchanged", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				delete(p.Annotations, LMCacheAnnotationEngine)
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			Expect(resp.Allowed).To(BeTrue())
+			Expect(resp.Patches).To(BeEmpty())
+		})
+
+		It("allows an already-injected pod as a no-op", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Annotations[LMCacheAnnotationInjected] = valueTrue
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			Expect(resp.Allowed).To(BeTrue())
+			Expect(resp.Patches).To(BeEmpty())
+		})
+
+		It("skips + stamps engine-not-found when the connection ConfigMap is absent", func() {
+			injector := newLMCacheInjector(false) // no connection ConfigMap seeded
+			pod := lmcachePod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[LMCacheAnnotationSkipReason]).To(Equal(SkipReasonEngineNotFound))
+			Expect(out.Annotations).NotTo(HaveKey(LMCacheAnnotationInjected))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+		})
+
+		It("skips + stamps command-override when the target container overrides command", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Command = []string{"/bin/sh", "-c", "exec vllm serve"}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[LMCacheAnnotationSkipReason]).To(Equal(SkipReasonCommandOverride))
+			Expect(out.Annotations).NotTo(HaveKey(LMCacheAnnotationInjected))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+		})
+
+		It("skips + stamps target-container-not-found for an unknown container name", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Annotations[LMCacheAnnotationContainer] = testUnknownContainer
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Annotations[LMCacheAnnotationSkipReason]).To(Equal(SkipReasonTargetContainerNotFound))
+			Expect(out.Annotations).NotTo(HaveKey(LMCacheAnnotationInjected))
+			Expect(out.Spec.HostIPC).To(BeFalse())
+		})
+	})
+
+	Describe("user-supplied --kv-transfer-config", func() {
+		It("skips + stamps but still applies hostIPC + PYTHONHASHSEED", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Args = []string{"--kv-transfer-config", `{"kv_connector":"Other"}`}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, testContainerVLLM)
+
+			By("the user's kv-transfer-config JSON is untouched")
+			Expect(argsFlagValue(c.Args, lmcFlagKVTransferConfig)).To(Equal(`{"kv_connector":"Other"}`))
+			Expect(argsFlagValue(c.Args, lmcFlagKVTransferConfig)).NotTo(ContainSubstring("LMCacheMPConnector"))
+
+			By("the skip reason is stamped but the rest of the injection still applies")
+			Expect(out.Annotations[LMCacheAnnotationSkipReason]).To(Equal(SkipReasonKVTransferConfigPresent))
+			Expect(out.Annotations[LMCacheAnnotationInjected]).To(Equal(valueTrue))
+			Expect(out.Spec.HostIPC).To(BeTrue())
+			Expect(envValue(c, pythonHashSeedEnvName)).To(Equal(pythonHashSeedValue))
+		})
+	})
+
+	Describe("target container resolution", func() {
+		It("injects into the annotation-named non-first container", func() {
+			injector := newLMCacheInjector(true)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Annotations[LMCacheAnnotationContainer] = testContainerVLLM
+				p.Spec.Containers = []corev1.Container{
+					{Name: "sidecar", Image: "busybox", Args: []string{"sleep"}},
+					{Name: testContainerVLLM, Image: "vllm/vllm-openai:latest", Args: []string{"--model", "m"}},
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			By("the vLLM container is mutated")
+			vllm := findContainer(out, testContainerVLLM)
+			Expect(argsFlagValue(vllm.Args, lmcFlagKVTransferConfig)).To(ContainSubstring("LMCacheMPConnector"))
+			Expect(envValue(vllm, pythonHashSeedEnvName)).To(Equal(pythonHashSeedValue))
+
+			By("the sidecar container is untouched")
+			sidecar := findContainer(out, "sidecar")
+			Expect(sidecar.Args).To(Equal([]string{"sleep"}))
+			Expect(envValue(sidecar, pythonHashSeedEnvName)).To(BeEmpty())
+		})
+	})
+
+	Describe("code-payload staging", func() {
+		It("stages the payload (volume + init + mount + PYTHONPATH + secret) and still wires the connection", func() {
+			injector := newLMCacheInjectorForEngine(lmcacheEngineWithInjection(testPayloadRepo))
+			pod := lmcachePod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			By("emptyDir payload volume")
+			vol := findVolume(out, lmcPayloadVolumeName)
+			Expect(vol).NotTo(BeNil())
+			Expect(vol.EmptyDir).NotTo(BeNil())
+
+			By("payload init container with image + SHARED_DIR + read-write mount")
+			Expect(out.Spec.InitContainers).To(HaveLen(1))
+			init := out.Spec.InitContainers[0]
+			Expect(init.Name).To(Equal(lmcPayloadInitName))
+			Expect(init.Image).To(Equal(testPayloadRepo + ":pinned"))
+			Expect(envValue(&init, lmcSharedDirEnvName)).To(Equal(lmcPayloadMountPath))
+			By("no command override — the payload image's own busybox cp ENTRYPOINT runs")
+			Expect(init.Command).To(BeEmpty())
+			Expect(init.ImagePullPolicy).To(Equal(corev1.PullIfNotPresent))
+			Expect(init.VolumeMounts).To(HaveLen(1))
+			Expect(init.VolumeMounts[0].Name).To(Equal(lmcPayloadVolumeName))
+			Expect(init.VolumeMounts[0].MountPath).To(Equal(lmcPayloadMountPath))
+			Expect(init.VolumeMounts[0].ReadOnly).To(BeFalse())
+
+			c := findContainer(out, testContainerVLLM)
+			By("read-only mount on the vLLM container")
+			mount := findVolumeMount(c, lmcPayloadVolumeName)
+			Expect(mount).NotTo(BeNil())
+			Expect(mount.ReadOnly).To(BeTrue())
+			Expect(mount.MountPath).To(Equal(lmcPayloadMountPath))
+
+			By("PYTHONPATH set to the payload mount path")
+			Expect(envValue(c, pythonPathEnvName)).To(Equal(lmcPayloadMountPath))
+
+			By("the engine's payload pull secret is merged onto the pod")
+			Expect(out.Spec.ImagePullSecrets).To(ContainElement(corev1.LocalObjectReference{Name: testPayloadPullSecret}))
+
+			By("connection wiring still applied")
+			Expect(out.Spec.HostIPC).To(BeTrue())
+			Expect(argsFlagValue(c.Args, lmcFlagKVTransferConfig)).To(ContainSubstring("LMCacheMPConnector"))
+			Expect(envValue(c, pythonHashSeedEnvName)).To(Equal(pythonHashSeedValue))
+			Expect(out.Annotations[LMCacheAnnotationInjected]).To(Equal(valueTrue))
+		})
+
+		It("does not stage when injection.payloadImage is unset (connection-only)", func() {
+			injector := newLMCacheInjectorForEngine(lmcacheEngineWithInjection(""))
+			pod := lmcachePod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Spec.InitContainers).To(BeEmpty())
+			Expect(findVolume(out, lmcPayloadVolumeName)).To(BeNil())
+			c := findContainer(out, testContainerVLLM)
+			Expect(envValue(c, pythonPathEnvName)).To(BeEmpty())
+
+			By("connection wiring still applied")
+			Expect(out.Spec.HostIPC).To(BeTrue())
+			Expect(argsFlagValue(c.Args, lmcFlagKVTransferConfig)).To(ContainSubstring("LMCacheMPConnector"))
+		})
+
+		It("does not stage when the engine CR is absent (connection-only via ConfigMap)", func() {
+			injector := newLMCacheInjector(true) // seeds only the connection ConfigMap, not the CR
+			pod := lmcachePod(nil)
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Spec.InitContainers).To(BeEmpty())
+			Expect(findVolume(out, lmcPayloadVolumeName)).To(BeNil())
+			Expect(out.Spec.HostIPC).To(BeTrue())
+			Expect(out.Annotations[LMCacheAnnotationInjected]).To(Equal(valueTrue))
+		})
+
+		It("prepends to a pre-existing PYTHONPATH", func() {
+			injector := newLMCacheInjectorForEngine(lmcacheEngineWithInjection(testPayloadRepo))
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.Containers[0].Env = []corev1.EnvVar{{Name: pythonPathEnvName, Value: "/opt/extra"}}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+			c := findContainer(out, testContainerVLLM)
+
+			Expect(envValue(c, pythonPathEnvName)).To(Equal(lmcPayloadMountPath + ":/opt/extra"))
+		})
+
+		It("honors the image-pull-secrets annotation override", func() {
+			injector := newLMCacheInjectorForEngine(lmcacheEngineWithInjection(testPayloadRepo))
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Annotations[LMCacheAnnotationImagePullSecrets] = "override-a,override-b"
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Spec.ImagePullSecrets).To(ContainElement(corev1.LocalObjectReference{Name: "override-a"}))
+			Expect(out.Spec.ImagePullSecrets).To(ContainElement(corev1.LocalObjectReference{Name: "override-b"}))
+
+			By("the annotation overrides the engine default rather than appending to it")
+			Expect(out.Spec.ImagePullSecrets).NotTo(ContainElement(corev1.LocalObjectReference{Name: testPayloadPullSecret}))
+		})
+
+		It("does not duplicate a payload pull secret the pod already lists", func() {
+			injector := newLMCacheInjectorForEngine(lmcacheEngineWithInjection(testPayloadRepo))
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.ImagePullSecrets = []corev1.LocalObjectReference{{Name: testPayloadPullSecret}}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			count := 0
+			for _, s := range out.Spec.ImagePullSecrets {
+				if s.Name == testPayloadPullSecret {
+					count++
+				}
+			}
+			Expect(count).To(Equal(1), "the engine's payload pull secret must be merged, not duplicated")
+		})
+
+		It("uses the engine injection.targetContainer default to select a non-first container", func() {
+			engine := lmcacheEngineWithInjection(testPayloadRepo)
+			targetName := testContainerVLLM
+			engine.Spec.Injection.TargetContainer = &targetName
+			injector := newLMCacheInjectorForEngine(engine)
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.Containers = []corev1.Container{
+					{Name: "sidecar", Image: "busybox", Args: []string{"sleep"}},
+					{Name: testContainerVLLM, Image: "vllm/vllm-openai:latest", Args: []string{"--model", "m"}},
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			By("the engine-named vLLM container is wired + staged")
+			vllm := findContainer(out, testContainerVLLM)
+			Expect(argsFlagValue(vllm.Args, lmcFlagKVTransferConfig)).To(ContainSubstring("LMCacheMPConnector"))
+			Expect(envValue(vllm, pythonPathEnvName)).To(Equal(lmcPayloadMountPath))
+			Expect(findVolumeMount(vllm, lmcPayloadVolumeName)).NotTo(BeNil())
+
+			By("the first (sidecar) container is untouched")
+			sidecar := findContainer(out, "sidecar")
+			Expect(sidecar.Args).To(Equal([]string{"sleep"}))
+			Expect(findVolumeMount(sidecar, lmcPayloadVolumeName)).To(BeNil())
+		})
+
+		It("is idempotent: pre-staged volume + init container are not duplicated", func() {
+			injector := newLMCacheInjectorForEngine(lmcacheEngineWithInjection(testPayloadRepo))
+			pod := lmcachePod(func(p *corev1.Pod) {
+				p.Spec.Volumes = []corev1.Volume{lmcStaging.volume()}
+				p.Spec.InitContainers = []corev1.Container{
+					lmcStaging.initContainer(testPayloadRepo+":pinned", corev1.PullIfNotPresent),
+				}
+			})
+
+			resp := injector.Handle(ctx, makeRequest(pod))
+			out := applyResponse(pod, resp)
+
+			Expect(out.Spec.Volumes).To(HaveLen(1))
+			Expect(out.Spec.InitContainers).To(HaveLen(1))
+		})
+	})
+})
diff --git a/operator/internal/webhook/payload_staging.go b/operator/internal/webhook/payload_staging.go
new file mode 100644
index 0000000..e09bdbd
--- /dev/null
+++ b/operator/internal/webhook/payload_staging.go
@@ -0,0 +1,134 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	corev1 "k8s.io/api/core/v1"
+)
+
+// pythonPathEnvName is the standard Python module search-path env var prepended
+// on the target vLLM container so it (and every spawned worker subprocess)
+// discovers a staged payload tree.
+const pythonPathEnvName = "PYTHONPATH"
+
+// payloadStaging parameterizes the init-container code-staging mutation shared by
+// the CacheBlend and LMCache injectors. The pattern is identical for both: a
+// shared emptyDir volume, a payload init container that copies an unpacked
+// package tree into it, a read-only mount of that volume on the target vLLM
+// container, and a PYTHONPATH entry so vLLM imports the staged tree. The two
+// injectors differ only in the names/paths they stage under, so they share this
+// machinery and supply their own constants (cbStaging, lmcStaging).
+type payloadStaging struct {
+	// volumeName is the shared emptyDir volume the init container stages the
+	// payload tree into and the vLLM container reads it back from.
+	volumeName string
+	// mountPath is the in-container path the volume mounts at — read-write in the
+	// init container (the copy target) and read-only in the vLLM container. It is
+	// also the PYTHONPATH entry, so the two must stay in lockstep.
+	mountPath string
+	// initName is the name of the injected payload init container.
+	initName string
+	// sharedDirEnv is the env var the payload image reads to learn where to copy
+	// the tree (its busybox `cp -a /payload $SHARED_DIR` ENTRYPOINT).
+	sharedDirEnv string
+}
+
+// volume returns the shared emptyDir volume the init container stages the
+// payload into and the vLLM container reads it back from.
+func (s payloadStaging) volume() corev1.Volume {
+	return corev1.Volume{
+		Name: s.volumeName,
+		VolumeSource: corev1.VolumeSource{
+			EmptyDir: &corev1.EmptyDirVolumeSource{},
+		},
+	}
+}
+
+// initContainer returns the payload init container. It mounts the shared volume
+// read-write at mountPath, sets the sharedDirEnv to that path, and runs the
+// payload image's own ENTRYPOINT (busybox `cp -a`) with no command override.
+//
+// Parameters:
+//   - image: the (possibly private) image that ships the unpacked package tree
+//     under /payload.
+//   - pullPolicy: the image pull policy for that image.
+func (s payloadStaging) initContainer(image string, pullPolicy corev1.PullPolicy) corev1.Container {
+	return corev1.Container{
+		Name:            s.initName,
+		Image:           image,
+		ImagePullPolicy: pullPolicy,
+		Env: []corev1.EnvVar{
+			{Name: s.sharedDirEnv, Value: s.mountPath},
+		},
+		VolumeMounts: []corev1.VolumeMount{
+			{
+				Name:      s.volumeName,
+				MountPath: s.mountPath,
+				ReadOnly:  false,
+			},
+		},
+	}
+}
+
+// volumeMount returns the read-only mount of the shared volume added to the
+// target vLLM container.
+func (s payloadStaging) volumeMount() corev1.VolumeMount {
+	return corev1.VolumeMount{
+		Name:      s.volumeName,
+		MountPath: s.mountPath,
+		ReadOnly:  true,
+	}
+}
+
+// prependPythonPath returns the target vLLM container's env with mountPath set as
+// (or prepended to) PYTHONPATH. It is set on the container, never the pod, so
+// every spawned worker inherits it. An existing PYTHONPATH is prepended, not
+// replaced, so <mountPath>:<existing> keeps the staged tree discoverable without
+// dropping the user's path entries.
+//
+// Parameters:
+//   - existing: the target container's current env list (may be nil).
+//
+// Returns a new env list; the input is not mutated.
+func (s payloadStaging) prependPythonPath(existing []corev1.EnvVar) []corev1.EnvVar {
+	out := make([]corev1.EnvVar, 0, len(existing)+1)
+	found := false
+	for _, e := range existing {
+		if e.Name == pythonPathEnvName {
+			found = true
+			prepended := e
+			if prepended.ValueFrom != nil {
+				// A valueFrom PYTHONPATH cannot be string-prepended safely; in
+				// that rare case overwrite with the staged path so the tree is
+				// at least discoverable (the alternative is no payload at all).
+				prepended.ValueFrom = nil
+				prepended.Value = s.mountPath
+			} else if prepended.Value == "" {
+				prepended.Value = s.mountPath
+			} else {
+				prepended.Value = s.mountPath + ":" + prepended.Value
+			}
+			out = append(out, prepended)
+			continue
+		}
+		out = append(out, e)
+	}
+	if !found {
+		out = append(out, corev1.EnvVar{Name: pythonPathEnvName, Value: s.mountPath})
+	}
+	return out
+}
diff --git a/operator/internal/webhook/pod_inject_common.go b/operator/internal/webhook/pod_inject_common.go
new file mode 100644
index 0000000..bf56e1a
--- /dev/null
+++ b/operator/internal/webhook/pod_inject_common.go
@@ -0,0 +1,245 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package webhook implements the pod-mutating admission webhooks that wire
+// opted-in vLLM pods to an engine (CacheBlend or LMCache). This file holds the
+// machinery shared by both injectors: the annotation key set, the opt-in /
+// idempotency gate, the connection-ConfigMap + target-container resolution, and
+// the skip / stamp / patch responses. The two injectors differ only in which
+// engine they read and which mutations they apply (cacheblend_pod_injector.go,
+// lmcache_pod_injector.go).
+package webhook
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/types"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	"github.com/LMCache/LMCache/internal/resources"
+)
+
+// valueTrue is the boolean-true string stamped on the injected guard and used as
+// the opt-in value of each injector's inject label.
+const valueTrue = "true"
+
+// kvTransferConfigDataKey is the key within the <engine>-connection ConfigMap's
+// Data map that holds the kv-transfer-config JSON. It must match the key written
+// by resources.buildConnectionConfigMapCore.
+const kvTransferConfigDataKey = "kv-transfer-config.json"
+
+// Skip-reason values shared by both injectors (stamped on the per-injector
+// skip-reason annotation; design §8). CacheBlend adds SkipReasonPayloadImageUnset.
+const (
+	// SkipReasonEngineNotFound is stamped when the named engine's connection
+	// ConfigMap (or, for CacheBlend, the engine CR) does not exist (fail-open).
+	SkipReasonEngineNotFound = "engine-not-found"
+
+	// SkipReasonCommandOverride is stamped when the target container overrides
+	// command, so appended args may never reach `vllm serve`.
+	SkipReasonCommandOverride = "command-override"
+
+	// SkipReasonKVTransferConfigPresent is stamped when the user already supplies
+	// --kv-transfer-config; the webhook does not clobber their structured JSON.
+	SkipReasonKVTransferConfigPresent = "kv-transfer-config-present"
+
+	// SkipReasonTargetContainerNotFound is stamped when the requested target
+	// container names a container that does not exist on the pod.
+	SkipReasonTargetContainerNotFound = "target-container-not-found"
+)
+
+// injectionKeys is one injector's annotation key set. It mirrors the same four
+// concerns for each injector (CacheBlend / LMCache) so the shared gate, skip,
+// and stamp helpers are key-set agnostic.
+type injectionKeys struct {
+	// engine binds a pod to an engine in the same namespace. Its presence is the
+	// opt-in signal; its value is the engine name.
+	engine string
+	// container optionally names the target vLLM container (empty = first).
+	container string
+	// injected is the idempotency guard stamped after a successful injection.
+	injected string
+	// skipReason records why injection was skipped (fail-open).
+	skipReason string
+}
+
+// gate decodes the pod and applies the shared idempotency + opt-in gates. When
+// handled is true the caller must return resp unchanged: either a decode error,
+// an unchanged Allow for an already-injected or non-opted-in pod. Otherwise it
+// returns the decoded pod, the bound engine name, and the lookup namespace
+// (req.Namespace, falling back to pod.Namespace which may be empty on CREATE).
+func (k injectionKeys) gate(
+	decoder admission.Decoder,
+	req admission.Request,
+) (pod *corev1.Pod, engineName, namespace string, resp admission.Response, handled bool) {
+	pod = &corev1.Pod{}
+	if err := decoder.Decode(req, pod); err != nil {
+		return nil, "", "", admission.Errored(http.StatusBadRequest, err), true
+	}
+	if pod.Annotations[k.injected] == valueTrue {
+		return pod, "", "", admission.Allowed("already injected"), true
+	}
+	engineName = strings.TrimSpace(pod.Annotations[k.engine])
+	if engineName == "" {
+		return pod, "", "", admission.Allowed("not opted in"), true
+	}
+	namespace = req.Namespace
+	if namespace == "" {
+		namespace = pod.Namespace
+	}
+	return pod, engineName, namespace, admission.Response{}, false
+}
+
+// prepareInjection performs the resolution shared by both injectors: read the
+// engine's <engine>-connection ConfigMap (existence gate, fail-open), resolve
+// the target container (annotation override > specDefault > first), and apply
+// the command-override gate. When ok is false the caller must return resp (a
+// skip + stamp, or an internal error). Otherwise it returns the kv-transfer
+// JSON and the target container index.
+//
+// Parameters:
+//   - specDefault: the engine's default target container name (nil = first); the
+//     per-pod container annotation overrides it.
+func prepareInjection(
+	ctx context.Context,
+	c client.Client,
+	req admission.Request,
+	pod *corev1.Pod,
+	keys injectionKeys,
+	engineName, namespace string,
+	specDefault *string,
+) (kvJSON string, targetIdx int, resp admission.Response, ok bool) {
+	log := ctrl.LoggerFrom(ctx)
+
+	connCM := &corev1.ConfigMap{}
+	connName := resources.ConnectionConfigMapName(engineName)
+	if err := c.Get(ctx, types.NamespacedName{Name: connName, Namespace: namespace}, connCM); err != nil {
+		if apierrors.IsNotFound(err) {
+			log.Info("Skipped injection: connection ConfigMap not found",
+				"engine", engineName, "configMap", connName, "namespace", namespace)
+			return "", 0, keys.skip(req, pod, SkipReasonEngineNotFound), false
+		}
+		return "", 0, admission.Errored(http.StatusInternalServerError, err), false
+	}
+	kvJSON = connCM.Data[kvTransferConfigDataKey]
+
+	idx, found := resolveTargetContainer(pod, specDefault, pod.Annotations[keys.container])
+	if !found {
+		log.Info("Skipped injection: target container not found",
+			"engine", engineName, "annotationContainer", pod.Annotations[keys.container])
+		return "", 0, keys.skip(req, pod, SkipReasonTargetContainerNotFound), false
+	}
+
+	if len(pod.Spec.Containers[idx].Command) > 0 {
+		log.Info("Skipped injection: target container overrides command",
+			"engine", engineName, "container", pod.Spec.Containers[idx].Name)
+		return "", 0, keys.skip(req, pod, SkipReasonCommandOverride), false
+	}
+	return kvJSON, idx, admission.Response{}, true
+}
+
+// stampInjected stamps the idempotency guard (and the kv-transfer-config-present
+// skip reason when the user supplied their own --kv-transfer-config), then
+// returns the success patch response. Callers apply their mutations first.
+func (k injectionKeys) stampInjected(
+	req admission.Request,
+	pod *corev1.Pod,
+	userHasKVTransferConfig bool,
+) admission.Response {
+	if pod.Annotations == nil {
+		pod.Annotations = map[string]string{}
+	}
+	pod.Annotations[k.injected] = valueTrue
+	if userHasKVTransferConfig {
+		pod.Annotations[k.skipReason] = SkipReasonKVTransferConfigPresent
+	}
+	return patchResponse(req, pod)
+}
+
+// skip stamps the given skip reason on the pod (without injecting) and returns
+// an Allowed patch response. The pod is still admitted (fail-open).
+func (k injectionKeys) skip(req admission.Request, pod *corev1.Pod, reason string) admission.Response {
+	if pod.Annotations == nil {
+		pod.Annotations = map[string]string{}
+	}
+	pod.Annotations[k.skipReason] = reason
+	return patchResponse(req, pod)
+}
+
+// patchResponse marshals the mutated pod and returns a JSON patch response
+// against the original raw object (req.Object.Raw).
+func patchResponse(req admission.Request, pod *corev1.Pod) admission.Response {
+	marshaled, err := json.Marshal(pod)
+	if err != nil {
+		return admission.Errored(http.StatusInternalServerError, err)
+	}
+	return admission.PatchResponseFromRaw(req.Object.Raw, marshaled)
+}
+
+// resolveTargetContainer returns the index of the container to inject into and
+// whether one was found. The per-pod annotation override (annotationName) takes
+// precedence over the engine's default; an empty selection falls back to the
+// first container. A non-empty name that matches no container yields ok=false.
+//
+// Parameters:
+//   - pod: the decoded pod.
+//   - specDefault: the engine's default target container (nil/"" = first).
+//   - annotationName: the per-pod container-override annotation value.
+func resolveTargetContainer(
+	pod *corev1.Pod,
+	specDefault *string,
+	annotationName string,
+) (int, bool) {
+	if len(pod.Spec.Containers) == 0 {
+		return 0, false
+	}
+
+	name := strings.TrimSpace(annotationName)
+	if name == "" && specDefault != nil {
+		name = strings.TrimSpace(*specDefault)
+	}
+	if name == "" {
+		return 0, true
+	}
+	for i := range pod.Spec.Containers {
+		if pod.Spec.Containers[i].Name == name {
+			return i, true
+		}
+	}
+	return 0, false
+}
+
+// argsHasFlag reports whether args already carries the given flag in either the
+// two-token "--flag value" form or the single-token "--flag=value" form.
+func argsHasFlag(args []string, flag string) bool {
+	eqPrefix := flag + "="
+	for _, a := range args {
+		if a == flag {
+			return true
+		}
+		if strings.HasPrefix(a, eqPrefix) {
+			return true
+		}
+	}
+	return false
+}
diff --git a/operator/internal/webhook/webhook_suite_test.go b/operator/internal/webhook/webhook_suite_test.go
new file mode 100644
index 0000000..1dab2f1
--- /dev/null
+++ b/operator/internal/webhook/webhook_suite_test.go
@@ -0,0 +1,173 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package webhook
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
+	"k8s.io/client-go/rest"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/envtest"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+	"sigs.k8s.io/controller-runtime/pkg/log/zap"
+	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
+	"sigs.k8s.io/controller-runtime/pkg/webhook"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// These package-level handles back the envtest-based integration spec
+// (pod_injector_envtest_test.go). The fake-client unit tests in
+// pod_injector_test.go do not use them. envtest is started once for the suite;
+// if the binaries are missing the suite fails fast (run `make setup-envtest`).
+var (
+	envtestCtx    context.Context
+	envtestCancel context.CancelFunc
+	mgrCancel     context.CancelFunc
+	testEnv       *envtest.Environment
+	cfg           *rest.Config
+	k8sClient     client.Client
+	envtestScheme *runtime.Scheme
+)
+
+// TestWebhook runs the Ginkgo suite for the CacheBlend mutating webhook package.
+func TestWebhook(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "CacheBlend Webhook Suite")
+}
+
+var _ = BeforeSuite(func() {
+	logf.SetLogger(zap.New(zap.WriteTo(GinkgoWriter), zap.UseDevMode(true)))
+
+	envtestCtx, envtestCancel = context.WithCancel(context.TODO())
+
+	envtestScheme = runtime.NewScheme()
+	Expect(clientgoscheme.AddToScheme(envtestScheme)).To(Succeed())
+	Expect(lmcachev1alpha1.AddToScheme(envtestScheme)).To(Succeed())
+
+	By("bootstrapping the test environment with the mutating webhook installed")
+	testEnv = &envtest.Environment{
+		CRDDirectoryPaths:     []string{filepath.Join("..", "..", "config", "crd", "bases")},
+		ErrorIfCRDPathMissing: true,
+		// Point at the generated manifest FILE, not the config/webhook dir: the
+		// dir also holds the kustomize selectors patch (a partial
+		// MutatingWebhookConfiguration with the same name), which envtest's
+		// path loader would try to install and reject as invalid. The base
+		// manifest has no objectSelector, so the webhook matches every pod —
+		// fine here, since the specs control which pods exist.
+		WebhookInstallOptions: envtest.WebhookInstallOptions{
+			Paths: []string{filepath.Join("..", "..", "config", "webhook", "manifests.yaml")},
+		},
+	}
+	if dir := firstFoundEnvtestBinaryDir(); dir != "" {
+		testEnv.BinaryAssetsDirectory = dir
+	}
+
+	var err error
+	cfg, err = testEnv.Start()
+	Expect(err).NotTo(HaveOccurred())
+	Expect(cfg).NotTo(BeNil())
+
+	k8sClient, err = client.New(cfg, client.Options{Scheme: envtestScheme})
+	Expect(err).NotTo(HaveOccurred())
+
+	By("starting a manager that serves the CacheBlendPodInjector webhook")
+	wio := &testEnv.WebhookInstallOptions
+	mgr, err := ctrl.NewManager(cfg, ctrl.Options{
+		Scheme:  envtestScheme,
+		Metrics: metricsserver.Options{BindAddress: "0"},
+		WebhookServer: webhook.NewServer(webhook.Options{
+			Host:    wio.LocalServingHost,
+			Port:    wio.LocalServingPort,
+			CertDir: wio.LocalServingCertDir,
+		}),
+		LeaderElection: false,
+	})
+	Expect(err).NotTo(HaveOccurred())
+
+	// The handler uses a direct (uncached) client so reads of the
+	// CacheBlendEngine and its connection ConfigMap succeed without waiting on
+	// informer cache sync — the production wiring uses mgr.GetClient().
+	directClient, err := client.New(cfg, client.Options{Scheme: envtestScheme})
+	Expect(err).NotTo(HaveOccurred())
+	mgr.GetWebhookServer().Register("/mutate--v1-pod", &webhook.Admission{Handler: &CacheBlendPodInjector{
+		Client:  directClient,
+		Decoder: admission.NewDecoder(mgr.GetScheme()),
+	}})
+
+	var mgrCtx context.Context
+	mgrCtx, mgrCancel = context.WithCancel(envtestCtx)
+	go func() {
+		defer GinkgoRecover()
+		Expect(mgr.Start(mgrCtx)).To(Succeed())
+	}()
+
+	By("waiting for the webhook server's TLS port to accept connections")
+	addr := fmt.Sprintf("%s:%d", wio.LocalServingHost, wio.LocalServingPort)
+	Eventually(func() error {
+		conn, derr := tls.DialWithDialer(&net.Dialer{Timeout: time.Second}, "tcp", addr,
+			&tls.Config{InsecureSkipVerify: true}) //nolint:gosec // test-only readiness probe
+		if derr != nil {
+			return derr
+		}
+		return conn.Close()
+	}, 30*time.Second, 200*time.Millisecond).Should(Succeed())
+})
+
+var _ = AfterSuite(func() {
+	if mgrCancel != nil {
+		mgrCancel()
+	}
+	if envtestCancel != nil {
+		envtestCancel()
+	}
+	By("tearing down the test environment")
+	if testEnv != nil {
+		Eventually(func() error { return testEnv.Stop() }, time.Minute, time.Second).Should(Succeed())
+	}
+})
+
+// firstFoundEnvtestBinaryDir locates the envtest binary directory under bin/k8s
+// so the suite runs from an IDE without KUBEBUILDER_ASSETS set, mirroring the
+// controller suite's helper.
+func firstFoundEnvtestBinaryDir() string {
+	basePath := filepath.Join("..", "..", "bin", "k8s")
+	entries, err := os.ReadDir(basePath)
+	if err != nil {
+		return ""
+	}
+	for _, entry := range entries {
+		if entry.IsDir() {
+			return filepath.Join(basePath, entry.Name())
+		}
+	}
+	return ""
+}
diff --git a/operator/make/build.mk b/operator/make/build.mk
new file mode 100644
index 0000000..eb77c2b
--- /dev/null
+++ b/operator/make/build.mk
@@ -0,0 +1,43 @@
+##@ Build
+
+.PHONY: build
+build: manifests generate fmt vet ## Build manager binary.
+	go build -o bin/manager cmd/main.go
+
+.PHONY: run
+run: manifests generate fmt vet ## Run a controller from your host (webhook off; no host certs needed).
+	ENABLE_WEBHOOKS=false go run ./cmd/main.go
+
+# If you wish to build the manager image targeting other platforms you can use the --platform flag.
+# (i.e. docker build --platform linux/arm64). However, you must enable docker buildKit for it.
+# More info: https://docs.docker.com/develop/develop-images/build_enhancements/
+.PHONY: docker-build
+docker-build: ## Build docker image with the manager.
+	$(CONTAINER_TOOL) build -t ${IMG} .
+
+.PHONY: docker-push
+docker-push: ## Push docker image with the manager.
+	$(CONTAINER_TOOL) push ${IMG}
+
+# PLATFORMS defines the target platforms for the manager image be built to provide support to multiple
+# architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
+# - be able to use docker buildx. More info: https://docs.docker.com/build/buildx/
+# - have enabled BuildKit. More info: https://docs.docker.com/develop/develop-images/build_enhancements/
+# - be able to push the image to your registry (i.e. if you do not set a valid value via IMG=<myregistry/image:<tag>> then the export will fail)
+# To adequately provide solutions that are compatible with multiple platforms, you should consider using this option.
+PLATFORMS ?= linux/amd64
+.PHONY: docker-buildx
+docker-buildx: ## Build and push docker image for the manager for cross-platform support
+	# copy existing Dockerfile and insert --platform=${BUILDPLATFORM} into Dockerfile.cross, and preserve the original Dockerfile
+	sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
+	- $(CONTAINER_TOOL) buildx create --name operator-builder
+	$(CONTAINER_TOOL) buildx use operator-builder
+	- $(CONTAINER_TOOL) buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile.cross .
+	- $(CONTAINER_TOOL) buildx rm operator-builder
+	rm Dockerfile.cross
+
+.PHONY: build-installer
+build-installer: manifests generate kustomize ## Generate a consolidated YAML with CRDs and deployment.
+	mkdir -p dist
+	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
+	"$(KUSTOMIZE)" build config/default > dist/install.yaml
diff --git a/operator/make/deploy.mk b/operator/make/deploy.mk
new file mode 100644
index 0000000..7d337b9
--- /dev/null
+++ b/operator/make/deploy.mk
@@ -0,0 +1,24 @@
+##@ Deployment
+
+ifndef ignore-not-found
+  ignore-not-found = false
+endif
+
+.PHONY: install
+install: manifests kustomize ## Install CRDs into the K8s cluster specified in ~/.kube/config.
+	@out="$$( "$(KUSTOMIZE)" build config/crd 2>/dev/null || true )"; \
+	if [ -n "$$out" ]; then echo "$$out" | "$(KUBECTL)" apply -f -; else echo "No CRDs to install; skipping."; fi
+
+.PHONY: uninstall
+uninstall: manifests kustomize ## Uninstall CRDs from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
+	@out="$$( "$(KUSTOMIZE)" build config/crd 2>/dev/null || true )"; \
+	if [ -n "$$out" ]; then echo "$$out" | "$(KUBECTL)" delete --ignore-not-found=$(ignore-not-found) -f -; else echo "No CRDs to delete; skipping."; fi
+
+.PHONY: deploy
+deploy: manifests kustomize ## Deploy controller to the K8s cluster specified in ~/.kube/config.
+	cd config/manager && "$(KUSTOMIZE)" edit set image controller=${IMG}
+	"$(KUSTOMIZE)" build config/default | "$(KUBECTL)" apply -f -
+
+.PHONY: undeploy
+undeploy: kustomize ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
+	"$(KUSTOMIZE)" build config/default | "$(KUBECTL)" delete --ignore-not-found=$(ignore-not-found) -f -
diff --git a/operator/make/dev.mk b/operator/make/dev.mk
new file mode 100644
index 0000000..ee4b188
--- /dev/null
+++ b/operator/make/dev.mk
@@ -0,0 +1,17 @@
+##@ Development
+
+.PHONY: manifests
+manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects.
+	"$(CONTROLLER_GEN)" rbac:roleName=manager-role crd:allowDangerousTypes=true webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+
+.PHONY: generate
+generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
+	"$(CONTROLLER_GEN)" object:headerFile="hack/boilerplate.go.txt" paths="./..."
+
+.PHONY: fmt
+fmt: ## Run gofmt against code (covers build-tagged files that `go fmt ./...` skips).
+	gofmt -w .
+
+.PHONY: vet
+vet: ## Run go vet against code.
+	go vet ./...
diff --git a/operator/make/e2e-gpu.mk b/operator/make/e2e-gpu.mk
new file mode 100644
index 0000000..afeea2e
--- /dev/null
+++ b/operator/make/e2e-gpu.mk
@@ -0,0 +1,175 @@
+##@ E2E (GPU)
+
+# Creates a 2-node Kind cluster (control-plane + GPU worker) and
+# installs the NVIDIA GPU Operator. The Operator handles toolkit
+# install + containerd reconfig inside the worker so pods with
+# `runtimeClassName: nvidia` get NVML / libcuda injected.
+#
+# Full design notes (why GPU Operator vs bare device plugin, host
+# prereqs, single-node intent) live in operator/AGENTS.md under the
+# "GPU tier (M2)" section. Keep this header lean.
+ifndef GPU_KIND_CLUSTER
+GPU_KIND_CLUSTER := operator-test-e2e-gpu-$(shell date +%s%N | tail -c 9)
+endif
+HELM ?= helm
+
+# GPU Operator helm flags worth a note (the rest are defaults):
+#   driver.enabled=false   — host docker's nvidia runtime already
+#                            injects /dev/nvidia* + driver libs into
+#                            the Kind worker; we don't want a kernel
+#                            driver installed inside the cluster.
+#   toolkit.enabled=true   — toolkit daemonset writes containerd's
+#                            config.toml + registers a `nvidia`
+#                            runtime handler. Pods with
+#                            runtimeClassName=nvidia then get NVML.
+#   cdi.enabled=true       — modern CDI annotation path; needs
+#                            containerd 1.7+ (kindest/node has it).
+#   CONTAINERD_CONFIG /    — Kind's containerd config + socket are at
+#   CONTAINERD_SOCKET        non-default paths; without overriding,
+#                            the toolkit daemonset edits a phantom
+#                            config and ClusterPolicy never goes Ready.
+#   validator.driver.env   — DISABLE_DEV_CHAR_SYMLINK_CREATION; Kind
+#                            nodes can't mknod /dev/char/* and the
+#                            driver validator pod would loop without
+#                            this. Documented gpu-operator-on-kind
+#                            workaround.
+.PHONY: setup-test-e2e-gpu-kind
+setup-test-e2e-gpu-kind: ## Create a Kind GPU cluster (inline config) + install the NVIDIA GPU Operator.
+	@command -v $(KIND)    >/dev/null 2>&1 || { echo "kind not found. Install Kind."; exit 1; }
+	@command -v $(HELM)    >/dev/null 2>&1 || { echo "helm not found. Install helm v3."; exit 1; }
+	@command -v $(KUBECTL) >/dev/null 2>&1 || { echo "kubectl not found."; exit 1; }
+	@docker info 2>/dev/null | grep -q "Default Runtime: nvidia" || { \
+		echo "ERROR: Docker default-runtime is not 'nvidia'."; \
+		echo "  Fix: sudo nvidia-ctk runtime configure --runtime=docker --set-as-default --cdi.enabled && sudo systemctl restart docker"; \
+		exit 1; \
+	}
+	@grep -E '^\s*accept-nvidia-visible-devices-as-volume-mounts\s*=\s*true' /etc/nvidia-container-runtime/config.toml >/dev/null 2>&1 || { \
+		echo "ERROR: 'accept-nvidia-visible-devices-as-volume-mounts' is not true in /etc/nvidia-container-runtime/config.toml."; \
+		echo "  Fix: sudo nvidia-ctk config --set accept-nvidia-visible-devices-as-volume-mounts=true --in-place && sudo systemctl restart docker"; \
+		echo "  Without this, the volume-mount marker won't propagate into the Kind worker."; \
+		exit 1; \
+	}
+	@echo "==> Creating Kind GPU cluster '$(GPU_KIND_CLUSTER)' (1 control-plane + 1 worker, all GPUs)..."
+	@printf '%s\n' \
+		'kind: Cluster' \
+		'apiVersion: kind.x-k8s.io/v1alpha4' \
+		'name: $(GPU_KIND_CLUSTER)' \
+		'nodes:' \
+		'- role: control-plane' \
+		'- role: worker' \
+		'  labels:' \
+		'    nvidia.com/gpu.present: "true"' \
+		'  extraMounts:' \
+		'    - hostPath: /dev/null' \
+		'      containerPath: /var/run/nvidia-container-devices/all' \
+		| $(KIND) create cluster --config=-
+	@echo "==> Installing the NVIDIA GPU Operator (this takes 5-10 minutes)..."
+	$(HELM) repo add nvidia https://helm.ngc.nvidia.com/nvidia >/dev/null 2>&1 || true
+	$(HELM) repo update nvidia >/dev/null
+	@$(HELM) upgrade -i gpu-operator nvidia/gpu-operator \
+		--kube-context=kind-$(GPU_KIND_CLUSTER) \
+		--namespace gpu-operator --create-namespace \
+		--set driver.enabled=false \
+		--set toolkit.enabled=true \
+		--set cdi.enabled=true \
+		--set toolkit.env[0].name=CONTAINERD_CONFIG \
+		--set-string toolkit.env[0].value=/etc/containerd/config.toml \
+		--set toolkit.env[1].name=CONTAINERD_SOCKET \
+		--set-string toolkit.env[1].value=/run/containerd/containerd.sock \
+		--set toolkit.env[2].name=CONTAINERD_RUNTIME_CLASS \
+		--set-string toolkit.env[2].value=nvidia \
+		--set toolkit.env[3].name=CONTAINERD_SET_AS_DEFAULT \
+		--set-string toolkit.env[3].value=true \
+		--set validator.driver.env[0].name=DISABLE_DEV_CHAR_SYMLINK_CREATION \
+		--set-string validator.driver.env[0].value=true \
+		--wait --timeout=15m \
+		|| { $(MAKE) --no-print-directory diagnose-test-e2e-gpu-kind GPU_KIND_CLUSTER=$(GPU_KIND_CLUSTER); exit 1; }
+	@echo "==> Waiting for the node to advertise nvidia.com/gpu (up to 5 min)..."
+	@gpus=""; \
+	for i in $$(seq 1 150); do \
+		gpus=$$($(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) get nodes \
+			-o jsonpath='{.items[?(@.metadata.labels.nvidia\.com/gpu\.present=="true")].status.allocatable.nvidia\.com/gpu}' 2>/dev/null || true); \
+		case "$$gpus" in [1-9]*) echo "==> Node advertises $$gpus GPU(s)"; exit 0 ;; esac; \
+		sleep 2; \
+	done; \
+	echo ""; \
+	echo "ERROR: node never advertised nvidia.com/gpu after 5 min."; \
+	$(MAKE) --no-print-directory diagnose-test-e2e-gpu-kind GPU_KIND_CLUSTER=$(GPU_KIND_CLUSTER); \
+	exit 1
+
+.PHONY: diagnose-test-e2e-gpu-kind
+diagnose-test-e2e-gpu-kind: ## Dump gpu-operator state for the named cluster (for setup failures).
+	@echo ""
+	@echo "=========================================================================="
+	@echo "GPU Operator diagnostic dump for cluster: $(GPU_KIND_CLUSTER)"
+	@echo "=========================================================================="
+	@echo ""
+	@echo "--- kubectl get nodes (allocatable / capacity) ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\n  allocatable: "}{.status.allocatable}{"\n  capacity: "}{.status.capacity}{"\n"}{end}' || true
+	@echo ""
+	@echo "--- ClusterPolicy status ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) get clusterpolicy -o jsonpath='{.items[0].status}' 2>/dev/null | head -c 2000 || echo "(no ClusterPolicy yet)"
+	@echo ""
+	@echo ""
+	@echo "--- gpu-operator pods ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) get pods -n gpu-operator -o wide || true
+	@echo ""
+	@echo "--- gpu-operator events (last 40) ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) get events -n gpu-operator --sort-by=.lastTimestamp 2>/dev/null | tail -40 || true
+	@echo ""
+	@echo "--- toolkit daemonset logs ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) logs -n gpu-operator -l app=nvidia-container-toolkit-daemonset --tail=60 --all-containers 2>&1 | head -120 || true
+	@echo ""
+	@echo "--- device-plugin daemonset logs ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) logs -n gpu-operator -l app=nvidia-device-plugin-daemonset --tail=60 --all-containers 2>&1 | head -120 || true
+	@echo ""
+	@echo "--- driver-validator pod logs (if running) ---"
+	@$(KUBECTL) --context=kind-$(GPU_KIND_CLUSTER) logs -n gpu-operator -l app=nvidia-operator-validator --tail=60 --all-containers 2>&1 | head -120 || true
+	@echo ""
+	@echo "--- /dev/nvidia* inside the Kind worker container ---"
+	@(docker exec $(GPU_KIND_CLUSTER)-worker  sh -c 'ls /dev/nvidia* 2>&1' || \
+	  docker exec $(GPU_KIND_CLUSTER)-control-plane sh -c 'ls /dev/nvidia* 2>&1' || \
+	  echo "(no nvidia devices visible)") | head -30 || true
+	@echo ""
+	@echo "--- /etc/containerd/config.toml nvidia stanza (inside Kind worker) ---"
+	@docker exec $(GPU_KIND_CLUSTER)-worker sh -c 'grep -A8 "nvidia" /etc/containerd/config.toml 2>&1 || echo "(no nvidia stanza)"' || true
+	@echo "=========================================================================="
+
+.PHONY: test-e2e-gpu-kind
+test-e2e-gpu-kind: manifests generate fmt vet ## Self-contained GPU smoke on a Kind cluster (build + load + run + cleanup).
+	@echo "==> Using Kind GPU cluster: $(GPU_KIND_CLUSTER) (auto-deleted after the run unless KEEP_CLUSTER_ON_FAILURE=1)"
+	@trap 'rc=$$?; \
+		if [ "$$rc" -ne 0 ] && [ "$(KEEP_CLUSTER_ON_FAILURE)" = "1" ]; then \
+			echo ""; \
+			echo "==> KEEP_CLUSTER_ON_FAILURE=1 set; leaving cluster '$(GPU_KIND_CLUSTER)' alive."; \
+			echo "    To diagnose:  make diagnose-test-e2e-gpu-kind GPU_KIND_CLUSTER=$(GPU_KIND_CLUSTER)"; \
+			echo "    To delete:    make cleanup-test-e2e-gpu-kind GPU_KIND_CLUSTER=$(GPU_KIND_CLUSTER)"; \
+		else \
+			$(MAKE) --no-print-directory cleanup-test-e2e-gpu-kind GPU_KIND_CLUSTER=$(GPU_KIND_CLUSTER); \
+		fi; \
+		exit $$rc' EXIT INT TERM; \
+	 $(MAKE) --no-print-directory setup-test-e2e-gpu-kind GPU_KIND_CLUSTER=$(GPU_KIND_CLUSTER) && \
+	 KIND=$(KIND) KIND_CLUSTER=$(GPU_KIND_CLUSTER) \
+		go test -tags=e2e,e2e_gpu ./test/e2e/ -v -ginkgo.v -timeout 60m
+
+.PHONY: cleanup-test-e2e-gpu-kind
+cleanup-test-e2e-gpu-kind: ## Delete the Kind GPU cluster (idempotent).
+	@if $(KIND) get clusters 2>/dev/null | grep -qx "$(GPU_KIND_CLUSTER)"; then \
+		echo "Deleting Kind GPU cluster '$(GPU_KIND_CLUSTER)'..."; \
+		$(KIND) delete cluster --name $(GPU_KIND_CLUSTER); \
+	else \
+		echo "Kind GPU cluster '$(GPU_KIND_CLUSTER)' does not exist; nothing to delete."; \
+	fi
+
+# Run the GPU smoke tier against an already-configured GPU cluster.
+# Runs the no-GPU specs PLUS the e2e_gpu specs. Caller is responsible
+# for: a GPU node labeled nvidia.com/gpu.present=true with the nvidia
+# RuntimeClass; KUBECONFIG pointing at it; pushing the operator image
+# (pass IMG=); and any cluster cleanup. Knobs: VLLM_MODEL,
+# VLLM_IMAGE, SKIP_VLLM_INTEGRATION (see vllm_integration_smoke_test.go).
+# 60m timeout absorbs cold pulls of the ~10GB vllm-openai image.
+.PHONY: test-e2e-gpu-cluster
+test-e2e-gpu-cluster: _require-img manifests generate fmt vet ## Run GPU smoke against an existing GPU cluster.
+	@echo "Running GPU smoke against $$(kubectl config current-context) using IMG=$(IMG)"
+	IMG=$(IMG) SMOKE_SKIP_IMAGE_LOAD=true \
+		go test -tags=e2e,e2e_gpu ./test/e2e/ -v -ginkgo.v -timeout 60m
diff --git a/operator/make/e2e.mk b/operator/make/e2e.mk
new file mode 100644
index 0000000..117dd30
--- /dev/null
+++ b/operator/make/e2e.mk
@@ -0,0 +1,64 @@
+##@ E2E (no-GPU)
+
+# Both *-cluster targets need a registry-reachable IMG and refuse the
+# scaffold default (controller:latest) which is meaningless to a remote
+# cluster's image puller. Used as a prereq by every cluster-targeting
+# recipe in both e2e.mk and e2e-gpu.mk.
+.PHONY: _require-img
+_require-img:
+	@if [ -z "$(IMG)" ] || [ "$(IMG)" = "controller:latest" ]; then \
+		echo "ERROR: pass IMG=<registry/image:tag> pointing at an image the cluster can pull"; \
+		exit 1; \
+	fi
+
+# Unique Kind cluster name per `make test-e2e-kind` invocation so
+# concurrent runs never collide and cleanup only touches THIS run's
+# cluster. Set KIND_CLUSTER explicitly to target an existing cluster
+# (you're responsible for cleanup in that case).
+ifndef KIND_CLUSTER
+KIND_CLUSTER := operator-test-e2e-$(shell date +%s%N | tail -c 9)
+endif
+
+.PHONY: setup-test-e2e-kind
+setup-test-e2e-kind: ## Create a fresh, uniquely-named Kind cluster for e2e tests
+	@command -v $(KIND) >/dev/null 2>&1 || { \
+		echo "Kind is not installed. Please install Kind manually."; \
+		exit 1; \
+	}
+	@echo "Creating Kind cluster '$(KIND_CLUSTER)'..."
+	@$(KIND) create cluster --name $(KIND_CLUSTER)
+
+# setup-test-e2e-kind is invoked from inside the trapped shell rather
+# than as a Make prerequisite, so a setup failure still triggers
+# cleanup (prerequisites run BEFORE the recipe's shell installs the
+# trap). KIND_CLUSTER is passed to both sub-makes so they target THIS
+# run's cluster, not a newly-computed unique name. SIGKILL is
+# uncatchable; on that rare path the cluster leaks under its unique
+# name (`kind delete cluster --name ...` to clean up manually).
+.PHONY: test-e2e-kind
+test-e2e-kind: manifests generate fmt vet ## Run the e2e tests. Expected an isolated environment using Kind.
+	@echo "==> Using Kind cluster: $(KIND_CLUSTER) (auto-deleted after the run)"
+	@trap '$(MAKE) --no-print-directory cleanup-test-e2e-kind KIND_CLUSTER=$(KIND_CLUSTER)' EXIT INT TERM; \
+	 $(MAKE) --no-print-directory setup-test-e2e-kind KIND_CLUSTER=$(KIND_CLUSTER) && \
+	 KIND=$(KIND) KIND_CLUSTER=$(KIND_CLUSTER) go test -tags=e2e ./test/e2e/ -v -ginkgo.v -timeout 30m
+
+.PHONY: cleanup-test-e2e-kind
+cleanup-test-e2e-kind: ## Delete the Kind cluster used for e2e tests (idempotent)
+	@if $(KIND) get clusters 2>/dev/null | grep -qx "$(KIND_CLUSTER)"; then \
+		echo "Deleting Kind cluster '$(KIND_CLUSTER)'..."; \
+		$(KIND) delete cluster --name $(KIND_CLUSTER); \
+	else \
+		echo "Kind cluster '$(KIND_CLUSTER)' does not exist; nothing to delete."; \
+	fi
+
+# Run the smoke suite against an already-configured cluster (no Kind setup).
+# Caller is responsible for: KUBECONFIG pointing at the cluster, the
+# operator image being pushed to a registry the cluster can pull from,
+# and any cluster cleanup. The suite will install CRDs, deploy the
+# controller, run every spec, then undeploy + uninstall; the cluster
+# is left intact.
+.PHONY: test-e2e-cluster
+test-e2e-cluster: _require-img manifests generate fmt vet ## Run smoke against the currently-configured cluster (no Kind).
+	@echo "Running smoke suite against $$(kubectl config current-context) using IMG=$(IMG)"
+	IMG=$(IMG) SMOKE_SKIP_IMAGE_LOAD=true \
+		go test -tags=e2e ./test/e2e/ -v -ginkgo.v -timeout 30m
diff --git a/operator/make/lint.mk b/operator/make/lint.mk
new file mode 100644
index 0000000..563d3e6
--- /dev/null
+++ b/operator/make/lint.mk
@@ -0,0 +1,22 @@
+##@ Lint
+
+.PHONY: install-hooks
+install-hooks: golangci-lint ## Install git pre-commit hooks (requires pre-commit: pip install pre-commit).
+	@command -v pre-commit >/dev/null 2>&1 || { \
+		echo "pre-commit not found. Install with: pip install pre-commit"; \
+		exit 1; \
+	}
+	cd "$(shell git rev-parse --show-toplevel)" && pre-commit install -c operator/.pre-commit-config.yaml
+	@echo "Pre-commit hooks installed (operator)."
+
+.PHONY: lint
+lint: golangci-lint ## Run golangci-lint linter
+	"$(GOLANGCI_LINT)" run
+
+.PHONY: lint-fix
+lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
+	"$(GOLANGCI_LINT)" run --fix
+
+.PHONY: lint-config
+lint-config: golangci-lint ## Verify golangci-lint linter configuration
+	"$(GOLANGCI_LINT)" config verify
diff --git a/operator/make/tools.mk b/operator/make/tools.mk
new file mode 100644
index 0000000..3577481
--- /dev/null
+++ b/operator/make/tools.mk
@@ -0,0 +1,83 @@
+##@ Dependencies
+
+## Location to install dependencies to
+LOCALBIN ?= $(shell pwd)/bin
+$(LOCALBIN):
+	mkdir -p "$(LOCALBIN)"
+
+## Tool Binaries
+KUBECTL ?= kubectl
+KIND ?= kind
+KUSTOMIZE ?= $(LOCALBIN)/kustomize
+CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
+ENVTEST ?= $(LOCALBIN)/setup-envtest
+GOLANGCI_LINT = $(LOCALBIN)/golangci-lint
+
+## Tool Versions
+KUSTOMIZE_VERSION ?= v5.8.1
+CONTROLLER_TOOLS_VERSION ?= v0.20.1
+
+#ENVTEST_VERSION is the version of controller-runtime release branch to fetch the envtest setup script (i.e. release-0.20)
+ENVTEST_VERSION ?= $(shell v='$(call gomodver,sigs.k8s.io/controller-runtime)'; \
+  [ -n "$$v" ] || { echo "Set ENVTEST_VERSION manually (controller-runtime replace has no tag)" >&2; exit 1; }; \
+  printf '%s\n' "$$v" | sed -E 's/^v?([0-9]+)\.([0-9]+).*/release-\1.\2/')
+
+#ENVTEST_K8S_VERSION is the version of Kubernetes to use for setting up ENVTEST binaries (i.e. 1.31)
+ENVTEST_K8S_VERSION ?= $(shell v='$(call gomodver,k8s.io/api)'; \
+  [ -n "$$v" ] || { echo "Set ENVTEST_K8S_VERSION manually (k8s.io/api replace has no tag)" >&2; exit 1; }; \
+  printf '%s\n' "$$v" | sed -E 's/^v?[0-9]+\.([0-9]+).*/1.\1/')
+
+GOLANGCI_LINT_VERSION ?= v2.8.0
+
+.PHONY: kustomize
+kustomize: $(KUSTOMIZE) ## Download kustomize locally if necessary.
+$(KUSTOMIZE): $(LOCALBIN)
+	$(call go-install-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v5,$(KUSTOMIZE_VERSION))
+
+.PHONY: controller-gen
+controller-gen: $(CONTROLLER_GEN) ## Download controller-gen locally if necessary.
+$(CONTROLLER_GEN): $(LOCALBIN)
+	$(call go-install-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen,$(CONTROLLER_TOOLS_VERSION))
+
+.PHONY: setup-envtest
+setup-envtest: envtest ## Download the binaries required for ENVTEST in the local bin directory.
+	@echo "Setting up envtest binaries for Kubernetes version $(ENVTEST_K8S_VERSION)..."
+	@"$(ENVTEST)" use $(ENVTEST_K8S_VERSION) --bin-dir "$(LOCALBIN)" -p path || { \
+		echo "Error: Failed to set up envtest binaries for version $(ENVTEST_K8S_VERSION)."; \
+		exit 1; \
+	}
+
+.PHONY: envtest
+envtest: $(ENVTEST) ## Download setup-envtest locally if necessary.
+$(ENVTEST): $(LOCALBIN)
+	$(call go-install-tool,$(ENVTEST),sigs.k8s.io/controller-runtime/tools/setup-envtest,$(ENVTEST_VERSION))
+
+.PHONY: golangci-lint
+golangci-lint: $(GOLANGCI_LINT) ## Download golangci-lint locally if necessary.
+$(GOLANGCI_LINT): $(LOCALBIN)
+	$(call go-install-tool,$(GOLANGCI_LINT),github.com/golangci/golangci-lint/v2/cmd/golangci-lint,$(GOLANGCI_LINT_VERSION))
+	@test -f .custom-gcl.yml && { \
+		echo "Building custom golangci-lint with plugins..." && \
+		$(GOLANGCI_LINT) custom --destination $(LOCALBIN) --name golangci-lint-custom && \
+		mv -f $(LOCALBIN)/golangci-lint-custom $(GOLANGCI_LINT); \
+	} || true
+
+# go-install-tool will 'go install' any package with custom target and name of binary, if it doesn't exist
+# $1 - target path with name of binary
+# $2 - package url which can be installed
+# $3 - specific version of package
+define go-install-tool
+@[ -f "$(1)-$(3)" ] && [ "$$(readlink -- "$(1)" 2>/dev/null)" = "$(1)-$(3)" ] || { \
+set -e; \
+package=$(2)@$(3) ;\
+echo "Downloading $${package}" ;\
+rm -f "$(1)" ;\
+GOBIN="$(LOCALBIN)" go install $${package} ;\
+mv "$(LOCALBIN)/$$(basename "$(1)")" "$(1)-$(3)" ;\
+} ;\
+ln -sf "$$(realpath "$(1)-$(3)")" "$(1)"
+endef
+
+define gomodver
+$(shell go list -m -f '{{if .Replace}}{{.Replace.Version}}{{else}}{{.Version}}{{end}}' $(1) 2>/dev/null)
+endef
diff --git a/operator/make/unit.mk b/operator/make/unit.mk
new file mode 100644
index 0000000..10fe847
--- /dev/null
+++ b/operator/make/unit.mk
@@ -0,0 +1,47 @@
+##@ Unit tests + coverage
+
+# Runs envtest-driven unit tests across everything except the
+# build-tagged e2e packages. Writes operator/cover.out so the
+# downstream test-cover* targets have something to summarise.
+.PHONY: test
+test: manifests generate fmt vet setup-envtest ## Run unit tests via envtest. Writes cover.out.
+	KUBEBUILDER_ASSETS="$(shell "$(ENVTEST)" use $(ENVTEST_K8S_VERSION) --bin-dir "$(LOCALBIN)" -p path)" \
+		go test $$(go list ./... | grep -v /e2e) -coverprofile cover.out
+
+# Strip auto-generated DeepCopy from the profile before reporting —
+# 100% coverage on `zz_generated.deepcopy.go` is meaningless and
+# either inflates or dilutes the headline depending on volume. We
+# also drop test/utils (its consumers are e2e specs, not unit tests)
+# and cmd/ (entrypoint wiring; integration-tested implicitly).
+COVER_PROFILE     ?= cover.out
+COVER_FILTERED    := $(COVER_PROFILE).filtered
+COVER_FILTER_RE   ?= zz_generated|test/utils|cmd/
+
+# Threshold (percent) for the "under-threshold" callout in test-cover.
+# Override at the CLI for stricter / looser runs:
+#   make test-cover COVER_THRESHOLD=90
+COVER_THRESHOLD   ?= 80
+
+.PHONY: test-cover
+test-cover: test ## Print a per-function coverage summary (filtered), call out under-threshold entries, + total.
+	@grep -vE "$(COVER_FILTER_RE)" $(COVER_PROFILE) > $(COVER_FILTERED)
+	@echo ""
+	@echo "==> Per-function coverage (filtered, last 20):"
+	@go tool cover -func=$(COVER_FILTERED) | tail -20
+	@echo ""
+	@echo "==> Functions below $(COVER_THRESHOLD)% (worst first):"
+	@# awk prepends the numeric percentage as a sort key, sort -n
+	@# orders ascending, cut strips the key back off.
+	@go tool cover -func=$(COVER_FILTERED) | awk -v t=$(COVER_THRESHOLD) ' \
+		/^total:/ { next } \
+		{ p = $$NF; sub(/%/, "", p); if (p+0 < t) printf "%07.3f|    %s\n", p+0, $$0 } \
+	' | sort -n | cut -d'|' -f2- || true
+	@echo ""
+	@echo "==> Total (filtered):"
+	@go tool cover -func=$(COVER_FILTERED) | grep "^total:"
+
+.PHONY: test-cover-html
+test-cover-html: test ## Generate an HTML coverage heatmap at cover.html.
+	@grep -vE "$(COVER_FILTER_RE)" $(COVER_PROFILE) > $(COVER_FILTERED)
+	go tool cover -html=$(COVER_FILTERED) -o cover.html
+	@echo "==> Open cover.html in your browser."
diff --git a/operator/test/e2e/auth_smoke_test.go b/operator/test/e2e/auth_smoke_test.go
new file mode 100644
index 0000000..8ecef7c
--- /dev/null
+++ b/operator/test/e2e/auth_smoke_test.go
@@ -0,0 +1,155 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// Cross-namespace authSecretRef.
+//
+// The operator mirrors a Secret referenced by spec.l2Backend.resp.
+// authSecretRef into the LMCacheEngine's namespace, then injects
+// LMCACHE_RESP_USERNAME / LMCACHE_RESP_PASSWORD into the DaemonSet
+// container as env vars (NOT as CLI args). This spec asserts:
+//
+//  1. A managed copy of the source Secret appears in the engine's
+//     namespace at <engine-name>-resp-auth.
+//  2. The pod template references the local copy via env-var
+//     SecretKeyRef — never via container args.
+//  3. The literal Secret values never leak into container args
+//     (i.e. they wouldn't show up in `kubectl describe pod`).
+var _ = Describe("LMCacheEngine cross-namespace auth smoke (no-GPU)", Ordered, func() {
+	var (
+		ctx          context.Context
+		nsName       string
+		sourceNSName string
+		expectedUser = "tm-test-user"
+		expectedPass = "tm-test-password" // pragma: allowlist secret
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+		// Source namespace lives separately so we test true cross-NS
+		// mirroring rather than same-NS direct reference.
+		sourceNSName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+	})
+
+	It("mirrors a cross-namespace authSecretRef and uses env-var injection", func() {
+		By("creating the source Secret in the upstream namespace")
+		src := &corev1.Secret{
+			ObjectMeta: metav1.ObjectMeta{
+				Name:      "redis-auth",
+				Namespace: sourceNSName,
+			},
+			Data: map[string][]byte{
+				"username": []byte(expectedUser),
+				"password": []byte(expectedPass),
+			},
+		}
+		Expect(k8sClient.Create(ctx, src)).To(Succeed())
+
+		By("loading the fixture and pointing it at the source namespace")
+		lmc, err := utils.NewLMCFromFixture("lmc_with_redis_l2_authsecret.yaml", nsName, "")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(lmc.Spec.L2Backend).NotTo(BeNil())
+		Expect(lmc.Spec.L2Backend.RESP).NotTo(BeNil())
+		Expect(lmc.Spec.L2Backend.RESP.AuthSecretRef).NotTo(BeNil())
+		lmc.Spec.L2Backend.RESP.AuthSecretRef.Namespace = sourceNSName
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		managedSecretName := lmc.Name + "-resp-auth"
+
+		By("eventually a managed copy of the Secret appears in the engine namespace")
+		Eventually(func(g Gomega) {
+			got := &corev1.Secret{}
+			g.Expect(k8sClient.Get(ctx,
+				types.NamespacedName{Namespace: nsName, Name: managedSecretName},
+				got,
+			)).To(Succeed())
+			g.Expect(got.Data).To(HaveKeyWithValue("password", []byte(expectedPass)))
+			g.Expect(got.Data).To(HaveKeyWithValue("username", []byte(expectedUser)))
+		}, 30*time.Second, time.Second).Should(Succeed())
+
+		By("checking the DaemonSet wires creds through env-var SecretKeyRef")
+		ds := &appsv1.DaemonSet{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), ds)).To(Succeed())
+		Expect(ds.Spec.Template.Spec.Containers).To(HaveLen(1))
+		c := ds.Spec.Template.Spec.Containers[0]
+
+		passwordEnv := findEnvVar(c.Env, "LMCACHE_RESP_PASSWORD")
+		Expect(passwordEnv).NotTo(BeNil(), "expected LMCACHE_RESP_PASSWORD env var")
+		Expect(passwordEnv.Value).To(BeEmpty(),
+			"LMCACHE_RESP_PASSWORD must be sourced from a Secret, not a literal value")
+		Expect(passwordEnv.ValueFrom).NotTo(BeNil())
+		Expect(passwordEnv.ValueFrom.SecretKeyRef).NotTo(BeNil())
+		Expect(passwordEnv.ValueFrom.SecretKeyRef.Name).To(Equal(managedSecretName),
+			"password env var must reference the local managed Secret, not the source namespace")
+		Expect(passwordEnv.ValueFrom.SecretKeyRef.Key).To(Equal("password"))
+
+		usernameEnv := findEnvVar(c.Env, "LMCACHE_RESP_USERNAME")
+		Expect(usernameEnv).NotTo(BeNil(), "expected LMCACHE_RESP_USERNAME env var")
+		Expect(usernameEnv.ValueFrom).NotTo(BeNil())
+		Expect(usernameEnv.ValueFrom.SecretKeyRef).NotTo(BeNil())
+		Expect(usernameEnv.ValueFrom.SecretKeyRef.Name).To(Equal(managedSecretName))
+
+		By("ensuring the literal Secret values do NOT appear in container args")
+		// "kubectl describe pod" prints the args verbatim; if the
+		// operator inlined credentials the user/pass would leak there.
+		// Env-var injection (the contract) keeps them out of the args.
+		joinedArgs := strings.Join(c.Args, " ")
+		Expect(joinedArgs).NotTo(ContainSubstring(expectedUser))
+		Expect(joinedArgs).NotTo(ContainSubstring(expectedPass))
+	})
+})
+
+// findEnvVar returns a pointer to the named env var (so callers can
+// inspect ValueFrom) or nil if absent. We return *corev1.EnvVar rather
+// than the value type so a missing entry is unambiguously nil instead
+// of the zero struct, which would be indistinguishable from an empty
+// env var Value="".
+func findEnvVar(envs []corev1.EnvVar, name string) *corev1.EnvVar {
+	for i := range envs {
+		if envs[i].Name == name {
+			return &envs[i]
+		}
+	}
+	return nil
+}
diff --git a/operator/test/e2e/cacheblend_integration_smoke_test.go b/operator/test/e2e/cacheblend_integration_smoke_test.go
new file mode 100644
index 0000000..b4e2df7
--- /dev/null
+++ b/operator/test/e2e/cacheblend_integration_smoke_test.go
@@ -0,0 +1,252 @@
+//go:build e2e && e2e_gpu
+// +build e2e,e2e_gpu
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"regexp"
+	"strings"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/yaml"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// vLLM + CacheBlendEngine round-trip (e2e_gpu): verifies the full CacheBlend
+// operator integration on a GPU node.
+//
+// The flow exercises every moving part:
+//  1. A CacheBlendEngine reconciles into a node-local `lmcache server
+//     --engine-type blend` DaemonSet pod.
+//  2. A vLLM Deployment opts in to CacheBlend injection (label + engine
+//     annotation). The mutating webhook injects the CacheBlend vLLM flags
+//     (--attention-backend CUSTOM, --kv-transfer-config <engine>, etc.), the
+//     cb-plugin init container, hostIPC, and the private payload's pull secret.
+//  3. vLLM loads the CUSTOM attention backend (asserted on the injected args
+//     AND on vLLM's own startup banner), starts, and serves /v1/models.
+//  4. A completion request drives a forward pass, which makes vLLM's connector
+//     register its rope cache with the engine — the engine logs
+//     "Registered CB rope state for instance N".
+//  5. The completion returns HTTP 200.
+//
+// Because failurePolicy on the webhook is Ignore (fail-open), a missing webhook
+// would admit the vLLM pod UNMUTATED and silently degrade this to a non-blend
+// run. We defend against that by asserting the webhook's success stamp
+// (lmcache.ai/cacheblend-injected=true) and the injected arg directly off the
+// pod object — not just on runtime behaviour.
+//
+// Knobs:
+//   - VLLM_MODEL                    HF model id. Default Qwen/Qwen2.5-0.5B.
+//   - VLLM_IMAGE                    vLLM image. Default lmcache/vllm-openai:latest-nightly.
+//   - CACHEBLEND_ENGINE_IMAGE       blend server image. Default lmcache/vllm-openai:latest-nightly.
+//   - CACHEBLEND_PAYLOAD_IMAGE      PRIVATE plugin image. Default
+//     tensormesh/cacheblend-plugin:latest-nightly.
+//   - CACHEBLEND_REGISTRY_USER      Docker registry username for the payload image.
+//   - CACHEBLEND_REGISTRY_TOKEN     Docker registry password / PAT (read-only pull).
+//   - CACHEBLEND_REGISTRY_SERVER    Registry server. Default https://index.docker.io/v1/.
+//   - CACHEBLEND_BACKEND_LOG_PATTERN  Regex proving the CUSTOM backend loaded.
+//     Default `Using AttentionBackendEnum\.CUSTOM backend`.
+//   - SKIP_CACHEBLEND_INTEGRATION   "true" skips this spec.
+//
+// When CACHEBLEND_REGISTRY_USER/TOKEN are unset the spec Skips (the private
+// payload image cannot be pulled), so the suite stays green on clusters
+// without registry credentials.
+var _ = Describe("vLLM + CacheBlendEngine integration smoke (GPU)", Ordered, func() {
+	const pullSecretName = "cacheblend-registry"
+
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		if os.Getenv("SKIP_CACHEBLEND_INTEGRATION") == "true" {
+			Skip("SKIP_CACHEBLEND_INTEGRATION=true; skipping CacheBlend round-trip spec")
+		}
+		if os.Getenv("CACHEBLEND_REGISTRY_USER") == "" || os.Getenv("CACHEBLEND_REGISTRY_TOKEN") == "" {
+			Skip("CACHEBLEND_REGISTRY_USER/CACHEBLEND_REGISTRY_TOKEN unset; " +
+				"cannot pull the private cacheblend-plugin payload image")
+		}
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+		// The vLLM Deployment, the CacheBlendEngine, and the pull Secret are
+		// all in the test namespace, so namespace deletion (DeferCleanup in
+		// createTestNamespace) cleans everything up. No explicit teardown.
+	})
+
+	It("injects CacheBlend, registers rope state on the engine, and serves a completion", func() {
+		model := envDefault("VLLM_MODEL", "Qwen/Qwen2.5-0.5B")
+		// nightly by default: the engine, vLLM, and the latest-nightly payload
+		// plugin must sit in the same CacheBlend compatibility window.
+		vllmImage := envDefault("VLLM_IMAGE", "lmcache/vllm-openai:latest-nightly")
+		engineImage := envDefault("CACHEBLEND_ENGINE_IMAGE", "lmcache/vllm-openai:latest-nightly")
+		payloadImage := envDefault("CACHEBLEND_PAYLOAD_IMAGE", "tensormesh/cacheblend-plugin:latest-nightly")
+		backendLog := regexp.MustCompile(
+			envDefault("CACHEBLEND_BACKEND_LOG_PATTERN", `Using AttentionBackendEnum\.CUSTOM backend`))
+
+		By("creating the private-registry pull Secret from env credentials")
+		Expect(utils.CreateDockerConfigJSONSecret(
+			ctx, k8sClient, nsName, pullSecretName,
+			envDefault("CACHEBLEND_REGISTRY_SERVER", "https://index.docker.io/v1/"),
+			os.Getenv("CACHEBLEND_REGISTRY_USER"),
+			os.Getenv("CACHEBLEND_REGISTRY_TOKEN"),
+		)).To(Succeed())
+
+		By("applying the CacheBlendEngine")
+		cbe, err := utils.NewCBEFromFixture("cacheblendengine.yaml", nsName, "cb-integration")
+		Expect(err).NotTo(HaveOccurred())
+		setImageSpec(&cbe.Spec.Image, engineImage)
+		// The fixture always carries an injection block, but guard against a
+		// future fixture edit dropping it — a nil Injection here would panic
+		// rather than fail the spec cleanly.
+		if cbe.Spec.Injection == nil {
+			cbe.Spec.Injection = &lmcachev1alpha1.InjectionSpec{}
+		}
+		setImageSpec(&cbe.Spec.Injection.PayloadImage, payloadImage)
+		Expect(utils.ApplyCBE(ctx, k8sClient, cbe)).To(Succeed())
+
+		key := engineKey(nsName, cbe.Name)
+		Expect(utils.WaitCBEReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("waiting for the CacheBlend engine DaemonSet pod to become Ready")
+		// 8 min covers the cold pull of the engine image on a fresh GPU node.
+		enginePod, err := utils.WaitDaemonSetPodReady(ctx, k8sClient, key, 8*time.Minute)
+		Expect(err).NotTo(HaveOccurred(), "CacheBlend engine pod did not become Ready")
+
+		By("verifying the blend engine logged its ZMQ listening line")
+		Eventually(func() int {
+			return countLogLines(ctx, nsName, enginePod, cbServerListeningLine)
+		}, 60*time.Second, 2*time.Second).Should(BeNumerically(">=", 1),
+			"blend engine never logged 'LMCache ZMQ cache server is running' — server did not bind")
+
+		By("applying the vLLM Deployment that opts into CacheBlend injection")
+		vllmRaw, err := utils.LoadFixture("vllm_cacheblend_deployment.yaml")
+		Expect(err).NotTo(HaveOccurred())
+		vllmYAML := substituteVLLMPlaceholders(string(vllmRaw), nsName, cbe.Name, model, vllmImage)
+		vllmDeploy := &appsv1.Deployment{}
+		Expect(yaml.Unmarshal([]byte(vllmYAML), vllmDeploy)).To(Succeed())
+		Expect(k8sClient.Create(ctx, vllmDeploy)).To(Succeed())
+
+		By("verifying the mutating webhook injected CacheBlend into the vLLM pod")
+		// The mutation happens at admission, so the pod carries the stamp and
+		// the injected args as soon as it exists — no need to wait for Running.
+		Eventually(func(g Gomega) {
+			pod := firstPodForDeployment(ctx, nsName, vllmDeploy)
+			g.Expect(pod).NotTo(BeNil(), "no vLLM pod created yet")
+			g.Expect(pod.Annotations).To(HaveKeyWithValue("lmcache.ai/cacheblend-injected", "true"),
+				"webhook did not stamp cacheblend-injected=true; injection did not fire "+
+					"(skip-reason=%q)", pod.Annotations["lmcache.ai/cacheblend-skip-reason"])
+			args := vllmContainerArgs(pod)
+			g.Expect(argValue(args, "--attention-backend")).To(Equal("CUSTOM"),
+				"injected args missing '--attention-backend CUSTOM': %v", args)
+		}, 60*time.Second, 2*time.Second).Should(Succeed())
+
+		By("waiting for the vLLM Deployment to become Available (model load + connector handshake)")
+		// 15 min — cold image pull (~10GB) + payload init container pull +
+		// model config download + vLLM startup. /v1/models gates readiness.
+		// Fails fast (~seconds) if the private payload pull is wedged
+		// (bad/missing pull secret, wrong tag) rather than burning the timeout.
+		Expect(utils.WaitDeploymentAvailableOrImagePullError(
+			ctx, k8sClient,
+			types.NamespacedName{Namespace: nsName, Name: vllmDeploy.Name},
+			15*time.Minute,
+		)).To(Succeed(), "vLLM did not become Available — check pod events / logs")
+
+		vllmPod := firstPodForDeployment(ctx, nsName, vllmDeploy)
+		Expect(vllmPod).NotTo(BeNil(), "vLLM pod disappeared after the Deployment became Available")
+
+		By("verifying vLLM logged the CUSTOM attention backend banner")
+		Eventually(func() int {
+			return countLogLines(ctx, nsName, vllmPod.Name, backendLog)
+		}, 60*time.Second, 2*time.Second).Should(BeNumerically(">=", 1),
+			"vLLM never logged the CUSTOM attention backend banner (pattern %q) — "+
+				"the injected --attention-backend CUSTOM did not take effect", backendLog.String())
+
+		By("port-forwarding to the vLLM service for completion requests")
+		vllmCloser, vllmBaseURL, err := utils.PortForward(
+			utils.PortForwardSpec{Namespace: nsName, Target: "deployment/" + vllmDeploy.Name},
+			"0:8000",
+		)
+		Expect(err).NotTo(HaveOccurred())
+		defer vllmCloser()
+		Expect(utils.WaitHTTP200(ctx, vllmBaseURL+"/v1/models", 60*time.Second)).To(Succeed())
+
+		By("sending a /v1/completions request and asserting HTTP 200")
+		Expect(postCompletion(ctx, vllmBaseURL, model, buildLongPrompt())).To(Succeed())
+
+		By("verifying the engine logged 'Registered CB rope state for instance N'")
+		// The forward pass drives vLLM's connector to send CB_REGISTER_ROPE_V3,
+		// which the engine handles and logs. kubectl log streaming buffers a
+		// beat behind, so poll.
+		Eventually(func() int {
+			return countLogLines(ctx, nsName, enginePod, cbRopeRegisteredLine)
+		}, 60*time.Second, 2*time.Second).Should(BeNumerically(">=", 1),
+			"engine never logged 'Registered CB rope state' — the CacheBlend rope "+
+				"handshake from vLLM did not reach the engine")
+
+		_, _ = fmt.Fprintf(GinkgoWriter,
+			"CacheBlend round-trip satisfied (engine pod=%s, vLLM pod=%s)\n",
+			enginePod, vllmPod.Name)
+	})
+})
+
+// cbServerListeningLine matches the blend engine's "server is listening" INFO
+// line (server.py), proving the lmcache server bound its ZMQ socket.
+var cbServerListeningLine = regexp.MustCompile(`LMCache ZMQ cache server is running`)
+
+// cbRopeRegisteredLine matches the engine-side log emitted by
+// BlendV3.cb_register_rope on every CB_REGISTER_ROPE_V3 message
+// (modules/blend_v3.py). Its presence proves the vLLM connector negotiated
+// the CacheBlend rope handshake with the engine.
+var cbRopeRegisteredLine = regexp.MustCompile(`Registered CB rope state for instance \d+`)
+
+// setImageSpec rewrites an ImageSpec's repository+tag from a "repo:tag" image
+// reference (the env-knob form), allocating the ImageSpec if nil. A reference
+// with no tag defaults the tag to "latest". The split is on the LAST colon, so
+// it does not handle a registry-host:port prefix on an untagged reference —
+// the smoke knobs never use that form.
+func setImageSpec(spec **lmcachev1alpha1.ImageSpec, ref string) {
+	repo, tag := ref, "latest"
+	if i := strings.LastIndex(ref, ":"); i >= 0 && !strings.Contains(ref[i+1:], "/") {
+		repo, tag = ref[:i], ref[i+1:]
+	}
+	if *spec == nil {
+		*spec = &lmcachev1alpha1.ImageSpec{}
+	}
+	(*spec).Repository = &repo
+	(*spec).Tag = &tag
+}
+
+// firstPodForDeployment and vllmContainerArgs live in smoke_helpers_test.go so
+// the CPU-only LMCache injection smoke (build tag e2e, no e2e_gpu) can share
+// them.
diff --git a/operator/test/e2e/coordinator_registration_smoke_test.go b/operator/test/e2e/coordinator_registration_smoke_test.go
new file mode 100644
index 0000000..c36ebbb
--- /dev/null
+++ b/operator/test/e2e/coordinator_registration_smoke_test.go
@@ -0,0 +1,134 @@
+//go:build e2e && e2e_gpu
+// +build e2e,e2e_gpu
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/types"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// Coordinator registration (e2e_gpu): verifies the new LMCacheCoordinator CRD
+// end-to-end. The operator stands up the coordinator Deployment + Service, and a
+// GPU-scheduled LMCacheEngine whose spec sets coordinator.ref resolves to the
+// coordinator's in-cluster URL, registers on startup, and shows up in the
+// coordinator's /instances fleet listing.
+//
+// This needs a GPU node because the engine runs the real lmcache server (the
+// coordinator client only registers once the server's event loop starts). The
+// coordinator pod itself is CPU-only; it is pinned to the GPU node here purely so
+// both pods share the already-pulled lmcache image and the test stays fast.
+var _ = Describe("LMCacheCoordinator registration smoke (GPU)", Ordered, func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	const coordinatorName = "smoke-coordinator"
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+	})
+
+	It("registers a GPU engine with the coordinator via coordinator.ref", func() {
+		By("applying the LMCacheCoordinator")
+		gpuSelector := map[string]string{"nvidia.com/gpu.present": "true"}
+		coordinator := &lmcachev1alpha1.LMCacheCoordinator{
+			ObjectMeta: metav1.ObjectMeta{Name: coordinatorName, Namespace: nsName},
+			Spec: lmcachev1alpha1.LMCacheCoordinatorSpec{
+				// Co-locate on the GPU worker so the (large) lmcache image is
+				// pulled once and shared with the engine pod.
+				NodeSelector: gpuSelector,
+			},
+		}
+		Expect(k8sClient.Create(ctx, coordinator)).To(Succeed())
+
+		By("waiting for the coordinator Deployment to become Available")
+		// 12 min absorbs the cold pull of the ~10GB lmcache image.
+		Expect(utils.WaitDeploymentAvailable(
+			ctx, k8sClient,
+			types.NamespacedName{Namespace: nsName, Name: coordinatorName},
+			12*time.Minute,
+		)).To(Succeed(), "coordinator Deployment did not become Available")
+
+		By("applying a GPU LMCacheEngine that references the coordinator")
+		lmc, err := utils.NewLMCFromFixture("lmc_runtime.yaml", nsName, "coord-engine")
+		Expect(err).NotTo(HaveOccurred())
+		lmc.Spec.Coordinator = &lmcachev1alpha1.CoordinatorConnectionSpec{
+			Ref:              &corev1.LocalObjectReference{Name: coordinatorName},
+			L2EventReporting: boolPtr(true),
+		}
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("verifying the operator resolved coordinator.ref into --coordinator-url")
+		ds := &appsv1.DaemonSet{}
+		Expect(k8sClient.Get(ctx, key, ds)).To(Succeed())
+		wantURL := fmt.Sprintf("http://%s.%s.svc:9300", coordinatorName, nsName)
+		Expect(argValue(containerArgs(ds), "--coordinator-url")).To(Equal(wantURL))
+
+		By("waiting for the engine DaemonSet pod to become Ready")
+		_, err = utils.WaitDaemonSetPodReady(ctx, k8sClient, key, 10*time.Minute)
+		Expect(err).NotTo(HaveOccurred(), "LMCache engine pod did not become Ready")
+
+		By("port-forwarding to the coordinator Service")
+		closer, baseURL, err := utils.PortForward(
+			utils.PortForwardSpec{Namespace: nsName, Target: "service/" + coordinatorName},
+			"0:9300",
+		)
+		Expect(err).NotTo(HaveOccurred())
+		defer closer()
+		Expect(utils.WaitHTTP200(ctx, baseURL+"/healthz", 60*time.Second)).To(Succeed())
+
+		By("verifying the engine registered in the coordinator fleet")
+		// The server registers on startup; allow a short window after Ready.
+		Eventually(func(g Gomega) {
+			var resp struct {
+				Instances []struct {
+					InstanceID string `json:"instance_id"`
+					IP         string `json:"ip"`
+				} `json:"instances"`
+			}
+			g.Expect(utils.HTTPGetJSON(ctx, baseURL+"/instances", &resp)).To(Succeed())
+			g.Expect(resp.Instances).NotTo(BeEmpty(), "no instances registered with the coordinator")
+		}, 90*time.Second, 3*time.Second).Should(Succeed())
+	})
+})
+
+// boolPtr returns a pointer to b (local helper to avoid importing a ptr pkg).
+func boolPtr(b bool) *bool { return &b }
diff --git a/operator/test/e2e/crd_smoke_test.go b/operator/test/e2e/crd_smoke_test.go
new file mode 100644
index 0000000..543014d
--- /dev/null
+++ b/operator/test/e2e/crd_smoke_test.go
@@ -0,0 +1,252 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/types"
+
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// Validate that applying an LMCacheEngine produces the documented K8s
+// objects with the documented shape. Two fixtures exercise the same
+// assertions: lmc_minimal (defaults) and lmc_custom_port (port=6555,
+// chunkSize=128). The minimal fixture additionally diffs the connection
+// ConfigMap against a checked-in golden file so schema drift in
+// kv-transfer-config.json fails loudly.
+//
+// The first It block is a harness sanity check — kept intentionally
+// cheap so a broken helper fails before the richer reconciliation
+// specs run.
+var _ = Describe("LMCacheEngine smoke (no-GPU)", Ordered, func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+	})
+
+	It("reconciles a minimal CR and cleans up on delete (harness check)", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "smoke-harness")
+		Expect(err).NotTo(HaveOccurred())
+
+		By("applying the minimal LMCacheEngine")
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		By("waiting for the operator to observe the spec and validate the config")
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient,
+			engineKey(nsName, "smoke-harness"),
+			60*time.Second,
+		)).To(Succeed())
+
+		By("ensuring the connection ConfigMap has been produced")
+		cfg, err := utils.GetConnectionConfig(ctx, k8sClient, engineKey(nsName, "smoke-harness"))
+		Expect(err).NotTo(HaveOccurred())
+		Expect(cfg.KVConnector).To(Equal("LMCacheMPConnector"))
+		Expect(cfg.KVConnectorModulePath).To(Equal("lmcache.integration.vllm.lmcache_mp_connector"))
+
+		By("deleting the CR and waiting for owned objects to be garbage-collected")
+		Expect(utils.DeleteLMCAndWaitGC(ctx, k8sClient,
+			engineKey(nsName, "smoke-harness"),
+			60*time.Second,
+		)).To(Succeed())
+	})
+
+	It("reconciles a minimal CR into the documented K8s artifacts", func() {
+		// Use the fixture's own metadata.name so the golden file's
+		// hostname matches verbatim ("smoke-minimal.<ns>.svc...").
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(lmc.Name).To(Equal("smoke-minimal"))
+
+		By("applying the minimal LMCacheEngine")
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+
+		By("waiting for the operator to observe the spec")
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("validating the DaemonSet pod template shape")
+		ds := &appsv1.DaemonSet{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), ds)).To(Succeed())
+		assertDaemonSetShape(ds, 5555 /* default server port */)
+
+		By("validating the lookup Service shape")
+		svc := &corev1.Service{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), svc)).To(Succeed())
+		assertLookupServiceShape(svc, 5555)
+
+		By("validating the connection ConfigMap matches the documented contract")
+		cfg, err := utils.GetConnectionConfig(ctx, k8sClient, key)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(cfg.KVConnector).To(Equal("LMCacheMPConnector"))
+		Expect(cfg.KVConnectorModulePath).To(Equal("lmcache.integration.vllm.lmcache_mp_connector"))
+		Expect(cfg.KVRole).To(Equal("kv_both"))
+		Expect(cfg.KVConnectorExtraConfig.Host).To(Equal(
+			fmt.Sprintf("tcp://smoke-minimal.%s.svc.cluster.local", nsName)))
+		Expect(cfg.KVConnectorExtraConfig.Port).To(Equal("5555"))
+
+		By("diffing the raw kv-transfer-config.json against the golden snapshot")
+		assertGoldenKvTransferConfig(ctx, key, "kv_transfer_config_minimal.json", nsName)
+	})
+
+	It("propagates server.port and server.chunkSize into args, Service, and ConfigMap", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_custom_port.yaml", nsName, "")
+		Expect(err).NotTo(HaveOccurred())
+
+		By("applying the custom-port LMCacheEngine")
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+
+		By("waiting for the operator to observe the spec")
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("validating the DaemonSet pod template")
+		ds := &appsv1.DaemonSet{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), ds)).To(Succeed())
+		assertDaemonSetShape(ds, 6555 /* spec.server.port */)
+
+		args := containerArgs(ds)
+		Expect(argValue(args, "--port")).To(Equal("6555"))
+		Expect(argValue(args, "--chunk-size")).To(Equal("128"))
+
+		By("validating the lookup Service uses the custom port")
+		svc := &corev1.Service{}
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), svc)).To(Succeed())
+		assertLookupServiceShape(svc, 6555)
+
+		By("validating the ConfigMap reflects the custom port")
+		cfg, err := utils.GetConnectionConfig(ctx, k8sClient, key)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(cfg.KVConnectorExtraConfig.Port).To(Equal("6555"))
+	})
+})
+
+// assertDaemonSetShape verifies the operator's auto-injected pod-level
+// settings: hostIPC, runtimeClassName=nvidia, a container security context
+// that is non-privileged by default (privileged is opt-in via spec.privileged),
+// --host 0.0.0.0 always present in container args, and the absence of any
+// /dev/shm volume mount that would shadow the host's /dev/shm and break CUDA IPC.
+func assertDaemonSetShape(ds *appsv1.DaemonSet, expectedServerPort int32) {
+	GinkgoHelper()
+	pod := ds.Spec.Template.Spec
+	Expect(pod.HostIPC).To(BeTrue(), "pod.hostIPC must be true")
+	Expect(pod.RuntimeClassName).NotTo(BeNil(), "pod.runtimeClassName must be set")
+	Expect(*pod.RuntimeClassName).To(Equal("nvidia"))
+	Expect(pod.Containers).To(HaveLen(1))
+
+	c := pod.Containers[0]
+	Expect(c.SecurityContext).NotTo(BeNil(), "container.securityContext must be set")
+	Expect(c.SecurityContext.Privileged).NotTo(BeNil())
+	Expect(*c.SecurityContext.Privileged).To(BeFalse(),
+		"container.privileged must default to false (opt-in via spec.privileged)")
+	Expect(c.Args).To(ContainElements("--host", "0.0.0.0"))
+	Expect(argValue(c.Args, "--port")).To(Equal(fmt.Sprintf("%d", expectedServerPort)))
+
+	// /dev/shm is left to the host via hostIPC=true. An emptyDir mount
+	// would shadow it and break cudaIpcOpenMemHandle between LMCache
+	// and vLLM pods. Verify both sides: no volume mount AND no volume.
+	for _, vm := range c.VolumeMounts {
+		Expect(vm.MountPath).NotTo(Equal("/dev/shm"),
+			"unexpected /dev/shm volumeMount on lmcache container")
+	}
+	for _, v := range pod.Volumes {
+		// Some helm charts call this volume "shm" or "dshm"; rather
+		// than enumerate names we check for any volume mounted at
+		// /dev/shm via the loop above. This loop catches a different
+		// mistake: an emptyDir/Volume named after /dev/shm with no
+		// matching mount, which is harmless but unexpected.
+		if v.EmptyDir != nil {
+			Expect(v.Name).NotTo(Or(Equal("shm"), Equal("dshm"), Equal("dev-shm")),
+				"unexpected /dev/shm-style emptyDir volume present")
+		}
+	}
+}
+
+// assertLookupServiceShape checks the node-local discovery Service has
+// internalTrafficPolicy=Local (so kube-proxy routes only to the on-node
+// LMCache pod) and exposes the spec'd server port.
+func assertLookupServiceShape(svc *corev1.Service, expectedServerPort int32) {
+	GinkgoHelper()
+	Expect(svc.Spec.InternalTrafficPolicy).NotTo(BeNil())
+	Expect(*svc.Spec.InternalTrafficPolicy).To(Equal(corev1.ServiceInternalTrafficPolicyLocal))
+	var found bool
+	for _, p := range svc.Spec.Ports {
+		if p.Name == "server" {
+			found = true
+			Expect(p.Port).To(Equal(expectedServerPort))
+		}
+	}
+	Expect(found).To(BeTrue(), "lookup Service must expose a port named 'server'")
+}
+
+// assertGoldenKvTransferConfig compares the on-cluster ConfigMap data
+// to the embedded golden snapshot. The placeholder __NAMESPACE__ in the
+// golden file is substituted with the live test namespace before
+// comparison so the diff sees a single reproducible string.
+func assertGoldenKvTransferConfig(ctx context.Context, key types.NamespacedName, goldenName, namespace string) {
+	GinkgoHelper()
+	golden, err := utils.LoadGolden(goldenName)
+	Expect(err).NotTo(HaveOccurred(), "load golden %s", goldenName)
+	expected := strings.ReplaceAll(string(golden), "__NAMESPACE__", namespace)
+
+	cm := &corev1.ConfigMap{}
+	cmKey := types.NamespacedName{Namespace: key.Namespace, Name: key.Name + "-connection"}
+	Expect(k8sClient.Get(ctx, cmKey, cm)).To(Succeed())
+	actual, ok := cm.Data["kv-transfer-config.json"]
+	Expect(ok).To(BeTrue(), "ConfigMap missing kv-transfer-config.json")
+
+	// Normalize both sides through json.Unmarshal+Marshal to absorb any
+	// trailing-newline / line-ending differences while still catching
+	// genuine schema drift. We compare on the canonical re-encoding.
+	Expect(canonicalJSON(actual)).To(Equal(canonicalJSON(expected)),
+		"kv-transfer-config.json drift vs %s\nactual:\n%s\nexpected:\n%s",
+		goldenName, actual, expected)
+}
+
+func canonicalJSON(s string) string {
+	var v any
+	if err := json.Unmarshal([]byte(s), &v); err != nil {
+		// Return as-is so the caller's diff reveals the malformed input.
+		return s
+	}
+	out, _ := json.MarshalIndent(v, "", "  ")
+	return string(out)
+}
diff --git a/operator/test/e2e/e2e_suite_test.go b/operator/test/e2e/e2e_suite_test.go
new file mode 100644
index 0000000..9524ae6
--- /dev/null
+++ b/operator/test/e2e/e2e_suite_test.go
@@ -0,0 +1,182 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"testing"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	"k8s.io/apimachinery/pkg/util/wait"
+	"k8s.io/client-go/kubernetes/scheme"
+	ctrl "sigs.k8s.io/controller-runtime"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+var (
+	// managerImage is the manager image used by build / load / deploy.
+	// Honors the IMG env var so test-e2e-cluster can point at an image
+	// already pushed to a registry the target cluster pulls from.
+	managerImage = envDefault("IMG", "example.com/operator:v0.0.1")
+	// skipImageLoad disables the Kind-only docker-build + kind-load
+	// steps. Set SMOKE_SKIP_IMAGE_LOAD=true when running against an
+	// existing cluster (OpenShift, EKS, k3s, etc.) where the image has
+	// already been pushed to a reachable registry.
+	skipImageLoad = os.Getenv("SMOKE_SKIP_IMAGE_LOAD") == "true"
+	// k8sClient is the typed controller-runtime client used by smoke specs.
+	// Initialised once in BeforeSuite after CRDs are installed; spec files
+	// read it directly without rebuilding their own client.
+	k8sClient client.Client
+	// certManagerInstalledBySuite records whether BeforeSuite installed
+	// cert-manager (vs. finding it pre-installed). AfterSuite only uninstalls
+	// what the suite installed, so a shared cluster's cert-manager is preserved.
+	certManagerInstalledBySuite bool
+)
+
+// envDefault returns os.Getenv(key) or def if the env var is unset/empty.
+// Pulled out as a helper so package-level var initialisers stay readable.
+func envDefault(key, def string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return def
+}
+
+// TestE2E runs the e2e test suite to validate the solution in an isolated environment.
+// Requires Kind (or an existing cluster reachable via the current kubeconfig).
+func TestE2E(t *testing.T) {
+	RegisterFailHandler(Fail)
+	_, _ = fmt.Fprintf(GinkgoWriter, "Starting operator e2e test suite\n")
+	RunSpecs(t, "e2e suite")
+}
+
+var _ = BeforeSuite(func() {
+	_, _ = fmt.Fprintf(GinkgoWriter, "manager image: %s (skipImageLoad=%v)\n",
+		managerImage, skipImageLoad)
+
+	// cert-manager must exist before `make deploy` applies the operator's
+	// Issuer/Certificate and the CA-injected mutating webhook. Install it up
+	// front (before the slow image build/load) so its webhook endpoints are
+	// warm by the time we deploy. Skip when the cluster already ships it.
+	By("ensuring cert-manager is installed (required by the operator's webhook serving cert)")
+	if utils.IsCertManagerCRDsInstalled() {
+		By("cert-manager CRDs already present; skipping install")
+	} else {
+		Expect(utils.InstallCertManager()).To(Succeed(), "Failed to install cert-manager")
+		certManagerInstalledBySuite = true
+	}
+
+	if skipImageLoad {
+		// Existing-cluster path: the user pushed the image to a
+		// registry before invoking the suite. We can't sideload, and
+		// we don't rebuild because rebuilds wouldn't propagate to the
+		// pushed copy anyway. The deploy step below uses managerImage
+		// as the registry URL.
+		By("skipping docker-build + kind-load (SMOKE_SKIP_IMAGE_LOAD=true)")
+	} else {
+		By("building the manager image")
+		_, err := utils.RunMake("docker-build", fmt.Sprintf("IMG=%s", managerImage))
+		Expect(err).NotTo(HaveOccurred(), "Failed to build the manager image")
+
+		By("loading the manager image on Kind")
+		err = utils.LoadImageToKindClusterWithName(managerImage)
+		Expect(err).NotTo(HaveOccurred(), "Failed to load the manager image into Kind")
+	}
+
+	By("installing CRDs")
+	_, err := utils.RunMake("install")
+	Expect(err).NotTo(HaveOccurred(), "Failed to install CRDs")
+
+	By("deploying the controller-manager")
+	_, err = utils.RunMake("deploy", fmt.Sprintf("IMG=%s", managerImage))
+	Expect(err).NotTo(HaveOccurred(), "Failed to deploy the controller-manager")
+
+	By("labeling the operator namespace with the restricted Pod Security profile")
+	labelCmd := exec.Command("kubectl", "label", "--overwrite", "ns",
+		"lmcache-operator-system",
+		"pod-security.kubernetes.io/enforce=restricted",
+	)
+	_, err = labelCmd.CombinedOutput()
+	Expect(err).NotTo(HaveOccurred(), "Failed to label operator namespace")
+
+	By("registering custom types in the scheme")
+	Expect(lmcachev1alpha1.AddToScheme(scheme.Scheme)).To(Succeed())
+	Expect(monitoringv1.AddToScheme(scheme.Scheme)).To(Succeed())
+
+	By("building the typed Kubernetes client")
+	cfg, err := ctrl.GetConfig()
+	Expect(err).NotTo(HaveOccurred(), "Failed to load kubeconfig")
+	k8sClient, err = client.New(cfg, client.Options{Scheme: scheme.Scheme})
+	Expect(err).NotTo(HaveOccurred(), "Failed to construct typed client")
+
+	By("waiting for the controller-manager Deployment to become Available")
+	Expect(waitDeploymentAvailable(context.Background(),
+		"lmcache-operator-system",
+		"lmcache-operator-controller-manager",
+		3*time.Minute,
+	)).To(Succeed(), "Controller-manager Deployment did not become Available")
+})
+
+var _ = AfterSuite(func() {
+	By("undeploying the controller-manager")
+	if _, err := utils.RunMake("undeploy", "ignore-not-found=true"); err != nil {
+		_, _ = fmt.Fprintf(GinkgoWriter, "warning: undeploy failed: %v\n", err)
+	}
+
+	By("uninstalling CRDs")
+	if _, err := utils.RunMake("uninstall", "ignore-not-found=true"); err != nil {
+		_, _ = fmt.Fprintf(GinkgoWriter, "warning: uninstall failed: %v\n", err)
+	}
+
+	if certManagerInstalledBySuite {
+		By("uninstalling cert-manager")
+		utils.UninstallCertManager()
+	}
+})
+
+// waitDeploymentAvailable polls a Deployment's status until the
+// Available condition is True, or until ctx is cancelled / timeout
+// elapses. Uses kubectl rather than the typed client because the typed
+// client only knows the schema we registered, not Deployments.
+func waitDeploymentAvailable(ctx context.Context, namespace, name string, timeout time.Duration) error {
+	return wait.PollUntilContextTimeout(ctx, 2*time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		// kubectl exits 0 with empty output if the condition isn't met
+		// yet, and 0 with "True" when it is — so we run it and inspect
+		// stdout rather than relying on exit codes.
+		cmd := exec.CommandContext(ctx, "kubectl", "get", "deployment", name,
+			"-n", namespace,
+			"-o", "jsonpath={.status.conditions[?(@.type=='Available')].status}")
+		out, err := cmd.Output()
+		if err != nil {
+			return false, nil
+		}
+		return string(out) == "True", nil
+	})
+}
diff --git a/operator/test/e2e/e2e_test.go b/operator/test/e2e/e2e_test.go
new file mode 100644
index 0000000..0d58620
--- /dev/null
+++ b/operator/test/e2e/e2e_test.go
@@ -0,0 +1,269 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"crypto/tls"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// namespace where the project is deployed in
+const namespace = "lmcache-operator-system"
+
+// serviceAccountName created for the project
+const serviceAccountName = "lmcache-operator-controller-manager"
+
+// metricsServiceName is the name of the metrics service of the project
+const metricsServiceName = "lmcache-operator-controller-manager-metrics-service"
+
+// metricsRoleBindingName is the name of the RBAC that will be created to allow get the metrics data
+const metricsRoleBindingName = "operator-metrics-binding"
+
+var _ = Describe("Manager", Ordered, func() {
+	var controllerPodName string
+
+	// Suite-level BeforeSuite (in integration_suite_test.go) handles building/loading
+	// the manager image, installing CRDs, deploying the controller, and
+	// labeling the operator namespace. This Describe block focuses on the
+	// metrics-endpoint contract; per-test setup runs in AfterEach.
+
+	// After each test, check for failures and collect logs, events,
+	// and pod descriptions for debugging.
+	AfterEach(func() {
+		specReport := CurrentSpecReport()
+		if specReport.Failed() {
+			By("Fetching controller manager pod logs")
+			cmd := exec.Command("kubectl", "logs", controllerPodName, "-n", namespace)
+			controllerLogs, err := utils.Run(cmd)
+			if err == nil {
+				_, _ = fmt.Fprintf(GinkgoWriter, "Controller logs:\n %s", controllerLogs)
+			} else {
+				_, _ = fmt.Fprintf(GinkgoWriter, "Failed to get Controller logs: %s", err)
+			}
+
+			By("Fetching Kubernetes events")
+			cmd = exec.Command("kubectl", "get", "events", "-n", namespace, "--sort-by=.lastTimestamp")
+			eventsOutput, err := utils.Run(cmd)
+			if err == nil {
+				_, _ = fmt.Fprintf(GinkgoWriter, "Kubernetes events:\n%s", eventsOutput)
+			} else {
+				_, _ = fmt.Fprintf(GinkgoWriter, "Failed to get Kubernetes events: %s", err)
+			}
+
+			By("Fetching controller manager pod description")
+			cmd = exec.Command("kubectl", "describe", "pod", controllerPodName, "-n", namespace)
+			podDescription, err := utils.Run(cmd)
+			if err == nil {
+				fmt.Println("Pod description:\n", podDescription)
+			} else {
+				fmt.Println("Failed to describe controller pod")
+			}
+		}
+	})
+
+	SetDefaultEventuallyTimeout(2 * time.Minute)
+	SetDefaultEventuallyPollingInterval(time.Second)
+
+	Context("Manager", func() {
+		It("should run successfully", func() {
+			By("validating that the controller-manager pod is running as expected")
+			verifyControllerUp := func(g Gomega) {
+				// Get the name of the controller-manager pod
+				cmd := exec.Command("kubectl", "get",
+					"pods", "-l", "control-plane=controller-manager",
+					"-o", "go-template={{ range .items }}"+
+						"{{ if not .metadata.deletionTimestamp }}"+
+						"{{ .metadata.name }}"+
+						"{{ \"\\n\" }}{{ end }}{{ end }}",
+					"-n", namespace,
+				)
+
+				podOutput, err := utils.Run(cmd)
+				g.Expect(err).NotTo(HaveOccurred(), "Failed to retrieve controller-manager pod information")
+				podNames := utils.GetNonEmptyLines(podOutput)
+				g.Expect(podNames).To(HaveLen(1), "expected 1 controller pod running")
+				controllerPodName = podNames[0]
+				g.Expect(controllerPodName).To(ContainSubstring("controller-manager"))
+
+				// Validate the pod's status
+				cmd = exec.Command("kubectl", "get",
+					"pods", controllerPodName, "-o", "jsonpath={.status.phase}",
+					"-n", namespace,
+				)
+				output, err := utils.Run(cmd)
+				g.Expect(err).NotTo(HaveOccurred())
+				g.Expect(output).To(Equal("Running"), "Incorrect controller-manager pod status")
+			}
+			Eventually(verifyControllerUp).Should(Succeed())
+		})
+
+		It("should ensure the metrics endpoint is serving metrics", func() {
+			By("creating a ClusterRoleBinding for the service account to allow access to metrics")
+			cmd := exec.Command("kubectl", "create", "clusterrolebinding", metricsRoleBindingName,
+				"--clusterrole=lmcache-operator-metrics-reader",
+				fmt.Sprintf("--serviceaccount=%s:%s", namespace, serviceAccountName),
+			)
+			_, err := utils.Run(cmd)
+			Expect(err).NotTo(HaveOccurred(), "Failed to create ClusterRoleBinding")
+
+			By("validating that the metrics service is available")
+			cmd = exec.Command("kubectl", "get", "service", metricsServiceName, "-n", namespace)
+			_, err = utils.Run(cmd)
+			Expect(err).NotTo(HaveOccurred(), "Metrics service should exist")
+
+			By("getting the service account token")
+			token, err := serviceAccountToken()
+			Expect(err).NotTo(HaveOccurred())
+			Expect(token).NotTo(BeEmpty())
+
+			By("ensuring the controller pod is ready")
+			verifyControllerPodReady := func(g Gomega) {
+				cmd := exec.Command("kubectl", "get", "pod", controllerPodName, "-n", namespace,
+					"-o", "jsonpath={.status.conditions[?(@.type=='Ready')].status}")
+				output, err := utils.Run(cmd)
+				g.Expect(err).NotTo(HaveOccurred())
+				g.Expect(output).To(Equal("True"), "Controller pod not ready")
+			}
+			Eventually(verifyControllerPodReady, 3*time.Minute, time.Second).Should(Succeed())
+
+			By("verifying that the controller manager is serving the metrics server")
+			verifyMetricsServerStarted := func(g Gomega) {
+				cmd := exec.Command("kubectl", "logs", controllerPodName, "-n", namespace)
+				output, err := utils.Run(cmd)
+				g.Expect(err).NotTo(HaveOccurred())
+				g.Expect(output).To(ContainSubstring("Serving metrics server"),
+					"Metrics server not yet started")
+			}
+			Eventually(verifyMetricsServerStarted, 3*time.Minute, time.Second).Should(Succeed())
+
+			// +kubebuilder:scaffold:e2e-metrics-webhooks-readiness
+
+			By("waiting for metrics service to have endpoints")
+			verifyEndpoints := func(g Gomega) {
+				cmd := exec.Command("kubectl", "get", "endpoints", metricsServiceName, "-n", namespace,
+					"-o", "jsonpath={.subsets[0].addresses[0].ip}")
+				output, err := utils.Run(cmd)
+				g.Expect(err).NotTo(HaveOccurred())
+				g.Expect(output).NotTo(BeEmpty(), "metrics service has no endpoints")
+			}
+			Eventually(verifyEndpoints, 5*time.Minute, time.Second).Should(Succeed())
+
+			By("port-forwarding the metrics service to localhost")
+			portForwardCmd := exec.Command("kubectl", "port-forward",
+				fmt.Sprintf("svc/%s", metricsServiceName),
+				"8443:8443", "-n", namespace)
+			portForwardCmd.Dir, _ = utils.GetProjectDir()
+			Expect(portForwardCmd.Start()).To(Succeed(), "Failed to start port-forward")
+			defer func() { _ = portForwardCmd.Process.Kill() }()
+
+			By("verifying metrics endpoint returns 200 via port-forward")
+			verifyMetrics := func(g Gomega) {
+				client := &http.Client{
+					Transport: &http.Transport{
+						TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, // #nosec G402
+					},
+				}
+				req, err := http.NewRequestWithContext(context.Background(),
+					http.MethodGet, "https://localhost:8443/metrics", nil)
+				g.Expect(err).NotTo(HaveOccurred())
+				req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", token))
+
+				resp, err := client.Do(req)
+				g.Expect(err).NotTo(HaveOccurred())
+				defer resp.Body.Close()
+				g.Expect(resp.StatusCode).To(Equal(http.StatusOK), "metrics endpoint returned non-200 status")
+			}
+			Eventually(verifyMetrics, 5*time.Minute, time.Second).Should(Succeed())
+		})
+
+		// +kubebuilder:scaffold:e2e-webhooks-checks
+
+		// TODO: Customize the e2e test suite with scenarios specific to your project.
+		// Consider applying sample/CR(s) and check their status and/or verifying
+		// the reconciliation by using the metrics, i.e.:
+		// metricsOutput, err := getMetricsOutput()
+		// Expect(err).NotTo(HaveOccurred(), "Failed to retrieve logs from curl pod")
+		// Expect(metricsOutput).To(ContainSubstring(
+		//    fmt.Sprintf(`controller_runtime_reconcile_total{controller="%s",result="success"} 1`,
+		//    strings.ToLower(<Kind>),
+		// ))
+	})
+})
+
+// serviceAccountToken returns a token for the specified service account in the given namespace.
+// It uses the Kubernetes TokenRequest API to generate a token by directly sending a request
+// and parsing the resulting token from the API response.
+func serviceAccountToken() (string, error) {
+	const tokenRequestRawString = `{
+		"apiVersion": "authentication.k8s.io/v1",
+		"kind": "TokenRequest"
+	}`
+
+	// Temporary file to store the token request
+	secretName := fmt.Sprintf("%s-token-request", serviceAccountName)
+	tokenRequestFile := filepath.Join("/tmp", secretName)
+	err := os.WriteFile(tokenRequestFile, []byte(tokenRequestRawString), os.FileMode(0o644))
+	if err != nil {
+		return "", err
+	}
+
+	var out string
+	verifyTokenCreation := func(g Gomega) {
+		// Execute kubectl command to create the token
+		cmd := exec.Command("kubectl", "create", "--raw", fmt.Sprintf(
+			"/api/v1/namespaces/%s/serviceaccounts/%s/token",
+			namespace,
+			serviceAccountName,
+		), "-f", tokenRequestFile)
+
+		output, err := cmd.CombinedOutput()
+		g.Expect(err).NotTo(HaveOccurred())
+
+		// Parse the JSON output to extract the token
+		var token tokenRequest
+		err = json.Unmarshal(output, &token)
+		g.Expect(err).NotTo(HaveOccurred())
+
+		out = token.Status.Token
+	}
+	Eventually(verifyTokenCreation).Should(Succeed())
+
+	return out, err
+}
+
+// tokenRequest is a simplified representation of the Kubernetes TokenRequest API response,
+// containing only the token field that we need to extract.
+type tokenRequest struct {
+	Status struct {
+		Token string `json:"token"`
+	} `json:"status"`
+}
diff --git a/operator/test/e2e/field_coverage_smoke_test.go b/operator/test/e2e/field_coverage_smoke_test.go
new file mode 100644
index 0000000..33089af
--- /dev/null
+++ b/operator/test/e2e/field_coverage_smoke_test.go
@@ -0,0 +1,133 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	monitoringv1 "github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1"
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/api/resource"
+	"k8s.io/apimachinery/pkg/types"
+
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// Field coverage smoke checks that non-default spec fields flow
+// through to the reconciled K8s objects.
+//
+//   - ServiceMonitor:    enabling prometheus.serviceMonitor produces a
+//     ServiceMonitor CR with the configured labels. Auto-skipped when
+//     the Prometheus Operator CRDs are absent.
+//   - extraArgs:         the user's --max-workers 4 wins over the
+//     operator's auto-generated --max-workers 1 (extraArgs are
+//     appended LAST by contract).
+//   - resourceOverrides: an explicit resourceOverrides block fully
+//     replaces the auto-computed memory request.
+var _ = Describe("LMCacheEngine field coverage smoke (no-GPU)", Ordered, func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+	})
+
+	It("creates a ServiceMonitor with the configured labels", func() {
+		if !serviceMonitorCRDInstalled() {
+			Skip("monitoring.coreos.com ServiceMonitor CRD not installed; skipping ServiceMonitor spec")
+		}
+
+		lmc, err := utils.NewLMCFromFixture("lmc_servicemonitor.yaml", nsName, "")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("eventually a ServiceMonitor exists with the configured labels")
+		Eventually(func(g Gomega) {
+			sm := &monitoringv1.ServiceMonitor{}
+			g.Expect(k8sClient.Get(ctx, types.NamespacedName(key), sm)).To(Succeed())
+			g.Expect(sm.Labels).To(HaveKeyWithValue("release", "kube-prometheus-stack"))
+			g.Expect(sm.Spec.Endpoints).NotTo(BeEmpty())
+			g.Expect(sm.Spec.Endpoints[0].Port).To(Equal("metrics"))
+			g.Expect(string(sm.Spec.Endpoints[0].Interval)).To(Equal("30s"))
+		}, 30*time.Second, time.Second).Should(Succeed())
+	})
+
+	It("lets spec.extraArgs override the auto-generated --max-workers", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "fields-extraargs")
+		Expect(err).NotTo(HaveOccurred())
+		lmc.Spec.ExtraArgs = []string{"--max-workers", "4"}
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("checking the DaemonSet container args show --max-workers=4 wins")
+		Eventually(func(g Gomega) {
+			ds := &appsv1.DaemonSet{}
+			g.Expect(k8sClient.Get(ctx, types.NamespacedName(key), ds)).To(Succeed())
+			args := containerArgs(ds)
+			// Both occurrences should be present — the auto-generated 1
+			// and the override 4 — so we can prove the override is
+			// strictly the LAST one rather than a clobber of the first.
+			g.Expect(args).To(ContainElements("--max-workers", "1", "--max-workers", "4"))
+			g.Expect(argValueLast(args, "--max-workers")).To(Equal("4"))
+		}, 30*time.Second, time.Second).Should(Succeed())
+	})
+
+	It("lets spec.resourceOverrides replace the auto-computed memory", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "fields-resourceoverride")
+		Expect(err).NotTo(HaveOccurred())
+		lmc.Spec.ResourceOverrides = &corev1.ResourceRequirements{
+			Requests: corev1.ResourceList{
+				corev1.ResourceMemory: resource.MustParse("70Gi"),
+			},
+		}
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("checking the DaemonSet container resources reflect the override")
+		Eventually(func(g Gomega) {
+			ds := &appsv1.DaemonSet{}
+			g.Expect(k8sClient.Get(ctx, types.NamespacedName(key), ds)).To(Succeed())
+			g.Expect(ds.Spec.Template.Spec.Containers).To(HaveLen(1))
+			req := ds.Spec.Template.Spec.Containers[0].Resources.Requests
+			g.Expect(req).To(HaveKey(corev1.ResourceMemory))
+			memQty := req[corev1.ResourceMemory]
+			g.Expect(memQty.String()).To(Equal("70Gi"))
+		}, 30*time.Second, time.Second).Should(Succeed())
+	})
+})
diff --git a/operator/test/e2e/lifecycle_smoke_test.go b/operator/test/e2e/lifecycle_smoke_test.go
new file mode 100644
index 0000000..46f119d
--- /dev/null
+++ b/operator/test/e2e/lifecycle_smoke_test.go
@@ -0,0 +1,146 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/types"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// Lifecycle smoke covers the three CR-edit scenarios:
+//
+//   - Update propagation: patching spec.server.port flows into the
+//     ConfigMap data and DaemonSet container args.
+//   - Finalizer cleanup:  deleting the CR removes every owned object
+//     within 60s; anything longer signals a stuck finalizer (a real
+//     bug we want to catch).
+//   - Invalid spec:       l1.sizeGB=-1 is rejected by the API server
+//     at admission time; the controller never sees it and no
+//     DaemonSet/Service is created.
+var _ = Describe("LMCacheEngine lifecycle smoke (no-GPU)", Ordered, func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+	})
+
+	It("patches spec.server.port and the new value flows to ConfigMap and DaemonSet", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "lifecycle-update")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("baseline: ConfigMap and DaemonSet show the default port 5555")
+		baseCfg, err := utils.GetConnectionConfig(ctx, k8sClient, key)
+		Expect(err).NotTo(HaveOccurred())
+		Expect(baseCfg.KVConnectorExtraConfig.Port).To(Equal("5555"))
+
+		By("patching spec.server.port from 5555 to 6555")
+		Expect(utils.PatchLMCSpec(ctx, k8sClient, types.NamespacedName(key),
+			func(spec *lmcachev1alpha1.LMCacheEngineSpec) {
+				if spec.Server == nil {
+					spec.Server = &lmcachev1alpha1.ServerSpec{}
+				}
+				newPort := int32(6555)
+				spec.Server.Port = &newPort
+			},
+		)).To(Succeed())
+
+		By("eventually the ConfigMap reflects the new port")
+		Eventually(func(g Gomega) {
+			cfg, err := utils.GetConnectionConfig(ctx, k8sClient, key)
+			g.Expect(err).NotTo(HaveOccurred())
+			g.Expect(cfg.KVConnectorExtraConfig.Port).To(Equal("6555"))
+		}, 60*time.Second, time.Second).Should(Succeed())
+
+		By("eventually the DaemonSet container args contain the new port")
+		Eventually(func(g Gomega) {
+			ds := &appsv1.DaemonSet{}
+			g.Expect(k8sClient.Get(ctx, types.NamespacedName(key), ds)).To(Succeed())
+			g.Expect(argValue(containerArgs(ds), "--port")).To(Equal("6555"))
+		}, 60*time.Second, time.Second).Should(Succeed())
+	})
+
+	It("deletes the CR and garbage-collects DaemonSet, Service, and ConfigMap within 60s", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "lifecycle-delete")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("ensuring the owned objects are present before deletion")
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), &appsv1.DaemonSet{})).To(Succeed())
+		Expect(k8sClient.Get(ctx, types.NamespacedName(key), &corev1.Service{})).To(Succeed())
+		Expect(k8sClient.Get(ctx,
+			types.NamespacedName{Namespace: key.Namespace, Name: key.Name + "-connection"},
+			&corev1.ConfigMap{},
+		)).To(Succeed())
+
+		By("deleting the CR — finalizer + owner refs must clean up everything in 60s")
+		Expect(utils.DeleteLMCAndWaitGC(ctx, k8sClient, types.NamespacedName(key), 60*time.Second)).To(Succeed())
+	})
+
+	It("rejects l1.sizeGB=-1 at admission and creates no owned objects", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "lifecycle-invalid")
+		Expect(err).NotTo(HaveOccurred())
+		lmc.Spec.L1.SizeGB = -1
+
+		By("attempting to create the CR — API server must reject with 422 Invalid")
+		applyErr := utils.ApplyLMC(ctx, k8sClient, lmc)
+		Expect(applyErr).To(HaveOccurred(), "expected API server to reject sizeGB=-1")
+		Expect(apierrors.IsInvalid(applyErr)).To(BeTrue(),
+			"expected an Invalid (422) status error, got: %v", applyErr)
+
+		key := engineKey(nsName, "lifecycle-invalid")
+
+		By("ensuring no LMCacheEngine, DaemonSet, or Service was created")
+		Expect(apierrors.IsNotFound(
+			k8sClient.Get(ctx, types.NamespacedName(key), &lmcachev1alpha1.LMCacheEngine{}),
+		)).To(BeTrue(), "rejected CR must not appear in the API")
+		Expect(apierrors.IsNotFound(
+			k8sClient.Get(ctx, types.NamespacedName(key), &appsv1.DaemonSet{}),
+		)).To(BeTrue(), "no DaemonSet may exist for a rejected CR")
+		Expect(apierrors.IsNotFound(
+			k8sClient.Get(ctx, types.NamespacedName(key), &corev1.Service{}),
+		)).To(BeTrue(), "no Service may exist for a rejected CR")
+	})
+})
diff --git a/operator/test/e2e/lmcache_injection_smoke_test.go b/operator/test/e2e/lmcache_injection_smoke_test.go
new file mode 100644
index 0000000..6355c2f
--- /dev/null
+++ b/operator/test/e2e/lmcache_injection_smoke_test.go
@@ -0,0 +1,220 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	"sigs.k8s.io/yaml"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// LMCacheEngine injection webhook smoke (M1, CPU-only): proves the mutating
+// webhook wires an opted-in vLLM pod to an LMCacheEngine end-to-end in a real
+// cluster — the piece the handler unit tests cannot cover (the webhook
+// registration, the objectSelector patch, RBAC, and the live connection
+// ConfigMap read).
+//
+// The mutation happens at admission, so the pod carries the stamp and injected
+// args/env the moment it exists — no GPU, no model load, no pod readiness
+// required. Because failurePolicy is Ignore (fail-open), a broken webhook would
+// admit the pod UNMUTATED and silently degrade to a non-cached run; we defend
+// against that by asserting the success stamp and the injected wiring directly
+// off the pod object.
+var _ = Describe("LMCacheEngine injection webhook smoke", func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+		// The LMCacheEngine and the vLLM Deployment are both in the test
+		// namespace, cleaned up by the namespace's DeferCleanup. No teardown.
+	})
+
+	It("stamps the vLLM pod and injects --kv-transfer-config + hostIPC + PYTHONHASHSEED", func() {
+		By("applying a minimal LMCacheEngine")
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "inject-smoke")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("waiting for the <engine>-connection ConfigMap (the webhook reads it at admission)")
+		// The Deployment must be created AFTER the ConfigMap exists: admission is
+		// one-shot at pod CREATE, so a pod admitted before the ConfigMap exists
+		// would be permanently unstamped (the webhook would fail open).
+		connName := fmt.Sprintf("%s-connection", lmc.Name)
+		Eventually(func() error {
+			return k8sClient.Get(ctx, engineKey(nsName, connName), &corev1.ConfigMap{})
+		}, 30*time.Second, 2*time.Second).Should(Succeed(),
+			"engine connection ConfigMap %q never appeared", connName)
+
+		By("creating the opted-in vLLM Deployment")
+		raw, err := utils.LoadFixture("vllm_lmcache_injection_deployment.yaml")
+		Expect(err).NotTo(HaveOccurred())
+		yamlText := strings.NewReplacer(
+			"__NAMESPACE__", nsName,
+			"__ENGINE_NAME__", lmc.Name,
+		).Replace(string(raw))
+		dep := &appsv1.Deployment{}
+		Expect(yaml.Unmarshal([]byte(yamlText), dep)).To(Succeed())
+		Expect(k8sClient.Create(ctx, dep)).To(Succeed())
+
+		By("verifying the mutating webhook injected LMCache into the vLLM pod")
+		Eventually(func(g Gomega) {
+			pod := firstPodForDeployment(ctx, nsName, dep)
+			g.Expect(pod).NotTo(BeNil(), "no vLLM pod created yet")
+			g.Expect(pod.Annotations).To(HaveKeyWithValue("lmcache.ai/lmcache-injected", "true"),
+				"webhook did not stamp lmcache-injected=true; injection did not fire "+
+					"(skip-reason=%q)", pod.Annotations["lmcache.ai/lmcache-skip-reason"])
+			g.Expect(pod.Spec.HostIPC).To(BeTrue(), "webhook did not inject hostIPC=true")
+
+			args := vllmContainerArgs(pod)
+			g.Expect(argValue(args, "--kv-transfer-config")).To(ContainSubstring("LMCacheMPConnector"),
+				"injected --kv-transfer-config missing the LMCacheMPConnector JSON: %v", args)
+			g.Expect(podEnvValue(pod, "vllm", "PYTHONHASHSEED")).To(Equal("0"),
+				"webhook did not inject PYTHONHASHSEED=0")
+		}, 60*time.Second, 2*time.Second).Should(Succeed())
+
+		_, _ = fmt.Fprintf(GinkgoWriter, "LMCache injection smoke satisfied (engine=%s)\n", lmc.Name)
+	})
+
+	It("stages the lmcache payload when injection.payloadImage is set", func() {
+		// Fixed staging contract the webhook injects (kept in lockstep with
+		// internal/webhook/lmcache_inject_builders.go; the e2e package cannot
+		// import those internal constants, so assert the observable literals).
+		const (
+			payloadRepo  = "registry.example.com/lmcache/lmcache-payload"
+			payloadTag   = "e2e"
+			payloadRef   = payloadRepo + ":" + payloadTag
+			pullSecret   = "lmcache-payload-pull"
+			initName     = "lmcache-payload-stage"
+			payloadVol   = "lmcache-payload"
+			payloadMount = "/lmcache-payload"
+			sharedDirEnv = "SHARED_DIR"
+		)
+
+		By("applying an LMCacheEngine with injection.payloadImage set")
+		lmc, err := utils.NewLMCFromFixture("lmc_minimal.yaml", nsName, "inject-payload-smoke")
+		Expect(err).NotTo(HaveOccurred())
+		repo, tag, policy := payloadRepo, payloadTag, "IfNotPresent"
+		lmc.Spec.Injection = &lmcachev1alpha1.LMCacheInjectionSpec{
+			PayloadImage:     &lmcachev1alpha1.ImageSpec{Repository: &repo, Tag: &tag, PullPolicy: &policy},
+			ImagePullSecrets: []corev1.LocalObjectReference{{Name: pullSecret}},
+		}
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("waiting for the <engine>-connection ConfigMap (the webhook reads it at admission)")
+		connName := fmt.Sprintf("%s-connection", lmc.Name)
+		Eventually(func() error {
+			return k8sClient.Get(ctx, engineKey(nsName, connName), &corev1.ConfigMap{})
+		}, 30*time.Second, 2*time.Second).Should(Succeed(),
+			"engine connection ConfigMap %q never appeared", connName)
+
+		By("creating the opted-in vLLM Deployment")
+		raw, err := utils.LoadFixture("vllm_lmcache_injection_deployment.yaml")
+		Expect(err).NotTo(HaveOccurred())
+		yamlText := strings.NewReplacer(
+			"__NAMESPACE__", nsName,
+			"__ENGINE_NAME__", lmc.Name,
+		).Replace(string(raw))
+		dep := &appsv1.Deployment{}
+		Expect(yaml.Unmarshal([]byte(yamlText), dep)).To(Succeed())
+		Expect(k8sClient.Create(ctx, dep)).To(Succeed())
+
+		By("verifying the mutating webhook staged the payload onto the vLLM pod")
+		// The mutation is at admission, so the pod carries the staging the moment
+		// it exists — the init container never has to pull or run (a bogus payload
+		// repo ImagePullBackOffs harmlessly; we assert the pod SPEC only).
+		Eventually(func(g Gomega) {
+			pod := firstPodForDeployment(ctx, nsName, dep)
+			g.Expect(pod).NotTo(BeNil(), "no vLLM pod created yet")
+			g.Expect(pod.Annotations).To(HaveKeyWithValue("lmcache.ai/lmcache-injected", "true"),
+				"webhook did not stamp lmcache-injected=true (skip-reason=%q)",
+				pod.Annotations["lmcache.ai/lmcache-skip-reason"])
+
+			By("payload init container: image + SHARED_DIR (no command override)")
+			init := podInitContainer(pod, initName)
+			g.Expect(init).NotTo(BeNil(), "payload init container %q not injected", initName)
+			g.Expect(init.Image).To(Equal(payloadRef))
+			g.Expect(init.Command).To(BeEmpty(), "init container must run the payload image ENTRYPOINT, not a command override")
+			g.Expect(containerEnvValue(init, sharedDirEnv)).To(Equal(payloadMount))
+
+			By("shared emptyDir payload volume")
+			g.Expect(podHasEmptyDirVolume(pod, payloadVol)).To(BeTrue(), "payload emptyDir volume %q missing", payloadVol)
+
+			By("read-only payload mount + PYTHONPATH on the vLLM container")
+			vllm := podContainer(pod, "vllm")
+			g.Expect(vllm).NotTo(BeNil())
+			mount := containerVolumeMount(vllm, payloadVol)
+			g.Expect(mount).NotTo(BeNil(), "payload mount %q missing on vLLM container", payloadVol)
+			g.Expect(mount.MountPath).To(Equal(payloadMount))
+			g.Expect(mount.ReadOnly).To(BeTrue())
+			g.Expect(containerEnvValue(vllm, "PYTHONPATH")).To(Equal(payloadMount),
+				"webhook did not prepend PYTHONPATH=%s", payloadMount)
+
+			By("payload pull secret merged onto the pod")
+			g.Expect(pod.Spec.ImagePullSecrets).To(ContainElement(corev1.LocalObjectReference{Name: pullSecret}))
+
+			By("connection wiring still applied alongside staging")
+			g.Expect(pod.Spec.HostIPC).To(BeTrue())
+			g.Expect(argValue(vllmContainerArgs(pod), "--kv-transfer-config")).To(ContainSubstring("LMCacheMPConnector"))
+		}, 60*time.Second, 2*time.Second).Should(Succeed())
+
+		_, _ = fmt.Fprintf(GinkgoWriter, "LMCache payload staging smoke satisfied (engine=%s)\n", lmc.Name)
+	})
+})
+
+// podEnvValue returns the value of env var name on the named container of the
+// pod, or "" if the container or var is absent.
+func podEnvValue(pod *corev1.Pod, container, name string) string {
+	for i := range pod.Spec.Containers {
+		if pod.Spec.Containers[i].Name != container {
+			continue
+		}
+		for _, e := range pod.Spec.Containers[i].Env {
+			if e.Name == name {
+				return e.Value
+			}
+		}
+	}
+	return ""
+}
diff --git a/operator/test/e2e/runtime_smoke_test.go b/operator/test/e2e/runtime_smoke_test.go
new file mode 100644
index 0000000..5b51d96
--- /dev/null
+++ b/operator/test/e2e/runtime_smoke_test.go
@@ -0,0 +1,117 @@
+//go:build e2e && e2e_gpu
+// +build e2e,e2e_gpu
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// Runtime smoke (e2e_gpu): verifies that the values declared on the CR
+// actually take effect inside the LMCache server process — not just on
+// the K8s objects. The M1 (no-GPU) suite stops at the K8s artifact
+// shape; this spec runs the pod and probes its HTTP frontend so a
+// regression that, say, swallows --chunk-size in arg-parsing is caught
+// even when the DaemonSet container args look correct.
+//
+// We probe `/status` because it returns is_healthy, chunk_size, and
+// hash_algorithm in one payload — enough to catch arg-parsing
+// regressions on those fields. The other CR fields (port, max_workers,
+// http_port) remain covered by the M1 K8s-side specs that diff the
+// DaemonSet container args.
+var _ = Describe("LMCacheEngine runtime smoke (GPU)", Ordered, func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+	})
+
+	It("GET /status reflects the CR's chunk_size + hash_algorithm end-to-end", func() {
+		lmc, err := utils.NewLMCFromFixture("lmc_runtime.yaml", nsName, "")
+		Expect(err).NotTo(HaveOccurred())
+
+		// Capture the spec values we'll assert against /status below.
+		// Reading via derefInt32-style accessors keeps the assertion
+		// independent of the operator's defaulting logic — we test
+		// "what the CR + defaults imply" vs "what the live server reports."
+		expectedChunkSize := int32(128)
+		expectedHashAlgorithm := "blake3"
+		// Used for port-forward target; matches lmc_runtime.yaml.
+		const httpPort int32 = 8080
+
+		By("applying the runtime LMCacheEngine")
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("waiting for the LMCache DaemonSet pod to become Ready")
+		// 8 min is intentional: this includes image pull on a cold node.
+		// Container image is lmcache/vllm-openai:latest (~10GB).
+		podName, err := utils.WaitDaemonSetPodReady(ctx, k8sClient, key, 8*time.Minute)
+		Expect(err).NotTo(HaveOccurred(), "LMCache pod did not become Ready")
+
+		By(fmt.Sprintf("port-forwarding to pod %s:%d", podName, httpPort))
+		closer, baseURL, err := utils.PortForward(
+			utils.PortForwardSpec{Namespace: nsName, Target: "pod/" + podName},
+			fmt.Sprintf("0:%d", httpPort),
+		)
+		Expect(err).NotTo(HaveOccurred())
+		defer closer()
+
+		By("waiting for /healthcheck to return 200")
+		Expect(utils.WaitHTTP200(ctx, baseURL+"/healthcheck", 2*time.Minute)).To(Succeed(),
+			"LMCache HTTP frontend did not become healthy")
+
+		By("fetching /status and asserting CR fields propagated to the live server")
+		status := &statusPayload{}
+		Expect(utils.HTTPGetJSON(ctx, baseURL+"/status", status)).To(Succeed())
+		Expect(status.IsHealthy).To(BeTrue(),
+			"status.is_healthy must be true — engine did not initialize cleanly")
+		Expect(status.ChunkSize).To(Equal(expectedChunkSize),
+			"status.chunk_size: live server disagrees with spec.server.chunkSize")
+		Expect(status.HashAlgorithm).To(Equal(expectedHashAlgorithm),
+			"status.hash_algorithm: live server disagrees with spec.server.hashAlgorithm")
+	})
+})
+
+// statusPayload is the strict subset of /status that the runtime
+// spec asserts against. Fields we don't assert on are intentionally
+// omitted — the server adds operational fields (registered_gpu_ids,
+// active_sessions, storage_manager) that change every run and would
+// just be noise here.
+type statusPayload struct {
+	IsHealthy     bool   `json:"is_healthy"`
+	ChunkSize     int32  `json:"chunk_size"`
+	HashAlgorithm string `json:"hash_algorithm"`
+}
diff --git a/operator/test/e2e/smoke_helpers_test.go b/operator/test/e2e/smoke_helpers_test.go
new file mode 100644
index 0000000..3d481fd
--- /dev/null
+++ b/operator/test/e2e/smoke_helpers_test.go
@@ -0,0 +1,353 @@
+//go:build e2e
+// +build e2e
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2" //nolint:revive,staticcheck
+	. "github.com/onsi/gomega"    //nolint:revive,staticcheck
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// nsCounter is a process-wide monotonic counter appended to every
+// generated namespace name. CurrentSpecReport().StartTime alone is not
+// enough — specs that call createTestNamespace twice in a single
+// BeforeEach (e.g. the cross-namespace auth spec, which needs both an
+// engine namespace and a source-Secret namespace) would otherwise compute the same name
+// twice and collide on AlreadyExists.
+var nsCounter atomic.Int64
+
+// createTestNamespace creates a fresh namespace whose name embeds the
+// running spec's text to make failing-spec dumps easier to attribute.
+// The deferred AfterEach is wired up by the caller via DeferCleanup so
+// each spec gets per-test isolation without relying on package state.
+//
+// The namespace is pre-labeled with the `privileged` PodSecurity profile
+// because the LMCache DaemonSet's pod template sets hostIPC=true (and
+// privileged=true only when spec.privileged is enabled), and hostIPC alone
+// is rejected by the restricted/baseline profiles. On clusters that enforce
+// PodSecurity admission (OCP in particular), a `restricted` namespace would
+// reject the DaemonSet at creation time, which the smokes need to succeed
+// even though they never wait for pods to schedule. The label is a no-op on
+// clusters that don't enforce PodSecurity.
+func createTestNamespace(ctx context.Context) string {
+	GinkgoHelper()
+	name := uniqueNamespaceName()
+	ns := &corev1.Namespace{
+		ObjectMeta: metav1.ObjectMeta{
+			Name: name,
+			Labels: map[string]string{
+				"pod-security.kubernetes.io/enforce": "privileged",
+				"pod-security.kubernetes.io/audit":   "privileged",
+				"pod-security.kubernetes.io/warn":    "privileged",
+			},
+		},
+	}
+	Expect(k8sClient.Create(ctx, ns)).To(Succeed(), "Failed to create test namespace %q", name)
+	DeferCleanup(func(ctx SpecContext) {
+		deleteNamespace(ctx, name)
+	})
+	return name
+}
+
+// uniqueNamespaceName produces a DNS-1123-safe namespace name that's
+// unique within the test process. The time component disambiguates
+// across runs / Kind-cluster restarts; the counter disambiguates
+// multiple calls inside a single spec.
+func uniqueNamespaceName() string {
+	n := nsCounter.Add(1)
+	hash := fmt.Sprintf("%x", time.Now().UnixNano())
+	if len(hash) > 8 {
+		hash = hash[len(hash)-8:]
+	}
+	return fmt.Sprintf("lmc-smoke-%s-%d", hash, n)
+}
+
+// deleteNamespace tears down a test namespace. We tolerate NotFound so
+// repeated cleanup calls don't fail; the namespace's contents are GC'd
+// asynchronously by Kubernetes.
+func deleteNamespace(ctx context.Context, name string) {
+	GinkgoHelper()
+	ns := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: name}}
+	if err := k8sClient.Delete(ctx, ns); err != nil && !apierrors.IsNotFound(err) {
+		_, _ = fmt.Fprintf(GinkgoWriter, "warning: delete namespace %q failed: %v\n", name, err)
+	}
+}
+
+// dumpControllerLogs writes the last <tail> lines of every
+// controller-manager pod's log to GinkgoWriter. Used by AfterEach
+// failure handlers to make CI dumps useful without paging the entire
+// reconcile history.
+func dumpControllerLogs(tail int) {
+	GinkgoHelper()
+	podName, err := controllerPodNameOnce()
+	if err != nil {
+		_, _ = fmt.Fprintf(GinkgoWriter, "warning: could not locate controller pod: %v\n", err)
+		return
+	}
+	cmd := exec.Command("kubectl", "logs", podName,
+		"-n", "lmcache-operator-system",
+		fmt.Sprintf("--tail=%d", tail),
+	)
+	out, _ := cmd.CombinedOutput()
+	_, _ = fmt.Fprintf(GinkgoWriter, "controller-manager logs (tail=%d):\n%s\n", tail, string(out))
+}
+
+// dumpNamespace writes events, pods, and the LMCacheEngine CR yaml from
+// the given namespace to GinkgoWriter. Designed to be cheap to call
+// from AfterEach without flooding output on success.
+func dumpNamespace(ns string) {
+	GinkgoHelper()
+	for _, args := range [][]string{
+		{"get", "events", "-n", ns, "--sort-by=.lastTimestamp"},
+		{"get", "lmcacheengines", "-n", ns, "-o", "yaml"},
+		{"get", "cacheblendengines", "-n", ns, "-o", "yaml"},
+		{"get", "pods", "-n", ns, "-o", "wide"},
+		// imagePullSecrets is not rendered by `describe pod`; print it
+		// explicitly so a wedged private-image pull can be triaged as
+		// "secret not attached" vs "bad credentials".
+		{"get", "pods", "-n", ns, "-o",
+			"jsonpath={range .items[*]}{.metadata.name}{\" imagePullSecrets=\"}{.spec.imagePullSecrets}{\"\\n\"}{end}"},
+		{"describe", "pods", "-n", ns},
+	} {
+		out, _ := exec.Command("kubectl", args...).CombinedOutput()
+		_, _ = fmt.Fprintf(GinkgoWriter, "$ kubectl %v\n%s\n", args, string(out))
+	}
+
+	// Per-pod logs (last 200 lines). The vLLM and LMCache pods produce
+	// most of the diagnostic signal on failure; without their logs,
+	// `describe pod` only tells us readiness flapped, not why. The
+	// `--previous` fetches the prior-instantiation logs when the
+	// container has crashed and restarted — that's where mid-inference
+	// CUDA / Python tracebacks live.
+	podNames := exec.Command("kubectl", "get", "pods", "-n", ns,
+		"-o", "jsonpath={range .items[*]}{.metadata.name} {end}")
+	out, err := podNames.Output()
+	if err != nil {
+		return
+	}
+	for _, podName := range strings.Fields(string(out)) {
+		for _, args := range [][]string{
+			{"logs", "-n", ns, podName, "--tail=200", "--all-containers"},
+			{"logs", "-n", ns, podName, "--tail=200", "--all-containers", "--previous"},
+		} {
+			cmd := exec.Command("kubectl", args...)
+			cmd.Stderr = nil // mute "previous terminated container not found" noise
+			out, _ := cmd.Output()
+			if len(out) == 0 {
+				continue
+			}
+			_, _ = fmt.Fprintf(GinkgoWriter, "$ kubectl %v\n%s\n", args, string(out))
+		}
+	}
+}
+
+// controllerPodNameOnce returns the first running controller-manager
+// pod name. We resolve fresh each call rather than caching because the
+// pod can be evicted/restarted between specs.
+func controllerPodNameOnce() (string, error) {
+	cmd := exec.Command("kubectl", "get", "pods",
+		"-n", "lmcache-operator-system",
+		"-l", "control-plane=controller-manager",
+		"-o", "jsonpath={.items[0].metadata.name}",
+	)
+	out, err := cmd.Output()
+	if err != nil {
+		return "", err
+	}
+	if len(out) == 0 {
+		return "", fmt.Errorf("no controller-manager pod found")
+	}
+	return string(out), nil
+}
+
+// recordOnFailure runs the standard dump bundle iff the current spec
+// failed. Use as the body of an AfterEach so passing specs stay quiet.
+func recordOnFailure(ns string) {
+	if !CurrentSpecReport().Failed() {
+		return
+	}
+	dumpControllerLogs(200)
+	dumpNamespace(ns)
+}
+
+// engineKey is shorthand for the typed namespaced name pair used throughout
+// the smoke specs.
+func engineKey(ns, name string) client.ObjectKey {
+	return client.ObjectKey{Namespace: ns, Name: name}
+}
+
+// containerArgs returns the args of the first (and only) container in
+// the DaemonSet pod template — the smoke contract requires exactly one.
+func containerArgs(ds *appsv1.DaemonSet) []string {
+	if len(ds.Spec.Template.Spec.Containers) == 0 {
+		return nil
+	}
+	return ds.Spec.Template.Spec.Containers[0].Args
+}
+
+// argValue returns the value following the first occurrence of flag in
+// args, or "" if flag is not present or has no value. Args are flat
+// ["--flag", "val", ...] pairs emitted by BuildContainerArgs.
+func argValue(args []string, flag string) string {
+	for i := range args {
+		if args[i] == flag && i+1 < len(args) {
+			return args[i+1]
+		}
+	}
+	return ""
+}
+
+// argValueLast returns the value following the LAST occurrence of flag.
+// argparse-style flag handling lets a later --flag override an earlier
+// one, so the operator's contract for spec.extraArgs is "appended last,
+// can override any auto-generated flag." This helper mirrors that
+// runtime semantics from the operator's perspective: which value would
+// the server actually use?
+func argValueLast(args []string, flag string) string {
+	last := ""
+	for i := range args {
+		if args[i] == flag && i+1 < len(args) {
+			last = args[i+1]
+		}
+	}
+	return last
+}
+
+// serviceMonitorCRDInstalled reports whether the Prometheus Operator's
+// ServiceMonitor CRD is registered on the target cluster. Specs that
+// only make sense in that environment (the ServiceMonitor spec) call this in
+// BeforeEach and Skip() when it returns false, so the same suite can
+// run unchanged on bare Kind clusters and on clusters with the
+// kube-prometheus-stack pre-installed. Errors other than NoMatch
+// fail loudly so a transient API hiccup is never silently masked.
+func serviceMonitorCRDInstalled() bool {
+	GinkgoHelper()
+	_, err := k8sClient.RESTMapper().RESTMapping(schema.GroupKind{
+		Group: "monitoring.coreos.com",
+		Kind:  "ServiceMonitor",
+	}, "v1")
+	if err == nil {
+		return true
+	}
+	if meta.IsNoMatchError(err) {
+		return false
+	}
+	Fail(fmt.Sprintf("unexpected error querying ServiceMonitor RESTMapping: %v", err))
+	return false // unreachable
+}
+
+// firstPodForDeployment returns the first non-terminating pod selected by the
+// Deployment's pod selector, or nil if none exist yet. Returns the typed Pod
+// so callers can read both annotations (injection stamp) and container args.
+func firstPodForDeployment(ctx context.Context, ns string, dep *appsv1.Deployment) *corev1.Pod {
+	pods := &corev1.PodList{}
+	if err := k8sClient.List(ctx, pods,
+		client.InNamespace(ns),
+		client.MatchingLabels(dep.Spec.Selector.MatchLabels),
+	); err != nil {
+		return nil
+	}
+	for i := range pods.Items {
+		if pods.Items[i].DeletionTimestamp == nil {
+			return &pods.Items[i]
+		}
+	}
+	return nil
+}
+
+// podInitContainer returns the named init container of the pod, or nil.
+func podInitContainer(pod *corev1.Pod, name string) *corev1.Container {
+	for i := range pod.Spec.InitContainers {
+		if pod.Spec.InitContainers[i].Name == name {
+			return &pod.Spec.InitContainers[i]
+		}
+	}
+	return nil
+}
+
+// podContainer returns the named (non-init) container of the pod, or nil.
+func podContainer(pod *corev1.Pod, name string) *corev1.Container {
+	for i := range pod.Spec.Containers {
+		if pod.Spec.Containers[i].Name == name {
+			return &pod.Spec.Containers[i]
+		}
+	}
+	return nil
+}
+
+// containerEnvValue returns the value of env var name on the container, or "".
+func containerEnvValue(c *corev1.Container, name string) string {
+	for _, e := range c.Env {
+		if e.Name == name {
+			return e.Value
+		}
+	}
+	return ""
+}
+
+// containerVolumeMount returns the named volume mount on the container, or nil.
+func containerVolumeMount(c *corev1.Container, name string) *corev1.VolumeMount {
+	for i := range c.VolumeMounts {
+		if c.VolumeMounts[i].Name == name {
+			return &c.VolumeMounts[i]
+		}
+	}
+	return nil
+}
+
+// podHasEmptyDirVolume reports whether the pod carries an emptyDir volume of the
+// given name.
+func podHasEmptyDirVolume(pod *corev1.Pod, name string) bool {
+	for i := range pod.Spec.Volumes {
+		if pod.Spec.Volumes[i].Name == name {
+			return pod.Spec.Volumes[i].EmptyDir != nil
+		}
+	}
+	return false
+}
+
+// vllmContainerArgs returns the args of the vLLM container in the pod (the one
+// named "vllm", falling back to the first container). The mutating webhooks
+// append vLLM flags to this container's args.
+func vllmContainerArgs(pod *corev1.Pod) []string {
+	for i := range pod.Spec.Containers {
+		if pod.Spec.Containers[i].Name == "vllm" {
+			return pod.Spec.Containers[i].Args
+		}
+	}
+	if len(pod.Spec.Containers) > 0 {
+		return pod.Spec.Containers[0].Args
+	}
+	return nil
+}
diff --git a/operator/test/e2e/vllm_integration_smoke_test.go b/operator/test/e2e/vllm_integration_smoke_test.go
new file mode 100644
index 0000000..6c37951
--- /dev/null
+++ b/operator/test/e2e/vllm_integration_smoke_test.go
@@ -0,0 +1,293 @@
+//go:build e2e && e2e_gpu
+// +build e2e,e2e_gpu
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package e2e
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"regexp"
+	"strings"
+	"time"
+
+	. "github.com/onsi/ginkgo/v2"
+	. "github.com/onsi/gomega"
+
+	appsv1 "k8s.io/api/apps/v1"
+	"k8s.io/apimachinery/pkg/types"
+	"sigs.k8s.io/yaml"
+
+	"github.com/LMCache/LMCache/test/utils"
+)
+
+// vLLM + LMCache round-trip (e2e_gpu): verifies that an external vLLM
+// pod, when pointed at the operator-managed LMCacheEngine via the
+// <engine>-connection ConfigMap and run with vLLM's APC OFF, actually
+// stores KV on request 1 and retrieves it on request 2.
+//
+// The assertion grep's the LMCache server's stdout for its own
+// "Stored N tokens" / "Retrieved N tokens" log lines (server.py logs
+// these at INFO level on every store and retrieve). This is more
+// direct than scraping Prometheus counters — those are emitted by
+// the vLLM-side connector and depend on OTel export cadence; the
+// server log is written synchronously and is the same signal an
+// on-call would look at when debugging cache behaviour by hand.
+//
+// Knobs:
+//   - VLLM_MODEL  Hugging Face model id. Default: Qwen/Qwen2.5-0.5B
+//     (small enough to load on a 16GB GPU, big enough that one chunk
+//     covers ≥256 tokens of the test prompt). Only the model config
+//     and tokenizer are downloaded; weights are dummy (see fixture).
+//   - VLLM_IMAGE  container image. Default: lmcache/vllm-openai:latest
+//     (same image the operator pins for the LMCache DaemonSet, which
+//     means a fresh node only pulls once).
+//   - SKIP_VLLM_INTEGRATION  when set to "true", skip this spec.
+//     Useful when the cluster has GPUs but no internet egress to HF
+//     even for config/tokenizer files.
+var _ = Describe("vLLM + LMCacheEngine integration smoke (GPU)", Ordered, func() {
+	var (
+		ctx    context.Context
+		nsName string
+	)
+
+	BeforeEach(func() {
+		if os.Getenv("SKIP_VLLM_INTEGRATION") == "true" {
+			Skip("SKIP_VLLM_INTEGRATION=true; skipping vLLM round-trip spec")
+		}
+		ctx = context.Background()
+		nsName = createTestNamespace(ctx)
+	})
+
+	AfterEach(func() {
+		recordOnFailure(nsName)
+		// vLLM Deployment is owned by the spec, not by the LMCacheEngine,
+		// so namespace deletion (via DeferCleanup in createTestNamespace)
+		// is what cleans it up. No explicit teardown needed here.
+	})
+
+	It("stores KV on first request and retrieves it on a second identical request", func() {
+		model := envDefault("VLLM_MODEL", "Qwen/Qwen2.5-0.5B")
+		vllmImage := envDefault("VLLM_IMAGE", "lmcache/vllm-openai:latest")
+
+		By("applying the runtime LMCacheEngine")
+		lmc, err := utils.NewLMCFromFixture("lmc_runtime.yaml", nsName, "vllm-integration")
+		Expect(err).NotTo(HaveOccurred())
+		Expect(utils.ApplyLMC(ctx, k8sClient, lmc)).To(Succeed())
+
+		key := engineKey(nsName, lmc.Name)
+		Expect(utils.WaitLMCReconciled(ctx, k8sClient, key, 60*time.Second)).To(Succeed())
+
+		By("waiting for the LMCache DaemonSet pod to become Ready")
+		lmcPodName, err := utils.WaitDaemonSetPodReady(ctx, k8sClient, key, 8*time.Minute)
+		Expect(err).NotTo(HaveOccurred(), "LMCache pod did not become Ready")
+
+		By("applying the vLLM Deployment, parameterised against this engine")
+		vllmRaw, err := utils.LoadFixture("vllm_deployment.yaml")
+		Expect(err).NotTo(HaveOccurred())
+		vllmYAML := substituteVLLMPlaceholders(string(vllmRaw), nsName, lmc.Name, model, vllmImage)
+		vllmDeploy := &appsv1.Deployment{}
+		Expect(yaml.Unmarshal([]byte(vllmYAML), vllmDeploy)).To(Succeed())
+		Expect(k8sClient.Create(ctx, vllmDeploy)).To(Succeed())
+
+		By("waiting for the vLLM Deployment to become Available (model load + connector handshake)")
+		// 15 min — covers cold-image pull (~10GB), HF model download,
+		// and vLLM startup. The readinessProbe gates on /v1/models so
+		// the deployment is only Available once vLLM has fully loaded.
+		Expect(utils.WaitDeploymentAvailable(
+			ctx, k8sClient,
+			types.NamespacedName{Namespace: nsName, Name: vllmDeploy.Name},
+			15*time.Minute,
+		)).To(Succeed(), "vLLM did not become Available — check pod events / logs")
+
+		By("port-forwarding to vLLM service for completion requests")
+		vllmCloser, vllmBaseURL, err := utils.PortForward(
+			utils.PortForwardSpec{Namespace: nsName, Target: "deployment/" + vllmDeploy.Name},
+			"0:8000",
+		)
+		Expect(err).NotTo(HaveOccurred())
+		defer vllmCloser()
+		Expect(utils.WaitHTTP200(ctx, vllmBaseURL+"/v1/models", 60*time.Second)).To(Succeed())
+
+		// Build a prompt long enough to cross at least one LMCache
+		// chunk boundary (chunkSize=128 tokens for the runtime
+		// fixture). The repeated paragraph generates well over a
+		// thousand tokens so the round-trip stores at least 8 chunks.
+		prompt := buildLongPrompt()
+
+		By("sending the first /v1/completions request (cold — LMCache should STORE)")
+		Expect(postCompletion(ctx, vllmBaseURL, model, prompt)).To(Succeed())
+
+		// Server-side flushes are synchronous up to the log line, but
+		// kubelet's log streaming buffers a beat behind. A couple of
+		// seconds is enough to absorb that without padding the suite.
+		By("waiting 2s for the LMCache server log to flush")
+		time.Sleep(2 * time.Second)
+
+		By("verifying LMCache logged a Stored line after the first request")
+		Eventually(func() int {
+			return countLMCacheStored(ctx, nsName, lmcPodName)
+		}, 30*time.Second, 2*time.Second).Should(BeNumerically(">=", 1),
+			"LMCache did not log any 'Stored N tokens' line after request 1")
+		storedBefore := countLMCacheStored(ctx, nsName, lmcPodName)
+		retrievedBefore := countLMCacheRetrieved(ctx, nsName, lmcPodName)
+		Expect(retrievedBefore).To(Equal(0),
+			"LMCache logged a 'Retrieved' before any cache hit was possible (got %d)", retrievedBefore)
+
+		By("sending the second /v1/completions request (same prompt — LMCache should HIT)")
+		Expect(postCompletion(ctx, vllmBaseURL, model, prompt)).To(Succeed())
+
+		By("verifying LMCache logged a Retrieved line after the second request")
+		// Eventually: log buffering between server.py and kubectl logs
+		// usually settles in <2s, but the storage controller is async
+		// in its accounting so we poll up to 30s. Hitting the floor of
+		// "retrieved-after >= 1 AND stored-after unchanged" proves the
+		// second request rode the cache rather than re-storing.
+		Eventually(func(g Gomega) {
+			retrievedAfter := countLMCacheRetrieved(ctx, nsName, lmcPodName)
+			storedAfter := countLMCacheStored(ctx, nsName, lmcPodName)
+			g.Expect(retrievedAfter).To(BeNumerically(">=", 1),
+				"LMCache did not log any 'Retrieved' line after request 2 (got %d)",
+				retrievedAfter)
+			g.Expect(storedAfter).To(Equal(storedBefore),
+				"LMCache logged additional 'Stored' lines on the repeat request "+
+					"(before=%d, after=%d) — the cache hit didn't short-circuit the store path",
+				storedBefore, storedAfter)
+		}, 30*time.Second, 2*time.Second).Should(Succeed())
+
+		_, _ = fmt.Fprintf(GinkgoWriter,
+			"cache round-trip assertion satisfied (stored=%d, retrieved=%d)\n",
+			countLMCacheStored(ctx, nsName, lmcPodName),
+			countLMCacheRetrieved(ctx, nsName, lmcPodName),
+		)
+	})
+})
+
+// substituteVLLMPlaceholders renders the vllm Deployment fixture for a
+// concrete run. Kept as a tiny function so the template stays readable
+// and so we don't pull in a heavy templating dependency for four substitutions.
+func substituteVLLMPlaceholders(yamlText, ns, engineName, model, image string) string {
+	r := strings.NewReplacer(
+		"__NAMESPACE__", ns,
+		"__ENGINE_NAME__", engineName,
+		"__MODEL__", model,
+		"__VLLM_IMAGE__", image,
+	)
+	return r.Replace(yamlText)
+}
+
+// completionRequest is the minimal /v1/completions payload — we don't
+// need streaming, sampling, or beam parameters since we're measuring
+// cache behaviour, not generation quality.
+type completionRequest struct {
+	Model       string  `json:"model"`
+	Prompt      string  `json:"prompt"`
+	MaxTokens   int     `json:"max_tokens"`
+	Temperature float64 `json:"temperature"`
+}
+
+// postCompletion sends a single /v1/completions request and discards
+// the result. Failures (non-2xx, network errors, JSON parse errors)
+// propagate to the spec so the assertion failure shows the underlying
+// HTTP context, not just "cache miss."
+func postCompletion(ctx context.Context, baseURL, model, prompt string) error {
+	body := completionRequest{
+		Model:       model,
+		Prompt:      prompt,
+		MaxTokens:   32,
+		Temperature: 0,
+	}
+	// vllm inference can be slow on first request (kernel cache cold),
+	// so the request gets its own longer timeout than the default
+	// httpJSONClient. We use HTTPPostJSON with a derived context.
+	reqCtx, cancel := context.WithTimeout(ctx, 5*time.Minute)
+	defer cancel()
+	return utils.HTTPPostJSON(reqCtx, baseURL+"/v1/completions", body, nil)
+}
+
+// lmcacheStoredLine matches the LMCache MP server's stdout INFO line
+// emitted on every successful STORE, e.g.
+//
+//	[2026-05-13 23:21:02,989] LMCache INFO: Stored 1152 tokens in 0.003 seconds
+//
+// The leading bracketed timestamp + log-level prefix may be coloured
+// with ANSI escapes in TTY mode; we don't bother stripping those
+// because `kubectl logs` returns the raw line and the regex only
+// requires the literal "Stored " substring.
+var lmcacheStoredLine = regexp.MustCompile(`LMCache INFO:.*\bStored \d+ tokens\b`)
+
+// lmcacheRetrievedLine mirrors lmcacheStoredLine for the RETRIEVE path,
+// emitted from server.py:531 on every cache hit.
+var lmcacheRetrievedLine = regexp.MustCompile(`LMCache INFO:.*\bRetrieved \d+ tokens\b`)
+
+// countLMCacheStored runs `kubectl logs` on the LMCache MP server pod
+// and returns the number of matching "Stored N tokens" lines seen so
+// far. Returns 0 on any kubectl error (caller is expected to wrap the
+// call in Eventually, which already retries on transient failures).
+func countLMCacheStored(ctx context.Context, ns, podName string) int {
+	return countLogLines(ctx, ns, podName, lmcacheStoredLine)
+}
+
+// countLMCacheRetrieved is the RETRIEVE counterpart of countLMCacheStored.
+func countLMCacheRetrieved(ctx context.Context, ns, podName string) int {
+	return countLogLines(ctx, ns, podName, lmcacheRetrievedLine)
+}
+
+// countLogLines is the implementation behind countLMCacheStored /
+// countLMCacheRetrieved. We shell out to kubectl rather than building
+// a typed Pods/log client because the rest of the suite already
+// depends on kubectl being on PATH for port-forward, and adding a
+// streaming-log client just for this would be heavier than the
+// problem warrants.
+func countLogLines(ctx context.Context, ns, podName string, pattern *regexp.Regexp) int {
+	cmd := exec.CommandContext(ctx, "kubectl", "logs",
+		"-n", ns, podName,
+		"--tail=10000", // generous: a few k tokens of LMCache INFO output
+	)
+	out, err := cmd.Output()
+	if err != nil {
+		return 0
+	}
+	return len(pattern.FindAllIndex(out, -1))
+}
+
+// buildLongPrompt assembles ~1.2k tokens of prose so the prompt spans
+// at least 8 chunks at chunkSize=128. We use a repeated history
+// passage rather than random tokens so the prompt is human-readable
+// in dump output (helps debugging when the test fails) and so vLLM's
+// tokeniser segments it consistently across runs.
+func buildLongPrompt() string {
+	const para = "The history and significance of the Roman empire spans more than a thousand years " +
+		"and profoundly shaped Western civilization. Its legal, architectural, linguistic, and " +
+		"political legacies persist to this day, influencing modern governments, languages, art, " +
+		"engineering, and law. The empire's trajectory from the founding of Rome through the " +
+		"Republic, the transition to the Principate under Augustus, the Pax Romana, the crisis of " +
+		"the third century, the Dominate under Diocletian, the adoption of Christianity under " +
+		"Constantine, the splitting into Western and Eastern halves, and the eventual collapse of " +
+		"the West is one of history's great narratives. Key figures include Julius Caesar, " +
+		"Augustus, Marcus Aurelius, Diocletian, Constantine, Justinian, and many others. "
+	var b strings.Builder
+	for range 8 {
+		b.WriteString(para)
+	}
+	b.WriteString("Tell me a long, detailed story about the rise, peak, and eventual fall of Rome, " +
+		"naming important figures and events.")
+	return b.String()
+}
diff --git a/operator/test/utils/cbe.go b/operator/test/utils/cbe.go
new file mode 100644
index 0000000..f6c36f9
--- /dev/null
+++ b/operator/test/utils/cbe.go
@@ -0,0 +1,107 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/apimachinery/pkg/util/wait"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/yaml"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// NewCBEFromFixture loads a fixture YAML, decodes it as a CacheBlendEngine,
+// and overrides metadata.name and metadata.namespace with the supplied
+// values. It mirrors NewLMCFromFixture for the CacheBlend engine type so the
+// GPU smoke tier can parameterise a fixture against a fresh namespace. Callers
+// can mutate the returned object further (e.g. inject env-driven images and
+// pull secrets) before applying.
+func NewCBEFromFixture(fixtureName, namespace, name string) (*lmcachev1alpha1.CacheBlendEngine, error) {
+	data, err := LoadFixture(fixtureName)
+	if err != nil {
+		return nil, err
+	}
+	cbe := &lmcachev1alpha1.CacheBlendEngine{}
+	if err := yaml.Unmarshal(data, cbe); err != nil {
+		return nil, fmt.Errorf("decode fixture %q: %w", fixtureName, err)
+	}
+	if name != "" {
+		cbe.Name = name
+	}
+	if namespace != "" {
+		cbe.Namespace = namespace
+	}
+	// Strip any server-side metadata that may have leaked through.
+	cbe.ResourceVersion = ""
+	cbe.UID = ""
+	cbe.Generation = 0
+	return cbe, nil
+}
+
+// ApplyCBE creates the CacheBlendEngine if absent, or patches it (spec only)
+// if it already exists. The status subresource is left untouched. Mirrors
+// ApplyLMC.
+func ApplyCBE(ctx context.Context, c client.Client, cbe *lmcachev1alpha1.CacheBlendEngine) error {
+	existing := &lmcachev1alpha1.CacheBlendEngine{}
+	err := c.Get(ctx, client.ObjectKeyFromObject(cbe), existing)
+	if apierrors.IsNotFound(err) {
+		return c.Create(ctx, cbe)
+	}
+	if err != nil {
+		return fmt.Errorf("get CacheBlendEngine %s/%s: %w", cbe.Namespace, cbe.Name, err)
+	}
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec = cbe.Spec
+	existing.Labels = cbe.Labels
+	existing.Annotations = cbe.Annotations
+	if err := c.Patch(ctx, existing, patch); err != nil {
+		return fmt.Errorf("patch CacheBlendEngine %s/%s: %w", cbe.Namespace, cbe.Name, err)
+	}
+	*cbe = *existing
+	return nil
+}
+
+// WaitCBEReconciled polls until status.observedGeneration matches the CR's
+// metadata.generation AND the ConfigValid condition is True. This is the
+// "controller saw and validated the spec" signal — it does NOT require the
+// engine pod to be Running (use WaitDaemonSetPodReady for that, keyed on the
+// same namespaced name since the engine DaemonSet is named after the CR).
+// The CacheBlendEngine controller reuses the LMCacheEngine condition
+// constants, so ConditionConfigValid is the right key here.
+func WaitCBEReconciled(ctx context.Context, c client.Client, key types.NamespacedName, timeout time.Duration) error {
+	return wait.PollUntilContextTimeout(ctx, time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		cbe := &lmcachev1alpha1.CacheBlendEngine{}
+		if err := c.Get(ctx, key, cbe); err != nil {
+			if apierrors.IsNotFound(err) {
+				return false, nil
+			}
+			return false, err
+		}
+		if cbe.Generation == 0 || cbe.Status.ObservedGeneration != cbe.Generation {
+			return false, nil
+		}
+		cond := meta.FindStatusCondition(cbe.Status.Conditions, lmcachev1alpha1.ConditionConfigValid)
+		return cond != nil && cond.Status == "True", nil
+	})
+}
diff --git a/operator/test/utils/fixtures.go b/operator/test/utils/fixtures.go
new file mode 100644
index 0000000..8f4e53d
--- /dev/null
+++ b/operator/test/utils/fixtures.go
@@ -0,0 +1,82 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"embed"
+	"fmt"
+	"path"
+
+	"sigs.k8s.io/yaml"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// fixturesFS embeds the fixtures tree shipped with the smoke harness:
+// CR YAMLs at fixtures/*.yaml and golden JSON snapshots at
+// fixtures/golden/*.json. Embedding sidesteps the working-directory
+// hack in utils.GetProjectDir: fixtures are compiled into the test
+// binary and resolved by relative path.
+//
+//go:embed fixtures/*.yaml fixtures/golden/*.json
+var fixturesFS embed.FS
+
+// LoadFixture returns the raw bytes of a fixture file by name (no path).
+func LoadFixture(name string) ([]byte, error) {
+	data, err := fixturesFS.ReadFile(path.Join("fixtures", name))
+	if err != nil {
+		return nil, fmt.Errorf("load fixture %q: %w", name, err)
+	}
+	return data, nil
+}
+
+// LoadGolden returns the raw bytes of a golden snapshot by name (no path).
+// Golden files live under fixtures/golden/ and represent expected JSON
+// payloads emitted by the operator. Tests typically substitute namespace
+// placeholders into the result before comparing.
+func LoadGolden(name string) ([]byte, error) {
+	data, err := fixturesFS.ReadFile(path.Join("fixtures", "golden", name))
+	if err != nil {
+		return nil, fmt.Errorf("load golden %q: %w", name, err)
+	}
+	return data, nil
+}
+
+// NewLMCFromFixture loads a fixture YAML, decodes it as an LMCacheEngine,
+// and overrides metadata.name and metadata.namespace with the supplied
+// values. Callers can mutate the returned object further before applying.
+func NewLMCFromFixture(fixtureName, namespace, name string) (*lmcachev1alpha1.LMCacheEngine, error) {
+	data, err := LoadFixture(fixtureName)
+	if err != nil {
+		return nil, err
+	}
+	lmc := &lmcachev1alpha1.LMCacheEngine{}
+	if err := yaml.Unmarshal(data, lmc); err != nil {
+		return nil, fmt.Errorf("decode fixture %q: %w", fixtureName, err)
+	}
+	if name != "" {
+		lmc.Name = name
+	}
+	if namespace != "" {
+		lmc.Namespace = namespace
+	}
+	// Strip any server-side metadata that may have leaked through.
+	lmc.ResourceVersion = ""
+	lmc.UID = ""
+	lmc.Generation = 0
+	return lmc, nil
+}
diff --git a/operator/test/utils/fixtures/cacheblendengine.yaml b/operator/test/utils/fixtures/cacheblendengine.yaml
new file mode 100644
index 0000000..888d5b5
--- /dev/null
+++ b/operator/test/utils/fixtures/cacheblendengine.yaml
@@ -0,0 +1,50 @@
+# CacheBlendEngine used by the e2e_gpu CacheBlend integration spec.
+#
+# NewCBEFromFixture decodes this YAML into a typed CacheBlendEngine and
+# overrides metadata.name / metadata.namespace. The spec then overrides the
+# two env-driven, deployment-specific bits before applying:
+#
+#   - spec.image                       (CACHEBLEND_ENGINE_IMAGE; the lmcache
+#                                       blend server image — public by default)
+#   - spec.injection.payloadImage      (CACHEBLEND_PAYLOAD_IMAGE; the PRIVATE
+#                                       cacheblend-plugin init-container image)
+#
+# spec.injection.imagePullSecrets references the docker-registry Secret the
+# spec creates in this namespace from CACHEBLEND_REGISTRY_USER/TOKEN. The
+# mutating webhook appends it to the vLLM pod so the payload init container
+# can pull the private image.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: CacheBlendEngine
+metadata:
+  name: cb-integration
+spec:
+  # The lmcache blend server image. Public; pinned to the same image the
+  # vLLM workload uses so a fresh GPU node pulls it only once. Nightly to stay
+  # in the CacheBlend compatibility window with the latest-nightly payload.
+  image:
+    repository: lmcache/vllm-openai
+    tag: latest-nightly
+    pullPolicy: IfNotPresent
+
+  # L1 cache is REQUIRED. 8 GiB is plenty for the small smoke model.
+  l1:
+    sizeGB: 8
+
+  injection:
+    # The PRIVATE cacheblend-plugin init-container image. The spec overrides
+    # repository/tag from CACHEBLEND_PAYLOAD_IMAGE; these are the defaults.
+    payloadImage:
+      repository: tensormesh/cacheblend-plugin
+      tag: latest-nightly
+      pullPolicy: IfNotPresent
+    # Pull secret for the private payload image. Created by the spec in this
+    # namespace (name must match the spec's pullSecretName constant).
+    imagePullSecrets:
+      - name: cacheblend-registry
+
+  # Place the engine on the GPU worker so the vLLM pod (same nodeSelector)
+  # co-schedules — CacheBlend's CUDA-IPC KV handoff requires colocation.
+  nodeSelector:
+    nvidia.com/gpu.present: "true"
+
+  logLevel: INFO
diff --git a/operator/test/utils/fixtures/golden/kv_transfer_config_minimal.json b/operator/test/utils/fixtures/golden/kv_transfer_config_minimal.json
new file mode 100644
index 0000000..aea1a6c
--- /dev/null
+++ b/operator/test/utils/fixtures/golden/kv_transfer_config_minimal.json
@@ -0,0 +1,9 @@
+{
+  "kv_connector": "LMCacheMPConnector",
+  "kv_connector_module_path": "lmcache.integration.vllm.lmcache_mp_connector",
+  "kv_connector_extra_config": {
+    "lmcache.mp.host": "tcp://smoke-minimal.__NAMESPACE__.svc.cluster.local",
+    "lmcache.mp.port": "5555"
+  },
+  "kv_role": "kv_both"
+}
diff --git a/operator/test/utils/fixtures/lmc_custom_port.yaml b/operator/test/utils/fixtures/lmc_custom_port.yaml
new file mode 100644
index 0000000..b349f10
--- /dev/null
+++ b/operator/test/utils/fixtures/lmc_custom_port.yaml
@@ -0,0 +1,18 @@
+# Custom-port LMCacheEngine fixture for the custom-port smoke spec.
+#
+# Exercises the non-default code paths in BuildContainerArgs and
+# BuildLookupService: the controller must propagate spec.server.port
+# (6555) and spec.server.chunkSize (128) into both the DaemonSet
+# container args and the lookup Service port. The golden assertion in
+# crd_smoke_test.go pairs this fixture with the expected ConfigMap.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: smoke-custom-port
+spec:
+  nodeSelector: {}
+  server:
+    port: 6555
+    chunkSize: 128
+  l1:
+    sizeGB: 10
diff --git a/operator/test/utils/fixtures/lmc_minimal.yaml b/operator/test/utils/fixtures/lmc_minimal.yaml
new file mode 100644
index 0000000..97295e2
--- /dev/null
+++ b/operator/test/utils/fixtures/lmc_minimal.yaml
@@ -0,0 +1,19 @@
+# Minimal LMCacheEngine fixture used by the smoke test harness.
+#
+# The fixture intentionally sets nodeSelector to {} (empty map) so the
+# operator's SetDefaults does NOT fall back to nvidia.com/gpu.present.
+# That keeps the DaemonSet schedulable on a no-GPU Kind cluster, which
+# is required for the no-GPU smoke tier. The pods will not become Ready
+# (no nvidia runtime / image), but the operator will still reconcile
+# every K8s artifact it owns — which is what the smokes assert on.
+#
+# Tests that need a deterministic, non-default port should use
+# lmc_custom_port.yaml or PatchLMCSpec instead.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: smoke-minimal
+spec:
+  nodeSelector: {}
+  l1:
+    sizeGB: 10
diff --git a/operator/test/utils/fixtures/lmc_runtime.yaml b/operator/test/utils/fixtures/lmc_runtime.yaml
new file mode 100644
index 0000000..aac7979
--- /dev/null
+++ b/operator/test/utils/fixtures/lmc_runtime.yaml
@@ -0,0 +1,22 @@
+# Runtime fixture used by the e2e_gpu smoke tier.
+#
+# This fixture deliberately OMITS spec.nodeSelector so the operator's
+# SetDefaults adds nvidia.com/gpu.present="true" and the DaemonSet pod
+# lands only on GPU nodes. (Compare with lmc_minimal.yaml which sets
+# nodeSelector: {} to allow scheduling on no-GPU Kind for the M1 tier.)
+#
+# Custom server.port + server.chunkSize values are non-defaults so the
+# /conf round-trip spec can prove "what the CR said" was actually
+# applied to the running LMCache server — not just to the K8s objects.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: smoke-runtime
+spec:
+  l1:
+    sizeGB: 10
+  server:
+    port: 6555
+    chunkSize: 128
+    maxWorkers: 2
+    hashAlgorithm: blake3
diff --git a/operator/test/utils/fixtures/lmc_servicemonitor.yaml b/operator/test/utils/fixtures/lmc_servicemonitor.yaml
new file mode 100644
index 0000000..798267e
--- /dev/null
+++ b/operator/test/utils/fixtures/lmc_servicemonitor.yaml
@@ -0,0 +1,20 @@
+# ServiceMonitor smoke fixture.
+#
+# Enabling prometheus.serviceMonitor.enabled is the only way the operator
+# creates a monitoring.coreos.com/v1 ServiceMonitor. We pin a release
+# label here so the test can assert it round-trips into the CR.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: smoke-servicemonitor
+spec:
+  nodeSelector: {}
+  l1:
+    sizeGB: 10
+  prometheus:
+    enabled: true
+    serviceMonitor:
+      enabled: true
+      interval: 30s
+      labels:
+        release: kube-prometheus-stack
diff --git a/operator/test/utils/fixtures/lmc_with_redis_l2_authsecret.yaml b/operator/test/utils/fixtures/lmc_with_redis_l2_authsecret.yaml
new file mode 100644
index 0000000..1f434a9
--- /dev/null
+++ b/operator/test/utils/fixtures/lmc_with_redis_l2_authsecret.yaml
@@ -0,0 +1,22 @@
+# Cross-namespace authSecretRef fixture.
+#
+# The authSecretRef.namespace is intentionally a placeholder — the test
+# overrides it with a per-spec source namespace at runtime so multiple
+# specs can run in parallel without colliding on a shared "redis-src".
+# The host/port don't need to be reachable; the operator only inspects
+# the auth machinery for this smoke.
+apiVersion: lmcache.lmcache.ai/v1alpha1
+kind: LMCacheEngine
+metadata:
+  name: smoke-auth
+spec:
+  nodeSelector: {}
+  l1:
+    sizeGB: 10
+  l2Backend:
+    resp:
+      host: redis.example.svc.cluster.local
+      port: 6379
+      authSecretRef:
+        name: redis-auth
+        namespace: __OVERRIDE_ME__
diff --git a/operator/test/utils/fixtures/vllm_cacheblend_deployment.yaml b/operator/test/utils/fixtures/vllm_cacheblend_deployment.yaml
new file mode 100644
index 0000000..09758f5
--- /dev/null
+++ b/operator/test/utils/fixtures/vllm_cacheblend_deployment.yaml
@@ -0,0 +1,92 @@
+# vLLM Deployment used by the e2e_gpu CacheBlend integration spec.
+#
+# Unlike vllm_deployment.yaml (the LMCacheEngine round-trip), this pod OPTS IN
+# to CacheBlend dependency injection via the mutating webhook. The webhook
+# appends the CacheBlend vLLM flags (--attention-backend CUSTOM,
+# --kv-transfer-config <engine>, --block-size 64, --pipeline-parallel-size 1,
+# --no-enable-chunked-prefill, --no-async-scheduling, --enforce-eager), the
+# cb-plugin init container + emptyDir + PYTHONPATH, hostIPC=true, and the
+# engine's payload imagePullSecrets.
+#
+# Placeholders substituted by the spec (substituteVLLMPlaceholders):
+#   __NAMESPACE__    — engine namespace (PSS-privileged; webhook injects hostIPC)
+#   __ENGINE_NAME__  — CacheBlendEngine metadata.name (bound via annotation)
+#   __MODEL__        — Hugging Face model id
+#   __VLLM_IMAGE__   — container image (default lmcache/vllm-openai:latest)
+#
+# CRITICAL: the vLLM container MUST launch via the image ENTRYPOINT
+# (["vllm","serve"]) with args ONLY. A `command:` override makes the webhook
+# SKIP injection (it stamps lmcache.ai/cacheblend-skip-reason=command-override)
+# because appended args can't reach `vllm serve`. Do NOT add --attention-backend
+# or --kv-transfer-config here — the webhook injects both.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-cacheblend
+  namespace: __NAMESPACE__
+  labels:
+    app: vllm-cacheblend
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-cacheblend
+  template:
+    metadata:
+      labels:
+        app: vllm-cacheblend
+        # OPT-IN: the webhook's objectSelector matches this label.
+        lmcache.ai/cacheblend-inject: "true"
+      annotations:
+        # BIND: names the CacheBlendEngine (same namespace) to inject for.
+        lmcache.ai/cacheblend-engine: "__ENGINE_NAME__"
+    spec:
+      # Needed for GPU access; the blend engine shares THIS pod's GPU via CUDA
+      # IPC, so engine + pod must land on the same GPU node.
+      runtimeClassName: nvidia
+      nodeSelector:
+        nvidia.com/gpu.present: "true"
+      # NOTE: do NOT set hostIPC here or mount an emptyDir at /dev/shm — the
+      # webhook injects hostIPC=true (shared host /dev/shm for CUDA IPC); an
+      # emptyDir would shadow it and break cudaIpcOpenMemHandle.
+      containers:
+        - name: vllm
+          image: __VLLM_IMAGE__
+          imagePullPolicy: IfNotPresent
+          # Args-only launch (image ENTRYPOINT is ["vllm","serve"]). --load-format
+          # dummy skips weight download (the smoke asserts startup + rope
+          # registration + HTTP 200, not generation quality). gpu-memory low so
+          # the node-local blend engine has headroom on the shared GPU.
+          args:
+            - "__MODEL__"
+            - "--port"
+            - "8000"
+            - "--gpu-memory-utilization"
+            - "0.5"
+            - "--load-format"
+            - "dummy"
+          env:
+            # Deterministic prefix hashing across processes — required by LMCache.
+            - name: PYTHONHASHSEED
+              value: "0"
+            - name: NVIDIA_VISIBLE_DEVICES
+              value: "all"
+            - name: NVIDIA_DRIVER_CAPABILITIES
+              value: "all"
+          ports:
+            - name: http
+              containerPort: 8000
+              protocol: TCP
+          resources:
+            limits:
+              nvidia.com/gpu: 1
+          readinessProbe:
+            httpGet:
+              path: /v1/models
+              port: 8000
+            # /v1/models is ready only after the model is loaded onto the GPU
+            # — a strong signal vLLM started AND the CacheBlend connector
+            # negotiated with the engine (otherwise vllm crashes during init).
+            initialDelaySeconds: 30
+            periodSeconds: 10
+            failureThreshold: 60
diff --git a/operator/test/utils/fixtures/vllm_deployment.yaml b/operator/test/utils/fixtures/vllm_deployment.yaml
new file mode 100644
index 0000000..aa9eab5
--- /dev/null
+++ b/operator/test/utils/fixtures/vllm_deployment.yaml
@@ -0,0 +1,122 @@
+# vLLM Deployment used by the e2e_gpu integration spec.
+#
+# Renders a single-replica vLLM serve, configured to reach the LMCache
+# DaemonSet via the operator-produced <engine>-connection ConfigMap.
+# Placeholders are substituted by the spec at apply time so the test
+# can target whichever namespace/engine/model the run was parameterised
+# with:
+#
+#   __NAMESPACE__       — engine namespace
+#   __ENGINE_NAME__     — LMCacheEngine metadata.name (also Service / ConfigMap name)
+#   __MODEL__           — Hugging Face model id (e.g., Qwen/Qwen2.5-0.5B)
+#   __VLLM_IMAGE__      — container image (defaults to lmcache/vllm-openai:latest,
+#                         the bundled vLLM + LMCache build)
+#
+# Requirements baked in (matching the operator's LMCache pod template
+# and the constraints of cudaIpcOpenMemHandle-based KV handoff):
+#   - hostIPC: true                — share /dev/shm with the LMCache pod
+#   - runtimeClassName: nvidia     — same as LMCache so they co-schedule
+#                                    on GPU nodes
+#   - nodeSelector: gpu.present    — pin to a GPU node so the service's
+#                                    internalTrafficPolicy=Local routes
+#                                    to the on-node LMCache pod
+#   - nvidia.com/gpu: 1            — consume one GPU device
+#   - --no-enable-prefix-caching   — REQUIRED: APC must be off so prompt
+#                                    re-runs miss vLLM's local KV and
+#                                    fall through to LMCache lookup
+#   - --kv-transfer-config         — inlined from the operator-produced
+#                                    ConfigMap by the entrypoint wrapper
+#                                    (vllm serve takes a JSON string,
+#                                    not a path)
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-smoke
+  namespace: __NAMESPACE__
+  labels:
+    app: vllm-smoke
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-smoke
+  template:
+    metadata:
+      labels:
+        app: vllm-smoke
+    spec:
+      hostIPC: true
+      runtimeClassName: nvidia
+      nodeSelector:
+        nvidia.com/gpu.present: "true"
+      containers:
+        - name: vllm
+          image: __VLLM_IMAGE__
+          imagePullPolicy: IfNotPresent
+          # vllm serve --kv-transfer-config takes the JSON connector
+          # config as a single argv token (string), so we read the
+          # mounted ConfigMap file inline via `cat`. Going through a
+          # shell wrapper keeps the JSON source of truth in the
+          # operator-produced ConfigMap rather than duplicated here.
+          #
+          # --load-format dummy: skip downloading the model weights
+          # from Hugging Face. vLLM still fetches the model's metadata
+          # (config.json, tokenizer.json) but generates random weights
+          # in-process. The test asserts on KV-cache hit counters, not
+          # on generation quality, so dummy weights are fine and we
+          # save several GB of download + ~5 min of test runtime.
+          command: ["/bin/sh", "-c"]
+          args:
+            - >-
+              exec vllm serve "__MODEL__"
+              --port 8000
+              --no-enable-prefix-caching
+              --enforce-eager
+              --load-format dummy
+              --gpu-memory-utilization 0.5
+              --kv-transfer-config "$(cat /etc/lmcache/kv-transfer-config.json)"
+          env:
+            # MP transport requires single-process scheduler so the
+            # connector lives in the same proc as the engine core.
+            - name: VLLM_ENABLE_V1_MULTIPROCESSING
+              value: "0"
+            # Determinism: same prompt -> same chunk hashes across runs
+            # so the cache lookup on the second request actually hits.
+            - name: PYTHONHASHSEED
+              value: "0"
+            - name: NVIDIA_VISIBLE_DEVICES
+              value: "all"
+            - name: NVIDIA_DRIVER_CAPABILITIES
+              value: "all"
+          ports:
+            - name: http
+              containerPort: 8000
+              protocol: TCP
+          resources:
+            limits:
+              nvidia.com/gpu: 1
+          readinessProbe:
+            httpGet:
+              path: /v1/models
+              port: 8000
+            # /v1/models is ready only after the model is loaded onto
+            # the GPU — a strong signal that the LMCache connector
+            # also negotiated successfully (otherwise vllm would have
+            # crashed during init).
+            initialDelaySeconds: 30
+            periodSeconds: 10
+            failureThreshold: 60
+          volumeMounts:
+            - name: lmcache-connection
+              mountPath: /etc/lmcache
+              readOnly: true
+      volumes:
+        - name: lmcache-connection
+          configMap:
+            # __ENGINE_NAME__-connection is owned by the LMCacheEngine
+            # so its lifecycle is tied to the CR — the test asserts on
+            # GC of this same ConfigMap in lifecycle_smoke_test.go.
+            name: __ENGINE_NAME__-connection
+            items:
+              - key: kv-transfer-config.json
+                path: kv-transfer-config.json
diff --git a/operator/test/utils/fixtures/vllm_lmcache_injection_deployment.yaml b/operator/test/utils/fixtures/vllm_lmcache_injection_deployment.yaml
new file mode 100644
index 0000000..313fecb
--- /dev/null
+++ b/operator/test/utils/fixtures/vllm_lmcache_injection_deployment.yaml
@@ -0,0 +1,49 @@
+# vLLM Deployment used by the M1 LMCache injection smoke spec.
+#
+# Unlike vllm_deployment.yaml (the e2e_gpu round-trip, which mounts the
+# connection ConfigMap and uses a `sh -c` wrapper), this pod OPTS IN to
+# LMCacheEngine dependency injection via the mutating webhook. The webhook
+# appends --kv-transfer-config <inline JSON>, sets hostIPC=true, and adds
+# PYTHONHASHSEED=0.
+#
+# The spec asserts the admission mutation directly off the pod object, so the
+# pod never needs to run — a tiny placeholder image keeps the smoke CPU-only and
+# avoids a multi-GB vLLM image pull on the Kind worker.
+#
+# Placeholders substituted by the spec:
+#   __NAMESPACE__    — engine namespace (PSS-privileged; webhook injects hostIPC)
+#   __ENGINE_NAME__  — LMCacheEngine metadata.name (bound via annotation)
+#
+# CRITICAL: launch args-only (no `command:` override) or the webhook SKIPs with
+# lmcache.ai/lmcache-skip-reason=command-override.
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vllm-lmcache-inject
+  namespace: __NAMESPACE__
+  labels:
+    app: vllm-lmcache-inject
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: vllm-lmcache-inject
+  template:
+    metadata:
+      labels:
+        app: vllm-lmcache-inject
+        # OPT-IN: the webhook's objectSelector matches this label.
+        lmcache.ai/lmcache-inject: "true"
+      annotations:
+        # BIND: names the LMCacheEngine (same namespace) to inject for.
+        lmcache.ai/lmcache-engine: "__ENGINE_NAME__"
+    spec:
+      containers:
+        - name: vllm
+          # Placeholder image: the pod is never expected to run — the spec only
+          # asserts the webhook's admission-time mutation on the pod spec.
+          image: busybox:1.36
+          args:
+            - "Qwen/Qwen2.5-0.5B"
+            - "--port"
+            - "8000"
diff --git a/operator/test/utils/http.go b/operator/test/utils/http.go
new file mode 100644
index 0000000..53c589f
--- /dev/null
+++ b/operator/test/utils/http.go
@@ -0,0 +1,157 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+
+	"k8s.io/apimachinery/pkg/util/wait"
+)
+
+// httpJSONClient is the shared client used by HTTP helpers. We do NOT
+// set Client.Timeout because that cap would override the caller's
+// context deadline — and callers like the vLLM-integration spec need
+// minutes-long deadlines for cold-cache completions. Every helper here
+// uses NewRequestWithContext, so cancellation is governed entirely by
+// the caller's ctx.
+//
+// DisableKeepAlives is on purpose: every test request goes through a
+// `kubectl port-forward` proxy that quietly drops idle TCP connections
+// after a few seconds. With keep-alive on, the second HTTP call in a
+// spec ends up trying to reuse a dead connection and gets EOF before
+// the request even reaches the upstream. Re-establishing the TCP
+// connection per request costs a few ms in tests; the alternative is
+// flaky failures that look like upstream crashes when they aren't.
+var httpJSONClient = &http.Client{
+	Transport: &http.Transport{DisableKeepAlives: true},
+}
+
+// HTTPGetJSON issues a GET against url and decodes the response body
+// into out. Returns an error if the request fails, the status is not
+// 2xx, or the body is not valid JSON. The caller owns out's lifetime.
+func HTTPGetJSON(ctx context.Context, url string, out any) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return fmt.Errorf("build GET %s: %w", url, err)
+	}
+	resp, err := httpJSONClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("GET %s: %w", url, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("read GET %s body: %w", url, err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("GET %s: status %d body=%s", url, resp.StatusCode, string(body))
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.Unmarshal(body, out); err != nil {
+		return fmt.Errorf("decode JSON from GET %s: %w\nbody=%s", url, err, string(body))
+	}
+	return nil
+}
+
+// HTTPGetText issues a GET against url and returns the raw response
+// body as a string. Used for endpoints that don't speak JSON
+// (Prometheus text exposition at /metrics).
+func HTTPGetText(ctx context.Context, url string) (string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		return "", fmt.Errorf("build GET %s: %w", url, err)
+	}
+	resp, err := httpJSONClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("GET %s: %w", url, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("read GET %s body: %w", url, err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return "", fmt.Errorf("GET %s: status %d body=%s", url, resp.StatusCode, string(body))
+	}
+	return string(body), nil
+}
+
+// HTTPPostJSON issues a POST with a JSON-encoded body and decodes the
+// 2xx response body into out (when non-nil). Returns the parsed JSON
+// status code so callers that care about distinguishing 200 vs 201 can
+// check it themselves.
+func HTTPPostJSON(ctx context.Context, url string, body, out any) error {
+	buf, err := json.Marshal(body)
+	if err != nil {
+		return fmt.Errorf("encode POST %s body: %w", url, err)
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(buf))
+	if err != nil {
+		return fmt.Errorf("build POST %s: %w", url, err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := httpJSONClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("POST %s: %w", url, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("read POST %s body: %w", url, err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("POST %s: status %d body=%s", url, resp.StatusCode, string(respBody))
+	}
+	if out == nil {
+		return nil
+	}
+	if err := json.Unmarshal(respBody, out); err != nil {
+		return fmt.Errorf("decode JSON from POST %s: %w\nbody=%s", url, err, string(respBody))
+	}
+	return nil
+}
+
+// WaitHTTP200 polls url with GET until it returns 2xx or the timeout
+// elapses. Tighter than HTTPGetJSON because it tolerates transient
+// connection-refused / status-503 noise during pod startup: the LMCache
+// HTTP frontend is reachable on the readiness-probed port (TCP-readiness
+// just confirms the ZMQ socket is bound), and the FastAPI app may not
+// have finished initializing yet. The poll absorbs that race so the
+// caller's assertion runs against a fully-ready server.
+func WaitHTTP200(ctx context.Context, url string, timeout time.Duration) error {
+	return wait.PollUntilContextTimeout(ctx, time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+		if err != nil {
+			return false, err
+		}
+		resp, err := httpJSONClient.Do(req)
+		if err != nil {
+			return false, nil
+		}
+		_, _ = io.Copy(io.Discard, resp.Body)
+		_ = resp.Body.Close()
+		return resp.StatusCode >= 200 && resp.StatusCode < 300, nil
+	})
+}
diff --git a/operator/test/utils/lmc.go b/operator/test/utils/lmc.go
new file mode 100644
index 0000000..f5828ec
--- /dev/null
+++ b/operator/test/utils/lmc.go
@@ -0,0 +1,210 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/apimachinery/pkg/util/wait"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	lmcachev1alpha1 "github.com/LMCache/LMCache/api/v1alpha1"
+)
+
+// KvTransferConfig is the typed schema of the kv-transfer-config.json
+// document produced by the operator into the <name>-connection ConfigMap.
+// Field tags mirror the JSON keys that vLLM's --kv-transfer-config expects.
+type KvTransferConfig struct {
+	KVConnector            string                 `json:"kv_connector"`
+	KVConnectorModulePath  string                 `json:"kv_connector_module_path"`
+	KVRole                 string                 `json:"kv_role"`
+	KVConnectorExtraConfig KvConnectorExtraConfig `json:"kv_connector_extra_config"`
+}
+
+// KvConnectorExtraConfig holds the LMCache MP-mode connection string the
+// vLLM connector uses to reach the LMCache server. The keys contain dots
+// — vLLM treats them as flat strings, not nested paths.
+type KvConnectorExtraConfig struct {
+	Host string `json:"lmcache.mp.host"`
+	Port string `json:"lmcache.mp.port"`
+}
+
+// ApplyLMC creates the LMCacheEngine if absent, or patches it (spec only)
+// if it already exists. The status subresource is left untouched.
+func ApplyLMC(ctx context.Context, c client.Client, lmc *lmcachev1alpha1.LMCacheEngine) error {
+	existing := &lmcachev1alpha1.LMCacheEngine{}
+	err := c.Get(ctx, client.ObjectKeyFromObject(lmc), existing)
+	if apierrors.IsNotFound(err) {
+		return c.Create(ctx, lmc)
+	}
+	if err != nil {
+		return fmt.Errorf("get LMCacheEngine %s/%s: %w", lmc.Namespace, lmc.Name, err)
+	}
+	patch := client.MergeFrom(existing.DeepCopy())
+	existing.Spec = lmc.Spec
+	existing.Labels = lmc.Labels
+	existing.Annotations = lmc.Annotations
+	if err := c.Patch(ctx, existing, patch); err != nil {
+		return fmt.Errorf("patch LMCacheEngine %s/%s: %w", lmc.Namespace, lmc.Name, err)
+	}
+	*lmc = *existing
+	return nil
+}
+
+// WaitLMCReconciled polls until status.observedGeneration matches the
+// CR's metadata.generation AND the ConfigValid condition is True. This
+// is the readiness signal for the no-GPU smoke tier — pods do not need
+// to be Running for the operator to have produced its K8s artifacts.
+func WaitLMCReconciled(ctx context.Context, c client.Client, key types.NamespacedName, timeout time.Duration) error {
+	return wait.PollUntilContextTimeout(ctx, time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		lmc := &lmcachev1alpha1.LMCacheEngine{}
+		if err := c.Get(ctx, key, lmc); err != nil {
+			if apierrors.IsNotFound(err) {
+				return false, nil
+			}
+			return false, err
+		}
+		if lmc.Generation == 0 || lmc.Status.ObservedGeneration != lmc.Generation {
+			return false, nil
+		}
+		cond := meta.FindStatusCondition(lmc.Status.Conditions, lmcachev1alpha1.ConditionConfigValid)
+		return cond != nil && cond.Status == "True", nil
+	})
+}
+
+// WaitLMCPhase polls until status.phase equals the requested phase value
+// (e.g. "Running", "Pending"). Use WaitLMCReconciled instead when the
+// observation contract is "controller saw the spec," not "pods are up."
+func WaitLMCPhase(
+	ctx context.Context,
+	c client.Client,
+	key types.NamespacedName,
+	phase string,
+	timeout time.Duration,
+) error {
+	return wait.PollUntilContextTimeout(ctx, time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		lmc := &lmcachev1alpha1.LMCacheEngine{}
+		if err := c.Get(ctx, key, lmc); err != nil {
+			if apierrors.IsNotFound(err) {
+				return false, nil
+			}
+			return false, err
+		}
+		return lmc.Status.Phase == phase, nil
+	})
+}
+
+// WaitLMCReady is a thin alias for WaitLMCPhase("Running"). It exists
+// because the GPU tier (M3) reads more naturally as "wait until ready"
+// — the no-GPU tier should not call this.
+func WaitLMCReady(ctx context.Context, c client.Client, key types.NamespacedName, timeout time.Duration) error {
+	return WaitLMCPhase(ctx, c, key, lmcachev1alpha1.PhaseRunning, timeout)
+}
+
+// GetConnectionConfig fetches the <name>-connection ConfigMap and parses
+// kv-transfer-config.json into a typed struct. Returns an error if the
+// ConfigMap is missing, the data key is missing, or the JSON is invalid.
+func GetConnectionConfig(ctx context.Context, c client.Client, key types.NamespacedName) (*KvTransferConfig, error) {
+	cm := &corev1.ConfigMap{}
+	cmKey := types.NamespacedName{Namespace: key.Namespace, Name: key.Name + "-connection"}
+	if err := c.Get(ctx, cmKey, cm); err != nil {
+		return nil, fmt.Errorf("get ConfigMap %s: %w", cmKey, err)
+	}
+	raw, ok := cm.Data["kv-transfer-config.json"]
+	if !ok {
+		return nil, fmt.Errorf("ConfigMap %s missing key kv-transfer-config.json", cmKey)
+	}
+	cfg := &KvTransferConfig{}
+	if err := json.Unmarshal([]byte(raw), cfg); err != nil {
+		return nil, fmt.Errorf("decode kv-transfer-config.json: %w", err)
+	}
+	return cfg, nil
+}
+
+// PatchLMCSpec re-fetches the CR, applies mutate to the spec, and submits
+// a merge patch. The mutate callback receives a pointer to the spec and
+// must mutate in place. Use this for tests like the port-update spec
+// that need to model "user kubectl-patches the spec."
+func PatchLMCSpec(
+	ctx context.Context,
+	c client.Client,
+	key types.NamespacedName,
+	mutate func(*lmcachev1alpha1.LMCacheEngineSpec),
+) error {
+	lmc := &lmcachev1alpha1.LMCacheEngine{}
+	if err := c.Get(ctx, key, lmc); err != nil {
+		return fmt.Errorf("get LMCacheEngine %s: %w", key, err)
+	}
+	patch := client.MergeFrom(lmc.DeepCopy())
+	mutate(&lmc.Spec)
+	return c.Patch(ctx, lmc, patch)
+}
+
+// DeleteLMCAndWaitGC issues a foreground delete on the CR and waits until
+// both the CR and its primary owned resources (DaemonSet, lookup Service,
+// connection ConfigMap) are gone. Times out if a finalizer is stuck.
+func DeleteLMCAndWaitGC(ctx context.Context, c client.Client, key types.NamespacedName, timeout time.Duration) error {
+	lmc := &lmcachev1alpha1.LMCacheEngine{}
+	if err := c.Get(ctx, key, lmc); err != nil {
+		if apierrors.IsNotFound(err) {
+			return nil
+		}
+		return fmt.Errorf("get LMCacheEngine %s: %w", key, err)
+	}
+	if err := c.Delete(ctx, lmc); err != nil && !apierrors.IsNotFound(err) {
+		return fmt.Errorf("delete LMCacheEngine %s: %w", key, err)
+	}
+
+	cmKey := types.NamespacedName{Namespace: key.Namespace, Name: key.Name + "-connection"}
+	return wait.PollUntilContextTimeout(ctx, time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		if exists, err := objectExists(ctx, c, key, &lmcachev1alpha1.LMCacheEngine{}); err != nil || exists {
+			return false, err
+		}
+		if exists, err := objectExists(ctx, c, key, &appsv1.DaemonSet{}); err != nil || exists {
+			return false, err
+		}
+		if exists, err := objectExists(ctx, c, key, &corev1.Service{}); err != nil || exists {
+			return false, err
+		}
+		if exists, err := objectExists(ctx, c, cmKey, &corev1.ConfigMap{}); err != nil || exists {
+			return false, err
+		}
+		return true, nil
+	})
+}
+
+// objectExists returns true if the object at key still exists in the API.
+// It treats NotFound as the only "absent" signal; any other error is
+// surfaced so the caller can distinguish transient API failures.
+func objectExists(ctx context.Context, c client.Client, key types.NamespacedName, obj client.Object) (bool, error) {
+	err := c.Get(ctx, key, obj)
+	if err == nil {
+		return true, nil
+	}
+	if apierrors.IsNotFound(err) {
+		return false, nil
+	}
+	return false, err
+}
diff --git a/operator/test/utils/portforward.go b/operator/test/utils/portforward.go
new file mode 100644
index 0000000..184cc32
--- /dev/null
+++ b/operator/test/utils/portforward.go
@@ -0,0 +1,173 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"fmt"
+	"net"
+	"os/exec"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// PortForwardSpec identifies what kubectl port-forward should target.
+// Target follows the kubectl convention (e.g. "svc/my-cache",
+// "pod/my-cache-abc", "deployment/my-cache").
+type PortForwardSpec struct {
+	Namespace string
+	Target    string
+}
+
+// PortForward starts a `kubectl port-forward` subprocess and waits until
+// the first local port begins accepting TCP connections. Each port arg
+// follows kubectl syntax: "LOCAL:REMOTE" or just "PORT" (where the local
+// and remote ports are equal). A LOCAL of "0" is replaced with a
+// kernel-picked free port chosen before kubectl starts, so concurrent
+// specs in the same run never collide on a fixed local port.
+//
+// Returns:
+//   - closer: must be called to terminate the subprocess and free ports.
+//     Safe to call multiple times.
+//   - localBase: "http://127.0.0.1:<localport>" using the first port mapping.
+//
+// Namespace is passed via the spec struct rather than encoded into
+// target because kubectl requires namespace as a separate -n flag
+// and silently ignores prefixes embedded in the target string.
+func PortForward(spec PortForwardSpec, ports ...string) (func(), string, error) {
+	if len(ports) == 0 {
+		return nil, "", fmt.Errorf("PortForward: at least one port mapping is required")
+	}
+
+	// Substitute "0:REMOTE" and "0" with a concrete kernel-picked port
+	// in every mapping. We resolve the port BEFORE invoking kubectl
+	// because kubectl's "LOCAL=0 => pick one" mode writes the chosen
+	// port to stdout asynchronously, which is racy to scrape — and
+	// because the first mapping's local port is what waitForLocalPort
+	// + the returned localBase URL refer to. The race between Close+
+	// kubectl-bind is acceptable: we don't run concurrent forwards in
+	// the same spec, and other processes binding ephemerals during that
+	// microsecond is highly unlikely.
+	resolved := make([]string, len(ports))
+	for i, p := range ports {
+		r, err := resolvePortMapping(p)
+		if err != nil {
+			return nil, "", err
+		}
+		resolved[i] = r
+	}
+	localPort, err := localPortFromMapping(resolved[0])
+	if err != nil {
+		return nil, "", err
+	}
+
+	args := []string{"port-forward"}
+	if spec.Namespace != "" {
+		args = append(args, "-n", spec.Namespace)
+	}
+	args = append(args, spec.Target)
+	args = append(args, resolved...)
+
+	cmd := exec.Command("kubectl", args...)
+	if err := cmd.Start(); err != nil {
+		return nil, "", fmt.Errorf("start kubectl port-forward: %w", err)
+	}
+
+	closer := func() {
+		// Killing the process is sufficient — kubectl port-forward
+		// closes the listener on SIGKILL, freeing the local port.
+		// We drop the Wait error because once we kill, the typical
+		// exit status is "signal: killed" which is expected.
+		_ = cmd.Process.Kill()
+		_, _ = cmd.Process.Wait()
+	}
+
+	if err := waitForLocalPort(localPort, 30*time.Second); err != nil {
+		closer()
+		return nil, "", fmt.Errorf("port-forward to %s/%s did not become ready: %w",
+			spec.Namespace, spec.Target, err)
+	}
+	return closer, fmt.Sprintf("http://127.0.0.1:%d", localPort), nil
+}
+
+// resolvePortMapping replaces a "0:REMOTE" mapping (or bare "0") with
+// "<picked>:REMOTE" using a kernel-allocated ephemeral port. Mappings
+// that already specify a concrete LOCAL pass through unchanged.
+func resolvePortMapping(mapping string) (string, error) {
+	parts := strings.SplitN(mapping, ":", 2)
+	local := parts[0]
+	if local != "0" {
+		return mapping, nil
+	}
+	picked, err := pickEphemeralPort()
+	if err != nil {
+		return "", fmt.Errorf("pick ephemeral local port: %w", err)
+	}
+	if len(parts) == 1 {
+		// "0" alone is ambiguous — there's no remote to forward to.
+		return "", fmt.Errorf("invalid port mapping %q: LOCAL=0 requires an explicit :REMOTE", mapping)
+	}
+	return fmt.Sprintf("%d:%s", picked, parts[1]), nil
+}
+
+// pickEphemeralPort asks the kernel for a free TCP port on 127.0.0.1
+// and immediately releases it. There is a small race window between
+// release and kubectl re-binding; tests don't run forwards concurrently
+// inside a single spec, and parallel host workloads rarely steal the
+// exact port in that microsecond.
+func pickEphemeralPort() (int, error) {
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return 0, err
+	}
+	port := l.Addr().(*net.TCPAddr).Port
+	if err := l.Close(); err != nil {
+		return 0, err
+	}
+	return port, nil
+}
+
+// localPortFromMapping extracts the LOCAL port from a kubectl mapping
+// of the form "LOCAL:REMOTE" or just "PORT" (where the local and remote
+// ports are equal). Expects LOCAL to already be a concrete integer —
+// the "0" case is handled by resolvePortMapping upstream.
+func localPortFromMapping(mapping string) (int, error) {
+	parts := strings.SplitN(mapping, ":", 2)
+	p, err := strconv.Atoi(parts[0])
+	if err != nil {
+		return 0, fmt.Errorf("invalid port mapping %q: %w", mapping, err)
+	}
+	return p, nil
+}
+
+// waitForLocalPort polls 127.0.0.1:port until a TCP connection succeeds
+// or timeout elapses. kubectl port-forward briefly accepts connections
+// and immediately closes them once before the upstream is wired, so we
+// also require the connection to stay open long enough to write to.
+func waitForLocalPort(port int, timeout time.Duration) error {
+	deadline := time.Now().Add(timeout)
+	addr := fmt.Sprintf("127.0.0.1:%d", port)
+	for time.Now().Before(deadline) {
+		conn, err := net.DialTimeout("tcp", addr, 500*time.Millisecond)
+		if err == nil {
+			_ = conn.Close()
+			return nil
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+	return fmt.Errorf("local port %d not reachable after %s", port, timeout)
+}
diff --git a/operator/test/utils/runner.go b/operator/test/utils/runner.go
new file mode 100644
index 0000000..d0898da
--- /dev/null
+++ b/operator/test/utils/runner.go
@@ -0,0 +1,65 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+// operatorRoot resolves to the absolute path of the operator/ directory,
+// derived at compile time from this file's location. Unlike GetProjectDir,
+// this does not depend on the current working directory and never calls
+// os.Chdir, so tests can run from any working directory.
+var operatorRoot = func() string {
+	_, thisFile, _, ok := runtime.Caller(0)
+	if !ok {
+		// Should never happen — runtime.Caller(0) only fails if the
+		// stack has fewer frames than requested.
+		panic("utils.operatorRoot: runtime.Caller failed")
+	}
+	// thisFile = <repo>/operator/test/utils/runner.go
+	return filepath.Clean(filepath.Join(filepath.Dir(thisFile), "..", ".."))
+}()
+
+// OperatorRoot returns the absolute path of the operator/ directory.
+func OperatorRoot() string {
+	return operatorRoot
+}
+
+// RunFromOperator runs an exec.Cmd with cmd.Dir set to the operator/ root.
+// It does not modify the process working directory. Output is captured
+// and returned as a single string; on non-zero exit, the error wraps
+// the combined output.
+func RunFromOperator(cmd *exec.Cmd) (string, error) {
+	cmd.Dir = operatorRoot
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		return string(out), fmt.Errorf("%s failed: %w\n%s", strings.Join(cmd.Args, " "), err, string(out))
+	}
+	return string(out), nil
+}
+
+// RunMake runs `make <args...>` from the operator/ directory and returns
+// the combined output. It is the no-Chdir replacement for the working-
+// directory hack in utils.Run.
+func RunMake(args ...string) (string, error) {
+	return RunFromOperator(exec.Command("make", args...))
+}
diff --git a/operator/test/utils/secret.go b/operator/test/utils/secret.go
new file mode 100644
index 0000000..b7a33a1
--- /dev/null
+++ b/operator/test/utils/secret.go
@@ -0,0 +1,92 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// CreateDockerConfigJSONSecret creates a kubernetes.io/dockerconfigjson pull
+// Secret in the given namespace, equivalent to
+//
+//	kubectl create secret docker-registry <name> \
+//	  --docker-server=<server> --docker-username=<username> --docker-password=<password>
+//
+// It is used by the GPU smoke tier to pull the PRIVATE cacheblend-plugin
+// payload image: the credentials arrive as env vars (e.g. from the Buildkite
+// pipeline secret store) and this Secret is referenced by the engine's
+// injection.imagePullSecrets, which the mutating webhook appends to the vLLM
+// pod that runs the payload init container.
+//
+// The Secret is recreated (delete-then-create) if one of the same name already
+// exists so reruns against a reused namespace pick up rotated credentials. The
+// password is never logged.
+func CreateDockerConfigJSONSecret(
+	ctx context.Context,
+	c client.Client,
+	namespace, name, server, username, password string,
+) error {
+	if server == "" || username == "" || password == "" {
+		return fmt.Errorf(
+			"docker-registry secret %s/%s: server, username and password are all required", namespace, name)
+	}
+
+	// .dockerconfigjson schema: {"auths":{"<server>":{username,password,auth}}}.
+	// "auth" is base64(username:password) — Docker reads this field; username
+	// and password are kept too for tooling that inspects the entry.
+	auth := base64.StdEncoding.EncodeToString([]byte(username + ":" + password))
+	dockerCfg := map[string]any{
+		"auths": map[string]any{
+			server: map[string]any{
+				"username": username,
+				"password": password,
+				"auth":     auth,
+			},
+		},
+	}
+	raw, err := json.Marshal(dockerCfg)
+	if err != nil {
+		return fmt.Errorf("marshal dockerconfigjson for %s/%s: %w", namespace, name, err)
+	}
+
+	secret := &corev1.Secret{
+		ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: namespace},
+		Type:       corev1.SecretTypeDockerConfigJson,
+		Data:       map[string][]byte{corev1.DockerConfigJsonKey: raw},
+	}
+
+	err = c.Create(ctx, secret)
+	if apierrors.IsAlreadyExists(err) {
+		existing := &corev1.Secret{ObjectMeta: metav1.ObjectMeta{Name: name, Namespace: namespace}}
+		if delErr := c.Delete(ctx, existing); delErr != nil && !apierrors.IsNotFound(delErr) {
+			return fmt.Errorf("replace docker-registry secret %s/%s: delete: %w", namespace, name, delErr)
+		}
+		err = c.Create(ctx, secret)
+	}
+	if err != nil {
+		return fmt.Errorf("create docker-registry secret %s/%s: %w", namespace, name, err)
+	}
+	return nil
+}
diff --git a/operator/test/utils/utils.go b/operator/test/utils/utils.go
new file mode 100644
index 0000000..7f73b22
--- /dev/null
+++ b/operator/test/utils/utils.go
@@ -0,0 +1,212 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"bufio"
+	"bytes"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+
+	. "github.com/onsi/ginkgo/v2" // nolint:revive,staticcheck
+)
+
+const (
+	defaultKindBinary  = "kind"
+	defaultKindCluster = "kind"
+
+	// certManagerDefaultVersion is the cert-manager release installed on the
+	// target cluster when none is already present. cert-manager is a hard
+	// prerequisite for the operator's mutating admission webhook: it mints the
+	// serving certificate (config/certmanager) and injects the CA bundle into
+	// the MutatingWebhookConfiguration. Override with CERT_MANAGER_VERSION.
+	certManagerDefaultVersion = "v1.16.3"
+	// certManagerManifestURLTmpl is the upstream static install manifest,
+	// parameterised by release tag.
+	certManagerManifestURLTmpl = "https://github.com/cert-manager/cert-manager/releases/download/%s/cert-manager.yaml"
+)
+
+// certManagerVersion returns the cert-manager release to install, honoring the
+// CERT_MANAGER_VERSION env var and falling back to certManagerDefaultVersion.
+func certManagerVersion() string {
+	if v := os.Getenv("CERT_MANAGER_VERSION"); v != "" {
+		return v
+	}
+	return certManagerDefaultVersion
+}
+
+// IsCertManagerCRDsInstalled reports whether cert-manager's CRDs are already
+// registered in the target cluster. Used to skip installation (and teardown)
+// when running against a cluster that ships cert-manager (e.g. a shared
+// OpenShift/EKS cluster), so the suite never uninstalls something it did not
+// install.
+func IsCertManagerCRDsInstalled() bool {
+	cmd := exec.Command("kubectl", "get", "crd", "certificates.cert-manager.io", "--ignore-not-found=true")
+	out, err := Run(cmd)
+	if err != nil {
+		return false
+	}
+	return strings.Contains(out, "certificates.cert-manager.io")
+}
+
+// InstallCertManager applies the upstream cert-manager static manifest and
+// blocks until its controller, webhook, and CA-injector Deployments report
+// Available. cert-manager must be ready before `make deploy` applies the
+// operator's Issuer/Certificate and the CA-injected webhook, otherwise the
+// apply is rejected (unknown cert-manager.io kinds) and the serving-cert
+// secret the controller-manager mounts never materialises.
+func InstallCertManager() error {
+	url := fmt.Sprintf(certManagerManifestURLTmpl, certManagerVersion())
+	if _, err := Run(exec.Command("kubectl", "apply", "-f", url)); err != nil {
+		return fmt.Errorf("failed to apply cert-manager manifest %q: %w", url, err)
+	}
+	for _, deploy := range []string{"cert-manager", "cert-manager-webhook", "cert-manager-cainjector"} {
+		cmd := exec.Command("kubectl", "wait", "deployment/"+deploy,
+			"--for=condition=Available",
+			"--namespace=cert-manager",
+			"--timeout=5m",
+		)
+		if _, err := Run(cmd); err != nil {
+			return fmt.Errorf("cert-manager deployment %q did not become Available: %w", deploy, err)
+		}
+	}
+	return nil
+}
+
+// UninstallCertManager removes the cert-manager release installed by
+// InstallCertManager. Best-effort: failures are logged to GinkgoWriter rather
+// than failing the suite, since teardown runs after the specs have reported.
+func UninstallCertManager() {
+	url := fmt.Sprintf(certManagerManifestURLTmpl, certManagerVersion())
+	if _, err := Run(exec.Command("kubectl", "delete", "-f", url, "--ignore-not-found=true")); err != nil {
+		_, _ = fmt.Fprintf(GinkgoWriter, "warning: cert-manager uninstall failed: %v\n", err)
+	}
+}
+
+// Run executes the provided command within this context
+func Run(cmd *exec.Cmd) (string, error) {
+	dir, _ := GetProjectDir()
+	cmd.Dir = dir
+
+	if err := os.Chdir(cmd.Dir); err != nil {
+		_, _ = fmt.Fprintf(GinkgoWriter, "chdir dir: %q\n", err)
+	}
+
+	cmd.Env = append(os.Environ(), "GO111MODULE=on")
+	command := strings.Join(cmd.Args, " ")
+	_, _ = fmt.Fprintf(GinkgoWriter, "running: %q\n", command)
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		return string(output), fmt.Errorf("%q failed with error %q: %w", command, string(output), err)
+	}
+
+	return string(output), nil
+}
+
+// LoadImageToKindClusterWithName loads a local docker image to the kind cluster
+func LoadImageToKindClusterWithName(name string) error {
+	cluster := defaultKindCluster
+	if v, ok := os.LookupEnv("KIND_CLUSTER"); ok {
+		cluster = v
+	}
+	kindOptions := []string{"load", "docker-image", name, "--name", cluster}
+	kindBinary := defaultKindBinary
+	if v, ok := os.LookupEnv("KIND"); ok {
+		kindBinary = v
+	}
+	cmd := exec.Command(kindBinary, kindOptions...)
+	_, err := Run(cmd)
+	return err
+}
+
+// GetNonEmptyLines converts given command output string into individual objects
+// according to line breakers, and ignores the empty elements in it.
+func GetNonEmptyLines(output string) []string {
+	var res []string
+	elements := strings.SplitSeq(output, "\n")
+	for element := range elements {
+		if element != "" {
+			res = append(res, element)
+		}
+	}
+
+	return res
+}
+
+// GetProjectDir will return the directory where the project is
+func GetProjectDir() (string, error) {
+	wd, err := os.Getwd()
+	if err != nil {
+		return wd, fmt.Errorf("failed to get current working directory: %w", err)
+	}
+	wd = strings.ReplaceAll(wd, "/test/e2e", "")
+	return wd, nil
+}
+
+// UncommentCode searches for target in the file and remove the comment prefix
+// of the target content. The target content may span multiple lines.
+func UncommentCode(filename, target, prefix string) error {
+	// false positive
+	// nolint:gosec
+	content, err := os.ReadFile(filename)
+	if err != nil {
+		return fmt.Errorf("failed to read file %q: %w", filename, err)
+	}
+	strContent := string(content)
+
+	idx := strings.Index(strContent, target)
+	if idx < 0 {
+		return fmt.Errorf("unable to find the code %q to be uncommented", target)
+	}
+
+	out := new(bytes.Buffer)
+	_, err = out.Write(content[:idx])
+	if err != nil {
+		return fmt.Errorf("failed to write to output: %w", err)
+	}
+
+	scanner := bufio.NewScanner(bytes.NewBufferString(target))
+	if !scanner.Scan() {
+		return nil
+	}
+	for {
+		if _, err = out.WriteString(strings.TrimPrefix(scanner.Text(), prefix)); err != nil {
+			return fmt.Errorf("failed to write to output: %w", err)
+		}
+		// Avoid writing a newline in case the previous line was the last in target.
+		if !scanner.Scan() {
+			break
+		}
+		if _, err = out.WriteString("\n"); err != nil {
+			return fmt.Errorf("failed to write to output: %w", err)
+		}
+	}
+
+	if _, err = out.Write(content[idx+len(target):]); err != nil {
+		return fmt.Errorf("failed to write to output: %w", err)
+	}
+
+	// false positive
+	// nolint:gosec
+	if err = os.WriteFile(filename, out.Bytes(), 0644); err != nil {
+		return fmt.Errorf("failed to write file %q: %w", filename, err)
+	}
+
+	return nil
+}
diff --git a/operator/test/utils/wait.go b/operator/test/utils/wait.go
new file mode 100644
index 0000000..d5f9fdf
--- /dev/null
+++ b/operator/test/utils/wait.go
@@ -0,0 +1,176 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package utils
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	appsv1 "k8s.io/api/apps/v1"
+	corev1 "k8s.io/api/core/v1"
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/apimachinery/pkg/util/wait"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// WaitDaemonSetPodReady waits until at least one pod selected by the
+// DaemonSet's pod selector reports a Ready=True condition. Returns the
+// name of the first Ready pod so the caller can target it with
+// port-forward (kubectl port-forward needs a stable pod name; selecting
+// the DaemonSet directly is flaky when multiple pods exist on a
+// multi-node cluster). The DaemonSet's TCP readiness probe binds the
+// LMCache server, so once the pod is Ready the HTTP frontend is also
+// (very nearly) up — the caller should still retry HTTP calls briefly.
+func WaitDaemonSetPodReady(
+	ctx context.Context,
+	c client.Client,
+	key types.NamespacedName,
+	timeout time.Duration,
+) (string, error) {
+	var podName string
+	err := wait.PollUntilContextTimeout(ctx, 2*time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		ds := &appsv1.DaemonSet{}
+		if err := c.Get(ctx, key, ds); err != nil {
+			if apierrors.IsNotFound(err) {
+				return false, nil
+			}
+			return false, err
+		}
+		pods := &corev1.PodList{}
+		if err := c.List(ctx, pods,
+			client.InNamespace(key.Namespace),
+			client.MatchingLabels(ds.Spec.Selector.MatchLabels),
+		); err != nil {
+			return false, err
+		}
+		for i := range pods.Items {
+			p := &pods.Items[i]
+			if p.DeletionTimestamp != nil {
+				continue
+			}
+			if p.Status.Phase != corev1.PodRunning {
+				continue
+			}
+			for _, cond := range p.Status.Conditions {
+				if cond.Type == corev1.PodReady && cond.Status == corev1.ConditionTrue {
+					podName = p.Name
+					return true, nil
+				}
+			}
+		}
+		return false, nil
+	})
+	if err != nil {
+		return "", fmt.Errorf("wait DaemonSet %s pod Ready: %w", key, err)
+	}
+	return podName, nil
+}
+
+// WaitDeploymentAvailable polls a Deployment until its Available
+// condition is True. Used to gate test logic on vLLM (or any other
+// auxiliary workload) being fully scheduled and accepting traffic.
+// We intentionally key off the Available condition rather than
+// ReadyReplicas because Available encodes the rolling-update completion
+// semantics — ReadyReplicas can flap during a fresh rollout even on a
+// clean cluster.
+func WaitDeploymentAvailable(
+	ctx context.Context,
+	c client.Client,
+	key types.NamespacedName,
+	timeout time.Duration,
+) error {
+	return wait.PollUntilContextTimeout(ctx, 2*time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		dep := &appsv1.Deployment{}
+		if err := c.Get(ctx, key, dep); err != nil {
+			if apierrors.IsNotFound(err) {
+				return false, nil
+			}
+			return false, err
+		}
+		for _, cond := range dep.Status.Conditions {
+			if cond.Type == appsv1.DeploymentAvailable && cond.Status == corev1.ConditionTrue {
+				return true, nil
+			}
+		}
+		return false, nil
+	})
+}
+
+// WaitDeploymentAvailableOrImagePullError is WaitDeploymentAvailable with a
+// fast-fail short-circuit: it returns a descriptive error the moment any pod
+// selected by the Deployment has a container or init container wedged in
+// ImagePullBackOff. A wrong image/tag, a missing pull Secret, or a credential
+// without pull access never resolves on its own, so blocking for the full
+// timeout only delays a guaranteed failure (and buries the registry's own
+// error message, which ImagePullBackOff's waiting state carries verbatim).
+// Returns nil once Available, the pull error when a pull is wedged, or the
+// poll timeout error otherwise.
+func WaitDeploymentAvailableOrImagePullError(
+	ctx context.Context,
+	c client.Client,
+	key types.NamespacedName,
+	timeout time.Duration,
+) error {
+	return wait.PollUntilContextTimeout(ctx, 2*time.Second, timeout, true, func(ctx context.Context) (bool, error) {
+		dep := &appsv1.Deployment{}
+		if err := c.Get(ctx, key, dep); err != nil {
+			if apierrors.IsNotFound(err) {
+				return false, nil
+			}
+			return false, err
+		}
+		for _, cond := range dep.Status.Conditions {
+			if cond.Type == appsv1.DeploymentAvailable && cond.Status == corev1.ConditionTrue {
+				return true, nil
+			}
+		}
+		if msg := imagePullBackOff(ctx, c, key.Namespace, dep.Spec.Selector.MatchLabels); msg != "" {
+			return false, fmt.Errorf(
+				"deployment %s will never become Available — image pull wedged: %s", key, msg)
+		}
+		return false, nil
+	})
+}
+
+// imagePullBackOff scans pods matching sel and returns a one-line description
+// (pod, container, image, kubelet message) of the first container or init
+// container in ImagePullBackOff, or "" if none. The kubelet message is the
+// registry's own error (e.g. "pull access denied" / "manifest unknown"), which
+// is what a caller needs to tell a credential problem from a wrong tag.
+func imagePullBackOff(ctx context.Context, c client.Client, ns string, sel map[string]string) string {
+	pods := &corev1.PodList{}
+	if err := c.List(ctx, pods, client.InNamespace(ns), client.MatchingLabels(sel)); err != nil {
+		return ""
+	}
+	for i := range pods.Items {
+		p := &pods.Items[i]
+		if p.DeletionTimestamp != nil {
+			continue
+		}
+		statuses := append(append([]corev1.ContainerStatus{},
+			p.Status.InitContainerStatuses...), p.Status.ContainerStatuses...)
+		for _, cs := range statuses {
+			if w := cs.State.Waiting; w != nil && w.Reason == "ImagePullBackOff" {
+				return fmt.Sprintf("pod %s container %q image %q: %s",
+					p.Name, cs.Name, cs.Image, w.Message)
+			}
+		}
+	}
+	return ""
+}
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..55cb544
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,187 @@
+[build-system]
+# Requirements for package build
+# Should be mirrored in requirements/build.txt (for builds external to setuptools)
+# The recommended installation from source will avoid the requirements here in order
+# to stay flexible for the torch version with `--no-build-isolation`. Thus, these packages
+# should be installed before `pip install -e . --no-build-isolation`. 
+# However, build isolation is still used for the cibuildwheel releases
+# Thus, we will still lock a torch version here because we can choose to release wheels
+# in sync with vllm and update our torch version accordingly
+requires = [
+    "ninja",
+    "packaging>=24.2",
+    "setuptools>=77.0.3,<81.0.0",
+    "setuptools_scm>=8",
+    "torch==2.11.0",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lmcache"
+authors = [{name = "LMCache Team", email = "lmcacheteam@gmail.com"}]
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+readme = "README.md"
+description = "A LLM serving engine extension to reduce TTFT and increase throughput, especially under long-context scenarios."
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: POSIX :: Linux",
+    "Environment :: GPU",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.10,<3.14"
+dynamic = ["dependencies", "optional-dependencies", "version"]
+
+[project.scripts]
+lmcache="lmcache.cli.main:main"
+lmcache_server="lmcache.v1.server.__main__:main"
+lmcache_controller="lmcache.v1.api_server.__main__:main"
+
+[project.urls]
+homepage = "https://docs.lmcache.ai"
+source = "https://github.com/LMCache/LMCache"
+issues = "https://github.com/LMCache/LMCache"
+
+[tool.setuptools_scm]
+version_file = "lmcache/_version.py"
+# do not include +gREV local version, required for Test PyPI upload
+local_scheme = "no-local-version"
+# only treat vX.Y.Z-style tags as version anchors; ignores nightly/nightly-cu129 tags
+tag_regex = "^v?(?P<version>\\d+\\.\\d+\\.\\d+.*)$"
+git_describe_command = ["git", "describe", "--tags", "--long", "--match", "v[0-9]*.[0-9]*", "--exclude", "v*-*"]
+
+[tool.setuptools.packages.find]
+where = [""]
+include = ["lmcache", "lmcache*"]
+
+[tool.ruff]
+# same as Black's default line length
+line-length = 88
+exclude = [
+    "lmcache/integration/vllm/lmcache_mp_connector_*.py",
+]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    # "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    #"SIM",
+    # Ruff does not support isort's import_headings feature, yet.
+    # "I",
+    # flake8-logging-format
+    #"G",
+    # flake8-self (private member access)
+    "SLF",
+]
+ignore = [
+    # star imports
+    "F405", "F403",
+    # lambda expression assignment
+    "E731",
+    # Loop control variable not used within loop body
+    "B007",
+    # f-string format
+    "UP032",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore SLF everywhere except lmcache/v1/multiprocess/
+"!lmcache/v1/multiprocess/**" = ["SLF"]
+"!lmcache/v1/distributed/**" = ["SLF"]
+
+[tool.ruff.lint.isort]
+# same as .isort.cfg
+from-first = true
+# not supported yet
+# import-heading-future=Future
+# import-heading-stdlib=Standard
+# import-heading-thirdparty=Third Party
+# import-heading-firstparty=First Party
+# import-heading-localfolder=Local
+
+[tool.mypy]
+
+platform = "linux"
+modules = ["lmcache", "tests", "benchmarks"]
+exclude = [
+    'lmcache/integration/vllm/lmcache_mp_connector_.*\.py',
+]
+
+disable_error_code = [
+    #"annotation-unchecked",
+    #"union-attr",
+    #"var-annotated",
+    #"arg-type",
+    # "call-arg",
+    #"import-untyped",
+    #"attr-defined",
+    #"return-value",
+    #"assignment",
+    #"call-overload",
+    #"misc",
+]
+
+ignore_missing_imports = true
+explicit_package_bases = true
+
+# TODO: tighten MyPy checks by enabling these checks over time.
+check_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+warn_return_any = false
+
+follow_imports = "silent"
+
+[tool.codespell]
+ignore-words-list = "afterall,allready,notin,te"
+skip = "operator/config/crd/bases/*,lmcache/integration/vllm/lmcache_mp_connector_*.py"
+
+[tool.cibuildwheel]
+build = "cp3*-manylinux_x86_64"
+
+# see https://developer.nvidia.com/cuda-gpus for compute capabilities
+# "CUDA-Enabled Datacenter Products"
+# 7.5:  T4
+# 8.0:  A100, A30
+# 8.6:  A40, A10, A16, A2
+# 8.9:  L4, L40, L40S
+# 9.0:  GH200, H200, H100
+# 10.0: GB200, B200
+# 12.0: RTX 50-series (PTX)
+# CUDA 13 dropped support for compute capability 7.0 (Volta).
+environment = {TORCH_CUDA_ARCH_LIST = "7.5;8.0;8.6;8.9;9.0;10.0;12.0", ENABLE_CXX11_ABI = "1", PIP_EXTRA_INDEX_URL = "https://download.pytorch.org/whl/cu130"}
+
+# Use the PyTorch manylinux image version '2_28' that contains CUDA 13.0
+manylinux-x86_64-image = "docker.io/pytorch/manylinux2_28-builder:cuda13.0"
+
+[tool.cibuildwheel.linux]
+repair-wheel-command = """
+auditwheel repair \
+  --plat manylinux_2_28_x86_64 \
+  --exclude libtorch.so \
+  --exclude libtorch_cuda.so \
+  --exclude libtorch_python.so \
+  --exclude libtorch_cpu.so \
+  --exclude libc10.so \
+  --exclude libc10_cuda.so \
+  --exclude libcudart.so.13 \
+  -w {dest_dir} {wheel}
+"""
diff --git a/pyproject_cli.toml b/pyproject_cli.toml
new file mode 100644
index 0000000..54fa6e3
--- /dev/null
+++ b/pyproject_cli.toml
@@ -0,0 +1,138 @@
+[build-system]
+# Requirements for package build
+# Should be mirrored in requirements/build.txt (for builds external to setuptools)
+# The recommended installation from source will avoid the requirements here in order
+# to stay flexible for the torch version with `--no-build-isolation`. Thus, these packages
+# should be installed before `pip install -e . --no-build-isolation`.
+# However, build isolation is still used for the cibuildwheel releases
+# Thus, we will still lock a torch version here because we can choose to release wheels
+# in sync with vllm and update our torch version accordingly
+requires = [
+    "packaging>=24.2",
+    "setuptools>=68.0.0",
+    "setuptools_scm>=8",
+    "wheel",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lmcache-cli"
+authors = [{name = "LMCache Team", email = "lmcacheteam@gmail.com"}]
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+readme = "README.md"
+description = "A LLM serving engine extension to reduce TTFT and increase throughput, especially under long-context scenarios."
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+requires-python = ">=3.10,<3.14"
+dynamic = ["dependencies", "version"]
+
+[project.scripts]
+lmcache="lmcache.cli.main:main"
+
+[project.urls]
+homepage = "https://docs.lmcache.ai"
+source = "https://github.com/LMCache/LMCache"
+issues = "https://github.com/LMCache/LMCache"
+
+[tool.setuptools_scm]
+version_file = "lmcache/_version.py"
+# do not include +gREV local version, required for Test PyPI upload
+local_scheme = "no-local-version"
+
+[tool.setuptools.dynamic]
+dependencies = { file = ["requirements/cli.txt"] }
+
+[tool.setuptools.packages.find]
+where = [""]
+include = ["lmcache", "lmcache*"]
+
+[tool.ruff]
+# same as Black's default line length
+line-length = 88
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    # "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    #"SIM",
+    # Ruff does not support isort's import_headings feature, yet.
+    # "I",
+    # flake8-logging-format
+    #"G",
+    # flake8-self (private member access)
+    "SLF",
+]
+ignore = [
+    # star imports
+    "F405", "F403",
+    # lambda expression assignment
+    "E731",
+    # Loop control variable not used within loop body
+    "B007",
+    # f-string format
+    "UP032",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore SLF everywhere except lmcache/v1/multiprocess/
+"!lmcache/v1/multiprocess/**" = ["SLF"]
+"!lmcache/v1/distributed/**" = ["SLF"]
+
+[tool.ruff.lint.isort]
+# same as .isort.cfg
+from-first = true
+
+[tool.mypy]
+
+platform = "linux"
+modules = ["lmcache", "tests", "benchmarks"]
+
+disable_error_code = [
+    #"annotation-unchecked",
+    #"union-attr",
+    #"var-annotated",
+    #"arg-type",
+    # "call-arg",
+    #"import-untyped",
+    #"attr-defined",
+    #"return-value",
+    #"assignment",
+    #"call-overload",
+    #"misc",
+]
+
+ignore_missing_imports = true
+explicit_package_bases = true
+
+# TODO: tighten MyPy checks by enabling these checks over time.
+check_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+warn_return_any = false
+
+follow_imports = "silent"
+
+[tool.codespell]
+ignore-words-list = "afterall,allready,notin"
+skip = "operator/config/crd/bases/*"
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 0000000..54f7848
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,5 @@
+[pytest]
+log_cli = true
+log_cli_level = INFO
+markers =
+    no_shared_allocator: Disable the shared-allocator monkeypatch for this test
diff --git a/requirements/bench.txt b/requirements/bench.txt
new file mode 100644
index 0000000..4b9aac9
--- /dev/null
+++ b/requirements/bench.txt
@@ -0,0 +1,8 @@
+openai
+requests
+tqdm
+transformers
+numpy<=2.2.6
+pandas
+matplotlib
+seaborn
\ No newline at end of file
diff --git a/requirements/build.txt b/requirements/build.txt
new file mode 100644
index 0000000..4d14f13
--- /dev/null
+++ b/requirements/build.txt
@@ -0,0 +1,11 @@
+# This should mirror the build dependencies in pyproject.toml
+
+ninja
+packaging>=24.2
+setuptools>=77.0.3,<81.0.0
+setuptools_scm>=8
+# torch is not here because vllm installation will implicitly install it for the dockerfile
+# and users should be deliberate about choosing their torch version (or letting their serving
+# engine be deliberate for them)
+wheel
+
diff --git a/requirements/cli.txt b/requirements/cli.txt
new file mode 100644
index 0000000..79a97d0
--- /dev/null
+++ b/requirements/cli.txt
@@ -0,0 +1,5 @@
+matplotlib
+openai
+# Required by `lmcache describe`, which parses Prometheus metrics text.
+prometheus_client >= 0.18.0, <= 0.24.1
+sortedcontainers
diff --git a/requirements/common.txt b/requirements/common.txt
new file mode 100644
index 0000000..79ac301
--- /dev/null
+++ b/requirements/common.txt
@@ -0,0 +1,49 @@
+aiofile
+aiofiles
+blake3
+aiohttp
+awscrt
+cufile-python
+fastapi
+httpx
+huggingface_hub>=1.5.0
+msgspec
+# nixl uses numba which requires numpy<=2.2.6
+numpy<=2.2.6
+numba
+nvtx
+opentelemetry-api >= 1.20.0, <= 1.40.0
+opentelemetry-sdk >= 1.20.0
+opentelemetry-exporter-otlp >= 1.20.0
+opentelemetry-exporter-prometheus >= 0.50b0, <= 0.61b0
+prometheus_client >= 0.18.0, <= 0.24.1
+psutil
+py-cpuinfo
+# cupy.testing._random unconditionally imports pytest at module level;
+# torch._dynamo triggers this via inspect.getmodule() during compilation.
+pytest
+pyyaml
+pyzmq >= 25.0.0
+redis
+safetensors
+setuptools>=77.0.3,<81.0.0
+setuptools_scm>=8
+sortedcontainers
+# 1. avoid pinning torch version in the runtime dependencies so that 
+# installing lmcache (from source or from pypi) will not override
+# the user's preexisting torch version 
+# 2. this keeps lmcache torch version flexible for many serving engines
+# and versions of those serving engines
+# if NO pre-existing torch version is installed, `pip install lmcache` or 
+# `pip install -e . --no-build-isolation` will install the latest torch version
+# 3. the extra benefit of not pinning is so that when vllm releases their docker
+# image (which has lmcache as a dependency), we will never forcefully collide with
+# whatever torch version that they have
+# 4. this torch version may also be overridden inside of LMCache/docker/Dockerfile
+torch
+transformers >= 5.4
+uvicorn
+httptools
+cachetools
+google-api-core
+google-cloud-bigtable
diff --git a/requirements/cuda.txt b/requirements/cuda.txt
new file mode 100644
index 0000000..d7ce56d
--- /dev/null
+++ b/requirements/cuda.txt
@@ -0,0 +1,21 @@
+# Common project dependencies
+-r common.txt
+# Vendor-specific runtime deps (cupy) baked into install_requires.
+# Defaults to the cu13 list; the cu12.9 build path overrides via setup.py
+# (LMCACHE_CUDA_MAJOR=12) and does not consume cuda.txt directly.
+-r cuda13_core.txt
+# NIXL ships as the optional `lmcache[nixl]` extra in wheels, but dev/CI
+# environments built from this file keep it installed by default.
+-r nixl.txt
+
+# Dependencies for NVIDIA GPUs
+ray >= 2.9
+nvidia-ml-py # for pynvml package
+
+
+# do not pin version because the dockerfile requires cuda.txt
+torch
+# Required for phi3v processor. See https://github.com/pytorch/vision?tab=readme-ov-file#installation for corresponding version
+torchvision
+# platform_system == 'Linux' and platform_machine == 'x86_64' 
+xformers
diff --git a/requirements/cuda12_core.txt b/requirements/cuda12_core.txt
new file mode 100644
index 0000000..ff842d1
--- /dev/null
+++ b/requirements/cuda12_core.txt
@@ -0,0 +1,4 @@
+# Vendor-specific runtime deps for CUDA 12.9 wheels. Selected by setup.py when
+# LMCACHE_CUDA_MAJOR=12. The cu13 default lives in cuda13_core.txt.
+
+cupy-cuda12x
diff --git a/requirements/cuda13_core.txt b/requirements/cuda13_core.txt
new file mode 100644
index 0000000..2f0faf5
--- /dev/null
+++ b/requirements/cuda13_core.txt
@@ -0,0 +1,5 @@
+# Vendor-specific runtime deps for CUDA 13 wheels. Selected by setup.py when
+# LMCACHE_CUDA_MAJOR is unset or "13" (the default, matching the PyPI build).
+# The cu12 analogue lives in cuda12_core.txt.
+
+cupy-cuda13x
diff --git a/requirements/docs.txt b/requirements/docs.txt
new file mode 100644
index 0000000..4666cf5
--- /dev/null
+++ b/requirements/docs.txt
@@ -0,0 +1,17 @@
+sphinx>=6,<9
+sphinx-rtd-theme==3.1.0
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0
+sphinxawesome_theme==5.3.2
+sphinx-copybutton==0.5.2
+sphinxcontrib-mermaid==2.0.2
+sphinx-multiversion==0.2.4
+sphinx-intl==2.3.1
+sphinxcontrib-images
+msgspec
+sphinx-design
diff --git a/requirements/lint.txt b/requirements/lint.txt
new file mode 100644
index 0000000..828e141
--- /dev/null
+++ b/requirements/lint.txt
@@ -0,0 +1,2 @@
+# linting and formatting
+pre-commit==4.5.0
diff --git a/requirements/nixl.txt b/requirements/nixl.txt
new file mode 100644
index 0000000..f5a6da8
--- /dev/null
+++ b/requirements/nixl.txt
@@ -0,0 +1,9 @@
+# Optional NIXL transport deps, exposed as the `pip install lmcache[nixl]`
+# extra.
+
+# Depend on the `nixl` meta-package: it is the only package that provides the
+# importable top-level `nixl` module, and since 1.3.0 it dispatches at runtime
+# to the backend (nixl_cu12 / nixl_cu13) matching torch's CUDA build. The
+# nixl-cu12 / nixl-cu13 backend wheels alone do NOT provide the `nixl` module.
+# Cost: the meta-package installs both CUDA backends (~105MB each).
+nixl>=1.3.0; python_version < "3.13"
diff --git a/requirements/rocm_core.txt b/requirements/rocm_core.txt
new file mode 100644
index 0000000..21e9e66
--- /dev/null
+++ b/requirements/rocm_core.txt
@@ -0,0 +1,9 @@
+# Vendor-specific runtime deps baked into install_requires by setup.py
+# when building for ROCm (BUILD_WITH_HIP=1).
+# cupy-rocm-7-0 is the AMD analogue of cupy-cuda12x.
+# torch/torchvision are NOT listed here because ROCm wheels live on a
+# non-PyPI index (https://download.pytorch.org/whl/rocm7.0) that pip
+# cannot be told about via install_requires; users install them manually
+# per the "LMCache on ROCm / Without vLLM docker base image" docs.
+
+cupy-rocm-7-0
diff --git a/requirements/test.txt b/requirements/test.txt
new file mode 100644
index 0000000..d86c4e0
--- /dev/null
+++ b/requirements/test.txt
@@ -0,0 +1,10 @@
+buildkite-test-collector
+pytest>=7.0,<9.1  # avoid some plugins breaking in 8.x
+pytest-asyncio
+pytest-benchmark
+pytest-benchmark[histogram]
+pytest-cov
+pytest-html>=3.2,<5.0  # 4.x requires external assets; 3.2 is stable
+jinja2<3.2
+python-multipart
+openai
diff --git a/rust/raw_block/.gitignore b/rust/raw_block/.gitignore
new file mode 100644
index 0000000..2c96eb1
--- /dev/null
+++ b/rust/raw_block/.gitignore
@@ -0,0 +1,2 @@
+target/
+Cargo.lock
diff --git a/rust/raw_block/Cargo.toml b/rust/raw_block/Cargo.toml
new file mode 100644
index 0000000..925e8ee
--- /dev/null
+++ b/rust/raw_block/Cargo.toml
@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "lmcache_rust_raw_block_io"
+version = "0.0.1"
+edition = "2021"
+
+[lib]
+name = "lmcache_rust_raw_block_io"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.24", features = ["extension-module"] }
+libc = "0.2"
+io-uring = "0.7"
diff --git a/rust/raw_block/README.md b/rust/raw_block/README.md
new file mode 100644
index 0000000..7c788e8
--- /dev/null
+++ b/rust/raw_block/README.md
@@ -0,0 +1,181 @@
+# LMCache Rust Raw Block I/O
+
+This crate provides the low-level raw device I/O layer for LMCache via Rust +
+PyO3. It is used by both:
+
+- the legacy non-MP `RustRawBlockBackend`
+- the MP `raw_block` L2 adapter (`RawBlockL2Adapter`) via `RawBlockCore`
+
+The Rust crate intentionally stays narrow: it owns the raw device handle and
+exposes blocking `pwrite_from_buffer` / `pread_into` primitives. Slotting,
+checkpointing, recovery, and MP task orchestration all live in Python.
+
+## I/O Engines
+
+`RawBlockDevice` accepts `io_engine`:
+
+- `posix` (default): synchronous Linux `pread` / `pwrite`.
+- `io_uring`: direct Rust io_uring syscall path using the existing worker,
+  batch, and `wait_iouring` machinery.
+
+`use_iouring=True` remains accepted for backward compatibility. If `io_engine`
+is explicitly set, it wins over the legacy flag.
+
+## io_uring_cmd (NVMe Passthrough)
+
+When `io_engine="io_uring"`, you can optionally enable `use_uring_cmd=True` to
+use NVMe passthrough via the io_uring command interface for direct device access.
+
+**io_uring_cmd notes:**
+
+- Requires NVMe character device node (`/dev/ngXnY`) instead of the block device
+  node (`/dev/nvmeXnY`) for direct NVMe passthrough command.
+- Requires `io_engine="io_uring"` to be set.
+- Supports `max_data_transfer_size` parameter to split large transfers into
+  smaller chunks that fit within device limits.
+- When `use_uring_cmd=True`, `use_odirect` is ignored for NVMe namespace
+  character devices.
+
+## MP Mode Integration
+
+In MP mode, the stack looks like this:
+
+```text
+StoreController / PrefetchController
+                |
+                v
+        RawBlockL2Adapter
+                |
+                v
+           RawBlockCore
+                |
+                v
+         lmcache_rust_raw_block_io
+                |
+                v
+         raw device / file
+```
+
+This split lets LMCache reuse the same on-device metadata and recovery model in
+both non-MP and MP mode without duplicating the raw-block implementation.
+
+## Zero-Copy Data Path
+
+```text
+LMCache LocalCPUBackend (aligned pinned CPU tensor)
+                 |
+                 |  Python buffer / memoryview (no payload memcpy)
+                 v
+RustRawBlockBackend (PyO3 boundary)
+                 |
+                 |  direct pointer path when O_DIRECT constraints are met
+                 |  fallback: bounce only for unaligned tail/block
+                 v
+RawBlockDevice::pwrite_from_buffer / pread_into
+                 |
+                 v
+Block device or file
+```
+
+## How To Compare Performance
+
+To compare `local_disk` vs `rust_raw_block` on a real NVMe device:
+- Run `local_disk` on an ext4 mount of the device.
+- Unmount it.
+- Run `rust_raw_block` directly on the raw block device.
+
+Use the benchmark commands in:
+- `benchmarks/storage_backend_io/README.md`
+
+No fixed numbers are included here because results are host/device/workload dependent.
+
+## Limitations
+
+- Linux only (`pread` / `pwrite`, O_DIRECT semantics).
+- O_DIRECT requires aligned offset, size, and user buffer address.
+
+## Build
+
+```bash
+cd rust/raw_block
+pip install maturin
+maturin develop --release
+```
+
+## Minimal Usage
+
+```python
+from lmcache_rust_raw_block_io import RawBlockDevice
+
+dev = RawBlockDevice("/dev/nvme0n1", True, use_odirect=True, alignment=4096)
+dev.pwrite_from_buffer(offset=0, data=b"hello", total_len=4096)
+
+buf = bytearray(4096)
+dev.pread_into(offset=0, out=buf, payload_len=5, total_len=4096)
+```
+
+io_uring:
+
+```python
+dev = RawBlockDevice(
+    "/dev/nvme0n1",
+    True,
+    use_odirect=True,
+    alignment=4096,
+    io_engine="io_uring",
+    iouring_queue_depth=256,
+)
+```
+
+io_uring with io_uring_cmd (NVMe passthrough):
+
+```python
+dev = RawBlockDevice(
+    "/dev/ng0n1",  # Note: NVMe character device node
+    True,
+    use_odirect=False,
+    alignment=4096,
+    io_engine="io_uring",
+    use_uring_cmd=True,
+    iouring_queue_depth=256,
+    max_data_transfer_size=131072,  # Optional: split large transfers
+)
+```
+
+## MP Adapter Example
+
+To use the MP adapter from `lmcache server`, pass a `raw_block` L2 adapter
+config:
+
+```bash
+lmcache server \
+  --l1-size-gb 10 \
+  --eviction-policy LRU \
+  --l1-align-bytes 4096 \
+  --l2-adapter '{
+    "type": "raw_block",
+    "device_path": "/dev/nvme0n1",
+    "slot_bytes": 1048576,
+    "block_align": 4096,
+    "header_bytes": 4096,
+    "meta_total_bytes": 268435456,
+    "use_odirect": true,
+    "io_engine": "io_uring",
+    "num_store_workers": 2,
+    "num_lookup_workers": 1,
+    "num_load_workers": 4
+  }'
+```
+
+Notes:
+
+- `device_path` should point to an unmounted raw block device or a dedicated
+  file used only by LMCache.
+- For `use_uring_cmd=true`, `device_path` must use the NVMe character
+  device node (e.g., `/dev/ng0n1`) instead of the block device node.
+- With `use_odirect=true`, LMCache MP L1 alignment must be at least
+  `block_align`.
+- Restart recovery uses the metadata checkpoint region on the same device.
+- Raw-block slot reclamation is driven by the shared/global L2 eviction
+  controller or explicit `delete()` calls.
+- `raw_block` remains the adapter type for all supported engines.
diff --git a/rust/raw_block/pyproject.toml b/rust/raw_block/pyproject.toml
new file mode 100644
index 0000000..9e1f682
--- /dev/null
+++ b/rust/raw_block/pyproject.toml
@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+
+[build-system]
+requires = ["maturin>=1.8"]
+build-backend = "maturin"
+
+[project]
+name = "lmcache_rust_raw_block_io"
+version = "0.0.1"
+description = "Rust (PyO3) raw block I/O helpers for LMCache storage plugins."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.maturin]
+bindings = "pyo3"
+module-name = "lmcache_rust_raw_block_io"
+
diff --git a/rust/raw_block/src/lib.rs b/rust/raw_block/src/lib.rs
new file mode 100644
index 0000000..8da6047
--- /dev/null
+++ b/rust/raw_block/src/lib.rs
@@ -0,0 +1,3104 @@
+// SPDX-License-Identifier: Apache-2.0
+#![allow(unknown_lints)]
+
+//! Raw block device I/O extension for LMCache.
+//! Provides direct block device access with optional O_DIRECT support.
+//!
+//! Design notes (for reviewers unfamiliar with Rust / Linux I/O):
+//! - This module exposes a very small surface to Python via PyO3.
+//! - We wrap Linux `pread` / `pwrite` on a file descriptor opened from a
+//!   block device (e.g., /dev/nvmeXnY) or a regular file (for tests).
+//! - When O_DIRECT is enabled, Linux requires aligned offsets and I/O sizes.
+//!   If Python buffers are aligned, we use them directly; otherwise we fallback
+//!   to a bounce buffer (aligned via `posix_memalign`) for safety.
+//! - For io_uring case a dedicated worker thread drives the io_uring
+//!   submission/completion loop. All alignment checks are performed before
+//!   enqueuing; violations result in an immediate Python `ValueError`.
+
+use pyo3::exceptions::{PyOSError, PyRuntimeError, PyValueError};
+use pyo3::prelude::*;
+use pyo3::types::PyAny;
+use std::collections::HashMap;
+use std::ffi::CString;
+use std::io;
+use std::os::unix::io::RawFd;
+use std::slice;
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, Condvar, Mutex};
+use std::thread;
+use std::time::Duration;
+
+use io_uring::cqueue::{Entry, Entry32};
+use io_uring::squeue::{Entry as SqueueEntry, Entry128};
+use io_uring::types::Fd;
+use io_uring::{opcode, IoUring};
+
+// Wrapper enum to support both standard and big io_uring entries
+// This allows fallback to standard entries on kernels < 5.19
+#[derive(Clone)]
+enum IoUringWrapper {
+    Standard(Arc<Mutex<IoUring<SqueueEntry, Entry>>>),
+    Big(Arc<Mutex<IoUring<Entry128, Entry32>>>),
+}
+
+impl IoUringWrapper {
+    // Get the submission queue length
+    fn submission_len(&self) -> usize {
+        match self {
+            IoUringWrapper::Standard(ring) => {
+                let mut ring = ring.lock().unwrap();
+                let len = ring.submission().len();
+                len
+            }
+            IoUringWrapper::Big(ring) => {
+                let mut ring = ring.lock().unwrap();
+                let len = ring.submission().len();
+                len
+            }
+        }
+    }
+
+    // Sync the submission queue
+    fn submission_sync(&self) {
+        match self {
+            IoUringWrapper::Standard(ring) => {
+                let mut ring = ring.lock().unwrap();
+                ring.submission().sync();
+            }
+            IoUringWrapper::Big(ring) => {
+                let mut ring = ring.lock().unwrap();
+                ring.submission().sync();
+            }
+        }
+    }
+}
+
+// NVMe identify namespace data structure
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+struct NvmeIdNs {
+    nsze: u64,
+    ncap: u64,
+    nuse: u64,
+    nsfeat: u8,
+    nlbaf: u8,
+    flbas: u8,
+    mc: u8,
+    dpc: u8,
+    dps: u8,
+    nmic: u8,
+    rescap: u8,
+    fpi: u8,
+    dlfeat: u8,
+    nawun: u16,
+    nawupf: u16,
+    nacwu: u16,
+    nabsn: u16,
+    nabo: u16,
+    nabspf: u16,
+    noiob: u16,
+    nvmcap: [u8; 16],
+    npwg: u16,
+    npwa: u16,
+    npdg: u16,
+    npda: u16,
+    nows: u16,
+    mssrl: u16,
+    mcl: u32,
+    msrc: u8,
+    rsvd81: [u8; 11],
+    anagrpid: u32,
+    rsvd96: [u8; 3],
+    nsattr: u8,
+    nvmsetid: u16,
+    endgid: u16,
+    nguid: [u8; 16],
+    eui64: [u8; 8],
+    lbaf: [NvmeLbaf; 64],
+    vs: [u8; 3712],
+}
+
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+struct NvmeLbaf {
+    ms: u16,
+    ds: u8,
+    rp: u8,
+}
+
+// NVMe admin opcodes
+const NVME_ADMIN_IDENTIFY: u8 = 0x06;
+
+// NVMe identify CNS values
+const NVME_IDENTIFY_CNS_NS: u32 = 0x00;
+
+// NVMe I/O opcodes
+const NVME_IO_READ: u8 = 0x02;
+const NVME_IO_WRITE: u8 = 0x01;
+
+// NVMe uring command structure (80 bytes)
+#[repr(C)]
+#[derive(Debug, Clone, Copy)]
+struct NvmeUringCmd {
+    opcode: u8,
+    flags: u8,
+    rsvd1: u16,
+    nsid: u32,
+    cdw2: u32,
+    cdw3: u32,
+    metadata: u64,
+    addr: u64,
+    metadata_len: u32,
+    data_len: u32,
+    cdw10: u32,
+    cdw11: u32,
+    cdw12: u32,
+    cdw13: u32,
+    cdw14: u32,
+    cdw15: u32,
+    rsvd2: [u32; 4],
+}
+
+// Linux ioctl for NVMe admin command
+// Defined in <linux/nvme_ioctl.h>: NVME_IOCTL_ADMIN_CMD _IOWR ('N', 0x41)
+const NVME_IOCTL_ADMIN_CMD: libc::c_ulong = 0xC048_4E41;
+
+// Defined in <linux/nvme_ioctl.h>: NVME_IOCTL_IO_CMD _IOWR ('N', 0x43)
+// const NVME_IOCTL_IO_CMD: libc::c_ulong = 0xC048_4E43;
+
+// NVMe io_uring_cmd opcodes
+const NVME_URING_CMD_IO: u32 = 0xC048_4E80;
+
+// Linux ioctl for NVMe namespace ID
+// Defined in <linux/nvme_ioctl.h>: NVME_IOCTL_ID _IO ('N', 0x40)
+const NVME_IOCTL_ID: libc::c_ulong = 0x4e40;
+
+// Linux ioctl for block device size in bytes.
+// Defined in <linux/fs.h>: BLKGETSIZE64 _IOR(0x12,114,size_t)
+const BLKGETSIZE64: libc::c_ulong = 0x8008_1272; // ioctl op to query block size
+
+// Buffer protocol flags (from CPython C-API).
+const PYBUF_WRITABLE: i32 = 0x0001; // buffer must be writable
+const PYBUF_ND: i32 = 0x0008; // request N-dimensional buffer
+const PYBUF_STRIDES: i32 = 0x0010 | PYBUF_ND; // request strides info
+const PYBUF_ANY_CONTIGUOUS: i32 = 0x0080 | PYBUF_STRIDES; // accept any contiguous layout
+
+// O_DIRECT is Linux-only; define a no-op fallback for other platforms.
+#[cfg(target_os = "linux")]
+const O_DIRECT: i32 = libc::O_DIRECT;
+#[cfg(not(target_os = "linux"))]
+const O_DIRECT: i32 = 0;
+const RING_SIZE: usize = 256;
+
+fn parse_use_iouring(io_engine: Option<String>, use_iouring: bool) -> PyResult<bool> {
+    match io_engine {
+        Some(engine) if !engine.is_empty() => match engine.as_str() {
+            "posix" => Ok(false),
+            "io_uring" => Ok(true),
+            other => Err(PyValueError::new_err(format!(
+                "io_engine must be one of posix, io_uring; got {other}"
+            ))),
+        },
+        _ => Ok(use_iouring),
+    }
+}
+
+///Per batch tracking for in flight I/O operation
+type BatchTracking = (Arc<AtomicU64>, Arc<Condvar>);
+
+/// Round up to nearest multiple of alignment (required for O_DIRECT).
+#[allow(clippy::manual_div_ceil)]
+// Small helper used to align sizes for O_DIRECT I/O.
+fn round_up(x: usize, align: usize) -> usize {
+    (x + align - 1) / align * align
+}
+
+// Fetch errno for the last libc call on this thread.
+fn errno() -> i32 {
+    // SAFETY: libc call.
+    #[cfg(target_os = "linux")]
+    unsafe {
+        *libc::__errno_location()
+    }
+    #[cfg(target_os = "macos")]
+    unsafe {
+        *libc::__error()
+    }
+}
+
+// Convert errno to a Python OSError with a message.
+fn os_err(msg: &str) -> PyErr {
+    PyOSError::new_err((errno(), msg.to_string()))
+}
+
+// Low-level write loop that retries until all bytes are written.
+// This isolates the raw syscalls from Python-facing logic.
+fn pwrite_from_ptr(
+    fd: RawFd,
+    mut offset: u64,
+    mut ptr: *const u8,
+    mut len: usize,
+) -> Result<(), PyErr> {
+    while len > 0 {
+        // SAFETY: caller guarantees ptr is valid for len bytes.
+        let chunk = unsafe { slice::from_raw_parts(ptr, len) };
+        let n = unsafe {
+            libc::pwrite(
+                fd,
+                chunk.as_ptr() as *const libc::c_void,
+                chunk.len(),
+                offset as libc::off_t,
+            )
+        };
+        if n < 0 {
+            return Err(os_err("pwrite failed"));
+        }
+        let n = n as usize;
+        offset += n as u64;
+        // SAFETY: advance ptr by n bytes.
+        unsafe {
+            ptr = ptr.add(n);
+        }
+        len -= n;
+    }
+    Ok(())
+}
+
+// Low-level read loop that retries until all bytes are read.
+// We treat EOF as an error because the caller expects a full read.
+fn pread_into(fd: RawFd, offset: u64, mut dst: *mut u8, mut size: usize) -> Result<(), PyErr> {
+    let mut off = offset;
+    while size > 0 {
+        // SAFETY: pread writes into dst for size bytes.
+        let n = unsafe { libc::pread(fd, dst as *mut libc::c_void, size, off as libc::off_t) };
+        if n < 0 {
+            return Err(os_err("pread failed"));
+        }
+        if n == 0 {
+            return Err(PyRuntimeError::new_err("unexpected EOF"));
+        }
+        let n = n as usize;
+        // SAFETY: advance dst by n bytes.
+        unsafe {
+            dst = dst.add(n);
+        }
+        off += n as u64;
+        size -= n;
+    }
+    Ok(())
+}
+
+// Determine file/device size in bytes (ioctl for block device, fstat fallback).
+fn fd_size_bytes(fd: RawFd) -> Result<u64, PyErr> {
+    // Try ioctl first (block device / loop device).
+    let mut size: u64 = 0;
+    // SAFETY: ioctl expects pointer to u64 for BLKGETSIZE64.
+    let rc = unsafe { libc::ioctl(fd, BLKGETSIZE64, &mut size as *mut u64) };
+    if rc == 0 {
+        return Ok(size);
+    }
+
+    // Fallback to fstat for regular files.
+    let mut st: libc::stat = unsafe { std::mem::zeroed() };
+    let rc2 = unsafe { libc::fstat(fd, &mut st as *mut libc::stat) };
+    if rc2 != 0 {
+        return Err(os_err("fstat failed"));
+    }
+    Ok(st.st_size as u64)
+}
+
+// NVMe helper functions for io_uring command support
+
+// Calculate NVMe namespace size in bytes from identify namespace data
+fn nvme_ns_size_bytes(id_ns: &NvmeIdNs, lba_size: u32) -> u64 {
+    id_ns.nsze * lba_size as u64
+}
+
+/// Check if device path is a character device (e.g., /dev/ng0n1)
+fn is_character_device(path: &str) -> Result<bool, PyErr> {
+    let cpath = CString::new(path).map_err(|_| PyValueError::new_err("path contains NUL"))?;
+
+    // SAFETY: stat call
+    let mut st: libc::stat = unsafe { std::mem::zeroed() };
+    let rc = unsafe { libc::stat(cpath.as_ptr(), &mut st as *mut libc::stat) };
+
+    if rc != 0 {
+        return Err(os_err("stat failed"));
+    }
+
+    Ok((st.st_mode & libc::S_IFMT) == libc::S_IFCHR)
+}
+
+/// Get namespace ID from NVMe device using ioctl.
+fn nvme_get_nsid_from_fd(fd: RawFd) -> Result<u32, PyErr> {
+    //SAFETY: ioctl call with request that returns an integer
+    let ret = unsafe { libc::ioctl(fd, NVME_IOCTL_ID) };
+    if ret < 0 {
+        return Err(os_err("Failed to get namespace ID via ioctl"));
+    }
+    Ok(ret as u32)
+}
+
+/// Get LBA shift (log2 of LBA size) from identify namespace data
+fn nvme_get_lba_shift(id_ns: &NvmeIdNs) -> Result<u32, PyErr> {
+    // Extract LBA format index from FLBAS
+
+    let lbaf_index = if id_ns.nlbaf < 16 {
+        (id_ns.flbas & 0x0F) as usize
+    } else {
+        let lsb = (id_ns.flbas & 0x0F) as usize;
+        let msb = ((id_ns.flbas >> 5) & 0x03) as usize;
+        lsb + (msb << 4)
+    };
+
+    if lbaf_index >= 64 {
+        return Err(PyValueError::new_err("Invalid LBA format index"));
+    }
+
+    // Get LBA data size from LBAF
+    let ds = id_ns.lbaf[lbaf_index].ds;
+    if ds == 0 {
+        return Err(PyValueError::new_err("Invalid LBA data size"));
+    }
+
+    // Check for metadata support
+    let ms = id_ns.lbaf[lbaf_index].ms;
+    if ms != 0 {
+        return Err(PyValueError::new_err(
+            "Device is formatted with metadata, can't be supported.",
+        ));
+    }
+
+    Ok(ds as u32)
+}
+
+/// Get LBA size in bytes from identify namespace data
+fn nvme_get_lba_size(id_ns: &NvmeIdNs) -> Result<u32, PyErr> {
+    let lba_shift = nvme_get_lba_shift(id_ns)?;
+    Ok(1u32 << lba_shift)
+}
+
+/// NVMe passthrough command structure for ioctl
+#[repr(C)]
+struct NvmePassthruCmd {
+    opcode: u8,
+    flags: u8,
+    rsvd1: u16,
+    nsid: u32,
+    cdw2: u32,
+    cdw3: u32,
+    metadata: u64,
+    addr: u64,
+    metadata_len: u32,
+    data_len: u32,
+    cdw10: u32,
+    cdw11: u32,
+    cdw12: u32,
+    cdw13: u32,
+    cdw14: u32,
+    cdw15: u32,
+    timeout_ms: u32,
+    result: u32,
+}
+
+/// Send NVMe identify namespace command via ioctl
+fn nvme_identify_ns(fd: RawFd, nsid: u32) -> Result<NvmeIdNs, PyErr> {
+    let mut id_ns: NvmeIdNs = unsafe { std::mem::zeroed() };
+
+    let cmd = NvmePassthruCmd {
+        opcode: NVME_ADMIN_IDENTIFY,
+        nsid,
+        addr: &mut id_ns as *mut NvmeIdNs as u64,
+        data_len: std::mem::size_of::<NvmeIdNs>() as u32,
+        cdw10: NVME_IDENTIFY_CNS_NS,
+        timeout_ms: 0,
+        ..unsafe { std::mem::zeroed() }
+    };
+
+    // SAFETY: ioctl with properly initialized command structure
+    let rc = unsafe { libc::ioctl(fd, NVME_IOCTL_ADMIN_CMD, &cmd as *const NvmePassthruCmd) };
+
+    if rc < 0 {
+        return Err(os_err("NVMe identify namespace ioctl failed"));
+    }
+
+    Ok(id_ns)
+}
+
+/// Prepare NVMe uring command for read/write operations
+#[allow(clippy::too_many_arguments)]
+fn nvme_uring_cmd_prep(
+    cmd: &mut NvmeUringCmd,
+    is_write: bool,
+    nsid: u32,
+    offset: u64,
+    len: usize,
+    lba_shift: u32,
+    ptr: *const u8,
+    dtype: u8,
+    dspec: u16,
+) -> Result<(), PyErr> {
+    let lba_size = 1usize << lba_shift;
+
+    // Validate offset alignment
+    if !(offset as usize).is_multiple_of(lba_size) {
+        return Err(PyValueError::new_err(format!(
+            "offset must be aligned to LBA size ({} bytes), got offset={}",
+            lba_size, offset
+        )));
+    }
+
+    // Validate length alignment
+    if !len.is_multiple_of(lba_size) {
+        return Err(PyValueError::new_err(format!(
+            "length must be aligned to LBA size ({} bytes), got len={}",
+            lba_size, len
+        )));
+    }
+
+    // Validate non-zero length
+    if len == 0 {
+        return Err(PyValueError::new_err("length must be non-zero"));
+    }
+
+    // Calculate SLBA (Starting LBA) and NLB (Number of LBAs)
+    let slba = offset >> lba_shift;
+    let nlb = (len >> lba_shift) - 1; // NLB is 0-based
+
+    // Validate NLB fits in NVMe field (16 bits, max 0xFFFF)
+    if nlb > 0xFFFF {
+        return Err(PyValueError::new_err(format!(
+            "NLB ({}) exceeds NVMe field maximum (65535)",
+            nlb
+        )));
+    }
+
+    // Set opcode
+    cmd.opcode = if is_write {
+        NVME_IO_WRITE
+    } else {
+        NVME_IO_READ
+    };
+    cmd.nsid = nsid;
+
+    // Set SLBA in cdw10 and cdw11
+    cmd.cdw10 = (slba & 0xFFFFFFFF) as u32;
+    cmd.cdw11 = (slba >> 32) as u32;
+
+    // Set NLB in cdw12 (bits 0-15) and dtype in bits 20-23
+    cmd.cdw12 = nlb as u32 | ((dtype as u32) << 20);
+
+    // Set dspec in cdw13 bits 16-31
+    cmd.cdw13 = (dspec as u32) << 16;
+
+    // Set data address and length
+    cmd.addr = ptr as u64;
+    cmd.data_len = len as u32;
+
+    // No metadata support for now
+    cmd.metadata = 0;
+    cmd.metadata_len = 0;
+
+    Ok(())
+}
+
+/// NVMe command data for io_uring_cmd submissions.
+///
+/// This structure contains NVMe-specific information needed for
+/// passthrough commands via io_uring_cmd.
+#[derive(Clone, Debug)]
+struct NvmeCmdData {
+    nsid: u32,      // Namespace ID
+    lba_shift: u32, // LBA shift (log2 of LBA size)
+    dtype: u8,      // Directive Type
+    dspec: u16,     // Directive Specific
+}
+
+/// Aligned buffer for O_DIRECT I/O.
+/// Allocated with posix_memalign so the pointer satisfies alignment requirements.
+/// Automatically freed on drop.
+struct AlignedBuf {
+    ptr: *mut u8,
+    #[allow(dead_code)]
+    len: usize,
+    #[allow(dead_code)]
+    align: usize,
+}
+
+unsafe impl Send for AlignedBuf {}
+unsafe impl Sync for AlignedBuf {}
+
+impl AlignedBuf {
+    // Allocate an aligned buffer suitable for O_DIRECT.
+    fn new(len: usize, align: usize) -> Result<Self, PyErr> {
+        let mut p: *mut libc::c_void = std::ptr::null_mut();
+        // SAFETY: posix_memalign writes to p.
+        let rc = unsafe { libc::posix_memalign(&mut p as *mut *mut libc::c_void, align, len) };
+        if rc != 0 {
+            return Err(PyRuntimeError::new_err(format!(
+                "posix_memalign failed rc={rc}"
+            )));
+        }
+        if p.is_null() {
+            return Err(PyRuntimeError::new_err("posix_memalign returned null"));
+        }
+        Ok(Self {
+            ptr: p as *mut u8,
+            len,
+            align,
+        })
+    }
+
+    // Mutable pointer for read/write syscalls.
+    fn as_mut_ptr(&self) -> *mut u8 {
+        self.ptr
+    }
+
+    // Const pointer for write syscalls.
+    fn as_ptr(&self) -> *const u8 {
+        self.ptr as *const u8
+    }
+}
+
+impl Drop for AlignedBuf {
+    fn drop(&mut self) {
+        if !self.ptr.is_null() {
+            unsafe {
+                libc::free(self.ptr as *mut libc::c_void);
+            }
+            self.ptr = std::ptr::null_mut();
+        }
+    }
+}
+
+// Acquire a Python buffer view with the requested mutability.
+fn get_pybuffer<'py>(
+    py: Python<'py>,
+    obj: &Bound<'py, PyAny>,
+    writable: bool,
+) -> Result<pyo3::ffi::Py_buffer, PyErr> {
+    // SAFETY: PyObject_GetBuffer follows CPython buffer protocol.
+    unsafe {
+        let mut view: pyo3::ffi::Py_buffer = std::mem::zeroed();
+        // Request a contiguous byte-view. This lets Rust issue a single syscall
+        // against a flat pointer instead of handling Python strides/shapes.
+        let flags = if writable {
+            PYBUF_WRITABLE | PYBUF_ANY_CONTIGUOUS
+        } else {
+            PYBUF_ANY_CONTIGUOUS
+        };
+        let rc = pyo3::ffi::PyObject_GetBuffer(obj.as_ptr(), &mut view, flags);
+        if rc != 0 {
+            return Err(PyErr::fetch(py));
+        }
+        Ok(view)
+    }
+}
+
+// Release a buffer view previously acquired by get_pybuffer.
+fn release_pybuffer(mut view: pyo3::ffi::Py_buffer) {
+    // SAFETY: view was created by PyObject_GetBuffer.
+    unsafe {
+        pyo3::ffi::PyBuffer_Release(&mut view);
+    }
+}
+
+/// Completion primitive for synchronous io_uring operations.
+///
+/// When a Python call needs to wait for an I/O operation to complete,
+/// we use this primitive. The worker thread will call `set()` with the
+/// result, and the caller calls `wait()` to block until the result is ready.
+///
+/// Fields:
+/// - `result`: Stores the completion status (Ok or Err)
+/// - `cvar`: Condition variable for signaling when result is available
+struct IoCompletion {
+    result: Mutex<Option<PyResult<()>>>,
+    cvar: Condvar,
+}
+
+impl IoCompletion {
+    fn new() -> Self {
+        Self {
+            result: Mutex::new(None),
+            cvar: Condvar::new(),
+        }
+    }
+    fn set(&self, r: PyResult<()>) {
+        let mut guard = self
+            .result
+            .lock()
+            .expect("IoCompletion: mutex poisoned in set()");
+        *guard = Some(r);
+        self.cvar.notify_one();
+    }
+    fn wait(&self) -> PyResult<()> {
+        let mut guard = self
+            .result
+            .lock()
+            .expect("IoCompletion: mutex poisoned in wait()");
+        while guard.is_none() {
+            guard = self
+                .cvar
+                .wait(guard)
+                .expect("IoCompletion: condition variable wait failed");
+        }
+        guard.take().unwrap()
+    }
+}
+
+/// Manages io_uring worker thread notification, using one `epoll` instance
+/// over two eventfds to wait on two event sources at once: a producer-side
+/// eventfd signalled when Python pushes a new submission, and a CQ-side
+/// eventfd signalled by the kernel when a completion is posted.
+struct UringNotify {
+    /// Epoll instance watching both `producer_efd` and `cq_efd`. A single
+    /// `epoll_wait` on this fd blocks until either eventfd becomes readable,
+    /// so the worker can react to user-space queue pushes and kernel CQE
+    /// posts from the same call site.
+    epoll_fd: RawFd,
+    /// Eventfd written by Python producer threads after pushing into the
+    /// submission queue. Replaces the `Condvar::notify_one` used in the
+    /// pre-eventfd design. Also written by `do_close` so the worker can
+    /// break out of `epoll_wait` and observe the shutdown flag.
+    producer_efd: RawFd,
+    /// Eventfd registered with the io_uring instance via
+    /// `Submitter::register_eventfd`. The kernel writes to it whenever a
+    /// CQE is posted, so the worker is woken without having to drain the
+    /// completion queue speculatively.
+    cq_efd: RawFd,
+}
+
+impl UringNotify {
+    /// Builds the three fds (two eventfds + one epoll) and wires the
+    /// eventfds into the epoll instance. Cleans up partially-built state
+    /// on any error path so no fd leaks if construction fails midway.
+    fn new() -> io::Result<Self> {
+        // Producer-side eventfd. Counter starts at 0 (no pending events).
+        // EFD_CLOEXEC prevents leaking the fd into a child process via
+        // execve. EFD_NONBLOCK makes read() return EAGAIN (instead of
+        // blocking) when the counter is already 0; wait() relies on this
+        // non-blocking behaviour to drain safely without hanging.
+        let producer_efd = unsafe { libc::eventfd(0, libc::EFD_CLOEXEC | libc::EFD_NONBLOCK) };
+        if producer_efd < 0 {
+            // Nothing else has been allocated yet -- just bubble the error.
+            return Err(io::Error::last_os_error());
+        }
+
+        // CQ-side eventfd. The kernel writes to this one after
+        // register_eventfd() is called on the io_uring instance.
+        let cq_efd = unsafe { libc::eventfd(0, libc::EFD_CLOEXEC | libc::EFD_NONBLOCK) };
+        if cq_efd < 0 {
+            // producer_efd is live -- close it before bubbling the error.
+            let e = io::Error::last_os_error();
+            unsafe { libc::close(producer_efd) };
+            return Err(e);
+        }
+
+        // Epoll instance fd. EPOLL_CLOEXEC for the same hygiene reason as
+        // EFD_CLOEXEC above.
+        let epoll_fd = unsafe { libc::epoll_create1(libc::EPOLL_CLOEXEC) };
+        if epoll_fd < 0 {
+            // Both eventfds are live; close them before returning.
+            let e = io::Error::last_os_error();
+            unsafe {
+                libc::close(producer_efd);
+                libc::close(cq_efd);
+            }
+            return Err(e);
+        }
+
+        // Register both eventfds with the epoll instance so epoll_wait
+        // can block on either source.
+        //
+        // We use EPOLLIN: wake when the counter becomes non-zero
+        // (someone signalled). Alternatives we deliberately don't use:
+        //   - EPOLLOUT (writable): pointless -- eventfd is effectively
+        //     always writable, so it would just busy-loop epoll_wait.
+        //   - EPOLLET (edge-triggered): would require fully draining
+        //     every wake-up in one go to avoid missing edges. Default
+        //     level-triggered fits our drain pattern in wait().
+        //   - EPOLLONESHOT: would auto-disarm after each fire and force
+        //     us to re-register; not worth the complexity.
+        // u64 stores the fd value itself so wait() can identify which
+        // fd fired without keeping a side map.
+        for fd in [producer_efd, cq_efd] {
+            let mut ev = libc::epoll_event {
+                events: libc::EPOLLIN as u32,
+                u64: fd as u64,
+            };
+            let rc = unsafe { libc::epoll_ctl(epoll_fd, libc::EPOLL_CTL_ADD, fd, &mut ev) };
+            if rc < 0 {
+                // All three fds are live; clean up all of them.
+                let e = io::Error::last_os_error();
+                unsafe {
+                    libc::close(epoll_fd);
+                    libc::close(producer_efd);
+                    libc::close(cq_efd);
+                }
+                return Err(e);
+            }
+        }
+
+        // Ownership of all three fds moves into Self; Drop handles the
+        // happy-path close.
+        Ok(Self {
+            epoll_fd,
+            producer_efd,
+            cq_efd,
+        })
+    }
+
+    /// Wakes the worker thread by writing 1 to `producer_efd`. Called by
+    /// producers after pushing a submission into the queue and by `do_close`
+    /// to break the worker out of `epoll_wait` for shutdown.
+    fn signal_producer(&self) {
+        let v: u64 = 1;
+        // Given EFD_NONBLOCK and counter < u64::MAX - 1, the 8-byte write
+        // always succeeds, so the return value is intentionally ignored.
+        unsafe {
+            libc::write(
+                self.producer_efd,
+                &v as *const u64 as *const libc::c_void,
+                8,
+            );
+        }
+    }
+
+    /// Blocks the worker until either eventfd is readable, then drains
+    /// each fired fd. Drain is required because epoll is level-triggered:
+    /// without consuming the counter, the next epoll_wait would return
+    /// immediately on the same already-handled signal.
+    fn wait(&self) {
+        // A capacity of 2 is enough: only two fds are registered with this
+        // epoll instance, so at most two events can come back per call.
+        let mut events = [libc::epoll_event { events: 0, u64: 0 }; 2];
+
+        // Timeout = -1 means "block indefinitely". Shutdown wakes us by
+        // writing producer_efd from do_close, so we never need a timeout.
+        let n = unsafe { libc::epoll_wait(self.epoll_fd, events.as_mut_ptr(), 2, -1) };
+
+        // n < 0 is usually EINTR (signal interruption); we just return and
+        // the worker's outer loop will call wait() again. n == 0 should
+        // not happen with timeout=-1 but is handled defensively.
+        if n <= 0 {
+            return;
+        }
+
+        // For each event reported, read 8 bytes from the corresponding
+        // eventfd to reset its counter to 0. The fd value was stashed in
+        // ev.u64 during epoll_ctl registration. We discard the read value
+        // (we only care that a signal arrived, not how many).
+        let mut buf = [0u8; 8];
+        for ev in &events[..n as usize] {
+            let fd = ev.u64 as RawFd;
+            // Discard the result. The wake-up was already delivered by
+            // epoll_wait; this read only exists to reset the eventfd
+            // counter so epoll stops reporting the fd as readable. If it
+            // fails, the worst case is one spurious wake-up next
+            // iteration. No work is lost, because the real submissions
+            // live in the queue and CQ, not in the bytes we just read.
+            unsafe {
+                libc::read(fd, buf.as_mut_ptr() as *mut libc::c_void, 8);
+            }
+        }
+    }
+}
+
+impl Drop for UringNotify {
+    fn drop(&mut self) {
+        unsafe {
+            libc::close(self.epoll_fd);
+            libc::close(self.producer_efd);
+            libc::close(self.cq_efd);
+        }
+    }
+}
+
+/// Represents a single I/O submission to io_uring.
+///
+/// This struct is sent from Python threads to the worker thread via a queue.
+/// It contains all information needed to perform the I/O operation.
+///
+/// Fields:
+/// - `fd`: File descriptor for the block device
+/// - `offset`: Byte offset on the device to read/write
+/// - `len`: Number of bytes to transfer
+/// - `ptr_addr`: Memory address of the buffer (as usize for Send)
+/// - `is_write`: true for write, false for read
+/// - `completion`: Shared completion primitive for signaling result
+/// - `fixed_buffer_idx`: Index into registered fixed buffers (if using zero-copy)
+/// - `bounce`: optional bounce buffer when O_DIRECT requires alignment.
+/// - `original_ptr`: For reads with bounce buffer, the original destination pointer.
+/// - `payload_len`: For reads with bounce buffer, the actual payload length to copy back.
+/// - `batch_id`: The batch ID this submission belongs to (for per-batch tracking)
+/// - `nvme_cmd_data`: Optional NVMe command for io_uring_cmd submission
+#[derive(Clone)]
+struct IoSubmission {
+    fd: RawFd,
+    offset: u64,
+    len: usize,
+    ptr_addr: usize,
+    is_write: bool,
+    completion: Arc<IoCompletion>,
+    fixed_buffer_idx: Option<u16>,
+    bounce: Option<std::sync::Arc<AlignedBuf>>,
+    original_ptr: Option<usize>,        // For bounce buffer reads
+    payload_len: Option<usize>,         // For bounce buffer reads
+    batch_id: u64,                      // Batch ID for per-batch tracking
+    nvme_cmd_data: Option<NvmeCmdData>, // NVMe command data for io_uring_cmd
+}
+
+impl Default for IoSubmission {
+    fn default() -> Self {
+        IoSubmission {
+            fd: -1 as RawFd,
+            offset: 0,
+            len: 0,
+            ptr_addr: 0,
+            is_write: false,
+            completion: Arc::new(IoCompletion::new()),
+            fixed_buffer_idx: None,
+            bounce: None,
+            original_ptr: None,
+            payload_len: None,
+            batch_id: 0,
+            nvme_cmd_data: None,
+        }
+    }
+}
+
+/// Raw block device I/O interface for Python.
+///
+/// - Synchronous I/O (pread/pwrite) - always available
+/// - Asynchronous I/O via io_uring - optional, enabled with use_iouring flag
+/// Higher-level policies (slotting, manifests, etc.) live in Python.
+#[pyclass]
+struct RawBlockDevice {
+    fd: RawFd,           // raw file descriptor
+    size: u64,           // cached device size in bytes
+    closed: AtomicBool,  // avoid double-close
+    use_odirect: bool,   // enforce alignment + bypass page cache
+    alignment: usize,    // required alignment in bytes
+    use_iouring: bool,   // Enable io_uring
+    use_uring_cmd: bool, // Enable io_uring_cmd for NVMe passthrough
+    // NVMe device data (only when use_uring_cmd=true)
+    nvme_nsid: Option<u32>,      // Namespace ID
+    nvme_lba_shift: Option<u32>, // LBA shift (log2 of LBA size)
+    nvme_lba_size: Option<u32>,  // LBA size in bytes
+    // io_uring ring instance (only when use_iouring=true)
+    // Uses wrapper to support both standard and big entries for kernel compatibility
+    ring: Option<IoUringWrapper>,
+    // Queue for sending I/O requests from Python to worker thread
+    queue: Option<Arc<Mutex<Vec<IoSubmission>>>>,
+    // Background worker thread handle
+    worker: Option<thread::JoinHandle<()>>,
+    // Shutdown signal for worker thread
+    shutdown: Option<Arc<AtomicBool>>,
+    // Map from buffer pointer address to registered fixed buffer index
+    // Used for zero-copy I/O with pre-registered buffers
+    fixed_buffer_map: Arc<Mutex<HashMap<usize, (u16, usize)>>>,
+    // Flag indicating if fixed buffers have been registered
+    fixed_buffers_registered: Arc<AtomicBool>,
+    // Count of currently in-flight I/O operations (global)
+    // Used for shutdown and cleanup
+    in_flight_count: Arc<AtomicU64>,
+    // Condition variable for signaling when in_flight_count reaches 0
+    in_flight_cvar: Arc<Condvar>,
+    // Per-batch in-flight count tracking
+    // Maps batch_id -> (in_flight_count, condition_variable)
+    batch_in_flight: Arc<Mutex<HashMap<u64, BatchTracking>>>,
+    // Worker wake-up: producer eventfd + ring CQ eventfd, both polled via
+    // a single epoll_fd. Replaces the previous `Arc<Condvar>` which couldn't
+    // be signaled from the kernel-side completion queue.
+    batch_ready: Option<Arc<UringNotify>>,
+    // Store Python buffer objects for writes, reads to keep them alive until they complete
+    // This prevents premature garbage collection while io_uring is using the buffers
+    // Keyed by batch_id to isolate concurrent batches
+    batched_buffer_objs: Arc<Mutex<HashMap<u64, Vec<Py<PyAny>>>>>,
+    // Store IoCompletion objects for batched operations to check for I/O errors
+    // Keyed by batch_id to isolate concurrent batches
+    batched_completions: Arc<Mutex<HashMap<u64, Vec<Arc<IoCompletion>>>>>,
+    // Counter for generating unique batch IDs
+    next_batch_id: Arc<AtomicU64>,
+}
+
+/// RAII guard for a raw file descriptor
+struct FdGuard {
+    fd: RawFd,
+}
+
+impl FdGuard {
+    /// Takes ownership of an open file descriptor.
+    ///
+    /// Args:
+    /// - `fd`: a descriptor returned by a successful `open()`.
+    fn new(fd: RawFd) -> Self {
+        FdGuard { fd }
+    }
+
+    /// Releases ownership of the fd to the caller, disarming the guard so the
+    /// descriptor is not closed on drop.
+    ///
+    /// Returns the raw descriptor, now owned by the caller.
+    fn disarm(self) -> RawFd {
+        let fd = self.fd;
+        std::mem::forget(self);
+        fd
+    }
+}
+
+impl Drop for FdGuard {
+    fn drop(&mut self) {
+        // SAFETY: `fd` was returned by a successful `open()` and ownership has
+        // not been released via `disarm()`, so this is the only close of this
+        // descriptor.
+        unsafe {
+            libc::close(self.fd);
+        }
+    }
+}
+
+impl RawBlockDevice {
+    /// Internal constructor performs all low level setup.
+    #[allow(clippy::too_many_arguments)]
+    fn new_internal(
+        path: String,
+        writable: bool,
+        use_odirect: bool,
+        alignment: usize,
+        use_iouring: bool,
+        use_uring_cmd: bool,
+        io_engine: Option<String>,
+        iouring_queue_depth: usize,
+    ) -> PyResult<Self> {
+        let use_iouring = parse_use_iouring(io_engine, use_iouring)?;
+        let iouring_queue_depth = iouring_queue_depth.max(1);
+        // use_uring_cmd requires use_iouring to be enabled
+        if use_uring_cmd && !use_iouring {
+            return Err(PyValueError::new_err(
+                "use_uring_cmd requires use_iouring to be enabled",
+            ));
+        }
+        let cpath =
+            CString::new(path.clone()).map_err(|_| PyValueError::new_err("path contains NUL"))?;
+        let mut flags = if writable {
+            libc::O_RDWR
+        } else {
+            libc::O_RDONLY
+        };
+        if use_odirect && !use_uring_cmd {
+            flags |= O_DIRECT;
+        }
+        // SAFETY: open returns fd or -1.
+        let fd = unsafe { libc::open(cpath.as_ptr(), flags) };
+        if fd < 0 {
+            return Err(os_err("open failed"));
+        }
+        // Take ownership of the fd so it is closed if any fallible setup step
+        // below returns early before the fd is moved into the RawBlockDevice.
+        // Disarmed once the struct is successfully constructed.
+        let fd_guard = FdGuard::new(fd);
+
+        // Initialize NVMe data if io_uring command support is enabled
+        let (nvme_nsid, nvme_lba_shift, nvme_lba_size, nvme_id_ns) = if use_uring_cmd {
+            // Validate that device is a character device (required for io_uring_cmd)
+            let is_char_dev = is_character_device(&path)?;
+            if !is_char_dev {
+                return Err(PyValueError::new_err(
+                    "use_uring_cmd requires an NVMe namespace character device (e.g., /dev/ng0n1)",
+                ));
+            }
+
+            // Get namespace ID from device path
+            let nsid = nvme_get_nsid_from_fd(fd)?;
+            // Send identify namespace command to get LBA size
+            let id_ns = nvme_identify_ns(fd, nsid)?;
+            let lba_shift = nvme_get_lba_shift(&id_ns)?;
+            let lba_size = nvme_get_lba_size(&id_ns)?;
+
+            (Some(nsid), Some(lba_shift), Some(lba_size), Some(id_ns))
+        } else {
+            (None, None, None, None)
+        };
+
+        // Calculate device size. Use NVMe ns info for character device
+        // Use ioctl/fstat for block devices and regular files
+        let size = if use_uring_cmd {
+            if let (Some(id_ns), Some(lba_size)) = (nvme_id_ns, nvme_lba_size) {
+                nvme_ns_size_bytes(&id_ns, lba_size)
+            } else {
+                0
+            }
+        } else {
+            fd_size_bytes(fd)?
+        };
+
+        let (
+            ring_opt,
+            queue_opt,
+            shutdown_opt,
+            worker_opt,
+            batch_ready_opt,
+            in_flight_count_opt,
+            in_flight_cvar_opt,
+            batched_buffer_objs_opt,
+            batched_completions_opt,
+            next_batch_id_opt,
+            batch_in_flight_opt,
+        ) = if use_iouring {
+            let notify = UringNotify::new()
+                .map_err(|e| PyRuntimeError::new_err(format!("UringNotify init failed: {}", e)))?;
+            // Try to create IoUring with big entries (Entry128/Entry32) first
+            // This is required for io_uring_cmd support (kernel 5.19+)
+            // If that fails, fall back to standard entries (Entry/Entry) for kernel 5.4-5.18
+            let ring = match IoUring::<Entry128, Entry32>::builder()
+                .build(iouring_queue_depth as u32)
+            {
+                Ok(big_ring) => {
+                    // Big entries supported - io_uring_cmd can be used
+                    if use_uring_cmd {
+                        // Validate that device is a character device (required for io_uring_cmd)
+                        let is_char_dev = is_character_device(&path)?;
+                        if !is_char_dev {
+                            return Err(PyValueError::new_err(
+                                "use_uring_cmd requires an NVMe namespace character device (e.g., /dev/ng0n1)",
+                            ));
+                        }
+                    }
+                    // Register the CQ eventfd with the ring so the kernel writes to it
+                    // whenever a CQE is posted. Must happen before the ring is wrapped
+                    // in a Mutex / handed to the worker.
+                    big_ring
+                        .submitter()
+                        .register_eventfd(notify.cq_efd)
+                        .map_err(|e| {
+                            PyRuntimeError::new_err(format!("register_eventfd failed: {}", e))
+                        })?;
+                    let big_ring = Arc::new(Mutex::new(big_ring));
+                    IoUringWrapper::Big(big_ring)
+                }
+                Err(_) => {
+                    // Big entries not supported (kernel < 5.19), fall back to standard entries
+                    // io_uring_cmd is not available on these kernels
+                    if use_uring_cmd {
+                        return Err(PyRuntimeError::new_err(
+                            "io_uring_cmd requires kernel 5.19 or later (big SQE/CQE entries not supported)",
+                        ));
+                    }
+                    let std_ring = IoUring::<SqueueEntry, Entry>::builder()
+                        .build(iouring_queue_depth as u32)
+                        .map_err(|e| {
+                            PyRuntimeError::new_err(format!("io_uring init failed: {}", e))
+                        })?;
+                    // Register the CQ eventfd with the ring so the kernel writes to it
+                    // whenever a CQE is posted. Must happen before the ring is wrapped
+                    // in a Mutex / handed to the worker.
+                    std_ring
+                        .submitter()
+                        .register_eventfd(notify.cq_efd)
+                        .map_err(|e| {
+                            PyRuntimeError::new_err(format!("register_eventfd failed: {}", e))
+                        })?;
+                    let std_ring = Arc::new(Mutex::new(std_ring));
+                    IoUringWrapper::Standard(std_ring)
+                }
+            };
+            let queue = Arc::new(Mutex::new(Vec::<IoSubmission>::new()));
+            let shutdown = Arc::new(AtomicBool::new(false));
+            let batch_ready = Arc::new(notify);
+            let in_flight_count = Arc::new(AtomicU64::new(0));
+            let in_flight_cvar = Arc::new(Condvar::new());
+            let batched_buffer_objs = Arc::new(Mutex::new(HashMap::<u64, Vec<Py<PyAny>>>::new()));
+            let batched_completions =
+                Arc::new(Mutex::new(HashMap::<u64, Vec<Arc<IoCompletion>>>::new()));
+            let next_batch_id = Arc::new(AtomicU64::new(1));
+            let batch_in_flight = Arc::new(Mutex::new(HashMap::<u64, BatchTracking>::new()));
+
+            let ring_clone = ring.clone();
+            let queue_clone = Arc::clone(&queue);
+            let shutdown_clone = Arc::clone(&shutdown);
+            let batch_ready_clone = Arc::clone(&batch_ready);
+            let in_flight_count_clone = Arc::clone(&in_flight_count);
+            let in_flight_cvar_clone = Arc::clone(&in_flight_cvar);
+            let batch_in_flight_clone = Arc::clone(&batch_in_flight);
+            let ring_size = iouring_queue_depth;
+
+            // Helper function to copy data from bounce buffer to original buffer
+            fn copy_from_bounce_buffer(bounce: &AlignedBuf, orig_ptr: usize, payload_len: usize) {
+                unsafe {
+                    libc::memcpy(
+                        orig_ptr as *mut libc::c_void,
+                        bounce.as_ptr() as *const libc::c_void,
+                        payload_len,
+                    );
+                }
+            }
+
+            // Helper function to handle completion result and set IoCompletion
+            // Returns Ok(()) for successful completion, Err for errors
+            // Note: Short I/O resubmission for regular I/O is handled BEFORE calling this function
+            // in the main completion loop. This function only handles:
+            // - Full completions
+            // - Errors (negative results)
+            // - Short I/O during shutdown (cannot resubmit)
+            fn handle_completion_result(
+                sub: &mut IoSubmission,
+                cqe_result: i32,
+                is_shutdown: bool,
+            ) -> PyResult<()> {
+                let is_uring_cmd = sub.nvme_cmd_data.is_some();
+
+                if cqe_result < 0 {
+                    let code = -cqe_result;
+                    let _ = sub.bounce.take();
+                    Err(PyOSError::new_err((code, "io_uring I/O error")))
+                } else if is_uring_cmd {
+                    // Non-zero result indicates NVMe command error
+                    if cqe_result != 0 {
+                        let code = cqe_result;
+                        let _ = sub.bounce.take();
+                        Err(PyOSError::new_err((code, "io_uring_cmd NVMe error")))
+                    } else {
+                        // io_uring_cmd successful completion (result == 0)
+                        // For reads with bounce buffer, copy data back to original buffer
+                        if !sub.is_write {
+                            if let (Some(bounce), Some(orig_ptr), Some(payload_len)) =
+                                (sub.bounce.take(), sub.original_ptr, sub.payload_len)
+                            {
+                                copy_from_bounce_buffer(&bounce, orig_ptr, payload_len);
+                            }
+                        } else {
+                            let _ = sub.bounce.take();
+                        }
+                        Ok(())
+                    }
+                } else {
+                    // Regular io_uring read/write
+                    let bytes_transferred = cqe_result as usize;
+                    if bytes_transferred < sub.len {
+                        if is_shutdown {
+                            // Short read/write during shutdown: fail the request
+                            let _ = sub.bounce.take();
+                            Err(PyRuntimeError::new_err(
+                                "io_uring worker shutting down: short I/O during shutdown",
+                            ))
+                        } else {
+                            // This should never happen
+                            let _ = sub.bounce.take();
+                            Err(PyRuntimeError::new_err(
+                                "Unexpected short I/O: internal error",
+                            ))
+                        }
+                    } else {
+                        // Full completion
+                        // For reads with bounce buffer, copy data back to original buffer
+                        if !sub.is_write {
+                            if let (Some(bounce), Some(orig_ptr), Some(payload_len)) =
+                                (sub.bounce.take(), sub.original_ptr, sub.payload_len)
+                            {
+                                copy_from_bounce_buffer(&bounce, orig_ptr, payload_len);
+                            }
+                        } else {
+                            let _ = sub.bounce.take();
+                        }
+                        Ok(())
+                    }
+                }
+            }
+
+            // Helper function to decrement in-flight counts and notify condition variables
+            fn decrement_in_flight(
+                in_flight_count: &Arc<AtomicU64>,
+                in_flight_cvar: &Arc<Condvar>,
+                batch_in_flight: &Arc<Mutex<HashMap<u64, BatchTracking>>>,
+                batch_id: u64,
+            ) {
+                let prev = in_flight_count.fetch_sub(1, Ordering::Relaxed);
+                if prev == 1 {
+                    in_flight_cvar.notify_all();
+                }
+                // Decrement per-batch in-flight count and notify if batch is complete
+                if batch_id != 0 {
+                    let batch_map = batch_in_flight.lock().unwrap();
+                    if let Some((batch_count, batch_cvar)) = batch_map.get(&batch_id) {
+                        let prev_batch = batch_count.fetch_sub(1, Ordering::Relaxed);
+                        if prev_batch == 1 {
+                            batch_cvar.notify_all();
+                        }
+                    }
+                }
+            }
+
+            // Helper function to build and submit an SQE for a submission
+            fn build_and_submit_sqe(
+                ring: &IoUringWrapper,
+                sub: &IoSubmission,
+                user_data: u64,
+            ) -> Result<(), PyErr> {
+                let ptr = sub.ptr_addr as *mut u8;
+
+                // Check if this is an io_uring_cmd submission
+                if let Some(nvme_data) = &sub.nvme_cmd_data {
+                    // Prepare NVMe uring command
+                    let mut nvme_cmd: NvmeUringCmd = unsafe { std::mem::zeroed() };
+                    nvme_uring_cmd_prep(
+                        &mut nvme_cmd,
+                        sub.is_write,
+                        nvme_data.nsid,
+                        sub.offset,
+                        sub.len,
+                        nvme_data.lba_shift,
+                        ptr,
+                        nvme_data.dtype,
+                        nvme_data.dspec,
+                    )?;
+
+                    // Convert NvmeUringCmd to byte array for UringCmd80
+                    let cmd_bytes: [u8; 80] = unsafe { std::mem::transmute_copy(&nvme_cmd) };
+
+                    // Build UringCmd80 with big SQE entry
+                    let mut uring_cmd =
+                        opcode::UringCmd80::new(Fd(sub.fd), NVME_URING_CMD_IO).cmd(cmd_bytes);
+
+                    // Set buf_index if using fixed buffers
+                    if let Some(idx) = sub.fixed_buffer_idx {
+                        uring_cmd = uring_cmd.buf_index(Some(idx));
+                    }
+
+                    let sqe128 = uring_cmd.build().user_data(user_data);
+
+                    // Push the big SQE entry (128 bytes)
+                    match ring {
+                        IoUringWrapper::Big(ring) => {
+                            let mut ring = ring.lock().unwrap();
+                            unsafe {
+                                ring.submission()
+                                    .push(&sqe128)
+                                    .expect("failed to push sqe128");
+                            }
+                        }
+                        IoUringWrapper::Standard(_) => {
+                            return Err(PyRuntimeError::new_err(
+                                "io_uring_cmd requires big entries (kernel 5.19+)",
+                            ));
+                        }
+                    }
+                } else {
+                    // Regular read/write operations
+                    let sqe = if sub.is_write {
+                        if let Some(idx) = sub.fixed_buffer_idx {
+                            opcode::WriteFixed::new(
+                                Fd(sub.fd),
+                                ptr as *const u8,
+                                sub.len as u32,
+                                idx,
+                            )
+                            .offset(sub.offset)
+                            .build()
+                        } else {
+                            opcode::Write::new(Fd(sub.fd), ptr as *const u8, sub.len as u32)
+                                .offset(sub.offset)
+                                .build()
+                        }
+                    } else if let Some(idx) = sub.fixed_buffer_idx {
+                        opcode::ReadFixed::new(Fd(sub.fd), ptr, sub.len as u32, idx)
+                            .offset(sub.offset)
+                            .build()
+                    } else {
+                        opcode::Read::new(Fd(sub.fd), ptr, sub.len as u32)
+                            .offset(sub.offset)
+                            .build()
+                    };
+                    let sqe = sqe.user_data(user_data);
+                    // Convert to appropriate entry type based on ring type
+                    match ring {
+                        IoUringWrapper::Big(ring) => {
+                            let mut ring = ring.lock().unwrap();
+                            let sqe128: Entry128 = sqe.into();
+                            unsafe {
+                                ring.submission().push(&sqe128).expect("failed to push sqe");
+                            }
+                        }
+                        IoUringWrapper::Standard(ring) => {
+                            let mut ring = ring.lock().unwrap();
+                            unsafe {
+                                ring.submission().push(&sqe).expect("failed to push sqe");
+                            }
+                        }
+                    }
+                }
+                Ok(())
+            }
+
+            // Worker thread that handles io_uring submissions and completions.
+            //
+            // Runs a continuous loop that:
+            // - Processes completion queue events (CQ) from the kernel
+            // - Waits for new I/O requests from Python via the queue
+            // - Submits new requests to the kernel (SQ)
+            //
+            // On shutdown, we must process ALL pending requests to avoid deadlocks:
+            // - Requests still in the queue
+            // - Requests already submitted to kernel (in_flight)
+            // Each waiting Python thread must be woken up with an error.
+            //
+            // Thread safety: All access to shared state (ring, queue, in_flight)
+            // is protected by mutexes. The worker is the only thread that:
+            // - Reads from the submission queue
+            // - Submits to io_uring
+            // - Processes completions
+            let worker = thread::Builder::new()
+                .name("rust-rawblock-uring".into())
+                .spawn(move || {
+                    let mut in_flight: HashMap<u64, IoSubmission> = HashMap::new();
+                    let mut next_user_data: u64 = 1;
+
+                    while !shutdown_clone.load(Ordering::Relaxed) {
+                        // This drains all completed I/O operations from the completion queue (CQ).
+                        // For each completion:
+                        //   - Remove the request from our in_flight tracking HashMap
+                        //   - Signal the waiting Python thread via IoCompletion
+                        //   - Decrement the in_flight_count atomic
+                        //   - Wake up any threads waiting for all I/O to complete
+                        {
+                            // Process completions for standard ring
+                            if let IoUringWrapper::Standard(ring) = &ring_clone {
+                                let completions: Vec<_> = {
+                                    let mut ring = ring.lock().unwrap();
+                                    ring.completion().collect()
+                                };
+                                for cqe in completions {
+                                    let user_data = cqe.user_data();
+                                    if let Some(mut sub) = in_flight.remove(&user_data) {
+                                        let batch_id = sub.batch_id;
+                                        let cqe_result = cqe.result();
+
+                                        // Handle short I/O with resubmission (only for regular I/O, not io_uring_cmd)
+                                        if cqe_result >= 0
+                                            && (cqe_result as usize) < sub.len
+                                            && sub.nvme_cmd_data.is_none()
+                                        {
+                                            let bytes_transferred = cqe_result as usize;
+                                            // Update offset and length for resubmission
+                                            sub.offset += bytes_transferred as u64;
+                                            sub.len -= bytes_transferred;
+                                            // Update buffer pointer for writes and direct reads
+                                            if sub.is_write || sub.bounce.is_none() {
+                                                sub.ptr_addr += bytes_transferred;
+                                            }
+                                            // For read with bounce buffer, copy partial data back
+                                            if !sub.is_write {
+                                                if let (
+                                                    Some(bounce),
+                                                    Some(orig_ptr),
+                                                    Some(payload_len),
+                                                ) = (
+                                                    sub.bounce.as_ref(),
+                                                    sub.original_ptr,
+                                                    sub.payload_len,
+                                                ) {
+                                                    copy_from_bounce_buffer(
+                                                        bounce,
+                                                        orig_ptr,
+                                                        bytes_transferred.min(payload_len),
+                                                    );
+                                                    sub.original_ptr =
+                                                        Some(orig_ptr + bytes_transferred);
+                                                    sub.payload_len = Some(
+                                                        payload_len
+                                                            .saturating_sub(bytes_transferred),
+                                                    );
+                                                }
+                                            }
+                                            // Re-insert into in_flight with updated values
+                                            // Don't decrement in_flight_count since we're resubmitting
+                                            in_flight.insert(user_data, sub.clone());
+                                            // Push a new SQE for the remaining data
+                                            let _ =
+                                                build_and_submit_sqe(&ring_clone, &sub, user_data);
+                                            let _ = match &ring_clone {
+                                                IoUringWrapper::Standard(ring) => {
+                                                    let ring = ring.lock().unwrap();
+                                                    ring.submitter().submit()
+                                                }
+                                                IoUringWrapper::Big(ring) => {
+                                                    let ring = ring.lock().unwrap();
+                                                    ring.submitter().submit()
+                                                }
+                                            };
+                                            continue;
+                                        }
+
+                                        // Handle completion result
+                                        let result =
+                                            handle_completion_result(&mut sub, cqe_result, false);
+                                        sub.completion.set(result);
+
+                                        // Decrement in-flight counts and notify
+                                        decrement_in_flight(
+                                            &in_flight_count_clone,
+                                            &in_flight_cvar_clone,
+                                            &batch_in_flight_clone,
+                                            batch_id,
+                                        );
+                                    }
+                                }
+                            } else if let IoUringWrapper::Big(ring) = &ring_clone {
+                                let completions: Vec<_> = {
+                                    let mut ring = ring.lock().unwrap();
+                                    ring.completion().collect()
+                                };
+                                for cqe in completions {
+                                    let user_data = cqe.user_data();
+                                    if let Some(mut sub) = in_flight.remove(&user_data) {
+                                        let batch_id = sub.batch_id;
+                                        let cqe_result = cqe.result();
+
+                                        // Handle short I/O with resubmission (only for regular I/O, not io_uring_cmd)
+                                        if cqe_result >= 0
+                                            && (cqe_result as usize) < sub.len
+                                            && sub.nvme_cmd_data.is_none()
+                                        {
+                                            let bytes_transferred = cqe_result as usize;
+                                            // Update offset and length for resubmission
+                                            sub.offset += bytes_transferred as u64;
+                                            sub.len -= bytes_transferred;
+                                            // Update buffer pointer for writes and direct reads
+                                            if sub.is_write || sub.bounce.is_none() {
+                                                sub.ptr_addr += bytes_transferred;
+                                            }
+                                            // For read with bounce buffer, copy partial data back
+                                            if !sub.is_write {
+                                                if let (
+                                                    Some(bounce),
+                                                    Some(orig_ptr),
+                                                    Some(payload_len),
+                                                ) = (
+                                                    sub.bounce.as_ref(),
+                                                    sub.original_ptr,
+                                                    sub.payload_len,
+                                                ) {
+                                                    copy_from_bounce_buffer(
+                                                        bounce,
+                                                        orig_ptr,
+                                                        bytes_transferred.min(payload_len),
+                                                    );
+                                                    sub.original_ptr =
+                                                        Some(orig_ptr + bytes_transferred);
+                                                    sub.payload_len = Some(
+                                                        payload_len
+                                                            .saturating_sub(bytes_transferred),
+                                                    );
+                                                }
+                                            }
+                                            // Re-insert into in_flight with updated values
+                                            // Don't decrement in_flight_count since we're resubmitting
+                                            in_flight.insert(user_data, sub.clone());
+                                            // Push a new SQE for the remaining data
+                                            let _ =
+                                                build_and_submit_sqe(&ring_clone, &sub, user_data);
+                                            let _ = match &ring_clone {
+                                                IoUringWrapper::Standard(ring) => {
+                                                    let ring = ring.lock().unwrap();
+                                                    ring.submitter().submit()
+                                                }
+                                                IoUringWrapper::Big(ring) => {
+                                                    let ring = ring.lock().unwrap();
+                                                    ring.submitter().submit()
+                                                }
+                                            };
+                                            continue;
+                                        }
+
+                                        // Handle completion result
+                                        let result =
+                                            handle_completion_result(&mut sub, cqe_result, false);
+                                        sub.completion.set(result);
+
+                                        // Decrement in-flight counts and notify
+                                        decrement_in_flight(
+                                            &in_flight_count_clone,
+                                            &in_flight_cvar_clone,
+                                            &batch_in_flight_clone,
+                                            batch_id,
+                                        );
+                                    }
+                                }
+                            }
+                            ring_clone.submission_sync();
+                        }
+
+                        // Block on epoll only if there's truly nothing pending. The empty +
+                        // shutdown checks short-circuit so we don't sleep when a producer or
+                        // do_close() already left work for us. Race-free against a late
+                        // signal_producer(): eventfd is a counter, so a wake-up between the
+                        // check and wait() is buffered, not lost.
+                        if !shutdown_clone.load(Ordering::Relaxed)
+                            && queue_clone.lock().unwrap().is_empty()
+                        {
+                            batch_ready_clone.wait();
+                        }
+
+                        let mut q = queue_clone.lock().unwrap();
+                        if !q.is_empty() {
+                            // Take all pending requests from our queue and submit them to io_uring.
+                            //
+                            // - Remove all pending requests from queue
+                            // - Check how much space is available in the ring (max 256 entries)
+                            // - If batch is larger than available space, put excess back in queue
+                            // - Increment in_flight_count for each request we're about to submit
+                            // - Build SQE (Submission Queue Entry) for each request
+                            // - Push SQEs to the ring
+                            // - Call submit() to send them to the kernel
+                            //
+                            // Fixed Buffer Support:
+                            // - If the buffer was pre-registered with register_fixed_buffers(),
+                            //   we use ReadFixed/WriteFixed for true zero-copy I/O
+                            // - Otherwise we use regular Read/Write with user-space pointers
+                            let mut batch: Vec<IoSubmission> = std::mem::take(&mut *q);
+                            let batch_len = batch.len();
+
+                            let available = ring_size - ring_clone.submission_len();
+                            let to_submit_count = std::cmp::min(available, batch_len);
+
+                            if to_submit_count < batch_len {
+                                let remaining: Vec<_> = batch[to_submit_count..].to_vec();
+                                if !remaining.is_empty() {
+                                    q.extend(remaining);
+                                }
+                            }
+
+                            drop(q);
+
+                            // Track user_data values for each submission to clean up in_flight entries
+                            // if submit() fails or returns partial count
+                            let mut user_data_list: Vec<u64> = Vec::with_capacity(to_submit_count);
+                            for sub in batch.iter().take(to_submit_count) {
+                                let user_data = next_user_data;
+                                next_user_data = next_user_data.wrapping_add(1);
+                                user_data_list.push(user_data);
+                                in_flight.insert(user_data, sub.clone());
+
+                                // Build and submit SQE
+                                let _ = build_and_submit_sqe(&ring_clone, sub, user_data);
+                            }
+
+                            let submit_result = match &ring_clone {
+                                IoUringWrapper::Standard(ring) => {
+                                    let ring = ring.lock().unwrap();
+                                    ring.submitter().submit()
+                                }
+                                IoUringWrapper::Big(ring) => {
+                                    let ring = ring.lock().unwrap();
+                                    ring.submitter().submit()
+                                }
+                            };
+                            // Handle EAGAIN (ring full) and EINTR (interrupted syscall)
+                            match submit_result {
+                                Ok(submitted) => {
+                                    // Any remaining requests in batch that weren't submitted
+                                    // will be retried in the next iteration of the loop
+                                    if submitted < to_submit_count {
+                                        // Remove in_flight entries for unsubmitted requests
+                                        for user_data in user_data_list[submitted..].iter() {
+                                            in_flight.remove(user_data);
+                                        }
+                                        // Put unsubmitted requests back in the queue for retry
+                                        let unsubmitted: Vec<_> =
+                                            batch[submitted..to_submit_count].to_vec();
+                                        if !unsubmitted.is_empty() {
+                                            let mut q = queue_clone.lock().unwrap();
+                                            // Insert unsubmitted requests back at the front preserving order
+                                            q.splice(0..0, unsubmitted);
+                                        }
+                                    }
+                                }
+                                Err(e) => {
+                                    // Handle submission errors
+                                    let error_code = e.raw_os_error();
+                                    match error_code {
+                                        Some(libc::EAGAIN) | Some(libc::EINTR) => {
+                                            // Ring is full, or the operation was interrupted due
+                                            // to signal. We need to wait for completions and then retry
+                                            // Remove in_flight entries for all submissions in this batch
+                                            for user_data in user_data_list.iter() {
+                                                in_flight.remove(user_data);
+                                            }
+                                            // Put unsubmitted requests back in queue for next iteration
+                                            if to_submit_count > 0 {
+                                                let unsubmitted: Vec<_> =
+                                                    batch[..to_submit_count].to_vec();
+                                                let mut q = queue_clone.lock().unwrap();
+                                                // Insert unsubmitted requests back at the front preserving order
+                                                q.splice(0..0, unsubmitted);
+                                            }
+                                        }
+                                        _ => {
+                                            // Error: fail all pending submissions in this batch.
+                                            // Remove in_flight entries since these won't generate completions
+                                            for user_data in user_data_list.iter() {
+                                                in_flight.remove(user_data);
+                                            }
+                                            for sub in batch.iter_mut().take(to_submit_count) {
+                                                let batch_id = sub.batch_id;
+                                                sub.completion.set(Err(PyRuntimeError::new_err(
+                                                    format!("io_uring submit error: {:?}", e),
+                                                )));
+                                                let _ = sub.bounce.take();
+                                                decrement_in_flight(
+                                                    &in_flight_count_clone,
+                                                    &in_flight_cvar_clone,
+                                                    &batch_in_flight_clone,
+                                                    batch_id,
+                                                );
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+
+                    // SHUTDOWN: Wake up all waiting Python threads
+                    // Drain the queue and wake up all waiting threads with error
+                    {
+                        let mut q = queue_clone
+                            .lock()
+                            .expect("Worker: queue mutex poisoned during shutdown");
+                        while let Some(mut sub) = q.pop() {
+                            let batch_id = sub.batch_id;
+                            let _ = sub.bounce.take();
+                            sub.completion.set(Err(PyRuntimeError::new_err(
+                                "io_uring worker shutting down",
+                            )));
+                            decrement_in_flight(
+                                &in_flight_count_clone,
+                                &in_flight_cvar_clone,
+                                &batch_in_flight_clone,
+                                batch_id,
+                            );
+                        }
+                    }
+
+                    // Process any remaining in-flight requests
+                    // Wait for kernel to complete the requests or force-cancel them
+                    // Note: This 1000 milliseconds is a rough estimate
+                    let graceful_shutdown = Duration::from_millis(1000);
+                    thread::sleep(graceful_shutdown);
+                    {
+                        // Process completions for standard ring
+                        if let IoUringWrapper::Standard(ring) = &ring_clone {
+                            let completions: Vec<_> = {
+                                let mut ring = ring.lock().unwrap();
+                                ring.completion().collect()
+                            };
+                            for cqe in completions {
+                                let user_data = cqe.user_data();
+                                if let Some(mut sub) = in_flight.remove(&user_data) {
+                                    let batch_id = sub.batch_id;
+                                    let result =
+                                        handle_completion_result(&mut sub, cqe.result(), true);
+                                    sub.completion.set(result);
+                                    decrement_in_flight(
+                                        &in_flight_count_clone,
+                                        &in_flight_cvar_clone,
+                                        &batch_in_flight_clone,
+                                        batch_id,
+                                    );
+                                }
+                            }
+                        } else if let IoUringWrapper::Big(ring) = &ring_clone {
+                            let completions: Vec<_> = {
+                                let mut ring = ring.lock().unwrap();
+                                ring.completion().collect()
+                            };
+                            for cqe in completions {
+                                let user_data = cqe.user_data();
+                                if let Some(mut sub) = in_flight.remove(&user_data) {
+                                    let batch_id = sub.batch_id;
+                                    let result =
+                                        handle_completion_result(&mut sub, cqe.result(), true);
+                                    sub.completion.set(result);
+                                    decrement_in_flight(
+                                        &in_flight_count_clone,
+                                        &in_flight_cvar_clone,
+                                        &batch_in_flight_clone,
+                                        batch_id,
+                                    );
+                                }
+                            }
+                        }
+                        ring_clone.submission_sync();
+                    }
+
+                    // Any remaining in_flight requests, force wake with error
+                    // (these were submitted to kernel but won't get completions)
+                    for (_user_data, mut sub) in in_flight.drain() {
+                        let batch_id = sub.batch_id;
+                        let _ = sub.bounce.take();
+                        sub.completion.set(Err(PyRuntimeError::new_err(
+                            "io_uring worker shutting down - request cancelled",
+                        )));
+                        decrement_in_flight(
+                            &in_flight_count_clone,
+                            &in_flight_cvar_clone,
+                            &batch_in_flight_clone,
+                            batch_id,
+                        );
+                    }
+
+                    // Final notification in case any thread is waiting on in_flight_count
+                    in_flight_cvar_clone.notify_all();
+                })
+                .expect("spawn rust-rawblock-uring worker");
+
+            (
+                Some(ring),
+                Some(queue),
+                Some(shutdown),
+                Some(worker),
+                Some(batch_ready),
+                Some(in_flight_count),
+                Some(in_flight_cvar),
+                Some(batched_buffer_objs),
+                Some(batched_completions),
+                Some(next_batch_id),
+                Some(batch_in_flight),
+            )
+        } else {
+            (
+                None, None, None, None, None, None, None, None, None, None, None,
+            )
+        };
+
+        // All fallible setup succeeded: hand the fd over to the struct, whose
+        // Drop is now responsible for closing it. Disarm so the guard does not
+        // close the same descriptor a second time.
+        let fd = fd_guard.disarm();
+
+        Ok(Self {
+            fd,
+            size,
+            closed: AtomicBool::new(false),
+            use_odirect,
+            alignment,
+            use_iouring,
+            use_uring_cmd,
+            nvme_nsid,
+            nvme_lba_shift,
+            nvme_lba_size,
+            ring: ring_opt,
+            queue: queue_opt,
+            worker: worker_opt,
+            shutdown: shutdown_opt,
+            fixed_buffer_map: Arc::new(Mutex::new(HashMap::new())),
+            fixed_buffers_registered: Arc::new(AtomicBool::new(false)),
+            in_flight_count: in_flight_count_opt.unwrap_or_else(|| Arc::new(AtomicU64::new(0))),
+            in_flight_cvar: in_flight_cvar_opt.unwrap_or_else(|| Arc::new(Condvar::new())),
+            batch_ready: batch_ready_opt,
+            batched_buffer_objs: batched_buffer_objs_opt
+                .unwrap_or_else(|| Arc::new(Mutex::new(HashMap::new()))),
+            batched_completions: batched_completions_opt
+                .unwrap_or_else(|| Arc::new(Mutex::new(HashMap::new()))),
+            next_batch_id: next_batch_id_opt.unwrap_or_else(|| Arc::new(AtomicU64::new(1))),
+            batch_in_flight: batch_in_flight_opt
+                .unwrap_or_else(|| Arc::new(Mutex::new(HashMap::new()))),
+        })
+    }
+
+    /// Build NVMe command data for io_uring_cmd operations.
+    /// Returns None if use_uring_cmd is disabled.
+    fn _build_nvme_cmd_data(&self, dtype: u8, dspec: u16) -> PyResult<Option<NvmeCmdData>> {
+        if !self.use_uring_cmd {
+            return Ok(None);
+        }
+        Ok(Some(NvmeCmdData {
+            nsid: self
+                .nvme_nsid
+                .ok_or_else(|| PyRuntimeError::new_err("NVMe namespace ID not available"))?,
+            lba_shift: self
+                .nvme_lba_shift
+                .ok_or_else(|| PyRuntimeError::new_err("NVMe LBA shift not available"))?,
+            dtype,
+            dspec,
+        }))
+    }
+}
+
+#[pymethods]
+impl RawBlockDevice {
+    #[new]
+    #[pyo3(
+        signature = (
+            path,
+            writable,
+            use_odirect = false,
+            use_iouring = false,
+            use_uring_cmd = false,
+            alignment = 4096,
+            io_engine = None,
+            iouring_queue_depth = RING_SIZE
+        )
+    )]
+    #[allow(clippy::too_many_arguments)]
+    fn new(
+        path: String,
+        writable: bool,
+        use_odirect: bool,
+        use_iouring: bool,
+        use_uring_cmd: bool,
+        alignment: usize,
+        io_engine: Option<String>,
+        iouring_queue_depth: usize,
+    ) -> PyResult<Self> {
+        Self::new_internal(
+            path,
+            writable,
+            use_odirect,
+            alignment,
+            use_iouring,
+            use_uring_cmd,
+            io_engine,
+            iouring_queue_depth,
+        )
+    }
+
+    // Expose cached size to Python.
+    fn size_bytes(&self) -> PyResult<u64> {
+        Ok(self.size)
+    }
+
+    /// Get NVMe namespace ID (only available when use_uring_cmd=true)
+    fn nvme_nsid(&self) -> PyResult<u32> {
+        self.nvme_nsid.ok_or_else(|| {
+            PyRuntimeError::new_err("NVMe namespace ID not available (use_uring_cmd not enabled)")
+        })
+    }
+
+    /// Get NVMe LBA shift (log2 of LBA size, only available when use_uring_cmd=true)
+    fn nvme_lba_shift(&self) -> PyResult<u32> {
+        self.nvme_lba_shift.ok_or_else(|| {
+            PyRuntimeError::new_err("NVMe LBA shift not available (use_uring_cmd not enabled)")
+        })
+    }
+
+    /// Get NVMe LBA size in bytes (only available when use_uring_cmd=true)
+    fn nvme_lba_size(&self) -> PyResult<u32> {
+        self.nvme_lba_size.ok_or_else(|| {
+            PyRuntimeError::new_err("NVMe LBA size not available (use_uring_cmd not enabled)")
+        })
+    }
+
+    /// Register fixed buffers for zero-copy io_uring operations.
+    ///
+    /// - Pre-registering memory buffers with the kernel
+    /// - Using indexed descriptors (instead of pointers) in I/O operations
+    /// - The kernel then does DMA directly from/to the registered buffers
+    ///
+    /// This is more efficient than regular I/O because:
+    /// - No buffer copying between user space and kernel
+    /// - The kernel can pin the memory pages for the duration of I/O
+    ///
+    /// Registration must happen BEFORE any I/O using these buffers.
+    /// The buffers must remain valid (not freed) until unregistered.
+    #[pyo3(signature = (buffer_ptrs, buffer_sizes))]
+    fn register_fixed_buffers(
+        &self,
+        buffer_ptrs: Vec<usize>,
+        buffer_sizes: Vec<usize>,
+    ) -> PyResult<()> {
+        if !self.use_iouring {
+            return Err(PyRuntimeError::new_err("io_uring not enabled"));
+        }
+        if buffer_ptrs.len() != buffer_sizes.len() {
+            return Err(PyValueError::new_err(
+                "buffer_ptrs and buffer_sizes must have same length",
+            ));
+        }
+        if buffer_ptrs.is_empty() {
+            return Err(PyValueError::new_err(
+                "at least one buffer must be provided",
+            ));
+        }
+
+        {
+            let mut map = self.fixed_buffer_map.lock().unwrap();
+            map.clear();
+            for (idx, (ptr, size)) in buffer_ptrs.iter().zip(buffer_sizes.iter()).enumerate() {
+                map.insert(*ptr, (idx as u16, *size));
+            }
+        }
+
+        if let Some(ring) = &self.ring {
+            let mut iovecs: Vec<libc::iovec> = Vec::new();
+            for (ptr, size) in buffer_ptrs.iter().zip(buffer_sizes.iter()) {
+                iovecs.push(libc::iovec {
+                    iov_base: *ptr as *mut libc::c_void,
+                    iov_len: *size,
+                });
+            }
+            unsafe {
+                let result = match ring {
+                    IoUringWrapper::Standard(ring) => {
+                        let ring = ring.lock().unwrap();
+                        ring.submitter().register_buffers(&iovecs)
+                    }
+                    IoUringWrapper::Big(ring) => {
+                        let ring = ring.lock().unwrap();
+                        ring.submitter().register_buffers(&iovecs)
+                    }
+                };
+                match result {
+                    Ok(_) => {
+                        self.fixed_buffers_registered.store(true, Ordering::Relaxed);
+                    }
+                    Err(e) => {
+                        return Err(PyRuntimeError::new_err(format!(
+                            "register_buffers failed: {}",
+                            e
+                        )))
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// Batched write: submit multiple writes at once via io_uring.
+    /// All writes are queued to the worker thread, which processes them
+    /// in batches to maximize throughput.
+    ///
+    /// Returns a batch_id that must be passed to wait_iouring() to wait
+    /// for completions for that batch.
+    #[pyo3(signature = (offsets, buffers, total_lens))]
+    fn batched_write(
+        &self,
+        py: Python<'_>,
+        offsets: Vec<u64>,
+        buffers: Vec<Bound<'_, PyAny>>,
+        total_lens: Vec<usize>,
+    ) -> PyResult<u64> {
+        if !self.use_iouring {
+            return Err(PyRuntimeError::new_err("io_uring not enabled"));
+        }
+        if self.closed.load(Ordering::Relaxed) {
+            return Err(PyRuntimeError::new_err("device is closed"));
+        }
+
+        let n = offsets.len();
+        if n == 0 {
+            // Return a valid batch_id even for empty batches
+            return Ok(self.next_batch_id.fetch_add(1, Ordering::Relaxed));
+        }
+        if buffers.len() != n || total_lens.len() != n {
+            return Err(PyValueError::new_err("All vectors must have same length"));
+        }
+
+        // Acquire buffer views to keep them alive until wait_iouring() completes
+        let mut views = Vec::with_capacity(n);
+        for buffer in &buffers {
+            let view = get_pybuffer(py, buffer, false)?;
+            if view.buf.is_null() {
+                for v in views {
+                    release_pybuffer(v);
+                }
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("null buffer pointer"));
+            }
+            views.push(view);
+        }
+
+        // Generate a unique batch ID for this batch
+        let batch_id = self.next_batch_id.fetch_add(1, Ordering::Relaxed);
+
+        // Initialize per-batch tracking for this batch
+        {
+            let mut batch_map = self.batch_in_flight.lock().unwrap();
+            batch_map.insert(
+                batch_id,
+                (Arc::new(AtomicU64::new(0)), Arc::new(Condvar::new())),
+            );
+        }
+
+        // Store buffer objects to keep them alive until they are complete
+        {
+            let mut stored_objs = self.batched_buffer_objs.lock().unwrap();
+            let batch_buffers = stored_objs.entry(batch_id).or_default();
+            for buffer in &buffers {
+                batch_buffers.push(buffer.clone().unbind());
+            }
+        }
+
+        // Extract pointers as usize before releasing GIL (raw pointers are not Send)
+        let mut ptrs = Vec::with_capacity(n);
+        for view in &views {
+            ptrs.push(view.buf as usize);
+        }
+
+        for view in views {
+            release_pybuffer(view);
+        }
+
+        let fd = self.fd;
+        let use_odirect = self.use_odirect;
+        let alignment = self.alignment;
+        let use_uring_cmd = self.use_uring_cmd;
+        let fixed_buffers_registered = self.fixed_buffers_registered.load(Ordering::Relaxed);
+        // Clone the fixed buffer map before releasing GIL to avoid lock contention
+        let fixed_buffer_map: HashMap<usize, (u16, usize)> = if fixed_buffers_registered {
+            let map = self.fixed_buffer_map.lock().unwrap();
+            map.clone()
+        } else {
+            HashMap::new()
+        };
+
+        let nvme_cmd_data_base = if use_uring_cmd {
+            Some((
+                self.nvme_nsid
+                    .ok_or_else(|| PyRuntimeError::new_err("NVMe namespace ID not available"))?,
+                self.nvme_lba_shift
+                    .ok_or_else(|| PyRuntimeError::new_err("NVMe LBA shift not available"))?,
+            ))
+        } else {
+            None
+        };
+        let in_flight_count = Arc::clone(&self.in_flight_count);
+        let queue = Arc::clone(self.queue.as_ref().unwrap());
+        let batch_ready = Arc::clone(self.batch_ready.as_ref().unwrap());
+        let batched_completions = Arc::clone(&self.batched_completions);
+        let batch_in_flight = Arc::clone(&self.batch_in_flight);
+        // Additional clones for cleanup on error path
+        let batch_in_flight_cleanup = Arc::clone(&batch_in_flight);
+        let batched_completions_cleanup = Arc::clone(&batched_completions);
+        let batched_buffer_objs_cleanup = Arc::clone(&self.batched_buffer_objs);
+
+        // Release the GIL while submitting I/O operations
+        let res = py.allow_threads(move || {
+            let mut submissions: Vec<(IoSubmission, Arc<IoCompletion>)> = Vec::with_capacity(n);
+
+            // Prepare all requests, bounce buffers (if needed) and collect submission data.
+            for i in 0..n {
+                let ptr = ptrs[i] as *const u8;
+                let total_len = total_lens[i];
+                let offset = offsets[i];
+
+                let comp = Arc::new(IoCompletion::new());
+
+                // Fixed buffers are pre-registered with io_uring, enabling true zero-copy I/O
+                let fixed_idx = fixed_buffer_map.get(&ptrs[i]).map(|(idx, _)| *idx);
+
+                // Ensure O_DIRECT buffers are aligned
+                let (final_ptr, bounce_opt, fixed_idx) = if use_odirect {
+                    let align = alignment;
+                    #[allow(clippy::manual_is_multiple_of)]
+                    if ptrs[i] % align != 0 {
+                        let bounce = AlignedBuf::new(total_len, align)?;
+                        unsafe {
+                            libc::memcpy(
+                                bounce.as_mut_ptr() as *mut libc::c_void,
+                                ptr as *const libc::c_void,
+                                total_len,
+                            );
+                        }
+                        let bounce_arc = std::sync::Arc::new(bounce);
+                        let bounce_ptr = bounce_arc.as_ptr();
+                        (bounce_ptr, Some(bounce_arc), None)
+                    } else {
+                        (ptr, None, fixed_idx)
+                    }
+                } else {
+                    (ptr, None, fixed_idx)
+                };
+
+                // Build NVMe command data
+                let nvme_cmd_data = if let Some((nsid, lba_shift)) = nvme_cmd_data_base {
+                    Some(NvmeCmdData {
+                        nsid,
+                        lba_shift,
+                        dtype: 0,
+                        dspec: 0,
+                    })
+                } else {
+                    None
+                };
+
+                let sub = IoSubmission {
+                    fd,
+                    offset,
+                    len: total_len,
+                    ptr_addr: final_ptr as usize,
+                    is_write: true,
+                    completion: comp.clone(),
+                    fixed_buffer_idx: fixed_idx,
+                    bounce: bounce_opt,
+                    original_ptr: None,
+                    payload_len: None,
+                    batch_id,
+                    nvme_cmd_data,
+                };
+
+                submissions.push((sub, comp));
+            }
+
+            // Queue all submissions atomically. At this point no further errors can
+            // occur during queuing.
+            for (sub, comp) in submissions {
+                in_flight_count.fetch_add(1, Ordering::Relaxed);
+
+                // Increment per-batch in-flight count
+                {
+                    let batch_map = batch_in_flight.lock().unwrap();
+                    if let Some((batch_count, _)) = batch_map.get(&batch_id) {
+                        batch_count.fetch_add(1, Ordering::Relaxed);
+                    }
+                }
+                {
+                    let mut q = queue.lock().unwrap();
+                    q.push(sub);
+                }
+                batch_ready.signal_producer();
+
+                // Store completion for error checking in wait_iouring
+                {
+                    let mut completions = batched_completions.lock().unwrap();
+                    let batch_completions = completions.entry(batch_id).or_default();
+                    batch_completions.push(comp);
+                }
+            }
+            Ok::<(), PyErr>(())
+        });
+
+        // Preparation failed, clean up the tracking entries to prevent leaks
+        if let Err(e) = res {
+            {
+                let mut batch_map = batch_in_flight_cleanup.lock().unwrap();
+                batch_map.remove(&batch_id);
+            }
+            {
+                let mut stored_objs = batched_buffer_objs_cleanup.lock().unwrap();
+                stored_objs.remove(&batch_id);
+            }
+            {
+                let mut completions = batched_completions_cleanup.lock().unwrap();
+                completions.remove(&batch_id);
+            }
+            return Err(e);
+        }
+
+        Ok(batch_id)
+    }
+
+    /// Wait for all in-flight I/O for a specific batch to complete.
+    /// The method waits on a per-batch condition variable that gets signaled
+    /// when the batch's in-flight count reaches 0.
+    ///
+    /// Args:
+    ///     batch_id: The batch ID returned by batched_write() or batched_read().
+    ///               Only completions from this batch are checked.
+    ///
+    /// Returns an error if any I/O operation in this batch failed. The error message
+    /// includes details about the first failure encountered.
+    #[pyo3(signature = (batch_id))]
+    fn wait_iouring(&self, py: Python<'_>, batch_id: u64) -> PyResult<()> {
+        if !self.use_iouring {
+            return Ok(());
+        }
+
+        // Get the per-batch tracking for this batch
+        let (batch_count, batch_cvar) = {
+            let batch_map = self.batch_in_flight.lock().unwrap();
+            match batch_map.get(&batch_id) {
+                Some((count, cvar)) => (Arc::clone(count), Arc::clone(cvar)),
+                None => {
+                    // Batch not found. This could be an empty batch or already completed
+                    // Check if there are any completions for this batch
+                    let mut completions = self.batched_completions.lock().unwrap();
+                    let batch_completions = completions.remove(&batch_id);
+                    let mut first_error: Option<PyErr> = None;
+                    if let Some(comp_vec) = batch_completions {
+                        for comp in comp_vec.iter() {
+                            if let Err(e) = comp.wait() {
+                                if first_error.is_none() {
+                                    first_error = Some(e);
+                                }
+                            }
+                        }
+                    }
+                    // Clear stored buffer objects for this batch
+                    let mut stored_objs = self.batched_buffer_objs.lock().unwrap();
+                    stored_objs.remove(&batch_id);
+                    return if let Some(e) = first_error {
+                        Err(e)
+                    } else {
+                        Ok(())
+                    };
+                }
+            }
+        };
+
+        // Release the GIL while waiting for I/O to complete
+        py.allow_threads(move || {
+            let mutex = Mutex::new(());
+            let mut guard = mutex.lock().unwrap();
+            while batch_count.load(Ordering::Relaxed) > 0 {
+                let (g, _) = batch_cvar
+                    .wait_timeout(guard, Duration::from_micros(10))
+                    .unwrap();
+                guard = g;
+            }
+        });
+
+        // Check all completion results for errors for this specific batch
+        let mut completions = self.batched_completions.lock().unwrap();
+        let batch_completions = completions.remove(&batch_id);
+        let mut first_error: Option<PyErr> = None;
+        if let Some(comp_vec) = batch_completions {
+            for comp in comp_vec.iter() {
+                if let Err(e) = comp.wait() {
+                    if first_error.is_none() {
+                        first_error = Some(e);
+                    }
+                }
+            }
+        }
+
+        // Clear stored buffer objects for this batch now that I/O is complete
+        let mut stored_objs = self.batched_buffer_objs.lock().unwrap();
+        stored_objs.remove(&batch_id);
+
+        // Clean up per-batch tracking
+        let mut batch_map = self.batch_in_flight.lock().unwrap();
+        batch_map.remove(&batch_id);
+
+        if let Some(e) = first_error {
+            Err(e)
+        } else {
+            Ok(())
+        }
+    }
+
+    /// Synchronous read using io_uring.
+    #[pyo3(signature = (offset, data, payload_len, total_len = None))]
+    fn read_uring(
+        &self,
+        py: Python<'_>,
+        offset: u64,
+        data: &Bound<'_, PyAny>,
+        payload_len: usize,
+        total_len: Option<usize>,
+    ) -> PyResult<()> {
+        if !self.use_iouring {
+            return Err(PyRuntimeError::new_err("io_uring not enabled"));
+        }
+        if self.closed.load(Ordering::Relaxed) {
+            return Err(PyRuntimeError::new_err("device is closed"));
+        }
+
+        let view = get_pybuffer(py, data, true)?;
+        if view.readonly != 0 {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("output buffer is readonly"));
+        }
+        let ptr = view.buf as *mut u8;
+        if ptr.is_null() {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("null buffer pointer"));
+        }
+
+        let cap = view.len as usize;
+        let total_len = total_len.unwrap_or(payload_len);
+        if cap < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err(format!(
+                "output buffer too small: cap={cap} need={payload_len}"
+            )));
+        }
+        if total_len < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("total_len must be >= payload_len"));
+        }
+
+        let align = self.alignment;
+        if self.use_odirect {
+            #[allow(clippy::manual_is_multiple_of)]
+            if (offset as usize) % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned offset"));
+            }
+            #[allow(clippy::manual_is_multiple_of)]
+            if total_len % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned total_len"));
+            }
+        }
+
+        // Check if the buffer is aligned for O_DIRECT
+        let ptr_aligned = if self.use_odirect {
+            (ptr as usize).is_multiple_of(align)
+        } else {
+            true
+        };
+
+        // Fixed buffers are pre-registered with io_uring, enabling true zero-copy I/O
+        let use_fixed = self.fixed_buffers_registered.load(Ordering::Relaxed);
+        let fixed_idx = if use_fixed && ptr_aligned {
+            let map = self.fixed_buffer_map.lock().unwrap();
+            let ptr_addr = ptr as usize;
+            map.get(&ptr_addr).map(|(idx, _)| *idx)
+        } else {
+            None
+        };
+
+        // Use bounce buffer if:
+        // Buffer is not aligned (O_DIRECT requirement)
+        // Buffer capacity is less than total_len
+        let use_bounce = !ptr_aligned || cap < total_len;
+
+        let res = if !use_bounce {
+            self.in_flight_count.fetch_add(1, Ordering::Relaxed);
+            let comp = Arc::new(IoCompletion::new());
+            let sub = IoSubmission {
+                fd: self.fd,
+                offset,
+                len: total_len,
+                ptr_addr: ptr as usize,
+                is_write: false,
+                completion: comp.clone(),
+                fixed_buffer_idx: fixed_idx,
+                bounce: None,
+                original_ptr: None,
+                payload_len: None,
+                batch_id: 0,
+                nvme_cmd_data: self._build_nvme_cmd_data(0, 0)?,
+            };
+            {
+                let q = self.queue.as_ref().expect("queue must exist");
+                let mut q = q.lock().unwrap();
+                q.push(sub);
+            }
+            if let Some(batch_ready) = &self.batch_ready {
+                batch_ready.signal_producer();
+            }
+            py.allow_threads(move || comp.wait())
+        } else {
+            let bounce = AlignedBuf::new(total_len, align)?;
+            let bounce_arc = std::sync::Arc::new(bounce);
+            let bounce_ptr = bounce_arc.as_mut_ptr();
+            self.in_flight_count.fetch_add(1, Ordering::Relaxed);
+            let comp = Arc::new(IoCompletion::new());
+            let sub = IoSubmission {
+                fd: self.fd,
+                offset,
+                len: total_len,
+                ptr_addr: bounce_ptr as usize,
+                is_write: false,
+                completion: comp.clone(),
+                fixed_buffer_idx: None,
+                bounce: Some(bounce_arc),
+                original_ptr: Some(ptr as usize),
+                payload_len: Some(payload_len),
+                batch_id: 0,
+                nvme_cmd_data: self._build_nvme_cmd_data(0, 0)?,
+            };
+            {
+                let q = self.queue.as_ref().expect("queue must exist");
+                let mut q = q.lock().unwrap();
+                q.push(sub);
+            }
+            if let Some(batch_ready) = &self.batch_ready {
+                batch_ready.signal_producer();
+            }
+            py.allow_threads(move || comp.wait())
+        };
+
+        release_pybuffer(view);
+        res?;
+        Ok(())
+    }
+
+    /// Synchronous write using io_uring.
+    #[pyo3(signature = (offset, data, payload_len, total_len = None))]
+    fn write_uring(
+        &self,
+        py: Python<'_>,
+        offset: u64,
+        data: &Bound<'_, PyAny>,
+        payload_len: usize,
+        total_len: Option<usize>,
+    ) -> PyResult<()> {
+        if !self.use_iouring {
+            return Err(PyRuntimeError::new_err("io_uring not enabled"));
+        }
+        if self.closed.load(Ordering::Relaxed) {
+            return Err(PyRuntimeError::new_err("device is closed"));
+        }
+
+        let view = get_pybuffer(py, data, false)?;
+        let ptr = view.buf as *const u8;
+        if ptr.is_null() {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("null buffer pointer"));
+        }
+
+        let cap = view.len as usize;
+        let total_len = total_len.unwrap_or(payload_len);
+        if cap < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err(format!(
+                "input buffer too small: cap={cap} need={payload_len}"
+            )));
+        }
+        if total_len < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("total_len must be >= payload_len"));
+        }
+
+        let align = self.alignment;
+        if self.use_odirect {
+            #[allow(clippy::manual_is_multiple_of)]
+            if (offset as usize) % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned offset"));
+            }
+            #[allow(clippy::manual_is_multiple_of)]
+            if total_len % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned total_len"));
+            }
+        }
+
+        // Check if the buffer is aligned for O_DIRECT
+        let ptr_aligned = if self.use_odirect {
+            (ptr as usize).is_multiple_of(align)
+        } else {
+            true
+        };
+
+        // Fixed buffers are pre-registered with io_uring, enabling true zero-copy I/O
+        let use_fixed = self.fixed_buffers_registered.load(Ordering::Relaxed);
+        let fixed_idx = if use_fixed && ptr_aligned {
+            let map = self.fixed_buffer_map.lock().unwrap();
+            let ptr_addr = ptr as usize;
+            map.get(&ptr_addr).map(|(idx, _)| *idx)
+        } else {
+            None
+        };
+
+        // Use bounce buffer if:
+        // Buffer is not aligned (O_DIRECT requirement)
+        // Buffer capacity is less than total_len
+        let use_bounce = !ptr_aligned || cap < total_len;
+
+        let res = if !use_bounce {
+            self.in_flight_count.fetch_add(1, Ordering::Relaxed);
+            let comp = Arc::new(IoCompletion::new());
+            let sub = IoSubmission {
+                fd: self.fd,
+                offset,
+                len: total_len,
+                ptr_addr: ptr as usize,
+                is_write: true,
+                completion: comp.clone(),
+                fixed_buffer_idx: fixed_idx,
+                bounce: None,
+                original_ptr: None,
+                payload_len: None,
+                batch_id: 0,
+                nvme_cmd_data: self._build_nvme_cmd_data(0, 0)?,
+            };
+            {
+                let q = self.queue.as_ref().expect("queue must exist");
+                let mut q = q.lock().unwrap();
+                q.push(sub);
+            }
+            if let Some(batch_ready) = &self.batch_ready {
+                batch_ready.signal_producer();
+            }
+            py.allow_threads(move || comp.wait())
+        } else {
+            let bounce = AlignedBuf::new(total_len, align)?;
+            let bounce_arc = std::sync::Arc::new(bounce);
+            let bounce_ptr = bounce_arc.as_mut_ptr();
+            // Copy data to bounce buffer before submission
+            unsafe {
+                std::ptr::copy_nonoverlapping(ptr, bounce_ptr, payload_len);
+            }
+            self.in_flight_count.fetch_add(1, Ordering::Relaxed);
+            let comp = Arc::new(IoCompletion::new());
+            let sub = IoSubmission {
+                fd: self.fd,
+                offset,
+                len: total_len,
+                ptr_addr: bounce_ptr as usize,
+                is_write: true,
+                completion: comp.clone(),
+                fixed_buffer_idx: None,
+                bounce: Some(bounce_arc),
+                original_ptr: None,
+                payload_len: Some(payload_len),
+                batch_id: 0,
+                nvme_cmd_data: self._build_nvme_cmd_data(0, 0)?,
+            };
+            {
+                let q = self.queue.as_ref().expect("queue must exist");
+                let mut q = q.lock().unwrap();
+                q.push(sub);
+            }
+            if let Some(batch_ready) = &self.batch_ready {
+                batch_ready.signal_producer();
+            }
+            py.allow_threads(move || comp.wait())
+        };
+
+        release_pybuffer(view);
+        res?;
+        Ok(())
+    }
+
+    /// Batched read: submit multiple reads at once via io_uring.
+    /// All reads are queued to the worker thread, which processes them
+    /// in batches to maximize throughput.
+    ///
+    /// Returns a batch_id that must be passed to wait_iouring() to wait
+    /// for completions for that batch
+    #[pyo3(signature = (offsets, buffers, total_lens))]
+    fn batched_read(
+        &self,
+        py: Python<'_>,
+        offsets: Vec<u64>,
+        buffers: Vec<Bound<'_, PyAny>>,
+        total_lens: Vec<usize>,
+    ) -> PyResult<u64> {
+        if !self.use_iouring {
+            return Err(PyRuntimeError::new_err("io_uring not enabled"));
+        }
+        if self.closed.load(Ordering::Relaxed) {
+            return Err(PyRuntimeError::new_err("device is closed"));
+        }
+
+        let n = offsets.len();
+        if n == 0 {
+            // Return a valid batch_id even for empty batches
+            return Ok(self.next_batch_id.fetch_add(1, Ordering::Relaxed));
+        }
+        if buffers.len() != n || total_lens.len() != n {
+            return Err(PyValueError::new_err("All vectors must have same length"));
+        }
+
+        // Acquire buffer views to keep them alive until wait_iouring() completes
+        let mut views = Vec::with_capacity(n);
+        let mut caps = Vec::with_capacity(n);
+        for buffer in &buffers {
+            let view = get_pybuffer(py, buffer, true)?;
+            if view.readonly != 0 {
+                for v in views {
+                    release_pybuffer(v);
+                }
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("output buffer is readonly"));
+            }
+            if view.buf.is_null() {
+                for v in views {
+                    release_pybuffer(v);
+                }
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("null buffer pointer"));
+            }
+            caps.push(view.len as usize);
+            views.push(view);
+        }
+
+        // Generate a unique batch ID for this batch
+        let batch_id = self.next_batch_id.fetch_add(1, Ordering::Relaxed);
+
+        // Initialize per-batch tracking for this batch
+        {
+            let mut batch_map = self.batch_in_flight.lock().unwrap();
+            batch_map.insert(
+                batch_id,
+                (Arc::new(AtomicU64::new(0)), Arc::new(Condvar::new())),
+            );
+        }
+
+        // Store buffer objects to keep them alive until they complete
+        {
+            let mut stored_objs = self.batched_buffer_objs.lock().unwrap();
+            let batch_buffers = stored_objs.entry(batch_id).or_default();
+            for buffer in &buffers {
+                batch_buffers.push(buffer.clone().unbind());
+            }
+        }
+
+        // Extract pointers as usize before releasing GIL (raw pointers are not Send)
+        let mut ptrs = Vec::with_capacity(n);
+        for view in &views {
+            ptrs.push(view.buf as usize);
+        }
+
+        for view in views {
+            release_pybuffer(view);
+        }
+
+        let fd = self.fd;
+        let use_odirect = self.use_odirect;
+        let alignment = self.alignment;
+        let fixed_buffers_registered = self.fixed_buffers_registered.load(Ordering::Relaxed);
+        // Clone the fixed buffer map before releasing GIL to avoid lock contention
+        let fixed_buffer_map: HashMap<usize, (u16, usize)> = if fixed_buffers_registered {
+            let map = self.fixed_buffer_map.lock().unwrap();
+            map.clone()
+        } else {
+            HashMap::new()
+        };
+        // Get NVMe data for io_uring_cmd
+        let nvme_cmd_data = self._build_nvme_cmd_data(0, 0)?;
+        let in_flight_count = Arc::clone(&self.in_flight_count);
+        let queue = Arc::clone(self.queue.as_ref().unwrap());
+        let batch_ready = Arc::clone(self.batch_ready.as_ref().unwrap());
+        let batched_completions = Arc::clone(&self.batched_completions);
+        let batch_in_flight = Arc::clone(&self.batch_in_flight);
+
+        // Additional clones for cleanup on error path
+        let batch_in_flight_cleanup = Arc::clone(&batch_in_flight);
+        let batched_completions_cleanup = Arc::clone(&batched_completions);
+        let batched_buffer_objs_cleanup = Arc::clone(&self.batched_buffer_objs);
+
+        // Release the GIL while submitting I/O operations
+        let res = py.allow_threads(move || {
+            let mut submissions: Vec<(IoSubmission, Arc<IoCompletion>)> = Vec::with_capacity(n);
+
+            // Prepare all requests, validate buffers and collect submission data.
+            for i in 0..n {
+                let total_len = total_lens[i];
+                let offset = offsets[i];
+                let cap = caps[i];
+
+                // Validate buffer capacity
+                if cap < total_len {
+                    return Err(PyValueError::new_err(format!(
+                        "output buffer too small: cap={} need={}",
+                        cap, total_len
+                    )));
+                }
+
+                if use_odirect {
+                    #[allow(clippy::manual_is_multiple_of)]
+                    if (offset as usize) % alignment != 0 {
+                        return Err(PyValueError::new_err("O_DIRECT requires aligned offset"));
+                    }
+                    #[allow(clippy::manual_is_multiple_of)]
+                    if total_len % alignment != 0 {
+                        return Err(PyValueError::new_err("O_DIRECT requires aligned total_len"));
+                    }
+                    #[allow(clippy::manual_is_multiple_of)]
+                    if ptrs[i] % alignment != 0 {
+                        return Err(PyValueError::new_err("O_DIRECT requires aligned buffers"));
+                    }
+                }
+
+                let comp = Arc::new(IoCompletion::new());
+
+                // Fixed buffers are pre-registered with io_uring, enabling true zero-copy I/O
+                let fixed_idx = fixed_buffer_map.get(&ptrs[i]).map(|(idx, _)| *idx);
+
+                let sub = IoSubmission {
+                    fd,
+                    offset,
+                    len: total_len,
+                    ptr_addr: ptrs[i],
+                    is_write: false, // read operation
+                    completion: comp.clone(),
+                    fixed_buffer_idx: fixed_idx,
+                    bounce: None,
+                    original_ptr: None,
+                    payload_len: None,
+                    batch_id,
+                    nvme_cmd_data: nvme_cmd_data.clone(),
+                };
+
+                submissions.push((sub, comp));
+            }
+
+            // Queue all submissions atomically. At this point no further errors can
+            // occur during queuing.
+            for (sub, comp) in submissions {
+                in_flight_count.fetch_add(1, Ordering::Relaxed);
+
+                // Increment per-batch in-flight count
+                {
+                    let batch_map = batch_in_flight.lock().unwrap();
+                    if let Some((batch_count, _)) = batch_map.get(&batch_id) {
+                        batch_count.fetch_add(1, Ordering::Relaxed);
+                    }
+                }
+
+                {
+                    let mut q = queue.lock().unwrap();
+                    q.push(sub);
+                }
+                batch_ready.signal_producer();
+
+                // Store completion for error checking in wait_iouring
+                {
+                    let mut completions = batched_completions.lock().unwrap();
+                    let batch_completions = completions.entry(batch_id).or_default();
+                    batch_completions.push(comp);
+                }
+            }
+            Ok::<(), PyErr>(())
+        });
+
+        // Preparation failed, clean up the tracking entries to prevent leaks
+        if let Err(e) = res {
+            {
+                let mut batch_map = batch_in_flight_cleanup.lock().unwrap();
+                batch_map.remove(&batch_id);
+            }
+            {
+                let mut stored_objs = batched_buffer_objs_cleanup.lock().unwrap();
+                stored_objs.remove(&batch_id);
+            }
+            {
+                let mut completions = batched_completions_cleanup.lock().unwrap();
+                completions.remove(&batch_id);
+            }
+            return Err(e);
+        }
+
+        Ok(batch_id)
+    }
+
+    /// Write bytes from any Python buffer object into the device.
+    /// For O_DIRECT, we use direct pointer I/O when aligned and fallback to
+    /// bounce buffering only for the unaligned/padded tail.
+    #[pyo3(signature=(offset, data, payload_len=None, total_len=None))]
+    fn pwrite_from_buffer(
+        &self,
+        py: Python<'_>,
+        offset: u64,
+        data: &Bound<'_, PyAny>,
+        payload_len: Option<usize>,
+        total_len: Option<usize>,
+    ) -> PyResult<()> {
+        if self.closed.load(Ordering::Relaxed) {
+            return Err(PyRuntimeError::new_err("device is closed"));
+        }
+        let fd = self.fd;
+
+        let view = get_pybuffer(py, data, false)?;
+        let ptr = view.buf as *const u8;
+        let buf_len = view.len as usize;
+        if ptr.is_null() {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("null buffer pointer"));
+        }
+
+        // `payload_len`: user bytes to write.
+        // `total_len`: actual I/O length. For O_DIRECT this is often aligned up.
+        // Example: payload=4100, align=4096 -> total_len=8192.
+        let payload_len = payload_len.unwrap_or(buf_len);
+        if payload_len > buf_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("payload_len exceeds buffer length"));
+        }
+        let total_len = total_len.unwrap_or(payload_len);
+        if total_len < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("total_len must be >= payload_len"));
+        }
+
+        let align = self.alignment;
+        if self.use_odirect {
+            #[allow(clippy::manual_is_multiple_of)]
+            if (offset as usize) % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned offset"));
+            }
+            #[allow(clippy::manual_is_multiple_of)]
+            if total_len % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned total_len"));
+            }
+        }
+
+        // Store pointer as integer before releasing the GIL. The closure passed
+        // to `allow_threads` must own plain data and cannot borrow `view`.
+        // We still keep `view` alive until I/O finishes, then release it below.
+        let ptr_usize = ptr as usize;
+        let res = py.allow_threads(move || {
+            let src = ptr_usize as *const u8;
+            let src_aligned = (src as usize).is_multiple_of(align);
+            if total_len == payload_len && !self.use_odirect {
+                // direct write without padding
+                return pwrite_from_ptr(fd, offset, src, payload_len);
+            }
+
+            if self.use_odirect && src_aligned {
+                if total_len == payload_len {
+                    // Fully aligned fast path: no copies.
+                    return pwrite_from_ptr(fd, offset, src, total_len);
+                }
+
+                // Hybrid path for O_DIRECT with padding:
+                // - If the Python pointer is aligned, we avoid copying the large
+                //   aligned prefix and write it directly.
+                // - Only the tail is copied into an aligned bounce buffer, then
+                //   zero-padded to satisfy O_DIRECT full-block writes.
+                //
+                // This keeps copy cost proportional to tail size, not payload size.
+                let aligned_prefix = payload_len / align * align;
+                if aligned_prefix > 0 {
+                    pwrite_from_ptr(fd, offset, src, aligned_prefix)?;
+                }
+                let tail_payload = payload_len - aligned_prefix;
+                let tail_total = total_len - aligned_prefix;
+                if tail_total > 0 {
+                    let tail_offset = offset
+                        .checked_add(aligned_prefix as u64)
+                        .ok_or_else(|| PyValueError::new_err("offset overflow"))?;
+                    let bounce = AlignedBuf::new(tail_total, align)?;
+                    unsafe {
+                        if tail_payload > 0 {
+                            libc::memcpy(
+                                bounce.as_mut_ptr() as *mut libc::c_void,
+                                src.add(aligned_prefix) as *const libc::c_void,
+                                tail_payload,
+                            );
+                        }
+                        if tail_total > tail_payload {
+                            libc::memset(
+                                bounce.as_mut_ptr().add(tail_payload) as *mut libc::c_void,
+                                0,
+                                tail_total - tail_payload,
+                            );
+                        }
+                    }
+                    pwrite_from_ptr(fd, tail_offset, bounce.as_ptr(), tail_total)?;
+                }
+                return Ok(());
+            }
+
+            // Full bounce path:
+            // - required when source pointer is not alignment-safe for O_DIRECT.
+            // - also used when non-O_DIRECT call asks for padding behavior.
+            let bounce = AlignedBuf::new(total_len, align)?;
+            unsafe {
+                libc::memcpy(
+                    bounce.as_mut_ptr() as *mut libc::c_void,
+                    src as *const libc::c_void,
+                    payload_len,
+                );
+                if total_len > payload_len {
+                    libc::memset(
+                        bounce.as_mut_ptr().add(payload_len) as *mut libc::c_void,
+                        0,
+                        total_len - payload_len,
+                    );
+                }
+            }
+            pwrite_from_ptr(fd, offset, bounce.as_ptr(), total_len)
+        });
+        // Always release the CPython buffer view once the blocking I/O closure
+        // completes. This decrements exporter-side view count correctly.
+        release_pybuffer(view);
+        res?;
+        Ok(())
+    }
+
+    /// Read exactly `payload_len` bytes into a writable Python buffer.
+    /// For O_DIRECT, use direct reads when destination is aligned and fallback
+    /// to a hybrid/read-bounce path when needed.
+    #[pyo3(signature=(offset, out, payload_len, total_len=None))]
+    fn pread_into(
+        &self,
+        py: Python<'_>,
+        offset: u64,
+        out: &Bound<'_, PyAny>,
+        payload_len: usize,
+        total_len: Option<usize>,
+    ) -> PyResult<()> {
+        if self.closed.load(Ordering::Relaxed) {
+            return Err(PyRuntimeError::new_err("device is closed"));
+        }
+        let fd = self.fd;
+        let view = get_pybuffer(py, out, true)?;
+        if view.readonly != 0 {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("output buffer is readonly"));
+        }
+        let cap = view.len as usize;
+        if cap < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err(format!(
+                "output buffer too small: cap={cap} need={payload_len}"
+            )));
+        }
+        let ptr = view.buf as *mut u8;
+        if ptr.is_null() {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("null buffer pointer"));
+        }
+
+        // `payload_len`: bytes caller wants copied into `out`.
+        // `total_len`: bytes to read from device. For O_DIRECT this is usually
+        // aligned up and can be larger than payload_len.
+        let total_len = total_len.unwrap_or(payload_len);
+        if total_len < payload_len {
+            release_pybuffer(view);
+            return Err(PyValueError::new_err("total_len must be >= payload_len"));
+        }
+
+        let align = self.alignment;
+        if self.use_odirect {
+            #[allow(clippy::manual_is_multiple_of)]
+            if (offset as usize) % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned offset"));
+            }
+            #[allow(clippy::manual_is_multiple_of)]
+            if total_len % align != 0 {
+                release_pybuffer(view);
+                return Err(PyValueError::new_err("O_DIRECT requires aligned total_len"));
+            }
+        }
+
+        // Same pattern as write path: move raw address into closure-safe value
+        // while retaining `view` lifetime until closure completion.
+        let dst_usize = ptr as usize;
+        let res = py.allow_threads(move || {
+            let dst = dst_usize as *mut u8;
+            let dst_aligned = (dst as usize).is_multiple_of(align);
+            if total_len == payload_len && !self.use_odirect {
+                return pread_into(fd, offset, dst, payload_len);
+            }
+
+            if self.use_odirect && dst_aligned {
+                if cap >= total_len {
+                    // Fully aligned fast path: no copies.
+                    return pread_into(fd, offset, dst, total_len);
+                }
+
+                // Hybrid path for O_DIRECT with smaller destination capacity:
+                // - read aligned prefix directly into destination.
+                // - read aligned tail into bounce buffer.
+                // - copy only payload tail bytes back into destination.
+                //
+                // This avoids writing beyond Python buffer capacity while still
+                // honoring O_DIRECT aligned read requirements.
+                let aligned_prefix = payload_len / align * align;
+                if aligned_prefix > 0 {
+                    pread_into(fd, offset, dst, aligned_prefix)?;
+                }
+                let tail_payload = payload_len - aligned_prefix;
+                let tail_total = total_len - aligned_prefix;
+                if tail_total > 0 {
+                    let tail_offset = offset
+                        .checked_add(aligned_prefix as u64)
+                        .ok_or_else(|| PyValueError::new_err("offset overflow"))?;
+                    let bounce = AlignedBuf::new(tail_total, align)?;
+                    pread_into(fd, tail_offset, bounce.as_mut_ptr(), tail_total)?;
+                    unsafe {
+                        if tail_payload > 0 {
+                            libc::memcpy(
+                                dst.add(aligned_prefix) as *mut libc::c_void,
+                                bounce.as_ptr() as *const libc::c_void,
+                                tail_payload,
+                            );
+                        }
+                    }
+                }
+                return Ok(());
+            }
+
+            // Full bounce read path:
+            // read aligned size into temporary aligned memory, then copy the
+            // requested payload portion to Python output buffer.
+            let bounce = AlignedBuf::new(round_up(total_len, align), align)?;
+            pread_into(fd, offset, bounce.as_mut_ptr(), total_len)?;
+            unsafe {
+                libc::memcpy(
+                    dst as *mut libc::c_void,
+                    bounce.as_ptr() as *const libc::c_void,
+                    payload_len,
+                );
+            }
+            Ok(())
+        });
+        release_pybuffer(view);
+        res?;
+        Ok(())
+    }
+
+    /// Internal function to perform the cleanup operation.
+    fn do_close(&mut self) -> Result<(), PyErr> {
+        if self.use_iouring {
+            if let Some(shutdown) = &self.shutdown {
+                shutdown.store(true, Ordering::Relaxed);
+            }
+            if let Some(batch_ready) = &self.batch_ready {
+                batch_ready.signal_producer();
+            }
+
+            let mutex = Mutex::new(());
+            let mut guard = mutex.lock().unwrap();
+            while self.in_flight_count.load(Ordering::Relaxed) > 0 {
+                let (g, _) = self
+                    .in_flight_cvar
+                    .wait_timeout(guard, Duration::from_millis(10))
+                    .unwrap();
+                guard = g;
+            }
+
+            if self.fixed_buffers_registered.load(Ordering::Relaxed) {
+                if let Some(ring) = &self.ring {
+                    let _ = match ring {
+                        IoUringWrapper::Standard(ring) => {
+                            let ring = ring.lock().unwrap();
+                            ring.submitter().unregister_buffers()
+                        }
+                        IoUringWrapper::Big(ring) => {
+                            let ring = ring.lock().unwrap();
+                            ring.submitter().unregister_buffers()
+                        }
+                    };
+                }
+                self.fixed_buffers_registered
+                    .store(false, Ordering::Relaxed);
+                self.fixed_buffer_map.lock().unwrap().clear();
+            }
+        }
+
+        if let Some(handle) = self.worker.take() {
+            let _ = handle.join();
+        }
+
+        let rc = unsafe { libc::close(self.fd) };
+        if rc != 0 {
+            return Err(os_err("close failed"));
+        }
+        self.closed.store(true, Ordering::Relaxed);
+        Ok(())
+    }
+
+    fn close(&mut self) -> PyResult<()> {
+        if !self.closed.load(Ordering::Relaxed) {
+            self.do_close()?;
+        }
+        Ok(())
+    }
+}
+
+impl Drop for RawBlockDevice {
+    fn drop(&mut self) {
+        if !self.closed.load(Ordering::Relaxed) {
+            let _ = self.do_close();
+        }
+    }
+}
+
+#[pymodule]
+fn lmcache_rust_raw_block_io(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<RawBlockDevice>()?;
+    Ok(())
+}
diff --git a/setup.py b/setup.py
new file mode 100644
index 0000000..7f0f2dd
--- /dev/null
+++ b/setup.py
@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: Apache-2.0
+"""LMCache setup script — policy-driven extension build.
+
+Uses the strategy pattern so that each platform lives in its own file
+under ``setup_extensions/build_profiles/``.  Adding a new platform requires
+zero changes to this file.
+"""
+
+# Standard
+from pathlib import Path
+import sys
+
+ROOT_DIR = Path(__file__).parent
+# Ensure the project root is importable when ``setup.py`` runs inside a
+# PEP 517 build subprocess (where CWD is not added to ``sys.path``).
+if str(ROOT_DIR) not in sys.path:
+    sys.path.insert(0, str(ROOT_DIR))
+
+# Third Party
+from setuptools import find_packages, setup  # noqa: E402
+
+# First Party
+from setup_extensions import BuildPolicy, BuildProfile  # noqa: E402
+
+
+def _read_requirements(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    reqs: list[str] = []
+    for raw in path.read_text().splitlines():
+        line = raw.strip()
+        if line and not line.startswith("#"):
+            reqs.append(line)
+    return reqs
+
+
+if __name__ == "__main__":
+    policy = BuildPolicy()
+    profile = policy.resolve_profile()
+    ext_modules, cmdclass, req_file = policy.collect_extensions(profile)
+
+    install_requires = _read_requirements(ROOT_DIR / "requirements" / "common.txt")
+    extras_require: dict[str, list[str]] = {}
+    if (
+        not BuildProfile.is_gpu_ext_disabled()
+        and req_file is not None
+        and profile is not None
+    ):
+        install_requires += _read_requirements(ROOT_DIR / "requirements" / req_file)
+        for extra_name, extra_req_file in profile.extras_requirements().items():
+            extras_require[extra_name] = _read_requirements(
+                ROOT_DIR / "requirements" / extra_req_file
+            )
+
+    setup(
+        packages=find_packages(exclude=("csrc",)),
+        ext_modules=ext_modules,
+        cmdclass=cmdclass,
+        include_package_data=True,
+        install_requires=install_requires,
+        extras_require=extras_require,
+    )
diff --git a/setup_extensions/__init__.py b/setup_extensions/__init__.py
new file mode 100644
index 0000000..ae568ed
--- /dev/null
+++ b/setup_extensions/__init__.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Extension build framework using strategy pattern.
+
+Usage from setup.py::
+
+    from setup_extensions import BuildPolicy
+    policy = BuildPolicy()
+    profile = policy.resolve_profile()
+    ext_modules, cmdclass, req_file = policy.collect_extensions(profile)
+"""
+
+# First Party
+from setup_extensions.build_profiles import BuildProfile  # noqa: F401
+from setup_extensions.common_cpp import build_common_cpp  # noqa: F401
+from setup_extensions.policy import BuildPolicy, discover_subclasses  # noqa: F401
+from setup_extensions.storage_backend_profiles import (  # noqa: F401
+    StorageBackendProfile,
+)
+
+# Re-export build-mode flags from BuildProfile for callers who prefer
+# module-level access (e.g. setup.py).
+BUILDING_SDIST = BuildProfile.is_building_sdist()
+NO_NATIVE_EXT = BuildProfile.is_native_ext_disabled()
+NO_GPU_EXT = BuildProfile.is_gpu_ext_disabled()
diff --git a/setup_extensions/build_profiles/__init__.py b/setup_extensions/build_profiles/__init__.py
new file mode 100644
index 0000000..bc1e3a3
--- /dev/null
+++ b/setup_extensions/build_profiles/__init__.py
@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base classes for the platform extension build pattern.
+
+Each hardware platform (CUDA, ROCm, SYCL, MUSA, ...) implements
+:class:`BuildProfile`.
+The :class:`BuildPolicy` orchestrates auto-detection, fallback, and building.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+    # First Party
+    from setup_extensions.common_cpp import CommonExtSpec
+
+
+class BuildProfile(ABC):
+    """Build profile for platform-specific extensions.
+
+    Subclasses must define:
+        name     – unique identifier string.
+        env_var  – ``BUILD_WITH_*`` environment variable name for explicit
+                   selection.
+
+    Subclasses must implement:
+        detect() – auto-detect if this profile's hardware/compiler is present.
+        build()  – return ``(ext_modules, cmdclass)`` for extensions.
+
+    Subclasses may override:
+        extra_cxx_flags_for(spec) – per-extension extra C++ flags for the
+                                    common extensions defined in
+                                    ``COMMON_EXTENSIONS``.
+        requirements_file()        – core requirements file name.
+        extras_requirements()      – optional-extra requirements files.
+    """
+
+    name: str = ""
+    env_var: str = ""
+
+    # ------------------------------------------------------------------
+    # Build-mode flags (owned by the profile, not the policy)
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def is_building_sdist(cls) -> bool:
+        """Return True when building a source distribution."""
+        # Standard
+        import sys
+
+        return "sdist" in sys.argv
+
+    @classmethod
+    def is_native_ext_disabled(cls) -> bool:
+        """Return True when native extensions are disabled.
+
+        Controlled by the ``NO_NATIVE_EXT`` environment variable.
+        When ``True``, all native C++ extensions are skipped — including
+        both common extensions (Redis, filesystem, storage manager)
+        and GPU backend extensions.
+
+        ``NO_CUDA_EXT`` is the legacy alias kept for backwards
+        compatibility (widely used by CI / packaging); it has always
+        controlled all native extensions, not just CUDA ones, and is
+        therefore treated as equivalent to ``NO_NATIVE_EXT``.
+        Use ``NO_GPU_EXT=1`` instead when only the GPU backend should
+        be skipped.
+        """
+        # Standard
+        import os
+        import sys
+
+        if os.environ.get("NO_CUDA_EXT", "0") == "1":
+            print(
+                "warning: NO_CUDA_EXT is deprecated; use NO_NATIVE_EXT=1 instead.",
+                file=sys.stderr,
+            )
+        return (
+            os.environ.get("NO_NATIVE_EXT", "0") == "1"
+            or os.environ.get("NO_CUDA_EXT", "0") == "1"
+        )
+
+    @classmethod
+    def is_gpu_ext_disabled(cls) -> bool:
+        """Return True when GPU extensions are disabled.
+
+        Controlled by the ``NO_GPU_EXT`` environment variable.
+        When ``True``, GPU-specific extensions (CUDA kernels, ROCm
+        hipified sources, SYCL kernels, etc.) are skipped even when
+        a platform is detected or explicitly requested.  Common C++
+        extensions are still built.
+        """
+        # Standard
+        import os
+
+        return os.environ.get("NO_GPU_EXT", "0") == "1"
+
+    # ------------------------------------------------------------------
+    # Instance methods
+    # ------------------------------------------------------------------
+
+    def is_explicitly_requested(self) -> bool:
+        """Return True when this profile was selected via env var."""
+        if not self.env_var:
+            return False
+        # Standard
+        import os
+
+        return os.environ.get(self.env_var, "0") == "1"
+
+    @abstractmethod
+    def detect(self) -> bool:
+        """Auto-detect if this profile's toolchain / hardware is available."""
+        ...
+
+    @abstractmethod
+    def build(self) -> tuple[list["Extension"], dict]:
+        """Build profile-specific extension modules.
+
+        Returns:
+            ``(ext_modules, cmdclass)`` tuple.
+        """
+        ...
+
+    def extra_cxx_flags_for(self, spec: "CommonExtSpec") -> list[str]:
+        """Extra C++ compile flags for a given common extension.
+
+        Called once per spec in :data:`COMMON_EXTENSIONS`.  Default
+        returns an empty list; subclasses override to inject per-extension
+        flags (e.g. ABI defines).
+        """
+        return []
+
+    def default_cxx_flags(self) -> list[str]:
+        """Default C++ flags to hand to downstream consumers (e.g. optional
+        L2 storage backends) that need a representative set of flags
+        compatible with this profile.
+
+        Subclasses override when their default ABI differs from the empty
+        baseline.
+        """
+        return []
+
+    def requirements_file(self) -> Optional[str]:
+        """Core requirements file name, relative to ``requirements/``.
+
+        Return ``None`` when this profile has no extra deps.
+        """
+        return None
+
+    def extras_requirements(self) -> dict[str, str]:
+        """Optional-extra requirements files, relative to ``requirements/``.
+
+        Returns:
+            Mapping from pip extra name (e.g. ``"nixl"``, installed via
+            ``pip install lmcache[nixl]``) to the requirements file that
+            lists that extra's dependencies. Empty when this profile
+            exposes no optional extras.
+        """
+        return {}
diff --git a/setup_extensions/build_profiles/cuda.py b/setup_extensions/build_profiles/cuda.py
new file mode 100644
index 0000000..cddd688
--- /dev/null
+++ b/setup_extensions/build_profiles/cuda.py
@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CUDA GPU backend profile.
+
+Builds the ``lmcache.c_ops`` extension containing memory kernels, lookup
+kernels, Cascade-AC encode/decode, position kernels, and event recorders.
+"""
+
+# Standard
+from typing import TYPE_CHECKING, Optional
+import os
+import shutil
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+# First Party
+from setup_extensions.build_profiles import BuildProfile
+
+ENABLE_CXX11_ABI = os.environ.get("ENABLE_CXX11_ABI", "1") == "1"
+
+
+class CudaProfile(BuildProfile):
+    """CUDA GPU extension build profile."""
+
+    name = "cuda"
+    env_var = "BUILD_WITH_CUDA"
+
+    def detect(self) -> bool:
+        """Detect CUDA by locating the ``nvcc`` compiler in PATH.
+
+        Build-time detection deliberately avoids ``torch.cuda.is_available``
+        because that probes the runtime driver, which is typically absent
+        on headless CI build hosts that nevertheless ship a full CUDA
+        toolchain.
+        """
+        return shutil.which("nvcc") is not None
+
+    def build(self) -> tuple[list["Extension"], dict]:
+        """Build CUDA extensions (kernels, allocator, recorders)."""
+        # Third Party
+        from torch.utils import cpp_extension
+
+        print("Building CUDA extensions")
+        flag_cxx_abi = (
+            "-D_GLIBCXX_USE_CXX11_ABI=1"
+            if ENABLE_CXX11_ABI
+            else "-D_GLIBCXX_USE_CXX11_ABI=0"
+        )
+        cuda_sources = [
+            "csrc/pybind.cpp",
+            "csrc/mem_kernels.cu",
+            "csrc/mp_mem_kernels.cu",
+            "csrc/cal_cdf.cu",
+            "csrc/ac_enc.cu",
+            "csrc/ac_dec.cu",
+            "csrc/pos_kernels.cu",
+            "csrc/mem_alloc.cpp",
+            "csrc/utils.cpp",
+            "csrc/event_recorder.cpp",
+            "csrc/completion_recorder.cpp",
+        ]
+        ext_modules = [
+            cpp_extension.CUDAExtension(
+                "lmcache.c_ops",
+                sources=cuda_sources,
+                extra_compile_args={
+                    "cxx": [flag_cxx_abi, "-std=c++17"],
+                    "nvcc": [flag_cxx_abi],
+                },
+            ),
+        ]
+        cmdclass = {"build_ext": cpp_extension.BuildExtension}
+        return ext_modules, cmdclass
+
+    def extra_cxx_flags_for(self, spec) -> list[str]:
+        """All common extensions share the same ABI flag under CUDA."""
+        return self.default_cxx_flags()
+
+    def default_cxx_flags(self) -> list[str]:
+        """ABI-aware default flags for downstream consumers."""
+        if ENABLE_CXX11_ABI:
+            return ["-D_GLIBCXX_USE_CXX11_ABI=1"]
+        return ["-D_GLIBCXX_USE_CXX11_ABI=0"]
+
+    def requirements_file(self) -> Optional[str]:
+        """Return the CUDA version-specific requirements file."""
+        return "cuda%s_core.txt" % self._cuda_major()
+
+    def extras_requirements(self) -> dict[str, str]:
+        """Return the CUDA optional extras.
+
+        Returns:
+            Mapping with the ``"nixl"`` extra (``pip install lmcache[nixl]``).
+            The extra depends on the ``nixl`` meta-package, which selects the
+            CUDA backend at runtime, so it is identical for CUDA 12 and 13.
+        """
+        return {"nixl": "nixl.txt"}
+
+    def _cuda_major(self) -> str:
+        """Resolve the target CUDA major version from ``LMCACHE_CUDA_MAJOR``.
+
+        Returns:
+            ``"12"`` or ``"13"`` (default ``"13"``, matching the PyPI build).
+
+        Raises:
+            ValueError: If ``LMCACHE_CUDA_MAJOR`` is set to anything else.
+        """
+        cuda_major = os.environ.get("LMCACHE_CUDA_MAJOR", "13")
+        if cuda_major not in ("12", "13"):
+            raise ValueError(
+                "LMCACHE_CUDA_MAJOR must be '12' or '13', got '%s'" % cuda_major
+            )
+        return cuda_major
diff --git a/setup_extensions/build_profiles/musa.py b/setup_extensions/build_profiles/musa.py
new file mode 100644
index 0000000..7206c55
--- /dev/null
+++ b/setup_extensions/build_profiles/musa.py
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+"""MUSA GPU backend profile (placeholder).
+
+MUSA fused GPU extensions are not built yet; this profile is a stub
+ready for future implementation.
+"""
+
+# Standard
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+# First Party
+from setup_extensions.build_profiles import BuildProfile
+
+
+class MusaProfile(BuildProfile):
+    """MUSA GPU extension build profile (stub)."""
+
+    name = "musa"
+    env_var = "BUILD_WITH_MUSA"
+
+    def detect(self) -> bool:
+        """MUSA detection is not implemented yet."""
+        return False
+
+    def build(self) -> tuple[list["Extension"], dict]:
+        """MUSA extensions are not built yet."""
+        print("MUSA GPU extensions are not built yet; skipping GPU extensions")
+        return [], {}
+
+    def requirements_file(self) -> Optional[str]:
+        """MUSA has no extra deps yet."""
+        return None
diff --git a/setup_extensions/build_profiles/rocm.py b/setup_extensions/build_profiles/rocm.py
new file mode 100644
index 0000000..0d682d9
--- /dev/null
+++ b/setup_extensions/build_profiles/rocm.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+"""ROCm/HIP GPU backend profile.
+
+Hipifies CUDA sources via ``torch.utils.hipify``, then builds
+``lmcache.c_ops`` with hipcc as the C++ compiler.
+"""
+
+# Standard
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+import os
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+# First Party
+from setup_extensions.build_profiles import BuildProfile
+
+ROOT_DIR = Path(__file__).parent.parent.parent
+HIPIFY_DIR = os.path.join(ROOT_DIR, "csrc/")
+HIPIFY_OUT_DIR = os.path.join(ROOT_DIR, "csrc_hip/")
+
+
+def _hipify_wrapper() -> list[str]:
+    """Run torch hipify on csrc/ and return hipified source paths."""
+    # Third Party
+    from torch.utils.hipify.hipify_python import hipify
+
+    print("Hipifying sources")
+    extra_files = [
+        os.path.abspath(os.path.join(HIPIFY_DIR, item))
+        for item in os.listdir(HIPIFY_DIR)
+        if os.path.isfile(os.path.join(HIPIFY_DIR, item))
+    ]
+    hipify_result = hipify(
+        project_directory=HIPIFY_DIR,
+        output_directory=HIPIFY_OUT_DIR,
+        header_include_dirs=[],
+        includes=[],
+        extra_files=extra_files,
+        show_detailed=True,
+        is_pytorch_extension=True,
+        hipify_extra_files_only=True,
+    )
+    hipified_sources: list[str] = []
+    for source in extra_files:
+        s_abs = os.path.abspath(source)
+        hipified_s_abs = (
+            hipify_result[s_abs].hipified_path
+            if (
+                s_abs in hipify_result
+                and hipify_result[s_abs].hipified_path is not None
+            )
+            else s_abs
+        )
+        hipified_sources.append(hipified_s_abs)
+
+    if len(hipified_sources) != len(extra_files):
+        raise RuntimeError(
+            "Hipify failed: expected %d sources, got %d"
+            % (len(extra_files), len(hipified_sources))
+        )
+    return hipified_sources
+
+
+class RocmProfile(BuildProfile):
+    """ROCm/HIP GPU extension build profile."""
+
+    name = "rocm"
+    env_var = "BUILD_WITH_HIP"
+
+    def detect(self) -> bool:
+        """Detect ROCm by checking for hipcc."""
+        # Standard
+        import shutil
+
+        return shutil.which("hipcc") is not None
+
+    def build(self) -> tuple[list["Extension"], dict]:
+        """Build ROCm/HIP extensions via hipcc."""
+        # Third Party
+        from torch.utils import cpp_extension
+
+        print("Building ROCM extensions")
+        _hipify_wrapper()
+        hip_sources = [
+            "csrc/pybind_hip.cpp",
+            "csrc/mem_kernels.hip",
+            "csrc/mp_mem_kernels.hip",
+            "csrc/cal_cdf.hip",
+            "csrc/ac_enc.hip",
+            "csrc/ac_dec.hip",
+            "csrc/pos_kernels.hip",
+            "csrc/mem_alloc_hip.cpp",
+            "csrc/utils_hip.cpp",
+            "csrc/event_recorder.cpp",
+            "csrc/completion_recorder.cpp",
+        ]
+        define_macros = [("__HIP_PLATFORM_HCC__", "1"), ("USE_ROCM", "1")]
+        ext_modules = [
+            cpp_extension.CppExtension(
+                "lmcache.c_ops",
+                sources=hip_sources,
+                extra_compile_args={
+                    "cxx": [
+                        "-O3",
+                        "-std=c++17",
+                    ],
+                },
+                include_dirs=[
+                    os.path.join(os.environ.get("ROCM_PATH", "/opt/rocm"), "include")
+                ],
+                library_dirs=[
+                    os.path.join(os.environ.get("ROCM_PATH", "/opt/rocm"), "lib")
+                ],
+                define_macros=define_macros,
+            ),
+        ]
+        cmdclass = {"build_ext": cpp_extension.BuildExtension}
+        return ext_modules, cmdclass
+
+    def requirements_file(self) -> Optional[str]:
+        """ROCm core requirements file."""
+        return "rocm_core.txt"
diff --git a/setup_extensions/build_profiles/sycl.py b/setup_extensions/build_profiles/sycl.py
new file mode 100644
index 0000000..8110c0e
--- /dev/null
+++ b/setup_extensions/build_profiles/sycl.py
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SYCL / Intel XPU GPU backend profile.
+
+Builds ``lmcache.xpu_ops`` using the DPC++ compiler (icpx).
+Requires Intel oneAPI environment to be sourced before building.
+"""
+
+# Standard
+from typing import TYPE_CHECKING, Optional
+import os
+import shutil
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+# First Party
+from setup_extensions.build_profiles import BuildProfile
+
+
+class SyclProfile(BuildProfile):
+    """SYCL / Intel XPU GPU extension build profile."""
+
+    name = "sycl"
+    env_var = "BUILD_WITH_SYCL"
+
+    def detect(self) -> bool:
+        """Detect SYCL by checking for the icpx compiler."""
+        return shutil.which("icpx") is not None
+
+    def build(self) -> tuple[list["Extension"], dict]:
+        """Build SYCL/XPU extensions via DPC++."""
+        # Third Party
+        from torch.utils import cpp_extension
+
+        print("Building SYCL/XPU extensions")
+        if shutil.which("icpx") is None:
+            raise RuntimeError("icpx not found. Please source oneAPI setvars.sh first")
+        os.environ["CXX"] = "icpx"
+        oneapi_root = os.environ.get("ONEAPI_ROOT", "/opt/intel/oneapi")
+        include_dirs = ["%s/include" % oneapi_root]
+        library_dirs = ["%s/lib" % oneapi_root]
+
+        sycl_sources = [
+            "csrc/sycl/pybind_sycl.cpp",
+            "csrc/sycl/mem_kernels_sycl.cpp",
+            "csrc/sycl/cal_cdf_sycl.cpp",
+            "csrc/sycl/pos_kernels_sycl.cpp",
+            "csrc/sycl/ac_enc_sycl.cpp",
+            "csrc/sycl/ac_dec_sycl.cpp",
+        ]
+        ext_modules = [
+            cpp_extension.SyclExtension(
+                "lmcache.xpu_ops",
+                sources=sycl_sources,
+                include_dirs=include_dirs,
+                library_dirs=library_dirs,
+                extra_compile_args={
+                    "cxx": [
+                        "-std=c++17",
+                        "-D_GLIBCXX_USE_CXX11_ABI=1",
+                        "-O3",
+                        "-fsycl",
+                        "-fno-sycl-id-queries-fit-in-int",
+                        "-ffast-math",
+                        "-funroll-loops",
+                        "-Wno-deprecated-declarations",
+                        "-Wno-nan-infinity-disabled",
+                    ],
+                },
+                extra_link_args=["-fsycl"],
+            ),
+        ]
+        cmdclass = {"build_ext": cpp_extension.BuildExtension}
+        return ext_modules, cmdclass
+
+    def extra_cxx_flags_for(self, spec) -> list[str]:
+        """SYCL uses CXX11 ABI for all common extensions except
+        ``lmcache_fs``, which omits ABI flags to preserve pre-refactor
+        behaviour."""
+        if spec.name == "lmcache_fs":
+            return []
+        return ["-D_GLIBCXX_USE_CXX11_ABI=1"]
+
+    def default_cxx_flags(self) -> list[str]:
+        """SYCL downstream consumers use the CXX11 ABI."""
+        return ["-D_GLIBCXX_USE_CXX11_ABI=1"]
+
+    def requirements_file(self) -> Optional[str]:
+        """SYCL core requirements file."""
+        return "xpu_core.txt"
diff --git a/setup_extensions/common_cpp.py b/setup_extensions/common_cpp.py
new file mode 100644
index 0000000..7c20fc5
--- /dev/null
+++ b/setup_extensions/common_cpp.py
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Common C++ extension builders shared by all backends.
+
+These extensions (storage manager, Redis, filesystem)
+are always compiled regardless of which backend is selected.
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+    # First Party
+    from setup_extensions.build_profiles import BuildProfile
+
+
+@dataclass(frozen=True)
+class CommonExtSpec:
+    """Declarative spec for a common C++ extension."""
+
+    name: str
+    sources: list[str]
+    include_dirs: list[str]
+
+
+COMMON_EXTENSIONS: list[CommonExtSpec] = [
+    CommonExtSpec(
+        name="native_storage_ops",
+        sources=[
+            "csrc/storage_manager/bitmap.cpp",
+            "csrc/storage_manager/fold.cpp",
+            "csrc/storage_manager/periodic_event_notifier.cpp",
+            "csrc/storage_manager/pybind.cpp",
+            "csrc/storage_manager/ttl_lock.cpp",
+            "csrc/storage_manager/utils.cpp",
+        ],
+        include_dirs=["csrc/storage_manager"],
+    ),
+    CommonExtSpec(
+        name="lmcache_redis",
+        sources=[
+            "csrc/storage_backends/redis/pybind.cpp",
+            "csrc/storage_backends/redis/connector.cpp",
+        ],
+        include_dirs=[
+            "csrc/storage_backends",
+            "csrc/storage_backends/redis",
+        ],
+    ),
+    CommonExtSpec(
+        name="lmcache_fs",
+        sources=[
+            "csrc/storage_backends/fs/pybind.cpp",
+            "csrc/storage_backends/fs/connector.cpp",
+        ],
+        include_dirs=[
+            "csrc/storage_backends",
+            "csrc/storage_backends/fs",
+        ],
+    ),
+]
+
+
+def build_common_cpp(
+    profile: "BuildProfile | None" = None,
+) -> tuple[list["Extension"], dict]:
+    """Build pure C++ extensions that do not depend on any backend.
+
+    Args:
+        profile: Resolved backend profile (or ``None``).  Each spec in
+            :data:`COMMON_EXTENSIONS` queries ``profile.extra_cxx_flags_for``
+            to obtain its per-extension extra flags.
+
+    Returns:
+        ``(ext_modules, cmdclass)`` tuple.
+    """
+    # Third Party
+    from torch.utils import cpp_extension
+
+    ext_modules = [
+        cpp_extension.CppExtension(
+            "lmcache." + spec.name,
+            sources=spec.sources,
+            include_dirs=spec.include_dirs,
+            extra_compile_args={
+                "cxx": (
+                    (profile.extra_cxx_flags_for(spec) if profile else [])
+                    + ["-O3", "-std=c++17"]
+                ),
+            },
+        )
+        for spec in COMMON_EXTENSIONS
+    ]
+    cmdclass = {"build_ext": cpp_extension.BuildExtension}
+    return ext_modules, cmdclass
diff --git a/setup_extensions/policy.py b/setup_extensions/policy.py
new file mode 100644
index 0000000..ab08b56
--- /dev/null
+++ b/setup_extensions/policy.py
@@ -0,0 +1,249 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Policy-driven extension build orchestrator.
+
+:class:`BuildPolicy` auto-discovers available platform profiles,
+selects the best one via explicit env var or auto-detection with fallback,
+and drives the common C++ + platform extension build pipeline.
+"""
+
+# Standard
+from types import ModuleType
+from typing import Callable, Iterator, Optional, TypeVar, Union
+import importlib
+import inspect
+import pkgutil
+import sys
+
+# First Party
+from setup_extensions.build_profiles import BuildProfile
+from setup_extensions.common_cpp import build_common_cpp
+from setup_extensions.storage_backend_profiles import (  # noqa: E402
+    StorageBackendProfile,
+)
+
+# ---------------------------------------------------------------------------
+# Generic subclass discovery (filesystem-based, from _discovery.py)
+# ---------------------------------------------------------------------------
+
+T = TypeVar("T")
+
+
+def discover_subclasses(
+    package: Union[ModuleType, str],
+    base_class: type[T],
+    *,
+    on_import_error: Optional[Callable[[str, Exception], None]] = None,
+) -> Iterator[type[T]]:
+    """Yield concrete subclasses of *base_class* found in direct
+    submodules of *package*.
+
+    Args:
+        package: The package to scan (module or dotted name).
+        base_class: The base class whose concrete subclasses to collect.
+        on_import_error: Optional callback ``(full_module_name, exc)``
+            invoked on import failures.  When omitted the error is
+            printed to stderr and discovery continues.
+    """
+    if isinstance(package, str):
+        package = importlib.import_module(package)
+    pkg_path = getattr(package, "__path__", None)
+    if pkg_path is None:
+        raise TypeError(
+            "discover_subclasses requires a package (with __path__), "
+            "got %r" % (package,)
+        )
+
+    seen: set[type] = set()
+    for _, short_name, _ in pkgutil.iter_modules(pkg_path):
+        full_name = "%s.%s" % (package.__name__, short_name)
+        try:
+            module = importlib.import_module(full_name)
+        except Exception as exc:
+            if on_import_error is not None:
+                on_import_error(full_name, exc)
+            else:
+                print(
+                    "warning: failed to import %s: %s" % (full_name, exc),
+                    file=sys.stderr,
+                )
+            continue
+
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if not issubclass(obj, base_class) or obj is base_class:
+                continue
+            if inspect.isabstract(obj):
+                continue
+            if obj in seen:
+                continue
+            seen.add(obj)
+            yield obj
+
+
+# ---------------------------------------------------------------------------
+# Platform auto-discovery (filesystem-based, no hard-coded module list)
+# ---------------------------------------------------------------------------
+
+
+def _discover_platforms() -> list[BuildProfile]:
+    """Auto-discover all platform build profiles.
+
+    Walks ``setup_extensions.build_profiles`` via ``discover_subclasses``,
+    which uses ``pkgutil.iter_modules`` to find submodules at the
+    filesystem level.  Adding a new ``.py`` file under that package
+    with a concrete ``BuildProfile`` subclass is all that is needed —
+    no module list to maintain.
+    """
+    platforms: list[BuildProfile] = []
+    for cls in discover_subclasses(
+        "setup_extensions.build_profiles",
+        BuildProfile,  # type: ignore[type-abstract]
+    ):
+        platforms.append(cls())
+    return platforms
+
+
+def _discover_storage_backends() -> list[StorageBackendProfile]:
+    """Auto-discover all optional L2 storage backend build profiles.
+
+    Walks ``setup_extensions.storage_backend_profiles`` via
+    ``discover_subclasses``. Adding a new ``.py`` file under that
+    package with a concrete ``StorageBackendProfile`` subclass is all
+    that is needed.
+    """
+    backends: list[StorageBackendProfile] = []
+    for cls in discover_subclasses(
+        "setup_extensions.storage_backend_profiles",
+        StorageBackendProfile,  # type: ignore[type-abstract]
+    ):
+        backends.append(cls())
+    return backends
+
+
+# ---------------------------------------------------------------------------
+# Policy engine
+# ---------------------------------------------------------------------------
+
+
+class BuildPolicy:
+    """Selects and builds extensions using platform-aware build profiles.
+
+    Resolution order:
+        1. If an explicit ``BUILD_WITH_*`` env var is set, use that profile
+           unconditionally (no fallback). A warning is emitted when its
+           toolchain cannot be auto-detected, but the build proceeds so
+           that the underlying compiler produces the authoritative error.
+        2. Otherwise auto-detect with fallback through candidates.
+        3. If nothing is available, warn and continue without extensions.
+    """
+
+    def __init__(self) -> None:
+        self._platforms = _discover_platforms()
+
+    def resolve_profile(self) -> Optional[BuildProfile]:
+        """Resolve the active build profile.
+
+        Returns ``None`` when building sdist, native extensions are
+        disabled, GPU extensions are disabled, or no profile was
+        detected.
+        """
+        if (
+            BuildProfile.is_building_sdist()
+            or BuildProfile.is_native_ext_disabled()
+            or BuildProfile.is_gpu_ext_disabled()
+        ):
+            return None
+
+        # ---------------------------------------------------------------
+        # Phase 1: explicit env var selection
+        # ---------------------------------------------------------------
+        explicitly_requested = [
+            s for s in self._platforms if s.is_explicitly_requested()
+        ]
+        if len(explicitly_requested) > 1:
+            names = ", ".join(s.name for s in explicitly_requested)
+            raise RuntimeError("Multiple profiles explicitly requested: %s" % names)
+        if explicitly_requested:
+            profile = explicitly_requested[0]
+            print("Using explicitly requested profile: %s" % profile.name)
+            if not profile.detect():
+                print(
+                    "warning: profile '%s' was explicitly requested but its "
+                    "toolchain was not auto-detected; proceeding anyway" % profile.name,
+                    file=sys.stderr,
+                )
+            return profile
+
+        # ---------------------------------------------------------------
+        # Phase 2: auto-detect with fallback
+        # ---------------------------------------------------------------
+        print("No profile explicitly selected, auto-detecting...")
+        for profile in self._platforms:
+            if profile.detect():
+                print("Auto-detected profile: %s" % profile.name)
+                return profile
+
+        # ---------------------------------------------------------------
+        # Phase 3: nothing found
+        # ---------------------------------------------------------------
+        print(
+            "warning: no profile detected, building without extensions",
+            file=sys.stderr,
+        )
+        return None
+
+    @staticmethod
+    def collect_extensions(
+        profile: Optional[BuildProfile],
+    ) -> tuple[list, dict, Optional[str]]:
+        """Build all extensions and return requirements file name.
+
+        Args:
+            profile: Resolved build profile, or ``None``.
+
+        Returns:
+            ``(ext_modules, cmdclass, requirements_file)`` tuple.
+        """
+        if BuildProfile.is_building_sdist():
+            print("Not building extensions for sdist")
+            return [], {}, None
+
+        if BuildProfile.is_native_ext_disabled():
+            return [], {}, None
+
+        # ---- build common C++ extensions ----
+        ext_modules, cmdclass = build_common_cpp(profile)
+
+        # ---- build profile-specific extensions ----
+        if profile and not BuildProfile.is_gpu_ext_disabled():
+            em, cc = profile.build()
+            ext_modules.extend(em)
+            cmdclass.update(cc)
+
+        # ---- build optional storage backends ----
+        storage_flags = profile.default_cxx_flags() if profile else []
+        ext_modules.extend(BuildPolicy.collect_storage_backends(storage_flags))
+
+        # ---- requirements ----
+        req_file = profile.requirements_file() if profile else None
+
+        return ext_modules, cmdclass, req_file
+
+    @staticmethod
+    def collect_storage_backends(
+        extra_cxx_flags: list[str],
+    ) -> list:
+        """Discover and build optional L2 storage backend extensions.
+
+        Each storage backend can be enabled via its ``BUILD_WITH_*``
+        env var or auto-detected through its SDK presence.
+        """
+        storage_backends = _discover_storage_backends()
+        ext_modules = []
+        for s in storage_backends:
+            if s.is_explicitly_requested():
+                print("Using explicitly requested storage backend: %s" % s.name)
+                ext_modules.extend(s.build(extra_cxx_flags))
+            elif s.detect():
+                print("Auto-detected storage backend: %s" % s.name)
+                ext_modules.extend(s.build(extra_cxx_flags))
+        return ext_modules
diff --git a/setup_extensions/storage_backend_profiles/__init__.py b/setup_extensions/storage_backend_profiles/__init__.py
new file mode 100644
index 0000000..f5edf2a
--- /dev/null
+++ b/setup_extensions/storage_backend_profiles/__init__.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Base classes for the optional L2 storage backend build profile pattern.
+
+Each optional storage backend (Mooncake, ...) implements
+:class:`StorageBackendProfile`.  Unlike GPU backends, multiple storage
+backends can be selected simultaneously.
+"""
+
+# Standard
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+
+class StorageBackendProfile(ABC):
+    """Build profile for an optional L2 storage backend extension.
+
+    Subclasses must define:
+        name     – unique identifier string.
+        env_var  – ``BUILD_WITH_*`` environment variable name for explicit
+                   selection.
+
+    Subclasses must implement:
+        detect() – auto-detect if this backend's SDK / toolchain is present.
+        build()  – return ``list[Extension]`` for the backend extension.
+    """
+
+    name: str = ""
+    env_var: str = ""
+
+    def is_explicitly_requested(self) -> bool:
+        """Return True when this backend was selected via env var."""
+        if not self.env_var:
+            return False
+        # Standard
+        import os
+
+        return os.environ.get(self.env_var, "0") == "1"
+
+    @abstractmethod
+    def detect(self) -> bool:
+        """Auto-detect if this backend's SDK / toolchain is available."""
+        ...
+
+    @abstractmethod
+    def build(self, extra_cxx_flags: list[str]) -> list["Extension"]:
+        """Build the storage backend extension module.
+
+        Args:
+            extra_cxx_flags: Additional C++ compiler flags from the
+                selected GPU backend profile.
+
+        Returns:
+            List of ``Extension`` objects for this backend.
+        """
+        ...
diff --git a/setup_extensions/storage_backend_profiles/aerospike.py b/setup_extensions/storage_backend_profiles/aerospike.py
new file mode 100644
index 0000000..63dceca
--- /dev/null
+++ b/setup_extensions/storage_backend_profiles/aerospike.py
@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Aerospike L2 storage backend profile.
+
+Builds the ``lmcache.lmcache_aerospike`` extension against a libaerospike
+development install.  Enabled via ``BUILD_WITH_AEROSPIKE=1`` (or the legacy
+``BUILD_AEROSPIKE=1``), or auto-detected through ``AEROSPIKE_INCLUDE_DIR``.
+"""
+
+# Standard
+from pathlib import Path
+from typing import TYPE_CHECKING
+import os
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+# First Party
+from setup_extensions.storage_backend_profiles import StorageBackendProfile
+
+# Repo root: setup_extensions/storage_backend_profiles/aerospike.py -> parents[2]
+ROOT_DIR = Path(__file__).resolve().parents[2]
+
+
+class AerospikeStorageBackend(StorageBackendProfile):
+    """Optional native Aerospike L2 storage backend."""
+
+    name = "aerospike"
+    env_var = "BUILD_WITH_AEROSPIKE"
+
+    def detect(self) -> bool:
+        """Detect Aerospike via the legacy ``BUILD_AEROSPIKE`` flag or by the
+        presence of ``AEROSPIKE_INCLUDE_DIR``."""
+        as_env = os.environ.get("BUILD_AEROSPIKE")
+        if as_env is not None:
+            return as_env == "1"
+        return os.environ.get("AEROSPIKE_INCLUDE_DIR", "") != ""
+
+    def build(self, extra_cxx_flags: list[str]) -> list["Extension"]:
+        """Build the Aerospike CppExtension."""
+        # Standard
+        import ctypes.util
+
+        # Third Party
+        from torch.utils import cpp_extension
+
+        as_include = os.environ.get("AEROSPIKE_INCLUDE_DIR", "")
+        as_lib = os.environ.get("AEROSPIKE_LIBRARY_DIR", "")
+        deps_yaml_lib = (
+            ROOT_DIR / ".deps" / "libyaml-install" / "usr" / "lib" / "x86_64-linux-gnu"
+        )
+        include_dirs = [
+            "csrc/storage_backends",
+            "csrc/storage_backends/aerospike",
+        ]
+        if as_include:
+            include_dirs.extend(as_include.split(";"))
+        library_dirs: list[str] = []
+        if as_lib:
+            library_dirs.extend(as_lib.split(";"))
+        extra_objects: list[str] = []
+        yaml_shared = deps_yaml_lib / "libyaml.so"
+        yaml_static = deps_yaml_lib / "libyaml.a"
+        if yaml_shared.exists() or yaml_static.exists():
+            library_dirs.append(str(deps_yaml_lib))
+
+        libraries = ["aerospike"]
+        if yaml_shared.exists() or ctypes.util.find_library("yaml"):
+            libraries.append("yaml")
+        elif yaml_static.exists():
+            extra_objects.append(str(yaml_static))
+        libraries.extend(["ssl", "crypto", "pthread", "z", "rt"])
+        if os.environ.get("AEROSPIKE_EVENT_LIB", "libuv") == "libuv":
+            libraries.append("uv")
+
+        runtime_library_dirs = list(library_dirs)
+
+        return [
+            cpp_extension.CppExtension(
+                "lmcache.lmcache_aerospike",
+                sources=[
+                    "csrc/storage_backends/aerospike/pybind.cpp",
+                    "csrc/storage_backends/aerospike/connector.cpp",
+                ],
+                include_dirs=include_dirs,
+                library_dirs=library_dirs,
+                libraries=libraries,
+                extra_objects=extra_objects,
+                runtime_library_dirs=runtime_library_dirs,
+                extra_compile_args={
+                    "cxx": extra_cxx_flags + ["-O3", "-std=c++17"],
+                },
+                extra_link_args=["-Wl,--no-as-needed"],
+            ),
+        ]
diff --git a/setup_extensions/storage_backend_profiles/mooncake.py b/setup_extensions/storage_backend_profiles/mooncake.py
new file mode 100644
index 0000000..6875cfa
--- /dev/null
+++ b/setup_extensions/storage_backend_profiles/mooncake.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Mooncake L2 storage backend profile.
+
+Builds the ``lmcache.lmcache_mooncake`` extension when the Mooncake SDK
+is available.  Enabled via ``BUILD_WITH_MOONCAKE=1`` or auto-detected
+through ``MOONCAKE_INCLUDE_DIR`` / ``BUILD_MOONCAKE`` env vars.
+"""
+
+# Standard
+from typing import TYPE_CHECKING
+import os
+
+if TYPE_CHECKING:
+    # Third Party
+    from setuptools.extension import Extension
+
+# First Party
+from setup_extensions.storage_backend_profiles import StorageBackendProfile
+
+
+class MooncakeStorageBackend(StorageBackendProfile):
+    """Mooncake distributed KV-cache storage backend."""
+
+    name = "mooncake"
+    env_var = "BUILD_WITH_MOONCAKE"
+
+    def detect(self) -> bool:
+        """Detect Mooncake SDK via legacy env vars."""
+        mc_env = os.environ.get("BUILD_MOONCAKE")
+        if mc_env is not None:
+            return mc_env == "1"
+        return os.environ.get("MOONCAKE_INCLUDE_DIR", "") != ""
+
+    def build(self, extra_cxx_flags: list[str]) -> list["Extension"]:
+        """Build the mooncake CppExtension."""
+        # Third Party
+        from torch.utils import cpp_extension
+
+        mc_include = os.environ.get("MOONCAKE_INCLUDE_DIR", "")
+        mc_lib = os.environ.get("MOONCAKE_LIB_DIR", "")
+        mc_include_dirs = [
+            "csrc/storage_backends",
+            "csrc/storage_backends/mooncake",
+        ]
+        if mc_include:
+            mc_include_dirs.extend(mc_include.split(";"))
+        mc_library_dirs: list[str] = []
+        if mc_lib:
+            mc_library_dirs.extend(mc_lib.split(";"))
+        return [
+            cpp_extension.CppExtension(
+                "lmcache.lmcache_mooncake",
+                sources=[
+                    "csrc/storage_backends/mooncake/pybind.cpp",
+                    "csrc/storage_backends/mooncake/connector.cpp",
+                ],
+                include_dirs=mc_include_dirs,
+                library_dirs=mc_library_dirs,
+                libraries=["mooncake_store"],
+                runtime_library_dirs=mc_library_dirs,
+                extra_compile_args={
+                    "cxx": extra_cxx_flags + ["-O3", "-std=c++20", "-DYLT_ENABLE_IBV"],
+                },
+            ),
+        ]
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/aerospike_ce.conf.template b/tests/aerospike_ce.conf.template
new file mode 100644
index 0000000..8fc2e12
--- /dev/null
+++ b/tests/aerospike_ce.conf.template
@@ -0,0 +1,53 @@
+# Aerospike CE template for CI/local integration tests.
+# __ACCESS_PORT__ is replaced by CI workflow / docker run
+service {
+    proto-fd-max 15000
+    cluster-name lmcache-test
+}
+
+logging {
+    console {
+        context any info
+    }
+}
+
+network {
+    service {
+        address any
+        port 3000
+        access-address 127.0.0.1
+        access-port __ACCESS_PORT__
+    }
+    heartbeat {
+        mode mesh
+        port 3002
+        interval 150
+        timeout 10
+    }
+    fabric {
+        port 3001
+    }
+    info {
+        port 3003
+    }
+}
+
+namespace lmcache {
+    replication-factor 1
+    nsup-period 120
+    default-ttl 0
+    max-record-size 1048576
+    storage-engine memory {
+        data-size 2G
+    }
+}
+
+namespace lmcache_no_nsup {
+    replication-factor 1
+    nsup-period 0
+    default-ttl 0
+    max-record-size 1048576
+    storage-engine memory {
+        data-size 512M
+    }
+}
diff --git a/tests/benchmarks/test_benchmark.py b/tests/benchmarks/test_benchmark.py
new file mode 100644
index 0000000..1fc27d6
--- /dev/null
+++ b/tests/benchmarks/test_benchmark.py
@@ -0,0 +1,459 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from functools import partial
+import os
+import random
+import shlex
+import subprocess
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from tests.v1.utils import (
+    create_gpu_connector,
+    dumb_metadata,
+    generate_kv_cache_paged_list_tensors,
+    generate_tokens,
+)
+
+# Optional override for tempfile root; see tests/v1/test_cache_engine.py
+# for rationale.
+_TEST_TMPDIR = os.environ.get("LMCACHE_TEST_TMPDIR") or None
+
+
+# helper functions
+def generate_random_slot_mapping(num_blocks, block_size, num_tokens, device):
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    return torch.tensor(slot_mapping, device=device)
+
+
+def get_expected_count(token_len, save_unfull_chunk, chunk_size):
+    """Calculate expected token count based on save_unfull_chunk setting.
+
+    Args:
+        token_len: Total token length
+        save_unfull_chunk: Whether to save partial chunks
+        chunk_size: Chunk size for alignment
+
+    Returns:
+        If save_unfull_chunk is True, returns token_len as-is.
+        Otherwise, returns chunk-aligned count (rounded down).
+    """
+    if save_unfull_chunk:
+        return token_len
+    return (token_len // chunk_size) * chunk_size
+
+
+@pytest.fixture
+def create_config():
+    """
+    backend can be:
+    - cpu
+    - disk
+    - fsconnector
+    """
+
+    def make_config(backend, size, save_unfull_chunk=True, **kwargs):
+        match backend:
+            case "cpu":
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=True,
+                    max_local_cpu_size=size,
+                    save_unfull_chunk=save_unfull_chunk,
+                    extra_config={"force_store_wait": False},
+                )
+            case "disk":
+                assert "path" in kwargs, "'path' is missing for disk backend"
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=False,
+                    max_local_cpu_size=size,
+                    local_disk=kwargs["path"],
+                    max_local_disk_size=size,
+                    save_unfull_chunk=save_unfull_chunk,
+                    extra_config={"force_store_wait": False},
+                )
+            case "fsconnector":
+                assert "path" in kwargs, "'path' is missing for fsconnector"
+                p = kwargs["path"]
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=False,
+                    max_local_cpu_size=size,
+                    remote_url=f"fs://host:0/{p}/",
+                    remote_serde="naive",
+                    save_unfull_chunk=save_unfull_chunk,
+                    extra_config={"force_store_wait": False},
+                )
+            case _:
+                print(f"Error: unknown backend: {backend}")
+                print("Supported backends: 'cpu', 'disk', and 'fsconnector'")
+                raise ValueError(f"Unknown backend: {backend}")
+
+    with tempfile.TemporaryDirectory(
+        dir=_TEST_TMPDIR, ignore_cleanup_errors=True
+    ) as temp_dir:
+        print("Temp dir is:", temp_dir)
+        yield partial(make_config, path=temp_dir)
+
+
+# test store 10GB data (1GB * 10)
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="store")
+@pytest.mark.parametrize("backend", ["cpu", "disk", "fsconnector"])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_store_1GB(
+    benchmark,
+    backend,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    """
+    In this test, it will run engine.store to store 10GB data in total.
+    The configs are carefully tuned to have:
+    - Each request has 2K tokens and 0.25GB KV cache
+    - There will be 40 store requests (storing 10GB data) in total.
+    - The store requests are split into 10 rounds, where each round has
+    1GB data.
+    - The benchmark tool will measure the time for each round (time to
+    store 1GB)
+
+    When creating the LMCache engine, it will first create a 1.5GB buffer, so
+    there will be eviction starting from the second round.
+
+    At the end of each round, we will run `engine.lookup` to ensure that all
+    the data are successfully stored into the LMCache engine. The test will
+    measure the time for each round and calculate the average time across
+    the rounds.
+
+    pytest-benchmark will report the average time. To calculate the store
+    throughput, we can use 1GB / average_round_time.
+    """
+    # model-related metadatas
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    # lmcache and vllm configs
+    device = "cuda"
+    num_tokens = 2000
+
+    num_blocks = 1000
+    block_size = 16
+
+    chunk_size = 256
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+
+    # Test configs
+    # - single request has 1.25GB KV, 8 requests has 10GB
+    # so we want to do 10 rounds
+    num_requests = 4
+    num_repeats = 10
+
+    # Initialize related modules
+    connector = create_gpu_connector(num_heads * head_dim, num_layers)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    cache_size = 1.5  # Allocate 15 GB KV cache buffer
+    cfg = create_config(backend, cache_size, save_unfull_chunk=save_unfull_chunk)
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    # Run benchmark
+    def run_func(tokens, slot_mappings):
+        for t, s in zip(tokens, slot_mappings, strict=False):
+            engine.store(t, kvcaches=kv_cache, slot_mapping=s)
+
+        # Wait for all tokens are being stored
+        timeout = 60
+        start = time.time()
+        while time.time() - start < timeout:
+            ready = all(
+                [
+                    engine.lookup(t)
+                    == get_expected_count(len(t), save_unfull_chunk, chunk_size)
+                    for t in tokens
+                ]
+            )
+            if ready:
+                return
+            else:
+                time.sleep(0.05)
+        raise TimeoutError(f"Store operation haven't finished in {timeout} seconds")
+
+    def setup():
+        list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+
+        list_slot_mappings = [
+            generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+            for _ in range(num_requests)
+        ]
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+        return (list_tokens, list_slot_mappings), {}
+
+    benchmark.pedantic(run_func, setup=setup, rounds=num_repeats, iterations=1)
+
+
+# Test retrieve 10data (10 rounds, each round 1GB, 100% hit)
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="retrieve")
+@pytest.mark.parametrize("backend", ["cpu", "disk", "fsconnector"])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_retrieve_1GB_allhit(
+    benchmark,
+    backend,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    """
+    In this test, it will run engine.retrieve to retrieve 10GB data in total.
+    The configs are carefully tuned to have:
+    - Each request has 2K tokens and 0.25GB KV cache
+    - There will be 40 retrieve requests (retrieving 10GB data) in total.
+    - The retrieve requests are split into 10 rounds, where each round has
+    1GB data.
+    - The benchmark tool will measure the time for each round (time to
+    retrieve 1GB)
+
+    When creating the LMCache engine, it will first create a 1.5GB buffer, and
+    then store 4 requests (1GB) into the engine.
+    After that, there will be 10 rounds of retrieve, where each round queries
+    the same set of requests (but shuffled) with a 100% hit rate.
+
+    The test will measure the time for each round and calculate the average
+    time across the rounds.
+
+    pytest-benchmark will report the average time. To calculate the retrieve
+    throughput, we can use 1GB / average_round_time.
+    """
+    # model-related metadatas
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    # lmcache and vllm configs
+    device = "cuda"
+    num_tokens = 2000
+
+    num_blocks = 1000
+    block_size = 16
+
+    chunk_size = 256
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+
+    # Test configs
+    # - Single request has 1.25 GB KV, 8 requests will use 10GB,
+    # so num repeats should be 10 to achieve 100 GB access
+    num_requests = 4
+    num_repeats = 10
+
+    # Initialize related modules
+    connector = create_gpu_connector(num_heads * head_dim, num_layers)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    cache_size = 1.5  # 2 GB KV cache buffer
+    cfg = create_config(backend, cache_size, save_unfull_chunk=save_unfull_chunk)
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    for t, s in zip(list_tokens, list_slot_mappings, strict=False):
+        engine.store(t, kvcaches=kv_cache, slot_mapping=s)
+
+    # Wait for kv cache to be ready
+    timeout = 60
+    start = time.time()
+    ready = False
+    while time.time() - start < timeout:
+        ready = all(
+            [
+                engine.lookup(t)
+                == get_expected_count(len(t), save_unfull_chunk, chunk_size)
+                for t in list_tokens
+            ]
+        )
+        if ready:
+            break
+        else:
+            time.sleep(0.1)
+    assert ready, "Store is not finished in 60 seconds"
+
+    # Run benchmark
+    def setup():
+        indexes = list(range(len(list_tokens)))
+        random.shuffle(indexes)
+        return (
+            [list_tokens[i] for i in indexes],
+            [list_slot_mappings[i] for i in indexes],
+        ), {}
+
+    def run_func(tokens, slot_mappings):
+        for t, s in zip(tokens, slot_mappings, strict=False):
+            engine.retrieve(t, kvcaches=kv_cache, slot_mapping=s)
+
+    benchmark.pedantic(run_func, setup=setup, rounds=num_repeats, iterations=1)
+
+
+# Test lookup 2K * 10 requests, 100% hit
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="lookup")
+@pytest.mark.parametrize("backend", ["cpu", "disk", "fsconnector"])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_lookup_20K_tokens(
+    benchmark,
+    backend,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    """
+    In this test, it will run engine.lookup to lookup 200K tokens in total.
+    The configs are carefully tuned to have:
+    - Each request has 2K tokens and 0.25GB KV cache
+    - There will be 100 lookup requests split into 10 rounds.
+    - Each round will shuffle the requests.
+
+    When creating the LMCache engine, it will first create a 5GB buffer, and
+    then store 10 requests (3GB) into the engine.
+    the same set of requests (but shuffled) with a 100% hit rate.
+
+    The test will measure the time for each round and calculate the average
+    time across the rounds.
+
+    pytest-benchmark will report the average time. To calculate the lookup
+    throughput, we can use 100K tokens / average_round_time.
+    """
+    # model-related metadatas
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    # lmcache and vllm configs
+    device = "cuda"
+    num_tokens = 2000
+
+    num_blocks = 1000
+    block_size = 16
+
+    chunk_size = 256
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+
+    # Test configs
+    num_requests = 10
+    num_repeats = 10
+
+    # Initialize related modules
+    connector = create_gpu_connector(num_heads * head_dim, num_layers)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    # TODO: Rewrite the config generation to another helper function
+    cache_size = 3  # 15 GB KV cache buffer
+    cfg = create_config(backend, cache_size, save_unfull_chunk=save_unfull_chunk)
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    for t, s in zip(list_tokens, list_slot_mappings, strict=False):
+        engine.store(t, kvcaches=kv_cache, slot_mapping=s)
+
+    # Make sure all the requests are stored
+    timeout = 60
+    start = time.time()
+    ready = False
+    while time.time() - start < timeout:
+        ready = all(
+            [
+                engine.lookup(t)
+                == get_expected_count(len(t), save_unfull_chunk, chunk_size)
+                for t in list_tokens
+            ]
+        )
+        if ready:
+            break
+        else:
+            time.sleep(0.1)
+    assert ready, "Store is not finished in 60 seconds"
+
+    # Run benchmark
+    def setup():
+        indexes = list(range(len(list_tokens)))
+        random.shuffle(indexes)
+        return (
+            [list_tokens[i] for i in indexes],
+            [list_slot_mappings[i] for i in indexes],
+        ), {}
+
+    def run_func(tokens, slot_mappings):
+        for t, s in zip(tokens, slot_mappings, strict=False):
+            assert engine.lookup(t) == get_expected_count(
+                len(t), save_unfull_chunk, chunk_size
+            )
+
+    benchmark.pedantic(run_func, setup=setup, rounds=num_repeats, iterations=1)
diff --git a/tests/benchmarks/test_cachegen.py b/tests/benchmarks/test_cachegen.py
new file mode 100644
index 0000000..242c14d
--- /dev/null
+++ b/tests/benchmarks/test_cachegen.py
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+"""End-to-end benchmark: CacheGen encode/decode on GPU (CUDA or XPU).
+
+Measures wall-clock to serialize and deserialize a synthetic KV-cache
+blob, and records the compression ratio against the uncompressed baseline.
+
+Run with: ``pytest tests/benchmarks/test_cachegen.py --benchmark-only``
+"""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.storage_backend.serde.cachegen_decoder import CacheGenDeserializer
+from lmcache.storage_backend.serde.cachegen_encoder import CacheGenSerializer
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+
+# CacheGen has hand-written CUDA and SYCL kernels only; gate the test on
+# those backends explicitly (whitelist), so HPU / CPU-only CI / future
+# backends without a CacheGen kernel are skipped automatically.
+# torch_device_type is set to "cuda"/"xpu" only after is_available() passes
+# in lmcache.__init__, so no extra availability check is needed here.
+pytestmark = pytest.mark.skipif(
+    torch_device_type not in ("cuda", "xpu"),
+    reason="CacheGen kernels only exist for CUDA and XPU",
+)
+
+
+def _generate_kv(num_tokens, device):
+    num_layers, num_heads, head_size = 32, 8, 128
+    shape = [num_tokens, num_heads, head_size]
+    pairs = []
+    for _ in range(num_layers):
+        k = torch.rand(shape, dtype=torch.bfloat16, device=device)
+        v = torch.rand(shape, dtype=torch.bfloat16, device=device)
+        pairs.append((k, v))
+    return torch.stack([torch.stack(p, dim=0) for p in pairs], dim=0)
+
+
+def _make_serde(chunk_size):
+    config = LMCacheEngineConfig.from_defaults(chunk_size=chunk_size)
+    metadata = LMCacheMetadata(
+        model_name="mistralai/Mistral-7B-Instruct-v0.2",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=None,
+    )
+    return (
+        CacheGenSerializer(config, metadata),
+        CacheGenDeserializer(config, metadata, torch.bfloat16),
+    )
+
+
+@pytest.mark.benchmark(group="cachegen_encode")
+@pytest.mark.parametrize("chunk_size", [64, 128, 256, 768])
+def test_cachegen_encoder_bench(benchmark, chunk_size):
+    serializer, _ = _make_serde(chunk_size)
+    kv = _generate_kv(chunk_size, torch_device_type)
+
+    def run():
+        return serializer.to_bytes(kv)
+
+    out = benchmark(run)
+    raw_bytes = kv.element_size() * kv.numel()
+    print(
+        f"\n[chunk={chunk_size}] raw={raw_bytes} compressed={len(out)} "
+        f"ratio={raw_bytes / max(len(out), 1):.2f}x"
+    )
+
+
+@pytest.mark.benchmark(group="cachegen_decode")
+@pytest.mark.parametrize("chunk_size", [64, 128, 256, 768])
+def test_cachegen_decoder_bench(benchmark, chunk_size):
+    serializer, deserializer = _make_serde(chunk_size)
+    kv = _generate_kv(chunk_size, torch_device_type)
+    payload = serializer.to_bytes(kv)
+
+    benchmark(deserializer.from_bytes, payload)
diff --git a/tests/benchmarks/test_musa_inprocess_benchmark.py b/tests/benchmarks/test_musa_inprocess_benchmark.py
new file mode 100644
index 0000000..15e979c
--- /dev/null
+++ b/tests/benchmarks/test_musa_inprocess_benchmark.py
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from benchmarks.musa.bench_inprocess_transfer import (
+    BenchmarkResult,
+    compare_results,
+)
+
+
+def test_compare_results_requires_native_speedup() -> None:
+    """A fast native result passes the Stage2 speedup gate."""
+    torch_result = BenchmarkResult(name="torch", seconds_per_iter=1.0)
+    native_result = BenchmarkResult(name="native", seconds_per_iter=0.7)
+
+    passed, summary = compare_results(
+        torch_result,
+        native_result,
+        min_speedup=1.2,
+    )
+
+    assert passed is True
+    assert "speedup=1.429x" in summary
+
+
+def test_compare_results_fails_when_native_is_slower() -> None:
+    """A slower native result fails with the required speedup in the summary."""
+    torch_result = BenchmarkResult(name="torch", seconds_per_iter=1.0)
+    native_result = BenchmarkResult(name="native", seconds_per_iter=1.1)
+
+    passed, summary = compare_results(
+        torch_result,
+        native_result,
+        min_speedup=1.2,
+    )
+
+    assert passed is False
+    assert "required>=1.200x" in summary
diff --git a/tests/benchmarks/test_xpu_connector_benchmark.py b/tests/benchmarks/test_xpu_connector_benchmark.py
new file mode 100644
index 0000000..2f3b29b
--- /dev/null
+++ b/tests/benchmarks/test_xpu_connector_benchmark.py
@@ -0,0 +1,477 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from functools import partial
+import os
+import random
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.xpu_connectors import VLLMPagedMemXPUConnectorV2
+from tests.v1.utils import (
+    dumb_metadata,
+    generate_kv_cache_paged_list_tensors,
+    generate_tokens,
+)
+
+DEVICE_PARAMS = ["xpu"]
+BACKENDS = ["cpu", "disk"]
+
+# Optional override for tempfile root; see tests/v1/test_cache_engine.py
+# for rationale.
+_TEST_TMPDIR = os.environ.get("LMCACHE_TEST_TMPDIR") or None
+
+
+def _skip_if_no_xpu() -> None:
+    if not hasattr(torch, "xpu") or not torch.xpu.is_available():
+        pytest.skip("torch.xpu is not available")
+
+
+def _device_from_type(device_type: str) -> torch.device:
+    if device_type == "xpu":
+        return torch.device("xpu")
+    raise ValueError(device_type)
+
+
+def generate_random_slot_mapping(
+    num_blocks: int,
+    block_size: int,
+    num_tokens: int,
+    device: torch.device,
+) -> torch.Tensor:
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    return torch.tensor(slot_mapping, device=device)
+
+
+def get_expected_count(token_len: int, save_unfull_chunk: bool, chunk_size: int) -> int:
+    if save_unfull_chunk:
+        return token_len
+    return (token_len // chunk_size) * chunk_size
+
+
+def _wait_for_store(
+    engine,
+    tokens: list[torch.Tensor],
+    expected: int,
+    timeout: int = 60,
+) -> None:
+    start = time.time()
+    while time.time() - start < timeout:
+        if all(engine.lookup(t) == expected for t in tokens):
+            return
+        time.sleep(0.1)
+    raise TimeoutError(f"Store operation has not finished in {timeout} seconds")
+
+
+def _create_connector(
+    device: torch.device,
+    hidden_dim: int,
+    num_layers: int,
+    *,
+    use_gpu: bool,
+    chunk_size: int,
+    dtype: torch.dtype,
+    use_mla: bool = False,
+):
+    return VLLMPagedMemXPUConnectorV2(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=use_mla,
+        device=device,
+    )
+
+
+def _v2_store_vllm_contract(
+    engine,
+    list_token_ids,
+    list_slot_mappings,
+    kvcaches,
+    *,
+    chunk_size: int,
+    save_unfull_chunk: bool,
+):
+    """Mimic vLLM non-layerwise store contract for V2 connector."""
+    for token_ids, slot_mapping in zip(
+        list_token_ids, list_slot_mappings, strict=False
+    ):
+        tokens = token_ids
+        slots = slot_mapping.to(kvcaches[0][0].device)
+
+        if save_unfull_chunk:
+            aligned_len = len(tokens)
+        else:
+            aligned_len = (len(tokens) // chunk_size) * chunk_size
+            tokens = tokens[:aligned_len]
+            slots = slots[:aligned_len]
+
+        if aligned_len == 0:
+            continue
+
+        engine.store(tokens, kvcaches=kvcaches, slot_mapping=slots)
+
+
+def _v2_retrieve_vllm_contract(
+    engine,
+    list_token_ids,
+    list_slot_mappings,
+    kvcaches,
+    *,
+    chunk_size: int,
+    save_unfull_chunk: bool,
+):
+    """Mimic vLLM non-layerwise retrieve contract for V2 connector."""
+    for token_ids, slot_mapping in zip(
+        list_token_ids, list_slot_mappings, strict=False
+    ):
+        tokens = token_ids
+        slots = slot_mapping.to(kvcaches[0][0].device)
+
+        if save_unfull_chunk:
+            aligned_len = len(tokens)
+        else:
+            aligned_len = (len(tokens) // chunk_size) * chunk_size
+            tokens = tokens[:aligned_len]
+            slots = slots[:aligned_len]
+
+        if aligned_len == 0:
+            continue
+
+        engine.retrieve(tokens, kvcaches=kvcaches, slot_mapping=slots)
+
+
+@pytest.fixture
+def create_config():
+    def make_config(
+        backend: str, size: float, save_unfull_chunk: bool = True, **kwargs
+    ):
+        common = dict(
+            save_unfull_chunk=save_unfull_chunk,
+            extra_config={"force_store_wait": True},
+            use_layerwise=False,
+        )
+
+        match backend:
+            case "cpu":
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=True,
+                    max_local_cpu_size=size,
+                    **common,
+                )
+            case "disk":
+                assert "path" in kwargs, "'path' is missing for disk backend"
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=False,
+                    max_local_cpu_size=size,
+                    local_disk=kwargs["path"],
+                    max_local_disk_size=size,
+                    **common,
+                )
+            case _:
+                raise ValueError(f"Unknown backend: {backend}")
+
+    with tempfile.TemporaryDirectory(
+        dir=_TEST_TMPDIR, ignore_cleanup_errors=True
+    ) as temp_dir:
+        yield partial(make_config, path=temp_dir)
+
+
+def _build_engine(
+    *,
+    name: str,
+    cfg,
+    connector,
+    num_layers: int,
+    chunk_size: int,
+    num_heads: int,
+    head_dim: int,
+    autorelease_v1,
+):
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+    return autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            name,
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="store-v2")
+@pytest.mark.parametrize("device_type", DEVICE_PARAMS)
+@pytest.mark.parametrize("backend", BACKENDS)
+@pytest.mark.parametrize("use_gpu", [False, True])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_store_1gb_v2(
+    benchmark,
+    device_type,
+    backend,
+    use_gpu,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    _skip_if_no_xpu()
+
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    device = _device_from_type(device_type)
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    chunk_size = 256
+
+    num_requests = 4
+    num_repeats = 10
+
+    connector = _create_connector(
+        device,
+        hidden_dim=num_heads * head_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=False,
+    )
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_dim,
+    )
+
+    cfg = create_config(backend, 1.5, save_unfull_chunk=save_unfull_chunk)
+    engine = _build_engine(
+        name="test",
+        cfg=cfg,
+        connector=connector,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        num_heads=num_heads,
+        head_dim=head_dim,
+        autorelease_v1=autorelease_v1,
+    )
+
+    expected = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+
+    def run_func(tokens, slot_mappings):
+        _v2_store_vllm_contract(
+            engine,
+            tokens,
+            slot_mappings,
+            kv_cache,
+            chunk_size=chunk_size,
+            save_unfull_chunk=save_unfull_chunk,
+        )
+        _wait_for_store(engine, tokens, expected)
+
+    def setup():
+        list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+        list_slot_mappings = [
+            generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+            for _ in range(num_requests)
+        ]
+        return (list_tokens, list_slot_mappings), {}
+
+    warm_tokens, warm_slot_mappings = setup()[0]
+    run_func(warm_tokens, warm_slot_mappings)
+    benchmark.pedantic(run_func, setup=setup, rounds=num_repeats, iterations=1)
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="retrieve-v2")
+@pytest.mark.parametrize("device_type", DEVICE_PARAMS)
+@pytest.mark.parametrize("backend", BACKENDS)
+@pytest.mark.parametrize("use_gpu", [False, True])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_retrieve_1gb_allhit_v2(
+    benchmark,
+    device_type,
+    backend,
+    use_gpu,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    _skip_if_no_xpu()
+
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    device = _device_from_type(device_type)
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    chunk_size = 256
+
+    num_requests = 4
+    num_repeats = 10
+
+    connector = _create_connector(
+        device,
+        hidden_dim=num_heads * head_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=False,
+    )
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_dim,
+    )
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    cfg = create_config(backend, 1.5, save_unfull_chunk=save_unfull_chunk)
+    engine = _build_engine(
+        name="test",
+        cfg=cfg,
+        connector=connector,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        num_heads=num_heads,
+        head_dim=head_dim,
+        autorelease_v1=autorelease_v1,
+    )
+
+    _v2_store_vllm_contract(
+        engine,
+        list_tokens,
+        list_slot_mappings,
+        kv_cache,
+        chunk_size=chunk_size,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+    expected = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    _wait_for_store(engine, list_tokens, expected)
+
+    def run_func():
+        _v2_retrieve_vllm_contract(
+            engine,
+            list_tokens,
+            list_slot_mappings,
+            kv_cache,
+            chunk_size=chunk_size,
+            save_unfull_chunk=save_unfull_chunk,
+        )
+
+    run_func()
+    benchmark.pedantic(run_func, rounds=num_repeats, iterations=1)
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="lookup-v2")
+@pytest.mark.parametrize("device_type", DEVICE_PARAMS)
+@pytest.mark.parametrize("backend", BACKENDS)
+@pytest.mark.parametrize("use_gpu", [False, True])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_lookup_20k_tokens_v2(
+    benchmark,
+    device_type,
+    backend,
+    use_gpu,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    _skip_if_no_xpu()
+
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    device = _device_from_type(device_type)
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    chunk_size = 256
+
+    # Match layerwise benchmark's request count cap for use_gpu=True.
+    num_requests = 8 if use_gpu else 10
+    num_repeats = 10
+
+    connector = _create_connector(
+        device,
+        hidden_dim=num_heads * head_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=False,
+    )
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_dim,
+    )
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    cfg = create_config(backend, 3.0, save_unfull_chunk=save_unfull_chunk)
+    engine = _build_engine(
+        name="test",
+        cfg=cfg,
+        connector=connector,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        num_heads=num_heads,
+        head_dim=head_dim,
+        autorelease_v1=autorelease_v1,
+    )
+
+    _v2_store_vllm_contract(
+        engine,
+        list_tokens,
+        list_slot_mappings,
+        kv_cache,
+        chunk_size=chunk_size,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+    expected = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    _wait_for_store(engine, list_tokens, expected)
+
+    def run_func():
+        for t in list_tokens:
+            engine.lookup(t)
+
+    benchmark.pedantic(run_func, iterations=1, rounds=num_repeats)
diff --git a/tests/benchmarks/test_xpu_kernels_microbench.py b/tests/benchmarks/test_xpu_kernels_microbench.py
new file mode 100644
index 0000000..1d94058
--- /dev/null
+++ b/tests/benchmarks/test_xpu_kernels_microbench.py
@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Microbenchmarks: SYCL (XPU) kernels vs python_ops_fallback.
+
+Per the project plan, Phase 0 confirmed all four fallback functions
+accept XPU tensors directly, so we can do an apples-to-apples timing
+comparison on the same device.
+
+Run with: ``pytest tests/benchmarks/test_xpu_kernels_microbench.py --benchmark-only``
+"""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+import lmcache.python_ops_fallback as F
+
+pytestmark = pytest.mark.skipif(
+    not (hasattr(torch, "xpu") and torch.xpu.is_available()),
+    reason="Intel XPU not available",
+)
+
+XPU = "xpu"
+
+
+def _xpu_sync():
+    if hasattr(torch, "xpu") and torch.xpu.is_available():
+        torch.xpu.synchronize()
+
+
+@pytest.fixture(scope="module")
+def xops():
+    # First Party
+    import lmcache.xpu_ops as XOPS  # noqa: F401
+
+    return XOPS
+
+
+# ---------------- calculate_cdf ----------------
+
+
+@pytest.mark.benchmark(group="calculate_cdf")
+@pytest.mark.parametrize("ntokens", [256, 1024, 4096])
+def test_bench_cdf_sycl(benchmark, xops, ntokens):
+    nlayers, nchannels, max_bins = 32, 1024, 32
+    sym = torch.randint(
+        0, max_bins, (nlayers, ntokens, nchannels), dtype=torch.uint8, device=XPU
+    )
+    _xpu_sync()
+
+    def run():
+        out = xops.calculate_cdf(sym, max_bins)
+        _xpu_sync()
+        return out
+
+    benchmark(run)
+
+
+@pytest.mark.benchmark(group="calculate_cdf")
+@pytest.mark.parametrize("ntokens", [256, 1024, 4096])
+def test_bench_cdf_fallback(benchmark, ntokens):
+    nlayers, nchannels, max_bins = 32, 1024, 32
+    sym = torch.randint(
+        0, max_bins, (nlayers, ntokens, nchannels), dtype=torch.uint8, device=XPU
+    )
+    _xpu_sync()
+
+    def run():
+        out = F.calculate_cdf(sym, max_bins)
+        _xpu_sync()
+        return out
+
+    benchmark(run)
+
+
+# ---------------- encode_fast_new ----------------
+
+
+def _make_encode_inputs(xops, nlayers, ntokens, nchannels, max_bins):
+    sym = torch.randint(
+        0, max_bins, (nlayers, ntokens, nchannels), dtype=torch.uint8, device=XPU
+    )
+    cdf = xops.calculate_cdf(sym, max_bins)
+    buf = torch.zeros((nlayers, nchannels, 256), dtype=torch.uint8, device=XPU)
+    lens = torch.zeros((nlayers, nchannels), dtype=torch.int32, device=XPU)
+    return sym, cdf, buf, lens
+
+
+@pytest.mark.benchmark(group="encode_fast_new")
+@pytest.mark.parametrize("ntokens", [64, 256])
+def test_bench_encode_sycl(benchmark, xops, ntokens):
+    nlayers, nchannels, max_bins = 32, 1024, 32
+    sym, cdf, buf, lens = _make_encode_inputs(
+        xops, nlayers, ntokens, nchannels, max_bins
+    )
+    _xpu_sync()
+
+    def run():
+        xops.encode_fast_new(cdf, sym, buf, lens)
+        _xpu_sync()
+
+    benchmark(run)
+
+
+@pytest.mark.benchmark(group="encode_fast_new")
+@pytest.mark.parametrize("ntokens", [64, 256])
+def test_bench_encode_fallback(benchmark, xops, ntokens):
+    nlayers, nchannels, max_bins = 32, 1024, 32
+    sym, cdf, buf, lens = _make_encode_inputs(
+        xops, nlayers, ntokens, nchannels, max_bins
+    )
+    _xpu_sync()
+
+    def run():
+        F.encode_fast_new(cdf, sym, buf, lens)
+        _xpu_sync()
+
+    benchmark(run)
+
+
+# ---------------- decode_fast_new ----------------
+
+
+@pytest.mark.benchmark(group="decode_fast_new")
+@pytest.mark.parametrize("ntokens", [256])
+def test_bench_decode_sycl(benchmark, xops, ntokens):
+    nlayers, nchannels, max_bins = 32, 1024, 32
+    sym, cdf, buf, lens = _make_encode_inputs(
+        xops, nlayers, ntokens, nchannels, max_bins
+    )
+    xops.encode_fast_new(cdf, sym, buf, lens)
+    out = torch.zeros_like(sym)
+    _xpu_sync()
+
+    def run():
+        xops.decode_fast_new(cdf, buf, lens, out)
+        _xpu_sync()
+
+    benchmark(run)
+
+
+# NOTE: decode_fast_new fallback crashes on XPU with an internal
+# IndexKernel gather OOB on these shapes (a torch-xpu fallback bug,
+# not a CacheGen bug).  Per the project plan we do not modify
+# python_ops_fallback to accommodate XPU; the SYCL kernel is the
+# correct/fast path.  Recording the absolute SYCL throughput is
+# sufficient.
+
+
+# ---------------- rotary_embedding_k_fused ----------------
+
+
+@pytest.mark.benchmark(group="rope_k_fused")
+@pytest.mark.parametrize("ntokens", [256, 1024, 4096])
+def test_bench_rope_sycl(benchmark, xops, ntokens):
+    num_kv_heads, head_size, rot_dim = 8, 128, 128
+    embed_dim = num_kv_heads * head_size
+    old_positions = torch.arange(ntokens, dtype=torch.int64, device=XPU)
+    new_positions = (old_positions + 1) % 2048
+    key = torch.randn(ntokens, embed_dim, dtype=torch.float16, device=XPU)
+    cos_sin = torch.randn(2048, rot_dim, dtype=torch.float16, device=XPU)
+    _xpu_sync()
+
+    def run():
+        xops.rotary_embedding_k_fused(
+            old_positions, new_positions, key, head_size, cos_sin, True
+        )
+        _xpu_sync()
+
+    benchmark(run)
+
+
+# NOTE: rotary_embedding_k_fused fallback uses advanced indexing that
+# triggers an internal IndexKernel OOB on XPU at these shapes.  Per the
+# project plan we do not patch fallback to fit XPU; SYCL is the
+# performance and correctness path.
diff --git a/tests/benchmarks/test_xpu_layerwise_connector_benchmark.py b/tests/benchmarks/test_xpu_layerwise_connector_benchmark.py
new file mode 100644
index 0000000..e2adc3b
--- /dev/null
+++ b/tests/benchmarks/test_xpu_layerwise_connector_benchmark.py
@@ -0,0 +1,602 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from functools import partial
+import os
+import random
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.xpu_connectors import VLLMPagedMemLayerwiseXPUConnector
+from tests.v1.utils import (
+    dumb_metadata,
+    generate_kv_cache_paged_list_tensors,
+    generate_tokens,
+)
+
+DEVICE_PARAMS = ["xpu"]
+BACKENDS = ["cpu", "disk"]
+
+# Optional override for tempfile root; see tests/v1/test_cache_engine.py
+# for rationale.
+_TEST_TMPDIR = os.environ.get("LMCACHE_TEST_TMPDIR") or None
+
+
+def _skip_if_no_xpu():
+    if not hasattr(torch, "xpu") or not torch.xpu.is_available():
+        pytest.skip("torch.xpu is not available")
+
+
+def generate_random_slot_mapping(num_blocks, block_size, num_tokens, device):
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    return torch.tensor(slot_mapping, device=device)
+
+
+def get_expected_count(token_len, save_unfull_chunk, chunk_size):
+    # expected tokens stored (not chunks)
+    if save_unfull_chunk:
+        return token_len
+    return (token_len // chunk_size) * chunk_size
+
+
+def _device_from_type(device_type):
+    if device_type == "xpu":
+        return torch.device("xpu")
+    raise ValueError(device_type)
+
+
+def _wait_for_store(engine, tokens, expected, timeout=60):
+    start = time.time()
+    last_hits = []
+    while time.time() - start < timeout:
+        last_hits = [engine.lookup(t) for t in tokens]
+        ready = all(hit == expected for hit in last_hits)
+        if ready:
+            return
+        time.sleep(0.1)
+    raise TimeoutError(
+        "Store operation hasn't finished in "
+        f"{timeout} seconds. expected={expected}, hits={last_hits}"
+    )
+
+
+def _create_connector(
+    device: torch.device,
+    hidden_dim: int,
+    num_layers: int,
+    *,
+    use_gpu: bool,
+    chunk_size: int,
+    dtype: torch.dtype,
+    use_mla: bool = False,
+):
+    return VLLMPagedMemLayerwiseXPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+
+
+def _layerwise_store_vllm_contract(
+    engine,
+    list_token_ids,  # list[Tensor] or list[list[int]]
+    list_slot_mappings,  # list[Tensor]
+    kvcaches,
+    *,
+    num_layers: int,
+    chunk_size: int,
+    save_unfull_chunk: bool,
+):
+    """
+    Mimic vLLM layerwise store contract:
+
+      - create one store_layer generator per request
+        (first one sync=True, rest sync=False)
+      - tick generators once per layer (num_layers times)
+      - tick generators one final time (like wait_for_save)
+
+    IMPORTANT:
+      - store_layer expects token_ids as list[int] (like vLLM adapter)
+      - for save_unfull_chunk=False, truncate to aligned_len
+        instead of trailing False mask
+      - mask False indicates skipped LEADING tokens only (we use skip=0 here)
+    """
+    storers = []
+    is_first = True
+
+    for token_ids, slot_mapping in zip(
+        list_token_ids, list_slot_mappings, strict=False
+    ):
+        # token_ids: Tensor -> list[int]
+        token_ids_list = (
+            token_ids.tolist() if isinstance(token_ids, torch.Tensor) else token_ids
+        )
+
+        # keep slot_mapping on same device as kvcaches (xpu)
+        slot_mapping = slot_mapping.to(kvcaches[0].device)
+
+        if save_unfull_chunk:
+            aligned_len = len(token_ids_list)
+        else:
+            aligned_len = (len(token_ids_list) // chunk_size) * chunk_size
+            token_ids_list = token_ids_list[:aligned_len]
+            slot_mapping = slot_mapping[:aligned_len]
+
+        if aligned_len == 0:
+            continue
+
+        skip_leading_tokens = 0
+        # put mask on same device (avoid implicit device moves)
+        mask = torch.ones(
+            len(token_ids_list), dtype=torch.bool, device=slot_mapping.device
+        )
+        mask[:skip_leading_tokens] = False
+
+        st = engine.store_layer(
+            token_ids_list,
+            mask=mask,
+            kvcaches=kvcaches,
+            slot_mapping=slot_mapping,
+            offset=skip_leading_tokens,
+            sync=is_first,
+        )
+        storers.append(st)
+        is_first = False
+
+    # Tick once per layer
+    for _ in range(num_layers):
+        for st in storers:
+            next(st)
+
+    # Finalize tick (equivalent of wait_for_save)
+    for st in storers:
+        next(st)
+
+
+def _layerwise_retrieve_vllm_contract(
+    engine,
+    list_token_ids,
+    list_slot_mappings,
+    kvcaches,
+    *,
+    num_layers: int,
+    chunk_size: int,
+    save_unfull_chunk: bool,
+):
+    """Mimic vLLM layerwise retrieve contract.
+
+    For layerwise mode, benchmark should call retrieve_layer with the same
+    slot mapping + KV cache context used by GPU connector.
+    """
+    retrievers = []
+    is_first = True
+
+    for token_ids, slot_mapping in zip(
+        list_token_ids, list_slot_mappings, strict=False
+    ):
+        if isinstance(token_ids, torch.Tensor):
+            tokens = token_ids
+        else:
+            tokens = torch.tensor(
+                token_ids, dtype=torch.long, device=slot_mapping.device
+            )
+
+        slot_mapping = slot_mapping.to(kvcaches[0].device)
+
+        if save_unfull_chunk:
+            aligned_len = len(tokens)
+        else:
+            aligned_len = (len(tokens) // chunk_size) * chunk_size
+            tokens = tokens[:aligned_len]
+            slot_mapping = slot_mapping[:aligned_len]
+
+        if aligned_len == 0:
+            continue
+
+        mask = torch.ones(aligned_len, dtype=torch.bool, device=slot_mapping.device)
+        retriever = engine.retrieve_layer(
+            tokens,
+            mask=mask,
+            kvcaches=kvcaches,
+            slot_mapping=slot_mapping,
+            sync=is_first,
+        )
+        retrievers.append(retriever)
+        is_first = False
+
+    # Tick once per layer to overlap multi-request loading/copying.
+    for _ in range(num_layers):
+        for retriever in retrievers:
+            next(retriever)
+
+    # Finalize connector sync stage.
+    for retriever in retrievers:
+        next(retriever)
+
+    # Consume final ret_mask yield.
+    for retriever in retrievers:
+        next(retriever)
+
+
+@pytest.fixture
+def create_config():
+    def make_config(backend, size, save_unfull_chunk=True, **kwargs):
+        # NOTE: use_layerwise=True because we use store_layer contract
+        common = dict(
+            save_unfull_chunk=save_unfull_chunk,
+            extra_config={"force_store_wait": True},  # deterministic for benchmarks
+            use_layerwise=True,
+        )
+
+        match backend:
+            case "cpu":
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=True,
+                    max_local_cpu_size=size,
+                    **common,
+                )
+            case "disk":
+                assert "path" in kwargs, "'path' is missing for disk backend"
+                return LMCacheEngineConfig.from_defaults(
+                    local_cpu=False,
+                    max_local_cpu_size=size,
+                    local_disk=kwargs["path"],
+                    max_local_disk_size=size,
+                    **common,
+                )
+            case _:
+                raise ValueError(f"Unknown backend: {backend}")
+
+    with tempfile.TemporaryDirectory(
+        dir=_TEST_TMPDIR, ignore_cleanup_errors=True
+    ) as temp_dir:
+        yield partial(make_config, path=temp_dir)
+
+
+def _build_engine(
+    *,
+    name: str,
+    cfg,
+    connector,
+    num_layers: int,
+    chunk_size: int,
+    num_heads: int,
+    head_dim: int,
+    autorelease_v1,
+):
+    # metadata shape used by tests
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+    return autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            name,
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+
+# --------------------------
+# Store benchmarks
+# --------------------------
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="store")
+@pytest.mark.parametrize("device_type", DEVICE_PARAMS)
+@pytest.mark.parametrize("backend", ["cpu", "disk"])
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_store_1GB(
+    benchmark,
+    device_type,
+    backend,
+    use_gpu,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    _skip_if_no_xpu()
+    """
+    Store benchmark for XPU layerwise connector.
+
+    Reduces volatility by:
+      - warming up once outside timing
+      - reusing the same engine/backend state
+      - shuffling request order per round
+    """
+    # model-related metadata
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    # lmcache / vllm configs
+    device = _device_from_type(device_type)
+
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    chunk_size = 256
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+
+    # benchmark configs
+    num_requests = 4
+    num_repeats = 10
+
+    connector = _create_connector(
+        device,
+        hidden_dim=num_heads * head_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=False,
+    )
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_dim,
+    )
+
+    cache_size = 1.5
+    cfg = create_config(backend, cache_size, save_unfull_chunk=save_unfull_chunk)
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    expected = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+
+    def run_func(tokens, slot_mappings):
+        _layerwise_store_vllm_contract(
+            engine,
+            tokens,
+            slot_mappings,
+            kv_cache,
+            num_layers=num_layers,
+            chunk_size=chunk_size,
+            save_unfull_chunk=save_unfull_chunk,
+        )
+        _wait_for_store(engine, tokens, expected)
+
+    def setup():
+        list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+        list_slot_mappings = [
+            generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+            for _ in range(num_requests)
+        ]
+        return (
+            list_tokens,
+            list_slot_mappings,
+        ), {}
+
+    # Warm up once outside timing to absorb first-touch XPU/backend overhead.
+    warm_tokens, warm_slot_mappings = setup()[0]
+    run_func(warm_tokens, warm_slot_mappings)
+    benchmark.pedantic(
+        run_func,
+        setup=setup,
+        rounds=num_repeats,
+        iterations=1,
+    )
+
+
+# --------------------------
+# Retrieve benchmarks (100% hit)
+# --------------------------
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="retrieve")
+@pytest.mark.parametrize("device_type", DEVICE_PARAMS)
+@pytest.mark.parametrize("backend", BACKENDS)
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_retrieve_1GB_allhit(
+    benchmark,
+    device_type,
+    backend,
+    use_gpu,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    _skip_if_no_xpu()
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    device = _device_from_type(device_type)
+
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    chunk_size = 256
+
+    num_requests = 4
+    num_repeats = 10
+
+    connector = _create_connector(
+        device,
+        hidden_dim=num_heads * head_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=False,
+    )
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_dim,
+    )
+    kvcaches = kv_cache
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    cfg = create_config(backend, 1.5, save_unfull_chunk=save_unfull_chunk)
+    engine = _build_engine(
+        name="test",
+        cfg=cfg,
+        connector=connector,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        num_heads=num_heads,
+        head_dim=head_dim,
+        autorelease_v1=autorelease_v1,
+    )
+
+    # Pre-populate cache once (not timed)
+    _layerwise_store_vllm_contract(
+        engine,
+        list_tokens,
+        list_slot_mappings,
+        kvcaches,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+    expected = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    _wait_for_store(engine, list_tokens, expected)
+
+    def run_func():
+        _layerwise_retrieve_vllm_contract(
+            engine,
+            list_tokens,
+            list_slot_mappings,
+            kvcaches,
+            num_layers=num_layers,
+            chunk_size=chunk_size,
+            save_unfull_chunk=save_unfull_chunk,
+        )
+
+    # Warm up once outside timing to absorb first-touch retrieve overhead.
+    run_func()
+
+    benchmark.pedantic(run_func, rounds=num_repeats, iterations=1)
+
+
+# --------------------------
+# Lookup benchmarks (100% hit)
+# 10 rounds, 1 iteration (requested)
+# --------------------------
+@pytest.mark.no_shared_allocator
+@pytest.mark.benchmark(group="lookup")
+@pytest.mark.parametrize("device_type", DEVICE_PARAMS)
+@pytest.mark.parametrize("backend", BACKENDS)
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_lookup_20K_tokens(
+    benchmark,
+    device_type,
+    backend,
+    use_gpu,
+    save_unfull_chunk,
+    create_config,
+    autorelease_v1,
+):
+    _skip_if_no_xpu()
+    num_heads = 8
+    head_dim = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+
+    device = _device_from_type(device_type)
+
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    chunk_size = 256
+
+    # use_gpu=True stages per-request chunks on XPU during layerwise store.
+    # Keeping 10 requests can exceed the default staging pool in pre-population.
+    num_requests = 8 if use_gpu else 10
+    num_repeats = 10
+
+    connector = _create_connector(
+        device,
+        hidden_dim=num_heads * head_dim,
+        num_layers=num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        use_mla=False,
+    )
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_dim,
+    )
+    kvcaches = kv_cache
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    cfg = create_config(backend, 3.0, save_unfull_chunk=save_unfull_chunk)
+    engine = _build_engine(
+        name="test",
+        cfg=cfg,
+        connector=connector,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        num_heads=num_heads,
+        head_dim=head_dim,
+        autorelease_v1=autorelease_v1,
+    )
+
+    # Pre-populate once (not timed)
+    _layerwise_store_vllm_contract(
+        engine,
+        list_tokens,
+        list_slot_mappings,
+        kvcaches,
+        num_layers=num_layers,
+        chunk_size=chunk_size,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+    expected = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    _wait_for_store(engine, list_tokens, expected)
+
+    def run_func():
+        # 1 iteration per round, 10 rounds (requested)
+        for t in list_tokens:
+            engine.lookup(t)
+
+    benchmark.pedantic(run_func, iterations=1, rounds=num_repeats)
diff --git a/tests/cli/__init__.py b/tests/cli/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/cli/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/cli/commands/__init__.py b/tests/cli/commands/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/cli/commands/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/cli/commands/bench/__init__.py b/tests/cli/commands/bench/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/cli/commands/bench/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/cli/commands/bench/engine_bench/__init__.py b/tests/cli/commands/bench/engine_bench/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/cli/commands/bench/engine_bench/interactive/__init__.py b/tests/cli/commands/bench/engine_bench/interactive/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/interactive/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/cli/commands/bench/engine_bench/interactive/test_back.py b/tests/cli/commands/bench/engine_bench/interactive/test_back.py
new file mode 100644
index 0000000..6ed2961
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/interactive/test_back.py
@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for 'go back' navigation in the interactive flow."""
+
+# Standard
+from typing import Any
+from unittest import mock
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench import interactive as flow
+from lmcache.cli.commands.bench.engine_bench.interactive import terminal
+from lmcache.cli.commands.bench.engine_bench.interactive.state import (
+    InteractiveState,
+)
+
+
+def test_back_token_returns_sentinel_only_when_enabled() -> None:
+    # The same key ("<") means "go back" everywhere, but only when offered.
+    with mock.patch("builtins.input", return_value=terminal.BACK_TOKEN):
+        assert terminal.prompt_text("L", allow_back=True) is terminal.GO_BACK
+        assert terminal.prompt_text("L", allow_back=False) == terminal.BACK_TOKEN
+
+
+def test_normalize_url_shorthand() -> None:
+    assert flow._normalize_url("8000") == "http://localhost:8000"
+    assert flow._normalize_url("localhost:8000") == "http://localhost:8000"
+    assert flow._normalize_url("http://host:9000") == "http://host:9000"
+    assert flow._normalize_url("") == ""
+
+
+def _drive(monkeypatch: Any, answers: list[tuple[str, Any]]) -> InteractiveState:
+    """Run the driver, feeding scripted answers keyed by question identity."""
+    pending = iter(answers)
+
+    def pull(tag: str) -> Any:
+        expected, value = next(pending)
+        assert expected == tag, f"expected {expected!r}, got {tag!r}"
+        return value
+
+    monkeypatch.setattr(
+        flow, "_prompt_for_item", lambda item, allow_back: pull(item.key)
+    )
+    monkeypatch.setattr(
+        flow,
+        "_prompt_gate",
+        lambda name, detail, allow_back: pull(
+            "gate:workload" if "Workload" in name else "gate:general"
+        ),
+    )
+    monkeypatch.setattr(flow, "_prompt_action", lambda allow_back: pull("action"))
+    monkeypatch.setattr(flow, "_print_summary", lambda state: None)
+
+    state = InteractiveState()
+    state.set("__started", flow._gather_config(state))
+    return state
+
+
+def test_back_undoes_previous_answer(monkeypatch: Any) -> None:
+    # has_lmcache=False makes tokens the next question; going back there must
+    # un-set has_lmcache and re-ask it.
+    state = _drive(
+        monkeypatch,
+        [
+            ("engine_url", "http://x"),
+            ("workload", "random-prefill"),
+            ("has_lmcache", False),
+            ("tokens_per_gb_kvcache", terminal.GO_BACK),  # back
+            ("has_lmcache", True),  # re-answered
+            ("lmcache_url", "http://y"),
+            ("gate:general", "use defaults"),
+            ("gate:workload", "use defaults"),
+            ("action", "start"),
+        ],
+    )
+    assert state.get("__started") is True
+    assert state.get("has_lmcache") is True
+    assert state.is_set("tokens_per_gb_kvcache") is False
+
+
+def test_quit_returns_false(monkeypatch: Any) -> None:
+    state = _drive(
+        monkeypatch,
+        [
+            ("engine_url", "http://x"),
+            ("workload", "random-prefill"),
+            ("has_lmcache", True),
+            ("lmcache_url", "http://y"),
+            ("gate:general", "use defaults"),
+            ("gate:workload", "use defaults"),
+            ("action", "quit"),
+        ],
+    )
+    assert state.get("__started") is False
diff --git a/tests/cli/commands/bench/engine_bench/interactive/test_schema.py b/tests/cli/commands/bench/engine_bench/interactive/test_schema.py
new file mode 100644
index 0000000..4a532c7
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/interactive/test_schema.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the config item schema."""
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.interactive.schema import (
+    ALL_ITEMS,
+    PHASE_GENERAL,
+    PHASE_REQUIRED,
+    PHASE_WORKLOAD,
+    ConfigItem,
+    get_item,
+    get_items_by_phase,
+)
+
+
+class TestConfigItemStructure:
+    def test_all_items_non_empty(self) -> None:
+        assert len(ALL_ITEMS) > 0
+
+    def test_all_items_have_unique_keys(self) -> None:
+        keys = [item.key for item in ALL_ITEMS]
+        assert len(keys) == len(set(keys))
+
+    def test_required_items_in_phase_required(self) -> None:
+        for item in ALL_ITEMS:
+            if item.required:
+                assert item.phase == PHASE_REQUIRED, (
+                    f"{item.key} is required but in phase {item.phase}"
+                )
+
+    def test_choice_items_have_choices(self) -> None:
+        for item in ALL_ITEMS:
+            if item.input_type == "choice":
+                assert len(item.choices) > 0, (
+                    f"{item.key} is 'choice' type but has no choices"
+                )
+
+    def test_all_input_types_valid(self) -> None:
+        valid = {"text", "int", "float", "bool", "choice"}
+        for item in ALL_ITEMS:
+            assert item.input_type in valid, (
+                f"{item.key} has unknown input_type {item.input_type!r}"
+            )
+
+
+class TestGetItemsByPhase:
+    def test_required_phase(self) -> None:
+        items = get_items_by_phase(PHASE_REQUIRED)
+        assert len(items) >= 3  # engine_url, workload, lmcache_url, tokens_per_gb
+        for item in items:
+            assert item.phase == PHASE_REQUIRED
+
+    def test_general_phase(self) -> None:
+        items = get_items_by_phase(PHASE_GENERAL)
+        assert len(items) >= 1
+        for item in items:
+            assert item.phase == PHASE_GENERAL
+
+    def test_workload_phase(self) -> None:
+        items = get_items_by_phase(PHASE_WORKLOAD)
+        assert len(items) >= 4  # long-doc-qa has 4
+        for item in items:
+            assert item.phase == PHASE_WORKLOAD
+
+
+class TestGetItem:
+    def test_known_key(self) -> None:
+        item = get_item("engine_url")
+        assert isinstance(item, ConfigItem)
+        assert item.key == "engine_url"
+        assert item.required is True
+
+    def test_unknown_key_raises(self) -> None:
+        # Third Party
+        import pytest
+
+        with pytest.raises(KeyError, match="no_such_key"):
+            get_item("no_such_key")
+
+
+class TestConditions:
+    def test_tokens_per_gb_condition_no_lmcache(self) -> None:
+        item = get_item("tokens_per_gb_kvcache")
+        assert item.condition is not None
+        # No lmcache_url → condition met → should show
+        assert item.condition({}) is True
+        assert item.condition({"lmcache_url": ""}) is True
+
+    def test_tokens_per_gb_condition_with_lmcache(self) -> None:
+        item = get_item("tokens_per_gb_kvcache")
+        assert item.condition is not None
+        # lmcache_url set → condition not met → skip
+        assert item.condition({"lmcache_url": "http://localhost:8080"}) is False
+
+    def test_ldqa_condition(self) -> None:
+        item = get_item("ldqa_document_length")
+        assert item.condition is not None
+        assert item.condition({"workload": "long-doc-qa"}) is True
+        assert item.condition({"workload": "multi-round-chat"}) is False
+        assert item.condition({}) is False
+
+    def test_mrc_condition(self) -> None:
+        item = get_item("mrc_shared_prompt_length")
+        assert item.condition is not None
+        assert item.condition({"workload": "multi-round-chat"}) is True
+        assert item.condition({"workload": "long-doc-qa"}) is False
+
+    def test_rp_condition(self) -> None:
+        item = get_item("rp_request_length")
+        assert item.condition is not None
+        assert item.condition({"workload": "random-prefill"}) is True
+        assert item.condition({"workload": "long-doc-qa"}) is False
diff --git a/tests/cli/commands/bench/engine_bench/interactive/test_state.py b/tests/cli/commands/bench/engine_bench/interactive/test_state.py
new file mode 100644
index 0000000..5c8aad7
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/interactive/test_state.py
@@ -0,0 +1,368 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for InteractiveState."""
+
+# Standard
+import argparse
+import json
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.interactive.state import (
+    InteractiveState,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_full_state(**overrides: object) -> InteractiveState:
+    """Build a state with all required fields set."""
+    values: dict[str, object] = {
+        "engine_url": "http://localhost:8000",
+        "workload": "long-doc-qa",
+        "tokens_per_gb_kvcache": 6553,
+    }
+    values.update(overrides)
+    state = InteractiveState()
+    for k, v in values.items():
+        state.set(k, v)
+    return state
+
+
+def _make_cli_args(**overrides: object) -> argparse.Namespace:
+    """Build a Namespace mimicking bench engine CLI output."""
+    defaults: dict[str, object] = {
+        "engine_url": None,
+        "workload": None,
+        "model": None,
+        "lmcache_url": None,
+        "tokens_per_gb_kvcache": None,
+        "kv_cache_volume": 100.0,
+        "seed": 42,
+        "output_dir": ".",
+        "no_csv": False,
+        "json": False,
+        "quiet": False,
+        "ldqa_document_length": 10000,
+        "ldqa_query_per_document": 2,
+        "ldqa_shuffle_policy": "random",
+        "ldqa_num_inflight_requests": 3,
+        "mrc_shared_prompt_length": 2000,
+        "mrc_chat_history_length": 10000,
+        "mrc_user_input_length": 50,
+        "mrc_output_length": 200,
+        "mrc_qps": 1.0,
+        "mrc_duration": 60.0,
+        "rp_request_length": 10000,
+        "rp_num_requests": 50,
+        "format": None,
+        "output": None,
+        "config": None,
+        "bench_target": "engine",
+    }
+    defaults.update(overrides)
+    return argparse.Namespace(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# Basic accessors
+# ---------------------------------------------------------------------------
+
+
+class TestBasicAccessors:
+    def test_empty_state(self) -> None:
+        state = InteractiveState()
+        assert not state.is_set("engine_url")
+        assert state.get("engine_url") is None
+        assert state.get("engine_url", "fallback") == "fallback"
+
+    def test_set_and_get(self) -> None:
+        state = InteractiveState()
+        state.set("engine_url", "http://localhost:8000")
+        assert state.is_set("engine_url")
+        assert state.get("engine_url") == "http://localhost:8000"
+
+    def test_values_copy(self) -> None:
+        state = _make_full_state()
+        vals = state.values
+        vals["engine_url"] = "mutated"
+        assert state.get("engine_url") == "http://localhost:8000"
+
+
+# ---------------------------------------------------------------------------
+# Readiness
+# ---------------------------------------------------------------------------
+
+
+class TestReadiness:
+    def test_empty_not_ready(self) -> None:
+        state = InteractiveState()
+        assert not state.is_ready()
+
+    def test_full_state_ready(self) -> None:
+        state = _make_full_state()
+        assert state.is_ready()
+
+    def test_missing_engine_url(self) -> None:
+        state = _make_full_state()
+        state._values.pop("engine_url")
+        assert not state.is_ready()
+
+    def test_missing_workload(self) -> None:
+        state = _make_full_state()
+        state._values.pop("workload")
+        assert not state.is_ready()
+
+    def test_tokens_per_gb_not_required_when_lmcache_set(self) -> None:
+        state = InteractiveState()
+        state.set("engine_url", "http://localhost:8000")
+        state.set("workload", "long-doc-qa")
+        state.set("lmcache_url", "http://localhost:8080")
+        # tokens_per_gb_kvcache not set, but lmcache_url is → condition
+        # for tokens_per_gb is not met → not required
+        assert state.is_ready()
+
+
+# ---------------------------------------------------------------------------
+# Missing required
+# ---------------------------------------------------------------------------
+
+
+class TestMissingRequired:
+    def test_all_missing(self) -> None:
+        state = InteractiveState()
+        missing = state.get_missing_required()
+        keys = [item.key for item in missing]
+        assert "engine_url" in keys
+        assert "workload" in keys
+
+    def test_none_missing(self) -> None:
+        state = _make_full_state()
+        assert state.get_missing_required() == []
+
+    def test_tokens_per_gb_skipped_with_lmcache(self) -> None:
+        state = InteractiveState()
+        state.set("engine_url", "http://localhost:8000")
+        state.set("workload", "long-doc-qa")
+        state.set("lmcache_url", "http://localhost:8080")
+        missing = state.get_missing_required()
+        keys = [item.key for item in missing]
+        assert "tokens_per_gb_kvcache" not in keys
+
+
+# ---------------------------------------------------------------------------
+# Workload items
+# ---------------------------------------------------------------------------
+
+
+class TestWorkloadItems:
+    def test_long_doc_qa(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        items = state.get_workload_items()
+        keys = [item.key for item in items]
+        assert "ldqa_document_length" in keys
+        assert "mrc_qps" not in keys
+        assert "rp_num_requests" not in keys
+
+    def test_multi_round_chat(self) -> None:
+        state = _make_full_state(workload="multi-round-chat")
+        items = state.get_workload_items()
+        keys = [item.key for item in items]
+        assert "mrc_shared_prompt_length" in keys
+        assert "ldqa_document_length" not in keys
+
+    def test_random_prefill(self) -> None:
+        state = _make_full_state(workload="random-prefill")
+        items = state.get_workload_items()
+        keys = [item.key for item in items]
+        assert "rp_request_length" in keys
+        assert "ldqa_document_length" not in keys
+
+    def test_workload_items_all_default_initially(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        assert state.workload_items_all_default()
+
+    def test_workload_items_not_default_after_set(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.set("ldqa_document_length", 5000)
+        assert not state.workload_items_all_default()
+
+
+# ---------------------------------------------------------------------------
+# Fill defaults
+# ---------------------------------------------------------------------------
+
+
+class TestFillDefaults:
+    def test_fills_kv_cache_volume(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.fill_defaults()
+        assert state.get("kv_cache_volume") == 100.0
+
+    def test_fills_workload_defaults(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.fill_defaults()
+        assert state.get("ldqa_document_length") == 10000
+        assert state.get("ldqa_query_per_document") == 2
+
+    def test_does_not_overwrite_set_values(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.set("ldqa_document_length", 5000)
+        state.fill_defaults()
+        assert state.get("ldqa_document_length") == 5000
+
+
+# ---------------------------------------------------------------------------
+# from_cli_args
+# ---------------------------------------------------------------------------
+
+
+class TestFromCliArgs:
+    def test_picks_up_explicit_values(self) -> None:
+        args = _make_cli_args(
+            engine_url="http://host:8000",
+            workload="long-doc-qa",
+            tokens_per_gb_kvcache=6553,
+        )
+        state = InteractiveState.from_cli_args(args)
+        assert state.get("engine_url") == "http://host:8000"
+        assert state.get("workload") == "long-doc-qa"
+        assert state.get("tokens_per_gb_kvcache") == 6553
+
+    def test_none_values_not_set(self) -> None:
+        args = _make_cli_args()  # all defaults
+        state = InteractiveState.from_cli_args(args)
+        assert not state.is_set("engine_url")
+        assert not state.is_set("workload")
+        assert not state.is_set("model")
+
+    def test_default_values_not_set(self) -> None:
+        # kv_cache_volume defaults to 100.0 — should not be marked as set
+        args = _make_cli_args(kv_cache_volume=100.0)
+        state = InteractiveState.from_cli_args(args)
+        assert not state.is_set("kv_cache_volume")
+
+    def test_non_default_values_set(self) -> None:
+        args = _make_cli_args(kv_cache_volume=50.0)
+        state = InteractiveState.from_cli_args(args)
+        assert state.is_set("kv_cache_volume")
+        assert state.get("kv_cache_volume") == 50.0
+
+
+# ---------------------------------------------------------------------------
+# to_namespace
+# ---------------------------------------------------------------------------
+
+
+class TestToNamespace:
+    def test_round_trip(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        ns = state.to_namespace()
+        assert ns.engine_url == "http://localhost:8000"
+        assert ns.workload == "long-doc-qa"
+        assert ns.tokens_per_gb_kvcache == 6553
+        # Defaults filled
+        assert ns.kv_cache_volume == 100.0
+        assert ns.ldqa_document_length == 10000
+        assert ns.seed == 42
+
+    def test_has_bench_target(self) -> None:
+        state = _make_full_state()
+        ns = state.to_namespace()
+        assert ns.bench_target == "engine"
+
+    def test_has_output_attrs(self) -> None:
+        state = _make_full_state()
+        ns = state.to_namespace()
+        assert hasattr(ns, "output_dir")
+        assert hasattr(ns, "no_csv")
+        assert hasattr(ns, "quiet")
+        assert hasattr(ns, "format")
+        assert hasattr(ns, "output")
+
+
+# ---------------------------------------------------------------------------
+# JSON round-trip
+# ---------------------------------------------------------------------------
+
+
+class TestJsonRoundTrip:
+    def test_to_json_and_back(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.set("ldqa_document_length", 5000)
+        data = state.to_json()
+        # engine_url excluded from export (environment-specific)
+        assert "engine_url" not in data
+        assert data["ldqa_document_length"] == 5000
+        restored = InteractiveState.from_json(data)
+        assert restored.get("ldqa_document_length") == 5000
+
+    def test_save_and_load(self, tmp_path: object) -> None:
+        # Standard
+        import pathlib
+
+        path = str(pathlib.Path(str(tmp_path)) / "test_config.json")
+        state = _make_full_state(workload="long-doc-qa")
+        state.save_json(path)
+
+        loaded = InteractiveState.load_json(path)
+        assert "engine_url" not in loaded.values
+        assert loaded.get("workload") == "long-doc-qa"
+
+    def test_json_file_is_valid_json(self, tmp_path: object) -> None:
+        # Standard
+        import pathlib
+
+        path = str(pathlib.Path(str(tmp_path)) / "test.json")
+        state = _make_full_state()
+        state.save_json(path)
+
+        with open(path) as f:
+            data = json.load(f)
+        assert isinstance(data, dict)
+        assert "engine_url" not in data
+        assert data["workload"] == "long-doc-qa"
+
+    def test_merge_cli_args(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        args = _make_cli_args(
+            engine_url="http://override:9000",
+        )
+        state.merge_cli_args(args)
+        assert state.get("engine_url") == "http://override:9000"
+        # Original values preserved
+        assert state.get("workload") == "long-doc-qa"
+
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+
+
+class TestSummary:
+    def test_summary_lines_non_empty(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.fill_defaults()
+        lines = state.summary_lines()
+        assert len(lines) > 0
+
+    def test_summary_includes_engine_url(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.fill_defaults()
+        labels = [label for label, _ in state.summary_lines()]
+        assert "Engine URL" in labels
+
+    def test_summary_shows_auto_detect_for_empty_model(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.fill_defaults()
+        for label, value in state.summary_lines():
+            if label == "Model name":
+                assert value == "(auto-detect)"
+                break
+
+    def test_summary_excludes_wrong_workload_items(self) -> None:
+        state = _make_full_state(workload="long-doc-qa")
+        state.fill_defaults()
+        labels = [label for label, _ in state.summary_lines()]
+        assert "Queries per second" not in labels  # mrc item
+        assert "Number of requests" not in labels  # rp item
diff --git a/tests/cli/commands/bench/engine_bench/test_config.py b/tests/cli/commands/bench/engine_bench/test_config.py
new file mode 100644
index 0000000..9d487a9
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/test_config.py
@@ -0,0 +1,340 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for bench engine config module."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import argparse
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.config import (
+    EngineBenchConfig,
+    _find_model_meta,
+    auto_detect_model,
+    parse_args_to_config,
+    resolve_tokens_per_gb,
+)
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def base_namespace() -> argparse.Namespace:
+    """Namespace with all required fields for parse_args_to_config."""
+    return argparse.Namespace(
+        engine_url="http://localhost:8000",
+        lmcache_url=None,
+        model="test-model",
+        workload="long-doc-qa",
+        kv_cache_volume=100.0,
+        tokens_per_gb_kvcache=50000,
+        seed=42,
+        output_dir=".",
+        no_csv=False,
+        json=False,
+        quiet=False,
+        ignore_eos=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# EngineBenchConfig
+# ---------------------------------------------------------------------------
+
+
+class TestEngineBenchConfig:
+    def _make_config(self, **overrides) -> EngineBenchConfig:
+        defaults = dict(
+            engine_url="http://localhost:8000",
+            model="test-model",
+            workload="long-doc-qa",
+            kv_cache_volume_gb=100.0,
+            tokens_per_gb_kvcache=50000,
+            seed=42,
+            output_dir=".",
+            export_csv=True,
+            export_json=False,
+            quiet=False,
+        )
+        defaults.update(overrides)
+        return EngineBenchConfig(**defaults)  # type: ignore[arg-type]
+
+    def test_valid_construction(self) -> None:
+        cfg = self._make_config()
+        assert cfg.engine_url == "http://localhost:8000"
+        assert cfg.model == "test-model"
+        assert cfg.workload == "long-doc-qa"
+        assert cfg.tokens_per_gb_kvcache == 50000
+
+    def test_ignore_eos_defaults_false_and_overridable(self) -> None:
+        assert self._make_config().ignore_eos is False
+        assert self._make_config(ignore_eos=True).ignore_eos is True
+
+    def test_empty_engine_url(self) -> None:
+        with pytest.raises(ValueError, match="engine_url must be non-empty"):
+            self._make_config(engine_url="")
+
+    def test_invalid_kv_cache_volume(self) -> None:
+        with pytest.raises(ValueError, match="kv_cache_volume_gb must be positive"):
+            self._make_config(kv_cache_volume_gb=0)
+
+    def test_invalid_tokens_per_gb(self) -> None:
+        with pytest.raises(ValueError, match="tokens_per_gb_kvcache must be positive"):
+            self._make_config(tokens_per_gb_kvcache=0)
+
+
+# ---------------------------------------------------------------------------
+# auto_detect_model
+# ---------------------------------------------------------------------------
+
+
+class TestAutoDetectModel:
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config.OpenAI",
+    )
+    def test_returns_first_model_id(self, mock_openai_cls) -> None:
+        mock_model = MagicMock()
+        mock_model.id = "Qwen/Qwen3-14B"
+        mock_client = MagicMock()
+        mock_client.models.list.return_value = MagicMock(data=[mock_model])
+        mock_openai_cls.return_value = mock_client
+
+        result = auto_detect_model("http://localhost:8000")
+        assert result == "Qwen/Qwen3-14B"
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config.OpenAI",
+    )
+    def test_empty_data_raises(self, mock_openai_cls) -> None:
+        mock_client = MagicMock()
+        mock_client.models.list.return_value = MagicMock(data=[])
+        mock_openai_cls.return_value = mock_client
+
+        with pytest.raises(RuntimeError, match="No models returned"):
+            auto_detect_model("http://localhost:8000")
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config.OpenAI",
+    )
+    def test_connection_error_raises(self, mock_openai_cls) -> None:
+        mock_openai_cls.side_effect = ConnectionError("refused")
+
+        with pytest.raises(RuntimeError, match="Failed to fetch models"):
+            auto_detect_model("http://localhost:8000")
+
+
+# ---------------------------------------------------------------------------
+# parse_args_to_config
+# ---------------------------------------------------------------------------
+
+
+class TestParseArgsToConfig:
+    def test_basic_parsing(self, base_namespace) -> None:
+        cfg = parse_args_to_config(base_namespace)
+        assert cfg.engine_url == "http://localhost:8000"
+        assert cfg.model == "test-model"
+        assert cfg.workload == "long-doc-qa"
+        assert cfg.kv_cache_volume_gb == 100.0
+        assert cfg.seed == 42
+        assert cfg.export_csv is True
+        assert cfg.export_json is False
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config.auto_detect_model",
+        return_value="auto-detected-model",
+    )
+    def test_model_auto_detect(self, mock_auto_detect, base_namespace) -> None:
+        base_namespace.model = None
+        cfg = parse_args_to_config(base_namespace)
+        assert cfg.model == "auto-detected-model"
+        mock_auto_detect.assert_called_once_with("http://localhost:8000")
+
+    def test_no_tokens_per_gb_no_lmcache_url_raises(
+        self,
+        base_namespace,
+    ) -> None:
+        base_namespace.tokens_per_gb_kvcache = None
+        base_namespace.lmcache_url = None
+        with pytest.raises(ValueError, match="--tokens-per-gb-kvcache"):
+            parse_args_to_config(base_namespace)
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config.resolve_tokens_per_gb",
+        return_value=6553,
+    )
+    def test_lmcache_url_resolves_tokens_per_gb(
+        self,
+        mock_resolve,
+        base_namespace,
+    ) -> None:
+        base_namespace.tokens_per_gb_kvcache = None
+        base_namespace.lmcache_url = "http://localhost:8080"
+        cfg = parse_args_to_config(base_namespace)
+        assert cfg.tokens_per_gb_kvcache == 6553
+        mock_resolve.assert_called_once_with(
+            "http://localhost:8080",
+            "test-model",
+        )
+
+    def test_export_flags(self, base_namespace) -> None:
+        base_namespace.no_csv = True
+        base_namespace.json = True
+        cfg = parse_args_to_config(base_namespace)
+        assert cfg.export_csv is False
+        assert cfg.export_json is True
+
+
+# ---------------------------------------------------------------------------
+# _find_model_meta
+# ---------------------------------------------------------------------------
+
+
+class TestFindModelMeta:
+    def _gpu_meta(self) -> dict:
+        return {
+            "gpu_0": {
+                "model_name": "Qwen/Qwen3-14B",
+                "world_size": 1,
+                "kv_cache_layout": {"cache_size_per_token": 163840},
+            },
+            "gpu_1": {
+                "model_name": "meta-llama/Llama-3.1-70B",
+                "world_size": 4,
+                "kv_cache_layout": {"cache_size_per_token": 327680},
+            },
+        }
+
+    def test_finds_matching_model(self) -> None:
+        meta = _find_model_meta(self._gpu_meta(), "Qwen/Qwen3-14B")
+        assert meta["model_name"] == "Qwen/Qwen3-14B"
+
+    def test_finds_second_model(self) -> None:
+        meta = _find_model_meta(
+            self._gpu_meta(),
+            "meta-llama/Llama-3.1-70B",
+        )
+        assert meta["world_size"] == 4
+
+    def test_missing_model_raises(self) -> None:
+        with pytest.raises(RuntimeError, match="not found"):
+            _find_model_meta(self._gpu_meta(), "nonexistent-model")
+
+    def test_error_lists_available(self) -> None:
+        with pytest.raises(RuntimeError, match="Qwen/Qwen3-14B"):
+            _find_model_meta(self._gpu_meta(), "nonexistent")
+
+
+# ---------------------------------------------------------------------------
+# resolve_tokens_per_gb
+# ---------------------------------------------------------------------------
+
+
+class TestResolveTokensPerGb:
+    def _status_response(
+        self,
+        cache_size_per_token: int = 163840,
+        world_size: int = 1,
+        model_name: str = "Qwen/Qwen3-14B",
+    ) -> dict:
+        return {
+            "cache_context_meta": {
+                "gpu_0": {
+                    "model_name": model_name,
+                    "world_size": world_size,
+                    "kv_cache_layout": {
+                        "num_layers": 40,
+                        "hidden_dim_size": 1024,
+                        "dtype": "torch.bfloat16",
+                        "cache_size_per_token": cache_size_per_token,
+                    },
+                },
+            },
+        }
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config._fetch_lmcache_status",
+    )
+    def test_basic_calculation(self, mock_fetch) -> None:
+        # 163840 bytes/token, world_size=1
+        # 1 GB = 1073741824 bytes
+        # 1073741824 // 163840 = 6553
+        mock_fetch.return_value = self._status_response(
+            cache_size_per_token=163840,
+            world_size=1,
+        )
+        result = resolve_tokens_per_gb(
+            "http://localhost:8080",
+            "Qwen/Qwen3-14B",
+        )
+        assert result == 6553
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config._fetch_lmcache_status",
+    )
+    def test_world_size_multiplier(self, mock_fetch) -> None:
+        # 163840 bytes/token (rank-local), world_size=4
+        # global = 163840 * 4 = 655360
+        # 1073741824 // 655360 = 1638
+        mock_fetch.return_value = self._status_response(
+            cache_size_per_token=163840,
+            world_size=4,
+        )
+        result = resolve_tokens_per_gb(
+            "http://localhost:8080",
+            "Qwen/Qwen3-14B",
+        )
+        assert result == 1638
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config._fetch_lmcache_status",
+    )
+    def test_no_gpu_meta_raises(self, mock_fetch) -> None:
+        mock_fetch.return_value = {"cache_context_meta": {}}
+        with pytest.raises(RuntimeError, match="No model info"):
+            resolve_tokens_per_gb(
+                "http://localhost:8080",
+                "Qwen/Qwen3-14B",
+            )
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config._fetch_lmcache_status",
+    )
+    def test_model_not_found_raises(self, mock_fetch) -> None:
+        mock_fetch.return_value = self._status_response()
+        with pytest.raises(RuntimeError, match="not found"):
+            resolve_tokens_per_gb(
+                "http://localhost:8080",
+                "nonexistent-model",
+            )
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config._fetch_lmcache_status",
+    )
+    def test_no_cache_size_raises(self, mock_fetch) -> None:
+        data = self._status_response()
+        del data["cache_context_meta"]["gpu_0"]["kv_cache_layout"][
+            "cache_size_per_token"
+        ]
+        mock_fetch.return_value = data
+        with pytest.raises(RuntimeError, match="cache_size_per_token"):
+            resolve_tokens_per_gb(
+                "http://localhost:8080",
+                "Qwen/Qwen3-14B",
+            )
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config._fetch_lmcache_status",
+    )
+    def test_no_layout_raises(self, mock_fetch) -> None:
+        data = self._status_response()
+        del data["cache_context_meta"]["gpu_0"]["kv_cache_layout"]
+        mock_fetch.return_value = data
+        with pytest.raises(RuntimeError, match="kv_cache_layout"):
+            resolve_tokens_per_gb(
+                "http://localhost:8080",
+                "Qwen/Qwen3-14B",
+            )
diff --git a/tests/cli/commands/bench/engine_bench/test_progress.py b/tests/cli/commands/bench/engine_bench/test_progress.py
new file mode 100644
index 0000000..4f5b63e
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/test_progress.py
@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for bench engine progress monitor."""
+
+# Standard
+import io
+import sys
+import threading
+import time
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.progress import (
+    ProgressMonitor,
+)
+from lmcache.cli.commands.bench.engine_bench.stats import (
+    RequestResult,
+    StatsCollector,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_collector() -> StatsCollector:
+    return StatsCollector()
+
+
+def _make_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.3,
+        request_latency=2.0,
+        num_input_tokens=10000,
+        num_output_tokens=128,
+        decode_speed=48.0,
+        submit_time=now,
+        first_token_time=now + 0.3,
+        finish_time=now + 2.0,
+        error="",
+    )
+
+
+# ---------------------------------------------------------------------------
+# State tracking
+# ---------------------------------------------------------------------------
+
+
+class TestProgressMonitorState:
+    def test_initial_state(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        assert m._in_flight == 0
+        assert m._log_messages == []
+
+    def test_in_flight_tracking(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        m.on_request_sent("r0")
+        m.on_request_sent("r1")
+        m.on_request_sent("r2")
+        assert m._in_flight == 3
+        m.on_request_finished("r0", True)
+        m.on_request_finished("r1", False)
+        assert m._in_flight == 1
+
+    def test_on_request_finished_decrements_to_zero(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        m.on_request_sent("r0")
+        m.on_request_finished("r0", True)
+        assert m._in_flight == 0
+
+    def test_on_request_finished_does_not_go_negative(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        m.on_request_finished("r0", True)
+        assert m._in_flight == 0
+
+    def test_multiple_log_messages(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        m.log_message("first")
+        m.log_message("second")
+        m.log_message("third")
+        assert m._log_messages == ["first", "second", "third"]
+
+    def test_log_message_max_lines(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        for i in range(10):
+            m.log_message(f"msg_{i}")
+        assert len(m._log_messages) == ProgressMonitor.LOG_LINES
+        assert m._log_messages[0] == "msg_5"
+        assert m._log_messages[-1] == "msg_9"
+
+
+# ---------------------------------------------------------------------------
+# Quiet mode
+# ---------------------------------------------------------------------------
+
+
+class TestProgressMonitorQuiet:
+    def test_quiet_no_thread(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        m.start()
+        assert m._thread is None
+
+    def test_quiet_stop_safe(self) -> None:
+        m = ProgressMonitor(_make_collector(), quiet=True)
+        m.start()
+        m.stop()  # should not raise
+
+
+# ---------------------------------------------------------------------------
+# Thread lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TestProgressMonitorThread:
+    def test_start_stop_lifecycle(self) -> None:
+        collector = _make_collector()
+        # Redirect stdout to suppress ANSI output
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            m = ProgressMonitor(collector)
+            m.start()
+            assert m._thread is not None
+            assert m._thread.is_alive()
+            time.sleep(0.1)
+            m.stop()
+            assert not m._thread.is_alive()
+        finally:
+            sys.stdout = old_stdout
+
+    def test_draw_calls_stats_collector(self) -> None:
+        collector = _make_collector()
+        call_count = 0
+        original_get = collector.get_current_stats
+
+        def counting_get():
+            nonlocal call_count
+            call_count += 1
+            return original_get()
+
+        collector.get_current_stats = counting_get  # type: ignore[assignment]
+
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            m = ProgressMonitor(collector)
+            m.start()
+            time.sleep(1.5)  # allow at least one tick
+            m.stop()
+            assert call_count >= 1
+        finally:
+            sys.stdout = old_stdout
+
+    def test_stop_without_start(self) -> None:
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            m = ProgressMonitor(_make_collector())
+            m.stop()  # should not raise
+        finally:
+            sys.stdout = old_stdout
+
+
+# ---------------------------------------------------------------------------
+# Thread safety
+# ---------------------------------------------------------------------------
+
+
+class TestProgressMonitorThreadSafety:
+    def test_concurrent_send_finish_log(self) -> None:
+        collector = _make_collector()
+
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            m = ProgressMonitor(collector)
+            m.start()
+
+            num_threads = 10
+            ops_per_thread = 50
+            barrier = threading.Barrier(num_threads)
+
+            def worker(thread_id: int) -> None:
+                barrier.wait()
+                for i in range(ops_per_thread):
+                    rid = f"t{thread_id}_r{i}"
+                    m.on_request_sent(rid)
+                    m.log_message(f"sent {rid}")
+                    m.on_request_finished(rid, True)
+
+            threads = [
+                threading.Thread(target=worker, args=(t,)) for t in range(num_threads)
+            ]
+            for t in threads:
+                t.start()
+            for t in threads:
+                t.join()
+
+            m.stop()
+            # All sends matched by finishes → in-flight == 0
+            assert m._in_flight == 0
+        finally:
+            sys.stdout = old_stdout
diff --git a/tests/cli/commands/bench/engine_bench/test_request_sender.py b/tests/cli/commands/bench/engine_bench/test_request_sender.py
new file mode 100644
index 0000000..e6c18e5
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/test_request_sender.py
@@ -0,0 +1,513 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for bench engine request sender."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock, patch
+import os
+
+# Third Party
+from openai.types import Completion, CompletionUsage
+from openai.types.chat import ChatCompletionChunk
+from openai.types.chat.chat_completion_chunk import Choice, ChoiceDelta
+from openai.types.completion_choice import CompletionChoice
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.request_sender import (
+    RequestSender,
+    _extract_content,
+    _normalize_url,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_chat_chunk(
+    content: str = "",
+    usage: CompletionUsage = None,
+) -> ChatCompletionChunk:
+    """Build a minimal ``ChatCompletionChunk``."""
+    choices = []
+    if content:
+        choices.append(
+            Choice(
+                delta=ChoiceDelta(content=content),
+                index=0,
+            )
+        )
+    return ChatCompletionChunk(
+        id="chunk-1",
+        choices=choices,
+        created=0,
+        model="test-model",
+        object="chat.completion.chunk",
+        usage=usage,
+    )
+
+
+def _make_completions_chunk(
+    text: str = "",
+    usage: CompletionUsage = None,
+) -> Completion:
+    """Build a minimal ``Completion`` chunk."""
+    choices = []
+    if text:
+        choices.append(
+            CompletionChoice(
+                text=text,
+                index=0,
+                finish_reason="stop",
+            )
+        )
+    return Completion(
+        id="cmpl-1",
+        choices=choices,
+        created=0,
+        model="test-model",
+        object="text_completion",
+        usage=usage,
+    )
+
+
+async def _fake_stream(chunks):
+    """Async generator yielding chunks."""
+    for chunk in chunks:
+        yield chunk
+
+
+async def _error_stream(chunks, error_after: int = 1):
+    """Async generator that raises after yielding some chunks."""
+    for i, chunk in enumerate(chunks):
+        if i >= error_after:
+            raise RuntimeError("stream interrupted")
+        yield chunk
+
+
+def _usage(prompt: int = 100, completion: int = 2) -> CompletionUsage:
+    return CompletionUsage(
+        prompt_tokens=prompt,
+        completion_tokens=completion,
+        total_tokens=prompt + completion,
+    )
+
+
+# ---------------------------------------------------------------------------
+# _extract_content
+# ---------------------------------------------------------------------------
+
+
+class TestExtractContent:
+    def test_chat_content(self) -> None:
+        chunk = _make_chat_chunk(content="hello")
+        assert _extract_content(chunk, completions_mode=False) == "hello"
+
+    def test_chat_no_choices(self) -> None:
+        chunk = _make_chat_chunk()  # no content → empty choices
+        assert _extract_content(chunk, completions_mode=False) == ""
+
+    def test_chat_none_content(self) -> None:
+        chunk = ChatCompletionChunk(
+            id="c1",
+            choices=[Choice(delta=ChoiceDelta(content=None), index=0)],
+            created=0,
+            model="m",
+            object="chat.completion.chunk",
+        )
+        assert _extract_content(chunk, completions_mode=False) == ""
+
+    def test_completions_text(self) -> None:
+        chunk = _make_completions_chunk(text="world")
+        assert _extract_content(chunk, completions_mode=True) == "world"
+
+    def test_completions_no_choices(self) -> None:
+        chunk = _make_completions_chunk()  # no text → empty choices
+        assert _extract_content(chunk, completions_mode=True) == ""
+
+
+# ---------------------------------------------------------------------------
+# _normalize_url
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeUrl:
+    def test_appends_v1(self) -> None:
+        assert _normalize_url("http://localhost:8000") == ("http://localhost:8000/v1")
+
+    def test_keeps_existing_v1(self) -> None:
+        assert _normalize_url("http://localhost:8000/v1") == (
+            "http://localhost:8000/v1"
+        )
+
+    def test_strips_trailing_slash(self) -> None:
+        assert _normalize_url("http://localhost:8000/") == ("http://localhost:8000/v1")
+
+
+# ---------------------------------------------------------------------------
+# RequestSender — construction
+# ---------------------------------------------------------------------------
+
+
+class TestRequestSenderInit:
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    def test_default_api_key(self, mock_openai_cls) -> None:
+        env = os.environ.copy()
+        env.pop("OPENAI_API_KEY", None)
+        with patch.dict(os.environ, env, clear=True):
+            RequestSender("http://localhost:8000", "test-model")
+        _, kwargs = mock_openai_cls.call_args
+        assert kwargs["api_key"] == "sk-dummy"
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    def test_env_api_key(self, mock_openai_cls) -> None:
+        with patch.dict(os.environ, {"OPENAI_API_KEY": "sk-test"}):
+            RequestSender("http://localhost:8000", "test-model")
+        _, kwargs = mock_openai_cls.call_args
+        assert kwargs["api_key"] == "sk-test"
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    def test_url_normalization(self, mock_openai_cls) -> None:
+        RequestSender("http://localhost:8000", "test-model")
+        _, kwargs = mock_openai_cls.call_args
+        assert kwargs["base_url"] == "http://localhost:8000/v1"
+
+
+# ---------------------------------------------------------------------------
+# RequestSender — send_request (chat mode)
+# ---------------------------------------------------------------------------
+
+
+class TestRequestSenderSendRequest:
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_successful_chat_request(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_chat_chunk(content="Hello"),
+            _make_chat_chunk(content=" world"),
+            _make_chat_chunk(usage=_usage(prompt=100, completion=2)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        result = await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert result.successful is True
+        assert result.error == ""
+        assert result.ttft > 0
+        assert result.request_latency > 0
+        assert result.num_input_tokens == 100
+        assert result.num_output_tokens == 2
+        assert result.decode_speed > 0
+        assert result.submit_time < result.first_token_time < result.finish_time
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_ignore_eos_adds_extra_body(self, mock_openai_cls) -> None:
+        chunks = [_make_chat_chunk(usage=_usage(prompt=10, completion=1))]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model", ignore_eos=True)
+        await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        _, kwargs = mock_client.chat.completions.create.call_args
+        assert kwargs["extra_body"] == {"ignore_eos": True}
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_default_omits_extra_body(self, mock_openai_cls) -> None:
+        chunks = [_make_chat_chunk(usage=_usage(prompt=10, completion=1))]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        _, kwargs = mock_client.chat.completions.create.call_args
+        assert "extra_body" not in kwargs
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_usage_extraction(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_chat_chunk(content="tok"),
+            _make_chat_chunk(usage=_usage(prompt=500, completion=20)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        result = await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert result.num_input_tokens == 500
+        assert result.num_output_tokens == 20
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_failed_request_on_exception(self, mock_openai_cls) -> None:
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            side_effect=ConnectionError("refused")
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        result = await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert result.successful is False
+        assert result.ttft == -1.0
+        assert "refused" in result.error
+        assert result.num_input_tokens == 0
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_exception_during_streaming(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_chat_chunk(content="Hello"),
+            _make_chat_chunk(content=" world"),  # won't be reached
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_error_stream(chunks, error_after=1)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        result = await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert result.successful is False
+        assert "stream interrupted" in result.error
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_no_content_chunks(self, mock_openai_cls) -> None:
+        # Only usage chunk, no content
+        chunks = [
+            _make_chat_chunk(usage=_usage(prompt=100, completion=0)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        result = await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert result.successful is False
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_callbacks_called_on_success(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_chat_chunk(content="Hello"),
+            _make_chat_chunk(content=" world"),
+            _make_chat_chunk(usage=_usage(prompt=100, completion=2)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        callback_args: list[tuple] = []
+
+        def on_finished(result, text):
+            callback_args.append((result, text))
+
+        sender = RequestSender(
+            "http://localhost:8000",
+            "test-model",
+            on_finished=[on_finished],
+        )
+        result = await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert len(callback_args) == 1
+        cb_result, cb_text = callback_args[0]
+        assert cb_result is result
+        assert cb_result.successful is True
+        assert cb_text == "Hello world"
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_callbacks_called_on_failure(self, mock_openai_cls) -> None:
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            side_effect=ConnectionError("refused")
+        )
+
+        callback_args: list[tuple] = []
+
+        def on_finished(result, text):
+            callback_args.append((result, text))
+
+        sender = RequestSender(
+            "http://localhost:8000",
+            "test-model",
+            on_finished=[on_finished],
+        )
+        await sender.send_request("req_0", [{"role": "user", "content": "Hi"}])
+
+        assert len(callback_args) == 1
+        cb_result, cb_text = callback_args[0]
+        assert cb_result.successful is False
+        assert cb_text == ""
+
+
+# ---------------------------------------------------------------------------
+# RequestSender — completions mode
+# ---------------------------------------------------------------------------
+
+
+class TestRequestSenderCompletionsMode:
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_uses_completions_api(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_completions_chunk(text="Hello"),
+            _make_completions_chunk(usage=_usage(prompt=50, completion=1)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.completions.create = AsyncMock(return_value=_fake_stream(chunks))
+
+        sender = RequestSender(
+            "http://localhost:8000", "test-model", completions_mode=True
+        )
+        result = await sender.send_request(
+            "req_0", [{"role": "user", "content": "Test prompt"}]
+        )
+
+        # Verify completions API was called
+        mock_client.completions.create.assert_called_once()
+        call_kwargs = mock_client.completions.create.call_args[1]
+        assert call_kwargs["prompt"] == "Test prompt"
+
+        # Chat API should NOT have been called
+        mock_client.chat.completions.create.assert_not_called()
+
+        assert result.successful is True
+
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_completions_content_extraction(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_completions_chunk(text="Hello"),
+            _make_completions_chunk(text=" there"),
+            _make_completions_chunk(usage=_usage(prompt=50, completion=2)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.completions.create = AsyncMock(return_value=_fake_stream(chunks))
+
+        callback_args: list[tuple] = []
+
+        sender = RequestSender(
+            "http://localhost:8000",
+            "test-model",
+            completions_mode=True,
+            on_finished=[lambda r, t: callback_args.append((r, t))],
+        )
+        result = await sender.send_request(
+            "req_0", [{"role": "user", "content": "Test"}]
+        )
+
+        assert result.successful is True
+        assert result.num_input_tokens == 50
+        assert result.num_output_tokens == 2
+        # Verify response text via callback
+        assert callback_args[0][1] == "Hello there"
+
+
+# ---------------------------------------------------------------------------
+# RequestSender — warmup
+# ---------------------------------------------------------------------------
+
+
+class TestRequestSenderWarmup:
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_warmup_defaults_max_tokens_1(self, mock_openai_cls) -> None:
+        chunks = [
+            _make_chat_chunk(content="X"),
+            _make_chat_chunk(usage=_usage(prompt=100, completion=1)),
+        ]
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            return_value=_fake_stream(chunks)
+        )
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        await sender.send_warmup_request(
+            "warmup_0", [{"role": "user", "content": "Hi"}]
+        )
+
+        call_kwargs = mock_client.chat.completions.create.call_args[1]
+        assert call_kwargs["max_tokens"] == 1
+
+
+# ---------------------------------------------------------------------------
+# RequestSender — close
+# ---------------------------------------------------------------------------
+
+
+class TestRequestSenderClose:
+    @pytest.mark.asyncio
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    async def test_close_calls_client_close(self, mock_openai_cls) -> None:
+        mock_client = MagicMock()
+        mock_client.close = AsyncMock()
+        mock_openai_cls.return_value = mock_client
+
+        sender = RequestSender("http://localhost:8000", "test-model")
+        await sender.close()
+
+        mock_client.close.assert_called_once()
diff --git a/tests/cli/commands/bench/engine_bench/test_stats.py b/tests/cli/commands/bench/engine_bench/test_stats.py
new file mode 100644
index 0000000..5dac6f0
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/test_stats.py
@@ -0,0 +1,407 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for bench engine stats module."""
+
+# Standard
+import csv
+import json
+import threading
+import time
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.config import EngineBenchConfig
+from lmcache.cli.commands.bench.engine_bench.stats import (
+    AggregatedStats,
+    FinalStats,
+    RequestResult,
+    StatsCollector,
+    _percentile,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_result(
+    request_id: str = "req_0",
+    successful: bool = True,
+    ttft: float = 0.3,
+    request_latency: float = 2.0,
+    num_input_tokens: int = 10000,
+    num_output_tokens: int = 128,
+    decode_speed: float = 48.0,
+    error: str = "",
+) -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=successful,
+        ttft=ttft,
+        request_latency=request_latency,
+        num_input_tokens=num_input_tokens,
+        num_output_tokens=num_output_tokens,
+        decode_speed=decode_speed,
+        submit_time=now,
+        first_token_time=now + ttft,
+        finish_time=now + request_latency,
+        error=error,
+    )
+
+
+def _make_config() -> EngineBenchConfig:
+    return EngineBenchConfig(
+        engine_url="http://localhost:8000",
+        model="test-model",
+        workload="long-doc-qa",
+        kv_cache_volume_gb=100.0,
+        tokens_per_gb_kvcache=50000,
+        seed=42,
+        output_dir=".",
+        export_csv=True,
+        export_json=True,
+        quiet=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# _percentile
+# ---------------------------------------------------------------------------
+
+
+class TestPercentile:
+    def test_empty_list(self) -> None:
+        assert _percentile([], 50) == 0.0
+
+    def test_single_element(self) -> None:
+        assert _percentile([5.0], 50) == 5.0
+
+    def test_p50_even_count(self) -> None:
+        # k = (4-1) * 50/100 = 1.5 → lerp(2, 3, 0.5) = 2.5
+        assert _percentile([1.0, 2.0, 3.0, 4.0], 50) == 2.5
+
+    def test_p50_odd_count(self) -> None:
+        # k = (5-1) * 50/100 = 2.0 → exact index 2 = 3.0
+        assert _percentile([1.0, 2.0, 3.0, 4.0, 5.0], 50) == 3.0
+
+    def test_p90(self) -> None:
+        data = list(range(1, 101))  # 1..100
+        # k = 99 * 90/100 = 89.1 → lerp(90, 91, 0.1) = 90.1
+        result = _percentile([float(x) for x in data], 90)
+        assert abs(result - 90.1) < 1e-9
+
+    def test_p0_and_p100(self) -> None:
+        data = [1.0, 2.0, 3.0]
+        assert _percentile(data, 0) == 1.0
+        assert _percentile(data, 100) == 3.0
+
+
+# ---------------------------------------------------------------------------
+# RequestResult
+# ---------------------------------------------------------------------------
+
+
+class TestRequestResult:
+    def test_construction(self) -> None:
+        r = _make_result(request_id="r1", ttft=0.5)
+        assert r.request_id == "r1"
+        assert r.ttft == 0.5
+        assert r.successful is True
+        assert r.error == ""
+
+    def test_failed_result(self) -> None:
+        r = _make_result(successful=False, error="timeout")
+        assert r.successful is False
+        assert r.error == "timeout"
+
+
+# ---------------------------------------------------------------------------
+# StatsCollector — basic operations
+# ---------------------------------------------------------------------------
+
+
+class TestStatsCollector:
+    def test_empty_stats(self) -> None:
+        c = StatsCollector()
+        s = c.get_current_stats()
+        assert s.total_requests == 0
+        assert s.successful_requests == 0
+        assert s.failed_requests == 0
+        assert s.mean_ttft_ms == 0.0
+        assert s.mean_decode_speed == 0.0
+
+    def test_single_success(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(
+            _make_result(ttft=0.3, decode_speed=48.0, request_latency=2.0)
+        )
+        s = c.get_current_stats()
+        assert s.total_requests == 1
+        assert s.successful_requests == 1
+        assert abs(s.mean_ttft_ms - 300.0) < 1e-9
+        assert abs(s.mean_decode_speed - 48.0) < 1e-9
+        assert abs(s.mean_request_latency_ms - 2000.0) < 1e-9
+
+    def test_single_failure(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(successful=False, error="fail"))
+        s = c.get_current_stats()
+        assert s.total_requests == 1
+        assert s.failed_requests == 1
+        # Means stay 0 because no successful requests
+        assert s.mean_ttft_ms == 0.0
+
+    def test_multiple_results(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(ttft=0.2, decode_speed=40.0))
+        c.on_request_finished(_make_result(ttft=0.4, decode_speed=60.0))
+        s = c.get_current_stats()
+        assert s.total_requests == 2
+        assert abs(s.mean_ttft_ms - 300.0) < 1e-9  # (200+400)/2
+        assert abs(s.mean_decode_speed - 50.0) < 1e-9  # (40+60)/2
+
+    def test_mixed_success_failure(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(ttft=0.2, decode_speed=40.0))
+        c.on_request_finished(_make_result(ttft=0.4, decode_speed=60.0))
+        c.on_request_finished(_make_result(successful=False, error="err"))
+        s = c.get_current_stats()
+        assert s.total_requests == 3
+        assert s.successful_requests == 2
+        assert s.failed_requests == 1
+        # Means over successful only
+        assert abs(s.mean_ttft_ms - 300.0) < 1e-9
+
+    def test_get_all_results_returns_copy(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(request_id="r1"))
+        results = c.get_all_results()
+        results.clear()
+        assert len(c.get_all_results()) == 1
+
+
+# ---------------------------------------------------------------------------
+# StatsCollector — final stats
+# ---------------------------------------------------------------------------
+
+
+class TestStatsCollectorFinalStats:
+    def test_percentiles_single_result(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(ttft=0.3))
+        f = c.get_final_stats()
+        assert isinstance(f, FinalStats)
+        assert isinstance(f, AggregatedStats)
+        assert abs(f.p50_ttft_ms - 300.0) < 1e-9
+        assert abs(f.p90_ttft_ms - 300.0) < 1e-9
+        assert abs(f.p99_ttft_ms - 300.0) < 1e-9
+
+    def test_percentiles_multiple(self) -> None:
+        c = StatsCollector()
+        # 10 results with TTFT 0.1, 0.2, ..., 1.0
+        for i in range(1, 11):
+            c.on_request_finished(
+                _make_result(
+                    request_id=f"r{i}",
+                    ttft=i * 0.1,
+                    decode_speed=float(i * 10),
+                    request_latency=float(i),
+                )
+            )
+        f = c.get_final_stats()
+        # P50 TTFT: k = 9 * 50/100 = 4.5 → lerp(500, 600, 0.5) = 550
+        assert abs(f.p50_ttft_ms - 550.0) < 1e-6
+
+    def test_final_stats_no_successful(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(successful=False, error="err"))
+        f = c.get_final_stats()
+        assert f.total_requests == 1
+        assert f.failed_requests == 1
+        assert f.p50_ttft_ms == 0.0
+        assert f.p90_ttft_ms == 0.0
+        assert f.p99_ttft_ms == 0.0
+
+
+# ---------------------------------------------------------------------------
+# StatsCollector — thread safety
+# ---------------------------------------------------------------------------
+
+
+class TestStatsCollectorThreadSafety:
+    def test_concurrent_writes(self) -> None:
+        c = StatsCollector()
+        num_threads = 10
+        results_per_thread = 100
+        barrier = threading.Barrier(num_threads)
+
+        def writer(thread_id: int) -> None:
+            barrier.wait()
+            for i in range(results_per_thread):
+                c.on_request_finished(_make_result(request_id=f"t{thread_id}_r{i}"))
+
+        threads = [
+            threading.Thread(target=writer, args=(t,)) for t in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        s = c.get_current_stats()
+        assert s.total_requests == num_threads * results_per_thread
+
+    def test_concurrent_read_write(self) -> None:
+        c = StatsCollector()
+        num_writes = 200
+        read_count = 0
+        stop_event = threading.Event()
+        reader_started = threading.Event()
+
+        def writer() -> None:
+            reader_started.wait()
+            for i in range(num_writes):
+                c.on_request_finished(_make_result(request_id=f"r{i}"))
+            stop_event.set()
+
+        def reader() -> None:
+            nonlocal read_count
+            reader_started.set()
+            while not stop_event.is_set():
+                c.get_current_stats()
+                read_count += 1
+
+        w = threading.Thread(target=writer)
+        r = threading.Thread(target=reader)
+        r.start()
+        w.start()
+        w.join()
+        r.join()
+
+        s = c.get_current_stats()
+        assert s.total_requests == num_writes
+        assert read_count > 0
+
+
+# ---------------------------------------------------------------------------
+# StatsCollector — export
+# ---------------------------------------------------------------------------
+
+
+class TestStatsCollectorExport:
+    def test_export_csv(self, tmp_path) -> None:
+        c = StatsCollector()
+        for i in range(3):
+            c.on_request_finished(_make_result(request_id=f"r{i}"))
+        path = str(tmp_path / "results.csv")
+        c.export_csv(path)
+
+        with open(path) as f:
+            reader = csv.DictReader(f)
+            rows = list(reader)
+        assert len(rows) == 3
+        assert rows[0]["request_id"] == "r0"
+        assert "ttft" in rows[0]
+        assert "decode_speed" in rows[0]
+
+    def test_export_csv_empty(self, tmp_path) -> None:
+        c = StatsCollector()
+        path = str(tmp_path / "empty.csv")
+        c.export_csv(path)
+
+        with open(path) as f:
+            reader = csv.DictReader(f)
+            rows = list(reader)
+        assert len(rows) == 0
+
+    def test_export_json(self, tmp_path) -> None:
+        c = StatsCollector()
+        for i in range(2):
+            c.on_request_finished(_make_result(request_id=f"r{i}"))
+        path = str(tmp_path / "summary.json")
+        c.export_json(path, _make_config())
+
+        with open(path) as f:
+            data = json.load(f)
+
+        assert "config" in data
+        assert "results" in data
+        assert data["config"]["engine_url"] == "http://localhost:8000"
+        assert "p50_ttft_ms" in data["results"]
+        assert "p90_ttft_ms" in data["results"]
+        assert data["results"]["total_requests"] == 2
+
+
+# ---------------------------------------------------------------------------
+# StatsCollector — reset
+# ---------------------------------------------------------------------------
+
+
+class TestStatsCollectorReset:
+    def test_reset_clears_results(self) -> None:
+        c = StatsCollector()
+        for i in range(3):
+            c.on_request_finished(_make_result(request_id=f"r{i}"))
+        assert c.get_current_stats().total_requests == 3
+        c.reset()
+        assert c.get_current_stats().total_requests == 0
+        assert len(c.get_all_results()) == 0
+
+    def test_reset_resets_accumulators(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(ttft=0.3, decode_speed=48.0))
+        c.reset()
+        s = c.get_current_stats()
+        assert s.mean_ttft_ms == 0.0
+        assert s.mean_decode_speed == 0.0
+        assert s.total_input_tokens == 0
+        assert s.total_output_tokens == 0
+
+    def test_reset_restarts_timer(self) -> None:
+        c = StatsCollector()
+        time.sleep(0.05)
+        c.reset()
+        s = c.get_current_stats()
+        assert s.elapsed_time < 0.1
+
+    def test_accumulate_after_reset(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(request_id="r0"))
+        c.on_request_finished(_make_result(request_id="r1"))
+        c.reset()
+        c.on_request_finished(
+            _make_result(request_id="r2", ttft=0.5, decode_speed=30.0)
+        )
+        s = c.get_current_stats()
+        assert s.total_requests == 1
+        assert abs(s.mean_ttft_ms - 500.0) < 1e-9
+        assert abs(s.mean_decode_speed - 30.0) < 1e-9
+
+    def test_final_stats_after_reset(self) -> None:
+        c = StatsCollector()
+        c.on_request_finished(_make_result(request_id="r0", ttft=0.1))
+        c.on_request_finished(_make_result(request_id="r1", ttft=0.9))
+        c.reset()
+        c.on_request_finished(_make_result(request_id="r2", ttft=0.5))
+        f = c.get_final_stats()
+        assert f.total_requests == 1
+        assert abs(f.p50_ttft_ms - 500.0) < 1e-9
+
+    def test_reset_thread_safe(self) -> None:
+        c = StatsCollector()
+        stop_event = threading.Event()
+        writer_started = threading.Event()
+
+        def writer() -> None:
+            writer_started.set()
+            while not stop_event.is_set():
+                c.on_request_finished(_make_result())
+
+        t = threading.Thread(target=writer)
+        t.start()
+        writer_started.wait()
+        # Reset while writer is running
+        for _ in range(10):
+            c.reset()
+        stop_event.set()
+        t.join()
+        # No crash — that's the assertion
diff --git a/tests/cli/commands/bench/engine_bench/workloads/__init__.py b/tests/cli/commands/bench/engine_bench/workloads/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_base_workload.py b/tests/cli/commands/bench/engine_bench/workloads/test_base_workload.py
new file mode 100644
index 0000000..6883468
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_base_workload.py
@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the BaseWorkload abstract class."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock
+import queue
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.cli.commands.bench.engine_bench.workloads.base import BaseWorkload
+
+# ---------------------------------------------------------------------------
+# Stub workload for testing
+# ---------------------------------------------------------------------------
+
+
+class StubWorkload(BaseWorkload):
+    """Minimal concrete workload for testing the base class."""
+
+    def __init__(self, request_sender, stats_collector, progress_monitor):
+        super().__init__(request_sender, stats_collector, progress_monitor)
+        self.warmup_called = False
+        self.step_calls: list[float] = []
+        self.finished_calls: list[tuple[str, str]] = []
+        self._step_returns: list[float] = []
+
+    def log_config(self) -> None:
+        pass
+
+    async def warmup(self) -> None:
+        self.warmup_called = True
+
+    async def step(self, time_offset: float) -> float:
+        self.step_calls.append(time_offset)
+        if self._step_returns:
+            return self._step_returns.pop(0)
+        return -1.0
+
+    def on_request_finished(self, request_id: str, output: str) -> None:
+        self.finished_calls.append((request_id, output))
+
+
+def _make_mock_result(request_id: str = "req_0") -> RequestResult:
+    return MagicMock(spec=RequestResult, request_id=request_id)
+
+
+def _make_stub(**kwargs) -> StubWorkload:
+    sender = MagicMock()
+    sender.close = AsyncMock()
+    collector = MagicMock()
+    monitor = MagicMock()
+    return StubWorkload(sender, collector, monitor, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Construction
+# ---------------------------------------------------------------------------
+
+
+class TestBaseWorkloadConstruction:
+    def test_stores_references(self) -> None:
+        sender = MagicMock()
+        collector = MagicMock()
+        monitor = MagicMock()
+        w = StubWorkload(sender, collector, monitor)
+        assert w._request_sender is sender
+        assert w._stats_collector is collector
+        assert w._progress_monitor is monitor
+        assert isinstance(w._finished_queue, queue.Queue)
+
+
+# ---------------------------------------------------------------------------
+# request_finished / drain
+# ---------------------------------------------------------------------------
+
+
+class TestBaseWorkloadRequestFinished:
+    def test_enqueues_to_queue(self) -> None:
+        w = _make_stub()
+        result = _make_mock_result("r1")
+        w.request_finished(result, "hello")
+        item = w._finished_queue.get_nowait()
+        assert item == ("r1", "hello")
+
+    def test_multiple_enqueues(self) -> None:
+        w = _make_stub()
+        for i in range(3):
+            w.request_finished(_make_mock_result(f"r{i}"), f"text_{i}")
+        assert w._finished_queue.qsize() == 3
+
+
+class TestBaseWorkloadDrainQueue:
+    def test_drain_empty_queue(self) -> None:
+        w = _make_stub()
+        w._drain_finished_queue()
+        assert w.finished_calls == []
+
+    def test_drain_calls_on_request_finished(self) -> None:
+        w = _make_stub()
+        w.request_finished(_make_mock_result("r0"), "text_0")
+        w.request_finished(_make_mock_result("r1"), "text_1")
+        w._drain_finished_queue()
+        assert w.finished_calls == [("r0", "text_0"), ("r1", "text_1")]
+
+    def test_drain_empties_queue(self) -> None:
+        w = _make_stub()
+        w.request_finished(_make_mock_result("r0"), "text")
+        w._drain_finished_queue()
+        assert w._finished_queue.empty()
+
+
+# ---------------------------------------------------------------------------
+# run loop
+# ---------------------------------------------------------------------------
+
+
+class TestBaseWorkloadRunLoop:
+    def test_run_calls_warmup(self) -> None:
+        w = _make_stub()
+        w.run()
+        assert w.warmup_called is True
+
+    def test_run_calls_stats_reset(self) -> None:
+        w = _make_stub()
+        w.run()
+        w._stats_collector.reset.assert_called_once()  # type: ignore[attr-defined]
+
+    def test_run_calls_step(self) -> None:
+        w = _make_stub()
+        w._step_returns = [0.0, -1.0]
+        w.run()
+        assert len(w.step_calls) == 2
+
+    def test_run_drains_queue_after_warmup(self) -> None:
+        class WarmupEnqueuer(StubWorkload):
+            async def warmup(self) -> None:
+                self.warmup_called = True
+                self.request_finished(_make_mock_result("warmup_0"), "warmup_text")
+
+        sender = MagicMock()
+        sender.close = AsyncMock()
+        collector = MagicMock()
+        monitor = MagicMock()
+        w = WarmupEnqueuer(sender, collector, monitor)
+        w.run()
+        # Warmup completion was drained (on_request_finished called)
+        assert ("warmup_0", "warmup_text") in w.finished_calls
+
+    def test_negative_step_stops_loop(self) -> None:
+        w = _make_stub()
+        # Default: step returns -1.0
+        w.run()
+        assert len(w.step_calls) == 1
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_create_workload.py b/tests/cli/commands/bench/engine_bench/workloads/test_create_workload.py
new file mode 100644
index 0000000..ed013a2
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_create_workload.py
@@ -0,0 +1,283 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the workload factory."""
+
+# Standard
+from unittest.mock import MagicMock
+import argparse
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.config import EngineBenchConfig
+from lmcache.cli.commands.bench.engine_bench.workloads import (
+    BaseWorkload,
+    create_workload,
+    validate_max_output_length_supported,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.long_doc_qa import (
+    LongDocQAWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.multi_round_chat import (
+    MultiRoundChatWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.prefix_suffix_tuner import (
+    PrefixSuffixTunerWorkload,
+)
+from lmcache.cli.commands.bench.engine_bench.workloads.random_prefill import (
+    RandomPrefillWorkload,
+)
+
+
+def _make_config(**overrides) -> EngineBenchConfig:
+    defaults = dict(
+        engine_url="http://localhost:8000",
+        model="test-model",
+        workload="long-doc-qa",
+        kv_cache_volume_gb=100.0,
+        tokens_per_gb_kvcache=50000,
+        seed=42,
+        output_dir=".",
+        export_csv=True,
+        export_json=False,
+        quiet=False,
+    )
+    defaults.update(overrides)
+    return EngineBenchConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_args(**overrides) -> argparse.Namespace:
+    defaults = dict(
+        # long-doc-qa defaults
+        ldqa_document_length=10000,
+        ldqa_query_per_document=2,
+        ldqa_shuffle_policy="random",
+        ldqa_num_inflight_requests=3,
+        ldqa_max_output_length=128,
+        # random-prefill defaults
+        rp_request_length=10000,
+        rp_num_requests=50,
+        # multi-round-chat defaults
+        mrc_shared_prompt_length=2000,
+        mrc_chat_history_length=10000,
+        mrc_user_input_length=50,
+        mrc_output_length=200,
+        mrc_qps=1.0,
+        mrc_duration=60.0,
+        # prefix-suffix-tuner defaults
+        psf_context_length=8000,
+        psf_prefix_ratio=0.8,
+        psf_thrash=20.0,
+    )
+    defaults.update(overrides)
+    return argparse.Namespace(**defaults)
+
+
+def _make_deps() -> tuple[MagicMock, MagicMock, MagicMock]:
+    sender = MagicMock()
+    collector = MagicMock()
+    monitor = MagicMock()
+    return sender, collector, monitor
+
+
+class TestValidateMaxOutputLengthSupported:
+    @pytest.mark.parametrize("workload", ["long-doc-qa", "multi-round-chat"])
+    def test_allowed_for_workloads_with_the_parameter(self, workload: str) -> None:
+        validate_max_output_length_supported(workload)
+
+    @pytest.mark.parametrize(
+        "workload",
+        ["long-doc-permutator", "random-prefill", "prefix-suffix-tuner"],
+    )
+    def test_rejected_for_workloads_without_the_parameter(self, workload: str) -> None:
+        with pytest.raises(ValueError, match="max output length cannot be specified"):
+            validate_max_output_length_supported(workload)
+
+
+class TestCreateWorkload:
+    def test_long_doc_qa(self) -> None:
+        config = _make_config(workload="long-doc-qa")
+        args = _make_args()
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, BaseWorkload)
+        assert isinstance(result, LongDocQAWorkload)
+        # 100 * 50000 / 10000 = 500
+        assert result._config.num_documents == 500
+
+    def test_long_doc_qa_custom_args(self) -> None:
+        config = _make_config(
+            workload="long-doc-qa",
+            kv_cache_volume_gb=10.0,
+            tokens_per_gb_kvcache=10000,
+        )
+        args = _make_args(
+            ldqa_document_length=5000,
+            ldqa_query_per_document=4,
+            ldqa_shuffle_policy="tile",
+            ldqa_max_output_length=1024,
+        )
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, LongDocQAWorkload)
+        assert result._config.document_length == 5000
+        assert result._config.query_per_document == 4
+        assert result._config.shuffle_policy == "tile"
+        assert result._config.max_output_length == 1024
+        assert result._config.num_documents == 20  # 10 * 10000 / 5000
+
+    def test_multi_round_chat(self) -> None:
+        config = _make_config(workload="multi-round-chat")
+        args = _make_args()
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, BaseWorkload)
+        assert isinstance(result, MultiRoundChatWorkload)
+        # 100 * 50000 / (2000 + 10000) = 416
+        assert result._config.num_concurrent_users == 416
+
+    def test_multi_round_chat_custom_args(self) -> None:
+        config = _make_config(
+            workload="multi-round-chat",
+            kv_cache_volume_gb=10.0,
+            tokens_per_gb_kvcache=10000,
+        )
+        args = _make_args(
+            mrc_shared_prompt_length=500,
+            mrc_chat_history_length=5000,
+            mrc_qps=5.0,
+            mrc_duration=30.0,
+        )
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, MultiRoundChatWorkload)
+        assert result._config.shared_prompt_length == 500
+        assert result._config.chat_history_length == 5000
+        assert result._config.qps == 5.0
+        assert result._config.duration == 30.0
+        # 10 * 10000 / (500 + 5000) = 18
+        assert result._config.num_concurrent_users == 18
+
+    def test_random_prefill(self) -> None:
+        config = _make_config(workload="random-prefill")
+        args = _make_args()
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, BaseWorkload)
+        assert isinstance(result, RandomPrefillWorkload)
+        assert result._config.request_length == 10000
+        assert result._config.num_requests == 50
+
+    def test_random_prefill_custom_args(self) -> None:
+        config = _make_config(workload="random-prefill")
+        args = _make_args(rp_request_length=5000, rp_num_requests=20)
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, RandomPrefillWorkload)
+        assert result._config.request_length == 5000
+        assert result._config.num_requests == 20
+
+    def test_prefix_suffix_tuner(self) -> None:
+        # Defaults: psf_thrash=20.0 (target tier in GB).  The workload does
+        # NOT consume kv_cache_volume_gb (its sizing is independent of the
+        # general kv_cache_volume flag), so this test asserts only on the
+        # psf-* args + tokens-per-gb.
+        config = _make_config(
+            workload="prefix-suffix-tuner",
+            tokens_per_gb_kvcache=10000,
+        )
+        args = _make_args()
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, BaseWorkload)
+        assert isinstance(result, PrefixSuffixTunerWorkload)
+        # context=8000, ratio=0.8 → prefix=6400; suffix=8000-6400-32=1568
+        assert result._config.prefix_tokens == 6400
+        assert result._config.suffix_tokens == 1568
+        # thrash=20.0 GB; pool_gb=20.0 * 1.05 = 21.0 GB
+        # Sized by context_length=8000 (full per-request KV footprint):
+        # num_prefixes = 21.0 * 10000 / 8000 = 26.25 → 26
+        assert result._config.num_prefixes == 26
+
+    def test_prefix_suffix_tuner_custom_args(self) -> None:
+        config = _make_config(
+            workload="prefix-suffix-tuner",
+            tokens_per_gb_kvcache=10000,
+        )
+        args = _make_args(
+            psf_context_length=4000,
+            psf_prefix_ratio=0.5,
+            psf_thrash=50.0,
+        )
+        sender, collector, monitor = _make_deps()
+        result = create_workload(
+            config,
+            args,
+            sender,
+            collector,
+            monitor,
+        )
+        assert isinstance(result, PrefixSuffixTunerWorkload)
+        assert result._config.context_length == 4000
+        assert result._config.prefix_ratio == 0.5
+        assert result._config.thrash == 50.0
+        assert result._config.prefix_tokens == 2000
+        # thrash=50 GB; pool_gb=50 * 1.05 = 52.5 GB
+        # Sized by context_length=4000:
+        # num_prefixes = 52.5 * 10000 / 4000 = 131.25 → 131
+        assert result._config.num_prefixes == 131
+
+    def test_unknown_workload_raises(self) -> None:
+        config = _make_config(workload="unknown-workload")
+        args = _make_args()
+        sender, collector, monitor = _make_deps()
+        with pytest.raises(ValueError, match="Unknown workload"):
+            create_workload(
+                config,
+                args,
+                sender,
+                collector,
+                monitor,
+            )
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_long_doc_permutator.py b/tests/cli/commands/bench/engine_bench/workloads/test_long_doc_permutator.py
new file mode 100644
index 0000000..d515b59
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_long_doc_permutator.py
@@ -0,0 +1,529 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for long-doc-permutator workload config and workload."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock
+import asyncio
+import math
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.cli.commands.bench.engine_bench.workloads.long_doc_permutator import (
+    LongDocPermutatorConfig,
+    LongDocPermutatorWorkload,
+    _enumerate_permutations,
+    _generate_contexts,
+    _generate_system_prompt,
+    _generate_vocab_pool,
+)
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorConfig — direct construction
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorConfig:
+    def test_defaults(self) -> None:
+        cfg = LongDocPermutatorConfig()
+        assert cfg.num_contexts == 5
+        assert cfg.context_length == 5000
+        assert cfg.system_prompt_length == 1000
+        assert cfg.num_permutations == 10
+        assert cfg.vocab_size == 8000
+        assert cfg.num_inflight_requests == 1
+
+    def test_custom_values(self) -> None:
+        cfg = LongDocPermutatorConfig(
+            num_contexts=3,
+            context_length=200,
+            system_prompt_length=50,
+            num_permutations=4,
+            vocab_size=500,
+            num_inflight_requests=2,
+        )
+        assert cfg.num_contexts == 3
+        assert cfg.context_length == 200
+        assert cfg.system_prompt_length == 50
+        assert cfg.num_permutations == 4
+        assert cfg.vocab_size == 500
+        assert cfg.num_inflight_requests == 2
+
+    def test_invalid_num_contexts_zero(self) -> None:
+        with pytest.raises(ValueError, match="num_contexts must be >= 1"):
+            LongDocPermutatorConfig(num_contexts=0)
+
+    def test_invalid_num_contexts_negative(self) -> None:
+        with pytest.raises(ValueError, match="num_contexts must be >= 1"):
+            LongDocPermutatorConfig(num_contexts=-1)
+
+    def test_invalid_context_length_zero(self) -> None:
+        with pytest.raises(ValueError, match="context_length must be positive"):
+            LongDocPermutatorConfig(context_length=0)
+
+    def test_invalid_context_length_negative(self) -> None:
+        with pytest.raises(ValueError, match="context_length must be positive"):
+            LongDocPermutatorConfig(context_length=-5)
+
+    def test_invalid_num_permutations_zero(self) -> None:
+        with pytest.raises(ValueError, match="num_permutations must be >= 1"):
+            LongDocPermutatorConfig(num_permutations=0)
+
+    def test_invalid_vocab_size_zero(self) -> None:
+        with pytest.raises(ValueError, match="vocab_size must be >= 1"):
+            LongDocPermutatorConfig(vocab_size=0)
+
+    def test_invalid_num_inflight_requests_zero(self) -> None:
+        with pytest.raises(ValueError, match="num_inflight_requests must be >= 1"):
+            LongDocPermutatorConfig(num_inflight_requests=0)
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorConfig.resolve
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorConfigResolve:
+    def test_resolve_defaults(self) -> None:
+        cfg = LongDocPermutatorConfig.resolve()
+        assert cfg.num_contexts == 5
+        assert cfg.context_length == 5000
+        assert cfg.system_prompt_length == 1000
+        assert cfg.num_permutations == 10
+        assert cfg.vocab_size == 8000
+        assert cfg.num_inflight_requests == 1
+
+    def test_resolve_custom(self) -> None:
+        cfg = LongDocPermutatorConfig.resolve(
+            num_contexts=3,
+            context_length=200,
+            system_prompt_length=50,
+            num_permutations=4,
+            vocab_size=500,
+            num_inflight_requests=2,
+        )
+        assert cfg.num_contexts == 3
+        assert cfg.context_length == 200
+        assert cfg.system_prompt_length == 50
+        assert cfg.num_permutations == 4
+        assert cfg.vocab_size == 500
+        assert cfg.num_inflight_requests == 2
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+
+class TestGenerateVocabPool:
+    def test_returns_correct_size(self) -> None:
+        pool = _generate_vocab_pool(100)
+        assert len(pool) == 100
+
+    def test_all_unique(self) -> None:
+        pool = _generate_vocab_pool(200)
+        assert len(pool) == len(set(pool))
+
+    def test_deterministic(self) -> None:
+        pool1 = _generate_vocab_pool(50, seed=42)
+        pool2 = _generate_vocab_pool(50, seed=42)
+        assert pool1 == pool2
+
+    def test_different_seeds_differ(self) -> None:
+        pool1 = _generate_vocab_pool(50, seed=1)
+        pool2 = _generate_vocab_pool(50, seed=2)
+        assert pool1 != pool2
+
+    def test_returns_sorted(self) -> None:
+        pool = _generate_vocab_pool(100)
+        assert pool == sorted(pool)
+
+
+class TestGenerateSystemPrompt:
+    def test_empty_for_zero_length(self) -> None:
+        assert _generate_system_prompt(0) == ""
+
+    def test_approximate_length(self) -> None:
+        prompt = _generate_system_prompt(50)
+        # Space-separated words → len(words) == length
+        assert len(prompt.split()) == 50
+
+    def test_deterministic(self) -> None:
+        p1 = _generate_system_prompt(30, seed=42)
+        p2 = _generate_system_prompt(30, seed=42)
+        assert p1 == p2
+
+    def test_different_seeds_differ(self) -> None:
+        p1 = _generate_system_prompt(30, seed=1)
+        p2 = _generate_system_prompt(30, seed=2)
+        assert p1 != p2
+
+
+class TestGenerateContexts:
+    def test_correct_count(self) -> None:
+        pool = _generate_vocab_pool(200)
+        contexts = _generate_contexts(4, 50, pool)
+        assert len(contexts) == 4
+
+    def test_approximate_length(self) -> None:
+        pool = _generate_vocab_pool(200)
+        contexts = _generate_contexts(3, 100, pool)
+        for ctx in contexts:
+            assert len(ctx.split()) == 100
+
+    def test_contexts_are_unique(self) -> None:
+        pool = _generate_vocab_pool(500)
+        contexts = _generate_contexts(5, 200, pool)
+        assert len(set(contexts)) == 5
+
+    def test_deterministic(self) -> None:
+        pool = _generate_vocab_pool(200, seed=42)
+        c1 = _generate_contexts(3, 50, pool, seed=10)
+        c2 = _generate_contexts(3, 50, pool, seed=10)
+        assert c1 == c2
+
+
+class TestEnumeratePermutations:
+    def test_all_permutations_when_small(self) -> None:
+        # 3! = 6 <= num_permutations
+        perms = _enumerate_permutations(3, 100)
+        assert len(perms) == math.factorial(3)
+
+    def test_capped_at_requested(self) -> None:
+        perms = _enumerate_permutations(5, 4)
+        assert len(perms) == 4
+
+    def test_all_are_valid_permutations(self) -> None:
+        perms = _enumerate_permutations(4, 10)
+        for perm in perms:
+            assert sorted(perm) == list(range(4))
+
+    def test_no_duplicates(self) -> None:
+        perms = _enumerate_permutations(4, 20)
+        assert len(set(perms)) == len(perms)
+
+    def test_deterministic(self) -> None:
+        p1 = _enumerate_permutations(5, 8, seed=0)
+        p2 = _enumerate_permutations(5, 8, seed=0)
+        assert p1 == p2
+
+    def test_single_context_single_permutation(self) -> None:
+        perms = _enumerate_permutations(1, 5)
+        assert perms == [(0,)]
+
+
+# ---------------------------------------------------------------------------
+# Shared test fixtures
+# ---------------------------------------------------------------------------
+
+
+def _make_config(**overrides) -> LongDocPermutatorConfig:
+    defaults = dict(
+        num_contexts=3,
+        context_length=20,
+        system_prompt_length=10,
+        num_permutations=4,
+        vocab_size=100,
+        num_inflight_requests=1,
+    )
+    defaults.update(overrides)
+    return LongDocPermutatorConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_mock_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.1,
+        request_latency=0.5,
+        num_input_tokens=100,
+        num_output_tokens=5,
+        decode_speed=20.0,
+        submit_time=now,
+        first_token_time=now + 0.1,
+        finish_time=now + 0.5,
+        error="",
+    )
+
+
+def _make_mock_sender() -> MagicMock:
+    sender = MagicMock()
+    sender.send_request = AsyncMock(return_value=_make_mock_result())
+    sender.send_warmup_request = AsyncMock(return_value=_make_mock_result())
+    sender.close = AsyncMock(return_value=None)
+    return sender
+
+
+def _make_workload(
+    config: LongDocPermutatorConfig | None = None,
+    seed: int = 42,
+) -> tuple[LongDocPermutatorWorkload, MagicMock, MagicMock, MagicMock]:
+    if config is None:
+        config = _make_config()
+    sender = _make_mock_sender()
+    collector = MagicMock()
+    monitor = MagicMock()
+    workload = LongDocPermutatorWorkload(
+        config,
+        sender,
+        collector,
+        monitor,
+        seed=seed,
+    )
+    return workload, sender, collector, monitor
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorWorkload — construction
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorWorkloadInit:
+    def test_system_prompt_built(self) -> None:
+        cfg = _make_config(system_prompt_length=20)
+        w, *_ = _make_workload(cfg)
+        assert len(w._system_prompt.split()) == 20
+
+    def test_system_prompt_empty_when_zero(self) -> None:
+        cfg = _make_config(system_prompt_length=0)
+        w, *_ = _make_workload(cfg)
+        assert w._system_prompt == ""
+
+    def test_contexts_count(self) -> None:
+        cfg = _make_config(num_contexts=4)
+        w, *_ = _make_workload(cfg)
+        assert len(w._contexts) == 4
+
+    def test_permutations_capped(self) -> None:
+        # 3! = 6; requesting 4 should yield 4
+        cfg = _make_config(num_contexts=3, num_permutations=4)
+        w, *_ = _make_workload(cfg)
+        assert len(w._permutations) == 4
+
+    def test_permutations_all_when_small(self) -> None:
+        cfg = _make_config(num_contexts=2, num_permutations=100)
+        w, *_ = _make_workload(cfg)
+        assert len(w._permutations) == math.factorial(2)
+
+    def test_request_list_length_matches_permutations(self) -> None:
+        cfg = _make_config(num_contexts=3, num_permutations=4)
+        w, *_ = _make_workload(cfg)
+        assert len(w._request_list) == len(w._permutations)
+
+    def test_request_index_starts_at_zero(self) -> None:
+        w, *_ = _make_workload()
+        assert w._request_index == 0
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorWorkload — request list building
+# ---------------------------------------------------------------------------
+
+
+class TestBuildRequestList:
+    def test_each_entry_is_tuple_messages_and_perm_idx(self) -> None:
+        cfg = _make_config(num_contexts=2, num_permutations=2)
+        w, *_ = _make_workload(cfg)
+        for messages, perm_idx in w._request_list:
+            assert isinstance(messages, list)
+            assert isinstance(perm_idx, int)
+
+    def test_system_prompt_prepended_when_present(self) -> None:
+        cfg = _make_config(system_prompt_length=10)
+        w, *_ = _make_workload(cfg)
+        messages, _ = w._request_list[0]
+        assert messages[0]["role"] == "system"
+        assert messages[1]["role"] == "user"
+
+    def test_no_system_message_when_empty(self) -> None:
+        cfg = _make_config(system_prompt_length=0)
+        w, *_ = _make_workload(cfg)
+        messages, _ = w._request_list[0]
+        assert len(messages) == 1
+        assert messages[0]["role"] == "user"
+
+    def test_user_message_contains_all_contexts(self) -> None:
+        cfg = _make_config(num_contexts=3, num_permutations=1)
+        w, *_ = _make_workload(cfg)
+        messages, perm_idx = w._request_list[0]
+        user_content = messages[-1]["content"]
+        perm = w._permutations[perm_idx]
+        for idx in perm:
+            assert w._contexts[idx] in user_content
+
+    def test_perm_idx_matches_permutations_list(self) -> None:
+        cfg = _make_config(num_contexts=3, num_permutations=4)
+        w, *_ = _make_workload(cfg)
+        for _, perm_idx in w._request_list:
+            assert 0 <= perm_idx < len(w._permutations)
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorWorkload — warmup (async)
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorWarmup:
+    def test_warmup_sends_exactly_one_request(self) -> None:
+        w, sender, _, _ = _make_workload()
+        asyncio.run(w.warmup())
+        assert sender.send_warmup_request.call_count == 1
+
+    def test_warmup_request_id_is_warmup_0(self) -> None:
+        w, sender, _, _ = _make_workload()
+        asyncio.run(w.warmup())
+        call_args = sender.send_warmup_request.call_args[0]
+        assert call_args[0] == "warmup_0"
+
+    def test_warmup_sends_chat_messages(self) -> None:
+        w, sender, _, _ = _make_workload()
+        asyncio.run(w.warmup())
+        messages = sender.send_warmup_request.call_args[0][1]
+        roles = [m["role"] for m in messages]
+        assert "system" in roles
+        assert "user" in roles
+
+    def test_warmup_logs_progress(self) -> None:
+        w, _, _, monitor = _make_workload()
+        asyncio.run(w.warmup())
+        assert monitor.on_request_sent.call_count == 1
+        assert monitor.log_message.call_count >= 2  # start + complete
+
+    def test_warmup_failed_result_logs_message(self) -> None:
+        now = time.time()
+        failed = RequestResult(
+            request_id="warmup_0",
+            successful=False,
+            ttft=0.0,
+            request_latency=0.0,
+            num_input_tokens=0,
+            num_output_tokens=0,
+            decode_speed=0.0,
+            submit_time=now,
+            first_token_time=now,
+            finish_time=now,
+            error="connection refused",
+        )
+        w, sender, _, monitor = _make_workload()
+        sender.send_warmup_request = AsyncMock(return_value=failed)
+        asyncio.run(w.warmup())
+        messages = [call[0][0] for call in monitor.log_message.call_args_list]
+        assert any("failed" in m.lower() for m in messages)
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorWorkload — step (async)
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorStep:
+    def test_first_step_dispatches_one_and_returns_zero(self) -> None:
+        async def _run() -> None:
+            cfg = _make_config(num_contexts=2, num_permutations=3)
+            w, _, _, _ = _make_workload(cfg)
+            result = await w.step(0.0)
+            assert result == 0.0
+            assert w._request_index == 1
+
+        asyncio.run(_run())
+
+    def test_step_returns_negative_when_all_done(self) -> None:
+        async def _run() -> None:
+            cfg = _make_config(num_contexts=2, num_permutations=2)
+            w, _, _, _ = _make_workload(cfg)
+
+            while True:
+                r = await w.step(0.0)
+                if w._pending_tasks:
+                    await asyncio.gather(*w._pending_tasks)
+                if r == -1.0:
+                    break
+
+            assert w._request_index == len(w._request_list)
+
+        asyncio.run(_run())
+
+    def test_step_calls_send_request(self) -> None:
+        async def _run() -> None:
+            cfg = _make_config(num_contexts=2, num_permutations=1)
+            w, sender, _, _ = _make_workload(cfg)
+
+            await w.step(0.0)
+            if w._pending_tasks:
+                await asyncio.gather(*w._pending_tasks)
+
+            assert sender.send_request.call_count == 1
+
+        asyncio.run(_run())
+
+    def test_step_waits_when_pending_and_no_new_requests(self) -> None:
+        async def _run() -> None:
+            cfg = _make_config(
+                num_contexts=2,
+                num_permutations=2,
+                num_inflight_requests=1,
+            )
+            w, _, _, _ = _make_workload(cfg)
+
+            await w.step(0.0)
+            await asyncio.gather(*list(w._pending_tasks))
+            await w.step(0.0)
+            await asyncio.gather(*list(w._pending_tasks))
+            result = await w.step(0.0)
+            assert result == -1.0
+
+        asyncio.run(_run())
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorWorkload — on_request_finished
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorOnRequestFinished:
+    def test_noop(self) -> None:
+        w, *_ = _make_workload()
+        w.on_request_finished("perm0_req1", "some output")  # must not raise
+
+
+# ---------------------------------------------------------------------------
+# LongDocPermutatorWorkload — full run
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocPermutatorFullRun:
+    def test_full_run_sends_all_permutations(self) -> None:
+        cfg = _make_config(num_contexts=2, num_permutations=2)
+        w, sender, collector, _ = _make_workload(cfg)
+
+        w.run()
+
+        assert sender.send_warmup_request.call_count == 1
+        assert sender.send_request.call_count == len(w._permutations)
+        collector.reset.assert_called_once()
+
+    def test_full_run_with_all_permutations(self) -> None:
+        # 3 contexts → 3! = 6 permutations
+        cfg = _make_config(num_contexts=3, num_permutations=100)
+        w, sender, collector, _ = _make_workload(cfg)
+
+        w.run()
+
+        expected = math.factorial(3)
+        assert sender.send_request.call_count == expected
+
+    def test_full_run_reproducible(self) -> None:
+        cfg = _make_config(num_contexts=2, num_permutations=2)
+        w1, s1, _, _ = _make_workload(cfg, seed=7)
+        w2, s2, _, _ = _make_workload(cfg, seed=7)
+
+        w1.run()
+        w2.run()
+
+        calls1 = [c[0][1] for c in s1.send_request.call_args_list]
+        calls2 = [c[0][1] for c in s2.send_request.call_args_list]
+        assert calls1 == calls2
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_long_doc_qa.py b/tests/cli/commands/bench/engine_bench/workloads/test_long_doc_qa.py
new file mode 100644
index 0000000..ed6232c
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_long_doc_qa.py
@@ -0,0 +1,385 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for long-doc-qa workload config and workload generator."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.cli.commands.bench.engine_bench.workloads.long_doc_qa import (
+    LongDocQAConfig,
+    LongDocQAWorkload,
+)
+
+# ---------------------------------------------------------------------------
+# LongDocQAConfig — direct construction
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAConfig:
+    def test_defaults(self) -> None:
+        cfg = LongDocQAConfig()
+        assert cfg.document_length == 10000
+        assert cfg.query_per_document == 2
+        assert cfg.num_documents == 1
+        assert cfg.shuffle_policy == "random"
+        assert cfg.num_inflight_requests == 3
+
+    def test_custom_values(self) -> None:
+        cfg = LongDocQAConfig(
+            document_length=5000,
+            query_per_document=4,
+            num_documents=10,
+            shuffle_policy="tile",
+            num_inflight_requests=5,
+        )
+        assert cfg.document_length == 5000
+        assert cfg.query_per_document == 4
+        assert cfg.num_documents == 10
+        assert cfg.shuffle_policy == "tile"
+        assert cfg.num_inflight_requests == 5
+
+    def test_invalid_document_length_zero(self) -> None:
+        with pytest.raises(ValueError, match="document_length must be positive"):
+            LongDocQAConfig(document_length=0)
+
+    def test_invalid_document_length_negative(self) -> None:
+        with pytest.raises(ValueError, match="document_length must be positive"):
+            LongDocQAConfig(document_length=-1)
+
+    def test_invalid_query_per_document(self) -> None:
+        with pytest.raises(ValueError, match="query_per_document must be >= 1"):
+            LongDocQAConfig(query_per_document=0)
+
+    def test_invalid_num_inflight_requests(self) -> None:
+        with pytest.raises(ValueError, match="num_inflight_requests must be >= 1"):
+            LongDocQAConfig(num_inflight_requests=0)
+
+    def test_invalid_shuffle_policy(self) -> None:
+        with pytest.raises(
+            ValueError, match="shuffle_policy must be 'random' or 'tile'"
+        ):
+            LongDocQAConfig(shuffle_policy="unknown")
+
+    def test_shuffle_policy_tile(self) -> None:
+        cfg = LongDocQAConfig(shuffle_policy="tile")
+        assert cfg.shuffle_policy == "tile"
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAConfig.resolve
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAConfigResolve:
+    def test_resolve_basic(self) -> None:
+        cfg = LongDocQAConfig.resolve(
+            kv_cache_volume_gb=100.0,
+            tokens_per_gb_kvcache=50000,
+            document_length=10000,
+        )
+        # 100 * 50000 / 10000 = 500
+        assert cfg.num_documents == 500
+        assert cfg.document_length == 10000
+
+    def test_resolve_fractional_floors(self) -> None:
+        cfg = LongDocQAConfig.resolve(
+            kv_cache_volume_gb=1.0,
+            tokens_per_gb_kvcache=10000,
+            document_length=3000,
+        )
+        # int(10000 / 3000) = int(3.333...) = 3
+        assert cfg.num_documents == 3
+
+    def test_resolve_minimum_one(self) -> None:
+        cfg = LongDocQAConfig.resolve(
+            kv_cache_volume_gb=0.001,
+            tokens_per_gb_kvcache=1,
+            document_length=10000,
+        )
+        # int(0.001 * 1 / 10000) = 0, clamped to 1
+        assert cfg.num_documents == 1
+
+    def test_resolve_passes_all_fields(self) -> None:
+        cfg = LongDocQAConfig.resolve(
+            kv_cache_volume_gb=10.0,
+            tokens_per_gb_kvcache=10000,
+            document_length=5000,
+            query_per_document=4,
+            shuffle_policy="tile",
+            num_inflight_requests=5,
+        )
+        assert cfg.document_length == 5000
+        assert cfg.query_per_document == 4
+        assert cfg.shuffle_policy == "tile"
+        assert cfg.num_inflight_requests == 5
+        assert cfg.num_documents == 20  # 10 * 10000 / 5000
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_workload_config(**overrides) -> LongDocQAConfig:
+    defaults = dict(
+        document_length=100,
+        query_per_document=2,
+        num_documents=3,
+        shuffle_policy="tile",
+        num_inflight_requests=2,
+    )
+    defaults.update(overrides)
+    return LongDocQAConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_mock_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.1,
+        request_latency=0.5,
+        num_input_tokens=100,
+        num_output_tokens=10,
+        decode_speed=25.0,
+        submit_time=now,
+        first_token_time=now + 0.1,
+        finish_time=now + 0.5,
+        error="",
+    )
+
+
+def _make_mock_sender() -> MagicMock:
+    sender = MagicMock()
+    sender.send_request = AsyncMock(return_value=_make_mock_result())
+    sender.send_warmup_request = AsyncMock(return_value=_make_mock_result())
+    sender.close = AsyncMock(return_value=None)
+    return sender
+
+
+def _make_workload(
+    config: LongDocQAConfig | None = None,
+    seed: int = 42,
+) -> tuple[LongDocQAWorkload, MagicMock, MagicMock, MagicMock]:
+    if config is None:
+        config = _make_workload_config()
+    sender = _make_mock_sender()
+    collector = MagicMock()
+    monitor = MagicMock()
+    workload = LongDocQAWorkload(
+        config,
+        sender,
+        collector,
+        monitor,
+        seed=seed,
+    )
+    return workload, sender, collector, monitor
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — document generation
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQADocumentGeneration:
+    def test_correct_count(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(num_documents=5))
+        assert len(w._documents) == 5
+
+    def test_document_format(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(num_documents=2))
+        assert w._documents[0].startswith("Document 0: ")
+        assert w._documents[1].startswith("Document 1: ")
+
+    def test_document_fill_tokens(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(document_length=100))
+        # 100 - 10 = 90 "hi" words
+        hi_count = w._documents[0].count("hi")
+        assert hi_count == 90
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — schedule building
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAScheduleBuilding:
+    def test_tile_schedule(self) -> None:
+        w, *_ = _make_workload(
+            _make_workload_config(
+                num_documents=2,
+                query_per_document=2,
+                shuffle_policy="tile",
+            )
+        )
+        # Query-major: all docs for q0, then all docs for q1
+        assert w._schedule == [(0, 0), (1, 0), (0, 1), (1, 1)]
+
+    def test_random_schedule_differs_from_tile(self) -> None:
+        cfg_tile = _make_workload_config(
+            num_documents=5,
+            query_per_document=3,
+            shuffle_policy="tile",
+        )
+        cfg_random = _make_workload_config(
+            num_documents=5,
+            query_per_document=3,
+            shuffle_policy="random",
+        )
+        w_tile, *_ = _make_workload(cfg_tile)
+        w_rand, *_ = _make_workload(cfg_random)
+        assert set(w_tile._schedule) == set(w_rand._schedule)
+        assert w_tile._schedule != w_rand._schedule
+
+    def test_random_schedule_reproducible(self) -> None:
+        cfg = _make_workload_config(
+            num_documents=5,
+            query_per_document=3,
+            shuffle_policy="random",
+        )
+        w1, *_ = _make_workload(cfg, seed=42)
+        w2, *_ = _make_workload(cfg, seed=42)
+        assert w1._schedule == w2._schedule
+
+    def test_schedule_length(self) -> None:
+        w, *_ = _make_workload(
+            _make_workload_config(
+                num_documents=5,
+                query_per_document=3,
+            )
+        )
+        assert len(w._schedule) == 15
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — message building
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAMessageBuilding:
+    def test_message_format(self) -> None:
+        w, *_ = _make_workload()
+        msgs = w._build_messages(0, 0)
+        assert len(msgs) == 1
+        assert msgs[0]["role"] == "user"
+        assert msgs[0]["content"].startswith("Document 0: ")
+        assert "Question 0: What is this document about?" in msgs[0]["content"]
+
+    def test_question_cycling_with_index(self) -> None:
+        w, *_ = _make_workload()
+        msgs = w._build_messages(0, 4)
+        content = msgs[0]["content"]
+        # query_index=4 cycles to _QUESTIONS[0] but with unique prefix
+        assert "Question 4: What is this document about?" in content
+
+    def test_on_request_finished_noop(self) -> None:
+        w, *_ = _make_workload()
+        w.on_request_finished("some_id", "some_text")  # should not raise
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — warmup (async)
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAWarmup:
+    @pytest.mark.asyncio
+    async def test_warmup_sends_all_documents(self) -> None:
+        cfg = _make_workload_config(num_documents=3)
+        w, sender, _, monitor = _make_workload(cfg)
+
+        await w.warmup()
+
+        assert sender.send_warmup_request.call_count == 3
+        for i, call in enumerate(sender.send_warmup_request.call_args_list):
+            request_id = call[0][0]
+            messages = call[0][1]
+            assert request_id == f"warmup_doc{i}"
+            assert len(messages) == 1
+            assert messages[0]["role"] == "user"
+            # Warmup sends just the document — no question appended
+            assert "Question" not in messages[0]["content"]
+            assert messages[0]["content"].startswith(f"Document {i}: ")
+
+    @pytest.mark.asyncio
+    async def test_warmup_logs_progress(self) -> None:
+        cfg = _make_workload_config(num_documents=2)
+        w, _, _, monitor = _make_workload(cfg)
+        await w.warmup()
+        # 2 per-doc messages + 1 completion message
+        assert monitor.log_message.call_count == 3
+        assert monitor.on_request_sent.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — step (async)
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAStep:
+    @pytest.mark.asyncio
+    async def test_step_dispatches_and_returns_zero(self) -> None:
+        cfg = _make_workload_config(
+            num_documents=1,
+            query_per_document=1,
+        )
+        w, sender, _, _ = _make_workload(cfg)
+
+        result = await w.step(0.0)
+        assert result == 0.0
+        # Wait for the dispatched task to complete
+        if w._pending_tasks:
+            # Standard
+            import asyncio
+
+            await asyncio.gather(*w._pending_tasks)
+        assert sender.send_request.call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_step_returns_negative_when_done(self) -> None:
+        cfg = _make_workload_config(
+            num_documents=1,
+            query_per_document=1,
+        )
+        w, _, _, _ = _make_workload(cfg)
+
+        # Dispatch the single request
+        await w.step(0.0)
+        # Wait for task
+        # Standard
+        import asyncio
+
+        if w._pending_tasks:
+            await asyncio.gather(*w._pending_tasks)
+        # Now schedule is exhausted and no pending tasks
+        result = await w.step(0.1)
+        assert result == -1.0
+
+
+# ---------------------------------------------------------------------------
+# LongDocQAWorkload — full run (async)
+# ---------------------------------------------------------------------------
+
+
+class TestLongDocQAFullRun:
+    def test_full_run(self) -> None:
+        cfg = _make_workload_config(
+            num_documents=2,
+            query_per_document=2,
+            shuffle_policy="tile",
+        )
+        w, sender, collector, monitor = _make_workload(cfg)
+
+        w.run()
+
+        # 2 warmup requests (one per document)
+        assert sender.send_warmup_request.call_count == 2
+        # 4 benchmark requests (2 docs × 2 queries)
+        assert sender.send_request.call_count == 4
+        # Stats reset called between warmup and benchmark
+        collector.reset.assert_called_once()
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_multi_round_chat.py b/tests/cli/commands/bench/engine_bench/workloads/test_multi_round_chat.py
new file mode 100644
index 0000000..b967420
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_multi_round_chat.py
@@ -0,0 +1,488 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for multi-round-chat workload config and workload."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.cli.commands.bench.engine_bench.workloads.multi_round_chat import (
+    MultiRoundChatConfig,
+    MultiRoundChatWorkload,
+    Session,
+)
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatConfig — direct construction
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatConfig:
+    def test_defaults(self) -> None:
+        cfg = MultiRoundChatConfig()
+        assert cfg.shared_prompt_length == 2000
+        assert cfg.chat_history_length == 10000
+        assert cfg.user_input_length == 50
+        assert cfg.output_length == 200
+        assert cfg.qps == 1.0
+        assert cfg.duration == 60.0
+        assert cfg.num_concurrent_users == 1
+
+    def test_custom_values(self) -> None:
+        cfg = MultiRoundChatConfig(
+            shared_prompt_length=500,
+            chat_history_length=5000,
+            user_input_length=100,
+            output_length=300,
+            qps=2.0,
+            duration=120.0,
+            num_concurrent_users=10,
+        )
+        assert cfg.shared_prompt_length == 500
+        assert cfg.chat_history_length == 5000
+        assert cfg.user_input_length == 100
+        assert cfg.output_length == 300
+        assert cfg.qps == 2.0
+        assert cfg.duration == 120.0
+        assert cfg.num_concurrent_users == 10
+
+    def test_invalid_shared_prompt_length(self) -> None:
+        with pytest.raises(ValueError, match="shared_prompt_length must be positive"):
+            MultiRoundChatConfig(shared_prompt_length=0)
+
+    def test_invalid_chat_history_length(self) -> None:
+        with pytest.raises(ValueError, match="chat_history_length must be positive"):
+            MultiRoundChatConfig(chat_history_length=-1)
+
+    def test_invalid_user_input_length(self) -> None:
+        with pytest.raises(ValueError, match="user_input_length must be >= 1"):
+            MultiRoundChatConfig(user_input_length=0)
+
+    def test_invalid_output_length(self) -> None:
+        with pytest.raises(ValueError, match="output_length must be >= 1"):
+            MultiRoundChatConfig(output_length=0)
+
+    def test_invalid_qps(self) -> None:
+        with pytest.raises(ValueError, match="qps must be positive"):
+            MultiRoundChatConfig(qps=0)
+
+    def test_invalid_duration(self) -> None:
+        with pytest.raises(ValueError, match="duration must be positive"):
+            MultiRoundChatConfig(duration=-1)
+
+    def test_invalid_num_concurrent_users(self) -> None:
+        with pytest.raises(ValueError, match="num_concurrent_users must be >= 1"):
+            MultiRoundChatConfig(num_concurrent_users=0)
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatConfig.resolve
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatConfigResolve:
+    def test_resolve_basic(self) -> None:
+        cfg = MultiRoundChatConfig.resolve(
+            kv_cache_volume_gb=100.0,
+            tokens_per_gb_kvcache=6000,
+            shared_prompt_length=2000,
+            chat_history_length=10000,
+        )
+        # 100 * 6000 / (2000 + 10000) = 600000 / 12000 = 50
+        assert cfg.num_concurrent_users == 50
+
+    def test_resolve_fractional_floors(self) -> None:
+        cfg = MultiRoundChatConfig.resolve(
+            kv_cache_volume_gb=1.0,
+            tokens_per_gb_kvcache=10000,
+            shared_prompt_length=2000,
+            chat_history_length=5000,
+        )
+        # 10000 / 7000 = 1.428 → int(1.428) = 1
+        assert cfg.num_concurrent_users == 1
+
+    def test_resolve_minimum_one(self) -> None:
+        cfg = MultiRoundChatConfig.resolve(
+            kv_cache_volume_gb=0.001,
+            tokens_per_gb_kvcache=1,
+            shared_prompt_length=2000,
+            chat_history_length=10000,
+        )
+        assert cfg.num_concurrent_users == 1
+
+    def test_resolve_passes_all_fields(self) -> None:
+        cfg = MultiRoundChatConfig.resolve(
+            kv_cache_volume_gb=10.0,
+            tokens_per_gb_kvcache=10000,
+            shared_prompt_length=500,
+            chat_history_length=5000,
+            user_input_length=100,
+            output_length=300,
+            qps=5.0,
+            duration=120.0,
+        )
+        assert cfg.shared_prompt_length == 500
+        assert cfg.chat_history_length == 5000
+        assert cfg.user_input_length == 100
+        assert cfg.output_length == 300
+        assert cfg.qps == 5.0
+        assert cfg.duration == 120.0
+        # 10 * 10000 / (500 + 5000) = 100000 / 5500 = 18
+        assert cfg.num_concurrent_users == 18
+
+
+# ---------------------------------------------------------------------------
+# Session
+# ---------------------------------------------------------------------------
+
+
+class TestSession:
+    def test_construction(self) -> None:
+        s = Session(
+            session_id=0,
+            system_prompt="You are helpful.",
+            history_text="Some history.",
+        )
+        assert s.session_id == 0
+        assert s.exchanges == []
+        assert s.in_flight is False
+
+    def test_build_messages_no_history(self) -> None:
+        s = Session(
+            session_id=0,
+            system_prompt="System.",
+            history_text="",
+        )
+        msgs = s.build_messages("Hello")
+        assert len(msgs) == 2
+        assert msgs[0] == {"role": "system", "content": "System."}
+        assert msgs[1] == {"role": "user", "content": "Hello"}
+
+    def test_build_messages_with_history(self) -> None:
+        s = Session(
+            session_id=0,
+            system_prompt="System.",
+            history_text="Context text.",
+        )
+        msgs = s.build_messages("Hello")
+        assert len(msgs) == 4
+        assert msgs[0]["role"] == "system"
+        assert msgs[1]["role"] == "user"
+        assert msgs[1]["content"] == "Context text."
+        assert msgs[2]["role"] == "assistant"
+        assert "Understood" in msgs[2]["content"]
+        assert msgs[3] == {"role": "user", "content": "Hello"}
+
+    def test_build_messages_with_exchanges(self) -> None:
+        s = Session(
+            session_id=0,
+            system_prompt="System.",
+            history_text="",
+            exchanges=[("q1", "a1"), ("q2", "a2")],
+        )
+        msgs = s.build_messages("q3")
+        # system + 2 exchanges (4 msgs) + new query = 6 (no history pair)
+        assert len(msgs) == 6
+        assert msgs[1] == {"role": "user", "content": "q1"}
+        assert msgs[2] == {"role": "assistant", "content": "a1"}
+        assert msgs[3] == {"role": "user", "content": "q2"}
+        assert msgs[4] == {"role": "assistant", "content": "a2"}
+        assert msgs[5] == {"role": "user", "content": "q3"}
+
+    def test_record_answer(self) -> None:
+        s = Session(
+            session_id=0,
+            system_prompt="System.",
+            history_text="",
+        )
+        s.in_flight = True
+        s.record_answer("q1", "a1")
+        assert s.exchanges == [("q1", "a1")]
+        assert s.in_flight is False
+
+    def test_record_multiple_answers(self) -> None:
+        s = Session(
+            session_id=0,
+            system_prompt="System.",
+            history_text="",
+        )
+        s.record_answer("q1", "a1")
+        s.record_answer("q2", "a2")
+        assert len(s.exchanges) == 2
+        assert s.exchanges[1] == ("q2", "a2")
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_config(**overrides) -> MultiRoundChatConfig:
+    defaults = dict(
+        shared_prompt_length=100,
+        chat_history_length=200,
+        user_input_length=10,
+        output_length=20,
+        qps=10.0,
+        duration=5.0,
+        num_concurrent_users=3,
+    )
+    defaults.update(overrides)
+    return MultiRoundChatConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_mock_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.1,
+        request_latency=0.5,
+        num_input_tokens=100,
+        num_output_tokens=10,
+        decode_speed=25.0,
+        submit_time=now,
+        first_token_time=now + 0.1,
+        finish_time=now + 0.5,
+        error="",
+    )
+
+
+def _make_mock_sender() -> MagicMock:
+    sender = MagicMock()
+    sender.send_request = AsyncMock(return_value=_make_mock_result())
+    sender.send_warmup_request = AsyncMock(return_value=_make_mock_result())
+    sender.close = AsyncMock(return_value=None)
+    return sender
+
+
+def _make_workload(
+    config: MultiRoundChatConfig | None = None,
+    seed: int = 42,
+) -> tuple[MultiRoundChatWorkload, MagicMock, MagicMock, MagicMock]:
+    if config is None:
+        config = _make_config()
+    sender = _make_mock_sender()
+    collector = MagicMock()
+    monitor = MagicMock()
+    workload = MultiRoundChatWorkload(
+        config,
+        sender,
+        collector,
+        monitor,
+        seed=seed,
+    )
+    return workload, sender, collector, monitor
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — session creation
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatSessionCreation:
+    def test_correct_count(self) -> None:
+        w, *_ = _make_workload(_make_config(num_concurrent_users=5))
+        assert len(w._sessions) == 5
+
+    def test_session_prompts(self) -> None:
+        w, *_ = _make_workload(_make_config(num_concurrent_users=2))
+        assert "Session 0" in w._sessions[0].system_prompt
+        assert "Session 1" in w._sessions[1].system_prompt
+
+    def test_session_history(self) -> None:
+        w, *_ = _make_workload(_make_config(num_concurrent_users=2))
+        assert "[Session 0 history]" in w._sessions[0].history_text
+        assert "[Session 1 history]" in w._sessions[1].history_text
+
+    def test_sessions_start_ready(self) -> None:
+        w, *_ = _make_workload()
+        for s in w._sessions:
+            assert s.in_flight is False
+            assert s.exchanges == []
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — query generation
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatQueryGeneration:
+    def test_query_length(self) -> None:
+        w, *_ = _make_workload(_make_config(user_input_length=10))
+        query = w._generate_query()
+        assert query.count("tell") == 10
+
+    def test_query_single_word(self) -> None:
+        w, *_ = _make_workload(_make_config(user_input_length=1))
+        query = w._generate_query()
+        assert query == "tell"
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — warmup (async)
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatWarmup:
+    @pytest.mark.asyncio
+    async def test_warmup_sends_all_sessions(self) -> None:
+        cfg = _make_config(num_concurrent_users=3)
+        w, sender, _, monitor = _make_workload(cfg)
+
+        await w.warmup()
+
+        assert sender.send_warmup_request.call_count == 3
+        for i, call in enumerate(sender.send_warmup_request.call_args_list):
+            request_id = call[0][0]
+            messages = call[0][1]
+            assert request_id == f"warmup_s{i}"
+            assert messages[0]["role"] == "system"
+            assert messages[-1]["role"] == "user"
+            assert messages[-1]["content"] == "Hello"
+
+    @pytest.mark.asyncio
+    async def test_warmup_logs_progress(self) -> None:
+        cfg = _make_config(num_concurrent_users=2)
+        w, _, _, monitor = _make_workload(cfg)
+        await w.warmup()
+        # 2 per-session messages + 1 completion message
+        assert monitor.log_message.call_count == 3
+        assert monitor.on_request_sent.call_count == 2
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — step (async)
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatStep:
+    @pytest.mark.asyncio
+    async def test_step_dispatches_and_returns_next_time(self) -> None:
+        cfg = _make_config(
+            num_concurrent_users=2,
+            qps=10.0,
+            duration=5.0,
+        )
+        w, sender, _, _ = _make_workload(cfg)
+
+        result = await w.step(0.0)
+        # Next wakeup at 1 * 0.1 = 0.1
+        assert abs(result - 0.1) < 1e-9
+        assert w._global_index == 1
+        # Wait for task
+        if w._pending_tasks:
+            # Standard
+            import asyncio
+
+            await asyncio.gather(*w._pending_tasks)
+        assert sender.send_request.call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_step_busy_session_returns_small_sleep(self) -> None:
+        cfg = _make_config(
+            num_concurrent_users=1,
+            qps=10.0,
+            duration=5.0,
+        )
+        w, _, _, _ = _make_workload(cfg)
+
+        # Mark session as in-flight
+        w._sessions[0].in_flight = True
+
+        result = await w.step(0.5)
+        # Should return current time + 0.01
+        assert abs(result - 0.51) < 1e-9
+        # global_index should NOT have incremented
+        assert w._global_index == 0
+
+    @pytest.mark.asyncio
+    async def test_step_returns_negative_when_done(self) -> None:
+        cfg = _make_config(duration=1.0)
+        w, _, _, _ = _make_workload(cfg)
+
+        # Time exceeds duration, no pending tasks
+        result = await w.step(2.0)
+        assert result == -1.0
+
+    @pytest.mark.asyncio
+    async def test_step_waits_for_pending_tasks_after_duration(
+        self,
+    ) -> None:
+        cfg = _make_config(
+            num_concurrent_users=1,
+            qps=100.0,
+            duration=0.01,
+        )
+        w, _, _, _ = _make_workload(cfg)
+
+        # Dispatch one request at time 0
+        await w.step(0.0)
+        assert len(w._pending_tasks) > 0
+
+        # Standard
+        import asyncio
+
+        # Let task finish
+        await asyncio.gather(*w._pending_tasks)
+
+        # Now past duration with no pending → done
+        result = await w.step(1.0)
+        assert result == -1.0
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — on_request_finished (stateful)
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatOnRequestFinished:
+    def test_records_answer_in_session(self) -> None:
+        w, *_ = _make_workload()
+        # Simulate a pending request
+        w._pending_info["s0_r0"] = (0, "What is 2+2?")
+        w._sessions[0].in_flight = True
+
+        w.on_request_finished("s0_r0", "4")
+
+        assert w._sessions[0].exchanges == [("What is 2+2?", "4")]
+        assert w._sessions[0].in_flight is False
+
+    def test_ignores_unknown_request(self) -> None:
+        w, *_ = _make_workload()
+        # Should not raise
+        w.on_request_finished("unknown_id", "text")
+
+    def test_warmup_request_ignored(self) -> None:
+        w, *_ = _make_workload()
+        # Warmup requests are not in _pending_info
+        w.on_request_finished("warmup_s0", "text")
+        assert w._sessions[0].exchanges == []
+
+
+# ---------------------------------------------------------------------------
+# MultiRoundChatWorkload — full run
+# ---------------------------------------------------------------------------
+
+
+class TestMultiRoundChatFullRun:
+    def test_full_run(self) -> None:
+        cfg = _make_config(
+            num_concurrent_users=2,
+            qps=100.0,  # fast dispatch
+            duration=0.1,  # short duration
+        )
+        w, sender, collector, monitor = _make_workload(cfg)
+
+        w.run()
+
+        # Warmup: 2 sessions
+        assert sender.send_warmup_request.call_count == 2
+        # Benchmark: at least some requests dispatched
+        assert sender.send_request.call_count > 0
+        # Stats reset called between warmup and benchmark
+        collector.reset.assert_called_once()
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_prefix_suffix_tuner.py b/tests/cli/commands/bench/engine_bench/workloads/test_prefix_suffix_tuner.py
new file mode 100644
index 0000000..432ea75
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_prefix_suffix_tuner.py
@@ -0,0 +1,766 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for prefix-suffix-tuner workload config and workload generator."""
+
+# Standard
+from collections import OrderedDict
+from unittest.mock import AsyncMock, MagicMock
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.cli.commands.bench.engine_bench.workloads.prefix_suffix_tuner import (
+    PrefixSuffixTunerConfig,
+    PrefixSuffixTunerWorkload,
+)
+
+# ---------------------------------------------------------------------------
+# PrefixSuffixTunerConfig — direct construction
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerConfig:
+    def test_defaults(self) -> None:
+        cfg = PrefixSuffixTunerConfig()
+        assert cfg.context_length == 8000
+        assert cfg.prefix_ratio == 0.8
+        assert cfg.thrash == 20.0
+        assert cfg.num_prefixes == 1
+        assert cfg.prefix_tokens == 1
+        assert cfg.suffix_tokens == 1
+        assert cfg.breaker_tokens == 32
+
+    def test_custom_values(self) -> None:
+        cfg = PrefixSuffixTunerConfig(
+            context_length=4000,
+            prefix_ratio=0.5,
+            thrash=50.0,
+            num_prefixes=10,
+            prefix_tokens=2000,
+            suffix_tokens=1968,
+            breaker_tokens=32,
+        )
+        assert cfg.context_length == 4000
+        assert cfg.prefix_ratio == 0.5
+        assert cfg.thrash == 50.0
+        assert cfg.num_prefixes == 10
+
+    def test_invalid_context_length(self) -> None:
+        with pytest.raises(ValueError, match="context_length must be positive"):
+            PrefixSuffixTunerConfig(context_length=0)
+
+    def test_invalid_prefix_ratio_zero(self) -> None:
+        with pytest.raises(ValueError, match=r"prefix_ratio must be in \(0.0, 1.0\)"):
+            PrefixSuffixTunerConfig(prefix_ratio=0.0)
+
+    def test_invalid_prefix_ratio_one(self) -> None:
+        with pytest.raises(ValueError, match=r"prefix_ratio must be in \(0.0, 1.0\)"):
+            PrefixSuffixTunerConfig(prefix_ratio=1.0)
+
+    def test_invalid_prefix_ratio_negative(self) -> None:
+        with pytest.raises(ValueError, match=r"prefix_ratio must be in \(0.0, 1.0\)"):
+            PrefixSuffixTunerConfig(prefix_ratio=-0.5)
+
+    def test_invalid_thrash_zero(self) -> None:
+        with pytest.raises(ValueError, match=r"thrash \(GB\) must be positive"):
+            PrefixSuffixTunerConfig(thrash=0.0)
+
+    def test_invalid_thrash_negative(self) -> None:
+        with pytest.raises(ValueError, match=r"thrash \(GB\) must be positive"):
+            PrefixSuffixTunerConfig(thrash=-1.0)
+
+    def test_thrash_small_positive_is_valid(self) -> None:
+        # Sub-1-GB target tier is valid for tiny test runs.
+        cfg = PrefixSuffixTunerConfig(thrash=0.5)
+        assert cfg.thrash == 0.5
+
+    def test_invalid_num_prefixes(self) -> None:
+        with pytest.raises(ValueError, match="num_prefixes must be >= 1"):
+            PrefixSuffixTunerConfig(num_prefixes=0)
+
+    def test_invalid_breaker_tokens(self) -> None:
+        with pytest.raises(ValueError, match="breaker_tokens must be >= 1"):
+            PrefixSuffixTunerConfig(breaker_tokens=0)
+
+
+# ---------------------------------------------------------------------------
+# PrefixSuffixTunerConfig.resolve
+#
+# ``thrash`` is the target tier size in GB; the resolve() helper applies an
+# internal _OVERFLOW_FACTOR (1.05) to size the prefix pool slightly larger
+# than the targeted tier, so pass-2 misses everything in that tier.
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerConfigResolve:
+    def test_resolve_basic(self) -> None:
+        cfg = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=10000,
+            context_length=4000,
+            prefix_ratio=0.5,
+            thrash=10.0,
+        )
+        # prefix_tokens = round(4000 * 0.5) = 2000
+        assert cfg.prefix_tokens == 2000
+        # suffix_tokens = 4000 - 2000 - 32 = 1968
+        assert cfg.suffix_tokens == 1968
+        # pool_gb = 10 * 1.05 = 10.5 GB; 10.5 * 10000 / 4000 = 26.25 → 26
+        assert cfg.num_prefixes == 26
+
+    def test_resolve_default_thrash_scaling(self) -> None:
+        cfg = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=50000,
+            context_length=8000,
+            prefix_ratio=0.8,
+        )
+        # prefix_tokens = round(8000 * 0.8) = 6400
+        assert cfg.prefix_tokens == 6400
+        # default thrash = 20.0 GB; pool = 20 * 1.05 = 21 GB
+        # 21 * 50000 / 8000 = 131.25 → 131  (sized by context_length)
+        assert cfg.num_prefixes == 131
+
+    def test_resolve_minimum_one_prefix(self) -> None:
+        cfg = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=1,
+            context_length=4000,
+            prefix_ratio=0.5,
+            thrash=0.0001,
+        )
+        assert cfg.num_prefixes == 1
+
+    def test_resolve_suffix_too_small(self) -> None:
+        # context=200, prefix_ratio=0.95 → prefix=190, breaker=32, suffix=-22
+        with pytest.raises(ValueError, match="suffix_tokens=.* below minimum 100"):
+            PrefixSuffixTunerConfig.resolve(
+                tokens_per_gb_kvcache=10000,
+                context_length=200,
+                prefix_ratio=0.95,
+                thrash=10.0,
+            )
+
+    def test_resolve_suffix_at_minimum(self) -> None:
+        # context = 200, prefix=68, breaker=32, suffix=100 (exactly minimum)
+        cfg = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=1000,
+            context_length=200,
+            prefix_ratio=0.34,
+            thrash=1.0,
+        )
+        assert cfg.suffix_tokens == 100
+
+    def test_resolve_thrash_scales_pool_linearly(self) -> None:
+        cfg_small = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=10000,
+            context_length=4000,
+            prefix_ratio=0.5,
+            thrash=10.0,
+        )
+        cfg_big = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=10000,
+            context_length=4000,
+            prefix_ratio=0.5,
+            thrash=20.0,
+        )
+        # Doubling thrash (target tier GB) should roughly double num_prefixes
+        # — within a single prefix of 2x because of integer flooring.
+        assert abs(cfg_big.num_prefixes - 2 * cfg_small.num_prefixes) <= 1
+
+    def test_resolve_applies_internal_overflow_factor(self) -> None:
+        """``thrash`` is the target tier size, not the pool size — pool is
+        ``thrash * _OVERFLOW_FACTOR``.  Verify that with a 100 GB target tier,
+        the pool genuinely overshoots."""
+        cfg = PrefixSuffixTunerConfig.resolve(
+            tokens_per_gb_kvcache=10000,
+            context_length=2000,
+            prefix_ratio=0.5,
+            thrash=100.0,
+        )
+        # prefix_tokens = 1000
+        # pool_gb = 100 * 1.05 = 105
+        # Sized by context_length=2000 (not prefix_tokens), so the L1
+        # footprint of the pool == thrash * _OVERFLOW_FACTOR GB:
+        # num_prefixes = 105 * 10000 / 2000 = 525
+        assert cfg.num_prefixes == 525
+        # Pool footprint (in tokens of full request) > target tier tokens:
+        pool_tokens = cfg.num_prefixes * cfg.context_length
+        target_tier_tokens = int(100.0 * 10000)
+        assert pool_tokens > target_tier_tokens
+
+
+# ---------------------------------------------------------------------------
+# PrefixSuffixTunerWorkload — helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_workload_config(**overrides) -> PrefixSuffixTunerConfig:
+    defaults = dict(
+        context_length=200,
+        prefix_ratio=0.5,
+        thrash=10.0,  # target tier size in GB; resolve() not invoked here
+        num_prefixes=4,
+        prefix_tokens=100,
+        suffix_tokens=68,
+        breaker_tokens=32,
+    )
+    defaults.update(overrides)
+    return PrefixSuffixTunerConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_mock_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.1,
+        request_latency=0.5,
+        num_input_tokens=100,
+        num_output_tokens=1,
+        decode_speed=10.0,
+        submit_time=now,
+        first_token_time=now + 0.1,
+        finish_time=now + 0.5,
+        error="",
+    )
+
+
+def _make_mock_sender() -> MagicMock:
+    sender = MagicMock()
+    sender.send_request = AsyncMock(return_value=_make_mock_result())
+    sender.send_warmup_request = AsyncMock(return_value=_make_mock_result())
+    sender.close = AsyncMock(return_value=None)
+    return sender
+
+
+def _make_workload(
+    config: PrefixSuffixTunerConfig | None = None,
+    seed: int = 42,
+) -> tuple[PrefixSuffixTunerWorkload, MagicMock, MagicMock, MagicMock]:
+    if config is None:
+        config = _make_workload_config()
+    sender = _make_mock_sender()
+    collector = MagicMock()
+    monitor = MagicMock()
+    workload = PrefixSuffixTunerWorkload(
+        config,
+        sender,
+        collector,
+        monitor,
+        seed=seed,
+    )
+    return workload, sender, collector, monitor
+
+
+# ---------------------------------------------------------------------------
+# Synthetic data generation
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerData:
+    def test_correct_prefix_count(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(num_prefixes=7))
+        assert len(w._prefixes) == 7
+
+    def test_prefixes_have_unique_id_at_start(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(num_prefixes=3))
+        assert w._prefixes[0].startswith("PREFIX_00000000")
+        assert w._prefixes[1].startswith("PREFIX_00000001")
+        assert w._prefixes[2].startswith("PREFIX_00000002")
+
+    def test_prefixes_are_distinct(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(num_prefixes=5))
+        assert len(set(w._prefixes)) == 5
+
+    def test_single_shared_suffix(self) -> None:
+        w, *_ = _make_workload()
+        assert isinstance(w._suffix, str)
+        assert w._suffix.startswith("SUFFIX")
+
+    def test_data_is_deterministic_with_seed(self) -> None:
+        cfg = _make_workload_config(num_prefixes=5)
+        w1, *_ = _make_workload(cfg, seed=42)
+        w2, *_ = _make_workload(cfg, seed=42)
+        assert w1._prefixes == w2._prefixes
+        assert w1._suffix == w2._suffix
+
+    def test_data_differs_with_different_seed(self) -> None:
+        # Only the breaker RNG depends on seed; prefixes/suffix are seed-
+        # independent now (deterministic "hi"-filler bodies).  Verify the
+        # breaker stream differs across seeds.
+        cfg = _make_workload_config(num_prefixes=2)
+        w1, *_ = _make_workload(cfg, seed=42)
+        w2, *_ = _make_workload(cfg, seed=99)
+        b1 = w1._build_messages(0)[0]["content"]
+        b2 = w2._build_messages(0)[0]["content"]
+        assert b1 != b2  # different breakers produce different prompts
+
+    def test_prefix_bodies_use_hi_fallback_when_no_tokenizer(self) -> None:
+        """Fallback path: when no tokenizer is loadable (unit tests pass
+        ``model_name=None``), bodies use deterministic ``"hi"`` filler.
+
+        Production runs with the real model name get **content-unique**
+        random bodies generated from the tokenizer's vocab; that path is
+        verified E2E (loading a real tokenizer in unit tests would be
+        slow).  See ``test_prefix_bodies_are_unique_with_mock_tokenizer``
+        for the tokenizer path under a mocked tokenizer.
+        """
+        w, *_ = _make_workload(_make_workload_config(num_prefixes=4))
+        # Without a tokenizer, fallback "hi" filler kicks in.
+        assert w._tokenizer is None
+        bodies = [p.split(" ", 1)[1] for p in w._prefixes]
+        assert len(set(bodies)) == 1
+        assert all(set(b.split(" ")) == {"hi"} for b in bodies)
+
+    def test_prefix_bodies_are_unique_with_mock_tokenizer(self) -> None:
+        """Tokenizer path: each prefix samples a different per-prefix RNG,
+        so the random token-ID sequences differ → decoded bodies differ.
+        Required for non-blend cache hit-rate metrics to be meaningful
+        (otherwise content-hash collisions across identical bodies would
+        inflate hit rates regardless of LRU eviction).
+
+        Uses a mocked tokenizer to avoid loading transformers in unit
+        tests; the real-tokenizer path is exercised in E2E runs.
+        """
+        # First Party
+        from lmcache.cli.commands.bench.engine_bench.workloads import (
+            prefix_suffix_tuner as psf,
+        )
+
+        fake_tok = MagicMock()
+        fake_tok.decode = lambda ids, **kw: " ".join(f"id{i}" for i in ids)
+        original = psf._try_load_tokenizer
+        psf._try_load_tokenizer = lambda model_name: fake_tok
+        try:
+            cfg = _make_workload_config(num_prefixes=8)
+            sender = _make_mock_sender()
+            collector = MagicMock()
+            monitor = MagicMock()
+            w = psf.PrefixSuffixTunerWorkload(
+                cfg, sender, collector, monitor, seed=42, model_name="mock"
+            )
+        finally:
+            psf._try_load_tokenizer = original
+
+        bodies = [p.split(" ", 1)[1] for p in w._prefixes]
+        # All 8 prefix bodies should be distinct token-id sequences.
+        assert len(set(bodies)) == 8
+
+
+# ---------------------------------------------------------------------------
+# Message construction — request structure
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerMessages:
+    def test_message_has_user_role(self) -> None:
+        w, *_ = _make_workload()
+        msgs = w._build_messages(0)
+        assert len(msgs) == 1
+        assert msgs[0]["role"] == "user"
+
+    def test_message_contains_prefix(self) -> None:
+        w, *_ = _make_workload()
+        msgs = w._build_messages(2)
+        assert "PREFIX_00000002" in msgs[0]["content"]
+
+    def test_message_contains_shared_suffix(self) -> None:
+        w, *_ = _make_workload()
+        msgs0 = w._build_messages(0)
+        msgs1 = w._build_messages(1)
+        # Same suffix appears in both
+        assert w._suffix in msgs0[0]["content"]
+        assert w._suffix in msgs1[0]["content"]
+
+    def test_breaker_differs_per_request(self) -> None:
+        w, *_ = _make_workload()
+        msgs_a = w._build_messages(0)
+        msgs_b = w._build_messages(0)  # same prefix, different breaker
+        # The two prompts must differ even for the same prefix index
+        assert msgs_a[0]["content"] != msgs_b[0]["content"]
+
+    def test_request_layout_prefix_breaker_suffix(self) -> None:
+        w, *_ = _make_workload(_make_workload_config(num_prefixes=1))
+        content = w._build_messages(0)[0]["content"]
+        # Prefix appears before suffix
+        prefix_pos = content.find("PREFIX_")
+        suffix_pos = content.find("SUFFIX")
+        assert prefix_pos == 0
+        assert suffix_pos > prefix_pos
+
+    def test_on_request_finished_noop(self) -> None:
+        w, *_ = _make_workload()
+        w.on_request_finished("some_id", "some_text")  # should not raise
+
+
+# ---------------------------------------------------------------------------
+# Pass 1 — warmup (async)
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerWarmup:
+    @pytest.mark.asyncio
+    async def test_warmup_sends_engine_warmup_then_each_prefix_once(self) -> None:
+        cfg = _make_workload_config(num_prefixes=4)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.warmup()
+
+        # 1 engine warmup + 4 pass-1 prefixes = 5 total
+        assert sender.send_warmup_request.call_count == 5
+        # First call is the engine warmup (throwaway, before pass 1).
+        assert sender.send_warmup_request.call_args_list[0][0][0] == "engine_warmup"
+        # Subsequent calls are pass-1 prefixes in index order.
+        for i, call in enumerate(sender.send_warmup_request.call_args_list[1:]):
+            assert call[0][0] == f"pass1_p{i}"
+
+    @pytest.mark.asyncio
+    async def test_warmup_sends_pass1_prefixes_in_order(self) -> None:
+        cfg = _make_workload_config(num_prefixes=3)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.warmup()
+
+        ids = [call[0][0] for call in sender.send_warmup_request.call_args_list]
+        assert ids == ["engine_warmup", "pass1_p0", "pass1_p1", "pass1_p2"]
+
+    @pytest.mark.asyncio
+    async def test_warmup_uses_real_request_structure(self) -> None:
+        cfg = _make_workload_config(num_prefixes=2)
+        w, sender, _, _ = _make_workload(cfg)
+        await w.warmup()
+
+        # The engine-warmup request (call 0) sends a tiny throwaway prompt;
+        # the pass-1 requests (calls 1..N) send full prefix+breaker+suffix.
+        warmup_messages = sender.send_warmup_request.call_args_list[0][0][1]
+        warmup_content = warmup_messages[0]["content"]
+        assert "PREFIX_" not in warmup_content  # throwaway, no real prefix
+        first_pass1_messages = sender.send_warmup_request.call_args_list[1][0][1]
+        first_pass1_content = first_pass1_messages[0]["content"]
+        assert "PREFIX_00000000" in first_pass1_content
+        assert w._suffix in first_pass1_content
+
+
+# ---------------------------------------------------------------------------
+# Pass 2 — step (async)
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerStep:
+    @pytest.mark.asyncio
+    async def test_step_sends_one_request_per_call(self) -> None:
+        cfg = _make_workload_config(num_prefixes=2)
+        w, sender, _, _ = _make_workload(cfg)
+
+        result = await w.step(0.0)
+        assert result == 0.0
+        assert sender.send_request.call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_step_terminates_after_pool_exhausted(self) -> None:
+        cfg = _make_workload_config(num_prefixes=2)
+        w, _, _, _ = _make_workload(cfg)
+
+        await w.step(0.0)
+        await w.step(0.0)
+        assert (await w.step(0.0)) == -1.0
+
+    @pytest.mark.asyncio
+    async def test_step_dispatches_in_pool_order(self) -> None:
+        cfg = _make_workload_config(num_prefixes=3)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.step(0.0)
+        await w.step(0.0)
+        await w.step(0.0)
+
+        ids = [call[0][0] for call in sender.send_request.call_args_list]
+        assert ids == ["pass2_p0", "pass2_p1", "pass2_p2"]
+
+    @pytest.mark.asyncio
+    async def test_step_uses_max_tokens_one(self) -> None:
+        cfg = _make_workload_config(num_prefixes=1)
+        w, sender, _, _ = _make_workload(cfg)
+        await w.step(0.0)
+        # send_request called with max_tokens=1
+        assert sender.send_request.call_args.kwargs["max_tokens"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Pass ordering — pass 1 and pass 2 use same prefix order, different breakers
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerTwoPassOrdering:
+    @pytest.mark.asyncio
+    async def test_pass1_and_pass2_share_prefix_order(self) -> None:
+        cfg = _make_workload_config(num_prefixes=4)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.warmup()
+        # Run pass 2 to exhaustion
+        while True:
+            r = await w.step(0.0)
+            if r < 0:
+                break
+
+        # Skip the engine-warmup throwaway call (call 0); pass-1 prefixes
+        # start at call 1.
+        warmup_prefixes = [
+            c[0][1][0]["content"].split()[0]
+            for c in sender.send_warmup_request.call_args_list[1:]
+        ]
+        bench_prefixes = [
+            c[0][1][0]["content"].split()[0] for c in sender.send_request.call_args_list
+        ]
+        # Same prefix sequence in both passes
+        assert warmup_prefixes == bench_prefixes
+        assert warmup_prefixes == [f"PREFIX_{i:08x}" for i in range(4)]
+
+    @pytest.mark.asyncio
+    async def test_pass1_and_pass2_use_different_breakers(self) -> None:
+        cfg = _make_workload_config(num_prefixes=2)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.warmup()
+        while True:
+            r = await w.step(0.0)
+            if r < 0:
+                break
+
+        # For prefix 0, the pass-1 and pass-2 prompts must differ
+        # (same prefix and suffix, but different random breaker).
+        # Note: call 0 of send_warmup_request is the engine warmup; pass-1
+        # prefix 0 is at call index 1.
+        pass1_prefix0 = sender.send_warmup_request.call_args_list[1][0][1][0]["content"]
+        pass2_prefix0 = sender.send_request.call_args_list[0][0][1][0]["content"]
+        assert pass1_prefix0 != pass2_prefix0
+
+
+# ---------------------------------------------------------------------------
+# Full run end-to-end
+# ---------------------------------------------------------------------------
+
+
+class TestPrefixSuffixTunerFullRun:
+    def test_full_run(self) -> None:
+        cfg = _make_workload_config(num_prefixes=3)
+        w, sender, collector, _ = _make_workload(cfg)
+
+        w.run()
+
+        # 1 engine warmup + 3 pass-1 prefixes = 4 warmup requests total
+        assert sender.send_warmup_request.call_count == 4
+        # Pass 2: 3 measured requests
+        assert sender.send_request.call_count == 3
+        # Stats reset between passes (warmup discarded)
+        collector.reset.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# LRU simulation — verifies the central design invariant
+#
+# The workload's value rests on a single algorithmic claim: with a sequential
+# pass-1 / pass-2 dispatch in identical order and a pool that just barely
+# overflows the targeted tier, every pass-2 access misses that tier.  These
+# tests prove that claim against an in-memory LRU model, using the access
+# order extracted from the actual workload.
+# ---------------------------------------------------------------------------
+
+
+def _simulate_lru(access_seq: list[int], capacity: int) -> tuple[int, int]:
+    """Replay *access_seq* against an LRU of *capacity*; return (hits, misses).
+
+    Args:
+        access_seq: Ordered list of cache keys to access.
+        capacity: Maximum number of entries the cache holds.
+
+    Returns:
+        Tuple of (hit_count, miss_count) over the full sequence.
+    """
+    cache: OrderedDict[int, bool] = OrderedDict()
+    hits = 0
+    misses = 0
+    for key in access_seq:
+        if key in cache:
+            cache.move_to_end(key)
+            hits += 1
+        else:
+            cache[key] = True
+            if len(cache) > capacity:
+                cache.popitem(last=False)
+            misses += 1
+    return hits, misses
+
+
+async def _capture_workload_access_order(
+    workload: PrefixSuffixTunerWorkload,
+    sender: MagicMock,
+) -> tuple[list[int], list[int]]:
+    """Run pass 1 + pass 2 and return the prefix-index access order of each.
+
+    The mocked *sender* records which prefix index it was asked to send.
+    The returned tuple lets tests assert on the order of pass 1 and pass
+    2 independently.
+    """
+    pass1: list[int] = []
+    pass2: list[int] = []
+
+    async def capture_warmup(req_id, _msgs, **_kw):
+        # request_id format: "pass1_p<index>" for cache-population requests;
+        # "engine_warmup" for the throwaway request before pass 1, which is
+        # not part of the access order under test.
+        if req_id == "engine_warmup":
+            return _make_mock_result(req_id)
+        pass1.append(int(req_id.split("_p")[1]))
+        return _make_mock_result(req_id)
+
+    async def capture_request(req_id, _msgs, **_kw):
+        pass2.append(int(req_id.split("_p")[1]))
+        return _make_mock_result(req_id)
+
+    sender.send_warmup_request = AsyncMock(side_effect=capture_warmup)
+    sender.send_request = AsyncMock(side_effect=capture_request)
+
+    await workload.warmup()
+    while True:
+        next_wake = await workload.step(0.0)
+        if next_wake < 0:
+            break
+    return pass1, pass2
+
+
+class TestLRUSimulator:
+    """Sanity checks on the LRU helper itself."""
+
+    def test_all_misses_when_no_repeats(self) -> None:
+        h, m = _simulate_lru([0, 1, 2, 3], capacity=10)
+        assert (h, m) == (0, 4)
+
+    def test_all_hits_after_repeat_within_capacity(self) -> None:
+        h, m = _simulate_lru([0, 1, 0, 1], capacity=10)
+        assert (h, m) == (2, 2)
+
+    def test_eviction_fifo_under_strict_lru(self) -> None:
+        # capacity 2; access 0, 1, 2 → evicts 0; access 0 → miss.
+        h, m = _simulate_lru([0, 1, 2, 0], capacity=2)
+        assert (h, m) == (0, 4)
+
+    def test_recent_access_promotes_to_mru(self) -> None:
+        # capacity 2; access 0, 1, 0, 2 → evicts 1 (LRU), not 0.
+        h, m = _simulate_lru([0, 1, 0, 2, 0], capacity=2)
+        # 0 (miss), 1 (miss), 0 (hit), 2 (miss; evict 1), 0 (hit)
+        assert (h, m) == (2, 3)
+
+
+class TestPrefixSuffixTunerWorkloadAccessOrder:
+    """Confirm the workload sends prefixes in identical sequential order
+    across both passes — the precondition for the LRU invariant below."""
+
+    @pytest.mark.asyncio
+    async def test_pass1_is_sequential(self) -> None:
+        cfg = _make_workload_config(num_prefixes=8)
+        w, sender, _, _ = _make_workload(cfg)
+        pass1, _ = await _capture_workload_access_order(w, sender)
+        assert pass1 == list(range(8))
+
+    @pytest.mark.asyncio
+    async def test_pass2_matches_pass1(self) -> None:
+        cfg = _make_workload_config(num_prefixes=8)
+        w, sender, _, _ = _make_workload(cfg)
+        pass1, pass2 = await _capture_workload_access_order(w, sender)
+        assert pass2 == pass1
+
+
+class TestPrefixSuffixTunerLRUInvariant:
+    """The central design claim: every pass-2 request misses the targeted
+    tier when the prefix pool is sized just larger than tier capacity."""
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "num_prefixes,capacity",
+        [
+            (21, 20),  # 1.05× overflow — the documented default
+            (40, 38),  # ~1.05× at a different scale
+            (100, 50),  # 2× overflow
+            (1000, 950),  # large pool, light overflow
+        ],
+    )
+    async def test_pass2_zero_hits_when_pool_overflows(
+        self, num_prefixes: int, capacity: int
+    ) -> None:
+        cfg = _make_workload_config(num_prefixes=num_prefixes)
+        w, sender, _, _ = _make_workload(cfg)
+        pass1, pass2 = await _capture_workload_access_order(w, sender)
+
+        # Pass 1 fills the cache; pass 2 must miss every entry in the
+        # targeted tier (capacity).  We measure pass-2 hits independently
+        # by replaying pass 1 first to populate the LRU, then pass 2.
+        cache: OrderedDict[int, bool] = OrderedDict()
+        for key in pass1:
+            cache[key] = True
+            if len(cache) > capacity:
+                cache.popitem(last=False)
+
+        pass2_hits = 0
+        pass2_misses = 0
+        for key in pass2:
+            if key in cache:
+                cache.move_to_end(key)
+                pass2_hits += 1
+            else:
+                cache[key] = True
+                if len(cache) > capacity:
+                    cache.popitem(last=False)
+                pass2_misses += 1
+
+        assert pass2_hits == 0, (
+            f"thrash invariant broken: {pass2_hits}/{num_prefixes} pass-2 "
+            f"requests hit a tier of capacity {capacity}"
+        )
+        assert pass2_misses == num_prefixes
+
+    @pytest.mark.asyncio
+    async def test_pass2_all_hits_when_pool_fits_in_tier(self) -> None:
+        # Counter-example: with pool ≤ capacity, pass 1 fills the cache
+        # without any eviction, so pass 2 is 100% hits.  This sanity-checks
+        # that the LRU sim correctly distinguishes "thrashing" from
+        # "cache-friendly" workloads.
+        cfg = _make_workload_config(num_prefixes=10)
+        w, sender, _, _ = _make_workload(cfg)
+        pass1, pass2 = await _capture_workload_access_order(w, sender)
+
+        cache: OrderedDict[int, bool] = OrderedDict()
+        capacity = 20  # tier larger than pool
+        for key in pass1:
+            cache[key] = True
+            if len(cache) > capacity:
+                cache.popitem(last=False)
+
+        pass2_hits = 0
+        for key in pass2:
+            if key in cache:
+                cache.move_to_end(key)
+                pass2_hits += 1
+            else:
+                cache[key] = True
+        assert pass2_hits == 10
+
+    @pytest.mark.asyncio
+    async def test_pass2_all_hits_when_pool_equals_tier(self) -> None:
+        # Boundary: pool == capacity (thrash == 1.0 exactly).  Pass 1 fills
+        # the cache to the brim, pass 2 is 100% hits.  This is why the
+        # default thrash is strictly > 1.0.
+        cfg = _make_workload_config(num_prefixes=15)
+        w, sender, _, _ = _make_workload(cfg)
+        pass1, pass2 = await _capture_workload_access_order(w, sender)
+
+        cache: OrderedDict[int, bool] = OrderedDict()
+        capacity = 15
+        for key in pass1:
+            cache[key] = True
+            if len(cache) > capacity:
+                cache.popitem(last=False)
+
+        pass2_hits = sum(1 for key in pass2 if key in cache)
+        assert pass2_hits == 15
diff --git a/tests/cli/commands/bench/engine_bench/workloads/test_random_prefill.py b/tests/cli/commands/bench/engine_bench/workloads/test_random_prefill.py
new file mode 100644
index 0000000..107331e
--- /dev/null
+++ b/tests/cli/commands/bench/engine_bench/workloads/test_random_prefill.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for random-prefill workload config and workload."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.engine_bench.stats import RequestResult
+from lmcache.cli.commands.bench.engine_bench.workloads.random_prefill import (
+    RandomPrefillConfig,
+    RandomPrefillWorkload,
+)
+
+# ---------------------------------------------------------------------------
+# RandomPrefillConfig — direct construction
+# ---------------------------------------------------------------------------
+
+
+class TestRandomPrefillConfig:
+    def test_defaults(self) -> None:
+        cfg = RandomPrefillConfig()
+        assert cfg.request_length == 10000
+        assert cfg.num_requests == 50
+
+    def test_custom_values(self) -> None:
+        cfg = RandomPrefillConfig(request_length=5000, num_requests=100)
+        assert cfg.request_length == 5000
+        assert cfg.num_requests == 100
+
+    def test_invalid_request_length(self) -> None:
+        with pytest.raises(ValueError, match="request_length must be positive"):
+            RandomPrefillConfig(request_length=0)
+
+    def test_invalid_request_length_negative(self) -> None:
+        with pytest.raises(ValueError, match="request_length must be positive"):
+            RandomPrefillConfig(request_length=-1)
+
+    def test_invalid_num_requests(self) -> None:
+        with pytest.raises(ValueError, match="num_requests must be >= 1"):
+            RandomPrefillConfig(num_requests=0)
+
+
+# ---------------------------------------------------------------------------
+# RandomPrefillConfig.resolve
+# ---------------------------------------------------------------------------
+
+
+class TestRandomPrefillConfigResolve:
+    def test_resolve_defaults(self) -> None:
+        cfg = RandomPrefillConfig.resolve()
+        assert cfg.request_length == 10000
+        assert cfg.num_requests == 50
+
+    def test_resolve_custom(self) -> None:
+        cfg = RandomPrefillConfig.resolve(
+            request_length=5000,
+            num_requests=20,
+        )
+        assert cfg.request_length == 5000
+        assert cfg.num_requests == 20
+
+
+# ---------------------------------------------------------------------------
+# RandomPrefillWorkload — helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_config(**overrides) -> RandomPrefillConfig:
+    defaults = dict(
+        request_length=100,
+        num_requests=5,
+    )
+    defaults.update(overrides)
+    return RandomPrefillConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_mock_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.1,
+        request_latency=0.5,
+        num_input_tokens=100,
+        num_output_tokens=1,
+        decode_speed=10.0,
+        submit_time=now,
+        first_token_time=now + 0.1,
+        finish_time=now + 0.5,
+        error="",
+    )
+
+
+def _make_mock_sender() -> MagicMock:
+    sender = MagicMock()
+    sender.send_request = AsyncMock(return_value=_make_mock_result())
+    sender.send_warmup_request = AsyncMock(return_value=_make_mock_result())
+    sender.close = AsyncMock(return_value=None)
+    return sender
+
+
+def _make_workload(
+    config: RandomPrefillConfig | None = None,
+    seed: int = 42,
+) -> tuple[RandomPrefillWorkload, MagicMock, MagicMock, MagicMock]:
+    if config is None:
+        config = _make_config()
+    sender = _make_mock_sender()
+    collector = MagicMock()
+    monitor = MagicMock()
+    workload = RandomPrefillWorkload(
+        config,
+        sender,
+        collector,
+        monitor,
+        seed=seed,
+    )
+    return workload, sender, collector, monitor
+
+
+# ---------------------------------------------------------------------------
+# RandomPrefillWorkload — prompt generation
+# ---------------------------------------------------------------------------
+
+
+class TestRandomPrefillPromptGeneration:
+    def test_correct_count(self) -> None:
+        w, *_ = _make_workload(_make_config(num_requests=10))
+        assert len(w._prompts) == 10
+
+    def test_prompt_format(self) -> None:
+        w, *_ = _make_workload(_make_config(num_requests=3))
+        assert w._prompts[0].startswith("Request 0: ")
+        assert w._prompts[1].startswith("Request 1: ")
+        assert w._prompts[2].startswith("Request 2: ")
+
+    def test_prompt_fill_tokens(self) -> None:
+        w, *_ = _make_workload(_make_config(request_length=100))
+        hi_count = w._prompts[0].count("hi")
+        assert hi_count == 90  # 100 - 10
+
+
+# ---------------------------------------------------------------------------
+# RandomPrefillWorkload — warmup
+# ---------------------------------------------------------------------------
+
+
+class TestRandomPrefillWarmup:
+    @pytest.mark.asyncio
+    async def test_warmup_is_noop(self) -> None:
+        w, sender, _, _ = _make_workload()
+        await w.warmup()
+        assert sender.send_warmup_request.call_count == 0
+        assert sender.send_request.call_count == 0
+
+
+# ---------------------------------------------------------------------------
+# RandomPrefillWorkload — step
+# ---------------------------------------------------------------------------
+
+
+class TestRandomPrefillStep:
+    @pytest.mark.asyncio
+    async def test_first_step_dispatches_all(self) -> None:
+        cfg = _make_config(num_requests=5)
+        w, sender, _, monitor = _make_workload(cfg)
+
+        result = await w.step(0.0)
+        assert result == 0.0
+        assert w._dispatched is True
+        assert len(w._pending_tasks) == 5
+        assert monitor.on_request_sent.call_count == 5
+
+        # Wait for tasks
+        # Standard
+        import asyncio
+
+        await asyncio.gather(*w._pending_tasks)
+        assert sender.send_request.call_count == 5
+
+        # Verify max_tokens=1
+        for call in sender.send_request.call_args_list:
+            assert call[1]["max_tokens"] == 1 or call[0][2] == 1
+
+    @pytest.mark.asyncio
+    async def test_second_step_does_not_redispatch(self) -> None:
+        cfg = _make_config(num_requests=3)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.step(0.0)
+        # Standard
+        import asyncio
+
+        await asyncio.gather(*w._pending_tasks)
+
+        # Second step — no pending, should return -1
+        result = await w.step(0.1)
+        assert result == -1.0
+        # Still only 3 calls
+        assert sender.send_request.call_count == 3
+
+    @pytest.mark.asyncio
+    async def test_returns_negative_when_all_done(self) -> None:
+        cfg = _make_config(num_requests=2)
+        w, _, _, _ = _make_workload(cfg)
+
+        await w.step(0.0)
+        # Standard
+        import asyncio
+
+        await asyncio.gather(*w._pending_tasks)
+
+        result = await w.step(0.5)
+        assert result == -1.0
+
+    @pytest.mark.asyncio
+    async def test_max_tokens_is_one(self) -> None:
+        cfg = _make_config(num_requests=1)
+        w, sender, _, _ = _make_workload(cfg)
+
+        await w.step(0.0)
+        # Standard
+        import asyncio
+
+        await asyncio.gather(*w._pending_tasks)
+
+        call_kwargs = sender.send_request.call_args[1]
+        assert call_kwargs["max_tokens"] == 1
+
+    def test_on_request_finished_noop(self) -> None:
+        w, *_ = _make_workload()
+        w.on_request_finished("prefill_0", "text")  # should not raise
+
+
+# ---------------------------------------------------------------------------
+# RandomPrefillWorkload — full run
+# ---------------------------------------------------------------------------
+
+
+class TestRandomPrefillFullRun:
+    def test_full_run(self) -> None:
+        cfg = _make_config(num_requests=5)
+        w, sender, collector, _ = _make_workload(cfg)
+
+        w.run()
+
+        # No warmup requests
+        assert sender.send_warmup_request.call_count == 0
+        # 5 benchmark requests
+        assert sender.send_request.call_count == 5
+        # Stats reset called
+        collector.reset.assert_called_once()
diff --git a/tests/cli/commands/bench/l2_adapter_bench/test_data.py b/tests/cli/commands/bench/l2_adapter_bench/test_data.py
new file mode 100644
index 0000000..affa8c7
--- /dev/null
+++ b/tests/cli/commands/bench/l2_adapter_bench/test_data.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.cli.commands.bench.l2_adapter_bench.data import (
+    create_l1_memory_desc,
+    make_aligned_tensor,
+    make_memory_objects,
+)
+
+
+def test_make_aligned_tensor_returns_aligned_buffer() -> None:
+    tensor = make_aligned_tensor(4096 * 3, align_bytes=4096)
+
+    assert tensor.numel() == 4096 * 3
+    assert tensor.dtype == torch.uint8
+    assert tensor.data_ptr() % 4096 == 0
+
+
+def test_create_l1_memory_desc_uses_requested_alignment() -> None:
+    tensor = make_aligned_tensor(8192, align_bytes=4096)
+
+    desc = create_l1_memory_desc(tensor, align_bytes=4096)
+
+    assert desc.ptr == tensor.data_ptr()
+    assert desc.size == 8192
+    assert desc.align_bytes == 4096
+
+
+def test_make_memory_objects_uses_shared_l1_range() -> None:
+    buffer = make_aligned_tensor(4096, align_bytes=1024)
+
+    objects = make_memory_objects(
+        buffer,
+        num_keys=2,
+        data_size=1024,
+        base_offset=1024,
+    )
+
+    assert len(objects) == 2
+    assert objects[0].raw_data.data_ptr() == buffer.data_ptr() + 1024
+    assert objects[1].raw_data.data_ptr() == buffer.data_ptr() + 2048
+    assert torch.all(objects[0].raw_data == 0)
+    assert torch.all(objects[1].raw_data == 1)
+
+
+def test_make_memory_objects_can_use_different_fill_pattern() -> None:
+    buffer = make_aligned_tensor(2048, align_bytes=1024)
+
+    objects = make_memory_objects(
+        buffer,
+        num_keys=2,
+        data_size=1024,
+        base_offset=0,
+        fill_offset=1,
+    )
+
+    assert torch.all(objects[0].raw_data == 1)
+    assert torch.all(objects[1].raw_data == 2)
diff --git a/tests/cli/commands/bench/l2_adapter_bench/test_profiling.py b/tests/cli/commands/bench/l2_adapter_bench/test_profiling.py
new file mode 100644
index 0000000..2ea2dcc
--- /dev/null
+++ b/tests/cli/commands/bench/l2_adapter_bench/test_profiling.py
@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Test for the L2 adapter benchmark flame-graph profiler."""
+
+# Standard
+from pathlib import Path
+import os
+import shutil
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench.l2_adapter_bench.profiling import (
+    FlameProfiler,
+    ProfileError,
+    check_profiling_deps,
+)
+
+
+def test_check_profiling_deps_missing_tool_is_actionable(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A missing tool names the tool and how to recover.
+
+    Runs on any machine: the toolchain is faked absent via monkeypatch,
+    so this never skips and always exercises the error path.
+    """
+    monkeypatch.setattr(shutil, "which", lambda _name: None)
+
+    with pytest.raises(ProfileError) as excinfo:
+        check_profiling_deps("on-cpu")
+
+    message = str(excinfo.value)
+    assert "perf" in message
+    # Actionable: points at the fallback mode.
+    assert "off-cpu" in message
+
+
+def test_flame_profiler_builds_with_real_toolchain(tmp_path: Path) -> None:
+    if shutil.which("perf") is None:
+        pytest.skip("perf not installed; flame-graph profiling unavailable")
+
+    scripts_dir = tmp_path / "FlameGraph"
+    scripts_dir.mkdir()
+    (scripts_dir / "flamegraph.pl").write_text("#!/usr/bin/perl\n")
+    output = tmp_path / "flames" / "out.svg"
+
+    FlameProfiler(
+        mode="on-cpu",
+        output=str(output),
+        flamegraph_dir=str(scripts_dir),
+        pid=os.getpid(),
+        title="test",
+    )
+
+    # The component validated the toolchain and prepared the output dir.
+    assert output.parent.is_dir()
diff --git a/tests/cli/commands/bench/test_bench_command.py b/tests/cli/commands/bench/test_bench_command.py
new file mode 100644
index 0000000..b932041
--- /dev/null
+++ b/tests/cli/commands/bench/test_bench_command.py
@@ -0,0 +1,714 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the BenchCommand CLI wiring and orchestrator."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock, patch
+import argparse
+import io
+import json
+import sys
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.bench import BenchCommand
+from lmcache.cli.commands.bench.engine_bench.command import (
+    _emit_final_metrics,
+    _resolve_args,
+    run_engine_bench,
+)
+from lmcache.cli.commands.bench.engine_bench.config import EngineBenchConfig
+from lmcache.cli.commands.bench.engine_bench.stats import (
+    FinalStats,
+    RequestResult,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_args(**overrides) -> argparse.Namespace:
+    defaults = dict(
+        bench_target="engine",
+        engine_url="http://localhost:8000",
+        lmcache_url=None,
+        model="test-model",
+        workload="long-doc-qa",
+        kv_cache_volume=100.0,
+        tokens_per_gb_kvcache=50000,
+        seed=42,
+        output_dir=".",
+        no_csv=False,
+        json=False,
+        quiet=True,
+        ignore_eos=False,
+        ldqa_document_length=100,
+        ldqa_query_per_document=1,
+        ldqa_shuffle_policy="tile",
+        ldqa_num_inflight_requests=1,
+        ldqa_max_output_length=128,
+        mrc_shared_prompt_length=2000,
+        mrc_chat_history_length=10000,
+        mrc_user_input_length=50,
+        mrc_output_length=200,
+        mrc_qps=1.0,
+        mrc_duration=60.0,
+        rp_request_length=10000,
+        rp_num_requests=50,
+        format=None,
+        output=None,
+        config=None,
+        no_interactive=False,
+        export_config=None,
+    )
+    defaults.update(overrides)
+    return argparse.Namespace(**defaults)
+
+
+def _make_config(**overrides) -> EngineBenchConfig:
+    defaults = dict(
+        engine_url="http://localhost:8000",
+        model="test-model",
+        workload="long-doc-qa",
+        kv_cache_volume_gb=100.0,
+        tokens_per_gb_kvcache=50000,
+        seed=42,
+        output_dir=".",
+        export_csv=True,
+        export_json=False,
+        quiet=True,
+    )
+    defaults.update(overrides)
+    return EngineBenchConfig(**defaults)  # type: ignore[arg-type]
+
+
+def _make_final_stats(**overrides) -> FinalStats:
+    defaults: dict[str, int | float] = dict(
+        total_requests=10,
+        successful_requests=10,
+        failed_requests=0,
+        elapsed_time=5.0,
+        mean_ttft_ms=300.0,
+        mean_decode_speed=48.0,
+        mean_request_latency_ms=2000.0,
+        input_throughput=20000.0,
+        output_throughput=256.0,
+        total_input_tokens=100000,
+        total_output_tokens=1280,
+        p50_ttft_ms=280.0,
+        p90_ttft_ms=450.0,
+        p99_ttft_ms=600.0,
+        p50_decode_speed=47.0,
+        p90_decode_speed=42.0,
+        p99_decode_speed=38.0,
+        p50_request_latency_ms=1900.0,
+        p90_request_latency_ms=2500.0,
+        p99_request_latency_ms=3000.0,
+    )
+    defaults.update(overrides)
+    return FinalStats(**defaults)  # type: ignore[arg-type]
+
+
+def _make_result(request_id: str = "req_0") -> RequestResult:
+    now = time.time()
+    return RequestResult(
+        request_id=request_id,
+        successful=True,
+        ttft=0.3,
+        request_latency=2.0,
+        num_input_tokens=100,
+        num_output_tokens=10,
+        decode_speed=25.0,
+        submit_time=now,
+        first_token_time=now + 0.3,
+        finish_time=now + 2.0,
+        error="",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+
+class TestBenchCommandRegistration:
+    def test_bench_in_all_commands(self) -> None:
+        # First Party
+        from lmcache.cli.commands import ALL_COMMANDS
+
+        names = [cmd.name() for cmd in ALL_COMMANDS]
+        assert "bench" in names
+
+    def test_engine_subparser_exists(self) -> None:
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        cmd = BenchCommand()
+        cmd.register(subparsers)
+
+        args = parser.parse_args(
+            [
+                "bench",
+                "engine",
+                "--engine-url",
+                "http://localhost:8000",
+                "--workload",
+                "long-doc-qa",
+                "--tokens-per-gb-kvcache",
+                "50000",
+            ]
+        )
+        assert args.bench_target == "engine"
+        assert args.engine_url == "http://localhost:8000"
+        assert args.workload == "long-doc-qa"
+        assert args.tokens_per_gb_kvcache == 50000
+
+    def test_optional_args_parse_without_engine_url(self) -> None:
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        cmd = BenchCommand()
+        cmd.register(subparsers)
+
+        # engine-url and workload are now optional (for interactive mode)
+        args = parser.parse_args(["bench", "engine"])
+        assert args.engine_url is None
+        assert args.workload is None
+
+    def test_config_flag_accepted(self) -> None:
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        cmd = BenchCommand()
+        cmd.register(subparsers)
+
+        args = parser.parse_args(["bench", "engine", "--config", "my_config.json"])
+        assert args.config == "my_config.json"
+
+    def test_default_values(self) -> None:
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        cmd = BenchCommand()
+        cmd.register(subparsers)
+
+        args = parser.parse_args(
+            [
+                "bench",
+                "engine",
+                "--engine-url",
+                "http://localhost:8000",
+                "--workload",
+                "long-doc-qa",
+                "--tokens-per-gb-kvcache",
+                "50000",
+            ]
+        )
+        assert args.kv_cache_volume == 100.0
+        assert args.seed == 42
+        assert args.output_dir == "."
+        assert args.ldqa_document_length == 10000
+        assert args.ldqa_query_per_document == 2
+        assert args.ldqa_shuffle_policy == "random"
+        assert args.ldqa_num_inflight_requests == 3
+        assert args.quiet is False
+
+
+# ---------------------------------------------------------------------------
+# --no-interactive
+# ---------------------------------------------------------------------------
+
+
+class TestNoInteractive:
+    def test_no_interactive_flag_accepted(self) -> None:
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        cmd = BenchCommand()
+        cmd.register(subparsers)
+
+        args = parser.parse_args(["bench", "engine", "--no-interactive"])
+        assert args.no_interactive is True
+
+    def test_no_interactive_missing_engine_url(self) -> None:
+        args = _make_args(
+            engine_url=None,
+            workload="long-doc-qa",
+            tokens_per_gb_kvcache=6553,
+            no_interactive=True,
+        )
+        with pytest.raises(SystemExit, match="--engine-url"):
+            _resolve_args(args)
+
+    def test_no_interactive_missing_workload(self) -> None:
+        args = _make_args(
+            engine_url="http://localhost:8000",
+            workload=None,
+            tokens_per_gb_kvcache=6553,
+            no_interactive=True,
+        )
+        with pytest.raises(SystemExit, match="--workload"):
+            _resolve_args(args)
+
+    def test_no_interactive_missing_tokens_and_lmcache(self) -> None:
+        args = _make_args(
+            engine_url="http://localhost:8000",
+            workload="long-doc-qa",
+            tokens_per_gb_kvcache=None,
+            lmcache_url=None,
+            no_interactive=True,
+        )
+        with pytest.raises(
+            SystemExit, match="--tokens-per-gb-kvcache or --lmcache-url"
+        ):
+            _resolve_args(args)
+
+    def test_no_interactive_passes_with_all_args(self) -> None:
+        args = _make_args(no_interactive=True)
+        result = _resolve_args(args)
+        assert result is args
+
+    def test_no_interactive_passes_with_lmcache_url(self) -> None:
+        args = _make_args(
+            tokens_per_gb_kvcache=None,
+            lmcache_url="http://localhost:8080",
+            no_interactive=True,
+        )
+        result = _resolve_args(args)
+        assert result is args
+
+
+# ---------------------------------------------------------------------------
+# --export-config
+# ---------------------------------------------------------------------------
+
+
+class TestExportConfig:
+    def test_export_config_flag_accepted(self) -> None:
+        parser = argparse.ArgumentParser()
+        subparsers = parser.add_subparsers()
+        cmd = BenchCommand()
+        cmd.register(subparsers)
+
+        args = parser.parse_args(
+            [
+                "bench",
+                "engine",
+                "--engine-url",
+                "http://localhost:8000",
+                "--workload",
+                "long-doc-qa",
+                "--tokens-per-gb-kvcache",
+                "6553",
+                "--export-config",
+                "out.json",
+            ]
+        )
+        assert args.export_config == "out.json"
+
+    def test_export_config_errors_when_missing_args(self) -> None:
+        args = _make_args(
+            engine_url=None,
+            export_config="out.json",
+        )
+        with pytest.raises(SystemExit, match="--engine-url"):
+            _resolve_args(args)
+
+    def test_export_config_writes_json(self, tmp_path) -> None:  # type: ignore[no-untyped-def]
+        export_path = str(tmp_path / "exported.json")
+        args = _make_args(
+            export_config=export_path,
+            quiet=True,
+        )
+
+        cmd = BenchCommand()
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            run_engine_bench(cmd, args)
+        finally:
+            sys.stdout = old_stdout
+
+        with open(export_path) as f:
+            data = json.load(f)
+
+        assert "engine_url" not in data
+        assert data["workload"] == "long-doc-qa"
+        assert data["tokens_per_gb_kvcache"] == 50000
+        assert "lmcache_url" not in data
+
+    def test_max_output_length_rejected_for_unsupported_workload(
+        self,
+        tmp_path,  # type: ignore[no-untyped-def]
+    ) -> None:
+        # Setting a non-default max output length for a workload without that
+        # parameter is rejected.
+        args = _make_args(
+            workload="random-prefill",
+            ldqa_max_output_length=512,
+            export_config=str(tmp_path / "exported.json"),
+        )
+        with pytest.raises(ValueError, match="max output length cannot be specified"):
+            run_engine_bench(BenchCommand(), args)
+
+    def test_export_config_excludes_lmcache_url(
+        self,
+        tmp_path,  # type: ignore[no-untyped-def]
+    ) -> None:
+        export_path = str(tmp_path / "exported.json")
+        args = _make_args(
+            lmcache_url="http://localhost:8080",
+            export_config=export_path,
+            quiet=True,
+        )
+
+        cmd = BenchCommand()
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            run_engine_bench(cmd, args)
+        finally:
+            sys.stdout = old_stdout
+
+        with open(export_path) as f:
+            data = json.load(f)
+
+        assert "lmcache_url" not in data
+        assert data["tokens_per_gb_kvcache"] == 50000
+
+    def test_export_config_includes_workload_args(
+        self,
+        tmp_path,  # type: ignore[no-untyped-def]
+    ) -> None:
+        export_path = str(tmp_path / "exported.json")
+        args = _make_args(
+            workload="long-doc-qa",
+            ldqa_document_length=5000,
+            ldqa_query_per_document=4,
+            export_config=export_path,
+            quiet=True,
+        )
+
+        cmd = BenchCommand()
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            run_engine_bench(cmd, args)
+        finally:
+            sys.stdout = old_stdout
+
+        with open(export_path) as f:
+            data = json.load(f)
+
+        assert data["ldqa_document_length"] == 5000
+        assert data["ldqa_query_per_document"] == 4
+
+
+# ---------------------------------------------------------------------------
+# Final metrics emission
+# ---------------------------------------------------------------------------
+
+
+class TestBenchCommandEmitMetrics:
+    def test_emit_final_metrics_terminal(self) -> None:
+        cmd = BenchCommand()
+        config = _make_config()
+        final = _make_final_stats()
+        args = _make_args(quiet=False)
+
+        old_stdout = sys.stdout
+        sys.stdout = buf = io.StringIO()
+        try:
+            _emit_final_metrics(cmd, config, final, args)
+        finally:
+            sys.stdout = old_stdout
+
+        output = buf.getvalue()
+        assert "Engine Benchmark Result" in output
+        assert "Configuration" in output
+        assert "Time to First Token" in output
+        assert "Decoding Speed" in output
+        assert "test-model" in output
+
+    def test_emit_final_metrics_json(self) -> None:
+        cmd = BenchCommand()
+        config = _make_config()
+        final = _make_final_stats()
+        args = _make_args(quiet=False, format="json")
+
+        old_stdout = sys.stdout
+        sys.stdout = buf = io.StringIO()
+        try:
+            _emit_final_metrics(cmd, config, final, args)
+        finally:
+            sys.stdout = old_stdout
+
+        data = json.loads(buf.getvalue())
+        assert "metrics" in data
+        assert "ttft" in data["metrics"]
+        assert "decode" in data["metrics"]
+        assert data["metrics"]["config"]["model"] == "test-model"
+        assert data["metrics"]["results"]["successful"] == 10
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+
+class TestBenchCommandOrchestrator:
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.config.resolve_tokens_per_gb",
+        return_value=6553,
+    )
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    def test_lmcache_url_resolves(
+        self,
+        mock_openai_cls,
+        mock_resolve,
+        tmp_path,
+    ) -> None:
+        """When --lmcache-url is set, tokens_per_gb is resolved from server."""
+        # Third Party
+        from openai.types import CompletionUsage
+        from openai.types.chat import ChatCompletionChunk
+        from openai.types.chat.chat_completion_chunk import (
+            Choice,
+            ChoiceDelta,
+        )
+
+        usage = CompletionUsage(
+            prompt_tokens=100,
+            completion_tokens=10,
+            total_tokens=110,
+        )
+
+        async def _fake_stream(*_args, **_kwargs):
+            yield ChatCompletionChunk(
+                id="c1",
+                choices=[
+                    Choice(
+                        delta=ChoiceDelta(content="Hi"),
+                        index=0,
+                    )
+                ],
+                created=0,
+                model="test-model",
+                object="chat.completion.chunk",
+            )
+            yield ChatCompletionChunk(
+                id="c1",
+                choices=[],
+                created=0,
+                model="test-model",
+                object="chat.completion.chunk",
+                usage=usage,
+            )
+
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            side_effect=lambda **kw: _fake_stream(),
+        )
+        mock_client.close = AsyncMock()
+
+        args = _make_args(
+            lmcache_url="http://localhost:8080",
+            tokens_per_gb_kvcache=None,
+            kv_cache_volume=0.001,
+            ldqa_document_length=100,
+            ldqa_query_per_document=1,
+            ldqa_num_inflight_requests=1,
+            output_dir=str(tmp_path),
+            no_csv=True,
+        )
+
+        cmd = BenchCommand()
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            run_engine_bench(cmd, args)
+        finally:
+            sys.stdout = old_stdout
+
+        mock_resolve.assert_called_once_with(
+            "http://localhost:8080",
+            "test-model",
+        )
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    def test_bench_engine_wiring(
+        self,
+        mock_openai_cls,
+        tmp_path,
+    ) -> None:
+        """End-to-end orchestrator test with mocked OpenAI client."""
+        # Third Party
+        from openai.types import CompletionUsage
+        from openai.types.chat import ChatCompletionChunk
+        from openai.types.chat.chat_completion_chunk import (
+            Choice,
+            ChoiceDelta,
+        )
+
+        def _make_chunk(content="", usage=None):
+            choices = []
+            if content:
+                choices.append(
+                    Choice(
+                        delta=ChoiceDelta(content=content),
+                        index=0,
+                    )
+                )
+            return ChatCompletionChunk(
+                id="c1",
+                choices=choices,
+                created=0,
+                model="test-model",
+                object="chat.completion.chunk",
+                usage=usage,
+            )
+
+        usage = CompletionUsage(
+            prompt_tokens=100,
+            completion_tokens=10,
+            total_tokens=110,
+        )
+
+        async def _fake_stream(*_args, **_kwargs):
+            yield _make_chunk(content="Hello")
+            yield _make_chunk(content=" world")
+            yield _make_chunk(usage=usage)
+
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            side_effect=lambda **kw: _fake_stream(),
+        )
+        mock_client.close = AsyncMock()
+
+        output_dir = str(tmp_path)
+        args = _make_args(
+            kv_cache_volume=0.001,
+            tokens_per_gb_kvcache=1000,
+            ldqa_document_length=100,
+            ldqa_query_per_document=1,
+            ldqa_num_inflight_requests=1,
+            output_dir=output_dir,
+            no_csv=False,
+            json=True,
+            quiet=True,
+        )
+
+        cmd = BenchCommand()
+        # Suppress stdout for metrics emission
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            run_engine_bench(cmd, args)
+        finally:
+            sys.stdout = old_stdout
+
+        # Verify CSV was written
+        csv_path = tmp_path / "bench_results.csv"
+        assert csv_path.exists()
+
+        # Verify JSON was written
+        json_path = tmp_path / "bench_summary.json"
+        assert json_path.exists()
+        with open(json_path) as f:
+            data = json.load(f)
+        assert "config" in data
+        assert "results" in data
+        assert data["results"]["total_requests"] > 0
+
+    @patch(
+        "lmcache.cli.commands.bench.engine_bench.request_sender.AsyncOpenAI",
+    )
+    def test_config_file_loading(
+        self,
+        mock_openai_cls,
+        tmp_path,
+    ) -> None:
+        """Benchmark runs correctly from a --config JSON file."""
+        # Third Party
+        from openai.types import CompletionUsage
+        from openai.types.chat import ChatCompletionChunk
+        from openai.types.chat.chat_completion_chunk import (
+            Choice,
+            ChoiceDelta,
+        )
+
+        def _make_chunk(content="", usage=None):
+            choices = []
+            if content:
+                choices.append(
+                    Choice(
+                        delta=ChoiceDelta(content=content),
+                        index=0,
+                    )
+                )
+            return ChatCompletionChunk(
+                id="c1",
+                choices=choices,
+                created=0,
+                model="test-model",
+                object="chat.completion.chunk",
+                usage=usage,
+            )
+
+        usage = CompletionUsage(
+            prompt_tokens=100,
+            completion_tokens=10,
+            total_tokens=110,
+        )
+
+        async def _fake_stream(*_args, **_kwargs):
+            yield _make_chunk(content="Hello")
+            yield _make_chunk(usage=usage)
+
+        mock_client = MagicMock()
+        mock_openai_cls.return_value = mock_client
+        mock_client.chat.completions.create = AsyncMock(
+            side_effect=lambda **kw: _fake_stream(),
+        )
+        mock_client.close = AsyncMock()
+
+        # Write a config JSON file
+        config_data = {
+            "engine_url": "http://localhost:8000",
+            "model": "test-model",
+            "workload": "long-doc-qa",
+            "tokens_per_gb_kvcache": 1000,
+            "kv_cache_volume": 0.001,
+            "ldqa_document_length": 100,
+            "ldqa_query_per_document": 1,
+            "ldqa_shuffle_policy": "tile",
+            "ldqa_num_inflight_requests": 1,
+        }
+        config_path = tmp_path / "test_config.json"
+        with open(config_path, "w") as f:
+            json.dump(config_data, f)
+
+        args = _make_args(
+            config=str(config_path),
+            engine_url=None,
+            workload=None,
+            tokens_per_gb_kvcache=None,
+            output_dir=str(tmp_path),
+            no_csv=True,
+            quiet=True,
+        )
+
+        cmd = BenchCommand()
+        old_stdout = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            run_engine_bench(cmd, args)
+        finally:
+            sys.stdout = old_stdout
+
+        # Verify benchmark ran — sender was called
+        assert mock_client.chat.completions.create.call_count > 0
diff --git a/tests/cli/commands/bench/test_server_bench.py b/tests/cli/commands/bench/test_server_bench.py
new file mode 100644
index 0000000..bd948bc
--- /dev/null
+++ b/tests/cli/commands/bench/test_server_bench.py
@@ -0,0 +1,625 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the ``lmcache bench server`` CLI command.
+
+Covers:
+- Sub-command registration under ``lmcache bench``
+- Argument registration and defaults
+- Pure helper functions (_build_token_ids, _make_key, _query_checksum)
+"""
+
+# Standard
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import argparse
+import json
+import threading
+
+# Third Party
+import msgspec
+import pytest
+import torch
+import zmq
+
+# First Party
+from lmcache.cli.commands.bench import BenchCommand
+from lmcache.cli.commands.bench.server_bench.helpers import (
+    _allocate_kv_cache,
+    _build_token_ids,
+    _make_key,
+    _poll_prefetch_status,
+    _query_checksum,
+    _send_lookup,
+    _send_unregister_kv_cache,
+)
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocols.base import RequestType
+
+# ------------------------------------------------------------------ #
+#  Fixtures
+# ------------------------------------------------------------------ #
+
+
+@pytest.fixture
+def cmd() -> BenchCommand:
+    return BenchCommand()
+
+
+@pytest.fixture
+def parser(cmd: BenchCommand) -> argparse.ArgumentParser:
+    """Parser with ``bench server`` subcommand registered."""
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers(dest="command")
+    cmd.register(sub)
+    return p
+
+
+# ------------------------------------------------------------------ #
+#  Command metadata
+# ------------------------------------------------------------------ #
+
+
+class TestCommandMetadata:
+    def test_name(self, cmd: BenchCommand) -> None:
+        assert cmd.name() == "bench"
+
+    def test_help(self, cmd: BenchCommand) -> None:
+        assert "benchmark" in cmd.help().lower()
+
+    def test_server_helpers_live_under_server_bench_package(self) -> None:
+        """Helpers backing ``bench server`` must live inside the
+        ``server_bench`` sub-package, mirroring the engine / l2 layout.
+        """
+        # First Party
+        from lmcache.cli.commands.bench.server_bench import command as sv_cmd
+        from lmcache.cli.commands.bench.server_bench import helpers as sv_helpers
+
+        assert sv_cmd.__name__ == ("lmcache.cli.commands.bench.server_bench.command")
+        assert sv_helpers.__name__ == (
+            "lmcache.cli.commands.bench.server_bench.helpers"
+        )
+        # Public command surface mirrors the sibling subpackages.
+        assert callable(sv_cmd.add_server_arguments)
+        assert callable(sv_cmd.run_server_bench)
+
+
+# ------------------------------------------------------------------ #
+#  Argument registration
+# ------------------------------------------------------------------ #
+
+
+class TestCommandArguments:
+    def test_registers_subcommand(
+        self,
+        parser: argparse.ArgumentParser,
+    ) -> None:
+        args = parser.parse_args(["bench", "server"])
+        assert hasattr(args, "func")
+        assert args.bench_target == "server"
+
+    def test_default_values(
+        self,
+        parser: argparse.ArgumentParser,
+    ) -> None:
+        args = parser.parse_args(["bench", "server"])
+        assert args.rpc_url == "tcp://localhost:5555"
+        assert args.mode == "gpu"
+        assert args.num_tokens == 512
+        assert args.num_blocks == 1024
+        assert args.block_size == 16
+        assert args.start == 0
+        assert args.end is None
+        assert args.interval == 0.5
+        assert args.url == "http://localhost:8080"
+
+    def test_custom_values(
+        self,
+        parser: argparse.ArgumentParser,
+    ) -> None:
+        args = parser.parse_args(
+            [
+                "bench",
+                "server",
+                "--rpc-url",
+                "tcp://host:9999",
+                "--num-tokens",
+                "256",
+                "--num-blocks",
+                "512",
+                "--block-size",
+                "8",
+                "--start",
+                "5",
+                "--end",
+                "10",
+                "--interval",
+                "1.0",
+                "--url",
+                "http://other:9090",
+            ],
+        )
+        assert args.rpc_url == "tcp://host:9999"
+        assert args.num_tokens == 256
+        assert args.num_blocks == 512
+        assert args.block_size == 8
+        assert args.start == 5
+        assert args.end == 10
+        assert args.interval == 1.0
+        assert args.url == "http://other:9090"
+
+    def test_kvcache_shape_spec_default(
+        self,
+        parser: argparse.ArgumentParser,
+    ) -> None:
+        args = parser.parse_args(["bench", "server"])
+        assert "float16" in args.kvcache_shape_spec
+
+    def test_kvcache_shape_spec_custom(
+        self,
+        parser: argparse.ArgumentParser,
+    ) -> None:
+        args = parser.parse_args(
+            [
+                "bench",
+                "server",
+                "--kvcache-shape-spec",
+                "(2,512,8,4,64):bfloat16:16",
+            ],
+        )
+        assert args.kvcache_shape_spec == ("(2,512,8,4,64):bfloat16:16")
+
+
+# ------------------------------------------------------------------ #
+#  _build_token_ids
+# ------------------------------------------------------------------ #
+
+
+class TestBuildTokenIds:
+    def test_basic(self):
+        ids = _build_token_ids(seq_no=7, num_tokens=3)
+        assert ids[0] == 7
+        assert len(ids) == 4  # seq_no + 3 hello tokens
+        # All remaining tokens should be the hello token
+        assert all(t == 9906 for t in ids[1:])
+
+    def test_zero_tokens(self):
+        ids = _build_token_ids(seq_no=0, num_tokens=0)
+        assert ids == (0,)
+
+    def test_different_seq_no(self):
+        ids1 = _build_token_ids(seq_no=1, num_tokens=2)
+        ids2 = _build_token_ids(seq_no=2, num_tokens=2)
+        assert ids1[0] != ids2[0]
+        assert ids1[1:] == ids2[1:]
+
+
+# ------------------------------------------------------------------ #
+#  _make_key
+# ------------------------------------------------------------------ #
+
+
+class TestMakeKey:
+    def test_basic_key(self):
+        token_ids = (0, 9906, 9906)
+        key = _make_key(
+            token_ids,
+            request_id="req-0-cold",
+        )
+        assert key.model_name == "test-model"
+        assert key.world_size == 1
+        assert key.worker_id is None
+        assert key.token_ids == token_ids
+        assert key.start == 0
+        assert key.end == len(token_ids)
+        assert key.request_id == "req-0-cold"
+
+    def test_custom_start_end(self):
+        token_ids = (0, 9906, 9906, 9906, 9906)
+        key = _make_key(
+            token_ids,
+            request_id="req-1-warm",
+            start=2,
+            end=4,
+        )
+        assert key.start == 2
+        assert key.end == 4
+
+    def test_worker_id(self):
+        token_ids = (0, 9906)
+        key = _make_key(
+            token_ids,
+            request_id="req-0-cold",
+            worker_id=0,
+        )
+        assert key.worker_id == 0
+
+
+# ------------------------------------------------------------------ #
+#  _query_checksum
+# ------------------------------------------------------------------ #
+
+
+class _ChecksumHandler(BaseHTTPRequestHandler):
+    """Tiny HTTP handler that records the POST body and returns fake checksums.
+
+    Mirrors the MP server's ``POST /cache/checksums`` (the old ``GET
+    /kvcache/check`` was removed). The received JSON is stored on the server so
+    the test can assert the request shape ``_query_checksum`` sends.
+    """
+
+    def do_POST(self):
+        if "/cache/checksums" not in self.path:
+            self.send_response(404)
+            self.end_headers()
+            return
+        length = int(self.headers.get("Content-Length", 0))
+        payload = json.loads(self.rfile.read(length).decode())
+        self.server.received_payloads.append(payload)
+        body = json.dumps(
+            {
+                "status": "success",
+                "chunk_checksums": ["a" * 32, "b" * 32],
+            }
+        ).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format, *args):
+        pass  # suppress logs
+
+
+class TestQueryChecksum:
+    @pytest.fixture(autouse=True)
+    def _start_server(self):
+        """Start a tiny HTTP server for the test."""
+        self.server = HTTPServer(
+            ("127.0.0.1", 0),
+            _ChecksumHandler,
+        )
+        self.server.received_payloads = []
+        self.port = self.server.server_address[1]
+        self.thread = threading.Thread(
+            target=self.server.serve_forever,
+        )
+        self.thread.daemon = True
+        self.thread.start()
+        yield
+        self.server.shutdown()
+
+    def test_success(self):
+        base = "http://127.0.0.1:%d" % self.port
+        result = _query_checksum(
+            base,
+            block_offset=0,
+            num_blocks=2,
+            block_size=2,
+            chunk_size=2,
+        )
+        assert result is not None
+        assert len(result) == 2
+        assert result[0] == "a" * 32
+        # The POST body matches the MP /cache/checksums contract: block-native
+        # ids and a block-level chunk_size (token chunk_size 2 / block_size 2).
+        assert len(self.server.received_payloads) == 1
+        sent = self.server.received_payloads[0]
+        assert sent["block_ids"] == [0, 1]
+        assert sent["chunk_size"] == 1
+        assert sent["layerwise"] is False
+
+    def test_unreachable_returns_none(self):
+        result = _query_checksum(
+            "http://127.0.0.1:1",
+            block_offset=0,
+            num_blocks=2,
+            block_size=2,
+            chunk_size=2,
+        )
+        assert result is None
+
+
+# ------------------------------------------------------------------ #
+#  ROUTER endpoint fixture                                             #
+# ------------------------------------------------------------------ #
+
+
+@pytest.fixture
+def router_endpoint() -> str:
+    """Allocate an ephemeral inproc/tcp endpoint for the ROUTER."""
+    # Use tcp with port=0 so the OS assigns a free port.
+    ctx = zmq.Context.instance()
+    probe = ctx.socket(zmq.ROUTER)
+    probe.bind("tcp://127.0.0.1:0")
+    endpoint = probe.getsockopt_string(zmq.LAST_ENDPOINT)
+    probe.close(linger=0)
+    return endpoint
+
+
+# ------------------------------------------------------------------ #
+#  _allocate_kv_cache (dtype branching)
+# ------------------------------------------------------------------ #
+
+
+class TestAllocateKVCache:
+    """Regression tests for ``_allocate_kv_cache`` dtype handling.
+
+    ``torch.randn`` only supports floating-point dtypes, so integer
+    dtypes in ``DTYPE_MAP`` (e.g. ``uint8`` used by FP8 quantized
+    layouts) must fall back to ``torch.randint`` -- see Bugbot
+    #3147565172.
+    """
+
+    @staticmethod
+    def _alloc(dtype: torch.dtype) -> list[torch.Tensor]:
+        return _allocate_kv_cache(
+            num_layers=1,
+            num_heads=2,
+            head_size=4,
+            num_blocks=2,
+            block_size=2,
+            dtype=dtype,
+            device="cpu",
+            kv_size=2,
+        )
+
+    @pytest.mark.parametrize(
+        "dtype",
+        [torch.float16, torch.float32, torch.bfloat16],
+    )
+    def test_floating_point_dtype(self, dtype: torch.dtype) -> None:
+        tensors = self._alloc(dtype)
+        assert len(tensors) == 1
+        assert tensors[0].dtype == dtype
+        assert tensors[0].shape == (2, 2, 2, 2, 4)
+
+    def test_uint8_dtype_uses_randint(self) -> None:
+        """Regression: ``torch.randn`` crashes with integer dtypes."""
+        tensors = self._alloc(torch.uint8)
+        assert len(tensors) == 1
+        assert tensors[0].dtype == torch.uint8
+        assert tensors[0].shape == (2, 2, 2, 2, 4)
+
+    def test_groups_honour_per_group_shape_and_dtype(self) -> None:
+        """Multi-group spec must allocate per-layer shape / dtype.
+
+        Regression for Bugbot #3150738055: previously every layer was
+        allocated with the *first* group's ``nh`` / ``hs`` / ``dtype``
+        (and the total ``num_layers`` from the sum), silently producing
+        wrong tensors for layers in later groups.
+        """
+        # Standard
+        from types import SimpleNamespace
+
+        # First Party
+        from lmcache.v1.kv_layer_groups import KVLayerGroupInfo
+
+        # Group A: 3 layers of (2, 2, 2, 8, 16), float16
+        # Group B: 2 layers of (1, 2, 2, 4, 32), bfloat16
+        # (NB / BS are intentionally identical — that's a hard
+        # requirement of paged KV, enforced in CLI execute().)
+        group_a = KVLayerGroupInfo(
+            layer_indices=[0, 1, 2],
+            shape_desc=SimpleNamespace(kv_size=2, nb=2, bs=2, nh=8, hs=16, nl=3),
+            dtype=torch.float16,
+        )
+        group_b = KVLayerGroupInfo(
+            layer_indices=[3, 4],
+            shape_desc=SimpleNamespace(kv_size=1, nb=2, bs=2, nh=4, hs=32, nl=2),
+            dtype=torch.bfloat16,
+        )
+        tensors = _allocate_kv_cache(
+            device="cpu",
+            groups=[group_a, group_b],
+        )
+        assert len(tensors) == 5
+        for t in tensors[:3]:
+            assert t.shape == (2, 2, 2, 8, 16)
+            assert t.dtype == torch.float16
+        for t in tensors[3:]:
+            assert t.shape == (1, 2, 2, 4, 32)
+            assert t.dtype == torch.bfloat16
+
+
+# ------------------------------------------------------------------ #
+#  _send_lookup / _poll_prefetch_status (protocol regression)          #
+# ------------------------------------------------------------------ #
+
+
+class _LookupRouter:
+    """Fake ROUTER implementing the LOOKUP / QUERY_PREFETCH_STATUS
+    subset of the MP server protocol.
+
+    * ``LOOKUP`` replies with **no payload** (void response) — the
+      real server-side handler returns ``None``. Regression for a
+      bug where the client treated the empty frame list as a
+      timeout and printed ``LOOKUP timeout``.
+    * ``QUERY_PREFETCH_STATUS`` accepts a ``request_id`` (str) and
+      returns ``None`` on the first N polls, then a fixed chunk
+      count — exercising both the in-progress and done branches.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        in_progress_polls: int = 1,
+        hit_chunks: int = 3,
+    ) -> None:
+        self._endpoint = endpoint
+        self._in_progress_left = in_progress_polls
+        self._hit_chunks = hit_chunks
+        self.last_query_request_id: str | None = None
+        self._ctx = zmq.Context.instance()
+        self._router = self._ctx.socket(zmq.ROUTER)
+        self._router.bind(endpoint)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2)
+        self._router.close(linger=0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            if not self._router.poll(100, zmq.POLLIN):
+                continue
+            frames = self._router.recv_multipart()
+            identity, uid_f, type_f, *payload = frames
+            req_type = msgspec.msgpack.decode(type_f, type=RequestType)
+            if req_type == RequestType.LOOKUP:
+                # Void reply: no payload frame.
+                self._router.send_multipart([identity, uid_f, type_f])
+            elif req_type == RequestType.QUERY_PREFETCH_STATUS:
+                req_id = msgspec.msgpack.decode(payload[0], type=str)
+                self.last_query_request_id = req_id
+                if self._in_progress_left > 0:
+                    self._in_progress_left -= 1
+                    body = msgspec.msgpack.encode(None)
+                else:
+                    body = msgspec.msgpack.encode(self._hit_chunks)
+                self._router.send_multipart([identity, uid_f, type_f, body])
+
+
+class TestLookupProtocol:
+    def _make_client(self, endpoint: str) -> MessageQueueClient:
+        ctx = zmq.Context.instance()
+        return MessageQueueClient(endpoint, ctx)
+
+    def test_send_lookup_void_reply_is_success(
+        self,
+        router_endpoint: str,
+    ) -> None:
+        """LOOKUP handler returns None (void) — must not be timeout."""
+        router = _LookupRouter(router_endpoint)
+        router.start()
+        try:
+            client = self._make_client(router_endpoint)
+            key = _make_key((1, 9906, 9906), request_id="req-void")
+            assert _send_lookup(client, key) is True
+            client.close()
+        finally:
+            router.stop()
+
+    def test_poll_prefetch_status_uses_request_id(
+        self,
+        router_endpoint: str,
+    ) -> None:
+        """QUERY_PREFETCH_STATUS payload is keyed by request_id str."""
+        router = _LookupRouter(
+            router_endpoint,
+            in_progress_polls=2,
+            hit_chunks=5,
+        )
+        router.start()
+        try:
+            client = self._make_client(router_endpoint)
+            hit = _poll_prefetch_status(
+                client,
+                "req-42",
+                max_polls=10,
+                poll_interval=0.0,
+            )
+            assert hit == 5
+            assert router.last_query_request_id == "req-42"
+            client.close()
+        finally:
+            router.stop()
+
+
+# ------------------------------------------------------------------ #
+#  _send_unregister_kv_cache (deregister on shutdown)                  #
+# ------------------------------------------------------------------ #
+
+
+class _UnregisterRouter:
+    """Fake ROUTER that records UNREGISTER requests and replies void.
+
+    Both ``UNREGISTER_KV_CACHE`` and
+    ``UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT`` carry a single
+    ``instance_id`` payload and return ``None`` (void). This fake
+    records the request type and decoded ``instance_id`` of the last
+    UNREGISTER it saw so the test can assert the bench sends the
+    correct protocol for each transfer mode.
+    """
+
+    def __init__(self, endpoint: str) -> None:
+        self.last_request_type: RequestType | None = None
+        self.last_instance_id: int | None = None
+        self._ctx = zmq.Context.instance()
+        self._router = self._ctx.socket(zmq.ROUTER)
+        self._router.bind(endpoint)
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=2)
+        self._router.close(linger=0)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            if not self._router.poll(100, zmq.POLLIN):
+                continue
+            frames = self._router.recv_multipart()
+            identity, uid_f, type_f, *payload = frames
+            req_type = msgspec.msgpack.decode(type_f, type=RequestType)
+            if req_type in (
+                RequestType.UNREGISTER_KV_CACHE,
+                RequestType.UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT,
+            ):
+                self.last_request_type = req_type
+                self.last_instance_id = msgspec.msgpack.decode(payload[0], type=int)
+                # Void reply: no payload frame.
+                self._router.send_multipart([identity, uid_f, type_f])
+
+
+class TestUnregisterKVCache:
+    def _make_client(self, endpoint: str) -> MessageQueueClient:
+        ctx = zmq.Context.instance()
+        return MessageQueueClient(endpoint, ctx)
+
+    def test_handle_mode_sends_unregister_kv_cache(
+        self,
+        router_endpoint: str,
+    ) -> None:
+        """Handle mode uses the GPU/SHM ``UNREGISTER_KV_CACHE`` protocol."""
+        router = _UnregisterRouter(router_endpoint)
+        router.start()
+        try:
+            client = self._make_client(router_endpoint)
+            assert (
+                _send_unregister_kv_cache(client, instance_id=7, use_handle=True)
+                is True
+            )
+            assert router.last_request_type == RequestType.UNREGISTER_KV_CACHE
+            assert router.last_instance_id == 7
+            client.close()
+        finally:
+            router.stop()
+
+    def test_data_mode_sends_engine_driven_unregister(
+        self,
+        router_endpoint: str,
+    ) -> None:
+        """Data mode uses the engine-driven context unregister protocol."""
+        router = _UnregisterRouter(router_endpoint)
+        router.start()
+        try:
+            client = self._make_client(router_endpoint)
+            assert (
+                _send_unregister_kv_cache(client, instance_id=0, use_handle=False)
+                is True
+            )
+            assert (
+                router.last_request_type
+                == RequestType.UNREGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT
+            )
+            assert router.last_instance_id == 0
+            client.close()
+        finally:
+            router.stop()
diff --git a/tests/cli/commands/test_coordinator.py b/tests/cli/commands/test_coordinator.py
new file mode 100644
index 0000000..025e609
--- /dev/null
+++ b/tests/cli/commands/test_coordinator.py
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the ``lmcache coordinator`` CLI command."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import argparse
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.coordinator import CoordinatorCommand
+
+
+@pytest.fixture
+def cmd():
+    return CoordinatorCommand()
+
+
+@pytest.fixture
+def parser(cmd):
+    """An ArgumentParser with CoordinatorCommand's arguments registered."""
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers()
+    cmd.register(sub)
+    return p
+
+
+class TestCoordinatorCommandMetadata:
+    def test_name(self, cmd):
+        assert cmd.name() == "coordinator"
+
+    def test_help(self, cmd):
+        assert "coordinator" in cmd.help().lower()
+
+
+class TestCoordinatorCommandArguments:
+    def test_all_flags_registered(self, parser):
+        """Every MPCoordinatorConfig field is settable via a CLI flag."""
+        args = parser.parse_args(
+            [
+                "coordinator",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                "9999",
+                "--instance-timeout",
+                "15",
+                "--health-check-interval",
+                "7",
+                "--eviction-check-interval",
+                "3",
+                "--eviction-ratio",
+                "0.5",
+                "--trigger-watermark",
+                "0.9",
+                "--chunk-size",
+                "512",
+                "--hash-algorithm",
+                "sha256",
+                "--blend-probe-stride",
+                "2",
+                "--timeout-keep-alive",
+                "15",
+            ]
+        )
+        assert args.host == "127.0.0.1"
+        assert args.port == 9999
+        assert args.chunk_size == 512
+        assert args.hash_algorithm == "sha256"
+        assert args.blend_probe_stride == 2
+        assert args.timeout_keep_alive == 15
+
+    def test_flags_default_to_none(self, parser):
+        """Unset flags default to None so env/config defaults win."""
+        args = parser.parse_args(["coordinator"])
+        assert args.chunk_size is None
+        assert args.hash_algorithm is None
+        assert args.blend_probe_stride is None
+        assert args.timeout_keep_alive is None
+
+
+class TestCoordinatorCommandExecute:
+    def test_overrides_applied(self, cmd):
+        """chunk_size/hash_algorithm/blend_probe_stride flags override the config."""
+        # First Party
+        from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+
+        args = argparse.Namespace(
+            host=None,
+            port=None,
+            instance_timeout=None,
+            health_check_interval=None,
+            eviction_check_interval=None,
+            eviction_ratio=None,
+            trigger_watermark=None,
+            chunk_size=512,
+            hash_algorithm="sha256",
+            blend_probe_stride=2,
+            timeout_keep_alive=None,
+        )
+
+        captured = {}
+
+        def fake_create_app(config: MPCoordinatorConfig):
+            captured["config"] = config
+            return MagicMock()
+
+        with (
+            patch("uvicorn.run"),
+            patch(
+                "lmcache.v1.mp_coordinator.app.create_app",
+                side_effect=fake_create_app,
+            ),
+        ):
+            cmd.execute(args)
+
+        assert captured["config"].chunk_size == 512
+        assert captured["config"].hash_algorithm == "sha256"
+        assert captured["config"].blend_probe_stride == 2
diff --git a/tests/cli/commands/test_query.py b/tests/cli/commands/test_query.py
new file mode 100644
index 0000000..8e29bfa
--- /dev/null
+++ b/tests/cli/commands/test_query.py
@@ -0,0 +1,244 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the ``lmcache query`` CLI command."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import argparse
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.query import QueryCommand
+
+
+def _engine_metric_map(
+    model_id: str = "facebook/opt-125m",
+) -> dict[str, tuple[str, object]]:
+    """Metric-map portion of :meth:`lmcache.cli.request.Request.send_request`."""
+    return {
+        "model": ("Model", model_id),
+        "prompt_tokens": ("Input tokens", 10),
+        "output_tokens": ("Output tokens", 5),
+        "ttft_ms": ("TTFT (ms)", 1.0),
+        "tpot_ms_per_token": ("TPOT (ms/token)", 2.0),
+        "total_latency_ms": ("Total latency (ms)", 100.0),
+        "throughput_tokens_per_s": ("Throughput (tokens/s)", 50.0),
+    }
+
+
+@pytest.fixture
+def cmd() -> QueryCommand:
+    return QueryCommand()
+
+
+@pytest.fixture
+def parser(cmd: QueryCommand) -> argparse.ArgumentParser:
+    """An :class:`~argparse.ArgumentParser` with ``QueryCommand`` registered."""
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers(dest="command")
+    cmd.register(sub)
+    return p
+
+
+class TestQueryCommandMetadata:
+    def test_name(self, cmd: QueryCommand) -> None:
+        assert cmd.name() == "query"
+
+    def test_help(self, cmd: QueryCommand) -> None:
+        assert "inference" in cmd.help().lower()
+
+
+class TestQueryCommandArguments:
+    def test_registers_subcommand(self, parser: argparse.ArgumentParser) -> None:
+        """The ``query engine`` subcommand should be parseable."""
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://localhost:8000/v1",
+                "--prompt",
+                "hello",
+            ],
+        )
+        assert hasattr(args, "func")
+
+    def test_engine_args_registered(self, parser: argparse.ArgumentParser) -> None:
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://host:9/v1",
+                "--prompt",
+                "{ffmpeg} test",
+                "--model",
+                "m",
+                "--max-tokens",
+                "64",
+                "--timeout",
+                "5",
+                "--documents",
+                "a=/tmp/x",
+                "--completions",
+                "--chat-first",
+                "--format",
+                "json",
+                "--output",
+                "/tmp/out",
+            ],
+        )
+        assert args.url == "http://host:9/v1"
+        assert args.prompt == "{ffmpeg} test"
+        assert args.model == "m"
+        assert args.max_tokens == 64
+        assert args.timeout == 5.0
+        assert args.documents == ["a=/tmp/x"]
+        assert args.completions is True
+        assert args.chat_first is True
+        assert args.format == "json"
+        assert args.output == "/tmp/out"
+
+    def test_default_values(self, parser: argparse.ArgumentParser) -> None:
+        """Required args only — everything else should get defaults."""
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://localhost:8000/v1",
+                "--prompt",
+                "hi",
+            ],
+        )
+        assert args.model is None
+        assert args.max_tokens == 128
+        assert args.timeout == 30.0
+        assert args.documents == []
+        assert args.completions is False
+        assert args.chat_first is False
+        assert args.format is None
+        assert args.output is None
+
+
+class TestQueryCommandExecute:
+    def test_func_bound_to_execute(
+        self, cmd: QueryCommand, parser: argparse.ArgumentParser
+    ) -> None:
+        """``parse_args`` should bind ``func`` to the subcommand's execute."""
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://localhost:8000/v1",
+                "--prompt",
+                "hello",
+                "--model",
+                "m",
+            ],
+        )
+        # func is bound to the discovered EngineCommand's execute
+        assert callable(args.func)
+        assert args.query_target == "engine"
+
+    @patch("lmcache.cli.commands.query.engine_command.Request")
+    def test_execute_calls_request_send_request(
+        self,
+        mock_request_cls: MagicMock,
+        cmd: QueryCommand,
+        parser: argparse.ArgumentParser,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """query_engine should call Request.send_request with the expanded prompt."""
+        mock_instance = MagicMock()
+        mock_instance.send_request.return_value = ("Paris.", _engine_metric_map())
+        mock_request_cls.return_value = mock_instance
+
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://localhost:8000/v1",
+                "--prompt",
+                "hello",
+                "--model",
+                "facebook/opt-125m",
+            ],
+        )
+        cmd.execute(args)
+
+        mock_request_cls.assert_called_once_with(
+            base="http://localhost:8000/v1",
+            model="facebook/opt-125m",
+            max_tokens=128,
+            timeout=30.0,
+            completions_only=False,
+            chat_first=False,
+        )
+        mock_instance.send_request.assert_called_once_with("hello")
+
+        out = capsys.readouterr().out
+        assert "Query Engine" in out
+        assert "facebook/opt-125m" in out
+        assert "Input tokens" in out
+        assert "Prompt tokens" not in out
+        assert "Answer" in out
+        assert "Paris." in out
+
+    @patch("lmcache.cli.commands.query.engine_command.Request")
+    def test_execute_uses_engine_model_when_cli_model_omitted(
+        self,
+        mock_request_cls: MagicMock,
+        cmd: QueryCommand,
+        parser: argparse.ArgumentParser,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """With no ``--model``, the report uses the model id from engine stats."""
+        mock_instance = MagicMock()
+        mock_instance.send_request.return_value = (
+            "answer",
+            _engine_metric_map(model_id="listed-model"),
+        )
+        mock_request_cls.return_value = mock_instance
+
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://localhost:8000/v1",
+                "--prompt",
+                "x",
+            ],
+        )
+        cmd.execute(args)
+        assert "listed-model" in capsys.readouterr().out
+
+    def test_execute_invalid_prompt_exits(
+        self,
+        cmd: QueryCommand,
+        parser: argparse.ArgumentParser,
+        capsys: pytest.CaptureFixture[str],
+    ) -> None:
+        """Unknown ``{placeholder}`` without ``--documents`` raises and exits."""
+        args = parser.parse_args(
+            [
+                "query",
+                "engine",
+                "--url",
+                "http://localhost:8000/v1",
+                "--prompt",
+                "{unknown_corpus}",
+                "--model",
+                "m",
+            ],
+        )
+        with pytest.raises(SystemExit) as exc_info:
+            cmd.execute(args)
+        assert exc_info.value.code == 1
+        err = capsys.readouterr().err
+        assert "Unknown documents" in err
+        assert "unknown_corpus" in err
diff --git a/tests/cli/commands/test_quota.py b/tests/cli/commands/test_quota.py
new file mode 100644
index 0000000..28feeb9
--- /dev/null
+++ b/tests/cli/commands/test_quota.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the ``lmcache quota`` CLI command."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import argparse
+import sys
+
+# Inject a fake openai module so that the auto-discovery of
+# lmcache.cli.commands (which imports bench -> openai) does not fail
+# in environments where openai is not installed.
+if "openai" not in sys.modules:
+    _fake_openai = MagicMock()
+    sys.modules["openai"] = _fake_openai
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.quota import QuotaCommand
+from lmcache.cli.commands.quota._helpers import (
+    DEFAULT_SALT_SENTINEL,
+    escape_salt,
+    normalize_url,
+    unescape_salt,
+)
+
+
+@pytest.fixture
+def cmd() -> QuotaCommand:
+    return QuotaCommand()
+
+
+@pytest.fixture
+def parser(cmd: QuotaCommand) -> argparse.ArgumentParser:
+    """An ArgumentParser with QuotaCommand registered."""
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers(dest="command")
+    cmd.register(sub)
+    return p
+
+
+class TestHelpers:
+    def test_normalize_url(self) -> None:
+        assert normalize_url("localhost:8080") == "http://localhost:8080"
+        assert normalize_url("https://host:443/") == "https://host:443"
+
+    def test_escape_unescape_salt(self) -> None:
+        assert escape_salt("") == DEFAULT_SALT_SENTINEL
+        assert escape_salt("tenant1") == "tenant1"
+        assert unescape_salt(DEFAULT_SALT_SENTINEL) == ""
+        assert unescape_salt("tenant1") == "tenant1"
+
+
+class TestQuotaCommandMetadata:
+    def test_name_and_help(self, cmd: QuotaCommand) -> None:
+        assert cmd.name() == "quota"
+        assert "quota" in cmd.help().lower()
+
+
+class TestQuotaCommandExecute:
+    @patch("lmcache.cli.commands.quota.set_command.http_request")
+    def test_set(
+        self,
+        mock_http,
+        cmd,
+        parser,
+        capsys,
+    ) -> None:
+        mock_http.return_value = {
+            "cache_salt": "tenant1",
+            "limit_gb": 10.5,
+            "status": "ok",
+        }
+        args = parser.parse_args(["quota", "set", "tenant1", "--limit-gb", "10.5"])
+        cmd.execute(args)
+
+        mock_http.assert_called_once_with(
+            "PUT",
+            "http://localhost:8080/quota/tenant1",
+            data={"limit_gb": 10.5},
+        )
+        out = capsys.readouterr().out
+        assert "Quota Set" in out and "tenant1" in out
+
+    @patch("lmcache.cli.commands.quota.get_command.http_request")
+    def test_get(
+        self,
+        mock_http,
+        cmd,
+        parser,
+        capsys,
+    ) -> None:
+        mock_http.return_value = {
+            "cache_salt": "tenant1",
+            "limit_gb": 10.5,
+            "current_usage_gb": 3.27,
+            "exists": True,
+        }
+        args = parser.parse_args(["quota", "get", "tenant1"])
+        cmd.execute(args)
+
+        mock_http.assert_called_once_with("GET", "http://localhost:8080/quota/tenant1")
+        out = capsys.readouterr().out
+        assert "Quota Info" in out and "3.27" in out
+
+    @patch("lmcache.cli.commands.quota.list_command.http_request")
+    def test_list(
+        self,
+        mock_http,
+        cmd,
+        parser,
+        capsys,
+    ) -> None:
+        mock_http.return_value = {
+            "users": {
+                "tenant1": {"limit_gb": 10.5, "current_usage_gb": 3.27},
+                "_default": {"limit_gb": 5.0, "current_usage_gb": 1.82},
+            }
+        }
+        args = parser.parse_args(["quota", "list"])
+        cmd.execute(args)
+
+        mock_http.assert_called_once_with("GET", "http://localhost:8080/quota")
+        out = capsys.readouterr().out
+        assert "tenant1" in out and "_default" in out
+
+    @patch("lmcache.cli.commands.quota.delete_command.http_request")
+    def test_delete(
+        self,
+        mock_http,
+        cmd,
+        parser,
+        capsys,
+    ) -> None:
+        mock_http.return_value = {"cache_salt": "tenant1", "status": "removed"}
+        args = parser.parse_args(["quota", "delete", "tenant1"])
+        cmd.execute(args)
+
+        mock_http.assert_called_once_with(
+            "DELETE",
+            "http://localhost:8080/quota/tenant1",
+        )
+        out = capsys.readouterr().out
+        assert "Quota Delete" in out and "removed" in out
+
+    @patch("lmcache.cli.commands.quota.set_command.http_request")
+    def test_quiet_suppresses_output(
+        self,
+        mock_http,
+        cmd,
+        parser,
+        capsys,
+    ) -> None:
+        mock_http.return_value = {"cache_salt": "t1", "limit_gb": 1.0, "status": "ok"}
+        args = parser.parse_args(["quota", "set", "t1", "--limit-gb", "1", "-q"])
+        cmd.execute(args)
+        assert capsys.readouterr().out == ""
diff --git a/tests/cli/commands/test_server.py b/tests/cli/commands/test_server.py
new file mode 100644
index 0000000..0b8ae75
--- /dev/null
+++ b/tests/cli/commands/test_server.py
@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the ``lmcache server`` CLI command."""
+
+# Standard
+from unittest.mock import patch
+import argparse
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.server import ServerCommand
+
+
+@pytest.fixture
+def cmd():
+    return ServerCommand()
+
+
+@pytest.fixture
+def parser(cmd):
+    """An ArgumentParser with ServerCommand's arguments registered."""
+    p = argparse.ArgumentParser()
+    sub = p.add_subparsers()
+    cmd.register(sub)
+    return p
+
+
+class TestServerCommandMetadata:
+    def test_name(self, cmd):
+        assert cmd.name() == "server"
+
+    def test_help(self, cmd):
+        assert "server" in cmd.help().lower()
+
+
+class TestServerCommandArguments:
+    def test_registers_subcommand(self, parser):
+        """The 'server' subcommand should be parseable."""
+        args = parser.parse_args(
+            [
+                "server",
+                "--l1-size-gb",
+                "4",
+                "--eviction-policy",
+                "LRU",
+            ]
+        )
+        assert hasattr(args, "func")
+
+    def test_mp_server_args_registered(self, parser):
+        args = parser.parse_args(
+            [
+                "server",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "6666",
+                "--l1-size-gb",
+                "4",
+                "--eviction-policy",
+                "LRU",
+            ]
+        )
+        assert args.host == "0.0.0.0"
+        assert args.port == 6666
+
+    def test_http_frontend_args_registered(self, parser):
+        args = parser.parse_args(
+            [
+                "server",
+                "--http-host",
+                "127.0.0.1",
+                "--http-port",
+                "9000",
+                "--l1-size-gb",
+                "4",
+                "--eviction-policy",
+                "LRU",
+            ]
+        )
+        assert args.http_host == "127.0.0.1"
+        assert args.http_port == 9000
+
+    def test_prometheus_args_registered(self, parser):
+        args = parser.parse_args(
+            [
+                "server",
+                "--prometheus-port",
+                "9999",
+                "--l1-size-gb",
+                "4",
+                "--eviction-policy",
+                "LRU",
+            ]
+        )
+        assert args.prometheus_port == 9999
+
+    def test_default_values(self, parser):
+        """Required args only — everything else should get defaults."""
+        args = parser.parse_args(
+            [
+                "server",
+                "--l1-size-gb",
+                "4",
+                "--eviction-policy",
+                "LRU",
+            ]
+        )
+        assert args.host == "localhost"
+        assert args.port == 5555
+        assert args.http_host == "0.0.0.0"
+        assert args.http_port == 8080
+
+
+class TestServerCommandExecute:
+    def test_func_bound_to_execute(self, cmd, parser):
+        """parser.parse_args should bind func to ServerCommand.execute."""
+        args = parser.parse_args(
+            [
+                "server",
+                "--l1-size-gb",
+                "4",
+                "--eviction-policy",
+                "LRU",
+            ]
+        )
+        assert args.func == cmd.execute
+
+    def test_execute_calls_run_http_server(self, parser):
+        """execute() should call run_http_server with parsed configs."""
+        http_server = pytest.importorskip("lmcache.v1.multiprocess.http_server")
+        with patch.object(http_server, "run_http_server") as mock_run:
+            args = parser.parse_args(
+                [
+                    "server",
+                    "--l1-size-gb",
+                    "4",
+                    "--eviction-policy",
+                    "LRU",
+                ]
+            )
+            cmd = ServerCommand()
+            cmd.execute(args)
+
+            mock_run.assert_called_once()
+            kwargs = mock_run.call_args.kwargs
+            assert "http_config" in kwargs
+            assert "mp_config" in kwargs
+            assert "storage_manager_config" in kwargs
+            assert "obs_config" in kwargs
diff --git a/tests/cli/commands/trace/__init__.py b/tests/cli/commands/trace/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/cli/commands/trace/test_dispatch.py b/tests/cli/commands/trace/test_dispatch.py
new file mode 100644
index 0000000..4e14546
--- /dev/null
+++ b/tests/cli/commands/trace/test_dispatch.py
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for :class:`CallDispatcher` and the default v1 registrations."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Any
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.trace._dispatch import (
+    CallDispatcher,
+    ReplayContext,
+    build_default_dispatcher,
+)
+from lmcache.v1.distributed.api import ObjectKey
+
+_SM_PREFIX = "lmcache.v1.distributed.storage_manager.StorageManager"
+
+
+class _FakeSM:
+    """Minimal StorageManager stand-in for dispatcher tests.
+
+    Records each call into ``self.calls`` so assertions can match
+    forwarded arguments exactly.  For the context-manager entry, it
+    returns a tiny object whose ``__enter__``/``__exit__`` push into
+    ``self.events`` so the FIFO ordering can be verified.
+    """
+
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, dict[str, Any]]] = []
+        self.events: list[str] = []
+
+    def reserve_write(self, **kw: Any) -> dict[Any, Any]:
+        self.calls.append(("reserve_write", kw))
+        return {}
+
+    def finish_write(self, **kw: Any) -> None:
+        self.calls.append(("finish_write", kw))
+
+    def submit_prefetch_task(self, **kw: Any) -> None:
+        self.calls.append(("submit_prefetch_task", kw))
+
+    def finish_read_prefetched(self, **kw: Any) -> None:
+        self.calls.append(("finish_read_prefetched", kw))
+
+    def read_prefetched_results(self, keys: list[ObjectKey]) -> "_FakeCM":
+        return _FakeCM(self, keys)
+
+
+class _FakeCM:
+    def __init__(self, parent: _FakeSM, keys: list[ObjectKey]) -> None:
+        self._parent = parent
+        self._keys = keys
+
+    def __enter__(self) -> None:
+        self._parent.events.append(f"enter-{len(self._keys)}")
+
+    def __exit__(self, *_exc: object) -> None:
+        self._parent.events.append(f"exit-{len(self._keys)}")
+
+
+def _key(i: int) -> ObjectKey:
+    return ObjectKey(chunk_hash=bytes([i]), model_name="test", kv_rank=0)
+
+
+class TestCallDispatcher:
+    def test_register_and_has(self):
+        d = CallDispatcher()
+        assert not d.has("x")
+        d.register("x", lambda c, a: None)
+        assert d.has("x")
+
+    def test_duplicate_registration_raises(self):
+        d = CallDispatcher()
+        d.register("x", lambda c, a: None)
+        with pytest.raises(ValueError):
+            d.register("x", lambda c, a: None)
+
+    def test_dispatch_unknown_qualname_raises_keyerror(self):
+        d = CallDispatcher()
+        with pytest.raises(KeyError):
+            d.dispatch("no.such.qualname", ReplayContext(sm=_FakeSM()), {})
+
+    def test_registered_qualnames_returns_new_list(self):
+        d = CallDispatcher()
+        d.register("a", lambda c, a: None)
+        qns = d.registered_qualnames()
+        qns.append("b")
+        assert "b" not in d.registered_qualnames()
+
+
+class TestDefaultDispatcher:
+    def test_registers_all_v1_qualnames(self):
+        d = build_default_dispatcher()
+        expected = {
+            f"{_SM_PREFIX}.reserve_write",
+            f"{_SM_PREFIX}.finish_write",
+            f"{_SM_PREFIX}.submit_prefetch_task",
+            f"{_SM_PREFIX}.finish_read_prefetched",
+            f"{_SM_PREFIX}.read_prefetched_results.__enter__",
+            f"{_SM_PREFIX}.read_prefetched_results.__exit__",
+        }
+        assert set(d.registered_qualnames()) == expected
+
+    def test_simple_method_forwarded_with_kwargs(self):
+        sm = _FakeSM()
+        ctx = ReplayContext(sm=sm)
+        d = build_default_dispatcher()
+        d.dispatch(
+            f"{_SM_PREFIX}.reserve_write",
+            ctx,
+            {"keys": [_key(1)], "layout_desc": "LAYOUT", "mode": "new"},
+        )
+        assert sm.calls == [
+            (
+                "reserve_write",
+                {"keys": [_key(1)], "layout_desc": "LAYOUT", "mode": "new"},
+            ),
+        ]
+
+    def test_read_prefetched_enter_exit_fifo(self):
+        """Two overlapping contexts with identical keys exit in FIFO order."""
+        sm = _FakeSM()
+        ctx = ReplayContext(sm=sm)
+        d = build_default_dispatcher()
+
+        keys = [_key(1), _key(2)]
+        enter = f"{_SM_PREFIX}.read_prefetched_results.__enter__"
+        exit_ = f"{_SM_PREFIX}.read_prefetched_results.__exit__"
+
+        d.dispatch(enter, ctx, {"keys": keys})
+        d.dispatch(enter, ctx, {"keys": keys})
+        assert sm.events == ["enter-2", "enter-2"]
+        # Both contexts share the same key tuple.
+        assert tuple(keys) in ctx.open_read_contexts
+        assert len(ctx.open_read_contexts[tuple(keys)]) == 2
+
+        d.dispatch(exit_, ctx, {"keys": keys})
+        assert sm.events == ["enter-2", "enter-2", "exit-2"]
+        d.dispatch(exit_, ctx, {"keys": keys})
+        assert sm.events == ["enter-2", "enter-2", "exit-2", "exit-2"]
+        # Fully drained → dict cleaned up.
+        assert ctx.open_read_contexts == {}
+
+    def test_exit_without_matching_enter_is_warning_only(self, caplog):
+        sm = _FakeSM()
+        ctx = ReplayContext(sm=sm)
+        d = build_default_dispatcher()
+
+        with caplog.at_level("WARNING"):
+            d.dispatch(
+                f"{_SM_PREFIX}.read_prefetched_results.__exit__",
+                ctx,
+                {"keys": [_key(1)]},
+            )
+        # No crash, no effect on sm.
+        assert sm.events == []
diff --git a/tests/cli/commands/trace/test_driver.py b/tests/cli/commands/trace/test_driver.py
new file mode 100644
index 0000000..a583829
--- /dev/null
+++ b/tests/cli/commands/trace/test_driver.py
@@ -0,0 +1,319 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""End-to-end tests for :class:`StorageReplayDriver`.
+
+Each test records a short sequence of StorageManager operations into a
+binary trace file via the real ``EventBus`` + ``StorageTraceRecorder``
+stack, then constructs a fresh StorageManager and drives replay over
+that trace.  These tests avoid any GPU/vLLM dependencies — the whole
+flow runs in-process on CPU memory.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from typing import Callable
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.cli.commands.trace._dispatch import (
+    CallDispatcher,
+    ReplayContext,
+    build_default_dispatcher,
+)
+from lmcache.cli.commands.trace._driver import StorageReplayDriver
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.trace.decorator import set_tracing_enabled
+from lmcache.v1.mp_observability.trace.recorder import StorageTraceRecorder
+import lmcache.v1.mp_observability.event_bus as _bus_module
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def _should_use_lazy() -> bool:
+    """Lazy allocator requires CUDA.  CPU-only hosts (our primary replay
+    target) must use eager allocation."""
+    return torch.cuda.is_available()
+
+
+def _make_sm_config() -> StorageManagerConfig:
+    """Build a small StorageManagerConfig suitable for CPU testing."""
+    memory = L1MemoryManagerConfig(
+        size_in_bytes=64 * 1024 * 1024,
+        use_lazy=_should_use_lazy(),
+        init_size_in_bytes=32 * 1024 * 1024,
+        align_bytes=0x1000,
+    )
+    l1 = L1ManagerConfig(
+        memory_config=memory,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+    return StorageManagerConfig(
+        l1_manager_config=l1,
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+
+
+def _make_key(i: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=i.to_bytes(4, "big"),
+        model_name="test",
+        kv_rank=0,
+    )
+
+
+def _make_layout() -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([16, 16])],
+        dtypes=[torch.float16],
+    )
+
+
+@pytest.fixture(autouse=True)
+def restore_global_bus():
+    saved = _bus_module._global_bus
+    yield
+    _bus_module._global_bus = saved
+    set_tracing_enabled(False)
+
+
+@pytest.fixture
+def trace_path(tmp_path):
+    return str(tmp_path / "run.lct")
+
+
+def _flush(bus: EventBus) -> None:
+    time.sleep(0.25)
+    bus._drain_all()
+
+
+# ---------------------------------------------------------------------------
+# Helpers: record a scripted sequence into a trace file
+# ---------------------------------------------------------------------------
+
+
+def _record_sequence(
+    trace_path: str,
+    sm_config: StorageManagerConfig,
+    script: Callable[[StorageManager], None],
+) -> None:
+    """Record whatever ``script(sm)`` does into *trace_path*.
+
+    ``script`` receives a live StorageManager and should call traced
+    methods on it.  This helper handles the bus / recorder lifecycle.
+    """
+    bus = EventBus(EventBusConfig(enabled=True))
+    _bus_module._global_bus = bus
+    bus.start()
+
+    sm = StorageManager(sm_config)
+    rec = StorageTraceRecorder(trace_path)
+    rec.attach_storage_config(sm_config)
+    bus.register_subscriber(rec)
+    try:
+        script(sm)
+        _flush(bus)
+    finally:
+        bus.stop()
+        sm.close()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestRecordReplayRoundtrip:
+    def test_reserve_and_finish_write_replay(self, trace_path):
+        sm_config = _make_sm_config()
+        layout = _make_layout()
+        keys = [_make_key(i) for i in range(3)]
+
+        def script(sm: StorageManager) -> None:
+            reserved = sm.reserve_write(keys, layout, mode="new")
+            assert len(reserved) == 3
+            sm.finish_write(keys)
+
+        _record_sequence(trace_path, sm_config, script)
+
+        with StorageReplayDriver(_make_sm_config(), trace_path) as driver:
+            result = driver.run()
+
+        assert result.records_failed == 0
+        assert result.records_replayed >= 2  # reserve_write + finish_write
+        assert result.header_level == "storage"
+        # Same config used on both sides → digest matches.
+        assert result.header_digest == result.replay_config_digest
+
+    def test_full_prefetch_cycle_replay(self, trace_path):
+        sm_config = _make_sm_config()
+        layout = _make_layout()
+        keys = [_make_key(i) for i in range(3)]
+
+        def script(sm: StorageManager) -> None:
+            sm.reserve_write(keys, layout, mode="new")
+            sm.finish_write(keys)
+            handle = sm.submit_prefetch_task(keys, layout)
+            assert handle is not None
+            with sm.read_prefetched_results(keys) as objs:
+                assert objs is not None
+                assert len(objs) == 3
+
+        _record_sequence(trace_path, sm_config, script)
+
+        with StorageReplayDriver(_make_sm_config(), trace_path) as driver:
+            result = driver.run()
+
+        # Everything replayed, no failures.
+        assert result.records_failed == 0
+        assert result.records_skipped == 0
+        qns = result.stats.summary().keys()
+        # Every op from the script appears in stats.
+        expected_substrings = [
+            "reserve_write",
+            "finish_write",
+            "submit_prefetch_task",
+            "read_prefetched_results.__enter__",
+            "read_prefetched_results.__exit__",
+        ]
+        for sub in expected_substrings:
+            assert any(sub in qn for qn in qns), (
+                f"missing qualname containing {sub!r}: saw {sorted(qns)}"
+            )
+
+    def test_on_record_callback_fires_per_record(self, trace_path):
+        sm_config = _make_sm_config()
+        layout = _make_layout()
+        keys = [_make_key(0)]
+
+        def script(sm: StorageManager) -> None:
+            sm.reserve_write(keys, layout, mode="new")
+            sm.finish_write(keys)
+
+        _record_sequence(trace_path, sm_config, script)
+
+        seen: list[tuple[str, bool]] = []
+
+        def on_record(qualname: str, latency_s: float, failed: bool) -> None:
+            seen.append((qualname, failed))
+
+        with StorageReplayDriver(_make_sm_config(), trace_path) as driver:
+            result = driver.run(on_record=on_record)
+
+        assert len(seen) == result.records_replayed
+        assert all(not failed for _, failed in seen)
+
+
+class TestMismatchHandling:
+    def test_unknown_qualname_is_skipped(self, trace_path):
+        """An empty dispatcher with no matching handlers skips every
+        record without raising."""
+        sm_config = _make_sm_config()
+        layout = _make_layout()
+        keys = [_make_key(0)]
+
+        def script(sm: StorageManager) -> None:
+            sm.reserve_write(keys, layout, mode="new")
+
+        _record_sequence(trace_path, sm_config, script)
+
+        empty = CallDispatcher()
+        with StorageReplayDriver(
+            _make_sm_config(), trace_path, dispatcher=empty
+        ) as driver:
+            result = driver.run()
+        assert result.records_replayed == 0
+        assert result.records_skipped >= 1
+
+    def test_handler_failure_counted(self, trace_path):
+        sm_config = _make_sm_config()
+        layout = _make_layout()
+        keys = [_make_key(0)]
+
+        def script(sm: StorageManager) -> None:
+            sm.reserve_write(keys, layout, mode="new")
+
+        _record_sequence(trace_path, sm_config, script)
+
+        d = build_default_dispatcher()
+        # Replace the reserve_write handler with one that raises.
+        failing = CallDispatcher()
+        for qn in d.registered_qualnames():
+            if qn.endswith(".reserve_write"):
+
+                def _boom(_ctx: ReplayContext, _a: dict) -> None:
+                    raise RuntimeError("boom")
+
+                failing.register(qn, _boom)
+            else:
+                # Reuse the default handler for anything else; none
+                # is expected in this script but registering keeps
+                # the test robust against future decorator additions.
+                # First Party
+                from lmcache.cli.commands.trace._dispatch import (
+                    _call_sm_method,
+                    _enter_read_prefetched,
+                    _exit_read_prefetched,
+                )
+
+                if qn.endswith(".__enter__"):
+                    failing.register(qn, _enter_read_prefetched)
+                elif qn.endswith(".__exit__"):
+                    failing.register(qn, _exit_read_prefetched)
+                else:
+                    failing.register(qn, _call_sm_method(qn.split(".")[-1]))
+
+        with StorageReplayDriver(
+            _make_sm_config(), trace_path, dispatcher=failing
+        ) as driver:
+            result = driver.run()
+
+        assert result.records_failed >= 1
+
+
+class TestPacing:
+    def test_replay_does_not_regress_past_monotonic(self, trace_path):
+        """Replay never runs *before* the recorded offset.
+
+        Records have t_mono=0 and a positive value; the driver always
+        honors the recorded gap — there is no as-fast-as-possible
+        mode, because async read/write dependencies inside
+        ``StorageManager`` make it unsafe to collapse the recorded
+        inter-call intervals.
+        """
+        sm_config = _make_sm_config()
+        layout = _make_layout()
+        keys = [_make_key(0)]
+
+        def script(sm: StorageManager) -> None:
+            sm.reserve_write(keys, layout, mode="new")
+            time.sleep(0.05)  # force a gap
+            sm.finish_write(keys)
+
+        _record_sequence(trace_path, sm_config, script)
+
+        start = time.monotonic()
+        with StorageReplayDriver(_make_sm_config(), trace_path) as driver:
+            result = driver.run()
+        elapsed = time.monotonic() - start
+
+        assert result.records_failed == 0
+        # Replay should have slept ≈ 50ms at minimum.  Use a generous
+        # bound to avoid flakes under load.
+        assert elapsed >= 0.04
diff --git a/tests/cli/commands/trace/test_stats.py b/tests/cli/commands/trace/test_stats.py
new file mode 100644
index 0000000..f7ccc80
--- /dev/null
+++ b/tests/cli/commands/trace/test_stats.py
@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for :class:`ReplayStatsCollector`."""
+
+# Standard
+import json
+import threading
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.trace._stats import (
+    OpStats,
+    ReplayStatsCollector,
+    _percentile,
+)
+
+
+class TestPercentile:
+    def test_empty_returns_zero(self):
+        assert _percentile([], 50) == 0.0
+
+    def test_p0_returns_min(self):
+        assert _percentile([1.0, 2.0, 3.0], 0) == 1.0
+
+    def test_p100_returns_max(self):
+        assert _percentile([1.0, 2.0, 3.0], 100) == 3.0
+
+    def test_p50_on_100_values(self):
+        vals = [float(i) for i in range(1, 101)]
+        # nearest-rank with floor((50/100)*100)=50 → index 50 → value 51
+        assert _percentile(vals, 50) == 51.0
+
+
+class TestReplayStatsCollector:
+    def test_record_and_summary(self):
+        s = ReplayStatsCollector()
+        for latency_ms in (1.0, 2.0, 3.0, 4.0, 100.0):
+            s.record("op.foo", latency_ms / 1000.0)
+        summary = s.summary()
+        assert "op.foo" in summary
+        stats = summary["op.foo"]
+        assert isinstance(stats, OpStats)
+        assert stats.count == 5
+        assert stats.error_count == 0
+        assert stats.min_ms == pytest.approx(1.0)
+        assert stats.max_ms == pytest.approx(100.0)
+        # 22 = mean of {1,2,3,4,100}
+        assert stats.mean_ms == pytest.approx(22.0)
+
+    def test_records_failed_separately(self):
+        s = ReplayStatsCollector()
+        s.record("op.foo", 0.001, failed=False)
+        s.record("op.foo", 0.001, failed=True)
+        summary = s.summary()
+        assert summary["op.foo"].count == 1
+        assert summary["op.foo"].error_count == 1
+
+    def test_error_only_bucket(self):
+        """A qualname that only ever failed still appears with zero
+        latency stats."""
+        s = ReplayStatsCollector()
+        s.record("op.failing", 0.0, failed=True)
+        summary = s.summary()
+        assert summary["op.failing"].count == 0
+        assert summary["op.failing"].error_count == 1
+        assert summary["op.failing"].mean_ms == 0.0
+
+    def test_duration(self):
+        s = ReplayStatsCollector()
+        assert s.total_duration_s() == 0.0
+        s.mark_start(100.0)
+        s.mark_end(105.5)
+        assert s.total_duration_s() == pytest.approx(5.5)
+
+    def test_export_csv(self, tmp_path):
+        s = ReplayStatsCollector()
+        s.record("op.a", 0.001)
+        s.record("op.a", 0.002)
+        s.record("op.b", 0.003)
+        path = str(tmp_path / "out.csv")
+        s.export_csv(path)
+        with open(path) as f:
+            lines = f.read().splitlines()
+        assert lines[0].split(",") == [
+            "qualname",
+            "count",
+            "errors",
+            "mean_ms",
+            "p50_ms",
+            "p90_ms",
+            "p99_ms",
+            "min_ms",
+            "max_ms",
+        ]
+        # two op rows sorted alphabetically
+        assert lines[1].startswith("op.a,")
+        assert lines[2].startswith("op.b,")
+
+    def test_export_json(self, tmp_path):
+        s = ReplayStatsCollector()
+        s.mark_start(0.0)
+        s.record("op.a", 0.001)
+        s.mark_end(1.0)
+        path = str(tmp_path / "out.json")
+        s.export_json(path)
+        with open(path) as f:
+            data = json.load(f)
+        assert data["duration_s"] == pytest.approx(1.0)
+        assert "op.a" in data["ops"]
+        assert data["ops"]["op.a"]["count"] == 1
+
+    def test_thread_safety(self):
+        s = ReplayStatsCollector()
+
+        def worker():
+            for _ in range(100):
+                s.record("op.x", 0.0001)
+
+        threads = [threading.Thread(target=worker) for _ in range(4)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        assert s.summary()["op.x"].count == 400
diff --git a/tests/cli/conftest.py b/tests/cli/conftest.py
new file mode 100644
index 0000000..91ad823
--- /dev/null
+++ b/tests/cli/conftest.py
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared fixtures for CLI tests.
+
+The CLI arg-registration code transitively imports
+``lmcache.native_storage_ops`` (a compiled C extension). On CI runners
+without a CUDA build the module is absent, so we insert a lightweight
+stub into ``sys.modules`` for the duration of each CLI test only.
+"""
+
+# Standard
+from collections.abc import Generator
+from typing import Any
+from unittest.mock import MagicMock
+import importlib
+import importlib.util
+import sys
+import types
+
+# Third Party
+import pytest
+
+_MOD_NAME = "lmcache.native_storage_ops"
+
+
+@pytest.fixture(autouse=True)
+def _stub_native_storage_ops() -> Generator[None, None, None]:
+    """Temporarily stub ``native_storage_ops`` if the extension is not built.
+
+    The stub is removed from ``sys.modules`` after the test so it does not
+    interfere with other test suites that ``importorskip`` the real module.
+    """
+    if importlib.util.find_spec(_MOD_NAME) is not None:
+        yield
+        return
+
+    stub: Any = types.ModuleType(_MOD_NAME)
+    stub.TTLLock = MagicMock()
+    stub.Bitmap = MagicMock()
+    stub.PeriodicEventNotifier = MagicMock()
+    stub.ParallelPatternMatcher = MagicMock()
+    stub.RangePatternMatcher = MagicMock()
+
+    sys.modules[_MOD_NAME] = stub
+    try:
+        yield
+    finally:
+        if sys.modules.get(_MOD_NAME) is stub:
+            del sys.modules[_MOD_NAME]
diff --git a/tests/cli/test_describe.py b/tests/cli/test_describe.py
new file mode 100644
index 0000000..0725d89
--- /dev/null
+++ b/tests/cli/test_describe.py
@@ -0,0 +1,616 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``lmcache describe kvcache``."""
+
+# Standard
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+from unittest.mock import patch
+import json
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.describe import (
+    DescribeError,
+    fetch_health,
+    fetch_json,
+    fetch_running_requests,
+    fmt_health,
+    normalize_url,
+    safe_get,
+)
+
+# ---------------------------------------------------------------------------
+# Sample /status payload
+# ---------------------------------------------------------------------------
+
+SAMPLE_STATUS = {
+    "is_healthy": True,
+    "engine_type": "MPCacheServer",
+    "chunk_size": 256,
+    "hash_algorithm": "sha256",
+    "registered_gpu_ids": [0],
+    "cache_context_meta": {
+        "0": {
+            "model_name": "llama",
+            "world_size": 1,
+            "kv_cache_layout": {
+                "num_layers": 32,
+                "num_blocks": 2048,
+                "cache_size_per_token": 163840,
+                "kernel_groups": [
+                    {
+                        "kernel_group_idx": 0,
+                        "engine_group_idx": 0,
+                        "object_group_idx": 0,
+                        "num_layers": 32,
+                        "layer_indices": list(range(32)),
+                        "tokens_per_block": 16,
+                        "slots_per_block": 16,
+                        "dtype": "torch.float16",
+                        "engine_kv_concrete_shape": "32 x [2, 2048, 16, 8, 128]",
+                        "is_mla": False,
+                        "engine_kv_format": "NL_X_TWO_NB_BS_NH_HS",
+                        "engine_kv_shape": "NL x [2, NB, BS, NH, HS]",
+                        "attention_backend": "vLLM non-MLA flash attention",
+                    },
+                ],
+            },
+        },
+    },
+    "active_sessions": 3,
+    "storage_manager": {
+        "is_healthy": True,
+        "l1_manager": {
+            "is_healthy": True,
+            "total_object_count": 1024,
+            "write_locked_count": 0,
+            "read_locked_count": 0,
+            "temporary_count": 0,
+            "memory_used_bytes": 45_415_895_859,  # ~42.30 GB
+            "memory_total_bytes": 64_424_509_440,  # ~60.00 GB
+            "memory_usage_ratio": 0.705,
+            "write_ttl_seconds": 10,
+            "read_ttl_seconds": 10,
+        },
+        "store_controller": {"is_healthy": True},
+        "prefetch_controller": {"is_healthy": True},
+        "eviction_controller": {
+            "is_healthy": True,
+            "thread_alive": True,
+            "eviction_policy": "LRU",
+            "trigger_watermark": 0.9,
+            "eviction_ratio": 0.2,
+        },
+        "l2_adapters": [],
+        "num_l2_adapters": 0,
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Helper tests
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeUrl:
+    def test_adds_http(self):
+        assert normalize_url("localhost:8000") == "http://localhost:8000"
+
+    def test_preserves_http(self):
+        assert normalize_url("http://localhost:8000") == "http://localhost:8000"
+
+    def test_preserves_https(self):
+        assert normalize_url("https://host:443") == "https://host:443"
+
+    def test_strips_trailing_slash(self):
+        assert normalize_url("http://host:8000/") == "http://host:8000"
+
+    def test_strips_multiple_trailing_slashes(self):
+        assert normalize_url("http://host:8000///") == "http://host:8000"
+
+
+class TestFmtHealth:
+    def test_healthy(self):
+        assert fmt_health(True) == "OK"
+
+    def test_unhealthy(self):
+        assert fmt_health(False) == "UNHEALTHY"
+
+    def test_none(self):
+        assert fmt_health(None) is None
+
+
+class TestSafeGet:
+    def test_nested(self):
+        d = {"a": {"b": {"c": 42}}}
+        assert safe_get(d, "a", "b", "c") == 42
+
+    def test_missing_key(self):
+        d = {"a": {"b": 1}}
+        assert safe_get(d, "a", "x") is None
+
+    def test_missing_key_with_default(self):
+        d = {"a": 1}
+        assert safe_get(d, "a", "b", default="N/A") == "N/A"
+
+    def test_non_dict_intermediate(self):
+        d = {"a": 5}
+        assert safe_get(d, "a", "b") is None
+
+
+# ---------------------------------------------------------------------------
+# Field extraction integration test
+# ---------------------------------------------------------------------------
+
+
+class TestDescribeKvcacheFields:
+    """Test that ``_describe_kvcache`` extracts fields correctly from a
+    sample ``/status`` response."""
+
+    def test_field_extraction(self):
+        """Verify metrics are populated from the sample status dict."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = "http://localhost:8000"
+            format = "json"
+            output = None
+
+        # Patch fetch_json to return our sample data
+        with patch(
+            "lmcache.cli.commands.describe.fetch_json",
+            return_value=SAMPLE_STATUS,
+        ):
+            # Capture the JSON output
+            # Standard
+            import io
+
+            buf = io.StringIO()
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+
+            output = json.loads(buf.getvalue())
+
+        m = output["metrics"]
+        assert m["health"] == "OK"
+        assert m["url"] == "http://localhost:8000"
+        assert m["engine_type"] == "MPCacheServer"
+        assert m["chunk_size"] == 256
+        assert m["l1_capacity_gb"] == 60.0
+        assert m["l1_used_gb"] == "42.30 (70.5%)"
+        assert m["eviction_policy"] == "LRU"
+        assert m["cached_objects"] == 1024
+        assert m["active_sessions"] == 3
+
+        # Per-model section (list)
+        assert "models" in m
+        model = m["models"][0]
+        assert model["model"] == "llama"
+        assert model["world_size"] == 1
+        assert model["gpu_ids"] == "0"
+        assert model["num_layers"] == 32
+        assert model["num_blocks"] == 2048
+        assert model["cache_size_per_token"] == 163840
+
+        # Per-kernel-group section (list)
+        assert "kernel_groups" in m
+        kg = m["kernel_groups"][0]
+        assert kg["model"] == "llama"
+        assert kg["kernel_group_idx"] == 0
+        assert kg["engine_group_idx"] == 0
+        assert kg["object_group_idx"] == 0
+        assert kg["num_layers"] == 32
+        assert kg["slots_per_block"] == 16
+        assert kg["dtype"] == "torch.float16"
+        assert kg["is_mla"] is False
+        assert kg["attention_backend"] == "vLLM non-MLA flash attention"
+        assert kg["engine_kv_shape"] == "NL x [2, NB, BS, NH, HS]"
+        assert kg["engine_kv_concrete_shape"] == "32 x [2, 2048, 16, 8, 128]"
+
+    def test_unhealthy(self):
+        """Verify health shows UNHEALTHY when is_healthy is False."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        unhealthy_data = {**SAMPLE_STATUS, "is_healthy": False}
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = "http://localhost:8000"
+            format = "json"
+            output = None
+
+        with patch(
+            "lmcache.cli.commands.describe.fetch_json",
+            return_value=unhealthy_data,
+        ):
+            # Standard
+            import io
+
+            buf = io.StringIO()
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+
+            output = json.loads(buf.getvalue())
+
+        assert output["metrics"]["health"] == "UNHEALTHY"
+
+    def test_missing_fields_show_na(self):
+        """Verify missing nested fields render as None (N/A in terminal)."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        minimal_data = {"is_healthy": True, "engine_type": "MPCacheServer"}
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = "http://localhost:8000"
+            format = "json"
+            output = None
+
+        with patch(
+            "lmcache.cli.commands.describe.fetch_json",
+            return_value=minimal_data,
+        ):
+            # Standard
+            import io
+
+            buf = io.StringIO()
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+
+            output = json.loads(buf.getvalue())
+
+        m = output["metrics"]
+        assert m["l1_capacity_gb"] is None
+        assert m["l1_used_gb"] is None
+        assert m["eviction_policy"] is None
+        assert m["cached_objects"] is None
+        assert m["active_sessions"] is None
+
+
+# ---------------------------------------------------------------------------
+# Error handling tests
+# ---------------------------------------------------------------------------
+
+
+class TestDescribeErrors:
+    def test_connection_refused(self):
+        """Verify sys.exit(1) on connection error."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = "http://localhost:19999"
+            format = None
+            output = None
+
+        with pytest.raises(SystemExit) as exc_info:
+            cmd.execute(FakeArgs())
+
+        assert exc_info.value.code == 1
+
+    def test_503_error(self):
+        """Verify sys.exit(1) on HTTP 503."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = "http://localhost:8000"
+            format = None
+            output = None
+
+        with patch(
+            "lmcache.cli.commands.describe.fetch_json",
+            side_effect=DescribeError("Server unhealthy: engine not initialized"),
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                cmd.execute(FakeArgs())
+
+            assert exc_info.value.code == 1
+
+
+# ---------------------------------------------------------------------------
+# fetch_json with a real HTTP server
+# ---------------------------------------------------------------------------
+
+
+class _MockHandler(BaseHTTPRequestHandler):
+    """Minimal handler that serves a canned JSON response."""
+
+    response_body: bytes = b"{}"
+    response_code: int = 200
+
+    def do_GET(self):
+        self.send_response(self.response_code)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(self.response_body)
+
+    def log_message(self, format, *args):
+        pass  # suppress stderr noise
+
+
+class TestFetchJson:
+    def test_success(self):
+        handler = type(
+            "_H",
+            (_MockHandler,),
+            {
+                "response_body": json.dumps({"ok": True}).encode(),
+                "response_code": 200,
+            },
+        )
+        server = HTTPServer(("127.0.0.1", 0), handler)
+        port = server.server_address[1]
+        t = Thread(target=server.handle_request, daemon=True)
+        t.start()
+        try:
+            result = fetch_json(f"http://127.0.0.1:{port}/status")
+            assert result == {"ok": True}
+        finally:
+            server.server_close()
+
+    def test_503(self):
+        handler = type(
+            "_H",
+            (_MockHandler,),
+            {
+                "response_body": json.dumps(
+                    {"error": "engine not initialized"}
+                ).encode(),
+                "response_code": 503,
+            },
+        )
+        server = HTTPServer(("127.0.0.1", 0), handler)
+        port = server.server_address[1]
+        t = Thread(target=server.handle_request, daemon=True)
+        t.start()
+        try:
+            with pytest.raises(DescribeError, match="Server unhealthy"):
+                fetch_json(f"http://127.0.0.1:{port}/status")
+        finally:
+            server.server_close()
+
+
+class TestFetchHealth:
+    def test_ok(self):
+        handler = type(
+            "_H",
+            (_MockHandler,),
+            {"response_body": b"", "response_code": 200},
+        )
+        server = HTTPServer(("127.0.0.1", 0), handler)
+        port = server.server_address[1]
+        t = Thread(target=server.handle_request, daemon=True)
+        t.start()
+        try:
+            assert fetch_health(f"http://127.0.0.1:{port}/health") is True
+        finally:
+            server.server_close()
+
+    def test_non_200(self):
+        handler = type(
+            "_H",
+            (_MockHandler,),
+            {"response_body": b"", "response_code": 503},
+        )
+        server = HTTPServer(("127.0.0.1", 0), handler)
+        port = server.server_address[1]
+        t = Thread(target=server.handle_request, daemon=True)
+        t.start()
+        try:
+            assert fetch_health(f"http://127.0.0.1:{port}/health") is False
+        finally:
+            server.server_close()
+
+    def test_connection_refused(self):
+        assert fetch_health("http://127.0.0.1:19999/health") is False
+
+
+class TestFetchRunningRequests:
+    def _serve(self, body: bytes, code: int = 200):
+        handler = type(
+            "_H",
+            (_MockHandler,),
+            {"response_body": body, "response_code": code},
+        )
+        server = HTTPServer(("127.0.0.1", 0), handler)
+        port = server.server_address[1]
+        t = Thread(target=server.handle_request, daemon=True)
+        t.start()
+        return server, port
+
+    def test_single_series(self):
+        body = (
+            b"# HELP vllm:num_requests_running Number of running requests.\n"
+            b"# TYPE vllm:num_requests_running gauge\n"
+            b'vllm:num_requests_running{model_name="m"} 3.0\n'
+        )
+        server, port = self._serve(body)
+        try:
+            assert fetch_running_requests(f"http://127.0.0.1:{port}/metrics") == 3
+        finally:
+            server.server_close()
+
+    def test_sums_multiple_series(self):
+        body = (
+            b'vllm:num_requests_running{model_name="a"} 3.0\n'
+            b'vllm:num_requests_running{model_name="b"} 1.0\n'
+        )
+        server, port = self._serve(body)
+        try:
+            assert fetch_running_requests(f"http://127.0.0.1:{port}/metrics") == 4
+        finally:
+            server.server_close()
+
+    def test_metric_absent(self):
+        body = b"# only other metrics here\nvllm:num_requests_waiting 5.0\n"
+        server, port = self._serve(body)
+        try:
+            assert fetch_running_requests(f"http://127.0.0.1:{port}/metrics") is None
+        finally:
+            server.server_close()
+
+    def test_connection_refused(self):
+        assert fetch_running_requests("http://127.0.0.1:19999/metrics") is None
+
+
+# ---------------------------------------------------------------------------
+# describe engine
+# ---------------------------------------------------------------------------
+
+SAMPLE_MODELS = {
+    "object": "list",
+    "data": [
+        {
+            "id": "meta-llama/Llama-3.1-8B-Instruct",
+            "object": "model",
+            "owned_by": "vllm",
+            "max_model_len": 131072,
+        }
+    ],
+}
+
+
+class TestDescribeEngineFields:
+    """Test that ``_describe_engine`` extracts fields from a sample
+    ``/v1/models`` response plus a ``/health`` result."""
+
+    def _run(self, models, is_healthy):
+        """Execute ``describe engine`` with mocked HTTP and return metrics dict."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "engine"
+            url = "http://localhost:8000"
+            format = "json"
+            output = None
+
+        with (
+            patch(
+                "lmcache.cli.commands.describe.fetch_json",
+                return_value=models,
+            ),
+            patch(
+                "lmcache.cli.commands.describe.fetch_health",
+                return_value=is_healthy,
+            ),
+            patch(
+                "lmcache.cli.commands.describe.fetch_running_requests",
+                return_value=3,
+            ),
+        ):
+            # Standard
+            import io
+
+            buf = io.StringIO()
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+            return json.loads(buf.getvalue())
+
+    def test_field_extraction(self):
+        """Verify model, context, status, and running requests are populated."""
+        output = self._run(SAMPLE_MODELS, is_healthy=True)
+        assert output["title"] == "Inference Engine"
+        m = output["metrics"]
+        assert m["model"] == "meta-llama/Llama-3.1-8B-Instruct"
+        assert m["max_context"] == 131072
+        assert m["status"] == "OK"
+        assert m["running_requests"] == 3
+
+    def test_unhealthy(self):
+        """Verify status shows UNHEALTHY when /health is not OK."""
+        output = self._run(SAMPLE_MODELS, is_healthy=False)
+        assert output["metrics"]["status"] == "UNHEALTHY"
+
+    def test_missing_model(self):
+        """Verify empty model list renders model/context as None."""
+        output = self._run({"object": "list", "data": []}, is_healthy=True)
+        m = output["metrics"]
+        assert m["model"] is None
+        assert m["max_context"] is None
+
+
+class TestDescribeEngineDefaultUrl:
+    def test_engine_default_url(self):
+        """Verify url=None resolves to the engine default (localhost:8000)."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "engine"
+            url = None
+            format = "json"
+            output = None
+
+        captured: dict[str, str] = {}
+
+        def fake_fetch(url, *args, **kwargs):
+            captured["url"] = url
+            return SAMPLE_MODELS
+
+        with (
+            patch(
+                "lmcache.cli.commands.describe.fetch_json",
+                side_effect=fake_fetch,
+            ),
+            patch(
+                "lmcache.cli.commands.describe.fetch_health",
+                return_value=True,
+            ),
+            patch(
+                "lmcache.cli.commands.describe.fetch_running_requests",
+                return_value=3,
+            ),
+        ):
+            # Standard
+            import io
+
+            buf = io.StringIO()
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+
+        assert "8000" in captured["url"]
+
+
+class TestDescribeEngineErrors:
+    def test_error_exits_1(self):
+        """Verify sys.exit(1) when the engine cannot be reached."""
+        # First Party
+        from lmcache.cli.commands.describe import DescribeCommand
+
+        cmd = DescribeCommand()
+
+        class FakeArgs:
+            target = "engine"
+            url = "http://localhost:8000"
+            format = None
+            output = None
+
+        with patch(
+            "lmcache.cli.commands.describe.fetch_json",
+            side_effect=DescribeError("Cannot connect"),
+        ):
+            with pytest.raises(SystemExit) as exc_info:
+                cmd.execute(FakeArgs())
+            assert exc_info.value.code == 1
diff --git a/tests/cli/test_ping.py b/tests/cli/test_ping.py
new file mode 100644
index 0000000..6364ae6
--- /dev/null
+++ b/tests/cli/test_ping.py
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``lmcache ping``."""
+
+# Standard
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from threading import Thread
+import io
+import json
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.cli.commands.ping import (
+    PingCommand,
+    ping,
+)
+
+# ---------------------------------------------------------------------------
+# Mock HTTP handler
+# ---------------------------------------------------------------------------
+
+
+class _MockHandler(BaseHTTPRequestHandler):
+    """Minimal handler that serves a canned response."""
+
+    response_body: bytes = b""
+    response_code: int = 200
+
+    def do_GET(self):
+        self.send_response(self.response_code)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(self.response_body)
+
+    def log_message(self, format, *args):
+        pass  # suppress stderr noise
+
+
+def _make_handler(code: int, body: bytes = b""):
+    return type("_H", (_MockHandler,), {"response_code": code, "response_body": body})
+
+
+def _start_server(code: int, body: bytes = b"") -> tuple[HTTPServer, int]:
+    """Start a local HTTP server and return ``(server, port)``."""
+    server = HTTPServer(("127.0.0.1", 0), _make_handler(code, body))
+    port = server.server_address[1]
+    t = Thread(target=server.handle_request, daemon=True)
+    t.start()
+    return server, port
+
+
+# ---------------------------------------------------------------------------
+# ping() helper tests
+# ---------------------------------------------------------------------------
+
+
+class TestPing:
+    def test_success(self):
+        server, port = _start_server(200)
+        try:
+            status, rtt_ms, error = ping(f"http://127.0.0.1:{port}/health")
+            assert status == "OK"
+            assert rtt_ms > 0
+            assert error is None
+        finally:
+            server.server_close()
+
+    def test_503(self):
+        body = json.dumps(
+            {"status": "unhealthy", "reason": "engine not initialized"}
+        ).encode()
+        server, port = _start_server(503, body)
+        try:
+            status, rtt_ms, error = ping(f"http://127.0.0.1:{port}/health")
+            assert status == "FAIL"
+            assert rtt_ms > 0
+            assert "503" in error
+        finally:
+            server.server_close()
+
+    def test_connection_refused(self):
+        status, rtt_ms, error = ping("http://127.0.0.1:19999/health")
+        assert status == "FAIL"
+        assert rtt_ms >= 0
+        assert "Cannot connect" in error
+
+
+# ---------------------------------------------------------------------------
+# PingCommand end-to-end tests (real HTTP server)
+# ---------------------------------------------------------------------------
+
+
+class TestPingCommandKvcache:
+    def test_ok(self):
+        body = json.dumps({"status": "healthy"}).encode()
+        server, port = _start_server(200, body)
+        try:
+            cmd = PingCommand()
+
+            class FakeArgs:
+                target = "kvcache"
+                url = f"http://127.0.0.1:{port}"
+                format = "json"
+                output = None
+
+            buf = io.StringIO()
+            # Standard
+            from unittest.mock import patch
+
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+
+            output = json.loads(buf.getvalue())
+            assert output["title"] == "Ping KV Cache"
+            m = output["metrics"]
+            assert m["status"] == "OK"
+            assert m["round_trip_time_ms"] > 0
+        finally:
+            server.server_close()
+
+    def test_503_exits_1(self):
+        body = json.dumps(
+            {"status": "unhealthy", "reason": "engine not initialized"}
+        ).encode()
+        server, port = _start_server(503, body)
+        try:
+            cmd = PingCommand()
+
+            class FakeArgs:
+                target = "kvcache"
+                url = f"http://127.0.0.1:{port}"
+                format = "json"
+                output = None
+
+            with pytest.raises(SystemExit) as exc_info:
+                cmd.execute(FakeArgs())
+            assert exc_info.value.code == 1
+        finally:
+            server.server_close()
+
+    def test_connection_refused_exits_1(self):
+        cmd = PingCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = "http://127.0.0.1:19999"
+            format = "json"
+            output = None
+
+        with pytest.raises(SystemExit) as exc_info:
+            cmd.execute(FakeArgs())
+        assert exc_info.value.code == 1
+
+
+class TestPingCommandEngine:
+    def test_ok(self):
+        server, port = _start_server(200)
+        try:
+            cmd = PingCommand()
+
+            class FakeArgs:
+                target = "engine"
+                url = f"http://127.0.0.1:{port}"
+                format = "json"
+                output = None
+
+            buf = io.StringIO()
+            # Standard
+            from unittest.mock import patch
+
+            with patch("sys.stdout", buf):
+                cmd.execute(FakeArgs())
+
+            output = json.loads(buf.getvalue())
+            assert output["title"] == "Ping Engine"
+            m = output["metrics"]
+            assert m["status"] == "OK"
+            assert m["round_trip_time_ms"] > 0
+        finally:
+            server.server_close()
+
+    def test_503_exits_1(self):
+        server, port = _start_server(503)
+        try:
+            cmd = PingCommand()
+
+            class FakeArgs:
+                target = "engine"
+                url = f"http://127.0.0.1:{port}"
+                format = "json"
+                output = None
+
+            with pytest.raises(SystemExit) as exc_info:
+                cmd.execute(FakeArgs())
+            assert exc_info.value.code == 1
+        finally:
+            server.server_close()
+
+
+# ---------------------------------------------------------------------------
+# Default URL resolution
+# ---------------------------------------------------------------------------
+
+
+class TestDefaultUrls:
+    def test_kvcache_default(self):
+        """Verify that url=None resolves to localhost:8080/healthcheck."""
+        cmd = PingCommand()
+
+        class FakeArgs:
+            target = "kvcache"
+            url = None
+            format = "json"
+            output = None
+
+        # Connection will be refused (no server), but we can check the URL
+        # from the error message.
+        with pytest.raises(SystemExit):
+            cmd.execute(FakeArgs())
+
+    def test_engine_default(self):
+        """Verify that url=None resolves to localhost:8000/health."""
+        cmd = PingCommand()
+
+        class FakeArgs:
+            target = "engine"
+            url = None
+            format = "json"
+            output = None
+
+        with pytest.raises(SystemExit):
+            cmd.execute(FakeArgs())
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 0000000..07862f1
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,920 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+# Copyright (c) 2026 Samsung Electronics Co., Ltd.All Rights Reserved
+#
+# 2026/4/20 Add mock for hf3fs_fuse
+#   Wenwen Chen <wenwen.chen@samsung.com>
+
+# Standard
+from dataclasses import dataclass
+from multiprocessing.shared_memory import SharedMemory
+from pathlib import Path
+from typing import Optional
+from unittest.mock import patch
+import asyncio
+import importlib.util
+import os
+import random
+import shlex
+import socket
+import subprocess
+import time
+
+# Third Party
+import numpy as np
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+
+if importlib.util.find_spec("pytest_benchmark") is None:
+
+    @pytest.fixture
+    def benchmark():
+        pytest.skip("pytest-benchmark is not installed")
+
+
+@pytest.fixture(scope="session", autouse=True)
+def disable_usage_tracking():
+    """Keep the test suite from sending usage telemetry to the stats server.
+
+    Tests that exercise the telemetry itself (tests/test_usage_context.py)
+    re-enable it per-test via monkeypatch with an injected transport.
+    """
+    os.environ["LMCACHE_TRACK_USAGE"] = "false"
+    yield
+
+
+# This is to mock the constructor and destructor of
+# MixedMemoryAllocator and PinMemoryAllocator to
+# use pin_memory=True for their constructors and
+# avoid calling cudaHostRegister and cudaHostUnregister
+# which may throw an error if torch.empty returns a buffer
+# that cannot be registered (which happens quicker on some machines,
+# especially when torch is doing many allocations and frees)
+
+
+# In production, using the cuda C++ API gives us a larger pinned buffer
+# but for the tests, we do not need this so this mock leaves the unit tests
+# functionally the same
+"""
+@pytest.fixture(autouse=True, scope="session")
+def patch_mixed_allocator():
+    def fake_mixed_init(self, size: int, use_paging: bool = False, **kwargs):
+        # self.buffer = torch.empty(size, dtype=torch.uint8)
+        # ptr = self.buffer.data_ptr()
+        # err = torch.cuda.cudart().cudaHostRegister(ptr, size, 0)
+        # assert err == 0, (
+        #     f"cudaHostRegister failed: {torch.cuda.cudart().cudaGetErrorString(err)}"
+        # )
+        self._unregistered = False
+        self.buffer = torch.empty(size, dtype=torch.uint8, pin_memory=True)
+
+        if use_paging:
+            assert "shape" in kwargs, (
+                "shape must be specified for paged memory allocator"
+            )
+            assert "dtype" in kwargs, (
+                "dtype must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.pin_allocator = PagedTensorMemoryAllocator(
+                tensor=self.buffer,
+                shape=kwargs["shape"],
+                dtype=kwargs["dtype"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.pin_allocator = TensorMemoryAllocator(self.buffer)
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+        self.buffer_allocator = BufferAllocator("cpu")
+
+    def fake_mixed_close(self):
+        if not self._unregistered:
+            torch.cuda.synchronize()
+            # torch.cuda.cudart().cudaHostUnregister(self.buffer.data_ptr())
+            self._unregistered = True
+
+    with (
+        patch(
+            "lmcache.v1.memory_allocators.mixed_memory_allocator.MixedMemoryAllocator.__init__",
+            fake_mixed_init,
+        ),
+        patch(
+            "lmcache.v1.memory_allocators.mixed_memory_allocator.MixedMemoryAllocator.close",
+            fake_mixed_close,
+        ),
+    ):
+        yield
+
+
+@pytest.fixture(autouse=True, scope="session")
+def patch_pin_allocator():
+    def fake_pin_init(self, size: int, use_paging: bool = False, **kwargs):
+
+        # self.buffer = torch.empty(size, dtype=torch.uint8)
+        # ptr = self.buffer.data_ptr()
+        # err = torch.cuda.cudart().cudaHostRegister(ptr, size, 0)
+        # assert err == 0, (
+        #     f"cudaHostRegister failed: {torch.cuda.cudart().cudaGetErrorString(err)}"
+        # )
+        self._unregistered = False
+        self.buffer = torch.empty(size, dtype=torch.uint8, pin_memory=True)
+
+        if use_paging:
+            assert "shape" in kwargs, (
+                "shape must be specified for paged memory allocator"
+            )
+            assert "dtype" in kwargs, (
+                "dtype must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.allocator = PagedTensorMemoryAllocator(
+                tensor=self.buffer,
+                shape=kwargs["shape"],
+                dtype=kwargs["dtype"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.allocator = TensorMemoryAllocator(self.buffer)
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+    def fake_pin_close(self):
+        if not self._unregistered:
+            torch.cuda.synchronize()
+            # torch.cuda.cudart().cudaHostUnregister(self.buffer.data_ptr())
+            self._unregistered = True
+
+    with (
+        patch(
+            "lmcache.v1.memory_allocators.pin_memory_allocator.PinMemoryAllocator.__init__",
+            fake_pin_init,
+        ),
+        patch(
+            "lmcache.v1.memory_allocators.pin_memory_allocator.PinMemoryAllocator.close",
+            fake_pin_close,
+        ),
+    ):
+        yield
+"""
+
+
+class MockSyncGlideClient:
+    """In-memory mock of a synchronous Glide (Valkey) client."""
+
+    _store: dict[bytes, bytes] = {}
+    #: Records the ``expiry`` argument from the most recent ``set`` call so
+    #: tests can assert TTL behavior. ``None`` means no expiry was passed.
+    last_expiry = None
+
+    def set(self, key: bytes, value, expiry=None) -> None:
+        self._store[key] = bytes(value)
+        type(self).last_expiry = expiry
+
+    def get(self, key: bytes, buffer=None):
+        data = self._store.get(key)
+        if buffer is None:
+            return data
+        # Mirror glide's native buffer-GET: write into the caller's buffer and
+        # return the number of bytes read (an int count), or None on miss.
+        if data is None:
+            return None
+        n = len(data)
+        buffer[:n] = data
+        return n
+
+    def exists(self, keys: list[bytes]) -> int:
+        return sum(1 for k in keys if k in self._store)
+
+    @classmethod
+    def reset_store(cls) -> None:
+        cls._store.clear()
+        cls.last_expiry = None
+
+
+class MockRedis:
+    def __init__(
+        self, host=None, port=None, url=None, decode_responses=False, **kwargs
+    ):
+        self.store = {}
+        self.host = host
+        self.port = port
+        self.url = url
+        self.decode_responses = decode_responses
+
+    def set(self, key, value):
+        self.store[key] = value
+        return True
+
+    def get(self, key):
+        return self.store.get(key, None)
+
+    def exists(self, key):
+        return key in self.store
+
+    def delete(self, key):
+        return self.store.pop(key, None) is not None
+
+    def scan(self, cursor=0, match=None):
+        keys = [s.encode("utf-8") for s in self.store.keys()]
+        return (0, keys)
+
+    def close(self):
+        pass
+
+    @classmethod
+    def from_url(cls, url, decode_responses=False, **kwargs):
+        """Mock implementation of Redis.from_url"""
+        return cls(url=url, decode_responses=decode_responses, **kwargs)
+
+    @classmethod
+    def from_pool(cls, pool, **kwargs):
+        """Mock implementation of Redis.from_pool"""
+        return cls(**kwargs)
+
+
+class MockAsyncRedis(MockRedis):
+    """Async version of MockRedis"""
+
+    async def set(self, key, value):
+        self.store[key] = value
+        return True
+
+    async def get(self, key):
+        return self.store.get(key, None)
+
+    async def exists(self, key):
+        return key in self.store
+
+    async def delete(self, key):
+        return self.store.pop(key, None) is not None
+
+    async def close(self):
+        pass
+
+    @classmethod
+    def from_url(cls, url, decode_responses=False, **kwargs):
+        """Mock implementation of Redis.from_url"""
+        return cls(url=url, decode_responses=decode_responses, **kwargs)
+
+    @classmethod
+    def from_pool(cls, pool, **kwargs):
+        """Mock implementation of Redis.from_pool"""
+        return cls(**kwargs)
+
+
+class MockRedisSentinel:
+    def __init__(self, hosts_and_ports, socket_timeout=None, **kwargs):
+        self.hosts_and_ports = hosts_and_ports
+        self.socket_timeout = socket_timeout
+        # Create a shared store but separate instances for master/slave
+        self.shared_store = {}
+        self.master_redis = MockRedis()
+        self.slave_redis = MockRedis()
+        # Share the store between master and slave to simulate Redis Sentinel behavior
+        self.master_redis.store = self.shared_store
+        self.slave_redis.store = self.shared_store
+
+    def master_for(
+        self, service_name, socket_timeout=None, username=None, password=None, **kwargs
+    ):
+        return self.master_redis
+
+    def slave_for(
+        self, service_name, socket_timeout=None, username=None, password=None, **kwargs
+    ):
+        return self.slave_redis
+
+
+class MockRESPClient:
+    """In-memory mock of RESPClient so RESP connector tests never hit real Redis."""
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        num_workers: int,
+        loop=None,
+        username: str = "",
+        password: str = "",
+    ):
+        self._store: dict[str, bytes] = {}  # key -> bytes
+        self._loop = loop
+        self._closed = False
+        self._username = username
+        self._password = password
+
+    async def exists(self, key: str) -> bool:
+        return key in self._store
+
+    def exists_sync(self, key: str) -> bool:
+        if self._loop is None:
+            return key in self._store
+        fut = asyncio.run_coroutine_threadsafe(self.exists(key), self._loop)
+        return fut.result(timeout=10.0)
+
+    def _copy_into_buf(self, buf: memoryview, data: bytes) -> None:
+        """
+        Copy bytes into buffer; buf may be non-byte or multi-dimensional
+        (e.g. from bfloat16 tensor).
+        """
+        view = buf.cast("B")
+        n = len(data)
+        try:
+            view[:n] = data
+        except (NotImplementedError, TypeError, ValueError):
+            # Multi-dimensional or non-contiguous:
+            # write via flat numpy view (same memory)
+            arr = np.asarray(view, dtype=np.uint8, copy=False)
+            arr.flat[:n] = np.frombuffer(data, dtype=np.uint8, count=n)
+
+    async def get(self, key: str, buf: memoryview) -> None:
+        data = self._store.get(key)
+        if data is None:
+            raise RuntimeError("key not found")
+        self._copy_into_buf(buf, data)
+
+    async def set(self, key: str, buf: memoryview) -> None:
+        self._store[key] = bytes(buf.cast("B"))
+
+    async def batch_get(self, keys: list, bufs: list) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        for k, b in zip(keys, bufs, strict=False):
+            data = self._store.get(k)
+            if data is None:
+                raise RuntimeError("key not found")
+            self._copy_into_buf(b, data)
+
+    async def batch_set(self, keys: list, bufs: list) -> None:
+        if len(keys) != len(bufs):
+            raise ValueError("keys and bufs length mismatch")
+        for k, b in zip(keys, bufs, strict=False):
+            self._store[k] = bytes(b.cast("B"))
+
+    async def batch_exists(self, keys: list) -> list:
+        return [k in self._store for k in keys]
+
+    def batch_exists_sync(self, keys: list) -> list:
+        if self._loop is None:
+            return [k in self._store for k in keys]
+        fut = asyncio.run_coroutine_threadsafe(self.batch_exists(keys), self._loop)
+        return fut.result(timeout=10.0)
+
+    def close(self) -> None:
+        self._closed = True
+        self._store.clear()
+
+
+class MockRedisCluster:
+    def __init__(
+        self, startup_nodes=None, max_connections=None, decode_responses=False, **kwargs
+    ):
+        self.startup_nodes = startup_nodes or []
+        self.max_connections = max_connections
+        self.decode_responses = decode_responses
+        self.store = {}
+
+    async def set(self, key, value):
+        self.store[key] = value
+        return True
+
+    async def get(self, key):
+        return self.store.get(key, None)
+
+    async def exists(self, key):
+        return key in self.store
+
+    async def delete(self, key):
+        return self.store.pop(key, None) is not None
+
+    async def close(self):
+        pass
+
+
+class MockHf3fsIoring:
+    """Mock I/O ring that stores data to local temp storage.
+
+    This mock implements the same interface as the real hf3fs ioring,
+    but uses local filesystem for actual I/O operations.
+    """
+
+    def __init__(
+        self,
+        mount_point: str,
+        entries: int,
+        for_read: bool = True,
+        timeout: int = 200,
+        numa: int = -1,
+    ):
+        self.mount_point = mount_point
+        self.entries = entries
+        self.for_read = for_read
+        self.timeout = timeout
+        self.numa = numa
+        self._prepared_iov = None
+        self._prepared_is_read: Optional[bool] = None
+        self._prepared_fd: Optional[int] = None
+        self._prepared_offset: Optional[int] = None
+        self._result_bytes = 0
+
+    def prepare(self, iov, is_read: bool, fd: int, offset: int):
+        """Prepare I/O operation - stores parameters for later use."""
+        self._prepared_iov = iov
+        self._prepared_is_read = is_read
+        self._prepared_fd = fd
+        self._prepared_offset = offset
+
+    def submit(self):
+        """Submit I/O operation - performs actual file I/O.
+
+        For write operations: writes data from shared memory to file.
+        For read operations: reads data from file into shared memory.
+        """
+        # Standard
+        import sys
+
+        if self._prepared_iov is None or self._prepared_fd is None:
+            return self
+
+        try:
+            # Get the shared memory buffer from iov
+            shm = self._prepared_iov.shm
+            if shm is None:
+                print(
+                    f"MockHf3fsIoring.submit: shm is None, "
+                    f"_prepared_iov={self._prepared_iov}",
+                    file=sys.stderr,
+                )
+                return self
+
+            # Get the length of data to transfer
+            slice_start = 0
+            if hasattr(self._prepared_iov, "slice_start"):
+                slice_start = self._prepared_iov.slice_start
+            slice_end = None
+            if hasattr(self._prepared_iov, "slice_end"):
+                slice_end = self._prepared_iov.slice_end
+
+            if slice_end is not None:
+                length = slice_end - slice_start
+            elif slice_start > 0:
+                length = shm.size - slice_start if hasattr(shm, "size") else 4096
+            else:
+                length = shm.size if hasattr(shm, "size") else 4096
+
+            if self._prepared_is_read:
+                os.lseek(self._prepared_fd, self._prepared_offset, os.SEEK_SET)
+                # Read data from file
+                data = os.read(self._prepared_fd, length)
+                # Write data to shared memory using slice range
+                if slice_end:
+                    shm.buf[slice_start:slice_end] = data
+                else:
+                    shm.buf[slice_start:] = data
+                self._result_bytes = len(data)
+            else:
+                # Get data from shared memory using slice range
+                if slice_end:
+                    data = bytes(shm.buf[slice_start:slice_end])
+                else:
+                    data = bytes(shm.buf[slice_start:])
+                os.lseek(self._prepared_fd, self._prepared_offset, os.SEEK_SET)
+                # Write data to file
+                bytes_written = os.write(self._prepared_fd, data)
+                self._result_bytes = bytes_written
+
+        except Exception as e:
+            # Log error but don't fail - return 0 bytes
+            # Standard
+            import traceback
+
+            print(f"MockHf3fsIoring.submit error: {e}", file=sys.stderr)
+            traceback.print_exc(file=sys.stderr)
+            self._result_bytes = 0
+
+        return self
+
+    def wait(self, min_results: int = 1):
+        """Wait for I/O completion and return results.
+
+        Returns:
+            List of MockIorResult, each with .result containing bytes transferred
+        """
+
+        class MockIorResult:
+            def __init__(self, result: int):
+                self.result = result
+
+        return [MockIorResult(self._result_bytes)]
+
+
+class MockHf3fsIovec:
+    """Mock I/O vector for HF3FS operations."""
+
+    def __init__(
+        self,
+        shm: SharedMemory,
+        hf3fs_mount_point: str,
+        numa: int = -1,
+        slice_start: int = 0,
+        slice_end: Optional[int] = None,
+    ):
+        self.shm = shm
+        self.mount_point = hf3fs_mount_point
+        self.numa = numa
+        self.slice_start = slice_start
+        self.slice_end = slice_end  # None means full range
+
+    def __getitem__(self, index):
+        # Support slicing operation, e.g., iov[:length]
+        if isinstance(index, slice):
+            start = index.start or 0
+            end = index.stop
+            return MockHf3fsIovec(self.shm, self.mount_point, self.numa, start, end)
+        return self
+
+    def __len__(self):
+        if self.slice_end is not None:
+            return self.slice_end - self.slice_start
+        elif self.slice_start > 0:
+            return getattr(self.shm, "size", 4096) - self.slice_start
+        return getattr(self.shm, "size", 4096)
+
+
+class MockHf3fsFuse:
+    """Mock for hf3fs_fuse.io module functions."""
+
+    @staticmethod
+    def extract_mount_point(path: str) -> str:
+        """Mock extract_mount_point - returns the path as-is if it exists.
+
+        In real 3FS, this function extracts the actual 3FS mount point from a path.
+        For testing, we just return the path if it exists, or return as-is.
+        """
+        p = Path(path)
+        if p.exists():
+            return str(p.resolve())
+        return path
+
+    @staticmethod
+    def make_iovec(shm: SharedMemory, hf3fs_mount_point: str, numa: int = -1):
+        """Mock make_iovec - creates a mock I/O vector."""
+        return MockHf3fsIovec(shm, hf3fs_mount_point, numa)
+
+    @staticmethod
+    def make_ioring(
+        mount_point: str,
+        entries: int,
+        for_read: bool = True,
+        timeout: int = 200,
+        numa: int = -1,
+    ):
+        """Mock make_ioring - creates a mock I/O ring."""
+        return MockHf3fsIoring(mount_point, entries, for_read, timeout, numa)
+
+    @staticmethod
+    def register_fd(fd: int):
+        """Mock register_fd - no-op for testing."""
+        pass
+
+    @staticmethod
+    def deregister_fd(fd: int):
+        """Mock deregister_fd - no-op for testing."""
+        pass
+
+
+@dataclass
+class LMCacheServerProcess:
+    server_url: str
+    server_process: object
+
+
+@pytest.fixture(scope="function", autouse=True)
+def mock_redis():
+    with (
+        patch("redis.Redis", MockRedis) as mock_redis_class,
+        patch("redis.from_url", MockRedis.from_url),
+        patch("redis.asyncio.Redis", MockAsyncRedis),
+        patch("redis.asyncio.from_url", MockAsyncRedis.from_url),
+        patch("redis.asyncio.ConnectionPool.from_url", lambda url, **kwargs: None),
+        patch("redis.asyncio.Redis.from_pool", MockAsyncRedis.from_pool),
+    ):
+        yield mock_redis_class
+
+
+@pytest.fixture(scope="function", autouse=True)
+def mock_redis_sentinel():
+    with (
+        patch("redis.Sentinel", MockRedisSentinel) as mock,
+        patch("redis.asyncio.Sentinel", MockRedisSentinel),
+    ):
+        yield mock
+
+
+@pytest.fixture(scope="function", autouse=True)
+def mock_redis_cluster():
+    with patch("redis.asyncio.cluster.RedisCluster", MockRedisCluster) as mock:
+        yield mock
+
+
+@pytest.fixture(scope="function", autouse=True)
+def mock_hf3fs():
+    """Mock hf3fs_fuse.io module for testing without 3FS filesystem.
+
+    This fixture creates a fake hf3fs_fuse.io module in sys.modules before
+    any imports happen, allowing tests to run without the actual package.
+    """
+    # Standard
+    from types import ModuleType
+    import sys
+
+    # Create a fake hf3fs_fuse module if it doesn't exist
+    hf3fs_fuse = ModuleType("hf3fs_fuse")
+    hf3fs_fuse.__file__ = "/mock/hf3fs_fuse/__init__.py"
+
+    # Create hf3fs_fuse.io module
+    hf3fs_io = ModuleType("hf3fs_fuse.io")
+    hf3fs_io.__file__ = "/mock/hf3fs_fuse/io.py"
+
+    # Add mock functions to hf3fs_fuse.io
+    hf3fs_io.extract_mount_point = MockHf3fsFuse.extract_mount_point
+    hf3fs_io.make_iovec = MockHf3fsFuse.make_iovec
+    hf3fs_io.make_ioring = MockHf3fsFuse.make_ioring
+    hf3fs_io.register_fd = MockHf3fsFuse.register_fd
+    hf3fs_io.deregister_fd = MockHf3fsFuse.deregister_fd
+
+    # Register modules in sys.modules
+    sys.modules["hf3fs_fuse"] = hf3fs_fuse
+    sys.modules["hf3fs_fuse.io"] = hf3fs_io
+
+    yield
+
+    # Cleanup: remove the mock modules after test
+    sys.modules.pop("hf3fs_fuse", None)
+    sys.modules.pop("hf3fs_fuse.io", None)
+
+
+@pytest.fixture(scope="module")
+def lmserver_v1_process(request):
+    def ensure_connection(host, port):
+        retries = 10
+        client_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        successful = False
+        while retries > 0:
+            retries -= 1
+            try:
+                print("Probing connection, remaining retries: ", retries)
+                client_socket.connect((host, port))
+                successful = True
+                break
+            except ConnectionRefusedError:
+                time.sleep(1)
+                print("Connection refused!")
+                continue
+            except Exception as e:
+                print(f"other Exception: {e}")
+                continue
+
+        client_socket.close()
+        return successful
+
+    # Specify remote device
+    device = request.param
+
+    # Start the process
+    max_retries = 5
+    while max_retries > 0:
+        max_retries -= 1
+        port_number = random.randint(10000, 65500)
+        print("Starting the lmcache v1 server process on port")
+        proc = subprocess.Popen(
+            shlex.split(
+                f"python3 -m lmcache.v1.server localhost {port_number} {device}"
+            )
+        )
+
+        # Wait for lmcache process to start
+        time.sleep(5)
+
+        successful = False
+        if proc.poll() is not None:
+            successful = True
+        else:
+            successful = ensure_connection("localhost", port_number)
+
+        if not successful:
+            proc.terminate()
+            proc.wait()
+        else:
+            break
+
+    # Yield control back to the test until it finishes
+    server_url = f"lm://localhost:{port_number}"
+    yield LMCacheServerProcess(server_url, proc)
+
+    # Terminate the process
+    proc.terminate()
+    proc.wait()
+
+    # Destroy remote disk path
+    if device not in ["cpu"]:
+        subprocess.run(shlex.split(f"rm -rf {device}"))
+
+
+@pytest.fixture(scope="function")
+def autorelease(request):
+    objects = []
+
+    def _factory(obj):
+        objects.append(obj)
+        return obj
+
+    yield _factory
+
+    # Cleanup all objects created by the factory
+    for obj in objects:
+        obj.close()
+
+
+@pytest.fixture(scope="function")
+def autorelease_v1(request):
+    objects = []
+
+    def _factory(obj, **kwargs):
+        if isinstance(obj, LMCacheEngine):
+            obj.post_init(**kwargs)
+        objects.append(obj)
+        return obj
+
+    yield _factory
+
+    LMCacheEngineBuilder.destroy("test")
+
+    # Cleanup all objects created by the factory
+    # IMPORTANT: We must close connectors to ensure AsyncPQExecutor and other
+    # async resources are properly cleaned up
+    # NOTE: Skip LMCacheEngine instances since destroy() already calls close()
+    for obj in objects:
+        if isinstance(obj, LMCacheEngine):
+            continue
+        try:
+            # Check if object has a close method
+            if hasattr(obj, "close"):
+                obj.close()
+        except Exception as e:
+            # Log but don't fail the test
+            print("Error during close obj:%s - %s", obj, e)
+
+
+@pytest.fixture(scope="session")
+def memory_allocator():
+    """One MixedMemoryAllocator (5GB) for the whole test session;
+    .close() is a no-op per-test."""
+    _real = MixedMemoryAllocator(5 * 1024 * 1024 * 1024)  # 5GB
+
+    class _NoCloseWrapper:
+        def __init__(self, real):
+            self._real = real
+
+        def __getattr__(self, name):
+            return getattr(self._real, name)
+
+        def close(self):
+            # No-op so per-test close() calls don't shut down the shared allocator
+            pass
+
+    try:
+        yield _NoCloseWrapper(_real)
+    finally:
+        # Actually close once when the session ends
+        _real.close()
+
+
+@pytest.fixture(autouse=True)  # function-scoped by default
+def use_shared_allocator(request, monkeypatch, memory_allocator):
+    """Default: patch. Opt out with @pytest.mark.no_shared_allocator."""
+    if request.node.get_closest_marker("no_shared_allocator"):
+        # do NOT patch for this test
+        yield
+        return
+
+    def _create_shared_allocator(config, metadata, numa_mapping):
+        return memory_allocator
+
+    monkeypatch.setattr(
+        LMCacheEngineBuilder,
+        "_Create_memory_allocator",
+        _create_shared_allocator,
+    )
+    yield
+
+
+@pytest.fixture(scope="function")
+def lmcache_engine_metadata(role="worker"):
+    """Create a fresh LMCacheMetadata for each test."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(32, 2, 256, 32, 128),
+        use_mla=False,
+        role=role,
+    )
+
+
+@pytest.fixture(scope="session")
+def bigtable_emulator():
+    """Start or connect to the Bigtable emulator for integration testing."""
+    # Standard
+    import os
+    import shutil
+    import subprocess
+    import time
+
+    existing_host = os.environ.get("BIGTABLE_EMULATOR_HOST")
+    if existing_host:
+        print(f"\n[Fixture] Reusing existing Bigtable emulator at {existing_host}...")
+        yield existing_host
+        return
+
+    if os.environ.get("CI") == "true" or os.environ.get("GITHUB_ACTIONS") == "true":
+        pytest.skip("Skipping Bigtable emulator integration tests in CI")
+
+    if not shutil.which("gcloud"):
+        pytest.skip(
+            "gcloud CLI not found, skipping Bigtable Emulator integration tests"
+        )
+
+    port = "8899"
+    host_port = f"localhost:{port}"
+
+    print(f"\n[Fixture] Starting Bigtable emulator on {host_port}...")
+    emulator_process = subprocess.Popen(
+        [
+            "gcloud",
+            "beta",
+            "emulators",
+            "bigtable",
+            "start",
+            f"--host-port={host_port}",
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+    os.environ["BIGTABLE_EMULATOR_HOST"] = host_port
+
+    def is_port_open(h: str, p: int, t: float = 1.0) -> bool:
+        # Standard
+        import socket
+
+        try:
+            with socket.create_connection((h, p), timeout=t):
+                return True
+        except OSError:
+            return False
+
+    # Wait for the emulator to initialize
+    port_num = int(port)
+    start_time = time.time()
+    success = False
+    while time.time() - start_time < 10.0:
+        if is_port_open("localhost", port_num):
+            success = True
+            break
+        time.sleep(0.5)
+
+    if not success:
+        print(
+            f"\n[Fixture] Bigtable emulator failed to bind to {host_port} within 10s!"
+        )
+        try:
+            stdout, stderr = emulator_process.communicate(timeout=2.0)
+            print(f"Stdout:\n{stdout.decode('utf-8', errors='ignore')}")
+            print(f"Stderr:\n{stderr.decode('utf-8', errors='ignore')}")
+        except Exception as e:
+            print(f"Could not retrieve process logs: {e}")
+        emulator_process.kill()
+        pytest.fail("Failed to start Bigtable emulator")
+
+    yield host_port
+
+    print("\n[Fixture] Stopping Bigtable emulator...")
+    emulator_process.terminate()
+    try:
+        emulator_process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        emulator_process.kill()
+
+    if "BIGTABLE_EMULATOR_HOST" in os.environ:
+        del os.environ["BIGTABLE_EMULATOR_HOST"]
diff --git a/tests/data/test_creation_from_file/disk.yaml b/tests/data/test_creation_from_file/disk.yaml
new file mode 100644
index 0000000..5e7af3a
--- /dev/null
+++ b/tests/data/test_creation_from_file/disk.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_device: "file:///tmp"
+remote_url: null
+remote_serde: null
diff --git a/tests/data/test_creation_from_file/fail.yaml b/tests/data/test_creation_from_file/fail.yaml
new file mode 100644
index 0000000..933a8b6
--- /dev/null
+++ b/tests/data/test_creation_from_file/fail.yaml
@@ -0,0 +1 @@
+chunk_size: 256
diff --git a/tests/data/test_creation_from_file/hybrid.yaml b/tests/data/test_creation_from_file/hybrid.yaml
new file mode 100644
index 0000000..40ba10a
--- /dev/null
+++ b/tests/data/test_creation_from_file/hybrid.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_device: "cpu"
+remote_url: "lm://localhost:65000"
+remote_serde: "safetensor"
diff --git a/tests/data/test_creation_from_file/local.yaml b/tests/data/test_creation_from_file/local.yaml
new file mode 100644
index 0000000..91c2565
--- /dev/null
+++ b/tests/data/test_creation_from_file/local.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_device: "cpu"
+remote_url: null
+remote_serde: null
diff --git a/tests/data/test_creation_from_file/remote.yaml b/tests/data/test_creation_from_file/remote.yaml
new file mode 100644
index 0000000..34bfe3d
--- /dev/null
+++ b/tests/data/test_creation_from_file/remote.yaml
@@ -0,0 +1,4 @@
+chunk_size: 256
+local_device: null
+remote_url: "lm://localhost:65000"
+remote_serde: "cachegen"
diff --git a/tests/disagg/README.md b/tests/disagg/README.md
new file mode 100644
index 0000000..8557ae9
--- /dev/null
+++ b/tests/disagg/README.md
@@ -0,0 +1,136 @@
+# Test disaggregated prefill related components
+
+## NIXL Pipe
+
+```bash
+# Terminal 1 (sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=0 python3 test_nixl_pipe.py --role sender
+ 
+# Terminal 2 (receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=1 python3 test_nixl_pipe.py --role receiver
+```
+
+## NIXL Channel
+
+```bash
+# Terminal 1 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=0 python3 test_nixl_channel.py --role sender --num-objs 500
+
+# Terminal 2 (Receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=1 python3 test_nixl_channel.py --role receiver --num-objs 500
+```
+
+NOTE: why 500 objects? -- Because we the pipe only has 4GB buffer, but 500 objects are 16GB in total. This is to test when the data to transfer is larger than the buffer size, how the sender/receiver behaves.
+
+## NIXL Backend
+
+```bash
+# Terminal 1 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=0 python3 test_nixl_storage_backend.py --role sender --num-objs 500
+
+# Terminal 2 (Receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=1 python3 test_nixl_storage_backend.py --role receiver --num-objs 500
+```
+
+Sender side logs:
+```plaintext
+[2025-04-07 13:00:26,142] LMCache INFO: Generated 500 objects with total size 16000.00 MB (test_nixl_storage_backend.py:70:__main__)
+Loaded plugin UCX
+Loaded plugin UCX_MO
+Initialized NIXL agent: NixlRole.SENDER
+[2025-04-07 13:00:26,339] LMCache INFO: Received remote transfer descriptors (nixl_connector.py:103:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,340] LMCache INFO: Sending 500 objects... (test_nixl_storage_backend.py:89:__main__)
+[2025-04-07 13:00:28,343] LMCache DEBUG: Committing write with 128 transfers (nixl_connector.py:188:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,377] LMCache DEBUG: Transfer completed in 33.7618 ms, creating the transfer: 0.0229 ms, transfer time: 18.9432 ms, wait for receiver: 14.7957 ms
+Pure transfer throughput: 211.1577 GB/s (nixl_connector.py:229:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,378] LMCache DEBUG: Committing write with 128 transfers (nixl_connector.py:188:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,404] LMCache DEBUG: Transfer completed in 25.6334 ms, creating the transfer: 0.0167 ms, transfer time: 11.9316 ms, wait for receiver: 13.6851 ms
+Pure transfer throughput: 335.2434 GB/s (nixl_connector.py:229:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,406] LMCache DEBUG: Committing write with 128 transfers (nixl_connector.py:188:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,432] LMCache DEBUG: Transfer completed in 26.4169 ms, creating the transfer: 0.0132 ms, transfer time: 11.6180 ms, wait for receiver: 14.7857 ms
+Pure transfer throughput: 344.2922 GB/s (nixl_connector.py:229:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,434] LMCache DEBUG: Committing write with 116 transfers (nixl_connector.py:188:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,458] LMCache DEBUG: Transfer completed in 23.8715 ms, creating the transfer: 0.0131 ms, transfer time: 11.1843 ms, wait for receiver: 12.6741 ms
+Pure transfer throughput: 324.1156 GB/s (nixl_connector.py:229:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,458] LMCache INFO: Sent 500 objects in 0.117705 seconds (test_nixl_storage_backend.py:95:__main__)
+[2025-04-07 13:00:28,458] LMCache INFO: Throughput: 132.75 GB/s (test_nixl_storage_backend.py:97:__main__)
+[2025-04-07 13:00:30,461] LMCache INFO: Test completed (test_nixl_storage_backend.py:153:__main__)
+```
+
+Receiver side logs:
+```
+[2025-04-07 13:00:26,094] LMCache INFO: Generated 500 objects with total size 16000.00 MB (test_nixl_storage_backend.py:70:__main__)
+Loaded plugin UCX
+Loaded plugin UCX_MO
+Initialized NIXL agent: NixlRole.RECEIVER
+[2025-04-07 13:00:26,317] LMCache INFO: Sent local transfer descriptors to sender (nixl_connector.py:115:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:26,317] LMCache INFO: Waiting to receive data... (test_nixl_storage_backend.py:101:__main__)
+[2025-04-07 13:00:28,341] LMCache DEBUG: Received event on the side channel, processing message... (nixl_connector.py:394:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,342] LMCache DEBUG: Received request with 500 keys and UUID: f69f0509846943eb9e478b021afe8127 (nixl_connector.py:403:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,359] LMCache INFO: Transfer for UUID 'f69f0509846943eb9e478b021afe8127' completed on the remote side (NixlRole.SENDER) (nixl_connector.py:251:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,359] LMCache DEBUG: Received 128 keys and 128 objects. (nixl_backend.py:51:lmcache.v1.storage_backend.nixl_backend)
+[2025-04-07 13:00:28,375] LMCache DEBUG: Observers processing in 15.6546 ms (nixl_connector.py:370:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,387] LMCache INFO: Transfer for UUID 'e4db696cc1604caaac790af47f111145' completed on the remote side (NixlRole.SENDER) (nixl_connector.py:251:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,388] LMCache DEBUG: Received 128 keys and 128 objects. (nixl_backend.py:51:lmcache.v1.storage_backend.nixl_backend)
+[2025-04-07 13:00:28,403] LMCache DEBUG: Observers processing in 15.8146 ms (nixl_connector.py:370:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,414] LMCache INFO: Transfer for UUID 'ead0858f0f134270b260ad4f2e05e121' completed on the remote side (NixlRole.SENDER) (nixl_connector.py:251:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,415] LMCache DEBUG: Received 128 keys and 128 objects. (nixl_backend.py:51:lmcache.v1.storage_backend.nixl_backend)
+[2025-04-07 13:00:28,432] LMCache DEBUG: Observers processing in 16.5569 ms (nixl_connector.py:370:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,441] LMCache INFO: Transfer for UUID '7cdbf69484ed4d3ca2ad9df35d00a402' completed on the remote side (NixlRole.SENDER) (nixl_connector.py:251:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,442] LMCache DEBUG: Received 116 keys and 116 objects. (nixl_backend.py:51:lmcache.v1.storage_backend.nixl_backend)
+[2025-04-07 13:00:28,457] LMCache DEBUG: Observers processing in 15.1075 ms (nixl_connector.py:370:lmcache.v1.storage_backend.connector.nixl_connector)
+[2025-04-07 13:00:28,522] LMCache INFO: Received all 500 objects (test_nixl_storage_backend.py:123:__main__)
+[2025-04-07 13:00:28,556] LMCache INFO: All data verified successfully! (test_nixl_storage_backend.py:146:__main__)
+```
+
+**Measured performance:** 132.75 GB/s
+
+## CacheEngine
+
+```bash
+# Terminal 1 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=0 python3 test_nixl_cache_engine.py --role sender --num-chunks 500 --num-rounds 5
+
+# Terminal 2 (Receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=1 python3 test_nixl_cache_engine.py --role receiver --num-chunks 500 --num-rounds 5
+```
+
+Measured performance: 70.97 ± 7.66 GB/s 
+
+## NIXL Pipe V2
+
+Added new `--simulate-work` flag to simulate the LLM work on both sender and receiver sides. On sender side: 50ms per 10 objects, and on receiver side: 20ms per 10 objects.
+
+```bash
+# Terminal 1 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=0 python3 test_nixl_pipe_v2.py --role sender --num-rounds 5 --num-objs 500 --simulate-work
+
+# Terminal 2 (Receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=1 python3 test_nixl_pipe_v2.py --role receiver --num-rounds 5 --num-objs 500 --simulate-work
+```
+
+## NIXL Channel v2 testing
+
+Introduced a new option: `--batch-size` to control the number of objects in each batch when calling send. 
+
+```bash
+# Terminal 1 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=0 python3 test_nixl_channel_v2.py --role sender --num-objs 1000 --batch-size 30 --simulate-workload
+
+# Terminal 2 (Receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=1 python3 test_nixl_channel_v2.py --role receiver --num-objs 1000 --batch-size 30 --simulate-workload
+```
+## NIXL Channel v2 multiplexing testing
+
+Introduced a new option: `--num-expected-sender` to control the number of senders.
+
+```bash
+# Terminal 1 (Receiver)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=7 python3 test_nixl_channel_v2.py --role receiver --num-objs 500 --batch-size 30 --simulate-workload --num-expected-senders 2
+
+# Terminal 2 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=6 python3 test_nixl_channel_v2.py --role sender --num-objs 500 --batch-size 30 --simulate-workload
+
+# Terminal 3 (Sender)
+UCX_TLS=cuda_ipc,cuda_copy,tcp CUDA_VISIBLE_DEVICES=3 python3 test_nixl_channel_v2.py --role sender --num-objs 500 --batch-size 30 --simulate-workload
+```
diff --git a/tests/disagg/test_nixl_cache_engine.py b/tests/disagg/test_nixl_cache_engine.py
new file mode 100644
index 0000000..47a1c0a
--- /dev/null
+++ b/tests/disagg/test_nixl_cache_engine.py
@@ -0,0 +1,337 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import random
+import time
+
+# Third Party
+from tqdm import tqdm
+import numpy as np
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.gpu_connectors import VLLMPagedMemGPUConnectorV2
+from lmcache.v1.metadata import LMCacheMetadata
+
+logger = init_logger(__name__)
+
+
+def generate_test_tokens(num_chunks: int, chunk_size: int) -> torch.Tensor:
+    """Generate test tokens for testing.
+    The sequence is [0, 1, 2, ..., num_chunks * chunk_size - 1]
+    """
+    # Create sequential tokens for testing
+    return torch.arange(0, num_chunks * chunk_size, dtype=torch.long, device="cuda")
+
+
+def generate_kv_cache_paged_list_tensors(
+    num_blocks, device, block_size=16, dtype=torch.bfloat16
+):
+    """
+    Instead of Tuple[Tuple[Tensor, Tensor]], return List[Tensor]
+    where KV are in the same tensor
+    """
+    ret = []
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    shape = [2, num_blocks, block_size, num_heads, head_size]
+
+    for i in range(num_layers):
+        # Use a fixed seed for reproducibility between sender and receiver
+        torch.manual_seed(42 + i)
+        kv = torch.rand(shape, dtype=dtype, device=device)
+        ret.append(kv)
+
+    return ret
+
+
+def fill_kv_cache_with_pattern(kv_cache, slot_mapping, pattern_value=0.99):
+    """Fill the KV cache at the specified slot mappings with
+    a recognizable pattern
+    """
+    print(slot_mapping.shape)
+    for layer_idx, layer_tensor in tqdm(enumerate(kv_cache), total=len(kv_cache)):
+        # Fill both K and V with the pattern value
+        num_blocks = layer_tensor.shape[1]
+        block_size = layer_tensor.shape[2]
+        new_shape = (2, num_blocks * block_size, 8, 128)
+        layer_tensor.reshape(new_shape)[:, slot_mapping, :, :] = pattern_value
+
+    return kv_cache
+
+
+def verify_kv_cache_pattern(kv_cache, slot_mapping, pattern_value=0.99, tolerance=0.01):
+    """Verify that the KV cache contains the expected pattern at the
+    specified slot mappings
+    """
+    logger.info(f"Verifying KV cache pattern {pattern_value}")
+    all_correct = True
+    for layer_idx, layer_tensor in tqdm(enumerate(kv_cache), total=len(kv_cache)):
+        num_blocks = layer_tensor.shape[1]
+        block_size = layer_tensor.shape[2]
+        new_shape = (2, num_blocks * block_size, 8, 128)
+        actual_values = layer_tensor.reshape(new_shape)[:, slot_mapping, :, :]
+        # Check if the mean is close to the pattern value
+        mean_value = actual_values.mean().item()
+        if abs(mean_value - pattern_value) > tolerance:
+            logger.error(
+                f"Pattern mismatch at layer {layer_idx}: "
+                f"expected mean ~{pattern_value}, got {mean_value}"
+            )
+            all_correct = False
+
+    return all_correct
+
+
+def calculate_throughput(total_bytes: int, elapsed_time: float) -> float:
+    """Calculate throughput in GB/s"""
+    if elapsed_time == 0:
+        return float("inf")
+    gb = total_bytes / (1024 * 1024 * 1024)
+    return gb / elapsed_time
+
+
+def create_config(role: str, host: str, port: int) -> LMCacheEngineConfig:
+    """Create a configuration for the LMCacheEngine with Nixl backend."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=False,  # Nixl requires local_cpu=False
+        max_local_cpu_size=0,  # Nixl requires max_local_cpu_size=0
+        local_disk=None,  # Nixl requires local_disk=None
+        max_local_disk_size=0,  # Nixl requires max_local_disk_size=0
+        remote_url=None,  # Nixl requires remote_url=None
+        remote_serde=None,  # Nixl requires remote_serde=None
+        save_decode_cache=False,  # Nixl requires save_decode_cache=False
+        enable_p2p=False,  # Nixl requires enable_p2p=False
+        enable_nixl=True,  # Enable Nixl
+        nixl_role=role,  # 'sender' or 'receiver'
+        nixl_receiver_host=host,
+        nixl_receiver_port=port,
+        nixl_buffer_size=2**30,  # 1GB
+        nixl_buffer_device="cuda",
+    )
+    return config
+
+
+def create_metadata() -> LMCacheMetadata:
+    """Create metadata for the LMCacheEngine."""
+    # Define KV shape: (num_layers, 2, chunk_size, num_heads, head_dim)
+    chunk_size = 256
+    num_layers = 32
+    num_heads = 32
+    head_dim = 128
+    kv_shape = (num_layers, 2, chunk_size, num_heads, head_dim)
+
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+    )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Test LMCacheEngine with Nixl backend")
+    parser.add_argument(
+        "--role",
+        type=str,
+        required=True,
+        choices=["sender", "receiver"],
+        help="Role of this instance (sender or receiver)",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="localhost",
+        help="Host name/IP for connection",
+    )
+    parser.add_argument(
+        "--port", type=int, default=5555, help="Port number for connection"
+    )
+    parser.add_argument(
+        "--num-chunks", type=int, default=10, help="Number of chunks to send"
+    )
+    parser.add_argument(
+        "--num-rounds",
+        type=int,
+        default=1,
+        help="Number of times to run the experiment",
+    )
+    args = parser.parse_args()
+
+    # Set fixed random seed for reproducibility
+    random.seed(42)
+    torch.manual_seed(42)
+    np.random.seed(42)
+
+    # Create configuration and metadata
+    config = create_config(args.role, args.host, args.port)
+    metadata = create_metadata()
+
+    # Parameters for paged KV cache
+    num_blocks = 10000
+    block_size = 16
+    dtype = torch.bfloat16
+    device = "cuda"
+
+    max_chunks = num_blocks * block_size // config.chunk_size
+    assert args.num_chunks <= max_chunks, f"Number of chunks must be <= {max_chunks}"
+
+    # Create the VLLMPagedMemGPUConnectorV2
+    hidden_dim = 1024
+    num_layers = 32
+    gpu_connector = VLLMPagedMemGPUConnectorV2(hidden_dim, num_layers)
+
+    # Calculate the expected total size of data
+    kv_shape = gpu_connector.get_shape(config.chunk_size)
+    element_size = torch.tensor([], dtype=metadata.kv_dtype).element_size()
+    chunk_size_bytes = torch.prod(torch.tensor(kv_shape)).item() * element_size
+    total_size = chunk_size_bytes * args.num_chunks
+
+    # Create the LMCacheEngine (will be reused across rounds)
+    engine = LMCacheEngineBuilder.get_or_create(
+        "test_engine",
+        config,
+        metadata,
+        gpu_connector,
+        mock_up_broadcast_fn,
+        mock_up_broadcast_object_fn,
+    )
+
+    # Generate or create buffers that will be reused across rounds
+    tokens = generate_test_tokens(args.num_chunks, config.chunk_size)
+    slot_indices = list(range(0, num_blocks * block_size))
+    random.shuffle(slot_indices)
+    slot_mapping = torch.tensor(slot_indices[: len(tokens)], device=device)
+
+    if args.role == "sender":
+        # Generate KV cache once and reuse
+        kv_cache = generate_kv_cache_paged_list_tensors(
+            num_blocks, device, block_size, dtype
+        )
+        pattern_value = 0.99
+        kv_cache = fill_kv_cache_with_pattern(kv_cache, slot_mapping, pattern_value)
+    else:  # receiver
+        # Create retrieval buffer once and reuse
+        retrieved_cache = generate_kv_cache_paged_list_tensors(
+            num_blocks, device, block_size, dtype
+        )
+
+    # Track statistics across rounds
+    throughputs = []
+
+    for round_num in range(args.num_rounds):
+        logger.info(f"\nStarting round {round_num + 1}/{args.num_rounds}")
+
+        if args.role == "sender":
+            # Wait a bit for the receiver to set up
+            time.sleep(2)
+
+            logger.info(f"Storing {len(tokens)} tokens ({args.num_chunks} chunks)...")
+            start_time = time.time()
+            engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+
+            end_time = time.time()
+            elapsed_time = end_time - start_time
+            logger.info(f"Stored {len(tokens)} tokens in {elapsed_time:.6f} seconds")
+            throughput = calculate_throughput(total_size, elapsed_time)
+            logger.info(f"Throughput: {throughput:.2f} GB/s")
+            throughputs.append(throughput)
+
+        else:  # receiver
+            # Wait for data to be received
+            logger.info("Waiting to receive data...")
+
+            # Poll until we receive all chunks or timeout
+            received_count = 0
+            start_time = time.time()
+            timeout = 60  # seconds
+
+            while received_count < args.num_chunks:
+                # Check how many chunks we've received by looking up tokens
+                received_count = engine.lookup(tokens) // config.chunk_size
+
+                if received_count == args.num_chunks:
+                    break
+
+                # Check for timeout
+                if time.time() - start_time > timeout:
+                    logger.error(
+                        "Timed out waiting for data. Received only "
+                        f"{received_count}/{args.num_chunks} chunks."
+                    )
+                    break
+
+                time.sleep(0.1)  # Small sleep to avoid busy waiting
+
+            if received_count == args.num_chunks:
+                logger.info(f"Received all {args.num_chunks} chunks")
+
+                # Retrieve and verify the data
+                logger.info("Retrieving and verifying data...")
+                start_time = time.time()
+
+                # Retrieve tokens from the cache engine
+                ret_mask = engine.retrieve(
+                    tokens, kvcaches=retrieved_cache, slot_mapping=slot_mapping
+                )
+
+                end_time = time.time()
+                elapsed_time = end_time - start_time
+
+                # Check if all tokens were retrieved
+                retrieved_tokens = torch.sum(ret_mask).item()
+                if retrieved_tokens == len(tokens):
+                    logger.info(
+                        f"Successfully retrieved all {retrieved_tokens} tokens "
+                        f"in {elapsed_time:.6f} seconds"
+                    )
+                    throughput = calculate_throughput(total_size, elapsed_time)
+                    logger.info(f"Retrieval throughput: {throughput:.2f} GB/s")
+
+                    # Verify the data by checking if the retrieved KV cache
+                    # has the expected pattern
+                    pattern_value = 0.99  # Same value used by sender
+                    if verify_kv_cache_pattern(
+                        retrieved_cache, slot_mapping, pattern_value
+                    ):
+                        logger.info(
+                            "✅ Data verification successful - pattern matches!"
+                        )
+                    else:
+                        logger.error(
+                            "❌ Data verification failed - pattern doesn't match!"
+                        )
+                else:
+                    logger.error(
+                        "Failed to retrieve all tokens. Retrieved "
+                        f"{retrieved_tokens}/{len(tokens)} tokens."
+                    )
+            else:
+                logger.error(f"Only received {received_count}/{args.num_chunks} chunks")
+
+        # Wait between rounds
+        time.sleep(2)
+
+    # Print summary statistics
+    if throughputs:
+        mean_throughput = sum(throughputs) / len(throughputs)
+        std_throughput = np.std(throughputs) if len(throughputs) > 1 else 0
+        logger.info("\nSummary Statistics:")
+        logger.info(
+            f"Mean throughput: {mean_throughput:.2f} ± {std_throughput:.2f} GB/s"
+        )
+        logger.info(f"Min throughput: {min(throughputs):.2f} GB/s")
+        logger.info(f"Max throughput: {max(throughputs):.2f} GB/s")
+
+    # Cleanup at the very end
+    LMCacheEngineBuilder.destroy("test_engine")
+    logger.info("All rounds completed")
diff --git a/tests/disagg/test_nixl_channel.py b/tests/disagg/test_nixl_channel.py
new file mode 100644
index 0000000..72846df
--- /dev/null
+++ b/tests/disagg/test_nixl_channel.py
@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Tuple
+import argparse
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.transfer_channel.nixl_channel import NixlChannel
+from lmcache.v1.transfer_channel.transfer_utils import get_correct_device
+
+pytest.importorskip("nixl", reason="nixl package is required for nixl tests")
+
+logger = init_logger(__name__)
+
+
+def generate_test_data(
+    num_objs: int, shape: torch.Size, dtype: torch.dtype = torch.bfloat16
+) -> Tuple[List[CacheEngineKey], List[MemoryObj]]:
+    keys = []
+    objs = []
+    allocator = AdHocMemoryAllocator(
+        device="cuda",  # Assuming we are using CUDA for the test
+    )
+    for i in range(num_objs):
+        keys.append(
+            CacheEngineKey(
+                model_name="test_model",
+                world_size=1,
+                worker_id=0,
+                chunk_hash=i,
+                dtype=dtype,
+            )
+        )
+        obj = allocator.allocate(shape, dtype, fmt=MemoryFormat.KV_2LTD)
+        obj.tensor.fill_(i + 1)  # Fill with some test data, e.g., the index
+        objs.append(obj)
+    return keys, objs
+
+
+def calculate_throughput(total_bytes: int, elapsed_time: float) -> float:
+    """Calculate throughput in GB/s"""
+    if elapsed_time == 0:
+        return float("inf")
+    gb = total_bytes / (1024 * 1024 * 1024)
+    return gb / elapsed_time
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Test NixlChannel with sender/receiver roles"
+    )
+    parser.add_argument(
+        "--role",
+        type=str,
+        required=True,
+        choices=["sender", "receiver"],
+        help="Role of this instance (sender or receiver)",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="localhost",
+        help="Host name/IP for connection",
+    )
+    parser.add_argument(
+        "--port", type=int, default=5555, help="Port number for connection"
+    )
+    parser.add_argument(
+        "--num-objs", type=int, default=100, help="Number of objects to send"
+    )
+    parser.add_argument(
+        "--num-rounds",
+        type=int,
+        default=1,
+        help="Number of rounds to run the experiment",
+    )
+    args = parser.parse_args()
+
+    # Generate test data
+    keys, objs = generate_test_data(args.num_objs, torch.Size([32, 2, 256, 1024]))
+    total_size = sum(obj.get_size() for obj in objs)
+    logger.info(
+        f"Generated {len(objs)} objects with total size "
+        f"{total_size / (1024 * 1024):.2f} MB"
+    )
+
+    # Common configuration
+    buffer_size = 2**32  # 4GB
+    buffer_device = get_correct_device("cuda", 0)  # Use first GPU
+
+    # Get buffer pointer from first object
+    buffer_ptr = objs[0].metadata.address
+    align_bytes = 4096  # Standard page size
+
+    # Create the NixlChannel
+    channel = NixlChannel(
+        async_mode=False,
+        role=args.role,
+        buffer_ptr=buffer_ptr,
+        buffer_size=buffer_size,
+        align_bytes=align_bytes,
+        tp_rank=0,
+        peer_init_url=f"tcp://{args.host}:{args.port}",
+        backends=["UCX"],
+    )
+
+    if args.role == "sender":
+        throughputs = []
+        for i in range(args.num_rounds):
+            logger.info(f"Round {i + 1}/{args.num_rounds}")
+            start_time = time.time()
+            num_sent = channel.batched_send(objs)
+            end_time = time.time()
+            elapsed_time = end_time - start_time
+            throughput = calculate_throughput(total_size, elapsed_time)
+            logger.info(f"Sent {num_sent} objects in {elapsed_time:.6f} seconds")
+            logger.info(f"Throughput: {throughput:.2f} GB/s")
+            throughputs.append(throughput)
+        avg_throughput = sum(throughputs) / len(throughputs)
+        logger.info(f"Average throughput: {avg_throughput:.2f} GB/s")
+    else:  # receiver
+        for i in range(args.num_rounds):
+            logger.info(f"Round {i + 1}/{args.num_rounds}")
+            start_time = time.time()
+            num_received = channel.batched_recv(objs)
+            end_time = time.time()
+            elapsed_time = end_time - start_time
+            throughput = calculate_throughput(total_size, elapsed_time)
+            logger.info(
+                f"Received {num_received} objects in {elapsed_time:.6f} seconds"
+            )
+            logger.info(f"Throughput: {throughput:.2f} GB/s")
+
+            # Verify data
+            for i, (received_obj, original_obj) in enumerate(
+                zip(objs, objs, strict=False)
+            ):
+                assert received_obj.tensor is not None, (
+                    f"Received tensor is None at index {i}"
+                )
+                assert original_obj.tensor is not None, (
+                    f"Original tensor is None at index {i}"
+                )
+                assert torch.allclose(received_obj.tensor, original_obj.tensor), (
+                    f"Data mismatch at index {i}: "
+                    f"received {received_obj.tensor.mean().item()}"
+                    f" but expected {original_obj.tensor.mean().item()}"
+                )
+
+    # Wait a bit before closing
+    time.sleep(2)
+    channel.close()
+    logger.info("Test completed")
diff --git a/tests/disagg/test_nixl_storage_backend.py b/tests/disagg/test_nixl_storage_backend.py
new file mode 100644
index 0000000..346646e
--- /dev/null
+++ b/tests/disagg/test_nixl_storage_backend.py
@@ -0,0 +1,523 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Tuple
+import argparse
+import asyncio
+import os
+import tempfile
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("nixl", reason="nixl package is required for nixl tests")
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.nixl_storage_backend import (
+    NixlStorageBackend,
+    NixlStorageConfig,
+)
+from lmcache.v1.transfer_channel.transfer_utils import get_correct_device
+
+logger = init_logger(__name__)
+
+
+def generate_test_data(
+    num_objs: int, shape: torch.Size, dtype: torch.dtype = torch.bfloat16
+) -> Tuple[List[CacheEngineKey], List[MemoryObj]]:
+    keys = []
+    objs = []
+    allocator = AdHocMemoryAllocator(
+        device="cuda" if torch.cuda.is_available() else "cpu",
+    )
+    for i in range(num_objs):
+        keys.append(
+            CacheEngineKey(
+                model_name="test_model",
+                world_size=1,
+                worker_id=0,
+                chunk_hash=i,
+                dtype=dtype,
+            )
+        )
+        obj = allocator.allocate(shape, dtype, fmt=MemoryFormat.KV_2LTD)
+        obj.tensor.fill_((i + 1) / num_objs)  # Fill with some test data
+        objs.append(obj)
+    return keys, objs
+
+
+def calculate_throughput(total_bytes: int, elapsed_time: float) -> float:
+    """Calculate throughput in GB/s"""
+    if elapsed_time == 0:
+        return float("inf")
+    gb = total_bytes / (1024 * 1024 * 1024)
+    return gb / elapsed_time
+
+
+def create_test_config(
+    buffer_device: str = "cuda" if torch.cuda.is_available() else "cpu",
+    backend: str = "GDS_MT" if torch.cuda.is_available() else "POSIX",
+) -> LMCacheEngineConfig:
+    """Create a test configuration for NixlStorageBackend"""
+    config = LMCacheEngineConfig()
+    config.nixl_buffer_size = 2**32  # 4GB
+    config.nixl_buffer_device = buffer_device
+    config.extra_config = {
+        "enable_nixl_storage": True,
+        "nixl_backend": backend,
+        "nixl_pool_size": 10,
+        "nixl_path": tempfile.mkdtemp(),  # Create a temporary directory for testing
+    }
+    return config
+
+
+def create_test_metadata() -> LMCacheMetadata:
+    """Create test metadata for NixlStorageBackend"""
+    return LMCacheMetadata(
+        model_name="test_model",
+        worker_id=0,
+        local_world_size=1,
+        local_worker_id=0,
+        world_size=1,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            32,
+            2,
+            256,
+            1024,
+            128,
+        ),  # (num_layer, 2, chunk_size, num_kv_head, head_size)
+    )
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_storage_config():
+    """Test NixlStorageConfig creation and validation"""
+    config = create_test_config()
+    metadata = create_test_metadata()
+
+    nixl_config = NixlStorageConfig.from_cache_engine_config(config, metadata)
+    if config.nixl_buffer_device == "cpu":
+        # CPU mode shares LocalCPUBackend's pool (sized by max_local_cpu_size),
+        # so the NIXL buffer_size is left at 0.
+        assert nixl_config.buffer_size == 0
+    else:
+        assert nixl_config.buffer_size == config.nixl_buffer_size
+    # buffer_device is normalized to include the worker's device id
+    # (e.g. "cuda" -> "cuda:0"); "cpu" stays "cpu".
+    assert nixl_config.buffer_device == get_correct_device(
+        config.nixl_buffer_device, metadata.worker_id
+    )
+    assert nixl_config.backend == config.extra_config["nixl_backend"]
+    assert nixl_config.pool_size == config.extra_config["nixl_pool_size"]
+    assert nixl_config.path == config.extra_config["nixl_path"]
+
+    # Test validation
+    assert NixlStorageConfig.validate_nixl_backend("GDS", "cuda")
+    assert NixlStorageConfig.validate_nixl_backend("GDS", "cpu")
+    assert NixlStorageConfig.validate_nixl_backend("GDS_MT", "cuda")
+    assert NixlStorageConfig.validate_nixl_backend("GDS_MT", "cpu")
+    assert NixlStorageConfig.validate_nixl_backend("POSIX", "cpu")
+    assert not NixlStorageConfig.validate_nixl_backend("POSIX", "cuda")
+    assert not NixlStorageConfig.validate_nixl_backend("INVALID", "cpu")
+
+
+def _make_obj_config(
+    extra_overrides: dict | None = None,
+) -> LMCacheEngineConfig:
+    """Create a minimal OBJ-backend config for endpoint-list tests."""
+    config = LMCacheEngineConfig()
+    # CPU mode: nixl_buffer_size is rejected; the pool comes from LocalCPUBackend.
+    config.nixl_buffer_device = "cpu"
+    config.extra_config = {
+        "enable_nixl_storage": True,
+        "nixl_backend": "OBJ",
+        "nixl_pool_size": 0,
+        "nixl_path": tempfile.mkdtemp(),
+    }
+    if extra_overrides:
+        config.extra_config.update(extra_overrides)
+    return config
+
+
+def _make_metadata(local_worker_id: int = 0) -> LMCacheMetadata:
+    """Create test metadata with a configurable local_worker_id."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        worker_id=local_worker_id,
+        local_world_size=1,
+        local_worker_id=local_worker_id,
+        world_size=1,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(32, 2, 256, 1024, 128),
+    )
+
+
+@pytest.mark.no_shared_allocator
+def test_endpoint_list_round_robin():
+    """nixl_endpoint_list should assign endpoints to workers round-robin."""
+    endpoints = [
+        "https://node-0:9021",
+        "https://node-1:9021",
+        "https://node-2:9021",
+    ]
+    config = _make_obj_config({"nixl_endpoint_list": endpoints})
+
+    for local_worker_id in range(6):
+        metadata = _make_metadata(local_worker_id=local_worker_id)
+        nixl_config = NixlStorageConfig.from_cache_engine_config(config, metadata)
+        expected = endpoints[local_worker_id % len(endpoints)]
+        assert nixl_config.backend_params["endpoint_override"] == expected
+
+
+@pytest.mark.no_shared_allocator
+def test_endpoint_list_overrides_endpoint_override():
+    """nixl_endpoint_list takes precedence over backend_params endpoint_override."""
+    endpoints = ["https://node-0:9021"]
+    config = _make_obj_config(
+        {
+            "nixl_endpoint_list": endpoints,
+            "nixl_backend_params": {
+                "endpoint_override": "https://should-be-ignored:9021",
+                "access_key": "key",
+            },
+        }
+    )
+    metadata = _make_metadata(local_worker_id=0)
+
+    nixl_config = NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+    assert nixl_config.backend_params["endpoint_override"] == endpoints[0]
+    # other params must be preserved
+    assert nixl_config.backend_params["access_key"] == "key"
+
+
+@pytest.mark.no_shared_allocator
+def test_endpoint_list_does_not_mutate_original_config():
+    """Setting nixl_endpoint_list must not mutate the original backend_params dict."""
+    original_params = {"access_key": "key", "secret_key": "secret"}
+    config = _make_obj_config(
+        {
+            "nixl_endpoint_list": ["https://node-0:9021"],
+            "nixl_backend_params": original_params,
+        }
+    )
+    metadata = _make_metadata(local_worker_id=0)
+
+    NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+    assert "endpoint_override" not in original_params
+
+
+@pytest.mark.no_shared_allocator
+def test_endpoint_list_empty_raises():
+    """nixl_endpoint_list=[] should raise ValueError before any nixl ops."""
+    config = _make_obj_config({"nixl_endpoint_list": []})
+    metadata = _make_metadata(local_worker_id=0)
+
+    with pytest.raises(ValueError, match="nixl_endpoint_list is set but empty"):
+        NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+
+@pytest.mark.no_shared_allocator
+def test_no_endpoint_list_leaves_backend_params_unchanged():
+    """When nixl_endpoint_list is absent, endpoint_override must not be injected."""
+    config = _make_obj_config()  # no nixl_endpoint_list key
+    metadata = _make_metadata(local_worker_id=0)
+
+    nixl_config = NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+    assert "endpoint_override" not in nixl_config.backend_params
+
+
+@pytest.mark.no_shared_allocator
+def test_endpoint_list_malformed_url_raises():
+    """A non-http(s) entry in nixl_endpoint_list should raise ValueError."""
+    config = _make_obj_config({"nixl_endpoint_list": ["htps://typo.example.com"]})
+    metadata = _make_metadata(local_worker_id=0)
+
+    with pytest.raises(ValueError, match="is not a valid URL"):
+        NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Requires CUDA")
+def test_nixl_storage_backend_basic():
+    """Test basic NixlStorageBackend operations"""
+    config = create_test_config()
+    metadata = create_test_metadata()
+
+    thread_loop = None
+    thread = None
+    backend = None
+    try:
+        thread_loop = asyncio.new_event_loop()
+        thread = threading.Thread(target=thread_loop.run_forever)
+        thread.start()
+
+        backend = NixlStorageBackend.CreateNixlStorageBackend(
+            config=config,
+            loop=thread_loop,
+            metadata=metadata,
+        )
+
+        # Test allocation
+        shape = torch.Size([32, 2, 256, 1024])
+        dtype = torch.bfloat16
+        obj = backend.allocate(shape, dtype)
+        assert obj is not None
+        assert obj.tensor is not None
+        assert obj.tensor.shape == shape
+        assert obj.tensor.dtype == dtype
+
+        # Test batched allocation
+        batch_size = 5
+        objs = backend.batched_allocate(shape, dtype, batch_size)
+        assert objs is not None
+        assert len(objs) == batch_size
+        for obj in objs:
+            assert obj.tensor is not None
+            assert obj.tensor.shape == shape
+            assert obj.tensor.dtype == dtype
+
+    except Exception:
+        raise
+    finally:
+        if backend:
+            backend.close()
+        if thread_loop and thread_loop.is_running():
+            thread_loop.call_soon_threadsafe(thread_loop.stop)
+        if thread and thread.is_alive():
+            thread.join()
+        # Cleanup temporary directory
+        if os.path.exists(config.extra_config["nixl_path"]):
+            os.rmdir(config.extra_config["nixl_path"])
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Requires CUDA")
+def test_nixl_storage_backend_put_get():
+    """Test put and get operations in NixlStorageBackend"""
+    config = create_test_config()
+    metadata = create_test_metadata()
+
+    thread_loop = None
+    thread = None
+    backend = None
+    try:
+        thread_loop = asyncio.new_event_loop()
+        thread = threading.Thread(target=thread_loop.run_forever)
+        thread.start()
+
+        backend = NixlStorageBackend.CreateNixlStorageBackend(
+            config=config,
+            loop=thread_loop,
+            metadata=metadata,
+        )
+
+        # Generate test data
+        keys, objs = generate_test_data(10, torch.Size([32, 2, 256, 1024]))
+
+        # Test contains before put
+        for key in keys:
+            assert not backend.contains(key)
+            assert not backend.exists_in_put_tasks(key)
+
+        # Test put
+        backend.batched_submit_put_task(keys, objs)
+
+        # Test get
+        for key, original_obj in zip(keys, objs, strict=False):
+            assert backend.contains(key)
+            retrieved_obj = backend.get_blocking(key)
+            assert retrieved_obj is not None
+            assert retrieved_obj.tensor is not None
+            assert torch.equal(retrieved_obj.tensor, original_obj.tensor)
+
+        # Test batched get
+        retrieved_objs = asyncio.run(
+            backend.batched_get_non_blocking(lookup_id="test", keys=keys)
+        )
+        assert len(retrieved_objs) == len(objs)
+        for retrieved_obj, original_obj in zip(retrieved_objs, objs, strict=False):
+            assert retrieved_obj is not None
+            assert retrieved_obj.tensor is not None
+            assert torch.equal(retrieved_obj.tensor, original_obj.tensor)
+
+        # Test remove
+        for key in keys:
+            backend.remove(key)
+            assert not backend.contains(key)
+
+    except Exception:
+        raise
+    finally:
+        if backend:
+            backend.close()
+        if thread_loop and thread_loop.is_running():
+            thread_loop.call_soon_threadsafe(thread_loop.stop)
+        if thread and thread.is_alive():
+            thread.join()
+        # Cleanup temporary directory
+        if os.path.exists(config.extra_config["nixl_path"]):
+            os.rmdir(config.extra_config["nixl_path"])
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Requires CUDA")
+def test_nixl_storage_backend_different_backends():
+    """Test NixlStorageBackend with different backend types"""
+    backends = (
+        [
+            ("GDS_MT", "cuda"),
+            ("GDS", "cuda"),
+            ("GDS_MT", "cpu"),
+            ("GDS", "cpu"),
+            ("POSIX", "cpu"),
+        ]
+        if torch.cuda.is_available()
+        else [
+            ("GDS_MT", "cpu"),
+            ("GDS", "cpu"),
+            ("POSIX", "cpu"),
+        ]
+    )
+
+    for backend_type, device in backends:
+        config = create_test_config(buffer_device=device, backend=backend_type)
+        metadata = create_test_metadata()
+
+        thread_loop = None
+        thread = None
+        backend = None
+        try:
+            thread_loop = asyncio.new_event_loop()
+            thread = threading.Thread(target=thread_loop.run_forever)
+            thread.start()
+
+            backend = NixlStorageBackend.CreateNixlStorageBackend(
+                config=config,
+                loop=thread_loop,
+                metadata=metadata,
+            )
+
+            # Basic allocation test
+            obj = backend.allocate(torch.Size([32, 2, 256, 1024]), torch.bfloat16)
+            assert obj is not None
+            assert obj.tensor is not None
+
+        except Exception:
+            raise
+        finally:
+            if backend:
+                backend.close()
+            if thread_loop and thread_loop.is_running():
+                thread_loop.call_soon_threadsafe(thread_loop.stop)
+            if thread and thread.is_alive():
+                thread.join()
+            # Cleanup temporary directory
+            if os.path.exists(config.extra_config["nixl_path"]):
+                os.rmdir(config.extra_config["nixl_path"])
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Test NixlStorageBackend with different configurations"
+    )
+    parser.add_argument(
+        "--backend",
+        type=str,
+        default="GDS_MT",
+        choices=["GDS_MT", "GDS", "POSIX"],
+        help="NIXL backend type to use",
+    )
+    parser.add_argument(
+        "--device",
+        type=str,
+        default="cuda",
+        choices=["cuda", "cpu"],
+        help="Device to use for buffer",
+    )
+    parser.add_argument(
+        "--num-objs",
+        type=int,
+        default=100,
+        help="Number of objects to test with",
+    )
+    args = parser.parse_args()
+
+    # Create config and metadata
+    config = create_test_config(buffer_device=args.device, backend=args.backend)
+    metadata = create_test_metadata()
+
+    thread_loop = None
+    thread = None
+    backend = None
+    try:
+        thread_loop = asyncio.new_event_loop()
+        thread = threading.Thread(target=thread_loop.run_forever)
+        thread.start()
+
+        # Create backend
+        backend = NixlStorageBackend.CreateNixlStorageBackend(
+            config=config,
+            loop=thread_loop,
+            metadata=metadata,
+        )
+
+        # Generate and test with data
+        keys, objs = generate_test_data(args.num_objs, torch.Size([32, 2, 256, 1024]))
+        total_size = sum(obj.get_size() for obj in objs)
+        logger.info(
+            "Generated %d objects with total size %.2f MB",
+            len(objs),
+            total_size / (1024 * 1024),
+        )
+
+        # Test put performance
+        start_time = time.time()
+        backend.batched_submit_put_task(keys, objs)
+        end_time = time.time()
+        elapsed_time = end_time - start_time
+        throughput = calculate_throughput(total_size, elapsed_time)
+        logger.info("Put throughput: %.2f GB/s", throughput)
+
+        # Test get performance
+        start_time = time.time()
+        retrieved_objs = asyncio.run(
+            backend.batched_get_non_blocking(lookup_id="test", keys=keys)
+        )
+        end_time = time.time()
+        elapsed_time = end_time - start_time
+        throughput = calculate_throughput(total_size, elapsed_time)
+        logger.info("Get throughput: %.2f GB/s", throughput)
+
+        # Verify data
+        for retrieved_obj, original_obj in zip(retrieved_objs, objs, strict=False):
+            assert torch.equal(retrieved_obj.tensor, original_obj.tensor)
+
+        logger.info("All tests passed successfully!")
+
+    except Exception:
+        raise
+    finally:
+        if backend:
+            backend.close()
+        if thread_loop and thread_loop.is_running():
+            thread_loop.call_soon_threadsafe(thread_loop.stop)
+        if thread and thread.is_alive():
+            thread.join()
+        # Cleanup temporary directory
+        if os.path.exists(config.extra_config["nixl_path"]):
+            os.rmdir(config.extra_config["nixl_path"])
diff --git a/tests/lmcache_frontend/__init__.py b/tests/lmcache_frontend/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/lmcache_frontend/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/lmcache_frontend/lmcache_mp_plugin/__init__.py b/tests/lmcache_frontend/lmcache_mp_plugin/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/lmcache_frontend/lmcache_mp_plugin/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/lmcache_frontend/lmcache_mp_plugin/test_lmcache_mp_frontend_plugin.py b/tests/lmcache_frontend/lmcache_mp_plugin/test_lmcache_mp_frontend_plugin.py
new file mode 100644
index 0000000..640eb75
--- /dev/null
+++ b/tests/lmcache_frontend/lmcache_mp_plugin/test_lmcache_mp_frontend_plugin.py
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the MP frontend plugin's argv builder.
+
+These tests exercise the pure ``build_argv`` function to make sure
+the aggregated ``LMCACHE_RUNTIME_PLUGIN_CONFIG`` payload is translated
+into the right CLI argv for ``lmcache.lmcache_frontend.app.main()``.
+"""
+
+# Standard
+import json
+
+# First Party
+from lmcache.lmcache_frontend.lmcache_mp_plugin.lmcache_mp_frontend_plugin import (
+    build_argv,
+)
+
+
+def _find_arg(argv: list, name: str) -> str | None:
+    """Return the value following ``name`` in ``argv``, or ``None``."""
+    if name not in argv:
+        return None
+    idx = argv.index(name)
+    if idx + 1 >= len(argv):
+        return None
+    return argv[idx + 1]
+
+
+def test_build_argv_with_tcp_http_config():
+    config = {
+        "http_frontend_config": {
+            "http_host": "192.168.1.5",
+            "http_port": 8085,
+            "http_socket_path": None,
+        },
+        "runtime_plugin_extra_config": {
+            "plugin.frontend.heartbeat-url": "http://disc.example/heartbeat",
+            "plugin.frontend.heartbeat-interval": 30,
+            "unrelated.key": "ignored",
+        },
+    }
+
+    argv = build_argv(config, prog="plugin")
+
+    assert argv[0] == "plugin"
+    assert "--no-http" in argv
+    assert _find_arg(argv, "--heartbeat-url") == "http://disc.example/heartbeat"
+    assert _find_arg(argv, "--heartbeat-interval") == "30"
+    # unrelated keys must not leak through
+    assert "--unrelated-key" not in argv
+
+    # --port is forwarded as the connectable lmcache HTTP port
+    assert _find_arg(argv, "--port") == "8085"
+
+    nodes_json = _find_arg(argv, "--nodes")
+    assert nodes_json is not None
+    nodes = json.loads(nodes_json)
+    assert nodes == [
+        {"name": "lmcache_server", "host": "192.168.1.5", "port": "8085"},
+    ]
+
+
+def test_build_argv_rewrites_wildcard_host():
+    config = {
+        "http_frontend_config": {
+            "http_host": "0.0.0.0",
+            "http_port": 9000,
+        },
+    }
+    argv = build_argv(config)
+    nodes = json.loads(_find_arg(argv, "--nodes"))
+    assert nodes[0]["host"] == "localhost"
+    assert nodes[0]["port"] == "9000"
+
+
+def test_build_argv_prefers_socket_path_when_set():
+    config = {
+        "http_frontend_config": {
+            "http_host": "0.0.0.0",
+            "http_port": 9000,
+            "http_socket_path": "/tmp/lmc.sock",
+        },
+    }
+    argv = build_argv(config)
+    nodes = json.loads(_find_arg(argv, "--nodes"))
+    assert nodes == [
+        {"name": "lmcache_server", "host": "localhost", "port": "/tmp/lmc.sock"},
+    ]
+
+
+def test_build_argv_accepts_http_config_alias():
+    """``MPRuntimePluginLauncher`` passes the http config under the key
+    ``http_config`` (see ``http_server.py``). Ensure we accept both
+    ``http_config`` and ``http_frontend_config`` at the top level.
+    """
+    config = {
+        "http_config": {
+            "http_host": "10.0.0.1",
+            "http_port": 7000,
+        },
+    }
+    argv = build_argv(config)
+    nodes = json.loads(_find_arg(argv, "--nodes"))
+    assert nodes[0]["host"] == "10.0.0.1"
+    assert nodes[0]["port"] == "7000"
+
+
+def test_build_argv_with_empty_config_has_defaults():
+    argv = build_argv({})
+    assert "--no-http" in argv
+    nodes = json.loads(_find_arg(argv, "--nodes"))
+    # falls back to localhost:8080 when http config is missing
+    assert nodes == [
+        {"name": "lmcache_server", "host": "localhost", "port": "8080"},
+    ]
+    # no --port should be appended when http_port is missing
+    assert _find_arg(argv, "--port") is None
diff --git a/tests/lmcache_frontend/test_heartbeat.py b/tests/lmcache_frontend/test_heartbeat.py
new file mode 100644
index 0000000..11b9e57
--- /dev/null
+++ b/tests/lmcache_frontend/test_heartbeat.py
@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for ``HeartbeatService``.
+
+These tests mock ``httpx.AsyncClient`` so the real network is never
+touched, and verify that ``send_heartbeat`` builds the expected query
+parameters from the configured app host/port and target nodes.
+"""
+
+# Standard
+import asyncio
+import json
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.lmcache_frontend.heartbeat import HeartbeatService
+
+
+class _FakeResponse:
+    def __init__(self, status_code: int = 200, content: bytes = b""):
+        self.status_code = status_code
+        self.content = content
+
+    def raise_for_status(self):  # noqa: D401 - match httpx API
+        if self.status_code >= 400:
+            raise RuntimeError("boom")
+
+
+class _FakeAsyncClient:
+    """Captures the last ``get`` call for later assertions."""
+
+    last_url: str | None = None
+    last_params: dict | None = None
+    version_response: _FakeResponse = _FakeResponse(200, b"")
+    heartbeat_response: _FakeResponse = _FakeResponse(200, b"ok")
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return False
+
+    async def get(self, url, params=None):
+        type(self).last_url = url
+        type(self).last_params = params
+        # Distinguish version probe vs heartbeat post
+        if url.endswith("/version"):
+            return type(self).version_response
+        return type(self).heartbeat_response
+
+
+@pytest.fixture
+def patched_httpx(monkeypatch):
+    """Patch ``httpx.AsyncClient`` used inside ``heartbeat`` module."""
+    # First Party
+    from lmcache.lmcache_frontend import heartbeat as hb_mod
+
+    _FakeAsyncClient.last_url = None
+    _FakeAsyncClient.last_params = None
+    _FakeAsyncClient.version_response = _FakeResponse(200, b"")
+    _FakeAsyncClient.heartbeat_response = _FakeResponse(200, b"ok")
+    monkeypatch.setattr(hb_mod.httpx, "AsyncClient", _FakeAsyncClient)
+    # Deterministic IP so assertions are stable
+    monkeypatch.setattr(HeartbeatService, "get_local_ip", lambda self: "10.0.0.42")
+    return _FakeAsyncClient
+
+
+def test_send_heartbeat_builds_expected_params(patched_httpx):
+    svc = HeartbeatService()
+    svc.set_app_config(
+        host="0.0.0.0",
+        port=8085,
+        target_nodes=[
+            {
+                "name": "proxy1",
+                "host": "127.0.0.1",
+                "port": "8001",
+                "nodes": [
+                    {"name": "n1", "host": "127.0.0.1", "port": "9001"},
+                    {"name": "n2", "host": "127.0.0.1", "port": "9002"},
+                ],
+            },
+        ],
+    )
+
+    ok = asyncio.run(svc.send_heartbeat("http://disc.example/heartbeat"))
+    assert ok is True
+
+    params = patched_httpx.last_params
+    assert params is not None
+    assert params["api_address"] == "http://10.0.0.42:8085"
+    assert params["pid"] > 0
+    # total children across proxies
+    other = json.loads(params["other_info"])
+    assert other["nodes_count"] == 2
+    # version fallback when /version returns empty body
+    assert params["version"] == "1.0.0"
+
+
+def test_send_heartbeat_returns_false_on_http_error(patched_httpx):
+    patched_httpx.heartbeat_response = _FakeResponse(500, b"err")
+
+    svc = HeartbeatService()
+    svc.set_app_config(host="0.0.0.0", port=8085, target_nodes=[])
+
+    ok = asyncio.run(svc.send_heartbeat("http://disc.example/heartbeat"))
+    assert ok is False
+
+
+def test_send_heartbeat_uses_version_from_target_nodes(patched_httpx):
+    patched_httpx.version_response = _FakeResponse(200, b'"1.2.3"')
+
+    svc = HeartbeatService()
+    svc.set_app_config(
+        host="0.0.0.0",
+        port=8085,
+        target_nodes=[
+            {
+                "name": "proxy1",
+                "host": "127.0.0.1",
+                "port": "8001",
+                "nodes": [
+                    {"name": "n1", "host": "127.0.0.1", "port": "9001"},
+                ],
+            },
+        ],
+    )
+
+    ok = asyncio.run(svc.send_heartbeat("http://disc.example/heartbeat"))
+    assert ok is True
+    assert patched_httpx.last_params["version"] == "1.2.3"
+
+
+def test_status_reports_running_flag():
+    svc = HeartbeatService()
+    status = svc.status()
+    assert status["running"] in (False, None)
+    assert "startup_time" in status
+    assert "current_time" in status
diff --git a/tests/test_banner.py b/tests/test_banner.py
new file mode 100644
index 0000000..b7598a7
--- /dev/null
+++ b/tests/test_banner.py
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the LMCache startup banner."""
+
+# Standard
+import io
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache import banner
+from lmcache.banner import (
+    DISABLE_BANNER_ENV,
+    LMCACHE_LINKEDIN,
+    LMCACHE_RECIPES,
+    LMCACHE_WEBSITE,
+    print_banner_once,
+)
+
+
+class _TTYStream(io.StringIO):
+    """In-memory stream that reports itself as a terminal."""
+
+    def isatty(self) -> bool:
+        return True
+
+
+@pytest.fixture(autouse=True)
+def _fresh_banner_state(monkeypatch):
+    """Reset the once-per-process guard and opt-out env var between tests."""
+    monkeypatch.setattr(banner, "_banner_printed", False)
+    monkeypatch.delenv(DISABLE_BANNER_ENV, raising=False)
+
+
+def test_banner_contains_version_links_and_opt_out_hint():
+    stream = io.StringIO()
+    print_banner_once(stream)
+    output = stream.getvalue()
+    assert "LMCache v" in output
+    assert LMCACHE_WEBSITE in output
+    assert LMCACHE_RECIPES in output
+    assert LMCACHE_LINKEDIN in output
+    assert DISABLE_BANNER_ENV in output
+
+
+def test_banner_is_plain_on_non_tty_stream():
+    stream = io.StringIO()
+    print_banner_once(stream)
+    assert "\x1b[" not in stream.getvalue()
+
+
+def test_banner_is_colored_on_tty_stream():
+    stream = _TTYStream()
+    print_banner_once(stream)
+    output = stream.getvalue()
+    assert "\x1b[1;3;38;2;203;75;22m" in output  # bold italic solarized orange
+    assert "\x1b[38;2;42;161;152m" in output  # solarized cyan
+
+
+def test_banner_prints_at_most_once_per_process():
+    first = io.StringIO()
+    second = io.StringIO()
+    print_banner_once(first)
+    print_banner_once(second)
+    assert first.getvalue() != ""
+    assert second.getvalue() == ""
+
+
+@pytest.mark.parametrize("value", ["1", "true", "YES"])
+def test_banner_disabled_by_env_var(monkeypatch, value):
+    monkeypatch.setenv(DISABLE_BANNER_ENV, value)
+    stream = io.StringIO()
+    print_banner_once(stream)
+    assert stream.getvalue() == ""
+
+
+def test_banner_not_disabled_by_falsy_env_var(monkeypatch):
+    monkeypatch.setenv(DISABLE_BANNER_ENV, "0")
+    stream = io.StringIO()
+    print_banner_once(stream)
+    assert stream.getvalue() != ""
diff --git a/tests/test_observability.py b/tests/test_observability.py
new file mode 100644
index 0000000..4e1f7ea
--- /dev/null
+++ b/tests/test_observability.py
@@ -0,0 +1,466 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+from prometheus_client import REGISTRY
+import pytest
+
+# First Party
+from lmcache.observability import (
+    LMCStatsMonitor,
+    PrometheusLogger,
+)
+
+
+@pytest.fixture(scope="function")
+def stats_monitor():
+    LMCStatsMonitor.DestroyInstance()
+    return LMCStatsMonitor.GetOrCreate()
+
+
+def test_on_retrieve_request(stats_monitor):
+    stats_monitor.on_retrieve_request(num_tokens=100)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_retrieve_requests == 1
+    assert stats.retrieve_hit_rate == 1.0
+    assert stats.local_cache_usage_bytes == 0
+    assert stats.remote_cache_usage_bytes == 0
+    assert len(stats.time_to_retrieve) == 0
+
+
+def test_on_retrieve_finished(stats_monitor):
+    stats_obj = stats_monitor.on_retrieve_request(num_tokens=100)
+    stats_monitor.on_retrieve_finished(
+        retrieve_stats=stats_obj,
+        num_retrieved_tokens=100,
+    )
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_retrieve_requests == 1
+    assert stats.retrieve_hit_rate == 1.0
+    assert len(stats.time_to_retrieve) == 1
+
+
+def test_on_store_request_and_finished(stats_monitor):
+    stats_obj = stats_monitor.on_store_request(num_tokens=50)
+    stats_monitor.on_store_finished(store_stats=stats_obj)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_store_requests == 1
+    assert len(stats.time_to_store) == 1
+
+
+def test_update_local_cache_usage(stats_monitor):
+    stats_monitor.update_local_cache_usage(usage=1024)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.local_cache_usage_bytes == 1024
+
+
+def test_update_remote_cache_usage(stats_monitor):
+    stats_monitor.update_remote_cache_usage(usage=2048)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.remote_cache_usage_bytes == 2048
+
+
+def test_update_local_storage_usage(stats_monitor):
+    stats_monitor.update_local_storage_usage(usage=4096)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.local_storage_usage_bytes == 4096
+
+
+def test_on_lookup_request(stats_monitor):
+    stats_monitor.on_lookup_request(num_tokens=50)
+    assert len(stats_monitor.lookup_requests) == 1
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_lookup_requests == 1
+    assert stats.interval_lookup_tokens == 50
+    assert stats.lookup_hit_rate == 0
+    assert len(stats.interval_lookup_hit_rates) == 0
+    # on_lookup_finished is not called, lookup_requests is not clear
+    assert len(stats_monitor.lookup_requests) == 1
+
+
+def test_on_lookup_finished(stats_monitor):
+    stats_obj = stats_monitor.on_lookup_request(num_tokens=100)
+    assert len(stats_monitor.lookup_requests) == 1
+    stats_monitor.on_lookup_finished(stats=stats_obj, num_hit_tokens=80)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_lookup_requests == 1
+    assert stats.interval_lookup_tokens == 100
+    assert stats.interval_lookup_hits == 80
+    assert stats.lookup_hit_rate == 0.8
+    assert len(stats.interval_lookup_hit_rates) == 1
+    assert stats.interval_lookup_hit_rates[0] == 0.8
+    assert len(stats_monitor.lookup_requests) == 0
+
+
+def test_remote_read_metrics(stats_monitor):
+    stats_monitor.update_interval_remote_read_metrics(read_bytes=1024)
+    stats_monitor.update_interval_remote_read_metrics(read_bytes=2048)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_remote_read_requests == 2
+    assert stats.interval_remote_read_bytes == 3072
+
+
+def test_remote_write_metrics(stats_monitor):
+    stats_monitor.update_interval_remote_write_metrics(write_bytes=512)
+    stats_monitor.update_interval_remote_write_metrics(write_bytes=1024)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_remote_write_requests == 2
+    assert stats.interval_remote_write_bytes == 1536
+
+
+def test_remote_time_metrics(stats_monitor):
+    stats_monitor.update_interval_remote_time_to_get(get_time=10.5)
+    stats_monitor.update_interval_remote_time_to_put(put_time=15.2)
+    stats_monitor.update_interval_remote_time_to_get_sync(get_time_sync=12.3)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_remote_time_to_get == [10.5]
+    assert stats.interval_remote_time_to_put == [15.2]
+    assert stats.interval_remote_time_to_get_sync == [12.3]
+
+
+def test_remote_ping_metrics(stats_monitor):
+    # Test successful ping
+    stats_monitor.update_remote_ping_latency(latency=25.5)
+    stats_monitor.update_remote_ping_error_code(error_code=0)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_remote_ping_latency == 25.5
+    assert stats.interval_remote_ping_success == 1
+    assert stats.interval_remote_ping_errors == 0
+    assert stats.interval_remote_ping_error_code == 0
+
+
+def test_remote_ping_errors(stats_monitor):
+    # Test ping errors
+    stats_monitor.update_remote_ping_error_code(error_code=404)
+    stats_monitor.update_remote_ping_error_code(error_code=500)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_remote_ping_errors == 2
+    assert stats.interval_remote_ping_success == 0
+    assert stats.interval_remote_ping_error_code == 500
+
+
+def test_retrieve_and_store_speed(stats_monitor):
+    # Test retrieve speed calculation
+    stats_obj_retrieve = stats_monitor.on_retrieve_request(num_tokens=1000)
+    stats_monitor.on_retrieve_finished(
+        retrieve_stats=stats_obj_retrieve, num_retrieved_tokens=1000
+    )
+
+    # Test store speed calculation
+    stats_obj_store = stats_monitor.on_store_request(num_tokens=500)
+    stats_monitor.on_store_finished(store_stats=stats_obj_store)
+
+    stats = stats_monitor.get_stats_and_clear()
+    assert len(stats.retrieve_speed) == 1
+    assert len(stats.store_speed) == 1
+    assert stats.retrieve_speed[0] > 0  # Should be tokens/second
+    assert stats.store_speed[0] > 0  # Should be tokens/second
+
+
+def test_multiple_lookup_operations(stats_monitor):
+    # Test multiple lookup operations
+    stats_obj_1 = stats_monitor.on_lookup_request(num_tokens=100)
+    stats_monitor.on_lookup_finished(stats=stats_obj_1, num_hit_tokens=80)
+    stats_obj_2 = stats_monitor.on_lookup_request(num_tokens=200)
+    stats_monitor.on_lookup_finished(stats=stats_obj_2, num_hit_tokens=150)
+    assert len(stats_monitor.lookup_requests) == 2
+    assert stats_monitor.lookup_requests[stats_obj_1.request_id].hit_rate() == 0.8
+    assert stats_monitor.lookup_requests[stats_obj_2.request_id].hit_rate() == 0.75
+
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_lookup_requests == 2
+    assert stats.interval_lookup_tokens == 300
+    assert stats.interval_lookup_hits == 230
+    assert stats.lookup_hit_rate == 230 / 300
+    assert len(stats.interval_lookup_hit_rates) == 2
+    assert len(stats_monitor.lookup_requests) == 0
+
+
+def test_mixed_remote_operations(stats_monitor):
+    # Test a mix of remote operations
+    stats_monitor.update_interval_remote_read_metrics(read_bytes=1024)
+    stats_monitor.update_interval_remote_write_metrics(write_bytes=512)
+    stats_monitor.update_interval_remote_time_to_get(get_time=10.0)
+    stats_monitor.update_interval_remote_time_to_put(put_time=20.0)
+    stats_monitor.update_interval_remote_time_to_get_sync(get_time_sync=15.0)
+    stats_monitor.update_remote_ping_latency(latency=30.0)
+    stats_monitor.update_remote_ping_error_code(error_code=0)
+
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_remote_read_requests == 1
+    assert stats.interval_remote_read_bytes == 1024
+    assert stats.interval_remote_write_requests == 1
+    assert stats.interval_remote_write_bytes == 512
+    assert stats.interval_remote_time_to_get == [10.0]
+    assert stats.interval_remote_time_to_put == [20.0]
+    assert stats.interval_remote_time_to_get_sync == [15.0]
+    assert stats.interval_remote_ping_latency == 30.0
+    assert stats.interval_remote_ping_success == 1
+    assert stats.interval_remote_ping_errors == 0
+
+
+def test_combined_operations(stats_monitor):
+    stats_obj_retrieve = stats_monitor.on_retrieve_request(num_tokens=200)
+    stats_monitor.on_retrieve_finished(
+        retrieve_stats=stats_obj_retrieve,
+        num_retrieved_tokens=200,
+    )
+    stats_obj_store = stats_monitor.on_store_request(num_tokens=100)
+    stats_monitor.on_store_finished(store_stats=stats_obj_store)
+    stats_monitor.update_local_cache_usage(usage=512)
+    stats_monitor.update_remote_cache_usage(usage=1024)
+    stats_monitor.update_local_storage_usage(usage=2048)
+
+    stats_monitor2 = LMCStatsMonitor.GetOrCreate()
+    stats = stats_monitor2.get_stats_and_clear()
+
+    assert stats.interval_retrieve_requests == 1
+    assert stats.interval_store_requests == 1
+    assert stats.retrieve_hit_rate == 1.0
+    assert stats.local_cache_usage_bytes == 512
+    assert stats.remote_cache_usage_bytes == 1024
+    assert stats.local_storage_usage_bytes == 2048
+    assert len(stats.time_to_retrieve) == 1
+    assert len(stats.time_to_store) == 1
+
+
+def test_stats_clearing(stats_monitor):
+    # Add some data
+    stats_obj = stats_monitor.on_lookup_request(num_tokens=100)
+    stats_monitor.update_interval_remote_read_metrics(read_bytes=1024)
+    stats_monitor.update_remote_ping_latency(latency=25.0)
+
+    assert len(stats_monitor.lookup_requests) == 1
+
+    # Get stats (which should clear them)
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.interval_lookup_requests == 1
+    assert stats.interval_lookup_tokens == 100
+    assert stats.interval_lookup_hits == 0
+    assert stats.interval_remote_read_requests == 1
+    assert stats.interval_remote_read_bytes == 1024
+    assert stats.interval_remote_ping_latency == 25.0
+    assert len(stats.interval_lookup_hit_rates) == 0
+
+    # Get stats again - should be cleared
+    stats2 = stats_monitor.get_stats_and_clear()
+    assert stats2.interval_lookup_requests == 0
+    assert stats2.interval_lookup_tokens == 0
+    assert stats2.interval_lookup_hits == 0
+    assert stats2.interval_remote_read_requests == 0
+    assert stats2.interval_remote_read_bytes == 0
+    assert stats2.interval_remote_ping_latency == 0
+    assert len(stats2.interval_lookup_hit_rates) == 0
+
+    assert len(stats_monitor.lookup_requests) == 1
+
+    # finish lookup request
+    stats_monitor.on_lookup_finished(stats=stats_obj, num_hit_tokens=80)
+    stats3 = stats_monitor.get_stats_and_clear()
+    assert stats3.interval_lookup_requests == 0
+    assert stats3.interval_lookup_tokens == 0
+    assert stats3.interval_lookup_hits == 80
+    assert stats3.interval_remote_read_requests == 0
+    assert stats3.interval_remote_read_bytes == 0
+    assert stats3.interval_remote_ping_latency == 0
+    assert len(stats3.interval_lookup_hit_rates) == 1
+    assert stats3.interval_lookup_hit_rates[0] == 0.8
+
+    assert len(stats_monitor.lookup_requests) == 0
+
+
+def test_zero_division_protection(stats_monitor):
+    # Test that hit rates handle zero division gracefully
+    stats = stats_monitor.get_stats_and_clear()
+    assert stats.retrieve_hit_rate == 1.0
+    assert stats.lookup_hit_rate == 0
+
+
+# ---- PrometheusLogger custom histogram bucket tests ----
+
+
+@pytest.fixture(scope="function")
+def _cleanup_prometheus_logger():
+    """Reset PrometheusLogger instances and metrics between tests."""
+    LMCStatsMonitor.unregister_all_metrics()
+    PrometheusLogger._instances = {}
+    yield
+    LMCStatsMonitor.unregister_all_metrics()
+    PrometheusLogger._instances = {}
+
+
+def _make_metadata():
+    """Create a minimal mock LMCacheMetadata for testing."""
+    meta = MagicMock()
+    meta.model_name = "test_model"
+    meta.worker_id = 0
+    meta.role = "worker"
+    meta.served_model_name = None
+    return meta
+
+
+def _make_config(extra_config=None):
+    """Create a minimal mock config for testing."""
+    cfg = MagicMock()
+    cfg.extra_config = extra_config
+    cfg.get_extra_config_value = lambda key, default=None: (
+        extra_config.get(key, default) if extra_config is not None else default
+    )
+    return cfg
+
+
+def _sample_labels(prom: PrometheusLogger) -> dict[str, str]:
+    """Return labels as Prometheus exposes them in collected samples."""
+    return {name: str(value) for name, value in prom.labels.items()}
+
+
+def test_prometheus_logger_default_buckets(_cleanup_prometheus_logger):
+    """Histogram should use default buckets when no config."""
+    meta = _make_metadata()
+    prom = PrometheusLogger(meta)
+    # Verify histogram was created (basic sanity check)
+    assert prom.histogram_time_to_retrieve is not None
+
+
+def test_prometheus_logger_custom_buckets(_cleanup_prometheus_logger):
+    """Histogram should use custom buckets from config."""
+    meta = _make_metadata()
+    custom_buckets = [0.1, 0.5, 1.0, 5.0]
+    cfg = _make_config(
+        {
+            "histogram_bucket_time_to_retrieve": custom_buckets,
+        }
+    )
+    prom = PrometheusLogger(meta, config=cfg)
+    labels = prom.labels
+
+    # Verify the histogram's upper_bounds match custom buckets + Inf
+    hist = prom.histogram_time_to_retrieve.labels(**labels)
+    # prometheus_client Histogram stores buckets as _upper_bounds
+    upper_bounds = list(hist._upper_bounds)
+    for bucket_val in custom_buckets:
+        assert bucket_val in upper_bounds
+
+
+def test_prometheus_logger_partial_custom_buckets(
+    _cleanup_prometheus_logger,
+):
+    """Only specified histograms should get custom buckets."""
+    meta = _make_metadata()
+    custom_buckets = [1, 10, 100]
+    cfg = _make_config(
+        {
+            "histogram_bucket_store_speed": custom_buckets,
+        }
+    )
+    prom = PrometheusLogger(meta, config=cfg)
+    labels = prom.labels
+
+    # store_speed should have custom buckets
+    hist = prom.histogram_store_speed.labels(**labels)
+    upper_bounds = list(hist._upper_bounds)
+    for bucket_val in custom_buckets:
+        assert bucket_val in upper_bounds
+
+    # time_to_retrieve should still have default buckets
+    hist_default = prom.histogram_time_to_retrieve.labels(**labels)
+    default_upper = list(hist_default._upper_bounds)
+    # default first bucket is 0.001
+    assert 0.001 in default_upper
+
+
+def test_prometheus_logger_get_or_create_with_config(
+    _cleanup_prometheus_logger,
+):
+    """GetOrCreate should pass config to the constructor."""
+    meta = _make_metadata()
+    custom_buckets = [0.01, 0.1, 1.0]
+    cfg = _make_config(
+        {
+            "histogram_bucket_time_to_store": custom_buckets,
+        }
+    )
+    prom = PrometheusLogger.GetOrCreate(meta, config=cfg)
+    labels = prom.labels
+
+    hist = prom.histogram_time_to_store.labels(**labels)
+    upper_bounds = list(hist._upper_bounds)
+    for bucket_val in custom_buckets:
+        assert bucket_val in upper_bounds
+
+
+def test_prometheus_logger_get_or_create_allows_multiple_roles(
+    _cleanup_prometheus_logger,
+):
+    """Different roles should not be treated as global metadata conflicts."""
+    worker_meta = _make_metadata()
+    scheduler_meta = _make_metadata()
+    scheduler_meta.role = "scheduler"
+
+    worker_prom = PrometheusLogger.GetOrCreate(worker_meta)
+    scheduler_prom = PrometheusLogger.GetOrCreate(scheduler_meta)
+
+    assert worker_prom.labels["role"] == "worker"
+    assert scheduler_prom.labels["role"] == "scheduler"
+
+
+def test_prometheus_logger_label_view_rebinds_dynamic_metrics(
+    _cleanup_prometheus_logger,
+):
+    """Dynamic gauge callbacks should use each label view's labels."""
+    worker_meta = _make_metadata()
+    scheduler_meta = _make_metadata()
+    scheduler_meta.role = "scheduler"
+
+    worker_prom = PrometheusLogger.GetOrCreate(worker_meta)
+    scheduler_prom = PrometheusLogger.GetOrCreate(scheduler_meta)
+
+    worker_prom.lmcache_is_healthy.set_function(lambda: 1)
+    scheduler_prom.lmcache_is_healthy.set_function(lambda: 2)
+
+    assert (
+        REGISTRY.get_sample_value(
+            "lmcache:lmcache_is_healthy",
+            _sample_labels(worker_prom),
+        )
+        == 1
+    )
+    assert (
+        REGISTRY.get_sample_value(
+            "lmcache:lmcache_is_healthy",
+            _sample_labels(scheduler_prom),
+        )
+        == 2
+    )
+
+
+def test_prometheus_logger_reset_reinitializes_all_label_views(
+    _cleanup_prometheus_logger,
+):
+    """Resetting one label view should keep metric children visible for all views."""
+    worker_meta = _make_metadata()
+    scheduler_meta = _make_metadata()
+    scheduler_meta.role = "scheduler"
+
+    worker_prom = PrometheusLogger.GetOrCreate(worker_meta)
+    scheduler_prom = PrometheusLogger.GetOrCreate(scheduler_meta)
+
+    worker_prom.counter_num_retrieve_requests.labels(**worker_prom.labels).inc()
+    scheduler_prom.counter_num_retrieve_requests.labels(**scheduler_prom.labels).inc()
+    scheduler_prom.reset_counters()
+
+    assert (
+        REGISTRY.get_sample_value(
+            "lmcache:num_retrieve_requests_total",
+            _sample_labels(worker_prom),
+        )
+        == 0
+    )
+    assert (
+        REGISTRY.get_sample_value(
+            "lmcache:num_retrieve_requests_total",
+            _sample_labels(scheduler_prom),
+        )
+        == 0
+    )
diff --git a/tests/test_serde.py b/tests/test_serde.py
new file mode 100644
index 0000000..d15e114
--- /dev/null
+++ b/tests/test_serde.py
@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.storage_backend.serde.cachegen_basics import CacheGenEncoderOutput
+from lmcache.storage_backend.serde.cachegen_decoder import CacheGenDeserializer
+from lmcache.storage_backend.serde.cachegen_encoder import CacheGenSerializer
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+
+# CacheGen has hand-written CUDA and SYCL kernels only; gate the test on
+# those backends explicitly (whitelist), so HPU / CPU-only CI / future
+# backends without a CacheGen kernel are skipped automatically.
+# torch_device_type is set to "cuda"/"xpu" only after is_available() passes
+# in lmcache.__init__, so no extra availability check is needed here.
+_GPU_AVAILABLE = torch_device_type == "cuda" or torch_device_type == "xpu"
+
+
+def generate_kv_cache(num_tokens, device):
+    ret = []
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    shape = [num_tokens, num_heads, head_size]
+    dtype = torch.bfloat16
+
+    for i in range(num_layers):
+        k = torch.rand(shape, dtype=dtype, device=device)
+        v = torch.rand(shape, dtype=dtype, device=device)
+        ret.append((k, v))
+
+    return tuple(ret)
+
+
+def to_blob(kv_tuples):
+    return torch.stack(
+        [torch.stack(inner_tuple, dim=0) for inner_tuple in kv_tuples], dim=0
+    )
+
+
+@pytest.mark.parametrize("chunk_size", [16, 128, 256])
+@pytest.mark.skipif(
+    not _GPU_AVAILABLE,
+    reason="No GPU backend (CUDA or XPU) available",
+)
+def test_cachegen_encoder(chunk_size):
+    config = LMCacheEngineConfig.from_defaults(chunk_size=chunk_size)
+    metadata = LMCacheMetadata(
+        model_name="mistralai/Mistral-7B-Instruct-v0.2",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=None,
+    )
+    # metadata2 = LMCacheMetadata(
+    #     model_name="mistralai/Mistral-7B-Instruct-v0.2",
+    #     world_size=1,
+    #     local_world_size=1,
+    #     worker_id=0,
+    #     local_worker_id=0,
+    #     kv_dtype=torch.bfloat16,
+    #     kv_shape=None,
+    # )
+    serializer = CacheGenSerializer(config, metadata)
+    # serializer2 = CacheGenSerializer(config, metadata2)
+
+    kv = to_blob(generate_kv_cache(chunk_size, torch_device_type))
+    output = serializer.to_bytes(kv)
+    # huggingface:
+    # kv2 = kv.permute([0, 1, 3, 2, 4])
+    # output2 = serializer2.to_bytes(kv2)
+
+    # assert abs(len(output) - len(output2)) < 10
+    output_dict = CacheGenEncoderOutput.from_bytes(output)
+    assert output_dict.num_heads == 8
+    assert output_dict.head_size == 128
+
+
+@pytest.mark.parametrize("chunk_size", [16, 128, 256])
+@pytest.mark.skipif(
+    not _GPU_AVAILABLE,
+    reason="No GPU backend (CUDA or XPU) available",
+)
+def test_cachegen_decoder(chunk_size):
+    config = LMCacheEngineConfig.from_defaults(chunk_size=chunk_size)
+    metadata = LMCacheMetadata(
+        model_name="mistralai/Mistral-7B-Instruct-v0.2",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=None,
+    )
+    serializer = CacheGenSerializer(config, metadata)
+    deserializer = CacheGenDeserializer(config, metadata, torch.bfloat16)
+
+    kv = to_blob(generate_kv_cache(chunk_size, torch_device_type))
+    output = serializer.to_bytes(kv)
+
+    decoded_kv = deserializer.from_bytes(output)
+    assert decoded_kv.shape == kv.shape
+    assert decoded_kv.mean() != 0
+
+
+@pytest.mark.skipif(
+    not _GPU_AVAILABLE,
+    reason="No GPU backend (CUDA or XPU) available",
+)
+def test_cachegen_unmatched_size():
+    chunk_size = 256
+    config = LMCacheEngineConfig.from_defaults(chunk_size=chunk_size)
+    metadata = LMCacheMetadata(
+        model_name="mistralai/Mistral-7B-Instruct-v0.2",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=None,
+    )
+    serializer = CacheGenSerializer(config, metadata)
+    deserializer = CacheGenDeserializer(config, metadata, torch.bfloat16)
+
+    kv = to_blob(generate_kv_cache(chunk_size - 20, torch_device_type))
+    output = serializer.to_bytes(kv)
+
+    decoded_kv = deserializer.from_bytes(output)
+    assert decoded_kv.shape == kv.shape
+    assert decoded_kv.mean() != 0
diff --git a/tests/test_usage_telemetry.py b/tests/test_usage_telemetry.py
new file mode 100644
index 0000000..2742eae
--- /dev/null
+++ b/tests/test_usage_telemetry.py
@@ -0,0 +1,520 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the anonymous usage telemetry package (lmcache/usage_telemetry/)."""
+
+# Standard
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.usage_telemetry import (
+    USAGE_SCHEMA_VERSION,
+    ContinuousUsageContext,
+    InitializeMPUsageContext,
+    InitializeUsageContext,
+    MPServerMessage,
+    MPUsageContext,
+    UsageContext,
+    UsageMessageSender,
+    get_usage_identity,
+    is_usage_tracking_enabled,
+)
+from lmcache.usage_telemetry.guard import swallow_telemetry_errors
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    GdsL1Config,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdaptersConfig,
+    get_type_name_for_config,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.multiprocess.config import MPServerConfig
+
+
+class RecordingSender(UsageMessageSender):
+    """Transport stub that records payloads instead of POSTing them."""
+
+    def __init__(self) -> None:
+        self.sent: list[tuple[str, dict[str, object]]] = []
+
+    def send(self, url: str, payload: dict[str, object]) -> None:
+        self.sent.append((url, payload))
+
+
+@dataclass
+class StubStats:
+    """Minimal stand-in for LMCacheStats used by incr_or_send_stats."""
+
+    interval_hit_tokens: int = 0
+    interval_stored_tokens: int = 0
+    interval_request_cache_lifespan: list[float] = field(default_factory=list)
+
+
+class UsageSink(ThreadingHTTPServer):
+    """In-process HTTP server recording every POSTed usage payload."""
+
+    def __init__(self) -> None:
+        super().__init__(("127.0.0.1", 0), _UsageSinkHandler)
+        self.received: list[tuple[str, dict[str, object]]] = []
+
+    def wait_for(
+        self, count: int, timeout: float = 15.0
+    ) -> list[tuple[str, dict[str, object]]]:
+        """Return received (path, payload) pairs once *count* arrived."""
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline and len(self.received) < count:
+            time.sleep(0.01)
+        return list(self.received)
+
+
+class _UsageSinkHandler(BaseHTTPRequestHandler):
+    def do_POST(self) -> None:
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length))
+        self.server.received.append((self.path, body))  # type: ignore[attr-defined]
+        self.send_response(200)
+        self.end_headers()
+
+    def log_message(self, *args: object) -> None:
+        pass
+
+
+@pytest.fixture
+def usage_env(monkeypatch, tmp_path):
+    """Isolate usage-telemetry state: HOME, env vars, and singletons."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("LMCACHE_USAGE_TRACK_URL", "http://stats.test")
+    monkeypatch.delenv("LMCACHE_TRACK_USAGE", raising=False)
+    monkeypatch.delenv("DO_NOT_TRACK", raising=False)
+    monkeypatch.delenv("LMCACHE_USAGE_TRACK_INTERVAL", raising=False)
+    monkeypatch.setattr("lmcache.usage_telemetry.identity._usage_identity", None)
+    monkeypatch.setattr(ContinuousUsageContext, "_instance", None)
+    return tmp_path
+
+
+@pytest.fixture
+def usage_sink(usage_env, monkeypatch):
+    """Local HTTP sink; points LMCACHE_USAGE_TRACK_URL at it."""
+    sink = UsageSink()
+    thread = threading.Thread(target=sink.serve_forever, daemon=True)
+    thread.start()
+    port = sink.server_address[1]
+    monkeypatch.setenv("LMCACHE_USAGE_TRACK_URL", f"http://127.0.0.1:{port}")
+    yield sink
+    sink.shutdown()
+    sink.server_close()
+
+
+def make_storage_manager_config() -> StorageManagerConfig:
+    return StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=1 << 30,
+                use_lazy=False,
+                shm_name="test_shm",
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+
+
+def make_metadata() -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(32, 2, 256, 32, 128),
+        use_mla=False,
+        role="worker",
+    )
+
+
+class TestOptOut:
+    def test_enabled_by_default(self, usage_env):
+        assert is_usage_tracking_enabled()
+
+    def test_lmcache_track_usage_false(self, usage_env, monkeypatch):
+        monkeypatch.setenv("LMCACHE_TRACK_USAGE", "false")
+        assert not is_usage_tracking_enabled()
+
+    @pytest.mark.parametrize("value", ["1", "true", "yes", "TRUE"])
+    def test_do_not_track_env(self, usage_env, monkeypatch, value):
+        monkeypatch.setenv("DO_NOT_TRACK", value)
+        assert not is_usage_tracking_enabled()
+
+    def test_do_not_track_env_unset_values(self, usage_env, monkeypatch):
+        monkeypatch.setenv("DO_NOT_TRACK", "0")
+        assert is_usage_tracking_enabled()
+
+
+class TestIdentity:
+    def test_identity_is_process_singleton(self, usage_env):
+        first = get_usage_identity()
+        second = get_usage_identity()
+        assert first is second
+        assert first.session_id
+        assert first.machine_id
+
+    def test_machine_id_persists_across_sessions(self, usage_env, monkeypatch):
+        first = get_usage_identity()
+        # Simulate a new process: the session singleton resets, the
+        # machine_id file survives.
+        monkeypatch.setattr("lmcache.usage_telemetry.identity._usage_identity", None)
+        second = get_usage_identity()
+        assert second.session_id != first.session_id
+        assert second.machine_id == first.machine_id
+        machine_id_file = usage_env / ".config" / "lmcache" / "machine_id"
+        assert machine_id_file.read_text().strip() == first.machine_id
+
+    def test_machine_id_empty_when_unwritable(self, usage_env):
+        # Occupy the config-dir path with a regular file so the machine_id
+        # file can be neither read nor created.
+        (usage_env / ".config").mkdir()
+        (usage_env / ".config" / "lmcache").touch()
+        identity = get_usage_identity()
+        assert identity.machine_id == ""
+        assert identity.session_id
+
+
+class TestUsageContext:
+    def test_report_once_sends_all_messages(self, usage_env):
+        sender = RecordingSender()
+        context = UsageContext(
+            LMCacheEngineConfig.from_defaults(),
+            make_metadata(),
+            sender=sender,
+        )
+        context.report_once()
+
+        message_types = [payload["message_type"] for _, payload in sender.sent]
+        assert message_types == ["EnvMessage", "EngineMessage", "MetadataMessage"]
+
+        identity = get_usage_identity()
+        for url, payload in sender.sent:
+            assert url == "http://stats.test/context"
+            assert payload["schema_version"] == USAGE_SCHEMA_VERSION
+            assert payload["session_id"] == identity.session_id
+            assert payload["machine_id"] == identity.machine_id
+            assert payload["deployment_mode"] == "single_process"
+
+        engine_payload = sender.sent[1][1]
+        assert engine_payload["model_name"] == "test_model"
+        assert engine_payload["kv_dtype"] == "torch.bfloat16"
+
+    def test_local_log_written(self, usage_env, tmp_path):
+        log_path = tmp_path / "usage.log"
+        context = UsageContext(
+            LMCacheEngineConfig.from_defaults(),
+            make_metadata(),
+            local_log=str(log_path),
+            sender=RecordingSender(),
+        )
+        context.report_once()
+        content = log_path.read_text()
+        assert "message_type: EnvMessage" in content
+        assert "message_type: EngineMessage" in content
+        assert "session_id:" in content
+
+
+class TestInitializeUsageContext:
+    def test_returns_none_when_disabled(self, usage_env, monkeypatch):
+        monkeypatch.setenv("LMCACHE_TRACK_USAGE", "false")
+        context = InitializeUsageContext(
+            LMCacheEngineConfig.from_defaults(), make_metadata()
+        )
+        assert context is None
+
+    def test_reports_from_background_thread(self, usage_env):
+        sender = RecordingSender()
+        context = InitializeUsageContext(
+            LMCacheEngineConfig.from_defaults(), make_metadata(), sender=sender
+        )
+        assert context is not None
+        deadline = time.monotonic() + 10
+        while time.monotonic() < deadline and len(sender.sent) < 3:
+            time.sleep(0.01)
+        assert len(sender.sent) == 3
+
+
+class TestContinuousUsageContext:
+    def test_flush_and_reset(self, usage_env, monkeypatch):
+        monkeypatch.setenv("LMCACHE_USAGE_TRACK_INTERVAL", "0")
+        sender = RecordingSender()
+        context = ContinuousUsageContext(make_metadata(), sender=sender)
+
+        context.incr_or_send_stats(
+            StubStats(
+                interval_hit_tokens=100,
+                interval_stored_tokens=200,
+                interval_request_cache_lifespan=[0.5, 2.0],
+            )
+        )
+
+        assert len(sender.sent) == 2
+        usage_url, usage_payload = sender.sent[0]
+        assert usage_url.endswith("cache-usage")
+        assert usage_payload["message_type"] == "ContinuousContextMessage"
+        assert usage_payload["interval_num_hit_tokens"] == 100
+        assert usage_payload["interval_num_stored_tokens"] == 200
+        assert usage_payload["sequence_number"] == 1
+        assert usage_payload["session_id"] == get_usage_identity().session_id
+        assert usage_payload["deployment_mode"] == "single_process"
+
+        lifespan_url, lifespan_payload = sender.sent[1]
+        assert lifespan_url.endswith("cache-lifespan")
+        assert lifespan_payload["message_type"] == "CacheLifespanMessage"
+        assert lifespan_payload["sequence_number"] == 1
+
+        # Counters reset after the flush; a second flush reports zeros with
+        # the next sequence number.
+        context.incr_or_send_stats(StubStats())
+        assert sender.sent[2][1]["interval_num_hit_tokens"] == 0
+        assert sender.sent[2][1]["sequence_number"] == 2
+
+    def test_disabled_is_noop(self, usage_env, monkeypatch):
+        monkeypatch.setenv("LMCACHE_TRACK_USAGE", "false")
+        monkeypatch.setenv("LMCACHE_USAGE_TRACK_INTERVAL", "0")
+        sender = RecordingSender()
+        context = ContinuousUsageContext(make_metadata(), sender=sender)
+        context.incr_or_send_stats(
+            StubStats(
+                interval_hit_tokens=100,
+                interval_request_cache_lifespan=[1.0],
+            )
+        )
+        assert sender.sent == []
+        assert context.cache_lifespan_data == []
+
+    def test_list_to_histogram(self, usage_env):
+        context = ContinuousUsageContext(make_metadata(), sender=RecordingSender())
+        histogram = context.list_to_histogram([0.5, 2.0, 3.0], [0, 1, 5, 10])
+        assert histogram == {0: 0, 1: 1, 5: 2, 10: 0}
+
+
+class TestMPUsage:
+    def test_mp_server_message_from_configs(self, usage_env):
+        message = MPServerMessage.from_configs(
+            MPServerConfig(), make_storage_manager_config()
+        )
+        assert message.chunk_size == 256
+        assert message.hash_algorithm == "blake3"
+        assert message.engine_type == "default"
+        assert message.supported_transfer_mode == "auto"
+        assert not message.p2p_enabled
+        assert message.l1_size_bytes == 1 << 30
+        assert message.l1_medium == "dram"
+        assert message.l1_shm_enabled
+        assert message.eviction_policy == "LRU"
+        assert message.l2_adapter_types == ""
+        assert message.l2_serde_types == ""
+        assert message.l2_store_policy == "default"
+        assert message.l2_prefetch_policy == "default"
+        assert not message.enable_segmented_prefix
+        assert message.lmcache_version
+
+    def test_mp_server_message_serde_and_segmented_prefix(self, usage_env, tmp_path):
+        # The FS adapter needs the native storage ops extension; skip on
+        # builds without it.
+        fs_l2_adapter = pytest.importorskip(
+            "lmcache.v1.distributed.l2_adapters.fs_l2_adapter",
+            reason="requires lmcache.native_storage_ops",
+        )
+        serde = pytest.importorskip(
+            "lmcache.v1.distributed.serde",
+            reason="requires lmcache.native_storage_ops",
+        )
+        fs_config = fs_l2_adapter.FSL2AdapterConfig(
+            base_path=str(tmp_path),
+            relative_tmp_dir=None,
+            read_ahead_size=None,
+            use_odirect=False,
+        )
+        fs_config.serde_config = serde.SerdeConfig(type="fp8", kwargs={})
+        storage_config = make_storage_manager_config()
+        storage_config.l2_adapter_config = L2AdaptersConfig([fs_config])
+
+        message = MPServerMessage.from_configs(
+            MPServerConfig(enable_segmented_prefix=True), storage_config
+        )
+        assert message.enable_segmented_prefix
+        assert message.l2_adapter_types == get_type_name_for_config(fs_config)
+        assert message.l2_serde_types == "fp8"
+
+    def test_mp_server_message_gds_l1(self, usage_env, tmp_path):
+        storage_config = StorageManagerConfig(
+            l1_manager_config=L1ManagerConfig(
+                memory_config=L1MemoryManagerConfig(
+                    size_in_bytes=1 << 30,
+                    use_lazy=False,
+                    shm_name="",
+                ),
+                gds_l1_config=GdsL1Config(
+                    file_location=str(tmp_path), size_in_bytes=2 << 30
+                ),
+            ),
+            eviction_config=EvictionConfig(eviction_policy="LRU"),
+        )
+        message = MPServerMessage.from_configs(MPServerConfig(), storage_config)
+        assert message.l1_medium == "gds"
+        assert message.l1_size_bytes == 2 << 30
+        assert not message.l1_shm_enabled
+
+    def test_mp_usage_context_sends_messages(self, usage_env):
+        sender = RecordingSender()
+        context = MPUsageContext(
+            MPServerConfig(),
+            make_storage_manager_config(),
+            sender=sender,
+        )
+        context.report_once()
+
+        message_types = [payload["message_type"] for _, payload in sender.sent]
+        assert message_types == ["EnvMessage", "MPServerMessage"]
+
+        identity = get_usage_identity()
+        for _, payload in sender.sent:
+            assert payload["schema_version"] == USAGE_SCHEMA_VERSION
+            assert payload["session_id"] == identity.session_id
+            assert payload["deployment_mode"] == "mp_server"
+
+        mp_payload = sender.sent[1][1]
+        assert mp_payload["chunk_size"] == 256
+        assert "instance_id" not in mp_payload
+
+    def test_initialize_mp_returns_none_when_disabled(self, usage_env, monkeypatch):
+        monkeypatch.setenv("DO_NOT_TRACK", "1")
+        context = InitializeMPUsageContext(
+            MPServerConfig(), make_storage_manager_config()
+        )
+        assert context is None
+
+
+class RaisingSender(UsageMessageSender):
+    """Transport stub whose every send raises."""
+
+    def send(self, url: str, payload: dict[str, object]) -> None:
+        raise RuntimeError("telemetry transport failure")
+
+
+class TestFailureIsolation:
+    def test_swallow_telemetry_errors_returns_none(self):
+        @swallow_telemetry_errors
+        def boom() -> int:
+            raise ValueError("telemetry bug")
+
+        assert boom() is None
+
+    def test_raising_sender_does_not_break_mp_report(self, usage_env):
+        context = MPUsageContext(
+            MPServerConfig(), make_storage_manager_config(), sender=RaisingSender()
+        )
+        context.report_once()
+
+    def test_raising_sender_does_not_break_continuous_flush(
+        self, usage_env, monkeypatch
+    ):
+        monkeypatch.setenv("LMCACHE_USAGE_TRACK_INTERVAL", "0")
+        context = ContinuousUsageContext(make_metadata(), sender=RaisingSender())
+        context.incr_or_send_stats(StubStats(interval_hit_tokens=1))
+
+    def test_unwritable_local_log_does_not_break_report(self, usage_env, tmp_path):
+        context = UsageContext(
+            LMCacheEngineConfig.from_defaults(),
+            make_metadata(),
+            local_log=str(tmp_path),  # a directory: open() for append fails
+            sender=RecordingSender(),
+        )
+        context.report_once()
+
+    def test_default_sender_swallows_unreachable_server(self, usage_env):
+        # Port 1 is never listening; the send must not raise.
+        UsageMessageSender().send("http://127.0.0.1:1/context", {"k": "v"})
+
+    def test_nonstandard_kv_shape_degrades_to_zero_bytes(self, usage_env, monkeypatch):
+        monkeypatch.setenv("LMCACHE_USAGE_TRACK_INTERVAL", "0")
+        metadata = make_metadata()
+        metadata.kv_shape = ()
+        sender = RecordingSender()
+        context = ContinuousUsageContext(metadata, sender=sender)
+        context.incr_or_send_stats(StubStats(interval_stored_tokens=100))
+        assert sender.sent[0][1]["interval_stored_kv_size"] == 0
+
+
+class TestSingletons:
+    def test_get_or_create_returns_same_instance(self, usage_env):
+        metadata = make_metadata()
+        first = ContinuousUsageContext.GetOrCreate(metadata)
+        second = ContinuousUsageContext.GetOrCreate(metadata)
+        assert first is second
+
+    def test_get_or_create_keeps_first_instance_on_metadata_mismatch(self, usage_env):
+        first = ContinuousUsageContext.GetOrCreate(make_metadata())
+        other_metadata = make_metadata()
+        other_metadata.model_name = "another_model"
+        assert ContinuousUsageContext.GetOrCreate(other_metadata) is first
+
+
+class TestEndToEnd:
+    """Exercise the real HTTP transport against a local sink (no stubs)."""
+
+    def test_single_process_report(self, usage_sink):
+        context = InitializeUsageContext(
+            LMCacheEngineConfig.from_defaults(), make_metadata()
+        )
+        assert context is not None
+        received = usage_sink.wait_for(3)
+        assert len(received) == 3
+        assert {path for path, _ in received} == {"/context"}
+        assert [payload["message_type"] for _, payload in received] == [
+            "EnvMessage",
+            "EngineMessage",
+            "MetadataMessage",
+        ]
+        for _, payload in received:
+            assert payload["deployment_mode"] == "single_process"
+
+    def test_mp_report(self, usage_sink):
+        context = InitializeMPUsageContext(
+            MPServerConfig(), make_storage_manager_config()
+        )
+        assert context is not None
+        received = usage_sink.wait_for(2)
+        assert [payload["message_type"] for _, payload in received] == [
+            "EnvMessage",
+            "MPServerMessage",
+        ]
+        for path, payload in received:
+            assert path == "/context"
+            assert payload["deployment_mode"] == "mp_server"
+        assert len({payload["session_id"] for _, payload in received}) == 1
+
+    def test_continuous_report(self, usage_sink, monkeypatch):
+        monkeypatch.setenv("LMCACHE_USAGE_TRACK_INTERVAL", "0")
+        context = ContinuousUsageContext(make_metadata())
+        context.incr_or_send_stats(
+            StubStats(
+                interval_hit_tokens=7,
+                interval_stored_tokens=9,
+                interval_request_cache_lifespan=[1.0],
+            )
+        )
+        received = usage_sink.wait_for(2)
+        assert [path for path, _ in received] == ["/cache-usage", "/cache-lifespan"]
+        assert received[0][1]["interval_num_hit_tokens"] == 7
+        # Histogram keys are bucket bounds (stringified by JSON); the 1.0 s
+        # sample falls in the [1, 5) bin, keyed "5".
+        assert received[1][1]["cache_lifespan_histogram"]["5"] == 1
diff --git a/tests/test_utils.py b/tests/test_utils.py
new file mode 100644
index 0000000..72d07f2
--- /dev/null
+++ b/tests/test_utils.py
@@ -0,0 +1,687 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for lmcache.utils module."""
+
+# Standard
+from unittest.mock import patch
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import (
+    CacheEngineKey,
+    LayerCacheEngineKey,
+    _append_range_or_elements,
+    cdiv,
+    compress_slot_mapping,
+    convert_tokens_to_list,
+    decompress_slot_mapping,
+    get_version,
+    parse_cache_key,
+    parse_mixed_slot_mapping,
+    round_down,
+)
+
+
+# ============================================================
+# Math utility functions
+# ============================================================
+class TestCdiv:
+    def test_exact_division(self):
+        assert cdiv(10, 5) == 2
+
+    def test_ceiling_division(self):
+        assert cdiv(7, 3) == 3
+
+    def test_one_element(self):
+        assert cdiv(1, 1) == 1
+
+    def test_numerator_smaller_than_denominator(self):
+        assert cdiv(1, 3) == 1
+
+    def test_large_values(self):
+        assert cdiv(1000000001, 1000000000) == 2
+
+
+class TestRoundDown:
+    def test_exact_multiple(self):
+        assert round_down(10, 5) == 10
+
+    def test_not_exact_multiple(self):
+        assert round_down(7, 3) == 6
+
+    def test_smaller_than_y(self):
+        assert round_down(2, 5) == 0
+
+    def test_zero(self):
+        assert round_down(0, 5) == 0
+
+
+# ============================================================
+# Slot mapping compression / decompression
+# ============================================================
+class TestCompressSlotMapping:
+    def test_empty_list(self):
+        assert compress_slot_mapping([]) == []
+
+    def test_single_element(self):
+        assert compress_slot_mapping([5]) == [5]
+
+    def test_two_consecutive(self):
+        # Two consecutive elements should NOT be compressed
+        assert compress_slot_mapping([3, 4]) == [3, 4]
+
+    def test_three_or_more_consecutive(self):
+        assert compress_slot_mapping([1, 2, 3]) == [[1, 3]]
+        assert compress_slot_mapping([1, 2, 3, 4, 5]) == [[1, 5]]
+
+    def test_mixed(self):
+        result = compress_slot_mapping([1, 2, 3, 4, 5, 7, 8])
+        assert result == [[1, 5], 7, 8]
+
+    def test_non_consecutive_order_preserved(self):
+        # 1,2 is only 2 consecutive -> not compressed
+        # 2,4 not consecutive -> separate
+        result = compress_slot_mapping([5, 3, 1, 2, 4])
+        assert result == [5, 3, 1, 2, 4]
+
+    def test_multiple_ranges(self):
+        result = compress_slot_mapping([1, 2, 3, 4, 5, 9, 10, 11, 12])
+        assert result == [[1, 5], [9, 12]]
+
+    def test_all_non_consecutive(self):
+        result = compress_slot_mapping([1, 3, 5, 7])
+        assert result == [1, 3, 5, 7]
+
+
+class TestAppendRangeOrElements:
+    def test_single_element(self):
+        result = []
+        _append_range_or_elements(result, 5, 5)
+        assert result == [5]
+
+    def test_two_elements(self):
+        result = []
+        _append_range_or_elements(result, 5, 6)
+        assert result == [5, 6]
+
+    def test_three_or_more_elements(self):
+        result = []
+        _append_range_or_elements(result, 1, 5)
+        assert result == [[1, 5]]
+
+
+class TestDecompressSlotMapping:
+    def test_empty(self):
+        assert decompress_slot_mapping([]) == []
+
+    def test_single_int(self):
+        assert decompress_slot_mapping([5]) == [5]
+
+    def test_single_range(self):
+        assert decompress_slot_mapping([[1, 5]]) == [1, 2, 3, 4, 5]
+
+    def test_mixed(self):
+        assert decompress_slot_mapping([[1, 5], 7, 8]) == [1, 2, 3, 4, 5, 7, 8]
+
+    def test_roundtrip(self):
+        """Compress then decompress should return original."""
+        original = [1, 2, 3, 4, 5, 9, 10, 11, 12]
+        compressed = compress_slot_mapping(original)
+        assert decompress_slot_mapping(compressed) == original
+
+
+class TestParseMixedSlotMapping:
+    def test_simple_numbers(self):
+        slots, err = parse_mixed_slot_mapping("1,2,3,17,19")
+        assert err is None
+        assert slots == [1, 2, 3, 17, 19]
+
+    def test_range_format(self):
+        slots, err = parse_mixed_slot_mapping("[9,12]")
+        assert err is None
+        assert slots == [9, 10, 11, 12]
+
+    def test_mixed_format(self):
+        slots, err = parse_mixed_slot_mapping("1,2,3,[9,12],17,19")
+        assert err is None
+        assert slots == [1, 2, 3, 9, 10, 11, 12, 17, 19]
+
+    def test_whitespace_handling(self):
+        slots, err = parse_mixed_slot_mapping(" 1 , 2 , [3 , 5] ")
+        assert err is None
+        assert slots == [1, 2, 3, 4, 5]
+
+    def test_nested_brackets_error(self):
+        slots, err = parse_mixed_slot_mapping("[[1,2]]")
+        assert slots is None
+        assert err is not None
+        assert "error" in err
+
+    def test_unmatched_closing_bracket(self):
+        slots, err = parse_mixed_slot_mapping("1,2]")
+        assert slots is None
+        assert err is not None
+
+    def test_unclosed_bracket(self):
+        slots, err = parse_mixed_slot_mapping("[1,2")
+        assert slots is None
+        assert err is not None
+
+    def test_invalid_range_start_gt_end(self):
+        slots, err = parse_mixed_slot_mapping("[5,2]")
+        assert slots is None
+        assert err is not None
+
+    def test_invalid_format(self):
+        slots, err = parse_mixed_slot_mapping("abc")
+        assert slots is None
+        assert err is not None
+
+    def test_empty_string(self):
+        slots, err = parse_mixed_slot_mapping("")
+        assert err is None
+        assert slots == []
+
+
+# ============================================================
+# Version
+# ============================================================
+class TestGetVersion:
+    def test_version_with_values(self):
+        with (
+            patch("lmcache.utils.VERSION", "1.0.0"),
+            patch("lmcache.utils.COMMIT_ID", "abc123"),
+        ):
+            assert get_version() == "1.0.0-abc123"
+
+    def test_version_empty(self):
+        with patch("lmcache.utils.VERSION", ""), patch("lmcache.utils.COMMIT_ID", ""):
+            assert get_version() == "NA-NA"
+
+    def test_version_partial(self):
+        with (
+            patch("lmcache.utils.VERSION", "2.0"),
+            patch("lmcache.utils.COMMIT_ID", ""),
+        ):
+            assert get_version() == "2.0-NA"
+
+
+# ============================================================
+# convert_tokens_to_list
+# ============================================================
+class TestConvertTokensToList:
+    def test_none_input(self):
+        assert convert_tokens_to_list(None, 0, 5) == []
+
+    def test_tensor_input(self):
+        t = torch.tensor([10, 20, 30, 40, 50])
+        result = convert_tokens_to_list(t, 1, 3)
+        assert result == [20, 30, 40]
+
+    def test_list_input(self):
+        tokens = [10, 20, 30, 40, 50]
+        result = convert_tokens_to_list(tokens, 0, 2)
+        assert result == [10, 20, 30]
+
+    def test_full_range(self):
+        t = torch.tensor([1, 2, 3])
+        result = convert_tokens_to_list(t, 0, 2)
+        assert result == [1, 2, 3]
+
+
+# ============================================================
+# CacheEngineKey
+# ============================================================
+class TestCacheEngineKey:
+    @pytest.fixture()
+    def basic_key(self):
+        return CacheEngineKey(
+            model_name="test_model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xABCD,
+            dtype=torch.float16,
+        )
+
+    @pytest.fixture()
+    def key_with_tags(self):
+        return CacheEngineKey(
+            model_name="model_a",
+            world_size=2,
+            worker_id=1,
+            chunk_hash=0xFF,
+            dtype=torch.bfloat16,
+            request_configs={
+                "lmcache.tag.lora": "adapter1",
+                "lmcache.tag.version": "v2",
+            },
+        )
+
+    def test_hash_and_eq(self, basic_key):
+        key2 = CacheEngineKey(
+            model_name="test_model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xABCD,
+            dtype=torch.float16,
+        )
+        assert basic_key == key2
+        assert hash(basic_key) == hash(key2)
+
+    def test_not_equal_different_hash(self, basic_key):
+        key2 = CacheEngineKey(
+            model_name="test_model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0x1234,
+            dtype=torch.float16,
+        )
+        assert basic_key != key2
+
+    def test_not_equal_different_type(self, basic_key):
+        assert basic_key != "not_a_key"
+
+    def test_to_string_basic(self, basic_key):
+        s = basic_key.to_string()
+        assert "test_model" in s
+        assert "abcd" in s
+        assert "half" in s
+
+    def test_to_string_with_tags(self, key_with_tags):
+        s = key_with_tags.to_string()
+        assert "lora%adapter1" in s
+        assert "version%v2" in s
+
+    def test_from_string_roundtrip(self, basic_key):
+        s = basic_key.to_string()
+        restored = CacheEngineKey.from_string(s)
+        assert restored == basic_key
+
+    def test_from_string_with_tags_roundtrip(self, key_with_tags):
+        s = key_with_tags.to_string()
+        restored = CacheEngineKey.from_string(s)
+        assert restored == key_with_tags
+
+    def test_from_string_invalid(self):
+        with pytest.raises(ValueError):
+            CacheEngineKey.from_string("invalid")
+
+    def test_from_string_invalid_tag_format(self):
+        with pytest.raises(ValueError):
+            CacheEngineKey.from_string("model@1@0@abcd@half@badtag")
+
+    def test_to_dict_and_from_dict(self, basic_key):
+        d = basic_key.to_dict()
+        assert d["__type__"] == "CacheEngineKey"
+        restored = CacheEngineKey.from_dict(d)
+        assert restored == basic_key
+
+    def test_to_dict_with_tags(self, key_with_tags):
+        d = key_with_tags.to_dict()
+        assert "request_configs" in d
+
+    def test_from_dict_invalid_tag(self):
+        d = {
+            "model_name": "m",
+            "world_size": 1,
+            "worker_id": 0,
+            "chunk_hash": 0xAB,
+            "dtype": "half",
+            "request_configs": ["badformat"],
+        }
+        with pytest.raises(ValueError):
+            CacheEngineKey.from_dict(d)
+
+    def test_with_new_worker_id(self, basic_key):
+        new_key = basic_key.with_new_worker_id(42)
+        assert new_key.worker_id == 42
+        assert new_key.model_name == basic_key.model_name
+        assert new_key.chunk_hash == basic_key.chunk_hash
+
+    def test_split_layers(self, basic_key):
+        layers = basic_key.split_layers(3)
+        assert len(layers) == 3
+        for i, layer_key in enumerate(layers):
+            assert isinstance(layer_key, LayerCacheEngineKey)
+            assert layer_key.layer_id == i
+            assert layer_key.model_name == "test_model"
+
+    def test_get_first_layer(self, basic_key):
+        first = basic_key.get_first_layer()
+        assert isinstance(first, LayerCacheEngineKey)
+        assert first.layer_id == 0
+        assert first.model_name == basic_key.model_name
+
+    def test_chunk_hash_hex(self, basic_key):
+        assert basic_key.chunk_hash_hex == "abcd"
+
+    def test_chunk_hash_hex_bytes(self):
+        key = CacheEngineKey(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xFF,
+            dtype=torch.float16,
+        )
+        # Manually set chunk_hash to bytes for coverage
+        object.__setattr__(key, "chunk_hash", b"\xab\xcd")
+        assert key.chunk_hash_hex == "abcd"
+
+    def test_unsupported_dtype_raises(self):
+        with pytest.raises(ValueError, match="Unsupported"):
+            CacheEngineKey(
+                model_name="m",
+                world_size=1,
+                worker_id=0,
+                chunk_hash=0x1,
+                dtype=torch.complex64,
+            )
+
+    def test_no_tags_when_no_tag_prefix(self):
+        key = CacheEngineKey(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0x1,
+            dtype=torch.float16,
+            request_configs={"some_config": "value"},
+        )
+        assert key.tags is None
+
+
+# ============================================================
+# LayerCacheEngineKey
+# ============================================================
+class TestLayerCacheEngineKey:
+    @pytest.fixture()
+    def layer_key(self):
+        return LayerCacheEngineKey(
+            model_name="model_b",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xBEEF,
+            dtype=torch.float16,
+            layer_id=5,
+        )
+
+    def test_hash_includes_layer_id(self, layer_key):
+        other = LayerCacheEngineKey(
+            model_name="model_b",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xBEEF,
+            dtype=torch.float16,
+            layer_id=6,
+        )
+        assert layer_key != other
+        assert hash(layer_key) != hash(other)
+
+    def test_eq_same_layer(self, layer_key):
+        same = LayerCacheEngineKey(
+            model_name="model_b",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xBEEF,
+            dtype=torch.float16,
+            layer_id=5,
+        )
+        assert layer_key == same
+
+    def test_eq_different_base_key(self, layer_key):
+        different = LayerCacheEngineKey(
+            model_name="other_model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xBEEF,
+            dtype=torch.float16,
+            layer_id=5,
+        )
+        assert layer_key != different
+
+    def test_to_string(self, layer_key):
+        s = layer_key.to_string()
+        assert "model_b" in s
+        assert "beef" in s
+        assert "@5" in s
+
+    def test_to_string_with_tags(self):
+        key = LayerCacheEngineKey(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xAB,
+            dtype=torch.float16,
+            layer_id=2,
+            request_configs={"lmcache.tag.foo": "bar"},
+        )
+        s = key.to_string()
+        assert "foo%bar" in s
+
+    def test_from_string_roundtrip(self, layer_key):
+        s = layer_key.to_string()
+        restored = LayerCacheEngineKey.from_string(s)
+        assert restored == layer_key
+
+    def test_from_string_with_tags(self):
+        key = LayerCacheEngineKey(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xAB,
+            dtype=torch.float16,
+            layer_id=3,
+            request_configs={"lmcache.tag.t1": "v1"},
+        )
+        s = key.to_string()
+        restored = LayerCacheEngineKey.from_string(s)
+        assert restored == key
+
+    def test_from_string_invalid(self):
+        with pytest.raises(ValueError):
+            LayerCacheEngineKey.from_string("a@b")
+
+    def test_from_string_invalid_tag(self):
+        with pytest.raises(ValueError):
+            LayerCacheEngineKey.from_string("m@1@0@ab@half@3@badtag")
+
+    def test_split_layers(self, layer_key):
+        layers = layer_key.split_layers(4)
+        assert len(layers) == 4
+        for i, lk in enumerate(layers):
+            assert lk.layer_id == i
+
+
+# ============================================================
+# parse_cache_key
+# ============================================================
+class TestCacheKeyParsing:
+    def test_parse_cache_engine_key(self):
+        key = CacheEngineKey(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xABC,
+            dtype=torch.float16,
+        )
+        s = key.to_string()
+        parsed = parse_cache_key(s)
+        assert isinstance(parsed, CacheEngineKey)
+        assert parsed == key
+
+    @pytest.mark.xfail(
+        reason="parse_cache_key bug: cannot parse LayerCacheEngineKey with dtype"
+    )
+    def test_parse_layer_cache_engine_key(self):
+        key = LayerCacheEngineKey(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=0xABC,
+            dtype=torch.float16,
+            layer_id=7,
+        )
+        s = key.to_string()
+        parsed = parse_cache_key(s)
+        assert isinstance(parsed, LayerCacheEngineKey)
+        assert parsed == key
+
+    """
+    Tests for CacheEngineKey and LayerCacheEngineKey parsing.
+    """
+
+    def test_parse_cache_key_without_tags(self):
+        """
+        Test parsing CacheEngineKey without tags.
+        """
+        key_str = "model@2@0@abc123@bfloat16"
+        result = parse_cache_key(key_str)
+
+        assert isinstance(result, CacheEngineKey)
+        assert not isinstance(result, LayerCacheEngineKey)
+        assert result.model_name == "model"
+        assert result.world_size == 2
+        assert result.worker_id == 0
+        assert result.chunk_hash == 0xABC123
+        assert result.dtype == torch.bfloat16
+
+    def test_parse_cache_key_with_tags(self):
+        """
+        Test parsing CacheEngineKey with tags.
+        """
+        key_str = "model@2@0@abc123@bfloat16@mytag%myvalue@othertag%othervalue"
+        result = parse_cache_key(key_str)
+
+        # This should be CacheEngineKey, not LayerCacheEngineKey
+        assert isinstance(result, CacheEngineKey)
+        assert not isinstance(result, LayerCacheEngineKey)
+        assert result.model_name == "model"
+        assert result.world_size == 2
+        assert result.worker_id == 0
+        assert result.chunk_hash == 0xABC123
+        assert result.dtype == torch.bfloat16
+        assert result.tags is not None
+        assert ("mytag", "myvalue") in result.tags
+        assert ("othertag", "othervalue") in result.tags
+
+    def test_parse_layer_cache_key_without_tags(self):
+        """
+        Test parsing LayerCacheEngineKey without tags.
+        """
+        key_str = "model@2@0@abc123@bfloat16@5"
+        result = parse_cache_key(key_str)
+
+        assert isinstance(result, LayerCacheEngineKey)
+        assert result.model_name == "model"
+        assert result.world_size == 2
+        assert result.worker_id == 0
+        assert result.chunk_hash == 0xABC123
+        assert result.dtype == torch.bfloat16
+        assert result.layer_id == 5
+
+    def test_parse_layer_cache_key_with_tags(self):
+        """
+        Test parsing LayerCacheEngineKey with tags - demonstrates the bug.
+        """
+        key_str = "model@2@0@abc123@bfloat16@5@mytag%myvalue"
+        result = parse_cache_key(key_str)
+
+        # This should be LayerCacheEngineKey with layer_id=5 and tags
+        assert isinstance(result, LayerCacheEngineKey)
+        assert result.model_name == "model"
+        assert result.world_size == 2
+        assert result.worker_id == 0
+        assert result.chunk_hash == 0xABC123
+        assert result.dtype == torch.bfloat16
+        assert result.layer_id == 5
+        assert result.tags is not None
+        assert ("mytag", "myvalue") in result.tags
+
+    def test_roundtrip_cache_engine_key_without_tags(self):
+        """
+        Test that CacheEngineKey serialization round-trips correctly.
+        """
+        original = CacheEngineKey(
+            model_name="test-model",
+            world_size=4,
+            worker_id=1,
+            chunk_hash=0xDEADBEEF,
+            dtype=torch.float16,
+            request_configs=None,
+        )
+
+        key_str = original.to_string()
+        parsed = parse_cache_key(key_str)
+
+        assert isinstance(parsed, CacheEngineKey)
+        assert not isinstance(parsed, LayerCacheEngineKey)
+        assert parsed == original
+
+    def test_roundtrip_cache_engine_key_with_tags(self):
+        """
+        Test that CacheEngineKey with tags serialization round-trips correctly.
+        """
+        original = CacheEngineKey(
+            model_name="test-model",
+            world_size=4,
+            worker_id=1,
+            chunk_hash=0xDEADBEEF,
+            dtype=torch.float32,
+            request_configs={
+                "lmcache.tag.user": "alice",
+                "lmcache.tag.session": "xyz789",
+            },
+        )
+
+        key_str = original.to_string()
+        parsed = parse_cache_key(key_str)
+
+        assert isinstance(parsed, CacheEngineKey)
+        assert not isinstance(parsed, LayerCacheEngineKey)
+        assert parsed == original
+
+    def test_roundtrip_layer_cache_engine_key_without_tags(self):
+        """
+        Test that LayerCacheEngineKey serialization round-trips correctly.
+        """
+        original = LayerCacheEngineKey(
+            model_name="test-model",
+            world_size=4,
+            worker_id=1,
+            chunk_hash=0xDEADBEEF,
+            dtype=torch.bfloat16,
+            request_configs=None,
+            layer_id=7,
+        )
+
+        key_str = original.to_string()
+        parsed = parse_cache_key(key_str)
+
+        assert isinstance(parsed, LayerCacheEngineKey)
+        assert parsed == original
+        assert parsed.layer_id == 7
+
+    def test_roundtrip_layer_cache_engine_key_with_tags(self):
+        """
+        Test that LayerCacheEngineKey with tags serialization round-trips correctly.
+        """
+        original = LayerCacheEngineKey(
+            model_name="test-model",
+            world_size=4,
+            worker_id=1,
+            chunk_hash=0xDEADBEEF,
+            dtype=torch.bfloat16,
+            request_configs={
+                "lmcache.tag.user": "bob",
+                "lmcache.tag.priority": "high",
+            },
+            layer_id=3,
+        )
+
+        key_str = original.to_string()
+        parsed = parse_cache_key(key_str)
+
+        assert isinstance(parsed, LayerCacheEngineKey)
+        assert parsed == original
+        assert parsed.layer_id == 3
diff --git a/tests/tools/test_cache_simulator.py b/tests/tools/test_cache_simulator.py
new file mode 100644
index 0000000..e4e2878
--- /dev/null
+++ b/tests/tools/test_cache_simulator.py
@@ -0,0 +1,332 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the LMCache cache simulator tool."""
+
+# Standard
+from pathlib import Path
+import json
+import tempfile
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.tools.cache_simulator.lru_cache import LRUCache, LRUCacheFast
+from lmcache.tools.cache_simulator.simulator import (
+    compute_kv_bytes_per_chunk,
+    load_lookup_events,
+    simulate,
+)
+
+# ---------------------------------------------------------------------------
+# LRUCacheFast
+# ---------------------------------------------------------------------------
+
+
+class TestLRUCacheFast:
+    def test_basic_insert_and_contains(self):
+        cache = LRUCacheFast(3)
+        cache.insert("a")
+        assert cache.contains("a")
+        assert not cache.contains("b")
+
+    def test_evicts_lru_when_full(self):
+        cache = LRUCacheFast(2)
+        cache.insert("a")
+        cache.insert("b")
+        cache.insert("c")  # should evict "a"
+        assert not cache.contains("a")
+        assert cache.contains("b")
+        assert cache.contains("c")
+        assert cache.eviction_count == 1
+
+    def test_access_refreshes_lru_order(self):
+        cache = LRUCacheFast(2)
+        cache.insert("a")
+        cache.insert("b")
+        cache.access("a")  # "a" is now MRU; "b" is LRU
+        cache.insert("c")  # should evict "b"
+        assert cache.contains("a")
+        assert not cache.contains("b")
+        assert cache.contains("c")
+
+    def test_insert_existing_key_does_not_grow(self):
+        cache = LRUCacheFast(2)
+        cache.insert("a")
+        cache.insert("a")
+        assert len(cache) == 1
+        assert cache.eviction_count == 0
+
+    def test_capacity_one(self):
+        cache = LRUCacheFast(1)
+        cache.insert("a")
+        cache.insert("b")
+        assert not cache.contains("a")
+        assert cache.contains("b")
+        assert cache.eviction_count == 1
+
+    def test_invalid_capacity_raises(self):
+        with pytest.raises(ValueError):
+            LRUCacheFast(0)
+
+
+# ---------------------------------------------------------------------------
+# LRUCache
+# ---------------------------------------------------------------------------
+
+
+class TestLRUCache:
+    def test_basic_insert_and_contains(self):
+        cache = LRUCache(3)
+        cache.insert("a")
+        assert cache.contains("a")
+        assert not cache.contains("z")
+
+    def test_evicts_lru_when_full(self):
+        cache = LRUCache(2)
+        cache.insert("a")
+        cache.insert("b")
+        cache.insert("c")  # evicts "a"
+        assert not cache.contains("a")
+        assert cache.eviction_count == 1
+
+    def test_position_mru_is_zero(self):
+        cache = LRUCache(3)
+        cache.insert("a")
+        cache.insert("b")
+        cache.insert("c")
+        # "c" was inserted last → MRU → position 0
+        assert cache.position("c") == 0
+        # "a" was inserted first → LRU → position 2
+        assert cache.position("a") == 2
+
+    def test_access_moves_to_mru(self):
+        cache = LRUCache(3)
+        cache.insert("a")
+        cache.insert("b")
+        cache.insert("c")
+        cache.access("a")  # "a" becomes MRU
+        assert cache.position("a") == 0
+        assert cache.position("c") == 1
+        assert cache.position("b") == 2
+
+    def test_invalid_capacity_raises(self):
+        with pytest.raises(ValueError):
+            LRUCache(0)
+
+
+# ---------------------------------------------------------------------------
+# compute_kv_bytes_per_chunk
+# ---------------------------------------------------------------------------
+
+
+class TestComputeKvBytesPerChunk:
+    def test_float16(self):
+        event = {"shapes": [[32, 256, 128]], "dtypes": ["float16"]}
+        assert compute_kv_bytes_per_chunk(event) == 32 * 256 * 128 * 2
+
+    def test_multiple_tensors(self):
+        # Two tensors: one float16, one float8_e4m3fn
+        event = {
+            "shapes": [[4, 256, 64], [4, 256, 64]],
+            "dtypes": ["float16", "float8_e4m3fn"],
+        }
+        expected = 4 * 256 * 64 * 2 + 4 * 256 * 64 * 1
+        assert compute_kv_bytes_per_chunk(event) == expected
+
+    def test_empty_shapes_returns_zero(self):
+        assert compute_kv_bytes_per_chunk({"shapes": [], "dtypes": []}) == 0
+
+    def test_missing_fields_returns_zero(self):
+        assert compute_kv_bytes_per_chunk({}) == 0
+
+
+# ---------------------------------------------------------------------------
+# load_lookup_events
+# ---------------------------------------------------------------------------
+
+
+class TestLoadLookupEvents:
+    def _write_jsonl(self, lines):
+        f = tempfile.NamedTemporaryFile("w", suffix=".jsonl", delete=False, dir="/tmp")
+        for line in lines:
+            f.write(json.dumps(line) + "\n")
+        f.close()
+        return Path(f.name)
+
+    def test_loads_and_sorts_by_timestamp(self):
+        path = self._write_jsonl(
+            [
+                {
+                    "timestamp": 2.0,
+                    "chunk_hashes": ["0xbb"],
+                    "seq_len": 256,
+                    "chunk_size": 256,
+                },
+                {
+                    "timestamp": 1.0,
+                    "chunk_hashes": ["0xaa"],
+                    "seq_len": 256,
+                    "chunk_size": 256,
+                },
+            ]
+        )
+        events = load_lookup_events([path])
+        assert events[0]["chunk_hashes"] == ["0xaa"]
+        assert events[1]["chunk_hashes"] == ["0xbb"]
+        path.unlink()
+
+    def test_model_filter(self):
+        path = self._write_jsonl(
+            [
+                {
+                    "timestamp": 1.0,
+                    "model_name": "A",
+                    "chunk_hashes": [],
+                    "seq_len": 0,
+                    "chunk_size": 256,
+                },
+                {
+                    "timestamp": 2.0,
+                    "model_name": "B",
+                    "chunk_hashes": [],
+                    "seq_len": 0,
+                    "chunk_size": 256,
+                },
+            ]
+        )
+        events = load_lookup_events([path], model="A")
+        assert len(events) == 1
+        assert events[0]["model_name"] == "A"
+        path.unlink()
+
+    def test_max_samples(self):
+        path = self._write_jsonl(
+            [
+                {
+                    "timestamp": float(i),
+                    "chunk_hashes": [],
+                    "seq_len": 0,
+                    "chunk_size": 256,
+                }
+                for i in range(10)
+            ]
+        )
+        events = load_lookup_events([path], max_samples=3)
+        assert len(events) == 3
+        path.unlink()
+
+    def test_skips_malformed_lines(self):
+        f = tempfile.NamedTemporaryFile("w", suffix=".jsonl", delete=False, dir="/tmp")
+        f.write(
+            '{"timestamp": 1.0, "chunk_hashes": [], "seq_len": 0, "chunk_size": 256}\n'
+        )
+        f.write("not json\n")
+        f.write(
+            '{"timestamp": 2.0, "chunk_hashes": [], "seq_len": 0, "chunk_size": 256}\n'
+        )
+        f.close()
+        # Standard
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            events = load_lookup_events([Path(f.name)])
+        assert len(events) == 2
+        Path(f.name).unlink()
+
+
+# ---------------------------------------------------------------------------
+# simulate
+# ---------------------------------------------------------------------------
+
+
+class TestSimulate:
+    """Core simulation correctness tests."""
+
+    def _make_events(self, specs):
+        """Build minimal event dicts from (chunk_hashes, seq_len) pairs."""
+        return [
+            {"chunk_hashes": hashes, "seq_len": seq_len, "chunk_size": 256}
+            for hashes, seq_len in specs
+        ]
+
+    def test_cold_cache_zero_hits(self):
+        events = self._make_events(
+            [
+                (["0xaa", "0xbb"], 600),
+            ]
+        )
+        res = simulate(events, cache_capacity_bytes=100, kv_bytes_per_chunk=1)
+        assert res["token_hit_rate"] == 0.0
+        assert res["total_hit_tokens"] == 0
+        assert res["total_tokens"] == 600
+
+    def test_second_identical_request_hits(self):
+        # r1: cold miss; r2: full prefix hit (2 chunks × 256 = 512 tokens)
+        events = self._make_events(
+            [
+                (["0xaa", "0xbb"], 600),
+                (["0xaa", "0xbb"], 600),
+            ]
+        )
+        res = simulate(events, cache_capacity_bytes=100, kv_bytes_per_chunk=1)
+        assert res["total_hit_tokens"] == 512
+        assert res["total_tokens"] == 1200
+        assert abs(res["token_hit_rate"] - 512 / 1200) < 1e-9
+
+    def test_prefix_semantics_breaks_on_first_miss(self):
+        # r1 populates 0xaa, 0xbb, 0xcc
+        # r2: 0xaa hits, 0xdd misses → prefix=1; 0xbb is in cache but not counted
+        events = self._make_events(
+            [
+                (["0xaa", "0xbb", "0xcc"], 768),
+                (["0xaa", "0xdd", "0xbb"], 768),
+            ]
+        )
+        res = simulate(events, cache_capacity_bytes=100, kv_bytes_per_chunk=1)
+        # Only 0xaa is a prefix hit in r2 → 1 × 256 = 256 hit tokens
+        assert res["total_hit_tokens"] == 256
+
+    def test_tail_tokens_always_miss(self):
+        # seq_len=300, chunk_size=256 → 1 full chunk + 44 tail tokens
+        # On second request the full chunk hits but tail is always a miss
+        events = self._make_events(
+            [
+                (["0xaa"], 300),
+                (["0xaa"], 300),
+            ]
+        )
+        res = simulate(events, cache_capacity_bytes=100, kv_bytes_per_chunk=1)
+        # hit tokens = 256, total = 600 → tail (44 tokens per request) is miss
+        assert res["total_hit_tokens"] == 256
+        assert res["total_tokens"] == 600
+
+    def test_eviction_reduces_hits(self):
+        # capacity = 1 chunk; insert 0xaa then 0xbb evicts 0xaa
+        events = self._make_events(
+            [
+                (["0xaa"], 256),  # populates 0xaa
+                (["0xbb"], 256),  # evicts 0xaa, populates 0xbb
+                (["0xaa"], 256),  # 0xaa was evicted → miss; evicts 0xbb
+            ]
+        )
+        res = simulate(events, cache_capacity_bytes=1, kv_bytes_per_chunk=1)
+        assert res["total_hit_tokens"] == 0
+        assert res["eviction_count"] == 2
+
+    def test_fast_mode_matches_normal_token_hit_rate(self):
+        events = self._make_events(
+            [
+                (["0xaa", "0xbb"], 600),
+                (["0xaa", "0xbb"], 600),
+                (["0xcc"], 300),
+            ]
+        )
+        cap, bpc = 100, 1
+        res_normal = simulate(events, cap, bpc, fast=False)
+        res_fast = simulate(events, cap, bpc, fast=True)
+        assert abs(res_normal["token_hit_rate"] - res_fast["token_hit_rate"]) < 1e-9
+
+    def test_invalid_kv_bytes_raises(self):
+        with pytest.raises(ValueError):
+            simulate([], cache_capacity_bytes=100, kv_bytes_per_chunk=0)
diff --git a/tests/tools/test_controller_zmq_benchmark.py b/tests/tools/test_controller_zmq_benchmark.py
new file mode 100644
index 0000000..9d54408
--- /dev/null
+++ b/tests/tools/test_controller_zmq_benchmark.py
@@ -0,0 +1,562 @@
+#!/usr/bin/env python3
+"""
+Tests for LMCache Controller ZMQ Benchmark Tool
+"""
+
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from typing import Dict
+from unittest.mock import AsyncMock, MagicMock, patch
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.tools.controller_benchmark.benchmark import ZMQControllerBenchmark
+from lmcache.tools.controller_benchmark.config import ZMQBenchmarkConfig
+from lmcache.tools.controller_benchmark.handlers import OPERATION_HANDLERS
+from lmcache.tools.controller_benchmark.handlers.admit import AdmitHandler
+from lmcache.tools.controller_benchmark.handlers.base import (
+    OperationHandler,
+    SocketType,
+)
+from lmcache.tools.controller_benchmark.handlers.deregister import DeregisterHandler
+from lmcache.tools.controller_benchmark.handlers.evict import EvictHandler
+from lmcache.tools.controller_benchmark.handlers.heartbeat import HeartbeatHandler
+from lmcache.tools.controller_benchmark.handlers.p2p_lookup import P2PLookupHandler
+from lmcache.tools.controller_benchmark.handlers.register import RegisterHandler
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    BatchedP2PLookupMsg,
+    DeRegisterMsg,
+    HeartbeatMsg,
+    OpType,
+    RegisterMsg,
+)
+
+logger = init_logger(__name__)
+
+
+class TestZMQBenchmarkConfig:
+    """Test ZMQBenchmarkConfig class"""
+
+    def test_default_operations(self):
+        """Test default operation distribution"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url=None,
+            duration=60,
+            batch_size=50,
+            num_instances=10,
+            num_workers=5,
+            num_locations=3,
+            num_keys=1000,
+        )
+
+        assert "admit" in config.operations
+        assert "evict" in config.operations
+        assert "heartbeat" in config.operations
+        assert abs(sum(config.operations.values()) - 100.0) < 0.01
+
+    def test_custom_operations(self):
+        """Test custom operation distribution"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url="localhost:8101",
+            duration=60,
+            batch_size=50,
+            num_instances=10,
+            num_workers=5,
+            num_locations=3,
+            num_keys=1000,
+            operations={"admit": 80.0, "evict": 20.0},
+        )
+
+        assert config.operations["admit"] == 80.0
+        assert config.operations["evict"] == 20.0
+        assert config.controller_pull_url == "localhost:8100"
+        assert config.controller_reply_url == "localhost:8101"
+        assert config.duration == 60
+        assert config.batch_size == 50
+        assert config.num_instances == 10
+        assert config.num_workers == 5
+        assert config.num_locations == 3
+        assert config.num_keys == 1000
+
+    def test_invalid_operation_percentage(self):
+        """Test invalid operation percentage sum"""
+        with pytest.raises(ValueError, match="must sum to 100"):
+            ZMQBenchmarkConfig(
+                controller_pull_url="localhost:8100",
+                controller_reply_url=None,
+                duration=60,
+                batch_size=50,
+                num_instances=10,
+                num_workers=5,
+                num_locations=3,
+                num_keys=1000,
+                operations={"admit": 50, "evict": 60},  # Sum > 100
+            )
+
+
+class TestOperationHandlers:
+    """Test operation handlers (Strategy Pattern)"""
+
+    @pytest.fixture
+    def controller_zmq_benchmark(self):
+        """Create a benchmark instance for testing"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url="localhost:8101",
+            duration=1,
+            batch_size=10,
+            num_instances=2,
+            num_workers=2,
+            num_locations=2,
+            num_keys=10,
+            num_hashes=5,
+            register_first=False,
+        )
+        return ZMQControllerBenchmark(config)
+
+    @pytest.fixture
+    def test_data(self, controller_zmq_benchmark):
+        """Generate test data"""
+        return controller_zmq_benchmark.generate_test_data()
+
+    def test_admit_handler(self, controller_zmq_benchmark, test_data):
+        """Test AdmitHandler functionality"""
+        handler = AdmitHandler()
+        msg = handler.create_message(controller_zmq_benchmark, test_data)
+
+        assert isinstance(msg, BatchedKVOperationMsg)
+        assert len(msg.operations) == controller_zmq_benchmark.config.batch_size
+        assert all(op.op_type == OpType.ADMIT for op in msg.operations)
+        assert (
+            handler.get_message_count(controller_zmq_benchmark)
+            == controller_zmq_benchmark.config.batch_size
+        )
+        assert handler.socket_type == SocketType.PUSH
+
+    def test_evict_handler(self, controller_zmq_benchmark, test_data):
+        """Test EvictHandler functionality"""
+        handler = EvictHandler()
+        msg = handler.create_message(controller_zmq_benchmark, test_data)
+
+        assert isinstance(msg, BatchedKVOperationMsg)
+        assert len(msg.operations) == controller_zmq_benchmark.config.batch_size
+        assert all(op.op_type == OpType.EVICT for op in msg.operations)
+        assert (
+            handler.get_message_count(controller_zmq_benchmark)
+            == controller_zmq_benchmark.config.batch_size
+        )
+        assert handler.socket_type == SocketType.PUSH
+
+    def test_heartbeat_handler(self, controller_zmq_benchmark, test_data):
+        """Test HeartbeatHandler functionality"""
+        handler = HeartbeatHandler()
+        msg = handler.create_message(controller_zmq_benchmark, test_data)
+
+        assert isinstance(msg, HeartbeatMsg)
+        assert handler.get_message_count(controller_zmq_benchmark) == 1
+        assert handler.socket_type == SocketType.HEARTBEAT
+
+    def test_register_handler(self, controller_zmq_benchmark, test_data):
+        """Test RegisterHandler functionality"""
+        handler = RegisterHandler()
+        msg = handler.create_message(controller_zmq_benchmark, test_data)
+
+        assert isinstance(msg, RegisterMsg)
+        assert handler.get_message_count(controller_zmq_benchmark) == 1
+        assert handler.socket_type == SocketType.DEALER
+
+    def test_deregister_handler(self, controller_zmq_benchmark, test_data):
+        """Test DeregisterHandler functionality"""
+        handler = DeregisterHandler()
+        msg = handler.create_message(controller_zmq_benchmark, test_data)
+
+        assert isinstance(msg, DeRegisterMsg)
+        assert handler.get_message_count(controller_zmq_benchmark) == 1
+        assert handler.socket_type == SocketType.PUSH
+
+    def test_p2p_lookup_handler(self, controller_zmq_benchmark, test_data):
+        """Test P2PLookupHandler functionality"""
+        handler = P2PLookupHandler()
+        msg = handler.create_message(controller_zmq_benchmark, test_data)
+
+        assert isinstance(msg, BatchedP2PLookupMsg)
+        assert len(msg.hashes) == controller_zmq_benchmark.config.num_hashes
+        assert (
+            handler.get_message_count(controller_zmq_benchmark)
+            == controller_zmq_benchmark.config.num_hashes
+        )
+        assert handler.socket_type == SocketType.DEALER
+
+    def test_operation_handler_registry(self):
+        """Test operation handler registry"""
+        assert "admit" in OPERATION_HANDLERS
+        assert "evict" in OPERATION_HANDLERS
+        assert "heartbeat" in OPERATION_HANDLERS
+        assert "register" in OPERATION_HANDLERS
+        assert "deregister" in OPERATION_HANDLERS
+        assert "p2p_lookup" in OPERATION_HANDLERS
+
+        for handler in OPERATION_HANDLERS.values():
+            assert isinstance(handler, OperationHandler)
+
+
+class TestZMQControllerBenchmark:
+    """Test ZMQControllerBenchmark class"""
+
+    @pytest.fixture
+    def config(self):
+        """Create test configuration"""
+        return ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url="localhost:8101",
+            duration=1,
+            batch_size=10,
+            num_instances=2,
+            num_workers=2,
+            num_locations=2,
+            num_keys=10,
+            num_hashes=5,
+            register_first=False,
+        )
+
+    @pytest.fixture
+    def zmq_benchmark(self, config):
+        """Create benchmark instance"""
+        return ZMQControllerBenchmark(config)
+
+    def test_generate_test_data(self, zmq_benchmark):
+        """Test test data generation"""
+        test_data = zmq_benchmark.generate_test_data()
+
+        assert hasattr(test_data, "instances")
+        assert hasattr(test_data, "workers")
+        assert hasattr(test_data, "locations")
+        assert hasattr(test_data, "keys")
+
+        assert len(test_data.instances) == zmq_benchmark.config.num_instances
+        assert len(test_data.workers) == zmq_benchmark.config.num_workers
+        assert len(test_data.locations) == zmq_benchmark.config.num_locations
+        assert len(test_data.keys) == zmq_benchmark.config.num_keys
+
+    def test_sequence_number_increment(self, zmq_benchmark):
+        """Test sequence number monotonic increment"""
+        instance_id = "instance_0"
+        worker_id = 0
+        location = "location_0"
+
+        seq1 = zmq_benchmark.get_next_sequence_number(instance_id, worker_id, location)
+        seq2 = zmq_benchmark.get_next_sequence_number(instance_id, worker_id, location)
+        seq3 = zmq_benchmark.get_next_sequence_number(instance_id, worker_id, location)
+
+        assert seq1 == 0
+        assert seq2 == 1
+        assert seq3 == 2
+
+    def test_sequence_number_isolation(self, zmq_benchmark):
+        """Test sequence number isolation between different keys"""
+        instance1, worker1, loc1 = "instance_0", 0, "location_0"
+        instance2, worker2, loc2 = "instance_1", 1, "location_1"
+
+        seq1a = zmq_benchmark.get_next_sequence_number(instance1, worker1, loc1)
+        seq2a = zmq_benchmark.get_next_sequence_number(instance2, worker2, loc2)
+        seq1b = zmq_benchmark.get_next_sequence_number(instance1, worker1, loc1)
+        seq2b = zmq_benchmark.get_next_sequence_number(instance2, worker2, loc2)
+
+        assert seq1a == 0
+        assert seq2a == 0
+        assert seq1b == 1
+        assert seq2b == 1
+
+    @pytest.mark.asyncio
+    async def test_send_messages_success(self, zmq_benchmark):
+        """Test successful message sending"""
+        # Mock the socket
+        mock_socket = AsyncMock()
+        zmq_benchmark.push_socket = mock_socket
+
+        test_data = zmq_benchmark.generate_test_data()
+        handler = RegisterHandler()
+        msg = handler.create_message(zmq_benchmark, test_data)
+
+        latency = await zmq_benchmark.send_messages([msg])
+
+        assert isinstance(latency, float)
+        assert latency >= 0
+        mock_socket.send_multipart.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_send_messages_timeout(self, zmq_benchmark):
+        """Test message sending timeout"""
+        # Mock the socket to raise timeout
+        mock_socket = AsyncMock()
+        mock_socket.send_multipart.side_effect = Exception("Send timeout")
+        zmq_benchmark.push_socket = mock_socket
+
+        test_data = zmq_benchmark.generate_test_data()
+        handler = RegisterHandler()
+        msg = handler.create_message(zmq_benchmark, test_data)
+
+        with pytest.raises(Exception, match="Send timeout"):
+            await zmq_benchmark.send_messages([msg])
+
+    @pytest.mark.asyncio
+    async def test_send_request_success(self, zmq_benchmark):
+        """Test successful request sending via DEALER socket"""
+        # Mock the socket
+        mock_socket = AsyncMock()
+        mock_socket.send_multipart = AsyncMock()
+        # DEALER receives: [empty_frame, payload]
+        mock_socket.recv_multipart = AsyncMock(return_value=[b"", b"response"])
+        zmq_benchmark.req_socket = mock_socket
+
+        test_data = zmq_benchmark.generate_test_data()
+        handler = P2PLookupHandler()
+        msg = handler.create_message(zmq_benchmark, test_data)
+
+        latency, response = await zmq_benchmark.send_request(msg)
+
+        assert isinstance(latency, float)
+        assert latency >= 0
+        assert response == b"response"
+        mock_socket.send_multipart.assert_called_once()
+        mock_socket.recv_multipart.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_send_request_timeout(self, zmq_benchmark):
+        """Test request sending timeout via DEALER socket"""
+        # Mock the socket to raise timeout
+        mock_socket = AsyncMock()
+        mock_socket.send_multipart = AsyncMock()
+        mock_socket.recv_multipart = AsyncMock(side_effect=Exception("Request timeout"))
+        zmq_benchmark.req_socket = mock_socket
+
+        test_data = zmq_benchmark.generate_test_data()
+        handler = P2PLookupHandler()
+        msg = handler.create_message(zmq_benchmark, test_data)
+
+        with pytest.raises(Exception, match="Request timeout"):
+            await zmq_benchmark.send_request(msg)
+
+    @pytest.mark.asyncio
+    async def test_execute_operation_success(self, zmq_benchmark):
+        """Test successful operation execution"""
+        # Mock send_messages to avoid actual socket operations
+        with patch.object(
+            zmq_benchmark, "send_messages", AsyncMock(return_value=0.001)
+        ):
+            test_data = zmq_benchmark.generate_test_data()
+
+            (
+                msg_count,
+                req_count,
+                latency,
+                error,
+            ) = await zmq_benchmark._execute_operation("admit", test_data)
+
+            assert msg_count == zmq_benchmark.config.batch_size
+            assert req_count == 1
+            assert latency > 0
+            assert error is None
+
+    @pytest.mark.asyncio
+    async def test_execute_operation_unknown(self, zmq_benchmark):
+        """Test unknown operation execution"""
+        test_data = zmq_benchmark.generate_test_data()
+
+        msg_count, req_count, latency, error = await zmq_benchmark._execute_operation(
+            "unknown_op", test_data
+        )
+
+        assert msg_count == 0
+        assert req_count == 0
+        assert latency == 0.0
+        assert isinstance(error, ValueError)
+
+    def test_build_operation_distribution(self, zmq_benchmark):
+        """Test operation distribution building"""
+        operations = zmq_benchmark._build_operation_distribution()
+
+        assert len(operations) > 0
+        assert all(op in zmq_benchmark.config.operations for op in operations)
+
+        # Verify distribution roughly matches percentages
+        op_counts = {}
+        for op in operations:
+            op_counts[op] = op_counts.get(op, 0) + 1
+
+        total_ops = len(operations)
+        for op_name, percentage in zmq_benchmark.config.operations.items():
+            expected_count = int(total_ops * percentage / 100)
+            actual_count = op_counts.get(op_name, 0)
+            # Allow some tolerance for random distribution
+            assert abs(actual_count - expected_count) <= 2
+
+
+class TestIntegration:
+    """Integration tests for the ZMQ benchmark tool"""
+
+    def test_operation_distribution(self):
+        """Test operation distribution calculation"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url=None,
+            duration=60,
+            batch_size=50,
+            num_instances=10,
+            num_workers=5,
+            num_locations=3,
+            num_keys=1000,
+            operations={"admit": 50, "evict": 30, "heartbeat": 20},
+        )
+
+        zmq_benchmark = ZMQControllerBenchmark(config)
+        # Verify benchmark was created with correct config
+        assert zmq_benchmark.config.batch_size == 50
+
+        # Build operation distribution
+        operations = []
+        total_ops = 1000
+        for op_name, percentage in config.operations.items():
+            count = int(total_ops * percentage / 100)
+            operations.extend([op_name] * count)
+
+        # Verify distribution
+        assert len(operations) == total_ops
+
+        op_counts: Dict[str, int] = {}
+        for op in operations:
+            op_counts[op] = op_counts.get(op, 0) + 1
+
+        assert op_counts["admit"] == 500
+        assert op_counts["evict"] == 300
+        assert op_counts["heartbeat"] == 200
+
+    @pytest.mark.asyncio
+    async def test_benchmark_setup_and_cleanup(self):
+        """Test benchmark setup and cleanup"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url="localhost:8101",
+            duration=1,
+            batch_size=10,
+            num_instances=2,
+            num_workers=2,
+            num_locations=2,
+            num_keys=10,
+            register_first=False,
+        )
+
+        zmq_benchmark = ZMQControllerBenchmark(config)
+
+        # Mock ZMQ context and sockets
+        with patch(
+            "lmcache.tools.controller_benchmark.benchmark.get_zmq_context"
+        ) as mock_context:
+            mock_ctx = MagicMock()
+            mock_context.return_value = mock_ctx
+
+            mock_socket = MagicMock()
+            mock_ctx.socket.return_value = mock_socket
+
+            await zmq_benchmark.setup()
+
+            # Verify setup was called
+            mock_context.assert_called_once()
+
+            # Test cleanup
+            zmq_benchmark.cleanup()
+            # Verify sockets were closed
+            assert mock_socket.close.called
+
+    def test_results_structure(self):
+        """Test results structure initialization"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="localhost:8100",
+            controller_reply_url="localhost:8101",
+            duration=1,
+            batch_size=10,
+            num_instances=2,
+            num_workers=2,
+            num_locations=2,
+            num_keys=10,
+            register_first=False,
+        )
+
+        zmq_benchmark = ZMQControllerBenchmark(config)
+        results = zmq_benchmark.results
+
+        assert hasattr(results, "operations")
+        assert hasattr(results, "memory_usage")
+        assert hasattr(results, "total_messages")
+        assert hasattr(results, "total_requests")
+        assert hasattr(results, "overall_qps")
+        assert hasattr(results, "overall_rps")
+
+        assert isinstance(results.operations, dict)
+        assert isinstance(results.memory_usage, list)
+        assert results.total_messages == 0
+        assert results.total_requests == 0
+
+    def test_normalize_heartbeat_url_localhost_connection(self):
+        """Test heartbeat URL normalization when connecting to localhost"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="127.0.0.1:8100",
+            controller_reply_url="127.0.0.1:8101",
+            duration=1,
+            batch_size=10,
+            num_instances=2,
+            num_workers=2,
+            num_locations=2,
+            num_keys=10,
+            register_first=False,
+        )
+
+        zmq_benchmark = ZMQControllerBenchmark(config)
+
+        # When connecting locally, remote IPs should be replaced with 127.0.0.1
+        assert (
+            zmq_benchmark._normalize_heartbeat_url("10.0.0.5:7557") == "127.0.0.1:7557"
+        )
+        assert (
+            zmq_benchmark._normalize_heartbeat_url("192.168.1.100:7557")
+            == "127.0.0.1:7557"
+        )
+        # localhost should remain unchanged
+        assert (
+            zmq_benchmark._normalize_heartbeat_url("127.0.0.1:7557") == "127.0.0.1:7557"
+        )
+        assert (
+            zmq_benchmark._normalize_heartbeat_url("localhost:7557") == "localhost:7557"
+        )
+
+    def test_normalize_heartbeat_url_remote_connection(self):
+        """Test heartbeat URL normalization when connecting to remote host"""
+        config = ZMQBenchmarkConfig(
+            controller_pull_url="10.0.0.5:8100",
+            controller_reply_url="10.0.0.5:8101",
+            duration=1,
+            batch_size=10,
+            num_instances=2,
+            num_workers=2,
+            num_locations=2,
+            num_keys=10,
+            register_first=False,
+        )
+
+        zmq_benchmark = ZMQControllerBenchmark(config)
+
+        # When connecting to remote, should keep the original IP
+        assert (
+            zmq_benchmark._normalize_heartbeat_url("10.0.0.5:7557") == "10.0.0.5:7557"
+        )
+        assert (
+            zmq_benchmark._normalize_heartbeat_url("192.168.1.100:7557")
+            == "192.168.1.100:7557"
+        )
diff --git a/tests/v1/__init__.py b/tests/v1/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/v1/cache_controller/__init__.py b/tests/v1/cache_controller/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/cache_controller/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/cache_controller/conftest.py b/tests/v1/cache_controller/conftest.py
new file mode 100644
index 0000000..1dac16a
--- /dev/null
+++ b/tests/v1/cache_controller/conftest.py
@@ -0,0 +1,468 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared test fixtures and utilities for cache controller tests."""
+
+# Standard
+from unittest.mock import AsyncMock, MagicMock, Mock, patch
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.cache_controller.controllers.full_sync_tracker import FullSyncTracker
+from lmcache.v1.cache_controller.controllers.kv_controller import KVController
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    FullSyncBatchMsg,
+    FullSyncEndMsg,
+    FullSyncStartMsg,
+    FullSyncStartRetMsg,
+    FullSyncStatusMsg,
+    FullSyncStatusRetMsg,
+    KVOpEvent,
+    RegisterMsg,
+)
+from lmcache.v1.cache_controller.utils import RegistryTree, WorkerInfo
+from lmcache.v1.config import LMCacheEngineConfig
+
+# Constants
+LOCATION = "LocalCPUBackend"
+
+
+# ============= Config & Key Creation =============
+
+
+def create_test_config(
+    batch_size: int = 100,
+    batch_interval_ms: int = 0,
+    startup_delay_s: float = 0.0,
+    status_poll_interval_s: float = 0.01,
+    max_retry_count: int = 3,
+    retry_delay_s: float = 0.01,
+):
+    """Create a test configuration."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        lmcache_instance_id="test_instance",
+    )
+    config.extra_config = {
+        "full_sync_batch_size": batch_size,
+        "full_sync_batch_interval_ms": batch_interval_ms,
+        "full_sync_startup_delay_s": startup_delay_s,
+        "full_sync_status_poll_interval_s": status_poll_interval_s,
+        "full_sync_max_retry_count": max_retry_count,
+        "full_sync_retry_delay_s": retry_delay_s,
+    }
+    return config
+
+
+def create_test_key(key_id: int) -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=0,
+        chunk_hash=key_id,
+        dtype=torch.bfloat16,
+    )
+
+
+# ============= Mock Classes =============
+
+
+class MockWorker:
+    """Mock LMCacheWorker for testing."""
+
+    def __init__(self):
+        self.worker_id = 0
+        self.messages = []
+        self.req_responses = []
+        self._response_index = 0
+
+    def put_msg(self, msg):
+        """Record pushed messages."""
+        self.messages.append(msg)
+
+    async def async_put_and_wait_msg(self, msg):
+        """Return predefined responses for REQ-REP messages."""
+        if self._response_index < len(self.req_responses):
+            response = self.req_responses[self._response_index]
+            self._response_index += 1
+            return response
+        # Default responses
+        if isinstance(msg, FullSyncStartMsg):
+            return FullSyncStartRetMsg(sync_id=msg.sync_id, accepted=True)
+        elif isinstance(msg, FullSyncStatusMsg):
+            return FullSyncStatusRetMsg(
+                sync_id=msg.sync_id,
+                is_complete=True,
+                global_progress=1.0,
+                can_exit_freeze=True,
+            )
+        return None
+
+    def set_responses(self, responses):
+        """Set predefined responses."""
+        self.req_responses = responses
+        self._response_index = 0
+
+
+class MockLMCacheEngine:
+    """Mock LMCacheEngine for testing."""
+
+    def __init__(self):
+        self._freeze = False
+        self.freeze_calls = []
+
+    def freeze(self, enabled: bool):
+        """Record freeze mode changes."""
+        self.freeze_calls.append(enabled)
+        self._freeze = enabled
+
+
+class MockLocalCPUBackend:
+    """Mock LocalCPUBackend for testing."""
+
+    def __init__(self, keys=None):
+        self._keys = keys or []
+
+    def get_keys(self):
+        """Return predefined keys."""
+        return self._keys
+
+    def __str__(self):
+        return LOCATION
+
+
+# ============= Helper Class =============
+
+
+class H:
+    """Helper class for test utilities."""
+
+    @staticmethod
+    def create_tracker(threshold=0.8, timeout=300.0):
+        """Create FullSyncTracker with registry."""
+        reg = RegistryTree()
+        tracker = FullSyncTracker(reg, threshold, timeout)
+        return tracker, reg
+
+    @staticmethod
+    def create_controller(threshold=0.8, timeout=300.0):
+        """Create KVController with test settings."""
+        reg = RegistryTree()
+        ctrl = KVController(reg, threshold, timeout)
+        ctrl.cluster_executor = MagicMock()
+        return ctrl
+
+    @staticmethod
+    def reg_worker(reg, inst, wid, ip="127.0.0.1", port=8000):
+        """Register a worker."""
+        reg.register_worker(inst, wid, ip, port, None, MagicMock(), time.time())
+
+    @staticmethod
+    async def reg_worker_async(ctrl, inst, wid, ip="127.0.0.1", port=8000):
+        """Register worker via registration controller."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock:
+            mock.return_value = MagicMock()
+            mock.return_value.sent_messages = []
+            return await ctrl.register(RegisterMsg(inst, wid, ip, port, None))
+
+    @staticmethod
+    def start_msg(inst, wid, sid, keys=100, batches=5):
+        """Create FullSyncStartMsg."""
+        return FullSyncStartMsg(inst, wid, LOCATION, sid, keys, batches)
+
+    @staticmethod
+    def batch_msg(inst, wid, sid, bid, keys):
+        """Create FullSyncBatchMsg."""
+        return FullSyncBatchMsg(inst, wid, LOCATION, sid, bid, keys)
+
+    @staticmethod
+    def end_msg(inst, wid, sid, total):
+        """Create FullSyncEndMsg."""
+        return FullSyncEndMsg(inst, wid, LOCATION, sid, total)
+
+    @staticmethod
+    def batched_op(inst, wid, op, key, seq=0):
+        """Create BatchedKVOperationMsg."""
+        return BatchedKVOperationMsg(inst, wid, LOCATION, [KVOpEvent(op, key, seq)])
+
+    @staticmethod
+    def start_ret(sync_id, accepted=True, error_msg=None):
+        """Create FullSyncStartRetMsg."""
+        return FullSyncStartRetMsg(
+            sync_id=sync_id, accepted=accepted, error_msg=error_msg
+        )
+
+    @staticmethod
+    def status_ret(sync_id, is_complete=True, progress=1.0, can_exit=True):
+        """Create FullSyncStatusRetMsg."""
+        return FullSyncStatusRetMsg(
+            sync_id=sync_id,
+            is_complete=is_complete,
+            global_progress=progress,
+            can_exit_freeze=can_exit,
+        )
+
+
+# ============= Pytest Fixtures =============
+
+
+@pytest.fixture
+def mock_reg_controller():
+    """Create a mock RegistrationController."""
+    controller = Mock()
+    controller.get_workers = Mock(return_value=[0, 1])
+    controller.get_socket = Mock()
+    controller.get_peer_init_url = Mock(return_value="tcp://localhost:5000")
+
+    # Create a mock registry with all required methods
+    mock_registry = Mock()
+    mock_registry.seq_tracker = {}
+    mock_registry.kv_pool = {}
+
+    def mock_get_seq_num(instance_id, worker_id, location):
+        key = (instance_id, worker_id, location)
+        return mock_registry.seq_tracker.get(key)
+
+    def mock_update_seq_num(instance_id, worker_id, location, seq_num):
+        key = (instance_id, worker_id, location)
+        mock_registry.seq_tracker[key] = seq_num
+        return True
+
+    def mock_admit_kv(instance_id, worker_id, location, key):
+        report_id = (instance_id, worker_id)
+        if report_id not in mock_registry.kv_pool:
+            mock_registry.kv_pool[report_id] = {}
+        if location not in mock_registry.kv_pool[report_id]:
+            mock_registry.kv_pool[report_id][location] = set()
+        mock_registry.kv_pool[report_id][location].add(key)
+        return True
+
+    def mock_evict_kv(instance_id, worker_id, location, key):
+        report_id = (instance_id, worker_id)
+        if report_id in mock_registry.kv_pool:
+            if location in mock_registry.kv_pool[report_id]:
+                if key in mock_registry.kv_pool[report_id][location]:
+                    mock_registry.kv_pool[report_id][location].remove(key)
+                    if not mock_registry.kv_pool[report_id][location]:
+                        del mock_registry.kv_pool[report_id][location]
+                    if not mock_registry.kv_pool[report_id]:
+                        del mock_registry.kv_pool[report_id]
+                    return True
+        return False
+
+    def mock_find_kv(key, exclude_instance_id=None):
+        for report_id, locations in mock_registry.kv_pool.items():
+            instance_id, worker_id = report_id
+            if exclude_instance_id and instance_id == exclude_instance_id:
+                continue
+            for location, keys in locations.items():
+                if key in keys:
+                    # Return a mock KVChunkInfo
+                    # First Party
+                    from lmcache.v1.cache_controller.utils import KVChunkInfo
+
+                    return KVChunkInfo(instance_id, worker_id, location)
+        return None
+
+    def mock_get_worker_kv_keys(instance_id, worker_id, location):
+        report_id = (instance_id, worker_id)
+        if report_id in mock_registry.kv_pool:
+            return mock_registry.kv_pool[report_id].get(location, set())
+        return set()
+
+    def mock_get_total_kv_count():
+        count = 0
+        for locations in mock_registry.kv_pool.values():
+            for keys in locations.values():
+                count += len(keys)
+        return count
+
+    def mock_get_seq_discontinuity_count():
+        # Simple implementation for testing
+        return getattr(mock_registry, "_seq_discontinuity_count", 0)
+
+    def mock_deregister_worker(instance_id, worker_id):
+        report_id = (instance_id, worker_id)
+        if report_id in mock_registry.kv_pool:
+            del mock_registry.kv_pool[report_id]
+        # Also clean up seq_tracker
+        keys_to_remove = [
+            k
+            for k in mock_registry.seq_tracker.keys()
+            if k[0] == instance_id and k[1] == worker_id
+        ]
+        for key in keys_to_remove:
+            del mock_registry.seq_tracker[key]
+        return True
+
+    def mock_find_kv_with_worker_info(key, exclude_instance_id=None):
+        """Find KV and return (kv_info, peer_init_url, current_keys)"""
+        for report_id, locations in mock_registry.kv_pool.items():
+            instance_id, worker_id = report_id
+            if exclude_instance_id and instance_id == exclude_instance_id:
+                continue
+            for location, keys in locations.items():
+                if key in keys:
+                    # First Party
+                    from lmcache.v1.cache_controller.utils import KVChunkInfo
+
+                    kv_info = KVChunkInfo(instance_id, worker_id, location)
+                    # Get peer_init_url from controller
+                    peer_init_url = controller.get_peer_init_url(instance_id, worker_id)
+                    return (kv_info, peer_init_url, keys)
+        return None
+
+    def mock_handle_batched_kv_operations(msg):
+        """Handle batched KV operations"""
+        # First Party
+        from lmcache.v1.cache_controller.message import OpType
+
+        report_id = (msg.instance_id, msg.worker_id)
+
+        for op in msg.operations:
+            # Check for sequence discontinuity
+            key = (msg.instance_id, msg.worker_id, msg.location)
+            last_seq_num = mock_registry.seq_tracker.get(key)
+            if last_seq_num is not None:
+                expected_seq = last_seq_num + 1
+                if op.seq_num != expected_seq:
+                    # Increment discontinuity counter
+                    mock_registry._seq_discontinuity_count += 1
+
+            # Update sequence number
+            mock_registry.seq_tracker[key] = op.seq_num
+
+            # Handle operation
+            if op.op_type == OpType.ADMIT:
+                if report_id not in mock_registry.kv_pool:
+                    mock_registry.kv_pool[report_id] = {}
+                if msg.location not in mock_registry.kv_pool[report_id]:
+                    mock_registry.kv_pool[report_id][msg.location] = set()
+                mock_registry.kv_pool[report_id][msg.location].add(op.key)
+            elif op.op_type == OpType.EVICT:
+                if report_id in mock_registry.kv_pool:
+                    if msg.location in mock_registry.kv_pool[report_id]:
+                        mock_registry.kv_pool[report_id][msg.location].discard(op.key)
+                        if not mock_registry.kv_pool[report_id][msg.location]:
+                            del mock_registry.kv_pool[report_id][msg.location]
+                        if not mock_registry.kv_pool[report_id]:
+                            del mock_registry.kv_pool[report_id]
+        return True
+
+    mock_registry.get_seq_num = Mock(side_effect=mock_get_seq_num)
+    mock_registry.update_seq_num = Mock(side_effect=mock_update_seq_num)
+    mock_registry.admit_kv = Mock(side_effect=mock_admit_kv)
+    mock_registry.evict_kv = Mock(side_effect=mock_evict_kv)
+    mock_registry.find_kv = Mock(side_effect=mock_find_kv)
+    mock_registry.get_worker_kv_keys = Mock(side_effect=mock_get_worker_kv_keys)
+    mock_registry.get_total_kv_count = Mock(side_effect=mock_get_total_kv_count)
+    mock_registry.get_seq_discontinuity_count = Mock(
+        side_effect=mock_get_seq_discontinuity_count
+    )
+    mock_registry.deregister_worker = Mock(side_effect=mock_deregister_worker)
+    mock_registry.find_kv_with_worker_info = Mock(
+        side_effect=mock_find_kv_with_worker_info
+    )
+    mock_registry.handle_batched_kv_operations = Mock(
+        side_effect=mock_handle_batched_kv_operations
+    )
+    mock_registry._seq_discontinuity_count = 0
+
+    controller.registry = mock_registry
+    return controller
+
+
+@pytest.fixture
+def mock_kv_controller():
+    """Create a mock KVController."""
+    controller = Mock()
+    controller.admit = AsyncMock()
+    controller.evict = AsyncMock()
+    controller.lookup = AsyncMock()
+    controller.clear = AsyncMock()
+    controller.pin = AsyncMock()
+    controller.compress = AsyncMock()
+    controller.decompress = AsyncMock()
+    controller.move = AsyncMock()
+    controller.deregister = AsyncMock()
+    controller.kv_pool = {}
+    controller.seq_tracker = {}
+
+    # Mock full_sync_tracker
+    mock_tracker = Mock()
+    mock_tracker.should_request_full_sync = Mock(return_value=(False, None))
+    controller.full_sync_tracker = mock_tracker
+
+    return controller
+
+
+@pytest.fixture
+def mock_cluster_executor():
+    """Create a mock LMCacheClusterExecutor."""
+    executor = Mock()
+    executor.execute = AsyncMock()
+    executor.clear = AsyncMock()
+    executor.pin = AsyncMock()
+    executor.compress = AsyncMock()
+    executor.decompress = AsyncMock()
+    executor.move = AsyncMock()
+    executor.health = AsyncMock()
+    executor.check_finish = AsyncMock()
+    return executor
+
+
+@pytest.fixture
+def mock_zmq_socket():
+    """Create a mock ZMQ socket."""
+    socket = AsyncMock()
+    socket.send = AsyncMock()
+    socket.recv = AsyncMock()
+    socket.send_multipart = AsyncMock()
+    socket.recv_multipart = AsyncMock()
+    socket.close = Mock()
+    socket.get = Mock(return_value=0)
+    return socket
+
+
+@pytest.fixture
+def mock_zmq_context():
+    """Create a mock ZMQ context."""
+    context = Mock()
+    context.socket = Mock()
+    context.term = Mock()
+    return context
+
+
+@pytest.fixture
+def sample_worker_info():
+    """Create sample worker info for testing."""
+    return WorkerInfo(
+        instance_id="test_instance",
+        worker_id=0,
+        ip="127.0.0.1",
+        port=5000,
+        peer_init_url="tcp://127.0.0.1:6000",
+        registration_time=time.time(),
+        last_heartbeat_time=time.time(),
+    )
+
+
+@pytest.fixture
+def mock_lmcache_engine():
+    """Create a mock LMCacheEngine."""
+    engine = Mock()
+    engine.move = Mock(return_value=100)
+    engine.compress = Mock(return_value=100)
+    engine.decompress = Mock(return_value=100)
+    engine.lookup = Mock(return_value=100)
+    engine.clear = Mock(return_value=100)
+    engine.health = Mock(return_value=0)
+    return engine
diff --git a/tests/v1/cache_controller/pytest.ini b/tests/v1/cache_controller/pytest.ini
new file mode 100644
index 0000000..4621e34
--- /dev/null
+++ b/tests/v1/cache_controller/pytest.ini
@@ -0,0 +1,26 @@
+[pytest]
+# Pytest configuration for cache_controller tests
+# This allows running these tests independently without the global conftest
+
+# Prevent loading parent conftest.py files
+norecursedirs = ../..
+
+# Test discovery patterns
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+
+# Async support
+asyncio_mode = auto
+
+# Output options
+addopts =
+    -v
+    --tb=short
+    --strict-markers
+
+# Markers
+markers =
+    asyncio: mark test as async
+    unit: mark test as unit test
+    integration: mark test as integration test
\ No newline at end of file
diff --git a/tests/v1/cache_controller/test_config.py b/tests/v1/cache_controller/test_config.py
new file mode 100644
index 0000000..c58b1e5
--- /dev/null
+++ b/tests/v1/cache_controller/test_config.py
@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test script for LMCache Controller Configuration
+
+This script tests the ControllerConfig class and its functionality:
+- Loading from environment variables
+- Loading from YAML file
+- Command-line parameter overrides
+- Global singleton pattern
+"""
+
+# Standard
+import os
+import tempfile
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.config import (
+    ControllerConfig,
+    controller_get_or_create_config,
+    load_controller_config_with_overrides,
+    override_controller_config_from_dict,
+)
+
+logger = init_logger(__name__)
+
+
+def test_from_env():
+    """Test loading configuration from environment variables"""
+    logger.info("=" * 80)
+    logger.info("Testing: Loading from environment variables")
+    logger.info("=" * 80)
+
+    # Set some environment variables
+    os.environ["LMCACHE_CONTROLLER_CONTROLLER_PORT"] = "9001"
+    os.environ["LMCACHE_CONTROLLER_HEALTH_CHECK_INTERVAL"] = "30"
+
+    config = ControllerConfig.from_env()
+    config.validate()
+    config.log_config()
+
+    # Verify values
+    assert config.controller_port == 9001
+    assert config.health_check_interval == 30
+
+    logger.info("✓ Environment variable loading test passed")
+
+
+def test_from_file():
+    """Test loading configuration from YAML file"""
+    logger.info("=" * 80)
+    logger.info("Testing: Loading from YAML file")
+    logger.info("=" * 80)
+
+    # Create a temporary YAML config file
+    config_content = """
+controller_port: 9002
+health_check_interval: 60
+"""
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+        f.write(config_content)
+        config_file = f.name
+
+    try:
+        config = ControllerConfig.from_file(config_file)
+        config.validate()
+        config.log_config()
+
+        # Verify values
+        assert config.controller_port == 9002
+        assert config.health_check_interval == 60
+
+        logger.info("✓ File loading test passed")
+    finally:
+        os.unlink(config_file)
+
+
+def test_override_from_dict():
+    """Test overriding configuration with dictionary"""
+    logger.info("=" * 80)
+    logger.info("Testing: Override configuration with dictionary")
+    logger.info("=" * 80)
+
+    config = ControllerConfig.from_env()
+
+    # Override with dictionary
+    overrides = {
+        "controller_port": 9003,
+        "health_check_interval": 45,
+    }
+
+    override_controller_config_from_dict(config, overrides)
+    config.validate()
+    config.log_config()
+
+    # Verify overrides
+    assert config.controller_port == 9003
+    assert config.health_check_interval == 45
+
+    logger.info("✓ Dictionary override test passed")
+
+
+def test_singleton_pattern():
+    """Test thread-safe singleton pattern"""
+    logger.info("=" * 80)
+    logger.info("Testing: Singleton pattern")
+    logger.info("=" * 80)
+
+    # Clear any existing instance using the new reset method
+    controller_get_or_create_config.reset()
+
+    # Set environment variable for config file
+    os.environ["LMCACHE_CONTROLLER_CONTROLLER_PORT"] = "9004"
+
+    # Get config instance multiple times
+    config1 = controller_get_or_create_config()
+    config2 = controller_get_or_create_config()
+
+    # Verify they are the same instance
+    assert config1 is config2
+    assert config1.controller_port == 9004
+
+    # Test reset functionality
+    controller_get_or_create_config.reset()
+    os.environ["LMCACHE_CONTROLLER_CONTROLLER_PORT"] = "9005"
+    config3 = controller_get_or_create_config()
+    assert config3.controller_port == 9005
+    assert config3 is not config1  # Should be a new instance after reset
+
+    logger.info("✓ Singleton pattern test passed")
+
+
+def test_to_from_dict():
+    """Test dictionary serialization/deserialization"""
+    logger.info("=" * 80)
+    logger.info("Testing: Dictionary serialization")
+    logger.info("=" * 80)
+
+    config = ControllerConfig.from_env()
+    config.controller_port = 9005
+
+    # Convert to dictionary
+    config_dict = config.to_dict()
+
+    # Create new config from dictionary
+    new_config = ControllerConfig.from_dict(config_dict)
+
+    # Verify they are equivalent
+    assert new_config.controller_port == config.controller_port
+
+    logger.info("✓ Dictionary serialization test passed")
+
+
+def test_to_from_json():
+    """Test JSON serialization/deserialization"""
+    logger.info("=" * 80)
+    logger.info("Testing: JSON serialization")
+    logger.info("=" * 80)
+
+    config = ControllerConfig.from_env()
+    config.controller_port = 9006
+
+    # Convert to JSON
+    json_str = config.to_json()
+
+    # Create new config from JSON
+    new_config = ControllerConfig.from_json(json_str)
+
+    # Verify they are equivalent
+    assert new_config.controller_port == config.controller_port
+
+    logger.info("✓ JSON serialization test passed")
+
+
+def test_controller_monitor_ports_json_parsing():
+    """Test that controller_monitor_ports JSON string is correctly parsed as dict"""
+    logger.info("=" * 80)
+    logger.info("Testing: controller_monitor_ports JSON parsing")
+    logger.info("=" * 80)
+
+    # Test 1: From environment variable (string JSON)
+    original_env = os.environ.get("LMCACHE_CONTROLLER_CONTROLLER_MONITOR_PORTS")
+    os.environ["LMCACHE_CONTROLLER_CONTROLLER_MONITOR_PORTS"] = (
+        '{"pull": 8300, "reply": 8400}'
+    )
+
+    try:
+        config = ControllerConfig.from_env()
+        config.validate()
+
+        # Check that controller_monitor_ports is a dict, not a string
+        expected_type_msg = (
+            f"Expected dict but got {type(config.controller_monitor_ports)}: "
+            f"{config.controller_monitor_ports}"
+        )
+        assert isinstance(config.controller_monitor_ports, dict), expected_type_msg
+        assert config.controller_monitor_ports["pull"] == 8300
+        assert config.controller_monitor_ports["reply"] == 8400
+
+        logger.info("✓ Environment variable JSON parsing test passed")
+
+        # Test 2: From file with YAML string
+        config_content = """
+controller_monitor_ports: '{"pull": 8500, "reply": 8600}'
+"""
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+            f.write(config_content)
+            config_file = f.name
+
+        try:
+            config2 = ControllerConfig.from_file(config_file)
+            config2.validate()
+
+            expected_type_msg2 = (
+                f"Expected dict but got {type(config2.controller_monitor_ports)}: "
+                f"{config2.controller_monitor_ports}"
+            )
+            assert isinstance(config2.controller_monitor_ports, dict), (
+                expected_type_msg2
+            )
+            assert config2.controller_monitor_ports["pull"] == 8500
+            assert config2.controller_monitor_ports["reply"] == 8600
+
+            logger.info("✓ File YAML JSON parsing test passed")
+
+            # Test 3: Dictionary override with JSON string
+            config3 = ControllerConfig.from_env()
+            override_dict = {
+                "controller_monitor_ports": '{"pull": 8700, "reply": 8800}'
+            }
+            override_controller_config_from_dict(config3, override_dict)
+
+            expected_type_msg3 = (
+                f"Expected dict but got {type(config3.controller_monitor_ports)}: "
+                f"{config3.controller_monitor_ports}"
+            )
+            assert isinstance(config3.controller_monitor_ports, dict), (
+                expected_type_msg3
+            )
+            assert config3.controller_monitor_ports["pull"] == 8700
+            assert config3.controller_monitor_ports["reply"] == 8800
+
+            logger.info("✓ Dictionary override JSON parsing test passed")
+
+            # Test 4: Dictionary override with actual dict
+            config4 = ControllerConfig.from_env()
+            override_dict2 = {"controller_monitor_ports": {"pull": 8900, "reply": 9000}}
+            override_controller_config_from_dict(config4, override_dict2)
+
+            expected_type_msg4 = (
+                f"Expected dict but got {type(config4.controller_monitor_ports)}: "
+                f"{config4.controller_monitor_ports}"
+            )
+            assert isinstance(config4.controller_monitor_ports, dict), (
+                expected_type_msg4
+            )
+            assert config4.controller_monitor_ports["pull"] == 8900
+            assert config4.controller_monitor_ports["reply"] == 9000
+
+            logger.info("✓ Dictionary override with dict test passed")
+
+        finally:
+            os.unlink(config_file)
+
+    finally:
+        # Restore original environment variable
+        if original_env is not None:
+            os.environ["LMCACHE_CONTROLLER_CONTROLLER_MONITOR_PORTS"] = original_env
+        else:
+            os.environ.pop("LMCACHE_CONTROLLER_CONTROLLER_MONITOR_PORTS", None)
+
+    logger.info("✓ controller_monitor_ports JSON parsing test passed")
+
+
+def test_load_controller_config_with_overrides():
+    """
+    Test loading controller config with overrides,
+    especially for controller_monitor_ports
+    """
+    logger.info("=" * 80)
+    logger.info("Testing: load_controller_config_with_overrides")
+    logger.info("=" * 80)
+
+    # Test with monitor ports as JSON string in overrides
+    overrides = {
+        "controller_host": "localhost",
+        "controller_port": 8000,
+        "controller_monitor_ports": '{"pull": 8300, "reply": 8400}',
+    }
+
+    # Load config without config file (from env with overrides)
+    config = load_controller_config_with_overrides(overrides=overrides)
+
+    # Verify values
+    assert config.controller_host == "localhost"
+    assert config.controller_port == 8000
+
+    expected_type_msg = (
+        f"Expected dict but got {type(config.controller_monitor_ports)}: "
+        f"{config.controller_monitor_ports}"
+    )
+    assert isinstance(config.controller_monitor_ports, dict), expected_type_msg
+    assert config.controller_monitor_ports["pull"] == 8300
+    assert config.controller_monitor_ports["reply"] == 8400
+
+    # Log config to see the output
+    config.log_config()
+
+    logger.info("✓ load_controller_config_with_overrides test passed")
diff --git a/tests/v1/cache_controller/test_full_sync.py b/tests/v1/cache_controller/test_full_sync.py
new file mode 100644
index 0000000..6538ca0
--- /dev/null
+++ b/tests/v1/cache_controller/test_full_sync.py
@@ -0,0 +1,447 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for full sync functionality (Tracker and KVController)."""
+
+# Standard
+import asyncio
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.cache_controller.commands.full_sync import FullSyncCommand
+from lmcache.v1.cache_controller.controllers.registration_controller import (
+    RegistrationController,
+)
+from lmcache.v1.cache_controller.message import (
+    FullSyncStatusMsg,
+    HeartbeatMsg,
+    OpType,
+)
+from lmcache.v1.cache_controller.utils import FullSyncState, RegistryTree
+
+# Local
+# Test utilities from conftest
+from .conftest import LOCATION, H
+
+# ============= FullSyncTracker Tests =============
+
+
+class TestFullSyncTracker:
+    """Tests for FullSyncTracker."""
+
+    @pytest.mark.parametrize(
+        "state,reason",
+        [
+            ("none", "controller_restart"),
+            ("syncing", None),
+            ("completed", None),
+            ("failed", "sync_failed_retry"),
+        ],
+    )
+    def test_should_request_full_sync(self, state, reason):
+        """Test sync request logic."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+
+        if state == "syncing":
+            tracker.start_sync("i1", 0, "s1", 100, 5)
+        elif state == "completed":
+            tracker.start_sync("i1", 0, "s1", 100, 5)
+            tracker.complete_sync("i1", 0, "s1", 100)
+        elif state == "failed":
+            tracker.set_need_full_sync_all(False)
+            tracker.start_sync("i1", 0, "s1", 100, 5)
+            tracker.mark_failed("i1", 0, "timeout")
+
+        need, r = tracker.should_request_full_sync("i1", 0)
+        assert (need, r) == (reason is not None, reason)
+
+    @pytest.mark.parametrize(
+        "action,syncing,state",
+        [
+            ("none", False, None),
+            ("start", True, FullSyncState.SYNCING),
+            ("complete", False, FullSyncState.COMPLETED),
+            ("fail", False, FullSyncState.FAILED),
+        ],
+    )
+    def test_is_worker_syncing(self, action, syncing, state):
+        """Test worker syncing status."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+
+        if action == "start":
+            tracker.start_sync("i1", 0, "s1", 100, 5)
+        elif action == "complete":
+            tracker.start_sync("i1", 0, "s1", 100, 5)
+            tracker.complete_sync("i1", 0, "s1", 100)
+        elif action == "fail":
+            tracker.start_sync("i1", 0, "s1", 100, 5)
+            tracker.mark_failed("i1", 0, "reason")
+
+        assert tracker.is_worker_syncing("i1", 0) == syncing
+        if action != "none":
+            assert reg.get_worker("i1", 0).sync_info.state == state
+
+    def test_start_sync_conflict(self):
+        """Test sync start conflict handling."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+
+        tracker.start_sync("i1", 0, "s1", 100, 5)
+        assert tracker.start_sync("i1", 0, "s2", 200, 10) is False  # Different ID
+        assert tracker.start_sync("i1", 0, "s1", 100, 5) is True  # Same ID (retry)
+
+    @pytest.mark.parametrize("batches,keys_per", [(5, 20), (2, 50), (1, 100)])
+    def test_receive_batches(self, batches, keys_per):
+        """Test batch receiving."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+        tracker.start_sync("i1", 0, "s1", 100, batches)
+
+        for i in range(batches):
+            assert tracker.receive_batch("i1", 0, "s1", i, keys_per) is True
+
+        info = reg.get_worker("i1", 0).sync_info
+        assert info.received_batches == set(range(batches))
+        assert info.received_keys_count == batches * keys_per
+
+    def test_receive_batch_wrong_sync_id(self):
+        """Test batch with wrong sync ID rejected."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+        tracker.start_sync("i1", 0, "correct", 100, 5)
+
+        assert tracker.receive_batch("i1", 0, "wrong", 0, 20) is False
+        assert reg.get_worker("i1", 0).sync_info.received_keys_count == 0
+
+    def test_complete_sync(self):
+        """Test sync completion."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+        tracker.start_sync("i1", 0, "s1", 100, 5)
+
+        for i in range(5):
+            tracker.receive_batch("i1", 0, "s1", i, 20)
+
+        assert tracker.complete_sync("i1", 0, "s1", 100) is True
+        assert reg.get_worker("i1", 0).sync_info.state == FullSyncState.COMPLETED
+        assert tracker.complete_sync("i1", 0, "wrong", 100) is False
+
+    def test_check_sync_timeout(self):
+        """Test timeout detection."""
+        tracker, reg = H.create_tracker(timeout=0.1)
+        tracker.set_need_full_sync_all(False)
+        H.reg_worker(reg, "i1", 0)
+        tracker.start_sync("i1", 0, "s1", 100, 5)
+
+        time.sleep(0.15)
+        tracker.check_sync_timeout()
+
+        assert reg.get_worker("i1", 0).sync_info.state == FullSyncState.FAILED
+        need, reason = tracker.should_request_full_sync("i1", 0)
+        assert need and reason == "sync_failed_retry"
+
+    @pytest.mark.parametrize(
+        "total,completed,expected",
+        [(4, 0, 0.0), (4, 1, 0.25), (4, 2, 0.5), (4, 4, 1.0)],
+    )
+    def test_get_global_progress(self, total, completed, expected):
+        """Test progress calculation."""
+        tracker, reg = H.create_tracker()
+        tracker.set_need_full_sync_all(False)
+
+        for i in range(total):
+            H.reg_worker(reg, "i1", i)
+            tracker.start_sync("i1", i, f"s{i}", 100, 5)
+        for i in range(completed):
+            tracker.complete_sync("i1", i, f"s{i}", 100)
+
+        assert abs(tracker.get_global_progress() - expected) < 0.001
+
+    @pytest.mark.parametrize(
+        "total,completed,threshold,can_exit",
+        [(4, 2, 0.5, True), (4, 1, 0.5, False), (4, 3, 0.8, False), (4, 4, 0.8, True)],
+    )
+    def test_can_exit_freeze(self, total, completed, threshold, can_exit):
+        """Test freeze exit check."""
+        tracker, reg = H.create_tracker(threshold)
+        tracker.set_need_full_sync_all(True)
+
+        for i in range(total):
+            H.reg_worker(reg, "i1", i)
+            tracker.start_sync("i1", i, f"s{i}", 100, 5)
+        for i in range(completed):
+            tracker.complete_sync("i1", i, f"s{i}", 100)
+
+        assert tracker.can_exit_freeze() == can_exit
+
+    @pytest.mark.parametrize(
+        "received,missing",
+        [([], [0, 1, 2, 3, 4]), ([0, 2, 4], [1, 3]), ([0, 1, 2, 3, 4], [])],
+    )
+    def test_get_missing_batches(self, received, missing):
+        """Test missing batches detection."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+        tracker.start_sync("i1", 0, "s1", 100, 5)
+
+        for b in received:
+            tracker.receive_batch("i1", 0, "s1", b, 20)
+
+        assert tracker.get_missing_batches("i1", 0, "s1") == missing
+
+    @pytest.mark.parametrize(
+        "setup,expected",
+        [
+            ("no_sync", []),  # No sync started
+            ("wrong_id", []),  # Wrong sync ID
+            ("completed", []),  # After completion
+        ],
+    )
+    def test_get_missing_batches_edge_cases(self, setup, expected):
+        """Test missing batches edge cases."""
+        tracker, reg = H.create_tracker()
+        H.reg_worker(reg, "i1", 0)
+
+        if setup == "wrong_id":
+            tracker.start_sync("i1", 0, "correct", 100, 5)
+            assert tracker.get_missing_batches("i1", 0, "wrong") == expected
+        elif setup == "completed":
+            tracker.start_sync("i1", 0, "correct", 100, 5)
+            tracker.complete_sync("i1", 0, "correct", 100)
+            assert tracker.get_missing_batches("i1", 0, "correct") == expected
+        else:
+            assert tracker.get_missing_batches("i1", 0, "s1") == expected
+
+
+# ============= KVController Tests =============
+
+
+class TestKVController:
+    """Tests for KVController full sync handling."""
+
+    @pytest.fixture
+    def ctrl(self):
+        """Create KVController."""
+        return H.create_controller()
+
+    @pytest.mark.asyncio
+    async def test_full_sync_start_clears_keys(self, ctrl):
+        """Test sync start clears existing keys."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        for seq, key in enumerate([1, 2, 3]):
+            ctrl.registry.handle_batched_kv_operations(
+                H.batched_op("i1", 0, OpType.ADMIT, key, seq)
+            )
+
+        ret = await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 100, 5))
+
+        assert ret.accepted is True
+        assert ctrl.full_sync_tracker.is_worker_syncing("i1", 0)
+        assert len(ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION)) == 0
+
+    @pytest.mark.asyncio
+    async def test_sync_start_conflict(self, ctrl):
+        """Test sync start conflict."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+
+        r1 = await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 100, 5))
+        r2 = await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s2", 200, 10))
+        r3 = await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 100, 5))
+
+        assert r1.accepted and not r2.accepted and r3.accepted
+
+    @pytest.mark.asyncio
+    async def test_batch_handling(self, ctrl):
+        """Test batch adds keys."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 15, 3))
+
+        for i in range(3):
+            await ctrl.handle_full_sync_batch(
+                H.batch_msg("i1", 0, "s1", i, list(range(i * 5, (i + 1) * 5)))
+            )
+
+        keys = ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION)
+        assert len(keys) == 15 and all(i in keys for i in range(15))
+
+    @pytest.mark.asyncio
+    async def test_batch_wrong_sync_id_rejected(self, ctrl):
+        """Test batch with wrong sync ID rejected."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "correct", 10, 1))
+
+        keys_before = ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION).copy()
+        await ctrl.handle_full_sync_batch(H.batch_msg("i1", 0, "wrong", 0, [1, 2, 3]))
+
+        assert ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION) == keys_before
+
+    @pytest.mark.asyncio
+    async def test_sync_end_completes(self, ctrl):
+        """Test sync end marks completion."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 5, 1))
+        await ctrl.handle_full_sync_batch(
+            H.batch_msg("i1", 0, "s1", 0, [1, 2, 3, 4, 5])
+        )
+        await ctrl.handle_full_sync_end(H.end_msg("i1", 0, "s1", 5))
+
+        assert not ctrl.full_sync_tracker.is_worker_syncing("i1", 0)
+        assert (
+            ctrl.registry.get_worker("i1", 0).sync_info.state == FullSyncState.COMPLETED
+        )
+
+    @pytest.mark.asyncio
+    async def test_sync_status(self, ctrl):
+        """Test status query."""
+        ctrl.full_sync_tracker.completion_threshold = 0.5
+        for i in range(4):
+            H.reg_worker(ctrl.registry, "i1", i)
+            ctrl.full_sync_tracker.start_sync("i1", i, f"s{i}", 100, 5)
+        for i in range(2):
+            ctrl.full_sync_tracker.complete_sync("i1", i, f"s{i}", 100)
+
+        ret = await ctrl.handle_full_sync_status(FullSyncStatusMsg("i1", 0, "s0"))
+
+        assert (
+            ret.is_complete
+            and abs(ret.global_progress - 0.5) < 0.001
+            and ret.can_exit_freeze
+        )
+
+    @pytest.mark.asyncio
+    async def test_sync_status_missing_batches(self, ctrl):
+        """Test status returns missing batches."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 100, 5))
+        await ctrl.handle_full_sync_batch(H.batch_msg("i1", 0, "s1", 0, [1, 2, 3]))
+        await ctrl.handle_full_sync_batch(H.batch_msg("i1", 0, "s1", 2, [7, 8, 9]))
+
+        ret = await ctrl.handle_full_sync_status(FullSyncStatusMsg("i1", 0, "s1"))
+
+        assert not ret.is_complete and ret.missing_batches == [1, 3, 4]
+
+    @pytest.mark.asyncio
+    async def test_incremental_discarded_during_sync(self, ctrl):
+        """Test incremental messages discarded during sync."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 5, 1))
+
+        await ctrl.handle_batched_kv_operations(
+            H.batched_op("i1", 0, OpType.ADMIT, 888)
+        )
+        assert 888 not in ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION)
+
+        await ctrl.handle_full_sync_batch(H.batch_msg("i1", 0, "s1", 0, [999]))
+        await ctrl.handle_batched_kv_operations(
+            H.batched_op("i1", 0, OpType.EVICT, 999)
+        )
+        assert 999 in ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION)
+
+    @pytest.mark.asyncio
+    async def test_incremental_allowed_after_sync(self, ctrl):
+        """Test incremental works after sync completion."""
+        H.reg_worker(ctrl.registry, "i1", 0)
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 0, 1))
+        await ctrl.handle_full_sync_end(H.end_msg("i1", 0, "s1", 0))
+
+        await ctrl.handle_batched_kv_operations(
+            H.batched_op("i1", 0, OpType.ADMIT, 1000, 1)
+        )
+
+        assert 1000 in ctrl.registry.get_worker_kv_keys("i1", 0, LOCATION)
+
+    @pytest.mark.asyncio
+    async def test_sync_timeout(self):
+        """Test sync timeout marks failed."""
+        ctrl = H.create_controller(timeout=0.1)
+        ctrl.full_sync_tracker.set_need_full_sync_all(False)
+        H.reg_worker(ctrl.registry, "i1", 0)
+
+        await ctrl.handle_full_sync_start(H.start_msg("i1", 0, "s1", 100, 5))
+        await asyncio.sleep(0.15)
+        ctrl.full_sync_tracker.check_sync_timeout()
+
+        assert ctrl.registry.get_worker("i1", 0).sync_info.state == FullSyncState.FAILED
+        need, reason = ctrl.full_sync_tracker.should_request_full_sync("i1", 0)
+        assert need and reason == "sync_failed_retry"
+
+
+# ============= Integration Tests =============
+
+
+class TestIntegration:
+    """Integration tests for full sync flow."""
+
+    @pytest.fixture
+    def setup(self):
+        """Setup controllers with shared registry."""
+        # Standard
+        from unittest.mock import MagicMock
+
+        # First Party
+        from lmcache.v1.cache_controller.controllers.kv_controller import KVController
+
+        reg = RegistryTree()
+        kv = KVController(reg, 0.5, 300.0)
+        kv.cluster_executor = MagicMock()
+        rc = RegistrationController()
+        rc.registry = reg
+        rc.kv_controller = kv
+        rc.cluster_executor = MagicMock()
+        return kv, rc
+
+    @pytest.mark.asyncio
+    async def test_complete_sync_flow(self, setup):
+        """Test complete sync flow for single worker."""
+        kv, rc = setup
+
+        await H.reg_worker_async(rc, "i1", 0)
+        for seq, key in enumerate([100, 200, 300]):
+            kv.registry.handle_batched_kv_operations(
+                H.batched_op("i1", 0, OpType.ADMIT, key, seq)
+            )
+
+        hb = await rc.heartbeat(HeartbeatMsg("i1", 0, "127.0.0.1", 8000, None))
+        assert len(hb.commands) == 1 and isinstance(hb.commands[0], FullSyncCommand)
+
+        await kv.handle_full_sync_start(H.start_msg("i1", 0, "s1", 10, 2))
+        assert len(kv.registry.get_worker_kv_keys("i1", 0, LOCATION)) == 0
+
+        await kv.handle_full_sync_batch(H.batch_msg("i1", 0, "s1", 0, [1, 2, 3, 4, 5]))
+        await kv.handle_full_sync_batch(H.batch_msg("i1", 0, "s1", 1, [6, 7, 8, 9, 10]))
+        await kv.handle_full_sync_end(H.end_msg("i1", 0, "s1", 10))
+
+        keys = kv.registry.get_worker_kv_keys("i1", 0, LOCATION)
+        assert keys == {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}
+
+        hb2 = await rc.heartbeat(HeartbeatMsg("i1", 0, "127.0.0.1", 8000, None))
+        assert len(hb2.commands) == 0
+
+        status = await kv.handle_full_sync_status(FullSyncStatusMsg("i1", 0, "s1"))
+        assert status.is_complete and status.global_progress == 1.0
+
+    @pytest.mark.asyncio
+    async def test_sync_progress_multiple_workers(self, setup):
+        """Test sync progress with multiple workers."""
+        kv, rc = setup
+        workers = [(f"i{i}", i, f"192.168.1.{i + 1}") for i in range(4)]
+
+        for i in range(len(workers)):
+            inst, wid, ip = workers[i]
+            sid = f"s{i}"
+            await H.reg_worker_async(rc, inst, wid, ip)
+            await kv.handle_full_sync_start(H.start_msg(inst, wid, sid, 5, 1))
+
+        for i in range(2):
+            inst, wid, _ = workers[i]
+            sid = f"s{i}"
+            await kv.handle_full_sync_batch(
+                H.batch_msg(inst, wid, sid, 0, list(range(5)))
+            )
+            await kv.handle_full_sync_end(H.end_msg(inst, wid, sid, 5))
+
+        assert kv.full_sync_tracker.get_global_progress() == 0.5
+        assert kv.full_sync_tracker.can_exit_freeze() is True
diff --git a/tests/v1/cache_controller/test_full_sync_sender.py b/tests/v1/cache_controller/test_full_sync_sender.py
new file mode 100644
index 0000000..98176cb
--- /dev/null
+++ b/tests/v1/cache_controller/test_full_sync_sender.py
@@ -0,0 +1,272 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for FullSyncSender."""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.cache_controller.full_sync_sender import FullSyncSender
+from lmcache.v1.cache_controller.message import (
+    FullSyncBatchMsg,
+    FullSyncEndMsg,
+)
+
+# Local
+# Test utilities from conftest
+from .conftest import (
+    H,
+    MockLMCacheEngine,
+    MockLocalCPUBackend,
+    MockWorker,
+    create_test_config,
+    create_test_key,
+)
+
+
+@pytest.fixture
+def full_sync_sender():
+    """Create a FullSyncSender instance for testing."""
+    config = create_test_config()
+    worker = MockWorker()
+    engine = MockLMCacheEngine()
+    backend = MockLocalCPUBackend()
+    sender = FullSyncSender(
+        config=config,
+        worker=worker,
+        lmcache_engine=engine,
+        local_cpu_backend=backend,
+    )
+    return sender, worker, engine, backend
+
+
+class TestFullSyncSenderInit:
+    """Test cases for FullSyncSender initialization."""
+
+    @pytest.mark.parametrize(
+        "batch_size,batch_interval_ms,startup_delay,max_retry",
+        [(100, 0, 0.0, 3), (500, 10, 2.0, 5)],
+    )
+    def test_init_config(self, batch_size, batch_interval_ms, startup_delay, max_retry):
+        """Test initialization with various configs."""
+        config = create_test_config(
+            batch_size=batch_size,
+            batch_interval_ms=batch_interval_ms,
+            startup_delay_s=startup_delay,
+            max_retry_count=max_retry,
+        )
+        sender = FullSyncSender(
+            config=config,
+            worker=MockWorker(),
+            lmcache_engine=MockLMCacheEngine(),
+            local_cpu_backend=MockLocalCPUBackend(),
+        )
+        assert sender.batch_size == batch_size
+        assert sender.batch_interval_ms == batch_interval_ms
+        assert sender.startup_delay_range_s == startup_delay
+        assert sender.max_retry_count == max_retry
+        assert sender._is_syncing is False
+
+
+class TestFullSyncSenderProperties:
+    """Test cases for FullSyncSender properties."""
+
+    @pytest.mark.parametrize(
+        "prop,expected",
+        [
+            ("instance_id", "test_instance"),
+            ("worker_id", 0),
+            ("location", "LocalCPUBackend"),
+            ("is_syncing", False),
+        ],
+    )
+    def test_properties(self, full_sync_sender, prop, expected):
+        """Test all properties."""
+        sender, _, _, _ = full_sync_sender
+        assert getattr(sender, prop) == expected
+
+
+class TestFullSyncSenderSyncId:
+    """Test cases for sync ID generation."""
+
+    def test_generate_sync_id_format_and_uniqueness(self, full_sync_sender):
+        """Test sync ID format and uniqueness."""
+        sender, _, _, _ = full_sync_sender
+        sync_ids = [sender._generate_sync_id() for _ in range(100)]
+
+        # Check format
+        assert all(s.startswith("test_instance_0_") for s in sync_ids)
+        # Check uniqueness
+        assert len(set(sync_ids)) == 100
+
+
+class TestFullSyncSenderGetKeys:
+    """Test cases for getting hot cache keys."""
+
+    @pytest.mark.parametrize("key_count", [0, 10])
+    def test_get_all_hot_cache_keys(self, key_count):
+        """Test getting keys from cache."""
+        test_keys = [create_test_key(i) for i in range(key_count)]
+        sender = FullSyncSender(
+            config=create_test_config(),
+            worker=MockWorker(),
+            lmcache_engine=MockLMCacheEngine(),
+            local_cpu_backend=MockLocalCPUBackend(keys=test_keys),
+        )
+        keys = sender._get_all_hot_cache_keys()
+        assert len(keys) == key_count
+        assert all(isinstance(k, int) for k in keys)
+
+
+class TestFullSyncSenderSendBatch:
+    """Test cases for sending sync batch messages."""
+
+    def test_send_sync_batch(self, full_sync_sender):
+        """Test sending batch messages."""
+        sender, worker, _, _ = full_sync_sender
+
+        for i in range(3):
+            sender._send_sync_batch("sync_123", i, [i * 3, i * 3 + 1, i * 3 + 2])
+
+        assert len(worker.messages) == 3
+        for i, msg in enumerate(worker.messages):
+            assert isinstance(msg, FullSyncBatchMsg)
+            assert msg.sync_id == "sync_123"
+            assert msg.batch_id == i
+
+
+class TestFullSyncSenderSendEnd:
+    """Test cases for sending sync end message."""
+
+    def test_send_sync_end(self, full_sync_sender):
+        """Test sending end message."""
+        sender, worker, _, _ = full_sync_sender
+        sender._send_sync_end("sync_123", 1000)
+
+        assert len(worker.messages) == 1
+        msg = worker.messages[0]
+        assert isinstance(msg, FullSyncEndMsg)
+        assert msg.sync_id == "sync_123"
+        assert msg.actual_total_keys == 1000
+
+
+class TestFullSyncSenderStartSync:
+    """Test cases for the full sync process."""
+
+    @pytest.mark.asyncio
+    async def test_start_full_sync_empty_cache(self, full_sync_sender):
+        """Test full sync with empty cache."""
+        sender, worker, engine, _ = full_sync_sender
+        worker.set_responses([H.start_ret("test"), H.status_ret("test")])
+
+        success = await sender.start_full_sync("test_reason")
+
+        assert success is True
+        assert sender.is_syncing is False
+        assert engine._freeze is False
+
+    @pytest.mark.asyncio
+    async def test_start_full_sync_with_keys(self):
+        """Test full sync with keys in cache."""
+        config = create_test_config(batch_size=5)
+        worker = MockWorker()
+        engine = MockLMCacheEngine()
+        test_keys = [create_test_key(i) for i in range(12)]  # 3 batches
+
+        sender = FullSyncSender(
+            config=config,
+            worker=worker,
+            lmcache_engine=engine,
+            local_cpu_backend=MockLocalCPUBackend(keys=test_keys),
+        )
+        worker.set_responses([H.start_ret("test"), H.status_ret("test")])
+
+        success = await sender.start_full_sync("test_reason")
+
+        assert success is True
+        batch_msgs = [m for m in worker.messages if isinstance(m, FullSyncBatchMsg)]
+        end_msgs = [m for m in worker.messages if isinstance(m, FullSyncEndMsg)]
+        assert len(batch_msgs) == 3
+        assert len(end_msgs) == 1
+
+    @pytest.mark.asyncio
+    async def test_start_full_sync_already_syncing(self, full_sync_sender):
+        """Test that concurrent sync is prevented."""
+        sender, _, _, _ = full_sync_sender
+        sender._is_syncing = True
+
+        assert await sender.start_full_sync("test_reason") is False
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "responses,expected",
+        [
+            # All retries rejected
+            ([H.start_ret("t", False, "Busy")] * 3, False),
+            # First fails, second succeeds
+            (
+                [H.start_ret("t", False, "Busy"), H.start_ret("t"), H.status_ret("t")],
+                True,
+            ),
+        ],
+    )
+    async def test_start_full_sync_retry(self, full_sync_sender, responses, expected):
+        """Test sync retry scenarios."""
+        sender, worker, engine, _ = full_sync_sender
+        worker.set_responses(responses)
+
+        success = await sender.start_full_sync("test_reason")
+
+        assert success is expected
+        assert engine._freeze is False
+
+    @pytest.mark.asyncio
+    async def test_start_full_sync_freeze_mode(self, full_sync_sender):
+        """Test that freeze mode is properly managed."""
+        sender, worker, engine, _ = full_sync_sender
+        worker.set_responses([H.start_ret("test"), H.status_ret("test")])
+
+        await sender.start_full_sync("test_reason")
+
+        assert True in engine.freeze_calls
+        assert False in engine.freeze_calls
+        assert engine.freeze_calls[-1] is False
+
+
+class TestFullSyncSenderMessages:
+    """Test cases for sync message methods."""
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "accepted,error_msg",
+        [(True, None), (False, "Already syncing")],
+    )
+    async def test_send_sync_start(self, full_sync_sender, accepted, error_msg):
+        """Test sync start responses."""
+        sender, worker, _, _ = full_sync_sender
+        worker.set_responses([H.start_ret("sync_123", accepted, error_msg)])
+
+        ret = await sender._send_sync_start("sync_123", 100, 5)
+
+        assert ret.accepted is accepted
+        if error_msg:
+            assert ret.error_msg == error_msg
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "is_complete,progress,can_exit",
+        [(True, 0.85, True), (False, 0.3, False)],
+    )
+    async def test_query_sync_status(
+        self, full_sync_sender, is_complete, progress, can_exit
+    ):
+        """Test sync status queries."""
+        sender, worker, _, _ = full_sync_sender
+        worker.set_responses(
+            [H.status_ret("sync_123", is_complete, progress, can_exit)]
+        )
+
+        ret = await sender._query_sync_status("sync_123")
+
+        assert ret.is_complete is is_complete
+        assert ret.global_progress == progress
+        assert ret.can_exit_freeze is can_exit
diff --git a/tests/v1/cache_controller/test_kv_controller.py b/tests/v1/cache_controller/test_kv_controller.py
new file mode 100644
index 0000000..77d9f08
--- /dev/null
+++ b/tests/v1/cache_controller/test_kv_controller.py
@@ -0,0 +1,721 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for KVController."""
+
+# Standard
+from unittest.mock import Mock, patch
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.cache_controller.controllers.kv_controller import KVController
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    BatchedP2PLookupMsg,
+    CheckFinishMsg,
+    ClearMsg,
+    CompressMsg,
+    DecompressMsg,
+    KVOpEvent,
+    LookupMsg,
+    MoveMsg,
+    OpType,
+    PinMsg,
+)
+
+
+@pytest.fixture
+def kv_controller(mock_reg_controller, mock_cluster_executor):
+    """Create a KVController instance for testing."""
+    controller = KVController(registry=mock_reg_controller.registry)
+    controller.post_init(
+        reg_controller=mock_reg_controller,
+        cluster_executor=mock_cluster_executor,
+    )
+    return controller
+
+
+class TestKVControllerAdmit:
+    """Test KVController admit operations."""
+
+    @pytest.mark.asyncio
+    async def test_admit_new_key(self, kv_controller):
+        """Test admitting a new KV chunk to the controller."""
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        # Access kv_pool through the registry mock
+        report_id = ("test_instance", 0)
+        assert report_id in kv_controller.registry.kv_pool
+        assert "LocalCPUBackend" in kv_controller.registry.kv_pool[report_id]
+        assert 12345 in kv_controller.registry.kv_pool[report_id]["LocalCPUBackend"]
+
+    @pytest.mark.asyncio
+    async def test_admit_duplicate_key(self, kv_controller):
+        """Test admitting same key to different instances."""
+        msg1 = BatchedKVOperationMsg(
+            instance_id="instance1",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+        msg2 = BatchedKVOperationMsg(
+            instance_id="instance2",
+            worker_id=1,
+            location="LocalDiskBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+
+        await kv_controller.handle_batched_kv_operations(msg1)
+        await kv_controller.handle_batched_kv_operations(msg2)
+
+        report_id1 = ("instance1", 0)
+        report_id2 = ("instance2", 1)
+        assert 12345 in kv_controller.registry.kv_pool[report_id1]["LocalCPUBackend"]
+        assert 12345 in kv_controller.registry.kv_pool[report_id2]["LocalDiskBackend"]
+
+    @pytest.mark.asyncio
+    async def test_admit_multiple_keys(self, kv_controller):
+        """Test admitting multiple different keys."""
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=1000 + i, seq_num=i + 1)
+            for i in range(5)
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        report_id = ("test_instance", 0)
+        assert report_id in kv_controller.registry.kv_pool
+        assert "LocalCPUBackend" in kv_controller.registry.kv_pool[report_id]
+        for i in range(5):
+            assert (1000 + i) in kv_controller.registry.kv_pool[report_id][
+                "LocalCPUBackend"
+            ]
+
+
+class TestKVControllerEvict:
+    """Test KVController evict operations."""
+
+    @pytest.mark.asyncio
+    async def test_evict_existing_key(self, kv_controller):
+        """Test evicting an existing KV chunk."""
+        # First admit
+        admit_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+        await kv_controller.handle_batched_kv_operations(admit_msg)
+
+        # Then evict
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.EVICT, key=12345, seq_num=2)],
+        )
+        await kv_controller.handle_batched_kv_operations(evict_msg)
+
+        report_id = ("test_instance", 0)
+        assert (
+            report_id not in kv_controller.registry.kv_pool
+            or 12345
+            not in kv_controller.registry.kv_pool.get(report_id, {}).get(
+                "LocalCPUBackend", set()
+            )
+        )
+
+    @pytest.mark.asyncio
+    async def test_evict_nonexistent_key(self, kv_controller):
+        """Test evicting a non-existent key does nothing."""
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.EVICT, key=99999, seq_num=1)],
+        )
+
+        # Should not raise an error
+        await kv_controller.handle_batched_kv_operations(evict_msg)
+        # Verify key doesn't exist in registry
+        result = kv_controller.registry.find_kv(99999)
+        assert result is None
+
+    @pytest.mark.asyncio
+    async def test_evict_partial_metadata(self, kv_controller):
+        """Test evicting from one instance while another instance still has it."""
+        # Admit two entries for the same key from different instances
+        msg1 = BatchedKVOperationMsg(
+            instance_id="instance1",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+        msg2 = BatchedKVOperationMsg(
+            instance_id="instance2",
+            worker_id=1,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+        await kv_controller.handle_batched_kv_operations(msg1)
+        await kv_controller.handle_batched_kv_operations(msg2)
+
+        # Evict only from the first instance
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="instance1",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.EVICT, key=12345, seq_num=2)],
+        )
+        await kv_controller.handle_batched_kv_operations(evict_msg)
+
+        # Key should still exist in instance2
+        report_id1 = ("instance1", 0)
+        report_id2 = ("instance2", 1)
+        assert (
+            report_id1 not in kv_controller.registry.kv_pool
+            or 12345
+            not in kv_controller.registry.kv_pool[report_id1].get(
+                "LocalCPUBackend", set()
+            )
+        )
+        assert 12345 in kv_controller.registry.kv_pool[report_id2]["LocalCPUBackend"]
+
+    @pytest.mark.asyncio
+    async def test_evict_by_location(self, kv_controller):
+        """Test evicting only matches specific location."""
+        # Admit same key to different locations
+        msg1 = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+        msg2 = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalDiskBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=2)],
+        )
+        await kv_controller.handle_batched_kv_operations(msg1)
+        await kv_controller.handle_batched_kv_operations(msg2)
+
+        # Evict only from CPU backend
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.EVICT, key=12345, seq_num=3)],
+        )
+        await kv_controller.handle_batched_kv_operations(evict_msg)
+
+        # Key should still exist in disk backend
+        report_id = ("test_instance", 0)
+        assert report_id in kv_controller.registry.kv_pool
+        assert "LocalDiskBackend" in kv_controller.registry.kv_pool[report_id]
+        assert 12345 in kv_controller.registry.kv_pool[report_id]["LocalDiskBackend"]
+        assert (
+            "LocalCPUBackend" not in kv_controller.registry.kv_pool[report_id]
+            or 12345 not in kv_controller.registry.kv_pool[report_id]["LocalCPUBackend"]
+        )
+
+
+class TestKVControllerSequenceTracking:
+    """Test KVController sequence number tracking."""
+
+    @pytest.mark.asyncio
+    async def test_sequence_number_first_message(self, kv_controller):
+        """Test first message from a source initializes sequence tracker."""
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=5)],
+        )
+
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        seq_num = kv_controller.reg_controller.registry.get_seq_num(
+            "test_instance", 0, "LocalCPUBackend"
+        )
+        assert seq_num == 5
+
+    @pytest.mark.asyncio
+    async def test_sequence_number_continuous(self, kv_controller):
+        """Test continuous sequence numbers don't trigger warnings."""
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=12345 + i, seq_num=i)
+            for i in range(1, 6)
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        seq_num = kv_controller.reg_controller.registry.get_seq_num(
+            "test_instance", 0, "LocalCPUBackend"
+        )
+        assert seq_num == 5
+        # Sequence discontinuity is now tracked in the registry
+        assert kv_controller.registry.get_seq_discontinuity_count() == 0
+
+    @pytest.mark.asyncio
+    async def test_sequence_discontinuity_detection(self, kv_controller):
+        """Test detection of gaps in sequence numbers."""
+        # First message
+        msg1 = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12345, seq_num=1)],
+        )
+        await kv_controller.handle_batched_kv_operations(msg1)
+
+        # Skip to sequence 5 (gap of 3)
+        msg2 = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=12346, seq_num=5)],
+        )
+        await kv_controller.handle_batched_kv_operations(msg2)
+
+        # Sequence discontinuity is now tracked in the registry
+        assert kv_controller.registry.get_seq_discontinuity_count() == 1
+        seq_num = kv_controller.reg_controller.registry.get_seq_num(
+            "test_instance", 0, "LocalCPUBackend"
+        )
+        assert seq_num == 5
+
+    @pytest.mark.asyncio
+    async def test_sequence_tracking_per_source(self, kv_controller):
+        """Test sequence tracking is independent per source."""
+        # Different sources should have independent tracking
+        msg1 = BatchedKVOperationMsg(
+            instance_id="instance1",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=100, seq_num=1)],
+        )
+        msg2 = BatchedKVOperationMsg(
+            instance_id="instance2",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=200, seq_num=1)],
+        )
+
+        await kv_controller.handle_batched_kv_operations(msg1)
+        await kv_controller.handle_batched_kv_operations(msg2)
+
+        seq_num1 = kv_controller.reg_controller.registry.get_seq_num(
+            "instance1", 0, "LocalCPUBackend"
+        )
+        seq_num2 = kv_controller.reg_controller.registry.get_seq_num(
+            "instance2", 0, "LocalCPUBackend"
+        )
+
+        assert seq_num1 == 1
+        assert seq_num2 == 1
+
+
+class TestKVControllerLookup:
+    """Test KVController lookup operations."""
+
+    @pytest.mark.asyncio
+    async def test_lookup_hit(self, kv_controller):
+        """Test successful lookup with prefix match."""
+        # Admit some chunks
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=1000 + i, seq_num=i + 1)
+            for i in range(3)
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        # Mock token database to return our keys
+        with patch.object(
+            kv_controller.token_database, "process_tokens"
+        ) as mock_process:
+            mock_process.return_value = [
+                (0, 256, 1000),
+                (256, 512, 1001),
+                (512, 768, 1002),
+            ]
+
+            lookup_msg = LookupMsg(
+                event_id="event_123",
+                tokens=list(range(768)),
+            )
+
+            result = await kv_controller.lookup(lookup_msg)
+
+            assert result.event_id == "event_123"
+            assert "test_instance" in result.layout_info
+            assert result.layout_info["test_instance"] == ("LocalCPUBackend", 768)
+
+    @pytest.mark.asyncio
+    async def test_lookup_miss(self, kv_controller):
+        """Test lookup with no matches."""
+        with patch.object(
+            kv_controller.token_database, "process_tokens"
+        ) as mock_process:
+            mock_process.return_value = [(0, 256, 9999)]
+
+            lookup_msg = LookupMsg(
+                event_id="event_123",
+                tokens=list(range(256)),
+            )
+
+            result = await kv_controller.lookup(lookup_msg)
+
+            assert result.event_id == "event_123"
+            assert len(result.layout_info) == 0
+
+    @pytest.mark.asyncio
+    async def test_lookup_partial_match(self, kv_controller):
+        """Test lookup with partial prefix match."""
+        # Admit only first chunk
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=1000, seq_num=1)],
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        with patch.object(
+            kv_controller.token_database, "process_tokens"
+        ) as mock_process:
+            # Return two chunks but only first exists
+            mock_process.return_value = [
+                (0, 256, 1000),
+                (256, 512, 1001),  # This doesn't exist
+            ]
+
+            lookup_msg = LookupMsg(
+                event_id="event_123",
+                tokens=list(range(512)),
+            )
+
+            result = await kv_controller.lookup(lookup_msg)
+
+            # Should only match up to first chunk
+            assert "test_instance" in result.layout_info
+            assert result.layout_info["test_instance"] == ("LocalCPUBackend", 256)
+
+
+class TestKVControllerBatchedP2PLookup:
+    """Test KVController batched P2P lookup operations."""
+
+    @pytest.mark.asyncio
+    async def test_batched_p2p_lookup_success(self, kv_controller):
+        """Test successful batched P2P lookup."""
+        # Admit chunks from different instance
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=1000 + i, seq_num=i + 1)
+            for i in range(3)
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="remote_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        # Query from different instance
+        lookup_msg = BatchedP2PLookupMsg(
+            hashes=[1000, 1001, 1002],
+            instance_id="query_instance",
+            worker_id=0,
+        )
+
+        result = await kv_controller.batched_p2p_lookup(lookup_msg)
+
+        assert len(result.layout_info) == 1
+        instance_id, location, num_hits, peer_url = result.layout_info[0]
+        assert instance_id == "remote_instance"
+        assert location == "LocalCPUBackend"
+        assert num_hits == 3
+        assert peer_url == "tcp://localhost:5000"
+
+    @pytest.mark.asyncio
+    async def test_batched_p2p_lookup_no_match(self, kv_controller):
+        """Test batched P2P lookup with no matches."""
+        lookup_msg = BatchedP2PLookupMsg(
+            hashes=[9999, 9998, 9997],
+            instance_id="query_instance",
+            worker_id=0,
+        )
+
+        result = await kv_controller.batched_p2p_lookup(lookup_msg)
+
+        assert len(result.layout_info) == 1
+        instance_id, location, num_hits, peer_url = result.layout_info[0]
+        assert instance_id == ""
+        assert location == ""
+        assert num_hits == 0
+        assert peer_url == ""
+
+    @pytest.mark.asyncio
+    async def test_batched_p2p_lookup_same_instance(self, kv_controller):
+        """Test batched P2P lookup filters out same instance."""
+        # Admit chunks from same instance as query
+        msg = BatchedKVOperationMsg(
+            instance_id="query_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=1000, seq_num=1)],
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        lookup_msg = BatchedP2PLookupMsg(
+            hashes=[1000],
+            instance_id="query_instance",
+            worker_id=0,
+        )
+
+        result = await kv_controller.batched_p2p_lookup(lookup_msg)
+
+        # Should not match same instance
+        instance_id, location, num_hits, peer_url = result.layout_info[0]
+        assert instance_id == ""
+        assert location == ""
+        assert num_hits == 0
+        assert peer_url == ""
+
+    @pytest.mark.asyncio
+    async def test_batched_p2p_lookup_partial_match(self, kv_controller):
+        """Test batched P2P lookup with partial matches."""
+        # Admit only first two chunks
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=1000 + i, seq_num=i + 1)
+            for i in range(2)
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="remote_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        # Query for three chunks
+        lookup_msg = BatchedP2PLookupMsg(
+            hashes=[1000, 1001, 1002],
+            instance_id="query_instance",
+            worker_id=0,
+        )
+
+        result = await kv_controller.batched_p2p_lookup(lookup_msg)
+
+        # Should only match first two
+        instance_id, location, num_hits, peer_url = result.layout_info[0]
+        assert num_hits == 2
+
+
+class TestKVControllerDeregister:
+    """Test KVController deregister operations."""
+
+    @pytest.mark.asyncio
+    async def test_deregister_cleanup(self, kv_controller):
+        """Test deregister cleans up KV pool and sequence tracker."""
+        # Admit some chunks
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=1000 + i, seq_num=i + 1)
+            for i in range(3)
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+        await kv_controller.handle_batched_kv_operations(msg)
+
+        # Verify data exists
+        report_id = ("test_instance", 0)
+        assert report_id in kv_controller.registry.kv_pool
+        assert len(kv_controller.registry.kv_pool[report_id]["LocalCPUBackend"]) == 3
+        seq_num = kv_controller.reg_controller.registry.get_seq_num(
+            "test_instance", 0, "LocalCPUBackend"
+        )
+        assert seq_num is not None
+
+        # Deregister directly through registry
+        kv_controller.registry.deregister_worker("test_instance", 0)
+
+        # Verify cleanup
+        assert len(kv_controller.registry.kv_pool) == 0
+        # Note: seq_tracker is managed by registry, cleaned up by deregister_worker
+
+    @pytest.mark.asyncio
+    async def test_deregister_partial_cleanup(self, kv_controller):
+        """Test deregister only removes specific instance-worker."""
+        # Admit chunks from different workers
+        msg1 = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=1000, seq_num=1)],
+        )
+        msg2 = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=1,
+            location="LocalCPUBackend",
+            operations=[KVOpEvent(op_type=OpType.ADMIT, key=1000, seq_num=1)],
+        )
+
+        await kv_controller.handle_batched_kv_operations(msg1)
+        await kv_controller.handle_batched_kv_operations(msg2)
+
+        # Deregister only worker 0 directly through registry
+        kv_controller.registry.deregister_worker("test_instance", 0)
+
+        # Worker 1's data should remain
+        report_id1 = ("test_instance", 1)
+        assert report_id1 in kv_controller.registry.kv_pool
+        assert 1000 in kv_controller.registry.kv_pool[report_id1]["LocalCPUBackend"]
+
+
+class TestKVControllerDelegation:
+    """Test KVController delegation to cluster executor."""
+
+    @pytest.mark.asyncio
+    async def test_clear_delegates_to_executor(self, kv_controller):
+        """Test clear operation delegates to cluster executor."""
+        msg = ClearMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            location="LocalCPUBackend",
+        )
+
+        await kv_controller.clear(msg)
+
+        kv_controller.cluster_executor.execute.assert_called_once_with("clear", msg)
+
+    @pytest.mark.asyncio
+    async def test_pin_delegates_to_executor(self, kv_controller):
+        """Test pin operation delegates to cluster executor."""
+        msg = PinMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        await kv_controller.pin(msg)
+
+        kv_controller.cluster_executor.execute.assert_called_once_with("pin", msg)
+
+    @pytest.mark.asyncio
+    async def test_compress_delegates_to_executor(self, kv_controller):
+        """Test compress operation delegates to cluster executor."""
+        msg = CompressMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        await kv_controller.compress(msg)
+
+        kv_controller.cluster_executor.execute.assert_called_once_with("compress", msg)
+
+    @pytest.mark.asyncio
+    async def test_decompress_delegates_to_executor(self, kv_controller):
+        """Test decompress operation delegates to cluster executor."""
+        msg = DecompressMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        await kv_controller.decompress(msg)
+
+        kv_controller.cluster_executor.execute.assert_called_once_with(
+            "decompress", msg
+        )
+
+    @pytest.mark.asyncio
+    async def test_move_delegates_to_executor(self, kv_controller):
+        """Test move operation delegates to cluster executor."""
+        msg = MoveMsg(
+            event_id="event_123",
+            old_position=("instance1", "LocalCPUBackend"),
+            new_position=("instance2", "LocalCPUBackend"),
+            tokens=[1, 2, 3],
+            copy=False,
+        )
+
+        await kv_controller.move(msg)
+
+        kv_controller.cluster_executor.execute.assert_called_once_with("move", msg)
+
+    @pytest.mark.asyncio
+    async def test_check_finish_delegates_to_executor(self, kv_controller):
+        """Test check_finish operation delegates to cluster executor."""
+        msg = CheckFinishMsg(event_id="event_123")
+
+        await kv_controller.check_finish(msg)
+
+        kv_controller.cluster_executor.execute.assert_called_once_with(
+            "check_finish", msg
+        )
+
+
+class TestKVControllerMetrics:
+    """Test KVController metrics setup."""
+
+    @patch("lmcache.v1.cache_controller.controllers.kv_controller.PrometheusLogger")
+    def test_metrics_setup(
+        self, mock_prometheus_logger, mock_reg_controller, mock_cluster_executor
+    ):
+        """Test metrics are properly set up."""
+        mock_logger_instance = Mock()
+        mock_prometheus_logger.GetInstanceOrNone.return_value = mock_logger_instance
+
+        _controller = KVController(registry=mock_reg_controller.registry)
+        _controller.post_init(
+            reg_controller=mock_reg_controller,
+            cluster_executor=mock_cluster_executor,
+        )
+
+        # Verify metrics functions were set
+        mock_logger_instance.kv_pool_keys_count.set_function.assert_called_once()
+        mock_logger_instance.kv_op_seq_discontinuity_count.set_function.assert_called_once()
+
+    @patch("lmcache.v1.cache_controller.controllers.kv_controller.PrometheusLogger")
+    def test_metrics_setup_no_logger(
+        self, mock_prometheus_logger, mock_reg_controller, mock_cluster_executor
+    ):
+        """Test metrics setup when no logger is available."""
+        mock_prometheus_logger.GetInstanceOrNone.return_value = None
+
+        # Should not raise an error
+        controller = KVController(registry=mock_reg_controller.registry)
+
+        assert controller is not None
diff --git a/tests/v1/cache_controller/test_locks.py b/tests/v1/cache_controller/test_locks.py
new file mode 100644
index 0000000..a6b9111
--- /dev/null
+++ b/tests/v1/cache_controller/test_locks.py
@@ -0,0 +1,347 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for lock utilities in lmcache.v1.cache_controller.locks.
+
+Tests cover RWLockWithTimeout and FastLockWithTimeout classes.
+"""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+import threading
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.cache_controller.locks import (
+    FastLockWithTimeout,
+    RWLockTimeoutError,
+    RWLockWithTimeout,
+)
+
+
+class TestRWLockWithTimeout:
+    """Test cases for RWLockWithTimeout."""
+
+    def test_basic_read_lock(self):
+        """Test basic read lock acquisition and release."""
+        lock = RWLockWithTimeout()
+        assert lock.acquire_read(timeout=1.0)
+        lock.release_read()
+
+    def test_basic_write_lock(self):
+        """Test basic write lock acquisition and release."""
+        lock = RWLockWithTimeout()
+        assert lock.acquire_write(timeout=1.0)
+        lock.release_write()
+
+    def test_multiple_readers(self):
+        """Test multiple readers can hold the lock simultaneously."""
+        lock = RWLockWithTimeout()
+        results = []
+
+        def reader(reader_id):
+            assert lock.acquire_read(timeout=1.0)
+            results.append(("acquired", reader_id))
+            time.sleep(0.05)
+            results.append(("released", reader_id))
+            lock.release_read()
+
+        threads = [threading.Thread(target=reader, args=(i,)) for i in range(5)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All readers should have acquired locks concurrently
+        assert len(results) == 10
+        acquired_count = sum(1 for r in results if r[0] == "acquired")
+        assert acquired_count == 5
+
+    def test_writer_exclusive(self):
+        """Test writer has exclusive access."""
+        lock = RWLockWithTimeout()
+        write_start = []
+        write_end = []
+
+        def writer(writer_id):
+            assert lock.acquire_write(timeout=2.0)
+            write_start.append(writer_id)
+            time.sleep(0.05)
+            write_end.append(writer_id)
+            lock.release_write()
+
+        threads = [threading.Thread(target=writer, args=(i,)) for i in range(3)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # Writers should have executed sequentially
+        assert len(write_start) == 3
+        assert len(write_end) == 3
+
+    def test_writer_blocks_readers(self):
+        """Test that a writer blocks new readers."""
+        lock = RWLockWithTimeout()
+        events = []
+        barrier = threading.Barrier(2)
+
+        def writer():
+            barrier.wait()
+            assert lock.acquire_write(timeout=2.0)
+            events.append("writer_acquired")
+            time.sleep(0.1)
+            events.append("writer_released")
+            lock.release_write()
+
+        def reader():
+            barrier.wait()
+            time.sleep(0.02)  # Let writer get the lock first
+            assert lock.acquire_read(timeout=2.0)
+            events.append("reader_acquired")
+            lock.release_read()
+
+        t1 = threading.Thread(target=writer)
+        t2 = threading.Thread(target=reader)
+        t1.start()
+        t2.start()
+        t1.join()
+        t2.join()
+
+        # Reader should acquire after writer releases
+        writer_released_idx = events.index("writer_released")
+        reader_acquired_idx = events.index("reader_acquired")
+        assert reader_acquired_idx > writer_released_idx
+
+    def test_read_lock_timeout(self):
+        """Test read lock timeout when writer holds the lock."""
+        lock = RWLockWithTimeout()
+        lock.acquire_write()
+
+        def try_read():
+            return lock.acquire_read(timeout=0.05)
+
+        result = try_read()
+        lock.release_write()
+
+        assert result is False
+
+    def test_write_lock_timeout(self):
+        """Test write lock timeout when another writer holds the lock."""
+        lock = RWLockWithTimeout()
+        lock.acquire_write()
+
+        def try_write():
+            return lock.acquire_write(timeout=0.05)
+
+        result = try_write()
+        lock.release_write()
+
+        assert result is False
+
+    def test_read_lock_context_manager(self):
+        """Test read lock context manager."""
+        lock = RWLockWithTimeout()
+        with lock.read_lock(timeout=1.0):
+            pass  # Should not raise
+
+    def test_write_lock_context_manager(self):
+        """Test write lock context manager."""
+        lock = RWLockWithTimeout()
+        with lock.write_lock(timeout=1.0):
+            pass  # Should not raise
+
+    def test_read_lock_context_manager_timeout(self):
+        """Test read lock context manager raises on timeout."""
+        lock = RWLockWithTimeout()
+        lock.acquire_write()
+
+        with pytest.raises(RWLockTimeoutError):
+            with lock.read_lock(timeout=0.01):
+                pass
+
+        lock.release_write()
+
+    def test_write_lock_context_manager_timeout(self):
+        """Test write lock context manager raises on timeout."""
+        lock = RWLockWithTimeout()
+        lock.acquire_write()
+
+        with pytest.raises(RWLockTimeoutError):
+            with lock.write_lock(timeout=0.01):
+                pass
+
+        lock.release_write()
+
+    def test_concurrent_read_write_operations(self):
+        """Test concurrent read and write operations maintain consistency."""
+        lock = RWLockWithTimeout()
+        shared_value = [0]
+        errors = []
+
+        def reader(reader_id):
+            for _ in range(20):
+                with lock.read_lock(timeout=1.0):
+                    val = shared_value[0]
+                    time.sleep(0.001)
+                    if shared_value[0] != val:
+                        errors.append(
+                            "Value changed during read for reader %d" % reader_id
+                        )
+
+        def writer(writer_id):
+            for _ in range(10):
+                with lock.write_lock(timeout=1.0):
+                    shared_value[0] += 1
+                    time.sleep(0.002)
+
+        threads = []
+        for i in range(5):
+            threads.append(threading.Thread(target=reader, args=(i,)))
+        for i in range(3):
+            threads.append(threading.Thread(target=writer, args=(i,)))
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+        assert shared_value[0] == 30
+
+    def test_writers_waiting_priority(self):
+        """Test that waiting writers get priority over new readers."""
+        lock = RWLockWithTimeout()
+        events = []
+        reader_started = threading.Event()
+        writer_waiting = threading.Event()
+
+        def first_reader():
+            with lock.read_lock(timeout=1.0):
+                events.append("reader1_acquired")
+                reader_started.set()
+                writer_waiting.wait(timeout=1.0)
+                time.sleep(0.05)
+                events.append("reader1_released")
+
+        def writer():
+            reader_started.wait(timeout=1.0)
+            writer_waiting.set()
+            with lock.write_lock(timeout=2.0):
+                events.append("writer_acquired")
+                events.append("writer_released")
+
+        def second_reader():
+            writer_waiting.wait(timeout=1.0)
+            time.sleep(0.01)  # Give writer time to start waiting
+            with lock.read_lock(timeout=2.0):
+                events.append("reader2_acquired")
+
+        t1 = threading.Thread(target=first_reader)
+        t2 = threading.Thread(target=writer)
+        t3 = threading.Thread(target=second_reader)
+
+        t1.start()
+        t2.start()
+        t3.start()
+
+        t1.join(timeout=3.0)
+        t2.join(timeout=3.0)
+        t3.join(timeout=3.0)
+
+        # Writer should get priority over second reader
+        writer_idx = events.index("writer_acquired")
+        reader2_idx = events.index("reader2_acquired")
+        assert writer_idx < reader2_idx
+
+
+class TestFastLockWithTimeout:
+    """Test cases for FastLockWithTimeout."""
+
+    def test_basic_acquire_release(self):
+        """Test basic lock acquisition and release."""
+        lock = FastLockWithTimeout()
+        assert lock.acquire(timeout=1.0)
+        lock.release()
+
+    def test_acquire_without_timeout(self):
+        """Test lock acquisition without timeout."""
+        lock = FastLockWithTimeout()
+        assert lock.acquire()
+        lock.release()
+
+    def test_context_manager(self):
+        """Test lock context manager."""
+        lock = FastLockWithTimeout()
+        with lock:
+            pass  # Should not raise
+
+    def test_context_manager_timeout(self):
+        """Test lock context manager raises on timeout."""
+        lock = FastLockWithTimeout()
+        lock.acquire()
+
+        def try_context():
+            with lock:
+                pass
+
+        # Run in a thread to avoid blocking forever
+        thread = threading.Thread(target=try_context)
+        thread.start()
+        thread.join(timeout=0.2)
+
+        lock.release()
+
+        # The thread should have timed out and raised RWLockTimeoutError
+        assert not thread.is_alive() or True  # Thread may still be alive briefly
+
+    def test_mutual_exclusion(self):
+        """Test that lock provides mutual exclusion."""
+        lock = FastLockWithTimeout()
+        shared_value = [0]
+
+        def incrementer(inc_id):
+            for _ in range(100):
+                with lock:
+                    val = shared_value[0]
+                    time.sleep(0.0001)
+                    shared_value[0] = val + 1
+
+        threads = [threading.Thread(target=incrementer, args=(i,)) for i in range(5)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert shared_value[0] == 500
+
+    def test_acquire_timeout(self):
+        """Test lock acquisition timeout."""
+        lock = FastLockWithTimeout()
+        lock.acquire()
+
+        result = lock.acquire(timeout=0.05)
+        lock.release()
+
+        assert result is False
+
+    def test_high_contention(self):
+        """Test lock under high contention."""
+        lock = FastLockWithTimeout()
+        counter = [0]
+        num_threads = 20
+        increments_per_thread = 50
+
+        def worker():
+            for _ in range(increments_per_thread):
+                with lock:
+                    counter[0] += 1
+
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [executor.submit(worker) for _ in range(num_threads)]
+            for f in futures:
+                f.result()
+
+        assert counter[0] == num_threads * increments_per_thread
diff --git a/tests/v1/cache_controller/test_messages.py b/tests/v1/cache_controller/test_messages.py
new file mode 100644
index 0000000..b7e6aaf
--- /dev/null
+++ b/tests/v1/cache_controller/test_messages.py
@@ -0,0 +1,739 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for cache controller message serialization and deserialization."""
+
+# Standard
+import time
+
+# Third Party
+import msgspec
+
+# First Party
+from lmcache.v1.cache_controller.message import (
+    BatchedKVOperationMsg,
+    BatchedP2PLookupMsg,
+    BatchedP2PLookupRetMsg,
+    CheckFinishMsg,
+    CheckFinishRetMsg,
+    ClearMsg,
+    ClearRetMsg,
+    ClearWorkerMsg,
+    ClearWorkerRetMsg,
+    CompressMsg,
+    CompressRetMsg,
+    CompressWorkerMsg,
+    CompressWorkerRetMsg,
+    DecompressMsg,
+    DecompressRetMsg,
+    DecompressWorkerMsg,
+    DecompressWorkerRetMsg,
+    DeRegisterMsg,
+    ErrorMsg,
+    HealthMsg,
+    HealthRetMsg,
+    HealthWorkerMsg,
+    HealthWorkerRetMsg,
+    HeartbeatMsg,
+    KVAdmitMsg,
+    KVEvictMsg,
+    KVOpEvent,
+    LookupMsg,
+    LookupRetMsg,
+    MoveMsg,
+    MoveRetMsg,
+    MoveWorkerMsg,
+    MoveWorkerRetMsg,
+    Msg,
+    OpType,
+    PinMsg,
+    PinRetMsg,
+    PinWorkerMsg,
+    PinWorkerRetMsg,
+    QueryInstMsg,
+    QueryInstRetMsg,
+    QueryWorkerInfoMsg,
+    QueryWorkerInfoRetMsg,
+    RegisterMsg,
+)
+from lmcache.v1.cache_controller.utils import WorkerInfo
+
+
+class TestWorkerMessages:
+    """Test worker message serialization."""
+
+    def test_register_msg_serialization(self):
+        """Test RegisterMsg encode/decode."""
+        msg = RegisterMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+            peer_init_url="tcp://127.0.0.1:6000",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, RegisterMsg)
+        assert decoded.instance_id == "test_instance"
+        assert decoded.worker_id == 0
+        assert decoded.ip == "127.0.0.1"
+        assert decoded.port == 5000
+        assert decoded.peer_init_url == "tcp://127.0.0.1:6000"
+
+    def test_register_msg_without_peer_url(self):
+        """Test RegisterMsg without peer_init_url."""
+        msg = RegisterMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+            peer_init_url=None,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, RegisterMsg)
+        assert decoded.peer_init_url is None
+
+    def test_deregister_msg_serialization(self):
+        """Test DeRegisterMsg encode/decode."""
+        msg = DeRegisterMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, DeRegisterMsg)
+        assert decoded.instance_id == "test_instance"
+        assert decoded.worker_id == 0
+
+    def test_kv_admit_msg_serialization(self):
+        """Test KVAdmitMsg encode/decode."""
+        msg = KVAdmitMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            key=12345,
+            location="LocalCPUBackend",
+            seq_num=1,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, KVAdmitMsg)
+        assert decoded.instance_id == "test_instance"
+        assert decoded.worker_id == 0
+        assert decoded.key == 12345
+        assert decoded.location == "LocalCPUBackend"
+        assert decoded.seq_num == 1
+
+    def test_kv_evict_msg_serialization(self):
+        """Test KVEvictMsg encode/decode."""
+        msg = KVEvictMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            key=12345,
+            location="LocalCPUBackend",
+            seq_num=2,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, KVEvictMsg)
+        assert decoded.key == 12345
+        assert decoded.seq_num == 2
+
+    def test_batched_kv_operation_msg(self):
+        """Test BatchedKVOperationMsg encode/decode."""
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=100, seq_num=1),
+            KVOpEvent(op_type=OpType.EVICT, key=200, seq_num=2),
+            KVOpEvent(op_type=OpType.ADMIT, key=300, seq_num=3),
+        ]
+
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            location="LocalCPUBackend",
+            operations=operations,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, BatchedKVOperationMsg)
+        assert decoded.instance_id == "test_instance"
+        assert decoded.worker_id == 0
+        assert decoded.location == "LocalCPUBackend"
+        assert len(decoded.operations) == 3
+        assert decoded.operations[0].op_type == OpType.ADMIT
+        assert decoded.operations[0].key == 100
+        assert decoded.operations[1].op_type == OpType.EVICT
+        assert decoded.operations[1].key == 200
+
+    def test_heartbeat_msg_serialization(self):
+        """Test HeartbeatMsg encode/decode."""
+        msg = HeartbeatMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+            peer_init_url="tcp://127.0.0.1:6000",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, HeartbeatMsg)
+        assert decoded.instance_id == "test_instance"
+
+    def test_batched_p2p_lookup_msg(self):
+        """Test BatchedP2PLookupMsg encode/decode."""
+        msg = BatchedP2PLookupMsg(
+            hashes=[100, 200, 300],
+            instance_id="test_instance",
+            worker_id=0,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, BatchedP2PLookupMsg)
+        assert decoded.hashes == [100, 200, 300]
+        assert decoded.instance_id == "test_instance"
+        assert decoded.worker_id == 0
+
+
+class TestControlMessages:
+    """Test control message serialization."""
+
+    def test_clear_worker_msg_serialization(self):
+        """Test ClearWorkerMsg encode/decode."""
+        msg = ClearWorkerMsg(
+            worker_event_id="event_123",
+            location="LocalCPUBackend",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, ClearWorkerMsg)
+        assert decoded.worker_event_id == "event_123"
+        assert decoded.location == "LocalCPUBackend"
+
+    def test_pin_worker_msg_serialization(self):
+        """Test PinWorkerMsg encode/decode."""
+        msg = PinWorkerMsg(
+            worker_event_id="event_123",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3, 4, 5],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, PinWorkerMsg)
+        assert decoded.tokens == [1, 2, 3, 4, 5]
+
+    def test_compress_worker_msg_serialization(self):
+        """Test CompressWorkerMsg encode/decode."""
+        msg = CompressWorkerMsg(
+            worker_event_id="event_123",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CompressWorkerMsg)
+        assert decoded.method == "gzip"
+        assert decoded.tokens == [1, 2, 3]
+
+    def test_compress_worker_msg_without_tokens(self):
+        """Test CompressWorkerMsg without tokens (compress all)."""
+        msg = CompressWorkerMsg(
+            worker_event_id="event_123",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=None,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CompressWorkerMsg)
+        assert decoded.tokens is None
+
+    def test_decompress_worker_msg_serialization(self):
+        """Test DecompressWorkerMsg encode/decode."""
+        msg = DecompressWorkerMsg(
+            worker_event_id="event_123",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, DecompressWorkerMsg)
+        assert decoded.method == "gzip"
+
+    def test_move_worker_msg_serialization(self):
+        """Test MoveWorkerMsg encode/decode."""
+        msg = MoveWorkerMsg(
+            worker_event_id="event_123",
+            old_position="LocalDiskBackend",
+            new_position=("tcp://127.0.0.1:5000", "LocalCPUBackend"),
+            tokens=[1, 2, 3],
+            copy=True,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, MoveWorkerMsg)
+        assert decoded.old_position == "LocalDiskBackend"
+        assert decoded.new_position == ("tcp://127.0.0.1:5000", "LocalCPUBackend")
+        assert decoded.copy is True
+
+    def test_health_worker_msg_serialization(self):
+        """Test HealthWorkerMsg encode/decode."""
+        msg = HealthWorkerMsg(worker_event_id="event_123")
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, HealthWorkerMsg)
+        assert decoded.worker_event_id == "event_123"
+
+
+class TestOrchestrationMessages:
+    """Test orchestration message serialization."""
+
+    def test_lookup_msg_serialization(self):
+        """Test LookupMsg encode/decode."""
+        msg = LookupMsg(
+            event_id="event_123",
+            tokens=[1, 2, 3, 4, 5],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, LookupMsg)
+        assert decoded.event_id == "event_123"
+        assert decoded.tokens == [1, 2, 3, 4, 5]
+
+    def test_clear_msg_serialization(self):
+        """Test ClearMsg encode/decode."""
+        msg = ClearMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            location="LocalCPUBackend",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, ClearMsg)
+        assert decoded.instance_id == "test_instance"
+        assert decoded.location == "LocalCPUBackend"
+
+    def test_pin_msg_serialization(self):
+        """Test PinMsg encode/decode."""
+        msg = PinMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, PinMsg)
+        assert decoded.tokens == [1, 2, 3]
+
+    def test_compress_msg_serialization(self):
+        """Test CompressMsg encode/decode."""
+        msg = CompressMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=[1, 2, 3],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CompressMsg)
+        assert decoded.method == "gzip"
+
+    def test_decompress_msg_serialization(self):
+        """Test DecompressMsg encode/decode."""
+        msg = DecompressMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            method="gzip",
+            location="LocalCPUBackend",
+            tokens=None,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, DecompressMsg)
+        assert decoded.tokens is None
+
+    def test_move_msg_serialization(self):
+        """Test MoveMsg encode/decode."""
+        msg = MoveMsg(
+            event_id="event_123",
+            old_position=("instance1", "LocalCPUBackend"),
+            new_position=("instance2", "LocalCPUBackend"),
+            tokens=[1, 2, 3],
+            copy=False,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, MoveMsg)
+        assert decoded.old_position == ("instance1", "LocalCPUBackend")
+        assert decoded.new_position == ("instance2", "LocalCPUBackend")
+        assert decoded.copy is False
+
+    def test_health_msg_serialization(self):
+        """Test HealthMsg encode/decode."""
+        msg = HealthMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, HealthMsg)
+        assert decoded.instance_id == "test_instance"
+
+    def test_check_finish_msg_serialization(self):
+        """Test CheckFinishMsg encode/decode."""
+        msg = CheckFinishMsg(event_id="event_123")
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CheckFinishMsg)
+        assert decoded.event_id == "event_123"
+
+    def test_query_inst_msg_serialization(self):
+        """Test QueryInstMsg encode/decode."""
+        msg = QueryInstMsg(
+            event_id="event_123",
+            ip="127.0.0.1",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, QueryInstMsg)
+        assert decoded.ip == "127.0.0.1"
+
+    def test_query_worker_info_msg_serialization(self):
+        """Test QueryWorkerInfoMsg encode/decode."""
+        msg = QueryWorkerInfoMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+            worker_ids=[0, 1, 2],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, QueryWorkerInfoMsg)
+        assert decoded.worker_ids == [0, 1, 2]
+
+
+class TestReturnMessages:
+    """Test return message serialization."""
+
+    def test_lookup_ret_msg_serialization(self):
+        """Test LookupRetMsg encode/decode."""
+        msg = LookupRetMsg(
+            event_id="event_123",
+            layout_info={"instance1": ("LocalCPUBackend", 100)},
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, LookupRetMsg)
+        assert decoded.layout_info == {"instance1": ("LocalCPUBackend", 100)}
+
+    def test_clear_ret_msg_serialization(self):
+        """Test ClearRetMsg encode/decode."""
+        msg = ClearRetMsg(
+            event_id="event_123",
+            num_tokens=100,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, ClearRetMsg)
+        assert decoded.num_tokens == 100
+
+    def test_pin_ret_msg_serialization(self):
+        """Test PinRetMsg encode/decode."""
+        msg = PinRetMsg(
+            event_id="event_123",
+            num_tokens=50,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, PinRetMsg)
+        assert decoded.num_tokens == 50
+
+    def test_compress_ret_msg_serialization(self):
+        """Test CompressRetMsg encode/decode."""
+        msg = CompressRetMsg(
+            event_id="event_123",
+            num_tokens=75,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CompressRetMsg)
+        assert decoded.num_tokens == 75
+
+    def test_decompress_ret_msg_serialization(self):
+        """Test DecompressRetMsg encode/decode."""
+        msg = DecompressRetMsg(
+            event_id="event_123",
+            num_tokens=75,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, DecompressRetMsg)
+        assert decoded.num_tokens == 75
+
+    def test_move_ret_msg_serialization(self):
+        """Test MoveRetMsg encode/decode."""
+        msg = MoveRetMsg(
+            event_id="event_123",
+            num_tokens=200,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, MoveRetMsg)
+        assert decoded.num_tokens == 200
+
+    def test_health_ret_msg_serialization(self):
+        """Test HealthRetMsg encode/decode."""
+        msg = HealthRetMsg(
+            event_id="event_123",
+            error_codes={0: 0, 1: 0, 2: -1},
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, HealthRetMsg)
+        assert decoded.error_codes == {0: 0, 1: 0, 2: -1}
+
+    def test_check_finish_ret_msg_serialization(self):
+        """Test CheckFinishRetMsg encode/decode."""
+        msg = CheckFinishRetMsg(status="completed")
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CheckFinishRetMsg)
+        assert decoded.status == "completed"
+
+    def test_query_inst_ret_msg_serialization(self):
+        """Test QueryInstRetMsg encode/decode."""
+        msg = QueryInstRetMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, QueryInstRetMsg)
+        assert decoded.instance_id == "test_instance"
+
+    def test_query_inst_ret_msg_none_instance(self):
+        """Test QueryInstRetMsg with None instance_id."""
+        msg = QueryInstRetMsg(
+            event_id="event_123",
+            instance_id=None,
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, QueryInstRetMsg)
+        assert decoded.instance_id is None
+
+    def test_query_worker_info_ret_msg_serialization(self):
+        """Test QueryWorkerInfoRetMsg encode/decode."""
+        worker_info = WorkerInfo(
+            instance_id="test_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+            peer_init_url="tcp://127.0.0.1:6000",
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        msg = QueryWorkerInfoRetMsg(
+            event_id="event_123",
+            worker_infos=[worker_info],
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, QueryWorkerInfoRetMsg)
+        assert len(decoded.worker_infos) == 1
+        assert decoded.worker_infos[0].instance_id == "test_instance"
+
+    def test_batched_p2p_lookup_ret_msg(self):
+        """Test BatchedP2PLookupRetMsg encode/decode."""
+        msg = BatchedP2PLookupRetMsg(
+            layout_info=[
+                ("instance1", "LocalCPUBackend", 10, "tcp://127.0.0.1:5000"),
+                ("instance2", "LocalCPUBackend", 5, "tcp://127.0.0.1:5001"),
+            ]
+        )
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, BatchedP2PLookupRetMsg)
+        assert len(decoded.layout_info) == 2
+        assert decoded.layout_info[0][0] == "instance1"
+        assert decoded.layout_info[0][2] == 10
+
+    def test_error_msg_serialization(self):
+        """Test ErrorMsg encode/decode."""
+        msg = ErrorMsg(error="Something went wrong")
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, ErrorMsg)
+        assert decoded.error == "Something went wrong"
+
+
+class TestWorkerReturnMessages:
+    """Test worker return message serialization."""
+
+    def test_clear_worker_ret_msg(self):
+        """Test ClearWorkerRetMsg encode/decode."""
+        msg = ClearWorkerRetMsg(num_tokens=100)
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, ClearWorkerRetMsg)
+        assert decoded.num_tokens == 100
+
+    def test_pin_worker_ret_msg(self):
+        """Test PinWorkerRetMsg encode/decode."""
+        msg = PinWorkerRetMsg(num_tokens=50)
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, PinWorkerRetMsg)
+        assert decoded.num_tokens == 50
+
+    def test_compress_worker_ret_msg(self):
+        """Test CompressWorkerRetMsg encode/decode."""
+        msg = CompressWorkerRetMsg(num_tokens=75)
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, CompressWorkerRetMsg)
+        assert decoded.num_tokens == 75
+
+    def test_decompress_worker_ret_msg(self):
+        """Test DecompressWorkerRetMsg encode/decode."""
+        msg = DecompressWorkerRetMsg(num_tokens=75)
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, DecompressWorkerRetMsg)
+        assert decoded.num_tokens == 75
+
+    def test_move_worker_ret_msg(self):
+        """Test MoveWorkerRetMsg encode/decode."""
+        msg = MoveWorkerRetMsg(num_tokens=200)
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, MoveWorkerRetMsg)
+        assert decoded.num_tokens == 200
+
+    def test_health_worker_ret_msg(self):
+        """Test HealthWorkerRetMsg encode/decode."""
+        msg = HealthWorkerRetMsg(error_code=0)
+
+        encoded = msgspec.msgpack.encode(msg)
+        decoded = msgspec.msgpack.decode(encoded, type=Msg)
+
+        assert isinstance(decoded, HealthWorkerRetMsg)
+        assert decoded.error_code == 0
+
+
+class TestMessageDescribe:
+    """Test message describe() methods."""
+
+    def test_register_msg_describe(self):
+        """Test RegisterMsg describe method."""
+        msg = RegisterMsg(
+            instance_id="test_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+            peer_init_url="tcp://127.0.0.1:6000",
+        )
+        description = msg.describe()
+        assert "test_instance" in description
+        assert "worker" in description.lower()
+
+    def test_lookup_msg_describe(self):
+        """Test LookupMsg describe method."""
+        msg = LookupMsg(event_id="event_123", tokens=[1, 2, 3])
+        description = msg.describe()
+        assert "lookup" in description.lower() or "tokens" in description.lower()
+
+    def test_error_msg_describe(self):
+        """Test ErrorMsg describe method."""
+        msg = ErrorMsg(error="Test error")
+        description = msg.describe()
+        assert "error" in description.lower() or "Test error" in description
diff --git a/tests/v1/cache_controller/test_registration_controller.py b/tests/v1/cache_controller/test_registration_controller.py
new file mode 100644
index 0000000..c286f1b
--- /dev/null
+++ b/tests/v1/cache_controller/test_registration_controller.py
@@ -0,0 +1,628 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for RegistrationController."""
+
+# Standard
+from unittest.mock import Mock, patch
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.cache_controller.controllers.registration_controller import (
+    RegistrationController,
+)
+from lmcache.v1.cache_controller.message import (
+    DeRegisterMsg,
+    HealthMsg,
+    HeartbeatMsg,
+    QueryInstMsg,
+    QueryWorkerInfoMsg,
+    RegisterMsg,
+)
+
+
+@pytest.fixture
+def reg_controller(mock_kv_controller, mock_cluster_executor):
+    """Create a RegistrationController instance for testing."""
+    controller = RegistrationController()
+    controller.post_init(
+        kv_controller=mock_kv_controller,
+        cluster_executor=mock_cluster_executor,
+    )
+    return controller
+
+
+class TestRegistrationControllerRegister:
+    """Test RegistrationController register operations."""
+
+    @pytest.mark.asyncio
+    async def test_register_new_worker(self, reg_controller, mock_zmq_socket):
+        """Test registering a new worker."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+
+            await reg_controller.register(msg)
+
+            # Verify worker is registered
+            worker_ids = reg_controller.registry.get_worker_ids("test_instance")
+            assert 0 in worker_ids
+
+            # Verify socket is created
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is not None
+            assert worker_node.socket is not None
+            assert worker_node.peer_init_url == "tcp://127.0.0.1:6000"
+
+            # Verify instance mapping
+            instance_node = reg_controller.registry.get_instance_by_ip("127.0.0.1")
+            assert instance_node is not None
+            assert instance_node.instance_id == "test_instance"
+
+    @pytest.mark.asyncio
+    async def test_register_without_peer_url(self, reg_controller, mock_zmq_socket):
+        """Test registering a worker without peer_init_url."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url=None,
+            )
+
+            await reg_controller.register(msg)
+
+            # Verify worker is registered
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is not None
+            assert worker_node.socket is not None
+
+            # Peer URL should not be registered
+            assert worker_node.peer_init_url is None
+
+    @pytest.mark.asyncio
+    async def test_register_duplicate_worker(self, reg_controller, mock_zmq_socket):
+        """Test duplicate registration is prevented."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+
+            # Register once
+            await reg_controller.register(msg)
+
+            # Try to register again
+            await reg_controller.register(msg)
+
+            # Should still have only one entry
+            worker_ids = reg_controller.registry.get_worker_ids("test_instance")
+            assert len(worker_ids) == 1
+
+    @pytest.mark.asyncio
+    async def test_register_multiple_workers(self, reg_controller, mock_zmq_socket):
+        """Test registering multiple workers for same instance."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            for worker_id in range(3):
+                msg = RegisterMsg(
+                    instance_id="test_instance",
+                    worker_id=worker_id,
+                    ip="127.0.0.1",
+                    port=5000 + worker_id,
+                    peer_init_url=f"tcp://127.0.0.1:{6000 + worker_id}",
+                )
+                await reg_controller.register(msg)
+
+            # Verify all workers are registered
+            worker_ids = reg_controller.registry.get_worker_ids("test_instance")
+            assert len(worker_ids) == 3
+
+            # Verify workers are sorted
+            assert worker_ids == [0, 1, 2]
+
+    @pytest.mark.asyncio
+    async def test_register_worker_info_timestamps(
+        self, reg_controller, mock_zmq_socket
+    ):
+        """Test worker info contains correct timestamps."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            before_time = time.time()
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+
+            await reg_controller.register(msg)
+
+            after_time = time.time()
+
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is not None
+
+            assert before_time <= worker_node.registration_time <= after_time
+            assert before_time <= worker_node.last_heartbeat_time <= after_time
+
+
+class TestRegistrationControllerDeregister:
+    """Test RegistrationController deregister operations."""
+
+    @pytest.mark.asyncio
+    async def test_deregister_worker(self, reg_controller, mock_zmq_socket):
+        """Test deregistering a worker."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            # First register
+            register_msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+            await reg_controller.register(register_msg)
+
+            # Then deregister
+            deregister_msg = DeRegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+            )
+            await reg_controller.deregister(deregister_msg)
+
+            # Verify cleanup
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is None
+
+            instance_node = reg_controller.registry.get_instance("test_instance")
+            assert instance_node is None
+
+            # Note: KV cleanup is now handled directly by the registry's
+            # deregister_worker method
+
+    @pytest.mark.asyncio
+    async def test_deregister_nonexistent_worker(self, reg_controller):
+        """Test deregistering a non-existent worker."""
+        deregister_msg = DeRegisterMsg(
+            instance_id="nonexistent_instance",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=5000,
+        )
+
+        # Should not raise an error
+        await reg_controller.deregister(deregister_msg)
+
+    @pytest.mark.asyncio
+    async def test_deregister_partial_workers(self, reg_controller, mock_zmq_socket):
+        """Test deregistering one of multiple workers."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            # Register two workers
+            for worker_id in range(2):
+                msg = RegisterMsg(
+                    instance_id="test_instance",
+                    worker_id=worker_id,
+                    ip="127.0.0.1",
+                    port=5000 + worker_id,
+                    peer_init_url=f"tcp://127.0.0.1:{6000 + worker_id}",
+                )
+                await reg_controller.register(msg)
+
+            # Deregister only worker 0
+            deregister_msg = DeRegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+            )
+            await reg_controller.deregister(deregister_msg)
+
+            # Worker 1 should still be registered
+            worker_ids = reg_controller.registry.get_worker_ids("test_instance")
+            assert worker_ids == [1]
+
+            worker_node = reg_controller.registry.get_worker("test_instance", 1)
+            assert worker_node is not None
+            assert worker_node.socket is not None
+
+
+class TestRegistrationControllerGetters:
+    """Test RegistrationController getter methods."""
+
+    @pytest.mark.asyncio
+    async def test_get_socket(self, reg_controller, mock_zmq_socket):
+        """Test getting socket for a worker."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+            await reg_controller.register(msg)
+
+            socket = reg_controller.get_socket("test_instance", 0)
+
+            assert socket is not None
+            assert socket == mock_zmq_socket
+
+    def test_get_socket_nonexistent(self, reg_controller):
+        """Test getting socket for non-existent worker."""
+        socket = reg_controller.get_socket("nonexistent", 0)
+
+        assert socket is None
+
+    @pytest.mark.asyncio
+    async def test_get_peer_init_url(self, reg_controller, mock_zmq_socket):
+        """Test getting peer init URL for a worker."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+            await reg_controller.register(msg)
+
+            url = reg_controller.get_peer_init_url("test_instance", 0)
+
+            assert url == "tcp://127.0.0.1:6000"
+
+    def test_get_peer_init_url_nonexistent(self, reg_controller):
+        """Test getting peer init URL for non-existent worker."""
+        url = reg_controller.get_peer_init_url("nonexistent", 0)
+
+        assert url is None
+
+    @pytest.mark.asyncio
+    async def test_get_workers(self, reg_controller, mock_zmq_socket):
+        """Test getting workers for an instance."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            for worker_id in [2, 0, 1]:  # Register out of order
+                msg = RegisterMsg(
+                    instance_id="test_instance",
+                    worker_id=worker_id,
+                    ip="127.0.0.1",
+                    port=5000 + worker_id,
+                    peer_init_url=f"tcp://127.0.0.1:{6000 + worker_id}",
+                )
+                await reg_controller.register(msg)
+
+            workers = reg_controller.get_workers("test_instance")
+
+            # Should be sorted
+            assert workers == [0, 1, 2]
+
+    def test_get_workers_nonexistent(self, reg_controller):
+        """Test getting workers for non-existent instance."""
+        workers = reg_controller.get_workers("nonexistent")
+
+        assert workers == []
+
+
+class TestRegistrationControllerInstanceMapping:
+    """Test RegistrationController instance ID mapping."""
+
+    @pytest.mark.asyncio
+    async def test_get_instance_id(self, reg_controller, mock_zmq_socket):
+        """Test getting instance ID from IP."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+            await reg_controller.register(msg)
+
+            query_msg = QueryInstMsg(
+                event_id="event_123",
+                ip="127.0.0.1",
+            )
+
+            result = await reg_controller.get_instance_id(query_msg)
+
+            assert result.event_id == "event_123"
+            assert result.instance_id == "test_instance"
+
+    @pytest.mark.asyncio
+    async def test_get_instance_id_not_found(self, reg_controller):
+        """Test getting instance ID for unregistered IP."""
+        query_msg = QueryInstMsg(
+            event_id="event_123",
+            ip="192.168.1.1",
+        )
+
+        result = await reg_controller.get_instance_id(query_msg)
+
+        assert result.event_id == "event_123"
+        assert result.instance_id is None
+
+
+class TestRegistrationControllerHeartbeat:
+    """Test RegistrationController heartbeat operations."""
+
+    @pytest.mark.asyncio
+    async def test_heartbeat_existing_worker(self, reg_controller, mock_zmq_socket):
+        """Test heartbeat updates timestamp for existing worker."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            # Register worker
+            register_msg = RegisterMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+            await reg_controller.register(register_msg)
+
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is not None
+            original_time = worker_node.last_heartbeat_time
+
+            # Wait a bit
+            time.sleep(0.1)
+
+            # Send heartbeat
+            heartbeat_msg = HeartbeatMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+            await reg_controller.heartbeat(heartbeat_msg)
+
+            # Verify timestamp was updated
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is not None
+            new_time = worker_node.last_heartbeat_time
+            assert new_time > original_time
+
+    @pytest.mark.asyncio
+    async def test_heartbeat_unregistered_worker(self, reg_controller, mock_zmq_socket):
+        """Test heartbeat triggers re-registration for unregistered worker."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            heartbeat_msg = HeartbeatMsg(
+                instance_id="test_instance",
+                worker_id=0,
+                ip="127.0.0.1",
+                port=5000,
+                peer_init_url="tcp://127.0.0.1:6000",
+            )
+
+            await reg_controller.heartbeat(heartbeat_msg)
+
+            # Worker should now be registered
+            worker_node = reg_controller.registry.get_worker("test_instance", 0)
+            assert worker_node is not None
+
+
+class TestRegistrationControllerQueryWorkerInfo:
+    """Test RegistrationController query worker info operations."""
+
+    @pytest.mark.asyncio
+    async def test_query_worker_info(self, reg_controller, mock_zmq_socket):
+        """Test querying worker information."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            # Register workers
+            for worker_id in range(3):
+                msg = RegisterMsg(
+                    instance_id="test_instance",
+                    worker_id=worker_id,
+                    ip="127.0.0.1",
+                    port=5000 + worker_id,
+                    peer_init_url=f"tcp://127.0.0.1:{6000 + worker_id}",
+                )
+                await reg_controller.register(msg)
+
+            # Query all workers
+            query_msg = QueryWorkerInfoMsg(
+                event_id="event_123",
+                instance_id="test_instance",
+                worker_ids=None,
+            )
+
+            result = await reg_controller.query_worker_info(query_msg)
+
+            assert result.event_id == "event_123"
+            assert len(result.worker_infos) == 3
+            assert result.worker_infos[0].worker_id == 0
+            assert result.worker_infos[1].worker_id == 1
+            assert result.worker_infos[2].worker_id == 2
+
+    @pytest.mark.asyncio
+    async def test_query_worker_info_specific_workers(
+        self, reg_controller, mock_zmq_socket
+    ):
+        """Test querying specific workers."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            # Register workers
+            for worker_id in range(3):
+                msg = RegisterMsg(
+                    instance_id="test_instance",
+                    worker_id=worker_id,
+                    ip="127.0.0.1",
+                    port=5000 + worker_id,
+                    peer_init_url=f"tcp://127.0.0.1:{6000 + worker_id}",
+                )
+                await reg_controller.register(msg)
+
+            # Query specific workers
+            query_msg = QueryWorkerInfoMsg(
+                event_id="event_123",
+                instance_id="test_instance",
+                worker_ids=[0, 2],
+            )
+
+            result = await reg_controller.query_worker_info(query_msg)
+
+            assert len(result.worker_infos) == 2
+            assert result.worker_infos[0].worker_id == 0
+            assert result.worker_infos[1].worker_id == 2
+
+    @pytest.mark.asyncio
+    async def test_query_worker_info_nonexistent_instance(self, reg_controller):
+        """Test querying worker info for non-existent instance."""
+        query_msg = QueryWorkerInfoMsg(
+            event_id="event_123",
+            instance_id="nonexistent",
+            worker_ids=None,
+        )
+
+        result = await reg_controller.query_worker_info(query_msg)
+
+        assert result.event_id == "event_123"
+        assert len(result.worker_infos) == 0
+
+    @pytest.mark.asyncio
+    async def test_query_worker_info_empty_list(self, reg_controller, mock_zmq_socket):
+        """Test querying with empty worker_ids list returns all workers."""
+        with patch(
+            "lmcache.v1.cache_controller.controllers.registration_controller.get_zmq_socket"
+        ) as mock_get_socket:
+            mock_get_socket.return_value = mock_zmq_socket
+
+            # Register workers
+            for worker_id in range(2):
+                msg = RegisterMsg(
+                    instance_id="test_instance",
+                    worker_id=worker_id,
+                    ip="127.0.0.1",
+                    port=5000 + worker_id,
+                    peer_init_url=f"tcp://127.0.0.1:{6000 + worker_id}",
+                )
+                await reg_controller.register(msg)
+
+            # Query with empty list
+            query_msg = QueryWorkerInfoMsg(
+                event_id="event_123",
+                instance_id="test_instance",
+                worker_ids=[],
+            )
+
+            result = await reg_controller.query_worker_info(query_msg)
+
+            # Should return all workers
+            assert len(result.worker_infos) == 2
+
+
+class TestRegistrationControllerHealth:
+    """Test RegistrationController health operations."""
+
+    @pytest.mark.asyncio
+    async def test_health_delegates_to_executor(self, reg_controller):
+        """Test health check delegates to cluster executor."""
+        msg = HealthMsg(
+            event_id="event_123",
+            instance_id="test_instance",
+        )
+
+        await reg_controller.health(msg)
+
+        reg_controller.cluster_executor.execute.assert_called_once_with("health", msg)
+
+
+class TestRegistrationControllerMetrics:
+    """Test RegistrationController metrics setup."""
+
+    @patch(
+        "lmcache.v1.cache_controller.controllers.registration_controller.PrometheusLogger"
+    )
+    def test_metrics_setup(self, mock_prometheus_logger):
+        """Test metrics are properly set up."""
+        mock_logger_instance = Mock()
+        mock_prometheus_logger.GetInstanceOrNone.return_value = mock_logger_instance
+
+        _controller = RegistrationController()
+
+        # Verify metrics function was set
+        mock_logger_instance.registered_workers_count.set_function.assert_called_once()
+
+    @patch(
+        "lmcache.v1.cache_controller.controllers.registration_controller.PrometheusLogger"
+    )
+    def test_metrics_setup_no_logger(self, mock_prometheus_logger):
+        """Test metrics setup when no logger is available."""
+        mock_prometheus_logger.GetInstanceOrNone.return_value = None
+
+        # Should not raise an error
+        controller = RegistrationController()
+
+        assert controller is not None
diff --git a/tests/v1/cache_controller/test_registry_tree.py b/tests/v1/cache_controller/test_registry_tree.py
new file mode 100644
index 0000000..fde3b99
--- /dev/null
+++ b/tests/v1/cache_controller/test_registry_tree.py
@@ -0,0 +1,1163 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for RegistryTree with fine-grained locking.
+
+Tests verify that the object-based locking mechanism provides:
+1. Thread-safe operations on instances, workers, and KV stores
+2. Concurrent operations on different instances don't block each other
+3. Data consistency under high concurrency
+"""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+import threading
+import time
+
+# First Party
+from lmcache.v1.cache_controller.message import BatchedKVOperationMsg, KVOpEvent, OpType
+from lmcache.v1.cache_controller.utils import (
+    InstanceNode,
+    RegistryTree,
+    WorkerNode,
+)
+
+
+class TestWorkerNodeLocking:
+    """Test WorkerNode's internal locking for kv_store and seq_tracker."""
+
+    def test_concurrent_admit_kv(self):
+        """Test concurrent KV admission on the same worker."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+        num_threads = 10
+        keys_per_thread = 100
+
+        def admit_keys(thread_id):
+            for i in range(keys_per_thread):
+                key = thread_id * keys_per_thread + i
+                msg = BatchedKVOperationMsg(
+                    instance_id="test_instance",
+                    worker_id=worker.worker_id,
+                    location=location,
+                    operations=[
+                        KVOpEvent(
+                            op_type=OpType.ADMIT,
+                            key=key,
+                            seq_num=thread_id * keys_per_thread + i,
+                        )
+                    ],
+                )
+                worker.handle_batched_kv_operations(msg)
+
+        threads = [
+            threading.Thread(target=admit_keys, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All keys should be admitted
+        assert worker.get_kv_count() == num_threads * keys_per_thread
+
+    def test_concurrent_admit_evict_kv(self):
+        """Test concurrent admit and evict on the same worker."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+        num_threads = 5
+        operations_per_thread = 100
+        errors = []
+
+        def mixed_operations(thread_id):
+            for i in range(operations_per_thread):
+                key = i  # Same key range for all threads
+                try:
+                    if i % 2 == 0:
+                        msg = BatchedKVOperationMsg(
+                            instance_id="test_instance",
+                            worker_id=worker.worker_id,
+                            location=location,
+                            operations=[
+                                KVOpEvent(
+                                    op_type=OpType.ADMIT,
+                                    key=key,
+                                    seq_num=thread_id * operations_per_thread + i,
+                                )
+                            ],
+                        )
+                    else:
+                        msg = BatchedKVOperationMsg(
+                            instance_id="test_instance",
+                            worker_id=worker.worker_id,
+                            location=location,
+                            operations=[
+                                KVOpEvent(
+                                    op_type=OpType.EVICT,
+                                    key=key,
+                                    seq_num=thread_id * operations_per_thread + i,
+                                )
+                            ],
+                        )
+                    worker.handle_batched_kv_operations(msg)
+                except Exception as e:
+                    errors.append("Thread %d error: %s" % (thread_id, e))
+
+        threads = [
+            threading.Thread(target=mixed_operations, args=(i,))
+            for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+    def test_concurrent_seq_num_update(self):
+        """Test concurrent sequence number updates."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+        num_threads = 10
+        updates_per_thread = 100
+
+        def update_seq(thread_id):
+            for i in range(updates_per_thread):
+                worker.update_seq_num(location, thread_id * updates_per_thread + i)
+
+        threads = [
+            threading.Thread(target=update_seq, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # Final seq_num should be set (exact value depends on thread order)
+        final_seq = worker.get_seq_num(location)
+        assert final_seq is not None
+
+
+class TestInstanceNodeLocking:
+    """Test InstanceNode's internal locking for workers dict."""
+
+    def test_concurrent_add_workers(self):
+        """Test concurrent worker additions to same instance."""
+        instance = InstanceNode(instance_id="test_instance")
+        num_threads = 10
+
+        def add_worker(worker_id):
+            worker = WorkerNode(
+                worker_id=worker_id,
+                ip="127.0.0.1",
+                port=8000 + worker_id,
+                peer_init_url=None,
+                socket=None,
+                registration_time=time.time(),
+                last_heartbeat_time=time.time(),
+            )
+            instance.add_worker(worker)
+
+        threads = [
+            threading.Thread(target=add_worker, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All workers should be added
+        assert len(instance.get_worker_ids()) == num_threads
+
+    def test_concurrent_add_remove_workers(self):
+        """Test concurrent worker add/remove on same instance."""
+        instance = InstanceNode(instance_id="test_instance")
+        errors = []
+
+        # Pre-add some workers
+        for i in range(50):
+            worker = WorkerNode(
+                worker_id=i,
+                ip="127.0.0.1",
+                port=8000 + i,
+                peer_init_url=None,
+                socket=None,
+                registration_time=time.time(),
+                last_heartbeat_time=time.time(),
+            )
+            instance.add_worker(worker)
+
+        def add_workers(start_id):
+            for i in range(10):
+                try:
+                    worker = WorkerNode(
+                        worker_id=start_id + i,
+                        ip="127.0.0.1",
+                        port=9000 + start_id + i,
+                        peer_init_url=None,
+                        socket=None,
+                        registration_time=time.time(),
+                        last_heartbeat_time=time.time(),
+                    )
+                    instance.add_worker(worker)
+                except Exception as e:
+                    errors.append("Add error: %s" % e)
+
+        def remove_workers(start_id):
+            for i in range(10):
+                try:
+                    instance.remove_worker(start_id + i)
+                except Exception as e:
+                    errors.append("Remove error: %s" % e)
+
+        threads = []
+        # Add workers 100-199
+        for i in range(10):
+            threads.append(threading.Thread(target=add_workers, args=(100 + i * 10,)))
+        # Remove workers 0-49
+        for i in range(5):
+            threads.append(threading.Thread(target=remove_workers, args=(i * 10,)))
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+
+class TestRegistryTreeFineGrainedLocking:
+    """Test RegistryTree's fine-grained object-based locking."""
+
+    def test_concurrent_operations_different_instances(self):
+        """
+        Test that operations on different instances don't block each other.
+        This is the key benefit of fine-grained locking.
+        """
+        registry = RegistryTree()
+        num_instances = 5
+        workers_per_instance = 20
+        errors = []
+        timing_results = []
+
+        def operate_on_instance(instance_idx):
+            nonlocal errors
+            instance_id = "instance_%d" % instance_idx
+            start_time = time.time()
+
+            for worker_id in range(workers_per_instance):
+                try:
+                    # Register worker
+                    registry.register_worker(
+                        instance_id=instance_id,
+                        worker_id=worker_id,
+                        ip="192.168.%d.%d" % (instance_idx, worker_id),
+                        port=8000 + worker_id,
+                        peer_init_url=None,
+                        socket=None,
+                        registration_time=time.time(),
+                    )
+
+                    # KV operations
+                    for kv_key in range(10):
+                        msg = BatchedKVOperationMsg(
+                            instance_id=instance_id,
+                            worker_id=worker_id,
+                            location="location_%d" % worker_id,
+                            operations=[
+                                KVOpEvent(
+                                    op_type=OpType.ADMIT,
+                                    key=kv_key,
+                                    seq_num=kv_key,
+                                )
+                            ],
+                        )
+                        registry.handle_batched_kv_operations(msg)
+
+                except Exception as e:
+                    errors.append("Instance %d error: %s" % (instance_idx, e))
+
+            elapsed = time.time() - start_time
+            timing_results.append((instance_idx, elapsed))
+
+        threads = [
+            threading.Thread(target=operate_on_instance, args=(i,))
+            for i in range(num_instances)
+        ]
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+        # Verify all data
+        for i in range(num_instances):
+            instance_id = "instance_%d" % i
+            worker_ids = registry.get_worker_ids(instance_id)
+            assert len(worker_ids) == workers_per_instance, (
+                "Instance %d: expected %d workers, got %d"
+                % (
+                    i,
+                    workers_per_instance,
+                    len(worker_ids),
+                )
+            )
+
+    def test_concurrent_register_deregister_same_instance(self):
+        """Test concurrent register/deregister on the same instance."""
+        registry = RegistryTree()
+        instance_id = "test_instance"
+        num_threads = 10
+        operations_per_thread = 50
+        errors = []
+
+        def register_deregister(thread_id):
+            for i in range(operations_per_thread):
+                worker_id = thread_id * 1000 + i
+                try:
+                    # Register
+                    registry.register_worker(
+                        instance_id=instance_id,
+                        worker_id=worker_id,
+                        ip="192.168.1.%d" % thread_id,
+                        port=8000 + i,
+                        peer_init_url=None,
+                        socket=None,
+                        registration_time=time.time(),
+                    )
+
+                    # Verify registration
+                    worker = registry.get_worker(instance_id, worker_id)
+                    if worker is None:
+                        errors.append(
+                            "Thread %d: Worker %d not found after register"
+                            % (thread_id, worker_id)
+                        )
+                        continue
+
+                    # Deregister
+                    result = registry.deregister_worker(instance_id, worker_id)
+                    if result is None:
+                        errors.append(
+                            "Thread %d: Deregister failed for worker %d"
+                            % (thread_id, worker_id)
+                        )
+
+                except Exception as e:
+                    errors.append("Thread %d error: %s" % (thread_id, e))
+
+        threads = [
+            threading.Thread(target=register_deregister, args=(i,))
+            for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+    def test_concurrent_kv_operations_same_worker(self):
+        """Test concurrent KV operations on the same worker."""
+        registry = RegistryTree()
+        instance_id = "test_instance"
+        worker_id = 0
+
+        registry.register_worker(
+            instance_id=instance_id,
+            worker_id=worker_id,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+        )
+
+        location = "test_location"
+        num_threads = 10
+        keys_per_thread = 100
+        errors = []
+
+        def kv_operations(thread_id):
+            nonlocal errors
+            for i in range(keys_per_thread):
+                key = thread_id * keys_per_thread + i
+                try:
+                    # Admit using batched operation message
+                    msg = BatchedKVOperationMsg(
+                        instance_id=instance_id,
+                        worker_id=worker_id,
+                        location=location,
+                        operations=[
+                            KVOpEvent(
+                                op_type=OpType.ADMIT,
+                                key=key,
+                                seq_num=thread_id * keys_per_thread + i,
+                            )
+                        ],
+                    )
+                    result = registry.handle_batched_kv_operations(msg)
+                    if not result:
+                        errors.append(
+                            "Thread %d: handle_batched_kv_operations failed for key %d"
+                            % (thread_id, key)
+                        )
+                except Exception as e:
+                    errors.append("Thread %d error: %s" % (thread_id, e))
+
+        threads = [
+            threading.Thread(target=kv_operations, args=(i,))
+            for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+        # Verify total KV count
+        total = registry.get_total_kv_count()
+        assert total == num_threads * keys_per_thread
+
+    def test_find_kv_concurrent_with_admit(self):
+        """Test find_kv while concurrent admit operations are happening."""
+        registry = RegistryTree()
+        num_instances = 3
+        workers_per_instance = 3
+
+        # Setup: register workers
+        for i in range(num_instances):
+            for w in range(workers_per_instance):
+                registry.register_worker(
+                    instance_id="instance_%d" % i,
+                    worker_id=w,
+                    ip="192.168.%d.%d" % (i, w),
+                    port=8000 + w,
+                    peer_init_url=None,
+                    socket=None,
+                    registration_time=time.time(),
+                )
+
+        errors = []
+        found_keys = []
+
+        def admit_keys(instance_idx, worker_id):
+            nonlocal errors
+            for key in range(100):
+                try:
+                    msg = BatchedKVOperationMsg(
+                        instance_id="instance_%d" % instance_idx,
+                        worker_id=worker_id,
+                        location="location_%d" % worker_id,
+                        operations=[
+                            KVOpEvent(
+                                op_type=OpType.ADMIT,
+                                key=key + instance_idx * 1000,
+                                seq_num=key,
+                            )
+                        ],
+                    )
+                    registry.handle_batched_kv_operations(msg)
+                except Exception as e:
+                    errors.append("Admit error: %s" % e)
+
+        def find_keys():
+            for _ in range(50):
+                for key in range(100):
+                    try:
+                        result = registry.find_kv(key)
+                        if result:
+                            found_keys.append(key)
+                    except Exception as e:
+                        errors.append("Find error: %s" % e)
+                time.sleep(0.001)
+
+        threads = []
+        # Admit threads
+        for i in range(num_instances):
+            for w in range(workers_per_instance):
+                threads.append(threading.Thread(target=admit_keys, args=(i, w)))
+        # Find threads
+        threads.append(threading.Thread(target=find_keys))
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+    def test_heartbeat_update_concurrent(self):
+        """Test concurrent heartbeat updates."""
+        registry = RegistryTree()
+        instance_id = "test_instance"
+        num_workers = 10
+
+        # Register workers
+        for w in range(num_workers):
+            registry.register_worker(
+                instance_id=instance_id,
+                worker_id=w,
+                ip="127.0.0.1",
+                port=8000 + w,
+                peer_init_url=None,
+                socket=None,
+                registration_time=time.time(),
+            )
+
+        errors = []
+        num_threads = 20
+        updates_per_thread = 100
+
+        def update_heartbeats():
+            for _ in range(updates_per_thread):
+                for w in range(num_workers):
+                    try:
+                        result = registry.update_heartbeat(instance_id, w, time.time())
+                        if not result:
+                            errors.append("Heartbeat update failed for worker %d" % w)
+                    except Exception as e:
+                        errors.append("Heartbeat error: %s" % e)
+
+        threads = [
+            threading.Thread(target=update_heartbeats) for _ in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+    def test_get_all_worker_infos_concurrent(self):
+        """Test get_all_worker_infos during concurrent modifications."""
+        registry = RegistryTree()
+        errors = []
+
+        def register_workers():
+            for i in range(100):
+                try:
+                    registry.register_worker(
+                        instance_id="instance_%d" % (i % 5),
+                        worker_id=i,
+                        ip="192.168.1.%d" % i,
+                        port=8000 + i,
+                        peer_init_url=None,
+                        socket=None,
+                        registration_time=time.time(),
+                    )
+                except Exception as e:
+                    errors.append("Register error: %s" % e)
+
+        def get_infos():
+            for _ in range(50):
+                try:
+                    infos = registry.get_all_worker_infos_cached()
+                    # Just verify it returns a list without error
+                    assert isinstance(infos, list)
+                except Exception as e:
+                    errors.append("Get infos error: %s" % e)
+                time.sleep(0.001)
+
+        threads = [
+            threading.Thread(target=register_workers),
+            threading.Thread(target=get_infos),
+            threading.Thread(target=get_infos),
+        ]
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+    def test_instance_cleanup_on_last_worker_deregister(self):
+        """Test that empty instances are cleaned up correctly."""
+        registry = RegistryTree()
+        instance_id = "test_instance"
+        num_workers = 10
+
+        # Register workers
+        for w in range(num_workers):
+            registry.register_worker(
+                instance_id=instance_id,
+                worker_id=w,
+                ip="127.0.0.1",
+                port=8000 + w,
+                peer_init_url=None,
+                socket=None,
+                registration_time=time.time(),
+            )
+
+        # Deregister all workers concurrently
+        errors = []
+
+        def deregister(worker_id):
+            try:
+                registry.deregister_worker(instance_id, worker_id)
+            except Exception as e:
+                errors.append("Deregister error: %s" % e)
+
+        threads = [
+            threading.Thread(target=deregister, args=(w,)) for w in range(num_workers)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+
+    def test_high_contention_stress(self):
+        """Stress test with high contention on a single instance."""
+        registry = RegistryTree()
+        instance_id = "stress_instance"
+        errors = []
+        num_threads = 30
+        operations_per_thread = 100
+
+        def stress_operations(thread_id):
+            nonlocal errors
+            for i in range(operations_per_thread):
+                worker_id = thread_id * operations_per_thread + i
+                try:
+                    # Register
+                    registry.register_worker(
+                        instance_id=instance_id,
+                        worker_id=worker_id,
+                        ip="10.0.0.%d" % (thread_id % 256),
+                        port=8000 + (i % 1000),
+                        peer_init_url=None,
+                        socket=None,
+                        registration_time=time.time(),
+                    )
+
+                    # KV operations
+                    msg = BatchedKVOperationMsg(
+                        instance_id=instance_id,
+                        worker_id=worker_id,
+                        location="loc1",
+                        operations=[
+                            KVOpEvent(
+                                op_type=OpType.ADMIT,
+                                key=i,
+                                seq_num=i,
+                            )
+                        ],
+                    )
+                    registry.handle_batched_kv_operations(msg)
+
+                    # Read operations
+                    registry.get_worker(instance_id, worker_id)
+
+                    # Deregister
+                    registry.deregister_worker(instance_id, worker_id)
+
+                except Exception as e:
+                    errors.append(
+                        "Thread %d iteration %d error: %s" % (thread_id, i, e)
+                    )
+
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [
+                executor.submit(stress_operations, i) for i in range(num_threads)
+            ]
+            for f in futures:
+                f.result()
+
+        assert not errors, "Errors occurred (first 10): %s" % errors[:10]
+
+    def test_data_consistency_after_concurrent_ops(self):
+        """Verify data consistency after heavy concurrent operations."""
+        registry = RegistryTree()
+        num_instances = 5
+        workers_per_instance = 10
+        kv_keys = 50
+
+        # Register all workers
+        for inst in range(num_instances):
+            for w in range(workers_per_instance):
+                registry.register_worker(
+                    instance_id="inst_%d" % inst,
+                    worker_id=w,
+                    ip="10.%d.%d.1" % (inst, w),
+                    port=8000,
+                    peer_init_url=None,
+                    socket=None,
+                    registration_time=time.time(),
+                )
+
+        errors = []
+
+        def concurrent_operations(inst_idx):
+            nonlocal errors
+            instance_id = "inst_%d" % inst_idx
+            for w in range(workers_per_instance):
+                for key in range(kv_keys):
+                    try:
+                        msg = BatchedKVOperationMsg(
+                            instance_id=instance_id,
+                            worker_id=w,
+                            location="loc",
+                            operations=[
+                                KVOpEvent(
+                                    op_type=OpType.ADMIT,
+                                    key=key,
+                                    seq_num=key,
+                                )
+                            ],
+                        )
+                        registry.handle_batched_kv_operations(msg)
+                    except Exception as e:
+                        errors.append("Admit error: %s" % e)
+
+        threads = [
+            threading.Thread(target=concurrent_operations, args=(i,))
+            for i in range(num_instances)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors during concurrent ops: %s" % errors
+
+        # Verify final state
+        total_kv = registry.get_total_kv_count()
+        expected_kv = num_instances * workers_per_instance * kv_keys
+        assert total_kv == expected_kv, "Expected %d KV entries, got %d" % (
+            expected_kv,
+            total_kv,
+        )
+
+        for inst in range(num_instances):
+            worker_ids = registry.get_worker_ids("inst_%d" % inst)
+            assert len(worker_ids) == workers_per_instance, (
+                "Instance %d: expected %d workers, got %d"
+                % (
+                    inst,
+                    workers_per_instance,
+                    len(worker_ids),
+                )
+            )
+
+
+class TestBatchOperations:
+    """Test batch KV operations for performance optimization."""
+
+    def test_batch_admit_kv_basic(self):
+        """Test basic batch admit functionality using handle_batched_kv_operations."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+        keys = list(range(100))
+
+        # Create batch operation message
+        operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=key) for key in keys
+        ]
+        msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=worker.worker_id,
+            location=location,
+            operations=operations,
+        )
+        worker.handle_batched_kv_operations(msg)
+
+        assert worker.get_kv_count() == 100
+        for key in keys:
+            assert worker.has_kv(location, key)
+
+    def test_batch_evict_kv_basic(self):
+        """Test basic batch evict functionality using handle_batched_kv_operations."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+        keys = list(range(100))
+
+        # First admit all keys using batch operation - start with seq_num=0
+        admit_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=i)
+            for i, key in enumerate(keys)
+        ]
+        admit_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=worker.worker_id,
+            location=location,
+            operations=admit_operations,
+        )
+        worker.handle_batched_kv_operations(admit_msg)
+        assert worker.get_kv_count() == 100
+
+        # Evict half of them using batch operation - continue sequence
+        evict_keys = list(range(50))
+        evict_operations = [
+            KVOpEvent(op_type=OpType.EVICT, key=key, seq_num=100 + i)
+            for i, key in enumerate(evict_keys)
+        ]
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=worker.worker_id,
+            location=location,
+            operations=evict_operations,
+        )
+        worker.handle_batched_kv_operations(evict_msg)
+
+        assert worker.get_kv_count() == 50
+
+        # Check remaining keys
+        for key in range(50, 100):
+            assert worker.has_kv(location, key)
+
+    def test_batch_evict_nonexistent_keys(self):
+        """Test batch evict with some non-existent keys
+        using handle_batched_kv_operations."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+
+        # Admit only keys 0-49 using batch operation - start with seq_num=0
+        admit_keys = list(range(50))
+        admit_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=i)
+            for i, key in enumerate(admit_keys)
+        ]
+        admit_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=worker.worker_id,
+            location=location,
+            operations=admit_operations,
+        )
+        worker.handle_batched_kv_operations(admit_msg)
+        assert worker.get_kv_count() == 50
+
+        # Try to evict keys 0-99 (half don't exist)
+        # using batch operation - continue sequence
+        evict_keys = list(range(100))
+        evict_operations = [
+            KVOpEvent(op_type=OpType.EVICT, key=key, seq_num=50 + i)
+            for i, key in enumerate(evict_keys)
+        ]
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="test_instance",
+            worker_id=worker.worker_id,
+            location=location,
+            operations=evict_operations,
+        )
+        worker.handle_batched_kv_operations(evict_msg)
+
+        # All admitted keys should be evicted
+        assert worker.get_kv_count() == 0
+
+    def test_registry_batch_operations(self):
+        """Test batch operations through RegistryTree
+        using handle_batched_kv_operations."""
+        registry = RegistryTree()
+
+        registry.register_worker(
+            instance_id="inst_0",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+        )
+
+        location = "test_location"
+        keys = list(range(1000))
+
+        # Batch admit using handle_batched_kv_operations - start with seq_num=0
+        admit_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=i)
+            for i, key in enumerate(keys)
+        ]
+        admit_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=admit_operations,
+        )
+        result = registry.handle_batched_kv_operations(admit_msg)
+        assert result is not False  # Should succeed
+        assert registry.get_total_kv_count() == 1000
+
+        # Batch evict using handle_batched_kv_operations - continue sequence
+        evict_keys = keys[:500]
+        evict_operations = [
+            KVOpEvent(op_type=OpType.EVICT, key=key, seq_num=1000 + i)
+            for i, key in enumerate(evict_keys)
+        ]
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=evict_operations,
+        )
+        registry.handle_batched_kv_operations(evict_msg)
+        assert registry.get_total_kv_count() == 500
+
+    def test_batch_operations_nonexistent_worker(self):
+        """Test batch operations on non-existent worker
+        using handle_batched_kv_operations."""
+        registry = RegistryTree()
+
+        # Batch admit to non-existent worker using handle_batched_kv_operations
+        admit_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=key) for key in [1, 2, 3]
+        ]
+        admit_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location="loc",
+            operations=admit_operations,
+        )
+        result = registry.handle_batched_kv_operations(admit_msg)
+        # Should return None or indicate failure when worker doesn't exist
+        assert result is None or result is False
+
+        # Batch evict from non-existent worker using handle_batched_kv_operations
+        evict_operations = [
+            KVOpEvent(op_type=OpType.EVICT, key=key, seq_num=key) for key in [1, 2, 3]
+        ]
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location="loc",
+            operations=evict_operations,
+        )
+        result = registry.handle_batched_kv_operations(evict_msg)
+        # Should return None or indicate failure when worker doesn't exist
+        assert result is None or result is False
+
+    def test_concurrent_batch_operations(self):
+        """Test concurrent batch operations on same worker
+        using handle_batched_kv_operations."""
+        worker = WorkerNode(
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+            last_heartbeat_time=time.time(),
+        )
+
+        location = "test_location"
+        num_threads = 10
+        keys_per_batch = 100
+        errors = []
+
+        def batch_admit(thread_id):
+            keys = [thread_id * keys_per_batch + i for i in range(keys_per_batch)]
+            try:
+                operations = [
+                    KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=key)
+                    for key in keys
+                ]
+                msg = BatchedKVOperationMsg(
+                    instance_id="test_instance",
+                    worker_id=worker.worker_id,
+                    location=location,
+                    operations=operations,
+                )
+                worker.handle_batched_kv_operations(msg)
+            except Exception as e:
+                errors.append("Thread %d error: %s" % (thread_id, e))
+
+        threads = [
+            threading.Thread(target=batch_admit, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors, "Errors occurred: %s" % errors
+        assert worker.get_kv_count() == num_threads * keys_per_batch
+
+    def test_registry_batch_with_seq_check(self):
+        """Test batch operations with sequence check through RegistryTree
+        using handle_batched_kv_operations."""
+        registry = RegistryTree()
+
+        registry.register_worker(
+            instance_id="inst_0",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+        )
+
+        location = "test_location"
+        discontinuity_detected = False
+
+        def on_discontinuity():
+            nonlocal discontinuity_detected
+            discontinuity_detected = True
+
+        # First batch admit with seq check (continuous)
+        batch1_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=seq_num)
+            for key, seq_num in [(1, 0), (2, 1), (3, 2)]
+        ]
+        batch1_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=batch1_operations,
+        )
+        result = registry.handle_batched_kv_operations(batch1_msg)
+        # Check discontinuity count instead
+        discontinuity_count = registry.get_seq_discontinuity_count()
+        assert result is not False and discontinuity_count == 0, (
+            "First batch should succeed and be continuous"
+        )
+        assert registry.get_total_kv_count() == 3
+
+        # Second batch admit (continuous)
+        batch2_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=seq_num)
+            for key, seq_num in [(4, 3), (5, 4), (6, 5)]
+        ]
+        batch2_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=batch2_operations,
+        )
+        result = registry.handle_batched_kv_operations(batch2_msg)
+        discontinuity_count = registry.get_seq_discontinuity_count()
+        assert result is not False and discontinuity_count == 0, (
+            "Second batch should succeed and be continuous"
+        )
+        assert registry.get_total_kv_count() == 6
+
+        # Third batch with gap
+        batch3_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=seq_num)
+            for key, seq_num in [(10, 10), (11, 11)]
+        ]
+        batch3_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=batch3_operations,
+        )
+        result = registry.handle_batched_kv_operations(batch3_msg)
+        discontinuity_count = registry.get_seq_discontinuity_count()
+        assert result is not False, "Batch with gap should still succeed"
+        assert discontinuity_count > 0, "Sequence discontinuity should be detected"
+        assert registry.get_total_kv_count() == 8
+
+    def test_registry_batch_evict_with_seq_check(self):
+        """Test batch evict with sequence check through RegistryTree
+        using handle_batched_kv_operations."""
+        registry = RegistryTree()
+
+        registry.register_worker(
+            instance_id="inst_0",
+            worker_id=0,
+            ip="127.0.0.1",
+            port=8000,
+            peer_init_url=None,
+            socket=None,
+            registration_time=time.time(),
+        )
+
+        location = "test_location"
+
+        # First admit some keys (continuous sequence starting from 0)
+        admit_operations = [
+            KVOpEvent(op_type=OpType.ADMIT, key=key, seq_num=i)
+            for i, key in enumerate(range(100))
+        ]
+        admit_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=admit_operations,
+        )
+        result = registry.handle_batched_kv_operations(admit_msg)
+        discontinuity_count = registry.get_seq_discontinuity_count()
+        assert result is not False and discontinuity_count == 0, (
+            "Admit should succeed and be continuous"
+        )
+        assert registry.get_total_kv_count() == 100
+
+        # Batch evict with seq check (continuous) - continue sequence from 100
+        evict_operations = [
+            KVOpEvent(op_type=OpType.EVICT, key=key, seq_num=100 + i)
+            for i, key in enumerate(range(50))
+        ]
+        evict_msg = BatchedKVOperationMsg(
+            instance_id="inst_0",
+            worker_id=0,
+            location=location,
+            operations=evict_operations,
+        )
+        result = registry.handle_batched_kv_operations(evict_msg)
+        discontinuity_count_after_evict = registry.get_seq_discontinuity_count()
+        assert discontinuity_count_after_evict == 0, (
+            "Evict should succeed and be continuous"
+        )
+        assert result is not False, "Evict should succeed"
+        # Note: Evict operations don't check sequence continuity,
+        # so count shouldn't increase
+        assert registry.get_total_kv_count() == 50
diff --git a/tests/v1/compute/attention/test_triton_kernels.py b/tests/v1/compute/attention/test_triton_kernels.py
new file mode 100644
index 0000000..84bc058
--- /dev/null
+++ b/tests/v1/compute/attention/test_triton_kernels.py
@@ -0,0 +1,297 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for Triton block-sparse attention kernels.
+
+Tests the three kernels in isolation without requiring a model or vLLM.
+Validates correctness against a naive PyTorch reference implementation.
+"""
+
+# Standard
+import math
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.compute.attention.metadata import _block_mask_to_csr
+from lmcache.v1.compute.attention.triton_kernels import (
+    block_sparse_attention,
+    causal_prefill_attention,
+    merge_attention_outputs,
+)
+
+# Skip entire module when no GPU available
+pytestmark = pytest.mark.skipif(not torch.cuda.is_available(), reason="GPU required")
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _ref_attention(q, k, v, sm_scale, causal=False):
+    """Naive PyTorch attention (no sparsity)."""
+    # q: [M, H, D], k: [N, H, D], v: [N, H, D]
+    M, H, D = q.shape
+    N = k.shape[0]
+    # [H, M, N]
+    scores = torch.einsum("mhd,nhd->hmn", q.float(), k.float()) * sm_scale
+    if causal:
+        # kv_pos <= q_pos
+        q_pos = torch.arange(M, device=q.device).unsqueeze(1)
+        kv_pos = torch.arange(N, device=q.device).unsqueeze(0)
+        mask = kv_pos <= q_pos
+        scores.masked_fill_(~mask.unsqueeze(0), float("-inf"))
+    attn = torch.softmax(scores, dim=-1)
+    out = torch.einsum("hmn,nhd->mhd", attn, v.float())
+    return out.to(q.dtype)
+
+
+def _ref_sparse_attention(q, k, v, block_indices, block_indptr, sm_scale, block_size):
+    """Naive PyTorch sparse attention for reference."""
+    M, H, D = q.shape
+    N = k.shape[0]
+    KV_H = k.shape[1]
+    gqa_ratio = H // KV_H
+
+    out = torch.zeros_like(q, dtype=torch.float32)
+    lse = torch.full((M, H), float("-inf"), dtype=torch.float32, device=q.device)
+
+    num_q_blocks = block_indptr.shape[0] - 1
+    for qb in range(num_q_blocks):
+        q_start = qb * block_size
+        q_end = min(q_start + block_size, M)
+        kv_start_idx = block_indptr[qb].item()
+        kv_end_idx = block_indptr[qb + 1].item()
+        if kv_end_idx <= kv_start_idx:
+            continue
+        for h in range(H):
+            kv_h = h // gqa_ratio
+            q_block = q[q_start:q_end, h, :].float()  # [bm, D]
+            all_scores = []
+            all_v = []
+            for idx in range(kv_start_idx, kv_end_idx):
+                kb = block_indices[idx].item()
+                kv_s = kb * block_size
+                kv_e = min(kv_s + block_size, N)
+                k_block = k[kv_s:kv_e, kv_h, :].float()  # [bn, D]
+                v_block = v[kv_s:kv_e, kv_h, :].float()
+                s = (q_block @ k_block.T) * sm_scale  # [bm, bn]
+                all_scores.append(s)
+                all_v.append(v_block)
+            # concat and softmax
+            scores = torch.cat(all_scores, dim=1)  # [bm, total_kv]
+            vals = torch.cat(all_v, dim=0)  # [total_kv, D]
+            attn = torch.softmax(scores, dim=-1)
+            o = attn @ vals  # [bm, D]
+            out[q_start:q_end, h, :] = o
+            lse[q_start:q_end, h] = scores.max(dim=1).values + torch.log(
+                torch.exp(scores - scores.max(dim=1, keepdim=True).values).sum(dim=1)
+            )
+    return out.to(q.dtype), lse
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestCausalPrefillAttention:
+    """Tests for _causal_prefill_attention_kernel."""
+
+    @pytest.mark.parametrize("dtype", [torch.float16, torch.bfloat16])
+    @pytest.mark.parametrize("seq_len", [64, 128, 200])
+    def test_matches_reference(self, dtype, seq_len):
+        H, D = 8, 64
+        q = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+        k = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+        v = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+        sm_scale = 1.0 / math.sqrt(D)
+
+        out = causal_prefill_attention(q, k, v, sm_scale, block_size=64)
+        ref = _ref_attention(q, k, v, sm_scale, causal=True)
+
+        torch.testing.assert_close(out, ref, atol=1e-2, rtol=1e-2)
+
+    @pytest.mark.parametrize("dtype", [torch.float16, torch.bfloat16])
+    def test_gqa(self, dtype):
+        """Test grouped-query attention (H > KV_H)."""
+        seq_len, H, KV_H, D = 64, 8, 2, 64
+        q = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+        k = torch.randn(seq_len, KV_H, D, device="cuda", dtype=dtype)
+        v = torch.randn(seq_len, KV_H, D, device="cuda", dtype=dtype)
+        sm_scale = 1.0 / math.sqrt(D)
+
+        out = causal_prefill_attention(q, k, v, sm_scale, block_size=64)
+        assert out.shape == (seq_len, H, D)
+        assert not torch.isnan(out).any()
+
+    def test_output_dtype_matches_input(self):
+        seq_len, H, D = 64, 4, 64
+        for dtype in [torch.float16, torch.bfloat16]:
+            q = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+            k = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+            v = torch.randn(seq_len, H, D, device="cuda", dtype=dtype)
+            out = causal_prefill_attention(q, k, v, 1.0 / math.sqrt(D))
+            assert out.dtype == dtype
+
+
+class TestBlockSparseAttention:
+    """Tests for block_sparse_attention kernel."""
+
+    def _make_full_mask_csr(self, num_q_blocks, num_kv_blocks, device):
+        """CSR for a fully dense mask (all blocks attended)."""
+        mask = torch.ones(num_q_blocks, num_kv_blocks, dtype=torch.bool, device=device)
+        return _block_mask_to_csr(mask, device)
+
+    @pytest.mark.parametrize("dtype", [torch.float16, torch.bfloat16])
+    def test_full_mask_matches_dense(self, dtype):
+        """With all blocks attended, should match dense attention."""
+        M, N, H, D = 64, 128, 4, 64
+        BS = 32
+        q = torch.randn(M, H, D, device="cuda", dtype=dtype)
+        k = torch.randn(N, H, D, device="cuda", dtype=dtype)
+        v = torch.randn(N, H, D, device="cuda", dtype=dtype)
+        sm_scale = 1.0 / math.sqrt(D)
+
+        num_q_blocks = (M + BS - 1) // BS
+        num_kv_blocks = (N + BS - 1) // BS
+        indices, indptr = self._make_full_mask_csr(
+            num_q_blocks, num_kv_blocks, q.device
+        )
+
+        out, lse = block_sparse_attention(
+            q, k, v, indices, indptr, sm_scale, block_size=BS
+        )
+        ref = _ref_attention(q, k, v, sm_scale, causal=False)
+
+        torch.testing.assert_close(out, ref, atol=1e-2, rtol=1e-2)
+        assert lse.shape == (M, H)
+        assert not torch.isnan(lse).any()
+
+    def test_empty_mask_returns_zeros(self):
+        """All-empty CSR → output zeros, LSE -inf."""
+        M, N, H, D = 64, 128, 4, 64
+        BS = 32
+        q = torch.randn(M, H, D, device="cuda", dtype=torch.float16)
+        k = torch.randn(N, H, D, device="cuda", dtype=torch.float16)
+        v = torch.randn(N, H, D, device="cuda", dtype=torch.float16)
+
+        num_q_blocks = (M + BS - 1) // BS
+        indptr = torch.zeros(num_q_blocks + 1, dtype=torch.int32, device="cuda")
+        indices = torch.zeros(0, dtype=torch.int32, device="cuda")
+
+        out, lse = block_sparse_attention(
+            q, k, v, indices, indptr, 1.0 / math.sqrt(D), block_size=BS
+        )
+        assert torch.all(out == 0)
+        assert torch.all(lse == float("-inf"))
+
+    @pytest.mark.parametrize("dtype", [torch.float16, torch.bfloat16])
+    def test_gqa_sparse(self, dtype):
+        """GQA with sparse mask."""
+        M, N, H, KV_H, D = 64, 128, 8, 2, 64
+        BS = 32
+        q = torch.randn(M, H, D, device="cuda", dtype=dtype)
+        k = torch.randn(N, KV_H, D, device="cuda", dtype=dtype)
+        v = torch.randn(N, KV_H, D, device="cuda", dtype=dtype)
+
+        num_q_blocks = (M + BS - 1) // BS
+        num_kv_blocks = (N + BS - 1) // BS
+        indices, indptr = self._make_full_mask_csr(
+            num_q_blocks, num_kv_blocks, q.device
+        )
+
+        out, lse = block_sparse_attention(
+            q, k, v, indices, indptr, 1.0 / math.sqrt(D), block_size=BS
+        )
+        assert out.shape == (M, H, D)
+        assert not torch.isnan(out).any()
+
+    def test_partial_trailing_block(self):
+        """Non-aligned seq_len (trailing partial block)."""
+        M, N, H, D = 100, 128, 4, 64  # 100 not divisible by 32
+        BS = 32
+        q = torch.randn(M, H, D, device="cuda", dtype=torch.float16)
+        k = torch.randn(N, H, D, device="cuda", dtype=torch.float16)
+        v = torch.randn(N, H, D, device="cuda", dtype=torch.float16)
+
+        num_q_blocks = (M + BS - 1) // BS  # 4 blocks, last has 4 rows
+        num_kv_blocks = (N + BS - 1) // BS
+        indices, indptr = self._make_full_mask_csr(
+            num_q_blocks, num_kv_blocks, q.device
+        )
+
+        out, lse = block_sparse_attention(
+            q, k, v, indices, indptr, 1.0 / math.sqrt(D), block_size=BS
+        )
+        assert out.shape == (M, H, D)
+        assert not torch.isnan(out).any()
+
+
+class TestMergeAttentionOutputs:
+    """Tests for _merge_attention_kernel."""
+
+    def test_one_path_inf(self):
+        """When one LSE is -inf, output should be entirely from the other."""
+        M, H, D = 64, 4, 64
+        o1 = torch.randn(M, H, D, device="cuda", dtype=torch.float16)
+        o2 = torch.randn(M, H, D, device="cuda", dtype=torch.float16)
+        lse1 = torch.full((M, H), float("-inf"), dtype=torch.float32, device="cuda")
+        lse2 = torch.ones(M, H, dtype=torch.float32, device="cuda")
+
+        merged = merge_attention_outputs(o1, lse1, o2, lse2)
+        torch.testing.assert_close(merged, o2, atol=1e-3, rtol=1e-3)
+
+    def test_both_inf_no_nan(self):
+        """When both LSEs are -inf, output should be zero (not NaN)."""
+        M, H, D = 64, 4, 64
+        o1 = torch.randn(M, H, D, device="cuda", dtype=torch.float16)
+        o2 = torch.randn(M, H, D, device="cuda", dtype=torch.float16)
+        lse1 = torch.full((M, H), float("-inf"), dtype=torch.float32, device="cuda")
+        lse2 = torch.full((M, H), float("-inf"), dtype=torch.float32, device="cuda")
+
+        merged = merge_attention_outputs(o1, lse1, o2, lse2)
+        assert not torch.isnan(merged).any()
+
+    def test_equal_lse_averages(self):
+        """When LSE values are equal, output should be average of both."""
+        M, H, D = 32, 2, 64
+        o1 = torch.ones(M, H, D, device="cuda", dtype=torch.float16)
+        o2 = torch.ones(M, H, D, device="cuda", dtype=torch.float16) * 3
+        lse = torch.ones(M, H, dtype=torch.float32, device="cuda")
+
+        merged = merge_attention_outputs(o1, lse, o2, lse)
+        expected = torch.ones_like(o1) * 2  # (1 + 3) / 2
+        torch.testing.assert_close(merged, expected, atol=1e-2, rtol=1e-2)
+
+    @pytest.mark.parametrize("dtype", [torch.float16, torch.bfloat16])
+    def test_output_dtype(self, dtype):
+        M, H, D = 32, 4, 64
+        o1 = torch.randn(M, H, D, device="cuda", dtype=dtype)
+        o2 = torch.randn(M, H, D, device="cuda", dtype=dtype)
+        lse1 = torch.randn(M, H, dtype=torch.float32, device="cuda")
+        lse2 = torch.randn(M, H, dtype=torch.float32, device="cuda")
+        merged = merge_attention_outputs(o1, lse1, o2, lse2)
+        assert merged.dtype == dtype
+
+
+class TestBlockMaskToCsr:
+    """Tests for _block_mask_to_csr helper."""
+
+    def test_full_mask(self):
+        mask = torch.ones(3, 4, dtype=torch.bool, device="cuda")
+        indices, indptr = _block_mask_to_csr(mask, mask.device)
+        assert indptr.tolist() == [0, 4, 8, 12]
+        assert indices.tolist() == [0, 1, 2, 3] * 3
+
+    def test_empty_mask(self):
+        mask = torch.zeros(3, 4, dtype=torch.bool, device="cuda")
+        indices, indptr = _block_mask_to_csr(mask, mask.device)
+        assert indptr.tolist() == [0, 0, 0, 0]
+        assert len(indices) == 0
+
+    def test_diagonal_mask(self):
+        mask = torch.eye(3, dtype=torch.bool, device="cuda")
+        indices, indptr = _block_mask_to_csr(mask, mask.device)
+        assert indptr.tolist() == [0, 1, 2, 3]
+        assert indices.tolist() == [0, 1, 2]
diff --git a/tests/v1/compute/attention/test_triton_sparse_e2e.py b/tests/v1/compute/attention/test_triton_sparse_e2e.py
new file mode 100644
index 0000000..58af2f0
--- /dev/null
+++ b/tests/v1/compute/attention/test_triton_sparse_e2e.py
@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: Apache-2.0
+"""E2E test for LMCache CacheBlend on ROCm with Triton sparse attention.
+
+Based on examples/blend_kv_v1/blend.py but adapted for ROCm:
+- Uses FlashAttention backend (not FlashInfer)
+- enable_sparse routes to LMCTritonSparseBackend automatically
+"""
+
+# Standard
+from dataclasses import asdict
+import contextlib
+import os
+import time
+
+# Third Party
+import pytest
+
+# Skip entire module when vLLM is not installed (e.g. in UT environments)
+vllm = pytest.importorskip("vllm", reason="vLLM required for E2E test")
+
+# Third Party
+from transformers import AutoTokenizer  # noqa: E402
+from vllm import LLM, SamplingParams  # noqa: E402
+from vllm.config import KVTransferConfig  # noqa: E402
+from vllm.engine.arg_utils import EngineArgs  # noqa: E402
+
+# First Party
+from lmcache.integration.vllm.utils import ENGINE_NAME  # noqa: E402
+from lmcache.v1.cache_engine import LMCacheEngineBuilder  # noqa: E402
+
+
+def setup_env():
+    """Set up LMCache environment variables for CacheBlend."""
+    os.environ["LMCACHE_CHUNK_SIZE"] = "256"
+    os.environ["LMCACHE_ENABLE_BLENDING"] = "True"
+    os.environ["LMCACHE_BLEND_SPECIAL_STR"] = " # # "
+    os.environ["LMCACHE_USE_LAYERWISE"] = "True"
+    os.environ["LMCACHE_BLEND_CHECK_LAYERS"] = "1"
+    os.environ["LMCACHE_BLEND_RECOMPUTE_RATIOS"] = "0.15"
+    os.environ["LMCACHE_LOCAL_CPU"] = "True"
+    os.environ["LMCACHE_MAX_LOCAL_CPU_SIZE"] = "5"
+
+    # Enable sparse attention (routes to Triton backend on ROCm)
+    os.environ["LMCACHE_EXTRA_CONFIG"] = '{"enable_sparse": true}'
+
+    # On ROCm, do NOT set VLLM_ATTENTION_BACKEND=FLASHINFER
+    # The Triton backend works with any vLLM attention impl
+
+
+@contextlib.contextmanager
+def build_llm(model: str):
+    ktc = KVTransferConfig(
+        kv_connector="LMCacheConnectorV1",
+        kv_role="kv_both",
+    )
+
+    llm_args = EngineArgs(
+        model=model,
+        kv_transfer_config=ktc,
+        max_model_len=8192,
+        gpu_memory_utilization=0.8,
+        enable_prefix_caching=False,
+        enforce_eager=True,
+        tensor_parallel_size=1,
+    )
+
+    llm = LLM(**asdict(llm_args))
+    try:
+        yield llm
+    finally:
+        LMCacheEngineBuilder.destroy(ENGINE_NAME)
+
+
+def timed_generate(llm, prompt, sampling_params, label):
+    start = time.time()
+    outputs = llm.generate(
+        prompts={"prompt_token_ids": prompt},
+        sampling_params=sampling_params,
+    )
+    elapsed = time.time() - start
+    text = outputs[0].outputs[0].text if outputs else ""
+    print(f"[{label}] {elapsed:.2f}s | Generated: {text!r}")
+    return elapsed
+
+
+def main():
+    # Standard
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", default="Qwen/Qwen2.5-7B-Instruct")
+    args = parser.parse_args()
+
+    model = args.model
+    print("=== LMCache CacheBlend ROCm E2E Test ===")
+    print(f"Model: {model}")
+    print("Backend: Triton sparse attention (auto-detected on ROCm)")
+
+    setup_env()
+    tokenizer = AutoTokenizer.from_pretrained(model)
+
+    with build_llm(model) as llm:
+        # Build prompts with shared chunks (non-prefix overlap)
+        blend_sep = tokenizer.encode(os.environ["LMCACHE_BLEND_SPECIAL_STR"])[
+            1:
+        ]  # skip BOS
+
+        chunk_a = tokenizer.encode("The quick brown fox jumps. " * 200)[1:]
+        chunk_b = tokenizer.encode("Machine learning is exciting. " * 200)[1:]
+        chunk_c = tokenizer.encode("AMD GPUs are powerful for AI. " * 200)[1:]
+
+        sys_tokens = tokenizer.encode("You are a helpful assistant. ")
+
+        # Request 1: sys + A + B + C + question
+        prompt1 = (
+            sys_tokens
+            + blend_sep
+            + chunk_a
+            + blend_sep
+            + chunk_b
+            + blend_sep
+            + chunk_c
+            + blend_sep
+            + tokenizer.encode("Summarize the above.")[1:]
+        )
+
+        # Request 2: sys + B + A + C + question (reordered — non-prefix!)
+        prompt2 = (
+            sys_tokens
+            + blend_sep
+            + chunk_b
+            + blend_sep
+            + chunk_a
+            + blend_sep
+            + chunk_c
+            + blend_sep
+            + tokenizer.encode("What is the main topic?")[1:]
+        )
+
+        # Request 3: sys + B + A + C + different question
+        prompt3 = (
+            sys_tokens
+            + blend_sep
+            + chunk_b
+            + blend_sep
+            + chunk_a
+            + blend_sep
+            + chunk_c
+            + blend_sep
+            + tokenizer.encode("Tell me more about GPUs.")[1:]
+        )
+
+        sp = SamplingParams(temperature=0, max_tokens=32)
+
+        print(
+            f"\nPrompt lengths: p1={len(prompt1)}, p2={len(prompt2)}, p3={len(prompt3)}"
+        )
+
+        # Warmup
+        warmup = tokenizer.encode("Hello world " * 100)[1:]
+        timed_generate(llm, warmup, sp, "warmup")
+
+        # Request 1: cold cache
+        t1 = timed_generate(llm, prompt1, sp, "req1-cold")
+
+        time.sleep(0.5)
+
+        # Request 2: non-prefix overlap → CacheBlend should reuse chunks
+        t2 = timed_generate(llm, prompt2, sp, "req2-blend")
+
+        time.sleep(0.5)
+
+        # Request 3: same prefix as req2 → should be faster
+        t3 = timed_generate(llm, prompt3, sp, "req3-blend")
+
+        print("\n=== Results ===")
+        print(f"Cold (req1):  {t1:.2f}s")
+        print(f"Blend (req2): {t2:.2f}s")
+        print(f"Blend (req3): {t3:.2f}s")
+
+        if t2 < t1 * 0.9:
+            print("✅ CacheBlend speedup observed!")
+        else:
+            print("⚠️  No significant speedup (may need longer prompts)")
+
+        print("\n✅ E2E test completed without errors!")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/v1/data/gds.yaml b/tests/v1/data/gds.yaml
new file mode 100644
index 0000000..e272223
--- /dev/null
+++ b/tests/v1/data/gds.yaml
@@ -0,0 +1,6 @@
+chunk_size: 256
+gds_path: "/tmp/gds/test-cache"
+local_cpu: False
+save_decode_cache: True
+gds_buffer_size: 128
+gds_backend: "cufile"
diff --git a/tests/v1/data/hipfile.yaml b/tests/v1/data/hipfile.yaml
new file mode 100644
index 0000000..b192f40
--- /dev/null
+++ b/tests/v1/data/hipfile.yaml
@@ -0,0 +1,7 @@
+# Test configuration for HipFile memory allocator
+chunk_size: 256
+gds_path: "/tmp/hipfile/test-cache"
+local_cpu: False
+save_decode_cache: True
+gds_buffer_size: 128
+gds_backend: "hipfile"
diff --git a/tests/v1/data/hipfile_gds.yaml b/tests/v1/data/hipfile_gds.yaml
new file mode 100644
index 0000000..43df497
--- /dev/null
+++ b/tests/v1/data/hipfile_gds.yaml
@@ -0,0 +1,9 @@
+# Configuration for GDS backend with hipFile (AMD ROCm)
+chunk_size: 256
+gds_path: "/tmp/hipfile-gds/test-cache"
+local_cpu: False
+save_decode_cache: True
+gds_buffer_size: 128
+gds_backend: "hipfile"
+extra_config:
+  use_direct_io: true
diff --git a/tests/v1/data/nixl.yaml b/tests/v1/data/nixl.yaml
new file mode 100644
index 0000000..2b581c0
--- /dev/null
+++ b/tests/v1/data/nixl.yaml
@@ -0,0 +1,11 @@
+local_cpu: false
+chunk_size: 256
+
+# CPU mode: NIXL shares LocalCPUBackend's pinned pool (sized by
+# max_local_cpu_size, default 5 GiB); nixl_buffer_size is GPU-mode only.
+nixl_buffer_device: cpu
+extra_config:
+  enable_nixl_storage: true
+  nixl_backend: POSIX
+  nixl_pool_size: 2
+  nixl_path: /tmp/nixl/cache
diff --git a/tests/v1/data/nixl_multipath.yaml b/tests/v1/data/nixl_multipath.yaml
new file mode 100644
index 0000000..01ec7a8
--- /dev/null
+++ b/tests/v1/data/nixl_multipath.yaml
@@ -0,0 +1,14 @@
+local_cpu: false
+chunk_size: 256
+
+nixl_buffer_size: 1073741824
+nixl_buffer_device: cpu
+extra_config:
+  enable_nixl_storage: true
+  nixl_backend: POSIX
+  nixl_pool_size: 2
+  nixl_path: 
+    - /tmp/nixl/cache0
+    - /tmp/nixl/cache1
+    - /tmp/nixl/cache2
+  nixl_path_sharding: by_gpu
diff --git a/tests/v1/data/test_config.yaml b/tests/v1/data/test_config.yaml
new file mode 100644
index 0000000..984df30
--- /dev/null
+++ b/tests/v1/data/test_config.yaml
@@ -0,0 +1,15 @@
+chunk_size: 256
+local_cpu: False
+extra_config:
+  key1: value1
+  key2: value2
+
+enable_pd: True
+transfer_channel: "nixl"
+pd_role: "receiver"
+pd_peer_host: "localhost"
+pd_peer_init_port: 7300
+pd_peer_alloc_port: 7400
+pd_buffer_size: 2147483648
+pd_buffer_device: "cuda"
+nixl_backends: [UCX, GDS]
\ No newline at end of file
diff --git a/tests/v1/distributed/__init__.py b/tests/v1/distributed/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/distributed/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/distributed/conftest.py b/tests/v1/distributed/conftest.py
new file mode 100644
index 0000000..b325073
--- /dev/null
+++ b/tests/v1/distributed/conftest.py
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Shared fixtures for distributed module tests.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from importlib.util import find_spec
+from typing import Any, cast
+import sys
+import types
+
+if find_spec("lmcache.native_storage_ops") is None:
+
+    class Bitmap:
+        """Small Python Bitmap fallback for source-only distributed tests."""
+
+        def __init__(self, size: int, first_n: int = 0) -> None:
+            self._size = int(size)
+            self._bits = {i for i in range(min(int(first_n), self._size))}
+
+        def set(self, index: int) -> None:
+            """Set one bit by index."""
+            index = int(index)
+            if index < 0 or index >= self._size:
+                raise IndexError(index)
+            self._bits.add(index)
+
+        def test(self, index: int) -> bool:
+            """Return whether one bit is set."""
+            return int(index) in self._bits
+
+        def get_indices_list(self) -> list[int]:
+            """Return set bit indices in ascending order."""
+            return sorted(self._bits)
+
+        def popcount(self) -> int:
+            """Return the number of set bits."""
+            return len(self._bits)
+
+        def count_leading_ones(self) -> int:
+            """Return the length of the leading contiguous set-bit prefix."""
+            count = 0
+            while count in self._bits:
+                count += 1
+            return count
+
+        def gather(self, values):
+            """Return values selected by set bit indices."""
+            return [values[i] for i in self.get_indices_list()]
+
+        def __and__(self, other: "Bitmap") -> "Bitmap":
+            size = min(self._size, other._size)
+            result = Bitmap(size)
+            result._bits = {i for i in self._bits & other._bits if i < size}
+            return result
+
+        def __iand__(self, other: "Bitmap") -> "Bitmap":
+            self._bits &= other._bits
+            self._bits = {i for i in self._bits if i < self._size}
+            return self
+
+        def __or__(self, other: "Bitmap") -> "Bitmap":
+            size = max(self._size, other._size)
+            result = Bitmap(size)
+            result._bits = set(self._bits | other._bits)
+            return result
+
+        def __ior__(self, other: "Bitmap") -> "Bitmap":
+            self._size = max(self._size, other._size)
+            self._bits |= other._bits
+            return self
+
+        def __invert__(self) -> "Bitmap":
+            result = Bitmap(self._size)
+            result._bits = set(range(self._size)) - self._bits
+            return result
+
+        def __str__(self) -> str:
+            return "".join("1" if i in self._bits else "0" for i in range(self._size))
+
+    class TTLLock:
+        """Minimal TTLLock fallback for tests that only import the symbol."""
+
+    fallback_module = types.ModuleType("lmcache.native_storage_ops")
+    fallback_module_any = cast(Any, fallback_module)
+    fallback_module_any.Bitmap = Bitmap
+    fallback_module_any.TTLLock = TTLLock
+    sys.modules["lmcache.native_storage_ops"] = fallback_module
diff --git a/tests/v1/distributed/l2_adapters/test_p2p_l2_adapter.py b/tests/v1/distributed/l2_adapters/test_p2p_l2_adapter.py
new file mode 100644
index 0000000..d0a1e86
--- /dev/null
+++ b/tests/v1/distributed/l2_adapters/test_p2p_l2_adapter.py
@@ -0,0 +1,422 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the P2P L2 adapter (mocked MQ client + transfer channel)."""
+
+# Standard
+from contextlib import contextmanager
+from unittest.mock import MagicMock, patch
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.l2_adapters import p2p_l2_adapter as p2p_mod
+from lmcache.v1.distributed.l2_adapters.p2p_l2_adapter import (
+    P2PL2Adapter,
+    P2PL2AdapterConfig,
+)
+from lmcache.v1.distributed.transfer_channel.api import (
+    TransferChannelAddress,
+    TransferChannelReadResult,
+)
+from lmcache.v1.multiprocess.protocol import RequestType
+
+_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+
+def _key(i: int) -> ObjectKey:
+    return ObjectKey(chunk_hash=f"hash{i}".encode(), model_name="m", kv_rank=1)
+
+
+class _FakeFuture:
+    """Minimal MessagingFuture stand-in returning a value or raising."""
+
+    def __init__(self, value=None, exc=None):
+        self._value = value
+        self._exc = exc
+
+    def result(self, timeout=None):
+        if self._exc is not None:
+            raise self._exc
+        return self._value
+
+    def query(self) -> bool:
+        return self._exc is None
+
+
+@contextmanager
+def _adapter(lookup_timeout_s: float = 10.0, load_timeout_s: float = 10.0):
+    mq = MagicMock()
+    tc_ctx = MagicMock()
+    tc_client = MagicMock()
+    tc_ctx.get_transfer_channel_client.return_value = tc_client
+    tc_ctx.get_transfer_channel_address.side_effect = lambda pairs: [
+        TransferChannelAddress(offset=o, size=s) for o, s in pairs
+    ]
+    notifier = MagicMock()
+
+    with (
+        patch.object(p2p_mod, "MessageQueueClient", return_value=mq),
+        patch.object(p2p_mod, "get_transfer_channel_context", return_value=tc_ctx),
+        patch.object(p2p_mod, "PeriodicEventNotifier") as mock_pen,
+    ):
+        mock_pen.get.return_value = notifier
+        config = P2PL2AdapterConfig(
+            peer_mq_server_url="tcp://peer:5555",
+            peer_transfer_channel_server_url="peer:7600",
+            lookup_timeout_s=lookup_timeout_s,
+            load_timeout_s=load_timeout_s,
+        )
+        adapter = P2PL2Adapter(config)
+        try:
+            yield adapter, mq, tc_ctx, tc_client, notifier
+        finally:
+            adapter.close()
+
+
+def _lookup_side_effect(remote_task_id, addresses):
+    """submit_request dispatcher keyed on request type."""
+
+    def _dispatch(request_type, payloads, response_cls=None):
+        if request_type == RequestType.P2P_LOOKUP_AND_LOCK:
+            return _FakeFuture(value=remote_task_id)
+        if request_type == RequestType.P2P_QUERY_LOOKUP_RESULTS:
+            return _FakeFuture(value=addresses)
+        return _FakeFuture(value=None)
+
+    return _dispatch
+
+
+# ---------------------------------------------------------------------------
+# Config + factory
+# ---------------------------------------------------------------------------
+
+
+def test_config_from_dict_roundtrip():
+    config = P2PL2AdapterConfig.from_dict(
+        {
+            "type": "p2p",
+            "peer_mq_server_url": "tcp://peer:5555",
+            "peer_transfer_channel_server_url": "peer:7600",
+            "lookup_timeout_s": 4,
+            "load_timeout_s": 6,
+        }
+    )
+    assert config.peer_mq_server_url == "tcp://peer:5555"
+    assert config.peer_transfer_channel_server_url == "peer:7600"
+    assert config.lookup_timeout_s == 4.0
+    assert config.load_timeout_s == 6.0
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        {"type": "p2p", "peer_transfer_channel_server_url": "peer:7600"},
+        {"type": "p2p", "peer_mq_server_url": "tcp://peer:5555"},
+        {
+            "type": "p2p",
+            "peer_mq_server_url": "tcp://peer:5555",
+            "peer_transfer_channel_server_url": "peer:7600",
+            "lookup_timeout_s": -1,
+        },
+    ],
+)
+def test_config_from_dict_rejects_invalid(bad):
+    with pytest.raises(ValueError):
+        P2PL2AdapterConfig.from_dict(bad)
+
+
+def test_factory_creates_adapter():
+    # First Party
+    from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+
+    with (
+        patch.object(p2p_mod, "MessageQueueClient", return_value=MagicMock()),
+        patch.object(p2p_mod, "get_transfer_channel_context", return_value=MagicMock()),
+        patch.object(p2p_mod, "PeriodicEventNotifier") as mock_pen,
+    ):
+        mock_pen.get.return_value = MagicMock()
+        config = P2PL2AdapterConfig("tcp://peer:5555", "peer:7600")
+        adapter = create_l2_adapter(config)
+        assert isinstance(adapter, P2PL2Adapter)
+        adapter.close()
+
+
+# ---------------------------------------------------------------------------
+# Event fds + notifier registration
+# ---------------------------------------------------------------------------
+
+
+def test_event_fds_are_distinct_and_registered():
+    with _adapter() as (adapter, _mq, _tc_ctx, _tc, notifier):
+        fds = {
+            adapter.get_store_event_fd(),
+            adapter.get_lookup_and_lock_event_fd(),
+            adapter.get_load_event_fd(),
+        }
+        assert len(fds) == 3
+        registered = {c.args[0] for c in notifier.register_fd.call_args_list}
+        assert adapter.get_lookup_and_lock_event_fd() in registered
+        assert adapter.get_load_event_fd() in registered
+        # The store fd is a dummy and is never pulsed.
+        assert adapter.get_store_event_fd() not in registered
+
+
+# ---------------------------------------------------------------------------
+# Lookup
+# ---------------------------------------------------------------------------
+
+
+def test_lookup_forwards_layout_desc_and_returns_addresses():
+    keys = [_key(0), _key(1), _key(2)]
+    addresses = [
+        TransferChannelAddress(offset=100, size=10),
+        TransferChannelAddress(offset=200, size=20),
+        TransferChannelAddress(offset=-1, size=0),  # not found on peer
+    ]
+    with _adapter() as (adapter, mq, _tc_ctx, _tc, _notifier):
+        mq.submit_request.side_effect = _lookup_side_effect(42, addresses)
+
+        task_id = adapter.submit_lookup_and_lock_task(keys, _LAYOUT)
+
+        # The real layout_desc is forwarded into the lookup payload.
+        lookup_call = mq.submit_request.call_args_list[0]
+        assert lookup_call.args[0] == RequestType.P2P_LOOKUP_AND_LOCK
+        assert lookup_call.args[1] == [keys, _LAYOUT]
+        assert lookup_call.args[1][1] is _LAYOUT
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0) is True
+        assert bitmap.test(1) is True
+        assert bitmap.test(2) is False
+
+        # Valid addresses are stashed by key for the load phase.
+        assert adapter._remote_addresses[keys[0]] == addresses[0]
+        assert adapter._remote_addresses[keys[1]] == addresses[1]
+        assert keys[2] not in adapter._remote_addresses
+
+
+def test_lookup_query_not_ready_then_ready():
+    keys = [_key(0)]
+    addresses = [TransferChannelAddress(offset=100, size=10)]
+    with _adapter() as (adapter, mq, _tc_ctx, _tc, _notifier):
+        responses = iter([_FakeFuture(value=None), _FakeFuture(value=addresses)])
+
+        def _dispatch(request_type, payloads, response_cls=None):
+            if request_type == RequestType.P2P_LOOKUP_AND_LOCK:
+                return _FakeFuture(value=7)
+            if request_type == RequestType.P2P_QUERY_LOOKUP_RESULTS:
+                return next(responses)
+            return _FakeFuture(value=None)
+
+        mq.submit_request.side_effect = _dispatch
+        task_id = adapter.submit_lookup_and_lock_task(keys, _LAYOUT)
+
+        # First pulse: peer not ready yet.
+        assert adapter.query_lookup_and_lock_result(task_id) is None
+        # Second pulse: ready.
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None and bitmap.test(0) is True
+
+
+def test_lookup_submit_timeout_yields_miss():
+    keys = [_key(0), _key(1)]
+    with _adapter() as (adapter, mq, _tc_ctx, _tc, _notifier):
+
+        def _dispatch(request_type, payloads, response_cls=None):
+            if request_type == RequestType.P2P_LOOKUP_AND_LOCK:
+                return _FakeFuture(exc=TimeoutError())
+            return _FakeFuture(value=None)
+
+        mq.submit_request.side_effect = _dispatch
+        task_id = adapter.submit_lookup_and_lock_task(keys, _LAYOUT)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.popcount() == 0
+        # No P2P_QUERY_LOOKUP_RESULTS was issued for a failed lookup.
+        assert all(
+            c.args[0] != RequestType.P2P_QUERY_LOOKUP_RESULTS
+            for c in mq.submit_request.call_args_list
+        )
+
+
+def test_lookup_deadline_expired_yields_miss():
+    keys = [_key(0)]
+    with _adapter(lookup_timeout_s=0.01) as (adapter, mq, _tc_ctx, _tc, _notifier):
+        # Lookup id resolves, but the query is never ready before the deadline.
+        def _dispatch(request_type, payloads, response_cls=None):
+            if request_type == RequestType.P2P_LOOKUP_AND_LOCK:
+                return _FakeFuture(value=7)
+            return _FakeFuture(value=None)
+
+        mq.submit_request.side_effect = _dispatch
+        task_id = adapter.submit_lookup_and_lock_task(keys, _LAYOUT)
+        time.sleep(0.02)
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.popcount() == 0
+
+
+def test_query_unknown_task_returns_none():
+    with _adapter() as (adapter, _mq, _tc_ctx, _tc, _notifier):
+        assert adapter.query_lookup_and_lock_result(999) is None
+
+
+# ---------------------------------------------------------------------------
+# Load
+# ---------------------------------------------------------------------------
+
+
+def test_load_reads_into_local_objects():
+    keys = [_key(0), _key(1)]
+    with _adapter() as (adapter, _mq, _tc_ctx, tc_client, _notifier):
+        adapter._remote_addresses[keys[0]] = TransferChannelAddress(offset=100, size=10)
+        adapter._remote_addresses[keys[1]] = TransferChannelAddress(offset=200, size=20)
+        tc_client.submit_read.return_value = 55
+        tc_client.query_read_status.return_value = TransferChannelReadResult(
+            finished=True, succeeded_mask=[True, False]
+        )
+
+        objects = [
+            MagicMock(shm_offset=1000, shm_byte_length=10),
+            MagicMock(shm_offset=2000, shm_byte_length=20),
+        ]
+        task_id = adapter.submit_load_task(keys, objects)
+
+        local, remote = tc_client.submit_read.call_args.args
+        assert local == [
+            TransferChannelAddress(offset=1000, size=10),
+            TransferChannelAddress(offset=2000, size=20),
+        ]
+        assert remote == [
+            adapter._remote_addresses[keys[0]],
+            adapter._remote_addresses[keys[1]],
+        ]
+
+        bitmap = adapter.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0) is True
+        assert bitmap.test(1) is False
+
+
+def test_load_not_finished_returns_none():
+    keys = [_key(0)]
+    with _adapter() as (adapter, _mq, _tc_ctx, tc_client, _notifier):
+        adapter._remote_addresses[keys[0]] = TransferChannelAddress(offset=100, size=10)
+        tc_client.submit_read.return_value = 1
+        tc_client.query_read_status.return_value = TransferChannelReadResult(
+            finished=False
+        )
+        task_id = adapter.submit_load_task(
+            keys, [MagicMock(shm_offset=0, shm_byte_length=10)]
+        )
+        assert adapter.query_load_result(task_id) is None
+
+
+def test_load_deadline_expired_yields_failure():
+    keys = [_key(0)]
+    with _adapter(load_timeout_s=0.01) as (adapter, _mq, _tc_ctx, tc_client, _notifier):
+        adapter._remote_addresses[keys[0]] = TransferChannelAddress(offset=100, size=10)
+        tc_client.submit_read.return_value = 1
+        task_id = adapter.submit_load_task(
+            keys, [MagicMock(shm_offset=0, shm_byte_length=10)]
+        )
+        time.sleep(0.02)
+        bitmap = adapter.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.popcount() == 0
+
+
+# ---------------------------------------------------------------------------
+# Unlock + store no-ops + lifecycle
+# ---------------------------------------------------------------------------
+
+
+def test_unlock_sends_rpc_and_clears_addresses():
+    keys = [_key(0), _key(1)]
+    with _adapter() as (adapter, mq, _tc_ctx, _tc, _notifier):
+        adapter._remote_addresses[keys[0]] = TransferChannelAddress(offset=1, size=1)
+        adapter.submit_unlock(keys)
+        unlock_call = mq.submit_request.call_args
+        assert unlock_call.args[0] == RequestType.P2P_UNLOCK_OBJECTS
+        assert unlock_call.args[1] == [keys]
+        assert keys[0] not in adapter._remote_addresses
+
+
+def test_unlock_empty_is_noop():
+    with _adapter() as (adapter, mq, _tc_ctx, _tc, _notifier):
+        adapter.submit_unlock([])
+        mq.submit_request.assert_not_called()
+
+
+def test_store_completes_immediately_without_leaking():
+    with _adapter() as (adapter, _mq, _tc_ctx, _tc, _notifier):
+        task_id = adapter.submit_store_task([_key(0)], [MagicMock()])
+        completed = adapter.pop_completed_store_tasks()
+        assert set(completed) == {task_id}
+        assert completed[task_id].is_successful() is True
+        assert completed[task_id].bytes_transferred() == 0
+        # Draining clears the completed set.
+        assert adapter.pop_completed_store_tasks() == {}
+
+
+def test_load_missing_address_is_failure_not_raise():
+    keys = [_key(0)]
+    with _adapter() as (adapter, _mq, _tc_ctx, tc_client, _notifier):
+        # No lookup ran, so no remote address is stashed for this key.
+        task_id = adapter.submit_load_task(
+            keys, [MagicMock(shm_offset=0, shm_byte_length=10)]
+        )
+        tc_client.submit_read.assert_not_called()
+        bitmap = adapter.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.popcount() == 0
+
+
+def test_load_invalid_address_is_failure_not_raise():
+    keys = [_key(0)]
+    with _adapter() as (adapter, _mq, _tc_ctx, tc_client, _notifier):
+        # An invalid stashed address must be rejected, not read.
+        adapter._remote_addresses[keys[0]] = TransferChannelAddress(offset=-1, size=0)
+        task_id = adapter.submit_load_task(
+            keys, [MagicMock(shm_offset=0, shm_byte_length=10)]
+        )
+        tc_client.submit_read.assert_not_called()
+        bitmap = adapter.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.popcount() == 0
+
+
+def test_report_status():
+    with _adapter() as (adapter, _mq, _tc_ctx, _tc, _notifier):
+        status = adapter.report_status()
+        assert status["is_healthy"] is True
+        assert status["peer_mq_server_url"] == "tcp://peer:5555"
+        assert status["peer_transfer_channel_server_url"] == "peer:7600"
+        assert status["in_flight_lookups"] == 0
+        assert status["in_flight_loads"] == 0
+
+
+def test_close_unregisters_fds_and_closes_client():
+    with _adapter() as (adapter, mq, tc_ctx, _tc, notifier):
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+        adapter.close()
+        unregistered = {c.args[0] for c in notifier.unregister_fd.call_args_list}
+        assert lookup_fd in unregistered
+        assert load_fd in unregistered
+        mq.close.assert_called()
+        # The transfer-channel client is dropped from the context on close.
+        tc_ctx.remove_transfer_channel_client.assert_called_once_with("peer:7600")
+
+
+def test_close_is_idempotent():
+    with _adapter() as (adapter, mq, tc_ctx, _tc, _notifier):
+        adapter.close()
+        adapter.close()
+        # The second close is a no-op: no duplicate teardown of shared resources.
+        mq.close.assert_called_once()
+        tc_ctx.remove_transfer_channel_client.assert_called_once_with("peer:7600")
diff --git a/tests/v1/distributed/l2_adapters/test_p2p_l2_adapter_integration.py b/tests/v1/distributed/l2_adapters/test_p2p_l2_adapter_integration.py
new file mode 100644
index 0000000..70e1ada
--- /dev/null
+++ b/tests/v1/distributed/l2_adapters/test_p2p_l2_adapter_integration.py
@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: Apache-2.0
+"""In-process, real-NIXL integration test for the P2P L2 adapter.
+
+Stands up a peer side (a real ``StorageManager`` with objects in L1, a NIXL
+transfer-channel context registered against that L1, and an MQ server hosting a
+``P2PController``) and a local side (the global NIXL context over a destination
+buffer + a ``P2PL2Adapter``). It then drives the adapter through the full
+lookup -> load (loopback RDMA read) -> unlock lifecycle and verifies the pulled
+bytes match the peer's.
+
+Requires a working NIXL runtime and CUDA (the L1 pool is pinned DRAM); skipped
+otherwise.
+"""
+
+# Standard
+import itertools
+import time
+
+# Third Party
+import pytest
+import torch
+
+nixl = pytest.importorskip("nixl")
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+# Third Party
+import zmq  # noqa: E402
+
+# First Party
+from lmcache.v1.distributed.api import (  # noqa: E402
+    MemoryLayoutDesc,
+    ObjectKey,
+)
+from lmcache.v1.distributed.config import (  # noqa: E402
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.internal_api import L1MemoryDesc  # noqa: E402
+from lmcache.v1.distributed.l2_adapters.p2p_l2_adapter import (  # noqa: E402
+    P2PL2Adapter,
+    P2PL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager  # noqa: E402
+from lmcache.v1.distributed.transfer_channel import (  # noqa: E402
+    delete_transfer_channel_context,
+    initialize_transfer_channel_context,
+)
+from lmcache.v1.distributed.transfer_channel.impl.nixl_impl import (  # noqa: E402
+    NixlTransferChannelContext,
+)
+from lmcache.v1.multiprocess.config import (  # noqa: E402
+    CoordinatorConfig,
+    P2PConfig,
+)
+from lmcache.v1.multiprocess.modules.p2p_controller import P2PController  # noqa: E402
+from lmcache.v1.multiprocess.mq import MessageQueueServer  # noqa: E402
+from lmcache.v1.multiprocess.protocol import get_payload_classes  # noqa: E402
+
+_PAGE = 4096
+_NUM_KEYS = 3
+_port_counter = itertools.count(18300)
+
+
+def _next_url() -> str:
+    return f"127.0.0.1:{next(_port_counter)}"
+
+
+def _make_storage_manager(size_bytes: int) -> StorageManager:
+    memory_config = L1MemoryManagerConfig(
+        size_in_bytes=size_bytes,
+        use_lazy=False,
+        init_size_in_bytes=size_bytes,
+        align_bytes=_PAGE,
+    )
+    l1_config = L1ManagerConfig(
+        memory_config=memory_config,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+    config = StorageManagerConfig(
+        l1_manager_config=l1_config,
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+    return StorageManager(config)
+
+
+class _PeerContext:
+    """Minimal P2PController context -- only ``storage_manager`` is used."""
+
+    def __init__(self, storage_manager: StorageManager) -> None:
+        self.storage_manager = storage_manager
+
+
+def _key(i: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(i),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def _poll(fn, timeout_s: float = 10.0):
+    deadline = time.monotonic() + timeout_s
+    result = fn()
+    while result is None and time.monotonic() < deadline:
+        time.sleep(0.02)
+        result = fn()
+    return result
+
+
+def test_p2p_adapter_end_to_end():
+    keys = [_key(i) for i in range(_NUM_KEYS)]
+    layout = MemoryLayoutDesc(shapes=[torch.Size([_PAGE])], dtypes=[torch.uint8])
+
+    peer_sm = _make_storage_manager(64 * 1024 * 1024)
+    peer_tc_ctx = None
+    mq_server = None
+    adapter = None
+    local_buf = torch.zeros((_NUM_KEYS + 1) * _PAGE, dtype=torch.uint8)
+
+    try:
+        # --- Peer side: store known objects in L1 ---
+        reserved = peer_sm.reserve_write(keys, layout, mode="new")
+        assert all(reserved[k] is not None for k in keys)
+        expected_values = {}
+        for i, key in enumerate(keys):
+            value = i + 1
+            reserved[key].tensor.fill_(value)
+            expected_values[key] = value
+        peer_sm.finish_write(keys)
+
+        # --- Peer side: NIXL context over the peer's L1 pool ---
+        peer_l1_desc = peer_sm._l1_manager.get_l1_memory_desc()
+        peer_tc_url = _next_url()
+        peer_tc_ctx = NixlTransferChannelContext(
+            peer_l1_desc, listen_url=peer_tc_url, advertise_url=peer_tc_url
+        )
+
+        # --- Peer side: MQ server hosting the P2P controller ---
+        controller = P2PController(
+            _PeerContext(peer_sm),
+            P2PConfig(),
+            CoordinatorConfig(),
+            instance_id="peer",
+        )
+        peer_mq_url = f"tcp://{_next_url()}"
+        mq_server = MessageQueueServer(peer_mq_url, zmq.Context.instance())
+        specs = controller.get_handlers()
+        for spec in specs:
+            mq_server.add_blocking_handler(
+                spec.request_type,
+                get_payload_classes(spec.request_type),
+                spec.handler,
+            )
+        mq_server.add_normal_thread_pool([s.request_type for s in specs], max_workers=4)
+        mq_server.start()
+
+        # --- Local side: global NIXL context over the destination buffer ---
+        local_tc_url = _next_url()
+        local_l1_desc = L1MemoryDesc(
+            ptr=local_buf.data_ptr(),
+            size=local_buf.numel(),
+            align_bytes=_PAGE,
+        )
+        initialize_transfer_channel_context(
+            "nixl", local_l1_desc, local_tc_url, local_tc_url
+        )
+
+        # --- Build the adapter and drive the lifecycle ---
+        adapter = P2PL2Adapter(
+            P2PL2AdapterConfig(peer_mq_url, peer_tc_url, lookup_timeout_s=10.0)
+        )
+
+        # Lookup: every key is resident on the peer.
+        lookup_id = adapter.submit_lookup_and_lock_task(keys, layout)
+        bitmap = _poll(lambda: adapter.query_lookup_and_lock_result(lookup_id))
+        assert bitmap is not None
+        for i in range(_NUM_KEYS):
+            assert bitmap.test(i) is True
+        # Stashed remote addresses match the peer objects' real offsets.
+        for key in keys:
+            assert adapter._remote_addresses[key].offset == reserved[key].shm_offset
+
+        # Load: pull each key into a distinct page of the local buffer.
+        local_objs = [_LocalObj(offset=i * _PAGE, size=_PAGE) for i in range(_NUM_KEYS)]
+        load_id = adapter.submit_load_task(keys, local_objs)
+        load_bitmap = _poll(lambda: adapter.query_load_result(load_id))
+        assert load_bitmap is not None
+        for i, key in enumerate(keys):
+            assert load_bitmap.test(i) is True
+            page = local_buf[i * _PAGE : (i + 1) * _PAGE]
+            assert torch.all(page == expected_values[key]), (
+                f"page {i} did not receive the peer's bytes"
+            )
+
+        # Unlock: releases the peer locks and clears the stashed addresses.
+        adapter.submit_unlock(keys)
+        for key in keys:
+            assert key not in adapter._remote_addresses
+    finally:
+        if adapter is not None:
+            adapter.close()
+        if mq_server is not None:
+            mq_server.close()
+        delete_transfer_channel_context()
+        if peer_tc_ctx is not None:
+            peer_tc_ctx.close()
+        peer_sm.close()
+
+
+class _LocalObj:
+    """A stand-in for an L1 MemoryObj exposing only the offset/size the
+    adapter reads when translating local transfer-channel addresses."""
+
+    def __init__(self, offset: int, size: int) -> None:
+        self.shm_offset = offset
+        self.shm_byte_length = size
diff --git a/tests/v1/distributed/memory_manager/__init__.py b/tests/v1/distributed/memory_manager/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/distributed/memory_manager/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/distributed/memory_manager/test_gds_l1_memory_manager.py b/tests/v1/distributed/memory_manager/test_gds_l1_memory_manager.py
new file mode 100644
index 0000000..56f7702
--- /dev/null
+++ b/tests/v1/distributed/memory_manager/test_gds_l1_memory_manager.py
@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for ``GDSL1MemoryManager``.
+
+These are pure: the manager sits on the in-memory ``AddressManager``, so no
+CUDA / cuFile / GDS hardware is required (the actual slab DMA lives in
+``GDSContext`` and is covered separately).
+"""
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.config import GdsL1Config
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.memory_manager import GDSL1MemoryManager
+from lmcache.v1.memory_management import GDSMemoryObject
+
+_ALIGN = 4096
+
+
+def _config(size_bytes: int) -> GdsL1Config:
+    return GdsL1Config(file_location="/unused", size_in_bytes=size_bytes)
+
+
+def _layout(nbytes: int) -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(shapes=[torch.Size([nbytes])], dtypes=[torch.uint8])
+
+
+class TestAllocate:
+    def test_returns_distinct_gds_objects(self):
+        mgr = GDSL1MemoryManager(_config(1 << 20))
+        err, objs = mgr.allocate(_layout(4096), 3)
+        assert err == L1Error.SUCCESS
+        assert len(objs) == 3
+        assert all(isinstance(o, GDSMemoryObject) for o in objs)
+        # Non-overlapping slab regions.
+        assert len({o.slab_offset for o in objs}) == 3
+
+    def test_oom_is_all_or_nothing(self):
+        # Slab fits exactly two 4 KiB chunks; asking for three must fail and
+        # leave nothing reserved.
+        mgr = GDSL1MemoryManager(_config(2 * _ALIGN))
+        err, objs = mgr.allocate(_layout(4096), 3)
+        assert err == L1Error.OUT_OF_MEMORY
+        assert objs == []
+        assert mgr.get_memory_usage()[0] == 0
+
+    def test_chunk_size_rounded_up_to_alignment(self):
+        # 5000-byte chunk rounds up to 8192 (next 4 KiB multiple).
+        mgr = GDSL1MemoryManager(_config(1 << 20))
+        _, objs = mgr.allocate(_layout(5000), 1)
+        assert objs[0].get_physical_size() == 8192
+
+
+class TestFreeAndUsage:
+    def test_free_returns_all_space(self):
+        mgr = GDSL1MemoryManager(_config(1 << 20))
+        _, objs = mgr.allocate(_layout(4096), 2)
+        assert mgr.get_memory_usage()[0] == 2 * _ALIGN
+        assert mgr.free(objs) == L1Error.SUCCESS
+        assert mgr.get_memory_usage()[0] == 0
+
+    def test_total_is_slab_size(self):
+        used, total = GDSL1MemoryManager(_config(1 << 20)).get_memory_usage()
+        assert used == 0
+        assert total == (1 << 20)
+
+    def test_memcheck_consistent_through_cycles(self):
+        mgr = GDSL1MemoryManager(_config(1 << 20))
+        assert mgr.memcheck() is True
+        _, a = mgr.allocate(_layout(4096), 2)
+        _, b = mgr.allocate(_layout(8192), 1)
+        assert mgr.memcheck() is True
+        mgr.free(a)
+        mgr.free(b)
+        assert mgr.memcheck() is True
+
+
+class TestMisc:
+    def test_get_l1_memory_desc_is_none(self):
+        assert GDSL1MemoryManager(_config(1 << 20)).get_l1_memory_desc() is None
+
+    def test_close_does_not_raise(self):
+        GDSL1MemoryManager(_config(1 << 20)).close()
diff --git a/tests/v1/distributed/serde/__init__.py b/tests/v1/distributed/serde/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/distributed/serde/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/distributed/serde/test_asym_k16_v8_multi.py b/tests/v1/distributed/serde/test_asym_k16_v8_multi.py
new file mode 100644
index 0000000..2c5d469
--- /dev/null
+++ b/tests/v1/distributed/serde/test_asym_k16_v8_multi.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the asymmetric K16/V8 multi-output serde in
+``lmcache/v1/distributed/serde/asym_k16_v8.py``.
+
+Validates the storage-only-dequant path: ``(K, V)`` group on
+serialize, ``(K_out, V_out)`` group on deserialize, K bit-exact
+and V within FP8 noise.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import cast
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.asym_k16_v8 import (
+    AsymK16V8MultiDeserializer,
+    AsymK16V8MultiSerializer,
+)
+from lmcache.v1.distributed.serde.multi import MemoryObjGroup
+from lmcache.v1.memory_management import MemoryObj
+
+# =============================================================================
+# Test scaffolding (mirrors the _FakeMemoryObj in test_multi.py / test_fp8.py)
+# =============================================================================
+
+
+@dataclass
+class _FakeMemoryObj:
+    tensor: torch.Tensor
+
+
+def _bf16_tensor(*shape: int, seed: int) -> torch.Tensor:
+    g = torch.Generator().manual_seed(seed)
+    return torch.randn(*shape, dtype=torch.bfloat16, generator=g).contiguous()
+
+
+def _byte_buffer(num_bytes: int) -> MemoryObj:
+    return cast(
+        MemoryObj, _FakeMemoryObj(tensor=torch.zeros(num_bytes, dtype=torch.uint8))
+    )
+
+
+def _grp(*objs: object) -> MemoryObjGroup:
+    """Cast a tuple of test fakes to the production MemoryObjGroup type."""
+    return cast(MemoryObjGroup, objs)
+
+
+# Llama-3.1-8B-Instruct-shaped chunk: (n_layers=32, seq=64, n_kv_heads=8,
+# head_dim=128) is large enough to exercise per-tensor V scaling without
+# wasting test runtime.
+_LLAMA_KV_SHAPE = (32, 64, 8, 128)
+
+
+# =============================================================================
+# group_size and contract surface
+# =============================================================================
+
+
+def test_group_size_is_two_on_both_endpoints() -> None:
+    s = AsymK16V8MultiSerializer()
+    d = AsymK16V8MultiDeserializer()
+    assert s.group_size == 2
+    assert d.group_size == 2
+
+
+def test_validate_group_size_rejects_wrong_arity() -> None:
+    s = AsymK16V8MultiSerializer()
+    d = AsymK16V8MultiDeserializer()
+    buf = _byte_buffer(64)
+
+    with pytest.raises(ValueError, match="src group length 1"):
+        s.serialize(_grp(_FakeMemoryObj(tensor=torch.zeros(8))), buf)
+    with pytest.raises(ValueError, match="dst group length 3"):
+        d.deserialize(
+            buf,
+            _grp(
+                _FakeMemoryObj(tensor=torch.zeros(8)),
+                _FakeMemoryObj(tensor=torch.zeros(8)),
+                _FakeMemoryObj(tensor=torch.zeros(8)),
+            ),
+        )
+
+
+def test_serialize_rejects_none_slot_in_storage_only_mode() -> None:
+    """Storage-only-dequant mode requires both K and V."""
+    s = AsymK16V8MultiSerializer()
+    buf = _byte_buffer(64)
+    v = _FakeMemoryObj(tensor=_bf16_tensor(2, 4, seed=0))
+    with pytest.raises(ValueError, match="both K and V must be provided"):
+        s.serialize(_grp(None, v), buf)
+
+
+# =============================================================================
+# Round-trip: K bit-exact, V within FP8 noise
+# =============================================================================
+
+
+def test_storage_only_round_trip_k_bit_exact_v_within_fp8_noise() -> None:
+    s = AsymK16V8MultiSerializer()
+    d = AsymK16V8MultiDeserializer()
+
+    n_layers, seq, n_heads, head_dim = _LLAMA_KV_SHAPE
+    k = _bf16_tensor(n_layers, seq, n_heads, head_dim, seed=1)
+    v = _bf16_tensor(n_layers, seq, n_heads, head_dim, seed=2)
+    src = _grp(_FakeMemoryObj(tensor=k), _FakeMemoryObj(tensor=v))
+
+    layout = (
+        MemoryLayoutDesc(shapes=[k.shape], dtypes=[k.dtype]),
+        MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]),
+    )
+    capacity = s.estimate_serialized_size(layout)
+    buf = _byte_buffer(capacity)
+    n = s.serialize(src, buf)
+    assert 0 < n <= capacity
+
+    k_out = _FakeMemoryObj(tensor=torch.zeros_like(k))
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v))
+    d.deserialize(buf, _grp(k_out, v_out))
+
+    # K must be bit-exact.
+    assert torch.equal(k_out.tensor, k), "K must round-trip bit-exact"
+
+    # V is dequantized from FP8 e4m3 — bounded but non-zero error.
+    v_diff = (v_out.tensor.float() - v.float()).abs()
+    rel = v_diff / (v.float().abs() + 1e-6)
+    assert rel.median().item() < 0.075, (
+        f"V relative error median {rel.median().item():.4f} exceeds "
+        f"FP8 noise threshold 0.075"
+    )
+
+
+def test_storage_only_round_trip_with_skipped_v_dst_leaves_buf_untouched() -> None:
+    """Pass (K_out, None) to load K only; the V slot is a deliberate skip."""
+    s = AsymK16V8MultiSerializer()
+    d = AsymK16V8MultiDeserializer()
+
+    k = _bf16_tensor(4, 8, 8, 64, seed=3)
+    v = _bf16_tensor(4, 8, 8, 64, seed=4)
+    layout = (
+        MemoryLayoutDesc(shapes=[k.shape], dtypes=[k.dtype]),
+        MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]),
+    )
+    buf = _byte_buffer(s.estimate_serialized_size(layout))
+    s.serialize(_grp(_FakeMemoryObj(tensor=k), _FakeMemoryObj(tensor=v)), buf)
+
+    sentinel = torch.full_like(v, fill_value=42.0)
+    v_unused = _FakeMemoryObj(tensor=sentinel.clone())
+    k_out = _FakeMemoryObj(tensor=torch.zeros_like(k))
+    d.deserialize(buf, _grp(k_out, None))
+
+    assert torch.equal(k_out.tensor, k)
+    assert torch.equal(v_unused.tensor, sentinel), (
+        "deserialize must not touch a None dst slot"
+    )
+
+
+def test_estimate_serialized_size_is_non_decreasing_in_chunk_size() -> None:
+    """Sanity: larger chunks predict larger byte budgets."""
+    s = AsymK16V8MultiSerializer()
+    small = (
+        MemoryLayoutDesc(shapes=[torch.Size([2, 4, 8, 64])], dtypes=[torch.bfloat16]),
+        MemoryLayoutDesc(shapes=[torch.Size([2, 4, 8, 64])], dtypes=[torch.bfloat16]),
+    )
+    large = (
+        MemoryLayoutDesc(shapes=[torch.Size([2, 4, 8, 256])], dtypes=[torch.bfloat16]),
+        MemoryLayoutDesc(shapes=[torch.Size([2, 4, 8, 256])], dtypes=[torch.bfloat16]),
+    )
+    assert s.estimate_serialized_size(small) < s.estimate_serialized_size(large)
+
+
+def test_estimate_serialized_size_meets_actual_blob_length() -> None:
+    """estimate_serialized_size must be an upper bound on the produced blob."""
+    s = AsymK16V8MultiSerializer()
+    k = _bf16_tensor(2, 4, 8, 64, seed=5)
+    v = _bf16_tensor(2, 4, 8, 64, seed=6)
+    layout = (
+        MemoryLayoutDesc(shapes=[k.shape], dtypes=[k.dtype]),
+        MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]),
+    )
+    capacity = s.estimate_serialized_size(layout)
+    buf = _byte_buffer(capacity)
+    n = s.serialize(_grp(_FakeMemoryObj(tensor=k), _FakeMemoryObj(tensor=v)), buf)
+    assert n <= capacity, (
+        f"actual blob {n} bytes exceeded estimate {capacity}; "
+        f"estimate must be a true upper bound"
+    )
diff --git a/tests/v1/distributed/serde/test_asym_k16_v8_v_only.py b/tests/v1/distributed/serde/test_asym_k16_v8_v_only.py
new file mode 100644
index 0000000..e3cdddf
--- /dev/null
+++ b/tests/v1/distributed/serde/test_asym_k16_v8_v_only.py
@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the asymmetric K16/V8 split-tier (V-only)
+multi-output serde in ``lmcache/v1/distributed/serde/asym_k16_v8.py``.
+
+Validates the V-only-write path:
+
+* ``serialize`` accepts ``src = (None, V)``: K is not written to
+  the byte buffer (the K slot must be ``None``); only V_fp8 +
+  scales hit L2.
+* ``deserialize`` accepts ``src = blob``, ``dst = (None|K_skip,
+  V_out)``: V is restored from the blob's FP8 + scales; the K slot
+  is a no-op regardless of whether the caller provides one.
+
+The byte-ratio claim under test: the V-only blob is
+``V_8 / (K_16 + V_16) = 1/4`` of FP16 KV -- equivalently ``1/3``
+of the corresponding storage-only-dequant blob (which carries both
+K and V).
+
+Cross-mode cases are also covered: a V-only deserializer must
+refuse a storage-only-dequant blob (K is present), and the
+storage-only-dequant deserializer would mis-decode a V-only blob
+(only the V-only deserializer recognizes ``k_payload_len = 0``).
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import cast
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.asym_k16_v8 import (
+    AsymK16V8MultiSerializer,
+    AsymK16V8VOnlyMultiDeserializer,
+    AsymK16V8VOnlyMultiSerializer,
+)
+from lmcache.v1.distributed.serde.multi import MemoryObjGroup
+from lmcache.v1.memory_management import MemoryObj
+
+# Mirror the _FakeMemoryObj used elsewhere; lets the test stay GPU-free
+# and L1Manager-free.
+
+
+@dataclass
+class _FakeMemoryObj:
+    tensor: torch.Tensor
+
+
+def _bf16_tensor(*shape: int, seed: int) -> torch.Tensor:
+    g = torch.Generator().manual_seed(seed)
+    return torch.randn(*shape, dtype=torch.bfloat16, generator=g).contiguous()
+
+
+def _byte_buffer(num_bytes: int) -> MemoryObj:
+    return cast(
+        MemoryObj, _FakeMemoryObj(tensor=torch.zeros(num_bytes, dtype=torch.uint8))
+    )
+
+
+def _grp(*objs: object) -> MemoryObjGroup:
+    """Cast a tuple of test fakes to the production MemoryObjGroup type."""
+    return cast(MemoryObjGroup, objs)
+
+
+# Llama-3.1-8B-Instruct-shaped chunk; same dimensions as the
+# storage-only-dequant tests for direct ratio comparability.
+_LLAMA_KV_SHAPE = (32, 64, 8, 128)
+
+
+# =============================================================================
+# group_size and contract surface
+# =============================================================================
+
+
+def test_group_size_is_two_on_both_endpoints() -> None:
+    s = AsymK16V8VOnlyMultiSerializer()
+    d = AsymK16V8VOnlyMultiDeserializer()
+    assert s.group_size == 2
+    assert d.group_size == 2
+
+
+def test_serialize_rejects_k_present() -> None:
+    """K slot must be None — providing K is a contract error."""
+    s = AsymK16V8VOnlyMultiSerializer()
+    k = _FakeMemoryObj(tensor=_bf16_tensor(2, 4, seed=0))
+    v = _FakeMemoryObj(tensor=_bf16_tensor(2, 4, seed=1))
+    buf = _byte_buffer(64)
+    with pytest.raises(ValueError, match="K slot must be None"):
+        s.serialize(_grp(k, v), buf)
+
+
+def test_serialize_requires_v() -> None:
+    s = AsymK16V8VOnlyMultiSerializer()
+    buf = _byte_buffer(64)
+    with pytest.raises(ValueError, match="V slot is required"):
+        s.serialize(_grp(None, None), buf)
+    v_no_tensor = _FakeMemoryObj(tensor=None)  # type: ignore[arg-type]
+    with pytest.raises(ValueError, match="V slot is required"):
+        s.serialize(_grp(None, v_no_tensor), buf)
+
+
+def test_estimate_serialized_size_rejects_k_layout_present() -> None:
+    s = AsymK16V8VOnlyMultiSerializer()
+    v_layout = MemoryLayoutDesc(shapes=[torch.Size([2, 4])], dtypes=[torch.bfloat16])
+    k_layout = MemoryLayoutDesc(shapes=[torch.Size([2, 4])], dtypes=[torch.bfloat16])
+    with pytest.raises(ValueError, match="K layout must be None"):
+        s.estimate_serialized_size((k_layout, v_layout))
+    with pytest.raises(ValueError, match="V layout is required"):
+        s.estimate_serialized_size((None, None))
+
+
+# =============================================================================
+# Round-trip: V-only write, V-only read
+# =============================================================================
+
+
+def test_v_only_round_trip_v_within_fp8_noise() -> None:
+    s = AsymK16V8VOnlyMultiSerializer()
+    d = AsymK16V8VOnlyMultiDeserializer()
+
+    v = _bf16_tensor(*_LLAMA_KV_SHAPE, seed=2)
+
+    layout = (
+        None,
+        MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]),
+    )
+    capacity = s.estimate_serialized_size(layout)
+    buf = _byte_buffer(capacity)
+    n = s.serialize(_grp(None, _FakeMemoryObj(tensor=v)), buf)
+    assert 0 < n <= capacity
+
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v))
+    d.deserialize(buf, _grp(None, v_out))
+
+    v_diff = (v_out.tensor.float() - v.float()).abs()
+    rel = v_diff / (v.float().abs() + 1e-6)
+    assert rel.median().item() < 0.075, (
+        f"V-only relative error median {rel.median().item():.4f} "
+        f"exceeds FP8 noise threshold 0.075"
+    )
+
+
+def test_v_only_deserialize_ignores_k_slot() -> None:
+    """A non-None K dst slot is a no-op for the V-only deserializer."""
+    s = AsymK16V8VOnlyMultiSerializer()
+    d = AsymK16V8VOnlyMultiDeserializer()
+
+    v = _bf16_tensor(2, 4, 8, 64, seed=3)
+    layout = (None, MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]))
+    buf = _byte_buffer(s.estimate_serialized_size(layout))
+    s.serialize(_grp(None, _FakeMemoryObj(tensor=v)), buf)
+
+    sentinel = torch.full((2, 4, 8, 64), fill_value=42.0, dtype=torch.bfloat16)
+    k_unused = _FakeMemoryObj(tensor=sentinel.clone())
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v))
+    d.deserialize(buf, _grp(k_unused, v_out))
+
+    # K must be untouched.
+    assert torch.equal(k_unused.tensor, sentinel)
+
+
+# =============================================================================
+# Byte ratio: V-only blob == 1/3 of storage-only-dequant blob
+# =============================================================================
+
+
+def test_v_only_blob_is_one_third_of_storage_only_blob() -> None:
+    """V-only blob bytes = V_8 + scales + small header.
+
+    Storage-only-dequant blob bytes = K_16 + V_8 + scales + small
+    header.  The layout-invariant ratio V-only / storage-only =
+    V_8 / (K_16 + V_8) = 1/3.  Test on a chunk size where the
+    headers are negligible relative to the payload so the ratio
+    resolves cleanly.
+    """
+    storage_only_s = AsymK16V8MultiSerializer()
+    v_only_s = AsymK16V8VOnlyMultiSerializer()
+
+    # Big-enough chunk that header overhead is < 0.5%.
+    k = _bf16_tensor(*_LLAMA_KV_SHAPE, seed=4)
+    v = _bf16_tensor(*_LLAMA_KV_SHAPE, seed=5)
+
+    storage_only_layout = (
+        MemoryLayoutDesc(shapes=[k.shape], dtypes=[k.dtype]),
+        MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]),
+    )
+    v_only_layout = (None, MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]))
+
+    storage_only_buf = _byte_buffer(
+        storage_only_s.estimate_serialized_size(storage_only_layout)
+    )
+    v_only_buf = _byte_buffer(v_only_s.estimate_serialized_size(v_only_layout))
+    storage_only_n = storage_only_s.serialize(
+        _grp(_FakeMemoryObj(tensor=k), _FakeMemoryObj(tensor=v)), storage_only_buf
+    )
+    v_only_n = v_only_s.serialize(_grp(None, _FakeMemoryObj(tensor=v)), v_only_buf)
+
+    ratio = v_only_n / storage_only_n
+    # Tolerance for header overhead.
+    assert abs(ratio - 1.0 / 3.0) < 0.005, (
+        f"v_only/storage_only byte ratio {ratio:.4f} should be ~0.3333; "
+        f"storage_only_bytes={storage_only_n}, v_only_bytes={v_only_n}"
+    )
+
+
+# =============================================================================
+# Cross-mode: V-only deserializer must refuse a storage-only-dequant blob
+# =============================================================================
+
+
+def test_v_only_deserializer_refuses_storage_only_blob() -> None:
+    """A storage-only-dequant blob has k_payload_len > 0; the V-only
+    deserializer must reject it rather than silently mis-decode."""
+    storage_only_s = AsymK16V8MultiSerializer()
+    v_only_d = AsymK16V8VOnlyMultiDeserializer()
+
+    k = _bf16_tensor(2, 4, 8, 64, seed=6)
+    v = _bf16_tensor(2, 4, 8, 64, seed=7)
+    layout = (
+        MemoryLayoutDesc(shapes=[k.shape], dtypes=[k.dtype]),
+        MemoryLayoutDesc(shapes=[v.shape], dtypes=[v.dtype]),
+    )
+    buf = _byte_buffer(storage_only_s.estimate_serialized_size(layout))
+    storage_only_s.serialize(
+        _grp(_FakeMemoryObj(tensor=k), _FakeMemoryObj(tensor=v)), buf
+    )
+
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v))
+    with pytest.raises(ValueError, match="storage-only-dequant"):
+        v_only_d.deserialize(buf, _grp(None, v_out))
diff --git a/tests/v1/distributed/serde/test_async_processor.py b/tests/v1/distributed/serde/test_async_processor.py
new file mode 100644
index 0000000..7c889ab
--- /dev/null
+++ b/tests/v1/distributed/serde/test_async_processor.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for AsyncSerdeProcessor.
+
+Verifies the async, notifier-based contract:
+- submit returns a task id immediately.
+- The corresponding notifier fd is signaled on completion.
+- query_result returns the bool outcome, None before completion and after
+  being consumed (non-idempotent).
+- Failing serialize/deserialize produces result=False and still signals fd.
+- Serialize and deserialize use distinct event fds.
+"""
+
+# Standard
+from typing import Callable, Optional
+import select
+import time
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde import (
+    AsyncSerdeProcessor,
+    Deserializer,
+    Serializer,
+)
+from lmcache.v1.platform import consume_fd
+
+
+class _FakeSerializer(Serializer):
+    def __init__(self, transform: Optional[Callable[[int], None]] = None) -> None:
+        self._transform = transform
+        self.calls = 0
+
+    def serialize(self, src, dst) -> int:  # type: ignore[no-untyped-def]
+        if self._transform is not None:
+            self._transform(self.calls)
+        self.calls += 1
+        return 1
+
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        return 1
+
+
+class _FakeDeserializer(Deserializer):
+    def __init__(self, transform: Optional[Callable[[int], None]] = None) -> None:
+        self._transform = transform
+        self.calls = 0
+
+    def deserialize(self, src, dst) -> None:  # type: ignore[no-untyped-def]
+        if self._transform is not None:
+            self._transform(self.calls)
+        self.calls += 1
+
+
+def _wait_for_fd(fd: int, timeout_s: float = 2.0) -> bool:
+    """Wait until ``fd`` is readable or timeout. Drains the pending signal."""
+    poller = select.poll()
+    poller.register(fd, select.POLLIN)
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        remaining_ms = int(max(0, (deadline - time.monotonic()) * 1000))
+        if poller.poll(remaining_ms):
+            try:
+                consume_fd(fd)
+            except OSError:
+                pass
+            return True
+    return False
+
+
+def test_serialize_and_deserialize_fds_are_distinct() -> None:
+    processor = AsyncSerdeProcessor(_FakeSerializer(), _FakeDeserializer())
+    try:
+        assert (
+            processor.get_serialize_event_fd() != processor.get_deserialize_event_fd()
+        )
+    finally:
+        processor.close()
+
+
+def test_serialize_signals_fd_and_result_is_true() -> None:
+    serializer = _FakeSerializer()
+    processor = AsyncSerdeProcessor(serializer, _FakeDeserializer())
+    try:
+        task_id = processor.submit_serialize([object()], [object()])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_serialize_event_fd()), "fd never signaled"
+        assert processor.query_serialize_result(task_id) is True
+        # Non-idempotent: second query returns None.
+        assert processor.query_serialize_result(task_id) is None
+        assert serializer.calls == 1
+    finally:
+        processor.close()
+
+
+def test_deserialize_signals_fd_and_result_is_true() -> None:
+    deserializer = _FakeDeserializer()
+    processor = AsyncSerdeProcessor(_FakeSerializer(), deserializer)
+    try:
+        task_id = processor.submit_deserialize([object()], [object()])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_deserialize_event_fd()), "fd never signaled"
+        assert processor.query_deserialize_result(task_id) is True
+        assert processor.query_deserialize_result(task_id) is None
+        assert deserializer.calls == 1
+    finally:
+        processor.close()
+
+
+def test_serialize_failure_reports_false() -> None:
+    """If the sync serializer raises, query_serialize_result returns False."""
+
+    def _boom(_i: int) -> None:
+        raise RuntimeError("serialize failed")
+
+    processor = AsyncSerdeProcessor(_FakeSerializer(_boom), _FakeDeserializer())
+    try:
+        task_id = processor.submit_serialize([object()], [object()])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_serialize_event_fd()), "fd never signaled"
+        assert processor.query_serialize_result(task_id) is False
+    finally:
+        processor.close()
+
+
+def test_query_returns_none_before_completion() -> None:
+    """Querying an unknown/not-yet-completed task yields None, not an error."""
+    processor = AsyncSerdeProcessor(_FakeSerializer(), _FakeDeserializer())
+    try:
+        # No task submitted with id 42 — should be None, not raise.
+        assert processor.query_serialize_result(42) is None
+        assert processor.query_deserialize_result(42) is None
+    finally:
+        processor.close()
+
+
+def test_estimate_serialized_size_delegates_to_serializer() -> None:
+    serializer = _FakeSerializer()
+    processor = AsyncSerdeProcessor(serializer, _FakeDeserializer())
+    try:
+        layout = MemoryLayoutDesc(shapes=[], dtypes=[])
+        assert processor.estimate_serialized_size(layout) == 1
+    finally:
+        processor.close()
+
+
+# ---------------------------------------------------------------------------
+# set_used_size propagation: after serialize returns ``n``, the processor
+# narrows the destination's logical size so downstream L2 adapters that
+# read ``obj.get_size()`` / ``obj.byte_array`` see exactly ``n`` bytes.
+# ---------------------------------------------------------------------------
+
+
+class _RecordingSerializer(Serializer):
+    """A serializer that always claims to have written ``n_bytes`` so
+    tests can assert the processor narrows the destination accordingly.
+    """
+
+    def __init__(self, n_bytes: int) -> None:
+        self._n_bytes = n_bytes
+
+    def serialize(self, src, dst) -> int:  # type: ignore[no-untyped-def]
+        return self._n_bytes
+
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        return self._n_bytes
+
+
+class _NarrowableDst:
+    """A minimal MemoryObj-like destination that records every
+    ``set_used_size`` call.  Not a real ``MemoryObj`` -- the test only
+    needs the part of the interface the processor touches."""
+
+    def __init__(self) -> None:
+        self.used_sizes: list[int] = []
+
+    def set_used_size(self, n: int) -> None:
+        self.used_sizes.append(n)
+
+
+def test_serialize_narrows_dst_to_actual_bytes_written() -> None:
+    """After a successful serialize that returns ``n``, the processor
+    calls ``dst.set_used_size(n)`` so the over-allocated destination
+    buffer reports the actual written length, not its allocated size."""
+    serializer = _RecordingSerializer(n_bytes=213)
+    processor = AsyncSerdeProcessor(serializer, _FakeDeserializer())
+    try:
+        dst = _NarrowableDst()
+        task_id = processor.submit_serialize([object()], [dst])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_serialize_event_fd()), "fd never signaled"
+        assert processor.query_serialize_result(task_id) is True
+        assert dst.used_sizes == [213]
+    finally:
+        processor.close()
+
+
+def test_serialize_failure_does_not_narrow_dst() -> None:
+    """If the serializer raises, the processor must NOT narrow the
+    destination -- failure cleanup typically reuses the original
+    allocation and the next attempt depends on the layout-derived
+    size."""
+
+    class _BoomSerializer(Serializer):
+        def serialize(self, src, dst) -> int:  # type: ignore[no-untyped-def]
+            raise RuntimeError("serialize failed")
+
+        def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+            return 1
+
+    processor = AsyncSerdeProcessor(_BoomSerializer(), _FakeDeserializer())
+    try:
+        dst = _NarrowableDst()
+        task_id = processor.submit_serialize([object()], [dst])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_serialize_event_fd()), "fd never signaled"
+        assert processor.query_serialize_result(task_id) is False
+        assert dst.used_sizes == [], "narrowing must not happen on failure"
+    finally:
+        processor.close()
+
+
+def test_serialize_works_when_dst_lacks_set_used_size() -> None:
+    """Backward compatibility: a duck-typed destination that does NOT
+    implement ``set_used_size`` (e.g. a bare ``object()`` in older
+    tests) must still produce a successful task; the processor guards
+    the narrowing call with ``hasattr``."""
+    processor = AsyncSerdeProcessor(_FakeSerializer(), _FakeDeserializer())
+    try:
+        task_id = processor.submit_serialize([object()], [object()])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_serialize_event_fd()), "fd never signaled"
+        # Success despite dst lacking set_used_size.
+        assert processor.query_serialize_result(task_id) is True
+    finally:
+        processor.close()
+
+
+def test_serialize_skips_narrowing_when_serializer_returns_non_int() -> None:
+    """A serializer that does not honor the ``serialize() -> int``
+    contract and returns ``None`` must not crash the processor.  The
+    narrowing call is skipped (``isinstance(n, int)`` guard) rather than
+    passing ``None`` into ``set_used_size``, where the range check would
+    raise ``TypeError: '<' not supported between NoneType and int``."""
+
+    class _NoneReturningSerializer(Serializer):
+        def serialize(self, src, dst):  # type: ignore[no-untyped-def]
+            return None  # type: ignore[return-value]
+
+        def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+            return 1
+
+    processor = AsyncSerdeProcessor(_NoneReturningSerializer(), _FakeDeserializer())
+    try:
+        dst = _NarrowableDst()
+        task_id = processor.submit_serialize([object()], [dst])  # type: ignore[list-item]
+        assert _wait_for_fd(processor.get_serialize_event_fd()), "fd never signaled"
+        # Task still succeeds; narrowing was skipped, not attempted.
+        assert processor.query_serialize_result(task_id) is True
+        assert dst.used_sizes == [], "must not call set_used_size with a non-int"
+    finally:
+        processor.close()
diff --git a/tests/v1/distributed/serde/test_factory.py b/tests/v1/distributed/serde/test_factory.py
new file mode 100644
index 0000000..3036ef5
--- /dev/null
+++ b/tests/v1/distributed/serde/test_factory.py
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the serde factory + config wiring.
+
+Covers:
+- Built-in ``"fp8"`` registration.
+- Custom factory registration + dispatch.
+- Error paths for missing/unknown ``type``.
+- L2 adapter JSON config parses ``serde`` sub-dict.
+"""
+
+# Standard
+import json
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.config import (
+    add_l2_adapters_args,
+    parse_args_to_l2_adapters_config,
+)
+from lmcache.v1.distributed.serde import (
+    AsyncSerdeProcessor,
+    SerdeConfig,
+    SerdeProcessor,
+    create_serde_processor,
+    get_registered_serde_types,
+    register_serde_factory,
+)
+
+# =============================================================================
+# Factory registration + dispatch
+# =============================================================================
+
+
+def test_fp8_is_registered_by_default() -> None:
+    """The built-in fp8 serde is available without extra setup."""
+    assert "fp8" in get_registered_serde_types()
+
+
+def test_create_fp8_returns_async_processor() -> None:
+    """fp8 config produces an AsyncSerdeProcessor with distinct event fds."""
+    processor = create_serde_processor(SerdeConfig(type="fp8"))
+    try:
+        assert isinstance(processor, AsyncSerdeProcessor)
+        s_fd = processor.get_serialize_event_fd()
+        d_fd = processor.get_deserialize_event_fd()
+        assert s_fd != d_fd
+    finally:
+        processor.close()
+
+
+def test_create_serde_unknown_type_raises() -> None:
+    with pytest.raises(ValueError, match="Unknown serde type"):
+        create_serde_processor(SerdeConfig(type="does-not-exist"))
+
+
+def test_create_fp8_accepts_float_max_workers() -> None:
+    """``max_workers`` from a YAML float (e.g. 2.0) must round to int.
+
+    Regression: the old ``int(str(...))`` parse rejected float-encoded
+    integers; direct ``int(...)`` handles ints, floats, and digit
+    strings uniformly.
+    """
+    processor = create_serde_processor(
+        SerdeConfig(type="fp8", kwargs={"max_workers": 2.0})
+    )
+    try:
+        assert isinstance(processor, AsyncSerdeProcessor)
+    finally:
+        processor.close()
+
+
+def test_register_serde_factory_dispatch() -> None:
+    """A custom factory is dispatched by its registered name."""
+
+    seen: dict[str, dict] = {}
+
+    class _DummyProcessor(SerdeProcessor):
+        def get_serialize_event_fd(self) -> int:
+            return -1
+
+        def get_deserialize_event_fd(self) -> int:
+            return -1
+
+        def submit_serialize(self, src_objs, dst_objs):  # type: ignore[no-untyped-def]
+            return 0
+
+        def query_serialize_result(self, task_id):  # type: ignore[no-untyped-def]
+            return True
+
+        def submit_deserialize(self, src_objs, dst_objs):  # type: ignore[no-untyped-def]
+            return 0
+
+        def query_deserialize_result(self, task_id):  # type: ignore[no-untyped-def]
+            return True
+
+        def estimate_serialized_size(self, layout_desc) -> int:  # type: ignore[no-untyped-def]
+            return 1
+
+        def close(self) -> None:
+            pass
+
+    def _factory(kwargs: dict) -> SerdeProcessor:
+        seen["kwargs"] = kwargs
+        return _DummyProcessor()
+
+    # Use a unique name to avoid collisions if the test runs twice.
+    register_serde_factory("test-dummy-ser-de-xyz", _factory)
+
+    processor = create_serde_processor(
+        SerdeConfig(type="test-dummy-ser-de-xyz", kwargs={"foo": "bar"})
+    )
+    assert isinstance(processor, _DummyProcessor)
+    # Factory only receives the type-specific kwargs, not the wrapping type.
+    assert seen["kwargs"] == {"foo": "bar"}
+
+
+def test_register_serde_factory_duplicate_raises() -> None:
+    """Registering the same name twice is rejected."""
+
+    def _factory(config: dict) -> SerdeProcessor:  # pragma: no cover - not called
+        raise NotImplementedError
+
+    with pytest.raises(ValueError, match="already registered"):
+        register_serde_factory("fp8", _factory)
+
+
+# =============================================================================
+# L2 adapter JSON config
+# =============================================================================
+
+
+def _parse_adapter(spec: dict):  # type: ignore[no-untyped-def]
+    """Helper: run the argparse plumbing on a single adapter JSON spec."""
+    # Standard
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    add_l2_adapters_args(parser)
+    args = parser.parse_args(["--l2-adapter", json.dumps(spec)])
+    cfg = parse_args_to_l2_adapters_config(args)
+    return cfg.adapters[0]
+
+
+def test_adapter_config_without_serde() -> None:
+    adapter = _parse_adapter({"type": "mock", "max_size_gb": 1, "mock_bandwidth_gb": 1})
+    assert adapter.serde_config is None
+
+
+def test_adapter_config_with_serde() -> None:
+    serde_spec = {"type": "fp8", "fp8_dtype": "float8_e4m3fn"}
+    adapter = _parse_adapter(
+        {"type": "mock", "max_size_gb": 1, "mock_bandwidth_gb": 1, "serde": serde_spec}
+    )
+    assert adapter.serde_config is not None
+    assert adapter.serde_config.type == "fp8"
+    assert adapter.serde_config.kwargs == {"fp8_dtype": "float8_e4m3fn"}
+
+
+def test_adapter_config_rejects_non_dict_serde() -> None:
+    with pytest.raises(ValueError, match="'serde' must be a dict"):
+        _parse_adapter(
+            {"type": "mock", "max_size_gb": 1, "mock_bandwidth_gb": 1, "serde": "fp8"}
+        )
+
+
+def test_adapter_config_rejects_serde_without_type() -> None:
+    with pytest.raises(ValueError, match="'serde' dict must include a 'type' field"):
+        _parse_adapter(
+            {
+                "type": "mock",
+                "max_size_gb": 1,
+                "mock_bandwidth_gb": 1,
+                "serde": {"fp8_dtype": "float8_e4m3fn"},
+            }
+        )
diff --git a/tests/v1/distributed/serde/test_fp8.py b/tests/v1/distributed/serde/test_fp8.py
new file mode 100644
index 0000000..ed2e44c
--- /dev/null
+++ b/tests/v1/distributed/serde/test_fp8.py
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for Fp8QuantizationSerializer / Fp8QuantizationDeserializer.
+
+These tests use BytesBufferMemoryObj and TensorMemoryObj directly so they
+do not need an L1Manager or GPU; they verify the pure transform logic.
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.fp8 import (
+    Fp8QuantizationDeserializer,
+    Fp8QuantizationSerializer,
+)
+
+
+@dataclass
+class _FakeMemoryObj:
+    """Minimal stand-in exposing the ``.tensor`` attribute used by fp8 serde."""
+
+    tensor: Optional[torch.Tensor]
+
+
+# =============================================================================
+# estimate_serialized_size
+# =============================================================================
+
+
+def test_estimate_serialized_size_single_group() -> None:
+    """Estimate is exactly num_elements bytes (1 byte/elem, no margin)."""
+    serializer = Fp8QuantizationSerializer()
+    layout = MemoryLayoutDesc(
+        shapes=[torch.Size([2, 4, 256, 128])],
+        dtypes=[torch.bfloat16],
+    )
+    numel = 2 * 4 * 256 * 128
+    assert serializer.estimate_serialized_size(layout) == numel
+
+
+def test_estimate_serialized_size_multi_group() -> None:
+    """Multi-group layouts sum element counts across groups."""
+    serializer = Fp8QuantizationSerializer()
+    layout = MemoryLayoutDesc(
+        shapes=[torch.Size([4, 8]), torch.Size([16])],
+        dtypes=[torch.bfloat16, torch.float16],
+    )
+    numel = 32 + 16
+    assert serializer.estimate_serialized_size(layout) == numel
+
+
+# =============================================================================
+# serialize / deserialize round-trip
+# =============================================================================
+
+
+def test_roundtrip_bfloat16_preserves_structure() -> None:
+    """Values survive fp8 round-trip with high correlation."""
+    shape = torch.Size([2, 4, 64, 128])
+    original = torch.randn(
+        shape, dtype=torch.bfloat16, generator=torch.Generator().manual_seed(0)
+    )
+    src = _FakeMemoryObj(tensor=original.clone())
+
+    # fp8 = 1 byte/elem; temp buffer is plain uint8.
+    temp = _FakeMemoryObj(tensor=torch.zeros(original.numel(), dtype=torch.uint8))
+
+    serializer = Fp8QuantizationSerializer()
+    n = serializer.serialize(src, temp)  # type: ignore[arg-type]
+    assert n == original.numel()
+
+    # Round-trip: deserialize into a fresh buffer with the original shape.
+    recovered = _FakeMemoryObj(tensor=torch.zeros(shape, dtype=torch.bfloat16))
+    Fp8QuantizationDeserializer().deserialize(temp, recovered)  # type: ignore[arg-type]
+
+    assert recovered.tensor is not None
+    corr = torch.corrcoef(
+        torch.stack([recovered.tensor.float().flatten(), original.float().flatten()])
+    )[0, 1].item()
+    assert corr > 0.99, f"fp8 round-trip correlation too low: {corr:.4f}"
+
+
+def test_serialize_raises_on_missing_tensor() -> None:
+    """A MemoryObj without ``.tensor`` is rejected rather than silently no-op'd."""
+    serializer = Fp8QuantizationSerializer()
+    src = _FakeMemoryObj(tensor=None)
+    dst = _FakeMemoryObj(tensor=torch.zeros(4, dtype=torch.uint8))
+    with pytest.raises(ValueError):
+        serializer.serialize(src, dst)  # type: ignore[arg-type]
+
+
+def test_deserialize_raises_on_missing_tensor() -> None:
+    deserializer = Fp8QuantizationDeserializer()
+    src = _FakeMemoryObj(tensor=torch.zeros(4, dtype=torch.uint8))
+    dst = _FakeMemoryObj(tensor=None)
+    with pytest.raises(ValueError):
+        deserializer.deserialize(src, dst)  # type: ignore[arg-type]
diff --git a/tests/v1/distributed/serde/test_multi.py b/tests/v1/distributed/serde/test_multi.py
new file mode 100644
index 0000000..328d794
--- /dev/null
+++ b/tests/v1/distributed/serde/test_multi.py
@@ -0,0 +1,449 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the multi-output serde extensions in
+``lmcache/v1/distributed/serde/multi.py``.
+
+These tests exercise the additive contract:
+
+* Fixed-length :class:`MemoryObjGroup` semantics, including the
+  ``None`` slot meaning "absent on serialize input" or "skip on
+  deserialize output".
+* The single-to-multi adapters preserve exact bytes vs the
+  underlying single-tensor :class:`Serializer` /
+  :class:`Deserializer` (so existing serdes opt into the group
+  call site without changing their on-the-wire format).
+* :func:`validate_group_size` rejects mismatched group lengths
+  with messages that name the offending side.
+
+The test deliberately uses a toy "concat" multi-serde defined
+in-file (rather than importing a production multi-serde) so that
+the tests pin down the API contract without depending on any
+specific concrete implementation. The format is documented inline.
+"""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from dataclasses import dataclass
+from typing import cast
+import struct
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.serde.base import Deserializer, Serializer
+from lmcache.v1.distributed.serde.multi import (
+    LayoutDescGroup,
+    MemoryObjGroup,
+    MultiDeserializer,
+    MultiSerializer,
+    single_to_multi_deserializer,
+    single_to_multi_serializer,
+    validate_group_size,
+)
+
+# =============================================================================
+# Test scaffolding: a minimal MemoryObj stand-in mirroring test_fp8.py.
+# =============================================================================
+
+
+@dataclass
+class _FakeMemoryObj:
+    """Minimal stand-in exposing the ``.tensor`` attribute used by serdes.
+
+    Mirrors the ``_FakeMemoryObj`` in ``test_fp8.py`` so the multi-serde
+    tests stay GPU-free and L1Manager-free.
+    """
+
+    tensor: torch.Tensor
+
+
+def _byte_buffer(num_bytes: int) -> _FakeMemoryObj:
+    return _FakeMemoryObj(tensor=torch.zeros(num_bytes, dtype=torch.uint8))
+
+
+def _bf16_tensor_obj(*shape: int, seed: int = 0) -> _FakeMemoryObj:
+    g = torch.Generator().manual_seed(seed)
+    t = torch.randn(*shape, dtype=torch.bfloat16, generator=g).contiguous()
+    return _FakeMemoryObj(tensor=t)
+
+
+# =============================================================================
+# Toy reference multi-serde used to validate the API contract.
+#
+# Wire format (group of fixed length N):
+#   header: N bytes of present-mask (0 or 1 per slot)
+#         + N * uint32 little-endian payload-length (0 when absent)
+#   body:   concatenation of the present slots' raw tensor bytes,
+#           in slot order. Absent slots contribute zero bytes.
+#
+# Header byte size = N + 4*N = 5*N. Payload size is the sum of present
+# slots' tensor byte sizes. Total = 5*N + sum(present payloads).
+# =============================================================================
+
+
+_MASK_FMT = struct.Struct("<B")  # one byte per present-mask entry
+_LEN_FMT = struct.Struct("<I")  # uint32 little-endian per length
+
+
+def _header_size(group_size: int) -> int:
+    return group_size * (_MASK_FMT.size + _LEN_FMT.size)
+
+
+def _tensor_bytes(t: torch.Tensor) -> bytes:
+    # Reinterpret as uint8 to avoid Python bytes() per-byte iteration on
+    # storage. Mirrors the trick used elsewhere in the tree but kept
+    # local so this test file does not depend on production helpers.
+    return t.contiguous().view(torch.uint8).numpy().tobytes()
+
+
+class ConcatMultiSerializer(MultiSerializer):
+    """Toy multi-serializer that concatenates present slots verbatim."""
+
+    def __init__(self, group_size: int) -> None:
+        if group_size <= 0:
+            raise ValueError(f"group_size must be positive, got {group_size}")
+        self._group_size = group_size
+
+    @property
+    def group_size(self) -> int:
+        return self._group_size
+
+    def serialize(self, src: MemoryObjGroup, dst) -> int:
+        validate_group_size(src, self._group_size, role="src")
+        # Build header and payload separately so we can write into dst
+        # in two contiguous moves.
+        masks = bytearray()
+        lens = bytearray()
+        payload = bytearray()
+        for slot in src:
+            if slot is None:
+                masks += _MASK_FMT.pack(0)
+                lens += _LEN_FMT.pack(0)
+                continue
+            if slot.tensor is None:
+                raise ValueError(
+                    "ConcatMultiSerializer: a non-None group slot must "
+                    "have a tensor attribute set"
+                )
+            blob = _tensor_bytes(slot.tensor)
+            masks += _MASK_FMT.pack(1)
+            lens += _LEN_FMT.pack(len(blob))
+            payload += blob
+        header = bytes(masks) + bytes(lens)
+        total = len(header) + len(payload)
+
+        if dst.tensor is None:
+            raise ValueError("ConcatMultiSerializer: dst.tensor is None")
+        if dst.tensor.numel() < total:
+            raise ValueError(
+                f"ConcatMultiSerializer: dst capacity {dst.tensor.numel()} "
+                f"is below required {total}"
+            )
+
+        dst_view = dst.tensor.view(torch.uint8)
+        dst_view[: len(header)].copy_(
+            torch.frombuffer(bytearray(header), dtype=torch.uint8)
+        )
+        if payload:
+            dst_view[len(header) : total].copy_(
+                torch.frombuffer(bytearray(payload), dtype=torch.uint8)
+            )
+        return total
+
+    def estimate_serialized_size(
+        self,
+        layout_descs: LayoutDescGroup,
+    ) -> int:
+        validate_group_size(layout_descs, self._group_size, role="layout")
+        total = _header_size(self._group_size)
+        for desc in layout_descs:
+            if desc is None:
+                continue
+            for shape, dtype in zip(desc.shapes, desc.dtypes, strict=True):
+                numel = 1
+                for dim in shape:
+                    numel *= int(dim)
+                total += numel * dtype.itemsize
+        return total
+
+
+class ConcatMultiDeserializer(MultiDeserializer):
+    """Inverse of :class:`ConcatMultiSerializer`."""
+
+    def __init__(self, group_size: int) -> None:
+        if group_size <= 0:
+            raise ValueError(f"group_size must be positive, got {group_size}")
+        self._group_size = group_size
+
+    @property
+    def group_size(self) -> int:
+        return self._group_size
+
+    def deserialize(self, src, dst: MemoryObjGroup) -> None:
+        validate_group_size(dst, self._group_size, role="dst")
+        if src.tensor is None:
+            raise ValueError("ConcatMultiDeserializer: src.tensor is None")
+
+        src_view = src.tensor.view(torch.uint8)
+        n = self._group_size
+        present = [bool(src_view[i].item()) for i in range(n)]
+        lens_off = n
+        lens = [
+            int(
+                _LEN_FMT.unpack_from(
+                    src_view[
+                        lens_off + i * _LEN_FMT.size : lens_off
+                        + (i + 1) * _LEN_FMT.size
+                    ]
+                    .numpy()
+                    .tobytes()
+                )[0]
+            )
+            for i in range(n)
+        ]
+        cursor = _header_size(n)
+        for i, slot in enumerate(dst):
+            this_len = lens[i]
+            if slot is None:
+                cursor += this_len
+                continue
+            if not present[i]:
+                # Caller asked for a slot the producer did not write.
+                # Leave dst untouched; this mirrors the wrapper-side
+                # handling for "absent on serialize" cases.
+                continue
+            if slot.tensor is None:
+                raise ValueError(
+                    "ConcatMultiDeserializer: a non-None dst slot must "
+                    "have a tensor attribute set"
+                )
+            payload = src_view[cursor : cursor + this_len]
+            slot_view = slot.tensor.view(torch.uint8).flatten()
+            if slot_view.numel() < this_len:
+                raise ValueError(
+                    f"ConcatMultiDeserializer: dst slot {i} capacity "
+                    f"{slot_view.numel()} below payload {this_len}"
+                )
+            slot_view[:this_len].copy_(payload)
+            cursor += this_len
+
+
+# =============================================================================
+# group_size invariants
+# =============================================================================
+
+
+def test_group_size_property_is_fixed() -> None:
+    s = ConcatMultiSerializer(group_size=2)
+    d = ConcatMultiDeserializer(group_size=2)
+    assert s.group_size == 2
+    assert d.group_size == 2
+
+
+def test_group_size_must_be_positive() -> None:
+    with pytest.raises(ValueError):
+        ConcatMultiSerializer(group_size=0)
+    with pytest.raises(ValueError):
+        ConcatMultiDeserializer(group_size=-1)
+
+
+def test_validate_group_size_rejects_mismatch() -> None:
+    with pytest.raises(ValueError, match="src"):
+        validate_group_size((None,), expected=2, role="src")
+    with pytest.raises(ValueError, match="dst"):
+        validate_group_size((None, None, None), expected=2, role="dst")
+
+
+# =============================================================================
+# Round-trip with all slots present
+# =============================================================================
+
+
+def test_two_slot_roundtrip_all_present() -> None:
+    s = ConcatMultiSerializer(group_size=2)
+    d = ConcatMultiDeserializer(group_size=2)
+
+    k = _bf16_tensor_obj(2, 4, 8, seed=1)
+    v = _bf16_tensor_obj(2, 4, 8, seed=2)
+    src: MemoryObjGroup = cast(MemoryObjGroup, (k, v))
+
+    layout = (
+        MemoryLayoutDesc(shapes=[k.tensor.shape], dtypes=[k.tensor.dtype]),
+        MemoryLayoutDesc(shapes=[v.tensor.shape], dtypes=[v.tensor.dtype]),
+    )
+    capacity = s.estimate_serialized_size(layout)
+    buf = _byte_buffer(capacity)
+    n = s.serialize(src, buf)
+    assert n <= capacity
+
+    k_out = _FakeMemoryObj(tensor=torch.zeros_like(k.tensor))
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v.tensor))
+    d.deserialize(buf, (k_out, v_out))  # type: ignore[arg-type]
+
+    assert torch.equal(k_out.tensor, k.tensor)
+    assert torch.equal(v_out.tensor, v.tensor)
+
+
+# =============================================================================
+# None on serialize input: absent K slot
+# =============================================================================
+
+
+def test_serialize_with_none_slot_skips_payload() -> None:
+    s = ConcatMultiSerializer(group_size=2)
+    d = ConcatMultiDeserializer(group_size=2)
+
+    v = _bf16_tensor_obj(2, 4, 8, seed=3)
+    src: MemoryObjGroup = cast(MemoryObjGroup, (None, v))
+
+    layout: LayoutDescGroup = (
+        None,
+        MemoryLayoutDesc(shapes=[v.tensor.shape], dtypes=[v.tensor.dtype]),
+    )
+    capacity = s.estimate_serialized_size(layout)
+    buf = _byte_buffer(capacity)
+    n = s.serialize(src, buf)
+
+    # Capacity must accommodate the full payload exactly when absences
+    # are accounted for; the toy header is 5*group_size so the absent
+    # K slot only saves the K payload, not the header bookkeeping.
+    expected = 2 * 5 + v.tensor.numel() * v.tensor.dtype.itemsize
+    assert n == expected
+
+    # Round-trip into matching dst group: K slot left None to mirror.
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v.tensor))
+    d.deserialize(buf, (None, v_out))  # type: ignore[arg-type]
+
+    assert torch.equal(v_out.tensor, v.tensor)
+
+
+# =============================================================================
+# None on deserialize output: skip K materialization on read
+# =============================================================================
+
+
+def test_deserialize_with_none_slot_leaves_caller_buffer_untouched() -> None:
+    s = ConcatMultiSerializer(group_size=2)
+    d = ConcatMultiDeserializer(group_size=2)
+
+    k = _bf16_tensor_obj(1, 2, 4, seed=4)
+    v = _bf16_tensor_obj(1, 2, 4, seed=5)
+    layout = (
+        MemoryLayoutDesc(shapes=[k.tensor.shape], dtypes=[k.tensor.dtype]),
+        MemoryLayoutDesc(shapes=[v.tensor.shape], dtypes=[v.tensor.dtype]),
+    )
+    capacity = s.estimate_serialized_size(layout)
+    buf = _byte_buffer(capacity)
+    s.serialize((k, v), buf)  # type: ignore[arg-type]
+
+    # Deserialize, but skip the K slot.
+    sentinel = torch.full_like(k.tensor, fill_value=42.0)
+    k_out_unused = _FakeMemoryObj(tensor=sentinel.clone())
+    v_out = _FakeMemoryObj(tensor=torch.zeros_like(v.tensor))
+    d.deserialize(buf, (None, v_out))  # type: ignore[arg-type]
+
+    # k_out_unused must still equal the sentinel: deserialize did not
+    # touch a None dst slot.
+    assert torch.equal(k_out_unused.tensor, sentinel)
+    assert torch.equal(v_out.tensor, v.tensor)
+
+
+# =============================================================================
+# Single-tensor adapter: equivalent bytes vs the underlying serde
+# =============================================================================
+
+
+class _IdentitySerializer(Serializer):
+    """Trivial single-tensor serializer copying tensor bytes verbatim."""
+
+    def serialize(self, src, dst) -> int:
+        if src.tensor is None or dst.tensor is None:
+            raise ValueError("identity serde requires tensors on both sides")
+        blob = _tensor_bytes(src.tensor)
+        dst_view = dst.tensor.view(torch.uint8)
+        if dst_view.numel() < len(blob):
+            raise ValueError("identity serde: dst capacity too small")
+        dst_view[: len(blob)].copy_(
+            torch.frombuffer(bytearray(blob), dtype=torch.uint8)
+        )
+        return len(blob)
+
+    def estimate_serialized_size(self, layout_desc: MemoryLayoutDesc) -> int:
+        total = 0
+        for shape, dtype in zip(layout_desc.shapes, layout_desc.dtypes, strict=True):
+            numel = 1
+            for dim in shape:
+                numel *= int(dim)
+            total += numel * dtype.itemsize
+        return total
+
+
+class _IdentityDeserializer(Deserializer):
+    """Inverse of :class:`_IdentitySerializer`."""
+
+    def deserialize(self, src, dst) -> None:
+        if src.tensor is None or dst.tensor is None:
+            raise ValueError("identity serde requires tensors on both sides")
+        n = dst.tensor.numel() * dst.tensor.dtype.itemsize
+        src_view = src.tensor.view(torch.uint8)
+        dst_view = dst.tensor.view(torch.uint8).flatten()
+        dst_view[:n].copy_(src_view[:n])
+
+
+def test_single_to_multi_serializer_round_trip_equivalence() -> None:
+    """A length-1 group MUST produce the same bytes as direct invocation."""
+    inner_s = _IdentitySerializer()
+    inner_d = _IdentityDeserializer()
+    multi_s = single_to_multi_serializer(inner_s)
+    multi_d = single_to_multi_deserializer(inner_d)
+    assert multi_s.group_size == 1
+    assert multi_d.group_size == 1
+
+    src = _bf16_tensor_obj(2, 4, 8, seed=6)
+    layout = MemoryLayoutDesc(shapes=[src.tensor.shape], dtypes=[src.tensor.dtype])
+
+    direct_buf = _byte_buffer(inner_s.estimate_serialized_size(layout))
+    direct_n = inner_s.serialize(src, direct_buf)
+
+    multi_buf = _byte_buffer(multi_s.estimate_serialized_size((layout,)))
+    multi_n = multi_s.serialize((src,), multi_buf)  # type: ignore[arg-type]
+
+    assert direct_n == multi_n
+    assert torch.equal(direct_buf.tensor, multi_buf.tensor)
+
+    direct_out = _FakeMemoryObj(tensor=torch.zeros_like(src.tensor))
+    inner_d.deserialize(direct_buf, direct_out)
+
+    multi_out = _FakeMemoryObj(tensor=torch.zeros_like(src.tensor))
+    multi_d.deserialize(multi_buf, (multi_out,))  # type: ignore[arg-type]
+
+    assert torch.equal(direct_out.tensor, multi_out.tensor)
+
+
+def test_single_to_multi_serializer_rejects_non_unit_group() -> None:
+    multi_s = single_to_multi_serializer(_IdentitySerializer())
+    src_a = _bf16_tensor_obj(2, 2, seed=7)
+    src_b = _bf16_tensor_obj(2, 2, seed=8)
+    buf = _byte_buffer(64)
+    with pytest.raises(ValueError, match="size 1"):
+        multi_s.serialize((src_a, src_b), buf)  # type: ignore[arg-type]
+
+
+def test_single_to_multi_serializer_rejects_none_slot() -> None:
+    multi_s = single_to_multi_serializer(_IdentitySerializer())
+    buf = _byte_buffer(64)
+    with pytest.raises(ValueError, match="None src"):
+        multi_s.serialize((None,), buf)  # type: ignore[arg-type]
+
+
+def test_single_to_multi_deserializer_treats_none_slot_as_skip() -> None:
+    """A length-1 group with None dst is a deliberate no-op, not an error."""
+    multi_d = single_to_multi_deserializer(_IdentityDeserializer())
+    src = _byte_buffer(8)
+    # Deliberately skip the only output: must not raise.
+    multi_d.deserialize(src, (None,))  # type: ignore[arg-type]
diff --git a/tests/v1/distributed/serde/test_serde_e2e.py b/tests/v1/distributed/serde/test_serde_e2e.py
new file mode 100644
index 0000000..2f2c0a6
--- /dev/null
+++ b/tests/v1/distributed/serde/test_serde_e2e.py
@@ -0,0 +1,560 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+End-to-end tests for the serde integration through StorageManager.
+
+Drives the full L1 -> L2 store (with serialize) and L2 -> L1 prefetch
+(with deserialize) paths using a real L1Manager + MockL2Adapter +
+AsyncSerdeProcessor(fp8). Tests exercise the public StorageManager API
+only (no private-member access), per AGENTS.md.
+
+Coverage:
+- Store + prefetch round-trip through fp8 serde
+- Memory accounting (no leaks after full cycle)
+- Partial prefix trimming with serde
+- Mixed adapters (one with serde, one without)
+- Serde disabled (None) preserves existing behavior exactly
+- Serde failure propagation
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import L2AdaptersConfig
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import MockL2AdapterConfig
+from lmcache.v1.distributed.serde import SerdeConfig
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def should_use_lazy_alloc() -> bool:
+    """Determine if lazy allocation should be used based on CUDA availability."""
+    return torch.cuda.is_available()
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_layout() -> MemoryLayoutDesc:
+    """Create a small MemoryLayoutDesc for testing (bf16, ~200KB/chunk)."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+def wait_for_condition(
+    predicate,
+    timeout: float = 10.0,
+    poll_interval: float = 0.05,
+) -> bool:
+    """Poll until a predicate returns True or timeout."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def wait_for_prefetch_status(
+    sm: StorageManager,
+    handle,
+    timeout: float = 10.0,
+    poll_interval: float = 0.05,
+) -> int | None:
+    """Poll query_prefetch_status until it returns a non-None value."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = sm.query_prefetch_status(handle)
+        if result is not None:
+            return result.count_leading_ones()
+        time.sleep(poll_interval)
+    return None
+
+
+def make_mock_adapter_config(
+    *,
+    serde_type: str | None = "fp8",
+) -> MockL2AdapterConfig:
+    """Create a MockL2AdapterConfig, optionally with serde."""
+    cfg = MockL2AdapterConfig(
+        max_size_gb=0.1,
+        mock_bandwidth_gb=10.0,
+    )
+    if serde_type is not None:
+        cfg.serde_config = SerdeConfig(type=serde_type)
+    return cfg
+
+
+def make_storage_manager_config(
+    adapter_configs: list[MockL2AdapterConfig],
+    l1_size_mb: int = 256,
+) -> StorageManagerConfig:
+    """Build a StorageManagerConfig with the given L2 adapter configs."""
+    return StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=l1_size_mb * 1024 * 1024,
+                use_lazy=should_use_lazy_alloc(),
+                init_size_in_bytes=min(l1_size_mb, 64) * 1024 * 1024,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(adapters=list(adapter_configs)),
+    )
+
+
+def get_l2_stored_object_count(sm: StorageManager) -> int:
+    """Return the total stored object count across all L2 adapters."""
+    return sum(
+        adapter["stored_object_count"] for adapter in sm.report_status()["l2_adapters"]
+    )
+
+
+def write_and_wait_for_l2(
+    sm: StorageManager,
+    keys: list[ObjectKey],
+    layout: MemoryLayoutDesc,
+    timeout: float = 10.0,
+) -> None:
+    """Write keys to L1 via StorageManager and wait for L2 store.
+
+    Fills each chunk with deterministic data so round-trip can be verified.
+    """
+    stored_before = get_l2_stored_object_count(sm)
+
+    ret = sm.reserve_write(keys, layout, mode="new")
+    assert len(ret) == len(keys), f"reserve_write: {len(ret)}/{len(keys)} succeeded"
+
+    # Fill with deterministic data per key
+    for i, key in enumerate(keys):
+        obj = ret[key]
+        tensor = obj.tensor
+        if tensor is not None:
+            tensor.fill_(float(i + 1))
+
+    sm.finish_write(list(ret.keys()))
+
+    # Wait for StoreController to flush to L2. Polling the controller's queue
+    # counters alone is racy: the background loop pops the pending keys
+    # (pending_keys_count -> 0) before it submits the store tasks
+    # (in_flight_task_count is still 0 in between), so a poll landing in that
+    # window declares the store complete before anything reached L2. Anchor
+    # the wait on the adapters' stored object counts, then use the queue
+    # counters only to confirm the controller has settled.
+    def flushed_to_l2() -> bool:
+        status = sm.report_status()
+        stored_total = sum(
+            adapter["stored_object_count"] for adapter in status["l2_adapters"]
+        )
+        store_controller = status["store_controller"]
+        return (
+            stored_total >= stored_before + len(keys)
+            and store_controller["in_flight_task_count"] == 0
+            and store_controller["pending_keys_count"] == 0
+        )
+
+    ok = wait_for_condition(flushed_to_l2, timeout=timeout)
+    assert ok, "Store to L2 did not complete within timeout"
+
+
+def get_l1_memory_used(sm: StorageManager) -> int:
+    """Return current L1 memory usage in bytes via public report_status."""
+    return sm.report_status()["l1_manager"]["memory_used_bytes"]
+
+
+def get_l1_object_count(sm: StorageManager) -> int:
+    """Return current L1 object count via public report_status."""
+    return sm.report_status()["l1_manager"]["total_object_count"]
+
+
+def clear_and_wait_drained(sm: StorageManager, timeout: float = 10.0) -> None:
+    """Clear L1 and poll until every object is evicted.
+
+    After an L2 store the StoreController holds read locks on the stored objects
+    for a short window, and ``StorageManager.clear`` keeps locked objects intact.
+    A single clear right after the store therefore races the lock release and can
+    leave objects behind. Retry clear() until the locks drop and L1 drains rather
+    than relying on a fixed sleep.
+
+    Raises:
+        AssertionError: If L1 still holds objects after ``timeout`` seconds.
+    """
+
+    def drained() -> bool:
+        sm.clear()
+        return get_l1_object_count(sm) == 0
+
+    if not wait_for_condition(drained, timeout=timeout):
+        raise AssertionError(
+            f"L1 did not drain after clear: {get_l1_object_count(sm)} objects remain"
+        )
+
+
+# =============================================================================
+# Tests: Full round-trip through serde
+# =============================================================================
+
+
+class TestSerdeRoundTrip:
+    """End-to-end store + prefetch through fp8 serde."""
+
+    def test_store_and_prefetch_with_serde(self) -> None:
+        """Write → L2 store (serialize) → clear L1 → prefetch (deserialize).
+
+        Verifies all keys are recovered and L1 memory returns to clean state
+        after all read locks are released.
+        """
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type="fp8")])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(5)]
+
+        write_and_wait_for_l2(sm, keys, layout)
+
+        clear_and_wait_drained(sm)
+        assert get_l1_object_count(sm) == 0
+
+        # Prefetch from L2
+        handle = sm.submit_prefetch_task(keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+        assert hits == 5, f"Expected 5 L2 hits, got {hits}"
+
+        # Read the data back
+        with sm.read_prefetched_results(keys) as objs:
+            assert objs is not None
+            assert len(objs) == 5
+
+        sm.finish_read_prefetched(keys)
+        sm.close()
+
+    def test_no_memory_leak_after_full_cycle(self) -> None:
+        """After write → store → clear → prefetch → finish_read, L1 is clean."""
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type="fp8")])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+
+        write_and_wait_for_l2(sm, keys, layout)
+        clear_and_wait_drained(sm)
+
+        # Prefetch
+        handle = sm.submit_prefetch_task(keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+        assert hits == 3
+
+        # Release read locks
+        sm.finish_read_prefetched(keys)
+
+        # L1 should have objects (temporary prefetch results auto-delete on
+        # finish_read), so memory should be back to 0.
+        ok = wait_for_condition(
+            lambda: get_l1_memory_used(sm) == 0,
+            timeout=5.0,
+        )
+        assert ok, (
+            f"L1 memory leak: {get_l1_memory_used(sm)} bytes still used "
+            f"after releasing all read locks"
+        )
+
+        sm.close()
+
+
+# =============================================================================
+# Tests: Serde disabled (None) preserves existing behavior
+# =============================================================================
+
+
+class TestSerdeDisabled:
+    """Verify that serde_config=None is equivalent to no-serde code path."""
+
+    def test_store_and_prefetch_without_serde(self) -> None:
+        """Same flow as the serde test, but without serde — must still work."""
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type=None)])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(5)]
+
+        write_and_wait_for_l2(sm, keys, layout)
+        clear_and_wait_drained(sm)
+
+        handle = sm.submit_prefetch_task(keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+        assert hits == 5
+
+        with sm.read_prefetched_results(keys) as objs:
+            assert objs is not None
+            assert len(objs) == 5
+
+        sm.finish_read_prefetched(keys)
+        sm.close()
+
+    def test_no_memory_leak_without_serde(self) -> None:
+        """No-serde path should also leave L1 clean after a full cycle."""
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type=None)])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+
+        write_and_wait_for_l2(sm, keys, layout)
+        clear_and_wait_drained(sm)
+
+        handle = sm.submit_prefetch_task(keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+        assert hits == 3
+        sm.finish_read_prefetched(keys)
+
+        ok = wait_for_condition(
+            lambda: get_l1_memory_used(sm) == 0,
+            timeout=5.0,
+        )
+        assert ok, f"L1 memory leak: {get_l1_memory_used(sm)} bytes still used"
+        sm.close()
+
+
+# =============================================================================
+# Tests: Prefix trimming with serde
+# =============================================================================
+
+
+class TestSerdePartialPrefix:
+    """Prefetch with serde when L2 has gaps in the key sequence."""
+
+    def test_partial_prefix_with_serde(self) -> None:
+        """L2 has keys {0,1,3,4} but not 2 → only prefix {0,1} returned."""
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type="fp8")])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+
+        # Write only keys 0, 1, 3, 4 (skip 2)
+        keys_to_write = [make_object_key(i) for i in [0, 1, 3, 4]]
+        write_and_wait_for_l2(sm, keys_to_write, layout)
+        clear_and_wait_drained(sm)
+
+        # Request all 5 keys — prefix should be 2 (gap at index 2)
+        all_keys = [make_object_key(i) for i in range(5)]
+        handle = sm.submit_prefetch_task(all_keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+
+        assert hits is not None
+        assert hits == 2, f"Expected prefix of 2, got {hits}"
+
+        sm.finish_read_prefetched(all_keys[:hits])
+        sm.close()
+
+
+# =============================================================================
+# Tests: Memory leak on repeated cycles
+# =============================================================================
+
+
+class TestSerdeMemoryStress:
+    """Run multiple store-clear-prefetch cycles to catch temp buffer leaks."""
+
+    def test_repeated_cycles_no_leak(self) -> None:
+        """5 cycles of write → L2 → clear → prefetch → finish_read.
+
+        After each cycle L1 should return to 0 bytes used. A temp buffer
+        leak would accumulate across cycles.
+        """
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type="fp8")])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+
+        for cycle in range(5):
+            keys = [make_object_key(cycle * 10 + i) for i in range(3)]
+            write_and_wait_for_l2(sm, keys, layout)
+            clear_and_wait_drained(sm)
+
+            handle = sm.submit_prefetch_task(keys, layout)
+            hits = wait_for_prefetch_status(sm, handle)
+            assert hits == 3, f"Cycle {cycle}: expected 3 hits, got {hits}"
+            sm.finish_read_prefetched(keys)
+
+            ok = wait_for_condition(
+                lambda: get_l1_memory_used(sm) == 0,
+                timeout=5.0,
+            )
+            assert ok, (
+                f"Cycle {cycle}: L1 memory leak — {get_l1_memory_used(sm)} bytes used"
+            )
+
+        sm.close()
+
+
+# =============================================================================
+# Tests: Multiple keys with nothing in L2
+# =============================================================================
+
+
+class TestSerdeNoHits:
+    """Prefetch with serde when L2 is empty — 0 hits, no crash."""
+
+    def test_prefetch_no_hits_with_serde(self) -> None:
+        """Empty L2 → prefetch returns 0 hits, no temp buffer leak."""
+        cfg = make_storage_manager_config([make_mock_adapter_config(serde_type="fp8")])
+        sm = StorageManager(cfg)
+        layout = make_layout()
+
+        keys = [make_object_key(i) for i in range(3)]
+        handle = sm.submit_prefetch_task(keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+
+        assert hits is not None
+        assert hits == 0
+
+        # No objects in L1 → memory should be 0
+        ok = wait_for_condition(
+            lambda: get_l1_memory_used(sm) == 0,
+            timeout=5.0,
+        )
+        assert ok, (
+            f"L1 memory leak after 0-hit prefetch: {get_l1_memory_used(sm)} bytes"
+        )
+        sm.close()
+
+
+# =============================================================================
+# Tests: Buffer sizing — no out-of-bound memory access
+# =============================================================================
+
+
+class TestSerdeBufferBounds:
+    """Verify that the temp buffer sizing chain does not cause OOB access.
+
+    The critical path:
+      estimate_serialized_size(layout) -> buffer size (includes 1.5x margin)
+      temp_buffer = estimate bytes as uint8
+      serialize: writes num_elements bytes into temp (must fit)
+      deserialize: reads num_elements bytes from temp (must fit)
+
+    OOB would manifest as a crash (segfault / CUDA illegal access),
+    wrong data, or a memory leak from corrupted L1 accounting.
+    """
+
+    def _run_roundtrip(
+        self,
+        layout: MemoryLayoutDesc,
+        num_keys: int = 3,
+        l1_size_mb: int = 512,
+    ) -> None:
+        """Helper: full store -> clear -> prefetch -> verify -> cleanup.
+
+        Crashes here indicate OOB in serialize or deserialize.
+        """
+        cfg = make_storage_manager_config(
+            [make_mock_adapter_config(serde_type="fp8")],
+            l1_size_mb=l1_size_mb,
+        )
+        sm = StorageManager(cfg)
+        keys = [make_object_key(i) for i in range(num_keys)]
+
+        write_and_wait_for_l2(sm, keys, layout)
+        clear_and_wait_drained(sm)
+        assert get_l1_object_count(sm) == 0
+
+        handle = sm.submit_prefetch_task(keys, layout)
+        hits = wait_for_prefetch_status(sm, handle)
+        assert hits == num_keys, f"Expected {num_keys} hits, got {hits}"
+
+        with sm.read_prefetched_results(keys) as objs:
+            assert objs is not None
+            assert len(objs) == num_keys
+
+        sm.finish_read_prefetched(keys)
+
+        # Verify no memory leak (temp buffers fully cleaned up)
+        ok = wait_for_condition(
+            lambda: get_l1_memory_used(sm) == 0,
+            timeout=5.0,
+        )
+        assert ok, f"L1 memory leak: {get_l1_memory_used(sm)} bytes after full cycle"
+        sm.close()
+
+    def test_bfloat16_layout(self) -> None:
+        """bf16: 2 bytes/elem KV -> 1 byte/elem fp8. Buffer = 1.5 * numel."""
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([100, 2, 512])],
+            dtypes=[torch.bfloat16],
+        )
+        self._run_roundtrip(layout)
+
+    def test_float16_layout(self) -> None:
+        """fp16: 2 bytes/elem KV -> 1 byte/elem fp8. Same ratio as bf16."""
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([100, 2, 512])],
+            dtypes=[torch.float16],
+        )
+        self._run_roundtrip(layout)
+
+    def test_float32_layout(self) -> None:
+        """fp32: 4 bytes/elem KV -> 1 byte/elem fp8. 4x compression.
+
+        The temp buffer (1.5 * numel bytes) is much smaller than the
+        real KV buffer (4 * numel bytes). This is the highest compression
+        ratio and the most likely to trigger sizing bugs.
+        """
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([50, 2, 256])],
+            dtypes=[torch.float32],
+        )
+        self._run_roundtrip(layout)
+
+    def test_large_tensor(self) -> None:
+        """Large tensor (~4M elements, ~8MB bf16). Stress the buffer boundary."""
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([256, 4, 2, 2048])],
+            dtypes=[torch.bfloat16],
+        )
+        self._run_roundtrip(layout, num_keys=2, l1_size_mb=512)
+
+    def test_small_tensor(self) -> None:
+        """Tiny tensor (single element). Edge case for buffer sizing."""
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([1])],
+            dtypes=[torch.bfloat16],
+        )
+        self._run_roundtrip(layout)
+
+    def test_odd_element_count(self) -> None:
+        """Non-power-of-2 element count. Tests alignment edge cases.
+
+        numel = 7 * 13 * 3 = 273, not divisible by any common alignment.
+        """
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([7, 13, 3])],
+            dtypes=[torch.bfloat16],
+        )
+        self._run_roundtrip(layout)
+
+    # NOTE: Multi-group layouts (multiple shapes/dtypes) are not tested here
+    # because the fp8 serde accesses MemoryObj.tensor which only works for
+    # single-group layouts. Multi-group would require per-group
+    # serialize/deserialize via MemoryObj.get_tensor(index).
diff --git a/tests/v1/distributed/serde/test_serde_fs_e2e.py b/tests/v1/distributed/serde/test_serde_fs_e2e.py
new file mode 100644
index 0000000..a2ed305
--- /dev/null
+++ b/tests/v1/distributed/serde/test_serde_fs_e2e.py
@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+End-to-end test for fp8 serde with a real filesystem L2 adapter.
+
+Unlike test_serde_e2e.py (which uses MockL2Adapter), this test exercises
+the full disk I/O path: L1 write -> fp8 serialize -> disk store -> L1
+clear -> disk load -> fp8 deserialize -> L1 read. Verifies the data
+round-trips within fp8 quantization error and that no temp buffers leak.
+"""
+
+# Standard
+import os
+import shutil
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import L2AdaptersConfig
+from lmcache.v1.distributed.l2_adapters.fs_l2_adapter import FSL2AdapterConfig
+from lmcache.v1.distributed.serde import SerdeConfig
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def _make_key(chunk_hash: bytes) -> ObjectKey:
+    """Create an ObjectKey with the given raw hash bytes."""
+    return ObjectKey(
+        chunk_hash=chunk_hash,
+        model_name="test-model",
+        kv_rank=0,
+    )
+
+
+def wait_for_condition(
+    predicate,
+    timeout: float = 10.0,
+    poll_interval: float = 0.1,
+) -> bool:
+    """Poll until predicate returns True or timeout."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def wait_for_prefetch_status(
+    sm: StorageManager,
+    handle,
+    timeout: float = 15.0,
+    poll_interval: float = 0.1,
+) -> int | None:
+    """Poll query_prefetch_status until non-None or timeout."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = sm.query_prefetch_status(handle)
+        if result is not None:
+            return result.count_leading_ones()
+        time.sleep(poll_interval)
+    return None
+
+
+# =============================================================================
+# Test
+# =============================================================================
+
+
+class TestFp8SerdeFsRoundTrip:
+    """Full disk-backed fp8 serde round-trip through StorageManager."""
+
+    def test_write_serialize_clear_prefetch_deserialize(self) -> None:
+        """Write KV → fp8 serialize → disk → clear L1 → prefetch → verify.
+
+        Checks:
+          - Serialized files appear on disk.
+          - Prefetch returns all keys from L2.
+          - Deserialized data correlates >0.95 with the original.
+          - L1 memory returns to 0 after all locks released.
+        """
+        disk_path = tempfile.mkdtemp(prefix="lmcache_serde_fs_test_")
+        try:
+            self._run(disk_path)
+        finally:
+            shutil.rmtree(disk_path, ignore_errors=True)
+
+    def _run(self, disk_path: str) -> None:
+        # ---- Config ----
+        fs_cfg = FSL2AdapterConfig(
+            base_path=disk_path,
+            relative_tmp_dir=None,
+            read_ahead_size=None,
+            use_odirect=False,
+        )
+        fs_cfg.serde_config = SerdeConfig(
+            type="fp8", kwargs={"fp8_dtype": "float8_e4m3fn"}
+        )
+
+        sm_cfg = StorageManagerConfig(
+            l1_manager_config=L1ManagerConfig(
+                memory_config=L1MemoryManagerConfig(
+                    size_in_bytes=4 << 30,
+                    use_lazy=True,
+                    init_size_in_bytes=1 << 30,
+                ),
+            ),
+            eviction_config=EvictionConfig(eviction_policy="LRU"),
+            l2_adapter_config=L2AdaptersConfig(adapters=[fs_cfg]),  # type: ignore[list-item]
+        )
+
+        sm = StorageManager(sm_cfg)
+
+        kv_shape = torch.Size([2, 4, 256, 128])
+        kv_dtype = torch.bfloat16
+        layout = MemoryLayoutDesc(shapes=[kv_shape], dtypes=[kv_dtype])
+
+        keys = [
+            _make_key(b"\x00" * 31 + b"\x01"),
+            _make_key(b"\x00" * 31 + b"\x02"),
+        ]
+        torch.manual_seed(0)
+        originals = [torch.randn(kv_shape, dtype=kv_dtype) for _ in keys]
+
+        # ---- Step 1: write to L1 ----
+        reserved = sm.reserve_write(keys, layout, mode="new")
+        assert len(reserved) == len(keys)
+        for k, orig in zip(keys, originals, strict=True):
+            mem_obj = reserved[k]
+            assert mem_obj.tensor is not None
+            mem_obj.tensor.view(kv_shape).view(kv_dtype).copy_(orig)
+        sm.finish_write(keys)
+
+        # ---- Step 2: wait for L2 store to disk ----
+        # The FS adapter writes one file per key (staged as "*.tmp" in the
+        # same directory), so wait for all final files rather than the
+        # first: the controller's queue counters can both read zero in the
+        # window between popping pending keys and submitting the store
+        # tasks, so they only confirm settling after the files prove the
+        # store actually happened.
+        def count_stored_files() -> int:
+            return sum(
+                1
+                for e in os.scandir(disk_path)
+                if e.is_file() and not e.name.endswith(".tmp")
+            )
+
+        ok = wait_for_condition(
+            lambda: count_stored_files() >= len(keys),
+            timeout=10.0,
+        )
+        assert ok, f"Expected {len(keys)} files under {disk_path}"
+
+        ok = wait_for_condition(
+            lambda: (
+                sm.report_status()["store_controller"]["in_flight_task_count"] == 0
+                and sm.report_status()["store_controller"]["pending_keys_count"] == 0
+            ),
+            timeout=10.0,
+        )
+        assert ok, "Store controller did not finish in time"
+
+        # ---- Step 3: clear L1 ----
+        sm.clear(force=True)
+        assert sm.report_status()["l1_manager"]["total_object_count"] == 0
+
+        # ---- Step 4: prefetch (disk load + fp8 deserialize) ----
+        handle = sm.submit_prefetch_task(keys, layout)
+        prefix_hits = wait_for_prefetch_status(sm, handle)
+        assert prefix_hits is not None, "Prefetch never completed"
+        assert prefix_hits == len(keys), (
+            f"Expected {len(keys)} prefix hits, got {prefix_hits}"
+        )
+
+        # ---- Step 5: verify fp8 round-trip ----
+        with sm.read_prefetched_results(keys) as mem_objs:
+            assert mem_objs is not None
+            assert len(mem_objs) == len(keys)
+            for orig, mem_obj in zip(originals, mem_objs, strict=True):
+                assert mem_obj.tensor is not None
+                got = mem_obj.tensor.view(kv_shape).view(kv_dtype)
+                corr = torch.corrcoef(
+                    torch.stack([got.float().flatten(), orig.float().flatten()])
+                )[0, 1].item()
+                assert corr > 0.95, f"fp8 round-trip correlation too low: {corr:.4f}"
+
+        sm.finish_read_prefetched(keys)
+
+        # ---- Step 6: verify no memory leak ----
+        ok = wait_for_condition(
+            lambda: sm.report_status()["l1_manager"]["memory_used_bytes"] == 0,
+            timeout=5.0,
+        )
+        assert ok, (
+            f"L1 memory leak: "
+            f"{sm.report_status()['l1_manager']['memory_used_bytes']} bytes"
+        )
+
+        sm.close()
diff --git a/tests/v1/distributed/serde/test_turboquant.py b/tests/v1/distributed/serde/test_turboquant.py
new file mode 100644
index 0000000..e860de9
--- /dev/null
+++ b/tests/v1/distributed/serde/test_turboquant.py
@@ -0,0 +1,623 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for TurboQuant serde skeleton.
+"""
+
+# Standard
+from pathlib import Path
+from typing import cast
+import shutil
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import L2AdaptersConfig
+from lmcache.v1.distributed.l2_adapters.fs_l2_adapter import FSL2AdapterConfig
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import MockL2AdapterConfig
+from lmcache.v1.distributed.serde import (
+    SerdeConfig,
+    create_serde_processor,
+    get_registered_serde_types,
+)
+from lmcache.v1.distributed.serde.turboquant import (
+    TurboQuantSerdeConfig,
+    TurboQuantSerializer,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.memory_management import MemoryObj
+
+
+def test_turboquant_registered() -> None:
+    assert "turboquant" in get_registered_serde_types()
+
+
+def test_create_turboquant_serde_processor() -> None:
+    processor = create_serde_processor(
+        SerdeConfig(
+            type="turboquant",
+            kwargs={
+                "preset": "turboquant_k8v4",
+                "head_dim": 128,
+                "block_size": 16,
+                "max_workers": 1,
+            },
+        )
+    )
+    processor.close()
+
+
+@pytest.mark.parametrize(
+    (
+        "preset",
+        "key_fp8",
+        "key_quant_bits",
+        "key_mse_bits",
+        "value_quant_bits",
+        "norm_correction",
+        "key_packed_size",
+        "value_packed_size",
+        "slot_size",
+        "slot_size_aligned",
+    ),
+    [
+        ("turboquant_k8v4", True, 8, 0, 4, False, 128, 68, 196, 196),
+        ("turboquant_4bit_nc", False, 4, 4, 4, True, 66, 68, 134, 134),
+        ("turboquant_k3v4_nc", False, 3, 3, 4, True, 50, 68, 118, 118),
+        ("turboquant_3bit_nc", False, 3, 3, 3, True, 50, 52, 102, 102),
+    ],
+)
+def test_turboquant_config_sizes_head_dim_128(
+    preset: str,
+    key_fp8: bool,
+    key_quant_bits: int,
+    key_mse_bits: int,
+    value_quant_bits: int,
+    norm_correction: bool,
+    key_packed_size: int,
+    value_packed_size: int,
+    slot_size: int,
+    slot_size_aligned: int,
+) -> None:
+    cfg = TurboQuantSerdeConfig(
+        preset=preset,
+        head_dim=128,
+        block_size=16,
+    )
+
+    assert cfg.key_fp8 is key_fp8
+    assert cfg.key_quant_bits == key_quant_bits
+    assert cfg.key_mse_bits == key_mse_bits
+    assert cfg.value_quant_bits == value_quant_bits
+    assert cfg.norm_correction is norm_correction
+    assert cfg.key_packed_size == key_packed_size
+    assert cfg.value_packed_size == value_packed_size
+    assert cfg.slot_size == slot_size
+    assert cfg.slot_size_aligned == slot_size_aligned
+
+
+def test_turboquant_config_rejects_invalid_preset() -> None:
+    cfg = TurboQuantSerdeConfig(
+        preset="turboquant_invalid",
+        head_dim=128,
+        block_size=16,
+    )
+
+    with pytest.raises(ValueError, match="Unsupported TurboQuant preset"):
+        _ = cfg.key_quant_bits
+
+
+def test_estimate_serialized_size_k8v4() -> None:
+    cfg = TurboQuantSerdeConfig(
+        preset="turboquant_k8v4",
+        head_dim=128,
+        block_size=16,
+    )
+    serializer = TurboQuantSerializer(cfg)
+
+    # LMCache KV layout: [2, num_layers, num_tokens, hidden_dim]
+    # hidden_dim = num_heads * head_dim = 4 * 128 = 512
+    layout = MemoryLayoutDesc(
+        shapes=[torch.Size([2, 3, 20, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+    # num_layers = 3
+    # default skip_first_layers=2 and skip_last_layers=2 leaves no middle
+    # layers to compress, so all layers are stored as raw bfloat16 KV.
+    expected = 2 * 3 * 20 * 512 * torch.bfloat16.itemsize
+
+    assert serializer.estimate_serialized_size(layout) == expected
+
+
+def test_estimate_serialized_size_rejects_invalid_kv_size() -> None:
+    cfg = TurboQuantSerdeConfig(
+        preset="turboquant_k8v4",
+        head_dim=128,
+        block_size=16,
+    )
+    serializer = TurboQuantSerializer(cfg)
+
+    layout = MemoryLayoutDesc(
+        shapes=[torch.Size([1, 3, 20, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+    with pytest.raises(ValueError, match="kv_size=2"):
+        serializer.estimate_serialized_size(layout)
+
+
+def test_estimate_serialized_size_rejects_bad_head_dim() -> None:
+    cfg = TurboQuantSerdeConfig(
+        preset="turboquant_k8v4",
+        head_dim=128,
+        block_size=16,
+    )
+    serializer = TurboQuantSerializer(cfg)
+
+    layout = MemoryLayoutDesc(
+        shapes=[torch.Size([2, 3, 20, 500])],
+        dtypes=[torch.bfloat16],
+    )
+
+    with pytest.raises(ValueError, match="must be divisible"):
+        serializer.estimate_serialized_size(layout)
+
+
+# =============================================================================
+# GPU E2E test: StorageManager + SerdeL2AdapterWrapper + MockL2Adapter
+# =============================================================================
+
+
+def _make_turboquant_object_key(chunk_id: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="turboquant_test_model",
+        kv_rank=0,
+    )
+
+
+def _make_turboquant_layout() -> MemoryLayoutDesc:
+    # TurboQuant serde currently expects [2, num_layers, num_tokens, hidden_dim].
+    # hidden_dim = num_heads * head_dim = 4 * 128 = 512.
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([2, 2, 32, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+def _wait_for_condition(
+    predicate,
+    timeout: float = 20.0,
+    poll_interval: float = 0.05,
+) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def _wait_for_prefetch_status(
+    sm: StorageManager,
+    handle,
+    timeout: float = 20.0,
+    poll_interval: float = 0.05,
+) -> Bitmap | None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = sm.query_prefetch_status(handle)
+        if result is not None:
+            return result
+        time.sleep(poll_interval)
+    return None
+
+
+def _finish_read_prefetched_until_clean(
+    sm: StorageManager,
+    keys: list[ObjectKey],
+    timeout: float = 30.0,
+) -> None:
+    """Release prefetched temporary objects and wait for L1 cleanup.
+
+    StorageManager / serde wrapper paths may hold more than one read lock
+    on temporary prefetched objects. Release repeatedly until L1 is clean.
+    """
+    for _ in range(4):
+        sm.finish_read_prefetched(keys)
+        ok = _wait_for_condition(
+            lambda: (
+                sm.report_status()["l1_manager"]["memory_used_bytes"] == 0
+                and sm.report_status()["l1_manager"]["total_object_count"] == 0
+                and sm.report_status()["l1_manager"]["read_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["write_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["temporary_count"] == 0
+            ),
+            timeout=timeout,
+        )
+        if ok:
+            return
+
+    raise AssertionError(f"L1 memory not released: {sm.report_status()['l1_manager']}")
+
+
+def _make_turboquant_storage_manager(preset: str) -> StorageManager:
+    adapter_cfg = MockL2AdapterConfig(
+        max_size_gb=0.1,
+        mock_bandwidth_gb=10.0,
+    )
+    adapter_cfg.serde_config = SerdeConfig(
+        type="turboquant",
+        kwargs={
+            "preset": preset,
+            "head_dim": 128,
+            "block_size": 16,
+            "max_workers": 1,
+        },
+    )
+
+    cfg = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=256 * 1024 * 1024,
+                use_lazy=torch.cuda.is_available(),
+                init_size_in_bytes=64 * 1024 * 1024,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(adapters=[adapter_cfg]),
+    )
+    return StorageManager(cfg)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA is not available")
+@pytest.mark.parametrize(
+    ("preset", "corr_lower_bound"),
+    [
+        ("turboquant_k8v4", 0.95),
+        ("turboquant_4bit_nc", 0.90),
+        ("turboquant_k3v4_nc", 0.85),
+        ("turboquant_3bit_nc", 0.80),
+    ],
+)
+def test_turboquant_storage_manager_roundtrip(
+    preset: str,
+    corr_lower_bound: float,
+) -> None:
+    """Store/load through StorageManager with TurboQuant serde.
+
+    This verifies:
+    reserve_write -> finish_write -> StoreController
+    -> SerdeL2AdapterWrapper serialize -> MockL2Adapter store
+    -> clear L1 -> prefetch -> MockL2Adapter load
+    -> SerdeL2AdapterWrapper deserialize -> read_prefetched_results.
+    """
+    sm = _make_turboquant_storage_manager(preset)
+    layout = _make_turboquant_layout()
+    keys = [_make_turboquant_object_key(i) for i in range(3)]
+
+    try:
+        ret = sm.reserve_write(keys, layout, mode="new")
+        assert len(ret) == len(keys), f"reserve_write got {len(ret)} / {len(keys)}"
+
+        original_by_key = {}
+        for i, key in enumerate(keys):
+            obj = ret[key]
+            assert obj.tensor is not None
+
+            torch.manual_seed(1234 + i)
+            data = torch.randn(
+                obj.tensor.shape,
+                dtype=obj.tensor.dtype,
+                device=obj.tensor.device,
+            )
+            data = data + float(i)
+
+            obj.tensor.copy_(data)
+            original_by_key[key] = data.detach().clone()
+
+        sm.finish_write(list(ret.keys()))
+
+        # Wait until both the store controller and the serde wrapper cleanup
+        # have released temporary objects and locks.
+        ok = _wait_for_condition(
+            lambda: (
+                sm.report_status()["store_controller"]["in_flight_task_count"] == 0
+                and sm.report_status()["store_controller"]["pending_keys_count"] == 0
+                and sm.report_status()["l1_manager"]["write_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["read_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["temporary_count"] == 0
+            ),
+            timeout=120.0,
+        )
+        assert ok, "Store to L2 did not fully complete"
+
+        sm.clear()
+        ok = _wait_for_condition(
+            lambda: (
+                sm.report_status()["l1_manager"]["total_object_count"] == 0
+                and sm.report_status()["l1_manager"]["memory_used_bytes"] == 0
+                and sm.report_status()["l1_manager"]["read_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["write_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["temporary_count"] == 0
+            ),
+            timeout=120.0,
+        )
+        assert ok, f"L1 not cleared: {sm.report_status()['l1_manager']}"
+
+        handle = sm.submit_prefetch_task(keys, layout)
+        hit_bitmap = _wait_for_prefetch_status(sm, handle, timeout=120.0)
+        assert hit_bitmap is not None
+        hits = hit_bitmap.count_leading_ones()
+        assert hits == len(keys), f"Expected {len(keys)} hits, got {hits}"
+
+        with sm.read_prefetched_results(keys) as objs:
+            assert objs is not None
+            assert len(objs) == len(keys)
+
+            for key, obj in zip(keys, objs, strict=True):
+                assert obj.tensor is not None
+
+                recovered = obj.tensor
+                original = original_by_key[key]
+
+                orig_f = original.float().flatten()
+                rec_f = recovered.float().flatten()
+
+                corr = torch.corrcoef(torch.stack([orig_f, rec_f]))[0, 1].item()
+                mae = torch.mean(torch.abs(orig_f - rec_f)).item()
+                mse = torch.mean((orig_f - rec_f) ** 2).item()
+
+                assert corr > corr_lower_bound, (
+                    f"low corr for preset={preset}, key={key}: "
+                    f"corr={corr}, mae={mae}, mse={mse}"
+                )
+
+        _finish_read_prefetched_until_clean(sm, keys)
+    finally:
+        sm.close()
+
+
+# =============================================================================
+# GPU direct test: TurboQuantSerializer + TurboQuantDeserializer
+# =============================================================================
+
+
+class _FakeMemoryObj:
+    def __init__(self, tensor: torch.Tensor):
+        self.tensor = tensor
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA is not available")
+@pytest.mark.parametrize(
+    ("preset", "expected_ratio_lower_bound", "corr_lower_bound"),
+    [
+        ("turboquant_k8v4", 2.60, 0.95),
+        ("turboquant_4bit_nc", 3.75, 0.90),
+        ("turboquant_k3v4_nc", 4.20, 0.85),
+        ("turboquant_3bit_nc", 4.85, 0.80),
+    ],
+)
+def test_turboquant_direct_roundtrip_cuda(
+    preset: str,
+    expected_ratio_lower_bound: float,
+    corr_lower_bound: float,
+) -> None:
+    """Direct GPU round-trip through TurboQuant serializer/deserializer."""
+    # First Party
+    from lmcache.v1.distributed.serde.turboquant import TurboQuantDeserializer
+
+    device = torch.device("cuda:0")
+    dtype = torch.float16
+
+    # LMCache KV layout: [2, num_layers, num_tokens, hidden_dim]
+    num_layers = 4
+    num_tokens = 128
+    num_heads = 8
+    head_dim = 128
+    hidden_dim = num_heads * head_dim
+
+    cfg = TurboQuantSerdeConfig(
+        preset=preset,
+        head_dim=head_dim,
+        block_size=16,
+        skip_first_layers=0,
+        skip_last_layers=0,
+    )
+
+    torch.manual_seed(2026)
+    shape = torch.Size([2, num_layers, num_tokens, hidden_dim])
+    original = torch.randn(shape, dtype=dtype, device=device)
+
+    serializer = TurboQuantSerializer(cfg)
+    deserializer = TurboQuantDeserializer(cfg)
+
+    layout = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+    n_bytes = serializer.estimate_serialized_size(layout)
+
+    compressed = torch.empty(n_bytes, dtype=torch.uint8, device=device)
+    recovered = torch.empty_like(original)
+
+    written = serializer.serialize(
+        cast(MemoryObj, _FakeMemoryObj(original)),
+        cast(MemoryObj, _FakeMemoryObj(compressed)),
+    )
+    assert written == n_bytes
+
+    deserializer.deserialize(
+        cast(MemoryObj, _FakeMemoryObj(compressed)),
+        cast(MemoryObj, _FakeMemoryObj(recovered)),
+    )
+
+    orig_f = original.float().flatten()
+    rec_f = recovered.float().flatten()
+
+    corr = torch.corrcoef(torch.stack([orig_f, rec_f]))[0, 1].item()
+    mae = torch.mean(torch.abs(orig_f - rec_f)).item()
+    mse = torch.mean((orig_f - rec_f) ** 2).item()
+
+    original_bytes = original.numel() * original.element_size()
+    ratio = original_bytes / n_bytes
+
+    assert ratio >= expected_ratio_lower_bound
+    assert corr > corr_lower_bound, (
+        f"low corr for preset={preset}: corr={corr}, mae={mae}, mse={mse}"
+    )
+
+
+# =============================================================================
+# GPU E2E test: StorageManager + SerdeL2AdapterWrapper + FSL2Adapter
+# =============================================================================
+
+
+def _make_turboquant_fs_storage_manager(
+    base_path: str,
+    preset: str,
+) -> StorageManager:
+    adapter_cfg = FSL2AdapterConfig(
+        base_path=base_path,
+        relative_tmp_dir="tmp",
+        use_odirect=False,
+    )
+    adapter_cfg.serde_config = SerdeConfig(
+        type="turboquant",
+        kwargs={
+            "preset": preset,
+            "head_dim": 128,
+            "block_size": 16,
+            "max_workers": 1,
+        },
+    )
+
+    cfg = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=256 * 1024 * 1024,
+                use_lazy=torch.cuda.is_available(),
+                init_size_in_bytes=64 * 1024 * 1024,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(adapters=[adapter_cfg]),
+    )
+    return StorageManager(cfg)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA is not available")
+@pytest.mark.parametrize(
+    ("preset", "corr_lower_bound"),
+    [
+        ("turboquant_k8v4", 0.95),
+        ("turboquant_4bit_nc", 0.90),
+        ("turboquant_k3v4_nc", 0.85),
+        ("turboquant_3bit_nc", 0.80),
+    ],
+)
+def test_turboquant_fs_storage_manager_roundtrip(
+    preset: str,
+    corr_lower_bound: float,
+) -> None:
+    """Store/load through FSL2Adapter with TurboQuant serde."""
+    base_dir = tempfile.mkdtemp(prefix="lmcache_turboquant_fs_")
+    sm = None
+
+    try:
+        sm = _make_turboquant_fs_storage_manager(base_dir, preset)
+        layout = _make_turboquant_layout()
+        keys = [_make_turboquant_object_key(i) for i in range(3)]
+
+        ret = sm.reserve_write(keys, layout, mode="new")
+        assert len(ret) == len(keys), f"reserve_write got {len(ret)} / {len(keys)}"
+
+        original_by_key = {}
+        for i, key in enumerate(keys):
+            obj = ret[key]
+            assert obj.tensor is not None
+
+            torch.manual_seed(5678 + i)
+            data = torch.randn(
+                obj.tensor.shape,
+                dtype=obj.tensor.dtype,
+                device=obj.tensor.device,
+            )
+            data = data + float(i)
+
+            obj.tensor.copy_(data)
+            original_by_key[key] = data.detach().clone()
+
+        sm.finish_write(list(ret.keys()))
+
+        ok = _wait_for_condition(
+            lambda: (
+                sm.report_status()["store_controller"]["in_flight_task_count"] == 0
+                and sm.report_status()["store_controller"]["pending_keys_count"] == 0
+                and sm.report_status()["l1_manager"]["write_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["read_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["temporary_count"] == 0
+            ),
+            timeout=120.0,
+        )
+        assert ok, "Store to FS L2 did not fully complete"
+
+        stored_files = [p for p in Path(base_dir).rglob("*") if p.is_file()]
+        assert len(stored_files) >= len(keys)
+
+        sm.clear()
+        ok = _wait_for_condition(
+            lambda: (
+                sm.report_status()["l1_manager"]["total_object_count"] == 0
+                and sm.report_status()["l1_manager"]["memory_used_bytes"] == 0
+                and sm.report_status()["l1_manager"]["read_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["write_locked_count"] == 0
+                and sm.report_status()["l1_manager"]["temporary_count"] == 0
+            ),
+            timeout=120.0,
+        )
+        assert ok, f"L1 not cleared: {sm.report_status()['l1_manager']}"
+
+        handle = sm.submit_prefetch_task(keys, layout)
+        hit_bitmap = _wait_for_prefetch_status(sm, handle, timeout=120.0)
+        assert hit_bitmap is not None
+        hits = hit_bitmap.count_leading_ones()
+        assert hits == len(keys), f"Expected {len(keys)} hits, got {hits}"
+
+        with sm.read_prefetched_results(keys) as objs:
+            assert objs is not None
+            assert len(objs) == len(keys)
+
+            for key, obj in zip(keys, objs, strict=True):
+                assert obj.tensor is not None
+
+                recovered = obj.tensor
+                original = original_by_key[key]
+
+                orig_f = original.float().flatten()
+                rec_f = recovered.float().flatten()
+
+                corr = torch.corrcoef(torch.stack([orig_f, rec_f]))[0, 1].item()
+                mae = torch.mean(torch.abs(orig_f - rec_f)).item()
+                mse = torch.mean((orig_f - rec_f) ** 2).item()
+
+                assert corr > corr_lower_bound, (
+                    f"low corr for preset={preset}, key={key}: "
+                    f"corr={corr}, mae={mae}, mse={mse}"
+                )
+
+        _finish_read_prefetched_until_clean(sm, keys)
+
+    finally:
+        if sm is not None:
+            sm.close()
+        shutil.rmtree(base_dir, ignore_errors=True)
diff --git a/tests/v1/distributed/serde/test_utils.py b/tests/v1/distributed/serde/test_utils.py
new file mode 100644
index 0000000..b8f4a53
--- /dev/null
+++ b/tests/v1/distributed/serde/test_utils.py
@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for ``lmcache.v1.distributed.serde.utils``."""
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.serde.utils import make_temp_key
+
+
+def _orig(salt: str = "", object_group_id: int = 0) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=b"\x00" * 16,
+        model_name="model",
+        kv_rank=0,
+        object_group_id=object_group_id,
+        cache_salt=salt,
+    )
+
+
+def test_make_temp_key_propagates_cache_salt() -> None:
+    """Temp keys inherit ``cache_salt`` so per-tenant L1 byte accounting
+    keeps temp buffers attributed to the same bucket as their originals."""
+    salt = "tenant-A"
+    temp = make_temp_key(_orig(salt=salt))
+    assert temp.cache_salt == salt
+
+
+def test_make_temp_key_propagates_other_fields() -> None:
+    """Non-hash identity fields are preserved verbatim."""
+    orig = _orig(salt="tenant-X", object_group_id=3)
+    temp = make_temp_key(orig)
+    assert temp.model_name == orig.model_name
+    assert temp.kv_rank == orig.kv_rank
+    assert temp.object_group_id == orig.object_group_id
+
+
+def test_make_temp_key_differs_from_original() -> None:
+    """Suffix ensures temp_hash ≠ original_hash so temps cannot collide
+    with real keys in the L1 namespace."""
+    orig = _orig()
+    temp = make_temp_key(orig)
+    assert temp.chunk_hash != orig.chunk_hash
+    assert temp.chunk_hash.startswith(orig.chunk_hash)
+
+
+def test_make_temp_key_unique_across_calls() -> None:
+    """Two temp keys for the same original are distinct."""
+    orig = _orig()
+    a = make_temp_key(orig)
+    b = make_temp_key(orig)
+    assert a.chunk_hash != b.chunk_hash
diff --git a/tests/v1/distributed/test_aerospike_l2_adapter_config.py b/tests/v1/distributed/test_aerospike_l2_adapter_config.py
new file mode 100644
index 0000000..c2859d6
--- /dev/null
+++ b/tests/v1/distributed/test_aerospike_l2_adapter_config.py
@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for Aerospike L2 adapter config (no native extension required)."""
+
+# Standard
+import os
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.config import (
+    get_registered_l2_adapter_types,
+    get_type_name_for_config,
+)
+from lmcache.v1.distributed.l2_adapters.factory import ensure_adapter_loaded
+
+
+class TestAerospikeL2AdapterConfig:
+    def test_type_registered(self):
+        ensure_adapter_loaded("aerospike")
+        assert "aerospike" in get_registered_l2_adapter_types()
+
+    def test_from_dict_required_fields(self):
+        ensure_adapter_loaded("aerospike")
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.aerospike_l2_adapter import (
+            AerospikeL2AdapterConfig,
+        )
+
+        cfg = AerospikeL2AdapterConfig.from_dict(
+            {
+                "type": "aerospike",
+                "hosts": "127.0.0.1:3000",
+                "namespace": "lmcache",
+                "set_name": "kv_it",
+            }
+        )
+        assert cfg.hosts == "127.0.0.1:3000"
+        assert cfg.namespace == "lmcache"
+        assert cfg.set_name == "kv_it"
+        assert get_type_name_for_config(cfg) == "aerospike"
+
+    def test_set_alias(self):
+        ensure_adapter_loaded("aerospike")
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.aerospike_l2_adapter import (
+            AerospikeL2AdapterConfig,
+        )
+
+        cfg = AerospikeL2AdapterConfig.from_dict(
+            {"type": "aerospike", "hosts": "h:3000", "set": "myset"}
+        )
+        assert cfg.set_name == "myset"
+
+    def test_missing_hosts_raises(self):
+        ensure_adapter_loaded("aerospike")
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.aerospike_l2_adapter import (
+            AerospikeL2AdapterConfig,
+        )
+
+        try:
+            AerospikeL2AdapterConfig.from_dict({"type": "aerospike"})
+            raised = False
+        except ValueError:
+            raised = True
+        assert raised
+
+    def test_env_vars_used_when_config_empty(self, monkeypatch):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.aerospike_l2_adapter import (
+            AerospikeL2AdapterConfig,
+        )
+
+        monkeypatch.setenv("LMCACHE_AEROSPIKE_HOSTS", "env-host:3000")
+        monkeypatch.setenv("LMCACHE_AEROSPIKE_NAMESPACE", "env-ns")
+        monkeypatch.setenv("LMCACHE_AEROSPIKE_SET", "env-set")
+        monkeypatch.setenv("LMCACHE_AEROSPIKE_USERNAME", "env-user")
+        monkeypatch.setenv("LMCACHE_AEROSPIKE_PASSWORD", "env-pass")
+
+        cfg = AerospikeL2AdapterConfig(hosts="", namespace="", set_name="")
+
+        hosts = cfg.hosts or os.environ.get("LMCACHE_AEROSPIKE_HOSTS", "")
+        namespace = cfg.namespace or os.environ.get(
+            "LMCACHE_AEROSPIKE_NAMESPACE", "lmcache"
+        )
+        set_name = cfg.set_name or os.environ.get("LMCACHE_AEROSPIKE_SET", "kv_chunks")
+        username = cfg.username or os.environ.get("LMCACHE_AEROSPIKE_USERNAME", "")
+        password = cfg.password or os.environ.get("LMCACHE_AEROSPIKE_PASSWORD", "")
+
+        assert hosts == "env-host:3000"
+        assert namespace == "env-ns"
+        assert set_name == "env-set"
+        assert username == "env-user"
+        assert password == "env-pass"
diff --git a/tests/v1/distributed/test_aerospike_l2_integration.py b/tests/v1/distributed/test_aerospike_l2_integration.py
new file mode 100644
index 0000000..46c7d76
--- /dev/null
+++ b/tests/v1/distributed/test_aerospike_l2_integration.py
@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Integration tests for the Aerospike L2 adapter (native connector).
+
+Requires Aerospike CE and BUILD_AEROSPIKE=1 extension. Skipped otherwise.
+"""
+
+# Standard
+import os
+import select
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.l2_adapters.factory import create_l2_adapter_from_registry
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+AEROSPIKE_HOST = os.environ.get("AEROSPIKE_TEST_HOST", "127.0.0.1")
+AEROSPIKE_PORT = int(os.environ.get("AEROSPIKE_TEST_PORT", "3000"))
+AEROSPIKE_NAMESPACE = os.environ.get("AEROSPIKE_TEST_NAMESPACE", "lmcache")
+RUN_AEROSPIKE_IT = os.environ.get("RUN_AEROSPIKE_INTEGRATION") == "1"
+
+
+def _aerospike_available() -> bool:
+    if not RUN_AEROSPIKE_IT:
+        return False
+    try:
+        # Third Party
+        import aerospike
+
+        client = aerospike.client(
+            {"hosts": [(AEROSPIKE_HOST, AEROSPIKE_PORT)]}
+        ).connect()
+        info = client.info_random_node(f"namespace/{AEROSPIKE_NAMESPACE}")
+        client.close()
+        return "nsup-period" in info
+    except Exception:
+        return False
+
+
+def _native_extension_available() -> bool:
+    try:
+        # First Party
+        from lmcache.lmcache_aerospike import LMCacheAerospikeClient  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+requires_aerospike = pytest.mark.skipif(
+    not _aerospike_available(),
+    reason=(
+        f"Aerospike not available at {AEROSPIKE_HOST}:{AEROSPIKE_PORT} "
+        "(set RUN_AEROSPIKE_INTEGRATION=1)"
+    ),
+)
+requires_native = pytest.mark.skipif(
+    not _native_extension_available(),
+    reason="lmcache.lmcache_aerospike extension not built",
+)
+
+
+def _wait_fd(fd: int, timeout: float = 30.0) -> None:
+    poller = select.poll()
+    poller.register(fd, select.POLLIN)
+    events = poller.poll(timeout * 1000)
+    assert events, "timed out waiting for eventfd"
+    try:
+        consume_fd(fd)
+    except BlockingIOError:
+        pass
+
+
+def _make_tensor_obj(size: int, fill: float) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def _object_key(suffix: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(suffix),
+        model_name="aerospike-it",
+        kv_rank=0,
+    )
+
+
+def _adapter_config():
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.aerospike_l2_adapter import (
+        AerospikeL2AdapterConfig,
+    )
+
+    return AerospikeL2AdapterConfig(
+        hosts=f"{AEROSPIKE_HOST}:{AEROSPIKE_PORT}",
+        namespace=AEROSPIKE_NAMESPACE,
+        set_name="kv_chunks_aerospike_it",
+        num_workers=2,
+    )
+
+
+@requires_aerospike
+@requires_native
+class TestAerospikeL2Integration:
+    def test_store_lookup_load_roundtrip(self):
+        adapter = create_l2_adapter_from_registry(_adapter_config())
+        try:
+            key = _object_key(9001)
+            store_obj = _make_tensor_obj(64, 42.0)
+            load_obj = _make_tensor_obj(64, 0.0)
+
+            tid = adapter.submit_store_task([key], [store_obj])
+            _wait_fd(adapter.get_store_event_fd())
+            done = adapter.pop_completed_store_tasks()
+            assert done[tid].is_successful()
+
+            lookup_tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+            _wait_fd(adapter.get_lookup_and_lock_event_fd())
+            lookup_bm = adapter.query_lookup_and_lock_result(lookup_tid)
+            assert lookup_bm is not None
+            assert lookup_bm.test(0)
+
+            load_tid = adapter.submit_load_task([key], [load_obj])
+            _wait_fd(adapter.get_load_event_fd())
+            load_bm = adapter.query_load_result(load_tid)
+            assert load_bm is not None
+            assert load_bm.test(0)
+            assert torch.all(load_obj.tensor == 42.0)
+
+            adapter.submit_unlock([key])
+        finally:
+            adapter.close()
diff --git a/tests/v1/distributed/test_bitmap_ops.py b/tests/v1/distributed/test_bitmap_ops.py
new file mode 100644
index 0000000..612a0a6
--- /dev/null
+++ b/tests/v1/distributed/test_bitmap_ops.py
@@ -0,0 +1,567 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the fold / unfold prefix-cache hit logic."""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import TrimPolicy
+from lmcache.v1.distributed.bitmap_ops import (
+    FULL_ATTENTION_WINDOW,
+    fold,
+    fold_unfold,
+    fold_unfold_ranked,
+    highest_set_bit,
+    merge_bitmaps,
+    select_retained,
+    unfold,
+    unfold_range,
+)
+from lmcache.v1.distributed.bitmap_ops.fold import _fold_python, _unfold_python
+
+
+def _make_presence(num_chunks: int, present_per_group: list[list[int]]) -> Bitmap:
+    """Build a group-major presence bitmap.
+
+    Args:
+        num_chunks: chunks per group.
+        present_per_group: present_per_group[g] is the list of chunk indices
+            available for object group g.
+
+    Returns:
+        A group-major Bitmap of length ``len(present_per_group) * num_chunks``.
+    """
+    bm = Bitmap(len(present_per_group) * num_chunks)
+    for group_idx, chunks in enumerate(present_per_group):
+        base = group_idx * num_chunks
+        for j in chunks:
+            bm.set(base + j)
+    return bm
+
+
+# --------------------------------------------------------------------------- #
+# unfold_range                                                                 #
+# --------------------------------------------------------------------------- #
+
+
+def test_unfold_full_attention_needs_whole_prefix():
+    assert unfold_range(4, FULL_ATTENTION_WINDOW) == (0, 4)
+    assert unfold_range(4, 0) == (0, 4)
+
+
+def test_unfold_window_needs_only_last_w():
+    assert unfold_range(4, 2) == (2, 4)
+    assert unfold_range(1, 2) == (0, 1)  # window larger than prefix
+    assert unfold_range(5, 1) == (4, 5)  # mamba: last chunk only
+
+
+def test_unfold_empty_prefix():
+    assert unfold_range(0, FULL_ATTENTION_WINDOW) == (0, 0)
+    assert unfold_range(0, 2) == (0, 0)
+
+
+# --------------------------------------------------------------------------- #
+# fold_unfold — single group reduces to leading-ones                           #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize(
+    "present,expected_hit",
+    [
+        ([0, 1, 2], 3),  # full contiguous prefix
+        ([0, 1, 3], 2),  # gap at 2 caps the prefix
+        ([], 0),  # nothing present
+        ([1, 2], 0),  # missing chunk 0 -> empty prefix
+    ],
+)
+def test_single_full_group_equals_leading_ones(present, expected_hit):
+    num_chunks = 4
+    found = _make_presence(num_chunks, [present])
+    hit, mask = fold_unfold(found, num_chunks, [FULL_ATTENTION_WINDOW])
+    assert hit == expected_hit
+    # equals the plain PREFIX leading-ones count on the same bitmap
+    assert hit == found.count_leading_ones()
+    # retained mask is exactly the first `hit` chunks
+    assert mask.get_indices_list() == list(range(expected_hit))
+
+
+# --------------------------------------------------------------------------- #
+# fold_unfold — worked full + sliding-window example                           #
+# --------------------------------------------------------------------------- #
+
+
+def test_full_plus_sliding_window_worked_example():
+    # N=5; group A full present {0,1,2,3}; group B sliding-window w=2 {2,3,4}.
+    # A blocks length 5 (chunk 4 missing); B's last-2 window at L=4 is {2,3} (present).
+    num_chunks = 5
+    found = _make_presence(num_chunks, [[0, 1, 2, 3], [2, 3, 4]])
+    hit, mask = fold_unfold(found, num_chunks, [FULL_ATTENTION_WINDOW, 2])
+    assert hit == 4
+    # A (full) needs chunks 0..3 -> flat 0,1,2,3 ; B (w=2) needs 2..3 -> flat 7,8
+    assert mask.get_indices_list() == [0, 1, 2, 3, 7, 8]
+
+
+def test_sliding_window_does_not_block_long_prefix_when_tail_present():
+    # SW group missing early chunks but holding the tail still serves a long hit.
+    num_chunks = 6
+    found = _make_presence(num_chunks, [[0, 1, 2, 3, 4, 5], [4, 5]])
+    hit, mask = fold_unfold(found, num_chunks, [FULL_ATTENTION_WINDOW, 2])
+    assert hit == 6
+    # full needs 0..5 ; window-2 needs 4..5 -> flat 6*1 + {4,5} = {10,11}
+    assert mask.get_indices_list() == [0, 1, 2, 3, 4, 5, 10, 11]
+
+
+def test_mamba_window_one():
+    # mamba == window 1: only the last chunk of the prefix is needed.
+    num_chunks = 4
+    found = _make_presence(num_chunks, [[0, 1, 2, 3], [3]])
+    hit, mask = fold_unfold(found, num_chunks, [FULL_ATTENTION_WINDOW, 1])
+    assert hit == 4
+    assert mask.get_indices_list() == [0, 1, 2, 3, 7]  # full 0..3 + mamba {3}
+
+
+# --------------------------------------------------------------------------- #
+# fold_unfold — all-full reduces to require-all intersection                   #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize(
+    "group_a,group_b,expected_hit",
+    [
+        ([0, 1, 2, 3], [0, 1, 2, 3], 4),  # both full -> full
+        ([0, 1, 2, 3], [0, 1], 2),  # B caps at 2
+        ([0, 1], [0, 1, 2, 3], 2),  # A caps at 2
+        ([0, 2, 3], [0, 1, 2, 3], 1),  # A gap at 1 caps at 1
+    ],
+)
+def test_all_full_is_require_all_intersection(group_a, group_b, expected_hit):
+    num_chunks = 4
+    found = _make_presence(num_chunks, [group_a, group_b])
+    windows = [FULL_ATTENTION_WINDOW, FULL_ATTENTION_WINDOW]
+    hit, mask = fold_unfold(found, num_chunks, windows)
+    assert hit == expected_hit
+    # both groups retain the same first `hit` chunks
+    expected = list(range(expected_hit)) + [num_chunks + j for j in range(expected_hit)]
+    assert mask.get_indices_list() == expected
+
+
+# --------------------------------------------------------------------------- #
+# fold_unfold — edges                                                          #
+# --------------------------------------------------------------------------- #
+
+
+def test_zero_chunks():
+    found = Bitmap(0)
+    hit, mask = fold_unfold(found, 0, [FULL_ATTENTION_WINDOW, 2])
+    assert hit == 0
+    assert mask.get_indices_list() == []
+
+
+# --------------------------------------------------------------------------- #
+# fold_unfold_ranked — group x chunk x kv_rank layout                          #
+# --------------------------------------------------------------------------- #
+
+
+def _make_ranked(
+    num_chunks: int,
+    num_ranks: int,
+    present_per_group: list[list[tuple[int, int]]],
+) -> Bitmap:
+    """Build a group-major / chunk-major / rank-minor presence bitmap.
+
+    present_per_group[g] is the list of ``(chunk, rank)`` present for group g.
+    """
+    num_groups = len(present_per_group)
+    stride = num_chunks * num_ranks
+    bm = Bitmap(num_groups * stride)
+    for group_idx, cells in enumerate(present_per_group):
+        gbase = group_idx * stride
+        for chunk, rank in cells:
+            bm.set(gbase + chunk * num_ranks + rank)
+    return bm
+
+
+def test_ranked_chunk_present_only_if_all_ranks_present():
+    # 1 full group, 2 ranks, 3 chunks. chunk1 is missing rank 1 -> not present.
+    present = [[(0, 0), (0, 1), (1, 0), (2, 0), (2, 1)]]
+    found = _make_ranked(3, 2, present)
+    hit, mask = fold_unfold_ranked(found, 3, 2, [FULL_ATTENTION_WINDOW])
+    assert hit == 1  # only chunk 0 has both ranks; chunk1 gap caps the prefix
+    assert mask.get_indices_list() == [0, 1]  # both ranks of chunk 0
+
+
+def test_ranked_reduces_to_unranked_when_one_rank():
+    # num_ranks == 1 must match fold_unfold exactly.
+    found_unranked = _make_presence(5, [[0, 1, 2, 3], [2, 3, 4]])
+    found_ranked = _make_ranked(
+        5, 1, [[(c, 0) for c in [0, 1, 2, 3]], [(c, 0) for c in [2, 3, 4]]]
+    )
+    hit_u, mask_u = fold_unfold(found_unranked, 5, [FULL_ATTENTION_WINDOW, 2])
+    hit_r, mask_r = fold_unfold_ranked(found_ranked, 5, 1, [FULL_ATTENTION_WINDOW, 2])
+    assert hit_u == hit_r == 4
+    assert mask_u.get_indices_list() == mask_r.get_indices_list()
+
+
+def test_ranked_full_plus_sw_expands_all_ranks():
+    # 2 groups, 2 ranks, 4 chunks. group0 full all present; group1 SW w=1 all present.
+    g0 = [(c, r) for c in range(4) for r in range(2)]
+    g1 = [(c, r) for c in range(4) for r in range(2)]
+    found = _make_ranked(4, 2, [g0, g1])
+    hit, mask = fold_unfold_ranked(found, 4, 2, [FULL_ATTENTION_WINDOW, 1])
+    assert hit == 4
+    # group0 full -> chunks 0..3 (ranks 0,1): flat 0..7
+    # group1 w=1 -> chunk 3 only (ranks 0,1): group base = 4*2 = 8, chunk3 -> 8+6,8+7
+    assert mask.get_indices_list() == [0, 1, 2, 3, 4, 5, 6, 7, 14, 15]
+
+
+def test_ranked_invalid_num_ranks_raises():
+    with pytest.raises(ValueError):
+        fold_unfold_ranked(Bitmap(0), 0, 0, [FULL_ATTENTION_WINDOW])
+
+
+def test_empty_group_windows_raises():
+    with pytest.raises(ValueError):
+        fold_unfold(Bitmap(0), 0, [])
+
+
+def test_negative_num_chunks_raises():
+    with pytest.raises(ValueError):
+        fold_unfold(Bitmap(0), -1, [FULL_ATTENTION_WINDOW])
+
+
+def _bm(num_keys: int, set_indices: list[int]) -> Bitmap:
+    bm = Bitmap(num_keys)
+    for i in set_indices:
+        bm.set(i)
+    return bm
+
+
+class TestSelectRetained:
+    """select_retained picks the retained subset per policy: PREFIX trims at the
+    first gap; any other policy keeps every set bit (gaps and all)."""
+
+    def test_prefix_trims_at_first_gap(self):
+        found = _bm(5, [0, 1, 3, 4])  # gap at index 2
+        assert select_retained(found, 5, TrimPolicy.PREFIX).get_indices_list() == [0, 1]
+
+    def test_sparse_keeps_all_found(self):
+        found = _bm(5, [0, 2, 4])
+        result = select_retained(found, 5, TrimPolicy.SPARSE).get_indices_list()
+        assert result == [0, 2, 4]
+
+    def test_segmented_prefix_keeps_all_found(self):
+        found = _bm(5, [0, 1, 3, 4])  # gap at index 2
+        result = select_retained(
+            found, 5, TrimPolicy.SEGMENTED_PREFIX
+        ).get_indices_list()
+        assert result == [0, 1, 3, 4]
+
+
+class TestMergeBitmaps:
+    """merge_bitmaps always returns a num_keys-sized bitmap."""
+
+    def test_empty_input_returns_sized_bitmap(self):
+        """Empty input -> num_keys-sized all-zeros bitmap (not Bitmap(0)), so a
+        downstream ``&`` with a same-sized mask never hits a size mismatch."""
+        merged = merge_bitmaps([], 5)
+        assert merged.popcount() == 0
+        mask = Bitmap(5)
+        mask.set(2)
+        assert (merged & mask).popcount() == 0  # would raise on size mismatch
+
+    def test_empty_generator_returns_sized_bitmap(self):
+        """A generator is truthy even when empty; the result is still size-5."""
+        merged = merge_bitmaps((b for b in []), 5)
+        assert merged.popcount() == 0
+        assert (merged & Bitmap(5)).popcount() == 0
+
+    def test_union_of_bitmaps(self):
+        """Non-empty inputs are OR-merged into one num_keys-sized bitmap."""
+        a, b = Bitmap(5), Bitmap(5)
+        a.set(0)
+        b.set(3)
+        assert merge_bitmaps([a, b], 5).get_indices_list() == [0, 3]
+
+
+# --------------------------------------------------------------------------- #
+# Separated operators: fold / highest_set_bit / unfold                      #
+# --------------------------------------------------------------------------- #
+
+
+class TestFoldOperator:
+    """``fold`` produces the servable bitmap (bit ``j`` = every group can serve
+    a length-``j + 1`` prefix)."""
+
+    def test_full_attention_servable_is_downward_closed(self):
+        # full group present {0,1,2} of 4 -> servable lengths {1,2,3} -> bits
+        # {0,1,2} (bit j == length j+1).
+        found = _make_ranked(4, 1, [[(0, 0), (1, 0), (2, 0)]])
+        servable = fold(found, 4, 1, [FULL_ATTENTION_WINDOW])
+        assert servable.get_indices_list() == [0, 1, 2]
+
+    def test_sliding_window_servable_is_gappy(self):
+        # window-2 group present chunks {0,1,3,4} of 5. A length L is servable
+        # iff chunks [L-2, L) present: L=1 ok(0), 2 ok(0,1), 3 no(1,2),
+        # 4 no(2,3), 5 ok(3,4) -> lengths {1,2,5} -> bits {0,1,4}.
+        found = _make_ranked(5, 1, [[(0, 0), (1, 0), (3, 0), (4, 0)]])
+        servable = fold(found, 5, 1, [2])
+        assert servable.get_indices_list() == [0, 1, 4]
+
+    def test_nothing_present_is_empty(self):
+        # No chunk present -> no length servable -> empty bitmap (highest_set_bit
+        # returns -1, so the pipeline reports hit length 0).
+        found = _make_ranked(3, 2, [[]])  # nothing present
+        servable = fold(found, 3, 2, [FULL_ATTENTION_WINDOW])
+        assert servable.get_indices_list() == []
+
+
+class TestHighestSetBit:
+    """``highest_set_bit`` returns the highest set bit, -1 if none."""
+
+    def test_basic(self):
+        bm = Bitmap(10)
+        for i in (1, 4, 7):
+            bm.set(i)
+        assert highest_set_bit(bm) == 7
+
+    def test_empty_returns_minus_one(self):
+        assert highest_set_bit(Bitmap(10)) == -1
+        assert highest_set_bit(Bitmap(0)) == -1
+
+    def test_single_and_last_bit(self):
+        bm = Bitmap(9)
+        bm.set(8)
+        assert highest_set_bit(bm) == 8
+
+
+class TestUnfoldOperator:
+    """``unfold`` expands a hit length into the ranked retain mask."""
+
+    def test_full_plus_sliding_window(self):
+        # hit=4, full group keeps [0,4), window-2 group keeps [2,4); 2 ranks.
+        mask = unfold(4, 5, 2, [FULL_ATTENTION_WINDOW, 2])
+        stride = 5 * 2
+        expected = [0, 1, 2, 3, 4, 5, 6, 7]  # full: chunks 0..3 x 2 ranks
+        expected += [stride + 4, stride + 5, stride + 6, stride + 7]  # win: c2,c3
+        assert mask.get_indices_list() == expected
+
+    def test_zero_hit_is_empty(self):
+        assert unfold(0, 5, 2, [FULL_ATTENTION_WINDOW, 2]).get_indices_list() == []
+
+    def test_hit_clamped_to_num_chunks(self):
+        # hit beyond num_chunks is clamped; full group keeps every chunk.
+        mask = unfold(99, 3, 1, [FULL_ATTENTION_WINDOW])
+        assert mask.get_indices_list() == [0, 1, 2]
+
+
+# --------------------------------------------------------------------------- #
+# Native ops must match the pure-Python reference (_fold_python/_unfold_python) #
+# bit-for-bit, on deterministic constructed inputs.                            #
+# --------------------------------------------------------------------------- #
+
+
+class TestNativeMatchesReference:
+    # (num_chunks, num_ranks, group_windows) shapes, small to large.
+    CASES = [
+        (64, 1, [FULL_ATTENTION_WINDOW]),
+        (64, 4, [FULL_ATTENTION_WINDOW, FULL_ATTENTION_WINDOW]),
+        (100, 3, [FULL_ATTENTION_WINDOW, 2, 5, 1]),
+        (300, 4, [FULL_ATTENTION_WINDOW, FULL_ATTENTION_WINDOW, 8, 32, 1]),
+    ]
+
+    def test_fold_matches_reference(self):
+        for num_chunks, num_ranks, gw in self.CASES:
+            nk = len(gw) * num_chunks * num_ranks
+            bm = Bitmap(nk)
+            # Deterministic irregular gap pattern (no RNG): drop ~1/7 of bits on
+            # an irregular stride so windows and rank-reduction are exercised.
+            bm.batched_set([i for i in range(nk) if (i * 5 + i // num_ranks) % 7 != 0])
+            assert (
+                fold(bm, num_chunks, num_ranks, gw).get_indices_list()
+                == _fold_python(bm, num_chunks, num_ranks, gw).get_indices_list()
+            ), f"fold mismatch C={num_chunks} R={num_ranks} gw={gw}"
+
+    def test_unfold_matches_reference_at_boundaries(self):
+        for num_chunks, num_ranks, gw in self.CASES:
+            # Cover empty, both ends, and interior hit lengths.
+            for hit in (0, 1, num_chunks // 3, num_chunks - 1, num_chunks):
+                assert (
+                    unfold(hit, num_chunks, num_ranks, gw).get_indices_list()
+                    == _unfold_python(hit, num_chunks, num_ranks, gw).get_indices_list()
+                ), f"unfold mismatch hit={hit} C={num_chunks} R={num_ranks} gw={gw}"
+
+
+# --------------------------------------------------------------------------- #
+# End-to-end: full fold -> highest_set_bit -> unfold pipeline against an    #
+# independent reference modeling vLLM's hybrid prefix-cache hit logic.         #
+# --------------------------------------------------------------------------- #
+
+
+def _reference_longest_hit(num_chunks, group_present, group_windows):
+    """Longest model-wide prefix hit, mirroring vLLM's per-group
+    ``find_longest_cache_hit`` combined across a hybrid model (independent
+    brute force; no vLLM import).
+
+    A length-``L`` prefix is a model-wide hit iff every object group can serve
+    it under its rule:
+
+    * full attention (``window <= 0``): chunks ``[0, L)`` all present
+      (vLLM ``FullAttentionManager``);
+    * sliding window ``w``: chunks ``[max(0, L - w), L)`` all present
+      (vLLM ``SlidingWindowManager``).
+
+    Args:
+        num_chunks: number of chunks.
+        group_present: ``group_present[g]`` = set of chunk indices present for
+            object group ``g`` (after requiring every kv_rank present).
+        group_windows: per-group window size; ``<= 0`` means full attention.
+
+    Returns:
+        The largest ``L`` in ``[0, num_chunks]`` servable by all groups.
+    """
+    best = 0
+    for length in range(num_chunks + 1):
+        servable_by_all = True
+        for present, window in zip(group_present, group_windows, strict=True):
+            lo = 0 if window <= 0 else max(0, length - window)
+            if not all(j in present for j in range(lo, length)):
+                servable_by_all = False
+                break
+        if servable_by_all:
+            best = length
+    return best
+
+
+def _expected_retained_indices(hit, num_chunks, num_ranks, group_windows):
+    """The ranked retain-mask indices the pipeline should produce for ``hit``."""
+    indices = []
+    stride = num_chunks * num_ranks
+    for g, window in enumerate(group_windows):
+        lo, hi = unfold_range(hit, window)
+        for j in range(lo, hi):
+            base = g * stride + j * num_ranks
+            indices.extend(range(base, base + num_ranks))
+    return sorted(indices)
+
+
+class TestEndToEndAgainstVllmStyleReference:
+    """Drive the full fold/highest_set_bit/unfold pipeline and compare the
+    hit length and retain mask against an independent vLLM-style oracle."""
+
+    def _run(
+        self, num_chunks, num_ranks, group_windows, present_cells, expected_hit=None
+    ):
+        # present_cells[g] = set of (chunk, rank) present for group g.
+        stride = num_chunks * num_ranks
+        bm = Bitmap(len(group_windows) * stride)
+        for g, cells in enumerate(present_cells):
+            for chunk, rank in cells:
+                bm.set(g * stride + chunk * num_ranks + rank)
+        hit, mask = fold_unfold_ranked(bm, num_chunks, num_ranks, group_windows)
+
+        # Reference: a chunk is present for a group only if all ranks present.
+        group_present = [
+            {
+                chunk
+                for chunk in range(num_chunks)
+                if all((chunk, r) in cells for r in range(num_ranks))
+            }
+            for cells in present_cells
+        ]
+        ref_hit = _reference_longest_hit(num_chunks, group_present, group_windows)
+        assert hit == ref_hit, (
+            f"hit {hit} != reference {ref_hit} "
+            f"(windows={group_windows}, present={group_present})"
+        )
+        if expected_hit is not None:
+            assert hit == expected_hit, f"hit {hit} != hand-derived {expected_hit}"
+        assert mask.get_indices_list() == _expected_retained_indices(
+            hit, num_chunks, num_ranks, group_windows
+        )
+
+    def test_full_attention_only_is_contiguous_prefix(self):
+        # Two full-attention groups; hit is the shortest contiguous prefix.
+        self._run(
+            num_chunks=6,
+            num_ranks=2,
+            group_windows=[FULL_ATTENTION_WINDOW, FULL_ATTENTION_WINDOW],
+            present_cells=[
+                {(j, r) for j in range(5) for r in range(2)},  # chunks 0..4
+                {(j, r) for j in range(3) for r in range(2)},  # chunks 0..2
+            ],
+        )  # -> hit 3
+
+    def test_sliding_window_tail_extends_hit(self):
+        # Full group has 0..5; window-2 group only has the tail {4,5} -> hit 6.
+        self._run(
+            num_chunks=6,
+            num_ranks=1,
+            group_windows=[FULL_ATTENTION_WINDOW, 2],
+            present_cells=[
+                {(j, 0) for j in range(6)},
+                {(4, 0), (5, 0)},
+            ],
+        )
+
+    def test_mamba_window_one(self):
+        self._run(
+            num_chunks=4,
+            num_ranks=1,
+            group_windows=[FULL_ATTENTION_WINDOW, 1],
+            present_cells=[{(j, 0) for j in range(4)}, {(3, 0)}],
+        )  # -> hit 4
+
+    def test_missing_rank_breaks_chunk(self):
+        # chunk 2 missing one rank -> not present -> caps the full-attn prefix.
+        self._run(
+            num_chunks=5,
+            num_ranks=2,
+            group_windows=[FULL_ATTENTION_WINDOW],
+            present_cells=[
+                {(0, 0), (0, 1), (1, 0), (1, 1), (2, 0), (3, 0), (3, 1)},
+            ],
+        )  # -> hit 2
+
+    def test_large_adversarial_hybrid(self):
+        # A large, deterministic scenario engineered so the hit is decided by a
+        # mid-window sliding-window gap, with decoy later gaps a wrong algorithm
+        # might trip on. 300 chunks x 4 ranks x 5 groups.
+        #
+        # windows: [full, full, SW8, SW32, mamba]
+        #   - g0 full: gap at chunk 150          -> full prefix capped at 150
+        #   - g1 full: one rank of chunk 220 gone -> chunk 220 absent (rank test)
+        #   - g2 SW8:  gaps at 10,11,12 (old)     -> must NOT affect a hit > 20
+        #   - g3 SW32: gap at chunk 130           -> lengths 131..162 unservable
+        #   - g4 mamba: fully present
+        # The only length servable by all groups and <= 150 is 130 (g3's gap at
+        # 130 blocks 131..162; g3 is servable again only at >= 163, beyond g0's
+        # 150 cap). So the model-wide hit is exactly 130.
+        num_chunks, num_ranks = 300, 4
+        group_windows = [FULL_ATTENTION_WINDOW, FULL_ATTENTION_WINDOW, 8, 32, 1]
+        cells = [
+            {(j, r) for j in range(num_chunks) for r in range(num_ranks)}
+            for _ in group_windows
+        ]
+        cells[0] -= {(150, r) for r in range(num_ranks)}
+        cells[1].discard((220, 2))
+        cells[2] -= {(j, r) for j in (10, 11, 12) for r in range(num_ranks)}
+        cells[3] -= {(130, r) for r in range(num_ranks)}
+        self._run(num_chunks, num_ranks, group_windows, cells, expected_hit=130)
+
+    def test_dense_deterministic_pattern(self):
+        # Wide grid with a deterministic irregular gap pattern (no RNG): drops
+        # ~1/9 of cells on an irregular stride so many window/intersection
+        # boundaries are exercised. Validated against the reference oracle.
+        num_chunks, num_ranks = 128, 3
+        group_windows = [FULL_ATTENTION_WINDOW, 2, 5, 1]
+        cells = []
+        for g in range(len(group_windows)):
+            present = {
+                (j, r)
+                for j in range(num_chunks)
+                for r in range(num_ranks)
+                if (j * 7 + r * 3 + g * 5) % 9 != 0
+            }
+            cells.append(present)
+        self._run(num_chunks, num_ranks, group_windows, cells)
diff --git a/tests/v1/distributed/test_cache_salt_l2_eviction.py b/tests/v1/distributed/test_cache_salt_l2_eviction.py
new file mode 100644
index 0000000..90fbda2
--- /dev/null
+++ b/tests/v1/distributed/test_cache_salt_l2_eviction.py
@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Integration tests for L2 eviction scoped by ``cache_salt``.
+
+Drives :class:`L2EvictionController` end-to-end against a real
+:class:`MockL2Adapter` with :class:`IsolatedLRUEvictionPolicy` and a
+:class:`QuotaManager`, covering:
+
+* over-budget salts get evicted; within-budget salts are left alone
+* unregistered salts (no quota entry) have effective limit 0 and are
+  wiped on the next eviction cycle
+* salt isolation: touching alice's keys doesn't move bob's
+"""
+
+# Standard
+import os
+import select
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.config import EvictionConfig
+from lmcache.v1.distributed.eviction import L2EvictionPolicy
+from lmcache.v1.distributed.eviction_policy.isolated_lru import (
+    IsolatedLRUEvictionPolicy,
+)
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.distributed.storage_controllers.eviction_controller import (
+    L2AdapterEvictionState,
+    L2EvictionController,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _key(chunk_id: int, cache_salt: str) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+        cache_salt=cache_salt,
+    )
+
+
+def _memory_obj(n_floats: int = 128) -> TensorMemoryObj:
+    """Small (~0.5 KB with 128 floats) tensor so quotas fit comfortably
+    inside the mock adapter's 1 MB capacity."""
+    raw = torch.empty(n_floats, dtype=torch.float32)
+    raw.fill_(1.0)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([n_floats]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=n_floats * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw, metadata, parent_allocator=None)
+
+
+def _wait_fd(fd: int, timeout: float = 5.0) -> bool:
+    poll = select.poll()
+    poll.register(fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if not events:
+        return False
+    try:
+        os.eventfd_read(fd)
+    except BlockingIOError:
+        pass
+    return True
+
+
+def _store_sync(adapter: MockL2Adapter, key: ObjectKey, obj: TensorMemoryObj):
+    """Submit a store and wait for it to land in the base-class
+    accounting (``_notify_keys_stored`` fires in ``_execute_store_in_the_loop``)."""
+    adapter.submit_store_task([key], [obj])
+    assert _wait_fd(adapter.get_store_event_fd()), "store event timed out"
+    adapter.pop_completed_store_tasks()
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def isolated_lru_setup():
+    """Mock adapter + IsolatedLRU policy + QuotaManager wired through a
+    controller — same topology as production, minus the background
+    thread. Tests drive eviction synchronously via
+    ``_check_and_evict`` so they don't race the 1-second loop."""
+    adapter_config = MockL2AdapterConfig(
+        max_size_gb=0.001,  # 1 MB — big enough for salted traffic
+        mock_bandwidth_gb=10.0,
+    )
+    adapter = MockL2Adapter(adapter_config)
+
+    policy = IsolatedLRUEvictionPolicy()
+    # Wire the adapter → policy bridge so on_keys_* updates fire on
+    # store / delete / access events. Normally StorageManager does
+    # this; the test sets up its own bridge so the controller sees
+    # accurate per-bucket LRU state.
+    adapter.register_listener(L2EvictionPolicy(policy))
+
+    eviction_config = EvictionConfig(
+        eviction_policy="IsolatedLRU",
+        trigger_watermark=0.8,
+        eviction_ratio=0.5,
+    )
+    state = L2AdapterEvictionState(
+        adapter_id=0, adapter=adapter, eviction_config=eviction_config
+    )
+    # L2AdapterEvictionState creates its own policy internally; swap in
+    # the one we made to observe it from the test side. The listener
+    # it attached is stale, but the policy reference the controller
+    # uses is the one on ``state``.
+    state.eviction_policy = policy
+
+    qm = QuotaManager()
+    controller = L2EvictionController([state], quota_manager=qm)
+    # Don't call ``controller.start()`` — the test drives
+    # ``_check_and_evict`` directly so timing is deterministic.
+
+    yield adapter, policy, qm, controller, state
+    adapter.close()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestOverQuotaEviction:
+    def test_over_budget_salt_gets_evicted(self, isolated_lru_setup):
+        """Alice exceeds 50% of her 2 KB quota (watermark=0.8) — the
+        controller evicts enough of her keys to bring her below."""
+        adapter, policy, qm, controller, state = isolated_lru_setup
+
+        # 2 KB quota; watermark 0.8 → threshold 1.6 KB; eviction
+        # ratio 0.5 → evict half of alice's keys.
+        qm.set_quota("alice", 2 * 1024)
+        qm.set_quota("bob", 10 * 1024)  # plenty of headroom
+
+        for i in range(4):
+            _store_sync(adapter, _key(i, "alice"), _memory_obj())
+        _store_sync(adapter, _key(100, "bob"), _memory_obj())
+
+        before = adapter.get_usage().bytes_by_cache_salt
+        assert before["alice"] > 0.8 * (2 * 1024)
+        assert before["bob"] < 0.8 * (10 * 1024)
+
+        controller._check_and_evict(state)
+
+        after = adapter.get_usage().bytes_by_cache_salt
+        assert after.get("alice", 0) < before["alice"], (
+            "alice's bytes should have dropped"
+        )
+        assert after["bob"] == before["bob"], (
+            "bob was within quota — nothing should have moved"
+        )
+
+    def test_unregistered_salt_gets_wiped(self, isolated_lru_setup):
+        """A salt with no quota entry is fully evicted on the next
+        cycle (allowlist semantics)."""
+        adapter, policy, qm, controller, state = isolated_lru_setup
+
+        # Only alice is registered.
+        qm.set_quota("alice", 10 * 1024)
+
+        _store_sync(adapter, _key(1, "alice"), _memory_obj())
+        _store_sync(adapter, _key(2, "stranger"), _memory_obj())
+        _store_sync(adapter, _key(3, "stranger"), _memory_obj())
+
+        controller._check_and_evict(state)
+
+        after = adapter.get_usage().bytes_by_cache_salt
+        assert "stranger" not in after, (
+            "unregistered salt should have been fully evicted"
+        )
+        assert after.get("alice", 0) > 0, "alice was under quota"
+
+    def test_under_budget_does_nothing(self, isolated_lru_setup):
+        """Nobody is over threshold → no eviction, accounting is
+        stable across the cycle."""
+        adapter, policy, qm, controller, state = isolated_lru_setup
+        qm.set_quota("alice", 10 * 1024)
+
+        _store_sync(adapter, _key(1, "alice"), _memory_obj())
+        before = dict(adapter.get_usage().bytes_by_cache_salt)
+
+        controller._check_and_evict(state)
+
+        after = dict(adapter.get_usage().bytes_by_cache_salt)
+        assert after == before
+
+
+class TestSaltIsolation:
+    def test_alice_over_quota_does_not_touch_bob(self, isolated_lru_setup):
+        """Scoped eviction — only alice's keys are candidates, even
+        though bob has some keys that are globally older."""
+        adapter, policy, qm, controller, state = isolated_lru_setup
+
+        qm.set_quota("alice", 2 * 1024)
+        qm.set_quota("bob", 10 * 1024)
+
+        # bob goes first → bob's keys are older globally.
+        for i in range(2):
+            _store_sync(adapter, _key(100 + i, "bob"), _memory_obj())
+        for i in range(4):
+            _store_sync(adapter, _key(i, "alice"), _memory_obj())
+
+        controller._check_and_evict(state)
+
+        after = adapter.get_usage().bytes_by_cache_salt
+        assert after["bob"] == 2 * 512, (
+            "bob should still have both keys — scoped eviction "
+            "shouldn't leak into his bucket"
+        )
+
+
+class TestPolicyDispatch:
+    def test_lru_policy_ignores_quota_manager(self, isolated_lru_setup):
+        """Sanity check: even if a QuotaManager is wired in, a
+        non-isolation policy falls through to the aggregate
+        watermark branch. Here that branch is a no-op (adapter well
+        under global capacity)."""
+        adapter, policy, qm, controller, state = isolated_lru_setup
+
+        # Swap the state's policy for one without isolation support.
+        # First Party
+        from lmcache.v1.distributed.eviction_policy.lru import (
+            LRUEvictionPolicy,
+        )
+
+        state.eviction_policy = LRUEvictionPolicy()
+        adapter.register_listener(L2EvictionPolicy(state.eviction_policy))
+
+        # Set a quota that would normally trigger eviction.
+        qm.set_quota("alice", 1)  # 1 byte limit
+
+        _store_sync(adapter, _key(1, "alice"), _memory_obj())
+        before = dict(adapter.get_usage().bytes_by_cache_salt)
+        controller._check_and_evict(state)
+        after = dict(adapter.get_usage().bytes_by_cache_salt)
+
+        # LRU policy doesn't look at the quota → under aggregate
+        # watermark → no eviction.
+        assert after == before
+
+    def test_isolated_lru_without_quota_manager_falls_through_to_global(
+        self, isolated_lru_setup
+    ):
+        """Defensive: IsolatedLRU configured on a controller that wasn't
+        given a QuotaManager falls through to the aggregate-watermark
+        branch. This path is unreachable through normal ``StorageManager``
+        wiring (which always creates a QuotaManager) but exists as a
+        safety fallback."""
+        adapter, policy, _qm, _controller, state = isolated_lru_setup
+
+        # Build a fresh controller without a QuotaManager.
+        no_qm_controller = L2EvictionController([state], quota_manager=None)
+
+        _store_sync(adapter, _key(1, "alice"), _memory_obj())
+        before = dict(adapter.get_usage().bytes_by_cache_salt)
+
+        # Even with IsolatedLRU policy, no quota_manager → global branch.
+        # Adapter is well under capacity → no eviction.
+        no_qm_controller._check_and_evict(state)
+
+        after = dict(adapter.get_usage().bytes_by_cache_salt)
+        assert after == before
diff --git a/tests/v1/distributed/test_dax_l2_adapter.py b/tests/v1/distributed/test_dax_l2_adapter.py
new file mode 100644
index 0000000..f29d21f
--- /dev/null
+++ b/tests/v1/distributed/test_dax_l2_adapter.py
@@ -0,0 +1,921 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the DAX MP L2 adapter.
+"""
+
+# Standard
+from typing import cast
+import select
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.internal_api import L2AdapterListener
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdaptersConfig,
+    get_registered_l2_adapter_types,
+)
+from lmcache.v1.distributed.l2_adapters.dax_l2_adapter import (
+    DaxDeviceConfig,
+    DaxL2Adapter,
+    DaxL2AdapterConfig,
+)
+from lmcache.v1.distributed.l2_adapters.reconfiguration import (
+    L2ReconfigurableAdapter,
+    L2ReconfigureError,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+_DEFAULT_SHAPE = torch.Size([2, 4, 8])
+
+
+class _RecordingListener(L2AdapterListener):
+    def __init__(self):
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        self.deleted.append(list(keys))
+
+
+def create_object_key(
+    chunk_id: int,
+    model_name: str = "test_model",
+    cache_salt: str = "",
+) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+        cache_salt=cache_salt,
+    )
+
+
+def create_memory_obj(
+    *,
+    shape: torch.Size = _DEFAULT_SHAPE,
+    dtype: torch.dtype = torch.bfloat16,
+    fill_value: float = 0,
+    fmt: MemoryFormat = MemoryFormat.KV_2LTD,
+) -> MemoryObj:
+    allocator = AdHocMemoryAllocator(device="cpu")
+    obj = allocator.allocate([shape], [dtype], fmt=fmt)
+    assert obj is not None
+    assert obj.tensor is not None
+    obj.tensor.fill_(fill_value)
+    return obj
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if not events:
+        return False
+    consume_fd(event_fd)
+    return True
+
+
+def wait_for_condition(predicate, timeout: float = 5.0, interval: float = 0.02) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(interval)
+    return False
+
+
+def make_adapter(
+    tmp_path,
+    *,
+    slot_bytes: int = 4096,
+    max_slots: int = 2,
+    num_store_workers: int = 1,
+    num_lookup_workers: int = 1,
+    num_load_workers: int = 1,
+) -> tuple[DaxL2Adapter, DaxL2AdapterConfig]:
+    device_path = tmp_path / "dax.bin"
+    arena_bytes = slot_bytes * max_slots
+    with open(device_path, "wb") as fout:
+        fout.truncate(arena_bytes)
+
+    config = DaxL2AdapterConfig(
+        devices=[
+            DaxDeviceConfig(
+                device_path=str(device_path),
+                max_dax_size_gb=arena_bytes / (1024**3),
+            )
+        ],
+        slot_bytes=slot_bytes,
+        num_store_workers=num_store_workers,
+        num_lookup_workers=num_lookup_workers,
+        num_load_workers=num_load_workers,
+    )
+    return DaxL2Adapter(config), config
+
+
+def make_hotplug_adapter(tmp_path, *, slot_bytes: int = 2048) -> DaxL2Adapter:
+    devices = []
+    for i in range(2):
+        device_path = tmp_path / f"dax_hotplug_{i}.bin"
+        with open(device_path, "wb") as fout:
+            fout.truncate(slot_bytes * 2)
+        devices.append(
+            DaxDeviceConfig(
+                device_path=str(device_path),
+                max_dax_size_gb=(slot_bytes * 2) / (1024**3),
+            )
+        )
+
+    return DaxL2Adapter(
+        DaxL2AdapterConfig(
+            devices=devices,
+            hotplug_enabled=True,
+            slot_bytes=slot_bytes,
+            num_store_workers=1,
+            num_lookup_workers=1,
+            num_load_workers=1,
+        )
+    )
+
+
+def store_and_wait(adapter: DaxL2Adapter, key: ObjectKey, obj: MemoryObj) -> None:
+    task_id = adapter.submit_store_task([key], [obj])
+    assert wait_for_event_fd(adapter.get_store_event_fd())
+    completed = adapter.pop_completed_store_tasks()
+    assert completed[task_id].is_successful()
+
+
+def bitmap_to_bools(bitmap: Bitmap, size: int) -> list[bool]:
+    return [bitmap.test(i) for i in range(size)]
+
+
+def lookup_and_wait(adapter: DaxL2Adapter, keys: list[ObjectKey]) -> list[bool]:
+    task_id = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+    assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+    bitmap = adapter.query_lookup_and_lock_result(task_id)
+    assert bitmap is not None
+    return bitmap_to_bools(bitmap, len(keys))
+
+
+def load_and_wait(
+    adapter: DaxL2Adapter,
+    keys: list[ObjectKey],
+    objs: list[MemoryObj],
+) -> list[bool]:
+    task_id = adapter.submit_load_task(keys, objs)
+    assert wait_for_event_fd(adapter.get_load_event_fd())
+    bitmap = adapter.query_load_result(task_id)
+    assert bitmap is not None
+    return bitmap_to_bools(bitmap, len(keys))
+
+
+def test_dax_adapter_registers_and_has_distinct_eventfds(tmp_path):
+    adapter, _ = make_adapter(tmp_path)
+    try:
+        assert "dax" in get_registered_l2_adapter_types()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+        assert len({store_fd, lookup_fd, load_fd}) == 3
+    finally:
+        adapter.close()
+
+
+def test_dax_hotplug_remove_migrate_preserves_loadability(tmp_path):
+    adapter = make_hotplug_adapter(tmp_path)
+    listener = _RecordingListener()
+    adapter.register_listener(listener)
+    obj = create_memory_obj(fill_value=9)
+    target = create_memory_obj(fill_value=0)
+    try:
+        key = create_object_key(80)
+        store_and_wait(adapter, key, obj)
+        source_path = adapter.hotplug_status()["devices"][0]["device_path"]
+
+        result = adapter.reconfigure(
+            "remove",
+            {
+                "device_path": source_path,
+                "mode": "migrate",
+            },
+        )
+
+        assert result["state"] == "removed"
+        assert result["moved_keys"] == 1
+        assert result["deleted_keys"] == 0
+        assert result["source_slots_freed"] == 1
+        assert listener.deleted == []
+        assert lookup_and_wait(adapter, [key]) == [True]
+        assert load_and_wait(adapter, [key], [target]) == [True]
+        assert target.tensor is not None
+        assert torch.all(target.tensor == 9)
+        adapter.submit_unlock([key])
+    finally:
+        obj.ref_count_down()
+        target.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_implements_generic_reconfigure_status(tmp_path):
+    adapter = make_hotplug_adapter(tmp_path)
+    try:
+        assert isinstance(adapter, L2ReconfigurableAdapter)
+        status = adapter.reconfigure("status", {})
+        assert status == {
+            "backend": "dax",
+            "supported_operations": ["status", "add", "remove", "resize"],
+            "status": adapter.hotplug_status(),
+        }
+    finally:
+        adapter.close()
+
+
+def test_dax_hotplug_drain_stops_new_writes_to_source_device(tmp_path):
+    adapter = make_hotplug_adapter(tmp_path)
+    obj0 = create_memory_obj(fill_value=1)
+    obj1 = create_memory_obj(fill_value=2)
+    try:
+        store_and_wait(adapter, create_object_key(81), obj0)
+        devices_before = adapter.hotplug_status()["devices"]
+        source_path = devices_before[0]["device_path"]
+        source_live_slots = devices_before[0]["live_slot_count"]
+
+        result = adapter.hotplug_remove_device(source_path, "drain")
+
+        assert result["status"] == "ok"
+        assert result["state"] == "draining"
+        store_and_wait(adapter, create_object_key(82), obj1)
+        devices = adapter.hotplug_status()["devices"]
+        assert devices[0]["live_slot_count"] == source_live_slots
+        assert devices[1]["live_slot_count"] == 1
+    finally:
+        obj0.ref_count_down()
+        obj1.ref_count_down()
+        adapter.close()
+
+
+def test_dax_hotplug_remove_blocked_restores_active_state(tmp_path):
+    adapter = make_hotplug_adapter(tmp_path)
+    obj = create_memory_obj(fill_value=5)
+    try:
+        key = create_object_key(84)
+        store_and_wait(adapter, key, obj)
+        source_path = adapter.hotplug_status()["devices"][0]["device_path"]
+        assert lookup_and_wait(adapter, [key]) == [True]
+
+        with pytest.raises(L2ReconfigureError) as exc_info:
+            adapter.hotplug_remove_device(source_path, "migrate")
+
+        assert exc_info.value.status_code == 409
+        assert adapter.hotplug_status()["devices"][0]["state"] == "active"
+        adapter.submit_unlock([key])
+    finally:
+        obj.ref_count_down()
+        adapter.close()
+
+
+def test_dax_hotplug_remove_migrate_rejects_duplicate_destination_key(tmp_path):
+    adapter = make_hotplug_adapter(tmp_path)
+    source_obj = create_memory_obj(fill_value=1)
+    duplicate_obj = create_memory_obj(fill_value=9)
+    target = create_memory_obj(fill_value=0)
+    try:
+        key = create_object_key(83)
+        store_and_wait(adapter, key, source_obj)
+        source_path = adapter.hotplug_status()["devices"][0]["device_path"]
+        destination = adapter._devices[1]
+        assert destination.core.put_many([key], [duplicate_obj]) == [True]
+
+        with pytest.raises(L2ReconfigureError) as exc_info:
+            adapter.hotplug_remove_device(source_path, "migrate")
+
+        assert exc_info.value.status_code == 409
+        assert adapter.hotplug_status()["devices"][0]["state"] == "active"
+        assert lookup_and_wait(adapter, [key]) == [True]
+        assert load_and_wait(adapter, [key], [target]) == [True]
+        assert target.tensor is not None
+        assert torch.all(target.tensor == 1)
+        adapter.submit_unlock([key])
+    finally:
+        source_obj.ref_count_down()
+        duplicate_obj.ref_count_down()
+        target.ref_count_down()
+        adapter.close()
+
+
+def test_dax_hotplug_remove_evict_notifies_logical_delete(tmp_path):
+    adapter = make_hotplug_adapter(tmp_path)
+    listener = _RecordingListener()
+    adapter.register_listener(listener)
+    obj = create_memory_obj(fill_value=1)
+    try:
+        key = create_object_key(85)
+        store_and_wait(adapter, key, obj)
+        source_path = adapter.hotplug_status()["devices"][0]["device_path"]
+
+        result = adapter.hotplug_remove_device(source_path, "evict")
+
+        assert result["deleted_keys"] == 1
+        assert result["source_slots_freed"] == 1
+        assert listener.deleted == [[key]]
+    finally:
+        obj.ref_count_down()
+        adapter.close()
+
+
+def test_dax_hotplug_add_sanitizes_mapping_errors(tmp_path):
+    adapter = DaxL2Adapter(
+        DaxL2AdapterConfig(
+            devices=[],
+            hotplug_enabled=True,
+            slot_bytes=2048,
+            num_store_workers=1,
+            num_lookup_workers=1,
+            num_load_workers=1,
+        )
+    )
+    missing_path = str(tmp_path / "missing_dax.bin")
+    try:
+        with pytest.raises(L2ReconfigureError) as exc_info:
+            adapter.hotplug_add_device(missing_path, 2048)
+
+        assert exc_info.value.status_code == 400
+        assert exc_info.value.payload == {"error": "failed to map DAX device"}
+        assert missing_path not in str(exc_info.value.payload)
+    finally:
+        adapter.close()
+
+
+def test_dax_lookup_batches_unmapped_keys_by_device(tmp_path, monkeypatch):
+    adapter = make_hotplug_adapter(tmp_path)
+    objs = [create_memory_obj(fill_value=i) for i in range(4)]
+    keys = [create_object_key(500 + i) for i in range(4)]
+    calls: list[tuple[int, int, bool]] = []
+
+    try:
+        task_id = adapter.submit_store_task(keys, objs)
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        completed = adapter.pop_completed_store_tasks()
+        assert completed[task_id].is_successful()
+
+        with adapter._device_lock:
+            adapter._key_to_device.clear()
+            for entry in adapter._devices:
+                original = entry.core.exists_many
+
+                def wrapped_exists_many(
+                    lookup_keys,
+                    lock=False,
+                    *,
+                    device_id=entry.device_id,
+                    original=original,
+                ):
+                    calls.append((device_id, len(lookup_keys), lock))
+                    return original(lookup_keys, lock=lock)
+
+                monkeypatch.setattr(entry.core, "exists_many", wrapped_exists_many)
+
+        assert lookup_and_wait(adapter, keys) == [True, True, True, True]
+
+        assert [count for _, count, _ in calls] == [4, 2]
+        assert all(lock for _, _, lock in calls)
+    finally:
+        adapter.submit_unlock(keys)
+        adapter.close()
+
+
+class _FakeReconfigurableAdapter:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, dict[str, object]]] = []
+
+    def reconfigure_status(self) -> dict:
+        return {
+            "backend": "fake",
+            "supported_operations": ["flip"],
+            "status": {"ready": True},
+        }
+
+    def reconfigure(self, operation: str, payload: dict[str, object]) -> dict:
+        self.calls.append((operation, payload))
+        return {"status": "ok", "operation": operation, "payload": payload}
+
+
+class _SerdeLikeWrapper:
+    def __init__(self, inner_adapter: _FakeReconfigurableAdapter) -> None:
+        self.inner_adapter = inner_adapter
+
+
+class _FakeAdapterDescriptor:
+    def __init__(self, type_name: str) -> None:
+        self.type_name = type_name
+
+
+def test_storage_manager_routes_generic_l2_reconfigure_to_adapter():
+    sm = StorageManager.__new__(StorageManager)
+    adapter = _FakeReconfigurableAdapter()
+    sm._adapters_lock = threading.Lock()
+    sm._l2_adapters = {0: cast(L2AdapterInterface, adapter)}
+
+    result = sm.reconfigure_l2_adapter(0, "flip", {"enabled": True})
+
+    assert result == {
+        "status": "ok",
+        "operation": "flip",
+        "payload": {"enabled": True},
+        "adapter_index": 0,
+    }
+    assert adapter.calls == [("flip", {"enabled": True})]
+
+
+def test_storage_manager_finds_serde_wrapped_reconfigurable_adapter():
+    sm = StorageManager.__new__(StorageManager)
+    sm._adapters_lock = threading.Lock()
+    sm._l2_adapters = {
+        0: cast(L2AdapterInterface, _SerdeLikeWrapper(_FakeReconfigurableAdapter()))
+    }
+    sm._adapter_descriptors = {0: _FakeAdapterDescriptor("configured_fake")}
+
+    status = sm.get_l2_adapter_reconfigure_status()
+
+    assert status["enabled"] is True
+    assert status["num_adapters"] == 1
+    assert status["adapters"][0]["backend"] == "configured_fake"
+    assert status["adapters"][0]["adapter_index"] == 0
+    assert status["adapters"][0]["l2_adapter_index"] == 0
+
+
+def test_dax_adapter_store_lookup_load_and_one_shot_results(tmp_path):
+    adapter, _ = make_adapter(tmp_path, slot_bytes=2048, max_slots=4)
+    listener = _RecordingListener()
+    adapter.register_listener(listener)
+
+    obj0 = create_memory_obj(fill_value=3)
+    obj2 = create_memory_obj(fill_value=7)
+    miss_target = create_memory_obj(fill_value=0)
+    load_target0 = create_memory_obj(fill_value=0)
+    load_target2 = create_memory_obj(fill_value=0)
+    try:
+        key0 = create_object_key(10)
+        key1 = create_object_key(11)
+        key2 = create_object_key(12)
+
+        store_task = adapter.submit_store_task([key0, key2], [obj0, obj2])
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        completed = adapter.pop_completed_store_tasks()
+        assert completed[store_task].is_successful()
+        assert adapter.pop_completed_store_tasks() == {}
+        assert listener.stored == [[key0, key2]]
+
+        lookup_task = adapter.submit_lookup_and_lock_task(
+            [key0, key1, key2], _EMPTY_LAYOUT
+        )
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_task)
+        assert lookup_bitmap is not None
+        assert bitmap_to_bools(lookup_bitmap, 3) == [True, False, True]
+        assert adapter.query_lookup_and_lock_result(lookup_task) is None
+
+        load_task = adapter.submit_load_task(
+            [key0, key1, key2],
+            [load_target0, miss_target, load_target2],
+        )
+        assert wait_for_event_fd(adapter.get_load_event_fd())
+        load_bitmap = adapter.query_load_result(load_task)
+        assert load_bitmap is not None
+        assert bitmap_to_bools(load_bitmap, 3) == [True, False, True]
+        assert adapter.query_load_result(load_task) is None
+
+        assert load_target0.tensor is not None
+        assert load_target2.tensor is not None
+        assert miss_target.tensor is not None
+        assert torch.all(load_target0.tensor == 3)
+        assert torch.all(load_target2.tensor == 7)
+        assert torch.all(miss_target.tensor == 0)
+        assert listener.accessed == [[key0, key2]]
+    finally:
+        obj0.ref_count_down()
+        obj2.ref_count_down()
+        miss_target.ref_count_down()
+        load_target0.ref_count_down()
+        load_target2.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_unlock_refcount_and_delete_skips_locked_keys(tmp_path):
+    adapter, _ = make_adapter(tmp_path, slot_bytes=2048, max_slots=2)
+    listener = _RecordingListener()
+    adapter.register_listener(listener)
+
+    obj = create_memory_obj(fill_value=5)
+    try:
+        key = create_object_key(20)
+        store_and_wait(adapter, key, obj)
+
+        first_lookup = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        assert adapter.query_lookup_and_lock_result(first_lookup) is not None
+
+        second_lookup = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        assert adapter.query_lookup_and_lock_result(second_lookup) is not None
+
+        adapter.delete([key])
+        assert listener.deleted == []
+        assert adapter.report_status()["locked_key_count"] == 1
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        assert listener.deleted == []
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        assert listener.deleted == [[key]]
+    finally:
+        obj.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_usage_and_status_track_pending_free_slots(tmp_path):
+    adapter, _ = make_adapter(tmp_path, slot_bytes=2048, max_slots=2)
+    obj = create_memory_obj(fill_value=9)
+    try:
+        assert adapter.supports_global_eviction is True
+        key = create_object_key(30)
+        store_and_wait(adapter, key, obj)
+
+        reservations, hits = adapter._core.reserve_reads([key], prefix_only=False)
+        assert hits == [True]
+
+        adapter.delete([key])
+        usage = adapter.get_usage()
+        assert usage.usage_fraction == pytest.approx(0.5)
+        assert usage.total_bytes_used == 2048
+
+        status = adapter.report_status()
+        assert status["live_slot_count"] == 1
+        assert status["borrowed_slot_count"] == 1
+        assert status["locked_key_count"] == 0
+        assert status["inflight_store_tasks"] == 0
+        assert status["inflight_lookup_tasks"] == 0
+        assert status["inflight_load_tasks"] == 0
+        _, usage_after_eviction = adapter._core.usage()
+        assert usage_after_eviction == pytest.approx(0.0)
+        assert status["supports_restart_recovery"] is False
+
+        adapter._core.finalize_reads(reservations, set())
+        assert adapter.get_usage().usage_fraction == pytest.approx(0.0)
+        assert adapter._core.usage()[1] == pytest.approx(0.0)
+    finally:
+        obj.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_full_arena_does_not_evict_internally(tmp_path):
+    adapter, _ = make_adapter(tmp_path, slot_bytes=2048, max_slots=2)
+    listener = _RecordingListener()
+    adapter.register_listener(listener)
+
+    obj0 = create_memory_obj(fill_value=1)
+    obj1 = create_memory_obj(fill_value=2)
+    obj2 = create_memory_obj(fill_value=3)
+    try:
+        key0 = create_object_key(31)
+        key1 = create_object_key(32)
+        key2 = create_object_key(33)
+
+        store_and_wait(adapter, key0, obj0)
+        store_and_wait(adapter, key1, obj1)
+
+        task_id = adapter.submit_store_task([key2], [obj2])
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        completed = adapter.pop_completed_store_tasks()
+        assert not completed[task_id].is_successful()
+        assert listener.stored == [[key0], [key1]]
+        assert adapter.get_usage().usage_fraction == pytest.approx(1.0)
+
+        lookup_task = adapter.submit_lookup_and_lock_task(
+            [key0, key1, key2], _EMPTY_LAYOUT
+        )
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        bitmap = adapter.query_lookup_and_lock_result(lookup_task)
+        assert bitmap is not None
+        assert bitmap_to_bools(bitmap, 3) == [True, True, False]
+        adapter.submit_unlock([key0, key1])
+    finally:
+        obj0.ref_count_down()
+        obj1.ref_count_down()
+        obj2.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_usage_tracks_cache_salt_by_slot(tmp_path):
+    adapter, _ = make_adapter(tmp_path, slot_bytes=2048, max_slots=4)
+
+    obj0 = create_memory_obj(fill_value=1)
+    obj1 = create_memory_obj(fill_value=2)
+    obj2 = create_memory_obj(fill_value=3)
+    try:
+        alice0 = create_object_key(34, cache_salt="alice")
+        bob = create_object_key(35, cache_salt="bob")
+        alice1 = create_object_key(36, cache_salt="alice")
+
+        store_and_wait(adapter, alice0, obj0)
+        store_and_wait(adapter, bob, obj1)
+        store_and_wait(adapter, alice1, obj2)
+
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 2048 * 3
+        assert dict(usage.bytes_by_cache_salt) == {
+            "alice": 2048 * 2,
+            "bob": 2048,
+        }
+
+        adapter.delete([alice0])
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 2048 * 2
+        assert dict(usage.bytes_by_cache_salt) == {
+            "alice": 2048,
+            "bob": 2048,
+        }
+
+        adapter.delete([alice1])
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 2048
+        assert dict(usage.bytes_by_cache_salt) == {"bob": 2048}
+    finally:
+        obj0.ref_count_down()
+        obj1.ref_count_down()
+        obj2.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_close_waits_for_inflight_tasks(tmp_path, monkeypatch):
+    adapter, _ = make_adapter(tmp_path, slot_bytes=2048, max_slots=2)
+    obj = create_memory_obj(fill_value=2)
+    target = create_memory_obj(fill_value=0)
+    try:
+        key = create_object_key(40)
+        store_and_wait(adapter, key, obj)
+
+        load_started = threading.Event()
+        allow_load = threading.Event()
+        close_returned = threading.Event()
+        original_load = adapter._core.load_many_into
+
+        def _blocking_load_many_into(keys, objs):
+            load_started.set()
+            assert allow_load.wait(timeout=2)
+            return original_load(keys, objs)
+
+        monkeypatch.setattr(adapter._core, "load_many_into", _blocking_load_many_into)
+
+        adapter.submit_load_task([key], [target])
+        assert load_started.wait(timeout=2)
+
+        closer = threading.Thread(
+            target=lambda: (adapter.close(), close_returned.set())
+        )
+        closer.start()
+        time.sleep(0.05)
+        assert not close_returned.is_set()
+
+        allow_load.set()
+        closer.join(timeout=2)
+        assert not closer.is_alive()
+        assert close_returned.is_set()
+    finally:
+        obj.ref_count_down()
+        target.ref_count_down()
+        adapter.close()
+
+
+def test_dax_adapter_restart_is_volatile_only(tmp_path):
+    adapter, config = make_adapter(tmp_path, slot_bytes=2048, max_slots=2)
+    obj = create_memory_obj(fill_value=4)
+    try:
+        key = create_object_key(50)
+        store_and_wait(adapter, key, obj)
+        adapter.close()
+
+        reopened = DaxL2Adapter(config)
+        try:
+            lookup_task = reopened.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+            assert wait_for_event_fd(reopened.get_lookup_and_lock_event_fd())
+            bitmap = reopened.query_lookup_and_lock_result(lookup_task)
+            assert bitmap is not None
+            assert bitmap_to_bools(bitmap, 1) == [False]
+        finally:
+            reopened.close()
+    finally:
+        obj.ref_count_down()
+        adapter.close()
+
+
+def test_storage_manager_dax_adapter_roundtrip(tmp_path):
+    shape = torch.Size([2, 4, 8])
+    dtype = torch.bfloat16
+    slot_bytes = shape.numel() * dtype.itemsize
+
+    device_path = tmp_path / "sm_dax.bin"
+    with open(device_path, "wb") as fout:
+        fout.truncate(slot_bytes * 4)
+
+    storage_config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=1 << 20,
+                use_lazy=False,
+                init_size_in_bytes=1 << 20,
+                align_bytes=0x1000,
+            ),
+            write_ttl_seconds=60,
+            read_ttl_seconds=60,
+        ),
+        eviction_config=EvictionConfig(eviction_policy="noop"),
+        l2_adapter_config=L2AdaptersConfig(
+            [
+                DaxL2AdapterConfig(
+                    devices=[
+                        DaxDeviceConfig(
+                            device_path=str(device_path),
+                            max_dax_size_gb=(slot_bytes * 4) / (1024**3),
+                        )
+                    ],
+                    slot_bytes=slot_bytes,
+                )
+            ]
+        ),
+        store_policy="skip_l1",
+    )
+
+    layout = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+    key = create_object_key(60)
+    sm = StorageManager(storage_config)
+
+    try:
+        adapter = sm._l2_adapters[0]
+        assert isinstance(adapter, DaxL2Adapter)
+
+        reserved = sm.reserve_write([key], layout, mode="new")
+        assert key in reserved
+        assert reserved[key].tensor is not None
+        reserved[key].tensor.fill_(11)
+        sm.finish_write([key])
+
+        assert wait_for_condition(
+            lambda: (
+                sm.report_status()["l1_manager"]["total_object_count"] == 0
+                and adapter.get_usage().usage_fraction > 0
+            ),
+            timeout=5.0,
+        )
+
+        handle = sm.submit_prefetch_task([key], layout)
+        assert wait_for_condition(
+            lambda: sm.query_prefetch_lookup_hits(handle) is not None,
+            timeout=5.0,
+        )
+        lookup_hits = sm.query_prefetch_lookup_hits(handle)
+        assert lookup_hits == 1
+
+        final_result: dict[str, int | None] = {"value": None}
+
+        def _capture_prefetch_result() -> bool:
+            result = sm.query_prefetch_status(handle)
+            if result is None:
+                return False
+            final_result["value"] = result.count_leading_ones()
+            return True
+
+        assert wait_for_condition(_capture_prefetch_result, timeout=5.0)
+        final_hits = final_result["value"]
+        assert final_hits == 1
+
+        with sm.read_prefetched_results([key]) as results:
+            assert results is not None
+            assert len(results) == 1
+            assert results[0].tensor is not None
+            assert torch.all(results[0].tensor == 11)
+
+        assert adapter.report_status()["locked_key_count"] == 0
+        assert sm._l1_manager.delete([key])[key] == L1Error.KEY_IS_LOCKED
+
+        sm.finish_read_prefetched([key])
+        assert sm._l1_manager.delete([key])[key] == L1Error.KEY_NOT_EXIST
+    finally:
+        sm.close()
+
+
+def test_storage_manager_dax_adapter_uses_global_l2_eviction(tmp_path):
+    shape = torch.Size([2, 4, 8])
+    dtype = torch.bfloat16
+    slot_bytes = shape.numel() * dtype.itemsize
+
+    device_path = tmp_path / "sm_dax_eviction.bin"
+    with open(device_path, "wb") as fout:
+        fout.truncate(slot_bytes * 2)
+
+    dax_config = DaxL2AdapterConfig(
+        devices=[
+            DaxDeviceConfig(
+                device_path=str(device_path),
+                max_dax_size_gb=(slot_bytes * 2) / (1024**3),
+            )
+        ],
+        slot_bytes=slot_bytes,
+    )
+    dax_config.eviction_config = EvictionConfig(
+        eviction_policy="LRU",
+        trigger_watermark=0.5,
+        eviction_ratio=0.5,
+    )
+
+    storage_config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=1 << 20,
+                use_lazy=False,
+                init_size_in_bytes=1 << 20,
+                align_bytes=0x1000,
+            ),
+            write_ttl_seconds=60,
+            read_ttl_seconds=60,
+        ),
+        eviction_config=EvictionConfig(eviction_policy="noop"),
+        l2_adapter_config=L2AdaptersConfig([dax_config]),
+        store_policy="skip_l1",
+    )
+
+    layout = MemoryLayoutDesc(shapes=[shape], dtypes=[dtype])
+    sm = StorageManager(storage_config)
+
+    try:
+        sm._l2_eviction_controller.stop()
+        adapter = sm._l2_adapters[0]
+        assert isinstance(adapter, DaxL2Adapter)
+        assert adapter.supports_global_eviction is True
+        assert len(sm._l2_eviction_controller._adapter_states) == 1
+
+        key0 = create_object_key(70)
+        key1 = create_object_key(71)
+        key2 = create_object_key(72)
+
+        def _write_key(key: ObjectKey, fill_value: int, usage_fraction: float) -> None:
+            reserved = sm.reserve_write([key], layout, mode="new")
+            assert key in reserved
+            assert reserved[key].tensor is not None
+            reserved[key].tensor.fill_(fill_value)
+            sm.finish_write([key])
+            assert wait_for_condition(
+                lambda: (
+                    adapter.get_usage().usage_fraction == pytest.approx(usage_fraction)
+                ),
+                timeout=5.0,
+            )
+
+        _write_key(key0, 1, 0.5)
+        _write_key(key1, 2, 1.0)
+        assert adapter.get_usage().usage_fraction == pytest.approx(1.0)
+
+        eviction_state = sm._l2_eviction_controller._adapter_states[0]
+        sm._l2_eviction_controller._check_and_evict(eviction_state)
+        assert adapter.get_usage().usage_fraction == pytest.approx(0.5)
+
+        hits = adapter._core.exists_many([key0, key1], lock=True)
+        assert hits == [False, True]
+        adapter.submit_unlock([key1])
+
+        _write_key(key2, 3, 1.0)
+        assert adapter.get_usage().usage_fraction == pytest.approx(1.0)
+    finally:
+        sm.close()
diff --git a/tests/v1/distributed/test_devdax_l1_allocator.py b/tests/v1/distributed/test_devdax_l1_allocator.py
new file mode 100644
index 0000000..fb5d2d4
--- /dev/null
+++ b/tests/v1/distributed/test_devdax_l1_allocator.py
@@ -0,0 +1,607 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for Device-DAX-backed L1 allocation.
+
+The tests use a regular mmap-able file rather than requiring real
+``/dev/dax`` hardware. That exercises the allocator contract and storage
+manager wiring while keeping CI portable.
+"""
+
+# Standard
+from typing import Any, cast
+import argparse
+import gc
+import json
+import os
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+    add_storage_manager_args,
+    parse_args_to_config,
+)
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    L2AdaptersConfig,
+    get_type_name_for_config,
+)
+from lmcache.v1.distributed.memory_manager.devdax_l1_memory_manager import (
+    DevDaxL1MemoryManager,
+)
+from lmcache.v1.memory_allocators.devdax_memory_allocator import DevDaxMemoryAllocator
+from lmcache.v1.multiprocess.config import add_mp_server_args
+from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+import lmcache.v1.memory_management as memory_management
+
+
+def _make_mmap_file(
+    tmp_path, size: int = 4 * 1024 * 1024, name: str = "l1-devdax-test.bin"
+) -> str:
+    path = tmp_path / name
+    with open(path, "wb") as f:
+        f.truncate(size)
+    return str(path)
+
+
+def _key(seed: int = 0) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=seed.to_bytes(4, "big") + b"\0" * 28,
+        model_name="devdax-l1-test",
+        kv_rank=0,
+    )
+
+
+def _layout(num_bytes: int = 4096) -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(shapes=[torch.Size([num_bytes])], dtypes=[torch.uint8])
+
+
+def _parse_mp_storage_args(args: list[str]) -> StorageManagerConfig:
+    parser = argparse.ArgumentParser()
+    add_mp_server_args(parser)
+    add_storage_manager_args(parser)
+    return parse_args_to_config(parser.parse_args(args))
+
+
+class _FakeMooncakeL2Config:
+    def __init__(self, setup_config: dict[str, str]) -> None:
+        self.setup_config = setup_config
+
+
+class _FakeExt:
+    is_pin_supported = True
+
+    def __init__(self, fake_runtime: "_FakeCudaRuntime") -> None:
+        self._runtime = fake_runtime
+
+    def pin_memory(self, ptr: int, size: int, flags: int = 0) -> bool:
+        self._runtime.register_calls.append((ptr, size, flags))
+        return self._runtime.register_error == 0
+
+    def unpin_memory(self, ptr: int) -> bool:
+        self._runtime.unregister_calls.append(ptr)
+        return True
+
+
+class _FakeCudaRuntime:
+    def __init__(self, register_error: int = 0) -> None:
+        self.register_error = register_error
+        self.register_calls: list[tuple[int, int, int]] = []
+        self.unregister_calls: list[int] = []
+        self.synchronize_calls = 0
+        self.ext = _FakeExt(self)
+
+    def is_available(self) -> bool:
+        return True
+
+    def synchronize(self) -> None:
+        self.synchronize_calls += 1
+
+    def cudart(self) -> "_FakeCudaRuntime":
+        return self
+
+    def cudaHostRegister(self, ptr: int, size: int, flags: int) -> int:
+        self.register_calls.append((ptr, size, flags))
+        return self.register_error
+
+    def cudaHostUnregister(self, ptr: int) -> int:
+        self.unregister_calls.append(ptr)
+        return 0
+
+
+def _hybrid_storage_config(path: str, adapter_config: object) -> StorageManagerConfig:
+    config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=1024 * 1024,
+                use_lazy=False,
+                shm_name="",
+                devdax_path=path,
+                devdax_size_in_bytes=1024 * 1024,
+            )
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(
+            adapters=[cast(L2AdapterConfigBase, adapter_config)]
+        ),
+    )
+    return config
+
+
+def test_devdax_config_rejects_lazy_allocation(tmp_path):
+    path = _make_mmap_file(tmp_path)
+
+    with pytest.raises(ValueError, match="--no-l1-use-lazy"):
+        L1MemoryManagerConfig(
+            size_in_bytes=1024 * 1024,
+            use_lazy=True,
+            shm_name="",
+            devdax_path=path,
+        )
+
+
+def test_devdax_config_rejects_shm(tmp_path):
+    path = _make_mmap_file(tmp_path)
+
+    with pytest.raises(ValueError, match="--shm-name"):
+        L1MemoryManagerConfig(
+            size_in_bytes=1024 * 1024,
+            use_lazy=False,
+            shm_name="lmcache_l1_pool_test",
+            devdax_path=path,
+            devdax_size_in_bytes=2 * 1024 * 1024,
+        )
+
+
+def test_devdax_config_accepts_explicit_lazy_and_shm_disable(tmp_path):
+    path = _make_mmap_file(tmp_path)
+
+    cfg = L1MemoryManagerConfig(
+        size_in_bytes=1024 * 1024,
+        use_lazy=False,
+        shm_name="",
+        devdax_path=path,
+    )
+
+    assert cfg.devdax_path == path
+    assert cfg.use_lazy is False
+    assert cfg.shm_name == ""
+
+
+@pytest.mark.parametrize(
+    ("adapter_name", "adapter_config"),
+    [
+        ("nixl_store", object()),
+        ("nixl_store_dynamic", object()),
+        ("mooncake_store", _FakeMooncakeL2Config({"protocol": "rdma"})),
+    ],
+)
+def test_devdax_overflow_rejects_single_region_l2_adapters(
+    tmp_path, monkeypatch, adapter_name, adapter_config
+):
+    path = _make_mmap_file(tmp_path)
+    monkeypatch.setattr(
+        "lmcache.v1.distributed.config.get_type_name_for_config",
+        lambda _: adapter_name,
+    )
+
+    with pytest.raises(ValueError, match=adapter_name):
+        _hybrid_storage_config(path, adapter_config)
+
+
+def test_devdax_overflow_allows_mooncake_without_rdma(tmp_path, monkeypatch):
+    path = _make_mmap_file(tmp_path)
+    monkeypatch.setattr(
+        "lmcache.v1.distributed.config.get_type_name_for_config",
+        lambda _: "mooncake_store",
+    )
+
+    config = _hybrid_storage_config(path, _FakeMooncakeL2Config({"protocol": "tcp"}))
+
+    assert config.l1_manager_config.memory_config.devdax_size_in_bytes == 1024 * 1024
+
+
+def test_devdax_allocator_uses_mmap_backing_file(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    allocator = DevDaxMemoryAllocator(
+        size=1024 * 1024,
+        device_path=path,
+        align_bytes=4096,
+    )
+
+    objs = allocator.batched_allocate(torch.Size([4096]), torch.uint8, 2)
+    assert objs is not None
+    first = objs[0]
+    assert first.data_ptr == allocator.buffer.data_ptr()
+    assert first.shm_offset == 0
+
+    first.raw_tensor.fill_(0x5A)
+    allocator.batched_free(objs)
+    del first
+    del objs
+    gc.collect()
+    allocator.close()
+
+    with open(path, "rb") as f:
+        assert f.read(4096) == bytes([0x5A]) * 4096
+
+
+def test_devdax_allocator_registers_cuda_host_mapping(tmp_path, monkeypatch):
+    path = _make_mmap_file(tmp_path)
+    cuda_runtime = _FakeCudaRuntime()
+    monkeypatch.setattr(memory_management, "torch_device_type", "cuda")
+    monkeypatch.setattr(memory_management, "torch_dev", cuda_runtime)
+    monkeypatch.setattr(memory_management, "current_device_spec", cuda_runtime.ext)
+
+    allocator = DevDaxMemoryAllocator(
+        size=1024 * 1024,
+        device_path=path,
+        align_bytes=4096,
+    )
+    ptr = allocator.buffer.data_ptr()
+
+    assert cuda_runtime.register_calls == [(ptr, 1024 * 1024, 0)]
+    allocator.close()
+    assert cuda_runtime.unregister_calls == [ptr]
+
+
+def test_devdax_allocator_falls_back_when_cuda_host_register_fails(
+    tmp_path, monkeypatch
+):
+    path = _make_mmap_file(tmp_path)
+    cuda_runtime = _FakeCudaRuntime(register_error=1)
+    monkeypatch.setattr(memory_management, "torch_device_type", "cuda")
+    monkeypatch.setattr(memory_management, "torch_dev", cuda_runtime)
+    monkeypatch.setattr(memory_management, "current_device_spec", cuda_runtime.ext)
+
+    allocator = DevDaxMemoryAllocator(
+        size=1024 * 1024,
+        device_path=path,
+        align_bytes=4096,
+    )
+    obj = allocator.allocate(torch.Size([4096]), torch.uint8)
+
+    assert cuda_runtime.register_calls == [
+        (allocator.buffer.data_ptr(), 1024 * 1024, 0)
+    ]
+    assert cuda_runtime.unregister_calls == []
+    assert obj is not None
+    allocator.free(obj)
+    del obj
+    gc.collect()
+    allocator.close()
+    assert cuda_runtime.unregister_calls == []
+
+
+def test_devdax_close_failure_preserves_allocator_state(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    allocator = DevDaxMemoryAllocator(
+        size=1024 * 1024,
+        device_path=path,
+        align_bytes=4096,
+    )
+    obj = allocator.allocate(torch.Size([4096]), torch.uint8)
+    assert obj is not None
+
+    with pytest.raises(BufferError):
+        allocator.close()
+
+    assert allocator.devdax_allocator is not None
+    assert allocator.devdax_buffer.numel() == 1024 * 1024
+
+    allocator.free(obj)
+    del obj
+    gc.collect()
+    allocator.close()
+
+
+def test_l1_manager_round_trip_on_devdax_mapping(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    cfg = L1ManagerConfig(
+        memory_config=L1MemoryManagerConfig(
+            size_in_bytes=1024 * 1024,
+            use_lazy=False,
+            shm_name="",
+            devdax_path=path,
+        )
+    )
+    manager = L1Manager(cfg)
+    key = _key(1)
+
+    write = manager.reserve_write([key], [False], _layout())
+    assert write[key][0] == L1Error.SUCCESS
+    obj = write[key][1]
+    assert obj is not None
+    obj.tensor.fill_(0x23)
+    assert manager.finish_write([key])[key] == L1Error.SUCCESS
+
+    read = manager.reserve_read([key])
+    assert read[key][0] == L1Error.SUCCESS
+    read_obj = read[key][1]
+    assert read_obj is not None
+    assert int(read_obj.tensor[0]) == 0x23
+    assert manager.finish_read([key])[key] == L1Error.SUCCESS
+
+    del write
+    del read
+    del obj
+    del read_obj
+    gc.collect()
+    manager.close()
+
+    with open(path, "rb") as f:
+        assert f.read(1) == bytes([0x23])
+
+
+def test_devdax_l1_memory_manager_spills_from_dram_to_devdax(tmp_path):
+    path = _make_mmap_file(tmp_path, size=8192)
+    manager = DevDaxL1MemoryManager(
+        L1MemoryManagerConfig(
+            size_in_bytes=8192,
+            use_lazy=False,
+            shm_name="",
+            align_bytes=4096,
+            devdax_path=path,
+            devdax_size_in_bytes=8192,
+        )
+    )
+
+    error, objs = manager.allocate(_layout(4096), count=3)
+
+    assert error == L1Error.SUCCESS
+    assert len(objs) == 3
+    assert isinstance(manager._allocator, DevDaxMemoryAllocator)
+    assert manager._allocator.local_allocator is not None
+    assert objs[0].parent() is manager._allocator.local_allocator
+    assert objs[1].parent() is manager._allocator.local_allocator
+    assert objs[2].parent() is manager._allocator
+    assert objs[0].data_ptr == manager._allocator.local_allocator.buffer.data_ptr()
+    assert (
+        objs[1].data_ptr == manager._allocator.local_allocator.buffer.data_ptr() + 4096
+    )
+    assert objs[2].data_ptr == manager._allocator.devdax_buffer.data_ptr()
+    used, total = manager.get_memory_usage()
+    assert used == 3 * 4096
+    assert total == 4 * 4096
+
+    objs[2].raw_tensor.fill_(0x6D)
+    manager.free(objs)
+    used, total = manager.get_memory_usage()
+    assert used == 0
+    assert total == 4 * 4096
+    manager.close()
+
+    with open(path, "rb") as f:
+        assert f.read(4096) == bytes([0x6D]) * 4096
+
+
+def test_devdax_l1_memory_manager_reports_devdax_desc(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    manager = DevDaxL1MemoryManager(
+        L1MemoryManagerConfig(
+            size_in_bytes=1024 * 1024,
+            use_lazy=False,
+            shm_name="",
+            devdax_path=path,
+        )
+    )
+
+    desc = manager.get_l1_memory_desc()
+    used, total = manager.get_memory_usage()
+
+    assert desc.ptr != 0
+    assert desc.size == 1024 * 1024
+    assert desc.align_bytes == 4096
+    assert used == 0
+    assert total == 1024 * 1024
+    manager.close()
+
+
+def test_cli_parses_l1_devdax_path(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    config = _parse_mp_storage_args(
+        [
+            "--l1-size-gb",
+            "1",
+            "--eviction-policy",
+            "LRU",
+            "--no-l1-use-lazy",
+            "--shm-name",
+            "",
+            "--l1-devdax-path",
+            path,
+        ]
+    )
+
+    mem_cfg = config.l1_manager_config.memory_config
+    assert mem_cfg.devdax_path == path
+    assert mem_cfg.use_lazy is False
+    assert mem_cfg.shm_name == ""
+
+
+def test_cli_rejects_devdax_l1_with_gds_l1(tmp_path):
+    path = _make_mmap_file(tmp_path)
+
+    with pytest.raises(ValueError, match="gds-l1-path"):
+        _parse_mp_storage_args(
+            [
+                "--l1-size-gb",
+                "1",
+                "--eviction-policy",
+                "LRU",
+                "--no-l1-use-lazy",
+                "--shm-name",
+                "",
+                "--l1-devdax-path",
+                path,
+                "--gds-l1-path",
+                str(tmp_path),
+            ]
+        )
+
+
+def test_cli_infers_l1_devdax_overflow_from_registered_dax_adapter(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    config = _parse_mp_storage_args(
+        [
+            "--l1-size-gb",
+            "1",
+            "--eviction-policy",
+            "LRU",
+            "--no-l1-use-lazy",
+            "--shm-name",
+            "",
+            "--l1-devdax-path",
+            path,
+            "--l2-adapter",
+            ('{"type":"dax","device_path":"%s","max_dax_size_gb":2,"slot_bytes":4096}')
+            % path,
+        ]
+    )
+
+    mem_cfg = config.l1_manager_config.memory_config
+    assert mem_cfg.size_in_bytes == 1 << 30
+    assert mem_cfg.devdax_path == path
+    assert mem_cfg.devdax_size_in_bytes == 2 << 30
+    assert mem_cfg.use_lazy is False
+    assert mem_cfg.shm_name == ""
+    assert config.l2_adapter_config.adapters == []
+
+
+@pytest.mark.parametrize(
+    ("adapter_spec", "expected_adapter_type"),
+    [
+        (
+            {
+                "type": "raw_block",
+                "device_path": "rawblock-l2.bin",
+                "slot_bytes": 8192,
+                "capacity_bytes": 16384,
+                "meta_total_bytes": 4096,
+                "use_odirect": False,
+                "meta_enable_periodic": False,
+                "load_checkpoint_on_init": False,
+                "meta_verify_on_load": False,
+            },
+            "raw_block",
+        ),
+    ],
+)
+def test_cli_hybrid_l1_keeps_ordinary_l2_adapters(
+    tmp_path, adapter_spec, expected_adapter_type
+):
+    path = _make_mmap_file(tmp_path)
+    adapter_spec = {
+        key: str(tmp_path / value) if key in ("base_path", "device_path") else value
+        for key, value in adapter_spec.items()
+    }
+
+    config = _parse_mp_storage_args(
+        [
+            "--l1-size-gb",
+            "1",
+            "--eviction-policy",
+            "LRU",
+            "--no-l1-use-lazy",
+            "--shm-name",
+            "",
+            "--l1-devdax-path",
+            path,
+            "--l2-adapter",
+            json.dumps(
+                {
+                    "type": "dax",
+                    "device_path": path,
+                    "max_dax_size_gb": 2,
+                    "slot_bytes": 4096,
+                }
+            ),
+            "--l2-adapter",
+            json.dumps(adapter_spec),
+        ]
+    )
+
+    mem_cfg = config.l1_manager_config.memory_config
+    assert mem_cfg.devdax_size_in_bytes == 2 << 30
+    assert len(config.l2_adapter_config.adapters) == 1
+    assert (
+        get_type_name_for_config(config.l2_adapter_config.adapters[0])
+        == expected_adapter_type
+    )
+
+
+def test_cli_hybrid_l1_splits_matching_dax_device_and_keeps_other_l2(tmp_path):
+    l1_dax_path = _make_mmap_file(tmp_path, name="l1-devdax.bin")
+    l2_dax_path = _make_mmap_file(tmp_path, name="l2-devdax.bin")
+
+    config = _parse_mp_storage_args(
+        [
+            "--l1-size-gb",
+            "1",
+            "--eviction-policy",
+            "LRU",
+            "--no-l1-use-lazy",
+            "--shm-name",
+            "",
+            "--l1-devdax-path",
+            l1_dax_path,
+            "--l2-adapter",
+            json.dumps(
+                {
+                    "type": "dax",
+                    "devices": [
+                        {"device_path": l1_dax_path, "max_dax_size_gb": 2},
+                        {"device_path": l2_dax_path, "max_dax_size_gb": 3},
+                    ],
+                    "slot_bytes": 4096,
+                    "hotplug_enabled": True,
+                    "num_store_workers": 2,
+                    "num_lookup_workers": 3,
+                    "num_load_workers": 4,
+                }
+            ),
+        ]
+    )
+
+    mem_cfg = config.l1_manager_config.memory_config
+    assert mem_cfg.devdax_size_in_bytes == 2 << 30
+    assert len(config.l2_adapter_config.adapters) == 1
+
+    dax_adapter = cast(Any, config.l2_adapter_config.adapters[0])
+    assert get_type_name_for_config(dax_adapter) == "dax"
+    assert [device.device_path for device in dax_adapter.devices] == [l2_dax_path]
+    assert dax_adapter.max_dax_size_gb == 3
+    assert dax_adapter.hotplug_enabled is True
+    assert dax_adapter.num_store_workers == 2
+    assert dax_adapter.num_lookup_workers == 3
+    assert dax_adapter.num_load_workers == 4
+
+
+def test_devdax_l1_does_not_advertise_shm_pool(tmp_path):
+    path = _make_mmap_file(tmp_path)
+    config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=1024 * 1024,
+                use_lazy=False,
+                shm_name="",
+                devdax_path=path,
+            )
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+    context = MPCacheServerContext(config)
+
+    try:
+        assert context.shm_pool_info == {"shm_name": "", "pool_size": 0}
+        assert os.path.exists(path)
+    finally:
+        context.storage_manager.close()
diff --git a/tests/v1/distributed/test_distributed_storage_manager.py b/tests/v1/distributed/test_distributed_storage_manager.py
new file mode 100644
index 0000000..6617710
--- /dev/null
+++ b/tests/v1/distributed/test_distributed_storage_manager.py
@@ -0,0 +1,904 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for StorageManager.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchMode,
+    TrimPolicy,
+)
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdaptersConfig,
+)
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import MockL2AdapterConfig
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBusConfig, init_event_bus
+
+try:
+    # First Party
+    from lmcache.v1.distributed.storage_manager import StorageManager
+except ImportError:
+    # Skip tests if L1Manager cannot be imported
+    pytest.skip(
+        "Skipping because StorageManager cannot be imported", allow_module_level=True
+    )
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+def should_use_lazy_alloc() -> bool:
+    """Determine if lazy allocation should be used based on CUDA availability."""
+    return torch.cuda.is_available()
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def basic_memory_config():
+    """Create a basic L1MemoryManagerConfig for testing."""
+    return L1MemoryManagerConfig(
+        size_in_bytes=128 * 1024 * 1024,  # 128MB
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64 * 1024 * 1024,  # 64MB
+        align_bytes=0x1000,  # 4KB
+    )
+
+
+@pytest.fixture
+def small_memory_config():
+    """Create a small L1MemoryManagerConfig to test memory exhaustion."""
+    return L1MemoryManagerConfig(
+        size_in_bytes=64 * 1024 * 1024,  # 64MB
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64 * 1024 * 1024,  # 64MB
+        align_bytes=0x1000,
+    )
+
+
+@pytest.fixture
+def basic_l1_config(basic_memory_config):
+    """Create a basic L1ManagerConfig for testing."""
+    return L1ManagerConfig(
+        memory_config=basic_memory_config,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+
+
+@pytest.fixture
+def small_l1_config(small_memory_config):
+    """Create a small L1ManagerConfig to test memory exhaustion."""
+    return L1ManagerConfig(
+        memory_config=small_memory_config,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+
+
+@pytest.fixture
+def basic_storage_manager_config(basic_l1_config):
+    """Create a basic StorageManagerConfig for testing"""
+    return StorageManagerConfig(
+        l1_manager_config=basic_l1_config,
+        eviction_config=EvictionConfig(
+            eviction_policy="LRU",
+        ),
+    )
+
+
+@pytest.fixture
+def small_storage_manager_config(small_l1_config):
+    """Create a small StorageManagerConfig to test memory exhaustion."""
+    return StorageManagerConfig(
+        l1_manager_config=small_l1_config,
+        eviction_config=EvictionConfig(
+            eviction_policy="LRU",
+        ),
+    )
+
+
+@pytest.fixture
+def basic_layout():
+    """Create a basic MemoryLayoutDesc for testing."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+@pytest.fixture
+def large_layout():
+    """Create a large MemoryLayoutDesc that will exhaust small memory.
+
+    Each allocation is 8MB (2M elements * 4 bytes).
+    """
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([2048, 1024])],  # 2M elements * 4 bytes = 8MB
+        dtypes=[torch.float32],
+    )
+
+
+def make_object_key(chunk_hash: int, model_name: str = "test_model", kv_rank: int = 0):
+    """Helper to create ObjectKey instances."""
+    hash_bytes = ObjectKey.IntHash2Bytes(chunk_hash)
+    return ObjectKey(chunk_hash=hash_bytes, model_name=model_name, kv_rank=kv_rank)
+
+
+def wait_for_condition(
+    predicate,
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+) -> bool:
+    """Poll until a predicate returns True or timeout."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def wait_for_prefetch_status(
+    sm: StorageManager,
+    handle,
+    timeout: float = 10.0,
+    poll_interval: float = 0.05,
+) -> int | None:
+    """Poll query_prefetch_status until it returns a non-None value.
+
+    Returns the contiguous prefix-hit count (``count_leading_ones``) of the
+    found bitmap, matching the dense semantics these tests assert on.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = sm.query_prefetch_status(handle)
+        if result is not None:
+            return result.count_leading_ones()
+        time.sleep(poll_interval)
+    return None
+
+
+def wait_for_sparse_found(
+    sm: StorageManager,
+    handle,
+    timeout: float = 10.0,
+    poll_interval: float = 0.05,
+) -> set[int] | None:
+    """Poll query_prefetch_status; return the found-key index set.
+
+    For SPARSE prefetches the result bitmap is gap-tolerant, so callers read
+    the full set via ``get_indices_list`` rather than ``count_leading_ones``.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = sm.query_prefetch_status(handle)
+        if result is not None:
+            return set(result.get_indices_list())
+        time.sleep(poll_interval)
+    return None
+
+
+# =============================================================================
+# Tests
+# =============================================================================
+
+
+class TestStorageManagerBasic:
+    """Tests for basic functionality of StorageManager."""
+
+    def test_basic_reserve_write(self, basic_storage_manager_config, basic_layout):
+        """Test basic reserve and write functionality."""
+        storage_manager = StorageManager(basic_storage_manager_config)
+
+        object_key = make_object_key(chunk_hash=12345)
+
+        # Reserve space for the object
+        ret = storage_manager.reserve_write([object_key], basic_layout, mode="new")
+        assert object_key in ret
+        assert ret[object_key] is not None
+
+        # Should not have any error
+        storage_manager.finish_write([object_key])
+
+        storage_manager.close()
+
+    def test_reserve_write_multiple_keys(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Test reserve_write with multiple keys."""
+        storage_manager = StorageManager(basic_storage_manager_config)
+
+        keys = [make_object_key(i) for i in range(5)]
+
+        ret = storage_manager.reserve_write(keys, basic_layout, mode="new")
+
+        # All keys should be allocated
+        assert len(ret) == len(keys)
+        for key in keys:
+            assert key in ret
+            assert ret[key] is not None
+
+        storage_manager.close()
+
+    def test_reserve_write_oom(self, small_storage_manager_config, large_layout):
+        """Test reserve_write raises L1Error on out-of-memory."""
+        storage_manager = StorageManager(small_storage_manager_config)
+
+        keys = [make_object_key(i) for i in range(20)]
+
+        ret = storage_manager.reserve_write(keys, large_layout, mode="new")
+
+        # At least some of the keys could be allocated
+        assert len(ret) < len(keys)
+
+        # If some keys were allocated, they should not be None
+        for key, obj in ret.items():
+            assert obj is not None
+
+        storage_manager.close()
+
+    def test_basic_prefetch(self, basic_storage_manager_config, basic_layout):
+        """Test basic prefetch functionality."""
+        storage_manager = StorageManager(basic_storage_manager_config)
+
+        object_keys = [make_object_key(i) for i in range(5)]
+
+        # Write keys into storage manager
+        ret = storage_manager.reserve_write(object_keys, basic_layout, mode="new")
+        for key in object_keys:
+            assert key in ret
+            assert ret[key] is not None
+        storage_manager.finish_write(list(ret.keys()))
+
+        # Prefetch all the objects
+        handle = storage_manager.submit_prefetch_task(object_keys, basic_layout)
+
+        hit_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert hit_count is not None
+        assert hit_count == len(object_keys)
+
+        storage_manager.close()
+
+    def test_prefetch_partial_prefix_hits(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Test prefetch with partial hits."""
+        # 5 keys: 0, 1, 3, 4 are written, 2 is missing
+        storage_manager = StorageManager(basic_storage_manager_config)
+
+        object_keys = [make_object_key(i) for i in range(5)]
+
+        # Write only some keys into storage manager
+        keys_to_write = [object_keys[0], object_keys[1], object_keys[3], object_keys[4]]
+        ret = storage_manager.reserve_write(keys_to_write, basic_layout, mode="new")
+        for key in keys_to_write:
+            assert key in ret
+            assert ret[key] is not None
+        storage_manager.finish_write(list(ret.keys()))
+
+        # Prefetch all the objects
+        handle = storage_manager.submit_prefetch_task(object_keys, basic_layout)
+
+        hit_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert hit_count is not None
+        assert hit_count == 2  # Only 2 keys were written
+
+        # The last 2 keys should be "writable"
+        ret = storage_manager.reserve_write(
+            object_keys[3:], basic_layout, mode="update"
+        )
+        for key in object_keys[3:]:
+            assert key in ret
+            assert ret[key] is not None
+
+        storage_manager.close()
+
+    def test_read_prefetched_basic(self, basic_storage_manager_config, basic_layout):
+        """Test reading prefetched objects."""
+        storage_manager = StorageManager(basic_storage_manager_config)
+
+        object_keys = [make_object_key(i) for i in range(3)]
+
+        # Write keys into storage manager
+        ret = storage_manager.reserve_write(object_keys, basic_layout, mode="new")
+        for key in object_keys:
+            assert key in ret
+            assert ret[key] is not None
+        storage_manager.finish_write(list(ret.keys()))
+
+        # Prefetch all the objects
+        handle = storage_manager.submit_prefetch_task(object_keys, basic_layout)
+
+        hit_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert hit_count is not None
+        assert hit_count == len(object_keys)
+
+        # Read the prefetched objects
+        with storage_manager.read_prefetched_results(object_keys) as retrieved_objects:
+            assert retrieved_objects is not None
+            assert len(retrieved_objects) == len(object_keys)
+
+        # Finish reading
+        storage_manager.finish_read_prefetched(object_keys)
+
+        # Now the objects should be writable again
+        ret = storage_manager.reserve_write(object_keys, basic_layout, mode="update")
+        for key in object_keys:
+            assert key in ret
+            assert ret[key] is not None
+
+        storage_manager.close()
+
+    def test_read_prefetched_not_found(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Test reading prefetched objects that were not found."""
+        storage_manager = StorageManager(basic_storage_manager_config)
+
+        object_keys = [make_object_key(i) for i in range(5)]
+
+        # Write all objects into storage manager
+        ret = storage_manager.reserve_write(object_keys, basic_layout, mode="new")
+        for key in object_keys:
+            assert key in ret
+            assert ret[key] is not None
+        storage_manager.finish_write(list(ret.keys()))
+
+        # Prefetch objects except the first one
+        handle = storage_manager.submit_prefetch_task(object_keys[1:], basic_layout)
+        hit_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert hit_count is not None
+        assert hit_count == len(object_keys) - 1
+
+        # Attempt to read all the objects, should get None
+        with storage_manager.read_prefetched_results(object_keys) as retrieved_objects:
+            assert retrieved_objects is None
+
+        # Remaining 4 objects should still be writable (i.e., no dangling read locks)
+        ret = storage_manager.reserve_write(
+            object_keys[1:], basic_layout, mode="update"
+        )
+        for key in object_keys[1:]:
+            assert key in ret
+            assert ret[key] is not None
+        storage_manager.close()
+
+
+# =============================================================================
+# Tests for multi-reader (count / num_readers) support
+# =============================================================================
+
+
+class TestStorageManagerMultiReader:
+    """Tests for the num_readers / count parameters.
+
+    These parameters allow multiple workers (e.g. MLA with
+    TP > 1) to each hold an independent read lock on the same
+    prefetched object.
+    """
+
+    def test_prefetch_with_extra_count(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """submit_prefetch_task(extra_count=N-1) acquires N locks."""
+        sm = StorageManager(basic_storage_manager_config)
+        keys = [make_object_key(i) for i in range(3)]
+
+        # Write keys
+        ret = sm.reserve_write(keys, basic_layout, mode="new")
+        assert len(ret) == len(keys)
+        sm.finish_write(list(ret.keys()))
+
+        extra_count = 2  # total = 1 + 2 = 3 locks
+        handle = sm.submit_prefetch_task(keys, basic_layout, extra_count=extra_count)
+        hit = sm.query_prefetch_status(handle).count_leading_ones()
+        assert hit == len(keys)
+
+        # Release with matching extra_count
+        sm.finish_read_prefetched(keys, extra_count=extra_count)
+
+        # All locks released -> objects writable again
+        ret = sm.reserve_write(keys, basic_layout, mode="update")
+        assert len(ret) == len(keys)
+
+        sm.close()
+
+    def test_finish_read_prefetched_partial_extra_count(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Partial extra_count release leaves locks held."""
+        sm = StorageManager(basic_storage_manager_config)
+        keys = [make_object_key(i) for i in range(2)]
+
+        ret = sm.reserve_write(keys, basic_layout, mode="new")
+        sm.finish_write(list(ret.keys()))
+
+        extra_count = 3  # total = 1 + 3 = 4 locks
+        handle = sm.submit_prefetch_task(keys, basic_layout, extra_count=extra_count)
+        hit = sm.query_prefetch_status(handle).count_leading_ones()
+        assert hit == len(keys)
+
+        # Release 2 of 4 (1 + extra_count=1)
+        sm.finish_read_prefetched(keys, extra_count=1)
+
+        # Objects should NOT be writable (2 locks remain)
+        ret = sm.reserve_write(keys, basic_layout, mode="update")
+        assert len(ret) == 0
+
+        # Release remaining 2 (1 + extra_count=1)
+        sm.finish_read_prefetched(keys, extra_count=1)
+
+        # Now writable
+        ret = sm.reserve_write(keys, basic_layout, mode="update")
+        assert len(ret) == len(keys)
+
+        sm.close()
+
+    def test_prefetch_skipped_keys_released_with_extra(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Non-prefix L1 hits are released with correct extra.
+
+        Keys {0,1,3,4} exist, key 2 is missing.  The prefix
+        hits are {0,1}; keys {3,4} must have their N locks
+        released to avoid dangling locks.
+        """
+        sm = StorageManager(basic_storage_manager_config)
+        all_keys = [make_object_key(i) for i in range(5)]
+        existing = [all_keys[i] for i in [0, 1, 3, 4]]
+
+        ret = sm.reserve_write(existing, basic_layout, mode="new")
+        sm.finish_write(list(ret.keys()))
+
+        extra_count = 1  # total = 1 + 1 = 2 locks
+        handle = sm.submit_prefetch_task(
+            all_keys, basic_layout, extra_count=extra_count
+        )
+        hit = sm.query_prefetch_status(handle).count_leading_ones()
+        # Only prefix {0,1} count as hits
+        assert hit is not None
+        assert hit == 2
+
+        # Finish the prefix hits
+        sm.finish_read_prefetched(all_keys[:2], extra_count=extra_count)
+
+        # Keys {3,4} should be writable (skipped locks released)
+        ret = sm.reserve_write(
+            [all_keys[3], all_keys[4]],
+            basic_layout,
+            mode="update",
+        )
+        assert len(ret) == 2
+
+        sm.close()
+
+    def test_extra_count_default_is_zero(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Default extra_count=0 behaves same as before."""
+        sm = StorageManager(basic_storage_manager_config)
+        keys = [make_object_key(i) for i in range(3)]
+
+        ret = sm.reserve_write(keys, basic_layout, mode="new")
+        sm.finish_write(list(ret.keys()))
+
+        handle = sm.submit_prefetch_task(keys, basic_layout)
+        hit = sm.query_prefetch_status(handle).count_leading_ones()
+        assert hit == len(keys)
+
+        # Single finish is enough
+        sm.finish_read_prefetched(keys)
+
+        ret = sm.reserve_write(keys, basic_layout, mode="update")
+        assert len(ret) == len(keys)
+
+        sm.close()
+
+
+# =============================================================================
+# L2 Prefetch Integration Tests
+# =============================================================================
+
+
+@pytest.fixture
+def l2_storage_manager_config(basic_l1_config):
+    """Create a StorageManagerConfig with one MockL2Adapter."""
+    return StorageManagerConfig(
+        l1_manager_config=basic_l1_config,
+        eviction_config=EvictionConfig(
+            eviction_policy="LRU",
+        ),
+        l2_adapter_config=L2AdaptersConfig(
+            adapters=[
+                MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0),
+            ],
+        ),
+    )
+
+
+class TestStorageManagerL2Prefetch:
+    """Tests for prefetching from L2 through StorageManager."""
+
+    def _write_keys_and_wait_for_l2(
+        self,
+        sm: StorageManager,
+        keys: list[ObjectKey],
+        layout: MemoryLayoutDesc,
+    ) -> None:
+        """Write keys to L1 via StorageManager and wait for L2 store."""
+        ret = sm.reserve_write(keys, layout, mode="new")
+        assert len(ret) == len(keys)
+        sm.finish_write(list(ret.keys()))
+
+        # Wait for StoreController to propagate all keys to L2
+        adapter = sm._l2_adapters[0]
+        ok = wait_for_condition(
+            lambda: all(adapter.debug_has_key(k) for k in keys),  # type: ignore
+            timeout=10.0,
+        )
+        assert ok, "Keys should be stored in L2 by StoreController"
+
+    def test_prefetch_from_l2(self, l2_storage_manager_config, basic_layout):
+        """Write to L1 → store to L2 → clear L1 → prefetch from L2."""
+        sm = StorageManager(l2_storage_manager_config)
+        keys = [make_object_key(i) for i in range(5)]
+
+        self._write_keys_and_wait_for_l2(sm, keys, basic_layout)
+
+        # Brief sleep to let StoreController release read locks
+        # after L2 store completion, then clear L1
+        time.sleep(0.05)
+        sm.clear()
+        used, _ = sm._l1_manager.get_memory_usage()
+        assert used == 0, f"L1 should be empty after clear, but {used} bytes used"
+
+        # Prefetch — L1 has 0 hits, L2 should have all 5
+        handle = sm.submit_prefetch_task(keys, basic_layout)
+        hit_count = wait_for_prefetch_status(sm, handle)
+
+        assert hit_count is not None, "Prefetch should complete"
+        assert hit_count == 5, f"Expected 5 hits from L2, got {hit_count}"
+
+        # Verify keys are read-locked in L1 after prefetch
+        with sm.read_prefetched_results(keys) as objs:
+            assert objs is not None
+            assert len(objs) == len(keys)
+
+        sm.finish_read_prefetched(keys)
+        sm.close()
+
+    def test_prefetch_mixed_l1_l2(self, l2_storage_manager_config, basic_layout):
+        """Some keys in L1, rest in L2 → combined prefix hits."""
+        sm = StorageManager(l2_storage_manager_config)
+
+        # Use distinct hash ranges for L1-only vs L2 keys
+        all_keys = [make_object_key(i) for i in range(5)]
+        l2_only_keys = all_keys[2:]  # keys 2, 3, 4 only in L2
+
+        # Write all keys to L1 (StoreController will push to L2)
+        self._write_keys_and_wait_for_l2(sm, all_keys, basic_layout)
+
+        # Delete only keys 2, 3, 4 from L1 so they must come from L2
+        sm._l1_manager.delete(l2_only_keys)
+
+        # Prefetch all 5 keys: first 2 from L1, next 3 from L2
+        handle = sm.submit_prefetch_task(all_keys, basic_layout)
+        hit_count = wait_for_prefetch_status(sm, handle)
+
+        assert hit_count is not None, "Prefetch should complete"
+        assert hit_count == 5, (
+            f"Expected 5 combined hits (2 L1 + 3 L2), got {hit_count}"
+        )
+
+        # Clean up read locks
+        sm.finish_read_prefetched(all_keys)
+        sm.close()
+
+    def test_prefetch_nothing_in_l2(self, l2_storage_manager_config, basic_layout):
+        """Prefetch keys not in L2 → returns 0 L2 hits."""
+        sm = StorageManager(l2_storage_manager_config)
+
+        # Don't write anything — keys exist nowhere
+        keys = [make_object_key(i) for i in range(3)]
+
+        handle = sm.submit_prefetch_task(keys, basic_layout)
+        hit_count = wait_for_prefetch_status(sm, handle)
+
+        assert hit_count is not None, "Prefetch should complete"
+        assert hit_count == 0, f"Expected 0 hits, got {hit_count}"
+
+        sm.close()
+
+    def test_warm_skip_l2_is_noop(self, l2_storage_manager_config, basic_layout):
+        """``mode=WARM`` + ``skip_l2=True`` submits no controller request.
+
+        Regression: the WARM branch must honor ``skip_l2`` (it previously
+        ignored it, issuing L2 lookup/load work and mutating L1). The returned
+        :class:`PrefetchHandle` is the public signal — no request id to track
+        and no L2-sourced indices; since the controller is the only path that
+        loads from L2, this also means L1 is left untouched.
+        """
+        sm = StorageManager(l2_storage_manager_config)
+        keys = [make_object_key(i) for i in range(3)]
+
+        # Put the keys in L2 so a non-skip warm would have something to load,
+        # then clear L1 so a load would be the only way they could reappear.
+        self._write_keys_and_wait_for_l2(sm, keys, basic_layout)
+        sm.clear()
+
+        handle = sm.submit_prefetch_task(
+            keys, basic_layout, mode=PrefetchMode.WARM, skip_l2=True
+        )
+
+        # skip_l2 honored: the controller was never asked.
+        assert handle.prefetch_request_id == -1
+        assert handle.l2_orig_indices == ()
+        assert handle.total_requested_keys == len(keys)
+
+        sm.close()
+
+    def test_prefetch_l2_partial_prefix(self, l2_storage_manager_config, basic_layout):
+        """L2 has keys {0,1,3,4} but not 2 → L2 returns prefix of 2."""
+        sm = StorageManager(l2_storage_manager_config)
+
+        all_keys = [make_object_key(i) for i in range(5)]
+        # Write only keys 0, 1, 3, 4 (skip key 2)
+        keys_to_write = [all_keys[i] for i in [0, 1, 3, 4]]
+        self._write_keys_and_wait_for_l2(sm, keys_to_write, basic_layout)
+
+        # Brief sleep to let StoreController release read locks
+        # after L2 store completion, then clear L1
+        time.sleep(0.05)
+        sm.clear()
+        used, _ = sm._l1_manager.get_memory_usage()
+        assert used == 0, f"L1 should be empty after clear, but {used} bytes used"
+
+        handle = sm.submit_prefetch_task(all_keys, basic_layout)
+        hit_count = wait_for_prefetch_status(sm, handle)
+
+        assert hit_count is not None, "Prefetch should complete"
+        assert hit_count == 2, (
+            f"Expected 2 prefix hits from L2 (gap at index 2), got {hit_count}"
+        )
+
+        # Only prefix keys {0, 1} should be readable
+        with sm.read_prefetched_results(all_keys[:2]) as objs:
+            assert objs is not None
+            assert len(objs) == 2
+
+        sm.finish_read_prefetched(all_keys[:2])
+        sm.close()
+
+    def test_prefetch_l1_prefix_plus_l2_continuation(
+        self, l2_storage_manager_config, basic_layout
+    ):
+        """L1 has keys {0,1}, L2 has {2,3,4} → combined prefix of 5."""
+        sm = StorageManager(l2_storage_manager_config)
+
+        all_keys = [make_object_key(i) for i in range(5)]
+
+        # Write all keys → StoreController stores all to L2
+        self._write_keys_and_wait_for_l2(sm, all_keys, basic_layout)
+
+        # Delete keys {2,3,4} from L1 only, keeping them in L2
+        sm._l1_manager.delete(all_keys[2:])
+
+        # Prefetch: L1 prefix hits = 2 (keys 0,1), L2 loads {2,3,4} → total = 5
+        handle = sm.submit_prefetch_task(all_keys, basic_layout)
+        hit_count = wait_for_prefetch_status(sm, handle)
+
+        assert hit_count is not None
+        assert hit_count == 5, f"Expected 5 total hits (2 L1 + 3 L2), got {hit_count}"
+
+        sm.finish_read_prefetched(all_keys)
+        sm.close()
+
+
+# =============================================================================
+# Tests for LM-291 failure event production
+# =============================================================================
+
+
+@pytest.fixture
+def captured_events():
+    """Enable the global event bus and capture all L1/L2 failure events.
+
+    Replaces the process-wide ``_global_bus`` with a fresh enabled bus,
+    subscribes a callback for the three failure event types, yields the
+    captured-events list, then resets the bus to disabled on teardown so
+    later tests don't see leftover state.
+    """
+    bus = init_event_bus(EventBusConfig(enabled=True, max_queue_size=10_000))
+    events: list[Event] = []
+
+    def _capture(event: Event) -> None:
+        events.append(event)
+
+    for et in (
+        EventType.L1_ALLOCATION_FAILED,
+        EventType.L1_READ_FAILED,
+        EventType.L2_PREFETCH_FAILED,
+    ):
+        bus.subscribe(et, _capture)
+    bus.start()
+    try:
+        yield events
+    finally:
+        bus.stop()
+        init_event_bus(EventBusConfig(enabled=False))
+
+
+def _events_of_type(events: list, event_type: EventType) -> list:
+    return [e for e in events if e.event_type == event_type]
+
+
+class TestFailureEventProduction:
+    """Verifies LM-291 health-monitoring events are published at the
+    right producer call sites with the expected metadata."""
+
+    def test_reserve_write_oom_emits_l1_allocation_failed(
+        self, small_storage_manager_config, large_layout, captured_events
+    ):
+        """OOM during user store must publish L1_ALLOCATION_FAILED with
+        during=l1_store and the OOM keys."""
+        sm = StorageManager(small_storage_manager_config)
+        try:
+            keys = [make_object_key(i) for i in range(20)]
+            sm.reserve_write(keys, large_layout, mode="new")
+
+            # Allow drain thread to deliver the event.
+            assert wait_for_condition(
+                lambda: len(
+                    _events_of_type(captured_events, EventType.L1_ALLOCATION_FAILED)
+                )
+                >= 1,
+                timeout=2.0,
+            )
+
+            alloc_events = _events_of_type(
+                captured_events, EventType.L1_ALLOCATION_FAILED
+            )
+            assert len(alloc_events) == 1
+            meta = alloc_events[0].metadata
+            assert meta["during"] == "l1_store"
+            assert len(meta["keys"]) > 0
+            # All emitted keys must be from the OOM subset of the request.
+            assert set(meta["keys"]).issubset(set(keys))
+        finally:
+            sm.close()
+
+    def test_unsafe_read_missing_key_emits_l1_read_failed(
+        self, basic_storage_manager_config, basic_layout, captured_events
+    ):
+        """Deleting a key between reserve_read and unsafe_read must publish
+        L1_READ_FAILED with during=l1_retrieve, reason=not_found."""
+        sm = StorageManager(basic_storage_manager_config)
+        try:
+            keys = [make_object_key(i) for i in range(3)]
+
+            # Write + finish_write so the keys are readable.
+            ret = sm.reserve_write(keys, basic_layout, mode="new")
+            assert len(ret) == len(keys)
+            sm.finish_write(list(ret.keys()))
+
+            # Prefetch to acquire read locks on all keys.
+            handle = sm.submit_prefetch_task(keys, basic_layout)
+            assert wait_for_prefetch_status(sm, handle) == len(keys)
+
+            # Force a mid-read race by removing the key from L1Manager's
+            # internal state dict, bypassing the lock check that
+            # ``L1Manager.delete`` enforces. This simulates the exact TOCTOU
+            # anomaly the metric is designed to catch: reserve_read acquired
+            # a lock, but the key vanished before unsafe_read.
+            del sm._l1_manager._objects[keys[1]]
+
+            # Now attempt to read — unsafe_read should find the middle key
+            # missing, emitting L1_READ_FAILED(during=l1_retrieve,
+            # reason=not_found).
+            with sm.read_prefetched_results(keys) as objs:
+                assert objs is None  # all_good=False because middle key is gone
+
+            assert wait_for_condition(
+                lambda: len(_events_of_type(captured_events, EventType.L1_READ_FAILED))
+                >= 1,
+                timeout=2.0,
+            )
+
+            read_events = _events_of_type(captured_events, EventType.L1_READ_FAILED)
+            assert len(read_events) == 1
+            meta = read_events[0].metadata
+            assert meta["during"] == "l1_retrieve"
+            assert meta["reason"] == "not_found"
+            assert keys[1] in meta["keys"]
+        finally:
+            sm.close()
+
+
+class TestStorageManagerSparsePrefetch:
+    """SPARSE prefetch: retain a read lock on every found key, not just the
+    leading contiguous prefix."""
+
+    def test_sparse_keeps_all_found_not_just_prefix(
+        self, basic_storage_manager_config, basic_layout
+    ):
+        """Sparse L1 prefetch retains + read-locks every found key, including
+        those past a gap (unlike the contiguous-prefix default)."""
+        sm = StorageManager(basic_storage_manager_config)
+        all_keys = [make_object_key(i) for i in range(5)]
+        # Write {0,1,3,4}; key 2 is the gap.
+        existing = [all_keys[i] for i in (0, 1, 3, 4)]
+        ret = sm.reserve_write(existing, basic_layout, mode="new")
+        sm.finish_write(list(ret.keys()))
+
+        handle = sm.submit_prefetch_task(
+            all_keys, basic_layout, policy=TrimPolicy.SPARSE
+        )
+        found = wait_for_sparse_found(sm, handle, timeout=10.0)
+
+        # Sparse: all four found indices, NOT just the prefix {0, 1}.
+        assert found == {0, 1, 3, 4}
+
+        # Every found key is read-locked (none write-reservable).
+        locked = sm.reserve_write(existing, basic_layout, mode="update")
+        assert len(locked) == 0
+
+        # Releasing the full found set frees them.
+        sm.finish_read_prefetched(existing)
+        freed = sm.reserve_write(existing, basic_layout, mode="update")
+        assert len(freed) == len(existing)
+
+        sm.close()
+
+    def test_sparse_from_l2_loads_all_found(
+        self, l2_storage_manager_config, basic_layout
+    ):
+        """Sparse prefetch from L2 loads every found key (controller skips the
+        prefix-only trim), not just the prefix before a gap."""
+        sm = StorageManager(l2_storage_manager_config)
+        all_keys = [make_object_key(i) for i in range(5)]
+        # L2 has {0,1,3,4}; gap at 2.
+        existing = [all_keys[i] for i in (0, 1, 3, 4)]
+        wret = sm.reserve_write(existing, basic_layout, mode="new")
+        sm.finish_write(list(wret.keys()))
+        adapter = sm._l2_adapters[0]
+        assert wait_for_condition(
+            lambda: all(adapter.debug_has_key(k) for k in existing),  # type: ignore
+            timeout=10.0,
+        )
+        time.sleep(0.05)
+        sm.clear()
+        used, _ = sm._l1_manager.get_memory_usage()
+        assert used == 0
+
+        handle = sm.submit_prefetch_task(
+            all_keys, basic_layout, policy=TrimPolicy.SPARSE
+        )
+        found = wait_for_sparse_found(sm, handle, timeout=10.0)
+
+        # Sparse from L2: all found {0,1,3,4}, NOT the contiguous prefix {0,1}.
+        assert found == {0, 1, 3, 4}
+
+        sm.finish_read_prefetched(existing)
+        sm.close()
diff --git a/tests/v1/distributed/test_encoded_object_key.py b/tests/v1/distributed/test_encoded_object_key.py
new file mode 100644
index 0000000..86d4848
--- /dev/null
+++ b/tests/v1/distributed/test_encoded_object_key.py
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for :class:`EncodedObjectKey` — the HTTP/JSON wire form of
+:class:`ObjectKey`.
+
+These tests stand alone from the heavier ``ObjectKey``-using machinery
+so they can run without ``lmcache.native_storage_ops`` being built.
+"""
+
+# Standard
+from dataclasses import asdict
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import EncodedObjectKey, ObjectKey
+
+
+def _make_object_key(**overrides) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=bytes.fromhex(overrides.get("chunk_hash_hex", "deadbeef")),
+        model_name=overrides.get("model_name", "llama"),
+        kv_rank=overrides.get("kv_rank", 7),
+        object_group_id=overrides.get("object_group_id", 0),
+        cache_salt=overrides.get("cache_salt", ""),
+    )
+
+
+class TestRoundTrip:
+    def test_encode_preserves_all_fields(self):
+        obj = _make_object_key(
+            chunk_hash_hex="cafebabe",
+            model_name="llama",
+            kv_rank=42,
+            object_group_id=3,
+            cache_salt="alice",
+        )
+        ck = obj.to_encoded_object_key()
+        assert ck.chunk_hash_hex == "cafebabe"
+        assert ck.model_name == "llama"
+        assert ck.kv_rank == 42
+        assert ck.object_group_id == 3
+        assert ck.cache_salt == "alice"
+
+    def test_round_trip_object_key(self):
+        obj = _make_object_key(
+            chunk_hash_hex="00010203",
+            model_name="m",
+            kv_rank=1,
+            object_group_id=5,
+            cache_salt="bob",
+        )
+        assert obj.to_encoded_object_key().to_object_key() == obj
+
+    def test_uppercase_hex_round_trips_lowercased(self):
+        # bytes.fromhex accepts uppercase; the recovered ObjectKey
+        # then re-projects to lowercase via bytes.hex().
+        ck = EncodedObjectKey(chunk_hash_hex="DEADBEEF", model_name="m", kv_rank=0)
+        obj = ck.to_object_key()
+        assert obj.chunk_hash == b"\xde\xad\xbe\xef"
+        assert obj.to_encoded_object_key().chunk_hash_hex == "deadbeef"
+
+    def test_optional_fields_default(self):
+        ck = EncodedObjectKey(chunk_hash_hex="aa", model_name="m", kv_rank=0)
+        assert ck.object_group_id == 0
+        assert ck.cache_salt == ""
+
+    def test_asdict_shape_is_stable(self):
+        # Wire callers serialize via ``dataclasses.asdict`` — the field
+        # set is the public contract.
+        ck = EncodedObjectKey(
+            chunk_hash_hex="aa",
+            model_name="m",
+            kv_rank=0,
+            object_group_id=1,
+            cache_salt="x",
+        )
+        assert asdict(ck) == {
+            "chunk_hash_hex": "aa",
+            "model_name": "m",
+            "kv_rank": 0,
+            "object_group_id": 1,
+            "cache_salt": "x",
+        }
+
+
+class TestToObjectKeyValidation:
+    def test_rejects_non_hex_chunk_hash(self):
+        ck = EncodedObjectKey(chunk_hash_hex="not-hex", model_name="m", kv_rank=0)
+        with pytest.raises(ValueError):
+            ck.to_object_key()
+
+    def test_propagates_object_key_invariants(self):
+        # ``@`` in model_name is rejected by ObjectKey.__post_init__,
+        # which fires from inside ``to_object_key``. This is the
+        # contract the HTTP endpoint relies on for malformed-but-typed
+        # bodies (which Pydantic let through).
+        ck = EncodedObjectKey(chunk_hash_hex="aa", model_name="bad@name", kv_rank=0)
+        with pytest.raises(ValueError):
+            ck.to_object_key()
+
+
+class TestSchemasReExport:
+    def test_schemas_module_still_exposes_encoded_object_key(self):
+        # The mp_coordinator schemas module re-exports the canonical
+        # type from ``api.py`` for callers that import from there.
+        # First Party
+        from lmcache.v1.mp_coordinator import schemas
+
+        assert schemas.EncodedObjectKey is EncodedObjectKey
diff --git a/tests/v1/distributed/test_fault_inject_l2_adapter.py b/tests/v1/distributed/test_fault_inject_l2_adapter.py
new file mode 100644
index 0000000..011886e
--- /dev/null
+++ b/tests/v1/distributed/test_fault_inject_l2_adapter.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for FaultInjectL2Adapter.
+
+The adapter is a decorator that drops a deterministic key subset at load to
+simulate partial L2 retrieve failures. These tests wrap a real MockL2Adapter
+and assert the load-result bitmap has exactly the expected bits cleared while
+the lookup bitmap is left intact, using only public interface methods.
+"""
+
+# Standard
+import select
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.l2_adapters.fault_inject_l2_adapter import (
+    FaultInjectL2Adapter,
+)
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+N_KEYS = 8
+
+
+def _object_key(chunk_id: int) -> ObjectKey:
+    """Build an ObjectKey from a chunk id (test fixture)."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def _memory_obj(size: int = 256, fill_value: float = 1.0) -> TensorMemoryObj:
+    """Build a filled TensorMemoryObj for use as a store/load buffer."""
+    raw = torch.empty(size, dtype=torch.float32)
+    raw.fill_(fill_value)
+    meta = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw, meta, parent_allocator=None)
+
+
+def _wait_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    """Wait up to ``timeout`` seconds for ``event_fd`` to signal, draining it.
+
+    Returns True if the fd became readable before the timeout, False otherwise.
+    """
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    if poll.poll(timeout * 1000):
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+def _make_adapter(rate: float = 0.0, seed: int = 0, gap_indices=(), gap_tail_ratios=()):
+    """Build a FaultInjectL2Adapter wrapping a fresh MockL2Adapter.
+
+    Returns the ``(wrapper, inner)`` pair.
+    """
+    inner = MockL2Adapter(MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0))
+    wrapper = FaultInjectL2Adapter(
+        inner,
+        rate=rate,
+        seed=seed,
+        gap_indices=tuple(gap_indices),
+        gap_tail_ratios=tuple(gap_tail_ratios),
+    )
+    return wrapper, inner
+
+
+def _store_all(adapter, keys):
+    """Store one memory object per key and drain the completion event."""
+    fd = adapter.get_store_event_fd()
+    adapter.submit_store_task(keys, [_memory_obj() for _ in keys])
+    assert _wait_fd(fd)
+    adapter.pop_completed_store_tasks()
+
+
+def _lookup_bitmap(adapter, keys):
+    """Run a lookup-and-lock for ``keys`` and return its result bitmap."""
+    fd = adapter.get_lookup_and_lock_event_fd()
+    tid = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+    assert _wait_fd(fd)
+    # query_*_result is non-idempotent (returns non-None once); poll briefly.
+    for _ in range(50):
+        bm = adapter.query_lookup_and_lock_result(tid)
+        if bm is not None:
+            return bm
+        time.sleep(0.01)
+    raise AssertionError("lookup result never ready")
+
+
+def _load_bitmap(adapter, keys):
+    """Run a load for ``keys`` and return its result bitmap."""
+    fd = adapter.get_load_event_fd()
+    tid = adapter.submit_load_task(keys, [_memory_obj() for _ in keys])
+    assert _wait_fd(fd)
+    for _ in range(50):
+        bm = adapter.query_load_result(tid)
+        if bm is not None:
+            return bm
+        time.sleep(0.01)
+    raise AssertionError("load result never ready")
+
+
+# =============================================================================
+# Pass-through (rate=0): no faults.
+# =============================================================================
+
+
+def test_rate_zero_is_passthrough():
+    """rate=0 passes every key through unchanged (no drops)."""
+    adapter, inner = _make_adapter(rate=0.0)
+    try:
+        keys = [_object_key(i) for i in range(N_KEYS)]
+        _store_all(adapter, keys)
+        lookup = _lookup_bitmap(adapter, keys)
+        load = _load_bitmap(adapter, keys)
+        assert lookup.popcount() == N_KEYS
+        assert load.popcount() == N_KEYS
+    finally:
+        adapter.close()
+
+
+# =============================================================================
+# gap_indices: exact, deterministic drops.
+# =============================================================================
+
+
+def test_load_gap_cleared_lookup_intact():
+    """A gapped load clears exactly those load bits, leaving lookup intact."""
+    gap = {1, 4, 6}
+    adapter, inner = _make_adapter(gap_indices=gap)
+    try:
+        keys = [_object_key(i) for i in range(N_KEYS)]
+        _store_all(adapter, keys)
+        # Lookup is never faulted (lookup says present).
+        lookup = _lookup_bitmap(adapter, keys)
+        assert lookup.popcount() == N_KEYS
+        load = _load_bitmap(adapter, keys)
+        for i in range(N_KEYS):
+            assert load.test(i) == (i not in gap)
+    finally:
+        adapter.close()
+
+
+# =============================================================================
+# gap_tail_ratios: distance-from-tail / load-length; workload-agnostic.
+# =============================================================================
+
+
+def test_gap_tail_ratio_position_and_scaling():
+    """A tail-ratio drops the chunk at round((1-ratio)*(n-1)); the absolute
+    index is computed from the load batch, so it scales with length -- no
+    content or position is known in advance."""
+    keys = [_object_key(i) for i in range(N_KEYS)]
+    adapter, inner = _make_adapter(gap_tail_ratios=(0.5,))
+    try:
+        _store_all(adapter, keys)
+        _lookup_bitmap(adapter, keys)
+        mid = round(0.5 * (N_KEYS - 1))
+        load = _load_bitmap(adapter, keys)
+        assert not load.test(mid)
+        assert all(load.test(i) for i in range(N_KEYS) if i != mid)
+        # Same ratio on a SHORTER load drops a proportionally-different index
+        # (relative to that batch's tail) -- self-scaling, workload-agnostic.
+        short = keys[:4]
+        load2 = _load_bitmap(adapter, short)
+        assert not load2.test(round(0.5 * (len(short) - 1)))
+    finally:
+        adapter.close()
+
+
+def test_gap_tail_ratio_endpoints():
+    """ratio=0.0 drops the last chunk; ratio=1.0 drops the first."""
+    keys = [_object_key(i) for i in range(N_KEYS)]
+    adapter, inner = _make_adapter(gap_tail_ratios=(0.0, 1.0))
+    try:
+        _store_all(adapter, keys)
+        _lookup_bitmap(adapter, keys)
+        load = _load_bitmap(adapter, keys)
+        assert not load.test(0) and not load.test(N_KEYS - 1)
+        assert all(load.test(i) for i in range(1, N_KEYS - 1))
+    finally:
+        adapter.close()
+
+
+# =============================================================================
+# rate-based drops: deterministic across instances with the same seed.
+# =============================================================================
+
+
+def test_rate_drop_is_deterministic_across_instances():
+    """Same seed drops the same keys; a different seed (very likely) differs."""
+    keys = [_object_key(i) for i in range(64)]
+
+    def dropped_positions(seed):
+        adapter, inner = _make_adapter(rate=0.3, seed=seed)
+        try:
+            _store_all(adapter, keys)
+            _lookup_bitmap(adapter, keys)
+            load = _load_bitmap(adapter, keys)
+            return {i for i in range(len(keys)) if not load.test(i)}
+        finally:
+            adapter.close()
+
+    a = dropped_positions(seed=42)
+    b = dropped_positions(seed=42)
+    c = dropped_positions(seed=1234)
+    assert a, "rate=0.3 should drop at least one of 64 keys"
+    assert a == b, "same seed must drop the same keys"
+    # A different seed should (with overwhelming probability) differ.
+    assert a != c
+
+
+def test_rate_drop_within_tolerance():
+    """Rate-based bucketing drops roughly ``rate * N`` keys (wide tolerance)."""
+    keys = [_object_key(i) for i in range(200)]
+    adapter, inner = _make_adapter(rate=0.25, seed=7)
+    try:
+        _store_all(adapter, keys)
+        _lookup_bitmap(adapter, keys)
+        load = _load_bitmap(adapter, keys)
+        dropped = sum(1 for i in range(len(keys)) if not load.test(i))
+        # Deterministic hash bucketing -> roughly rate * N, allow a wide band.
+        assert 25 <= dropped <= 75
+    finally:
+        adapter.close()
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/tests/v1/distributed/test_fs_l2_adapter_keys.py b/tests/v1/distributed/test_fs_l2_adapter_keys.py
new file mode 100644
index 0000000..9a83a2a
--- /dev/null
+++ b/tests/v1/distributed/test_fs_l2_adapter_keys.py
@@ -0,0 +1,323 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for fs_l2_adapter key serialization helpers.
+
+These helpers round-trip ObjectKey <-> filename. ``object_group_id`` is
+embedded as a fixed field right after ``kv_rank``; ``cache_salt`` is
+appended as a trailing field when non-empty. Unsalted keys use the
+4-field shape and salted keys use the 5-field shape.
+"""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.l2_adapters.fs_l2_adapter import (
+    _filename_to_object_key,
+    _object_key_to_filename,
+)
+
+
+class TestFilenameRoundtrip:
+    """``_object_key_to_filename`` and ``_filename_to_object_key`` are
+    exact inverses for both the 4-field (unsalted) and 5-field (salted)
+    shapes."""
+
+    @pytest.mark.parametrize(
+        "model_name",
+        [
+            "llama",
+            "meta-llama/Llama-3",  # has '/', must survive PATH_SLASH_REPLACEMENT
+        ],
+    )
+    @pytest.mark.parametrize("cache_salt", ["", "alice", "user-abc_123.xyz:42"])
+    @pytest.mark.parametrize("object_group_id", [0, 1, 255])
+    def test_roundtrip(self, model_name: str, cache_salt: str, object_group_id: int):
+        key = ObjectKey(
+            chunk_hash=b"\xde\xad\xbe\xef",
+            model_name=model_name,
+            kv_rank=42,
+            object_group_id=object_group_id,
+            cache_salt=cache_salt,
+        )
+        fn = _object_key_to_filename(key)
+        assert fn.endswith(".data")
+        # Salted filenames gain a trailing "@<salt>" before ".data".
+        if cache_salt:
+            assert fn.endswith("@" + cache_salt + ".data")
+        parsed = _filename_to_object_key(fn)
+        assert parsed == key
+
+    def test_object_group_id_distinguishes_filenames(self):
+        """Keys differing only in object_group_id must not collide."""
+        fn0 = _object_key_to_filename(
+            ObjectKey(
+                chunk_hash=b"\xde\xad\xbe\xef",
+                model_name="llama",
+                kv_rank=42,
+                object_group_id=0,
+            )
+        )
+        fn1 = _object_key_to_filename(
+            ObjectKey(
+                chunk_hash=b"\xde\xad\xbe\xef",
+                model_name="llama",
+                kv_rank=42,
+                object_group_id=1,
+            )
+        )
+        assert fn0 != fn1
+
+    def test_unsalted_format(self):
+        """Unsalted keys use the 4-field shape."""
+        fn = "llama@0x0000002a@0@deadbeef.data"
+        parsed = _filename_to_object_key(fn)
+        assert parsed == ObjectKey(
+            chunk_hash=b"\xde\xad\xbe\xef",
+            model_name="llama",
+            kv_rank=42,
+            object_group_id=0,
+            cache_salt="",
+        )
+
+    def test_salted_format(self):
+        """Salted keys append ``@<cache_salt>`` before the extension."""
+        fn = "llama@0x0000002a@2@deadbeef@alice.data"
+        parsed = _filename_to_object_key(fn)
+        assert parsed == ObjectKey(
+            chunk_hash=b"\xde\xad\xbe\xef",
+            model_name="llama",
+            kv_rank=42,
+            object_group_id=2,
+            cache_salt="alice",
+        )
+
+    def test_non_data_file_returns_none(self):
+        assert _filename_to_object_key("not-a-data-file.txt") is None
+
+    def test_too_few_fields_returns_none(self):
+        assert _filename_to_object_key("just-one-field.data") is None
+
+    def test_old_three_field_format_returns_none(self):
+        """The pre-object_group_id 3-field shape is no longer accepted."""
+        assert _filename_to_object_key("llama@0x0000002a@deadbeef.data") is None
+
+    def test_too_many_fields_returns_none(self):
+        assert _filename_to_object_key("a@b@c@d@e@f.data") is None
+
+    def test_salt_with_forbidden_char_returns_none(self):
+        # A filename that parses into 5 fields but whose trailing "salt"
+        # slot contains a char ObjectKey.__post_init__ rejects (NUL here
+        # is impossible in filenames, so use the length cap instead).
+        too_long_salt = "x" * 129
+        fn = f"llama@0x0000002a@0@deadbeef@{too_long_salt}.data"
+        assert _filename_to_object_key(fn) is None
+
+
+class TestIpcKeyToObjectKeys:
+    """ipc_key_to_object_keys reads cache_salt from the ipc_key itself —
+    there is no separate parameter, so callers cannot accidentally drop
+    the salt."""
+
+    def test_forwards_cache_salt_single_worker(self):
+        # First Party
+        from lmcache.v1.distributed.api import ipc_key_to_object_keys
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            token_ids=[1, 2, 3],
+            cache_salt="alice",
+        )
+        out = ipc_key_to_object_keys(k, [b"h1", b"h2"], [0])[0]
+        assert len(out) == 2
+        assert all(o.cache_salt == "alice" for o in out)
+
+    def test_forwards_cache_salt_scheduler_path(self):
+        """worker_id=None explodes one chunk into one ObjectKey per worker."""
+        # First Party
+        from lmcache.v1.distributed.api import ipc_key_to_object_keys
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=4,
+            worker_id=None,
+            token_ids=[1, 2, 3],
+            cache_salt="alice",
+        )
+        out = ipc_key_to_object_keys(k, [b"h1"], [0])[0]
+        assert len(out) == 4
+        assert all(o.cache_salt == "alice" for o in out)
+
+    def test_empty_salt_passes_through(self):
+        # First Party
+        from lmcache.v1.distributed.api import ipc_key_to_object_keys
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            token_ids=[1],
+        )
+        out = ipc_key_to_object_keys(k, [b"h1"], [0])[0]
+        assert all(o.cache_salt == "" for o in out)
+
+    def test_object_group_id_zero(self):
+        # First Party
+        from lmcache.v1.distributed.api import ipc_key_to_object_keys
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            token_ids=[1, 2],
+        )
+        out = ipc_key_to_object_keys(k, [b"h1", b"h2"], [0])[0]
+        assert all(o.object_group_id == 0 for o in out)
+
+    def test_object_group_id_propagates_to_all_keys(self):
+        """A non-zero object_group_id reaches every produced ObjectKey,
+        including the worker-expansion (scheduler) path."""
+        # First Party
+        from lmcache.v1.distributed.api import ipc_key_to_object_keys
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=4,
+            worker_id=None,
+            token_ids=[1, 2, 3],
+        )
+        out = ipc_key_to_object_keys(k, [b"h1"], [3])[0]
+        assert len(out) == 4
+        assert all(o.object_group_id == 3 for o in out)
+
+    def test_multiple_object_groups(self):
+        """Each requested object group gets its own positional key list."""
+        # First Party
+        from lmcache.v1.distributed.api import ipc_key_to_object_keys
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=2,
+            worker_id=None,
+            token_ids=[1, 2, 3],
+            cache_salt="alice",
+        )
+        out = ipc_key_to_object_keys(k, [b"h1", b"h2"], [0, 3])
+        assert len(out) == 2
+        # 2 chunks * 2 workers = 4 keys per group.
+        assert all(len(group_keys) == 4 for group_keys in out)
+        assert all(o.object_group_id == 0 for o in out[0])
+        assert all(o.object_group_id == 3 for o in out[1])
+        # The groups differ only in object_group_id.
+        for first, second in zip(out[0], out[1], strict=True):
+            assert first.chunk_hash == second.chunk_hash
+            assert first.kv_rank == second.kv_rank
+            assert first.cache_salt == second.cache_salt
+
+
+class TestObjectKeyValidation:
+    """``ObjectKey.__post_init__`` rejects invalid ``object_group_id``."""
+
+    def test_negative_object_group_id_rejected(self):
+        with pytest.raises(ValueError, match="object_group_id"):
+            ObjectKey(
+                chunk_hash=b"\xde\xad\xbe\xef",
+                model_name="llama",
+                kv_rank=0,
+                object_group_id=-1,
+            )
+
+
+class TestIPCCacheServerKeyCacheSalt:
+    """cache_salt on IPCCacheServerKey: validation + wire compat."""
+
+    def test_reject_at_in_salt(self):
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        with pytest.raises(ValueError, match="cache_salt"):
+            IPCCacheServerKey.from_token_ids(
+                model_name="m",
+                world_size=1,
+                worker_id=0,
+                token_ids=[1],
+                cache_salt="a@b",
+            )
+
+    def test_reject_slash_in_salt(self):
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        with pytest.raises(ValueError, match="cache_salt"):
+            IPCCacheServerKey.from_token_ids(
+                model_name="m",
+                world_size=1,
+                worker_id=0,
+                token_ids=[1],
+                cache_salt="tenant/alice",
+            )
+
+    def test_no_worker_id_version_preserves_salt(self):
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=4,
+            worker_id=2,
+            token_ids=[1],
+            cache_salt="alice",
+        )
+        k2 = k.no_worker_id_version()
+        assert k2.worker_id is None
+        assert k2.cache_salt == "alice"
+
+    def test_wire_compat_old_payload_decodes(self):
+        """An old 7-field msgspec payload must decode cleanly on new code
+        with cache_salt defaulting to ""."""
+        # Third Party
+        import msgspec
+
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        old_payload = {
+            "model_name": "m",
+            "world_size": 1,
+            "worker_id": 0,
+            "token_ids": (1, 2),
+            "start": 0,
+            "end": 2,
+            "request_id": "r1",
+        }
+        wire = msgspec.msgpack.encode(old_payload)
+        decoded = msgspec.msgpack.decode(wire, type=IPCCacheServerKey)
+        assert decoded.cache_salt == ""
+
+    def test_wire_compat_new_payload_roundtrip(self):
+        # Third Party
+        import msgspec
+
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+        k = IPCCacheServerKey.from_token_ids(
+            model_name="m",
+            world_size=1,
+            worker_id=0,
+            token_ids=[1, 2],
+            cache_salt="alice",
+        )
+        wire = msgspec.msgpack.encode(k)
+        decoded = msgspec.msgpack.decode(wire, type=IPCCacheServerKey)
+        assert decoded == k
+        assert decoded.cache_salt == "alice"
diff --git a/tests/v1/distributed/test_hfbucket_l2_adapter.py b/tests/v1/distributed/test_hfbucket_l2_adapter.py
new file mode 100644
index 0000000..6025cff
--- /dev/null
+++ b/tests/v1/distributed/test_hfbucket_l2_adapter.py
@@ -0,0 +1,581 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the HFBucket MP L2 adapter."""
+
+# Standard
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+import select
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2AdapterListener
+from lmcache.v1.distributed.l2_adapters import hfbucket_l2_adapter as hfmod
+from lmcache.v1.distributed.l2_adapters.hfbucket_l2_adapter import (
+    HFBucketL2Adapter,
+    HFBucketL2AdapterConfig,
+    _object_key_to_bucket_path,
+    _object_key_to_string,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+from lmcache.v1.storage_backend.connector.hfbucket_connector import (
+    parse_hfbucket_handle,
+)
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+_TEST_BUCKET_HANDLE = "hf://buckets/test-org/test-bucket/prod"
+_TEST_BUCKET_LOCATION = parse_hfbucket_handle(_TEST_BUCKET_HANDLE)
+
+
+@dataclass(frozen=True)
+class _FakePathInfo:
+    path: str
+    type: str
+    size: int
+
+
+class _FakeBucketClient:
+    """In-memory HFBucket client used by adapter unit tests."""
+
+    def __init__(self) -> None:
+        self.storage: dict[str, bytes] = {}
+        self.created_buckets: list[str] = []
+        self.deleted_paths: list[str] = []
+        self.fail_upload_after: int | None = None
+        self._lock = threading.Lock()
+
+    def create_bucket(self, bucket_id: str) -> None:
+        with self._lock:
+            self.created_buckets.append(bucket_id)
+
+    def bucket_info(self, bucket_id: str) -> object:
+        return {"bucket_id": bucket_id}
+
+    def get_paths_info(
+        self,
+        bucket_id: str,
+        paths: Sequence[str],
+    ) -> list[object]:
+        del bucket_id
+        with self._lock:
+            return [
+                _FakePathInfo(path=path, type="file", size=len(self.storage[path]))
+                for path in paths
+                if path in self.storage
+            ]
+
+    def list_tree(self, bucket_id: str, prefix: str) -> list[object]:
+        del bucket_id
+        with self._lock:
+            return [
+                _FakePathInfo(path=path, type="file", size=len(data))
+                for path, data in self.storage.items()
+                if not prefix or path.startswith(prefix)
+            ]
+
+    def upload_files(
+        self,
+        bucket_id: str,
+        add: Sequence[tuple[bytes, str]],
+    ) -> None:
+        del bucket_id
+        with self._lock:
+            for index, (data, path) in enumerate(add, start=1):
+                self.storage[path] = bytes(data)
+                if (
+                    self.fail_upload_after is not None
+                    and index >= self.fail_upload_after
+                ):
+                    raise RuntimeError("injected partial upload failure")
+
+    def download_files(
+        self,
+        bucket_id: str,
+        files: Sequence[tuple[str, str]],
+    ) -> None:
+        del bucket_id
+        with self._lock:
+            items = [
+                (remote, local, self.storage.get(remote)) for remote, local in files
+            ]
+
+        for _remote, local, data in items:
+            if data is None:
+                continue
+            Path(local).write_bytes(data)
+
+    def delete_files(
+        self,
+        bucket_id: str,
+        delete: Sequence[str],
+    ) -> None:
+        del bucket_id
+        with self._lock:
+            for path in delete:
+                self.deleted_paths.append(path)
+                self.storage.pop(path, None)
+
+    def contains(self, path: str) -> bool:
+        with self._lock:
+            return path in self.storage
+
+
+def create_object_key(chunk_id: int, model_name: str = "test/model") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(size: int = 16, fill_value: float = 1.0) -> MemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def bucket_path_for_key(key: ObjectKey) -> str:
+    return _object_key_to_bucket_path(key, _TEST_BUCKET_LOCATION)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+@pytest.fixture
+def fake_client() -> _FakeBucketClient:
+    return _FakeBucketClient()
+
+
+@pytest.fixture
+def adapter(tmp_path: Path, fake_client: _FakeBucketClient):
+    cfg = HFBucketL2AdapterConfig(
+        bucket_handle=_TEST_BUCKET_HANDLE,
+        download_tmp_dir=str(tmp_path),
+        metadata_cache_ttl_secs=30,
+        num_workers=2,
+        max_capacity_gb=0.001,
+    )
+    adapter = HFBucketL2Adapter(cfg, bucket_client=fake_client)
+    yield adapter
+    adapter.close()
+
+
+class _RecordingListener(L2AdapterListener):
+    def __init__(self) -> None:
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys, sizes):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys):
+        self.deleted.append(list(keys))
+
+
+class TestObjectKeySerialization:
+    def test_format(self) -> None:
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+        )
+        assert _object_key_to_string(key) == "llama@000000ff@0@00010203"
+
+    def test_object_group_id_embedded(self) -> None:
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+            object_group_id=5,
+        )
+        assert _object_key_to_string(key) == "llama@000000ff@5@00010203"
+
+    def test_cache_salt_appended(self) -> None:
+        base_key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+        )
+        salted = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+            cache_salt="user-42",
+        )
+        assert _object_key_to_string(base_key) == "llama@000000ff@0@00010203"
+        assert _object_key_to_string(salted) == "llama@000000ff@0@00010203@user-42"
+        assert _object_key_to_string(base_key) != _object_key_to_string(salted)
+
+    def test_bucket_path_uses_prefix_and_encoding(self) -> None:
+        cfg = HFBucketL2AdapterConfig(bucket_handle=_TEST_BUCKET_HANDLE)
+        key = create_object_key(1)
+        path = _object_key_to_bucket_path(key, cfg.bucket_location)
+        assert path.startswith("prod/")
+        assert "/" not in path.removeprefix("prod/")
+
+
+class TestEventFdInterface:
+    def test_three_distinct_fds(self, adapter: HFBucketL2Adapter) -> None:
+        a = adapter.get_store_event_fd()
+        b = adapter.get_lookup_and_lock_event_fd()
+        c = adapter.get_load_event_fd()
+        assert a >= 0 and b >= 0 and c >= 0
+        assert len({a, b, c}) == 3
+
+
+class TestStoreLookupLoad:
+    def test_roundtrip_single_key(self, adapter: HFBucketL2Adapter) -> None:
+        key = create_object_key(1)
+        obj = create_memory_obj(fill_value=3.14)
+
+        tid = adapter.submit_store_task([key], [obj])
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        assert adapter.pop_completed_store_tasks()[tid].is_successful()
+
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        bm = adapter.query_lookup_and_lock_result(tid)
+        assert bm is not None and bm.test(0) is True
+
+        dst = create_memory_obj(fill_value=0.0)
+        tid = adapter.submit_load_task([key], [dst])
+        assert wait_for_event_fd(adapter.get_load_event_fd())
+        bm = adapter.query_load_result(tid)
+        assert bm is not None and bm.test(0) is True
+        assert torch.allclose(dst.tensor, torch.full((16,), 3.14))
+
+    def test_partial_hits(self, adapter: HFBucketL2Adapter) -> None:
+        stored = [create_object_key(0), create_object_key(2)]
+        objs = [create_memory_obj(fill_value=float(i)) for i in range(2)]
+        adapter.submit_store_task(stored, objs)
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+        keys = [create_object_key(i) for i in range(4)]
+        tid = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        bm = adapter.query_lookup_and_lock_result(tid)
+        assert bm is not None
+        assert bm.test(0) is True
+        assert bm.test(1) is False
+        assert bm.test(2) is True
+        assert bm.test(3) is False
+
+    def test_load_miss_returns_zero_bit(self, adapter: HFBucketL2Adapter) -> None:
+        key = create_object_key(99)
+        dst = create_memory_obj()
+        tid = adapter.submit_load_task([key], [dst])
+        wait_for_event_fd(adapter.get_load_event_fd())
+        bm = adapter.query_load_result(tid)
+        assert bm is not None and bm.test(0) is False
+
+    def test_load_size_mismatch_returns_zero_bit(
+        self,
+        adapter: HFBucketL2Adapter,
+        fake_client: _FakeBucketClient,
+    ) -> None:
+        key = create_object_key(7)
+        object_path = bucket_path_for_key(key)
+        fake_client.storage[object_path] = b"too-small"
+
+        dst = create_memory_obj()
+        tid = adapter.submit_load_task([key], [dst])
+        wait_for_event_fd(adapter.get_load_event_fd())
+        bm = adapter.query_load_result(tid)
+        assert bm is not None and bm.test(0) is False
+
+    def test_query_lookup_returns_none_after_pop(
+        self,
+        adapter: HFBucketL2Adapter,
+    ) -> None:
+        key = create_object_key(1)
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        assert adapter.query_lookup_and_lock_result(tid) is not None
+        assert adapter.query_lookup_and_lock_result(tid) is None
+
+    def test_partial_store_failure_accounts_written_keys(
+        self,
+        adapter: HFBucketL2Adapter,
+        fake_client: _FakeBucketClient,
+    ) -> None:
+        fake_client.fail_upload_after = 1
+        keys = [create_object_key(0), create_object_key(1)]
+        objs = [create_memory_obj(), create_memory_obj()]
+
+        tid = adapter.submit_store_task(keys, objs)
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        assert not adapter.pop_completed_store_tasks()[tid].is_successful()
+
+        assert fake_client.contains(bucket_path_for_key(keys[0]))
+        assert not fake_client.contains(bucket_path_for_key(keys[1]))
+        assert adapter.get_usage().total_bytes_used == 64
+
+
+class TestEviction:
+    def _store(self, adapter: HFBucketL2Adapter, key: ObjectKey) -> None:
+        adapter.submit_store_task([key], [create_memory_obj()])
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+    def _lookup(self, adapter: HFBucketL2Adapter, key: ObjectKey):
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        return adapter.query_lookup_and_lock_result(tid)
+
+    def test_delete_removes_key(
+        self,
+        adapter: HFBucketL2Adapter,
+        fake_client: _FakeBucketClient,
+    ) -> None:
+        key = create_object_key(1)
+        self._store(adapter, key)
+        object_path = bucket_path_for_key(key)
+        assert fake_client.contains(object_path)
+
+        adapter.delete([key])
+        assert not fake_client.contains(object_path)
+
+    def test_lock_blocks_delete(
+        self,
+        adapter: HFBucketL2Adapter,
+        fake_client: _FakeBucketClient,
+    ) -> None:
+        key = create_object_key(1)
+        self._store(adapter, key)
+        bm = self._lookup(adapter, key)
+        assert bm is not None and bm.test(0) is True
+
+        deletes_before = len(fake_client.deleted_paths)
+        adapter.delete([key])
+        assert len(fake_client.deleted_paths) == deletes_before
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        object_path = bucket_path_for_key(key)
+        assert not fake_client.contains(object_path)
+
+    def test_refcount_unlock(
+        self,
+        adapter: HFBucketL2Adapter,
+        fake_client: _FakeBucketClient,
+    ) -> None:
+        key = create_object_key(1)
+        self._store(adapter, key)
+        self._lookup(adapter, key)
+        self._lookup(adapter, key)
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        object_path = bucket_path_for_key(key)
+        assert fake_client.contains(object_path)
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        assert not fake_client.contains(object_path)
+
+    def test_delete_on_unknown_key(self, adapter: HFBucketL2Adapter) -> None:
+        adapter.delete([create_object_key(42)])
+
+
+class TestGetUsage:
+    def test_disabled_returns_minus_one(self, tmp_path: Path) -> None:
+        cfg = HFBucketL2AdapterConfig(
+            bucket_handle="hf://buckets/test-org/test-bucket",
+            download_tmp_dir=str(tmp_path),
+            max_capacity_gb=0.0,
+        )
+        adapter = HFBucketL2Adapter(cfg, bucket_client=_FakeBucketClient())
+        try:
+            usage = adapter.get_usage()
+            # 0/0 is defined as -1.0 to indicate disabled
+            assert usage.usage_fraction == -1.0
+            assert usage.total_bytes_used == 0
+            assert usage.total_capacity_bytes == 0
+        finally:
+            adapter.close()
+
+    def test_usage_grows_on_store_and_shrinks_on_delete(
+        self,
+        adapter: HFBucketL2Adapter,
+    ) -> None:
+        keys = [create_object_key(i) for i in range(4)]
+        objs = [create_memory_obj() for _ in range(4)]
+
+        adapter.submit_store_task(keys, objs)
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+        total = 4 * 64
+        capacity = int(0.001 * 1024**3)
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == total
+        assert usage.total_capacity_bytes == capacity
+        assert usage.usage_fraction == pytest.approx(total / capacity)
+
+        adapter.delete(keys)
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 0
+        assert usage.usage_fraction == 0.0
+
+
+class TestListener:
+    def test_stored_accessed_and_deleted_fire(
+        self,
+        adapter: HFBucketL2Adapter,
+    ) -> None:
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        key = create_object_key(1)
+        adapter.submit_store_task([key], [create_memory_obj()])
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+        time.sleep(0.05)
+        assert any(key in batch for batch in listener.stored)
+
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        adapter.query_lookup_and_lock_result(tid)
+        time.sleep(0.05)
+        assert any(key in batch for batch in listener.accessed)
+        accessed_count = len(listener.accessed)
+
+        dst = create_memory_obj(fill_value=0.0)
+        tid = adapter.submit_load_task([key], [dst])
+        wait_for_event_fd(adapter.get_load_event_fd())
+        adapter.query_load_result(tid)
+        time.sleep(0.05)
+        assert len(listener.accessed) == accessed_count
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        assert any(key in batch for batch in listener.deleted)
+
+
+class TestConfig:
+    def test_from_dict_requires_bucket_handle(self) -> None:
+        with pytest.raises(ValueError):
+            HFBucketL2AdapterConfig.from_dict({"type": "hfbucket"})
+
+    def test_from_dict_parses_all_fields(self) -> None:
+        cfg = HFBucketL2AdapterConfig.from_dict(
+            {
+                "type": "hfbucket",
+                "bucket_handle": _TEST_BUCKET_HANDLE,
+                "token_env": "HF_TEST_TOKEN",
+                "token": "direct-token",
+                "create_bucket_if_missing": True,
+                "download_tmp_dir": "/tmp/hf",
+                "metadata_cache_ttl_secs": 12.5,
+                "num_workers": 8,
+                "max_capacity_gb": 2.5,
+            }
+        )
+        assert cfg.bucket_handle == _TEST_BUCKET_HANDLE
+        assert cfg.bucket_location.bucket_id == "test-org/test-bucket"
+        assert cfg.bucket_location.object_prefix == "prod"
+        assert cfg.token_env == "HF_TEST_TOKEN"
+        assert cfg.token == "direct-token"
+        assert cfg.create_bucket_if_missing is True
+        assert cfg.download_tmp_dir == Path("/tmp/hf")
+        assert cfg.metadata_cache_ttl_secs == 12.5
+        assert cfg.num_workers == 8
+        assert cfg.max_capacity_gb == 2.5
+
+    # strict boolean parsing
+    def test_from_dict_rejects_string_boolean(self) -> None:
+        with pytest.raises(ValueError, match="create_bucket_if_missing"):
+            HFBucketL2AdapterConfig.from_dict(
+                {
+                    "type": "hfbucket",
+                    "bucket_handle": _TEST_BUCKET_HANDLE,
+                    "create_bucket_if_missing": "false",
+                }
+            )
+
+    def test_help_nonempty(self) -> None:
+        assert isinstance(HFBucketL2AdapterConfig.help(), str)
+        assert "bucket_handle" in HFBucketL2AdapterConfig.help()
+
+
+class TestFactoryRegistration:
+    def test_create_l2_adapter_registers_hfbucket(
+        self,
+        monkeypatch,
+        tmp_path: Path,
+    ) -> None:
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+
+        monkeypatch.setattr(
+            hfmod,
+            "HFBucketClient",
+            lambda token=None: _FakeBucketClient(),
+        )
+        cfg = HFBucketL2AdapterConfig.from_dict(
+            {
+                "type": "hfbucket",
+                "bucket_handle": _TEST_BUCKET_HANDLE,
+                "download_tmp_dir": str(tmp_path),
+                "num_workers": 1,
+            }
+        )
+        adapter = create_l2_adapter(cfg)
+        try:
+            assert isinstance(adapter, HFBucketL2Adapter)
+        finally:
+            adapter.close()
+
+
+class TestCleanup:
+    def test_close_cleans_temp_dir(
+        self,
+        tmp_path: Path,
+        fake_client: _FakeBucketClient,
+    ) -> None:
+        cfg = HFBucketL2AdapterConfig(
+            bucket_handle=_TEST_BUCKET_HANDLE,
+            download_tmp_dir=str(tmp_path),
+        )
+        adapter = HFBucketL2Adapter(cfg, bucket_client=fake_client)
+        assert list(tmp_path.iterdir())
+
+        adapter.close()
+
+        assert list(tmp_path.iterdir()) == []
diff --git a/tests/v1/distributed/test_isolated_lru_eviction_policy.py b/tests/v1/distributed/test_isolated_lru_eviction_policy.py
new file mode 100644
index 0000000..3ebbde5
--- /dev/null
+++ b/tests/v1/distributed/test_isolated_lru_eviction_policy.py
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for :class:`IsolatedLRUEvictionPolicy`.
+"""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.eviction_policy.isolated_lru import (
+    IsolatedLRUEvictionPolicy,
+)
+from lmcache.v1.distributed.internal_api import EvictionDestination
+
+
+def _key(chunk_id: int, cache_salt: str = "") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="m",
+        kv_rank=0,
+        cache_salt=cache_salt,
+    )
+
+
+class TestSupportIsolation:
+    def test_support_isolation_is_true(self):
+        """``IsolatedLRUEvictionPolicy`` reports isolation support so
+        the controller routes to the by-cache_salt eviction branch."""
+        assert IsolatedLRUEvictionPolicy().support_isolation is True
+
+
+class TestPerSaltTracking:
+    def test_keys_bucketed_by_salt(self):
+        """Each ``cache_salt`` lives in its own LRU list; buckets do
+        not bleed into each other."""
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(1, "alice"), _key(2, "bob"), _key(3, "alice")])
+        assert p.get_num_tracked_keys("alice") == 2
+        assert p.get_num_tracked_keys("bob") == 1
+        assert p.get_num_tracked_keys("charlie") == 0
+        assert sorted(p.get_tracked_salts()) == ["alice", "bob"]
+
+    def test_empty_bucket_dropped_after_removal(self):
+        """When a bucket empties the policy forgets the salt entirely
+        — keeps status / list snapshots compact."""
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(1, "alice")])
+        p.on_keys_removed([_key(1, "alice")])
+        assert "alice" not in p.get_tracked_salts()
+
+    def test_touch_updates_order(self):
+        """Touching a key moves it to MRU. After ``on_keys_created``
+        the reversed-insertion rule leaves ``k2`` as LRU (first out).
+        Touching ``k2`` must promote it so ``k1`` becomes the LRU
+        victim — this specifically exercises ``move_to_end`` on an
+        existing entry (a no-op touch on the already-MRU key would
+        pass the test trivially and hide bugs in the touch path)."""
+        p = IsolatedLRUEvictionPolicy()
+        k1 = _key(1, "alice")
+        k2 = _key(2, "alice")
+        p.on_keys_created([k1, k2])
+        # Default LRU order now: [k2 (oldest), k1 (newest)].
+        p.on_keys_touched([k2])
+        # Expected after touch: [k1 (oldest), k2 (newest)].
+        actions = p.get_eviction_actions(expected_ratio=0.5, cache_salt="alice")
+        evicted = actions[0].keys
+        assert evicted == [k1], (
+            f"k1 should be LRU after touching k2; got {[k.chunk_hash for k in evicted]}"
+        )
+
+
+class TestScopedEviction:
+    def test_scoped_eviction_stays_in_bucket(self):
+        """Eviction scoped to a salt only returns keys from that
+        bucket — other salts' data is untouched."""
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(1, "alice"), _key(2, "bob"), _key(3, "alice")])
+        actions = p.get_eviction_actions(expected_ratio=1.0, cache_salt="alice")
+        assert len(actions) == 1
+        evicted_salts = {k.cache_salt for k in actions[0].keys}
+        assert evicted_salts == {"alice"}
+        assert len(actions[0].keys) == 2
+
+    def test_scoped_eviction_empty_bucket_returns_empty(self):
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(1, "alice")])
+        # No bob bucket yet.
+        actions = p.get_eviction_actions(expected_ratio=1.0, cache_salt="bob")
+        assert actions == []
+
+    def test_missing_cache_salt_raises(self):
+        """``IsolatedLRU`` is per-bucket only — calling without an
+        explicit ``cache_salt`` raises ``ValueError`` rather than
+        silently falling back to a global pool."""
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(1, "alice")])
+        with pytest.raises(ValueError, match="cache_salt"):
+            p.get_eviction_actions(expected_ratio=1.0, cache_salt=None)
+
+
+class TestEvictionAmount:
+    def test_at_least_one_when_ratio_positive(self):
+        """Matches ``LRUEvictionPolicy`` — a positive ratio that rounds
+        to zero still yields one eviction so the caller makes forward
+        progress."""
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(i, "alice") for i in range(3)])
+        actions = p.get_eviction_actions(expected_ratio=0.01, cache_salt="alice")
+        assert len(actions[0].keys) == 1
+
+    def test_zero_ratio_evicts_nothing(self):
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(i, "alice") for i in range(3)])
+        assert p.get_eviction_actions(expected_ratio=0.0, cache_salt="alice") == []
+
+    def test_eviction_destination_default_is_discard(self):
+        p = IsolatedLRUEvictionPolicy()
+        p.on_keys_created([_key(1, "alice")])
+        actions = p.get_eviction_actions(expected_ratio=1.0, cache_salt="alice")
+        assert actions[0].destination == EvictionDestination.DISCARD
+
+    def test_key_eligible_filter_skips_locked_keys(self):
+        """The filter is useful for skipping pinned / locked keys. Any
+        key for which the filter returns False should be bypassed when
+        choosing victims."""
+        p = IsolatedLRUEvictionPolicy()
+        k1 = _key(1, "alice")
+        k2 = _key(2, "alice")
+        p.on_keys_created([k1, k2])
+        # Only allow k2 to be evicted.
+        actions = p.get_eviction_actions(
+            expected_ratio=1.0,
+            cache_salt="alice",
+            key_eligible_filter=lambda k: k == k2,
+        )
+        assert actions[0].keys == [k2]
diff --git a/tests/v1/distributed/test_l1_l2_state_metrics.py b/tests/v1/distributed/test_l1_l2_state_metrics.py
new file mode 100644
index 0000000..26f52d9
--- /dev/null
+++ b/tests/v1/distributed/test_l1_l2_state_metrics.py
@@ -0,0 +1,379 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Integration tests for the four L1/L2 state metrics.
+
+Drives real controllers through real state changes and reads back values
+via a process-shared ``InMemoryMetricReader``.  Assertions are on deltas
+so prior tests that exercised the meters don't poison the baseline.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import L1ManagerConfig, L1MemoryManagerConfig
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_controller import (
+    PrefetchController,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_policy import (
+    DefaultPrefetchPolicy,
+)
+from lmcache.v1.distributed.storage_controllers.store_controller import (
+    StoreController,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+    DefaultStorePolicy,
+)
+from lmcache.v1.memory_management import MemoryObjMetadata, TensorMemoryObj
+
+# Importing this sets the process-wide MeterProvider with an
+# InMemoryMetricReader; controllers bind their instruments to it.
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_layout() -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+def make_adapter(bandwidth_gb: float = 10.0) -> MockL2Adapter:
+    config = MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=bandwidth_gb)
+    return MockL2Adapter(config)
+
+
+def make_descriptor(index: int) -> AdapterDescriptor:
+    config = MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0)
+    return AdapterDescriptor(index=index, config=config)
+
+
+def wait_for_condition(predicate, timeout: float = 5.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(0.05)
+    return False
+
+
+def write_keys_to_l1(
+    l1_manager: L1Manager,
+    keys: list[ObjectKey],
+    layout: MemoryLayoutDesc,
+) -> list[ObjectKey]:
+    results = l1_manager.reserve_write(
+        keys=keys,
+        is_temporary=[False] * len(keys),
+        layout_desc=layout,
+        mode="new",
+    )
+    written = [k for k, (e, m) in results.items() if m is not None]
+    if written:
+        l1_manager.finish_write(written)
+    return written
+
+
+def store_keys_in_l2(
+    adapter: MockL2Adapter,
+    keys: list[ObjectKey],
+    layout: MemoryLayoutDesc,
+) -> None:
+    """Push test data into L2 directly so subsequent prefetches hit."""
+    if not keys:
+        return
+    objs = []
+    for _ in keys:
+        tensor = torch.randn(layout.shapes[0], dtype=layout.dtypes[0])
+        metadata = MemoryObjMetadata(
+            shape=layout.shapes[0],
+            dtype=layout.dtypes[0],
+            address=0,
+            phy_size=tensor.nelement() * tensor.element_size(),
+            ref_count=0,
+        )
+        obj = TensorMemoryObj(raw_data=tensor, metadata=metadata, parent_allocator=None)
+        objs.append(obj)
+    adapter.submit_store_task(keys, objs)  # type: ignore[arg-type]
+    assert wait_for_condition(
+        lambda: all(adapter.debug_has_key(k) for k in keys),
+    ), "Failed to seed L2 with test data"
+
+
+def _read_points_by_attrs() -> dict[str, dict[tuple, float]]:
+    """``{metric: {sorted_attrs_tuple: value}}`` from the shared reader."""
+    data = _reader.get_metrics_data()
+    result: dict[str, dict[tuple, float]] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue
+                    key = tuple(sorted(dict(dp.attributes).items()))
+                    result.setdefault(metric.name, {})[key] = dp.value
+    return result
+
+
+def _value_for(metric: str, attrs: dict | None = None) -> float:
+    """Look up the current value of ``metric`` for the exact attribute set."""
+    snapshot = _read_points_by_attrs().get(metric, {})
+    key = tuple(sorted((attrs or {}).items()))
+    return snapshot.get(key, 0)
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def l1_manager():
+    config = L1ManagerConfig(
+        memory_config=L1MemoryManagerConfig(
+            size_in_bytes=128 * 1024 * 1024,
+            use_lazy=True,
+            init_size_in_bytes=64 * 1024 * 1024,
+            align_bytes=0x1000,
+        ),
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+    mgr = L1Manager(config)
+    yield mgr
+    mgr.close()
+
+
+# =============================================================================
+# L1 memory usage gauge
+# =============================================================================
+
+
+class TestL1MemoryUsageGauge:
+    """``lmcache_mp.l1_memory_usage_bytes`` reports current L1 usage."""
+
+    def test_gauge_reports_zero_initially(self, l1_manager):
+        # A fresh L1 with no writes should report 0 used bytes.
+        before = _value_for("lmcache_mp.l1_memory_usage_bytes")
+        assert before == 0
+
+    def test_gauge_grows_after_writes(self, l1_manager):
+        before = _value_for("lmcache_mp.l1_memory_usage_bytes")
+
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        after = _value_for("lmcache_mp.l1_memory_usage_bytes")
+        assert after > before, "Gauge should reflect bytes written to L1"
+
+
+# =============================================================================
+# StoreController in-flight counter
+# =============================================================================
+
+
+class TestNumInflightL2Stores:
+    """``lmcache_mp.num_inflight_l2_stores`` per (l2_name, adapter_index)."""
+
+    def test_counter_balances_to_zero_after_store_cycle(self, l1_manager):
+        adapter = make_adapter()
+        adapter_index = 0
+        attrs = {"l2_name": "mock", "adapter_index": adapter_index}
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(adapter_index)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        before = _value_for("lmcache_mp.num_inflight_l2_stores", attrs)
+
+        layout = make_layout()
+        keys = [make_object_key(100 + i) for i in range(2)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Every store must complete and decrement back to the baseline.
+        assert wait_for_condition(lambda: adapter.debug_get_stored_object_count() == 2)
+        assert wait_for_condition(
+            lambda: _value_for("lmcache_mp.num_inflight_l2_stores", attrs) == before
+        )
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_counter_uses_per_adapter_attribution(self, l1_manager):
+        # Two adapters of the same backend type get distinct datapoints
+        # via adapter_index; their counters return to zero independently.
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(0), make_descriptor(1)]
+        attrs0 = {"l2_name": "mock", "adapter_index": 0}
+        attrs1 = {"l2_name": "mock", "adapter_index": 1}
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,  # type: ignore[arg-type]
+            adapter_descriptors=descriptors,
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        before0 = _value_for("lmcache_mp.num_inflight_l2_stores", attrs0)
+        before1 = _value_for("lmcache_mp.num_inflight_l2_stores", attrs1)
+
+        layout = make_layout()
+        keys = [make_object_key(200 + i) for i in range(3)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Both adapters should have stored every key (DefaultStorePolicy
+        # writes to all) and counters should return to baseline.
+        assert wait_for_condition(
+            lambda: adapters[0].debug_get_stored_object_count() == 3
+            and adapters[1].debug_get_stored_object_count() == 3
+        )
+        assert wait_for_condition(
+            lambda: (
+                _value_for("lmcache_mp.num_inflight_l2_stores", attrs0) == before0
+                and _value_for("lmcache_mp.num_inflight_l2_stores", attrs1) == before1
+            )
+        )
+
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+
+# =============================================================================
+# PrefetchController in-flight counters
+# =============================================================================
+
+
+class TestNumInflightL2Loads:
+    """``num_inflight_l2_loads`` and ``inflight_load_memory_usage_bytes``
+    return to baseline after a successful prefetch cycle."""
+
+    def test_load_counters_balance_to_zero(self, l1_manager):
+        adapter = make_adapter()
+        adapter_index = 0
+        attrs = {"l2_name": "mock", "adapter_index": adapter_index}
+        layout = make_layout()
+        keys = [make_object_key(300 + i) for i in range(4)]
+
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(adapter_index)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        before_loads = _value_for("lmcache_mp.num_inflight_l2_loads", attrs)
+        before_bytes = _value_for("lmcache_mp.inflight_load_memory_usage_bytes", attrs)
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+
+        # Wait for the request to fully resolve, then the counters should
+        # come back to where they started.
+        assert wait_for_condition(
+            lambda: ctrl.query_prefetch_result(req_id) is not None
+        )
+        assert wait_for_condition(
+            lambda: (
+                _value_for("lmcache_mp.num_inflight_l2_loads", attrs) == before_loads
+                and _value_for("lmcache_mp.inflight_load_memory_usage_bytes", attrs)
+                == before_bytes
+            )
+        )
+
+        # Release any read locks so teardown is clean.
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_no_leak_after_shutdown_with_inflight_loads(self, l1_manager):
+        # Slow adapter so the load is still in flight when stop() runs;
+        # the gauge callback reads live state, so once cleanup clears the
+        # in-flight dict the gauges naturally report 0.  We assert via
+        # the metric that the load is observably in-flight before calling
+        # stop(), otherwise the test could pass via normal completion.
+        slow_gb = 0.001  # 1 MB/s — a 200 KB key takes ~200 ms.
+        adapter = make_adapter(bandwidth_gb=slow_gb)
+        adapter_index = 0
+        attrs = {"l2_name": "mock", "adapter_index": adapter_index}
+        layout = make_layout()
+        keys = [make_object_key(400 + i) for i in range(4)]
+
+        # Seed L2 (also slow at this bandwidth, so allow plenty of time).
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(adapter_index)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        before_loads = _value_for("lmcache_mp.num_inflight_l2_loads", attrs)
+        before_bytes = _value_for("lmcache_mp.inflight_load_memory_usage_bytes", attrs)
+
+        ctrl.submit_prefetch_request(keys, layout)
+
+        # Wait until the load is actually in flight on this adapter; only
+        # then is ``_cleanup_in_flight_requests`` the path that brings the
+        # counters back down.  Without this wait, the test could pass via
+        # the normal completion path instead.
+        assert wait_for_condition(
+            lambda: (
+                _value_for("lmcache_mp.num_inflight_l2_loads", attrs) > before_loads
+            ),
+            timeout=10.0,
+        ), "Load never entered the in-flight state"
+        assert (
+            _value_for("lmcache_mp.inflight_load_memory_usage_bytes", attrs)
+            > before_bytes
+        )
+
+        # Stop while the load is still in flight; cleanup must decrement.
+        ctrl.stop()
+
+        assert _value_for("lmcache_mp.num_inflight_l2_loads", attrs) == before_loads
+        assert (
+            _value_for("lmcache_mp.inflight_load_memory_usage_bytes", attrs)
+            == before_bytes
+        )
+
+        adapter.close()
diff --git a/tests/v1/distributed/test_l1_manager.py b/tests/v1/distributed/test_l1_manager.py
new file mode 100644
index 0000000..a73ce3e
--- /dev/null
+++ b/tests/v1/distributed/test_l1_manager.py
@@ -0,0 +1,1938 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for L1Manager.
+
+These tests verify the behavior of L1Manager as described in the
+interface docstrings. The tests focus on:
+
+1. reserve_read() - Reserve read access for given keys
+   - Returns KEY_NOT_EXIST if key does not exist
+   - Returns KEY_NOT_READABLE if key exists but is write-locked
+   - Returns SUCCESS and MemoryObj if key is readable
+
+2. unsafe_read() - Unsafe read without acquiring new read locks
+   - Returns KEY_NOT_EXIST if key does not exist
+   - Returns KEY_NOT_READABLE if key is not read-locked
+   - Returns SUCCESS and MemoryObj if key is read-locked
+
+3. finish_read() - Finish read access for given keys
+   - Returns KEY_NOT_EXIST if key does not exist
+   - Returns KEY_IN_WRONG_STATE if key is write-locked or non-read-locked
+   - Returns SUCCESS on successful unlock
+   - Deletes temporary objects when read count reaches zero
+
+4. reserve_write() - Reserve write access for given keys
+   - Returns KEY_NOT_WRITABLE if key exists but cannot be written
+   - Returns OUT_OF_MEMORY if allocation fails
+   - Returns SUCCESS and MemoryObj on success
+
+5. finish_write() - Finish write access for given keys
+   - Returns KEY_NOT_EXIST if key does not exist
+   - Returns KEY_IN_WRONG_STATE if not write-locked or read-locked
+   - Returns SUCCESS on successful unlock
+
+6. delete() - Delete keys from L1 cache
+   - Returns KEY_NOT_EXIST if key does not exist
+   - Returns KEY_IS_LOCKED if key is locked
+   - Returns SUCCESS on successful deletion
+
+7. get_object_state() - Debugging API to get internal state
+
+8. close() - Close the L1Manager and free all resources
+"""
+
+# Standard
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+)
+from lmcache.v1.distributed.error import L1Error
+
+try:
+    # First Party
+    from lmcache.v1.distributed.l1_manager import L1Manager
+except ImportError:
+    # Skip tests if L1Manager cannot be imported
+    pytest.skip(
+        "Skipping because L1 manager cannot be imported", allow_module_level=True
+    )
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+def should_use_lazy_alloc() -> bool:
+    """Determine if lazy allocation should be used based on CUDA availability."""
+    return torch.cuda.is_available()
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def basic_memory_config():
+    """Create a basic L1MemoryManagerConfig for testing."""
+    return L1MemoryManagerConfig(
+        size_in_bytes=128 * 1024 * 1024,  # 128MB
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64 * 1024 * 1024,  # 64MB
+        align_bytes=0x1000,  # 4KB
+    )
+
+
+@pytest.fixture
+def small_memory_config():
+    """Create a small L1MemoryManagerConfig to test memory exhaustion."""
+    return L1MemoryManagerConfig(
+        size_in_bytes=64 * 1024 * 1024,  # 64MB
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64 * 1024 * 1024,  # 64MB
+        align_bytes=0x1000,
+    )
+
+
+@pytest.fixture
+def basic_l1_config(basic_memory_config):
+    """Create a basic L1ManagerConfig for testing."""
+    return L1ManagerConfig(
+        memory_config=basic_memory_config,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+
+
+@pytest.fixture
+def small_l1_config(small_memory_config):
+    """Create a small L1ManagerConfig to test memory exhaustion."""
+    return L1ManagerConfig(
+        memory_config=small_memory_config,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+
+
+@pytest.fixture
+def basic_layout():
+    """Create a basic MemoryLayoutDesc for testing."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+@pytest.fixture
+def large_layout():
+    """Create a large MemoryLayoutDesc that will exhaust small memory.
+
+    Each allocation is 8MB (2M elements * 4 bytes).
+    """
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([2048, 1024])],  # 2M elements * 4 bytes = 8MB
+        dtypes=[torch.float32],
+    )
+
+
+def make_object_key(chunk_hash: int, model_name: str = "test_model", kv_rank: int = 0):
+    """Helper to create ObjectKey instances."""
+    hash_bytes = ObjectKey.IntHash2Bytes(chunk_hash)
+    return ObjectKey(chunk_hash=hash_bytes, model_name=model_name, kv_rank=kv_rank)
+
+
+# =============================================================================
+# Tests for L1Manager.reserve_read()
+# =============================================================================
+
+
+class TestReserveRead:
+    """
+    Tests for L1Manager.reserve_read() method.
+
+    Per the docstring:
+    - KEY_NOT_EXIST: The key does not exist.
+    - KEY_NOT_READABLE: The key exists but is not readable.
+    - Returns (L1Error, Optional[MemoryObj]) for each key.
+    """
+
+    def test_reserve_read_non_existing_key_returns_key_not_exist(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that reserve_read returns KEY_NOT_EXIST for non-existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.reserve_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_NOT_EXIST
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_reserve_read_write_locked_key_returns_key_not_readable(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that reserve_read returns KEY_NOT_READABLE for write-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Reserve write (but don't finish) - key is now write-locked
+        write_result = manager.reserve_write([key], [False], basic_layout)
+        assert write_result[key][0] == L1Error.SUCCESS
+
+        # Try to reserve read on a write-locked key
+        read_result = manager.reserve_read([key])
+
+        assert key in read_result
+        error, mem_obj = read_result[key]
+        assert error == L1Error.KEY_NOT_READABLE
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_reserve_read_ready_key_returns_success(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that reserve_read returns SUCCESS for ready (unlocked) keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create object: reserve write -> finish write
+        write_result = manager.reserve_write([key], [False], basic_layout)
+        assert write_result[key][0] == L1Error.SUCCESS
+        finish_result = manager.finish_write([key])
+        assert finish_result[key] == L1Error.SUCCESS
+
+        # Now reserve read
+        read_result = manager.reserve_read([key])
+
+        assert key in read_result
+        error, mem_obj = read_result[key]
+        assert error == L1Error.SUCCESS
+        assert mem_obj is not None
+        assert mem_obj.is_valid()
+
+        manager.close()
+
+    def test_reserve_read_multiple_keys(self, basic_l1_config, basic_layout):
+        """Test reserve_read with multiple keys in a single call."""
+        manager = L1Manager(basic_l1_config)
+        key1 = make_object_key(1)
+        key2 = make_object_key(2)
+        key3 = make_object_key(3)
+
+        # Create key1 as ready object
+        manager.reserve_write([key1], [False], basic_layout)
+        manager.finish_write([key1])
+
+        # key2 does not exist
+        # key3 is write-locked
+        manager.reserve_write([key3], [False], basic_layout)
+
+        # Reserve read on all three
+        result = manager.reserve_read([key1, key2, key3])
+
+        assert result[key1][0] == L1Error.SUCCESS
+        assert result[key1][1] is not None
+        assert result[key2][0] == L1Error.KEY_NOT_EXIST
+        assert result[key2][1] is None
+        assert result[key3][0] == L1Error.KEY_NOT_READABLE
+        assert result[key3][1] is None
+
+        manager.close()
+
+    def test_reserve_read_can_be_called_multiple_times(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that multiple read reservations can be made on the same key."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Multiple read reservations
+        result1 = manager.reserve_read([key])
+        result2 = manager.reserve_read([key])
+        result3 = manager.reserve_read([key])
+
+        assert result1[key][0] == L1Error.SUCCESS
+        assert result2[key][0] == L1Error.SUCCESS
+        assert result3[key][0] == L1Error.SUCCESS
+
+        # Verify using get_object_state that read lock is held
+        state = manager.get_object_state(key)
+        assert state is not None
+        # Check via available_for_read (should still be true since
+        # read-locked is readable)
+        assert state.available_for_read() is True
+
+        manager.close()
+
+    def test_reserve_read_with_extra_count(self, basic_l1_config, basic_layout):
+        """Test reserve_read(extra_count=N) acquires 1+N locks."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve with extra_count=2 -> total 3 locks
+        result = manager.reserve_read([key], extra_count=2)
+        assert result[key][0] == L1Error.SUCCESS
+        assert result[key][1] is not None
+
+        # Need 3 finish_read() to fully release
+        manager.finish_read([key])
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert state.read_lock.is_locked()
+
+        manager.finish_read([key])
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert state.read_lock.is_locked()
+
+        manager.finish_read([key])
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert not state.read_lock.is_locked()
+
+        manager.close()
+
+    def test_reserve_read_extra_count_default_is_zero(
+        self, basic_l1_config, basic_layout
+    ):
+        """Default extra_count=0 acquires exactly 1 lock."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        manager.reserve_read([key])
+        manager.finish_read([key])
+
+        # Lock fully released after single finish_read
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert not state.read_lock.is_locked()
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.unsafe_read()
+# =============================================================================
+
+
+class TestUnsafeRead:
+    """
+    Tests for L1Manager.unsafe_read() method.
+
+    Per the docstring:
+    - This method does not acquire read locks.
+    - Caller must ensure unsafe_read is called between reserve_read and finish_read.
+    - KEY_NOT_EXIST: The key does not exist.
+    - KEY_NOT_READABLE: The key is not readable (not read-locked).
+    - Returns (L1Error, Optional[MemoryObj]) for each key.
+    """
+
+    def test_unsafe_read_non_existing_key_returns_key_not_exist(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that unsafe_read returns KEY_NOT_EXIST for non-existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.unsafe_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_NOT_EXIST
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_unsafe_read_non_read_locked_returns_key_not_readable(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that unsafe_read returns KEY_NOT_READABLE if not read-locked."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object (not read-locked)
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Try unsafe_read without reserve_read
+        result = manager.unsafe_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_NOT_READABLE
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_unsafe_read_write_locked_returns_key_not_readable(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that unsafe_read returns KEY_NOT_READABLE for write-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create write-locked object
+        manager.reserve_write([key], [False], basic_layout)
+
+        # Try unsafe_read on write-locked key
+        result = manager.unsafe_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_NOT_READABLE
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_unsafe_read_read_locked_returns_success(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that unsafe_read returns SUCCESS for read-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object and reserve read
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+        reserve_result = manager.reserve_read([key])
+        assert reserve_result[key][0] == L1Error.SUCCESS
+
+        # unsafe_read should succeed on read-locked key
+        result = manager.unsafe_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.SUCCESS
+        assert mem_obj is not None
+        assert mem_obj.is_valid()
+
+        manager.close()
+
+    def test_unsafe_read_returns_same_memory_obj_as_reserve_read(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that unsafe_read returns the same MemoryObj as reserve_read."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read and get memory object
+        reserve_result = manager.reserve_read([key])
+        assert reserve_result[key][0] == L1Error.SUCCESS
+        reserved_mem_obj = reserve_result[key][1]
+
+        # unsafe_read should return the same memory object
+        unsafe_result = manager.unsafe_read([key])
+        assert unsafe_result[key][0] == L1Error.SUCCESS
+        unsafe_mem_obj = unsafe_result[key][1]
+
+        # Should be the same object
+        assert reserved_mem_obj is unsafe_mem_obj
+
+        manager.close()
+
+    def test_unsafe_read_multiple_times_without_adding_read_count(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that multiple unsafe_reads don't add to read lock count."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read once
+        manager.reserve_read([key])
+
+        # Multiple unsafe_reads
+        for _ in range(5):
+            result = manager.unsafe_read([key])
+            assert result[key][0] == L1Error.SUCCESS
+
+        # Single finish_read should release the lock and delete temp object
+        manager.finish_read([key])
+
+        # Object should be deleted (only 1 read lock was held, not 6)
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_unsafe_read_multiple_keys(self, basic_l1_config, basic_layout):
+        """Test unsafe_read with multiple keys in a single call."""
+        manager = L1Manager(basic_l1_config)
+        key1 = make_object_key(1)
+        key2 = make_object_key(2)
+        key3 = make_object_key(3)
+
+        # key1: read-locked
+        manager.reserve_write([key1], [False], basic_layout)
+        manager.finish_write([key1])
+        manager.reserve_read([key1])
+
+        # key2: does not exist
+
+        # key3: ready but not read-locked
+        manager.reserve_write([key3], [False], basic_layout)
+        manager.finish_write([key3])
+
+        # unsafe_read on all three
+        result = manager.unsafe_read([key1, key2, key3])
+
+        assert result[key1][0] == L1Error.SUCCESS
+        assert result[key1][1] is not None
+        assert result[key2][0] == L1Error.KEY_NOT_EXIST
+        assert result[key2][1] is None
+        assert result[key3][0] == L1Error.KEY_NOT_READABLE
+        assert result[key3][1] is None
+
+        manager.close()
+
+    def test_unsafe_read_between_reserve_and_finish(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test proper usage: unsafe_read between reserve_read and finish_read."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Proper workflow: reserve_read -> unsafe_read -> finish_read
+        reserve_result = manager.reserve_read([key])
+        assert reserve_result[key][0] == L1Error.SUCCESS
+
+        unsafe_result = manager.unsafe_read([key])
+        assert unsafe_result[key][0] == L1Error.SUCCESS
+        assert unsafe_result[key][1] is not None
+
+        finish_result = manager.finish_read([key])
+        assert finish_result[key] == L1Error.SUCCESS
+
+        # After finish_read, unsafe_read should fail (not read-locked)
+        result = manager.unsafe_read([key])
+        assert result[key][0] == L1Error.KEY_NOT_READABLE
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.finish_read()
+# =============================================================================
+
+
+class TestFinishRead:
+    """
+    Tests for L1Manager.finish_read() method.
+
+    Per the docstring:
+    - KEY_NOT_EXIST: The key does not exist.
+    - KEY_IN_WRONG_STATE: The key is write-locked or non-read-locked.
+    - Will delete the object if it is temporary and read count reaches zero.
+    """
+
+    def test_finish_read_non_existing_key_returns_key_not_exist(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that finish_read returns KEY_NOT_EXIST for non-existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.finish_read([key])
+
+        assert key in result
+        assert result[key] == L1Error.KEY_NOT_EXIST
+
+        manager.close()
+
+    def test_finish_read_success(self, basic_l1_config, basic_layout):
+        """Test that finish_read returns SUCCESS after proper read reservation."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read, then finish read
+        manager.reserve_read([key])
+        result = manager.finish_read([key])
+
+        assert result[key] == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_finish_read_non_read_locked_returns_wrong_state(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that finish_read returns KEY_IN_WRONG_STATE if not read-locked."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object (not read-locked)
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Try to finish read without reserving
+        result = manager.finish_read([key])
+
+        assert result[key] == L1Error.KEY_IN_WRONG_STATE
+
+        manager.close()
+
+    def test_finish_read_write_locked_returns_wrong_state(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that finish_read returns KEY_IN_WRONG_STATE if write-locked."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create write-locked object
+        manager.reserve_write([key], [False], basic_layout)
+
+        # Try to finish read on write-locked key
+        result = manager.finish_read([key])
+
+        assert result[key] == L1Error.KEY_IN_WRONG_STATE
+
+        manager.close()
+
+    def test_finish_read_temporary_object_deleted_when_count_zero(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that temporary objects are deleted when read count reaches zero."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)  # is_temporary=True
+        manager.finish_write([key])
+
+        # Reserve read
+        manager.reserve_read([key])
+
+        # Verify object exists
+        assert manager.get_object_state(key) is not None
+
+        # Finish read - should delete the temporary object
+        result = manager.finish_read([key])
+        assert result[key] == L1Error.SUCCESS
+
+        # Verify object is deleted
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_finish_read_multiple_reads_count_down(self, basic_l1_config, basic_layout):
+        """Test that multiple finish_reads count down properly."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read three times
+        manager.reserve_read([key])
+        manager.reserve_read([key])
+        manager.reserve_read([key])
+
+        # Finish read twice - object should still exist
+        manager.finish_read([key])
+        manager.finish_read([key])
+        assert manager.get_object_state(key) is not None
+
+        # Finish read third time - temporary object should be deleted
+        manager.finish_read([key])
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_finish_read_with_extra_count_releases_multiple(
+        self, basic_l1_config, basic_layout
+    ):
+        """finish_read(extra_count=2) releases 3 locks at once."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Acquire 3 read locks (1 + extra_count=2)
+        manager.reserve_read([key], extra_count=2)
+
+        # Release all 3 at once
+        result = manager.finish_read([key], extra_count=2)
+        assert result[key] == L1Error.SUCCESS
+
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert not state.read_lock.is_locked()
+
+        manager.close()
+
+    def test_finish_read_extra_count_partial_release(
+        self, basic_l1_config, basic_layout
+    ):
+        """Partial extra_count release leaves remaining locks."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # 3 locks total (1 + extra_count=2)
+        manager.reserve_read([key], extra_count=2)
+
+        # Release 2 of 3 (1 + extra_count=1)
+        manager.finish_read([key], extra_count=1)
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert state.read_lock.is_locked()
+
+        # Release last one (1 + extra_count=0)
+        manager.finish_read([key])
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert not state.read_lock.is_locked()
+
+        manager.close()
+
+    def test_finish_read_extra_count_deletes_temporary(
+        self, basic_l1_config, basic_layout
+    ):
+        """Temp objects deleted when extra_count releases all."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        # Acquire 3 read locks at once (1 + extra_count=2)
+        manager.reserve_read([key], extra_count=2)
+        assert manager.get_object_state(key) is not None
+
+        # Release all 3 at once -> temp deleted
+        result = manager.finish_read([key], extra_count=2)
+        assert result[key] == L1Error.SUCCESS
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_finish_read_extra_count_temp_survives_partial(
+        self, basic_l1_config, basic_layout
+    ):
+        """Temp object survives partial extra_count release."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        # 4 locks total (1 + extra_count=3)
+        manager.reserve_read([key], extra_count=3)
+
+        # Release 2 of 4 -> still locked
+        manager.finish_read([key], extra_count=1)
+        assert manager.get_object_state(key) is not None
+
+        # Release remaining 2 -> deleted
+        manager.finish_read([key], extra_count=1)
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.reserve_write()
+# =============================================================================
+
+
+class TestReserveWrite:
+    """
+    Tests for L1Manager.reserve_write() method.
+
+    Per the docstring:
+    - KEY_NOT_WRITABLE: The key exists but is not writable.
+    - OUT_OF_MEMORY: Not enough memory to allocate for the object.
+    - Returns (L1Error, Optional[MemoryObj]) for each key.
+    """
+
+    def test_reserve_write_new_key_returns_success(self, basic_l1_config, basic_layout):
+        """Test that reserve_write returns SUCCESS for new keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.reserve_write([key], [False], basic_layout)
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.SUCCESS
+        assert mem_obj is not None
+        assert mem_obj.is_valid()
+
+        manager.close()
+
+    def test_reserve_write_write_locked_key_returns_not_writable(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that reserve_write returns KEY_NOT_WRITABLE for write-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # First reserve write
+        result1 = manager.reserve_write([key], [False], basic_layout)
+        assert result1[key][0] == L1Error.SUCCESS
+
+        # Try to reserve write again while still write-locked
+        result2 = manager.reserve_write([key], [False], basic_layout)
+
+        assert result2[key][0] == L1Error.KEY_NOT_WRITABLE
+        assert result2[key][1] is None
+
+        manager.close()
+
+    def test_reserve_write_read_locked_key_returns_not_writable(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that reserve_write returns KEY_NOT_WRITABLE for read-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read
+        manager.reserve_read([key])
+
+        # Try to reserve write while read-locked
+        result = manager.reserve_write([key], [False], basic_layout)
+
+        assert result[key][0] == L1Error.KEY_NOT_WRITABLE
+        assert result[key][1] is None
+
+        manager.close()
+
+    def test_reserve_write_temporary_key_returns_not_writable(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that reserve_write returns KEY_NOT_WRITABLE for temporary objects."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)  # is_temporary=True
+        manager.finish_write([key])
+
+        # Try to reserve write on temporary object
+        result = manager.reserve_write([key], [False], basic_layout)
+
+        assert result[key][0] == L1Error.KEY_NOT_WRITABLE
+
+        manager.close()
+
+    def test_reserve_write_multiple_keys(self, basic_l1_config, basic_layout):
+        """Test reserve_write with multiple keys in a single call."""
+        manager = L1Manager(basic_l1_config)
+        keys = [make_object_key(i) for i in range(5)]
+        is_temporary = [False] * 5
+
+        result = manager.reserve_write(keys, is_temporary, basic_layout)
+
+        for key in keys:
+            assert key in result
+            error, mem_obj = result[key]
+            assert error == L1Error.SUCCESS
+            assert mem_obj is not None
+
+        manager.close()
+
+    def test_reserve_write_out_of_memory(self, small_l1_config, large_layout):
+        """Test that reserve_write returns OUT_OF_MEMORY when allocation fails."""
+        manager = L1Manager(small_l1_config)
+        keys = [make_object_key(i) for i in range(10)]
+        is_temporary = [False] * 10
+
+        # Request more memory than available (8MB * 10 = 80MB > 64MB)
+        result = manager.reserve_write(keys, is_temporary, large_layout)
+
+        # All keys should return OUT_OF_MEMORY
+        for key in keys:
+            assert result[key][0] == L1Error.OUT_OF_MEMORY
+            assert result[key][1] is None
+
+        manager.close()
+
+    def test_reserve_write_new_mode(self, basic_l1_config, basic_layout):
+        """Test that reserve_write returns KEY_NOT_WRITABLE for existing keys."""
+        manager = L1Manager(basic_l1_config)
+        keys = [make_object_key(i) for i in range(5)]
+        is_temporary = [False] * 5
+
+        result = manager.reserve_write(keys, is_temporary, basic_layout, mode="new")
+
+        for key in keys:
+            assert result[key][0] == L1Error.SUCCESS
+            assert result[key][1] is not None
+
+        # Commit the write
+        result = manager.finish_write(keys)
+        for key in keys:
+            assert result[key] == L1Error.SUCCESS
+
+        # Now try to reserve write again with mode="new"
+        result = manager.reserve_write(keys, is_temporary, basic_layout, mode="new")
+        for key in keys:
+            assert result[key][0] == L1Error.KEY_NOT_WRITABLE
+            assert result[key][1] is None
+
+        manager.close()
+
+    def test_reserve_write_update_mode(self, basic_l1_config, basic_layout):
+        """Test that reserve_write returns KEY_NOT_WRITABLE for new keys."""
+        manager = L1Manager(basic_l1_config)
+        keys = [make_object_key(i) for i in range(5)]
+        is_temporary = [False] * 5
+
+        result = manager.reserve_write(keys, is_temporary, basic_layout, mode="update")
+        for key in keys:
+            assert result[key][0] == L1Error.KEY_NOT_WRITABLE
+            assert result[key][1] is None
+
+        # Cannot finish write in update mode because keys not exist
+        result = manager.finish_write(keys)
+        for key in keys:
+            assert result[key] == L1Error.KEY_NOT_EXIST
+
+        # Now try to reserve write again with mode="new"
+        result = manager.reserve_write(keys, is_temporary, basic_layout, mode="new")
+        for key in keys:
+            assert result[key][0] == L1Error.SUCCESS
+            assert result[key][1] is not None
+
+        # Commit the write
+        result = manager.finish_write(keys)
+        for key in keys:
+            assert result[key] == L1Error.SUCCESS
+
+        # Now try to reserve write again with mode="update"
+        result = manager.reserve_write(keys, is_temporary, basic_layout, mode="update")
+        for key in keys:
+            assert result[key][0] == L1Error.SUCCESS
+            assert result[key][1] is not None
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.finish_write()
+# =============================================================================
+
+
+class TestFinishWrite:
+    """
+    Tests for L1Manager.finish_write() method.
+
+    Per the docstring:
+    - KEY_NOT_EXIST: The key does not exist.
+    - KEY_IN_WRONG_STATE: The key is not write-locked, or it's read-locked.
+    """
+
+    def test_finish_write_non_existing_key_returns_key_not_exist(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that finish_write returns KEY_NOT_EXIST for non-existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.finish_write([key])
+
+        assert key in result
+        assert result[key] == L1Error.KEY_NOT_EXIST
+
+        manager.close()
+
+    def test_finish_write_success(self, basic_l1_config, basic_layout):
+        """Test that finish_write returns SUCCESS after proper write reservation."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Reserve write
+        manager.reserve_write([key], [False], basic_layout)
+
+        # Finish write
+        result = manager.finish_write([key])
+
+        assert result[key] == L1Error.SUCCESS
+
+        # Verify object is now ready (not write-locked)
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert state.available_for_read() is True
+        assert state.available_for_write() is True
+
+        manager.close()
+
+    def test_finish_write_non_write_locked_returns_wrong_state(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that finish_write returns KEY_IN_WRONG_STATE if not write-locked."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object (not write-locked)
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Try to finish write again
+        result = manager.finish_write([key])
+
+        assert result[key] == L1Error.KEY_IN_WRONG_STATE
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.finish_write_and_reserve_read()
+# =============================================================================
+
+
+class TestFinishWriteAndReserveRead:
+    """
+    Tests for L1Manager.finish_write_and_reserve_read() method.
+
+    This method atomically finishes write and acquires read lock,
+    preventing a race window where eviction could interfere.
+
+    Per the docstring:
+    - KEY_NOT_EXIST: The key does not exist.
+    - KEY_IN_WRONG_STATE: Not write-locked, or already read-locked.
+    - SUCCESS: Write unlocked and read lock acquired atomically.
+    """
+
+    def test_normal_transition(self, basic_l1_config, basic_layout):
+        """Test normal write-locked -> read-locked transition."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Reserve write (key is now write-locked)
+        write_result = manager.reserve_write([key], [False], basic_layout)
+        assert write_result[key][0] == L1Error.SUCCESS
+
+        # Atomically finish write and reserve read
+        result = manager.finish_write_and_reserve_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.SUCCESS
+        assert mem_obj is not None
+
+        # Verify state: write unlocked, read locked
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert not state.write_lock.is_locked()
+        assert state.read_lock.is_locked()
+
+        # Should be readable (not write-locked)
+        assert state.available_for_read() is True
+        # Should not be writable (read-locked)
+        assert state.available_for_write() is False
+
+        # Clean up read lock
+        manager.finish_read([key])
+        manager.close()
+
+    def test_key_not_exist(self, basic_l1_config, basic_layout):
+        """Test that non-existing key returns KEY_NOT_EXIST."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.finish_write_and_reserve_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_NOT_EXIST
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_not_write_locked(self, basic_l1_config, basic_layout):
+        """Test that non-write-locked key returns KEY_IN_WRONG_STATE."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object (not write-locked)
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        result = manager.finish_write_and_reserve_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_IN_WRONG_STATE
+        assert mem_obj is None
+
+        manager.close()
+
+    def test_already_read_locked(self, basic_l1_config, basic_layout):
+        """Test that key with both write+read locks returns KEY_IN_WRONG_STATE.
+
+        This is an unexpected state — normally a key shouldn't be both
+        write-locked and read-locked simultaneously.
+        """
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create write-locked object
+        manager.reserve_write([key], [False], basic_layout)
+
+        # Force a read lock via internal state (unusual state)
+        state = manager.get_object_state(key)
+        assert state is not None
+        state.read_lock.lock()
+
+        result = manager.finish_write_and_reserve_read([key])
+
+        assert key in result
+        error, mem_obj = result[key]
+        assert error == L1Error.KEY_IN_WRONG_STATE
+        assert mem_obj is None
+
+        # Clean up
+        state.read_lock.unlock()
+        manager.close()
+
+    def test_multiple_keys_mixed_results(self, basic_l1_config, basic_layout):
+        """Test with multiple keys where some succeed and some fail."""
+        manager = L1Manager(basic_l1_config)
+        key1 = make_object_key(1)
+        key2 = make_object_key(2)  # will not exist
+        key3 = make_object_key(3)
+
+        # key1: write-locked (should succeed)
+        manager.reserve_write([key1], [False], basic_layout)
+
+        # key3: ready, not write-locked (should fail)
+        manager.reserve_write([key3], [False], basic_layout)
+        manager.finish_write([key3])
+
+        result = manager.finish_write_and_reserve_read([key1, key2, key3])
+
+        # key1: SUCCESS
+        assert result[key1][0] == L1Error.SUCCESS
+        assert result[key1][1] is not None
+
+        # key2: KEY_NOT_EXIST
+        assert result[key2][0] == L1Error.KEY_NOT_EXIST
+        assert result[key2][1] is None
+
+        # key3: KEY_IN_WRONG_STATE (not write-locked)
+        assert result[key3][0] == L1Error.KEY_IN_WRONG_STATE
+        assert result[key3][1] is None
+
+        # Clean up
+        manager.finish_read([key1])
+        manager.close()
+
+    def test_can_unsafe_read_after_transition(self, basic_l1_config, basic_layout):
+        """Test that unsafe_read works on the transitioned key."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Write and transition
+        manager.reserve_write([key], [False], basic_layout)
+        result = manager.finish_write_and_reserve_read([key])
+        assert result[key][0] == L1Error.SUCCESS
+
+        # unsafe_read should work (key is read-locked)
+        read_result = manager.unsafe_read([key])
+        assert read_result[key][0] == L1Error.SUCCESS
+        assert read_result[key][1] is not None
+
+        manager.finish_read([key])
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.delete()
+# =============================================================================
+
+
+class TestDelete:
+    """
+    Tests for L1Manager.delete() method.
+
+    Per the docstring:
+    - KEY_NOT_EXIST: The key does not exist.
+    - KEY_IS_LOCKED: The key is locked (either write-locked or read-locked).
+    """
+
+    def test_delete_non_existing_key_returns_key_not_exist(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that delete returns KEY_NOT_EXIST for non-existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        result = manager.delete([key])
+
+        assert key in result
+        assert result[key] == L1Error.KEY_NOT_EXIST
+
+        manager.close()
+
+    def test_delete_success(self, basic_l1_config, basic_layout):
+        """Test that delete returns SUCCESS for unlocked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Verify object exists
+        assert manager.get_object_state(key) is not None
+
+        # Delete
+        result = manager.delete([key])
+
+        assert result[key] == L1Error.SUCCESS
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_delete_write_locked_returns_key_is_locked(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that delete returns KEY_IS_LOCKED for write-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create write-locked object
+        manager.reserve_write([key], [False], basic_layout)
+
+        # Try to delete
+        result = manager.delete([key])
+
+        assert result[key] == L1Error.KEY_IS_LOCKED
+
+        manager.close()
+
+    def test_delete_read_locked_returns_key_is_locked(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that delete returns KEY_IS_LOCKED for read-locked keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read
+        manager.reserve_read([key])
+
+        # Try to delete
+        result = manager.delete([key])
+
+        assert result[key] == L1Error.KEY_IS_LOCKED
+
+        manager.close()
+
+    def test_delete_multiple_keys(self, basic_l1_config, basic_layout):
+        """Test delete with multiple keys in a single call."""
+        manager = L1Manager(basic_l1_config)
+        key1 = make_object_key(1)
+        key2 = make_object_key(2)
+        key3 = make_object_key(3)
+
+        # key1: ready (unlocked)
+        manager.reserve_write([key1], [False], basic_layout)
+        manager.finish_write([key1])
+
+        # key2: does not exist
+
+        # key3: write-locked
+        manager.reserve_write([key3], [False], basic_layout)
+
+        result = manager.delete([key1, key2, key3])
+
+        assert result[key1] == L1Error.SUCCESS
+        assert result[key2] == L1Error.KEY_NOT_EXIST
+        assert result[key3] == L1Error.KEY_IS_LOCKED
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.get_object_state()
+# =============================================================================
+
+
+class TestGetObjectState:
+    """
+    Tests for L1Manager.get_object_state() method.
+
+    Per the docstring:
+    - Returns the L1ObjectState if the object exists, None otherwise.
+    """
+
+    def test_get_object_state_non_existing_returns_none(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that get_object_state returns None for non-existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        state = manager.get_object_state(key)
+
+        assert state is None
+
+        manager.close()
+
+    def test_get_object_state_existing_returns_state(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test that get_object_state returns L1ObjectState for existing keys."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        state = manager.get_object_state(key)
+
+        assert state is not None
+        # Verify we can use the state's methods
+        assert state.available_for_read() is True
+        assert state.available_for_write() is True
+
+        manager.close()
+
+    def test_get_object_state_write_locked(self, basic_l1_config, basic_layout):
+        """Test get_object_state for write-locked objects."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create write-locked object
+        manager.reserve_write([key], [False], basic_layout)
+
+        state = manager.get_object_state(key)
+
+        assert state is not None
+        assert state.available_for_read() is False
+        assert state.available_for_write() is False
+
+        manager.close()
+
+    def test_get_object_state_read_locked(self, basic_l1_config, basic_layout):
+        """Test get_object_state for read-locked objects."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object, then read lock it
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+        manager.reserve_read([key])
+
+        state = manager.get_object_state(key)
+
+        assert state is not None
+        # Read-locked is still readable
+        assert state.available_for_read() is True
+        # But not writable
+        assert state.available_for_write() is False
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.close()
+# =============================================================================
+
+
+class TestClose:
+    """
+    Tests for L1Manager.close() method.
+
+    Per the docstring:
+    - Close the L1Manager and free all resources.
+    """
+
+    def test_close_empty_manager(self, basic_l1_config):
+        """Test that close works on an empty manager."""
+        manager = L1Manager(basic_l1_config)
+
+        # Should not raise any exceptions
+        manager.close()
+
+    def test_close_with_objects(self, basic_l1_config, basic_layout):
+        """Test that close frees all objects in the manager."""
+        manager = L1Manager(basic_l1_config)
+
+        # Create multiple objects
+        keys = [make_object_key(i) for i in range(5)]
+        manager.reserve_write(keys, [False] * 5, basic_layout)
+
+        # Close should free all objects
+        manager.close()
+
+    def test_close_clears_objects(self, basic_l1_config, basic_layout):
+        """Test that close clears all objects from the manager."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Verify object exists before close
+        assert manager.get_object_state(key) is not None
+
+        # Close
+        manager.close()
+
+        # After close, get_object_state should return None
+        # (objects dict should be cleared)
+        assert manager.get_object_state(key) is None
+
+
+# =============================================================================
+# Tests for state machine transitions (integration)
+# =============================================================================
+
+
+class TestStateMachineTransitions:
+    """
+    Integration tests verifying the state machine transitions as described in the
+    L1Manager class docstring.
+    """
+
+    def test_full_write_read_cycle(self, basic_l1_config, basic_layout):
+        """Test full cycle: None -> write_locked -> ready -> read_locked -> ready."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # None state (key doesn't exist)
+        assert manager.get_object_state(key) is None
+
+        # reserve_write: None -> write_locked
+        result = manager.reserve_write([key], [False], basic_layout)
+        assert result[key][0] == L1Error.SUCCESS
+        state = manager.get_object_state(key)
+        assert state.available_for_read() is False
+        assert state.available_for_write() is False
+
+        # finish_write: write_locked -> ready
+        result = manager.finish_write([key])
+        assert result[key] == L1Error.SUCCESS
+        state = manager.get_object_state(key)
+        assert state.available_for_read() is True
+        assert state.available_for_write() is True
+
+        # reserve_read: ready -> read_locked
+        result = manager.reserve_read([key])
+        assert result[key][0] == L1Error.SUCCESS
+        state = manager.get_object_state(key)
+        assert state.available_for_read() is True
+        assert state.available_for_write() is False
+
+        # finish_read: read_locked -> ready
+        result = manager.finish_read([key])
+        assert result[key] == L1Error.SUCCESS
+        state = manager.get_object_state(key)
+        assert state.available_for_read() is True
+        assert state.available_for_write() is True
+
+        manager.close()
+
+    def test_full_write_read_with_unsafe_read(self, basic_l1_config, basic_layout):
+        """Test cycle with unsafe_read between reserve_read and finish_read."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read
+        reserve_result = manager.reserve_read([key])
+        assert reserve_result[key][0] == L1Error.SUCCESS
+
+        # Multiple unsafe_reads should all succeed
+        for _ in range(3):
+            unsafe_result = manager.unsafe_read([key])
+            assert unsafe_result[key][0] == L1Error.SUCCESS
+
+        # Finish read
+        finish_result = manager.finish_read([key])
+        assert finish_result[key] == L1Error.SUCCESS
+
+        # Object should still exist (not temporary)
+        assert manager.get_object_state(key) is not None
+
+        manager.close()
+
+    def test_delete_from_ready_state(self, basic_l1_config, basic_layout):
+        """Test deletion from ready state."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # delete: ready -> None
+        result = manager.delete([key])
+        assert result[key] == L1Error.SUCCESS
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_temporary_object_lifecycle(self, basic_l1_config, basic_layout):
+        """Test temporary object lifecycle: deleted after last read."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        # Read and release
+        manager.reserve_read([key])
+        manager.finish_read([key])
+
+        # Object should be deleted
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_temporary_object_with_unsafe_read(self, basic_l1_config, basic_layout):
+        """Test temporary object with unsafe_read doesn't affect deletion."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create temporary object
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read
+        manager.reserve_read([key])
+
+        # Multiple unsafe_reads
+        for _ in range(5):
+            result = manager.unsafe_read([key])
+            assert result[key][0] == L1Error.SUCCESS
+
+        # Single finish_read should delete the object
+        manager.finish_read([key])
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+    def test_multi_reader_lifecycle_with_extra_count(
+        self, basic_l1_config, basic_layout
+    ):
+        """Full lifecycle using extra_count (MLA TP>1 scenario).
+
+        Simulates multiple workers sharing the same key:
+        reserve_read(extra_count=N-1) acquires N locks,
+        finish_read(extra_count=N-1) releases them all.
+        """
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+        extra = 3  # total locks = 1 + 3 = 4
+
+        # write -> ready
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # reserve_read with extra_count
+        result = manager.reserve_read([key], extra_count=extra)
+        assert result[key][0] == L1Error.SUCCESS
+
+        # unsafe_read should work while read-locked
+        ur = manager.unsafe_read([key])
+        assert ur[key][0] == L1Error.SUCCESS
+
+        # finish_read with same extra_count
+        fr = manager.finish_read([key], extra_count=extra)
+        assert fr[key] == L1Error.SUCCESS
+
+        # All locks released -> writable again
+        state = manager.get_object_state(key)
+        assert state is not None
+        assert state.available_for_write() is True
+
+        manager.close()
+
+    def test_temp_object_multi_reader_deletion(self, basic_l1_config, basic_layout):
+        """Temporary object deleted after extra_count release."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+        extra = 2  # total locks = 1 + 2 = 3
+
+        manager.reserve_write([key], [True], basic_layout)
+        manager.finish_write([key])
+
+        manager.reserve_read([key], extra_count=extra)
+        assert manager.get_object_state(key) is not None
+
+        manager.finish_read([key], extra_count=extra)
+        assert manager.get_object_state(key) is None
+
+        manager.close()
+
+
+# =============================================================================
+# Thread safety tests
+# =============================================================================
+
+
+class TestThreadSafety:
+    """Tests verifying thread-safety of L1Manager operations."""
+
+    def test_concurrent_reserve_write_different_keys(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test concurrent reserve_write on different keys."""
+        manager = L1Manager(basic_l1_config)
+        num_threads = 8
+        keys_per_thread = 5
+        results = []
+        lock = threading.Lock()
+
+        def worker(thread_id):
+            thread_keys = [
+                make_object_key(thread_id * 1000 + i) for i in range(keys_per_thread)
+            ]
+            is_temporary = [False] * keys_per_thread
+            result = manager.reserve_write(thread_keys, is_temporary, basic_layout)
+            with lock:
+                results.append((thread_keys, result))
+
+        threads = [
+            threading.Thread(target=worker, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All writes should succeed
+        assert len(results) == num_threads
+        for keys, result in results:
+            for key in keys:
+                assert result[key][0] == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_concurrent_read_same_key(self, basic_l1_config, basic_layout):
+        """Test concurrent reads on the same key."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        num_threads = 10
+        results = []
+        lock = threading.Lock()
+
+        def worker():
+            result = manager.reserve_read([key])
+            with lock:
+                results.append(result)
+
+        threads = [threading.Thread(target=worker) for _ in range(num_threads)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All reads should succeed
+        assert len(results) == num_threads
+        for result in results:
+            assert result[key][0] == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_concurrent_unsafe_read_same_key(self, basic_l1_config, basic_layout):
+        """Test concurrent unsafe_reads on the same read-locked key."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(12345)
+
+        # Create ready object and reserve read
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+        manager.reserve_read([key])
+
+        num_threads = 10
+        results = []
+        lock = threading.Lock()
+
+        def worker():
+            result = manager.unsafe_read([key])
+            with lock:
+                results.append(result)
+
+        threads = [threading.Thread(target=worker) for _ in range(num_threads)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All unsafe_reads should succeed
+        assert len(results) == num_threads
+        for result in results:
+            assert result[key][0] == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_concurrent_read_write_mixed_operations(
+        self, basic_l1_config, basic_layout
+    ):
+        """Test concurrent mixed operations don't cause crashes."""
+        manager = L1Manager(basic_l1_config)
+        num_threads = 8
+        operations_per_thread = 10
+        errors = []
+        lock = threading.Lock()
+
+        def worker(thread_id):
+            try:
+                for i in range(operations_per_thread):
+                    key = make_object_key(thread_id * 1000 + i)
+
+                    # Write cycle
+                    write_result = manager.reserve_write([key], [False], basic_layout)
+                    if write_result[key][0] == L1Error.SUCCESS:
+                        manager.finish_write([key])
+
+                        # Read cycle with unsafe_read
+                        read_result = manager.reserve_read([key])
+                        if read_result[key][0] == L1Error.SUCCESS:
+                            # Do some unsafe_reads
+                            manager.unsafe_read([key])
+                            manager.unsafe_read([key])
+                            manager.finish_read([key])
+
+                        # Delete
+                        manager.delete([key])
+            except Exception as e:
+                with lock:
+                    errors.append(e)
+
+        threads = [
+            threading.Thread(target=worker, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # No exceptions should have occurred
+        assert len(errors) == 0, f"Thread safety errors: {errors}"
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1Manager.is_key_evictable()
+# =============================================================================
+
+
+class TestIsKeyEvictable:
+    """Tests for L1Manager.is_key_evictable() method."""
+
+    def test_evictable_key_in_ready_state(self, basic_l1_config, basic_layout):
+        """A key that has been written and finished should be evictable."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Write and finish -> key is in ready state
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        assert manager.is_key_evictable(key) is True
+
+        manager.close()
+
+    def test_write_locked_key_is_not_evictable(self, basic_l1_config, basic_layout):
+        """A write-locked key should not be evictable."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Reserve write but don't finish -> key is write-locked
+        manager.reserve_write([key], [False], basic_layout)
+
+        assert manager.is_key_evictable(key) is False
+
+        # Cleanup
+        manager.finish_write([key])
+        manager.close()
+
+    def test_read_locked_key_is_not_evictable(self, basic_l1_config, basic_layout):
+        """A read-locked key should not be evictable."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Write, finish, then reserve read -> key is read-locked
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+        manager.reserve_read([key])
+
+        assert manager.is_key_evictable(key) is False
+
+        # Cleanup
+        manager.finish_read([key])
+        manager.close()
+
+    def test_nonexistent_key_is_not_evictable(self, basic_l1_config):
+        """A key that does not exist should not be evictable."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(999)
+
+        assert manager.is_key_evictable(key) is False
+
+        manager.close()
+
+    def test_key_becomes_evictable_after_read_unlock(
+        self, basic_l1_config, basic_layout
+    ):
+        """A key should become evictable after all read locks are released."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Write and finish
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read -> not evictable
+        manager.reserve_read([key])
+        assert manager.is_key_evictable(key) is False
+
+        # Finish read -> evictable again
+        manager.finish_read([key])
+        assert manager.is_key_evictable(key) is True
+
+        manager.close()
+
+    def test_key_becomes_evictable_after_write_unlock(
+        self, basic_l1_config, basic_layout
+    ):
+        """A key should become evictable after write lock is released."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Reserve write -> not evictable
+        manager.reserve_write([key], [False], basic_layout)
+        assert manager.is_key_evictable(key) is False
+
+        # Finish write -> evictable
+        manager.finish_write([key])
+        assert manager.is_key_evictable(key) is True
+
+        manager.close()
+
+    def test_multiple_keys_mixed_evictability(self, basic_l1_config, basic_layout):
+        """Test evictability with multiple keys in different states."""
+        manager = L1Manager(basic_l1_config)
+        key_ready = make_object_key(1)
+        key_write_locked = make_object_key(2)
+        key_read_locked = make_object_key(3)
+
+        # key_ready: write + finish -> ready state
+        manager.reserve_write([key_ready], [False], basic_layout)
+        manager.finish_write([key_ready])
+
+        # key_write_locked: write only -> write-locked
+        manager.reserve_write([key_write_locked], [False], basic_layout)
+
+        # key_read_locked: write + finish + read -> read-locked
+        manager.reserve_write([key_read_locked], [False], basic_layout)
+        manager.finish_write([key_read_locked])
+        manager.reserve_read([key_read_locked])
+
+        assert manager.is_key_evictable(key_ready) is True
+        assert manager.is_key_evictable(key_write_locked) is False
+        assert manager.is_key_evictable(key_read_locked) is False
+
+        # Cleanup
+        manager.finish_write([key_write_locked])
+        manager.finish_read([key_read_locked])
+        manager.close()
+
+    def test_deleted_key_is_not_evictable(self, basic_l1_config, basic_layout):
+        """A key that has been deleted should not be evictable."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Write, finish, then delete
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+        manager.delete([key])
+
+        assert manager.is_key_evictable(key) is False
+
+        manager.close()
+
+    def test_key_with_multiple_read_locks_not_evictable(
+        self, basic_l1_config, basic_layout
+    ):
+        """A key with extra_count read locks should not be evictable
+        until all locks are released."""
+        manager = L1Manager(basic_l1_config)
+        key = make_object_key(1)
+
+        # Write and finish
+        manager.reserve_write([key], [False], basic_layout)
+        manager.finish_write([key])
+
+        # Reserve read with extra_count=2 (total 3 locks)
+        manager.reserve_read([key], extra_count=2)
+        assert manager.is_key_evictable(key) is False
+
+        # Release only 1 lock (extra_count=0) -> still locked
+        manager.finish_read([key], extra_count=0)
+        assert manager.is_key_evictable(key) is False
+
+        # Release remaining 2 locks (extra_count=1)
+        manager.finish_read([key], extra_count=1)
+        assert manager.is_key_evictable(key) is True
+
+        manager.close()
diff --git a/tests/v1/distributed/test_l1_memory_manager.py b/tests/v1/distributed/test_l1_memory_manager.py
new file mode 100644
index 0000000..9771197
--- /dev/null
+++ b/tests/v1/distributed/test_l1_memory_manager.py
@@ -0,0 +1,556 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for L1MemoryManager.
+
+These tests verify the behavior of L1MemoryManager as described in the
+interface docstrings. The tests focus on:
+
+1. allocate() - Thread-safe allocation returning (error_code, memory_objs)
+   - Returns SUCCESS and non-empty list on successful allocation
+   - Returns OUT_OF_MEMORY and empty list when allocation fails
+
+2. free() - Thread-safe deallocation returning error_code
+   - Returns SUCCESS when operation succeeds
+
+3. get_l1_memory_desc() - Returns L1MemoryDesc with pointer, size, and
+   alignment of the L1 buffer
+"""
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor, as_completed
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.config import L1MemoryManagerConfig
+from lmcache.v1.distributed.error import L1Error
+
+try:
+    # First Party
+    from lmcache.v1.distributed.internal_api import L1MemoryDesc
+    from lmcache.v1.distributed.memory_manager import (
+        L1MemoryManager,
+    )
+except ImportError:
+    # Skip the tests if the L1MemoryManager cannot be imported
+    pytest.skip("L1MemoryManager could not be imported", allow_module_level=True)
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+def should_use_lazy_alloc() -> bool:
+    """Determine if lazy allocation should be used based on CUDA availability."""
+    return torch.cuda.is_available()
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def basic_config():
+    """Create a basic L1MemoryManagerConfig for testing."""
+    return L1MemoryManagerConfig(
+        size_in_bytes=128 * 1024 * 1024,  # 128MB
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64 * 1024 * 1024,  # 64MB
+        align_bytes=0x1000,  # 4KB
+    )
+
+
+@pytest.fixture
+def small_config():
+    """Create a small L1MemoryManagerConfig to test memory exhaustion.
+
+    Note: Minimum size is 64MB due to LazyMemoryAllocator's PIN_CHUNK_SIZE.
+    """
+    return L1MemoryManagerConfig(
+        size_in_bytes=64 * 1024 * 1024,  # 64MB
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64
+        * 1024
+        * 1024,  # 64MB (same as final to prevent expansion)
+        align_bytes=0x1000,
+    )
+
+
+@pytest.fixture
+def non_lazy_config():
+    """Create a config that does not use lazy allocation."""
+    return L1MemoryManagerConfig(
+        size_in_bytes=128 * 1024 * 1024,  # 128MB
+        use_lazy=False,
+        init_size_in_bytes=64 * 1024 * 1024,
+        align_bytes=0x1000,
+    )
+
+
+@pytest.fixture
+def basic_layout():
+    """Create a basic MemoryLayoutDesc for testing."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+@pytest.fixture
+def multi_tensor_layout():
+    """Create a MemoryLayoutDesc with multiple tensor shapes."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512]), torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16, torch.bfloat16],
+    )
+
+
+@pytest.fixture
+def large_layout():
+    """Create a large MemoryLayoutDesc that will exhaust small memory.
+
+    Each allocation is 8MB (2M elements * 4 bytes).
+    """
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([2048, 1024])],  # 2M elements * 4 bytes = 8MB
+        dtypes=[torch.float32],
+    )
+
+
+# =============================================================================
+# Tests for L1MemoryManager.allocate()
+# =============================================================================
+
+
+class TestAllocate:
+    """
+    Tests for L1MemoryManager.allocate() method.
+
+    Per the docstring:
+    - This function should be thread-safe
+    - Returns tuple[L1Error, list[MemoryObj]]
+    - Error code is OUT_OF_MEMORY if allocation fails, otherwise SUCCESS
+    - If allocation fails, the memory object list will be empty
+    """
+
+    def test_allocate_returns_success_and_memory_objs(self, basic_config, basic_layout):
+        """Test that allocate returns SUCCESS and valid memory objects."""
+        manager = L1MemoryManager(basic_config)
+
+        error, mem_objs = manager.allocate(basic_layout, count=1)
+
+        assert error == L1Error.SUCCESS
+        assert isinstance(mem_objs, list)
+        assert len(mem_objs) == 1
+        for obj in mem_objs:
+            assert obj is not None
+            assert obj.is_valid()
+
+        manager.close()
+
+    def test_allocate_returns_correct_count(self, basic_config, basic_layout):
+        """Test that allocate returns the requested number of memory objects."""
+        manager = L1MemoryManager(basic_config)
+        count = 5
+
+        error, mem_objs = manager.allocate(basic_layout, count=count)
+
+        assert error == L1Error.SUCCESS
+        assert len(mem_objs) == count
+
+        manager.close()
+
+    def test_allocate_with_multi_tensor_layout(self, basic_config, multi_tensor_layout):
+        """Test allocation with multiple tensor shapes in the layout."""
+        manager = L1MemoryManager(basic_config)
+
+        error, mem_objs = manager.allocate(multi_tensor_layout, count=2)
+
+        assert error == L1Error.SUCCESS
+        assert len(mem_objs) == 2
+
+        manager.close()
+
+    def test_allocate_returns_out_of_memory_when_exhausted(
+        self, small_config, large_layout
+    ):
+        """
+        Test that allocate returns OUT_OF_MEMORY and empty list when memory
+        is exhausted.
+        """
+        manager = L1MemoryManager(small_config)
+
+        # Request more memory than available (8MB * 10 = 80MB > 64MB)
+        error, mem_objs = manager.allocate(large_layout, count=10)
+
+        assert error == L1Error.OUT_OF_MEMORY
+        assert isinstance(mem_objs, list)
+        assert len(mem_objs) == 0
+
+        manager.close()
+
+    def test_allocate_returns_empty_list_on_failure(self, small_config, large_layout):
+        """Test that the memory object list is empty when allocation fails."""
+        manager = L1MemoryManager(small_config)
+
+        # Request more memory than available (8MB * 10 = 80MB > 64MB)
+        error, mem_objs = manager.allocate(large_layout, count=10)
+
+        # Verify the docstring contract: "If the allocation fails, the memory
+        # object list will be empty."
+        assert error == L1Error.OUT_OF_MEMORY
+        assert mem_objs == []
+
+        manager.close()
+
+    def test_allocate_is_thread_safe(self, basic_config, basic_layout):
+        """Test that allocate is thread-safe with concurrent allocations."""
+        manager = L1MemoryManager(basic_config)
+        num_threads = 10
+        allocations_per_thread = 5
+        results = []
+        errors = []
+
+        def allocate_task():
+            try:
+                for _ in range(allocations_per_thread):
+                    error, mem_objs = manager.allocate(basic_layout, count=1)
+                    results.append((error, mem_objs))
+            except Exception as e:
+                errors.append(e)
+
+        threads = [threading.Thread(target=allocate_task) for _ in range(num_threads)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # No exceptions should have been raised
+        assert len(errors) == 0, f"Thread-safety errors: {errors}"
+
+        # All results should have valid error codes
+        for error, mem_objs in results:
+            assert error in (
+                L1Error.SUCCESS,
+                L1Error.OUT_OF_MEMORY,
+            )
+            if error == L1Error.SUCCESS:
+                assert len(mem_objs) == 1
+            else:
+                assert len(mem_objs) == 0
+
+        manager.close()
+
+    def test_allocate_with_non_lazy_config(self, non_lazy_config, basic_layout):
+        """Test allocation with non-lazy (MixedMemoryAllocator) configuration."""
+        manager = L1MemoryManager(non_lazy_config)
+
+        error, mem_objs = manager.allocate(basic_layout, count=2)
+
+        assert error == L1Error.SUCCESS
+        assert len(mem_objs) == 2
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1MemoryManager.free()
+# =============================================================================
+
+
+class TestFree:
+    """
+    Tests for L1MemoryManager.free() method.
+
+    Per the docstring:
+    - This function should be thread-safe
+    - Returns L1Error indicating the result
+    - Returns SUCCESS if operation succeeds
+    """
+
+    def test_free_returns_success(self, basic_config, basic_layout):
+        """Test that free returns SUCCESS for valid memory objects."""
+        manager = L1MemoryManager(basic_config)
+
+        error, mem_objs = manager.allocate(basic_layout, count=2)
+        assert error == L1Error.SUCCESS
+
+        free_error = manager.free(mem_objs)
+
+        assert free_error == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_free_invalidates_memory_objects(self, basic_config, basic_layout):
+        """Test that free invalidates the memory objects."""
+        manager = L1MemoryManager(basic_config)
+
+        error, mem_objs = manager.allocate(basic_layout, count=1)
+        assert error == L1Error.SUCCESS
+        assert mem_objs[0].is_valid()
+
+        free_error = manager.free(mem_objs)
+        assert free_error == L1Error.SUCCESS
+
+        # After freeing, the memory objects should be invalidated
+        for obj in mem_objs:
+            assert not obj.is_valid()
+
+        manager.close()
+
+    def test_free_empty_list_returns_success(self, basic_config):
+        """Test that freeing an empty list returns SUCCESS."""
+        manager = L1MemoryManager(basic_config)
+
+        free_error = manager.free([])
+
+        assert free_error == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_free_allows_reallocation(self, basic_config, basic_layout):
+        """Test that freed memory can be reallocated."""
+        manager = L1MemoryManager(basic_config)
+
+        # Allocate
+        error1, mem_objs1 = manager.allocate(basic_layout, count=5)
+        assert error1 == L1Error.SUCCESS
+
+        # Free
+        free_error = manager.free(mem_objs1)
+        assert free_error == L1Error.SUCCESS
+
+        # Reallocate
+        error2, mem_objs2 = manager.allocate(basic_layout, count=5)
+        assert error2 == L1Error.SUCCESS
+        assert len(mem_objs2) == 5
+
+        manager.close()
+
+    def test_free_is_thread_safe(self, basic_config, basic_layout):
+        """Test that free is thread-safe with concurrent operations."""
+        manager = L1MemoryManager(basic_config)
+        num_threads = 10
+        errors_list = []
+        lock = threading.Lock()
+
+        def allocate_and_free_task():
+            try:
+                error, mem_objs = manager.allocate(basic_layout, count=1)
+                if error == L1Error.SUCCESS:
+                    free_error = manager.free(mem_objs)
+                    with lock:
+                        errors_list.append(free_error)
+            except Exception as e:
+                with lock:
+                    errors_list.append(e)
+
+        threads = [
+            threading.Thread(target=allocate_and_free_task) for _ in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        # All free operations should have succeeded
+        for err in errors_list:
+            if isinstance(err, Exception):
+                pytest.fail(f"Thread-safety error: {err}")
+            assert err == L1Error.SUCCESS
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1MemoryManager.get_l1_memory_desc()
+# =============================================================================
+
+
+class TestGetL1MemoryDesc:
+    """
+    Tests for L1MemoryManager.get_l1_memory_desc() method.
+
+    Per the docstring:
+    - Returns an L1MemoryDesc with ptr, size, and align_bytes
+    - Used by RDMA communication to register the underlying virtual memory space
+    """
+
+    def test_get_l1_memory_desc_returns_desc(self, basic_config):
+        """Test that get_l1_memory_desc returns an L1MemoryDesc."""
+        manager = L1MemoryManager(basic_config)
+
+        desc = manager.get_l1_memory_desc()
+
+        assert isinstance(desc, L1MemoryDesc)
+
+        manager.close()
+
+    def test_get_l1_memory_desc_returns_consistent_ptr(self, basic_config):
+        """Test that get_l1_memory_desc returns the same pointer on multiple calls."""
+        manager = L1MemoryManager(basic_config)
+
+        desc1 = manager.get_l1_memory_desc()
+        desc2 = manager.get_l1_memory_desc()
+
+        assert desc1.ptr == desc2.ptr
+
+        manager.close()
+
+    def test_get_l1_memory_desc_size_matches_config(self, basic_config):
+        """Test that the desc size matches the configured size."""
+        manager = L1MemoryManager(basic_config)
+
+        desc = manager.get_l1_memory_desc()
+
+        assert desc.size == basic_config.size_in_bytes
+        assert desc.align_bytes == basic_config.align_bytes
+
+        manager.close()
+
+    def test_get_l1_memory_desc_with_non_lazy_config(self, non_lazy_config):
+        """Test get_l1_memory_desc with non-lazy (MixedMemoryAllocator)
+        configuration."""
+        manager = L1MemoryManager(non_lazy_config)
+
+        desc = manager.get_l1_memory_desc()
+
+        assert isinstance(desc, L1MemoryDesc)
+        assert desc.ptr != 0
+        assert desc.size == non_lazy_config.size_in_bytes
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for L1MemoryManager integration
+# =============================================================================
+
+
+class TestL1MemoryManagerIntegration:
+    """Integration tests for L1MemoryManager."""
+
+    def test_allocate_free_cycle(self, basic_config, basic_layout):
+        """Test a complete allocate-free cycle."""
+        manager = L1MemoryManager(basic_config)
+
+        # Allocate
+        error, mem_objs = manager.allocate(basic_layout, count=3)
+        assert error == L1Error.SUCCESS
+        assert len(mem_objs) == 3
+
+        # Verify objects are valid
+        for obj in mem_objs:
+            assert obj.is_valid()
+
+        # Free
+        free_error = manager.free(mem_objs)
+        assert free_error == L1Error.SUCCESS
+
+        # Verify objects are invalidated
+        for obj in mem_objs:
+            assert not obj.is_valid()
+
+        manager.close()
+
+    def test_multiple_allocate_free_cycles(self, basic_config, basic_layout):
+        """Test multiple allocate-free cycles."""
+        manager = L1MemoryManager(basic_config)
+
+        for i in range(5):
+            error, mem_objs = manager.allocate(basic_layout, count=2)
+            assert error == L1Error.SUCCESS, f"Cycle {i} failed"
+            assert len(mem_objs) == 2
+
+            free_error = manager.free(mem_objs)
+            assert free_error == L1Error.SUCCESS
+
+        manager.close()
+
+    def test_interleaved_allocate_and_free(self, basic_config, basic_layout):
+        """Test interleaved allocation and free operations."""
+        manager = L1MemoryManager(basic_config)
+
+        # Allocate batch 1
+        err1, objs1 = manager.allocate(basic_layout, count=2)
+        assert err1 == L1Error.SUCCESS
+
+        # Allocate batch 2
+        err2, objs2 = manager.allocate(basic_layout, count=2)
+        assert err2 == L1Error.SUCCESS
+
+        # Free batch 1
+        free_err1 = manager.free(objs1)
+        assert free_err1 == L1Error.SUCCESS
+
+        # Allocate batch 3 (should reuse freed memory)
+        err3, objs3 = manager.allocate(basic_layout, count=2)
+        assert err3 == L1Error.SUCCESS
+
+        # Free remaining
+        manager.free(objs2)
+        manager.free(objs3)
+
+        manager.close()
+
+    def test_concurrent_allocate_and_free(self, basic_config, basic_layout):
+        """
+        Test concurrent allocate and free operations from multiple threads.
+        This verifies the thread-safety guarantees of both methods.
+        """
+        manager = L1MemoryManager(basic_config)
+        num_threads = 8
+        iterations = 20
+        exceptions = []
+
+        def worker():
+            try:
+                for _ in range(iterations):
+                    # Allocate
+                    error, mem_objs = manager.allocate(basic_layout, count=1)
+                    if error == L1Error.SUCCESS:
+                        # Briefly hold the memory
+                        assert len(mem_objs) == 1
+                        # Free
+                        free_error = manager.free(mem_objs)
+                        assert free_error == L1Error.SUCCESS
+            except Exception as e:
+                exceptions.append(e)
+
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [executor.submit(worker) for _ in range(num_threads)]
+            for future in as_completed(futures):
+                future.result()  # Raises exception if worker failed
+
+        assert len(exceptions) == 0, f"Concurrency errors: {exceptions}"
+
+        manager.close()
+
+
+# =============================================================================
+# Tests for error code semantics
+# =============================================================================
+
+
+class TestErrorCodeSemantics:
+    """Tests verifying error code semantics as documented."""
+
+    def test_success_error_code_value(self):
+        """Test that SUCCESS is a valid enum member."""
+        assert L1Error.SUCCESS is not None
+        assert L1Error.SUCCESS.name == "SUCCESS"
+
+    def test_out_of_memory_error_code_value(self):
+        """Test that OUT_OF_MEMORY is a valid enum member."""
+        assert L1Error.OUT_OF_MEMORY is not None
+        assert L1Error.OUT_OF_MEMORY.name == "OUT_OF_MEMORY"
+
+    def test_error_codes_are_distinct(self):
+        """Test that error codes are distinct values."""
+        assert L1Error.SUCCESS != L1Error.OUT_OF_MEMORY
diff --git a/tests/v1/distributed/test_l1_single_region.py b/tests/v1/distributed/test_l1_single_region.py
new file mode 100644
index 0000000..0c7f4a1
--- /dev/null
+++ b/tests/v1/distributed/test_l1_single_region.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``l1_exposes_single_memory_region`` (P2P L1 compatibility)."""
+
+# First Party
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    GdsL1Config,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+    l1_exposes_single_memory_region,
+)
+from lmcache.v1.distributed.l2_adapters.config import L2AdaptersConfig
+
+_SIZE = 128 * 1024 * 1024
+
+
+def _config(
+    memory_config: L1MemoryManagerConfig,
+    gds_l1_config: GdsL1Config | None = None,
+) -> StorageManagerConfig:
+    return StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=memory_config,
+            gds_l1_config=gds_l1_config,
+            write_ttl_seconds=600,
+            read_ttl_seconds=300,
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(adapters=[]),
+    )
+
+
+def test_plain_dram_is_single_region():
+    config = _config(L1MemoryManagerConfig(size_in_bytes=_SIZE, use_lazy=False))
+    assert l1_exposes_single_memory_region(config) is True
+
+
+def test_gds_l1_is_not_single_region():
+    config = _config(
+        L1MemoryManagerConfig(size_in_bytes=_SIZE, use_lazy=False),
+        gds_l1_config=GdsL1Config(file_location="/tmp/gds_slab", size_in_bytes=_SIZE),
+    )
+    assert l1_exposes_single_memory_region(config) is False
+
+
+def test_devdax_l1_is_not_single_region():
+    config = _config(
+        L1MemoryManagerConfig(
+            size_in_bytes=_SIZE,
+            use_lazy=False,
+            devdax_path="/dev/dax0.0",
+            shm_name="",
+        )
+    )
+    assert l1_exposes_single_memory_region(config) is False
diff --git a/tests/v1/distributed/test_l2_adapter_base.py b/tests/v1/distributed/test_l2_adapter_base.py
new file mode 100644
index 0000000..b95ccfb
--- /dev/null
+++ b/tests/v1/distributed/test_l2_adapter_base.py
@@ -0,0 +1,323 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the L2 adapter base class accounting + AdapterUsage.
+
+The base class owns ``_total_bytes_used`` / ``_bytes_by_cache_salt`` and
+exposes them through ``get_usage()``. Adapters drive accounting by passing
+``sizes`` to ``_notify_keys_stored`` / ``_notify_keys_deleted``.
+"""
+
+# Standard
+import threading
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2AdapterListener, L2StoreResult
+from lmcache.v1.distributed.l2_adapters.base import (
+    AdapterUsage,
+    L2AdapterInterface,
+    L2TaskId,
+)
+
+
+def _make_key(chunk_id: int, salt: str = "") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="m",
+        kv_rank=0,
+        cache_salt=salt,
+    )
+
+
+class _StubAdapter(L2AdapterInterface):
+    """Minimal adapter that satisfies the abstract surface so we can
+    exercise base-class behavior in isolation."""
+
+    def get_store_event_fd(self) -> int:
+        return -1
+
+    def get_lookup_and_lock_event_fd(self) -> int:
+        return -1
+
+    def get_load_event_fd(self) -> int:
+        return -1
+
+    def submit_store_task(self, keys, objects):
+        return 0
+
+    def pop_completed_store_tasks(self) -> dict[L2TaskId, L2StoreResult]:
+        return {}
+
+    def submit_lookup_and_lock_task(self, keys, layout_desc: MemoryLayoutDesc):
+        return 0
+
+    def query_lookup_and_lock_result(self, task_id):
+        return None
+
+    def submit_unlock(self, keys):
+        return None
+
+    def submit_load_task(self, keys, objects):
+        return 0
+
+    def query_load_result(self, task_id):
+        return None
+
+    def close(self) -> None:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# AdapterUsage
+# ---------------------------------------------------------------------------
+
+
+class TestAdapterUsage:
+    def test_usage_fraction_in_range(self):
+        u = AdapterUsage(total_bytes_used=50, total_capacity_bytes=100)
+        assert u.usage_fraction == 0.5
+
+    def test_usage_fraction_zero_capacity_returns_minus_one(self):
+        # ``-1`` is the legacy "no eviction signal" sentinel — kept so
+        # eviction-controller callers can keep using ``< 0`` shortcuts.
+        u = AdapterUsage(total_bytes_used=0, total_capacity_bytes=0)
+        assert u.usage_fraction == -1.0
+
+    def test_usage_fraction_negative_capacity_returns_minus_one(self):
+        u = AdapterUsage(total_bytes_used=10, total_capacity_bytes=-1)
+        assert u.usage_fraction == -1.0
+
+    def test_bytes_by_cache_salt_default_empty(self):
+        u = AdapterUsage(total_bytes_used=0, total_capacity_bytes=100)
+        assert u.bytes_by_cache_salt == {}
+
+    def test_frozen(self):
+        # Standard
+        from dataclasses import FrozenInstanceError
+
+        u = AdapterUsage(total_bytes_used=1, total_capacity_bytes=2)
+        with pytest.raises(FrozenInstanceError):
+            u.total_bytes_used = 5  # type: ignore[misc]
+
+
+# ---------------------------------------------------------------------------
+# supports_global_eviction
+# ---------------------------------------------------------------------------
+
+
+class TestSupportsGlobalEviction:
+    def test_default_no_capacity_means_no_eviction(self):
+        a = _StubAdapter()
+        assert a.supports_global_eviction is False
+        assert a.get_usage().usage_fraction == -1.0
+
+    def test_positive_capacity_supports_global_eviction(self):
+        a = _StubAdapter(max_capacity_bytes=1024)
+        assert a.supports_global_eviction is True
+
+    def test_zero_capacity_explicit_means_no_eviction(self):
+        a = _StubAdapter(max_capacity_bytes=0)
+        assert a.supports_global_eviction is False
+
+
+# ---------------------------------------------------------------------------
+# Base-class byte accounting
+# ---------------------------------------------------------------------------
+
+
+class TestBaseAccounting:
+    def test_store_increments_aggregate_and_by_cache_salt(self):
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k_alice = _make_key(1, salt="alice")
+        k_bob = _make_key(2, salt="bob")
+        k_alice2 = _make_key(3, salt="alice")
+        a._notify_keys_stored([k_alice, k_bob, k_alice2], [100, 200, 50])
+        u = a.get_usage()
+        assert u.total_bytes_used == 350
+        assert u.bytes_by_cache_salt == {"alice": 150, "bob": 200}
+
+    def test_delete_decrements_aggregate_and_by_cache_salt(self):
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k_alice = _make_key(1, salt="alice")
+        k_bob = _make_key(2, salt="bob")
+        a._notify_keys_stored([k_alice, k_bob], [100, 200])
+        a._notify_keys_deleted([k_alice], [100])
+        u = a.get_usage()
+        assert u.total_bytes_used == 200
+        assert u.bytes_by_cache_salt == {"bob": 200}
+
+    def test_cache_salt_bucket_dropped_when_zero(self):
+        """Per-``cache_salt`` bookkeeping should not retain stale ``0``
+        entries — it keeps the snapshot compact and avoids memory
+        growth across many short-lived salts."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k = _make_key(1, salt="alice")
+        a._notify_keys_stored([k], [100])
+        a._notify_keys_deleted([k], [100])
+        u = a.get_usage()
+        assert u.total_bytes_used == 0
+        assert "alice" not in u.bytes_by_cache_salt
+        assert u.bytes_by_cache_salt == {}
+
+    def test_empty_salt_is_a_real_bucket(self):
+        """Un-salted traffic accumulates under the empty-string key.
+        ``bytes_by_cache_salt`` must reflect that so legacy/unisolated traffic
+        is observable too."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k = _make_key(1, salt="")
+        a._notify_keys_stored([k], [100])
+        u = a.get_usage()
+        assert u.bytes_by_cache_salt == {"": 100}
+
+    def test_get_usage_filters_zero_buckets(self):
+        """Snapshot only includes positive-byte buckets."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        # Manually inject a ``0`` entry as if accounting drift left one
+        # behind.
+        a._bytes_by_cache_salt["ghost"] = 0
+        a._bytes_by_cache_salt["alice"] = 100
+        a._total_bytes_used = 100
+        u = a.get_usage()
+        assert u.bytes_by_cache_salt == {"alice": 100}
+
+    def test_size_list_length_mismatch_raises(self):
+        """``zip(strict=True)`` catches caller bugs where keys/sizes drift
+        out of sync — that would silently corrupt accounting otherwise."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        with pytest.raises(ValueError):
+            a._notify_keys_stored([_make_key(1)], [100, 200])
+
+    def test_underflow_clamps_to_zero(self):
+        """A delete that would drive ``_total_bytes_used`` negative
+        clamps to 0 (and logs a warning, observable via stderr).
+        Without the clamp the sentinel ``usage_fraction == -1`` would
+        silently disable eviction across the whole adapter."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k = _make_key(1, salt="alice")
+        a._notify_keys_stored([k], [100])
+        # Delete reports a larger size than was stored — caller bug.
+        a._notify_keys_deleted([k], [500])
+        u = a.get_usage()
+        assert u.total_bytes_used == 0  # clamped, not -400
+        assert u.usage_fraction == 0.0  # not the -1 sentinel
+
+    def test_get_usage_returns_immutable_by_cache_salt_view(self):
+        """``bytes_by_cache_salt`` is a read-only ``Mapping`` so a caller
+        cannot mutate the snapshot or the adapter's live state."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k = _make_key(1, salt="alice")
+        a._notify_keys_stored([k], [100])
+        u = a.get_usage()
+        # MappingProxyType raises TypeError on mutation attempts.
+        with pytest.raises(TypeError):
+            u.bytes_by_cache_salt["bob"] = 999  # type: ignore[index]
+        # Original snapshot still intact.
+        assert dict(u.bytes_by_cache_salt) == {"alice": 100}
+
+    def test_get_usage_snapshot_is_detached(self):
+        """A held ``AdapterUsage`` reference does not see later
+        accounting changes — each call returns a fresh snapshot."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        k1 = _make_key(1, salt="alice")
+        a._notify_keys_stored([k1], [100])
+        u1 = a.get_usage()
+        a._notify_keys_stored([_make_key(2, salt="bob")], [200])
+        # u1 is the snapshot at the earlier moment.
+        assert u1.total_bytes_used == 100
+        assert dict(u1.bytes_by_cache_salt) == {"alice": 100}
+        # Live state is now 300 / {alice, bob}.
+        u2 = a.get_usage()
+        assert u2.total_bytes_used == 300
+        assert dict(u2.bytes_by_cache_salt) == {"alice": 100, "bob": 200}
+
+    def test_zero_size_notify_is_listener_only(self):
+        """Calling ``_notify_keys_stored`` with size=0 fires the listener
+        but leaves byte counters untouched. Used by the native connector
+        to bump LRU on a re-store without double-counting bytes."""
+        a = _StubAdapter(max_capacity_bytes=10_000)
+        lst = _RecordingListener()
+        a.register_listener(lst)
+        k = _make_key(1, salt="alice")
+        a._notify_keys_stored([k], [100])
+        # Re-store with size=0 — listener fires, bytes unchanged.
+        a._notify_keys_stored([k], [0])
+        u = a.get_usage()
+        assert u.total_bytes_used == 100
+        assert dict(u.bytes_by_cache_salt) == {"alice": 100}
+        # Listener fired twice (LRU policy can move_to_end on second).
+        assert lst.stored == [[k], [k]]
+
+    def test_concurrent_stores_thread_safe(self):
+        """Accounting is held under ``_usage_lock``; concurrent notifies
+        from many threads must not lose updates."""
+        a = _StubAdapter(max_capacity_bytes=10_000_000)
+        n_threads = 8
+        per_thread = 100
+
+        def worker(idx: int):
+            keys = [_make_key(i + idx * per_thread) for i in range(per_thread)]
+            sizes = [10] * per_thread
+            a._notify_keys_stored(keys, sizes)
+
+        threads = [threading.Thread(target=worker, args=(i,)) for i in range(n_threads)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+        assert a.get_usage().total_bytes_used == n_threads * per_thread * 10
+
+
+# ---------------------------------------------------------------------------
+# Listener notifications still fire (regression guard for the refactor)
+# ---------------------------------------------------------------------------
+
+
+class _RecordingListener(L2AdapterListener):
+    """Concrete ``L2AdapterListener`` that captures notify calls so tests
+    can assert listener invocation."""
+
+    def __init__(self) -> None:
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]) -> None:
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]) -> None:
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]) -> None:
+        self.deleted.append(list(keys))
+
+
+class TestListenersStillFire:
+    def test_store_notify_fires_listener(self):
+        a = _StubAdapter(max_capacity_bytes=1000)
+        lst = _RecordingListener()
+        a.register_listener(lst)
+        k = _make_key(1, salt="alice")
+        a._notify_keys_stored([k], [100])
+        assert lst.stored == [[k]]
+
+    def test_delete_notify_fires_listener(self):
+        a = _StubAdapter(max_capacity_bytes=1000)
+        lst = _RecordingListener()
+        a.register_listener(lst)
+        k = _make_key(1, salt="alice")
+        a._notify_keys_stored([k], [100])
+        a._notify_keys_deleted([k], [100])
+        assert lst.deleted == [[k]]
+
+    def test_accessed_notify_unchanged_signature(self):
+        """``_notify_keys_accessed`` does not affect bytes — its signature
+        is unchanged from before the refactor."""
+        a = _StubAdapter()
+        lst = _RecordingListener()
+        a.register_listener(lst)
+        k = _make_key(1)
+        a._notify_keys_accessed([k])
+        assert lst.accessed == [[k]]
diff --git a/tests/v1/distributed/test_l2_adapter_factory.py b/tests/v1/distributed/test_l2_adapter_factory.py
new file mode 100644
index 0000000..acd8e0d
--- /dev/null
+++ b/tests/v1/distributed/test_l2_adapter_factory.py
@@ -0,0 +1,1138 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the L2 adapter factory registry and
+PluginL2AdapterConfig.
+"""
+
+# Standard
+import os
+import tempfile
+import types
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdapterConfigBase,
+    get_type_name_for_config,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    create_l2_adapter_from_registry,
+    register_l2_adapter_factory,
+)
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import MockL2AdapterConfig
+from lmcache.v1.distributed.l2_adapters.plugin_l2_adapter import PluginL2AdapterConfig
+from lmcache.v1.distributed.l2_adapters.raw_block_l2_adapter import (
+    RawBlockL2AdapterConfig,
+)
+from lmcache.v1.platform import create_event_notifier
+
+
+def _has_raw_block_ext() -> bool:
+    try:
+        # Third Party
+        import lmcache_rust_raw_block_io  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+# =========================================================
+# Helpers
+# =========================================================
+
+
+class _FakeL2Adapter:
+    """Minimal stub that passes issubclass check."""
+
+    def __init__(self, params=None, **kwargs):
+        self.params = params
+        self.kwargs = kwargs
+
+
+class _NotAnAdapter:
+    """Class that does NOT subclass L2AdapterInterface."""
+
+    pass
+
+
+def _make_fake_module(
+    adapter_cls: type,
+    class_name: str = "FakeL2Adapter",
+) -> types.ModuleType:
+    """Create a fake Python module containing *adapter_cls*."""
+    mod = types.ModuleType("fake_l2_module")
+    setattr(mod, class_name, adapter_cls)
+    return mod
+
+
+# =========================================================
+# Tests: factory registry basics
+# =========================================================
+
+
+class TestFactoryRegistry:
+    """Tests for register/create via factory registry."""
+
+    def test_mock_factory_is_registered(self):
+        """Mock adapter factory should be auto-registered
+        on import."""
+        config = MockL2AdapterConfig(
+            max_size_gb=0.001,
+            mock_bandwidth_gb=10.0,
+        )
+        name = get_type_name_for_config(config)
+        assert name == "mock"
+
+    def test_raw_block_factory_is_registered(self):
+        config = RawBlockL2AdapterConfig(
+            device_path="/tmp/raw-block-dev",
+            slot_bytes=64 * 1024,
+            use_odirect=False,
+            meta_enable_periodic=False,
+        )
+        name = get_type_name_for_config(config)
+        assert name == "raw_block"
+
+    def test_create_mock_via_registry(self):
+        """create_l2_adapter_from_registry creates a
+        MockL2Adapter."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+            MockL2Adapter,
+        )
+
+        config = MockL2AdapterConfig(
+            max_size_gb=0.001,
+            mock_bandwidth_gb=10.0,
+        )
+        adapter = create_l2_adapter_from_registry(config)
+        assert isinstance(adapter, MockL2Adapter)
+        adapter.close()
+
+    @pytest.mark.skipif(
+        not _has_raw_block_ext(),
+        reason="lmcache_rust_raw_block_io extension not installed",
+    )
+    def test_create_raw_block_via_registry(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.raw_block_l2_adapter import (
+            RawBlockL2Adapter,
+        )
+
+        with tempfile.TemporaryDirectory() as td:
+            dev_path = os.path.join(td, "dev.bin")
+            with open(dev_path, "wb") as f:
+                f.truncate(8 * 1024 * 1024)
+
+            config = RawBlockL2AdapterConfig(
+                device_path=dev_path,
+                slot_bytes=64 * 1024,
+                use_odirect=False,
+                meta_total_bytes=1 * 1024 * 1024,
+                meta_enable_periodic=False,
+            )
+            adapter = create_l2_adapter_from_registry(config)
+            assert isinstance(adapter, RawBlockL2Adapter)
+            adapter.close()
+
+    def test_duplicate_factory_raises(self):
+        """Registering the same factory name twice should
+        raise ValueError."""
+        with pytest.raises(ValueError, match="already registered"):
+            register_l2_adapter_factory("mock", lambda c, **kw: None)
+
+    def test_unknown_config_raises(self):
+        """Config class not in the registry should fail."""
+
+        class _UnknownConfig:
+            pass
+
+        with pytest.raises(ValueError, match="Unregistered"):
+            get_type_name_for_config(_UnknownConfig())
+
+
+# =========================================================
+# Tests: PluginL2AdapterConfig parsing
+# =========================================================
+
+
+class TestPluginL2AdapterConfig:
+    """Tests for PluginL2AdapterConfig.from_dict."""
+
+    def test_valid_config(self):
+        d = {
+            "type": "plugin",
+            "module_path": "my.module",
+            "class_name": "MyAdapter",
+            "adapter_params": {"host": "localhost"},
+        }
+        cfg = PluginL2AdapterConfig.from_dict(d)
+        assert cfg.module_path == "my.module"
+        assert cfg.class_name == "MyAdapter"
+        assert cfg.adapter_params == {"host": "localhost"}
+
+    def test_default_adapter_params(self):
+        d = {
+            "type": "plugin",
+            "module_path": "my.module",
+            "class_name": "MyAdapter",
+        }
+        cfg = PluginL2AdapterConfig.from_dict(d)
+        assert cfg.adapter_params == {}
+
+    def test_missing_module_path_raises(self):
+        d = {"type": "plugin", "class_name": "X"}
+        with pytest.raises(ValueError, match="module_path"):
+            PluginL2AdapterConfig.from_dict(d)
+
+    def test_missing_class_name_raises(self):
+        d = {"type": "plugin", "module_path": "x"}
+        with pytest.raises(ValueError, match="class_name"):
+            PluginL2AdapterConfig.from_dict(d)
+
+    def test_invalid_adapter_params_raises(self):
+        d = {
+            "type": "plugin",
+            "module_path": "x",
+            "class_name": "X",
+            "adapter_params": "not_a_dict",
+        }
+        with pytest.raises(ValueError, match="adapter_params"):
+            PluginL2AdapterConfig.from_dict(d)
+
+
+# =========================================================
+# Tests: plugin adapter factory dynamic loading
+# =========================================================
+
+
+class TestPluginAdapterFactory:
+    """Tests for the plugin adapter factory using monkeypatch
+    to mock importlib.import_module."""
+
+    def test_load_external_adapter(self, monkeypatch):
+        """Successfully load an external adapter class."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import plugin_l2_adapter as plugin_mod
+
+        # Make _FakeL2Adapter pass issubclass check
+        monkeypatch.setattr(
+            plugin_mod,
+            "_L2AI",
+            _FakeL2Adapter,
+        )
+
+        fake_mod = _make_fake_module(_FakeL2Adapter)
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda path: fake_mod,
+        )
+
+        config = PluginL2AdapterConfig(
+            module_path="fake_l2_module",
+            class_name="FakeL2Adapter",
+            adapter_params={"host": "localhost"},
+        )
+        adapter = create_l2_adapter_from_registry(config)
+        assert isinstance(adapter, _FakeL2Adapter)
+        assert adapter.params["host"] == "localhost"
+
+    def test_import_error_raises(self, monkeypatch):
+        """ImportError propagates when module not found."""
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: (_ for _ in ()).throw(ImportError("no such module")),
+        )
+        config = PluginL2AdapterConfig(
+            module_path="nonexistent",
+            class_name="X",
+        )
+        with pytest.raises(ImportError, match="nonexistent"):
+            create_l2_adapter_from_registry(config)
+
+    def test_missing_class_raises(self, monkeypatch):
+        """AttributeError when class not in module."""
+        fake_mod = types.ModuleType("empty_mod")
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: fake_mod,
+        )
+        config = PluginL2AdapterConfig(
+            module_path="empty_mod",
+            class_name="NoSuchClass",
+        )
+        with pytest.raises(AttributeError, match="NoSuchClass"):
+            create_l2_adapter_from_registry(config)
+
+    def test_not_subclass_raises(self, monkeypatch):
+        """TypeError when class is not an L2AdapterInterface
+        subclass."""
+        fake_mod = _make_fake_module(_NotAnAdapter, "BadAdapter")
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: fake_mod,
+        )
+        config = PluginL2AdapterConfig(
+            module_path="fake_mod",
+            class_name="BadAdapter",
+        )
+        with pytest.raises(TypeError, match="not a subclass"):
+            create_l2_adapter_from_registry(config)
+
+
+# =========================================================
+# Tests: plugin registration and initialization
+# =========================================================
+
+
+class _FakeL2AdapterWithDesc:
+    """Stub that records l1_memory_desc."""
+
+    def __init__(self, config, **kwargs):
+        self.config = config
+        self.l1_memory_desc = kwargs.get("l1_memory_desc")
+
+
+class _FakeConfig(L2AdapterConfigBase):
+    """Minimal config subclass for discovery tests."""
+
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "_FakeConfig":
+        return cls(**d)
+
+    @classmethod
+    def help(cls) -> str:
+        return "fake"
+
+
+class TestPluginRegistration:
+    """Verify plugin self-registration on import."""
+
+    def test_plugin_type_registered(self):
+        """'plugin' config type should be registered."""
+        cfg = PluginL2AdapterConfig(module_path="x", class_name="X")
+        name = get_type_name_for_config(cfg)
+        assert name == "plugin"
+
+    def test_plugin_factory_registered(self):
+        """'plugin' factory should be callable via
+        create_l2_adapter_from_registry (smoke test
+        with ImportError)."""
+        cfg = PluginL2AdapterConfig(
+            module_path="nonexistent.module",
+            class_name="X",
+        )
+        with pytest.raises(ImportError):
+            create_l2_adapter_from_registry(cfg)
+
+
+class TestPluginInitialization:
+    """Verify config-class discovery and l1_memory_desc
+    forwarding during plugin initialization."""
+
+    def _patch_base(self, monkeypatch, adapter_cls):
+        """Make *adapter_cls* pass issubclass check."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import plugin_l2_adapter as plugin_mod
+
+        monkeypatch.setattr(
+            plugin_mod,
+            "_L2AI",
+            adapter_cls,
+        )
+
+    # -- l1_memory_desc forwarding --
+
+    def test_l1_memory_desc_forwarded(self, monkeypatch):
+        """l1_memory_desc should reach the adapter
+        constructor when provided."""
+        self._patch_base(monkeypatch, _FakeL2AdapterWithDesc)
+        fake_mod = _make_fake_module(
+            _FakeL2AdapterWithDesc,
+            "Adapter",
+        )
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda _: fake_mod,
+        )
+        cfg = PluginL2AdapterConfig(
+            module_path="m",
+            class_name="Adapter",
+            adapter_params={"k": "v"},
+        )
+        sentinel = object()
+        adapter = create_l2_adapter_from_registry(cfg, l1_memory_desc=sentinel)
+        assert adapter.l1_memory_desc is sentinel
+
+    def test_l1_memory_desc_omitted(self, monkeypatch):
+        """l1_memory_desc should be None when not
+        provided."""
+        self._patch_base(monkeypatch, _FakeL2AdapterWithDesc)
+        fake_mod = _make_fake_module(
+            _FakeL2AdapterWithDesc,
+            "Adapter",
+        )
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda _: fake_mod,
+        )
+        cfg = PluginL2AdapterConfig(
+            module_path="m",
+            class_name="Adapter",
+        )
+        adapter = create_l2_adapter_from_registry(cfg)
+        assert adapter.l1_memory_desc is None
+
+    # -- config class discovery --
+
+    def test_init_with_explicit_config_class(self, monkeypatch):
+        """Explicit config_class_name should be used."""
+        self._patch_base(monkeypatch, _FakeL2AdapterWithDesc)
+        fake_mod = _make_fake_module(
+            _FakeL2AdapterWithDesc,
+            "Adapter",
+        )
+        fake_mod.MyCfg = _FakeConfig  # type: ignore[attr-defined]
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda _: fake_mod,
+        )
+        cfg = PluginL2AdapterConfig(
+            module_path="m",
+            class_name="Adapter",
+            config_class_name="MyCfg",
+            adapter_params={"x": 1},
+        )
+        adapter = create_l2_adapter_from_registry(cfg)
+        assert isinstance(adapter.config, _FakeConfig)
+        assert adapter.config.kwargs == {"x": 1}
+
+    def test_init_with_convention_config_class(self, monkeypatch):
+        """Config class discovered via ClassName+'Config'
+        convention."""
+        self._patch_base(monkeypatch, _FakeL2AdapterWithDesc)
+        fake_mod = _make_fake_module(
+            _FakeL2AdapterWithDesc,
+            "Adapter",
+        )
+        # Convention: "Adapter" + "Config"
+        fake_mod.AdapterConfig = _FakeConfig  # type: ignore[attr-defined]
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda _: fake_mod,
+        )
+        cfg = PluginL2AdapterConfig(
+            module_path="m",
+            class_name="Adapter",
+            adapter_params={"y": 2},
+        )
+        adapter = create_l2_adapter_from_registry(cfg)
+        assert isinstance(adapter.config, _FakeConfig)
+
+    def test_init_fallback_raw_dict(self, monkeypatch):
+        """When no config class is found, adapter receives
+        a raw dict."""
+        self._patch_base(monkeypatch, _FakeL2AdapterWithDesc)
+        fake_mod = _make_fake_module(
+            _FakeL2AdapterWithDesc,
+            "Adapter",
+        )
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda _: fake_mod,
+        )
+        cfg = PluginL2AdapterConfig(
+            module_path="m",
+            class_name="Adapter",
+            adapter_params={"z": 3},
+        )
+        adapter = create_l2_adapter_from_registry(cfg)
+        assert isinstance(adapter.config, dict)
+        assert adapter.config == {"z": 3}
+
+
+# =========================================================
+# Tests: lazy loading (add_pending_module,
+# ensure_adapter_loaded, load_all_adapters,
+# get_all_registered_names)
+# =========================================================
+
+
+class TestLazyLoading:
+    """Tests for the deferred module import mechanism."""
+
+    @pytest.fixture(autouse=True)
+    def _isolate_registry(self, monkeypatch):
+        """Snapshot and restore the factory registry and
+        pending-module list around each test."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        orig_reg = fmod._L2_ADAPTER_FACTORY_REGISTRY.copy()
+        orig_pending = list(fmod._PENDING_MODULES)
+        # Start each test with a clean slate
+        fmod._PENDING_MODULES.clear()
+        yield
+        fmod._L2_ADAPTER_FACTORY_REGISTRY.clear()
+        fmod._L2_ADAPTER_FACTORY_REGISTRY.update(orig_reg)
+        fmod._PENDING_MODULES.clear()
+        fmod._PENDING_MODULES.extend(orig_pending)
+
+    # -- add_pending_module --
+
+    def test_add_pending_module_appends(self):
+        """Module path is appended to the pending list."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.factory import (
+            _PENDING_MODULES,
+            add_pending_module,
+        )
+
+        add_pending_module("fake.mod.a")
+        assert "fake.mod.a" in _PENDING_MODULES
+
+    def test_add_pending_module_dedup(self):
+        """Duplicate paths are not added twice."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.factory import (
+            _PENDING_MODULES,
+            add_pending_module,
+        )
+
+        add_pending_module("fake.mod.b")
+        add_pending_module("fake.mod.b")
+        assert _PENDING_MODULES.count("fake.mod.b") == 1
+
+    # -- ensure_adapter_loaded --
+
+    def test_ensure_already_registered(self):
+        """No import happens when name is already in the
+        registry."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.factory import (
+            _L2_ADAPTER_FACTORY_REGISTRY,
+            _PENDING_MODULES,
+            ensure_adapter_loaded,
+        )
+
+        _L2_ADAPTER_FACTORY_REGISTRY["pre"] = lambda c, d: None
+        _PENDING_MODULES.append("should.not.import")
+        ensure_adapter_loaded("pre")
+        # Pending list untouched
+        assert "should.not.import" in _PENDING_MODULES
+
+    def test_ensure_imports_until_found(self, monkeypatch):
+        """Modules are imported one-by-one until the
+        requested name appears in the registry."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        imported: list[str] = []
+
+        def _fake_import(path):
+            imported.append(path)
+            if path == "mod_b":
+                fmod._L2_ADAPTER_FACTORY_REGISTRY["lazy_b"] = lambda c, d: None
+
+        monkeypatch.setattr("importlib.import_module", _fake_import)
+        fmod._PENDING_MODULES.extend(["mod_a", "mod_b", "mod_c"])
+        fmod.ensure_adapter_loaded("lazy_b")
+
+        assert imported == ["mod_a", "mod_b"]
+        # mod_c should remain pending
+        assert "mod_c" in fmod._PENDING_MODULES
+
+    def test_ensure_raises_last_import_error(self, monkeypatch):
+        """When all pending modules fail, the last
+        ImportError is raised."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        def _fail_import(path):
+            raise ImportError(path)
+
+        monkeypatch.setattr("importlib.import_module", _fail_import)
+        fmod._PENDING_MODULES.extend(["bad_a", "bad_b"])
+
+        with pytest.raises(ImportError, match="bad_b"):
+            fmod.ensure_adapter_loaded("missing")
+
+    def test_ensure_no_error_when_not_found_silently(self, monkeypatch):
+        """When pending modules import OK but name is
+        still missing, no error is raised (no last_err).
+        """
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        monkeypatch.setattr("importlib.import_module", lambda p: None)
+        fmod._PENDING_MODULES.extend(["ok_a", "ok_b"])
+
+        # Should not raise
+        fmod.ensure_adapter_loaded("nonexistent")
+
+    # -- load_all_adapters --
+
+    def test_load_all_adapters_imports_everything(self, monkeypatch):
+        """All pending modules are imported."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        imported: list[str] = []
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: imported.append(p),
+        )
+        fmod._PENDING_MODULES.extend(["m1", "m2", "m3"])
+        fmod.load_all_adapters()
+
+        assert imported == ["m1", "m2", "m3"]
+        assert len(fmod._PENDING_MODULES) == 0
+
+    def test_load_all_adapters_skips_failures(self, monkeypatch):
+        """Modules that fail to import are silently
+        skipped."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        imported: list[str] = []
+
+        def _selective_import(path):
+            if path == "bad":
+                raise ImportError(path)
+            imported.append(path)
+
+        monkeypatch.setattr("importlib.import_module", _selective_import)
+        fmod._PENDING_MODULES.extend(["good1", "bad", "good2"])
+        fmod.load_all_adapters()
+
+        assert imported == ["good1", "good2"]
+        assert len(fmod._PENDING_MODULES) == 0
+
+    # -- get_all_registered_names --
+
+    def test_get_all_registered_names_sorted(self, monkeypatch):
+        """Returns sorted list after loading all pending
+        modules."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        def _register_import(path):
+            fmod._L2_ADAPTER_FACTORY_REGISTRY[path] = lambda c, d: None
+
+        monkeypatch.setattr("importlib.import_module", _register_import)
+        fmod._PENDING_MODULES.extend(["z_mod", "a_mod"])
+
+        names = fmod.get_all_registered_names()
+        # Should contain at least the two we just added
+        assert "z_mod" in names
+        assert "a_mod" in names
+        # Must be sorted
+        assert names == sorted(names)
+
+    def test_lazy_module_not_in_sys_modules(self, monkeypatch):
+        """Pending modules are NOT in sys.modules until
+        ensure_adapter_loaded triggers the import."""
+        # Standard
+        import sys
+
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import factory as fmod
+
+        sentinel = "test.lazy.sentinel.module"
+        fmod._PENDING_MODULES.append(sentinel)
+        assert sentinel not in sys.modules
+
+        def _fake_import(path):
+            mod = types.ModuleType(path)
+            sys.modules[path] = mod
+            fmod._L2_ADAPTER_FACTORY_REGISTRY["sentinel"] = lambda c, d: None
+
+        monkeypatch.setattr("importlib.import_module", _fake_import)
+        fmod.ensure_adapter_loaded("sentinel")
+        assert sentinel in sys.modules
+        # Cleanup
+        sys.modules.pop(sentinel, None)
+
+
+# =========================================================
+# Tests: create_l2_adapter public API
+# =========================================================
+
+
+class TestCreateL2Adapter:
+    """Tests for the public create_l2_adapter function."""
+
+    def test_create_mock_adapter(self):
+        """create_l2_adapter dispatches to MockL2Adapter."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import (
+            create_l2_adapter,
+        )
+        from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+            MockL2Adapter,
+        )
+
+        config = MockL2AdapterConfig(
+            max_size_gb=0.001,
+            mock_bandwidth_gb=10.0,
+        )
+        adapter = create_l2_adapter(config)
+        assert isinstance(adapter, MockL2Adapter)
+        adapter.close()
+
+
+# =========================================================
+# Tests: NativePluginL2AdapterConfig factory
+# =========================================================
+
+
+class _FakeNativeConnector:
+    """Minimal mock that satisfies the native connector
+    interface check."""
+
+    def __init__(self, **kwargs):
+        self.kwargs = kwargs
+
+    def event_fd(self):
+        return -1
+
+    def submit_batch_get(self, keys, memoryviews):
+        return 0
+
+    def submit_batch_set(self, keys, memoryviews):
+        return 0
+
+    def submit_batch_exists(self, keys):
+        return 0
+
+    def drain_completions(self):
+        return []
+
+    def close(self):
+        pass
+
+
+class _MissingMethodConnector:
+    """Connector missing the 'close' method."""
+
+    def event_fd(self):
+        return -1
+
+    def submit_batch_get(self, keys, memoryviews):
+        return 0
+
+    def submit_batch_set(self, keys, memoryviews):
+        return 0
+
+    def submit_batch_exists(self, keys):
+        return 0
+
+    def drain_completions(self):
+        return []
+
+
+class TestNativePluginFactory:
+    """Tests for the native_plugin adapter factory."""
+
+    def test_load_native_connector(self, monkeypatch):
+        """Successfully load a native connector."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+            NativeConnectorL2Adapter,
+        )
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        fake_mod = types.ModuleType("fake_native_mod")
+        fake_mod.FakeClient = _FakeNativeConnector  # type: ignore[attr-defined]
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: fake_mod,
+        )
+
+        cfg = NativePluginL2AdapterConfig(
+            module_path="fake_native_mod",
+            class_name="FakeClient",
+            adapter_params={"host": "localhost"},
+        )
+        adapter = create_l2_adapter_from_registry(cfg)
+        assert isinstance(adapter, NativeConnectorL2Adapter)
+        adapter.close()
+
+    def test_import_error_raises(self, monkeypatch):
+        """ImportError propagates when module not found."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: (_ for _ in ()).throw(ImportError("no such module")),
+        )
+        cfg = NativePluginL2AdapterConfig(
+            module_path="nonexistent",
+            class_name="X",
+        )
+        with pytest.raises(ImportError, match="nonexistent"):
+            create_l2_adapter_from_registry(cfg)
+
+    def test_missing_class_raises(self, monkeypatch):
+        """AttributeError when class not in module."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        fake_mod = types.ModuleType("empty_mod")
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: fake_mod,
+        )
+        cfg = NativePluginL2AdapterConfig(
+            module_path="empty_mod",
+            class_name="NoSuchClass",
+        )
+        with pytest.raises(AttributeError, match="NoSuchClass"):
+            create_l2_adapter_from_registry(cfg)
+
+    def test_missing_method_raises(self, monkeypatch):
+        """TypeError when connector is missing a required
+        method."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        fake_mod = types.ModuleType("incomplete_mod")
+        fake_mod.Bad = _MissingMethodConnector  # type: ignore[attr-defined]
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: fake_mod,
+        )
+        cfg = NativePluginL2AdapterConfig(
+            module_path="incomplete_mod",
+            class_name="Bad",
+        )
+        with pytest.raises(TypeError, match="close"):
+            create_l2_adapter_from_registry(cfg)
+
+    def test_adapter_params_forwarded(self, monkeypatch):
+        """adapter_params are forwarded as kwargs to the
+        connector class."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+            NativeConnectorL2Adapter,
+        )
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        fake_mod = types.ModuleType("param_mod")
+        fake_mod.Client = _FakeNativeConnector  # type: ignore[attr-defined]
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda p: fake_mod,
+        )
+
+        cfg = NativePluginL2AdapterConfig(
+            module_path="param_mod",
+            class_name="Client",
+            adapter_params={"host": "myhost", "port": 42},
+        )
+        adapter = create_l2_adapter_from_registry(cfg)
+        assert isinstance(adapter, NativeConnectorL2Adapter)
+        adapter.close()
+
+    def test_native_plugin_type_registered(self):
+        """'native_plugin' config type should be
+        registered."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        cfg = NativePluginL2AdapterConfig(
+            module_path="x",
+            class_name="X",
+        )
+        name = get_type_name_for_config(cfg)
+        assert name == "native_plugin"
+
+
+# =========================================================
+# Tests: FSNativeL2AdapterConfig factory
+# =========================================================
+
+
+class _FakeLMCacheFSClient:
+    """Mock for lmcache.lmcache_fs.LMCacheFSClient."""
+
+    def __init__(
+        self,
+        base_path,
+        num_workers,
+        relative_tmp_dir="",
+        use_odirect=False,
+        read_ahead_size=0,
+    ):
+        self.base_path = base_path
+        self.num_workers = num_workers
+        self.relative_tmp_dir = relative_tmp_dir
+        self.use_odirect = use_odirect
+        self.read_ahead_size = read_ahead_size
+        self._efd = create_event_notifier()
+        self._closed = False
+
+    def event_fd(self):
+        return self._efd.fileno()
+
+    def submit_batch_get(self, keys, memoryviews):
+        return 0
+
+    def submit_batch_set(self, keys, memoryviews):
+        return 0
+
+    def submit_batch_exists(self, keys):
+        return 0
+
+    def drain_completions(self):
+        return []
+
+    def close(self):
+        if not self._closed:
+            self._closed = True
+            self._efd.close()
+
+
+class TestFSNativeAdapterFactory:
+    """Tests for the fs_native adapter factory."""
+
+    def test_factory_creates_adapter(self, monkeypatch):
+        """Factory creates a NativeConnectorL2Adapter
+        wrapping the FS client."""
+        # First Party
+        # Re-register so registry points to patched fn
+        from lmcache.v1.distributed.l2_adapters.factory import (
+            _L2_ADAPTER_FACTORY_REGISTRY,
+        )
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+        from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+            NativeConnectorL2Adapter,
+        )
+
+        old = _L2_ADAPTER_FACTORY_REGISTRY["fs_native"]
+        _L2_ADAPTER_FACTORY_REGISTRY["fs_native"] = _patched_fs_factory
+
+        try:
+            cfg = FSNativeL2AdapterConfig(
+                base_path="/tmp/lmcache_test_factory",
+                num_workers=2,
+            )
+            adapter = create_l2_adapter_from_registry(cfg)
+            assert isinstance(adapter, NativeConnectorL2Adapter)
+            adapter.close()
+        finally:
+            _L2_ADAPTER_FACTORY_REGISTRY["fs_native"] = old
+
+    def test_factory_forwards_all_params(self, monkeypatch):
+        """All config params are forwarded to the
+        FS client constructor."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        captured: dict = {}
+
+        class _CaptureFSClient(_FakeLMCacheFSClient):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+                captured["args"] = args
+                captured["kwargs"] = kwargs
+
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.factory import (
+            _L2_ADAPTER_FACTORY_REGISTRY,
+        )
+
+        def _capture_factory(config, l1_memory_desc=None):
+            assert isinstance(config, FSNativeL2AdapterConfig)
+            client = _CaptureFSClient(
+                config.base_path,
+                config.num_workers,
+                config.relative_tmp_dir,
+                config.use_odirect,
+                config.read_ahead_size or 0,
+            )
+            # First Party
+            from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+                NativeConnectorL2Adapter,
+            )
+
+            return NativeConnectorL2Adapter(client)
+
+        old = _L2_ADAPTER_FACTORY_REGISTRY["fs_native"]
+        _L2_ADAPTER_FACTORY_REGISTRY["fs_native"] = _capture_factory
+
+        try:
+            cfg = FSNativeL2AdapterConfig(
+                base_path="/data/kv",
+                num_workers=8,
+                relative_tmp_dir=".tmp",
+                use_odirect=True,
+                read_ahead_size=4096,
+            )
+            adapter = create_l2_adapter_from_registry(cfg)
+            assert captured["args"] == (
+                "/data/kv",
+                8,
+                ".tmp",
+                True,
+                4096,
+            )
+            adapter.close()
+        finally:
+            _L2_ADAPTER_FACTORY_REGISTRY["fs_native"] = old
+
+    def test_factory_import_error_raises(self, monkeypatch):
+        """RuntimeError raised when C++ FS extension is
+        not available."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        # Patch the actual factory to simulate missing
+        # C++ extension
+        def _broken_import(name, *args, **kwargs):
+            if name == "lmcache.lmcache_fs":
+                raise ImportError("no C++ FS extension")
+            return _original_import(name, *args, **kwargs)
+
+        # Standard
+        import builtins
+
+        _original_import = builtins.__import__
+        monkeypatch.setattr(builtins, "__import__", _broken_import)
+
+        cfg = FSNativeL2AdapterConfig(
+            base_path="/tmp/test",
+        )
+        with pytest.raises(RuntimeError, match="C\\+\\+ FS"):
+            create_l2_adapter_from_registry(cfg)
+
+    def test_fs_native_type_registered(self):
+        """'fs_native' config type should be
+        registered."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        cfg = FSNativeL2AdapterConfig(
+            base_path="/tmp/test",
+        )
+        name = get_type_name_for_config(cfg)
+        assert name == "fs_native"
+
+    def test_fs_native_factory_registered(self):
+        """'fs_native' factory should be callable via
+        create_l2_adapter_from_registry (smoke test
+        with RuntimeError from missing C++ ext)."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        cfg = FSNativeL2AdapterConfig(
+            base_path="/tmp/test_smoke",
+        )
+        # Without the C++ extension built, expect
+        # RuntimeError
+        try:
+            adapter = create_l2_adapter_from_registry(cfg)
+            adapter.close()
+        except RuntimeError:
+            pass  # Expected when C++ ext not built
+
+    def test_read_ahead_size_none_becomes_zero(self, monkeypatch):
+        """read_ahead_size=None should be passed as 0
+        to the native client."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        captured: dict = {}
+
+        class _CaptureFSClient2(_FakeLMCacheFSClient):
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+                captured["read_ahead"] = args[4]
+
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.factory import (
+            _L2_ADAPTER_FACTORY_REGISTRY,
+        )
+
+        def _capture_factory2(config, l1_memory_desc=None):
+            assert isinstance(config, FSNativeL2AdapterConfig)
+            client = _CaptureFSClient2(
+                config.base_path,
+                config.num_workers,
+                config.relative_tmp_dir,
+                config.use_odirect,
+                config.read_ahead_size or 0,
+            )
+            # First Party
+            from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+                NativeConnectorL2Adapter,
+            )
+
+            return NativeConnectorL2Adapter(client)
+
+        old = _L2_ADAPTER_FACTORY_REGISTRY["fs_native"]
+        _L2_ADAPTER_FACTORY_REGISTRY["fs_native"] = _capture_factory2
+
+        try:
+            cfg = FSNativeL2AdapterConfig(
+                base_path="/tmp/test_ra",
+            )
+            assert cfg.read_ahead_size is None
+            adapter = create_l2_adapter_from_registry(cfg)
+            assert captured["read_ahead"] == 0
+            adapter.close()
+        finally:
+            _L2_ADAPTER_FACTORY_REGISTRY["fs_native"] = old
+
+
+def _patched_fs_factory(config, l1_memory_desc=None):
+    """Factory that uses _FakeLMCacheFSClient instead
+    of the real C++ extension."""
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+        FSNativeL2AdapterConfig,
+    )
+    from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+        NativeConnectorL2Adapter,
+    )
+
+    assert isinstance(config, FSNativeL2AdapterConfig)
+    client = _FakeLMCacheFSClient(
+        config.base_path,
+        config.num_workers,
+        config.relative_tmp_dir,
+        config.use_odirect,
+        config.read_ahead_size or 0,
+    )
+    return NativeConnectorL2Adapter(client)
diff --git a/tests/v1/distributed/test_lru_eviction_policy.py b/tests/v1/distributed/test_lru_eviction_policy.py
new file mode 100644
index 0000000..edcb117
--- /dev/null
+++ b/tests/v1/distributed/test_lru_eviction_policy.py
@@ -0,0 +1,403 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for LRU eviction policy.
+
+These tests verify the basic functionality of the LRUEvictionPolicy:
+1. Key tracking (create, delete)
+2. LRU ordering (least recently used first for eviction)
+3. Touch updates access order
+4. Expected ratio controls eviction count
+5. Eviction destinations
+"""
+
+# Third Party
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.eviction_policy import LRUEvictionPolicy
+from lmcache.v1.distributed.internal_api import (
+    EvictionDestination,
+)
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def make_key(chunk_hash: int, model: str = "model", kv_rank: int = 0) -> ObjectKey:
+    """Create an ObjectKey for testing."""
+    hash_bytes = ObjectKey.IntHash2Bytes(chunk_hash)
+    return ObjectKey(chunk_hash=hash_bytes, model_name=model, kv_rank=kv_rank)
+
+
+# =============================================================================
+# Basic Functionality Tests
+# =============================================================================
+
+
+class TestLRUEvictionPolicyBasic:
+    """Tests for basic LRU eviction policy functionality."""
+
+    def test_empty_policy_has_no_tracked_keys(self):
+        """A new policy should have no tracked keys."""
+        policy = LRUEvictionPolicy()
+        assert policy.get_num_tracked_keys() == 0
+
+    def test_empty_policy_returns_no_eviction_actions(self):
+        """An empty policy should return no eviction actions."""
+        policy = LRUEvictionPolicy()
+        actions = policy.get_eviction_actions(1.0)
+        assert actions == []
+
+    def test_create_keys_increases_tracked_count(self):
+        """Creating keys should increase the tracked key count."""
+        policy = LRUEvictionPolicy()
+        keys = [make_key(1), make_key(2), make_key(3)]
+        policy.on_keys_created(keys)
+        assert policy.get_num_tracked_keys() == 3
+
+    def test_delete_keys_decreases_tracked_count(self):
+        """Deleting keys should decrease the tracked key count."""
+        policy = LRUEvictionPolicy()
+        keys = [make_key(1), make_key(2), make_key(3)]
+        policy.on_keys_created(keys)
+        policy.on_keys_removed([make_key(2)])
+        assert policy.get_num_tracked_keys() == 2
+
+    def test_delete_nonexistent_key_is_safe(self):
+        """Deleting a nonexistent key should not raise an error."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_removed([make_key(999)])
+        assert policy.get_num_tracked_keys() == 0
+
+    def test_create_duplicate_key_does_not_increase_count(self):
+        """Creating the same key twice should not duplicate it."""
+        policy = LRUEvictionPolicy()
+        key = make_key(1)
+        policy.on_keys_created([key])
+        policy.on_keys_created([key])
+        assert policy.get_num_tracked_keys() == 1
+
+
+# =============================================================================
+# LRU Ordering Tests
+# =============================================================================
+
+
+class TestLRUEvictionPolicyOrdering:
+    """Tests for LRU ordering behavior."""
+
+    def test_eviction_order_is_lru(self):
+        """Keys should be evicted in LRU order (oldest first)."""
+        policy = LRUEvictionPolicy()
+        # Create keys in order: 1, 2, 3
+        policy.on_keys_created([make_key(1)])
+        policy.on_keys_created([make_key(2)])
+        policy.on_keys_created([make_key(3)])
+
+        # Get candidates - should be in LRU order: 1, 2, 3
+        candidates = policy.get_eviction_candidates(3)
+        assert len(candidates) == 3
+        assert ObjectKey.Bytes2IntHash(candidates[0].chunk_hash) == 1
+        assert ObjectKey.Bytes2IntHash(candidates[1].chunk_hash) == 2
+        assert ObjectKey.Bytes2IntHash(candidates[2].chunk_hash) == 3
+
+    def test_touch_moves_key_to_most_recent(self):
+        """Touching a key should move it to the most recently used position."""
+        policy = LRUEvictionPolicy()
+        # Create keys in order: 1, 2, 3, evict order is 3, 2, 1
+        policy.on_keys_created([make_key(1), make_key(2), make_key(3)])
+
+        # Touch key 3 - should move it to most recent
+        policy.on_keys_touched([make_key(3)])
+
+        # Now order should be: 2, 1, 3
+        candidates = policy.get_eviction_candidates(3)
+        assert ObjectKey.Bytes2IntHash(candidates[0].chunk_hash) == 2
+        assert ObjectKey.Bytes2IntHash(candidates[1].chunk_hash) == 1
+        assert ObjectKey.Bytes2IntHash(candidates[2].chunk_hash) == 3
+
+    def test_touch_nonexistent_key_is_safe(self):
+        """Touching a nonexistent key should not raise an error."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(1)])
+        policy.on_keys_touched([make_key(999)])
+        assert policy.get_num_tracked_keys() == 1
+
+    def test_create_existing_key_moves_to_most_recent(self):
+        """Creating an existing key should move it to most recent position."""
+        policy = LRUEvictionPolicy()
+        # Create keys in order: 1, 2, 3, evict order is 3, 2, 1
+        policy.on_keys_created([make_key(1), make_key(2), make_key(3)])
+
+        # Create key 3 again - should move to end
+        policy.on_keys_created([make_key(3)])
+
+        # Now order should be: 2, 1, 3
+        candidates = policy.get_eviction_candidates(3)
+        assert ObjectKey.Bytes2IntHash(candidates[0].chunk_hash) == 2
+        assert ObjectKey.Bytes2IntHash(candidates[1].chunk_hash) == 1
+        assert ObjectKey.Bytes2IntHash(candidates[2].chunk_hash) == 3
+
+
+# =============================================================================
+# Expected Ratio Tests
+# =============================================================================
+
+
+class TestLRUEvictionPolicyRatio:
+    """Tests for expected_ratio behavior in get_eviction_actions."""
+
+    def test_ratio_zero_returns_no_actions(self):
+        """A ratio of 0 should return no eviction actions."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(i) for i in range(10)])
+        actions = policy.get_eviction_actions(0.0)
+        assert actions == []
+
+    def test_ratio_one_returns_all_keys(self):
+        """A ratio of 1.0 should return all keys (up to batch size)."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(i) for i in range(10)])
+        actions = policy.get_eviction_actions(1.0)
+        assert len(actions) == 1
+        assert len(actions[0].keys) == 10
+
+    def test_ratio_half_returns_half_keys(self):
+        """A ratio of 0.5 should return approximately half the keys."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(i) for i in range(10)])
+        actions = policy.get_eviction_actions(0.5)
+        assert len(actions) == 1
+        assert len(actions[0].keys) == 5
+
+    def test_small_ratio_returns_at_least_one_key(self):
+        """A small ratio > 0 should return at least 1 key."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(i) for i in range(10)])
+        actions = policy.get_eviction_actions(0.01)
+        assert len(actions) == 1
+        assert len(actions[0].keys) >= 1
+
+    def test_ratio_clamped_to_valid_range(self):
+        """Ratios outside [0, 1] should be clamped."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(i) for i in range(10)])
+
+        # Negative ratio should be treated as 0
+        actions = policy.get_eviction_actions(-0.5)
+        assert actions == []
+
+        # Ratio > 1 should be treated as 1
+        actions = policy.get_eviction_actions(1.5)
+        assert len(actions[0].keys) == 10
+
+
+# =============================================================================
+# Eviction Destination Tests
+# =============================================================================
+
+
+class TestLRUEvictionPolicyDestination:
+    """Tests for eviction destination behavior."""
+
+    def test_default_destination_is_discard(self):
+        """Default destination should be DISCARD."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(1)])
+        actions = policy.get_eviction_actions(1.0)
+        assert actions[0].destination == EvictionDestination.DISCARD
+
+    def test_custom_default_destination(self):
+        """Custom default destination should be used."""
+        policy = LRUEvictionPolicy(default_destination=EvictionDestination.L2_CACHE)
+        policy.on_keys_created([make_key(1)])
+        actions = policy.get_eviction_actions(1.0)
+        assert actions[0].destination == EvictionDestination.L2_CACHE
+
+    def test_registered_destination_takes_precedence(self):
+        """Registered destination should take precedence over default."""
+        policy = LRUEvictionPolicy(default_destination=EvictionDestination.DISCARD)
+        policy.register_eviction_destination(EvictionDestination.L2_CACHE)
+        policy.on_keys_created([make_key(1)])
+        actions = policy.get_eviction_actions(1.0)
+        assert actions[0].destination == EvictionDestination.L2_CACHE
+
+
+# =============================================================================
+# Get Eviction Candidates Tests
+# =============================================================================
+
+
+class TestLRUEvictionPolicyCandidates:
+    """Tests for get_eviction_candidates method."""
+
+    def test_get_candidates_returns_lru_order(self):
+        """Candidates should be returned in LRU order."""
+        policy = LRUEvictionPolicy()
+        # Create keys in order: 1, 2, 3, evict order is 3, 2, 1
+        policy.on_keys_created([make_key(1), make_key(2), make_key(3)])
+        candidates = policy.get_eviction_candidates(2)
+        assert len(candidates) == 2
+        assert ObjectKey.Bytes2IntHash(candidates[0].chunk_hash) == 3
+        assert ObjectKey.Bytes2IntHash(candidates[1].chunk_hash) == 2
+
+    def test_get_candidates_respects_count_limit(self):
+        """Candidates should be limited by count parameter."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(i) for i in range(10)])
+        candidates = policy.get_eviction_candidates(3)
+        assert len(candidates) == 3
+
+    def test_get_candidates_returns_all_if_count_exceeds_tracked(self):
+        """If count exceeds tracked keys, return all keys."""
+        policy = LRUEvictionPolicy()
+        policy.on_keys_created([make_key(1), make_key(2)])
+        candidates = policy.get_eviction_candidates(10)
+        assert len(candidates) == 2
+
+
+# =============================================================================
+# Key Eligible Filter Tests
+# =============================================================================
+
+
+class TestLRUEvictionPolicyKeyEligibleFilter:
+    """Tests for key_eligible_filter parameter in get_eviction_actions."""
+
+    def test_key_eligible_filter_skips_filtered_keys(self):
+        """Keys that fail the filter should be skipped during eviction."""
+        policy = LRUEvictionPolicy()
+        keys = [make_key(i) for i in range(5)]
+        policy.on_keys_created(keys)
+
+        # Filter out keys with even chunk_hash
+        def key_eligible_filter(key: ObjectKey) -> bool:
+            return ObjectKey.Bytes2IntHash(key.chunk_hash) % 2 != 0
+
+        actions = policy.get_eviction_actions(
+            1.0, key_eligible_filter=key_eligible_filter
+        )
+        assert len(actions) == 1
+        evicted_hashes = {
+            ObjectKey.Bytes2IntHash(k.chunk_hash) for k in actions[0].keys
+        }
+        # Only odd keys should be evicted: 1, 3
+        assert evicted_hashes == {1, 3}
+
+    def test_key_eligible_filter_none_evicts_all(self):
+        """When key_eligible_filter is None, all keys should be eligible."""
+        policy = LRUEvictionPolicy()
+        keys = [make_key(i) for i in range(5)]
+        policy.on_keys_created(keys)
+
+        actions = policy.get_eviction_actions(1.0, key_eligible_filter=None)
+        assert len(actions) == 1
+        assert len(actions[0].keys) == 5
+
+    def test_key_eligible_filter_rejects_all_returns_empty(self):
+        """When filter rejects all keys, no eviction actions should be returned."""
+        policy = LRUEvictionPolicy()
+        keys = [make_key(i) for i in range(5)]
+        policy.on_keys_created(keys)
+
+        actions = policy.get_eviction_actions(1.0, key_eligible_filter=lambda _: False)
+        assert actions == []
+
+    def test_key_eligible_filter_respects_target_count(self):
+        """Filter should stop collecting once target_count is reached."""
+        policy = LRUEvictionPolicy()
+        # Create 10 keys, all pass filter
+        keys = [make_key(i) for i in range(10)]
+        policy.on_keys_created(keys)
+
+        # Request 50% eviction with a filter that accepts all
+        actions = policy.get_eviction_actions(0.5, key_eligible_filter=lambda _: True)
+        assert len(actions) == 1
+        assert len(actions[0].keys) == 5
+
+    def test_key_eligible_filter_with_partial_acceptance(self):
+        """When filter accepts some keys, only accepted keys up to
+        target_count should be evicted."""
+        policy = LRUEvictionPolicy()
+        # Create 10 keys: 0..9
+        keys = [make_key(i) for i in range(10)]
+        policy.on_keys_created(keys)
+
+        # Filter: only accept keys with hash >= 5
+        def key_eligible_filter(key: ObjectKey) -> bool:
+            return ObjectKey.Bytes2IntHash(key.chunk_hash) >= 5
+
+        # Request 100% eviction -> target_count = 10, but only 5 pass filter
+        actions = policy.get_eviction_actions(
+            1.0, key_eligible_filter=key_eligible_filter
+        )
+        assert len(actions) == 1
+        assert len(actions[0].keys) == 5
+        for k in actions[0].keys:
+            assert ObjectKey.Bytes2IntHash(k.chunk_hash) >= 5
+
+    def test_key_eligible_filter_preserves_lru_order(self):
+        """Filtered eviction should still respect LRU order."""
+        policy = LRUEvictionPolicy()
+        # Create keys in order: 1, 2, 3, 4, 5
+        for i in range(1, 6):
+            policy.on_keys_created([make_key(i)])
+
+        # Touch key 1 to make it most recently used
+        policy.on_keys_touched([make_key(1)])
+
+        # Filter: accept all keys
+        actions = policy.get_eviction_actions(0.6, key_eligible_filter=lambda _: True)
+        assert len(actions) == 1
+        evicted_hashes = [
+            ObjectKey.Bytes2IntHash(k.chunk_hash) for k in actions[0].keys
+        ]
+        # LRU order after touch: 2, 3, 4, 5, 1
+        # 60% of 5 = 3 keys, should be 2, 3, 4
+        assert evicted_hashes == [2, 3, 4]
+
+    def test_key_eligible_filter_skips_locked_simulated(self):
+        """Simulate the real use case: filter skips 'locked' keys."""
+        policy = LRUEvictionPolicy()
+        keys = [make_key(i) for i in range(1, 6)]
+        policy.on_keys_created(keys)
+
+        # Simulate: keys 1 and 3 are "locked" (not evictable)
+        locked_hashes = {1, 3}
+
+        def key_eligible_filter(key: ObjectKey) -> bool:
+            return ObjectKey.Bytes2IntHash(key.chunk_hash) not in locked_hashes
+
+        # Request 100% eviction
+        actions = policy.get_eviction_actions(
+            1.0, key_eligible_filter=key_eligible_filter
+        )
+        assert len(actions) == 1
+        evicted_hashes = {
+            ObjectKey.Bytes2IntHash(k.chunk_hash) for k in actions[0].keys
+        }
+        # Keys 1 and 3 should be skipped
+        assert evicted_hashes == {2, 4, 5}
+
+    def test_key_eligible_filter_with_small_ratio_and_many_filtered(self):
+        """When many keys are filtered, a small ratio should still
+        collect enough eligible keys."""
+        policy = LRUEvictionPolicy()
+        # Create 20 keys: 0..19
+        keys = [make_key(i) for i in range(20)]
+        policy.on_keys_created(keys)
+
+        # Filter: only accept keys with hash divisible by 5
+        # Eligible: 0, 5, 10, 15 (4 keys)
+        def key_eligible_filter(key: ObjectKey) -> bool:
+            return ObjectKey.Bytes2IntHash(key.chunk_hash) % 5 == 0
+
+        # Request 10% eviction -> target_count = 2
+        actions = policy.get_eviction_actions(
+            0.1, key_eligible_filter=key_eligible_filter
+        )
+        assert len(actions) == 1
+        assert len(actions[0].keys) == 2
+        for k in actions[0].keys:
+            assert ObjectKey.Bytes2IntHash(k.chunk_hash) % 5 == 0
diff --git a/tests/v1/distributed/test_mock_l2_adapter.py b/tests/v1/distributed/test_mock_l2_adapter.py
new file mode 100644
index 0000000..1704b56
--- /dev/null
+++ b/tests/v1/distributed/test_mock_l2_adapter.py
@@ -0,0 +1,888 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for MockL2Adapter.
+
+Tests are written based on the L2AdapterInterface contract defined in base.py.
+Tests only use public methods and do not access private fields.
+"""
+
+# Standard
+import select
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2AdapterListener
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+
+class _RecordingListener(L2AdapterListener):
+    """Listener that records all events for inspection in tests."""
+
+    def __init__(self):
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        self.deleted.append(list(keys))
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(size: int = 1024, fill_value: float = 1.0) -> TensorMemoryObj:
+    """Create a test TensorMemoryObj with the given size."""
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    """
+    Wait for an event fd to be signaled.
+
+    Returns True if signaled within timeout, False otherwise.
+    """
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)  # timeout in milliseconds
+    if events:
+        # Read and consume the event
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+@pytest.fixture
+def adapter():
+    """Create a MockL2Adapter with reasonable defaults for testing."""
+    config = MockL2AdapterConfig(
+        max_size_gb=0.001,  # 1 MB
+        mock_bandwidth_gb=10.0,  # 10 GB/s (fast for tests)
+    )
+    adapter = MockL2Adapter(config)
+    yield adapter
+    adapter.close()
+
+
+@pytest.fixture
+def slow_adapter():
+    """Create a MockL2Adapter with slow bandwidth for timing tests."""
+    config = MockL2AdapterConfig(
+        max_size_gb=0.001,  # 1 MB
+        mock_bandwidth_gb=0.0001,  # Very slow bandwidth
+    )
+    adapter = MockL2Adapter(config)
+    yield adapter
+    adapter.close()
+
+
+# =============================================================================
+# Event Fd Interface Tests
+# =============================================================================
+
+
+class TestEventFdInterface:
+    """Test the event fd interface methods."""
+
+    def test_get_store_event_fd_returns_valid_fd(self, adapter):
+        """get_store_event_fd should return a valid file descriptor."""
+        fd = adapter.get_store_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_get_lookup_and_lock_event_fd_returns_valid_fd(self, adapter):
+        """get_lookup_and_lock_event_fd should return a valid file descriptor."""
+        fd = adapter.get_lookup_and_lock_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_get_load_event_fd_returns_valid_fd(self, adapter):
+        """get_load_event_fd should return a valid file descriptor."""
+        fd = adapter.get_load_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_event_fds_are_different(self, adapter):
+        """Each operation should have a distinct event fd."""
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        assert store_fd != lookup_fd
+        assert store_fd != load_fd
+        assert lookup_fd != load_fd
+
+
+# =============================================================================
+# Store Interface Tests
+# =============================================================================
+
+
+class TestStoreInterface:
+    """Test the store operation interface."""
+
+    def test_submit_store_task_returns_task_id(self, adapter):
+        """submit_store_task should return a valid task ID."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+
+        task_id = adapter.submit_store_task([key], [obj])
+
+        assert isinstance(task_id, int)
+
+    def test_submit_store_task_signals_event_fd(self, adapter):
+        """Store completion should signal the store event fd."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+
+        adapter.submit_store_task([key], [obj])
+
+        # Wait for the event fd to be signaled
+        assert wait_for_event_fd(store_fd, timeout=5.0), (
+            "Store event fd was not signaled within timeout"
+        )
+
+    def test_pop_completed_store_tasks_returns_completed(self, adapter):
+        """pop_completed_store_tasks should return completed tasks
+        with success status.
+        """
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+
+        task_id = adapter.submit_store_task([key], [obj])
+
+        # Wait for completion
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed = adapter.pop_completed_store_tasks()
+
+        assert task_id in completed
+        assert completed[task_id].is_successful()  # Should be successful
+
+    def test_pop_completed_store_tasks_clears_completed(self, adapter):
+        """pop_completed_store_tasks should clear the completed tasks."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+
+        # First pop should return the task
+        completed1 = adapter.pop_completed_store_tasks()
+        assert len(completed1) == 1
+
+        # Second pop should return empty
+        completed2 = adapter.pop_completed_store_tasks()
+        assert len(completed2) == 0
+
+    def test_submit_multiple_store_tasks(self, adapter):
+        """Multiple store tasks should each get unique task IDs."""
+        keys = [create_object_key(i) for i in range(3)]
+        objs = [create_memory_obj(fill_value=float(i)) for i in range(3)]
+        store_fd = adapter.get_store_event_fd()
+
+        task_ids = []
+        for key, obj in zip(keys, objs, strict=False):
+            task_id = adapter.submit_store_task([key], [obj])
+            task_ids.append(task_id)
+
+        # All task IDs should be unique
+        assert len(set(task_ids)) == 3
+
+        # Wait for all completions
+        completed = {}
+        while len(completed) < 3:
+            wait_for_event_fd(store_fd, timeout=5.0)
+            completed.update(adapter.pop_completed_store_tasks())
+
+        # All tasks should be completed
+        for task_id in task_ids:
+            assert task_id in completed
+            assert completed[task_id].is_successful()
+
+    def test_store_batch_of_objects(self, adapter):
+        """A single store task can store multiple key-object pairs."""
+        keys = [create_object_key(i) for i in range(5)]
+        objs = [create_memory_obj(fill_value=float(i)) for i in range(5)]
+        store_fd = adapter.get_store_event_fd()
+
+        task_id = adapter.submit_store_task(keys, objs)
+
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed = adapter.pop_completed_store_tasks()
+        assert task_id in completed
+        assert completed[task_id].is_successful()
+
+
+# =============================================================================
+# Lookup and Lock Interface Tests
+# =============================================================================
+
+
+class TestLookupAndLockInterface:
+    """Test the lookup and lock operation interface."""
+
+    def test_submit_lookup_returns_task_id(self, adapter):
+        """submit_lookup_and_lock_task should return a valid task ID."""
+        key = create_object_key(1)
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+
+        assert isinstance(task_id, int)
+
+    def test_lookup_signals_event_fd(self, adapter):
+        """Lookup completion should signal the lookup event fd."""
+        key = create_object_key(1)
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+
+        assert wait_for_event_fd(lookup_fd, timeout=5.0), (
+            "Lookup event fd was not signaled within timeout"
+        )
+
+    def test_lookup_nonexistent_key_returns_bitmap_with_zeros(self, adapter):
+        """Looking up a non-existent key should return a bitmap with 0."""
+        key = create_object_key(999)  # Never stored
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is False  # Key not found
+
+    def test_lookup_existing_key_returns_bitmap_with_ones(self, adapter):
+        """Looking up an existing key should return a bitmap with 1."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # First store the object
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Now lookup
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is True  # Key found
+
+    def test_lookup_mixed_keys(self, adapter):
+        """Lookup of mixed existing/non-existing keys returns correct bitmap."""
+        existing_key = create_object_key(1)
+        nonexistent_key = create_object_key(999)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # Store only one key
+        adapter.submit_store_task([existing_key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Lookup both keys
+        task_id = adapter.submit_lookup_and_lock_task(
+            [existing_key, nonexistent_key], _EMPTY_LAYOUT
+        )
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is True  # existing_key found
+        assert bitmap.test(1) is False  # nonexistent_key not found
+
+    def test_query_lookup_result_returns_none_for_unknown_task(self, adapter):
+        """Querying an unknown task ID should return None."""
+        result = adapter.query_lookup_and_lock_result(99999)
+        assert result is None
+
+    def test_query_lookup_result_clears_result(self, adapter):
+        """Querying lookup result should remove it (can only query once)."""
+        key = create_object_key(1)
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        # First query returns result
+        result1 = adapter.query_lookup_and_lock_result(task_id)
+        assert result1 is not None
+
+        # Second query returns None
+        result2 = adapter.query_lookup_and_lock_result(task_id)
+        assert result2 is None
+
+
+# =============================================================================
+# Unlock Interface Tests
+# =============================================================================
+
+
+class TestUnlockInterface:
+    """Test the unlock operation interface."""
+
+    def test_submit_unlock_does_not_raise(self, adapter):
+        """submit_unlock should not raise an exception."""
+        key = create_object_key(1)
+
+        # Should not raise even for non-existent key
+        adapter.submit_unlock([key])
+
+    def test_unlock_after_lock(self, adapter):
+        """Unlocking after locking should work without error."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # Store
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Lookup and lock
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+        adapter.query_lookup_and_lock_result(task_id)
+
+        # Unlock should not raise
+        adapter.submit_unlock([key])
+
+
+# =============================================================================
+# Load Interface Tests
+# =============================================================================
+
+
+class TestLoadInterface:
+    """Test the load operation interface."""
+
+    def test_submit_load_task_returns_task_id(self, adapter):
+        """submit_load_task should return a valid task ID."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+
+        task_id = adapter.submit_load_task([key], [obj])
+
+        assert isinstance(task_id, int)
+
+    def test_load_signals_event_fd(self, adapter):
+        """Load completion should signal the load event fd."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        load_fd = adapter.get_load_event_fd()
+
+        adapter.submit_load_task([key], [obj])
+
+        assert wait_for_event_fd(load_fd, timeout=5.0), (
+            "Load event fd was not signaled within timeout"
+        )
+
+    def test_load_nonexistent_key_returns_bitmap_with_zeros(self, adapter):
+        """Loading a non-existent key should return a bitmap with 0."""
+        key = create_object_key(999)  # Never stored
+        obj = create_memory_obj()
+        load_fd = adapter.get_load_event_fd()
+
+        task_id = adapter.submit_load_task([key], [obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        bitmap = adapter.query_load_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is False  # Load failed
+
+    def test_load_existing_key_copies_data(self, adapter):
+        """Loading an existing key should copy data to the provided buffer."""
+        key = create_object_key(1)
+        store_obj = create_memory_obj(size=100, fill_value=42.0)
+        load_obj = create_memory_obj(size=100, fill_value=0.0)
+        store_fd = adapter.get_store_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store
+        adapter.submit_store_task([key], [store_obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Load
+        task_id = adapter.submit_load_task([key], [load_obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        bitmap = adapter.query_load_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is True  # Load succeeded
+
+        # Data should be copied
+        assert torch.all(load_obj.tensor == 42.0)
+
+    def test_query_load_result_returns_none_for_unknown_task(self, adapter):
+        """Querying an unknown task ID should return None."""
+        result = adapter.query_load_result(99999)
+        assert result is None
+
+    def test_query_load_result_clears_result(self, adapter):
+        """Querying load result should remove it (can only query once)."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        load_fd = adapter.get_load_event_fd()
+
+        task_id = adapter.submit_load_task([key], [obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        # First query returns result
+        result1 = adapter.query_load_result(task_id)
+        assert result1 is not None
+
+        # Second query returns None
+        result2 = adapter.query_load_result(task_id)
+        assert result2 is None
+
+
+# =============================================================================
+# End-to-End Workflow Tests
+# =============================================================================
+
+
+class TestEndToEndWorkflow:
+    """Test complete store-lookup-load workflows."""
+
+    def test_store_lookup_load_workflow(self, adapter):
+        """Test the complete workflow: store -> lookup -> load."""
+        key = create_object_key(1)
+        store_obj = create_memory_obj(size=256, fill_value=123.0)
+        load_obj = create_memory_obj(size=256, fill_value=0.0)
+
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Step 1: Store
+        store_task_id = adapter.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        completed = adapter.pop_completed_store_tasks()
+        assert completed[store_task_id].is_successful()
+
+        # Step 2: Lookup and lock
+        lookup_task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_task_id)
+        assert lookup_bitmap.test(0) is True
+
+        # Step 3: Load
+        load_task_id = adapter.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        load_bitmap = adapter.query_load_result(load_task_id)
+        assert load_bitmap.test(0) is True
+
+        # Verify data
+        assert torch.all(load_obj.tensor == 123.0)
+
+        # Step 4: Unlock
+        adapter.submit_unlock([key])
+
+    def test_multiple_objects_workflow(self, adapter):
+        """Test workflow with multiple objects."""
+        num_objects = 5
+        keys = [create_object_key(i) for i in range(num_objects)]
+        store_objs = [
+            create_memory_obj(size=64, fill_value=float(i * 10))
+            for i in range(num_objects)
+        ]
+        load_objs = [
+            create_memory_obj(size=64, fill_value=0.0) for _ in range(num_objects)
+        ]
+
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store all
+        store_task_id = adapter.submit_store_task(keys, store_objs)
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        completed = adapter.pop_completed_store_tasks()
+        assert completed[store_task_id].is_successful()
+
+        # Lookup all
+        lookup_task_id = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_task_id)
+        for i in range(num_objects):
+            assert lookup_bitmap.test(i) is True
+
+        # Load all
+        load_task_id = adapter.submit_load_task(keys, load_objs)
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        load_bitmap = adapter.query_load_result(load_task_id)
+        for i in range(num_objects):
+            assert load_bitmap.test(i) is True
+            assert torch.all(load_objs[i].tensor == float(i * 10))
+
+
+# =============================================================================
+# Close Interface Tests
+# =============================================================================
+
+
+class TestCloseInterface:
+    """Test the close operation."""
+
+    def test_close_does_not_raise(self):
+        """close() should not raise an exception."""
+        config = MockL2AdapterConfig(max_size_gb=0.001, mock_bandwidth_gb=10.0)
+        adapter = MockL2Adapter(config)
+
+        # Should not raise
+        adapter.close()
+
+    def test_close_after_operations(self):
+        """close() should work after store/lookup/load operations."""
+        config = MockL2AdapterConfig(max_size_gb=0.001, mock_bandwidth_gb=10.0)
+        adapter = MockL2Adapter(config)
+
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Should not raise
+        adapter.close()
+
+
+# =============================================================================
+# Bandwidth Simulation Tests
+# =============================================================================
+
+
+class TestBandwidthSimulation:
+    """Test that bandwidth simulation affects completion timing."""
+
+    def test_store_completion_is_delayed_by_bandwidth(self, slow_adapter):
+        """Store completion should be delayed based on object size and bandwidth."""
+        key = create_object_key(1)
+        # Create a larger object to see noticeable delay
+        obj = create_memory_obj(size=10000)  # ~40KB
+        store_fd = slow_adapter.get_store_event_fd()
+
+        start_time = time.time()
+        slow_adapter.submit_store_task([key], [obj])
+
+        # Should take some time due to bandwidth simulation
+        assert wait_for_event_fd(store_fd, timeout=60.0)
+        elapsed = time.time() - start_time
+
+        # With very slow bandwidth, should take noticeable time
+        # (exact time depends on bandwidth config)
+        assert elapsed > 0.1  # At least some delay
+
+    def test_fast_bandwidth_completes_quickly(self, adapter):
+        """With fast bandwidth, completion should be quick."""
+        key = create_object_key(1)
+        obj = create_memory_obj(size=1000)
+        store_fd = adapter.get_store_event_fd()
+
+        start_time = time.time()
+        adapter.submit_store_task([key], [obj])
+
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        elapsed = time.time() - start_time
+
+        # With fast bandwidth, should complete quickly
+        assert elapsed < 1.0
+
+
+# =============================================================================
+# Eviction Interface Tests
+# =============================================================================
+
+
+def _store_and_wait(adapter, key, obj):
+    """Helper: store one key and wait for the store event fd to fire."""
+    store_fd = adapter.get_store_event_fd()
+    adapter.submit_store_task([key], [obj])
+    assert wait_for_event_fd(store_fd, timeout=5.0), "store timed out"
+    adapter.pop_completed_store_tasks()
+
+
+class TestEvictionInterface:
+    """Tests for delete(), get_usage(), and listener notifications."""
+
+    def test_delete_removes_key(self, adapter):
+        """delete() should make the key invisible to subsequent lookups."""
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        _store_and_wait(adapter, key, obj)
+
+        adapter.delete([key])
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap.test(0) is False
+
+    def test_delete_nonexistent_key_does_not_raise(self, adapter):
+        """delete() on a key that was never stored should not raise."""
+        adapter.delete([create_object_key(999)])
+
+    def test_delete_multiple_keys(self, adapter):
+        """delete() on a batch of keys removes all of them."""
+        keys = [create_object_key(i) for i in range(3)]
+        objs = [create_memory_obj() for _ in range(3)]
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        adapter.submit_store_task(keys, objs)
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        adapter.delete(keys)
+
+        task_id = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        for i in range(len(keys)):
+            assert bitmap.test(i) is False
+
+    def test_get_usage_empty_adapter_is_zero(self, adapter):
+        """get_usage() on a fresh adapter should report 0 bytes."""
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 0
+        assert usage.usage_fraction == 0.0
+        assert usage.bytes_by_cache_salt == {}
+
+    def test_get_usage_increases_after_store(self, adapter):
+        """get_usage() should report positive bytes after a store."""
+        key = create_object_key(1)
+        obj = create_memory_obj(size=1024)
+        _store_and_wait(adapter, key, obj)
+
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used > 0
+        assert 0.0 < usage.usage_fraction <= 1.0
+
+    def test_get_usage_decreases_after_delete(self, adapter):
+        """get_usage() should drop back to 0 after deleting the only stored key."""
+        key = create_object_key(1)
+        obj = create_memory_obj(size=1024)
+        _store_and_wait(adapter, key, obj)
+
+        assert adapter.get_usage().total_bytes_used > 0
+
+        adapter.delete([key])
+
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 0
+        assert usage.usage_fraction == 0.0
+
+    def test_bytes_by_cache_salt_populated_from_cache_salt(self, adapter):
+        """End-to-end: storing keys with different ``cache_salt`` values
+        should drive the byte buckets in ``AdapterUsage`` — proves the
+        salt actually flows through the real adapter into the base-class
+        accounting (not just verified by the stub tests)."""
+        # Two keys per cache_salt so we know the totals are summed, not
+        # just per-key-overwritten.
+        alice_keys = [
+            ObjectKey(
+                chunk_hash=ObjectKey.IntHash2Bytes(i),
+                model_name="m",
+                kv_rank=0,
+                cache_salt="alice",
+            )
+            for i in (1, 2)
+        ]
+        bob_key = ObjectKey(
+            chunk_hash=ObjectKey.IntHash2Bytes(3),
+            model_name="m",
+            kv_rank=0,
+            cache_salt="bob",
+        )
+        obj = create_memory_obj(size=128)  # 128 floats * 4 bytes = 512 B
+        for k in alice_keys + [bob_key]:
+            _store_and_wait(adapter, k, obj)
+
+        usage = adapter.get_usage()
+        assert usage.bytes_by_cache_salt == {"alice": 1024, "bob": 512}
+        assert usage.total_bytes_used == 1536
+
+        # Deleting one of alice's keys should shrink alice's bucket but
+        # leave bob's untouched.
+        adapter.delete([alice_keys[0]])
+        usage = adapter.get_usage()
+        assert usage.bytes_by_cache_salt == {"alice": 512, "bob": 512}
+        assert usage.total_bytes_used == 1024
+
+        # Deleting alice's last key should drop the bucket entirely so
+        # the snapshot stays compact.
+        adapter.delete([alice_keys[1]])
+        usage = adapter.get_usage()
+        assert "alice" not in usage.bytes_by_cache_salt
+        assert usage.bytes_by_cache_salt == {"bob": 512}
+
+    def test_listener_notified_on_store(self, adapter):
+        """Listener.on_l2_keys_stored should be called after a store completes."""
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        _store_and_wait(adapter, key, obj)
+
+        assert len(listener.stored) == 1
+        assert key in listener.stored[0]
+        assert listener.deleted == []
+
+    def test_listener_notified_on_delete(self, adapter):
+        """Listener.on_l2_keys_deleted should be called after delete()."""
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        _store_and_wait(adapter, key, obj)
+        adapter.delete([key])
+
+        assert len(listener.deleted) == 1
+        assert key in listener.deleted[0]
+
+    def test_listener_delete_skips_missing_keys(self, adapter):
+        """on_l2_keys_deleted should only include keys that were actually removed."""
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        real_key = create_object_key(1)
+        missing_key = create_object_key(999)
+        obj = create_memory_obj()
+        _store_and_wait(adapter, real_key, obj)
+
+        adapter.delete([real_key, missing_key])
+
+        assert len(listener.deleted) == 1
+        notified = listener.deleted[0]
+        assert real_key in notified
+        assert missing_key not in notified
+
+    def test_listener_notified_on_load(self, adapter):
+        """Listener.on_l2_keys_accessed should be called after a load completes."""
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        key = create_object_key(1)
+        store_obj = create_memory_obj(size=100, fill_value=42.0)
+        load_obj = create_memory_obj(size=100, fill_value=0.0)
+        store_fd = adapter.get_store_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store
+        adapter.submit_store_task([key], [store_obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Load
+        adapter.submit_load_task([key], [load_obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        assert len(listener.accessed) == 1
+        assert key in listener.accessed[0]
+
+    def test_listener_load_skips_missing_keys(self, adapter):
+        """on_l2_keys_accessed should only include keys that were actually loaded."""
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        real_key = create_object_key(1)
+        missing_key = create_object_key(999)
+        store_obj = create_memory_obj(size=100, fill_value=42.0)
+        load_obj1 = create_memory_obj(size=100, fill_value=0.0)
+        load_obj2 = create_memory_obj(size=100, fill_value=0.0)
+        store_fd = adapter.get_store_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store only real_key
+        adapter.submit_store_task([real_key], [store_obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Load both keys
+        adapter.submit_load_task([real_key, missing_key], [load_obj1, load_obj2])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        assert len(listener.accessed) == 1
+        assert real_key in listener.accessed[0]
+        assert missing_key not in listener.accessed[0]
+
+    def test_multiple_listeners_all_notified(self, adapter):
+        """All registered listeners should receive the same store event."""
+        l1, l2 = _RecordingListener(), _RecordingListener()
+        adapter.register_listener(l1)
+        adapter.register_listener(l2)
+
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        _store_and_wait(adapter, key, obj)
+
+        assert len(l1.stored) == 1
+        assert len(l2.stored) == 1
diff --git a/tests/v1/distributed/test_mooncake_store_l2_adapter.py b/tests/v1/distributed/test_mooncake_store_l2_adapter.py
new file mode 100644
index 0000000..1c96e00
--- /dev/null
+++ b/tests/v1/distributed/test_mooncake_store_l2_adapter.py
@@ -0,0 +1,991 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for MooncakeStoreL2AdapterConfig and factory registration.
+
+Integration tests require the C++ Mooncake extension and a running
+Mooncake Store service.  They are skipped automatically when the
+extension is not available.
+"""
+
+# Standard
+from typing import Any, cast
+import os
+import select
+import sys
+import types
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.l2_adapters import (
+    mooncake_store_l2_adapter as mooncake_store_module,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    get_registered_l2_adapter_types,
+    get_type_name_for_config,
+)
+from lmcache.v1.distributed.l2_adapters.factory import (
+    create_l2_adapter_from_registry,
+)
+from lmcache.v1.distributed.l2_adapters.mooncake_store_l2_adapter import (
+    MooncakeStoreL2AdapterConfig,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def _native_mooncake_available() -> bool:
+    """Check if the C++ Mooncake extension can be imported."""
+    try:
+        # First Party
+        from lmcache.lmcache_mooncake import LMCacheMooncakeClient  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+requires_mooncake = pytest.mark.skipif(
+    not _native_mooncake_available(),
+    reason="C++ Mooncake extension (lmcache_mooncake) not available",
+)
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(size: int = 256, fill_value: float = 1.0) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def create_buffer_memory_obj(
+    buffer: torch.Tensor,
+    offset_bytes: int,
+    size_bytes: int,
+    fill_value: float = 1.0,
+) -> TensorMemoryObj:
+    """Create a tensor-backed memory object from a slice of a buffer.
+
+    Args:
+        buffer: Backing tensor containing the bytes to expose.
+        offset_bytes: Byte offset where the memory object starts in ``buffer``.
+        size_bytes: Size of the memory object in bytes.
+        fill_value: Value used to initialize the exposed float32 view.
+
+    Returns:
+        A ``TensorMemoryObj`` describing the requested buffer slice.
+    """
+    raw_data = buffer[offset_bytes : offset_bytes + size_bytes].view(torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size_bytes // 4]),
+        dtype=torch.float32,
+        address=offset_bytes,
+        phy_size=size_bytes,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 10.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+# =============================================================================
+# Config Unit Tests (no C++ extension needed)
+# =============================================================================
+
+
+class TestMooncakeStoreL2AdapterConfig:
+    """Unit tests for MooncakeStoreL2AdapterConfig."""
+
+    def test_from_dict_minimal(self):
+        """Minimal dict with only mooncake keys should work."""
+        d = {
+            "type": "mooncake_store",
+            "local_hostname": "192.168.1.1",
+            "metadata_server": "etcd://localhost:2379",
+            "global_segment_size": "3221225472",
+            "local_buffer_size": "1073741824",
+            "protocol": "tcp",
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+
+        # LMCache-only keys should be stripped
+        assert "type" not in config.setup_config
+
+        # Mooncake keys should be forwarded as strings
+        assert config.setup_config["local_hostname"] == "192.168.1.1"
+        assert config.setup_config["metadata_server"] == "etcd://localhost:2379"
+        assert config.setup_config["protocol"] == "tcp"
+
+        # Default num_workers
+        assert config.num_workers == 4
+
+    def test_from_dict_with_num_workers(self):
+        """num_workers should be parsed and excluded from setup_config."""
+        d = {
+            "type": "mooncake_store",
+            "num_workers": 8,
+            "local_hostname": "10.0.0.1",
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+
+        assert config.num_workers == 8
+        assert "num_workers" not in config.setup_config
+        assert config.setup_config["local_hostname"] == "10.0.0.1"
+
+    def test_from_dict_with_per_op_workers(self):
+        """Per-operation worker counts should be parsed as a dict
+        and excluded from setup_config."""
+        d = {
+            "type": "mooncake_store",
+            "num_workers": 16,
+            "per_op_workers": {
+                "lookup": 4,
+                "retrieve": 16,
+                "store": 4,
+            },
+            "local_hostname": "10.0.0.1",
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+
+        assert config.per_op_workers == {"lookup": 4, "retrieve": 16, "store": 4}
+        assert "per_op_workers" not in config.setup_config
+        assert config.setup_config["local_hostname"] == "10.0.0.1"
+
+    def test_from_dict_forwards_boolean_mooncake_keys_as_strings(self):
+        """Non-LMCache boolean keys should be forwarded as strings."""
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": "127.0.0.1",
+                "mooncake_prefer_local_alloc": True,
+            }
+        )
+
+        assert config.setup_config["mooncake_prefer_local_alloc"] == "True"
+
+    def test_from_dict_forwards_unknown_keys(self):
+        """Unknown keys should be forwarded to mooncake unchanged."""
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "experimental_key": "enabled",
+            }
+        )
+
+        assert config.setup_config["experimental_key"] == "enabled"
+
+    def test_from_dict_strips_lmcache_only_keys(self):
+        """LMCache-only keys should
+        not appear in setup_config."""
+        d = {
+            "type": "mooncake_store",
+            "num_workers": 2,
+            "eviction": "lru",
+            "per_op_workers": {
+                "lookup": 3,
+                "retrieve": 5,
+                "store": 2,
+            },
+            "local_hostname": "host1",
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+
+        assert "type" not in config.setup_config
+        assert "num_workers" not in config.setup_config
+        assert "eviction" not in config.setup_config
+        assert "per_op_workers" not in config.setup_config
+        assert config.setup_config["local_hostname"] == "host1"
+
+    def test_from_dict_converts_values_to_str(self):
+        """Non-string values should be converted to strings."""
+        d = {
+            "type": "mooncake_store",
+            "global_segment_size": 3221225472,
+            "local_buffer_size": 1073741824,
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+
+        assert config.setup_config["global_segment_size"] == "3221225472"
+        assert config.setup_config["local_buffer_size"] == "1073741824"
+
+    def test_from_dict_skips_none_values(self):
+        """Keys with None values should be excluded from setup_config."""
+        d = {
+            "type": "mooncake_store",
+            "local_hostname": "host1",
+            "optional_key": None,
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+
+        assert "optional_key" not in config.setup_config
+        assert config.setup_config["local_hostname"] == "host1"
+
+    def test_from_dict_invalid_num_workers_zero(self):
+        """num_workers=0 should raise ValueError."""
+        d = {"type": "mooncake_store", "num_workers": 0}
+        with pytest.raises(ValueError, match="num_workers"):
+            MooncakeStoreL2AdapterConfig.from_dict(d)
+
+    def test_from_dict_invalid_num_workers_negative(self):
+        """Negative num_workers should raise ValueError."""
+        d = {"type": "mooncake_store", "num_workers": -1}
+        with pytest.raises(ValueError, match="num_workers"):
+            MooncakeStoreL2AdapterConfig.from_dict(d)
+
+    def test_from_dict_invalid_num_workers_string(self):
+        """Non-integer num_workers should raise ValueError."""
+        d = {"type": "mooncake_store", "num_workers": "four"}
+        with pytest.raises(ValueError, match="num_workers"):
+            MooncakeStoreL2AdapterConfig.from_dict(d)
+
+    @pytest.mark.parametrize("value", [0, -1, "four"])
+    def test_from_dict_invalid_per_op_workers(self, value: Any):
+        """Invalid per_op_workers values should raise ValueError."""
+        d: dict[str, object] = {
+            "type": "mooncake_store",
+            "per_op_workers": {
+                "lookup": 2,
+                "retrieve": value,
+                "store": 2,
+            },
+        }
+        with pytest.raises(ValueError, match="per_op_workers"):
+            MooncakeStoreL2AdapterConfig.from_dict(d)
+
+    def test_from_dict_partial_per_op_workers(self):
+        """Partial per_op_workers is valid — unmentioned keys use shared pool."""
+        d = {
+            "type": "mooncake_store",
+            "per_op_workers": {
+                "lookup": 4,
+                "retrieve": 16,
+            },
+            "local_hostname": "10.0.0.1",
+        }
+        config = MooncakeStoreL2AdapterConfig.from_dict(d)
+        assert config.per_op_workers == {"lookup": 4, "retrieve": 16}
+        assert "store" not in config.per_op_workers
+
+    def test_constructor_copies_setup_config(self):
+        """Constructor should copy the setup_config dict."""
+        original = {"key": "value"}
+        config = MooncakeStoreL2AdapterConfig(setup_config=original)
+
+        # Mutating the original should not affect the config
+        original["key"] = "changed"
+        assert config.setup_config["key"] == "value"
+
+    def test_help_returns_string(self):
+        """help() should return a non-empty string."""
+        h = MooncakeStoreL2AdapterConfig.help()
+        assert isinstance(h, str)
+        assert len(h) > 0
+
+
+# =============================================================================
+# Factory Registration Tests (no C++ extension needed)
+# =============================================================================
+
+
+class TestMooncakeStoreRegistration:
+    """Tests for factory and config type registration."""
+
+    def test_mooncake_store_type_registered(self):
+        """'mooncake_store' should be in the registered adapter types."""
+        assert "mooncake_store" in get_registered_l2_adapter_types()
+
+    def test_config_type_name(self):
+        """get_type_name_for_config should return 'mooncake_store'."""
+        config = MooncakeStoreL2AdapterConfig(setup_config={})
+        name = get_type_name_for_config(config)
+        assert name == "mooncake_store"
+
+    def test_factory_raises_without_extension(self):
+        """Factory should raise RuntimeError when C++ extension
+        is not available."""
+        if _native_mooncake_available():
+            pytest.skip("C++ Mooncake extension is available")
+
+        config = MooncakeStoreL2AdapterConfig(
+            setup_config={"local_hostname": "localhost"},
+            num_workers=2,
+        )
+        with pytest.raises(RuntimeError, match="Mooncake"):
+            create_l2_adapter_from_registry(config)
+
+
+def _install_fake_mooncake_extension(
+    monkeypatch: pytest.MonkeyPatch,
+    client_cls: type,
+) -> None:
+    """Install a fake lmcache_mooncake module for factory unit tests."""
+
+    class FakeL1RegistrationConfig:
+        def __init__(self):
+            self.enabled = False
+            self.base = 0
+            self.size = 0
+
+    fake_module = types.ModuleType("lmcache.lmcache_mooncake")
+    fake_module_any = cast(Any, fake_module)
+    fake_module_any.L1RegistrationConfig = FakeL1RegistrationConfig
+    fake_module_any.LMCacheMooncakeClient = client_cls
+    monkeypatch.setitem(sys.modules, "lmcache.lmcache_mooncake", fake_module)
+
+
+class TestMooncakeStoreL1RegistrationFactory:
+    """Tests for Mooncake TCP/RDMA L1 registration factory behavior.
+
+    RDMA creation must receive a valid L1 memory descriptor; TCP creation
+    must not enable preregistration even if a descriptor is provided.
+    Uses a fake native extension so these tests do not require Mooncake.
+    """
+
+    def test_factory_passes_disabled_l1_registration_for_tcp(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import native_connector_l2_adapter
+
+        captured: dict[str, Any] = {}
+
+        class FakeClient:
+            def __init__(
+                self,
+                config: dict[str, str],
+                num_workers: int,
+                l1_registration,
+                per_op_workers=None,
+            ):
+                captured["config"] = config
+                captured["num_workers"] = num_workers
+                captured["l1_registration"] = l1_registration
+                captured["per_op_workers"] = per_op_workers
+
+        _install_fake_mooncake_extension(monkeypatch, FakeClient)
+        monkeypatch.setattr(
+            native_connector_l2_adapter,
+            "NativeConnectorL2Adapter",
+            lambda client: ("wrapped", client),
+        )
+
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": "127.0.0.1",
+                "metadata_server": "P2PHANDSHAKE",
+                "num_workers": 3,
+                "protocol": "tcp",
+            }
+        )
+        l1_desc = L1MemoryDesc(ptr=123456, size=65536, align_bytes=4096)
+
+        adapter = mooncake_store_module._create_mooncake_store_l2_adapter(
+            config,
+            l1_memory_desc=l1_desc,
+        )
+        wrapped_adapter: Any = adapter
+
+        assert wrapped_adapter[0] == "wrapped"
+        assert captured["config"] == config.setup_config
+        assert captured["num_workers"] == 3
+        registration = captured["l1_registration"]
+        assert registration.enabled is False
+        assert registration.base == 0
+        assert registration.size == 0
+
+    def test_factory_passes_enabled_l1_registration_for_rdma(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import native_connector_l2_adapter
+
+        captured: dict[str, Any] = {}
+
+        class FakeClient:
+            def __init__(
+                self,
+                config: dict[str, str],
+                num_workers: int,
+                l1_registration,
+                per_op_workers=None,
+            ):
+                captured["config"] = config
+                captured["num_workers"] = num_workers
+                captured["l1_registration"] = l1_registration
+                captured["per_op_workers"] = per_op_workers
+
+        _install_fake_mooncake_extension(monkeypatch, FakeClient)
+        monkeypatch.setattr(
+            native_connector_l2_adapter,
+            "NativeConnectorL2Adapter",
+            lambda client: ("wrapped", client),
+        )
+
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": "127.0.0.1",
+                "metadata_server": "P2PHANDSHAKE",
+                "num_workers": 2,
+                "protocol": "rdma",
+            }
+        )
+        l1_desc = L1MemoryDesc(ptr=123456, size=65536, align_bytes=4096)
+
+        adapter = mooncake_store_module._create_mooncake_store_l2_adapter(
+            config,
+            l1_memory_desc=l1_desc,
+        )
+        wrapped_adapter: Any = adapter
+
+        assert wrapped_adapter[0] == "wrapped"
+        assert captured["config"] == config.setup_config
+        assert captured["num_workers"] == 2
+        registration = captured["l1_registration"]
+        assert registration.enabled is True
+        assert registration.base == l1_desc.ptr
+        assert registration.size == l1_desc.size
+
+    def test_factory_passes_per_op_worker_counts(self, monkeypatch: pytest.MonkeyPatch):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import native_connector_l2_adapter
+
+        captured: dict[str, Any] = {}
+
+        class FakeClient:
+            def __init__(
+                self,
+                config: dict[str, str],
+                num_workers: int,
+                l1_registration,
+                per_op_workers=None,
+            ):
+                captured["config"] = config
+                captured["num_workers"] = num_workers
+                captured["l1_registration"] = l1_registration
+                captured["per_op_workers"] = per_op_workers
+
+        _install_fake_mooncake_extension(monkeypatch, FakeClient)
+        monkeypatch.setattr(
+            native_connector_l2_adapter,
+            "NativeConnectorL2Adapter",
+            lambda client: ("wrapped", client),
+        )
+
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": "127.0.0.1",
+                "num_workers": 16,
+                "per_op_workers": {
+                    "lookup": 4,
+                    "retrieve": 16,
+                    "store": 4,
+                },
+                "protocol": "tcp",
+            }
+        )
+
+        adapter = mooncake_store_module._create_mooncake_store_l2_adapter(config)
+        wrapped_adapter: Any = adapter
+
+        assert wrapped_adapter[0] == "wrapped"
+        assert captured["config"] == config.setup_config
+        assert captured["num_workers"] == 16
+        assert captured["per_op_workers"] == {"lookup": 4, "retrieve": 16, "store": 4}
+
+    def test_factory_requires_l1_memory_descriptor_for_rdma(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        class FakeClient:
+            pass
+
+        _install_fake_mooncake_extension(monkeypatch, FakeClient)
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": "127.0.0.1",
+                "protocol": "rdma",
+            }
+        )
+
+        with pytest.raises(ValueError, match="no L1 memory descriptor"):
+            mooncake_store_module._create_mooncake_store_l2_adapter(config)
+
+    def test_factory_rejects_invalid_l1_memory_descriptor_for_rdma(
+        self, monkeypatch: pytest.MonkeyPatch
+    ):
+        class FakeClient:
+            pass
+
+        _install_fake_mooncake_extension(monkeypatch, FakeClient)
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": "127.0.0.1",
+                "protocol": "rdma",
+            }
+        )
+        invalid_desc = L1MemoryDesc(ptr=0, size=0, align_bytes=4096)
+
+        with pytest.raises(ValueError, match="invalid"):
+            mooncake_store_module._create_mooncake_store_l2_adapter(
+                config,
+                l1_memory_desc=invalid_desc,
+            )
+
+
+# =============================================================================
+# Integration Tests (require C++ Mooncake extension + running service)
+# =============================================================================
+
+# Mooncake service connection params from environment
+MOONCAKE_LOCAL_HOSTNAME = os.environ.get("MOONCAKE_LOCAL_HOSTNAME", "")
+MOONCAKE_METADATA_SERVER = os.environ.get(
+    "MOONCAKE_METADATA_SERVER", "etcd://localhost:2379"
+)
+MOONCAKE_MASTER_SERVER_ADDRESS = os.environ.get(
+    "MOONCAKE_MASTER_SERVER_ADDRESS", "localhost:50051"
+)
+MOONCAKE_DEVICE_NAME = os.environ.get("MOONCAKE_DEVICE_NAME", "")
+MOONCAKE_RUN_RDMA_TESTS = os.environ.get("MOONCAKE_RUN_RDMA_TESTS") == "1"
+
+requires_mooncake_service = pytest.mark.skipif(
+    not _native_mooncake_available() or not MOONCAKE_LOCAL_HOSTNAME,
+    reason=("C++ Mooncake extension not available or MOONCAKE_LOCAL_HOSTNAME not set"),
+)
+requires_mooncake_rdma = pytest.mark.skipif(
+    not MOONCAKE_RUN_RDMA_TESTS,
+    reason="RDMA-specific Mooncake test requires MOONCAKE_RUN_RDMA_TESTS=1",
+)
+
+
+@requires_mooncake_service
+class TestMooncakeStoreIntegration:
+    """Integration tests using real Mooncake Store service.
+
+    These tests require:
+    1. The C++ Mooncake extension (lmcache_mooncake) to be built
+    2. A running Mooncake Store service
+    3. MOONCAKE_LOCAL_HOSTNAME environment variable set
+
+    Set environment variables before running:
+        export MOONCAKE_LOCAL_HOSTNAME=<your-ip>
+        export MOONCAKE_METADATA_SERVER=etcd://<etcd-host>:2379
+    """
+
+    @pytest.fixture(autouse=True)
+    def setup_adapter(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": MOONCAKE_LOCAL_HOSTNAME,
+                "metadata_server": MOONCAKE_METADATA_SERVER,
+                "master_server_addr": MOONCAKE_MASTER_SERVER_ADDRESS,
+                "num_workers": 2,
+            }
+        )
+        self.adapter = create_l2_adapter(config)
+        yield
+        adapter = self.adapter
+        self.adapter = None
+        if adapter is not None:
+            adapter.close()
+
+    def test_event_fds_are_distinct(self):
+        """Each operation should have a distinct event fd."""
+        fds = {
+            self.adapter.get_store_event_fd(),
+            self.adapter.get_lookup_and_lock_event_fd(),
+            self.adapter.get_load_event_fd(),
+        }
+        assert len(fds) == 3
+
+    def test_store_and_lookup(self):
+        """Store objects, then verify lookup finds them."""
+        keys = [create_object_key(i) for i in range(5)]
+        objs = [create_memory_obj(size=64, fill_value=float(i)) for i in range(5)]
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Store
+        store_tid = self.adapter.submit_store_task(keys, objs)
+        assert wait_for_event_fd(store_fd)
+        completed = self.adapter.pop_completed_store_tasks()
+        assert completed[store_tid].is_successful()
+
+        # Lookup all — should find everything
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap is not None
+        for i in range(5):
+            assert bitmap.test(i) is True, f"Key {i} not found in lookup"
+
+        # Unlock
+        self.adapter.submit_unlock(keys)
+
+    def test_lookup_nonexistent_keys(self):
+        """Lookup for keys not stored should return all zeros."""
+        keys = [create_object_key(i + 10000) for i in range(3)]
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap is not None
+        for i in range(3):
+            assert bitmap.test(i) is False
+
+    def test_full_store_lookup_load_workflow(self):
+        """End-to-end: store -> lookup -> load, verify data integrity."""
+        key = create_object_key(42)
+        store_obj = create_memory_obj(size=512, fill_value=3.14)
+        load_obj = create_memory_obj(size=512, fill_value=0.0)
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+        load_fd = self.adapter.get_load_event_fd()
+
+        # Store
+        store_tid = self.adapter.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Lookup
+        lookup_tid = self.adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap.test(0) is True
+
+        # Load
+        load_tid = self.adapter.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd)
+        bitmap = self.adapter.query_load_result(load_tid)
+        assert bitmap.test(0) is True
+
+        # Verify data integrity
+        assert torch.allclose(load_obj.tensor, store_obj.tensor), (
+            "Loaded data does not match stored data"
+        )
+
+        # Unlock
+        self.adapter.submit_unlock([key])
+
+    def test_batch_store_lookup_load(self):
+        """Batch workflow with multiple objects."""
+        n = 10
+        keys = [create_object_key(i + 100) for i in range(n)]
+        store_objs = [
+            create_memory_obj(size=128, fill_value=float(i * 7)) for i in range(n)
+        ]
+        load_objs = [create_memory_obj(size=128, fill_value=0.0) for _ in range(n)]
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+        load_fd = self.adapter.get_load_event_fd()
+
+        # Store all
+        store_tid = self.adapter.submit_store_task(keys, store_objs)
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Lookup all
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        for i in range(n):
+            assert bitmap.test(i) is True
+
+        # Load all
+        load_tid = self.adapter.submit_load_task(keys, load_objs)
+        assert wait_for_event_fd(load_fd)
+        bitmap = self.adapter.query_load_result(load_tid)
+        for i in range(n):
+            assert bitmap.test(i) is True
+            assert torch.allclose(load_objs[i].tensor, store_objs[i].tensor), (
+                f"Data mismatch for key {i}"
+            )
+
+        self.adapter.submit_unlock(keys)
+
+    def test_mixed_lookup_existing_and_missing(self):
+        """Lookup a mix of stored and non-stored keys."""
+        stored_keys = [create_object_key(i + 200) for i in range(3)]
+        stored_objs = [create_memory_obj(fill_value=float(i)) for i in range(3)]
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Store first 3
+        self.adapter.submit_store_task(stored_keys, stored_objs)
+        assert wait_for_event_fd(store_fd)
+        self.adapter.pop_completed_store_tasks()
+
+        # Lookup 5 keys (3 stored + 2 missing)
+        all_keys = stored_keys + [
+            create_object_key(10100),
+            create_object_key(10101),
+        ]
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(all_keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+
+        for i in range(3):
+            assert bitmap.test(i) is True, f"Stored key {i} should be found"
+        assert bitmap.test(3) is False, "Missing key should not be found"
+        assert bitmap.test(4) is False, "Missing key should not be found"
+
+        self.adapter.submit_unlock(stored_keys)
+
+    # -----------------------------------------------------------------
+    # Delete tests
+    # -----------------------------------------------------------------
+
+    def test_delete_stored_key(self):
+        """Delete a stored key, then lookup confirms it is gone."""
+        key = create_object_key(555)
+        store_obj = create_memory_obj(size=128, fill_value=7.0)
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Store
+        store_tid = self.adapter.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Confirm stored
+        lookup_tid = self.adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap.test(0) is True
+        self.adapter.submit_unlock([key])
+
+        # Delete
+        self.adapter.delete([key])
+
+        # Lookup again — should be gone
+        lookup_tid = self.adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap.test(0) is False, "Key should not exist after delete"
+
+    def test_delete_nonexistent_keys(self):
+        """Deleting keys that don't exist should not raise."""
+        keys = [create_object_key(i + 80000) for i in range(3)]
+        # Should complete without error
+        self.adapter.delete(keys)
+
+    def test_batch_delete_mixed_existing_and_missing(self):
+        """Batch delete a mix of stored and non-stored keys."""
+        stored_keys = [create_object_key(i + 600) for i in range(3)]
+        stored_objs = [
+            create_memory_obj(size=64, fill_value=float(i + 1)) for i in range(3)
+        ]
+        missing_keys = [
+            create_object_key(90001),
+            create_object_key(90002),
+        ]
+        all_keys = stored_keys + missing_keys
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Store the first 3
+        store_tid = self.adapter.submit_store_task(stored_keys, stored_objs)
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Confirm they exist
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(
+            stored_keys, _EMPTY_LAYOUT
+        )
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        for i in range(3):
+            assert bitmap.test(i) is True
+        self.adapter.submit_unlock(stored_keys)
+
+        # Batch delete mixed keys
+        self.adapter.delete(all_keys)
+
+        # Stored keys should now be gone
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(
+            stored_keys, _EMPTY_LAYOUT
+        )
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        for i in range(3):
+            assert bitmap.test(i) is False, f"Key {i} should be gone after delete"
+
+    def test_delete_updates_usage_tracking(self):
+        """Deleting a stored key reduces tracked byte usage."""
+        key = create_object_key(777)
+        store_obj = create_memory_obj(size=128, fill_value=9.0)
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Record usage before store
+        usage_before = self.adapter.get_usage().total_bytes_used
+
+        # Store
+        store_tid = self.adapter.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        usage_after_store = self.adapter.get_usage().total_bytes_used
+        assert usage_after_store > usage_before, "Usage should increase after store"
+
+        # Confirm stored in lookup so _key_sizes is populated
+        _ = self.adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        self.adapter.submit_unlock([key])
+
+        # Delete
+        self.adapter.delete([key])
+
+        usage_after_delete = self.adapter.get_usage().total_bytes_used
+        assert usage_after_delete == usage_before, (
+            f"Usage should return to baseline after delete: "
+            f"before={usage_before}, after_delete={usage_after_delete}"
+        )
+
+    def test_factory_creates_adapter(self):
+        """Verify the factory can create a Mooncake Store L2 adapter."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": MOONCAKE_LOCAL_HOSTNAME,
+                "metadata_server": MOONCAKE_METADATA_SERVER,
+                "master_server_addr": MOONCAKE_MASTER_SERVER_ADDRESS,
+                "num_workers": 2,
+            }
+        )
+        adapter = create_l2_adapter(config)
+        try:
+            # Should have valid event fds
+            assert adapter.get_store_event_fd() >= 0
+            assert adapter.get_lookup_and_lock_event_fd() >= 0
+            assert adapter.get_load_event_fd() >= 0
+        finally:
+            adapter.close()
+
+    @requires_mooncake_rdma
+    def test_buffer_backed_store_lookup_load(self):
+        """Store and load RDMA-preregistered objects backed by an explicit L1 buffer."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+
+        # The class-level fixture creates a default TCP adapter. Close it before
+        # creating the RDMA adapter, otherwise Mooncake master may allocate this
+        # test object's replica on the TCP segment and the RDMA-only client will
+        # fail with NotSupportedTransport.
+        self.adapter.close()
+        self.adapter = None
+
+        page_size = 4096
+        obj_size_bytes = page_size * 16
+        l1_buffer = torch.empty(page_size * 256, dtype=torch.uint8, device="cpu")
+        l1_desc = L1MemoryDesc(
+            ptr=l1_buffer.data_ptr(),
+            size=l1_buffer.numel(),
+            align_bytes=page_size,
+        )
+
+        config = MooncakeStoreL2AdapterConfig.from_dict(
+            {
+                "type": "mooncake_store",
+                "local_hostname": MOONCAKE_LOCAL_HOSTNAME,
+                "metadata_server": MOONCAKE_METADATA_SERVER,
+                "master_server_addr": MOONCAKE_MASTER_SERVER_ADDRESS,
+                "num_workers": 2,
+                "protocol": "rdma",
+                "rdma_devices": MOONCAKE_DEVICE_NAME,
+            }
+        )
+        adapter = create_l2_adapter(config, l1_memory_desc=l1_desc)
+        try:
+            key = create_object_key(9001, model_name="preregister_model")
+            store_obj = create_buffer_memory_obj(
+                l1_buffer,
+                offset_bytes=0,
+                size_bytes=obj_size_bytes,
+                fill_value=6.25,
+            )
+            load_obj = create_buffer_memory_obj(
+                l1_buffer,
+                offset_bytes=obj_size_bytes * 2,
+                size_bytes=obj_size_bytes,
+                fill_value=0.0,
+            )
+
+            store_tid = adapter.submit_store_task([key], [store_obj])
+            assert wait_for_event_fd(adapter.get_store_event_fd())
+            assert adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+            lookup_tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+            assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+            lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_tid)
+            assert lookup_bitmap.test(0) is True
+
+            load_tid = adapter.submit_load_task([key], [load_obj])
+            assert wait_for_event_fd(adapter.get_load_event_fd())
+            load_bitmap = adapter.query_load_result(load_tid)
+            assert load_bitmap.test(0) is True
+            assert torch.equal(load_obj.tensor, store_obj.tensor)
+
+            adapter.submit_unlock([key])
+        finally:
+            adapter.close()
diff --git a/tests/v1/distributed/test_multimodel.py b/tests/v1/distributed/test_multimodel.py
new file mode 100644
index 0000000..6e8a3b5
--- /dev/null
+++ b/tests/v1/distributed/test_multimodel.py
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+"""End-to-end tests for multi-model support in the StoreController.
+
+A single ``finish_write`` with mixed-model keys must result in per-model
+``submit_store_task`` calls so each submission sees uniform ``(shape, dtype)``.
+"""
+
+# Standard
+from unittest.mock import patch
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import L2AdaptersConfig
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int, model_name: str) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def wait_for_condition(predicate, timeout: float = 10.0, poll_interval: float = 0.05):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def make_storage_manager(l1_size_mb: int = 256) -> StorageManager:
+    cfg = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=l1_size_mb * 1024 * 1024,
+                use_lazy=True,
+                init_size_in_bytes=min(l1_size_mb, 64) * 1024 * 1024,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(
+            adapters=[MockL2AdapterConfig(max_size_gb=0.1, mock_bandwidth_gb=10.0)],
+        ),
+    )
+    return StorageManager(cfg)
+
+
+# =============================================================================
+# Tests
+# =============================================================================
+
+
+class TestStoreControllerMultimodel:
+    """Mixed-model keys in one ``finish_write`` must be split per model
+    before reaching ``submit_store_task``."""
+
+    def test_each_submit_store_task_has_uniform_shape(self):
+        layout_a = MemoryLayoutDesc(
+            shapes=[torch.Size([100, 2, 512])], dtypes=[torch.bfloat16]
+        )
+        layout_b = MemoryLayoutDesc(
+            shapes=[torch.Size([50, 2, 256])], dtypes=[torch.bfloat16]
+        )
+        keys_a = [make_object_key(i, "model_a") for i in range(3)]
+        keys_b = [make_object_key(100 + i, "model_b") for i in range(3)]
+
+        # Record the (shape, dtype) set observed per submit_store_task call.
+        submit_shape_groups = []
+        original_submit = MockL2Adapter.submit_store_task
+
+        def recording_submit(self, keys, objects):
+            shape_set = frozenset(
+                (tuple(obj.get_shapes()), tuple(obj.get_dtypes())) for obj in objects
+            )
+            submit_shape_groups.append(shape_set)
+            return original_submit(self, keys, objects)
+
+        with patch.object(MockL2Adapter, "submit_store_task", recording_submit):
+            sm = make_storage_manager()
+            adapter = sm._l2_adapters[0]
+
+            ret_a = sm.reserve_write(keys_a, layout_a, mode="new")
+            ret_b = sm.reserve_write(keys_b, layout_b, mode="new")
+            for i, k in enumerate(keys_a):
+                ret_a[k].tensor.fill_(float(i + 1))
+            for i, k in enumerate(keys_b):
+                ret_b[k].tensor.fill_(float(100 + i))
+
+            # Single finish_write forces a mixed-model batch in the listener.
+            sm.finish_write(keys_a + keys_b)
+
+            # Wait until every key has landed in L2 — avoids a race on the
+            # in_flight counter (which is briefly 0 between pop and submit).
+            ok = wait_for_condition(
+                lambda: all(
+                    adapter.debug_has_key(k)  # type: ignore[attr-defined]
+                    for k in keys_a + keys_b
+                ),
+                timeout=10.0,
+            )
+            assert ok, "Not all keys were stored in L2 within timeout"
+
+            assert submit_shape_groups, "No submit_store_task calls were recorded"
+            for i, shapes in enumerate(submit_shape_groups):
+                assert len(shapes) == 1, (
+                    f"submit_store_task #{i} received keys with mixed "
+                    f"(shape, dtype): {shapes}. Mixed-model batches must be "
+                    f"grouped by model before reaching the adapter."
+                )
+
+            distinct_shapes = {s for group in submit_shape_groups for s in group}
+            assert len(distinct_shapes) == 2, (
+                f"Expected both models' shapes to appear across submits, "
+                f"got {len(distinct_shapes)}: {distinct_shapes}"
+            )
+
+            sm.close()
diff --git a/tests/v1/distributed/test_native_connector_l2_adapter.py b/tests/v1/distributed/test_native_connector_l2_adapter.py
new file mode 100644
index 0000000..dc16cdd
--- /dev/null
+++ b/tests/v1/distributed/test_native_connector_l2_adapter.py
@@ -0,0 +1,1360 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for NativeConnectorL2Adapter.
+
+Uses a mock native connector (pure Python) that simulates the pybind-wrapped
+C++ IStorageConnector interface, so no Redis or C++ build is needed.
+"""
+
+# Standard
+import ctypes
+import select
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+    NativeConnectorL2Adapter,
+    _object_key_to_string,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd, create_event_notifier
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+# =============================================================================
+# Mock Native Connector (simulates the pybind C++ IStorageConnector interface)
+# =============================================================================
+
+
+class MockNativeConnector:
+    """
+    Pure-Python mock that implements the same interface as a pybind-wrapped
+    C++ IStorageConnector.  Stores data in-memory dicts.
+
+    Methods:
+      - event_fd() -> int
+      - submit_batch_get(keys, memoryviews) -> int
+      - submit_batch_set(keys, memoryviews) -> int
+      - submit_batch_exists(keys) -> int
+      - drain_completions() -> list[tuple[int, bool, str, list[bool] | None]]
+      - close()
+    """
+
+    def __init__(self):
+        self._efd = create_event_notifier()
+        self._store: dict[str, bytes] = {}
+        self._next_id = 1
+        self._completions: list[tuple[int, bool, str, list[bool] | None]] = []
+        self._lock = threading.Lock()
+        self._closed = False
+
+    def event_fd(self) -> int:
+        return self._efd.fileno()
+
+    def submit_batch_set(self, keys: list[str], memoryviews: list) -> int:
+        with self._lock:
+            fid = self._next_id
+            self._next_id += 1
+
+        try:
+            for key, mv in zip(keys, memoryviews, strict=False):
+                self._store[key] = bytes(mv)
+            self._push_completion(fid, True, "", None)
+        except Exception as e:
+            self._push_completion(fid, False, str(e), None)
+
+        return fid
+
+    def submit_batch_get(self, keys: list[str], memoryviews: list) -> int:
+        with self._lock:
+            fid = self._next_id
+            self._next_id += 1
+
+        try:
+            all_ok = True
+            for key, mv in zip(keys, memoryviews, strict=False):
+                data = self._store.get(key)
+                if data is None:
+                    all_ok = False
+                    break
+                if len(data) != mv.nbytes:
+                    all_ok = False
+                    break
+                # Copy data into the buffer using ctypes (same as C++ void* write)
+                dest_ptr = ctypes.c_char_p(
+                    ctypes.addressof(ctypes.c_char.from_buffer(mv))
+                )
+                ctypes.memmove(dest_ptr, data, len(data))
+            self._push_completion(fid, all_ok, "", None)
+        except Exception as e:
+            self._push_completion(fid, False, str(e), None)
+
+        return fid
+
+    def submit_batch_exists(self, keys: list[str]) -> int:
+        with self._lock:
+            fid = self._next_id
+            self._next_id += 1
+
+        results = [key in self._store for key in keys]
+        self._push_completion(fid, True, "", results)
+
+        return fid
+
+    def submit_batch_delete(self, keys: list[str]) -> int:
+        with self._lock:
+            fid = self._next_id
+            self._next_id += 1
+
+        results = []
+        for key in keys:
+            if key in self._store:
+                del self._store[key]
+                results.append(True)
+            else:
+                results.append(False)
+        self._push_completion(fid, True, "", results)
+
+        return fid
+
+    def drain_completions(self) -> list[tuple[int, bool, str, list[bool] | None]]:
+        # Drain the eventfd
+        try:
+            self._efd.consume()
+        except BlockingIOError:
+            pass
+
+        with self._lock:
+            completions = list(self._completions)
+            self._completions.clear()
+        return completions
+
+    def close(self):
+        if not self._closed:
+            self._closed = True
+            self._efd.close()
+
+    def _push_completion(
+        self, fid: int, ok: bool, error: str, result_bools: list[bool] | None
+    ):
+        with self._lock:
+            self._completions.append((fid, ok, error, result_bools))
+        # Signal the eventfd
+        try:
+            self._efd.notify()
+        except OSError:
+            pass
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(size: int = 1024, fill_value: float = 1.0) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+@pytest.fixture
+def adapter():
+    mock_client = MockNativeConnector()
+    adp = NativeConnectorL2Adapter(mock_client)
+    yield adp
+    adp.close()
+
+
+# =============================================================================
+# ObjectKey Serialization Tests
+# =============================================================================
+
+
+class TestObjectKeySerialization:
+    def test_serialization_is_deterministic(self):
+        key = create_object_key(42, "my_model")
+        s1 = _object_key_to_string(key)
+        s2 = _object_key_to_string(key)
+        assert s1 == s2
+
+    def test_different_keys_produce_different_strings(self):
+        k1 = create_object_key(1)
+        k2 = create_object_key(2)
+        assert _object_key_to_string(k1) != _object_key_to_string(k2)
+
+    def test_serialization_format(self):
+        """Unsalted keys use the 4-field shape with object_group_id
+        embedded right after kv_rank."""
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+        )
+        s = _object_key_to_string(key)
+        assert s == "llama@000000ff@0@00010203"
+
+    def test_object_group_id_embedded(self):
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+            object_group_id=5,
+        )
+        s = _object_key_to_string(key)
+        assert s == "llama@000000ff@5@00010203"
+
+    def test_salted_serialization_format(self):
+        """Salted keys append ``@<cache_salt>`` as a 5th field."""
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+            cache_salt="alice",
+        )
+        s = _object_key_to_string(key)
+        assert s == "llama@000000ff@0@00010203@alice"
+
+    def test_different_salts_produce_different_strings(self):
+        base = {
+            "chunk_hash": b"\x00\x01\x02\x03",
+            "model_name": "llama",
+            "kv_rank": 0,
+        }
+        k_empty = ObjectKey(**base)
+        k_alice = ObjectKey(**base, cache_salt="alice")
+        k_bob = ObjectKey(**base, cache_salt="bob")
+        s_empty = _object_key_to_string(k_empty)
+        s_alice = _object_key_to_string(k_alice)
+        s_bob = _object_key_to_string(k_bob)
+        assert s_empty != s_alice
+        assert s_alice != s_bob
+        # Empty salt has no trailing "@salt", salted keys do.
+        assert s_empty.count("@") == 3  # 4 fields (model, kv_rank, group, hash)
+        assert s_alice.endswith("@alice")
+        assert s_bob.endswith("@bob")
+
+
+class TestObjectKeyModelNameValidation:
+    """model_name must not contain ``@`` — the L2 adapters split keys
+    and filenames on ``@`` and rely on this invariant."""
+
+    def test_reject_at_in_model_name(self):
+        with pytest.raises(ValueError, match="model_name"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="ns@model",
+                kv_rank=0,
+            )
+
+    def test_slash_in_model_name_is_accepted(self):
+        # '/' is sanitized to '-SEP-' by the FS adapter; the invariant
+        # is only about '@'.
+        key = ObjectKey(
+            chunk_hash=b"\x00",
+            model_name="meta-llama/Llama-3",
+            kv_rank=0,
+        )
+        assert key.model_name == "meta-llama/Llama-3"
+
+
+class TestObjectKeyCacheSaltValidation:
+    """cache_salt must not contain ``@``, ``/``, ``\\``, or NUL, and must
+    be <= 128 chars. The invariant is enforced at construction time so
+    all downstream serializers (Python + C++) can rely on it."""
+
+    def test_reject_at_in_salt(self):
+        with pytest.raises(ValueError, match="cache_salt"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="m",
+                kv_rank=0,
+                cache_salt="alice@bob",
+            )
+
+    def test_reject_leading_at_in_salt(self):
+        with pytest.raises(ValueError, match="cache_salt"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="m",
+                kv_rank=0,
+                cache_salt="@user",
+            )
+
+    def test_reject_slash_in_salt(self):
+        with pytest.raises(ValueError, match="cache_salt"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="m",
+                kv_rank=0,
+                cache_salt="tenant/alice",
+            )
+
+    def test_reject_backslash_in_salt(self):
+        with pytest.raises(ValueError, match="cache_salt"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="m",
+                kv_rank=0,
+                cache_salt="tenant\\alice",
+            )
+
+    def test_reject_nul_in_salt(self):
+        with pytest.raises(ValueError, match="cache_salt"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="m",
+                kv_rank=0,
+                cache_salt="bad\x00salt",
+            )
+
+    def test_reject_too_long_salt(self):
+        with pytest.raises(ValueError, match="max length"):
+            ObjectKey(
+                chunk_hash=b"\x00",
+                model_name="m",
+                kv_rank=0,
+                cache_salt="x" * 129,
+            )
+
+    def test_max_length_salt_accepted(self):
+        key = ObjectKey(
+            chunk_hash=b"\x00",
+            model_name="m",
+            kv_rank=0,
+            cache_salt="x" * 128,
+        )
+        assert len(key.cache_salt) == 128
+
+    def test_empty_salt_is_accepted(self):
+        # Default (unsalted) path.
+        key = ObjectKey(chunk_hash=b"\x00", model_name="m", kv_rank=0)
+        assert key.cache_salt == ""
+
+    def test_non_salt_chars_are_accepted(self):
+        # Common identifier chars are fine.
+        key = ObjectKey(
+            chunk_hash=b"\x00",
+            model_name="m",
+            kv_rank=0,
+            cache_salt="user-abc_123.xyz:42",
+        )
+        assert key.cache_salt == "user-abc_123.xyz:42"
+
+
+class TestObjectKeyIsolation:
+    """cache_salt must participate in eq/hash so the L1/L2 caches treat
+    same-content/different-user entries as distinct."""
+
+    def test_different_salts_are_unequal(self):
+        base = {"chunk_hash": b"x", "model_name": "m", "kv_rank": 0}
+        a = ObjectKey(**base, cache_salt="alice")
+        b = ObjectKey(**base, cache_salt="bob")
+        assert a != b
+        assert hash(a) != hash(b)
+
+    def test_empty_salt_is_unequal_to_any_salted(self):
+        base = {"chunk_hash": b"x", "model_name": "m", "kv_rank": 0}
+        unsalted = ObjectKey(**base)
+        salted = ObjectKey(**base, cache_salt="alice")
+        assert unsalted != salted
+
+    def test_same_salt_are_equal(self):
+        base = {"chunk_hash": b"x", "model_name": "m", "kv_rank": 0}
+        a = ObjectKey(**base, cache_salt="alice")
+        b = ObjectKey(**base, cache_salt="alice")
+        assert a == b
+        assert hash(a) == hash(b)
+
+
+# =============================================================================
+# Event Fd Interface Tests
+# =============================================================================
+
+
+class TestEventFdInterface:
+    def test_three_distinct_event_fds(self, adapter):
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        assert store_fd >= 0
+        assert lookup_fd >= 0
+        assert load_fd >= 0
+        assert len({store_fd, lookup_fd, load_fd}) == 3
+
+
+# =============================================================================
+# Store Interface Tests
+# =============================================================================
+
+
+class TestStoreInterface:
+    def test_submit_store_returns_task_id(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        task_id = adapter.submit_store_task([key], [obj])
+        assert isinstance(task_id, int)
+
+    def test_store_signals_event_fd_and_completes(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+
+        task_id = adapter.submit_store_task([key], [obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed = adapter.pop_completed_store_tasks()
+        assert task_id in completed
+        assert completed[task_id].is_successful()
+
+    def test_pop_clears_completed_tasks(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed1 = adapter.pop_completed_store_tasks()
+        assert len(completed1) == 1
+
+        completed2 = adapter.pop_completed_store_tasks()
+        assert len(completed2) == 0
+
+    def test_multiple_store_tasks_get_unique_ids(self, adapter):
+        store_fd = adapter.get_store_event_fd()
+        task_ids = set()
+        for i in range(5):
+            key = create_object_key(i)
+            obj = create_memory_obj(fill_value=float(i))
+            task_ids.add(adapter.submit_store_task([key], [obj]))
+
+        assert len(task_ids) == 5
+
+        # Wait for all completions
+        completed = {}
+        while len(completed) < 5:
+            wait_for_event_fd(store_fd, timeout=5.0)
+            completed.update(adapter.pop_completed_store_tasks())
+
+        for tid in task_ids:
+            assert completed[tid].is_successful()
+
+    def test_batch_store(self, adapter):
+        keys = [create_object_key(i) for i in range(3)]
+        objs = [create_memory_obj(fill_value=float(i)) for i in range(3)]
+        store_fd = adapter.get_store_event_fd()
+
+        task_id = adapter.submit_store_task(keys, objs)
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed = adapter.pop_completed_store_tasks()
+        assert completed[task_id].is_successful()
+
+
+# =============================================================================
+# Lookup and Lock Interface Tests
+# =============================================================================
+
+
+class TestLookupAndLockInterface:
+    def test_lookup_nonexistent_key(self, adapter):
+        key = create_object_key(999)
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0) is False
+
+    def test_lookup_existing_key(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # Store first
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Lookup
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0) is True
+
+    def test_lookup_mixed_keys(self, adapter):
+        existing = create_object_key(1)
+        missing = create_object_key(999)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        adapter.submit_store_task([existing], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        task_id = adapter.submit_lookup_and_lock_task(
+            [existing, missing], _EMPTY_LAYOUT
+        )
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0) is True
+        assert bitmap.test(1) is False
+
+    def test_query_is_one_shot(self, adapter):
+        key = create_object_key(1)
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        result1 = adapter.query_lookup_and_lock_result(task_id)
+        assert result1 is not None
+
+        result2 = adapter.query_lookup_and_lock_result(task_id)
+        assert result2 is None
+
+    def test_query_unknown_task_returns_none(self, adapter):
+        assert adapter.query_lookup_and_lock_result(99999) is None
+
+
+# =============================================================================
+# Unlock Interface Tests
+# =============================================================================
+
+
+class TestUnlockInterface:
+    def test_unlock_does_not_raise(self, adapter):
+        key = create_object_key(1)
+        adapter.submit_unlock([key])  # should not raise
+
+    def test_unlock_after_lock(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+        adapter.query_lookup_and_lock_result(task_id)
+
+        adapter.submit_unlock([key])  # should not raise
+
+
+# =============================================================================
+# Load Interface Tests
+# =============================================================================
+
+
+class TestLoadInterface:
+    def test_submit_load_returns_task_id(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        task_id = adapter.submit_load_task([key], [obj])
+        assert isinstance(task_id, int)
+
+    def test_load_signals_event_fd(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        load_fd = adapter.get_load_event_fd()
+
+        adapter.submit_load_task([key], [obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+
+    def test_load_existing_key_copies_data(self, adapter):
+        key = create_object_key(1)
+        store_obj = create_memory_obj(size=100, fill_value=42.0)
+        load_obj = create_memory_obj(size=100, fill_value=0.0)
+        store_fd = adapter.get_store_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store
+        adapter.submit_store_task([key], [store_obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Load
+        task_id = adapter.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+
+        bitmap = adapter.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0) is True
+
+        # Verify data was copied into the load buffer
+        assert torch.all(load_obj.tensor == 42.0)
+
+    def test_load_nonexistent_key_fails(self, adapter):
+        key = create_object_key(999)
+        obj = create_memory_obj()
+        load_fd = adapter.get_load_event_fd()
+
+        task_id = adapter.submit_load_task([key], [obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+
+        bitmap = adapter.query_load_result(task_id)
+        assert bitmap is not None
+        # Batch GET failed → no bits set
+        assert bitmap.test(0) is False
+
+    def test_query_load_is_one_shot(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        load_fd = adapter.get_load_event_fd()
+
+        task_id = adapter.submit_load_task([key], [obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        result1 = adapter.query_load_result(task_id)
+        assert result1 is not None
+
+        result2 = adapter.query_load_result(task_id)
+        assert result2 is None
+
+    def test_query_unknown_task_returns_none(self, adapter):
+        assert adapter.query_load_result(99999) is None
+
+
+# =============================================================================
+# End-to-End Workflow Tests
+# =============================================================================
+
+
+class TestEndToEndWorkflow:
+    def test_store_lookup_load_workflow(self, adapter):
+        key = create_object_key(1)
+        store_obj = create_memory_obj(size=256, fill_value=123.0)
+        load_obj = create_memory_obj(size=256, fill_value=0.0)
+
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store
+        store_tid = adapter.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        assert adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Lookup
+        lookup_tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap.test(0) is True
+
+        # Load
+        load_tid = adapter.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        bitmap = adapter.query_load_result(load_tid)
+        assert bitmap.test(0) is True
+        assert torch.all(load_obj.tensor == 123.0)
+
+        # Unlock
+        adapter.submit_unlock([key])
+
+    def test_multiple_objects_workflow(self, adapter):
+        n = 5
+        keys = [create_object_key(i) for i in range(n)]
+        store_objs = [
+            create_memory_obj(size=64, fill_value=float(i * 10)) for i in range(n)
+        ]
+        load_objs = [create_memory_obj(size=64, fill_value=0.0) for _ in range(n)]
+
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+        load_fd = adapter.get_load_event_fd()
+
+        # Store all
+        store_tid = adapter.submit_store_task(keys, store_objs)
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        assert adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Lookup all
+        lookup_tid = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(lookup_tid)
+        for i in range(n):
+            assert bitmap.test(i) is True
+
+        # Load all
+        load_tid = adapter.submit_load_task(keys, load_objs)
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        bitmap = adapter.query_load_result(load_tid)
+        for i in range(n):
+            assert bitmap.test(i) is True
+            assert torch.all(load_objs[i].tensor == float(i * 10))
+
+
+# =============================================================================
+# Close Tests
+# =============================================================================
+
+
+class TestClose:
+    def test_close_does_not_raise(self):
+        mock_client = MockNativeConnector()
+        adp = NativeConnectorL2Adapter(mock_client)
+        adp.close()
+
+    def test_close_after_operations(self):
+        mock_client = MockNativeConnector()
+        adp = NativeConnectorL2Adapter(mock_client)
+
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adp.get_store_event_fd()
+
+        adp.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adp.pop_completed_store_tasks()
+
+        adp.close()
+
+
+# =============================================================================
+# Config Tests
+# =============================================================================
+
+
+class TestRESPL2AdapterConfig:
+    def test_from_dict_minimal(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        config = RESPL2AdapterConfig.from_dict(
+            {
+                "type": "resp",
+                "host": "localhost",
+                "port": 6379,
+            }
+        )
+        assert config.host == "localhost"
+        assert config.port == 6379
+        assert config.num_workers == 8
+        assert config.username == ""
+        assert config.password == ""
+
+    def test_from_dict_full(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        config = RESPL2AdapterConfig.from_dict(
+            {
+                "type": "resp",
+                "host": "10.0.0.1",
+                "port": 6380,
+                "num_workers": 16,
+                "username": "user",
+                "password": "pass",
+            }
+        )
+        assert config.host == "10.0.0.1"
+        assert config.port == 6380
+        assert config.num_workers == 16
+        assert config.username == "user"
+        assert config.password == "pass"
+
+    def test_from_dict_missing_host_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="host"):
+            RESPL2AdapterConfig.from_dict({"type": "resp", "port": 6379})
+
+    def test_from_dict_missing_port_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="port"):
+            RESPL2AdapterConfig.from_dict({"type": "resp", "host": "localhost"})
+
+    def test_registered_as_resp(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.config import (
+            get_registered_l2_adapter_types,
+        )
+
+        assert "resp" in get_registered_l2_adapter_types()
+
+
+# =============================================================================
+# NativePluginL2AdapterConfig Tests
+# =============================================================================
+
+
+class TestNativePluginL2AdapterConfig:
+    def test_from_dict_minimal(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        config = NativePluginL2AdapterConfig.from_dict(
+            {
+                "type": "native_plugin",
+                "module_path": "my_ext.connector",
+                "class_name": "MyClient",
+            }
+        )
+        assert config.module_path == "my_ext.connector"
+        assert config.class_name == "MyClient"
+        assert config.adapter_params == {}
+
+    def test_from_dict_full(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        config = NativePluginL2AdapterConfig.from_dict(
+            {
+                "type": "native_plugin",
+                "module_path": "my_ext.connector",
+                "class_name": "MyClient",
+                "adapter_params": {
+                    "host": "localhost",
+                    "port": 1234,
+                },
+            }
+        )
+        assert config.module_path == "my_ext.connector"
+        assert config.class_name == "MyClient"
+        assert config.adapter_params == {
+            "host": "localhost",
+            "port": 1234,
+        }
+
+    def test_from_dict_missing_module_path_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="module_path"):
+            NativePluginL2AdapterConfig.from_dict(
+                {
+                    "type": "native_plugin",
+                    "class_name": "X",
+                }
+            )
+
+    def test_from_dict_missing_class_name_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="class_name"):
+            NativePluginL2AdapterConfig.from_dict(
+                {
+                    "type": "native_plugin",
+                    "module_path": "my_ext",
+                }
+            )
+
+    def test_from_dict_invalid_adapter_params_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="adapter_params"):
+            NativePluginL2AdapterConfig.from_dict(
+                {
+                    "type": "native_plugin",
+                    "module_path": "my_ext",
+                    "class_name": "X",
+                    "adapter_params": "not_a_dict",
+                }
+            )
+
+    def test_registered_as_native_plugin(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.config import (
+            get_registered_l2_adapter_types,
+        )
+
+        assert "native_plugin" in get_registered_l2_adapter_types()
+
+    def test_help_returns_string(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.native_plugin_l2_adapter import (
+            NativePluginL2AdapterConfig,
+        )
+
+        h = NativePluginL2AdapterConfig.help()
+        assert isinstance(h, str)
+        assert "module_path" in h
+        assert "class_name" in h
+        assert "adapter_params" in h
+
+
+# =============================================================================
+# FSNativeL2AdapterConfig Tests
+# =============================================================================
+
+
+class TestFSNativeL2AdapterConfig:
+    def test_from_dict_minimal(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        config = FSNativeL2AdapterConfig.from_dict(
+            {
+                "type": "fs_native",
+                "base_path": "/tmp/lmcache_test",
+            }
+        )
+        assert config.base_path == "/tmp/lmcache_test"
+        assert config.num_workers == 4
+        assert config.relative_tmp_dir == ""
+        assert config.use_odirect is False
+        assert config.read_ahead_size is None
+
+    def test_from_dict_full(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        config = FSNativeL2AdapterConfig.from_dict(
+            {
+                "type": "fs_native",
+                "base_path": "/data/kv_cache",
+                "num_workers": 16,
+                "relative_tmp_dir": ".tmp",
+                "use_odirect": True,
+                "read_ahead_size": 4096,
+            }
+        )
+        assert config.base_path == "/data/kv_cache"
+        assert config.num_workers == 16
+        assert config.relative_tmp_dir == ".tmp"
+        assert config.use_odirect is True
+        assert config.read_ahead_size == 4096
+
+    def test_from_dict_missing_base_path_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="base_path"):
+            FSNativeL2AdapterConfig.from_dict({"type": "fs_native"})
+
+    def test_from_dict_empty_base_path_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="base_path"):
+            FSNativeL2AdapterConfig.from_dict({"type": "fs_native", "base_path": ""})
+
+    def test_from_dict_invalid_num_workers_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="num_workers"):
+            FSNativeL2AdapterConfig.from_dict(
+                {
+                    "type": "fs_native",
+                    "base_path": "/tmp/x",
+                    "num_workers": 0,
+                }
+            )
+
+    def test_from_dict_zero_num_workers_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="num_workers"):
+            FSNativeL2AdapterConfig.from_dict(
+                {
+                    "type": "fs_native",
+                    "base_path": "/tmp/x",
+                    "num_workers": -1,
+                }
+            )
+
+    def test_from_dict_invalid_relative_tmp_dir_raises(
+        self,
+    ):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="relative_tmp_dir"):
+            FSNativeL2AdapterConfig.from_dict(
+                {
+                    "type": "fs_native",
+                    "base_path": "/tmp/x",
+                    "relative_tmp_dir": 123,
+                }
+            )
+
+    def test_from_dict_invalid_use_odirect_raises(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="use_odirect"):
+            FSNativeL2AdapterConfig.from_dict(
+                {
+                    "type": "fs_native",
+                    "base_path": "/tmp/x",
+                    "use_odirect": "yes",
+                }
+            )
+
+    def test_from_dict_invalid_read_ahead_size_raises(
+        self,
+    ):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="read_ahead_size"):
+            FSNativeL2AdapterConfig.from_dict(
+                {
+                    "type": "fs_native",
+                    "base_path": "/tmp/x",
+                    "read_ahead_size": -1,
+                }
+            )
+
+    def test_from_dict_zero_read_ahead_size_raises(
+        self,
+    ):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        with pytest.raises(ValueError, match="read_ahead_size"):
+            FSNativeL2AdapterConfig.from_dict(
+                {
+                    "type": "fs_native",
+                    "base_path": "/tmp/x",
+                    "read_ahead_size": 0,
+                }
+            )
+
+    def test_registered_as_fs_native(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.config import (
+            get_registered_l2_adapter_types,
+        )
+
+        assert "fs_native" in get_registered_l2_adapter_types()
+
+    def test_help_returns_string(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        h = FSNativeL2AdapterConfig.help()
+        assert isinstance(h, str)
+        assert "base_path" in h
+        assert "num_workers" in h
+        assert "use_odirect" in h
+        assert "read_ahead_size" in h
+
+    def test_type_name_lookup(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.config import (
+            get_type_name_for_config,
+        )
+        from lmcache.v1.distributed.l2_adapters.fs_native_l2_adapter import (
+            FSNativeL2AdapterConfig,
+        )
+
+        cfg = FSNativeL2AdapterConfig(
+            base_path="/tmp/test",
+        )
+        assert get_type_name_for_config(cfg) == "fs_native"
+
+
+# =============================================================================
+# Delete Interface Tests
+# =============================================================================
+
+
+class TestDeleteInterface:
+    def test_delete_existing_key(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj()
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # Store
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Verify exists
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap.test(0) is True
+        adapter.submit_unlock([key])
+
+        # Delete (synchronous)
+        adapter.delete([key])
+
+        # Verify gone
+        task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        assert bitmap.test(0) is False
+
+    def test_delete_nonexistent_key(self, adapter):
+        key = create_object_key(999)
+        adapter.delete([key])  # should not raise
+
+    def test_delete_empty_keys(self, adapter):
+        adapter.delete([])  # should not raise
+
+    def test_delete_batch(self, adapter):
+        keys = [create_object_key(i) for i in range(5)]
+        objs = [create_memory_obj(fill_value=float(i)) for i in range(5)]
+        store_fd = adapter.get_store_event_fd()
+        lookup_fd = adapter.get_lookup_and_lock_event_fd()
+
+        # Store all
+        adapter.submit_store_task(keys, objs)
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adapter.pop_completed_store_tasks()
+
+        # Delete first 3
+        adapter.delete(keys[:3])
+
+        # Verify: first 3 gone, last 2 remain
+        task_id = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adapter.query_lookup_and_lock_result(task_id)
+        for i in range(3):
+            assert bitmap.test(i) is False
+        for i in range(3, 5):
+            assert bitmap.test(i) is True
+        adapter.submit_unlock(keys[3:])
+
+
+# =============================================================================
+# Delete Backward Compatibility Tests
+# =============================================================================
+
+
+class TestDeleteBackwardCompatibility:
+    def test_delete_noop_without_submit_batch_delete(self):
+        """Connector without submit_batch_delete => delete is no-op."""
+
+        class NoDeleteConnector:
+            """Mock connector that only has the 6 original methods."""
+
+            def __init__(self):
+                self._efd = create_event_notifier()
+                self._closed = False
+
+            def event_fd(self) -> int:
+                return self._efd.fileno()
+
+            def submit_batch_get(self, keys, memoryviews):
+                return 0
+
+            def submit_batch_set(self, keys, memoryviews):
+                return 0
+
+            def submit_batch_exists(self, keys):
+                return 0
+
+            def drain_completions(self):
+                return []
+
+            def close(self):
+                if not self._closed:
+                    self._closed = True
+                    self._efd.close()
+
+        client = NoDeleteConnector()
+        adp = NativeConnectorL2Adapter(client)
+        try:
+            key = create_object_key(1)
+            adp.delete([key])  # should not raise, just no-op
+        finally:
+            adp.close()
+
+
+# =============================================================================
+# Usage Tracking Tests
+# =============================================================================
+
+
+@pytest.fixture
+def adapter_with_capacity():
+    """Adapter with max_capacity_gb set for usage tracking tests."""
+    mock_client = MockNativeConnector()
+    # 100 floats * 4 bytes = 400 bytes per obj; capacity = 2000 bytes = 2000/1024^3 GB
+    adp = NativeConnectorL2Adapter(mock_client, max_capacity_gb=2000 / (1024**3))
+    yield adp
+    adp.close()
+
+
+class TestUsageTracking:
+    def test_get_usage_without_capacity(self, adapter):
+        """Without max_capacity_bytes, usage_fraction == -1 (sentinel)."""
+        usage = adapter.get_usage()
+        assert usage.usage_fraction == -1.0
+        assert usage.total_capacity_bytes == 0
+
+    def test_get_usage_starts_at_zero(self, adapter_with_capacity):
+        usage = adapter_with_capacity.get_usage()
+        assert usage.usage_fraction == 0.0
+        assert usage.total_bytes_used == 0
+
+    def test_get_usage_after_store(self, adapter_with_capacity):
+        adp = adapter_with_capacity
+        store_fd = adp.get_store_event_fd()
+
+        key = create_object_key(1)
+        obj = create_memory_obj(size=100, fill_value=1.0)  # 100 floats = 400 bytes
+
+        adp.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adp.pop_completed_store_tasks()
+
+        usage = adp.get_usage()
+        # 400 bytes / 2000 bytes = 0.2
+        assert usage.usage_fraction == pytest.approx(0.2)
+        assert usage.total_bytes_used == 400
+
+    def test_get_usage_after_delete(self, adapter_with_capacity):
+        adp = adapter_with_capacity
+        store_fd = adp.get_store_event_fd()
+
+        key = create_object_key(1)
+        obj = create_memory_obj(size=100, fill_value=1.0)
+
+        # Store
+        adp.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adp.pop_completed_store_tasks()
+
+        assert adp.get_usage().usage_fraction == pytest.approx(0.2)
+
+        # Delete
+        adp.delete([key])
+
+        assert adp.get_usage().usage_fraction == pytest.approx(0.0)
+        assert adp.get_usage().total_bytes_used == 0
+
+    def test_get_usage_store_delete_cycle(self, adapter_with_capacity):
+        adp = adapter_with_capacity
+        store_fd = adp.get_store_event_fd()
+
+        # Store 3 objects (3 * 400 = 1200 bytes)
+        keys = [create_object_key(i) for i in range(3)]
+        objs = [create_memory_obj(size=100, fill_value=float(i)) for i in range(3)]
+
+        adp.submit_store_task(keys, objs)
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adp.pop_completed_store_tasks()
+
+        usage = adp.get_usage()
+        assert usage.usage_fraction == pytest.approx(1200 / 2000)
+        assert usage.total_bytes_used == 1200
+
+        # Delete 2
+        adp.delete(keys[:2])
+
+        usage = adp.get_usage()
+        assert usage.usage_fraction == pytest.approx(400 / 2000)
+        assert usage.total_bytes_used == 400
+
+    def test_idempotent_store_no_double_count(self, adapter_with_capacity):
+        adp = adapter_with_capacity
+        store_fd = adp.get_store_event_fd()
+
+        key = create_object_key(1)
+        obj = create_memory_obj(size=100, fill_value=1.0)
+
+        # Store same key twice
+        adp.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adp.pop_completed_store_tasks()
+
+        adp.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adp.pop_completed_store_tasks()
+
+        # Should only count once
+        usage = adp.get_usage()
+        assert usage.usage_fraction == pytest.approx(0.2)
+        assert usage.total_bytes_used == 400
diff --git a/tests/v1/distributed/test_nixl_store_dynamic_l2_adapter.py b/tests/v1/distributed/test_nixl_store_dynamic_l2_adapter.py
new file mode 100644
index 0000000..4365f22
--- /dev/null
+++ b/tests/v1/distributed/test_nixl_store_dynamic_l2_adapter.py
@@ -0,0 +1,869 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for DynamicNixlStoreL2Adapter with POSIX backend.
+
+Tests cover the L2AdapterInterface contract, dynamic file operations,
+persist, secondary lookup, and capacity management.
+"""
+
+# Standard
+import os
+import select
+import shutil
+import tempfile
+
+# Third Party
+import pytest
+import torch
+
+nixl = pytest.importorskip("nixl")
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey  # noqa: E402
+from lmcache.v1.distributed.internal_api import (  # noqa: E402
+    L1MemoryDesc,
+    L2AdapterListener,
+)
+from lmcache.v1.distributed.l2_adapters.config import PersistConfig  # noqa: E402
+from lmcache.v1.distributed.l2_adapters.nixl_store_dynamic_l2_adapter import (  # noqa: E402
+    DynamicNixlStoreL2Adapter,
+    DynamicNixlStoreL2AdapterConfig,
+    _object_key_to_filename,
+)
+from lmcache.v1.memory_management import (  # noqa: E402
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd  # noqa: E402
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+
+class _RecordingListener(L2AdapterListener):
+    """Listener that records all events for inspection in tests."""
+
+    def __init__(self):
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        self.deleted.append(list(keys))
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+PAGE_SIZE = 4096  # 4 KB per page
+NUM_BUFFER_PAGES = 20  # pages in the registered memory buffer
+MAX_CAPACITY_GB = 0.001  # ~1 MB
+
+# =============================================================================
+# Test Helpers
+# =============================================================================
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(
+    buffer: torch.Tensor,
+    page_index: int,
+    fill_value: float = 1.0,
+    num_pages: int = 1,
+) -> TensorMemoryObj:
+    """Create a TensorMemoryObj that references page(s) in the registered buffer."""
+    obj_size = PAGE_SIZE * num_pages
+    start = page_index * PAGE_SIZE
+    end = start + obj_size
+    num_floats = obj_size // 4
+
+    raw_data = buffer[start:end].view(torch.float32)
+    raw_data.fill_(fill_value)
+
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([num_floats]),
+        dtype=torch.float32,
+        address=page_index * PAGE_SIZE,
+        phy_size=obj_size,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    """Wait for an event fd to be signaled."""
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def adapter():
+    """Create a DynamicNixlStoreL2Adapter with POSIX backend.
+
+    Yields (adapter, buffer) so tests can create memory objects that
+    reference pages inside the registered buffer.
+    """
+    tmp_dir = tempfile.mkdtemp(prefix="nixl_dyn_l2_test_")
+
+    buffer = torch.empty(PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu")
+
+    l1_memory = L1MemoryDesc(
+        ptr=buffer.data_ptr(),
+        size=buffer.numel(),
+        align_bytes=PAGE_SIZE,
+    )
+
+    config = DynamicNixlStoreL2AdapterConfig(
+        backend="POSIX",
+        backend_params={
+            "file_path": tmp_dir,
+            "use_direct_io": "false",
+            "max_capacity_gb": str(MAX_CAPACITY_GB),
+        },
+    )
+    adpt = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+    yield adpt, buffer, tmp_dir
+
+    adpt.close()
+    shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+@pytest.fixture
+def adapter_with_persist():
+    """Create a DynamicNixlStoreL2Adapter with persist enabled.
+
+    Yields (adapter, buffer, tmp_dir, l1_memory, config) and does NOT call
+    close() — tests manage the lifecycle themselves.
+    """
+    tmp_dir = tempfile.mkdtemp(prefix="nixl_dyn_l2_persist_test_")
+
+    buffer = torch.empty(PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu")
+
+    l1_memory = L1MemoryDesc(
+        ptr=buffer.data_ptr(),
+        size=buffer.numel(),
+        align_bytes=PAGE_SIZE,
+    )
+
+    config = DynamicNixlStoreL2AdapterConfig(
+        backend="POSIX",
+        backend_params={
+            "file_path": tmp_dir,
+            "use_direct_io": "false",
+            "max_capacity_gb": str(MAX_CAPACITY_GB),
+        },
+    )
+    config.persist_config = PersistConfig(persist_enabled=True)
+    adpt = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+    yield adpt, buffer, tmp_dir, l1_memory, config
+
+    shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+# =============================================================================
+# Event Fd Interface Tests
+# =============================================================================
+
+
+class TestEventFdInterface:
+    def test_get_store_event_fd_returns_valid_fd(self, adapter):
+        adpt, _, _ = adapter
+        fd = adpt.get_store_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_get_lookup_and_lock_event_fd_returns_valid_fd(self, adapter):
+        adpt, _, _ = adapter
+        fd = adpt.get_lookup_and_lock_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_get_load_event_fd_returns_valid_fd(self, adapter):
+        adpt, _, _ = adapter
+        fd = adpt.get_load_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_event_fds_are_different(self, adapter):
+        adpt, _, _ = adapter
+        fds = {
+            adpt.get_store_event_fd(),
+            adpt.get_lookup_and_lock_event_fd(),
+            adpt.get_load_event_fd(),
+        }
+        assert len(fds) == 3
+
+
+# =============================================================================
+# Store Interface Tests
+# =============================================================================
+
+
+class TestStoreInterface:
+    def test_submit_store_task_returns_task_id(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        task_id = adpt.submit_store_task([key], [obj])
+        assert isinstance(task_id, int)
+
+    def test_submit_store_task_signals_event_fd(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        assert wait_for_event_fd(adpt.get_store_event_fd())
+
+    def test_pop_completed_store_tasks_returns_completed(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        task_id = adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+
+        completed = adpt.pop_completed_store_tasks()
+        assert task_id in completed
+        assert completed[task_id].is_successful()
+
+    def test_store_creates_file_on_disk(self, adapter):
+        adpt, buf, tmp_dir = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+
+        expected_file = os.path.join(tmp_dir, _object_key_to_filename(key))
+        assert os.path.exists(expected_file)
+
+    def test_submit_multiple_store_tasks_unique_ids(self, adapter):
+        adpt, buf, _ = adapter
+        key1 = create_object_key(1)
+        key2 = create_object_key(2)
+        obj1 = create_memory_obj(buf, page_index=0)
+        obj2 = create_memory_obj(buf, page_index=1)
+
+        task_id1 = adpt.submit_store_task([key1], [obj1])
+        task_id2 = adpt.submit_store_task([key2], [obj2])
+        assert task_id1 != task_id2
+
+
+# =============================================================================
+# Lookup and Lock Interface Tests
+# =============================================================================
+
+
+class TestLookupAndLockInterface:
+    def test_lookup_nonexistent_key_returns_zeros(self, adapter):
+        adpt, _, _ = adapter
+        key = create_object_key(999)
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert not bitmap.test(0)
+
+    def test_lookup_existing_key_returns_ones(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        # Store first
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        # Lookup
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        # Unlock
+        adpt.submit_unlock([key])
+
+    def test_query_lookup_result_clears_result(self, adapter):
+        adpt, _, _ = adapter
+        key = create_object_key(1)
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+
+        result1 = adpt.query_lookup_and_lock_result(task_id)
+        result2 = adpt.query_lookup_and_lock_result(task_id)
+        assert result1 is not None
+        assert result2 is None
+
+
+# =============================================================================
+# Load Interface Tests
+# =============================================================================
+
+
+class TestLoadInterface:
+    def test_load_existing_key_copies_data(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=42.0)
+
+        # Store
+        adpt.submit_store_task([key], [store_obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        # Lookup and lock
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Load into a different page
+        load_obj = create_memory_obj(buf, page_index=1, fill_value=0.0)
+        task_id = adpt.submit_load_task([key], [load_obj])
+        wait_for_event_fd(adpt.get_load_event_fd())
+
+        bitmap = adpt.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        # Verify data was copied
+        loaded_data = buf[PAGE_SIZE : 2 * PAGE_SIZE].view(torch.float32)
+        assert torch.all(loaded_data == 42.0)
+
+        adpt.submit_unlock([key])
+
+    def test_load_multiple_keys_concurrent(self, adapter):
+        """A multi-key load task reads every chunk correctly.
+
+        Exercises the concurrent (gather-based) load loop: store several
+        keys, then load them all in a single task and verify each landed in
+        its own page with the right data.
+        """
+        adpt, buf, _ = adapter
+        keys = [create_object_key(i) for i in range(1, 4)]
+        fills = [11.0, 22.0, 33.0]
+        store_objs = [
+            create_memory_obj(buf, page_index=i, fill_value=fills[i]) for i in range(3)
+        ]
+
+        # Store all three
+        adpt.submit_store_task(keys, store_objs)
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        # Lookup and lock
+        task_id = adpt.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Load all three into separate pages (3, 4, 5) in ONE task
+        load_objs = [
+            create_memory_obj(buf, page_index=3 + i, fill_value=0.0) for i in range(3)
+        ]
+        task_id = adpt.submit_load_task(keys, load_objs)
+        wait_for_event_fd(adpt.get_load_event_fd())
+
+        bitmap = adpt.query_load_result(task_id)
+        assert bitmap is not None
+        for i in range(3):
+            assert bitmap.test(i)
+            page = 3 + i
+            loaded = buf[page * PAGE_SIZE : (page + 1) * PAGE_SIZE].view(torch.float32)
+            assert torch.all(loaded == fills[i])
+
+        adpt.submit_unlock(keys)
+
+    def test_load_partial_failure_marks_only_successful(self, adapter):
+        """One chunk's failure must not discard the others in the same task.
+
+        With ``asyncio.gather(..., return_exceptions=True)``, a single failed
+        load (here: its backing file is removed) is reported as failed for
+        that key while the sibling keys still load successfully.
+        """
+        adpt, buf, tmp_dir = adapter
+        keys = [create_object_key(i) for i in range(1, 4)]
+        fills = [11.0, 22.0, 33.0]
+        store_objs = [
+            create_memory_obj(buf, page_index=i, fill_value=fills[i]) for i in range(3)
+        ]
+
+        adpt.submit_store_task(keys, store_objs)
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        task_id = adpt.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Sabotage the middle key's backing file so its load raises.
+        os.remove(os.path.join(tmp_dir, _object_key_to_filename(keys[1])))
+
+        load_objs = [
+            create_memory_obj(buf, page_index=3 + i, fill_value=0.0) for i in range(3)
+        ]
+        task_id = adpt.submit_load_task(keys, load_objs)
+        wait_for_event_fd(adpt.get_load_event_fd())
+
+        bitmap = adpt.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0)  # loaded ok
+        assert not bitmap.test(1)  # file removed -> failed, not crashed
+        assert bitmap.test(2)  # loaded ok despite sibling failure
+
+        # The two successful loads landed correct data.
+        for i in (0, 2):
+            page = 3 + i
+            loaded = buf[page * PAGE_SIZE : (page + 1) * PAGE_SIZE].view(torch.float32)
+            assert torch.all(loaded == fills[i])
+
+        adpt.submit_unlock(keys)
+
+    def test_query_load_result_clears_result(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=1.0)
+
+        adpt.submit_store_task([key], [store_obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        adpt.query_lookup_and_lock_result(task_id)
+
+        load_obj = create_memory_obj(buf, page_index=1)
+        task_id = adpt.submit_load_task([key], [load_obj])
+        wait_for_event_fd(adpt.get_load_event_fd())
+
+        result1 = adpt.query_load_result(task_id)
+        result2 = adpt.query_load_result(task_id)
+        assert result1 is not None
+        assert result2 is None
+
+        adpt.submit_unlock([key])
+
+
+# =============================================================================
+# Store-Lookup-Load End-to-End Test
+# =============================================================================
+
+
+class TestEndToEnd:
+    def test_store_lookup_load_workflow(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=99.0)
+
+        # Store
+        store_task = adpt.submit_store_task([key], [store_obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        completed = adpt.pop_completed_store_tasks()
+        assert completed[store_task].is_successful()
+
+        # Lookup
+        lookup_task = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        bitmap = adpt.query_lookup_and_lock_result(lookup_task)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        # Load into different page
+        load_obj = create_memory_obj(buf, page_index=2, fill_value=0.0)
+        load_task = adpt.submit_load_task([key], [load_obj])
+        wait_for_event_fd(adpt.get_load_event_fd())
+        bitmap = adpt.query_load_result(load_task)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        # Verify
+        loaded = buf[2 * PAGE_SIZE : 3 * PAGE_SIZE].view(torch.float32)
+        assert torch.all(loaded == 99.0)
+
+        # Unlock
+        adpt.submit_unlock([key])
+
+
+# =============================================================================
+# Eviction / Delete Interface Tests
+# =============================================================================
+
+
+class TestEvictionInterface:
+    def test_delete_removes_key(self, adapter):
+        adpt, buf, tmp_dir = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        # Delete
+        adpt.delete([key])
+
+        # Lookup should miss
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert not bitmap.test(0)
+
+        # File should be removed from disk
+        expected_file = os.path.join(tmp_dir, _object_key_to_filename(key))
+        assert not os.path.exists(expected_file)
+
+    def test_delete_skips_pinned_key(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        # Lock
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Delete should skip pinned key
+        adpt.delete([key])
+
+        # Should still be found
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        adpt.submit_unlock([key])
+        adpt.submit_unlock([key])
+
+    def test_listener_notified_on_store(self, adapter):
+        adpt, buf, _ = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        assert len(listener.stored) == 1
+        assert key in listener.stored[0]
+
+    def test_listener_notified_on_delete(self, adapter):
+        adpt, buf, _ = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        adpt.delete([key])
+
+        assert len(listener.deleted) == 1
+        assert key in listener.deleted[0]
+
+
+# =============================================================================
+# Capacity / Usage Tests
+# =============================================================================
+
+
+class TestCapacity:
+    def test_get_usage_empty_is_zero(self, adapter):
+        adpt, _, _ = adapter
+        usage = adpt.get_usage()
+        assert usage.usage_fraction == 0.0
+
+    def test_get_usage_increases_after_store(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        usage = adpt.get_usage()
+        assert usage.usage_fraction > 0.0
+
+    def test_get_usage_decreases_after_delete(self, adapter):
+        adpt, buf, _ = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        usage_before = adpt.get_usage().usage_fraction
+        adpt.delete([key])
+        usage_after = adpt.get_usage().usage_fraction
+
+        assert usage_after < usage_before
+
+    def test_store_rejected_when_capacity_exceeded(self):
+        """Store should stop when max capacity is reached."""
+        tmp_dir = tempfile.mkdtemp(prefix="nixl_dyn_cap_test_")
+        try:
+            buffer = torch.empty(
+                PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu"
+            )
+            l1_memory = L1MemoryDesc(
+                ptr=buffer.data_ptr(),
+                size=buffer.numel(),
+                align_bytes=PAGE_SIZE,
+            )
+            # Very small capacity: 1 page worth of data
+            tiny_cap_gb = PAGE_SIZE / (1024**3)
+            config = DynamicNixlStoreL2AdapterConfig(
+                backend="POSIX",
+                backend_params={
+                    "file_path": tmp_dir,
+                    "use_direct_io": "false",
+                    "max_capacity_gb": str(tiny_cap_gb),
+                },
+            )
+            adpt = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+            # Store first object (should succeed)
+            key1 = create_object_key(1)
+            obj1 = create_memory_obj(buffer, page_index=0)
+            adpt.submit_store_task([key1], [obj1])
+            wait_for_event_fd(adpt.get_store_event_fd())
+
+            # Store second object (should be rejected due to capacity)
+            key2 = create_object_key(2)
+            obj2 = create_memory_obj(buffer, page_index=1)
+            adpt.submit_store_task([key2], [obj2])
+            wait_for_event_fd(adpt.get_store_event_fd())
+
+            # Only first key should be found
+            task_id = adpt.submit_lookup_and_lock_task([key1, key2], _EMPTY_LAYOUT)
+            wait_for_event_fd(adpt.get_lookup_and_lock_event_fd())
+            bitmap = adpt.query_lookup_and_lock_result(task_id)
+            assert bitmap is not None
+            assert bitmap.test(0)  # key1 found
+            assert not bitmap.test(1)  # key2 not found
+
+            adpt.submit_unlock([key1])
+            adpt.close()
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+# =============================================================================
+# Persist / Secondary Lookup Tests
+# =============================================================================
+
+
+class TestPersistAndSecondaryLookup:
+    def test_persist_keeps_files_on_close(self, adapter_with_persist):
+        """With persist_enabled=True, data files remain on disk after close."""
+        adpt, buf, tmp_dir, _, _ = adapter_with_persist
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        data_file = os.path.join(tmp_dir, _object_key_to_filename(key))
+        assert os.path.exists(data_file)
+
+        adpt.close()
+
+        assert os.path.exists(data_file)
+
+    def test_secondary_lookup_finds_key(self, adapter_with_persist):
+        """Lookup finds keys whose files exist on disk via secondary lookup."""
+        adpt, buf, _, l1_memory, config = adapter_with_persist
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0, fill_value=77.0)
+
+        # Store and close (files are kept)
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+        adpt.close()
+
+        # New adapter — secondary lookup discovers the persisted file
+        adpt2 = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+        # Lookup should find the key via secondary lookup
+        task_id = adpt2.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt2.get_lookup_and_lock_event_fd())
+        bitmap = adpt2.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        adpt2.submit_unlock([key])
+        adpt2.close()
+
+    def test_secondary_lookup_and_load_data(self, adapter_with_persist):
+        """After secondary lookup, load returns the same data that was stored."""
+        adpt, buf, _, l1_memory, config = adapter_with_persist
+        key = create_object_key(1)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=55.0)
+
+        adpt.submit_store_task([key], [store_obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+        adpt.close()
+
+        adpt2 = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+        # Lookup (lazy recover) + load
+        task_id = adpt2.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt2.get_lookup_and_lock_event_fd())
+        adpt2.query_lookup_and_lock_result(task_id)
+
+        load_obj = create_memory_obj(buf, page_index=2, fill_value=0.0)
+        task_id = adpt2.submit_load_task([key], [load_obj])
+        wait_for_event_fd(adpt2.get_load_event_fd())
+        bitmap = adpt2.query_load_result(task_id)
+        assert bitmap is not None
+        assert bitmap.test(0)
+
+        loaded = buf[2 * PAGE_SIZE : 3 * PAGE_SIZE].view(torch.float32)
+        assert torch.all(loaded == 55.0)
+
+        adpt2.submit_unlock([key])
+        adpt2.close()
+
+    def test_secondary_lookup_misses_when_file_deleted(self, adapter_with_persist):
+        """Secondary lookup returns miss for keys whose files are absent on disk."""
+        adpt, buf, tmp_dir, l1_memory, config = adapter_with_persist
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+        adpt.close()
+
+        # Delete the data file manually
+        data_file = os.path.join(tmp_dir, _object_key_to_filename(key))
+        os.unlink(data_file)
+
+        adpt2 = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+        task_id = adpt2.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt2.get_lookup_and_lock_event_fd())
+        bitmap = adpt2.query_lookup_and_lock_result(task_id)
+        assert bitmap is not None
+        assert not bitmap.test(0)
+
+        adpt2.close()
+
+    def test_secondary_lookup_usage_updates(self, adapter_with_persist):
+        """Secondary lookup populates _total_bytes so get_usage reflects disk files."""
+        adpt, buf, _, l1_memory, config = adapter_with_persist
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(adpt.get_store_event_fd())
+        adpt.pop_completed_store_tasks()
+
+        usage_before = adpt.get_usage().usage_fraction
+        adpt.close()
+
+        # Right after init, usage is zero (no eager recovery)
+        adpt2 = DynamicNixlStoreL2Adapter(config, l1_memory)
+        usage_initial = adpt2.get_usage().usage_fraction
+        assert usage_initial == 0.0
+
+        # After a lookup, the key is populated and usage matches
+        task_id = adpt2.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adpt2.get_lookup_and_lock_event_fd())
+        adpt2.query_lookup_and_lock_result(task_id)
+
+        usage_after = adpt2.get_usage().usage_fraction
+        assert usage_after == pytest.approx(usage_before, rel=1e-6)
+
+        adpt2.submit_unlock([key])
+        adpt2.close()
+
+    def test_close_without_persist_deletes_files(self):
+        """With persist_enabled=False, close() deletes all data files."""
+        tmp_dir = tempfile.mkdtemp(prefix="nixl_dyn_cleanup_test_")
+        try:
+            buffer = torch.empty(
+                PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu"
+            )
+            l1_memory = L1MemoryDesc(
+                ptr=buffer.data_ptr(),
+                size=buffer.numel(),
+                align_bytes=PAGE_SIZE,
+            )
+            config = DynamicNixlStoreL2AdapterConfig(
+                backend="POSIX",
+                backend_params={
+                    "file_path": tmp_dir,
+                    "use_direct_io": "false",
+                    "max_capacity_gb": str(MAX_CAPACITY_GB),
+                },
+            )
+            config.persist_config = PersistConfig(persist_enabled=False)
+            adpt = DynamicNixlStoreL2Adapter(config, l1_memory)
+
+            key = create_object_key(1)
+            obj = create_memory_obj(buffer, page_index=0)
+            adpt.submit_store_task([key], [obj])
+            wait_for_event_fd(adpt.get_store_event_fd())
+            adpt.pop_completed_store_tasks()
+
+            data_file = os.path.join(tmp_dir, _object_key_to_filename(key))
+            assert os.path.exists(data_file)
+
+            adpt.close()
+
+            assert not os.path.exists(data_file)
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
diff --git a/tests/v1/distributed/test_nixl_store_l2_adapter.py b/tests/v1/distributed/test_nixl_store_l2_adapter.py
new file mode 100644
index 0000000..51a8028
--- /dev/null
+++ b/tests/v1/distributed/test_nixl_store_l2_adapter.py
@@ -0,0 +1,1068 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for NixlStoreL2Adapter with POSIX backend.
+
+Tests are written based on the L2AdapterInterface contract defined in base.py.
+Tests only use public methods and do not access private fields.
+"""
+
+# Standard
+import select
+import shutil
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+nixl = pytest.importorskip("nixl")
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey  # noqa: E402
+from lmcache.v1.distributed.internal_api import (  # noqa: E402
+    L1MemoryDesc,
+    L2AdapterListener,
+)
+from lmcache.v1.distributed.l2_adapters.nixl_store_l2_adapter import (  # noqa: E402
+    NixlStoreL2Adapter,
+    NixlStoreL2AdapterConfig,
+)
+
+
+class _RecordingListener(L2AdapterListener):
+    """Listener that records all events for inspection in tests."""
+
+    def __init__(self):
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        self.deleted.append(list(keys))
+
+
+# First Party
+from lmcache.v1.memory_management import (  # noqa: E402
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd  # noqa: E402
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+PAGE_SIZE = 4096  # 4 KB per page
+NUM_BUFFER_PAGES = 20  # pages in the registered memory buffer
+POOL_SIZE = 20  # number of storage descriptors to pre-allocate
+
+# =============================================================================
+# Test Helpers
+# =============================================================================
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(
+    buffer: torch.Tensor,
+    page_index: int,
+    fill_value: float = 1.0,
+    num_pages: int = 1,
+) -> TensorMemoryObj:
+    """Create a TensorMemoryObj that references page(s) in the registered buffer.
+
+    Args:
+        buffer: The flat uint8 buffer registered with NIXL.
+        page_index: Starting page in the buffer this object occupies.
+        fill_value: Value to fill the tensor with.
+        num_pages: Number of contiguous pages this object spans.
+    """
+    obj_size = PAGE_SIZE * num_pages
+    start = page_index * PAGE_SIZE
+    end = start + obj_size
+    num_floats = obj_size // 4
+
+    raw_data = buffer[start:end].view(torch.float32)
+    raw_data.fill_(fill_value)
+
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([num_floats]),
+        dtype=torch.float32,
+        address=page_index * PAGE_SIZE,
+        phy_size=obj_size,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    """Wait for an event fd to be signaled.
+
+    Returns True if signaled within timeout, False otherwise.
+    """
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)  # timeout in milliseconds
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def adapter():
+    """Create a NixlStoreL2Adapter with POSIX backend and an initialized
+    memory buffer.
+
+    Yields (adapter, buffer) so tests can create memory objects that
+    reference pages inside the registered buffer.
+    """
+    tmp_dir = tempfile.mkdtemp(prefix="nixl_l2_test_")
+
+    # Allocate a contiguous CPU buffer first so we can pass it to the adapter
+    buffer = torch.empty(PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu")
+
+    l1_memory = L1MemoryDesc(
+        ptr=buffer.data_ptr(),
+        size=buffer.numel(),
+        align_bytes=PAGE_SIZE,
+    )
+
+    config = NixlStoreL2AdapterConfig(
+        backend="POSIX",
+        backend_params={"file_path": tmp_dir, "use_direct_io": "false"},
+        pool_size=POOL_SIZE,
+    )
+    adapter = NixlStoreL2Adapter(config, l1_memory)
+
+    yield adapter, buffer
+
+    adapter.close()
+    shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+# =============================================================================
+# Event Fd Interface Tests
+# =============================================================================
+
+
+class TestEventFdInterface:
+    """Test the event fd interface methods."""
+
+    def test_get_store_event_fd_returns_valid_fd(self, adapter):
+        """get_store_event_fd should return a valid file descriptor."""
+        adpt, _ = adapter
+        fd = adpt.get_store_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_get_lookup_and_lock_event_fd_returns_valid_fd(self, adapter):
+        """get_lookup_and_lock_event_fd should return a valid file descriptor."""
+        adpt, _ = adapter
+        fd = adpt.get_lookup_and_lock_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_get_load_event_fd_returns_valid_fd(self, adapter):
+        """get_load_event_fd should return a valid file descriptor."""
+        adpt, _ = adapter
+        fd = adpt.get_load_event_fd()
+        assert isinstance(fd, int)
+        assert fd >= 0
+
+    def test_event_fds_are_different(self, adapter):
+        """Each operation should have a distinct event fd."""
+        adpt, _ = adapter
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+        load_fd = adpt.get_load_event_fd()
+
+        assert store_fd != lookup_fd
+        assert store_fd != load_fd
+        assert lookup_fd != load_fd
+
+
+# =============================================================================
+# Store Interface Tests
+# =============================================================================
+
+
+class TestStoreInterface:
+    """Test the store operation interface."""
+
+    def test_submit_store_task_returns_task_id(self, adapter):
+        """submit_store_task should return a valid task ID."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        task_id = adpt.submit_store_task([key], [obj])
+
+        assert isinstance(task_id, int)
+
+    def test_submit_store_task_signals_event_fd(self, adapter):
+        """Store completion should signal the store event fd."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+
+        adpt.submit_store_task([key], [obj])
+
+        assert wait_for_event_fd(store_fd, timeout=5.0), (
+            "Store event fd was not signaled within timeout"
+        )
+
+    def test_pop_completed_store_tasks_returns_completed(self, adapter):
+        """pop_completed_store_tasks should return completed tasks
+        with success status.
+        """
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+
+        task_id = adpt.submit_store_task([key], [obj])
+
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed = adpt.pop_completed_store_tasks()
+
+        assert task_id in completed
+        assert completed[task_id].is_successful()
+
+    def test_pop_completed_store_tasks_clears_completed(self, adapter):
+        """pop_completed_store_tasks should clear the completed tasks."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+
+        # First pop should return the task
+        completed1 = adpt.pop_completed_store_tasks()
+        assert len(completed1) == 1
+
+        # Second pop should return empty
+        completed2 = adpt.pop_completed_store_tasks()
+        assert len(completed2) == 0
+
+    def test_submit_multiple_store_tasks(self, adapter):
+        """Multiple store tasks should each get unique task IDs."""
+        adpt, buf = adapter
+        keys = [create_object_key(i) for i in range(3)]
+        objs = [
+            create_memory_obj(buf, page_index=i, fill_value=float(i)) for i in range(3)
+        ]
+        store_fd = adpt.get_store_event_fd()
+
+        task_ids = []
+        for key, obj in zip(keys, objs, strict=False):
+            task_id = adpt.submit_store_task([key], [obj])
+            task_ids.append(task_id)
+
+        # All task IDs should be unique
+        assert len(set(task_ids)) == 3
+
+        # Wait for all completions
+        completed = {}
+        while len(completed) < 3:
+            wait_for_event_fd(store_fd, timeout=5.0)
+            completed.update(adpt.pop_completed_store_tasks())
+
+        for task_id in task_ids:
+            assert task_id in completed
+            assert completed[task_id].is_successful()
+
+    def test_store_batch_of_objects(self, adapter):
+        """A single store task can store multiple key-object pairs."""
+        adpt, buf = adapter
+        keys = [create_object_key(i) for i in range(5)]
+        objs = [
+            create_memory_obj(buf, page_index=i, fill_value=float(i)) for i in range(5)
+        ]
+        store_fd = adpt.get_store_event_fd()
+
+        task_id = adpt.submit_store_task(keys, objs)
+
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+
+        completed = adpt.pop_completed_store_tasks()
+        assert task_id in completed
+        assert completed[task_id].is_successful()
+
+
+# =============================================================================
+# Lookup and Lock Interface Tests
+# =============================================================================
+
+
+class TestLookupAndLockInterface:
+    """Test the lookup and lock operation interface."""
+
+    def test_submit_lookup_returns_task_id(self, adapter):
+        """submit_lookup_and_lock_task should return a valid task ID."""
+        adpt, _ = adapter
+        key = create_object_key(1)
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+
+        assert isinstance(task_id, int)
+
+    def test_lookup_signals_event_fd(self, adapter):
+        """Lookup completion should signal the lookup event fd."""
+        adpt, _ = adapter
+        key = create_object_key(1)
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+
+        assert wait_for_event_fd(lookup_fd, timeout=5.0), (
+            "Lookup event fd was not signaled within timeout"
+        )
+
+    def test_lookup_nonexistent_key_returns_bitmap_with_zeros(self, adapter):
+        """Looking up a non-existent key should return a bitmap with 0."""
+        adpt, _ = adapter
+        key = create_object_key(999)  # Never stored
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is False  # Key not found
+
+    def test_lookup_existing_key_returns_bitmap_with_ones(self, adapter):
+        """Looking up an existing key should return a bitmap with 1."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        # First store the object
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Now lookup
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is True  # Key found
+
+    def test_lookup_mixed_keys(self, adapter):
+        """Lookup of mixed existing/non-existing keys returns correct bitmap."""
+        adpt, buf = adapter
+        existing_key = create_object_key(1)
+        nonexistent_key = create_object_key(999)
+        obj = create_memory_obj(buf, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        # Store only one key
+        adpt.submit_store_task([existing_key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Lookup both keys
+        task_id = adpt.submit_lookup_and_lock_task(
+            [existing_key, nonexistent_key], _EMPTY_LAYOUT
+        )
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is True  # existing_key found
+        assert bitmap.test(1) is False  # nonexistent_key not found
+
+    def test_query_lookup_result_returns_none_for_unknown_task(self, adapter):
+        """Querying an unknown task ID should return None."""
+        adpt, _ = adapter
+        result = adpt.query_lookup_and_lock_result(99999)
+        assert result is None
+
+    def test_query_lookup_result_clears_result(self, adapter):
+        """Querying lookup result should remove it (can only query once)."""
+        adpt, _ = adapter
+        key = create_object_key(1)
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+
+        # First query returns result
+        result1 = adpt.query_lookup_and_lock_result(task_id)
+        assert result1 is not None
+
+        # Second query returns None
+        result2 = adpt.query_lookup_and_lock_result(task_id)
+        assert result2 is None
+
+
+# =============================================================================
+# Unlock Interface Tests
+# =============================================================================
+
+
+class TestUnlockInterface:
+    """Test the unlock operation interface."""
+
+    def test_submit_unlock_does_not_raise(self, adapter):
+        """submit_unlock should not raise an exception."""
+        adpt, _ = adapter
+        key = create_object_key(1)
+
+        # Should not raise even for non-existent key
+        adpt.submit_unlock([key])
+
+    def test_unlock_after_lock(self, adapter):
+        """Unlocking after locking should work without error."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        # Store
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Lookup and lock
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(lookup_fd, timeout=5.0)
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Unlock should not raise
+        adpt.submit_unlock([key])
+
+
+# =============================================================================
+# Load Interface Tests
+# =============================================================================
+
+
+class TestLoadInterface:
+    """Test the load operation interface."""
+
+    def test_submit_load_task_returns_task_id(self, adapter):
+        """submit_load_task should return a valid task ID."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        task_id = adpt.submit_load_task([key], [obj])
+
+        assert isinstance(task_id, int)
+
+    def test_load_signals_event_fd(self, adapter):
+        """Load completion should signal the load event fd."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        load_fd = adpt.get_load_event_fd()
+
+        adpt.submit_load_task([key], [obj])
+
+        assert wait_for_event_fd(load_fd, timeout=5.0), (
+            "Load event fd was not signaled within timeout"
+        )
+
+    def test_load_nonexistent_key_returns_bitmap_with_zeros(self, adapter):
+        """Loading a non-existent key should return a bitmap with 0."""
+        adpt, buf = adapter
+        key = create_object_key(999)  # Never stored
+        obj = create_memory_obj(buf, page_index=0)
+        load_fd = adpt.get_load_event_fd()
+
+        task_id = adpt.submit_load_task([key], [obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        bitmap = adpt.query_load_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is False  # Load failed
+
+    def test_load_existing_key_copies_data(self, adapter):
+        """Loading an existing key should copy data to the provided buffer."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+
+        # Store from page 0 (filled with 42.0)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=42.0)
+        store_fd = adpt.get_store_event_fd()
+        load_fd = adpt.get_load_event_fd()
+
+        adpt.submit_store_task([key], [store_obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Load into page 1 (initially filled with 0.0)
+        load_obj = create_memory_obj(buf, page_index=1, fill_value=0.0)
+        task_id = adpt.submit_load_task([key], [load_obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        bitmap = adpt.query_load_result(task_id)
+
+        assert bitmap is not None
+        assert bitmap.test(0) is True  # Load succeeded
+
+        # Data should be copied
+        assert torch.all(load_obj.raw_data == 42.0)
+
+    def test_query_load_result_returns_none_for_unknown_task(self, adapter):
+        """Querying an unknown task ID should return None."""
+        adpt, _ = adapter
+        result = adpt.query_load_result(99999)
+        assert result is None
+
+    def test_query_load_result_clears_result(self, adapter):
+        """Querying load result should remove it (can only query once)."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        load_fd = adpt.get_load_event_fd()
+
+        task_id = adpt.submit_load_task([key], [obj])
+        wait_for_event_fd(load_fd, timeout=5.0)
+
+        # First query returns result
+        result1 = adpt.query_load_result(task_id)
+        assert result1 is not None
+
+        # Second query returns None
+        result2 = adpt.query_load_result(task_id)
+        assert result2 is None
+
+
+# =============================================================================
+# End-to-End Workflow Tests
+# =============================================================================
+
+
+class TestEndToEndWorkflow:
+    """Test complete store-lookup-load workflows."""
+
+    def test_store_lookup_load_workflow(self, adapter):
+        """Test the complete workflow: store -> lookup -> load."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+        load_fd = adpt.get_load_event_fd()
+
+        # Step 1: Store from page 0 (filled with 123.0)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=123.0)
+        store_task_id = adpt.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        completed = adpt.pop_completed_store_tasks()
+        assert completed[store_task_id].is_successful()
+
+        # Step 2: Lookup and lock
+        lookup_task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        lookup_bitmap = adpt.query_lookup_and_lock_result(lookup_task_id)
+        assert lookup_bitmap.test(0) is True
+
+        # Step 3: Load into page 1 (initially 0.0)
+        load_obj = create_memory_obj(buf, page_index=1, fill_value=0.0)
+        load_task_id = adpt.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        load_bitmap = adpt.query_load_result(load_task_id)
+        assert load_bitmap.test(0) is True
+
+        # Verify data
+        assert torch.all(load_obj.raw_data == 123.0)
+
+        # Step 4: Unlock
+        adpt.submit_unlock([key])
+
+    def test_multi_page_object_workflow(self, adapter):
+        """Test store-lookup-load with an object spanning multiple pages."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        num_pages = 3
+
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+        load_fd = adpt.get_load_event_fd()
+
+        # Store a 3-page object starting at page 0
+        store_obj = create_memory_obj(
+            buf, page_index=0, fill_value=77.0, num_pages=num_pages
+        )
+        store_task_id = adpt.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        completed = adpt.pop_completed_store_tasks()
+        assert completed[store_task_id].is_successful()
+
+        # Lookup
+        lookup_task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        lookup_bitmap = adpt.query_lookup_and_lock_result(lookup_task_id)
+        assert lookup_bitmap.test(0) is True
+
+        # Load into pages 10..12 (initially 0.0)
+        load_obj = create_memory_obj(
+            buf, page_index=10, fill_value=0.0, num_pages=num_pages
+        )
+        load_task_id = adpt.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        load_bitmap = adpt.query_load_result(load_task_id)
+        assert load_bitmap.test(0) is True
+
+        # All 3 pages should contain 77.0
+        assert torch.all(load_obj.raw_data == 77.0)
+
+        adpt.submit_unlock([key])
+
+    def test_multiple_objects_workflow(self, adapter):
+        """Test workflow with multiple objects."""
+        adpt, buf = adapter
+        num_objects = 5
+
+        keys = [create_object_key(i) for i in range(num_objects)]
+
+        store_fd = adpt.get_store_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+        load_fd = adpt.get_load_event_fd()
+
+        # Store all (pages 0..4, each filled with i * 10.0)
+        store_objs = [
+            create_memory_obj(buf, page_index=i, fill_value=float(i * 10))
+            for i in range(num_objects)
+        ]
+        store_task_id = adpt.submit_store_task(keys, store_objs)
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        completed = adpt.pop_completed_store_tasks()
+        assert completed[store_task_id].is_successful()
+
+        # Lookup all
+        lookup_task_id = adpt.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        lookup_bitmap = adpt.query_lookup_and_lock_result(lookup_task_id)
+        for i in range(num_objects):
+            assert lookup_bitmap.test(i) is True
+
+        # Load all (pages 10..14, initially 0.0)
+        load_objs = [
+            create_memory_obj(buf, page_index=10 + i, fill_value=0.0)
+            for i in range(num_objects)
+        ]
+        load_task_id = adpt.submit_load_task(keys, load_objs)
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+        load_bitmap = adpt.query_load_result(load_task_id)
+        for i in range(num_objects):
+            assert load_bitmap.test(i) is True
+            assert torch.all(load_objs[i].raw_data == float(i * 10))
+
+
+# =============================================================================
+# Close Interface Tests
+# =============================================================================
+
+
+class TestCloseInterface:
+    """Test the close operation."""
+
+    def test_close_does_not_raise(self):
+        """close() should not raise an exception."""
+        tmp_dir = tempfile.mkdtemp(prefix="nixl_l2_close_test_")
+        buffer = torch.empty(
+            PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu"
+        )
+        l1_memory = L1MemoryDesc(
+            ptr=buffer.data_ptr(),
+            size=buffer.numel(),
+            align_bytes=PAGE_SIZE,
+        )
+        config = NixlStoreL2AdapterConfig(
+            backend="POSIX",
+            backend_params={"file_path": tmp_dir, "use_direct_io": "false"},
+            pool_size=POOL_SIZE,
+        )
+        adpt = NixlStoreL2Adapter(config, l1_memory)
+
+        # Should not raise
+        adpt.close()
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    def test_close_after_operations(self):
+        """close() should work after store/lookup/load operations."""
+        tmp_dir = tempfile.mkdtemp(prefix="nixl_l2_close_ops_test_")
+        buffer = torch.empty(
+            PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu"
+        )
+        l1_memory = L1MemoryDesc(
+            ptr=buffer.data_ptr(),
+            size=buffer.numel(),
+            align_bytes=PAGE_SIZE,
+        )
+        config = NixlStoreL2AdapterConfig(
+            backend="POSIX",
+            backend_params={"file_path": tmp_dir, "use_direct_io": "false"},
+            pool_size=POOL_SIZE,
+        )
+        adpt = NixlStoreL2Adapter(config, l1_memory)
+
+        key = create_object_key(1)
+        obj = create_memory_obj(buffer, page_index=0)
+        store_fd = adpt.get_store_event_fd()
+
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Should not raise
+        adpt.close()
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+# =============================================================================
+# Report Status Tests
+# =============================================================================
+
+
+class TestReportStatus:
+    """Tests for NixlStoreL2Adapter.report_status()."""
+
+    def test_report_status_shape(self, adapter):
+        """report_status() should return all expected keys with correct types."""
+        adpt, _ = adapter
+        status = adpt.report_status()
+
+        assert status["is_healthy"] is True
+        assert status["type"] == "NixlStoreL2Adapter"
+        assert status["backend"] == "POSIX"
+        assert isinstance(status["stored_object_count"], int)
+        assert isinstance(status["pinned_object_count"], int)
+        assert isinstance(status["pool_size"], int)
+        assert isinstance(status["pool_free_slots"], int)
+        assert isinstance(status["event_loop_alive"], bool)
+
+    def test_report_status_initial_state(self, adapter):
+        """Fresh adapter should report zero stored objects and full pool."""
+        adpt, _ = adapter
+        status = adpt.report_status()
+
+        assert status["stored_object_count"] == 0
+        assert status["pinned_object_count"] == 0
+        assert status["pool_size"] == POOL_SIZE
+        assert status["pool_free_slots"] > 0
+        assert status["event_loop_alive"] is True
+
+    def test_report_status_after_store(self, adapter):
+        """stored_object_count should increase after a store completes."""
+        adpt, buffer = adapter
+        store_fd = adpt.get_store_event_fd()
+
+        key = create_object_key(42)
+        obj = create_memory_obj(buffer, page_index=0)
+        adpt.submit_store_task([key], [obj])
+        wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        status = adpt.report_status()
+        assert status["stored_object_count"] == 1
+        assert status["pool_free_slots"] < status["pool_size"]
+
+    def test_report_status_after_close(self):
+        """is_healthy should become False after close()."""
+        tmp_dir = tempfile.mkdtemp(prefix="nixl_l2_status_test_")
+        buffer = torch.empty(
+            PAGE_SIZE * NUM_BUFFER_PAGES, dtype=torch.uint8, device="cpu"
+        )
+        l1_memory = L1MemoryDesc(
+            ptr=buffer.data_ptr(),
+            size=buffer.numel(),
+            align_bytes=PAGE_SIZE,
+        )
+        config = NixlStoreL2AdapterConfig(
+            backend="POSIX",
+            backend_params={"file_path": tmp_dir, "use_direct_io": "false"},
+            pool_size=POOL_SIZE,
+        )
+        adpt = NixlStoreL2Adapter(config, l1_memory)
+
+        # Healthy before close
+        assert adpt.report_status()["is_healthy"] is True
+
+        adpt.close()
+
+        # Unhealthy after close
+        status = adpt.report_status()
+        assert status["is_healthy"] is False
+        assert status["event_loop_alive"] is False
+
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+# =============================================================================
+# Eviction Interface Tests
+# =============================================================================
+
+
+def _store_and_wait(adpt, key, obj):
+    """Helper: store one key and wait for the store event fd to fire."""
+    store_fd = adpt.get_store_event_fd()
+    adpt.submit_store_task([key], [obj])
+    assert wait_for_event_fd(store_fd, timeout=5.0), "store timed out"
+    adpt.pop_completed_store_tasks()
+
+
+@pytest.mark.skip(
+    reason="Leaks file descriptors — "
+    "NixlStorageAgent.close() does not close os.open() FDs"
+)
+class TestEvictionInterface:
+    """Tests for delete(), get_usage(), and listener notifications."""
+
+    def test_delete_removes_key(self, adapter):
+        """delete() should make the key invisible to subsequent lookups."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        _store_and_wait(adpt, key, obj)
+
+        adpt.delete([key])
+
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        bitmap = adpt.query_lookup_and_lock_result(task_id)
+        assert bitmap.test(0) is False
+
+    def test_delete_nonexistent_key_does_not_raise(self, adapter):
+        """delete() on a key that was never stored should not raise."""
+        adpt, _ = adapter
+        adpt.delete([create_object_key(999)])
+
+    def test_delete_frees_pool_slot(self, adapter):
+        """delete() should release the storage pool slot back to the pool."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+
+        _store_and_wait(adpt, key, obj)
+        usage_after_store, _ = adpt.get_usage()
+        assert usage_after_store > 0.0
+
+        adpt.delete([key])
+
+        usage_after_delete, _ = adpt.get_usage()
+        assert usage_after_delete < usage_after_store
+
+    def test_get_usage_empty_adapter_is_zero(self, adapter):
+        """get_usage() on a fresh adapter should return (0.0, 0.0)."""
+        adpt, _ = adapter
+        current, projected = adpt.get_usage()
+        assert current == 0.0
+        assert projected == 0.0
+
+    def test_get_usage_increases_after_store(self, adapter):
+        """get_usage() current value should be > 0 after storing an object."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        _store_and_wait(adpt, key, obj)
+
+        current, _ = adpt.get_usage()
+        assert current > 0.0
+        assert current <= 1.0
+
+    def test_get_usage_reflects_multiple_stores(self, adapter):
+        """get_usage() should increase monotonically as more objects are stored."""
+        adpt, buf = adapter
+        store_fd = adpt.get_store_event_fd()
+
+        keys = [create_object_key(i) for i in range(3)]
+        objs = [create_memory_obj(buf, page_index=i) for i in range(3)]
+        adpt.submit_store_task(keys, objs)
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        current, _ = adpt.get_usage()
+        # 3 out of POOL_SIZE slots used
+        assert current == pytest.approx(3 / POOL_SIZE)
+
+    def test_delete_pinned_key_is_skipped(self, adapter):
+        """delete() should skip a key that is pinned by an in-flight lookup."""
+        adpt, buf = adapter
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        _store_and_wait(adpt, key, obj)
+
+        # Pin the key via lookup_and_lock
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # delete should skip the pinned key — stored_object_count stays 1
+        adpt.delete([key])
+        assert adpt.report_status()["stored_object_count"] == 1
+
+        # Unpin, then delete should succeed
+        adpt.submit_unlock([key])
+        time.sleep(0.1)  # let the unlock execute in the event loop
+        adpt.delete([key])
+        assert adpt.report_status()["stored_object_count"] == 0
+
+    def test_listener_notified_on_store(self, adapter):
+        """Listener.on_l2_keys_stored should be called after a store completes."""
+        adpt, buf = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        _store_and_wait(adpt, key, obj)
+
+        assert len(listener.stored) == 1
+        assert key in listener.stored[0]
+        assert listener.deleted == []
+
+    def test_listener_notified_on_load(self, adapter):
+        """Listener.on_l2_keys_accessed should be called after a load completes."""
+        adpt, buf = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        key = create_object_key(1)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=42.0)
+        store_fd = adpt.get_store_event_fd()
+        load_fd = adpt.get_load_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        # Store
+        adpt.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Lookup and lock (required before load)
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Load
+        load_obj = create_memory_obj(buf, page_index=1, fill_value=0.0)
+        adpt.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+
+        assert len(listener.accessed) == 1
+        assert key in listener.accessed[0]
+
+        adpt.submit_unlock([key])
+
+    def test_listener_load_skips_missing_keys(self, adapter):
+        """on_l2_keys_accessed should only include keys that were actually loaded."""
+        adpt, buf = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        real_key = create_object_key(1)
+        missing_key = create_object_key(999)
+        store_obj = create_memory_obj(buf, page_index=0, fill_value=42.0)
+        store_fd = adpt.get_store_event_fd()
+        load_fd = adpt.get_load_event_fd()
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        # Store only real_key
+        adpt.submit_store_task([real_key], [store_obj])
+        assert wait_for_event_fd(store_fd, timeout=5.0)
+        adpt.pop_completed_store_tasks()
+
+        # Lookup and lock
+        task_id = adpt.submit_lookup_and_lock_task([real_key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # Load both keys
+        load_obj1 = create_memory_obj(buf, page_index=1, fill_value=0.0)
+        load_obj2 = create_memory_obj(buf, page_index=2, fill_value=0.0)
+        adpt.submit_load_task([real_key, missing_key], [load_obj1, load_obj2])
+        assert wait_for_event_fd(load_fd, timeout=5.0)
+
+        assert len(listener.accessed) == 1
+        assert real_key in listener.accessed[0]
+        assert missing_key not in listener.accessed[0]
+
+        adpt.submit_unlock([real_key])
+
+    def test_listener_notified_on_delete(self, adapter):
+        """Listener.on_l2_keys_deleted should be called after delete()."""
+        adpt, buf = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        _store_and_wait(adpt, key, obj)
+        adpt.delete([key])
+
+        assert len(listener.deleted) == 1
+        assert key in listener.deleted[0]
+
+    def test_listener_delete_skips_pinned_key(self, adapter):
+        """
+        on_l2_keys_deleted should not include keys
+        that were skipped due to pinning.
+        """
+        adpt, buf = adapter
+        listener = _RecordingListener()
+        adpt.register_listener(listener)
+
+        key = create_object_key(1)
+        obj = create_memory_obj(buf, page_index=0)
+        lookup_fd = adpt.get_lookup_and_lock_event_fd()
+
+        _store_and_wait(adpt, key, obj)
+
+        # Pin via lookup
+        task_id = adpt.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd, timeout=5.0)
+        adpt.query_lookup_and_lock_result(task_id)
+
+        # delete while pinned — should be skipped
+        adpt.delete([key])
+
+        assert listener.deleted == []
diff --git a/tests/v1/distributed/test_object_key_parallel.py b/tests/v1/distributed/test_object_key_parallel.py
new file mode 100644
index 0000000..59bdc90
--- /dev/null
+++ b/tests/v1/distributed/test_object_key_parallel.py
@@ -0,0 +1,734 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for tensor parallel (TP) support in the multiprocess cache engine.
+
+This module tests the TP lookup mechanism where:
+- scheduler uses worker_id=None to lookup cache across all workers
+- workers use specific worker_id for store/retrieve operations
+- lookup requires ALL workers to have the cache for a hit
+
+Key scenarios tested:
+- TP=2 with both workers having all chunks cached
+- TP=2 with only one worker having cache (asymmetric)
+- TP=2 with different partial hits across workers
+- Various world sizes (TP=1, TP=2, TP=4, TP=8)
+"""
+
+# Standard
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+)
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+from lmcache.v1.memory_management import MemoryFormat
+
+# ==============================================================================
+# Test Fixtures
+# ==============================================================================
+
+
+@pytest.fixture
+def storage_manager():
+    """Create a storage manager with 1GB buffer for testing."""
+    l1_memory_config = L1MemoryManagerConfig(
+        size_in_bytes=1 << 30,
+        use_lazy=True,
+        init_size_in_bytes=1 << 30,
+    )
+    storage_manager_config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=l1_memory_config,
+        ),
+        eviction_config=EvictionConfig(
+            eviction_policy="LRU",
+        ),
+    )
+    manager = StorageManager(config=storage_manager_config)
+    yield manager
+    manager.close()
+
+
+@pytest.fixture
+def test_shape():
+    """Standard test shape for tensors."""
+    return torch.Size((2, 16, 16, 128))
+
+
+@pytest.fixture
+def test_dtype():
+    """Standard test dtype for tensors."""
+    return torch.float16
+
+
+@pytest.fixture
+def test_layout(test_shape, test_dtype):
+    return MemoryLayoutDesc(
+        shapes=[test_shape],
+        dtypes=[test_dtype],
+    )
+
+
+@pytest.fixture
+def test_format():
+    """Standard test memory format."""
+    return MemoryFormat.KV_2LTD
+
+
+# ==============================================================================
+# Helper Functions
+# ==============================================================================
+
+
+def create_object_key(
+    chunk_hash: int,
+    worker_id: int,
+    world_size: int = 2,
+    model_name: str = "test_model",
+) -> ObjectKey:
+    """Create an ObjectKey for testing."""
+    kv_rank = ObjectKey.ComputeKVRank(
+        world_size=world_size,
+        global_rank=worker_id,
+        local_world_size=world_size,
+        local_rank=worker_id,
+    )
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_hash),
+        model_name=model_name,
+        kv_rank=kv_rank,
+    )
+
+
+def create_interleaved_lookup_keys(
+    num_chunks: int,
+    world_size: int,
+    model_name: str = "test_model",
+) -> list[ObjectKey]:
+    """
+    Create interleaved lookup keys for scheduler-style TP lookup.
+
+    The order matches what the scheduler expects:
+    [chunk0_worker0, chunk0_worker1, ..., chunk0_workerN,
+     chunk1_worker0, chunk1_worker1, ..., chunk1_workerN, ...]
+
+    This simulates the key expansion that happens for scheduler lookups
+    where worker_id=None gets expanded to all workers.
+    """
+    keys = []
+    for chunk_idx in range(num_chunks):
+        for worker_id in range(world_size):
+            keys.append(
+                create_object_key(
+                    chunk_hash=chunk_idx,
+                    worker_id=worker_id,
+                    world_size=world_size,
+                    model_name=model_name,
+                )
+            )
+    return keys
+
+
+# ==============================================================================
+# Tests for Storage Manager with TP Scenarios
+# ==============================================================================
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for tensor parallel tests",
+)
+class TestStorageManagerTPLookup:
+    """
+    Tests for storage manager lookup with tensor parallel scenarios.
+
+    The key invariant: for a scheduler lookup (worker_id=None) to succeed,
+    ALL workers must have the cache stored for that chunk.
+    """
+
+    def test_tp2_both_workers_have_all_chunks(self, storage_manager, test_layout):
+        """
+        Test TP=2 lookup when both workers have all chunks cached.
+        Expected: All lookups return True.
+        """
+        world_size = 2
+        num_chunks = 5
+
+        # Store chunks for both workers
+        for worker_id in range(world_size):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_chunks)
+            ]
+            reserved_dict = storage_manager.reserve_write(
+                storage_keys, test_layout, "new"
+            )
+            storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Create interleaved lookup keys for scheduler-style lookup
+        lookup_keys = create_interleaved_lookup_keys(num_chunks, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # All keys should be found (5 chunks * 2 workers = 10)
+        assert found_count == num_chunks * world_size
+
+        # Simulating MPCacheServer.lookup logic
+        found_ipc_count = found_count // world_size
+        assert found_ipc_count == num_chunks
+
+    def test_tp2_only_worker0_has_cache_asymmetric(self, storage_manager, test_layout):
+        """
+        Test TP=2 lookup when only worker 0 has cache (asymmetric).
+        Expected: Lookup returns 0 (no complete cache hit).
+        """
+        world_size = 2
+        num_chunks = 5
+
+        # Store chunks for worker 0 only
+        storage_keys = [
+            create_object_key(chunk_hash=i, worker_id=0, world_size=world_size)
+            for i in range(num_chunks)
+        ]
+        reserved_dict = storage_manager.reserve_write(storage_keys, test_layout, "new")
+        storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Create interleaved lookup keys for scheduler-style lookup
+        lookup_keys = create_interleaved_lookup_keys(num_chunks, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # Only worker 0's first chunk is found, then lookup stops
+        # at worker 1's missing chunk
+        # The ordering is: [chunk0_worker0, chunk0_worker1, chunk1_worker0, ...]
+        # So we find chunk0_worker0 (1), then miss chunk0_worker1
+        assert found_count == 1
+
+        # Simulating MPCacheServer.lookup logic
+        found_ipc_count = found_count // world_size
+        # 1 // 2 = 0, so no complete cache hit
+        assert found_ipc_count == 0
+
+    def test_tp2_only_worker1_has_cache_asymmetric(self, storage_manager, test_layout):
+        """
+        Test TP=2 lookup when only worker 1 has cache (asymmetric).
+        Expected: Lookup returns 0 (first key for worker 0 is missing).
+        """
+        world_size = 2
+        num_chunks = 5
+
+        # Store chunks for worker 1 only
+        storage_keys = [
+            create_object_key(chunk_hash=i, worker_id=1, world_size=world_size)
+            for i in range(num_chunks)
+        ]
+        reserved_dict = storage_manager.reserve_write(storage_keys, test_layout, "new")
+        storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Create interleaved lookup keys for scheduler-style lookup
+        lookup_keys = create_interleaved_lookup_keys(num_chunks, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # First lookup key is chunk0_worker0 which is missing
+        assert found_count == 0
+
+        # Simulating MPCacheServer.lookup logic
+        found_ipc_count = found_count // world_size
+        assert found_ipc_count == 0
+
+    def test_tp2_partial_prefix_both_workers(self, storage_manager, test_layout):
+        """
+        Test TP=2 lookup with partial prefix: both workers have first 3 chunks.
+        Expected: First 3 chunks return True, rest return False.
+        """
+        world_size = 2
+        num_stored_chunks = 3
+        num_requested_chunks = 5
+
+        # Store first 3 chunks for both workers
+        for worker_id in range(world_size):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_stored_chunks)
+            ]
+            reserved_dict = storage_manager.reserve_write(
+                storage_keys, test_layout, "new"
+            )
+            storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Request 5 chunks with scheduler-style interleaved lookup
+        lookup_keys = create_interleaved_lookup_keys(num_requested_chunks, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # First 3 chunks * 2 workers = 6 keys found, then stops at chunk3_worker0
+        assert found_count == num_stored_chunks * world_size
+
+        # Simulating MPCacheServer.lookup logic
+        found_ipc_count = found_count // world_size
+        assert found_ipc_count == num_stored_chunks
+
+    def test_tp2_different_partial_hits_min_common_prefix(
+        self, storage_manager, test_layout
+    ):
+        """
+        Test TP=2 with different partial hits across workers.
+        Worker 0: has chunks 0, 1, 2, 3, 4 (5 chunks)
+        Worker 1: has chunks 0, 1 (2 chunks)
+        Expected: Only first 2 chunks are counted (minimum common prefix).
+        """
+        world_size = 2
+
+        # Worker 0 has 5 chunks
+        storage_keys_w0 = [
+            create_object_key(chunk_hash=i, worker_id=0, world_size=world_size)
+            for i in range(5)
+        ]
+        reserved_dict = storage_manager.reserve_write(
+            storage_keys_w0, test_layout, "new"
+        )
+        storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Worker 1 has only 2 chunks
+        storage_keys_w1 = [
+            create_object_key(chunk_hash=i, worker_id=1, world_size=world_size)
+            for i in range(2)
+        ]
+        reserved_dict = storage_manager.reserve_write(
+            storage_keys_w1, test_layout, "new"
+        )
+        storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Request 5 chunks with scheduler-style interleaved lookup
+        lookup_keys = create_interleaved_lookup_keys(5, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # Lookup order:
+        # chunk0_w0, chunk0_w1, chunk1_w0, chunk1_w1, chunk2_w0, chunk2_w1...
+        # chunk0_w0: found (1)
+        # chunk0_w1: found (2)
+        # chunk1_w0: found (3)
+        # chunk1_w1: found (4)
+        # chunk2_w0: found (5)
+        # chunk2_w1: NOT found (stops)
+        assert found_count == 5  # 2 complete chunks * 2 workers + 1 partial
+
+        # Simulating MPCacheServer.lookup logic
+        found_ipc_count = found_count // world_size
+        # 5 // 2 = 2, so only 2 complete chunks
+        assert found_ipc_count == 2
+
+    def test_tp4_all_workers_have_cache(self, storage_manager, test_layout):
+        """
+        Test TP=4 lookup when all 4 workers have all chunks cached.
+        """
+        world_size = 4
+        num_chunks = 3
+
+        # Store chunks for all workers
+        for worker_id in range(world_size):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_chunks)
+            ]
+            reserved_dict = storage_manager.reserve_write(
+                storage_keys, test_layout, "new"
+            )
+            storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Scheduler-style interleaved lookup
+        lookup_keys = create_interleaved_lookup_keys(num_chunks, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # All keys found: 3 chunks * 4 workers = 12
+        assert found_count == num_chunks * world_size
+
+        found_ipc_count = found_count // world_size
+        assert found_ipc_count == num_chunks
+
+    def test_tp4_one_worker_missing_causes_no_hit(self, storage_manager, test_layout):
+        """
+        Test TP=4 where one worker (worker 2) is missing all cache.
+        Expected: No complete hits due to prefix matching.
+        """
+        world_size = 4
+        num_chunks = 3
+
+        # Store chunks for workers 0, 1, 3 (skip worker 2)
+        for worker_id in [0, 1, 3]:
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_chunks)
+            ]
+            reserved_dict = storage_manager.reserve_write(
+                storage_keys, test_layout, "new"
+            )
+            storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Scheduler-style interleaved lookup
+        lookup_keys = create_interleaved_lookup_keys(num_chunks, world_size)
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # Lookup order: chunk0_w0, chunk0_w1, chunk0_w2, chunk0_w3, ...
+        # chunk0_w0: found (1)
+        # chunk0_w1: found (2)
+        # chunk0_w2: NOT found (stops)
+        assert found_count == 2
+
+        found_ipc_count = found_count // world_size
+        # 2 // 4 = 0, no complete chunks
+        assert found_ipc_count == 0
+
+
+# ==============================================================================
+# Tests for Store and Retrieve with TP
+# ==============================================================================
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for tensor parallel tests",
+)
+class TestStorageManagerTPStoreRetrieve:
+    """Tests for store and retrieve operations with tensor parallel."""
+
+    def test_tp2_store_creates_separate_keys(self, storage_manager, test_layout):
+        """
+        Test that storing with different worker_ids creates separate entries.
+        """
+        world_size = 2
+
+        # Store same chunk hash but different worker_ids
+        key_w0 = create_object_key(chunk_hash=100, worker_id=0, world_size=world_size)
+        key_w1 = create_object_key(chunk_hash=100, worker_id=1, world_size=world_size)
+
+        # Store worker 0's data
+        reserved_dict0 = storage_manager.reserve_write([key_w0], test_layout, "new")
+        assert len(reserved_dict0) == 1
+        storage_manager.finish_write(list(reserved_dict0.keys()))
+
+        # Store worker 1's data
+        reserved_dict1 = storage_manager.reserve_write([key_w1], test_layout, "new")
+        assert len(reserved_dict1) == 1
+        storage_manager.finish_write(list(reserved_dict1.keys()))
+
+        # Prefetch to secure both entries
+        handle = storage_manager.submit_prefetch_task([key_w0, key_w1], test_layout)
+        _ = storage_manager.query_prefetch_status(handle)
+
+        # Both should be retrievable independently
+        with storage_manager.read_prefetched_results([key_w0]) as objs:
+            assert len(objs) == 1
+
+        with storage_manager.read_prefetched_results([key_w1]) as objs:
+            assert len(objs) == 1
+
+    def test_tp2_retrieve_specific_worker(self, storage_manager, test_layout):
+        """
+        Test that retrieve with specific worker_id only gets that worker's data.
+        """
+        world_size = 2
+
+        # Store for both workers
+        all_keys = []
+        for worker_id in range(world_size):
+            keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(3)
+            ]
+            reserved_dict = storage_manager.reserve_write(keys, test_layout, "new")
+            storage_manager.finish_write(list(reserved_dict.keys()))
+            all_keys.extend(keys)
+
+        # Prefetch to secure all entries
+        handle = storage_manager.submit_prefetch_task(all_keys, test_layout)
+        _ = storage_manager.query_prefetch_status(handle)
+
+        # Retrieve only worker 0's data
+        keys_w0 = [
+            create_object_key(chunk_hash=i, worker_id=0, world_size=world_size)
+            for i in range(3)
+        ]
+        with storage_manager.read_prefetched_results(keys_w0) as objs:
+            assert len(objs) == 3
+
+        # Retrieve only worker 1's data
+        keys_w1 = [
+            create_object_key(chunk_hash=i, worker_id=1, world_size=world_size)
+            for i in range(3)
+        ]
+        with storage_manager.read_prefetched_results(keys_w1) as objs:
+            assert len(objs) == 3
+
+
+# ==============================================================================
+# Tests for Edge Cases
+# ==============================================================================
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for tensor parallel tests",
+)
+class TestTPEdgeCases:
+    """Edge case tests for tensor parallel support."""
+
+    def test_world_size_1_stores_and_retrieves(self, storage_manager, test_layout):
+        """
+        Test that world_size=1 (no TP) works correctly through the API.
+        Single worker stores and retrieves data successfully.
+        """
+        world_size = 1
+        num_chunks = 3
+
+        # Store chunks for worker 0
+        storage_keys = [
+            create_object_key(chunk_hash=i, worker_id=0, world_size=world_size)
+            for i in range(num_chunks)
+        ]
+        reserved_dict = storage_manager.reserve_write(storage_keys, test_layout, "new")
+        storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Lookup should find all chunks
+        handle = storage_manager.submit_prefetch_task(storage_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert found_count == num_chunks
+
+        # Retrieve should work
+        with storage_manager.read_prefetched_results(storage_keys) as objs:
+            assert len(objs) == num_chunks
+
+    def test_large_world_size_tp8(self, storage_manager, test_layout):
+        """
+        Test with larger world_size (TP=8) through the API.
+        All 8 workers store and lookup works correctly.
+        """
+        world_size = 8
+        num_chunks = 3
+
+        # Store chunks for all workers
+        all_keys = []
+        for worker_id in range(world_size):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_chunks)
+            ]
+            all_keys.extend(storage_keys)
+            reserved_dict = storage_manager.reserve_write(
+                storage_keys, test_layout, "new"
+            )
+            storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Create interleaved lookup keys (simulating scheduler lookup)
+        # Order: [chunk0_w0, chunk0_w1, ..., chunk0_w7, chunk1_w0, ...]
+        lookup_keys = []
+        for chunk_idx in range(num_chunks):
+            for worker_id in range(world_size):
+                lookup_keys.append(
+                    create_object_key(
+                        chunk_hash=chunk_idx, worker_id=worker_id, world_size=world_size
+                    )
+                )
+
+        # All keys should be found
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert found_count == num_chunks * world_size
+
+        # Verify retrieval for each worker
+        for worker_id in range(world_size):
+            worker_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_chunks)
+            ]
+            with storage_manager.read_prefetched_results(worker_keys) as objs:
+                assert len(objs) == num_chunks
+
+    def test_all_workers_same_chunk_different_keys(self, storage_manager, test_layout):
+        """
+        Test that same chunk_hash with different worker_ids creates
+        distinct entries in storage and can be stored/retrieved independently.
+        """
+        world_size = 4
+        chunk_hash = 42
+
+        # Create storage keys for all workers with same chunk_hash
+        storage_keys = [
+            create_object_key(chunk_hash=chunk_hash, worker_id=i, world_size=world_size)
+            for i in range(world_size)
+        ]
+
+        # All keys should be distinct
+        assert len(set(storage_keys)) == world_size
+
+        # Store all keys
+        reserved_dict = storage_manager.reserve_write(storage_keys, test_layout, "new")
+        assert len(reserved_dict) == world_size
+        storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Lookup all keys
+        handle = storage_manager.submit_prefetch_task(storage_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert found_count == world_size
+
+        # Retrieve each worker's key independently
+        for worker_id in range(world_size):
+            worker_key = create_object_key(
+                chunk_hash=chunk_hash, worker_id=worker_id, world_size=world_size
+            )
+            with storage_manager.read_prefetched_results([worker_key]) as objs:
+                assert len(objs) == 1
+                assert objs[0] is not None
+
+
+# ==============================================================================
+# Integration Tests
+# ==============================================================================
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for tensor parallel tests",
+)
+class TestTPIntegration:
+    """Integration tests simulating real TP workflows."""
+
+    def test_full_tp2_workflow(self, storage_manager, test_layout):
+        """
+        Simulate a full TP=2 workflow:
+        1. Worker 0 stores chunks 0, 1, 2
+        2. Worker 1 stores chunks 0, 1, 2
+        3. Scheduler looks up chunks 0, 1, 2, 3, 4 (interleaved for all workers)
+        4. Verify correct hit count
+        5. Workers retrieve their respective chunks
+        """
+        world_size = 2
+        stored_chunks = 3
+        requested_chunks = 5
+
+        # Step 1 & 2: Workers store their chunks
+        for worker_id in range(world_size):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(stored_chunks)
+            ]
+            reserved_dict = storage_manager.reserve_write(
+                storage_keys, test_layout, "new"
+            )
+            storage_manager.finish_write(list(reserved_dict.keys()))
+
+        # Step 3: Scheduler lookup with interleaved keys
+        # Order: [chunk0_w0, chunk0_w1, chunk1_w0, chunk1_w1, ...]
+        lookup_keys = []
+        for chunk_idx in range(requested_chunks):
+            for worker_id in range(world_size):
+                lookup_keys.append(
+                    create_object_key(
+                        chunk_hash=chunk_idx,
+                        worker_id=worker_id,
+                        world_size=world_size,
+                    )
+                )
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+
+        # Step 4: Verify hit count
+        # First 3 chunks * 2 workers = 6 keys found, then stops at chunk3_worker0
+        assert found_count == stored_chunks * world_size
+
+        # Compute number of complete IPC-level hits
+        found_ipc_count = found_count // world_size
+        assert found_ipc_count == stored_chunks
+
+        # Step 5: Workers retrieve their chunks
+        for worker_id in range(world_size):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(stored_chunks)
+            ]
+            with storage_manager.read_prefetched_results(storage_keys) as objs:
+                assert len(objs) == stored_chunks
+                for obj in objs:
+                    assert obj is not None
+
+    def test_concurrent_tp2_stores(self, storage_manager, test_layout):
+        """
+        Test concurrent stores from multiple "workers" (threads).
+        """
+        world_size = 2
+        num_chunks = 10
+        results = {}
+
+        def worker_store(worker_id: int):
+            storage_keys = [
+                create_object_key(
+                    chunk_hash=i, worker_id=worker_id, world_size=world_size
+                )
+                for i in range(num_chunks)
+            ]
+            reserved = storage_manager.reserve_write(storage_keys, test_layout, "new")
+            storage_manager.finish_write(list(reserved.keys()))
+            results[worker_id] = len(reserved)
+
+        # Run stores concurrently
+        threads = []
+        for worker_id in range(world_size):
+            t = threading.Thread(target=worker_store, args=(worker_id,))
+            threads.append(t)
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Verify both workers stored their chunks
+        assert results[0] == num_chunks
+        assert results[1] == num_chunks
+
+        # Verify lookup works with interleaved keys
+        lookup_keys = []
+        for chunk_idx in range(num_chunks):
+            for worker_id in range(world_size):
+                lookup_keys.append(
+                    create_object_key(
+                        chunk_hash=chunk_idx,
+                        worker_id=worker_id,
+                        world_size=world_size,
+                    )
+                )
+        handle = storage_manager.submit_prefetch_task(lookup_keys, test_layout)
+        found_count = storage_manager.query_prefetch_status(handle).count_leading_ones()
+        assert found_count == num_chunks * world_size
diff --git a/tests/v1/distributed/test_prefetch_controller.py b/tests/v1/distributed/test_prefetch_controller.py
new file mode 100644
index 0000000..09c06c5
--- /dev/null
+++ b/tests/v1/distributed/test_prefetch_controller.py
@@ -0,0 +1,1500 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for PrefetchController.
+
+Tests verify the end-to-end prefetch flow: submit request → lookup in L2 →
+compute prefix-trimmed load plan → reserve L1 buffers → load from L2 →
+transition to read-locked → report prefix hits.
+
+Uses a real L1Manager and MockL2Adapter (with debug methods) to exercise
+the full integration without mocking internals.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import (
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchMode,
+    TrimPolicy,
+)
+from lmcache.v1.distributed.config import L1ManagerConfig, L1MemoryManagerConfig
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.fault_inject_l2_adapter import (
+    FaultInjectL2Adapter,
+)
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_controller import (
+    PrefetchController,
+    build_trim_mask,
+    merge_bitmaps,
+)
+from lmcache.v1.distributed.storage_controllers.prefetch_policy import (
+    DefaultPrefetchPolicy,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+)
+from lmcache.v1.memory_management import MemoryObjMetadata, TensorMemoryObj
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_layout() -> MemoryLayoutDesc:
+    """Create a small MemoryLayoutDesc for testing."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+def should_use_lazy_alloc() -> bool:
+    return torch.cuda.is_available()
+
+
+def wait_for_condition(
+    predicate,
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+) -> bool:
+    """Poll until a predicate returns True or timeout."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def wait_for_prefetch_result(
+    ctrl: PrefetchController,
+    req_id: int,
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+) -> int | None:
+    """Poll query_prefetch_result until it returns a non-None value."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = ctrl.query_prefetch_result(req_id)
+        if result is not None:
+            return result.count_leading_ones()
+        time.sleep(poll_interval)
+    return None
+
+
+def wait_for_lookup_result(
+    ctrl: PrefetchController,
+    req_id: int,
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+) -> int | None:
+    """Poll query_lookup_result until it returns a non-None value."""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = ctrl.query_lookup_result(req_id)
+        if result is not None:
+            return result
+        time.sleep(poll_interval)
+    return None
+
+
+def wait_for_prefetch_result_bitmap(
+    ctrl: PrefetchController,
+    req_id: int,
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+):
+    """Poll query_prefetch_result, returning the raw retained Bitmap.
+
+    Unlike :func:`wait_for_prefetch_result`, this keeps the full bitmap so a
+    caller can inspect non-contiguous retained sets (e.g. SEGMENTED_PREFIX).
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        result = ctrl.query_prefetch_result(req_id)
+        if result is not None:
+            return result
+        time.sleep(poll_interval)
+    return None
+
+
+def make_adapter() -> MockL2Adapter:
+    """Create a MockL2Adapter with fast bandwidth."""
+    config = MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0)
+    return MockL2Adapter(config)
+
+
+def make_descriptor(index: int) -> AdapterDescriptor:
+    """Create an AdapterDescriptor for testing."""
+    config = MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0)
+    return AdapterDescriptor(index=index, config=config)
+
+
+def store_keys_in_l2(
+    adapter: MockL2Adapter,
+    keys: list[ObjectKey],
+    layout: MemoryLayoutDesc,
+) -> None:
+    """Store test data directly in L2 adapter and wait for completion."""
+    if not keys:
+        return
+    objs = []
+    for _ in keys:
+        tensor = torch.randn(layout.shapes[0], dtype=layout.dtypes[0])
+        metadata = MemoryObjMetadata(
+            shape=layout.shapes[0],
+            dtype=layout.dtypes[0],
+            address=0,
+            phy_size=tensor.nelement() * tensor.element_size(),
+            ref_count=0,
+        )
+        obj = TensorMemoryObj(raw_data=tensor, metadata=metadata, parent_allocator=None)
+        objs.append(obj)
+    adapter.submit_store_task(keys, objs)  # type: ignore
+    ok = wait_for_condition(
+        lambda: all(adapter.debug_has_key(k) for k in keys),
+        timeout=5.0,
+    )
+    assert ok, "Failed to store test data in L2 adapter"
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def l1_manager():
+    """Create an L1Manager with a reasonable memory config."""
+    config = L1ManagerConfig(
+        memory_config=L1MemoryManagerConfig(
+            size_in_bytes=128 * 1024 * 1024,
+            use_lazy=should_use_lazy_alloc(),
+            init_size_in_bytes=64 * 1024 * 1024,
+            align_bytes=0x1000,
+        ),
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+    mgr = L1Manager(config)
+    yield mgr
+    mgr.close()
+
+
+# =============================================================================
+# Lifecycle Tests
+# =============================================================================
+
+
+class TestPrefetchControllerLifecycle:
+    """Test PrefetchController start/stop behavior."""
+
+    def test_start_stop(self, l1_manager):
+        """Controller should start and stop cleanly."""
+        adapter = make_adapter()
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+        ctrl.stop()
+        adapter.close()
+
+    def test_start_stop_no_adapters(self, l1_manager):
+        """Controller should start and stop cleanly with no adapters."""
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+        ctrl.stop()
+
+
+# =============================================================================
+# Single Adapter Prefetch
+# =============================================================================
+
+
+class TestSingleAdapterPrefetch:
+    """Test PrefetchController with one MockL2Adapter."""
+
+    def test_full_prefix_hit(self, l1_manager):
+        """All keys in L2 → all loaded, prefix hits = total keys."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(5)]
+
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 5, f"Expected 5 prefix hits, got {result}"
+
+        # Verify prefix keys are read-locked in L1
+        read_results = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        # Cleanup: release read locks
+        l1_manager.finish_read(keys)
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_prefix_with_gap(self, l1_manager):
+        """L2 has keys {0,1,3,4} but not 2 → only prefix {0,1} loaded."""
+        adapter = make_adapter()
+        layout = make_layout()
+        all_keys = [make_object_key(i) for i in range(5)]
+        # Store only keys 0, 1, 3, 4 (gap at index 2)
+        stored_keys = [all_keys[i] for i in [0, 1, 3, 4]]
+        store_keys_in_l2(adapter, stored_keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(all_keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 2, f"Expected 2 prefix hits (gap at index 2), got {result}"
+
+        # Verify prefix keys {0,1} are read-locked in L1
+        prefix_keys = all_keys[:2]
+        read_results = l1_manager.unsafe_read(prefix_keys)
+        for key in prefix_keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        # Verify keys beyond prefix {2,3,4} are NOT in L1
+        non_prefix_keys = all_keys[2:]
+        read_results = l1_manager.reserve_read(non_prefix_keys)
+        for key in non_prefix_keys:
+            assert read_results[key][0] == L1Error.KEY_NOT_EXIST
+
+        l1_manager.finish_read(prefix_keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_segmented_prefix_with_gap(self, l1_manager):
+        """SEGMENTED_PREFIX retains the post-gap keys: L2 {0,1,3,4} -> {0,1,3,4}.
+
+        The PREFIX counterpart (test_prefix_with_gap) truncates the same gap to
+        {0,1}; SEGMENTED_PREFIX keeps the post-gap chunks L1-resident so only
+        the hole (index 2) needs recomputing.
+        """
+        adapter = make_adapter()
+        layout = make_layout()
+        all_keys = [make_object_key(i) for i in range(5)]
+        # Store only keys 0, 1, 3, 4 (gap at index 2).
+        store_keys_in_l2(adapter, [all_keys[i] for i in [0, 1, 3, 4]], layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(
+            all_keys, layout, policy=TrimPolicy.SEGMENTED_PREFIX
+        )
+        retained = wait_for_prefetch_result_bitmap(ctrl, req_id)
+        assert retained is not None
+        assert retained.get_indices_list() == [0, 1, 3, 4], (
+            "SEGMENTED_PREFIX should retain post-gap keys, got "
+            f"{retained.get_indices_list()}"
+        )
+
+        # Retained keys {0,1,3,4} are read-locked in L1; the gap (2) is absent.
+        retained_keys = [all_keys[i] for i in [0, 1, 3, 4]]
+        read = l1_manager.unsafe_read(retained_keys)
+        for key in retained_keys:
+            assert read[key][0] == L1Error.SUCCESS
+        gap_read = l1_manager.reserve_read([all_keys[2]])
+        assert gap_read[all_keys[2]][0] == L1Error.KEY_NOT_EXIST
+
+        l1_manager.finish_read(retained_keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_fault_inject_load_gap_segmented_vs_prefix(self, l1_manager):
+        """fault_inject (load fails at index 2) drives the segmented path.
+
+        Lookup reports all 5 keys present; the *load* of index 2 fails (the L2
+        retrieve error the adapter simulates). SEGMENTED_PREFIX retains the
+        post-gap keys {0,1,3,4}; PREFIX truncates at the hole to {0,1}. Distinct
+        key ranges per policy keep the shared L1 from serving the second pass.
+        """
+        layout = make_layout()
+        for base, trim, expected in (
+            (0, TrimPolicy.SEGMENTED_PREFIX, [0, 1, 3, 4]),
+            (10, TrimPolicy.PREFIX, [0, 1]),
+        ):
+            keys = [make_object_key(base + i) for i in range(5)]
+            inner = make_adapter()
+            store_keys_in_l2(inner, keys, layout)  # all 5 present at lookup
+            # Drop task-position 2 at load -> a mid-prefix L2 retrieve failure.
+            fault = FaultInjectL2Adapter(inner, rate=0.0, seed=0, gap_indices=(2,))
+
+            ctrl = PrefetchController(
+                l1_manager=l1_manager,
+                l2_adapters=[fault],
+                adapter_descriptors=[make_descriptor(0)],
+                policy=DefaultPrefetchPolicy(),
+            )
+            ctrl.start()
+            req_id = ctrl.submit_prefetch_request(keys, layout, policy=trim)
+            retained = wait_for_prefetch_result_bitmap(ctrl, req_id)
+            assert retained is not None
+            assert retained.get_indices_list() == expected, (
+                f"{trim.name}: expected {expected}, got {retained.get_indices_list()}"
+            )
+
+            held = [keys[i] for i in retained.get_indices_list()]
+            if held:
+                l1_manager.finish_read(held)
+            ctrl.stop()
+            fault.close()
+
+    def test_key0_missing(self, l1_manager):
+        """L2 has keys {1,2,3} but not 0 → prefix = 0, nothing loaded."""
+        adapter = make_adapter()
+        layout = make_layout()
+        all_keys = [make_object_key(i) for i in range(4)]
+        # Store keys 1, 2, 3 but not 0
+        stored_keys = all_keys[1:]
+        store_keys_in_l2(adapter, stored_keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(all_keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 0, f"Expected 0 prefix hits (key 0 missing), got {result}"
+
+        # Verify no keys are in L1
+        read_results = l1_manager.reserve_read(all_keys)
+        for key in all_keys:
+            assert read_results[key][0] == L1Error.KEY_NOT_EXIST
+
+        ctrl.stop()
+        adapter.close()
+
+
+# =============================================================================
+# Multi Adapter Prefetch
+# =============================================================================
+
+
+class TestMultiAdapterPrefetch:
+    """Test PrefetchController with multiple MockL2Adapters."""
+
+    def test_disjoint_adapters(self, l1_manager):
+        """Adapter 0 has {0,1}, adapter 1 has {2,3} → full prefix of 4."""
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(i) for i in range(2)]
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(4)]
+
+        store_keys_in_l2(adapters[0], keys[:2], layout)
+        store_keys_in_l2(adapters[1], keys[2:], layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,
+            adapter_descriptors=descriptors,
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 4, f"Expected 4 prefix hits, got {result}"
+
+        read_results = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+    def test_overlap_first_wins(self, l1_manager):
+        """Both adapters have key 1. Adapter 0 (lower index) loads it."""
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(i) for i in range(2)]
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+
+        # Adapter 0 has keys {0, 1}, adapter 1 has keys {1, 2}
+        store_keys_in_l2(adapters[0], keys[:2], layout)
+        store_keys_in_l2(adapters[1], keys[1:], layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,
+            adapter_descriptors=descriptors,
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 3, f"Expected 3 prefix hits, got {result}"
+
+        read_results = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+
+# =============================================================================
+# No Hits
+# =============================================================================
+
+
+class TestNoHits:
+    """Test PrefetchController when no keys are found in L2."""
+
+    def test_no_keys_in_l2(self, l1_manager):
+        """Prefetch keys not in any L2 → 0 prefix hits."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        # Don't store anything in L2
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 0, f"Expected 0 prefix hits, got {result}"
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_no_adapters(self, l1_manager):
+        """No adapters → 0 prefix hits immediately."""
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 0, f"Expected 0 prefix hits, got {result}"
+
+        ctrl.stop()
+
+
+# =============================================================================
+# Query Result
+# =============================================================================
+
+
+class TestQueryResult:
+    """Test query_prefetch_result semantics."""
+
+    def test_query_returns_int_then_none(self, l1_manager):
+        """Result is consumed on first query; second query returns None."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(2)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+
+        assert result == 2
+        # Second query should return None (already consumed)
+        assert ctrl.query_prefetch_result(req_id) is None
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_query_before_completion_returns_none(self, l1_manager):
+        """Querying a nonexistent request ID returns None."""
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        assert ctrl.query_prefetch_result(999) is None
+
+        ctrl.stop()
+
+
+# =============================================================================
+# L2 Lock Release
+# =============================================================================
+
+
+class TestPrefetchL2LockRelease:
+    """Test that L2 locks are properly released after prefetch."""
+
+    def test_locks_released_after_full_hit(self, l1_manager):
+        """All L2 locks should be released after a successful prefetch."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        # Wait for L2 unlock operations to be processed
+        ok = wait_for_condition(
+            lambda: adapter.debug_get_locked_key_count() == 0,
+            timeout=5.0,
+        )
+        assert ok, "L2 locks should be released after prefetch completion"
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_locks_released_after_prefix_trim(self, l1_manager):
+        """L2 locks released for both prefix and non-prefix keys."""
+        adapter = make_adapter()
+        layout = make_layout()
+        all_keys = [make_object_key(i) for i in range(5)]
+        # Store keys 0, 1, 3, 4 (gap at index 2)
+        stored_keys = [all_keys[i] for i in [0, 1, 3, 4]]
+        store_keys_in_l2(adapter, stored_keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(all_keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 2
+
+        # All L2 locks should be released (both prefix and trimmed keys)
+        ok = wait_for_condition(
+            lambda: adapter.debug_get_locked_key_count() == 0,
+            timeout=5.0,
+        )
+        assert ok, "All L2 locks should be released after prefix-trimmed prefetch"
+
+        l1_manager.finish_read(all_keys[:2])
+        ctrl.stop()
+        adapter.close()
+
+    def test_locks_released_after_no_hits(self, l1_manager):
+        """L2 locks released even when nothing is found."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        # Don't store anything
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 0
+
+        ok = wait_for_condition(
+            lambda: adapter.debug_get_locked_key_count() == 0,
+            timeout=5.0,
+        )
+        assert ok, "L2 locks should be 0 when nothing was found"
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_multi_adapter_locks_released(self, l1_manager):
+        """Both adapters' L2 locks released after overlapping prefetch."""
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(i) for i in range(2)]
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+
+        # Adapter 0 has {0, 1}, adapter 1 has {1, 2}
+        store_keys_in_l2(adapters[0], keys[:2], layout)
+        store_keys_in_l2(adapters[1], keys[1:], layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,
+            adapter_descriptors=descriptors,
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        # Both adapters should have all locks released
+        for i, adapter in enumerate(adapters):
+            ok = wait_for_condition(
+                lambda a=adapter: a.debug_get_locked_key_count() == 0,
+                timeout=5.0,
+            )
+            assert ok, f"Adapter {i} should have all L2 locks released"
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+
+# =============================================================================
+# Max In-Flight
+# =============================================================================
+
+
+class TestMaxInFlight:
+    """Test PrefetchController max in-flight request limiting."""
+
+    def test_queuing_beyond_max_in_flight(self, l1_manager):
+        """Submit more requests than max_in_flight → all eventually complete."""
+        adapter = make_adapter()
+        layout = make_layout()
+
+        # Store keys for 4 separate requests (2 keys each)
+        all_keys = [make_object_key(i) for i in range(8)]
+        store_keys_in_l2(adapter, all_keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+            max_in_flight=2,
+        )
+        ctrl.start()
+
+        # Submit 4 requests (max_in_flight=2, so 2 queued)
+        req_ids = []
+        for i in range(4):
+            batch_keys = all_keys[i * 2 : (i + 1) * 2]
+            req_id = ctrl.submit_prefetch_request(batch_keys, layout)
+            req_ids.append(req_id)
+
+        # All 4 requests should eventually complete
+        results = []
+        for req_id in req_ids:
+            result = wait_for_prefetch_result(ctrl, req_id, timeout=10.0)
+            assert result is not None, f"Request {req_id} should complete"
+            results.append(result)
+
+        assert results == [2, 2, 2, 2]
+
+        # Release read locks for all keys
+        l1_manager.finish_read(all_keys)
+
+        ctrl.stop()
+        adapter.close()
+
+
+# =============================================================================
+# Multiple Sequential Requests
+# =============================================================================
+
+
+class TestMultipleRequests:
+    """Test multiple sequential prefetch requests."""
+
+    def test_two_sequential_requests(self, l1_manager):
+        """Two back-to-back requests should both complete correctly."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys1 = [make_object_key(i) for i in range(3)]
+        keys2 = [make_object_key(i) for i in range(10, 14)]
+
+        store_keys_in_l2(adapter, keys1, layout)
+        store_keys_in_l2(adapter, keys2, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req1 = ctrl.submit_prefetch_request(keys1, layout)
+        result1 = wait_for_prefetch_result(ctrl, req1)
+        assert result1 == 3
+
+        req2 = ctrl.submit_prefetch_request(keys2, layout)
+        result2 = wait_for_prefetch_result(ctrl, req2)
+        assert result2 == 4
+
+        l1_manager.finish_read(keys1)
+        l1_manager.finish_read(keys2)
+        ctrl.stop()
+        adapter.close()
+
+
+# =============================================================================
+# extra_count Path
+# =============================================================================
+
+
+class TestExtraCountPrefetch:
+    """Test that extra_count is correctly propagated through the prefetch path.
+
+    When extra_count=N is passed to submit_prefetch_request, the controller
+    must acquire 1 + N read locks per key (one for the prefetch controller
+    itself, plus N for additional TP workers).  Each consumer must call
+    finish_read (or finish_read_prefetched) once to release its lock.
+
+    These tests verify:
+    1. Keys remain accessible after the first finish_read when extra_count > 0.
+    2. Keys are evictable only after ALL 1 + N locks are released.
+    3. extra_count=0 (default) behaves identically to the original single-lock
+       path.
+    4. Prefix trimming still works correctly with extra_count > 0.
+    5. Non-prefix loaded keys have all extra locks released by _finalize_load.
+    """
+
+    def test_extra_count_zero_default_behavior(self, l1_manager):
+        """extra_count=0 (default): single read lock, key freed after one
+        finish_read."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout, extra_count=0)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        # Keys should be readable immediately after prefetch
+        read_results = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        # Release the single read lock — keys should become unlocked
+        finish_results = l1_manager.finish_read(keys, extra_count=0)
+        for key in keys:
+            assert finish_results[key] == L1Error.SUCCESS
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_extra_count_one_requires_two_finish_reads(self, l1_manager):
+        """extra_count=1: two read locks acquired; key stays locked after
+        first finish_read and is released after second."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        # extra_count=1 → 2 read locks per key
+        req_id = ctrl.submit_prefetch_request(keys, layout, extra_count=1)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        # Keys must be readable right after prefetch
+        read_results = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        # Release lock #1 (the "prefetch controller" lock, extra_count=0)
+        finish_results = l1_manager.finish_read(keys, extra_count=0)
+        for key in keys:
+            assert finish_results[key] == L1Error.SUCCESS
+
+        # Keys must STILL be readable — lock #2 (the TP worker lock) is held
+        read_results2 = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert read_results2[key][0] == L1Error.SUCCESS, (
+                f"Key {key} should still be read-locked after first finish_read"
+            )
+
+        # Release lock #2 (the TP worker lock, extra_count=0)
+        finish_results2 = l1_manager.finish_read(keys, extra_count=0)
+        for key in keys:
+            assert finish_results2[key] == L1Error.SUCCESS
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_extra_count_three_requires_four_finish_reads(self, l1_manager):
+        """extra_count=3 (TP=4): four read locks; key stays locked until all
+        four are released."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(2)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        # extra_count=3 → 4 read locks per key
+        req_id = ctrl.submit_prefetch_request(keys, layout, extra_count=3)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 2
+
+        # Release locks one by one; key must remain readable until the last
+        for release_idx in range(3):
+            finish_results = l1_manager.finish_read(keys, extra_count=0)
+            for key in keys:
+                assert finish_results[key] == L1Error.SUCCESS
+
+            # Still readable — remaining locks are held
+            read_results = l1_manager.unsafe_read(keys)
+            for key in keys:
+                assert read_results[key][0] == L1Error.SUCCESS, (
+                    f"Key {key} should still be locked after {release_idx + 1} "
+                    f"finish_read calls"
+                )
+
+        # Release the final lock
+        finish_results = l1_manager.finish_read(keys, extra_count=0)
+        for key in keys:
+            assert finish_results[key] == L1Error.SUCCESS
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_extra_count_with_prefix_trim(self, l1_manager):
+        """extra_count=1 with a gap in L2: only prefix keys get 2 locks;
+        non-prefix keys are never loaded."""
+        adapter = make_adapter()
+        layout = make_layout()
+        all_keys = [make_object_key(i) for i in range(5)]
+        # Store keys 0, 1, 3, 4 — gap at index 2
+        stored_keys = [all_keys[i] for i in [0, 1, 3, 4]]
+        store_keys_in_l2(adapter, stored_keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(all_keys, layout, extra_count=1)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 2, f"Expected 2 prefix hits (gap at index 2), got {result}"
+
+        prefix_keys = all_keys[:2]
+
+        # Prefix keys must be readable
+        read_results = l1_manager.unsafe_read(prefix_keys)
+        for key in prefix_keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        # Release lock #1 — prefix keys still held by lock #2
+        l1_manager.finish_read(prefix_keys, extra_count=0)
+
+        read_results2 = l1_manager.unsafe_read(prefix_keys)
+        for key in prefix_keys:
+            assert read_results2[key][0] == L1Error.SUCCESS, (
+                f"Prefix key {key} should still be locked after first finish_read"
+            )
+
+        # Release lock #2
+        l1_manager.finish_read(prefix_keys, extra_count=0)
+
+        # Non-prefix keys must NOT be in L1
+        non_prefix_keys = all_keys[2:]
+        reserve_results = l1_manager.reserve_read(non_prefix_keys)
+        for key in non_prefix_keys:
+            assert reserve_results[key][0] == L1Error.KEY_NOT_EXIST, (
+                f"Non-prefix key {key} should not be in L1"
+            )
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_extra_count_non_prefix_loaded_keys_fully_released(self, l1_manager):
+        """Keys loaded beyond the prefix (due to partial load failure) must
+        have ALL extra locks released by _finalize_load so they can be evicted.
+
+        We simulate this by storing keys {0, 1, 2} in L2 but making key 1
+        fail to reserve in L1 (by pre-occupying it), creating a gap so that
+        key 2 is loaded but lies beyond the prefix.  _finalize_load must
+        release 1 + extra_count locks for key 2.
+        """
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        # Pre-occupy key[1] in L1 with a write lock so reserve_write fails for it.
+        # This forces a gap: key 0 is prefix (hit), key 1 fails reservation
+        # (gap), key 2 is loaded but beyond the prefix.
+        pre_write_results = l1_manager.reserve_write(
+            keys=[keys[1]],
+            is_temporary=[False],
+            layout_desc=layout,
+            mode="new",
+        )
+        assert pre_write_results[keys[1]][0] == L1Error.SUCCESS
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout, extra_count=1)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        # Only key 0 is in the prefix (key 1 reservation failed → gap)
+        assert result == 1, f"Expected 1 prefix hit, got {result}"
+
+        # key[0] should be in L1 with 2 read locks (1 + extra_count=1)
+        read_results = l1_manager.unsafe_read([keys[0]])
+        assert read_results[keys[0]][0] == L1Error.SUCCESS
+
+        # key[2] was loaded but is beyond the prefix; _finalize_load must have
+        # released all 1 + extra_count=2 locks, so it should be gone from L1
+        # (it's a temporary object and its lock count should be 0).
+        reserve_results = l1_manager.reserve_read([keys[2]])
+        assert reserve_results[keys[2]][0] == L1Error.KEY_NOT_EXIST, (
+            "Non-prefix loaded key[2] should have all locks released and be "
+            "evicted from L1"
+        )
+
+        # Clean up: release key[0]'s 2 locks and key[1]'s write lock
+        l1_manager.finish_read([keys[0]], extra_count=0)
+        l1_manager.finish_read([keys[0]], extra_count=0)
+        l1_manager.finish_write([keys[1]])
+        l1_manager.delete([keys[1]])
+
+        ctrl.stop()
+        adapter.close()
+
+
+# =============================================================================
+# Query Lookup Result
+# =============================================================================
+
+
+class TestQueryLookupResult:
+    """Test query_lookup_result semantics."""
+
+    def test_lookup_result_available_before_prefetch_completes(self, l1_manager):
+        """Lookup result is available while load is still in progress."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+
+        # Lookup result should be available before or at the same time as
+        # the full prefetch result.
+        lookup_hits = wait_for_lookup_result(ctrl, req_id)
+        assert lookup_hits is not None
+        assert lookup_hits == 3
+
+        # Wait for full prefetch to complete and clean up
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_lookup_result_with_prefix_gap(self, l1_manager):
+        """Lookup result reflects prefix-only hits (gap breaks prefix)."""
+        adapter = make_adapter()
+        layout = make_layout()
+        # Store keys 0 and 2 (gap at 1)
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, [keys[0], keys[2]], layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        lookup_hits = wait_for_lookup_result(ctrl, req_id)
+        assert lookup_hits is not None
+        # Only key 0 is in the prefix (gap at key 1 breaks it)
+        assert lookup_hits == 1
+
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 1
+
+        l1_manager.finish_read([keys[0]])
+        ctrl.stop()
+        adapter.close()
+
+    def test_lookup_result_zero_hits(self, l1_manager):
+        """Lookup result is 0 when no keys are found in L2."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        # Don't store anything in L2
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        lookup_hits = wait_for_lookup_result(ctrl, req_id)
+        assert lookup_hits is not None
+        assert lookup_hits == 0
+
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 0
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_lookup_result_not_popped_by_query(self, l1_manager):
+        """query_lookup_result does not consume the result (idempotent reads)."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(2)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        lookup_hits = wait_for_lookup_result(ctrl, req_id)
+        assert lookup_hits == 2
+
+        # Second query should still return the same value (not consumed)
+        assert ctrl.query_lookup_result(req_id) == 2
+
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 2
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_lookup_result_cleaned_up_by_prefetch_result(self, l1_manager):
+        """query_prefetch_result cleans up the lookup result entry."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(2)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        lookup_hits = wait_for_lookup_result(ctrl, req_id)
+        assert lookup_hits == 2
+
+        # Consume the prefetch result (should also clean up lookup entry)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 2
+
+        # Lookup result should now be gone
+        assert ctrl.query_lookup_result(req_id) is None
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_lookup_result_nonexistent_request(self, l1_manager):
+        """Querying a nonexistent request ID returns None."""
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        assert ctrl.query_lookup_result(999) is None
+
+        ctrl.stop()
+
+
+class TestBuildTrimMask:
+    """build_trim_mask picks the retained subset per policy: PREFIX trims at
+    the first gap; SEGMENTED_PREFIX and SPARSE keep every set bit (gaps and
+    all). The retained bitmap is consumed unchanged at the controller's load
+    sites, so testing the mask directly covers the policy semantics."""
+
+    @staticmethod
+    def _bm(n, idxs):
+        bm = Bitmap(n)
+        for i in idxs:
+            bm.set(i)
+        return bm
+
+    def test_prefix_trims_at_first_gap(self):
+        found = self._bm(5, [0, 1, 3, 4])  # gap at index 2
+        assert build_trim_mask(found, 5, TrimPolicy.PREFIX).get_indices_list() == [
+            0,
+            1,
+        ]
+
+    def test_segmented_prefix_keeps_gaps(self):
+        # Models an L2 hit whose L1 load failed mid-prefix (e.g. OOM at index
+        # 2): the keys that did load are kept, not trimmed to the first gap.
+        found = self._bm(5, [0, 1, 3, 4])
+        assert build_trim_mask(
+            found, 5, TrimPolicy.SEGMENTED_PREFIX
+        ).get_indices_list() == [0, 1, 3, 4]
+
+    def test_sparse_keeps_all_found(self):
+        found = self._bm(5, [0, 2, 4])
+        assert build_trim_mask(found, 5, TrimPolicy.SPARSE).get_indices_list() == [
+            0,
+            2,
+            4,
+        ]
+
+
+class TestMergeBitmaps:
+    """merge_bitmaps always returns a num_keys-sized bitmap."""
+
+    def test_empty_input_returns_sized_bitmap(self):
+        """Empty input -> num_keys-sized all-zeros bitmap (not Bitmap(0)), so a
+        downstream ``&`` with a same-sized mask never hits a size mismatch."""
+        merged = merge_bitmaps([], 5)
+        assert merged.popcount() == 0
+        mask = Bitmap(5)
+        mask.set(2)
+        assert (merged & mask).popcount() == 0  # would raise on size mismatch
+
+    def test_empty_generator_returns_sized_bitmap(self):
+        """A generator is truthy even when empty; the result is still size-5."""
+        merged = merge_bitmaps((b for b in []), 5)
+        assert merged.popcount() == 0
+        assert (merged & Bitmap(5)).popcount() == 0
+
+    def test_union_of_bitmaps(self):
+        """Non-empty inputs are OR-merged into one num_keys-sized bitmap."""
+        a, b = Bitmap(5), Bitmap(5)
+        a.set(0)
+        b.set(3)
+        assert merge_bitmaps([a, b], 5).get_indices_list() == [0, 3]
+
+
+class TestWaitPrefetchResult:
+    """Test the blocking wait_prefetch_result interface."""
+
+    def test_wait_blocks_until_result_ready(self, l1_manager):
+        """wait_prefetch_result blocks until the background result is published,
+        returns True, and does not consume the result."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(5)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        # Blocks until the background thread publishes the result.
+        assert ctrl.wait_prefetch_result(req_id, timeout=10.0) is True
+        # wait_prefetch_result must not consume the result.
+        result = ctrl.query_prefetch_result(req_id)
+        assert result is not None
+        assert result.count_leading_ones() == 5
+
+        l1_manager.finish_read(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_wait_times_out_for_unknown_request(self, l1_manager):
+        """wait_prefetch_result returns False, after genuinely waiting, when no
+        result arrives within the timeout."""
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        start = time.monotonic()
+        assert ctrl.wait_prefetch_result(999999, timeout=0.2) is False
+        assert time.monotonic() - start >= 0.2
+
+        ctrl.stop()
+
+
+# =============================================================================
+# Retention Policy
+# =============================================================================
+
+
+class TestPrefetchMode:
+    """``mode=WARM`` (the warm path) loads keys **permanent** and
+    **without a read lock**, vs ``LOOKUP`` which read-locks temporary
+    objects that vanish on release.
+
+    Both tests use ``DefaultPrefetchPolicy`` so the only difference is the
+    per-request ``mode`` argument.
+    """
+
+    def test_warm_loads_unlocked_and_permanent(self, l1_manager):
+        """WARM loads keys permanent and with NO read lock: immediately ready
+        (reserve_read SUCCEEDS), holding no lock (unsafe_read NOT_READABLE), and
+        not deleted on a reserve_read/finish_read cycle (permanent, not temp)."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout, mode=PrefetchMode.WARM)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        # No warming lock: unsafe_read (which needs an active read lock) reports
+        # NOT_READABLE even though the keys are present and ready.
+        unsafe = l1_manager.unsafe_read(keys)
+        for key in keys:
+            assert unsafe[key][0] == L1Error.KEY_NOT_READABLE
+
+        # They are ready and re-lookupable: reserve_read SUCCEEDS...
+        read_results = l1_manager.reserve_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        # ...and releasing that probe lock does NOT delete them (permanent).
+        l1_manager.finish_read(keys)
+        again = l1_manager.reserve_read(keys)
+        for key in keys:
+            assert again[key][0] == L1Error.SUCCESS
+
+        l1_manager.finish_read(keys)
+        l1_manager.delete(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_warm_sparse_skips_write_locked_prefix_and_loads_later_keys(
+        self, l1_manager
+    ):
+        """SPARSE WARM does not let a write-locked earlier key suppress later
+        keys that can be reserved and loaded."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        existing = l1_manager.reserve_write(
+            [keys[0]], is_temporary=[False], layout_desc=layout, mode="new"
+        )
+        assert existing[keys[0]][0] == L1Error.SUCCESS
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(
+            keys,
+            layout,
+            policy=TrimPolicy.SPARSE,
+            mode=PrefetchMode.WARM,
+        )
+        result = wait_for_prefetch_result_bitmap(ctrl, req_id)
+        assert result is not None
+        assert result.get_indices_list() == [1, 2]
+
+        l1_manager.finish_write([keys[0]])
+        read_results = l1_manager.reserve_read(keys[1:])
+        for key in keys[1:]:
+            assert read_results[key][0] == L1Error.SUCCESS
+
+        l1_manager.finish_read(keys[1:])
+        l1_manager.delete(keys)
+        ctrl.stop()
+        adapter.close()
+
+    def test_default_deletes_keys_after_finish_read(self, l1_manager):
+        """LOOKUP defers to ``DefaultPrefetchPolicy`` (temporary), so
+        the keys are deleted from L1 once the read-lock is released."""
+        adapter = make_adapter()
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(3)]
+        store_keys_in_l2(adapter, keys, layout)
+
+        ctrl = PrefetchController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultPrefetchPolicy(),
+        )
+        ctrl.start()
+
+        req_id = ctrl.submit_prefetch_request(keys, layout)
+        result = wait_for_prefetch_result(ctrl, req_id)
+        assert result == 3
+
+        # Releasing the read-lock deletes the temporary objects, so a
+        # subsequent lookup (reserve_read) misses with KEY_NOT_EXIST.
+        l1_manager.finish_read(keys)
+        read_results = l1_manager.reserve_read(keys)
+        for key in keys:
+            assert read_results[key][0] == L1Error.KEY_NOT_EXIST
+
+        ctrl.stop()
+        adapter.close()
diff --git a/tests/v1/distributed/test_prefetch_policy.py b/tests/v1/distributed/test_prefetch_policy.py
new file mode 100644
index 0000000..e2f00ee
--- /dev/null
+++ b/tests/v1/distributed/test_prefetch_policy.py
@@ -0,0 +1,308 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for prefetch policy interface and DefaultPrefetchPolicy.
+
+Tests are written against the PrefetchPolicy contract defined in
+prefetch_policy.py.
+"""
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import MockL2AdapterConfig
+from lmcache.v1.distributed.storage_controllers.prefetch_policy import (
+    DefaultPrefetchPolicy,
+    RetainPrefetchPolicy,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+)
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_descriptor(index: int) -> AdapterDescriptor:
+    """Create an AdapterDescriptor for testing."""
+    config = MockL2AdapterConfig(max_size_gb=1.0, mock_bandwidth_gb=10.0)
+    return AdapterDescriptor(index=index, config=config)
+
+
+def make_bitmap(size: int, set_bits: list[int]) -> Bitmap:
+    """Create a Bitmap with specific bits set."""
+    bitmap = Bitmap(size)
+    for i in set_bits:
+        bitmap.set(i)
+    return bitmap
+
+
+def plan_to_indices(plan: dict[int, Bitmap]) -> dict[int, list[int]]:
+    """Convert a Bitmap-based load plan to index lists for easy assertion."""
+    return {
+        adapter_idx: bitmap.get_indices_list() for adapter_idx, bitmap in plan.items()
+    }
+
+
+# =============================================================================
+# DefaultPrefetchPolicy Tests
+# =============================================================================
+
+
+class TestDefaultPrefetchPolicy:
+    """Test DefaultPrefetchPolicy.select_load_plan behavior."""
+
+    def test_single_adapter_all_keys_found(self):
+        """All found keys assigned to the single adapter."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0)]
+        lookup_results = {0: make_bitmap(3, [0, 1, 2])}
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        assert plan_to_indices(result) == {0: [0, 1, 2]}
+
+    def test_single_adapter_partial_hits(self):
+        """Only found keys are in the plan."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(4)]
+        adapters = [make_descriptor(0)]
+        # Only keys 0 and 2 found
+        lookup_results = {0: make_bitmap(4, [0, 2])}
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        assert plan_to_indices(result) == {0: [0, 2]}
+
+    def test_multi_adapter_overlap_first_wins(self):
+        """When key is in multiple adapters, lowest-index adapter gets it."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0), make_descriptor(1)]
+        # Both adapters have key 1
+        lookup_results = {
+            0: make_bitmap(3, [0, 1]),
+            1: make_bitmap(3, [1, 2]),
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        # key 0 → adapter 0, key 1 → adapter 0 (first wins), key 2 → adapter 1
+        assert plan_to_indices(result) == {0: [0, 1], 1: [2]}
+
+    def test_multi_adapter_disjoint(self):
+        """Each adapter gets its unique keys."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(4)]
+        adapters = [make_descriptor(0), make_descriptor(1)]
+        lookup_results = {
+            0: make_bitmap(4, [0, 1]),
+            1: make_bitmap(4, [2, 3]),
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        assert plan_to_indices(result) == {0: [0, 1], 1: [2, 3]}
+
+    def test_no_hits_returns_empty(self):
+        """Empty bitmaps → empty plan."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0), make_descriptor(1)]
+        lookup_results = {
+            0: make_bitmap(3, []),
+            1: make_bitmap(3, []),
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        assert plan_to_indices(result) == {}
+
+    def test_empty_adapters_returns_empty(self):
+        """No adapters means no plan."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(0)]
+
+        result = policy.select_load_plan(keys, {}, [])
+
+        assert plan_to_indices(result) == {}
+
+    def test_empty_keys_returns_empty(self):
+        """Empty keys list → empty plan."""
+        policy = DefaultPrefetchPolicy()
+        adapters = [make_descriptor(0)]
+        lookup_results = {0: make_bitmap(0, [])}
+
+        result = policy.select_load_plan([], lookup_results, adapters)
+
+        assert plan_to_indices(result) == {}
+
+    def test_adapter_order_matters(self):
+        """Adapter with lower index always has priority, regardless of order
+        in the adapters list."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(0)]
+        # Adapter 1 listed first, but adapter 0 should win
+        adapters = [make_descriptor(1), make_descriptor(0)]
+        lookup_results = {
+            0: make_bitmap(1, [0]),
+            1: make_bitmap(1, [0]),
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        # Adapter 0 gets the key (lower index wins)
+        assert plan_to_indices(result) == {0: [0]}
+
+    def test_three_adapters_with_overlap(self):
+        """Three adapters with partial overlaps."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(5)]
+        adapters = [make_descriptor(0), make_descriptor(1), make_descriptor(2)]
+        lookup_results = {
+            0: make_bitmap(5, [0, 3]),  # has keys 0, 3
+            1: make_bitmap(5, [1, 2, 3]),  # has keys 1, 2, 3
+            2: make_bitmap(5, [2, 3, 4]),  # has keys 2, 3, 4
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        # key 0 → adapter 0
+        # key 1 → adapter 1
+        # key 2 → adapter 1 (lower than adapter 2)
+        # key 3 → adapter 0 (lowest that has it)
+        # key 4 → adapter 2
+        assert plan_to_indices(result) == {0: [0, 3], 1: [1, 2], 2: [4]}
+
+    def test_missing_lookup_result_for_adapter(self):
+        """Adapter with no lookup result is skipped."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(2)]
+        adapters = [make_descriptor(0), make_descriptor(1)]
+        # Only adapter 1 has results
+        lookup_results = {1: make_bitmap(2, [0, 1])}
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        assert plan_to_indices(result) == {1: [0, 1]}
+
+    def test_each_key_appears_at_most_once(self):
+        """No key should be assigned to multiple adapters."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0), make_descriptor(1), make_descriptor(2)]
+        # All adapters have all keys
+        lookup_results = {
+            0: make_bitmap(3, [0, 1, 2]),
+            1: make_bitmap(3, [0, 1, 2]),
+            2: make_bitmap(3, [0, 1, 2]),
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        # All keys should go to adapter 0 only
+        assert plan_to_indices(result) == {0: [0, 1, 2]}
+        assert 1 not in result
+        assert 2 not in result
+
+
+# =============================================================================
+# DefaultPrefetchPolicy.select_l1_retentions Tests
+# =============================================================================
+
+
+class TestDefaultPrefetchPolicyRetentions:
+    """Test DefaultPrefetchPolicy.select_l1_retentions."""
+
+    def test_returns_all_false(self):
+        """Default policy marks all keys as temporary."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(5)]
+        result = policy.select_l1_retentions(keys)
+        assert result == [False] * 5
+
+    def test_empty_keys(self):
+        """Empty keys list returns empty list."""
+        policy = DefaultPrefetchPolicy()
+        result = policy.select_l1_retentions([])
+        assert result == []
+
+    def test_single_key(self):
+        """Single key returns single False."""
+        policy = DefaultPrefetchPolicy()
+        keys = [make_object_key(0)]
+        result = policy.select_l1_retentions(keys)
+        assert result == [False]
+
+    def test_length_matches_input(self):
+        """Output length always matches input length."""
+        policy = DefaultPrefetchPolicy()
+        for n in [0, 1, 10, 100]:
+            keys = [make_object_key(i) for i in range(n)]
+            result = policy.select_l1_retentions(keys)
+            assert len(result) == n
+
+
+# =============================================================================
+# RetainPrefetchPolicy Tests
+# =============================================================================
+
+
+class TestRetainPrefetchPolicyRetentions:
+    """Test RetainPrefetchPolicy.select_l1_retentions."""
+
+    def test_returns_all_true(self):
+        """Retain policy marks all keys as permanent."""
+        policy = RetainPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(5)]
+        result = policy.select_l1_retentions(keys)
+        assert result == [True] * 5
+
+    def test_empty_keys(self):
+        """Empty keys list returns empty list."""
+        policy = RetainPrefetchPolicy()
+        result = policy.select_l1_retentions([])
+        assert result == []
+
+    def test_single_key(self):
+        """Single key returns single True."""
+        policy = RetainPrefetchPolicy()
+        keys = [make_object_key(0)]
+        result = policy.select_l1_retentions(keys)
+        assert result == [True]
+
+    def test_length_matches_input(self):
+        """Output length always matches input length."""
+        policy = RetainPrefetchPolicy()
+        for n in [0, 1, 10, 100]:
+            keys = [make_object_key(i) for i in range(n)]
+            result = policy.select_l1_retentions(keys)
+            assert len(result) == n
+
+
+class TestRetainPrefetchPolicyLoadPlan:
+    """RetainPrefetchPolicy inherits load plan from Default."""
+
+    def test_inherits_load_plan(self):
+        """Load plan should behave identically to Default."""
+        policy = RetainPrefetchPolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0), make_descriptor(1)]
+        lookup_results = {
+            0: make_bitmap(3, [0, 1]),
+            1: make_bitmap(3, [1, 2]),
+        }
+
+        result = policy.select_load_plan(keys, lookup_results, adapters)
+
+        assert plan_to_indices(result) == {0: [0, 1], 1: [2]}
diff --git a/tests/v1/distributed/test_quota_manager.py b/tests/v1/distributed/test_quota_manager.py
new file mode 100644
index 0000000..a47779e
--- /dev/null
+++ b/tests/v1/distributed/test_quota_manager.py
@@ -0,0 +1,247 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for :class:`QuotaManager`.
+"""
+
+# Standard
+import threading
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.quota_manager import QuotaEntry, QuotaManager
+
+
+class TestQuotaManagerBasics:
+    def test_unregistered_salt_limit_is_zero(self):
+        """Legacy allowlist semantics — anything unregistered has limit 0."""
+        qm = QuotaManager()
+        assert qm.get_limit_bytes("alice") == 0
+        assert not qm.has_quota("alice")
+
+    def test_set_and_get(self):
+        qm = QuotaManager()
+        qm.set_quota("alice", 1024)
+        assert qm.get_limit_bytes("alice") == 1024
+        assert qm.has_quota("alice")
+
+    def test_set_overwrites(self):
+        qm = QuotaManager()
+        qm.set_quota("alice", 1024)
+        qm.set_quota("alice", 2048)
+        assert qm.get_limit_bytes("alice") == 2048
+
+    def test_delete_returns_true_when_present(self):
+        qm = QuotaManager()
+        qm.set_quota("alice", 1024)
+        assert qm.delete_quota("alice") is True
+        assert not qm.has_quota("alice")
+        assert qm.get_limit_bytes("alice") == 0
+
+    def test_delete_returns_false_when_absent(self):
+        qm = QuotaManager()
+        assert qm.delete_quota("alice") is False
+
+    def test_zero_limit_is_registered_and_distinguishable(self):
+        """A zero limit IS a registration — ``has_quota`` returns True,
+        so the entry shows up in ``list_quotas``. Evaluating the quota
+        still yields 0, so the salt behaves like an unregistered one
+        for eviction purposes."""
+        qm = QuotaManager()
+        qm.set_quota("alice", 0)
+        assert qm.has_quota("alice")
+        assert qm.get_limit_bytes("alice") == 0
+        entries = qm.list_quotas()
+        assert QuotaEntry(cache_salt="alice", limit_bytes=0) in entries
+
+    def test_reject_negative_limit(self):
+        qm = QuotaManager()
+        with pytest.raises(ValueError, match="non-negative"):
+            qm.set_quota("alice", -1)
+
+    def test_empty_salt_is_a_valid_key(self):
+        """``cache_salt=""`` is a real bucket (anonymous traffic) — the
+        registry treats it like any other key."""
+        qm = QuotaManager()
+        qm.set_quota("", 512)
+        assert qm.has_quota("")
+        assert qm.get_limit_bytes("") == 512
+
+
+class TestQuotaManagerList:
+    def test_list_returns_snapshot(self):
+        qm = QuotaManager()
+        qm.set_quota("alice", 1)
+        entries = qm.list_quotas()
+        # Mutating the snapshot must not affect the registry.
+        entries.clear()
+        assert qm.has_quota("alice")
+
+    def test_list_is_complete(self):
+        qm = QuotaManager()
+        qm.set_quota("alice", 100)
+        qm.set_quota("bob", 200)
+        qm.set_quota("", 50)
+        got = {(e.cache_salt, e.limit_bytes) for e in qm.list_quotas()}
+        assert got == {("alice", 100), ("bob", 200), ("", 50)}
+
+
+class TestQuotaManagerThreadSafety:
+    def test_concurrent_writes_do_not_corrupt(self):
+        """Every write must land intact under contention."""
+        qm = QuotaManager()
+        n_writers = 8
+        per_writer = 50
+        barrier = threading.Barrier(n_writers)
+
+        def writer(worker_id: int) -> None:
+            barrier.wait()
+            for i in range(per_writer):
+                qm.set_quota(f"user-{worker_id}-{i}", worker_id * 1000 + i)
+
+        threads = [threading.Thread(target=writer, args=(w,)) for w in range(n_writers)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert len(qm.list_quotas()) == n_writers * per_writer
+        # Spot-check a few values.
+        assert qm.get_limit_bytes("user-3-7") == 3007
+        assert qm.get_limit_bytes("user-0-0") == 0
+
+    def test_concurrent_read_write(self):
+        """Readers must never see a corrupted value."""
+        qm = QuotaManager()
+        qm.set_quota("alice", 1024)
+        stop = threading.Event()
+        errors: list[str] = []
+
+        def reader():
+            while not stop.is_set():
+                v = qm.get_limit_bytes("alice")
+                if v not in (1024, 2048):
+                    errors.append(f"unexpected {v}")
+                    return
+
+        def writer():
+            for _ in range(1000):
+                qm.set_quota("alice", 2048)
+                qm.set_quota("alice", 1024)
+
+        t_r = threading.Thread(target=reader)
+        t_w = threading.Thread(target=writer)
+        t_r.start()
+        t_w.start()
+        t_w.join()
+        stop.set()
+        t_r.join()
+        assert not errors, errors
+
+    def test_concurrent_set_and_delete_on_same_key(self):
+        """A set racing with a delete must leave the registry in a
+        self-consistent state — either set wins (entry present) or
+        delete wins (entry absent). Neither path should crash or leak
+        a half-applied write."""
+        qm = QuotaManager()
+        iters = 500
+
+        def setter():
+            for _ in range(iters):
+                qm.set_quota("alice", 1024)
+
+        def deleter():
+            for _ in range(iters):
+                qm.delete_quota("alice")
+
+        t1 = threading.Thread(target=setter)
+        t2 = threading.Thread(target=deleter)
+        t1.start()
+        t2.start()
+        t1.join()
+        t2.join()
+        # Final state is either present-with-1024 or absent. Anything
+        # else (KeyError mid-read, partial write, etc.) would have
+        # surfaced during the run.
+        final = qm.get_limit_bytes("alice")
+        assert final in (0, 1024)
+
+
+class TestQuotaManagerEdgeCases:
+    def test_very_large_limit(self):
+        """Well inside a 64-bit int — shouldn't overflow or round."""
+        qm = QuotaManager()
+        big = 2**60
+        qm.set_quota("alice", big)
+        assert qm.get_limit_bytes("alice") == big
+
+    def test_delete_then_read_returns_zero(self):
+        """After deletion the salt is indistinguishable from an
+        unregistered one — limit is the allowlist default of 0."""
+        qm = QuotaManager()
+        qm.set_quota("alice", 1024)
+        qm.delete_quota("alice")
+        assert qm.get_limit_bytes("alice") == 0
+        assert not qm.has_quota("alice")
+
+    def test_many_salts(self):
+        """Sanity: large registries don't trip a size limit."""
+        qm = QuotaManager()
+        for i in range(10_000):
+            qm.set_quota(f"user-{i}", i)
+        assert len(qm.list_quotas()) == 10_000
+        assert qm.get_limit_bytes("user-9999") == 9999
+
+
+class TestQuotaManagerDefaultLimit:
+    """Default-quota semantics used by the coordinator's eviction manager
+    (``effective_limit_bytes``); ``get_limit_bytes`` keeps the legacy
+    allowlist behavior for the MP server's local eviction controller."""
+
+    def test_default_starts_unset(self):
+        qm = QuotaManager()
+        assert qm.get_default_limit_bytes() is None
+
+    def test_effective_limit_none_for_unregistered_until_default_set(self):
+        """Boot state: unregistered salts are exempt (None), even though
+        the legacy ``get_limit_bytes`` still reports 0."""
+        qm = QuotaManager()
+        assert qm.effective_limit_bytes("alice") is None
+        assert qm.get_limit_bytes("alice") == 0
+
+    def test_default_zero_applies_to_unregistered(self):
+        qm = QuotaManager()
+        qm.set_default_limit_bytes(0)
+        assert qm.get_default_limit_bytes() == 0
+        assert qm.effective_limit_bytes("alice") == 0
+
+    def test_positive_default_applies_to_unregistered(self):
+        qm = QuotaManager()
+        qm.set_default_limit_bytes(4096)
+        assert qm.effective_limit_bytes("alice") == 4096
+
+    def test_explicit_quota_wins_over_default(self):
+        qm = QuotaManager()
+        qm.set_default_limit_bytes(4096)
+        qm.set_quota("alice", 1024)
+        assert qm.effective_limit_bytes("alice") == 1024
+
+    def test_explicit_zero_quota_wins_over_unset_default(self):
+        """An explicit 0 is enforceable even while the default is None."""
+        qm = QuotaManager()
+        qm.set_quota("alice", 0)
+        assert qm.effective_limit_bytes("alice") == 0
+        assert qm.effective_limit_bytes("bob") is None
+
+    def test_default_resettable_to_none(self):
+        qm = QuotaManager()
+        qm.set_default_limit_bytes(0)
+        qm.set_default_limit_bytes(None)
+        assert qm.get_default_limit_bytes() is None
+        assert qm.effective_limit_bytes("alice") is None
+
+    def test_negative_default_rejected(self):
+        qm = QuotaManager()
+        with pytest.raises(ValueError):
+            qm.set_default_limit_bytes(-1)
diff --git a/tests/v1/distributed/test_raw_block_l2_adapter.py b/tests/v1/distributed/test_raw_block_l2_adapter.py
new file mode 100644
index 0000000..8434272
--- /dev/null
+++ b/tests/v1/distributed/test_raw_block_l2_adapter.py
@@ -0,0 +1,629 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from unittest.mock import patch
+import os
+import select
+import tempfile
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import EvictionConfig
+from lmcache.v1.distributed.internal_api import L2AdapterListener
+from lmcache.v1.distributed.l2_adapters.raw_block_l2_adapter import (
+    RawBlockL2Adapter,
+    RawBlockL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_controllers.eviction_controller import (
+    L2AdapterEvictionState,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+
+def _has_ext() -> bool:
+    try:
+        # Third Party
+        import lmcache_rust_raw_block_io  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+requires_raw_block_ext = pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+
+
+class _RecordingListener(L2AdapterListener):
+    def __init__(self):
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        self.deleted.append(list(keys))
+
+
+class _FailingListener(L2AdapterListener):
+    def on_l2_keys_stored(self, keys: list[ObjectKey], sizes: list[int]):
+        del keys
+        raise RuntimeError("store listener failed")
+
+    def on_l2_keys_accessed(self, keys: list[ObjectKey]):
+        raise RuntimeError("access listener failed")
+
+    def on_l2_keys_deleted(self, keys: list[ObjectKey]):
+        del keys
+        raise RuntimeError("delete listener failed")
+
+
+def _create_object_key(
+    chunk_id: int,
+    model_name: str = "test_model",
+    cache_salt: str = "",
+) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+        cache_salt=cache_salt,
+    )
+
+
+def _create_memory_obj(size: int = 1024, fill_value: float = 0.0) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def _create_complex_memory_obj(
+    size: int = 1024,
+    fill_value: complex = 0j,
+) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.complex64)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.complex64,
+        address=0,
+        phy_size=raw_data.numel() * raw_data.element_size(),
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def _wait_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            os.eventfd_read(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+def _make_config(
+    device_path: str,
+    *,
+    slot_bytes: int = 64 * 1024,
+    capacity_bytes: int = 0,
+    io_engine: str = "posix",
+    use_uring_cmd: bool = False,
+) -> RawBlockL2AdapterConfig:
+    return RawBlockL2AdapterConfig(
+        device_path=device_path,
+        slot_bytes=slot_bytes,
+        capacity_bytes=capacity_bytes,
+        use_odirect=False,
+        io_engine=io_engine,
+        use_uring_cmd=use_uring_cmd,
+        block_align=4096,
+        header_bytes=4096,
+        meta_total_bytes=1 * 1024 * 1024,
+        meta_enable_periodic=False,
+        num_store_workers=2,
+        num_lookup_workers=1,
+        num_load_workers=2,
+    )
+
+
+def _config_dict(**overrides) -> dict[str, object]:
+    config: dict[str, object] = {
+        "device_path": "/tmp/raw-block-test-device",
+        "slot_bytes": 64 * 1024,
+        "use_odirect": False,
+    }
+    config.update(overrides)
+    return config
+
+
+def test_raw_block_l2_adapter_config_default_io_engine():
+    config = RawBlockL2AdapterConfig.from_dict(_config_dict())
+
+    assert config.io_engine == "posix"
+
+
+@pytest.mark.parametrize("io_engine", ["posix", "io_uring"])
+def test_raw_block_l2_adapter_config_accepts_io_engine_values(io_engine):
+    config = RawBlockL2AdapterConfig.from_dict(_config_dict(io_engine=io_engine))
+
+    assert config.io_engine == io_engine
+
+
+def test_raw_block_l2_adapter_config_rejects_invalid_io_engine():
+    with pytest.raises(ValueError, match="io_engine"):
+        RawBlockL2AdapterConfig.from_dict(_config_dict(io_engine="uring"))
+
+
+@pytest.mark.parametrize("legacy_key", ["use_iouring", "use_uring"])
+def test_raw_block_l2_adapter_config_legacy_use_uring_maps_to_iouring(legacy_key):
+    config = RawBlockL2AdapterConfig.from_dict(_config_dict(**{legacy_key: True}))
+
+    assert config.io_engine == "io_uring"
+
+
+def test_raw_block_l2_adapter_config_explicit_io_engine_wins_over_legacy_flag():
+    config = RawBlockL2AdapterConfig.from_dict(
+        _config_dict(io_engine="posix", use_iouring=True)
+    )
+
+    assert config.io_engine == "posix"
+
+
+def test_raw_block_l2_adapter_config_validates_iouring_queue_depth():
+    with pytest.raises(ValueError, match="iouring_queue_depth"):
+        RawBlockL2AdapterConfig.from_dict(_config_dict(iouring_queue_depth=0))
+
+
+def _run_store(adapter: RawBlockL2Adapter, keys, objects) -> bool:
+    task_id = adapter.submit_store_task(keys, objects)
+    assert _wait_event_fd(adapter.get_store_event_fd())
+    completed = adapter.pop_completed_store_tasks()
+    assert task_id in completed
+    return completed[task_id].is_successful()
+
+
+def _run_lookup(adapter: RawBlockL2Adapter, keys):
+    task_id = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+    assert _wait_event_fd(adapter.get_lookup_and_lock_event_fd())
+    return task_id, adapter.query_lookup_and_lock_result(task_id)
+
+
+def _run_load(adapter: RawBlockL2Adapter, keys, objects):
+    task_id = adapter.submit_load_task(keys, objects)
+    assert _wait_event_fd(adapter.get_load_event_fd())
+    return task_id, adapter.query_load_result(task_id)
+
+
+def test_raw_block_l2_adapter_config_parses_uring_flags():
+    cfg = RawBlockL2AdapterConfig.from_dict(
+        {
+            "type": "raw_block",
+            "device_path": "/tmp/raw-block-dev",
+            "slot_bytes": 64 * 1024,
+            "use_odirect": False,
+            "io_engine": "io_uring",
+        }
+    )
+
+    assert cfg.io_engine == "io_uring"
+    assert cfg.use_uring_cmd is False
+
+    with pytest.raises(ValueError, match="use_uring_cmd requires io_uring"):
+        RawBlockL2AdapterConfig.from_dict(
+            {
+                "type": "raw_block",
+                "device_path": "/tmp/raw-block-dev",
+                "slot_bytes": 64 * 1024,
+                "use_uring_cmd": True,
+            }
+        )
+
+
+def test_raw_block_l2_adapter_uring_cmd_rejects_regular_file():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        with pytest.raises(ValueError, match="NVMe namespace character device"):
+            RawBlockL2Adapter(
+                _make_config(
+                    dev_path,
+                    io_engine="io_uring",
+                    use_uring_cmd=True,
+                )
+            )
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_store_lookup_load_roundtrip():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        adapter = RawBlockL2Adapter(_make_config(dev_path))
+        try:
+            key1 = _create_object_key(1)
+            key_miss = _create_object_key(2)
+            key3 = _create_object_key(3)
+            obj1 = _create_memory_obj(fill_value=1.0)
+            obj3 = _create_memory_obj(fill_value=3.0)
+
+            assert _run_store(adapter, [key1, key3], [obj1, obj3]) is True
+
+            lookup_task_id, lookup_bitmap = _run_lookup(
+                adapter,
+                [key1, key_miss, key3],
+            )
+            assert lookup_bitmap is not None
+            assert lookup_bitmap.get_indices_list() == [0, 2]
+            assert adapter.query_lookup_and_lock_result(lookup_task_id) is None
+
+            load_buffers = [
+                _create_memory_obj(fill_value=0.0),
+                _create_memory_obj(fill_value=0.0),
+                _create_memory_obj(fill_value=0.0),
+            ]
+            load_task_id, load_bitmap = _run_load(
+                adapter,
+                [key1, key_miss, key3],
+                load_buffers,
+            )
+            assert load_bitmap is not None
+            assert load_bitmap.get_indices_list() == [0, 2]
+            assert adapter.query_load_result(load_task_id) is None
+            assert torch.equal(load_buffers[0].tensor, obj1.tensor)
+            assert torch.equal(load_buffers[2].tensor, obj3.tensor)
+            assert torch.count_nonzero(load_buffers[1].tensor) == 0
+
+            adapter.submit_unlock([key1, key_miss, key3])
+        finally:
+            adapter.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_delete_respects_lock_until_unlock():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        adapter = RawBlockL2Adapter(_make_config(dev_path))
+        try:
+            key = _create_object_key(11)
+            obj = _create_memory_obj(fill_value=11.0)
+            assert _run_store(adapter, [key], [obj]) is True
+
+            _, bitmap = _run_lookup(adapter, [key])
+            assert bitmap is not None
+            assert bitmap.get_indices_list() == [0]
+
+            adapter.delete([key])
+            _, still_present = _run_lookup(adapter, [key])
+            assert still_present is not None
+            assert still_present.get_indices_list() == [0]
+            adapter.submit_unlock([key, key])
+
+            adapter.delete([key])
+            _, after_delete = _run_lookup(adapter, [key])
+            assert after_delete is not None
+            assert after_delete.get_indices_list() == []
+            adapter.submit_unlock([key])
+        finally:
+            adapter.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_uses_global_eviction_accounting():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        slot_bytes = 64 * 1024
+        capacity_bytes = (1 * 1024 * 1024) + slot_bytes
+        adapter = RawBlockL2Adapter(
+            _make_config(
+                dev_path,
+                slot_bytes=slot_bytes,
+                capacity_bytes=capacity_bytes,
+            )
+        )
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        try:
+            key1 = _create_object_key(21)
+            key2 = _create_object_key(22)
+            obj1 = _create_memory_obj(fill_value=21.0)
+            obj2 = _create_memory_obj(fill_value=22.0)
+
+            assert _run_store(adapter, [key1], [obj1]) is True
+            assert _run_store(adapter, [key2], [obj2]) is False
+
+            assert listener.stored == [[key1]]
+            assert listener.deleted == []
+
+            usage = adapter.get_usage()
+            assert usage.total_bytes_used == slot_bytes
+            assert usage.total_capacity_bytes == slot_bytes
+            assert 0.0 < usage.usage_fraction <= 1.0
+            assert adapter.supports_global_eviction is True
+
+            status = adapter.report_status()
+            assert status["is_healthy"] is True
+            assert status["type"] == "RawBlockL2Adapter"
+            assert status["core"]["usable_capacity_bytes"] == slot_bytes
+
+            _, bitmap1 = _run_lookup(adapter, [key1])
+            assert bitmap1 is not None
+            assert bitmap1.get_indices_list() == [0]
+            _, bitmap2 = _run_lookup(adapter, [key2])
+            assert bitmap2 is not None
+            assert bitmap2.get_indices_list() == []
+            adapter.submit_unlock([key1, key2])
+
+            adapter.delete([key1])
+            assert listener.deleted[-1] == [key1]
+            assert adapter.get_usage().total_bytes_used == 0
+
+            assert _run_store(adapter, [key2], [obj2]) is True
+            assert listener.stored[-1] == [key2]
+            _, bitmap_after_delete = _run_lookup(adapter, [key1, key2])
+            assert bitmap_after_delete is not None
+            assert bitmap_after_delete.get_indices_list() == [1]
+            adapter.submit_unlock([key1, key2])
+        finally:
+            adapter.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_does_not_notify_duplicate_store():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        adapter = RawBlockL2Adapter(_make_config(dev_path))
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        try:
+            key = _create_object_key(25)
+            obj = _create_memory_obj(fill_value=25.0)
+
+            assert _run_store(adapter, [key], [obj]) is True
+            assert _run_store(adapter, [key], [obj]) is True
+
+            assert listener.stored == [[key]]
+        finally:
+            adapter.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_listener_errors_do_not_block_eventfds():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        adapter = RawBlockL2Adapter(_make_config(dev_path))
+        adapter.register_listener(_FailingListener())
+
+        try:
+            key = _create_object_key(29)
+            obj = _create_memory_obj(fill_value=29.0)
+
+            store_task_id = adapter.submit_store_task([key], [obj])
+            assert _wait_event_fd(adapter.get_store_event_fd())
+            assert adapter.pop_completed_store_tasks()[store_task_id].is_successful()
+
+            load_buffer = _create_memory_obj(fill_value=0.0)
+            load_task_id = adapter.submit_load_task([key], [load_buffer])
+            assert _wait_event_fd(adapter.get_load_event_fd())
+            load_bitmap = adapter.query_load_result(load_task_id)
+            assert load_bitmap is not None
+            assert load_bitmap.get_indices_list() == [0]
+            adapter.delete([key])
+            _, after_delete = _run_lookup(adapter, [key])
+            assert after_delete is not None
+            assert after_delete.get_indices_list() == []
+        finally:
+            adapter.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_recovery_from_checkpoint():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        config = _make_config(dev_path)
+        key = _create_object_key(31)
+        obj = _create_memory_obj(fill_value=31.0)
+
+        adapter1 = RawBlockL2Adapter(config)
+        try:
+            assert _run_store(adapter1, [key], [obj]) is True
+        finally:
+            adapter1.close()
+
+        adapter2 = RawBlockL2Adapter(config)
+        try:
+            _, lookup_bitmap = _run_lookup(adapter2, [key])
+            assert lookup_bitmap is not None
+            assert lookup_bitmap.get_indices_list() == [0]
+
+            load_buffer = _create_memory_obj(fill_value=0.0)
+            _, load_bitmap = _run_load(adapter2, [key], [load_buffer])
+            assert load_bitmap is not None
+            assert load_bitmap.get_indices_list() == [0]
+            assert torch.equal(load_buffer.tensor, obj.tensor)
+            adapter2.submit_unlock([key])
+        finally:
+            adapter2.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_recovery_seeds_usage_by_cache_salt():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        slot_bytes = 64 * 1024
+        config = _make_config(dev_path, slot_bytes=slot_bytes)
+        key = _create_object_key(33, cache_salt="u1")
+        obj = _create_memory_obj(fill_value=33.0)
+
+        adapter1 = RawBlockL2Adapter(config)
+        try:
+            assert _run_store(adapter1, [key], [obj]) is True
+        finally:
+            adapter1.close()
+
+        adapter2 = RawBlockL2Adapter(config)
+        try:
+            usage = adapter2.get_usage()
+            assert usage.total_bytes_used == slot_bytes
+            assert dict(usage.bytes_by_cache_salt) == {"u1": slot_bytes}
+
+            adapter2.delete([key])
+            usage = adapter2.get_usage()
+            assert usage.total_bytes_used == 0
+            assert dict(usage.bytes_by_cache_salt) == {}
+        finally:
+            adapter2.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_recovered_keys_seed_l2_eviction_state():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        config = _make_config(dev_path)
+        key = _create_object_key(34)
+        obj = _create_memory_obj(fill_value=34.0)
+
+        adapter1 = RawBlockL2Adapter(config)
+        try:
+            assert _run_store(adapter1, [key], [obj]) is True
+        finally:
+            adapter1.close()
+
+        adapter2 = RawBlockL2Adapter(config)
+        try:
+            state = L2AdapterEvictionState(
+                0,
+                adapter2,
+                EvictionConfig(eviction_policy="LRU", eviction_ratio=1.0),
+            )
+            assert state.eviction_policy.get_eviction_candidates(1) == [key]
+
+            actions = state.eviction_policy.get_eviction_actions(1.0)
+            assert len(actions) == 1
+            assert actions[0].keys == [key]
+            adapter2.delete(actions[0].keys)
+
+            assert adapter2.get_usage().total_bytes_used == 0
+            assert state.eviction_policy.get_eviction_candidates(1) == []
+        finally:
+            adapter2.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_recovers_unknown_checkpoint_dtype():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        config = _make_config(dev_path)
+        key = _create_object_key(35)
+        obj = _create_complex_memory_obj(fill_value=1 + 2j)
+
+        adapter1 = RawBlockL2Adapter(config)
+        try:
+            assert _run_store(adapter1, [key], [obj]) is True
+        finally:
+            adapter1.close()
+
+        adapter2 = RawBlockL2Adapter(config)
+        try:
+            load_buffer = _create_complex_memory_obj(fill_value=0j)
+            _, load_bitmap = _run_load(adapter2, [key], [load_buffer])
+            assert load_bitmap is not None
+            assert load_bitmap.get_indices_list() == [0]
+            assert load_buffer.metadata.dtype is torch.complex64
+            assert torch.equal(load_buffer.tensor, obj.tensor)
+        finally:
+            adapter2.close()
+
+
+@requires_raw_block_ext
+def test_raw_block_l2_adapter_error_bitmaps_keep_submitted_size():
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        adapter = RawBlockL2Adapter(_make_config(dev_path))
+        try:
+            keys = [_create_object_key(41), _create_object_key(42)]
+            objects = [_create_memory_obj(), _create_memory_obj()]
+
+            with patch.object(
+                adapter, "_run_lookup_task", side_effect=RuntimeError("lookup failed")
+            ):
+                lookup_task_id = adapter.submit_lookup_and_lock_task(
+                    keys, _EMPTY_LAYOUT
+                )
+                assert _wait_event_fd(adapter.get_lookup_and_lock_event_fd())
+                lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_task_id)
+            assert lookup_bitmap is not None
+            assert str(lookup_bitmap) == "00"
+
+            with patch.object(
+                adapter, "_run_load_task", side_effect=RuntimeError("load failed")
+            ):
+                load_task_id = adapter.submit_load_task(keys, objects)
+                assert _wait_event_fd(adapter.get_load_event_fd())
+                load_bitmap = adapter.query_load_result(load_task_id)
+            assert load_bitmap is not None
+            assert str(load_bitmap) == "00"
+        finally:
+            adapter.close()
diff --git a/tests/v1/distributed/test_report_status.py b/tests/v1/distributed/test_report_status.py
new file mode 100644
index 0000000..e5c14d1
--- /dev/null
+++ b/tests/v1/distributed/test_report_status.py
@@ -0,0 +1,222 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the report_status() interface across the StorageManager subtree.
+"""
+
+# Standard
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l2_adapters.config import (
+    L2AdaptersConfig,
+)
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2AdapterConfig,
+)
+
+try:
+    # First Party
+    from lmcache.v1.distributed.storage_manager import StorageManager
+except ImportError:
+    pytest.skip(
+        "Skipping because StorageManager cannot be imported", allow_module_level=True
+    )
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+def should_use_lazy_alloc() -> bool:
+    return torch.cuda.is_available()
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def basic_memory_config():
+    return L1MemoryManagerConfig(
+        size_in_bytes=128 * 1024 * 1024,
+        use_lazy=should_use_lazy_alloc(),
+        init_size_in_bytes=64 * 1024 * 1024,
+        align_bytes=0x1000,
+    )
+
+
+@pytest.fixture
+def basic_l1_config(basic_memory_config):
+    return L1ManagerConfig(
+        memory_config=basic_memory_config,
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+
+
+@pytest.fixture
+def basic_layout():
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+@pytest.fixture
+def storage_manager_no_l2(basic_l1_config):
+    """StorageManager without L2 adapters."""
+    config = StorageManagerConfig(
+        l1_manager_config=basic_l1_config,
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+    sm = StorageManager(config)
+    yield sm
+    sm.close()
+
+
+@pytest.fixture
+def storage_manager_with_l2(basic_l1_config):
+    """StorageManager with one mock L2 adapter."""
+    config = StorageManagerConfig(
+        l1_manager_config=basic_l1_config,
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(
+            adapters=[
+                MockL2AdapterConfig(
+                    max_size_gb=0.1,
+                    mock_bandwidth_gb=10.0,
+                ),
+            ]
+        ),
+    )
+    sm = StorageManager(config)
+    yield sm
+    sm.close()
+
+
+def make_object_key(chunk_hash: int, model_name: str = "test_model", kv_rank: int = 0):
+    hash_bytes = ObjectKey.IntHash2Bytes(chunk_hash)
+    return ObjectKey(chunk_hash=hash_bytes, model_name=model_name, kv_rank=kv_rank)
+
+
+# =============================================================================
+# Tests
+# =============================================================================
+
+
+class TestStorageManagerReportStatus:
+    """Tests for StorageManager.report_status() shape and values."""
+
+    def test_report_status_shape_no_l2(self, storage_manager_no_l2):
+        status = storage_manager_no_l2.report_status()
+
+        # Top-level keys
+        assert "is_healthy" in status
+        assert "l1_manager" in status
+        assert "store_controller" in status
+        assert "prefetch_controller" in status
+        assert "l1_eviction_controller" in status
+        assert "l2_adapters" in status
+        assert "num_l2_adapters" in status
+
+        assert status["is_healthy"] is True
+        assert status["num_l2_adapters"] == 0
+        assert status["l2_adapters"] == []
+
+    def test_report_status_shape_with_l2(self, storage_manager_with_l2):
+        status = storage_manager_with_l2.report_status()
+
+        assert status["is_healthy"] is True
+        assert status["num_l2_adapters"] == 1
+        assert len(status["l2_adapters"]) == 1
+
+        adapter_status = status["l2_adapters"][0]
+        assert adapter_status["is_healthy"] is True
+        assert adapter_status["type"] == "MockL2Adapter"
+        assert "stored_object_count" in adapter_status
+        assert "max_capacity_bytes" in adapter_status
+
+    def test_l1_manager_status_shape(self, storage_manager_no_l2):
+        l1 = storage_manager_no_l2.report_status()["l1_manager"]
+
+        assert l1["is_healthy"] is True
+        assert l1["total_object_count"] == 0
+        assert l1["write_locked_count"] == 0
+        assert l1["read_locked_count"] == 0
+        assert l1["temporary_count"] == 0
+        assert l1["memory_used_bytes"] == 0
+        assert l1["memory_total_bytes"] > 0
+        assert l1["memory_usage_ratio"] == 0.0
+        assert "write_ttl_seconds" in l1
+        assert "read_ttl_seconds" in l1
+
+    def test_store_controller_status_shape(self, storage_manager_no_l2):
+        sc = storage_manager_no_l2.report_status()["store_controller"]
+
+        assert sc["is_healthy"] is True
+        assert sc["thread_alive"] is True
+        assert "pending_keys_count" in sc
+        assert "in_flight_task_count" in sc
+        assert "num_l2_adapters" in sc
+
+    def test_prefetch_controller_status_shape(self, storage_manager_no_l2):
+        pc = storage_manager_no_l2.report_status()["prefetch_controller"]
+
+        assert pc["is_healthy"] is True
+        assert pc["thread_alive"] is True
+        assert "max_in_flight" in pc
+        assert "submission_queue_size" in pc
+        assert "pending_queue_size" in pc
+        assert "in_flight_request_count" in pc
+        assert "lookup_phase_count" in pc
+        assert "load_phase_count" in pc
+        assert "completed_results_count" in pc
+        assert "num_l2_adapters" in pc
+
+    def test_eviction_controller_status_shape(self, storage_manager_no_l2):
+        ec = storage_manager_no_l2.report_status()["l1_eviction_controller"]
+
+        assert ec["is_healthy"] is True
+        assert ec["thread_alive"] is True
+        assert "eviction_policy" in ec
+        assert "trigger_watermark" in ec
+        assert "eviction_ratio" in ec
+
+    def test_l1_status_reflects_writes(self, storage_manager_no_l2, basic_layout):
+        """After writing objects, L1 status should reflect them."""
+        keys = [make_object_key(i) for i in range(3)]
+        reserved = storage_manager_no_l2.reserve_write(keys, basic_layout, "new")
+        assert len(reserved) == 3
+
+        l1 = storage_manager_no_l2.report_status()["l1_manager"]
+        assert l1["total_object_count"] == 3
+        assert l1["write_locked_count"] == 3
+        assert l1["memory_used_bytes"] > 0
+
+        # Finish writes
+        storage_manager_no_l2.finish_write(keys)
+        l1 = storage_manager_no_l2.report_status()["l1_manager"]
+        assert l1["write_locked_count"] == 0
+
+    def test_health_propagation(self, storage_manager_no_l2):
+        """Top-level is_healthy should be True when all children are healthy."""
+        status = storage_manager_no_l2.report_status()
+        assert status["is_healthy"] is True
+
+        # Verify all child components are healthy
+        assert status["l1_manager"]["is_healthy"] is True
+        assert status["store_controller"]["is_healthy"] is True
+        assert status["prefetch_controller"]["is_healthy"] is True
+        assert status["l1_eviction_controller"]["is_healthy"] is True
diff --git a/tests/v1/distributed/test_resp_env_vars.py b/tests/v1/distributed/test_resp_env_vars.py
new file mode 100644
index 0000000..ff202ba
--- /dev/null
+++ b/tests/v1/distributed/test_resp_env_vars.py
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for RESP adapter environment variable support.
+
+These tests verify the precedence logic (config > env var > default)
+without requiring a live Redis server.
+"""
+
+# Standard
+import os
+
+
+class TestRESPL2AdapterEnvVars:
+    """Test env var resolution in the MP-mode RESP L2 adapter factory."""
+
+    def test_env_vars_used_when_config_empty(self, monkeypatch):
+        """Env vars should be used when config values are empty/default."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        monkeypatch.setenv("LMCACHE_RESP_HOST", "env-host")
+        monkeypatch.setenv("LMCACHE_RESP_PORT", "7777")
+        monkeypatch.setenv("LMCACHE_RESP_USERNAME", "env-user")
+        monkeypatch.setenv("LMCACHE_RESP_PASSWORD", "env-pass")
+
+        config = RESPL2AdapterConfig(host="", port=0, username="", password="")
+
+        host = config.host or os.environ.get("LMCACHE_RESP_HOST", "")
+        port = (
+            config.port
+            if config.port
+            else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+        )
+        username = config.username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+        password = config.password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+        assert host == "env-host"
+        assert port == 7777
+        assert username == "env-user"
+        assert password == "env-pass"
+
+    def test_config_overrides_env_vars(self, monkeypatch):
+        """Config values should take precedence over env vars."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        monkeypatch.setenv("LMCACHE_RESP_HOST", "env-host")
+        monkeypatch.setenv("LMCACHE_RESP_PORT", "7777")
+        monkeypatch.setenv("LMCACHE_RESP_USERNAME", "env-user")
+        monkeypatch.setenv("LMCACHE_RESP_PASSWORD", "env-pass")
+
+        config = RESPL2AdapterConfig(
+            host="cfg-host",
+            port=8888,
+            username="cfg-user",
+            password="cfg-pass",
+        )
+
+        host = config.host or os.environ.get("LMCACHE_RESP_HOST", "")
+        port = (
+            config.port
+            if config.port
+            else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+        )
+        username = config.username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+        password = config.password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+        assert host == "cfg-host"
+        assert port == 8888
+        assert username == "cfg-user"
+        assert password == "cfg-pass"
+
+    def test_defaults_when_no_env_and_no_config(self, monkeypatch):
+        """Without env vars or config, values should be empty/zero."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        monkeypatch.delenv("LMCACHE_RESP_HOST", raising=False)
+        monkeypatch.delenv("LMCACHE_RESP_PORT", raising=False)
+        monkeypatch.delenv("LMCACHE_RESP_USERNAME", raising=False)
+        monkeypatch.delenv("LMCACHE_RESP_PASSWORD", raising=False)
+
+        config = RESPL2AdapterConfig(host="", port=0, username="", password="")
+
+        host = config.host or os.environ.get("LMCACHE_RESP_HOST", "")
+        port = (
+            config.port
+            if config.port
+            else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+        )
+        username = config.username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+        password = config.password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+        assert host == ""
+        assert port == 0
+        assert username == ""
+        assert password == ""
+
+
+class TestRESPConnectorAdapterEnvVars:
+    """Test env var resolution in the non-MP RESP connector adapter."""
+
+    def test_env_vars_used_when_extra_config_empty(self, monkeypatch):
+        """Env vars should be used when extra_config has no credentials."""
+        monkeypatch.setenv("LMCACHE_RESP_USERNAME", "env-user")
+        monkeypatch.setenv("LMCACHE_RESP_PASSWORD", "env-pass")
+
+        extra_config = {}
+
+        cfg_username = str(extra_config.get("username", ""))
+        cfg_password = str(extra_config.get("password", ""))
+        username = cfg_username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+        password = cfg_password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+        assert username == "env-user"
+        assert password == "env-pass"
+
+    def test_extra_config_overrides_env_vars(self, monkeypatch):
+        """extra_config values should take precedence over env vars."""
+        monkeypatch.setenv("LMCACHE_RESP_USERNAME", "env-user")
+        monkeypatch.setenv("LMCACHE_RESP_PASSWORD", "env-pass")
+
+        extra_config = {"username": "cfg-user", "password": "cfg-pass"}
+
+        cfg_username = str(extra_config.get("username", ""))
+        cfg_password = str(extra_config.get("password", ""))
+        username = cfg_username or os.environ.get("LMCACHE_RESP_USERNAME", "")
+        password = cfg_password or os.environ.get("LMCACHE_RESP_PASSWORD", "")
+
+        assert username == "cfg-user"
+        assert password == "cfg-pass"
+
+    def test_host_port_env_var_fallback(self, monkeypatch):
+        """Host/port env vars should be used when URL values are empty."""
+        monkeypatch.setenv("LMCACHE_RESP_HOST", "env-host")
+        monkeypatch.setenv("LMCACHE_RESP_PORT", "9999")
+
+        parsed_host = ""
+        parsed_port = 0
+
+        host = parsed_host or os.environ.get("LMCACHE_RESP_HOST", "")
+        port = (
+            parsed_port
+            if parsed_port
+            else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+        )
+
+        assert host == "env-host"
+        assert port == 9999
+
+    def test_url_overrides_env_vars(self, monkeypatch):
+        """URL-parsed values should take precedence over env vars."""
+        monkeypatch.setenv("LMCACHE_RESP_HOST", "env-host")
+        monkeypatch.setenv("LMCACHE_RESP_PORT", "9999")
+
+        parsed_host = "url-host"
+        parsed_port = 6379
+
+        host = parsed_host or os.environ.get("LMCACHE_RESP_HOST", "")
+        port = (
+            parsed_port
+            if parsed_port
+            else int(os.environ.get("LMCACHE_RESP_PORT", "0"))
+        )
+
+        assert host == "url-host"
+        assert port == 6379
diff --git a/tests/v1/distributed/test_resp_l2_adapter_integration.py b/tests/v1/distributed/test_resp_l2_adapter_integration.py
new file mode 100644
index 0000000..9b7e9aa
--- /dev/null
+++ b/tests/v1/distributed/test_resp_l2_adapter_integration.py
@@ -0,0 +1,292 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Integration test for the RESP L2 adapter in MP mode.
+
+Requires a running Redis server. Skipped if Redis or the C++ extension
+is unavailable.
+"""
+
+# Standard
+import os
+import select
+import subprocess
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+REDIS_HOST = os.environ.get("REDIS_HOST", "localhost")
+REDIS_PORT = int(os.environ.get("REDIS_PORT", "6399"))
+
+
+def _redis_available() -> bool:
+    """Check if Redis is reachable."""
+    try:
+        result = subprocess.run(
+            ["redis-cli", "-h", REDIS_HOST, "-p", str(REDIS_PORT), "ping"],
+            capture_output=True,
+            text=True,
+            timeout=3,
+        )
+        return result.stdout.strip() == "PONG"
+    except Exception:
+        return False
+
+
+def _native_client_available() -> bool:
+    """Check if the C++ Redis extension can be imported."""
+    try:
+        # First Party
+        from lmcache.lmcache_redis import LMCacheRedisClient  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+requires_redis = pytest.mark.skipif(
+    not _redis_available(),
+    reason=f"Redis not available at {REDIS_HOST}:{REDIS_PORT}",
+)
+requires_native = pytest.mark.skipif(
+    not _native_client_available(),
+    reason="C++ Redis extension (lmcache_redis) not available",
+)
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(size: int = 256, fill_value: float = 1.0) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 10.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+def flush_redis():
+    """Flush the test Redis database."""
+    subprocess.run(
+        ["redis-cli", "-h", REDIS_HOST, "-p", str(REDIS_PORT), "FLUSHDB"],
+        capture_output=True,
+        timeout=3,
+    )
+
+
+@requires_redis
+@requires_native
+class TestRESPL2AdapterIntegration:
+    """Integration tests using real Redis + real C++ RESP connector."""
+
+    @pytest.fixture(autouse=True)
+    def setup_adapter(self):
+        flush_redis()
+
+        # First Party
+        from lmcache.lmcache_redis import LMCacheRedisClient
+        from lmcache.v1.distributed.l2_adapters.native_connector_l2_adapter import (
+            NativeConnectorL2Adapter,
+        )
+
+        native_client = LMCacheRedisClient(REDIS_HOST, REDIS_PORT, 4)
+        self.adapter = NativeConnectorL2Adapter(native_client)
+        yield
+        self.adapter.close()
+        flush_redis()
+
+    def test_event_fds_are_distinct(self):
+        fds = {
+            self.adapter.get_store_event_fd(),
+            self.adapter.get_lookup_and_lock_event_fd(),
+            self.adapter.get_load_event_fd(),
+        }
+        assert len(fds) == 3
+
+    def test_store_and_lookup(self):
+        """Store objects to Redis, then verify lookup finds them."""
+        keys = [create_object_key(i) for i in range(5)]
+        objs = [create_memory_obj(size=64, fill_value=float(i)) for i in range(5)]
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Store
+        store_tid = self.adapter.submit_store_task(keys, objs)
+        assert wait_for_event_fd(store_fd)
+        completed = self.adapter.pop_completed_store_tasks()
+        assert completed[store_tid].is_successful()
+
+        # Lookup all — should find everything
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap is not None
+        for i in range(5):
+            assert bitmap.test(i) is True, f"Key {i} not found in lookup"
+
+        # Unlock
+        self.adapter.submit_unlock(keys)
+
+    def test_lookup_nonexistent_keys(self):
+        """Lookup for keys not in Redis should return all zeros."""
+        keys = [create_object_key(i + 1000) for i in range(3)]
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap is not None
+        for i in range(3):
+            assert bitmap.test(i) is False
+
+    def test_full_store_lookup_load_workflow(self):
+        """End-to-end: store → lookup → load, verify data integrity."""
+        key = create_object_key(42)
+        store_obj = create_memory_obj(size=512, fill_value=3.14)
+        load_obj = create_memory_obj(size=512, fill_value=0.0)
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+        load_fd = self.adapter.get_load_event_fd()
+
+        # Store
+        store_tid = self.adapter.submit_store_task([key], [store_obj])
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Lookup
+        lookup_tid = self.adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        assert bitmap.test(0) is True
+
+        # Load
+        load_tid = self.adapter.submit_load_task([key], [load_obj])
+        assert wait_for_event_fd(load_fd)
+        bitmap = self.adapter.query_load_result(load_tid)
+        assert bitmap.test(0) is True
+
+        # Verify data integrity
+        assert torch.allclose(load_obj.tensor, store_obj.tensor), (
+            "Loaded data does not match stored data"
+        )
+
+        # Unlock
+        self.adapter.submit_unlock([key])
+
+    def test_batch_store_lookup_load(self):
+        """Batch workflow with multiple objects."""
+        n = 10
+        keys = [create_object_key(i) for i in range(n)]
+        store_objs = [
+            create_memory_obj(size=128, fill_value=float(i * 7)) for i in range(n)
+        ]
+        load_objs = [create_memory_obj(size=128, fill_value=0.0) for _ in range(n)]
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+        load_fd = self.adapter.get_load_event_fd()
+
+        # Store all
+        store_tid = self.adapter.submit_store_task(keys, store_objs)
+        assert wait_for_event_fd(store_fd)
+        assert self.adapter.pop_completed_store_tasks()[store_tid].is_successful()
+
+        # Lookup all
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+        for i in range(n):
+            assert bitmap.test(i) is True
+
+        # Load all
+        load_tid = self.adapter.submit_load_task(keys, load_objs)
+        assert wait_for_event_fd(load_fd)
+        bitmap = self.adapter.query_load_result(load_tid)
+        for i in range(n):
+            assert bitmap.test(i) is True
+            assert torch.allclose(load_objs[i].tensor, store_objs[i].tensor), (
+                f"Data mismatch for key {i}"
+            )
+
+        self.adapter.submit_unlock(keys)
+
+    def test_mixed_lookup_existing_and_missing(self):
+        """Lookup a mix of stored and non-stored keys."""
+        stored_keys = [create_object_key(i) for i in range(3)]
+        stored_objs = [create_memory_obj(fill_value=float(i)) for i in range(3)]
+
+        store_fd = self.adapter.get_store_event_fd()
+        lookup_fd = self.adapter.get_lookup_and_lock_event_fd()
+
+        # Store first 3
+        self.adapter.submit_store_task(stored_keys, stored_objs)
+        assert wait_for_event_fd(store_fd)
+        self.adapter.pop_completed_store_tasks()
+
+        # Lookup 5 keys (3 stored + 2 missing)
+        all_keys = stored_keys + [create_object_key(100), create_object_key(101)]
+        lookup_tid = self.adapter.submit_lookup_and_lock_task(all_keys, _EMPTY_LAYOUT)
+        assert wait_for_event_fd(lookup_fd)
+        bitmap = self.adapter.query_lookup_and_lock_result(lookup_tid)
+
+        for i in range(3):
+            assert bitmap.test(i) is True, f"Stored key {i} should be found"
+        assert bitmap.test(3) is False, "Missing key should not be found"
+        assert bitmap.test(4) is False, "Missing key should not be found"
+
+        self.adapter.submit_unlock(stored_keys)
+
+    def test_factory_creates_adapter(self):
+        """Verify the factory can create a RESP L2 adapter from config."""
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+        from lmcache.v1.distributed.l2_adapters.resp_l2_adapter import (
+            RESPL2AdapterConfig,
+        )
+
+        config = RESPL2AdapterConfig(host=REDIS_HOST, port=REDIS_PORT, num_workers=2)
+        adapter = create_l2_adapter(config)
+        try:
+            # Should have valid event fds
+            assert adapter.get_store_event_fd() >= 0
+            assert adapter.get_lookup_and_lock_event_fd() >= 0
+            assert adapter.get_load_event_fd() >= 0
+        finally:
+            adapter.close()
diff --git a/tests/v1/distributed/test_runtime_adapters.py b/tests/v1/distributed/test_runtime_adapters.py
new file mode 100644
index 0000000..83987a2
--- /dev/null
+++ b/tests/v1/distributed/test_runtime_adapters.py
@@ -0,0 +1,392 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for runtime add/remove of L2 adapters.
+
+Covers both the controller-level primitives (StoreController /
+PrefetchController add_adapter / request_remove_adapter with graceful
+drain) and the StorageManager orchestration (add_l2_adapter /
+delete_l2_adapter), including stable-id semantics and the
+active/draining observability surface.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.config import L2AdaptersConfig
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_controllers.store_controller import StoreController
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+    DefaultStorePolicy,
+)
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_layout() -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+def should_use_lazy_alloc() -> bool:
+    return torch.cuda.is_available()
+
+
+def wait_for_condition(predicate, timeout: float = 5.0, poll: float = 0.02) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll)
+    return False
+
+
+def make_mock_config() -> MockL2AdapterConfig:
+    return MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0)
+
+
+def make_adapter() -> MockL2Adapter:
+    return MockL2Adapter(make_mock_config())
+
+
+def make_descriptor(index: int) -> AdapterDescriptor:
+    return AdapterDescriptor(index=index, config=make_mock_config())
+
+
+def adapter_by_id(sm: StorageManager, adapter_id: int) -> MockL2Adapter:
+    """Fetch an active adapter by stable id via the public ``l2_adapters()``
+    API (no private-member access)."""
+    for desc, adapter in sm.l2_adapters():
+        if desc.index == adapter_id:
+            return adapter  # type: ignore[return-value]
+    raise AssertionError(f"no active L2 adapter with id {adapter_id}")
+
+
+def active_adapter_ids(sm: StorageManager) -> set[int]:
+    """Set of active adapter ids exposed by the public ``l2_adapters()`` API."""
+    return {desc.index for desc, _ in sm.l2_adapters()}
+
+
+def write_keys_to_l1(
+    l1_manager: L1Manager,
+    keys: list[ObjectKey],
+    layout: MemoryLayoutDesc,
+) -> None:
+    results = l1_manager.reserve_write(
+        keys=keys,
+        is_temporary=[False] * len(keys),
+        layout_desc=layout,
+        mode="new",
+    )
+    written = [k for k, (e, m) in results.items() if m is not None]
+    if written:
+        l1_manager.finish_write(written)
+
+
+@pytest.fixture
+def l1_manager():
+    config = L1ManagerConfig(
+        memory_config=L1MemoryManagerConfig(
+            size_in_bytes=128 * 1024 * 1024,
+            use_lazy=should_use_lazy_alloc(),
+            init_size_in_bytes=64 * 1024 * 1024,
+            align_bytes=0x1000,
+        ),
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+    mgr = L1Manager(config)
+    yield mgr
+    mgr.close()
+
+
+@pytest.fixture
+def empty_storage_manager_config():
+    """A StorageManagerConfig with no L2 adapters configured."""
+    return StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=128 * 1024 * 1024,
+                use_lazy=should_use_lazy_alloc(),
+                init_size_in_bytes=64 * 1024 * 1024,
+                align_bytes=0x1000,
+            ),
+            write_ttl_seconds=600,
+            read_ttl_seconds=300,
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+        l2_adapter_config=L2AdaptersConfig(adapters=[]),
+    )
+
+
+# =============================================================================
+# StoreController-level tests
+# =============================================================================
+
+
+class TestStoreControllerRuntimeAdapters:
+    def test_add_adapter_routes_new_stores(self, l1_manager):
+        """A key written after add_adapter is stored to the new adapter."""
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+        try:
+            adapter = make_adapter()
+            ctrl.add_adapter(0, adapter, make_descriptor(0))
+
+            assert ctrl.report_status()["num_active_adapters"] == 1
+            assert ctrl.report_status()["num_draining_adapters"] == 0
+
+            layout = make_layout()
+            keys = [make_object_key(i) for i in range(3)]
+            write_keys_to_l1(l1_manager, keys, layout)
+
+            ok = wait_for_condition(
+                lambda: adapter.debug_get_stored_object_count() == 3
+            )
+            assert ok, "Keys should be stored to the runtime-added adapter"
+        finally:
+            ctrl.stop()
+            adapter.close()
+
+    def test_remove_adapter_drains_and_detaches(self, l1_manager):
+        """request_remove_adapter drains in-flight work then detaches."""
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+        try:
+            layout = make_layout()
+            keys = [make_object_key(i) for i in range(3)]
+            write_keys_to_l1(l1_manager, keys, layout)
+            assert wait_for_condition(
+                lambda: adapter.debug_get_stored_object_count() == 3
+            )
+
+            done = ctrl.request_remove_adapter(0)
+            assert done.wait(timeout=5.0), "Adapter should drain and detach"
+
+            status = ctrl.report_status()
+            assert status["num_l2_adapters"] == 0
+            assert status["num_active_adapters"] == 0
+            assert status["num_draining_adapters"] == 0
+        finally:
+            ctrl.stop()
+            adapter.close()
+
+    def test_remove_stops_new_routing(self, l1_manager):
+        """After removal, new writes are not routed to the removed adapter."""
+        keep = make_adapter()
+        drop = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[keep, drop],
+            adapter_descriptors=[make_descriptor(0), make_descriptor(1)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+        try:
+            done = ctrl.request_remove_adapter(1)
+            assert done.wait(timeout=5.0)
+
+            layout = make_layout()
+            keys = [make_object_key(i) for i in range(3)]
+            write_keys_to_l1(l1_manager, keys, layout)
+
+            assert wait_for_condition(lambda: keep.debug_get_stored_object_count() == 3)
+            # The dropped adapter must not receive the new keys.
+            time.sleep(0.2)
+            assert drop.debug_get_stored_object_count() == 0
+        finally:
+            ctrl.stop()
+            keep.close()
+            drop.close()
+
+    def test_double_remove_is_safe(self, l1_manager):
+        """Removing an already-removed adapter signals immediately."""
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+        try:
+            assert ctrl.request_remove_adapter(0).wait(timeout=5.0)
+            # Second removal of the same (now-detached) id must not hang.
+            assert ctrl.request_remove_adapter(0).wait(timeout=5.0)
+        finally:
+            ctrl.stop()
+            adapter.close()
+
+
+# =============================================================================
+# StorageManager-level tests
+# =============================================================================
+
+
+class TestStorageManagerRuntimeAdapters:
+    def test_add_to_empty_manager(self, empty_storage_manager_config):
+        """add_l2_adapter wires a new adapter into all controllers."""
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            assert sm.report_status()["num_l2_adapters"] == 0
+
+            adapter_id = sm.add_l2_adapter(make_mock_config())
+            assert adapter_id == 0
+
+            status = sm.report_status()
+            assert status["num_l2_adapters"] == 1
+            assert status["store_controller"]["num_active_adapters"] == 1
+            assert status["prefetch_controller"]["num_active_adapters"] == 1
+        finally:
+            sm.close()
+
+    def test_add_then_store(self, empty_storage_manager_config):
+        """Keys written after add_l2_adapter land in the new adapter."""
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            adapter_id = sm.add_l2_adapter(make_mock_config())
+            adapter = adapter_by_id(sm, adapter_id)
+
+            layout = make_layout()
+            keys = [make_object_key(i) for i in range(4)]
+            ret = sm.reserve_write(keys, layout, mode="new")
+            sm.finish_write(list(ret.keys()))
+
+            assert wait_for_condition(
+                lambda: all(adapter.debug_has_key(k) for k in keys),  # type: ignore
+                timeout=10.0,
+            )
+        finally:
+            sm.close()
+
+    def test_delete_detaches_everywhere(self, empty_storage_manager_config):
+        """delete_l2_adapter drains and removes the adapter from all controllers."""
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            adapter_id = sm.add_l2_adapter(make_mock_config())
+            assert sm.report_status()["num_l2_adapters"] == 1
+
+            sm.delete_l2_adapter(adapter_id, timeout=10.0)
+
+            status = sm.report_status()
+            assert status["num_l2_adapters"] == 0
+            assert status["store_controller"]["num_l2_adapters"] == 0
+            assert status["prefetch_controller"]["num_l2_adapters"] == 0
+        finally:
+            sm.close()
+
+    def test_delete_unknown_id_raises(self, empty_storage_manager_config):
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            with pytest.raises(ValueError):
+                sm.delete_l2_adapter(999)
+        finally:
+            sm.close()
+
+    def test_stable_ids_across_add_delete(self, empty_storage_manager_config):
+        """Ids are monotonic and never reused; delete does not shift others."""
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            id0 = sm.add_l2_adapter(make_mock_config())
+            id1 = sm.add_l2_adapter(make_mock_config())
+            assert (id0, id1) == (0, 1)
+
+            sm.delete_l2_adapter(id0, timeout=10.0)
+
+            id2 = sm.add_l2_adapter(make_mock_config())
+            assert id2 == 2, "Ids must not be reused after a delete"
+
+            # The surviving adapter keeps its original id.
+            assert active_adapter_ids(sm) == {1, 2}
+            assert sm.report_status()["num_l2_adapters"] == 2
+        finally:
+            sm.close()
+
+    def test_add_after_delete_routes_to_new_adapter(self, empty_storage_manager_config):
+        """A fresh adapter added after a delete receives new stores."""
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            first = sm.add_l2_adapter(make_mock_config())
+            sm.delete_l2_adapter(first, timeout=10.0)
+            second = sm.add_l2_adapter(make_mock_config())
+            adapter = adapter_by_id(sm, second)
+
+            layout = make_layout()
+            keys = [make_object_key(i) for i in range(3)]
+            ret = sm.reserve_write(keys, layout, mode="new")
+            sm.finish_write(list(ret.keys()))
+
+            assert wait_for_condition(
+                lambda: all(adapter.debug_has_key(k) for k in keys),  # type: ignore
+                timeout=10.0,
+            )
+        finally:
+            sm.close()
+
+    def test_l2_adapters_reflects_runtime_changes(self, empty_storage_manager_config):
+        """l2_adapters() tracks runtime add/delete in stable-id order."""
+        sm = StorageManager(empty_storage_manager_config)
+        try:
+            assert sm.l2_adapters() == []
+
+            id0 = sm.add_l2_adapter(make_mock_config())
+            id1 = sm.add_l2_adapter(make_mock_config())
+            pairs = sm.l2_adapters()
+            assert [d.index for d, _ in pairs] == [id0, id1]
+            a0, a1 = pairs[0][1], pairs[1][1]
+            assert a0 is not a1
+
+            # Deleting one leaves the survivor (same instance); order is by id.
+            sm.delete_l2_adapter(id0, timeout=10.0)
+            pairs = sm.l2_adapters()
+            assert len(pairs) == 1
+            assert pairs[0][0].index == id1
+            assert pairs[0][1] is a1
+        finally:
+            sm.close()
diff --git a/tests/v1/distributed/test_s3_l2_adapter.py b/tests/v1/distributed/test_s3_l2_adapter.py
new file mode 100644
index 0000000..3e53213
--- /dev/null
+++ b/tests/v1/distributed/test_s3_l2_adapter.py
@@ -0,0 +1,902 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for S3L2Adapter.
+
+The real ``awscrt.s3.S3Request`` is replaced with an in-memory fake that
+routes PUT/GET/HEAD/DELETE against a shared dict.  No network required.
+"""
+
+# Standard
+from concurrent.futures import Future as ConcurrentFuture
+import select
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.internal_api import L2AdapterListener
+from lmcache.v1.distributed.l2_adapters import s3_l2_adapter as s3mod
+from lmcache.v1.distributed.l2_adapters.s3_l2_adapter import (
+    S3L2Adapter,
+    S3L2AdapterConfig,
+    _object_key_to_string,
+)
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+# =============================================================================
+# Fake awscrt.s3.S3Request
+# =============================================================================
+
+
+class _FakeBackend:
+    """In-memory backing store shared by all fake S3Requests in a test."""
+
+    def __init__(self):
+        self._data: dict[str, bytes] = {}
+        self._lock = threading.Lock()
+        # When non-None, every request raises with this message
+        # (used to simulate network failures for the circuit-breaker test).
+        self._inject_error: str | None = None
+        self._put_count = 0
+        self._get_count = 0
+        self._delete_count = 0
+        self._head_count = 0
+
+    def reset(self):
+        with self._lock:
+            self._data.clear()
+            self._inject_error = None
+            self._put_count = self._get_count = 0
+            self._delete_count = self._head_count = 0
+
+    def get(self, key: str) -> bytes | None:
+        with self._lock:
+            return self._data.get(key)
+
+    def put(self, key: str, data: bytes):
+        with self._lock:
+            self._data[key] = data
+
+    def delete(self, key: str) -> bool:
+        with self._lock:
+            return self._data.pop(key, None) is not None
+
+    def contains(self, key: str) -> bool:
+        with self._lock:
+            return key in self._data
+
+    def set_error(self, msg: str | None):
+        with self._lock:
+            self._inject_error = msg
+
+    def counts(self) -> dict[str, int]:
+        with self._lock:
+            return {
+                "put": self._put_count,
+                "get": self._get_count,
+                "delete": self._delete_count,
+                "head": self._head_count,
+            }
+
+
+_BACKEND = _FakeBackend()
+
+
+def _path_to_key(path: str) -> str:
+    # Adapter uses url-encoded key in path; "@" is %-encoded. Reverse by
+    # unquoting.  Simpler: path always starts with "/", strip it, unquote.
+    # Standard
+    from urllib.parse import unquote
+
+    return unquote(path.lstrip("/"))
+
+
+def _build_list_objects_v2_response(
+    backend: "_FakeBackend",
+    prefix: str | None,
+    max_keys: int,
+    continuation_token: str | None,
+) -> bytes:
+    """Render a minimal ListObjectsV2 XML response from the fake backend.
+
+    The adapter's parser only consumes ``<Contents>/<Key>`` +
+    ``<Contents>/<Size>`` and ``<NextContinuationToken>``, so other
+    fields can be omitted. Continuation tokens here are just the
+    "start-after-this-key" cursor — opaque to the adapter, simple
+    enough for tests.
+    """
+    with backend._lock:
+        all_keys = sorted(backend._data.keys())
+        sizes = {k: len(backend._data[k]) for k in all_keys}
+
+    if prefix:
+        all_keys = [k for k in all_keys if k.startswith(prefix)]
+    if continuation_token is not None:
+        # In our fake, the token IS the last key returned on the
+        # previous page. Start strictly after it.
+        all_keys = [k for k in all_keys if k > continuation_token]
+
+    page = all_keys[:max_keys]
+    truncated = len(all_keys) > max_keys
+    next_token = page[-1] if (truncated and page) else None
+
+    body = ["<?xml version='1.0' encoding='UTF-8'?>"]
+    body.append("<ListBucketResult xmlns='http://s3.amazonaws.com/doc/2006-03-01/'>")
+    body.append(f"<IsTruncated>{'true' if truncated else 'false'}</IsTruncated>")
+    for k in page:
+        body.append(f"<Contents><Key>{k}</Key><Size>{sizes[k]}</Size></Contents>")
+    if next_token is not None:
+        body.append(f"<NextContinuationToken>{next_token}</NextContinuationToken>")
+    body.append("</ListBucketResult>")
+    return "".join(body).encode("utf-8")
+
+
+def _parse_list_query(path: str) -> tuple[str | None, int, str | None]:
+    """Pull ``prefix`` / ``max-keys`` / ``continuation-token`` out of the
+    ListObjectsV2 query string."""
+    # Standard
+    from urllib.parse import parse_qs, urlsplit
+
+    qs = parse_qs(urlsplit(path).query)
+    prefix = qs.get("prefix", [None])[0]
+    max_keys = int(qs.get("max-keys", ["1000"])[0])
+    cont = qs.get("continuation-token", [None])[0]
+    return prefix, max_keys, cont
+
+
+class _FakeS3Request:
+    """In-process substitute for awscrt.s3.S3Request.
+
+    Dispatches by HTTP method + operation_name against ``_BACKEND`` and
+    fires the on_headers / on_body / on_done callbacks that the real CRT
+    would invoke, then completes the finished_future.
+    """
+
+    def __init__(
+        self,
+        *,
+        client,
+        type,  # noqa: A002
+        request,
+        credential_provider,
+        region,
+        on_body=None,
+        on_done=None,
+        on_headers=None,
+        operation_name=None,
+        **kwargs,
+    ):
+        self.finished_future: ConcurrentFuture = ConcurrentFuture()
+
+        # Extract method + path from the HttpRequest
+        method = request.method
+        path = request.path
+
+        # ListObjectsV2 is dispatched as GET on the bucket root with a
+        # ``?list-type=2&...`` query string — intercept before the
+        # per-key GET branch below so it doesn't try to look up an
+        # object named "".
+        if (
+            method == "GET"
+            and operation_name == "ListObjectsV2"
+            and path.startswith("/?")
+        ):
+            prefix, max_keys, cont = _parse_list_query(path)
+            xml = _build_list_objects_v2_response(_BACKEND, prefix, max_keys, cont)
+            try:
+                if on_headers is not None:
+                    on_headers(200, [("content-type", "application/xml")])
+                if on_body is not None:
+                    on_body(xml, 0)
+                if on_done is not None:
+                    on_done(error=None, status_code=200)
+                self.finished_future.set_result(None)
+            except Exception as e:
+                if not self.finished_future.done():
+                    self.finished_future.set_exception(e)
+            return
+        key_str = _path_to_key(path)
+
+        err_inj = _BACKEND._inject_error
+
+        try:
+            if err_inj:
+                raise RuntimeError(err_inj)
+
+            if method == "PUT":
+                data = b""
+                body = request.body_stream
+                # body is a MemoryViewStream — read it fully
+                body.seek(0)
+                data = bytes(body.read())
+                _BACKEND.put(key_str, data)
+                with _BACKEND._lock:
+                    _BACKEND._put_count += 1
+                if on_headers is not None:
+                    on_headers(200, [])
+                if on_done is not None:
+                    on_done(error=None, status_code=200)
+                self.finished_future.set_result(None)
+
+            elif method == "GET":
+                with _BACKEND._lock:
+                    _BACKEND._get_count += 1
+                data = _BACKEND.get(key_str)
+                if data is None:
+                    if on_done is not None:
+                        try:
+                            on_done(error=None, status_code=404)
+                        except Exception:
+                            pass
+                    self.finished_future.set_exception(
+                        RuntimeError(f"S3 GET 404 for {key_str}")
+                    )
+                    return
+                if on_body is not None:
+                    on_body(data, 0)
+                if on_done is not None:
+                    on_done(error=None, status_code=200)
+                self.finished_future.set_result(None)
+
+            elif method == "HEAD":
+                with _BACKEND._lock:
+                    _BACKEND._head_count += 1
+                data = _BACKEND.get(key_str)
+                if data is None:
+                    if on_headers is not None:
+                        on_headers(404, [])
+                    self.finished_future.set_exception(
+                        RuntimeError(f"S3 HEAD 404 for {key_str}")
+                    )
+                    return
+                if on_headers is not None:
+                    on_headers(200, [("content-length", str(len(data)))])
+                self.finished_future.set_result(None)
+
+            elif method == "DELETE":
+                with _BACKEND._lock:
+                    _BACKEND._delete_count += 1
+                _BACKEND.delete(key_str)
+                if on_headers is not None:
+                    on_headers(204, [])
+                if on_done is not None:
+                    on_done(error=None, status_code=204)
+                self.finished_future.set_result(None)
+
+            else:
+                self.finished_future.set_exception(
+                    RuntimeError(f"unexpected method {method}")
+                )
+
+        except Exception as e:
+            try:
+                if on_done is not None:
+                    on_done(error=str(e), status_code=None)
+            except Exception:
+                pass
+            if not self.finished_future.done():
+                self.finished_future.set_exception(e)
+
+
+class _FakeHttpRequest:
+    """Plain-Python HttpRequest that preserves body_stream as-is."""
+
+    def __init__(self, method, path, headers, body_stream=None):
+        self.method = method
+        self.path = path
+        self.headers = headers
+        self.body_stream = body_stream
+
+
+@pytest.fixture(autouse=True)
+def patch_s3_request(monkeypatch):
+    """Replace awscrt.s3.S3Request in the adapter with the in-memory fake.
+
+    Also patch HttpRequest so body_stream is preserved as a plain Python
+    object (real HttpRequest wraps it in an opaque awscrt InputStream).
+
+    Stubs the credentials provider so tests don't depend on boto3 or any
+    AWS credentials being present in the environment; mocked requests
+    never reach a real signer.
+    """
+    _BACKEND.reset()
+    monkeypatch.setattr(s3mod.s3, "S3Request", _FakeS3Request)
+    monkeypatch.setattr(s3mod, "HttpRequest", _FakeHttpRequest)
+    monkeypatch.setattr(
+        s3mod,
+        "_make_credentials_provider",
+        lambda _config: s3mod.auth.AwsCredentialsProvider.new_static(
+            "test-key", "test-secret"
+        ),
+    )
+    yield
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def create_object_key(chunk_id: int, model_name: str = "test_model") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def create_memory_obj(size: int = 16, fill_value: float = 1.0) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.float32)
+    raw_data.fill_(fill_value)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.float32,
+        address=0,
+        phy_size=size * 4,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if events:
+        try:
+            consume_fd(event_fd)
+        except BlockingIOError:
+            pass
+        return True
+    return False
+
+
+@pytest.fixture
+def adapter():
+    config = S3L2AdapterConfig(
+        s3_endpoint="s3://test-bucket",
+        s3_region="us-east-1",
+        s3_prefer_http2=False,  # skip TLS ALPN setup for faster init
+        # Keep awscrt EventLoopGroup tiny so CI runners with tight FD
+        # ulimits (each epoll event loop costs a few fds) don't exhaust
+        # file descriptors across ~15 adapter fixtures in this module.
+        # Production callers should leave this at the default 64.
+        s3_num_io_threads=1,
+        max_capacity_gb=0.001,  # 1 MB
+    )
+    a = S3L2Adapter(config)
+    yield a
+    a.close()
+
+
+class _RecordingListener(L2AdapterListener):
+    def __init__(self):
+        self.stored: list[list[ObjectKey]] = []
+        self.accessed: list[list[ObjectKey]] = []
+        self.deleted: list[list[ObjectKey]] = []
+
+    def on_l2_keys_stored(self, keys, sizes):
+        self.stored.append(list(keys))
+
+    def on_l2_keys_accessed(self, keys):
+        self.accessed.append(list(keys))
+
+    def on_l2_keys_deleted(self, keys):
+        self.deleted.append(list(keys))
+
+
+# =============================================================================
+# Key serialization
+# =============================================================================
+
+
+class TestObjectKeySerialization:
+    def test_format(self):
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+        )
+        assert _object_key_to_string(key) == "llama@000000ff@0@00010203"
+
+    def test_object_group_id_embedded(self):
+        key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+            object_group_id=5,
+        )
+        assert _object_key_to_string(key) == "llama@000000ff@5@00010203"
+
+    def test_cache_salt_appended(self):
+        """A non-empty cache_salt must be included in the S3 object name so
+        two users with the same model/rank/chunk map to distinct objects.
+        """
+        base_key = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+        )
+        salted = ObjectKey(
+            chunk_hash=b"\x00\x01\x02\x03",
+            model_name="llama",
+            kv_rank=255,
+            cache_salt="user-42",
+        )
+        assert _object_key_to_string(base_key) == "llama@000000ff@0@00010203"
+        assert _object_key_to_string(salted) == "llama@000000ff@0@00010203@user-42"
+        assert _object_key_to_string(base_key) != _object_key_to_string(salted)
+
+
+# =============================================================================
+# Event fd interface
+# =============================================================================
+
+
+class TestEventFdInterface:
+    def test_three_distinct_fds(self, adapter):
+        a = adapter.get_store_event_fd()
+        b = adapter.get_lookup_and_lock_event_fd()
+        c = adapter.get_load_event_fd()
+        assert a >= 0 and b >= 0 and c >= 0
+        assert len({a, b, c}) == 3
+
+
+# =============================================================================
+# Round-trip
+# =============================================================================
+
+
+class TestStoreLookupLoad:
+    def test_roundtrip_single_key(self, adapter):
+        key = create_object_key(1)
+        obj = create_memory_obj(fill_value=3.14)
+
+        # Store
+        tid = adapter.submit_store_task([key], [obj])
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        completed = adapter.pop_completed_store_tasks()
+        assert completed[tid].is_successful()
+
+        # Lookup
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        bm = adapter.query_lookup_and_lock_result(tid)
+        assert bm is not None and bm.test(0) is True
+
+        # Load into a fresh buffer and verify the bytes match.
+        dst = create_memory_obj(fill_value=0.0)
+        tid = adapter.submit_load_task([key], [dst])
+        assert wait_for_event_fd(adapter.get_load_event_fd())
+        bm = adapter.query_load_result(tid)
+        assert bm is not None and bm.test(0) is True
+        assert torch.allclose(dst.tensor, torch.full((16,), 3.14))
+
+    def test_partial_hits(self, adapter):
+        # Store keys 0, 2
+        stored = [create_object_key(0), create_object_key(2)]
+        objs = [create_memory_obj(fill_value=float(i)) for i in range(2)]
+        adapter.submit_store_task(stored, objs)
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+        # Lookup 0, 1, 2, 3 — expect bitmap 1010
+        keys = [create_object_key(i) for i in range(4)]
+        tid = adapter.submit_lookup_and_lock_task(keys, _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        bm = adapter.query_lookup_and_lock_result(tid)
+        assert bm is not None
+        assert bm.test(0) is True
+        assert bm.test(1) is False
+        assert bm.test(2) is True
+        assert bm.test(3) is False
+
+    def test_load_miss_returns_zero_bit(self, adapter):
+        key = create_object_key(99)
+        dst = create_memory_obj()
+        tid = adapter.submit_load_task([key], [dst])
+        wait_for_event_fd(adapter.get_load_event_fd())
+        bm = adapter.query_load_result(tid)
+        assert bm is not None
+        assert bm.test(0) is False
+
+    def test_query_lookup_returns_none_after_pop(self, adapter):
+        key = create_object_key(1)
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        assert adapter.query_lookup_and_lock_result(tid) is not None
+        assert adapter.query_lookup_and_lock_result(tid) is None
+
+
+# =============================================================================
+# Eviction (delete + locking)
+# =============================================================================
+
+
+class TestEviction:
+    def _store(self, adapter, key, obj):
+        adapter.submit_store_task([key], [obj])
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+    def _lookup(self, adapter, key):
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        return adapter.query_lookup_and_lock_result(tid)
+
+    def test_delete_removes_key(self, adapter):
+        key = create_object_key(1)
+        self._store(adapter, key, create_memory_obj())
+        assert _BACKEND.contains(_object_key_to_string(key))
+        adapter.delete([key])
+        assert not _BACKEND.contains(_object_key_to_string(key))
+
+    def test_lock_blocks_delete(self, adapter):
+        key = create_object_key(1)
+        self._store(adapter, key, create_memory_obj())
+        bm = self._lookup(adapter, key)  # bumps refcount
+        assert bm.test(0) is True
+
+        deletes_before = _BACKEND.counts()["delete"]
+        adapter.delete([key])
+        assert _BACKEND.counts()["delete"] == deletes_before
+        # Still there.
+        assert _BACKEND.contains(_object_key_to_string(key))
+
+        adapter.submit_unlock([key])
+        adapter.delete([key])
+        assert not _BACKEND.contains(_object_key_to_string(key))
+
+    def test_refcount_unlock(self, adapter):
+        key = create_object_key(1)
+        self._store(adapter, key, create_memory_obj())
+        self._lookup(adapter, key)
+        self._lookup(adapter, key)  # refcount now 2
+
+        adapter.submit_unlock([key])  # refcount 1, still locked
+        adapter.delete([key])
+        assert _BACKEND.contains(_object_key_to_string(key))
+
+        adapter.submit_unlock([key])  # refcount 0
+        adapter.delete([key])
+        assert not _BACKEND.contains(_object_key_to_string(key))
+
+    def test_delete_on_unknown_key(self, adapter):
+        # Should not raise.
+        adapter.delete([create_object_key(42)])
+
+
+# =============================================================================
+# get_usage
+# =============================================================================
+
+
+class TestGetUsage:
+    def test_disabled_returns_minus_one(self):
+        cfg = S3L2AdapterConfig(
+            s3_endpoint="s3://b",
+            s3_region="r",
+            s3_prefer_http2=False,
+            s3_num_io_threads=1,
+            max_capacity_gb=0.0,
+        )
+        a = S3L2Adapter(cfg)
+        try:
+            usage = a.get_usage()
+            assert usage.usage_fraction == -1.0
+            assert usage.total_bytes_used == 0
+            assert usage.total_capacity_bytes == 0
+        finally:
+            a.close()
+
+    def test_usage_grows_on_store_and_shrinks_on_delete(self, adapter):
+        # adapter max_capacity_gb = 0.001 = 1 MB
+        # each obj is 16 floats = 64 bytes
+        keys = [create_object_key(i) for i in range(4)]
+        objs = [create_memory_obj() for _ in range(4)]
+
+        adapter.submit_store_task(keys, objs)
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+        total = 4 * 64
+        capacity = int(0.001 * 1024**3)
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == total
+        assert usage.total_capacity_bytes == capacity
+        assert usage.usage_fraction == pytest.approx(total / capacity)
+
+        adapter.delete(keys)
+        usage = adapter.get_usage()
+        assert usage.total_bytes_used == 0
+        assert usage.usage_fraction == 0.0
+
+
+# =============================================================================
+# Circuit breaker
+# =============================================================================
+
+
+class TestCircuitBreaker:
+    def test_trips_after_three_connection_errors(self, adapter):
+        _BACKEND.set_error("CONNECTION_REFUSED: mock")
+
+        keys = [create_object_key(i) for i in range(3)]
+        for k in keys:
+            obj = create_memory_obj()
+            adapter.submit_store_task([k], [obj])
+            wait_for_event_fd(adapter.get_store_event_fd(), timeout=2.0)
+            adapter.pop_completed_store_tasks()
+
+        status = adapter.report_status()
+        assert status["connection_disabled"] is True
+        assert status["is_healthy"] is False
+
+        # Subsequent submit short-circuits.
+        _BACKEND.set_error(None)  # even if we un-inject, the breaker is tripped
+        put_before = _BACKEND.counts()["put"]
+        disabled_tid = adapter.submit_store_task(
+            [create_object_key(42)], [create_memory_obj()]
+        )
+        wait_for_event_fd(adapter.get_store_event_fd(), timeout=2.0)
+        completed = adapter.pop_completed_store_tasks()
+        assert not completed[disabled_tid].is_successful()
+        assert _BACKEND.counts()["put"] == put_before  # never reached the backend
+
+        # Lookup and load also short-circuit to all-zero bitmaps.
+        tid = adapter.submit_lookup_and_lock_task([create_object_key(1)], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd(), timeout=2.0)
+        bm = adapter.query_lookup_and_lock_result(tid)
+        assert bm is not None and bm.test(0) is False
+
+        tid = adapter.submit_load_task([create_object_key(1)], [create_memory_obj()])
+        wait_for_event_fd(adapter.get_load_event_fd(), timeout=2.0)
+        bm = adapter.query_load_result(tid)
+        assert bm is not None and bm.test(0) is False
+
+
+# =============================================================================
+# Listener notifications
+# =============================================================================
+
+
+class TestListener:
+    def test_stored_and_deleted_fire(self, adapter):
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        key = create_object_key(1)
+        adapter.submit_store_task([key], [create_memory_obj()])
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+        # Give the coroutine a moment to fire notify; it fires inline but
+        # on the loop thread, so yield briefly.
+        time.sleep(0.05)
+        assert any(key in batch for batch in listener.stored)
+
+        adapter.delete([key])
+        assert any(key in batch for batch in listener.deleted)
+
+    def test_accessed_fires_on_hit(self, adapter):
+        listener = _RecordingListener()
+        adapter.register_listener(listener)
+
+        key = create_object_key(1)
+        adapter.submit_store_task([key], [create_memory_obj()])
+        wait_for_event_fd(adapter.get_store_event_fd())
+        adapter.pop_completed_store_tasks()
+
+        tid = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        adapter.query_lookup_and_lock_result(tid)
+        time.sleep(0.05)
+        assert any(key in batch for batch in listener.accessed)
+
+
+# =============================================================================
+# Config
+# =============================================================================
+
+
+class TestConfig:
+    def test_from_dict_requires_endpoint_and_region(self):
+        with pytest.raises(ValueError):
+            S3L2AdapterConfig.from_dict({"s3_region": "us-east-1"})
+        with pytest.raises(ValueError):
+            S3L2AdapterConfig.from_dict({"s3_endpoint": "s3://b"})
+
+    def test_from_dict_parses_all_fields(self):
+        cfg = S3L2AdapterConfig.from_dict(
+            {
+                "type": "s3",
+                "s3_endpoint": "s3://my-bucket",
+                "s3_region": "us-west-2",
+                "s3_num_io_threads": 32,
+                "s3_prefer_http2": False,
+                "s3_enable_s3express": True,
+                "disable_tls": True,
+                "aws_access_key_id": "id",
+                "aws_secret_access_key": "secret",
+                "max_capacity_gb": 2.5,
+            }
+        )
+        assert cfg.s3_endpoint == "s3://my-bucket"
+        assert cfg.s3_region == "us-west-2"
+        assert cfg.s3_num_io_threads == 32
+        assert cfg.s3_prefer_http2 is False
+        assert cfg.s3_enable_s3express is True
+        assert cfg.disable_tls is True
+        assert cfg.aws_access_key_id == "id"
+        assert cfg.aws_secret_access_key == "secret"
+        assert cfg.max_capacity_gb == 2.5
+
+    def test_help_nonempty(self):
+        assert isinstance(S3L2AdapterConfig.help(), str)
+        assert "s3_endpoint" in S3L2AdapterConfig.help()
+
+
+# =============================================================================
+# Factory registration
+# =============================================================================
+
+
+class TestFactoryRegistration:
+    def test_create_l2_adapter_registers_s3(self):
+        # First Party
+        from lmcache.v1.distributed.l2_adapters import create_l2_adapter
+
+        cfg = S3L2AdapterConfig.from_dict(
+            {
+                "type": "s3",
+                "s3_endpoint": "s3://fac-test",
+                "s3_region": "us-east-1",
+                "s3_prefer_http2": False,
+                "s3_num_io_threads": 1,
+            }
+        )
+        adp = create_l2_adapter(cfg)
+        try:
+            assert isinstance(adp, S3L2Adapter)
+        finally:
+            adp.close()
+
+
+# =============================================================================
+# list_l2_keys
+# =============================================================================
+#
+# These tests populate the fake S3 backend directly via ``_BACKEND.put``,
+# bypassing the adapter's store pipeline. The listing path is what's
+# under test: ListObjectsV2 dispatch, XML parse, prefix filter, and
+# cursor pagination.
+
+
+def _put_object(key: ObjectKey, size: int = 0) -> None:
+    """Place a key in the fake S3 backend with deterministic content.
+
+    Mirrors the production PUT pipeline: ``_object_key_to_string`` →
+    ``_format_safe_path`` (URL-encoding only — no path-flattening) →
+    URL-unquote in the fake → backend storage. So the fake's stored
+    name is byte-identical to the literal S3 object name a real PUT
+    would land.
+    """
+    # First Party
+    from lmcache.v1.distributed.l2_adapters.s3_l2_adapter import (
+        _object_key_to_string,
+    )
+
+    _BACKEND.put(_object_key_to_string(key), b"\x00" * size)
+
+
+class TestS3L2AdapterListKeys:
+    def test_empty_bucket_returns_empty_page(self, adapter):
+        page = adapter.list_l2_keys()
+        assert page.entries == ()
+        assert page.next_page_token is None
+
+    def test_lists_all_keys_when_unfiltered(self, adapter):
+        for i in range(3):
+            _put_object(create_object_key(i, model_name="llama"), size=100 + i)
+
+        page = adapter.list_l2_keys(page_size=10)
+
+        assert len(page.entries) == 3
+        assert {e.size_bytes for e in page.entries} == {100, 101, 102}
+        assert page.next_page_token is None
+
+    def test_model_name_pushed_down_as_prefix(self, adapter):
+        llama = ObjectKey(chunk_hash=b"\x00" * 4, model_name="llama", kv_rank=0)
+        mistral = ObjectKey(chunk_hash=b"\x00" * 4, model_name="mistral", kv_rank=0)
+        _put_object(llama, size=1)
+        _put_object(mistral, size=1)
+
+        page = adapter.list_l2_keys(model_name="llama", page_size=10)
+        assert [e.key for e in page.entries] == [llama.to_encoded_object_key()]
+
+    def test_model_name_with_slash_round_trips(self, adapter):
+        # Real HF model ids contain ``/``. The adapter stores the
+        # literal object name on S3 (no path-flattening) and the
+        # listing decodes it back unchanged.
+        original = ObjectKey(
+            chunk_hash=b"\xde\xad\xbe\xef",
+            model_name="meta-llama/Llama-3.1-8B",
+            kv_rank=7,
+        )
+        encoded = original.to_encoded_object_key()
+        _put_object(original, size=128)
+
+        # The listing returns the original model_name (slash intact).
+        page = adapter.list_l2_keys(page_size=10)
+        assert len(page.entries) == 1
+        assert page.entries[0].key == encoded
+        assert page.entries[0].key.model_name == "meta-llama/Llama-3.1-8B"
+
+        # And the model_name filter accepts the caller-supplied form
+        # verbatim — no encoding magic to remember.
+        page = adapter.list_l2_keys(model_name="meta-llama/Llama-3.1-8B", page_size=10)
+        assert [e.key for e in page.entries] == [encoded]
+
+    def test_pagination_cursor_walks_full_set(self, adapter):
+        # 5 keys, page_size=2 → expect 3 calls: (0,1), (2,3), (4,).
+        for i in range(5):
+            _put_object(create_object_key(i, model_name="llama"), size=1)
+
+        collected = []
+        cursor = None
+        while True:
+            page = adapter.list_l2_keys(page_size=2, cursor=cursor)
+            collected.extend(page.entries)
+            cursor = page.next_page_token
+            if cursor is None:
+                break
+        assert len(collected) == 5
+
+    def test_page_size_must_be_positive(self, adapter):
+        with pytest.raises(ValueError):
+            adapter.list_l2_keys(page_size=0)
+
+    def test_page_size_clamped_to_s3_max(self, adapter):
+        # Ask for far more than S3's MaxKeys ceiling. The adapter
+        # clamps internally and the fake honors whatever it receives,
+        # so 5 keys come back without error.
+        for i in range(5):
+            _put_object(create_object_key(i, model_name="m"), size=1)
+        page = adapter.list_l2_keys(page_size=999_999)
+        assert len(page.entries) == 5
+        assert page.next_page_token is None
+
+    def test_circuit_breaker_blocks_listing(self, adapter):
+        # When the connection is disabled, listing must surface a
+        # clear error instead of issuing a doomed request.
+        with adapter._lock:
+            adapter._connection_disabled = True
+        with pytest.raises(RuntimeError) as exc:
+            adapter.list_l2_keys()
+        assert "disabled" in str(exc.value)
+
+    def test_unparsable_objects_silently_skipped(self, adapter):
+        # An object with a name that isn't this adapter's format
+        # (e.g. left behind by another tool) must not poison the
+        # response — it's just dropped from the listing.
+        _put_object(create_object_key(0, model_name="m"), size=1)
+        _BACKEND.put("not-our-format-key", b"junk")
+
+        page = adapter.list_l2_keys(page_size=10)
+
+        assert len(page.entries) == 1
+        assert (
+            page.entries[0].key
+            == create_object_key(0, model_name="m").to_encoded_object_key()
+        )
diff --git a/tests/v1/distributed/test_storage_manager_l2_keys.py b/tests/v1/distributed/test_storage_manager_l2_keys.py
new file mode 100644
index 0000000..295149f
--- /dev/null
+++ b/tests/v1/distributed/test_storage_manager_l2_keys.py
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for ``StorageManager.l2_adapters()`` — the lookup the
+``DELETE /l2`` / ``GET /l2/keys`` / ``GET /l2/adapters`` HTTP handlers
+(and any future admin/coordinator tooling) use to reach configured L2
+adapters.
+
+Bypasses ``StorageManager.__init__`` (which requires CUDA, an
+L1Manager, and a full controller stack) and instead instantiates the
+class via ``__new__`` with only the two attributes the method reads:
+``_l2_adapters`` and ``_adapter_descriptors``.
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import cast
+import threading
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.base import L2AdapterInterface
+from lmcache.v1.distributed.storage_controllers.store_policy import AdapterDescriptor
+from lmcache.v1.distributed.storage_manager import StorageManager
+
+
+@dataclass
+class _StubDescriptor:
+    """Replaces ``AdapterDescriptor`` — only ``type_name`` is read."""
+
+    type_name: str
+
+
+class _StubAdapter:
+    """Identity-only stub. ``l2_adapters`` returns it by reference;
+    none of its methods are invoked by the unit under test."""
+
+
+def _make_sm(adapters: list[_StubAdapter], names: list[str]) -> StorageManager:
+    sm = StorageManager.__new__(StorageManager)
+    # ``_StubAdapter`` / ``_StubDescriptor`` only implement the surface
+    # the method under test actually reads. Cast through the real types
+    # for mypy. Adapters/descriptors are keyed by stable adapter id.
+    sm._adapters_lock = threading.Lock()
+    sm._l2_adapters = cast("dict[int, L2AdapterInterface]", dict(enumerate(adapters)))
+    sm._adapter_descriptors = cast(
+        "dict[int, AdapterDescriptor]",
+        {i: _StubDescriptor(type_name=n) for i, n in enumerate(names)},
+    )
+    return sm
+
+
+# =============================================================================
+# l2_adapters
+# =============================================================================
+
+
+class TestL2Adapters:
+    def test_returns_all_adapters_in_configuration_order(self):
+        a1, a2 = _StubAdapter(), _StubAdapter()
+        sm = _make_sm([a1, a2], ["s3", "fs"])
+
+        adapters = sm.l2_adapters()
+
+        # Pair-up matches configuration order; first element is primary.
+        assert len(adapters) == 2
+        assert adapters[0][1] is a1
+        assert adapters[0][0].type_name == "s3"
+        assert adapters[1][1] is a2
+        assert adapters[1][0].type_name == "fs"
+
+    def test_empty_when_no_adapters_configured(self):
+        sm = _make_sm([], [])
+        # Empty list — callers (typically HTTP handlers) decide how to
+        # surface it. The SM does not raise on its own.
+        assert sm.l2_adapters() == []
+
+    def test_single_adapter_round_trip(self):
+        a = _StubAdapter()
+        sm = _make_sm([a], ["s3"])
+
+        adapters = sm.l2_adapters()
+
+        assert len(adapters) == 1
+        desc, adapter = adapters[0]
+        assert adapter is a
+        assert desc.type_name == "s3"
+
+    def test_each_call_re_reads_the_list(self):
+        # The docstring promises the method re-reads ``_l2_adapters`` on
+        # every call so a runtime reconfigure (which swaps the adapter
+        # list) is picked up by the next caller. Simulate the swap by
+        # mutating ``_l2_adapters`` between two calls.
+        a1, a2 = _StubAdapter(), _StubAdapter()
+        sm = _make_sm([a1], ["s3"])
+
+        first = sm.l2_adapters()
+        assert first[0][1] is a1
+        assert first[0][0].type_name == "s3"
+
+        # Reconfigure: swap a1 → a2 (and the descriptor with it).
+        sm._l2_adapters = cast("dict[int, L2AdapterInterface]", {0: a2})
+        sm._adapter_descriptors = cast(
+            "dict[int, AdapterDescriptor]", {0: _StubDescriptor(type_name="fs")}
+        )
+
+        second = sm.l2_adapters()
+        assert second[0][1] is a2
+        assert second[0][0].type_name == "fs"
+
+    def test_returned_list_is_independent_of_internal_state(self):
+        # Callers may mutate the returned list without affecting SM
+        # state — the method returns a fresh copy.
+        a = _StubAdapter()
+        sm = _make_sm([a], ["s3"])
+        snapshot = sm.l2_adapters()
+        snapshot.clear()
+        assert len(sm.l2_adapters()) == 1
diff --git a/tests/v1/distributed/test_store_controller.py b/tests/v1/distributed/test_store_controller.py
new file mode 100644
index 0000000..0b90c34
--- /dev/null
+++ b/tests/v1/distributed/test_store_controller.py
@@ -0,0 +1,724 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for StoreController.
+
+Tests verify the end-to-end flow: L1 write -> listener notification ->
+L2 store submission -> completion handling -> L1 read lock release.
+
+Uses a real L1Manager and MockL2Adapter (with debug methods) to exercise
+the full integration without mocking internals.
+"""
+
+# Standard
+import select
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.config import L1ManagerConfig, L1MemoryManagerConfig
+from lmcache.v1.distributed.eviction_policy.noop import (
+    NoOpEvictionPolicy,
+)
+from lmcache.v1.distributed.l1_manager import L1Manager
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import (
+    MockL2Adapter,
+    MockL2AdapterConfig,
+)
+from lmcache.v1.distributed.storage_controllers.store_controller import (
+    StoreController,
+    StoreListener,
+)
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+    BufferOnlyStorePolicy,
+    DefaultStorePolicy,
+    StorePolicy,
+)
+
+# Skip all tests in this module if CUDA is not available
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA is not available"
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_layout() -> MemoryLayoutDesc:
+    """Create a small MemoryLayoutDesc for testing."""
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([100, 2, 512])],
+        dtypes=[torch.bfloat16],
+    )
+
+
+def should_use_lazy_alloc() -> bool:
+    """Determine if lazy allocation should be used based on CUDA availability."""
+    return torch.cuda.is_available()
+
+
+def wait_for_condition(
+    predicate,
+    timeout: float = 5.0,
+    poll_interval: float = 0.05,
+) -> bool:
+    """
+    Poll until a predicate returns True or timeout.
+
+    Args:
+        predicate: Callable returning bool.
+        timeout: Max wait time in seconds.
+        poll_interval: Time between polls in seconds.
+
+    Returns:
+        True if predicate was satisfied, False on timeout.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if predicate():
+            return True
+        time.sleep(poll_interval)
+    return False
+
+
+def write_keys_to_l1(
+    l1_manager: L1Manager,
+    keys: list[ObjectKey],
+    layout: MemoryLayoutDesc,
+) -> list[ObjectKey]:
+    """
+    Write keys to L1 (reserve_write + finish_write).
+
+    Args:
+        l1_manager: The L1 manager to write to.
+        keys: Object keys to write.
+        layout: Memory layout description.
+
+    Returns:
+        List of keys that were successfully written.
+    """
+    results = l1_manager.reserve_write(
+        keys=keys,
+        is_temporary=[False] * len(keys),
+        layout_desc=layout,
+        mode="new",
+    )
+    written = [k for k, (e, m) in results.items() if m is not None]
+    if written:
+        l1_manager.finish_write(written)
+    return written
+
+
+# =============================================================================
+# Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def l1_manager():
+    """Create an L1Manager with a reasonable memory config."""
+    config = L1ManagerConfig(
+        memory_config=L1MemoryManagerConfig(
+            size_in_bytes=128 * 1024 * 1024,
+            use_lazy=should_use_lazy_alloc(),
+            init_size_in_bytes=64 * 1024 * 1024,
+            align_bytes=0x1000,
+        ),
+        write_ttl_seconds=600,
+        read_ttl_seconds=300,
+    )
+    mgr = L1Manager(config)
+    yield mgr
+    mgr.close()
+
+
+def make_adapter() -> MockL2Adapter:
+    """Create a MockL2Adapter with fast bandwidth."""
+    config = MockL2AdapterConfig(
+        max_size_gb=0.01,
+        mock_bandwidth_gb=10.0,
+    )
+    return MockL2Adapter(config)
+
+
+def make_descriptor(index: int) -> AdapterDescriptor:
+    """Create an AdapterDescriptor for testing."""
+    config = MockL2AdapterConfig(max_size_gb=0.01, mock_bandwidth_gb=10.0)
+    return AdapterDescriptor(index=index, config=config)
+
+
+# =============================================================================
+# StoreListener Tests
+# =============================================================================
+
+
+class TestStoreListener:
+    """Test StoreListener as a standalone component."""
+
+    def test_pop_pending_keys_returns_empty_initially(self):
+        """A fresh listener should have no pending keys."""
+        listener = StoreListener()
+        assert listener.pop_pending_keys() == []
+        listener.close()
+
+    def test_on_l1_keys_write_finished_enqueues_keys(self):
+        """Keys passed to on_l1_keys_write_finished should be retrievable via pop."""
+        listener = StoreListener()
+        keys = [make_object_key(i) for i in range(3)]
+
+        listener.on_l1_keys_write_finished(keys)
+        popped = listener.pop_pending_keys()
+
+        assert popped == keys
+        listener.close()
+
+    def test_pop_pending_keys_clears_queue(self):
+        """pop_pending_keys should drain the queue."""
+        listener = StoreListener()
+        listener.on_l1_keys_write_finished([make_object_key(0)])
+        listener.pop_pending_keys()
+
+        assert listener.pop_pending_keys() == []
+        listener.close()
+
+    def test_on_l1_keys_write_finished_signals_eventfd(self):
+        """The eventfd should become readable after on_l1_keys_write_finished."""
+        listener = StoreListener()
+        efd = listener.get_event_fd()
+        poller = select.poll()
+        poller.register(efd, select.POLLIN)
+
+        listener.on_l1_keys_write_finished([make_object_key(0)])
+
+        events = poller.poll(1000)
+        assert len(events) > 0
+        listener.close()
+
+    def test_multiple_writes_accumulate(self):
+        """Multiple on_l1_keys_write_finished calls should accumulate keys."""
+        listener = StoreListener()
+        listener.on_l1_keys_write_finished([make_object_key(0)])
+        listener.on_l1_keys_write_finished([make_object_key(1), make_object_key(2)])
+
+        popped = listener.pop_pending_keys()
+        assert len(popped) == 3
+        listener.close()
+
+    def test_finish_write_and_reserve_read_does_not_enqueue(self):
+        """on_l1_keys_finish_write_and_reserve_read should not enqueue keys."""
+        listener = StoreListener()
+        keys = [make_object_key(i) for i in range(3)]
+
+        listener.on_l1_keys_finish_write_and_reserve_read(keys)
+
+        assert listener.pop_pending_keys() == []
+        assert listener.pending_count() == 0
+        listener.close()
+
+
+# =============================================================================
+# StoreController Integration Tests
+# =============================================================================
+
+
+class TestStoreControllerLifecycle:
+    """Test StoreController start/stop behavior."""
+
+    def test_start_stop(self, l1_manager):
+        """StoreController should start and stop cleanly."""
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+        ctrl.stop()
+        adapter.close()
+
+    def test_start_stop_no_adapters(self, l1_manager):
+        """Controller should start and stop cleanly with no adapters."""
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+        ctrl.stop()
+
+
+class TestStoreControllerSingleAdapter:
+    """Test StoreController with one MockL2Adapter."""
+
+    def test_l1_write_triggers_l2_store(self, l1_manager):
+        """Writing to L1 should cause the object to appear in L2."""
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Wait for the object to appear in L2
+        ok = wait_for_condition(
+            lambda: adapter.debug_get_stored_object_count() == 1,
+            timeout=5.0,
+        )
+        assert ok, "Object should be stored in L2 after L1 write"
+        assert adapter.debug_has_key(keys[0])
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_multiple_keys_stored_to_l2(self, l1_manager):
+        """Multiple L1 writes should result in all keys in L2."""
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(5)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        ok = wait_for_condition(
+            lambda: adapter.debug_get_stored_object_count() == 5,
+            timeout=5.0,
+        )
+        assert ok, "All 5 objects should be stored in L2"
+        for key in keys:
+            assert adapter.debug_has_key(key)
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_read_lock_released_after_store(self, l1_manager):
+        """After L2 store completes, L1 read locks should be released."""
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Wait for L2 store to complete
+        ok = wait_for_condition(
+            lambda: adapter.debug_has_key(keys[0]),
+            timeout=5.0,
+        )
+        assert ok
+
+        # Verify read lock is released: the key should be updatable
+        ok = wait_for_condition(
+            lambda: l1_manager.reserve_write(
+                keys=keys,
+                is_temporary=[False],
+                layout_desc=layout,
+                mode="update",
+            )[keys[0]][1]
+            is not None,
+            timeout=5.0,
+        )
+        assert ok, "Key should be updatable after store controller releases read lock"
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_multiple_concurrent_requests_same_adapter(self, l1_manager):
+        """Each L1-write batch produces an independent in-flight store request.
+
+        When two batches target the same adapter, the adapter's single
+        eventfd may batch-signal both completions. All in-flight requests
+        should be advanced and their L1 read locks released.
+        """
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        batch_a = [make_object_key(i) for i in range(3)]
+        batch_b = [make_object_key(i) for i in range(3, 6)]
+
+        write_keys_to_l1(l1_manager, batch_a, layout)
+        write_keys_to_l1(l1_manager, batch_b, layout)
+
+        all_keys = batch_a + batch_b
+        ok = wait_for_condition(
+            lambda: all(adapter.debug_has_key(k) for k in all_keys),
+            timeout=5.0,
+        )
+        assert ok, "Both batches should reach L2"
+
+        # Every key must be updatable: read locks from both requests released.
+        # ``reserve_write`` acquires a write lock on success, so release it
+        # via ``finish_write`` after each successful check — otherwise the
+        # second poll would find already-locked keys and time out.
+        def all_keys_updatable() -> bool:
+            for k in all_keys:
+                result = l1_manager.reserve_write(
+                    keys=[k],
+                    is_temporary=[False],
+                    layout_desc=layout,
+                    mode="update",
+                )
+                if result[k][1] is None:
+                    return False
+                l1_manager.finish_write([k])
+            return True
+
+        ok = wait_for_condition(all_keys_updatable, timeout=5.0)
+        assert ok, "Read locks must be released for every concurrent request"
+
+        ctrl.stop()
+        adapter.close()
+
+
+class TestStoreControllerMultipleAdapters:
+    """Test StoreController with multiple L2 adapters."""
+
+    def test_stores_to_all_adapters(self, l1_manager):
+        """DefaultStorePolicy sends keys to all adapters."""
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(i) for i in range(2)]
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,
+            adapter_descriptors=descriptors,
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Wait for both adapters to have the object
+        ok = wait_for_condition(
+            lambda: all(a.debug_has_key(keys[0]) for a in adapters),
+            timeout=5.0,
+        )
+        assert ok, "Object should be stored in both L2 adapters"
+
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+    def test_read_lock_released_after_all_adapters_complete(self, l1_manager):
+        """Read locks should be released after all adapter stores complete."""
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(i) for i in range(2)]
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,
+            adapter_descriptors=descriptors,
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Wait for stores to both adapters, then check updatability
+        ok = wait_for_condition(
+            lambda: all(a.debug_has_key(keys[0]) for a in adapters),
+            timeout=5.0,
+        )
+        assert ok
+
+        ok = wait_for_condition(
+            lambda: l1_manager.reserve_write(
+                keys=keys,
+                is_temporary=[False],
+                layout_desc=layout,
+                mode="update",
+            )[keys[0]][1]
+            is not None,
+            timeout=5.0,
+        )
+        assert ok, "Key should be updatable after all adapter stores complete"
+
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+
+class TestStoreControllerNoAdapters:
+    """Test StoreController with no L2 adapters."""
+
+    def test_write_with_no_adapters_no_read_lock(self, l1_manager):
+        """With no adapters, no read locks should be held after L1 write."""
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[],
+            adapter_descriptors=[],
+            policy=DefaultStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Give the controller time to process the listener event
+        time.sleep(0.3)
+
+        # Key should be updatable (no read locks)
+        result = l1_manager.reserve_write(
+            keys=keys,
+            is_temporary=[False],
+            layout_desc=layout,
+            mode="update",
+        )
+        assert result[keys[0]][1] is not None
+
+        ctrl.stop()
+
+
+class TestStoreControllerCustomPolicy:
+    """Test StoreController with custom StorePolicy implementations."""
+
+    def test_policy_that_skips_all_adapters(self, l1_manager):
+        """A policy returning empty targets should not trigger L2 stores."""
+
+        class SkipAllPolicy(StorePolicy):
+            """Never store to L2."""
+
+            def select_store_targets(self, keys, adapters):
+                return {}
+
+            def select_l1_deletions(self, keys):
+                return []
+
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=SkipAllPolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Give the controller time to process
+        time.sleep(0.5)
+
+        assert adapter.debug_get_stored_object_count() == 0, (
+            "No objects should be stored when policy skips all adapters"
+        )
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_policy_that_deletes_from_l1(self, l1_manager):
+        """A policy that requests L1 deletion should result in deleted keys."""
+
+        class DeleteAfterStorePolicy(StorePolicy):
+            """Delete all keys from L1 after storing to L2."""
+
+            def select_store_targets(self, keys, adapters):
+                return {ad.index: list(keys) for ad in adapters}
+
+            def select_l1_deletions(self, keys):
+                return list(keys)
+
+        adapter = make_adapter()
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=DeleteAfterStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Wait for L2 store and L1 deletion
+        ok = wait_for_condition(
+            lambda: adapter.debug_has_key(keys[0]),
+            timeout=5.0,
+        )
+        assert ok, "Object should be stored in L2"
+
+        # After deletion, reserve_write with mode="new" should succeed
+        ok = wait_for_condition(
+            lambda: l1_manager.reserve_write(
+                keys=keys,
+                is_temporary=[False],
+                layout_desc=layout,
+                mode="new",
+            )[keys[0]][1]
+            is not None,
+            timeout=5.0,
+        )
+        assert ok, "Key should be re-creatable after L1 deletion by policy"
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_policy_selects_subset_of_adapters(self, l1_manager):
+        """A policy that targets only some adapters should skip others."""
+
+        class FirstAdapterOnlyPolicy(StorePolicy):
+            """Only store to adapter index 0."""
+
+            def select_store_targets(self, keys, adapters):
+                for ad in adapters:
+                    if ad.index == 0:
+                        return {0: list(keys)}
+                return {}
+
+            def select_l1_deletions(self, keys):
+                return []
+
+        adapters = [make_adapter(), make_adapter()]
+        descriptors = [make_descriptor(i) for i in range(2)]
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=adapters,
+            adapter_descriptors=descriptors,
+            policy=FirstAdapterOnlyPolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        ok = wait_for_condition(
+            lambda: adapters[0].debug_has_key(keys[0]),
+            timeout=5.0,
+        )
+        assert ok, "Object should be stored in first adapter"
+
+        # Give some time and verify second adapter is empty
+        time.sleep(0.5)
+        assert adapters[1].debug_get_stored_object_count() == 0, (
+            "Second adapter should have no objects"
+        )
+
+        ctrl.stop()
+        for a in adapters:
+            a.close()
+
+
+class TestBufferOnlyMode:
+    """Test buffer-only mode: BufferOnlyStorePolicy + NoOpEvictionPolicy."""
+
+    def test_l1_cleaned_after_l2_store(self, l1_manager):
+        """L1 data should be deleted after successful L2 store."""
+        adapter = make_adapter()
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=BufferOnlyStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(0)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        # Wait for L2 store
+        ok = wait_for_condition(
+            lambda: adapter.debug_has_key(keys[0]),
+            timeout=5.0,
+        )
+        assert ok, "Object should be stored in L2"
+
+        # L1 should be cleaned: check key is gone
+        ok = wait_for_condition(
+            lambda: l1_manager.get_object_state(keys[0]) is None,
+            timeout=5.0,
+        )
+        assert ok, "Key should be deleted from L1 in buffer-only mode"
+
+        ctrl.stop()
+        adapter.close()
+
+    def test_noop_eviction_never_evicts(self):
+        """NoOpEvictionPolicy should never return eviction actions."""
+        noop = NoOpEvictionPolicy()
+        noop.on_keys_created([make_object_key(i) for i in range(10)])
+        assert noop.get_eviction_actions(1.0) == []
+
+    def test_buffer_only_multiple_keys(self, l1_manager):
+        """Multiple keys should all flow to L2 and be removed
+        from L1."""
+        adapter = make_adapter()
+
+        ctrl = StoreController(
+            l1_manager=l1_manager,
+            l2_adapters=[adapter],
+            adapter_descriptors=[make_descriptor(0)],
+            policy=BufferOnlyStorePolicy(),
+        )
+        ctrl.start()
+
+        layout = make_layout()
+        keys = [make_object_key(i) for i in range(5)]
+        write_keys_to_l1(l1_manager, keys, layout)
+
+        ok = wait_for_condition(
+            lambda: adapter.debug_get_stored_object_count() == 5,
+            timeout=5.0,
+        )
+        assert ok, "All 5 objects should be stored in L2"
+
+        # All keys should be gone from L1
+        ok = wait_for_condition(
+            lambda: all(l1_manager.get_object_state(k) is None for k in keys),
+            timeout=5.0,
+        )
+        assert ok, "All keys should be deleted from L1 after buffer-only cleanup"
+
+        ctrl.stop()
+        adapter.close()
diff --git a/tests/v1/distributed/test_store_policy.py b/tests/v1/distributed/test_store_policy.py
new file mode 100644
index 0000000..c83d4a9
--- /dev/null
+++ b/tests/v1/distributed/test_store_policy.py
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for store policy interface and DefaultStorePolicy.
+
+Tests are written against the StorePolicy contract defined in store_policy.py.
+"""
+
+# Third Party
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.l2_adapters.mock_l2_adapter import MockL2AdapterConfig
+from lmcache.v1.distributed.storage_controllers.store_policy import (
+    AdapterDescriptor,
+    DefaultStorePolicy,
+)
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+
+def make_object_key(chunk_id: int) -> ObjectKey:
+    """Create a test ObjectKey with the given chunk ID."""
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+def make_descriptor(index: int) -> AdapterDescriptor:
+    """Create an AdapterDescriptor for testing."""
+    config = MockL2AdapterConfig(max_size_gb=1.0, mock_bandwidth_gb=10.0)
+    return AdapterDescriptor(index=index, config=config)
+
+
+# =============================================================================
+# DefaultStorePolicy Tests
+# =============================================================================
+
+
+class TestDefaultStorePolicyTargets:
+    """Test DefaultStorePolicy.select_store_targets behavior."""
+
+    def test_single_adapter_all_keys(self):
+        """All keys should be sent to the single adapter."""
+        policy = DefaultStorePolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0)]
+
+        result = policy.select_store_targets(keys, adapters)
+
+        assert 0 in result
+        assert result[0] == keys
+
+    def test_multiple_adapters_all_keys_to_each(self):
+        """All keys should be sent to every adapter."""
+        policy = DefaultStorePolicy()
+        keys = [make_object_key(i) for i in range(3)]
+        adapters = [make_descriptor(0), make_descriptor(1)]
+
+        result = policy.select_store_targets(keys, adapters)
+
+        assert len(result) == 2
+        assert result[0] == keys
+        assert result[1] == keys
+
+    def test_empty_adapters_returns_empty(self):
+        """No adapters means no store targets."""
+        policy = DefaultStorePolicy()
+        keys = [make_object_key(0)]
+
+        result = policy.select_store_targets(keys, [])
+
+        assert result == {}
+
+    def test_empty_keys_returns_empty_lists(self):
+        """Empty keys list should produce empty lists for each adapter."""
+        policy = DefaultStorePolicy()
+        adapters = [make_descriptor(0)]
+
+        result = policy.select_store_targets([], adapters)
+
+        assert 0 in result
+        assert result[0] == []
+
+    def test_returns_copies_not_references(self):
+        """Returned lists should be independent copies of the input."""
+        policy = DefaultStorePolicy()
+        keys = [make_object_key(0)]
+        adapters = [make_descriptor(0)]
+
+        result = policy.select_store_targets(keys, adapters)
+
+        # Mutating the result should not affect the input
+        result[0].append(make_object_key(99))
+        assert len(keys) == 1
+
+
+class TestDefaultStorePolicyDeletions:
+    """Test DefaultStorePolicy.select_l1_deletions behavior."""
+
+    def test_never_deletes(self):
+        """DefaultStorePolicy should never delete from L1."""
+        policy = DefaultStorePolicy()
+        keys = [make_object_key(i) for i in range(5)]
+
+        result = policy.select_l1_deletions(keys)
+
+        assert result == []
+
+    def test_empty_keys_returns_empty(self):
+        """Empty input should return empty output."""
+        policy = DefaultStorePolicy()
+
+        result = policy.select_l1_deletions([])
+
+        assert result == []
diff --git a/tests/v1/distributed/transfer_channel/__init__.py b/tests/v1/distributed/transfer_channel/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/distributed/transfer_channel/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/distributed/transfer_channel/test_api.py b/tests/v1/distributed/transfer_channel/test_api.py
new file mode 100644
index 0000000..2896ba2
--- /dev/null
+++ b/tests/v1/distributed/transfer_channel/test_api.py
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the transfer channel data types.
+
+Tests are written against the public contracts documented in
+``lmcache/v1/distributed/transfer_channel/api.py`` and exercise only the
+public interface.
+"""
+
+# Standard
+import dataclasses
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.transfer_channel import (
+    TransferChannelAddress,
+    TransferChannelReadResult,
+)
+
+
+# =========================================================
+# TransferChannelAddress
+# =========================================================
+def test_address_stores_offset_and_size():
+    addr = TransferChannelAddress(offset=128, size=64)
+    assert addr.offset == 128
+    assert addr.size == 64
+
+
+def test_address_is_immutable():
+    addr = TransferChannelAddress(offset=0, size=16)
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        addr.offset = 32  # type: ignore[misc]
+
+
+def test_addresses_with_same_fields_are_equal():
+    a = TransferChannelAddress(offset=10, size=20)
+    b = TransferChannelAddress(offset=10, size=20)
+    c = TransferChannelAddress(offset=10, size=21)
+    assert a == b
+    assert a != c
+
+
+# =========================================================
+# TransferChannelReadResult
+# =========================================================
+def test_read_result_succeeded_mask_defaults_to_empty_list():
+    result = TransferChannelReadResult(finished=False)
+    assert result.succeeded_mask == []
+
+
+def test_read_result_is_finished_reflects_finished_flag():
+    in_flight = TransferChannelReadResult(finished=False)
+    done = TransferChannelReadResult(finished=True)
+    assert in_flight.is_finished() is False
+    assert done.is_finished() is True
+
+
+def test_read_result_succeeded_mask_returns_flags():
+    result = TransferChannelReadResult(finished=True, succeeded_mask=[True, False])
+    assert result.succeeded_mask == [True, False]
+
+
+def test_read_result_default_succeeded_masks_are_independent():
+    a = TransferChannelReadResult(finished=False)
+    b = TransferChannelReadResult(finished=False)
+    a.succeeded_mask.append(True)
+    assert b.succeeded_mask == []
diff --git a/tests/v1/distributed/transfer_channel/test_context_lifecycle.py b/tests/v1/distributed/transfer_channel/test_context_lifecycle.py
new file mode 100644
index 0000000..902e0f3
--- /dev/null
+++ b/tests/v1/distributed/transfer_channel/test_context_lifecycle.py
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the global transfer channel context lifecycle:
+``initialize_transfer_channel_context``, ``get_transfer_channel_context`` and
+``delete_transfer_channel_context``.
+
+Tests are written against the documented contracts in
+``lmcache/v1/distributed/transfer_channel/__init__.py`` and use only the
+public interface.
+"""
+
+# Standard
+from collections.abc import Iterator
+import itertools
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.transfer_channel import (
+    TransferChannelContext,
+    delete_transfer_channel_context,
+    get_transfer_channel_context,
+    initialize_transfer_channel_context,
+)
+from lmcache.v1.distributed.transfer_channel.factory import (
+    register_transfer_channel_factory,
+)
+
+_name_counter = itertools.count()
+
+
+def _unique_type_name() -> str:
+    return f"test_lifecycle_{next(_name_counter)}"
+
+
+class _FakeContext(TransferChannelContext):
+    """Context double that records whether ``close`` was called."""
+
+    def __init__(self, **kwargs) -> None:
+        self.created_kwargs = kwargs
+        self.closed = False
+
+    def get_transfer_channel_server(self):
+        raise NotImplementedError
+
+    def get_transfer_channel_client(self, peer_advertise_url: str):
+        raise NotImplementedError
+
+    def remove_transfer_channel_client(self, peer_advertise_url: str) -> None:
+        raise NotImplementedError
+
+    def get_transfer_channel_address(self, lmcache_addresses):
+        raise NotImplementedError
+
+    def get_num_connected_clients(self) -> int:
+        return 0
+
+    def close(self) -> None:
+        self.closed = True
+
+
+@pytest.fixture
+def fake_type() -> Iterator[str]:
+    """Register a fake factory and guarantee the global context is cleared."""
+    name = _unique_type_name()
+    register_transfer_channel_factory(name, lambda **kw: _FakeContext(**kw))
+    try:
+        yield name
+    finally:
+        delete_transfer_channel_context()
+
+
+def _l1_desc() -> L1MemoryDesc:
+    return L1MemoryDesc(ptr=0, size=4096, align_bytes=256)
+
+
+def test_get_before_initialize_raises_runtime_error(fake_type):
+    with pytest.raises(RuntimeError):
+        get_transfer_channel_context()
+
+
+def test_initialize_returns_context_and_get_returns_same(fake_type):
+    ctx = initialize_transfer_channel_context(
+        transfer_channel_type=fake_type,
+        l1_memory_desc=_l1_desc(),
+        listen_url="0.0.0.0:7600",
+        advertise_url="host:7600",
+    )
+    assert isinstance(ctx, TransferChannelContext)
+    assert get_transfer_channel_context() is ctx
+
+
+def test_double_initialize_raises_runtime_error(fake_type):
+    initialize_transfer_channel_context(
+        transfer_channel_type=fake_type,
+        l1_memory_desc=_l1_desc(),
+        listen_url="0.0.0.0:7600",
+        advertise_url="host:7600",
+    )
+    with pytest.raises(RuntimeError):
+        initialize_transfer_channel_context(
+            transfer_channel_type=fake_type,
+            l1_memory_desc=_l1_desc(),
+            listen_url="0.0.0.0:7601",
+            advertise_url="host:7601",
+        )
+
+
+def test_delete_closes_context_and_get_raises_again(fake_type):
+    ctx = initialize_transfer_channel_context(
+        transfer_channel_type=fake_type,
+        l1_memory_desc=_l1_desc(),
+        listen_url="0.0.0.0:7600",
+        advertise_url="host:7600",
+    )
+    delete_transfer_channel_context()
+    assert ctx.closed is True
+    with pytest.raises(RuntimeError):
+        get_transfer_channel_context()
+
+
+def test_delete_without_initialize_is_noop(fake_type):
+    # Should not raise even when no context exists.
+    delete_transfer_channel_context()
+
+
+def test_reinitialize_after_delete_succeeds(fake_type):
+    first = initialize_transfer_channel_context(
+        transfer_channel_type=fake_type,
+        l1_memory_desc=_l1_desc(),
+        listen_url="0.0.0.0:7600",
+        advertise_url="host:7600",
+    )
+    delete_transfer_channel_context()
+    second = initialize_transfer_channel_context(
+        transfer_channel_type=fake_type,
+        l1_memory_desc=_l1_desc(),
+        listen_url="0.0.0.0:7600",
+        advertise_url="host:7600",
+    )
+    assert second is not first
+    assert get_transfer_channel_context() is second
diff --git a/tests/v1/distributed/transfer_channel/test_factory.py b/tests/v1/distributed/transfer_channel/test_factory.py
new file mode 100644
index 0000000..374ceab
--- /dev/null
+++ b/tests/v1/distributed/transfer_channel/test_factory.py
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the transfer channel factory registry.
+
+Tests are written against the documented contracts of
+``register_transfer_channel_factory`` and ``create_transfer_channel_context``
+in ``lmcache/v1/distributed/transfer_channel/factory.py`` and use only the
+public interface.
+"""
+
+# Standard
+import itertools
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.internal_api import L1MemoryDesc
+from lmcache.v1.distributed.transfer_channel import (
+    TransferChannelContext,
+)
+from lmcache.v1.distributed.transfer_channel.factory import (
+    create_transfer_channel_context,
+    register_transfer_channel_factory,
+)
+
+# Unique-name generator so each test registers a fresh type name (the registry
+# is process-global and rejects duplicate registrations).
+_name_counter = itertools.count()
+
+
+def _unique_type_name() -> str:
+    return f"test_fake_{next(_name_counter)}"
+
+
+class _FakeContext(TransferChannelContext):
+    """Minimal context double recording the kwargs it was created with."""
+
+    def __init__(self, **kwargs) -> None:
+        self.created_kwargs = kwargs
+
+    def get_transfer_channel_server(self):
+        raise NotImplementedError
+
+    def get_transfer_channel_client(self, peer_advertise_url: str):
+        raise NotImplementedError
+
+    def remove_transfer_channel_client(self, peer_advertise_url: str) -> None:
+        raise NotImplementedError
+
+    def get_transfer_channel_address(self, lmcache_addresses):
+        raise NotImplementedError
+
+    def get_num_connected_clients(self) -> int:
+        return 0
+
+    def close(self) -> None:
+        pass
+
+
+def _l1_desc() -> L1MemoryDesc:
+    return L1MemoryDesc(ptr=0, size=4096, align_bytes=256)
+
+
+# =========================================================
+# register_transfer_channel_factory
+# =========================================================
+def test_create_invokes_registered_factory_with_kwargs():
+    name = _unique_type_name()
+    register_transfer_channel_factory(name, lambda **kw: _FakeContext(**kw))
+
+    desc = _l1_desc()
+    ctx = create_transfer_channel_context(
+        transfer_channel_type=name,
+        l1_memory_desc=desc,
+        listen_url="0.0.0.0:7600",
+        advertise_url="host:7600",
+        backends=["UCX"],
+    )
+
+    assert isinstance(ctx, _FakeContext)
+    assert ctx.created_kwargs["l1_memory_desc"] is desc
+    assert ctx.created_kwargs["listen_url"] == "0.0.0.0:7600"
+    assert ctx.created_kwargs["advertise_url"] == "host:7600"
+    # Implementation-specific kwargs are forwarded as-is.
+    assert ctx.created_kwargs["backends"] == ["UCX"]
+
+
+def test_register_duplicate_type_raises_value_error():
+    name = _unique_type_name()
+    register_transfer_channel_factory(name, lambda **kw: _FakeContext(**kw))
+    with pytest.raises(ValueError):
+        register_transfer_channel_factory(name, lambda **kw: _FakeContext(**kw))
+
+
+# =========================================================
+# create_transfer_channel_context
+# =========================================================
+def test_create_unregistered_type_raises_value_error():
+    with pytest.raises(ValueError):
+        create_transfer_channel_context(
+            transfer_channel_type=_unique_type_name(),
+            l1_memory_desc=_l1_desc(),
+            listen_url="0.0.0.0:7600",
+            advertise_url="host:7600",
+        )
diff --git a/tests/v1/distributed/transfer_channel/test_nixl_impl.py b/tests/v1/distributed/transfer_channel/test_nixl_impl.py
new file mode 100644
index 0000000..857f558
--- /dev/null
+++ b/tests/v1/distributed/transfer_channel/test_nixl_impl.py
@@ -0,0 +1,236 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Integration tests for the nixl-backed transfer channel implementation.
+
+Tests are written against the public contracts documented in
+``transfer_channel/abstract.py`` and ``transfer_channel/api.py`` (the
+``TransferChannelContext`` / ``TransferChannelServer`` / ``TransferChannelClient``
+interfaces). They use only public methods and do not access private fields.
+
+These tests require a working nixl runtime (with a UCX backend) and are skipped
+when nixl is unavailable.
+
+Most tests share a single module-scoped context-pair to avoid paying the (slow)
+nixl agent initialization for every test. The reads are self-verifying -- each
+reads fresh remote data into its target region and checks that region -- so a
+reused buffer and connection do not affect their outcome. The one test that must
+observe a pristine connection state (the 0 -> 1 connection-count transition)
+uses its own function-scoped pair instead, since there is no public way to reset
+an existing context's connected clients short of closing it.
+"""
+
+# Standard
+from unittest.mock import MagicMock
+import itertools
+import time
+
+# Third Party
+import pytest
+import torch
+
+nixl = pytest.importorskip("nixl")
+
+# First Party
+from lmcache.v1.distributed.internal_api import L1MemoryDesc  # noqa: E402
+from lmcache.v1.distributed.transfer_channel.impl.nixl_impl import (  # noqa: E402
+    NixlTransferChannelContext,
+)
+
+_ALIGN = 256
+_BUF_SIZE = 4096
+
+# Each context must bind to a distinct port so multiple pairs can coexist in one
+# process without clashing.
+_port_counter = itertools.count(17900)
+
+
+def _next_url() -> str:
+    return f"127.0.0.1:{next(_port_counter)}"
+
+
+def _make_context_pair():
+    """Create two contexts backed by two distinct CPU buffers.
+
+    ``buf_b`` holds a known byte pattern so transfers can be content-verified;
+    ``buf_a`` starts zeroed. Returns ``(ctx_a, buf_a, ctx_b, buf_b)``.
+    """
+    buf_a = torch.zeros(_BUF_SIZE, dtype=torch.uint8)
+    buf_b = torch.arange(0, 256, dtype=torch.uint8).repeat(_BUF_SIZE // 256)
+    desc_a = L1MemoryDesc(ptr=buf_a.data_ptr(), size=buf_a.numel(), align_bytes=_ALIGN)
+    desc_b = L1MemoryDesc(ptr=buf_b.data_ptr(), size=buf_b.numel(), align_bytes=_ALIGN)
+
+    url_a, url_b = _next_url(), _next_url()
+    ctx_a = NixlTransferChannelContext(desc_a, listen_url=url_a, advertise_url=url_a)
+    ctx_b = NixlTransferChannelContext(desc_b, listen_url=url_b, advertise_url=url_b)
+    return ctx_a, buf_a, ctx_b, buf_b
+
+
+@pytest.fixture(scope="module")
+def shared_contexts():
+    """A single context-pair reused across connection-state-insensitive tests."""
+    ctx_a, buf_a, ctx_b, buf_b = _make_context_pair()
+    try:
+        yield ctx_a, buf_a, ctx_b, buf_b
+    finally:
+        ctx_a.close()
+        ctx_b.close()
+
+
+@pytest.fixture
+def fresh_contexts():
+    """A brand-new context-pair for tests that need pristine connection state."""
+    ctx_a, buf_a, ctx_b, buf_b = _make_context_pair()
+    try:
+        yield ctx_a, buf_a, ctx_b, buf_b
+    finally:
+        ctx_a.close()
+        ctx_b.close()
+
+
+def _wait_finished(client, task_id, timeout_s=5.0):
+    """Poll query_read_status until the task reports finished (or timeout)."""
+    deadline = time.monotonic() + timeout_s
+    result = client.query_read_status(task_id)
+    while not result.is_finished() and time.monotonic() < deadline:
+        time.sleep(0.01)
+        result = client.query_read_status(task_id)
+    return result
+
+
+# =========================================================
+# Address translation (get_transfer_channel_address)
+# =========================================================
+def test_get_address_returns_matching_offsets_and_sizes(shared_contexts):
+    ctx_a, _, _, _ = shared_contexts
+    addrs = ctx_a.get_transfer_channel_address([(0, 512), (1024, 256)])
+    assert len(addrs) == 2
+    assert (addrs[0].offset, addrs[0].size) == (0, 512)
+    assert (addrs[1].offset, addrs[1].size) == (1024, 256)
+
+
+def test_get_address_out_of_region_raises_value_error(shared_contexts):
+    ctx_a, _, _, _ = shared_contexts
+    with pytest.raises(ValueError):
+        ctx_a.get_transfer_channel_address([(_BUF_SIZE, 256)])
+    with pytest.raises(ValueError):
+        ctx_a.get_transfer_channel_address([(_BUF_SIZE - 128, 256)])
+
+
+# =========================================================
+# End-to-end read (submit_read / query_read_status)
+# =========================================================
+def test_read_copies_remote_data_into_local_buffer(shared_contexts):
+    ctx_a, buf_a, ctx_b, buf_b = shared_contexts
+    client = ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+
+    local = ctx_a.get_transfer_channel_address([(0, 512)])
+    remote = ctx_b.get_transfer_channel_address([(0, 512)])
+    task_id = client.submit_read(local, remote)
+
+    result = _wait_finished(client, task_id)
+    assert result.is_finished() is True
+    assert result.succeeded_mask == [True] * len(remote)
+    assert torch.equal(buf_a[:512], buf_b[:512])
+
+
+def test_read_into_offset_region(shared_contexts):
+    ctx_a, buf_a, ctx_b, buf_b = shared_contexts
+    client = ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+
+    # Read remote [0, 256) into local [1024, 1280).
+    local = ctx_a.get_transfer_channel_address([(1024, 256)])
+    remote = ctx_b.get_transfer_channel_address([(0, 256)])
+    task_id = client.submit_read(local, remote)
+
+    result = _wait_finished(client, task_id)
+    assert result.is_finished() is True
+    assert torch.equal(buf_a[1024:1280], buf_b[0:256])
+
+
+def test_submit_read_mismatched_lengths_raises_value_error(shared_contexts):
+    ctx_a, _, ctx_b, _ = shared_contexts
+    client = ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+    local = ctx_a.get_transfer_channel_address([(0, 256)])
+    remote = ctx_b.get_transfer_channel_address([(0, 256), (256, 256)])
+    with pytest.raises(ValueError):
+        client.submit_read(local, remote)
+
+
+def test_query_unknown_task_id_raises_key_error(shared_contexts):
+    ctx_a, _, ctx_b, _ = shared_contexts
+    client = ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+    with pytest.raises(KeyError):
+        client.query_read_status(99999)
+
+
+# =========================================================
+# Client / server management
+# =========================================================
+def test_get_client_is_idempotent(shared_contexts):
+    ctx_a, _, ctx_b, _ = shared_contexts
+    first = ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+    second = ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+    assert first is second
+
+
+def test_register_client_keeps_first_and_closes_duplicate(fresh_contexts):
+    """A racing second registration keeps the first client and closes the dup."""
+    ctx_a, _, _, _ = fresh_contexts
+    key = "10.255.255.1:65000"
+    first = MagicMock()
+    second = MagicMock()
+
+    assert ctx_a.register_client(key, first) is first
+    # The peer's inbound connection registers a duplicate for the same key.
+    assert ctx_a.register_client(key, second) is first
+    second.close.assert_called_once()
+    first.close.assert_not_called()
+    assert ctx_a.get_num_connected_clients() == 1
+
+
+def test_remove_client_closes_and_drops_it(fresh_contexts):
+    """Removing a peer closes its client and drops it from the context."""
+    ctx_a, _, _, _ = fresh_contexts
+    key = "10.255.255.1:65000"
+    client = MagicMock()
+    ctx_a.register_client(key, client)
+    assert ctx_a.get_num_connected_clients() == 1
+
+    ctx_a.remove_transfer_channel_client(key)
+
+    client.close.assert_called_once()
+    assert ctx_a.get_num_connected_clients() == 0
+
+
+def test_remove_unknown_client_is_noop(fresh_contexts):
+    """Removing a peer with no registered client does nothing and does not raise."""
+    ctx_a, _, _, _ = fresh_contexts
+    ctx_a.remove_transfer_channel_client("10.255.255.1:65000")
+    assert ctx_a.get_num_connected_clients() == 0
+
+
+def test_remove_client_after_connect(fresh_contexts):
+    """A live client obtained via get_transfer_channel_client can be removed."""
+    ctx_a, _, ctx_b, _ = fresh_contexts
+    ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+    assert ctx_a.get_num_connected_clients() == 1
+
+    ctx_a.remove_transfer_channel_client(ctx_b.advertise_url)
+    assert ctx_a.get_num_connected_clients() == 0
+
+
+def test_connecting_registers_clients_on_both_sides(fresh_contexts):
+    ctx_a, _, ctx_b, _ = fresh_contexts
+    assert ctx_a.get_num_connected_clients() == 0
+    assert ctx_b.get_num_connected_clients() == 0
+
+    ctx_a.get_transfer_channel_client(ctx_b.advertise_url)
+
+    # A actively dialed B; B passively learned a reverse client for A.
+    assert ctx_a.get_num_connected_clients() == 1
+    assert ctx_b.get_num_connected_clients() == 1
+
+
+def test_server_is_available_from_context(shared_contexts):
+    ctx_a, _, _, _ = shared_contexts
+    assert ctx_a.get_transfer_channel_server() is not None
diff --git a/tests/v1/gpu_connector/test_blocks_first_fused_kv_format.py b/tests/v1/gpu_connector/test_blocks_first_fused_kv_format.py
new file mode 100644
index 0000000..5a43e13
--- /dev/null
+++ b/tests/v1/gpu_connector/test_blocks_first_fused_kv_format.py
@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Blocks-first, fused-K/V KV layout (GPUKVFormat.NL_X_NB_NH_BS_TWO_HS).
+
+A non-MLA blocks-first attention backend registers its KV cache as the 4D
+``[NB, NH, BS, 2 * HS]`` with K/V fused into the trailing dim (as opposed to
+the 5D K/V-major ``[2, NB, NH, BS, HS]``). Discovery splits the fused axis into
+the canonical 5D ``[NB, NH, BS, 2, HS]`` and classifies it as
+``NL_X_NB_NH_BS_TWO_HS``.
+
+These tests pin discovery, the format-aware accessors, and the multiprocess
+gather/scatter round-trip for that layout.
+"""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache import torch_device_type
+from lmcache.python_ops_fallback import (
+    multi_layer_block_kv_transfer as fallback_multi_layer_block_kv_transfer,
+)
+from lmcache.python_ops_fallback import (
+    set_shape_desc_dtype,
+)
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector import utils as U
+from lmcache.v1.multiprocess.transfer_context.base import (
+    gather_paged_kv_to_cpu,
+    scatter_cpu_to_paged_kv,
+)
+import lmcache.c_ops as lmc_ops
+
+pytestmark = pytest.mark.skipif(
+    torch_device_type != "cpu",
+    reason="vLLM blocks-first fused format (Format 10) is strictly CPU-only.",
+)
+
+NB, NH, BS, HS, NL = 16, 4, 128, 64, 3
+HINTS = {"kv_layout": "HND"}
+
+
+def _raw_blocks_first_caches() -> list[torch.Tensor]:
+    """Per-layer blocks-first tensors as registered: [NB, NH, BS, 2 * HS]."""
+    torch.manual_seed(0)
+    return [torch.randn(NB, NH, BS, 2 * HS) for _ in range(NL)]
+
+
+def test_discovery_splits_fused_axis():
+    fmt, norm = U.normalize_kv_and_discover_format(
+        _raw_blocks_first_caches(), EngineType.VLLM, HINTS
+    )
+    assert fmt == lmc_ops.EngineKVFormat.NL_X_NB_NH_BS_TWO_HS
+    # 4D [NB, NH, BS, 2*HS] -> canonical 5D [NB, NH, BS, 2, HS]
+    assert tuple(norm[0].shape) == (NB, NH, BS, 2, HS)
+
+
+def test_discovery_rejects_odd_trailing_dim():
+    bad = [torch.randn(NB, NH, BS, 2 * HS + 1) for _ in range(NL)]
+    with pytest.raises(ValueError):
+        U.normalize_kv_and_discover_format(bad, EngineType.VLLM, HINTS)
+
+
+def test_accessors():
+    fmt, norm = U.normalize_kv_and_discover_format(
+        _raw_blocks_first_caches(), EngineType.VLLM, HINTS
+    )
+    assert U.get_num_layers(norm, fmt) == NL
+    assert U.get_num_blocks(norm, fmt) == NB
+    assert U.get_block_size(norm, fmt) == BS
+    assert U.get_num_heads(norm, fmt) == NH
+    assert U.get_head_size(norm, fmt) == HS
+    assert U.get_hidden_dim_size(norm, fmt) == NH * HS
+    assert U.get_page_buffer_size(norm, fmt) == NB * BS
+    assert U.get_tokens_per_layer(norm, fmt) == NB * BS
+    assert U.get_elements_per_layer(norm, fmt) == NB * NH * BS * HS * 2
+    # get_dtype is on the register_kv_caches -> group_layers_by_identity path,
+    # so it must recognize this format too.
+    assert U.get_dtype(norm, fmt) == _raw_blocks_first_caches()[0].dtype
+    assert not U.is_mla(fmt)
+
+
+def test_mp_gather_scatter_roundtrip():
+    blocks_per_chunk = 2
+    block_ids = [0, 3, 5, 6]  # 2 chunks
+    raw = _raw_blocks_first_caches()
+    src = {f"layer_{i}": t for i, t in enumerate(raw)}
+    ref = {k: v.clone() for k, v in src.items()}
+    idx = torch.tensor(block_ids)
+
+    chunks = gather_paged_kv_to_cpu(
+        src, block_ids, blocks_per_chunk, layout_hints=HINTS
+    )
+    # [K/V, NL, chunk_tokens, NH*HS]
+    assert tuple(chunks[0].shape) == (2, NL, blocks_per_chunk * BS, NH * HS)
+
+    # Wipe the gathered blocks, scatter back, and confirm exact recovery.
+    dst = {k: v.clone() for k, v in src.items()}
+    for k in dst:
+        dst[k][idx] = 0.0
+    scatter_cpu_to_paged_kv(
+        dst, block_ids, chunks, blocks_per_chunk, layout_hints=HINTS
+    )
+
+    for k in dst:
+        assert torch.equal(dst[k][idx], ref[k][idx])
+
+    # Untouched blocks must be left alone.
+    untouched = torch.tensor([b for b in range(NB) if b not in block_ids])
+    for k in dst:
+        assert torch.equal(dst[k][untouched], ref[k][untouched])
+
+
+def test_multi_layer_block_kv_transfer_roundtrip():
+    """Server-side copy (handle mode) D2H + H2D round-trip.
+
+    Regression for the CI ``cpu_e2e_validation (server-side copy)`` failure:
+    ``LMCacheDrivenTransferModule.store`` calls ``multi_layer_block_kv_transfer`` for
+    this format, so the per-layer HND fallback must recognize it and split
+    K/V at dim 3.
+    """
+    # Use canonical 5D layers so the fallback exercises the HND split path.
+    fmt, norm = U.normalize_kv_and_discover_format(
+        _raw_blocks_first_caches(), EngineType.VLLM, HINTS
+    )
+    chunk_tokens = NB * BS
+    obj = torch.zeros((2, NL, chunk_tokens, NH * HS), dtype=norm[0].dtype)
+
+    sd = lmc_ops.PageBufferShapeDesc()
+    sd.kv_size = 2
+    sd.nl = NL
+    sd.nb = NB
+    sd.bs = BS
+    sd.nh = NH
+    sd.hs = HS
+    sd.element_size = norm[0].element_size()
+    sd.block_stride_elems = NH * BS * 2 * HS
+    set_shape_desc_dtype(sd, norm[0].dtype)
+
+    block_ids = torch.tensor(list(range(NB)), dtype=torch.long)
+
+    # Match the C++ binding's strict signature: 1D int64 tensor of paged
+    # buffer ``data_ptr()`` values, and a list of int ``data_ptr()`` for
+    # the lmcache objects (the fallback also accepts tensors directly,
+    # but the compiled extension does not).
+    norm_ptrs = torch.tensor([t.data_ptr() for t in norm], dtype=torch.long)
+    obj_ptrs = [obj.data_ptr()]
+
+    # Drive the python fallback directly: this regression specifically
+    # targets the CPU handle-mode path. ``lmc_ops.multi_layer_block_kv_transfer``
+    # is replaced by the CUDA C++ extension when CUDA is available, and that
+    # extension rejects ``torch.device("cpu")`` with a CUDAGuard error.
+    fallback_multi_layer_block_kv_transfer(
+        norm_ptrs,
+        obj_ptrs,
+        block_ids,
+        torch.device("cpu"),
+        lmc_ops.TransferDirection.D2H,
+        sd,
+        chunk_tokens,
+        fmt,
+        0,
+    )
+
+    # H2D into a fresh per-layer buffer set; round-trip must be bit-exact.
+    out = [torch.zeros_like(layer) for layer in norm]
+    out_ptrs = torch.tensor([t.data_ptr() for t in out], dtype=torch.long)
+    fallback_multi_layer_block_kv_transfer(
+        out_ptrs,
+        obj_ptrs,
+        block_ids,
+        torch.device("cpu"),
+        lmc_ops.TransferDirection.H2D,
+        sd,
+        chunk_tokens,
+        fmt,
+        0,
+    )
+
+    for original, recovered in zip(norm, out, strict=True):
+        assert torch.equal(original, recovered)
diff --git a/tests/v1/gpu_connector/test_concrete_shape.py b/tests/v1/gpu_connector/test_concrete_shape.py
new file mode 100644
index 0000000..a59096d
--- /dev/null
+++ b/tests/v1/gpu_connector/test_concrete_shape.py
@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for :func:`get_concrete_engine_kv_shape_from_shape_desc`.
+
+These run without a CUDA build: ``lmcache.c_ops`` resolves to the
+pure-Python fallback, which provides both ``PageBufferShapeDesc`` and
+``EngineKVFormat``.
+"""
+
+# First Party
+from lmcache.v1.gpu_connector.utils import (
+    get_concrete_engine_kv_shape_from_shape_desc,
+)
+import lmcache.c_ops as lmc_ops
+
+
+def _make_shape_desc(
+    *, kv_size: int, nl: int, nb: int, bs: int, nh: int, hs: int
+) -> "lmc_ops.PageBufferShapeDesc":
+    """Build a ``PageBufferShapeDesc`` with the given geometry."""
+    sd = lmc_ops.PageBufferShapeDesc()
+    sd.kv_size = kv_size
+    sd.nl = nl
+    sd.nb = nb
+    sd.bs = bs
+    sd.nh = nh
+    sd.hs = hs
+    sd.element_size = 2
+    sd.block_stride_elems = 0
+    return sd
+
+
+def test_concrete_shape_vllm_flash_attn():
+    sd = _make_shape_desc(kv_size=2, nl=32, nb=2048, bs=16, nh=8, hs=128)
+    out = get_concrete_engine_kv_shape_from_shape_desc(
+        sd, lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    )
+    assert out == "32 x [2, 2048, 16, 8, 128]"
+
+
+def test_concrete_shape_vllm_mla():
+    sd = _make_shape_desc(kv_size=1, nl=61, nb=1024, bs=64, nh=1, hs=512)
+    out = get_concrete_engine_kv_shape_from_shape_desc(
+        sd, lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    )
+    assert out == "61 x [1024, 64, 512]"
+
+
+def test_concrete_shape_uses_pbs_for_folded_formats():
+    # NL_X_NBBS_ONE_HS folds num_blocks * block_size into one PBS dim.
+    sd = _make_shape_desc(kv_size=1, nl=2, nb=32, bs=16, nh=1, hs=128)
+    out = get_concrete_engine_kv_shape_from_shape_desc(
+        sd, lmc_ops.EngineKVFormat.NL_X_NBBS_ONE_HS
+    )
+    assert out == "2 x [512, 1, 128]"  # 512 == 32 * 16
+
+
+def test_concrete_shape_is_group_accurate():
+    # Two groups with different layer counts produce different shapes for
+    # the same format — the whole-context helper could not do this.
+    fmt = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    g0 = _make_shape_desc(kv_size=2, nl=4, nb=128, bs=16, nh=8, hs=64)
+    g1 = _make_shape_desc(kv_size=2, nl=2, nb=128, bs=16, nh=16, hs=64)
+    assert get_concrete_engine_kv_shape_from_shape_desc(g0, fmt) == (
+        "4 x [2, 128, 16, 8, 64]"
+    )
+    assert get_concrete_engine_kv_shape_from_shape_desc(g1, fmt) == (
+        "2 x [2, 128, 16, 16, 64]"
+    )
diff --git a/tests/v1/gpu_connector/test_gds_context.py b/tests/v1/gpu_connector/test_gds_context.py
new file mode 100644
index 0000000..422be82
--- /dev/null
+++ b/tests/v1/gpu_connector/test_gds_context.py
@@ -0,0 +1,323 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the GDS cuFile context (``GDSContext``).
+
+Most tests are pure (no cuFile): they exercise the public interface
+(singleton/no-op semantics, the <=16 MiB region split observed at the ``ca``
+cuFile seam, and the registered-region mapping driven through
+:meth:`GDSContext.transfer_async`). The ``test_gds_*_roundtrip`` tests
+exercise the real GDS DMA path (cuFile on NVIDIA, hipFile on AMD ROCm) and are
+skipped unless that stack is present (see :func:`_gds_available`).
+"""
+
+# Standard
+from types import SimpleNamespace
+import os
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache import torch_dev
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.distributed.config import GdsL1Config
+from lmcache.v1.distributed.error import L1Error
+from lmcache.v1.distributed.memory_manager import GDSL1MemoryManager
+from lmcache.v1.gpu_connector import _gds_async as ca
+from lmcache.v1.gpu_connector.gds_context import (
+    GDSContext,
+    SlabDirection,
+    get_gds_context,
+    initialize_gds_context,
+)
+
+
+def _fake_stream(handle: int):
+    """A stand-in for ``torch_dev.current_stream()`` (no CUDA needed)."""
+    return SimpleNamespace(cuda_stream=handle, synchronize=lambda: None)
+
+
+def _gds_available() -> bool:
+    """Whether a real GPUDirect Storage stack is present for the roundtrip tests.
+
+    NVIDIA: CUDA plus the nvidia-fs kernel module (``/proc/driver/nvidia-fs``).
+    AMD ROCm: a loadable ``libhipfile.so`` (the hipFile GPU IO library). When
+    the GDS-capable driver/filesystem is absent hipFile still round-trips
+    correctly via its host-bounce fallback, so library loadability is a
+    sufficient gate for the correctness checks below.
+    """
+    if not torch.cuda.is_available():
+        return False
+    if torch.version.hip is not None:
+        # Standard
+        import ctypes
+
+        try:
+            ctypes.CDLL("libhipfile.so")
+        except OSError:
+            return False
+        return True
+    return os.path.exists("/proc/driver/nvidia-fs/stats")
+
+
+requires_gds = pytest.mark.skipif(
+    not _gds_available(),
+    reason="needs CUDA + nvidia-fs or ROCm + libhipfile.so (real GPUDirect Storage)",
+)
+
+
+@pytest.fixture(autouse=True)
+def _reset_singleton():
+    """Drop the process-global GDSContext between tests."""
+    get_gds_context.cache_clear()
+    yield
+    get_gds_context.cache_clear()
+
+
+class TestSingleton:
+    def test_singleton_identity(self):
+        assert get_gds_context() is get_gds_context()
+
+    def test_fresh_context_is_off(self):
+        assert GDSContext().initialized is False
+
+    def test_initialize_with_none_is_noop(self):
+        ctx = initialize_gds_context(None)
+        assert ctx is get_gds_context()
+        assert ctx.initialized is False
+
+
+class TestRegisterGpuBuffer:
+    def test_noop_when_uninitialized(self, monkeypatch):
+        ctx = GDSContext()
+        registered = []
+        monkeypatch.setattr(ca, "register_buffer", registered.append)
+        # GDS off -> registers nothing, makes no cuFile calls.
+        ctx.register_gpu_buffer(torch.empty(4096, dtype=torch.uint8))
+        assert registered == []
+
+    def test_splits_buffer_into_regions(self, monkeypatch):
+        ctx = GDSContext()
+        ctx.initialized = True
+        # Record each cuFile registration's byte size at the ca seam.
+        sizes = []
+        monkeypatch.setattr(
+            ca,
+            "register_buffer",
+            lambda buf: sizes.append(buf.numel() * buf.element_size()),
+        )
+        monkeypatch.setattr(ca, "register_stream", lambda raw: None)
+        monkeypatch.setattr(torch_dev, "current_stream", lambda: _fake_stream(0))
+
+        # The whole buffer is registered in <=16 MiB regions, irrespective of
+        # any chunk/slot layout. A 40 MiB buffer -> 16 + 16 + 8 MiB.
+        # A CPU tensor is fine: the cuFile calls are mocked.
+        buf = torch.empty(40 << 20, dtype=torch.uint8)
+        ctx.register_gpu_buffer(buf)
+
+        assert sizes == [16 << 20, 16 << 20, 8 << 20]
+
+
+class TestResolveBuffer:
+    """Region mapping: a buffer slice resolves to ``(region base, offset)``,
+    exercised through the public ``transfer_async`` path."""
+
+    def _registered_ctx(self, monkeypatch, buf: torch.Tensor):
+        """Register ``buf``; capture the ``(base, offset)`` that
+        ``transfer_async`` resolves a slice to before handing it to the slab."""
+        ctx = GDSContext()
+        ctx.initialized = True
+        monkeypatch.setattr(ca, "register_buffer", lambda b: None)
+        monkeypatch.setattr(ca, "register_stream", lambda raw: None)
+        monkeypatch.setattr(torch_dev, "current_stream", lambda: _fake_stream(0))
+        ctx.register_gpu_buffer(buf)
+        resolved: list[tuple[int, int]] = []
+        monkeypatch.setattr(
+            ctx,
+            "_slab_write",
+            lambda slab_offset, size, dev_offset, buf_base: resolved.append(
+                (buf_base, dev_offset)
+            ),
+        )
+        return ctx, resolved
+
+    def test_maps_slice_to_base_and_offset(self, monkeypatch):
+        buf = torch.empty(8192, dtype=torch.uint8)
+        ctx, resolved = self._registered_ctx(monkeypatch, buf)
+        mem_obj = SimpleNamespace(get_size=lambda: 4096, slab_offset=0)
+        # A slice 4 KiB into the region must map to (region base, offset 4096).
+        ctx.transfer_async(mem_obj, buf[4096:], SlabDirection.WRITE)
+        assert resolved == [(buf.data_ptr(), 4096)]
+
+
+class TestPerStreamRegistration:
+    """Each distinct stream is cuFile-registered once and deregistered once its
+    last region is gone -- observed at the ``ca`` seam (no private state)."""
+
+    def test_register_and_deregister_per_stream(self, monkeypatch):
+        ctx = GDSContext()
+        ctx.initialized = True
+        reg_str: list[int] = []
+        dereg_str: list[int] = []
+        dereg_buf: list[int] = []
+        monkeypatch.setattr(ca, "register_buffer", lambda b: None)
+        monkeypatch.setattr(
+            ca, "deregister_buffer", lambda b: dereg_buf.append(b.data_ptr())
+        )
+        monkeypatch.setattr(ca, "register_stream", reg_str.append)
+        monkeypatch.setattr(ca, "deregister_stream", dereg_str.append)
+
+        def use_stream(handle: int):
+            monkeypatch.setattr(
+                torch_dev, "current_stream", lambda: _fake_stream(handle)
+            )
+
+        buf_a = torch.empty(24 << 20, dtype=torch.uint8)  # 2 regions on stream 11
+        buf_b = torch.empty(4096, dtype=torch.uint8)  # 1 region on stream 22
+        use_stream(11)
+        ctx.register_gpu_buffer(buf_a)
+        use_stream(22)
+        ctx.register_gpu_buffer(buf_b)
+        # Each distinct stream registered exactly once.
+        assert reg_str == [11, 22]
+
+        # Deregistering buf_b frees stream 22's only region -> stream 22 dropped.
+        use_stream(22)
+        ctx.deregister_gpu_buffer(buf_b)
+        assert dereg_str == [22]
+        # Stream 11 still has 2 regions (24 MiB -> 16 + 8), so not yet dropped.
+        use_stream(11)
+        ctx.deregister_gpu_buffer(buf_a)
+        assert dereg_str == [22, 11]
+        assert len(dereg_buf) == 3  # all three slots deregistered
+
+
+@requires_gds
+def test_gds_two_stream_write_read(tmp_path):
+    """Two CUDA streams each register their own buffer and round-trip a chunk
+    through real cuFile DMA; verify the data stays isolated per stream."""
+    cfg = GdsL1Config(file_location=str(tmp_path), size_in_bytes=64 << 20)
+    chunk_bytes = 8 << 20
+    ctx = GDSContext()
+    ctx.initialize(cfg)
+    mgr = GDSL1MemoryManager(cfg)
+
+    def register_and_write(stream, pattern):
+        """Register a buffer on ``stream`` and write ``pattern`` to a chunk."""
+        with torch.cuda.stream(stream):
+            buf = torch.empty(chunk_bytes, dtype=torch.uint8, device="cuda")
+            ctx.register_gpu_buffer(buf)
+            err, objs = mgr.allocate(
+                MemoryLayoutDesc(
+                    shapes=[torch.Size([chunk_bytes])], dtypes=[torch.uint8]
+                ),
+                1,
+            )
+            assert err == L1Error.SUCCESS
+            buf.fill_(pattern)
+            torch.cuda.synchronize()
+            ctx.transfer_async(objs[0], buf, SlabDirection.WRITE)
+            torch.cuda.synchronize()
+        return buf, objs[0]
+
+    stream_a = torch.cuda.Stream()
+    stream_b = torch.cuda.Stream()
+    try:
+        buf_a, mem_a = register_and_write(stream_a, 0xA1)
+        buf_b, mem_b = register_and_write(stream_b, 0xB2)
+
+        # Read each chunk back on its own stream; each must see its own pattern,
+        # confirming the two streams' buffers/regions don't clobber each other.
+        for stream, buf, mem, pattern in (
+            (stream_a, buf_a, mem_a, 0xA1),
+            (stream_b, buf_b, mem_b, 0xB2),
+        ):
+            with torch.cuda.stream(stream):
+                buf.zero_()
+                torch.cuda.synchronize()
+                ctx.transfer_async(mem, buf, SlabDirection.READ)
+                torch.cuda.synchronize()
+                expected = torch.full((chunk_bytes,), pattern, dtype=torch.uint8)
+                assert torch.equal(buf.cpu(), expected)
+
+        # Deregister each buffer on its own stream.
+        for stream, buf in ((stream_a, buf_a), (stream_b, buf_b)):
+            with torch.cuda.stream(stream):
+                ctx.deregister_gpu_buffer(buf)
+    finally:
+        ctx.close()
+
+
+@requires_gds
+def test_gds_write_read_roundtrip(tmp_path):
+    """Cold write then read of a chunk through the real cuFile DMA path."""
+    cfg = GdsL1Config(file_location=str(tmp_path), size_in_bytes=64 << 20)
+    ctx = GDSContext()
+    ctx.initialize(cfg)
+    try:
+        chunk_bytes = 8 << 20
+        buf = torch.empty(chunk_bytes, dtype=torch.uint8, device="cuda")
+        ctx.register_gpu_buffer(buf)
+
+        mgr = GDSL1MemoryManager(cfg)
+        err, objs = mgr.allocate(
+            MemoryLayoutDesc(shapes=[torch.Size([chunk_bytes])], dtypes=[torch.uint8]),
+            1,
+        )
+        assert err == L1Error.SUCCESS
+        mem_obj = objs[0]
+
+        buf.fill_(0xAB)
+        torch.cuda.synchronize()
+        ctx.transfer_async(mem_obj, buf, SlabDirection.WRITE)
+
+        buf.zero_()
+        torch.cuda.synchronize()
+        ctx.transfer_async(mem_obj, buf, SlabDirection.READ)
+        torch.cuda.synchronize()
+
+        expected = torch.full((chunk_bytes,), 0xAB, dtype=torch.uint8)
+        assert torch.equal(buf.cpu(), expected)
+    finally:
+        ctx.close()
+
+
+@requires_gds
+def test_gds_chunk_larger_than_region_roundtrip(tmp_path):
+    """A chunk larger than the 16 MiB cuFile region cap round-trips correctly.
+
+    Exercises the multi-region registration and the split (per-segment) DMA
+    path: a 24 MiB chunk is registered/transferred as a 16 MiB + 8 MiB pair.
+    """
+    cfg = GdsL1Config(file_location=str(tmp_path), size_in_bytes=64 << 20)
+    ctx = GDSContext()
+    ctx.initialize(cfg)
+    try:
+        chunk_bytes = 24 << 20  # > 16 MiB -> two registered regions / two DMAs
+        buf = torch.empty(chunk_bytes, dtype=torch.uint8, device="cuda")
+        ctx.register_gpu_buffer(buf)
+
+        mgr = GDSL1MemoryManager(cfg)
+        err, objs = mgr.allocate(
+            MemoryLayoutDesc(shapes=[torch.Size([chunk_bytes])], dtypes=[torch.uint8]),
+            1,
+        )
+        assert err == L1Error.SUCCESS
+        mem_obj = objs[0]
+
+        # Position-dependent pattern: a mis-offset or swapped segment (e.g. the
+        # second segment using the wrong slab offset) would corrupt the bytes
+        # around the 16 MiB boundary, which a uniform fill would not catch.
+        pattern = (torch.arange(chunk_bytes, dtype=torch.int64) % 251).to(torch.uint8)
+        buf.copy_(pattern.cuda())
+        torch.cuda.synchronize()
+        ctx.transfer_async(mem_obj, buf, SlabDirection.WRITE)
+
+        buf.zero_()
+        torch.cuda.synchronize()
+        ctx.transfer_async(mem_obj, buf, SlabDirection.READ)
+        torch.cuda.synchronize()
+
+        assert torch.equal(buf.cpu(), pattern)
+    finally:
+        ctx.close()
diff --git a/tests/v1/gpu_connector/test_hipfile_async.py b/tests/v1/gpu_connector/test_hipfile_async.py
new file mode 100644
index 0000000..22c0547
--- /dev/null
+++ b/tests/v1/gpu_connector/test_hipfile_async.py
@@ -0,0 +1,227 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the hipFile async wrapper (``_hipfile_async``).
+
+These are pure: ``libhipfile.so`` is never dlopened. A fake lib (see
+:class:`_FakeLib`) is substituted at the ``_lib`` seam, so the tests exercise
+the Python logic of the ctypes wrapper -- ``hipFileDescr_t`` construction, the
+stream-register flag value, error decoding, :class:`Submission` lifetime, and
+which symbol each call dispatches to -- without a GPU or the ROCm GPU IO
+driver. The ctypes ABI itself (struct field offsets, argtype marshalling) is
+covered by the on-hardware roundtrip tests in ``test_gds_context.py``.
+"""
+
+# Standard
+from types import SimpleNamespace
+import ctypes
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.gpu_connector import _hipfile_async as ha
+
+
+def _ok() -> ha._HipFileError:
+    """A success ``hipFileError_t`` (err == hipFileSuccess)."""
+    return ha._HipFileError(err=ha._HIPFILE_SUCCESS, hip_drv_err=0)
+
+
+def _err(code: int = 5001) -> ha._HipFileError:
+    """A failure ``hipFileError_t``."""
+    return ha._HipFileError(err=code, hip_drv_err=0)
+
+
+class _FakeLib:
+    """Stand-in for the ``libhipfile.so`` CDLL.
+
+    Each hipFile symbol records its positional args in :attr:`calls` and returns
+    a success ``hipFileError_t`` by default. Tests override individual symbols
+    (e.g. to populate an out-param or force an error) by assigning attributes.
+    """
+
+    def __init__(self) -> None:
+        self.calls: dict[str, tuple] = {}
+
+    def __getattr__(self, name: str):
+        # Any hipFile* symbol not explicitly overridden records its args and
+        # succeeds. ``__getattr__`` only fires for names not set in __dict__.
+        def _record(*args):
+            self.calls[name] = args
+            if name == "hipFileGetOpErrorString":
+                return b"hipFileFakeError"
+            return _ok()
+
+        return _record
+
+
+@pytest.fixture(autouse=True)
+def _fake_lib(monkeypatch) -> _FakeLib:
+    """Replace the ``_lib`` seam with a fake and reset module driver state."""
+    lib = _FakeLib()
+    monkeypatch.setattr(ha, "_lib", lambda: lib)
+    monkeypatch.setattr(ha, "_driver_opened", False)
+    return lib
+
+
+def _fake_gpu_tensor(ptr: int = 0x1000, nbytes: int = 4096):
+    """A duck-typed stand-in for a CUDA ``torch.Tensor`` (no GPU needed)."""
+    return SimpleNamespace(
+        is_cuda=True,
+        data_ptr=lambda: ptr,
+        numel=lambda: nbytes,
+        element_size=lambda: 1,
+    )
+
+
+class TestCheck:
+    def test_success_is_noop(self):
+        ha._check(_ok(), "op")
+
+    def test_nonzero_raises_with_code_and_name(self, _fake_lib):
+        with pytest.raises(RuntimeError) as exc:
+            ha._check(_err(5002), "hipFileDriverOpen")
+        msg = str(exc.value)
+        assert "hipFileDriverOpen" in msg
+        assert "5002" in msg
+        # The op-error string is resolved through the lib.
+        assert "hipFileFakeError" in msg
+
+
+class TestDriverLifecycle:
+    def test_ensure_open_calls_driver_open_once(self, _fake_lib):
+        ha._ensure_driver_open()
+        ha._ensure_driver_open()
+        # Recorded means it was called; idempotency guarded by _driver_opened.
+        assert "hipFileDriverOpen" in _fake_lib.calls
+        assert ha._driver_opened is True
+
+    def test_close_driver_when_open(self, _fake_lib):
+        ha._ensure_driver_open()
+        ha.close_driver()
+        assert "hipFileDriverClose" in _fake_lib.calls
+        assert ha._driver_opened is False
+
+    def test_close_driver_noop_when_closed(self, _fake_lib):
+        ha.close_driver()
+        assert "hipFileDriverClose" not in _fake_lib.calls
+
+
+class TestRegisterHandle:
+    def test_builds_opaque_fd_descr_and_returns_handle(self, _fake_lib):
+        captured = {}
+
+        def _register(fh_ref, descr_ref):
+            descr = descr_ref._obj
+            captured["type"] = descr.type
+            captured["fd"] = descr.handle.fd
+            # Populate the out-param like the real driver would.
+            fh_ref._obj.value = 0xDEADBEEF
+            return _ok()
+
+        _fake_lib.hipFileHandleRegister = _register
+        handle = ha.register_handle(42)
+        assert handle == 0xDEADBEEF
+        assert captured["type"] == ha._HIPFILE_HANDLE_TYPE_OPAQUE_FD
+        assert captured["fd"] == 42
+
+    def test_register_handle_opens_driver(self, _fake_lib):
+        ha.register_handle(7)
+        assert "hipFileDriverOpen" in _fake_lib.calls
+
+    def test_deregister_handle_dispatches(self, _fake_lib):
+        ha.deregister_handle(0x1234)
+        assert "hipFileHandleDeregister" in _fake_lib.calls
+
+
+class TestBufferRegistration:
+    def test_rejects_non_gpu_tensor(self):
+        cpu = SimpleNamespace(is_cuda=False)
+        with pytest.raises(ValueError):
+            ha.register_buffer(cpu)
+
+    def test_register_buffer_passes_size(self, _fake_lib):
+        ha.register_buffer(_fake_gpu_tensor(ptr=0x2000, nbytes=8192))
+        base, length, flags = _fake_lib.calls["hipFileBufRegister"]
+        assert base.value == 0x2000
+        assert length.value == 8192
+
+    def test_deregister_buffer_dispatches(self, _fake_lib):
+        ha.deregister_buffer(_fake_gpu_tensor(ptr=0x2000))
+        (base,) = _fake_lib.calls["hipFileBufDeregister"]
+        assert base.value == 0x2000
+
+
+class TestStreamRegistration:
+    def test_register_stream_uses_fixed_flags(self, _fake_lib):
+        ha.register_stream(0xABC)
+        stream, flags = _fake_lib.calls["hipFileStreamRegister"]
+        assert stream.value == 0xABC
+        # FIXED_BUF_OFFSET | FIXED_FILE_OFFSET | FIXED_FILE_SIZE.
+        assert flags == 0x7
+
+    def test_deregister_stream_dispatches(self, _fake_lib):
+        ha.register_stream(0xABC)
+        ha.deregister_stream(0xABC)
+        (stream,) = _fake_lib.calls["hipFileStreamDeregister"]
+        assert stream.value == 0xABC
+
+
+class TestSubmission:
+    def test_bytes_done_defaults_zero_then_reflects_driver(self):
+        sub = ha.Submission(size=4096, file_offset=0, buf_offset=0)
+        assert sub.bytes_done == 0
+        sub._bytes_done.value = 4096
+        assert sub.bytes_done == 4096
+
+
+class TestAsyncHandleIO:
+    def _handle(self) -> ha.AsyncHandle:
+        return ha.AsyncHandle.from_fd(fd=5, handle=0xFEED, path="/slab", writable=True)
+
+    def test_read_async_dispatches_and_returns_submission(self, _fake_lib):
+        def _read(fh, buf, size_p, foff_p, boff_p, bytes_p, stream):
+            # Driver reports the byte count into the caller's storage.
+            bytes_p._obj.value = 4096
+            _fake_lib.calls["hipFileReadAsync"] = (fh, buf, stream)
+            return _ok()
+
+        _fake_lib.hipFileReadAsync = _read
+        h = self._handle()
+        sub = h.read_async(
+            buf_base=0x3000, size=4096, file_offset=0, buf_offset=0, raw_stream=0x9
+        )
+        fh, buf, stream = _fake_lib.calls["hipFileReadAsync"]
+        assert fh.value == 0xFEED
+        assert buf.value == 0x3000
+        assert stream.value == 0x9
+        assert sub.bytes_done == 4096
+
+    def test_write_async_dispatches(self, _fake_lib):
+        h = self._handle()
+        sub = h.write_async(
+            buf_base=0x3000, size=2048, file_offset=512, buf_offset=0, raw_stream=0x9
+        )
+        assert "hipFileWriteAsync" in _fake_lib.calls
+        assert isinstance(sub, ha.Submission)
+
+    def test_io_error_raises(self, _fake_lib):
+        _fake_lib.hipFileWriteAsync = lambda *a: _err(5023)
+        h = self._handle()
+        with pytest.raises(RuntimeError) as exc:
+            h.write_async(
+                buf_base=0x3000, size=2048, file_offset=0, buf_offset=0, raw_stream=0x9
+            )
+        assert "hipFileWriteAsync" in str(exc.value)
+
+
+class TestStructLayout:
+    """Guard the ctypes structs against the hipfile.h C ABI (LP64)."""
+
+    def test_error_struct_size(self):
+        assert ctypes.sizeof(ha._HipFileError) == 8
+
+    def test_descr_struct_layout(self):
+        assert ctypes.sizeof(ha._HipFileDescr) == 24
+        assert ha._HipFileDescr.type.offset == 0
+        assert ha._HipFileDescr.handle.offset == 8
+        assert ha._HipFileDescr.fs_ops.offset == 16
diff --git a/tests/v1/gpu_connector/test_kv_format_classification.py b/tests/v1/gpu_connector/test_kv_format_classification.py
new file mode 100644
index 0000000..9dda707
--- /dev/null
+++ b/tests/v1/gpu_connector/test_kv_format_classification.py
@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Golden tests for the ``EngineKVFormat`` classification predicates.
+
+The structural shape (``is_cross_layer`` / ``is_kv_list`` / ``is_layer_list``)
+and the ``is_mla`` modifier are defined once in ``csrc/engine_kv_format.h`` and
+read via ``lmc_ops``, shared with the device kernels. This file pins each
+format's classification and enforces that the three structural flags partition
+every format (exactly one is true), so a new format or an edit cannot silently
+break the contract the per-layer detection relies on.
+"""
+
+# First Party
+import lmcache.c_ops as lmc_ops
+
+F = lmc_ops.EngineKVFormat
+
+# (is_cross_layer, is_kv_list, is_layer_list, is_mla) per format.
+EXPECTED = {
+    F.NB_NL_TWO_BS_NH_HS: (True, False, False, False),
+    F.NB_NL_TWO_NH_BS_HS: (True, False, False, False),
+    F.TWO_X_NL_X_NBBS_NH_HS: (False, True, False, False),
+    F.TWO_X_NL_X_NB_BS_NH_HS: (False, True, False, False),
+    F.NL_X_TWO_NB_BS_NH_HS: (False, False, True, False),
+    F.NL_X_NB_TWO_BS_NH_HS: (False, False, True, False),
+    F.NL_X_TWO_NB_NH_BS_HS: (False, False, True, False),
+    F.NL_X_NB_TWO_NH_BS_HS: (False, False, True, False),
+    F.NL_X_NB_NH_BS_TWO_HS: (False, False, True, False),
+    F.NL_X_NB_BS_HS: (False, False, True, True),
+    F.NL_X_NBBS_ONE_HS: (False, False, True, True),
+}
+
+
+def _all_formats():
+    return [v for v in vars(F).values() if isinstance(v, F)]
+
+
+def test_classification_matches_golden():
+    for fmt, expected in EXPECTED.items():
+        got = (
+            lmc_ops.is_cross_layer(fmt),
+            lmc_ops.is_kv_list(fmt),
+            lmc_ops.is_layer_list(fmt),
+            lmc_ops.is_mla(fmt),
+        )
+        assert got == expected, f"{fmt}: got {got}, expected {expected}"
+
+
+def test_every_format_is_pinned():
+    # A new EngineKVFormat must be added to EXPECTED (and classified) deliberately.
+    assert set(_all_formats()) == set(EXPECTED)
+
+
+def test_structural_flags_partition_every_format():
+    # Exactly one structural shape is true for every format.
+    for fmt in _all_formats():
+        structural = (
+            lmc_ops.is_cross_layer(fmt),
+            lmc_ops.is_kv_list(fmt),
+            lmc_ops.is_layer_list(fmt),
+        )
+        assert sum(structural) == 1, f"{fmt}: structural flags {structural}"
diff --git a/tests/v1/gpu_connector/test_kv_format_detection.py b/tests/v1/gpu_connector/test_kv_format_detection.py
new file mode 100644
index 0000000..b4b189a
--- /dev/null
+++ b/tests/v1/gpu_connector/test_kv_format_detection.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the per-engine format detection split.
+
+``detect_format`` normalizes a raw ``kv_caches`` and discovers its
+``EngineKVFormat``. These cases feed canonical (already-normalized)
+structures plus the engine and layout hints, and assert the detected
+format -- covering the vLLM NHD/HND branch, the SGLang depth-1/depth-2
+branch, and the TRT-LLM cross-layer branch.
+"""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.kv_format import detect_format
+import lmcache.c_ops as lmc_ops
+
+NB, NL, BS, NH, HS = 7, 5, 3, 2, 4
+DT = torch.float16
+F = lmc_ops.EngineKVFormat
+
+
+def _t(*shape: int) -> torch.Tensor:
+    return torch.zeros(shape, dtype=DT)
+
+
+def test_vllm_cross_layer():
+    kv = _t(NB, NL, 2, BS, NH, HS)
+    fmt, out = detect_format(kv, EngineType.VLLM, {"kv_layout": "NHD"})
+    assert fmt == F.NB_NL_TWO_BS_NH_HS
+    assert out is kv
+
+
+# The CPU-HND safeguard forces HND regardless of hint when running on a CPU
+# host; bypass it so the hint-driven NHD/HND branch is exercised on any host.
+_VLLM_DEV = "lmcache.v1.gpu_connector.kv_format.detectors.vllm.torch_device_type"
+
+
+def test_vllm_flash_attn_nhd_vs_hnd(monkeypatch):
+    monkeypatch.setattr(_VLLM_DEV, "cuda")
+    kv = [_t(2, NB, BS, NH, HS) for _ in range(NL)]
+    fmt_nhd, _ = detect_format(kv, EngineType.VLLM, {"kv_layout": "NHD"})
+    assert fmt_nhd == F.NL_X_TWO_NB_BS_NH_HS
+    # HND geometry has heads before block-size: [2, NB, NH, BS, HS].
+    kv_hnd = [_t(2, NB, NH, BS, HS) for _ in range(NL)]
+    fmt_hnd, _ = detect_format(kv_hnd, EngineType.VLLM, {"kv_layout": "HND"})
+    assert fmt_hnd == F.NL_X_TWO_NB_NH_BS_HS
+
+
+def test_vllm_flash_infer_nhd(monkeypatch):
+    monkeypatch.setattr(_VLLM_DEV, "cuda")
+    kv = [_t(NB, 2, BS, NH, HS) for _ in range(NL)]
+    fmt, _ = detect_format(kv, EngineType.VLLM, {"kv_layout": "NHD"})
+    assert fmt == F.NL_X_NB_TWO_BS_NH_HS
+
+
+def test_vllm_mla():
+    kv = [_t(NB, BS, HS) for _ in range(NL)]
+    fmt, _ = detect_format(kv, EngineType.VLLM, {"kv_layout": "NHD"})
+    assert fmt == F.NL_X_NB_BS_HS
+
+
+def test_vllm_blocks_first_fused_num_heads_2():
+    # Raw 4-D [NB, NH, BS, 2*HS] with NH == 2 (a common GQA config): after the
+    # fused split the K/V axis and the head axis both equal 2, so the 5-D shape
+    # is ambiguous with flash-infer. Detection must use the rank-4 split, not
+    # the post-split shape, to land on the fused format.
+    raw = [_t(NB, 2, BS, 2 * HS) for _ in range(NL)]
+    fmt, out = detect_format(raw, EngineType.VLLM, {"kv_layout": "HND"})
+    assert fmt == F.NL_X_NB_NH_BS_TWO_HS
+    assert tuple(out[0].shape) == (NB, 2, BS, 2, HS)
+
+
+def test_sglang_mla_depth1():
+    kv = [_t(NB * BS, 1, HS) for _ in range(NL)]
+    fmt, _ = detect_format(kv, EngineType.SGLANG, {})
+    assert fmt == F.NL_X_NBBS_ONE_HS
+
+
+def test_sglang_mha_depth2_fused():
+    kv = [[_t(NB * BS, NH, HS) for _ in range(NL)] for _ in range(2)]
+    fmt, _ = detect_format(kv, EngineType.SGLANG, {})
+    assert fmt == F.TWO_X_NL_X_NBBS_NH_HS
+
+
+def test_sglang_mha_mp_reshape():
+    # MP path: flat list of 2*NL 3-D tensors + tokens_per_block hint;
+    # detection should un-flatten + reshape to the 4-D inner MP format.
+    if not hasattr(F, "TWO_X_NL_X_NB_BS_NH_HS"):
+        pytest.skip("extension lacks TWO_X_NL_X_NB_BS_NH_HS")
+    flat = [_t(NB * BS, NH, HS) for _ in range(2 * NL)]
+    fmt, out = detect_format(flat, EngineType.SGLANG, {"tokens_per_block": BS})
+    assert fmt == F.TWO_X_NL_X_NB_BS_NH_HS
+    # Canonical depth-2 [K_layers, V_layers], inner reshaped to 4-D.
+    assert len(out) == 2 and len(out[0]) == NL
+    assert tuple(out[0][0].shape) == (NB, BS, NH, HS)
+
+
+def test_trtllm_cross_layer_6d():
+    kv = _t(NB, NL, 2, NH, BS, HS)
+    fmt, _ = detect_format(kv, EngineType.TRTLLM, {})
+    assert fmt == F.NB_NL_TWO_NH_BS_HS
+
+
+def test_unsupported_structure_raises():
+    # vLLM depth-1 list of 2-D tensors matches no branch (needs 5-D, 4-D, or
+    # 3-D). (4-D is now the blocks-first fused layout, so it no longer raises.)
+    kv = [_t(NB, HS) for _ in range(NL)]
+    with pytest.raises(ValueError):
+        detect_format(kv, EngineType.VLLM, {"kv_layout": "NHD"})
diff --git a/tests/v1/gpu_connector/test_kv_format_specs.py b/tests/v1/gpu_connector/test_kv_format_specs.py
new file mode 100644
index 0000000..a30d76e
--- /dev/null
+++ b/tests/v1/gpu_connector/test_kv_format_specs.py
@@ -0,0 +1,292 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Golden tests for the kv_format spec layer.
+
+Each :class:`KVFormatSpec` is pinned to independently-computed expected
+geometry for a synthetic ``kv_caches`` built from distinct prime-ish
+dims. The values were validated to match the pre-refactor ``utils.py``
+switch-on-enum accessors exactly; this file freezes them so future
+edits to a spec cannot silently drift.
+"""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format import (
+    describe_shape,
+    get_spec,
+    get_spec_class,
+)
+import lmcache.c_ops as lmc_ops
+
+# Distinct dims so a wrong axis surfaces as a wrong number.
+NB, NL, BS, NH, HS = 7, 5, 3, 2, 4
+PBS = NB * BS  # 21
+DT = torch.float16
+
+
+def _t(*shape: int) -> torch.Tensor:
+    return torch.zeros(shape, dtype=DT)
+
+
+def _build(name: str):
+    """Build a synthetic normalized kv_caches for the named format."""
+    builders = {
+        "NB_NL_TWO_BS_NH_HS": lambda: _t(NB, NL, 2, BS, NH, HS),
+        "NB_NL_TWO_NH_BS_HS": lambda: _t(NB, NL, 2, NH, BS, HS),
+        "NL_X_TWO_NB_BS_NH_HS": lambda: [_t(2, NB, BS, NH, HS) for _ in range(NL)],
+        "NL_X_NB_TWO_BS_NH_HS": lambda: [_t(NB, 2, BS, NH, HS) for _ in range(NL)],
+        "NL_X_TWO_NB_NH_BS_HS": lambda: [_t(2, NB, NH, BS, HS) for _ in range(NL)],
+        "NL_X_NB_TWO_NH_BS_HS": lambda: [_t(NB, 2, NH, BS, HS) for _ in range(NL)],
+        "NL_X_NB_BS_HS": lambda: [_t(NB, BS, HS) for _ in range(NL)],
+        "TWO_X_NL_X_NBBS_NH_HS": lambda: [
+            [_t(PBS, NH, HS) for _ in range(NL)] for _ in range(2)
+        ],
+        "TWO_X_NL_X_NB_BS_NH_HS": lambda: [
+            [_t(NB, BS, NH, HS) for _ in range(NL)] for _ in range(2)
+        ],
+        "NL_X_NBBS_ONE_HS": lambda: [_t(PBS, 1, HS) for _ in range(NL)],
+        "NL_X_NB_NH_BS_TWO_HS": lambda: [_t(NB, NH, BS, 2, HS) for _ in range(NL)],
+    }
+    return builders[name]()
+
+
+# Independently-computed expected geometry per format. ``num_blocks`` /
+# ``block_size`` are ``None`` for NBBS-fused formats, which must raise.
+_RAISE = object()
+GOLDEN = {
+    "NB_NL_TWO_BS_NH_HS": dict(
+        shape_desc="[NB, NL, 2, BS, NH, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * 2 * BS * NH * HS,
+        concrete="[7, 5, 2, 3, 2, 4]",
+    ),
+    "NB_NL_TWO_NH_BS_HS": dict(
+        shape_desc="[NB, NL, 2, NH, BS, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * 2 * NH * BS * HS,
+        concrete="[7, 5, 2, 2, 3, 4]",
+    ),
+    "NL_X_TWO_NB_BS_NH_HS": dict(
+        shape_desc="NL x [2, NB, BS, NH, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * BS * NH * HS * 2,
+        concrete="5 x [2, 7, 3, 2, 4]",
+    ),
+    "NL_X_NB_TWO_BS_NH_HS": dict(
+        shape_desc="NL x [NB, 2, BS, NH, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * BS * NH * HS * 2,
+        concrete="5 x [7, 2, 3, 2, 4]",
+    ),
+    "NL_X_TWO_NB_NH_BS_HS": dict(
+        shape_desc="NL x [2, NB, NH, BS, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * NH * BS * HS * 2,
+        concrete="5 x [2, 7, 2, 3, 4]",
+    ),
+    "NL_X_NB_TWO_NH_BS_HS": dict(
+        shape_desc="NL x [NB, 2, NH, BS, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * NH * BS * HS * 2,
+        concrete="5 x [7, 2, 2, 3, 4]",
+    ),
+    "NL_X_NB_BS_HS": dict(
+        shape_desc="NL x [NB, BS, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=1,
+        hidden_dim=HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * BS * HS,
+        concrete="5 x [7, 3, 4]",
+    ),
+    "TWO_X_NL_X_NBBS_NH_HS": dict(
+        shape_desc="2 x NL x [PBS, NH, HS]",
+        num_layers=NL,
+        num_blocks=_RAISE,
+        block_size=_RAISE,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=PBS * NH * HS * 2,
+        concrete="2 x 5 x [21, 2, 4]",
+    ),
+    "TWO_X_NL_X_NB_BS_NH_HS": dict(
+        shape_desc="2 x NL x [NB, BS, NH, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * BS * NH * HS * 2,
+        concrete="2 x 5 x [7, 3, 2, 4]",
+    ),
+    "NL_X_NBBS_ONE_HS": dict(
+        shape_desc="NL x [PBS, 1, HS]",
+        num_layers=NL,
+        num_blocks=_RAISE,
+        block_size=_RAISE,
+        page_buffer_size=PBS,
+        num_heads=1,
+        hidden_dim=HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=PBS * HS,
+        concrete="5 x [21, 1, 4]",
+    ),
+    "NL_X_NB_NH_BS_TWO_HS": dict(
+        shape_desc="NL x [NB, NH, BS, 2, HS]",
+        num_layers=NL,
+        num_blocks=NB,
+        block_size=BS,
+        page_buffer_size=PBS,
+        num_heads=NH,
+        hidden_dim=NH * HS,
+        head_size=HS,
+        tokens_per_layer=PBS,
+        elements_per_layer=NB * NH * BS * HS * 2,
+        concrete="5 x [7, 2, 3, 2, 4]",
+    ),
+}
+
+# Only formats the installed extension actually exposes.
+FORMAT_NAMES = [n for n in GOLDEN if hasattr(lmc_ops.EngineKVFormat, n)]
+
+
+@pytest.fixture(params=FORMAT_NAMES)
+def case(request):
+    name = request.param
+    return name, getattr(lmc_ops.EngineKVFormat, name), GOLDEN[name]
+
+
+def test_static_metadata(case):
+    # The format's static layout flags are pinned in test_kv_format_classification
+    # (read via lmc_ops); here we only freeze the symbolic shape.
+    name, fmt, gold = case
+    assert describe_shape(fmt) == gold["shape_desc"], name
+
+
+def test_scalar_geometry(case):
+    name, fmt, gold = case
+    spec = get_spec(_build(name), fmt)
+    for attr in (
+        "num_layers",
+        "page_buffer_size",
+        "num_heads",
+        "hidden_dim",
+        "head_size",
+        "tokens_per_layer",
+        "elements_per_layer",
+    ):
+        assert getattr(spec, attr)() == gold[attr], f"{name}.{attr}"
+    assert spec.dtype() == DT, name
+    assert spec.concrete_shape_str() == gold["concrete"], name
+
+
+def test_num_blocks_and_block_size(case):
+    name, fmt, gold = case
+    spec = get_spec(_build(name), fmt)
+    if gold["num_blocks"] is _RAISE:
+        with pytest.raises(ValueError):
+            spec.num_blocks()
+        with pytest.raises(ValueError):
+            spec.block_size()
+    else:
+        assert spec.num_blocks() == gold["num_blocks"], name
+        assert spec.block_size() == gold["block_size"], name
+
+
+def test_data_ptrs_shape(case):
+    name, fmt, gold = case
+    kv = _build(name)
+    spec = get_spec(kv, fmt)
+    ptrs = spec.data_ptrs(list(range(NL)))
+    if lmc_ops.is_cross_layer(fmt):
+        assert len(ptrs) == 1, name  # single base pointer
+    elif lmc_ops.is_kv_list(fmt):
+        assert len(ptrs) == 2 * NL, name  # K's then V's
+    else:
+        assert len(ptrs) == NL, name  # one per layer
+    assert all(isinstance(p, int) for p in ptrs), name
+
+
+def test_all_extension_formats_registered():
+    # No silent gaps: every format the extension exposes has a spec.
+    for name in FORMAT_NAMES:
+        assert get_spec_class(getattr(lmc_ops.EngineKVFormat, name)) is not None, name
+
+
+def test_spec_carries_attention_backends(case):
+    # First Party
+    from lmcache.v1.gpu_connector import utils
+
+    name, fmt, _ = case
+    cls = get_spec_class(fmt)
+    # Backend labels are colocated on the spec (one format -> many backends).
+    assert isinstance(cls.attention_backends, tuple) and cls.attention_backends, name
+    # The facade returns the first (canonical/representative) one.
+    assert utils.get_attention_backend(fmt) == cls.attention_backends[0], name
+
+
+def test_facade_diagnostic_labels(case):
+    # First Party
+    from lmcache.v1.gpu_connector import utils
+
+    name, fmt, gold = case
+    # get_engine_kv_shape_description is the geometry legend (delegates to spec).
+    assert utils.get_engine_kv_shape_description(fmt) == gold["shape_desc"], name
+    # get_attention_backend is a diagnostic-only representative label.
+    label = utils.get_attention_backend(fmt)
+    assert isinstance(label, str) and not label.startswith("Unknown"), name
diff --git a/tests/v1/gpu_connector/test_normalize_per_layer_formats.py b/tests/v1/gpu_connector/test_normalize_per_layer_formats.py
new file mode 100644
index 0000000..09c6373
--- /dev/null
+++ b/tests/v1/gpu_connector/test_normalize_per_layer_formats.py
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``normalize_and_discover_per_layer_formats``.
+
+Uniform models return the whole normalized structure (so a format that isn't a
+per-layer list -- a cross-layer fused tensor, or a ``[keys, values]`` K/V-split
+-- stays intact); mixed models report each engine group's own per-layer format.
+The K/V-split path is the SGLang regression: it must not be sliced per layer.
+"""
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.utils import normalize_and_discover_per_layer_formats
+import lmcache.c_ops as lmc_ops
+
+NB, NL, BS, NH, HS = 7, 5, 3, 2, 4
+DT = torch.float16
+F = lmc_ops.EngineKVFormat
+
+# The vLLM CPU-HND safeguard forces HND regardless of hint on a CPU host; bypass
+# it so the hint-driven NHD branch is exercised on any host.
+_VLLM_DEV = "lmcache.v1.gpu_connector.kv_format.detectors.vllm.torch_device_type"
+
+
+def _t(*shape: int) -> torch.Tensor:
+    return torch.zeros(shape, dtype=DT)
+
+
+def test_sglang_kv_list_uniform():
+    # Regression: a flat list of 2*NL tensors that detection regroups into a
+    # length-2 [key_layers, value_layers]. ``is_layer_list`` is False for the
+    # K/V-split format, so it is returned whole -- never sliced per layer.
+    flat = [_t(NB * BS, NH, HS) for _ in range(2 * NL)]
+    normalized, formats = normalize_and_discover_per_layer_formats(
+        flat, (), EngineType.SGLANG, {"tokens_per_block": BS}
+    )
+    assert len(normalized) == 2 and len(normalized[0]) == NL
+    assert tuple(normalized[0][0].shape) == (NB, BS, NH, HS)
+    assert formats == [F.TWO_X_NL_X_NB_BS_NH_HS] * NL
+
+
+def test_vllm_layer_list_uniform(monkeypatch):
+    # Per-layer-list format, every layer the same: whole list back, format per layer.
+    monkeypatch.setattr(_VLLM_DEV, "cuda")
+    kv = [_t(2, NB, BS, NH, HS) for _ in range(NL)]
+    normalized, formats = normalize_and_discover_per_layer_formats(
+        kv, (), EngineType.VLLM, {"kv_layout": "NHD"}
+    )
+    assert len(normalized) == NL
+    assert formats == [F.NL_X_TWO_NB_BS_NH_HS] * NL
+
+
+def test_vllm_heterogeneous_groups(monkeypatch):
+    # Mixed-format model: a full K/V group beside a key-only MLA index group.
+    monkeypatch.setattr(_VLLM_DEV, "cuda")
+    kv = [_t(2, NB, BS, NH, HS) for _ in range(3)] + [_t(NB, BS, HS) for _ in range(2)]
+    normalized, formats = normalize_and_discover_per_layer_formats(
+        kv, [[0, 1, 2], [3, 4]], EngineType.VLLM, {"kv_layout": "NHD"}
+    )
+    assert len(normalized) == 5
+    assert formats[:3] == [F.NL_X_TWO_NB_BS_NH_HS] * 3
+    assert formats[3:] == [F.NL_X_NB_BS_HS] * 2
diff --git a/tests/v1/gpu_connector/test_utils_shape_desc.py b/tests/v1/gpu_connector/test_utils_shape_desc.py
new file mode 100644
index 0000000..8c603de
--- /dev/null
+++ b/tests/v1/gpu_connector/test_utils_shape_desc.py
@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unit tests for the format-aware per-layer helpers in
+:mod:`lmcache.v1.gpu_connector.utils`.
+"""
+
+# Third Party
+import pytest
+import torch
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="PageBufferShapeDesc and GPUKVFormat require the CUDA build",
+)
+
+# First Party
+from lmcache.v1.gpu_connector.kv_format.contiguity import (  # noqa: E402
+    attempt_permute_to_contiguous_view,
+)
+from lmcache.v1.gpu_connector.utils import (  # noqa: E402
+    get_device,
+    get_dtype,
+    get_group_data_ptrs,
+    get_head_size,
+    get_num_heads,
+    make_page_buffer_shape_desc,
+)
+import lmcache.c_ops as lmc_ops  # noqa: E402
+
+
+def test_make_shape_desc_vllm_flash_attn_nhd():
+    kv_caches = [torch.empty(2, 32, 16, 8, 64, dtype=torch.bfloat16) for _ in range(4)]
+    sd = make_page_buffer_shape_desc(
+        kv_caches,
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        layer_idx=0,
+        num_layers_in_group=4,
+        num_blocks=32,
+        block_size=16,
+    )
+    assert sd.kv_size == 2
+    assert sd.nl == 4
+    assert sd.nb == 32
+    assert sd.bs == 16
+    assert sd.nh == 8
+    assert sd.hs == 64
+    assert sd.element_size == 2
+
+
+def test_make_shape_desc_vllm_flash_infer_nhd():
+    kv_caches = [torch.empty(32, 2, 16, 8, 64, dtype=torch.float16) for _ in range(2)]
+    sd = make_page_buffer_shape_desc(
+        kv_caches,
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,
+        layer_idx=0,
+        num_layers_in_group=2,
+        num_blocks=32,
+        block_size=16,
+    )
+    assert sd.nh == 8
+    assert sd.hs == 64
+    assert sd.kv_size == 2
+
+
+def test_make_shape_desc_vllm_mla():
+    kv_caches = [torch.empty(32, 16, 512, dtype=torch.bfloat16) for _ in range(3)]
+    sd = make_page_buffer_shape_desc(
+        kv_caches,
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+        layer_idx=0,
+        num_layers_in_group=3,
+        num_blocks=32,
+        block_size=16,
+    )
+    assert sd.kv_size == 1
+    assert sd.nh == 1
+    assert sd.hs == 512
+
+
+def test_make_shape_desc_sglang_mla():
+    kv_caches = [torch.empty(512, 1, 128, dtype=torch.bfloat16) for _ in range(2)]
+    sd = make_page_buffer_shape_desc(
+        kv_caches,
+        lmc_ops.EngineKVFormat.NL_X_NBBS_ONE_HS,
+        layer_idx=0,
+        num_layers_in_group=2,
+        num_blocks=32,
+        block_size=16,
+    )
+    assert sd.kv_size == 1
+    assert sd.nh == 1
+    assert sd.hs == 128
+
+
+def test_make_shape_desc_sglang_mha():
+    k = [torch.empty(512, 8, 64, dtype=torch.bfloat16) for _ in range(4)]
+    v = [torch.empty(512, 8, 64, dtype=torch.bfloat16) for _ in range(4)]
+    kv_caches = [k, v]
+    sd = make_page_buffer_shape_desc(
+        kv_caches,
+        lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS,
+        layer_idx=0,
+        num_layers_in_group=4,
+        num_blocks=32,
+        block_size=16,
+    )
+    assert sd.kv_size == 2
+    assert sd.nh == 8
+    assert sd.hs == 64
+
+
+def test_per_layer_scalar_accessors_per_layer_list():
+    """For per-layer list formats, each scalar accessor honours layer_idx."""
+    kv_caches = [
+        torch.randn(2, 32, 16, 8 + i, 64, dtype=torch.float16, device="cuda")
+        for i in range(3)  # distinct num_heads per layer: 8, 9, 10
+    ]
+    fmt = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+
+    assert get_num_heads(kv_caches, fmt, layer_idx=0) == 8
+    assert get_num_heads(kv_caches, fmt, layer_idx=2) == 10
+    assert get_head_size(kv_caches, fmt, layer_idx=1) == 64
+    assert get_dtype(kv_caches, fmt, layer_idx=0) == torch.float16
+
+
+def test_per_layer_scalar_accessors_sglang_mha():
+    """For SGLang MHA (nested list), accessors walk into [k_list|v_list]."""
+    k = [torch.randn(512, 8, 64, dtype=torch.bfloat16, device="cuda") for _ in range(2)]
+    v = [torch.randn(512, 8, 64, dtype=torch.bfloat16, device="cuda") for _ in range(2)]
+    kv_caches = [k, v]
+    fmt = lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS
+
+    assert get_num_heads(kv_caches, fmt, layer_idx=0) == 8
+    assert get_dtype(kv_caches, fmt, layer_idx=1) == torch.bfloat16
+
+
+def test_get_group_data_ptrs_per_layer_list_flattens_in_order():
+    kv_caches = [
+        torch.randn(2, 32, 16, 8, 64, dtype=torch.float16, device="cuda")
+        for _ in range(4)
+    ]
+    fmt = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+
+    ptrs = get_group_data_ptrs(kv_caches, fmt, [0, 2, 3])
+    assert ptrs == [
+        kv_caches[0].data_ptr(),
+        kv_caches[2].data_ptr(),
+        kv_caches[3].data_ptr(),
+    ]
+
+
+def test_get_group_data_ptrs_sglang_mha_groups_k_before_v():
+    """SGLang MHA kernel contract: [K0, K1, ..., KN, V0, V1, ..., VN] —
+    not per-layer [K0, V0, K1, V1, ...]."""
+    k = [torch.randn(512, 8, 64, dtype=torch.bfloat16, device="cuda") for _ in range(3)]
+    v = [torch.randn(512, 8, 64, dtype=torch.bfloat16, device="cuda") for _ in range(3)]
+    kv_caches = [k, v]
+    fmt = lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS
+
+    ptrs = get_group_data_ptrs(kv_caches, fmt, [0, 1, 2])
+    expected = [
+        k[0].data_ptr(),
+        k[1].data_ptr(),
+        k[2].data_ptr(),
+        v[0].data_ptr(),
+        v[1].data_ptr(),
+        v[2].data_ptr(),
+    ]
+    assert ptrs == expected
+
+
+def test_get_group_data_ptrs_cross_layer_returns_single_base():
+    """Cross-layer format packs every layer into one tensor; the kernel
+    (csrc/mp_mem_kernels.cu) reads paged_buffer_ptrs[0] and computes
+    per-layer offsets from shape_desc.nl internally. The group helper
+    must return a single base pointer, not num_layers entries."""
+    big = torch.empty(32, 80, 2, 16, 8, 64, dtype=torch.bfloat16, device="cuda")
+    fmt = lmc_ops.EngineKVFormat.NB_NL_TWO_BS_NH_HS
+    ptrs = get_group_data_ptrs(big, fmt, list(range(80)))
+    assert ptrs == [big.data_ptr()]
+
+
+def test_attempt_permute_preserves_bare_tensor():
+    """A bare torch.Tensor input (cross-layer shape) must pass through
+    attempt_permute_to_contiguous_view unchanged — no list wrapping — so the
+    DiscoverableKVCache recursive union is respected end-to-end."""
+    big = torch.empty(32, 80, 2, 16, 8, 64, dtype=torch.bfloat16, device="cuda")
+    out = attempt_permute_to_contiguous_view(big)
+    assert isinstance(out, torch.Tensor)
+    assert out is big
+
+
+def test_attempt_permute_recurses_all_shapes():
+    """attempt_permute_to_contiguous_view must descend into every
+    DiscoverableKVCache shape and permute non-contiguous tensor leaves."""
+    # Build a flash-attention HND-layout tensor (non-contiguous after
+    # logical→physical permute exposure — the vLLM HND case).
+    nhd_view = (
+        torch.empty(2, 32, 8, 16, 64, dtype=torch.bfloat16, device="cuda")
+        .permute(0, 1, 3, 2, 4)
+        .contiguous()
+        .permute(0, 1, 3, 2, 4)  # NHD logical view over HND physical
+    )
+    assert not nhd_view.is_contiguous()
+
+    # bare tensor
+    out_tensor = attempt_permute_to_contiguous_view(nhd_view)
+    assert out_tensor.is_contiguous()
+
+    # flat list
+    lst = [nhd_view.clone() for _ in range(2)]
+    out_list = attempt_permute_to_contiguous_view(lst)
+    assert isinstance(out_list, list)
+    assert all(t.is_contiguous() for t in out_list)
+
+    # nested list (SGLang-shaped)
+    k = [nhd_view.clone() for _ in range(2)]
+    v = [nhd_view.clone() for _ in range(2)]
+    out_nested = attempt_permute_to_contiguous_view([k, v])
+    assert isinstance(out_nested, list)
+    assert all(t.is_contiguous() for sublist in out_nested for t in sublist)
+
+
+def test_get_device_handles_every_kvcaches_shape():
+    """get_device must work for every DiscoverableKVCache shape without format hints."""
+    t = torch.empty(8, dtype=torch.bfloat16, device="cuda")
+    assert get_device(t) == t.device
+
+    flat = [torch.empty(4, dtype=torch.bfloat16, device="cuda") for _ in range(3)]
+    assert get_device(flat) == flat[0].device
+
+    k = [torch.empty(4, dtype=torch.bfloat16, device="cuda") for _ in range(2)]
+    v = [torch.empty(4, dtype=torch.bfloat16, device="cuda") for _ in range(2)]
+    assert get_device([k, v]) == k[0].device
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/tests/v1/internal_api_server/test_backend_api.py b/tests/v1/internal_api_server/test_backend_api.py
new file mode 100644
index 0000000..d20d91d
--- /dev/null
+++ b/tests/v1/internal_api_server/test_backend_api.py
@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test cases for the /backends/* API endpoints.
+
+Tests cover:
+- GET /backends  — list active backends
+- DELETE /backends/{name} — close and remove a backend
+- POST /backends — create new backends from current config
+- POST /backends/{name}/recreate — atomic close + create
+- End-to-end flow: close → conf update → create → verify
+"""
+
+# Standard
+from collections import OrderedDict
+from unittest.mock import MagicMock
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.internal_api_server.api_server import app
+
+# ------------------------------------------------------------------ #
+#  Fixtures
+# ------------------------------------------------------------------ #
+
+
+class FakeBackend:
+    """Minimal fake backend for testing."""
+
+    def __init__(self, name: str = "FakeBackend"):
+        self._name = name
+        self.closed = False
+
+    def close(self):
+        self.closed = True
+
+    def __str__(self):
+        return self._name
+
+
+@pytest.fixture
+def mock_storage_manager():
+    """Create a mock StorageManager with two fake backends."""
+    sm = MagicMock()
+    fake_cpu = FakeBackend("LocalCPUBackend")
+    fake_remote = FakeBackend("RemoteBackend")
+    backends = OrderedDict(
+        [
+            ("LocalCPUBackend", fake_cpu),
+            ("RemoteBackend", fake_remote),
+        ]
+    )
+    sm.storage_backends = backends
+
+    # Wire real-ish list_backends
+    sm.list_backends.side_effect = lambda: {
+        n: type(b).__name__ for n, b in sm.storage_backends.items()
+    }
+    return sm
+
+
+@pytest.fixture
+def mock_engine(mock_storage_manager):
+    engine = MagicMock()
+    engine.storage_manager = mock_storage_manager
+    return engine
+
+
+@pytest.fixture
+def client_with_engine(mock_engine):
+    adapter = MagicMock()
+    adapter.lmcache_engine = mock_engine
+    app.state.lmcache_adapter = adapter
+    client = TestClient(app)
+    yield client
+    client.close()
+
+
+@pytest.fixture
+def client_without_engine():
+    adapter = MagicMock()
+    adapter.lmcache_engine = None
+    app.state.lmcache_adapter = adapter
+    client = TestClient(app)
+    yield client
+    client.close()
+
+
+# ------------------------------------------------------------------ #
+#  GET /backends
+# ------------------------------------------------------------------ #
+
+
+class TestListBackends:
+    def test_list_success(self, client_with_engine, mock_storage_manager):
+        resp = client_with_engine.get("/backends")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "LocalCPUBackend" in data
+        assert "RemoteBackend" in data
+
+    def test_list_no_engine(self, client_without_engine):
+        resp = client_without_engine.get("/backends")
+        assert resp.status_code == 503
+
+    def test_list_exception(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.list_backends.side_effect = RuntimeError("boom")
+        resp = client_with_engine.get("/backends")
+        assert resp.status_code == 500
+        data = resp.json()
+        assert "boom" in data["message"]
+
+
+# ------------------------------------------------------------------ #
+#  DELETE /backends/{name}
+# ------------------------------------------------------------------ #
+
+
+class TestCloseBackend:
+    def test_close_success(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.close_backend.return_value = True
+        resp = client_with_engine.delete("/backends/RemoteBackend")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        mock_storage_manager.close_backend.assert_called_once_with("RemoteBackend")
+
+    def test_close_not_found(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.close_backend.return_value = False
+        resp = client_with_engine.delete("/backends/NonExistent")
+        assert resp.status_code == 404
+        data = resp.json()
+        assert data["status"] == "not_found"
+
+    def test_close_no_engine(self, client_without_engine):
+        resp = client_without_engine.delete("/backends/RemoteBackend")
+        assert resp.status_code == 503
+
+    def test_close_exception(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.close_backend.side_effect = RuntimeError("close error")
+        resp = client_with_engine.delete("/backends/RemoteBackend")
+        assert resp.status_code == 500
+        data = resp.json()
+        assert "close error" in data["message"]
+
+
+# ------------------------------------------------------------------ #
+#  POST /backends
+# ------------------------------------------------------------------ #
+
+
+class TestCreateBackends:
+    def test_create_success(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.create_backends.return_value = {"GdsBackend": "GdsBackend"}
+        resp = client_with_engine.post("/backends")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        assert "GdsBackend" in data["created"]
+
+    def test_create_no_engine(self, client_without_engine):
+        resp = client_without_engine.post("/backends")
+        assert resp.status_code == 503
+
+    def test_create_exception(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.create_backends.side_effect = RuntimeError("create error")
+        resp = client_with_engine.post("/backends")
+        assert resp.status_code == 500
+        data = resp.json()
+        assert "create error" in data["message"]
+
+
+# ------------------------------------------------------------------ #
+#  POST /backends/{name}/recreate
+# ------------------------------------------------------------------ #
+
+
+class TestRecreateBackend:
+    def test_recreate_success(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.recreate_backend.return_value = {
+            "RemoteBackend": "RemoteBackend"
+        }
+        resp = client_with_engine.post("/backends/RemoteBackend/recreate")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        assert "RemoteBackend" in data["recreated"]
+        mock_storage_manager.recreate_backend.assert_called_once_with("RemoteBackend")
+
+    def test_recreate_not_found(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.recreate_backend.side_effect = KeyError(
+            "Backend NonExistent not found"
+        )
+        resp = client_with_engine.post("/backends/NonExistent/recreate")
+        assert resp.status_code == 404
+        data = resp.json()
+        assert data["status"] == "not_found"
+
+    def test_recreate_no_engine(self, client_without_engine):
+        resp = client_without_engine.post("/backends/RemoteBackend/recreate")
+        assert resp.status_code == 503
+
+    def test_recreate_exception(self, client_with_engine, mock_storage_manager):
+        mock_storage_manager.recreate_backend.side_effect = RuntimeError(
+            "recreate error"
+        )
+        resp = client_with_engine.post("/backends/RemoteBackend/recreate")
+        assert resp.status_code == 500
+        data = resp.json()
+        assert "recreate error" in data["message"]
+
+
+# ------------------------------------------------------------------ #
+#  End-to-end flow: close → conf → create
+# ------------------------------------------------------------------ #
+
+
+class TestBackendSwitchFlow:
+    """Simulate the full backend-switch workflow via API."""
+
+    def test_close_update_conf_create_flow(
+        self, client_with_engine, mock_storage_manager
+    ):
+        """
+        1. DELETE /backends/RemoteBackend
+        2. POST /conf to update remote_url
+        3. POST /backends to create new RemoteBackend
+        4. GET /backends to verify
+        """
+        # Step 1: close RemoteBackend
+        mock_storage_manager.close_backend.return_value = True
+        resp = client_with_engine.delete("/backends/RemoteBackend")
+        assert resp.status_code == 200
+
+        # Step 2: update config via /conf (uses conf_api)
+        # We patch the config object on the adapter
+        mock_config = MagicMock()
+        client_with_engine.app.state.lmcache_adapter.config = mock_config
+
+        # Step 3: create new backends
+        mock_storage_manager.create_backends.return_value = {
+            "RemoteBackend": "RemoteBackend"
+        }
+        resp = client_with_engine.post("/backends")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        assert "RemoteBackend" in data["created"]
+
+        # Step 4: list backends
+        resp = client_with_engine.get("/backends")
+        assert resp.status_code == 200
diff --git a/tests/v1/internal_api_server/test_cache_clear.py b/tests/v1/internal_api_server/test_cache_clear.py
new file mode 100644
index 0000000..f3b82bc
--- /dev/null
+++ b/tests/v1/internal_api_server/test_cache_clear.py
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock
+import json
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.internal_api_server.api_server import app
+
+
+class TestCacheClearAPI:
+    """Test suite for the /cache/clear API endpoint."""
+
+    @pytest.fixture
+    def mock_lmcache_adapter(self):
+        """Create a mock LMCacheConnectorV1Impl adapter."""
+        adapter = MagicMock()
+
+        # Create a mock LMCache engine
+        mock_engine = MagicMock(spec=LMCacheEngine)
+        mock_engine.clear.return_value = 5  # Mock return value for clear operation
+
+        adapter.lmcache_engine = mock_engine
+        return adapter
+
+    @pytest.fixture
+    def client_with_adapter(self, mock_lmcache_adapter):
+        """Create a test client with mocked adapter."""
+        app.state.lmcache_adapter = mock_lmcache_adapter
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    def test_cache_clear_success(self, client_with_adapter, mock_lmcache_adapter):
+        """Test successful cache clear operation."""
+        # Act
+        response = client_with_adapter.delete("/cache/clear")
+
+        # Assert
+        assert response.status_code == 200
+        response_data = json.loads(response.text)
+        assert response_data["status"] == "success"
+        assert response_data["num_removed"] == 5
+
+        # Verify that the clear method was called with correct parameters
+        mock_lmcache_adapter.lmcache_engine.clear.assert_called_once_with(
+            locations=None, request_configs=None
+        )
+
+    @pytest.mark.parametrize(
+        "locations,test_description",
+        [
+            (["LocalCPUBackend", "LocalDiskBackend"], "multiple locations"),
+            (["LocalCPUBackend"], "single location"),
+        ],
+    )
+    def test_cache_clear_with_locations(
+        self, client_with_adapter, mock_lmcache_adapter, locations, test_description
+    ):
+        """Test cache clear with specific locations."""
+        # Act
+        # curl -X DELETE "http://localhost:8000/cache/clear?locations=LocalCPUBackend&locations=LocalDiskBackend"
+        response = client_with_adapter.delete(
+            "/cache/clear", params={"locations": locations}
+        )
+
+        # Assert
+        assert response.status_code == 200
+        response_data = json.loads(response.text)
+        assert response_data["status"] == "success"
+        assert response_data["num_removed"] == 5
+
+        # Verify that the clear method was called with the correct locations
+        mock_lmcache_adapter.lmcache_engine.clear.assert_called_once()
+        call_args = mock_lmcache_adapter.lmcache_engine.clear.call_args
+
+        # Verify the locations parameter was passed correctly
+        assert call_args is not None
+        assert "locations" in call_args.kwargs
+        assert "request_configs" in call_args.kwargs
+
+        # Assert that the locations parameter matches what we sent
+        assert call_args.kwargs["locations"] == locations
+
+    def test_cache_clear_engine_exception(
+        self, client_with_adapter, mock_lmcache_adapter
+    ):
+        """Test cache clear when engine raises an exception."""
+        # Arrange
+        mock_lmcache_adapter.lmcache_engine.clear.side_effect = Exception("Cache error")
+
+        # Act
+        response = client_with_adapter.delete("/cache/clear")
+
+        # Assert
+        assert response.status_code == 500
+        response_data = json.loads(response.text)
+        assert response_data["error"] == "Failed to clear cache"
+        assert response_data["message"] == "Cache error"
+
+    def test_cache_clear_negative_return_value(
+        self, client_with_adapter, mock_lmcache_adapter
+    ):
+        """Test cache clear when engine returns negative value (edge case)."""
+        # Arrange
+        mock_lmcache_adapter.lmcache_engine.clear.return_value = -1
+
+        # Act
+        response = client_with_adapter.delete("/cache/clear")
+
+        # Assert
+        assert response.status_code == 200
+        response_data = json.loads(response.text)
+        assert response_data["status"] == "success"
+        assert response_data["num_removed"] == -1
+
+    def test_cache_clear_adapter_attribute_error(self):
+        """Test cache clear when adapter doesn't have lmcache_engine attribute."""
+
+        # Arrange
+        class AdapterWithoutEngine:
+            pass
+
+        app.state.lmcache_adapter = AdapterWithoutEngine()
+        with TestClient(app) as client:
+            # Act
+            response = client.delete("/cache/clear")
+        # Assert
+        assert response.status_code == 503
+        response_data = json.loads(response.text)
+        assert response_data["error"] == "LMCache API is unavailable"
+        assert response_data["message"] == "LMCache engine not configured."
diff --git a/tests/v1/internal_api_server/test_hot_cache_api.py b/tests/v1/internal_api_server/test_hot_cache_api.py
new file mode 100644
index 0000000..21d6709
--- /dev/null
+++ b/tests/v1/internal_api_server/test_hot_cache_api.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock
+import json
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.internal_api_server.api_server import app
+
+
+class TestHotCacheAPI:
+    """Test suite for the /hot_cache/* API endpoints."""
+
+    @pytest.fixture
+    def mock_engine(self):
+        engine = MagicMock()
+        engine.set_hot_cache = MagicMock()
+        engine.is_hot_cache_enabled = MagicMock(return_value=False)
+        return engine
+
+    @pytest.fixture
+    def client_with_engine(self, mock_engine):
+        adapter = MagicMock()
+        adapter.lmcache_engine = mock_engine
+        app.state.lmcache_adapter = adapter
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    @pytest.fixture
+    def client_without_engine(self):
+        adapter = MagicMock()
+        adapter.lmcache_engine = None
+        app.state.lmcache_adapter = adapter
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    # --- enable ---
+
+    def test_enable_hot_cache_success(self, client_with_engine, mock_engine):
+        response = client_with_engine.put("/hot_cache/enable")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["status"] == "success"
+        assert data["hot_cache"] is True
+        mock_engine.set_hot_cache.assert_called_once_with(True)
+
+    def test_enable_hot_cache_no_engine(self, client_without_engine):
+        response = client_without_engine.put("/hot_cache/enable")
+        assert response.status_code == 503
+        data = json.loads(response.text)
+        assert "unavailable" in data["error"]
+
+    def test_enable_hot_cache_exception(self, client_with_engine, mock_engine):
+        mock_engine.set_hot_cache.side_effect = RuntimeError("test error")
+        response = client_with_engine.put("/hot_cache/enable")
+        assert response.status_code == 500
+        data = json.loads(response.text)
+        assert "test error" in data["message"]
+
+    # --- disable ---
+
+    def test_disable_hot_cache_success(self, client_with_engine, mock_engine):
+        response = client_with_engine.put("/hot_cache/disable")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["status"] == "success"
+        assert data["hot_cache"] is False
+        mock_engine.set_hot_cache.assert_called_once_with(False)
+
+    def test_disable_hot_cache_no_engine(self, client_without_engine):
+        response = client_without_engine.put("/hot_cache/disable")
+        assert response.status_code == 503
+
+    def test_disable_hot_cache_exception(self, client_with_engine, mock_engine):
+        mock_engine.set_hot_cache.side_effect = RuntimeError("boom")
+        response = client_with_engine.put("/hot_cache/disable")
+        assert response.status_code == 500
+        data = json.loads(response.text)
+        assert "boom" in data["message"]
+
+    # --- status ---
+
+    def test_status_hot_cache_enabled(self, client_with_engine, mock_engine):
+        mock_engine.is_hot_cache_enabled.return_value = True
+        response = client_with_engine.get("/hot_cache/status")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["hot_cache"] is True
+        assert "enabled" in data["message"]
+
+    def test_status_hot_cache_disabled(self, client_with_engine, mock_engine):
+        mock_engine.is_hot_cache_enabled.return_value = False
+        response = client_with_engine.get("/hot_cache/status")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["hot_cache"] is False
+        assert "disabled" in data["message"]
+
+    def test_status_hot_cache_no_engine(self, client_without_engine):
+        response = client_without_engine.get("/hot_cache/status")
+        assert response.status_code == 503
+
+    def test_status_hot_cache_exception(self, client_with_engine, mock_engine):
+        mock_engine.is_hot_cache_enabled.side_effect = RuntimeError("oops")
+        response = client_with_engine.get("/hot_cache/status")
+        assert response.status_code == 500
+        data = json.loads(response.text)
+        assert "oops" in data["message"]
diff --git a/tests/v1/internal_api_server/test_kvcache_check_api.py b/tests/v1/internal_api_server/test_kvcache_check_api.py
new file mode 100644
index 0000000..642a523
--- /dev/null
+++ b/tests/v1/internal_api_server/test_kvcache_check_api.py
@@ -0,0 +1,266 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Dict, List, Optional
+from unittest.mock import MagicMock
+import hashlib
+import json
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import compress_slot_mapping
+from lmcache.v1.internal_api_server.api_server import app
+
+
+class TestKVCacheCheckAPI:
+    """Test suite for the /kvcache/check API endpoint."""
+
+    @pytest.fixture(autouse=True)
+    def reset_adapter(self):
+        """Reset adapter before each test."""
+        yield
+        app.state.lmcache_adapter = None
+
+    @pytest.fixture
+    def mock_kv_caches(self) -> Dict[str, torch.Tensor]:
+        """Create mock kv_caches tensors for testing."""
+        return {
+            "layer_0": torch.randn(4, 4, 8, 64),
+            "layer_1": torch.randn(4, 4, 8, 64),
+        }
+
+    @pytest.fixture
+    def mock_lmcache_adapter(self, mock_kv_caches):
+        """Create a mock LMCacheConnectorV1Impl adapter."""
+        adapter = MagicMock()
+        adapter.kv_caches = mock_kv_caches
+        adapter.kvcaches = mock_kv_caches  # API uses kvcaches (no underscore)
+
+        # Mock lmcache_engine for record_slot tests
+        mock_engine = MagicMock()
+        mock_engine.kvcache_check_log_enabled = False
+        adapter.lmcache_engine = mock_engine
+
+        def compute_checksums(
+            slot_indices: List[int], chunk_size: Optional[int] = None
+        ) -> Optional[Dict[str, Any]]:
+            if not adapter.kv_caches:
+                return None
+
+            layer_checksums: Dict[str, str] = {}
+            chunk_checksums: Dict[str, List[str]] = {}
+
+            for layer_name, kv_tensor in adapter.kv_caches.items():
+                slot_tensor = torch.tensor(
+                    slot_indices, dtype=torch.long, device=kv_tensor.device
+                )
+                kv_at_slots = kv_tensor.view(-1, *kv_tensor.shape[2:])[slot_tensor]
+                tensor_bytes = kv_at_slots.detach().cpu().contiguous().numpy().tobytes()
+                layer_checksums[layer_name] = hashlib.md5(tensor_bytes).hexdigest()
+
+                if chunk_size and chunk_size > 0:
+                    num_slots = len(slot_indices)
+                    chunk_checksum_list: List[str] = []
+                    for i in range((num_slots + chunk_size - 1) // chunk_size):
+                        chunk_data = kv_at_slots[i * chunk_size : (i + 1) * chunk_size]
+                        chunk_bytes = (
+                            chunk_data.detach().cpu().contiguous().numpy().tobytes()
+                        )
+                        chunk_checksum_list.append(hashlib.md5(chunk_bytes).hexdigest())
+                    chunk_checksums[layer_name] = chunk_checksum_list
+
+            result: Dict[str, Any] = {"layer_checksums": layer_checksums}
+            if chunk_size:
+                result["chunk_checksums"] = chunk_checksums
+                result["chunk_size"] = chunk_size
+                result["num_chunks"] = (
+                    (len(slot_indices) + chunk_size - 1) // chunk_size
+                    if slot_indices
+                    else 0
+                )
+            return result
+
+        adapter.compute_kvcache_checksums = compute_checksums
+        return adapter
+
+    @pytest.fixture
+    def client_with_adapter(self, mock_lmcache_adapter):
+        """Create a test client with mocked adapter."""
+        app.state.lmcache_adapter = mock_lmcache_adapter
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    # ==========================================================================
+    # Tests for /kvcache/check endpoint
+    # ==========================================================================
+
+    def test_kvcache_check_success_layer_only(self, client_with_adapter):
+        """Test successful kvcache check with layer-level checksums."""
+        response = client_with_adapter.get(
+            "/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"
+        )
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["status"] == "success"
+        assert "chunk_checksums" in data
+
+    @pytest.mark.parametrize(
+        "url,expected_error",
+        [
+            ("/cache/kvcache/check?slot_mapping=a,b,c", "Invalid slot_mapping format"),
+            (
+                "/cache/kvcache/check?slot_mapping=0,1&chunk_size=0",
+                "Invalid chunk_size",
+            ),
+            (
+                "/cache/kvcache/check?slot_mapping=0,1&chunk_size=-1",
+                "Invalid chunk_size",
+            ),
+        ],
+    )
+    def test_kvcache_check_invalid_params(
+        self, client_with_adapter, url, expected_error
+    ):
+        """Test kvcache check with various invalid parameters."""
+        response = client_with_adapter.get(url)
+        assert response.status_code == 400
+        assert json.loads(response.text)["error"] == expected_error
+
+    @pytest.mark.parametrize(
+        "slots,chunk_size,expected_chunks",
+        [
+            ("0,1,2,3,4,5,6,7", 4, 2),
+            ("0,1,2,3,4,5,6", 3, 3),
+            ("0,1,2,3", 4, 1),
+            ("0,1,2,3", 1, 4),
+        ],
+    )
+    def test_kvcache_check_with_chunk_size(
+        self, client_with_adapter, slots, chunk_size, expected_chunks
+    ):
+        """Test kvcache check with various chunk sizes."""
+        response = client_with_adapter.get(
+            f"/cache/kvcache/check?slot_mapping={slots}&chunk_size={chunk_size}"
+        )
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["num_chunks"] == expected_chunks
+
+    def test_kvcache_check_consistency(self, client_with_adapter):
+        """Test that checksums are consistent across calls."""
+        url = "/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"
+        data1 = json.loads(client_with_adapter.get(url).text)
+        data2 = json.loads(client_with_adapter.get(url).text)
+        assert data1["chunk_checksums"] == data2["chunk_checksums"]
+
+    # ==========================================================================
+    # Tests for adapter unavailable scenarios
+    # ==========================================================================
+
+    @pytest.mark.parametrize(
+        "method,url",
+        [
+            ("get", "/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"),
+            ("get", "/cache/kvcache/info"),
+            ("post", "/cache/kvcache/record_slot?enabled=true"),
+        ],
+    )
+    def test_no_adapter(self, method, url):
+        """Test endpoints when adapter is not available."""
+        app.state.lmcache_adapter = None
+        with TestClient(app) as client:
+            response = getattr(client, method)(url)
+        assert response.status_code == 503
+        assert json.loads(response.text)["error"] == "LMCache adapter unavailable"
+
+    def test_kvcache_check_empty_kv_caches(self):
+        """Test kvcache check when kv_caches is empty."""
+        adapter = MagicMock()
+        adapter.kv_caches = {}
+        adapter.kvcaches = {}
+        adapter.compute_kvcache_checksums = MagicMock(return_value=None)
+        app.state.lmcache_adapter = adapter
+        with TestClient(app) as client:
+            response = client.get(
+                "/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"
+            )
+        assert response.status_code == 404
+
+    # ==========================================================================
+    # Tests for /cache/kvcache/info endpoint
+    # ==========================================================================
+
+    def test_kvcache_info_success(self, client_with_adapter):
+        """Test successful kvcache info retrieval."""
+        response = client_with_adapter.get("/cache/kvcache/info")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["num_layers"] == 2
+        assert "layer_0" in data["layers"]
+
+    def test_kvcache_info_empty(self):
+        """Test kvcache info when kvcaches is empty."""
+        adapter = MagicMock()
+        adapter.kvcaches = {}
+        app.state.lmcache_adapter = adapter
+        with TestClient(app) as client:
+            response = client.get("/cache/kvcache/info")
+        assert response.status_code == 404
+
+    # ==========================================================================
+    # Tests for /cache/kvcache/record_slot endpoint
+    # ==========================================================================
+
+    @pytest.mark.parametrize(
+        "enabled_param,expected_value",
+        [("true", True), ("false", False), ("TRUE", True), ("False", False)],
+    )
+    def test_kvcache_record_slot_toggle(
+        self, client_with_adapter, mock_lmcache_adapter, enabled_param, expected_value
+    ):
+        """Test enabling/disabling KVCache Check logging."""
+        response = client_with_adapter.post(
+            f"/cache/kvcache/record_slot?enabled={enabled_param}"
+        )
+        assert response.status_code == 200
+        assert (
+            mock_lmcache_adapter.lmcache_engine.kvcache_check_log_enabled
+            == expected_value
+        )
+
+    def test_kvcache_record_slot_invalid(self, client_with_adapter):
+        """Test with invalid enabled parameter."""
+        response = client_with_adapter.post(
+            "/cache/kvcache/record_slot?enabled=invalid"
+        )
+        assert response.status_code == 400
+
+
+class TestCompressSlotMapping:
+    """Test suite for the compress_slot_mapping function."""
+
+    @pytest.mark.parametrize(
+        "input_slots,expected",
+        [
+            ([1, 2, 3, 4, 5], [[1, 5]]),
+            ([1, 2, 3, 4, 5, 9, 10, 11, 12], [[1, 5], [9, 12]]),
+            # No consecutive elements, no compression
+            ([1, 3, 5, 7], [1, 3, 5, 7]),
+            # 5 is single, not compressed
+            ([1, 2, 3, 5, 7, 8, 9], [[1, 3], 5, [7, 9]]),
+            ([], []),
+            ([42], [42]),  # Single element, not compressed
+            # Mixed order
+            ([5, 3, 1, 2, 4, 9, 10, 11, 13], [5, 3, 1, 2, 4, [9, 11], 13]),
+            ([0, 1, 2, 100, 101, 102], [[0, 2], [100, 102]]),
+            ([1, 2], [1, 2]),  # Two elements, not compressed
+            ([1, 2, 3], [[1, 3]]),  # Three elements, compressed
+        ],
+    )
+    def test_compress_slot_mapping(self, input_slots, expected):
+        """Test compression of slot mappings."""
+        assert compress_slot_mapping(input_slots) == expected
diff --git a/tests/v1/internal_api_server/test_load_fs_chunks.py b/tests/v1/internal_api_server/test_load_fs_chunks.py
new file mode 100644
index 0000000..3331439
--- /dev/null
+++ b/tests/v1/internal_api_server/test_load_fs_chunks.py
@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock
+import asyncio
+import json
+import os
+import shutil
+import tempfile
+import threading
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+import torch
+import yaml
+
+# First Party
+from lmcache.utils import CacheEngineKey, start_loop_in_thread_with_exceptions
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.internal_api_server.api_server import app
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+from tests.v1.utils import create_test_memory_obj
+
+
+class TestLoadFSChunksAPI:
+    """Test suite for the /cache/load-fs-chunks API endpoint."""
+
+    @pytest.fixture
+    def temp_fs_path(self):
+        """Create a temporary directory for FSConnector storage."""
+        temp_dir = tempfile.mkdtemp(prefix="lmcache_test_")
+        yield temp_dir
+        if os.path.exists(temp_dir):
+            shutil.rmtree(temp_dir)
+
+    @pytest.fixture
+    def async_loop(self):
+        """Create an event loop for async operations."""
+        loop = asyncio.new_event_loop()
+
+        thread = threading.Thread(
+            target=start_loop_in_thread_with_exceptions,
+            args=(loop,),
+            name="test-async-loop",
+        )
+        thread.start()
+
+        yield loop
+
+        loop.call_soon_threadsafe(loop.stop)
+        thread.join(timeout=5.0)
+
+    @pytest.fixture
+    def local_cpu_backend(self, test_metadata):
+        """Create a LocalCPUBackend for testing."""
+        config = LMCacheEngineConfig.from_defaults(chunk_size=256)
+        allocator = AdHocMemoryAllocator(device="cpu")
+        backend = LocalCPUBackend(config, test_metadata, memory_allocator=allocator)
+        yield backend
+        backend.memory_allocator.close()
+
+    @pytest.fixture
+    def test_metadata(self):
+        """Create test metadata."""
+        return LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(28, 2, 256, 8, 128),
+        )
+
+    @pytest.fixture
+    def mock_lmcache_adapter(self, local_cpu_backend, test_metadata, async_loop):
+        """Create a mock LMCacheConnectorV1Impl adapter with real backend."""
+        adapter = MagicMock()
+        mock_engine = MagicMock(spec=LMCacheEngine)
+        mock_engine.metadata = test_metadata
+        mock_engine.local_cpu_backend = local_cpu_backend
+
+        # Mock storage_manager with allocator_backend and loop
+        mock_storage_manager = MagicMock()
+        mock_storage_manager.allocator_backend = local_cpu_backend
+        mock_storage_manager.loop = async_loop
+        mock_engine.storage_manager = mock_storage_manager
+
+        adapter.lmcache_engine = mock_engine
+        return adapter
+
+    @pytest.fixture
+    def client_with_adapter(self, mock_lmcache_adapter):
+        """Create a test client with mocked adapter."""
+        app.state.lmcache_adapter = mock_lmcache_adapter
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    @pytest.fixture
+    def temp_config_file(self, temp_fs_path):
+        """Create a temporary config file for testing."""
+        config_data = {
+            "chunk_size": 256,
+            "local_cpu": False,
+            "max_local_cpu_size": 2.0,
+            "remote_url": f"fs://host:0/{temp_fs_path}",
+        }
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+            yaml.dump(config_data, f)
+            temp_path = f.name
+
+        yield temp_path
+
+        if os.path.exists(temp_path):
+            os.unlink(temp_path)
+
+    def _create_test_key(self, key_id: int) -> CacheEngineKey:
+        """Create a test CacheEngineKey."""
+        return CacheEngineKey(
+            model_name="test_model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=key_id,
+            dtype=torch.bfloat16,
+        )
+
+    def _prepare_test_data(
+        self,
+        temp_fs_path: str,
+        async_loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        test_metadata: LMCacheMetadata,
+        num_chunks: int = 3,
+    ):
+        """Prepare test data by putting chunks into FSConnector."""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            remote_url=f"fs://host:0/{temp_fs_path}",
+            remote_serde="naive",
+        )
+
+        remote_backend = RemoteBackend(
+            config=config,
+            metadata=test_metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+        try:
+            for i in range(num_chunks):
+                key = self._create_test_key(i)
+                memory_obj = create_test_memory_obj()
+                future = remote_backend.submit_put_task(key, memory_obj)
+                if future:
+                    future.result(timeout=5.0)
+        finally:
+            remote_backend.close()
+        return num_chunks
+
+    def test_load_fs_chunks_success(
+        self,
+        client_with_adapter,
+        mock_lmcache_adapter,
+        temp_config_file,
+        temp_fs_path,
+        async_loop,
+        local_cpu_backend,
+        test_metadata,
+    ):
+        """Test successful load-fs-chunks operation with real FSConnector."""
+        num_chunks = 3
+        self._prepare_test_data(
+            temp_fs_path,
+            async_loop,
+            local_cpu_backend,
+            test_metadata,
+            num_chunks=num_chunks,
+        )
+
+        response = client_with_adapter.post(
+            "/cache/load-fs-chunks",
+            json={"config_path": temp_config_file, "max_chunks": 2},
+        )
+
+        assert response.status_code == 200
+        response_data = json.loads(response.text)
+        assert response_data["status"] == "success"
+        assert response_data["loaded_chunks"] == 2
+        assert response_data["total_files"] == 3
+        assert response_data["config_path"] == temp_config_file
+
+        self._verify_hot_cache(local_cpu_backend, num_chunks, 2)
+
+    def test_load_fs_chunks_no_engine(self, client_with_adapter, temp_config_file):
+        """Test load-fs-chunks when engine is not configured."""
+        app.state.lmcache_adapter = None
+
+        response = client_with_adapter.post(
+            "/cache/load-fs-chunks", json={"config_path": temp_config_file}
+        )
+
+        assert response.status_code == 503
+        response_data = json.loads(response.text)
+        assert response_data["error"] == "/cache/load-fs-chunks API is unavailable"
+        assert response_data["message"] == "LMCache engine not configured."
+
+    def test_load_fs_chunks_invalid_config(
+        self, client_with_adapter, mock_lmcache_adapter
+    ):
+        """Test load-fs-chunks with invalid config file."""
+        response = client_with_adapter.post(
+            "/cache/load-fs-chunks", json={"config_path": "/nonexistent/config.json"}
+        )
+
+        assert response.status_code == 400
+        response_data = json.loads(response.text)
+        assert "Invalid configuration file" in response_data["detail"]
+
+    def test_load_fs_chunks_empty_directory(
+        self,
+        client_with_adapter,
+        mock_lmcache_adapter,
+        temp_config_file,
+        temp_fs_path,
+    ):
+        """Test load-fs-chunks with empty FSConnector directory."""
+        response = client_with_adapter.post(
+            "/cache/load-fs-chunks", json={"config_path": temp_config_file}
+        )
+
+        assert response.status_code == 200
+        response_data = json.loads(response.text)
+        assert response_data["status"] == "success"
+        assert response_data["loaded_chunks"] == 0
+        assert response_data["total_files"] == 0
+
+    def _verify_hot_cache(
+        self, local_cpu_backend: LocalCPUBackend, num_chunks: int, expected_count: int
+    ):
+        """Verify hot cache contains expected memory objects with ref count 1."""
+        with local_cpu_backend.cpu_lock:
+            assert len(local_cpu_backend.hot_cache) == expected_count
+
+            # Check that exactly expected_count keys from total_files
+            # are present in hot cache
+            found_count = 0
+            for i in range(num_chunks):  # total_files is num_chunks
+                key = self._create_test_key(i)
+                if key in local_cpu_backend.hot_cache:
+                    found_count += 1
+                    memory_obj = local_cpu_backend.hot_cache[key]
+                    assert memory_obj.get_ref_count() == 1
+
+            # Verify that we found exactly expected_count keys
+            assert found_count == expected_count
+
+    def test_load_fs_chunks_all_chunks(
+        self,
+        client_with_adapter,
+        mock_lmcache_adapter,
+        temp_config_file,
+        temp_fs_path,
+        async_loop,
+        local_cpu_backend,
+        test_metadata,
+    ):
+        """Test load-fs-chunks loading all chunks without max_chunks limit."""
+        num_chunks = 3
+        self._prepare_test_data(
+            temp_fs_path,
+            async_loop,
+            local_cpu_backend,
+            test_metadata,
+            num_chunks=num_chunks,
+        )
+
+        response = client_with_adapter.post(
+            "/cache/load-fs-chunks", json={"config_path": temp_config_file}
+        )
+
+        assert response.status_code == 200
+        response_data = json.loads(response.text)
+        assert response_data["status"] == "success"
+        assert response_data["loaded_chunks"] == 3
+        assert response_data["total_files"] == 3
+        assert len(response_data["failed_keys"]) == 0
+
+        self._verify_hot_cache(local_cpu_backend, num_chunks, 3)
diff --git a/tests/v1/internal_api_server/test_lookup_api.py b/tests/v1/internal_api_server/test_lookup_api.py
new file mode 100644
index 0000000..ef538c6
--- /dev/null
+++ b/tests/v1/internal_api_server/test_lookup_api.py
@@ -0,0 +1,334 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock
+import json
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.internal_api_server.api_server import app
+
+
+def _make_metadata(role: str) -> MagicMock:
+    """Create a mock metadata with the given role."""
+    metadata = MagicMock()
+    metadata.role = role
+    return metadata
+
+
+class TestLookupAPI:
+    """Test suite for the /lookup/* API endpoints."""
+
+    @pytest.fixture
+    def mock_scheduler_manager(self):
+        """Create a mock LMCacheManager for scheduler role."""
+        manager = MagicMock()
+        manager.lmcache_engine_metadata = _make_metadata("scheduler")
+        manager.get_lookup_info.return_value = {
+            "client": "HitLimitLookupClient(LMCacheBypassLookupClient)",
+            "server": "None",
+        }
+        manager.close_lookup_client.return_value = {
+            "old": "HitLimitLookupClient(LMCacheBypassLookupClient)"
+        }
+        manager.create_lookup_client.return_value = {"new": "LMCacheLookupClient"}
+        manager.recreate_lookup_client.return_value = {
+            "old": "HitLimitLookupClient(LMCacheBypassLookupClient)",
+            "new": "LMCacheLookupClient",
+        }
+        return manager
+
+    @pytest.fixture
+    def mock_worker_manager(self):
+        """Create a mock LMCacheManager for worker role."""
+        manager = MagicMock()
+        manager.lmcache_engine_metadata = _make_metadata("worker")
+        manager.get_lookup_info.return_value = {
+            "client": "None",
+            "server": "LMCacheLookupServer",
+        }
+        manager.close_lookup_server.return_value = {"old": "LMCacheLookupServer"}
+        manager.create_lookup_server.return_value = {"new": "LMCacheAsyncLookupServer"}
+        manager.recreate_lookup_server.return_value = {
+            "old": "LMCacheLookupServer",
+            "new": "LMCacheAsyncLookupServer",
+        }
+        return manager
+
+    @pytest.fixture
+    def scheduler_client(self, mock_scheduler_manager):
+        """Create a test client with mocked scheduler manager."""
+        app.state.lmcache_adapter = mock_scheduler_manager
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    @pytest.fixture
+    def worker_client(self, mock_worker_manager):
+        """Create a test client with mocked worker manager."""
+        app.state.lmcache_adapter = mock_worker_manager
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    # ==================== GET /lookup/info Tests ====================
+
+    def test_get_lookup_info_scheduler(self, scheduler_client, mock_scheduler_manager):
+        """Test get lookup info for scheduler role."""
+        response = scheduler_client.get("/lookup/info")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert "LMCacheBypassLookupClient" in data["client"]
+        assert data["server"] == "None"
+        mock_scheduler_manager.get_lookup_info.assert_called_once()
+
+    def test_get_lookup_info_worker(self, worker_client, mock_worker_manager):
+        """Test get lookup info for worker role."""
+        response = worker_client.get("/lookup/info")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["client"] == "None"
+        assert data["server"] == "LMCacheLookupServer"
+        mock_worker_manager.get_lookup_info.assert_called_once()
+
+    def test_get_lookup_info_not_supported(self):
+        """Test get lookup info when manager doesn't support it."""
+
+        class SimpleAdapter:
+            pass
+
+        app.state.lmcache_adapter = SimpleAdapter()
+        with TestClient(app) as client:
+            response = client.get("/lookup/info")
+
+        assert response.status_code == 503
+        data = json.loads(response.text)
+        assert "error" in data
+
+    # ==================== POST /lookup/close Tests ====================
+
+    def test_close_lookup_scheduler(self, scheduler_client, mock_scheduler_manager):
+        """Test close lookup client for scheduler."""
+        response = scheduler_client.post("/lookup/close")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert "LMCacheBypassLookupClient" in data["old"]
+        assert data["role"] == "scheduler"
+        mock_scheduler_manager.close_lookup_client.assert_called_once()
+
+    def test_close_lookup_worker(self, worker_client, mock_worker_manager):
+        """Test close lookup server for worker."""
+        response = worker_client.post("/lookup/close")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["old"] == "LMCacheLookupServer"
+        assert data["role"] == "worker"
+        mock_worker_manager.close_lookup_server.assert_called_once()
+
+    # ==================== POST /lookup/create Tests ====================
+
+    def test_create_lookup_scheduler(self, scheduler_client, mock_scheduler_manager):
+        """Test create lookup client for scheduler."""
+        response = scheduler_client.post("/lookup/create")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["new"] == "LMCacheLookupClient"
+        assert data["role"] == "scheduler"
+        mock_scheduler_manager.create_lookup_client.assert_called_once_with(
+            dryrun=False
+        )
+
+    def test_create_lookup_worker(self, worker_client, mock_worker_manager):
+        """Test create lookup server for worker."""
+        response = worker_client.post("/lookup/create")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["new"] == "LMCacheAsyncLookupServer"
+        assert data["role"] == "worker"
+        mock_worker_manager.create_lookup_server.assert_called_once_with(dryrun=False)
+
+    def test_create_lookup_dryrun_scheduler(
+        self, scheduler_client, mock_scheduler_manager
+    ):
+        """Test dryrun create lookup client for scheduler."""
+        mock_scheduler_manager.create_lookup_client.return_value = {
+            "new": "LMCacheLookupClient",
+            "dryrun": True,
+        }
+
+        response = scheduler_client.post("/lookup/create?dryrun=true")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["new"] == "LMCacheLookupClient"
+        assert data["dryrun"] is True
+        mock_scheduler_manager.create_lookup_client.assert_called_once_with(dryrun=True)
+
+    def test_create_lookup_dryrun_worker(self, worker_client, mock_worker_manager):
+        """Test dryrun create lookup server for worker."""
+        mock_worker_manager.create_lookup_server.return_value = {
+            "new": "LMCacheAsyncLookupServer",
+            "dryrun": True,
+        }
+
+        response = worker_client.post("/lookup/create?dryrun=true")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["new"] == "LMCacheAsyncLookupServer"
+        assert data["dryrun"] is True
+        mock_worker_manager.create_lookup_server.assert_called_once_with(dryrun=True)
+
+    def test_create_lookup_error(self, scheduler_client, mock_scheduler_manager):
+        """Test create lookup with error."""
+        mock_scheduler_manager.create_lookup_client.return_value = {
+            "error": "metadata not available"
+        }
+
+        response = scheduler_client.post("/lookup/create")
+
+        assert response.status_code == 400
+        data = json.loads(response.text)
+        assert data["error"] == "metadata not available"
+
+    # ==================== POST /lookup/recreate Tests ====================
+
+    def test_recreate_lookup_scheduler(self, scheduler_client, mock_scheduler_manager):
+        """Test recreate lookup client for scheduler."""
+        response = scheduler_client.post("/lookup/recreate")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert "LMCacheBypassLookupClient" in data["old"]
+        assert data["new"] == "LMCacheLookupClient"
+        assert data["role"] == "scheduler"
+        mock_scheduler_manager.recreate_lookup_client.assert_called_once()
+
+    def test_recreate_lookup_worker(self, worker_client, mock_worker_manager):
+        """Test recreate lookup server for worker."""
+        response = worker_client.post("/lookup/recreate")
+
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["old"] == "LMCacheLookupServer"
+        assert data["new"] == "LMCacheAsyncLookupServer"
+        assert data["role"] == "worker"
+        mock_worker_manager.recreate_lookup_server.assert_called_once()
+
+    def test_recreate_lookup_error(self, scheduler_client, mock_scheduler_manager):
+        """Test recreate lookup with error."""
+        mock_scheduler_manager.recreate_lookup_client.return_value = {
+            "error": "only supported for scheduler role"
+        }
+
+        response = scheduler_client.post("/lookup/recreate")
+
+        assert response.status_code == 400
+        data = json.loads(response.text)
+        assert "error" in data
+
+    def test_recreate_lookup_unknown_role(self):
+        """Test recreation with unknown role."""
+        manager = MagicMock()
+        manager.lmcache_engine_metadata = _make_metadata("unknown")
+        app.state.lmcache_adapter = manager
+        with TestClient(app) as client:
+            response = client.post("/lookup/recreate")
+
+        assert response.status_code == 400
+        data = json.loads(response.text)
+        assert data["error"] == "Unknown role"
+
+    def test_recreate_lookup_no_metadata(self):
+        """Test recreation when metadata is not available."""
+        manager = MagicMock()
+        manager.lmcache_engine_metadata = None
+        app.state.lmcache_adapter = manager
+        with TestClient(app) as client:
+            response = client.post("/lookup/recreate")
+
+        assert response.status_code == 400
+        data = json.loads(response.text)
+        assert data["error"] == "Unknown role"
+
+    def test_recreate_lookup_not_supported(self):
+        """Test recreation when manager doesn't support it."""
+
+        class SimpleAdapter:
+            lmcache_engine_metadata = _make_metadata("scheduler")
+
+        app.state.lmcache_adapter = SimpleAdapter()
+        with TestClient(app) as client:
+            response = client.post("/lookup/recreate")
+
+        assert response.status_code == 503
+        data = json.loads(response.text)
+        assert "error" in data
+
+    # ==================== Integration Flow Tests ====================
+
+    def test_full_flow_worker_then_scheduler(
+        self, mock_worker_manager, mock_scheduler_manager
+    ):
+        """
+        Test the complete flow:
+        1. POST /lookup/recreate on worker (recreate server)
+        2. POST /lookup/recreate on scheduler (recreate client)
+
+        Note: Config should be updated via /conf API before each step.
+        """
+        # Step 1: Worker side - recreate server
+        app.state.lmcache_adapter = mock_worker_manager
+        with TestClient(app) as worker_client:
+            response = worker_client.post("/lookup/recreate")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert data["old"] == "LMCacheLookupServer"
+        assert data["new"] == "LMCacheAsyncLookupServer"
+        mock_worker_manager.recreate_lookup_server.assert_called_once()
+
+        # Step 2: Scheduler side - recreate client
+        app.state.lmcache_adapter = mock_scheduler_manager
+        with TestClient(app) as scheduler_client:
+            response = scheduler_client.post("/lookup/recreate")
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert "LMCacheBypassLookupClient" in data["old"]
+        assert data["new"] == "LMCacheLookupClient"
+        mock_scheduler_manager.recreate_lookup_client.assert_called_once()
+
+    def test_step_by_step_flow(self, mock_scheduler_manager):
+        """
+        Test step-by-step flow: dryrun -> close -> create.
+        """
+        app.state.lmcache_adapter = mock_scheduler_manager
+        with TestClient(app) as client:
+            # Step 1: Dryrun - check what would be created
+            mock_scheduler_manager.create_lookup_client.return_value = {
+                "new": "LMCacheLookupClient",
+                "dryrun": True,
+            }
+            response = client.post("/lookup/create?dryrun=true")
+            assert response.status_code == 200
+            data = json.loads(response.text)
+            assert data["dryrun"] is True
+
+            # Step 2: Close current client
+            response = client.post("/lookup/close")
+            assert response.status_code == 200
+            mock_scheduler_manager.close_lookup_client.assert_called_once()
+
+            # Step 3: Create new client
+            mock_scheduler_manager.create_lookup_client.return_value = {
+                "new": "LMCacheLookupClient"
+            }
+            response = client.post("/lookup/create")
+            assert response.status_code == 200
diff --git a/tests/v1/internal_api_server/test_per_instance_app.py b/tests/v1/internal_api_server/test_per_instance_app.py
new file mode 100644
index 0000000..7249b31
--- /dev/null
+++ b/tests/v1/internal_api_server/test_per_instance_app.py
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Regression test for issue #3104.
+
+In TP=1 non-MP vLLM mode, scheduler and worker are initialized in the
+same Python process and both construct ``InternalAPIServer``. Prior to
+the fix, the module-level ``app`` was shared across all instances, so
+the later-initialized scheduler (whose ``lmcache_engine`` is ``None``)
+overwrote the worker's ``app.state.lmcache_adapter``, causing every
+cache endpoint on the worker port to return 503.
+
+This test verifies that each ``InternalAPIServer`` owns its own
+FastAPI app and the adapters do not clobber each other.
+"""
+
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+from fastapi.testclient import TestClient
+
+# First Party
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.internal_api_server.api_server import InternalAPIServer
+from lmcache.v1.metadata import LMCacheMetadata
+
+
+def _make_config(port_start: int) -> LMCacheEngineConfig:
+    cfg = LMCacheEngineConfig.from_defaults(chunk_size=256, local_cpu=True)
+    cfg.internal_api_server_enabled = True
+    cfg.internal_api_server_port_start = port_start
+    cfg.internal_api_server_socket_path_prefix = None
+    return cfg
+
+
+def _make_worker_manager(cfg: LMCacheEngineConfig) -> MagicMock:
+    """Mock LMCacheManager representing a worker (engine present)."""
+    metadata = LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=None,
+        kv_shape=(1, 2, 256, 8, 128),
+    )
+    engine = MagicMock(spec=LMCacheEngine)
+    engine.config = cfg
+    engine.metadata = metadata
+    engine.clear.return_value = 7
+
+    manager = MagicMock()
+    manager.lmcache_engine = engine
+    manager.config = cfg
+    return manager
+
+
+def _make_scheduler_manager(cfg: LMCacheEngineConfig) -> MagicMock:
+    """Mock LMCacheManager representing a scheduler (no engine)."""
+    manager = MagicMock()
+    manager.lmcache_engine = None
+    manager.config = cfg
+    return manager
+
+
+def test_scheduler_does_not_overwrite_worker_adapter() -> None:
+    """Scheduler initialized after worker must not break worker endpoints."""
+    cfg = _make_config(port_start=17000)
+
+    worker_manager = _make_worker_manager(cfg)
+    worker_server = InternalAPIServer(worker_manager)
+
+    # Scheduler comes up after worker in TP=1 non-MP mode.
+    scheduler_manager = _make_scheduler_manager(cfg)
+    scheduler_server = InternalAPIServer(scheduler_manager)
+
+    # Each server must own a distinct FastAPI app.
+    assert worker_server.app is not scheduler_server.app
+
+    # Worker's adapter is still its own manager, not overwritten by
+    # the scheduler's manager (which has lmcache_engine=None).
+    assert worker_server.app.state.lmcache_adapter is worker_manager
+    assert scheduler_server.app.state.lmcache_adapter is scheduler_manager
+
+    # Worker cache endpoint works (returns 200 instead of 503).
+    with TestClient(worker_server.app) as client:
+        response = client.delete("/cache/clear")
+    assert response.status_code == 200
+    assert response.json()["num_removed"] == 7
+
+    # Scheduler endpoint correctly reports engine unavailable (503),
+    # because the scheduler genuinely has no engine.
+    with TestClient(scheduler_server.app) as client:
+        response = client.delete("/cache/clear")
+    assert response.status_code == 503
+
+
+def test_worker_after_scheduler_still_works() -> None:
+    """Reverse order: worker initialized after scheduler also stays healthy."""
+    cfg = _make_config(port_start=17100)
+
+    scheduler_manager = _make_scheduler_manager(cfg)
+    scheduler_server = InternalAPIServer(scheduler_manager)
+
+    worker_manager = _make_worker_manager(cfg)
+    worker_server = InternalAPIServer(worker_manager)
+
+    assert worker_server.app is not scheduler_server.app
+    assert worker_server.app.state.lmcache_adapter is worker_manager
+    assert scheduler_server.app.state.lmcache_adapter is scheduler_manager
+
+    with TestClient(worker_server.app) as client:
+        response = client.delete("/cache/clear")
+    assert response.status_code == 200
+    assert response.json()["num_removed"] == 7
diff --git a/tests/v1/internal_api_server/test_run_script.py b/tests/v1/internal_api_server/test_run_script.py
new file mode 100644
index 0000000..646f6e1
--- /dev/null
+++ b/tests/v1/internal_api_server/test_run_script.py
@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+from unittest.mock import MagicMock
+import json
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.internal_api_server.api_server import app
+
+
+def _get_test_scripts_static():
+    """Static function to get test scripts for parametrize."""
+    script_dir = Path(__file__).parent / "test_scripts"
+    scripts = []
+    for script_file in sorted(script_dir.glob("*.py")):
+        content = script_file.read_text()
+        # Find TEST_METADATA line
+        lines = content.split("\n")
+        metadata_lines = []
+        in_metadata = False
+        brace_count = 0
+
+        for line in lines:
+            if line.strip().startswith("# TEST_METADATA: {"):
+                in_metadata = True
+                # Extract JSON part after ': '
+                json_part = line.split("# TEST_METADATA: ", 1)[1]
+                metadata_lines.append(json_part)
+                brace_count = json_part.count("{") - json_part.count("}")
+            elif in_metadata and line.strip().startswith("#"):
+                # Continuation line in comment
+                json_part = line.strip()[1:].strip()  # Remove '#' and trim
+                metadata_lines.append(json_part)
+                brace_count += json_part.count("{") - json_part.count("}")
+
+                # Check if we've closed all braces
+                if brace_count == 0 and "}" in json_part:
+                    in_metadata = False
+            elif in_metadata:
+                # Not a comment line, metadata block ended
+                in_metadata = False
+
+        if metadata_lines:
+            json_str = " ".join(metadata_lines)
+            metadata = json.loads(json_str)
+            scripts.append((script_file.name, metadata))
+    return scripts
+
+
+class TestRunScriptAPI:
+    """Test suite for the /run_script API endpoint."""
+
+    @pytest.fixture
+    def mock_lmcache_adapter_with_config(self):
+        """Create a mock LMCacheConnectorV1Impl adapter with config."""
+        adapter = MagicMock()
+        config = LMCacheEngineConfig.from_defaults()
+        adapter.config = config
+        return adapter
+
+    @pytest.fixture
+    def client_with_adapter(self, mock_lmcache_adapter_with_config):
+        """Create a test client with mocked adapter."""
+        app.state.lmcache_adapter = mock_lmcache_adapter_with_config
+        app.state.lmcache_engine = mock_lmcache_adapter_with_config.lmcache_engine
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    @pytest.fixture
+    def script_dir(self):
+        """Get the test scripts directory."""
+        return Path(__file__).parent / "test_scripts"
+
+    @pytest.mark.parametrize(
+        "script_name,metadata",
+        [
+            pytest.param(name, meta, id=name.replace(".py", ""))
+            for name, meta in _get_test_scripts_static()
+        ],
+    )
+    def test_run_script_from_file(
+        self,
+        client_with_adapter,
+        script_dir,
+        script_name,
+        metadata,
+    ):
+        """Test script execution by directly uploading script files."""
+        script_path = script_dir / script_name
+
+        # Configure allowed imports
+        allowed_imports = metadata.get("allowed_imports", [])
+        client_with_adapter.app.state.lmcache_adapter.config.script_allowed_imports = (
+            allowed_imports
+        )
+
+        # Upload the script file directly
+        with open(script_path, "rb") as f:
+            files = {"script": (script_name, f, "text/plain")}
+            response = client_with_adapter.post("/run_script", files=files)
+
+        # Verify status code
+        expected_status = metadata.get("expected_status", 200)
+        assert response.status_code == expected_status, (
+            f"Expected status {expected_status}, got {response.status_code}"
+        )
+
+        # Verify response content
+        if "expected_result" in metadata:
+            assert response.text == metadata["expected_result"], (
+                f"Expected '{metadata['expected_result']}', got '{response.text}'"
+            )
+
+        if "expected_contains" in metadata:
+            contains_list = metadata["expected_contains"]
+            if isinstance(contains_list, str):
+                contains_list = [contains_list]
+            for expected_text in contains_list:
+                assert expected_text in response.text, (
+                    f"Expected '{expected_text}' in response"
+                )
+
+        if "expected_min_length" in metadata:
+            assert len(response.text) >= metadata["expected_min_length"], (
+                f"Response too short: {len(response.text)}"
+            )
+
+    def test_run_script_no_file(self, client_with_adapter):
+        """Test run_script with no file provided."""
+        response = client_with_adapter.post("/run_script")
+
+        assert response.status_code == 400
+        assert "No script file provided" in response.text
diff --git a/tests/v1/internal_api_server/test_scripts/allowed_imports.py b/tests/v1/internal_api_server/test_scripts/allowed_imports.py
new file mode 100644
index 0000000..75686b5
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/allowed_imports.py
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "{\"key\": \"value\"}",
+#   "allowed_imports": ["json", "sys"]
+# }
+# Standard
+import json
+
+data = {"key": "value"}
+result = json.dumps(data)
diff --git a/tests/v1/internal_api_server/test_scripts/basic.py b/tests/v1/internal_api_server/test_scripts/basic.py
new file mode 100644
index 0000000..d46ac09
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/basic.py
@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {"expected_status": 200, "expected_result": "2", "allowed_imports": []}
+result = 1 + 1
diff --git a/tests/v1/internal_api_server/test_scripts/builtin_functions.py b/tests/v1/internal_api_server/test_scripts/builtin_functions.py
new file mode 100644
index 0000000..7eb02fd
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/builtin_functions.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "42 is the answer",
+#   "allowed_imports": []
+# }
+result = str(42) + " is the answer"
diff --git a/tests/v1/internal_api_server/test_scripts/default_result.py b/tests/v1/internal_api_server/test_scripts/default_result.py
new file mode 100644
index 0000000..ea2f0d1
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/default_result.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "Script executed successfully",
+#   "allowed_imports": []
+# }
+x = 1 + 1
diff --git a/tests/v1/internal_api_server/test_scripts/empty_allowed_imports.py b/tests/v1/internal_api_server/test_scripts/empty_allowed_imports.py
new file mode 100644
index 0000000..ef91481
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/empty_allowed_imports.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "test",
+#   "allowed_imports": []
+# }
+result = "test"
diff --git a/tests/v1/internal_api_server/test_scripts/exception.py b/tests/v1/internal_api_server/test_scripts/exception.py
new file mode 100644
index 0000000..75c5ea7
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/exception.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 500,
+#   "expected_contains": ["Error executing script", "division by zero"],
+#   "allowed_imports": []
+# }
+result = 1 / 0
diff --git a/tests/v1/internal_api_server/test_scripts/invalid_module.py b/tests/v1/internal_api_server/test_scripts/invalid_module.py
new file mode 100644
index 0000000..d69c0ca
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/invalid_module.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "test",
+#   "allowed_imports": ["nonexistent_module"]
+# }
+result = "test"
diff --git a/tests/v1/internal_api_server/test_scripts/math_module.py b/tests/v1/internal_api_server/test_scripts/math_module.py
new file mode 100644
index 0000000..2eb64be
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/math_module.py
@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "4.0",
+#   "allowed_imports": ["math"]
+# }
+# Standard
+import math
+
+result = math.sqrt(16)
diff --git a/tests/v1/internal_api_server/test_scripts/multiple_imports.py b/tests/v1/internal_api_server/test_scripts/multiple_imports.py
new file mode 100644
index 0000000..92a58a6
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/multiple_imports.py
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_result": "{\"sqrt\": 5.0}",
+#   "allowed_imports": ["json", "math", "datetime"]
+# }
+# Standard
+import json
+import math
+
+result = json.dumps({"sqrt": math.sqrt(25)})
diff --git a/tests/v1/internal_api_server/test_scripts/os_module.py b/tests/v1/internal_api_server/test_scripts/os_module.py
new file mode 100644
index 0000000..3c7b57b
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/os_module.py
@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 200,
+#   "expected_min_length": 1,
+#   "allowed_imports": ["os"]
+# }
+# Standard
+import os
+
+result = os.environ.get("PATH", "default_value")
+print(result)
diff --git a/tests/v1/internal_api_server/test_scripts/without_allowed_imports.py b/tests/v1/internal_api_server/test_scripts/without_allowed_imports.py
new file mode 100644
index 0000000..90ba6e6
--- /dev/null
+++ b/tests/v1/internal_api_server/test_scripts/without_allowed_imports.py
@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# TEST_METADATA: {
+#   "expected_status": 500,
+#   "expected_contains": "Error executing script",
+#   "allowed_imports": []
+# }
+# Standard
+import json
+
+result = json.dumps({"test": "value"})
diff --git a/tests/v1/internal_api_server/test_worker_info_api.py b/tests/v1/internal_api_server/test_worker_info_api.py
new file mode 100644
index 0000000..06f790b
--- /dev/null
+++ b/tests/v1/internal_api_server/test_worker_info_api.py
@@ -0,0 +1,307 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import asyncio
+import json
+import threading
+import time
+
+# Third Party
+from fastapi.testclient import TestClient
+import msgspec
+import pytest
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.cache_controller.controller_manager import LMCacheControllerManager
+from lmcache.v1.cache_controller.message import HeartbeatMsg, Msg, RegisterMsg
+from lmcache.v1.internal_api_server.api_server import app
+from lmcache.v1.rpc_utils import get_zmq_context, get_zmq_socket
+
+# Test utilities
+from tests.v1.utils import get_available_port
+
+logger = init_logger(__name__)
+
+
+class TestWorkerInfoAPI:
+    """Test suite for the /controller/workers API endpoint."""
+
+    @pytest.fixture
+    def zmq_context(self):
+        return get_zmq_context(use_asyncio=False)
+
+    @pytest.fixture
+    def controller_urls(self):
+        pull_port = get_available_port()
+        reply_port = get_available_port()
+        heartbeat_port = get_available_port()
+        return {
+            "pull": f"127.0.0.1:{pull_port}",
+            "reply": f"127.0.0.1:{reply_port}",
+            "heartbeat": f"127.0.0.1:{heartbeat_port}",
+        }
+
+    @pytest.fixture
+    def real_controller_manager(self, zmq_context, controller_urls):
+        controller_manager = LMCacheControllerManager(
+            controller_urls=controller_urls,
+            health_check_interval=10,
+            lmcache_worker_timeout=30,
+        )
+
+        self.controller_thread = threading.Thread(
+            target=lambda: asyncio.run(controller_manager.start_all()), daemon=True
+        )
+        self.controller_thread.start()
+        time.sleep(0.5)
+
+        yield controller_manager
+
+        controller_manager.close()
+
+    @pytest.fixture
+    def worker_socket(self, zmq_context, controller_urls):
+        socket = get_zmq_socket(
+            zmq_context,
+            controller_urls["pull"],
+            protocol="tcp",
+            role=zmq.PUSH,
+            bind_or_connect="connect",
+        )
+        yield socket
+        socket.close()
+
+    @pytest.fixture
+    def req_socket(self, zmq_context, controller_urls):
+        """DEALER socket for register operations (DEALER-ROUTER mode)"""
+        socket = get_zmq_socket(
+            zmq_context,
+            controller_urls["reply"],
+            protocol="tcp",
+            role=zmq.DEALER,
+            bind_or_connect="connect",
+        )
+        yield socket
+        socket.close()
+
+    @pytest.fixture
+    def heartbeat_socket(self, zmq_context, controller_urls):
+        """DEALER socket for heartbeat operations"""
+        socket = get_zmq_socket(
+            zmq_context,
+            controller_urls["heartbeat"],
+            protocol="tcp",
+            role=zmq.DEALER,
+            bind_or_connect="connect",
+        )
+        yield socket
+        socket.close()
+
+    @pytest.fixture
+    def client_with_real_controller(self, real_controller_manager):
+        app.state.lmcache_controller_manager = real_controller_manager
+        with TestClient(app) as client:
+            yield client
+
+    @pytest.fixture
+    def client_without_controller(self):
+        app.state.lmcache_controller_manager = None
+        client = TestClient(app)
+        yield client
+        client.close()
+
+    def _send_message(self, socket, msg_type, instance_id, worker_id, ip, port):
+        """Send message to controller via ZMQ
+
+        For register: uses DEALER socket (DEALER-ROUTER mode), returns response
+        For heartbeat: uses DEALER socket (dedicated heartbeat socket)
+        For others: uses PUSH socket (fire-and-forget)
+        """
+        msg_classes = {
+            "register": RegisterMsg,
+            "heartbeat": HeartbeatMsg,
+        }
+
+        if msg_type not in msg_classes:
+            raise ValueError(f"Unsupported message type: {msg_type}")
+
+        msg_cls = msg_classes[msg_type]
+        msg = msg_cls(
+            instance_id=instance_id,
+            worker_id=worker_id,
+            ip=ip,
+            port=port,
+            peer_init_url=None,
+        )
+
+        message_data = msgspec.msgpack.encode(msg)
+
+        # DEALER-ROUTER mode for register and heartbeat
+        if msg_type in ("register", "heartbeat"):
+            # DEALER socket: send [empty_frame, payload]
+            socket.send_multipart([b"", message_data])
+            # DEALER receives: [empty_frame, payload]
+            frames = socket.recv_multipart()
+            response = frames[-1]
+            return msgspec.msgpack.decode(response, type=Msg)
+        else:
+            socket.send(message_data)
+            return None
+
+    def _wait_for_workers(self, client, expected_count, timeout=5):
+        """Wait for expected number of workers to be registered"""
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            response = client.get("/controller/workers")
+            if response.status_code == 200:
+                data = json.loads(response.text)
+                if data.get("total_count") == expected_count:
+                    return
+            time.sleep(0.1)
+        pytest.fail(f"Timed out waiting for {expected_count} workers.")
+
+    def _wait_for_specific_worker(self, client, instance_id, worker_id, timeout=5):
+        """Wait for specific worker to be available"""
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            response = client.get(
+                f"/controller/workers?instance_id={instance_id}&worker_id={worker_id}"
+            )
+            if response.status_code == 200:
+                return
+            time.sleep(0.1)
+        pytest.fail(f"Timed out waiting for worker ({instance_id}, {worker_id}).")
+
+    def _assert_worker_fields(self, worker_data):
+        required_fields = {
+            "instance_id",
+            "worker_id",
+            "ip",
+            "port",
+            "peer_init_url",
+            "registration_time",
+            "last_heartbeat_time",
+        }
+        for field in required_fields:
+            assert field in worker_data, f"Missing field: {field}"
+
+    def _assert_worker_list_response(self, response, expected_count):
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        assert "workers" in data
+        assert "total_count" in data
+        assert data["total_count"] == expected_count
+        return data
+
+    def _assert_single_worker_response(self, response, instance_id, worker_id):
+        assert response.status_code == 200
+        data = json.loads(response.text)
+        self._assert_worker_fields(data)
+        assert data["instance_id"] == instance_id
+        assert data["worker_id"] == worker_id
+        return data
+
+    def test_real_worker_registration_and_query(
+        self, client_with_real_controller, req_socket, heartbeat_socket
+    ):
+        # Register workers via DEALER-ROUTER communication
+        self._send_message(req_socket, "register", "instance1", 0, "127.0.0.1", 8000)
+        self._send_message(req_socket, "register", "instance1", 1, "127.0.0.1", 8001)
+        self._send_message(req_socket, "register", "instance2", 0, "127.0.0.2", 8002)
+
+        # Wait for workers to be registered
+        self._wait_for_workers(client_with_real_controller, 3)
+
+        # Send heartbeats to update last_heartbeat_time
+        self._send_message(
+            heartbeat_socket, "heartbeat", "instance1", 0, "127.0.0.1", 8000
+        )
+        self._send_message(
+            heartbeat_socket, "heartbeat", "instance1", 1, "127.0.0.1", 8001
+        )
+        self._send_message(
+            heartbeat_socket, "heartbeat", "instance2", 0, "127.0.0.2", 8002
+        )
+
+        # Test getting all workers
+        response = client_with_real_controller.get("/controller/workers")
+        data = self._assert_worker_list_response(response, 3)
+
+        workers = data["workers"]
+        assert len(workers) == 3
+
+        worker_keys = {(w["instance_id"], w["worker_id"]) for w in workers}
+        assert worker_keys == {("instance1", 0), ("instance1", 1), ("instance2", 0)}
+
+        for worker in workers:
+            self._assert_worker_fields(worker)
+            assert worker["registration_time"] == pytest.approx(time.time(), abs=2)
+            assert worker["last_heartbeat_time"] == pytest.approx(time.time(), abs=2)
+
+    def test_real_workers_by_instance(self, client_with_real_controller, req_socket):
+        self._send_message(req_socket, "register", "instance1", 0, "127.0.0.1", 8000)
+        self._send_message(req_socket, "register", "instance2", 0, "127.0.0.2", 8002)
+
+        # Wait for workers to be registered
+        self._wait_for_workers(client_with_real_controller, 2)
+
+        response = client_with_real_controller.get(
+            "/controller/workers?instance_id=instance1"
+        )
+        data = self._assert_worker_list_response(response, 1)
+
+        workers = data["workers"]
+        assert len(workers) == 1
+        assert workers[0]["instance_id"] == "instance1"
+        assert workers[0]["worker_id"] == 0
+
+    def test_real_specific_worker_query(
+        self, client_with_real_controller, req_socket, heartbeat_socket
+    ):
+        self._send_message(req_socket, "register", "instance1", 0, "127.0.0.1", 8000)
+        self._send_message(
+            heartbeat_socket, "heartbeat", "instance1", 0, "127.0.0.1", 8000
+        )
+
+        # Wait for worker to be available
+        self._wait_for_specific_worker(client_with_real_controller, "instance1", 0)
+
+        response = client_with_real_controller.get(
+            "/controller/workers?instance_id=instance1&worker_id=0"
+        )
+        data = self._assert_single_worker_response(response, "instance1", 0)
+
+        assert data["ip"] == "127.0.0.1"
+        assert data["port"] == 8000
+        assert data["peer_init_url"] is None
+        assert data["last_heartbeat_time"] == pytest.approx(time.time(), abs=2)
+
+    def test_real_nonexistent_worker(self, client_with_real_controller):
+        response = client_with_real_controller.get(
+            "/controller/workers?instance_id=nonexistent&worker_id=999"
+        )
+        assert response.status_code == 404
+        data = json.loads(response.text)
+        assert "detail" in data
+        assert (
+            "not found" in data["detail"]
+            and "nonexistent" in data["detail"]
+            and "999" in data["detail"]
+        )
+
+    def test_real_nonexistent_instance(self, client_with_real_controller):
+        response = client_with_real_controller.get(
+            "/controller/workers?instance_id=nonexistent"
+        )
+        assert response.status_code == 404
+        data = json.loads(response.text)
+        assert "detail" in data
+        assert "No workers found for instance nonexistent" in data["detail"]
+
+    def test_real_controller_manager_not_available(self, client_without_controller):
+        response = client_without_controller.get("/controller/workers")
+        assert response.status_code == 503
+        data = json.loads(response.text)
+        assert "detail" in data
+        assert "Controller manager not available" in data["detail"]
diff --git a/tests/v1/lookup_client/__init__.py b/tests/v1/lookup_client/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/v1/lookup_client/test_chunk_statistics_lookup_client.py b/tests/v1/lookup_client/test_chunk_statistics_lookup_client.py
new file mode 100644
index 0000000..32ce507
--- /dev/null
+++ b/tests/v1/lookup_client/test_chunk_statistics_lookup_client.py
@@ -0,0 +1,357 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Optional, Union
+import shutil
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.chunk_statistics_lookup_client import (
+    ChunkStatisticsLookupClient,
+)
+from lmcache.v1.lookup_client.record_strategies import _get_strategies
+from lmcache.v1.utils.bloom_filter import BloomFilter
+
+
+class BaseMockClient(LookupClientInterface):
+    def __init__(self, chunk_size: int = 256):
+        self.chunk_size = chunk_size
+
+    def clear_lookup_status(self, lookup_id: str) -> None:
+        pass
+
+    def supports_producer_reuse(self) -> bool:
+        return True
+
+    def close(self) -> None:
+        pass
+
+
+class MockLookupClient(BaseMockClient):
+    def __init__(self):
+        super().__init__()
+        self.lookup_calls = []
+
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        self.lookup_calls.append((token_ids, lookup_id, request_configs))
+        return len(token_ids) // 2
+
+
+class FastMissLookupClient(BaseMockClient):
+    def lookup(
+        self,
+        token_ids: Union[torch.Tensor, list[int]],
+        lookup_id: str,
+        request_configs: Optional[dict] = None,
+    ) -> Optional[int]:
+        time.sleep(0.008)
+        return 0
+
+
+class BaseTestCase:
+    def create_stats_client(self, **kwargs):
+        return ChunkStatisticsLookupClient(
+            MockLookupClient(), LMCacheEngineConfig(**kwargs)
+        )
+
+    def setup_stats_client(self, **kwargs):
+        default_kwargs = {
+            "enable_chunk_statistics": True,
+            "chunk_statistics_strategy": "memory_bloom_filter",
+            "extra_config": {
+                "chunk_statistics_mem_bf_expected_chunks": 1000,
+                "chunk_statistics_mem_bf_false_positive_rate": 0.01,
+            },
+        }
+        if "extra_config" in kwargs:
+            default_kwargs["extra_config"].update(kwargs.pop("extra_config"))
+        default_kwargs.update(kwargs)
+        stats_client = self.create_stats_client(**default_kwargs)
+        stats_client.start_statistics()
+        return stats_client, stats_client.actual_lookup_client
+
+
+class TestStrategyDiscovery:
+    def test_get_strategies_discovers_all_strategies(self):
+        strategies = _get_strategies()
+        assert isinstance(strategies, dict) and len(strategies) >= 2
+        assert "file_hash" in strategies and "memory_bloom_filter" in strategies
+        assert strategies["file_hash"].__module__.split(".")[-1] == "file_hash"
+        assert (
+            strategies["memory_bloom_filter"].__module__.split(".")[-1]
+            == "memory_bloom_filter"
+        )
+
+
+class TestBloomFilter:
+    def test_bloom_filter_operations(self):
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        bf.add("test_item_1")
+        bf.add("test_item_2")
+        assert bf.contains("test_item_1") and bf.contains("test_item_2")
+        assert not bf.contains("test_item_3")
+        bf.clear()
+        assert not bf.contains("test_item_1")
+
+    def test_false_positive_rate(self):
+        bf = BloomFilter(expected_elements=10000, false_positive_rate=0.01)
+        for i in range(10000):
+            bf.add(f"item_{i}")
+        fp_rate = sum(1 for i in range(10000, 11000) if bf.contains(f"item_{i}")) / 1000
+        assert fp_rate < 0.05
+
+    def test_memory_metrics(self):
+        bf = BloomFilter(expected_elements=10000, false_positive_rate=0.01)
+        stats = bf.get_statistics()
+        for metric in ["size_mb", "hash_count", "item_count", "bits_set", "fill_rate"]:
+            assert metric in stats
+        assert stats["size_mb"] > 0
+
+
+class TestChunkStatisticsBasic(BaseTestCase):
+    def test_preemption_handling(self):
+        stats_client, _ = self.setup_stats_client()
+        token_ids = list(range(256))
+        stats_client.lookup(token_ids, "req_1")
+        stats1 = stats_client.get_statistics()
+        stats_client.lookup(token_ids, "req_1")
+        stats2 = stats_client.get_statistics()
+        assert stats1["total_requests"] == stats2["total_requests"]
+        assert stats1["total_chunks"] == stats2["total_chunks"]
+
+    def test_disabled_statistics(self):
+        stats_client = self.create_stats_client()
+        stats_client.lookup(list(range(256)), "req_1")
+        stats = stats_client.get_statistics()
+        assert stats["enabled"] is False and stats["total_requests"] == 0
+
+
+class TestChunkStatisticsMetrics(BaseTestCase):
+    def test_detailed_metrics(self):
+        stats_client, _ = self.setup_stats_client(
+            extra_config={
+                "chunk_statistics_mem_bf_expected_chunks": 5000,
+                "chunk_statistics_mem_bf_false_positive_rate": 0.01,
+            }
+        )
+        stats_client.lookup(list(range(512)), "req_1")
+        stats_client.lookup(list(range(256)), "req_2")
+        stats = stats_client.get_statistics()
+        for stat in [
+            "enabled",
+            "total_requests",
+            "total_chunks",
+            "unique_chunks",
+            "duplicate_chunks",
+            "reuse_rate",
+            "bloom_filter",
+            "timing",
+        ]:
+            assert stat in stats
+        bf_stats = stats["bloom_filter"]
+        for stat in [
+            "size_mb",
+            "hash_count",
+            "item_count",
+            "bits_set",
+            "fill_rate",
+            "expected_elements",
+            "false_positive_rate",
+        ]:
+            assert stat in bf_stats
+        assert stats["total_requests"] == 2 and stats["total_chunks"] == 3
+        assert 0.0 <= stats["reuse_rate"] <= 1.0
+        assert (
+            bf_stats["expected_elements"] == 5000
+            and bf_stats["false_positive_rate"] == 0.01
+        )
+        timing = stats["timing"]
+        for field in [
+            "lookup_time_seconds",
+            "record_statistics_time_seconds",
+            "check_exit_conditions_time_seconds",
+            "total_time_seconds",
+            "overhead_time_seconds",
+            "overhead_percentage",
+        ]:
+            assert field in timing and timing[field] >= 0
+        assert 0 <= timing["overhead_percentage"] <= 100
+
+    def test_progressive_metrics(self):
+        stats_client, _ = self.setup_stats_client()
+        stats_client.lookup(list(range(256)), "req_1")
+        assert stats_client.get_statistics()["total_requests"] == 1
+        stats_client.lookup(list(range(256, 512)), "req_2")
+        assert stats_client.get_statistics()["total_requests"] == 2
+        stats_client.lookup(torch.arange(256), "req_3")
+        stats3 = stats_client.get_statistics()
+        assert stats3["total_requests"] == 3 and stats3["duplicate_chunks"] > 0
+
+    def test_memory_efficiency(self):
+        stats_client, _ = self.setup_stats_client(
+            extra_config={
+                "chunk_statistics_mem_bf_expected_chunks": 100000,
+                "chunk_statistics_mem_bf_false_positive_rate": 0.01,
+            }
+        )
+        for i in range(100):
+            stats_client.lookup(list(range(i * 256, (i + 1) * 256)), f"req_{i}")
+        stats = stats_client.get_statistics()
+        assert stats["bloom_filter"]["size_mb"] < 1.0
+        assert stats["total_requests"] == 100 and stats["total_chunks"] == 100
+
+
+class TestChunkStatisticsLifecycle(BaseTestCase):
+    def test_reset_statistics(self):
+        stats_client, _ = self.setup_stats_client()
+        stats_client.lookup(list(range(256)), "req_1")
+        stats_client.reset_statistics()
+        stats = stats_client.get_statistics()
+        assert (
+            stats["total_requests"] == 0
+            and stats["total_chunks"] == 0
+            and stats["unique_chunks"] == 0
+        )
+
+    def test_auto_exit_configuration(self):
+        stats_client = self.create_stats_client(
+            enable_chunk_statistics=True,
+            chunk_statistics_auto_start_statistics=True,
+            chunk_statistics_auto_exit_timeout_hours=1.0,
+        )
+        stats = stats_client.get_statistics()
+        assert stats["enabled"] is True and stats["total_requests"] == 0
+        assert (
+            stats_client.enable_auto_exit is True and stats_client.timeout_hours == 1.0
+        )
+        stats_client2 = self.create_stats_client(
+            enable_chunk_statistics=True, chunk_statistics_auto_exit_timeout_hours=0.0
+        )
+        assert stats_client2.enable_auto_exit is False
+
+
+class TestChunkStatisticsPerformance:
+    """Test suite for chunk statistics performance validation."""
+
+    @pytest.mark.parametrize(
+        "strategy_name,async_preprocess_chunks",
+        [
+            ("memory_bloom_filter", True),
+            ("memory_bloom_filter", False),
+            ("file_hash", True),
+            ("file_hash", False),
+        ],
+    )
+    def test_worst_case_overhead(self, strategy_name, async_preprocess_chunks):
+        """Test worst case performance with different strategies and configs."""
+        self._run_performance_test(
+            strategy_name=strategy_name,
+            async_preprocess_chunks=async_preprocess_chunks,
+        )
+
+    def _run_performance_test(self, strategy_name: str, async_preprocess_chunks: bool):
+        if async_preprocess_chunks:
+            mode_desc = f"{strategy_name} (Async Preprocessed)"
+        else:
+            mode_desc = f"{strategy_name} (Async Raw Tokens)"
+        temp_dir: Optional[str] = (
+            tempfile.mkdtemp(prefix="lmcache_test_")
+            if strategy_name == "file_hash"
+            else None
+        )
+        try:
+            extra_config: dict[str, Any] = {
+                "chunk_statistics_mem_bf_expected_chunks": 100000,
+                "chunk_statistics_mem_bf_false_positive_rate": 0.01,
+                "chunk_statistics_async_preprocess_chunks": async_preprocess_chunks,
+            }
+            if temp_dir:
+                extra_config["chunk_statistics_file_output_dir"] = temp_dir
+            config_kwargs = {
+                "chunk_size": 256,
+                "chunk_statistics_strategy": strategy_name,
+                "extra_config": extra_config,
+            }
+            config = LMCacheEngineConfig(**config_kwargs)
+            stats_client = ChunkStatisticsLookupClient(FastMissLookupClient(), config)
+            stats_client.start_statistics()
+            token_count, num_requests = 32 * 1024, 30
+            token_ids = list(range(token_count))
+            stats_client.lookup(token_ids, "warmup")
+            stats_client.reset_statistics()
+            stats_client.start_statistics()
+            for i in range(num_requests):
+                stats_client.lookup(token_ids, f"req_{i}")
+            assert stats_client.wait_for_async_processing(timeout=10.0), "Async timeout"
+            stats = stats_client.get_statistics()
+            timing = stats["timing"]
+
+            overhead_percentage = timing["overhead_percentage"]
+            print(f"Overhead percentage({mode_desc}): {overhead_percentage:.2f}%")
+            assert stats["total_requests"] == num_requests
+            assert stats["total_chunks"] == num_requests * (token_count // 256)
+            assert timing["overhead_percentage"] <= 40.0, (
+                f"Overhead {timing['overhead_percentage']:.2f}% > 40%"
+            )
+            assert timing["record_statistics_time_seconds"] / num_requests < 0.01, (
+                "Avg record time > 10ms"
+            )
+            async_queue = stats.get("async_queue", {})
+            if async_queue:
+                assert async_queue.get("capacity") == config.get_extra_config_value(
+                    "chunk_statistics_async_queue_capacity", 100000
+                )
+                assert async_queue.get("full_blocks", 0) == 0
+        finally:
+            if temp_dir:
+                try:
+                    shutil.rmtree(temp_dir)
+                except Exception:
+                    pass
+
+
+class TestFileHashStrategy:
+    def test_file_hash_basic(self):
+        # Standard
+        from pathlib import Path
+        import json
+
+        temp_dir = tempfile.mkdtemp()
+        try:
+            config = LMCacheEngineConfig.from_dict(
+                {
+                    "chunk_statistics_enabled": True,
+                    "chunk_statistics_strategy": "file_hash",
+                    "extra_config": {
+                        "chunk_statistics_file_output_dir": temp_dir,
+                    },
+                }
+            )
+            client = ChunkStatisticsLookupClient(MockLookupClient(), config)
+            client.start_statistics()
+            client.lookup(list(range(512)), "test_request_1")
+            client.wait_for_async_processing(timeout=2.0)
+            output_files = list(Path(temp_dir).glob("*.jsonl"))
+            assert len(output_files) > 0
+            with open(output_files[0], "r") as f:
+                data = json.loads(f.readline())
+                assert (
+                    "chunk_hashes" in data
+                    and "lookup_id" in data
+                    and "timestamp" in data
+                )
+                assert len(data["chunk_hashes"]) == 2
+            client.close()
+        finally:
+            shutil.rmtree(temp_dir)
diff --git a/tests/v1/lookup_client/test_lmcache_lookup_client.py b/tests/v1/lookup_client/test_lmcache_lookup_client.py
new file mode 100644
index 0000000..9de5226
--- /dev/null
+++ b/tests/v1/lookup_client/test_lmcache_lookup_client.py
@@ -0,0 +1,457 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for LMCacheLookupClient and LMCacheLookupServer communication.
+
+IMPORTANT: These tests require PYTHONHASHSEED to be set for consistent hashing.
+In production, LMCacheLookupClient and LMCacheLookupServer run in separate
+processes (scheduler vs worker), and PYTHONHASHSEED must be set consistently
+across all processes to ensure hash consistency for cache lookups.
+
+Run with: PYTHONHASHSEED=0 pytest tests/v1/lookup_client/test_lmcache_lookup_client.py
+"""
+
+# Standard
+import os
+import random
+import tempfile
+import time
+import uuid
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.gpu_connector.mock_gpu_connector import MockGPUConnector
+from lmcache.v1.lookup_client.factory import LookupClientFactory
+from lmcache.v1.lookup_client.lmcache_lookup_client import (
+    LMCacheLookupClient,
+    LMCacheLookupServer,
+)
+from tests.v1.utils import (
+    create_test_config,
+    create_test_metadata,
+    generate_kv_cache_paged_list_tensors,
+    generate_tokens,
+    recover_engine_states,
+)
+
+# Skip all tests in this module if PYTHONHASHSEED is not set.
+# This reflects production requirements where consistent hashing across
+# processes (scheduler/worker) requires PYTHONHASHSEED to be set.
+pytestmark = pytest.mark.skipif(
+    os.environ.get("PYTHONHASHSEED") is None,
+    reason=(
+        "PYTHONHASHSEED must be set for consistent hashing between "
+        "LMCacheLookupClient and LMCacheLookupServer. "
+        "Run with: PYTHONHASHSEED=0 pytest ..."
+    ),
+)
+
+
+class TestLMCacheLookupClientServer:
+    """Test suite for LMCacheLookupClient and LMCacheLookupServer communication."""
+
+    @pytest.fixture
+    def temp_dir(self):
+        """Create a temporary directory for testing."""
+        temp_dir = tempfile.mkdtemp()
+        yield temp_dir
+
+    @pytest.fixture
+    def lmcache_engine_metadata(self):
+        """Create test metadata for LMCacheEngine."""
+        return create_test_metadata()
+
+    @pytest.fixture
+    def lmcache_engine(self, temp_dir, lmcache_engine_metadata):
+        """Create a LMCacheEngine instance for testing."""
+        instance_id = f"test_lookup_instance_{uuid.uuid4().hex[:8]}"
+        config = create_test_config(instance_id=instance_id)
+
+        # Use mock connector for CPU testing
+        connector = MockGPUConnector(kv_shape=(32, 2, 256, 8, 128))
+
+        engine = LMCacheEngineBuilder.get_or_create(
+            instance_id=instance_id,
+            config=config,
+            metadata=lmcache_engine_metadata,
+            gpu_connector=connector,
+            broadcast_fn=mock_up_broadcast_fn,
+            broadcast_object_fn=mock_up_broadcast_object_fn,
+        )
+        engine.post_init()
+
+        yield engine
+
+        # Cleanup
+        engine.close()
+        # Remove from singleton cache to avoid test pollution
+        LMCacheEngineBuilder._instances.pop(instance_id, None)
+        LMCacheEngineBuilder._cfgs.pop(instance_id, None)
+        LMCacheEngineBuilder._metadatas.pop(instance_id, None)
+        LMCacheEngineBuilder._stat_loggers.pop(instance_id, None)
+
+    def _create_server(self, lmcache_engine):
+        """Helper to create a lookup server with transport."""
+        transport = LookupClientFactory._create_zmq_server_transport(
+            lmcache_engine.metadata
+        )
+        return LMCacheLookupServer(lmcache_engine, lmcache_engine.metadata, transport)
+
+    def _create_client(self, lmcache_engine):
+        """Helper to create a lookup client with transport."""
+        transport = LookupClientFactory._create_zmq_client_transport(
+            lmcache_engine.config, lmcache_engine.metadata
+        )
+        return LMCacheLookupClient(
+            lmcache_engine.config,
+            lmcache_engine.metadata,
+            transport,
+        )
+
+    def test_basic_lookup_communication(self, lmcache_engine):
+        """Test basic lookup communication between client and server."""
+        device = "cpu"
+        num_tokens = 512
+        num_blocks = 100
+        block_size = 16
+
+        # Prepare test data
+        tokens = generate_tokens(num_tokens, device, fixed=True)
+        kv_cache = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+        slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping = torch.tensor(slot_mapping, device=device)
+
+        # Store data into cache
+        lmcache_engine.store(
+            tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping
+        )
+        recover_engine_states(lmcache_engine)
+        time.sleep(0.5)
+
+        with self._create_server(lmcache_engine):
+            time.sleep(0.5)
+            with self._create_client(lmcache_engine) as client:
+                lookup_id = "test_request_1"
+                result = client.lookup(tokens.tolist(), lookup_id)
+
+                # Verify exact match
+                assert result == num_tokens, f"Expected {num_tokens}, got {result}"
+
+                # Verify lookup status is cached
+                cached_result = client.lookup_cache(lookup_id)
+                assert cached_result == num_tokens
+
+                # Test clear lookup status
+                client.clear_lookup_status(lookup_id)
+                assert client.lookup_cache(lookup_id) == -1
+
+                # Test supports_producer_reuse
+                assert client.supports_producer_reuse() is True
+
+    def test_multiple_lookups(self, lmcache_engine):
+        """Test multiple lookup requests."""
+        device = "cpu"
+        num_blocks = 200
+        block_size = 16
+
+        # Store multiple token sequences
+        stored_tokens = []
+        for i in range(5):
+            num_tokens = 256
+            tokens = generate_tokens(num_tokens, device, fixed=True)
+            # Make each sequence unique by adding offset
+            tokens = tokens + i * 10000
+            kv_cache = generate_kv_cache_paged_list_tensors(
+                num_blocks, device, block_size
+            )
+            slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+            slot_mapping = torch.tensor(slot_mapping, device=device)
+
+            lmcache_engine.store(
+                tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping
+            )
+            recover_engine_states(lmcache_engine)
+            stored_tokens.append(tokens)
+
+        time.sleep(0.5)
+
+        with self._create_server(lmcache_engine):
+            time.sleep(0.5)
+            with self._create_client(lmcache_engine) as client:
+                # Perform multiple lookups
+                for i, tokens in enumerate(stored_tokens):
+                    lookup_id = f"test_request_{i}"
+                    result = client.lookup(tokens.tolist(), lookup_id)
+                    assert result == 256, f"Expected 256, got {result}"
+                    assert client.lookup_cache(lookup_id) == 256
+
+    def test_lookup_with_request_configs(self, lmcache_engine):
+        """Test lookup with request configurations and tag-based cache isolation."""
+        device = "cpu"
+        num_tokens = 256
+        num_blocks = 100
+        block_size = 16
+
+        # Prepare test data for user_a
+        tokens_user_a = generate_tokens(num_tokens, device, fixed=True)
+        kv_cache = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+        slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping = torch.tensor(slot_mapping, device=device)
+
+        # Store data with tag: user=user_a
+        request_configs_user_a = {
+            "temperature": 0.8,
+            "top_p": 0.9,
+            "lmcache.tag.user": "user_a",
+        }
+        lmcache_engine.store(
+            tokens=tokens_user_a,
+            kvcaches=kv_cache,
+            slot_mapping=slot_mapping,
+            request_configs=request_configs_user_a,
+        )
+        recover_engine_states(lmcache_engine)
+        time.sleep(0.5)
+
+        with self._create_server(lmcache_engine):
+            time.sleep(0.5)
+            with self._create_client(lmcache_engine) as client:
+                # Test 1: Lookup with same tag (user_a) should hit cache
+                lookup_id_1 = "test_user_a_match"
+                result_1 = client.lookup(
+                    tokens_user_a.tolist(), lookup_id_1, request_configs_user_a
+                )
+                assert result_1 == num_tokens, (
+                    f"Expected cache hit with {num_tokens} tokens "
+                    f"for user_a, got {result_1}"
+                )
+
+                # Test 2: Lookup with different tag (user_b) should NOT hit cache
+                request_configs_user_b = {
+                    "temperature": 0.8,
+                    "top_p": 0.9,
+                    "lmcache.tag.user": "user_b",
+                }
+                lookup_id_2 = "test_user_b_no_match"
+                result_2 = client.lookup(
+                    tokens_user_a.tolist(), lookup_id_2, request_configs_user_b
+                )
+                assert result_2 == 0, (
+                    f"Expected cache miss (0) for user_b, got {result_2}"
+                )
+
+                # Test 3: Lookup without tag should NOT hit cache
+                request_configs_no_tag = {"temperature": 0.8, "top_p": 0.9}
+                lookup_id_3 = "test_no_tag_no_match"
+                result_3 = client.lookup(
+                    tokens_user_a.tolist(), lookup_id_3, request_configs_no_tag
+                )
+                assert result_3 == 0, (
+                    f"Expected cache miss (0) without tag, got {result_3}"
+                )
+
+                # Test 4: Lookup with same tag again should still hit cache
+                lookup_id_4 = "test_user_a_match_again"
+                result_4 = client.lookup(
+                    tokens_user_a.tolist(), lookup_id_4, request_configs_user_a
+                )
+                assert result_4 == num_tokens, (
+                    f"Expected cache hit with {num_tokens} tokens "
+                    f"for user_a again, got {result_4}"
+                )
+
+                # Test 5: Multiple tags - store with user=user_a and env=prod
+                request_configs_multi_tags = {
+                    "lmcache.tag.user": "user_a",
+                    "lmcache.tag.env": "prod",
+                }
+                tokens_multi = generate_tokens(num_tokens, device, fixed=True) + 50000
+                kv_cache_multi = generate_kv_cache_paged_list_tensors(
+                    num_blocks, device, block_size
+                )
+                slot_mapping_multi = random.sample(
+                    range(0, num_blocks * block_size), num_tokens
+                )
+                slot_mapping_multi = torch.tensor(slot_mapping_multi, device=device)
+
+                lmcache_engine.store(
+                    tokens=tokens_multi,
+                    kvcaches=kv_cache_multi,
+                    slot_mapping=slot_mapping_multi,
+                    request_configs=request_configs_multi_tags,
+                )
+                recover_engine_states(lmcache_engine)
+                time.sleep(0.5)
+
+                # Should hit with exact same tags
+                lookup_id_5 = "test_multi_tags_match"
+                result_5 = client.lookup(
+                    tokens_multi.tolist(), lookup_id_5, request_configs_multi_tags
+                )
+                assert result_5 == num_tokens, (
+                    f"Expected cache hit with {num_tokens} tokens "
+                    f"for multi tags, got {result_5}"
+                )
+
+                # Should NOT hit with partial tags
+                request_configs_partial = {"lmcache.tag.user": "user_a"}
+                lookup_id_6 = "test_partial_tags_no_match"
+                result_6 = client.lookup(
+                    tokens_multi.tolist(), lookup_id_6, request_configs_partial
+                )
+                assert result_6 == 0, (
+                    f"Expected cache miss (0) with partial tags, got {result_6}"
+                )
+
+                # Should NOT hit with different env tag
+                request_configs_diff_env = {
+                    "lmcache.tag.user": "user_a",
+                    "lmcache.tag.env": "dev",
+                }
+                lookup_id_7 = "test_diff_env_no_match"
+                result_7 = client.lookup(
+                    tokens_multi.tolist(), lookup_id_7, request_configs_diff_env
+                )
+                assert result_7 == 0, (
+                    f"Expected cache miss (0) with different env tag, got {result_7}"
+                )
+
+    def test_client_timeout_handling(self, lmcache_engine):
+        """Test client timeout handling when server is not responding."""
+        server = self._create_server(lmcache_engine)
+        time.sleep(0.5)
+
+        with self._create_client(lmcache_engine) as client:
+            # Close server to simulate timeout
+            server.close()
+            time.sleep(0.5)
+
+            # Try lookup - should handle timeout gracefully
+            token_ids = list(range(256))
+            lookup_id = "test_timeout"
+
+            result = client.lookup(token_ids, lookup_id)
+
+            # Should return 0 on timeout
+            assert result == 0
+
+    def test_socket_recreation_on_error(self, lmcache_engine):
+        """Test socket recreation when ZMQ error occurs."""
+        device = "cpu"
+        num_tokens = 256
+        num_blocks = 100
+        block_size = 16
+
+        # Store some data first
+        tokens = generate_tokens(num_tokens, device, fixed=True)
+        kv_cache = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+        slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping = torch.tensor(slot_mapping, device=device)
+
+        lmcache_engine.store(
+            tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping
+        )
+        recover_engine_states(lmcache_engine)
+        time.sleep(0.5)
+
+        with self._create_server(lmcache_engine) as server:
+            time.sleep(0.5)
+
+            with self._create_client(lmcache_engine) as client:
+                # First lookup - should hit cache
+                token_ids = tokens.tolist()
+                result1 = client.lookup(token_ids, "test_1")
+                assert result1 == num_tokens
+
+                # Simulate error by closing server
+                server.close()
+                time.sleep(0.5)
+
+                # This should trigger socket recreation and return 0 on error
+                result2 = client.lookup(token_ids, "test_2")
+                assert result2 == 0
+
+                # Recreate server
+                with self._create_server(lmcache_engine):
+                    time.sleep(0.5)
+
+                    # Should work again after socket recreation and hit cache
+                    result3 = client.lookup(token_ids, "test_3")
+                    assert result3 == num_tokens
+
+    def test_close_methods(self, lmcache_engine):
+        """Test proper cleanup of client and server close methods."""
+        with self._create_server(lmcache_engine) as server:
+            time.sleep(0.5)
+
+            with self._create_client(lmcache_engine) as client:
+                # Perform a lookup
+                token_ids = list(range(256))
+                result = client.lookup(token_ids, "test_close")
+                assert result is not None
+
+            # After exiting context, transport is closed
+
+        # After exiting context, verify server thread is stopped
+        assert server.running is False
+        assert not server.thread.is_alive()
+
+    def test_concurrent_lookups(self, lmcache_engine):
+        """Test concurrent lookup requests from same client."""
+        with self._create_server(lmcache_engine):
+            time.sleep(0.5)
+            with self._create_client(lmcache_engine) as client:
+                # Perform rapid consecutive lookups
+                results = []
+                for i in range(10):
+                    token_ids = list(range(256))
+                    lookup_id = f"concurrent_test_{i}"
+                    result = client.lookup(token_ids, lookup_id)
+                    results.append(result)
+
+                # All lookups should succeed
+                assert len(results) == 10
+                assert all(isinstance(r, int) for r in results)
+
+    def test_empty_token_lookup(self, lmcache_engine):
+        """Test lookup with empty token list."""
+        with self._create_server(lmcache_engine):
+            time.sleep(0.5)
+            with self._create_client(lmcache_engine) as client:
+                # Empty token list
+                token_ids = []
+                lookup_id = "test_empty"
+
+                result = client.lookup(token_ids, lookup_id)
+                assert result is not None
+                assert result == 0  # No tokens to lookup
+
+    def test_large_token_lookup(self, lmcache_engine):
+        """Test lookup with large number of tokens."""
+        device = "cpu"
+        num_tokens = 2048
+        num_blocks = 500
+        block_size = 16
+
+        # Store large token sequence
+        tokens = generate_tokens(num_tokens, device, fixed=True)
+        kv_cache = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+        slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping = torch.tensor(slot_mapping, device=device)
+
+        lmcache_engine.store(
+            tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping
+        )
+        recover_engine_states(lmcache_engine)
+        time.sleep(0.5)
+
+        with self._create_server(lmcache_engine):
+            time.sleep(0.5)
+            with self._create_client(lmcache_engine) as client:
+                lookup_id = "test_large"
+                result = client.lookup(tokens.tolist(), lookup_id)
+                assert result == num_tokens, f"Expected {num_tokens}, got {result}"
diff --git a/tests/v1/mp_coordinator/__init__.py b/tests/v1/mp_coordinator/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/mp_coordinator/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/mp_coordinator/test_api.py b/tests/v1/mp_coordinator/test_api.py
new file mode 100644
index 0000000..1ee83f8
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_api.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator REST API via FastAPI TestClient."""
+
+# Third Party
+from fastapi.testclient import TestClient
+
+# First Party
+from lmcache.v1.mp_coordinator.app import create_app
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+
+
+def _client() -> TestClient:
+    # health_check_interval=0 disables the background loop for deterministic tests.
+    config = MPCoordinatorConfig(health_check_interval=0.0)
+    return TestClient(create_app(config))
+
+
+def test_register_lists_then_deregister():
+    with _client() as client:
+        resp = client.post(
+            "/instances",
+            json={"instance_id": "i1", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        assert resp.status_code == 200
+        assert resp.json() == {"instance_id": "i1", "re_registered": False}
+
+        listed = client.get("/instances").json()["instances"]
+        assert [i["instance_id"] for i in listed] == ["i1"]
+
+        assert client.delete("/instances/i1").status_code == 204
+        assert client.get("/instances").json()["instances"] == []
+
+
+def test_register_round_trips_p2p_and_mq_fields():
+    with _client() as client:
+        client.post(
+            "/instances",
+            json={
+                "instance_id": "i1",
+                "ip": "10.0.0.1",
+                "http_port": 8080,
+                "p2p_advertised_url": "10.0.0.1:7600",
+                "mq_port": 5555,
+            },
+        )
+        listed = client.get("/instances").json()["instances"]
+        assert listed[0]["ip"] == "10.0.0.1"
+        assert listed[0]["p2p_advertised_url"] == "10.0.0.1:7600"
+        assert listed[0]["mq_port"] == 5555
+
+
+def test_register_defaults_mq_port_when_absent():
+    with _client() as client:
+        client.post(
+            "/instances",
+            json={"instance_id": "i1", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        listed = client.get("/instances").json()["instances"]
+        assert listed[0]["mq_port"] == 0
+
+
+def test_re_register_reports_true():
+    with _client() as client:
+        client.post(
+            "/instances",
+            json={"instance_id": "i1", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        resp = client.post(
+            "/instances",
+            json={"instance_id": "i1", "ip": "127.0.0.1", "http_port": 9090},
+        )
+        assert resp.json()["re_registered"] is True
+
+
+def test_heartbeat_known_and_unknown():
+    with _client() as client:
+        client.post(
+            "/instances",
+            json={"instance_id": "i1", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        assert client.put("/instances/i1/heartbeat").status_code == 200
+        # Unknown instance -> 404 so the client knows to re-register.
+        assert client.put("/instances/ghost/heartbeat").status_code == 404
+
+
+def test_deregister_is_idempotent():
+    with _client() as client:
+        assert client.delete("/instances/never-registered").status_code == 204
+
+
+def test_register_rejects_bad_body():
+    # The Pydantic model validates the body; FastAPI returns 422 on bad input.
+    with _client() as client:
+        # Missing ip / http_port.
+        assert client.post("/instances", json={"instance_id": "x"}).status_code == 422
+        # http_port not coercible to int.
+        bad = {"instance_id": "x", "ip": "127.0.0.1", "http_port": "nope"}
+        assert client.post("/instances", json=bad).status_code == 422
+
+
+def test_register_generates_id_when_empty():
+    with _client() as client:
+        # Empty / omitted instance_id -> coordinator assigns one.
+        resp = client.post("/instances", json={"ip": "127.0.0.1", "http_port": 8080})
+        assert resp.status_code == 200
+        assigned = resp.json()["instance_id"]
+        assert assigned
+        listed = client.get("/instances").json()["instances"]
+        assert [i["instance_id"] for i in listed] == [assigned]
+
+
+def test_register_rejects_blank_ip():
+    with _client() as client:
+        # Whitespace-only ip is stripped to empty and rejected.
+        bad = {"instance_id": "x", "ip": "   ", "http_port": 8080}
+        assert client.post("/instances", json=bad).status_code == 422
+
+
+def test_whitespace_instance_id_is_generated():
+    with _client() as client:
+        # Whitespace-only id strips to empty -> coordinator assigns one.
+        resp = client.post(
+            "/instances",
+            json={"instance_id": "  ", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["instance_id"].strip()
+
+
+def test_p2p_advertised_url_round_trips():
+    with _client() as client:
+        client.post(
+            "/instances",
+            json={
+                "instance_id": "i1",
+                "ip": "127.0.0.1",
+                "http_port": 8080,
+                "p2p_advertised_url": "http://10.0.0.1:9100",
+            },
+        )
+        listed = client.get("/instances").json()["instances"]
+        assert listed[0]["p2p_advertised_url"] == "http://10.0.0.1:9100"
+
+
+def test_p2p_advertised_url_defaults_to_empty():
+    with _client() as client:
+        # Omitting p2p_advertised_url leaves it empty (instance is not in P2P).
+        client.post(
+            "/instances",
+            json={"instance_id": "i1", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        listed = client.get("/instances").json()["instances"]
+        assert listed[0]["p2p_advertised_url"] == ""
+
+
+def test_healthz():
+    with _client() as client:
+        assert client.get("/healthz").json() == {"status": "healthy"}
diff --git a/tests/v1/mp_coordinator/test_blend_client.py b/tests/v1/mp_coordinator/test_blend_client.py
new file mode 100644
index 0000000..43522ea
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_blend_client.py
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the blend-server side coordinator client.
+
+The HTTP layer is replaced by an injected ``request_fn`` backed by a real
+``GlobalBlendMatcher``, so the queue/daemon/poll state machine is exercised
+end-to-end against the actual directory without a network or server.
+"""
+
+# Standard
+from collections.abc import Callable
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_coordinator.blend_client import (
+    PENDING,
+    BlendCoordinatorClient,
+)
+from lmcache.v1.mp_coordinator.blend_directory import (
+    GlobalBlendMatcher,
+    StoreRange,
+)
+from lmcache.v1.mp_coordinator.schemas import decode_tokens
+
+CHUNK = 3
+SCOPE = "model-a"
+
+
+def _matcher_request(
+    matcher: GlobalBlendMatcher,
+) -> Callable[[str, str, dict], dict]:
+    """request_fn that drives a real matcher, mirroring the coordinator router."""
+
+    def request(method: str, path: str, payload: dict) -> dict:
+        if method == "POST" and path == "/blend/fingerprints":
+            ranges = [
+                StoreRange(
+                    model_scope=r["model_scope"],
+                    tokens=r["tokens"],
+                    object_keys=r["object_keys"],
+                    old_st_base=r["old_st_base"],
+                )
+                for r in payload.get("ranges", [])
+            ]
+            return {"inserted": matcher.register(ranges) if ranges else 0}
+        if method == "DELETE" and path == "/blend/fingerprints":
+            keys = payload.get("object_keys", [])
+            return {"removed": matcher.remove(keys) if keys else 0}
+        if method == "POST" and path == "/blend/match":
+            matches = matcher.match(
+                payload["model_scope"], decode_tokens(payload["tokens_b64"])
+            )
+            return {
+                "matches": [
+                    {"object_key": m.object_key, "old_st": m.old_st, "cur_st": m.cur_st}
+                    for m in matches
+                ]
+            }
+        raise AssertionError(f"unexpected {method} {path}")
+
+    return request
+
+
+def _range(prefix: str, tokens: list[int]) -> dict:
+    n_chunks = len(tokens) // CHUNK
+    return {
+        "model_scope": SCOPE,
+        "tokens": tokens,
+        "object_keys": [f"{prefix}{i}" for i in range(n_chunks)],
+        "old_st_base": 0,
+    }
+
+
+def _store_range(prefix: str, tokens: list[int]) -> StoreRange:
+    d = _range(prefix, tokens)
+    return StoreRange(**d)
+
+
+def _wait_match(client: BlendCoordinatorClient, rid: str, timeout: float = 2.0):
+    end = time.time() + timeout
+    while time.time() < end:
+        v = client.poll_match(rid)
+        if isinstance(v, list):
+            return v
+        time.sleep(0.005)
+    return client.poll_match(rid)
+
+
+def test_match_after_register():
+    m = GlobalBlendMatcher(chunk_size=CHUNK)
+    doc = [1, 2, 3, 4, 5, 6]
+    m.register([_store_range("K", doc)])
+    client = BlendCoordinatorClient(request_fn=_matcher_request(m))
+    try:
+        client.submit_match("r1", SCOPE, doc)
+        matches = _wait_match(client, "r1")
+        assert isinstance(matches, list)
+        assert [(x.object_key, x.old_st, x.cur_st) for x in matches] == [
+            ("K0", 0, 0),
+            ("K1", 3, 3),
+        ]
+    finally:
+        client.close()
+
+
+def test_publish_reaches_matcher():
+    m = GlobalBlendMatcher(chunk_size=CHUNK)
+    client = BlendCoordinatorClient(request_fn=_matcher_request(m))
+    try:
+        doc = [1, 2, 3]
+        client.enqueue_register([_range("K", doc)])
+        end = time.time() + 2.0
+        ok = False
+        while time.time() < end:
+            if m.match(SCOPE, doc):
+                ok = True
+                break
+            time.sleep(0.005)
+        assert ok
+    finally:
+        client.close()
+
+
+def test_evict_reaches_matcher():
+    m = GlobalBlendMatcher(chunk_size=CHUNK)
+    doc = [1, 2, 3]
+    m.register([_store_range("K", doc)])
+    client = BlendCoordinatorClient(request_fn=_matcher_request(m))
+    try:
+        client.enqueue_evict(["K0"])
+        end = time.time() + 2.0
+        gone = False
+        while time.time() < end:
+            if not m.match(SCOPE, doc):
+                gone = True
+                break
+            time.sleep(0.005)
+        assert gone
+    finally:
+        client.close()
+
+
+def test_poll_none_before_submit():
+    client = BlendCoordinatorClient(request_fn=lambda mth, p, b: {})
+    try:
+        assert client.poll_match("never") is None
+    finally:
+        client.close()
+
+
+def test_submit_is_idempotent():
+    m = GlobalBlendMatcher(chunk_size=CHUNK)
+    doc = [1, 2, 3]
+    m.register([_store_range("K", doc)])
+    client = BlendCoordinatorClient(request_fn=_matcher_request(m))
+    try:
+        client.submit_match("r1", SCOPE, doc)
+        client.submit_match("r1", SCOPE, doc)  # no-op
+        matches = _wait_match(client, "r1")
+        assert isinstance(matches, list) and len(matches) == 1
+    finally:
+        client.close()
+
+
+def test_match_error_degrades_to_empty():
+    def boom(method: str, path: str, payload: dict) -> dict:
+        raise RuntimeError("coordinator down")
+
+    client = BlendCoordinatorClient(request_fn=boom)
+    try:
+        client.submit_match("r1", SCOPE, [1, 2, 3])
+        matches = _wait_match(client, "r1")
+        assert matches == []  # failure -> local-only, never hangs
+    finally:
+        client.close()
+
+
+def test_take_match_clears():
+    m = GlobalBlendMatcher(chunk_size=CHUNK)
+    doc = [1, 2, 3]
+    m.register([_store_range("K", doc)])
+    client = BlendCoordinatorClient(request_fn=_matcher_request(m))
+    try:
+        client.submit_match("r1", SCOPE, doc)
+        _wait_match(client, "r1")
+        client.take_match("r1")
+        assert client.poll_match("r1") is None
+    finally:
+        client.close()
+
+
+def test_maybe_from_env(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.delenv("LMCACHE_COORDINATOR_URL", raising=False)
+    assert BlendCoordinatorClient.maybe_from_env() is None
+
+    monkeypatch.setenv("LMCACHE_COORDINATOR_URL", "http://coord:9300")
+    monkeypatch.delenv("LMCACHE_COORDINATOR_BLEND_TIMEOUT", raising=False)
+    client = BlendCoordinatorClient.maybe_from_env()
+    assert client is not None
+    assert client.match_budget_s == 1.0  # default timeout
+    client.close()
+
+    monkeypatch.setenv("LMCACHE_COORDINATOR_BLEND_TIMEOUT", "1.5")
+    client = BlendCoordinatorClient.maybe_from_env()
+    assert client is not None
+    assert client.match_budget_s == 1.5  # env override
+    client.close()
+
+
+def test_pending_sentinel_distinct():
+    assert PENDING is not None and not isinstance(PENDING, list)
diff --git a/tests/v1/mp_coordinator/test_blend_directory.py b/tests/v1/mp_coordinator/test_blend_directory.py
new file mode 100644
index 0000000..d607890
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_blend_directory.py
@@ -0,0 +1,259 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator global CacheBlend fingerprint directory."""
+
+# Standard
+import threading
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_coordinator.blend_directory import (
+    GlobalBlendMatcher,
+    StoreRange,
+)
+from lmcache.v1.mp_coordinator.schemas import decode_tokens, encode_tokens
+
+CHUNK = 3
+SCOPE = "model-a"
+
+
+def store_range(
+    prefix: str, tokens: list[int], *, scope: str = SCOPE, old_st_base: int = 0
+) -> StoreRange:
+    """A StoreRange with one object_key per complete chunk (mirrors publisher)."""
+    n_chunks = len(tokens) // CHUNK
+    return StoreRange(
+        model_scope=scope,
+        tokens=tokens,
+        object_keys=[f"{prefix}{i}" for i in range(n_chunks)],
+        old_st_base=old_st_base,
+    )
+
+
+class TestRegisterMatch:
+    def test_full_reuse(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        doc = [1, 2, 3, 4, 5, 6]  # 2 chunks
+        assert m.register([store_range("K", doc)]) == 2
+        matches = m.match(SCOPE, doc)
+        assert [(x.object_key, x.old_st, x.cur_st) for x in matches] == [
+            ("K0", 0, 0),
+            ("K1", 3, 3),
+        ]
+
+    def test_stride_controls_offset(self) -> None:
+        """A non-chunk-aligned offset is found at stride 1, missed at stride=chunk."""
+        doc = [1, 2, 3, 4, 5, 6]
+        req = [9, 1, 2, 3, 4, 5, 6]  # doc shifted by 1 (preamble 9)
+
+        fine = GlobalBlendMatcher(chunk_size=CHUNK, probe_stride=1)
+        fine.register([store_range("K", doc)])
+        out = fine.match(SCOPE, req)
+        assert [(x.object_key, x.cur_st) for x in out] == [("K0", 1), ("K1", 4)]
+
+        coarse = GlobalBlendMatcher(chunk_size=CHUNK, probe_stride=CHUNK)
+        coarse.register([store_range("K", doc)])  # probes pos 0,3,6 -> misses
+        assert coarse.match(SCOPE, req) == []
+
+    def test_dedup_by_object_key(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        m.register([store_range("K", [1, 2, 3])])  # single chunk K0
+        matches = m.match(SCOPE, [1, 2, 3, 1, 2, 3])  # content repeats
+        assert len(matches) == 1 and matches[0].object_key == "K0"
+
+    def test_scope_isolation(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        m.register([store_range("K", [1, 2, 3], scope="model-a")])
+        assert m.match("model-b", [1, 2, 3]) == []
+
+    def test_request_shorter_than_chunk(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        m.register([store_range("K", [1, 2, 3])])
+        assert m.match(SCOPE, [1, 2]) == []
+
+    def test_no_match(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        m.register([store_range("K", [1, 2, 3])])
+        assert m.match(SCOPE, [7, 8, 9]) == []
+
+
+class TestIdempotencyEviction:
+    def test_register_idempotent(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        rng = store_range("K", [1, 2, 3, 4, 5, 6])
+        assert m.register([rng]) == 2
+        assert m.register([rng]) == 0
+        assert len(m.match(SCOPE, [1, 2, 3, 4, 5, 6])) == 2
+
+    def test_remove_evicts(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        m.register([store_range("K", [1, 2, 3, 4, 5, 6])])  # K0, K1
+        assert m.remove(["K0"]) == 1
+        matches = m.match(SCOPE, [1, 2, 3, 4, 5, 6])
+        assert [x.object_key for x in matches] == ["K1"]  # only K0 gone
+
+    def test_remove_unknown_is_noop(self) -> None:
+        assert GlobalBlendMatcher(chunk_size=CHUNK).remove(["nope"]) == 0
+
+    def test_growth_and_compaction(self) -> None:
+        """Matching survives a table grow rebuild and a mass-evict compaction."""
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        n = 400  # past the initial table's load factor, forcing a grow rebuild
+        docs = [[1000 + 3 * i, 1001 + 3 * i, 1002 + 3 * i] for i in range(n)]
+        for d, doc in enumerate(docs):
+            m.register([store_range(f"D{d}_", doc)])
+        # Mass eviction triggers tombstone compaction.
+        assert m.remove([f"D{d}_0" for d in range(n - 1)]) == n - 1
+        out = m.match(SCOPE, docs[n - 1])
+        assert [x.object_key for x in out] == [f"D{n - 1}_0"]
+        assert m.match(SCOPE, docs[0]) == []
+
+    def test_count_mismatch_range_skipped(self) -> None:
+        """A range whose object_keys count != chunk count is skipped, not partial."""
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        doc = [1, 2, 3, 4, 5, 6]  # 2 chunks
+        bad = StoreRange(
+            model_scope=SCOPE,
+            tokens=doc,
+            object_keys=["K0"],  # only 1 key for 2 chunks -> mismatch
+            old_st_base=0,
+        )
+        assert m.register([bad]) == 0
+        assert m.match(SCOPE, doc) == []
+
+
+class TestValidation:
+    def test_bad_chunk_size(self) -> None:
+        with pytest.raises(ValueError):
+            GlobalBlendMatcher(chunk_size=0)
+
+    def test_bad_probe_stride(self) -> None:
+        with pytest.raises(ValueError):
+            GlobalBlendMatcher(chunk_size=CHUNK, probe_stride=0)
+
+
+class TestVectorizedMatch:
+    """Guards the vectorized probe against a brute-force reference."""
+
+    def test_matches_reference_on_large_random_input(self) -> None:
+        # Standard
+        import random
+
+        rng = random.Random(1234)
+        chunk = 8
+        m = GlobalBlendMatcher(chunk_size=chunk, probe_stride=1)
+
+        # Build a corpus of distinct docs; register each as one object_key/chunk.
+        windows: dict[tuple[int, ...], tuple[str, int]] = {}
+        for d in range(40):
+            doc = [rng.randint(0, 50) for _ in range(chunk * 4)]
+            n_chunks = len(doc) // chunk
+            m.register(
+                [
+                    StoreRange(
+                        model_scope=SCOPE,
+                        tokens=doc,
+                        object_keys=[f"D{d}_{c}" for c in range(n_chunks)],
+                        old_st_base=0,
+                    )
+                ]
+            )
+            for c in range(len(doc) // chunk):
+                w = tuple(doc[c * chunk : (c + 1) * chunk])
+                windows.setdefault(w, (f"D{d}_{c}", c * chunk))
+
+        # A request stitched from random tokens and some embedded known windows.
+        req = [rng.randint(0, 50) for _ in range(200)]
+        for _ in range(5):
+            embed = list(rng.choice(list(windows.keys())))
+            pos = rng.randint(0, len(req) - chunk)
+            req[pos : pos + chunk] = embed
+
+        # Reference: probe every position, first-writer-wins object_key dedup.
+        expected: list[tuple[str, int]] = []
+        seen: set[str] = set()
+        for p in range(len(req) - chunk + 1):
+            w = tuple(req[p : p + chunk])
+            loc = windows.get(w)
+            if loc is None or loc[0] in seen:
+                continue
+            seen.add(loc[0])
+            expected.append((loc[0], p))
+
+        got = [(x.object_key, x.cur_st) for x in m.match(SCOPE, req)]
+        assert got == expected
+        # Sanity: the embedded windows are actually found.
+        assert len(got) >= 1
+
+    def test_cur_st_ascending_with_stride(self) -> None:
+        doc = [1, 2, 3, 4, 5, 6, 7, 8, 9]  # 3 chunks of size 3
+        m = GlobalBlendMatcher(chunk_size=CHUNK, probe_stride=CHUNK)
+        m.register([store_range("K", doc)])
+        out = m.match(SCOPE, doc)
+        cur_sts = [x.cur_st for x in out]
+        assert cur_sts == sorted(cur_sts)
+        assert cur_sts == [0, 3, 6]
+
+
+class TestConcurrency:
+    def test_concurrent_register_and_match(self) -> None:
+        """Interleaved publishes and queries stay correct and never crash."""
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        docs = [[i, i + 1, i + 2] for i in range(0, 300, 3)]
+        errors: list[Exception] = []
+
+        def publisher() -> None:
+            try:
+                for d, doc in enumerate(docs):
+                    m.register([store_range(f"D{d}_", doc)])
+            except Exception as e:  # noqa: BLE001
+                errors.append(e)
+
+        def matcher() -> None:
+            try:
+                for doc in docs:
+                    m.match(SCOPE, doc)
+            except Exception as e:  # noqa: BLE001
+                errors.append(e)
+
+        threads = [threading.Thread(target=publisher) for _ in range(2)]
+        threads += [threading.Thread(target=matcher) for _ in range(4)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert not errors
+        # After all publishes, every doc's chunk is matchable.
+        for d, doc in enumerate(docs):
+            out = m.match(SCOPE, doc)
+            assert any(x.object_key == f"D{d}_0" for x in out)
+
+
+class TestTokenCodec:
+    def test_round_trip(self) -> None:
+        tokens = [0, 1, 2, 65535, 2**31, 2**32 - 1]
+        decoded = decode_tokens(encode_tokens(tokens))
+        assert decoded.tolist() == tokens
+
+    def test_empty(self) -> None:
+        assert decode_tokens(encode_tokens([])).tolist() == []
+
+    def test_decoded_feeds_match(self) -> None:
+        m = GlobalBlendMatcher(chunk_size=CHUNK)
+        doc = [1, 2, 3, 4, 5, 6]
+        m.register([store_range("K", doc)])
+        out = m.match(SCOPE, decode_tokens(encode_tokens(doc)))
+        assert [x.object_key for x in out] == ["K0", "K1"]
+
+    def test_malformed_base64_raises(self) -> None:
+        with pytest.raises(ValueError):
+            decode_tokens("not valid base64 !!!")
+
+    def test_bad_byte_length_raises(self) -> None:
+        # Standard
+        import base64
+
+        with pytest.raises(ValueError):
+            decode_tokens(base64.b64encode(b"abc").decode())  # 3 bytes, not /4
diff --git a/tests/v1/mp_coordinator/test_blend_directory_api.py b/tests/v1/mp_coordinator/test_blend_directory_api.py
new file mode 100644
index 0000000..ba787bc
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_blend_directory_api.py
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the /blend fingerprint directory REST endpoints."""
+
+# Third Party
+from fastapi.testclient import TestClient
+
+# First Party
+from lmcache.v1.mp_coordinator.app import create_app
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+from lmcache.v1.mp_coordinator.schemas import encode_tokens
+
+CHUNK = 3
+SCOPE = "model-a"
+
+
+def _client() -> TestClient:
+    config = MPCoordinatorConfig(health_check_interval=0.0, chunk_size=CHUNK)
+    return TestClient(create_app(config))
+
+
+def _range(prefix: str, tokens: list[int]) -> dict:
+    n_chunks = len(tokens) // CHUNK
+    return {
+        "model_scope": SCOPE,
+        "tokens": tokens,
+        "object_keys": [f"{prefix}{i}" for i in range(n_chunks)],
+        "old_st_base": 0,
+    }
+
+
+def test_publish_then_match():
+    with _client() as client:
+        doc = [1, 2, 3, 4, 5, 6]
+        resp = client.post("/blend/fingerprints", json={"ranges": [_range("K", doc)]})
+        assert resp.status_code == 200
+        assert resp.json() == {"inserted": 2}
+
+        out = client.post(
+            "/blend/match",
+            json={"model_scope": SCOPE, "tokens_b64": encode_tokens(doc)},
+        ).json()["matches"]
+        assert [(m["object_key"], m["old_st"], m["cur_st"]) for m in out] == [
+            ("K0", 0, 0),
+            ("K1", 3, 3),
+        ]
+
+
+def test_match_miss_returns_empty():
+    with _client() as client:
+        out = client.post(
+            "/blend/match",
+            json={"model_scope": SCOPE, "tokens_b64": encode_tokens([7, 8, 9])},
+        ).json()
+        assert out == {"matches": []}
+
+
+def test_remove_evicts():
+    with _client() as client:
+        doc = [1, 2, 3, 4, 5, 6]
+        client.post("/blend/fingerprints", json={"ranges": [_range("K", doc)]})
+        resp = client.request(
+            "DELETE", "/blend/fingerprints", json={"object_keys": ["K0", "K1"]}
+        )
+        assert resp.json() == {"removed": 2}
+        out = client.post(
+            "/blend/match",
+            json={"model_scope": SCOPE, "tokens_b64": encode_tokens(doc)},
+        ).json()
+        assert out == {"matches": []}
+
+
+def test_idempotent_publish():
+    with _client() as client:
+        doc = [1, 2, 3, 4, 5, 6]
+        client.post("/blend/fingerprints", json={"ranges": [_range("K", doc)]})
+        resp = client.post("/blend/fingerprints", json={"ranges": [_range("K", doc)]})
+        assert resp.json() == {"inserted": 0}
+
+
+def test_match_malformed_tokens_b64_returns_422():
+    """A bad tokens_b64 is a client error (422), not an unhandled 500."""
+    with _client() as client:
+        # Not valid base64.
+        resp = client.post(
+            "/blend/match",
+            json={"model_scope": SCOPE, "tokens_b64": "not!base64!"},
+        )
+        assert resp.status_code == 422
+
+        # Valid base64 but not a whole number of uint32 tokens (3 bytes).
+        # Standard
+        import base64
+
+        resp = client.post(
+            "/blend/match",
+            json={
+                "model_scope": SCOPE,
+                "tokens_b64": base64.b64encode(b"\x01\x02\x03").decode("ascii"),
+            },
+        )
+        assert resp.status_code == 422
diff --git a/tests/v1/mp_coordinator/test_cache_api.py b/tests/v1/mp_coordinator/test_cache_api.py
new file mode 100644
index 0000000..5aadaed
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_cache_api.py
@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator ``/cache/*`` REST API (warm-prefetch dispatch).
+
+Quota writes, usage events, and status reads moved to the ``/quota`` group --
+see ``test_quota_api.py``.
+"""
+
+# Third Party
+from fastapi.testclient import TestClient
+import httpx
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.mp_coordinator.app import create_app
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+from lmcache.v1.mp_coordinator.utils.cache_utils import resolve_object_keys
+
+
+def _client() -> TestClient:
+    config = MPCoordinatorConfig(health_check_interval=0.0, eviction_check_interval=0.0)
+    return TestClient(create_app(config))
+
+
+# -- Prefetch dispatch -------------------------------------------------------
+
+
+def _prefetch_body(instance_id: str, salt: str = "alice") -> dict:
+    return {
+        "instance_id": instance_id,
+        "model_name": "m",
+        "world_size": 1,
+        "token_ids": [1, 2, 3, 4],
+        "cache_salt": salt,
+    }
+
+
+def _mock_mp_server() -> httpx.AsyncClient:
+    """An outbound client that emulates the target MP server's prefetch API."""
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST" and request.url.path == "/cache/prefetches":
+            return httpx.Response(
+                202, json={"request_id": "abc", "chunks": 2, "status": "submitted"}
+            )
+        if request.method == "GET" and request.url.path == "/cache/prefetches/abc":
+            return httpx.Response(
+                200, json={"status": "completed", "found_keys": 2, "total_keys": 2}
+            )
+        return httpx.Response(404, json={"detail": "not found"})
+
+    return httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+
+def test_prefetch_unknown_instance_returns_404():
+    """Targeting an unregistered instance must 404 (before any dispatch)."""
+    with _client() as client:
+        resp = client.post("/cache/prefetches", json=_prefetch_body("does-not-exist"))
+        assert resp.status_code == 404
+
+
+def test_prefetch_submit_then_status_proxy():
+    """A registered target: submit relays the server's request_id, and the
+    status GET proxies the server's completion body."""
+    with _client() as client:
+        client.post(
+            "/instances",
+            json={"instance_id": "mp-1", "ip": "127.0.0.1", "http_port": 8080},
+        )
+        # Replace the lifespan's real outbound client with a mock MP server.
+        client.app.state.ctx.outbound_client = _mock_mp_server()
+
+        resp = client.post("/cache/prefetches", json=_prefetch_body("mp-1"))
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {
+            "instance_id": "mp-1",
+            "request_id": "abc",
+            "chunks": 2,
+            "status": "submitted",
+        }
+
+        status = client.get("/cache/prefetches/mp-1/abc")
+        assert status.status_code == 200, status.text
+        assert status.json() == {
+            "status": "completed",
+            "found_keys": 2,
+            "total_keys": 2,
+        }
+
+
+def test_prefetch_status_unknown_instance_returns_404():
+    """Status for an unregistered instance must 404."""
+    with _client() as client:
+        resp = client.get("/cache/prefetches/does-not-exist/abc")
+        assert resp.status_code == 404
+
+
+# -- Pin / unpin (coordinator-side L2 pin) -----------------------------------
+
+
+def _pin_client() -> TestClient:
+    """A coordinator with a small chunk_size so short token sequences resolve."""
+    config = MPCoordinatorConfig(
+        health_check_interval=0.0, eviction_check_interval=0.0, chunk_size=4
+    )
+    return TestClient(create_app(config))
+
+
+def _pin_body(salt: str = "alice") -> dict:
+    return {
+        "model_name": "m",
+        "world_size": 1,
+        "token_ids": [1, 2, 3, 4, 5, 6, 7, 8],
+        "cache_salt": salt,
+    }
+
+
+def _resolve(ctx, salt: str = "alice") -> list[ObjectKey]:
+    """Resolve the pin body's keys the same way the handler will."""
+    keys, _ = resolve_object_keys(
+        ctx.token_hasher, "m", 1, [1, 2, 3, 4, 5, 6, 7, 8], salt
+    )
+    return keys
+
+
+def test_pin_then_unpin_tracks_l2_eviction():
+    """Pin excludes the resolved keys from L2 eviction; unpin restores them."""
+    with _pin_client() as client:
+        ctx = client.app.state.ctx
+        keys = _resolve(ctx)
+        assert keys  # 2 chunks x world_size 1
+
+        # Arm allowlist enforcement (unquota'd salts are exempt until the
+        # default limit is set), then track the keys in the L2 eviction LRU
+        # with no quota (evict-all), so the plan would evict them unless
+        # pinned.
+        assert (
+            client.put("/quota/config", json={"default_limit_gb": 0}).status_code == 200
+        )
+        for k in keys:
+            ctx.usage_manager.record_stored(k, 1000)
+            ctx.eviction_manager.on_store(k)
+        assert ctx.eviction_manager.compute_eviction_plan()["alice"]
+
+        resp = client.post("/cache/pins", json=_pin_body())
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {
+            "requested": 2,
+            "affected": len(keys),
+            "status": "pinned",
+        }
+        # Pinned: the keys drop out of the eviction plan.
+        assert ctx.eviction_manager.compute_eviction_plan() == {}
+
+        resp = client.request("DELETE", "/cache/pins", json=_pin_body())
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {
+            "requested": 2,
+            "affected": len(keys),
+            "status": "unpinned",
+        }
+        # Unpinned: the keys are eligible for eviction again.
+        assert ctx.eviction_manager.compute_eviction_plan()["alice"]
+
+
+def test_pin_short_sequence_is_noop():
+    """A sub-chunk sequence resolves to no keys (affected 0)."""
+    with _pin_client() as client:
+        body = {
+            "model_name": "m",
+            "world_size": 1,
+            "token_ids": [1, 2],
+            "cache_salt": "",
+        }
+        resp = client.post("/cache/pins", json=body)
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"requested": 0, "affected": 0, "status": "pinned"}
+
+
+def test_pin_invalid_cache_salt_returns_400():
+    """An invalid cache_salt (forbidden char) is a 400."""
+    with _pin_client() as client:
+        resp = client.post("/cache/pins", json=_pin_body(salt="bad@salt"))
+        assert resp.status_code == 400
diff --git a/tests/v1/mp_coordinator/test_config.py b/tests/v1/mp_coordinator/test_config.py
new file mode 100644
index 0000000..62615d2
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_config.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for MPCoordinatorConfig validation and env loading."""
+
+# Standard
+from unittest.mock import patch
+import os
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+
+
+def test_defaults_are_valid():
+    config = MPCoordinatorConfig()
+    assert config.instance_timeout > 0
+
+
+def test_non_positive_intervals_rejected():
+    with pytest.raises(ValueError):
+        MPCoordinatorConfig(instance_timeout=0.0)
+    with pytest.raises(ValueError):
+        MPCoordinatorConfig(health_check_interval=-1.0)
+
+
+def test_from_env_overrides_and_falls_back():
+    env = {
+        "LMCACHE_MP_COORDINATOR_HOST": "127.0.0.1",
+        "LMCACHE_MP_COORDINATOR_PORT": "7777",
+        "LMCACHE_MP_COORDINATOR_INSTANCE_TIMEOUT": "42",
+    }
+    with patch.dict(os.environ, env, clear=False):
+        config = MPCoordinatorConfig.from_env()
+    assert config.host == "127.0.0.1"
+    assert config.port == 7777
+    assert config.instance_timeout == 42.0
+    # Unset variable keeps the default.
+    assert config.health_check_interval == MPCoordinatorConfig.health_check_interval
diff --git a/tests/v1/mp_coordinator/test_eviction_manager.py b/tests/v1/mp_coordinator/test_eviction_manager.py
new file mode 100644
index 0000000..21f256b
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_eviction_manager.py
@@ -0,0 +1,526 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator eviction manager."""
+
+# Standard
+import time
+
+# Third Party
+import httpx
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.mp_coordinator.cache_control.eviction_manager import (
+    L2EvictionManager,
+)
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry, MPInstance
+
+
+def _make_key(salt: str, model: str = "m", rank: int = 0, h: str = "aa") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=bytes.fromhex(h),
+        model_name=model,
+        kv_rank=rank,
+        cache_salt=salt,
+    )
+
+
+def _setup(
+    eviction_ratio: float = 0.5,
+    trigger_watermark: float = 1.0,
+    default_limit_bytes: int | None = 0,
+) -> tuple[L2EvictionManager, QuotaManager, L2UsageManager]:
+    """Build the manager trio.
+
+    ``default_limit_bytes=0`` (the helper default) arms strict allowlist
+    enforcement — the steady state a quota controller configures via
+    ``PUT /quota/config`` after re-syncing quotas — so most tests exercise
+    armed behavior. Pass ``default_limit_bytes=None`` to exercise the
+    exempt boot state instead.
+    """
+    qs = QuotaManager()
+    qs.set_default_limit_bytes(default_limit_bytes)
+    ut = L2UsageManager()
+    ctrl = L2EvictionManager(
+        qs,
+        ut,
+        eviction_ratio=eviction_ratio,
+        trigger_watermark=trigger_watermark,
+    )
+    return ctrl, qs, ut
+
+
+def _store(
+    ctrl: L2EvictionManager,
+    ut: L2UsageManager,
+    key: ObjectKey,
+    size: int,
+) -> None:
+    """Helper: record the bytes against the usage ledger and register
+    the key in the eviction LRU — the two calls that the production
+    ``/quota/events`` handler issues for a single store event."""
+    ut.record_stored(key, size)
+    ctrl.on_store(key)
+
+
+def _remove(
+    ctrl: L2EvictionManager,
+    ut: L2UsageManager,
+    key: ObjectKey,
+) -> None:
+    """Helper: subtract the key's bytes from the usage ledger and
+    drop it from the eviction LRU — the two calls that the production
+    ``/quota/events`` handler issues for a single delete event."""
+    ut.record_evicted(key)
+    ctrl.on_remove(key)
+
+
+def test_on_store_tracks_key():
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 100)
+    result = ctrl.compute_eviction_plan()
+    assert result["a"] == [k]
+
+
+def test_on_lookup_touches_key():
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k1 = _make_key("a", h="01")
+    k2 = _make_key("a", h="02")
+    _store(ctrl, ut, k1, 100)
+    _store(ctrl, ut, k2, 100)
+    ctrl.on_lookup(k1)
+    result = ctrl.compute_eviction_plan()
+    assert result["a"][0] == k2
+
+
+def test_on_lookup_unknown_key_is_noop():
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    ctrl.on_lookup(k)
+    # Lookup without prior store ⇒ key never tracked. Add an
+    # unrelated key so the salt has some usage, but the unknown key
+    # mustn't show up in the plan.
+    other = _make_key("a", h="ff")
+    _store(ctrl, ut, other, 100)
+    result = ctrl.compute_eviction_plan()
+    assert k not in result.get("a", [])
+
+
+def test_on_remove():
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k1 = _make_key("a", h="01")
+    k2 = _make_key("a", h="02")
+    _store(ctrl, ut, k1, 100)
+    _store(ctrl, ut, k2, 200)
+    _remove(ctrl, ut, k1)
+    # _remove drops k1 from both LRU and the size ledger.
+    assert not ut.has_key(k1)
+    assert ut.has_key(k2)
+    result = ctrl.compute_eviction_plan()
+    assert result["a"] == [k2]
+
+
+def test_on_remove_subtracts_bytes_from_usage():
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k1 = _make_key("a", h="01")
+    k2 = _make_key("a", h="02")
+    _store(ctrl, ut, k1, 100)
+    _store(ctrl, ut, k2, 200)
+    assert ut.get("a") == 300
+    _remove(ctrl, ut, k1)
+    # Bucket loses exactly k1's bytes.
+    assert ut.get("a") == 200
+
+
+def test_on_remove_cleans_empty_bucket():
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 100)
+    _remove(ctrl, ut, k)
+    assert ut.get("a") == 0
+    result = ctrl.compute_eviction_plan()
+    assert result == {}
+
+
+def test_no_quota_evicts_all_when_default_armed():
+    """Armed default (0): a salt with no explicit quota is fully evicted."""
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 1000)
+    result = ctrl.compute_eviction_plan()
+    assert "a" in result
+    assert result["a"] == [k]
+
+
+# ============================================================================
+# Default-limit gating (exempt boot state vs armed allowlist)
+# ============================================================================
+
+
+def test_unquotad_salt_exempt_until_default_set():
+    """Boot state (default None): unquota'd salts are skipped entirely —
+    a restarted coordinator with an empty quota table must not plan a
+    mass eviction of unknown tenants."""
+    ctrl, _, ut = _setup(eviction_ratio=1.0, default_limit_bytes=None)
+    _store(ctrl, ut, _make_key("a", h="01"), 1000)
+    _store(ctrl, ut, _make_key("b", h="02"), 2000)
+    assert ctrl.compute_eviction_plan() == {}
+
+
+def test_explicit_quota_enforced_even_while_default_unset():
+    """Per-salt quotas take effect as soon as they are registered, even
+    before the controller arms the default — over-quota tenants are
+    evicted while unquota'd tenants stay exempt."""
+    ctrl, qs, ut = _setup(eviction_ratio=1.0, default_limit_bytes=None)
+    ka = _make_key("a", h="01")
+    kb = _make_key("b", h="02")
+    _store(ctrl, ut, ka, 1000)
+    _store(ctrl, ut, kb, 1000)
+    qs.set_quota("a", 500)  # over quota
+    result = ctrl.compute_eviction_plan()
+    assert result.get("a") == [ka]
+    assert "b" not in result  # unquota'd, default unset ⇒ exempt
+
+
+def test_setting_default_zero_arms_allowlist_eviction():
+    """The controller's ``PUT /quota/config`` signal: flipping the default
+    from None to 0 makes previously-exempt unquota'd bytes evictable."""
+    ctrl, qs, ut = _setup(eviction_ratio=1.0, default_limit_bytes=None)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 1000)
+    assert ctrl.compute_eviction_plan() == {}
+
+    qs.set_default_limit_bytes(0)
+    result = ctrl.compute_eviction_plan()
+    assert result.get("a") == [k]
+
+
+def test_positive_default_acts_as_budget_for_unquotad_salts():
+    """A positive default gives unquota'd salts a real byte budget."""
+    ctrl, qs, ut = _setup(eviction_ratio=1.0, default_limit_bytes=None)
+    qs.set_default_limit_bytes(1500)
+    under = _make_key("a", h="01")
+    over = _make_key("b", h="02")
+    _store(ctrl, ut, under, 1000)  # under the 1500 default
+    _store(ctrl, ut, over, 2000)  # over it
+    result = ctrl.compute_eviction_plan()
+    assert "a" not in result
+    assert result.get("b") == [over]
+
+
+def test_under_quota():
+    ctrl, qs, ut = _setup()
+    qs.set_quota("a", 2000)
+    _store(ctrl, ut, _make_key("a"), 1000)
+    result = ctrl.compute_eviction_plan()
+    assert result == {}
+
+
+def test_over_quota():
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    qs.set_quota("a", 500)
+    k1 = _make_key("a", h="01")
+    k2 = _make_key("a", h="02")
+    _store(ctrl, ut, k1, 400)
+    _store(ctrl, ut, k2, 600)
+    result = ctrl.compute_eviction_plan()
+    assert "a" in result
+    assert k1 in result["a"]
+    assert k2 in result["a"]
+
+
+def test_eviction_ratio():
+    ctrl, qs, ut = _setup(eviction_ratio=0.5)
+    qs.set_quota("a", 500)
+    k1 = _make_key("a", h="01")
+    k2 = _make_key("a", h="02")
+    _store(ctrl, ut, k1, 200)
+    _store(ctrl, ut, k2, 800)
+    result = ctrl.compute_eviction_plan()
+    assert "a" in result
+    assert len(result["a"]) == 1
+    assert result["a"][0] == k1
+
+
+def test_zero_quota_evicts_all():
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    qs.set_quota("a", 0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 1000)
+    result = ctrl.compute_eviction_plan()
+    assert "a" in result
+    assert result["a"] == [k]
+
+
+def test_multiple_salts_independent():
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    qs.set_quota("a", 100)
+    qs.set_quota("b", 5000)
+    ka = _make_key("a", h="01")
+    kb = _make_key("b", h="02")
+    _store(ctrl, ut, ka, 500)
+    _store(ctrl, ut, kb, 1000)
+    result = ctrl.compute_eviction_plan()
+    assert "a" in result
+    assert "b" not in result
+
+
+def test_watermark_below_threshold_skips():
+    ctrl, qs, ut = _setup(trigger_watermark=0.8)
+    qs.set_quota("a", 1000)
+    _store(ctrl, ut, _make_key("a"), 700)
+    result = ctrl.compute_eviction_plan()
+    assert result == {}
+
+
+def test_watermark_above_threshold_evicts():
+    ctrl, qs, ut = _setup(eviction_ratio=1.0, trigger_watermark=0.8)
+    qs.set_quota("a", 1000)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 900)
+    result = ctrl.compute_eviction_plan()
+    assert "a" in result
+    assert result["a"] == [k]
+
+
+# ============================================================================
+# execute_evictions (async dispatch)
+# ============================================================================
+
+
+def _make_registry(*instances: MPInstance) -> InstanceRegistry:
+    reg = InstanceRegistry()
+    for inst in instances:
+        reg.register(inst)
+    return reg
+
+
+def _instance(instance_id: str, ip: str = "10.0.0.1", port: int = 8000) -> MPInstance:
+    now = time.time()
+    return MPInstance(
+        instance_id=instance_id,
+        ip=ip,
+        http_port=port,
+        registration_time=now,
+        last_heartbeat_time=now,
+    )
+
+
+@pytest.mark.asyncio
+async def test_execute_evictions_dispatches_to_registered_instance():
+    """Computed plan must DELETE /cache/objects to a registered MP server with
+    the right body shape. The LRU is NOT cleared by ``execute_evictions``
+    itself — that happens later via the coordinator's ``/quota/events``
+    handler when the MP server reports the deletion back."""
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("alice", h="aa")
+    _store(ctrl, ut, k, 100)
+    qs.set_quota("alice", 0)  # ratio=1.0 → full eviction
+
+    registry = _make_registry(_instance("mp-1", ip="10.0.0.7", port=8765))
+
+    captured: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        captured["json"] = (request.read() or b"").decode()
+        return httpx.Response(200, json={"requested": 1, "adapter": "s3", "ok": True})
+
+    transport = httpx.MockTransport(handler)
+    async with httpx.AsyncClient(transport=transport) as client:
+        plan = await ctrl.execute_evictions(registry, client)
+        # Dispatch is fire-and-forget — wait for the background task
+        # to actually issue the HTTP call before the client closes.
+        await ctrl.wait_for_in_flight_dispatches()
+
+    assert plan == {"alice": [k]}
+    # Hit the single registered instance.
+    assert captured["url"] == "http://10.0.0.7:8765/cache/objects"
+    # Body shape matches the MP endpoint's contract.
+    # Standard
+    import json as _json
+
+    body = _json.loads(captured["json"])
+    assert body == {
+        "keys": [
+            {
+                "chunk_hash_hex": "aa",
+                "model_name": "m",
+                "kv_rank": 0,
+                "object_group_id": 0,
+                "cache_salt": "alice",
+            }
+        ]
+    }
+    # LRU + usage are UNCHANGED at this point — the DELETE event hasn't
+    # arrived yet. Cleanup happens once the MP server flushes its
+    # ``on_l2_keys_deleted`` events back through ``/quota/events``.
+    assert ctrl.compute_eviction_plan() == {"alice": [k]}
+    assert ut.get("alice") == 100
+
+
+@pytest.mark.asyncio
+async def test_execute_evictions_no_instances_skips_dispatch_and_keeps_lru():
+    """No registered MP servers ⇒ the plan is logged but neither
+    dispatched nor cleared from the LRU."""
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("alice", h="bb")
+    _store(ctrl, ut, k, 100)
+    qs.set_quota("alice", 0)
+
+    registry = _make_registry()  # empty
+
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(
+            lambda r: pytest.fail("must not be called")  # type: ignore[arg-type]
+        )
+    ) as client:
+        plan = await ctrl.execute_evictions(registry, client)
+        await ctrl.wait_for_in_flight_dispatches()
+
+    assert plan == {"alice": [k]}
+    # LRU UNCHANGED — the same plan should re-emerge next cycle.
+    assert ctrl.compute_eviction_plan() == {"alice": [k]}
+
+
+@pytest.mark.asyncio
+async def test_execute_evictions_http_failure_keeps_lru():
+    """A non-2xx (or transport error) from the MP server must NOT
+    clear the LRU — the next cycle should retry."""
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("alice", h="cc")
+    _store(ctrl, ut, k, 100)
+    qs.set_quota("alice", 0)
+
+    registry = _make_registry(_instance("mp-1"))
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, json={"error": "internal"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+        plan = await ctrl.execute_evictions(registry, client)
+        await ctrl.wait_for_in_flight_dispatches()
+
+    assert plan == {"alice": [k]}
+    # LRU UNCHANGED — retry on the next cycle.
+    assert ctrl.compute_eviction_plan() == {"alice": [k]}
+
+
+@pytest.mark.asyncio
+async def test_execute_evictions_chunks_large_plan(monkeypatch):
+    """A plan larger than ``MAX_KEYS_PER_DELETE`` is split into multiple DELETE
+    requests, each within the cap, together covering every key. Guards against
+    the MP endpoint's per-request key limit (object_service.MAX_DELETE_BATCH),
+    which rejects an oversized single request with HTTP 400."""
+    # First Party
+    import lmcache.v1.mp_coordinator.cache_control.eviction_manager as em
+
+    monkeypatch.setattr(em, "MAX_DELETE_BATCH", 2)
+
+    ctrl, qs, ut = _setup(eviction_ratio=1.0)
+    keys = [_make_key("alice", h=f"{i:02x}") for i in range(5)]
+    for k in keys:
+        _store(ctrl, ut, k, 100)
+    qs.set_quota("alice", 0)  # ratio=1.0 → full eviction of all 5 keys
+
+    registry = _make_registry(_instance("mp-1"))
+
+    # Standard
+    import json as _json
+
+    batch_sizes: list[int] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = _json.loads((request.read() or b"").decode())
+        batch_sizes.append(len(body["keys"]))
+        return httpx.Response(200, json={"requested": len(body["keys"]), "ok": True})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+        plan = await ctrl.execute_evictions(registry, client)
+        await ctrl.wait_for_in_flight_dispatches()
+
+    assert plan == {"alice": keys}
+    # 5 keys, cap 2 → three requests of 2, 2, 1; none exceeds the cap.
+    assert sum(batch_sizes) == 5
+    assert all(n <= 2 for n in batch_sizes)
+    assert sorted(batch_sizes, reverse=True) == [2, 2, 1]
+
+
+@pytest.mark.asyncio
+async def test_execute_evictions_empty_plan_is_noop():
+    """No salts over threshold ⇒ no HTTP dispatch."""
+    ctrl, _, _ = _setup()
+
+    registry = _make_registry(_instance("mp-1"))
+
+    async with httpx.AsyncClient(
+        transport=httpx.MockTransport(
+            lambda r: pytest.fail("must not be called")  # type: ignore[arg-type]
+        )
+    ) as client:
+        plan = await ctrl.execute_evictions(registry, client)
+        await ctrl.wait_for_in_flight_dispatches()
+
+    assert plan == {}
+
+
+# =============================================================================
+# L2 pin / unpin (eviction exclusion)
+# =============================================================================
+
+
+def test_pin_excludes_key_from_eviction_plan():
+    """A pinned key is never selected for eviction, even over-quota."""
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k1 = _make_key("a", h="01")
+    k2 = _make_key("a", h="02")
+    _store(ctrl, ut, k1, 100)
+    _store(ctrl, ut, k2, 100)
+
+    ctrl.pin([k1])
+    plan = ctrl.compute_eviction_plan()
+    assert k1 not in plan.get("a", [])
+    assert k2 in plan["a"]
+
+
+def test_unpin_restores_eviction_eligibility():
+    """After unpin, a previously pinned key can be evicted again."""
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 100)
+
+    ctrl.pin([k])
+    assert ctrl.compute_eviction_plan() == {}
+
+    ctrl.unpin([k])
+    assert ctrl.compute_eviction_plan()["a"] == [k]
+
+
+def test_pin_is_reference_counted():
+    """Two pins require two unpins before the key can be evicted."""
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 100)
+
+    ctrl.pin([k])
+    ctrl.pin([k])
+    assert ctrl.compute_eviction_plan() == {}
+
+    ctrl.unpin([k])
+    assert ctrl.compute_eviction_plan() == {}  # still pinned once
+
+    ctrl.unpin([k])
+    assert ctrl.compute_eviction_plan()["a"] == [k]
+
+
+def test_unpin_unknown_key_is_noop():
+    """Unpinning a key that was never pinned does not go negative."""
+    ctrl, _, ut = _setup(eviction_ratio=1.0)
+    k = _make_key("a")
+    _store(ctrl, ut, k, 100)
+
+    ctrl.unpin([_make_key("a", h="ff")])  # never pinned
+    assert ctrl.compute_eviction_plan()["a"] == [k]
diff --git a/tests/v1/mp_coordinator/test_health.py b/tests/v1/mp_coordinator/test_health.py
new file mode 100644
index 0000000..fb7551e
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_health.py
@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the health-check eviction logic."""
+
+# Standard
+import time
+
+# First Party
+from lmcache.v1.mp_coordinator.app import evict_stale
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry, MPInstance
+
+
+def _instance(instance_id: str, heartbeat: float) -> MPInstance:
+    return MPInstance(
+        instance_id=instance_id,
+        ip="127.0.0.1",
+        http_port=8080,
+        registration_time=heartbeat,
+        last_heartbeat_time=heartbeat,
+    )
+
+
+def test_evict_stale_removes_only_expired():
+    registry = InstanceRegistry()
+    now = time.monotonic()
+    registry.register(_instance("fresh", now))
+    registry.register(_instance("old", now - 100.0))
+
+    evicted = evict_stale(registry, instance_timeout=30.0)
+
+    assert evicted == ["old"]
+    assert registry.contains("fresh")
+    assert not registry.contains("old")
+
+
+def test_evict_stale_noop_when_all_fresh():
+    registry = InstanceRegistry()
+    registry.register(_instance("a", time.monotonic()))
+    assert evict_stale(registry, instance_timeout=30.0) == []
+    assert registry.contains("a")
diff --git a/tests/v1/mp_coordinator/test_integration.py b/tests/v1/mp_coordinator/test_integration.py
new file mode 100644
index 0000000..c948e63
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_integration.py
@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: Apache-2.0
+"""End-to-end test: a real uvicorn-served coordinator driven over HTTP.
+
+Exercises the REST API against a live server (real lifespan + sockets) the way
+an mp server will: register, heartbeat, deregister, with health-check eviction.
+"""
+
+# Standard
+import socket as _socket
+import threading
+import time
+
+# Third Party
+import requests
+import uvicorn
+
+# First Party
+from lmcache.v1.mp_coordinator.app import create_app
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+
+
+def _free_port() -> int:
+    s = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
+    s.bind(("127.0.0.1", 0))
+    port = s.getsockname()[1]
+    s.close()
+    return port
+
+
+def _wait_until_up(base_url: str, timeout: float = 5.0) -> None:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            if requests.get(f"{base_url}/healthz", timeout=0.5).status_code == 200:
+                return
+        except requests.RequestException:
+            time.sleep(0.05)
+    raise RuntimeError("coordinator did not come up")
+
+
+def _serve(config: MPCoordinatorConfig):
+    """Start the coordinator in a background thread; return (server, thread)."""
+    server = uvicorn.Server(
+        uvicorn.Config(
+            create_app(config), host=config.host, port=config.port, log_level="warning"
+        )
+    )
+    thread = threading.Thread(target=server.run, daemon=True)
+    thread.start()
+    return server, thread
+
+
+def test_register_heartbeat_deregister_over_real_http():
+    port = _free_port()
+    base = f"http://127.0.0.1:{port}"
+    config = MPCoordinatorConfig(host="127.0.0.1", port=port, health_check_interval=0.0)
+    server, thread = _serve(config)
+    try:
+        _wait_until_up(base)
+        body = {"instance_id": "i1", "ip": "127.0.0.1", "http_port": 9999}
+        assert (
+            requests.post(f"{base}/instances", json=body, timeout=2).status_code == 200
+        )
+
+        listed = requests.get(f"{base}/instances", timeout=2).json()["instances"]
+        assert [i["instance_id"] for i in listed] == ["i1"]
+
+        assert (
+            requests.put(f"{base}/instances/i1/heartbeat", timeout=2).status_code == 200
+        )
+        assert requests.delete(f"{base}/instances/i1", timeout=2).status_code == 204
+        assert requests.get(f"{base}/instances", timeout=2).json()["instances"] == []
+    finally:
+        server.should_exit = True
+        thread.join(timeout=5.0)
+
+
+def test_health_loop_evicts_stale_instance():
+    port = _free_port()
+    base = f"http://127.0.0.1:{port}"
+    # Fast loop + short timeout so a non-heartbeating instance is evicted quickly.
+    config = MPCoordinatorConfig(
+        host="127.0.0.1",
+        port=port,
+        instance_timeout=0.6,
+        health_check_interval=0.2,
+    )
+    server, thread = _serve(config)
+    try:
+        _wait_until_up(base)
+        body = {"instance_id": "ghost", "ip": "127.0.0.1", "http_port": 9999}
+        requests.post(f"{base}/instances", json=body, timeout=2)
+        assert requests.get(f"{base}/instances", timeout=2).json()["instances"]
+
+        # Never heartbeat -> the health loop evicts it within a couple seconds.
+        deadline = time.time() + 3.0
+        while time.time() < deadline:
+            if not requests.get(f"{base}/instances", timeout=2).json()["instances"]:
+                break
+            time.sleep(0.1)
+        assert requests.get(f"{base}/instances", timeout=2).json()["instances"] == []
+    finally:
+        server.should_exit = True
+        thread.join(timeout=5.0)
diff --git a/tests/v1/mp_coordinator/test_prefetch_manager.py b/tests/v1/mp_coordinator/test_prefetch_manager.py
new file mode 100644
index 0000000..e09eab4
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_prefetch_manager.py
@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator warm-prefetch manager (submit + status proxy)."""
+
+# Standard
+import json as _json
+import time
+
+# Third Party
+import httpx
+import pytest
+
+# First Party
+from lmcache.v1.mp_coordinator.cache_control.prefetch_manager import PrefetchManager
+from lmcache.v1.mp_coordinator.registry import MPInstance
+
+
+def _instance(instance_id: str, ip: str = "10.0.0.1", port: int = 8000) -> MPInstance:
+    now = time.time()
+    return MPInstance(
+        instance_id=instance_id,
+        ip=ip,
+        http_port=port,
+        registration_time=now,
+        last_heartbeat_time=now,
+    )
+
+
+@pytest.mark.asyncio
+async def test_submit_prefetch_posts_body_and_returns_reply():
+    """submit_prefetch POSTs /cache/prefetches with the token body and returns the
+    server's JSON reply verbatim."""
+    mgr = PrefetchManager()
+    target = _instance("mp-1", ip="10.0.0.7", port=8765)
+    captured: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["method"] = request.method
+        captured["url"] = str(request.url)
+        captured["json"] = (request.read() or b"").decode()
+        return httpx.Response(
+            202, json={"request_id": "abc", "chunks": 2, "status": "submitted"}
+        )
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+        result = await mgr.submit_prefetch(
+            target=target,
+            http_client=client,
+            model_name="m",
+            world_size=2,
+            token_ids=[1, 2, 3, 4],
+            cache_salt="alice",
+        )
+
+    assert captured["method"] == "POST"
+    assert captured["url"] == "http://10.0.0.7:8765/cache/prefetches"
+    assert _json.loads(captured["json"]) == {
+        "model_name": "m",
+        "world_size": 2,
+        "token_ids": [1, 2, 3, 4],
+        "cache_salt": "alice",
+    }
+    assert result == {"request_id": "abc", "chunks": 2, "status": "submitted"}
+
+
+@pytest.mark.asyncio
+async def test_submit_prefetch_raises_on_http_error():
+    """A non-2xx submit surfaces as an httpx error for the caller to map."""
+    mgr = PrefetchManager()
+    target = _instance("mp-1")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, json={"error": "boom"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+        with pytest.raises(httpx.HTTPError):
+            await mgr.submit_prefetch(
+                target=target,
+                http_client=client,
+                model_name="m",
+                world_size=1,
+                token_ids=[1, 2],
+                cache_salt="",
+            )
+
+
+@pytest.mark.asyncio
+async def test_get_status_proxies_code_and_body():
+    """get_status returns the server's (status_code, body) verbatim."""
+    mgr = PrefetchManager()
+    target = _instance("mp-1", ip="10.0.0.7", port=8765)
+    captured: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(
+            200, json={"status": "completed", "found_keys": 4, "total_keys": 4}
+        )
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+        code, body = await mgr.get_status(
+            target=target, http_client=client, request_id="abc"
+        )
+
+    assert captured["url"] == "http://10.0.0.7:8765/cache/prefetches/abc"
+    assert code == 200
+    assert body == {"status": "completed", "found_keys": 4, "total_keys": 4}
+
+
+@pytest.mark.asyncio
+async def test_get_status_relays_404():
+    """An unknown id on the server is relayed as a 404 (not raised)."""
+    mgr = PrefetchManager()
+    target = _instance("mp-1")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"detail": "unknown"})
+
+    async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+        code, body = await mgr.get_status(
+            target=target, http_client=client, request_id="x"
+        )
+
+    assert code == 404
+    assert body == {"detail": "unknown"}
diff --git a/tests/v1/mp_coordinator/test_quota_api.py b/tests/v1/mp_coordinator/test_quota_api.py
new file mode 100644
index 0000000..6eb96e2
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_quota_api.py
@@ -0,0 +1,368 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator ``/quota`` REST API (quota writes, combined
+quota+usage status, and usage-event ingestion)."""
+
+# Third Party
+from fastapi.testclient import TestClient
+
+# First Party
+from lmcache.v1.mp_coordinator.app import create_app
+from lmcache.v1.mp_coordinator.config import MPCoordinatorConfig
+
+
+def _client() -> TestClient:
+    config = MPCoordinatorConfig(health_check_interval=0.0, eviction_check_interval=0.0)
+    return TestClient(create_app(config))
+
+
+def _key(salt: str, h: str = "aa", model: str = "m", rank: int = 0) -> dict:
+    return {
+        "chunk_hash_hex": h,
+        "model_name": model,
+        "kv_rank": rank,
+        "cache_salt": salt,
+    }
+
+
+def _store(salt: str, nbytes: int, **kw) -> dict:
+    return {"type": "store", "key": _key(salt, **kw), "bytes": nbytes}
+
+
+def _lookup(salt: str, **kw) -> dict:
+    return {"type": "lookup", "key": _key(salt, **kw), "bytes": 0}
+
+
+def _delete(salt: str, **kw) -> dict:
+    return {"type": "delete", "key": _key(salt, **kw), "bytes": 0}
+
+
+_seq_counter = 0
+
+
+def _events_body(events: list[dict], instance_id: str = "test-server") -> dict:
+    global _seq_counter
+    _seq_counter += 1
+    return {"instance_id": instance_id, "seq": _seq_counter, "events": events}
+
+
+# -- Quota writes ------------------------------------------------------------
+
+
+def test_set_quota():
+    with _client() as client:
+        resp = client.put("/quota/user-a", json={"limit_gb": 2.5})
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["cache_salt"] == "user-a"
+        assert data["limit_gb"] == 2.5
+        assert data["status"] == "ok"
+
+
+def test_update_quota():
+    with _client() as client:
+        client.put("/quota/user-a", json={"limit_gb": 1.0})
+        client.put("/quota/user-a", json={"limit_gb": 5.0})
+        data = client.get("/quota/user-a").json()
+        assert abs(data["quota_limit_gb"] - 5.0) < 1e-6
+
+
+def test_delete_quota():
+    with _client() as client:
+        client.put("/quota/user-a", json={"limit_gb": 1.0})
+        resp = client.delete("/quota/user-a")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "removed"
+
+        data = client.get("/quota/user-a").json()
+        assert data["quota_exists"] is False
+
+
+def test_delete_nonexistent_quota():
+    with _client() as client:
+        resp = client.delete("/quota/unknown")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "not_found"
+
+
+def test_negative_limit_rejected():
+    with _client() as client:
+        resp = client.put("/quota/user-a", json={"limit_gb": -1.0})
+        assert resp.status_code == 422
+
+
+def test_missing_body_rejected():
+    with _client() as client:
+        resp = client.put("/quota/user-a")
+        assert resp.status_code == 422
+
+
+def test_zero_limit_accepted():
+    with _client() as client:
+        resp = client.put("/quota/user-a", json={"limit_gb": 0.0})
+        assert resp.status_code == 200
+        data = client.get("/quota/user-a").json()
+        assert data["quota_exists"] is True
+        assert data["quota_limit_gb"] == 0.0
+
+
+# -- Quota config (default limit for unquota'd salts) --------------------------
+
+
+def test_quota_config_defaults_to_null():
+    """Boot state: no default configured — unquota'd salts are exempt."""
+    with _client() as client:
+        resp = client.get("/quota/config")
+        assert resp.status_code == 200
+        assert resp.json() == {"default_limit_gb": None}
+
+
+def test_quota_config_set_and_read_back():
+    with _client() as client:
+        resp = client.put("/quota/config", json={"default_limit_gb": 0})
+        assert resp.status_code == 200
+        assert resp.json() == {"default_limit_gb": 0.0}
+        assert client.get("/quota/config").json() == {"default_limit_gb": 0.0}
+
+
+def test_quota_config_positive_value_round_trips():
+    with _client() as client:
+        client.put("/quota/config", json={"default_limit_gb": 2.5})
+        data = client.get("/quota/config").json()
+        assert abs(data["default_limit_gb"] - 2.5) < 1e-6
+
+
+def test_quota_config_resettable_to_null():
+    with _client() as client:
+        client.put("/quota/config", json={"default_limit_gb": 0})
+        resp = client.put("/quota/config", json={"default_limit_gb": None})
+        assert resp.status_code == 200
+        assert resp.json() == {"default_limit_gb": None}
+
+
+def test_quota_config_negative_rejected():
+    with _client() as client:
+        resp = client.put("/quota/config", json={"default_limit_gb": -1.0})
+        assert resp.status_code == 422
+
+
+def test_quota_config_path_not_captured_as_salt():
+    """``config`` is a fixed route, not a ``cache_salt`` — setting the
+    default must not create a quota entry named ``config``."""
+    with _client() as client:
+        client.put("/quota/config", json={"default_limit_gb": 1.0})
+        assert client.get("/quota/config").json() == {"default_limit_gb": 1.0}
+        salts = {e["cache_salt"] for e in client.get("/quota").json()["by_cache_salt"]}
+        assert "config" not in salts
+
+
+def test_quota_config_arms_unquotad_eviction_flow():
+    """End-to-end controller flow: unquota'd usage is exempt until the
+    default flips to 0, while explicit quotas work throughout."""
+    with _client() as client:
+        # Usage arrives for two tenants; only user-a gets a quota.
+        client.post(
+            "/quota/events",
+            json=_events_body(
+                [
+                    _store("user-a", 1000, h="01"),
+                    _store("user-b", 2000, h="02"),
+                ]
+            ),
+        )
+        client.put("/quota/user-a", json={"limit_gb": 10.0})
+
+        # Boot state: default null — user-b is exempt (nothing to assert
+        # via HTTP beyond config state; eviction-plan behavior is covered
+        # in test_eviction_manager.py).
+        assert client.get("/quota/config").json() == {"default_limit_gb": None}
+
+        # Controller arms allowlist enforcement.
+        resp = client.put("/quota/config", json={"default_limit_gb": 0})
+        assert resp.json() == {"default_limit_gb": 0.0}
+
+
+# -- Usage event ingestion ---------------------------------------------------
+
+
+def test_report_store_events():
+    with _client() as client:
+        resp = client.post(
+            "/quota/events",
+            json=_events_body(
+                [
+                    _store("user-a", 1000, h="01"),
+                    _store("user-a", 500, h="02"),
+                    _store("user-b", 2000, h="03"),
+                ]
+            ),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["recorded"] == 3
+
+        data = client.get("/quota/user-a").json()
+        assert abs(data["usage_gb"] - 1500 / 1024**3) < 1e-12
+
+        data = client.get("/quota/user-b").json()
+        assert abs(data["usage_gb"] - 2000 / 1024**3) < 1e-12
+
+
+def test_report_lookup_events_accepted():
+    with _client() as client:
+        resp = client.post(
+            "/quota/events",
+            json=_events_body([_lookup("user-a")]),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["recorded"] == 1
+
+
+def test_empty_events_batch():
+    with _client() as client:
+        resp = client.post(
+            "/quota/events",
+            json=_events_body([]),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["recorded"] == 0
+
+
+def test_invalid_event_type_rejected():
+    with _client() as client:
+        resp = client.post(
+            "/quota/events",
+            json=_events_body([{"type": "purge", "key": _key("a"), "bytes": 100}]),
+        )
+        assert resp.status_code == 422
+
+
+def test_delete_event_drops_key_from_tracking():
+    """A DELETE event subtracts the key's bytes from per-salt usage and
+    removes it from the eviction LRU. The keys' sizes come from the
+    earlier STORE events the usage manager has on file."""
+    with _client() as client:
+        # Seed two keys for "user-a".
+        client.post(
+            "/quota/events",
+            json=_events_body(
+                [
+                    _store("user-a", 1000, h="01"),
+                    _store("user-a", 500, h="02"),
+                ]
+            ),
+        )
+        data = client.get("/quota/user-a").json()
+        assert abs(data["usage_gb"] - 1500 / 1024**3) < 1e-12
+
+        # Delete one of them — usage shrinks by exactly that key's
+        # recorded size (1000), not the wire ``bytes=0``.
+        resp = client.post(
+            "/quota/events",
+            json=_events_body([_delete("user-a", h="01")]),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["recorded"] == 1
+
+        data = client.get("/quota/user-a").json()
+        assert abs(data["usage_gb"] - 500 / 1024**3) < 1e-12
+
+
+def test_delete_event_for_unknown_key_is_noop():
+    """A DELETE for a key the coordinator never saw a STORE for is
+    accepted but has no observable effect (no usage to subtract from)."""
+    with _client() as client:
+        resp = client.post(
+            "/quota/events",
+            json=_events_body([_delete("user-a", h="ff")]),
+        )
+        assert resp.status_code == 200
+        assert resp.json()["recorded"] == 1
+        data = client.get("/quota/user-a").json()
+        assert data["usage_gb"] == 0.0
+
+
+def test_negative_bytes_rejected():
+    with _client() as client:
+        resp = client.post(
+            "/quota/events",
+            json=_events_body([{"type": "store", "key": _key("a"), "bytes": -1}]),
+        )
+        assert resp.status_code == 422
+
+
+# -- Combined status queries -------------------------------------------------
+
+
+def test_status_single_salt():
+    with _client() as client:
+        client.put("/quota/user-a", json={"limit_gb": 2.5})
+        client.post(
+            "/quota/events",
+            json=_events_body([_store("user-a", 1000)]),
+        )
+        data = client.get("/quota/user-a").json()
+        assert data["cache_salt"] == "user-a"
+        assert abs(data["quota_limit_gb"] - 2.5) < 1e-6
+        assert data["quota_exists"] is True
+        assert abs(data["usage_gb"] - 1000 / 1024**3) < 1e-12
+
+
+def test_status_unknown_salt():
+    with _client() as client:
+        data = client.get("/quota/unknown").json()
+        assert data["usage_gb"] == 0.0
+        assert data["quota_exists"] is False
+        assert data["quota_limit_gb"] == 0.0
+
+
+def test_status_list():
+    with _client() as client:
+        client.put("/quota/a", json={"limit_gb": 1.0})
+        client.post(
+            "/quota/events",
+            json=_events_body(
+                [
+                    _store("a", 100, h="01"),
+                    _store("b", 200, h="02"),
+                ]
+            ),
+        )
+        data = client.get("/quota").json()
+        assert abs(data["total_gb"] - 300 / 1024**3) < 1e-12
+        by_salt = {e["cache_salt"]: e for e in data["by_cache_salt"]}
+        assert abs(by_salt["a"]["usage_gb"] - 100 / 1024**3) < 1e-12
+        assert by_salt["a"]["quota_exists"] is True
+        assert abs(by_salt["b"]["usage_gb"] - 200 / 1024**3) < 1e-12
+        assert by_salt["b"]["quota_exists"] is False
+
+
+def test_status_list_empty():
+    with _client() as client:
+        data = client.get("/quota").json()
+        assert data["total_gb"] == 0.0
+        assert data["by_cache_salt"] == []
+
+
+def test_status_list_includes_quota_only_salt():
+    """A salt with a quota but no usage should appear in the list."""
+    with _client() as client:
+        client.put("/quota/q-only", json={"limit_gb": 5.0})
+        data = client.get("/quota").json()
+        by_salt = {e["cache_salt"]: e for e in data["by_cache_salt"]}
+        assert "q-only" in by_salt
+        assert by_salt["q-only"]["quota_exists"] is True
+        assert by_salt["q-only"]["usage_gb"] == 0.0
+
+
+def test_default_salt_sentinel():
+    """``_default`` in path maps to the empty-string salt."""
+    with _client() as client:
+        client.put("/quota/_default", json={"limit_gb": 3.0})
+        client.post(
+            "/quota/events",
+            json=_events_body([_store("", 500)]),
+        )
+        data = client.get("/quota/_default").json()
+        assert data["cache_salt"] == ""
+        assert data["quota_exists"] is True
+        assert abs(data["quota_limit_gb"] - 3.0) < 1e-6
+        assert abs(data["usage_gb"] - 500 / 1024**3) < 1e-12
diff --git a/tests/v1/mp_coordinator/test_registrar.py b/tests/v1/mp_coordinator/test_registrar.py
new file mode 100644
index 0000000..42e137b
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_registrar.py
@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the mp-side coordinator registration helpers.
+
+Driven with an httpx MockTransport (no real I/O): register, the keep_registered
+loop (heartbeat, re-register on 404, deregister on cancel), and resilience when
+the coordinator is unreachable.
+"""
+
+# Standard
+import asyncio
+import contextlib
+
+# Third Party
+import httpx
+
+# First Party
+from lmcache.v1.mp_coordinator.registrar import keep_registered, register
+
+_BASE = "http://coord:9300"
+
+
+def _client(handler) -> httpx.AsyncClient:
+    return httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+
+def test_register_returns_assigned_id():
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST":
+            assert request.url.path == "/instances"
+            return httpx.Response(
+                200, json={"instance_id": "mp-xyz", "re_registered": False}
+            )
+        return httpx.Response(204)
+
+    async def run():
+        async with _client(handler) as client:
+            assigned = await register(
+                client, _BASE, http_port=8080, advertise_ip="127.0.0.1"
+            )
+            assert assigned == "mp-xyz"
+
+    asyncio.run(run())
+
+
+def test_register_forwards_p2p_and_mq_fields():
+    captured: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        # Standard
+        import json
+
+        captured.update(json.loads(request.content))
+        return httpx.Response(200, json={"instance_id": "i1", "re_registered": False})
+
+    async def run():
+        async with _client(handler) as client:
+            await register(
+                client,
+                _BASE,
+                http_port=8080,
+                advertise_ip="10.0.0.1",
+                instance_id="i1",
+                p2p_advertised_url="10.0.0.1:7600",
+                mq_port=5555,
+            )
+
+    asyncio.run(run())
+    # The MQ server is reachable at the same advertised ip, so no separate
+    # mq_ip is sent -- only the port.
+    assert captured["ip"] == "10.0.0.1"
+    assert captured["p2p_advertised_url"] == "10.0.0.1:7600"
+    assert captured["mq_port"] == 5555
+
+
+def test_register_omits_mq_port_when_p2p_disabled():
+    captured: dict = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        # Standard
+        import json
+
+        captured.update(json.loads(request.content))
+        return httpx.Response(200, json={"instance_id": "i1", "re_registered": False})
+
+    async def run():
+        async with _client(handler) as client:
+            await register(client, _BASE, http_port=8080, advertise_ip="10.0.0.1")
+
+    asyncio.run(run())
+    assert captured["mq_port"] == 0
+
+
+async def _run_loop_briefly(client: httpx.AsyncClient, **kwargs) -> None:
+    """Run keep_registered for a few ticks, then cancel it."""
+    task = asyncio.create_task(
+        keep_registered(
+            client,
+            _BASE,
+            http_port=8080,
+            advertise_ip="127.0.0.1",
+            heartbeat_interval=0.03,
+            **kwargs,
+        )
+    )
+    await asyncio.sleep(0.12)
+    task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await task
+
+
+def test_keep_registered_heartbeats_then_deregisters():
+    seen = {"heartbeats": 0, "delete_path": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST":
+            return httpx.Response(
+                200, json={"instance_id": "i1", "re_registered": False}
+            )
+        if request.method == "PUT":
+            seen["heartbeats"] += 1
+            return httpx.Response(200, json={"instance_id": "i1"})
+        seen["delete_path"] = request.url.path  # DELETE on cancel
+        return httpx.Response(204)
+
+    async def run():
+        async with _client(handler) as client:
+            await _run_loop_briefly(client, instance_id="i1")
+
+    asyncio.run(run())
+    assert seen["heartbeats"] >= 1
+    assert seen["delete_path"] == "/instances/i1"
+
+
+def test_keep_registered_reregisters_on_404():
+    calls = {"register": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST":
+            calls["register"] += 1
+            return httpx.Response(
+                200, json={"instance_id": "i1", "re_registered": False}
+            )
+        if request.method == "PUT":
+            return httpx.Response(404, json={"error": "unknown"})
+        return httpx.Response(204)
+
+    async def run():
+        async with _client(handler) as client:
+            await _run_loop_briefly(client, instance_id="i1")
+
+    asyncio.run(run())
+    assert calls["register"] >= 2  # initial + at least one re-register after 404
+
+
+def test_keep_registered_keeps_id_on_transient_heartbeat_failure():
+    seen = {"register": 0, "delete_path": None}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.method == "POST":
+            seen["register"] += 1
+            return httpx.Response(
+                200, json={"instance_id": "i1", "re_registered": False}
+            )
+        if request.method == "PUT":
+            return httpx.Response(500, json={"error": "transient"})
+        seen["delete_path"] = request.url.path
+        return httpx.Response(204)
+
+    async def run():
+        async with _client(handler) as client:
+            await _run_loop_briefly(client, instance_id="i1")
+
+    asyncio.run(run())
+    # Transient 5xx must NOT spawn a duplicate registration, and the id is
+    # kept so shutdown can still deregister.
+    assert seen["register"] == 1
+    assert seen["delete_path"] == "/instances/i1"
+
+
+def test_keep_registered_survives_malformed_response():
+    def handler(request: httpx.Request) -> httpx.Response:
+        # 200 with a schema-mismatched body -> RegisterResponse validation fails.
+        return httpx.Response(200, json={"unexpected": "field"})
+
+    async def run():
+        async with _client(handler) as client:
+            task = asyncio.create_task(
+                keep_registered(
+                    client,
+                    _BASE,
+                    http_port=8080,
+                    advertise_ip="127.0.0.1",
+                    heartbeat_interval=0.03,
+                )
+            )
+            await asyncio.sleep(0.1)
+            assert not task.done()  # validation error did not kill the task
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+    asyncio.run(run())
+
+
+def test_keep_registered_survives_unreachable_coordinator():
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("coordinator down")
+
+    async def run():
+        async with _client(handler) as client:
+            task = asyncio.create_task(
+                keep_registered(
+                    client,
+                    _BASE,
+                    http_port=8080,
+                    advertise_ip="127.0.0.1",
+                    heartbeat_interval=0.03,
+                )
+            )
+            await asyncio.sleep(0.1)
+            assert not task.done()  # kept retrying, did not crash
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+
+    asyncio.run(run())
diff --git a/tests/v1/mp_coordinator/test_registry.py b/tests/v1/mp_coordinator/test_registry.py
new file mode 100644
index 0000000..67d50ac
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_registry.py
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the mp coordinator instance registry."""
+
+# Standard
+import time
+
+# First Party
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry, MPInstance
+
+
+def _instance(instance_id: str, heartbeat: float = 0.0) -> MPInstance:
+    """Build a pure-membership MPInstance for tests."""
+    now = heartbeat or time.time()
+    return MPInstance(
+        instance_id=instance_id,
+        ip="127.0.0.1",
+        http_port=8080,
+        registration_time=now,
+        last_heartbeat_time=now,
+    )
+
+
+def test_register_and_get():
+    registry = InstanceRegistry()
+    instance = _instance("a")
+    registry.register(instance)
+    assert registry.contains("a")
+    assert registry.get("a") is instance
+    assert registry.get("missing") is None
+
+
+def test_register_returns_replaced_flag():
+    registry = InstanceRegistry()
+    assert registry.register(_instance("a")) is False
+    assert registry.register(_instance("a")) is True
+
+
+def test_deregister_returns_instance():
+    registry = InstanceRegistry()
+    instance = _instance("a")
+    registry.register(instance)
+    removed = registry.deregister("a")
+    assert removed is instance
+    assert not registry.contains("a")
+    assert registry.deregister("a") is None
+
+
+def test_all_instances_snapshot_is_independent():
+    registry = InstanceRegistry()
+    registry.register(_instance("a"))
+    registry.register(_instance("b"))
+    snapshot = registry.all_instances()
+    assert {n.instance_id for n in snapshot} == {"a", "b"}
+    registry.deregister("a")
+    # Snapshot taken earlier is unaffected by later mutation.
+    assert {n.instance_id for n in snapshot} == {"a", "b"}
+
+
+def test_update_heartbeat():
+    registry = InstanceRegistry()
+    instance = _instance("a", heartbeat=100.0)
+    registry.register(instance)
+    assert registry.update_heartbeat("a", 200.0) is True
+    assert registry.get("a").last_heartbeat_time == 200.0
+    # Unknown instance signals a needed re-register.
+    assert registry.update_heartbeat("missing", 300.0) is False
+
+
+def test_stale_detects_expired():
+    registry = InstanceRegistry()
+    # stale() compares against the monotonic clock, so seed heartbeat times
+    # from the same clock.
+    now = time.monotonic()
+    registry.register(_instance("fresh", heartbeat=now))
+    registry.register(_instance("old", heartbeat=now - 100.0))
+    stale = registry.stale(timeout=30.0)
+    assert stale == ["old"]
+
+
+def test_random_instance_empty_returns_none():
+    registry = InstanceRegistry()
+    assert registry.random_instance() is None
+
+
+def test_random_instance_single_is_deterministic():
+    registry = InstanceRegistry()
+    inst = _instance("only")
+    registry.register(inst)
+    # Sampling a 1-element population is deterministic.
+    assert registry.random_instance() is inst
+
+
+def test_random_instance_samples_from_live_set():
+    # Standard
+    import random as _random
+
+    registry = InstanceRegistry()
+    for letter in "abc":
+        registry.register(_instance(letter))
+    # Deterministic seed → reproducible assertion that random_instance
+    # actually samples from the registered set (and only it).
+    _random.seed(7)
+    seen = {registry.random_instance().instance_id for _ in range(50)}
+    assert seen <= {"a", "b", "c"}
+    # With 50 picks across 3 items the chance of missing one is
+    # (2/3)**50 ≈ 1.6e-9 — close enough to "covers the set" for
+    # a sanity test with a fixed seed.
+    assert seen == {"a", "b", "c"}
diff --git a/tests/v1/mp_coordinator/test_resync_manager.py b/tests/v1/mp_coordinator/test_resync_manager.py
new file mode 100644
index 0000000..9d2fc5b
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_resync_manager.py
@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator L2 resync manager."""
+
+# Standard
+import time
+
+# Third Party
+import httpx
+import pytest
+
+# First Party
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.mp_coordinator.cache_control.eviction_manager import L2EvictionManager
+from lmcache.v1.mp_coordinator.cache_control.resync_manager import L2ResyncManager
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+from lmcache.v1.mp_coordinator.registry import InstanceRegistry, MPInstance
+
+
+def _make_components() -> tuple[L2UsageManager, L2EvictionManager, L2ResyncManager]:
+    usage = L2UsageManager()
+    eviction = L2EvictionManager(QuotaManager(), usage, eviction_ratio=1.0)
+    resync = L2ResyncManager(usage, eviction, page_size=2)
+    return usage, eviction, resync
+
+
+def _instance(instance_id: str = "mp-1") -> MPInstance:
+    now = time.time()
+    return MPInstance(
+        instance_id=instance_id,
+        ip="10.0.0.1",
+        http_port=8000,
+        registration_time=now,
+        last_heartbeat_time=now,
+    )
+
+
+def _entry(
+    *,
+    chunk_hash_hex: str = "aa",
+    model_name: str = "llama",
+    kv_rank: int = 0,
+    object_group_id: int = 0,
+    cache_salt: str = "alice",
+    size_bytes: int = 100,
+) -> dict[str, object]:
+    """Wire shape of one ``KeyListPage`` entry: nested ``key`` plus
+    a sibling ``size_bytes``."""
+    return {
+        "key": {
+            "chunk_hash_hex": chunk_hash_hex,
+            "model_name": model_name,
+            "kv_rank": kv_rank,
+            "object_group_id": object_group_id,
+            "cache_salt": cache_salt,
+        },
+        "size_bytes": size_bytes,
+    }
+
+
+# =============================================================================
+# resync_from — single instance, paginated walk
+# =============================================================================
+
+
+class TestResyncFrom:
+    @pytest.mark.asyncio
+    async def test_single_page_records_all_entries(self):
+        usage, eviction, resync = _make_components()
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            assert str(request.url) == "http://10.0.0.1:8000/cache/objects?page_size=2"
+            return httpx.Response(
+                200,
+                json={
+                    "entries": [
+                        _entry(chunk_hash_hex="aa", size_bytes=100),
+                        _entry(chunk_hash_hex="bb", size_bytes=200),
+                    ],
+                    "next_page_token": None,
+                },
+            )
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+            total = await resync.resync_from(_instance(), client)
+
+        assert total == 2
+        # Usage manager aggregated bytes per cache_salt.
+        assert usage.get("alice") == 300
+        # Eviction manager registered both keys — confirmed by
+        # synthesizing an eviction (no quota ⇒ ratio=1.0 full sweep).
+        eviction._quota_manager.set_quota("alice", 0)
+        plan = eviction.compute_eviction_plan()
+        assert len(plan.get("alice", [])) == 2
+
+    @pytest.mark.asyncio
+    async def test_paginates_through_continuation_tokens(self):
+        usage, _eviction, resync = _make_components()
+
+        pages = [
+            {
+                "entries": [_entry(chunk_hash_hex="aa", size_bytes=10)],
+                "next_page_token": "T1",
+            },
+            {
+                "entries": [_entry(chunk_hash_hex="bb", size_bytes=20)],
+                "next_page_token": "T2",
+            },
+            {
+                "entries": [_entry(chunk_hash_hex="cc", size_bytes=30)],
+                "next_page_token": None,
+            },
+        ]
+        seen_tokens: list[str | None] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            token = request.url.params.get("page_token")
+            seen_tokens.append(token)
+            return httpx.Response(200, json=pages.pop(0))
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+            total = await resync.resync_from(_instance(), client)
+
+        assert total == 3
+        # First page sends no token, follow-ups forward the previous
+        # next_page_token verbatim.
+        assert seen_tokens == [None, "T1", "T2"]
+        assert usage.get("alice") == 60
+
+    @pytest.mark.asyncio
+    async def test_http_failure_stops_early_returns_partial_count(self):
+        usage, _eviction, resync = _make_components()
+
+        call_count = {"n": 0}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            call_count["n"] += 1
+            if call_count["n"] == 1:
+                return httpx.Response(
+                    200,
+                    json={
+                        "entries": [_entry(chunk_hash_hex="aa", size_bytes=10)],
+                        "next_page_token": "T1",
+                    },
+                )
+            return httpx.Response(503, json={"error": "down"})
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+            total = await resync.resync_from(_instance(), client)
+
+        # First page succeeded; second failed.
+        assert total == 1
+        assert usage.get("alice") == 10
+
+    @pytest.mark.asyncio
+    async def test_malformed_entries_skipped(self):
+        usage, _eviction, resync = _make_components()
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                200,
+                json={
+                    "entries": [
+                        # Bad: ``@`` in model_name violates ObjectKey
+                        # invariant → skipped.
+                        _entry(model_name="bad@name", size_bytes=99),
+                        # Bad: non-hex chunk_hash_hex → skipped.
+                        _entry(chunk_hash_hex="not-hex", size_bytes=99),
+                        # Bad: missing ``key`` field → skipped.
+                        {"size_bytes": 99},
+                        # Bad: missing ``size_bytes`` → skipped.
+                        {
+                            "key": {
+                                "chunk_hash_hex": "aa",
+                                "model_name": "m",
+                                "kv_rank": 0,
+                            }
+                        },
+                        # Good.
+                        _entry(chunk_hash_hex="aa", size_bytes=50),
+                    ],
+                    "next_page_token": None,
+                },
+            )
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+            total = await resync.resync_from(_instance(), client)
+
+        assert total == 1
+        assert usage.get("alice") == 50
+
+    @pytest.mark.asyncio
+    async def test_constructor_rejects_non_positive_page_size(self):
+        usage = L2UsageManager()
+        eviction = L2EvictionManager(QuotaManager(), usage)
+        with pytest.raises(ValueError):
+            L2ResyncManager(usage, eviction, page_size=0)
+
+
+# =============================================================================
+# wait_and_resync — registry polling
+# =============================================================================
+
+
+class TestWaitAndResync:
+    @pytest.mark.asyncio
+    async def test_returns_zero_when_no_instance_within_max_wait(self):
+        _usage, _eviction, resync = _make_components()
+        registry = InstanceRegistry()
+
+        # ``poll_interval`` and ``max_wait`` are both small enough that
+        # the test finishes well under a second.
+        async with httpx.AsyncClient(
+            transport=httpx.MockTransport(
+                lambda r: pytest.fail("HTTP must not be called")  # type: ignore[arg-type]
+            )
+        ) as client:
+            total = await resync.wait_and_resync(
+                registry=registry,
+                http_client=client,
+                poll_interval=0.05,
+                max_wait=0.2,
+            )
+
+        assert total == 0
+
+    @pytest.mark.asyncio
+    async def test_resyncs_against_first_registered_instance(self):
+        usage, _eviction, resync = _make_components()
+        registry = InstanceRegistry()
+        registry.register(_instance("mp-1"))
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(
+                200,
+                json={
+                    "entries": [_entry(chunk_hash_hex="aa", size_bytes=25)],
+                    "next_page_token": None,
+                },
+            )
+
+        async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as client:
+            total = await resync.wait_and_resync(
+                registry=registry,
+                http_client=client,
+                poll_interval=0.05,
+                max_wait=1.0,
+            )
+
+        assert total == 1
+        assert usage.get("alice") == 25
diff --git a/tests/v1/mp_coordinator/test_usage_manager.py b/tests/v1/mp_coordinator/test_usage_manager.py
new file mode 100644
index 0000000..227161a
--- /dev/null
+++ b/tests/v1/mp_coordinator/test_usage_manager.py
@@ -0,0 +1,175 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the coordinator L2UsageManager."""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.mp_coordinator.cache_control.usage_manager import L2UsageManager
+
+
+def _key(chunk: int = 0, salt: str = "a") -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=chunk.to_bytes(4, "big"),
+        model_name="m",
+        kv_rank=0,
+        cache_salt=salt,
+    )
+
+
+# =============================================================================
+# record_stored — basic accumulation
+# =============================================================================
+
+
+def test_record_stored_basic():
+    t = L2UsageManager()
+    t.record_stored(_key(0, salt="a"), 100)
+    assert t.get("a") == 100
+    assert t.get_total() == 100
+    assert t.has_key(_key(0, salt="a"))
+
+
+def test_record_stored_distinct_keys_accumulate():
+    t = L2UsageManager()
+    t.record_stored(_key(0, salt="a"), 100)
+    t.record_stored(_key(1, salt="a"), 200)
+    assert t.get("a") == 300
+    assert t.get_total() == 300
+
+
+# =============================================================================
+# record_stored — replace-on-existing (the new contract)
+# =============================================================================
+
+
+def test_record_stored_same_key_same_size_is_idempotent():
+    t = L2UsageManager()
+    k = _key(0, salt="a")
+    t.record_stored(k, 100)
+    t.record_stored(k, 100)
+    # Stored twice, but the per-salt total stays at 100 — no
+    # double-counting.
+    assert t.get("a") == 100
+    assert t.get_total() == 100
+
+
+def test_record_stored_same_key_new_size_replaces():
+    t = L2UsageManager()
+    k = _key(0, salt="a")
+    t.record_stored(k, 100)
+    t.record_stored(k, 250)
+    # New size replaces the old one; delta (+150) lands on the total.
+    assert t.get_key_size(k) == 250
+    assert t.get("a") == 250
+    assert t.get_total() == 250
+
+
+def test_record_stored_shrink_adjusts_down():
+    t = L2UsageManager()
+    k = _key(0, salt="a")
+    t.record_stored(k, 100)
+    t.record_stored(k, 40)
+    assert t.get("a") == 40
+    assert t.get_total() == 40
+
+
+# =============================================================================
+# record_evicted — key-aware
+# =============================================================================
+
+
+def test_record_evicted_returns_freed_bytes():
+    t = L2UsageManager()
+    k = _key(0, salt="a")
+    t.record_stored(k, 100)
+    assert t.record_evicted(k) == 100
+    assert t.get("a") == 0
+    assert t.get_total() == 0
+    assert not t.has_key(k)
+
+
+def test_record_evicted_unknown_key_returns_zero():
+    t = L2UsageManager()
+    assert t.record_evicted(_key(99, salt="z")) == 0
+
+
+def test_record_evicted_removes_zero_entry():
+    t = L2UsageManager()
+    k = _key(0, salt="a")
+    t.record_stored(k, 100)
+    t.record_evicted(k)
+    assert t.get_all() == {}
+
+
+def test_record_evicted_partial_when_multiple_keys():
+    t = L2UsageManager()
+    t.record_stored(_key(0, salt="a"), 100)
+    t.record_stored(_key(1, salt="a"), 200)
+    t.record_evicted(_key(0, salt="a"))
+    # Bucket only loses the evicted key's bytes.
+    assert t.get("a") == 200
+    assert t.get_total() == 200
+
+
+# =============================================================================
+# Existence query
+# =============================================================================
+
+
+def test_has_key_returns_false_for_unknown():
+    t = L2UsageManager()
+    assert not t.has_key(_key(0))
+
+
+def test_get_key_size_returns_none_for_unknown():
+    t = L2UsageManager()
+    assert t.get_key_size(_key(0)) is None
+
+
+# =============================================================================
+# Multi-salt + zero / negative
+# =============================================================================
+
+
+def test_multiple_salts():
+    t = L2UsageManager()
+    t.record_stored(_key(0, salt="a"), 100)
+    t.record_stored(_key(0, salt="b"), 200)
+    assert t.get("a") == 100
+    assert t.get("b") == 200
+    assert t.get_total() == 300
+
+
+def test_get_unknown_returns_zero():
+    t = L2UsageManager()
+    assert t.get("unknown") == 0
+
+
+def test_get_all():
+    t = L2UsageManager()
+    t.record_stored(_key(0, salt="a"), 100)
+    t.record_stored(_key(0, salt="b"), 200)
+    assert t.get_all() == {"a": 100, "b": 200}
+
+
+def test_get_all_empty():
+    t = L2UsageManager()
+    assert t.get_all() == {}
+
+
+def test_zero_bytes_stores_entry_without_changing_total():
+    t = L2UsageManager()
+    k = _key(0, salt="a")
+    t.record_stored(k, 0)
+    # The key is now tracked at size 0; the per-salt total doesn't move.
+    assert t.has_key(k)
+    assert t.get("a") == 0
+    assert t.get_total() == 0
+
+
+def test_negative_store_raises():
+    t = L2UsageManager()
+    with pytest.raises(ValueError, match="non-negative"):
+        t.record_stored(_key(0), -1)
diff --git a/tests/v1/mp_observability/subscribers/__init__.py b/tests/v1/mp_observability/subscribers/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/mp_observability/subscribers/logging/__init__.py b/tests/v1/mp_observability/subscribers/logging/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/logging/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/mp_observability/subscribers/logging/test_cb_server.py b/tests/v1/mp_observability/subscribers/logging/test_cb_server.py
new file mode 100644
index 0000000..147ccb6
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/logging/test_cb_server.py
@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for BlendLoggingSubscriber."""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.logging.cb_server import (
+    BlendLoggingSubscriber,
+)
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = BlendLoggingSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+class TestBlendLoggingSubscriber:
+    def test_subscriptions_cover_all_cb_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.CB_LOOKUP_START in subs
+        assert EventType.CB_LOOKUP_END in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_START in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_END in subs
+        assert EventType.CB_RETRIEVE_START in subs
+        assert EventType.CB_RETRIEVE_END in subs
+        assert EventType.CB_STORE_FINAL_START in subs
+        assert EventType.CB_STORE_FINAL_END in subs
+        assert EventType.CB_FINGERPRINTS_REGISTERED in subs
+        assert EventType.CB_CHUNKS_EVICTED in subs
+
+    def test_no_subscription_for_lifecycle_sentinels(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.CB_REQUEST_START not in subs
+        assert EventType.CB_REQUEST_END not in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_SUBMITTED not in subs
+        assert EventType.CB_RETRIEVE_SUBMITTED not in subs
+        assert EventType.CB_STORE_FINAL_SUBMITTED not in subs
+
+    def test_lookup_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id="req-1",
+                metadata={"num_tokens": 128},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_lookup_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-1",
+                metadata={
+                    "num_tokens": 128,
+                    "fingerprint_hits": 4,
+                    "storage_hits": 3,
+                    "stale_chunks": 1,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_pre_computed_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id="req-2",
+                metadata={"instance_id": 0, "num_tokens": 64},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_pre_computed_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id="req-2",
+                metadata={
+                    "instance_id": 0,
+                    "num_tokens": 64,
+                    "stored_chunks": 4,
+                    "success": True,
+                },
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_retrieve_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_START,
+                session_id="req-3",
+                metadata={"instance_id": 1, "num_chunks": 3},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_retrieve_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id="req-3",
+                metadata={"instance_id": 1, "num_chunks": 3, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_final_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_START,
+                session_id="req-4",
+                metadata={"instance_id": 2, "num_tokens": 512},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_final_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_END,
+                session_id="req-4",
+                metadata={
+                    "instance_id": 2,
+                    "num_tokens": 512,
+                    "stored_chunks": 32,
+                    "success": True,
+                },
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_fingerprints_registered_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_FINGERPRINTS_REGISTERED,
+                session_id="req-5",
+                metadata={"num_chunks": 8, "num_tokens": 256},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_chunks_evicted_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_CHUNKS_EVICTED,
+                session_id="req-5",
+                metadata={"num_chunks": 2},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_multiple_events_no_crash(self, bus, subscriber):
+        bus.start()
+        for i in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_START,
+                    session_id=f"req-{i}",
+                    metadata={"num_tokens": 100},
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id=f"req-{i}",
+                    metadata={
+                        "num_tokens": 100,
+                        "fingerprint_hits": 2,
+                        "storage_hits": 2,
+                        "stale_chunks": 0,
+                        "no_gpu_context": False,
+                    },
+                )
+            )
+        time.sleep(0.15)
+        bus.stop()
diff --git a/tests/v1/mp_observability/subscribers/logging/test_lookup_hash_logger.py b/tests/v1/mp_observability/subscribers/logging/test_lookup_hash_logger.py
new file mode 100644
index 0000000..d402cfa
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/logging/test_lookup_hash_logger.py
@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for LookupHashLoggingSubscriber and LookupHashLogConfig."""
+
+# Standard
+from pathlib import Path
+import json
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.logging.lookup_hash import (
+    LookupHashLogConfig,
+    LookupHashLoggingSubscriber,
+    _format_timestamp,
+)
+
+
+class TestLookupHashLogConfig:
+    def test_disabled_by_default(self) -> None:
+        config = LookupHashLogConfig()
+        assert not config.enabled
+        assert config.output_dir == ""
+
+    def test_enabled_when_output_dir_set(self) -> None:
+        config = LookupHashLogConfig(output_dir="/tmp/test")
+        assert config.enabled
+
+    def test_defaults(self) -> None:
+        config = LookupHashLogConfig()
+        assert config.rotation_interval_sec == 6 * 3600
+        assert config.rotation_max_size == 100 * 1024 * 1024
+        assert config.max_files == 100
+
+
+class TestFormatTimestamp:
+    def test_known_timestamp(self) -> None:
+        # 2026-04-01 14:30:25 UTC
+        ts = 1775053825.0
+        result = _format_timestamp(ts)
+        assert result == "20260401_143025"
+
+    def test_returns_string(self) -> None:
+        result = _format_timestamp(time.time())
+        assert isinstance(result, str)
+        assert len(result) == 15  # YYYYMMDD_HHMMSS
+
+
+def _make_event(
+    request_id: str = "req-001",
+    chunk_hashes: list | None = None,
+    model_name: str = "test-model",
+    chunk_size: int = 256,
+    seq_len: int = 1024,
+    dtypes: list[str] | None = None,
+    shapes: list | None = None,
+) -> Event:
+    """Helper to create a lookup event with metadata."""
+    return Event(
+        event_type=EventType.MP_LOOKUP,
+        session_id=request_id,
+        metadata={
+            "request_id": request_id,
+            "chunk_hashes": chunk_hashes or [b"\xab\xcd"],
+            "model_name": model_name,
+            "chunk_size": chunk_size,
+            "seq_len": seq_len,
+            "dtypes": dtypes or [],
+            "shapes": shapes or [],
+        },
+    )
+
+
+def _publish_and_drain(bus: EventBus, event: Event) -> None:
+    """Publish an event and synchronously drain it."""
+    bus.publish(event)
+    bus._drain_all()
+
+
+class TestLookupHashLoggingSubscriber:
+    @pytest.fixture
+    def log_dir(self, tmp_path: Path) -> Path:
+        """Provide a temporary log directory."""
+        return tmp_path / "lookup_hashes"
+
+    @pytest.fixture
+    def config(self, log_dir: Path) -> LookupHashLogConfig:
+        """Provide a config with small limits for testing."""
+        return LookupHashLogConfig(
+            output_dir=str(log_dir),
+            rotation_interval_sec=3600,
+            rotation_max_size=100 * 1024 * 1024,
+            max_files=100,
+        )
+
+    @pytest.fixture
+    def bus(self) -> EventBus:
+        """Create an EventBus (no background thread — we drain manually)."""
+        return EventBus(EventBusConfig(enabled=True))
+
+    def test_creates_output_dir(self, config: LookupHashLogConfig) -> None:
+        sub = LookupHashLoggingSubscriber(config)
+        assert Path(config.output_dir).is_dir()
+        sub.shutdown()
+
+    def test_log_and_shutdown_writes_file(
+        self,
+        config: LookupHashLogConfig,
+        log_dir: Path,
+        bus: EventBus,
+    ) -> None:
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        event = _make_event(
+            chunk_hashes=[b"\xab\xcd", b"\x12\x34"],
+        )
+        _publish_and_drain(bus, event)
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        assert len(files) == 1
+
+        lines = files[0].read_text(encoding="utf-8").strip().split("\n")
+        assert len(lines) == 1
+
+        data = json.loads(lines[0])
+        assert data["request_id"] == "req-001"
+        assert data["model_name"] == "test-model"
+        assert data["chunk_hashes"] == ["0xabcd", "0x1234"]
+        assert "timestamp" in data
+
+    def test_multiple_entries(
+        self,
+        config: LookupHashLogConfig,
+        log_dir: Path,
+        bus: EventBus,
+    ) -> None:
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        for i in range(10):
+            event = _make_event(
+                request_id=f"req-{i:03d}",
+                chunk_hashes=[b"\xaa"],
+                model_name=f"model-{i}",
+            )
+            _publish_and_drain(bus, event)
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        assert len(files) == 1
+
+        lines = files[0].read_text(encoding="utf-8").strip().split("\n")
+        assert len(lines) == 10
+
+    def test_disabled_config_not_enabled(self) -> None:
+        config = LookupHashLogConfig()  # output_dir=""
+        assert not config.enabled
+        # Just verify the config property works; init_observability
+        # checks config.enabled before creating the subscriber.
+
+    def test_shutdown_is_idempotent(
+        self,
+        config: LookupHashLogConfig,
+        bus: EventBus,
+    ) -> None:
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        _publish_and_drain(
+            bus,
+            _make_event(chunk_hashes=[b"\xaa"]),
+        )
+        sub.shutdown()
+        # Second shutdown should not raise
+        sub.shutdown()
+
+    def test_size_based_rotation(self, log_dir: Path, bus: EventBus) -> None:
+        config = LookupHashLogConfig(
+            output_dir=str(log_dir),
+            rotation_interval_sec=999999,  # won't trigger
+            rotation_max_size=200,  # very small, triggers quickly
+            max_files=100,
+        )
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        for i in range(20):
+            _publish_and_drain(
+                bus,
+                _make_event(
+                    request_id=f"req-{i:03d}",
+                    chunk_hashes=[b"\xaa\xbb\xcc\xdd"],
+                ),
+            )
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        assert len(files) > 1, "Should have rotated due to size"
+
+    def test_max_files_limit(self, log_dir: Path, bus: EventBus) -> None:
+        config = LookupHashLogConfig(
+            output_dir=str(log_dir),
+            rotation_interval_sec=999999,
+            rotation_max_size=50,  # tiny, forces many rotations
+            max_files=3,
+        )
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        for i in range(30):
+            _publish_and_drain(
+                bus,
+                _make_event(
+                    request_id=f"req-{i:03d}",
+                    chunk_hashes=[b"\xaa\xbb\xcc\xdd"],
+                ),
+            )
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        assert len(files) <= 3
+
+    def test_existing_files_discovered_on_init(
+        self, log_dir: Path, bus: EventBus
+    ) -> None:
+        """Files from previous runs are counted toward max_files."""
+        log_dir.mkdir(parents=True, exist_ok=True)
+        # Create 3 pre-existing files
+        for i in range(3):
+            f = log_dir / f"lookup_hashes_20260101_000000_{i:06d}.jsonl"
+            f.write_text("{}\n", encoding="utf-8")
+            # Stagger mtime so sorting is deterministic
+            time.sleep(0.01)
+
+        config = LookupHashLogConfig(
+            output_dir=str(log_dir),
+            rotation_interval_sec=999999,
+            rotation_max_size=50,
+            max_files=4,  # 3 existing + 1 new = at limit
+        )
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        # Write enough to trigger at least 2 rotations
+        for i in range(20):
+            _publish_and_drain(
+                bus,
+                _make_event(
+                    request_id=f"req-{i:03d}",
+                    chunk_hashes=[b"\xaa\xbb\xcc\xdd"],
+                ),
+            )
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        assert len(files) <= 4
+
+    def test_json_output_is_valid(
+        self,
+        config: LookupHashLogConfig,
+        log_dir: Path,
+        bus: EventBus,
+    ) -> None:
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        _publish_and_drain(
+            bus,
+            _make_event(
+                request_id="req-001",
+                chunk_hashes=[b"\xff"],
+                model_name="model-a",
+            ),
+        )
+        _publish_and_drain(
+            bus,
+            _make_event(
+                request_id="req-002",
+                chunk_hashes=[b"\x00" * 16],
+                model_name="model-b",
+            ),
+        )
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        for f in files:
+            for line in f.read_text(encoding="utf-8").strip().split("\n"):
+                data = json.loads(line)  # Should not raise
+                assert isinstance(data["timestamp"], float)
+                assert isinstance(data["request_id"], str)
+                assert isinstance(data["model_name"], str)
+                assert isinstance(data["shapes"], list)
+                assert isinstance(data["chunk_hashes"], list)
+
+    def test_integer_hashes_handled(
+        self,
+        config: LookupHashLogConfig,
+        log_dir: Path,
+        bus: EventBus,
+    ) -> None:
+        """Verify integer chunk hashes (not bytes) are also handled."""
+        sub = LookupHashLoggingSubscriber(config)
+        bus.register_subscriber(sub)
+
+        _publish_and_drain(
+            bus,
+            _make_event(
+                chunk_hashes=[255, 65536],  # type: ignore[list-item]
+            ),
+        )
+        sub.shutdown()
+
+        files = list(log_dir.glob("lookup_hashes_*.jsonl"))
+        lines = files[0].read_text(encoding="utf-8").strip().split("\n")
+        data = json.loads(lines[0])
+        assert data["chunk_hashes"] == ["0xff", "0x10000"]
diff --git a/tests/v1/mp_observability/subscribers/logging/test_mp_server.py b/tests/v1/mp_observability/subscribers/logging/test_mp_server.py
new file mode 100644
index 0000000..1f78559
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/logging/test_mp_server.py
@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for MPServerLoggingSubscriber."""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.logging.mp_server import (
+    MPServerLoggingSubscriber,
+)
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = MPServerLoggingSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+class TestMPServerLoggingSubscriber:
+    def test_subscriptions_cover_all_mp_server_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.MP_STORE_START in subs
+        assert EventType.MP_STORE_END in subs
+        assert EventType.MP_RETRIEVE_START in subs
+        assert EventType.MP_RETRIEVE_END in subs
+        assert EventType.MP_LOOKUP_PREFETCH_START in subs
+        assert EventType.MP_LOOKUP_PREFETCH_END in subs
+
+    def test_store_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id="req-1",
+                metadata={"device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id="req-1",
+                metadata={"device": "cuda:0", "stored_count": 5},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_retrieve_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id="req-2",
+                metadata={"device": "cuda:1"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_retrieve_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_END,
+                session_id="req-2",
+                metadata={"device": "cuda:1", "retrieved_count": 3},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_lookup_prefetch_start_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_START,
+                session_id="req-3",
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_lookup_prefetch_end_logs(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-3",
+                metadata={"found_count": 10},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_multiple_events_no_crash(self, bus, subscriber):
+        bus.start()
+        for i in range(10):
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_STORE_START,
+                    session_id=f"req-{i}",
+                    metadata={"device": "cuda:0"},
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_STORE_END,
+                    session_id=f"req-{i}",
+                    metadata={"device": "cuda:0", "stored_count": i},
+                )
+            )
+        time.sleep(0.15)
+        bus.stop()
diff --git a/tests/v1/mp_observability/subscribers/logging/test_timeout.py b/tests/v1/mp_observability/subscribers/logging/test_timeout.py
new file mode 100644
index 0000000..b7eb7a6
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/logging/test_timeout.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for TimeoutLoggingSubscriber."""
+
+# Standard
+import logging
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.logging.timeout import (
+    TimeoutLoggingSubscriber,
+)
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+_LOGGER_NAME = "lmcache.v1.mp_observability.subscribers.logging.timeout"
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = TimeoutLoggingSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+class _CaptureHandler(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__()
+        self.records: list[logging.LogRecord] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self.records.append(record)
+
+
+class TestTimeoutLoggingSubscriber:
+    def test_subscription_covers_timeout_event(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.TIMEOUT_RAISED in subs
+        assert len(subs) == 1
+
+    def test_logs_warning_with_message_and_stacktrace(self, bus, subscriber):
+        handler = _CaptureHandler()
+        lg = logging.getLogger(_LOGGER_NAME)
+        lg.addHandler(handler)
+        try:
+            bus.start()
+            bus.publish(
+                Event(
+                    event_type=EventType.TIMEOUT_RAISED,
+                    metadata={
+                        "message": "boom",
+                        "exception_type": "LMCacheTimeoutError",
+                        "stacktrace": "the-stacktrace",
+                    },
+                )
+            )
+            time.sleep(_DRAIN_WAIT)
+            bus.stop()
+        finally:
+            lg.removeHandler(handler)
+
+        warnings = [r for r in handler.records if r.levelno == logging.WARNING]
+        assert len(warnings) == 1
+        message = warnings[0].getMessage()
+        assert "boom" in message
+        assert "LMCacheTimeoutError" in message
+        assert "the-stacktrace" in message
diff --git a/tests/v1/mp_observability/subscribers/metrics/counter_helpers.py b/tests/v1/mp_observability/subscribers/metrics/counter_helpers.py
new file mode 100644
index 0000000..40902dc
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/counter_helpers.py
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared helpers for tagged-counter subscriber tests.
+
+Reads back counter data points from the in-memory OTel reader (see
+``otel_setup.py``) keyed by ``(metric_name, frozenset_of_attribute_pairs)``.
+This enables tests to assert on exact counts for specific attribute
+combinations (e.g. ``during=l1_store``, ``model_name=llama-7b``) without
+hand-rolling the plumbing in every test file.
+"""
+
+# Future
+from __future__ import annotations
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+TaggedKey = tuple[str, frozenset[tuple[str, str]]]
+
+
+def make_key(model: str, chunk_id: int) -> ObjectKey:
+    """Build a test ObjectKey with the given model name and chunk id."""
+    return ObjectKey(
+        chunk_hash=chunk_id.to_bytes(4, byteorder="big"),
+        model_name=model,
+        kv_rank=0,
+    )
+
+
+def read_tagged_counters() -> dict[TaggedKey, int]:
+    """Snapshot all counter values keyed by (metric_name, attrs).
+
+    Works for tagged counters where multiple data points differ only by
+    their attribute set. Histogram data points (which lack ``value``) are
+    skipped.
+    """
+    data = _reader.get_metrics_data()
+    result: dict[TaggedKey, int] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue
+                    attrs = frozenset(
+                        (str(k), str(v)) for k, v in dict(dp.attributes).items()
+                    )
+                    result[(metric.name, attrs)] = int(dp.value)
+    return result
+
+
+def counter_delta(
+    before: dict[TaggedKey, int],
+    after: dict[TaggedKey, int],
+) -> dict[TaggedKey, int]:
+    """Return the per-tagged-key delta between two snapshots."""
+    all_keys = set(before) | set(after)
+    return {k: after.get(k, 0) - before.get(k, 0) for k in all_keys}
+
+
+def counter_value(
+    delta: dict[TaggedKey, int],
+    metric: str,
+    **attrs: str,
+) -> int:
+    """Look up a counter delta by metric name + attribute equality.
+
+    Returns 0 if no data point matches the attribute set exactly.
+    """
+    key = (metric, frozenset(attrs.items()))
+    return delta.get(key, 0)
diff --git a/tests/v1/mp_observability/subscribers/metrics/otel_setup.py b/tests/v1/mp_observability/subscribers/metrics/otel_setup.py
new file mode 100644
index 0000000..87f576b
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/otel_setup.py
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared OTel MeterProvider + helpers for all metrics subscriber tests.
+
+OTel only allows one MeterProvider per process.  This module sets it up
+once so that every test file in this directory reads from the same reader,
+and provides a small set of helpers for snapshotting and diffing counter /
+histogram values via :data:`reader`.
+
+Import as::
+
+    from tests.v1.mp_observability.subscribers.metrics.otel_setup import (
+        reader,
+        read_counters,
+        histogram_count,
+        counter_delta,
+    )
+"""
+
+# Third Party
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import InMemoryMetricReader
+
+reader = InMemoryMetricReader()
+_provider = MeterProvider(metric_readers=[reader])
+metrics.set_meter_provider(_provider)
+
+
+def read_counters() -> dict[str, int]:
+    """Snapshot counter values, summed across all attribute combinations.
+
+    Accumulates into the result dict (rather than overwriting) when the
+    same metric name appears in multiple resource/scope buckets, which
+    can happen when several test files have populated the shared reader.
+
+    Returns:
+        Mapping of metric name -> total value across all data points.
+        Histograms are skipped (use :func:`histogram_count` instead).
+    """
+    data = reader.get_metrics_data()
+    result: dict[str, int] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                total = 0
+                any_value = False
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue  # skip histogram data points
+                    total += int(dp.value)
+                    any_value = True
+                if any_value:
+                    result[metric.name] = result.get(metric.name, 0) + total
+    return result
+
+
+def histogram_count(name: str) -> int:
+    """Return the total observation count for the named histogram.
+
+    Args:
+        name: OTel metric name, e.g. ``"lmcache_mp.l1_usage_ratio"``.
+
+    Returns:
+        Sum of ``count`` across all data points for that histogram.
+        Returns 0 if the histogram has no observations yet.
+    """
+    data = reader.get_metrics_data()
+    if data is None:
+        return 0
+    total = 0
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                if metric.name != name:
+                    continue
+                for dp in metric.data.data_points:
+                    if hasattr(dp, "count"):
+                        total += int(dp.count)
+    return total
+
+
+def counter_delta(before: dict[str, int], after: dict[str, int]) -> dict[str, int]:
+    """Compute ``after - before`` for every metric name in either snapshot."""
+    all_keys = set(before) | set(after)
+    return {k: after.get(k, 0) - before.get(k, 0) for k in all_keys}
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_cb_server.py b/tests/v1/mp_observability/subscribers/metrics/test_cb_server.py
new file mode 100644
index 0000000..04525a6
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_cb_server.py
@@ -0,0 +1,401 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for BlendMetricsSubscriber."""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.cb_server import (
+    BlendMetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import (
+    counter_delta,
+    read_counters,
+)
+
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = BlendMetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    """Capture counters before the test; yield a callable that returns deltas."""
+    before = read_counters()
+
+    def get_delta() -> dict[str, int]:
+        return counter_delta(before, read_counters())
+
+    return get_delta
+
+
+class TestBlendMetricsSubscriber:
+    def test_subscriptions_cover_all_cb_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.CB_LOOKUP_START in subs
+        assert EventType.CB_LOOKUP_END in subs
+        assert EventType.CB_RETRIEVE_START in subs
+        assert EventType.CB_RETRIEVE_END in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_START in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_END in subs
+        assert EventType.CB_STORE_FINAL_START in subs
+        assert EventType.CB_STORE_FINAL_END in subs
+        assert EventType.CB_FINGERPRINTS_REGISTERED in subs
+        assert EventType.CB_CHUNKS_EVICTED in subs
+
+    def test_no_subscription_for_lifecycle_sentinels(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.CB_REQUEST_START not in subs
+        assert EventType.CB_REQUEST_END not in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_SUBMITTED not in subs
+        assert EventType.CB_RETRIEVE_SUBMITTED not in subs
+        assert EventType.CB_STORE_FINAL_SUBMITTED not in subs
+
+    def test_lookup_start_increments_counter(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id="req-1",
+                metadata={"num_tokens": 128},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_lookup_end_normal(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-1",
+                metadata={
+                    "requested_tokens": 1024,
+                    "hit_tokens": 768,
+                    "fingerprint_hits": 4,
+                    "storage_hits": 3,
+                    "stale_chunks": 1,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_lookup_end_no_gpu_context_flag(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-1",
+                metadata={
+                    "requested_tokens": 0,
+                    "hit_tokens": 0,
+                    "fingerprint_hits": 0,
+                    "storage_hits": 0,
+                    "stale_chunks": 0,
+                    "no_gpu_context": True,
+                },
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_retrieve_success(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_START,
+                session_id="req-2",
+                metadata={"instance_id": 0, "num_chunks": 3},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id="req-2",
+                metadata={"instance_id": 0, "num_chunks": 3, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_retrieve_failure_counted(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_START,
+                session_id="req-2",
+                metadata={"instance_id": 0, "num_chunks": 2},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id="req-2",
+                metadata={"instance_id": 0, "num_chunks": 2, "success": False},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_pre_computed_failure_counted(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id="req-3",
+                metadata={"instance_id": 0, "num_tokens": 64},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id="req-3",
+                metadata={"instance_id": 0, "stored_chunks": 0, "success": False},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_store_final_failure_counted(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_START,
+                session_id="req-4",
+                metadata={"instance_id": 1, "num_tokens": 256},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_END,
+                session_id="req-4",
+                metadata={"instance_id": 1, "stored_chunks": 0, "success": False},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_fingerprints_registered(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_FINGERPRINTS_REGISTERED,
+                metadata={"num_chunks": 8},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_chunks_evicted(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_CHUNKS_EVICTED,
+                metadata={"num_chunks": 3},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_multiple_events_accumulate(self, bus, subscriber):
+        bus.start()
+        for _ in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_START,
+                    session_id="req-bulk",
+                    metadata={"num_tokens": 100},
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id="req-bulk",
+                    metadata={
+                        "requested_tokens": 96,
+                        "hit_tokens": 32,
+                        "fingerprint_hits": 2,
+                        "storage_hits": 1,
+                        "stale_chunks": 1,
+                        "no_gpu_context": False,
+                    },
+                )
+            )
+        time.sleep(0.15)
+        bus.stop()
+
+
+# ---------------------------------------------------------------------------
+# Blend token-level hit-rate counters
+#
+# These counters expose the numerator/denominator that let dashboards compute
+# the blend hit rate identically to the L1+L2 lookup hit rate:
+#
+#     rate(lmcache_blend_lookup_hit_tokens_total[5m])
+#     / rate(lmcache_blend_lookup_requested_tokens_total[5m])
+#
+# Asserts on actual counter deltas via the InMemoryMetricReader fixture.
+# ---------------------------------------------------------------------------
+
+
+class TestBlendLookupHitTokenCounters:
+    def test_full_hit(self, bus, subscriber, snapshot):
+        """All requested tokens are served by blend."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-1",
+                metadata={
+                    "requested_tokens": 1024,
+                    "hit_tokens": 1024,
+                    "fingerprint_hits": 4,
+                    "storage_hits": 4,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_blend.lookup_requested_tokens"] == 1024
+        assert delta["lmcache_blend.lookup_hit_tokens"] == 1024
+
+    def test_partial_hit(self, bus, subscriber, snapshot):
+        """A subset of the requested tokens is served by blend."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-2",
+                metadata={
+                    "requested_tokens": 1024,
+                    "hit_tokens": 256,
+                    "fingerprint_hits": 4,
+                    "storage_hits": 1,
+                    "stale_chunks": 3,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_blend.lookup_requested_tokens"] == 1024
+        assert delta["lmcache_blend.lookup_hit_tokens"] == 256
+
+    def test_full_miss_still_records_denominator(self, bus, subscriber, snapshot):
+        """Cold lookup: the request must still increment the denominator so
+        the running hit rate properly reflects the miss."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-3",
+                metadata={
+                    "requested_tokens": 512,
+                    "hit_tokens": 0,
+                    "fingerprint_hits": 0,
+                    "storage_hits": 0,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_blend.lookup_requested_tokens"] == 512
+        assert delta.get("lmcache_blend.lookup_hit_tokens", 0) == 0
+
+    def test_no_gpu_context_records_zero_tokens(self, bus, subscriber, snapshot):
+        """``no_gpu_context`` lookups emit ``hit_tokens=0`` and
+        ``requested_tokens=0`` — neither counter should move so the ratio
+        stays meaningful."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-4",
+                metadata={
+                    "requested_tokens": 0,
+                    "hit_tokens": 0,
+                    "fingerprint_hits": 5,
+                    "storage_hits": 0,
+                    "stale_chunks": 0,
+                    "no_gpu_context": True,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta.get("lmcache_blend.lookup_requested_tokens", 0) == 0
+        assert delta.get("lmcache_blend.lookup_hit_tokens", 0) == 0
+
+    def test_multiple_lookups_accumulate(self, bus, subscriber, snapshot):
+        """Counters accumulate across multiple completed lookups."""
+        bus.start()
+        # 3 full-hit lookups @ 256 tokens each
+        for i in range(3):
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id=f"hit-{i}",
+                    metadata={
+                        "requested_tokens": 256,
+                        "hit_tokens": 256,
+                        "fingerprint_hits": 1,
+                        "storage_hits": 1,
+                        "stale_chunks": 0,
+                        "no_gpu_context": False,
+                    },
+                )
+            )
+        # 2 partial-hit lookups: 1024 requested, 128 hit
+        for i in range(2):
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id=f"partial-{i}",
+                    metadata={
+                        "requested_tokens": 1024,
+                        "hit_tokens": 128,
+                        "fingerprint_hits": 4,
+                        "storage_hits": 1,
+                        "stale_chunks": 3,
+                        "no_gpu_context": False,
+                    },
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        # 3*256 + 2*1024 = 768 + 2048 = 2816
+        assert delta["lmcache_blend.lookup_requested_tokens"] == 2816
+        # 3*256 + 2*128 = 768 + 256 = 1024
+        assert delta["lmcache_blend.lookup_hit_tokens"] == 1024
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_engine.py b/tests/v1/mp_observability/subscribers/metrics/test_engine.py
new file mode 100644
index 0000000..2a2a840
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_engine.py
@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for EngineMetricsSubscriber."""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.engine import (
+    EngineMetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+_DRAIN_WAIT = 0.15
+_METRIC = "lmcache_mp.num_chunks_loaded"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _retrieve_end(
+    retrieved_count: int,
+    engine_id: int = 0,
+    model_name: str = "test-model",
+    cache_salt: str = "",
+    device: str = "cuda:0",
+) -> Event:
+    return Event(
+        event_type=EventType.MP_RETRIEVE_END,
+        session_id="req-1",
+        metadata={
+            "retrieved_count": retrieved_count,
+            "device": device,
+            "engine_id": engine_id,
+            "model_name": model_name,
+            "cache_salt": cache_salt,
+            "total_bytes": 0,
+        },
+    )
+
+
+def _attrs(
+    worker_id: str, model_name: str = "test-model", cache_salt: str = ""
+) -> tuple:
+    """Build the sorted-tuple attribute key the subscriber emits."""
+    return tuple(
+        sorted(
+            {
+                "worker_id": worker_id,
+                "model_name": model_name,
+                "cache_salt": cache_salt,
+            }.items()
+        )
+    )
+
+
+def _read_counter_by_attrs() -> dict[tuple, int]:
+    data = _reader.get_metrics_data()
+    result: dict[tuple, int] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                if metric.name != _METRIC:
+                    continue
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue
+                    key = tuple(sorted(dict(dp.attributes).items()))
+                    result[key] = int(dp.value)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def subscriber():
+    return EngineMetricsSubscriber()
+
+
+# ---------------------------------------------------------------------------
+# Subscription surface
+# ---------------------------------------------------------------------------
+
+
+class TestSubscriptions:
+    def test_subscribes_to_retrieve_end_only(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.MP_RETRIEVE_END in subs
+        # Store path is not of interest here; the counter is load-only.
+        assert EventType.MP_STORE_END not in subs
+
+
+# ---------------------------------------------------------------------------
+# Happy path
+# ---------------------------------------------------------------------------
+
+
+class TestNumChunksLoaded:
+    def test_single_retrieve_adds_retrieved_count(self, subscriber):
+        before = _read_counter_by_attrs()
+        subscriber._on_retrieve_end(_retrieve_end(retrieved_count=8, engine_id=3))
+        after = _read_counter_by_attrs()
+
+        key = _attrs(worker_id="3")
+        assert after.get(key, 0) == before.get(key, 0) + 8
+
+    def test_different_workers_are_independent(self, subscriber):
+        before = _read_counter_by_attrs()
+        subscriber._on_retrieve_end(_retrieve_end(retrieved_count=5, engine_id=0))
+        subscriber._on_retrieve_end(_retrieve_end(retrieved_count=7, engine_id=1))
+        subscriber._on_retrieve_end(_retrieve_end(retrieved_count=3, engine_id=0))
+        after = _read_counter_by_attrs()
+
+        worker_0 = _attrs(worker_id="0")
+        worker_1 = _attrs(worker_id="1")
+        assert after.get(worker_0, 0) == before.get(worker_0, 0) + 8
+        assert after.get(worker_1, 0) == before.get(worker_1, 0) + 7
+
+    def test_carries_model_name_and_cache_salt(self, subscriber):
+        before = _read_counter_by_attrs()
+        subscriber._on_retrieve_end(
+            _retrieve_end(
+                retrieved_count=4,
+                engine_id=2,
+                model_name="llama-3.1-8b",
+                cache_salt="tenant-A",
+            )
+        )
+        after = _read_counter_by_attrs()
+        key = _attrs(worker_id="2", model_name="llama-3.1-8b", cache_salt="tenant-A")
+        assert after.get(key, 0) == before.get(key, 0) + 4
+
+    def test_different_models_or_salts_accumulate_independently(self, subscriber):
+        before = _read_counter_by_attrs()
+        # Same worker, different (model, salt) pairs.
+        subscriber._on_retrieve_end(
+            _retrieve_end(
+                retrieved_count=5,
+                engine_id=0,
+                model_name="model-A",
+                cache_salt="salt-1",
+            )
+        )
+        subscriber._on_retrieve_end(
+            _retrieve_end(
+                retrieved_count=3,
+                engine_id=0,
+                model_name="model-A",
+                cache_salt="salt-2",
+            )
+        )
+        subscriber._on_retrieve_end(
+            _retrieve_end(
+                retrieved_count=7,
+                engine_id=0,
+                model_name="model-B",
+                cache_salt="salt-1",
+            )
+        )
+        after = _read_counter_by_attrs()
+        a1 = _attrs(worker_id="0", model_name="model-A", cache_salt="salt-1")
+        a2 = _attrs(worker_id="0", model_name="model-A", cache_salt="salt-2")
+        b1 = _attrs(worker_id="0", model_name="model-B", cache_salt="salt-1")
+        assert after.get(a1, 0) == before.get(a1, 0) + 5
+        assert after.get(a2, 0) == before.get(a2, 0) + 3
+        assert after.get(b1, 0) == before.get(b1, 0) + 7
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_zero_count_is_noop(self, subscriber):
+        before = _read_counter_by_attrs()
+        subscriber._on_retrieve_end(_retrieve_end(retrieved_count=0, engine_id=4))
+        after = _read_counter_by_attrs()
+        key = _attrs(worker_id="4")
+        assert after.get(key, 0) == before.get(key, 0)
+
+    def test_missing_engine_id_still_records_without_attr(self, subscriber):
+        # Some future emission site may forget engine_id; we should
+        # record the count anyway (so operators notice the total) but
+        # drop the worker_id attribute.
+        before = _read_counter_by_attrs()
+        subscriber._on_retrieve_end(
+            Event(
+                event_type=EventType.MP_RETRIEVE_END,
+                metadata={"retrieved_count": 2},
+            )
+        )
+        after = _read_counter_by_attrs()
+        empty_key: tuple = ()
+        assert after.get(empty_key, 0) == before.get(empty_key, 0) + 2
+
+
+# ---------------------------------------------------------------------------
+# End-to-end via EventBus
+# ---------------------------------------------------------------------------
+
+
+class TestEventBusIntegration:
+    def test_retrieve_end_via_bus_increments_counter(self):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        sub = EngineMetricsSubscriber()
+        bus.register_subscriber(sub)
+
+        before = _read_counter_by_attrs()
+        bus.start()
+        bus.publish(_retrieve_end(retrieved_count=12, engine_id=9))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        after = _read_counter_by_attrs()
+
+        key = _attrs(worker_id="9")
+        assert after.get(key, 0) == before.get(key, 0) + 12
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_event_bus_self_metrics.py b/tests/v1/mp_observability/subscribers/metrics/test_event_bus_self_metrics.py
new file mode 100644
index 0000000..e7f9f34
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_event_bus_self_metrics.py
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for ``EventBusSelfMetricsSubscriber``."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import time
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import (
+    EventBus,
+    EventBusConfig,
+    EventSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.metrics.event_bus import (
+    EventBusSelfMetricsSubscriber,
+)
+
+_PATCH_TARGET = "lmcache.v1.mp_observability.subscribers.metrics.event_bus.metrics"
+
+
+def _make_mock_metrics() -> tuple[MagicMock, MagicMock]:
+    """Build a (mock_metrics_module, mock_meter) pair for patching OTel."""
+    mock_meter = MagicMock()
+    mock_metrics = MagicMock()
+    mock_metrics.get_meter.return_value = mock_meter
+    mock_metrics.Observation = lambda value, attrs=None: (value, attrs)
+    return mock_metrics, mock_meter
+
+
+def _counter_callbacks(meter: MagicMock) -> dict:
+    return {
+        c.args[0]: c.kwargs["callbacks"][0]
+        for c in meter.create_observable_counter.call_args_list
+    }
+
+
+class TestRegistration:
+    def test_registers_two_counters(self):
+        bus = EventBus(EventBusConfig(enabled=True))
+        mock_metrics, meter = _make_mock_metrics()
+        with patch(_PATCH_TARGET, mock_metrics):
+            EventBusSelfMetricsSubscriber(bus)
+            assert set(_counter_callbacks(meter)) == {
+                "lmcache_mp.event_bus.dropped_events_total",
+                "lmcache_mp.event_bus.subscriber_exceptions",
+            }
+
+    def test_dropped_counter_callback_reflects_drops(self):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=2))
+        for _ in range(5):
+            bus.publish(Event(event_type=EventType.L1_READ_FINISHED, session_id="s"))
+
+        mock_metrics, meter = _make_mock_metrics()
+        with patch(_PATCH_TARGET, mock_metrics):
+            EventBusSelfMetricsSubscriber(bus)
+            cb = _counter_callbacks(meter)["lmcache_mp.event_bus.dropped_events_total"]
+            assert cb(None) == [(3, None)]
+
+    def test_exceptions_counter_emits_per_subscriber(self):
+        class _BadSub(EventSubscriber):
+            def get_subscriptions(self):
+                return {EventType.L1_READ_FINISHED: self._on_event}
+
+            def _on_event(self, event):
+                raise RuntimeError("boom")
+
+        bus = EventBus(EventBusConfig(enabled=True))
+        bus.register_subscriber(_BadSub())
+        bus.start()
+        bus.publish(Event(event_type=EventType.L1_READ_FINISHED, session_id="s1"))
+        bus.publish(Event(event_type=EventType.L1_READ_FINISHED, session_id="s2"))
+        time.sleep(0.15)
+        bus.stop()
+
+        mock_metrics, meter = _make_mock_metrics()
+        with patch(_PATCH_TARGET, mock_metrics):
+            EventBusSelfMetricsSubscriber(bus)
+            cb = _counter_callbacks(meter)["lmcache_mp.event_bus.subscriber_exceptions"]
+            assert (2, {"subscriber_name": "_BadSub"}) in cb(None)
+
+    def test_exceptions_counter_empty_when_no_failures(self):
+        bus = EventBus(EventBusConfig(enabled=True))
+        mock_metrics, meter = _make_mock_metrics()
+        with patch(_PATCH_TARGET, mock_metrics):
+            EventBusSelfMetricsSubscriber(bus)
+            cb = _counter_callbacks(meter)["lmcache_mp.event_bus.subscriber_exceptions"]
+            assert cb(None) == []
+
+    def test_no_event_subscriptions(self):
+        bus = EventBus(EventBusConfig(enabled=True))
+        mock_metrics, _ = _make_mock_metrics()
+        with patch(_PATCH_TARGET, mock_metrics):
+            sub = EventBusSelfMetricsSubscriber(bus)
+        assert sub.get_subscriptions() == {}
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l0_l1_throughput.py b/tests/v1/mp_observability/subscribers/metrics/test_l0_l1_throughput.py
new file mode 100644
index 0000000..4672a3f
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l0_l1_throughput.py
@@ -0,0 +1,390 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L0L1ThroughputSubscriber.
+
+Uses ``InMemoryMetricReader`` (via ``otel_setup``) to read back OTel
+histogram values.  Most tests invoke handlers directly to stay
+deterministic; the end-to-end test drives through ``EventBus``.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l0_l1_throughput import (
+    L0L1ThroughputSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+_DRAIN_WAIT = 0.15
+_STORE_METRIC = "lmcache_mp.l0_l1_store_throughput"
+_LOAD_METRIC = "lmcache_mp.l0_l1_load_throughput"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _start_event(
+    event_type: EventType,
+    session_id: str,
+    t: float,
+    engine_id: int = 0,
+    device: str = "cuda:0",
+    model_name: str = "test-model",
+) -> Event:
+    return Event(
+        event_type=event_type,
+        timestamp=t,
+        session_id=session_id,
+        metadata={
+            "engine_id": engine_id,
+            "device": device,
+            "model_name": model_name,
+        },
+    )
+
+
+def _end_event(
+    event_type: EventType,
+    session_id: str,
+    t: float,
+    total_bytes: int,
+    engine_id: int = 0,
+    device: str = "cuda:0",
+    model_name: str = "test-model",
+) -> Event:
+    return Event(
+        event_type=event_type,
+        timestamp=t,
+        session_id=session_id,
+        metadata={
+            "engine_id": engine_id,
+            "device": device,
+            "model_name": model_name,
+            "total_bytes": total_bytes,
+        },
+    )
+
+
+def _read_histograms() -> dict[str, list]:
+    data = _reader.get_metrics_data()
+    result: dict[str, list] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                result[metric.name] = list(metric.data.data_points)
+    return result
+
+
+def _total_count(name: str) -> int:
+    dps = _read_histograms().get(name, [])
+    return sum(dp.count for dp in dps)
+
+
+def _sum(name: str) -> float:
+    dps = _read_histograms().get(name, [])
+    return sum(dp.sum for dp in dps)
+
+
+def _attrs_of_nonzero_dps(name: str) -> list[dict]:
+    dps = _read_histograms().get(name, [])
+    return [dict(dp.attributes) for dp in dps if dp.count > 0]
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def subscriber():
+    return L0L1ThroughputSubscriber()
+
+
+# ---------------------------------------------------------------------------
+# Subscription surface
+# ---------------------------------------------------------------------------
+
+
+class TestSubscriptions:
+    def test_covers_expected_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.MP_STORE_START in subs
+        assert EventType.MP_STORE_END in subs
+        assert EventType.MP_RETRIEVE_START in subs
+        assert EventType.MP_RETRIEVE_END in subs
+
+    def test_does_not_subscribe_to_l1_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_WRITE_RESERVED not in subs
+        assert EventType.L1_READ_RESERVED not in subs
+
+
+# ---------------------------------------------------------------------------
+# Happy-path throughput recording
+# ---------------------------------------------------------------------------
+
+
+class TestStoreThroughput:
+    def test_records_gbps_with_attrs(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        sum_before = _sum(_STORE_METRIC)
+
+        # 2 GB in 0.1 s → 20 GB/s
+        subscriber._on_store_start(
+            _start_event(
+                EventType.MP_STORE_START, "req-1", 1000.0, engine_id=7, device="cuda:3"
+            )
+        )
+        subscriber._on_store_end(
+            _end_event(
+                EventType.MP_STORE_END,
+                "req-1",
+                1000.1,
+                total_bytes=2_000_000_000,
+                engine_id=7,
+                device="cuda:3",
+            )
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before + 1
+        observed_delta = _sum(_STORE_METRIC) - sum_before
+        assert observed_delta == pytest.approx(20.0, rel=1e-6)
+
+        attrs = _attrs_of_nonzero_dps(_STORE_METRIC)
+        assert any(
+            a.get("engine_id") == "7"
+            and a.get("device") == "cuda:3"
+            and a.get("model_name") == "test-model"
+            for a in attrs
+        )
+
+    def test_drains_pending_dict_on_end(self, subscriber):
+        subscriber._on_store_start(
+            _start_event(EventType.MP_STORE_START, "req-drain", 0.0)
+        )
+        assert ("req-drain", "cuda:0") in subscriber._pending_store
+
+        subscriber._on_store_end(
+            _end_event(EventType.MP_STORE_END, "req-drain", 0.1, total_bytes=1_000)
+        )
+        assert ("req-drain", "cuda:0") not in subscriber._pending_store
+
+
+class TestLoadThroughput:
+    def test_records_gbps_with_attrs(self, subscriber):
+        count_before = _total_count(_LOAD_METRIC)
+        sum_before = _sum(_LOAD_METRIC)
+
+        # 500 MB in 0.05 s → 10 GB/s
+        subscriber._on_retrieve_start(
+            _start_event(
+                EventType.MP_RETRIEVE_START,
+                "req-r1",
+                2000.0,
+                engine_id=2,
+                device="cuda:0",
+            )
+        )
+        subscriber._on_retrieve_end(
+            _end_event(
+                EventType.MP_RETRIEVE_END,
+                "req-r1",
+                2000.05,
+                total_bytes=500_000_000,
+                engine_id=2,
+                device="cuda:0",
+            )
+        )
+
+        assert _total_count(_LOAD_METRIC) == count_before + 1
+        observed_delta = _sum(_LOAD_METRIC) - sum_before
+        assert observed_delta == pytest.approx(10.0, rel=1e-6)
+
+        attrs = _attrs_of_nonzero_dps(_LOAD_METRIC)
+        assert any(
+            a.get("engine_id") == "2"
+            and a.get("device") == "cuda:0"
+            and a.get("model_name") == "test-model"
+            for a in attrs
+        )
+
+
+# ---------------------------------------------------------------------------
+# Edge cases — must not crash or emit nonsense
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_end_without_start_is_noop(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        subscriber._on_store_end(
+            _end_event(EventType.MP_STORE_END, "orphan", 1.0, total_bytes=10**9)
+        )
+        assert _total_count(_STORE_METRIC) == count_before
+
+    def test_zero_bytes_is_noop(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        subscriber._on_store_start(
+            _start_event(EventType.MP_STORE_START, "req-zb", 0.0)
+        )
+        subscriber._on_store_end(
+            _end_event(EventType.MP_STORE_END, "req-zb", 0.1, total_bytes=0)
+        )
+        assert _total_count(_STORE_METRIC) == count_before
+
+    def test_nonpositive_duration_is_noop(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        subscriber._on_store_start(
+            _start_event(EventType.MP_STORE_START, "req-dt", 5.0)
+        )
+        # END at same timestamp → dt == 0 → skip.
+        subscriber._on_store_end(
+            _end_event(EventType.MP_STORE_END, "req-dt", 5.0, total_bytes=10**9)
+        )
+        assert _total_count(_STORE_METRIC) == count_before
+
+    def test_missing_session_id_skips_tracking(self, subscriber):
+        # session_id="" (default) must not populate pending map.
+        subscriber._on_store_start(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                timestamp=1.0,
+                session_id="",
+                metadata={"engine_id": 1, "device": "cuda:0"},
+            )
+        )
+        assert len(subscriber._pending_store) == 0
+
+    def test_missing_device_skips_tracking(self, subscriber):
+        # Without "device" in metadata the correlation key is ambiguous
+        # across GPUs — event must be dropped.
+        subscriber._on_store_start(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                timestamp=1.0,
+                session_id="req-no-dev",
+                metadata={"engine_id": 1},
+            )
+        )
+        assert len(subscriber._pending_store) == 0
+
+    def test_store_and_load_dicts_are_independent(self, subscriber):
+        # Same session_id used for both paths — must not cross-pollinate.
+        subscriber._on_store_start(
+            _start_event(EventType.MP_STORE_START, "req-dual", 0.0)
+        )
+        subscriber._on_retrieve_start(
+            _start_event(EventType.MP_RETRIEVE_START, "req-dual", 0.0)
+        )
+
+        # Finish store only.
+        subscriber._on_store_end(
+            _end_event(EventType.MP_STORE_END, "req-dual", 0.1, total_bytes=10**9)
+        )
+        assert ("req-dual", "cuda:0") not in subscriber._pending_store
+        assert ("req-dual", "cuda:0") in subscriber._pending_load
+
+    def test_same_session_id_different_devices_do_not_collide(self, subscriber):
+        # One MP server handles multiple GPUs; TP replicas of the same
+        # request_id must not stomp on each other's pending START timestamp.
+        count_before = _total_count(_STORE_METRIC)
+
+        # Two concurrent STARTs, same session_id, different devices.
+        subscriber._on_store_start(
+            _start_event(
+                EventType.MP_STORE_START,
+                "tp-req",
+                100.0,
+                engine_id=0,
+                device="cuda:0",
+            )
+        )
+        subscriber._on_store_start(
+            _start_event(
+                EventType.MP_STORE_START,
+                "tp-req",
+                100.0,
+                engine_id=1,
+                device="cuda:1",
+            )
+        )
+        assert ("tp-req", "cuda:0") in subscriber._pending_store
+        assert ("tp-req", "cuda:1") in subscriber._pending_store
+
+        # Both END independently — both must record.
+        subscriber._on_store_end(
+            _end_event(
+                EventType.MP_STORE_END,
+                "tp-req",
+                100.1,
+                total_bytes=1_000_000_000,
+                engine_id=0,
+                device="cuda:0",
+            )
+        )
+        subscriber._on_store_end(
+            _end_event(
+                EventType.MP_STORE_END,
+                "tp-req",
+                100.1,
+                total_bytes=1_000_000_000,
+                engine_id=1,
+                device="cuda:1",
+            )
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before + 2
+        assert ("tp-req", "cuda:0") not in subscriber._pending_store
+        assert ("tp-req", "cuda:1") not in subscriber._pending_store
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: drive through EventBus
+# ---------------------------------------------------------------------------
+
+
+class TestEventBusIntegration:
+    def test_store_pair_via_bus_records_metric(self):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        sub = L0L1ThroughputSubscriber()
+        bus.register_subscriber(sub)
+
+        count_before = _total_count(_STORE_METRIC)
+        bus.start()
+        bus.publish(
+            _start_event(
+                EventType.MP_STORE_START,
+                "bus-req",
+                100.0,
+                engine_id=9,
+                device="cuda:1",
+            )
+        )
+        bus.publish(
+            _end_event(
+                EventType.MP_STORE_END,
+                "bus-req",
+                100.2,
+                total_bytes=4_000_000_000,
+                engine_id=9,
+                device="cuda:1",
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert _total_count(_STORE_METRIC) == count_before + 1
+        attrs = _attrs_of_nonzero_dps(_STORE_METRIC)
+        assert any(
+            a.get("engine_id") == "9" and a.get("device") == "cuda:1" for a in attrs
+        )
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l0_lifecycle.py b/tests/v1/mp_observability/subscribers/metrics/test_l0_lifecycle.py
new file mode 100644
index 0000000..045dbc2
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l0_lifecycle.py
@@ -0,0 +1,477 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L0LifecycleSubscriber.
+
+Uses ``InMemoryMetricReader`` to read back actual OTel histogram values
+and verifies shadow-map eviction detection logic with END_SESSION tracking.
+
+OTel only allows one MeterProvider per process, so we use a module-scoped
+provider and assert on histogram observations.
+"""
+
+# Standard
+from dataclasses import dataclass
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l0_lifecycle import (
+    L0LifecycleSubscriber,
+    _BlockStatus,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FakeBlockAllocationRecord:
+    """Mimics BlockAllocationRecord for testing without importing vLLM types."""
+
+    req_id: str
+    new_block_ids: list[int]
+    new_token_ids: list[int]
+
+
+def _make_allocation_event(
+    records: list[FakeBlockAllocationRecord],
+    instance_id: int = 0,
+    model_name: str = "test-model",
+) -> Event:
+    return Event(
+        event_type=EventType.MP_VLLM_BLOCK_ALLOCATION,
+        metadata={
+            "instance_id": instance_id,
+            "model_name": model_name,
+            "records": records,
+        },
+    )
+
+
+def _make_end_session_event(request_id: str) -> Event:
+    return Event(
+        event_type=EventType.MP_VLLM_END_SESSION,
+        metadata={"request_id": request_id},
+    )
+
+
+def _read_histograms() -> dict[str, list]:
+    """Snapshot all histogram data points."""
+    data = _reader.get_metrics_data()
+    result: dict[str, list] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                result[metric.name] = list(metric.data.data_points)
+    return result
+
+
+def _get_histogram_count(name: str) -> int:
+    histograms = _read_histograms()
+    dps = histograms.get(name, [])
+    return sum(dp.count for dp in dps)
+
+
+def _get_histogram_attrs(name: str) -> list[dict]:
+    """Return a list of attribute dicts from all data points of a histogram."""
+    histograms = _read_histograms()
+    dps = histograms.get(name, [])
+    return [dict(dp.attributes) for dp in dps if dp.count > 0]
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L0LifecycleSubscriber(sample_rate=1.0)
+    bus.register_subscriber(sub)
+    return sub
+
+
+# ---------------------------------------------------------------------------
+# Tests: New allocation
+# ---------------------------------------------------------------------------
+
+
+class TestL0NewAllocation:
+    def test_new_block_no_metrics_emitted(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l0_block_lifetime")
+        bus.start()
+        bus.publish(
+            _make_allocation_event(
+                [FakeBlockAllocationRecord("req-1", [0, 1, 2], [10, 20, 30])]
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        count_after = _get_histogram_count("lmcache_mp.l0_block_lifetime")
+        assert count_after == count_before
+
+    def test_shadow_map_populated(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            _make_allocation_event(
+                [FakeBlockAllocationRecord("req-1", [10, 11], [100, 200])]
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert (0, 10) in subscriber._shadow
+        assert (0, 11) in subscriber._shadow
+        assert subscriber._shadow[(0, 10)].status == _BlockStatus.ACTIVE
+
+
+# ---------------------------------------------------------------------------
+# Tests: Prefix sharing (no reuse gap)
+# ---------------------------------------------------------------------------
+
+
+class TestL0PrefixSharing:
+    def test_prefix_sharing_no_reuse_gap(self, bus, subscriber):
+        """Two requests sharing the same block while both active = no reuse."""
+        bus.start()
+
+        # Request A allocates block 5.
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-A", [5], [42])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        reuse_before = _get_histogram_count("lmcache_mp.l0_block_reuse_gap")
+
+        # Request B also uses block 5 with same tokens (prefix sharing).
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-B", [5], [42])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        reuse_after = _get_histogram_count("lmcache_mp.l0_block_reuse_gap")
+        # No reuse gap should be recorded — this is prefix sharing.
+        assert reuse_after == reuse_before
+
+    def test_prefix_sharing_adds_owner(self, bus, subscriber):
+        """Prefix sharing should add the new request as co-owner."""
+        bus.start()
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-A", [6], [99])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-B", [6], [99])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        state = subscriber._shadow[(0, 6)]
+        assert "req-A" in state.owners
+        assert "req-B" in state.owners
+        assert state.status == _BlockStatus.ACTIVE
+
+
+# ---------------------------------------------------------------------------
+# Tests: END_SESSION and true reuse
+# ---------------------------------------------------------------------------
+
+
+class TestL0EndSessionAndReuse:
+    def test_end_session_releases_block(self, bus, subscriber):
+        """After END_SESSION, block with no remaining owners is RELEASED."""
+        bus.start()
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [7], [10])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        bus.publish(_make_end_session_event("req-1"))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert subscriber._shadow[(0, 7)].status == _BlockStatus.RELEASED
+
+    def test_end_session_with_coowner_stays_active(self, bus, subscriber):
+        """If another request still owns the block, it stays ACTIVE."""
+        bus.start()
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-A", [8], [10])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-B", [8], [10])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        bus.publish(_make_end_session_event("req-A"))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        state = subscriber._shadow[(0, 8)]
+        assert state.status == _BlockStatus.ACTIVE
+        assert "req-A" not in state.owners
+        assert "req-B" in state.owners
+
+    def test_true_reuse_after_release(self, bus, subscriber):
+        """Block released then reused with same tokens = true cache hit."""
+        bus.start()
+
+        # Allocate.
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [9], [42])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        # Release.
+        bus.publish(_make_end_session_event("req-1"))
+        time.sleep(_DRAIN_WAIT)
+
+        # Reuse with same tokens — true cache hit.
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-2", [9], [42])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        # Release again.
+        bus.publish(_make_end_session_event("req-2"))
+        time.sleep(_DRAIN_WAIT)
+
+        # Another reuse.
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-3", [9], [42])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        state = subscriber._shadow[(0, 9)]
+        # Two true reuses → 2 access history entries → 1 reuse gap.
+        assert len(state.access_history) == 2
+
+
+# ---------------------------------------------------------------------------
+# Tests: Eviction detection
+# ---------------------------------------------------------------------------
+
+
+class TestL0EvictionDetection:
+    def test_different_tokens_triggers_eviction(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l0_block_lifetime")
+        bus.start()
+
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [3], [10])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-2", [3], [99])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        count_after = _get_histogram_count("lmcache_mp.l0_block_lifetime")
+        assert count_after == count_before + 1
+
+    def test_eviction_records_idle_time(self, bus, subscriber):
+        idle_before = _get_histogram_count("lmcache_mp.l0_block_idle_before_evict")
+        bus.start()
+
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [20], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-2", [20], [2])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        idle_after = _get_histogram_count("lmcache_mp.l0_block_idle_before_evict")
+        assert idle_after == idle_before + 1
+
+    def test_eviction_clears_old_owners(self, bus, subscriber):
+        """Eviction should clear old owner references."""
+        bus.start()
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [40], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-2", [40], [2])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        state = subscriber._shadow[(0, 40)]
+        assert state.owners == {"req-2"}
+        assert state.token_ids == [2]
+
+
+# ---------------------------------------------------------------------------
+# Tests: Reuse gap with proper release cycle
+# ---------------------------------------------------------------------------
+
+
+class TestL0ReuseGaps:
+    def test_reuse_gap_after_release_and_reuse(self, bus, subscriber):
+        """Proper release→reuse cycle should record reuse gaps on eviction."""
+        bus.start()
+
+        # Allocate block 30.
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [30], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        # Release and reuse twice (true cache hits).
+        bus.publish(_make_end_session_event("req-1"))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-2", [30], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        bus.publish(_make_end_session_event("req-2"))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-3", [30], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        gap_before = _get_histogram_count("lmcache_mp.l0_block_reuse_gap")
+
+        # Now evict to flush reuse gaps.
+        bus.publish(
+            _make_allocation_event(
+                [FakeBlockAllocationRecord("req-evict", [30], [999])]
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        gap_after = _get_histogram_count("lmcache_mp.l0_block_reuse_gap")
+        # 2 true reuses → 1 reuse gap.
+        assert gap_after == gap_before + 1
+
+
+# ---------------------------------------------------------------------------
+# Tests: Sampling
+# ---------------------------------------------------------------------------
+
+
+class TestL0Sampling:
+    def test_full_sample_rate_tracks_all(self, bus):
+        sub = L0LifecycleSubscriber(sample_rate=1.0)
+        bus.register_subscriber(sub)
+        bus.start()
+
+        for i in range(10):
+            bus.publish(
+                _make_allocation_event(
+                    [FakeBlockAllocationRecord(f"req-{i}", [2000 + i], [i])]
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert len(sub._shadow) == 10
+
+
+# ---------------------------------------------------------------------------
+# Tests: Edge cases
+# ---------------------------------------------------------------------------
+
+
+class TestL0EdgeCases:
+    def test_empty_block_ids(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-empty", [], [])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert len(subscriber._shadow) == 0
+
+    def test_same_req_same_block_ignored(self, bus, subscriber):
+        """Same request reporting same block again should be ignored."""
+        bus.start()
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [50], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+
+        # Same request, same block, same tokens — decode continuation.
+        bus.publish(
+            _make_allocation_event([FakeBlockAllocationRecord("req-1", [50], [1])])
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        state = subscriber._shadow[(0, 50)]
+        # No access recorded — it was the same request.
+        assert len(state.access_history) == 0
+
+    def test_end_session_unknown_req(self, bus, subscriber):
+        """END_SESSION for unknown req_id should not crash."""
+        bus.start()
+        bus.publish(_make_end_session_event("unknown-req"))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        # No crash = pass.
+
+
+# ---------------------------------------------------------------------------
+# Tests: OTel attributes (instance_id, model_name)
+# ---------------------------------------------------------------------------
+
+
+class TestL0MetricAttributes:
+    def test_eviction_emits_instance_id_and_model_name(self, bus, subscriber):
+        """Histogram data points should carry instance_id and model_name."""
+        bus.start()
+        bus.publish(
+            _make_allocation_event(
+                [FakeBlockAllocationRecord("req-1", [60], [10])],
+                instance_id=42,
+                model_name="llama-7b",
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(
+            _make_allocation_event(
+                [FakeBlockAllocationRecord("req-2", [60], [99])],
+                instance_id=42,
+                model_name="llama-7b",
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        attrs_list = _get_histogram_attrs("lmcache_mp.l0_block_lifetime")
+        matching = [
+            a
+            for a in attrs_list
+            if a.get("instance_id") == "42" and a.get("model_name") == "llama-7b"
+        ]
+        assert len(matching) > 0
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l1.py b/tests/v1/mp_observability/subscribers/metrics/test_l1.py
new file mode 100644
index 0000000..27af9b8
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l1.py
@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L1MetricsSubscriber."""
+
+# Standard
+from types import SimpleNamespace
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l1 import (
+    L1MetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+_DRAIN_WAIT = 0.15
+
+
+def _make_keys(count: int, cache_salt: str = "") -> list:
+    """Create a list of placeholder key objects with a cache_salt attribute."""
+    return [SimpleNamespace(cache_salt=cache_salt, id=i) for i in range(count)]
+
+
+def _make_event(event_type: EventType, keys: list) -> Event:
+    return Event(event_type=event_type, metadata={"keys": keys})
+
+
+def _read_counters_by_attrs() -> dict[str, dict[tuple, int]]:
+    """Snapshot counter values keyed by (metric_name, frozenset(attrs))."""
+    data = _reader.get_metrics_data()
+    result: dict[str, dict[tuple, int]] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue
+                    key = tuple(sorted(dict(dp.attributes).items()))
+                    result.setdefault(metric.name, {})[key] = int(dp.value)
+    return result
+
+
+@pytest.fixture
+def bus():
+    b = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+    return b
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L1MetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+class TestL1MetricsSubscriber:
+    def test_read_finished_increments_counter(self, bus, subscriber):
+        bus.start()
+        bus.publish(_make_event(EventType.L1_READ_FINISHED, _make_keys(5)))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+    def test_write_finished_increments_counter(self, bus, subscriber):
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, _make_keys(3)))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+    def test_write_finished_and_read_reserved_increments_write_counter(
+        self, bus, subscriber
+    ):
+        bus.start()
+        bus.publish(
+            _make_event(EventType.L1_WRITE_FINISHED_AND_READ_RESERVED, _make_keys(7))
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+    def test_evicted_increments_counter(self, bus, subscriber):
+        bus.start()
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, _make_keys(4)))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+    def test_no_subscription_for_reserved_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_READ_RESERVED not in subs
+        assert EventType.L1_WRITE_RESERVED not in subs
+
+    def test_subscriptions_cover_expected_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_READ_FINISHED in subs
+        assert EventType.L1_WRITE_FINISHED in subs
+        assert EventType.L1_WRITE_FINISHED_AND_READ_RESERVED in subs
+        assert EventType.L1_KEYS_EVICTED in subs
+
+    def test_multiple_events_accumulate(self, bus, subscriber):
+        bus.start()
+        for _ in range(10):
+            bus.publish(_make_event(EventType.L1_READ_FINISHED, _make_keys(2)))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+    def test_does_not_crash_on_empty_keys(self, bus, subscriber):
+        bus.start()
+        bus.publish(_make_event(EventType.L1_READ_FINISHED, []))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+
+class TestL1CacheSaltTagging:
+    def test_read_carries_cache_salt(self, bus, subscriber):
+        before = _read_counters_by_attrs().get("lmcache_mp.l1_read", {})
+        bus.start()
+        bus.publish(
+            _make_event(
+                EventType.L1_READ_FINISHED, _make_keys(5, cache_salt="tenant-a")
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l1_read", {})
+        key = (("cache_salt", "tenant-a"),)
+        assert after.get(key, 0) >= before.get(key, 0) + 5
+
+    def test_different_cache_salts_accumulate_independently(self, bus, subscriber):
+        before = _read_counters_by_attrs().get("lmcache_mp.l1_write", {})
+        bus.start()
+        bus.publish(
+            _make_event(
+                EventType.L1_WRITE_FINISHED, _make_keys(3, cache_salt="tenant-a")
+            )
+        )
+        bus.publish(
+            _make_event(
+                EventType.L1_WRITE_FINISHED, _make_keys(7, cache_salt="tenant-b")
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l1_write", {})
+        key_a = (("cache_salt", "tenant-a"),)
+        key_b = (("cache_salt", "tenant-b"),)
+        assert after.get(key_a, 0) >= before.get(key_a, 0) + 3
+        assert after.get(key_b, 0) >= before.get(key_b, 0) + 7
+
+    def test_mixed_salts_in_single_event(self, bus, subscriber):
+        """A single event with keys from two tenants splits correctly."""
+        mixed_keys = _make_keys(3, cache_salt="salt-x") + _make_keys(
+            2, cache_salt="salt-y"
+        )
+        before = _read_counters_by_attrs().get("lmcache_mp.l1_read", {})
+        bus.start()
+        bus.publish(_make_event(EventType.L1_READ_FINISHED, mixed_keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l1_read", {})
+        key_x = (("cache_salt", "salt-x"),)
+        key_y = (("cache_salt", "salt-y"),)
+        assert after.get(key_x, 0) >= before.get(key_x, 0) + 3
+        assert after.get(key_y, 0) >= before.get(key_y, 0) + 2
+
+    def test_empty_cache_salt_omits_attribute(self, bus, subscriber):
+        """Empty salt produces a dimensionless counter (no cache_salt attr)."""
+        before = _read_counters_by_attrs().get("lmcache_mp.l1_evicted", {})
+        bus.start()
+        bus.publish(
+            _make_event(EventType.L1_KEYS_EVICTED, _make_keys(4, cache_salt=""))
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l1_evicted", {})
+        key = ()  # no attributes
+        assert after.get(key, 0) >= before.get(key, 0) + 4
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l1_eviction_loop.py b/tests/v1/mp_observability/subscribers/metrics/test_l1_eviction_loop.py
new file mode 100644
index 0000000..47a92fc
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l1_eviction_loop.py
@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L1EvictionLoopSubscriber."""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l1_eviction_loop import (
+    L1EvictionLoopSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import (
+    counter_delta,
+    read_counters,
+)
+
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L1EvictionLoopSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    """Capture counters before the test; yield a callable that returns deltas."""
+    before = read_counters()
+
+    def get_delta() -> dict[str, int]:
+        return counter_delta(before, read_counters())
+
+    return get_delta
+
+
+def _tick(triggered: bool, usage: float = 0.5) -> Event:
+    return Event(
+        event_type=EventType.L1_EVICTION_LOOP_TICK,
+        metadata={"usage": usage, "watermark": 0.8, "triggered": triggered},
+    )
+
+
+class TestL1EvictionLoopSubscriber:
+    def test_subscribes_only_to_eviction_loop_tick(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_EVICTION_LOOP_TICK in subs
+        assert len(subs) == 1
+
+    def test_below_watermark_increments_only_ticks(self, bus, subscriber, snapshot):
+        bus.start()
+        for _ in range(5):
+            bus.publish(_tick(triggered=False))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l1_eviction_loop_ticks"] == 5
+        assert delta.get("lmcache_mp.l1_eviction_loop_triggered", 0) == 0
+
+    def test_triggered_increments_both_counters(self, bus, subscriber, snapshot):
+        bus.start()
+        for _ in range(3):
+            bus.publish(_tick(triggered=True))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l1_eviction_loop_ticks"] == 3
+        assert delta["lmcache_mp.l1_eviction_loop_triggered"] == 3
+
+    def test_mixed_ticks(self, bus, subscriber, snapshot):
+        """Ratio of triggered to ticks reflects how often eviction fired."""
+        bus.start()
+        for _ in range(4):
+            bus.publish(_tick(triggered=False))
+        for _ in range(6):
+            bus.publish(_tick(triggered=True))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l1_eviction_loop_ticks"] == 10
+        assert delta["lmcache_mp.l1_eviction_loop_triggered"] == 6
+
+    def test_missing_metadata_uses_safe_defaults(self, bus, subscriber, snapshot):
+        """A tick event with empty metadata still increments ``ticks`` (and
+        leaves ``triggered`` unchanged) without crashing."""
+        bus.start()
+        bus.publish(Event(event_type=EventType.L1_EVICTION_LOOP_TICK, metadata={}))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l1_eviction_loop_ticks"] == 1
+        assert delta.get("lmcache_mp.l1_eviction_loop_triggered", 0) == 0
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l1_failures.py b/tests/v1/mp_observability/subscribers/metrics/test_l1_failures.py
new file mode 100644
index 0000000..f8c37e6
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l1_failures.py
@@ -0,0 +1,305 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L1FailureMetricsSubscriber.
+
+Verifies that ``L1_ALLOCATION_FAILED`` and ``L1_READ_FAILED`` events
+produce the expected OTel counters with correct ``during``, ``reason``,
+and ``model_name`` attributes. Uses the shared ``InMemoryMetricReader``
+to assert on counter deltas keyed by (metric_name, attributes).
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l1_failures import (
+    L1FailureMetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.counter_helpers import (
+    counter_delta,
+    counter_value,
+    make_key,
+    read_tagged_counters,
+)
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L1FailureMetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    before = read_tagged_counters()
+
+    def get_delta():
+        return counter_delta(before, read_tagged_counters())
+
+    return get_delta
+
+
+class TestL1AllocationFailure:
+    def test_during_l1_store_single_model(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [make_key("llama-7b", i) for i in range(3)]
+        bus.publish(
+            Event(
+                event_type=EventType.L1_ALLOCATION_FAILED,
+                metadata={"during": "l1_store", "keys": keys},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_allocation_failure",
+                during="l1_store",
+                model_name="llama-7b",
+            )
+            == 3
+        )
+
+    def test_during_l2_prefetch_single_model(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [make_key("mistral-7b", i) for i in range(5)]
+        bus.publish(
+            Event(
+                event_type=EventType.L1_ALLOCATION_FAILED,
+                metadata={"during": "l2_prefetch", "keys": keys},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_allocation_failure",
+                during="l2_prefetch",
+                model_name="mistral-7b",
+            )
+            == 5
+        )
+
+    def test_multi_model_in_one_event_buckets_separately(
+        self, bus, subscriber, snapshot
+    ):
+        """A single event with keys from multiple models should emit
+        per-model increments."""
+        bus.start()
+        keys = [
+            make_key("llama-7b", 1),
+            make_key("llama-7b", 2),
+            make_key("mistral-7b", 3),
+        ]
+        bus.publish(
+            Event(
+                event_type=EventType.L1_ALLOCATION_FAILED,
+                metadata={"during": "l1_store", "keys": keys},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_allocation_failure",
+                during="l1_store",
+                model_name="llama-7b",
+            )
+            == 2
+        )
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_allocation_failure",
+                during="l1_store",
+                model_name="mistral-7b",
+            )
+            == 1
+        )
+
+    def test_accumulates_across_events(self, bus, subscriber, snapshot):
+        bus.start()
+        for _ in range(4):
+            bus.publish(
+                Event(
+                    event_type=EventType.L1_ALLOCATION_FAILED,
+                    metadata={
+                        "during": "l1_store",
+                        "keys": [make_key("llama-7b", 0)],
+                    },
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_allocation_failure",
+                during="l1_store",
+                model_name="llama-7b",
+            )
+            == 4
+        )
+
+
+class TestL1ReadFailure:
+    def test_during_l2_store_not_found(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [make_key("llama-7b", i) for i in range(2)]
+        bus.publish(
+            Event(
+                event_type=EventType.L1_READ_FAILED,
+                metadata={
+                    "during": "l2_store",
+                    "reason": "not_found",
+                    "keys": keys,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_read_failure",
+                during="l2_store",
+                reason="not_found",
+                model_name="llama-7b",
+            )
+            == 2
+        )
+
+    def test_during_l1_retrieve_write_locked(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [make_key("llama-7b", i) for i in range(3)]
+        bus.publish(
+            Event(
+                event_type=EventType.L1_READ_FAILED,
+                metadata={
+                    "during": "l1_retrieve",
+                    "reason": "write_locked",
+                    "keys": keys,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_read_failure",
+                during="l1_retrieve",
+                reason="write_locked",
+                model_name="llama-7b",
+            )
+            == 3
+        )
+
+    def test_different_reasons_counted_separately(self, bus, subscriber, snapshot):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L1_READ_FAILED,
+                metadata={
+                    "during": "l2_store",
+                    "reason": "not_found",
+                    "keys": [make_key("llama-7b", 0)],
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L1_READ_FAILED,
+                metadata={
+                    "during": "l2_store",
+                    "reason": "write_locked",
+                    "keys": [make_key("llama-7b", 1), make_key("llama-7b", 2)],
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_read_failure",
+                during="l2_store",
+                reason="not_found",
+                model_name="llama-7b",
+            )
+            == 1
+        )
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l1_read_failure",
+                during="l2_store",
+                reason="write_locked",
+                model_name="llama-7b",
+            )
+            == 2
+        )
+
+
+class TestL1FailureSubscriptions:
+    def test_subscriptions_cover_both_failure_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_ALLOCATION_FAILED in subs
+        assert EventType.L1_READ_FAILED in subs
+        assert len(subs) == 2
+
+    def test_no_subscription_for_normal_l1_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_READ_FINISHED not in subs
+        assert EventType.L1_WRITE_FINISHED not in subs
+
+
+class TestL1FailureEdgeCases:
+    def test_empty_keys_list_is_noop(self, bus, subscriber, snapshot):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L1_ALLOCATION_FAILED,
+                metadata={"during": "l1_store", "keys": []},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        # No keys → no emissions
+        for (name, _attrs), val in delta.items():
+            assert not (name == "lmcache_mp.l1_allocation_failure" and val != 0), (
+                f"Unexpected emission for empty keys: {name}={val}"
+            )
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l1_lifecycle.py b/tests/v1/mp_observability/subscribers/metrics/test_l1_lifecycle.py
new file mode 100644
index 0000000..f5a8c35
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l1_lifecycle.py
@@ -0,0 +1,331 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L1LifecycleSubscriber.
+
+Uses ``InMemoryMetricReader`` to read back actual OTel histogram values
+and verify lifecycle tracking with sampling.
+
+NOTE: OTel only allows one MeterProvider per process. If these tests run
+in the same process as other test files, the provider is already set. We
+re-read from the same global reader.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l1_lifecycle import (
+    L1LifecycleSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_keys(prefix: str, count: int) -> list:
+    return [f"{prefix}-{i}" for i in range(count)]
+
+
+def _make_event(event_type: EventType, keys: list) -> Event:
+    return Event(event_type=event_type, metadata={"keys": keys})
+
+
+def _get_histogram_count(name: str) -> int:
+    data = _reader.get_metrics_data()
+    result: dict[str, list] = {}
+    if data is None:
+        return 0
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                result[metric.name] = list(metric.data.data_points)
+    dps = result.get(name, [])
+    return sum(dp.count for dp in dps)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L1LifecycleSubscriber(sample_rate=1.0)
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def sampled_subscriber(bus):
+    """Subscriber with 0% sample rate — nothing should be tracked."""
+    sub = L1LifecycleSubscriber(sample_rate=1e-9)
+    bus.register_subscriber(sub)
+    return sub
+
+
+# ---------------------------------------------------------------------------
+# Tests: Shadow map and lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TestL1Lifecycle:
+    def test_write_populates_shadow(self, bus, subscriber):
+        keys = ["life-a", "life-b"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert "life-a" in subscriber._shadow
+        assert "life-b" in subscriber._shadow
+
+    def test_eviction_records_lifetime(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_lifetime")
+        keys = ["lt-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_lifetime")
+        assert count_after == count_before + 1
+
+    def test_eviction_records_idle(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_idle_before_evict")
+        keys = ["idle-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_idle_before_evict")
+        assert count_after == count_before + 1
+
+    def test_eviction_removes_from_shadow(self, bus, subscriber):
+        keys = ["rm-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert "rm-1" not in subscriber._shadow
+
+    def test_eviction_without_write_no_crash(self, bus, subscriber):
+        """Evicting a key that was never written should not crash."""
+        bus.start()
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, ["ghost-1"]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+
+# ---------------------------------------------------------------------------
+# Tests: Reuse gap
+# ---------------------------------------------------------------------------
+
+
+class TestL1ReuseGap:
+    def test_read_after_write_records_reuse_gap(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_reuse_gap")
+        keys = ["rg-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_READ_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_reuse_gap")
+        assert count_after == count_before + 1
+
+    def test_rewrite_records_reuse_gap(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_reuse_gap")
+        keys = ["rg-2"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_reuse_gap")
+        assert count_after == count_before + 1
+
+    def test_read_untracked_key_no_gap(self, bus, subscriber):
+        """Reading a key never written should not record a gap."""
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_reuse_gap")
+        bus.start()
+        bus.publish(_make_event(EventType.L1_READ_FINISHED, ["nowrite-1"]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_reuse_gap")
+        assert count_after == count_before
+
+
+# ---------------------------------------------------------------------------
+# Tests: Evict-reuse gap
+# ---------------------------------------------------------------------------
+
+
+class TestL1EvictReuseGap:
+    def test_rewrite_after_eviction_records_gap(self, bus, subscriber):
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_evict_reuse_gap")
+        keys = ["erg-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_evict_reuse_gap")
+        assert count_after == count_before + 1
+
+    def test_evicted_key_tracked_in_evicted_at(self, bus, subscriber):
+        keys = ["erg-2"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert "erg-2" in subscriber._evicted_at
+
+    def test_rewrite_clears_evicted_at(self, bus, subscriber):
+        keys = ["erg-3"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert "erg-3" not in subscriber._evicted_at
+
+
+# ---------------------------------------------------------------------------
+# Tests: Sampling
+# ---------------------------------------------------------------------------
+
+
+class TestL1Sampling:
+    def test_sample_rate_1_tracks_all(self, bus, subscriber):
+        """With sample_rate=1.0, all keys should be tracked."""
+        keys = _make_keys("samp", 10)
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert len(subscriber._shadow) >= 10
+
+    def test_sample_rate_zero_tracks_none(self, bus, sampled_subscriber):
+        """With near-zero sample rate, no keys should be tracked."""
+        keys = _make_keys("nosamp", 100)
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert len(sampled_subscriber._shadow) == 0
+
+    def test_deterministic_sampling_is_consistent(self, bus):
+        """Same key always gets the same sampling decision."""
+        sub = L1LifecycleSubscriber(sample_rate=0.5)
+        bus.register_subscriber(sub)
+        keys = ["det-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        tracked_first = "det-1" in sub._shadow
+        # Evict and re-write — should get same decision
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        tracked_second = "det-1" in sub._shadow
+        assert tracked_first == tracked_second
+
+    def test_unsampled_key_ignored_on_eviction(self, bus, sampled_subscriber):
+        """Evicting an unsampled key should not record lifetime."""
+        count_before = _get_histogram_count("lmcache_mp.l1_chunk_lifetime")
+        keys = ["skip-ev-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        count_after = _get_histogram_count("lmcache_mp.l1_chunk_lifetime")
+        assert count_after == count_before
+
+
+# ---------------------------------------------------------------------------
+# Tests: Sweep stale evictions
+# ---------------------------------------------------------------------------
+
+
+class TestL1SweepStaleEvictions:
+    def test_sweep_removes_old_entries(self, bus):
+        sub = L1LifecycleSubscriber(sample_rate=1.0, max_evict_reuse_wait=0.1)
+        bus.register_subscriber(sub)
+
+        keys = ["sweep-1"]
+        bus.start()
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, keys))
+        time.sleep(_DRAIN_WAIT)
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, keys))
+        time.sleep(_DRAIN_WAIT)
+
+        # Wait longer than max_evict_reuse_wait
+        time.sleep(0.2)
+
+        # Trigger sweep via another write
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, ["sweep-trigger"]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert "sweep-1" not in sub._evicted_at
+
+
+# ---------------------------------------------------------------------------
+# Tests: Subscriptions
+# ---------------------------------------------------------------------------
+
+
+class TestL1Subscriptions:
+    def test_subscriptions_cover_expected_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_READ_FINISHED in subs
+        assert EventType.L1_WRITE_FINISHED in subs
+        assert EventType.L1_WRITE_FINISHED_AND_READ_RESERVED in subs
+        assert EventType.L1_KEYS_EVICTED in subs
+
+    def test_no_subscription_for_reserved_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L1_READ_RESERVED not in subs
+        assert EventType.L1_WRITE_RESERVED not in subs
+
+    def test_does_not_crash_on_empty_keys(self, bus, subscriber):
+        bus.start()
+        bus.publish(_make_event(EventType.L1_READ_FINISHED, []))
+        bus.publish(_make_event(EventType.L1_WRITE_FINISHED, []))
+        bus.publish(_make_event(EventType.L1_KEYS_EVICTED, []))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l2.py b/tests/v1/mp_observability/subscribers/metrics/test_l2.py
new file mode 100644
index 0000000..30da217
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l2.py
@@ -0,0 +1,766 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L2MetricsSubscriber.
+
+Uses ``InMemoryMetricReader`` to read back actual OTel counter values
+and assert exact counts after publishing known events through the EventBus.
+
+OTel only allows one MeterProvider per process, so we use a module-scoped
+provider and assert on counter **deltas** between before/after snapshots.
+"""
+
+# Standard
+from collections import Counter
+from types import SimpleNamespace
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l2 import (
+    L2MetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_keys(count: int, cache_salt: str = "") -> list:
+    return [SimpleNamespace(cache_salt=cache_salt, id=i) for i in range(count)]
+
+
+def _salt_counts(keys: list) -> dict[str, int]:
+    return dict(Counter(k.cache_salt for k in keys))
+
+
+def _read_counters() -> dict[str, int]:
+    """Snapshot all counter values from the module-level reader, summed
+    across attribute combinations.  A counter with multiple labeled data
+    points (e.g. ``l2_name="fs"`` and ``l2_name="nixl"``) reports the
+    aggregate; tests that need per-label values use ``_read_counters_by_attrs``.
+    """
+    data = _reader.get_metrics_data()
+    result: dict[str, int] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                total = 0
+                any_value = False
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue  # skip histogram data points
+                    total += int(dp.value)
+                    any_value = True
+                if any_value:
+                    result[metric.name] = total
+    return result
+
+
+def _read_counters_by_attrs() -> dict[str, dict[tuple, int]]:
+    """Snapshot counter values keyed by (metric_name, frozenset(attrs))."""
+    data = _reader.get_metrics_data()
+    result: dict[str, dict[tuple, int]] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue
+                    key = tuple(sorted(dict(dp.attributes).items()))
+                    result.setdefault(metric.name, {})[key] = int(dp.value)
+    return result
+
+
+def _counter_delta(before: dict[str, int], after: dict[str, int]) -> dict[str, int]:
+    """Compute the difference between two counter snapshots."""
+    all_keys = set(before) | set(after)
+    return {k: after.get(k, 0) - before.get(k, 0) for k in all_keys}
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L2MetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    """Capture counters before the test; yield a callable that returns deltas."""
+    before = _read_counters()
+
+    def get_delta() -> dict[str, int]:
+        return _counter_delta(before, _read_counters())
+
+    return get_delta
+
+
+# ---------------------------------------------------------------------------
+# Store events
+# ---------------------------------------------------------------------------
+
+
+class TestL2StoreMetrics:
+    def test_store_submitted_counts(self, bus, subscriber, snapshot):
+        bus.start()
+        keys_a = _make_keys(10)
+        keys_b = _make_keys(5)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_SUBMITTED,
+                metadata={
+                    "adapter_index": 0,
+                    "key_count": 10,
+                    "key_count_per_salt": _salt_counts(keys_a),
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_SUBMITTED,
+                metadata={
+                    "adapter_index": 1,
+                    "key_count": 5,
+                    "key_count_per_salt": _salt_counts(keys_b),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_store_submitted"] == 2
+        assert delta["lmcache_mp.l2_store_submitted_objects"] == 15
+
+    def test_store_completed_success(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = _make_keys(8)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_COMPLETED,
+                metadata={
+                    "adapter_index": 0,
+                    "succeeded_count": 8,
+                    "failed_count": 0,
+                    "key_count_per_salt": _salt_counts(keys),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_store_completed"] == 1
+        assert delta["lmcache_mp.l2_store_completed_objects"] == 8
+
+    def test_store_completed_with_failures(self, bus, subscriber, snapshot):
+        bus.start()
+        succeeded = _make_keys(3)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_COMPLETED,
+                metadata={
+                    "adapter_index": 0,
+                    "succeeded_count": 3,
+                    "failed_count": 7,
+                    "key_count_per_salt": _salt_counts(succeeded),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_store_completed"] == 1
+        assert delta["lmcache_mp.l2_store_completed_objects"] == 3
+
+    def test_store_full_lifecycle(self, bus, subscriber, snapshot):
+        """Simulate warmup: submit 20 keys, all succeed."""
+        bus.start()
+        keys = _make_keys(20)
+        sc = _salt_counts(keys)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_SUBMITTED,
+                metadata={
+                    "adapter_index": 0,
+                    "key_count": 20,
+                    "key_count_per_salt": sc,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_COMPLETED,
+                metadata={
+                    "adapter_index": 0,
+                    "succeeded_count": 20,
+                    "failed_count": 0,
+                    "key_count_per_salt": sc,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_store_submitted"] == 1
+        assert delta["lmcache_mp.l2_store_submitted_objects"] == 20
+        assert delta["lmcache_mp.l2_store_completed"] == 1
+        assert delta["lmcache_mp.l2_store_completed_objects"] == 20
+
+
+# ---------------------------------------------------------------------------
+# Prefetch events
+# ---------------------------------------------------------------------------
+
+
+class TestL2PrefetchMetrics:
+    def test_lookup_submitted_counts(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = _make_keys(12)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_SUBMITTED,
+                metadata={
+                    "request_id": 1,
+                    "key_count": 12,
+                    "adapter_count": 2,
+                    "key_count_per_salt": _salt_counts(keys),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_prefetch_lookup"] == 1
+        assert delta["lmcache_mp.l2_prefetch_lookup_objects"] == 12
+
+    def test_lookup_completed_counts_hits(self, bus, subscriber, snapshot):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_COMPLETED,
+                metadata={"request_id": 1, "prefix_hit_count": 10},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_prefetch_hit"] == 10
+
+    def test_load_submitted_counts(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = _make_keys(10)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_SUBMITTED,
+                metadata={
+                    "request_id": 1,
+                    "key_count": 10,
+                    "adapter_count": 2,
+                    "key_count_per_salt": _salt_counts(keys),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_prefetch_load_submitted"] == 2
+        assert delta["lmcache_mp.l2_prefetch_load_submitted_objects"] == 10
+
+    def test_load_completed_counts(self, bus, subscriber, snapshot):
+        bus.start()
+        loaded = _make_keys(9)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_COMPLETED,
+                metadata={
+                    "request_id": 1,
+                    "loaded_count": 9,
+                    "failed_count": 1,
+                    "key_count_per_salt": _salt_counts(loaded),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_prefetch_load_completed"] == 9
+
+    def test_prefetch_full_lifecycle(self, bus, subscriber, snapshot):
+        """Simulate query: lookup 20 keys, 18 prefix hits, all 18 load OK."""
+        bus.start()
+        lookup_keys = _make_keys(20)
+        load_keys = _make_keys(18)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_SUBMITTED,
+                metadata={
+                    "request_id": 42,
+                    "key_count": 20,
+                    "adapter_count": 1,
+                    "key_count_per_salt": _salt_counts(lookup_keys),
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_COMPLETED,
+                metadata={"request_id": 42, "prefix_hit_count": 18},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_SUBMITTED,
+                metadata={
+                    "request_id": 42,
+                    "key_count": 18,
+                    "adapter_count": 1,
+                    "key_count_per_salt": _salt_counts(load_keys),
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_COMPLETED,
+                metadata={
+                    "request_id": 42,
+                    "loaded_count": 18,
+                    "failed_count": 0,
+                    "key_count_per_salt": _salt_counts(load_keys),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_prefetch_lookup"] == 1
+        assert delta["lmcache_mp.l2_prefetch_lookup_objects"] == 20
+        assert delta["lmcache_mp.l2_prefetch_hit"] == 18
+        assert delta["lmcache_mp.l2_prefetch_load_submitted"] == 1
+        assert delta["lmcache_mp.l2_prefetch_load_submitted_objects"] == 18
+        assert delta["lmcache_mp.l2_prefetch_load_completed"] == 18
+
+
+# ---------------------------------------------------------------------------
+# Eviction events
+# ---------------------------------------------------------------------------
+
+
+class TestL2EvictionMetrics:
+    def test_eviction_counts(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = _make_keys(7)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_KEYS_EVICTED,
+                metadata={
+                    "key_count": 7,
+                    "key_count_per_salt": _salt_counts(keys),
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_evicted_objects"] == 7
+
+
+# ---------------------------------------------------------------------------
+# Subscription wiring
+# ---------------------------------------------------------------------------
+
+
+class TestL2MetricsSubscriptions:
+    def test_subscriptions_cover_all_l2_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L2_STORE_SUBMITTED in subs
+        assert EventType.L2_STORE_COMPLETED in subs
+        assert EventType.L2_LOAD_TASK_COMPLETED in subs
+        assert EventType.L2_PREFETCH_LOOKUP_SUBMITTED in subs
+        assert EventType.L2_PREFETCH_LOOKUP_COMPLETED in subs
+        assert EventType.L2_PREFETCH_LOAD_SUBMITTED in subs
+        assert EventType.L2_PREFETCH_LOAD_COMPLETED in subs
+        assert EventType.L2_KEYS_EVICTED in subs
+        assert len(subs) == 8
+
+
+# ---------------------------------------------------------------------------
+# l2_name-labeled counters (for per-backend IOPS via rate())
+# ---------------------------------------------------------------------------
+
+
+class TestL2NameLabeledCounters:
+    def test_store_completed_carries_l2_name(self, bus, subscriber):
+        bus.start()
+        before = _read_counters_by_attrs().get("lmcache_mp.l2_store_completed", {})
+        keys = _make_keys(5)
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_COMPLETED,
+                metadata={
+                    "adapter_index": 0,
+                    "task_id": 1,
+                    "l2_name": "fs",
+                    "succeeded_count": 5,
+                    "failed_count": 0,
+                    "key_count_per_salt": _salt_counts(keys),
+                    "total_bytes": 1_000,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l2_store_completed", {})
+        fs_key = (("l2_name", "fs"),)
+        assert after.get(fs_key, 0) == before.get(fs_key, 0) + 1
+
+    def test_load_task_completed_carries_l2_name(self, bus, subscriber):
+        bus.start()
+        before = _read_counters_by_attrs().get("lmcache_mp.l2_load_completed", {})
+        bus.publish(
+            Event(
+                event_type=EventType.L2_LOAD_TASK_COMPLETED,
+                metadata={
+                    "request_id": 7,
+                    "adapter_index": 1,
+                    "task_id": 42,
+                    "l2_name": "nixl_store",
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l2_load_completed", {})
+        nixl_key = (("l2_name", "nixl_store"),)
+        assert after.get(nixl_key, 0) == before.get(nixl_key, 0) + 1
+
+    def test_different_l2_names_accumulate_independently(self, bus, subscriber):
+        bus.start()
+        before = _read_counters_by_attrs().get("lmcache_mp.l2_load_completed", {})
+        # 3x fs, 2x nixl_store completions.
+        for _ in range(3):
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_LOAD_TASK_COMPLETED,
+                    metadata={
+                        "request_id": 1,
+                        "adapter_index": 0,
+                        "task_id": 1,
+                        "l2_name": "fs",
+                    },
+                )
+            )
+        for _ in range(2):
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_LOAD_TASK_COMPLETED,
+                    metadata={
+                        "request_id": 1,
+                        "adapter_index": 1,
+                        "task_id": 1,
+                        "l2_name": "nixl_store",
+                    },
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l2_load_completed", {})
+        fs_key = (("l2_name", "fs"),)
+        nixl_key = (("l2_name", "nixl_store"),)
+        assert after.get(fs_key, 0) == before.get(fs_key, 0) + 3
+        assert after.get(nixl_key, 0) == before.get(nixl_key, 0) + 2
+
+
+# ---------------------------------------------------------------------------
+# Accumulation across multiple events
+# ---------------------------------------------------------------------------
+
+
+class TestL2MetricsAccumulation:
+    def test_multiple_store_events_accumulate(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = _make_keys(3)
+        sc = _salt_counts(keys)
+        for _ in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_STORE_SUBMITTED,
+                    metadata={
+                        "adapter_index": 0,
+                        "key_count": 3,
+                        "key_count_per_salt": sc,
+                    },
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_STORE_COMPLETED,
+                    metadata={
+                        "adapter_index": 0,
+                        "succeeded_count": 3,
+                        "failed_count": 0,
+                        "key_count_per_salt": sc,
+                    },
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_store_submitted"] == 5
+        assert delta["lmcache_mp.l2_store_submitted_objects"] == 15
+        assert delta["lmcache_mp.l2_store_completed"] == 5
+        assert delta["lmcache_mp.l2_store_completed_objects"] == 15
+
+    def test_multiple_prefetch_events_accumulate(self, bus, subscriber, snapshot):
+        bus.start()
+        lookup_sc = _salt_counts(_make_keys(10))
+        load_sc = _salt_counts(_make_keys(8))
+        loaded_sc = _salt_counts(_make_keys(7))
+        for i in range(3):
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_LOOKUP_SUBMITTED,
+                    metadata={
+                        "request_id": i,
+                        "key_count": 10,
+                        "adapter_count": 1,
+                        "key_count_per_salt": lookup_sc,
+                    },
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_LOOKUP_COMPLETED,
+                    metadata={"request_id": i, "prefix_hit_count": 8},
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_LOAD_SUBMITTED,
+                    metadata={
+                        "request_id": i,
+                        "key_count": 8,
+                        "adapter_count": 1,
+                        "key_count_per_salt": load_sc,
+                    },
+                )
+            )
+            bus.publish(
+                Event(
+                    event_type=EventType.L2_PREFETCH_LOAD_COMPLETED,
+                    metadata={
+                        "request_id": i,
+                        "loaded_count": 7,
+                        "failed_count": 1,
+                        "key_count_per_salt": loaded_sc,
+                    },
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.l2_prefetch_lookup"] == 3
+        assert delta["lmcache_mp.l2_prefetch_lookup_objects"] == 30
+        assert delta["lmcache_mp.l2_prefetch_hit"] == 24
+        assert delta["lmcache_mp.l2_prefetch_load_submitted"] == 3
+        assert delta["lmcache_mp.l2_prefetch_load_submitted_objects"] == 24
+        assert delta["lmcache_mp.l2_prefetch_load_completed"] == 21
+
+
+# ---------------------------------------------------------------------------
+# cache_salt-labeled counters
+# ---------------------------------------------------------------------------
+
+
+class TestL2CacheSaltTagging:
+    def test_store_submitted_groups_by_salt(self, bus, subscriber):
+        """Store submitted object counter groups by cache_salt."""
+        before = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_store_submitted_objects", {}
+        )
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_SUBMITTED,
+                metadata={
+                    "adapter_index": 0,
+                    "key_count": 7,
+                    "key_count_per_salt": {"tenant-a": 3, "tenant-b": 4},
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_store_submitted_objects", {}
+        )
+        key_a = (("cache_salt", "tenant-a"),)
+        key_b = (("cache_salt", "tenant-b"),)
+        assert after.get(key_a, 0) >= before.get(key_a, 0) + 3
+        assert after.get(key_b, 0) >= before.get(key_b, 0) + 4
+
+    def test_store_completed_groups_by_salt(self, bus, subscriber):
+        """Store completed object counter groups by cache_salt."""
+        before = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_store_completed_objects", {}
+        )
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_STORE_COMPLETED,
+                metadata={
+                    "adapter_index": 0,
+                    "task_id": 1,
+                    "l2_name": "fs",
+                    "succeeded_count": 7,
+                    "failed_count": 0,
+                    "key_count_per_salt": {"tenant-a": 3, "tenant-b": 4},
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_store_completed_objects", {}
+        )
+        key_a = (("cache_salt", "tenant-a"),)
+        key_b = (("cache_salt", "tenant-b"),)
+        assert after.get(key_a, 0) >= before.get(key_a, 0) + 3
+        assert after.get(key_b, 0) >= before.get(key_b, 0) + 4
+
+    def test_prefetch_lookup_submitted_groups_by_salt(self, bus, subscriber):
+        """Prefetch lookup submitted object counter groups by cache_salt."""
+        before = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_prefetch_lookup_objects", {}
+        )
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOOKUP_SUBMITTED,
+                metadata={
+                    "request_id": 1,
+                    "key_count": 5,
+                    "adapter_count": 1,
+                    "key_count_per_salt": {"tenant-d": 5},
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_prefetch_lookup_objects", {}
+        )
+        key = (("cache_salt", "tenant-d"),)
+        assert after.get(key, 0) >= before.get(key, 0) + 5
+
+    def test_prefetch_load_submitted_groups_by_salt(self, bus, subscriber):
+        """Prefetch load submitted object counter groups by cache_salt."""
+        before = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_prefetch_load_submitted_objects", {}
+        )
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_SUBMITTED,
+                metadata={
+                    "request_id": 1,
+                    "key_count": 6,
+                    "adapter_count": 1,
+                    "key_count_per_salt": {"tenant-e": 6},
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_prefetch_load_submitted_objects", {}
+        )
+        key = (("cache_salt", "tenant-e"),)
+        assert after.get(key, 0) >= before.get(key, 0) + 6
+
+    def test_prefetch_load_completed_groups_by_salt(self, bus, subscriber):
+        """Prefetch load completed counter groups by cache_salt."""
+        before = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_prefetch_load_completed", {}
+        )
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_LOAD_COMPLETED,
+                metadata={
+                    "request_id": 1,
+                    "loaded_count": 5,
+                    "failed_count": 0,
+                    "key_count_per_salt": {"tenant-c": 5},
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get(
+            "lmcache_mp.l2_prefetch_load_completed", {}
+        )
+        key = (("cache_salt", "tenant-c"),)
+        assert after.get(key, 0) >= before.get(key, 0) + 5
+
+    def test_evicted_groups_by_salt(self, bus, subscriber):
+        """Eviction counter groups by cache_salt."""
+        before = _read_counters_by_attrs().get("lmcache_mp.l2_evicted_objects", {})
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_KEYS_EVICTED,
+                metadata={
+                    "key_count": 9,
+                    "key_count_per_salt": {"tenant-a": 4, "tenant-b": 5},
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs().get("lmcache_mp.l2_evicted_objects", {})
+        key_a = (("cache_salt", "tenant-a"),)
+        key_b = (("cache_salt", "tenant-b"),)
+        assert after.get(key_a, 0) >= before.get(key_a, 0) + 4
+        assert after.get(key_b, 0) >= before.get(key_b, 0) + 5
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l2_failures.py b/tests/v1/mp_observability/subscribers/metrics/test_l2_failures.py
new file mode 100644
index 0000000..4a0cbfd
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l2_failures.py
@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L2FailureMetricsSubscriber.
+
+Verifies that ``L2_PREFETCH_FAILED`` events produce the expected
+``lmcache_mp.l2_prefetch_failure`` counter with ``reason`` and
+``model_name`` attributes. Uses the shared ``InMemoryMetricReader`` to
+assert on counter deltas.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l2_failures import (
+    L2FailureMetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.counter_helpers import (
+    counter_delta,
+    counter_value,
+    make_key,
+    read_tagged_counters,
+)
+
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = L2FailureMetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    before = read_tagged_counters()
+
+    def get_delta():
+        return counter_delta(before, read_tagged_counters())
+
+    return get_delta
+
+
+class TestL2PrefetchFailure:
+    def test_reason_l1_oom(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [make_key("llama-7b", i) for i in range(4)]
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_FAILED,
+                metadata={"reason": "l1_oom", "keys": keys},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l2_prefetch_failure",
+                reason="l1_oom",
+                model_name="llama-7b",
+            )
+            == 4
+        )
+
+    def test_reason_not_found(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [make_key("mistral-7b", i) for i in range(2)]
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_FAILED,
+                metadata={"reason": "not_found", "keys": keys},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l2_prefetch_failure",
+                reason="not_found",
+                model_name="mistral-7b",
+            )
+            == 2
+        )
+
+    def test_multi_model_buckets_separately(self, bus, subscriber, snapshot):
+        bus.start()
+        keys = [
+            make_key("llama-7b", 1),
+            make_key("mistral-7b", 2),
+            make_key("mistral-7b", 3),
+        ]
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_FAILED,
+                metadata={"reason": "not_found", "keys": keys},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l2_prefetch_failure",
+                reason="not_found",
+                model_name="llama-7b",
+            )
+            == 1
+        )
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l2_prefetch_failure",
+                reason="not_found",
+                model_name="mistral-7b",
+            )
+            == 2
+        )
+
+    def test_different_reasons_counted_separately(self, bus, subscriber, snapshot):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_FAILED,
+                metadata={
+                    "reason": "l1_oom",
+                    "keys": [make_key("llama-7b", 0), make_key("llama-7b", 1)],
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_FAILED,
+                metadata={
+                    "reason": "not_found",
+                    "keys": [make_key("llama-7b", 2)],
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l2_prefetch_failure",
+                reason="l1_oom",
+                model_name="llama-7b",
+            )
+            == 2
+        )
+        assert (
+            counter_value(
+                delta,
+                "lmcache_mp.l2_prefetch_failure",
+                reason="not_found",
+                model_name="llama-7b",
+            )
+            == 1
+        )
+
+
+class TestL2FailureSubscriptions:
+    def test_subscribes_only_to_prefetch_failed(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L2_PREFETCH_FAILED in subs
+        assert len(subs) == 1
+
+    def test_no_subscription_for_normal_l2_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L2_STORE_SUBMITTED not in subs
+        assert EventType.L2_PREFETCH_LOAD_COMPLETED not in subs
+
+
+class TestL2FailureEdgeCases:
+    def test_empty_keys_is_noop(self, bus, subscriber, snapshot):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.L2_PREFETCH_FAILED,
+                metadata={"reason": "l1_oom", "keys": []},
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        for (name, _attrs), val in delta.items():
+            assert not (name == "lmcache_mp.l2_prefetch_failure" and val != 0), (
+                f"Unexpected emission for empty keys: {name}={val}"
+            )
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_l2_throughput.py b/tests/v1/mp_observability/subscribers/metrics/test_l2_throughput.py
new file mode 100644
index 0000000..e1d4c3c
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_l2_throughput.py
@@ -0,0 +1,436 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for L2ThroughputSubscriber.
+
+Uses ``InMemoryMetricReader`` (via ``otel_setup``) to read back OTel
+histogram values.  Most tests invoke handlers directly to stay
+deterministic; the end-to-end test drives through ``EventBus``.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.l2_throughput import (
+    L2ThroughputSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+_DRAIN_WAIT = 0.15
+_STORE_METRIC = "lmcache_mp.l2_store_throughput"
+_LOAD_METRIC = "lmcache_mp.l2_load_throughput"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _store_submitted(
+    task_id: int,
+    t: float,
+    adapter_index: int = 0,
+    l2_name: str = "fs",
+    total_bytes: int = 0,
+) -> Event:
+    return Event(
+        event_type=EventType.L2_STORE_SUBMITTED,
+        timestamp=t,
+        metadata={
+            "adapter_index": adapter_index,
+            "task_id": task_id,
+            "l2_name": l2_name,
+            "key_count": 1,
+            "total_bytes": total_bytes,
+        },
+    )
+
+
+def _store_completed(
+    task_id: int,
+    t: float,
+    adapter_index: int = 0,
+    l2_name: str = "fs",
+    bytes_transferred: int | None = None,
+) -> Event:
+    # ``bytes_transferred`` is populated by fast-path-aware adapters (see
+    # ``store_controller._finalize_store``).  Absence means the subscriber
+    # falls back to the submitted-bytes accounting it cached at SUBMITTED
+    # time.
+    metadata: dict = {
+        "adapter_index": adapter_index,
+        "task_id": task_id,
+        "l2_name": l2_name,
+        "succeeded_count": 1,
+        "failed_count": 0,
+    }
+    if bytes_transferred is not None:
+        metadata["bytes_transferred"] = bytes_transferred
+    return Event(
+        event_type=EventType.L2_STORE_COMPLETED,
+        timestamp=t,
+        metadata=metadata,
+    )
+
+
+def _load_submitted(
+    request_id: int,
+    t: float,
+    adapter_index: int = 0,
+    l2_name: str = "fs",
+    total_bytes: int = 0,
+    task_id: int = 0,
+) -> Event:
+    return Event(
+        event_type=EventType.L2_LOAD_TASK_SUBMITTED,
+        timestamp=t,
+        metadata={
+            "request_id": request_id,
+            "adapter_index": adapter_index,
+            "task_id": task_id,
+            "l2_name": l2_name,
+            "key_count": 1,
+            "total_bytes": total_bytes,
+        },
+    )
+
+
+def _load_completed(
+    request_id: int,
+    t: float,
+    adapter_index: int = 0,
+    l2_name: str = "fs",
+    task_id: int = 0,
+) -> Event:
+    # L2_LOAD_TASK_COMPLETED does not carry total_bytes; bytes are
+    # looked up from the subscriber's SUBMITTED-time cache.
+    return Event(
+        event_type=EventType.L2_LOAD_TASK_COMPLETED,
+        timestamp=t,
+        metadata={
+            "request_id": request_id,
+            "adapter_index": adapter_index,
+            "task_id": task_id,
+            "l2_name": l2_name,
+        },
+    )
+
+
+def _read_histograms() -> dict[str, list]:
+    data = _reader.get_metrics_data()
+    result: dict[str, list] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                result[metric.name] = list(metric.data.data_points)
+    return result
+
+
+def _total_count(name: str) -> int:
+    dps = _read_histograms().get(name, [])
+    return sum(dp.count for dp in dps)
+
+
+def _sum(name: str) -> float:
+    dps = _read_histograms().get(name, [])
+    return sum(dp.sum for dp in dps)
+
+
+def _attrs_of_nonzero_dps(name: str) -> list[dict]:
+    dps = _read_histograms().get(name, [])
+    return [dict(dp.attributes) for dp in dps if dp.count > 0]
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def subscriber():
+    return L2ThroughputSubscriber()
+
+
+# ---------------------------------------------------------------------------
+# Subscription surface
+# ---------------------------------------------------------------------------
+
+
+class TestSubscriptions:
+    def test_covers_expected_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.L2_STORE_SUBMITTED in subs
+        assert EventType.L2_STORE_COMPLETED in subs
+        assert EventType.L2_LOAD_TASK_SUBMITTED in subs
+        assert EventType.L2_LOAD_TASK_COMPLETED in subs
+
+    def test_does_not_subscribe_to_request_level_load_events(self, subscriber):
+        # The request-level L2_PREFETCH_LOAD_* events aggregate across
+        # adapters; per-adapter throughput requires the task-level events.
+        subs = subscriber.get_subscriptions()
+        assert EventType.L2_PREFETCH_LOAD_SUBMITTED not in subs
+        assert EventType.L2_PREFETCH_LOAD_COMPLETED not in subs
+
+
+# ---------------------------------------------------------------------------
+# Happy-path throughput recording
+# ---------------------------------------------------------------------------
+
+
+class TestStoreThroughput:
+    def test_records_gbps_with_l2_name(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        sum_before = _sum(_STORE_METRIC)
+
+        # 2 GB in 0.1 s -> 20 GB/s
+        subscriber._on_store_submitted(
+            _store_submitted(
+                task_id=1,
+                t=1000.0,
+                adapter_index=0,
+                l2_name="nixl",
+                total_bytes=2_000_000_000,
+            )
+        )
+        subscriber._on_store_completed(
+            _store_completed(task_id=1, t=1000.1, adapter_index=0, l2_name="nixl")
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before + 1
+        assert _sum(_STORE_METRIC) - sum_before == pytest.approx(20.0, rel=1e-6)
+
+        attrs = _attrs_of_nonzero_dps(_STORE_METRIC)
+        assert any(a.get("l2_name") == "nixl" for a in attrs)
+
+    def test_drains_pending_dict_on_completed(self, subscriber):
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=7, t=0.0, total_bytes=1_000)
+        )
+        assert (0, 7) in subscriber._pending_store
+
+        subscriber._on_store_completed(_store_completed(task_id=7, t=0.1))
+        assert (0, 7) not in subscriber._pending_store
+
+
+class TestLoadThroughput:
+    def test_records_gbps_with_l2_name(self, subscriber):
+        count_before = _total_count(_LOAD_METRIC)
+        sum_before = _sum(_LOAD_METRIC)
+
+        # 500 MB in 0.05 s -> 10 GB/s
+        subscriber._on_load_submitted(
+            _load_submitted(
+                request_id=42,
+                t=2000.0,
+                adapter_index=1,
+                l2_name="mooncake_store",
+                total_bytes=500_000_000,
+            )
+        )
+        subscriber._on_load_completed(
+            _load_completed(
+                request_id=42,
+                t=2000.05,
+                adapter_index=1,
+                l2_name="mooncake_store",
+            )
+        )
+
+        assert _total_count(_LOAD_METRIC) == count_before + 1
+        assert _sum(_LOAD_METRIC) - sum_before == pytest.approx(10.0, rel=1e-6)
+
+        attrs = _attrs_of_nonzero_dps(_LOAD_METRIC)
+        assert any(a.get("l2_name") == "mooncake_store" for a in attrs)
+
+
+# ---------------------------------------------------------------------------
+# Edge cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    def test_completed_without_submitted_is_noop(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        subscriber._on_store_completed(_store_completed(task_id=999, t=1.0))
+        assert _total_count(_STORE_METRIC) == count_before
+
+    def test_zero_bytes_is_noop(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=3, t=0.0, total_bytes=0)
+        )
+        subscriber._on_store_completed(_store_completed(task_id=3, t=0.1))
+        assert _total_count(_STORE_METRIC) == count_before
+
+    def test_nonpositive_duration_is_noop(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=4, t=5.0, total_bytes=10**9)
+        )
+        subscriber._on_store_completed(_store_completed(task_id=4, t=5.0))
+        assert _total_count(_STORE_METRIC) == count_before
+
+    def test_missing_correlation_fields_skips(self, subscriber):
+        # Missing task_id on the submitted event.
+        subscriber._on_store_submitted(
+            Event(
+                event_type=EventType.L2_STORE_SUBMITTED,
+                timestamp=1.0,
+                metadata={"adapter_index": 0, "l2_name": "fs"},
+            )
+        )
+        assert len(subscriber._pending_store) == 0
+
+    def test_same_task_id_different_adapters_do_not_collide(self, subscriber):
+        # Task IDs are only unique per-adapter; the compound key must
+        # keep different adapters separate.
+        count_before = _total_count(_STORE_METRIC)
+
+        subscriber._on_store_submitted(
+            _store_submitted(
+                task_id=1,
+                t=100.0,
+                adapter_index=0,
+                l2_name="fs",
+                total_bytes=1_000_000_000,
+            )
+        )
+        subscriber._on_store_submitted(
+            _store_submitted(
+                task_id=1,
+                t=100.0,
+                adapter_index=1,
+                l2_name="nixl",
+                total_bytes=1_000_000_000,
+            )
+        )
+        assert (0, 1) in subscriber._pending_store
+        assert (1, 1) in subscriber._pending_store
+
+        subscriber._on_store_completed(
+            _store_completed(task_id=1, t=100.1, adapter_index=0, l2_name="fs")
+        )
+        subscriber._on_store_completed(
+            _store_completed(task_id=1, t=100.1, adapter_index=1, l2_name="nixl")
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before + 2
+        assert (0, 1) not in subscriber._pending_store
+        assert (1, 1) not in subscriber._pending_store
+
+    def test_store_and_load_dicts_are_independent(self, subscriber):
+        # Store and load use structurally similar compound keys but
+        # different pending dicts; no cross-pollination.
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=5, t=0.0, total_bytes=10**9)
+        )
+        subscriber._on_load_submitted(
+            _load_submitted(request_id=5, t=0.0, adapter_index=0, total_bytes=10**9)
+        )
+
+        subscriber._on_store_completed(_store_completed(task_id=5, t=0.1))
+        assert (0, 5) not in subscriber._pending_store
+        # Load pending dict untouched — different key space (request_id).
+        assert (5, 0) in subscriber._pending_load
+
+
+# ---------------------------------------------------------------------------
+# bytes_transferred override (fast-path-aware adapters)
+# ---------------------------------------------------------------------------
+
+
+class TestStoreBytesTransferred:
+    """Store path prefers ``bytes_transferred`` from the COMPLETED event
+    over the submitted-bytes cache when the adapter populates it."""
+
+    def test_uses_bytes_transferred_when_present(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        sum_before = _sum(_STORE_METRIC)
+
+        # Submitted = 10 GB but adapter actually transferred only 1 GB
+        # (rest were fast-pathed duplicates).  Over 0.25 s -> 4 GB/s,
+        # not 40 GB/s.
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=10, t=0.0, total_bytes=10_000_000_000)
+        )
+        subscriber._on_store_completed(
+            _store_completed(task_id=10, t=0.25, bytes_transferred=1_000_000_000)
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before + 1
+        assert _sum(_STORE_METRIC) - sum_before == pytest.approx(4.0, rel=1e-6)
+
+    def test_zero_bytes_transferred_drops_sample(self, subscriber):
+        count_before = _total_count(_STORE_METRIC)
+        sum_before = _sum(_STORE_METRIC)
+
+        # Adapter fast-pathed every key -- no real work, drop the sample
+        # even though submitted bytes and dt look reasonable.
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=11, t=0.0, total_bytes=10_000_000_000)
+        )
+        subscriber._on_store_completed(
+            _store_completed(task_id=11, t=0.1, bytes_transferred=0)
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before
+        assert _sum(_STORE_METRIC) == sum_before
+        # Pending dict still drained even when sample dropped.
+        assert (0, 11) not in subscriber._pending_store
+
+    def test_absent_field_falls_back_to_submitted_bytes(self, subscriber):
+        # Adapters that don't track per-task transfer bytes omit the
+        # field; behavior matches the load path -- submitted bytes / dt.
+        count_before = _total_count(_STORE_METRIC)
+        sum_before = _sum(_STORE_METRIC)
+
+        # 2 GB in 0.1 s -> 20 GB/s
+        subscriber._on_store_submitted(
+            _store_submitted(task_id=12, t=0.0, total_bytes=2_000_000_000)
+        )
+        subscriber._on_store_completed(
+            _store_completed(task_id=12, t=0.1)  # no bytes_transferred
+        )
+
+        assert _total_count(_STORE_METRIC) == count_before + 1
+        assert _sum(_STORE_METRIC) - sum_before == pytest.approx(20.0, rel=1e-6)
+
+
+# ---------------------------------------------------------------------------
+# End-to-end: drive through EventBus
+# ---------------------------------------------------------------------------
+
+
+class TestEventBusIntegration:
+    def test_store_pair_via_bus_records_metric(self):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        sub = L2ThroughputSubscriber()
+        bus.register_subscriber(sub)
+
+        count_before = _total_count(_STORE_METRIC)
+        bus.start()
+        bus.publish(
+            _store_submitted(
+                task_id=77,
+                t=100.0,
+                adapter_index=2,
+                l2_name="fs",
+                total_bytes=4_000_000_000,
+            )
+        )
+        bus.publish(
+            _store_completed(task_id=77, t=100.2, adapter_index=2, l2_name="fs")
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert _total_count(_STORE_METRIC) == count_before + 1
+        attrs = _attrs_of_nonzero_dps(_STORE_METRIC)
+        assert any(a.get("l2_name") == "fs" for a in attrs)
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_lookup.py b/tests/v1/mp_observability/subscribers/metrics/test_lookup.py
new file mode 100644
index 0000000..635b8aa
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_lookup.py
@@ -0,0 +1,360 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for LookupMetricsSubscriber.
+
+Uses ``InMemoryMetricReader`` to read back actual OTel counter values
+and assert exact counts after publishing known events through the EventBus.
+
+OTel only allows one MeterProvider per process, so we use a module-scoped
+provider and assert on counter **deltas** between before/after snapshots.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.lookup import (
+    LookupMetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_counters() -> dict[str, int]:
+    """Snapshot counter values, summed across attribute combinations."""
+    data = _reader.get_metrics_data()
+    result: dict[str, int] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                total = 0
+                any_value = False
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue  # skip histogram data points
+                    total += int(dp.value)
+                    any_value = True
+                if any_value:
+                    result[metric.name] = total
+    return result
+
+
+def _read_counters_by_attrs() -> dict[str, dict[tuple, int]]:
+    """Snapshot counter values keyed by (metric_name, sorted-attrs-tuple)."""
+    data = _reader.get_metrics_data()
+    result: dict[str, dict[tuple, int]] = {}
+    if data is None:
+        return result
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                for dp in metric.data.data_points:
+                    if not hasattr(dp, "value"):
+                        continue
+                    key = tuple(sorted(dict(dp.attributes).items()))
+                    result.setdefault(metric.name, {})[key] = int(dp.value)
+    return result
+
+
+def _counter_delta(before: dict[str, int], after: dict[str, int]) -> dict[str, int]:
+    """Compute the difference between two counter snapshots."""
+    all_keys = set(before) | set(after)
+    return {k: after.get(k, 0) - before.get(k, 0) for k in all_keys}
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = LookupMetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    """Capture counters before the test; yield a callable that returns deltas."""
+    before = _read_counters()
+
+    def get_delta() -> dict[str, int]:
+        return _counter_delta(before, _read_counters())
+
+    return get_delta
+
+
+# ---------------------------------------------------------------------------
+# Hit-rate counters
+# ---------------------------------------------------------------------------
+
+
+class TestLookupHitRateCounters:
+    def test_full_hit(self, bus, subscriber, snapshot):
+        """All requested tokens are found in L1+L2."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-1",
+                metadata={
+                    "found_count": 4,
+                    "requested_tokens": 1024,
+                    "hit_tokens": 1024,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.lookup_requested"] == 1024
+        assert delta["lmcache_mp.lookup_hit"] == 1024
+
+    def test_partial_hit(self, bus, subscriber, snapshot):
+        """A prefix of the requested tokens is served from cache."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-2",
+                metadata={
+                    "found_count": 2,
+                    "requested_tokens": 1024,
+                    "hit_tokens": 512,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.lookup_requested"] == 1024
+        assert delta["lmcache_mp.lookup_hit"] == 512
+
+    def test_full_miss(self, bus, subscriber, snapshot):
+        """Nothing is cached; both counters still receive the denominator."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-3",
+                metadata={
+                    "found_count": 0,
+                    "requested_tokens": 1024,
+                    "hit_tokens": 0,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta["lmcache_mp.lookup_requested"] == 1024
+        assert delta.get("lmcache_mp.lookup_hit", 0) == 0
+
+    def test_early_exit_contributes_zero(self, bus, subscriber, snapshot):
+        """Early-exit lookups (no layout_desc or empty chunk_hashes) emit
+        `MP_LOOKUP_PREFETCH_END` with both token fields set to 0, so they
+        must not move either counter — preserves the ratio."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-4",
+                metadata={
+                    "found_count": 0,
+                    "requested_tokens": 0,
+                    "hit_tokens": 0,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert delta.get("lmcache_mp.lookup_requested", 0) == 0
+        assert delta.get("lmcache_mp.lookup_hit", 0) == 0
+
+    def test_multiple_lookups_accumulate(self, bus, subscriber, snapshot):
+        """Counters should accumulate across multiple completed lookups."""
+        bus.start()
+        # 3 full-hit lookups @ 512 tokens each
+        for i in range(3):
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                    session_id=f"hit-{i}",
+                    metadata={
+                        "found_count": 2,
+                        "requested_tokens": 512,
+                        "hit_tokens": 512,
+                    },
+                )
+            )
+        # 2 partial-hit lookups: 1024 requested, 256 hit
+        for i in range(2):
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                    session_id=f"partial-{i}",
+                    metadata={
+                        "found_count": 1,
+                        "requested_tokens": 1024,
+                        "hit_tokens": 256,
+                    },
+                )
+            )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        # 3*512 + 2*1024 = 1536 + 2048 = 3584
+        assert delta["lmcache_mp.lookup_requested"] == 3584
+        # 3*512 + 2*256 = 1536 + 512 = 2048
+        assert delta["lmcache_mp.lookup_hit"] == 2048
+
+
+# ---------------------------------------------------------------------------
+# Subscription wiring
+# ---------------------------------------------------------------------------
+
+
+class TestLookupMetricsSubscriptions:
+    def test_subscribes_only_to_prefetch_end(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.MP_LOOKUP_PREFETCH_END in subs
+        # Must not subscribe to START — the denominator must not be attributed
+        # to lookups that will never fire END (abandoned, early-exit).
+        assert EventType.MP_LOOKUP_PREFETCH_START not in subs
+        assert len(subs) == 1
+
+
+# ---------------------------------------------------------------------------
+# Per-(model_name, cache_salt) label slicing
+# ---------------------------------------------------------------------------
+
+
+class TestLookupAttributeLabels:
+    def test_carries_model_name_and_cache_salt(self, bus, subscriber):
+        bus.start()
+        before = _read_counters_by_attrs()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-labeled",
+                metadata={
+                    "found_count": 2,
+                    "requested_tokens": 1024,
+                    "hit_tokens": 768,
+                    "model_name": "llama-3.1-8b",
+                    "cache_salt": "tenant-A",
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs()
+        attr_key = (
+            ("cache_salt", "tenant-A"),
+            ("model_name", "llama-3.1-8b"),
+        )
+        before_req = before.get("lmcache_mp.lookup_requested", {}).get(attr_key, 0)
+        before_hit = before.get("lmcache_mp.lookup_hit", {}).get(attr_key, 0)
+        after_req = after.get("lmcache_mp.lookup_requested", {}).get(attr_key, 0)
+        after_hit = after.get("lmcache_mp.lookup_hit", {}).get(attr_key, 0)
+        assert after_req == before_req + 1024
+        assert after_hit == before_hit + 768
+
+    def test_different_models_accumulate_independently(self, bus, subscriber):
+        bus.start()
+        before = _read_counters_by_attrs()
+        # 2 lookups on model-A, 1 on model-B, all same salt.
+        for _ in range(2):
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                    session_id="x",
+                    metadata={
+                        "found_count": 1,
+                        "requested_tokens": 256,
+                        "hit_tokens": 256,
+                        "model_name": "model-A",
+                        "cache_salt": "salt-1",
+                    },
+                )
+            )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="y",
+                metadata={
+                    "found_count": 1,
+                    "requested_tokens": 256,
+                    "hit_tokens": 256,
+                    "model_name": "model-B",
+                    "cache_salt": "salt-1",
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs()
+        a_key = (("cache_salt", "salt-1"), ("model_name", "model-A"))
+        b_key = (("cache_salt", "salt-1"), ("model_name", "model-B"))
+        req = "lmcache_mp.lookup_requested"
+        assert (
+            after.get(req, {}).get(a_key, 0) == before.get(req, {}).get(a_key, 0) + 512
+        )
+        assert (
+            after.get(req, {}).get(b_key, 0) == before.get(req, {}).get(b_key, 0) + 256
+        )
+
+    def test_missing_labels_record_without_attrs(self, bus, subscriber):
+        # Older event producers may not populate model_name / cache_salt;
+        # the counter should still record under the empty-attrs bucket
+        # rather than crashing.
+        bus.start()
+        before = _read_counters_by_attrs()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="legacy",
+                metadata={
+                    "found_count": 1,
+                    "requested_tokens": 128,
+                    "hit_tokens": 128,
+                },
+            )
+        )
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        after = _read_counters_by_attrs()
+        empty_key: tuple = ()
+        req = "lmcache_mp.lookup_requested"
+        assert (
+            after.get(req, {}).get(empty_key, 0)
+            == before.get(req, {}).get(empty_key, 0) + 128
+        )
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_sm_lifecycle.py b/tests/v1/mp_observability/subscribers/metrics/test_sm_lifecycle.py
new file mode 100644
index 0000000..43595cb
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_sm_lifecycle.py
@@ -0,0 +1,362 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the real-reuse-gap histograms emitted by ``SMLifecycleSubscriber``.
+
+Both histograms are driven by StorageManager read/write events:
+
+- ``lmcache_mp.real_reuse_gap`` — wall-clock gap between a
+  chunk's most recent access (read or write) and the next read.
+  Captures storage cost.
+- ``lmcache_mp.real_reuse_gap_objects`` — per-``cache_salt`` chunk-event
+  gap between two reads of the same chunk.  The counter advances on
+  every chunk access (read AND write, all chunks); the histogram
+  records gaps only on read events for sampled chunks.
+
+Both are tagged with ``cache_salt``.  Writes never emit a sample —
+only ``read → read`` and ``write → read`` transitions do.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.sm_lifecycle import (
+    SMLifecycleSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.otel_setup import reader as _reader
+
+_DRAIN_WAIT = 0.15
+
+
+class _Key:
+    """ObjectKey-shape stand-in for L1 event metadata."""
+
+    __slots__ = ("chunk_hash", "cache_salt", "kv_rank")
+
+    def __init__(self, chunk_hash: str, cache_salt: str = "", kv_rank: int = 0):
+        self.chunk_hash = chunk_hash
+        self.cache_salt = cache_salt
+        self.kv_rank = kv_rank
+
+    def __hash__(self) -> int:
+        return hash((self.chunk_hash, self.cache_salt, self.kv_rank))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, _Key):
+            return NotImplemented
+        return (
+            self.chunk_hash == other.chunk_hash
+            and self.cache_salt == other.cache_salt
+            and self.kv_rank == other.kv_rank
+        )
+
+
+def _l1_read(keys: list) -> Event:
+    return Event(
+        event_type=EventType.SM_READ_PREFETCHED_FINISHED,
+        metadata={"succeeded_keys": keys, "failed_keys": []},
+    )
+
+
+def _l1_write(keys: list) -> Event:
+    return Event(
+        event_type=EventType.SM_WRITE_FINISHED,
+        metadata={"succeeded_keys": keys, "failed_keys": []},
+    )
+
+
+def _totals_by_salt(name: str) -> dict[str, tuple[float, int]]:
+    """Return ``{cache_salt: (sum, count)}`` for histogram *name*."""
+    data = _reader.get_metrics_data()
+    out: dict[str, tuple[float, int]] = {}
+    if data is None:
+        return out
+    for resource_metrics in data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                if metric.name != name:
+                    continue
+                for dp in metric.data.data_points:
+                    salt = dp.attributes.get("cache_salt", "<missing>")
+                    prev_sum, prev_count = out.get(salt, (0.0, 0))
+                    out[salt] = (
+                        prev_sum + float(dp.sum),
+                        prev_count + int(dp.count),
+                    )
+    return out
+
+
+def _delta(
+    before: dict[str, tuple[float, int]], after: dict[str, tuple[float, int]]
+) -> dict[str, tuple[float, int]]:
+    salts = set(before) | set(after)
+    return {
+        s: (
+            after.get(s, (0.0, 0))[0] - before.get(s, (0.0, 0))[0],
+            after.get(s, (0.0, 0))[1] - before.get(s, (0.0, 0))[1],
+        )
+        for s in salts
+    }
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = SMLifecycleSubscriber(sample_rate=1.0)
+    bus.register_subscriber(sub)
+    return sub
+
+
+class TestReadEmitsGap:
+    def test_read_then_read_records_gap(self, bus, subscriber):
+        before_t = _totals_by_salt("lmcache_mp.real_reuse_gap")
+        before_c = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("h1", cache_salt="t-a")]))  # counter=1, seed
+        bus.publish(_l1_read([_Key("h1", cache_salt="t-a")]))  # counter=2, gap=1
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        time_d = _delta(before_t, _totals_by_salt("lmcache_mp.real_reuse_gap"))
+        chunks_d = _delta(
+            before_c, _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+        )
+        assert time_d.get("t-a", (0.0, 0))[1] == 1
+        assert chunks_d.get("t-a", (0.0, 0)) == (1.0, 1)
+
+    def test_write_then_read_records_gap(self, bus, subscriber):
+        """Write seeds the anchor; first read records gap = read - write."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_write([_Key("h1", cache_salt="t-w")]))  # counter=1, seed
+        bus.publish(_l1_read([_Key("h1", cache_salt="t-w")]))  # counter=2, gap=1
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-w", (0.0, 0)) == (1.0, 1)
+
+    def test_first_access_is_cold_no_emission(self, bus, subscriber):
+        """The very first event for a chunk seeds; no histogram sample."""
+        before_t = _totals_by_salt("lmcache_mp.real_reuse_gap")
+        before_c = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("cold", cache_salt="t-cold")]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        t_d = _delta(before_t, _totals_by_salt("lmcache_mp.real_reuse_gap"))
+        c_d = _delta(before_c, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert t_d.get("t-cold", (0.0, 0))[1] == 0
+        assert c_d.get("t-cold", (0.0, 0))[1] == 0
+
+
+class TestWriteDoesNotEmit:
+    def test_write_then_write_no_emission(self, bus, subscriber):
+        """Write → write does not record a sample."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_write([_Key("k", cache_salt="t-ww")]))
+        bus.publish(_l1_write([_Key("k", cache_salt="t-ww")]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-ww", (0.0, 0))[1] == 0
+
+    def test_read_then_write_no_emission(self, bus, subscriber):
+        """Read → write does not record a sample.  Write only updates anchor."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("k", cache_salt="t-rw")]))  # seed
+        bus.publish(_l1_write([_Key("k", cache_salt="t-rw")]))  # no emit
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-rw", (0.0, 0))[1] == 0
+
+    def test_write_updates_anchor_for_next_read(self, bus, subscriber):
+        """After read → write, the next read measures from the write."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("k", cache_salt="t-x")]))  # counter=1
+        bus.publish(_l1_read([_Key("a", cache_salt="t-x")]))  # counter=2
+        bus.publish(_l1_write([_Key("k", cache_salt="t-x")]))  # counter=3, anchor
+        bus.publish(_l1_read([_Key("b", cache_salt="t-x")]))  # counter=4
+        bus.publish(_l1_read([_Key("k", cache_salt="t-x")]))  # counter=5, gap=5-3=2
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        # Only sample is the final read of k, gap = 5 - 3 = 2.
+        assert delta.get("t-x", (0.0, 0)) == (2.0, 1)
+
+
+class TestChunksGapCounter:
+    def test_counter_advances_for_all_accesses(self, bus, subscriber):
+        """Counter bumps on every read AND write, all chunks under salt."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("target", cache_salt="t-b")]))  # counter=1
+        # Mixed reads + writes of unrelated chunks bump the counter.
+        bus.publish(_l1_read([_Key("c0", cache_salt="t-b")]))  # 2
+        bus.publish(_l1_write([_Key("c1", cache_salt="t-b")]))  # 3
+        bus.publish(_l1_read([_Key("c2", cache_salt="t-b")]))  # 4
+        bus.publish(_l1_write([_Key("c3", cache_salt="t-b")]))  # 5
+        bus.publish(_l1_read([_Key("target", cache_salt="t-b")]))  # 6, gap=5
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-b", (0.0, 0)) == (5.0, 1)
+
+    def test_cache_salt_isolates_counter(self, bus, subscriber):
+        """Per-salt counter: t-x accesses don't bump t-y's gap."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("target", cache_salt="t-y")]))  # y=1
+        bus.publish(
+            _l1_read(
+                [
+                    _Key("a", cache_salt="t-x"),
+                    _Key("b", cache_salt="t-x"),
+                    _Key("c", cache_salt="t-x"),
+                ]
+            )
+        )  # x=1..3
+        bus.publish(_l1_read([_Key("target", cache_salt="t-y")]))  # y=2, gap=1
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-y", (0.0, 0)) == (1.0, 1)
+        # tenant-x has no second read of any chunk → no sample.
+        assert delta.get("t-x", (0.0, 0))[1] == 0
+
+    def test_cache_salt_isolates_chunk_identity(self, bus, subscriber):
+        """Same chunk_hash under different cache_salts = different keys."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("shared", cache_salt="t-p")]))
+        bus.publish(_l1_read([_Key("shared", cache_salt="t-q")]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        # Both tenants saw "shared" first time → no samples.
+        assert delta.get("t-p", (0.0, 0))[1] == 0
+        assert delta.get("t-q", (0.0, 0))[1] == 0
+
+
+class TestSampling:
+    def test_unsampled_first_sighting_is_dropped(self, bus):
+        """Near-zero sample rate → cold seed skipped → no later sample."""
+        sub = SMLifecycleSubscriber(sample_rate=1e-9)
+        bus.register_subscriber(sub)
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        for _ in range(3):
+            bus.publish(_l1_read([_Key("unsamp", cache_salt="t-u")]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-u", (0.0, 0))[1] == 0
+
+    def test_unsampled_chunks_still_advance_counter(self, bus):
+        """Counter bumps on every access regardless of sampling.
+
+        Sampling decides which chunks are in the histogram, not which
+        chunks contribute to the per-salt event count.
+        """
+        # Sample rate 1.0 for "target", ~0 for others — but `_should_sample`
+        # is hash-deterministic, so we can't easily target a specific chunk.
+        # Instead: sample_rate=1.0, but verify the counter math with mixed
+        # access types; the previous test class already covered counter
+        # progression under read+write.  Here we verify the cap path
+        # (LRU eviction) does not break the counter semantics.
+        sub = SMLifecycleSubscriber(sample_rate=1.0)
+        bus.register_subscriber(sub)
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read([_Key("k", cache_salt="t-cnt")]))  # 1, seed
+        # Many unrelated chunks of varied access types.
+        for i in range(10):
+            ev = _l1_write if i % 2 else _l1_read
+            bus.publish(ev([_Key(f"c{i}", cache_salt="t-cnt")]))
+        bus.publish(_l1_read([_Key("k", cache_salt="t-cnt")]))  # 12, gap=11
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-cnt", (0.0, 0)) == (11.0, 1)
+
+
+class TestTPFanout:
+    def test_read_dedupes_tp_fanout(self, bus, subscriber):
+        """Same logical chunk fanned across TP ranks counts as one access."""
+        keys = [_Key("tp-chunk", cache_salt="t-tp", kv_rank=r) for r in range(4)]
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+
+        bus.start()
+        bus.publish(_l1_read(keys))  # counter=1 (deduped)
+        bus.publish(_l1_read(keys))  # counter=2, gap=1
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        # 4 ObjectKeys per event, 1 logical chunk, 2 events → counter=2,
+        # one sample with gap=1.
+        assert delta.get("t-tp", (0.0, 0)) == (1.0, 1)
+
+    def test_write_dedupes_tp_fanout(self, bus, subscriber):
+        """Write fanout produces a single anchor, not one per rank."""
+        before = _totals_by_salt("lmcache_mp.real_reuse_gap_objects")
+        keys = [_Key("tp", cache_salt="t-tpw", kv_rank=r) for r in range(4)]
+
+        bus.start()
+        bus.publish(_l1_write(keys))  # counter=1, seed (deduped)
+        bus.publish(_l1_read([_Key("tp", cache_salt="t-tpw")]))  # 2, gap=1
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = _delta(before, _totals_by_salt("lmcache_mp.real_reuse_gap_objects"))
+        assert delta.get("t-tpw", (0.0, 0)) == (1.0, 1)
+
+
+class TestBounds:
+    def test_track_dict_bounded_by_cap(self, bus, subscriber, monkeypatch):
+        """Random eviction on overflow: dict size never exceeds cap."""
+        # First Party
+        from lmcache.v1.mp_observability.subscribers.metrics import sm_lifecycle as smlc
+
+        monkeypatch.setattr(smlc, "_REUSE_TRACK_CAP", 8)
+
+        bus.start()
+        for i in range(50):
+            bus.publish(_l1_read([_Key(f"h{i}", cache_salt="t-cap")]))
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert len(subscriber._reuse_track) <= 8
diff --git a/tests/v1/mp_observability/subscribers/metrics/test_timeout.py b/tests/v1/mp_observability/subscribers/metrics/test_timeout.py
new file mode 100644
index 0000000..7f72493
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/metrics/test_timeout.py
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for TimeoutMetricsSubscriber.
+
+Verifies that ``TIMEOUT_RAISED`` events increment the ``lmcache_mp.timeouts``
+OTel counter, tagged by ``exception_type``. Uses the shared
+``InMemoryMetricReader`` to assert on counter deltas keyed by attributes.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.metrics.timeout import (
+    TimeoutMetricsSubscriber,
+)
+from tests.v1.mp_observability.subscribers.metrics.counter_helpers import (
+    counter_delta,
+    counter_value,
+    read_tagged_counters,
+)
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def subscriber(bus):
+    sub = TimeoutMetricsSubscriber()
+    bus.register_subscriber(sub)
+    return sub
+
+
+@pytest.fixture
+def snapshot():
+    before = read_tagged_counters()
+
+    def get_delta():
+        return counter_delta(before, read_tagged_counters())
+
+    return get_delta
+
+
+def _publish_timeout(bus, exception_type: str = "LMCacheTimeoutError") -> None:
+    bus.publish(
+        Event(
+            event_type=EventType.TIMEOUT_RAISED,
+            metadata={
+                "message": "boom",
+                "exception_type": exception_type,
+                "stacktrace": "trace",
+            },
+        )
+    )
+
+
+class TestTimeoutMetricsSubscriber:
+    def test_subscription_covers_timeout_event(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.TIMEOUT_RAISED in subs
+        assert len(subs) == 1
+
+    def test_single_timeout_increments_counter(self, bus, subscriber, snapshot):
+        bus.start()
+        _publish_timeout(bus)
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta, "lmcache_mp.timeouts", exception_type="LMCacheTimeoutError"
+            )
+            == 1
+        )
+
+    def test_accumulates_across_events(self, bus, subscriber, snapshot):
+        bus.start()
+        for _ in range(5):
+            _publish_timeout(bus)
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta, "lmcache_mp.timeouts", exception_type="LMCacheTimeoutError"
+            )
+            == 5
+        )
+
+    def test_different_types_counted_separately(self, bus, subscriber, snapshot):
+        bus.start()
+        _publish_timeout(bus, "LMCacheTimeoutError")
+        _publish_timeout(bus, "MyTimeout")
+        _publish_timeout(bus, "MyTimeout")
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        delta = snapshot()
+        assert (
+            counter_value(
+                delta, "lmcache_mp.timeouts", exception_type="LMCacheTimeoutError"
+            )
+            == 1
+        )
+        assert (
+            counter_value(delta, "lmcache_mp.timeouts", exception_type="MyTimeout") == 2
+        )
diff --git a/tests/v1/mp_observability/subscribers/tracing/__init__.py b/tests/v1/mp_observability/subscribers/tracing/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/tracing/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/mp_observability/subscribers/tracing/test_cb_server.py b/tests/v1/mp_observability/subscribers/tracing/test_cb_server.py
new file mode 100644
index 0000000..e8a7dab
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/tracing/test_cb_server.py
@@ -0,0 +1,1076 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for BlendTracingSubscriber."""
+
+# Standard
+from unittest.mock import patch
+import time
+
+# Third Party
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.tracing.cb_server import (
+    BlendTracingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import (
+    SpanRegistry,
+)
+import lmcache.v1.mp_observability.subscribers.tracing.cb_server as cb_server_module
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def registry():
+    return SpanRegistry()
+
+
+@pytest.fixture
+def subscriber(registry, bus):
+    sub = BlendTracingSubscriber(registry)
+    bus.register_subscriber(sub)
+    return sub
+
+
+class TestBlendTracingSubscriber:
+    def test_subscriptions_cover_all_cb_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.CB_REQUEST_START in subs
+        assert EventType.CB_REQUEST_END in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_SUBMITTED in subs
+        assert EventType.CB_RETRIEVE_SUBMITTED in subs
+        assert EventType.CB_STORE_FINAL_SUBMITTED in subs
+        assert EventType.CB_LOOKUP_START in subs
+        assert EventType.CB_LOOKUP_END in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_START in subs
+        assert EventType.CB_STORE_PRE_COMPUTED_END in subs
+        assert EventType.CB_RETRIEVE_START in subs
+        assert EventType.CB_RETRIEVE_END in subs
+        assert EventType.CB_STORE_FINAL_START in subs
+        assert EventType.CB_STORE_FINAL_END in subs
+        assert EventType.CB_FINGERPRINTS_REGISTERED in subs
+        assert EventType.CB_CHUNKS_EVICTED in subs
+
+    # ------------------------------------------------------------------
+    # Root span creation
+    # ------------------------------------------------------------------
+
+    def test_root_span_created_on_request_start(self, bus, registry, subscriber):
+        bus.start()
+        bus.publish(Event(event_type=EventType.CB_REQUEST_START, session_id="req-root"))
+        time.sleep(0.15)
+        assert registry.get("req-root", "cb.request") is not None
+        bus.stop()
+
+    def test_no_root_span_before_any_event(self, registry):
+        assert registry.get("any-session", "cb.request") is None
+
+    # ------------------------------------------------------------------
+    # Session end closes root immediately when no GPU ops in flight
+    # ------------------------------------------------------------------
+
+    def test_session_end_closes_root_immediately_when_no_gpu_ops(
+        self, bus, registry, subscriber
+    ):
+        bus.start()
+        now = time.time()
+        sid = "req-lookup-only"
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 64},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "num_tokens": 64,
+                    "fingerprint_hits": 2,
+                    "storage_hits": 2,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "cb.request") is None
+        assert sid not in subscriber._pending_gpu_ops
+        assert len(subscriber._pending) == 0
+
+    # ------------------------------------------------------------------
+    # Deferred close: SESSION_END races GPU store_pre_computed
+    # ------------------------------------------------------------------
+
+    def test_session_end_deferred_until_store_pre_computed_finishes(
+        self, bus, registry, subscriber
+    ):
+        bus.start()
+        now = time.time()
+        sid = "req-deferred-store-pre"
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"instance_id": 0},
+            )
+        )
+        # SESSION_END arrives before GPU store completes
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        # Root should still be open
+        assert registry.get(sid, "cb.request") is not None
+        assert sid in subscriber._deferred_session_end_ts
+
+        # GPU store completes
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"instance_id": 0, "num_tokens": 64},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id=sid,
+                timestamp=now + 0.050,
+                metadata={"instance_id": 0, "stored_chunks": 4, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "cb.request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+        assert sid not in subscriber._pending_gpu_ops
+
+    # ------------------------------------------------------------------
+    # Deferred close: SESSION_END races GPU retrieve
+    # ------------------------------------------------------------------
+
+    def test_session_end_deferred_until_retrieve_finishes(
+        self, bus, registry, subscriber
+    ):
+        bus.start()
+        now = time.time()
+        sid = "req-deferred-retrieve"
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"instance_id": 1},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        assert registry.get(sid, "cb.request") is not None
+        assert sid in subscriber._deferred_session_end_ts
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"instance_id": 1, "num_chunks": 3},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id=sid,
+                timestamp=now + 0.050,
+                metadata={"instance_id": 1, "num_chunks": 3, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "cb.request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+        assert sid not in subscriber._pending_gpu_ops
+
+    # ------------------------------------------------------------------
+    # Deferred close: SESSION_END races GPU store_final
+    # ------------------------------------------------------------------
+
+    def test_session_end_deferred_until_store_final_finishes(
+        self, bus, registry, subscriber
+    ):
+        bus.start()
+        now = time.time()
+        sid = "req-deferred-store-final"
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"instance_id": 2},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        assert registry.get(sid, "cb.request") is not None
+        assert sid in subscriber._deferred_session_end_ts
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"instance_id": 2, "num_tokens": 256},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_END,
+                session_id=sid,
+                timestamp=now + 0.060,
+                metadata={"instance_id": 2, "stored_chunks": 16, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "cb.request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+        assert sid not in subscriber._pending_gpu_ops
+
+    # ------------------------------------------------------------------
+    # Multiple GPU ops: all must finish before root closes
+    # ------------------------------------------------------------------
+
+    def test_multiple_gpu_ops_all_must_finish(self, bus, registry, subscriber):
+        bus.start()
+        now = time.time()
+        sid = "req-multi-gpu-ops"
+
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"instance_id": 0},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.002,
+                metadata={"instance_id": 0},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        # Both in flight — root still open
+        assert registry.get(sid, "cb.request") is not None
+
+        # Store finishes first — retrieve still pending, root stays open
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"instance_id": 0, "num_tokens": 64},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id=sid,
+                timestamp=now + 0.030,
+                metadata={"instance_id": 0, "stored_chunks": 4, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        assert registry.get(sid, "cb.request") is not None
+
+        # Retrieve finishes — all done, root closes
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_START,
+                session_id=sid,
+                timestamp=now + 0.040,
+                metadata={"instance_id": 0, "num_chunks": 4},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id=sid,
+                timestamp=now + 0.060,
+                metadata={"instance_id": 0, "num_chunks": 4, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "cb.request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+
+    # ------------------------------------------------------------------
+    # Child span lifecycles
+    # ------------------------------------------------------------------
+
+    def test_lookup_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id="req-lookup",
+                metadata={"num_tokens": 128},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id="req-lookup",
+                metadata={
+                    "num_tokens": 128,
+                    "fingerprint_hits": 3,
+                    "storage_hits": 2,
+                    "stale_chunks": 1,
+                    "no_gpu_context": False,
+                },
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_store_pre_computed_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id="req-sp",
+                metadata={"instance_id": 0, "num_tokens": 64},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id="req-sp",
+                metadata={"instance_id": 0, "stored_chunks": 4, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_retrieve_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_START,
+                session_id="req-ret",
+                metadata={"instance_id": 1, "num_chunks": 3},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_RETRIEVE_END,
+                session_id="req-ret",
+                metadata={"instance_id": 1, "num_chunks": 3, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_store_final_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_START,
+                session_id="req-sf",
+                metadata={"instance_id": 2, "num_tokens": 512},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_FINAL_END,
+                session_id="req-sf",
+                metadata={"instance_id": 2, "stored_chunks": 32, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    # ------------------------------------------------------------------
+    # Point events
+    # ------------------------------------------------------------------
+
+    def test_fingerprints_registered_no_crash(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_FINGERPRINTS_REGISTERED,
+                session_id="req-fp",
+                metadata={"num_chunks": 8, "num_tokens": 256},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    def test_chunks_evicted_no_crash(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_CHUNKS_EVICTED,
+                session_id="req-ev",
+                metadata={"num_chunks": 2},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+    # ------------------------------------------------------------------
+    # Error resilience
+    # ------------------------------------------------------------------
+
+    def test_unmatched_end_does_not_crash(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_END,
+                session_id="orphan",
+                metadata={"stored_chunks": 2, "success": True},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_unmatched_start_cleaned_on_shutdown(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.CB_STORE_PRE_COMPUTED_START,
+                session_id="leaked",
+                metadata={"instance_id": 0, "num_tokens": 64},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        subscriber.shutdown()
+        assert len(subscriber._pending) == 0
+
+    def test_multiple_concurrent_sessions(self, bus, subscriber):
+        bus.start()
+        for i in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_START,
+                    session_id=f"req-{i}",
+                    metadata={"num_tokens": 100},
+                )
+            )
+        for i in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.CB_LOOKUP_END,
+                    session_id=f"req-{i}",
+                    metadata={
+                        "num_tokens": 100,
+                        "fingerprint_hits": 2,
+                        "storage_hits": 2,
+                        "stale_chunks": 0,
+                        "no_gpu_context": False,
+                    },
+                )
+            )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+
+class TestCBHitRateAttributes:
+    """Verify hit_tokens / requested_tokens / hit_rate are set on cb.request root span.
+
+    Uses a real OTel TracerProvider backed by InMemorySpanExporter so that span
+    attributes are actually recorded.  The module-level ``_tracer`` is patched
+    for the duration of each test; ``_HAS_OTEL`` is forced True.
+    """
+
+    @pytest.fixture
+    def exporter(self):
+        """Real OTel provider with in-memory exporter; patches module tracer."""
+        exp = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(exp))
+        real_tracer = provider.get_tracer("lmcache_mp.blend")
+        with (
+            patch.object(cb_server_module, "_tracer", real_tracer),
+            patch.object(cb_server_module, "_HAS_OTEL", True),
+        ):
+            yield exp
+        exp.shutdown()
+
+    def _root_span(self, exporter: InMemorySpanExporter, sid: str):
+        """Return the finished cb.request root span for *sid*, or None."""
+        for span in exporter.get_finished_spans():
+            if span.name == "cb.request" and span.attributes.get("session_id") == sid:
+                return span
+        return None
+
+    def test_hit_rate_attrs_set_on_root_span(self, exporter):
+        """CB_LOOKUP_END with hit_tokens=512, requested_tokens=1024 → hit_rate=0.5."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(BlendTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "cb-hr-normal"
+
+        bus.publish(
+            Event(event_type=EventType.CB_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 1024},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "num_tokens": 1024,
+                    "fingerprint_hits": 4,
+                    "storage_hits": 2,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                    "hit_tokens": 512,
+                    "requested_tokens": 1024,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["hit_tokens"] == 512
+        assert root.attributes["requested_tokens"] == 1024
+        assert abs(root.attributes["hit_rate"] - 0.5) < 1e-9
+
+    def test_hit_rate_zero_when_requested_tokens_is_zero(self, exporter):
+        """CB_LOOKUP_END with requested_tokens=0 yields hit_rate=0.0 without error."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(BlendTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "cb-hr-zero"
+
+        bus.publish(
+            Event(event_type=EventType.CB_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 0},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "num_tokens": 0,
+                    "fingerprint_hits": 0,
+                    "storage_hits": 0,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                    "hit_tokens": 0,
+                    "requested_tokens": 0,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["hit_tokens"] == 0
+        assert root.attributes["requested_tokens"] == 0
+        assert root.attributes["hit_rate"] == 0.0
+
+    def test_total_miss_hit_rate(self, exporter):
+        """CB_LOOKUP_END with storage_hits=0 but requested_tokens>0 → hit_rate=0.0."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(BlendTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "cb-hr-miss"
+
+        bus.publish(
+            Event(event_type=EventType.CB_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 1024},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "num_tokens": 1024,
+                    "fingerprint_hits": 0,
+                    "storage_hits": 0,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                    "hit_tokens": 0,
+                    "requested_tokens": 1024,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["hit_tokens"] == 0
+        assert root.attributes["requested_tokens"] == 1024
+        assert root.attributes["hit_rate"] == 0.0
+
+    def test_prefix_hits_attr_set_on_root_span(self, exporter):
+        """CB_LOOKUP_END with prefix_hits=2 stamps prefix_hits=2 on root span."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(BlendTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "cb-prefix-hits"
+
+        bus.publish(
+            Event(event_type=EventType.CB_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 512},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "num_tokens": 512,
+                    "fingerprint_hits": 0,
+                    "prefix_hits": 2,
+                    "storage_hits": 2,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                    "hit_tokens": 512,
+                    "requested_tokens": 512,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["prefix_hits"] == 2
+        assert root.attributes["hit_tokens"] == 512
+        assert root.attributes["hit_rate"] == 1.0
+
+    def test_prefix_hits_defaults_to_zero_when_absent(self, exporter):
+        """CB_LOOKUP_END without prefix_hits stamps prefix_hits=0 (backward compat)."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(BlendTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "cb-prefix-absent"
+
+        bus.publish(
+            Event(event_type=EventType.CB_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 256},
+            )
+        )
+        # Omit prefix_hits to simulate an older server payload
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "num_tokens": 256,
+                    "fingerprint_hits": 1,
+                    "storage_hits": 1,
+                    "stale_chunks": 0,
+                    "no_gpu_context": False,
+                    "hit_tokens": 256,
+                    "requested_tokens": 256,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["prefix_hits"] == 0
+
+    def test_hit_rate_includes_prefix_and_non_prefix(self, exporter):
+        """V3 hit_rate numerator = prefix_hit_tokens + non_prefix_hit_tokens;
+        both are also recorded as separate attributes on the root span."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        bus.register_subscriber(BlendTracingSubscriber(SpanRegistry()))
+        bus.start()
+        now = time.time()
+        sid = "cb-hr-split"
+        bus.publish(
+            Event(event_type=EventType.CB_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"num_tokens": 1024},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_LOOKUP_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "prefix_hit_tokens": 256,
+                    "non_prefix_hit_tokens": 256,
+                    "hit_tokens": 512,  # = prefix + non_prefix (set by blend_v3)
+                    "requested_tokens": 1024,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.CB_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.011,
+            )
+        )
+        time.sleep(0.2)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["prefix_hit_tokens"] == 256
+        assert root.attributes["non_prefix_hit_tokens"] == 256
+        assert root.attributes["hit_tokens"] == 512
+        assert root.attributes["hit_rate"] == 0.5
+
+
+class TestCBLookupSubspans:
+    """V3 lookup sub-spans (cb.fingerprint_match / cb.sparse_prefetch) nest under
+    cb.lookup, not the cb.request root. The prefix lookup has no cb.* span (it is
+    traced by mp.lookup_prefetch); prefix_chunks rides on cb.lookup."""
+
+    @pytest.fixture
+    def exporter(self):
+        exp = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(exp))
+        real_tracer = provider.get_tracer("lmcache_mp.blend")
+        with (
+            patch.object(cb_server_module, "_tracer", real_tracer),
+            patch.object(cb_server_module, "_HAS_OTEL", True),
+        ):
+            yield exp
+        exp.shutdown()
+
+    def _spans_by_name(self, exporter: InMemorySpanExporter, sid: str):
+        return {
+            s.name: s
+            for s in exporter.get_finished_spans()
+            if s.attributes.get("session_id") == sid
+        }
+
+    def test_lookup_subspans_nest_under_cb_lookup(self, exporter):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        bus.register_subscriber(BlendTracingSubscriber(SpanRegistry()))
+        bus.start()
+        now = time.time()
+        sid = "cb-subspans"
+        seq = [
+            (EventType.CB_REQUEST_START, {}),
+            (EventType.CB_LOOKUP_START, {"num_tokens": 1024}),
+            (EventType.CB_FINGERPRINT_MATCH_START, {}),
+            (EventType.CB_FINGERPRINT_MATCH_END, {"matches": 7}),
+            (EventType.CB_SPARSE_PREFETCH_START, {"n_chunks": 5}),
+            (EventType.CB_SPARSE_PREFETCH_END, {"found_keys": 5}),
+            (EventType.CB_LOOKUP_END, {"num_tokens": 1024, "prefix_chunks": 2}),
+            (EventType.CB_REQUEST_END, {}),
+        ]
+        for i, (et, md) in enumerate(seq):
+            bus.publish(
+                Event(
+                    event_type=et,
+                    session_id=sid,
+                    timestamp=now + i * 0.001,
+                    metadata=md,
+                )
+            )
+        time.sleep(0.3)
+        bus.stop()
+
+        spans = self._spans_by_name(exporter, sid)
+        for name in (
+            "cb.lookup",
+            "cb.fingerprint_match",
+            "cb.sparse_prefetch",
+        ):
+            assert name in spans, f"missing span {name}; have {sorted(spans)}"
+        # No cb.prefix_lookup span (traced by mp.lookup_prefetch instead).
+        assert "cb.prefix_lookup" not in spans
+        lookup_id = spans["cb.lookup"].context.span_id
+        for name in ("cb.fingerprint_match", "cb.sparse_prefetch"):
+            assert spans[name].parent is not None, f"{name} has no parent span"
+            assert spans[name].parent.span_id == lookup_id, (
+                f"{name} should nest under cb.lookup"
+            )
+        # cb.lookup itself nests under the cb.request root (unchanged behavior).
+        assert spans["cb.lookup"].parent.span_id == spans["cb.request"].context.span_id
+        # sub-span metadata propagates as attributes.
+        assert spans["cb.fingerprint_match"].attributes.get("matches") == "7"
+        # prefix coverage rides on cb.lookup (no dedicated prefix span).
+        assert spans["cb.lookup"].attributes.get("prefix_chunks") == "2"
+        assert spans["cb.sparse_prefetch"].attributes.get("found_keys") == "5"
+
+    def test_coordinator_match_span_nests_under_cb_lookup(self, exporter):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        bus.register_subscriber(BlendTracingSubscriber(SpanRegistry()))
+        bus.start()
+        now = time.time()
+        sid = "cb-coord-match"
+        seq = [
+            (EventType.CB_REQUEST_START, {}),
+            (EventType.CB_LOOKUP_START, {"num_tokens": 1024}),
+            (EventType.CB_COORDINATOR_MATCH_START, {}),
+            (EventType.CB_COORDINATOR_MATCH_END, {"matches": 3, "timed_out": False}),
+            (EventType.CB_LOOKUP_END, {"num_tokens": 1024, "prefix_chunks": 2}),
+            (EventType.CB_REQUEST_END, {}),
+        ]
+        for i, (et, md) in enumerate(seq):
+            bus.publish(
+                Event(
+                    event_type=et,
+                    session_id=sid,
+                    timestamp=now + i * 0.001,
+                    metadata=md,
+                )
+            )
+        time.sleep(0.3)
+        bus.stop()
+
+        spans = self._spans_by_name(exporter, sid)
+        assert "cb.coordinator_match" in spans, (
+            f"missing cb.coordinator_match; have {sorted(spans)}"
+        )
+        assert (
+            spans["cb.coordinator_match"].parent.span_id
+            == spans["cb.lookup"].context.span_id
+        ), "cb.coordinator_match should nest under cb.lookup"
+        assert spans["cb.coordinator_match"].attributes.get("matches") == "3"
+        assert spans["cb.coordinator_match"].attributes.get("timed_out") == "False"
+
+    def test_scatter_span_nests_under_cb_retrieve(self, exporter):
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        bus.register_subscriber(BlendTracingSubscriber(SpanRegistry()))
+        bus.start()
+        now = time.time()
+        sid = "cb-scatter"
+        seq = [
+            (EventType.CB_REQUEST_START, {}),
+            (EventType.CB_RETRIEVE_START, {"num_chunks": 5}),
+            (
+                EventType.CB_SCATTER_START,
+                {
+                    "scattered_tokens": 1280,
+                    "n_prefix": 1,
+                    "n_shifted": 4,
+                    "dropped": 0,
+                },
+            ),
+            (EventType.CB_SCATTER_END, {}),
+            (EventType.CB_RETRIEVE_END, {}),
+            (EventType.CB_REQUEST_END, {}),
+        ]
+        for i, (et, md) in enumerate(seq):
+            bus.publish(
+                Event(
+                    event_type=et,
+                    session_id=sid,
+                    timestamp=now + i * 0.001,
+                    metadata=md,
+                )
+            )
+        time.sleep(0.3)
+        bus.stop()
+
+        spans = self._spans_by_name(exporter, sid)
+        assert "cb.scatter" in spans, f"missing cb.scatter; have {sorted(spans)}"
+        assert "cb.retrieve" in spans
+        assert (
+            spans["cb.scatter"].parent.span_id == spans["cb.retrieve"].context.span_id
+        ), "cb.scatter should nest under cb.retrieve"
+        assert spans["cb.scatter"].attributes.get("scattered_tokens") == "1280"
+        assert spans["cb.scatter"].attributes.get("n_shifted") == "4"
+        assert spans["cb.scatter"].attributes.get("dropped") == "0"
diff --git a/tests/v1/mp_observability/subscribers/tracing/test_mp_server.py b/tests/v1/mp_observability/subscribers/tracing/test_mp_server.py
new file mode 100644
index 0000000..7da78dd
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/tracing/test_mp_server.py
@@ -0,0 +1,781 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for MPServerTracingSubscriber."""
+
+# Standard
+from unittest.mock import patch
+import time
+
+# Third Party
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.tracing import (
+    MPServerTracingSubscriber,
+)
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import (
+    SpanRegistry,
+)
+import lmcache.v1.mp_observability.subscribers.tracing.mp_server as mp_server_module
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def registry():
+    return SpanRegistry()
+
+
+@pytest.fixture
+def subscriber(registry, bus):
+    sub = MPServerTracingSubscriber(registry)
+    bus.register_subscriber(sub)
+    return sub
+
+
+class TestMPServerTracingSubscriber:
+    def test_subscriptions_cover_all_mp_server_events(self, subscriber):
+        subs = subscriber.get_subscriptions()
+        assert EventType.MP_REQUEST_START in subs
+        assert EventType.MP_STORE_SUBMITTED in subs
+        assert EventType.MP_RETRIEVE_SUBMITTED in subs
+        assert EventType.MP_REQUEST_END in subs
+        assert EventType.MP_STORE_START in subs
+        assert EventType.MP_STORE_END in subs
+        assert EventType.MP_RETRIEVE_START in subs
+        assert EventType.MP_RETRIEVE_END in subs
+        assert EventType.MP_LOOKUP_PREFETCH_START in subs
+        assert EventType.MP_LOOKUP_PREFETCH_END in subs
+
+    # ------------------------------------------------------------------
+    # Root span creation
+    # ------------------------------------------------------------------
+
+    def test_root_span_created_on_request_start(self, bus, registry, subscriber):
+        bus.start()
+        bus.publish(Event(event_type=EventType.MP_REQUEST_START, session_id="req-root"))
+        time.sleep(0.15)
+        assert registry.get("req-root", "request") is not None
+        bus.stop()
+
+    def test_no_root_span_before_any_event(self, registry):
+        assert registry.get("any-session", "request") is None
+
+    # ------------------------------------------------------------------
+    # Session-end closes root immediately when no stores in flight
+    # ------------------------------------------------------------------
+
+    def test_session_end_closes_root_immediately_when_no_store(
+        self, bus, registry, subscriber
+    ):
+        bus.start()
+        now = time.time()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_START,
+                session_id="req-lookup-only",
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_START,
+                session_id="req-lookup-only",
+                timestamp=now + 0.001,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-lookup-only",
+                timestamp=now + 0.010,
+                metadata={"found_count": 4},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id="req-lookup-only",
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get("req-lookup-only", "request") is None
+        assert "req-lookup-only" not in subscriber._pending_store_count
+        assert len(subscriber._pending) == 0
+
+    # ------------------------------------------------------------------
+    # Deferred close: SESSION_END races GPU store
+    # ------------------------------------------------------------------
+
+    def test_session_end_deferred_until_store_finishes(self, bus, registry, subscriber):
+        bus.start()
+        now = time.time()
+        sid = "req-deferred"
+
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+            )
+        )
+        # SESSION_END arrives before STORE_END
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        # Root should still be open (store in flight)
+        assert registry.get(sid, "request") is not None
+        assert sid in subscriber._deferred_session_end_ts
+
+        # Now GPU store completes
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id=sid,
+                timestamp=now + 0.050,
+                metadata={"stored_count": 2, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        # Root should now be closed
+        assert registry.get(sid, "request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+        assert sid not in subscriber._pending_store_count
+
+    # ------------------------------------------------------------------
+    # Multiple stores: root stays open until all complete
+    # ------------------------------------------------------------------
+
+    def test_multiple_stores_all_must_finish(self, bus, registry, subscriber):
+        bus.start()
+        now = time.time()
+        sid = "req-multi-store"
+
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.002,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        # count=2 — still open
+        assert registry.get(sid, "request") is not None
+
+        # First store ends — count=1, still open
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id=sid,
+                timestamp=now + 0.030,
+                metadata={"stored_count": 1, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        assert registry.get(sid, "request") is not None
+
+        # Second store ends — count=0, closes now
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id=sid,
+                timestamp=now + 0.040,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id=sid,
+                timestamp=now + 0.060,
+                metadata={"stored_count": 1, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "request") is None
+        assert sid not in subscriber._pending_store_count
+
+    # ------------------------------------------------------------------
+    # Lazy root creation on store-only path (no lookup)
+    # ------------------------------------------------------------------
+
+    def test_lazy_root_on_store_only_path(self, bus, registry, subscriber):
+        bus.start()
+        now = time.time()
+        sid = "req-store-only"
+
+        # No MP_REQUEST_START — root created lazily on MP_STORE_START
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_SUBMITTED,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+
+        assert registry.get(sid, "request") is not None
+
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+                metadata={"stored_count": 3, "device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.025,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "request") is None
+
+    # ------------------------------------------------------------------
+    # Retrieve deferral: SESSION_END races GPU retrieve
+    # ------------------------------------------------------------------
+
+    def test_session_end_deferred_until_retrieve_finishes(
+        self, bus, registry, subscriber
+    ):
+        bus.start()
+        now = time.time()
+        sid = "req-deferred-retrieve"
+
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+            )
+        )
+        # SESSION_END arrives before RETRIEVE_END (the race condition)
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        # Root should still be open (retrieve in flight)
+        assert registry.get(sid, "request") is not None
+        assert sid in subscriber._deferred_session_end_ts
+
+        # Now GPU retrieve completes
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_END,
+                session_id=sid,
+                timestamp=now + 0.050,
+                metadata={"retrieved_count": 4, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        # Root should now be closed
+        assert registry.get(sid, "request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+        assert sid not in subscriber._pending_retrieve_count
+
+    def test_session_end_deferred_until_both_store_and_retrieve_finish(
+        self, bus, registry, subscriber
+    ):
+        """Root span stays open until both a store and a retrieve finish."""
+        bus.start()
+        now = time.time()
+        sid = "req-store-and-retrieve"
+
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_START,
+                session_id=sid,
+                timestamp=now,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.001,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_SUBMITTED,
+                session_id=sid,
+                timestamp=now + 0.002,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.005,
+            )
+        )
+        time.sleep(0.15)
+
+        # Both in flight — root still open
+        assert registry.get(sid, "request") is not None
+
+        # Store finishes first — retrieve still pending, root stays open
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id=sid,
+                timestamp=now + 0.030,
+                metadata={"stored_count": 1, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        assert registry.get(sid, "request") is not None
+
+        # Retrieve finishes — now both counters are zero → root closes
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id=sid,
+                timestamp=now + 0.040,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_END,
+                session_id=sid,
+                timestamp=now + 0.060,
+                metadata={"retrieved_count": 2, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert registry.get(sid, "request") is None
+        assert sid not in subscriber._deferred_session_end_ts
+
+    # ------------------------------------------------------------------
+    # Child spans registered in shared registry for sub-span parenting
+    # ------------------------------------------------------------------
+
+    def test_retrieve_span_registered_in_registry_while_open(
+        self, bus, registry, subscriber
+    ):
+        """An open mp.retrieve span is accessible in the registry under
+        ``span_name="retrieve"`` so that a future sub-span subscriber can
+        look it up as a parent."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id="req-reg",
+                metadata={"device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        assert registry.get("req-reg", "retrieve") is not None
+        bus.stop()
+
+    def test_retrieve_span_deregistered_after_close(self, bus, registry, subscriber):
+        """Registry entry is cleaned up when mp.retrieve ends so stale
+        contexts do not leak into subsequent requests."""
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id="req-reg2",
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_END,
+                session_id="req-reg2",
+                metadata={"device": "cuda:0", "retrieved_count": 1},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert registry.get("req-reg2", "retrieve") is None
+
+    # ------------------------------------------------------------------
+    # Existing lifecycle tests (unchanged behaviour)
+    # ------------------------------------------------------------------
+
+    def test_store_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id="req-1",
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id="req-1",
+                metadata={"device": "cuda:0", "stored_count": 5},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_retrieve_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_START,
+                session_id="req-2",
+                metadata={"device": "cuda:1"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_RETRIEVE_END,
+                session_id="req-2",
+                metadata={"device": "cuda:1", "retrieved_count": 3},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_lookup_prefetch_span_lifecycle(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_START,
+                session_id="req-3",
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id="req-3",
+                metadata={"found_count": 10},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_unmatched_end_does_not_crash(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id="orphan",
+                metadata={"stored_count": 1, "device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+    def test_unmatched_start_cleaned_on_shutdown(self, bus, subscriber):
+        bus.start()
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id="leaked",
+                metadata={"device": "cuda:0"},
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+        subscriber.shutdown()
+        assert len(subscriber._pending) == 0
+
+    def test_multiple_concurrent_sessions(self, bus, subscriber):
+        bus.start()
+        for i in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_STORE_START,
+                    session_id=f"req-{i}",
+                    metadata={"device": "cuda:0"},
+                )
+            )
+        for i in range(5):
+            bus.publish(
+                Event(
+                    event_type=EventType.MP_STORE_END,
+                    session_id=f"req-{i}",
+                    metadata={"device": "cuda:0", "stored_count": i},
+                )
+            )
+        time.sleep(0.15)
+        bus.stop()
+        assert len(subscriber._pending) == 0
+
+
+class TestHitRateAttributes:
+    """Verify hit_tokens / requested_tokens / hit_rate are set on the root span.
+
+    Uses a real OTel TracerProvider backed by InMemorySpanExporter so that span
+    attributes are actually recorded.  The module-level ``_tracer`` is patched
+    for the duration of each test; ``_HAS_OTEL`` is forced True so that the
+    handlers don't early-return.
+    """
+
+    @pytest.fixture
+    def exporter(self):
+        """Real OTel provider with in-memory exporter; patches module tracer."""
+        exp = InMemorySpanExporter()
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(exp))
+        real_tracer = provider.get_tracer("lmcache_mp.server")
+        with (
+            patch.object(mp_server_module, "_tracer", real_tracer),
+            patch.object(mp_server_module, "_HAS_OTEL", True),
+        ):
+            yield exp
+        exp.shutdown()
+
+    def _root_span(self, exporter: InMemorySpanExporter, sid: str):
+        """Return the finished root span for *sid*, or None."""
+        for span in exporter.get_finished_spans():
+            if span.name == "request" and span.attributes.get("session_id") == sid:
+                return span
+        return None
+
+    def test_hit_rate_attrs_set_on_root_span(self, exporter):
+        """LP_END with hit_tokens=512, requested_tokens=1024 → hit_rate=0.5."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(MPServerTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "req-hr-normal"
+
+        bus.publish(
+            Event(event_type=EventType.MP_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={
+                    "hit_tokens": 512,
+                    "requested_tokens": 1024,
+                    "found_count": 2,
+                },
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["hit_tokens"] == 512
+        assert root.attributes["requested_tokens"] == 1024
+        assert abs(root.attributes["hit_rate"] - 0.5) < 1e-9
+
+    def test_hit_rate_zero_when_requested_tokens_is_zero(self, exporter):
+        """LP_END with requested_tokens=0 yields hit_rate=0.0 without error."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(MPServerTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "req-hr-zero"
+
+        bus.publish(
+            Event(event_type=EventType.MP_REQUEST_START, session_id=sid, timestamp=now)
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_LOOKUP_PREFETCH_END,
+                session_id=sid,
+                timestamp=now + 0.010,
+                metadata={"hit_tokens": 0, "requested_tokens": 0, "found_count": 0},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert root.attributes["hit_tokens"] == 0
+        assert root.attributes["requested_tokens"] == 0
+        assert root.attributes["hit_rate"] == 0.0
+
+    def test_no_hit_rate_attrs_on_store_only_path(self, exporter):
+        """Store-only request (no LP_END) leaves root span without hit rate attrs."""
+        bus = EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+        registry = SpanRegistry()
+        bus.register_subscriber(MPServerTracingSubscriber(registry))
+        bus.start()
+        now = time.time()
+        sid = "req-hr-store-only"
+
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_SUBMITTED, session_id=sid, timestamp=now
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id=sid,
+                timestamp=now + 0.001,
+                metadata={"device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id=sid,
+                timestamp=now + 0.020,
+                metadata={"stored_count": 3, "device": "cuda:0"},
+            )
+        )
+        bus.publish(
+            Event(
+                event_type=EventType.MP_REQUEST_END,
+                session_id=sid,
+                timestamp=now + 0.025,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        root = self._root_span(exporter, sid)
+        assert root is not None
+        assert "hit_tokens" not in root.attributes
+        assert "hit_rate" not in root.attributes
diff --git a/tests/v1/mp_observability/subscribers/tracing/test_timeout.py b/tests/v1/mp_observability/subscribers/tracing/test_timeout.py
new file mode 100644
index 0000000..3028a5a
--- /dev/null
+++ b/tests/v1/mp_observability/subscribers/tracing/test_timeout.py
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for TimeoutTracingSubscriber.
+
+The subscriber's module-level ``_tracer`` is patched with a mock so the test
+can assert on the span shape (name, exception event, ERROR status, parent
+context) without depending on the single process-wide OTel TracerProvider.
+"""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.subscribers.tracing.span_registry import SpanRegistry
+from lmcache.v1.mp_observability.subscribers.tracing.timeout import (
+    TimeoutTracingSubscriber,
+)
+import lmcache.v1.mp_observability.subscribers.tracing.timeout as timeout_module
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+@pytest.fixture
+def registry():
+    return SpanRegistry()
+
+
+def _publish(bus, session_id: str = "", message: str = "boom") -> None:
+    bus.publish(
+        Event(
+            event_type=EventType.TIMEOUT_RAISED,
+            session_id=session_id,
+            metadata={
+                "message": message,
+                "exception_type": "LMCacheTimeoutError",
+                "stacktrace": "the-stacktrace",
+            },
+        )
+    )
+
+
+class TestTimeoutTracingSubscriber:
+    def test_subscription_covers_timeout_event(self, registry):
+        sub = TimeoutTracingSubscriber(registry)
+        subs = sub.get_subscriptions()
+        assert EventType.TIMEOUT_RAISED in subs
+        assert len(subs) == 1
+
+    def test_creates_span_with_exception_event_and_error_status(self, bus, registry):
+        fake_span = MagicMock()
+        fake_tracer = MagicMock()
+        fake_tracer.start_span.return_value = fake_span
+        with (
+            patch.object(timeout_module, "_tracer", fake_tracer),
+            patch.object(timeout_module, "_HAS_OTEL", True),
+        ):
+            bus.register_subscriber(TimeoutTracingSubscriber(registry))
+            bus.start()
+            _publish(bus, message="boom")
+            time.sleep(_DRAIN_WAIT)
+            bus.stop()
+
+        fake_tracer.start_span.assert_called_once()
+        assert fake_tracer.start_span.call_args.args[0] == "timeout"
+
+        # Exception recorded as an "exception" span event with the OTel
+        # exception semantic-convention attributes.
+        fake_span.add_event.assert_called_once()
+        assert fake_span.add_event.call_args.args[0] == "exception"
+        attrs = fake_span.add_event.call_args.kwargs["attributes"]
+        assert attrs["exception.type"] == "LMCacheTimeoutError"
+        assert attrs["exception.message"] == "boom"
+        assert attrs["exception.stacktrace"] == "the-stacktrace"
+
+        fake_span.set_status.assert_called_once()
+        fake_span.end.assert_called_once()
+
+    def test_nests_under_request_span_when_session_matches(self, bus, registry):
+        sentinel_ctx = object()
+        registry.open("req-1", "request", MagicMock(), sentinel_ctx)
+        fake_tracer = MagicMock()
+        fake_tracer.start_span.return_value = MagicMock()
+        with (
+            patch.object(timeout_module, "_tracer", fake_tracer),
+            patch.object(timeout_module, "_HAS_OTEL", True),
+        ):
+            bus.register_subscriber(TimeoutTracingSubscriber(registry))
+            bus.start()
+            _publish(bus, session_id="req-1")
+            time.sleep(_DRAIN_WAIT)
+            bus.stop()
+
+        assert fake_tracer.start_span.call_args.kwargs["context"] is sentinel_ctx
+
+    def test_standalone_span_when_no_session(self, bus, registry):
+        fake_tracer = MagicMock()
+        fake_tracer.start_span.return_value = MagicMock()
+        with (
+            patch.object(timeout_module, "_tracer", fake_tracer),
+            patch.object(timeout_module, "_HAS_OTEL", True),
+        ):
+            bus.register_subscriber(TimeoutTracingSubscriber(registry))
+            bus.start()
+            _publish(bus, session_id="")
+            time.sleep(_DRAIN_WAIT)
+            bus.stop()
+
+        assert fake_tracer.start_span.call_args.kwargs["context"] is None
diff --git a/tests/v1/mp_observability/test_errors.py b/tests/v1/mp_observability/test_errors.py
new file mode 100644
index 0000000..21827d0
--- /dev/null
+++ b/tests/v1/mp_observability/test_errors.py
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for LMCacheTimeoutError (observability-aware timeout error).
+
+Verifies that the class is a drop-in ``TimeoutError`` subclass, is a no-op
+when observability is disabled, and otherwise publishes a ``TIMEOUT_RAISED``
+event to the global EventBus carrying the message, exception type, and a
+captured stack trace.
+"""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.errors import LMCacheTimeoutError
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import (
+    EventBusConfig,
+    init_event_bus,
+)
+
+# Time for the drain thread to process queued events.
+_DRAIN_WAIT = 0.15
+
+
+@pytest.fixture(autouse=True)
+def _restore_global_bus():
+    """Reset the global EventBus to the disabled default after each test."""
+    yield
+    init_event_bus(EventBusConfig(enabled=False))
+
+
+class TestLMCacheTimeoutErrorType:
+    def test_is_timeout_error_subclass(self) -> None:
+        assert issubclass(LMCacheTimeoutError, TimeoutError)
+
+    def test_caught_by_except_timeout_error(self) -> None:
+        init_event_bus(EventBusConfig(enabled=False))
+        with pytest.raises(TimeoutError):
+            raise LMCacheTimeoutError("boom")
+
+    def test_message_preserved(self) -> None:
+        init_event_bus(EventBusConfig(enabled=False))
+        err = LMCacheTimeoutError("the message")
+        assert str(err) == "the message"
+
+
+class TestLMCacheTimeoutErrorEmission:
+    def test_no_event_when_observability_disabled(self) -> None:
+        bus = init_event_bus(EventBusConfig(enabled=False))
+        captured: list[Event] = []
+        bus.subscribe(EventType.TIMEOUT_RAISED, captured.append)
+        bus.start()  # no-op when disabled
+        LMCacheTimeoutError("nope")
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+        assert captured == []
+
+    def test_publishes_event_when_enabled(self) -> None:
+        bus = init_event_bus(EventBusConfig(enabled=True, max_queue_size=100))
+        captured: list[Event] = []
+        bus.subscribe(EventType.TIMEOUT_RAISED, captured.append)
+        bus.start()
+        LMCacheTimeoutError("timed out!", session_id="req-7")
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert len(captured) == 1
+        event = captured[0]
+        assert event.event_type == EventType.TIMEOUT_RAISED
+        assert event.session_id == "req-7"
+        assert event.metadata["message"] == "timed out!"
+        assert event.metadata["exception_type"] == "LMCacheTimeoutError"
+        # The construction stack should be captured and include the caller.
+        assert "test_publishes_event_when_enabled" in event.metadata["stacktrace"]
+
+    def test_subclass_reports_its_own_type(self) -> None:
+        class MyTimeout(LMCacheTimeoutError):
+            pass
+
+        bus = init_event_bus(EventBusConfig(enabled=True, max_queue_size=100))
+        captured: list[Event] = []
+        bus.subscribe(EventType.TIMEOUT_RAISED, captured.append)
+        bus.start()
+        MyTimeout("sub")
+        time.sleep(_DRAIN_WAIT)
+        bus.stop()
+
+        assert len(captured) == 1
+        assert captured[0].metadata["exception_type"] == "MyTimeout"
diff --git a/tests/v1/mp_observability/test_event_bus.py b/tests/v1/mp_observability/test_event_bus.py
new file mode 100644
index 0000000..0b8c550
--- /dev/null
+++ b/tests/v1/mp_observability/test_event_bus.py
@@ -0,0 +1,539 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for EventBus, EventSubscriber, and singleton management."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import (
+    EventBus,
+    EventBusConfig,
+    EventSubscriber,
+    get_event_bus,
+    init_event_bus,
+)
+import lmcache.v1.mp_observability.event_bus as _bus_module
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_event(
+    event_type: EventType = EventType.L1_READ_FINISHED,
+    session_id: str = "s1",
+    **metadata,
+) -> Event:
+    return Event(event_type=event_type, session_id=session_id, metadata=metadata)
+
+
+class _RecordingSubscriber(EventSubscriber):
+    """Test subscriber that records events."""
+
+    def __init__(self, event_types: list[EventType] | None = None):
+        if event_types is None:
+            event_types = [EventType.L1_READ_FINISHED]
+        self._event_types = event_types
+        self.events: list[Event] = []
+        self.shutdown_called = False
+
+    def get_subscriptions(self):
+        return {et: self._on_event for et in self._event_types}
+
+    def _on_event(self, event: Event) -> None:
+        self.events.append(event)
+
+    def shutdown(self) -> None:
+        self.shutdown_called = True
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(autouse=True)
+def restore_global_bus():
+    """Save and restore the global singleton so tests don't leak state."""
+    saved = _bus_module._global_bus
+    yield
+    _bus_module._global_bus = saved
+
+
+@pytest.fixture
+def bus():
+    """Enabled EventBus with small queue for fast tests."""
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+# ---------------------------------------------------------------------------
+# Subscribe / publish basics
+# ---------------------------------------------------------------------------
+
+
+class TestSubscription:
+    def test_subscribe_adds_callback(self, bus):
+        cb = MagicMock()
+        bus.subscribe(EventType.L1_READ_FINISHED, cb)
+        assert cb in bus._subscribers[EventType.L1_READ_FINISHED]
+
+    def test_multiple_callbacks_per_event_type(self, bus):
+        cb1, cb2 = MagicMock(), MagicMock()
+        bus.subscribe(EventType.L1_READ_FINISHED, cb1)
+        bus.subscribe(EventType.L1_READ_FINISHED, cb2)
+        assert len(bus._subscribers[EventType.L1_READ_FINISHED]) == 2
+
+    def test_register_subscriber(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        assert sub in bus._registered_subscribers
+        assert len(bus._subscribers[EventType.L1_READ_FINISHED]) == 1
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TestLifecycle:
+    def test_start_launches_thread(self, bus):
+        bus.start()
+        assert bus._thread is not None
+        assert bus._thread.is_alive()
+        bus.stop()
+
+    def test_disabled_noop(self):
+        b = EventBus(EventBusConfig(enabled=False))
+        b.start()
+        assert b._thread is None
+
+    def test_thread_is_daemon(self, bus):
+        bus.start()
+        assert bus._thread.daemon is True
+        bus.stop()
+
+    def test_thread_name(self, bus):
+        bus.start()
+        assert bus._thread.name == "EventBus"
+        bus.stop()
+
+    def test_double_start_is_idempotent(self, bus):
+        bus.start()
+        thread = bus._thread
+        bus.start()
+        assert bus._thread is thread
+        bus.stop()
+
+    def test_double_stop(self, bus):
+        bus.start()
+        bus.stop()
+        bus.stop()
+
+    def test_stop_without_start(self, bus):
+        bus.stop()
+
+
+# ---------------------------------------------------------------------------
+# Event dispatch
+# ---------------------------------------------------------------------------
+
+
+class TestEventDispatch:
+    def test_event_reaches_subscriber(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        bus.start()
+
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub.events) == 1
+        assert sub.events[0].event_type == EventType.L1_READ_FINISHED
+
+    def test_publish_stamps_timestamp(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        bus.start()
+
+        before = time.time()
+        bus.publish(_make_event())
+        after = time.time()
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub.events) == 1
+        assert before <= sub.events[0].timestamp <= after
+
+    def test_events_dispatched_in_order(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        bus.start()
+
+        for i in range(5):
+            bus.publish(_make_event(session_id=str(i)))
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub.events) == 5
+        for i, ev in enumerate(sub.events):
+            assert ev.session_id == str(i)
+
+    def test_event_only_dispatched_to_matching_subscribers(self, bus):
+        l1_sub = _RecordingSubscriber([EventType.L1_READ_FINISHED])
+        sm_sub = _RecordingSubscriber([EventType.SM_WRITE_RESERVED])
+        bus.register_subscriber(l1_sub)
+        bus.register_subscriber(sm_sub)
+        bus.start()
+
+        bus.publish(_make_event(event_type=EventType.L1_READ_FINISHED))
+        bus.publish(_make_event(event_type=EventType.SM_WRITE_RESERVED))
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(l1_sub.events) == 1
+        assert l1_sub.events[0].event_type == EventType.L1_READ_FINISHED
+        assert len(sm_sub.events) == 1
+        assert sm_sub.events[0].event_type == EventType.SM_WRITE_RESERVED
+
+    def test_multiple_subscribers_same_event(self, bus):
+        sub1 = _RecordingSubscriber()
+        sub2 = _RecordingSubscriber()
+        bus.register_subscriber(sub1)
+        bus.register_subscriber(sub2)
+        bus.start()
+
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub1.events) == 1
+        assert len(sub2.events) == 1
+
+    def test_metadata_preserved(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        bus.start()
+
+        bus.publish(_make_event(count=42, name="test"))
+        time.sleep(0.15)
+        bus.stop()
+
+        assert sub.events[0].metadata["count"] == 42
+        assert sub.events[0].metadata["name"] == "test"
+
+    def test_disabled_bus_drops_events(self):
+        b = EventBus(EventBusConfig(enabled=False))
+        sub = _RecordingSubscriber()
+        b.register_subscriber(sub)
+        b.publish(_make_event())
+        assert len(b._queue) == 0
+
+    def test_late_registered_subscriber(self, bus):
+        bus.start()
+        time.sleep(0.05)
+
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub.events) >= 1
+
+    def test_stop_drains_remaining_events(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        # Don't start the drain thread — events accumulate in the queue
+        for _ in range(3):
+            bus.publish(_make_event())
+        assert len(bus._queue) == 3
+
+        # stop() should do a final drain
+        bus.stop()
+        assert len(sub.events) == 3
+
+
+# ---------------------------------------------------------------------------
+# Exception isolation
+# ---------------------------------------------------------------------------
+
+
+class TestExceptionIsolation:
+    def test_bad_callback_doesnt_block_good(self, bus):
+        bad_cb = MagicMock(side_effect=RuntimeError("boom"))
+        bus.subscribe(EventType.L1_READ_FINISHED, bad_cb)
+
+        good_sub = _RecordingSubscriber()
+        bus.register_subscriber(good_sub)
+        bus.start()
+
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(good_sub.events) == 1
+
+    def test_shutdown_exception_isolated(self, bus):
+        bad_sub = _RecordingSubscriber()
+        bad_sub.shutdown = MagicMock(side_effect=RuntimeError("shutdown boom"))
+        good_sub = _RecordingSubscriber()
+
+        bus.register_subscriber(bad_sub)
+        bus.register_subscriber(good_sub)
+        bus.start()
+        bus.stop()
+
+        assert good_sub.shutdown_called
+
+
+# ---------------------------------------------------------------------------
+# Backpressure
+# ---------------------------------------------------------------------------
+
+
+class TestBackpressure:
+    def test_events_discarded_when_queue_full(self):
+        b = EventBus(EventBusConfig(enabled=True, max_queue_size=5))
+        # Don't start — nothing drains
+        for _ in range(10):
+            b.publish(_make_event())
+
+        assert len(b._queue) == 5
+        assert b._discard_count == 5
+
+
+# ---------------------------------------------------------------------------
+# Self-monitoring accessors
+# ---------------------------------------------------------------------------
+
+
+class TestSelfMonitoring:
+    def test_queue_depth_reports_current_size(self, bus):
+        # Don't start the drain thread so events accumulate.
+        assert bus.queue_depth() == 0
+        for _ in range(3):
+            bus.publish(_make_event())
+        assert bus.queue_depth() == 3
+
+    def test_oldest_event_lag_zero_when_empty(self, bus):
+        assert bus.oldest_event_lag_seconds() == 0.0
+
+    def test_oldest_event_lag_grows_with_age(self, bus):
+        # Don't start drain — let events sit in the queue.
+        bus.publish(_make_event())
+        time.sleep(0.05)
+        lag = bus.oldest_event_lag_seconds()
+        assert lag >= 0.05
+        # Drain via stop() so the bus shuts down cleanly.
+        bus.stop()
+
+    def test_oldest_event_lag_returns_zero_after_drain(self, bus):
+        sub = _RecordingSubscriber()
+        bus.register_subscriber(sub)
+        bus.start()
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        # Drained, queue should be empty.
+        assert bus.oldest_event_lag_seconds() == 0.0
+        bus.stop()
+
+    def test_dropped_events_count_starts_zero(self, bus):
+        assert bus.dropped_events_count() == 0
+
+    def test_dropped_events_count_increments_on_drop(self):
+        b = EventBus(EventBusConfig(enabled=True, max_queue_size=2))
+        # Don't start — nothing drains.
+        for _ in range(5):
+            b.publish(_make_event())
+        assert b.dropped_events_count() == 3
+
+    def test_subscriber_exception_counts_starts_empty(self, bus):
+        assert bus.subscriber_exception_counts() == {}
+
+    def test_subscriber_exception_counts_tracks_bound_methods(self, bus):
+        class _BadSub(EventSubscriber):
+            def get_subscriptions(self):
+                return {EventType.L1_READ_FINISHED: self._on_event}
+
+            def _on_event(self, event):
+                raise RuntimeError("boom")
+
+        bus.register_subscriber(_BadSub())
+        bus.start()
+        bus.publish(_make_event())
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        counts = bus.subscriber_exception_counts()
+        assert counts.get("_BadSub") == 2
+
+    def test_subscriber_exception_counts_returns_copy(self, bus):
+        class _BadSub(EventSubscriber):
+            def get_subscriptions(self):
+                return {EventType.L1_READ_FINISHED: self._on_event}
+
+            def _on_event(self, event):
+                raise RuntimeError("boom")
+
+        bus.register_subscriber(_BadSub())
+        bus.start()
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        snapshot = bus.subscriber_exception_counts()
+        snapshot["_BadSub"] = 99
+        assert bus.subscriber_exception_counts().get("_BadSub") == 1
+
+    def test_subscriber_exception_counts_uses_qualname_for_free_function(self, bus):
+        def free_callback(event):
+            raise RuntimeError("boom")
+
+        bus.subscribe(EventType.L1_READ_FINISHED, free_callback)
+        bus.start()
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        counts = bus.subscriber_exception_counts()
+        # Free functions are labeled by __qualname__, which here lives
+        # inside the test method.
+        assert any("free_callback" in name for name in counts)
+
+    def test_good_subscriber_not_counted(self, bus):
+        class _BadSub(EventSubscriber):
+            def get_subscriptions(self):
+                return {EventType.L1_READ_FINISHED: self._on_event}
+
+            def _on_event(self, event):
+                raise RuntimeError("boom")
+
+        good = _RecordingSubscriber()
+        bus.register_subscriber(_BadSub())
+        bus.register_subscriber(good)
+        bus.start()
+        bus.publish(_make_event())
+        time.sleep(0.15)
+        bus.stop()
+
+        counts = bus.subscriber_exception_counts()
+        assert "_BadSub" in counts
+        assert "_RecordingSubscriber" not in counts
+
+
+# ---------------------------------------------------------------------------
+# Global singleton
+# ---------------------------------------------------------------------------
+
+
+class TestGlobalSingleton:
+    def test_get_returns_instance(self):
+        bus = get_event_bus()
+        assert isinstance(bus, EventBus)
+
+    def test_init_replaces_global(self):
+        old = get_event_bus()
+        new = init_event_bus(EventBusConfig(enabled=False))
+        assert get_event_bus() is new
+        assert get_event_bus() is not old
+
+    def test_default_singleton_is_disabled(self):
+        bus = get_event_bus()
+        assert bus._config.enabled is False
+
+    def test_init_with_none_uses_defaults(self):
+        bus = init_event_bus()
+        assert bus._config.enabled is True
+        assert bus._config.max_queue_size == 10_000
+
+
+# ---------------------------------------------------------------------------
+# Block allocation event
+# ---------------------------------------------------------------------------
+
+
+class TestBlockAllocationEvent:
+    def test_publish_block_allocation_event(self, bus):
+        """Verify MP_VLLM_BLOCK_ALLOCATION events are delivered to subscribers."""
+        sub = _RecordingSubscriber(event_types=[EventType.MP_VLLM_BLOCK_ALLOCATION])
+        bus.register_subscriber(sub)
+        bus.start()
+
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import BlockAllocationRecord
+
+        records = [
+            BlockAllocationRecord(
+                req_id="req-1",
+                new_block_ids=[0, 1, 2],
+                new_token_ids=[10, 20, 30],
+            ),
+        ]
+        bus.publish(
+            _make_event(
+                event_type=EventType.MP_VLLM_BLOCK_ALLOCATION,
+                session_id="",
+                records=records,
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub.events) == 1
+        evt = sub.events[0]
+        assert evt.event_type == EventType.MP_VLLM_BLOCK_ALLOCATION
+        assert len(evt.metadata["records"]) == 1
+        assert evt.metadata["records"][0].req_id == "req-1"
+        assert evt.metadata["records"][0].new_block_ids == [0, 1, 2]
+
+    def test_block_allocation_not_delivered_to_other_subscriber(self, bus):
+        """Verify block allocation events are not delivered to unrelated subscribers."""
+        sub = _RecordingSubscriber(event_types=[EventType.L1_READ_FINISHED])
+        bus.register_subscriber(sub)
+        bus.start()
+
+        bus.publish(
+            _make_event(
+                event_type=EventType.MP_VLLM_BLOCK_ALLOCATION,
+                session_id="",
+            )
+        )
+        time.sleep(0.15)
+        bus.stop()
+
+        assert len(sub.events) == 0
+
+
+_REGISTER_GAUGE = "lmcache.v1.mp_observability.event_bus.register_gauge"
+
+
+class TestSelfMonitoringGauges:
+    def test_init_registers_both_gauges(self):
+        with patch(_REGISTER_GAUGE) as mock_register:
+            EventBus(EventBusConfig(enabled=True))
+            names = [c.args[1] for c in mock_register.call_args_list]
+            assert set(names) == {
+                "lmcache_mp.event_bus.queue_depth",
+                "lmcache_mp.event_bus.drain_lag_seconds",
+            }
+
+    def test_queue_depth_callback_reflects_bus(self):
+        captured: dict[str, object] = {}
+
+        def _capture(_meter, name, _desc, func):
+            captured[name] = func
+
+        with patch(_REGISTER_GAUGE, side_effect=_capture):
+            bus = EventBus(EventBusConfig(enabled=True))
+            bus.publish(_make_event(session_id="s1"))
+            bus.publish(_make_event(session_id="s2"))
+            assert captured["lmcache_mp.event_bus.queue_depth"]() == 2
diff --git a/tests/v1/mp_observability/test_event_recorder.py b/tests/v1/mp_observability/test_event_recorder.py
new file mode 100644
index 0000000..bb9cf1e
--- /dev/null
+++ b/tests/v1/mp_observability/test_event_recorder.py
@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the C++ EventRecorder (record_event_on_stream / drain)."""
+
+# Standard
+import time
+
+# Third Party
+import pytest
+
+torch = pytest.importorskip("torch", reason="torch required")
+if not torch.cuda.is_available():
+    pytest.skip("CUDA not available", allow_module_level=True)
+
+lmc_ops = pytest.importorskip("lmcache.c_ops", reason="lmcache.c_ops not built")
+if not hasattr(lmc_ops, "record_event_on_stream"):
+    pytest.skip("record_event_on_stream not available", allow_module_level=True)
+
+# Third Party
+import cupy  # noqa: E402
+
+# First Party
+from lmcache.v1.mp_observability.event import Event, EventType  # noqa: E402
+from lmcache.v1.mp_observability.event_bus import (  # noqa: E402
+    EventBus,
+    EventBusConfig,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def stream():
+    """Return a synchronised CuPy external stream."""
+    s = cupy.cuda.Stream()
+    yield s
+    s.synchronize()
+
+
+@pytest.fixture()
+def bus():
+    return EventBus(EventBusConfig(enabled=True, max_queue_size=100))
+
+
+# ---------------------------------------------------------------------------
+# Tests: C++ record / drain API
+# ---------------------------------------------------------------------------
+
+
+class TestRecordAndDrain:
+    """Low-level tests for lmc_ops.record_event_on_stream / drain."""
+
+    def test_drain_empty(self):
+        events = lmc_ops.drain_recorded_events()
+        assert events == []
+
+    def test_single_event(self, stream):
+        lmc_ops.record_event_on_stream(
+            stream.ptr,
+            "mp.store.start",
+            "sess-1",
+            {"device": "cuda:0"},
+            {},
+        )
+        stream.synchronize()
+
+        events = lmc_ops.drain_recorded_events()
+        assert len(events) == 1
+        name, sid, ts, str_meta, int_meta = events[0]
+        assert name == "mp.store.start"
+        assert sid == "sess-1"
+        assert ts > 0.0
+        assert str_meta == {"device": "cuda:0"}
+        assert int_meta == {}
+
+    def test_int_metadata_preserved(self, stream):
+        lmc_ops.record_event_on_stream(
+            stream.ptr,
+            "mp.store.end",
+            "sess-2",
+            {"device": "cuda:0"},
+            {"stored_count": 42},
+        )
+        stream.synchronize()
+
+        events = lmc_ops.drain_recorded_events()
+        assert len(events) == 1
+        _, _, _, str_meta, int_meta = events[0]
+        assert str_meta == {"device": "cuda:0"}
+        assert int_meta == {"stored_count": 42}
+
+    def test_multiple_events_ordered(self, stream):
+        for i in range(5):
+            lmc_ops.record_event_on_stream(
+                stream.ptr,
+                f"mp.test.{i}",
+                f"sess-{i}",
+                {},
+                {"idx": i},
+            )
+        stream.synchronize()
+
+        events = lmc_ops.drain_recorded_events()
+        assert len(events) == 5
+        for i, (name, sid, ts, _, int_meta) in enumerate(events):
+            assert name == f"mp.test.{i}"
+            assert sid == f"sess-{i}"
+            assert int_meta["idx"] == i
+            assert ts > 0.0
+
+    def test_drain_clears_buffer(self, stream):
+        lmc_ops.record_event_on_stream(stream.ptr, "mp.store.start", "s", {}, {})
+        stream.synchronize()
+
+        first = lmc_ops.drain_recorded_events()
+        assert len(first) == 1
+
+        second = lmc_ops.drain_recorded_events()
+        assert second == []
+
+    def test_timestamps_monotonic(self, stream):
+        for _ in range(3):
+            lmc_ops.record_event_on_stream(stream.ptr, "mp.store.start", "s", {}, {})
+        stream.synchronize()
+
+        events = lmc_ops.drain_recorded_events()
+        timestamps = [e[2] for e in events]
+        assert timestamps == sorted(timestamps)
+
+
+# ---------------------------------------------------------------------------
+# Tests: EventBus integration (publish_on_stream -> drain)
+# ---------------------------------------------------------------------------
+
+
+class TestEventBusIntegration:
+    """Verify EventBus.publish_on_stream routes through C++ and events
+    are dispatched to subscribers via the drain thread."""
+
+    def test_publish_on_stream_reaches_subscriber(self, stream, bus):
+        received: list[Event] = []
+        bus.subscribe(EventType.MP_STORE_START, received.append)
+        bus.start()
+
+        bus.publish_on_stream(
+            stream,
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id="req-1",
+                metadata={"device": "cuda:0"},
+            ),
+        )
+        stream.synchronize()
+        time.sleep(0.3)
+        bus.stop()
+
+        assert len(received) == 1
+        evt = received[0]
+        assert evt.event_type is EventType.MP_STORE_START
+        assert evt.session_id == "req-1"
+        assert evt.metadata["device"] == "cuda:0"
+        assert evt.timestamp > 0.0
+
+    def test_int_metadata_roundtrip(self, stream, bus):
+        received: list[Event] = []
+        bus.subscribe(EventType.MP_STORE_END, received.append)
+        bus.start()
+
+        bus.publish_on_stream(
+            stream,
+            Event(
+                event_type=EventType.MP_STORE_END,
+                session_id="req-2",
+                metadata={"device": "cuda:0", "stored_count": 10},
+            ),
+        )
+        stream.synchronize()
+        time.sleep(0.3)
+        bus.stop()
+
+        assert len(received) == 1
+        assert received[0].metadata["stored_count"] == 10
+        assert received[0].metadata["device"] == "cuda:0"
+
+    def test_disabled_bus_skips_recording(self, stream):
+        disabled_bus = EventBus(EventBusConfig(enabled=False))
+        disabled_bus.publish_on_stream(
+            stream,
+            Event(
+                event_type=EventType.MP_STORE_START,
+                session_id="req-3",
+                metadata={"device": "cuda:0"},
+            ),
+        )
+        stream.synchronize()
+
+        events = lmc_ops.drain_recorded_events()
+        assert events == []
diff --git a/tests/v1/mp_observability/test_otel_init.py b/tests/v1/mp_observability/test_otel_init.py
new file mode 100644
index 0000000..abaf60f
--- /dev/null
+++ b/tests/v1/mp_observability/test_otel_init.py
@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the ``start_http_server`` flag in OTel metrics init."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.config import (
+    ObservabilityConfig,
+    init_observability,
+)
+from lmcache.v1.mp_observability.otel_init import init_otel_metrics
+
+
+@pytest.fixture(autouse=True)
+def _mock_otel_provider(monkeypatch):
+    """Avoid mutating the process-global OTel MeterProvider."""
+    # Third Party
+    from opentelemetry import metrics as otel_metrics
+
+    monkeypatch.setattr(otel_metrics, "set_meter_provider", MagicMock())
+
+
+def test_init_otel_metrics_starts_http_server_by_default():
+    with patch("prometheus_client.start_http_server") as mock_start:
+        init_otel_metrics(prometheus_port=19090)
+    mock_start.assert_called_once_with(19090)
+
+
+def test_init_otel_metrics_skips_http_server_when_disabled():
+    with patch("prometheus_client.start_http_server") as mock_start:
+        init_otel_metrics(prometheus_port=19091, start_http_server=False)
+    mock_start.assert_not_called()
+
+
+def test_init_otel_metrics_otlp_mode_never_starts_prom_server():
+    """OTLP push mode must not spawn a Prometheus HTTP server,
+    regardless of ``start_http_server``."""
+    with (
+        patch(
+            "opentelemetry.exporter.otlp.proto.grpc.metric_exporter.OTLPMetricExporter"
+        ),
+        patch("prometheus_client.start_http_server") as mock_start,
+    ):
+        init_otel_metrics(
+            otlp_endpoint="http://localhost:4317",
+            start_http_server=True,
+        )
+    mock_start.assert_not_called()
+
+
+def test_init_observability_propagates_flag_false():
+    """``init_observability`` must forward ``False`` to
+    ``init_otel_metrics``."""
+    cfg = ObservabilityConfig(enabled=True, metrics_enabled=True, logging_enabled=False)
+    with patch("lmcache.v1.mp_observability.otel_init.init_otel_metrics") as mock_init:
+        init_observability(cfg, start_prometheus_http_server=False)
+    mock_init.assert_called_once()
+    assert mock_init.call_args.kwargs["start_http_server"] is False
+
+
+def test_init_observability_propagates_flag_true_by_default():
+    cfg = ObservabilityConfig(enabled=True, metrics_enabled=True, logging_enabled=False)
+    with patch("lmcache.v1.mp_observability.otel_init.init_otel_metrics") as mock_init:
+        init_observability(cfg)
+    mock_init.assert_called_once()
+    assert mock_init.call_args.kwargs["start_http_server"] is True
diff --git a/tests/v1/mp_observability/test_register_gauge.py b/tests/v1/mp_observability/test_register_gauge.py
new file mode 100644
index 0000000..3c84dfb
--- /dev/null
+++ b/tests/v1/mp_observability/test_register_gauge.py
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for register_gauge in otel_init."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+
+# First Party
+from lmcache.v1.mp_observability.otel_init import register_gauge
+
+
+class TestRegisterGauge:
+    """Tests for the register_gauge convenience wrapper."""
+
+    def test_creates_observable_gauge(self):
+        """Gauge is created on the correct meter."""
+        # Standard
+        import sys
+
+        mock_meter = MagicMock()
+        mock_otel = MagicMock()
+        mock_otel.get_meter.return_value = mock_meter
+        mock_otel.metrics = mock_otel
+
+        saved = {
+            k: sys.modules.get(k) for k in ("opentelemetry", "opentelemetry.metrics")
+        }
+        sys.modules["opentelemetry"] = mock_otel
+        sys.modules["opentelemetry.metrics"] = mock_otel
+        try:
+            register_gauge(
+                "test.meter",
+                "test.gauge",
+                "A test gauge",
+                lambda: 42,
+            )
+            mock_otel.get_meter.assert_called_once_with("test.meter")
+            mock_meter.create_observable_gauge.assert_called_once()
+            call_kwargs = mock_meter.create_observable_gauge.call_args
+            assert call_kwargs[0][0] == "test.gauge"
+            assert call_kwargs[1]["description"] == "A test gauge"
+        finally:
+            for k, v in saved.items():
+                if v is None:
+                    sys.modules.pop(k, None)
+                else:
+                    sys.modules[k] = v
+
+    def test_callback_invokes_func(self):
+        """The OTel callback delegates to the user-provided func."""
+        mock_meter = MagicMock()
+        mock_otel = MagicMock()
+        mock_otel.get_meter.return_value = mock_meter
+        mock_otel.Observation = lambda v: v
+
+        # Standard
+        import sys
+
+        saved = {
+            k: sys.modules.get(k) for k in ("opentelemetry", "opentelemetry.metrics")
+        }
+        sys.modules["opentelemetry"] = mock_otel
+        sys.modules["opentelemetry.metrics"] = mock_otel
+        mock_otel.metrics = mock_otel
+        try:
+            counter = {"value": 0}
+
+            def my_func():
+                counter["value"] += 1
+                return 99
+
+            register_gauge("m", "g", "desc", my_func)
+
+            # Extract the callback that was passed
+            cb_list = mock_meter.create_observable_gauge.call_args[1]["callbacks"]
+            assert len(cb_list) == 1
+            result = cb_list[0](None)
+            assert result == [99]
+            assert counter["value"] == 1
+        finally:
+            for k, v in saved.items():
+                if v is None:
+                    sys.modules.pop(k, None)
+                else:
+                    sys.modules[k] = v
+
+    def test_no_otel_logs_debug(self):
+        """When opentelemetry is missing, log debug and skip."""
+        # Standard
+        import sys
+
+        saved = {
+            k: sys.modules.pop(k, None)
+            for k in list(sys.modules)
+            if k.startswith("opentelemetry")
+        }
+        try:
+            # Force ImportError by removing the module
+            with patch(
+                "builtins.__import__",
+                side_effect=ImportError("no otel"),
+            ):
+                # Should not raise
+                register_gauge("m", "g", "desc", lambda: 0)
+        finally:
+            sys.modules.update({k: v for k, v in saved.items() if v is not None})
+
+    def test_register_multiple_gauges(self):
+        """Multiple gauges can be registered without error."""
+        mock_meter = MagicMock()
+        mock_otel = MagicMock()
+        mock_otel.get_meter.return_value = mock_meter
+
+        # Standard
+        import sys
+
+        saved = {
+            k: sys.modules.get(k) for k in ("opentelemetry", "opentelemetry.metrics")
+        }
+        sys.modules["opentelemetry"] = mock_otel
+        sys.modules["opentelemetry.metrics"] = mock_otel
+        mock_otel.metrics = mock_otel
+        try:
+            register_gauge("m", "g1", "d1", lambda: 1)
+            register_gauge("m", "g2", "d2", lambda: 2)
+            assert mock_meter.create_observable_gauge.call_count == 2
+        finally:
+            for k, v in saved.items():
+                if v is None:
+                    sys.modules.pop(k, None)
+                else:
+                    sys.modules[k] = v
diff --git a/tests/v1/mp_observability/trace/__init__.py b/tests/v1/mp_observability/trace/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/v1/mp_observability/trace/test_codecs.py b/tests/v1/mp_observability/trace/test_codecs.py
new file mode 100644
index 0000000..ff81526
--- /dev/null
+++ b/tests/v1/mp_observability/trace/test_codecs.py
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Round-trip tests for the trace codec registry."""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import (
+    AttnWindowDesc,
+    MemoryLayoutDesc,
+    ObjectKey,
+    PrefetchHandle,
+    TrimPolicy,
+)
+from lmcache.v1.mp_observability.trace import codecs
+
+
+def _roundtrip(v):
+    """Encode then decode through msgpack to mirror the recorder path."""
+    # Third Party
+    import msgspec
+
+    encoded = codecs.encode_value(v)
+    blob = msgspec.msgpack.encode(encoded)
+    decoded_msgpack = msgspec.msgpack.decode(blob)
+    return codecs.decode_value(decoded_msgpack)
+
+
+class TestPrimitives:
+    @pytest.mark.parametrize("v", [0, 1, -1, 3.14, "hi", b"bytes", True, False, None])
+    def test_passthrough(self, v):
+        assert _roundtrip(v) == v
+
+    def test_list(self):
+        assert _roundtrip([1, "a", None]) == [1, "a", None]
+
+    def test_dict(self):
+        assert _roundtrip({"a": 1, "b": [2, 3]}) == {"a": 1, "b": [2, 3]}
+
+    def test_tuple_preserved(self):
+        out = _roundtrip((1, 2, "x"))
+        assert out == (1, 2, "x")
+        assert isinstance(out, tuple)
+
+
+class TestObjectKey:
+    def test_roundtrip(self):
+        k = ObjectKey(chunk_hash=b"\x00\x01\x02", model_name="m", kv_rank=42)
+        out = _roundtrip(k)
+        assert out == k
+
+    def test_object_group_id_roundtrip(self):
+        k = ObjectKey(
+            chunk_hash=b"\x00\x01\x02",
+            model_name="m",
+            kv_rank=42,
+            object_group_id=7,
+        )
+        out = _roundtrip(k)
+        assert out == k
+        assert out.object_group_id == 7
+
+    def test_inside_list(self):
+        keys = [
+            ObjectKey(chunk_hash=b"a", model_name="m", kv_rank=1),
+            ObjectKey(chunk_hash=b"b", model_name="m", kv_rank=2),
+        ]
+        assert _roundtrip(keys) == keys
+
+
+class TestMemoryLayoutDesc:
+    def test_roundtrip(self):
+        d = MemoryLayoutDesc(
+            shapes=[torch.Size([2, 3]), torch.Size([4])],
+            dtypes=[torch.float16, torch.bfloat16],
+        )
+        out = _roundtrip(d)
+        assert out == d
+
+
+class TestPrefetchHandle:
+    def test_roundtrip(self):
+        h = PrefetchHandle(
+            prefetch_request_id=7,
+            external_request_id="req-1",
+            l1_found_indices=(0, 1, 2),
+            total_requested_keys=10,
+            submit_time=12345.6,
+            l2_orig_indices=(3, 4, 5),
+        )
+        out = _roundtrip(h)
+        assert out == h
+
+
+class TestTrimPolicy:
+    def test_roundtrip(self):
+        for p in TrimPolicy:
+            assert _roundtrip(p) is p
+
+
+class TestAttnWindowDesc:
+    def test_full_roundtrip(self):
+        out = _roundtrip(AttnWindowDesc(num_chunks_in_sw=[-1]))
+        assert out.num_chunks_in_sw == [-1]
+        assert out.is_full_attention(0)
+
+    def test_mixed_roundtrip(self):
+        out = _roundtrip(AttnWindowDesc(num_chunks_in_sw=[-1, 4, 1]))
+        assert out.num_chunks_in_sw == [-1, 4, 1]
+        assert out.is_full_attention(0)
+        assert not out.is_full_attention(1)
+        assert out.num_object_groups == 3
+
+    def test_empty_roundtrip(self):
+        out = _roundtrip(AttnWindowDesc(num_chunks_in_sw=[]))
+        assert out.num_chunks_in_sw == []
+        assert out.num_object_groups == 0
+
+
+class TestSet:
+    def test_roundtrip(self):
+        keys = {
+            ObjectKey(chunk_hash=b"a", model_name="m", kv_rank=1),
+            ObjectKey(chunk_hash=b"b", model_name="m", kv_rank=2),
+        }
+        out = _roundtrip(keys)
+        assert out == keys
+        assert isinstance(out, set)
+
+
+class TestTorchTypes:
+    def test_torch_size(self):
+        s = torch.Size([1, 2, 3])
+        out = _roundtrip(s)
+        assert isinstance(out, torch.Size)
+        assert tuple(out) == (1, 2, 3)
+
+    def test_torch_dtype(self):
+        for dt in [torch.float16, torch.bfloat16, torch.float32, torch.uint8]:
+            assert _roundtrip(dt) is dt
+
+
+class TestErrors:
+    def test_unknown_type_raises(self):
+        class Custom:
+            pass
+
+        with pytest.raises(TypeError, match="no codec"):
+            codecs.encode_value(Custom())
+
+    def test_unknown_tag_raises(self):
+        with pytest.raises(ValueError, match="unknown tag"):
+            codecs.decode_value({"__t__": "no-such-tag", "v": None})
+
+
+class TestEncodeArgs:
+    def test_args_dict(self):
+        args = {
+            "keys": [ObjectKey(chunk_hash=b"x", model_name="m", kv_rank=0)],
+            "mode": "new",
+            "extra_count": 0,
+        }
+        encoded = codecs.encode_args(args)
+        # mode and extra_count pass through; keys is wrapped.
+        assert encoded["mode"] == "new"
+        assert encoded["extra_count"] == 0
+        assert isinstance(encoded["keys"], list)
+        decoded = codecs.decode_args(encoded)
+        assert decoded == args
diff --git a/tests/v1/mp_observability/trace/test_decorator.py b/tests/v1/mp_observability/trace/test_decorator.py
new file mode 100644
index 0000000..4177c5c
--- /dev/null
+++ b/tests/v1/mp_observability/trace/test_decorator.py
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the ``@enable_tracing`` decorator and trace gate."""
+
+# Standard
+from unittest.mock import patch
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.mp_observability.event import EventType
+from lmcache.v1.mp_observability.trace.decorator import (
+    enable_tracing,
+    is_tracing_enabled,
+    publish_call_event,
+    set_tracing_enabled,
+)
+
+
+@pytest.fixture(autouse=True)
+def reset_gate():
+    """Ensure the trace gate is off before and after every test."""
+    set_tracing_enabled(False)
+    yield
+    set_tracing_enabled(False)
+
+
+class TestGate:
+    def test_default_off(self):
+        assert is_tracing_enabled() is False
+
+    def test_set_and_clear(self):
+        set_tracing_enabled(True)
+        assert is_tracing_enabled() is True
+        set_tracing_enabled(False)
+        assert is_tracing_enabled() is False
+
+
+class TestDisabledOverhead:
+    """When tracing is off, the decorator must not touch the EventBus."""
+
+    def test_no_publish_when_disabled(self):
+        @enable_tracing()
+        def f(x, y):
+            return x + y
+
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            assert f(1, 2) == 3
+            fake_bus.assert_not_called()
+
+    def test_no_signature_bind_when_disabled(self):
+        """Signature is bound at decoration time only when ENABLED.
+
+        We assert this indirectly: a function whose signature would
+        raise on bind (e.g. wrong arity) still completes its real call
+        successfully when the gate is off.
+        """
+        calls = []
+
+        @enable_tracing()
+        def f(*args, **kwargs):
+            calls.append((args, kwargs))
+
+        f(1, 2, k=3)
+        assert calls == [((1, 2), {"k": 3})]
+
+
+class TestEntryPublish:
+    def test_publishes_when_enabled(self):
+        seen = []
+
+        @enable_tracing(qualname="pkg.mod.Cls.method")
+        def method(self, a, b=2):
+            return a + b
+
+        set_tracing_enabled(True)
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            fake_bus.return_value.publish = lambda ev: seen.append(ev)
+            assert method("self_obj", 10) == 12
+
+        assert len(seen) == 1
+        ev = seen[0]
+        assert ev.event_type == EventType.TRACE_CALL
+        assert ev.metadata["qualname"] == "pkg.mod.Cls.method"
+        # ``self`` is dropped; defaults are filled in.
+        assert ev.metadata["args"] == {"a": 10, "b": 2}
+
+    def test_default_qualname(self):
+        @enable_tracing()
+        def some_func(x):
+            return x
+
+        # Nested defs include ``<locals>`` in __qualname__ so we
+        # compare against the actual current name to avoid coupling
+        # the test to the test method's path.
+        assert some_func.__lmc_trace_qualname__ == (
+            f"{some_func.__module__}.{some_func.__qualname__}"
+        )
+
+    def test_capture_filter(self):
+        seen = []
+
+        @enable_tracing(capture=["a"])
+        def f(a, b, c):
+            return a + b + c
+
+        set_tracing_enabled(True)
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            fake_bus.return_value.publish = lambda ev: seen.append(ev)
+            f(1, 2, 3)
+        assert seen[0].metadata["args"] == {"a": 1}
+
+    def test_redact_filter(self):
+        seen = []
+
+        @enable_tracing(redact=["password"])
+        def login(user, password):
+            return True
+
+        set_tracing_enabled(True)
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            fake_bus.return_value.publish = lambda ev: seen.append(ev)
+            login("alice", "hunter2")
+        assert seen[0].metadata["args"] == {"user": "alice"}
+
+    def test_entry_only_published_on_exception(self):
+        """Even when the wrapped function raises, the entry event has
+        already been published.  No exit event is emitted."""
+        seen = []
+
+        @enable_tracing()
+        def boom(x):
+            raise RuntimeError("nope")
+
+        set_tracing_enabled(True)
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            fake_bus.return_value.publish = lambda ev: seen.append(ev)
+            with pytest.raises(RuntimeError):
+                boom(7)
+        assert len(seen) == 1
+        assert seen[0].metadata["args"] == {"x": 7}
+
+
+class TestPublishCallEvent:
+    def test_no_publish_when_disabled(self):
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            publish_call_event("a.b", {"x": 1})
+            fake_bus.assert_not_called()
+
+    def test_publishes_when_enabled(self):
+        seen = []
+        set_tracing_enabled(True)
+        with patch(
+            "lmcache.v1.mp_observability.trace.decorator.get_event_bus"
+        ) as fake_bus:
+            fake_bus.return_value.publish = lambda ev: seen.append(ev)
+            publish_call_event("a.b", {"x": 1})
+        md = seen[0].metadata
+        assert md["qualname"] == "a.b"
+        assert md["args"] == {"x": 1}
+        # ``t_mono`` is stamped at publish time so the recorder's record
+        # timestamp is co-temporal with ``Event.timestamp``.
+        assert isinstance(md["t_mono"], float)
+        assert md["t_mono"] > 0
diff --git a/tests/v1/mp_observability/trace/test_recorder.py b/tests/v1/mp_observability/trace/test_recorder.py
new file mode 100644
index 0000000..0370ce5
--- /dev/null
+++ b/tests/v1/mp_observability/trace/test_recorder.py
@@ -0,0 +1,295 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for ``StorageTraceRecorder`` and the file format round-trip.
+
+These tests exercise the full publish → encode → write → read path
+without requiring a real ``StorageManager`` or any GPU code.
+"""
+
+# Standard
+from dataclasses import dataclass
+import os
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.mp_observability.event import Event, EventType
+from lmcache.v1.mp_observability.event_bus import EventBus, EventBusConfig
+from lmcache.v1.mp_observability.trace.decorator import (
+    is_tracing_enabled,
+    publish_call_event,
+    set_tracing_enabled,
+)
+from lmcache.v1.mp_observability.trace.format import (
+    FORMAT_VERSION,
+    MAGIC,
+    TRACE_SCHEMA_VERSION,
+)
+from lmcache.v1.mp_observability.trace.reader import TraceReader
+from lmcache.v1.mp_observability.trace.recorder import StorageTraceRecorder
+import lmcache.v1.mp_observability.event_bus as _bus_module
+
+
+@pytest.fixture(autouse=True)
+def restore_global_bus():
+    saved = _bus_module._global_bus
+    yield
+    _bus_module._global_bus = saved
+    set_tracing_enabled(False)
+
+
+@pytest.fixture
+def trace_path(tmp_path):
+    return str(tmp_path / "test.lct")
+
+
+@dataclass
+class _FakeAdapterCfg:
+    name: str = "noop"
+
+
+@dataclass
+class _FakeStorageManagerCfg:
+    chunk_size: int = 256
+    adapters: tuple = ()
+
+
+def _flush(bus: EventBus) -> None:
+    """Wait for the drain thread to process pending events."""
+    # The bus drains every 100ms; sleep slightly longer to be safe.
+    time.sleep(0.25)
+    # Force a final drain in case the wake event was missed.
+    bus._drain_all()
+
+
+class TestHeader:
+    def test_header_roundtrip(self, trace_path):
+        rec = StorageTraceRecorder(trace_path)
+        try:
+            rec.attach_storage_config(_FakeStorageManagerCfg())
+        finally:
+            rec.close()
+
+        with TraceReader(trace_path) as r:
+            h = r.header
+            assert h.magic == MAGIC
+            assert h.format_version == FORMAT_VERSION
+            assert h.trace_schema_version == TRACE_SCHEMA_VERSION
+            assert h.level == "storage"
+            assert h.t_mono_start > 0
+            assert h.t_wall_start > 0
+            assert h.sm_config_json  # populated by attach_storage_config
+            assert len(h.sm_config_digest) == 64  # sha256 hex
+
+    def test_header_without_attach(self, trace_path):
+        """When ``attach_storage_config`` is never called, the file is
+        still readable; config fields are empty."""
+        rec = StorageTraceRecorder(trace_path)
+        rec.close()
+        with TraceReader(trace_path) as r:
+            assert r.header.sm_config_json == ""
+            assert r.header.sm_config_digest == ""
+
+
+class TestGateLifecycle:
+    def test_init_flips_gate_on(self, trace_path):
+        assert is_tracing_enabled() is False
+        rec = StorageTraceRecorder(trace_path)
+        try:
+            assert is_tracing_enabled() is True
+        finally:
+            rec.close()
+        assert is_tracing_enabled() is False
+
+    def test_close_idempotent(self, trace_path):
+        rec = StorageTraceRecorder(trace_path)
+        rec.close()
+        rec.close()  # must not raise
+        assert is_tracing_enabled() is False
+
+
+class TestRecordRoundtrip:
+    def test_records_via_eventbus(self, trace_path):
+        bus = EventBus(EventBusConfig(enabled=True))
+        _bus_module._global_bus = bus
+        bus.start()
+
+        rec = StorageTraceRecorder(trace_path)
+        bus.register_subscriber(rec)
+        try:
+            publish_call_event(
+                "lmcache.X.method",
+                {
+                    "keys": [ObjectKey(chunk_hash=b"\x01", model_name="m", kv_rank=1)],
+                    "mode": "new",
+                },
+            )
+            publish_call_event(
+                "lmcache.X.method2",
+                {"extra_count": 7},
+            )
+            _flush(bus)
+        finally:
+            bus.stop()  # invokes recorder.shutdown()
+
+        with TraceReader(trace_path) as r:
+            records = list(r.records())
+        assert len(records) == 2
+        assert records[0].qualname == "lmcache.X.method"
+        # Decoder yields msgpack-friendly form; codec decode happens in
+        # the replay driver (PR2). We assert structure only.
+        assert "keys" in records[0].args
+        assert records[0].args["mode"] == "new"
+        assert records[1].args["extra_count"] == 7
+        assert records[0].t_mono >= 0
+        assert records[1].t_mono >= records[0].t_mono
+
+    def test_layout_desc_roundtrip(self, trace_path):
+        """End-to-end: a publish carrying a MemoryLayoutDesc round-trips
+        through codec encode → file → reader → codec decode."""
+        # First Party
+        from lmcache.v1.mp_observability.trace import codecs
+
+        bus = EventBus(EventBusConfig(enabled=True))
+        _bus_module._global_bus = bus
+        bus.start()
+
+        rec = StorageTraceRecorder(trace_path)
+        bus.register_subscriber(rec)
+        layout = MemoryLayoutDesc(
+            shapes=[torch.Size([2, 3])],
+            dtypes=[torch.float16],
+        )
+        try:
+            publish_call_event("lmcache.X.method", {"layout_desc": layout})
+            _flush(bus)
+        finally:
+            bus.stop()
+
+        with TraceReader(trace_path) as r:
+            records = list(r.records())
+        assert len(records) == 1
+        decoded_args = codecs.decode_args(records[0].args)
+        assert decoded_args["layout_desc"] == layout
+
+
+class TestReaderRobustness:
+    def test_truncated_file_warns(self, trace_path):
+        bus = EventBus(EventBusConfig(enabled=True))
+        _bus_module._global_bus = bus
+        bus.start()
+
+        rec = StorageTraceRecorder(trace_path)
+        bus.register_subscriber(rec)
+        try:
+            publish_call_event("a.b", {"x": 1})
+            _flush(bus)
+        finally:
+            bus.stop()
+
+        # Truncate the file mid-frame.
+        size = os.path.getsize(trace_path)
+        with open(trace_path, "r+b") as fh:
+            fh.truncate(size - 3)
+
+        with TraceReader(trace_path) as r:
+            # Header was full; truncation hit the record body.
+            records = list(r.records())
+        # No assert on record count — it may be 0 or 1 depending on
+        # how big the record was; the point is no exception escapes.
+        assert isinstance(records, list)
+
+    def test_bad_magic_rejected(self, trace_path):
+        # Build a structurally valid Header frame but with wrong magic
+        # so the reader's magic check (rather than msgspec's schema
+        # check) fires.
+        # First Party
+        from lmcache.v1.mp_observability.trace.format import (
+            FORMAT_VERSION,
+            Header,
+            encode_header,
+        )
+
+        bad = Header(
+            magic=b"WRNG",
+            format_version=FORMAT_VERSION,
+            level="storage",
+            trace_schema_version=TRACE_SCHEMA_VERSION,
+            t_mono_start=0.0,
+            t_wall_start=0.0,
+            sm_config_json="",
+            sm_config_digest="",
+        )
+        frame = encode_header(bad)
+        with open(trace_path, "wb") as fh:
+            fh.write(len(frame).to_bytes(4, "big") + frame)
+        with pytest.raises(ValueError, match="bad magic"):
+            TraceReader(trace_path)
+
+
+class TestDroppedCount:
+    def test_unencodable_arg_drops_record(self, trace_path):
+        """An arg whose type has no codec is dropped, not crashed on."""
+        bus = EventBus(EventBusConfig(enabled=True))
+        _bus_module._global_bus = bus
+        bus.start()
+
+        rec = StorageTraceRecorder(trace_path)
+        bus.register_subscriber(rec)
+
+        class Unknown:
+            pass
+
+        try:
+            publish_call_event("a.b", {"v": Unknown()})
+            publish_call_event("a.c", {"v": 1})
+            _flush(bus)
+        finally:
+            bus.stop()
+
+        assert rec.dropped_count == 1
+        with TraceReader(trace_path) as r:
+            records = list(r.records())
+        assert len(records) == 1
+        assert records[0].qualname == "a.c"
+
+
+class TestEvent:
+    def test_event_construction(self):
+        # Sanity: the event constructor accepts our metadata shape.
+        ev = Event(
+            event_type=EventType.TRACE_CALL,
+            metadata={"qualname": "x", "args": {}},
+        )
+        assert ev.event_type == EventType.TRACE_CALL
+
+
+class TestShutdownContract:
+    def test_bus_stop_closes_recorder(self, trace_path):
+        """``EventBus.stop()`` alone must flush, fsync, and close the
+        recorder — without an explicit ``close()`` call.  Regression
+        guard for the server shutdown chain (event_bus.stop →
+        subscriber.shutdown → recorder.close)."""
+        bus = EventBus(EventBusConfig(enabled=True))
+        _bus_module._global_bus = bus
+        bus.start()
+
+        rec = StorageTraceRecorder(trace_path)
+        bus.register_subscriber(rec)
+        publish_call_event("a.b", {"x": 1})
+        _flush(bus)
+
+        # Only the bus is stopped; the recorder is not closed directly.
+        bus.stop()
+
+        # Gate must be off and the record must be readable from disk
+        # (i.e. the file was flushed + closed by shutdown()).
+        assert is_tracing_enabled() is False
+        with TraceReader(trace_path) as r:
+            records = list(r.records())
+        assert len(records) == 1
+        assert records[0].qualname == "a.b"
diff --git a/tests/v1/multiprocess/__init__.py b/tests/v1/multiprocess/__init__.py
new file mode 100644
index 0000000..db43924
--- /dev/null
+++ b/tests/v1/multiprocess/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+
diff --git a/tests/v1/multiprocess/http_apis/__init__.py b/tests/v1/multiprocess/http_apis/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/v1/multiprocess/http_apis/test_cache_api.py b/tests/v1/multiprocess/http_apis/test_cache_api.py
new file mode 100644
index 0000000..e4e71ac
--- /dev/null
+++ b/tests/v1/multiprocess/http_apis/test_cache_api.py
@@ -0,0 +1,582 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP-level tests for the MP server's ``/cache/*`` surface (``cache_api``).
+
+Covers the object endpoints (``/cache/objects``), the
+prefetch endpoints (``/cache/prefetches``), and the diagnostics endpoints
+(``/cache/clear``, ``/cache/checksums``). Handlers are thin over the typed
+services resolved from the app context, so these inject a fake engine via
+``build_context`` and exercise the HTTP layer without a real cache engine.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Third Party
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import KeyEntry, KeyListPage, ObjectKey
+from lmcache.v1.multiprocess.cache_control.object_service import MAX_DELETE_BATCH
+from lmcache.v1.multiprocess.http_apis.cache_api import router as cache_router
+from lmcache.v1.multiprocess.http_apis.dependencies import build_context
+from lmcache.v1.multiprocess.http_apis.error_handlers import register_error_handlers
+
+
+@dataclass
+class _FakeDescriptor:
+    """Minimal descriptor — only ``type_name`` is read."""
+
+    type_name: str = "s3"
+
+
+@dataclass
+class _FakeAdapter:
+    """Records calls and serves canned responses for adapter methods."""
+
+    delete_calls: list[list[ObjectKey]] = field(default_factory=list)
+    delete_raises: Optional[BaseException] = None
+
+    list_page: Optional[KeyListPage] = None
+    list_raises: Optional[BaseException] = None
+    last_list_kwargs: dict[str, object] = field(default_factory=dict)
+
+    def delete(self, keys: list[ObjectKey]) -> None:
+        self.delete_calls.append(list(keys))
+        if self.delete_raises is not None:
+            raise self.delete_raises
+
+    def list_l2_keys(
+        self,
+        model_name: Optional[str] = None,
+        page_size: int = 500,
+        cursor: Optional[str] = None,
+    ) -> KeyListPage:
+        self.last_list_kwargs = {
+            "model_name": model_name,
+            "page_size": page_size,
+            "cursor": cursor,
+        }
+        if self.list_raises is not None:
+            raise self.list_raises
+        return self.list_page or KeyListPage(entries=(), next_page_token=None)
+
+
+@dataclass
+class _FakeStorageManager:
+    """Implements ``l2_adapters()``. An empty list reproduces the "no L2 adapters
+    configured" condition."""
+
+    adapters: list[tuple[str, _FakeAdapter]] = field(default_factory=list)
+
+    def l2_adapters(self) -> list[tuple[_FakeDescriptor, _FakeAdapter]]:
+        return [(_FakeDescriptor(type_name=n), a) for n, a in self.adapters]
+
+
+class _FakeEngine:
+    def __init__(self, sm: _FakeStorageManager):
+        self.storage_manager = sm
+
+
+def _make_app(sm: Optional[_FakeStorageManager]) -> FastAPI:
+    """Build an app with the cache router and a context wrapping a fake engine
+    (or no context, reproducing the not-initialized condition)."""
+    app = FastAPI()
+    app.include_router(cache_router)
+    register_error_handlers(app)
+    if sm is not None:
+        app.state.context = build_context(_FakeEngine(sm))
+    return app
+
+
+def _hex(n: int, width: int = 4) -> str:
+    return n.to_bytes(width, "big").hex()
+
+
+def _sm_with(*entries: tuple[str, _FakeAdapter]) -> _FakeStorageManager:
+    return _FakeStorageManager(adapters=list(entries))
+
+
+# =============================================================================
+# Delete objects
+# =============================================================================
+
+
+class TestDeleteObjectsEndpoint:
+    def test_happy_path_defaults_to_primary(self):
+        primary = _FakeAdapter()
+        secondary = _FakeAdapter()
+        sm = _sm_with(("s3", primary), ("fs", secondary))
+        client = TestClient(_make_app(sm))
+
+        resp = client.request(
+            "DELETE",
+            "/cache/objects",
+            json={
+                "keys": [
+                    {
+                        "chunk_hash_hex": _hex(1),
+                        "model_name": "llama",
+                        "kv_rank": 0,
+                        "cache_salt": "alice",
+                    },
+                    {"chunk_hash_hex": _hex(2), "model_name": "llama", "kv_rank": 0},
+                ],
+            },
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"requested": 2, "adapter": "s3", "ok": True}
+        assert len(primary.delete_calls) == 1
+        assert secondary.delete_calls == []
+        forwarded = primary.delete_calls[0]
+        assert forwarded[0] == ObjectKey(
+            chunk_hash=b"\x00\x00\x00\x01",
+            model_name="llama",
+            kv_rank=0,
+            cache_salt="alice",
+        )
+        assert forwarded[1].cache_salt == ""
+
+    def test_adapter_in_body_selects_non_primary(self):
+        primary = _FakeAdapter()
+        secondary = _FakeAdapter()
+        sm = _sm_with(("s3", primary), ("fs", secondary))
+        client = TestClient(_make_app(sm))
+
+        resp = client.request(
+            "DELETE",
+            "/cache/objects",
+            json={
+                "adapter": "fs",
+                "keys": [{"chunk_hash_hex": _hex(1), "model_name": "m", "kv_rank": 0}],
+            },
+        )
+        assert resp.status_code == 200, resp.text
+        assert resp.json()["adapter"] == "fs"
+        assert primary.delete_calls == []
+        assert len(secondary.delete_calls) == 1
+
+    def test_404_when_adapter_no_match(self):
+        client = TestClient(_make_app(_sm_with(("s3", _FakeAdapter()))))
+        resp = client.request(
+            "DELETE", "/cache/objects", json={"adapter": "nope", "keys": []}
+        )
+        assert resp.status_code == 404
+        assert "nope" in resp.json()["detail"]
+
+    def test_propagates_adapter_failure_in_body(self):
+        adapter = _FakeAdapter(delete_raises=RuntimeError("s3 down"))
+        client = TestClient(_make_app(_sm_with(("s3", adapter))))
+        resp = client.request("DELETE", "/cache/objects", json={"keys": []})
+        assert resp.status_code == 200, resp.text
+        body = resp.json()
+        assert body["adapter"] == "s3"
+        assert body["ok"] is False
+        assert "s3 down" in body["error"]
+
+    def test_400_on_unsupported_tier(self):
+        client = TestClient(_make_app(_sm_with(("s3", _FakeAdapter()))))
+        resp = client.request(
+            "DELETE", "/cache/objects", json={"tier": "l1", "keys": []}
+        )
+        assert resp.status_code == 400
+        assert "tier" in resp.json()["detail"]
+
+    def test_503_when_no_adapters_configured(self):
+        client = TestClient(_make_app(_sm_with()))
+        resp = client.request("DELETE", "/cache/objects", json={"keys": []})
+        assert resp.status_code == 503
+        assert "no L2 adapters" in resp.json()["detail"]
+
+    def test_503_when_not_initialized(self):
+        client = TestClient(_make_app(None))
+        assert (
+            client.request("DELETE", "/cache/objects", json={"keys": []}).status_code
+            == 503
+        )
+
+    @pytest.mark.parametrize(
+        "body",
+        [
+            "not-json-text",
+            {},
+            {"keys": "not-a-list"},
+            {"keys": [{"chunk_hash_hex": _hex(1), "kv_rank": 0}]},
+            {"keys": [{"chunk_hash_hex": _hex(1), "model_name": "m", "kv_rank": "x"}]},
+        ],
+    )
+    def test_422_on_validation_failure(self, body):
+        adapter = _FakeAdapter()
+        client = TestClient(_make_app(_sm_with(("s3", adapter))))
+        if isinstance(body, str):
+            resp = client.request(
+                "DELETE",
+                "/cache/objects",
+                content=body,
+                headers={"content-type": "application/json"},
+            )
+        else:
+            resp = client.request("DELETE", "/cache/objects", json=body)
+        assert resp.status_code == 422, resp.text
+        assert adapter.delete_calls == []
+
+    @pytest.mark.parametrize(
+        "body",
+        [
+            {"keys": [{"chunk_hash_hex": "zz", "model_name": "m", "kv_rank": 0}]},
+            {
+                "keys": [
+                    {"chunk_hash_hex": _hex(1), "model_name": "bad@name", "kv_rank": 0}
+                ]
+            },
+        ],
+    )
+    def test_400_on_object_key_invariant_violation(self, body):
+        adapter = _FakeAdapter()
+        client = TestClient(_make_app(_sm_with(("s3", adapter))))
+        resp = client.request("DELETE", "/cache/objects", json=body)
+        assert resp.status_code == 400, resp.text
+        assert adapter.delete_calls == []
+
+    def test_400_when_batch_exceeds_cap(self):
+        adapter = _FakeAdapter()
+        client = TestClient(_make_app(_sm_with(("s3", adapter))))
+        oversized = [
+            {"chunk_hash_hex": _hex(i), "model_name": "m", "kv_rank": 0}
+            for i in range(MAX_DELETE_BATCH + 1)
+        ]
+        resp = client.request("DELETE", "/cache/objects", json={"keys": oversized})
+        assert resp.status_code == 400, resp.text
+        assert "too many keys" in resp.json()["detail"]
+        assert adapter.delete_calls == []
+
+
+# =============================================================================
+# List objects
+# =============================================================================
+
+
+class TestListObjectsEndpoint:
+    def test_happy_path_defaults_to_primary(self):
+        k1 = ObjectKey(
+            chunk_hash=b"\xde\xad\xbe\xef",
+            model_name="llama",
+            kv_rank=2,
+            cache_salt="alice",
+        )
+        primary = _FakeAdapter(
+            list_page=KeyListPage(
+                entries=(KeyEntry(key=k1.to_encoded_object_key(), size_bytes=4096),),
+                next_page_token="opaque-cursor",
+            )
+        )
+        secondary = _FakeAdapter()
+        sm = _sm_with(("s3", primary), ("fs", secondary))
+        client = TestClient(_make_app(sm))
+
+        resp = client.get(
+            "/cache/objects", params={"model_name": "llama", "page_size": 100}
+        )
+        assert resp.status_code == 200, resp.text
+        body = resp.json()
+        assert body["adapter"] == "s3"
+        assert body["entries"] == [
+            {
+                "key": {
+                    "chunk_hash_hex": "deadbeef",
+                    "model_name": "llama",
+                    "kv_rank": 2,
+                    "object_group_id": 0,
+                    "cache_salt": "alice",
+                },
+                "size_bytes": 4096,
+            }
+        ]
+        assert body["next_page_token"] == "opaque-cursor"
+        assert primary.last_list_kwargs == {
+            "model_name": "llama",
+            "page_size": 100,
+            "cursor": None,
+        }
+        assert secondary.last_list_kwargs == {}
+
+    def test_adapter_param_selects_non_primary(self):
+        primary = _FakeAdapter()
+        secondary = _FakeAdapter(
+            list_page=KeyListPage(entries=(), next_page_token="from-fs")
+        )
+        sm = _sm_with(("s3", primary), ("fs", secondary))
+        client = TestClient(_make_app(sm))
+        resp = client.get("/cache/objects", params={"adapter": "fs"})
+        assert resp.status_code == 200, resp.text
+        body = resp.json()
+        assert body["adapter"] == "fs"
+        assert body["next_page_token"] == "from-fs"
+        assert primary.last_list_kwargs == {}
+
+    def test_404_when_adapter_no_match(self):
+        client = TestClient(_make_app(_sm_with(("s3", _FakeAdapter()))))
+        assert (
+            client.get("/cache/objects", params={"adapter": "nope"}).status_code == 404
+        )
+
+    def test_page_token_threads_through_as_cursor(self):
+        adapter = _FakeAdapter()
+        client = TestClient(_make_app(_sm_with(("s3", adapter))))
+        client.get("/cache/objects", params={"page_token": "abc"})
+        assert adapter.last_list_kwargs["cursor"] == "abc"
+
+    def test_400_on_unsupported_tier(self):
+        client = TestClient(_make_app(_sm_with(("s3", _FakeAdapter()))))
+        resp = client.get("/cache/objects", params={"tier": "l1"})
+        assert resp.status_code == 400
+
+    def test_503_when_no_adapters_configured(self):
+        client = TestClient(_make_app(_sm_with()))
+        assert client.get("/cache/objects").status_code == 503
+
+    def test_503_when_listing_unsupported(self):
+        adapter = _FakeAdapter(list_raises=NotImplementedError("no listing"))
+        client = TestClient(_make_app(_sm_with(("fs", adapter))))
+        resp = client.get("/cache/objects")
+        assert resp.status_code == 503
+        assert "does not support listing" in resp.json()["detail"]
+
+    def test_400_on_malformed_page_token(self):
+        adapter = _FakeAdapter(list_raises=ValueError("malformed cursor"))
+        client = TestClient(_make_app(_sm_with(("s3", adapter))))
+        assert (
+            client.get("/cache/objects", params={"page_token": "garbage"}).status_code
+            == 400
+        )
+
+    def test_503_when_not_initialized(self):
+        assert TestClient(_make_app(None)).get("/cache/objects").status_code == 503
+
+
+# =============================================================================
+# Prefetch
+# =============================================================================
+
+
+@dataclass
+class _FakeLayoutRegistry:
+    layout: Optional[object] = None
+    find_calls: list[tuple[str, int]] = field(default_factory=list)
+
+    def find(self, model_name: str, world_size: int) -> Optional[object]:
+        self.find_calls.append((model_name, world_size))
+        return self.layout
+
+
+class _PrefetchHandle:
+    def __init__(self, total: int) -> None:
+        self.total_requested_keys = total
+
+
+class _PrefetchBitmap:
+    def __init__(self, n: int) -> None:
+        self._n = n
+
+    def popcount(self) -> int:
+        return self._n
+
+
+@dataclass
+class _PrefetchStorageManager:
+    submit_calls: list[dict] = field(default_factory=list)
+
+    def submit_prefetch_task(
+        self, keys, layout_desc, mode=None, **_
+    ) -> _PrefetchHandle:
+        self.submit_calls.append({"keys": list(keys), "mode": mode})
+        return _PrefetchHandle(len(keys))
+
+    def query_prefetch_status(self, handle) -> _PrefetchBitmap:
+        return _PrefetchBitmap(handle.total_requested_keys)
+
+
+@dataclass
+class _FakeTokenHasher:
+    chunk_size: int = 4
+
+    def compute_chunk_hashes(self, token_ids: list[int]) -> list[bytes]:
+        n = len(token_ids) // self.chunk_size
+        return [i.to_bytes(4, "big") for i in range(n)]
+
+
+@dataclass
+class _FakeContext:
+    layout_desc_registry: _FakeLayoutRegistry
+    storage_manager: _PrefetchStorageManager
+    token_hasher: _FakeTokenHasher = field(default_factory=_FakeTokenHasher)
+
+
+class _PrefetchEngine:
+    def __init__(self, ctx: _FakeContext):
+        self.context = ctx
+        self.storage_manager = ctx.storage_manager
+
+
+def _make_prefetch_app(ctx: Optional[_FakeContext]) -> FastAPI:
+    app = FastAPI()
+    app.include_router(cache_router)
+    register_error_handlers(app)
+    if ctx is not None:
+        app.state.context = build_context(_PrefetchEngine(ctx))
+    return app
+
+
+def _ctx(layout: Optional[object]) -> _FakeContext:
+    return _FakeContext(
+        layout_desc_registry=_FakeLayoutRegistry(layout=layout),
+        storage_manager=_PrefetchStorageManager(),
+    )
+
+
+def _prefetch_body(token_ids: list[int], world_size: int = 2, salt: str = "") -> dict:
+    return {
+        "model_name": "m",
+        "world_size": world_size,
+        "token_ids": token_ids,
+        "cache_salt": salt,
+    }
+
+
+class TestPrefetchEndpoint:
+    def test_submit_returns_request_id_and_resolves_layout(self):
+        ctx = _ctx(layout=object())
+        client = TestClient(_make_prefetch_app(ctx))
+        resp = client.post(
+            "/cache/prefetches",
+            json=_prefetch_body([1, 2, 3, 4, 5, 6, 7, 8], world_size=2),
+        )
+        assert resp.status_code == 202, resp.text
+        body = resp.json()
+        assert body["status"] == "submitted"
+        assert body["chunks"] == 2
+        assert body["request_id"]
+        assert ("m", 2) in ctx.layout_desc_registry.find_calls
+
+    def test_status_poll_completes_then_404(self):
+        ctx = _ctx(layout=object())
+        client = TestClient(_make_prefetch_app(ctx))
+        rid = client.post(
+            "/cache/prefetches",
+            json=_prefetch_body([1, 2, 3, 4, 5, 6, 7, 8], world_size=2),
+        ).json()["request_id"]
+
+        resp = client.get(f"/cache/prefetches/{rid}")
+        assert resp.status_code == 200, resp.text
+        body = resp.json()
+        assert body["status"] == "completed"
+        assert body["found_keys"] == 4
+        assert body["total_keys"] == 4
+        assert client.get(f"/cache/prefetches/{rid}").status_code == 404
+
+    def test_status_unknown_request_id_404(self):
+        client = TestClient(_make_prefetch_app(_ctx(layout=object())))
+        assert client.get("/cache/prefetches/nope").status_code == 404
+
+    def test_short_sequence_is_noop(self):
+        client = TestClient(_make_prefetch_app(_ctx(layout=object())))
+        resp = client.post("/cache/prefetches", json=_prefetch_body([1, 2]))
+        assert resp.status_code == 202, resp.text
+        assert resp.json() == {"chunks": 0, "status": "noop"}
+
+    def test_503_when_layout_not_registered(self):
+        client = TestClient(_make_prefetch_app(_ctx(layout=None)))
+        resp = client.post(
+            "/cache/prefetches", json=_prefetch_body([1, 2, 3, 4], world_size=99)
+        )
+        assert resp.status_code == 503
+
+    def test_400_on_invalid_cache_salt(self):
+        client = TestClient(_make_prefetch_app(_ctx(layout=object())))
+        resp = client.post(
+            "/cache/prefetches", json=_prefetch_body([1, 2, 3, 4], salt="bad@salt")
+        )
+        assert resp.status_code == 400
+
+    def test_400_on_unsupported_direction(self):
+        client = TestClient(_make_prefetch_app(_ctx(layout=object())))
+        body = _prefetch_body([1, 2, 3, 4])
+        body["target_tier"] = "l2"
+        resp = client.post("/cache/prefetches", json=body)
+        assert resp.status_code == 400
+
+    def test_503_when_not_initialized(self):
+        client = TestClient(_make_prefetch_app(None))
+        assert (
+            client.post(
+                "/cache/prefetches", json=_prefetch_body([1, 2, 3, 4])
+            ).status_code
+            == 503
+        )
+
+
+# =============================================================================
+# Diagnostics (clear)
+# =============================================================================
+
+
+@dataclass
+class _ClearEngine:
+    clear_calls: int = 0
+    cache_contexts: Optional[dict] = None
+
+    def clear(self) -> None:
+        self.clear_calls += 1
+
+
+def _make_clear_app(engine: Optional[_ClearEngine]) -> FastAPI:
+    app = FastAPI()
+    app.include_router(cache_router)
+    register_error_handlers(app)
+    if engine is not None:
+        app.state.context = build_context(engine)
+    return app
+
+
+class TestClearEndpoint:
+    def test_clear_l1(self):
+        engine = _ClearEngine()
+        client = TestClient(_make_clear_app(engine))
+        resp = client.post("/cache/clear", json={"tier": "l1"})
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"status": "ok", "cleared": {"tier": "l1"}}
+        assert engine.clear_calls == 1
+
+    def test_clear_no_body_defaults_to_l1(self):
+        """The body is optional; an absent body defaults to tier l1."""
+        engine = _ClearEngine()
+        client = TestClient(_make_clear_app(engine))
+        resp = client.post("/cache/clear")
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"status": "ok", "cleared": {"tier": "l1"}}
+        assert engine.clear_calls == 1
+
+    def test_clear_unsupported_tier(self):
+        client = TestClient(_make_clear_app(_ClearEngine()))
+        resp = client.post("/cache/clear", json={"tier": "l2"})
+        assert resp.status_code == 400
+
+    def test_clear_503_when_not_initialized(self):
+        assert (
+            TestClient(_make_clear_app(None)).post("/cache/clear", json={}).status_code
+            == 503
+        )
+
+    def test_checksums_503_when_not_initialized(self):
+        resp = TestClient(_make_clear_app(None)).post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        assert resp.status_code == 503
+
+    def test_checksums_501_when_engine_unsupported(self):
+        # _ClearEngine has cache_contexts=None -> 501.
+        client = TestClient(_make_clear_app(_ClearEngine()))
+        resp = client.post("/cache/checksums", json={"block_ids": [0], "chunk_size": 1})
+        assert resp.status_code == 501
diff --git a/tests/v1/multiprocess/http_apis/test_common_api.py b/tests/v1/multiprocess/http_apis/test_common_api.py
new file mode 100644
index 0000000..b5d2187
--- /dev/null
+++ b/tests/v1/multiprocess/http_apis/test_common_api.py
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for common_api.py — the aggregation layer that pulls in
+``internal_api_server/common`` routers while excluding
+vLLM-specific modules.
+
+Covers:
+- ``run_script_api`` IS now registered on the mp HTTP server.
+- Other common endpoints (env, loglevel, metrics, …) ARE present.
+- /run_script works in mp mode (no lmcache_adapter on app.state).
+- /run_script works in inProcess mode (lmcache_adapter on app.state).
+"""
+
+# Standard
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Optional
+
+# Third Party
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+# First Party
+from lmcache.v1.internal_api_server.common.run_script_api import (
+    router as run_script_router,
+)
+from lmcache.v1.multiprocess.config import MPServerConfig
+from lmcache.v1.multiprocess.http_api_registry import HTTPAPIRegistry
+
+
+def _app_with_all_apis() -> FastAPI:
+    app = FastAPI()
+    registry = HTTPAPIRegistry(app)
+    registry.register_all_apis()
+    return app
+
+
+class TestCommonApiAggregation:
+    def test_run_script_endpoint_present(self):
+        """/run_script must be registered on the mp server."""
+        app = _app_with_all_apis()
+        paths = set(app.openapi()["paths"])
+        assert "/run_script" in paths
+
+    def test_common_env_endpoint_present(self):
+        """/env from env_api should be registered."""
+        app = _app_with_all_apis()
+        paths = set(app.openapi()["paths"])
+        assert "/env" in paths
+
+    def test_common_loglevel_endpoint_present(self):
+        """/loglevel from loglevel_api should be registered."""
+        app = _app_with_all_apis()
+        paths = set(app.openapi()["paths"])
+        assert "/loglevel" in paths
+
+    def test_config_endpoint_present(self):
+        """/config from config_api should be registered."""
+        app = _app_with_all_apis()
+        paths = set(app.openapi()["paths"])
+        assert "/config" in paths
+
+
+@dataclass
+class _FakeAdapterConfig:
+    script_allowed_imports: Optional[list] = None
+
+
+class _FakeAdapter:
+    def __init__(self, allowed=None):
+        self.config = _FakeAdapterConfig(script_allowed_imports=allowed)
+
+
+def _make_run_script_app(state_kwargs: dict) -> FastAPI:
+    app = FastAPI()
+    app.include_router(run_script_router)
+    for k, v in state_kwargs.items():
+        setattr(app.state, k, v)
+    return app
+
+
+class TestRunScriptMpMode:
+    """Tests for /run_script in mp mode (no lmcache_adapter)."""
+
+    def test_mp_mode_basic_script(self):
+        """Script executes and returns result in mp mode."""
+        app = _make_run_script_app({"configs": {"mp": MPServerConfig()}})
+        client = TestClient(app)
+        script = b"result = 1 + 2"
+        resp = client.post(
+            "/run_script",
+            files={"script": ("test.py", BytesIO(script), "text/plain")},
+        )
+        assert resp.status_code == 200
+        assert resp.text == "3"
+
+    def test_mp_mode_no_script_file(self):
+        """Missing script file returns 400."""
+        app = _make_run_script_app({"configs": {"mp": MPServerConfig()}})
+        client = TestClient(app)
+        resp = client.post("/run_script", data={})
+        assert resp.status_code == 400
+
+    def test_mp_mode_allowed_imports(self):
+        """script_allowed_imports in MPServerConfig is respected."""
+        cfg = MPServerConfig(script_allowed_imports=["math"])
+        app = _make_run_script_app({"configs": {"mp": cfg}})
+        client = TestClient(app)
+        script = b"math = __import__('math'); result = math.floor(3.9)"
+        resp = client.post(
+            "/run_script",
+            files={"script": ("test.py", BytesIO(script), "text/plain")},
+        )
+        assert resp.status_code == 200
+        assert resp.text == "3"
+
+    def test_mp_mode_no_state(self):
+        """No app.state set — allowed_imports falls back to empty list."""
+        app = FastAPI()
+        app.include_router(run_script_router)
+        client = TestClient(app)
+        script = b"result = 'ok'"
+        resp = client.post(
+            "/run_script",
+            files={"script": ("test.py", BytesIO(script), "text/plain")},
+        )
+        assert resp.status_code == 200
+        assert resp.text == "ok"
+
+
+class TestRunScriptInProcessMode:
+    """Tests for /run_script in inProcess mode (lmcache_adapter present)."""
+
+    def test_inprocess_mode_basic_script(self):
+        """Script executes and returns result in inProcess mode."""
+        app = _make_run_script_app({"lmcache_adapter": _FakeAdapter()})
+        client = TestClient(app)
+        script = b"result = 'hello'"
+        resp = client.post(
+            "/run_script",
+            files={"script": ("test.py", BytesIO(script), "text/plain")},
+        )
+        assert resp.status_code == 200
+        assert resp.text == "hello"
+
+    def test_inprocess_mode_default_result(self):
+        """Script with no result variable returns default message."""
+        app = _make_run_script_app({"lmcache_adapter": _FakeAdapter()})
+        client = TestClient(app)
+        script = b"x = 1"
+        resp = client.post(
+            "/run_script",
+            files={"script": ("test.py", BytesIO(script), "text/plain")},
+        )
+        assert resp.status_code == 200
+        assert resp.text == "Script executed successfully"
diff --git a/tests/v1/multiprocess/http_apis/test_config_api.py b/tests/v1/multiprocess/http_apis/test_config_api.py
new file mode 100644
index 0000000..0cf532e
--- /dev/null
+++ b/tests/v1/multiprocess/http_apis/test_config_api.py
@@ -0,0 +1,201 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the ``/config`` endpoint exposed by config_api.
+
+Covers:
+- Dataclass configs serialized with nested values.
+- Plain-dict configs merged via ``make_json_safe``.
+- Missing ``app.state.configs`` returns HTTP 503.
+- Response body is valid JSON and is indented for readability.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from pathlib import Path
+import json
+
+# Third Party
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.http_apis.config_api import router as config_router
+from lmcache.v1.multiprocess.http_apis.dependencies import build_context
+
+
+@dataclass
+class _FakeMPConfig:
+    host: str = "0.0.0.0"
+    port: int = 9000
+    path: Path = Path("/tmp/mp")
+
+
+@dataclass
+class _FakeStorageConfig:
+    backend: str = "local"
+    capacity: int = 1024
+    tags: list = field(default_factory=lambda: ["a", "b"])
+
+
+def _make_app(configs):
+    app = FastAPI()
+    app.include_router(config_router)
+    if configs is not None:
+        app.state.configs = configs
+    return app
+
+
+class TestConfigEndpoint:
+    def test_dataclass_configs_serialized(self):
+        app = _make_app(
+            {
+                "mp": _FakeMPConfig(host="1.2.3.4", port=8000),
+                "storage": _FakeStorageConfig(backend="redis"),
+            }
+        )
+        client = TestClient(app)
+        resp = client.get("/config")
+
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["mp"] == {
+            "host": "1.2.3.4",
+            "port": 8000,
+            "path": "/tmp/mp",
+        }
+        assert body["storage"]["backend"] == "redis"
+        assert body["storage"]["capacity"] == 1024
+        assert body["storage"]["tags"] == ["a", "b"]
+
+    def test_plain_dict_config_merged(self):
+        """Non-dataclass values still go through make_json_safe."""
+        app = _make_app({"extra": {"k": Path("/v")}})
+        client = TestClient(app)
+
+        body = client.get("/config").json()
+        assert body == {"extra": {"k": "/v"}}
+
+    def test_returns_503_when_configs_missing(self):
+        """/config returns 503 if app.state.configs is absent."""
+        client = TestClient(_make_app(configs=None))
+        resp = client.get("/config")
+
+        assert resp.status_code == 503
+        assert resp.json() == {"error": "configs not initialized"}
+
+    def test_response_is_indented_json(self):
+        """Indented JSON renderer keeps the payload human-readable."""
+        app = _make_app({"mp": _FakeMPConfig()})
+        client = TestClient(app)
+
+        raw = client.get("/config").text
+        # Indented output has newlines and 2-space indentation.
+        assert "\n" in raw
+        assert '  "mp"' in raw
+        # And the body is still valid JSON.
+        assert json.loads(raw)["mp"]["host"] == "0.0.0.0"
+
+    def test_empty_configs_returns_empty_object(self):
+        client = TestClient(_make_app(configs={}))
+        resp = client.get("/config")
+
+        assert resp.status_code == 200
+        assert resp.json() == {}
+
+
+@pytest.mark.parametrize(
+    "configs,expected_key",
+    [
+        ({"only": _FakeMPConfig()}, "only"),
+        ({"a": _FakeMPConfig(), "b": _FakeStorageConfig()}, "b"),
+    ],
+)
+def test_arbitrary_config_keys_round_trip(configs, expected_key):
+    client = TestClient(_make_app(configs))
+    body = client.get("/config").json()
+    assert expected_key in body
+
+
+# =============================================================================
+# Adapters -- ``GET /config/adapters`` (listing configured cache adapters is a
+# configuration-inspection concern, so it lives in the config group).
+# =============================================================================
+
+
+@dataclass
+class _FakeDescriptor:
+    """Minimal adapter descriptor -- only ``type_name`` is read."""
+
+    type_name: str = "s3"
+
+
+@dataclass
+class _FakeStorageManager:
+    """Implements ``l2_adapters()`` and ``reconfigurable_l2_backends()``. An
+    empty ``adapters`` list reproduces the "no L2 adapters configured"
+    condition; ``reconfigurable`` names the type_names that report runtime
+    reconfiguration support."""
+
+    adapters: list = field(default_factory=list)
+    reconfigurable: set = field(default_factory=set)
+
+    def l2_adapters(self):
+        return [(_FakeDescriptor(type_name=n), a) for n, a in self.adapters]
+
+    def reconfigurable_l2_backends(self) -> set:
+        return set(self.reconfigurable)
+
+
+class _FakeEngine:
+    def __init__(self, sm: _FakeStorageManager):
+        self.storage_manager = sm
+
+
+def _make_adapters_app(sm) -> FastAPI:
+    """Build an app with the config router and a context wrapping a fake engine
+    (or no context, reproducing the not-initialized condition)."""
+    app = FastAPI()
+    app.include_router(config_router)
+    if sm is not None:
+        app.state.context = build_context(_FakeEngine(sm))
+    return app
+
+
+class TestConfigAdaptersEndpoint:
+    def test_empty_adapter_list_returns_empty_array(self):
+        client = TestClient(_make_adapters_app(_FakeStorageManager()))
+        resp = client.get("/config/adapters")
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {"adapters": []}
+
+    def test_lists_all_adapters_with_primary_and_reconfigurable_flags(self):
+        sm = _FakeStorageManager(
+            adapters=[("s3", object()), ("dax", object())],
+            reconfigurable={"dax"},
+        )
+        client = TestClient(_make_adapters_app(sm))
+        resp = client.get("/config/adapters")
+        assert resp.status_code == 200, resp.text
+        assert resp.json() == {
+            "adapters": [
+                {
+                    "index": 0,
+                    "type_name": "s3",
+                    "tier": "l2",
+                    "primary": True,
+                    "reconfigurable": False,
+                },
+                {
+                    "index": 1,
+                    "type_name": "dax",
+                    "tier": "l2",
+                    "primary": False,
+                    "reconfigurable": True,
+                },
+            ]
+        }
+
+    def test_503_when_not_initialized(self):
+        client = TestClient(_make_adapters_app(None))
+        assert client.get("/config/adapters").status_code == 503
diff --git a/tests/v1/multiprocess/http_apis/test_info_api.py b/tests/v1/multiprocess/http_apis/test_info_api.py
new file mode 100644
index 0000000..9ce0570
--- /dev/null
+++ b/tests/v1/multiprocess/http_apis/test_info_api.py
@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the basic-info endpoints exposed by info_api.
+
+Covers:
+- ``GET /`` static liveness payload.
+- ``GET /healthcheck`` 503 before the engine is wired, 200 after.
+- ``GET /status`` 503 before the engine is wired, engine status after.
+- The version routes (``/version``, ``/lmc_version``, ``/commit_id``) are
+  registered as part of the group.
+"""
+
+# Third Party
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+# First Party
+from lmcache.v1.multiprocess.http_apis.info_api import router as info_router
+
+
+class _FakeEngine:
+    def report_status(self) -> dict[str, str]:
+        return {"l1": "ok", "l2": "ok"}
+
+
+def _make_app(engine=None) -> FastAPI:
+    app = FastAPI()
+    app.include_router(info_router)
+    if engine is not None:
+        app.state.engine = engine
+    return app
+
+
+def test_root_returns_ok():
+    client = TestClient(_make_app())
+    resp = client.get("/")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "ok", "service": "LMCache HTTP API"}
+
+
+def test_healthcheck_503_without_engine():
+    client = TestClient(_make_app(engine=None))
+    resp = client.get("/healthcheck")
+    assert resp.status_code == 503
+    assert resp.json()["status"] == "unhealthy"
+
+
+def test_healthcheck_healthy_with_engine():
+    client = TestClient(_make_app(engine=_FakeEngine()))
+    resp = client.get("/healthcheck")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "healthy"}
+
+
+def test_status_503_without_engine():
+    client = TestClient(_make_app(engine=None))
+    resp = client.get("/status")
+    assert resp.status_code == 503
+    assert resp.json() == {"error": "engine not initialized"}
+
+
+def test_status_reports_engine_status():
+    client = TestClient(_make_app(engine=_FakeEngine()))
+    resp = client.get("/status")
+    assert resp.status_code == 200
+    assert resp.json() == {"l1": "ok", "l2": "ok"}
+
+
+def test_version_routes_registered():
+    """The version routes are folded into the basic-info group."""
+    app = _make_app()
+    paths = set(app.openapi()["paths"])
+    assert {"/version", "/lmc_version", "/commit_id"}.issubset(paths)
diff --git a/tests/v1/multiprocess/http_apis/test_reconfigure_api.py b/tests/v1/multiprocess/http_apis/test_reconfigure_api.py
new file mode 100644
index 0000000..de7b099
--- /dev/null
+++ b/tests/v1/multiprocess/http_apis/test_reconfigure_api.py
@@ -0,0 +1,336 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for MP runtime reconfiguration HTTP endpoints."""
+
+# Standard
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Third Party
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.distributed.l2_adapters.reconfiguration import L2ReconfigureError
+from lmcache.v1.multiprocess.http_apis.reconfigure_api import router
+
+_DAX_OPS = ["status", "add", "remove", "resize"]
+
+
+def _adapter_status(
+    backend: str,
+    adapter_index: int,
+    status: Optional[dict[str, object]] = None,
+    supported_operations: Optional[list[str]] = None,
+) -> dict[str, object]:
+    return {
+        "backend": backend,
+        "supported_operations": supported_operations or [],
+        "status": status or {},
+        "adapter_index": adapter_index,
+    }
+
+
+@dataclass
+class _FakeStorageManager:
+    calls: list[tuple[str, tuple[object, ...]]] = field(default_factory=list)
+    raise_error: Optional[L2ReconfigureError] = None
+    status: Optional[dict] = None
+
+    def get_l2_adapter_reconfigure_status(self) -> dict:
+        self.calls.append(("status", ()))
+        if self.status is not None:
+            return self.status
+        return {
+            "enabled": True,
+            "num_adapters": 1,
+            "adapters": [
+                _adapter_status(
+                    "dax",
+                    0,
+                    {"hotplug_enabled": True, "devices": []},
+                    _DAX_OPS,
+                )
+            ],
+        }
+
+    def reconfigure_l2_adapter(
+        self,
+        adapter_index: int,
+        operation: str,
+        payload: dict[str, object],
+    ) -> dict:
+        self.calls.append(("reconfigure", (adapter_index, operation, payload)))
+        if self.raise_error is not None:
+            raise self.raise_error
+        return {"status": "ok", "operation": operation}
+
+
+@dataclass
+class _FakeEngine:
+    storage_manager: _FakeStorageManager
+
+
+def _client(sm: _FakeStorageManager) -> TestClient:
+    app = FastAPI()
+    app.include_router(router)
+    app.state.engine = _FakeEngine(storage_manager=sm)
+    return TestClient(app)
+
+
+def test_calls_storage_manager_without_timeout_and_without_accepted_response():
+    sm = _FakeStorageManager()
+    client = _client(sm)
+
+    status_resp = client.get("/reconfigure/dax/status")
+    add_resp = client.post(
+        "/reconfigure/dax/add",
+        json={
+            "adapter_index": 0,
+            "device_path": "/dev/daxX.X",
+            "size": "2GiB",
+        },
+    )
+    remove_resp = client.post(
+        "/reconfigure/dax/remove",
+        json={
+            "adapter_index": 0,
+            "device_path": "/dev/daxX.X",
+            "mode": "drain",
+            "force": True,
+        },
+    )
+    resize_resp = client.post(
+        "/reconfigure/dax/resize",
+        json={
+            "adapter_index": 0,
+            "device_path": "/dev/daxX.X",
+            "size": "1536MiB",
+            "mode": "migrate",
+            "force": False,
+        },
+    )
+
+    assert status_resp.status_code == 200
+    assert add_resp.status_code == 200
+    assert remove_resp.status_code == 200
+    assert resize_resp.status_code == 200
+    assert status_resp.json()["backend"] == "dax"
+    assert status_resp.json()["num_adapters"] == 1
+    assert sm.calls == [
+        ("status", ()),
+        ("status", ()),
+        (
+            "reconfigure",
+            (0, "add", {"device_path": "/dev/daxX.X", "size_bytes": 2 * 1024**3}),
+        ),
+        ("status", ()),
+        (
+            "reconfigure",
+            (
+                0,
+                "remove",
+                {"device_path": "/dev/daxX.X", "mode": "drain", "force": True},
+            ),
+        ),
+        ("status", ()),
+        (
+            "reconfigure",
+            (
+                0,
+                "resize",
+                {
+                    "device_path": "/dev/daxX.X",
+                    "size_bytes": int(1.5 * 1024**3),
+                    "mode": "migrate",
+                    "force": False,
+                },
+            ),
+        ),
+    ]
+
+
+def test_status_filters_non_dax_reconfigurable_adapters():
+    sm = _FakeStorageManager(
+        status={
+            "enabled": True,
+            "num_adapters": 2,
+            "adapters": [
+                _adapter_status("fake", 0, {"ready": True}, ["flip"]),
+                _adapter_status(
+                    "dax",
+                    1,
+                    {"hotplug_enabled": True, "devices": []},
+                    _DAX_OPS,
+                ),
+            ],
+        }
+    )
+
+    resp = _client(sm).get("/reconfigure/dax/status")
+
+    assert resp.status_code == 200
+    assert resp.json() == {
+        "enabled": True,
+        "backend": "dax",
+        "num_adapters": 1,
+        "adapters": [
+            {
+                "backend": "dax",
+                "supported_operations": _DAX_OPS,
+                "status": {"hotplug_enabled": True, "devices": []},
+                "adapter_index": 0,
+            }
+        ],
+    }
+
+
+def test_add_resolves_public_dax_index_to_generic_reconfigure_index():
+    sm = _FakeStorageManager(
+        status={
+            "enabled": True,
+            "num_adapters": 2,
+            "adapters": [
+                _adapter_status("fake", 0, {"ready": True}, ["flip"]),
+                _adapter_status(
+                    "dax",
+                    1,
+                    {"hotplug_enabled": True, "devices": []},
+                    _DAX_OPS,
+                ),
+            ],
+        }
+    )
+
+    resp = _client(sm).post(
+        "/reconfigure/dax/add",
+        json={
+            "adapter_index": 0,
+            "device_path": "/dev/daxX.X",
+            "size": 1024,
+        },
+    )
+
+    assert resp.status_code == 200
+    assert sm.calls == [
+        ("status", ()),
+        ("reconfigure", (1, "add", {"device_path": "/dev/daxX.X", "size_bytes": 1024})),
+    ]
+
+
+@pytest.mark.parametrize(
+    ("payload", "status_code"),
+    [
+        ({"device_path": "/dev/daxX.X", "size_bytes": 1024}, 422),
+        ({"device_path": "/dev/daxX.X", "size": "many"}, 400),
+    ],
+)
+def test_add_rejects_invalid_size_payloads(
+    payload: dict[str, object],
+    status_code: int,
+):
+    resp = _client(_FakeStorageManager()).post("/reconfigure/dax/add", json=payload)
+    assert resp.status_code == status_code
+
+
+def test_add_rejects_pathological_size_string_without_echoing_input():
+    sm = _FakeStorageManager()
+    bad_size = "9" + " " * 5000 + "x"
+
+    resp = _client(sm).post(
+        "/reconfigure/dax/add",
+        json={"device_path": "/dev/daxX.X", "size": bad_size},
+    )
+
+    assert resp.status_code == 400
+    assert bad_size not in resp.text
+    assert sm.calls == []
+
+
+@pytest.mark.parametrize(
+    ("path", "payload"),
+    [
+        (
+            "/reconfigure/dax/remove",
+            {"device_path": "/dev/daxX.X", "timeout_s": 1},
+        ),
+        (
+            "/reconfigure/dax/resize",
+            {"device_path": "/dev/daxX.X", "size": 1024, "timeout_s": 1},
+        ),
+        (
+            "/reconfigure/dax/resize",
+            {"device_path": "/dev/daxX.X", "size": 1024, "mode": "drain"},
+        ),
+    ],
+)
+def test_rejects_removed_fields_and_invalid_resize_mode(
+    path: str,
+    payload: dict[str, object],
+):
+    resp = _client(_FakeStorageManager()).post(path, json=payload)
+    assert resp.status_code == 422
+
+
+def test_hotplug_error_status_code_is_preserved():
+    sm = _FakeStorageManager(
+        raise_error=L2ReconfigureError(
+            507,
+            "no active destination DAX capacity",
+        )
+    )
+    resp = _client(sm).post(
+        "/reconfigure/dax/add",
+        json={
+            "device_path": "/dev/daxX.X",
+            "size": 1024,
+        },
+    )
+    assert resp.status_code == 507
+    assert resp.json() == {"error": "no active destination DAX capacity"}
+
+
+def test_generic_backend_routes_payload_to_matching_reconfigurable_adapter():
+    sm = _FakeStorageManager(
+        status={
+            "enabled": True,
+            "num_adapters": 2,
+            "adapters": [
+                _adapter_status("fake", 0, {"ready": True}, ["flip"]),
+                _adapter_status("dax", 1, {"hotplug_enabled": True}, _DAX_OPS),
+            ],
+        }
+    )
+
+    resp = _client(sm).post(
+        "/reconfigure/fake/flip",
+        json={"adapter_index": 0, "enabled": True},
+    )
+
+    assert resp.status_code == 200
+    assert sm.calls == [
+        ("status", ()),
+        ("reconfigure", (0, "flip", {"enabled": True})),
+    ]
+
+
+def test_reconfigure_post_rejects_missing_backend_adapter():
+    sm = _FakeStorageManager(
+        status={
+            "enabled": True,
+            "num_adapters": 1,
+            "adapters": [
+                _adapter_status("dax", 0, {"hotplug_enabled": True}, _DAX_OPS)
+            ],
+        }
+    )
+
+    resp = _client(sm).post("/reconfigure/fake/flip", json={"enabled": True})
+
+    assert resp.status_code == 404
+    assert resp.json() == {"error": "fake adapter not found"}
+
+
+def test_old_dax_routes_are_not_registered():
+    resp = _client(_FakeStorageManager()).get("/dax/status")
+    assert resp.status_code == 404
diff --git a/tests/v1/multiprocess/test_affinity_pool.py b/tests/v1/multiprocess/test_affinity_pool.py
new file mode 100644
index 0000000..74a30e6
--- /dev/null
+++ b/tests/v1/multiprocess/test_affinity_pool.py
@@ -0,0 +1,248 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for AffinityThreadPool."""
+
+# Standard
+import threading
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.affinity_pool import AffinityThreadPool
+
+
+def test_submit_returns_correct_result():
+    pool = AffinityThreadPool(max_workers=2)
+    future = pool.submit(lambda x: x * 2, 21, affinity_key=0)
+    assert future.result(timeout=5) == 42
+    pool.shutdown()
+
+
+def test_affinity_routing():
+    """Tasks with the same affinity_key always run on the same thread."""
+    pool = AffinityThreadPool(max_workers=4, thread_name_prefix="test-affinity")
+    results: dict[int, str] = {}
+
+    def record_thread(key: int) -> str:
+        name = threading.current_thread().name
+        return name
+
+    futures = []
+    for key in [0, 1, 2, 3, 0, 1, 2, 3]:
+        f = pool.submit(record_thread, key, affinity_key=key)
+        futures.append((key, f))
+
+    for key, f in futures:
+        name = f.result(timeout=5)
+        if key in results:
+            assert results[key] == name, (
+                f"Key {key} ran on {name} but previously on {results[key]}"
+            )
+        else:
+            results[key] = name
+
+    pool.shutdown()
+
+
+def test_distinct_keys_get_distinct_workers():
+    """Up to ``max_workers`` distinct keys each land on their own worker.
+
+    Dynamic assignment binds each new key to the next free slot, so any set of
+    keys (dense or not) within the worker count gets a 1:1 spread across
+    threads -- no key collides onto a shared slot while another sits idle.
+    """
+    num_workers = 8
+    pool = AffinityThreadPool(max_workers=num_workers, thread_name_prefix="dense")
+
+    def record_thread() -> str:
+        return threading.current_thread().name
+
+    futures = [
+        (rank, pool.submit(record_thread, affinity_key=rank))
+        for rank in range(num_workers)
+    ]
+    threads = {rank: f.result(timeout=5) for rank, f in futures}
+
+    # Every rank ran on a distinct worker thread -> no idle workers, no sharing.
+    assert len(set(threads.values())) == num_workers
+    # Keys are assigned slots in arrival order, so rank N lands on slot N here.
+    for rank in range(num_workers):
+        assert threads[rank] == f"dense-{rank}"
+
+    pool.shutdown()
+
+
+def test_modulo_colliding_keys_get_distinct_workers():
+    """Keys that would collide under ``key % num_workers`` still get their own
+    worker under dynamic assignment.
+
+    With 4 workers the keys ``0, 4, 8, 12`` all map to slot 0 under a modulo
+    scheme -- the bug this pool avoids. Dynamic assignment instead binds them to
+    slots 0, 1, 2, 3, so each gets a dedicated thread.
+    """
+    pool = AffinityThreadPool(max_workers=4, thread_name_prefix="collide")
+
+    def record_thread() -> str:
+        return threading.current_thread().name
+
+    keys = [0, 4, 8, 12]  # all == 0 (mod 4)
+    threads = {
+        k: pool.submit(record_thread, affinity_key=k).result(timeout=5) for k in keys
+    }
+
+    assert len(set(threads.values())) == 4, threads
+    pool.shutdown()
+
+
+def test_overflow_warning_on_shared_slot():
+    """More distinct keys than workers wraps onto shared slots and warns once.
+
+    LMCache loggers set ``propagate = False``, so assert on the module logger
+    directly rather than via the ``caplog`` (root-logger) fixture.
+    """
+    # Standard
+    from unittest.mock import patch
+
+    # First Party
+    from lmcache.v1.multiprocess import affinity_pool as affinity_pool_mod
+
+    pool = AffinityThreadPool(max_workers=2, thread_name_prefix="overflow")
+    with patch.object(affinity_pool_mod.logger, "warning") as mock_warning:
+        # Keys 0 and 1 fill the two slots; key 2 is the first overflow (wraps
+        # onto slot 0), and key 3 wraps too but must not warn a second time.
+        for key in [0, 1, 2, 3]:
+            pool.submit(lambda: None, affinity_key=key).result(timeout=5)
+
+    assert mock_warning.call_count == 1
+    assert "wrapped onto worker slot" in mock_warning.call_args.args[0]
+    pool.shutdown()
+
+
+def test_overflow_keys_share_a_slot():
+    """When keys outnumber workers, overflow keys reuse earlier slots."""
+    pool = AffinityThreadPool(max_workers=2, thread_name_prefix="share")
+
+    def record_thread() -> str:
+        return threading.current_thread().name
+
+    threads = {
+        key: pool.submit(record_thread, affinity_key=key).result(timeout=5)
+        for key in [0, 1, 2, 3]
+    }
+
+    # Only two threads exist, so the four keys collapse onto two threads, and
+    # the wrap is deterministic (key 2 shares key 0's slot, key 3 shares key 1's).
+    assert len(set(threads.values())) == 2
+    assert threads[0] == threads[2]
+    assert threads[1] == threads[3]
+    pool.shutdown()
+
+
+def test_no_overflow_warning_within_worker_count():
+    """Distinct keys within the worker count never warn, even when re-submitted."""
+    # Standard
+    from unittest.mock import patch
+
+    # First Party
+    from lmcache.v1.multiprocess import affinity_pool as affinity_pool_mod
+
+    pool = AffinityThreadPool(max_workers=4, thread_name_prefix="nooverflow")
+    with patch.object(affinity_pool_mod.logger, "warning") as mock_warning:
+        for rank in range(4):
+            pool.submit(lambda: None, affinity_key=rank).result(timeout=5)
+        # Re-submitting the same keys reuses their slots -> still no overflow.
+        for rank in range(4):
+            pool.submit(lambda: None, affinity_key=rank).result(timeout=5)
+
+    assert mock_warning.call_count == 0
+    pool.shutdown()
+
+
+def test_same_key_serialization():
+    """Tasks with the same affinity key execute sequentially."""
+    pool = AffinityThreadPool(max_workers=2)
+    order: list[int] = []
+    lock = threading.Lock()
+
+    def append_value(val: int) -> None:
+        with lock:
+            order.append(val)
+        # Small sleep to ensure ordering matters
+        time.sleep(0.01)
+
+    futures = [pool.submit(append_value, i, affinity_key=42) for i in range(5)]
+    for f in futures:
+        f.result(timeout=5)
+
+    assert order == [0, 1, 2, 3, 4]
+    pool.shutdown()
+
+
+def test_different_keys_parallel():
+    """Tasks with different affinity keys can run concurrently."""
+    pool = AffinityThreadPool(max_workers=2)
+    barrier = threading.Barrier(2, timeout=5)
+
+    def wait_at_barrier() -> bool:
+        barrier.wait()
+        return True
+
+    f1 = pool.submit(wait_at_barrier, affinity_key=0)
+    f2 = pool.submit(wait_at_barrier, affinity_key=1)
+
+    assert f1.result(timeout=5) is True
+    assert f2.result(timeout=5) is True
+    pool.shutdown()
+
+
+def test_future_exception():
+    pool = AffinityThreadPool(max_workers=1)
+
+    def fail():
+        raise ValueError("test error")
+
+    future = pool.submit(fail, affinity_key=0)
+    with pytest.raises(ValueError, match="test error"):
+        future.result(timeout=5)
+    pool.shutdown()
+
+
+def test_future_done_callback():
+    pool = AffinityThreadPool(max_workers=1)
+    callback_results: list[int] = []
+    event = threading.Event()
+
+    def task():
+        return 99
+
+    future = pool.submit(task, affinity_key=0)
+
+    def on_done(fut):
+        callback_results.append(fut.result())
+        event.set()
+
+    future.add_done_callback(on_done)
+    event.wait(timeout=5)
+    assert callback_results == [99]
+    pool.shutdown()
+
+
+def test_shutdown_wait():
+    pool = AffinityThreadPool(max_workers=1)
+    completed = threading.Event()
+
+    def slow_task():
+        time.sleep(0.1)
+        completed.set()
+
+    pool.submit(slow_task, affinity_key=0)
+    pool.shutdown(wait=True)
+    assert completed.is_set()
+
+
+def test_shutdown_no_wait():
+    pool = AffinityThreadPool(max_workers=1)
+    pool.submit(lambda: time.sleep(0.5), affinity_key=0)
+    # Should return immediately without waiting
+    pool.shutdown(wait=False)
diff --git a/tests/v1/multiprocess/test_async_engine_driven_transfer_context.py b/tests/v1/multiprocess/test_async_engine_driven_transfer_context.py
new file mode 100644
index 0000000..8058705
--- /dev/null
+++ b/tests/v1/multiprocess/test_async_engine_driven_transfer_context.py
@@ -0,0 +1,460 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import nullcontext
+from dataclasses import dataclass
+from types import SimpleNamespace
+from typing import Callable
+from unittest.mock import MagicMock
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.transfer_context import (
+    async_engine_driven,
+    worker_transfer,
+)
+from lmcache.v1.multiprocess.transfer_context.async_engine_driven import (
+    AsyncEngineDrivenTransferContext,
+)
+from lmcache.v1.multiprocess.transfer_context.worker_transfer import (
+    EngineDrivenTransferContext,
+)
+
+
+@dataclass
+class _FakeStoreContext:
+    """Minimal engine-driven context for async store tests."""
+
+    commit_impl: Callable[[list[torch.Tensor]], bool]
+    prepare_result: tuple[list[torch.Tensor], list[int]] | None = None
+    prepare_impl: Callable[[], None] | None = None
+
+    def __post_init__(self) -> None:
+        self.layout_desc = SimpleNamespace(
+            shapes=[torch.Size([2, 1, 1, 1])], dtypes=[torch.float32]
+        )
+
+    def prepare_store(
+        self, _key: object, _instance_id: int
+    ) -> tuple[list[torch.Tensor], list[int]] | None:
+        if self.prepare_impl is not None:
+            self.prepare_impl()
+        return self.prepare_result
+
+    def commit_store(
+        self, _key: object, _instance_id: int, chunks: list[torch.Tensor]
+    ) -> bool:
+        return bool(self.commit_impl(chunks))
+
+    def close(self) -> None:
+        return None
+
+
+class _FakeEvent:
+    def __init__(self, gate: threading.Event):
+        self._gate = gate
+
+    def record(self, stream: object | None = None) -> None:
+        return None
+
+    def wait(self, stream: object | None = None) -> None:
+        return None
+
+    def synchronize(self) -> None:
+        self._gate.wait(timeout=2)
+
+    def query(self) -> bool:
+        return self._gate.is_set()
+
+    def ipc_handle(self) -> object:
+        return object()
+
+
+class _FakeTorchDev:
+    def __init__(self, gather_gate: threading.Event):
+        self._stream = object()
+        self._gather_gate = gather_gate
+
+    def Stream(self) -> object:
+        return object()
+
+    def stream(self, stream: object) -> object:
+        return nullcontext(stream)
+
+    def current_stream(self) -> object:
+        return self._stream
+
+    def Event(self, interprocess: bool = False) -> _FakeEvent:
+        return _FakeEvent(self._gather_gate)
+
+    def synchronize(self) -> None:
+        pass
+
+
+def _install_fake_gather(monkeypatch: pytest.MonkeyPatch) -> None:
+    def _gather(
+        _kv_caches: dict[str, torch.Tensor],
+        _block_ids: list[int],
+        _blocks_in_chunk: int,
+        **kwargs: object,
+    ) -> list[torch.Tensor]:
+        out = kwargs.get("out")
+        if out is None:
+            return [torch.ones(1)]
+        assert isinstance(out, list)
+        for tensor in out:
+            tensor.fill_(1.0)
+        return out
+
+    # Patch gather in both modules so either path is exercised.
+    monkeypatch.setattr(async_engine_driven, "gather_paged_kv_to_cpu", _gather)
+    monkeypatch.setattr(worker_transfer, "gather_paged_kv_to_cpu", _gather)
+
+
+def _new_context(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    gather_gate: threading.Event,
+    commit_impl: Callable[[list[torch.Tensor]], bool],
+    max_inflight: int = 8,
+) -> AsyncEngineDrivenTransferContext:
+    monkeypatch.setattr(async_engine_driven, "torch_dev", _FakeTorchDev(gather_gate))
+    _install_fake_gather(monkeypatch)
+    ctx = AsyncEngineDrivenTransferContext(commit_workers=max_inflight)
+    ctx._engine_driven_context = (
+        _FakeStoreContext(commit_impl=commit_impl)  # type: ignore[assignment]
+    )
+    return ctx
+
+
+def test_submit_store_returns_pending_future_until_gather_and_commit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gather_gate = threading.Event()
+    ctx = _new_context(
+        monkeypatch, gather_gate=gather_gate, commit_impl=lambda _c: True
+    )
+    future = ctx.submit_store(
+        "r1", object(), 1, {"k": torch.zeros(1)}, [[0]], _FakeEvent(gather_gate), 1
+    )
+    assert not future.query()
+    gather_gate.set()
+    assert future.result(timeout=1) is True
+    ctx.close()
+
+
+def test_submit_store_commit_waits_for_gather_done(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gather_gate = threading.Event()
+    commit_called = threading.Event()
+
+    def _commit(_chunks: list[torch.Tensor]) -> bool:
+        commit_called.set()
+        return True
+
+    ctx = _new_context(monkeypatch, gather_gate=gather_gate, commit_impl=_commit)
+    future = ctx.submit_store(
+        "r1", object(), 1, {"k": torch.zeros(1)}, [[0]], _FakeEvent(gather_gate), 1
+    )
+    assert not commit_called.wait(timeout=0.05)
+    gather_gate.set()
+    assert future.result(timeout=1) is True
+    assert commit_called.is_set()
+    ctx.close()
+
+
+def test_close_drains_inflight_async_store(monkeypatch: pytest.MonkeyPatch) -> None:
+    gather_gate = threading.Event()
+    commit_gate = threading.Event()
+    gather_gate.set()
+
+    def _commit(_chunks: list[torch.Tensor]) -> bool:
+        commit_gate.wait(timeout=2)
+        return True
+
+    ctx = _new_context(monkeypatch, gather_gate=gather_gate, commit_impl=_commit)
+    future = ctx.submit_store(
+        "r1", object(), 1, {"k": torch.zeros(1)}, [[0]], _FakeEvent(gather_gate), 1
+    )
+    closed = threading.Event()
+
+    def _close() -> None:
+        ctx.close()
+        closed.set()
+
+    t = threading.Thread(target=_close, daemon=True)
+    t.start()
+    assert not closed.wait(timeout=0.05)
+    commit_gate.set()
+    t.join(timeout=1)
+    assert closed.is_set()
+    assert future.result(timeout=1) is True
+
+
+def test_commit_failure_sets_false_and_logs(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gather_gate = threading.Event()
+
+    def _commit(_chunks: list[torch.Tensor]) -> bool:
+        raise RuntimeError("commit failed")
+
+    log_exception = MagicMock()
+    monkeypatch.setattr(async_engine_driven.logger, "exception", log_exception)
+    ctx = _new_context(monkeypatch, gather_gate=gather_gate, commit_impl=_commit)
+    future = ctx.submit_store(
+        "r1", object(), 1, {"k": torch.zeros(1)}, [[0]], _FakeEvent(gather_gate), 1
+    )
+    gather_gate.set()
+    assert future.result(timeout=1) is False
+    log_exception.assert_called_once()
+    ctx.close()
+
+
+def test_flush_inflight_stores_no_inflight_is_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    gather_gate = threading.Event()
+    gather_gate.set()
+    ctx = _new_context(
+        monkeypatch, gather_gate=gather_gate, commit_impl=lambda _c: True
+    )
+    # No in-flight events: flush is a cheap no-op and must not raise.
+    ctx.flush_inflight_stores()
+    ctx.close()
+
+
+def test_sync_engine_driven_context_returns_resolved_future(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    class _RecordingTorchDev:
+        def __init__(self) -> None:
+            self.synchronize_calls = 0
+
+        def synchronize(self) -> None:
+            self.synchronize_calls += 1
+
+    fake = _RecordingTorchDev()
+    monkeypatch.setattr(worker_transfer, "torch_dev", fake)
+    _install_fake_gather(monkeypatch)
+    ctx = EngineDrivenTransferContext()
+    ctx._engine_driven_context = (
+        _FakeStoreContext(commit_impl=lambda _c: True)  # type: ignore[assignment]
+    )
+
+    future = ctx.submit_store(
+        "r1",
+        object(),
+        1,
+        {"k": torch.zeros(1)},
+        [[0]],
+        _FakeEvent(threading.Event()),
+        1,
+    )
+
+    # Sync path resolves inline.
+    assert future.query()
+    assert future.result(timeout=1) is True
+    assert fake.synchronize_calls >= 1
+    # flush_inflight_stores is the inherited base no-op; must not raise.
+    ctx.flush_inflight_stores()
+    ctx.close()
+
+
+def test_sync_engine_driven_context_has_no_async_resources() -> None:
+    ctx = EngineDrivenTransferContext()
+    assert not hasattr(ctx, "_copy_stream")
+    assert not hasattr(ctx, "_commit_executor")
+    assert not hasattr(ctx, "_inflight_semaphore")
+    # close() on an unregistered sync context must not raise.
+    ctx.close()
+
+
+def test_build_engine_driven_context_dispatches_on_capability(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(worker_transfer, "_supports_async_primitives", lambda: True)
+    # Avoid touching real stream/event primitives when instantiating the async
+    # context returned by the capable branch.
+    monkeypatch.setattr(
+        async_engine_driven, "torch_dev", _FakeTorchDev(threading.Event())
+    )
+    capable = worker_transfer._build_engine_driven_context()
+    assert isinstance(capable, AsyncEngineDrivenTransferContext)
+    capable.close()
+
+    monkeypatch.setattr(worker_transfer, "_supports_async_primitives", lambda: False)
+    fallback = worker_transfer._build_engine_driven_context()
+    assert isinstance(fallback, EngineDrivenTransferContext)
+    assert not isinstance(fallback, AsyncEngineDrivenTransferContext)
+    fallback.close()
+
+
+def test_supports_async_primitives_false_without_stream(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # A torch_dev without Stream/Event is not async-capable.
+    monkeypatch.setattr(worker_transfer, "torch_dev", object())
+    assert worker_transfer._supports_async_primitives() is False
+
+
+def test_flush_inflight_stores_waits_for_pending_gather(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """flush_inflight_stores must not return before a submitted-but-not-yet-
+    launched gather has recorded its CUDA event (preemption race condition)."""
+    gather_gate = threading.Event()
+    flush_returned = threading.Event()
+    gather_started = threading.Event()
+
+    # Gate that blocks gather from completing until we are ready.
+    class _BlockingFakeTorchDev(_FakeTorchDev):
+        def stream(self, stream: object) -> object:
+            gather_started.set()
+            # Block here until the test releases the gate — simulating the
+            # background thread not yet recording the CUDA event.
+            gather_gate.wait(timeout=2)
+            return super().stream(stream)
+
+    # Pass gather_gate so _FakeEvent.synchronize() also uses the same gate.
+    monkeypatch.setattr(
+        async_engine_driven, "torch_dev", _BlockingFakeTorchDev(gather_gate)
+    )
+    _install_fake_gather(monkeypatch)
+
+    ctx = AsyncEngineDrivenTransferContext(commit_workers=1)
+    ctx._engine_driven_context = (
+        _FakeStoreContext(commit_impl=lambda _c: True)  # type: ignore[assignment]
+    )
+
+    ctx.submit_store(
+        "r1", object(), 1, {"k": torch.zeros(1)}, [[0]], _FakeEvent(gather_gate), 1
+    )
+
+    # Wait until the background thread has started (entered stream()), proving
+    # it has not yet recorded its CUDA event.
+    assert gather_started.wait(timeout=1), "background thread never started"
+
+    def _flush() -> None:
+        ctx.flush_inflight_stores()
+        flush_returned.set()
+
+    t = threading.Thread(target=_flush, daemon=True)
+    t.start()
+
+    # flush_inflight_stores must NOT return while the gather is still pending.
+    assert not flush_returned.wait(timeout=0.05), (
+        "flush_inflight_stores returned before gather launched — race condition!"
+    )
+
+    # Now let the background gather proceed; flush should complete shortly.
+    gather_gate.set()
+    t.join(timeout=2)
+    assert flush_returned.is_set(), "flush_inflight_stores did not complete"
+    ctx.close()
+
+
+def test_commit_store_serialized_by_commit_lock(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Concurrent commit_store calls must be serialized by _commit_lock to
+    protect ZMQ socket access."""
+    gather_gate = threading.Event()
+    gather_gate.set()
+    concurrent_commits = threading.Event()
+    active_commits = [0]
+
+    def _commit(_chunks: list[torch.Tensor]) -> bool:
+        active_commits[0] += 1
+        if active_commits[0] > 1:
+            concurrent_commits.set()
+        # Briefly yield so a second commit could slip in if unlocked.
+        time.sleep(0.02)
+        active_commits[0] -= 1
+        return True
+
+    ctx = _new_context(
+        monkeypatch, gather_gate=gather_gate, commit_impl=_commit, max_inflight=4
+    )
+
+    futures = [
+        ctx.submit_store(
+            f"r{i}",
+            object(),
+            1,
+            {"k": torch.zeros(1)},
+            [[0]],
+            _FakeEvent(gather_gate),
+            1,
+        )
+        for i in range(4)
+    ]
+
+    for f in futures:
+        assert f.result(timeout=2) is True
+
+    # With _commit_lock, no two commits should have been active simultaneously.
+    assert not concurrent_commits.is_set(), (
+        "commit_store called concurrently — _commit_lock not working"
+    )
+    ctx.close()
+
+
+def test_prepare_store_runs_on_background_thread_not_forward_thread(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """submit_store must return immediately even when prepare_store is slow.
+
+    The forward thread must not be blocked by the prepare_store RPC round-trip.
+    Both prepare_store and buffer allocation now run entirely inside the
+    background ``_prepare_gather_and_commit`` closure.
+    """
+    gather_gate = threading.Event()
+    gather_gate.set()
+    prepare_started = threading.Event()
+    prepare_gate = threading.Event()
+
+    def _slow_prepare() -> None:
+        prepare_started.set()
+        # Block until the test explicitly releases the gate.
+        prepare_gate.wait(timeout=2)
+
+    monkeypatch.setattr(async_engine_driven, "torch_dev", _FakeTorchDev(gather_gate))
+    _install_fake_gather(monkeypatch)
+
+    ctx = AsyncEngineDrivenTransferContext(commit_workers=1)
+    ctx._engine_driven_context = _FakeStoreContext(  # type: ignore[assignment]
+        commit_impl=lambda _c: True,
+        prepare_impl=_slow_prepare,
+    )
+
+    submit_returned = threading.Event()
+
+    def _submit() -> None:
+        ctx.submit_store(
+            "r1", object(), 1, {"k": torch.zeros(1)}, [[0]], _FakeEvent(gather_gate), 1
+        )
+        submit_returned.set()
+
+    t = threading.Thread(target=_submit, daemon=True)
+    t.start()
+
+    # submit_store must return before prepare_store finishes.
+    assert submit_returned.wait(timeout=1), (
+        "submit_store blocked the forward thread — prepare_store is not async"
+    )
+
+    # Confirm prepare_store was actually reached by the background thread.
+    assert prepare_started.wait(timeout=1), (
+        "background thread never reached prepare_store"
+    )
+
+    # Now release prepare_store and let the background work complete.
+    prepare_gate.set()
+    t.join(timeout=1)
+    ctx.close()
diff --git a/tests/v1/multiprocess/test_batched_iteration_with_skip.py b/tests/v1/multiprocess/test_batched_iteration_with_skip.py
new file mode 100644
index 0000000..cd81d3b
--- /dev/null
+++ b/tests/v1/multiprocess/test_batched_iteration_with_skip.py
@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for ``batched_iteration_with_skip``."""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.modules.lmcache_driven_transfer import (
+    batched_iteration_with_skip,
+)
+
+
+def test_basic_batching_with_skip():
+    """Skipped items are dropped and reported indices stay in original space."""
+    data = list(range(10))
+    result = list(batched_iteration_with_skip(data, batch_size=3, skip_count=2))
+
+    assert result == [
+        (2, (2, 3, 4)),
+        (5, (5, 6, 7)),
+        (8, (8, 9)),
+    ]
+
+
+def test_skip_count_zero_matches_plain_batching():
+    """With skip_count=0 every item is yielded, indexed from 0."""
+    data = list(range(7))
+    result = list(batched_iteration_with_skip(data, batch_size=2, skip_count=0))
+
+    assert result == [
+        (0, (0, 1)),
+        (2, (2, 3)),
+        (4, (4, 5)),
+        (6, (6,)),
+    ]
+    # The concatenation of all batches equals the unskipped tail of the list.
+    flattened = [item for _, batch in result for item in batch]
+    assert flattened == data
+
+
+def test_batch_start_indices_are_original_indices():
+    """Reported start index is the original list index, accounting for skip."""
+    data = list(range(20))
+    result = list(batched_iteration_with_skip(data, batch_size=5, skip_count=10))
+
+    start_indices = [start for start, _ in result]
+    assert start_indices == [10, 15]
+    # The docstring example: skip_count=10, batch_size=5 -> first start idx 10.
+    assert result[0] == (10, (10, 11, 12, 13, 14))
+
+
+def test_partial_final_batch():
+    """The final short batch still reports the correct start index."""
+    data = list(range(8))
+    result = list(batched_iteration_with_skip(data, batch_size=3, skip_count=1))
+
+    assert result == [
+        (1, (1, 2, 3)),
+        (4, (4, 5, 6)),
+        (7, (7,)),
+    ]
+
+
+def test_skip_equal_to_length_yields_nothing():
+    """Skipping the entire list yields no batches."""
+    data = list(range(5))
+    result = list(batched_iteration_with_skip(data, batch_size=2, skip_count=5))
+    assert result == []
+
+
+def test_skip_larger_than_length_yields_nothing():
+    """Skipping past the end of the list yields no batches and does not raise."""
+    data = list(range(5))
+    result = list(batched_iteration_with_skip(data, batch_size=2, skip_count=100))
+    assert result == []
+
+
+def test_empty_list():
+    """An empty input yields no batches regardless of skip_count."""
+    assert list(batched_iteration_with_skip([], batch_size=4, skip_count=0)) == []
+    assert list(batched_iteration_with_skip([], batch_size=4, skip_count=3)) == []
+
+
+def test_batch_size_larger_than_remaining():
+    """A batch_size exceeding the remaining items yields one full-remainder batch."""
+    data = list(range(6))
+    result = list(batched_iteration_with_skip(data, batch_size=100, skip_count=2))
+    assert result == [(2, (2, 3, 4, 5))]
+
+
+@pytest.mark.parametrize("batch_size", [0, -1, -10])
+def test_invalid_batch_size_raises(batch_size):
+    """A batch_size below 1 raises ValueError."""
+    with pytest.raises(ValueError, match="batch size must be at least one"):
+        list(batched_iteration_with_skip([1, 2, 3], batch_size, skip_count=0))
+
+
+@pytest.mark.parametrize("skip_count", [-1, -5])
+def test_negative_skip_count_raises(skip_count):
+    """A negative skip_count raises ValueError."""
+    with pytest.raises(ValueError, match="skip_count must be non-negative"):
+        list(
+            batched_iteration_with_skip([1, 2, 3], batch_size=2, skip_count=skip_count)
+        )
+
+
+def test_returns_tuples_not_lists():
+    """Each yielded batch is a tuple, mirroring batched_iteration."""
+    _, batch = next(
+        batched_iteration_with_skip([1, 2, 3, 4], batch_size=2, skip_count=0)
+    )
+    assert isinstance(batch, tuple)
diff --git a/tests/v1/multiprocess/test_blend_v3_load_store_opts.py b/tests/v1/multiprocess/test_blend_v3_load_store_opts.py
new file mode 100644
index 0000000..5d1a685
--- /dev/null
+++ b/tests/v1/multiprocess/test_blend_v3_load_store_opts.py
@@ -0,0 +1,568 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for V3 load/store optimizations: L1 (batched rope), L2
+(obj_keys cache), S1 (async fingerprint).
+
+These tests exercise the wiring/state changes without touching CUDA or
+the storage controller. The CUDA kernel inside ``_apply_cb_rope_batched``
+is mocked; the matcher inside the async fingerprint worker is mocked.
+"""
+
+# Standard
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+import threading
+import time
+
+# Third Party
+import pytest
+
+# ---------------------------------------------------------------------------
+# S1: async fingerprint registration
+# ---------------------------------------------------------------------------
+
+
+def _make_engine_with_mocked_matcher():
+    """Construct a real BlendV3Module with the matcher mocked so we can
+    observe `on_new_token_hashes` calls without setting up storage."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    eng_mock = MagicMock(spec=v3_mod.BlendV3Module)
+    eng_mock._fingerprint_stop = threading.Event()
+    eng_mock._token_range_matcher = MagicMock()
+    eng_mock._pending_fp_lock = threading.Lock()
+    eng_mock._pending_fp_hashes = set()
+    # Bind the real drainer method to our mock.
+    eng_mock._drain_fingerprint_queue = (
+        v3_mod.BlendV3Module._drain_fingerprint_queue.__get__(eng_mock)
+    )
+    return eng_mock
+
+
+def test_fingerprint_queue_drains_in_order():
+    """Jobs enqueued by store() flow through the worker in submission order."""
+    # Standard
+    from queue import Queue
+
+    eng = _make_engine_with_mocked_matcher()
+    eng._fingerprint_queue = Queue()
+
+    worker = threading.Thread(target=eng._drain_fingerprint_queue, daemon=True)
+    worker.start()
+    try:
+        jobs = [
+            ([1, 2, 3], [b"h1"], 0, 0),
+            ([4, 5, 6], [b"h2"], 1, 3),
+            ([7, 8, 9], [b"h3"], 0, 6),
+        ]
+        for j in jobs:
+            eng._fingerprint_queue.put(j)
+        # Wait for the queue to drain (worker calls task_done implicitly
+        # only via get(); we just poll until matcher has all calls).
+        deadline = time.monotonic() + 2.0
+        while (
+            eng._token_range_matcher.on_new_token_hashes.call_count < len(jobs)
+            and time.monotonic() < deadline
+        ):
+            time.sleep(0.01)
+    finally:
+        eng._fingerprint_stop.set()
+        worker.join(timeout=1.0)
+
+    # All three were registered.
+    assert eng._token_range_matcher.on_new_token_hashes.call_count == 3
+    # In submission order.
+    calls = eng._token_range_matcher.on_new_token_hashes.call_args_list
+    assert calls[0].args[0] == [1, 2, 3]
+    assert calls[1].args[0] == [4, 5, 6]
+    assert calls[2].args[0] == [7, 8, 9]
+    # kwargs are preserved (start_chunk_idx, position_offset).
+    assert calls[1].kwargs == {"start_chunk_idx": 1, "position_offset": 3}
+
+
+def test_fingerprint_worker_survives_kernel_exception():
+    """A failing matcher call doesn't kill the worker."""
+    # Standard
+    from queue import Queue
+
+    eng = _make_engine_with_mocked_matcher()
+    eng._fingerprint_queue = Queue()
+    # First call raises, subsequent succeed.
+    eng._token_range_matcher.on_new_token_hashes.side_effect = [
+        RuntimeError("boom"),
+        None,
+    ]
+
+    worker = threading.Thread(target=eng._drain_fingerprint_queue, daemon=True)
+    worker.start()
+    try:
+        eng._fingerprint_queue.put(([1], [b"h1"], 0, 0))
+        eng._fingerprint_queue.put(([2], [b"h2"], 0, 1))
+        deadline = time.monotonic() + 2.0
+        while (
+            eng._token_range_matcher.on_new_token_hashes.call_count < 2
+            and time.monotonic() < deadline
+        ):
+            time.sleep(0.01)
+    finally:
+        eng._fingerprint_stop.set()
+        worker.join(timeout=1.0)
+
+    assert eng._token_range_matcher.on_new_token_hashes.call_count == 2
+    assert not worker.is_alive()
+
+
+def test_fingerprint_worker_stops_on_signal():
+    """``_fingerprint_stop`` event halts the drainer cleanly."""
+    # Standard
+    from queue import Queue
+
+    eng = _make_engine_with_mocked_matcher()
+    eng._fingerprint_queue = Queue()
+    worker = threading.Thread(target=eng._drain_fingerprint_queue, daemon=True)
+    worker.start()
+    eng._fingerprint_stop.set()
+    worker.join(timeout=1.0)
+    assert not worker.is_alive()
+
+
+# ---------------------------------------------------------------------------
+# L2: obj_keys cache lifecycle
+# ---------------------------------------------------------------------------
+
+
+def _fake_obj_key(chunk_hash: bytes, worker_id: int) -> SimpleNamespace:
+    return SimpleNamespace(chunk_hash=chunk_hash, worker_id=worker_id)
+
+
+def test_obj_keys_cache_round_trip_tp1():
+    """At world_size=1, retrieve can rebuild from the cache exactly."""
+    eng = MagicMock()
+    eng._lookup_obj_keys_cache = {}
+    eng._lookup_obj_keys_lock = threading.Lock()
+
+    # Simulate what cb_lookup_subsequences stores.
+    chunk_hashes = [b"h1", b"h2", b"h3"]
+    obj_keys_per_chunk = {h: [_fake_obj_key(h, 0)] for h in chunk_hashes}
+    with eng._lookup_obj_keys_lock:
+        eng._lookup_obj_keys_cache["req-1"] = obj_keys_per_chunk
+
+    # Simulate retrieve consuming the cache.
+    matches_sorted = [
+        SimpleNamespace(hash=h, cur_st=i) for i, h in enumerate(chunk_hashes)
+    ]
+    with eng._lookup_obj_keys_lock:
+        cached = eng._lookup_obj_keys_cache.pop("req-1", None)
+
+    assert cached is not None
+    assert all(r.hash in cached for r in matches_sorted)
+    rebuilt = [k for r in matches_sorted for k in cached[r.hash]]
+    assert len(rebuilt) == 3
+    assert [k.chunk_hash for k in rebuilt] == chunk_hashes
+    # Cache is now empty for this request.
+    with eng._lookup_obj_keys_lock:
+        assert "req-1" not in eng._lookup_obj_keys_cache
+
+
+def test_obj_keys_cache_round_trip_tp_expanded():
+    """world_size>1: cached entry per hash is a list of length world_size,
+    rebuilt list is flat chunk-major."""
+    eng = MagicMock()
+    eng._lookup_obj_keys_cache = {}
+    eng._lookup_obj_keys_lock = threading.Lock()
+
+    ws = 4
+    chunk_hashes = [b"h1", b"h2"]
+    per_hash = {h: [_fake_obj_key(h, w) for w in range(ws)] for h in chunk_hashes}
+    with eng._lookup_obj_keys_lock:
+        eng._lookup_obj_keys_cache["req-tp"] = per_hash
+
+    matches_sorted = [
+        SimpleNamespace(hash=h, cur_st=i) for i, h in enumerate(chunk_hashes)
+    ]
+    with eng._lookup_obj_keys_lock:
+        cached = eng._lookup_obj_keys_cache.pop("req-tp", None)
+    rebuilt = [k for r in matches_sorted for k in cached[r.hash]]
+    # Length = 2 chunks × 4 workers.
+    assert len(rebuilt) == 8
+    # Chunk-major: first 4 entries are h1's workers 0..3, then h2's.
+    assert [k.chunk_hash for k in rebuilt[:4]] == [b"h1"] * 4
+    assert [k.worker_id for k in rebuilt[:4]] == [0, 1, 2, 3]
+    assert [k.chunk_hash for k in rebuilt[4:]] == [b"h2"] * 4
+
+
+def test_obj_keys_cache_miss_falls_back():
+    """If the cache doesn't contain every match's hash, retrieve must
+    fall back to recompute (handled in the engine; this test just pins
+    the detection logic)."""
+    cached = {b"h1": ["k1"]}
+    matches = [SimpleNamespace(hash=b"h1"), SimpleNamespace(hash=b"h_missing")]
+    all_present = all(r.hash in cached for r in matches)
+    assert all_present is False
+
+
+# ---------------------------------------------------------------------------
+# L1: batched rope structure
+# ---------------------------------------------------------------------------
+
+
+class _FakeTensor:
+    """Minimal stand-in for the torch tensors used inside _apply_cb_rope_batched.
+    Tracks shape so the kernel mock can assert on it.
+    """
+
+    def __init__(self, shape):
+        self.shape = shape
+        self.device = "cpu"
+
+    def __getitem__(self, idx):
+        # tmp[0] selects K from the (2, num_layers, slots, hidden_dim) tensor.
+        return _FakeTensor(self.shape[1:] if isinstance(idx, int) else self.shape)
+
+    def reshape(self, *new_shape):
+        return _FakeTensor(tuple(new_shape))
+
+    def view(self, *new_shape):
+        return _FakeTensor(tuple(new_shape))
+
+
+def _build_fake_gpu_context(batch_size: int, num_groups: int):
+    """Returns a MagicMock matching the minimal GPUCacheContext surface
+    used by _apply_cb_rope_batched."""
+    gpu_context = MagicMock()
+    gpu_context.kv_layer_groups_manager.num_kernel_groups = num_groups
+    # All groups: uncompressed (tokens_per_block == slots_per_block), kv_size=2.
+    groups = [
+        SimpleNamespace(tokens_per_block=4, slots_per_block=4, engine_group_idx=idx)
+        for idx in range(num_groups)
+    ]
+    gpu_context.kv_layer_groups_manager.kernel_groups = groups
+
+    # Each per-(slot, group) buffer has shape
+    # (2 kv, num_layers, slots_per_block, hidden_dim).
+    num_layers, slots_per_block, hidden_dim = 2, 4, 64
+    head_size = 32
+
+    def _get_temp_kernel_group_buffer(batch_idx, kernel_group_idx):
+        return _FakeTensor((2, num_layers, slots_per_block, hidden_dim))
+
+    gpu_context.get_temp_kernel_group_buffer.side_effect = _get_temp_kernel_group_buffer
+    return gpu_context, head_size
+
+
+def test_batched_rope_calls_kernel_per_group_per_slot():
+    """For N non-prefix slots and G groups, kernel is called N*G times
+    (matching today's CUDA-level work) but the Python ``per-group setup``
+    runs only G times (vs N*G under the legacy path)."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    gpu_context, head_size = _build_fake_gpu_context(batch_size=4, num_groups=2)
+    rope_state = v3_mod._CBRopeState(
+        head_size=head_size,
+        is_neox_style=True,
+        cos_sin_caches=[MagicMock()],
+        group_to_cache=[],
+    )
+
+    eng = MagicMock(spec=v3_mod.BlendV3Module)
+    eng._apply_cb_rope_batched = v3_mod.BlendV3Module._apply_cb_rope_batched.__get__(
+        eng
+    )
+
+    slots_to_rope = [(0, 100, 200), (2, 300, 400)]  # 2 non-prefix slots
+
+    with (
+        patch.object(v3_mod, "lmc_ops") as ops,
+        patch.object(v3_mod, "torch") as torch_mod,
+    ):
+        torch_mod.long = "long"
+
+        # Build a fake positions tensor that supports + and .repeat()
+        class _Pos:
+            def __add__(self, other):
+                return _Pos()
+
+            def __radd__(self, other):
+                return _Pos()
+
+            def repeat(self, n):
+                return _Pos()
+
+        torch_mod.arange.return_value = _Pos()
+
+        eng._apply_cb_rope_batched(gpu_context, rope_state, 4, slots_to_rope)
+
+    # all_slots is built once per group (G=2), each fetching the full batch
+    # of slot buffers => batch_len(4) × G(2) = 8 buffer fetches, independent
+    # of how many slots are actually re-RoPE'd.
+    assert gpu_context.get_temp_kernel_group_buffer.call_count == 8
+    # Kernel called N=2 slots × G=2 groups = 4 times.
+    assert ops.rotary_embedding_k_fused.call_count == 4
+
+
+def test_batched_rope_noop_on_empty_slots():
+    """No non-prefix slots → no setup, no kernel calls."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    gpu_context, head_size = _build_fake_gpu_context(batch_size=2, num_groups=2)
+    rope_state = v3_mod._CBRopeState(
+        head_size=head_size,
+        is_neox_style=False,
+        cos_sin_caches=[MagicMock()],
+        group_to_cache=[],
+    )
+    eng = MagicMock(spec=v3_mod.BlendV3Module)
+    eng._apply_cb_rope_batched = v3_mod.BlendV3Module._apply_cb_rope_batched.__get__(
+        eng
+    )
+
+    with patch.object(v3_mod, "lmc_ops") as ops:
+        eng._apply_cb_rope_batched(gpu_context, rope_state, 2, [])
+
+    assert gpu_context.get_temp_kernel_group_buffer.call_count == 0
+    assert ops.rotary_embedding_k_fused.call_count == 0
+
+
+def test_batched_rope_raises_on_compressed_layout():
+    """A compressed group (tokens_per_block != slots_per_block) → RuntimeError."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    gpu_context = MagicMock()
+    gpu_context.kv_layer_groups_manager.num_kernel_groups = 1
+    gpu_context.kv_layer_groups_manager.kernel_groups = [
+        SimpleNamespace(tokens_per_block=8, slots_per_block=4)
+    ]
+    rope_state = SimpleNamespace(
+        head_size=32, cos_sin_cache=MagicMock(), is_neox_style=True
+    )
+
+    eng = MagicMock(spec=v3_mod.BlendV3Module)
+    eng._apply_cb_rope_batched = v3_mod.BlendV3Module._apply_cb_rope_batched.__get__(
+        eng
+    )
+
+    with pytest.raises(RuntimeError, match="is compressed"):
+        eng._apply_cb_rope_batched(gpu_context, rope_state, 2, [(0, 1, 2)])
+
+
+# ---------------------------------------------------------------------------
+# Coordinator (global) leg: conversion to retrievable CBMatchResult + deadline
+# ---------------------------------------------------------------------------
+
+
+def _coord_engine(chunk_size: int = 4):
+    """A BlendV3Module mock with the coordinator-leg methods bound."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    eng = MagicMock(spec=v3_mod.BlendV3Module)
+    eng._ctx = SimpleNamespace(chunk_size=chunk_size)
+    # _event_bus is an instance attr (set in __init__), so spec= omits it;
+    # _poll_coordinator_match publishes CB_COORDINATOR_MATCH_END through it.
+    eng._event_bus = MagicMock()
+    eng._build_global_segments = v3_mod.BlendV3Module._build_global_segments.__get__(
+        eng
+    )
+    eng._poll_coordinator_match = v3_mod.BlendV3Module._poll_coordinator_match.__get__(
+        eng
+    )
+    return eng
+
+
+def test_build_global_segments_are_retrievable_cbmatchresults():
+    """Coordinator object_key hex round-trips to the hash the retrieve path
+    resolves via ipc_key_to_object_keys; positions span one chunk."""
+    # First Party
+    from lmcache.v1.mp_coordinator.blend_client import RemoteMatch
+    from lmcache.v1.multiprocess.custom_types import CBMatchResult
+
+    eng = _coord_engine(chunk_size=4)
+    raw = bytes.fromhex("00") * 0 + b"\xab\xcd\xef\x01"
+    matches = [RemoteMatch(object_key=raw.hex(), old_st=8, cur_st=20)]
+
+    segs = eng._build_global_segments(matches)
+
+    assert len(segs) == 1
+    seg = segs[0]
+    assert isinstance(seg, CBMatchResult)
+    assert seg.hash == raw  # hex -> exact bytes the retrieve path expands
+    assert (seg.old_st, seg.old_ed, seg.cur_st, seg.cur_ed) == (8, 12, 20, 24)
+
+
+def test_poll_coordinator_match_deferred_then_resolved():
+    """PENDING within deadline defers (None); a list resolves to segments."""
+    # First Party
+    from lmcache.v1.mp_coordinator.blend_client import PENDING, RemoteMatch
+
+    eng = _coord_engine(chunk_size=4)
+    coordinator = MagicMock()
+    eng._coordinator = coordinator
+    job = SimpleNamespace(coord_submitted=True, coord_deadline=time.monotonic() + 60)
+
+    coordinator.poll_match.return_value = PENDING
+    assert eng._poll_coordinator_match(job, "rid") is None  # defer
+    coordinator.take_match.assert_not_called()
+
+    coordinator.poll_match.return_value = [RemoteMatch("aa", old_st=0, cur_st=4)]
+    out = eng._poll_coordinator_match(job, "rid")
+    assert [s.cur_st for s in out] == [4]
+    coordinator.take_match.assert_called_once_with("rid")
+
+
+def test_poll_coordinator_match_gives_up_past_deadline():
+    """PENDING past the deadline degrades to local-only ([]) and drops state."""
+    # First Party
+    from lmcache.v1.mp_coordinator.blend_client import PENDING
+
+    eng = _coord_engine(chunk_size=4)
+    coordinator = MagicMock()
+    eng._coordinator = coordinator
+    coordinator.poll_match.return_value = PENDING
+    job = SimpleNamespace(coord_submitted=True, coord_deadline=time.monotonic() - 1)
+
+    assert eng._poll_coordinator_match(job, "rid") == []
+    coordinator.take_match.assert_called_once_with("rid")
+
+
+def test_non_overlapping_after_prefix():
+    """Prefix filter + leftmost-greedy overlap dedup, filter applied first."""
+    # First Party
+    from lmcache.v1.multiprocess.custom_types import CBMatchResult
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    f = v3_mod.BlendV3Module._non_overlapping_after_prefix
+
+    def m(cur_st: int, cur_ed: int) -> CBMatchResult:
+        return CBMatchResult(
+            old_st=0, old_ed=cur_ed - cur_st, cur_st=cur_st, cur_ed=cur_ed, hash=b""
+        )
+
+    assert f([], 0) == []
+
+    # Overlap dedup + ascending cur_st: 10-20 overlaps the kept 5-15, dropped.
+    out = f([m(10, 20), m(5, 15), m(15, 25)], 0)
+    assert [(r.cur_st, r.cur_ed) for r in out] == [(5, 15), (15, 25)]
+
+    # Prefix filter drops matches starting before the coverage.
+    out = f([m(0, 10), m(10, 20)], 5)
+    assert [r.cur_st for r in out] == [10]
+
+    # Filter precedes dedup: a prefix-covered match (5-13) must NOT suppress the
+    # usable 10-18 in the greedy pass (dedup-first would drop both -> []).
+    out = f([m(5, 13), m(10, 18)], 8)
+    assert [r.cur_st for r in out] == [10]
+
+
+# ---------------------------------------------------------------------------
+# Dual-RoPE: per-group cache selection + registration validation
+# ---------------------------------------------------------------------------
+
+
+def test_cache_for_group_uniform_and_mapped():
+    """Empty map -> every group uses cache 0; a map indexes per group;
+    a group past the map's end raises instead of guessing."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    local, global_ = MagicMock(), MagicMock()
+
+    uniform = v3_mod._CBRopeState(
+        head_size=32, is_neox_style=True, cos_sin_caches=[local], group_to_cache=[]
+    )
+    assert uniform.cache_for_group(0) is local
+    assert uniform.cache_for_group(5) is local
+
+    mapped = v3_mod._CBRopeState(
+        head_size=32,
+        is_neox_style=True,
+        cos_sin_caches=[local, global_],
+        group_to_cache=[0, 1],
+    )
+    assert mapped.cache_for_group(0) is local
+    assert mapped.cache_for_group(1) is global_
+    with pytest.raises(RuntimeError, match="no rope cache mapping"):
+        mapped.cache_for_group(2)
+
+
+def _rope_registration_engine(engine_group_indices: list[int]):
+    """A BlendV3Module mock with ``cb_register_rope`` bound and a registered
+    instance whose kernel groups span the given engine group indices."""
+    # First Party
+    from lmcache.v1.multiprocess.modules import blend_v3 as v3_mod
+
+    eng = MagicMock(spec=v3_mod.BlendV3Module)
+    eng._cb_rope_state = {}
+    eng._transfer_module = MagicMock()
+    entry = SimpleNamespace(
+        cache_context=SimpleNamespace(
+            kv_layer_groups_manager=SimpleNamespace(
+                kernel_groups=[
+                    SimpleNamespace(engine_group_idx=idx)
+                    for idx in engine_group_indices
+                ]
+            )
+        )
+    )
+    eng._transfer_module.get_and_touch_context_entry.return_value = entry
+    eng.cb_register_rope = v3_mod.BlendV3Module.cb_register_rope.__get__(eng)
+    return eng
+
+
+def _unit_rope_cache_ipc():
+    """An IPC-wrapper mock whose tensor has unit magnitude (cos=1, sin=0),
+    so registration skips mscale normalization."""
+    # Third Party
+    import torch
+
+    cache = torch.zeros(4, 8)
+    cache[:, :4] = 1.0
+    ipc = MagicMock()
+    ipc.to_tensor.return_value = cache
+    return ipc
+
+
+def test_register_rope_dual_cache_round_trip():
+    """Two caches + a full engine-group map register and land in rope state."""
+    eng = _rope_registration_engine(engine_group_indices=[0, 1])
+
+    eng.cb_register_rope(
+        instance_id=7,
+        cos_sin_caches_ipc=[_unit_rope_cache_ipc(), _unit_rope_cache_ipc()],
+        head_size=8,
+        is_neox_style=True,
+        group_to_cache=[0, 1],
+    )
+
+    state = eng._cb_rope_state[7]
+    assert len(state.cos_sin_caches) == 2
+    assert state.group_to_cache == [0, 1]
+    assert state.cache_for_group(1) is state.cos_sin_caches[1]
+
+
+def test_register_rope_rejects_invalid_group_to_cache():
+    """Out-of-range / negative cache indices and a map that does not cover
+    every engine group of the registered model are rejected."""
+    eng = _rope_registration_engine(engine_group_indices=[0, 1])
+    caches = [_unit_rope_cache_ipc(), _unit_rope_cache_ipc()]
+
+    with pytest.raises(ValueError, match="outside"):
+        eng.cb_register_rope(1, caches, 8, True, group_to_cache=[0, 2])
+    with pytest.raises(ValueError, match="outside"):
+        eng.cb_register_rope(1, caches, 8, True, group_to_cache=[-1, 0])
+    # Model has engine groups {0, 1} but the map only covers group 0.
+    with pytest.raises(ValueError, match="engine groups up to index 1"):
+        eng.cb_register_rope(1, caches, 8, True, group_to_cache=[0])
+    with pytest.raises(ValueError, match=">=1 cos/sin cache"):
+        eng.cb_register_rope(1, [], 8, True, group_to_cache=[])
+
+
+def test_register_rope_requires_registered_instance():
+    """CB_REGISTER_ROPE_V3 before REGISTER_KV_CACHE is rejected."""
+    eng = _rope_registration_engine(engine_group_indices=[0])
+    eng._transfer_module.get_and_touch_context_entry.return_value = None
+
+    with pytest.raises(ValueError, match="no paged KV cache registered"):
+        eng.cb_register_rope(1, [_unit_rope_cache_ipc()], 8, True, group_to_cache=[])
diff --git a/tests/v1/multiprocess/test_cache_server.py b/tests/v1/multiprocess/test_cache_server.py
new file mode 100644
index 0000000..e4f2e1b
--- /dev/null
+++ b/tests/v1/multiprocess/test_cache_server.py
@@ -0,0 +1,753 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Generator
+import multiprocessing as mp
+import os
+import time
+
+# Third Party
+import pytest
+import torch
+import zmq
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.mp_observability.config import DEFAULT_OBSERVABILITY_CONFIG
+from lmcache.v1.multiprocess.config import MPServerConfig
+from lmcache.v1.multiprocess.custom_types import (
+    IPCCacheServerKey,
+    KVCache,
+)
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    get_response_class,
+)
+from lmcache.v1.multiprocess.server import run_cache_server
+from lmcache.v1.platform.cuda.ipc_wrapper import CudaIPCWrapper
+
+# Configuration constants
+SERVER_HOST = "localhost"
+SERVER_PORT = 5599
+SERVER_URL = f"tcp://{SERVER_HOST}:{SERVER_PORT}"
+CHUNK_SIZE = 256
+CPU_BUFFER_SIZE = 5.0
+DEFAULT_TIMEOUT = 20.0
+
+
+def _has_working_new_shared_cuda() -> bool:
+    if not torch.cuda.is_available():
+        print("CUDA is not available, skipping tests that require new_shared_cuda")
+        return False
+    try:
+        # Minimal sanity check — adapt to your real API
+        buf = torch.empty(1024, device="cuda")
+        shared = buf.untyped_storage()._share_cuda_()  # or your exact call
+        return shared is not None
+    except Exception:
+        return False
+
+
+if not _has_working_new_shared_cuda():
+    pytest.skip(
+        "new_shared_cuda is not available or not working on this system",
+        allow_module_level=True,
+    )
+
+
+def initialize_kv_cache(
+    device: torch.device,
+    num_pages: int = 1024,
+    num_layers: int = 32,
+    page_size: int = 16,
+    num_heads: int = 8,
+    head_size: int = 128,
+    dtype: torch.dtype = torch.bfloat16,
+) -> list[torch.Tensor]:
+    """
+    Initialize KV cache tensors on GPU for testing.
+    """
+    torch.random.manual_seed(42)
+
+    gpu_tensors = [
+        torch.rand(
+            (2, num_pages, page_size, num_heads, head_size),
+            dtype=dtype,
+            device=device,
+        )
+        for _ in range(num_layers)
+    ]
+
+    return gpu_tensors
+
+
+class ClientContext:
+    """
+    Client context that manages GPU KV cache tensors.
+    """
+
+    def __init__(
+        self,
+        device: torch.device,
+        num_pages: int = 1024,
+        num_layers: int = 32,
+        page_size: int = 16,
+        num_heads: int = 8,
+        head_size: int = 128,
+        dtype: torch.dtype = torch.bfloat16,
+    ):
+        self.device = device
+        self.num_pages = num_pages
+        self.num_layers = num_layers
+        self.page_size = page_size
+        self.num_heads = num_heads
+        self.head_size = head_size
+        self.dtype = dtype
+
+        self.gpu_kv_caches = initialize_kv_cache(
+            device, num_pages, num_layers, page_size, num_heads, head_size, dtype
+        )
+
+    def get_kv_cache(self) -> KVCache:
+        """
+        Wrap GPU tensors in CudaIPCWrapper for IPC communication.
+        """
+        return [CudaIPCWrapper(tensor) for tensor in self.gpu_kv_caches]
+
+    def get_tensor_slice(
+        self, layer: int, start_page: int, num_pages: int
+    ) -> torch.Tensor:
+        """
+        Get a slice of the KV cache tensor for a specific layer.
+        """
+        return self.gpu_kv_caches[layer][:, start_page : start_page + num_pages]
+
+
+def create_cache_key(index: int, model: str = "testmodel") -> IPCCacheServerKey:
+    """
+    Create a cache key for testing.
+    """
+    global CHUNK_SIZE
+    token_ids = [index] * CHUNK_SIZE
+    return IPCCacheServerKey.from_token_ids(
+        model,
+        1,
+        0,
+        token_ids,
+        start=0,
+        end=CHUNK_SIZE,
+        request_id=f"test_request_{index}",
+    )
+
+
+BLOCKS_PER_KEY = 16
+
+
+def lookup_all(
+    client: MessageQueueClient,
+    keys: list[IPCCacheServerKey],
+    timeout: float = DEFAULT_TIMEOUT,
+) -> int:
+    """Lookup all keys individually and return total found count.
+
+    Uses the two-phase lookup protocol: LOOKUP registers the job server-side,
+    then QUERY_PREFETCH_STATUS is polled by request_id until the result is ready.
+    """
+    total = 0
+    for key in keys:
+        lookup_key = key.no_worker_id_version()
+        # Phase 1: Submit lookup (server tracks by request_id, returns None)
+        client.submit_request(
+            RequestType.LOOKUP,
+            [lookup_key, 1],
+            get_response_class(RequestType.LOOKUP),
+        ).result(timeout=timeout)
+        # Phase 2: Poll by request_id until done
+        while True:
+            result = client.submit_request(
+                RequestType.QUERY_PREFETCH_STATUS,
+                [lookup_key.request_id],
+                get_response_class(RequestType.QUERY_PREFETCH_STATUS),
+            ).result(timeout=timeout)
+            if result is not None:
+                total += result
+                break
+    return total
+
+
+def store_keys(
+    client: MessageQueueClient,
+    keys: list[IPCCacheServerKey],
+    instance_id: int,
+    gpu_block_ids: list[int],
+    event: torch.cuda.Event,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> None:
+    """Store keys one at a time using the single-key API."""
+    for i, key in enumerate(keys):
+        start = i * BLOCKS_PER_KEY
+        end = start + BLOCKS_PER_KEY
+        block_ids = gpu_block_ids[start:end]
+        future = client.submit_request(
+            RequestType.STORE,
+            [key, instance_id, [block_ids], event.ipc_handle()],
+            get_response_class(RequestType.STORE),
+        )
+        result = future.to_cuda_future().result(timeout=timeout)
+        assert result is True, f"Store should succeed for key {i}"
+
+
+def retrieve_keys(
+    client: MessageQueueClient,
+    keys: list[IPCCacheServerKey],
+    instance_id: int,
+    gpu_block_ids: list[int],
+    event: torch.cuda.Event,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> list[bool]:
+    """Retrieve keys one at a time using the single-key API."""
+    results = []
+    for i, key in enumerate(keys):
+        start = i * BLOCKS_PER_KEY
+        end = start + BLOCKS_PER_KEY
+        block_ids = gpu_block_ids[start:end]
+        future = client.submit_request(
+            RequestType.RETRIEVE,
+            [key, instance_id, [block_ids], event.ipc_handle(), 0],
+            get_response_class(RequestType.RETRIEVE),
+        )
+        result = future.to_cuda_future().result(timeout=timeout)
+        results.append(result)
+    return results
+
+
+def server_process_runner(
+    host: str, port: int, chunk_size: int, cpu_buffer_size: float
+):
+    """
+    Entry point for the server process.
+    """
+    mp_config = MPServerConfig(host=host, port=port, chunk_size=chunk_size)
+    storage_manager_config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=int(cpu_buffer_size * 1024**3),
+                use_lazy=True,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+    run_cache_server(
+        mp_config=mp_config,
+        storage_manager_config=storage_manager_config,
+        obs_config=DEFAULT_OBSERVABILITY_CONFIG,
+    )
+
+
+@pytest.fixture(scope="module")
+def server_process() -> Generator[mp.Process, None, None]:
+    """
+    Fixture that starts the cache server in a separate process.
+    The server runs for the entire test module.
+    """
+    # Start server process
+    mp.set_start_method("spawn", force=True)
+    process = mp.Process(
+        target=server_process_runner,
+        args=(SERVER_HOST, SERVER_PORT, CHUNK_SIZE, CPU_BUFFER_SIZE),
+        daemon=True,
+    )
+    process.start()
+
+    # Wait for server to initialize
+    time.sleep(2)
+
+    yield process
+
+    # Cleanup: terminate the server process
+    if process.is_alive():
+        process.terminate()
+        process.join(timeout=5)
+        if process.is_alive():
+            process.kill()
+            process.join()
+
+
+@pytest.fixture(scope="module")
+def zmq_context() -> Generator[zmq.Context, None, None]:
+    """
+    Fixture that provides a ZMQ context for the test module.
+    """
+    context = zmq.Context.instance()
+    yield context
+    # Context cleanup is handled by ZMQ
+
+
+@pytest.fixture(scope="function")
+def client(
+    server_process: mp.Process, zmq_context: zmq.Context
+) -> Generator[MessageQueueClient, None, None]:
+    """
+    Fixture that provides a message queue client for each test function.
+    """
+    client = MessageQueueClient(server_url=SERVER_URL, context=zmq_context)
+    yield client
+    # Client cleanup
+    client.close()
+
+
+@pytest.fixture(scope="function")
+def client_context() -> Generator[ClientContext, None, None]:
+    """
+    Fixture that provides a client context with initialized KV cache.
+    """
+    if not torch.cuda.is_available():
+        pytest.skip("CUDA is not available")
+
+    device = torch.device("cuda:0")
+    ctx = ClientContext(device=device)
+    yield ctx
+
+    # Cleanup GPU memory
+    del ctx.gpu_kv_caches
+    torch.cuda.empty_cache()
+
+
+@pytest.fixture(scope="function")
+def registered_instance(
+    client: MessageQueueClient, client_context: ClientContext
+) -> Generator[int, None, None]:
+    """
+    Fixture that registers a KV cache instance and returns the instance ID.
+    Automatically unregisters after the test.
+    """
+    instance_id = os.getpid()
+
+    # Register KV cache. No engine group infos are sent, so the server
+    # detects ``slots_per_block`` from the tensors and treats every group
+    # as uncompressed (``compress_ratio == 1``).
+    future = client.submit_request(
+        RequestType.REGISTER_KV_CACHE,
+        [
+            instance_id,
+            client_context.get_kv_cache(),
+            "testmodel",
+            1,
+            EngineType.VLLM,
+            {},
+            [],
+        ],
+        get_response_class(RequestType.REGISTER_KV_CACHE),
+    )
+    result = future.result(timeout=DEFAULT_TIMEOUT)
+    assert result is None, "Register should return None"
+
+    yield instance_id
+
+    # Unregister KV cache
+    try:
+        client.submit_request(
+            RequestType.CLEAR, [], get_response_class(RequestType.CLEAR)
+        ).result(timeout=DEFAULT_TIMEOUT)
+        future = client.submit_request(
+            RequestType.UNREGISTER_KV_CACHE,
+            [instance_id],
+            get_response_class(RequestType.UNREGISTER_KV_CACHE),
+        )
+        future.result(timeout=DEFAULT_TIMEOUT)
+    except Exception as e:
+        print(f"Error during unregister: {e}")
+
+
+# ============================================================================
+# Test Functions
+# ============================================================================
+
+
+def test_server_running(server_process: mp.Process):
+    """
+    Test that the server process is running.
+    """
+    assert server_process.is_alive(), "Server process should be running"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Register/Unregister KV cache requires CUDA",
+)
+def test_register_unregister_kv_cache(
+    client: MessageQueueClient, client_context: ClientContext
+):
+    """
+    Test registering and unregistering a KV cache.
+    """
+    instance_id = os.getpid()
+
+    # Register. No engine group infos: geometry is detected from the
+    # tensors (uncompressed).
+    future = client.submit_request(
+        RequestType.REGISTER_KV_CACHE,
+        [
+            instance_id,
+            client_context.get_kv_cache(),
+            "testmodel",
+            1,
+            EngineType.VLLM,
+            {},
+            [],
+        ],
+        get_response_class(RequestType.REGISTER_KV_CACHE),
+    )
+    result = future.result(timeout=DEFAULT_TIMEOUT)
+    assert result is None
+
+    # Unregister
+    future = client.submit_request(
+        RequestType.UNREGISTER_KV_CACHE,
+        [instance_id],
+        get_response_class(RequestType.UNREGISTER_KV_CACHE),
+    )
+    result = future.result(timeout=DEFAULT_TIMEOUT)
+    assert result is None
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Store and Lookup require CUDA",
+)
+def test_store_and_lookup(
+    client: MessageQueueClient,
+    client_context: ClientContext,
+    registered_instance: int,
+):
+    """
+    Test storing KV cache entries and looking them up.
+    """
+    num_keys = 10
+    keys = [create_cache_key(i) for i in range(num_keys)]
+    gpu_block_ids = list(range(0, 16 * num_keys))
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+
+    # Store
+    store_keys(client, keys, registered_instance, gpu_block_ids, event)
+
+    # Lookup - keys that exist
+    lookup_result = lookup_all(client, keys)
+    assert lookup_result == num_keys, "All stored keys should exist"
+
+    # Lookup - keys that don't exist
+    non_existent_keys = [create_cache_key(i + 1000) for i in range(5)]
+    lookup_result2 = lookup_all(client, non_existent_keys)
+    assert lookup_result2 == 0, "Non-existent keys should not be found"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Store requires CUDA",
+)
+def test_store_fails_closed_on_incomplete_block_ids(
+    client: MessageQueueClient,
+    client_context: ClientContext,
+    registered_instance: int,
+):
+    """An under-length block-id list skips the whole store (fail-closed).
+
+    Regression guard for the all-or-nothing store contract: a ``gpu_block_ids``
+    list too short to fully cover a chunk (e.g. a caller/protocol bug) must skip
+    the store entirely (returning ``False``) and commit nothing — the previous
+    fail-open path raised internally but then ``finish_write``-committed the
+    reservation anyway, turning the key into a retrievable garbage entry (lookup
+    would find it).
+
+    The committed-state assertion is on a *miss* (lookup == 0), which is robust
+    to this harness's known store->lookup race (that race can only turn a true
+    hit into a miss, never the reverse).
+    """
+    # One-chunk key (256 tokens == BLOCKS_PER_KEY blocks) but only half the
+    # block IDs needed, so the chunk is not fully covered.
+    key = create_cache_key(90001)
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+
+    result = (
+        client.submit_request(
+            RequestType.STORE,
+            [
+                key,
+                registered_instance,
+                [list(range(BLOCKS_PER_KEY // 2))],
+                event.ipc_handle(),
+            ],
+            get_response_class(RequestType.STORE),
+        )
+        .to_cuda_future()
+        .result(timeout=DEFAULT_TIMEOUT)
+    )
+    assert result is False, "Store should fail closed (skip) on a short list"
+    assert lookup_all(client, [key]) == 0, "An uncovered chunk must not be committed"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Store, Retrieve, and Verify require CUDA",
+)
+def test_store_retrieve_verify(
+    client: MessageQueueClient,
+    client_context: ClientContext,
+    registered_instance: int,
+):
+    """
+    Test storing and retrieving KV cache entries, verifying correctness.
+    """
+    num_keys = 20
+    keys = [create_cache_key(i) for i in range(num_keys)]
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+
+    # Store at the beginning of the cache
+    store_block_ids = list(range(0, 16 * num_keys))
+    store_keys(client, keys, registered_instance, store_block_ids, event)
+
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+
+    # Call look up to ensure the data is ready to be retrieved
+    lookup_result = lookup_all(client, keys)
+    assert lookup_result == num_keys
+
+    # Retrieve to a different location in the cache
+    # Use offset of 40 blocks (640 pages total needed: 320 + 320)
+    retrieve_offset = 40 * 16
+    retrieve_block_ids = list(range(retrieve_offset, retrieve_offset + 16 * num_keys))
+    retrieve_result = retrieve_keys(
+        client, keys, registered_instance, retrieve_block_ids, event
+    )
+
+    assert len(retrieve_result) == num_keys
+    assert all(retrieve_result), "All keys should be retrieved successfully"
+
+    # Verify correctness by comparing tensors
+    for i in range(num_keys):
+        for layer in range(client_context.num_layers):
+            original_block = i * 16
+            retrieved_block = retrieve_offset + i * 16
+
+            original_tensor = client_context.gpu_kv_caches[layer][
+                :, original_block : original_block + 16
+            ]
+            retrieved_tensor = client_context.gpu_kv_caches[layer][
+                :, retrieved_block : retrieved_block + 16
+            ]
+
+            assert torch.allclose(original_tensor, retrieved_tensor, atol=1e-4), (
+                f"Mismatch for key {i}, layer {layer}"
+            )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Partial miss retrieval requires CUDA",
+)
+def test_retrieve_partial_miss(
+    client: MessageQueueClient,
+    client_context: ClientContext,
+    registered_instance: int,
+):
+    """
+    Test retrieving when some keys exist and some don't.
+    The retrieve should return ALL FALSE if any key is missing.
+    """
+    # Store first 30 keys (480 pages)
+    num_stored = 30
+    stored_keys = [create_cache_key(i) for i in range(num_stored)]
+    store_block_ids = list(range(0, 16 * num_stored))
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+
+    store_keys(client, stored_keys, registered_instance, store_block_ids, event)
+
+    # Lookup to ensure keys are stored
+    lookup_result = lookup_all(client, stored_keys)
+    assert lookup_result == num_stored
+
+    # Try to retrieve 60 keys (only first 30 exist)
+    # Total pages needed: 60 * 16 = 960 (< 1024)
+    num_requested = 60
+    all_keys = [create_cache_key(i) for i in range(num_requested)]
+    # Start retrieve at offset 2 keys (32 pages)
+    retrieve_offset_keys = 2
+    retrieve_block_ids = list(
+        range(retrieve_offset_keys * 16, (retrieve_offset_keys + num_requested) * 16)
+    )
+
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+
+    retrieve_result = retrieve_keys(
+        client, all_keys, registered_instance, retrieve_block_ids, event
+    )
+
+    assert len(retrieve_result) == num_requested
+    # First 30 keys exist, remaining 30 don't
+    assert all(retrieve_result[:num_stored]), "Stored keys should be retrieved"
+    assert not any(retrieve_result[num_stored:]), (
+        "Non-existent keys should fail to retrieve"
+    )
+
+    # Doing look up again to ensure data is ready
+    lookup_result_2 = lookup_all(client, stored_keys)
+    assert lookup_result_2 == num_stored
+
+    # Try to retrieve the first 30 keys only (all exist)
+    retrieve_block_ids_2 = list(range(0, 16 * num_stored))
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+    retrieve_result_2 = retrieve_keys(
+        client, stored_keys, registered_instance, retrieve_block_ids_2, event
+    )
+    assert len(retrieve_result_2) == num_stored
+    assert all(retrieve_result_2), "All stored keys should be retrieved successfully"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Multiple retrieve operations require CUDA",
+)
+def test_multiple_retrieve_operations(
+    client: MessageQueueClient,
+    client_context: ClientContext,
+    registered_instance: int,
+):
+    """
+    Test multiple retrieve operations:
+    Store 8,8,8,8 keys and then retrieve 8,8,8,8 keys in sequence.
+    """
+    num_batches = 4
+    keys_per_batch = 8
+    pages_per_key = 16
+
+    # Initialize the values in GPU KV cache
+    for layer in range(client_context.num_layers):
+        layer_cache = client_context.gpu_kv_caches[layer]
+        for i in range(num_batches):
+            start_page = (i * keys_per_batch) * pages_per_key
+            end_page = start_page + (keys_per_batch * pages_per_key)
+            layer_cache[:, start_page:end_page] = (i + 1) / num_batches
+
+    # Store in batches
+    for batch_idx in range(num_batches):
+        keys = [
+            create_cache_key(batch_idx * keys_per_batch + i)
+            for i in range(keys_per_batch)
+        ]
+        blocks = list(
+            range(
+                (batch_idx * keys_per_batch) * 16,
+                (batch_idx * keys_per_batch + keys_per_batch) * 16,
+            )
+        )
+        event = torch.cuda.Event(interprocess=True)
+        event.record()
+        store_keys(client, keys, registered_instance, blocks, event)
+
+    # Doing look up to ensure data is ready to be retrieved
+    all_keys = [
+        create_cache_key(batch_idx * keys_per_batch + i)
+        for batch_idx in range(num_batches)
+        for i in range(keys_per_batch)
+    ]
+    lookup_result = lookup_all(client, all_keys)
+    assert lookup_result == num_batches * keys_per_batch, "All stored keys should exist"
+
+    # Retrieve in batches
+    retrieve_offset = 32  # Start retrieving at offset of 32 chunks
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+    for batch_idx in range(num_batches):
+        keys = [
+            create_cache_key(batch_idx * keys_per_batch + i)
+            for i in range(keys_per_batch)
+        ]
+        blocks = list(
+            range(
+                (batch_idx * keys_per_batch + retrieve_offset) * pages_per_key,
+                (batch_idx * keys_per_batch + retrieve_offset + keys_per_batch)
+                * pages_per_key,
+            )
+        )
+
+        retrieve_result = retrieve_keys(
+            client, keys, registered_instance, blocks, event
+        )
+        assert len(retrieve_result) == keys_per_batch
+        assert all(retrieve_result), "All keys should be retrieved successfully"
+
+    # Verify correctness
+    for layer in range(client_context.num_layers):
+        layer_cache = client_context.gpu_kv_caches[layer]
+        for batch_idx in range(num_batches):
+            start_page = (retrieve_offset + batch_idx * keys_per_batch) * pages_per_key
+            end_page = start_page + (keys_per_batch * pages_per_key)
+            retrieved_tensor = layer_cache[:, start_page:end_page]
+            expected_value = (batch_idx + 1) / num_batches
+            assert torch.allclose(
+                retrieved_tensor,
+                torch.full_like(retrieved_tensor, expected_value),
+            ), f"Mismatch in batch {batch_idx}, layer {layer}"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Multiple store operations require CUDA",
+)
+def test_multiple_store_operations(
+    client: MessageQueueClient,
+    client_context: ClientContext,
+    registered_instance: int,
+):
+    """
+    Test multiple store operations in sequence.
+    """
+    # Store batch 1
+    keys1 = [create_cache_key(i) for i in range(30)]
+    blocks1 = list(range(0, 16 * 30))
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+    store_keys(client, keys1, registered_instance, blocks1, event)
+
+    # Store batch 2
+    keys2 = [create_cache_key(i + 30) for i in range(20)]
+    blocks2 = list(range(30 * 16, 50 * 16))
+
+    # Test with the same event for 2 store requests
+    store_keys(client, keys2, registered_instance, blocks2, event)
+
+    # Verify all keys exist
+    all_keys = keys1 + keys2
+    lookup_result = lookup_all(client, all_keys)
+    assert lookup_result == 50, "All stored keys from both batches should exist"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="Get chunk size requires CUDA"
+)
+def test_get_chunk_size(
+    client: MessageQueueClient,
+):
+    """
+    Test retrieving the chunk size from the server.
+    """
+    chunk_size = client.submit_request(
+        RequestType.GET_CHUNK_SIZE,
+        [],
+        get_response_class(RequestType.GET_CHUNK_SIZE),
+    ).result(timeout=DEFAULT_TIMEOUT)
+
+    assert chunk_size == CHUNK_SIZE, f"Chunk size should be {CHUNK_SIZE}"
diff --git a/tests/v1/multiprocess/test_completion_recorder.py b/tests/v1/multiprocess/test_completion_recorder.py
new file mode 100644
index 0000000..9a29740
--- /dev/null
+++ b/tests/v1/multiprocess/test_completion_recorder.py
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for the C++ CompletionRecorder and DeviceHostFuncDispatcher."""
+
+# Standard
+import threading
+import time
+
+# Third Party
+import msgspec
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.native_completion import (
+    DeviceHostFuncDispatcher,
+    submit_callback_to_stream,
+)
+
+try:
+    # Third Party
+    import torch  # noqa: F401
+
+    _has_cuda = torch.cuda.is_available()
+except ImportError:
+    _has_cuda = False
+
+try:
+    # First Party
+    import lmcache.c_ops as lmc_ops
+
+    _has_native_op = hasattr(lmc_ops, "record_completion_on_stream")
+except ImportError:
+    lmc_ops = None
+    _has_native_op = False
+
+native_only = pytest.mark.skipif(
+    not (_has_cuda and _has_native_op),
+    reason="requires CUDA and native record_completion_on_stream",
+)
+
+if _has_cuda and _has_native_op:
+    # Third Party
+    import cupy  # noqa: E402
+
+
+@pytest.fixture()
+def stream():
+    s = cupy.cuda.Stream()
+    yield s
+    s.synchronize()
+
+
+@pytest.fixture()
+def dispatcher():
+    d = DeviceHostFuncDispatcher(drain_interval_seconds=0.001)
+    d.start()
+    yield d
+    d.stop()
+
+
+@native_only
+class TestRecordAndDrain:
+    """Low-level tests on lmc_ops.record_completion_on_stream / drain."""
+
+    def test_drain_empty(self):
+        completions = lmc_ops.drain_recorded_completions()
+        assert completions == []
+
+    def test_single_completion_payload_is_bytes(self, stream):
+        # drain must hand back py::bytes, not utf-8-decoded str — msgpack
+        # output is arbitrary bytes including invalid utf-8.
+        encoded = msgspec.msgpack.encode([b"key-1", b"key-2"])
+        lmc_ops.record_completion_on_stream(stream.ptr, "finish_write", encoded)
+        stream.synchronize()
+
+        completions = lmc_ops.drain_recorded_completions()
+        assert len(completions) == 1
+        kind, payload = completions[0]
+        assert kind == "finish_write"
+        assert isinstance(payload, bytes)
+        assert msgspec.msgpack.decode(payload, type=list[bytes]) == [
+            b"key-1",
+            b"key-2",
+        ]
+
+    def test_many_completions_in_order(self, stream):
+        for i in range(50):
+            lmc_ops.record_completion_on_stream(
+                stream.ptr, "finish_write", msgspec.msgpack.encode(i)
+            )
+        stream.synchronize()
+
+        completions = lmc_ops.drain_recorded_completions()
+        assert len(completions) == 50
+        for idx, (kind, payload) in enumerate(completions):
+            assert kind == "finish_write"
+            assert msgspec.msgpack.decode(payload, type=int) == idx
+
+
+@native_only
+class TestDispatcher:
+    """Integration tests for DeviceHostFuncDispatcher (drain + dispatch)."""
+
+    def test_dispatch_to_registered_handler(self, dispatcher, stream):
+        seen: list[list[bytes]] = []
+        dispatcher.register("finish_write", seen.append, payload_type=list[bytes])
+
+        submit_callback_to_stream(stream, "finish_write", [b"k0", b"k1", b"k2"])
+        stream.synchronize()
+
+        deadline = time.monotonic() + 5.0
+        while time.monotonic() < deadline and not seen:
+            time.sleep(0.01)
+        assert seen == [[b"k0", b"k1", b"k2"]]
+
+    def test_unknown_kind_drops_payload(self, dispatcher, stream):
+        submit_callback_to_stream(stream, "finish_unknown", [b"x"])
+        stream.synchronize()
+        time.sleep(0.1)
+        assert dispatcher.dispatched_count() == 0
+
+    def test_handler_exception_does_not_kill_thread(self, dispatcher, stream):
+        calls: list[list[bytes]] = []
+
+        def handler(payload):
+            calls.append(payload)
+            if len(calls) == 1:
+                raise RuntimeError("boom")
+
+        dispatcher.register("finish_write", handler, payload_type=list[bytes])
+        submit_callback_to_stream(stream, "finish_write", [b"a"])
+        submit_callback_to_stream(stream, "finish_write", [b"b"])
+        stream.synchronize()
+
+        deadline = time.monotonic() + 5.0
+        while time.monotonic() < deadline and len(calls) < 2:
+            time.sleep(0.01)
+        assert calls == [[b"a"], [b"b"]]
+        assert dispatcher.handler_exception_counts().get("finish_write", 0) == 1
+
+    def test_tuple_payload_for_multiple_arguments(self, dispatcher, stream):
+        # Multi-arg handlers: wrap args in a tuple, register tuple decode type.
+        seen: list[tuple[int, str]] = []
+        dispatcher.register("finish_multi", seen.append, payload_type=tuple[int, str])
+
+        submit_callback_to_stream(stream, "finish_multi", (42, "hello"))
+        stream.synchronize()
+
+        deadline = time.monotonic() + 5.0
+        while time.monotonic() < deadline and not seen:
+            time.sleep(0.01)
+        assert seen == [(42, "hello")]
+
+
+@native_only
+class TestDeadlockRegression:
+    """Regression for the GIL deadlock: the legacy
+    ``stream.launch_host_func(python_fn, ...)`` path stalls; the C++
+    callback runs without the GIL and must finish within the timeout."""
+
+    def test_many_concurrent_records_no_deadlock(self, dispatcher, stream):
+        received: list[int] = []
+        ready = threading.Event()
+
+        def handler(payload):
+            received.append(payload)
+            if len(received) >= 200:
+                ready.set()
+
+        dispatcher.register("finish_write", handler, payload_type=int)
+
+        for i in range(200):
+            submit_callback_to_stream(stream, "finish_write", i)
+        stream.synchronize()
+
+        assert ready.wait(timeout=10.0), (
+            f"deadlock or drop: only {len(received)} of 200 dispatched"
+        )
+        assert len(received) == 200
diff --git a/tests/v1/multiprocess/test_compute_mp_checksums.py b/tests/v1/multiprocess/test_compute_mp_checksums.py
new file mode 100644
index 0000000..8532889
--- /dev/null
+++ b/tests/v1/multiprocess/test_compute_mp_checksums.py
@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import hashlib
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.http_apis.cache_api import _compute_block_checksums
+
+
+def _make_5d_kv(
+    num_layers: int = 2,
+    kv_size: int = 2,
+    num_blocks: int = 4,
+    block_size: int = 4,
+    num_heads: int = 2,
+    head_size: int = 8,
+    dtype: torch.dtype = torch.float32,
+) -> list[torch.Tensor]:
+    """Create deterministic 5D CPU KV tensors: ``[kv, NB, BS, NH, HS]``.
+
+    Matches the ``NL_X_TWO_NB_BS_NH_HS`` layout (block_axis=1).
+    ``kv_size=1`` mimics the MLA-as-5D edge case.
+    """
+    torch.manual_seed(0)
+    return [
+        torch.randn(kv_size, num_blocks, block_size, num_heads, head_size, dtype=dtype)
+        for _ in range(num_layers)
+    ]
+
+
+def _make_3d_mla_kv(
+    num_layers: int = 2,
+    num_blocks: int = 4,
+    block_size: int = 4,
+    head_size: int = 8,
+    dtype: torch.dtype = torch.float32,
+) -> list[torch.Tensor]:
+    """Create MLA-style 3D CPU tensors: ``[NB, BS, HS]`` (block_axis=0)."""
+    torch.manual_seed(0)
+    return [
+        torch.randn(num_blocks, block_size, head_size, dtype=dtype)
+        for _ in range(num_layers)
+    ]
+
+
+class TestComputeBlockChecksums5DLayout:
+    """Checksum computation on the 5D ``[2, NB, BS, NH, HS]`` layout."""
+
+    def test_non_layerwise_shape(self):
+        kv = _make_5d_kv()
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2, 3],
+            block_axes=[1] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        assert result["status"] == "success"
+        assert result["layerwise"] is False
+        assert result["chunk_size"] == 2
+        assert result["num_chunks"] == 2
+        assert len(result["chunk_checksums"]) == 2
+
+    def test_layerwise_shape(self):
+        kv = _make_5d_kv(num_layers=3)
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2, 3],
+            block_axes=[1] * len(kv),
+            chunk_size=4,
+            layerwise=True,
+        )
+        assert result["layerwise"] is True
+        assert result["num_chunks"] == 1
+        per_layer = result["chunk_checksums"]
+        assert set(per_layer.keys()) == {"layer_0", "layer_1", "layer_2"}
+        for digests in per_layer.values():
+            assert len(digests) == 1
+
+    def test_partial_last_chunk(self):
+        kv = _make_5d_kv()
+        # 3 blocks with chunk_size=2 -> 2 chunks (2 + 1).
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2],
+            block_axes=[1] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        assert result["num_chunks"] == 2
+        assert len(result["chunk_checksums"]) == 2
+
+    def test_deterministic(self):
+        kv = _make_5d_kv()
+        args = dict(
+            block_ids=[0, 1], block_axes=[1] * len(kv), chunk_size=2, layerwise=False
+        )
+        r1 = _compute_block_checksums(kv, **args)
+        r2 = _compute_block_checksums(kv, **args)
+        assert r1["chunk_checksums"] == r2["chunk_checksums"]
+
+    def test_md5_hex_format(self):
+        kv = _make_5d_kv()
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1],
+            block_axes=[1] * len(kv),
+            chunk_size=1,
+            layerwise=False,
+        )
+        for digest in result["chunk_checksums"]:
+            assert len(digest) == 32
+            int(digest, 16)
+
+    def test_bfloat16_does_not_crash(self):
+        kv = _make_5d_kv(dtype=torch.bfloat16)
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2, 3],
+            block_axes=[1] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        assert result["status"] == "success"
+        assert len(result["chunk_checksums"]) == 2
+
+    def test_mla_as_5d_kv_size_one(self):
+        """5D layout with ``kv_size=1`` (MLA-in-5D) hashes cleanly."""
+        kv = _make_5d_kv(kv_size=1)
+        assert kv[0].shape[0] == 1
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2, 3],
+            block_axes=[1] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        assert result["status"] == "success"
+        assert len(result["chunk_checksums"]) == 2
+
+
+class TestComputeBlockChecksums3DMLA:
+    """Checksum computation on the native 3D MLA layout ``[NB, BS, HS]``."""
+
+    def test_non_layerwise_shape(self):
+        kv = _make_3d_mla_kv()
+        assert kv[0].ndim == 3
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2, 3],
+            block_axes=[0] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        assert result["status"] == "success"
+        assert result["num_chunks"] == 2
+
+    def test_layerwise_shape(self):
+        kv = _make_3d_mla_kv()
+        result = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1, 2, 3],
+            block_axes=[0] * len(kv),
+            chunk_size=2,
+            layerwise=True,
+        )
+        assert result["layerwise"] is True
+        assert set(result["chunk_checksums"].keys()) == {"layer_0", "layer_1"}
+
+    def test_matches_manual_md5(self):
+        """Full oracle: recompute MD5 by hand and compare."""
+        torch.manual_seed(42)
+        kv = [torch.randn(4, 2, 3, dtype=torch.float32)]
+        block_ids = [0, 2, 3]
+        chunk_size = 2
+        result = _compute_block_checksums(
+            kv,
+            block_ids=block_ids,
+            block_axes=[0] * len(kv),
+            chunk_size=chunk_size,
+            layerwise=False,
+        )
+        gathered = kv[0].index_select(0, torch.tensor(block_ids)).contiguous()
+        expected = []
+        for ci in range((len(block_ids) + chunk_size - 1) // chunk_size):
+            s = ci * chunk_size
+            e = min(s + chunk_size, len(block_ids))
+            chunk = gathered.narrow(0, s, e - s).contiguous()
+            md5 = hashlib.md5()
+            md5.update(chunk.numpy().tobytes())
+            expected.append(md5.hexdigest())
+        assert result["chunk_checksums"] == expected
+
+
+class TestBlockSelectionSemantics:
+    """The endpoint is block-addressed: duplicated / reordered block IDs
+    must visibly change the checksum, and selecting disjoint block sets
+    must yield different digests."""
+
+    def test_reordered_blocks_change_checksum(self):
+        kv = _make_3d_mla_kv()
+        r1 = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1],
+            block_axes=[0] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        r2 = _compute_block_checksums(
+            kv,
+            block_ids=[1, 0],
+            block_axes=[0] * len(kv),
+            chunk_size=2,
+            layerwise=False,
+        )
+        assert r1["chunk_checksums"] != r2["chunk_checksums"]
+
+    def test_different_block_sets_differ(self):
+        kv = _make_3d_mla_kv()
+        r_a = _compute_block_checksums(
+            kv,
+            block_ids=[0, 1],
+            block_axes=[0] * len(kv),
+            chunk_size=1,
+            layerwise=False,
+        )
+        r_b = _compute_block_checksums(
+            kv,
+            block_ids=[2, 3],
+            block_axes=[0] * len(kv),
+            chunk_size=1,
+            layerwise=False,
+        )
+        assert r_a["chunk_checksums"] != r_b["chunk_checksums"]
+
+    def test_out_of_range_block_axis_raises(self):
+        """A block axis out of range for the tensor ndim must bubble up
+        from ``index_select`` as ``IndexError``."""
+        kv = _make_3d_mla_kv()
+        with pytest.raises(IndexError):
+            _compute_block_checksums(
+                kv,
+                block_ids=[0],
+                block_axes=[9] * len(kv),
+                chunk_size=1,
+                layerwise=False,
+            )
diff --git a/tests/v1/multiprocess/test_config.py b/tests/v1/multiprocess/test_config.py
new file mode 100644
index 0000000..b3c98a6
--- /dev/null
+++ b/tests/v1/multiprocess/test_config.py
@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for multiprocess config parsing (coordinator registration).
+
+Covers CLI flags, ``LMCACHE_COORDINATOR_*`` env fallback, flag-over-env
+precedence, and heartbeat-interval validation. This module imports only the
+pure config layer (no native extensions), so it runs without a CUDA build.
+"""
+
+# Standard
+import argparse
+import uuid
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.config import (
+    CoordinatorConfig,
+    MPServerConfig,
+    add_coordinator_args,
+    add_mp_server_args,
+    parse_args_to_coordinator_config,
+    parse_args_to_mp_server_config,
+)
+
+_COORD_ENV = (
+    "LMCACHE_COORDINATOR_URL",
+    "LMCACHE_COORDINATOR_ADVERTISE_IP",
+    "LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL",
+)
+
+
+def _parse(argv: list[str]) -> CoordinatorConfig:
+    parser = argparse.ArgumentParser()
+    add_coordinator_args(parser)
+    return parse_args_to_coordinator_config(parser.parse_args(argv))
+
+
+@pytest.fixture(autouse=True)
+def _clear_coord_env(monkeypatch):
+    """Isolate each test from any coordinator env vars in the environment."""
+    for name in _COORD_ENV:
+        monkeypatch.delenv(name, raising=False)
+
+
+def test_defaults_disable_registration():
+    config = _parse([])
+    assert config.url == ""  # empty url => registration disabled
+    assert config.advertise_ip == ""
+    assert config.heartbeat_interval == 5.0
+
+
+def test_flags_are_parsed():
+    config = _parse(
+        [
+            "--coordinator-url",
+            "http://coord:9300",
+            "--coordinator-advertise-ip",
+            "10.0.0.5",
+            "--coordinator-heartbeat-interval",
+            "2.5",
+        ]
+    )
+    assert config.url == "http://coord:9300"
+    assert config.advertise_ip == "10.0.0.5"
+    assert config.heartbeat_interval == 2.5
+
+
+def test_env_fallback(monkeypatch):
+    monkeypatch.setenv("LMCACHE_COORDINATOR_URL", "http://env-coord:9300")
+    monkeypatch.setenv("LMCACHE_COORDINATOR_ADVERTISE_IP", "192.168.1.2")
+    monkeypatch.setenv("LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL", "3")
+    config = _parse([])
+    assert config.url == "http://env-coord:9300"
+    assert config.advertise_ip == "192.168.1.2"
+    assert config.heartbeat_interval == 3.0
+
+
+def test_flag_beats_env(monkeypatch):
+    monkeypatch.setenv("LMCACHE_COORDINATOR_URL", "http://env-coord:9300")
+    config = _parse(["--coordinator-url", "http://flag-coord:9300"])
+    assert config.url == "http://flag-coord:9300"
+
+
+@pytest.mark.parametrize("interval", ["0", "-1", "nan", "inf"])
+def test_invalid_heartbeat_rejected(interval):
+    # Non-positive and non-finite (nan/inf) values are all rejected.
+    with pytest.raises(ValueError, match="finite number > 0"):
+        _parse(["--coordinator-heartbeat-interval", interval])
+
+
+@pytest.mark.parametrize("interval", ["nan", "inf"])
+def test_invalid_heartbeat_from_env_rejected(monkeypatch, interval):
+    monkeypatch.setenv("LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL", interval)
+    with pytest.raises(ValueError, match="finite number > 0"):
+        _parse([])
+
+
+def test_garbage_env_heartbeat_rejected(monkeypatch):
+    monkeypatch.setenv("LMCACHE_COORDINATOR_HEARTBEAT_INTERVAL", "abc")
+    with pytest.raises(ValueError, match="not a number"):
+        _parse([])
+
+
+def _parse_mp(argv: list[str]) -> MPServerConfig:
+    parser = argparse.ArgumentParser()
+    add_mp_server_args(parser)
+    return parse_args_to_mp_server_config(parser.parse_args(argv))
+
+
+def test_instance_id_defaults_to_uuid4():
+    # No --instance-id flag => a random UUID v4 is minted.
+    config = _parse_mp([])
+    assert uuid.UUID(config.instance_id).version == 4
+
+
+def test_instance_id_flag_is_preserved():
+    config = _parse_mp(["--instance-id", "mp-server-7"])
+    assert config.instance_id == "mp-server-7"
+
+
+def test_instance_id_defaults_are_distinct():
+    # Each parse without the flag gets its own id (no shared default).
+    assert _parse_mp([]).instance_id != _parse_mp([]).instance_id
+
+
+def test_instance_id_dataclass_default_is_distinct():
+    # Direct construction (no CLI) also mints a fresh id per instance.
+    assert MPServerConfig().instance_id != MPServerConfig().instance_id
diff --git a/tests/v1/multiprocess/test_custom_types.py b/tests/v1/multiprocess/test_custom_types.py
new file mode 100644
index 0000000..dba5084
--- /dev/null
+++ b/tests/v1/multiprocess/test_custom_types.py
@@ -0,0 +1,367 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from multiprocessing import Queue
+import multiprocessing as mp
+
+# Third Party
+import msgspec
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import (
+    BlockAllocationRecord,
+    IPCCacheServerKey,
+    get_customized_decoder,
+    get_customized_encoder,
+)
+from lmcache.v1.platform.cuda.ipc_wrapper import CudaIPCWrapper
+
+
+def test_ipc_cache_engine_key_serialization():
+    """Test encoding and decoding of IPCCacheServerKey using msgspec."""
+    # Create a sample IPCCacheServerKey
+    original_key = IPCCacheServerKey.from_token_ids(
+        model_name="test_model",
+        world_size=4,
+        worker_id=1,
+        token_ids=list(range(256)),
+        start=0,
+        end=256,
+        request_id="test_request",
+    )
+
+    # Encode the key
+    encoded = msgspec.msgpack.encode(original_key)
+
+    # Decode the key
+    decoded_key = msgspec.msgpack.decode(encoded, type=IPCCacheServerKey)
+
+    # Verify correctness
+    assert original_key == decoded_key, "IPCCacheServerKeys do not match!"
+
+
+def test_ipc_cache_engine_key_serialization_with_cache_salt():
+    """Roundtrip must carry ``cache_salt`` verbatim — it is part of
+    cache identity so eq must hold after encode/decode."""
+    original_key = IPCCacheServerKey.from_token_ids(
+        model_name="test_model",
+        world_size=4,
+        worker_id=1,
+        token_ids=list(range(256)),
+        start=0,
+        end=256,
+        request_id="test_request",
+        cache_salt="alice",
+    )
+
+    encoded = msgspec.msgpack.encode(original_key)
+    decoded_key = msgspec.msgpack.decode(encoded, type=IPCCacheServerKey)
+
+    assert original_key == decoded_key
+    assert decoded_key.cache_salt == "alice"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CudaIPCWrapper tests",
+)
+def test_cudaipc_wrapper_serialization():
+    """Test custom encoder/decoder for single CudaIPCWrapper object."""
+    encoder = get_customized_encoder(type=CudaIPCWrapper)
+    decoder = get_customized_decoder(type=CudaIPCWrapper)
+
+    # Create a sample tensor
+    original_tensor = torch.randn(3, 4, device="cuda")
+    wrapper = CudaIPCWrapper(original_tensor)
+
+    # Encode the wrapper
+    encoded = encoder.encode(wrapper)
+
+    # Decode the wrapper
+    decoded_wrapper = decoder.decode(encoded)
+    assert isinstance(decoded_wrapper, CudaIPCWrapper), (
+        "Decoded object is not of type CudaIPCWrapper"
+    )
+    assert decoded_wrapper == wrapper, (
+        "Decoded CudaIPCWrapper does not match the original"
+    )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CudaIPCWrapper tests",
+)
+def test_cudaipc_wrapper_list_serialization():
+    """Test custom encoder/decoder for list of CudaIPCWrapper objects."""
+    wrappers = []
+    for _ in range(5):
+        tensor = torch.randn(2, 2, device="cuda")
+        wrapper = CudaIPCWrapper(tensor)
+        wrappers.append(wrapper)
+
+    encoder = get_customized_encoder(type=list[CudaIPCWrapper])
+    decoder = get_customized_decoder(type=list[CudaIPCWrapper])
+
+    # Encode the list of wrappers
+    encoded = encoder.encode(wrappers)
+
+    # Decode the list of wrappers
+    decoded_wrappers = decoder.decode(encoded)
+
+    assert len(decoded_wrappers) == len(wrappers), (
+        "Decoded list length does not match original"
+    )
+
+    for original, decoded in zip(wrappers, decoded_wrappers, strict=False):
+        assert original == decoded, "Decoded CudaIPCWrapper does not match the original"
+
+
+def _worker_process_deserialize_and_reconstruct(
+    encoded_data: bytes, result_queue: Queue
+):
+    """
+    Worker function that runs in a separate process.
+    Deserializes CudaIPCWrapper list and reconstructs tensors.
+    """
+    try:
+        # Decode the list of wrappers
+        torch.cuda.init()
+        decoder = get_customized_decoder(type=list[CudaIPCWrapper])
+        decoded_wrappers = decoder.decode(encoded_data)
+
+        # Convert each wrapper back to tensor and compute checksum
+        checksums = []
+        shapes = []
+        for wrapper in decoded_wrappers:
+            tensor = wrapper.to_tensor()
+            # Compute checksum as sum of all elements
+            checksum = float(tensor.sum().cpu().item())
+            checksums.append(checksum)
+            shapes.append(list(tensor.shape))
+
+            # Do add 1 on the tensor to ensure it's writable
+            tensor.add_(1)
+
+        result_queue.put(("success", checksums, shapes))
+    except Exception as e:
+        result_queue.put(("error", str(e), None))
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CudaIPCWrapper multiprocessing tests",
+)
+def test_cudaipc_wrapper_multiprocess_serialization():
+    """
+    Test CudaIPCWrapper serialization across processes using spawn method.
+    This verifies that CUDA IPC handles can be properly shared between processes.
+    """
+    # Set multiprocessing start method to spawn
+    ctx = mp.get_context("spawn")
+
+    # Create test tensors and wrappers in the main process
+    num_tensors = 3
+    tensors = []
+    test_data = []
+    wrappers = []
+
+    for i in range(num_tensors):
+        # Create a tensor with known values
+        tensor = torch.full(
+            (2, 3), fill_value=float(i + 1), dtype=torch.float32, device="cuda"
+        )
+        tensors.append(tensor)
+        wrapper = CudaIPCWrapper(tensor)
+        wrappers.append(wrapper)
+
+        # Store expected checksum and shape
+        expected_checksum = float(tensor.sum().cpu().item())
+        expected_shape = list(tensor.shape)
+        test_data.append((expected_checksum, expected_shape))
+
+    # Serialize the wrappers
+    encoder = get_customized_encoder(type=list[CudaIPCWrapper])
+    encoded_data = encoder.encode(wrappers)
+
+    # Create a queue for results
+    result_queue = ctx.Queue()
+
+    # Start worker process
+    process = ctx.Process(
+        target=_worker_process_deserialize_and_reconstruct,
+        args=(encoded_data, result_queue),
+    )
+    process.start()
+
+    # Wait for result with timeout
+    process.join(timeout=10)
+
+    # Check if process completed successfully
+    if process.is_alive():
+        process.terminate()
+        process.join()
+        pytest.fail("Worker process timed out")
+
+    assert process.exitcode == 0, (
+        f"Worker process failed with exit code {process.exitcode}"
+    )
+
+    # Get result from queue
+    assert not result_queue.empty(), "No result received from worker process"
+    status, checksums, shapes = result_queue.get()
+
+    assert status == "success", f"Worker process encountered error: {checksums}"
+    assert len(checksums) == num_tensors, "Number of checksums does not match"
+    assert len(shapes) == num_tensors, "Number of shapes does not match"
+
+    # Verify checksums and shapes match
+    for i, (
+        (expected_checksum, expected_shape),
+        actual_checksum,
+        actual_shape,
+    ) in enumerate(zip(test_data, checksums, shapes, strict=False)):
+        assert actual_shape == expected_shape, (
+            f"Tensor {i}: shape mismatch. Expected {expected_shape}, got {actual_shape}"
+        )
+        assert abs(actual_checksum - expected_checksum) < 1e-5, (
+            f"Tensor {i}: checksum mismatch. Expected {expected_checksum}, "
+            f"got {actual_checksum}"
+        )
+
+    # Verify that the tensors are being modified in the worker process
+    for i, (tensor, (expected_checksum, _)) in enumerate(
+        zip(tensors, test_data, strict=False)
+    ):
+        # After adding 1 to each element, the new checksum should be:
+        num_elements = tensor.numel()
+        new_expected_checksum = expected_checksum + float(num_elements)
+        actual_checksum = float(tensor.sum().cpu().item())
+        assert abs(actual_checksum - new_expected_checksum) < 1e-5, (
+            f"Tensor {i}: post-modification checksum mismatch. "
+            f"Expected {new_expected_checksum}, got {actual_checksum}"
+        )
+
+
+def _worker_reconstruct_offset_tensor(encoded_data: bytes, result_queue: Queue):
+    """Worker: decode a single CudaIPCWrapper and reconstruct its tensor,
+    reporting the layout metadata and a checksum back to the parent."""
+    try:
+        torch.cuda.init()
+        decoder = get_customized_decoder(type=CudaIPCWrapper)
+        wrapper = decoder.decode(encoded_data)
+        tensor = wrapper.to_tensor()
+        result_queue.put(
+            (
+                "success",
+                int(tensor.storage_offset()),
+                list(tensor.shape),
+                list(tensor.stride()),
+                float(tensor.sum().cpu().item()),
+            )
+        )
+    except Exception as e:
+        result_queue.put(("error", str(e), None, None, None))
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CudaIPCWrapper tests",
+)
+def test_cudaipc_wrapper_nonzero_storage_offset():
+    """CudaIPCWrapper must round-trip a slice/narrow view with
+    ``storage_offset > 0`` bit-identically across processes.
+
+    This is the property PR #3853 relies on: with MTP speculative decoding +
+    CPU offload, per-layer KV are non-zero-``storage_offset`` slices of a
+    unified pool, so ``_validate_dim0_padded_layout`` must accept them. The
+    view here is both dim-0-padded (``stride[0] > prod(shape[1:])``) and
+    offset-shifted, exactly that shape. ``CudaIPCWrapper`` encodes
+    ``storage_offset`` and the receiver rebuilds the view via
+    ``set_(storage, storage_offset, shape, stride)``; this verifies the
+    reconstructed tensor reads from the correct (offset, strided) region.
+    """
+    ctx = mp.get_context("spawn")
+
+    # arange so each element's value equals its flat storage index -- the
+    # checksum then pins down exactly which storage positions were read.
+    base = torch.arange(64, dtype=torch.float32, device="cuda")
+    # dim-0-padded view: shape (3, 2, 4), per-block stride 12 > prod(shape[1:])=8
+    # (4 elements of padding per block), shifted by storage_offset=8.
+    view = base.as_strided((3, 2, 4), (12, 4, 1), storage_offset=8)
+    assert view.storage_offset() == 8
+    assert not view.is_contiguous()
+
+    wrapper = CudaIPCWrapper(view)
+    assert wrapper.storage_offset == view.storage_offset()
+    assert wrapper.shape == tuple(view.shape)
+    assert wrapper.stride == tuple(view.stride())
+
+    encoder = get_customized_encoder(type=CudaIPCWrapper)
+    encoded = encoder.encode(wrapper)
+
+    result_queue = ctx.Queue()
+    process = ctx.Process(
+        target=_worker_reconstruct_offset_tensor,
+        args=(encoded, result_queue),
+    )
+    process.start()
+    process.join(timeout=10)
+
+    if process.is_alive():
+        process.terminate()
+        process.join()
+        pytest.fail("Worker process timed out")
+    assert process.exitcode == 0, (
+        f"Worker process failed with exit code {process.exitcode}"
+    )
+    assert not result_queue.empty(), "No result received from worker process"
+
+    status, offset, shape, stride, checksum = result_queue.get()
+    assert status == "success", f"Worker process encountered error: {offset}"
+    assert offset == view.storage_offset()
+    assert shape == list(view.shape)
+    assert stride == list(view.stride())
+    assert abs(checksum - float(view.sum().cpu().item())) < 1e-5
+
+
+def test_block_allocation_record_serialization():
+    """Test encoding and decoding of BlockAllocationRecord using msgspec."""
+    original = BlockAllocationRecord(
+        req_id="req-42",
+        new_block_ids=[10, 20, 30],
+        new_token_ids=[100, 200, 300, 400],
+    )
+
+    encoded = msgspec.msgpack.encode(original)
+    decoded = msgspec.msgpack.decode(encoded, type=BlockAllocationRecord)
+
+    assert decoded.req_id == original.req_id
+    assert decoded.new_block_ids == original.new_block_ids
+    assert decoded.new_token_ids == original.new_token_ids
+
+
+def test_block_allocation_record_list_serialization():
+    """Test encoding and decoding of a list of BlockAllocationRecord."""
+    records = [
+        BlockAllocationRecord(
+            req_id="req-1",
+            new_block_ids=[1, 2],
+            new_token_ids=[10, 20, 30],
+        ),
+        BlockAllocationRecord(
+            req_id="req-2",
+            new_block_ids=[],
+            new_token_ids=[40, 50],
+        ),
+    ]
+
+    encoded = msgspec.msgpack.encode(records)
+    decoded = msgspec.msgpack.decode(encoded, type=list[BlockAllocationRecord])
+
+    assert len(decoded) == 2
+    assert decoded[0].req_id == "req-1"
+    assert decoded[0].new_block_ids == [1, 2]
+    assert decoded[1].req_id == "req-2"
+    assert decoded[1].new_block_ids == []
+    assert decoded[1].new_token_ids == [40, 50]
diff --git a/tests/v1/multiprocess/test_engine_driven_transfer.py b/tests/v1/multiprocess/test_engine_driven_transfer.py
new file mode 100644
index 0000000..2d07b3d
--- /dev/null
+++ b/tests/v1/multiprocess/test_engine_driven_transfer.py
@@ -0,0 +1,1573 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Callable, Protocol
+from unittest.mock import MagicMock, patch
+import os
+import pickle
+import sys
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache import torch_dev, torch_device_type
+from lmcache.v1.distributed.api import MemoryLayoutDesc
+from lmcache.v1.multiprocess.posix_shm import (
+    shm_create_readwrite,
+    shm_munmap,
+    shm_open_pool_as_mmap,
+    shm_unlink,
+)
+from lmcache.v1.multiprocess.protocol import RequestType
+from lmcache.v1.multiprocess.protocols.engine import (
+    PrepareRetrieveResponse,
+    PrepareStoreResponse,
+    RegisterEngineDrivenContextResponse,
+)
+from lmcache.v1.multiprocess.transfer_context.base import (
+    EngineDrivenContextMetadata,
+    create_engine_driven_context,
+)
+from lmcache.v1.multiprocess.transfer_context.pickle import EngineDrivenContextPickle
+from lmcache.v1.multiprocess.transfer_context.shm import EngineDrivenContextShm
+
+if TYPE_CHECKING:
+    # First Party
+    from lmcache.v1.distributed.config import StorageManagerConfig
+    from lmcache.v1.gpu_connector.utils import LayoutHints
+    from lmcache.v1.multiprocess.custom_types import (
+        IPCCacheServerKey,
+        RegisterEngineDrivenContextPayload,
+    )
+    from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+    from lmcache.v1.multiprocess.modules.engine_driven_transfer import (
+        EngineDrivenTransferModule,
+    )
+
+
+class ServerModuleFactory(Protocol):
+    """Typed callable contract for creating patched server test modules.
+
+    Args:
+        storage_manager_config: Optional engine storage config override.
+        chunk_size: Engine chunk size used to initialize the context.
+        object_keys: Object keys returned by ``ipc_key_to_object_keys``.
+        mock_storage: Optional storage mock; defaults to a new ``MagicMock``.
+        mock_session: Optional session mock; defaults to a new ``MagicMock``.
+
+    Returns a tuple of ``(EngineDrivenTransferModule, storage MagicMock,
+    session MagicMock, MPCacheServerContext)``.
+    """
+
+    def __call__(
+        self,
+        *,
+        storage_manager_config: "StorageManagerConfig | None" = None,
+        chunk_size: int = 8,
+        object_keys: list[str] | None = None,
+        mock_storage: MagicMock | None = None,
+        mock_session: MagicMock | None = None,
+    ) -> tuple[
+        "EngineDrivenTransferModule", MagicMock, MagicMock, "MPCacheServerContext"
+    ]: ...
+
+
+def _make_kv_caches(
+    num_layers: int = 2,
+    num_blocks: int = 6,
+    block_size: int = 4,
+    num_heads: int = 2,
+    head_size: int = 8,
+) -> dict[str, torch.Tensor]:
+    """Build per-layer NHD KV tensors for non-CUDA data transfer tests."""
+    kv_caches = {}
+    for i in range(num_layers):
+        kv_caches[f"layer_{i}"] = torch.randn(
+            2, num_blocks, block_size, num_heads, head_size
+        )
+    return kv_caches
+
+
+def _make_mla_kv_caches(
+    num_layers: int = 2,
+    num_blocks: int = 6,
+    block_size: int = 4,
+    hidden_size: int = 16,
+) -> dict[str, torch.Tensor]:
+    """Build per-layer MLA KV tensors for non-CUDA data transfer tests.
+
+    Args:
+        num_layers: Number of KV layers to generate.
+        num_blocks: Number of paged blocks per layer.
+        block_size: Number of tokens per block.
+        hidden_size: Hidden size per token.
+
+    Returns:
+        Mapping from layer name to MLA KV tensor with shape
+        ``[num_blocks, block_size, hidden_size]``.
+    """
+    kv_caches = {}
+    for i in range(num_layers):
+        kv_caches[f"layer_{i}"] = torch.randn(num_blocks, block_size, hidden_size)
+    return kv_caches
+
+
+def _make_hnd_kv_caches(
+    num_layers: int = 2,
+    num_blocks: int = 6,
+    block_size: int = 4,
+    num_heads: int = 2,
+    head_size: int = 8,
+) -> dict[str, torch.Tensor]:
+    """Build per-layer HND KV tensors for non-CUDA data transfer tests."""
+    kv_caches = {}
+    for i in range(num_layers):
+        kv_caches[f"layer_{i}"] = torch.randn(
+            2, num_blocks, num_heads, block_size, head_size
+        )
+    return kv_caches
+
+
+def _make_hnd_flashinfer_kv_caches(
+    num_layers: int = 2,
+    num_blocks: int = 6,
+    block_size: int = 4,
+    num_heads: int = 2,
+    head_size: int = 8,
+) -> dict[str, torch.Tensor]:
+    """Build per-layer HND flash-infer KV tensors for non-CUDA data transfer tests."""
+    kv_caches = {}
+    for i in range(num_layers):
+        kv_caches[f"layer_{i}"] = torch.randn(
+            num_blocks, 2, num_heads, block_size, head_size
+        )
+    return kv_caches
+
+
+def _make_storage_manager_config(
+    *,
+    shm_name: str = "",
+    pool_size: int = 4096,
+    use_lazy: bool = False,
+) -> Any:
+    """Build a StorageManagerConfig for multiprocess engine-context tests."""
+    # First Party
+    from lmcache.v1.distributed.config import (
+        EvictionConfig,
+        L1ManagerConfig,
+        L1MemoryManagerConfig,
+        StorageManagerConfig,
+    )
+
+    return StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=pool_size,
+                use_lazy=use_lazy,
+                shm_name=shm_name,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+
+
+def _default_register_payload(
+    instance_id: int = 1,
+) -> "RegisterEngineDrivenContextPayload":
+    """Build a default non-GPU registration payload for server-side tests.
+
+    Args:
+        instance_id: Worker instance id to register. Defaults to ``1``.
+
+    Uses fixed values ``model_name="m"``, ``world_size=1``, ``block_size=4``,
+    ``num_layers=2``, ``hidden_dim_size=16``, ``dtype_str="float32"``, and
+    ``use_mla=False`` for a compact baseline scenario used by most tests.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.custom_types import RegisterEngineDrivenContextPayload
+
+    return RegisterEngineDrivenContextPayload(
+        instance_id=instance_id,
+        model_name="m",
+        world_size=1,
+        block_size=4,
+        num_layers=2,
+        hidden_dim_size=16,
+        dtype_str="float32",
+        use_mla=False,
+    )
+
+
+def _default_key(tokens: int = 8) -> "IPCCacheServerKey":
+    """Build a default IPC cache key with ``tokens`` contiguous token IDs.
+
+    Args:
+        tokens: Total token count and key end offset. Defaults to ``8``.
+
+    Uses fixed values ``model_name="m"``, ``world_size=1``, ``rank=0``,
+    token IDs of ``[1] * tokens``, ``start=0``, ``end=tokens``,
+    and ``request_id="req"``.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+
+    return IPCCacheServerKey.from_token_ids(
+        "m",
+        1,
+        0,
+        [1] * tokens,
+        start=0,
+        end=tokens,
+        request_id="req",
+    )
+
+
+def test_wrap_kv_caches_wraps_all_tensors() -> None:
+    """Verify wrap_kv_caches wraps all provided KV tensors."""
+    # First Party
+    from lmcache.integration.vllm import vllm_multi_process_adapter as adapter_mod
+    from lmcache.v1.platform import _registry as platform_registry
+
+    kv_caches = _make_kv_caches()
+    # ``wrap_kv_caches`` dispatches through ``platform_registry``: each
+    # accelerator self-registers a wrapper factory keyed by
+    # ``tensor.device.type``. Override the relevant entries through the
+    # registry's documented API (snapshot + register + restore on
+    # teardown) instead of poking the adapter's private helper.
+    saved = platform_registry.snapshot()
+
+    def _fake_factory(tensor: Any) -> tuple[str, Any]:
+        return ("wrapped", tensor)
+
+    try:
+        for device_type in {t.device.type for t in kv_caches.values()}:
+            platform_registry.register_kv_wrapper(device_type, _fake_factory)
+        wrapped = adapter_mod.wrap_kv_caches(kv_caches)
+    finally:
+        platform_registry.restore(saved)
+
+    assert len(wrapped) == len(kv_caches)
+
+
+def test_create_transfer_context_uses_non_cuda_context_on_cpu() -> None:
+    """Ensure factory returns EngineDrivenTransferContext for CPU KV."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.worker_transfer import (
+        EngineDrivenTransferContext,
+        create_transfer_context,
+    )
+
+    context = create_transfer_context({"layer_0": torch.randn(2, 2)})
+    assert isinstance(context, EngineDrivenTransferContext)
+
+
+def test_resolve_extra_config_default_mp_transfer_mode_is_auto() -> None:
+    """Without override the resolved mp_transfer_mode must be ``auto``."""
+    # First Party
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        ExtraConfigDefault,
+        _resolve_extra_config,
+    )
+
+    cfg = _resolve_extra_config(None)
+    assert cfg[ExtraConfigDefault.mp_transfer_mode.name] == "auto"
+
+
+def test_resolve_extra_config_overrides_mp_transfer_mode() -> None:
+    """``lmcache.mp.mp_transfer_mode`` override flows through unchanged."""
+    # First Party
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        ExtraConfigDefault,
+        _resolve_extra_config,
+    )
+
+    cfg = _resolve_extra_config({"lmcache.mp.mp_transfer_mode": "lmcache_driven"})
+    assert cfg[ExtraConfigDefault.mp_transfer_mode.name] == "lmcache_driven"
+
+
+def test_extra_config_default_lets_env_var_select_mp_transfer_mode(
+    monkeypatch: Any,
+) -> None:
+    """When extra_config omits mp_transfer_mode, env var must still win.
+
+    The adapter detects the absence of ``lmcache.mp.mp_transfer_mode`` and
+    passes ``mode=None`` to ``create_transfer_context``, which then reads
+    the ``LMCACHE_MP_TRANSFER_MODE`` env var. Regression test for
+    buildkite k3-multiprocess CI ``cpu_e2e_validation (server-side copy)``.
+    """
+    # First Party
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        _EXTRA_CONFIG_KEY_PREFIX,
+        ExtraConfigDefault,
+    )
+    from lmcache.v1.multiprocess.transfer_context import (
+        EngineDrivenTransferContext,
+        create_transfer_context,
+    )
+    from lmcache.v1.multiprocess.transfer_context.worker_transfer import (
+        ENV_MP_TRANSFER_MODE,
+    )
+
+    mp_mode_key = _EXTRA_CONFIG_KEY_PREFIX + ExtraConfigDefault.mp_transfer_mode.name
+    # Simulate adapter init: extra_config omits the mp_transfer_mode key.
+    extra_config: dict[str, Any] = {"lmcache.mp.mq_timeout": "1"}
+    resolved_mode = extra_config[mp_mode_key] if mp_mode_key in extra_config else None
+    assert resolved_mode is None
+
+    # With env=engine_driven and mode=None, CPU KV must pick
+    # EngineDrivenTransferContext.
+    monkeypatch.setenv(ENV_MP_TRANSFER_MODE, "engine_driven")
+    context = create_transfer_context(
+        {"layer_0": torch.randn(2, 2)}, mode=resolved_mode
+    )
+    assert isinstance(context, EngineDrivenTransferContext)
+
+
+def test_create_transfer_context_force_lmcache_driven_mode() -> None:
+    """``mode='lmcache_driven'`` must always pick
+    LMCacheDrivenTransferContext (handle path); CPU also works because the
+    CPU SHM wrapper factory is registered on import."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        LMCacheDrivenTransferContext,
+        MPTransferMode,
+        create_transfer_context,
+    )
+
+    # Importing the CPU sub-package self-registers its KV-wrapper factory.
+    import lmcache.v1.platform.cpu  # noqa: F401
+
+    context = create_transfer_context(
+        {"layer_0": torch.randn(2, 2)}, mode=MPTransferMode.LMCACHE_DRIVEN
+    )
+    assert isinstance(context, LMCacheDrivenTransferContext)
+
+
+def test_create_transfer_context_force_engine_driven_mode_on_cpu() -> None:
+    """``mode='engine_driven'`` on CPU returns EngineDrivenTransferContext
+    (data path; no wrapper-factory capability check is performed)."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        EngineDrivenTransferContext,
+        create_transfer_context,
+    )
+
+    context = create_transfer_context(
+        {"layer_0": torch.randn(2, 2)}, mode="engine_driven"
+    )
+    assert isinstance(context, EngineDrivenTransferContext)
+
+
+def test_create_transfer_context_invalid_mode_raises() -> None:
+    """Unknown mode strings must raise a clear ValueError."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import create_transfer_context
+
+    with pytest.raises(ValueError, match="Invalid MP transfer mode"):
+        create_transfer_context({"layer_0": torch.randn(2, 2)}, mode="bogus")
+
+
+def test_create_transfer_context_handle_mode_unsupported_device_raises(
+    monkeypatch: Any,
+) -> None:
+    """``mode='lmcache_driven'`` must raise when no wrapper factory exists
+    for the device."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import create_transfer_context
+    from lmcache.v1.platform import _registry as platform_registry
+
+    snapshot = platform_registry.snapshot()
+    try:
+        # Drop every registered factory so 'cpu' can never be resolved.
+        # Pass ``discovered=True`` so the lazy discovery pass does not
+        # immediately re-register the auto-discovered backends and
+        # defeat the empty-table fixture.
+        platform_registry.restore(
+            {"kv_wrapper": {}, "availability": {}, "discovered": True}
+        )
+        with pytest.raises(ValueError, match="not supported for device type"):
+            create_transfer_context(
+                {"layer_0": torch.randn(2, 2)}, mode="lmcache_driven"
+            )
+    finally:
+        platform_registry.restore(snapshot)
+
+
+def test_musa_data_context_keeps_layout_validation_device_agnostic(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """MUSA MP data path must not put device layout gates in transfer context."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        EngineDrivenTransferContext,
+        worker_transfer,
+    )
+    import lmcache.c_ops as lmc_ops
+
+    def _fake_compute_kv_layout(
+        *_args: Any, **_kwargs: Any
+    ) -> tuple[int, int, int, str, Any]:
+        return (
+            4,
+            2,
+            16,
+            "float32",
+            lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,
+        )
+
+    monkeypatch.setattr(worker_transfer, "compute_kv_layout", _fake_compute_kv_layout)
+    monkeypatch.setattr(
+        worker_transfer,
+        "create_engine_driven_context",
+        lambda *_args, **_kwargs: MagicMock(),
+    )
+    future = MagicMock()
+    future.result.return_value = RegisterEngineDrivenContextResponse()
+    ctx = EngineDrivenTransferContext()
+
+    ctx.register(
+        instance_id=1,
+        kv_caches=_make_hnd_kv_caches(),
+        model_name="m",
+        world_size=1,
+        blocks_in_chunk=2,
+        mq_client=MagicMock(),
+        mq_timeout=1.0,
+        send_request=MagicMock(return_value=future),
+    )
+
+
+def test_musa_data_context_store_uses_device_agnostic_gather(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Stage3 store keeps MUSA native details behind block-transfer entry."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        EngineDrivenTransferContext,
+        worker_transfer,
+    )
+    import lmcache.c_ops as lmc_ops
+
+    class _FakeEngineDrivenContext:
+        def prepare_store(self, *_args: Any, **_kwargs: Any) -> None:
+            return None
+
+        def commit_store(self, *_args: Any, **_kwargs: Any) -> bool:
+            return True
+
+        def close(self) -> None:
+            return None
+
+    captured_kwargs: dict[str, Any] = {}
+    future = MagicMock()
+    future.result.return_value = RegisterEngineDrivenContextResponse()
+    monkeypatch.setattr(
+        worker_transfer,
+        "compute_kv_layout",
+        lambda *_args, **_kwargs: (
+            4,
+            2,
+            16,
+            "float32",
+            lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        ),
+    )
+    monkeypatch.setattr(
+        worker_transfer,
+        "create_engine_driven_context",
+        lambda *_args, **_kwargs: _FakeEngineDrivenContext(),
+    )
+
+    def _fake_gather(*_args: Any, **kwargs: Any) -> list[torch.Tensor]:
+        captured_kwargs.update(kwargs)
+        return [torch.zeros(2, 2, 8, 16)]
+
+    monkeypatch.setattr(worker_transfer, "gather_paged_kv_to_cpu", _fake_gather)
+    ctx = EngineDrivenTransferContext()
+    ctx.register(
+        instance_id=1,
+        kv_caches=_make_kv_caches(),
+        model_name="m",
+        world_size=1,
+        blocks_in_chunk=2,
+        mq_client=MagicMock(),
+        mq_timeout=1.0,
+        send_request=MagicMock(return_value=future),
+    )
+
+    result = ctx.submit_store(
+        "req",
+        _default_key(),
+        1,
+        _make_kv_caches(),
+        [[0, 1]],
+        MagicMock(),
+        2,
+    ).result()
+
+    assert result is True
+    assert "prefer_musa_native" not in captured_kwargs
+
+
+def test_musa_data_context_retrieve_uses_device_agnostic_scatter(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Stage3 retrieve keeps MUSA native details behind block-transfer entry."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        EngineDrivenTransferContext,
+        worker_transfer,
+    )
+    import lmcache.c_ops as lmc_ops
+
+    class _FakeEngineDrivenContext:
+        def prepare_retrieve(self, *_args: Any, **_kwargs: Any) -> list[torch.Tensor]:
+            return [torch.zeros(2, 2, 8, 16)]
+
+        def commit_retrieve(self, *_args: Any, **_kwargs: Any) -> bool:
+            return True
+
+        def close(self) -> None:
+            return None
+
+    captured_kwargs: dict[str, Any] = {}
+    future = MagicMock()
+    future.result.return_value = RegisterEngineDrivenContextResponse()
+    monkeypatch.setattr(
+        worker_transfer,
+        "compute_kv_layout",
+        lambda *_args, **_kwargs: (
+            4,
+            2,
+            16,
+            "float32",
+            lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        ),
+    )
+    monkeypatch.setattr(
+        worker_transfer,
+        "create_engine_driven_context",
+        lambda *_args, **_kwargs: _FakeEngineDrivenContext(),
+    )
+
+    def _fake_scatter(*_args: Any, **kwargs: Any) -> None:
+        captured_kwargs.update(kwargs)
+
+    monkeypatch.setattr(worker_transfer, "scatter_cpu_to_paged_kv", _fake_scatter)
+    ctx = EngineDrivenTransferContext()
+    ctx.register(
+        instance_id=1,
+        kv_caches=_make_kv_caches(),
+        model_name="m",
+        world_size=1,
+        blocks_in_chunk=2,
+        mq_client=MagicMock(),
+        mq_timeout=1.0,
+        send_request=MagicMock(return_value=future),
+    )
+
+    result = ctx.submit_retrieve(
+        "req",
+        _default_key(),
+        1,
+        _make_kv_caches(),
+        [[0, 1]],
+        MagicMock(),
+        2,
+    ).result()
+
+    assert result is True
+    assert "prefer_musa_native" not in captured_kwargs
+
+
+def test_create_transfer_context_env_var_overrides_default(
+    monkeypatch: Any,
+) -> None:
+    """``LMCACHE_MP_TRANSFER_MODE=lmcache_driven`` must force the
+    LMCache-driven path."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        LMCacheDrivenTransferContext,
+        create_transfer_context,
+    )
+    from lmcache.v1.multiprocess.transfer_context.worker_transfer import (
+        ENV_MP_TRANSFER_MODE,
+    )
+
+    # Importing the CPU sub-package self-registers its KV-wrapper factory,
+    # which is required by the lmcache-driven (handle) path.
+    import lmcache.v1.platform.cpu  # noqa: F401
+
+    monkeypatch.setenv(ENV_MP_TRANSFER_MODE, "lmcache_driven")
+    context = create_transfer_context({"layer_0": torch.randn(2, 2)})
+    assert isinstance(context, LMCacheDrivenTransferContext)
+
+
+@pytest.mark.parametrize(
+    ("builder_fn", "expected_block_size", "expected_hidden_dim", "layout_hints"),
+    [
+        pytest.param(
+            lambda: _make_kv_caches(
+                num_layers=2,
+                num_blocks=8,
+                block_size=4,
+                num_heads=4,
+                head_size=4,
+            ),
+            4,
+            16,
+            None,
+            id="nhd",
+        ),
+        pytest.param(
+            lambda: _make_mla_kv_caches(
+                num_layers=2, num_blocks=8, block_size=4, hidden_size=16
+            ),
+            4,
+            16,
+            None,
+            id="mla",
+        ),
+    ],
+)
+def test_compute_kv_layout_and_gather_scatter_roundtrip(
+    builder_fn: Callable[[], dict[str, torch.Tensor]],
+    expected_block_size: int,
+    expected_hidden_dim: int,
+    layout_hints: "LayoutHints | None",
+) -> None:
+    """Validate layout extraction and gather/scatter round-trip on CPU tensors."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.base import (
+        compute_kv_layout,
+        gather_paged_kv_to_cpu,
+        scatter_cpu_to_paged_kv,
+    )
+
+    source = {k: v.to(torch_device_type) for k, v in builder_fn().items()}
+    (
+        block_size,
+        num_layers,
+        hidden_dim,
+        dtype_str,
+        detected_kv_format,
+    ) = compute_kv_layout(source, layout_hints=layout_hints)
+    assert block_size == expected_block_size
+    assert num_layers == 2
+    assert hidden_dim == expected_hidden_dim
+    assert dtype_str == "float32"
+    assert detected_kv_format is not None
+
+    blocks_per_chunk = 2
+    gathered = gather_paged_kv_to_cpu(source, [0, 1], blocks_per_chunk)
+    destination = {name: torch.zeros_like(tensor) for name, tensor in source.items()}
+    scatter_cpu_to_paged_kv(destination, [4, 5], gathered, blocks_per_chunk)
+
+    for name in source:
+        if source[name].dim() == 5:
+            assert torch.allclose(source[name][:, 0], destination[name][:, 4])
+            assert torch.allclose(source[name][:, 1], destination[name][:, 5])
+        else:
+            assert torch.allclose(source[name][0], destination[name][4])
+            assert torch.allclose(source[name][1], destination[name][5])
+
+
+@pytest.mark.parametrize(
+    ("hnd_builder", "expected_format"),
+    [
+        (_make_hnd_kv_caches, "NL_X_TWO_NB_NH_BS_HS"),
+        (_make_hnd_flashinfer_kv_caches, "NL_X_NB_TWO_NH_BS_HS"),
+    ],
+)
+def test_gather_scatter_roundtrip_hnd_layout(
+    hnd_builder: Callable[[int, int, int, int, int], dict[str, torch.Tensor]],
+    expected_format: str,
+) -> None:
+    """Validate gather/scatter round-trip for HND vLLM KV layout."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.base import (
+        compute_kv_layout,
+        gather_paged_kv_to_cpu,
+        scatter_cpu_to_paged_kv,
+    )
+    import lmcache.c_ops as lmc_ops
+
+    source = {k: v.to(torch_device_type) for k, v in hnd_builder(2, 8, 4, 2, 8).items()}
+    layout_hints: LayoutHints = {"kv_layout": "HND"}
+    (
+        block_size,
+        num_layers,
+        hidden_dim,
+        dtype_str,
+        detected_kv_format,
+    ) = compute_kv_layout(source, layout_hints=layout_hints)
+    assert block_size == 4
+    assert num_layers == 2
+    assert hidden_dim == 16
+    assert dtype_str == "float32"
+    assert detected_kv_format == getattr(lmc_ops.EngineKVFormat, expected_format)
+
+    blocks_per_chunk = 2
+    gathered = gather_paged_kv_to_cpu(
+        source,
+        [0, 1],
+        blocks_per_chunk,
+        layout_hints=layout_hints,
+        engine_kv_format=detected_kv_format,
+    )
+    destination = {name: torch.zeros_like(tensor) for name, tensor in source.items()}
+    scatter_cpu_to_paged_kv(
+        destination,
+        [4, 5],
+        gathered,
+        blocks_per_chunk,
+        layout_hints=layout_hints,
+        engine_kv_format=detected_kv_format,
+    )
+
+    for name in source:
+        if detected_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS:
+            assert torch.allclose(source[name][:, 0], destination[name][:, 4])
+            assert torch.allclose(source[name][:, 1], destination[name][:, 5])
+        else:
+            assert torch.allclose(source[name][0], destination[name][4])
+            assert torch.allclose(source[name][1], destination[name][5])
+
+
+def test_compute_kv_layout_empty_raises_value_error() -> None:
+    """Ensure compute_kv_layout rejects empty KV cache input."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.base import compute_kv_layout
+
+    with pytest.raises(ValueError, match="kv_caches is empty"):
+        compute_kv_layout({})
+
+
+@pytest.mark.parametrize(
+    (
+        "builder_fn",
+        "skip_tokens",
+        "expected_unchanged_blocks",
+        "expected_copied_blocks",
+    ),
+    [
+        pytest.param(
+            lambda: _make_kv_caches(
+                num_layers=2,
+                num_blocks=8,
+                block_size=4,
+                num_heads=4,
+                head_size=4,
+            ),
+            8,
+            [0, 1],
+            [2, 3],
+            id="nhd-skip-two-blocks",
+        ),
+        pytest.param(
+            lambda: _make_mla_kv_caches(
+                num_layers=2, num_blocks=8, block_size=4, hidden_size=16
+            ),
+            8,
+            [0, 1],
+            [2, 3],
+            id="mla-skip-two-blocks",
+        ),
+        pytest.param(
+            lambda: _make_mla_kv_caches(
+                num_layers=2, num_blocks=8, block_size=4, hidden_size=16
+            ),
+            40,
+            [0, 1, 2, 3],
+            [],
+            id="mla-skip-past-chunk",
+        ),
+    ],
+)
+def test_scatter_respects_skip_first_n_tokens(
+    builder_fn: Callable[[], dict[str, torch.Tensor]],
+    skip_tokens: int,
+    expected_unchanged_blocks: list[int],
+    expected_copied_blocks: list[int],
+) -> None:
+    """Ensure scatter honors skip_first_n_tokens and preserves skipped blocks."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.base import (
+        gather_paged_kv_to_cpu,
+        scatter_cpu_to_paged_kv,
+    )
+
+    source = {k: v.to(torch_device_type) for k, v in builder_fn().items()}
+    destination = {
+        name: torch.full_like(tensor, 999.0) for name, tensor in source.items()
+    }
+    gathered = gather_paged_kv_to_cpu(source, [0, 1, 2, 3], blocks_per_chunk=4)
+    scatter_cpu_to_paged_kv(
+        destination,
+        [0, 1, 2, 3],
+        gathered,
+        blocks_per_chunk=4,
+        skip_first_n_tokens=skip_tokens,
+    )
+
+    for name in destination:
+        for block_idx in expected_unchanged_blocks:
+            if destination[name].dim() == 5:
+                assert torch.all(destination[name][:, block_idx] == 999.0)
+            else:
+                assert torch.all(destination[name][block_idx] == 999.0)
+        for block_idx in expected_copied_blocks:
+            if destination[name].dim() == 5:
+                assert torch.allclose(
+                    destination[name][:, block_idx], source[name][:, block_idx]
+                )
+            else:
+                assert torch.allclose(
+                    destination[name][block_idx],
+                    source[name][block_idx],
+                )
+
+
+@pytest.mark.parametrize(
+    ("builder_fn", "layout_hints"),
+    [
+        pytest.param(
+            lambda: _make_hnd_kv_caches(num_layers=2, num_blocks=4, block_size=4),
+            {"kv_layout": "HND"},
+            id="hnd",
+        ),
+        pytest.param(
+            lambda: _make_mla_kv_caches(
+                num_layers=2, num_blocks=4, block_size=4, hidden_size=16
+            ),
+            None,
+            id="mla",
+        ),
+    ],
+)
+def test_scatter_rounds_down_partial_block_skip_first_n_tokens(
+    builder_fn: Callable[[], dict[str, torch.Tensor]],
+    layout_hints: "LayoutHints | None",
+) -> None:
+    """Scatter rounds non-block-aligned prefix skips down to whole blocks."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.base import (
+        gather_paged_kv_to_cpu,
+        scatter_cpu_to_paged_kv,
+    )
+
+    source = {k: v.to(torch_device_type) for k, v in builder_fn().items()}
+    destination = {
+        name: torch.full_like(tensor, 999.0) for name, tensor in source.items()
+    }
+    gathered = gather_paged_kv_to_cpu(
+        source,
+        [0, 1],
+        blocks_per_chunk=2,
+        layout_hints=layout_hints,
+    )
+    scatter_cpu_to_paged_kv(
+        destination,
+        [0, 1],
+        gathered,
+        blocks_per_chunk=2,
+        skip_first_n_tokens=2,
+        layout_hints=layout_hints,
+    )
+
+    for name in destination:
+        for block_idx in (0, 1):
+            if destination[name].dim() == 5:
+                assert torch.allclose(
+                    destination[name][:, block_idx],
+                    source[name][:, block_idx],
+                )
+            else:
+                assert torch.allclose(
+                    destination[name][block_idx],
+                    source[name][block_idx],
+                )
+        for block_idx in (2, 3):
+            if destination[name].dim() == 5:
+                assert torch.all(destination[name][:, block_idx] == 999.0)
+            else:
+                assert torch.all(destination[name][block_idx] == 999.0)
+
+
+@pytest.fixture
+def stub_native_storage_ops() -> Any:
+    """Stub native modules so server imports work in source-only test runs."""
+    module = type(sys)("lmcache.native_storage_ops")
+    module.TTLLock = type("TTLLock", (), {})  # type: ignore[attr-defined]
+    module.Bitmap = type("Bitmap", (), {})  # type: ignore[attr-defined]
+    module.PeriodicEventNotifier = type(  # type: ignore[attr-defined]
+        "PeriodicEventNotifier", (), {}
+    )
+    with patch.dict(
+        sys.modules,
+        {
+            "lmcache.native_storage_ops": module,
+            "cupy": MagicMock(),
+        },
+    ):
+        yield
+
+
+@pytest.fixture
+def server_module_factory(
+    stub_native_storage_ops: Any,
+) -> Iterator[ServerModuleFactory]:
+    """Create a patched server module/context with configurable mocks."""
+    # Standard
+    from contextlib import ExitStack
+
+    # First Party
+    from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+    from lmcache.v1.multiprocess.modules.engine_driven_transfer import (
+        EngineDrivenTransferModule,
+    )
+
+    stack = ExitStack()
+
+    def _create(
+        *,
+        storage_manager_config: "StorageManagerConfig | None" = None,
+        chunk_size: int = 8,
+        object_keys: list[str] | None = None,
+        mock_storage: MagicMock | None = None,
+        mock_session: MagicMock | None = None,
+    ) -> tuple[
+        "EngineDrivenTransferModule", MagicMock, MagicMock, "MPCacheServerContext"
+    ]:
+        """Create a patched module/context plus storage/session mocks.
+
+        Args:
+            storage_manager_config: Optional engine storage config override.
+            chunk_size: Engine chunk size passed to context construction.
+            object_keys: Keys returned from ``ipc_key_to_object_keys`` patch.
+            mock_storage: Optional storage mock instance to inject.
+            mock_session: Optional session mock instance to inject.
+
+        Returns ``(module, mock_storage, mock_session, ctx)``.
+        """
+        mock_storage = mock_storage or MagicMock()
+        if mock_session is None:
+            mock_session = MagicMock()
+            mock_session.get_hashes.return_value = [b"h"]
+
+        stack.enter_context(
+            patch(
+                "lmcache.v1.multiprocess.engine_context.StorageManager",
+                return_value=mock_storage,
+            )
+        )
+        stack.enter_context(patch("lmcache.v1.multiprocess.engine_context.TokenHasher"))
+        session_cls = stack.enter_context(
+            patch("lmcache.v1.multiprocess.engine_context.SessionManager")
+        )
+        stack.enter_context(
+            patch("lmcache.v1.multiprocess.engine_context.get_event_bus")
+        )
+        stack.enter_context(
+            patch(
+                "lmcache.v1.multiprocess.engine_context.ipc_key_to_object_keys",
+                return_value=[object_keys or ["obj"]],
+            )
+        )
+
+        session_cls.return_value.get_or_create.return_value = mock_session
+        if storage_manager_config is None:
+            storage_manager_config = MagicMock()
+            # GDS L1 is off in these tests. A bare MagicMock would auto-vivify
+            # gds_l1_config to a truthy mock, making MPCacheServerContext attempt
+            # real cuFile init; pin it to None so GDS init stays a no-op.
+            storage_manager_config.l1_manager_config.gds_l1_config = None
+        ctx = MPCacheServerContext(
+            storage_manager_config=storage_manager_config,
+            chunk_size=chunk_size,
+        )
+        module = EngineDrivenTransferModule(ctx)
+
+        return module, mock_storage, mock_session, ctx
+
+    yield _create  # type: ignore[misc]
+    stack.close()
+
+
+@pytest.mark.parametrize(
+    ("config_kwargs", "expected_pool_info"),
+    [
+        pytest.param(
+            {"shm_name": "/test_pool", "pool_size": 1024},
+            {"shm_name": "lmcache_l1_pool_test_pool", "pool_size": 1024},
+            id="non-lazy",
+        ),
+        pytest.param(
+            {
+                "shm_name": "lmcache_l1_pool_existing",
+                "pool_size": 2048,
+                "use_lazy": True,
+            },
+            {"shm_name": "", "pool_size": 0},
+            id="lazy",
+        ),
+    ],
+)
+def test_engine_context_shm_pool_info(
+    stub_native_storage_ops: Any,
+    config_kwargs: dict[str, Any],
+    expected_pool_info: dict[str, Any],
+) -> None:
+    """Ensure engine context computes SHM pool metadata for lazy and non-lazy modes."""
+    # First Party
+    from lmcache.v1.multiprocess.engine_context import MPCacheServerContext
+
+    with patch(
+        "lmcache.v1.distributed.config.current_device_spec",
+        MagicMock(is_pin_supported=True),
+    ):
+        config = _make_storage_manager_config(**config_kwargs)
+
+    with (
+        patch("lmcache.v1.multiprocess.engine_context.StorageManager"),
+        patch("lmcache.v1.multiprocess.engine_context.TokenHasher"),
+        patch("lmcache.v1.multiprocess.engine_context.SessionManager"),
+        patch("lmcache.v1.multiprocess.engine_context.get_event_bus"),
+    ):
+        ctx = MPCacheServerContext(storage_manager_config=config, chunk_size=16)
+
+    assert ctx.shm_pool_info == expected_pool_info
+
+
+def test_server_register_and_find_non_cuda_context_layout(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Ensure non-CUDA registration stores metadata and lookup finds layout."""
+    module, _, _, ctx = server_module_factory(chunk_size=16)
+    response = module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=1)
+    )
+    assert response.shm_name == ""
+    assert response.pool_size == 0
+
+    layout = ctx.layout_desc_registry.find("m", 1)
+    assert layout is not None
+    assert layout.shapes[0] == torch.Size([2, 2, 16, 16])
+
+
+def test_server_store_and_retrieve_cpu_chunks(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Validate mocked server-side CPU chunk store and retrieve behavior."""
+    mock_storage = MagicMock()
+    target_tensor = torch.zeros(2, 2, 8, 16)
+    mock_memory_obj = MagicMock()
+    mock_memory_obj.tensor = target_tensor
+    mock_storage.reserve_write.return_value = {"obj": mock_memory_obj}
+
+    @contextmanager
+    def _read_prefetched_results(_keys: Any) -> Any:
+        yield [mock_memory_obj]
+
+    mock_storage.read_prefetched_results.side_effect = _read_prefetched_results
+    mock_session = MagicMock()
+    mock_session.get_hashes.return_value = [b"h"]
+    module, _, _, _ = server_module_factory(
+        mock_storage=mock_storage,
+        mock_session=mock_session,
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=2)
+    )
+    payload = torch.ones(2, 2, 8, 16)
+    key = _default_key()
+    store_ok = module.commit_store(key, 2, pickle.dumps([payload]))
+    response = module.prepare_retrieve(key, 2)
+    success = response.success
+    cpu_data = response.data
+
+    assert isinstance(store_ok, bool)
+    assert torch.allclose(mock_memory_obj.tensor, payload)
+
+    assert success is True
+    recovered_chunks: list[torch.Tensor] = pickle.loads(cpu_data)
+    assert len(recovered_chunks) == 1
+    assert torch.allclose(recovered_chunks[0], payload)
+
+
+def test_server_shm_commit_store_allows_noop_when_all_keys_exist(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Regression: repeated prompt after worker restart should no-op-store cleanly.
+
+    When all object keys already exist in cache, SHM ``prepare_store`` reserves
+    no new objects and returns empty slots (``{"slots": [], "chunk_indices": []}``).
+    The worker sees an empty chunk_indices list, skips gather and commit entirely,
+    so no entry leaks in ``_pending_shm_writes`` and no spurious error is logged.
+    """
+    mock_storage = MagicMock()
+    # Empty reserve_write indicates all object keys already exist in cache.
+    mock_storage.reserve_write.return_value = {}
+    mock_session = MagicMock()
+    mock_session.get_hashes.return_value = [b"h"]
+
+    module, _, _, _ = server_module_factory(
+        storage_manager_config=_make_storage_manager_config(
+            shm_name="lmcache_test_pool", pool_size=1024
+        ),
+        mock_storage=mock_storage,
+        mock_session=mock_session,
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=3)
+    )
+    key = _default_key()
+    prepare_response = module.prepare_store(key, 3)
+    # Server signals all-cached via empty slots list (not missing "slots" key).
+    assert prepare_response.context == {"slots": [], "chunk_indices": []}
+
+    # commit_store without a matching prepare must fail (no entry leaked).
+    assert module.commit_store(key, 3, b"") is False
+
+
+def test_server_prepare_store_releases_unused_reserved_write_locks(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Ensure SHM prepare_store releases reserved keys that have no writable tensor."""
+    # First Party
+    from lmcache.v1.multiprocess.protocols.engine import PrepareStoreResponse
+
+    mock_storage = MagicMock()
+    memory_obj = MagicMock()
+    memory_obj.tensor = None
+    mock_storage.reserve_write.side_effect = lambda obj_keys, *_args, **_kwargs: {
+        obj_key: memory_obj for obj_key in obj_keys
+    }
+    mock_session = MagicMock()
+    mock_session.get_hashes.return_value = [b"h"]
+
+    module, _, _, _ = server_module_factory(
+        storage_manager_config=_make_storage_manager_config(
+            shm_name="lmcache_test_pool", pool_size=1024
+        ),
+        mock_storage=mock_storage,
+        mock_session=mock_session,
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=5)
+    )
+    key = _default_key()
+    prepare_response = module.prepare_store(key, 5)
+    assert isinstance(prepare_response, PrepareStoreResponse)
+    assert prepare_response.context == {"slots": [], "chunk_indices": []}
+    reserved_keys = mock_storage.reserve_write.call_args[0][0]
+    mock_storage.finish_write.assert_called_once_with(reserved_keys)
+
+
+def test_server_shm_transport_uses_engine_level_config(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Ensure all instances share the same engine-level SHM transport setting."""
+    mock_storage = MagicMock()
+    mock_memory_obj = MagicMock()
+    mock_memory_obj.tensor = torch.zeros(2, 2, 8, 16)
+    mock_memory_obj.shm_offset = 0
+    mock_memory_obj.shm_byte_length = 2048
+    mock_storage.reserve_write.side_effect = lambda obj_keys, *_args, **_kwargs: {
+        obj_key: mock_memory_obj for obj_key in obj_keys
+    }
+    mock_session = MagicMock()
+    mock_session.get_hashes.return_value = [b"h"]
+
+    module, _, _, _ = server_module_factory(
+        storage_manager_config=_make_storage_manager_config(
+            shm_name="lmcache_test_pool", pool_size=1024
+        ),
+        mock_storage=mock_storage,
+        mock_session=mock_session,
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=6)
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=7)
+    )
+    key = _default_key()
+    assert module.prepare_store(key, 6).context.get("slots")
+    assert module.prepare_store(key, 7).context.get("slots")
+    assert mock_storage.reserve_write.call_count == 2
+
+
+def test_server_engine_driven_reregister_returns_existing_shm_response(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Ensure duplicate non-GPU registration returns existing SHM response."""
+    module, _, _, _ = server_module_factory(
+        storage_manager_config=_make_storage_manager_config(
+            shm_name="lmcache_test_pool", pool_size=2048
+        ),
+    )
+    payload = _default_register_payload(instance_id=8)
+    first_response = module.register_kv_cache_engine_driven_context(payload)
+    second_response = module.register_kv_cache_engine_driven_context(payload)
+
+    assert first_response.shm_name == "lmcache_l1_pool_lmcache_test_pool"
+    assert first_response.pool_size == 2048
+    assert second_response.shm_name == "lmcache_l1_pool_lmcache_test_pool"
+    assert second_response.pool_size == 2048
+
+
+def test_server_unregister_engine_driven_context_releases_pending_shm_locks(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """Ensure unregister releases pending SHM read/write reservations."""
+    mock_storage = MagicMock()
+    mock_memory_obj = MagicMock()
+    mock_memory_obj.tensor = torch.zeros(2, 2, 8, 16)
+    mock_memory_obj.shm_offset = 0
+    mock_memory_obj.shm_byte_length = 2048
+    mock_storage.reserve_write.side_effect = lambda obj_keys, *_args, **_kwargs: {
+        obj_key: mock_memory_obj for obj_key in obj_keys
+    }
+    mock_storage.unsafe_read.side_effect = lambda obj_keys: (
+        obj_keys,
+        [mock_memory_obj for _ in obj_keys],
+    )
+    mock_session = MagicMock()
+    mock_session.get_hashes.return_value = [b"h"]
+
+    module, _, _, _ = server_module_factory(
+        storage_manager_config=_make_storage_manager_config(
+            shm_name="lmcache_test_pool", pool_size=4096
+        ),
+        mock_storage=mock_storage,
+        mock_session=mock_session,
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=4)
+    )
+    key = _default_key()
+    assert module.prepare_store(key, 4).context.get("slots")
+    assert module.prepare_retrieve(key, 4).success is True
+
+    module.unregister_kv_cache(4)
+
+    mock_storage.finish_write.assert_called_once()
+    mock_storage.finish_read_prefetched.assert_called_once()
+
+
+def test_gather_paged_kv_with_chunk_indices_subset() -> None:
+    """gather_paged_kv_to_cpu with chunk_indices only gathers the specified chunks.
+
+    This tests the fix for the IndexError that occurred when SHM prepare_store
+    returned fewer slots than total chunks because some chunks already existed
+    in cache.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context.base import gather_paged_kv_to_cpu
+
+    # 3 chunks (6 blocks, 2 blocks per chunk), but we only want chunks 0 and 2
+    source = {
+        k: v.to(torch_device_type)
+        for k, v in _make_kv_caches(
+            num_layers=2,
+            num_blocks=6,
+            block_size=4,
+            num_heads=4,
+            head_size=4,
+        ).items()
+    }
+    blocks_per_chunk = 2
+    # Pre-allocate output buffers for chunks 0 and 2 only (2 tensors, not 3).
+    # Shape: [2, num_layers, chunk_tokens, hidden_dim] where
+    # chunk_tokens = blocks_per_chunk * block_size = 2 * 4 = 8.
+    out0 = torch.zeros(2, 2, 8, 16)
+    out2 = torch.zeros(2, 2, 8, 16)
+    out_buffers = [out0, out2]
+
+    # With chunk_indices=[0, 2], gather only chunks at positions 0 and 2
+    # block_ids has 6 entries: [0,1] for chunk 0, [2,3] for chunk 1, [4,5] for chunk 2
+    result = gather_paged_kv_to_cpu(
+        source,
+        block_ids=[0, 1, 2, 3, 4, 5],
+        blocks_per_chunk=blocks_per_chunk,
+        out=out_buffers,
+        chunk_indices=[0, 2],
+    )
+    torch_dev.synchronize()
+    # Result should be the same list as out_buffers (in-place fill)
+    assert result is out_buffers
+
+    # out_buffers[0] should contain chunk 0 (blocks 0,1) data
+    # out_buffers[1] should contain chunk 2 (blocks 4,5) data
+    # Verify by independently gathering all chunks and comparing
+    all_chunks = gather_paged_kv_to_cpu(source, [0, 1, 2, 3, 4, 5], blocks_per_chunk)
+    torch_dev.synchronize()
+
+    assert torch.allclose(out_buffers[0], all_chunks[0])
+    assert torch.allclose(out_buffers[1], all_chunks[2])
+
+
+def test_server_prepare_store_includes_chunk_indices(
+    stub_native_storage_ops: Any,
+    server_module_factory: ServerModuleFactory,
+) -> None:
+    """prepare_store response context includes chunk_indices for SHM mode.
+
+    Regression test: the server must return the positional indices of the
+    reserved chunks so the client only gathers KV data for those chunks.
+    """
+    mock_storage = MagicMock()
+    obj1 = "obj1"
+    obj2 = "obj2"
+    mock_memory_obj = MagicMock()
+    mock_memory_obj.tensor = torch.zeros(2, 2, 8, 16)
+    mock_memory_obj.shm_offset = 0
+    mock_memory_obj.shm_byte_length = 2048
+    # Only obj2 (index 1) is reserved; obj1 (index 0) already exists in cache.
+    mock_storage.reserve_write.return_value = {obj2: mock_memory_obj}
+    mock_session = MagicMock()
+    mock_session.get_hashes.return_value = [b"h1", b"h2"]
+
+    module, _, _, _ = server_module_factory(
+        storage_manager_config=_make_storage_manager_config(
+            shm_name="lmcache_test_pool", pool_size=4096
+        ),
+        object_keys=[obj1, obj2],
+        mock_storage=mock_storage,
+        mock_session=mock_session,
+    )
+    module.register_kv_cache_engine_driven_context(
+        _default_register_payload(instance_id=10)
+    )
+    key = _default_key(tokens=16)
+    response = module.prepare_store(key, 10)
+    response_context = response.context
+
+    # slots should have 1 entry (only obj2 reserved)
+    assert len(response_context.get("slots", [])) == 1
+    # chunk_indices should be [1] (position of obj2 in [obj1, obj2])
+    assert response_context.get("chunk_indices") == [1]
+
+
+class _CompletedFuture:
+    def __init__(self, value):
+        self._value = value
+
+    def wait(self, timeout=None):  # noqa: ARG002
+        return True
+
+    def result(self, timeout=None):  # noqa: ARG002
+        return self._value
+
+
+def _create_shm_segment(shm_name: str, size: int) -> int:
+    """Create a POSIX SHM segment via the project facade.
+
+    Returns the owner mmap address so the test can release the segment
+    with ``shm_munmap`` + ``shm_unlink`` regardless of platform
+    (Linux/macOS), instead of hard-coding ``/dev/shm`` paths.
+    """
+    return shm_create_readwrite(shm_name, size)
+
+
+def test_engine_driven_context_shm_tensor_view_from_buffer() -> None:
+    shm_name = f"lmcache_test_view_{os.getpid()}"
+    addr = _create_shm_segment(shm_name, 4096)
+    try:
+        mm = shm_open_pool_as_mmap(shm_name, 4096)
+        try:
+            src = torch.arange(8, dtype=torch.float32).reshape(2, 4)
+            mm[: src.numel() * src.element_size()] = src.numpy().tobytes()
+        finally:
+            mm.close()
+
+        context = EngineDrivenContextShm(
+            metadata=EngineDrivenContextMetadata(
+                layout_desc=MemoryLayoutDesc(
+                    shapes=[torch.Size([2, 4])],
+                    dtypes=[torch.float32],
+                ),
+                block_size=1,
+                use_mla=False,
+            ),
+            mq_client=MagicMock(),
+            mq_timeout=1.0,
+            shm_name=shm_name,
+            pool_size=4096,
+        )
+        try:
+            view = context._make_tensor_view(
+                offset=0,
+                length=src.numel() * src.element_size(),
+                shape=[2, 4],
+                dtype_str="float32",
+            )
+            assert torch.equal(view, src)
+        finally:
+            context.close()
+    finally:
+        shm_munmap(addr, 4096)
+        shm_unlink(shm_name)
+
+
+def test_engine_driven_context_shm_store_retrieve_flow_with_mocked_mq() -> None:
+    shm_name = f"lmcache_test_flow_{os.getpid()}"
+    addr = _create_shm_segment(shm_name, 4096)
+    slots = [
+        {
+            "offset": 0,
+            "length": 16,
+            "shape": [2, 2],
+            "dtype": "float32",
+        }
+    ]
+
+    mq_client = MagicMock()
+
+    def _submit_request(req_type, payload, response_cls):  # noqa: ARG001
+        if req_type == RequestType.PREPARE_STORE:
+            return _CompletedFuture(
+                PrepareStoreResponse(context={"slots": slots, "chunk_indices": [0]})
+            )
+        if req_type == RequestType.COMMIT_STORE:
+            _, _, commit_cpu_data = payload
+            assert commit_cpu_data == b""
+            return _CompletedFuture(True)
+        if req_type == RequestType.PREPARE_RETRIEVE:
+            return _CompletedFuture(
+                PrepareRetrieveResponse(
+                    success=True, data=b"", context={"slots": slots}
+                )
+            )
+        if req_type == RequestType.COMMIT_RETRIEVE:
+            return _CompletedFuture(True)
+        raise AssertionError(f"Unexpected request type: {req_type}")
+
+    mq_client.submit_request.side_effect = _submit_request
+
+    context = EngineDrivenContextShm(
+        metadata=EngineDrivenContextMetadata(
+            layout_desc=MemoryLayoutDesc(
+                shapes=[torch.Size([2, 2])],
+                dtypes=[torch.float32],
+            ),
+            block_size=1,
+            use_mla=False,
+        ),
+        mq_client=mq_client,
+        mq_timeout=1.0,
+        shm_name=shm_name,
+        pool_size=4096,
+    )
+    try:
+        key = _default_key()
+        store_result = context.prepare_store(key=key, instance_id=1)
+        assert store_result is not None
+        store_views, _ = store_result
+        store_views[0].copy_(
+            torch.tensor([[1.0, 2.0], [3.0, 4.0]], dtype=torch.float32)
+        )
+        assert context.commit_store(key, 1, store_views)
+
+        retrieve_views = context.prepare_retrieve(key=key, instance_id=1)
+        assert retrieve_views is not None
+        assert torch.equal(
+            retrieve_views[0],
+            torch.tensor([[1.0, 2.0], [3.0, 4.0]], dtype=torch.float32),
+        )
+        assert context.commit_retrieve(key, 1)
+    finally:
+        context.close()
+        shm_munmap(addr, 4096)
+        shm_unlink(shm_name)
+
+
+def test_engine_driven_context_shm_init_raises_when_segment_missing() -> None:
+    with pytest.raises(FileNotFoundError, match="No such file or directory"):
+        EngineDrivenContextShm(
+            metadata=EngineDrivenContextMetadata(
+                layout_desc=MemoryLayoutDesc(
+                    shapes=[torch.Size([2, 2])],
+                    dtypes=[torch.float32],
+                ),
+                block_size=1,
+                use_mla=False,
+            ),
+            mq_client=MagicMock(),
+            mq_timeout=1.0,
+            shm_name="lmcache_missing_shm_segment",
+            pool_size=4096,
+        )
+
+
+def test_create_engine_driven_context_falls_back_to_pickle_without_shm_info() -> None:
+    context = create_engine_driven_context(
+        metadata=EngineDrivenContextMetadata(
+            layout_desc=MemoryLayoutDesc(
+                shapes=[torch.Size([2, 2])],
+                dtypes=[torch.float32],
+            ),
+            block_size=1,
+            use_mla=False,
+        ),
+        mq_client=MagicMock(),
+        mq_timeout=1.0,
+        shm_name="",
+        pool_size=0,
+    )
+    assert isinstance(context, EngineDrivenContextPickle)
+
+
+def test_create_engine_driven_context_use_pickle_ignores_valid_shm_info() -> None:
+    context = create_engine_driven_context(
+        metadata=EngineDrivenContextMetadata(
+            layout_desc=MemoryLayoutDesc(
+                shapes=[torch.Size([2, 2])],
+                dtypes=[torch.float32],
+            ),
+            block_size=1,
+            use_mla=False,
+        ),
+        mq_client=MagicMock(),
+        mq_timeout=1.0,
+        shm_name="lmcache_valid_shm",
+        pool_size=4096,
+        use_pickle=True,
+    )
+    assert isinstance(context, EngineDrivenContextPickle)
+
+
+def test_engine_driven_context_shm_close_is_idempotent() -> None:
+    shm_name = f"lmcache_test_close_{os.getpid()}"
+    addr = _create_shm_segment(shm_name, 4096)
+    try:
+        context = EngineDrivenContextShm(
+            metadata=EngineDrivenContextMetadata(
+                layout_desc=MemoryLayoutDesc(
+                    shapes=[torch.Size([2, 2])],
+                    dtypes=[torch.float32],
+                ),
+                block_size=1,
+                use_mla=False,
+            ),
+            mq_client=MagicMock(),
+            mq_timeout=1.0,
+            shm_name=shm_name,
+            pool_size=4096,
+        )
+        context.close()
+        context.close()
+    finally:
+        shm_munmap(addr, 4096)
+        shm_unlink(shm_name)
diff --git a/tests/v1/multiprocess/test_engine_passthroughs.py b/tests/v1/multiprocess/test_engine_passthroughs.py
new file mode 100644
index 0000000..f19c35c
--- /dev/null
+++ b/tests/v1/multiprocess/test_engine_passthroughs.py
@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Regression: HTTP-layer passthroughs dropped by the engine refactor."""
+
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.modules.lmcache_driven_transfer import (
+    ContextEntry,
+    LMCacheDrivenTransferModule,
+)
+from lmcache.v1.multiprocess.modules.management import ManagementModule
+from lmcache.v1.multiprocess.server import MPCacheServer
+
+
+def test_storage_manager_returns_context_storage_manager() -> None:
+    sm = MagicMock(name="storage_manager")
+    ctx = MagicMock()
+    ctx.storage_manager = sm
+
+    engine = MPCacheServer(ctx, modules=[])
+    assert engine.storage_manager is sm
+
+
+def test_cache_contexts_unwraps_entries_from_gpu_transfer_module() -> None:
+    gpu0, gpu1 = MagicMock(name="gpu_ctx_0"), MagicMock(name="gpu_ctx_1")
+    gpu_transfer = MagicMock(spec=LMCacheDrivenTransferModule)
+    gpu_transfer.context_entries_snapshot.return_value = {
+        0: ContextEntry(cache_context=gpu0, model_name="m", world_size=1),
+        7: ContextEntry(cache_context=gpu1, model_name="m", world_size=1),
+    }
+
+    engine = MPCacheServer(MagicMock(), modules=[MagicMock(), gpu_transfer])
+    # Values must be unwrapped GPUCacheContexts.
+    assert engine.cache_contexts == {0: gpu0, 7: gpu1}
+
+
+def test_cache_contexts_returns_none_in_engine_driven_mode() -> None:
+    engine = MPCacheServer(MagicMock(), modules=[MagicMock()])
+    assert engine.cache_contexts is None
+
+
+def test_clear_delegates_to_management_module() -> None:
+    mgmt = MagicMock(spec=ManagementModule)
+    engine = MPCacheServer(MagicMock(), modules=[MagicMock(), mgmt])
+    engine.clear()
+    mgmt.clear.assert_called_once_with()
+
+
+def test_clear_raises_without_management_module() -> None:
+    engine = MPCacheServer(MagicMock(), modules=[])
+    with pytest.raises(RuntimeError, match="no ManagementModule"):
+        engine.clear()
diff --git a/tests/v1/multiprocess/test_free_locks.py b/tests/v1/multiprocess/test_free_locks.py
new file mode 100644
index 0000000..5edb445
--- /dev/null
+++ b/tests/v1/multiprocess/test_free_locks.py
@@ -0,0 +1,273 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the FREE_LOOKUP_LOCKS protocol: enum registration, protocol definition,
+message-queue round-trip, server handler, and client-side adapter API.
+"""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import threading
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.mq import MessageQueueClient
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    get_handler_type,
+    get_payload_classes,
+    get_response_class,
+)
+from lmcache.v1.multiprocess.protocols.base import HandlerType
+
+# Test helpers
+from tests.v1.multiprocess import test_mq_handler_helpers
+from tests.v1.multiprocess.test_mq import (
+    MessageQueueTestHelper,
+    create_cache_key,
+)
+
+# ============================================================================
+# Protocol definition tests
+# ============================================================================
+
+
+def test_free_locks_in_request_type():
+    """FREE_LOOKUP_LOCKS should be a member of RequestType."""
+    assert hasattr(RequestType, "FREE_LOOKUP_LOCKS")
+    assert isinstance(RequestType.FREE_LOOKUP_LOCKS, RequestType)
+
+
+def test_free_locks_payload_classes():
+    """FREE_LOOKUP_LOCKS payload should be [IPCCacheServerKey, int]."""
+    payload_classes = get_payload_classes(RequestType.FREE_LOOKUP_LOCKS)
+    assert len(payload_classes) == 2
+    assert payload_classes[0] is IPCCacheServerKey
+    assert payload_classes[1] is int
+
+
+def test_free_locks_response_class():
+    """FREE_LOOKUP_LOCKS should have no response (None)."""
+    response_class = get_response_class(RequestType.FREE_LOOKUP_LOCKS)
+    assert response_class is None
+
+
+def test_free_locks_handler_type():
+    """FREE_LOOKUP_LOCKS should use BLOCKING handler type."""
+    handler_type = get_handler_type(RequestType.FREE_LOOKUP_LOCKS)
+    assert handler_type == HandlerType.BLOCKING
+
+
+# ============================================================================
+# Message-queue round-trip test
+# ============================================================================
+
+
+def test_mq_free_locks():
+    """
+    Test MessageQueue with FREE_LOOKUP_LOCKS request type.
+    FREE_LOOKUP_LOCKS takes (key: KeyType) and returns None.
+    """
+    key = create_cache_key(0)
+
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5570")
+    helper.register_handler(
+        RequestType.FREE_LOOKUP_LOCKS, test_mq_handler_helpers.free_locks_handler
+    )
+
+    helper.run_test(
+        request_type=RequestType.FREE_LOOKUP_LOCKS,
+        payloads=[key, 1],
+        expected_response=None,
+        num_requests=1,
+    )
+
+
+# ============================================================================
+# Server handler tests
+# ============================================================================
+
+
+def test_server_free_lookup_locks_calls_finish_read_prefetched():
+    """LookupModule.free_lookup_locks should resolve hash keys and call
+    finish_read_prefetched on the storage manager."""
+    # First Party
+    from lmcache.v1.multiprocess.modules.lookup import LookupModule
+
+    ctx = MagicMock()
+    ctx.token_hasher.chunk_size = 256
+    ctx.token_hasher.compute_chunk_hashes.return_value = [b"hash0"]
+
+    module = LookupModule(ctx)
+
+    # Build a key
+    key = create_cache_key(0).no_worker_id_version()
+
+    sentinel_obj_keys = [MagicMock()]
+    with patch(
+        "lmcache.v1.multiprocess.modules.lookup.ipc_key_to_object_keys",
+        return_value=[sentinel_obj_keys],
+    ):
+        module.free_lookup_locks(key, 1)
+
+    module.context.storage_manager.finish_read_prefetched.assert_called_once_with(
+        sentinel_obj_keys, extra_count=0
+    )
+
+
+def test_server_free_lookup_locks_no_matching_chunks():
+    """LookupModule.free_lookup_locks with no chunks in range should be a no-op."""
+    # First Party
+    from lmcache.v1.multiprocess.modules.lookup import LookupModule
+
+    ctx = MagicMock()
+    ctx.token_hasher.chunk_size = 256
+    ctx.token_hasher.compute_chunk_hashes.return_value = []
+
+    module = LookupModule(ctx)
+
+    # Key with start == end means no chunks to free
+    key = IPCCacheServerKey(
+        model_name="testmodel",
+        world_size=1,
+        worker_id=None,
+        token_ids=tuple(range(256)),
+        start=0,
+        end=0,
+        request_id="req-empty",
+    )
+
+    module.free_lookup_locks(key, 1)
+
+    module.context.storage_manager.finish_read_prefetched.assert_not_called()
+
+
+def test_server_handler_registered():
+    """LookupModule should have a free_lookup_locks method."""
+    # First Party
+    from lmcache.v1.multiprocess.modules.lookup import LookupModule
+
+    assert hasattr(LookupModule, "free_lookup_locks")
+    assert callable(LookupModule.free_lookup_locks)
+
+
+# ============================================================================
+# Client adapter tests
+# ============================================================================
+
+
+def test_adapter_free_lookup_locks_sends_request():
+    """LMCacheMPSchedulerAdapter.free_lookup_locks should send a FREE_LOOKUP_LOCKS
+    request with the correct key payload."""
+    # First Party
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        LMCacheMPSchedulerAdapter,
+        ParallelStrategy,
+    )
+
+    adapter = LMCacheMPSchedulerAdapter.__new__(LMCacheMPSchedulerAdapter)
+    adapter.model_name = "test_model"
+    adapter.lmcache_tokens_per_chunk = 256
+    adapter.blocks_in_chunk = 16
+    adapter.parallel_strategy = ParallelStrategy(False, 1, 0, 1, 1, 1)
+    adapter._health_events = {"tcp://test:0": threading.Event()}
+    adapter._health_events["tcp://test:0"].set()
+    adapter._server_urls = ["tcp://test:0"]
+    adapter._mq_timeout = 30.0
+
+    mock_client = MagicMock(spec=MessageQueueClient)
+    mock_future = MagicMock()
+    mock_client.submit_request.return_value = mock_future
+    adapter.mq_clients = {"tcp://test:0": mock_client}
+    adapter._pending_lookups = set()
+
+    token_ids = list(range(512))
+    adapter.free_lookup_locks(
+        token_ids=token_ids,
+        start=0,
+        end=512,
+        request_id="req-1",
+    )
+
+    mock_client.submit_request.assert_called_once()
+    call_args = mock_client.submit_request.call_args
+    req_type = call_args[0][0]
+    payloads = call_args[0][1]
+    assert req_type == RequestType.FREE_LOOKUP_LOCKS
+
+    # Payload should be [key, tp_size]
+    assert isinstance(payloads, list)
+    assert len(payloads) == 2
+
+    key = payloads[0]
+    assert isinstance(key, IPCCacheServerKey)
+    assert key.worker_id is None
+    assert key.model_name == "test_model"
+    assert key.request_id == "req-1"
+    assert payloads[1] == 1  # tp_size
+
+
+def test_adapter_free_lookup_locks_key_matches_lookup():
+    """The key created by free_lookup_locks should match the key created by
+    maybe_submit_lookup_request (no_worker_id_version, same start/end)."""
+    # First Party
+    from lmcache.integration.vllm.vllm_multi_process_adapter import (
+        LMCacheMPSchedulerAdapter,
+        ParallelStrategy,
+    )
+
+    adapter = LMCacheMPSchedulerAdapter.__new__(LMCacheMPSchedulerAdapter)
+    adapter.model_name = "test_model"
+    adapter.lmcache_tokens_per_chunk = 256
+    adapter.blocks_in_chunk = 16
+    adapter.parallel_strategy = ParallelStrategy(False, 1, 0, 1, 1, 1)
+    adapter._server_urls = ["tcp://test:0"]
+    adapter._health_events = {"tcp://test:0": threading.Event()}
+    adapter._health_events["tcp://test:0"].set()
+    adapter._mq_timeout = 30.0
+    adapter._heartbeats: dict[str, object] = {}
+    adapter._heartbeat_lock = threading.Lock()
+    adapter._heartbeat_interval = 5.0
+
+    mock_client = MagicMock(spec=MessageQueueClient)
+    mock_future = MagicMock()
+    mock_future.result.return_value = None  # LOOKUP returns None
+    mock_client.submit_request.return_value = mock_future
+    adapter.mq_clients = {"tcp://test:0": mock_client}
+    adapter._pending_lookups = set()
+    adapter._lookup_params = {}
+
+    token_ids = list(range(512))
+
+    # Submit lookup – patch heartbeat to avoid spawning a real thread
+    with patch.object(adapter, "_ensure_heartbeat_started"):
+        adapter.maybe_submit_lookup_request("req-1", token_ids)
+    lookup_call = mock_client.submit_request.call_args
+    lookup_payloads = lookup_call[0][1]
+    lookup_key = lookup_payloads[0]
+
+    mock_client.submit_request.reset_mock()
+
+    # Submit free_lookup_locks with aligned end
+    tokens_per_chunk = adapter.lmcache_tokens_per_chunk
+    aligned_end = (len(token_ids) // tokens_per_chunk) * tokens_per_chunk
+    adapter.free_lookup_locks(
+        token_ids=token_ids,
+        start=0,
+        end=aligned_end,
+        request_id="req-1",
+    )
+    free_call = mock_client.submit_request.call_args
+    free_payloads = free_call[0][1]
+    assert len(free_payloads) == 2
+    free_key = free_payloads[0]
+    assert free_payloads[1] == 1  # tp_size
+
+    # Keys should be identical
+    assert lookup_key.model_name == free_key.model_name
+    assert lookup_key.world_size == free_key.world_size
+    assert lookup_key.worker_id == free_key.worker_id
+    assert lookup_key.worker_id is None
+    assert lookup_key.start == free_key.start
+    assert lookup_key.end == free_key.end
+    assert lookup_key.request_id == free_key.request_id
+    assert lookup_key.token_ids == free_key.token_ids
diff --git a/tests/v1/multiprocess/test_futures.py b/tests/v1/multiprocess/test_futures.py
new file mode 100644
index 0000000..53cf694
--- /dev/null
+++ b/tests/v1/multiprocess/test_futures.py
@@ -0,0 +1,586 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import multiprocessing as mp
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.futures import CUDAMessagingFuture, MessagingFuture
+
+# ==============================================================================
+# Helper Functions for CUDAMessagingFuture Tests
+# ==============================================================================
+
+
+def _create_cuda_event_in_process(event_queue: mp.Queue, delay: float = 0.0):
+    """Helper process that creates a CUDA event and sends the IPC handle."""
+    torch.cuda.init()
+    if delay > 0:
+        time.sleep(delay)
+
+    # Create and record a CUDA event with interprocess flag
+    event = torch.cuda.Event(interprocess=True)
+    event.record()
+    event_bytes = event.ipc_handle()
+
+    # Send the event handle to the main process
+    event_queue.put(event_bytes)
+
+
+def test_messaging_future_basic_usage():
+    """Test basic usage of MessagingFuture: set result and retrieve it."""
+    future = MessagingFuture[int]()
+
+    # Initially, future should not be done
+    assert not future.query(), "Future should not be done initially"
+
+    # Set result
+    future.set_result(42)
+
+    # Future should now be done
+    assert future.query(), "Future should be done after setting result"
+
+    # Get result (should be immediate)
+    result = future.result(timeout=1)
+    assert result == 42, f"Expected result 42, got {result}"
+
+
+def test_messaging_future_with_thread():
+    """Test MessagingFuture with result set from another thread."""
+    future = MessagingFuture[str]()
+
+    def set_future_result():
+        time.sleep(0.5)
+        future.set_result("Hello from thread")
+
+    # Start thread that will set the result
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Initially should not be done
+    assert not future.query(), "Future should not be done before thread sets result"
+
+    # Wait for result
+    result = future.result(timeout=2)
+    assert result == "Hello from thread", f"Expected 'Hello from thread', got {result}"
+
+    # Should be done now
+    assert future.query(), "Future should be done after getting result"
+
+    thread.join()
+
+
+def test_messaging_future_wait_success():
+    """Test wait method when result becomes available."""
+    future = MessagingFuture[int]()
+
+    def set_future_result():
+        time.sleep(0.3)
+        future.set_result(100)
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Wait should return True when result is set
+    success = future.wait(timeout=1)
+    assert success, "Wait should return True when result is available"
+    assert future.query(), "Future should be done after wait returns True"
+
+    thread.join()
+
+
+def test_messaging_future_wait_timeout():
+    """Test wait method when timeout is reached."""
+    future = MessagingFuture[int]()
+
+    # Wait with short timeout (result never set)
+    start_time = time.time()
+    success = future.wait(timeout=0.2)
+    elapsed = time.time() - start_time
+
+    assert not success, "Wait should return False on timeout"
+    assert not future.query(), "Future should not be done after timeout"
+    assert 0.15 < elapsed < 0.3, f"Wait should respect timeout, elapsed: {elapsed}"
+
+
+def test_messaging_future_result_timeout():
+    """Test result method raises TimeoutError when timeout is reached."""
+    future = MessagingFuture[int]()
+
+    # Try to get result with timeout (result never set)
+    with pytest.raises(
+        TimeoutError, match="Future result not available within timeout"
+    ):
+        future.result(timeout=0.2)
+
+    assert not future.query(), "Future should not be done after timeout"
+
+
+def test_messaging_future_wait_no_timeout():
+    """Test wait method without timeout (waits indefinitely until result is set)."""
+    future = MessagingFuture[float]()
+
+    def set_future_result():
+        time.sleep(0.3)
+        future.set_result(3.14)
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Wait without timeout should wait until result is available
+    success = future.wait()  # No timeout parameter
+    assert success, "Wait should return True when result is set"
+    assert future.result() == 3.14, "Result should be accessible after wait"
+
+    thread.join()
+
+
+def test_messaging_future_multiple_result_calls():
+    """Test that result can be retrieved multiple times after being set."""
+    future = MessagingFuture[str]()
+    future.set_result("persistent value")
+
+    # Get result multiple times
+    result1 = future.result(timeout=0.1)
+    result2 = future.result(timeout=0.1)
+    result3 = future.result(timeout=0.1)
+
+    assert result1 == result2 == result3 == "persistent value", (
+        "Result should be retrievable multiple times"
+    )
+
+
+def test_messaging_future_complex_type():
+    """Test MessagingFuture with complex types like lists and dicts."""
+    future = MessagingFuture[dict]()
+
+    complex_data = {"key1": [1, 2, 3], "key2": {"nested": "value"}, "key3": 42}
+
+    def set_future_result():
+        time.sleep(0.2)
+        future.set_result(complex_data)
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    result = future.result(timeout=1)
+    assert result == complex_data, "Complex types should be preserved"
+
+    thread.join()
+
+
+# ==============================================================================
+# CUDAMessagingFuture Tests
+# ==============================================================================
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_basic_usage():
+    """Test basic usage of CUDAMessagingFuture: create, wait, and get result."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    # Create the raw future that will return (event_bytes, result_value)
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+
+    # Create CUDAMessagingFuture from raw future
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    # Initially, future should not be done
+    assert not cuda_future.query(), "CUDAMessagingFuture should not be done initially"
+
+    # Set result in raw future
+    raw_future.set_result((event_bytes, 42))
+
+    # Wait for CUDA future to complete
+    success = cuda_future.wait()
+    assert success, "Wait should return True when result is available"
+
+    # Get result
+    result = cuda_future.result()
+    assert result == 42, f"Expected result 42, got {result}"
+
+    # Query should return True after completion
+    assert cuda_future.query(), "CUDAMessagingFuture should be done after wait"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_with_thread():
+    """Test CUDAMessagingFuture with result set from another thread."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, str]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    def set_future_result():
+        time.sleep(0.5)
+        raw_future.set_result((event_bytes, "Hello CUDA"))
+
+    # Start thread that will set the result
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Initially should not be done
+    assert not cuda_future.query(), (
+        "Future should not be done before thread sets result"
+    )
+
+    # Wait for result
+    result = cuda_future.result()
+    assert result == "Hello CUDA", f"Expected 'Hello CUDA', got {result}"
+
+    # Should be done now
+    assert cuda_future.query(), "Future should be done after getting result"
+
+    thread.join()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_wait_no_timeout():
+    """Test wait method without timeout (waits indefinitely
+    until result is set).
+    """
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, float]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    def set_future_result():
+        time.sleep(0.3)
+        raw_future.set_result((event_bytes, 3.14))
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Wait without timeout should wait until result is available
+    success = cuda_future.wait()  # No timeout parameter
+    assert success, "Wait should return True when result is set"
+    assert cuda_future.result() == 3.14, "Result should be accessible after wait"
+
+    thread.join()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_wait_with_timeout_success():
+    """Test that wait method works correctly with timeout when result is available."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    def set_future_result():
+        time.sleep(0.3)
+        raw_future.set_result((event_bytes, 123))
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Wait with timeout should return True when result is available
+    success = cuda_future.wait(timeout=2.0)
+    assert success, "Wait with timeout should return True when result is available"
+    assert cuda_future.result() == 123, "Result should be accessible after wait"
+
+    thread.join()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_wait_timeout_reached():
+    """Test that wait method returns False when timeout is reached."""
+    torch.cuda.init()
+
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    # Wait with short timeout (result never set)
+    start_time = time.time()
+    success = cuda_future.wait(timeout=0.2)
+    elapsed = time.time() - start_time
+
+    assert not success, "Wait should return False on timeout"
+    assert not cuda_future.query(), "Future should not be done after timeout"
+    assert 0.15 < elapsed < 0.4, f"Wait should respect timeout, elapsed: {elapsed}"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_result_with_timeout_success():
+    """Test that result method works correctly with timeout when result is available."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    def set_future_result():
+        time.sleep(0.3)
+        raw_future.set_result((event_bytes, 456))
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    # Get result with timeout should succeed when result is available
+    result = cuda_future.result(timeout=2.0)
+    assert result == 456, f"Expected result 456, got {result}"
+
+    thread.join()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_result_timeout_reached():
+    """Test that result method raises TimeoutError when timeout is reached."""
+    torch.cuda.init()
+
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    # Try to get result with timeout (result never set)
+    with pytest.raises(
+        TimeoutError, match="CUDAMessagingFuture result not available within timeout"
+    ):
+        cuda_future.result(timeout=0.2)
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_multiple_result_calls():
+    """Test that result can be retrieved multiple times after being set."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, str]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    raw_future.set_result((event_bytes, "persistent cuda value"))
+
+    # Get result multiple times
+    result1 = cuda_future.result()
+    result2 = cuda_future.result()
+    result3 = cuda_future.result()
+
+    assert result1 == result2 == result3 == "persistent cuda value", (
+        "Result should be retrievable multiple times"
+    )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_query_before_and_after():
+    """Test query method returns False before completion and True after."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    # Query before setting result
+    assert not cuda_future.query(), "Query should return False before result is set"
+
+    # Set result
+    raw_future.set_result((event_bytes, 100))
+
+    # Wait for completion
+    cuda_future.wait()
+
+    # Query after setting result
+    assert cuda_future.query(), (
+        "Query should return True after result is set and waited"
+    )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_complex_type():
+    """Test CUDAMessagingFuture with complex types like lists and dicts."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    complex_data = {"key1": [1, 2, 3], "key2": {"nested": "value"}, "key3": 42}
+
+    raw_future = MessagingFuture[tuple[bytes, dict]]()
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future)
+
+    def set_future_result():
+        time.sleep(0.2)
+        raw_future.set_result((event_bytes, complex_data))
+
+    thread = threading.Thread(target=set_future_result)
+    thread.start()
+
+    result = cuda_future.result()
+    assert result == complex_data, "Complex types should be preserved"
+
+    thread.join()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_messaging_future_to_cuda_future():
+    """Test converting MessagingFuture to CUDAMessagingFuture
+    using to_cuda_future method.
+    """
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    raw_future = MessagingFuture[tuple[bytes, int]]()
+
+    # Convert to CUDA future
+    cuda_future = raw_future.to_cuda_future()
+
+    # Verify it's a CUDAMessagingFuture instance
+    assert isinstance(cuda_future, CUDAMessagingFuture), (
+        "to_cuda_future should return CUDAMessagingFuture instance"
+    )
+
+    # Set result and verify it works
+    raw_future.set_result((event_bytes, 999))
+
+    result = cuda_future.result()
+    assert result == 999, f"Expected result 999, got {result}"
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for CUDAMessagingFuture tests",
+)
+def test_cuda_messaging_future_with_explicit_device():
+    """Test CUDAMessagingFuture with explicit device parameter."""
+    torch.cuda.init()
+
+    # Create CUDA event in a separate process
+    ctx = mp.get_context("spawn")
+    event_queue = ctx.Queue()
+    process = ctx.Process(target=_create_cuda_event_in_process, args=(event_queue,))
+    process.start()
+
+    # Get event bytes from the process
+    event_bytes = event_queue.get(timeout=30)
+    process.join(timeout=2)
+
+    device = torch.cuda.current_device()
+    raw_future = MessagingFuture[tuple[bytes, str]]()
+
+    # Create CUDA future with explicit device
+    cuda_future = CUDAMessagingFuture.FromMessagingFuture(raw_future, device=device)
+
+    # Set result
+    raw_future.set_result((event_bytes, "explicit device"))
+
+    # Get result
+    result = cuda_future.result()
+    assert result == "explicit device", f"Expected 'explicit device', got {result}"
diff --git a/tests/v1/multiprocess/test_http_api_registry.py b/tests/v1/multiprocess/test_http_api_registry.py
new file mode 100644
index 0000000..fde305d
--- /dev/null
+++ b/tests/v1/multiprocess/test_http_api_registry.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for HTTPAPIRegistry auto-discovery and the shared
+``discover_api_routers`` utility.
+
+Covers:
+- Module filtering (only ``*_api`` modules are loaded)
+- Router type-checking (non-APIRouter ``router`` attrs skipped)
+- Nested router inclusion into the FastAPI app
+- Missing directory gracefully handled
+"""
+
+# Standard
+import sys
+
+# Third Party
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.http_api_registry import (
+    HTTPAPIRegistry,
+)
+from lmcache.v1.utils.router_discovery import discover_api_routers
+
+# ------------------------------------------------------------------ #
+#  discover_api_routers
+# ------------------------------------------------------------------ #
+
+
+class TestDiscoverApiRouters:
+    """Unit tests for the shared discovery function."""
+
+    def test_discovers_api_modules(self, tmp_path):
+        """Modules ending with ``_api`` that expose an APIRouter
+        are discovered."""
+        # Create two valid _api modules
+        (tmp_path / "foo_api.py").write_text(
+            "from fastapi import APIRouter\n"
+            "router = APIRouter()\n"
+            "@router.get('/foo')\n"
+            "async def foo(): return 'ok'\n"
+        )
+        (tmp_path / "bar_api.py").write_text(
+            "from fastapi import APIRouter\n"
+            "router = APIRouter()\n"
+            "@router.get('/bar')\n"
+            "async def bar(): return 'ok'\n"
+        )
+        # __init__.py to make it a package
+        (tmp_path / "__init__.py").write_text("")
+
+        sys.path.insert(0, str(tmp_path.parent))
+        try:
+            routers = discover_api_routers(tmp_path, pkg_name := tmp_path.name)
+        finally:
+            sys.path.pop(0)
+            # cleanup imported modules
+            for key in list(sys.modules):
+                if key.startswith(pkg_name):
+                    del sys.modules[key]
+
+        assert len(routers) == 2
+
+    def test_skips_non_api_modules(self, tmp_path):
+        """Modules without the ``_api`` suffix are ignored."""
+        (tmp_path / "helpers.py").write_text(
+            "from fastapi import APIRouter\nrouter = APIRouter()\n"
+        )
+        (tmp_path / "__init__.py").write_text("")
+
+        sys.path.insert(0, str(tmp_path.parent))
+        try:
+            routers = discover_api_routers(tmp_path, pkg_name := tmp_path.name)
+        finally:
+            sys.path.pop(0)
+            for key in list(sys.modules):
+                if key.startswith(pkg_name):
+                    del sys.modules[key]
+
+        assert len(routers) == 0
+
+    def test_skips_module_without_router(self, tmp_path):
+        """Modules that lack a ``router`` attribute are skipped."""
+        (tmp_path / "empty_api.py").write_text("# no router here\nvalue = 42\n")
+        (tmp_path / "__init__.py").write_text("")
+
+        sys.path.insert(0, str(tmp_path.parent))
+        try:
+            routers = discover_api_routers(tmp_path, pkg_name := tmp_path.name)
+        finally:
+            sys.path.pop(0)
+            for key in list(sys.modules):
+                if key.startswith(pkg_name):
+                    del sys.modules[key]
+
+        assert len(routers) == 0
+
+    def test_skips_non_apirouter_router(self, tmp_path):
+        """A ``router`` attr that is not an APIRouter is skipped."""
+        (tmp_path / "bad_api.py").write_text("router = 'not a router'\n")
+        (tmp_path / "__init__.py").write_text("")
+
+        sys.path.insert(0, str(tmp_path.parent))
+        try:
+            routers = discover_api_routers(tmp_path, pkg_name := tmp_path.name)
+        finally:
+            sys.path.pop(0)
+            for key in list(sys.modules):
+                if key.startswith(pkg_name):
+                    del sys.modules[key]
+
+        assert len(routers) == 0
+
+    def test_exclude_filters_named_modules(self, tmp_path):
+        """Modules whose base name is listed in ``exclude`` are skipped."""
+        (tmp_path / "keep_api.py").write_text(
+            "from fastapi import APIRouter\nrouter = APIRouter()\n"
+        )
+        (tmp_path / "drop_api.py").write_text(
+            "from fastapi import APIRouter\nrouter = APIRouter()\n"
+        )
+        (tmp_path / "__init__.py").write_text("")
+
+        sys.path.insert(0, str(tmp_path.parent))
+        try:
+            routers = discover_api_routers(
+                tmp_path,
+                pkg_name := tmp_path.name,
+                exclude={"drop_api"},
+            )
+        finally:
+            sys.path.pop(0)
+            for key in list(sys.modules):
+                if key.startswith(pkg_name):
+                    del sys.modules[key]
+
+        assert len(routers) == 1
+
+    def test_exclude_none_is_default(self, tmp_path):
+        """Passing ``exclude=None`` keeps all discoverable modules."""
+        (tmp_path / "a_api.py").write_text(
+            "from fastapi import APIRouter\nrouter = APIRouter()\n"
+        )
+        (tmp_path / "b_api.py").write_text(
+            "from fastapi import APIRouter\nrouter = APIRouter()\n"
+        )
+        (tmp_path / "__init__.py").write_text("")
+
+        sys.path.insert(0, str(tmp_path.parent))
+        try:
+            routers = discover_api_routers(
+                tmp_path,
+                pkg_name := tmp_path.name,
+                exclude=None,
+            )
+        finally:
+            sys.path.pop(0)
+            for key in list(sys.modules):
+                if key.startswith(pkg_name):
+                    del sys.modules[key]
+
+        assert len(routers) == 2
+
+
+# ------------------------------------------------------------------ #
+#  HTTPAPIRegistry integration
+# ------------------------------------------------------------------ #
+
+
+class TestHTTPAPIRegistry:
+    """Integration tests using the real http_apis/ modules."""
+
+    @pytest.fixture
+    def app_with_registry(self):
+        """Create a fresh FastAPI app and register all HTTP APIs."""
+        test_app = FastAPI()
+        registry = HTTPAPIRegistry(test_app)
+        registry.register_all_apis()
+        return test_app
+
+    def test_root_endpoint_registered(self, app_with_registry):
+        """The ``/`` endpoint from info_api is reachable."""
+        client = TestClient(app_with_registry)
+        resp = client.get("/")
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "ok"
+
+    def test_all_expected_routes_present(self, app_with_registry):
+        """All four expected routes are registered."""
+        routes = set(app_with_registry.openapi()["paths"])
+        expected = {"/", "/healthcheck", "/cache/clear", "/status"}
+        assert expected.issubset(routes)
diff --git a/tests/v1/multiprocess/test_http_quota_endpoints.py b/tests/v1/multiprocess/test_http_quota_endpoints.py
new file mode 100644
index 0000000..2b9d37d
--- /dev/null
+++ b/tests/v1/multiprocess/test_http_quota_endpoints.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the quota CRUD HTTP endpoints.
+
+Uses ``fastapi.testclient.TestClient`` against the module's ``app``
+with a hand-built stub engine on ``app.state.engine`` — bypasses the
+lifespan so we don't spin up the full ZMQ cache server. The stub
+exposes just the two attributes the endpoints touch:
+``storage_manager.quota_manager`` and
+``storage_manager.get_usage_bytes_by_cache_salt()``.
+"""
+
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+
+# First Party
+from lmcache.v1.distributed.quota_manager import QuotaManager
+from lmcache.v1.multiprocess.http_server import app
+
+
+@pytest.fixture
+def client():
+    """TestClient with a stub engine wired to app.state.
+
+    Each test gets a fresh QuotaManager + usage map — there is no
+    cross-test state leakage because the fixture reassigns both.
+    """
+    usage_map: dict[str, int] = {}
+
+    stub_engine = MagicMock()
+    stub_engine.storage_manager.quota_manager = QuotaManager()
+    stub_engine.storage_manager.get_usage_bytes_by_cache_salt.return_value = usage_map
+
+    app.state.engine = stub_engine
+    # ``TestClient`` without the context manager skips lifespan startup/shutdown,
+    # which is exactly what we want here.
+    c = TestClient(app)
+    yield c, stub_engine, usage_map
+    # Clear the engine so later tests don't accidentally reuse the stub.
+    if hasattr(app.state, "engine"):
+        delattr(app.state, "engine")
+
+
+@pytest.fixture
+def no_engine_client():
+    """Client with no engine on ``app.state`` — exercises the 503 path."""
+    if hasattr(app.state, "engine"):
+        delattr(app.state, "engine")
+    return TestClient(app)
+
+
+# ---------------------------------------------------------------------------
+# PUT /quota/{salt}
+# ---------------------------------------------------------------------------
+
+
+class TestPutQuota:
+    def test_set_quota_for_named_salt(self, client):
+        c, engine, _ = client
+        resp = c.put("/quota/alice", json={"limit_gb": 2.0})
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body == {"cache_salt": "alice", "limit_gb": 2.0, "status": "ok"}
+        assert engine.storage_manager.quota_manager.get_limit_bytes("alice") == int(
+            2.0 * (1024**3)
+        )
+
+    def test_set_quota_sentinel_maps_to_empty_salt(self, client):
+        """`_default` in the URL must resolve to the empty-string salt
+        in the registry — un-salted traffic doesn't have its own
+        distinct path parameter."""
+        c, engine, _ = client
+        resp = c.put("/quota/_default", json={"limit_gb": 1.0})
+        assert resp.status_code == 200
+        assert engine.storage_manager.quota_manager.has_quota("")
+        assert not engine.storage_manager.quota_manager.has_quota("_default")
+        assert resp.json()["cache_salt"] == "_default"
+
+    def test_overwrite_existing_quota(self, client):
+        c, engine, _ = client
+        c.put("/quota/alice", json={"limit_gb": 1.0})
+        resp = c.put("/quota/alice", json={"limit_gb": 5.0})
+        assert resp.status_code == 200
+        assert engine.storage_manager.quota_manager.get_limit_bytes("alice") == int(
+            5.0 * (1024**3)
+        )
+
+    def test_missing_limit_gb_is_400(self, client):
+        c, _, _ = client
+        resp = c.put("/quota/alice", json={})
+        assert resp.status_code == 400
+        assert "limit_gb" in resp.json()["error"]
+
+    def test_non_numeric_limit_is_400(self, client):
+        c, _, _ = client
+        resp = c.put("/quota/alice", json={"limit_gb": "huge"})
+        assert resp.status_code == 400
+        assert "numeric" in resp.json()["error"]
+
+    def test_negative_limit_is_400(self, client):
+        c, _, _ = client
+        resp = c.put("/quota/alice", json={"limit_gb": -1.0})
+        assert resp.status_code == 400
+        assert "non-negative" in resp.json()["error"]
+
+    def test_nan_limit_is_400(self, client):
+        """``nan`` would propagate to ``int()`` below and raise a 500;
+        reject it cleanly at parse time.
+
+        Strict JSON doesn't allow ``NaN``, but Python's ``json.loads``
+        accepts it as an extension — so a client that uses the same
+        library (including anyone who calls ``json.dumps(allow_nan=True)``)
+        can send it. Use a raw ``content=`` body to bypass the
+        strict-JSON serializer in the test client.
+        """
+        c, _, _ = client
+        resp = c.put(
+            "/quota/alice",
+            content=b'{"limit_gb": NaN}',
+            headers={"content-type": "application/json"},
+        )
+        assert resp.status_code == 400
+        assert "finite" in resp.json()["error"]
+
+    def test_inf_limit_is_400(self, client):
+        """Same rationale as NaN — ``Infinity`` is a Python json
+        extension, so a malicious client can still send it."""
+        c, _, _ = client
+        resp = c.put(
+            "/quota/alice",
+            content=b'{"limit_gb": Infinity}',
+            headers={"content-type": "application/json"},
+        )
+        assert resp.status_code == 400
+        assert "finite" in resp.json()["error"]
+
+    def test_zero_limit_is_accepted(self, client):
+        """Zero is a valid limit — it registers the salt but evaluates
+        to ``0`` bytes (same effective behavior as no entry, but the
+        entry shows up in list_quotas)."""
+        c, engine, _ = client
+        resp = c.put("/quota/alice", json={"limit_gb": 0.0})
+        assert resp.status_code == 200
+        qm = engine.storage_manager.quota_manager
+        assert qm.has_quota("alice")
+        assert qm.get_limit_bytes("alice") == 0
+
+    def test_503_when_engine_not_initialized(self, no_engine_client):
+        resp = no_engine_client.put("/quota/alice", json={"limit_gb": 1.0})
+        assert resp.status_code == 503
+
+
+# ---------------------------------------------------------------------------
+# GET /quota/{salt}
+# ---------------------------------------------------------------------------
+
+
+class TestGetQuota:
+    def test_reports_limit_and_usage(self, client):
+        c, engine, usage_map = client
+        engine.storage_manager.quota_manager.set_quota("alice", int(2.0 * (1024**3)))
+        usage_map["alice"] = int(1.3 * (1024**3))
+        resp = c.get("/quota/alice")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["cache_salt"] == "alice"
+        assert body["exists"] is True
+        assert body["limit_gb"] == pytest.approx(2.0)
+        assert body["current_usage_gb"] == pytest.approx(1.3)
+
+    def test_reports_zero_for_unknown_salt(self, client):
+        """Allowlist semantics — unknown salt returns ``exists=False``
+        and limit/usage of 0."""
+        c, _, _ = client
+        resp = c.get("/quota/charlie")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["exists"] is False
+        assert body["limit_gb"] == 0.0
+        assert body["current_usage_gb"] == 0.0
+
+    def test_sentinel_reads_empty_salt_entry(self, client):
+        c, engine, usage_map = client
+        engine.storage_manager.quota_manager.set_quota("", 512)
+        usage_map[""] = 128
+        resp = c.get("/quota/_default")
+        assert resp.status_code == 200
+        body = resp.json()
+        assert body["cache_salt"] == "_default"
+        assert body["exists"] is True
+
+
+# ---------------------------------------------------------------------------
+# DELETE /quota/{salt}
+# ---------------------------------------------------------------------------
+
+
+class TestDeleteQuota:
+    def test_delete_existing_salt(self, client):
+        c, engine, _ = client
+        engine.storage_manager.quota_manager.set_quota("alice", 1024)
+        resp = c.delete("/quota/alice")
+        assert resp.status_code == 200
+        assert resp.json() == {"cache_salt": "alice", "status": "removed"}
+        assert not engine.storage_manager.quota_manager.has_quota("alice")
+
+    def test_delete_missing_salt_returns_not_found(self, client):
+        c, _, _ = client
+        resp = c.delete("/quota/charlie")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "not_found"
+
+    def test_delete_sentinel_removes_empty_salt_entry(self, client):
+        c, engine, _ = client
+        engine.storage_manager.quota_manager.set_quota("", 512)
+        resp = c.delete("/quota/_default")
+        assert resp.status_code == 200
+        assert resp.json() == {
+            "cache_salt": "_default",
+            "status": "removed",
+        }
+        assert not engine.storage_manager.quota_manager.has_quota("")
+
+
+# ---------------------------------------------------------------------------
+# GET /quota
+# ---------------------------------------------------------------------------
+
+
+class TestListQuotas:
+    def test_list_empty_registry(self, client):
+        c, _, _ = client
+        resp = c.get("/quota")
+        assert resp.status_code == 200
+        assert resp.json() == {"users": {}}
+
+    def test_list_reports_usage_for_each_salt(self, client):
+        c, engine, usage_map = client
+        qm = engine.storage_manager.quota_manager
+        qm.set_quota("alice", int(2.0 * (1024**3)))
+        qm.set_quota("bob", int(5.0 * (1024**3)))
+        qm.set_quota("", 512)
+        usage_map.update({"alice": int(1.3 * (1024**3)), "bob": 0})
+        resp = c.get("/quota")
+        assert resp.status_code == 200
+        users = resp.json()["users"]
+        assert set(users) == {"alice", "bob", "_default"}
+        assert users["alice"]["limit_gb"] == pytest.approx(2.0)
+        assert users["alice"]["current_usage_gb"] == pytest.approx(1.3)
+        assert users["bob"]["current_usage_gb"] == 0.0
+        # The empty-salt entry appears under its URL sentinel.
+        assert "_default" in users
diff --git a/tests/v1/multiprocess/test_http_server.py b/tests/v1/multiprocess/test_http_server.py
new file mode 100644
index 0000000..ec73bcc
--- /dev/null
+++ b/tests/v1/multiprocess/test_http_server.py
@@ -0,0 +1,379 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the POST /cache/checksums endpoint (and other MP HTTP routes)."""
+
+# Standard
+from unittest.mock import MagicMock, PropertyMock
+
+# Third Party
+from fastapi.testclient import TestClient
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.http_apis.dependencies import build_context
+from lmcache.v1.multiprocess.http_server import app
+import lmcache.c_ops as lmc_ops
+
+
+def _make_kv_tensors(
+    num_layers: int = 2,
+    num_blocks: int = 4,
+    block_size: int = 4,
+    num_heads: int = 2,
+    head_size: int = 8,
+    dtype: torch.dtype = torch.float32,
+) -> list[torch.Tensor]:
+    """Create deterministic CPU KV tensors for testing."""
+    torch.manual_seed(42)
+    return [
+        torch.randn(
+            2,
+            num_blocks,
+            block_size,
+            num_heads,
+            head_size,
+            dtype=dtype,
+        )
+        for _ in range(num_layers)
+    ]
+
+
+@pytest.fixture
+def mock_gpu_ctx():
+    """Create a mock GPUCacheContext with kv_tensors."""
+    ctx = MagicMock()
+    tensors = _make_kv_tensors()
+    type(ctx).kv_tensors = PropertyMock(return_value=tensors)
+    type(ctx).block_size = PropertyMock(return_value=4)
+    # KV tensors are built as [2, NB, BS, NH, HS] -> NL_X_TWO_NB_BS_NH_HS;
+    # one homogeneous kernel group, so every layer reports the same format.
+    fmt = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    ctx.engine_kv_formats.return_value = [fmt]
+    ctx.engine_kv_format_per_layer.return_value = [fmt] * len(tensors)
+    return ctx
+
+
+@pytest.fixture
+def mock_mixed_engine():
+    """Engine whose context mixes two KV formats (a key+value layer and a
+    key-only layer), so the endpoint gathers each along its own axis."""
+    ctx = MagicMock()
+    kv_kv = torch.randn(2, 4, 4, 2, 8)
+    kv_idx = torch.randn(4, 4, 8)
+    type(ctx).kv_tensors = PropertyMock(return_value=[kv_kv, kv_idx])
+    ctx.engine_kv_format_per_layer.return_value = [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    ]
+    engine = MagicMock()
+    engine.cache_contexts = {0: ctx}
+    return engine
+
+
+@pytest.fixture
+def mock_engine(mock_gpu_ctx):
+    """Create a mock engine with cache_contexts."""
+    engine = MagicMock()
+    engine.cache_contexts = {0: mock_gpu_ctx}
+    return engine
+
+
+@pytest.fixture
+def client_with_engine(mock_engine):
+    """Create a test client with a mocked engine wired onto the per-app context.
+
+    The cache handlers resolve the engine through ``get_context`` (i.e.
+    ``app.state.context``), so the context must be built, not just
+    ``app.state.engine``.
+    """
+    app.state.engine = mock_engine
+    app.state.context = build_context(mock_engine)
+    client = TestClient(app)
+    yield client
+    client.close()
+    app.state.engine = None
+    app.state.context = None
+
+
+@pytest.fixture
+def client_no_engine():
+    """Create a test client without an engine/context."""
+    app.state.engine = None
+    app.state.context = None
+    client = TestClient(app)
+    yield client
+    client.close()
+
+
+class TestCacheChecksumsEndpoint:
+    """Tests for POST /cache/checksums."""
+
+    def test_success_basic(self, client_with_engine):
+        """Basic successful checksum request."""
+        # chunk_size is in blocks; 1 block + chunk_size=1 -> 1 chunk.
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        assert data["chunk_size"] == 1
+        assert data["num_chunks"] == 1
+        assert len(data["chunk_checksums"]) == 1
+        assert "block_id_ranges" in data
+
+    def test_success_layerwise(self, client_with_engine):
+        """Layerwise mode returns per-layer checksums."""
+        resp = client_with_engine.post(
+            "/cache/checksums",
+            json={"block_ids": [0], "chunk_size": 1, "layerwise": True},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["layerwise"] is True
+        cks = data["chunk_checksums"]
+        assert "layer_0" in cks
+        assert "layer_1" in cks
+
+    def test_deterministic(self, client_with_engine):
+        """Same request produces identical checksums."""
+        body = {"block_ids": [0], "chunk_size": 1}
+        d1 = client_with_engine.post("/cache/checksums", json=body).json()
+        d2 = client_with_engine.post("/cache/checksums", json=body).json()
+        assert d1["chunk_checksums"] == d2["chunk_checksums"]
+
+    def test_mixed_format_supported(self, mock_mixed_engine):
+        """Two different KV formats are gathered per layer, not rejected."""
+        app.state.engine = mock_mixed_engine
+        app.state.context = build_context(mock_mixed_engine)
+        client = TestClient(app)
+        try:
+            resp = client.post(
+                "/cache/checksums",
+                json={"block_ids": [0], "chunk_size": 1, "layerwise": True},
+            )
+        finally:
+            client.close()
+            app.state.engine = None
+            app.state.context = None
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        # Both layers checksummed despite different formats / block axes.
+        assert set(data["chunk_checksums"]) == {"layer_0", "layer_1"}
+
+    def test_range_block_ids(self, client_with_engine):
+        """Two block ids -> two single-block chunks."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0, 1], "chunk_size": 1}
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        # 2 blocks, chunk_size=1 block -> 2 chunks
+        assert data["num_chunks"] == 2
+
+    def test_multiple_block_ids(self, client_with_engine):
+        """Three block ids -> three single-block chunks."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0, 1, 2], "chunk_size": 1}
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        # 3 blocks, chunk_size=1 block -> 3 chunks
+        assert data["num_chunks"] == 3
+
+    # ------------------------------------------------------------------
+    # Error cases
+    # ------------------------------------------------------------------
+
+    def test_no_engine(self, client_no_engine):
+        """503 when the engine/context is not initialized."""
+        resp = client_no_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        assert resp.status_code == 503
+
+    def test_no_cache_contexts(self, client_with_engine, mock_engine):
+        """501 when engine has no cache_contexts attribute."""
+        mock_engine.cache_contexts = None
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        assert resp.status_code == 501
+
+    def test_unknown_instance_id(self, client_with_engine):
+        """404 when instance_id is not registered."""
+        resp = client_with_engine.post(
+            "/cache/checksums",
+            json={"block_ids": [0], "chunk_size": 1, "instance_id": 99},
+        )
+        assert resp.status_code == 404
+
+    def test_missing_block_ids(self, client_with_engine):
+        """400 when block_ids is empty."""
+        resp = client_with_engine.post("/cache/checksums", json={"chunk_size": 1})
+        assert resp.status_code == 400
+        assert "block_ids" in resp.json()["detail"]
+
+    def test_missing_chunk_size(self, client_with_engine):
+        """400 when chunk_size is missing (defaults to 0)."""
+        resp = client_with_engine.post("/cache/checksums", json={"block_ids": [0]})
+        assert resp.status_code == 400
+        assert "chunk_size" in resp.json()["detail"]
+
+    def test_zero_chunk_size(self, client_with_engine):
+        """400 when chunk_size is zero."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 0}
+        )
+        assert resp.status_code == 400
+
+    def test_negative_chunk_size(self, client_with_engine):
+        """400 when chunk_size is negative."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": -1}
+        )
+        assert resp.status_code == 400
+
+    def test_empty_kv_caches(self, client_with_engine, mock_gpu_ctx):
+        """404 when kv_tensors is empty."""
+        type(mock_gpu_ctx).kv_tensors = PropertyMock(
+            return_value=[],
+        )
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        assert resp.status_code == 404
+
+    # ------------------------------------------------------------------
+    # Chunk boundary edge cases
+    # ------------------------------------------------------------------
+
+    def test_partial_last_chunk(self, client_with_engine):
+        """3 blocks with chunk_size=2 blocks -> 2 chunks (2+1)."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0, 1, 2], "chunk_size": 2}
+        )
+        data = resp.json()
+        assert data["num_chunks"] == 2
+        assert len(data["chunk_checksums"]) == 2
+
+    def test_single_block_single_chunk(self, client_with_engine):
+        """Single block with chunk_size=1 block produces one chunk."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        data = resp.json()
+        assert data["num_chunks"] == 1
+
+    # ------------------------------------------------------------------
+    # Checksum validity
+    # ------------------------------------------------------------------
+
+    def test_checksums_are_valid_md5(self, client_with_engine):
+        """All checksums are 32-char hex strings."""
+        # 2 blocks, chunk_size=1 block -> 2 md5 digests.
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0, 1], "chunk_size": 1}
+        )
+        data = resp.json()
+        for cksum in data["chunk_checksums"]:
+            assert len(cksum) == 32
+            int(cksum, 16)  # must be valid hex
+
+    def test_block_id_ranges_in_response(
+        self,
+        client_with_engine,
+    ):
+        """Response includes compressed block_id_ranges."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0], "chunk_size": 1}
+        )
+        data = resp.json()
+        assert "block_id_ranges" in data
+        # Single block id is kept as-is (no range compression).
+        assert data["block_id_ranges"] == [0]
+
+    # ------------------------------------------------------------------
+    # block_ids addressing
+    # ------------------------------------------------------------------
+
+    def test_block_ids_basic(self, client_with_engine):
+        """block_ids with a block-level chunk_size."""
+        # 2 blocks, chunk_size=1 block -> 2 chunks.
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": [0, 1], "chunk_size": 1}
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["status"] == "success"
+        assert data["num_chunks"] == 2
+        assert data["block_id_ranges"] == [0, 1]
+
+    def test_block_ids_invalid_type(self, client_with_engine):
+        """422 when block_ids is not a list of ints (FastAPI validation)."""
+        resp = client_with_engine.post(
+            "/cache/checksums", json={"block_ids": "abc", "chunk_size": 1}
+        )
+        assert resp.status_code == 422
+
+
+class TestHealthAndMiscEndpoints:
+    """Smoke tests for other endpoints on the MP HTTP server."""
+
+    @pytest.fixture(autouse=True)
+    def _reset_state(self):
+        yield
+        app.state.engine = None
+        app.state.context = None
+
+    def test_root(self, client_no_engine):
+        """GET / returns ok."""
+        resp = client_no_engine.get("/")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "ok"
+
+    def test_healthcheck_no_engine(self, client_no_engine):
+        """503 when engine is not set."""
+        resp = client_no_engine.get("/healthcheck")
+        assert resp.status_code == 503
+
+    def test_healthcheck_with_engine(
+        self,
+        client_with_engine,
+    ):
+        """200 when engine is available."""
+        resp = client_with_engine.get("/healthcheck")
+        assert resp.status_code == 200
+        assert resp.json()["status"] == "healthy"
+
+    def test_clear_cache_no_engine(self, client_no_engine):
+        """503 when engine/context is not set."""
+        resp = client_no_engine.post("/cache/clear", json={})
+        assert resp.status_code == 503
+
+    def test_clear_cache_success(
+        self,
+        client_with_engine,
+        mock_engine,
+    ):
+        """200 and engine.clear() called."""
+        resp = client_with_engine.post("/cache/clear", json={"tier": "l1"})
+        assert resp.status_code == 200
+        mock_engine.clear.assert_called_once()
+
+    def test_status_no_engine(self, client_no_engine):
+        """503 when engine is not set."""
+        resp = client_no_engine.get("/status")
+        assert resp.status_code == 503
+
+    def test_status_success(
+        self,
+        client_with_engine,
+        mock_engine,
+    ):
+        """200 and engine.report_status() called."""
+        mock_engine.report_status.return_value = {"ok": True}
+        resp = client_with_engine.get("/status")
+        assert resp.status_code == 200
+        assert resp.json()["ok"] is True
diff --git a/tests/v1/multiprocess/test_lmcache_driven_layout_registry.py b/tests/v1/multiprocess/test_lmcache_driven_layout_registry.py
new file mode 100644
index 0000000..caa4158
--- /dev/null
+++ b/tests/v1/multiprocess/test_lmcache_driven_layout_registry.py
@@ -0,0 +1,203 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Regression tests for GPU transfer layout registration lifetime."""
+
+# Standard
+from typing import Any, cast
+from unittest.mock import MagicMock, patch
+import sys
+import types
+
+# Third Party
+import pytest
+import torch
+
+
+class _FakeKVLayerGroupsManager:
+    """Minimal manager stub: one full-attention object group."""
+
+    num_object_groups: int = 1
+
+    def get_attn_desc(self) -> Any:
+        """One full-attention object group."""
+        # First Party
+        from lmcache.v1.distributed.api import AttnWindowDesc
+
+        return AttnWindowDesc(num_chunks_in_sw=[-1])
+
+
+class _FakeGPUContext:
+    """Small stand-in for GPUCacheContext used by registration tests."""
+
+    num_layers: int = 2
+    kv_layer_groups_manager: _FakeKVLayerGroupsManager = _FakeKVLayerGroupsManager()
+
+    def close(self) -> None:
+        """No-op teardown (real GPUCacheContext.close deregisters its GDS buffer)."""
+
+
+class _FakeDeviceHostFuncDispatcher:
+    """No-op dispatcher to avoid starting native completion threads."""
+
+    def register(self, kind: str, handler: object, payload_type: object) -> None:
+        """Record no native callback registration."""
+
+    def start(self) -> None:
+        """Start no background thread."""
+
+    def stop(self) -> None:
+        """Stop no background thread."""
+
+
+@pytest.fixture
+def stub_native_storage_ops() -> Any:
+    """Stub native modules so MP server imports work in source-only test runs."""
+    module = types.ModuleType("lmcache.native_storage_ops")
+    module_any = cast(Any, module)
+    module_any.TTLLock = type("TTLLock", (), {})
+    module_any.Bitmap = type("Bitmap", (), {})
+    module_any.PeriodicEventNotifier = type("PeriodicEventNotifier", (), {})
+    with patch.dict(
+        sys.modules,
+        {
+            "lmcache.native_storage_ops": module,
+            "cupy": MagicMock(),
+        },
+    ):
+        yield
+
+
+def test_unregister_one_shared_gpu_layout_keeps_registry_until_last_instance(
+    monkeypatch: pytest.MonkeyPatch,
+    stub_native_storage_ops: Any,
+) -> None:
+    """Unregistering one shared GPU instance must not remove the shared layout."""
+    # First Party
+    from lmcache.utils import EngineType
+    from lmcache.v1.distributed.api import MemoryLayoutDesc
+    from lmcache.v1.multiprocess.engine_context import LayoutDescRegistry
+    from lmcache.v1.multiprocess.modules import (
+        lmcache_driven_transfer as lmcache_driven_transfer_mod,
+    )
+
+    layout_desc = MemoryLayoutDesc(
+        shapes=[torch.Size([2, 16, 32])],
+        dtypes=[torch.float32],
+    )
+    ctx = MagicMock()
+    ctx.chunk_size = 16
+    ctx.layout_desc_registry = LayoutDescRegistry()
+
+    def fake_create_cache_context(
+        kv_caches: object,
+        lmcache_tokens_per_chunk: int,
+        layout_hints: object = None,
+        engine_group_infos: object = (),
+        engine_type: object = None,
+        separate_object_groups: bool = False,
+        full_sw_kv: bool = False,
+    ) -> _FakeGPUContext:
+        """Return a fake cache context without touching CUDA or wrappers."""
+        return _FakeGPUContext()
+
+    def fake_layout_desc(
+        gpu_context: _FakeGPUContext,
+        num_tokens: int,
+        object_group_id: int = 0,
+    ) -> MemoryLayoutDesc:
+        """Return the shared layout descriptor used by both registrations."""
+        return layout_desc
+
+    monkeypatch.setattr(
+        lmcache_driven_transfer_mod,
+        "DeviceHostFuncDispatcher",
+        _FakeDeviceHostFuncDispatcher,
+    )
+    monkeypatch.setattr(
+        lmcache_driven_transfer_mod,
+        "create_cache_context",
+        fake_create_cache_context,
+    )
+    monkeypatch.setattr(
+        lmcache_driven_transfer_mod,
+        "get_layout_desc",
+        fake_layout_desc,
+    )
+    monkeypatch.setattr(
+        lmcache_driven_transfer_mod.torch_dev,
+        "empty_cache",
+        lambda: None,
+        raising=False,
+    )
+
+    module = lmcache_driven_transfer_mod.LMCacheDrivenTransferModule(ctx)
+    module.register_kv_cache(1, [], "shared-model", 1, EngineType.VLLM, {}, [])
+    module.register_kv_cache(2, [], "shared-model", 1, EngineType.VLLM, {}, [])
+    assert ctx.layout_desc_registry.find("shared-model", 1) is layout_desc
+
+    module.unregister_kv_cache(1)
+
+    assert ctx.layout_desc_registry.find("shared-model", 1) is layout_desc
+
+    module.unregister_kv_cache(2)
+    assert ctx.layout_desc_registry.find("shared-model", 1) is None
+
+
+def _layout() -> Any:
+    """A minimal layout descriptor for registry tests."""
+    # First Party
+    from lmcache.v1.distributed.api import MemoryLayoutDesc
+
+    return MemoryLayoutDesc(shapes=[torch.Size([2, 4])], dtypes=[torch.float16])
+
+
+def test_registry_attn_desc_roundtrip() -> None:
+    """register stores the attention-window descriptor; find_attn_desc reads it."""
+    # First Party
+    from lmcache.v1.distributed.api import AttnWindowDesc
+    from lmcache.v1.multiprocess.engine_context import LayoutDescRegistry
+
+    registry = LayoutDescRegistry()
+    registry.register(
+        "m", 2, _layout(), attn_desc=AttnWindowDesc(num_chunks_in_sw=[-1, 2])
+    )
+
+    assert registry.find_attn_desc("m", 2).num_chunks_in_sw == [-1, 2]
+
+
+def test_registry_attn_desc_raises_when_unregistered() -> None:
+    """find_attn_desc raises for an unknown (model, world_size) pair."""
+    # First Party
+    from lmcache.v1.multiprocess.engine_context import LayoutDescRegistry
+
+    registry = LayoutDescRegistry()
+
+    with pytest.raises(ValueError, match="No attention-window descriptor"):
+        registry.find_attn_desc("missing", 1)
+
+
+def test_registry_windows_default_single_group_when_omitted() -> None:
+    """A registration without windows resolves to a single full-attention group."""
+    # First Party
+    from lmcache.v1.multiprocess.engine_context import LayoutDescRegistry
+
+    registry = LayoutDescRegistry()
+    registry.register("m", 1, _layout())
+
+    assert registry.find_attn_desc("m", 1).num_chunks_in_sw == [-1]
+
+
+def test_registry_windows_updated_on_reregister() -> None:
+    """Re-registering the same pair refreshes the stored windows."""
+    # First Party
+    from lmcache.v1.distributed.api import AttnWindowDesc
+    from lmcache.v1.multiprocess.engine_context import LayoutDescRegistry
+
+    registry = LayoutDescRegistry()
+    registry.register(
+        "m", 1, _layout(), attn_desc=AttnWindowDesc(num_chunks_in_sw=[-1])
+    )
+    registry.register(
+        "m", 1, _layout(), attn_desc=AttnWindowDesc(num_chunks_in_sw=[-1, 4])
+    )
+
+    assert registry.find_attn_desc("m", 1).num_chunks_in_sw == [-1, 4]
diff --git a/tests/v1/multiprocess/test_lookup_wait_prefetch.py b/tests/v1/multiprocess/test_lookup_wait_prefetch.py
new file mode 100644
index 0000000..5c0ebb8
--- /dev/null
+++ b/tests/v1/multiprocess/test_lookup_wait_prefetch.py
@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the ``WAIT_PREFETCH_STATUS`` request handler path.
+
+The prefetch-controller tests cover the condition-variable wait in isolation;
+these cover the ``LookupModule`` handler that ``WAIT_PREFETCH_STATUS`` dispatches
+to, i.e. the ``wait_prefetch_status -> query_prefetch_status`` path: count
+computation, event emission, and exactly-once job consumption. The storage
+manager is mocked, so no GPU or native bitmap is needed.
+"""
+
+# Standard
+from unittest import mock
+import threading
+
+# First Party
+from lmcache.v1.multiprocess.modules.lookup import LookupModule, _PrefetchJob
+
+
+def _make_ctx(wait_result=True, found=None):
+    storage_manager = mock.Mock()
+    storage_manager.wait_prefetch_status.return_value = wait_result
+    storage_manager.query_prefetch_status.return_value = found
+    ctx = mock.Mock()
+    ctx.storage_manager = storage_manager
+    ctx.event_bus = mock.Mock()
+    ctx.chunk_size = 256
+    return ctx
+
+
+def _make_module(ctx):
+    # Bypass __init__ (which wires up otel metrics needing a full context); the
+    # handler methods only touch _ctx, _prefetch_jobs, and _prefetch_job_lock.
+    module = object.__new__(LookupModule)
+    module._ctx = ctx
+    module._prefetch_jobs = {}
+    module._prefetch_job_lock = threading.Lock()
+    return module
+
+
+def test_wait_prefetch_status_returns_count_and_consumes_job():
+    found = mock.Mock()
+    found.count_leading_ones.return_value = 8
+    ctx = _make_ctx(wait_result=True, found=found)
+    module = _make_module(ctx)
+    module._prefetch_jobs["req"] = _PrefetchJob(
+        handle=mock.sentinel.handle,
+        world_size=2,
+        request_id="req",
+        requested_tokens=512,
+    )
+
+    # wait succeeds -> query returns the bitmap -> count_leading_ones() // world_size.
+    assert module.wait_prefetch_status("req", timeout=1.0) == 4
+    ctx.storage_manager.wait_prefetch_status.assert_called_once_with(
+        mock.sentinel.handle, 1.0
+    )
+    ctx.event_bus.publish.assert_called_once()
+    # Exactly-once: the job is removed after a non-None result.
+    assert "req" not in module._prefetch_jobs
+
+
+def test_wait_prefetch_status_timeout_returns_none_and_keeps_job():
+    ctx = _make_ctx(wait_result=False)
+    module = _make_module(ctx)
+    job = _PrefetchJob(
+        handle=mock.sentinel.handle,
+        world_size=1,
+        request_id="req",
+        requested_tokens=0,
+    )
+    module._prefetch_jobs["req"] = job
+
+    assert module.wait_prefetch_status("req", timeout=0.5) is None
+    ctx.storage_manager.query_prefetch_status.assert_not_called()
+    # Job is kept so a later wait/query can still resolve it.
+    assert module._prefetch_jobs["req"] is job
+
+
+def test_wait_prefetch_status_unknown_request_returns_zero():
+    module = _make_module(_make_ctx())
+    assert module.wait_prefetch_status("missing", timeout=1.0) == 0
diff --git a/tests/v1/multiprocess/test_mp_runtime_plugin_launcher.py b/tests/v1/multiprocess/test_mp_runtime_plugin_launcher.py
new file mode 100644
index 0000000..40dfa97
--- /dev/null
+++ b/tests/v1/multiprocess/test_mp_runtime_plugin_launcher.py
@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for MPRuntimePluginLauncher.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from pathlib import Path
+from unittest.mock import patch
+import json
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.mp_runtime_plugin_launcher import (
+    MPRuntimePluginLauncher,
+)
+
+# ---------------------------------------------------------------------------
+# Test dataclasses used as config fixtures
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _FakeRuntimePluginConfig:
+    locations: list[str] = field(default_factory=list)
+    extra_config: dict = field(default_factory=dict)
+
+
+@dataclass
+class _FakeServerConfig:
+    host: str = "localhost"
+    port: int = 8080
+    chunk_size: int = 256
+
+
+@dataclass
+class _FakeStorageConfig:
+    backend: str = "local"
+    capacity: int = 1024
+
+
+@dataclass
+class _FakeConfigWithPath:
+    """Config containing a non-JSON-serializable field."""
+
+    name: str = "test"
+    path: Path = Path("/tmp/test")
+
+
+# ---------------------------------------------------------------------------
+# MPRuntimePluginLauncher
+# ---------------------------------------------------------------------------
+
+
+class TestMPRuntimePluginLauncher:
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_init_aggregates_configs(self, mock_rpl_cls):
+        """Configs are aggregated into a single JSON dict."""
+        srv = _FakeServerConfig(host="0.0.0.0", port=9090)
+        stg = _FakeStorageConfig(backend="redis", capacity=2048)
+        rpc = _FakeRuntimePluginConfig(locations=["/plugins"])
+
+        MPRuntimePluginLauncher(
+            runtime_plugin_config=rpc,
+            server=srv,
+            storage=stg,
+        )
+
+        mock_rpl_cls.assert_called_once()
+        call_kwargs = mock_rpl_cls.call_args[1]
+        wrapper = call_kwargs["config"]
+
+        assert wrapper.runtime_plugin_locations == ["/plugins"]
+        parsed = json.loads(wrapper.to_json())
+        assert parsed["server"]["host"] == "0.0.0.0"
+        assert parsed["server"]["port"] == 9090
+        assert parsed["storage"]["backend"] == "redis"
+        assert parsed["storage"]["capacity"] == 2048
+
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_init_with_non_serializable_fields(self, mock_rpl_cls):
+        """Non-serializable fields are converted to str."""
+        cfg = _FakeConfigWithPath(name="test", path=Path("/data"))
+        rpc = _FakeRuntimePluginConfig(locations=["/p"])
+
+        MPRuntimePluginLauncher(
+            runtime_plugin_config=rpc,
+            my_config=cfg,
+        )
+
+        wrapper = mock_rpl_cls.call_args[1]["config"]
+        parsed = json.loads(wrapper.to_json())
+        assert parsed["my_config"]["path"] == "/data"
+
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_init_rejects_non_dataclass(self, mock_rpl_cls):
+        """Passing a non-dataclass config raises TypeError."""
+        rpc = _FakeRuntimePluginConfig(locations=["/p"])
+        with pytest.raises(TypeError, match="Expected a dataclass"):
+            MPRuntimePluginLauncher(
+                runtime_plugin_config=rpc,
+                bad_config={"not": "a dataclass"},
+            )
+
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_init_no_configs(self, mock_rpl_cls):
+        """Launcher works with zero extra configs."""
+        rpc = _FakeRuntimePluginConfig(locations=["/p"])
+        MPRuntimePluginLauncher(
+            runtime_plugin_config=rpc,
+        )
+
+        wrapper = mock_rpl_cls.call_args[1]["config"]
+        assert json.loads(wrapper.to_json()) == {}
+
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_init_passes_no_role(self, mock_rpl_cls):
+        """MP mode has no role; inner launcher gets role=None."""
+        rpc = _FakeRuntimePluginConfig(locations=["/p"])
+        MPRuntimePluginLauncher(
+            runtime_plugin_config=rpc,
+        )
+
+        call_kwargs = mock_rpl_cls.call_args[1]
+        assert call_kwargs["role"] is None
+
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_launch_plugins_delegates(self, mock_rpl_cls):
+        """launch_plugins delegates to inner launcher."""
+        rpc = _FakeRuntimePluginConfig(locations=["/p"])
+        launcher = MPRuntimePluginLauncher(
+            runtime_plugin_config=rpc,
+        )
+        launcher.launch_plugins()
+        mock_rpl_cls.return_value.launch_plugins.assert_called_once()
+
+    @patch("lmcache.v1.multiprocess.mp_runtime_plugin_launcher.RuntimePluginLauncher")
+    def test_stop_plugins_delegates(self, mock_rpl_cls):
+        """stop_plugins delegates to inner launcher."""
+        rpc = _FakeRuntimePluginConfig(locations=["/p"])
+        launcher = MPRuntimePluginLauncher(
+            runtime_plugin_config=rpc,
+        )
+        launcher.stop_plugins()
+        mock_rpl_cls.return_value.stop_plugins.assert_called_once()
diff --git a/tests/v1/multiprocess/test_mq.py b/tests/v1/multiprocess/test_mq.py
new file mode 100644
index 0000000..75ff9cd
--- /dev/null
+++ b/tests/v1/multiprocess/test_mq.py
@@ -0,0 +1,872 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from multiprocessing.synchronize import Event as EventClass
+from typing import Any, Callable
+import multiprocessing as mp
+import sys
+import time
+
+# Third Party
+import pytest
+import torch
+import zmq
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.multiprocess.custom_types import (
+    BlockAllocationRecord,
+    IPCCacheServerKey,
+)
+from lmcache.v1.multiprocess.mq import (
+    BlockingRequestHandler,
+    MessageQueueClient,
+    MessageQueueServer,
+)
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    get_handler_type,
+    get_payload_classes,
+)
+from lmcache.v1.multiprocess.server import add_handler_helper
+from lmcache.v1.platform.cuda.ipc_wrapper import CudaIPCWrapper
+
+# Test helpers
+from tests.v1.multiprocess import test_mq_handler_helpers
+
+# ==============================================================================
+# MessageQueueServer and MessageQueueClient Tests Infrastructure
+# ==============================================================================
+
+
+def create_cache_key(index: int, model: str = "testmodel") -> IPCCacheServerKey:
+    """
+    Create a cache key for testing.
+    """
+    chunk_size = 256
+    token_ids = [index] * chunk_size
+    return IPCCacheServerKey.from_token_ids(
+        model,
+        1,
+        0,
+        token_ids,
+        start=0,
+        end=chunk_size,
+        request_id=f"test_request_{index}",
+    )
+
+
+def _server_process(
+    server_url: str,
+    ready_event: EventClass,
+    shutdown_event: EventClass,
+    request_handlers: dict[RequestType, Callable],
+):
+    """
+    Server process that runs the MessageQueueServer.
+
+    Args:
+        server_url: URL to bind the server to
+        ready_event: Event to signal when server is ready
+        shutdown_event: Event to signal server shutdown
+        request_handlers: Dict mapping RequestType to handler functions
+    """
+    # First Party
+    from lmcache.v1.multiprocess.protocol import HandlerType
+
+    context = zmq.Context.instance()
+    server = MessageQueueServer(server_url, context)
+
+    # Register all handlers
+    blocking_types: list[RequestType] = []
+    for request_type, handler in request_handlers.items():
+        payload_classes = get_payload_classes(request_type)
+        handler_type = get_handler_type(request_type)
+        server.add_handler(request_type, payload_classes, handler_type, handler)
+        if handler_type == HandlerType.BLOCKING:
+            blocking_types.append(request_type)
+
+    # Assign a normal pool for all blocking handlers in tests
+    if blocking_types:
+        server.add_normal_thread_pool(blocking_types, max_workers=4)
+
+    server.start()
+
+    # Signal that server is ready
+    ready_event.set()
+
+    # Wait for shutdown signal
+    shutdown_event.wait()
+
+    # Cleanup
+    server.close()
+
+
+def _run_client_test(
+    server_url: str,
+    ready_event: EventClass,
+    request_type: RequestType,
+    payloads: list[Any],
+    expected_response: Any,
+    num_requests: int = 1,
+    client_id: int = 0,
+) -> None:
+    """
+    Client process that sends requests and validates responses.
+
+    Args:
+        server_url: URL to connect to
+        ready_event: Event to wait for server to be ready
+        request_type: Type of request to send
+        payloads: List of payloads for the request
+        expected_response: Expected response from server
+        num_requests: Number of requests to send
+        client_id: ID of this client (for debugging)
+
+    Returns:
+        bool: True if all tests passed, False otherwise
+    """
+    # Wait for server to be ready
+    if not ready_event.wait(timeout=5):
+        print(f"Client {client_id}: Server failed to start within timeout")
+        sys.exit(1)
+
+    # Small delay to ensure server is fully initialized
+    time.sleep(0.1)
+
+    context = zmq.Context.instance()
+    client = MessageQueueClient(server_url, context)
+    successful = True
+
+    try:
+        futures = []
+        # Submit requests
+        for _ in range(num_requests):
+            future = client.submit_request(request_type, payloads)  # type: ignore
+            futures.append(future)
+
+        # Validate responses
+        for i, future in enumerate(futures):
+            response = future.result(timeout=5)
+            if response != expected_response:
+                print(
+                    f"Client {client_id}, Request {i}: Expected "
+                    f"{expected_response}, got {response}"
+                )
+
+                # Exit with error code
+                client.close()
+                sys.exit(1)
+
+    except Exception as e:
+        print(f"Client {client_id} test failed with exception: {e}")
+        successful = False
+    finally:
+        client.close()
+        if not successful:
+            sys.exit(1)
+
+
+class MessageQueueTestHelper:
+    """
+    Helper class to facilitate testing MessageQueueServer and MessageQueueClient.
+
+    Supports testing with single or multiple concurrent clients, where each client
+    can send multiple requests to the server.
+
+    Usage:
+        1. Create an instance with server URL
+        2. Register handlers for different RequestTypes
+        3. Call run_test() to execute the test with client requests
+
+    Example:
+        helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5556")
+        helper.register_handler(RequestType.NOOP, noop_handler)
+        helper.run_test(
+            request_type=RequestType.NOOP,
+            payloads=[],
+            expected_response="NOOP_OK",
+            num_requests=10,  # Each client sends 10 requests
+            num_clients=3,    # Start 3 concurrent clients
+        )
+    """
+
+    def __init__(self, server_url: str = "tcp://127.0.0.1:5556"):
+        self.server_url = server_url
+        self.handlers: dict[RequestType, Callable] = {}
+        self.ctx = mp.get_context("spawn")
+
+    def register_handler(
+        self,
+        request_type: RequestType,
+        handler: Callable,
+    ) -> "MessageQueueTestHelper":
+        """
+        Register a handler for a specific RequestType.
+
+        Args:
+            request_type: The type of request to handle
+            handler: Handler function that matches the protocol signature
+
+        Returns:
+            self for method chaining
+        """
+        self.handlers[request_type] = handler
+        return self
+
+    def run_test(
+        self,
+        request_type: RequestType,
+        payloads: list[Any],
+        expected_response: Any,
+        num_requests: int = 1,
+        num_clients: int = 1,
+        timeout: float = 10.0,
+    ) -> None:
+        """
+        Run a test by starting server and client processes.
+
+        Args:
+            request_type: Type of request to send
+            payloads: List of payloads for the request
+            expected_response: Expected response from server
+            num_requests: Number of requests each client should send
+            num_clients: Number of client processes to start
+            timeout: Maximum time to wait for test completion
+
+        Raises:
+            AssertionError: If test fails
+        """
+        ready_event = self.ctx.Event()
+        shutdown_event = self.ctx.Event()
+
+        # Start server process
+        server_process = self.ctx.Process(
+            target=_server_process,
+            args=(self.server_url, ready_event, shutdown_event, self.handlers),
+        )
+        server_process.start()
+
+        # Start multiple client processes
+        client_processes = []
+        for client_id in range(num_clients):
+            client_process = self.ctx.Process(
+                target=_run_client_test,
+                args=(
+                    self.server_url,
+                    ready_event,
+                    request_type,
+                    payloads,
+                    expected_response,
+                    num_requests,
+                    client_id,
+                ),
+            )
+            client_process.start()
+            client_processes.append(client_process)
+
+        # Wait for all clients to complete
+        failed_clients = []
+        for client_id, client_process in enumerate(client_processes):
+            client_process.join(timeout=timeout)
+
+            # Check if client completed successfully
+            if client_process.is_alive():
+                client_process.terminate()
+                client_process.join()
+                failed_clients.append((client_id, "timeout"))
+            elif client_process.exitcode != 0:
+                failed_clients.append(
+                    (client_id, f"exit code {client_process.exitcode}")
+                )
+
+        # Shutdown server
+        shutdown_event.set()
+        server_process.join(timeout=2)
+
+        if server_process.is_alive():
+            server_process.terminate()
+            server_process.join()
+
+        # Report any failures
+        if failed_clients:
+            failure_details = ", ".join(
+                [f"Client {cid}: {reason}" for cid, reason in failed_clients]
+            )
+            pytest.fail(f"Some clients failed: {failure_details}")
+
+        if server_process.exitcode != 0:
+            pytest.fail(
+                f"Server process failed with exit code {server_process.exitcode}"
+            )
+
+
+# ==============================================================================
+# Tests for Different RequestTypes
+# ==============================================================================
+
+
+def test_mq_noop_request():
+    """
+    Test MessageQueue with NOOP request type.
+    NOOP takes no payloads and returns a string response.
+    """
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5556")
+    helper.register_handler(RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+
+    # Run test with single request
+    helper.run_test(
+        request_type=RequestType.NOOP,
+        payloads=[],
+        expected_response="NOOP_OK",
+        num_requests=1,
+    )
+
+
+def test_mq_noop_multiple_requests():
+    """
+    Test MessageQueue with multiple NOOP requests.
+    Verifies that server can handle multiple sequential requests.
+    """
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5557")
+    helper.register_handler(RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+
+    # Run test with multiple requests
+    helper.run_test(
+        request_type=RequestType.NOOP,
+        payloads=[],
+        expected_response="NOOP_OK",
+        num_requests=10,
+    )
+
+
+def test_mq_noop_multiple_clients():
+    """
+    Test MessageQueue with multiple concurrent clients.
+    Verifies that server can handle requests from multiple clients simultaneously.
+    """
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5558")
+    helper.register_handler(RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+
+    # Run test with multiple clients, each sending multiple requests
+    helper.run_test(
+        request_type=RequestType.NOOP,
+        payloads=[],
+        expected_response="NOOP_OK",
+        num_requests=5,
+        num_clients=3,
+    )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="CUDA is required for REGISTER_KV_CACHE tests",
+)
+def test_mq_register_kv_cache():
+    """
+    Test MessageQueue with REGISTER_KV_CACHE request type.
+    REGISTER_KV_CACHE takes (gpu_id: int, kv_cache: KVCache) and returns None.
+    """
+    # Create test KV cache (list of CudaIPCWrapper objects)
+    kv_cache = []
+    for _ in range(3):
+        tensor = torch.randn(2, 4, device="cuda")
+        wrapper = CudaIPCWrapper(tensor)
+        kv_cache.append(wrapper)
+
+    gpu_id = 0
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5559")
+    helper.register_handler(
+        RequestType.REGISTER_KV_CACHE, test_mq_handler_helpers.register_kv_cache_handler
+    )
+
+    # Run test with REGISTER_KV_CACHE request
+    helper.run_test(
+        request_type=RequestType.REGISTER_KV_CACHE,
+        payloads=[
+            gpu_id,
+            kv_cache,
+            "testmodel",
+            1,
+            EngineType.VLLM,
+            {"vllm_block_size": 16},
+            [],
+        ],
+        expected_response=None,
+        num_requests=1,
+    )
+
+
+def test_mq_unregister_kv_cache():
+    """
+    Test MessageQueue with UNREGISTER_KV_CACHE request type.
+    UNREGISTER_KV_CACHE takes (gpu_id: int) and returns None.
+    """
+    gpu_id = 0
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5560")
+    helper.register_handler(
+        RequestType.UNREGISTER_KV_CACHE,
+        test_mq_handler_helpers.unregister_kv_cache_handler,
+    )
+
+    # Run test with UNREGISTER_KV_CACHE request
+    helper.run_test(
+        request_type=RequestType.UNREGISTER_KV_CACHE,
+        payloads=[gpu_id],
+        expected_response=None,
+        num_requests=1,
+    )
+
+
+def test_mq_unregister_kv_cache_multiple_clients():
+    """
+    Test MessageQueue with UNREGISTER_KV_CACHE from multiple clients.
+    Verifies that multiple clients can unregister KV caches concurrently.
+    """
+    gpu_id = 0
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5561")
+    helper.register_handler(
+        RequestType.UNREGISTER_KV_CACHE,
+        test_mq_handler_helpers.unregister_kv_cache_handler,
+    )
+
+    # Run test with multiple clients
+    helper.run_test(
+        request_type=RequestType.UNREGISTER_KV_CACHE,
+        payloads=[gpu_id],
+        expected_response=None,
+        num_requests=3,
+        num_clients=2,
+    )
+
+
+def test_mq_store():
+    """
+    Test MessageQueue with STORE request type.
+    STORE takes (key: KeyType, gpu_id: int, gpu_block_ids: list[list[int]],
+    event_ipc_handle: bytes) and returns (bytes, bool).
+    """
+    # Create test key
+    key = create_cache_key(0)
+    gpu_id = 0
+    gpu_block_ids = [[0, 1, 2]]
+    test_handle = b"\x00" * 64
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5562")
+    helper.register_handler(RequestType.STORE, test_mq_handler_helpers.store_handler)
+
+    # Run test with STORE request
+    helper.run_test(
+        request_type=RequestType.STORE,
+        payloads=[key, gpu_id, gpu_block_ids, test_handle],
+        expected_response=(b"\x01" * 64, True),
+        num_requests=1,
+    )
+
+
+def test_mq_retrieve():
+    """
+    Test MessageQueue with RETRIEVE request type.
+    RETRIEVE takes (key: KeyType, gpu_id: int, gpu_block_ids: list[list[int]],
+    event_ipc_handle: bytes) and returns (bytes, bool).
+    """
+    # Create test key
+    key = create_cache_key(0)
+    gpu_id = 0
+    gpu_block_ids = [[0, 1, 2]]
+    test_handle = b"\x00" * 64
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5563")
+    helper.register_handler(
+        RequestType.RETRIEVE, test_mq_handler_helpers.retrieve_handler
+    )
+
+    # Run test with RETRIEVE request
+    helper.run_test(
+        request_type=RequestType.RETRIEVE,
+        payloads=[key, gpu_id, gpu_block_ids, test_handle, 0],
+        expected_response=(b"\x01" * 64, True),
+        num_requests=1,
+    )
+
+
+def test_mq_lookup():
+    """
+    Test MessageQueue with LOOKUP request type.
+    LOOKUP takes (key: KeyType, tp_size: int) and returns None.
+    The job is tracked server-side by request_id; poll via QUERY_PREFETCH_STATUS.
+    """
+    # Create a single test key
+    key = create_cache_key(0)
+
+    # Expected response: None (LOOKUP no longer returns a job_id)
+    expected_response = None
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5564")
+    helper.register_handler(RequestType.LOOKUP, test_mq_handler_helpers.lookup_handler)
+
+    # Run test with LOOKUP request
+    helper.run_test(
+        request_type=RequestType.LOOKUP,
+        payloads=[key, 1],
+        expected_response=expected_response,
+        num_requests=1,
+    )
+
+
+def test_mq_lookup_with_different_key():
+    """
+    Test MessageQueue with LOOKUP request type with a different key.
+    Tests that the handler correctly processes a single key.
+    """
+    # Create a different test key
+    key = create_cache_key(42)
+
+    # Expected response: None (LOOKUP no longer returns a job_id)
+    expected_response = None
+
+    # Create test helper and register handler
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5565")
+    helper.register_handler(RequestType.LOOKUP, test_mq_handler_helpers.lookup_handler)
+
+    # Run test with LOOKUP request
+    helper.run_test(
+        request_type=RequestType.LOOKUP,
+        payloads=[key, 1],
+        expected_response=expected_response,
+        num_requests=1,
+    )
+
+
+def test_mq_report_block_allocation():
+    """
+    Test MessageQueue with REPORT_BLOCK_ALLOCATION request type.
+    REPORT_BLOCK_ALLOCATION takes (instance_id, model_name, records)
+    and returns None.
+    """
+    records = [
+        BlockAllocationRecord(
+            req_id="req-1",
+            new_block_ids=[0, 1, 2],
+            new_token_ids=[100, 200, 300],
+        ),
+        BlockAllocationRecord(
+            req_id="req-2",
+            new_block_ids=[3, 4],
+            new_token_ids=[400, 500],
+        ),
+    ]
+
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5566")
+    helper.register_handler(
+        RequestType.REPORT_BLOCK_ALLOCATION,
+        test_mq_handler_helpers.report_block_allocations_handler,
+    )
+
+    helper.run_test(
+        request_type=RequestType.REPORT_BLOCK_ALLOCATION,
+        payloads=[42, "test-model", records],
+        expected_response=None,
+        num_requests=1,
+    )
+
+
+def test_mq_report_block_allocation_empty():
+    """
+    Test REPORT_BLOCK_ALLOCATION with an empty records list.
+    """
+    records: list[BlockAllocationRecord] = []
+
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5567")
+    helper.register_handler(
+        RequestType.REPORT_BLOCK_ALLOCATION,
+        test_mq_handler_helpers.report_block_allocations_handler,
+    )
+
+    helper.run_test(
+        request_type=RequestType.REPORT_BLOCK_ALLOCATION,
+        payloads=[0, "", records],
+        expected_response=None,
+        num_requests=1,
+    )
+
+
+# ==============================================================================
+# Shared Polling Loop Lifecycle Tests
+# ==============================================================================
+
+
+def test_shared_loop_lifecycle():
+    """
+    Test that multiple clients share a single ClientPollingLoop and
+    that the loop is torn down when all clients close.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.mq import ClientPollingLoop
+
+    context = zmq.Context.instance()
+
+    # No loop before any clients exist
+    assert ClientPollingLoop._instance is None
+
+    client_a = MessageQueueClient("tcp://127.0.0.1:16000", context)
+    client_b = MessageQueueClient("tcp://127.0.0.1:16001", context)
+
+    # Both share the same singleton
+    loop = ClientPollingLoop._instance
+    assert loop is not None
+    assert loop._ref_count == 2
+    assert len(loop._socket_to_client) == 2
+
+    # Close one — loop persists
+    client_a.close()
+    assert ClientPollingLoop._instance is loop
+    assert loop._ref_count == 1
+    assert len(loop._socket_to_client) == 1
+
+    # Close the last — loop is destroyed
+    client_b.close()
+    assert ClientPollingLoop._instance is None
+
+
+def test_shared_loop_dispatch():
+    """
+    Test that the shared polling loop correctly dispatches responses
+    to multiple clients connected to the same server.
+
+    Server and clients run in the same process (different threads),
+    so both clients share one ClientPollingLoop.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.mq import ClientPollingLoop
+
+    server_url = "tcp://127.0.0.1:16020"
+    context = zmq.Context.instance()
+
+    # Start server in-process
+    server = MessageQueueServer(server_url, context)
+    add_handler_helper(server, RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+    server.start()
+
+    try:
+        # Create two clients sharing the same polling loop
+        client_a = MessageQueueClient(server_url, context)
+        client_b = MessageQueueClient(server_url, context)
+
+        loop = ClientPollingLoop._instance
+        assert loop is not None
+        assert loop._ref_count == 2
+
+        # Both clients submit requests concurrently
+        futures_a = [client_a.submit_request(RequestType.NOOP, []) for _ in range(5)]
+        futures_b = [client_b.submit_request(RequestType.NOOP, []) for _ in range(5)]
+
+        # All futures should resolve with the correct response
+        for future in futures_a:
+            assert future.result(timeout=5) == "NOOP_OK"
+        for future in futures_b:
+            assert future.result(timeout=5) == "NOOP_OK"
+
+        client_a.close()
+        client_b.close()
+        assert ClientPollingLoop._instance is None
+    finally:
+        server.close()
+
+
+def test_shared_loop_recreate():
+    """
+    Test that closing all clients and creating new ones starts a fresh loop.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.mq import ClientPollingLoop
+
+    context = zmq.Context.instance()
+
+    client = MessageQueueClient("tcp://127.0.0.1:16010", context)
+    first_loop = ClientPollingLoop._instance
+    assert first_loop is not None
+    client.close()
+    assert ClientPollingLoop._instance is None
+
+    # New client creates a brand-new loop
+    client2 = MessageQueueClient("tcp://127.0.0.1:16011", context)
+    second_loop = ClientPollingLoop._instance
+    assert second_loop is not None
+    assert second_loop is not first_loop
+    client2.close()
+    assert ClientPollingLoop._instance is None
+
+
+# ==============================================================================
+# Thread Pool Tests
+# ==============================================================================
+
+
+def test_add_normal_thread_pool():
+    """
+    Test that add_normal_thread_pool assigns handler executors.
+    """
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15700", context)
+
+    add_handler_helper(
+        server, RequestType.LOOKUP, test_mq_handler_helpers.lookup_handler
+    )
+    add_handler_helper(server, RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+
+    lookup_handler = server.handlers[RequestType.LOOKUP]
+    assert isinstance(lookup_handler, BlockingRequestHandler)
+    assert lookup_handler.executor is None
+
+    server.add_normal_thread_pool([RequestType.LOOKUP], max_workers=4)
+
+    assert lookup_handler.executor is not None
+    assert len(server.extra_pools) == 1
+
+    server.close()
+
+
+def test_add_affinity_thread_pool():
+    """
+    Test that add_affinity_thread_pool assigns AffinityThreadPool executors.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.affinity_pool import AffinityThreadPool
+
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15700", context)
+
+    add_handler_helper(server, RequestType.STORE, test_mq_handler_helpers.store_handler)
+    add_handler_helper(
+        server, RequestType.RETRIEVE, test_mq_handler_helpers.retrieve_handler
+    )
+
+    store_handler = server.handlers[RequestType.STORE]
+    retrieve_handler = server.handlers[RequestType.RETRIEVE]
+    assert isinstance(store_handler, BlockingRequestHandler)
+    assert isinstance(retrieve_handler, BlockingRequestHandler)
+    assert store_handler.executor is None
+
+    server.add_affinity_thread_pool(
+        [RequestType.STORE, RequestType.RETRIEVE], max_workers=2
+    )
+
+    assert isinstance(store_handler.executor, AffinityThreadPool)
+    assert store_handler.executor is retrieve_handler.executor
+    assert len(server.extra_pools) == 1
+
+    server.close()
+
+
+def test_normal_pool_error_on_sync_handler():
+    """
+    Test that add_normal_thread_pool raises TypeError for SYNC handlers.
+    """
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15701", context)
+
+    add_handler_helper(server, RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+
+    with pytest.raises(TypeError, match="not BlockingRequestHandler"):
+        server.add_normal_thread_pool([RequestType.NOOP], max_workers=1)
+
+    server.close()
+
+
+def test_affinity_pool_error_on_sync_handler():
+    """
+    Test that add_affinity_thread_pool raises TypeError for SYNC handlers.
+    """
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15701", context)
+
+    add_handler_helper(server, RequestType.NOOP, test_mq_handler_helpers.noop_handler)
+
+    with pytest.raises(TypeError, match="not BlockingRequestHandler"):
+        server.add_affinity_thread_pool([RequestType.NOOP], max_workers=1)
+
+    server.close()
+
+
+def test_pool_error_on_unregistered():
+    """
+    Test that pool methods raise ValueError for unregistered request types.
+    """
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15702", context)
+
+    with pytest.raises(ValueError, match="No handler registered"):
+        server.add_normal_thread_pool([RequestType.STORE], max_workers=1)
+
+    with pytest.raises(ValueError, match="No handler registered"):
+        server.add_affinity_thread_pool([RequestType.STORE], max_workers=1)
+
+    server.close()
+
+
+def test_multiple_pools():
+    """
+    Test that normal and affinity pools can coexist.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.affinity_pool import AffinityThreadPool
+
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15703", context)
+
+    add_handler_helper(server, RequestType.STORE, test_mq_handler_helpers.store_handler)
+    add_handler_helper(
+        server, RequestType.RETRIEVE, test_mq_handler_helpers.retrieve_handler
+    )
+    add_handler_helper(
+        server, RequestType.LOOKUP, test_mq_handler_helpers.lookup_handler
+    )
+
+    server.add_affinity_thread_pool(
+        [RequestType.STORE, RequestType.RETRIEVE], max_workers=2
+    )
+    server.add_normal_thread_pool([RequestType.LOOKUP], max_workers=3)
+
+    store_handler = server.handlers[RequestType.STORE]
+    retrieve_handler = server.handlers[RequestType.RETRIEVE]
+    lookup_handler = server.handlers[RequestType.LOOKUP]
+    assert isinstance(store_handler, BlockingRequestHandler)
+    assert isinstance(retrieve_handler, BlockingRequestHandler)
+    assert isinstance(lookup_handler, BlockingRequestHandler)
+
+    # STORE/RETRIEVE share affinity pool
+    assert isinstance(store_handler.executor, AffinityThreadPool)
+    assert store_handler.executor is retrieve_handler.executor
+    # LOOKUP uses normal pool
+    assert store_handler.executor is not lookup_handler.executor
+    assert not isinstance(lookup_handler.executor, AffinityThreadPool)
+    assert len(server.extra_pools) == 2
+
+    server.close()
+
+
+def test_start_fails_without_pool_assignment():
+    """
+    Test that start() raises RuntimeError if a blocking handler
+    has no executor assigned.
+    """
+    context = zmq.Context.instance()
+    server = MessageQueueServer("tcp://127.0.0.1:15704", context)
+
+    add_handler_helper(server, RequestType.STORE, test_mq_handler_helpers.store_handler)
+    # Don't assign any pool
+
+    with pytest.raises(RuntimeError, match="no thread pool assigned"):
+        server.start()
+
+    server.close()
diff --git a/tests/v1/multiprocess/test_mq_handler_helpers.py b/tests/v1/multiprocess/test_mq_handler_helpers.py
new file mode 100644
index 0000000..b1d6525
--- /dev/null
+++ b/tests/v1/multiprocess/test_mq_handler_helpers.py
@@ -0,0 +1,258 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Helper handler functions for MessageQueue tests.
+
+These handlers are defined at module level to allow them to be pickled
+and passed between processes during multiprocessing tests.
+"""
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.gpu_connector.utils import LayoutHints
+from lmcache.v1.multiprocess.custom_types import (
+    BlockAllocationRecord,
+    KVCache,
+)
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+from lmcache.v1.multiprocess.protocol import KeyType
+
+# ==============================================================================
+# NOOP Request Handlers
+# ==============================================================================
+
+
+def noop_handler() -> str:
+    """
+    Dummy handler for NOOP requests.
+    Takes no arguments and returns a simple string response.
+    """
+    return "NOOP_OK"
+
+
+# ==============================================================================
+# REGISTER_KV_CACHE Request Handlers
+# ==============================================================================
+
+
+def register_kv_cache_handler(
+    gpu_id: int,
+    kv_cache: KVCache,
+    model_name: str,
+    world_size: int,
+    engine_type: EngineType,
+    layout_hints: LayoutHints,
+    engine_group_infos: list[EngineGroupInfo],
+) -> None:
+    """
+    Dummy handler for REGISTER_KV_CACHE requests.
+
+    Args:
+        gpu_id: GPU device ID
+        kv_cache: List of CudaIPCWrapper objects representing KV cache
+        model_name: Name of the model associated with this KV cache
+        world_size: World size associated with this KV cache
+        engine_type: Which serving engine produced the caches
+        layout_hints: Engine-provided hints dict.
+        engine_group_infos: Engine-neutral KV cache group metadata,
+            msgspec-decoded from the request payload.
+
+    Returns:
+        None
+    """
+    # In a real implementation, this would register the KV cache
+    # For testing, we just validate the inputs are received correctly
+    assert isinstance(gpu_id, int), f"Expected gpu_id to be int, got {type(gpu_id)}"
+    assert isinstance(kv_cache, list), (
+        f"Expected kv_cache to be list, got {type(kv_cache)}"
+    )
+    assert isinstance(model_name, str), (
+        f"Expected model_name to be str, got {type(model_name)}"
+    )
+    assert isinstance(world_size, int), (
+        f"Expected world_size to be int, got {type(world_size)}"
+    )
+    assert isinstance(engine_type, EngineType), (
+        f"Expected engine_type to be EngineType, got {type(engine_type)}"
+    )
+    assert isinstance(layout_hints, dict), (
+        f"Expected layout_hints to be dict, got {type(layout_hints)}"
+    )
+    assert isinstance(engine_group_infos, list), (
+        f"Expected engine_group_infos to be a list, got {type(engine_group_infos)}"
+    )
+    # No return value (returns None implicitly)
+
+
+# ==============================================================================
+# UNREGISTER_KV_CACHE Request Handlers
+# ==============================================================================
+
+
+def unregister_kv_cache_handler(gpu_id: int) -> None:
+    """
+    Dummy handler for UNREGISTER_KV_CACHE requests.
+
+    Args:
+        gpu_id: GPU device ID
+
+    Returns:
+        None
+    """
+    # In a real implementation, this would unregister the KV cache for the given GPU
+    # For testing, we just validate the input is received correctly
+    assert isinstance(gpu_id, int), f"Expected gpu_id to be int, got {type(gpu_id)}"
+    # No return value (returns None implicitly)
+
+
+# ==============================================================================
+# STORE Request Handlers
+# ==============================================================================
+
+
+def store_handler(
+    key: KeyType, gpu_id: int, gpu_block_ids: list[list[int]], ipc_handle: bytes
+) -> tuple[bytes, bool]:
+    """
+    Dummy handler for STORE requests.
+
+    Args:
+        key: Cache key to store
+        gpu_id: GPU device ID
+        gpu_block_ids: GPU block IDs per KV cache group
+        ipc_handle: CUDA event IPC handle
+
+    Returns:
+        tuple[bytes, bool]: (event handle, success flag)
+    """
+    assert isinstance(key, KeyType), f"Expected key to be KeyType, got {type(key)}"
+    assert isinstance(gpu_id, int), f"Expected gpu_id to be int, got {type(gpu_id)}"
+    assert isinstance(gpu_block_ids, list), (
+        f"Expected gpu_block_ids to be list, got {type(gpu_block_ids)}"
+    )
+    assert all(isinstance(block_ids, list) for block_ids in gpu_block_ids), (
+        "Expected gpu_block_ids to be list[list[int]]"
+    )
+    assert isinstance(ipc_handle, bytes), (
+        f"Expected ipc_handle to be bytes, got {type(ipc_handle)}"
+    )
+    return b"\x01" * 64, True
+
+
+# ==============================================================================
+# RETRIEVE Request Handlers
+# ==============================================================================
+
+
+def retrieve_handler(
+    key: KeyType,
+    gpu_id: int,
+    gpu_block_ids: list[list[int]],
+    event_handler: bytes,
+    skip_first_n_tokens: int = 0,
+) -> tuple[bytes, bool]:
+    """
+    Dummy handler for RETRIEVE requests.
+
+    Args:
+        key: Cache key to retrieve
+        gpu_id: GPU device ID
+        gpu_block_ids: GPU block IDs per KV cache group
+        event_handler: CUDA event IPC handle
+        skip_first_n_tokens: Number of tokens to skip at retrieve start
+
+    Returns:
+        tuple[bytes, bool]: (event handle, success flag)
+    """
+    assert isinstance(key, KeyType), f"Expected key to be KeyType, got {type(key)}"
+    assert isinstance(gpu_id, int), f"Expected gpu_id to be int, got {type(gpu_id)}"
+    assert isinstance(gpu_block_ids, list), (
+        f"Expected gpu_block_ids to be list, got {type(gpu_block_ids)}"
+    )
+    assert all(isinstance(block_ids, list) for block_ids in gpu_block_ids), (
+        "Expected gpu_block_ids to be list[list[int]]"
+    )
+    assert isinstance(event_handler, bytes), (
+        f"Expected event_handler to be bytes, got {type(event_handler)}"
+    )
+    assert isinstance(skip_first_n_tokens, int), (
+        f"Expected skip_first_n_tokens to be int, got {type(skip_first_n_tokens)}"
+    )
+    return b"\x01" * 64, True
+
+
+# ==============================================================================
+# LOOKUP Request Handlers
+# ==============================================================================
+
+
+def lookup_handler(key: KeyType, tp_size: int) -> None:
+    """
+    Dummy handler for LOOKUP requests.
+
+    Args:
+        key: Cache key to look up (request_id embedded in the key)
+        tp_size: Tensor-parallel size for MLA
+            multi-reader locking
+
+    Returns:
+        None: LOOKUP registers the job server-side; poll via QUERY_PREFETCH_STATUS.
+    """
+    # In a real implementation, this would look up the key in the cache
+    # For testing, we just validate the input
+    assert isinstance(key, KeyType), f"Expected key to be KeyType, got {type(key)}"
+    assert isinstance(tp_size, int), f"Expected tp_size to be int, got {type(tp_size)}"
+
+
+# ==============================================================================
+# FREE_LOOKUP_LOCKS Request Handlers
+# ==============================================================================
+
+
+def free_locks_handler(key: KeyType, tp_size: int) -> None:
+    """
+    Dummy handler for FREE_LOOKUP_LOCKS requests.
+
+    Args:
+        key: Cache key whose read locks should be released
+        tp_size: Tensor-parallel size for MLA
+            multi-reader locking
+
+    Returns:
+        None
+    """
+    assert isinstance(key, KeyType), f"Expected key to be KeyType, got {type(key)}"
+    assert isinstance(tp_size, int), f"Expected tp_size to be int, got {type(tp_size)}"
+
+
+# ==============================================================================
+# REPORT_BLOCK_ALLOCATION Request Handlers
+# ==============================================================================
+
+
+def report_block_allocations_handler(
+    instance_id: int,
+    model_name: str,
+    records: list[BlockAllocationRecord],
+) -> None:
+    """
+    Dummy handler for REPORT_BLOCK_ALLOCATION requests.
+
+    Args:
+        instance_id: The scheduler instance ID.
+        model_name: The model name from the adapter.
+        records: List of BlockAllocationRecord with per-request
+            block and token allocation deltas.
+
+    Returns:
+        None
+    """
+    assert isinstance(records, list), (
+        f"Expected records to be list, got {type(records)}"
+    )
+    for rec in records:
+        assert isinstance(rec, BlockAllocationRecord), (
+            f"Expected BlockAllocationRecord, got {type(rec)}"
+        )
+        assert isinstance(rec.req_id, str)
+        assert isinstance(rec.new_block_ids, list)
+        assert isinstance(rec.new_token_ids, list)
diff --git a/tests/v1/multiprocess/test_optimized_lookup_v3.py b/tests/v1/multiprocess/test_optimized_lookup_v3.py
new file mode 100644
index 0000000..e39d437
--- /dev/null
+++ b/tests/v1/multiprocess/test_optimized_lookup_v3.py
@@ -0,0 +1,799 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Optimized vs current V3 lookup — pure-Python module test.
+
+Compares two lookup designs over the same V3 matcher state:
+
+* ``current_v3_lookup`` — single ``match_sub_sequence`` call returning one
+  flat list; each result is classified as prefix/non-prefix at retrieve
+  time via ``old_st == cur_st``.
+
+* ``optimal_lookup`` — chain-walk first (contiguous aligned prefix),
+  matcher probe filtered to ``cur_chunk_idx >= K``, partitioned into
+  ``prefix_hits`` / ``cb_aligned`` / ``cb_shifted``.
+
+Both paths share the same matcher (same registrations, same hashes), so the
+union of optimal's buckets must equal the V3 result set (after dedupe).
+Re-rope decisions must match: ``cb_shifted`` ↔ ``old_st != cur_st``,
+``prefix_hits ∪ cb_aligned`` ↔ ``old_st == cur_st``.
+"""
+
+# Standard
+from collections.abc import Callable
+from dataclasses import dataclass
+import time
+
+# Third Party
+import numpy as np
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.multiprocess.custom_types import CBMatchResult
+from lmcache.v1.multiprocess.modules.blend_v3 import BlendTokenRangeMatcherV3
+from lmcache.v1.multiprocess.token_hasher import rolling_hash_windows_numba
+
+CHUNK_SIZE = 256
+# vLLM v1's typical paged-block size; retrieve drops cur_st % BLOCK_SIZE != 0.
+BLOCK_SIZE = 16
+
+
+# ---------------------------------------------------------------------------
+# Lookup implementations under test
+# ---------------------------------------------------------------------------
+
+
+def _greedy_leftmost_dedupe(matches: list[CBMatchResult]) -> list[CBMatchResult]:
+    """Drop overlapping matches keeping the leftmost — same as V2/V3 lookup."""
+    matches = sorted(matches, key=lambda r: r.cur_st)
+    out: list[CBMatchResult] = []
+    covered_end = -1
+    for r in matches:
+        if r.cur_st >= covered_end:
+            out.append(r)
+            covered_end = r.cur_ed
+    return out
+
+
+def current_v3_lookup(
+    matcher: BlendTokenRangeMatcherV3,
+    query: list[int],
+) -> list[CBMatchResult]:
+    """Mirror of the V3 lookup body (without the storage-prefetch round)."""
+    matches = matcher.match_sub_sequence(query)
+    return _greedy_leftmost_dedupe(matches)
+
+
+@dataclass
+class OptimalLookupResult:
+    """Three-bucket plan emitted by the optimal lookup."""
+
+    prefix_hits: list[CBMatchResult]  # chain walk; old_st == cur_st, contiguous from 0
+    cb_aligned: list[CBMatchResult]  # matcher hit; old_st == cur_st, past chain break
+    cb_shifted: list[CBMatchResult]  # matcher hit; old_st != cur_st
+
+
+def _simulate_chain_walk(
+    matches_by_chunk: dict[int, CBMatchResult],
+    num_chunks: int,
+) -> list[CBMatchResult]:
+    """Longest contiguous prefix where each chunk i has an aligned match.
+
+    Stand-in for the real chain walker, which probes storage by chained
+    chunk hash. Here we use ``matches_by_chunk`` (built from the matcher's
+    output) as the ground truth for "chunk i is in storage and aligns".
+    """
+    out: list[CBMatchResult] = []
+    for i in range(num_chunks):
+        m = matches_by_chunk.get(i)
+        if m is None or m.old_st != m.cur_st:
+            break
+        out.append(m)
+    return out
+
+
+def optimal_lookup(
+    matcher: BlendTokenRangeMatcherV3,
+    query: list[int],
+    chunk_size: int,
+    chain_walk_fn=None,
+) -> OptimalLookupResult:
+    """Chain walk + filtered matcher probe + three-bucket partition.
+
+    Args:
+        matcher: V3 matcher with registered chunks.
+        query: Query token sequence.
+        chunk_size: Chunk size.
+        chain_walk_fn: Optional callable ``(query, chunk_size) -> list[CBMatchResult]``
+            that simulates the chain-walk storage probe **without** touching the
+            matcher. When provided and it covers the full query, the matcher
+            probe is skipped (early-out). When ``None``, the chain walk is
+            derived from the matcher's own output (no early-out — used by
+            equivalence tests to keep the implementation closed-form).
+    """
+    num_chunks = len(query) // chunk_size
+
+    if chain_walk_fn is not None:
+        prefix_hits = chain_walk_fn(query, chunk_size)
+        if len(prefix_hits) == num_chunks:
+            return OptimalLookupResult(
+                prefix_hits=prefix_hits, cb_aligned=[], cb_shifted=[]
+            )
+        K = len(prefix_hits)
+        matches = _greedy_leftmost_dedupe(matcher.match_sub_sequence(query))
+    else:
+        matches = _greedy_leftmost_dedupe(matcher.match_sub_sequence(query))
+        aligned_by_chunk: dict[int, CBMatchResult] = {}
+        for m in matches:
+            if m.cur_st % chunk_size == 0 and m.old_st == m.cur_st:
+                aligned_by_chunk.setdefault(m.cur_st // chunk_size, m)
+        prefix_hits = _simulate_chain_walk(aligned_by_chunk, num_chunks)
+        K = len(prefix_hits)
+
+    cb_aligned: list[CBMatchResult] = []
+    cb_shifted: list[CBMatchResult] = []
+    for m in matches:
+        if m.cur_st // chunk_size < K:
+            continue  # already covered by prefix_hits
+        if m.old_st == m.cur_st:
+            cb_aligned.append(m)
+        else:
+            cb_shifted.append(m)
+
+    return OptimalLookupResult(
+        prefix_hits=prefix_hits,
+        cb_aligned=cb_aligned,
+        cb_shifted=cb_shifted,
+    )
+
+
+def make_chain_walk_storage(
+    stored_chunks: list[tuple[int, list[int]]],
+) -> Callable:
+    """Build a chain-walk callable backed by a dict.
+
+    Models the real chain-walk path: walks contiguous chunks from position 0,
+    probes a fast in-memory map keyed by ``(chunk_idx, tuple(tokens))``, stops
+    at the first miss. **Does not** touch the matcher.
+
+    Args:
+        stored_chunks: List of ``(chunk_idx, tokens)`` pairs known to be in
+            storage at that chunk index.
+
+    Returns:
+        Function ``(query, chunk_size) -> list[CBMatchResult]``.
+    """
+    storage: dict[tuple[int, tuple[int, ...]], bytes] = {}
+    for idx, toks in stored_chunks:
+        storage[(idx, tuple(toks))] = ObjectKey.IntHash2Bytes(900000 + idx)
+
+    def walk(query: list[int], chunk_size: int) -> list[CBMatchResult]:
+        out: list[CBMatchResult] = []
+        for i in range(len(query) // chunk_size):
+            toks = tuple(query[i * chunk_size : (i + 1) * chunk_size])
+            h = storage.get((i, toks))
+            if h is None:
+                break
+            out.append(
+                CBMatchResult(
+                    old_st=i * chunk_size,
+                    old_ed=(i + 1) * chunk_size,
+                    cur_st=i * chunk_size,
+                    cur_ed=(i + 1) * chunk_size,
+                    hash=h,
+                )
+            )
+        return out
+
+    return walk
+
+
+def match_strided(
+    matcher: BlendTokenRangeMatcherV3,
+    query: list[int],
+    chunk_size: int,
+    stride: int,
+    start_pos: int = 0,
+) -> list[CBMatchResult]:
+    """Aligned-only probe — same hash function as V3 but only probes
+    positions ``{start_pos, start_pos + stride, start_pos + 2*stride, ...}``.
+
+    Equivalent to V3 ``match_sub_sequence`` post-filtered to
+    ``cur_st % stride == 0 and cur_st >= start_pos``, except this version
+    does not visit non-strided positions in its probe loop, so it scales
+    as ``O(N / stride)`` instead of ``O(N)``.
+
+    Accesses matcher internals directly — module test only.
+
+    Args:
+        matcher: V3 matcher with registered chunks.
+        query: Query token sequence.
+        chunk_size: Chunk size (must match matcher.chunk_size).
+        stride: Step between probe positions (e.g., BLOCK_SIZE).
+        start_pos: First position to probe (used for trim — skip the
+            chain-walk-covered prefix).
+    """
+    if len(query) < chunk_size:
+        return []
+    arr = np.array(query, dtype=np.uint64)
+    rolling = rolling_hash_windows_numba(arr, chunk_size, matcher._BASE)
+    n_positions = rolling.shape[0]
+
+    with matcher._lock:
+        if not matcher._chunk_token_hash:
+            return []
+
+        results: list[CBMatchResult] = []
+        seen_cids: set[int] = set()
+        mask = int(matcher._mask)
+        for q_pos in range(start_pos, n_positions, stride):
+            r = int(rolling[q_pos])
+            cid = int(matcher._table_id[r & mask])
+            if cid < 0 or cid in seen_cids:
+                continue
+            if r != matcher._chunk_poly_hash[cid]:
+                continue  # bucket collision
+            th = matcher._chunk_token_hash[cid]
+            if th is None:
+                continue  # evicted
+            old_st = matcher._token_hash_to_start.get(th)
+            if old_st is None:
+                continue
+            seen_cids.add(cid)
+            results.append(
+                CBMatchResult(
+                    old_st=old_st,
+                    old_ed=old_st + chunk_size,
+                    cur_st=q_pos,
+                    cur_ed=q_pos + chunk_size,
+                    hash=th,
+                )
+            )
+        return results
+
+
+def optimal_lookup_aligned(
+    matcher: BlendTokenRangeMatcherV3,
+    query: list[int],
+    chunk_size: int,
+    block_size: int,
+    chain_walk_fn,
+) -> OptimalLookupResult:
+    """Chain walk + block-aligned probe + chain-walk trim + fused partition.
+
+    Implements Opts 1–3 from the design discussion:
+    * Probe only at ``block_size`` stride (Opt 1) — zero coverage loss vs
+      V3 because retrieve already drops non-block-aligned ``cur_st``.
+    * Trim probe range to skip ``[0, K * chunk_size)`` (Opt 2) — the
+      chain walk already covers it.
+    * Partition into aligned/shifted in the same pass as the probe
+      (Opt 3) — no extra Python loop.
+    """
+    num_chunks = len(query) // chunk_size
+
+    prefix_hits = chain_walk_fn(query, chunk_size)
+    if len(prefix_hits) == num_chunks:
+        return OptimalLookupResult(
+            prefix_hits=prefix_hits, cb_aligned=[], cb_shifted=[]
+        )
+    K = len(prefix_hits)
+    start_pos = K * chunk_size
+
+    raw = match_strided(matcher, query, chunk_size, block_size, start_pos=start_pos)
+    raw = _greedy_leftmost_dedupe(raw)
+
+    cb_aligned: list[CBMatchResult] = []
+    cb_shifted: list[CBMatchResult] = []
+    for m in raw:
+        if m.old_st == m.cur_st:
+            cb_aligned.append(m)
+        else:
+            cb_shifted.append(m)
+
+    return OptimalLookupResult(
+        prefix_hits=prefix_hits, cb_aligned=cb_aligned, cb_shifted=cb_shifted
+    )
+
+
+# ---------------------------------------------------------------------------
+# Equivalence assertions
+# ---------------------------------------------------------------------------
+
+
+def _match_key(m: CBMatchResult) -> tuple[int, int, bytes]:
+    return (m.cur_st, m.old_st, m.hash)
+
+
+def assert_equivalent(
+    v3_result: list[CBMatchResult],
+    opt: OptimalLookupResult,
+) -> None:
+    """Optimal's three buckets cover the V3 list with no overlap and same classes."""
+    union = opt.prefix_hits + opt.cb_aligned + opt.cb_shifted
+
+    # 1. Union == V3 (same set of match keys).
+    v3_keys = {_match_key(m) for m in v3_result}
+    union_keys = {_match_key(m) for m in union}
+    assert union_keys == v3_keys, (
+        f"Union mismatch:\n  V3 only:   {v3_keys - union_keys}\n  "
+        f"Opt only:  {union_keys - v3_keys}"
+    )
+
+    # 2. No bucket overlap.
+    p_keys = {_match_key(m) for m in opt.prefix_hits}
+    a_keys = {_match_key(m) for m in opt.cb_aligned}
+    s_keys = {_match_key(m) for m in opt.cb_shifted}
+    assert not (p_keys & a_keys), "prefix_hits ∩ cb_aligned non-empty"
+    assert not (p_keys & s_keys), "prefix_hits ∩ cb_shifted non-empty"
+    assert not (a_keys & s_keys), "cb_aligned ∩ cb_shifted non-empty"
+
+    # 3. cb_shifted ↔ old_st != cur_st; prefix_hits ∪ cb_aligned ↔ aligned.
+    for m in opt.prefix_hits:
+        assert m.old_st == m.cur_st, "prefix_hits contains shifted match"
+    for m in opt.cb_aligned:
+        assert m.old_st == m.cur_st, "cb_aligned contains shifted match"
+    for m in opt.cb_shifted:
+        assert m.old_st != m.cur_st, "cb_shifted contains aligned match"
+
+    # 4. prefix_hits is contiguous from chunk 0 and strictly ordered.
+    for i, m in enumerate(opt.prefix_hits):
+        assert m.cur_st == i * CHUNK_SIZE, (
+            f"prefix_hits[{i}].cur_st = {m.cur_st}, expected {i * CHUNK_SIZE}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Test fixtures
+# ---------------------------------------------------------------------------
+
+
+def _register(
+    matcher: BlendTokenRangeMatcherV3,
+    tokens: list[int],
+    chunk_hash_seeds: list[int],
+    position_offset: int = 0,
+    start_chunk_idx: int = 0,
+) -> None:
+    hashes = [ObjectKey.IntHash2Bytes(s) for s in chunk_hash_seeds]
+    matcher.on_new_token_hashes(
+        tokens,
+        hashes,
+        start_chunk_idx=start_chunk_idx,
+        position_offset=position_offset,
+    )
+
+
+def _chunk(seed: int) -> list[int]:
+    """Deterministic chunk_size tokens derived from seed; unique per seed."""
+    return [seed * CHUNK_SIZE + i + 1 for i in range(CHUNK_SIZE)]
+
+
+# ---------------------------------------------------------------------------
+# Test cases
+# ---------------------------------------------------------------------------
+
+
+class TestOptimizedLookupEquivalence:
+    """Same matcher, two lookup paths — outputs must be equivalent."""
+
+    def test_full_prefix_hit(self):
+        """Query == stored sequence verbatim → all chunks become prefix_hits."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        stored = _chunk(1) + _chunk(2) + _chunk(3) + _chunk(4)
+        _register(matcher, stored, [101, 102, 103, 104])
+
+        v3 = current_v3_lookup(matcher, stored)
+        opt = optimal_lookup(matcher, stored, CHUNK_SIZE)
+
+        assert_equivalent(v3, opt)
+        assert len(opt.prefix_hits) == 4
+        assert opt.cb_aligned == []
+        assert opt.cb_shifted == []
+
+    def test_no_hits(self):
+        """Disjoint query → empty result, empty buckets."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        _register(matcher, _chunk(1) + _chunk(2), [201, 202])
+
+        query = _chunk(9) + _chunk(8)
+        v3 = current_v3_lookup(matcher, query)
+        opt = optimal_lookup(matcher, query, CHUNK_SIZE)
+
+        assert v3 == []
+        assert opt.prefix_hits == []
+        assert opt.cb_aligned == []
+        assert opt.cb_shifted == []
+
+    def test_segmented_prefix_aligned_gap(self):
+        """First chunk differs (chain breaks at 0), later chunks align positionally.
+
+        Stored: [A B C D] at positions 0..4*c
+        Query:  [X B C D] — chunk 0 differs, chunks 1..3 are aligned hits.
+        Expected: prefix_hits=[], cb_aligned=[chunk1..chunk3], cb_shifted=[].
+        """
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a, b, c, d, x = _chunk(1), _chunk(2), _chunk(3), _chunk(4), _chunk(99)
+        stored = a + b + c + d
+        _register(matcher, stored, [301, 302, 303, 304])
+
+        query = x + b + c + d
+        v3 = current_v3_lookup(matcher, query)
+        opt = optimal_lookup(matcher, query, CHUNK_SIZE)
+
+        assert_equivalent(v3, opt)
+        assert opt.prefix_hits == []
+        assert len(opt.cb_aligned) == 3
+        assert opt.cb_shifted == []
+        for i, m in enumerate(opt.cb_aligned, start=1):
+            assert m.cur_st == i * CHUNK_SIZE
+            assert m.old_st == m.cur_st
+
+    def test_pure_non_prefix_shifted(self):
+        """Stored chunk reappears at a different position → cb_shifted only."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a, b = _chunk(1), _chunk(2)
+        stored = a + b
+        _register(matcher, stored, [401, 402])
+
+        # Insert two filler chunks before chunk 'b' — pushes it to position 3*c.
+        f1, f2, f3 = _chunk(50), _chunk(51), _chunk(52)
+        query = f1 + f2 + f3 + b
+        v3 = current_v3_lookup(matcher, query)
+        opt = optimal_lookup(matcher, query, CHUNK_SIZE)
+
+        assert_equivalent(v3, opt)
+        assert opt.prefix_hits == []
+        assert opt.cb_aligned == []
+        assert len(opt.cb_shifted) == 1
+        m = opt.cb_shifted[0]
+        assert m.old_st == CHUNK_SIZE  # was second chunk in stored seq
+        assert m.cur_st == 3 * CHUNK_SIZE  # now at position 3 in query
+
+    def test_mixed_prefix_then_shifted(self):
+        """Contiguous prefix hit, chain break, shifted hit past the break."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a, b, c, d = _chunk(1), _chunk(2), _chunk(3), _chunk(4)
+        stored_main = a + b + c + d  # registered as a single 4-chunk run
+        _register(matcher, stored_main, [501, 502, 503, 504])
+        # Separately register chunk 'd' as if it had been stored at position 0
+        # — gives us a registration with old_st=0 we can shift in a query.
+        _register(matcher, d, [505])
+
+        # Query: a, b, unrelated, d. Prefix hits = [a, b]; shifted = [d@0 → 3c].
+        g1 = _chunk(60)
+        query = a + b + g1 + d
+        v3 = current_v3_lookup(matcher, query)
+        opt = optimal_lookup(matcher, query, CHUNK_SIZE)
+
+        assert_equivalent(v3, opt)
+        # 'd' has multiple stored registrations; matcher picks one. Just check shapes.
+        assert len(opt.prefix_hits) == 2
+        # 'd' at query position 3c could match either old_st=3c (aligned) or
+        # old_st=0 (shifted).
+        assert len(opt.cb_aligned) + len(opt.cb_shifted) == 1
+
+    def test_mixed_prefix_gap_shifted(self):
+        """Prefix hit at chunk 0, gap, aligned hit, shifted hit — all three buckets."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a, b, c = _chunk(1), _chunk(2), _chunk(3)
+        # Register one sequence [a, b, c] with positions 0, c, 2c
+        _register(matcher, a + b + c, [601, 602, 603])
+        # Register chunk 'c' alone, recorded at position 0 — shifted candidate.
+        _register(matcher, c, [604])
+
+        # Query: a (prefix), unrelated (gap), c at 2c (aligned), c again at 3c.
+        g = _chunk(70)
+        query = a + g + c + c
+        v3 = current_v3_lookup(matcher, query)
+        opt = optimal_lookup(matcher, query, CHUNK_SIZE)
+
+        assert_equivalent(v3, opt)
+        # Prefix walk reaches chunk 0 only (chunk 1 is unrelated).
+        assert len(opt.prefix_hits) == 1
+        assert opt.prefix_hits[0].cur_st == 0
+        assert opt.prefix_hits[0].old_st == 0
+
+    def test_partial_sequence_registration(self):
+        """Registration with position_offset > 0; queries find at that offset."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        b, c = _chunk(2), _chunk(3)
+        # Pretend b, c were stored at absolute positions [c, 2c] — register with offset.
+        _register(matcher, b + c, [701, 702], position_offset=CHUNK_SIZE)
+
+        # Query containing b, c at positions c, 2c — both aligned (cb_aligned).
+        a = _chunk(80)
+        query = a + b + c
+        v3 = current_v3_lookup(matcher, query)
+        opt = optimal_lookup(matcher, query, CHUNK_SIZE)
+
+        assert_equivalent(v3, opt)
+        # Chunk 0 (a) has no registration → prefix walk stops at 0.
+        assert opt.prefix_hits == []
+        # b, c found at their original positions → both aligned.
+        assert len(opt.cb_aligned) == 2
+        assert opt.cb_shifted == []
+
+
+class TestOptimizedLookupTiming:
+    """Timing comparison — informational only, no asserts.
+
+    The optimal path's win comes from its **early-out**: when the chain walk
+    covers the whole query, the matcher is skipped entirely. The tests below
+    drive ``optimal_lookup`` with a chain-walk callable backed by a dict, so
+    the timing reflects the real cost model (chain walk = O(K) dict probes,
+    matcher = O(N) numba probe).
+    """
+
+    @pytest.mark.parametrize(
+        "n_chunks,scenario",
+        [
+            (128, "full_prefix"),  # K = N → early-out, matcher skipped
+            (
+                128,
+                "no_prefix_shifted",
+            ),  # K = 0 → chain walk fails fast, matcher does all
+            (128, "half_prefix"),  # K = N/2 → both pay something
+        ],
+    )
+    def test_timing(self, n_chunks, scenario, capsys):
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        stored: list[int] = []
+        seeds = []
+        chunks_for_storage: list[tuple[int, list[int]]] = []
+        for i in range(n_chunks):
+            c = _chunk(i)
+            stored.extend(c)
+            seeds.append(1000 + i)
+            chunks_for_storage.append((i, c))
+        _register(matcher, stored, seeds)
+        chain_walk = make_chain_walk_storage(chunks_for_storage)
+
+        if scenario == "full_prefix":
+            query = list(stored)
+        elif scenario == "no_prefix_shifted":
+            rotated: list[int] = []
+            for i in range(n_chunks):
+                rotated.extend(_chunk((i + 1) % n_chunks))
+            query = rotated
+        elif scenario == "half_prefix":
+            half = n_chunks // 2
+            query = stored[: half * CHUNK_SIZE]
+            for i in range(half, n_chunks):
+                query.extend(_chunk((i + 1) % n_chunks))
+        else:
+            raise ValueError(scenario)
+
+        # Warm up numba JIT.
+        matcher.match_sub_sequence(query)
+        chain_walk(query, CHUNK_SIZE)
+
+        n_iter = 50
+        t0 = time.perf_counter()
+        for _ in range(n_iter):
+            current_v3_lookup(matcher, query)
+        t_v3 = (time.perf_counter() - t0) / n_iter * 1e6  # µs
+
+        t0 = time.perf_counter()
+        for _ in range(n_iter):
+            optimal_lookup(matcher, query, CHUNK_SIZE, chain_walk_fn=chain_walk)
+        t_opt = (time.perf_counter() - t0) / n_iter * 1e6  # µs
+
+        with capsys.disabled():
+            print(
+                f"\n  [{scenario:>20s}] N={n_chunks:>4d} chunks  "
+                f"V3={t_v3:8.1f}µs  OPT={t_opt:8.1f}µs  "
+                f"OPT/V3={t_opt / t_v3:.2f}x"
+            )
+
+
+# =============================================================================
+# Block-aligned probe (Opt 1) + trim (Opt 2) + fused partition (Opt 3)
+# =============================================================================
+
+
+def _v3_filtered_to_block_aligned(
+    v3_result: list[CBMatchResult], block_size: int
+) -> set[tuple[int, int, bytes]]:
+    """Set of V3 matches that survive retrieve's ``cur_st % block_size == 0`` drop.
+
+    Strided probe's correctness target: it must find at least every
+    block-aligned chunk-content occurrence in the query. V3's first-cur_st
+    behavior may keep a non-block-aligned position for a chunk that also
+    has a block-aligned occurrence; the strided probe will find the
+    block-aligned occurrence instead. So the strided probe is a superset
+    by **content** (hash) of what V3 surfaces after the retrieve filter.
+    """
+    return {_match_key(m) for m in v3_result if m.cur_st % block_size == 0}
+
+
+class TestStridedProbe:
+    """Block-aligned probe must give zero-loss coverage vs V3 + retrieve filter."""
+
+    def test_returns_only_block_aligned_cur_st(self):
+        """Every match has cur_st divisible by BLOCK_SIZE."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a, b = _chunk(1), _chunk(2)
+        _register(matcher, a + b, [801, 802])
+
+        # Insert a 32-token shim (block-aligned, not chunk-aligned).
+        shim = list(range(70000, 70032))  # length 32 = 2 * BLOCK_SIZE
+        query = shim + a + b
+        results = match_strided(matcher, query, CHUNK_SIZE, BLOCK_SIZE)
+
+        assert len(results) >= 1
+        for r in results:
+            assert r.cur_st % BLOCK_SIZE == 0
+
+    def test_finds_block_aligned_shifted_match(self):
+        """Stored chunk at block-aligned, non-chunk-aligned query pos → found.
+
+        V3 (stride=1) finds these too; strided (stride=block) must as well.
+        """
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a = _chunk(1)
+        _register(matcher, a, [901])
+
+        # Query: 32-token prefix (block-aligned but not chunk-aligned start).
+        shim = list(range(80000, 80032))
+        query = shim + a
+        results = match_strided(matcher, query, CHUNK_SIZE, BLOCK_SIZE)
+
+        assert len(results) == 1
+        assert results[0].old_st == 0
+        assert results[0].cur_st == 32
+        assert results[0].cur_st % BLOCK_SIZE == 0
+
+    def test_zero_loss_vs_v3_filtered(self):
+        """Strided probe content-hash set ⊇ V3 set filtered to block-aligned cur_st."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        chunks = [_chunk(i) for i in range(5)]
+        stored = sum(chunks, [])
+        _register(matcher, stored, [1100 + i for i in range(5)])
+
+        # Mixed query: shifted by 48 tokens (3 * BLOCK_SIZE, not chunk-aligned).
+        shim = list(range(90000, 90048))
+        query = shim + stored
+
+        v3 = current_v3_lookup(matcher, query)
+        v3_block_aligned = _v3_filtered_to_block_aligned(v3, BLOCK_SIZE)
+        strided = match_strided(matcher, query, CHUNK_SIZE, BLOCK_SIZE)
+        strided_hashes = {m.hash for m in strided}
+        v3_block_aligned_hashes = {key[2] for key in v3_block_aligned}
+
+        # Every block-aligned-cur_st hit that V3 surfaces must be discoverable
+        # by the strided probe (same hash). Strided may discover additional
+        # block-aligned occurrences that V3 dropped in favor of an earlier
+        # non-block-aligned cur_st.
+        assert v3_block_aligned_hashes <= strided_hashes, (
+            f"Strided missed hashes V3 found:\n"
+            f"  v3 block-aligned: {v3_block_aligned_hashes}\n"
+            f"  strided:          {strided_hashes}"
+        )
+
+    def test_trim_skips_prefix_range(self):
+        """``start_pos > 0`` skips the chain-walk-covered prefix."""
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        a, b, c = _chunk(1), _chunk(2), _chunk(3)
+        _register(matcher, a + b + c, [1201, 1202, 1203])
+
+        query = a + b + c
+        # start_pos at chunk 1's beginning: must skip chunk 0's match.
+        strided = match_strided(
+            matcher, query, CHUNK_SIZE, BLOCK_SIZE, start_pos=CHUNK_SIZE
+        )
+
+        assert len(strided) == 2
+        for r in strided:
+            assert r.cur_st >= CHUNK_SIZE
+
+
+class TestOptimalLookupAligned:
+    """End-to-end equivalence for optimal_lookup_aligned."""
+
+    def _make(self):
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        chunks = [_chunk(i) for i in range(4)]
+        stored = sum(chunks, [])
+        _register(matcher, stored, [1300 + i for i in range(4)])
+        chain_walk = make_chain_walk_storage(list(enumerate(chunks)))
+        return matcher, stored, chunks, chain_walk
+
+    def test_full_prefix_early_out(self):
+        matcher, stored, _, chain_walk = self._make()
+        opt = optimal_lookup_aligned(
+            matcher, stored, CHUNK_SIZE, BLOCK_SIZE, chain_walk
+        )
+        assert len(opt.prefix_hits) == 4
+        assert opt.cb_aligned == []
+        assert opt.cb_shifted == []
+
+    def test_segmented_prefix(self):
+        """Chunk 0 mismatch → cb_aligned picks up the rest with no re-rope."""
+        matcher, _, chunks, chain_walk = self._make()
+        x = _chunk(99)
+        query = x + chunks[1] + chunks[2] + chunks[3]
+        opt = optimal_lookup_aligned(matcher, query, CHUNK_SIZE, BLOCK_SIZE, chain_walk)
+        assert opt.prefix_hits == []
+        assert len(opt.cb_aligned) == 3
+        assert opt.cb_shifted == []
+        for m in opt.cb_aligned:
+            assert m.old_st == m.cur_st
+            assert m.cur_st % BLOCK_SIZE == 0
+
+    def test_shifted_at_block_boundary(self):
+        """Stored chunk appears at block-aligned but not chunk-aligned cur_st."""
+        matcher, _, chunks, chain_walk = self._make()
+        shim = list(range(80000, 80032))  # 32 tokens = 2 * BLOCK_SIZE
+        query = shim + chunks[1] + chunks[2]
+        opt = optimal_lookup_aligned(matcher, query, CHUNK_SIZE, BLOCK_SIZE, chain_walk)
+
+        # Chunk 0 of query is the shim → chain walk stops at 0.
+        assert opt.prefix_hits == []
+        # chunks[1], chunks[2] appear at cur_st=32, 288 — both shifted from stored.
+        assert opt.cb_aligned == []
+        assert len(opt.cb_shifted) == 2
+        for m in opt.cb_shifted:
+            assert m.cur_st % BLOCK_SIZE == 0
+            assert m.old_st != m.cur_st
+
+
+class TestOptimalLookupAlignedTiming:
+    """Cost of optimal_lookup_aligned vs current V3, with chain-walk early-out."""
+
+    @pytest.mark.parametrize(
+        "n_chunks,scenario",
+        [
+            (128, "full_prefix"),
+            (128, "no_prefix_shifted"),
+            (128, "half_prefix"),
+        ],
+    )
+    def test_timing(self, n_chunks, scenario, capsys):
+        matcher = BlendTokenRangeMatcherV3(chunk_size=CHUNK_SIZE)
+        stored: list[int] = []
+        seeds = []
+        chunks_for_storage: list[tuple[int, list[int]]] = []
+        for i in range(n_chunks):
+            c = _chunk(i)
+            stored.extend(c)
+            seeds.append(2000 + i)
+            chunks_for_storage.append((i, c))
+        _register(matcher, stored, seeds)
+        chain_walk = make_chain_walk_storage(chunks_for_storage)
+
+        if scenario == "full_prefix":
+            query = list(stored)
+        elif scenario == "no_prefix_shifted":
+            rotated: list[int] = []
+            for i in range(n_chunks):
+                rotated.extend(_chunk((i + 1) % n_chunks))
+            query = rotated
+        elif scenario == "half_prefix":
+            half = n_chunks // 2
+            query = stored[: half * CHUNK_SIZE]
+            for i in range(half, n_chunks):
+                query.extend(_chunk((i + 1) % n_chunks))
+        else:
+            raise ValueError(scenario)
+
+        # Warm up numba JIT for both kernels.
+        matcher.match_sub_sequence(query)
+        match_strided(matcher, query, CHUNK_SIZE, BLOCK_SIZE)
+        chain_walk(query, CHUNK_SIZE)
+
+        n_iter = 50
+        t0 = time.perf_counter()
+        for _ in range(n_iter):
+            current_v3_lookup(matcher, query)
+        t_v3 = (time.perf_counter() - t0) / n_iter * 1e6
+
+        t0 = time.perf_counter()
+        for _ in range(n_iter):
+            optimal_lookup_aligned(matcher, query, CHUNK_SIZE, BLOCK_SIZE, chain_walk)
+        t_opt = (time.perf_counter() - t0) / n_iter * 1e6
+
+        with capsys.disabled():
+            print(
+                f"\n  [{scenario:>20s}] N={n_chunks:>4d} chunks  "
+                f"V3={t_v3:8.1f}µs  ALIGNED={t_opt:8.1f}µs  "
+                f"speedup={t_v3 / t_opt:.1f}x"
+            )
diff --git a/tests/v1/multiprocess/test_p2p_controller.py b/tests/v1/multiprocess/test_p2p_controller.py
new file mode 100644
index 0000000..df4b8a9
--- /dev/null
+++ b/tests/v1/multiprocess/test_p2p_controller.py
@@ -0,0 +1,485 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the P2P protocol and P2PController: enum registration, protocol
+definitions, MemoryLayoutDesc wire serialization, and server handlers.
+"""
+
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+import httpx
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc, ObjectKey
+from lmcache.v1.distributed.l2_adapters.p2p_l2_adapter import P2PL2AdapterConfig
+from lmcache.v1.distributed.transfer_channel.api import TransferChannelAddress
+from lmcache.v1.multiprocess.config import CoordinatorConfig, P2PConfig
+from lmcache.v1.multiprocess.modules.p2p_controller import (
+    _MAX_MISSES,
+    P2PController,
+    _P2PState,
+    _PeerInstance,
+)
+from lmcache.v1.multiprocess.mq import msgspec_decode, msgspec_encode
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    get_handler_type,
+    get_payload_classes,
+    get_response_class,
+)
+from lmcache.v1.multiprocess.protocols.base import HandlerType
+
+
+def _make_key(i: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=f"hash{i}".encode(),
+        model_name="test_model",
+        kv_rank=1,
+    )
+
+
+def _make_layout_desc() -> MemoryLayoutDesc:
+    return MemoryLayoutDesc(
+        shapes=[torch.Size([2, 3]), torch.Size([4])],
+        dtypes=[torch.float16, torch.bfloat16],
+    )
+
+
+# ============================================================================
+# Protocol definition tests
+# ============================================================================
+
+
+def test_p2p_request_types_registered():
+    """The three P2P request types should be members of RequestType."""
+    for name in (
+        "P2P_LOOKUP_AND_LOCK",
+        "P2P_QUERY_LOOKUP_RESULTS",
+        "P2P_UNLOCK_OBJECTS",
+    ):
+        assert hasattr(RequestType, name)
+        assert isinstance(getattr(RequestType, name), RequestType)
+
+
+def test_p2p_lookup_and_lock_protocol():
+    """P2P_LOOKUP_AND_LOCK payload is [list[ObjectKey], MemoryLayoutDesc],
+    returns int, and is BLOCKING."""
+    payload_classes = get_payload_classes(RequestType.P2P_LOOKUP_AND_LOCK)
+    assert payload_classes == [list[ObjectKey], MemoryLayoutDesc]
+    assert get_response_class(RequestType.P2P_LOOKUP_AND_LOCK) is int
+    assert get_handler_type(RequestType.P2P_LOOKUP_AND_LOCK) == HandlerType.BLOCKING
+
+
+def test_p2p_query_lookup_results_protocol():
+    """P2P_QUERY_LOOKUP_RESULTS payload is [int], returns the optional address
+    list, and is BLOCKING."""
+    assert get_payload_classes(RequestType.P2P_QUERY_LOOKUP_RESULTS) == [int]
+    assert (
+        get_response_class(RequestType.P2P_QUERY_LOOKUP_RESULTS)
+        == list[TransferChannelAddress] | None
+    )
+    assert (
+        get_handler_type(RequestType.P2P_QUERY_LOOKUP_RESULTS) == HandlerType.BLOCKING
+    )
+
+
+def test_p2p_unlock_objects_protocol():
+    """P2P_UNLOCK_OBJECTS payload is [list[ObjectKey]], returns None, BLOCKING."""
+    assert get_payload_classes(RequestType.P2P_UNLOCK_OBJECTS) == [list[ObjectKey]]
+    assert get_response_class(RequestType.P2P_UNLOCK_OBJECTS) is None
+    assert get_handler_type(RequestType.P2P_UNLOCK_OBJECTS) == HandlerType.BLOCKING
+
+
+# ============================================================================
+# MemoryLayoutDesc serialization tests
+# ============================================================================
+
+
+def test_memory_layout_desc_mq_roundtrip():
+    """The mq encode/decode dispatch must round-trip MemoryLayoutDesc, whose
+    torch.Size / torch.dtype fields ride the customized enc_hook / dec_hook."""
+    desc = MemoryLayoutDesc(
+        shapes=[torch.Size([8, 16, 128]), torch.Size([4])],
+        dtypes=[torch.float32, torch.int8],
+    )
+    decoded = msgspec_decode(
+        msgspec_encode(desc, cls=MemoryLayoutDesc), cls=MemoryLayoutDesc
+    )
+    assert decoded == desc
+    assert all(isinstance(s, torch.Size) for s in decoded.shapes)
+    assert all(isinstance(d, torch.dtype) for d in decoded.dtypes)
+
+
+def test_memory_layout_desc_empty_mq_roundtrip():
+    """An empty layout descriptor must round-trip through the mq dispatch."""
+    desc = MemoryLayoutDesc(shapes=[], dtypes=[])
+    decoded = msgspec_decode(
+        msgspec_encode(desc, cls=MemoryLayoutDesc), cls=MemoryLayoutDesc
+    )
+    assert decoded == desc
+
+
+# ============================================================================
+# TransferChannelAddress tests
+# ============================================================================
+
+
+def test_transfer_channel_address_validity():
+    """A non-negative offset is valid; a negative one is not."""
+    assert TransferChannelAddress(offset=128, size=64).is_valid()
+    assert not TransferChannelAddress(offset=-1, size=0).is_valid()
+
+
+# ============================================================================
+# Server handler tests
+# ============================================================================
+
+
+def _make_controller() -> tuple[P2PController, MagicMock]:
+    """Build a P2P-disabled controller (no thread / transfer channel)."""
+    ctx = MagicMock()
+    controller = P2PController(
+        ctx,
+        P2PConfig(),
+        CoordinatorConfig(),
+        instance_id="self",
+    )
+    return controller, ctx
+
+
+def test_lookup_and_lock_submits_skip_l2_and_returns_task_id():
+    """p2p_lookup_and_lock submits a skip_l2 prefetch and returns a fresh id."""
+    controller, ctx = _make_controller()
+    handle = MagicMock(l1_found_indices=(0, 1))
+    ctx.storage_manager.submit_prefetch_task.return_value = handle
+
+    keys = [_make_key(0), _make_key(1)]
+    layout_desc = _make_layout_desc()
+    task_id = controller.p2p_lookup_and_lock(keys, layout_desc)
+
+    assert task_id == 0
+    args, kwargs = ctx.storage_manager.submit_prefetch_task.call_args
+    assert args[0] == keys
+    assert args[1] is layout_desc
+    assert kwargs["skip_l2"] is True
+    # A second call gets a distinct id.
+    assert controller.p2p_lookup_and_lock(keys, layout_desc) == 1
+
+
+def test_query_lookup_results_builds_addresses_for_prefix():
+    """A completed lookup returns one address per key: real offsets for the
+    found prefix, invalid offsets for the rest."""
+    controller, ctx = _make_controller()
+    handle = MagicMock(l1_found_indices=(0, 1))
+    ctx.storage_manager.submit_prefetch_task.return_value = handle
+
+    keys = [_make_key(0), _make_key(1), _make_key(2)]
+    task_id = controller.p2p_lookup_and_lock(keys, _make_layout_desc())
+
+    found = MagicMock()
+    found.count_leading_ones.return_value = 2
+    ctx.storage_manager.query_prefetch_status.return_value = found
+    obj0 = MagicMock(shm_offset=100, shm_byte_length=10)
+    obj1 = MagicMock(shm_offset=200, shm_byte_length=20)
+    ctx.storage_manager.unsafe_read.return_value = ([keys[0], keys[1]], [obj0, obj1])
+
+    addresses = controller.p2p_query_lookup_results(task_id)
+    assert addresses == [
+        TransferChannelAddress(offset=100, size=10),
+        TransferChannelAddress(offset=200, size=20),
+        TransferChannelAddress(offset=-1, size=0),
+    ]
+
+
+def test_query_lookup_results_exactly_once():
+    """Re-querying a completed task returns None (the job is consumed)."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.submit_prefetch_task.return_value = MagicMock(
+        l1_found_indices=()
+    )
+    task_id = controller.p2p_lookup_and_lock([_make_key(0)], _make_layout_desc())
+
+    found = MagicMock()
+    found.count_leading_ones.return_value = 0
+    ctx.storage_manager.query_prefetch_status.return_value = found
+
+    assert controller.p2p_query_lookup_results(task_id) == [
+        TransferChannelAddress(offset=-1, size=0)
+    ]
+    assert controller.p2p_query_lookup_results(task_id) is None
+
+
+def test_query_lookup_results_unknown_task():
+    """Querying an unknown task id returns None."""
+    controller, _ = _make_controller()
+    assert controller.p2p_query_lookup_results(999) is None
+
+
+def test_query_lookup_results_in_progress():
+    """A lookup whose prefetch is not done yet returns None without consuming
+    the job."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.submit_prefetch_task.return_value = MagicMock(
+        l1_found_indices=()
+    )
+    task_id = controller.p2p_lookup_and_lock([_make_key(0)], _make_layout_desc())
+
+    ctx.storage_manager.query_prefetch_status.return_value = None
+    assert controller.p2p_query_lookup_results(task_id) is None
+    # Job is still alive; status flips to done on the next poll.
+    found = MagicMock()
+    found.count_leading_ones.return_value = 0
+    ctx.storage_manager.query_prefetch_status.return_value = found
+    assert controller.p2p_query_lookup_results(task_id) is not None
+
+
+def test_unlock_objects_calls_finish_read_prefetched():
+    """p2p_unlock_objects forwards the keys to finish_read_prefetched."""
+    controller, ctx = _make_controller()
+    keys = [_make_key(0), _make_key(1)]
+    controller.p2p_unlock_objects(keys)
+    ctx.storage_manager.finish_read_prefetched.assert_called_once_with(keys)
+
+
+def test_unlock_objects_empty_is_noop():
+    """Unlocking an empty key list does nothing."""
+    controller, ctx = _make_controller()
+    controller.p2p_unlock_objects([])
+    ctx.storage_manager.finish_read_prefetched.assert_not_called()
+
+
+def test_report_status_counts_active_jobs():
+    """report_status reflects the number of in-flight lookup jobs."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.submit_prefetch_task.return_value = MagicMock(
+        l1_found_indices=()
+    )
+    assert controller.report_status()["active_p2p_lookup_jobs"] == 0
+    controller.p2p_lookup_and_lock([_make_key(0)], _make_layout_desc())
+    status = controller.report_status()
+    assert status["active_p2p_lookup_jobs"] == 1
+    assert status["p2p_enabled"] is False
+    assert status["p2p_state"] == _P2PState.UNREGISTERED.value
+
+
+def test_get_handlers_covers_all_p2p_request_types():
+    """get_handlers wires exactly the three P2P request types."""
+    controller, _ = _make_controller()
+    request_types = {spec.request_type for spec in controller.get_handlers()}
+    assert request_types == {
+        RequestType.P2P_LOOKUP_AND_LOCK,
+        RequestType.P2P_QUERY_LOOKUP_RESULTS,
+        RequestType.P2P_UNLOCK_OBJECTS,
+    }
+
+
+# ============================================================================
+# Orchestration: adapter reconcile
+# ============================================================================
+
+
+def _peer(
+    instance_id: str,
+    url: str = "tc-host:9",
+    ip: str = "10.0.0.2",
+    mq_port: int = 5555,
+) -> _PeerInstance:
+    return _PeerInstance(
+        instance_id=instance_id,
+        ip=ip,
+        p2p_advertised_url=url,
+        mq_port=mq_port,
+    )
+
+
+def test_reconcile_adds_new_peer():
+    """A newly discovered peer gets one P2P L2 adapter with the right urls."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.return_value = 7
+
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA")})
+
+    ctx.storage_manager.add_l2_adapter.assert_called_once()
+    config = ctx.storage_manager.add_l2_adapter.call_args.args[0]
+    assert isinstance(config, P2PL2AdapterConfig)
+    assert config.peer_mq_server_url == "tcp://10.0.0.2:5555"
+    assert config.peer_transfer_channel_server_url == "tc-host:9"
+    assert controller.report_status()["p2p_peers"] == ["peerA"]
+
+
+def test_reconcile_no_op_when_peer_unchanged():
+    """A still-present, unchanged peer is not re-added on the next cycle."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.return_value = 7
+
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA")})
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA")})
+
+    ctx.storage_manager.add_l2_adapter.assert_called_once()
+    ctx.storage_manager.delete_l2_adapter.assert_not_called()
+
+
+def test_reconcile_keeps_peer_within_grace():
+    """A peer absent for up to _MAX_MISSES cycles keeps its adapter."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.return_value = 7
+
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA")})
+    for _ in range(_MAX_MISSES):
+        controller._apply_state(_P2PState.REGISTERED, {})
+
+    ctx.storage_manager.delete_l2_adapter.assert_not_called()
+    assert controller.report_status()["p2p_peers"] == ["peerA"]
+
+
+def test_reconcile_removes_peer_after_grace():
+    """A peer absent beyond _MAX_MISSES cycles has its adapter removed."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.return_value = 7
+
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA")})
+    for _ in range(_MAX_MISSES + 1):
+        controller._apply_state(_P2PState.REGISTERED, {})
+
+    ctx.storage_manager.delete_l2_adapter.assert_called_once_with(7)
+    assert controller.report_status()["p2p_peers"] == []
+
+
+def test_reconcile_readds_on_url_change():
+    """A peer whose advertised url changes is removed and re-added."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.side_effect = [7, 8]
+
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA", url="a:1")})
+    controller._apply_state(_P2PState.REGISTERED, {"peerA": _peer("peerA", url="b:2")})
+
+    ctx.storage_manager.delete_l2_adapter.assert_called_once_with(7)
+    assert ctx.storage_manager.add_l2_adapter.call_count == 2
+    latest = ctx.storage_manager.add_l2_adapter.call_args.args[0]
+    assert latest.peer_transfer_channel_server_url == "b:2"
+
+
+def test_close_removes_all_adapters():
+    """close drains every tracked peer adapter."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.side_effect = [7, 8]
+    controller._apply_state(
+        _P2PState.REGISTERED,
+        {"peerA": _peer("peerA"), "peerB": _peer("peerB", mq_port=5556)},
+    )
+
+    controller.close()
+
+    removed = {c.args[0] for c in ctx.storage_manager.delete_l2_adapter.call_args_list}
+    assert removed == {7, 8}
+
+
+# ============================================================================
+# Orchestration: poll-cycle state machine
+# ============================================================================
+
+
+def _enable_polling(
+    controller: P2PController, advertise_url: str = "me:1"
+) -> MagicMock:
+    """Point a controller's poll loop at a mock coordinator client."""
+    controller._p2p_config = P2PConfig(advertise_url=advertise_url)
+    controller._instances_url = "http://coordinator/instances"
+    client = MagicMock()
+    controller._http_client = client
+    return client
+
+
+def _instances_response(instances: list[dict]) -> MagicMock:
+    response = MagicMock()
+    response.raise_for_status.return_value = None
+    response.json.return_value = {"instances": instances}
+    return response
+
+
+def _entry(
+    instance_id: str,
+    url: str,
+    ip: str = "10.0.0.9",
+    mq_port: int = 5555,
+) -> dict:
+    return {
+        "instance_id": instance_id,
+        "ip": ip,
+        "p2p_advertised_url": url,
+        "mq_port": mq_port,
+    }
+
+
+def test_poll_cycle_timeout_is_disconnected():
+    """A request timeout maps to the Disconnected state."""
+    controller, _ = _make_controller()
+    client = _enable_polling(controller)
+    client.get.side_effect = httpx.TimeoutException("boom")
+
+    controller._poll_cycle()
+    assert controller.report_status()["p2p_state"] == _P2PState.DISCONNECTED.value
+
+
+def test_poll_cycle_http_error_is_unregistered():
+    """A non-timeout HTTP error maps to the Unregistered state."""
+    controller, _ = _make_controller()
+    client = _enable_polling(controller)
+    client.get.side_effect = httpx.HTTPError("boom")
+
+    controller._poll_cycle()
+    assert controller.report_status()["p2p_state"] == _P2PState.UNREGISTERED.value
+
+
+def test_poll_cycle_self_absent_is_unregistered():
+    """Not finding our own instance in the listing is Unregistered."""
+    controller, _ = _make_controller()
+    client = _enable_polling(controller)
+    client.get.return_value = _instances_response([_entry("other", "tc:1")])
+
+    controller._poll_cycle()
+    assert controller.report_status()["p2p_state"] == _P2PState.UNREGISTERED.value
+
+
+def test_poll_cycle_registered_excludes_self_and_adds_peer():
+    """When registered, peers (but not self) get adapters."""
+    controller, ctx = _make_controller()
+    ctx.storage_manager.add_l2_adapter.return_value = 7
+    client = _enable_polling(controller, advertise_url="me:1")
+    client.get.return_value = _instances_response(
+        [_entry("self", "me:1"), _entry("peerA", "tc:1")]
+    )
+
+    controller._poll_cycle()
+
+    status = controller.report_status()
+    assert status["p2p_state"] == _P2PState.REGISTERED.value
+    assert status["p2p_peers"] == ["peerA"]
+
+
+def test_poll_cycle_unexpected_error_does_not_crash():
+    """An unexpected parsing error is caught and maps to Unregistered."""
+    controller, _ = _make_controller()
+    client = _enable_polling(controller)
+    # A non-dict entry makes parsing raise AttributeError (raw.get on a str).
+    client.get.return_value = _instances_response(["not-a-dict"])
+
+    summary = controller._poll_cycle()  # must not raise
+    assert summary.success is True
+    assert controller.report_status()["p2p_state"] == _P2PState.UNREGISTERED.value
+
+
+def test_poll_cycle_skips_peer_without_p2p_url():
+    """A peer that advertises no p2p url is not adapted."""
+    controller, ctx = _make_controller()
+    client = _enable_polling(controller, advertise_url="me:1")
+    client.get.return_value = _instances_response(
+        [_entry("self", "me:1"), _entry("peerA", "")]
+    )
+
+    controller._poll_cycle()
+
+    ctx.storage_manager.add_l2_adapter.assert_not_called()
+    assert controller.report_status()["p2p_peers"] == []
diff --git a/tests/v1/multiprocess/test_posix_shm.py b/tests/v1/multiprocess/test_posix_shm.py
new file mode 100644
index 0000000..a04497d
--- /dev/null
+++ b/tests/v1/multiprocess/test_posix_shm.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``lmcache.v1.multiprocess.posix_shm``.
+
+Validates the POSIX-SHM primitives and the ``mmap``-based pool helper
+shared by SHM-based transports.
+"""
+
+# Standard
+import os
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.posix_shm import (
+    shm_create_readwrite,
+    shm_map_readwrite,
+    shm_munmap,
+    shm_open_pool_as_mmap,
+    shm_unlink,
+)
+
+
+def _unique_name(tag: str) -> str:
+    # macOS shm_open caps names at 31 bytes incl. leading '/'.
+    return "/lmc_pshm_%s_%d" % (tag, os.getpid())
+
+
+def test_create_map_munmap_unlink_roundtrip():
+    name = _unique_name("rt")
+    addr = shm_create_readwrite(name, 4096)
+    try:
+        assert addr not in (0, None)
+        # Map again from a fresh address: same segment, different vaddr.
+        addr2 = shm_map_readwrite(name, 4096)
+        try:
+            assert addr2 not in (0, None)
+        finally:
+            shm_munmap(addr2, 4096)
+    finally:
+        shm_munmap(addr, 4096)
+        shm_unlink(name)
+
+
+def test_create_excl_collision():
+    name = _unique_name("excl")
+    addr = shm_create_readwrite(name, 4096)
+    try:
+        with pytest.raises(OSError):
+            shm_create_readwrite(name, 4096)
+    finally:
+        shm_munmap(addr, 4096)
+        shm_unlink(name)
+
+
+def test_open_pool_as_mmap_zero_copy_view():
+    name = _unique_name("pool")
+    nbytes = 4096
+    addr = shm_create_readwrite(name, nbytes)
+    try:
+        mm = shm_open_pool_as_mmap(name, nbytes)
+        try:
+            mm[0:4] = b"\x01\x02\x03\x04"
+            mm2 = shm_open_pool_as_mmap(name, nbytes)
+            try:
+                assert bytes(mm2[0:4]) == b"\x01\x02\x03\x04"
+            finally:
+                mm2.close()
+        finally:
+            mm.close()
+    finally:
+        shm_munmap(addr, nbytes)
+        shm_unlink(name)
+
+
+def test_munmap_no_op_on_zero_addr():
+    # Should not crash; best-effort no-op.
+    shm_munmap(0, 4096)
diff --git a/tests/v1/multiprocess/test_query_lookup_hits.py b/tests/v1/multiprocess/test_query_lookup_hits.py
new file mode 100644
index 0000000..7e59001
--- /dev/null
+++ b/tests/v1/multiprocess/test_query_lookup_hits.py
@@ -0,0 +1,305 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the QUERY_PREFETCH_LOOKUP_HITS protocol: enum registration,
+protocol definition, message-queue round-trip, and server handler.
+"""
+
+# Standard
+from unittest.mock import MagicMock
+import time
+
+# First Party
+from lmcache.v1.distributed.api import (
+    AttnWindowDesc,
+    ObjectKey,
+    ipc_key_to_object_keys,
+)
+from lmcache.v1.distributed.storage_manager import PrefetchHandle
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.modules.lookup import LookupModule, _PrefetchJob
+from lmcache.v1.multiprocess.protocol import (
+    RequestType,
+    get_handler_type,
+    get_payload_classes,
+    get_response_class,
+)
+from lmcache.v1.multiprocess.protocols.base import HandlerType
+
+# Test helpers
+from tests.v1.multiprocess.test_mq import (
+    MessageQueueTestHelper,
+)
+
+# ============================================================================
+# Protocol definition tests
+# ============================================================================
+
+
+def test_query_prefetch_lookup_hits_in_request_type():
+    """QUERY_PREFETCH_LOOKUP_HITS should be a member of RequestType."""
+    assert hasattr(RequestType, "QUERY_PREFETCH_LOOKUP_HITS")
+    assert isinstance(RequestType.QUERY_PREFETCH_LOOKUP_HITS, RequestType)
+
+
+def test_query_prefetch_lookup_hits_payload_classes():
+    """QUERY_PREFETCH_LOOKUP_HITS payload should be [str]."""
+    payload_classes = get_payload_classes(RequestType.QUERY_PREFETCH_LOOKUP_HITS)
+    assert len(payload_classes) == 1
+    assert payload_classes[0] is str
+
+
+def test_query_prefetch_lookup_hits_response_class():
+    """QUERY_PREFETCH_LOOKUP_HITS response should be int | None."""
+    response_class = get_response_class(RequestType.QUERY_PREFETCH_LOOKUP_HITS)
+    assert response_class == int | None
+
+
+def test_query_prefetch_lookup_hits_handler_type():
+    """QUERY_PREFETCH_LOOKUP_HITS should use BLOCKING handler type."""
+    handler_type = get_handler_type(RequestType.QUERY_PREFETCH_LOOKUP_HITS)
+    assert handler_type == HandlerType.BLOCKING
+
+
+# ============================================================================
+# Message-queue round-trip test
+# ============================================================================
+
+
+def _query_lookup_hits_handler(request_id: str) -> int | None:
+    """Dummy handler for QUERY_PREFETCH_LOOKUP_HITS requests."""
+    assert isinstance(request_id, str)
+    return 42
+
+
+def test_mq_query_prefetch_lookup_hits():
+    """Test MessageQueue with QUERY_PREFETCH_LOOKUP_HITS request type."""
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5575")
+    helper.register_handler(
+        RequestType.QUERY_PREFETCH_LOOKUP_HITS, _query_lookup_hits_handler
+    )
+
+    helper.run_test(
+        request_type=RequestType.QUERY_PREFETCH_LOOKUP_HITS,
+        payloads=["req-1"],
+        expected_response=42,
+        num_requests=1,
+    )
+
+
+def _query_lookup_hits_none_handler(request_id: str) -> int | None:
+    """Dummy handler that returns None (lookup still in progress)."""
+    assert isinstance(request_id, str)
+    return None
+
+
+def test_mq_query_prefetch_lookup_hits_none_response():
+    """Test MessageQueue returns None when lookup is still in progress."""
+    helper = MessageQueueTestHelper(server_url="tcp://127.0.0.1:5576")
+    helper.register_handler(
+        RequestType.QUERY_PREFETCH_LOOKUP_HITS, _query_lookup_hits_none_handler
+    )
+
+    helper.run_test(
+        request_type=RequestType.QUERY_PREFETCH_LOOKUP_HITS,
+        payloads=["req-1"],
+        expected_response=None,
+        num_requests=1,
+    )
+
+
+# ============================================================================
+# Server handler tests
+# ============================================================================
+
+
+def _make_module_with_job(
+    world_size: int, storage_return: int | None, num_object_groups: int = 1
+) -> tuple[LookupModule, str]:
+    """Create a LookupModule with a mock context and a single prefetch job.
+
+    Returns:
+        (module, request_id)
+    """
+    ctx = MagicMock()
+    ctx.token_hasher.chunk_size = 256
+    module = LookupModule(ctx)
+
+    handle = PrefetchHandle(
+        prefetch_request_id=0,
+        external_request_id="req-0",
+        l1_found_indices=(),
+        total_requested_keys=10,
+        submit_time=time.monotonic(),
+    )
+    request_id = "req-1"
+    job = _PrefetchJob(
+        handle=handle,
+        world_size=world_size,
+        request_id=request_id,
+        requested_tokens=0,
+        num_object_groups=num_object_groups,
+    )
+    module._prefetch_jobs[request_id] = job
+    # The storage layer returns the prefix-hit count; the module divides it by
+    # world_size.
+    ctx.storage_manager.query_prefetch_lookup_hits.return_value = storage_return
+
+    return module, request_id
+
+
+def test_server_lookup_hits_returns_count():
+    """query_prefetch_lookup_hits returns chunk count when lookup is done."""
+    module, request_id = _make_module_with_job(world_size=1, storage_return=5)
+
+    result = module.query_prefetch_lookup_hits(request_id)
+
+    assert result == 5
+    module.context.storage_manager.query_prefetch_lookup_hits.assert_called_once()
+
+
+def test_server_lookup_hits_divides_by_world_size():
+    """Result should be divided by world_size for tensor parallelism."""
+    module, request_id = _make_module_with_job(world_size=2, storage_return=10)
+
+    result = module.query_prefetch_lookup_hits(request_id)
+
+    assert result == 5  # 10 // 2
+
+
+def test_server_lookup_hits_divides_by_world_size_times_num_groups():
+    """Chunk-major layout packs world_size * num_object_groups keys per chunk."""
+    module, request_id = _make_module_with_job(
+        world_size=2, storage_return=12, num_object_groups=3
+    )
+
+    result = module.query_prefetch_lookup_hits(request_id)
+
+    assert result == 2  # 12 // (2 * 3)
+
+
+def test_server_lookup_hits_returns_none_when_in_progress():
+    """Returns None when storage manager lookup is still in progress."""
+    module, request_id = _make_module_with_job(world_size=1, storage_return=None)
+
+    result = module.query_prefetch_lookup_hits(request_id)
+
+    assert result is None
+
+
+def test_server_lookup_hits_returns_zero_for_invalid_request():
+    """Returns 0 for a request_id that doesn't exist (prevents infinite spin)."""
+    ctx = MagicMock()
+    ctx.token_hasher.chunk_size = 256
+    module = LookupModule(ctx)
+
+    result = module.query_prefetch_lookup_hits("nonexistent-req")
+
+    assert result == 0
+    ctx.storage_manager.query_prefetch_lookup_hits.assert_not_called()
+
+
+def test_server_lookup_hits_returns_zero_after_prefetch_consumed():
+    """Returns 0 after query_prefetch_status has consumed the job.
+
+    This prevents the caller from spinning forever on a completed request.
+    """
+    module, request_id = _make_module_with_job(world_size=1, storage_return=5)
+
+    # Simulate query_prefetch_status consuming the job
+    module._prefetch_jobs.pop(request_id)
+
+    result = module.query_prefetch_lookup_hits(request_id)
+
+    assert result == 0
+
+
+def test_server_lookup_hits_zero_count():
+    """Returns 0 when no keys matched (not None)."""
+    module, request_id = _make_module_with_job(world_size=1, storage_return=0)
+
+    result = module.query_prefetch_lookup_hits(request_id)
+
+    assert result == 0
+    assert result is not None
+
+
+def test_server_handler_registered():
+    """LookupModule should have a query_prefetch_lookup_hits method."""
+    assert hasattr(LookupModule, "query_prefetch_lookup_hits")
+    assert callable(LookupModule.query_prefetch_lookup_hits)
+
+
+# ============================================================================
+# Chunk-major key layout
+# ============================================================================
+
+
+def _lookup_key(world_size: int) -> IPCCacheServerKey:
+    """A lookup-side IPC key (worker_id None -> expand over all workers)."""
+    return IPCCacheServerKey(
+        model_name="m",
+        world_size=world_size,
+        worker_id=None,
+        token_ids=(0,),
+        start=0,
+        end=0,
+        request_id="r",
+    )
+
+
+def _captured_lookup_object_keys(
+    world_size: int, num_groups: int, chunk_hashes: list[bytes]
+) -> list[ObjectKey]:
+    """Drive the public ``lookup()`` and return the object keys it submits.
+
+    The engine context is mocked so ``lookup()`` runs end-to-end; the
+    chunk-major key list it builds is recovered from the ``submit_prefetch_task``
+    call rather than by reaching into a private helper.
+    """
+    ctx = MagicMock()
+    ctx.chunk_size = 16
+    ctx.event_bus.has_subscribers.return_value = False
+    ctx.layout_desc_registry.find.return_value = MagicMock()  # non-None layout
+    ctx.layout_desc_registry.find_attn_desc.return_value = AttnWindowDesc(
+        num_chunks_in_sw=[-1] * num_groups
+    )
+    ctx.token_hasher.compute_chunk_hashes.return_value = chunk_hashes
+
+    module = LookupModule(ctx)
+    module.lookup(_lookup_key(world_size=world_size), tp_size=1)
+
+    ctx.storage_manager.submit_prefetch_task.assert_called_once()
+    return ctx.storage_manager.submit_prefetch_task.call_args.args[0]
+
+
+def test_lookup_lays_keys_out_chunk_then_group_then_rank():
+    """lookup() submits keys laid out chunk -> object group -> kv_rank, so each
+    chunk's keys are contiguous (the property that makes a leading-ones prefix
+    equal to the full-attention model-wide hit)."""
+    keys = _captured_lookup_object_keys(
+        world_size=2, num_groups=2, chunk_hashes=[b"c0", b"c1"]
+    )
+
+    # 2 chunks * 2 groups * 2 ranks.
+    assert len(keys) == 8
+    # Each chunk's 4 keys are contiguous.
+    assert [k.chunk_hash for k in keys[:4]] == [b"c0"] * 4
+    assert [k.chunk_hash for k in keys[4:]] == [b"c1"] * 4
+    # Within a chunk, group 0 (both ranks) precedes group 1 (both ranks).
+    assert [k.object_group_id for k in keys[:4]] == [0, 0, 1, 1]
+    assert [k.object_group_id for k in keys[4:]] == [0, 0, 1, 1]
+    # The two ranks within one (chunk, group) cell are distinct.
+    assert keys[0].kv_rank != keys[1].kv_rank
+
+
+def test_lookup_single_group_matches_single_group_layout():
+    """With one object group the submitted layout is byte-identical to the
+    single-group layout (the object-group-separation-disabled / non-hybrid
+    case)."""
+    chunk_hashes = [b"c0", b"c1"]
+    keys = _captured_lookup_object_keys(
+        world_size=2, num_groups=1, chunk_hashes=chunk_hashes
+    )
+
+    expected = ipc_key_to_object_keys(_lookup_key(world_size=2), chunk_hashes, [0])[0]
+    assert keys == expected
diff --git a/tests/v1/multiprocess/test_raw_block_l2_adapter.py b/tests/v1/multiprocess/test_raw_block_l2_adapter.py
new file mode 100644
index 0000000..6263911
--- /dev/null
+++ b/tests/v1/multiprocess/test_raw_block_l2_adapter.py
@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from pathlib import Path
+
+# Third Party
+import pytest
+
+# First Party
+from tests.v1.storage_backend.raw_block_test_utils import (
+    RAW_BLOCK_CI_BLOCK_ALIGN,
+    RAW_BLOCK_CI_CAPACITY_BYTES,
+    RAW_BLOCK_CI_HEADER_BYTES,
+    RAW_BLOCK_CI_META_TOTAL_BYTES,
+    RAW_BLOCK_CI_SLOT_BYTES,
+    install_native_storage_ops_fallback,
+    make_empty_memory_obj,
+    make_memory_obj,
+    make_object_key,
+    make_raw_block_file,
+    memory_obj_bytes,
+    wait_for_event_fd,
+)
+
+install_native_storage_ops_fallback()
+pytest.importorskip("lmcache_rust_raw_block_io")
+
+# First Party
+from lmcache.v1.distributed.api import MemoryLayoutDesc  # noqa: E402
+from lmcache.v1.distributed.l2_adapters.raw_block_l2_adapter import (  # noqa: E402
+    RawBlockL2Adapter,
+    RawBlockL2AdapterConfig,
+)
+
+_EMPTY_LAYOUT = MemoryLayoutDesc(shapes=[], dtypes=[])
+
+
+def _make_adapter(tmp_path: Path) -> RawBlockL2Adapter:
+    path = make_raw_block_file(tmp_path)
+    config = RawBlockL2AdapterConfig(
+        device_path=str(path),
+        capacity_bytes=RAW_BLOCK_CI_CAPACITY_BYTES,
+        block_align=RAW_BLOCK_CI_BLOCK_ALIGN,
+        header_bytes=RAW_BLOCK_CI_HEADER_BYTES,
+        slot_bytes=RAW_BLOCK_CI_SLOT_BYTES,
+        meta_total_bytes=RAW_BLOCK_CI_META_TOTAL_BYTES,
+        use_odirect=False,
+        enable_zero_copy=False,
+        meta_enable_periodic=False,
+        meta_idle_quiet_ms=0,
+        io_engine="posix",
+        iouring_queue_depth=8,
+        num_store_workers=1,
+        num_lookup_workers=1,
+        num_load_workers=1,
+    )
+    return RawBlockL2Adapter(config)
+
+
+def test_raw_block_l2_adapter_store_lookup_load_roundtrip(tmp_path):
+    adapter = _make_adapter(tmp_path)
+    try:
+        key = make_object_key(1)
+        missing_key = make_object_key(999)
+        payload = b"raw-block-l2-adapter-payload"
+
+        store_task_id = adapter.submit_store_task([key], [make_memory_obj(payload)])
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        store_result = adapter.pop_completed_store_tasks()[store_task_id]
+        assert store_result.is_successful()
+        assert store_result.bytes_transferred() == RAW_BLOCK_CI_SLOT_BYTES
+
+        lookup_task_id = adapter.submit_lookup_and_lock_task(
+            [key, missing_key], _EMPTY_LAYOUT
+        )
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_task_id)
+        assert lookup_bitmap is not None
+        assert lookup_bitmap.test(0) is True
+        assert lookup_bitmap.test(1) is False
+
+        loaded = make_empty_memory_obj(len(payload))
+        missing = make_empty_memory_obj(len(payload))
+        load_task_id = adapter.submit_load_task([key, missing_key], [loaded, missing])
+        assert wait_for_event_fd(adapter.get_load_event_fd())
+        load_bitmap = adapter.query_load_result(load_task_id)
+        assert load_bitmap is not None
+        assert load_bitmap.test(0) is True
+        assert load_bitmap.test(1) is False
+        assert memory_obj_bytes(loaded) == payload
+
+        adapter.submit_unlock([key])
+    finally:
+        adapter.close()
+
+
+def test_raw_block_l2_adapter_delete_makes_key_miss(tmp_path):
+    adapter = _make_adapter(tmp_path)
+    try:
+        key = make_object_key(2)
+        payload = b"delete-from-raw-block-l2"
+
+        store_task_id = adapter.submit_store_task([key], [make_memory_obj(payload)])
+        assert wait_for_event_fd(adapter.get_store_event_fd())
+        store_result = adapter.pop_completed_store_tasks()[store_task_id]
+        assert store_result.is_successful()
+        assert store_result.bytes_transferred() == RAW_BLOCK_CI_SLOT_BYTES
+
+        adapter.delete([key])
+
+        lookup_task_id = adapter.submit_lookup_and_lock_task([key], _EMPTY_LAYOUT)
+        assert wait_for_event_fd(adapter.get_lookup_and_lock_event_fd())
+        lookup_bitmap = adapter.query_lookup_and_lock_result(lookup_task_id)
+        assert lookup_bitmap is not None
+        assert lookup_bitmap.test(0) is False
+    finally:
+        adapter.close()
diff --git a/tests/v1/multiprocess/test_session.py b/tests/v1/multiprocess/test_session.py
new file mode 100644
index 0000000..f93ea6a
--- /dev/null
+++ b/tests/v1/multiprocess/test_session.py
@@ -0,0 +1,359 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for Session and SessionManager."""
+
+# Standard
+import threading
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.session import Session, SessionManager
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+from lmcache.v1.periodic_thread import PeriodicThreadRegistry
+
+
+@pytest.fixture
+def hasher() -> TokenHasher:
+    """TokenHasher with small chunk_size for testing."""
+    return TokenHasher(chunk_size=4, hash_algorithm="blake3")
+
+
+@pytest.fixture
+def session(hasher: TokenHasher) -> Session:
+    """A fresh Session instance."""
+    return Session(request_id="req-1", hasher=hasher)
+
+
+@pytest.fixture
+def session_manager(hasher: TokenHasher) -> SessionManager:
+    """A SessionManager with short TTL for testing expiry."""
+    return SessionManager(hasher, ttl=0.1, cleanup_interval=None)
+
+
+class TestSession:
+    def test_set_tokens_replaces(self, session: Session) -> None:
+        session.set_tokens([1, 2, 3])
+        assert session.token_ids == [1, 2, 3]
+        session.set_tokens([4, 5, 6])
+        assert session.token_ids == [4, 5, 6]
+
+    def test_get_hashes_basic(self, session: Session) -> None:
+        """8 tokens, chunk_size=4 produces 2 hashes."""
+        session.set_tokens(list(range(8)))
+        hashes = session.get_hashes(0, 8)
+        assert len(hashes) == 2
+
+    def test_get_hashes_incremental(self, session: Session) -> None:
+        """Calling get_hashes incrementally should produce same results."""
+        tokens = list(range(12))
+        session.set_tokens(tokens)
+
+        # First call: compute chunks 0-1
+        h_first = session.get_hashes(0, 8)
+        assert len(h_first) == 2
+        assert session.num_chunks_processed == 2
+
+        # Second call: compute chunk 2 (chunks 0-1 already cached)
+        h_second = session.get_hashes(8, 12)
+        assert len(h_second) == 1
+        assert session.num_chunks_processed == 3
+
+        # Full range should match
+        h_all = session.get_hashes(0, 12)
+        assert h_all == h_first + h_second
+
+    def test_get_hashes_idempotent(self, session: Session) -> None:
+        """Calling get_hashes twice with same range returns same result."""
+        session.set_tokens(list(range(8)))
+        h1 = session.get_hashes(0, 8)
+        h2 = session.get_hashes(0, 8)
+        assert h1 == h2
+        assert session.num_chunks_processed == 2  # not recomputed
+
+    def test_get_hashes_matches_hasher(
+        self, hasher: TokenHasher, session: Session
+    ) -> None:
+        """Session hashes should match standalone TokenHasher hashes."""
+        tokens = list(range(8))
+        session.set_tokens(tokens)
+        session_hashes = session.get_hashes(0, 8)
+        hasher_hashes = hasher.compute_chunk_hashes(tokens)
+        assert session_hashes == hasher_hashes
+
+    def test_rolling_state_across_calls(self, session: Session) -> None:
+        """Simulates the lookup then store flow: lookup hashes all, store
+        hashes a subrange. The rolling state from lookup should be reused."""
+        tokens = list(range(12))
+        session.set_tokens(tokens)
+
+        # Lookup: hash everything
+        all_hashes = session.get_hashes(0, 12)
+        assert len(all_hashes) == 3
+
+        # Store: request hashes for chunk 1-2 (tokens 4:12)
+        # Should reuse already-computed hashes
+        store_hashes = session.get_hashes(4, 12)
+        assert store_hashes == all_hashes[1:]
+        assert session.num_chunks_processed == 3  # no extra computation
+
+
+class TestSessionManager:
+    def test_get_or_create_new(self, session_manager: SessionManager) -> None:
+        s = session_manager.get_or_create("req-1")
+        assert s.request_id == "req-1"
+
+    def test_get_or_create_existing(self, session_manager: SessionManager) -> None:
+        s1 = session_manager.get_or_create("req-1")
+        s2 = session_manager.get_or_create("req-1")
+        assert s1 is s2
+
+    def test_get_or_create_different_ids(self, session_manager: SessionManager) -> None:
+        s1 = session_manager.get_or_create("req-1")
+        s2 = session_manager.get_or_create("req-2")
+        assert s1 is not s2
+
+    def test_remove(self, session_manager: SessionManager) -> None:
+        session_manager.get_or_create("req-1")
+        removed = session_manager.remove("req-1")
+        assert removed is not None
+        assert removed.request_id == "req-1"
+        # Should create a fresh session
+        s = session_manager.get_or_create("req-1")
+        assert s.num_chunks_processed == 0
+
+    def test_remove_nonexistent(self, session_manager: SessionManager) -> None:
+        """Removing a non-existent session should return None."""
+        result = session_manager.remove("does-not-exist")
+        assert result is None
+
+    def test_cleanup_expired(self, session_manager: SessionManager) -> None:
+        """Sessions older than TTL should be cleaned up."""
+        session_manager.get_or_create("req-1")
+        session_manager.get_or_create("req-2")
+        # Wait for TTL to expire (ttl=0.1s)
+        time.sleep(0.15)
+        removed = session_manager.cleanup_expired()
+        assert removed == 2
+        # New session should be fresh
+        s = session_manager.get_or_create("req-1")
+        assert s.num_chunks_processed == 0
+
+    def test_cleanup_keeps_fresh(self, session_manager: SessionManager) -> None:
+        """Fresh sessions should not be cleaned up."""
+        session_manager.get_or_create("req-1")
+        removed = session_manager.cleanup_expired()
+        assert removed == 0
+
+    def test_periodic_cleanup_removes_expired_sessions(
+        self, hasher: TokenHasher
+    ) -> None:
+        """Background cleanup should remove expired sessions automatically."""
+        PeriodicThreadRegistry.reset()
+        manager = SessionManager(hasher, ttl=0.05, cleanup_interval=0.01)
+        try:
+            manager.get_or_create("req-1")
+            manager.get_or_create("req-2")
+
+            threads = PeriodicThreadRegistry.get_instance().get_all()
+            assert len(threads) == 1
+            assert threads[0].is_running
+
+            deadline = time.time() + 1.0
+            while manager.active_count() != 0 and time.time() < deadline:
+                time.sleep(0.01)
+
+            assert manager.active_count() == 0
+        finally:
+            manager.close()
+            assert PeriodicThreadRegistry.get_instance().get_all() == []
+            PeriodicThreadRegistry.reset()
+
+
+class TestSessionThreadSafety:
+    """Verify Session is safe under concurrent access
+    from multiple TP worker threads."""
+
+    def test_concurrent_get_hashes(self, hasher: TokenHasher) -> None:
+        """Multiple threads calling get_hashes on the same Session
+        must produce correct hashes (no duplicates, no corruption).
+        """
+        session = Session(request_id="req-mt", hasher=hasher)
+        tokens = list(range(20))  # 5 chunks of 4
+        session.set_tokens(tokens)
+
+        # Reference hashes computed single-threaded
+        expected = hasher.compute_chunk_hashes(tokens)
+        errors: list[str] = []
+        barrier = threading.Barrier(8)
+
+        def worker(tid: int) -> None:
+            try:
+                barrier.wait(timeout=5)
+                hashes = session.get_hashes(0, 20)
+                if hashes != expected:
+                    errors.append(
+                        "Thread %d: got %r, expected %r" % (tid, hashes, expected)
+                    )
+            except Exception as exc:
+                errors.append("Thread %d: %s" % (tid, exc))
+
+        threads = [threading.Thread(target=worker, args=(i,)) for i in range(8)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+
+        assert not errors, "\n".join(errors)
+        assert session.num_chunks_processed == 5
+
+    def test_concurrent_set_and_get(self, hasher: TokenHasher) -> None:
+        """set_tokens and get_hashes called concurrently must not
+        corrupt internal state."""
+        session = Session(request_id="req-mt2", hasher=hasher)
+        tokens = list(range(8))  # 2 chunks
+        session.set_tokens(tokens)
+        expected = hasher.compute_chunk_hashes(tokens)
+        errors: list[str] = []
+        barrier = threading.Barrier(4)
+
+        def reader(tid: int) -> None:
+            try:
+                barrier.wait(timeout=5)
+                hashes = session.get_hashes(0, 8)
+                if hashes != expected:
+                    errors.append("Reader %d: mismatch" % tid)
+            except Exception as exc:
+                errors.append("Reader %d: %s" % (tid, exc))
+
+        def writer() -> None:
+            try:
+                barrier.wait(timeout=5)
+                # Re-set same tokens (idempotent)
+                session.set_tokens(tokens)
+            except Exception as exc:
+                errors.append("Writer: %s" % exc)
+
+        threads = [threading.Thread(target=reader, args=(i,)) for i in range(3)]
+        threads.append(threading.Thread(target=writer))
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join(timeout=10)
+
+        assert not errors, "\n".join(errors)
+
+
+class TestSessionGetHashesOptionalEnd:
+    """
+    Tests for Session.get_hashes with optional end (auto-align to last full chunk).
+    """
+
+    def test_get_hashes_optional_end_empty(self, session: Session) -> None:
+        """get_hashes(0) should return empty list when no tokens set."""
+        assert session.get_hashes(0) == []
+
+    def test_get_hashes_optional_end_after_compute(self, session: Session) -> None:
+        """get_hashes(0) should return all computed hashes."""
+        session.set_tokens(list(range(12)))  # 3 chunks of 4
+        all_hashes = session.get_hashes(0)
+        assert len(all_hashes) == 3
+
+    def test_get_hashes_optional_end_incremental(self, session: Session) -> None:
+        """get_hashes(0) should accumulate hashes from incremental calls."""
+        session.set_tokens(list(range(12)))  # 3 chunks of 4
+        # First compute 2 chunks
+        session.get_hashes(0, 8)
+        # get_hashes(0) should now compute all 3 chunks
+        assert len(session.get_hashes(0)) == 3
+
+    def test_get_hashes_optional_end_matches_explicit(self, session: Session) -> None:
+        """get_hashes(0) should return the same as get_hashes(0, aligned_len)."""
+        session.set_tokens(list(range(12)))
+        expected = session.get_hashes(0, 12)
+        assert session.get_hashes(0) == expected
+
+    def test_get_hashes_optional_end_truncates_partial_chunk(
+        self, session: Session
+    ) -> None:
+        """get_hashes(0) should ignore trailing tokens that don't fill a chunk."""
+        # 14 tokens with chunk_size=4 -> 3 full chunks (12 tokens), 2 leftover
+        session.set_tokens(list(range(14)))
+        hashes = session.get_hashes(0)
+        assert len(hashes) == 3
+
+    def test_get_hashes_optional_end_matches_hasher(
+        self, hasher: TokenHasher, session: Session
+    ) -> None:
+        """get_hashes(0) should match standalone TokenHasher results."""
+        tokens = list(range(12))
+        session.set_tokens(tokens)
+        session_hashes = session.get_hashes(0)
+        hasher_hashes = hasher.compute_chunk_hashes(tokens)
+        # Convert session hashes to bytes for comparison
+        converted = [TokenHasher.hash_to_bytes(h) for h in session_hashes]
+        assert converted == hasher_hashes
+
+
+class TestSessionLookupIpcKey:
+    """Tests for Session.lookup_ipc_key field."""
+
+    def test_lookup_ipc_key_default_none(self, session: Session) -> None:
+        """lookup_ipc_key should default to None."""
+        assert session.lookup_ipc_key is None
+
+    def test_lookup_ipc_key_set_and_get(self, session: Session) -> None:
+        """lookup_ipc_key should be settable and retrievable."""
+        key = IPCCacheServerKey.from_token_ids(
+            model_name="test-model",
+            world_size=1,
+            worker_id=None,
+            token_ids=list(range(8)),
+            start=0,
+            end=8,
+            request_id="req-1",
+        )
+        session.lookup_ipc_key = key
+        assert session.lookup_ipc_key is key
+        assert session.lookup_ipc_key.model_name == "test-model"
+        assert session.lookup_ipc_key.worker_id is None
+
+
+class TestSessionManagerRemoveReturnsSession:
+    """Tests for SessionManager.remove returning the removed session."""
+
+    def test_remove_returns_session_with_state(self, hasher: TokenHasher) -> None:
+        """remove() should return the session with all accumulated state."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        session = mgr.get_or_create("req-1")
+        session.set_tokens(list(range(8)))
+        session.get_hashes(0, 8)
+
+        key = IPCCacheServerKey.from_token_ids(
+            model_name="model",
+            world_size=1,
+            worker_id=None,
+            token_ids=list(range(8)),
+            request_id="req-1",
+        )
+        session.lookup_ipc_key = key
+
+        removed = mgr.remove("req-1")
+        assert removed is not None
+        assert removed.request_id == "req-1"
+        assert len(removed.get_hashes(0)) == 2
+        assert removed.lookup_ipc_key is key
+
+    def test_remove_clears_from_manager(self, hasher: TokenHasher) -> None:
+        """After remove(), the session should no longer be in the manager."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        mgr.get_or_create("req-1")
+        mgr.remove("req-1")
+        assert mgr.active_count() == 0
+
+    def test_remove_nonexistent_returns_none(self, hasher: TokenHasher) -> None:
+        """remove() on a non-existent request_id should return None."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        assert mgr.remove("no-such-id") is None
diff --git a/tests/v1/multiprocess/test_skip_first_n_tokens.py b/tests/v1/multiprocess/test_skip_first_n_tokens.py
new file mode 100644
index 0000000..3585700
--- /dev/null
+++ b/tests/v1/multiprocess/test_skip_first_n_tokens.py
@@ -0,0 +1,228 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for the skip_first_n_tokens logic in CacheServer.retrieve.
+
+These tests verify the chunk-skip arithmetic without requiring GPU,
+ensuring that:
+  - Tokens within the skip range are not written (chunks are skipped)
+  - Tokens outside the skip range are written with correct skip_in_chunk
+  - Partial-chunk skip works (skip_first_n_tokens = chunk_size / 2)
+  - Full-chunk skip works (skip_first_n_tokens >= chunk_size)
+"""
+
+# Third Party
+import pytest
+
+
+def compute_retrieve_plan(
+    num_chunks: int,
+    chunk_size: int,
+    skip_first_n_tokens: int,
+) -> list[tuple[int, int]]:
+    """
+    Reproduce the skip logic from CacheServer.retrieve._retrieve_loop.
+
+    Returns a list of (chunk_index, skip_in_chunk) for each chunk that
+    would actually be written to the paged buffer (i.e., not fully skipped).
+    """
+    written_chunks = []
+    for idx in range(num_chunks):
+        chunk_start = idx * chunk_size
+        chunk_end = chunk_start + chunk_size
+
+        effective_start = max(chunk_start, skip_first_n_tokens)
+        effective_start = min(effective_start, chunk_end)
+        if effective_start >= chunk_end:
+            continue
+
+        skip_in_chunk = max(0, min(effective_start - chunk_start, chunk_size - 1))
+        written_chunks.append((idx, skip_in_chunk))
+    return written_chunks
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+CHUNK_SIZE = 256
+
+
+class TestSkipFirstNTokensZero:
+    """skip_first_n_tokens == 0  →  every chunk is written, no skip."""
+
+    def test_all_chunks_written(self):
+        plan = compute_retrieve_plan(
+            num_chunks=4, chunk_size=CHUNK_SIZE, skip_first_n_tokens=0
+        )
+        assert len(plan) == 4
+        for idx, skip in plan:
+            assert skip == 0, f"chunk {idx} should have skip_in_chunk=0"
+
+
+class TestFullChunkSkip:
+    """skip_first_n_tokens >= chunk_size  →  first chunk(s) fully skipped."""
+
+    def test_skip_exactly_one_chunk(self):
+        """skip == chunk_size  →  chunk 0 skipped, chunk 1+ written."""
+        plan = compute_retrieve_plan(
+            num_chunks=4, chunk_size=CHUNK_SIZE, skip_first_n_tokens=CHUNK_SIZE
+        )
+        indices = [idx for idx, _ in plan]
+        assert 0 not in indices, "chunk 0 should be fully skipped"
+        assert indices == [1, 2, 3]
+        for _, skip in plan:
+            assert skip == 0
+
+    def test_skip_multiple_chunks(self):
+        """skip == 2 * chunk_size  →  chunks 0 and 1 skipped."""
+        plan = compute_retrieve_plan(
+            num_chunks=4,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=2 * CHUNK_SIZE,
+        )
+        indices = [idx for idx, _ in plan]
+        assert indices == [2, 3]
+        for _, skip in plan:
+            assert skip == 0
+
+    def test_skip_all_chunks(self):
+        """skip >= total tokens  →  everything skipped, nothing written."""
+        plan = compute_retrieve_plan(
+            num_chunks=4,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=4 * CHUNK_SIZE,
+        )
+        assert plan == []
+
+    def test_skip_more_than_all_tokens(self):
+        """skip far exceeds total tokens  →  still nothing written."""
+        plan = compute_retrieve_plan(
+            num_chunks=2,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=100 * CHUNK_SIZE,
+        )
+        assert plan == []
+
+
+class TestPartialChunkSkip:
+    """skip_first_n_tokens lands in the middle of a chunk."""
+
+    def test_skip_half_chunk(self):
+        """skip == chunk_size / 2  →  chunk 0 written with half skip."""
+        half = CHUNK_SIZE // 2
+        plan = compute_retrieve_plan(
+            num_chunks=4,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=half,
+        )
+        assert len(plan) == 4
+        # chunk 0 partially skipped
+        assert plan[0] == (0, half)
+        # remaining chunks fully written
+        for idx, skip in plan[1:]:
+            assert skip == 0
+
+    def test_skip_one_token(self):
+        """skip == 1  →  chunk 0 written with skip_in_chunk=1."""
+        plan = compute_retrieve_plan(
+            num_chunks=3, chunk_size=CHUNK_SIZE, skip_first_n_tokens=1
+        )
+        assert plan[0] == (0, 1)
+        assert plan[1] == (1, 0)
+        assert plan[2] == (2, 0)
+
+    def test_skip_last_token_of_chunk(self):
+        """skip == chunk_size - 1  →  chunk 0 almost entirely skipped."""
+        plan = compute_retrieve_plan(
+            num_chunks=2,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=CHUNK_SIZE - 1,
+        )
+        assert len(plan) == 2
+        assert plan[0] == (0, CHUNK_SIZE - 1)
+        assert plan[1] == (1, 0)
+
+    def test_skip_into_second_chunk(self):
+        """skip lands in the middle of chunk 1."""
+        skip = CHUNK_SIZE + CHUNK_SIZE // 4  # 1.25 chunks
+        plan = compute_retrieve_plan(
+            num_chunks=4,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=skip,
+        )
+        indices = [idx for idx, _ in plan]
+        assert 0 not in indices, "chunk 0 should be fully skipped"
+        # chunk 1 partially written
+        assert plan[0] == (1, CHUNK_SIZE // 4)
+        # chunks 2, 3 fully written
+        assert plan[1] == (2, 0)
+        assert plan[2] == (3, 0)
+
+
+class TestEdgeCases:
+    """Boundary and edge cases."""
+
+    def test_single_chunk_full_skip(self):
+        plan = compute_retrieve_plan(
+            num_chunks=1,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=CHUNK_SIZE,
+        )
+        assert plan == []
+
+    def test_single_chunk_no_skip(self):
+        plan = compute_retrieve_plan(
+            num_chunks=1,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=0,
+        )
+        assert plan == [(0, 0)]
+
+    def test_single_chunk_partial_skip(self):
+        plan = compute_retrieve_plan(
+            num_chunks=1,
+            chunk_size=CHUNK_SIZE,
+            skip_first_n_tokens=100,
+        )
+        assert plan == [(0, 100)]
+
+    def test_skip_in_chunk_never_negative(self):
+        """skip_in_chunk must always be >= 0 regardless of inputs."""
+        for skip in range(0, 5 * CHUNK_SIZE, 17):
+            plan = compute_retrieve_plan(
+                num_chunks=4,
+                chunk_size=CHUNK_SIZE,
+                skip_first_n_tokens=skip,
+            )
+            for _, skip_in_chunk in plan:
+                assert skip_in_chunk >= 0
+
+    def test_skip_in_chunk_never_exceeds_chunk_size_minus_one(self):
+        """skip_in_chunk must always be <= chunk_size - 1."""
+        for skip in range(0, 5 * CHUNK_SIZE, 17):
+            plan = compute_retrieve_plan(
+                num_chunks=4,
+                chunk_size=CHUNK_SIZE,
+                skip_first_n_tokens=skip,
+            )
+            for _, skip_in_chunk in plan:
+                assert skip_in_chunk <= CHUNK_SIZE - 1
+
+    @pytest.mark.parametrize("chunk_size", [1, 16, 64, 256, 1024])
+    def test_various_chunk_sizes(self, chunk_size):
+        """The logic should work correctly for any chunk_size."""
+        half = chunk_size // 2
+        plan = compute_retrieve_plan(
+            num_chunks=3,
+            chunk_size=chunk_size,
+            skip_first_n_tokens=half,
+        )
+        if half == 0:
+            # chunk_size=1, half=0 → no skip
+            assert len(plan) == 3
+            assert all(skip == 0 for _, skip in plan)
+        else:
+            assert len(plan) == 3
+            assert plan[0] == (0, half)
+            assert plan[1][1] == 0
+            assert plan[2][1] == 0
diff --git a/tests/v1/multiprocess/test_token_hasher.py b/tests/v1/multiprocess/test_token_hasher.py
new file mode 100644
index 0000000..8e3c9a0
--- /dev/null
+++ b/tests/v1/multiprocess/test_token_hasher.py
@@ -0,0 +1,375 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for TokenHasher."""
+
+# Standard
+import builtins
+
+# Third Party
+import numpy as np
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.token_hasher import (
+    TokenHasher,
+    chunk_hash_windows_numba,
+    rolling_hash_windows_numba,
+    unique_hits_direct_id_numba,
+    update_table_id_numba,
+)
+
+
+@pytest.fixture
+def hasher() -> TokenHasher:
+    """TokenHasher with small chunk_size for testing."""
+    return TokenHasher(chunk_size=4, hash_algorithm="blake3")
+
+
+class TestTokenHasher:
+    def test_init_blake3(self) -> None:
+        hasher = TokenHasher(chunk_size=256, hash_algorithm="blake3")
+        assert hasher.chunk_size == 256
+        assert hasher.none_hash is not None
+
+    def test_init_blake3_does_not_import_vllm(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        real_import = builtins.__import__
+
+        def guarded_import(name, *args, **kwargs):
+            if name == "vllm" or name.startswith("vllm."):
+                raise AssertionError("blake3 TokenHasher should not import vLLM")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", guarded_import)
+
+        hasher = TokenHasher(chunk_size=256, hash_algorithm="blake3")
+
+        assert hasher.none_hash is not None
+
+    def test_init_none_hash_vllm_runtime_error_falls_back(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        real_import = builtins.__import__
+
+        def failing_vllm_import(name, *args, **kwargs):
+            if name == "vllm.v1.core":
+                raise RuntimeError("already a kernel registered")
+            return real_import(name, *args, **kwargs)
+
+        monkeypatch.setattr(builtins, "__import__", failing_vllm_import)
+        hasher = TokenHasher.__new__(TokenHasher)
+        hasher.hash_algorithm_name = "sha256_cbor"
+        hasher.hash_func = lambda _: b"fallback"
+
+        assert hasher._init_none_hash() == b"fallback"
+
+    def test_hash_tokens_returns_bytes(self, hasher: TokenHasher) -> None:
+        h = hasher.hash_tokens([1, 2, 3, 4])
+        assert isinstance(h, bytes)
+
+    def test_hash_tokens_deterministic(self, hasher: TokenHasher) -> None:
+        h1 = hasher.hash_tokens([1, 2, 3, 4])
+        h2 = hasher.hash_tokens([1, 2, 3, 4])
+        assert h1 == h2
+
+    def test_hash_tokens_different_input(self, hasher: TokenHasher) -> None:
+        h1 = hasher.hash_tokens([1, 2, 3, 4])
+        h2 = hasher.hash_tokens([5, 6, 7, 8])
+        assert h1 != h2
+
+    def test_hash_tokens_with_prefix(self, hasher: TokenHasher) -> None:
+        """Rolling hash: same tokens with different prefix produces different hash."""
+        h_no_prefix = hasher.hash_tokens([1, 2, 3, 4])
+        h_with_prefix = hasher.hash_tokens([1, 2, 3, 4], prefix_hash=h_no_prefix)
+        assert h_no_prefix != h_with_prefix
+
+    def test_compute_chunk_hashes_exact_chunks(self, hasher: TokenHasher) -> None:
+        """8 tokens with chunk_size=4 produces 2 hashes."""
+        tokens = list(range(8))
+        hashes = hasher.compute_chunk_hashes(tokens)
+        assert len(hashes) == 2
+
+    def test_compute_chunk_hashes_partial_chunk_discarded(
+        self, hasher: TokenHasher
+    ) -> None:
+        """10 tokens with chunk_size=4 produces 2 hashes (last 2 tokens discarded)."""
+        tokens = list(range(10))
+        hashes = hasher.compute_chunk_hashes(tokens)
+        assert len(hashes) == 2
+
+    def test_compute_chunk_hashes_too_few_tokens(self, hasher: TokenHasher) -> None:
+        """3 tokens with chunk_size=4 produces 0 hashes."""
+        hashes = hasher.compute_chunk_hashes([1, 2, 3])
+        assert len(hashes) == 0
+
+    def test_compute_chunk_hashes_empty(self, hasher: TokenHasher) -> None:
+        hashes = hasher.compute_chunk_hashes([])
+        assert len(hashes) == 0
+
+    def test_compute_chunk_hashes_rolling(self, hasher: TokenHasher) -> None:
+        """Second chunk hash depends on the first (rolling property)."""
+        tokens = list(range(8))
+        hashes = hasher.compute_chunk_hashes(tokens)
+        # Hash of chunk [4,5,6,7] alone (no prefix) should differ
+        standalone = hasher.hash_tokens([4, 5, 6, 7])
+        assert hashes[1] != standalone
+
+    def test_compute_chunk_hashes_matches_manual(self, hasher: TokenHasher) -> None:
+        """compute_chunk_hashes should match manual rolling hash_tokens calls."""
+        tokens = list(range(12))  # 3 chunks
+        auto_hashes = hasher.compute_chunk_hashes(tokens)
+
+        h0 = hasher.hash_tokens(tokens[0:4])
+        h1 = hasher.hash_tokens(tokens[4:8], prefix_hash=h0)
+        h2 = hasher.hash_tokens(tokens[8:12], prefix_hash=h1)
+        assert auto_hashes == [h0, h1, h2]
+
+    def test_hash_to_bytes_from_bytes(self) -> None:
+        val = b"\x01\x02\x03"
+        assert TokenHasher.hash_to_bytes(val) is val
+
+    def test_hash_to_bytes_from_int(self) -> None:
+        val = 42
+        result = TokenHasher.hash_to_bytes(val)
+        assert isinstance(result, bytes)
+        assert len(result) == 8
+
+
+_BASE = np.uint64(31)
+
+
+class TestRollingHashWindowsNumba:
+    def test_output_length(self) -> None:
+        arr = np.arange(10, dtype=np.uint64)
+        out = rolling_hash_windows_numba(arr, 4, _BASE)
+        assert len(out) == 7  # 10 - 4 + 1
+
+    def test_single_window(self) -> None:
+        arr = np.array([1, 2, 3], dtype=np.uint64)
+        out = rolling_hash_windows_numba(arr, 3, _BASE)
+        assert len(out) == 1
+
+    def test_k_equals_1(self) -> None:
+        """With window size 1 each output equals the corresponding input element."""
+        arr = np.array([7, 13, 42], dtype=np.uint64)
+        out = rolling_hash_windows_numba(arr, 1, _BASE)
+        np.testing.assert_array_equal(out, arr)
+
+    def test_deterministic(self) -> None:
+        arr = np.array([1, 2, 3, 4, 5], dtype=np.uint64)
+        out1 = rolling_hash_windows_numba(arr, 3, _BASE)
+        out2 = rolling_hash_windows_numba(arr, 3, _BASE)
+        np.testing.assert_array_equal(out1, out2)
+
+    def test_different_inputs_different_outputs(self) -> None:
+        arr1 = np.array([1, 2, 3, 4, 5], dtype=np.uint64)
+        arr2 = np.array([5, 4, 3, 2, 1], dtype=np.uint64)
+        out1 = rolling_hash_windows_numba(arr1, 3, _BASE)
+        out2 = rolling_hash_windows_numba(arr2, 3, _BASE)
+        assert not np.array_equal(out1, out2)
+
+    def test_different_base_different_output(self) -> None:
+        arr = np.array([1, 2, 3, 4, 5], dtype=np.uint64)
+        out1 = rolling_hash_windows_numba(arr, 3, np.uint64(31))
+        out2 = rolling_hash_windows_numba(arr, 3, np.uint64(37))
+        assert not np.array_equal(out1, out2)
+
+    def test_manual_values(self) -> None:
+        """Verify polynomial hash values against manual computation.
+
+        For arr=[1,2,3,4,5], k=3, base=31:
+          power = 31^2 = 961
+          window [1,2,3]: h = ((0*31+1)*31+2)*31+3 = 1026
+          window [2,3,4]: h = 1026 - 1*961 = 65; 65*31+4 = 2019
+          window [3,4,5]: h = 2019 - 2*961 = 97; 97*31+5 = 3012
+        """
+        arr = np.array([1, 2, 3, 4, 5], dtype=np.uint64)
+        out = rolling_hash_windows_numba(arr, 3, _BASE)
+        expected = np.array([1026, 2019, 3012], dtype=np.uint64)
+        np.testing.assert_array_equal(out, expected)
+
+    def test_output_dtype(self) -> None:
+        arr = np.array([1, 2, 3], dtype=np.uint64)
+        out = rolling_hash_windows_numba(arr, 2, _BASE)
+        assert out.dtype == np.uint64
+
+
+class TestChunkHashWindowsNumba:
+    def test_output_length(self) -> None:
+        arr = np.arange(12, dtype=np.uint64)
+        out = chunk_hash_windows_numba(arr, 4, _BASE)
+        assert len(out) == 3  # 12 // 4
+
+    def test_partial_chunk_ignored(self) -> None:
+        """Trailing tokens that don't fill a full window are dropped."""
+        arr = np.arange(10, dtype=np.uint64)
+        out = chunk_hash_windows_numba(arr, 4, _BASE)
+        assert len(out) == 2  # 10 // 4
+
+    def test_no_full_windows(self) -> None:
+        arr = np.arange(3, dtype=np.uint64)
+        out = chunk_hash_windows_numba(arr, 4, _BASE)
+        assert len(out) == 0
+
+    def test_deterministic(self) -> None:
+        arr = np.arange(8, dtype=np.uint64)
+        out1 = chunk_hash_windows_numba(arr, 4, _BASE)
+        out2 = chunk_hash_windows_numba(arr, 4, _BASE)
+        np.testing.assert_array_equal(out1, out2)
+
+    def test_different_inputs_different_outputs(self) -> None:
+        arr1 = np.array([1, 2, 3, 4, 5, 6], dtype=np.uint64)
+        arr2 = np.array([6, 5, 4, 3, 2, 1], dtype=np.uint64)
+        out1 = chunk_hash_windows_numba(arr1, 3, _BASE)
+        out2 = chunk_hash_windows_numba(arr2, 3, _BASE)
+        assert not np.array_equal(out1, out2)
+
+    def test_first_window_matches_rolling(self) -> None:
+        """First chunk hash must equal the first rolling-hash window."""
+        arr = np.array([1, 2, 3, 4, 5, 6], dtype=np.uint64)
+        chunk_out = chunk_hash_windows_numba(arr, 3, _BASE)
+        rolling_out = rolling_hash_windows_numba(arr, 3, _BASE)
+        assert chunk_out[0] == rolling_out[0]
+
+    def test_manual_values(self) -> None:
+        """Verify chunk hashes against manual computation.
+
+        For arr=[1,2,3,4,5,6], k=3, base=31:
+          window 0 [1,2,3]: ((0*31+1)*31+2)*31+3 = 1026
+          window 1 [4,5,6]: ((0*31+4)*31+5)*31+6 = 4005
+        """
+        arr = np.array([1, 2, 3, 4, 5, 6], dtype=np.uint64)
+        out = chunk_hash_windows_numba(arr, 3, _BASE)
+        expected = np.array([1026, 4005], dtype=np.uint64)
+        np.testing.assert_array_equal(out, expected)
+
+    def test_output_dtype(self) -> None:
+        arr = np.array([1, 2, 3, 4], dtype=np.uint64)
+        out = chunk_hash_windows_numba(arr, 2, _BASE)
+        assert out.dtype == np.uint64
+
+
+class TestUpdateTableIdNumba:
+    def _empty_table(self, size: int = 8) -> np.ndarray:
+        return np.full(size, -1, dtype=np.int64)
+
+    def test_basic_update(self) -> None:
+        table = self._empty_table()
+        hashes = np.array([0], dtype=np.uint64)  # 0 & 7 = 0
+        vals = np.array([99], dtype=np.int64)
+        update_table_id_numba(hashes, table, vals)
+        assert table[0] == 99
+
+    def test_index_from_hash_lower_bits(self) -> None:
+        """idx = hash & (table_size - 1)."""
+        table = self._empty_table(8)  # mask = 7
+        hashes = np.array([9], dtype=np.uint64)  # 9 & 7 = 1
+        vals = np.array([42], dtype=np.int64)
+        update_table_id_numba(hashes, table, vals)
+        assert table[1] == 42
+        assert all(table[i] == -1 for i in range(8) if i != 1)
+
+    def test_multiple_updates(self) -> None:
+        table = self._empty_table()
+        hashes = np.array([0, 1, 2], dtype=np.uint64)
+        vals = np.array([10, 20, 30], dtype=np.int64)
+        update_table_id_numba(hashes, table, vals)
+        assert table[0] == 10
+        assert table[1] == 20
+        assert table[2] == 30
+
+    def test_collision_last_write_wins(self) -> None:
+        """When two hashes map to the same slot, the last value is stored."""
+        table = self._empty_table()
+        # hash 0 → idx 0, hash 8 → idx 0 (8 & 7 = 0)
+        hashes = np.array([0, 8], dtype=np.uint64)
+        vals = np.array([10, 20], dtype=np.int64)
+        update_table_id_numba(hashes, table, vals)
+        assert table[0] == 20
+
+    def test_modifies_in_place(self) -> None:
+        table = self._empty_table()
+        ptr = table.ctypes.data
+        hashes = np.array([3], dtype=np.uint64)
+        vals = np.array([7], dtype=np.int64)
+        update_table_id_numba(hashes, table, vals)
+        assert table.ctypes.data == ptr  # same buffer
+        assert table[3] == 7
+
+    def test_empty_hashes_no_change(self) -> None:
+        table = self._empty_table()
+        hashes = np.empty(0, dtype=np.uint64)
+        vals = np.empty(0, dtype=np.int64)
+        update_table_id_numba(hashes, table, vals)
+        assert all(v == -1 for v in table)
+
+
+class TestUniqueHitsDirectIdNumba:
+    def _table(self, size: int = 8) -> np.ndarray:
+        return np.full(size, -1, dtype=np.int64)
+
+    def test_no_hits_all_empty(self) -> None:
+        table = self._table()
+        hashes = np.array([0, 1, 2], dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 4)
+        assert len(out) == 0
+
+    def test_single_hit(self) -> None:
+        table = self._table()
+        table[1] = 5
+        hashes = np.array([1], dtype=np.uint64)  # 1 & 7 = 1 → ID 5
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 10)
+        assert len(out) == 1
+        assert out[0] == 5
+
+    def test_deduplication(self) -> None:
+        """Same ID reached via two different hashes is returned only once."""
+        table = self._table()
+        table[1] = 3  # index 1 → ID 3
+        # hash 1 and hash 9 both map to index 1 (& 7 == 1)
+        hashes = np.array([1, 9], dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 5)
+        assert len(out) == 1
+        assert out[0] == 3
+
+    def test_multiple_unique_ids(self) -> None:
+        table = self._table()
+        table[0] = 0
+        table[1] = 1
+        table[2] = 2
+        hashes = np.array([0, 1, 2], dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 5)
+        assert len(out) == 3
+        assert set(out) == {0, 1, 2}
+
+    def test_mixed_hits_and_misses(self) -> None:
+        table = self._table()
+        table[2] = 10
+        # indices 0 (miss), 2 (hit → 10), 5 (miss)
+        hashes = np.array([0, 2, 5], dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 15)
+        assert len(out) == 1
+        assert out[0] == 10
+
+    def test_order_of_first_encounter_preserved(self) -> None:
+        """IDs appear in the order they are first seen in the hash stream."""
+        table = self._table()
+        table[0] = 2
+        table[1] = 0
+        table[2] = 1
+        hashes = np.array([0, 1, 2], dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 3)
+        np.testing.assert_array_equal(out, [2, 0, 1])
+
+    def test_empty_hashes(self) -> None:
+        table = self._table()
+        hashes = np.empty(0, dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 4)
+        assert len(out) == 0
+
+    def test_output_dtype(self) -> None:
+        table = self._table()
+        table[0] = 0
+        hashes = np.array([0], dtype=np.uint64)
+        out = unique_hits_direct_id_numba(hashes, table, np.uint64(7), 1)
+        assert out.dtype == np.int64
diff --git a/tests/v1/multiprocess/test_unified_touch.py b/tests/v1/multiprocess/test_unified_touch.py
new file mode 100644
index 0000000..38b69f3
--- /dev/null
+++ b/tests/v1/multiprocess/test_unified_touch.py
@@ -0,0 +1,335 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the unified touch feature in end_session.
+
+This module tests:
+1. L1EvictionPolicy.on_l1_keys_accessed bridges to policy.on_keys_touched
+2. L1EvictionPolicy.on_l1_keys_read_finished also triggers touch
+3. L1Manager.touch_keys dispatches to all registered listeners
+4. MPCacheServer.end_session performs unified touch with correct keys
+5. StorageManager.touch_l1_keys delegates to L1Manager
+"""
+
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey, ipc_key_to_object_keys
+from lmcache.v1.distributed.eviction import L1EvictionPolicy
+from lmcache.v1.distributed.eviction_policy import LRUEvictionPolicy
+from lmcache.v1.multiprocess.custom_types import IPCCacheServerKey
+from lmcache.v1.multiprocess.session import SessionManager
+from lmcache.v1.multiprocess.token_hasher import TokenHasher
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def make_key(chunk_hash: int, model: str = "model", kv_rank: int = 0) -> ObjectKey:
+    """Create an ObjectKey for testing."""
+    hash_bytes = ObjectKey.IntHash2Bytes(chunk_hash)
+    return ObjectKey(chunk_hash=hash_bytes, model_name=model, kv_rank=kv_rank)
+
+
+def make_ipc_key(
+    token_ids: list[int],
+    chunk_size: int = 4,
+    model_name: str = "model",
+    world_size: int = 1,
+    worker_id: int | None = None,
+    request_id: str = "req-1",
+) -> IPCCacheServerKey:
+    """Create an IPCCacheServerKey for testing."""
+    return IPCCacheServerKey.from_token_ids(
+        model_name=model_name,
+        world_size=world_size,
+        worker_id=worker_id,
+        token_ids=token_ids,
+        start=0,
+        end=len(token_ids),
+        request_id=request_id,
+    )
+
+
+@pytest.fixture
+def hasher() -> TokenHasher:
+    """TokenHasher with small chunk_size for testing."""
+    return TokenHasher(chunk_size=4, hash_algorithm="blake3")
+
+
+# =============================================================================
+# L1EvictionPolicy Bridge Tests
+# =============================================================================
+
+
+class TestL1EvictionPolicyAccessedBridge:
+    """Tests for L1EvictionPolicy.on_l1_keys_accessed bridging."""
+
+    def test_on_l1_keys_accessed_calls_policy_on_keys_touched(self):
+        """on_l1_keys_accessed should delegate to policy.on_keys_touched."""
+        mock_policy = MagicMock()
+        listener = L1EvictionPolicy(mock_policy)
+        keys = [make_key(1), make_key(2)]
+
+        listener.on_l1_keys_accessed(keys)
+
+        mock_policy.on_keys_touched.assert_called_once_with(keys)
+
+    def test_on_l1_keys_read_finished_also_touches(self):
+        """on_l1_keys_read_finished should call on_keys_touched."""
+        mock_policy = MagicMock()
+        listener = L1EvictionPolicy(mock_policy)
+        keys = [make_key(1), make_key(2)]
+
+        listener.on_l1_keys_read_finished(keys)
+
+        mock_policy.on_keys_touched.assert_called_once_with(keys)
+
+    def test_on_l1_keys_accessed_with_lru_policy(self):
+        """on_l1_keys_accessed should update LRU order via real LRU policy."""
+        lru = LRUEvictionPolicy()
+        listener = L1EvictionPolicy(lru)
+
+        # Create keys in order: 1, 2, 3
+        keys = [make_key(1), make_key(2), make_key(3)]
+        lru.on_keys_created(keys)
+
+        # Touch key 1 via the listener bridge
+        listener.on_l1_keys_accessed([make_key(1)])
+
+        # Eviction order should now be: 3, 2, 1 (1 is most recent)
+        candidates = lru.get_eviction_candidates(3)
+        assert ObjectKey.Bytes2IntHash(candidates[0].chunk_hash) == 3
+        assert ObjectKey.Bytes2IntHash(candidates[1].chunk_hash) == 2
+        assert ObjectKey.Bytes2IntHash(candidates[2].chunk_hash) == 1
+
+    def test_on_l1_keys_read_finished_updates_lru(self):
+        """on_l1_keys_read_finished should update LRU order."""
+        lru = LRUEvictionPolicy()
+        listener = L1EvictionPolicy(lru)
+
+        # Create keys in order: 1, 2, 3
+        keys = [make_key(1), make_key(2), make_key(3)]
+        lru.on_keys_created(keys)
+
+        # Call on_l1_keys_read_finished on key 1 - should touch it
+        listener.on_l1_keys_read_finished([make_key(1)])
+
+        # Key 1 is now most recently touched, eviction order: 2, 3, 1
+        candidates = lru.get_eviction_candidates(3)
+        assert ObjectKey.Bytes2IntHash(candidates[0].chunk_hash) == 3
+        assert ObjectKey.Bytes2IntHash(candidates[1].chunk_hash) == 2
+        assert ObjectKey.Bytes2IntHash(candidates[2].chunk_hash) == 1
+
+
+class TestL1EvictionPolicyUnifiedTouchOrder:
+    """Tests for the unified touch producing correct eviction order.
+
+    The key benefit of unified touch is that all chunks of a request
+    are touched in order, so eviction proceeds from the last chunk
+    backwards (most recent chunk evicted last).
+    """
+
+    def test_unified_touch_produces_reverse_eviction_order(self):
+        """Touching keys in order [1,2,3] should evict 1 first (LRU)."""
+        lru = LRUEvictionPolicy()
+        listener = L1EvictionPolicy(lru)
+
+        keys = [make_key(i) for i in range(1, 6)]
+        lru.on_keys_created(keys)
+
+        # Unified touch: touch all keys in order (simulating end_session)
+        listener.on_l1_keys_accessed(keys)
+
+        # Eviction should be in reverse order: 1 first (least recently touched)
+        # because on_keys_touched processes them sequentially,
+        # so key 5 is the most recently touched
+        candidates = lru.get_eviction_candidates(5)
+        evicted_ids = [ObjectKey.Bytes2IntHash(c.chunk_hash) for c in candidates]
+        # LRU evicts from the back of the ordered dict (least recent first)
+        # After touching [1,2,3,4,5] in order, 1 is least recent, 5 is most recent
+        assert evicted_ids == [5, 4, 3, 2, 1]
+
+    def test_per_read_touch_vs_unified_touch_order(self):
+        """Compare per-read touch (old behavior) vs unified touch (new behavior).
+
+        Old behavior: each retrieve touches its keys immediately.
+        New behavior: all keys are touched together at end_session.
+
+        With unified touch, the eviction order reflects the full request's
+        chunk ordering, not the order of individual retrieve calls.
+        """
+        # Scenario: request has chunks [1,2,3,4,5]
+        # Retrieve touches [1,2,3] (prefix hit), Store creates [4,5]
+        lru = LRUEvictionPolicy()
+
+        keys = [make_key(i) for i in range(1, 6)]
+        lru.on_keys_created(keys)
+
+        # Unified touch at end_session: touch all in order
+        lru.on_keys_touched(keys)
+
+        candidates = lru.get_eviction_candidates(5)
+        evicted_ids = [ObjectKey.Bytes2IntHash(c.chunk_hash) for c in candidates]
+        # Last chunk (5) should be evicted last (most recently touched)
+        assert evicted_ids[-1] == 1
+
+
+# =============================================================================
+# End Session Touch Integration Tests
+# =============================================================================
+
+
+class TestEndSessionTouchKeys:
+    """Tests for the end_session unified touch key generation logic.
+
+    These tests verify that end_session correctly:
+    1. Retrieves the session with accumulated hashes
+    2. Generates the correct ObjectKeys using lookup_ipc_key
+    3. Handles edge cases (no session, no lookup key, empty hashes)
+    """
+
+    def test_end_session_generates_correct_keys(self, hasher: TokenHasher):
+        """end_session should generate ObjectKeys from session hashes and lookup key."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        session = mgr.get_or_create("req-1")
+
+        tokens = list(range(12))  # 3 chunks of 4
+        session.set_tokens(tokens)
+        session.get_hashes(0, 12)
+
+        ipc_key = make_ipc_key(tokens, chunk_size=4, worker_id=None, request_id="req-1")
+        session.lookup_ipc_key = ipc_key
+
+        # Simulate end_session logic
+        removed = mgr.remove("req-1")
+        assert removed is not None
+        assert removed.lookup_ipc_key is not None
+
+        chunk_hashes = [TokenHasher.hash_to_bytes(h) for h in removed.get_hashes(0)]
+        obj_keys = ipc_key_to_object_keys(removed.lookup_ipc_key, chunk_hashes, [0])[0]
+
+        # With world_size=1 and worker_id=None, should have 3 keys
+        assert len(obj_keys) == 3
+
+    def test_end_session_expands_keys_for_world_size(self, hasher: TokenHasher):
+        """end_session should expand keys for all workers when world_size > 1."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        session = mgr.get_or_create("req-1")
+
+        tokens = list(range(8))  # 2 chunks of 4
+        session.set_tokens(tokens)
+        session.get_hashes(0, 8)
+
+        ipc_key = make_ipc_key(
+            tokens,
+            chunk_size=4,
+            world_size=2,
+            worker_id=None,
+            request_id="req-1",
+        )
+        session.lookup_ipc_key = ipc_key
+
+        removed = mgr.remove("req-1")
+        assert removed is not None
+        assert removed.lookup_ipc_key is not None
+
+        chunk_hashes = [TokenHasher.hash_to_bytes(h) for h in removed.get_hashes(0)]
+        obj_keys = ipc_key_to_object_keys(removed.lookup_ipc_key, chunk_hashes, [0])[0]
+
+        # 2 chunks * 2 workers = 4 keys
+        assert len(obj_keys) == 4
+
+    def test_end_session_no_session_skips_touch(self, hasher: TokenHasher):
+        """end_session should skip touch when session doesn't exist."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        removed = mgr.remove("nonexistent")
+        assert removed is None
+        # No error should occur
+
+    def test_end_session_no_lookup_key_skips_touch(self, hasher: TokenHasher):
+        """end_session should skip touch when session has no lookup_ipc_key."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        session = mgr.get_or_create("req-1")
+        session.set_tokens(list(range(8)))
+        session.get_hashes(0, 8)
+        # Don't set lookup_ipc_key
+
+        removed = mgr.remove("req-1")
+        assert removed is not None
+        assert removed.lookup_ipc_key is None
+        # No error should occur
+
+    def test_end_session_empty_hashes_produces_no_keys(self, hasher: TokenHasher):
+        """end_session should produce no keys when session has no computed hashes."""
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        session = mgr.get_or_create("req-1")
+
+        ipc_key = make_ipc_key(
+            list(range(8)), chunk_size=4, worker_id=None, request_id="req-1"
+        )
+        session.lookup_ipc_key = ipc_key
+        # Don't compute any hashes
+
+        removed = mgr.remove("req-1")
+        assert removed is not None
+        assert removed.lookup_ipc_key is not None
+
+        chunk_hashes = [TokenHasher.hash_to_bytes(h) for h in removed.get_hashes(0)]
+        obj_keys = ipc_key_to_object_keys(removed.lookup_ipc_key, chunk_hashes, [0])[0]
+        assert len(obj_keys) == 0
+
+    def test_end_session_hashes_cover_retrieve_and_store(self, hasher: TokenHasher):
+        """Session hashes should cover both retrieve and store ranges.
+
+        Simulates the typical flow:
+        1. lookup computes all hashes (but via TokenHasher, not Session)
+        2. retrieve calls session.get_hashes(0, hit_end)
+        3. store calls session.get_hashes(hit_end, total)
+        4. end_session uses session.get_hashes(0) to get all
+        """
+        mgr = SessionManager(hasher, ttl=600, cleanup_interval=None)
+        session = mgr.get_or_create("req-1")
+
+        tokens = list(range(20))  # 5 chunks of 4
+        session.set_tokens(tokens)
+
+        # Simulate retrieve: first 3 chunks
+        retrieve_hashes = session.get_hashes(0, 12)
+        assert len(retrieve_hashes) == 3
+
+        # Simulate store: last 2 chunks
+        store_hashes = session.get_hashes(12, 20)
+        assert len(store_hashes) == 2
+
+        # All hashes should cover all 5 chunks
+        all_hashes = session.get_hashes(0)
+        assert len(all_hashes) == 5
+        assert all_hashes == retrieve_hashes + store_hashes
+
+
+# =============================================================================
+# StoreListener No-op Tests
+# =============================================================================
+
+
+class TestStoreListenerAccessedNoop:
+    """Tests that StoreListener.on_l1_keys_accessed is a no-op."""
+
+    def test_store_listener_accessed_is_noop(self):
+        """StoreListener.on_l1_keys_accessed should not raise."""
+        # Import here to avoid import errors if store_controller has
+        # heavy dependencies
+        # First Party
+        from lmcache.v1.distributed.storage_controllers.store_controller import (
+            StoreListener,
+        )
+
+        # StoreListener requires an event_fd; use a mock
+        listener = MagicMock(spec=StoreListener)
+        # Call the real method on the class
+        StoreListener.on_l1_keys_accessed(listener, [make_key(1)])
+        # Should not raise - that's the test
diff --git a/tests/v1/multiprocess/test_usage_telemetry_server.py b/tests/v1/multiprocess/test_usage_telemetry_server.py
new file mode 100644
index 0000000..a1a2273
--- /dev/null
+++ b/tests/v1/multiprocess/test_usage_telemetry_server.py
@@ -0,0 +1,119 @@
+# SPDX-License-Identifier: Apache-2.0
+"""End-to-end test: the MP cache server emits usage telemetry at startup.
+
+Spawns a real ``run_cache_server`` in a child process with the stats-server
+URL pointed at a local HTTP sink, and asserts the startup report arrives
+over the wire.
+"""
+
+# Standard
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import multiprocessing
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.distributed.config import (
+    EvictionConfig,
+    L1ManagerConfig,
+    L1MemoryManagerConfig,
+    StorageManagerConfig,
+)
+from lmcache.v1.mp_observability.config import DEFAULT_OBSERVABILITY_CONFIG
+from lmcache.v1.multiprocess.config import MPServerConfig
+from lmcache.v1.multiprocess.server import run_cache_server
+
+if not torch.cuda.is_available():
+    pytest.skip(
+        "MP cache server requires an accelerator device",
+        allow_module_level=True,
+    )
+
+SERVER_PORT = 15599
+STARTUP_TIMEOUT_SECONDS = 90.0
+
+
+class _SinkHandler(BaseHTTPRequestHandler):
+    def do_POST(self) -> None:
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length))
+        self.server.received.append((self.path, body))  # type: ignore[attr-defined]
+        self.send_response(200)
+        self.end_headers()
+
+    def log_message(self, *args: object) -> None:
+        pass
+
+
+class _UsageSink(ThreadingHTTPServer):
+    def __init__(self) -> None:
+        super().__init__(("127.0.0.1", 0), _SinkHandler)
+        self.received: list[tuple[str, dict[str, object]]] = []
+
+
+def _usage_server_runner(port: int) -> None:
+    """Child-process entry point running a minimal cache server."""
+    mp_config = MPServerConfig(host="localhost", port=port)
+    storage_manager_config = StorageManagerConfig(
+        l1_manager_config=L1ManagerConfig(
+            memory_config=L1MemoryManagerConfig(
+                size_in_bytes=1 << 30,
+                use_lazy=True,
+            ),
+        ),
+        eviction_config=EvictionConfig(eviction_policy="LRU"),
+    )
+    run_cache_server(
+        mp_config=mp_config,
+        storage_manager_config=storage_manager_config,
+        obs_config=DEFAULT_OBSERVABILITY_CONFIG,
+    )
+
+
+def test_server_startup_emits_usage_report(monkeypatch, tmp_path):
+    sink = _UsageSink()
+    sink_thread = threading.Thread(target=sink.serve_forever, daemon=True)
+    sink_thread.start()
+
+    # The child inherits this environment at spawn: tracking enabled,
+    # stats URL pointed at the sink, HOME isolated so no real state files
+    # (machine_id) are touched.
+    monkeypatch.setenv("LMCACHE_TRACK_USAGE", "true")
+    monkeypatch.setenv(
+        "LMCACHE_USAGE_TRACK_URL", f"http://127.0.0.1:{sink.server_address[1]}"
+    )
+    monkeypatch.setenv("HOME", str(tmp_path))
+
+    context = multiprocessing.get_context("spawn")
+    process = context.Process(target=_usage_server_runner, args=(SERVER_PORT,))
+    process.start()
+    try:
+        deadline = time.monotonic() + STARTUP_TIMEOUT_SECONDS
+        while time.monotonic() < deadline and len(sink.received) < 2:
+            time.sleep(0.1)
+        received = list(sink.received)
+        assert len(received) == 2, f"expected 2 usage messages, got {received}"
+
+        assert {path for path, _ in received} == {"/context"}
+        payloads = {payload["message_type"]: payload for _, payload in received}
+        assert set(payloads) == {"EnvMessage", "MPServerMessage"}
+
+        mp_payload = payloads["MPServerMessage"]
+        assert mp_payload["deployment_mode"] == "mp_server"
+        assert mp_payload["chunk_size"] == 256
+        assert mp_payload["l1_size_bytes"] == 1 << 30
+        assert "instance_id" not in mp_payload
+        assert payloads["EnvMessage"]["session_id"] == mp_payload["session_id"]
+    finally:
+        process.terminate()
+        process.join(timeout=10)
+        if process.is_alive():
+            process.kill()
+            process.join()
+        sink.shutdown()
+        sink.server_close()
diff --git a/tests/v1/multiprocess/test_warm_prefetch.py b/tests/v1/multiprocess/test_warm_prefetch.py
new file mode 100644
index 0000000..d2962ed
--- /dev/null
+++ b/tests/v1/multiprocess/test_warm_prefetch.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the warm-prefetch job table (:mod:`warm_prefetch`).
+
+Fakes the ``StorageManager``, so no real engine/CUDA/L2 is needed. Verifies the
+no-lock contract: ``submit`` uses ``PrefetchMode.WARM`` (the no-lock warm
+path), status is polled reactively, and completion releases **nothing** (no
+``finish_read`` — the warm holds no lock).
+"""
+
+# Standard
+from dataclasses import dataclass
+from typing import Optional
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey, PrefetchMode, TrimPolicy
+from lmcache.v1.multiprocess.warm_prefetch import (
+    COMPLETED,
+    PENDING,
+    UNKNOWN,
+    WarmPrefetchJobs,
+)
+
+
+def _key(i: int) -> ObjectKey:
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(i),
+        model_name="test_model",
+        kv_rank=0,
+    )
+
+
+class _FakeHandle:
+    def __init__(self, total: int) -> None:
+        self.total_requested_keys = total
+
+
+class _FakeBitmap:
+    """Stands in for the found-key ``Bitmap``; ``popcount`` is the found count."""
+
+    def __init__(self, n: int) -> None:
+        self._n = n
+
+    def popcount(self) -> int:
+        return self._n
+
+
+@dataclass
+class _FakeStorageManager:
+    found: int = 0
+    delay_polls: int = 0
+
+    submit_args: Optional[dict] = None
+    finish_called: bool = False
+    _polls: int = 0
+    _total: int = 0
+
+    def submit_prefetch_task(self, keys, layout_desc, mode=None, policy=None, **_):
+        self._total = len(keys)
+        self.submit_args = {"keys": list(keys), "mode": mode, "policy": policy}
+        return _FakeHandle(self._total)
+
+    def query_prefetch_status(self, handle):
+        if self._polls < self.delay_polls:
+            self._polls += 1
+            return None
+        return _FakeBitmap(self.found)
+
+    def finish_read_prefetched(self, keys, extra_count: int = 0) -> None:
+        # Must never be called: the warm holds no lock.
+        self.finish_called = True
+
+
+def test_submit_uses_retain_and_poll_completes_without_release():
+    """submit goes through the WARM (no-lock) path; the caller polls
+    (pending → completed); completion releases nothing and consumes the job."""
+    keys = [_key(0), _key(1)]
+    sm = _FakeStorageManager(found=2, delay_polls=2)
+    jobs = WarmPrefetchJobs()
+
+    request_id = jobs.submit(sm, keys, layout_desc=object())
+    assert sm.submit_args is not None
+    assert sm.submit_args["mode"] is PrefetchMode.WARM
+    assert sm.submit_args["policy"] is TrimPolicy.SPARSE
+
+    # Pending while the load runs (reactive poll; no background loop).
+    assert jobs.poll(sm, request_id).state == PENDING
+    assert jobs.poll(sm, request_id).state == PENDING
+
+    status = jobs.poll(sm, request_id)
+    assert status.state == COMPLETED
+    assert status.found_keys == 2
+    assert status.total_keys == 2
+    # No lock was held, so nothing is released.
+    assert sm.finish_called is False
+
+    # Exactly-once: the completing poll consumed the job.
+    assert jobs.poll(sm, request_id).state == UNKNOWN
+
+
+def test_poll_unknown_request_id():
+    """Polling an id that was never submitted returns UNKNOWN."""
+    sm = _FakeStorageManager()
+    jobs = WarmPrefetchJobs()
+    assert jobs.poll(sm, "does-not-exist").state == UNKNOWN
+    assert sm.finish_called is False
diff --git a/tests/v1/multiprocess/test_worker_liveness.py b/tests/v1/multiprocess/test_worker_liveness.py
new file mode 100644
index 0000000..80947c8
--- /dev/null
+++ b/tests/v1/multiprocess/test_worker_liveness.py
@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for server-side worker liveness tracking and reaping.
+
+Cover the public liveness interfaces of the transfer modules, the
+management reaper wiring, the blend reap listener, and config validation.
+No GPU or live server is required; module-level construction dependencies
+are stubbed.
+"""
+
+# Standard
+from typing import cast
+from unittest.mock import MagicMock
+import threading
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.multiprocess.config import MPServerConfig
+from lmcache.v1.multiprocess.modules import engine_driven_transfer as non_gpu_mod
+from lmcache.v1.multiprocess.modules import lmcache_driven_transfer as gpu_mod
+from lmcache.v1.multiprocess.modules.engine_driven_transfer import (
+    EngineDrivenTransferModule,
+)
+from lmcache.v1.multiprocess.modules.lmcache_driven_transfer import (
+    ContextEntry,
+    LMCacheDrivenTransferModule,
+)
+from lmcache.v1.multiprocess.modules.management import ManagementModule
+from lmcache.v1.periodic_thread import PeriodicThreadRegistry
+
+
+def _bare_gpu_module() -> LMCacheDrivenTransferModule:
+    """A LMCacheDrivenTransferModule with only the liveness state initialized.
+
+    Bypasses __init__ (which starts a CUDA host-func dispatcher) so the
+    liveness methods can be exercised without GPU hardware.
+    """
+    module = LMCacheDrivenTransferModule.__new__(LMCacheDrivenTransferModule)
+    module._ctx = MagicMock(name="ctx")
+    module._cache_contexts = {}
+    module._lock = threading.Lock()
+    return module
+
+
+def _bare_non_gpu_module() -> EngineDrivenTransferModule:
+    """A EngineDrivenTransferModule with only the liveness state initialized."""
+    module = EngineDrivenTransferModule.__new__(EngineDrivenTransferModule)
+    module._ctx = MagicMock(name="ctx")
+    module._engine_driven_contexts = {}
+    module._strategies = {}
+    module._lock = threading.Lock()
+    module._pending_shm_writes = {}
+    module._pending_shm_reads = {}
+    module._pending_shm_lock = threading.Lock()
+    return module
+
+
+def test_gpu_register_inserts_unlatched_entry(monkeypatch) -> None:
+    """register_kv_cache inserts an entry that is not yet ping-proven."""
+    monkeypatch.setattr(
+        gpu_mod, "create_cache_context", lambda *a, **kw: MagicMock(num_layers=2)
+    )
+    monkeypatch.setattr(gpu_mod, "get_layout_desc", lambda *a, **kw: MagicMock())
+    module = _bare_gpu_module()
+
+    module.register_kv_cache(1, MagicMock(), "model", 1, MagicMock(), MagicMock(), [])
+
+    assert module.tracked_instance_count() == 1
+    entry = module.get_and_touch_context_entry(1)
+    assert entry is not None and entry.has_liveness_signal is False
+
+
+def test_gpu_noop_register_refreshes_without_latching(monkeypatch) -> None:
+    """Re-registering a known instance refreshes last_seen but does not
+    rebuild the context or latch the ping-proven flag."""
+    create = MagicMock(return_value=MagicMock(num_layers=2))
+    monkeypatch.setattr(gpu_mod, "create_cache_context", create)
+    monkeypatch.setattr(gpu_mod, "get_layout_desc", lambda *a, **kw: MagicMock())
+    module = _bare_gpu_module()
+    module.register_kv_cache(1, MagicMock(), "model", 1, MagicMock(), MagicMock(), [])
+    module._cache_contexts[1].last_seen = 0.0
+
+    module.register_kv_cache(1, MagicMock(), "model", 1, MagicMock(), MagicMock(), [])
+
+    assert create.call_count == 1  # not rebuilt
+    assert module._cache_contexts[1].last_seen > 0.0  # refreshed
+    assert module._cache_contexts[1].has_liveness_signal is False
+
+
+def test_gpu_touch_latches_get_does_not() -> None:
+    """touch_instance marks ping-proven; get_and_touch_context_entry only refreshes."""
+    module = _bare_gpu_module()
+    module._cache_contexts[1] = ContextEntry(MagicMock(), "m", 1, last_seen=0.0)
+
+    module.get_and_touch_context_entry(1)
+    assert module._cache_contexts[1].last_seen > 0.0
+    assert module._cache_contexts[1].has_liveness_signal is False
+
+    module.touch_instance(1)
+    assert module._cache_contexts[1].has_liveness_signal is True
+    module.touch_instance(999)  # absent -> no error
+
+
+def test_gpu_reap_two_tier_windows() -> None:
+    """Ping-proven entries reap at the timeout; never-pinged ones survive
+    until the larger registration grace."""
+    module = _bare_gpu_module()
+    old = time.monotonic() - 1000.0
+    module._cache_contexts[1] = ContextEntry(MagicMock(), "m", 1, old, True)
+    module._cache_contexts[2] = ContextEntry(MagicMock(), "m", 1, old, False)
+    module._cache_contexts[3] = ContextEntry(
+        MagicMock(), "m", 1, time.monotonic(), True
+    )
+
+    reaped = module.reap_stale_instances(120.0, 3600.0)
+
+    assert reaped == [1]  # only the ping-proven stale entry
+    assert module.tracked_instance_count() == 2
+    cast(
+        MagicMock, module._ctx.layout_desc_registry.unregister
+    ).assert_called_once_with("m", 1)
+
+
+def test_gpu_unregister_cleans_up() -> None:
+    """unregister_kv_cache pops and releases; missing id is a no-op."""
+    module = _bare_gpu_module()
+    module._cache_contexts[1] = ContextEntry(MagicMock(), "m", 1, time.monotonic())
+
+    module.unregister_kv_cache(1)
+    assert module.tracked_instance_count() == 0
+    cast(
+        MagicMock, module._ctx.layout_desc_registry.unregister
+    ).assert_called_once_with("m", 1)
+
+    module.unregister_kv_cache(1)  # already gone -> no exception
+
+
+def test_non_gpu_reap_pops_strategy_as_pair() -> None:
+    """Reaping a non-GPU entry pops its strategy in the same scan, keeping
+    'strategy present iff entry present'."""
+    module = _bare_non_gpu_module()
+    old = time.monotonic() - 1000.0
+    module._engine_driven_contexts[1] = non_gpu_mod.EngineDrivenContextEntry(
+        MagicMock(), "m", 1, old, True
+    )
+    module._strategies[1] = MagicMock()
+    module._engine_driven_contexts[2] = non_gpu_mod.EngineDrivenContextEntry(
+        MagicMock(), "m", 1, old, False
+    )
+    module._strategies[2] = MagicMock()
+
+    reaped = module.reap_stale_instances(120.0, 3600.0)
+
+    assert reaped == [1]
+    assert 1 not in module._strategies  # strategy popped with the entry
+    assert 2 in module._strategies  # never-pinged survives on grace
+
+
+def test_non_gpu_resolve_for_transfer_refreshes_and_raises() -> None:
+    """_resolve_for_transfer returns (entry, strategy) and refreshes
+    last_seen; an unknown id raises ValueError."""
+    module = _bare_non_gpu_module()
+    module._engine_driven_contexts[1] = non_gpu_mod.EngineDrivenContextEntry(
+        MagicMock(), "m", 1, 0.0, False
+    )
+    strategy = MagicMock()
+    module._strategies[1] = strategy
+
+    entry, resolved = module._resolve_for_transfer(1)
+    assert resolved is strategy
+    assert entry.last_seen > 0.0
+    assert entry.has_liveness_signal is False  # traffic does not latch
+
+    with pytest.raises(ValueError, match="not registered"):
+        module._resolve_for_transfer(999)
+
+
+class _FakeTarget:
+    """Liveness target double recording touches/drops and scripted reaps."""
+
+    def __init__(self) -> None:
+        self.touched: list[int] = []
+        self.to_reap: list[int] = []
+        self.dropped: list[int] = []
+        self.count = 0
+
+    def touch_instance(self, instance_id: int) -> None:
+        self.touched.append(instance_id)
+
+    def reap_stale_instances(
+        self, reap_timeout_s: float, registration_grace_s: float
+    ) -> list[int]:
+        reaped = self.to_reap[:]
+        self.to_reap.clear()
+        return reaped
+
+    def tracked_instance_count(self) -> int:
+        return self.count
+
+    def drop_instance_state(self, instance_id: int) -> None:
+        self.dropped.append(instance_id)
+
+
+@pytest.fixture(autouse=True)
+def _reset_periodic_registry():
+    """Keep the reaper out of the global registry across tests."""
+    PeriodicThreadRegistry.reset()
+    yield
+    PeriodicThreadRegistry.reset()
+
+
+def test_management_ping_touches_targets() -> None:
+    """ping refreshes every target for a real id; None is ignored."""
+    target = _FakeTarget()
+    mgmt = ManagementModule(MagicMock(), liveness_targets=[target])
+
+    assert mgmt.ping(42) is True
+    assert mgmt.ping(None) is True
+    assert target.touched == [42]
+
+
+def test_management_reaper_reaps_and_drops() -> None:
+    """The reaper scans targets and calls drop_instance_state for reaped ids."""
+    target = _FakeTarget()
+    mgmt = ManagementModule(
+        MagicMock(),
+        liveness_targets=[target],
+        worker_reap_timeout_seconds=0.4,
+        worker_registration_grace_seconds=0.8,
+    )
+    try:
+        target.to_reap = [7]
+        deadline = time.monotonic() + 2.0
+        while target.dropped != [7] and time.monotonic() < deadline:
+            time.sleep(0.02)
+        assert target.dropped == [7]
+    finally:
+        mgmt.close()
+
+
+def test_management_reaper_disabled_when_timeout_zero() -> None:
+    """timeout == 0 starts no reaper thread."""
+    mgmt = ManagementModule(
+        MagicMock(),
+        liveness_targets=[_FakeTarget()],
+        worker_reap_timeout_seconds=0.0,
+    )
+    assert mgmt._reaper is None
+    assert mgmt.ping(1) is True
+
+
+def test_management_report_status_summarizes_liveness() -> None:
+    """report_status reports a worker_liveness summary when targets exist."""
+    target = _FakeTarget()
+    target.count = 3
+    mgmt = ManagementModule(
+        MagicMock(),
+        liveness_targets=[target],
+        worker_reap_timeout_seconds=120.0,
+        worker_registration_grace_seconds=3600.0,
+    )
+    try:
+        status = mgmt.report_status()["worker_liveness"]
+        assert status["enabled"] is True
+        assert status["tracked_instances"] == 3
+        assert status["reap_timeout_seconds"] == 120.0
+    finally:
+        mgmt.close()
+
+    assert ManagementModule(MagicMock()).report_status() == {}
+
+
+def test_blend_drop_instance_state_drops_rope_state() -> None:
+    """drop_instance_state pops the reaped instance's CB rope state.
+
+    The GPU context is no longer mirrored in BlendV3Module (reaping the GPU
+    entry frees it directly), so only the rope state is dropped here.
+    """
+    # First Party
+    from lmcache.v1.multiprocess.modules.blend_v3 import BlendV3Module
+
+    module = BlendV3Module.__new__(BlendV3Module)
+    module._cb_rope_state = {5: MagicMock()}
+
+    module.drop_instance_state(5)
+
+    assert 5 not in module._cb_rope_state
+    module.drop_instance_state(999)  # nothing held -> no error
+
+
+def test_config_rejects_bad_reap_timeouts() -> None:
+    """Validation rejects sub-floor reap timeouts and undersized grace."""
+    with pytest.raises(ValueError, match="reap timeout"):
+        MPServerConfig(worker_reap_timeout_seconds=10.0)
+    with pytest.raises(ValueError, match="registration grace"):
+        MPServerConfig(
+            worker_reap_timeout_seconds=120.0,
+            worker_registration_grace_seconds=60.0,
+        )
+
+
+def test_config_accepts_disabled_and_defaults() -> None:
+    """0 disables reaping; defaults satisfy the grace >= timeout invariant."""
+    MPServerConfig(
+        worker_reap_timeout_seconds=0.0, worker_registration_grace_seconds=0.0
+    )
+    default = MPServerConfig()
+    assert default.worker_reap_timeout_seconds == 120.0
+    assert default.worker_registration_grace_seconds == 3600.0
diff --git a/tests/v1/native_storage_ops/test_bitmap.py b/tests/v1/native_storage_ops/test_bitmap.py
new file mode 100644
index 0000000..8cb220f
--- /dev/null
+++ b/tests/v1/native_storage_ops/test_bitmap.py
@@ -0,0 +1,680 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+import random
+
+# Third Party
+import pytest
+
+pytest.importorskip(
+    "lmcache.native_storage_ops",
+    reason="native_storage_ops extension not built",
+)
+
+# First Party
+from lmcache.native_storage_ops import Bitmap
+
+
+class TestBitmapSetClearTest:
+    """Test set, clear, and test for various sizes (including non-multiple-of-8)."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 15, 16, 17, 24, 25])
+    def test_set_and_test(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            assert not b.test(i)
+        for i in range(0, size, 2):
+            b.set(i)
+        for i in range(size):
+            assert b.test(i) == (i % 2 == 0)
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 15, 16, 17])
+    def test_clear(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        for i in range(size):
+            assert b.test(i)
+        for i in range(0, size, 2):
+            b.clear(i)
+        for i in range(size):
+            assert b.test(i) == (i % 2 == 1)
+
+    @pytest.mark.parametrize("size", [1, 5, 9, 12])
+    def test_out_of_range_no_op(self, size):
+        b = Bitmap(size)
+        b.set(size)  # no-op
+        b.set(size + 10)  # no-op
+        b.clear(size)
+        b.clear(size + 10)
+        for i in range(size):
+            assert not b.test(i)
+        assert not b.test(size)
+        assert not b.test(size + 1)
+
+    def test_single_bit_size_one(self):
+        b = Bitmap(1)
+        assert not b.test(0)
+        b.set(0)
+        assert b.test(0)
+        b.clear(0)
+        assert not b.test(0)
+
+
+class TestBitmapSetRange:
+    """set_range([start, end)) must match the equivalent per-bit set, including
+    single-byte, head/middle/tail spans, clamping, and empty ranges."""
+
+    @pytest.mark.parametrize(
+        "size,start,end",
+        [
+            (16, 3, 3),  # empty range -> no-op
+            (16, 0, 0),  # empty at 0
+            (16, 2, 5),  # within one byte
+            (16, 0, 8),  # exactly one full byte
+            (16, 0, 16),  # whole bitmap
+            (24, 3, 20),  # head + middle byte + tail
+            (24, 8, 16),  # exactly the middle byte
+            (10, 5, 100),  # end clamped to size
+            (10, 9, 10),  # last bit only
+            (10, 100, 200),  # fully out of range -> no-op
+        ],
+    )
+    def test_set_range_matches_per_bit(self, size, start, end):
+        ranged = Bitmap(size)
+        ranged.set_range(start, end)
+
+        per_bit = Bitmap(size)
+        for i in range(start, min(end, size)):
+            per_bit.set(i)
+
+        assert ranged.get_indices_list() == per_bit.get_indices_list()
+
+    def test_set_range_accumulates(self):
+        b = Bitmap(32)
+        b.set_range(2, 6)
+        b.set_range(10, 12)
+        assert b.get_indices_list() == [2, 3, 4, 5, 10, 11]
+
+    def test_set_range_random_against_per_bit(self):
+        rng = random.Random(0)
+        for _ in range(500):
+            size = rng.randint(0, 40)
+            start = rng.randint(0, size + 4)
+            end = rng.randint(0, size + 4)
+            ranged = Bitmap(size)
+            ranged.set_range(start, end)
+            per_bit = Bitmap(size)
+            for i in range(start, min(end, size)):
+                per_bit.set(i)
+            assert ranged.get_indices_list() == per_bit.get_indices_list()
+
+
+class TestBitmapPopcount:
+    """Test popcount (count of set bits), especially for size not multiple of 8."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 15, 16, 17, 24, 25])
+    def test_popcount_all_zeros(self, size):
+        b = Bitmap(size)
+        assert b.popcount() == 0
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 15, 16, 17])
+    def test_popcount_all_ones(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        assert b.popcount() == size
+
+    @pytest.mark.parametrize("size", [1, 5, 9, 12, 20])
+    def test_popcount_partial(self, size):
+        b = Bitmap(size)
+        for i in range(0, size, 2):
+            b.set(i)
+        expected = (size + 1) // 2
+        assert b.popcount() == expected, f"size={size}"
+
+    @pytest.mark.parametrize("size", [9, 12, 20])
+    def test_popcount_random(self, size):
+        b = Bitmap(size)
+        one_counts = 5
+        one_positions = random.sample(range(size), one_counts)
+        for i in one_positions:
+            b.set(i)
+        assert b.popcount() == one_counts
+
+
+class TestBitmapClzClo:
+    """Test count leading zeros (clz) and count leading ones (clo)."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 15, 16, 17])
+    def test_clz_all_zeros(self, size):
+        b = Bitmap(size)
+        assert b.count_leading_zeros() == size
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_clz_first_bit_set(self, size):
+        b = Bitmap(size)
+        b.set(0)
+        assert b.count_leading_zeros() == 0
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10])
+    def test_clz_second_bit_set(self, size):
+        b = Bitmap(size)
+        b.set(1)
+        assert b.count_leading_zeros() == 1
+
+    def test_clz_middle_bits_set(self):
+        # size=9: bits 0..8; set 3,4,5 -> leading zeros = 3
+        b = Bitmap(9)
+        b.set(3)
+        b.set(4)
+        b.set(5)
+        assert b.count_leading_zeros() == 3
+
+    def test_clz_last_bit_only_size_9(self):
+        b = Bitmap(9)
+        b.set(8)  # only last bit (index 8)
+        assert b.count_leading_zeros() == 8
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_clo_all_ones(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        assert b.count_leading_ones() == size
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10])
+    def test_clo_all_zeros(self, size):
+        b = Bitmap(size)
+        assert b.count_leading_ones() == 0
+
+    def test_clo_first_zero_at_3(self):
+        b = Bitmap(9)
+        b.set(0)
+        b.set(1)
+        b.set(2)
+        # bits 3..8 are 0
+        assert b.count_leading_ones() == 3
+
+    def test_clo_partial_byte_size_10(self):
+        # 10 bits: all set -> clo = 10
+        b = Bitmap(10)
+        for i in range(10):
+            b.set(i)
+        assert b.count_leading_ones() == 10
+
+    def test_clo_partial_byte_first_zero_at_5(self):
+        b = Bitmap(10)
+        for i in range(5):
+            b.set(i)
+        assert b.count_leading_ones() == 5
+
+
+class TestBitmapAnd:
+    """Test bitwise AND between two bitmaps."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 16, 17])
+    def test_and_same_size_all_overlap(self, size):
+        a = Bitmap(size)
+        b = Bitmap(size)
+        for i in range(0, size, 2):
+            a.set(i)
+        for i in range(1, size, 2):
+            b.set(i)
+        c = a & b
+        assert c.popcount() == 0
+        for i in range(size):
+            assert not c.test(i)
+
+    @pytest.mark.parametrize("size", [1, 9, 10])
+    def test_and_same_size_intersection(self, size):
+        a = Bitmap(size)
+        b = Bitmap(size)
+        for i in range(size):
+            a.set(i)
+        for i in range(0, size, 2):
+            b.set(i)
+        c = a & b
+        assert c.popcount() == (size + 1) // 2
+        for i in range(size):
+            assert c.test(i) == (i % 2 == 0)
+
+    def test_and_different_sizes_result_truncated(self):
+        a = Bitmap(10)
+        b = Bitmap(5)
+        for i in range(10):
+            a.set(i)
+        for i in range(5):
+            b.set(i)
+        c = a & b
+        # Result is min(10,5)=5 bits, all set
+        assert c.popcount() == 5
+        for i in range(5):
+            assert c.test(i)
+
+    def test_and_different_sizes_other_longer(self):
+        a = Bitmap(5)
+        b = Bitmap(10)
+        for i in range(5):
+            a.set(i)
+        for i in range(10):
+            b.set(i)
+        c = a & b
+        assert c.popcount() == 5
+        for i in range(5):
+            assert c.test(i)
+
+
+class TestBitmapToString:
+    """Test string representation (bit 0 = leftmost character)."""
+
+    def test_to_string_empty_zero_bits(self):
+        # Size 0 might not be allowed; skip or use size 1
+        b = Bitmap(1)
+        b.clear(0)
+        assert "0" in str(b)
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10])
+    def test_to_string_matches_set_bits(self, size):
+        b = Bitmap(size)
+        for i in range(0, size, 2):
+            b.set(i)
+        s = str(b)
+        print(s)
+        assert len(s) == size
+        for i in range(size):
+            assert s[i] == "1" if (i % 2 == 0) else "0"
+
+    def test_repr_calls_to_string(self):
+        b = Bitmap(3)
+        b.set(1)
+        r = repr(b)
+        assert "1" in r and "0" in r
+
+
+class TestBitmapOr:
+    """Test bitwise OR between two bitmaps."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 16, 17])
+    def test_or_same_size_no_overlap(self, size):
+        a = Bitmap(size)
+        b = Bitmap(size)
+        for i in range(0, size, 2):
+            a.set(i)
+        for i in range(1, size, 2):
+            b.set(i)
+        c = a | b
+        assert c.popcount() == size
+        for i in range(size):
+            assert c.test(i)
+
+    @pytest.mark.parametrize("size", [1, 9, 10])
+    def test_or_same_size_with_overlap(self, size):
+        a = Bitmap(size)
+        b = Bitmap(size)
+        for i in range(size):
+            a.set(i)
+        for i in range(0, size, 2):
+            b.set(i)
+        c = a | b
+        assert c.popcount() == size
+
+    def test_or_different_sizes_result_truncated(self):
+        a = Bitmap(10)
+        b = Bitmap(5)
+        for i in range(0, 10, 2):
+            a.set(i)
+        for i in range(1, 5, 2):
+            b.set(i)
+        c = a | b
+        # Result is min(10,5)=5 bits
+        assert c.popcount() == 5
+        for i in range(5):
+            assert c.test(i)
+
+    def test_or_both_empty(self):
+        a = Bitmap(8)
+        b = Bitmap(8)
+        c = a | b
+        assert c.popcount() == 0
+
+
+class TestBitmapGetIndices:
+    """Test get_indices_list and get_indices_set."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_get_indices_list_all_zeros(self, size):
+        b = Bitmap(size)
+        assert b.get_indices_list() == []
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_get_indices_list_all_ones(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        assert b.get_indices_list() == list(range(size))
+
+    @pytest.mark.parametrize("size", [9, 10, 17, 25])
+    def test_get_indices_list_even_bits(self, size):
+        b = Bitmap(size)
+        expected = list(range(0, size, 2))
+        for i in expected:
+            b.set(i)
+        assert b.get_indices_list() == expected
+
+    @pytest.mark.parametrize("size", [9, 12, 20])
+    def test_get_indices_list_random(self, size):
+        b = Bitmap(size)
+        positions = sorted(random.sample(range(size), 5))
+        for i in positions:
+            b.set(i)
+        assert b.get_indices_list() == positions
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_get_indices_set_all_zeros(self, size):
+        b = Bitmap(size)
+        assert b.get_indices_set() == set()
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_get_indices_set_all_ones(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        assert b.get_indices_set() == set(range(size))
+
+    @pytest.mark.parametrize("size", [9, 12, 20])
+    def test_get_indices_set_random(self, size):
+        b = Bitmap(size)
+        positions = random.sample(range(size), 5)
+        for i in positions:
+            b.set(i)
+        assert b.get_indices_set() == set(positions)
+
+    def test_get_indices_list_and_set_consistent(self):
+        b = Bitmap(17)
+        for i in [0, 3, 8, 15, 16]:
+            b.set(i)
+        assert set(b.get_indices_list()) == b.get_indices_set()
+
+
+class TestBitmapGather:
+    """Test gather operation."""
+
+    def test_gather_basic(self):
+        b = Bitmap(5)
+        b.set(0)
+        b.set(2)
+        b.set(4)
+        items = ["a", "b", "c", "d", "e"]
+        assert b.gather(items) == ["a", "c", "e"]
+
+    def test_gather_all_set(self):
+        b = Bitmap(4)
+        for i in range(4):
+            b.set(i)
+        items = [10, 20, 30, 40]
+        assert b.gather(items) == [10, 20, 30, 40]
+
+    def test_gather_none_set(self):
+        b = Bitmap(3)
+        items = ["x", "y", "z"]
+        assert b.gather(items) == []
+
+    def test_gather_mixed_types(self):
+        b = Bitmap(4)
+        b.set(1)
+        b.set(3)
+        items = [1, "two", 3.0, None]
+        assert b.gather(items) == ["two", None]
+
+    @pytest.mark.parametrize("size", [9, 10, 17])
+    def test_gather_preserves_order(self, size):
+        b = Bitmap(size)
+        positions = sorted(random.sample(range(size), 5))
+        for i in positions:
+            b.set(i)
+        items = list(range(size))
+        assert b.gather(items) == positions
+
+    def test_gather_single_element(self):
+        b = Bitmap(1)
+        b.set(0)
+        assert b.gather(["only"]) == ["only"]
+
+    def test_gather_accepts_tuple(self):
+        # gather takes any sequence, not just list (e.g. l2_orig_indices tuple).
+        b = Bitmap(5)
+        b.set(1)
+        b.set(3)
+        assert b.gather((10, 11, 12, 13, 14)) == [11, 13]
+
+
+class TestBitmapInvert:
+    """Test bitwise NOT (~) operation."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 16, 17])
+    def test_invert_all_zeros_gives_all_ones(self, size):
+        b = Bitmap(size)
+        inv = ~b
+        assert inv.popcount() == size
+        for i in range(size):
+            assert inv.test(i)
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 16, 17])
+    def test_invert_all_ones_gives_all_zeros(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        inv = ~b
+        assert inv.popcount() == 0
+        for i in range(size):
+            assert not inv.test(i)
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17, 25])
+    def test_invert_flips_each_bit(self, size):
+        b = Bitmap(size)
+        for i in range(0, size, 2):
+            b.set(i)
+        inv = ~b
+        for i in range(size):
+            assert inv.test(i) == (i % 2 == 1)
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 17])
+    def test_double_invert_is_identity(self, size):
+        b = Bitmap(size)
+        positions = [i for i in range(size) if i % 3 == 0]
+        for i in positions:
+            b.set(i)
+        result = ~(~b)
+        for i in range(size):
+            assert result.test(i) == b.test(i)
+
+    def test_invert_does_not_mutate_original(self):
+        b = Bitmap(10)
+        b.set(0)
+        b.set(5)
+        _ = ~b
+        assert b.popcount() == 2
+        assert b.test(0)
+        assert b.test(5)
+
+    @pytest.mark.parametrize("size", [9, 10, 17])
+    def test_invert_popcount_complement(self, size):
+        b = Bitmap(size)
+        for i in range(0, size, 3):
+            b.set(i)
+        inv = ~b
+        assert b.popcount() + inv.popcount() == size
+
+    def test_invert_and_original_gives_zero(self):
+        b = Bitmap(10)
+        for i in [1, 3, 5, 7, 9]:
+            b.set(i)
+        result = b & ~b
+        assert result.popcount() == 0
+
+    def test_invert_or_original_gives_all_ones(self):
+        b = Bitmap(10)
+        for i in [1, 3, 5, 7, 9]:
+            b.set(i)
+        result = b | ~b
+        assert result.popcount() == 10
+
+
+class TestBitmapPrefixConstructor:
+    """Test Bitmap(size, prefix_bits) constructor."""
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 16, 17, 25])
+    def test_prefix_zero(self, size):
+        b = Bitmap(size, 0)
+        assert b.popcount() == 0
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 10, 16, 17, 25])
+    def test_prefix_all(self, size):
+        b = Bitmap(size, size)
+        assert b.popcount() == size
+        assert b.count_leading_ones() == size
+
+    @pytest.mark.parametrize("size", [8, 9, 10, 16, 17, 25])
+    def test_prefix_partial(self, size):
+        prefix = size // 2
+        b = Bitmap(size, prefix)
+        assert b.popcount() == prefix
+        assert b.count_leading_ones() == prefix
+        for i in range(prefix):
+            assert b.test(i)
+        for i in range(prefix, size):
+            assert not b.test(i)
+
+    @pytest.mark.parametrize("size", [1, 7, 8, 9, 16, 17])
+    def test_prefix_one(self, size):
+        b = Bitmap(size, 1)
+        assert b.popcount() == 1
+        assert b.test(0)
+        for i in range(1, size):
+            assert not b.test(i)
+
+    def test_prefix_exceeds_size_clamped(self):
+        b = Bitmap(5, 100)
+        assert b.popcount() == 5
+        assert b.count_leading_ones() == 5
+
+    @pytest.mark.parametrize("size", [8, 16, 24])
+    def test_prefix_exact_byte_boundary(self, size):
+        b = Bitmap(size, 8)
+        assert b.popcount() == 8
+        assert b.count_leading_ones() == 8
+        for i in range(8):
+            assert b.test(i)
+        for i in range(8, size):
+            assert not b.test(i)
+
+    @pytest.mark.parametrize(
+        "size,prefix",
+        [(9, 3), (10, 5), (17, 9), (25, 13)],
+    )
+    def test_prefix_matches_manual_set(self, size, prefix):
+        """Bitmap(size, prefix) should be identical to setting bits 0..prefix-1."""
+        a = Bitmap(size, prefix)
+        b = Bitmap(size)
+        for i in range(prefix):
+            b.set(i)
+        assert a.popcount() == b.popcount()
+        assert a.get_indices_list() == b.get_indices_list()
+        assert str(a) == str(b)
+
+    def test_prefix_zero_size(self):
+        b = Bitmap(0, 0)
+        assert b.popcount() == 0
+
+
+class TestBitmapNonMultipleOfEight:
+    """Focused tests when length is not a multiple of 8."""
+
+    @pytest.mark.parametrize("size", [1, 2, 3, 5, 7, 9, 10, 11, 15, 17, 23, 25])
+    def test_roundtrip_set_test_all_positions(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+            assert b.test(i)
+            b.clear(i)
+            assert not b.test(i)
+            b.set(i)
+
+    @pytest.mark.parametrize("size", [9, 10, 12, 17])
+    def test_popcount_only_low_bits_counted_in_last_byte(self, size):
+        b = Bitmap(size)
+        for i in range(size):
+            b.set(i)
+        assert b.popcount() == size
+
+    @pytest.mark.parametrize("size", [9, 10, 12])
+    def test_clz_clo_consistent_with_test(self, size):
+        b = Bitmap(size)
+        b.set(size - 1)  # only last bit set
+        assert b.count_leading_zeros() == size - 1
+        assert b.count_leading_ones() == 0
+
+        b2 = Bitmap(size)
+        for i in range(size - 1):
+            b2.set(i)
+        assert b2.count_leading_ones() == size - 1
+        assert b2.count_leading_zeros() == 0
+
+
+class TestBatchedSet:
+    """Bitmap.batched_set(indices): set every listed bit; positions >= size
+    are ignored (bounds-checked, like set())."""
+
+    def test_sets_listed_bits(self):
+        b = Bitmap(8)
+        b.batched_set([1, 3, 7])
+        assert b.get_indices_set() == {1, 3, 7}
+
+    def test_accumulates_with_existing(self):
+        b = Bitmap(8)
+        b.set(0)
+        b.batched_set([2, 4])
+        assert b.get_indices_set() == {0, 2, 4}
+
+    def test_out_of_range_ignored(self):
+        b = Bitmap(5)
+        b.batched_set([1, 5, 99])  # 5 and 99 are >= size -> dropped
+        assert b.get_indices_set() == {1}
+
+    def test_empty_is_noop(self):
+        b = Bitmap(4)
+        b.set(2)
+        b.batched_set([])
+        assert b.get_indices_set() == {2}
+
+    def test_duplicates_idempotent(self):
+        b = Bitmap(4)
+        b.batched_set([1, 1, 1])
+        assert b.get_indices_set() == {1}
+
+    def test_accepts_tuple(self):
+        b = Bitmap(4)
+        b.batched_set((0, 3))
+        assert b.get_indices_set() == {0, 3}
+
+    def test_matches_python_reference(self):
+        rng = random.Random(1234)
+        for _ in range(50):
+            size = rng.randint(1, 64)
+            indices = rng.sample(range(size), k=rng.randint(0, size))
+            b = Bitmap(size)
+            b.batched_set(indices)
+            assert b.get_indices_set() == set(indices)
+
+    def test_combine_found_pattern(self):
+        # The _combine_found composition: seed L1 indices, then batched_set the
+        # L2 set bits gathered through their original-position map.
+        l2 = Bitmap(3)  # L2 result over the 3 L2-submitted keys
+        l2.set(0)
+        l2.set(2)
+        l2_orig = (3, 5, 7)  # L2-local i -> original position
+        found = Bitmap(10)
+        found.batched_set([0, 1, 2])  # L1 prefix
+        found.batched_set(l2.gather(l2_orig))  # -> {3, 7}
+        assert found.get_indices_set() == {0, 1, 2, 3, 7}
diff --git a/tests/v1/native_storage_ops/test_pattern_matcher.py b/tests/v1/native_storage_ops/test_pattern_matcher.py
new file mode 100644
index 0000000..d7ced17
--- /dev/null
+++ b/tests/v1/native_storage_ops/test_pattern_matcher.py
@@ -0,0 +1,701 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+import threading
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip(
+    "lmcache.native_storage_ops",
+    reason="native_storage_ops extension not built",
+)
+
+# First Party
+from lmcache.native_storage_ops import ParallelPatternMatcher, RangePatternMatcher
+
+
+def assert_torch():
+    """Test that torch is available and can be imported."""
+    assert torch.__version__ is not None, "Torch should be available"
+
+
+class TestParallelPatternMatcherBasic:
+    """Test basic functionality of ParallelPatternMatcher."""
+
+    def test_example_from_spec(self):
+        """Test the exact example from the specification."""
+        pattern = [1, 2, 3]
+        data = [1, 1, 1, 1, 2, 3, 3, 3, 1, 2, 3, 3, 3]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [3, 8], f"Expected [3, 8] but got {result}"
+
+    def test_no_matches(self):
+        """Test when pattern is not found in data."""
+        pattern = [5, 6, 7]
+        data = [1, 2, 3, 4, 1, 2, 3, 4]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_single_match(self):
+        """Test when pattern appears once."""
+        pattern = [7, 8, 9]
+        data = [1, 2, 3, 7, 8, 9, 10, 11]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [3]
+
+    def test_pattern_at_start(self):
+        """Test when pattern is at the beginning of data."""
+        pattern = [1, 2, 3]
+        data = [1, 2, 3, 4, 5, 6]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [0]
+
+    def test_pattern_at_end(self):
+        """Test when pattern is at the end of data."""
+        pattern = [4, 5, 6]
+        data = [1, 2, 3, 4, 5, 6]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [3]
+
+    def test_multiple_matches(self):
+        """Test when pattern appears multiple times."""
+        pattern = [1, 2]
+        data = [1, 2, 3, 1, 2, 4, 1, 2, 5]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [0, 3, 6]
+
+    def test_overlapping_patterns(self):
+        """Test when patterns overlap."""
+        pattern = [1, 1]
+        data = [1, 1, 1, 1, 2]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        # Overlapping patterns at positions 0, 1, 2
+        assert result == [0, 1, 2]
+
+    def test_single_element_pattern(self):
+        """Test with a single-element pattern."""
+        pattern = [5]
+        data = [1, 2, 5, 3, 5, 4, 5]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [2, 4, 6]
+
+    def test_pattern_equals_data(self):
+        """Test when pattern is exactly the same as data."""
+        pattern = [1, 2, 3, 4, 5]
+        data = [1, 2, 3, 4, 5]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [0]
+
+    def test_pattern_longer_than_data(self):
+        """Test when pattern is longer than data."""
+        pattern = [1, 2, 3, 4, 5]
+        data = [1, 2, 3]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_empty_data(self):
+        """Test with empty data."""
+        pattern = [1, 2, 3]
+        data = []
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_large_pattern(self):
+        """Test with a large pattern."""
+        pattern = list(range(10))
+        data = [0] + list(range(10)) + [99] + list(range(10)) + [88]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [1, 12]
+
+
+class TestParallelPatternMatcherConsistency:
+    """Test consistency of pattern matching."""
+
+    def test_repeated_matches_consistent(self):
+        """Test that repeated calls produce consistent results."""
+        pattern = [1, 2, 3]
+        data = [1, 1, 1, 1, 2, 3, 3, 3, 1, 2, 3, 3, 3]
+
+        matcher = ParallelPatternMatcher(pattern)
+
+        # Call match multiple times
+        results = [matcher.match(data) for _ in range(5)]
+
+        # All results should be the same
+        for result in results:
+            assert result == [3, 8]
+
+    def test_multiple_matchers_same_result(self):
+        """Test that multiple matcher instances produce the same result."""
+        pattern = [5, 6, 7]
+        data = list(range(100)) + [5, 6, 7] + list(range(50)) + [5, 6, 7]
+
+        results = []
+        for _ in range(5):
+            matcher = ParallelPatternMatcher(pattern)
+            result = matcher.match(data)
+            results.append(result)
+
+        # All results should be the same
+        for i in range(1, len(results)):
+            assert results[i] == results[0], (
+                f"Results differ: {results[0]} vs {results[i]}"
+            )
+
+
+class TestParallelPatternMatcherEdgeCases:
+    """Test edge cases and boundary conditions."""
+
+    def test_negative_numbers(self):
+        """Test with negative numbers in pattern and data."""
+        pattern = [-1, -2, -3]
+        data = [1, 2, -1, -2, -3, 4, 5]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [2]
+
+    def test_mixed_positive_negative(self):
+        """Test with mixed positive and negative numbers."""
+        pattern = [1, -1, 2]
+        data = [0, 1, -1, 2, 3, 1, -1, 2, 4]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [1, 5]
+
+    def test_zeros_in_pattern(self):
+        """Test with zeros in the pattern."""
+        pattern = [0, 0, 0]
+        data = [1, 2, 0, 0, 0, 3, 0, 0, 0]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [2, 6]
+
+    def test_large_numbers(self):
+        """Test with large numbers."""
+        pattern = [1000000, 2000000, 3000000]
+        data = [1, 1000000, 2000000, 3000000, 2, 1000000, 2000000, 3000000]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [1, 5]
+
+    def test_repeating_pattern_in_repeating_data(self):
+        """Test repeating pattern in repeating data."""
+        pattern = [1, 2]
+        data = [1, 2, 1, 2, 1, 2, 1, 2]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [0, 2, 4, 6]
+
+    def test_pattern_at_every_position(self):
+        """Test when pattern could match at multiple overlapping positions."""
+        pattern = [1, 1, 1]
+        data = [1, 1, 1, 1, 1]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        # Pattern matches at positions 0, 1, 2
+        assert result == [0, 1, 2]
+
+
+class TestParallelPatternMatcherThreadSafety:
+    """Test thread safety when using the same matcher from multiple threads."""
+
+    def test_concurrent_matches(self):
+        """Test that multiple threads can call match() concurrently."""
+        pattern = [1, 2, 3]
+        data = [1, 1, 1, 1, 2, 3, 3, 3, 1, 2, 3, 3, 3]
+
+        matcher = ParallelPatternMatcher(pattern)
+
+        def do_match():
+            result = matcher.match(data)
+            assert result == [3, 8]
+
+        num_threads = 10
+        threads = []
+        for _ in range(num_threads):
+            t = threading.Thread(target=do_match)
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+    def test_concurrent_different_data(self):
+        """Test concurrent matches with different data."""
+        pattern = [5, 6, 7]
+        matcher = ParallelPatternMatcher(pattern)
+
+        data_sets = [
+            ([5, 6, 7, 1, 2, 3], [0]),
+            ([1, 2, 5, 6, 7, 8], [2]),
+            ([1, 2, 3, 4, 5, 6], []),
+            ([5, 6, 7, 5, 6, 7], [0, 3]),
+        ]
+
+        results = [None] * len(data_sets)
+
+        def do_match(idx, data, expected):
+            result = matcher.match(data)
+            assert result == expected, f"Expected {expected} but got {result}"
+            results[idx] = result
+
+        threads = []
+        for idx, (data, expected) in enumerate(data_sets):
+            t = threading.Thread(target=do_match, args=(idx, data, expected))
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Verify all results
+        for idx, (_, expected) in enumerate(data_sets):
+            assert results[idx] == expected
+
+
+class TestParallelPatternMatcherPerformance:
+    """Test performance characteristics."""
+
+    def test_large_data(self):
+        """Test with large data."""
+        pattern = [42, 43, 42]
+        data = list(range(10000)) + [42, 43, 42] + list(range(5000))
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == [10000]
+
+    def test_many_matches_in_large_data(self):
+        """Test with many pattern occurrences in large data."""
+        pattern = [1, 2, 3]
+        # Create data with pattern appearing every 10 elements
+        data = []
+        for i in range(1000):
+            if i % 10 == 0:
+                data.extend([1, 2, 3])
+            else:
+                data.extend([4, 5, 6])
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        # Verify we found all occurrences
+        for idx in result:
+            assert data[idx : idx + 3] == [1, 2, 3], f"Invalid match at position {idx}"
+
+        # Should have ~100 matches
+        assert len(result) > 90
+
+    def test_stress_test_parallel_execution(self):
+        """Stress test with multiple matchers running in parallel."""
+        pattern = [7, 8, 9]
+        data = list(range(1000)) + [7, 8, 9] + list(range(500))
+
+        def worker():
+            matcher = ParallelPatternMatcher(pattern)
+            result = matcher.match(data)
+            assert 1000 in result
+
+        with ThreadPoolExecutor(max_workers=20) as executor:
+            futures = [executor.submit(worker) for _ in range(100)]
+            for f in futures:
+                f.result()  # Will raise if any thread failed
+
+
+class TestParallelPatternMatcherResultSorted:
+    """Test that results are always sorted."""
+
+    def test_results_are_sorted(self):
+        """Test that matches are returned in sorted order."""
+        pattern = [1, 2]
+        # Create data where pattern appears in various positions
+        data = [0, 1, 2, 0, 1, 2, 0, 0, 1, 2, 0]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        # Verify sorted
+        assert result == sorted(result)
+
+        # Verify correctness
+        assert result == [1, 4, 8]
+
+    def test_results_sorted_multiple_matches(self):
+        """Test that results are sorted with multiple matches."""
+        pattern = [5]
+        data = [5, 0, 5, 0, 5, 0, 5, 0, 5, 0, 5]
+
+        matcher = ParallelPatternMatcher(pattern)
+        result = matcher.match(data)
+
+        assert result == sorted(result)
+        assert result == [0, 2, 4, 6, 8, 10]
+
+
+class TestRangePatternMatcherBasic:
+    """Test basic functionality of RangePatternMatcher."""
+
+    def test_example_from_spec(self):
+        """Test the exact example from the specification."""
+        start = [1, 2]
+        end = [3, 4]
+        data = [1, 2, 0, 3, 4, 0, 3, 4, 1, 2, 0, 0, 3, 4]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 5), (8, 14)], (
+            f"Expected [(0, 5), (8, 14)] but got {result}"
+        )
+
+    def test_single_range(self):
+        """Test when there's a single range in the data."""
+        start = [1, 2]
+        end = [5, 6]
+        data = [0, 1, 2, 3, 4, 5, 6, 7, 8]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(1, 7)]
+
+    def test_no_matches(self):
+        """Test when no start pattern is found."""
+        start = [10, 11]
+        end = [20, 21]
+        data = [1, 2, 3, 4, 5, 6, 7, 8]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_start_without_end(self):
+        """Test when start pattern is found but no end pattern follows."""
+        start = [1, 2]
+        end = [9, 10]
+        data = [1, 2, 3, 4, 5, 6, 7, 8]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_end_without_start(self):
+        """Test when end pattern exists but no start pattern before it."""
+        start = [1, 2]
+        end = [7, 8]
+        data = [0, 3, 4, 5, 6, 7, 8, 9]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_multiple_ranges(self):
+        """Test multiple ranges in the data."""
+        start = [1]
+        end = [2]
+        data = [1, 0, 2, 1, 0, 0, 2, 1, 2]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 3), (3, 7), (7, 9)]
+
+    def test_minimal_range_selection(self):
+        """Test that the first end pattern is selected (minimal range)."""
+        start = [1]
+        end = [2]
+        data = [1, 0, 2, 0, 2, 0, 2]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        # Should match to the first occurrence of end pattern at position 2
+        assert result == [(0, 3)]
+
+    def test_adjacent_start_end(self):
+        """Test when start and end patterns are adjacent."""
+        start = [1, 2]
+        end = [3, 4]
+        data = [0, 1, 2, 3, 4, 5]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(1, 5)]
+
+    def test_start_equals_data(self):
+        """Test when start pattern equals all the data."""
+        start = [1, 2, 3, 4]
+        end = [5, 6]
+        data = [1, 2, 3, 4]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_single_element_patterns(self):
+        """Test with single-element patterns."""
+        start = [1]
+        end = [5]
+        data = [1, 2, 3, 4, 5, 6, 1, 2, 5]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 5), (6, 9)]
+
+
+class TestRangePatternMatcherEdgeCases:
+    """Test edge cases and boundary conditions for RangePatternMatcher."""
+
+    def test_empty_data(self):
+        """Test with empty data."""
+        start = [1, 2]
+        end = [3, 4]
+        data = []
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_data_too_short(self):
+        """Test when data is shorter than start + end patterns."""
+        start = [1, 2, 3]
+        end = [7, 8, 9]
+        data = [1, 2]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_pattern_at_boundaries(self):
+        """Test patterns at the start and end of data."""
+        start = [1]
+        end = [9]
+        data = [1, 2, 3, 4, 9]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 5)]
+
+    def test_negative_numbers(self):
+        """Test with negative numbers."""
+        start = [-1, -2]
+        end = [-5, -6]
+        data = [0, -1, -2, -3, -4, -5, -6, 10]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(1, 7)]
+
+    def test_zeros_in_patterns(self):
+        """Test with zeros in patterns."""
+        start = [0, 0]
+        end = [1, 1]
+        data = [0, 0, 5, 5, 1, 1, 0, 0, 1, 1]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 6), (6, 10)]
+
+    def test_large_numbers(self):
+        """Test with large numbers."""
+        start = [1000000]
+        end = [2000000]
+        data = [1000000, 999, 2000000, 1000000, 2000000]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 3), (3, 5)]
+
+
+class TestRangePatternMatcherConsistency:
+    """Test consistency of range pattern matching."""
+
+    def test_repeated_matches_consistent(self):
+        """Test that repeated calls produce consistent results."""
+        start = [1, 2]
+        end = [3, 4]
+        data = [1, 2, 0, 3, 4, 0, 3, 4, 1, 2, 0, 0, 3, 4]
+
+        matcher = RangePatternMatcher(start, end)
+
+        # Call match multiple times
+        results = [matcher.match(data) for _ in range(5)]
+
+        # All results should be the same
+        for result in results:
+            assert result == [(0, 5), (8, 14)]
+
+    def test_multiple_matchers_same_result(self):
+        """Test that multiple matcher instances produce the same result."""
+        start = [5, 6]
+        end = [7, 8]
+        data = [5, 6, 0, 7, 8, 1, 5, 6, 7, 8]
+
+        results = []
+        for _ in range(5):
+            matcher = RangePatternMatcher(start, end)
+            result = matcher.match(data)
+            results.append(result)
+
+        # All results should be the same
+        for i in range(1, len(results)):
+            assert results[i] == results[0], (
+                f"Results differ: {results[0]} vs {results[i]}"
+            )
+
+
+class TestRangePatternMatcherComplexScenarios:
+    """Test complex scenarios for RangePatternMatcher."""
+
+    def test_nested_like_patterns(self):
+        """Test when a new start pattern appears before the first end."""
+        start = [1]
+        end = [9]
+        data = [1, 2, 1, 3, 9, 5, 9]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        # First start at 0, first end at 4 -> (0, 5)
+        # Second start at 2 is "inside" the first range, but we already consumed it
+        # Continue from 5, no more start patterns
+        # Wait, after finding (0, 5), we continue from position 5
+        # At position 5, data[5] = 5, not a start
+        # At position 6, data[6] = 9, not a start
+        # No more ranges
+        # But wait, what about the start at position 2?
+        # The algorithm processes left to right, so:
+        # - Find start at 0, find end at 4, add (0, 5), continue from 5
+        # - Check position 5, 6: no starts found
+        # So result is [(0, 5)]
+        # Actually, I need to reconsider. Let me trace through the algorithm:
+        # i=0: start matches, search from 1, end at 4, add (0,5), i=5
+        # i=5: data[5]=5, no match, i=6
+        # i=6: data[6]=9, no match, i=7
+        # i=7: out of bounds
+        # Result: [(0, 5)]
+        assert result == [(0, 5)]
+
+    def test_multiple_ends_after_start(self):
+        """Test multiple end patterns after a start (should pick first)."""
+        start = [1, 2]
+        end = [5]
+        data = [1, 2, 3, 5, 4, 5, 6, 5, 7]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        # Start at 0, first end at 3, range (0, 4)
+        assert result == [(0, 4)]
+
+    def test_consecutive_ranges(self):
+        """Test consecutive non-overlapping ranges."""
+        start = [1]
+        end = [2]
+        data = [1, 2, 1, 2, 1, 2]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 2), (2, 4), (4, 6)]
+
+    def test_long_data_with_sparse_patterns(self):
+        """Test long data with patterns far apart."""
+        start = [100]
+        end = [200]
+        data = [0] * 50 + [100] + [1] * 50 + [200] + [0] * 50 + [100] + [2] * 30 + [200]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(50, 102), (152, 184)]
+
+    def test_pattern_longer_than_data(self):
+        """Test when patterns are longer than data."""
+        start = [1, 2, 3, 4, 5]
+        end = [6, 7]
+        data = [1, 2, 3]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == []
+
+    def test_alternating_start_end(self):
+        """Test alternating start and end patterns."""
+        start = [1]
+        end = [2]
+        data = [1, 2, 1, 2, 1, 2, 1, 2]
+
+        matcher = RangePatternMatcher(start, end)
+        result = matcher.match(data)
+
+        assert result == [(0, 2), (2, 4), (4, 6), (6, 8)]
diff --git a/tests/v1/native_storage_ops/test_periodic_event_notifier.py b/tests/v1/native_storage_ops/test_periodic_event_notifier.py
new file mode 100644
index 0000000..bae0386
--- /dev/null
+++ b/tests/v1/native_storage_ops/test_periodic_event_notifier.py
@@ -0,0 +1,231 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+import os
+import select
+import time
+
+# Third Party
+import pytest
+
+pytest.importorskip(
+    "lmcache.native_storage_ops",
+    reason="native_storage_ops extension not built",
+)
+
+# First Party
+from lmcache.native_storage_ops import PeriodicEventNotifier
+from lmcache.v1.platform import HAS_EVENTFD
+
+
+@pytest.fixture(autouse=True)
+def cleanup():
+    yield
+    PeriodicEventNotifier.shutdown()
+
+
+def _make_notifier_fd():
+    """Create a test fd suitable for the periodic notifier to write to.
+
+    Returns (poll_fd, write_fd, close_func) where poll_fd is for
+    select.poll() and write_fd is what gets registered with the notifier.
+    For eventfd they are the same; for pipes they differ.
+    """
+    if HAS_EVENTFD:
+        fd = os.eventfd(0, os.EFD_NONBLOCK | os.EFD_CLOEXEC)
+        return fd, fd, lambda: os.close(fd)
+    else:
+        r, w = os.pipe()
+        os.set_blocking(r, False)
+        os.set_blocking(w, False)
+
+        def close_both():
+            os.close(r)
+            os.close(w)
+
+        return r, w, close_both
+
+
+def _consume_fd(fd):
+    if HAS_EVENTFD:
+        try:
+            os.eventfd_read(fd)
+        except BlockingIOError:
+            pass
+    else:
+        while True:
+            try:
+                if not os.read(fd, 4096):
+                    return
+            except BlockingIOError:
+                return
+
+
+def _poll_fd(fd, timeout_ms=500):
+    poller = select.poll()
+    poller.register(fd, select.POLLIN)
+    return bool(poller.poll(timeout_ms))
+
+
+class TestLifecycle:
+    def test_get_before_create_returns_none(self):
+        assert PeriodicEventNotifier.get() is None
+
+    def test_create_and_get(self):
+        PeriodicEventNotifier.create(interval_ms=50, use_eventfd=HAS_EVENTFD)
+        assert PeriodicEventNotifier.get() is not None
+
+    def test_shutdown_clears_instance(self):
+        PeriodicEventNotifier.create(interval_ms=50, use_eventfd=HAS_EVENTFD)
+        PeriodicEventNotifier.shutdown()
+        assert PeriodicEventNotifier.get() is None
+
+    def test_double_create_idempotent(self):
+        PeriodicEventNotifier.create(interval_ms=50, use_eventfd=HAS_EVENTFD)
+        PeriodicEventNotifier.create(interval_ms=100, use_eventfd=HAS_EVENTFD)
+        assert PeriodicEventNotifier.get() is not None
+
+    def test_double_shutdown_idempotent(self):
+        PeriodicEventNotifier.create(interval_ms=50, use_eventfd=HAS_EVENTFD)
+        PeriodicEventNotifier.shutdown()
+        PeriodicEventNotifier.shutdown()
+
+    def test_shutdown_before_create(self):
+        PeriodicEventNotifier.shutdown()
+
+
+class TestSignaling:
+    def test_register_fd_triggers_signals(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        poll_fd, write_fd, close_fn = _make_notifier_fd()
+        try:
+            notifier = PeriodicEventNotifier.get()
+            notifier.register_fd(write_fd)
+            assert _poll_fd(poll_fd, timeout_ms=1000)
+            _consume_fd(poll_fd)
+        finally:
+            notifier.unregister_fd(write_fd)
+            close_fn()
+
+    def test_multiple_fds_all_signaled(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        fds = [_make_notifier_fd() for _ in range(3)]
+        try:
+            notifier = PeriodicEventNotifier.get()
+            for _, write_fd, _ in fds:
+                notifier.register_fd(write_fd)
+            time.sleep(0.05)
+            for poll_fd, _, _ in fds:
+                assert _poll_fd(poll_fd, timeout_ms=500)
+                _consume_fd(poll_fd)
+        finally:
+            for _, write_fd, close_fn in fds:
+                notifier.unregister_fd(write_fd)
+                close_fn()
+
+    def test_unregister_stops_signals(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        poll_fd, write_fd, close_fn = _make_notifier_fd()
+        try:
+            notifier = PeriodicEventNotifier.get()
+            notifier.register_fd(write_fd)
+            assert _poll_fd(poll_fd, timeout_ms=1000)
+            _consume_fd(poll_fd)
+
+            notifier.unregister_fd(write_fd)
+            time.sleep(0.05)
+            _consume_fd(poll_fd)
+            assert not _poll_fd(poll_fd, timeout_ms=100)
+        finally:
+            close_fn()
+
+
+class TestDormancy:
+    def test_dormancy_and_wake(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        poll_fd, write_fd, close_fn = _make_notifier_fd()
+        try:
+            notifier = PeriodicEventNotifier.get()
+
+            notifier.register_fd(write_fd)
+            assert _poll_fd(poll_fd, timeout_ms=1000)
+            _consume_fd(poll_fd)
+
+            notifier.unregister_fd(write_fd)
+            time.sleep(0.05)
+            _consume_fd(poll_fd)
+            assert not _poll_fd(poll_fd, timeout_ms=100)
+
+            notifier.register_fd(write_fd)
+            assert _poll_fd(poll_fd, timeout_ms=1000)
+            _consume_fd(poll_fd)
+        finally:
+            notifier.unregister_fd(write_fd)
+            close_fn()
+
+
+class TestInterval:
+    def test_set_interval_ms(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        poll_fd, write_fd, close_fn = _make_notifier_fd()
+        try:
+            notifier = PeriodicEventNotifier.get()
+            notifier.register_fd(write_fd)
+
+            # Drain initial burst and wait for steady state.
+            time.sleep(0.05)
+            _consume_fd(poll_fd)
+
+            # Count signals at 10ms interval over 200ms → expect ~20.
+            count_fast = 0
+            deadline = time.monotonic() + 0.2
+            while time.monotonic() < deadline:
+                if _poll_fd(poll_fd, timeout_ms=50):
+                    _consume_fd(poll_fd)
+                    count_fast += 1
+
+            notifier.set_interval_ms(200)
+            time.sleep(0.25)
+            _consume_fd(poll_fd)
+
+            # Count signals at 200ms interval over 1s → expect ~5.
+            count_slow = 0
+            deadline = time.monotonic() + 1.0
+            while time.monotonic() < deadline:
+                if _poll_fd(poll_fd, timeout_ms=250):
+                    _consume_fd(poll_fd)
+                    count_slow += 1
+
+            assert count_fast > count_slow
+        finally:
+            notifier.unregister_fd(write_fd)
+            close_fn()
+
+
+class TestEdgeCases:
+    def test_register_same_fd_twice(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        poll_fd, write_fd, close_fn = _make_notifier_fd()
+        try:
+            notifier = PeriodicEventNotifier.get()
+            notifier.register_fd(write_fd)
+            notifier.register_fd(write_fd)
+            assert _poll_fd(poll_fd, timeout_ms=1000)
+            _consume_fd(poll_fd)
+        finally:
+            notifier.unregister_fd(write_fd)
+            close_fn()
+
+    def test_unregister_nonexistent_fd(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        notifier = PeriodicEventNotifier.get()
+        notifier.unregister_fd(999)
+
+    def test_closed_fd_does_not_crash(self):
+        PeriodicEventNotifier.create(interval_ms=10, use_eventfd=HAS_EVENTFD)
+        poll_fd, write_fd, close_fn = _make_notifier_fd()
+        notifier = PeriodicEventNotifier.get()
+        notifier.register_fd(write_fd)
+        close_fn()
+        time.sleep(0.05)
+        notifier.unregister_fd(write_fd)
diff --git a/tests/v1/native_storage_ops/test_ttl_lock.py b/tests/v1/native_storage_ops/test_ttl_lock.py
new file mode 100644
index 0000000..9c9ccc9
--- /dev/null
+++ b/tests/v1/native_storage_ops/test_ttl_lock.py
@@ -0,0 +1,464 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from concurrent.futures import ThreadPoolExecutor
+import threading
+import time
+
+# Third Party
+import pytest
+
+pytest.importorskip(
+    "lmcache.native_storage_ops",
+    reason="native_storage_ops extension not built",
+)
+
+# First Party
+from lmcache.native_storage_ops import TTLLock
+
+
+class TestTTLLockBasicSemantics:
+    """Test basic semantics of TTLLock operations."""
+
+    def test_initial_state(self):
+        """Test that a new lock starts in unlocked state."""
+        lock = TTLLock()
+        assert not lock.is_locked()
+
+    def test_lock_increments_counter(self):
+        """Test that lock() increments the counter."""
+        lock = TTLLock()
+
+        lock.lock()
+        assert lock.is_locked()
+
+        lock.lock()
+        assert lock.is_locked()
+
+        lock.lock()
+        assert lock.is_locked()
+
+    def test_unlock_decrements_counter(self):
+        """Test that unlock() decrements the counter."""
+        lock = TTLLock()
+
+        # Lock 3 times
+        lock.lock()
+        lock.lock()
+        lock.lock()
+
+        lock.unlock()
+        assert lock.is_locked()
+
+        lock.unlock()
+        assert lock.is_locked()
+
+        lock.unlock()
+        assert not lock.is_locked()
+
+    def test_unlock_does_not_go_below_zero(self):
+        """Test that unlock() never goes below 0."""
+        lock = TTLLock()
+
+        # Unlock without any locks - should not crash
+        lock.unlock()
+        assert not lock.is_locked()
+
+        # Multiple unlocks should still be safe
+        lock.unlock()
+        lock.unlock()
+        assert not lock.is_locked()
+
+    def test_unlock_after_partial_locks(self):
+        """Test unlock when counter is already at minimum."""
+        lock = TTLLock()
+
+        lock.lock()
+        lock.lock()
+        lock.unlock()
+        lock.unlock()
+
+        # Extra unlocks should be safe
+        lock.unlock()
+        lock.unlock()
+        assert not lock.is_locked()
+
+    def test_reset(self):
+        """Test that reset() clears the lock state."""
+        lock = TTLLock()
+
+        lock.lock()
+        lock.lock()
+        lock.lock()
+        assert lock.is_locked()
+
+        lock.reset()
+        assert not lock.is_locked()
+
+    def test_lock_after_reset(self):
+        """Test that lock works correctly after reset."""
+        lock = TTLLock()
+
+        lock.lock()
+        lock.lock()
+        lock.reset()
+
+        lock.lock()
+        assert lock.is_locked()
+
+
+class TestTTLLockTTLSemantics:
+    """Test TTL (Time-To-Live) semantics of TTLLock."""
+
+    def test_lock_expires_after_ttl(self):
+        """Test that lock expires after TTL duration."""
+        # Create a lock with 1 second TTL
+        lock = TTLLock(ttl_second=1)
+
+        lock.lock()
+        assert lock.is_locked()
+
+        # Wait for TTL to expire
+        time.sleep(1.5)  # 1.5s > 1s TTL
+
+        assert not lock.is_locked()
+
+    def test_lock_refreshes_ttl(self):
+        """Test that each lock() call refreshes the TTL."""
+        lock = TTLLock(ttl_second=2)
+
+        lock.lock()
+
+        # Wait 1.5s (less than TTL)
+        time.sleep(0.5)
+        assert lock.is_locked()
+
+        # Lock again to refresh TTL
+        lock.lock()
+
+        # Wait another 1.5s - total 3s from first lock,
+        # but only 1.5s from second lock
+        time.sleep(1.5)
+        assert lock.is_locked()
+
+        # Wait for TTL to expire from the last lock
+        time.sleep(1.0)  # Now 2.5s from last lock > 2s TTL
+        assert not lock.is_locked()
+
+    def test_lock_after_ttl_expired_resets_counter(self):
+        """Test that lock() after TTL expires resets counter to 1."""
+        lock = TTLLock(ttl_second=1)
+
+        # Lock multiple times
+        lock.lock()
+        lock.lock()
+        lock.lock()
+
+        # Wait for TTL to expire
+        time.sleep(1.5)
+        assert not lock.is_locked()
+
+        # Lock again - should reset counter and be locked
+        lock.lock()
+        assert lock.is_locked()
+
+        # Verify counter was reset by unlocking once
+        lock.unlock()
+        assert not lock.is_locked()
+
+    def test_default_ttl_is_300_seconds(self):
+        """Test that default TTL is 300 seconds."""
+        lock = TTLLock()
+
+        lock.lock()
+        assert lock.is_locked()
+
+        # After a short time, should still be locked
+        time.sleep(0.1)
+        assert lock.is_locked()
+
+    def test_custom_ttl(self):
+        """Test custom TTL values."""
+        lock = TTLLock(ttl_second=1)
+
+        lock.lock()
+        assert lock.is_locked()
+
+        time.sleep(0.5)  # 0.5s < 1s
+        assert lock.is_locked()
+
+        time.sleep(0.7)  # Total 1.2s > 1s
+        assert not lock.is_locked()
+
+
+class TestTTLLockThreadSafety:
+    """Test thread safety of TTLLock operations."""
+
+    def test_concurrent_locks(self):
+        """Test that concurrent lock() operations are thread-safe."""
+        lock = TTLLock()
+        num_threads = 100
+        locks_per_thread = 100
+
+        def do_locks():
+            for _ in range(locks_per_thread):
+                lock.lock()
+
+        threads = []
+        for _ in range(num_threads):
+            t = threading.Thread(target=do_locks)
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Final counter should be num_threads * locks_per_thread
+        # We verify by unlocking and counting
+        count = 0
+        while lock.is_locked():
+            lock.unlock()
+            count += 1
+
+        assert count == num_threads * locks_per_thread
+
+    def test_concurrent_unlocks(self):
+        """Test that concurrent unlock() operations are thread-safe."""
+        lock = TTLLock()
+        total_locks = 10000
+
+        # Lock many times first
+        for _ in range(total_locks):
+            lock.lock()
+
+        num_threads = 100
+        unlocks_per_thread = total_locks // num_threads
+
+        def do_unlocks():
+            for _ in range(unlocks_per_thread):
+                lock.unlock()
+
+        threads = []
+        for _ in range(num_threads):
+            t = threading.Thread(target=do_unlocks)
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Should be at 0
+        assert not lock.is_locked()
+
+    def test_concurrent_lock_unlock(self):
+        """Test concurrent mixed lock/unlock operations."""
+        lock = TTLLock()
+        num_threads = 50
+        ops_per_thread = 100
+        lock_count = [0]
+        unlock_count = [0]
+        lock_mutex = threading.Lock()
+
+        def do_mixed_ops(thread_id):
+            lock.lock()  # Must do a lock first to avoid double unlock
+            with lock_mutex:
+                lock_count[0] += 1
+            for i in range(ops_per_thread):
+                if (thread_id + i) % 2 == 0:
+                    lock.lock()
+                    with lock_mutex:
+                        lock_count[0] += 1
+                else:
+                    lock.unlock()
+                    with lock_mutex:
+                        unlock_count[0] += 1
+
+        threads = []
+        for i in range(num_threads):
+            t = threading.Thread(target=do_mixed_ops, args=(i,))
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # The lock counter should never go negative
+        # We can verify the final state is consistent
+        expected_remaining = max(0, lock_count[0] - unlock_count[0])
+
+        # Count remaining locks
+        remaining = 0
+        while lock.is_locked():
+            lock.unlock()
+            remaining += 1
+
+        assert remaining == expected_remaining
+
+    def test_concurrent_is_locked_reads(self):
+        """Test that is_locked() is safe to call concurrently with modifications."""
+        lock = TTLLock()
+        stop_flag = threading.Event()
+        errors = []
+
+        def reader():
+            try:
+                while not stop_flag.is_set():
+                    # Just read - should never crash
+                    _ = lock.is_locked()
+            except Exception as e:
+                errors.append(e)
+
+        def writer():
+            try:
+                for _ in range(1000):
+                    lock.lock()
+                    lock.unlock()
+            except Exception as e:
+                errors.append(e)
+
+        # Start multiple readers
+        readers = [threading.Thread(target=reader) for _ in range(10)]
+        # Start multiple writers
+        writers = [threading.Thread(target=writer) for _ in range(10)]
+
+        for t in readers + writers:
+            t.start()
+
+        # Wait for writers to finish
+        for t in writers:
+            t.join()
+
+        # Signal readers to stop
+        stop_flag.set()
+
+        for t in readers:
+            t.join()
+
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+
+    def test_stress_test_high_contention(self):
+        """Stress test with high contention from many threads."""
+        lock = TTLLock()
+        num_threads = 200
+        ops_per_thread = 500
+
+        def stress_worker():
+            for _ in range(ops_per_thread):
+                lock.lock()
+                # Small work
+                _ = lock.is_locked()
+                lock.unlock()
+
+        with ThreadPoolExecutor(max_workers=num_threads) as executor:
+            futures = [executor.submit(stress_worker) for _ in range(num_threads)]
+            for f in futures:
+                f.result()  # Will raise if any thread failed
+
+        # After all operations, lock should be released
+        assert not lock.is_locked()
+
+    def test_concurrent_reset(self):
+        """Test that reset() is safe to call concurrently."""
+        lock = TTLLock()
+        num_threads = 50
+        ops_per_thread = 100
+        errors = []
+
+        def worker():
+            try:
+                for i in range(ops_per_thread):
+                    if i % 3 == 0:
+                        lock.lock()
+                    elif i % 3 == 1:
+                        lock.unlock()
+                    else:
+                        lock.reset()
+            except Exception as e:
+                errors.append(e)
+
+        threads = [threading.Thread(target=worker) for _ in range(num_threads)]
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+
+
+class TestTTLLockEdgeCases:
+    """Test edge cases and boundary conditions."""
+
+    def test_very_short_ttl(self):
+        """Test with very short TTL (1 second)."""
+        lock = TTLLock(ttl_second=1)
+
+        lock.lock()
+        assert lock.is_locked()
+
+        time.sleep(1.5)  # 1.5s > 1s
+        assert not lock.is_locked()
+
+    def test_multiple_locks_same_ttl_window(self):
+        """Test multiple locks within the same TTL window."""
+        lock = TTLLock(ttl_second=10)
+
+        # Lock many times quickly
+        for _ in range(100):
+            lock.lock()
+
+        assert lock.is_locked()
+
+        # Unlock 100 times
+        for _ in range(100):
+            lock.unlock()
+
+        assert not lock.is_locked()
+
+    def test_unlock_without_lock(self):
+        """Test unlocking a never-locked lock."""
+        lock = TTLLock()
+
+        lock.unlock()  # Should not crash
+        assert not lock.is_locked()
+
+    def test_lock_unlock_lock_pattern(self):
+        """Test lock-unlock-lock pattern."""
+        lock = TTLLock()
+
+        lock.lock()
+        assert lock.is_locked()
+
+        lock.unlock()
+        assert not lock.is_locked()
+
+        lock.lock()
+        assert lock.is_locked()
+
+    def test_multiple_independent_locks(self):
+        """Test that multiple lock instances are independent."""
+        lock1 = TTLLock()
+        lock2 = TTLLock()
+
+        lock1.lock()
+        lock1.lock()
+
+        assert lock1.is_locked()
+        assert not lock2.is_locked()
+
+        lock2.lock()
+
+        assert lock1.is_locked()
+        assert lock2.is_locked()
+
+        lock1.reset()
+
+        assert not lock1.is_locked()
+        assert lock2.is_locked()
diff --git a/tests/v1/platform/__init__.py b/tests/v1/platform/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/platform/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/platform/test_cache_context_dispatch.py b/tests/v1/platform/test_cache_context_dispatch.py
new file mode 100644
index 0000000..d1e42d1
--- /dev/null
+++ b/tests/v1/platform/test_cache_context_dispatch.py
@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unit tests for the device-type-driven dispatch in
+``lmcache.v1.platform.cache_context.create_cache_context``.
+
+The facade routes by the ``torch.device.type`` reported by the
+wrappers' ``to_tensor()`` output and looks up the registered cache
+context class via :mod:`lmcache.v1.platform._registry`. These tests
+exercise that dispatch without touching CUDA or the real
+``GPUCacheContext`` / ``CPUCacheContext`` constructors -- they
+install fake classes in the registry through ``snapshot``/``restore``
+so the test stays platform-agnostic.
+"""
+
+# Standard
+from typing import Any, List
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.platform import cache_context as cache_context_module
+from lmcache.v1.platform.base_cache_context import BaseCacheContext
+from lmcache.v1.platform.cache_context import create_cache_context
+
+
+class _FakeWrapper:
+    """Minimal stand-in for a KV-cache IPC wrapper.
+
+    ``create_cache_context`` only ever reads ``to_tensor().device.type``
+    from the wrappers it receives, so a 0-byte tensor on the requested
+    device is enough.
+    """
+
+    def __init__(self, device_type: str) -> None:
+        self._device_type = device_type
+
+    def to_tensor(self) -> torch.Tensor:
+        return torch.empty(0, device=torch.device(self._device_type))
+
+
+class _FakeContext(BaseCacheContext):
+    """Bare-bones ``BaseCacheContext`` subclass used as a registry stub.
+
+    All abstract members are no-ops: the test never invokes them; it
+    only checks that the right class is instantiated with the
+    forwarded arguments.
+    """
+
+    device_type = "fake"
+
+    def __init__(
+        self,
+        kv_caches: Any,
+        lmcache_tokens_per_chunk: int,
+        layout_hints: Any,
+        engine_group_infos: Any,
+        engine_type: Any,
+        separate_object_groups: bool = True,
+        full_sw_kv: bool = False,
+    ) -> None:
+        # Skip ``BaseCacheContext.__init__`` -- it requires real
+        # KVLayerGroupsManager / shape descriptors that are out of
+        # scope for the dispatch test.
+        self.kv_caches = kv_caches
+        self.lmcache_tokens_per_chunk = lmcache_tokens_per_chunk
+        self.layout_hints = layout_hints
+        self.engine_group_infos = engine_group_infos
+        self.engine_type = engine_type
+        self.separate_object_groups = separate_object_groups
+        self.full_sw_kv = full_sw_kv
+
+    # ------------------------------------------------------------------
+    # Abstract stubs -- never called from these tests.
+    # ------------------------------------------------------------------
+
+    @property
+    def dtype(self) -> torch.dtype:  # pragma: no cover - never invoked
+        return torch.float32
+
+    @property
+    def stream(self) -> Any:  # pragma: no cover - never invoked
+        return None
+
+    @property
+    def cupy_stream(self) -> Any:  # pragma: no cover - never invoked
+        return None
+
+    @property
+    def max_batch_size(self) -> int:  # pragma: no cover - never invoked
+        return 0
+
+    def close(self) -> None:  # pragma: no cover - never invoked
+        return None
+
+    def get_kernel_group_kv_pointers(
+        self, kernel_group_idx: int
+    ) -> torch.Tensor:  # pragma: no cover
+        return torch.empty(0)
+
+    def get_temp_kernel_group_buffer(
+        self, batch_idx: int, kernel_group_idx: int
+    ) -> torch.Tensor:  # pragma: no cover
+        return torch.empty(0)
+
+    def get_temp_object_group_buffer(
+        self, batch_idx: int, object_group_idx: int
+    ) -> torch.Tensor:  # pragma: no cover
+        return torch.empty(0)
+
+    def get_kernel_group_shape_dtype(
+        self,
+        num_tokens: int,
+        kernel_group_idx: int,
+    ) -> Any:  # pragma: no cover
+        return torch.Size(()), torch.float32
+
+    def cache_size_per_token(self) -> int:  # pragma: no cover
+        return 0
+
+
+class _FakeCPUContext(_FakeContext):
+    device_type = "cpu"
+
+
+class _FakeCUDAContext(_FakeContext):
+    device_type = "cuda"
+
+
+@pytest.fixture
+def isolated_registry() -> Any:
+    """Snapshot the backend table so each test can install fakes
+    without polluting other tests / the production setup."""
+    saved = cache_context_module.snapshot_backends()
+    # Start each test from an empty backend table so we can assert
+    # the "no class registered" branch deterministically.
+    cache_context_module.restore_backends({})
+    try:
+        yield
+    finally:
+        cache_context_module.restore_backends(saved)
+
+
+def _install(**backends: type) -> None:
+    """Replace the live backend table with *backends*."""
+    cache_context_module.restore_backends(dict(backends))
+
+
+def test_dispatches_by_cpu_device_type(isolated_registry: None) -> None:
+    """Wrappers reporting ``cpu`` tensors must yield the cpu-registered
+    class."""
+    _install(cpu=_FakeCPUContext)
+
+    wrappers: List[_FakeWrapper] = [_FakeWrapper("cpu"), _FakeWrapper("cpu")]
+    ctx = create_cache_context(wrappers)  # type: ignore[arg-type]
+
+    assert isinstance(ctx, _FakeCPUContext)
+    assert ctx.kv_caches is wrappers
+
+
+def test_dispatches_by_cuda_device_type(isolated_registry: None) -> None:
+    """Wrappers reporting a non-cpu device type must route to the
+    matching registered class -- no isinstance branching."""
+    if not torch.cuda.is_available():
+        pytest.skip("CUDA not available")
+    _install(cuda=_FakeCUDAContext)
+
+    wrappers = [_FakeWrapper("cuda")]
+    ctx = create_cache_context(wrappers, lmcache_tokens_per_chunk=128)  # type: ignore[arg-type]
+
+    assert isinstance(ctx, _FakeCUDAContext)
+    assert ctx.lmcache_tokens_per_chunk == 128
+
+
+def test_empty_kv_caches_raises(isolated_registry: None) -> None:
+    with pytest.raises(ValueError, match="non-empty"):
+        create_cache_context([])
+
+
+def test_mixed_device_types_raises(isolated_registry: None) -> None:
+    """Cross-device batches are unsupported and must fail loudly."""
+    if not torch.cuda.is_available():
+        pytest.skip("CUDA not available")
+    _install(cpu=_FakeCPUContext, cuda=_FakeCUDAContext)
+
+    wrappers = [_FakeWrapper("cpu"), _FakeWrapper("cuda")]
+    with pytest.raises(ValueError, match="share one"):
+        create_cache_context(wrappers)  # type: ignore[arg-type]
+
+
+def test_unregistered_device_type_raises(isolated_registry: None) -> None:
+    """An unknown device type is a hard failure with a clear hint."""
+    wrappers = [_FakeWrapper("cpu")]
+    with pytest.raises(ValueError, match="No cache-context class"):
+        create_cache_context(wrappers)  # type: ignore[arg-type]
diff --git a/tests/v1/platform/test_cpu_shm.py b/tests/v1/platform/test_cpu_shm.py
new file mode 100644
index 0000000..02a11a4
--- /dev/null
+++ b/tests/v1/platform/test_cpu_shm.py
@@ -0,0 +1,273 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``lmcache.v1.platform.cpu.shm``.
+
+Validates that the POSIX-SHM-backed wrapper can round-trip a CPU
+tensor in-process: the constructed wrapper's ``to_tensor()`` view
+sees writes made through the original tensor.
+"""
+
+# Standard
+import os
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.posix_shm import shm_unlink
+from lmcache.v1.platform.cpu.shm import (
+    CpuShmTensorWrapper,
+    migrate_to_shm_and_wrap,
+    shm_create_readwrite,
+)
+
+
+def test_shm_create_unlink_roundtrip():
+    """``shm_create_readwrite`` succeeds and ``shm_unlink`` cleans up."""
+    name = "/lmcache_test_%d" % os.getpid()
+    addr = shm_create_readwrite(name, 4096)
+    try:
+        assert addr not in (0, None)
+    finally:
+        shm_unlink(name)
+
+
+def test_migrate_to_shm_and_wrap_zero_copy_view():
+    """After migrate, writes via the original tensor are visible via wrapper."""
+    src = torch.zeros((2, 4, 4), dtype=torch.float32)
+    wrapper = migrate_to_shm_and_wrap(src)
+    try:
+        assert isinstance(wrapper, CpuShmTensorWrapper)
+        assert wrapper.shape == (2, 4, 4)
+        assert wrapper.dtype == torch.float32
+        # Mutate via the migrated source tensor; its storage is now the
+        # SHM segment, so the wrapper's reconstructed view must see it.
+        src.add_(7.0)
+        view = wrapper.to_tensor()
+        assert torch.equal(view, src)
+    finally:
+        shm_unlink(wrapper.shm_name)
+
+
+def test_migrate_handles_empty_tensor():
+    """Empty tensors must not call ``mmap`` (length 0 is EINVAL).
+
+    Regression for the case where ``nbytes == 0``: the wrapper carries
+    an empty ``shm_name`` and ``to_tensor`` rebuilds the empty view in
+    process without touching POSIX shared memory.
+    """
+    src = torch.empty((0, 4), dtype=torch.float32)
+    wrapper = migrate_to_shm_and_wrap(src)
+    assert isinstance(wrapper, CpuShmTensorWrapper)
+    assert wrapper.shm_name == ""
+    assert wrapper.nbytes == 0
+    view = wrapper.to_tensor()
+    assert view.shape == (0, 4)
+    assert view.dtype == torch.float32
+
+
+def test_migrate_is_idempotent_on_same_tensor():
+    """Re-wrapping the same tensor reuses the existing SHM segment."""
+    src = torch.zeros((3, 5), dtype=torch.float32)
+    w1 = migrate_to_shm_and_wrap(src)
+    try:
+        w2 = migrate_to_shm_and_wrap(src)
+        assert w1.shm_name == w2.shm_name
+    finally:
+        shm_unlink(w1.shm_name)
+
+
+def test_rejects_non_cpu_tensor():
+    """Construction rejects tensors that are not on CPU."""
+    if not torch.backends.mps.is_available():
+        pytest.skip("MPS not available; cannot synthesize a non-cpu tensor")
+    src = torch.zeros((2, 2), device="mps")
+    with pytest.raises(ValueError, match="CPU tensor"):
+        CpuShmTensorWrapper(src, "/lmcache_test_should_not_exist")
+
+
+def test_migrate_finalizer_unlinks_on_gc():
+    """Once the migrated tensor is GC-ed, its SHM segment is unlinked."""
+    # Standard
+    import gc
+
+    # First Party
+    from lmcache.v1.platform.cpu.shm import shm_map_readwrite
+
+    src = torch.zeros((2, 2), dtype=torch.float32)
+    w = migrate_to_shm_and_wrap(src)
+    name = w.shm_name
+    nbytes = w.nbytes
+    # Drop both references; the weakref.finalize hook should unlink.
+    del src, w
+    gc.collect()
+    with pytest.raises(OSError):
+        shm_map_readwrite(name, nbytes)
+
+
+def test_shm_create_cleans_up_on_existing_name():
+    """If ``shm_open(O_EXCL)`` fails the helper must not leave the fd open.
+
+    We exercise the failure path by creating a segment, then asking
+    ``shm_create_readwrite`` to recreate the same name -- it must
+    raise without leaking the file descriptor it briefly held.
+    """
+    name = "/lmcache_test_excl_%d" % os.getpid()
+    addr = shm_create_readwrite(name, 4096)
+    try:
+        with pytest.raises(OSError):
+            shm_create_readwrite(name, 4096)
+    finally:
+        shm_unlink(name)
+    # And after unlink, the name is reusable again.
+    addr2 = shm_create_readwrite(name, 4096)
+    assert addr2 not in (0, None)
+    shm_unlink(name)
+    _ = addr  # silence unused-variable hint
+
+
+def test_to_tensor_view_carries_munmap_finalizer():
+    """``to_tensor`` returns a tensor whose storage releases its mmap on GC."""
+    # Standard
+    import gc
+    import weakref
+
+    src = torch.zeros((2, 2), dtype=torch.float32)
+    w = migrate_to_shm_and_wrap(src)
+    try:
+        view = w.to_tensor()
+        ref = weakref.ref(view)
+        del view
+        gc.collect()
+        assert ref() is None
+    finally:
+        del src
+        gc.collect()
+        shm_unlink(w.shm_name)
+
+
+def test_to_tensor_view_survives_reshape_after_original_is_gced():
+    """A reshape view must keep working after the original tensor is GC-ed.
+
+    Regression for the CI ``cpu_e2e_validation (server-side copy)`` segfault
+    where ``normalize_kv_and_discover_format`` reshapes the unwrapped 4D
+    tensor into the canonical 5D ``[NB, NH, BS, 2, HS]`` and the original
+    4D tensor goes out of scope. The reshape view shares the same storage
+    but used to be left without a lifetime hook, so the next read after GC
+    landed on an already-``munmap``-ed page and crashed the LMCache server.
+    """
+    # Standard
+    import gc
+
+    NB, NH, BS, HS = 8, 4, 16, 8
+    src = torch.zeros((NB, NH, BS, 2 * HS), dtype=torch.bfloat16)
+    w = migrate_to_shm_and_wrap(src)
+    try:
+        unwrapped = [w.to_tensor()]
+        normalized = [
+            layer.reshape(*layer.shape[:3], 2, layer.shape[3] // 2)
+            for layer in unwrapped
+        ]
+        # Drop every reference to the 4D unwrapped tensor; only the 5D
+        # reshape view keeps the storage alive now.
+        del unwrapped
+        gc.collect()
+
+        # These ops would segfault before the fix because the SHM mapping
+        # had been munmap-ed when the 4D tensor's finalizer ran.
+        idx = torch.tensor([0, 3, 5], dtype=torch.long)
+        gathered = normalized[0].index_select(0, idx)
+        assert tuple(gathered.shape) == (3, NH, BS, 2, HS)
+        # The SHM segment is freshly mmap'd zeros; just make sure the
+        # bytes are addressable end-to-end so the kernel does not fault.
+        assert gathered.float().abs().sum().item() == 0.0
+    finally:
+        del src
+        gc.collect()
+        shm_unlink(w.shm_name)
+
+
+def test_to_tensor_replays_stride_and_storage_offset():
+    """``to_tensor`` rebuilds the view via stride+offset (not reshape)."""
+    src = torch.arange(24, dtype=torch.float32).reshape(2, 3, 4).contiguous()
+    w = migrate_to_shm_and_wrap(src)
+    try:
+        view = w.to_tensor()
+        assert tuple(view.stride()) == w.stride
+        assert int(view.storage_offset()) == w.storage_offset
+        assert torch.equal(view, src)
+    finally:
+        del src, view
+        shm_unlink(w.shm_name)
+
+
+def test_wrap_kv_caches_unlinks_partial_batch_on_failure(monkeypatch):
+    """If wrapping the N-th tensor raises, earlier SHM names are unlinked.
+
+    Drives :func:`wrap_kv_caches` with two CPU tensors and forces the
+    second factory call to raise; the first iteration's SHM segment
+    must be ``shm_unlink``-ed so the named segment does not outlive
+    the failed batch.
+    """
+    # First Party
+    from lmcache.integration.vllm import vllm_multi_process_adapter as adapter
+    from lmcache.v1.platform.cpu.shm import shm_map_readwrite
+
+    real_wrap = adapter.wrap_one_kv_cache
+    state = {"n": 0, "first_name": None}
+
+    def flaky_wrap(tensor):
+        state["n"] += 1
+        if state["n"] == 2:
+            raise RuntimeError("simulated migration failure")
+        w = real_wrap(tensor)
+        state["first_name"] = w.shm_name
+        return w
+
+    monkeypatch.setattr(adapter, "wrap_one_kv_cache", flaky_wrap)
+
+    t1 = torch.zeros((2, 2), dtype=torch.float32)
+    t2 = torch.zeros((2, 2), dtype=torch.float32)
+    with pytest.raises(RuntimeError, match="simulated migration failure"):
+        adapter.wrap_kv_caches({"a": t1, "b": t2})
+
+    # The first iteration's SHM segment must no longer be openable.
+    nbytes = t1.numel() * t1.element_size()
+    with pytest.raises(OSError):
+        shm_map_readwrite(state["first_name"], nbytes)
+
+
+def test_migrate_ignores_stale_entry_from_id_reuse():
+    """A cached entry whose weakref is dead must not be reused.
+
+    Simulates CPython recycling an object id by injecting a stale
+    ``(dead_ref, old_name)`` tuple keyed by the live tensor's id,
+    then calling :func:`migrate_to_shm_and_wrap`. The factory must
+    treat the dead entry as a miss and allocate a fresh SHM segment
+    -- if it blindly reused the cached name, ``shm_create_readwrite``
+    would crash with ``EEXIST`` (and even worse, the fresh tensor
+    would be silently bound to the wrong SHM name).
+    """
+    # Standard
+    import gc
+    import weakref as _wr
+
+    # First Party
+    from lmcache.v1.platform.cpu.shm import inject_stale_cache_entry_for_test
+
+    # Build a tensor we will let die so we have a guaranteed-dead ref.
+    ghost = torch.zeros((1,), dtype=torch.float32)
+    dead_ref = _wr.ref(ghost)
+    del ghost
+    gc.collect()
+    assert dead_ref() is None
+
+    live = torch.zeros((2, 2), dtype=torch.float32)
+    stale_name = "/lmcache_test_stale_%d" % os.getpid()
+    inject_stale_cache_entry_for_test(live, dead_ref, stale_name)
+
+    w = migrate_to_shm_and_wrap(live)
+    try:
+        assert w.shm_name != stale_name
+    finally:
+        shm_unlink(w.shm_name)
diff --git a/tests/v1/platform/test_gpu_cache_context.py b/tests/v1/platform/test_gpu_cache_context.py
new file mode 100644
index 0000000..c8fe469
--- /dev/null
+++ b/tests/v1/platform/test_gpu_cache_context.py
@@ -0,0 +1,550 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Unit tests for the temp-GPU-buffer machinery in
+``lmcache.v1.platform.cuda.cache_context``.
+
+Two layers are exercised:
+
+* ``_TempGPUBuffer`` -- the standalone buffer manager. It is built directly
+  from a real :class:`KVLayerGroupsManager` (its constructor is fully public),
+  so the layout invariants (per-kernel-group shape/dtype, per-object-group flat
+  views, non-overlap, write isolation, byte sizing) are tested in isolation.
+
+* ``GPUCacheContext`` -- the higher-level context that owns a ``_TempGPUBuffer``
+  and exposes the per-kernel-group / per-object-group buffer accessors plus
+  ``get_kernel_group_kv_pointers``, ``calculate_num_blocks``,
+  ``kv_layer_groups_manager`` and ``report_status``. It is built through its
+  real public constructor using a lightweight ``to_tensor`` test double in place
+  of ``CudaIPCWrapper`` (same-process CUDA IPC cannot reimport its own handle).
+"""
+
+# Standard
+from collections.abc import Sequence
+
+# Third Party
+import pytest
+import torch
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="CUDA not available"
+)
+
+# First Party
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager  # noqa: E402
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo  # noqa: E402
+from lmcache.v1.platform.cuda.cache_context import (  # noqa: E402
+    GPUCacheContext,
+    _TempGPUBuffer,
+)
+import lmcache.c_ops as lmc_ops  # noqa: E402
+
+_DEVICE = torch.device("cuda")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _GroupSpec:
+    """Description of one homogeneous block of KV layers used to build the
+    synthetic ``[2, NB, BS, NH, HS]`` (non-MLA) tensors fed to the manager."""
+
+    def __init__(
+        self,
+        num_layers: int,
+        num_heads: int = 8,
+        head_size: int = 64,
+        block_size: int = 16,
+        dtype: torch.dtype = torch.bfloat16,
+    ) -> None:
+        self.num_layers = num_layers
+        self.num_heads = num_heads
+        self.head_size = head_size
+        self.block_size = block_size
+        self.dtype = dtype
+
+
+def _make_kv_tensors(
+    specs: Sequence[_GroupSpec],
+    num_blocks: int = 4,
+) -> list[torch.Tensor]:
+    """Build non-MLA per-layer KV tensors shaped ``[2, NB, BS, NH, HS]``."""
+    tensors: list[torch.Tensor] = []
+    for spec in specs:
+        for _ in range(spec.num_layers):
+            tensors.append(
+                torch.empty(
+                    2,
+                    num_blocks,
+                    spec.block_size,
+                    spec.num_heads,
+                    spec.head_size,
+                    dtype=spec.dtype,
+                    device=_DEVICE,
+                )
+            )
+    return tensors
+
+
+def _build_manager(
+    tensors: list[torch.Tensor],
+    engine_kv_format: "lmc_ops.EngineKVFormat" = (
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    ),
+    engine_group_infos: Sequence[EngineGroupInfo] = (),
+    lmcache_tokens_per_chunk: int = 256,
+) -> KVLayerGroupsManager:
+    """Build a real :class:`KVLayerGroupsManager` from synthetic tensors."""
+    return KVLayerGroupsManager(
+        tensors,
+        engine_kv_formats=[engine_kv_format] * len(tensors),
+        engine_group_infos=engine_group_infos,
+        lmcache_tokens_per_chunk=lmcache_tokens_per_chunk,
+    )
+
+
+def _make_temp_buffer(
+    specs: Sequence[_GroupSpec],
+    chunk_size: int = 256,
+    max_batch_size: int = 4,
+    num_blocks: int = 4,
+    engine_group_infos: Sequence[EngineGroupInfo] = (),
+) -> _TempGPUBuffer:
+    """Build a ``_TempGPUBuffer`` backed by a real manager."""
+    tensors = _make_kv_tensors(specs, num_blocks=num_blocks)
+    manager = _build_manager(
+        tensors,
+        engine_group_infos=engine_group_infos,
+        lmcache_tokens_per_chunk=chunk_size,
+    )
+    return _TempGPUBuffer(
+        kv_layer_groups_manager=manager,
+        lmcache_tokens_per_chunk=chunk_size,
+        device=_DEVICE,
+        max_batch_size=max_batch_size,
+    )
+
+
+def _expected_kernel_group_shape(
+    manager: KVLayerGroupsManager, num_tokens: int, kernel_group_idx: int
+) -> torch.Size:
+    """Compute the expected kernel-group buffer shape from the manager's
+    public metadata (kv_size, num_layers, slots, hidden_dim)."""
+    group = manager.kernel_groups[kernel_group_idx]
+    num_slots = num_tokens * group.slots_per_block // group.tokens_per_block
+    return torch.Size(
+        (
+            group.shape_desc.kv_size,
+            group.num_layers,
+            num_slots,
+            group.hidden_dim_size,
+        )
+    )
+
+
+def _expected_kernel_group_bytes(
+    manager: KVLayerGroupsManager, chunk_size: int, kernel_group_idx: int
+) -> int:
+    """Byte size of one kernel group's per-chunk buffer."""
+    group = manager.kernel_groups[kernel_group_idx]
+    shape = _expected_kernel_group_shape(manager, chunk_size, kernel_group_idx)
+    return shape.numel() * group.dtype.itemsize
+
+
+def _byte_region(buf: torch.Tensor) -> tuple[int, int]:
+    """Return ``(start_ptr, end_ptr)`` covering a tensor's bytes."""
+    start = buf.data_ptr()
+    return start, start + buf.nelement() * buf.element_size()
+
+
+def _assert_disjoint(regions: list[tuple[int, int, str]]) -> None:
+    """Assert that no two ``(start, end, label)`` byte ranges overlap."""
+    for i in range(len(regions)):
+        for j in range(i + 1, len(regions)):
+            s_i, e_i, label_i = regions[i]
+            s_j, e_j, label_j = regions[j]
+            assert e_i <= s_j or e_j <= s_i, f"Overlap between {label_i} and {label_j}"
+
+
+class _FakeIPCWrapper:
+    """Test-only stand-in for ``CudaIPCWrapper``.
+
+    ``GPUCacheContext`` only needs ``to_tensor()`` from each entry of its
+    ``kv_caches`` argument. Same-process CUDA IPC cannot reopen its own handle,
+    so this test double simply hands back a locally allocated CUDA tensor,
+    letting the real ``GPUCacheContext`` constructor run end to end.
+    """
+
+    def __init__(self, tensor: torch.Tensor) -> None:
+        self._tensor = tensor
+
+    def to_tensor(self) -> torch.Tensor:
+        """Return the wrapped local CUDA tensor (test-only)."""
+        return self._tensor
+
+
+def _make_context(
+    specs: Sequence[_GroupSpec],
+    chunk_size: int = 256,
+    num_blocks: int = 4,
+    engine_group_infos: Sequence[EngineGroupInfo] = (),
+) -> GPUCacheContext:
+    """Build a real ``GPUCacheContext`` via its public constructor."""
+    tensors = _make_kv_tensors(specs, num_blocks=num_blocks)
+    kv_caches = [_FakeIPCWrapper(t) for t in tensors]
+    return GPUCacheContext(
+        kv_caches,  # type: ignore
+        lmcache_tokens_per_chunk=chunk_size,
+        engine_group_infos=engine_group_infos,
+    )
+
+
+# Common group layouts reused across tests.
+_SINGLE_GROUP = [_GroupSpec(num_layers=4, num_heads=8, head_size=64)]
+_MULTI_GROUP = [
+    _GroupSpec(num_layers=4, num_heads=8, head_size=64, dtype=torch.bfloat16),
+    _GroupSpec(num_layers=2, num_heads=16, head_size=64, dtype=torch.float16),
+]
+
+
+# ---------------------------------------------------------------------------
+# _TempGPUBuffer tests
+# ---------------------------------------------------------------------------
+
+
+class TestTempGPUBufferConstruction:
+    def test_max_batch_size_property(self) -> None:
+        buf = _make_temp_buffer(_SINGLE_GROUP, max_batch_size=3)
+        assert buf.max_batch_size == 3
+
+
+class TestTempGPUBufferKernelGroupBuffer:
+    def test_shape_and_dtype(self) -> None:
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        manager = _build_manager(tensors)
+        buf = _TempGPUBuffer(manager, 256, _DEVICE)
+        for kg in range(manager.num_kernel_groups):
+            tensor = buf.get_temp_kernel_group_buffer(0, kg)
+            assert tensor.shape == _expected_kernel_group_shape(manager, 256, kg)
+            assert tensor.dtype == manager.kernel_groups[kg].dtype
+
+    def test_contiguous(self) -> None:
+        buf = _make_temp_buffer(_SINGLE_GROUP)
+        assert buf.get_temp_kernel_group_buffer(0, 0).is_contiguous()
+
+    def test_repeated_calls_same_ptr(self) -> None:
+        buf = _make_temp_buffer(_SINGLE_GROUP)
+        first = buf.get_temp_kernel_group_buffer(1, 0)
+        second = buf.get_temp_kernel_group_buffer(1, 0)
+        assert first.data_ptr() == second.data_ptr()
+
+    def test_invalid_batch_idx_raises(self) -> None:
+        buf = _make_temp_buffer(_SINGLE_GROUP, max_batch_size=4)
+        with pytest.raises(ValueError, match="Invalid batch_idx"):
+            buf.get_temp_kernel_group_buffer(4, 0)
+
+    def test_invalid_kernel_group_idx_raises(self) -> None:
+        buf = _make_temp_buffer(_SINGLE_GROUP)
+        with pytest.raises(ValueError, match="kernel_group_idx"):
+            buf.get_temp_kernel_group_buffer(0, 99)
+
+    def test_buffers_non_overlapping(self) -> None:
+        """Every (batch, kernel_group) buffer occupies disjoint memory."""
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        manager = _build_manager(tensors)
+        max_batch_size = 4
+        buf = _TempGPUBuffer(manager, 256, _DEVICE, max_batch_size=max_batch_size)
+        regions: list[tuple[int, int, str]] = []
+        for batch in range(max_batch_size):
+            for kg in range(manager.num_kernel_groups):
+                tensor = buf.get_temp_kernel_group_buffer(batch, kg)
+                start, end = _byte_region(tensor)
+                regions.append((start, end, f"batch={batch},kg={kg}"))
+        _assert_disjoint(regions)
+
+    def test_write_isolation(self) -> None:
+        """Writing to one batch slot must not corrupt another."""
+        buf = _make_temp_buffer(
+            [_GroupSpec(num_layers=2, num_heads=2, head_size=16)],
+            chunk_size=32,
+            max_batch_size=4,
+        )
+        for batch in range(4):
+            buf.get_temp_kernel_group_buffer(batch, 0).fill_(float(batch + 1))
+        for batch in range(4):
+            tensor = buf.get_temp_kernel_group_buffer(batch, 0).to(torch.float32)
+            assert tensor.min().item() == pytest.approx(batch + 1, rel=1e-3)
+            assert tensor.max().item() == pytest.approx(batch + 1, rel=1e-3)
+
+
+class TestTempGPUBufferObjectGroupBuffer:
+    def test_flat_uint8(self) -> None:
+        buf = _make_temp_buffer(_MULTI_GROUP)
+        tensor = buf.get_temp_object_group_buffer(0, 0)
+        assert tensor.dtype == torch.uint8
+        assert tensor.dim() == 1
+        assert tensor.is_contiguous()
+
+    def test_size_covers_all_kernel_groups(self) -> None:
+        """The single object group's flat buffer spans every kernel group's
+        bytes for one chunk."""
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        manager = _build_manager(tensors)
+        chunk_size = 256
+        buf = _TempGPUBuffer(manager, chunk_size, _DEVICE)
+        obj_group = manager.object_groups[0]
+        expected_bytes = sum(
+            _expected_kernel_group_bytes(manager, chunk_size, kg)
+            for kg in obj_group.kernel_group_indices
+        )
+        assert buf.get_temp_object_group_buffer(0, 0).numel() == expected_bytes
+
+    def test_starts_at_first_kernel_group(self) -> None:
+        """The object-group flat view aliases the same memory as its first
+        kernel group's buffer."""
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        manager = _build_manager(tensors)
+        buf = _TempGPUBuffer(manager, 256, _DEVICE)
+        first_kg = manager.object_groups[0].kernel_group_indices[0]
+        obj_buf = buf.get_temp_object_group_buffer(0, 0)
+        kg_buf = buf.get_temp_kernel_group_buffer(0, first_kg)
+        assert obj_buf.data_ptr() == kg_buf.data_ptr()
+
+    def test_invalid_indices_raise(self) -> None:
+        buf = _make_temp_buffer(_SINGLE_GROUP, max_batch_size=4)
+        with pytest.raises(ValueError, match="object_group_idx"):
+            buf.get_temp_object_group_buffer(0, 99)
+        with pytest.raises(ValueError, match="batch_idx"):
+            buf.get_temp_object_group_buffer(4, 0)
+
+    def test_contains_kernel_group_data(self) -> None:
+        """Bytes written through kernel-group views are visible through the
+        object-group flat view at matching offsets."""
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        chunk_size = 64
+        manager = _build_manager(tensors, lmcache_tokens_per_chunk=chunk_size)
+        buf = _TempGPUBuffer(manager, chunk_size, _DEVICE)
+        obj_group = manager.object_groups[0]
+
+        for offset_kg, kg in enumerate(obj_group.kernel_group_indices):
+            buf.get_temp_kernel_group_buffer(0, kg).view(torch.uint8).fill_(
+                offset_kg + 1
+            )
+
+        flat = buf.get_temp_object_group_buffer(0, 0)
+        cursor = 0
+        for offset_kg, kg in enumerate(obj_group.kernel_group_indices):
+            size = _expected_kernel_group_bytes(manager, chunk_size, kg)
+            region = flat[cursor : cursor + size]
+            assert region.min().item() == offset_kg + 1
+            assert region.max().item() == offset_kg + 1
+            cursor += size
+
+    def test_object_groups_non_overlapping(self) -> None:
+        """Object-group buffers across batch slots occupy disjoint memory."""
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        manager = _build_manager(tensors)
+        max_batch_size = 4
+        buf = _TempGPUBuffer(manager, 256, _DEVICE, max_batch_size=max_batch_size)
+        regions: list[tuple[int, int, str]] = []
+        for batch in range(max_batch_size):
+            for og in range(manager.num_object_groups):
+                start, end = _byte_region(buf.get_temp_object_group_buffer(batch, og))
+                regions.append((start, end, f"batch={batch},og={og}"))
+        _assert_disjoint(regions)
+
+
+class TestTempGPUBufferShapeDtype:
+    def test_shape_scales_with_num_tokens(self) -> None:
+        # num_tokens must be a whole number of chunks; the shape scales
+        # linearly with the chunk count.
+        tensors = _make_kv_tensors(_SINGLE_GROUP)
+        manager = _build_manager(tensors)
+        buf = _TempGPUBuffer(manager, 256, _DEVICE)
+        for num_tokens in (256, 512, 768):
+            shape, dtype = buf.get_kernel_group_shape_dtype(num_tokens, 0)
+            assert shape == _expected_kernel_group_shape(manager, num_tokens, 0)
+            assert dtype == manager.kernel_groups[0].dtype
+
+    def test_shape_compressed_group(self) -> None:
+        """For a compressed group, the token dim is divided by compress_ratio."""
+        tensors = _make_kv_tensors([_GroupSpec(num_layers=2, block_size=8)])
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[EngineGroupInfo(0, (0, 1), tokens_per_block=16)],
+        )
+        kg = manager.kernel_groups[0]
+        assert kg.tokens_per_block // kg.slots_per_block == 2
+        buf = _TempGPUBuffer(manager, 256, _DEVICE)
+        shape, _ = buf.get_kernel_group_shape_dtype(256, 0)
+        assert shape[2] == 256 // 2
+
+    def test_not_whole_chunks_raises(self) -> None:
+        tensors = _make_kv_tensors([_GroupSpec(num_layers=2, block_size=8)])
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[EngineGroupInfo(0, (0, 1), tokens_per_block=16)],
+        )
+        buf = _TempGPUBuffer(manager, 256, _DEVICE)
+        with pytest.raises(ValueError, match="must be a multiple of"):
+            buf.get_kernel_group_shape_dtype(255, 0)
+
+
+class TestTempGPUBufferCacheSize:
+    def test_cache_size_per_token(self) -> None:
+        tensors = _make_kv_tensors(_MULTI_GROUP)
+        manager = _build_manager(tensors)
+        chunk_size = 256
+        buf = _TempGPUBuffer(manager, chunk_size, _DEVICE)
+        expected = (
+            sum(
+                _expected_kernel_group_bytes(manager, chunk_size, kg)
+                for kg in range(manager.num_kernel_groups)
+            )
+            // chunk_size
+        )
+        assert buf.get_cache_size_per_token() == expected
+
+    def test_cache_size_per_token_compressed(self) -> None:
+        """Compression halves per-physical-slot bytes, so the per-logical-token
+        size of a 2x-compressed group is half its uncompressed counterpart."""
+        uncompressed = _make_temp_buffer([_GroupSpec(num_layers=2, block_size=16)])
+        compressed = _make_temp_buffer(
+            [_GroupSpec(num_layers=2, block_size=8)],
+            engine_group_infos=[EngineGroupInfo(0, (0, 1), tokens_per_block=16)],
+        )
+        assert (
+            compressed.get_cache_size_per_token() * 2
+            == uncompressed.get_cache_size_per_token()
+        )
+
+
+# ---------------------------------------------------------------------------
+# GPUCacheContext tests
+# ---------------------------------------------------------------------------
+
+
+class TestGPUCacheContextBuffers:
+    def test_max_batch_size(self) -> None:
+        ctx = _make_context(_SINGLE_GROUP)
+        assert ctx.max_batch_size == 4
+
+    def test_kv_layer_groups_manager(self) -> None:
+        ctx = _make_context(_MULTI_GROUP)
+        manager = ctx.kv_layer_groups_manager
+        assert isinstance(manager, KVLayerGroupsManager)
+        assert manager.num_kernel_groups == 2
+
+    def test_get_temp_kernel_group_buffer(self) -> None:
+        ctx = _make_context(_MULTI_GROUP)
+        manager = ctx.kv_layer_groups_manager
+        for kg in range(manager.num_kernel_groups):
+            tensor = ctx.get_temp_kernel_group_buffer(0, kg)
+            assert tensor.shape == _expected_kernel_group_shape(manager, 256, kg)
+            assert tensor.dtype == manager.kernel_groups[kg].dtype
+
+    def test_get_temp_object_group_buffer(self) -> None:
+        ctx = _make_context(_MULTI_GROUP)
+        tensor = ctx.get_temp_object_group_buffer(0, 0)
+        assert tensor.dtype == torch.uint8
+        assert tensor.dim() == 1
+
+    def test_get_kernel_group_shape_dtype(self) -> None:
+        ctx = _make_context(_SINGLE_GROUP)
+        manager = ctx.kv_layer_groups_manager
+        shape, dtype = ctx.get_kernel_group_shape_dtype(256, 0)
+        assert shape == _expected_kernel_group_shape(manager, 256, 0)
+        assert dtype == manager.kernel_groups[0].dtype
+
+
+class TestGPUCacheContextPointers:
+    def test_get_kernel_group_kv_pointers(self) -> None:
+        ctx = _make_context(_MULTI_GROUP)
+        manager = ctx.kv_layer_groups_manager
+        for kg in range(manager.num_kernel_groups):
+            pointers = ctx.get_kernel_group_kv_pointers(kg)
+            assert pointers.dtype == torch.long
+            # One pointer per layer in the group.
+            assert pointers.numel() == manager.kernel_groups[kg].num_layers
+
+
+class TestGPUCacheContextBlocks:
+    def test_calculate_num_blocks_uncompressed(self) -> None:
+        # block_size=16, compress_ratio=1 -> 256 tokens span 16 blocks.
+        ctx = _make_context([_GroupSpec(num_layers=2, block_size=16)])
+        assert ctx.calculate_num_blocks(256, 0) == 16
+
+    def test_calculate_num_blocks_matches_manager(self) -> None:
+        ctx = _make_context(_MULTI_GROUP)
+        manager = ctx.kv_layer_groups_manager
+        for kg in range(manager.num_kernel_groups):
+            assert ctx.calculate_num_blocks(256, kg) == manager.calculate_num_blocks(
+                kg, 256
+            )
+
+
+class TestGPUCacheContextReportStatus:
+    _TOP_LEVEL_KEYS = {
+        "num_layers",
+        "num_blocks",
+        "cache_size_per_token",
+        "kernel_groups",
+    }
+    _GROUP_KEYS = {
+        "kernel_group_idx",
+        "engine_group_idx",
+        "object_group_idx",
+        "num_layers",
+        "layer_indices",
+        "tokens_per_block",
+        "slots_per_block",
+        "dtype",
+        "engine_kv_concrete_shape",
+        "is_mla",
+        "engine_kv_format",
+        "engine_kv_shape",
+        "attention_backend",
+    }
+
+    def test_report_status_fields(self) -> None:
+        ctx = _make_context(_SINGLE_GROUP)
+        status = ctx.report_status()
+
+        assert set(status.keys()) == self._TOP_LEVEL_KEYS
+        assert status["num_layers"] == 4
+        assert status["cache_size_per_token"] == ctx.cache_size_per_token()
+
+        assert len(status["kernel_groups"]) == 1
+        group = status["kernel_groups"][0]
+        assert set(group.keys()) == self._GROUP_KEYS
+        assert group["kernel_group_idx"] == 0
+        assert group["num_layers"] == 4
+        assert group["layer_indices"] == [0, 1, 2, 3]
+        assert group["is_mla"] is False
+        assert group["engine_kv_format"] == "NL_X_TWO_NB_BS_NH_HS"
+        assert group["dtype"] == str(ctx.kv_tensors[0].dtype)
+
+    def test_report_status_multi_group(self) -> None:
+        ctx = _make_context(_MULTI_GROUP)
+        manager = ctx.kv_layer_groups_manager
+        status = ctx.report_status()
+        assert status["num_layers"] == 6
+        assert len(status["kernel_groups"]) == manager.num_kernel_groups
+
+        # Group reports enumerate in order and stay self-consistent with the
+        # manager's kernel groups.
+        for kg_idx, (group, kernel_group) in enumerate(
+            zip(status["kernel_groups"], manager.kernel_groups, strict=False)
+        ):
+            assert set(group.keys()) == self._GROUP_KEYS
+            assert group["kernel_group_idx"] == kg_idx
+            assert group["engine_group_idx"] == kernel_group.engine_group_idx
+            assert group["num_layers"] == kernel_group.num_layers
+            assert group["slots_per_block"] == kernel_group.slots_per_block
+            assert group["tokens_per_block"] == kernel_group.tokens_per_block
+            assert 0 <= group["object_group_idx"] < manager.num_object_groups
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/tests/v1/plugin/test_runtime_plugin_launcher.py b/tests/v1/plugin/test_runtime_plugin_launcher.py
new file mode 100644
index 0000000..23767c0
--- /dev/null
+++ b/tests/v1/plugin/test_runtime_plugin_launcher.py
@@ -0,0 +1,363 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for RuntimePluginLauncher.
+"""
+
+# Standard
+from pathlib import Path
+from unittest.mock import Mock, patch
+import tempfile
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.plugin.runtime_plugin_launcher import RuntimePluginLauncher
+
+
+class MockConfig:
+    """Mock configuration object."""
+
+    def __init__(self, runtime_plugin_locations=None):
+        self.runtime_plugin_locations = runtime_plugin_locations or []
+
+    def to_json(self):
+        return '{"test": "config"}'
+
+
+@pytest.fixture
+def temp_plugin_dir():
+    """Create a temporary directory for plugin files."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        yield tmpdir
+
+
+@pytest.fixture
+def config_with_location(temp_plugin_dir):
+    """Create a config with plugin location."""
+    return MockConfig([temp_plugin_dir])
+
+
+@pytest.fixture
+def config_without_location():
+    """Create a config without plugin location."""
+    return MockConfig([])
+
+
+def test_init():
+    """Test RuntimePluginLauncher initialization."""
+    config = MockConfig()
+    role = "WORKER"
+    worker_count = 4
+    worker_id = 1
+
+    launcher = RuntimePluginLauncher(config, role, worker_count, worker_id)
+
+    assert launcher.config == config
+    assert launcher.role == "WORKER"
+    assert launcher.worker_count == worker_count
+    assert launcher.worker_id == worker_id
+    assert launcher.plugin_processes == []
+
+
+def test_launch_plugins_no_locations(config_without_location):
+    """Test launch_plugins when no locations are configured."""
+    launcher = RuntimePluginLauncher(
+        config_without_location, "WORKER", worker_count=4, worker_id=1
+    )
+
+    # Should not raise any exceptions
+    launcher.launch_plugins()
+    assert len(launcher.plugin_processes) == 0
+
+
+def test_launch_plugins_location_does_not_exist():
+    """Test launch_plugins when location does not exist."""
+    config = MockConfig(["/non/existent/path"])
+    launcher = RuntimePluginLauncher(config, "WORKER", worker_count=4, worker_id=1)
+
+    with patch("lmcache.v1.plugin.runtime_plugin_launcher.logger") as mock_logger:
+        launcher.launch_plugins()
+
+        # Should log warning
+        mock_logger.warning.assert_called_once()
+        call_args = mock_logger.warning.call_args[0][0]
+        assert "does not exist" in call_args
+
+    assert len(launcher.plugin_processes) == 0
+
+
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.shutil.which")
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.subprocess.Popen")
+def test_launch_plugins_python_file(
+    mock_popen, mock_which, temp_plugin_dir, config_with_location
+):
+    """Test launching a Python plugin file."""
+    # Create a Python plugin file
+    plugin_file = Path(temp_plugin_dir) / "worker_test.py"
+    plugin_content = "#!/usr/bin/env python3\nprint('Hello from plugin')"
+    plugin_file.write_text(plugin_content)
+
+    # Mock subprocess
+    mock_proc = Mock()
+    mock_proc.stdout = Mock()
+    mock_proc.stdout.readline = Mock(side_effect=["output line\n", ""])
+    mock_proc.poll = Mock(return_value=None)
+    mock_proc.returncode = 0
+    mock_popen.return_value = mock_proc
+
+    # Mock interpreter resolution
+    mock_which.return_value = "/usr/bin/python3"
+
+    launcher = RuntimePluginLauncher(
+        config_with_location, "WORKER", worker_count=4, worker_id=1
+    )
+
+    with patch("threading.Thread") as mock_thread:
+        launcher.launch_plugins()
+
+        # Should create process
+        assert mock_popen.called
+        call_args = mock_popen.call_args[0][0]
+        assert call_args[0] == "/usr/bin/python3"
+        assert str(call_args[1]) == str(plugin_file)
+
+        # Should start thread for output capture
+        assert mock_thread.called
+
+        # Should add process to list
+        assert len(launcher.plugin_processes) == 1
+        assert launcher.plugin_processes[0] == mock_proc
+
+
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.shutil.which")
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.subprocess.Popen")
+def test_launch_plugins_role_filtering(
+    mock_popen,
+    mock_which,
+    temp_plugin_dir,
+    config_with_location,
+):
+    """Test plugin filtering based on role."""
+    # Create plugins for different roles
+    worker_plugin = Path(temp_plugin_dir) / "worker_test.py"
+    scheduler_plugin = Path(temp_plugin_dir) / "scheduler_test.py"
+    all_plugin = Path(temp_plugin_dir) / "all_test.py"
+
+    for plugin in [worker_plugin, scheduler_plugin, all_plugin]:
+        plugin.write_text("#!/usr/bin/env python3\n")
+
+    # Mock subprocess
+    mock_proc = Mock()
+    mock_proc.stdout = Mock()
+    mock_proc.stdout.readline = Mock(return_value="")
+    mock_proc.poll = Mock(return_value=None)
+    mock_popen.return_value = mock_proc
+
+    # Mock interpreter resolution
+    mock_which.return_value = "/usr/bin/python3"
+
+    # Test with worker role - should launch worker_plugin and all_plugin
+    launcher = RuntimePluginLauncher(
+        config_with_location, "WORKER", worker_count=4, worker_id=1
+    )
+
+    with (
+        patch("lmcache.v1.plugin.runtime_plugin_launcher.logger") as mock_logger,
+        patch("threading.Thread"),
+    ):
+        launcher.launch_plugins()
+
+        # Should log info about skipping scheduler plugin
+        # New format: logger.info("Skipping %s: requires role %s", file, role)
+        info_calls = [call[0] for call in mock_logger.info.call_args_list]
+        scheduler_skipped = any(
+            len(call) >= 3
+            and "requires role" in call[0]
+            and "SCHEDULER" in str(call[2])
+            for call in info_calls
+        )
+        assert scheduler_skipped
+
+        # Should launch 2 plugins (worker_plugin and all_plugin)
+        assert mock_popen.call_count == 2
+
+
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.shutil.which")
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.subprocess.Popen")
+def test_launch_plugins_worker_id_filtering(
+    mock_popen, mock_which, temp_plugin_dir, config_with_location
+):
+    """Test plugin filtering based on worker ID."""
+    # Create plugins for specific worker IDs
+    worker0_plugin = Path(temp_plugin_dir) / "worker_0_specific.py"
+    worker1_plugin = Path(temp_plugin_dir) / "worker_1_specific.py"
+    generic_worker_plugin = Path(temp_plugin_dir) / "worker_generic.py"
+
+    for plugin in [worker0_plugin, worker1_plugin, generic_worker_plugin]:
+        plugin.write_text("#!/usr/bin/env python3\n")
+
+    # Mock subprocess
+    mock_proc = Mock()
+    mock_proc.stdout = Mock()
+    mock_proc.stdout.readline = Mock(return_value="")
+    mock_proc.poll = Mock(return_value=None)
+    mock_popen.return_value = mock_proc
+
+    # Mock interpreter resolution
+    mock_which.return_value = "/usr/bin/python3"
+
+    # Test with worker_id=1 - should launch worker1_plugin and generic_worker_plugin
+    launcher = RuntimePluginLauncher(
+        config_with_location, "WORKER", worker_count=4, worker_id=1
+    )
+
+    with (
+        patch("lmcache.v1.plugin.runtime_plugin_launcher.logger") as mock_logger,
+        patch("threading.Thread"),
+    ):
+        launcher.launch_plugins()
+
+        # Should log info about skipping worker0 plugin
+        info_calls = [call[0] for call in mock_logger.info.call_args_list]
+        worker0_skipped = any(
+            len(call) >= 4
+            and "is skipping" in call[0]
+            and call[1] == 1
+            and call[3] == 0
+            for call in info_calls
+        )
+        assert worker0_skipped
+
+        # Should launch 2 plugins (worker1_plugin and generic_worker_plugin)
+        assert mock_popen.call_count == 2
+
+
+def test_get_interpreter_python(temp_plugin_dir):
+    """Test interpreter detection for Python files."""
+    # Create a Python file with shebang
+    python_file = Path(temp_plugin_dir) / "test.py"
+    python_file.write_text("#!/usr/bin/env python3\nprint('test')")
+
+    config = MockConfig()
+    launcher = RuntimePluginLauncher(config, "WORKER", 4, 1)
+
+    with patch("lmcache.v1.plugin.runtime_plugin_launcher.shutil.which") as mock_which:
+        # Mock which to return the interpreter for shebang
+        mock_which.return_value = "/usr/bin/python3"
+        interpreter = launcher._get_interpreter(python_file)
+
+        assert interpreter == "/usr/bin/python3"
+        # Should try shebang interpreter first
+        mock_which.assert_called_once_with("/usr/bin/env python3")
+        # Should NOT try fallback interpreters since shebang interpreter is found
+
+
+def test_get_interpreter_bash(temp_plugin_dir):
+    """Test interpreter detection for Bash files."""
+    # Create a Bash file
+    bash_file = Path(temp_plugin_dir) / "test.sh"
+    bash_file.write_text("#!/bin/bash\necho 'test'")
+
+    config = MockConfig()
+    launcher = RuntimePluginLauncher(config, "WORKER", 4, 1)
+
+    with patch("lmcache.v1.plugin.runtime_plugin_launcher.shutil.which") as mock_which:
+        # Mock which to return the interpreter for shebang
+        mock_which.return_value = "/bin/bash"
+        interpreter = launcher._get_interpreter(bash_file)
+
+        assert interpreter == "/bin/bash"
+        # Should try shebang interpreter first
+        mock_which.assert_called_once_with("/bin/bash")
+        # Should NOT try fallback bash since shebang interpreter is found
+
+
+def test_get_interpreter_no_shebang(temp_plugin_dir):
+    """Test interpreter detection for file without shebang."""
+    # Create a Python file without shebang
+    python_file = Path(temp_plugin_dir) / "test.py"
+    python_file.write_text("print('test')")
+
+    config = MockConfig()
+    launcher = RuntimePluginLauncher(config, "WORKER", 4, 1)
+
+    with patch("lmcache.v1.plugin.runtime_plugin_launcher.shutil.which") as mock_which:
+        # Mock which to return interpreter for python
+        mock_which.side_effect = {
+            "python": "/usr/bin/python",
+            "python3": "/usr/bin/python3",
+        }.get
+        interpreter = launcher._get_interpreter(python_file)
+
+        # Should return python (first in the fallback list)
+        assert interpreter == "/usr/bin/python"
+        # Should try python first, then stop since it's found
+        mock_which.assert_called_once_with("python")
+
+
+def test_get_interpreter_unsupported_type(temp_plugin_dir):
+    """Test interpreter detection for unsupported file type."""
+    # Create an unsupported file type
+    unsupported_file = Path(temp_plugin_dir) / "test.txt"
+    unsupported_file.write_text("test content")
+
+    config = MockConfig()
+    launcher = RuntimePluginLauncher(config, "WORKER", 4, 1)
+
+    with pytest.raises(ValueError) as exc_info:
+        launcher._get_interpreter(unsupported_file)
+
+    assert "not supported" in str(exc_info.value)
+
+
+@pytest.mark.parametrize(
+    ("role_name", "worker_id", "filename_parts", "should_skip"),
+    [
+        ("WORKER", 1, ["SCHEDULER", "test"], True),
+        ("WORKER", 1, ["WORKER", "test"], False),
+        ("WORKER", 1, ["ALL", "test"], False),
+        ("WORKER", 1, ["WORKER", "0", "specific"], True),
+        ("WORKER", 1, ["WORKER", "1", "specific"], False),
+        ("WORKER", 1, ["WORKER", "generic"], False),
+        ("SCHEDULER", 0, ["WORKER", "generic"], True),
+    ],
+)
+def test_should_skip_plugin(role_name, worker_id, filename_parts, should_skip):
+    """Test plugin skipping logic."""
+    config = MockConfig()
+    launcher = RuntimePluginLauncher(config, role_name, 4, worker_id)
+
+    assert launcher._should_skip_plugin(Path("test.py"), filename_parts) is should_skip
+
+
+def test_stop_plugins():
+    """Test stopping plugin processes."""
+    config = MockConfig()
+    launcher = RuntimePluginLauncher(config, "WORKER", 4, 1)
+
+    # Create mock processes
+    mock_proc1 = Mock()
+    mock_proc1.poll = Mock(return_value=None)  # Still running
+    mock_proc2 = Mock()
+    mock_proc2.poll = Mock(return_value=0)  # Already exited
+
+    launcher.plugin_processes = [mock_proc1, mock_proc2]
+
+    launcher.stop_plugins()
+
+    # Should terminate running process
+    mock_proc1.terminate.assert_called_once()
+    # Should not terminate exited process
+    mock_proc2.terminate.assert_not_called()
+
+
+@patch("lmcache.v1.plugin.runtime_plugin_launcher.atexit.register")
+def test_atexit_registration(mock_register):
+    """Test that cleanup handler is registered at initialization."""
+    config = MockConfig()
+
+    launcher = RuntimePluginLauncher(config, "WORKER", worker_count=4, worker_id=1)
+
+    # Should register stop_plugins with atexit
+    mock_register.assert_called_once_with(launcher.stop_plugins)
diff --git a/tests/v1/shm_allocator/__init__.py b/tests/v1/shm_allocator/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/v1/shm_allocator/csrc/.gitignore b/tests/v1/shm_allocator/csrc/.gitignore
new file mode 100644
index 0000000..567609b
--- /dev/null
+++ b/tests/v1/shm_allocator/csrc/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/tests/v1/shm_allocator/csrc/CMakeLists.txt b/tests/v1/shm_allocator/csrc/CMakeLists.txt
new file mode 100644
index 0000000..0559c16
--- /dev/null
+++ b/tests/v1/shm_allocator/csrc/CMakeLists.txt
@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.10)
+project(shm_file_worker_test LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+
+add_executable(shm_file_worker shm_file_worker.cpp)
+if(NOT APPLE)
+    target_link_libraries(shm_file_worker PRIVATE rt)
+endif()
diff --git a/tests/v1/shm_allocator/csrc/shm_file_worker.cpp b/tests/v1/shm_allocator/csrc/shm_file_worker.cpp
new file mode 100644
index 0000000..0756926
--- /dev/null
+++ b/tests/v1/shm_allocator/csrc/shm_file_worker.cpp
@@ -0,0 +1,345 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// A subprocess that opens a POSIX shared memory segment and performs
+// file I/O directly into/from it.
+//
+// Protocol (line-based, works over stdin/stdout OR TCP):
+//   ATTACH <shm_name> <shm_size> <base_addr>
+//     -> OK | ERROR <msg>
+//   WRITE <file_path> <data_ptr> <length>
+//     -> OK <bytes_written> | ERROR <msg>
+//   READ <file_path> <data_ptr> <length>
+//     -> OK <bytes_read> | ERROR <msg>
+//   QUIT
+//     -> OK
+//
+// Usage:
+//   ./shm_file_worker                 # PIPE mode (stdin/stdout)
+//   ./shm_file_worker --listen 0.0.0.0:9800  # TCP mode
+
+#include <cerrno>
+#include <cstdint>
+#include <cstdio>
+#include <cstring>
+#include <fcntl.h>
+#include <iostream>
+#include <sstream>
+#include <string>
+#include <sys/mman.h>
+#include <sys/stat.h>
+#include <unistd.h>
+
+#include <arpa/inet.h>
+#include <netinet/in.h>
+#include <sys/socket.h>
+
+static void* g_shm_ptr = nullptr;
+static size_t g_shm_size = 0;
+static uintptr_t g_base_addr = 0;
+
+static bool handle_attach(const std::string& shm_name, size_t size,
+                          uintptr_t base_addr, std::ostream& out) {
+  std::cerr << "[LOG] ATTACH shm_name=" << shm_name << " size=" << size
+            << " base_addr=" << base_addr << std::endl;
+  int fd = shm_open(shm_name.c_str(), O_RDWR, 0600);
+  if (fd < 0) {
+    std::cerr << "[LOG] ATTACH failed: shm_open: " << strerror(errno)
+              << std::endl;
+    out << "ERROR shm_open failed: " << strerror(errno) << std::endl;
+    return false;
+  }
+  void* ptr = mmap(nullptr, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+  close(fd);
+  if (ptr == MAP_FAILED) {
+    std::cerr << "[LOG] ATTACH failed: mmap: " << strerror(errno) << std::endl;
+    out << "ERROR mmap failed: " << strerror(errno) << std::endl;
+    return false;
+  }
+  g_shm_ptr = ptr;
+  g_shm_size = size;
+  g_base_addr = base_addr;
+  std::cerr << "[LOG] ATTACH succeeded" << std::endl;
+  out << "OK" << std::endl;
+  return true;
+}
+
+static void handle_write(const std::string& file_path, uintptr_t data_ptr,
+                         size_t length, std::ostream& out) {
+  std::cerr << "[LOG] WRITE path=" << file_path << " data_ptr=" << data_ptr
+            << " length=" << length << std::endl;
+  if (!g_shm_ptr) {
+    std::cerr << "[LOG] WRITE failed: not attached" << std::endl;
+    out << "ERROR not attached" << std::endl;
+    return;
+  }
+  if (data_ptr < g_base_addr) {
+    std::cerr << "[LOG] WRITE failed: data_ptr is before shm base address"
+              << std::endl;
+    out << "ERROR data_ptr is before shm base address" << std::endl;
+    return;
+  }
+  size_t offset = data_ptr - g_base_addr;
+  if (offset >= g_shm_size || length > g_shm_size - offset) {
+    std::cerr << "[LOG] WRITE failed: offset+length exceeds shm size"
+              << std::endl;
+    out << "ERROR offset+length exceeds shm size" << std::endl;
+    return;
+  }
+  int fd = open(file_path.c_str(), O_WRONLY | O_CREAT | O_TRUNC, 0644);
+  if (fd < 0) {
+    std::cerr << "[LOG] WRITE failed: open: " << strerror(errno) << std::endl;
+    out << "ERROR open failed: " << strerror(errno) << std::endl;
+    return;
+  }
+  const char* src = static_cast<const char*>(g_shm_ptr) + offset;
+  size_t written = 0;
+  while (written < length) {
+    ssize_t n = write(fd, src + written, length - written);
+    if (n < 0) {
+      if (errno == EINTR) continue;
+      close(fd);
+      std::cerr << "[LOG] WRITE failed: write: " << strerror(errno)
+                << std::endl;
+      out << "ERROR write failed: " << strerror(errno) << std::endl;
+      return;
+    }
+    written += static_cast<size_t>(n);
+  }
+  close(fd);
+  std::cerr << "[LOG] WRITE succeeded: " << written << " bytes" << std::endl;
+  out << "OK " << written << std::endl;
+}
+
+static void handle_read(const std::string& file_path, uintptr_t data_ptr,
+                        size_t length, std::ostream& out) {
+  std::cerr << "[LOG] READ path=" << file_path << " data_ptr=" << data_ptr
+            << " length=" << length << std::endl;
+  if (!g_shm_ptr) {
+    std::cerr << "[LOG] READ failed: not attached" << std::endl;
+    out << "ERROR not attached" << std::endl;
+    return;
+  }
+  if (data_ptr < g_base_addr) {
+    std::cerr << "[LOG] READ failed: data_ptr is before shm base address"
+              << std::endl;
+    out << "ERROR data_ptr is before shm base address" << std::endl;
+    return;
+  }
+  size_t offset = data_ptr - g_base_addr;
+  if (offset >= g_shm_size || length > g_shm_size - offset) {
+    std::cerr << "[LOG] READ failed: offset+length exceeds shm size"
+              << std::endl;
+    out << "ERROR offset+length exceeds shm size" << std::endl;
+    return;
+  }
+  int fd = open(file_path.c_str(), O_RDONLY);
+  if (fd < 0) {
+    std::cerr << "[LOG] READ failed: open: " << strerror(errno) << std::endl;
+    out << "ERROR open failed: " << strerror(errno) << std::endl;
+    return;
+  }
+  // Get file size to clamp read
+  struct stat st;
+  if (fstat(fd, &st) != 0) {
+    close(fd);
+    std::cerr << "[LOG] READ failed: fstat: " << strerror(errno) << std::endl;
+    out << "ERROR fstat failed: " << strerror(errno) << std::endl;
+    return;
+  }
+  size_t to_read = (static_cast<size_t>(st.st_size) < length)
+                       ? static_cast<size_t>(st.st_size)
+                       : length;
+
+  char* dst = static_cast<char*>(g_shm_ptr) + offset;
+  size_t total_read = 0;
+  while (total_read < to_read) {
+    ssize_t n = read(fd, dst + total_read, to_read - total_read);
+    if (n < 0) {
+      if (errno == EINTR) continue;
+      close(fd);
+      std::cerr << "[LOG] READ failed: read: " << strerror(errno) << std::endl;
+      out << "ERROR read failed: " << strerror(errno) << std::endl;
+      return;
+    }
+    if (n == 0) break;
+    total_read += static_cast<size_t>(n);
+  }
+  close(fd);
+  std::cerr << "[LOG] READ succeeded: " << total_read << " bytes" << std::endl;
+  out << "OK " << total_read << std::endl;
+}
+
+// Process a single command line, write response to ostream.
+static bool process_line(const std::string& line, std::ostream& out) {
+  std::istringstream iss(line);
+  std::string cmd;
+  iss >> cmd;
+
+  if (cmd == "ATTACH") {
+    std::string shm_name;
+    size_t size;
+    uintptr_t base_addr;
+    iss >> shm_name >> size >> base_addr;
+    handle_attach(shm_name, size, base_addr, out);
+  } else if (cmd == "WRITE") {
+    std::string path;
+    uintptr_t data_ptr;
+    size_t length;
+    iss >> path >> data_ptr >> length;
+    handle_write(path, data_ptr, length, out);
+  } else if (cmd == "READ") {
+    std::string path;
+    uintptr_t data_ptr;
+    size_t length;
+    iss >> path >> data_ptr >> length;
+    handle_read(path, data_ptr, length, out);
+  } else if (cmd == "QUIT") {
+    std::cerr << "[LOG] QUIT received" << std::endl;
+    out << "OK" << std::endl;
+    return false;  // signal to exit
+  } else {
+    std::cerr << "[LOG] Unknown command: " << cmd << std::endl;
+    out << "ERROR unknown command: " << cmd << std::endl;
+  }
+  return true;  // continue
+}
+
+// Read a line from a socket fd (up to newline).
+static std::string read_line_from_fd(int fd) {
+  std::string line;
+  char ch;
+  while (true) {
+    ssize_t n = ::read(fd, &ch, 1);
+    if (n <= 0) return "";
+    if (ch == '\n') break;
+    line += ch;
+  }
+  return line;
+}
+
+// Write a string to a socket fd.
+static void write_to_fd(int fd, const std::string& data) {
+  const char* ptr = data.c_str();
+  size_t remaining = data.size();
+  while (remaining > 0) {
+    ssize_t n = ::write(fd, ptr, remaining);
+    if (n <= 0) return;
+    ptr += n;
+    remaining -= static_cast<size_t>(n);
+  }
+}
+
+// Run PIPE mode: read from stdin, write to stdout.
+static int run_pipe_mode() {
+  std::ios_base::sync_with_stdio(false);
+  std::cin.tie(nullptr);
+  std::cout.tie(nullptr);
+
+  std::string line;
+  while (std::getline(std::cin, line)) {
+    if (!process_line(line, std::cout)) break;
+  }
+  return 0;
+}
+
+// Parse "host:port" string.
+static bool parse_addr(const std::string& addr, std::string& host, int& port) {
+  auto pos = addr.rfind(':');
+  if (pos == std::string::npos) return false;
+  host = addr.substr(0, pos);
+  port = std::stoi(addr.substr(pos + 1));
+  return port > 0 && port < 65536;
+}
+
+// Run TCP mode: listen on host:port, accept one client.
+static int run_tcp_mode(const std::string& addr) {
+  std::string host;
+  int port;
+  if (!parse_addr(addr, host, port)) {
+    std::cerr << "Invalid address: " << addr << std::endl;
+    return 1;
+  }
+
+  int srv = socket(AF_INET, SOCK_STREAM, 0);
+  if (srv < 0) {
+    std::cerr << "socket failed: " << strerror(errno) << std::endl;
+    return 1;
+  }
+  int opt = 1;
+  setsockopt(srv, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt));
+
+  struct sockaddr_in sa{};
+  sa.sin_family = AF_INET;
+  sa.sin_port = htons(static_cast<uint16_t>(port));
+  if (host == "0.0.0.0" || host.empty()) {
+    // Default to localhost for security
+    inet_pton(AF_INET, "127.0.0.1", &sa.sin_addr);
+  } else {
+    inet_pton(AF_INET, host.c_str(), &sa.sin_addr);
+  }
+
+  if (bind(srv, (struct sockaddr*)&sa, sizeof(sa)) < 0) {
+    std::cerr << "bind failed: " << strerror(errno) << std::endl;
+    ::close(srv);
+    return 1;
+  }
+  if (listen(srv, 1) < 0) {
+    std::cerr << "listen failed: " << strerror(errno) << std::endl;
+    ::close(srv);
+    return 1;
+  }
+
+  std::cerr << "Listening on " << host << ":" << port << std::endl;
+
+  // Accept one client connection
+  struct sockaddr_in client_addr{};
+  socklen_t client_len = sizeof(client_addr);
+  int client_fd = accept(srv, (struct sockaddr*)&client_addr, &client_len);
+  if (client_fd < 0) {
+    std::cerr << "accept failed: " << strerror(errno) << std::endl;
+    ::close(srv);
+    return 1;
+  }
+  std::cerr << "Client connected" << std::endl;
+
+  // Process commands from the client
+  while (true) {
+    std::string line = read_line_from_fd(client_fd);
+    if (line.empty()) break;
+    std::ostringstream oss;
+    bool cont = process_line(line, oss);
+    write_to_fd(client_fd, oss.str());
+    if (!cont) break;
+  }
+
+  ::close(client_fd);
+  ::close(srv);
+
+  if (g_shm_ptr) {
+    munmap(g_shm_ptr, g_shm_size);
+  }
+  return 0;
+}
+
+int main(int argc, char* argv[]) {
+  // Parse arguments
+  std::string listen_addr;
+  for (int i = 1; i < argc; ++i) {
+    std::string arg(argv[i]);
+    if (arg == "--listen" && i + 1 < argc) {
+      listen_addr = argv[++i];
+    }
+  }
+
+  int ret;
+  if (!listen_addr.empty()) {
+    ret = run_tcp_mode(listen_addr);
+  } else {
+    ret = run_pipe_mode();
+  }
+
+  if (g_shm_ptr) {
+    munmap(g_shm_ptr, g_shm_size);
+  }
+  return ret;
+}
diff --git a/tests/v1/shm_allocator/shmfile_basic_check.yaml b/tests/v1/shm_allocator/shmfile_basic_check.yaml
new file mode 100644
index 0000000..e8ba339
--- /dev/null
+++ b/tests/v1/shm_allocator/shmfile_basic_check.yaml
@@ -0,0 +1,33 @@
+# LMCache ShmFile Connector - basic_check configuration
+#
+# Usage:
+#   Step 1: Build shm_file_worker (PIPE mode, same machine)
+#     mkdir -p tests/v1/csrc/build && cd tests/v1/csrc/build
+#     cmake .. && make shm_file_worker
+#
+#   Step 2: Run basic_check
+#     LMCACHE_CONFIG_FILE=configs/shmfile_basic_check.yaml \
+#       python -m lmcache.v1.basic_check \
+#         --mode test_storage_manager
+#
+# For IDC / TCP mode (worker on host, LMCache in container):
+#   On host:  ./shm_file_worker --listen 0.0.0.0:9800
+#   In container: set shmfs.worker_addr to HOST_IP:9800
+#   and run with: docker run --ipc=host ...
+#
+# ShmFileConnector is loaded via external:// adapter, so
+# no shmfile_adapter.py is needed in production code.
+
+chunk_size: 256
+local_cpu: False
+max_local_cpu_size: 0.5
+
+remote_url: "external://host:0/tests.v1.shm_allocator.shmfile_connector/?connector_name=ShmFileConnector"
+
+extra_config:
+  # shm_name for MixedMemoryAllocator
+  shm_name: "/lmcache_verify"
+  # shmfs.* keys for ShmFileConnector
+  shmfs.storage_dir: "/data1/tmp/shmfile_basic_check_data"
+  # For TCP mode, uncomment and set:
+  shmfs.worker_addr: "127.0.0.1:9800"
\ No newline at end of file
diff --git a/tests/v1/shm_allocator/shmfile_connector.py b/tests/v1/shm_allocator/shmfile_connector.py
new file mode 100644
index 0000000..2ab2d6d
--- /dev/null
+++ b/tests/v1/shm_allocator/shmfile_connector.py
@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List, Optional
+import asyncio
+import os
+import socket
+import subprocess
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector.base_connector import (
+    RemoteConnector,
+)
+from lmcache.v1.storage_backend.local_cpu_backend import (
+    LocalCPUBackend,
+)
+
+logger = init_logger(__name__)
+
+# extra_config key prefix for shmfile connector
+_SHMFS_PREFIX = "shmfs."
+
+
+class ShmFileConnector(RemoteConnector):
+    """Connector that uses a C++ subprocess to read/write
+    files via POSIX shared memory.
+
+    Supports two communication modes:
+    - **PIPE mode** (default): spawn a local subprocess and
+      communicate via stdin/stdout. Used in unit tests.
+    - **TCP mode**: connect to a remote shm_file_worker that
+      is already listening on host:port. Used in IDC
+      environments where the worker runs on the host machine
+      while LMCache runs inside a container.
+    """
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        local_cpu_backend: LocalCPUBackend,
+        config: Optional[LMCacheEngineConfig] = None,
+    ):
+        super().__init__(
+            local_cpu_backend.config,
+            local_cpu_backend.metadata,
+        )
+
+        self.loop = loop
+        self.local_cpu_backend = local_cpu_backend
+
+        # Read shmfs.* parameters from extra_config
+        storage_dir = self._shmfs_cfg(config, "storage_dir", "/tmp/lmcache_shmfs")
+        worker_binary = self._shmfs_cfg(config, "worker_binary")
+        worker_addr = self._shmfs_cfg(config, "worker_addr")
+
+        self.storage_dir: str = storage_dir or "/tmp/lmcache_shmfs"
+        os.makedirs(self.storage_dir, exist_ok=True)
+
+        # Resolve shm_name: shmfs.shm_name -> shm_name -> allocator
+        allocator = self.local_cpu_backend.memory_allocator
+        shm_name = (
+            self._shmfs_cfg(config, "shm_name")
+            or self._extra_cfg(config, "shm_name")
+            or getattr(allocator, "shm_name", None)
+        )
+        self.shm_name = shm_name
+        if not self.shm_name:
+            raise ValueError(
+                "ShmFileConnector requires shm_name. "
+                "Set extra_config shmfs.shm_name or "
+                "shm_name, or use "
+                "MixedMemoryAllocator(shm_name=...)."
+            )
+
+        self.shm_size = getattr(allocator, "size", 0)
+        if self.shm_size <= 0:
+            raise ValueError("ShmFileConnector requires allocator.size > 0")
+
+        # Cache base address for offset calculation
+        base_ptr = getattr(allocator, "buffer", None)
+        if base_ptr is None:
+            raise ValueError("ShmFileConnector requires allocator.buffer")
+        self.base_addr = base_ptr.data_ptr()
+
+        # Communication mode: TCP or PIPE
+        self._sock: Optional[socket.socket] = None
+        self._proc: Optional[subprocess.Popen] = None
+        self._sock_buf = b""
+
+        if worker_addr:
+            # TCP mode: connect to a remote worker
+            self._init_tcp(worker_addr)
+        else:
+            # PIPE mode: spawn a local subprocess
+            self._init_pipe(worker_binary)
+
+        # Attach to shared memory
+        resp = self._send_cmd(
+            "ATTACH %s %d %d",
+            self.shm_name,
+            self.shm_size,
+            self.base_addr,
+        )
+        if not resp.startswith("OK"):
+            raise RuntimeError("shm_file_worker ATTACH failed: %s" % resp)
+
+        logger.info(
+            "ShmFileConnector: attached shm=%s size=%d base_addr=%d mode=%s",
+            self.shm_name,
+            self.shm_size,
+            self.base_addr,
+            "tcp" if self._sock else "pipe",
+        )
+
+    # -- Config helpers -------------------------------------------
+
+    @staticmethod
+    def _shmfs_cfg(
+        config: Optional[LMCacheEngineConfig],
+        key: str,
+        default: Optional[str] = None,
+    ) -> Optional[str]:
+        """Read extra_config['shmfs.<key>']."""
+        if config is None:
+            return default
+        return config.get_extra_config_value(_SHMFS_PREFIX + key, default)
+
+    @staticmethod
+    def _extra_cfg(
+        config: Optional[LMCacheEngineConfig],
+        key: str,
+        default: Optional[str] = None,
+    ) -> Optional[str]:
+        """Read extra_config['<key>'] (no prefix)."""
+        if config is None:
+            return default
+        return config.get_extra_config_value(key, default)
+
+    # -- Worker init helpers --------------------------------------
+
+    def _init_tcp(self, worker_addr: str):
+        """Connect to a remote worker via TCP."""
+        host, port_str = worker_addr.rsplit(":", 1)
+        port = int(port_str)
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._sock.connect((host, port))
+        logger.info(
+            "ShmFileConnector: connected to worker at %s",
+            worker_addr,
+        )
+
+    def _init_pipe(self, worker_binary: Optional[str]):
+        """Spawn a local worker subprocess."""
+        if worker_binary is None:
+            worker_binary = os.environ.get("SHM_FILE_WORKER_BIN", "shm_file_worker")
+        self._proc = subprocess.Popen(
+            [worker_binary],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+
+    # -- Low-level communication ----------------------------------
+
+    def _send_cmd(self, fmt: str, *args) -> str:
+        """Send a command and return the response line."""
+        cmd = (fmt % args) + "\n"
+        if self._sock is not None:
+            return self._send_cmd_tcp(cmd)
+        return self._send_cmd_pipe(cmd)
+
+    def _send_cmd_pipe(self, cmd: str) -> str:
+        """Send via stdin/stdout PIPE."""
+        assert self._proc is not None
+        assert self._proc.stdin is not None
+        assert self._proc.stdout is not None
+        self._proc.stdin.write(cmd)
+        self._proc.stdin.flush()
+        return self._proc.stdout.readline().strip()
+
+    def _send_cmd_tcp(self, cmd: str) -> str:
+        """Send via TCP socket."""
+        assert self._sock is not None
+        self._sock.sendall(cmd.encode("utf-8"))
+        # Read until newline
+        while b"\n" not in self._sock_buf:
+            data = self._sock.recv(4096)
+            if not data:
+                return "ERROR connection closed"
+            self._sock_buf += data
+        line, self._sock_buf = self._sock_buf.split(b"\n", 1)
+        return line.decode("utf-8").strip()
+
+    def _get_file_name(self, key: CacheEngineKey) -> str:
+        return key.to_string().replace("/", "-SEP-") + ".data"
+
+    def _file_path(self, key: CacheEngineKey) -> str:
+        return os.path.join(self.storage_dir, self._get_file_name(key))
+
+    # -- Connector interface --------------------------------------
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        path = self._file_path(key)
+        return await asyncio.to_thread(os.path.isfile, path)
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return os.path.isfile(self._file_path(key))
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Write memory_obj data to a file via the worker."""
+        tensor = memory_obj.tensor
+        assert tensor is not None
+        buf_ptr = tensor.data_ptr()
+        buf_size = tensor.numel() * tensor.element_size()
+
+        path = self._file_path(key)
+        resp = await asyncio.to_thread(
+            self._send_cmd,
+            "WRITE %s %d %d",
+            path,
+            buf_ptr,
+            buf_size,
+        )
+        if not resp.startswith("OK"):
+            raise RuntimeError("shm_file_worker WRITE failed: %s" % resp)
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Read a file into a newly allocated memory_obj
+        via the worker subprocess."""
+        path = self._file_path(key)
+        if not os.path.isfile(path):
+            return None
+
+        if not self.meta_shapes or not self.meta_dtypes or not self.meta_fmt:
+            logger.error("Metadata not available for get")
+            return None
+
+        memory_obj = self.local_cpu_backend.allocate(
+            self.meta_shapes,
+            self.meta_dtypes,
+            self.meta_fmt,
+        )
+        if memory_obj is None:
+            return None
+
+        tensor = memory_obj.tensor
+        if tensor is None:
+            memory_obj.ref_count_down()
+            return None
+
+        buf_ptr = tensor.data_ptr()
+        buf_size = tensor.numel() * tensor.element_size()
+
+        resp = await asyncio.to_thread(
+            self._send_cmd,
+            "READ %s %d %d",
+            path,
+            buf_ptr,
+            buf_size,
+        )
+        if not resp.startswith("OK"):
+            memory_obj.ref_count_down()
+            logger.error("shm_file_worker READ failed: %s", resp)
+            return None
+
+        parts = resp.split()
+        bytes_read = int(parts[1]) if len(parts) > 1 else 0
+        if bytes_read <= 0:
+            memory_obj.ref_count_down()
+            return None
+
+        try:
+            return self.reshape_partial_chunk(memory_obj, bytes_read)
+        except Exception:
+            logger.error(
+                "reshape_partial_chunk failed for key %s",
+                key,
+            )
+            memory_obj.ref_count_down()
+            return None
+
+    async def list(self) -> List[str]:
+        files = await asyncio.to_thread(os.listdir, self.storage_dir)
+        return [
+            f.replace(".data", "").replace("-SEP-", "/")
+            for f in files
+            if f.endswith(".data")
+        ]
+
+    async def close(self):
+        try:
+            self._send_cmd("QUIT")
+        except Exception:
+            pass
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+            self._sock = None
+        if self._proc is not None:
+            if self._proc.poll() is None:
+                self._proc.terminate()
+                self._proc.wait(timeout=5)
+            self._proc = None
+        logger.info("ShmFileConnector closed")
diff --git a/tests/v1/shm_allocator/test_shm_allocator.py b/tests/v1/shm_allocator/test_shm_allocator.py
new file mode 100644
index 0000000..d037306
--- /dev/null
+++ b/tests/v1/shm_allocator/test_shm_allocator.py
@@ -0,0 +1,463 @@
+# SPDX-License-Identifier: Apache-2.0
+"""End-to-end test for the ShmFile connector.
+
+This test verifies that:
+1. Data written via put() is persisted to a file.
+2. Data read via get() matches the original data exactly.
+3. The C++ subprocess (shm_file_worker) correctly attaches to
+   POSIX shared memory and performs I/O without extra copies.
+"""
+
+# Standard
+from multiprocessing import shared_memory
+from typing import Optional
+import asyncio
+import ctypes
+import os
+import subprocess
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend import LocalCPUBackend
+
+# Local
+from ..utils import (
+    close_asyncio_loop,
+    dumb_cache_engine_key,
+    init_asyncio_loop,
+)
+from .shmfile_connector import ShmFileConnector
+
+logger = init_logger(__name__)
+
+SHM_NAME = "/lmcache_test_shm"
+SHM_BUF_SIZE = 5 * 1024 * 1024 * 1024  # 5 GB
+
+
+_CSRC_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "csrc")
+_BUILD_DIR = os.path.join(_CSRC_DIR, "build")
+_WORKER_BIN = os.path.join(_BUILD_DIR, "shm_file_worker")
+
+
+def _build_worker_binary() -> str:
+    """Build shm_file_worker from tests/v1/shm_allocator/csrc/
+    and return the path to the compiled binary."""
+    env_bin = os.environ.get("SHM_FILE_WORKER_BIN")
+    if env_bin and os.path.isfile(env_bin):
+        return env_bin
+
+    if os.path.isfile(_WORKER_BIN):
+        return _WORKER_BIN
+
+    os.makedirs(_BUILD_DIR, exist_ok=True)
+    try:
+        subprocess.check_call(
+            ["cmake", ".."],
+            cwd=_BUILD_DIR,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        subprocess.check_call(
+            ["make", "shm_file_worker"],
+            cwd=_BUILD_DIR,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        pytest.skip(
+            "Cannot compile shm_file_worker. "
+            "Ensure cmake and a C++ compiler are available."
+        )
+    if not os.path.isfile(_WORKER_BIN):
+        pytest.skip("shm_file_worker build failed.")
+    return _WORKER_BIN
+
+
+def _get_metadata():
+    kv_shape = (32, 2, 256, 8, 128)
+    dtype = torch.bfloat16
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=dtype,
+        kv_shape=kv_shape,
+    )
+
+
+def _create_shmfs_config(
+    storage_dir: str,
+    worker_binary: str,
+    shm_name: str = SHM_NAME,
+    worker_addr: Optional[str] = None,
+) -> LMCacheEngineConfig:
+    """Build config with shmfs.* extra_config entries."""
+    extra = {
+        "shmfs.storage_dir": storage_dir,
+        "shmfs.shm_name": shm_name,
+        "shmfs.worker_binary": worker_binary,
+        "shm_name": shm_name,
+    }
+    if worker_addr:
+        extra["shmfs.worker_addr"] = worker_addr
+    return LMCacheEngineConfig.from_defaults(
+        extra_config=extra,
+    )
+
+
+def _create_local_cpu_backend(memory_allocator):
+    config = LMCacheEngineConfig.from_defaults()
+    metadata = _get_metadata()
+    return LocalCPUBackend(
+        config=config,
+        metadata=metadata,
+        memory_allocator=memory_allocator,
+    )
+
+
+@pytest.fixture
+def shm_allocator():
+    """Create a MixedMemoryAllocator backed by POSIX shm."""
+    allocator = MixedMemoryAllocator(SHM_BUF_SIZE, shm_name=SHM_NAME)
+    yield allocator
+    allocator.close()
+
+
+@pytest.fixture
+def worker_binary():
+    worker_binary_path = _build_worker_binary()
+    logger.info(f"Using shm_file_worker binary: {worker_binary_path}")
+    return worker_binary_path
+
+
+class TestShmFileConnector:
+    """End-to-end tests for ShmFileConnector."""
+
+    def test_put_and_get_roundtrip(self, shm_allocator, worker_binary):
+        """Write data via put(), then read via get() and
+        verify byte-for-byte equality."""
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            async_loop, async_thread = init_asyncio_loop()
+            try:
+                backend = _create_local_cpu_backend(shm_allocator)
+                cfg = _create_shmfs_config(
+                    tmp_dir,
+                    worker_binary,
+                )
+                connector = ShmFileConnector(
+                    loop=async_loop,
+                    local_cpu_backend=backend,
+                    config=cfg,
+                )
+
+                key = dumb_cache_engine_key()
+
+                # Verify key does not exist initially
+                fut = asyncio.run_coroutine_threadsafe(
+                    connector.exists(key), async_loop
+                )
+                assert not fut.result()
+
+                # Allocate and fill with deterministic data
+                shape = torch.Size([2, 32, 256, 1024])
+                dtype = torch.bfloat16
+                mem_obj = backend.allocate(shape, dtype)
+                assert mem_obj is not None
+                mem_obj.ref_count_up()
+
+                torch.manual_seed(42)
+                test_data = torch.randint(
+                    0,
+                    100,
+                    mem_obj.raw_data.shape,
+                    dtype=torch.int64,
+                )
+                mem_obj.raw_data.copy_(test_data.to(torch.float32).to(dtype))
+
+                # Put
+                fut = asyncio.run_coroutine_threadsafe(
+                    connector.put(key, mem_obj), async_loop
+                )
+                fut.result()
+
+                # Verify file exists on disk
+                fut = asyncio.run_coroutine_threadsafe(
+                    connector.exists(key), async_loop
+                )
+                assert fut.result()
+
+                # Get
+                fut = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+                retrieved = fut.result()
+                assert retrieved is not None
+
+                # Compare
+                orig = mem_obj.tensor
+                got = retrieved.tensor
+                assert orig is not None
+                assert got is not None
+                assert orig.shape == got.shape
+                assert torch.equal(orig, got), "Data mismatch after roundtrip!"
+
+                # Clean up
+                fut = asyncio.run_coroutine_threadsafe(connector.close(), async_loop)
+                fut.result()
+                backend.close()
+            finally:
+                close_asyncio_loop(async_loop, async_thread)
+
+    def test_get_nonexistent_key(self, shm_allocator, worker_binary):
+        """get() on a missing key returns None."""
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            async_loop, async_thread = init_asyncio_loop()
+            try:
+                backend = _create_local_cpu_backend(shm_allocator)
+                cfg = _create_shmfs_config(
+                    tmp_dir,
+                    worker_binary,
+                )
+                connector = ShmFileConnector(
+                    loop=async_loop,
+                    local_cpu_backend=backend,
+                    config=cfg,
+                )
+
+                key = dumb_cache_engine_key(id=999)
+                fut = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+                assert fut.result() is None
+
+                fut = asyncio.run_coroutine_threadsafe(connector.close(), async_loop)
+                fut.result()
+                backend.close()
+            finally:
+                close_asyncio_loop(async_loop, async_thread)
+
+    def test_list_keys(self, shm_allocator, worker_binary):
+        """list() returns keys for all stored files."""
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            async_loop, async_thread = init_asyncio_loop()
+            try:
+                backend = _create_local_cpu_backend(shm_allocator)
+                cfg = _create_shmfs_config(
+                    tmp_dir,
+                    worker_binary,
+                )
+                connector = ShmFileConnector(
+                    loop=async_loop,
+                    local_cpu_backend=backend,
+                    config=cfg,
+                )
+
+                shape = torch.Size([2, 32, 256, 1024])
+                dtype = torch.bfloat16
+
+                keys = [dumb_cache_engine_key(id=i) for i in range(3)]
+
+                for k in keys:
+                    mem_obj = backend.allocate(shape, dtype)
+                    assert mem_obj is not None
+                    mem_obj.ref_count_up()
+                    fut = asyncio.run_coroutine_threadsafe(
+                        connector.put(k, mem_obj), async_loop
+                    )
+                    fut.result()
+
+                fut = asyncio.run_coroutine_threadsafe(connector.list(), async_loop)
+                listed = set(fut.result())
+                expected = {k.to_string() for k in keys}
+                assert listed == expected
+
+                fut = asyncio.run_coroutine_threadsafe(connector.close(), async_loop)
+                fut.result()
+                backend.close()
+            finally:
+                close_asyncio_loop(async_loop, async_thread)
+
+
+class TestShmWorkerSubprocess:
+    """Test the C++ shm_file_worker directly."""
+
+    def test_allocator_receives_shm_name_from_config(self):
+        """Verify that initialize_allocator passes shm_name
+        when extra_config contains shm_name."""
+        config = LMCacheEngineConfig.from_defaults(
+            extra_config={"shm_name": "/lmc_prod_test"},
+            max_local_cpu_size=0.001,
+        )
+        metadata = _get_metadata()
+        backend = LocalCPUBackend(config=config, metadata=metadata)
+        alloc = backend.memory_allocator
+        assert isinstance(alloc, MixedMemoryAllocator)
+        assert alloc.shm_name == "/lmc_prod_test"
+        backend.close()
+
+    def test_allocator_no_shm_name_without_extra_config(self):
+        """Verify that shm_name is None when extra_config
+        does not contain shm_name."""
+        config = LMCacheEngineConfig.from_defaults(
+            max_local_cpu_size=0.001,
+        )
+        metadata = _get_metadata()
+        backend = LocalCPUBackend(config=config, metadata=metadata)
+        alloc = backend.memory_allocator
+        assert isinstance(alloc, MixedMemoryAllocator)
+        assert alloc.shm_name is None
+        backend.close()
+
+    def test_worker_attach_and_io(self, worker_binary):
+        """Verify the worker can attach, write, and read."""
+        shm_test_name = "lmcache_worker_test"
+        shm_test_size = 4096
+
+        # Create shm segment from Python side
+        shm = shared_memory.SharedMemory(
+            name=shm_test_name, create=True, size=shm_test_size
+        )
+
+        try:
+            # Write known pattern into shm
+            msg = b"Hello SHM Worker!"
+            shm.buf[:17] = msg
+
+            # Get the base address of shm buffer
+            arr_t = ctypes.c_uint8 * shm_test_size
+            arr = arr_t.from_buffer(shm.buf)
+            base_addr = ctypes.addressof(arr)
+
+            proc = subprocess.Popen(
+                [worker_binary],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                bufsize=1,
+            )
+
+            def send(cmd):
+                assert proc.stdin is not None
+                assert proc.stdout is not None
+                proc.stdin.write(cmd + "\n")
+                proc.stdin.flush()
+                return proc.stdout.readline().strip()
+
+            # Attach with base_addr
+            resp = send("ATTACH /%s %d %d" % (shm_test_name, shm_test_size, base_addr))
+            assert resp == "OK", "ATTACH failed: %s" % resp
+
+            # Write shm content to a temp file (data_ptr = base_addr)
+            with tempfile.NamedTemporaryFile(delete=False) as f:
+                tmp_path = f.name
+            try:
+                resp = send("WRITE %s %d 17" % (tmp_path, base_addr))
+                assert resp.startswith("OK"), "WRITE failed: %s" % resp
+
+                with open(tmp_path, "rb") as f:
+                    assert f.read() == msg
+
+                # Now zero the shm region and read back
+                shm.buf[:17] = b"\x00" * 17
+                resp = send("READ %s %d 17" % (tmp_path, base_addr))
+                assert resp.startswith("OK"), "READ failed: %s" % resp
+                assert bytes(shm.buf[:17]) == msg
+            finally:
+                os.unlink(tmp_path)
+
+            send("QUIT")
+            proc.wait(timeout=5)
+        finally:
+            del arr  # Release exported pointer before close
+            shm.close()
+            shm.unlink()
+
+    def test_worker_tcp_mode(self, worker_binary):
+        """Verify the worker can run in TCP mode and
+        communicate via socket."""
+        shm_test_name = "lmcache_tcp_test"
+        shm_test_size = 4096
+        tcp_port = 19800
+
+        shm = shared_memory.SharedMemory(
+            name=shm_test_name,
+            create=True,
+            size=shm_test_size,
+        )
+
+        try:
+            msg = b"Hello TCP Worker!"
+            shm.buf[:17] = msg
+
+            arr_t = ctypes.c_uint8 * shm_test_size
+            arr = arr_t.from_buffer(shm.buf)
+            base_addr = ctypes.addressof(arr)
+
+            # Start worker in TCP mode
+            proc = subprocess.Popen(
+                [
+                    worker_binary,
+                    "--listen",
+                    "127.0.0.1:%d" % tcp_port,
+                ],
+                stderr=subprocess.PIPE,
+            )
+
+            # Wait for worker to start listening
+            time.sleep(0.5)
+
+            # Standard
+            import socket as sock_mod
+
+            conn = sock_mod.socket(sock_mod.AF_INET, sock_mod.SOCK_STREAM)
+            conn.connect(("127.0.0.1", tcp_port))
+
+            def send_tcp(cmd):
+                conn.sendall((cmd + "\n").encode("utf-8"))
+                buf = b""
+                while b"\n" not in buf:
+                    data = conn.recv(4096)
+                    if not data:
+                        return "ERROR connection closed"
+                    buf += data
+                return buf.split(b"\n", 1)[0].decode().strip()
+
+            # Attach
+            resp = send_tcp(
+                "ATTACH /%s %d %d" % (shm_test_name, shm_test_size, base_addr)
+            )
+            assert resp == "OK", "ATTACH failed: %s" % resp
+
+            # Write to file
+            with tempfile.NamedTemporaryFile(delete=False) as f:
+                tmp_path = f.name
+            try:
+                resp = send_tcp("WRITE %s %d 17" % (tmp_path, base_addr))
+                assert resp.startswith("OK"), "WRITE failed: %s" % resp
+
+                with open(tmp_path, "rb") as f:
+                    assert f.read() == msg
+
+                # Zero and read back
+                shm.buf[:17] = b"\x00" * 17
+                resp = send_tcp("READ %s %d 17" % (tmp_path, base_addr))
+                assert resp.startswith("OK"), "READ failed: %s" % resp
+                assert bytes(shm.buf[:17]) == msg
+            finally:
+                os.unlink(tmp_path)
+
+            send_tcp("QUIT")
+            conn.close()
+            proc.wait(timeout=5)
+        finally:
+            del arr
+            shm.close()
+            shm.unlink()
diff --git a/tests/v1/shm_allocator/verify_shmfile_tcp.py b/tests/v1/shm_allocator/verify_shmfile_tcp.py
new file mode 100644
index 0000000..3ca1a26
--- /dev/null
+++ b/tests/v1/shm_allocator/verify_shmfile_tcp.py
@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""
+IDC end-to-end verification script for shared memory
+connector (TCP mode).
+
+This script runs INSIDE the container.  The shm_file_worker
+must be started on the HOST MACHINE first (see instructions
+below).
+
+Usage
+-----
+
+Step 1 (on the HOST machine):
+  mkdir -p tests/v1/shm_allocator/csrc/build && cd tests/v1/shm_allocator/csrc/build
+  cmake .. && make shm_file_worker
+  ./shm_file_worker --listen 0.0.0.0:9800
+
+Step 2 (INSIDE the container):
+  python tests/v1/shm_allocator/verify_shmfile_tcp.py \
+      --worker-addr <HOST_IP>:9800 \
+      --shm-name /lmcache_verify \
+      --shm-size 8388608 \
+      --storage-dir /tmp/shm_verify_data
+"""
+
+# Standard
+from multiprocessing import shared_memory
+import argparse
+import ctypes
+import hashlib
+import os
+import random
+import socket
+import sys
+import time
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="Verify SHM + TCP worker roundtrip")
+    p.add_argument(
+        "--worker-addr",
+        required=True,
+        help="host:port of the shm_file_worker",
+    )
+    p.add_argument(
+        "--shm-name",
+        default="/lmcache_verify",
+        help="POSIX shm name (must start with /)",
+    )
+    p.add_argument(
+        "--shm-size-gb",
+        type=int,
+        default=1,
+        help="Size of shared memory in GB (default 1 GB)",
+    )
+    p.add_argument(
+        "--storage-dir",
+        default="/tmp/shm_verify_data",
+        help="Directory for temporary file storage",
+    )
+    p.add_argument(
+        "--data-size-gb",
+        type=float,
+        default=0.001,
+        help="Size of test data in GB (default 0.001 GB)",
+    )
+    return p.parse_args()
+
+
+class ShmRegion:
+    """Manage a POSIX shared memory region."""
+
+    def __init__(self, name: str, size: int):
+        self.name = name.lstrip("/")
+        self.size = size
+        # Clean up stale segment if any
+        try:
+            old = shared_memory.SharedMemory(name=self.name, create=False)
+            old.close()
+            old.unlink()
+        except FileNotFoundError:
+            pass
+
+        self.shm = shared_memory.SharedMemory(name=self.name, create=True, size=size)
+        arr_t = ctypes.c_uint8 * size
+        self._arr = arr_t.from_buffer(self.shm.buf)
+        self.base_addr = ctypes.addressof(self._arr)
+        print(
+            "[OK] Created shm /%s, size=%d, "
+            "base_addr=%d" % (self.name, size, self.base_addr)
+        )
+
+    def write_bytes(self, offset: int, data: bytes):
+        self.shm.buf[offset : offset + len(data)] = data
+
+    def read_bytes(self, offset: int, length: int) -> bytes:
+        return bytes(self.shm.buf[offset : offset + length])
+
+    def zero(self, offset: int, length: int):
+        self.shm.buf[offset : offset + length] = b"\x00" * length
+
+    def close(self):
+        del self._arr
+        self.shm.close()
+        self.shm.unlink()
+        print("[OK] Cleaned up shm /%s" % self.name)
+
+
+class TcpClient:
+    """Simple TCP client for the shm_file_worker protocol."""
+
+    def __init__(self, addr: str):
+        host, port_str = addr.rsplit(":", 1)
+        port = int(port_str)
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.sock.connect((host, port))
+        self._buf = b""
+        print("[OK] Connected to worker at %s" % addr)
+
+    def send_cmd(self, cmd: str) -> str:
+        self.sock.sendall((cmd + "\n").encode("utf-8"))
+        while b"\n" not in self._buf:
+            data = self.sock.recv(4096)
+            if not data:
+                return "ERROR connection closed"
+            self._buf += data
+        line, self._buf = self._buf.split(b"\n", 1)
+        return line.decode("utf-8").strip()
+
+    def close(self):
+        try:
+            self.send_cmd("QUIT")
+        except Exception:
+            pass
+        self.sock.close()
+
+
+def md5(data: bytes) -> str:
+    return hashlib.md5(data).hexdigest()
+
+
+def main():
+    args = parse_args()
+    os.makedirs(args.storage_dir, exist_ok=True)
+    shm_size = int(args.shm_size_gb * 1024 * 1024 * 1024)
+    data_size = int(args.data_size_gb * 1024 * 1024 * 1024)
+    print("=" * 60)
+    print("SHM File Connector - IDC Verification")
+    print("=" * 60)
+    print("Worker addr : %s" % args.worker_addr)
+    print("SHM name    : %s" % args.shm_name)
+    print("SHM size    : %d GB" % args.shm_size_gb)
+    print("Data size   : %d GB" % args.data_size_gb)
+    print("Storage dir : %s" % args.storage_dir)
+    print()
+
+    # 1. Create shared memory
+    print("[Step 1] Creating POSIX shared memory...")
+    shm = ShmRegion(args.shm_name, shm_size)
+
+    # 2. Connect to remote worker
+    print("[Step 2] Connecting to remote worker...")
+    client = TcpClient(args.worker_addr)
+
+    # 3. ATTACH
+    print("[Step 3] Sending ATTACH command...")
+    resp = client.send_cmd("ATTACH %s %d %d" % (args.shm_name, shm_size, shm.base_addr))
+    if not resp.startswith("OK"):
+        print("[FAIL] ATTACH failed: %s" % resp)
+        sys.exit(1)
+    print("[OK] ATTACH response: %s" % resp)
+
+    # 4. Generate random test data and write to shm
+    print("[Step 4] Generating random test data...")
+    random.seed(42)
+    test_data = random.randbytes(data_size)
+    original_md5 = md5(test_data)
+    print("  Original data MD5: %s (%d bytes)" % (original_md5, len(test_data)))
+
+    offset = 0
+    shm.write_bytes(offset, test_data)
+
+    # 5. WRITE: worker reads from shm and writes to file
+    file_path = os.path.join(args.storage_dir, "verify_test.data")
+    data_ptr = shm.base_addr + offset
+    print("[Step 5] WRITE: shm -> file (%s)..." % file_path)
+    t0 = time.time()
+    resp = client.send_cmd("WRITE %s %d %d" % (file_path, data_ptr, data_size))
+    t1 = time.time()
+    if not resp.startswith("OK"):
+        print("[FAIL] WRITE failed: %s" % resp)
+        sys.exit(1)
+    print("[OK] WRITE response: %s (%.3f ms)" % (resp, (t1 - t0) * 1000))
+
+    # Verify file content from disk
+    with open(file_path, "rb") as f:
+        file_data = f.read()
+    file_md5 = md5(file_data)
+    print("  File on disk MD5 : %s" % file_md5)
+    if file_md5 != original_md5:
+        print("[FAIL] WRITE data mismatch!")
+        sys.exit(1)
+    print("[OK] WRITE data verified!")
+
+    # 6. Zero the shm region
+    print("[Step 6] Zeroing shm region...")
+    shm.zero(offset, data_size)
+    zero_md5 = md5(shm.read_bytes(offset, data_size))
+    print("  Zeroed shm MD5   : %s" % zero_md5)
+
+    # 7. READ: worker reads from file and writes to shm
+    print("[Step 7] READ: file -> shm (%s)..." % file_path)
+    t0 = time.time()
+    resp = client.send_cmd("READ %s %d %d" % (file_path, data_ptr, data_size))
+    t1 = time.time()
+    if not resp.startswith("OK"):
+        print("[FAIL] READ failed: %s" % resp)
+        sys.exit(1)
+    print("[OK] READ response: %s (%.3f ms)" % (resp, (t1 - t0) * 1000))
+
+    # 8. Verify data in shm matches original
+    print("[Step 8] Verifying data in shm...")
+    read_back = shm.read_bytes(offset, data_size)
+    read_md5 = md5(read_back)
+    print("  Read-back MD5    : %s" % read_md5)
+    if read_md5 != original_md5:
+        print("[FAIL] READ data mismatch!")
+        print("  Expected: %s, Got: %s" % (original_md5, read_md5))
+        sys.exit(1)
+    print("[OK] READ data verified!")
+
+    # 9. Byte-by-byte comparison
+    print("[Step 9] Byte-by-byte comparison...")
+    if read_back == test_data:
+        print("[OK] All %d bytes match!" % data_size)
+    else:
+        # Find first mismatch
+        for i in range(len(test_data)):
+            if read_back[i] != test_data[i]:
+                print(
+                    "[FAIL] First mismatch at byte %d: "
+                    "expected 0x%02x, got 0x%02x" % (i, test_data[i], read_back[i])
+                )
+                sys.exit(1)
+
+    # Cleanup
+    print()
+    print("[Step 10] Cleaning up...")
+    client.close()
+    shm.close()
+    os.unlink(file_path)
+
+    print()
+    print("=" * 60)
+    print("ALL CHECKS PASSED!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/v1/storage_backend/__init__.py b/tests/v1/storage_backend/__init__.py
new file mode 100644
index 0000000..9881313
--- /dev/null
+++ b/tests/v1/storage_backend/__init__.py
@@ -0,0 +1 @@
+# SPDX-License-Identifier: Apache-2.0
diff --git a/tests/v1/storage_backend/raw_block_test_utils.py b/tests/v1/storage_backend/raw_block_test_utils.py
new file mode 100644
index 0000000..29a6c3b
--- /dev/null
+++ b/tests/v1/storage_backend/raw_block_test_utils.py
@@ -0,0 +1,265 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TypeVar
+import importlib
+import select
+import sys
+import types
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.platform import consume_fd
+from lmcache.v1.storage_backend.raw_block import RawBlockCoreConfig
+
+RAW_BLOCK_CI_CAPACITY_BYTES = 128 * 1024 * 1024
+RAW_BLOCK_CI_BLOCK_ALIGN = 4096
+RAW_BLOCK_CI_HEADER_BYTES = 4096
+RAW_BLOCK_CI_SLOT_BYTES = 64 * 1024
+RAW_BLOCK_CI_META_TOTAL_BYTES = 1 * 1024 * 1024
+_T = TypeVar("_T")
+
+
+def make_raw_block_file(
+    tmp_path: Path,
+    size_bytes: int = RAW_BLOCK_CI_CAPACITY_BYTES,
+) -> Path:
+    """Create a fixed-size file for raw block backend tests.
+
+    Args:
+        tmp_path: Pytest temporary directory used to place the backing file.
+        size_bytes: Size of the file to create in bytes.
+
+    Returns:
+        Path to the created backing file.
+    """
+    path = tmp_path / "raw_block_ci.bin"
+    with open(path, "wb") as f:
+        f.truncate(size_bytes)
+    return path
+
+
+def make_raw_block_core_config(
+    path: Path,
+    capacity_bytes: int = RAW_BLOCK_CI_CAPACITY_BYTES,
+) -> RawBlockCoreConfig:
+    """Build a small POSIX raw block core config for temp-file tests.
+
+    Args:
+        path: Backing file path for the raw block device.
+        capacity_bytes: Total capacity exposed by the raw block test file.
+
+    Returns:
+        Raw block core configuration using CI-safe defaults.
+    """
+    return RawBlockCoreConfig(
+        device_path=str(path),
+        capacity_bytes=capacity_bytes,
+        block_align=RAW_BLOCK_CI_BLOCK_ALIGN,
+        header_bytes=RAW_BLOCK_CI_HEADER_BYTES,
+        slot_bytes=RAW_BLOCK_CI_SLOT_BYTES,
+        use_odirect=False,
+        enable_zero_copy=False,
+        meta_total_bytes=RAW_BLOCK_CI_META_TOTAL_BYTES,
+        meta_magic=b"LMCIDX01",
+        meta_version=1,
+        meta_checkpoint_interval_sec=60,
+        meta_idle_quiet_ms=0,
+        meta_enable_periodic=False,
+        meta_verify_on_load=True,
+        io_engine="posix",
+        iouring_queue_depth=8,
+    )
+
+
+def make_object_key(chunk_id: int, model_name: str = "raw_block_ci") -> ObjectKey:
+    """Create a deterministic object key for raw block tests.
+
+    Args:
+        chunk_id: Integer chunk identifier encoded into the object key hash.
+        model_name: Model name stored in the object key.
+
+    Returns:
+        Object key with a stable hash, model name, and KV rank.
+    """
+    return ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(chunk_id),
+        model_name=model_name,
+        kv_rank=0,
+    )
+
+
+def make_memory_obj(payload: bytes | bytearray | memoryview) -> TensorMemoryObj:
+    """Wrap payload bytes in a binary tensor memory object.
+
+    Args:
+        payload: Byte-compatible data to expose through TensorMemoryObj.
+
+    Returns:
+        Tensor memory object containing the payload bytes.
+    """
+    data = bytearray(payload)
+    raw_data = torch.frombuffer(data, dtype=torch.uint8)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([len(data)]),
+        dtype=torch.uint8,
+        address=0,
+        phy_size=len(data),
+        fmt=MemoryFormat.BINARY,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def make_empty_memory_obj(size_bytes: int) -> TensorMemoryObj:
+    """Create a zero-filled binary tensor memory object.
+
+    Args:
+        size_bytes: Number of bytes to allocate.
+
+    Returns:
+        Tensor memory object backed by a zero-filled uint8 tensor.
+    """
+    raw_data = torch.zeros(size_bytes, dtype=torch.uint8)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size_bytes]),
+        dtype=torch.uint8,
+        address=0,
+        phy_size=size_bytes,
+        fmt=MemoryFormat.BINARY,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def memory_obj_bytes(obj: TensorMemoryObj) -> bytes:
+    """Copy a tensor memory object's byte contents into bytes.
+
+    Args:
+        obj: Tensor memory object to read.
+
+    Returns:
+        Byte copy of the object's data buffer.
+    """
+    return bytes(obj.byte_array)
+
+
+def wait_for_event_fd(event_fd: int, timeout: float = 5.0) -> bool:
+    """Wait for an eventfd notification and consume it when present.
+
+    Args:
+        event_fd: Event file descriptor to poll.
+        timeout: Maximum wait time in seconds.
+
+    Returns:
+        True when an event was observed, otherwise False.
+    """
+    poll = select.poll()
+    poll.register(event_fd, select.POLLIN)
+    events = poll.poll(timeout * 1000)
+    if not events:
+        return False
+    try:
+        consume_fd(event_fd)
+    except BlockingIOError:
+        pass
+    return True
+
+
+def install_native_storage_ops_fallback() -> None:
+    """Install a small native_storage_ops fallback for test environments.
+
+    Args:
+        None.
+
+    Returns:
+        None.
+    """
+    try:
+        native_storage_ops = importlib.import_module("lmcache.native_storage_ops")
+        if hasattr(native_storage_ops, "Bitmap") and hasattr(
+            native_storage_ops, "TTLLock"
+        ):
+            return
+    except Exception:
+        pass
+
+    class Bitmap:
+        def __init__(self, size: int, first_n: int = 0) -> None:
+            self._size = int(size)
+            self._bits = {i for i in range(min(int(first_n), self._size))}
+
+        def set(self, index: int) -> None:
+            index = int(index)
+            if index < 0 or index >= self._size:
+                raise IndexError(index)
+            self._bits.add(index)
+
+        def test(self, index: int) -> bool:
+            return int(index) in self._bits
+
+        def get_indices_list(self) -> list[int]:
+            return sorted(self._bits)
+
+        def popcount(self) -> int:
+            return len(self._bits)
+
+        def count_leading_ones(self) -> int:
+            count = 0
+            while count in self._bits:
+                count += 1
+            return count
+
+        def gather(self, values: Sequence[_T]) -> list[_T]:
+            return [values[i] for i in self.get_indices_list()]
+
+        def __and__(self, other: "Bitmap") -> "Bitmap":
+            size = min(self._size, other._size)
+            result = Bitmap(size)
+            result._bits = {i for i in self._bits & other._bits if i < size}
+            return result
+
+        def __iand__(self, other: "Bitmap") -> "Bitmap":
+            self._bits &= other._bits
+            self._bits = {i for i in self._bits if i < self._size}
+            return self
+
+        def __or__(self, other: "Bitmap") -> "Bitmap":
+            size = max(self._size, other._size)
+            result = Bitmap(size)
+            result._bits = set(self._bits | other._bits)
+            return result
+
+        def __ior__(self, other: "Bitmap") -> "Bitmap":
+            self._size = max(self._size, other._size)
+            self._bits |= other._bits
+            return self
+
+        def __invert__(self) -> "Bitmap":
+            result = Bitmap(self._size)
+            result._bits = set(range(self._size)) - self._bits
+            return result
+
+        def __str__(self) -> str:
+            return "".join("1" if i in self._bits else "0" for i in range(self._size))
+
+    class TTLLock:
+        pass
+
+    fallback_module = types.ModuleType("lmcache.native_storage_ops")
+    fallback_module.__dict__["Bitmap"] = Bitmap
+    fallback_module.__dict__["TTLLock"] = TTLLock
+    sys.modules["lmcache.native_storage_ops"] = fallback_module
diff --git a/tests/v1/storage_backend/test_audit_connector.py b/tests/v1/storage_backend/test_audit_connector.py
new file mode 100644
index 0000000..10243ed
--- /dev/null
+++ b/tests/v1/storage_backend/test_audit_connector.py
@@ -0,0 +1,654 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from io import StringIO
+import asyncio
+import logging
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+    TensorMemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector.audit_connector import AuditConnector
+from lmcache.v1.storage_backend.connector.mock_connector import MockConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+
+def create_test_key(key_id: str) -> CacheEngineKey:
+    """Helper to create a test CacheEngineKey"""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.uint8,
+    )
+
+
+def create_mock_memory_obj(backend: LocalCPUBackend, data: bytes) -> MemoryObj:
+    """Helper to create a mock MemoryObj with proper structure"""
+    tensor = torch.tensor(
+        [ord(c) for c in data.decode("latin1") if ord(c) < 256], dtype=torch.uint8
+    )
+    if len(tensor) == 0:
+        tensor = torch.tensor([0], dtype=torch.uint8)
+
+    memory_obj = backend.allocate(
+        shapes=[tensor.shape],
+        dtypes=[tensor.dtype],
+        fmt=MemoryFormat.KV_2LTD,
+    )
+
+    if memory_obj is not None and isinstance(memory_obj, TensorMemoryObj):
+        memory_obj.tensor.copy_(tensor)
+
+    return memory_obj
+
+
+@pytest.fixture
+def event_loop():
+    """Create an event loop for async tests"""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    yield loop
+
+    # Simplified cleanup logic
+    try:
+        pending = asyncio.all_tasks(loop)
+        for task in pending:
+            task.cancel()
+
+        if not loop.is_closed():
+            loop.call_soon(loop.stop)
+            loop.run_forever()
+            loop.close()
+    except Exception:
+        pass
+    finally:
+        asyncio.set_event_loop(None)
+
+
+@pytest.fixture
+def local_cpu_backend():
+    """Fixture for LocalCPUBackend"""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=1,
+        remote_url="mock://test",
+        extra_config={},
+    )
+    metadata = LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(64, 2, 1, 8, 128),
+    )
+    allocator = AdHocMemoryAllocator(device="cpu")
+    return LocalCPUBackend(config=config, metadata=metadata, memory_allocator=allocator)
+
+
+@pytest.fixture
+def mock_connector(event_loop, local_cpu_backend):
+    """Fixture for mock connector"""
+    connector = MockConnector(
+        url="mock://test",
+        loop=event_loop,
+        local_cpu_backend=local_cpu_backend,
+        capacity=1,
+        peeking_latency=0.0,
+        read_throughput=100.0,
+        write_throughput=100.0,
+    )
+    yield connector
+    # Clean up connector to ensure AsyncPQExecutor is properly shut down
+    try:
+        # Close the connector which will shutdown the AsyncPQExecutor
+        connector.close()
+    except Exception as e:
+        # Log but don't fail the test
+        print(f"Failed to close mock connector: {e}")
+
+
+class LogCaptureHandler(logging.Handler):
+    def __init__(self):
+        super().__init__()
+        self.records = []
+        self.stream = StringIO()
+
+    def emit(self, record):
+        self.records.append(record)
+        msg = self.format(record)
+        self.stream.write(msg + "\n")
+
+    def get_records(self):
+        return self.records
+
+    def get_logs(self):
+        return self.stream.getvalue()
+
+    def clear(self):
+        self.records = []
+        self.stream = StringIO()
+
+
+@pytest.fixture
+def log_capture():
+    """Fixture for capturing logs"""
+    handler = LogCaptureHandler()
+    handler.setFormatter(logging.Formatter("%(name)s - %(levelname)s - %(message)s"))
+
+    # Get audit logger and add handler
+    audit_logger = logging.getLogger(
+        "lmcache.v1.storage_backend.connector.audit_connector"
+    )
+    original_level = audit_logger.level
+    audit_logger.setLevel(logging.INFO)
+    audit_logger.addHandler(handler)
+
+    yield handler
+
+    # Cleanup
+    audit_logger.removeHandler(handler)
+    audit_logger.setLevel(original_level)
+
+
+class TestAuditConnector:
+    """Test AuditConnector functionality"""
+
+    def test_initialization_basic(self, mock_connector, log_capture):
+        """Test basic initialization"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+        audit = AuditConnector(mock_connector, config)
+
+        assert audit.real_connector is mock_connector
+        assert audit.verify_checksum is False
+        assert audit.calc_checksum is False
+        assert len(audit.excluded_cmds) == 0
+
+        print("\nCaptured logs:")
+        print(log_capture.get_logs())
+
+        init_logs = [
+            r.msg
+            for r in log_capture.get_records()
+            if "[REMOTE_AUDIT]" in r.msg and "INITIALIZED" in r.msg
+        ]
+
+        assert len(init_logs) > 0, (
+            f"Expected INITIALIZED log. Got logs: {log_capture.get_logs()}"
+        )
+
+    def test_initialization_with_checksum(self, mock_connector, log_capture):
+        """Test initialization with checksum enabled"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={
+                "audit_calc_checksum": True,
+                "audit_verify_checksum": True,
+            },
+        )
+        audit = AuditConnector(mock_connector, config)
+
+        assert audit.verify_checksum is True
+        assert audit.calc_checksum is True
+        assert audit.registry_lock is not None
+
+        print("\nCaptured logs:")
+        print(log_capture.get_logs())
+
+        init_logs = [r for r in log_capture.get_records() if "INITIALIZED" in r.msg]
+        assert len(init_logs) > 0, (
+            f"Expected INITIALIZED log. Got logs: {log_capture.get_logs()}"
+        )
+        assert "Calc Checksum:True" in init_logs[0].msg
+
+    def test_initialization_with_excluded_cmds(self, mock_connector, log_capture):
+        """Test initialization with excluded commands"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={
+                "audit_exclude_cmds": "exists,list",
+            },
+        )
+        audit = AuditConnector(mock_connector, config)
+
+        assert "exists" in audit.excluded_cmds
+        assert "list" in audit.excluded_cmds
+
+        print("\nCaptured logs:")
+        print(log_capture.get_logs())
+
+        init_logs = [r for r in log_capture.get_records() if "INITIALIZED" in r.msg]
+        assert len(init_logs) > 0, (
+            f"Expected INITIALIZED log. Got logs: {log_capture.get_logs()}"
+        )
+        assert "Excluded Cmds:" in init_logs[0].msg
+
+    def test_put_and_get_with_audit_log(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test put and get operations with audit log verification"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key = create_test_key("test_key")
+            memory_obj = create_mock_memory_obj(local_cpu_backend, b"test_data")
+
+            log_capture.clear()
+
+            await audit.put(key, memory_obj)
+
+            print("\nAfter PUT:")
+            print(log_capture.get_logs())
+
+            put_logs = [
+                r
+                for r in log_capture.get_records()
+                if "PUT" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(put_logs) > 0, (
+                f"Expected PUT audit log. Got logs: {log_capture.get_logs()}"
+            )
+            assert "Cost:" in put_logs[0].msg
+            assert "Size:" in put_logs[0].msg
+
+            log_capture.clear()
+
+            result = await audit.get(key)
+            assert result is not None
+            assert result.metadata.shape == memory_obj.metadata.shape
+
+            print("\nAfter GET:")
+            print(log_capture.get_logs())
+
+            get_logs = [
+                r
+                for r in log_capture.get_records()
+                if "GET" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(get_logs) > 0, (
+                f"Expected GET audit log. Got logs: {log_capture.get_logs()}"
+            )
+            assert "Cost:" in get_logs[0].msg
+
+        event_loop.run_until_complete(run_test())
+
+    def test_exists_with_audit_log(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test exists operation with audit log"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key = create_test_key("test_key")
+
+            log_capture.clear()
+
+            result = await audit.exists(key)
+            assert result is False
+
+            print("\nAfter EXISTS:")
+            print(log_capture.get_logs())
+
+            exists_logs = [
+                r
+                for r in log_capture.get_records()
+                if "EXISTS" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(exists_logs) > 0, (
+                f"Expected EXISTS audit log. Got logs: {log_capture.get_logs()}"
+            )
+            assert "Cost:" in exists_logs[0].msg
+
+        event_loop.run_until_complete(run_test())
+
+    def test_put_with_checksum_audit_log(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test put with checksum calculation and audit log"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={
+                "audit_calc_checksum": True,
+                "audit_verify_checksum": True,
+            },
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key = create_test_key("test_key")
+            memory_obj = create_mock_memory_obj(local_cpu_backend, b"test_data")
+
+            log_capture.clear()
+
+            await audit.put(key, memory_obj)
+
+            print("\nAfter PUT with checksum:")
+            print(log_capture.get_logs())
+
+            put_logs = [
+                r
+                for r in log_capture.get_records()
+                if "PUT" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(put_logs) > 0, (
+                f"Expected PUT audit log. Got logs: {log_capture.get_logs()}"
+            )
+            assert "Checksum:" in put_logs[0].msg
+            assert "Checksum:N/A" not in put_logs[0].msg
+
+        event_loop.run_until_complete(run_test())
+
+    def test_put_and_get_with_kwargs(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test put and get operations with keyword arguments
+        to ensure robust argument handling."""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key = create_test_key("test_key_kwargs")
+            memory_obj = create_mock_memory_obj(local_cpu_backend, b"test_data_kwargs")
+
+            log_capture.clear()
+
+            # Use keyword arguments to test argument passing
+            await audit.put(key=key, memory_obj=memory_obj)
+
+            put_logs = [
+                r
+                for r in log_capture.get_records()
+                if "PUT" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(put_logs) > 0, "Expected PUT audit log with keyword arguments."
+
+            log_capture.clear()
+
+            result = await audit.get(key=key)
+            assert result is not None
+
+            get_logs = [
+                r
+                for r in log_capture.get_records()
+                if "GET" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(get_logs) > 0, "Expected GET audit log with keyword arguments."
+
+        event_loop.run_until_complete(run_test())
+
+    def test_excluded_command_no_audit_log(
+        self, mock_connector, event_loop, log_capture
+    ):
+        """Test that excluded commands don't generate audit logs"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={
+                "audit_exclude_cmds": "exists",
+            },
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key = create_test_key("test_key")
+
+            log_capture.clear()
+
+            await audit.exists(key)
+
+            print("\nAfter excluded EXISTS:")
+            print(log_capture.get_logs())
+
+            exists_logs = [
+                r
+                for r in log_capture.get_records()
+                if "EXISTS" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(exists_logs) == 0, (
+                f"Excluded command should not log. Got logs: {log_capture.get_logs()}"
+            )
+
+        event_loop.run_until_complete(run_test())
+
+    def test_non_excluded_command_has_audit_log(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test that non-excluded commands generate audit logs"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={
+                "audit_exclude_cmds": "exists",
+            },
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key = create_test_key("test_key")
+            memory_obj = create_mock_memory_obj(local_cpu_backend, b"test_data")
+
+            log_capture.clear()
+
+            await audit.put(key, memory_obj)
+
+            print("\nAfter non-excluded PUT:")
+            print(log_capture.get_logs())
+
+            put_logs = [
+                r
+                for r in log_capture.get_records()
+                if "PUT" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(put_logs) > 0, (
+                f"Non-excluded command should log. Got logs: {log_capture.get_logs()}"
+            )
+
+        event_loop.run_until_complete(run_test())
+
+    def test_not_audit_decorator(self, mock_connector, log_capture):
+        """Test that @NotAudit methods don't generate operation audit logs"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+        audit = AuditConnector(mock_connector, config)
+
+        log_capture.clear()
+
+        audit.post_init()
+
+        print("\nAfter @NotAudit methods:")
+        print(log_capture.get_logs())
+
+        operation_logs = [r for r in log_capture.get_records() if "POST_INIT" in r.msg]
+        operation_logs = [r for r in operation_logs if "SUCCESS" in r.msg]
+        assert len(operation_logs) == 0, (
+            f"@NotAudit methods should not generate operation audit logs. "
+            f"Got logs: {log_capture.get_logs()}"
+        )
+
+    def test_batched_get_with_audit_log(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test batched get with audit log"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key1 = create_test_key("key1")
+            key2 = create_test_key("key2")
+
+            await audit.put(key1, create_mock_memory_obj(local_cpu_backend, b"data1"))
+            await audit.put(key2, create_mock_memory_obj(local_cpu_backend, b"data2"))
+
+            log_capture.clear()
+
+            results = await audit.batched_get([key1, key2])
+            assert len(results) == 2
+            assert all(r is not None for r in results)
+
+            print("\nAfter BATCHED_GET:")
+            print(log_capture.get_logs())
+
+            batched_logs = [
+                r
+                for r in log_capture.get_records()
+                if "BATCHED_GET" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(batched_logs) > 0, (
+                f"Expected BATCHED_GET audit log. Got logs: {log_capture.get_logs()}"
+            )
+            assert "Cost:" in batched_logs[0].msg
+
+        event_loop.run_until_complete(run_test())
+
+    def test_batched_async_contains_with_audit_log(
+        self, mock_connector, local_cpu_backend, event_loop, log_capture
+    ):
+        """Test batched async contains with audit log"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+
+        async def run_test():
+            audit = AuditConnector(mock_connector, config)
+            key1 = create_test_key("key1")
+            key2 = create_test_key("key2")
+            key3 = create_test_key("key3")
+
+            await audit.put(key1, create_mock_memory_obj(local_cpu_backend, b"data1"))
+            await audit.put(key2, create_mock_memory_obj(local_cpu_backend, b"data2"))
+
+            log_capture.clear()
+
+            count = await audit.batched_async_contains("lookup1", [key1, key2, key3])
+            assert count == 2
+
+            print("\nAfter BATCHED_ASYNC_CONTAINS:")
+            print(log_capture.get_logs())
+
+            batched_logs = [
+                r
+                for r in log_capture.get_records()
+                if "BATCHED_ASYNC_CONTAINS" in r.msg and "SUCCESS" in r.msg
+            ]
+            assert len(batched_logs) > 0, (
+                f"Expected BATCHED_ASYNC_CONTAINS audit log. "
+                f"Got logs: {log_capture.get_logs()}"
+            )
+            assert "Cost:" in batched_logs[0].msg
+
+        event_loop.run_until_complete(run_test())
+
+    def test_support_methods(self, mock_connector):
+        """Test support_* methods are properly forwarded"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+        audit = AuditConnector(mock_connector, config)
+
+        assert audit.support_batched_get() is True
+        assert audit.support_batched_async_contains() is True
+
+    def test_exists_sync_with_audit_log(self, mock_connector, log_capture):
+        """Test exists_sync synchronous operation with audit log"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={},
+        )
+        audit = AuditConnector(mock_connector, config)
+        key = create_test_key("test_key")
+
+        log_capture.clear()
+
+        result = audit.exists_sync(key)
+        assert result is False
+
+        print("\nAfter EXISTS_SYNC:")
+        print(log_capture.get_logs())
+
+        exists_sync_logs = [
+            r
+            for r in log_capture.get_records()
+            if "EXISTS_SYNC" in r.msg and "SUCCESS" in r.msg
+        ]
+        assert len(exists_sync_logs) > 0, (
+            f"Expected EXISTS_SYNC audit log. Got logs: {log_capture.get_logs()}"
+        )
+        assert "Cost:" in exists_sync_logs[0].msg
+
+    def test_exists_sync_excluded_no_audit_log(self, mock_connector, log_capture):
+        """Test that excluded exists_sync doesn't generate audit logs"""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=1,
+            remote_url="mock://test",
+            extra_config={
+                "audit_exclude_cmds": "exists_sync",
+            },
+        )
+        audit = AuditConnector(mock_connector, config)
+        key = create_test_key("test_key")
+
+        log_capture.clear()
+
+        result = audit.exists_sync(key)
+        assert result is False
+
+        print("\nAfter excluded EXISTS_SYNC:")
+        print(log_capture.get_logs())
+
+        exists_sync_logs = [
+            r
+            for r in log_capture.get_records()
+            if "EXISTS_SYNC" in r.msg and "SUCCESS" in r.msg
+        ]
+        assert len(exists_sync_logs) == 0, (
+            f"Excluded exists_sync should not log. Got logs: {log_capture.get_logs()}"
+        )
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v", "-s"])
diff --git a/tests/v1/storage_backend/test_azure_connector.py b/tests/v1/storage_backend/test_azure_connector.py
new file mode 100644
index 0000000..32043f9
--- /dev/null
+++ b/tests/v1/storage_backend/test_azure_connector.py
@@ -0,0 +1,327 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the native Azure Blob Storage connector.
+
+The ``azure-storage-blob`` / ``azure-identity`` SDKs are mocked at the
+``sys.modules`` level so these tests run anywhere (including CPU-only / M1
+machines) without the real packages installed.
+"""
+
+# Standard
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+import asyncio
+import sys
+import threading
+
+_original_sys_modules: dict[str, Any] = {}
+_mocked_modules = [
+    "azure",
+    "azure.core",
+    "azure.core.exceptions",
+    "azure.storage",
+    "azure.storage.blob",
+    "azure.storage.blob.aio",
+    "azure.identity",
+    "azure.identity.aio",
+]
+
+
+class MockResourceNotFoundError(Exception):
+    pass
+
+
+# ---- build the mock azure package tree -------------------------------------
+mock_exceptions = MagicMock()
+mock_exceptions.ResourceNotFoundError = MockResourceNotFoundError
+
+# The BlobServiceClient class mock. Both the constructor and
+# from_connection_string return the same configurable service-client instance
+# so tests can reach in via ``BlobServiceClient.return_value``.
+mock_blob_service_cls = MagicMock(name="BlobServiceClient")
+mock_blob_service_cls.from_connection_string.return_value = (
+    mock_blob_service_cls.return_value
+)
+
+mock_aio = MagicMock()
+mock_aio.BlobServiceClient = mock_blob_service_cls
+
+mock_identity_aio = MagicMock()
+mock_identity_aio.DefaultAzureCredential = MagicMock(name="DefaultAzureCredential")
+
+# Third Party
+import pytest  # noqa: E402
+import torch  # noqa: E402
+
+# First Party
+from lmcache.utils import CacheEngineKey  # noqa: E402
+from lmcache.v1.config import LMCacheEngineConfig  # noqa: E402
+from lmcache.v1.memory_management import MemoryObj  # noqa: E402
+from lmcache.v1.metadata import LMCacheMetadata  # noqa: E402
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend  # noqa: E402
+
+
+@pytest.fixture(scope="module", autouse=True)
+def mock_azure_sdk():
+    # Backup and inject mocks
+    for name in _mocked_modules:
+        if name in sys.modules:
+            _original_sys_modules[name] = sys.modules[name]
+    sys.modules["azure"] = MagicMock()
+    sys.modules["azure.core"] = MagicMock()
+    sys.modules["azure.core.exceptions"] = mock_exceptions
+    sys.modules["azure.storage"] = MagicMock()
+    sys.modules["azure.storage.blob"] = MagicMock()
+    sys.modules["azure.storage.blob.aio"] = mock_aio
+    sys.modules["azure.identity"] = MagicMock()
+    sys.modules["azure.identity.aio"] = mock_identity_aio
+
+    yield
+
+    # Restore
+    for name in _mocked_modules:
+        if name in _original_sys_modules:
+            sys.modules[name] = _original_sys_modules[name]
+        elif name in sys.modules:
+            del sys.modules[name]
+
+
+# Imported after the SDK is mocked so the lazy imports resolve to the mocks.
+@pytest.fixture(scope="module")
+def AzureConnector(mock_azure_sdk):
+    # First Party
+    from lmcache.v1.storage_backend.connector.azure_connector import (
+        AzureConnector as _AzureConnector,
+    )
+
+    return _AzureConnector
+
+
+CONN_STR = (
+    "DefaultEndpointsProtocol=https;AccountName=test;"
+    "AccountKey=Zm9v;EndpointSuffix=core.windows.net"
+)
+
+
+def create_test_metadata(kv_shape=(1, 2, 16, 8, 128), chunk_size=16):
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+        chunk_size=chunk_size,
+    )
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+@pytest.fixture
+def async_loop():
+    loop = asyncio.new_event_loop()
+    # First Party
+    from lmcache.utils import start_loop_in_thread_with_exceptions
+
+    thread = threading.Thread(
+        target=start_loop_in_thread_with_exceptions,
+        args=(loop,),
+        name="test-azure-loop",
+    )
+    thread.start()
+    yield loop
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=5.0)
+
+
+@pytest.fixture
+def local_cpu_backend(memory_allocator):
+    config = LMCacheEngineConfig.from_legacy(chunk_size=16)
+    metadata = create_test_metadata()
+    return LocalCPUBackend(config, metadata, memory_allocator=memory_allocator)
+
+
+def run(loop, coro):
+    return asyncio.run_coroutine_threadsafe(coro, loop).result()
+
+
+def make_connector(AzureConnector, async_loop, local_cpu_backend, **kwargs):
+    """Build a connector wired to a fresh mock container/blob client tree."""
+    container_client = MagicMock(name="container_client")
+    blob_client = MagicMock(name="blob_client")
+    container_client.get_blob_client.return_value = blob_client
+
+    service = mock_blob_service_cls.return_value
+    service.get_container_client.return_value = container_client
+    service.close = AsyncMock()
+
+    connector = AzureConnector(
+        container="test-container",
+        loop=async_loop,
+        local_cpu_backend=local_cpu_backend,
+        connection_string=CONN_STR,
+        **kwargs,
+    )
+    return connector, container_client, blob_client
+
+
+class TestAzureConnector:
+    def test_init_connection_string(
+        self, AzureConnector, async_loop, local_cpu_backend
+    ):
+        connector, _, _ = make_connector(AzureConnector, async_loop, local_cpu_backend)
+        mock_blob_service_cls.from_connection_string.assert_called_with(CONN_STR)
+        assert connector.container == "test-container"
+
+    def test_init_account_key(self, AzureConnector, async_loop, local_cpu_backend):
+        mock_blob_service_cls.reset_mock()
+        connector = AzureConnector(
+            container="c",
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            account_url="https://acct.blob.core.windows.net",
+            account_key="secret-key",
+        )
+        mock_blob_service_cls.assert_called_once()
+        _, kwargs = mock_blob_service_cls.call_args
+        assert kwargs["account_url"] == "https://acct.blob.core.windows.net"
+        assert kwargs["credential"] == "secret-key"
+        assert connector.container == "c"
+
+    def test_exists_hit(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        blob_client.get_blob_properties = AsyncMock(
+            return_value=MagicMock(size=connector.full_chunk_size_bytes)
+        )
+        key = create_test_key(1)
+        assert run(async_loop, connector.exists(key)) is True
+        # Second call should hit the size cache (no extra SDK call).
+        assert run(async_loop, connector.exists(key)) is True
+        blob_client.get_blob_properties.assert_called_once()
+
+    def test_exists_miss(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        blob_client.get_blob_properties = AsyncMock(
+            side_effect=MockResourceNotFoundError("nope")
+        )
+        key = create_test_key(2)
+        assert run(async_loop, connector.exists(key)) is False
+
+    def test_get_hit(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        size = connector.full_chunk_size_bytes
+        payload = bytes(range(256)) * (size // 256) + bytes(size % 256)
+        blob_client.get_blob_properties = AsyncMock(return_value=MagicMock(size=size))
+
+        async def fake_readinto(buf):
+            mv = memoryview(buf).cast("B")
+            mv[: len(payload)] = payload[: len(mv)]
+            return len(payload)
+
+        downloader = MagicMock()
+        downloader.readinto = AsyncMock(side_effect=fake_readinto)
+        blob_client.download_blob = AsyncMock(return_value=downloader)
+
+        key = create_test_key(3)
+        res = run(async_loop, connector.get(key))
+        assert isinstance(res, MemoryObj)
+        assert bytes(res.byte_array)[: len(payload)] == payload[: len(res.byte_array)]
+        res.ref_count_down()
+
+    def test_get_miss_returns_none(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        blob_client.get_blob_properties = AsyncMock(
+            side_effect=MockResourceNotFoundError("nope")
+        )
+        key = create_test_key(4)
+        assert run(async_loop, connector.get(key)) is None
+
+    def test_get_size_mismatch_returns_none(
+        self, AzureConnector, async_loop, local_cpu_backend
+    ):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        # Report a wrong size -> connector must reject and not download.
+        blob_client.get_blob_properties = AsyncMock(
+            return_value=MagicMock(size=connector.full_chunk_size_bytes + 8)
+        )
+        blob_client.download_blob = AsyncMock()
+        key = create_test_key(5)
+        assert run(async_loop, connector.get(key)) is None
+        blob_client.download_blob.assert_not_called()
+
+    def test_put(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        blob_client.upload_blob = AsyncMock()
+
+        # Allocate a full chunk via the backend (same path get() uses); its
+        # physical size matches the connector's expected part size.
+        memory_obj = local_cpu_backend.allocate(
+            connector.meta_shapes,
+            connector.meta_dtypes,
+            connector.meta_fmt,
+        )
+        assert memory_obj.get_physical_size() == connector.part_size
+
+        key = create_test_key(6)
+        run(async_loop, connector.put(key, memory_obj))
+
+        blob_client.upload_blob.assert_called_once()
+        _, kwargs = blob_client.upload_blob.call_args
+        assert kwargs.get("overwrite") is True
+        memory_obj.ref_count_down()
+
+    def test_put_size_mismatch_skips(
+        self, AzureConnector, async_loop, local_cpu_backend
+    ):
+        connector, _, blob_client = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+        blob_client.upload_blob = AsyncMock()
+
+        memory_obj = MagicMock()
+        memory_obj.get_physical_size.return_value = connector.part_size + 1
+
+        key = create_test_key(7)
+        run(async_loop, connector.put(key, memory_obj))
+        blob_client.upload_blob.assert_not_called()
+
+    def test_list(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, container_client, _ = make_connector(
+            AzureConnector, async_loop, local_cpu_backend
+        )
+
+        async def fake_list_blobs():
+            for name in ["blob_a", "blob_b"]:
+                # ``name`` is reserved by MagicMock's constructor; set it after.
+                blob = MagicMock()
+                blob.name = name
+                yield blob
+
+        container_client.list_blobs = MagicMock(side_effect=fake_list_blobs)
+        res = run(async_loop, connector.list())
+        assert res == ["blob_a", "blob_b"]
+
+    def test_close(self, AzureConnector, async_loop, local_cpu_backend):
+        connector, _, _ = make_connector(AzureConnector, async_loop, local_cpu_backend)
+        run(async_loop, connector.close())
+        connector.service_client.close.assert_called_once()
diff --git a/tests/v1/storage_backend/test_batched_message_sender.py b/tests/v1/storage_backend/test_batched_message_sender.py
new file mode 100644
index 0000000..a9db609
--- /dev/null
+++ b/tests/v1/storage_backend/test_batched_message_sender.py
@@ -0,0 +1,421 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import gc
+import threading
+import time
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.cache_controller.message import OpType
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.storage_backend.batched_message_sender import (
+    BatchedMessageSender,
+)
+
+
+class MockLookupServer:
+    def __init__(self):
+        self.removed_keys = []
+        self.inserted_keys = []
+
+    def batched_remove(self, keys):
+        self.removed_keys.extend(keys)
+
+    def batched_insert(self, keys):
+        self.inserted_keys.extend(keys)
+
+
+class MockLMCacheWorker:
+    def __init__(self):
+        self.messages = []
+        self._lock = threading.Lock()
+
+    def put_msg(self, msg):
+        with self._lock:
+            self.messages.append(msg)
+
+
+def create_test_config(
+    local_cpu: bool = True, use_layerwise: bool = False, enable_blending: bool = False
+):
+    """Create a test configuration for LocalCPUBackend."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=local_cpu,
+        use_layerwise=use_layerwise,
+        enable_blending=enable_blending,
+        lmcache_instance_id="test_instance",
+    )
+    return config
+
+
+def create_test_key(key_id: str = "test_key") -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+class TestBatchedMessageSender:
+    """Test cases for BatchedMessageSender."""
+
+    def teardown_method(self, method):
+        # Clean up any lingering BatchedMessageSender instances
+        for obj in gc.get_objects():
+            if isinstance(obj, BatchedMessageSender) and hasattr(obj, "running"):
+                obj.close()
+
+        LMCStatsMonitor.unregister_all_metrics()
+        LMCStatsMonitor.DestroyInstance()
+
+    def test_basic_batching(self, lmcache_engine_metadata):
+        """Test basic message batching functionality."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 3
+        config.extra_config["kv_msg_batch_timeout"] = 0.1
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        # Add operations below batch size threshold
+        sender.add_kv_op(OpType.ADMIT, 1)
+        sender.add_kv_op(OpType.ADMIT, 2)
+
+        # Should not have sent messages yet
+        assert len(lmcache_worker.messages) == 0
+
+        # Add one more to reach batch size
+        sender.add_kv_op(OpType.ADMIT, 3)
+
+        # Give some time for the message to be sent
+        time.sleep(0.05)
+
+        # Should have sent one batched message
+        assert len(lmcache_worker.messages) == 1
+        msg = lmcache_worker.messages[0]
+        assert len(msg.operations) == 3
+
+        sender.close()
+
+    def test_timeout_based_flush(self, lmcache_engine_metadata):
+        """Test that messages are flushed based on timeout."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 100
+        config.extra_config["kv_msg_batch_timeout"] = 0.05
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        # Add a few operations (below batch size)
+        sender.add_kv_op(OpType.ADMIT, 1)
+        sender.add_kv_op(OpType.EVICT, 2)
+
+        # Wait for timeout to trigger flush
+        time.sleep(0.1)
+
+        # Should have sent messages due to timeout
+        assert len(lmcache_worker.messages) >= 1
+
+        sender.close()
+
+    def test_manual_flush(self, lmcache_engine_metadata):
+        """Test manual flush functionality."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 100
+        config.extra_config["kv_msg_batch_timeout"] = 10.0
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        # Add operations
+        sender.add_kv_op(OpType.ADMIT, 1)
+        sender.add_kv_op(OpType.EVICT, 2)
+
+        # Manually flush
+        sender.flush()
+
+        # Should have sent messages
+        assert len(lmcache_worker.messages) == 1
+        msg = lmcache_worker.messages[0]
+        assert len(msg.operations) == 2
+
+        sender.close()
+
+    def test_sequence_numbers(self, lmcache_engine_metadata):
+        """Test that sequence numbers are monotonically increasing."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 10
+        config.extra_config["kv_msg_batch_timeout"] = 0.1
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        # Add multiple operations
+        for i in range(15):
+            sender.add_kv_op(OpType.ADMIT, i)
+
+        sender.flush()
+
+        # Collect all sequence numbers
+        seq_nums = []
+        for msg in lmcache_worker.messages:
+            for op in msg.operations:
+                seq_nums.append(op.seq_num)
+
+        # Verify sequence numbers are strictly consecutive
+        # Since we have a single consumer thread, messages must arrive in order
+        assert seq_nums == list(range(len(seq_nums))), (
+            "Sequence numbers must be consecutive starting from 0"
+        )
+
+        sender.close()
+
+    def test_concurrent_producers(self, lmcache_engine_metadata):
+        """Stress test with multiple producer threads."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 50
+        config.extra_config["kv_msg_batch_timeout"] = 0.01
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        num_threads = 10
+        ops_per_thread = 100
+
+        def producer_task(thread_id):
+            for i in range(ops_per_thread):
+                key = thread_id * ops_per_thread + i
+                sender.add_kv_op(OpType.ADMIT, key)
+
+        threads = [
+            threading.Thread(target=producer_task, args=(i,))
+            for i in range(num_threads)
+        ]
+
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join()
+
+        # Flush remaining messages
+        sender.flush()
+
+        # Collect all operations
+        all_ops = []
+        for msg in lmcache_worker.messages:
+            all_ops.extend(msg.operations)
+
+        # Verify total number of operations
+        assert len(all_ops) == num_threads * ops_per_thread
+
+        # Verify sequence numbers are strictly increasing within each batch
+        # Since sequence numbers are assigned during drain (not add_kv_op),
+        # the order in which operations are dequeued determines their
+        # sequence numbers. This guarantees that within each batch,
+        # sequence numbers are strictly increasing.
+        seq_nums = [op.seq_num for op in all_ops]
+
+        # Verify no duplicate sequence numbers
+        assert len(seq_nums) == len(set(seq_nums)), "Sequence numbers must be unique"
+
+        # Verify all sequence numbers are present (no messages lost)
+        expected_seq_nums = set(range(num_threads * ops_per_thread))
+        actual_seq_nums = set(seq_nums)
+        assert expected_seq_nums == actual_seq_nums, (
+            f"Missing sequence numbers: {expected_seq_nums - actual_seq_nums}"
+        )
+
+        # Verify sequence numbers are strictly increasing within each batch
+        for msg in lmcache_worker.messages:
+            batch_seq_nums = [op.seq_num for op in msg.operations]
+            for i in range(1, len(batch_seq_nums)):
+                assert batch_seq_nums[i] > batch_seq_nums[i - 1], (
+                    f"Sequence numbers must be strictly increasing within batch: "
+                    f"{batch_seq_nums[i - 1]} -> {batch_seq_nums[i]}"
+                )
+
+        sender.close()
+
+    def test_mixed_operations_order(self, lmcache_engine_metadata):
+        """Test that admit and evict operations maintain order."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 100
+        config.extra_config["kv_msg_batch_timeout"] = 0.1
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        # Add operations in specific order
+        operations = [
+            (OpType.ADMIT, 1),
+            (OpType.EVICT, 1),
+            (OpType.ADMIT, 1),
+            (OpType.ADMIT, 2),
+            (OpType.EVICT, 2),
+        ]
+
+        for op_type, key in operations:
+            sender.add_kv_op(op_type, key)
+
+        sender.flush()
+
+        # Collect all operations
+        all_ops = []
+        for msg in lmcache_worker.messages:
+            all_ops.extend(msg.operations)
+
+        # Verify operations are in the same order
+        assert len(all_ops) == len(operations)
+        for i, (expected_op_type, expected_key) in enumerate(operations):
+            assert all_ops[i].op_type == expected_op_type
+            assert all_ops[i].key == expected_key
+
+        sender.close()
+
+    def test_high_throughput_stress(self, lmcache_engine_metadata):
+        """Stress test with high throughput operations."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 100
+        config.extra_config["kv_msg_batch_timeout"] = 0.01
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        num_operations = 10000
+
+        # Add many operations rapidly
+        for i in range(num_operations):
+            op_type = OpType.ADMIT if i % 2 == 0 else OpType.EVICT
+            sender.add_kv_op(op_type, i)
+
+        sender.flush()
+
+        # Collect all operations
+        all_ops = []
+        for msg in lmcache_worker.messages:
+            all_ops.extend(msg.operations)
+
+        # Verify all operations were sent
+        assert len(all_ops) == num_operations
+
+        # Verify sequence numbers are strictly increasing
+        # In a concurrent environment, we need to ensure that:
+        # 1. Sequence numbers are strictly increasing within each batch
+        # 2. No sequence numbers are duplicated
+        # 3. All sequence numbers from 0 to num_operations-1 are present
+
+        seq_nums = [op.seq_num for op in all_ops]
+
+        # Verify no duplicate sequence numbers
+        assert len(seq_nums) == len(set(seq_nums)), "Sequence numbers must be unique"
+
+        # Verify all sequence numbers are present (no messages lost)
+        expected_seq_nums = set(range(num_operations))
+        actual_seq_nums = set(seq_nums)
+        assert expected_seq_nums == actual_seq_nums, (
+            f"Missing sequence numbers: {expected_seq_nums - actual_seq_nums}"
+        )
+
+        # Verify sequence numbers are strictly increasing within each batch
+        # Since we have a single consumer thread, each batch should be processed
+        # in the order it was created, and within each batch, messages should be
+        # in the order they were added to the queue.
+        for msg in lmcache_worker.messages:
+            batch_seq_nums = [op.seq_num for op in msg.operations]
+            for i in range(1, len(batch_seq_nums)):
+                assert batch_seq_nums[i] > batch_seq_nums[i - 1], (
+                    f"Sequence numbers must be strictly increasing within batch: "
+                    f"{batch_seq_nums[i - 1]} -> {batch_seq_nums[i]}"
+                )
+
+        sender.close()
+
+    def test_close_with_pending_messages(self, lmcache_engine_metadata):
+        """Test that close() flushes pending messages."""
+
+        config = create_test_config()
+        config.extra_config = {}
+        config.extra_config["kv_msg_batch_size"] = 100
+        config.extra_config["kv_msg_batch_timeout"] = 10.0
+
+        lmcache_worker = MockLMCacheWorker()
+        sender = BatchedMessageSender(
+            metadata=lmcache_engine_metadata,
+            config=config,
+            location="test_location",
+            lmcache_worker=lmcache_worker,
+        )
+
+        # Add operations
+        sender.add_kv_op(OpType.ADMIT, 1)
+        sender.add_kv_op(OpType.EVICT, 2)
+
+        # Close should flush pending messages
+        sender.close()
+
+        # Should have sent messages
+        assert len(lmcache_worker.messages) >= 1
+
+        # Collect all operations
+        all_ops = []
+        for msg in lmcache_worker.messages:
+            all_ops.extend(msg.operations)
+
+        assert len(all_ops) == 2
diff --git a/tests/v1/storage_backend/test_bigtable_connector.py b/tests/v1/storage_backend/test_bigtable_connector.py
new file mode 100644
index 0000000..f4876ea
--- /dev/null
+++ b/tests/v1/storage_backend/test_bigtable_connector.py
@@ -0,0 +1,981 @@
+# SPDX-License-Identifier: Apache-2.0
+# Backup original state of sys.modules and google package attributes
+
+# Standard
+from typing import Any
+from unittest.mock import ANY, AsyncMock, MagicMock, patch
+import asyncio
+import sys
+
+_original_sys_modules: dict[str, Any] = {}
+_original_google_attrs: dict[str, Any] = {}
+_mocked_modules = [
+    "google.api_core",
+    "google.api_core.exceptions",
+    "google.api_core.gapic_v1",
+    "google.api_core.gapic_v1.client_info",
+    "google.cloud",
+    "google.cloud.bigtable",
+    "google.cloud.bigtable.row_filters",
+    "google.cloud.bigtable.data",
+    "google.cloud.bigtable.data.row_filters",
+    "google.oauth2",
+    "google.oauth2.service_account",
+]
+
+
+class MockDeadlineExceeded(Exception):
+    pass
+
+
+class MockPermissionDenied(Exception):
+    pass
+
+
+class MockNotFound(Exception):
+    pass
+
+
+class MockResourceExhausted(Exception):
+    pass
+
+
+# Setup mock google packages before any test runs
+mock_exceptions = MagicMock()
+mock_exceptions.DeadlineExceeded = MockDeadlineExceeded
+mock_exceptions.Timeout = MockDeadlineExceeded
+mock_exceptions.PermissionDenied = MockPermissionDenied
+mock_exceptions.Unauthenticated = MockPermissionDenied
+mock_exceptions.NotFound = MockNotFound
+mock_exceptions.ResourceExhausted = MockResourceExhausted
+
+mock_row_filters = MagicMock()
+mock_row_filters.StripValueTransformerFilter.return_value = MagicMock()
+
+mock_data = MagicMock()
+mock_data.BigtableDataClientAsync = MagicMock()
+
+
+def fake_client_constructor(*args, **kwargs):
+    client = mock_data.BigtableDataClientAsync.return_value
+    if isinstance(client, MagicMock):
+        client.get_table.return_value = client
+    return client
+
+
+mock_data.BigtableDataClientAsync.side_effect = fake_client_constructor
+
+mock_data.ReadRowsQuery = MagicMock()
+mock_data.RowMutationEntry = MagicMock()
+mock_data.row_filters = mock_row_filters
+
+mock_bigtable = MagicMock(data=mock_data, row_filters=mock_row_filters)
+
+mock_service_account = MagicMock()
+mock_oauth2 = MagicMock(service_account=mock_service_account)
+
+mock_api_core = MagicMock(exceptions=mock_exceptions)
+mock_gapic = MagicMock()
+mock_cloud = MagicMock(bigtable=mock_bigtable)
+
+# Third Party
+import pytest  # noqa: E402
+import torch  # noqa: E402
+
+# First Party
+from lmcache.utils import CacheEngineKey  # noqa: E402
+from lmcache.v1.config import LMCacheEngineConfig  # noqa: E402
+from lmcache.v1.memory_management import MemoryObj  # noqa: E402
+from lmcache.v1.metadata import LMCacheMetadata  # noqa: E402
+from lmcache.v1.storage_backend.connector.bigtable_connector import (  # noqa: E402
+    BigtableConnector,
+)
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend  # noqa: E402
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend  # noqa: E402
+from tests.v1.utils import create_test_memory_obj  # noqa: E402
+
+
+@pytest.fixture(scope="module", autouse=True)
+def cleanup_google_mocks():
+    print("\n[Fixture] cleanup_google_mocks: running setup...")
+    # 1. Backup original state
+    for name in _mocked_modules:
+        if name in sys.modules:
+            _original_sys_modules[name] = sys.modules[name]
+    if "google" in sys.modules:
+        google_mod = sys.modules["google"]
+        for attr in ["oauth2", "cloud", "api_core"]:
+            if hasattr(google_mod, attr):
+                _original_google_attrs[attr] = getattr(google_mod, attr)
+
+    # 2. Inject mocks
+    sys.modules["google.api_core"] = mock_api_core
+    sys.modules["google.api_core.exceptions"] = mock_exceptions
+    sys.modules["google.api_core.gapic_v1"] = mock_gapic
+    sys.modules["google.api_core.gapic_v1.client_info"] = MagicMock()
+
+    sys.modules["google.cloud"] = mock_cloud
+    sys.modules["google.cloud.bigtable"] = mock_bigtable
+    sys.modules["google.cloud.bigtable.row_filters"] = mock_row_filters
+    sys.modules["google.cloud.bigtable.data"] = mock_data
+    sys.modules["google.cloud.bigtable.data.row_filters"] = mock_row_filters
+
+    sys.modules["google.oauth2"] = mock_oauth2
+    sys.modules["google.oauth2.service_account"] = mock_service_account
+
+    if "google" in sys.modules:
+        google_mod = sys.modules["google"]
+        google_mod.oauth2 = mock_oauth2  # type: ignore[attr-defined]
+        google_mod.cloud = mock_cloud  # type: ignore[attr-defined]
+        google_mod.api_core = mock_api_core  # type: ignore[attr-defined]
+
+    if "google.cloud" in sys.modules:
+        sys.modules["google.cloud"].bigtable = mock_bigtable  # type: ignore[attr-defined]
+
+    if "google.oauth2" in sys.modules:
+        sys.modules["google.oauth2"].service_account = mock_service_account  # type: ignore[attr-defined]
+
+    if "google.api_core" in sys.modules:
+        sys.modules["google.api_core"].exceptions = mock_exceptions  # type: ignore[attr-defined]
+        sys.modules["google.api_core"].gapic_v1 = mock_gapic  # type: ignore[attr-defined]
+
+    yield
+    print("\n[Fixture] cleanup_google_mocks: running teardown/cleanup...")
+    # 1. Restore sys.modules
+    for name in _mocked_modules:
+        if name in _original_sys_modules:
+            print(f"  Restoring sys.modules[{name}]")
+            sys.modules[name] = _original_sys_modules[name]
+        elif name in sys.modules:
+            print(f"  Deleting sys.modules[{name}]")
+            del sys.modules[name]
+
+    # 2. Restore google module attributes
+    if "google" in sys.modules:
+        google_mod = sys.modules["google"]
+        for attr in ["oauth2", "cloud", "api_core"]:
+            if attr in _original_google_attrs:
+                print(f"  Restoring google.{attr}")
+                setattr(google_mod, attr, _original_google_attrs[attr])
+            elif hasattr(google_mod, attr):
+                print(f"  Deleting google.{attr}")
+                delattr(google_mod, attr)
+
+
+async def mock_async_gen(items):
+    for item in items:
+        yield item
+
+
+def create_test_config(extra_overrides=None):
+    extras = {
+        "bigtable_project_id": "test-project",
+        "bigtable_instance_id": "test-instance",
+        "bigtable_table_name": "test-table",
+        "bigtable_max_chunk_size_mb": 90.0,
+        "bigtable_max_retries": 2,
+        "bigtable_exists_cache_ttl_seconds": 10.0,
+    }
+    if extra_overrides:
+        extras.update(extra_overrides)
+
+    return LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        remote_storage_plugins=["bigtable"],
+        remote_serde="naive",
+        lmcache_instance_id="test_instance",
+        extra_config=extras,
+    )
+
+
+def create_test_metadata(kv_shape=(28, 2, 256, 8, 128), chunk_size=256):
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+        chunk_size=chunk_size,
+    )
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+@pytest.fixture
+def async_loop():
+    loop = asyncio.new_event_loop()
+    # Standard
+    import threading
+
+    # First Party
+    from lmcache.utils import start_loop_in_thread_with_exceptions
+
+    thread = threading.Thread(
+        target=start_loop_in_thread_with_exceptions,
+        args=(loop,),
+        name="test-async-loop",
+    )
+    thread.start()
+    yield loop
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=5.0)
+
+
+@pytest.fixture
+def local_cpu_backend(memory_allocator):
+    config = LMCacheEngineConfig.from_legacy(chunk_size=256)
+    metadata = create_test_metadata()
+    return LocalCPUBackend(config, metadata, memory_allocator=memory_allocator)
+
+
+@pytest.fixture(autouse=True)
+def mock_pq_executor():
+    # Patch AsyncPQExecutor so it doesn't spawn real thread workers during unit tests,
+    # but still executes jobs inline when submit_job is called.
+    with patch(
+        "lmcache.v1.storage_backend.connector.bigtable_connector.AsyncPQExecutor"
+    ) as mock:
+        instance = MagicMock()
+
+        async def fake_submit_job(fn, *args, **kwargs):
+            kwargs.pop("priority", None)
+            return await fn(*args, **kwargs)
+
+        instance.submit_job = AsyncMock(side_effect=fake_submit_job)
+        instance.shutdown_async = AsyncMock()
+        instance.shutdown = MagicMock()
+        mock.return_value = instance
+        yield mock
+
+
+class TestBigtableConnector:
+    def test_init_and_lazy_pool(self, async_loop, local_cpu_backend):
+        """Verify independent lazy async client pool initialization."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.read_row = AsyncMock(return_value=None)
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        assert isinstance(connector, BigtableConnector)
+        assert connector.cfg.project_id == "test-project"
+        assert connector.cfg.instance_id == "test-instance"
+        assert connector.cfg.table_name == "test-table"
+
+        # Client pool should not be initialized yet (lazy)
+        assert connector._client is None
+
+        # Trigger first operation
+        key = create_test_key(1)
+
+        assert not backend.contains(key)
+        # Pool now initialized
+        assert connector._client is not None
+        mock_data.BigtableDataClientAsync.assert_called_once_with(
+            project="test-project", client_info=ANY
+        )
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_out_of_tree_plugin_init(self, async_loop, local_cpu_backend):
+        """Verify standalone out-of-tree plugin initialization via
+        class_name/module_path.
+        """
+        config = create_test_config(
+            {
+                "remote_storage_plugin.bigtable.module_path": "lmc_bigtable_connector",
+                "remote_storage_plugin.bigtable.class_name": "BigtableConnector",
+                "bigtable_project_id": "ext-project",
+                "bigtable_instance_id": "ext-instance",
+                "bigtable_table_name": "ext-table",
+            }
+        )
+        metadata = create_test_metadata()
+
+        mock_plugin_module = MagicMock()
+        mock_plugin_module.BigtableConnector = BigtableConnector
+        sys.modules["lmc_bigtable_connector"] = mock_plugin_module
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        assert connector.__class__.__name__ == "BigtableConnector"
+        assert connector.cfg.project_id == "ext-project"
+        assert connector.cfg.instance_id == "ext-instance"
+        assert connector.cfg.table_name == "ext-table"
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_credentials_path_init(self, async_loop, local_cpu_backend):
+        """Verify passing credentials_path initializes client with
+        explicit service account.
+        """
+        config = create_test_config(
+            {"bigtable_credentials_path": "/path/to/creds.json"}
+        )
+        metadata = create_test_metadata()
+
+        mock_creds = MagicMock()
+        mock_service_account.Credentials.from_service_account_file.return_value = (
+            mock_creds
+        )
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        connector._get_client()
+
+        mock_service_account.Credentials.from_service_account_file.assert_called_once_with(
+            "/path/to/creds.json"
+        )
+        mock_data.BigtableDataClientAsync.assert_called_with(
+            project="test-project", credentials=mock_creds, client_info=ANY
+        )
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_custom_row_key_template(self, async_loop, local_cpu_backend):
+        """Verify substituting {model} and {hash} placeholders flexibly."""
+        config = create_test_config({"bigtable_row_key_template": "{model}#{hash}"})
+        metadata = create_test_metadata()
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(123)
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        row_key = connector.schema.get_row_key(key)
+        row_key_str = row_key.decode("utf-8")
+
+        assert row_key_str.startswith("test_model@3@1@bfloat16#")
+        assert row_key_str.endswith(key.chunk_hash_hex)
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_local_ttl_cache_hits(self, async_loop, local_cpu_backend):
+        """Verify that exists calls accelerate via local TTL cache
+        without hitting Bigtable.
+        """
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.read_row = AsyncMock(return_value=MagicMock())
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(1)
+
+        assert backend.contains(key)
+        assert mock_client_instance.read_row.call_count == 1
+
+        assert backend.contains(key)
+        assert mock_client_instance.read_row.call_count == 1
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_get_blocking_hit(self, async_loop, local_cpu_backend):
+        config = create_test_config()
+        metadata = create_test_metadata(kv_shape=(1, 2, 16, 8, 128), chunk_size=16)
+        local_cpu_backend.metadata = metadata
+
+        memory_obj = create_test_memory_obj()
+        expected_bytes = bytes(memory_obj.byte_array)
+
+        mock_cell = MagicMock(value=expected_bytes)
+        mock_row = MagicMock()
+        mock_row.cells = {"cf": {b"data": [mock_cell]}}
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.read_row = AsyncMock(return_value=mock_row)
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(1)
+
+        res = backend.get_blocking(key)
+        assert res is not None
+        assert isinstance(res, MemoryObj)
+        assert bytes(res.byte_array)[: len(expected_bytes)] == expected_bytes
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        assert connector.exists_cache.get(key.to_string()) is True
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_cell_size_validation_skips_large_writes(
+        self, async_loop, local_cpu_backend
+    ):
+        """Validate chunk size at write time. Skips > 90MB rather than failing."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.mutate_row = AsyncMock()
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(1)
+        large_view = bytearray(95 * 1024 * 1024)
+        mock_memory_obj = MagicMock()
+        mock_memory_obj.byte_array = large_view
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        asyncio.run_coroutine_threadsafe(
+            connector._put_internal(key, mock_memory_obj),
+            async_loop,
+        ).result()
+
+        mock_client_instance.mutate_row.assert_not_called()
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_error_handling_timeouts_as_miss(self, async_loop, local_cpu_backend):
+        """TimeoutError / DeadlineExceeded treated as cache miss and fall through."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.read_row = AsyncMock(
+            side_effect=MockDeadlineExceeded("timeout")
+        )
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(1)
+
+        assert not backend.contains(key)
+
+        res = backend.get_blocking(key)
+        assert res is None
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_error_handling_auth_raises(self, async_loop, local_cpu_backend):
+        """PermissionDenied / Unauthenticated propagate up."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.read_row = AsyncMock(
+            side_effect=MockPermissionDenied("auth error")
+        )
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(1)
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        with pytest.raises(MockPermissionDenied):
+            asyncio.run_coroutine_threadsafe(connector.exists(key), async_loop).result()
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_batched_get(self, async_loop, local_cpu_backend):
+        """Verify batched_get retrieves multiple memory objects cleanly."""
+        config = create_test_config()
+        metadata = create_test_metadata(kv_shape=(1, 2, 16, 8, 128), chunk_size=16)
+        local_cpu_backend.metadata = metadata
+
+        memory_obj1 = create_test_memory_obj()
+        memory_obj2 = create_test_memory_obj()
+        bytes1 = bytes(memory_obj1.byte_array)
+        bytes2 = bytes(memory_obj2.byte_array)
+
+        mock_client_instance = MagicMock()
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key1 = create_test_key(1)
+        key2 = create_test_key(2)
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        row_key1 = connector.schema.get_row_key(key1)
+        row_key2 = connector.schema.get_row_key(key2)
+
+        mock_cell1 = MagicMock(value=bytes1)
+        mock_cell2 = MagicMock(value=bytes2)
+        mock_row1 = MagicMock(row_key=row_key1)
+        mock_row2 = MagicMock(row_key=row_key2)
+        mock_row1.cells = {"cf": {b"data": [mock_cell1]}}
+        mock_row2.cells = {"cf": {b"data": [mock_cell2]}}
+        mock_client_instance.read_rows = AsyncMock(return_value=[mock_row1, mock_row2])
+
+        res = asyncio.run_coroutine_threadsafe(
+            backend.connection.batched_get([key1, key2]),
+            async_loop,
+        ).result()
+
+        assert len(res) == 2
+        assert res[0] is not None and res[1] is not None
+        assert bytes(res[0].byte_array)[: len(bytes1)] == bytes1
+        assert bytes(res[1].byte_array)[: len(bytes2)] == bytes2
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_batched_put(self, async_loop, local_cpu_backend):
+        """Verify batched_put packs mutations and sends bulk mutate rows cleanly."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.bulk_mutate_rows = AsyncMock()
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key1 = create_test_key(1)
+        key2 = create_test_key(2)
+        memory_obj1 = create_test_memory_obj()
+        memory_obj2 = create_test_memory_obj()
+
+        asyncio.run_coroutine_threadsafe(
+            backend.connection.batched_put([key1, key2], [memory_obj1, memory_obj2]),
+            async_loop,
+        ).result()
+
+        mock_client_instance.bulk_mutate_rows.assert_called_once()
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_batched_async_contains(self, async_loop, local_cpu_backend):
+        """Verify batched_async_contains returns correct match counts."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key1 = create_test_key(1)
+        key2 = create_test_key(2)
+
+        connector = (
+            backend.connection._connector
+            if hasattr(backend.connection, "_connector")
+            else backend.connection
+        )
+        row_key1 = connector.schema.get_row_key(key1)
+        mock_row = MagicMock(row_key=row_key1)
+        mock_client_instance.read_rows = AsyncMock(return_value=[mock_row])
+
+        res = asyncio.run_coroutine_threadsafe(
+            backend.connection.batched_async_contains("test", [key1, key2]),
+            async_loop,
+        ).result()
+
+        # Only key1 rowkey starts with matched row_key
+        # from read_rows, so match count is 1
+        assert res == 1
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_remove_sync(self, async_loop, local_cpu_backend):
+        """Verify remove_sync issues DeleteAllFromRow mutation cleanly."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.mutate_row = AsyncMock()
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = create_test_key(1)
+        res = backend.connection.remove_sync(key)
+
+        assert res is True
+        # Wait up to 1 second for background deletion task to execute
+        # Standard
+        import time
+
+        for _ in range(100):
+            if mock_client_instance.mutate_row.call_count == 1:
+                break
+            time.sleep(0.01)
+        mock_client_instance.mutate_row.assert_called_once()
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_list(self, async_loop, local_cpu_backend):
+        """Verify list() returns parsed standardized LMCache key metadata formats."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        mock_row1 = MagicMock(row_key=b"hash1#test_model@3@1@bfloat16")
+        mock_row2 = MagicMock(row_key=b"hash2#test_model@3@1@bfloat16")
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.read_rows = AsyncMock(return_value=[mock_row1, mock_row2])
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        res = asyncio.run_coroutine_threadsafe(
+            backend.connection.list(),
+            async_loop,
+        ).result()
+
+        assert len(res) == 2
+        assert "test_model@3@1@hash1@bfloat16" in res
+        assert "test_model@3@1@hash2@bfloat16" in res
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_ping(self, async_loop, local_cpu_backend):
+        """Verify ping executes SELECT 1; health queries cleanly."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        async def mock_query_iter():
+            yield MagicMock()
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.execute_query = AsyncMock(return_value=mock_query_iter())
+        mock_data.BigtableDataClientAsync.return_value = mock_client_instance
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        res = asyncio.run_coroutine_threadsafe(
+            backend.connection.ping(),
+            async_loop,
+        ).result()
+
+        assert res == 0
+        mock_client_instance.execute_query.assert_called_once()
+
+        backend.close()
+        local_cpu_backend.memory_allocator.close()
+
+    def test_get_client_credentials_success(self, async_loop, local_cpu_backend):
+        config = create_test_config(
+            extra_overrides={"bigtable_credentials_path": "/path/to/fake_creds.json"}
+        )
+        connector = BigtableConnector(async_loop, local_cpu_backend, config)
+
+        mock_creds = MagicMock()
+        with (
+            patch(
+                "google.oauth2.service_account.Credentials.from_service_account_file",
+                return_value=mock_creds,
+            ) as mock_from_file,
+            patch(
+                "google.cloud.bigtable.data.BigtableDataClientAsync"
+            ) as mock_client_cls,
+        ):
+            client = connector._get_client()
+
+            mock_from_file.assert_called_once_with("/path/to/fake_creds.json")
+            mock_client_cls.assert_called_once()
+            assert mock_client_cls.call_args[1]["credentials"] == mock_creds
+            assert mock_client_cls.call_args[1]["project"] == "test-project"
+            assert client == mock_client_cls.return_value
+
+    def test_get_client_credentials_os_error(self, async_loop, local_cpu_backend):
+        config = create_test_config(
+            extra_overrides={
+                "bigtable_credentials_path": "/path/to/permission_denied_creds.json"
+            }
+        )
+        connector = BigtableConnector(async_loop, local_cpu_backend, config)
+
+        with (
+            patch(
+                "google.oauth2.service_account.Credentials.from_service_account_file",
+                side_effect=PermissionError("Permission denied"),
+            ),
+            patch(
+                "google.cloud.bigtable.data.BigtableDataClientAsync"
+            ) as mock_client_cls,
+            patch(
+                "lmcache.v1.storage_backend.connector.bigtable_connector.logger.warning"
+            ) as mock_warning,
+        ):
+            client = connector._get_client()
+
+            mock_client_cls.assert_called_once()
+            assert (
+                "credentials" not in mock_client_cls.call_args[1]
+                or mock_client_cls.call_args[1]["credentials"] is None
+            )
+            assert mock_client_cls.call_args[1]["project"] == "test-project"
+
+            mock_warning.assert_called_once()
+            assert (
+                "Falling back to Application Default Credentials"
+                in mock_warning.call_args[0][0]
+            )
+            assert client == mock_client_cls.return_value
+
+    def test_get_client_credentials_value_error(self, async_loop, local_cpu_backend):
+        config = create_test_config(
+            extra_overrides={
+                "bigtable_credentials_path": "/path/to/corrupted_creds.json"
+            }
+        )
+        connector = BigtableConnector(async_loop, local_cpu_backend, config)
+
+        with (
+            patch(
+                "google.oauth2.service_account.Credentials.from_service_account_file",
+                side_effect=ValueError("Invalid JSON"),
+            ),
+            patch(
+                "google.cloud.bigtable.data.BigtableDataClientAsync"
+            ) as mock_client_cls,
+            patch(
+                "lmcache.v1.storage_backend.connector.bigtable_connector.logger.warning"
+            ) as mock_warning,
+        ):
+            client = connector._get_client()
+
+            mock_client_cls.assert_called_once()
+            assert (
+                "credentials" not in mock_client_cls.call_args[1]
+                or mock_client_cls.call_args[1]["credentials"] is None
+            )
+            assert mock_client_cls.call_args[1]["project"] == "test-project"
+
+            mock_warning.assert_called_once()
+            assert (
+                "Falling back to Application Default Credentials"
+                in mock_warning.call_args[0][0]
+            )
+            assert client == mock_client_cls.return_value
+
+    def test_get_client_credentials_auth_error(self, async_loop, local_cpu_backend):
+        config = create_test_config(
+            extra_overrides={"bigtable_credentials_path": "/path/to/expired_creds.json"}
+        )
+        connector = BigtableConnector(async_loop, local_cpu_backend, config)
+
+        # Third Party
+        import google.auth.exceptions
+
+        with (
+            patch(
+                "google.oauth2.service_account.Credentials.from_service_account_file",
+                side_effect=google.auth.exceptions.GoogleAuthError("Auth failed"),
+            ),
+            patch(
+                "google.cloud.bigtable.data.BigtableDataClientAsync"
+            ) as mock_client_cls,
+            patch(
+                "lmcache.v1.storage_backend.connector.bigtable_connector.logger.warning"
+            ) as mock_warning,
+        ):
+            client = connector._get_client()
+
+            mock_client_cls.assert_called_once()
+            assert (
+                "credentials" not in mock_client_cls.call_args[1]
+                or mock_client_cls.call_args[1]["credentials"] is None
+            )
+            assert mock_client_cls.call_args[1]["project"] == "test-project"
+
+            mock_warning.assert_called_once()
+            assert (
+                "Falling back to Application Default Credentials"
+                in mock_warning.call_args[0][0]
+            )
+            assert client == mock_client_cls.return_value
+
+    def test_bigtable_config_defaults(self):
+        """Verify that Bigtable configuration defaults are consistent."""
+        # First Party
+        from lmcache.v1.storage_backend.connector.bigtable_config import (
+            BigtablePluginConfig,
+        )
+
+        # Test defaults directly from class instantiation
+        config = BigtablePluginConfig(
+            project_id="test-project",
+            instance_id="test-instance",
+            table_name="test-table",
+        )
+        assert config.max_chunk_size_mb == 90.0
+        assert config.read_timeout_sec == 0.2
+        assert config.write_timeout_sec == 0.5
+        assert config.max_retries == 3
+
+        # Test defaults loaded via from_extra_config (no explicit overrides)
+        extra_config = {
+            "bigtable_project_id": "test-project",
+            "bigtable_instance_id": "test-instance",
+            "bigtable_table_name": "test-table",
+        }
+        loaded_config = BigtablePluginConfig.from_extra_config(extra_config)
+        assert loaded_config.max_chunk_size_mb == 90.0
+        assert loaded_config.read_timeout_sec == 0.2
+        assert loaded_config.write_timeout_sec == 0.5
+        assert loaded_config.max_retries == 3
diff --git a/tests/v1/storage_backend/test_bigtable_integration.py b/tests/v1/storage_backend/test_bigtable_integration.py
new file mode 100644
index 0000000..74705d1
--- /dev/null
+++ b/tests/v1/storage_backend/test_bigtable_integration.py
@@ -0,0 +1,281 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Samsung Electronics Co., Ltd. All Rights Reserved
+
+# Standard
+import asyncio
+import threading
+
+# Third Party
+from google.cloud.bigtable import Client
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+from tests.v1.utils import create_test_memory_obj
+
+
+# Simple test helpers
+def create_test_metadata(kv_shape=(2, 2, 256, 8, 128)):
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+        use_mla=False,
+        role="worker",
+    )
+
+
+def create_test_config(extra_overrides=None):
+    extras = {
+        "bigtable_project_id": "test-project",
+        "bigtable_instance_id": "test-instance",
+        "bigtable_table_name": "test-table",
+        "bigtable_family_name": "cf",
+        "bigtable_column_name": "data",
+        "bigtable_max_chunk_size_mb": 5.0,  # 5MB threshold for testing skip logic
+        "bigtable_max_retries": 2,
+    }
+    if extra_overrides:
+        extras.update(extra_overrides)
+
+    return LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        remote_storage_plugins=["bigtable"],
+        remote_serde="naive",
+        lmcache_instance_id="test_instance",
+        extra_config=extras,
+    )
+
+
+@pytest.fixture
+def async_loop():
+    loop = asyncio.new_event_loop()
+    # Standard
+    import threading
+
+    # First Party
+    from lmcache.utils import start_loop_in_thread_with_exceptions
+
+    thread = threading.Thread(
+        target=start_loop_in_thread_with_exceptions,
+        args=(loop,),
+        name="test-async-loop",
+    )
+    thread.start()
+    yield loop
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=5.0)
+
+
+@pytest.mark.integration
+class TestBigtableEmulatorIntegration:
+    @pytest.fixture(autouse=True)
+    def setup_emulator_table(self, bigtable_emulator):
+        """Prepare instance, table, and column family in the emulator."""
+        project_id = "test-project"
+        instance_id = "test-instance"
+        table_name = "test-table"
+        family_name = "cf"
+
+        # Initialize sync admin client using the emulator host
+        client = Client(project=project_id, admin=True)
+        instance = client.instance(instance_id)
+
+        table = instance.table(table_name)
+        try:
+            if table.exists():
+                table.delete()
+        except Exception:
+            pass
+
+        table.create()
+        cf = table.column_family(family_name)
+        cf.create()
+
+        yield
+
+        # Clean up table after each test
+        try:
+            if table.exists():
+                table.delete()
+        except Exception:
+            pass
+
+    @pytest.fixture
+    def memory_allocator(self):
+        alloc = MixedMemoryAllocator(100 * 1024 * 1024)  # 100MB
+        yield alloc
+        alloc.close()
+
+    @pytest.fixture
+    def local_cpu_backend(self, memory_allocator):
+        config = LMCacheEngineConfig.from_defaults(chunk_size=256)
+        metadata = create_test_metadata()
+        backend = LocalCPUBackend(config, metadata, memory_allocator=memory_allocator)
+        yield backend
+        backend.close()
+
+    def test_integration_put_and_get(self, async_loop, local_cpu_backend):
+        """Verify standard put and get of chunk bytes with emulator."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = CacheEngineKey("test_model", 0, 0, 256, torch.bfloat16)
+
+        # Use test helper to create concrete MemoryObj and fill it with values
+        memory_obj = create_test_memory_obj(
+            shape=torch.Size([2, 2, 256, 8, 128]), dtype=torch.bfloat16
+        )
+        memory_obj.tensor.fill_(3.14)
+
+        # Write asynchronously and wait for future
+        fut = backend.submit_put_task(key, memory_obj)
+        fut.result(timeout=5.0)
+
+        # Query contains
+        assert backend.contains(key)
+
+        # Read back using get_blocking (allocates automatically)
+        retrieved_obj = backend.get_blocking(key)
+        assert retrieved_obj is not None
+        assert torch.all(retrieved_obj.tensor == 3.14)
+
+        backend.close()
+
+    def test_integration_batched_put_and_get(self, async_loop, local_cpu_backend):
+        """Verify dynamic batching and batched operations with emulator."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        keys = [
+            CacheEngineKey("test_model", 0, i, 256, torch.bfloat16) for i in range(5)
+        ]
+
+        memory_objs = []
+        for i in range(5):
+            memory_obj = create_test_memory_obj(
+                shape=torch.Size([2, 2, 256, 8, 128]), dtype=torch.bfloat16
+            )
+            memory_obj.tensor.fill_(float(i))
+            memory_objs.append(memory_obj)
+
+        # Use threading events to wait for batched write completion
+        done_events = [threading.Event() for _ in range(5)]
+
+        def on_complete(key):
+            idx = keys.index(key)
+            done_events[idx].set()
+
+        # Batched Put
+        backend.batched_submit_put_task(
+            keys, memory_objs, on_complete_callback=on_complete
+        )
+
+        # Wait for all writes to finish
+        for ev in done_events:
+            assert ev.wait(timeout=10.0)
+
+        # Assert all keys are in backend
+        for key in keys:
+            assert backend.contains(key)
+
+        # Read all back using batched_get_blocking
+        retrieved_objs = backend.batched_get_blocking(keys)
+        assert len(retrieved_objs) == 5
+
+        for i in range(5):
+            assert retrieved_objs[i] is not None
+            assert torch.all(retrieved_objs[i].tensor == float(i))
+
+        backend.close()
+
+    def test_integration_remove(self, async_loop, local_cpu_backend):
+        """Verify deleting chunks from emulator works."""
+        config = create_test_config()
+        metadata = create_test_metadata()
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = CacheEngineKey("test_model", 0, 10, 256, torch.bfloat16)
+        memory_obj = create_test_memory_obj(
+            shape=torch.Size([2, 2, 256, 8, 128]), dtype=torch.bfloat16
+        )
+        memory_obj.tensor.fill_(1.0)
+
+        fut = backend.submit_put_task(key, memory_obj)
+        fut.result(timeout=5.0)
+        assert backend.contains(key)
+
+        # Remove
+        assert backend.remove(key)
+        assert not backend.contains(key)
+
+        backend.close()
+
+    def test_integration_skips_large_writes(self, async_loop, local_cpu_backend):
+        """Verify writing a chunk larger than max_chunk_size_mb is skipped
+        without failure.
+        """
+        config = create_test_config()  # Max size is 5.0 MB
+        metadata = create_test_metadata()
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="bigtable",
+        )
+
+        key = CacheEngineKey("test_model", 0, 99, 256, torch.bfloat16)
+
+        # Create a payload of ~8.38 MB (exceeds the 5.0 MB threshold)
+        # 8 * 2 * 256 * 8 * 128 * 2 bytes = 8,388,608 bytes
+        memory_obj = create_test_memory_obj(
+            shape=torch.Size([8, 2, 256, 8, 128]), dtype=torch.bfloat16
+        )
+
+        # Try to put and wait for it
+        fut = backend.submit_put_task(key, memory_obj)
+        fut.result(timeout=5.0)
+
+        # Verify it was NOT written (skips write)
+        assert not backend.contains(key)
+
+        backend.close()
diff --git a/tests/v1/storage_backend/test_dax_backend.py b/tests/v1/storage_backend/test_dax_backend.py
new file mode 100644
index 0000000..e3a1d49
--- /dev/null
+++ b/tests/v1/storage_backend/test_dax_backend.py
@@ -0,0 +1,2090 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from collections.abc import Generator
+from concurrent.futures import ThreadPoolExecutor
+import asyncio
+import os
+import tempfile
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.plugins.dax_backend import DaxBackend
+import lmcache.v1.storage_backend.plugins.dax_backend as dax_backend_module
+
+
+@pytest.fixture
+def loop_in_thread() -> Generator[asyncio.AbstractEventLoop]:
+    loop = asyncio.new_event_loop()
+    try:
+        yield loop
+    finally:
+        loop.close()
+
+
+def _create_metadata(
+    chunk_size: int = 16,
+    world_size: int = 1,
+    role: str = "worker",
+) -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=world_size,
+        local_world_size=world_size,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(2, 2, chunk_size, 2, 8),
+        role=role,
+    )
+
+
+def _create_multi_group_metadata(chunk_size: int = 16) -> LMCacheMetadata:
+    # First Party
+    import lmcache.c_ops as lmc_ops
+
+    metadata = _create_metadata(chunk_size=chunk_size)
+    # Two single-layer groups whose only differing signature field is
+    # head_size (8 vs 16), exercising the multi-group code path.
+    kv_caches = [
+        torch.empty(2, 1, chunk_size, 1, 8, dtype=torch.bfloat16),
+        torch.empty(2, 1, chunk_size, 1, 16, dtype=torch.bfloat16),
+    ]
+    metadata.kv_layer_groups_manager = KVLayerGroupsManager(
+        kv_caches,
+        [lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS] * len(kv_caches),
+    )
+    return metadata
+
+
+def _create_config(
+    *,
+    chunk_size: int = 16,
+    local_cpu: bool = True,
+    max_local_cpu_size: float = 0.1,
+    extra_config: dict | None = None,
+    storage_plugins: list[str] | None = None,
+) -> LMCacheEngineConfig:
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=chunk_size,
+        local_cpu=local_cpu,
+        max_local_cpu_size=max_local_cpu_size,
+        lmcache_instance_id="test_dax_backend",
+    )
+    merged_extra_config = {
+        "dax.restore_workers": 1,
+        "dax.restore_max_regions": 1,
+        "dax.retrieve_staging_slab_bytes": 8 * 1024 * 1024,
+    }
+    if extra_config is not None:
+        merged_extra_config.update(extra_config)
+    config.extra_config = merged_extra_config
+    if storage_plugins is not None:
+        config.storage_plugins = storage_plugins
+    return config
+
+
+def _allocate_kv_obj(
+    *,
+    num_tokens: int,
+    hidden_dim: int = 8,
+    fill_value: int = 0,
+) -> MemoryObj:
+    alloc = AdHocMemoryAllocator(device="cpu")
+    obj = alloc.allocate(
+        [torch.Size([2, num_tokens, hidden_dim])],
+        [torch.bfloat16],
+        fmt=MemoryFormat.KV_T2D,
+    )
+    assert obj is not None
+    assert obj.tensor is not None
+    obj.tensor.fill_(fill_value)
+    return obj
+
+
+def _store_tensor(
+    backend: DaxBackend,
+    key: CacheEngineKey,
+    *,
+    num_tokens: int,
+    hidden_dim: int = 8,
+    fill_value: int = 0,
+) -> None:
+    obj = _allocate_kv_obj(
+        num_tokens=num_tokens,
+        hidden_dim=hidden_dim,
+        fill_value=fill_value,
+    )
+    try:
+        futures = backend.batched_submit_put_task([key], [obj])
+        if futures:
+            for future in futures:
+                future.result(timeout=5)
+    finally:
+        obj.ref_count_down()
+
+
+def test_dax_backend_roundtrip(memory_allocator, loop_in_thread):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            key = CacheEngineKey("test_model", 1, 0, 1, torch.bfloat16)
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None
+            assert obj.tensor is not None
+            obj.tensor.fill_(5)
+
+            futs = backend.batched_submit_put_task([key], [obj])
+            if futs:
+                for fut in futs:
+                    fut.result(timeout=5)
+
+            out = backend.get_blocking(key)
+            assert out is not None
+            assert out.tensor is not None
+            assert torch.equal(out.tensor, obj.tensor)
+            out.ref_count_down()
+            obj.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_batched_get_blocking_keeps_positional_holes(
+    memory_allocator,
+    loop_in_thread,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            key1 = CacheEngineKey("test_model", 1, 0, 11, torch.bfloat16)
+            key2 = CacheEngineKey("test_model", 1, 0, 12, torch.bfloat16)
+            key3 = CacheEngineKey("test_model", 1, 0, 13, torch.bfloat16)
+            _store_tensor(backend, key1, num_tokens=16, fill_value=3)
+            _store_tensor(backend, key3, num_tokens=16, fill_value=7)
+
+            results = backend.batched_get_blocking([key1, key2, key3])
+            assert len(results) == 3
+            assert results[1] is None
+            assert results[0] is not None
+            assert results[2] is not None
+            assert torch.all(results[0].tensor == 3)
+            assert torch.all(results[2].tensor == 7)
+            results[0].ref_count_down()
+            results[2].ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_batched_get_blocking_passes_cached_fmt_to_allocator(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        seen_formats: list[MemoryFormat] = []
+        original_batched_allocate = local_cpu.batched_allocate
+
+        def _tracking_batched_allocate(
+            shapes: torch.Size | list[torch.Size],
+            dtypes: torch.dtype | list[torch.dtype],
+            batch_size: int,
+            fmt: MemoryFormat | None = None,
+            eviction: bool = True,
+            busy_loop: bool = True,
+        ) -> list[MemoryObj] | None:
+            assert fmt is not None
+            seen_formats.append(fmt)
+            return original_batched_allocate(
+                shapes,
+                dtypes,
+                batch_size,
+                fmt,
+                eviction=eviction,
+                busy_loop=busy_loop,
+            )
+
+        monkeypatch.setattr(local_cpu, "batched_allocate", _tracking_batched_allocate)
+
+        try:
+            key1 = CacheEngineKey("test_model", 1, 0, 14, torch.bfloat16)
+            key2 = CacheEngineKey("test_model", 1, 0, 15, torch.bfloat16)
+            _store_tensor(backend, key1, num_tokens=16, fill_value=4)
+            _store_tensor(backend, key2, num_tokens=16, fill_value=8)
+
+            results = backend.batched_get_blocking([key1, key2])
+            assert seen_formats == [MemoryFormat.KV_T2D]
+            for result in results:
+                assert result is not None
+                result.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_batched_get_blocking_handles_heterogeneous_chunk_shapes(
+    memory_allocator,
+    loop_in_thread,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            full_key = CacheEngineKey("test_model", 1, 0, 21, torch.bfloat16)
+            tail_key = CacheEngineKey("test_model", 1, 0, 22, torch.bfloat16)
+            _store_tensor(backend, full_key, num_tokens=16, fill_value=5)
+            _store_tensor(backend, tail_key, num_tokens=8, fill_value=9)
+
+            results = backend.batched_get_blocking([full_key, tail_key])
+            assert [result.get_shape() for result in results if result is not None] == [
+                torch.Size([2, 16, 8]),
+                torch.Size([2, 8, 8]),
+            ]
+            assert results[0] is not None
+            assert results[1] is not None
+            assert torch.all(results[0].tensor == 5)
+            assert torch.all(results[1].tensor == 9)
+            for result in results:
+                assert result is not None
+                result.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_batched_get_non_blocking_stops_at_first_miss(
+    memory_allocator,
+    loop_in_thread,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            key1 = CacheEngineKey("test_model", 1, 0, 31, torch.bfloat16)
+            key2 = CacheEngineKey("test_model", 1, 0, 32, torch.bfloat16)
+            key3 = CacheEngineKey("test_model", 1, 0, 33, torch.bfloat16)
+            _store_tensor(backend, key1, num_tokens=16, fill_value=1)
+            _store_tensor(backend, key3, num_tokens=16, fill_value=2)
+
+            results = asyncio.run(
+                backend.batched_get_non_blocking("lookup", [key1, key2, key3])
+            )
+            assert len(results) == 1
+            assert torch.all(results[0].tensor == 1)
+            results[0].ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_blocking_and_async_share_restore_dispatch(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        key1 = CacheEngineKey("test_model", 1, 0, 43, torch.bfloat16)
+        key2 = CacheEngineKey("test_model", 1, 0, 44, torch.bfloat16)
+        first_restore_started = threading.Event()
+        allow_first_restore = threading.Event()
+        second_restore_started = threading.Event()
+        original_restore_batch = backend._restore_batch
+        call_count = 0
+        call_count_lock = threading.Lock()
+
+        def _gated_restore_batch(keys, prefix_only):
+            nonlocal call_count
+            with call_count_lock:
+                call_count += 1
+                current_call = call_count
+            if current_call == 1:
+                first_restore_started.set()
+                assert allow_first_restore.wait(timeout=1)
+            elif current_call == 2:
+                second_restore_started.set()
+            return original_restore_batch(keys, prefix_only)
+
+        def _read_async() -> list[MemoryObj]:
+            return asyncio.run(backend.batched_get_non_blocking("lookup", [key2]))
+
+        monkeypatch.setattr(backend, "_restore_batch", _gated_restore_batch)
+
+        try:
+            _store_tensor(backend, key1, num_tokens=16, fill_value=12)
+            _store_tensor(backend, key2, num_tokens=16, fill_value=13)
+
+            with ThreadPoolExecutor(max_workers=2) as executor:
+                blocking_future = executor.submit(backend.batched_get_blocking, [key1])
+                assert first_restore_started.wait(timeout=1)
+
+                async_future = executor.submit(_read_async)
+                assert not second_restore_started.wait(timeout=0.2)
+
+                allow_first_restore.set()
+
+                blocking_results = blocking_future.result(timeout=2)
+                assert second_restore_started.wait(timeout=1)
+                async_results = async_future.result(timeout=2)
+
+            assert len(blocking_results) == 1
+            assert len(async_results) == 1
+            assert blocking_results[0] is not None
+            assert torch.all(blocking_results[0].tensor == 12)
+            assert torch.all(async_results[0].tensor == 13)
+            blocking_results[0].ref_count_down()
+            async_results[0].ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_batched_memcpy_helper() -> None:
+    src = torch.arange(16, dtype=torch.uint8)
+    dst = torch.zeros(16, dtype=torch.uint8)
+    dst2 = torch.zeros(4, dtype=torch.uint8)
+
+    dax_backend_module.lmc_ops.batched_memcpy(
+        [src.data_ptr(), src.data_ptr() + 4],
+        [dst.data_ptr(), dst2.data_ptr()],
+        [8, 4],
+    )
+
+    assert torch.equal(dst[:8], src[:8])
+    assert torch.equal(dst2, src[4:8])
+
+
+def test_dax_backend_rejects_tp_gt_1(loop_in_thread):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(4 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 4 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16, world_size=2)
+
+        with pytest.raises(ValueError, match="only supports TP=1"):
+            DaxBackend(
+                config=config,
+                metadata=metadata,
+                local_cpu_backend=None,
+                loop=loop_in_thread,
+                dst_device="cpu",
+            )
+
+
+def test_dax_backend_requires_local_cpu_backend() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(4096)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 4096 / 1024**3,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+
+        with pytest.raises(ValueError, match="requires local_cpu_backend"):
+            DaxBackend(
+                config=config,
+                metadata=metadata,
+                local_cpu_backend=None,
+                loop=None,
+                dst_device="cpu",
+            )
+
+
+def test_dax_backend_rejects_multi_group_metadata_at_init() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(8 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 8 / 1024,
+            },
+        )
+        metadata = _create_multi_group_metadata(chunk_size=16)
+
+        with pytest.raises(ValueError, match="single-group KV layout"):
+            DaxBackend(
+                config=config,
+                metadata=metadata,
+                local_cpu_backend=None,
+                loop=None,
+                dst_device="cpu",
+            )
+
+
+def test_dax_backend_failed_init_does_not_leak_fds() -> None:
+    if not os.path.isdir("/proc/self/fd"):
+        pytest.skip("/proc/self/fd is not available on this platform")
+
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(4096)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+
+        fd_before = len(os.listdir("/proc/self/fd"))
+        for _ in range(3):
+            local_cpu = LocalCPUBackend(
+                config=config,
+                metadata=metadata,
+                dst_device="cpu",
+                memory_allocator=AdHocMemoryAllocator(device="cpu"),
+            )
+            with pytest.raises(RuntimeError, match="exceeds device capacity"):
+                DaxBackend(
+                    config=config,
+                    metadata=metadata,
+                    local_cpu_backend=local_cpu,
+                    loop=None,
+                    dst_device="cpu",
+                )
+        fd_after = len(os.listdir("/proc/self/fd"))
+        assert fd_after == fd_before
+
+
+def test_dax_backend_oversized_put_raises_error(
+    memory_allocator,
+    loop_in_thread,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 32 / (1024 * 1024),  # one slot
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            oversized_key = CacheEngineKey("test_model", 1, 0, 704, torch.bfloat16)
+            oversized = alloc.allocate(
+                [torch.Size([2, 1025, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert oversized is not None
+            assert oversized.get_size() > backend.slot_bytes
+
+            with pytest.raises(ValueError, match="exceeds slot size"):
+                backend.batched_submit_put_task([oversized_key], [oversized])
+            assert not backend.contains(oversized_key)
+            oversized.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_put_rejects_mismatched_key_and_obj_lengths(
+    memory_allocator,
+    loop_in_thread,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 64 / (1024 * 1024),
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+
+            with pytest.raises(ValueError, match="same length"):
+                backend.batched_submit_put_task(
+                    [
+                        CacheEngineKey("test_model", 1, 0, 801, torch.bfloat16),
+                        CacheEngineKey("test_model", 1, 0, 802, torch.bfloat16),
+                    ],
+                    [obj],
+                )
+            obj.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_multi_tensor_put_skips_without_indexing_or_leaking_slots(
+    memory_allocator,
+    loop_in_thread,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 32 / (1024 * 1024),  # one slot
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            multi_key = CacheEngineKey("test_model", 1, 0, 706, torch.bfloat16)
+            multi = alloc.allocate(
+                [torch.Size([2, 128, 8]), torch.Size([2, 128, 8])],
+                [torch.bfloat16, torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert multi is not None
+
+            backend.batched_submit_put_task([multi_key], [multi])
+            assert not backend.contains(multi_key)
+            assert backend.get_blocking(multi_key) is None
+            multi.ref_count_down()
+
+            valid_key = CacheEngineKey("test_model", 1, 0, 708, torch.bfloat16)
+            reclaimed = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert reclaimed is not None
+            backend.batched_submit_put_task([valid_key], [reclaimed])
+            out = backend.get_blocking(valid_key)
+            assert out is not None
+            out.ref_count_down()
+            reclaimed.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_get_blocking_releases_lock_during_read(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        key1 = CacheEngineKey("test_model", 1, 0, 701, torch.bfloat16)
+        key2 = CacheEngineKey("test_model", 1, 0, 702, torch.bfloat16)
+        read_started = threading.Event()
+        allow_read = threading.Event()
+        remove_finished = threading.Event()
+        reader_result: list[MemoryObj | None] = []
+        remove_result: list[bool] = []
+        original_do_read = DaxBackend._do_read
+
+        def _blocking_do_read(self, offset, memory_obj, size) -> None:
+            read_started.set()
+            assert allow_read.wait(timeout=1)
+            original_do_read(self, offset, memory_obj, size)
+
+        monkeypatch.setattr(DaxBackend, "_do_read", _blocking_do_read)
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            for key, fill_value in ((key1, 3), (key2, 4)):
+                obj = alloc.allocate(
+                    [torch.Size([2, 16, 8])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None
+                assert obj.tensor is not None
+                obj.tensor.fill_(fill_value)
+                backend.batched_submit_put_task([key], [obj])
+                obj.ref_count_down()
+
+            def _reader() -> None:
+                reader_result.append(backend.get_blocking(key1))
+
+            def _remover() -> None:
+                remove_result.append(backend.remove(key2))
+                remove_finished.set()
+
+            reader = threading.Thread(target=_reader)
+            reader.start()
+            assert read_started.wait(timeout=1)
+
+            remover = threading.Thread(target=_remover)
+            remover.start()
+            assert remove_finished.wait(timeout=0.2)
+            assert remove_result[0] is True
+
+            allow_read.set()
+            reader.join(timeout=1)
+            remover.join(timeout=1)
+            assert not reader.is_alive()
+            assert not remover.is_alive()
+
+            result = reader_result[0]
+            assert result is not None
+            assert result.tensor is not None
+            assert torch.all(result.tensor == 3)
+            result.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_batched_get_blocking_releases_lock_during_restore(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        key1 = CacheEngineKey("test_model", 1, 0, 711, torch.bfloat16)
+        key2 = CacheEngineKey("test_model", 1, 0, 712, torch.bfloat16)
+        restore_started = threading.Event()
+        allow_restore = threading.Event()
+        remove_finished = threading.Event()
+        reader_result: list[list[MemoryObj | None]] = []
+        remove_result: list[bool] = []
+        original_batched_memcpy = backend._batched_memcpy
+        call_count = 0
+
+        def _blocking_batched_memcpy(src_ptrs, dst_ptrs, sizes) -> None:
+            nonlocal call_count
+            if call_count == 0:
+                restore_started.set()
+                assert allow_restore.wait(timeout=1)
+            call_count += 1
+            original_batched_memcpy(src_ptrs, dst_ptrs, sizes)
+
+        monkeypatch.setattr(backend, "_batched_memcpy", _blocking_batched_memcpy)
+
+        try:
+            _store_tensor(backend, key1, num_tokens=16, fill_value=3)
+            _store_tensor(backend, key2, num_tokens=16, fill_value=4)
+
+            def _reader() -> None:
+                reader_result.append(backend.batched_get_blocking([key1]))
+
+            def _remover() -> None:
+                remove_result.append(backend.remove(key2))
+                remove_finished.set()
+
+            reader = threading.Thread(target=_reader)
+            reader.start()
+            assert restore_started.wait(timeout=1)
+
+            remover = threading.Thread(target=_remover)
+            remover.start()
+            assert remove_finished.wait(timeout=0.2)
+            assert remove_result == [True]
+
+            allow_restore.set()
+            reader.join(timeout=1)
+            remover.join(timeout=1)
+            assert not reader.is_alive()
+            assert not remover.is_alive()
+
+            results = reader_result[0]
+            assert len(results) == 1
+            assert results[0] is not None
+            assert torch.all(results[0].tensor == 3)
+            results[0].ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_remove_during_read_defers_slot_reclaim(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 32 / (1024 * 1024),
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        key = CacheEngineKey("test_model", 1, 0, 703, torch.bfloat16)
+        read_started = threading.Event()
+        allow_read = threading.Event()
+        reader_result: list[MemoryObj | None] = []
+        original_do_read = DaxBackend._do_read
+
+        def _blocking_do_read(self, offset, memory_obj, size) -> None:
+            read_started.set()
+            assert allow_read.wait(timeout=1)
+            original_do_read(self, offset, memory_obj, size)
+
+        monkeypatch.setattr(DaxBackend, "_do_read", _blocking_do_read)
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+            assert obj.tensor is not None
+            obj.tensor.fill_(7)
+            backend.batched_submit_put_task([key], [obj])
+            obj.ref_count_down()
+
+            def _reader() -> None:
+                reader_result.append(backend.get_blocking(key))
+
+            reader = threading.Thread(target=_reader)
+            reader.start()
+            assert read_started.wait(timeout=1)
+
+            assert backend.remove(key)
+            blocked_key = CacheEngineKey("test_model", 1, 0, 704, torch.bfloat16)
+            blocked = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert blocked is not None
+            with pytest.raises(RuntimeError, match="No free slots available"):
+                backend.batched_submit_put_task([blocked_key], [blocked])
+            blocked.ref_count_down()
+
+            allow_read.set()
+            reader.join(timeout=1)
+            assert not reader.is_alive()
+
+            result = reader_result[0]
+            assert result is not None
+            assert result.tensor is not None
+            assert torch.all(result.tensor == 7)
+            result.ref_count_down()
+
+            recycled_key = CacheEngineKey("test_model", 1, 0, 705, torch.bfloat16)
+            recycled = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert recycled is not None
+            backend.batched_submit_put_task([recycled_key], [recycled])
+            recycled_out = backend.get_blocking(recycled_key)
+            assert recycled_out is not None
+            recycled_out.ref_count_down()
+            recycled.ref_count_down()
+            assert backend.get_blocking(key) is None
+        finally:
+            backend.close()
+
+
+def test_dax_backend_remove_during_batched_restore_defers_slot_reclaim(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 32 / (1024 * 1024),
+                "dax.restore_workers": 1,
+                "dax.restore_max_regions": 1,
+                "dax.retrieve_staging_slab_bytes": 65536,
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        key = CacheEngineKey("test_model", 1, 0, 713, torch.bfloat16)
+        restore_started = threading.Event()
+        allow_restore = threading.Event()
+        reader_result: list[list[MemoryObj | None]] = []
+        original_batched_memcpy = backend._batched_memcpy
+        call_count = 0
+
+        def _blocking_batched_memcpy(src_ptrs, dst_ptrs, sizes) -> None:
+            nonlocal call_count
+            if call_count == 0:
+                restore_started.set()
+                assert allow_restore.wait(timeout=1)
+            call_count += 1
+            original_batched_memcpy(src_ptrs, dst_ptrs, sizes)
+
+        monkeypatch.setattr(backend, "_batched_memcpy", _blocking_batched_memcpy)
+
+        try:
+            _store_tensor(backend, key, num_tokens=256, fill_value=7)
+
+            def _reader() -> None:
+                reader_result.append(backend.batched_get_blocking([key]))
+
+            reader = threading.Thread(target=_reader)
+            reader.start()
+            assert restore_started.wait(timeout=1)
+
+            assert backend.remove(key)
+            blocked_key = CacheEngineKey("test_model", 1, 0, 714, torch.bfloat16)
+            blocked = _allocate_kv_obj(num_tokens=256, fill_value=11)
+            try:
+                with pytest.raises(RuntimeError, match="No free slots available"):
+                    backend.batched_submit_put_task([blocked_key], [blocked])
+            finally:
+                blocked.ref_count_down()
+
+            allow_restore.set()
+            reader.join(timeout=1)
+            assert not reader.is_alive()
+
+            results = reader_result[0]
+            assert len(results) == 1
+            assert results[0] is not None
+            assert torch.all(results[0].tensor == 7)
+            results[0].ref_count_down()
+
+            recycled_key = CacheEngineKey("test_model", 1, 0, 715, torch.bfloat16)
+            _store_tensor(backend, recycled_key, num_tokens=256, fill_value=9)
+            recycled_results = backend.batched_get_blocking([recycled_key])
+            assert recycled_results[0] is not None
+            recycled_results[0].ref_count_down()
+            assert backend.get_blocking(key) is None
+        finally:
+            backend.close()
+
+
+def test_dax_backend_get_read_failure_releases_cpu_memory_obj(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 32 / (1024 * 1024),
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        allocated_on_read: list[MemoryObj] = []
+        original_allocate = local_cpu.allocate
+
+        def _tracking_allocate(
+            shape: torch.Size,
+            dtype: torch.dtype,
+            fmt: MemoryFormat,
+        ) -> MemoryObj:
+            memory_obj = original_allocate(shape, dtype, fmt)
+            assert memory_obj is not None
+            allocated_on_read.append(memory_obj)
+            return memory_obj
+
+        def _failing_do_read(
+            self,
+            offset: int,
+            memory_obj: MemoryObj,
+            size: int,
+        ) -> None:
+            del self, offset, memory_obj, size
+            raise RuntimeError("simulated read failure")
+
+        monkeypatch.setattr(local_cpu, "allocate", _tracking_allocate)
+        monkeypatch.setattr(DaxBackend, "_do_read", _failing_do_read)
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            key = CacheEngineKey("test_model", 1, 0, 707, torch.bfloat16)
+            obj = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+            assert obj.tensor is not None
+            obj.tensor.fill_(7)
+            backend.batched_submit_put_task([key], [obj])
+            obj.ref_count_down()
+
+            with pytest.raises(RuntimeError, match="simulated read failure"):
+                backend.get_blocking(key)
+
+            assert len(allocated_on_read) == 1
+            assert allocated_on_read[0].get_ref_count() == 0
+            assert backend.contains(key)
+        finally:
+            backend.close()
+
+
+def test_dax_backend_allocator_exhaustion_fails_without_internal_eviction(
+    memory_allocator,
+    loop_in_thread,
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 64 / (1024 * 1024),  # ~2 slots for test kv shape
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            keys = [
+                CacheEngineKey("test_model", 1, 0, 101, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 102, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 103, torch.bfloat16),
+            ]
+
+            for i, key in enumerate(keys[:2]):
+                obj = alloc.allocate(
+                    [torch.Size([2, 256, 8])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None
+                assert obj.tensor is not None
+                obj.tensor.fill_(i + 1)
+                futs = backend.batched_submit_put_task([key], [obj])
+                if futs:
+                    for fut in futs:
+                        fut.result(timeout=5)
+                obj.ref_count_down()
+
+            obj3 = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj3 is not None
+            with pytest.raises(RuntimeError, match="No free slots available"):
+                backend.batched_submit_put_task([keys[2]], [obj3])
+            obj3.ref_count_down()
+
+            out0 = backend.get_blocking(keys[0])
+            assert out0 is not None
+            out0.ref_count_down()
+            out1 = backend.get_blocking(keys[1])
+            assert out1 is not None
+            out1.ref_count_down()
+            assert backend.get_blocking(keys[2]) is None
+        finally:
+            backend.close()
+
+
+def test_dax_backend_full_arena_does_not_evict_pinned_or_unpinned_keys(
+    memory_allocator, loop_in_thread
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 64 / (1024 * 1024),
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            keys = [
+                CacheEngineKey("test_model", 1, 0, 201, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 202, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 203, torch.bfloat16),
+            ]
+
+            for key in keys[:2]:
+                obj = alloc.allocate(
+                    [torch.Size([2, 256, 8])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None
+                futs = backend.batched_submit_put_task([key], [obj])
+                if futs:
+                    for fut in futs:
+                        fut.result(timeout=5)
+                obj.ref_count_down()
+
+            assert backend.pin(keys[0])
+
+            obj3 = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj3 is not None
+            with pytest.raises(RuntimeError, match="No free slots available"):
+                futs = backend.batched_submit_put_task([keys[2]], [obj3])
+                if futs:
+                    for fut in futs:
+                        fut.result(timeout=5)
+            obj3.ref_count_down()
+
+            out0 = backend.get_blocking(keys[0])
+            assert out0 is not None
+            out0.ref_count_down()
+            out1 = backend.get_blocking(keys[1])
+            assert out1 is not None
+            out1.ref_count_down()
+            assert backend.get_blocking(keys[2]) is None
+        finally:
+            backend.close()
+
+
+def test_dax_backend_overlapping_pin_unpin(memory_allocator, loop_in_thread):
+    """Regression: overlapping pin/unpin must use ref-counting, not a plain set."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 64 / (1024 * 1024),  # 2 slots
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            keys = [
+                CacheEngineKey("test_model", 1, 0, 401, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 402, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 403, torch.bfloat16),
+                CacheEngineKey("test_model", 1, 0, 404, torch.bfloat16),
+            ]
+
+            # Store keys A and B (fills both slots)
+            for key in keys[:2]:
+                obj = alloc.allocate(
+                    [torch.Size([2, 256, 8])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None
+                futs = backend.batched_submit_put_task([key], [obj])
+                if futs:
+                    for fut in futs:
+                        fut.result(timeout=5)
+                obj.ref_count_down()
+
+            # Pin key A twice (simulate two concurrent lookups)
+            assert backend.pin(keys[0])
+            assert backend.pin(keys[0])
+
+            # Unpin key A once — pin_count should still be 1
+            backend.unpin(keys[0])
+
+            # Key A still has one outstanding pin and cannot be removed
+            # by non-forced eviction-controller delete calls.
+            assert not backend.remove(keys[0], force=False)
+            assert backend.remove(keys[1], force=False)
+
+            obj_c = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj_c is not None
+            futs = backend.batched_submit_put_task([keys[2]], [obj_c])
+            if futs:
+                for fut in futs:
+                    fut.result(timeout=5)
+            obj_c.ref_count_down()
+
+            assert backend.contains(keys[0]), (
+                "key A should survive non-forced delete while pin_count=1"
+            )
+            assert not backend.contains(keys[1]), "key B should be deleted"
+            assert backend.contains(keys[2])
+
+            # Unpin key A a second time; non-forced delete can now reclaim it.
+            backend.unpin(keys[0])
+            assert backend.remove(keys[0], force=False)
+
+            obj_d = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj_d is not None
+            futs = backend.batched_submit_put_task([keys[3]], [obj_d])
+            if futs:
+                for fut in futs:
+                    fut.result(timeout=5)
+            obj_d.ref_count_down()
+
+            assert not backend.contains(keys[0]), (
+                "key A should be removable after full unpin"
+            )
+            assert backend.contains(keys[3])
+        finally:
+            backend.close()
+
+
+def test_dax_backend_remove_inflight_reclaims_slot(memory_allocator, loop_in_thread):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(1024 * 1024)
+
+        config = _create_config(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 32 / (1024 * 1024),  # one slot
+            },
+        )
+        metadata = _create_metadata(chunk_size=256)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            key1 = CacheEngineKey("test_model", 1, 0, 301, torch.bfloat16)
+            obj1 = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj1 is not None
+            backend.batched_submit_put_task([key1], [obj1])
+            obj1.ref_count_down()
+
+            assert backend.remove(key1)
+            assert backend.get_blocking(key1) is None
+
+            key2 = CacheEngineKey("test_model", 1, 0, 302, torch.bfloat16)
+            obj2 = alloc.allocate(
+                [torch.Size([2, 256, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj2 is not None
+            backend.batched_submit_put_task([key2], [obj2])
+            obj2.ref_count_down()
+            out = backend.get_blocking(key2)
+            assert out is not None
+            out.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_multithread_put_get_smoke(memory_allocator, loop_in_thread):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        def _worker(i: int) -> None:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            key = CacheEngineKey("test_model", 1, 0, 400 + i, torch.bfloat16)
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None
+            assert obj.tensor is not None
+            obj.tensor.fill_(i)
+            futs = backend.batched_submit_put_task([key], [obj])
+            if futs:
+                for fut in futs:
+                    fut.result(timeout=5)
+            obj.ref_count_down()
+            out = backend.get_blocking(key)
+            assert out is not None
+            assert out.tensor is not None
+            assert torch.equal(out.tensor, obj.tensor)
+            out.ref_count_down()
+
+        try:
+            with ThreadPoolExecutor(max_workers=4) as executor:
+                futures = [executor.submit(_worker, i) for i in range(20)]
+                for fut in futures:
+                    fut.result(timeout=10)
+        finally:
+            backend.close()
+
+
+def test_dax_backend_sync_close_waits_for_active_put(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        write_started = threading.Event()
+        allow_write = threading.Event()
+        close_returned = threading.Event()
+        observed: dict[str, object] = {}
+        writer_exc: dict[str, BaseException] = {}
+        original_do_write = DaxBackend._do_write
+
+        def _blocking_do_write(self, offset, memory_obj, size) -> None:
+            write_started.set()
+            assert allow_write.wait(timeout=1)
+            observed["mmap_is_none"] = self._mmap_obj is None
+            observed["base_ptr"] = self._base_ptr
+            original_do_write(self, offset, memory_obj, size)
+
+        monkeypatch.setattr(DaxBackend, "_do_write", _blocking_do_write)
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+            key = CacheEngineKey("test_model", 1, 0, 410, torch.bfloat16)
+
+            def _writer() -> None:
+                try:
+                    backend.batched_submit_put_task([key], [obj])
+                except BaseException as e:
+                    writer_exc["error"] = e
+
+            def _closer() -> None:
+                backend.close()
+                close_returned.set()
+
+            writer = threading.Thread(target=_writer)
+            closer = threading.Thread(target=_closer)
+
+            writer.start()
+            assert write_started.wait(timeout=1)
+            closer.start()
+            time.sleep(0.05)
+            assert not close_returned.is_set()
+
+            allow_write.set()
+            writer.join(timeout=1)
+            closer.join(timeout=1)
+
+            assert not writer.is_alive()
+            assert not closer.is_alive()
+            assert "error" not in writer_exc
+            assert close_returned.is_set()
+            assert observed["mmap_is_none"] is False
+            assert observed["base_ptr"] != 0
+            obj.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_sync_close_waits_for_active_get(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        read_started = threading.Event()
+        allow_read = threading.Event()
+        close_returned = threading.Event()
+        reader_result: list[MemoryObj | None] = []
+        original_do_read = DaxBackend._do_read
+
+        def _blocking_do_read(self, offset, memory_obj, size) -> None:
+            read_started.set()
+            assert allow_read.wait(timeout=1)
+            original_do_read(self, offset, memory_obj, size)
+
+        monkeypatch.setattr(DaxBackend, "_do_read", _blocking_do_read)
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+            assert obj.tensor is not None
+            obj.tensor.fill_(6)
+            key = CacheEngineKey("test_model", 1, 0, 412, torch.bfloat16)
+            backend.batched_submit_put_task([key], [obj])
+            obj.ref_count_down()
+
+            def _reader() -> None:
+                reader_result.append(backend.get_blocking(key))
+
+            def _closer() -> None:
+                backend.close()
+                close_returned.set()
+
+            reader = threading.Thread(target=_reader)
+            closer = threading.Thread(target=_closer)
+
+            reader.start()
+            assert read_started.wait(timeout=1)
+            closer.start()
+            time.sleep(0.05)
+
+            assert not close_returned.is_set()
+            assert backend._mmap_obj is not None  # noqa: SLF001
+            assert backend._base_ptr != 0  # noqa: SLF001
+
+            allow_read.set()
+            reader.join(timeout=1)
+            closer.join(timeout=1)
+
+            assert not reader.is_alive()
+            assert not closer.is_alive()
+            assert close_returned.is_set()
+
+            result = reader_result[0]
+            assert result is not None
+            assert result.tensor is not None
+            assert torch.all(result.tensor == 6)
+            result.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_sync_close_waits_for_active_batched_restore(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        restore_started = threading.Event()
+        allow_restore = threading.Event()
+        close_returned = threading.Event()
+        reader_result: list[list[MemoryObj | None]] = []
+        original_batched_memcpy = backend._batched_memcpy
+        call_count = 0
+
+        def _blocking_batched_memcpy(src_ptrs, dst_ptrs, sizes) -> None:
+            nonlocal call_count
+            if call_count == 0:
+                restore_started.set()
+                assert allow_restore.wait(timeout=1)
+            call_count += 1
+            original_batched_memcpy(src_ptrs, dst_ptrs, sizes)
+
+        monkeypatch.setattr(backend, "_batched_memcpy", _blocking_batched_memcpy)
+
+        key = CacheEngineKey("test_model", 1, 0, 719, torch.bfloat16)
+
+        try:
+            _store_tensor(backend, key, num_tokens=16, fill_value=6)
+
+            def _reader() -> None:
+                reader_result.append(backend.batched_get_blocking([key]))
+
+            reader = threading.Thread(target=_reader)
+            reader.start()
+            assert restore_started.wait(timeout=1)
+
+            def _closer() -> None:
+                backend.close()
+                close_returned.set()
+
+            closer = threading.Thread(target=_closer)
+            closer.start()
+
+            time.sleep(0.1)
+            assert not close_returned.is_set()
+
+            allow_restore.set()
+            reader.join(timeout=1)
+            closer.join(timeout=1)
+            assert close_returned.is_set()
+            assert not reader.is_alive()
+            assert not closer.is_alive()
+
+            results = reader_result[0]
+            assert len(results) == 1
+            assert results[0] is not None
+            results[0].ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_close_rejects_new_ops_after_shutdown() -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=AdHocMemoryAllocator(device="cpu"),
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=None,
+            dst_device="cpu",
+        )
+
+        try:
+            backend.close()
+            assert (
+                backend.get_blocking(
+                    CacheEngineKey("test_model", 1, 0, 999, torch.bfloat16)
+                )
+                is None
+            )
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+            with pytest.raises(RuntimeError, match="closing"):
+                backend.batched_submit_put_task(
+                    [CacheEngineKey("test_model", 1, 0, 1000, torch.bfloat16)],
+                    [obj],
+                )
+            obj.ref_count_down()
+        finally:
+            backend.close()
+
+
+def test_dax_backend_async_close_waits_for_active_put(
+    memory_allocator,
+    loop_in_thread,
+    monkeypatch,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dax.bin")
+        with open(dev_path, "wb") as fout:
+            fout.truncate(16 * 1024 * 1024)
+
+        config = _create_config(
+            chunk_size=16,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            extra_config={
+                "dax.device_path": dev_path,
+                "dax.max_dax_size": 16 / 1024,
+                "dax.async_put": True,
+            },
+        )
+        metadata = _create_metadata(chunk_size=16)
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = DaxBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        write_started = threading.Event()
+        allow_write = threading.Event()
+        close_returned = threading.Event()
+        original_do_write = DaxBackend._do_write
+
+        def _blocking_do_write(self, offset, memory_obj, size) -> None:
+            write_started.set()
+            assert allow_write.wait(timeout=2)
+            original_do_write(self, offset, memory_obj, size)
+
+        monkeypatch.setattr(DaxBackend, "_do_write", _blocking_do_write)
+
+        # Start the event loop so the async_put path is exercised.
+        loop_thread = threading.Thread(target=loop_in_thread.run_forever, daemon=True)
+        loop_thread.start()
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+            key = CacheEngineKey("test_model", 1, 0, 411, torch.bfloat16)
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8])],
+                [torch.bfloat16],
+                fmt=MemoryFormat.KV_T2D,
+            )
+            assert obj is not None
+
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+
+            def _closer() -> None:
+                backend.close()
+                close_returned.set()
+
+            assert write_started.wait(timeout=2)
+            closer = threading.Thread(target=_closer)
+            closer.start()
+            time.sleep(0.05)
+            assert not close_returned.is_set()
+
+            allow_write.set()
+            closer.join(timeout=2)
+
+            assert not closer.is_alive()
+            assert close_returned.is_set()
+            obj.ref_count_down()
+        finally:
+            loop_in_thread.call_soon_threadsafe(loop_in_thread.stop)
+            loop_thread.join(timeout=2)
+            backend.close()
diff --git a/tests/v1/storage_backend/test_eic.py b/tests/v1/storage_backend/test_eic.py
new file mode 100644
index 0000000..e760e04
--- /dev/null
+++ b/tests/v1/storage_backend/test_eic.py
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import argparse
+import os
+
+# Third Party
+import pytest
+import torch
+import yaml
+
+try:
+    # Third Party
+    import eic
+
+    EIC_AVAILABLE = True
+except ImportError:
+    EIC_AVAILABLE = False
+
+pytestmark = pytest.mark.skipif(not EIC_AVAILABLE, reason="eic module not available")
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="EIC Storage Unit Test")
+    parser.add_argument(
+        "--config",
+        "-c",
+        type=str,
+        default="/workspace/config/remote-eic.yaml",
+        help="EIC yaml config",
+    )
+    args, _ = parser.parse_known_args()
+    return args
+
+
+def init_eic_client():
+    args = parse_args()
+    config_path = os.path.abspath(args.config)
+    if not os.path.exists(config_path):
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+    with open(config_path, "r") as fin:
+        config = yaml.safe_load(fin)
+
+    remote_url = config.get("remote_url", None)
+    if remote_url is None:
+        raise AssertionError("remote_url is None")
+    endpoint = remote_url[len("eic://") :]
+    eic_instance_id = config.get("eic_instance_id", None)
+    eic_log_dir = config.get("eic_log_dir", None)
+    eic_log_level = config.get("eic_log_level", 2)
+    eic_trans_type = config.get("eic_trans_type", 3)
+    eic_flag_file = config.get("eic_flag_file", None)
+
+    if not os.path.exists(eic_log_dir):
+        os.makedirs(eic_log_dir, exist_ok=True)
+    eic_client = eic.Client()
+    init_option = eic.InitOption()
+    init_option.log_dir = eic_log_dir
+    init_option.log_level = eic.LogLevel(eic_log_level)
+    init_option.transport_type = eic.TransportType(eic_trans_type)
+    init_option.flag_file = eic_flag_file
+    ret = eic_client.init(eic_instance_id, endpoint, init_option)
+    if ret != 0:
+        raise RuntimeError(f"EIC Client init failed with error code: {ret}")
+    return eic_client
+
+
+def test_set(eic_client):
+    test_key = ["test_key_" + str(i) for i in range(16)]
+    tensors = [
+        torch.ones([12, 6, 1, 512], dtype=torch.bfloat16, device="cpu")
+        for _ in range(16)
+    ]
+    data_keys = eic.StringVector()
+    data_vals = eic.IOBuffers()
+    for i in range(16):
+        data_keys.append(test_key[i])
+        data_vals.append(
+            tensors[i].data_ptr(),
+            tensors[i].numel() * tensors[i].element_size(),
+            False,
+        )
+    set_opt = eic.SetOption()
+    set_opt.ttl_second = 3
+    status_code, set_outcome = eic_client.mset(data_keys, data_vals, set_opt)
+    assert status_code == eic.StatusCode.SUCCESS, (
+        f"Set failed with status code: {status_code}"
+    )
+
+
+def test_get(eic_client):
+    test_key = ["test_key_" + str(i) for i in range(16)]
+    tensors = [
+        torch.zeros([12, 6, 1, 512], dtype=torch.bfloat16, device="cpu")
+        for _ in range(16)
+    ]
+    data_keys = eic.StringVector()
+    data_vals = eic.IOBuffers()
+    for i in range(16):
+        data_keys.append(test_key[i])
+        data_vals.append(
+            tensors[i].data_ptr(),
+            tensors[i].numel() * tensors[i].element_size(),
+            False,
+        )
+    get_opt = eic.GetOption()
+    status_code, data_vals, get_outcome = eic_client.mget(data_keys, get_opt, data_vals)
+    assert status_code == eic.StatusCode.SUCCESS, (
+        f"Get failed with status code: {status_code}"
+    )
+
+
+def test_exists(eic_client):
+    test_key = ["test_key_" + str(i) for i in range(16)]
+    data_keys = eic.StringVector()
+    for key in test_key:
+        data_keys.append(key)
+    exists_opt = eic.ExistOption()
+    status_code, exists_outcome = eic_client.mexist(data_keys, exists_opt)
+    assert status_code == eic.StatusCode.SUCCESS, (
+        f"Exists failed with status code: {status_code}"
+    )
+
+
+def main():
+    eic_client = init_eic_client()
+    test_set(eic_client)
+    test_exists(eic_client)
+    test_get(eic_client)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/v1/storage_backend/test_fs_connector.py b/tests/v1/storage_backend/test_fs_connector.py
new file mode 100644
index 0000000..7052e37
--- /dev/null
+++ b/tests/v1/storage_backend/test_fs_connector.py
@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import asyncio
+import os
+import shutil
+import tempfile
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+from tests.v1.utils import create_test_memory_obj
+
+
+def create_test_config(fs_path: str):
+    """Create a test configuration for FSConnector."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        remote_url=f"fs://host:0/{fs_path}",
+        remote_serde="naive",
+        lmcache_instance_id="test_instance",
+    )
+    return config
+
+
+def create_test_config_with_plugin(fs_path: str):
+    """Create a test configuration for FSConnector using remote_storage_plugins."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        remote_storage_plugins=["fs"],
+        remote_serde="naive",
+        lmcache_instance_id="test_instance",
+        extra_config={
+            "remote_storage_plugin.fs.base_path": fs_path,
+        },
+    )
+    return config
+
+
+def create_test_config_with_dual_plugins(fs_path1: str, fs_path2: str):
+    """Create config with two fs_connector instances."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        remote_storage_plugins=["fs.primary", "fs.backup"],
+        remote_serde="naive",
+        lmcache_instance_id="test_instance",
+        extra_config={
+            "remote_storage_plugin.fs.primary.base_path": fs_path1,
+            "remote_storage_plugin.fs.backup.base_path": fs_path2,
+        },
+    )
+    return config
+
+
+def create_test_metadata():
+    """Create a test metadata for LMCacheMetadata."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(28, 2, 256, 8, 128),
+    )
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+@pytest.fixture
+def temp_fs_path():
+    """Create a temporary directory for filesystem storage tests."""
+    temp_dir = tempfile.mkdtemp()
+    yield temp_dir
+    # Cleanup
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir)
+
+
+@pytest.fixture
+def async_loop():
+    """Create an asyncio event loop running in a separate thread for testing."""
+    loop = asyncio.new_event_loop()
+
+    # Start the event loop in a separate thread
+    # Standard
+    import threading
+
+    # First Party
+    from lmcache.utils import start_loop_in_thread_with_exceptions
+
+    thread = threading.Thread(
+        target=start_loop_in_thread_with_exceptions,
+        args=(loop,),
+        name="test-async-loop",
+    )
+    thread.start()
+
+    yield loop
+
+    # Cleanup: stop the loop and wait for thread to finish
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=5.0)
+
+
+@pytest.fixture
+def local_cpu_backend(memory_allocator):
+    """Create a LocalCPUBackend for testing."""
+    config = LMCacheEngineConfig.from_legacy(chunk_size=256)
+    metadata = create_test_metadata()
+    return LocalCPUBackend(config, metadata, memory_allocator=memory_allocator)
+
+
+@pytest.fixture
+def remote_backend_with_fs(temp_fs_path, async_loop, local_cpu_backend):
+    """Create a RemoteBackend with FSConnector for testing."""
+    config = create_test_config(temp_fs_path)
+    metadata = create_test_metadata()
+    backend = RemoteBackend(
+        config=config,
+        metadata=metadata,
+        loop=async_loop,
+        local_cpu_backend=local_cpu_backend,
+        dst_device="cpu",
+    )
+    yield backend
+    backend.local_cpu_backend.memory_allocator.close()
+    backend.close()
+
+
+class TestFSConnector:
+    """Test cases for FSConnector via RemoteBackend."""
+
+    def test_init(self, temp_fs_path, async_loop, local_cpu_backend):
+        """Test FSConnector initialization via RemoteBackend."""
+        config = create_test_config(temp_fs_path)
+        metadata = create_test_metadata()
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        assert backend.dst_device == "cpu"
+        assert backend.local_cpu_backend == local_cpu_backend
+        assert backend.remote_url == f"fs://host:0/{temp_fs_path}"
+        assert os.path.exists(temp_fs_path)
+        assert backend.config.remote_serde == "naive"
+
+        local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+    def test_init_with_plugin(self, temp_fs_path, async_loop, local_cpu_backend):
+        """Test FSConnector init via RemoteBackend
+        using remote_storage_plugins."""
+        config = create_test_config_with_plugin(temp_fs_path)
+        metadata = create_test_metadata()
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="fs",
+        )
+
+        assert backend.dst_device == "cpu"
+        assert backend.local_cpu_backend == local_cpu_backend
+        assert backend.plugin_name == "fs"
+        assert os.path.exists(temp_fs_path)
+        assert backend.config.remote_serde == "naive"
+
+        local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+    def test_dual_fs_instances(self, async_loop, local_cpu_backend):
+        """Test two fs_connector instances with different paths."""
+        dir1 = tempfile.mkdtemp()
+        dir2 = tempfile.mkdtemp()
+        try:
+            config = create_test_config_with_dual_plugins(dir1, dir2)
+            metadata = create_test_metadata()
+
+            backend1 = RemoteBackend(
+                config=config,
+                metadata=metadata,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cpu",
+                plugin_name="fs.primary",
+            )
+            backend2 = RemoteBackend(
+                config=config,
+                metadata=metadata,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cpu",
+                plugin_name="fs.backup",
+            )
+
+            key = create_test_key(99)
+            memory_obj = create_test_memory_obj()
+
+            # Put to backend1 only
+            future = backend1.submit_put_task(key, memory_obj)
+            if future:
+                future.result(timeout=5.0)
+
+            # backend1 has the key, backend2 does not
+            assert backend1.contains(key)
+            assert not backend2.contains(key)
+
+            # Put to backend2 as well
+            future2 = backend2.submit_put_task(key, memory_obj)
+            if future2:
+                future2.result(timeout=5.0)
+
+            assert backend2.contains(key)
+
+            backend1.close()
+            backend2.close()
+            local_cpu_backend.memory_allocator.close()
+        finally:
+            if os.path.exists(dir1):
+                shutil.rmtree(dir1)
+            if os.path.exists(dir2):
+                shutil.rmtree(dir2)
+
+    def test_contains_key_not_exists(self, remote_backend_with_fs):
+        """Test contains() when key doesn't exist in filesystem."""
+        key = create_test_key(1)
+        assert not remote_backend_with_fs.contains(key)
+        assert not remote_backend_with_fs.contains(key, pin=True)
+
+        remote_backend_with_fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_fs.close()
+
+    def test_get_blocking_key_not_exists(self, remote_backend_with_fs):
+        """Test get_blocking() when key doesn't exist in filesystem."""
+        key = create_test_key(2)
+        result = remote_backend_with_fs.get_blocking(key)
+
+        assert result is None
+
+        remote_backend_with_fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_fs.close()
+
+    def test_put_and_get_roundtrip(self, remote_backend_with_fs):
+        """Test put and get roundtrip for FSConnector."""
+        key = create_test_key(3)
+        memory_obj = create_test_memory_obj()
+
+        # Put data to filesystem
+        future = remote_backend_with_fs.submit_put_task(key, memory_obj)
+        # Wait for the async put to complete
+        if future:
+            future.result(timeout=5.0)
+
+        # Check that key exists
+        assert remote_backend_with_fs.contains(key)
+
+        # Get data back
+        result = remote_backend_with_fs.get_blocking(key)
+
+        assert result is not None
+        assert isinstance(result, MemoryObj)
+        assert result.metadata.shape == memory_obj.metadata.shape
+        assert result.metadata.dtype == memory_obj.metadata.dtype
+
+        remote_backend_with_fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_fs.close()
+
+    def test_batched_put_and_get(self, remote_backend_with_fs):
+        """Test batched put and get operations."""
+        keys = [create_test_key(i) for i in range(3)]
+        memory_objs = [create_test_memory_obj() for _ in range(3)]
+
+        # Batched put
+        futures = [
+            remote_backend_with_fs.submit_put_task(key, memory_obj)
+            for key, memory_obj in zip(keys, memory_objs, strict=False)
+        ]
+        for future in filter(None, futures):
+            future.result(timeout=5.0)
+
+        # Check all keys exist
+        for key in keys:
+            assert remote_backend_with_fs.contains(key)
+
+        # Batched get
+        results = remote_backend_with_fs.batched_get_blocking(keys)
+
+        assert results is not None
+        assert len(results) == 3
+        for result, original in zip(results, memory_objs, strict=False):
+            assert result is not None
+            assert result.metadata.shape == original.metadata.shape
+            assert result.metadata.dtype == original.metadata.dtype
+
+        remote_backend_with_fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_fs.close()
+
+    def test_multiple_paths_config(self, temp_fs_path, async_loop, local_cpu_backend):
+        """Test FSConnector with multiple paths."""
+        # Create additional temp directories
+        temp_dir2 = tempfile.mkdtemp()
+        temp_dir3 = tempfile.mkdtemp()
+
+        try:
+            # Create config with multiple paths
+            multi_path = f"{temp_fs_path},{temp_dir2},{temp_dir3}"
+            config = create_test_config(multi_path)
+            metadata = create_test_metadata()
+
+            backend = RemoteBackend(
+                config=config,
+                metadata=metadata,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cpu",
+            )
+
+            key = create_test_key(10)
+            memory_obj = create_test_memory_obj()
+
+            # Put and get should work with multiple paths
+            future = backend.submit_put_task(key, memory_obj)
+            if future:
+                future.result(timeout=5.0)
+
+            assert backend.contains(key)
+
+            result = backend.get_blocking(key)
+            assert result is not None
+            assert result.metadata.shape == memory_obj.metadata.shape
+
+            backend.local_cpu_backend.memory_allocator.close()
+            backend.close()
+
+        finally:
+            # Cleanup additional directories
+            if os.path.exists(temp_dir2):
+                shutil.rmtree(temp_dir2)
+            if os.path.exists(temp_dir3):
+                shutil.rmtree(temp_dir3)
+
+    def test_file_persistence(self, temp_fs_path, async_loop, local_cpu_backend):
+        """Test that files persist after backend closure."""
+        config = create_test_config(temp_fs_path)
+        metadata = create_test_metadata()
+
+        key = create_test_key(5)
+        memory_obj = create_test_memory_obj()
+
+        # Create backend, put data, and close
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        future = backend.submit_put_task(key, memory_obj)
+        if future:
+            future.result(timeout=5.0)
+
+        backend.local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+        # Create new backend instance and verify data persists
+        new_local_cpu_backend = LocalCPUBackend(
+            LMCacheEngineConfig.from_legacy(chunk_size=256),
+            local_cpu_backend.metadata,
+            memory_allocator=local_cpu_backend.memory_allocator,
+        )
+        new_backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=new_local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        assert new_backend.contains(key)
+
+        result = new_backend.get_blocking(key)
+        assert result is not None
+        assert result.metadata.shape == memory_obj.metadata.shape
+
+        new_backend.local_cpu_backend.memory_allocator.close()
+        new_backend.close()
diff --git a/tests/v1/storage_backend/test_gds_backend.py b/tests/v1/storage_backend/test_gds_backend.py
new file mode 100644
index 0000000..2746f7d
--- /dev/null
+++ b/tests/v1/storage_backend/test_gds_backend.py
@@ -0,0 +1,1057 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest import mock
+import asyncio
+import os
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import urllib.parse
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey, LayerCacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.gds_backend import (
+    _DATA_FILE_SUFFIX,
+    _METADATA_FILE_SUFFIX,
+    _METADATA_VERSION,
+    GdsBackend,
+    UnsupportedMetadataVersion,
+    get_extra_config_bool,
+    pack_metadata,
+    unpack_metadata,
+)
+from tests.v1.utils import create_test_memory_obj, has_cufile, has_hipfile
+
+# Optional override for tempfile root. In CI we point this at a GDS-capable
+# host-backed mount (see .buildkite/k3_tests/unit/run.sh); locally, it's
+# unset and tempfile falls back to its default (usually /tmp). cuFile needs
+# direct-I/O-capable storage (ext4/xfs on real disk); overlayfs and tmpfs
+# fail with CU_FILE_IO_NOT_SUPPORTED (err=5027).
+_TEST_TMPDIR = os.environ.get("LMCACHE_TEST_TMPDIR") or None
+
+
+def create_test_config(gds_path: str, gds_path_sharding: str = "by_gpu"):
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        gds_path=gds_path,
+        gds_path_sharding=gds_path_sharding,
+        lmcache_instance_id="test_instance",
+        gds_buffer_size=256,
+        extra_config={"use_direct_io": True},
+    )
+    return config
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    # NO UNDERSCORE HERE for model_name
+    return CacheEngineKey(
+        model_name="testmodel",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=key_id,
+        dtype=torch.bfloat16,
+    )
+
+
+def create_test_layer_key(key_id: int = 0, layer_id: int = 0) -> LayerCacheEngineKey:
+    """Create a LayerCacheEngineKey for testing layer-wise GDS operations."""
+    return LayerCacheEngineKey(
+        model_name="testmodel",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=key_id,
+        dtype=torch.bfloat16,
+        layer_id=layer_id,
+    )
+
+
+def create_test_metadata():
+    """Create a test metadata for LMCacheMetadata."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(28, 2, 256, 8, 128),
+    )
+
+
+@pytest.fixture
+def temp_gds_path():
+    temp_dir = tempfile.mkdtemp(dir=_TEST_TMPDIR)
+    yield temp_dir
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir)
+
+
+@pytest.fixture
+def async_loop():
+    loop = asyncio.new_event_loop()
+    thread = threading.Thread(target=loop.run_forever)
+    thread.start()
+    yield loop
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join()
+    loop.close()
+
+
+@pytest.fixture
+def gds_backend(temp_gds_path, async_loop):
+    config = create_test_config(temp_gds_path)
+    metadata = create_test_metadata()
+    return GdsBackend(
+        config=config,
+        loop=async_loop,
+        metadata=metadata,
+        dst_device="cuda:0",
+    )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Requires CUDA for TestGdsBackend",
+)
+@pytest.mark.skipif(
+    not (has_cufile() or has_hipfile()),
+    reason="Requires NVIDIA cuFile (libcufile.so) or AMD hipFile (libhipfile.so). "
+    "Skipping on systems without GDS support.",
+)
+@pytest.mark.skipif(sys.platform != "linux", reason="TestGdsBackend runs only on Linux")
+class TestGdsBackend:
+    def test_init(self, temp_gds_path, async_loop):
+        config = create_test_config(temp_gds_path)
+        metadata = create_test_metadata()
+        backend = GdsBackend(
+            config=config,
+            loop=async_loop,
+            metadata=metadata,
+            dst_device="cuda:0",
+        )
+        assert backend.gds_path == temp_gds_path
+        assert backend.dst_device == "cuda:0"
+        assert os.path.exists(temp_gds_path)
+
+    def test_str(self, gds_backend):
+        assert str(gds_backend) == "GdsBackend"
+
+    def test_key_to_path_and_insert_key(self, gds_backend):
+        key = create_test_key(0)
+        memory_obj = create_test_memory_obj(device="cuda")
+        gds_backend.insert_key(key, memory_obj)
+        # Check that the key is in hot_cache
+        assert key in gds_backend.hot_cache
+        meta = gds_backend.hot_cache[key]
+        assert meta.shape == memory_obj.metadata.shape
+        assert meta.dtype == memory_obj.metadata.dtype
+
+    def test_contains_key_not_exists(self, gds_backend):
+        key = create_test_key(1)
+        assert not gds_backend.contains(key)
+        assert not gds_backend.contains(key, pin=True)
+
+    def test_contains_key_exists(self, gds_backend):
+        key = create_test_key(0)
+        memory_obj = create_test_memory_obj(device="cuda")
+        gds_backend.insert_key(key, memory_obj)
+        assert gds_backend.contains(key)
+        assert gds_backend.contains(key, pin=True)
+
+    def test_exists_in_put_tasks(self, gds_backend):
+        key = create_test_key(0)
+        assert not gds_backend.exists_in_put_tasks(key)
+        # Simulate adding to put_tasks
+        with gds_backend.put_lock:
+            gds_backend.put_tasks.add(key)
+        assert gds_backend.exists_in_put_tasks(key)
+
+    @pytest.mark.asyncio
+    @pytest.mark.skipif(
+        not torch.cuda.is_available(),
+        reason="Requires CUDA for GdsBackend get_blocking",
+    )
+    @pytest.mark.skipif(
+        not (has_cufile() or has_hipfile()),
+        reason="Requires NVIDIA cuFile (libcufile.so) or AMD hipFile (libhipfile.so). "
+        "Skipping on systems without GDS support.",
+    )
+    async def test_submit_put_task_and_get_blocking(self, gds_backend):
+        key = create_test_key(0)
+        memory_obj = create_test_memory_obj(device="cuda")
+        # submit_put_task returns a Future
+        future = gds_backend.submit_put_task(key, memory_obj)
+        assert future is not None
+        # Wait for the async save to complete
+        future.result(timeout=5)
+        # Now the key should be in hot_cache
+        assert gds_backend.contains(key)
+        # get_blocking should return a MemoryObj (may be None if not CUDA)
+        result = gds_backend.get_blocking(key)
+        # On CPU, _load_bytes_from_disk may not work,
+        # so just check for None or MemoryObj
+        assert result is None or isinstance(result, MemoryObj)
+
+    @pytest.mark.asyncio
+    async def test_batched_submit_put_task(self, gds_backend):
+        keys = [create_test_key(i) for i in range(2, 5)]
+        memory_objs = [create_test_memory_obj(device="cuda") for _ in range(3)]
+        futures = gds_backend.batched_submit_put_task(keys, memory_objs)
+        assert futures is not None
+        assert len(futures) == 3
+        for future in futures:
+            assert future is not None
+            future.result(timeout=5)
+        for key in keys:
+            assert gds_backend.contains(key)
+
+    def test_get_blocking_key_not_exists(self, gds_backend):
+        key = create_test_key(1)
+        result = gds_backend.get_blocking(key)
+        assert result is None
+
+    # Error handling tests
+    def test_try_to_read_metadata_file_not_found(self, gds_backend, temp_gds_path):
+        """Test that FileNotFoundError is handled gracefully."""
+        key = create_test_key(400)
+
+        # Create a path that doesn't exist
+        result = gds_backend._try_to_read_metadata(key)
+        assert result is None
+
+    def test_try_to_read_metadata_permission_error(self, gds_backend, temp_gds_path):
+        """Test that PermissionError is handled gracefully."""
+        key = create_test_key(401)
+        path, subdir_key, l1_dir, l2_dir = gds_backend._key_to_path(key)
+        metadata_path = path + _METADATA_FILE_SUFFIX
+
+        # Create metadata file
+        os.makedirs(os.path.join(temp_gds_path, l1_dir, l2_dir), exist_ok=True)
+        memory_obj = create_test_memory_obj(device="cuda")
+        metadata = pack_metadata(
+            memory_obj.tensor,
+            fmt=memory_obj.metadata.fmt,
+            lmcache_version=str(_METADATA_VERSION),
+        )
+        with open(metadata_path, "wb") as f:
+            f.write(metadata)
+
+        # Mock _read_metadata to raise PermissionError
+        original_read_metadata = gds_backend._read_metadata
+
+        def failing_read_metadata(*args, **kwargs):
+            raise PermissionError("Simulated permission denied")
+
+        gds_backend._read_metadata = failing_read_metadata
+
+        try:
+            result = gds_backend._try_to_read_metadata(key)
+            assert result is None
+        finally:
+            gds_backend._read_metadata = original_read_metadata
+
+    def test_try_to_read_metadata_unsupported_version(self, gds_backend, temp_gds_path):
+        """Test that UnsupportedMetadataVersion is handled gracefully."""
+        key = create_test_key(402)
+        path, subdir_key, l1_dir, l2_dir = gds_backend._key_to_path(key)
+        metadata_path = path + _METADATA_FILE_SUFFIX
+
+        os.makedirs(os.path.join(temp_gds_path, l1_dir, l2_dir), exist_ok=True)
+
+        # Mock _read_metadata to raise UnsupportedMetadataVersion
+        original_read_metadata = gds_backend._read_metadata
+
+        def failing_read_metadata(*args, **kwargs):
+            raise UnsupportedMetadataVersion("Unsupported version")
+
+        gds_backend._read_metadata = failing_read_metadata
+
+        # Create a dummy file so os.path.exists returns True
+        with open(metadata_path, "wb") as f:
+            f.write(b"dummy")
+
+        try:
+            result = gds_backend._try_to_read_metadata(key)
+            assert result is None
+        finally:
+            gds_backend._read_metadata = original_read_metadata
+
+    def test_try_to_read_metadata_io_error(self, gds_backend, temp_gds_path):
+        """Test that OSError/IOError is handled gracefully."""
+        key = create_test_key(403)
+        path, subdir_key, l1_dir, l2_dir = gds_backend._key_to_path(key)
+        metadata_path = path + _METADATA_FILE_SUFFIX
+
+        os.makedirs(os.path.join(temp_gds_path, l1_dir, l2_dir), exist_ok=True)
+
+        # Mock _read_metadata to raise IOError
+        original_read_metadata = gds_backend._read_metadata
+
+        def failing_read_metadata(*args, **kwargs):
+            raise IOError("Simulated I/O error")
+
+        gds_backend._read_metadata = failing_read_metadata
+
+        # Create a dummy file
+        with open(metadata_path, "wb") as f:
+            f.write(b"dummy")
+
+        try:
+            result = gds_backend._try_to_read_metadata(key)
+            assert result is None
+        finally:
+            gds_backend._read_metadata = original_read_metadata
+
+    def test_try_to_read_metadata_generic_exception(self, gds_backend, temp_gds_path):
+        """Test that generic exceptions are handled gracefully."""
+        key = create_test_key(404)
+        path, subdir_key, l1_dir, l2_dir = gds_backend._key_to_path(key)
+        metadata_path = path + _METADATA_FILE_SUFFIX
+
+        os.makedirs(os.path.join(temp_gds_path, l1_dir, l2_dir), exist_ok=True)
+
+        # Mock _read_metadata to raise a generic exception
+        original_read_metadata = gds_backend._read_metadata
+
+        def failing_read_metadata(*args, **kwargs):
+            raise RuntimeError("Unexpected error")
+
+        gds_backend._read_metadata = failing_read_metadata
+
+        # Create a dummy file
+        with open(metadata_path, "wb") as f:
+            f.write(b"dummy")
+
+        try:
+            result = gds_backend._try_to_read_metadata(key)
+            assert result is None
+        finally:
+            gds_backend._read_metadata = original_read_metadata
+
+    @pytest.mark.asyncio
+    async def test_async_save_bytes_to_disk_write_error_handling(
+        self, gds_backend, temp_gds_path
+    ):
+        """Test error handling when GDS write operation fails."""
+        key = create_test_key(300)
+        memory_obj = create_test_memory_obj(device="cuda")
+        memory_obj.ref_count_up()
+
+        # Mock _save_gds to raise an exception
+        original_save_gds = gds_backend._save_gds
+
+        def failing_save_gds(*args, **kwargs):
+            raise IOError("Simulated GDS write failure")
+
+        gds_backend._save_gds = failing_save_gds
+
+        try:
+            # Call should not raise, but should handle error gracefully
+            await gds_backend._async_save_bytes_to_disk(key, memory_obj)
+
+            # Key should not be in cache after failed write
+            assert not gds_backend.contains(key)
+        finally:
+            gds_backend._save_gds = original_save_gds
+            memory_obj.ref_count_down()
+
+    @pytest.mark.asyncio
+    async def test_async_save_bytes_metadata_write_failure(
+        self, gds_backend, temp_gds_path
+    ):
+        """
+        Test that metadata write failures during task execution trigger cache cleanup.
+        """
+        key = create_test_key(500)
+        memory_obj = create_test_memory_obj(device="cuda")
+        memory_obj.ref_count_up()
+
+        # Mock save_metadata to raise an exception during execution
+        async def failing_save_metadata(path, tmp, metadata):
+            raise IOError("Simulated metadata write failure")
+
+        with mock.patch(
+            "lmcache.v1.storage_backend.gds_backend.save_metadata",
+            side_effect=failing_save_metadata,
+        ):
+            try:
+                await gds_backend._async_save_bytes_to_disk(key, memory_obj)
+
+                # Wait for the background task to complete and exception to be handled
+                await asyncio.sleep(0.2)
+
+                # Key should be removed from hot_cache after metadata write failure
+                with gds_backend.hot_lock:
+                    assert key not in gds_backend.hot_cache
+            finally:
+                memory_obj.ref_count_down()
+
+    def test_close(self, gds_backend):
+        # Should not raise
+        gds_backend.close()
+
+    def test_pin_unpin_not_implemented(self, gds_backend):
+        key = create_test_key(0)
+        assert not gds_backend.pin(key)
+        assert not gds_backend.unpin(key)
+
+    def test_weka_initialization_suffix(self, temp_gds_path, async_loop):
+        class DummyCuFileDriver:
+            def __init__(self):
+                pass
+
+        class DummyCuFile:
+            def __init__(self, *_, **__):
+                pass
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *args):
+                return False
+
+            def write(self, *_, **__):
+                return None
+
+            def read(self, *_, **__):
+                return 0
+
+        dummy_cufile_module = type(
+            "DummyCuFileModule",
+            (),
+            {"CuFileDriver": DummyCuFileDriver, "CuFile": DummyCuFile},
+        )()
+
+        with mock.patch.dict(sys.modules, {"cufile": dummy_cufile_module}):
+            with (
+                mock.patch(
+                    "lmcache.v1.storage_backend.gds_backend.get_fstype",
+                    return_value="wekafs",
+                ),
+                mock.patch.object(
+                    GdsBackend,
+                    "initialize_allocator",
+                    return_value=TestGdsBackend._DummyAllocator(),
+                ),
+            ):
+                config = create_test_config(temp_gds_path)
+                metadata = create_test_metadata()
+
+                backend = GdsBackend(
+                    config=config,
+                    loop=async_loop,
+                    metadata=metadata,
+                    dst_device="cuda:0",
+                )
+                try:
+                    key = create_test_key(0)
+                    path, _, _, _ = backend._key_to_path(key)
+                    assert path.endswith(".weka1")
+                    assert backend.data_suffix == ".weka1"
+                    assert backend.use_gds
+                finally:
+                    backend.close()
+
+    def test_weka_disallows_disabling_gds(self, temp_gds_path, async_loop):
+        class DummyAllocator:
+            def __init__(self):
+                self.base_pointer = 0
+
+            def close(self):
+                pass
+
+        with (
+            mock.patch(
+                "lmcache.v1.storage_backend.gds_backend.get_fstype",
+                return_value="wekafs",
+            ),
+            mock.patch.object(
+                GdsBackend,
+                "initialize_allocator",
+                return_value=DummyAllocator(),
+            ),
+        ):
+            config = create_test_config(temp_gds_path)
+            config.use_gds = False
+            metadata = create_test_metadata()
+
+            with pytest.raises(AssertionError):
+                GdsBackend(
+                    config=config,
+                    loop=async_loop,
+                    metadata=metadata,
+                    dst_device="cuda:0",
+                )
+
+    class _DummyAllocator:
+        def __init__(self) -> None:
+            self.base_pointer: int = 0
+
+        def close(self) -> None:
+            pass
+
+        def allocate(self, *args, **kwargs):
+            return None
+
+        def batched_allocate(self, *args, **kwargs):
+            return None
+
+        def memcheck(self) -> bool:
+            return True
+
+    @staticmethod
+    def _make_mocked_backend(
+        temp_gds_path: str,
+        async_loop: asyncio.AbstractEventLoop,
+        allocator=None,
+    ) -> GdsBackend:
+        """Return a GdsBackend with tmpfs mocked so GDS is auto-disabled."""
+        eff_allocator = allocator or TestGdsBackend._DummyAllocator()
+        config = create_test_config(temp_gds_path)
+        metadata = create_test_metadata()
+        with (
+            mock.patch(
+                "lmcache.v1.storage_backend.gds_backend.get_fstype",
+                return_value="tmpfs",
+            ),
+            mock.patch.object(
+                GdsBackend, "initialize_allocator", return_value=eff_allocator
+            ),
+            mock.patch(
+                "lmcache.v1.storage_backend.gds_backend.ctypes.CDLL",
+                return_value=mock.MagicMock(),
+            ),
+        ):
+            return GdsBackend(
+                config=config,
+                loop=async_loop,
+                metadata=metadata,
+                dst_device="cuda:0",
+            )
+
+    def test_allocate_retry_then_succeed(self, temp_gds_path, async_loop):
+        """allocate retries on None and returns the obj once the allocator succeeds."""
+        sentinel = object()
+        allocator = self._DummyAllocator()
+        allocator.allocate = mock.MagicMock(side_effect=[None, None, sentinel])
+        backend = self._make_mocked_backend(temp_gds_path, async_loop, allocator)
+        try:
+            backend.alloc_attempt_delay_secs = 0
+            backend.max_alloc_attempts = 5
+            result = backend.allocate(
+                torch.Size([2, 16, 8, 128]), torch.bfloat16, busy_loop=True
+            )
+            assert result is sentinel
+            assert allocator.allocate.call_count == 3
+        finally:
+            backend.close()
+
+    def test_allocate_busy_loop_false_single_attempt(self, temp_gds_path, async_loop):
+        """allocate with busy_loop=False makes exactly one attempt."""
+        allocator = self._DummyAllocator()
+        allocator.allocate = mock.MagicMock(return_value=None)
+        backend = self._make_mocked_backend(temp_gds_path, async_loop, allocator)
+        try:
+            backend.alloc_attempt_delay_secs = 0
+            backend.max_alloc_attempts = 10
+            backend.allocate(
+                torch.Size([2, 16, 8, 128]), torch.bfloat16, busy_loop=False
+            )
+            assert allocator.allocate.call_count == 1
+        finally:
+            backend.close()
+
+    def test_batched_allocate_retry_then_succeed(self, temp_gds_path, async_loop):
+        """batched_allocate retries on None and returns the list once it succeeds."""
+        sentinel = [object(), object()]
+        allocator = self._DummyAllocator()
+        allocator.batched_allocate = mock.MagicMock(side_effect=[None, sentinel])
+        backend = self._make_mocked_backend(temp_gds_path, async_loop, allocator)
+        try:
+            backend.alloc_attempt_delay_secs = 0
+            backend.max_alloc_attempts = 5
+            result = backend.batched_allocate(
+                torch.Size([2, 16, 8, 128]),
+                torch.bfloat16,
+                batch_size=2,
+                busy_loop=True,
+            )
+            assert result is sentinel
+            assert allocator.batched_allocate.call_count == 2
+        finally:
+            backend.close()
+
+    def test_batched_allocate_busy_loop_false_single_attempt(
+        self, temp_gds_path, async_loop
+    ):
+        """batched_allocate with busy_loop=False makes exactly one attempt."""
+        allocator = self._DummyAllocator()
+        allocator.batched_allocate = mock.MagicMock(return_value=None)
+        backend = self._make_mocked_backend(temp_gds_path, async_loop, allocator)
+        try:
+            backend.alloc_attempt_delay_secs = 0
+            backend.max_alloc_attempts = 10
+            backend.batched_allocate(
+                torch.Size([2, 16, 8, 128]),
+                torch.bfloat16,
+                batch_size=2,
+                busy_loop=False,
+            )
+            assert allocator.batched_allocate.call_count == 1
+        finally:
+            backend.close()
+
+    def test_batched_get_blocking_no_thread_pool(self, temp_gds_path, async_loop):
+        """batched_get_blocking returns None per missing key when thread pool is off."""
+        backend = self._make_mocked_backend(temp_gds_path, async_loop)
+        try:
+            assert not backend.use_thread_pool
+            keys = [create_test_key(i) for i in range(3)]
+            results = backend.batched_get_blocking(keys)
+            assert results == [None, None, None]
+        finally:
+            backend.close()
+
+    @pytest.mark.asyncio
+    async def test_batched_get_blocking_thread_pool(self, gds_backend):
+        """batched_get_blocking returns correct results via the thread pool."""
+        keys = [create_test_key(i) for i in range(700, 703)]
+        memory_objs = [create_test_memory_obj(device="cuda") for _ in keys]
+
+        futures = gds_backend.batched_submit_put_task(keys, memory_objs)
+        assert futures is not None
+        for f in futures:
+            f.result(timeout=10)
+
+        assert gds_backend.use_thread_pool
+        results = gds_backend.batched_get_blocking(keys)
+        assert len(results) == len(keys)
+        for orig, result in zip(memory_objs, results, strict=False):
+            assert result is not None
+            assert result.metadata.shape == orig.metadata.shape
+            assert result.metadata.dtype == orig.metadata.dtype
+
+    @pytest.mark.asyncio
+    async def test_on_complete_callback_invoked(self, gds_backend):
+        """on_complete_callback is called with the key after the write finishes."""
+        key = create_test_key(600)
+        memory_obj = create_test_memory_obj(device="cuda")
+        received: list = []
+
+        future = gds_backend.submit_put_task(
+            key, memory_obj, on_complete_callback=lambda k: received.append(k)
+        )
+        future.result(timeout=10)
+
+        assert received == [key]
+
+    @pytest.mark.asyncio
+    async def test_on_complete_callback_exception_does_not_propagate(self, gds_backend):
+        """A callback that raises must not crash the put pipeline."""
+        key = create_test_key(601)
+        memory_obj = create_test_memory_obj(device="cuda")
+
+        def bad_callback(k: CacheEngineKey) -> None:
+            raise RuntimeError("intentional callback error")
+
+        future = gds_backend.submit_put_task(
+            key, memory_obj, on_complete_callback=bad_callback
+        )
+        future.result(timeout=10)
+        assert gds_backend.contains(key)
+
+    def test_scan_metadata_layer_key(self, temp_gds_path, async_loop):
+        """
+        _scan_metadata_subdir must reconstruct LayerCacheEngineKey filenames with
+        a trailing layer_id (e.g. ...@dtype@4).
+        """
+        config = create_test_config(temp_gds_path)
+        metadata = create_test_metadata()
+        backend = GdsBackend(
+            config=config,
+            loop=async_loop,
+            metadata=metadata,
+            dst_device="cuda:0",
+        )
+
+        layer_key = create_test_layer_key(0xABCD, 4)
+
+        memory_obj = create_test_memory_obj(device="cuda")
+        future = backend.submit_put_task(layer_key, memory_obj)
+        future.result(timeout=10)
+        memory_obj.ref_count_down()
+        # Wait for async metadata write to land
+        backend.close()
+
+        # Re-create backend, which triggers _scan_metadata
+        backend2 = GdsBackend(
+            config=config,
+            loop=async_loop,
+            metadata=metadata,
+            dst_device="cuda:0",
+        )
+        # Wait for the background scan to complete
+        time.sleep(1)
+        assert layer_key in backend2.hot_cache
+        backend2.close()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Requires CUDA for TestGdsMultiPath",
+)
+@pytest.mark.skipif(sys.platform != "linux", reason="Runs only on Linux")
+class TestGdsMultiPath:
+    """Tests for multi-path GDS backend support.
+
+    Verifies comma-separated gds_path parsing, GPU-to-NVMe affinity
+    (by_gpu sharding), directory creation for all paths, and backward
+    compatibility with single-path configs.
+    """
+
+    @staticmethod
+    def _make_backend(
+        gds_path: str,
+        dst_device: str,
+        async_loop,
+        gds_path_sharding: str = "by_gpu",
+    ):
+        """Create a GdsBackend with mocked allocator and fstype.
+
+        Mocks are used so the tests run without cuFile / real NVMe.
+        """
+
+        class DummyAllocator:
+            def __init__(self):
+                self.base_pointer = 0
+
+            def close(self):
+                pass
+
+        config = create_test_config(gds_path, gds_path_sharding=gds_path_sharding)
+        metadata = create_test_metadata()
+        with (
+            mock.patch(
+                "lmcache.v1.storage_backend.gds_backend.get_fstype",
+                return_value="tmpfs",
+            ),
+            mock.patch.object(
+                GdsBackend,
+                "initialize_allocator",
+                return_value=DummyAllocator(),
+            ),
+            mock.patch(
+                "lmcache.v1.storage_backend.gds_backend.ctypes.CDLL",
+                return_value=mock.MagicMock(),
+            ),
+        ):
+            backend = GdsBackend(
+                config=config,
+                loop=async_loop,
+                metadata=metadata,
+                dst_device=dst_device,
+            )
+        return backend
+
+    def test_single_path_backward_compat(self, temp_gds_path, async_loop):
+        """A single gds_path (no commas) behaves like before."""
+        backend = self._make_backend(temp_gds_path, "cuda:0", async_loop)
+        try:
+            assert backend.gds_paths == [temp_gds_path]
+            assert backend.gds_path == temp_gds_path
+        finally:
+            backend.close()
+
+    def test_multi_path_parsing(self, async_loop):
+        """Comma-separated paths are split into gds_paths list."""
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(3)]
+        try:
+            gds_path = ",".join(paths)
+            backend = self._make_backend(gds_path, "cuda:0", async_loop)
+            try:
+                assert backend.gds_paths == paths
+                assert len(backend.gds_paths) == 3
+            finally:
+                backend.close()
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_multi_path_parsing_with_spaces(self, async_loop):
+        """Spaces around commas are stripped."""
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(2)]
+        try:
+            gds_path = f"  {paths[0]}  ,  {paths[1]}  "
+            backend = self._make_backend(gds_path, "cuda:0", async_loop)
+            try:
+                assert backend.gds_paths == paths
+            finally:
+                backend.close()
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_gpu_affinity_selects_path(self, async_loop):
+        """Different cuda devices select different paths via modulo."""
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(4)]
+        try:
+            gds_path = ",".join(paths)
+            for device_id in range(8):
+                dst = f"cuda:{device_id}"
+                backend = self._make_backend(gds_path, dst, async_loop)
+                try:
+                    expected = paths[device_id % 4]
+                    assert backend.gds_path == expected, (
+                        f"cuda:{device_id} should map to {expected}, "
+                        f"got {backend.gds_path}"
+                    )
+                finally:
+                    backend.close()
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_all_directories_created(self, async_loop):
+        """All paths in gds_paths get their directories created."""
+        base = tempfile.mkdtemp(dir=_TEST_TMPDIR)
+        try:
+            paths = [os.path.join(base, f"nvme{i}") for i in range(3)]
+            gds_path = ",".join(paths)
+            backend = self._make_backend(gds_path, "cuda:0", async_loop)
+            try:
+                for p in paths:
+                    assert os.path.isdir(p), f"{p} should exist"
+            finally:
+                backend.close()
+        finally:
+            shutil.rmtree(base, ignore_errors=True)
+
+    def test_key_to_path_uses_selected_path(self, async_loop):
+        """_key_to_path builds file paths under the selected gds_path."""
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(2)]
+        try:
+            gds_path = ",".join(paths)
+            backend = self._make_backend(gds_path, "cuda:0", async_loop)
+            try:
+                key = create_test_key(0)
+                file_path, _, _, _ = backend._key_to_path(key)
+                assert file_path.startswith(backend.gds_path)
+            finally:
+                backend.close()
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_deterministic_path_selection(self, async_loop):
+        """Same device always selects the same path."""
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(3)]
+        try:
+            gds_path = ",".join(paths)
+            selected = set()
+            for _ in range(5):
+                backend = self._make_backend(gds_path, "cuda:1", async_loop)
+                try:
+                    selected.add(backend.gds_path)
+                finally:
+                    backend.close()
+            assert len(selected) == 1, "Path selection should be deterministic"
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_scan_discovers_entries_across_all_paths(self, async_loop):
+        """Startup scan finds metadata written under a non-affinity path.
+
+        cuda:0 has affinity to paths[0], but a metadata file is placed
+        under paths[1].  The scan should still discover it because
+        ``_scan_metadata`` iterates all ``gds_paths``.
+        """
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(2)]
+        try:
+            # chunk_hash must have >=4 decimal digits so l1/l2 dirs
+            # are each 2 chars (the scanner filters on len == 2).
+            key = CacheEngineKey(
+                model_name="testmodel",
+                world_size=3,
+                worker_id=1,
+                chunk_hash=1234,
+                dtype=torch.bfloat16,
+            )
+            hash_str = str(key.chunk_hash)
+            l1_dir = hash_str[:2]
+            l2_dir = hash_str[2:4]
+            key_str = urllib.parse.quote(key.to_string(), safe="")
+
+            # Build directory structure under paths[1] (non-affinity path)
+            subdir = os.path.join(paths[1], l1_dir, l2_dir)
+            os.makedirs(subdir, exist_ok=True)
+
+            # Write a valid metadata file
+            dummy_tensor = torch.zeros(2, 256, 8, 128, dtype=torch.bfloat16)
+            metadata_bytes = pack_metadata(
+                dummy_tensor,
+                fmt=MemoryFormat.KV_2LTD,
+                lmcache_version="1",
+            )
+            meta_path = os.path.join(
+                subdir,
+                key_str + _DATA_FILE_SUFFIX + _METADATA_FILE_SUFFIX,
+            )
+            with open(meta_path, "wb") as f:
+                f.write(metadata_bytes)
+
+            # Create backend — cuda:0 affinity selects paths[0]
+            gds_path = ",".join(paths)
+            backend = self._make_backend(gds_path, "cuda:0", async_loop)
+            try:
+                assert backend.gds_path == paths[0]
+
+                # Wait for the async _scan_metadata to finish
+                time.sleep(1)
+
+                # contains() would NOT find this via _try_to_read_metadata
+                # (which only checks the affinity path).  If it returns
+                # True, the cross-path scan populated hot_cache.
+                assert backend.contains(key), (
+                    "Scan should discover metadata across all gds_paths"
+                )
+            finally:
+                backend.close()
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_try_to_read_metadata_finds_across_all_paths(self, async_loop):
+        """contains() fallback finds metadata on a non-affinity path.
+
+        After clearing hot_cache (so the startup scan results are gone),
+        ``contains()`` falls back to ``_try_to_read_metadata`` which
+        should search all ``gds_paths``, not just the affinity path.
+        """
+        paths = [tempfile.mkdtemp(dir=_TEST_TMPDIR) for _ in range(2)]
+        try:
+            key = CacheEngineKey(
+                model_name="testmodel",
+                world_size=3,
+                worker_id=1,
+                chunk_hash=1234,
+                dtype=torch.bfloat16,
+            )
+            hash_str = str(key.chunk_hash)
+            l1_dir = hash_str[:2]
+            l2_dir = hash_str[2:4]
+            key_str = urllib.parse.quote(key.to_string(), safe="")
+
+            # Place metadata under paths[1] (non-affinity path)
+            subdir = os.path.join(paths[1], l1_dir, l2_dir)
+            os.makedirs(subdir, exist_ok=True)
+
+            dummy_tensor = torch.zeros(2, 256, 8, 128, dtype=torch.bfloat16)
+            metadata_bytes = pack_metadata(
+                dummy_tensor,
+                fmt=MemoryFormat.KV_2LTD,
+                lmcache_version="1",
+            )
+            meta_path = os.path.join(
+                subdir,
+                key_str + _DATA_FILE_SUFFIX + _METADATA_FILE_SUFFIX,
+            )
+            with open(meta_path, "wb") as f:
+                f.write(metadata_bytes)
+
+            gds_path = ",".join(paths)
+            backend = self._make_backend(gds_path, "cuda:0", async_loop)
+            try:
+                assert backend.gds_path == paths[0]
+
+                # Wait for async scan, then clear its results
+                time.sleep(1)
+                with backend.hot_lock:
+                    backend.hot_cache.clear()
+
+                # contains() now relies solely on _try_to_read_metadata
+                assert backend.contains(key), (
+                    "_try_to_read_metadata should search all gds_paths"
+                )
+            finally:
+                backend.close()
+        finally:
+            for p in paths:
+                shutil.rmtree(p, ignore_errors=True)
+
+    def test_gds_path_sharding_default(self, temp_gds_path, async_loop):
+        """Default gds_path_sharding is 'by_gpu' (backend inits OK)."""
+        backend = self._make_backend(temp_gds_path, "cuda:0", async_loop)
+        try:
+            assert backend.gds_path == temp_gds_path
+        finally:
+            backend.close()
+
+    def test_gds_path_sharding_explicit_by_gpu(self, temp_gds_path, async_loop):
+        """Explicitly setting gds_path_sharding='by_gpu' works."""
+        backend = self._make_backend(
+            temp_gds_path,
+            "cuda:0",
+            async_loop,
+            gds_path_sharding="by_gpu",
+        )
+        try:
+            assert backend.gds_path == temp_gds_path
+        finally:
+            backend.close()
+
+    def test_gds_path_sharding_unsupported_raises(self, temp_gds_path, async_loop):
+        """Unsupported gds_path_sharding value raises ValueError."""
+        with pytest.raises(ValueError, match="Unsupported path sharding strategy"):
+            self._make_backend(
+                temp_gds_path,
+                "cuda:0",
+                async_loop,
+                gds_path_sharding="round_robin",
+            )
+
+
+def test_get_extra_config_bool_valid_inputs():
+    """String, uppercase string, literal bool, and missing key all parse correctly."""
+    config = create_test_config("/tmp")
+    config.extra_config = {
+        "str_true": "true",
+        "str_false": "FALSE",
+        "lit_true": True,
+        "lit_false": False,
+    }
+    assert get_extra_config_bool("str_true", config) is True
+    assert get_extra_config_bool("str_false", config) is False
+    assert get_extra_config_bool("lit_true", config) is True
+    assert get_extra_config_bool("lit_false", config) is False
+    assert get_extra_config_bool("missing", config) is None
+
+
+def test_get_extra_config_bool_invalid_value_raises():
+    """Non-bool non-string value raises RuntimeError."""
+    config = create_test_config("/tmp")
+    config.extra_config = {"flag": 42}
+    with pytest.raises(RuntimeError, match="Invalid value"):
+        get_extra_config_bool("flag", config)
+
+
+def test_pack_unpack_metadata_multiple_dtypes():
+    """pack_metadata / unpack_metadata roundtrip is correct for several dtypes."""
+    for dtype in [torch.float32, torch.float16, torch.bfloat16, torch.int8]:
+        tensor = torch.zeros(4, 8, dtype=dtype)
+        packed = pack_metadata(tensor, fmt=MemoryFormat.KV_2LTD, tag="test")
+        shape, out_dtype, nbytes, fmt, extra = unpack_metadata(packed)
+        assert shape == tensor.shape
+        assert out_dtype == dtype
+        assert nbytes == tensor.numel() * tensor.element_size()
+        assert fmt == MemoryFormat.KV_2LTD
+        assert extra["tag"] == "test"
diff --git a/tests/v1/storage_backend/test_hf3fs_connector.py b/tests/v1/storage_backend/test_hf3fs_connector.py
new file mode 100644
index 0000000..784b739
--- /dev/null
+++ b/tests/v1/storage_backend/test_hf3fs_connector.py
@@ -0,0 +1,656 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026 Samsung Electronics Co., Ltd.All Rights Reserved
+# Authors:
+#   Wenwen Chen <wenwen.chen@samsung.com>
+
+"""
+Test cases for HF3fsConnector storage backend.
+
+This module tests the HF3fsConnector which provides access to 3FS
+distributed filesystem using Usrbio interfaces.
+
+Note: These tests use mock fixtures to simulate 3FS filesystem without
+requiring actual 3FS hardware or hf3fs_fuse package.
+"""
+
+# Standard
+from pathlib import Path
+import asyncio
+import os
+import shutil
+import tempfile
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+from tests.v1.utils import create_test_memory_obj
+
+# 2nd dim should equal to chunk size
+# converted shape is [2, 28, 256, 1024] (8×128=1024)
+# byte size: 2 × 28 × 256 × 1024 × 2 (bfloat16) = 29,360,128 = 28MB
+DEFAULT_KV_SHAPE = (28, 2, 256, 8, 128)
+DEFAULT_SHAPE = torch.Size([2, 28, 256, 1024])
+DEFAULT_DTYPE = torch.bfloat16
+DEFAULT_CHUNK_SIZE = 256
+
+
+def create_test_config(
+    base_path: str,
+    mount_point: str,
+    iov_size: int = 209715200,
+    ior_entries: int = 256,
+    io_depth: int = 0,
+    numa_id: int = -1,
+    io_thread_num: int = 4,
+) -> LMCacheEngineConfig:
+    """Create a test configuration for HF3fsConnector.
+
+    Args:
+        base_path: Base path for storage
+        mount_point: 3FS mount point
+        iov_size: Shared memory size for Iov
+        ior_entries: Max num of concurrent requests
+        io_depth: I/O depth
+        numa_id: NUMA ID
+        io_thread_num: Number of IO threads
+
+    Returns:
+        LMCacheEngineConfig configured for HF3FS
+    """
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=DEFAULT_CHUNK_SIZE,
+        remote_url=f"hf3fs://{base_path}",
+        remote_serde="naive",
+        lmcache_instance_id="test_hf3fs_instance",
+        extra_config={
+            "save_chunk_meta": True,
+            "hf3fs_mount_point": mount_point,
+            "hf3fs_iov_size": iov_size,
+            "hf3fs_ior_entries": ior_entries,
+            "hf3fs_io_depth": io_depth,
+            "hf3fs_numa_id": numa_id,
+            "hf3fs_io_thread_num": io_thread_num,
+        },
+    )
+    return config
+
+
+def create_test_config_with_plugin(
+    base_path: str,
+    mount_point: str,
+    plugin_name: str = "hf3fs",
+) -> LMCacheEngineConfig:
+    """Create a test configuration for HF3fsConnector using remote_storage_plugins.
+
+    Args:
+        base_path: Base path for storage
+        mount_point: 3FS mount point
+        plugin_name: Plugin instance name
+
+    Returns:
+        LMCacheEngineConfig configured for HF3FS with plugin
+    """
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=DEFAULT_CHUNK_SIZE,
+        remote_storage_plugins=[plugin_name],
+        remote_serde="naive",
+        lmcache_instance_id="test_hf3fs_plugin_instance",
+        extra_config={
+            f"remote_storage_plugin.{plugin_name}.base_path": base_path,
+            "hf3fs_mount_point": mount_point,
+            "hf3fs_iov_size": 209715200,
+            "hf3fs_ior_entries": 256,
+            "hf3fs_io_depth": 0,
+            "hf3fs_numa_id": -1,
+            "hf3fs_io_thread_num": 4,
+        },
+    )
+    return config
+
+
+def create_test_metadata() -> LMCacheMetadata:
+    """Create a test metadata for LMCacheMetadata.
+
+    Returns:
+        LMCacheMetadata with test configuration
+    """
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=DEFAULT_DTYPE,
+        kv_shape=DEFAULT_KV_SHAPE,
+    )
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    """Create a test CacheEngineKey.
+
+    Args:
+        key_id: Key ID for testing
+
+    Returns:
+        CacheEngineKey with test configuration
+    """
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+@pytest.fixture
+def temp_3fs_path():
+    """Create a temporary directory for 3FS storage tests.
+
+    Note: This is a local temp directory for testing.
+    In real 3FS environment, this would be a path under the 3FS mount point.
+    """
+    temp_dir = tempfile.mkdtemp(prefix="hf3fs_test_")
+    yield temp_dir
+    # Cleanup
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+@pytest.fixture
+def mock_3fs_mount_point(tmp_path):
+    """Provide a mock 3FS mount point using a temporary directory.
+
+    Creates a directory structure that mimics 3FS mount point:
+    - mock_3fs_mount/3fs-virt/
+
+    Returns:
+        str: Path to the mock 3FS mount point
+    """
+    mock_mount = tmp_path / "mock_3fs_mount"
+    mock_mount.mkdir()
+    # Create the 3fs-virt directory structure that HF3FS expects
+    virt_dir = mock_mount / "3fs-virt"
+    virt_dir.mkdir()
+    return str(mock_mount)
+
+
+@pytest.fixture
+def mock_base_path(mock_3fs_mount_point):
+    """Provide a mock base path under the mock 3FS mount point.
+
+    Returns:
+        str: Path to the mock base storage directory
+    """
+    base_path = Path(mock_3fs_mount_point) / "3fs-virt" / "test_data"
+    base_path.mkdir(parents=True, exist_ok=True)
+    return str(base_path)
+
+
+@pytest.fixture
+def async_loop():
+    """Create an asyncio event loop running in a separate thread for testing."""
+    loop = asyncio.new_event_loop()
+
+    # Start the event loop in a separate thread
+    # Standard
+    import threading
+
+    # First Party
+    from lmcache.utils import start_loop_in_thread_with_exceptions
+
+    thread = threading.Thread(
+        target=start_loop_in_thread_with_exceptions,
+        args=(loop,),
+        name="test-hf3fs-async-loop",
+    )
+    thread.start()
+
+    yield loop
+
+    # Cleanup: stop the loop and wait for thread to finish
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=5.0)
+
+
+@pytest.fixture
+def memory_allocator():
+    """Create a memory allocator for testing."""
+    # First Party
+    from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import (
+        AdHocMemoryAllocator,
+    )
+
+    return AdHocMemoryAllocator(device="cpu")
+
+
+@pytest.fixture
+def local_cpu_backend(memory_allocator):
+    """Create a LocalCPUBackend for testing."""
+    config = LMCacheEngineConfig.from_legacy(chunk_size=DEFAULT_CHUNK_SIZE)
+    metadata = create_test_metadata()
+    backend = LocalCPUBackend(config, metadata, memory_allocator=memory_allocator)
+    yield backend
+    memory_allocator.close()
+
+
+@pytest.fixture
+def remote_backend_with_hf3fs(
+    mock_base_path, mock_3fs_mount_point, async_loop, local_cpu_backend
+):
+    """Create a RemoteBackend with HF3fsConnector for testing.
+
+    Args:
+        mock_base_path: Temporary directory for storage
+        mock_3fs_mount_point: Mock 3FS mount point
+        async_loop: Asyncio event loop
+        local_cpu_backend: Local CPU backend
+
+    Returns:
+        RemoteBackend configured with HF3fsConnector
+    """
+    config = create_test_config(
+        base_path=mock_base_path,
+        mount_point=mock_3fs_mount_point,
+    )
+    metadata = create_test_metadata()
+    print(f"metadata = {metadata}")
+    backend = RemoteBackend(
+        config=config,
+        metadata=metadata,
+        loop=async_loop,
+        local_cpu_backend=local_cpu_backend,
+        dst_device="cpu",
+    )
+    yield backend
+    # Cleanup
+    try:
+        if hasattr(backend, "local_cpu_backend") and backend.local_cpu_backend:
+            backend.local_cpu_backend.memory_allocator.close()
+    except Exception:
+        pass
+    try:
+        backend.close()
+    except Exception:
+        pass
+
+
+class TestHF3fsConnector:
+    """Test cases for HF3fsConnector via RemoteBackend."""
+
+    def test_init(
+        self, mock_base_path, mock_3fs_mount_point, async_loop, local_cpu_backend
+    ):
+        """Test HF3fsConnector initialization via RemoteBackend.
+
+        This test verifies that the HF3fsConnector can be properly
+        initialized with the required configuration parameters.
+        """
+        config = create_test_config(
+            base_path=mock_base_path,
+            mount_point=mock_3fs_mount_point,
+        )
+        metadata = create_test_metadata()
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        # Verify backend configuration
+        assert backend.dst_device == "cpu"
+        assert backend.local_cpu_backend == local_cpu_backend
+        assert backend.remote_url == f"hf3fs://{mock_base_path}"
+        assert backend.config.remote_serde == "naive"
+
+        # Verify storage path exists
+        assert os.path.exists(mock_base_path)
+
+        local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+    def test_init_with_plugin(
+        self, mock_base_path, mock_3fs_mount_point, async_loop, local_cpu_backend
+    ):
+        """Test HF3fsConnector initialization via RemoteBackend using
+        remote_storage_plugins. This test verifies that the HF3fsConnector can be
+        initialized using the plugin configuration pattern.
+        """
+        config = create_test_config_with_plugin(
+            base_path=mock_base_path,
+            mount_point=mock_3fs_mount_point,
+            plugin_name="hf3fs",
+        )
+        metadata = create_test_metadata()
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="hf3fs",
+        )
+
+        # Verify backend configuration
+        assert backend.dst_device == "cpu"
+        assert backend.local_cpu_backend == local_cpu_backend
+        assert backend.plugin_name == "hf3fs"
+        assert os.path.exists(mock_base_path)
+        assert backend.config.remote_serde == "naive"
+
+        local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+    def test_contains_key_not_exists(self, remote_backend_with_hf3fs):
+        """Test contains() when key doesn't exist in 3FS storage.
+
+        This test verifies that the contains() method correctly
+        returns False when the key does not exist.
+        """
+        key = create_test_key(1)
+        assert not remote_backend_with_hf3fs.contains(key)
+        assert not remote_backend_with_hf3fs.contains(key, pin=True)
+
+        remote_backend_with_hf3fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_hf3fs.close()
+
+    def test_get_blocking_key_not_exists(self, remote_backend_with_hf3fs):
+        """Test get_blocking() when key doesn't exist in 3FS storage.
+
+        This test verifies that the get_blocking() method correctly
+        returns None when the key does not exist.
+        """
+        key = create_test_key(2)
+        result = remote_backend_with_hf3fs.get_blocking(key)
+
+        assert result is None
+
+        remote_backend_with_hf3fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_hf3fs.close()
+
+    def test_put_and_get_roundtrip(self, remote_backend_with_hf3fs):
+        """Test put and get roundtrip for HF3fsConnector.
+
+        This test verifies the basic write-read cycle:
+        1. Put a memory object to 3FS storage
+        2. Verify the key exists
+        3. Get the memory object back
+        4. Verify the retrieved data matches the original
+        """
+        key = create_test_key(3)
+        memory_obj = create_test_memory_obj(shape=DEFAULT_SHAPE, dtype=DEFAULT_DTYPE)
+
+        # Put data to 3FS storage
+        future = remote_backend_with_hf3fs.submit_put_task(key, memory_obj)
+        # Wait for the async put to complete
+        if future:
+            future.result(timeout=10.0)
+
+        # Check that key exists
+        assert remote_backend_with_hf3fs.contains(key)
+
+        # Get data back
+        result = remote_backend_with_hf3fs.get_blocking(key)
+
+        assert result is not None
+        assert isinstance(result, MemoryObj)
+        assert result.metadata.shape == memory_obj.metadata.shape
+        assert result.metadata.dtype == memory_obj.metadata.dtype
+
+        remote_backend_with_hf3fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_hf3fs.close()
+
+    def test_batched_put_and_get(self, remote_backend_with_hf3fs):
+        """Test batched put and get operations.
+
+        This test verifies that multiple keys can be stored
+        and retrieved in batch.
+        """
+        keys = [create_test_key(i) for i in range(3)]
+        memory_objs = [
+            create_test_memory_obj(shape=DEFAULT_SHAPE, dtype=DEFAULT_DTYPE)
+            for _ in range(3)
+        ]
+
+        # Batched put
+        futures = [
+            remote_backend_with_hf3fs.submit_put_task(key, memory_obj)
+            for key, memory_obj in zip(keys, memory_objs, strict=False)
+        ]
+        for future in filter(None, futures):
+            future.result(timeout=10.0)
+
+        # Check all keys exist
+        for key in keys:
+            assert remote_backend_with_hf3fs.contains(key)
+
+        # Batched get
+        results = remote_backend_with_hf3fs.batched_get_blocking(keys)
+
+        assert results is not None
+        assert len(results) == 3
+        for result, original in zip(results, memory_objs, strict=False):
+            assert result is not None
+            assert result.metadata.shape == original.metadata.shape
+            assert result.metadata.dtype == original.metadata.dtype
+
+        remote_backend_with_hf3fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_hf3fs.close()
+
+    def test_multiple_paths_config(
+        self, mock_base_path, mock_3fs_mount_point, async_loop, local_cpu_backend
+    ):
+        """Test HF3fsConnector with multiple base paths.
+
+        This test verifies that the connector can handle
+        multiple base paths (comma-separated).
+        """
+        # Create additional temp directories
+        temp_dir2 = tempfile.mkdtemp(prefix="hf3fs_test2_", dir=mock_3fs_mount_point)
+        temp_dir3 = tempfile.mkdtemp(prefix="hf3fs_test3_", dir=mock_3fs_mount_point)
+
+        try:
+            # Create config with multiple paths
+            multi_path = f"{mock_base_path},{temp_dir2},{temp_dir3}"
+            config = create_test_config(
+                base_path=multi_path,
+                mount_point=mock_3fs_mount_point,
+            )
+            metadata = create_test_metadata()
+
+            backend = RemoteBackend(
+                config=config,
+                metadata=metadata,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cpu",
+            )
+
+            key = create_test_key(10)
+            memory_obj = create_test_memory_obj(
+                shape=DEFAULT_SHAPE, dtype=DEFAULT_DTYPE
+            )
+
+            # Put and get should work with multiple paths
+            future = backend.submit_put_task(key, memory_obj)
+            if future:
+                future.result(timeout=10.0)
+
+            assert backend.contains(key)
+
+            result = backend.get_blocking(key)
+            assert result is not None
+            assert result.metadata.shape == memory_obj.metadata.shape
+
+            backend.local_cpu_backend.memory_allocator.close()
+            backend.close()
+
+        finally:
+            # Cleanup additional directories
+            if os.path.exists(temp_dir2):
+                shutil.rmtree(temp_dir2, ignore_errors=True)
+            if os.path.exists(temp_dir3):
+                shutil.rmtree(temp_dir3, ignore_errors=True)
+
+    def test_file_persistence(
+        self, mock_base_path, mock_3fs_mount_point, async_loop, local_cpu_backend
+    ):
+        """Test that files persist after backend closure.
+
+        This test verifies that data written to 3FS storage
+        persists after the backend is closed and can be
+        retrieved with a new backend instance.
+        """
+        config = create_test_config(
+            base_path=mock_base_path,
+            mount_point=mock_3fs_mount_point,
+        )
+        metadata = create_test_metadata()
+
+        key = create_test_key(5)
+        memory_obj = create_test_memory_obj(shape=DEFAULT_SHAPE, dtype=DEFAULT_DTYPE)
+
+        # Create backend, put data, and close
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        future = backend.submit_put_task(key, memory_obj)
+        if future:
+            future.result(timeout=10.0)
+
+        backend.local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+        # Create new backend instance and verify data persists
+        new_memory_allocator = local_cpu_backend.memory_allocator.__class__(
+            device="cpu"
+        )
+        new_local_cpu_backend = LocalCPUBackend(
+            LMCacheEngineConfig.from_legacy(chunk_size=DEFAULT_CHUNK_SIZE),
+            metadata,
+            memory_allocator=new_memory_allocator,
+        )
+        new_backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=new_local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        assert new_backend.contains(key)
+
+        result = new_backend.get_blocking(key)
+        assert result is not None
+        assert result.metadata.shape == memory_obj.metadata.shape
+
+        new_backend.local_cpu_backend.memory_allocator.close()
+        new_backend.close()
+
+    def test_remove_key(self, remote_backend_with_hf3fs):
+        """Test removing a key from 3FS storage.
+
+        This test verifies that keys can be properly removed
+        from the storage backend.
+        """
+        key = create_test_key(6)
+        memory_obj = create_test_memory_obj(shape=DEFAULT_SHAPE, dtype=DEFAULT_DTYPE)
+
+        # Put data
+        future = remote_backend_with_hf3fs.submit_put_task(key, memory_obj)
+        if future:
+            future.result(timeout=10.0)
+
+        # Verify key exists
+        assert remote_backend_with_hf3fs.contains(key)
+
+        # Remove key
+        result = remote_backend_with_hf3fs.remove(key)
+        assert result is True
+
+        # Verify key no longer exists
+        assert not remote_backend_with_hf3fs.contains(key)
+
+        remote_backend_with_hf3fs.local_cpu_backend.memory_allocator.close()
+        remote_backend_with_hf3fs.close()
+
+
+class TestHF3fsConnectorConfiguration:
+    """Test cases for HF3fsConnector configuration validation."""
+
+    def test_invalid_mount_point(self, mock_base_path, async_loop, local_cpu_backend):
+        """Test that invalid mount point raises an error.
+
+        This test verifies that the connector properly validates
+        the 3FS mount point during initialization.
+        """
+        # Use a non-existent path as mount point
+        invalid_mount_point = "/nonexistent/path/3fs"
+
+        config = create_test_config(
+            base_path=mock_base_path,
+            mount_point=invalid_mount_point,
+        )
+        metadata = create_test_metadata()
+
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+            plugin_name="hf3fs",
+        )
+
+        # will not create connection
+        assert backend is not None
+        assert backend.connection is None
+        local_cpu_backend.memory_allocator.close()
+        backend.close()
+
+    def test_configuration_parameters(
+        self, mock_base_path, mock_3fs_mount_point, async_loop, local_cpu_backend
+    ):
+        """Test various configuration parameters.
+
+        This test verifies that different configuration parameters
+        are properly passed to the HF3fsConnector.
+        """
+        # Test with custom parameters
+        config = create_test_config(
+            base_path=mock_base_path,
+            mount_point=mock_3fs_mount_point,
+            iov_size=104857600,  # 100MB
+            ior_entries=128,
+            io_depth=32,
+            numa_id=0,
+            io_thread_num=8,
+        )
+        metadata = create_test_metadata()
+        backend = RemoteBackend(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cpu",
+        )
+
+        assert backend is not None
+
+        backend.local_cpu_backend.memory_allocator.close()
+        backend.close()
diff --git a/tests/v1/storage_backend/test_hfbucket_connector.py b/tests/v1/storage_backend/test_hfbucket_connector.py
new file mode 100644
index 0000000..40da69d
--- /dev/null
+++ b/tests/v1/storage_backend/test_hfbucket_connector.py
@@ -0,0 +1,518 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+import asyncio
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector import ConnectorContext
+from lmcache.v1.storage_backend.connector.hfbucket_adapter import (
+    HFBucketConnectorAdapter,
+)
+from lmcache.v1.storage_backend.connector.hfbucket_connector import (
+    HFBucketConnector,
+    HFBucketConnectorConfig,
+    encode_hfbucket_object_name,
+    parse_hfbucket_handle,
+    resolve_hfbucket_connector_config,
+)
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+
+
+@dataclass(frozen=True)
+class FakeBucketEntry:
+    """Small stand-in for Hugging Face bucket metadata objects."""
+
+    path: str
+    size: int
+    type: str
+
+
+class FakeBucketClient:
+    """In-memory bucket client used to unit test the connector."""
+
+    def __init__(self) -> None:
+        self.storage: dict[str, bytes] = {}
+        self.created_buckets: list[str] = []
+        self.deleted_paths: list[str] = []
+        self.info_paths_calls: list[tuple[str, ...]] = []
+        self.download_calls: list[tuple[str, ...]] = []
+        self.fail_upload_after: int | None = None
+        self.raise_on_download: Exception | None = None
+
+    def create_bucket(self, bucket_id: str) -> None:
+        """Record bucket creation requests."""
+        self.created_buckets.append(bucket_id)
+
+    def bucket_info(self, bucket_id: str) -> object:
+        """Return a trivial bucket info payload."""
+        return {"id": bucket_id}
+
+    def get_paths_info(self, bucket_id: str, paths: Sequence[str]) -> list[object]:
+        """Return exact metadata for the requested paths."""
+        del bucket_id
+        self.info_paths_calls.append(tuple(paths))
+        entries: list[object] = [
+            FakeBucketEntry(
+                path=path,
+                size=len(self.storage[path]) if path in self.storage else 0,
+                type="file" if path in self.storage else "missing",
+            )
+            for path in paths
+        ]
+        return entries
+
+    def list_tree(self, bucket_id: str, prefix: str) -> list[object]:
+        """List stored objects under the requested prefix."""
+        del bucket_id
+        prefix_with_separator = f"{prefix}/" if prefix else ""
+        entries: list[object] = []
+        for path, payload in sorted(self.storage.items()):
+            if prefix and path != prefix and not path.startswith(prefix_with_separator):
+                continue
+            entries.append(FakeBucketEntry(path=path, size=len(payload), type="file"))
+        return entries
+
+    def upload_files(
+        self,
+        bucket_id: str,
+        add: Sequence[tuple[bytes, str]],
+    ) -> None:
+        """Store uploaded bytes under their remote object paths."""
+        del bucket_id
+        for index, (payload, path) in enumerate(add):
+            self.storage[path] = payload
+            if self.fail_upload_after is not None and index >= self.fail_upload_after:
+                raise RuntimeError("simulated partial upload failure")
+
+    def download_files(
+        self,
+        bucket_id: str,
+        files: Sequence[tuple[str, str]],
+    ) -> None:
+        """Write stored objects to the requested local paths."""
+        del bucket_id
+        self.download_calls.append(tuple(path for path, _ in files))
+        for remote_path, local_path in files:
+            payload = self.storage.get(remote_path)
+            if payload is None:
+                continue
+            Path(local_path).write_bytes(payload)
+        if self.raise_on_download is not None:
+            raise self.raise_on_download
+
+    def delete_files(
+        self,
+        bucket_id: str,
+        delete: Sequence[str],
+    ) -> None:
+        """Remove stored objects."""
+        del bucket_id
+        for path in delete:
+            self.deleted_paths.append(path)
+            self.storage.pop(path, None)
+
+
+def create_test_metadata() -> LMCacheMetadata:
+    """Create LMCache metadata with a deterministic full chunk layout."""
+    return LMCacheMetadata(
+        model_name="test-model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+
+def create_test_config(
+    extra_config: dict[str, object] | None = None,
+    *,
+    plugin_name: str = "hfbucket",
+    save_unfull_chunk: bool = False,
+) -> LMCacheEngineConfig:
+    """Create a plugin-based config for the HFBucket connector."""
+    return LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=0.1,
+        save_unfull_chunk=save_unfull_chunk,
+        lmcache_instance_id="test-hfbucket",
+        remote_storage_plugins=[plugin_name],
+        extra_config=extra_config or {},
+    )
+
+
+def create_test_key(key_id: int) -> CacheEngineKey:
+    """Create a deterministic cache key for unit tests."""
+    return CacheEngineKey(
+        model_name="test/model",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=key_id,
+        dtype=torch.bfloat16,
+    )
+
+
+def create_connector(
+    tmp_path: Path,
+    memory_allocator,
+    *,
+    plugin_name: str = "hfbucket",
+    extra_config: dict[str, object] | None = None,
+    save_unfull_chunk: bool = False,
+    bucket_client: FakeBucketClient | None = None,
+) -> tuple[HFBucketConnector, FakeBucketClient, LMCacheMetadata]:
+    """Create a connector with an in-memory fake bucket client."""
+    metadata = create_test_metadata()
+    config_dict = {
+        f"remote_storage_plugin.{plugin_name}.bucket_handle": (
+            "hf://buckets/test-org/test-bucket/prod"
+        ),
+        f"remote_storage_plugin.{plugin_name}.download_tmp_dir": str(tmp_path),
+        f"remote_storage_plugin.{plugin_name}.metadata_cache_ttl_secs": 30,
+    }
+    if extra_config is not None:
+        config_dict.update(extra_config)
+
+    config = create_test_config(
+        config_dict,
+        plugin_name=plugin_name,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+    local_cpu_backend = LocalCPUBackend(
+        config,
+        metadata,
+        memory_allocator=memory_allocator,
+    )
+    client = bucket_client or FakeBucketClient()
+    connector = HFBucketConnector(
+        local_cpu_backend=local_cpu_backend,
+        config=config,
+        metadata=metadata,
+        connector_config=resolve_hfbucket_connector_config(config, plugin_name),
+        bucket_client=client,
+    )
+    return connector, client, metadata
+
+
+def create_full_chunk_memory_obj(
+    local_cpu_backend: LocalCPUBackend,
+    metadata: LMCacheMetadata,
+    fill_byte: int,
+) -> tuple[MemoryObj, bytes]:
+    """Allocate and initialize a full chunk memory object for upload tests."""
+    memory_obj = local_cpu_backend.allocate(
+        metadata.get_shapes(),
+        metadata.get_dtypes(),
+        MemoryFormat.KV_2LTD,
+    )
+    assert memory_obj is not None
+    byte_buffer = memoryview(memory_obj.byte_array).cast("B")
+    payload = bytes([fill_byte]) * len(byte_buffer)
+    byte_buffer[:] = payload
+    return memory_obj, payload
+
+
+def memory_obj_to_bytes(memory_obj: MemoryObj) -> bytes:
+    """Convert a test memory object to raw bytes."""
+    return memoryview(memory_obj.byte_array).cast("B").tobytes()
+
+
+@pytest.mark.parametrize(
+    ("bucket_handle", "bucket_id", "object_prefix"),
+    [
+        ("hf://buckets/my-org/my-bucket", "my-org/my-bucket", ""),
+        (
+            "hf://buckets/my-org/my-bucket/prod/checkpoints",
+            "my-org/my-bucket",
+            "prod/checkpoints",
+        ),
+    ],
+)
+def test_parse_hfbucket_handle(
+    bucket_handle: str,
+    bucket_id: str,
+    object_prefix: str,
+) -> None:
+    """Bucket handles should split into bucket id and object prefix."""
+    location = parse_hfbucket_handle(bucket_handle)
+    assert location.bucket_id == bucket_id
+    assert location.object_prefix == object_prefix
+
+
+def test_adapter_can_parse_plugin_urls() -> None:
+    """The adapter should match plugin URLs with and without instances."""
+    adapter = HFBucketConnectorAdapter()
+    assert adapter.can_parse("plugin://hfbucket")
+    assert adapter.can_parse("plugin://hfbucket.us")
+    assert not adapter.can_parse("plugin://fs")
+
+
+def test_resolve_hfbucket_connector_config_uses_full_plugin_name() -> None:
+    """Instance-specific plugin config should be resolved from the full name."""
+    config = create_test_config(
+        {
+            "remote_storage_plugin.hfbucket.us.bucket_handle": (
+                "hf://buckets/test-org/us-bucket/prod"
+            ),
+            "remote_storage_plugin.hfbucket.us.token_env": "HF_US_TOKEN",
+            "remote_storage_plugin.hfbucket.us.create_bucket_if_missing": True,
+            "remote_storage_plugin.hfbucket.us.download_tmp_dir": "/tmp/hf-us",
+            "remote_storage_plugin.hfbucket.us.metadata_cache_ttl_secs": 12,
+        },
+        plugin_name="hfbucket.us",
+    )
+
+    connector_config = resolve_hfbucket_connector_config(config, "hfbucket.us")
+
+    assert connector_config.plugin_name == "hfbucket.us"
+    assert connector_config.bucket_location.bucket_id == "test-org/us-bucket"
+    assert connector_config.bucket_location.object_prefix == "prod"
+    assert connector_config.token_env == "HF_US_TOKEN"
+    assert connector_config.create_bucket_if_missing is True
+    assert connector_config.download_tmp_dir == Path("/tmp/hf-us")
+    assert connector_config.metadata_cache_ttl_secs == 12.0
+
+
+def test_adapter_create_connector_uses_plugin_scoped_config(monkeypatch) -> None:
+    """Adapter connector creation should pass through the resolved plugin config."""
+
+    created: dict[str, object] = {}
+
+    class DummyConnector:
+        """Capture adapter constructor arguments without invoking the real client."""
+
+        def __init__(
+            self,
+            local_cpu_backend: object,
+            config: LMCacheEngineConfig,
+            metadata: LMCacheMetadata,
+            connector_config: HFBucketConnectorConfig,
+        ) -> None:
+            created["local_cpu_backend"] = local_cpu_backend
+            created["config"] = config
+            created["metadata"] = metadata
+            created["connector_config"] = connector_config
+
+    config = create_test_config(
+        {
+            "remote_storage_plugin.hfbucket.prod.bucket_handle": (
+                "hf://buckets/test-org/test-bucket/prod"
+            ),
+        },
+        plugin_name="hfbucket.prod",
+    )
+    metadata = create_test_metadata()
+    loop = asyncio.new_event_loop()
+    adapter = HFBucketConnectorAdapter()
+
+    monkeypatch.setattr(
+        "lmcache.v1.storage_backend.connector.hfbucket_adapter.HFBucketConnector",
+        DummyConnector,
+    )
+
+    connector = adapter.create_connector(
+        ConnectorContext(
+            url="plugin://hfbucket.prod",
+            loop=loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=metadata,
+            plugin_name="hfbucket.prod",
+        )
+    )
+
+    assert isinstance(connector, DummyConnector)
+    connector_config = created["connector_config"]
+    assert isinstance(connector_config, HFBucketConnectorConfig)
+    assert connector_config.plugin_name == "hfbucket.prod"
+    assert connector_config.bucket_location.object_prefix == "prod"
+
+
+def test_put_get_exists_list_and_remove_roundtrip(
+    tmp_path: Path,
+    memory_allocator,
+) -> None:
+    """Single-object operations should round-trip against the fake client."""
+    connector, fake_client, metadata = create_connector(tmp_path, memory_allocator)
+    key = create_test_key(1)
+    memory_obj, payload = create_full_chunk_memory_obj(
+        connector.local_cpu_backend,
+        metadata,
+        fill_byte=17,
+    )
+
+    try:
+        asyncio.run(connector.put(key, memory_obj))
+        assert fake_client.created_buckets == []
+
+        assert connector.exists_sync(key) is True
+        assert asyncio.run(connector.exists(key)) is True
+
+        results = asyncio.run(connector.list())
+        assert results == [key.to_string()]
+
+        loaded = asyncio.run(connector.get(key))
+        assert loaded is not None
+        try:
+            assert memory_obj_to_bytes(loaded) == payload
+        finally:
+            loaded.ref_count_down()
+
+        assert connector.remove_sync(key) is True
+        assert connector.exists_sync(key) is False
+    finally:
+        memory_obj.ref_count_down()
+        asyncio.run(connector.close())
+        connector.local_cpu_backend.memory_allocator.close()
+
+
+def test_batched_put_and_batched_get_preserve_order(
+    tmp_path: Path,
+    memory_allocator,
+) -> None:
+    """Batched operations should upload once and preserve result order."""
+    connector, fake_client, metadata = create_connector(
+        tmp_path,
+        memory_allocator,
+        extra_config={
+            "remote_storage_plugin.hfbucket.create_bucket_if_missing": True,
+        },
+    )
+    keys = [create_test_key(10), create_test_key(11)]
+    memory_objs_and_payloads = [
+        create_full_chunk_memory_obj(
+            connector.local_cpu_backend, metadata, fill_byte=33
+        ),
+        create_full_chunk_memory_obj(
+            connector.local_cpu_backend, metadata, fill_byte=44
+        ),
+    ]
+    memory_objs = [item[0] for item in memory_objs_and_payloads]
+    payloads = [item[1] for item in memory_objs_and_payloads]
+
+    try:
+        asyncio.run(connector.batched_put(keys, memory_objs))
+        assert fake_client.created_buckets == ["test-org/test-bucket"]
+
+        missing_key = create_test_key(12)
+        results = asyncio.run(connector.batched_get([keys[0], missing_key, keys[1]]))
+        assert results[0] is not None
+        assert results[1] is None
+        assert results[2] is not None
+        try:
+            assert memory_obj_to_bytes(results[0]) == payloads[0]
+            assert memory_obj_to_bytes(results[2]) == payloads[1]
+        finally:
+            for result in results:
+                if result is not None:
+                    result.ref_count_down()
+    finally:
+        for memory_obj in memory_objs:
+            memory_obj.ref_count_down()
+        asyncio.run(connector.close())
+        connector.local_cpu_backend.memory_allocator.close()
+
+
+def test_batched_contains_returns_prefix_hits(tmp_path: Path, memory_allocator) -> None:
+    """Prefix hit counting should stop at the first missing or invalid object."""
+    connector, fake_client, metadata = create_connector(tmp_path, memory_allocator)
+    keys = [create_test_key(20), create_test_key(21), create_test_key(22)]
+    try:
+        for key, fill_byte in zip(keys[:2], [51, 52], strict=True):
+            memory_obj, _ = create_full_chunk_memory_obj(
+                connector.local_cpu_backend,
+                metadata,
+                fill_byte=fill_byte,
+            )
+            try:
+                asyncio.run(connector.put(key, memory_obj))
+            finally:
+                memory_obj.ref_count_down()
+
+        assert connector.batched_contains(keys) == 2
+        assert asyncio.run(connector.batched_async_contains("lookup", keys)) == 2
+    finally:
+        asyncio.run(connector.close())
+        connector.local_cpu_backend.memory_allocator.close()
+
+
+def test_rejects_save_unfull_chunk_and_save_chunk_meta(
+    tmp_path: Path,
+    memory_allocator,
+) -> None:
+    """Constructor validation should reject unsupported chunk persistence modes."""
+    with pytest.raises(ValueError, match="save_unfull_chunk must be False"):
+        create_connector(
+            tmp_path,
+            memory_allocator,
+            save_unfull_chunk=True,
+        )
+
+    with pytest.raises(ValueError, match="save_chunk_meta must be False"):
+        create_connector(
+            tmp_path,
+            memory_allocator,
+            extra_config={"save_chunk_meta": True},
+        )
+
+
+def test_put_rejects_partial_chunk_upload(tmp_path: Path, memory_allocator) -> None:
+    """Uploads should reject buffers that are smaller than a full chunk."""
+    connector, _, metadata = create_connector(tmp_path, memory_allocator)
+    key = create_test_key(30)
+    try:
+        partial_obj = connector.local_cpu_backend.allocate(
+            metadata.get_shapes(num_tokens=128),
+            metadata.get_dtypes(),
+            MemoryFormat.KV_2LTD,
+        )
+        assert partial_obj is not None
+        with pytest.raises(ValueError, match="Partial/unfull chunks are not supported"):
+            asyncio.run(connector.put(key, partial_obj))
+    finally:
+        partial_obj.ref_count_down()
+        asyncio.run(connector.close())
+        connector.local_cpu_backend.memory_allocator.close()
+
+
+def test_get_rejects_download_size_mismatch(tmp_path: Path, memory_allocator) -> None:
+    """Downloads should return None when bucket objects are not full chunks."""
+    connector, fake_client, _ = create_connector(tmp_path, memory_allocator)
+    key = create_test_key(40)
+    fake_client.storage[f"prod/{encode_hfbucket_object_name(key.to_string())}"] = (
+        b"x" * 13
+    )
+
+    try:
+        assert connector.exists_sync(key) is False
+        loaded = asyncio.run(connector.get(key))
+        assert loaded is None
+    finally:
+        asyncio.run(connector.close())
+        connector.local_cpu_backend.memory_allocator.close()
+
+
+def test_close_cleans_temp_dir(tmp_path: Path, memory_allocator) -> None:
+    """Connector close should clean up its per-connector temp directory."""
+    connector, _, _ = create_connector(tmp_path, memory_allocator)
+    download_root_entries = list(tmp_path.iterdir())
+    assert download_root_entries, (
+        "Expected connector to create a temp session directory"
+    )
+
+    asyncio.run(connector.close())
+
+    assert list(tmp_path.iterdir()) == []
+    connector.local_cpu_backend.memory_allocator.close()
diff --git a/tests/v1/storage_backend/test_local_cpu_backend.py b/tests/v1/storage_backend/test_local_cpu_backend.py
new file mode 100644
index 0000000..0cab447
--- /dev/null
+++ b/tests/v1/storage_backend/test_local_cpu_backend.py
@@ -0,0 +1,732 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.observability import LMCStatsMonitor
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.cache_controller.message import BatchedKVOperationMsg, OpType
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.pin_monitor import PinMonitor
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from tests.v1.utils import create_test_memory_obj
+import lmcache.v1.storage_backend.local_cpu_backend as local_cpu_backend_module
+
+
+class MockLookupServer:
+    def __init__(self):
+        self.removed_keys = []
+        self.inserted_keys = []
+
+    def batched_remove(self, keys):
+        self.removed_keys.extend(keys)
+
+    def batched_insert(self, keys):
+        self.inserted_keys.extend(keys)
+
+
+class MockLMCacheWorker:
+    def __init__(self):
+        self.messages = []
+        self._lock = threading.Lock()
+
+    def put_msg(self, msg):
+        with self._lock:
+            self.messages.append(msg)
+
+
+def create_test_config(
+    local_cpu: bool = True, use_layerwise: bool = False, enable_blending: bool = False
+):
+    """Create a test configuration for LocalCPUBackend."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=local_cpu,
+        use_layerwise=use_layerwise,
+        enable_blending=enable_blending,
+        lmcache_instance_id="test_instance",
+    )
+    return config
+
+
+def create_test_key(key_id: str = "test_key") -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=0,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+def create_test_metadata() -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+
+@pytest.fixture
+def local_cpu_backend(memory_allocator):
+    """Create a LocalCPUBackend for testing."""
+    config = create_test_config()
+
+    # Initialize PinMonitor before creating backend
+    PinMonitor.GetOrCreate(config)
+
+    backend = LocalCPUBackend(config=config, memory_allocator=memory_allocator)
+
+    yield backend
+
+    # Cleanup: destroy PinMonitor after test
+    PinMonitor.DestroyInstance()
+
+
+@pytest.fixture
+def local_cpu_backend_disabled(memory_allocator):
+    """Create a LocalCPUBackend with local_cpu disabled."""
+    config = create_test_config(local_cpu=False)
+
+    # Initialize PinMonitor before creating backend
+    PinMonitor.GetOrCreate(config)
+
+    backend = LocalCPUBackend(config=config, memory_allocator=memory_allocator)
+
+    yield backend
+
+    # Cleanup: destroy PinMonitor after test
+    PinMonitor.DestroyInstance()
+
+
+class TestLocalCPUBackend:
+    """Test cases for LocalCPUBackend."""
+
+    def teardown_method(self, method):
+        LMCStatsMonitor.unregister_all_metrics()
+        LMCStatsMonitor.DestroyInstance()
+
+    def test_init(self, memory_allocator):
+        """Test LocalCPUBackend initialization."""
+        config = create_test_config()
+        backend = LocalCPUBackend(config=config, memory_allocator=memory_allocator)
+
+        assert backend.use_hot is True
+        assert backend.memory_allocator == memory_allocator
+        assert backend.lmcache_worker is None
+        assert backend.instance_id == "test_instance"
+        assert len(backend.hot_cache) == 0
+        assert backend.layerwise is False
+        assert backend.enable_blending is False
+
+        memory_allocator.close()
+
+    def test_init_with_lookup_server_and_worker(self, memory_allocator):
+        """Test LocalCPUBackend initialization with lookup server and worker."""
+        config = create_test_config()
+        lmcache_worker = MockLMCacheWorker()
+
+        backend = LocalCPUBackend(
+            config=config,
+            memory_allocator=memory_allocator,
+            lmcache_worker=lmcache_worker,
+        )
+
+        assert backend.lmcache_worker == lmcache_worker
+
+        memory_allocator.close()
+
+    def test_init_with_layerwise_config(self, memory_allocator):
+        """Test LocalCPUBackend initialization with layerwise configuration."""
+        config = create_test_config(use_layerwise=True, enable_blending=True)
+        backend = LocalCPUBackend(config=config, memory_allocator=memory_allocator)
+
+        assert backend.layerwise is True
+        assert backend.enable_blending is True
+
+        memory_allocator.close()
+
+    def test_str(self, local_cpu_backend):
+        """Test string representation."""
+        assert str(local_cpu_backend) == "LocalCPUBackend"
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_contains_key_not_exists(self, local_cpu_backend):
+        """Test contains() when key doesn't exist."""
+        key = create_test_key("nonexistent")
+        assert not local_cpu_backend.contains(key)
+        assert not local_cpu_backend.contains(key, pin=True)
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_contains_key_exists(self, local_cpu_backend):
+        """Test contains() when key exists."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key first
+        local_cpu_backend.submit_put_task(key, memory_obj)
+
+        assert local_cpu_backend.contains(key)
+        assert local_cpu_backend.contains(key, pin=True)
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_exists_in_put_tasks(self, local_cpu_backend):
+        """Test exists_in_put_tasks()."""
+        key = create_test_key("test_key")
+        # LocalCPUBackend always returns False for exists_in_put_tasks
+        assert not local_cpu_backend.exists_in_put_tasks(key)
+        local_cpu_backend.memory_allocator.close()
+
+    def test_submit_put_task(self, local_cpu_backend):
+        """Test submit_put_task()."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        future = local_cpu_backend.submit_put_task(key, memory_obj)
+
+        # LocalCPUBackend returns None for submit_put_task
+        assert future is None
+        assert key in local_cpu_backend.hot_cache
+        assert local_cpu_backend.hot_cache[key] == memory_obj
+        assert (
+            memory_obj.get_ref_count() == 2
+        )  # 1 from creation + 1 from submit_put_task
+        local_cpu_backend.memory_allocator.close()
+
+    def test_submit_put_task_reinsert(self, local_cpu_backend):
+        """Test submit_put_task() with reinsertion."""
+        key = create_test_key("test_key")
+        memory_obj1 = create_test_memory_obj(shape=torch.Size([2, 16, 8, 128]))
+        memory_obj2 = create_test_memory_obj(shape=torch.Size([2, 32, 8, 128]))
+
+        # First insertion
+        local_cpu_backend.submit_put_task(key, memory_obj1)
+        assert local_cpu_backend.hot_cache[key] == memory_obj1
+
+        # Reinsertion
+        local_cpu_backend.submit_put_task(key, memory_obj2)
+        assert local_cpu_backend.hot_cache[key] != memory_obj2
+        assert memory_obj1.get_ref_count() == 2
+        assert memory_obj2.get_ref_count() == 1
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_batched_submit_put_task(self, local_cpu_backend):
+        """Test batched_submit_put_task()."""
+        keys = [create_test_key(f"key_{i}") for i in range(3)]
+        memory_objs = [create_test_memory_obj() for _ in range(3)]
+
+        futures = local_cpu_backend.batched_submit_put_task(keys, memory_objs)
+
+        # LocalCPUBackend returns None for batched_submit_put_task
+        assert futures is None
+
+        # Check that all keys were inserted
+        for key, memory_obj in zip(keys, memory_objs, strict=False):
+            assert key in local_cpu_backend.hot_cache
+            assert local_cpu_backend.hot_cache[key] == memory_obj
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_batched_submit_put_task_disabled(self, local_cpu_backend_disabled):
+        """Test batched_submit_put_task() when local_cpu is disabled."""
+        keys = [create_test_key(f"key_{i}") for i in range(3)]
+        memory_objs = [create_test_memory_obj() for _ in range(3)]
+
+        futures = local_cpu_backend_disabled.batched_submit_put_task(keys, memory_objs)
+
+        # Should return None when local_cpu is disabled
+        assert futures is None
+
+        local_cpu_backend_disabled.memory_allocator.close()
+
+    def test_get_blocking_key_not_exists(self, local_cpu_backend):
+        """Test get_blocking() when key doesn't exist."""
+        key = create_test_key("nonexistent")
+        result = local_cpu_backend.get_blocking(key)
+
+        assert result is None
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_get_blocking_key_exists(self, local_cpu_backend):
+        """Test get_blocking() when key exists."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key first
+        local_cpu_backend.submit_put_task(key, memory_obj)
+
+        result = local_cpu_backend.get_blocking(key)
+
+        assert result is not None
+        assert isinstance(result, MemoryObj)
+        assert result == memory_obj
+        assert (
+            result.get_ref_count() == 3
+        )  # 1 from creation + 1 from submit_put_task + 1 from get_blocking
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_pin_unpin(self, local_cpu_backend):
+        """Test pin() and unpin() operations."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key first
+        local_cpu_backend.submit_put_task(key, memory_obj)
+
+        # Test pin
+        assert local_cpu_backend.pin(key)
+        assert memory_obj.is_pinned
+
+        # Test unpin
+        assert local_cpu_backend.unpin(key)
+        assert not memory_obj.is_pinned
+
+        # Test pin/unpin non-existent key
+        non_existent_key = create_test_key("non_existent")
+        assert not local_cpu_backend.pin(non_existent_key)
+        assert not local_cpu_backend.unpin(non_existent_key)
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_remove(self, local_cpu_backend):
+        """Test remove()."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key first
+        local_cpu_backend.submit_put_task(key, memory_obj)
+        assert key in local_cpu_backend.hot_cache
+
+        # Remove the key
+        result = local_cpu_backend.remove(key)
+
+        assert result is True
+        assert key not in local_cpu_backend.hot_cache
+        assert memory_obj.get_ref_count() == 1  # Should be decremented
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_remove_non_existent(self, local_cpu_backend):
+        """Test remove() with non-existent key."""
+        key = create_test_key("nonexistent")
+        result = local_cpu_backend.remove(key)
+
+        assert result is False
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_remove_with_worker(self, memory_allocator, lmcache_engine_metadata):
+        """Test remove() with LMCacheWorker."""
+        config = create_test_config()
+        lmcache_worker = MockLMCacheWorker()
+
+        backend = LocalCPUBackend(
+            config=config,
+            metadata=lmcache_engine_metadata,
+            memory_allocator=memory_allocator,
+            lmcache_worker=lmcache_worker,
+        )
+
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key first
+        backend.submit_put_task(key, memory_obj)
+
+        # Remove the key
+        backend.remove(key)
+
+        # Manually flush to ensure messages are sent for testing
+        if backend.batched_msg_sender is not None:
+            backend.batched_msg_sender.flush()
+
+        # Check that we have batched messages
+        batched_msgs = [
+            msg
+            for msg in lmcache_worker.messages
+            if isinstance(msg, BatchedKVOperationMsg)
+        ]
+        assert len(batched_msgs) >= 1, "Should have at least one batched message"
+
+        # Collect all operations from all batches
+        all_admit_ops = []
+        all_evict_ops = []
+        for msg in batched_msgs:
+            for op in msg.operations:
+                if op.op_type == OpType.ADMIT:
+                    all_admit_ops.append(op)
+                elif op.op_type == OpType.EVICT:
+                    all_evict_ops.append(op)
+
+        # Verify we have exactly one ADMIT and one EVICT operation
+        assert len(all_admit_ops) == 1, "Should have exactly one ADMIT operation"
+        assert len(all_evict_ops) == 1, "Should have exactly one EVICT operation"
+
+        # Verify the operations are for the correct key
+        assert all_admit_ops[0].key == key.chunk_hash
+        assert all_evict_ops[0].key == key.chunk_hash
+
+        memory_allocator.close()
+
+    def test_allocate(self, local_cpu_backend):
+        """Test allocate()."""
+        shape = torch.Size([2, 16, 8, 128])
+        dtype = torch.bfloat16
+
+        memory_obj = local_cpu_backend.allocate(shape, dtype)
+
+        assert memory_obj is not None
+        assert isinstance(memory_obj, MemoryObj)
+        assert memory_obj.metadata.shape == shape
+        assert memory_obj.metadata.dtype == dtype
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_allocate_with_format(self, local_cpu_backend):
+        """Test allocate() with specific format."""
+        shape = torch.Size([2, 16, 8, 128])
+        dtype = torch.bfloat16
+        fmt = MemoryFormat.KV_2LTD
+
+        memory_obj = local_cpu_backend.allocate(shape, dtype, fmt)
+
+        assert memory_obj is not None
+        assert memory_obj.metadata.fmt == fmt
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_allocate_with_layerwise_config(self, memory_allocator):
+        """Test allocate() with layerwise configuration."""
+        config = create_test_config(use_layerwise=True, enable_blending=True)
+        backend = LocalCPUBackend(config=config, memory_allocator=memory_allocator)
+
+        shape = torch.Size([2, 16, 8, 128])
+        dtype = torch.bfloat16
+
+        memory_obj = backend.allocate(shape, dtype)
+
+        assert memory_obj is not None
+        # Should use KV_2TD format when layerwise=True and enable_blending=True
+        assert memory_obj.metadata.fmt == MemoryFormat.KV_2TD
+
+        memory_allocator.close()
+
+    def test_batched_allocate(self, local_cpu_backend):
+        """Test batched_allocate()."""
+        shape = torch.Size([2, 16, 8, 128])
+        dtype = torch.bfloat16
+        batch_size = 3
+
+        memory_objs = local_cpu_backend.batched_allocate(shape, dtype, batch_size)
+
+        assert memory_objs is not None
+        assert len(memory_objs) == batch_size
+        for memory_obj in memory_objs:
+            assert isinstance(memory_obj, MemoryObj)
+            assert memory_obj.metadata.shape == shape
+            assert memory_obj.metadata.dtype == dtype
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_get_keys(self, local_cpu_backend):
+        """Test get_keys()."""
+        keys = [create_test_key(f"key_{i}") for i in range(3)]
+        memory_objs = [create_test_memory_obj() for _ in range(3)]
+
+        # Insert keys
+        for key, memory_obj in zip(keys, memory_objs, strict=False):
+            local_cpu_backend.submit_put_task(key, memory_obj)
+
+        # Get keys
+        retrieved_keys = local_cpu_backend.get_keys()
+
+        assert len(retrieved_keys) == 3
+        assert all(key in retrieved_keys for key in keys)
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_get_keys_empty(self, local_cpu_backend):
+        """Test get_keys() when cache is empty."""
+        keys = local_cpu_backend.get_keys()
+
+        assert len(keys) == 0
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_concurrent_access(self, local_cpu_backend):
+        """Test concurrent access to the backend."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key
+        local_cpu_backend.submit_put_task(key, memory_obj)
+
+        # Test concurrent contains() calls
+        def check_contains():
+            for _ in range(20):
+                assert local_cpu_backend.contains(key)
+
+        threads = [threading.Thread(target=check_contains) for _ in range(3)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join()
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_thread_safety(self, local_cpu_backend):
+        """Test thread safety of the backend."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        # Insert key
+        local_cpu_backend.submit_put_task(key, memory_obj)
+
+        # Test concurrent operations
+        def concurrent_operations():
+            for _ in range(10):
+                # Test contains
+                local_cpu_backend.contains(key)
+                # Test pin/unpin
+                local_cpu_backend.pin(key)
+                local_cpu_backend.unpin(key)
+                # Test get_blocking
+                result = local_cpu_backend.get_blocking(key)
+                assert result is not None
+
+        threads = [threading.Thread(target=concurrent_operations) for _ in range(3)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join()
+
+        # The backend should still be in a consistent state
+        assert local_cpu_backend.contains(key)
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_ref_count_management(self, local_cpu_backend):
+        """Test reference count management."""
+        key = create_test_key("test_key")
+        memory_obj = create_test_memory_obj()
+
+        initial_ref_count = memory_obj.get_ref_count()
+
+        # Insert key
+        local_cpu_backend.submit_put_task(key, memory_obj)
+        assert memory_obj.get_ref_count() == initial_ref_count + 1
+
+        # Get blocking
+        local_cpu_backend.get_blocking(key)
+        assert memory_obj.get_ref_count() == initial_ref_count + 2
+
+        # Remove key
+        local_cpu_backend.remove(key)
+        assert memory_obj.get_ref_count() == initial_ref_count + 1
+        local_cpu_backend.memory_allocator.close()
+
+
+@pytest.mark.no_shared_allocator
+class TestLocalCPUBackendAllocatorRecovery:
+    def teardown_method(self, method):
+        LMCStatsMonitor.unregister_all_metrics()
+        LMCStatsMonitor.DestroyInstance()
+        PinMonitor.DestroyInstance()
+
+    def test_batched_allocate_fails_while_group_pinned_then_recovers(self):
+        chunk_bytes = 1024 * 1024
+        batch_size = 2
+        shape = torch.Size([1, chunk_bytes])
+        config = create_test_config()
+        PinMonitor.GetOrCreate(config)
+        allocator = MixedMemoryAllocator(chunk_bytes * batch_size)
+        backend = LocalCPUBackend(config=config, memory_allocator=allocator)
+        layer_keys = create_test_key("batched_pinned").split_layers(batch_size)
+
+        memory_objs = backend.batched_allocate(
+            shape,
+            torch.uint8,
+            batch_size=batch_size,
+            fmt=MemoryFormat.KV_T2D,
+            busy_loop=False,
+        )
+        assert memory_objs is not None
+        backend.batched_submit_put_task(layer_keys, memory_objs)
+        for memory_obj in memory_objs:
+            memory_obj.ref_count_down()
+
+        assert backend.pin(layer_keys[0])
+        assert (
+            backend.batched_allocate(
+                shape,
+                torch.uint8,
+                batch_size=batch_size,
+                fmt=MemoryFormat.KV_T2D,
+                busy_loop=False,
+            )
+            is None
+        )
+        assert all(key in backend.hot_cache for key in layer_keys)
+
+        assert backend.unpin(layer_keys[0])
+        recovered = backend.batched_allocate(
+            shape,
+            torch.uint8,
+            batch_size=batch_size,
+            fmt=MemoryFormat.KV_T2D,
+            busy_loop=False,
+        )
+        assert recovered is not None
+        assert all(key not in backend.hot_cache for key in layer_keys)
+        assert allocator.memcheck()
+
+        for memory_obj in recovered:
+            memory_obj.ref_count_down()
+        allocator.close()
+
+    def test_batched_allocate_recovers_with_fully_evictable_group(self):
+        chunk_bytes = 4096
+        batch_size = 2
+        shape = torch.Size([1, chunk_bytes])
+        config = create_test_config()
+        PinMonitor.GetOrCreate(config)
+        allocator = MixedMemoryAllocator(chunk_bytes * batch_size * 2)
+        backend = LocalCPUBackend(config=config, memory_allocator=allocator)
+        pinned_group_keys = create_test_key("batched_pinned_group").split_layers(
+            batch_size
+        )
+        safe_group_keys = create_test_key("batched_safe_group").split_layers(batch_size)
+
+        pinned_group_objs = backend.batched_allocate(
+            shape,
+            torch.uint8,
+            batch_size=batch_size,
+            fmt=MemoryFormat.KV_T2D,
+            busy_loop=False,
+        )
+        safe_group_objs = backend.batched_allocate(
+            shape,
+            torch.uint8,
+            batch_size=batch_size,
+            fmt=MemoryFormat.KV_T2D,
+            busy_loop=False,
+        )
+        assert pinned_group_objs is not None
+        assert safe_group_objs is not None
+        backend.batched_submit_put_task(pinned_group_keys, pinned_group_objs)
+        backend.batched_submit_put_task(safe_group_keys, safe_group_objs)
+        for memory_obj in pinned_group_objs + safe_group_objs:
+            memory_obj.ref_count_down()
+
+        assert backend.pin(pinned_group_keys[0])
+        recovered = backend.batched_allocate(
+            shape,
+            torch.uint8,
+            batch_size=batch_size,
+            fmt=MemoryFormat.KV_T2D,
+            busy_loop=False,
+        )
+
+        assert recovered is not None
+        assert all(key in backend.hot_cache for key in pinned_group_keys)
+        assert all(key not in backend.hot_cache for key in safe_group_keys)
+
+        for memory_obj in recovered:
+            memory_obj.ref_count_down()
+        assert backend.unpin(pinned_group_keys[0])
+        backend.clear()
+        assert allocator.memcheck()
+        allocator.close()
+
+
+class TestLocalCPUBackendAllocatorAlignment:
+    def test_rust_odirect_auto_alignment_for_mixed_allocator(self, monkeypatch):
+        config = create_test_config(local_cpu=True)
+        config.max_local_cpu_size = 0.01
+        config.extra_config = {
+            "rust_raw_block.device_path": "/tmp/dev.bin",
+            "rust_raw_block.use_odirect": True,
+            "rust_raw_block.block_align": 4096,
+        }
+        metadata = create_test_metadata()
+
+        captured: dict[str, object] = {}
+
+        class DummyMixedMemoryAllocator:
+            def __init__(self, size, **kwargs):
+                captured["size"] = size
+                captured["kwargs"] = kwargs
+                self.align_bytes = kwargs.get("align_bytes", 4096)
+
+            def close(self):
+                return None
+
+        monkeypatch.setattr(
+            local_cpu_backend_module,
+            "MixedMemoryAllocator",
+            DummyMixedMemoryAllocator,
+        )
+
+        backend = LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
+        try:
+            kwargs = captured["kwargs"]
+            assert isinstance(kwargs, dict)
+            assert kwargs.get("align_bytes") == 4096
+        finally:
+            backend.memory_allocator.close()
+
+    def test_explicit_alignment_override_for_mixed_allocator(self, monkeypatch):
+        config = create_test_config(local_cpu=True)
+        config.max_local_cpu_size = 0.01
+        config.extra_config = {
+            "local_cpu.pinned_align_bytes": 4096,
+            "rust_raw_block.device_path": "/tmp/dev.bin",
+            "rust_raw_block.use_odirect": False,
+        }
+        metadata = create_test_metadata()
+
+        captured: dict[str, object] = {}
+
+        class DummyMixedMemoryAllocator:
+            def __init__(self, size, **kwargs):
+                captured["size"] = size
+                captured["kwargs"] = kwargs
+                self.align_bytes = kwargs.get("align_bytes", 4096)
+
+            def close(self):
+                return None
+
+        monkeypatch.setattr(
+            local_cpu_backend_module,
+            "MixedMemoryAllocator",
+            DummyMixedMemoryAllocator,
+        )
+
+        backend = LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
+        try:
+            kwargs = captured["kwargs"]
+            assert isinstance(kwargs, dict)
+            assert kwargs.get("align_bytes") == 4096
+        finally:
+            backend.memory_allocator.close()
diff --git a/tests/v1/storage_backend/test_local_cpu_backend_nixl_paged.py b/tests/v1/storage_backend/test_local_cpu_backend_nixl_paged.py
new file mode 100644
index 0000000..7952277
--- /dev/null
+++ b/tests/v1/storage_backend/test_local_cpu_backend_nixl_paged.py
@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for LocalCPUBackend.initialize_allocator() NIXL CPU shared-pool path.
+
+Verifies that when NIXL CPU mode is active (enable_nixl_storage=True and
+nixl_buffer_device="cpu") the resulting LocalCPUBackend pool is paged (and
+therefore registrable by NIXL), and that the default path produces a
+non-paged pool. Behavior is checked via MixedMemoryAllocator.get_paged_buffers()
+rather than by peering at the allocator's internal type.
+"""
+
+# Standard
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+import lmcache.v1.memory_management as memory_management_module
+import lmcache.v1.storage_backend.local_cpu_backend as local_cpu_backend_module
+
+
+def create_test_metadata() -> LMCacheMetadata:
+    """Create a minimal test metadata instance."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+
+def create_nixl_cpu_config(cpu_size_gb: float = 0.01) -> LMCacheEngineConfig:
+    """Create a config with NIXL CPU mode enabled."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        lmcache_instance_id="test_nixl_cpu",
+    )
+    config.max_local_cpu_size = cpu_size_gb
+    config.extra_config = {
+        "enable_nixl_storage": True,
+    }
+    config.nixl_buffer_device = "cpu"
+    config.save_unfull_chunk = False
+    return config
+
+
+def create_default_config(cpu_size_gb: float = 0.01) -> LMCacheEngineConfig:
+    """Create a default config without NIXL storage."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        lmcache_instance_id="test_default",
+    )
+    config.max_local_cpu_size = cpu_size_gb
+    return config
+
+
+class TestInitializeAllocatorNixlCpuMode:
+    """Tests for the NIXL CPU shared-pool code path in initialize_allocator()."""
+
+    def test_nixl_cpu_mode_returns_paged_pool(self, monkeypatch):
+        """When enable_nixl_storage=True and nixl_buffer_device='cpu',
+        LocalCPUBackend must expose a paged pool (registrable by NIXL).
+        """
+        metadata = create_test_metadata()
+        config = create_nixl_cpu_config()
+
+        # Compute a buffer size that is a valid multiple of chunk size so the
+        # PagedTensorMemoryAllocator assertion passes.
+        shapes = metadata.get_shapes()
+        dtypes = metadata.get_dtypes()
+        chunk_bytes = sum(
+            s.numel() * d.itemsize for s, d in zip(shapes, dtypes, strict=True)
+        )
+        # Use exactly 4 chunks worth of memory so alignment is trivially satisfied.
+        aligned_bytes = chunk_bytes * 4
+        # Override max_local_cpu_size so the computed cpu_size_bytes == aligned_bytes.
+        config.max_local_cpu_size = aligned_bytes / (1024**3)
+
+        # Replace _allocate_cpu_memory (in memory_management) with one that returns
+        # a real uint8 tensor of the right size so PagedTensorMemoryAllocator can
+        # split it.
+        real_buffer = torch.zeros(aligned_bytes, dtype=torch.uint8)
+
+        monkeypatch.setattr(
+            memory_management_module,
+            "_allocate_cpu_memory",
+            lambda size, *args, **kwargs: real_buffer,
+        )
+        # real_buffer is a plain (pageable) tensor; the real _free_cpu_memory
+        # would call cudaFreeHost on it on a CUDA build and raise
+        # "cudaFreeHost failed". Neutralize free to match the faked alloc.
+        monkeypatch.setattr(
+            memory_management_module, "_free_cpu_memory", lambda *a, **kw: None
+        )
+
+        backend = LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
+        try:
+            # Public behavioral check: in NIXL CPU mode the allocator must be
+            # paged so NIXL can register it as a contiguous pinned region.
+            # MixedMemoryAllocator.get_paged_buffers() returns the page tuple
+            # when the underlying allocator is paged, None otherwise.
+            paged_buffers = backend.get_memory_allocator().get_paged_buffers()
+            assert paged_buffers is not None, (
+                "NIXL CPU mode must produce a paged pool (get_paged_buffers "
+                "returned None — pool is not registrable with NIXL)"
+            )
+        finally:
+            backend.memory_allocator.close()
+
+    def test_default_mode_is_not_paged(self):
+        """Without NIXL flags, the default LocalCPUBackend pool is non-paged
+        (so it cannot be registered with NIXL — the inverse contract of the
+        previous test)."""
+        metadata = create_test_metadata()
+        config = create_default_config()
+        backend = LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
+        try:
+            assert backend.get_memory_allocator().get_paged_buffers() is None, (
+                "Default LocalCPUBackend must NOT be paged; got a paged pool "
+                "which would unexpectedly satisfy NIXL's allocator check."
+            )
+        finally:
+            backend.memory_allocator.close()
+
+    def test_nixl_cpu_mode_only_when_both_flags_set(self, monkeypatch):
+        """NIXL CPU path activates only when BOTH enable_nixl_storage=True AND
+        nixl_buffer_device='cpu'.  If either flag is missing the default
+        (non-paged) pool is used.
+        """
+        metadata = create_test_metadata()
+
+        # Case 1: enable_nixl_storage=True but nixl_buffer_device is None
+        config1 = create_default_config()
+        config1.extra_config = {"enable_nixl_storage": True}
+        backend1 = LocalCPUBackend(config=config1, metadata=metadata, dst_device="cpu")
+        assert backend1.get_memory_allocator().get_paged_buffers() is None
+        backend1.memory_allocator.close()
+
+        # Case 2: nixl_buffer_device='cpu' but enable_nixl_storage not set
+        config2 = create_default_config()
+        config2.nixl_buffer_device = "cpu"
+        backend2 = LocalCPUBackend(config=config2, metadata=metadata, dst_device="cpu")
+        assert backend2.get_memory_allocator().get_paged_buffers() is None
+        backend2.memory_allocator.close()
+
+        # Case 3: nixl_buffer_device='gpu' (not cpu)
+        config3 = create_nixl_cpu_config()
+        config3.nixl_buffer_device = "gpu"
+        backend3 = LocalCPUBackend(config=config3, metadata=metadata, dst_device="cpu")
+        assert backend3.get_memory_allocator().get_paged_buffers() is None
+        backend3.memory_allocator.close()
+
+    def test_nixl_cpu_mode_alignment_warning(self, monkeypatch):
+        """When cpu_size_bytes is NOT a multiple of chunk_bytes, a warning is logged
+        and the size is rounded down to the nearest chunk multiple.
+        """
+        # Standard
+        from unittest.mock import patch
+
+        metadata = create_test_metadata()
+        config = create_nixl_cpu_config()
+
+        shapes = metadata.get_shapes()
+        dtypes = metadata.get_dtypes()
+        chunk_bytes = sum(
+            s.numel() * d.itemsize for s, d in zip(shapes, dtypes, strict=True)
+        )
+        # Deliberately misaligned: 4 chunks + 1 byte
+        misaligned_bytes = chunk_bytes * 4 + 1
+        config.max_local_cpu_size = misaligned_bytes / (1024**3)
+
+        aligned_bytes = chunk_bytes * 4
+        real_buffer = torch.zeros(aligned_bytes, dtype=torch.uint8)
+
+        allocated_sizes: list = []
+
+        def fake_allocate_cpu_memory(size, *args, **kwargs):
+            allocated_sizes.append(size)
+            return real_buffer
+
+        monkeypatch.setattr(
+            memory_management_module,
+            "_allocate_cpu_memory",
+            fake_allocate_cpu_memory,
+        )
+        # real_buffer is a plain (pageable) tensor; the real _free_cpu_memory
+        # would call cudaFreeHost on it on a CUDA build and raise
+        # "cudaFreeHost failed". Neutralize free to match the faked alloc.
+        monkeypatch.setattr(
+            memory_management_module, "_free_cpu_memory", lambda *a, **kw: None
+        )
+
+        # Patch the module-level logger to capture warning calls
+        warning_messages: list = []
+        original_warning = local_cpu_backend_module.logger.warning
+
+        def capture_warning(msg, *args, **kwargs):
+            warning_messages.append(msg % args if args else msg)
+            original_warning(msg, *args, **kwargs)
+
+        with patch.object(
+            local_cpu_backend_module.logger, "warning", side_effect=capture_warning
+        ):
+            backend = LocalCPUBackend(
+                config=config, metadata=metadata, dst_device="cpu"
+            )
+
+        try:
+            # The allocator must have been given the rounded-down size
+            assert len(allocated_sizes) == 1, (
+                f"Expected 1 _allocate_cpu_memory call, got {len(allocated_sizes)}"
+            )
+            assert allocated_sizes[0] == aligned_bytes, (
+                f"Expected aligned size {aligned_bytes}, got {allocated_sizes[0]}"
+            )
+            # A "rounding down" warning should have been emitted via the module logger
+            assert any("rounding down" in w for w in warning_messages), (
+                "Expected a 'rounding down' warning; captured warnings: "
+                f"{warning_messages}"
+            )
+        finally:
+            backend.memory_allocator.close()
+
+    def test_nixl_cpu_mode_raises_on_undersized_buffer(self, monkeypatch):
+        """When cpu_size_bytes < chunk_bytes, initialize_allocator() must raise
+        a ValueError instead of silently creating a zero-capacity allocator.
+        """
+        # Third Party
+        import pytest
+
+        metadata = create_test_metadata()
+        config = create_nixl_cpu_config()
+
+        # Set cpu_size_bytes to exactly 1 byte — smaller than one chunk.
+        config.max_local_cpu_size = 1 / (1024**3)
+
+        with pytest.raises(ValueError, match="smaller than one chunk"):
+            LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
diff --git a/tests/v1/storage_backend/test_local_disk_backend.py b/tests/v1/storage_backend/test_local_disk_backend.py
new file mode 100644
index 0000000..44c7eda
--- /dev/null
+++ b/tests/v1/storage_backend/test_local_disk_backend.py
@@ -0,0 +1,611 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock, patch
+import asyncio
+import os
+import shutil
+import tempfile
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey, DiskCacheMetadata
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.config_base import _parse_local_disk
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.local_disk_backend import LocalDiskBackend
+
+
+class MockLookupServer:
+    def __init__(self):
+        self.removed_keys = []
+        self.inserted_keys = []
+
+    def batched_remove(self, keys):
+        self.removed_keys.extend(keys)
+
+    def batched_insert(self, keys):
+        self.inserted_keys.extend(keys)
+
+
+class MockLMCacheWorker:
+    def __init__(self):
+        self.messages = []
+
+    def put_msg(self, msg):
+        self.messages.append(msg)
+
+
+def create_test_config(
+    disk_path: str,
+    max_disk_size: float = 1.0,
+    local_disk_path_sharding: str = "by_gpu",
+):
+    """Create a test configuration for LocalDiskBackend."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_disk=disk_path,
+        local_disk_path_sharding=local_disk_path_sharding,
+        max_local_disk_size=max_disk_size,
+        lmcache_instance_id="test_instance",
+    )
+    return config
+
+
+def create_test_metadata():
+    """Create a test metadata for LMCacheMetadata."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(28, 2, 256, 8, 128),
+    )
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+    )
+
+
+@pytest.fixture
+def temp_disk_path():
+    """Create a temporary directory for disk storage tests."""
+    temp_dir = tempfile.mkdtemp()
+    yield temp_dir
+    # Cleanup
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir)
+
+
+@pytest.fixture
+def async_loop():
+    """Create an asyncio event loop for testing."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    yield loop
+    loop.close()
+
+
+# ----------------------------------------------------------------------------
+
+
+@pytest.fixture
+def local_cpu_backend(memory_allocator):
+    """Create a LocalCPUBackend for testing."""
+    config = LMCacheEngineConfig.from_legacy(chunk_size=256)
+    return LocalCPUBackend(config, memory_allocator=memory_allocator)
+
+
+@pytest.fixture
+def local_disk_backend(temp_disk_path, async_loop, local_cpu_backend):
+    """Create a LocalDiskBackend for testing."""
+    config = create_test_config(temp_disk_path)
+    return LocalDiskBackend(
+        config=config,
+        loop=async_loop,
+        local_cpu_backend=local_cpu_backend,
+        dst_device="cuda:0",
+    )
+
+
+class TestLocalDiskBackend:
+    """Test cases for LocalDiskBackend."""
+
+    def test_init(self, temp_disk_path, async_loop, local_cpu_backend):
+        """Test LocalDiskBackend initialization."""
+        config = create_test_config(temp_disk_path)
+        backend = LocalDiskBackend(
+            config=config,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cuda:0",
+        )
+
+        assert backend.dst_device == "cuda:0"
+        assert backend.local_cpu_backend == local_cpu_backend
+        assert backend.path == temp_disk_path
+        assert os.path.exists(temp_disk_path)
+        assert backend.lmcache_worker is None
+        assert backend.instance_id == "test_instance"
+        assert backend.usage == 0
+        assert len(backend.dict) == 0
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_init_with_lookup_server_and_worker(
+        self, temp_disk_path, async_loop, local_cpu_backend
+    ):
+        """Test LocalDiskBackend initialization with lookup server and worker."""
+        config = create_test_config(temp_disk_path)
+        lmcache_worker = MockLMCacheWorker()
+
+        backend = LocalDiskBackend(
+            config=config,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cuda:0",
+            lmcache_worker=lmcache_worker,
+        )
+
+        assert backend.lmcache_worker == lmcache_worker
+
+        local_cpu_backend.memory_allocator.close()
+
+    def test_str(self, local_disk_backend):
+        """Test string representation."""
+        assert str(local_disk_backend) == "LocalDiskBackend"
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_key_to_path(self, local_disk_backend):
+        """Test key to path conversion."""
+        key = create_test_key(1)
+        path = local_disk_backend._key_to_path(key)
+
+        expected_filename = key.to_string().replace("/", "-") + ".pt"
+        assert path == os.path.join(local_disk_backend.path, expected_filename)
+
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_contains_key_not_exists(self, local_disk_backend):
+        """Test contains() when key doesn't exist."""
+        key = create_test_key(2)
+        assert not local_disk_backend.contains(key)
+        assert not local_disk_backend.contains(key, pin=True)
+
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_get_blocking_key_not_exists(self, local_disk_backend):
+        """Test get_blocking() when key doesn't exist."""
+        key = create_test_key(2)
+        result = local_disk_backend.get_blocking(key)
+
+        assert result is None
+
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+
+class TestMultiPathDiskBackend:
+    """Test cases for multi-path (multi-device) LocalDiskBackend."""
+
+    def test_init_multi_path(self, async_loop, local_cpu_backend):
+        """Test initialisation with comma-separated paths."""
+        dir_a = tempfile.mkdtemp()
+        dir_b = tempfile.mkdtemp()
+        try:
+            combined = f"{dir_a},{dir_b}"
+            config = create_test_config(combined)
+            backend = LocalDiskBackend(
+                config=config,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cuda:0",
+            )
+
+            # Path selected by device_id (0 % 2 = 0 -> dir_a)
+            assert backend.path == dir_a
+            # Both directories should exist
+            assert os.path.isdir(dir_a)
+            assert os.path.isdir(dir_b)
+            # Block size is a plain int for the selected path
+            assert isinstance(backend.os_disk_bs, int)
+        finally:
+            shutil.rmtree(dir_a, ignore_errors=True)
+            shutil.rmtree(dir_b, ignore_errors=True)
+            local_cpu_backend.memory_allocator.close()
+
+    def test_gpu_affinity_selects_path(self, async_loop, local_cpu_backend):
+        """Different cuda devices select different paths via modulo."""
+        dir_a = tempfile.mkdtemp()
+        dir_b = tempfile.mkdtemp()
+        try:
+            combined = f"{dir_a},{dir_b}"
+            config = create_test_config(combined)
+
+            dirs_by_gpu = {}
+            for device in ("cuda:0", "cuda:1"):
+                backend = LocalDiskBackend(
+                    config=config,
+                    loop=async_loop,
+                    local_cpu_backend=local_cpu_backend,
+                    dst_device=device,
+                )
+                dirs_by_gpu[device] = backend.path
+
+            assert dirs_by_gpu["cuda:0"] == dir_a
+            assert dirs_by_gpu["cuda:1"] == dir_b
+        finally:
+            shutil.rmtree(dir_a, ignore_errors=True)
+            shutil.rmtree(dir_b, ignore_errors=True)
+            local_cpu_backend.memory_allocator.close()
+
+    def test_all_directories_created(self, async_loop, local_cpu_backend):
+        """All paths in the list get their directories created."""
+        base = tempfile.mkdtemp()
+        try:
+            paths = [os.path.join(base, f"nvme{i}") for i in range(3)]
+            combined = ",".join(paths)
+            config = create_test_config(combined)
+            LocalDiskBackend(
+                config=config,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cuda:0",
+            )
+            for p in paths:
+                assert os.path.isdir(p), f"{p} should exist"
+        finally:
+            shutil.rmtree(base, ignore_errors=True)
+            local_cpu_backend.memory_allocator.close()
+
+    def test_single_path_backward_compat(
+        self, temp_disk_path, async_loop, local_cpu_backend
+    ):
+        """A single path (no commas) works exactly as before."""
+        config = create_test_config(temp_disk_path)
+        backend = LocalDiskBackend(
+            config=config,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cuda:0",
+        )
+        assert backend.path == temp_disk_path
+        local_cpu_backend.memory_allocator.close()
+
+    def test_path_sharding_default(self, temp_disk_path, async_loop, local_cpu_backend):
+        """Default local_disk_path_sharding is 'by_gpu' (backend inits OK)."""
+        config = create_test_config(temp_disk_path)
+        backend = LocalDiskBackend(
+            config=config,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cuda:0",
+        )
+        assert backend.path == temp_disk_path
+        local_cpu_backend.memory_allocator.close()
+
+    def test_path_sharding_explicit_by_gpu(
+        self, temp_disk_path, async_loop, local_cpu_backend
+    ):
+        """Explicitly setting local_disk_path_sharding='by_gpu' works."""
+        config = create_test_config(temp_disk_path, local_disk_path_sharding="by_gpu")
+        backend = LocalDiskBackend(
+            config=config,
+            loop=async_loop,
+            local_cpu_backend=local_cpu_backend,
+            dst_device="cuda:0",
+        )
+        assert backend.path == temp_disk_path
+        local_cpu_backend.memory_allocator.close()
+
+    def test_path_sharding_unsupported_raises(
+        self, temp_disk_path, async_loop, local_cpu_backend
+    ):
+        """Unsupported local_disk_path_sharding raises ValueError."""
+        config = create_test_config(
+            temp_disk_path, local_disk_path_sharding="round_robin"
+        )
+        with pytest.raises(ValueError, match="Unsupported path sharding strategy"):
+            LocalDiskBackend(
+                config=config,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cuda:0",
+            )
+
+    def test_cpu_dst_device_defaults_to_first_path(self, async_loop, local_cpu_backend):
+        """dst_device='cpu' should fall back to device_id=0."""
+        dir_a = tempfile.mkdtemp()
+        dir_b = tempfile.mkdtemp()
+        try:
+            combined = f"{dir_a},{dir_b}"
+            config = create_test_config(combined)
+            backend = LocalDiskBackend(
+                config=config,
+                loop=async_loop,
+                local_cpu_backend=local_cpu_backend,
+                dst_device="cpu",
+            )
+            # device_id=0 -> 0 % 2 = 0 -> dir_a
+            assert backend.path == dir_a
+        finally:
+            shutil.rmtree(dir_a, ignore_errors=True)
+            shutil.rmtree(dir_b, ignore_errors=True)
+            local_cpu_backend.memory_allocator.close()
+
+
+class TestParseLocalDisk:
+    """Unit tests for the _parse_local_disk config parser."""
+
+    def test_none(self):
+        assert _parse_local_disk(None) is None
+
+    def test_single_raw_path(self):
+        assert _parse_local_disk("/mnt/nvme0/cache/") == "/mnt/nvme0/cache/"
+
+    def test_single_file_uri(self):
+        assert _parse_local_disk("file:///mnt/nvme0/cache/") == "/mnt/nvme0/cache/"
+
+    def test_single_file_uri_no_trailing_slash(self):
+        assert _parse_local_disk("file:///mnt/nvme0/cache") == "/mnt/nvme0/cache"
+
+    def test_comma_separated_raw(self):
+        result = _parse_local_disk("/mnt/nvme0/,/mnt/nvme1/")
+        assert result == "/mnt/nvme0/,/mnt/nvme1/"
+
+    def test_comma_separated_file_uris(self):
+        result = _parse_local_disk("file:///mnt/nvme0/,file:///mnt/nvme1/")
+        assert result == "/mnt/nvme0/,/mnt/nvme1/"
+
+    def test_mixed_uri_and_raw(self):
+        result = _parse_local_disk("file:///mnt/nvme0/,/mnt/nvme1/")
+        assert result == "/mnt/nvme0/,/mnt/nvme1/"
+
+    def test_whitespace_around_paths(self):
+        result = _parse_local_disk("  /mnt/nvme0/ , /mnt/nvme1/  ")
+        assert result == "/mnt/nvme0/,/mnt/nvme1/"
+
+    def test_empty_string(self):
+        assert _parse_local_disk("") is None
+
+
+class TestGetBlockingCachePolicyUpdate:
+    """Regression tests for phantom cache hit in get_blocking() (issue #3015).
+
+    ``get_blocking()`` must call ``cache_policy.update_on_hit()`` only when
+    ``load_bytes_from_disk()`` returns a valid ``MemoryObj``.  Calling it
+    before confirming load success records a phantom hit that skews future
+    eviction decisions.
+    """
+
+    def _inject_key(
+        self,
+        backend: LocalDiskBackend,
+        key: CacheEngineKey,
+        shape: torch.Size,
+        dtype: torch.dtype,
+    ) -> None:
+        """Insert a key into backend.dict without writing anything to disk."""
+        meta = DiskCacheMetadata(
+            path="/nonexistent/path.pt",
+            size=0,
+            shape=shape,
+            dtype=dtype,
+            cached_positions=None,
+            fmt=MemoryFormat.KV_2LTD,
+            pin_count=0,
+        )
+        with backend.disk_lock:
+            backend.dict[key] = meta
+            backend.cache_policy.update_on_put(key)
+
+    def test_no_phantom_hit_when_load_fails(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """update_on_hit must NOT be called when load_bytes_from_disk returns None."""
+        key = create_test_key(101)
+        shape = torch.Size([28, 2, 256, 8, 128])
+        self._inject_key(local_disk_backend, key, shape, torch.bfloat16)
+
+        with patch.object(
+            local_disk_backend, "load_bytes_from_disk", return_value=None
+        ):
+            with patch.object(
+                local_disk_backend.cache_policy, "update_on_hit"
+            ) as mock_update:
+                result = local_disk_backend.get_blocking(key)
+
+        assert result is None
+        mock_update.assert_not_called()
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_updates_cache_policy_on_successful_load(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """update_on_hit must be called exactly once when the load succeeds."""
+        key = create_test_key(102)
+        shape = torch.Size([28, 2, 256, 8, 128])
+        self._inject_key(local_disk_backend, key, shape, torch.bfloat16)
+
+        fake_memory_obj = MagicMock(spec=MemoryObj)
+        with patch.object(
+            local_disk_backend, "load_bytes_from_disk", return_value=fake_memory_obj
+        ):
+            with patch.object(
+                local_disk_backend.cache_policy, "update_on_hit"
+            ) as mock_update:
+                result = local_disk_backend.get_blocking(key)
+
+        assert result is fake_memory_obj
+        mock_update.assert_called_once_with(key, local_disk_backend.dict)
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_key_absent_returns_none_without_policy_update(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """get_blocking must return None immediately when the key is not cached."""
+        key = create_test_key(103)
+
+        with patch.object(
+            local_disk_backend.cache_policy, "update_on_hit"
+        ) as mock_update:
+            result = local_disk_backend.get_blocking(key)
+
+        assert result is None
+        mock_update.assert_not_called()
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+
+class TestBatchedGetBlocking:
+    """Tests for the concurrent batched_get_blocking() override."""
+
+    _SHAPE = torch.Size([28, 2, 256, 8, 128])
+    _DTYPE = torch.bfloat16
+
+    def _write_key(
+        self,
+        backend: LocalDiskBackend,
+        key: CacheEngineKey,
+    ) -> bytes:
+        """Write random data to disk for *key* and register it in the backend.
+
+        Returns the raw bytes that were written so callers can verify reads.
+        """
+        path = backend._key_to_path(key)
+        nbytes = 1
+        for s in self._SHAPE:
+            nbytes *= s
+        nbytes *= self._DTYPE.itemsize
+        data = os.urandom(nbytes)
+        with open(path, "wb") as f:
+            f.write(data)
+        backend.insert_key(
+            key,
+            size=nbytes,
+            shape=self._SHAPE,
+            dtype=self._DTYPE,
+            fmt=MemoryFormat.KV_2LTD,
+        )
+        return data
+
+    def test_all_keys_missing(self, local_disk_backend: LocalDiskBackend) -> None:
+        """batched_get_blocking returns [None, …] when no keys are cached."""
+        keys = [create_test_key(i) for i in range(200, 204)]
+        results = local_disk_backend.batched_get_blocking(keys)
+
+        assert len(results) == len(keys)
+        assert all(r is None for r in results)
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_reads_match_written_data(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """Data loaded by batched_get_blocking matches what was written."""
+        keys = [create_test_key(i) for i in range(210, 214)]
+        expected_data = {}
+        for key in keys:
+            expected_data[key] = self._write_key(local_disk_backend, key)
+
+        results = local_disk_backend.batched_get_blocking(keys)
+
+        assert len(results) == len(keys)
+        for key, mem_obj in zip(keys, results, strict=True):
+            assert mem_obj is not None, f"Expected data for {key}"
+            actual = bytes(mem_obj.byte_array)
+            assert actual == expected_data[key]
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_mixed_hit_and_miss(self, local_disk_backend: LocalDiskBackend) -> None:
+        """Handles a mix of cached and missing keys correctly."""
+        present_key = create_test_key(220)
+        missing_key = create_test_key(221)
+        expected = self._write_key(local_disk_backend, present_key)
+
+        results = local_disk_backend.batched_get_blocking([present_key, missing_key])
+
+        assert len(results) == 2
+        assert results[0] is not None
+        assert bytes(results[0].byte_array) == expected
+        assert results[1] is None
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_cache_policy_updated_only_for_hits(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """update_on_hit is called only for keys that were successfully loaded."""
+        hit_key = create_test_key(230)
+        miss_key = create_test_key(231)
+        self._write_key(local_disk_backend, hit_key)
+
+        with patch.object(
+            local_disk_backend.cache_policy, "update_on_hit"
+        ) as mock_update:
+            results = local_disk_backend.batched_get_blocking([hit_key, miss_key])
+
+        assert results[0] is not None
+        assert results[1] is None
+        mock_update.assert_called_once_with(hit_key, local_disk_backend.dict)
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_single_key_delegates_to_get_blocking(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """A single-key batch falls through to get_blocking (fast path)."""
+        key = create_test_key(240)
+        sentinel = MagicMock(spec=MemoryObj)
+        with patch.object(
+            local_disk_backend, "get_blocking", return_value=sentinel
+        ) as mock_get:
+            results = local_disk_backend.batched_get_blocking([key])
+
+        assert results == [sentinel]
+        mock_get.assert_called_once_with(key)
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_concurrent_reads_use_multiple_threads(
+        self, local_disk_backend: LocalDiskBackend
+    ) -> None:
+        """Verify that reads actually fan out across threads."""
+        keys = [create_test_key(i) for i in range(250, 254)]
+        for key in keys:
+            self._write_key(local_disk_backend, key)
+
+        thread_ids: list[int] = []
+        lock = threading.Lock()
+        original_read_file = local_disk_backend.read_file
+
+        def tracking_read_file(key, buffer, path):
+            with lock:
+                thread_ids.append(threading.current_thread().ident)
+            return original_read_file(key, buffer, path)
+
+        with patch.object(
+            local_disk_backend, "read_file", side_effect=tracking_read_file
+        ):
+            results = local_disk_backend.batched_get_blocking(keys)
+
+        assert all(r is not None for r in results)
+        # With 4 keys and 4 threads, we should see more than 1 unique thread.
+        assert len(set(thread_ids)) > 1, (
+            f"Expected multiple threads, got {set(thread_ids)}"
+        )
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
+
+    def test_empty_keys_list(self, local_disk_backend: LocalDiskBackend) -> None:
+        """An empty key list returns an empty result list."""
+        results = local_disk_backend.batched_get_blocking([])
+        assert results == []
+        local_disk_backend.local_cpu_backend.memory_allocator.close()
diff --git a/tests/v1/storage_backend/test_maru_backend.py b/tests/v1/storage_backend/test_maru_backend.py
new file mode 100644
index 0000000..94961e2
--- /dev/null
+++ b/tests/v1/storage_backend/test_maru_backend.py
@@ -0,0 +1,788 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from unittest.mock import MagicMock, patch
+import asyncio
+import mmap
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat, TensorMemoryObj
+from lmcache.v1.pin_monitor import PinMonitor
+from lmcache.v1.storage_backend.abstract_backend import AllocatorBackendInterface
+from tests.v1.utils import (
+    check_method_signatures,
+    get_abstract_methods,
+    get_methods_implemented_in_class,
+)
+
+maru = pytest.importorskip("maru", reason="maru package not installed")
+maru_lmcache = pytest.importorskip(
+    "maru_lmcache", reason="maru_lmcache package not installed"
+)
+
+# Third Party
+from maru_handler.memory import AllocHandle  # noqa: E402
+from maru_handler.memory.types import MappedRegion, MemoryInfo  # noqa: E402
+from maru_lmcache.adapter import CxlMemoryAdapter  # noqa: E402
+
+# First Party
+from lmcache.v1.storage_backend.maru_backend import MaruBackend  # noqa: E402
+
+# =========================================================================
+# Constants
+# =========================================================================
+
+TEST_CHUNK_SIZE = 1024
+TEST_DTYPE = torch.float32
+TEST_SHAPE = torch.Size([256])  # 256 * 4B = 1024 bytes = chunk_size
+
+
+# =========================================================================
+# Helpers
+# =========================================================================
+
+
+def _make_mock_handler(pool_size=4096, chunk_size=TEST_CHUNK_SIZE):
+    """Create a mock MaruHandler with mmap-backed regions."""
+    handler = MagicMock()
+    handler._connected = True
+
+    region_id = 100
+    page_count = pool_size // chunk_size
+
+    mmap_obj = mmap.mmap(-1, pool_size)
+    mapped_region = MappedRegion(
+        region_id=region_id,
+        handle=MagicMock(region_id=region_id, length=pool_size),
+        size=pool_size,
+        _mmap_obj=mmap_obj,
+    )
+
+    handler.get_buffer_view.side_effect = lambda rid, offset, size: (
+        mapped_region.get_buffer_view(offset, size) if rid == region_id else None
+    )
+    handler.get_region_page_count.side_effect = lambda rid: (
+        page_count if rid == region_id else None
+    )
+    handler.get_owned_region_ids.return_value = [region_id]
+    handler.get_chunk_size.return_value = chunk_size
+
+    def mock_set_on_region_added(callback):
+        if callback is not None:
+            callback(region_id, page_count)
+
+    handler.set_on_region_added.side_effect = mock_set_on_region_added
+
+    page_counter = [0]
+
+    def mock_alloc(size):
+        idx = page_counter[0]
+        page_counter[0] += 1
+        buf = mapped_region.get_buffer_view(idx * chunk_size, size)
+        return AllocHandle(buf=buf, _region_id=region_id, _page_index=idx, _size=size)
+
+    handler.alloc.side_effect = mock_alloc
+    handler.free = MagicMock()
+    handler.connect.return_value = True
+    handler.close.return_value = None
+    handler.store.return_value = True
+    handler.batch_store.return_value = None
+    handler.retrieve.return_value = None
+    handler.batch_retrieve.return_value = []
+    handler.exists.return_value = False
+    handler.batch_exists.return_value = []
+    handler.delete.return_value = True
+    handler.pin.return_value = True
+    handler.unpin.return_value = True
+    handler.batch_pin.return_value = []
+    handler.batch_unpin.return_value = None
+
+    return handler
+
+
+def _make_cache_key(chunk_hash: int = 12345) -> CacheEngineKey:
+    """Create a CacheEngineKey for testing."""
+    return CacheEngineKey(
+        model_name="test-model",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=chunk_hash,
+        dtype=torch.float32,
+    )
+
+
+def _make_memory_obj(adapter: CxlMemoryAdapter) -> TensorMemoryObj:
+    """Allocate a TensorMemoryObj from the adapter."""
+    obj = adapter.allocate(TEST_SHAPE, TEST_DTYPE)
+    assert obj is not None
+    return obj
+
+
+# =========================================================================
+# Fixtures
+# =========================================================================
+
+
+@pytest.fixture(autouse=True)
+def _init_pin_monitor():
+    """Initialize PinMonitor singleton required by TensorMemoryObj.pin()."""
+    PinMonitor._instance = None
+    PinMonitor.GetOrCreate(LMCacheEngineConfig.from_defaults())
+    yield
+    PinMonitor._instance = None
+
+
+@pytest.fixture
+def async_loop():
+    """Provide an asyncio event loop running in a background thread."""
+    loop = asyncio.new_event_loop()
+    thread = threading.Thread(target=loop.run_forever, daemon=True)
+    thread.start()
+    yield loop
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=5)
+    loop.close()
+
+
+@pytest.fixture
+def mock_handler():
+    return _make_mock_handler()
+
+
+@pytest.fixture
+def adapter(mock_handler):
+    return CxlMemoryAdapter(
+        handler=mock_handler,
+        shapes=[TEST_SHAPE],
+        dtypes=[TEST_DTYPE],
+        fmt=MemoryFormat.KV_2LTD,
+        chunk_size=TEST_CHUNK_SIZE,
+    )
+
+
+@pytest.fixture
+def backend(mock_handler, adapter, async_loop):
+    """Create a MaruBackend with mocked internals."""
+    # Local
+
+    with patch.object(MaruBackend, "initialize_allocator", return_value=adapter):
+        backend = MaruBackend.__new__(MaruBackend)
+        backend.dst_device = "cpu"
+        backend.config = MagicMock()
+        backend.config.maru_pool_size = 4.0
+        backend.loop = async_loop
+        backend.memory_allocator = adapter
+        backend._handler = mock_handler
+
+        backend._full_chunk_size_bytes = TEST_CHUNK_SIZE
+        backend._single_token_size = TEST_CHUNK_SIZE // 256  # 4 bytes per token
+        backend._mla_worker_id_as0_mode = False
+
+        backend.put_lock = threading.Lock()
+        backend.put_tasks = set()
+    return backend
+
+
+def _run_async(loop, coro):
+    """Submit a coroutine to a running event loop and wait for result."""
+    future = asyncio.run_coroutine_threadsafe(coro, loop)
+    return future.result(timeout=5)
+
+
+# =========================================================================
+# Tests — Init & Interface Compliance
+# =========================================================================
+
+
+class TestMaruBackendInit:
+    def test_str(self, backend):
+        assert str(backend) == "MaruBackend"
+
+    def test_get_allocator_backend_returns_self(self, backend):
+        assert backend.get_allocator_backend() is backend
+
+    def test_get_memory_allocator_returns_adapter(self, backend, adapter):
+        assert backend.get_memory_allocator() is adapter
+
+
+class TestMaruBackendPoolSizeGbToBytes:
+    """Test _pool_size_gb_to_bytes static method."""
+
+    def test_4gb(self):
+        assert MaruBackend._pool_size_gb_to_bytes(4.0) == 4 * 1024**3
+
+    def test_half_gb(self):
+        assert MaruBackend._pool_size_gb_to_bytes(0.5) == 512 * 1024**2
+
+    def test_1gb(self):
+        assert MaruBackend._pool_size_gb_to_bytes(1.0) == 1024**3
+
+    def test_zero(self):
+        assert MaruBackend._pool_size_gb_to_bytes(0.0) == 0
+
+
+class TestMaruBackendInterfaceCompliance:
+    """Verify MaruBackend implements all required interface methods."""
+
+    def test_implements_all_abstract_methods(self):
+        abstract = get_abstract_methods(AllocatorBackendInterface)
+        implemented = get_methods_implemented_in_class(
+            MaruBackend, AllocatorBackendInterface
+        )
+        missing = abstract - implemented
+        assert not missing, f"Missing abstract methods: {missing}"
+
+    def test_method_signatures_match(self):
+        # Known: batched_submit_put_task uses 'memory_objs' instead of 'objs'
+        # TODO: Rename to 'objs' for full compliance
+        known_param_renames = {"batched_submit_put_task"}
+
+        mismatches = check_method_signatures(AllocatorBackendInterface, MaruBackend)
+        unexpected = [m for m in mismatches if m["method"] not in known_param_renames]
+        assert not unexpected, f"Signature mismatches: {unexpected}"
+
+
+# =========================================================================
+# Tests — Allocate
+# =========================================================================
+
+
+class TestMaruBackendAllocate:
+    def test_allocate_returns_memory_obj(self, backend):
+        obj = backend.allocate(TEST_SHAPE, TEST_DTYPE)
+        assert obj is not None
+        assert obj.tensor is not None
+        assert obj.metadata.dtype == TEST_DTYPE
+
+    def test_batched_allocate_returns_list(self, backend):
+        objs = backend.batched_allocate(TEST_SHAPE, TEST_DTYPE, batch_size=3)
+        assert objs is not None
+        assert len(objs) == 3
+        for obj in objs:
+            assert obj.tensor is not None
+
+
+# =========================================================================
+# Tests — Put (async)
+# =========================================================================
+
+
+class TestMaruBackendPut:
+    def test_submit_put_task_returns_future(self, backend, adapter):
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+
+        future = backend.submit_put_task(key, obj)
+        assert future is not None
+        future.result(timeout=5)
+
+        backend._handler.store.assert_called_once()
+
+    def test_submit_put_task_tracks_in_flight(self, backend, adapter):
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+
+        assert not backend.exists_in_put_tasks(key)
+
+        future = backend.submit_put_task(key, obj)
+        future.result(timeout=5)
+
+        # After completion, key should be removed from put_tasks
+        assert not backend.exists_in_put_tasks(key)
+
+    def test_exists_in_put_tasks_true_during_store(self, backend, adapter):
+        """Verify exists_in_put_tasks returns True while store is in progress."""
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+
+        store_entered = threading.Event()
+        store_proceed = threading.Event()
+
+        def blocking_store(*args, **kwargs):
+            store_entered.set()
+            store_proceed.wait(timeout=5)
+            return True
+
+        backend._handler.store.side_effect = blocking_store
+
+        future = backend.submit_put_task(key, obj)
+
+        # Wait until store is actually running
+        assert store_entered.wait(timeout=5)
+        assert backend.exists_in_put_tasks(key)
+
+        # Let store complete
+        store_proceed.set()
+        future.result(timeout=5)
+        assert not backend.exists_in_put_tasks(key)
+
+    def test_batched_submit_put_task(self, backend, adapter):
+        keys = [_make_cache_key(i) for i in range(3)]
+        objs = [_make_memory_obj(adapter) for _ in range(3)]
+        for obj in objs:
+            obj.parent_allocator = None
+
+        backend._handler.batch_store.return_value = [True, True, True]
+
+        futures = backend.batched_submit_put_task(keys, objs)
+        assert futures is not None
+
+        for future in futures:
+            future.result(timeout=5)
+
+        backend._handler.batch_store.assert_called_once()
+
+    def test_submit_put_calls_callback(self, backend, adapter):
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+        callback_called = []
+
+        def callback(k):
+            callback_called.append(k)
+
+        future = backend.submit_put_task(key, obj, on_complete_callback=callback)
+        future.result(timeout=5)
+
+        assert len(callback_called) == 1
+        assert callback_called[0] == key
+
+    def test_batched_submit_put_calls_callback_per_key(self, backend, adapter):
+        keys = [_make_cache_key(i) for i in range(3)]
+        objs = [_make_memory_obj(adapter) for _ in range(3)]
+        for obj in objs:
+            obj.parent_allocator = None
+
+        backend._handler.batch_store.return_value = [True, True, True]
+        callback_keys = []
+
+        def callback(k):
+            callback_keys.append(k)
+
+        futures = backend.batched_submit_put_task(
+            keys, objs, on_complete_callback=callback
+        )
+        for future in futures:
+            future.result(timeout=5)
+
+        assert set(callback_keys) == set(keys)
+
+    def test_submit_put_task_skips_in_mla_mode(self, backend, adapter):
+        """In MLA worker_id_as0 mode, submit_put_task should skip store."""
+        backend._mla_worker_id_as0_mode = True
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+
+        future = backend.submit_put_task(key, obj)
+        assert future.result(timeout=5) is None
+        backend._handler.store.assert_not_called()
+
+    def test_submit_put_task_refcount_down_on_failure(self, backend, adapter):
+        """On store failure, ref_count should return to pre-submit level."""
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+        initial_ref = obj.get_ref_count()
+
+        backend._handler.store.side_effect = RuntimeError("store failed")
+
+        future = backend.submit_put_task(key, obj)
+        with pytest.raises(RuntimeError):
+            future.result(timeout=5)
+
+        assert obj.get_ref_count() == initial_ref
+        assert not backend.exists_in_put_tasks(key)
+
+    def test_batched_submit_put_task_refcount_down_on_failure(self, backend, adapter):
+        """On batch_store failure, ref_count should return to pre-submit level."""
+        keys = [_make_cache_key(i) for i in range(3)]
+        objs = [_make_memory_obj(adapter) for _ in range(3)]
+        for obj in objs:
+            obj.parent_allocator = None
+        initial_refs = [obj.get_ref_count() for obj in objs]
+
+        backend._handler.batch_store.side_effect = RuntimeError("batch failed")
+
+        futures = backend.batched_submit_put_task(keys, objs)
+        for future in futures:
+            with pytest.raises(RuntimeError):
+                future.result(timeout=5)
+
+        for obj, initial_ref in zip(objs, initial_refs, strict=False):
+            assert obj.get_ref_count() == initial_ref
+        for key in keys:
+            assert not backend.exists_in_put_tasks(key)
+
+    def test_batched_submit_put_task_skips_in_mla_mode(self, backend, adapter):
+        """In MLA worker_id_as0 mode, batched_submit_put_task should skip."""
+        backend._mla_worker_id_as0_mode = True
+        keys = [_make_cache_key(i) for i in range(3)]
+        objs = [_make_memory_obj(adapter) for _ in range(3)]
+        for obj in objs:
+            obj.parent_allocator = None
+
+        result = backend.batched_submit_put_task(keys, objs)
+        assert result is None
+        backend._handler.batch_store.assert_not_called()
+
+
+# =========================================================================
+# Tests — Get (sync)
+# =========================================================================
+
+
+class TestMaruBackendGet:
+    def test_get_blocking_hit(self, backend, adapter):
+        key = _make_cache_key()
+
+        data_size = TEST_CHUNK_SIZE
+        data = bytearray(data_size)
+        mock_info = MemoryInfo(
+            view=memoryview(data),
+            region_id=100,
+            page_index=0,
+        )
+        backend._handler.retrieve.return_value = mock_info
+
+        result = backend.get_blocking(key)
+        assert result is not None
+        backend._handler.retrieve.assert_called_once()
+
+    def test_get_blocking_miss(self, backend):
+        key = _make_cache_key()
+        backend._handler.retrieve.return_value = None
+
+        result = backend.get_blocking(key)
+        assert result is None
+
+    def test_get_blocking_ref_count_increases(self, backend, adapter):
+        """After get_blocking, the returned MemoryObj should have ref_count
+        incremented."""
+        # Pre-allocate so pool has page 0
+        _make_memory_obj(adapter)
+
+        key = _make_cache_key()
+        mock_info = MemoryInfo(
+            view=memoryview(bytearray(TEST_CHUNK_SIZE)),
+            region_id=100,
+            page_index=0,
+        )
+        backend._handler.retrieve.return_value = mock_info
+
+        result = backend.get_blocking(key)
+        assert result is not None
+        # Pool objects start with ref_count=1, get_blocking calls ref_count_up
+        assert result.get_ref_count() >= 2
+
+    def test_batched_get_blocking(self, backend, adapter):
+        """batched_get_blocking returns list of MemoryObj via batch_retrieve."""
+        objs = [_make_memory_obj(adapter) for _ in range(2)]
+        keys = [_make_cache_key(i) for i in range(2)]
+
+        infos = []
+        for obj in objs:
+            rid, pid = CxlMemoryAdapter.decode_address(obj.metadata.address)
+            infos.append(
+                MemoryInfo(
+                    view=memoryview(bytearray(TEST_CHUNK_SIZE)),
+                    region_id=rid,
+                    page_index=pid,
+                )
+            )
+        backend._handler.batch_retrieve.return_value = infos
+
+        results = backend.batched_get_blocking(keys)
+        assert len(results) == 2
+        for r in results:
+            assert r is not None
+
+    def test_batched_get_blocking_with_miss(self, backend, adapter):
+        """batched_get_blocking returns None for missing keys."""
+        obj = _make_memory_obj(adapter)
+        keys = [_make_cache_key(i) for i in range(2)]
+
+        rid, pid = CxlMemoryAdapter.decode_address(obj.metadata.address)
+        info = MemoryInfo(
+            view=memoryview(bytearray(TEST_CHUNK_SIZE)),
+            region_id=rid,
+            page_index=pid,
+        )
+        backend._handler.batch_retrieve.return_value = [info, None]
+
+        results = backend.batched_get_blocking(keys)
+        assert len(results) == 2
+        assert results[0] is not None
+        assert results[1] is None
+
+
+# =========================================================================
+# Tests — Contains
+# =========================================================================
+
+
+class TestMaruBackendContains:
+    def test_contains_true(self, backend):
+        key = _make_cache_key()
+        backend._handler.exists.return_value = True
+
+        assert backend.contains(key) is True
+        backend._handler.exists.assert_called_once_with(key.to_string())
+
+    def test_contains_false(self, backend):
+        key = _make_cache_key()
+        backend._handler.exists.return_value = False
+
+        assert backend.contains(key) is False
+
+    def test_batched_contains_all_hit(self, backend):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_exists.return_value = [True, True, True]
+
+        result = backend.batched_contains(keys)
+        assert result == 3
+
+    def test_batched_contains_partial_prefix(self, backend):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_exists.return_value = [True, True, False]
+
+        result = backend.batched_contains(keys)
+        assert result == 2
+
+    def test_batched_contains_first_miss(self, backend):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_exists.return_value = [False, True, True]
+
+        result = backend.batched_contains(keys)
+        assert result == 0
+
+    def test_contains_with_pin(self, backend):
+        key = _make_cache_key()
+        backend._handler.pin.return_value = True
+
+        assert backend.contains(key, pin=True) is True
+        backend._handler.pin.assert_called_once_with(key.to_string())
+        backend._handler.exists.assert_not_called()
+
+    def test_contains_with_pin_false(self, backend):
+        key = _make_cache_key()
+        backend._handler.pin.return_value = False
+
+        assert backend.contains(key, pin=True) is False
+
+    def test_batched_contains_with_pin(self, backend):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_pin.return_value = [True, True, True]
+
+        result = backend.batched_contains(keys, pin=True)
+        assert result == 3
+        backend._handler.batch_pin.assert_called_once_with(
+            [k.to_string() for k in keys]
+        )
+        backend._handler.batch_exists.assert_not_called()
+
+    def test_batched_contains_with_pin_partial(self, backend):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_pin.return_value = [True, False, True]
+
+        result = backend.batched_contains(keys, pin=True)
+        assert result == 1
+
+    def test_batched_contains_empty(self, backend):
+        backend._handler.batch_exists.return_value = []
+        assert backend.batched_contains([]) == 0
+
+
+# =========================================================================
+# Tests — Async Lookup
+# =========================================================================
+
+
+class TestMaruBackendAsyncLookup:
+    def test_batched_async_contains_all_hit(self, backend, async_loop):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_exists.return_value = [True, True, True]
+
+        result = _run_async(
+            async_loop, backend.batched_async_contains("lookup-1", keys)
+        )
+        assert result == 3
+
+    def test_batched_async_contains_partial_prefix(self, backend, async_loop):
+        keys = [_make_cache_key(i) for i in range(3)]
+        backend._handler.batch_exists.return_value = [True, False, True]
+
+        result = _run_async(
+            async_loop, backend.batched_async_contains("lookup-2", keys)
+        )
+        assert result == 1
+
+    def test_batched_async_contains_empty(self, backend, async_loop):
+        backend._handler.batch_exists.return_value = []
+        result = _run_async(async_loop, backend.batched_async_contains("lookup-3", []))
+        assert result == 0
+
+    def test_batched_get_non_blocking_all_hit(self, backend, adapter, async_loop):
+        keys = [_make_cache_key(i) for i in range(2)]
+
+        objs = [_make_memory_obj(adapter) for _ in range(2)]
+        infos = []
+        for obj in objs:
+            rid, pid = CxlMemoryAdapter.decode_address(obj.metadata.address)
+            infos.append(
+                MemoryInfo(
+                    view=memoryview(bytearray(TEST_CHUNK_SIZE)),
+                    region_id=rid,
+                    page_index=pid,
+                )
+            )
+        backend._handler.batch_retrieve.return_value = infos
+
+        results = _run_async(
+            async_loop, backend.batched_get_non_blocking("lookup-4", keys)
+        )
+        assert len(results) == 2
+        for obj in results:
+            assert obj is not None
+
+    def test_batched_get_non_blocking_prefix_stop_on_miss(
+        self, backend, adapter, async_loop
+    ):
+        """Second key is a miss -> only first returned (prefix semantics)."""
+        keys = [_make_cache_key(i) for i in range(3)]
+
+        obj = _make_memory_obj(adapter)
+        rid, pid = CxlMemoryAdapter.decode_address(obj.metadata.address)
+        info = MemoryInfo(
+            view=memoryview(bytearray(TEST_CHUNK_SIZE)),
+            region_id=rid,
+            page_index=pid,
+        )
+        # hit, miss, hit -> should return only [hit]
+        backend._handler.batch_retrieve.return_value = [info, None, info]
+
+        results = _run_async(
+            async_loop, backend.batched_get_non_blocking("lookup-5", keys)
+        )
+        assert len(results) == 1
+
+    def test_batched_get_non_blocking_empty(self, backend, async_loop):
+        backend._handler.batch_retrieve.return_value = []
+        results = _run_async(
+            async_loop, backend.batched_get_non_blocking("lookup-6", [])
+        )
+        assert results == []
+
+
+# =========================================================================
+# Tests — Pin / Unpin / Remove
+# =========================================================================
+
+
+class TestMaruBackendPinRemove:
+    def test_pin_delegates_to_handler(self, backend):
+        key = _make_cache_key()
+        backend._handler.pin.return_value = True
+
+        assert backend.pin(key) is True
+        backend._handler.pin.assert_called_once_with(key.to_string())
+
+    def test_pin_returns_false_on_failure(self, backend):
+        key = _make_cache_key()
+        backend._handler.pin.return_value = False
+
+        assert backend.pin(key) is False
+
+    def test_unpin_delegates_to_handler(self, backend):
+        key = _make_cache_key()
+        backend._handler.unpin.return_value = True
+
+        assert backend.unpin(key) is True
+        backend._handler.unpin.assert_called_once_with(key.to_string())
+
+    def test_unpin_returns_false_on_failure(self, backend):
+        key = _make_cache_key()
+        backend._handler.unpin.return_value = False
+
+        assert backend.unpin(key) is False
+
+    def test_batched_unpin(self, backend):
+        keys = [_make_cache_key(i) for i in range(3)]
+
+        backend.batched_unpin(keys)
+        backend._handler.batch_unpin.assert_called_once_with(
+            [k.to_string() for k in keys]
+        )
+
+    def test_batched_unpin_empty(self, backend):
+        backend.batched_unpin([])
+        backend._handler.batch_unpin.assert_not_called()
+
+    def test_remove_existing_key(self, backend):
+        key = _make_cache_key()
+        backend._handler.delete.return_value = True
+
+        result = backend.remove(key)
+        assert result is True
+        backend._handler.delete.assert_called_once_with(key.to_string())
+
+    def test_remove_nonexistent_key(self, backend):
+        key = _make_cache_key()
+        backend._handler.delete.return_value = False
+
+        result = backend.remove(key)
+        assert result is False
+
+
+# =========================================================================
+# Tests — Lifecycle
+# =========================================================================
+
+
+class TestMaruBackendLifecycle:
+    def test_close_calls_handler_and_allocator(self, backend):
+        backend.memory_allocator = MagicMock()
+        backend.close()
+        backend.memory_allocator.close.assert_called_once()
+        backend._handler.close.assert_called_once()
+
+    def test_close_drains_pending_put_tasks(self, backend, adapter):
+        """close() should wait for in-flight put tasks to complete."""
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+        key = _make_cache_key()
+
+        # Submit a real put task that will complete via the event loop
+        future = backend.submit_put_task(key, obj)
+        future.result(timeout=5)
+
+        # After drain, close should succeed
+        backend.close()
+        backend._handler.close.assert_called_once()
+
+
+# =========================================================================
+# Tests — Store Handle Roundtrip
+# =========================================================================
+
+
+class TestMaruBackendStoreHandle:
+    def test_store_handle_roundtrip(self, backend, adapter):
+        """AllocHandle from create_store_handle should match original."""
+        obj = _make_memory_obj(adapter)
+        obj.parent_allocator = None
+
+        handle = adapter.create_store_handle(obj)
+        assert handle.region_id == 100
+        assert handle.page_index == 0
+        assert handle._size == obj.metadata.phy_size
diff --git a/tests/v1/storage_backend/test_nixl_shared_pool.py b/tests/v1/storage_backend/test_nixl_shared_pool.py
new file mode 100644
index 0000000..922577f
--- /dev/null
+++ b/tests/v1/storage_backend/test_nixl_shared_pool.py
@@ -0,0 +1,688 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for NixlStorageBackend shared-pool (CPU mode) constructor-based init.
+
+Verifies that local_cpu_backend is wired up at construction time (no post_init),
+get_allocator_backend() returns the correct backend, and error cases are caught
+early. No real NIXL hardware needed — agent constructors are stubbed per test,
+and when the nixl package is not installed it is shadowed at sys.modules level
+only for the duration of this module's import (see _install_nixl_mock_if_absent).
+"""
+
+# Standard
+from unittest.mock import MagicMock
+import asyncio
+import sys
+import types
+
+# Third Party
+import pytest
+import torch
+
+# ---------------------------------------------------------------------------
+# Mock the nixl package before any import of nixl_storage_backend
+# ---------------------------------------------------------------------------
+
+
+def _install_nixl_mock_if_absent() -> list:
+    """Install a fake ``nixl`` package so this module can import
+    ``nixl_storage_backend`` and exercise its construction paths without a real
+    NIXL build. Returns the list of ``sys.modules`` keys it inserted.
+
+    The fake is removed again immediately after the imports below — it must NOT
+    outlive this module's import. Other nixl test modules gate on
+    ``pytest.importorskip("nixl")`` and import ``nixl`` at module top; a fake
+    left in ``sys.modules`` during collection would make those modules run
+    against the mock instead of skipping (or, with real nixl present, shadow it)
+    and fail. Removing it at import time — rather than in a teardown — closes
+    that window, because pytest imports each module to completion during
+    collection before collecting the next one (a teardown runs far too late).
+
+    When real nixl is installed we install nothing and use it as-is; the
+    per-test agent ``__init__`` stubs keep the tests off any real transport.
+    """
+    try:
+        # Third Party
+        import nixl  # noqa: F401
+        import nixl._api  # noqa: F401
+
+        return []
+    except ImportError:
+        pass
+
+    nixlBind_mock = MagicMock()
+    nixlBind_mock.nixlRegDList = object
+    nixlBind_mock.nixlXferDList = object
+    nixlBind_mock.nixlBackendError = Exception
+
+    sync_t_mock = MagicMock()
+    sync_t_mock.NIXL_THREAD_SYNC_STRICT = "NIXL_THREAD_SYNC_STRICT"
+
+    api_mock = types.ModuleType("nixl._api")
+    api_mock.nixl_agent = MagicMock  # type: ignore[attr-defined]
+    api_mock.nixl_agent_config = MagicMock  # type: ignore[attr-defined]
+    api_mock.nixl_prepped_dlist_handle = MagicMock  # type: ignore[attr-defined]
+    api_mock.nixl_xfer_handle = MagicMock  # type: ignore[attr-defined]
+    api_mock.nixlBind = nixlBind_mock  # type: ignore[attr-defined]
+    api_mock.nixl_thread_sync_t = sync_t_mock  # type: ignore[attr-defined]
+
+    nixl_mock = types.ModuleType("nixl")
+    nixl_mock._api = api_mock  # type: ignore[attr-defined]
+
+    inserted = []
+    for name, mod in (("nixl", nixl_mock), ("nixl._api", api_mock)):
+        if name not in sys.modules:
+            sys.modules[name] = mod
+            inserted.append(name)
+    return inserted
+
+
+_NIXL_MOCK_KEYS = _install_nixl_mock_if_absent()
+
+
+# First Party
+from lmcache.utils import CacheEngineKey  # noqa: E402
+from lmcache.v1.config import LMCacheEngineConfig  # noqa: E402
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (  # noqa: E402
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_management import MemoryFormat  # noqa: E402
+from lmcache.v1.metadata import LMCacheMetadata  # noqa: E402
+from lmcache.v1.storage_backend import CreateStorageBackends  # noqa: E402
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend  # noqa: E402
+import lmcache.v1.memory_management as memory_management_module  # noqa: E402
+import lmcache.v1.storage_backend.nixl_storage_backend as nixl_module  # noqa: E402
+
+# nixl_module has now captured whatever it needs from the (possibly fake) nixl
+# package. Drop the fake from sys.modules so it cannot leak into other test
+# modules' pytest.importorskip("nixl") during collection. No-op when real nixl
+# is installed (nothing was inserted).
+for _name in _NIXL_MOCK_KEYS:
+    sys.modules.pop(_name, None)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_metadata() -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+
+def _nixl_cpu_config(pool_size: int = 0) -> LMCacheEngineConfig:
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        lmcache_instance_id="test_nixl_shared",
+    )
+    # In CPU mode nixl_buffer_size is rejected by config validation; the pool
+    # is sized by max_local_cpu_size via LocalCPUBackend.
+    config.nixl_buffer_device = "cpu"
+    config.save_unfull_chunk = False
+    config.extra_config = {
+        "enable_nixl_storage": True,
+        "nixl_backend": "OBJ",
+        "nixl_pool_size": pool_size,
+        "nixl_backend_params": {},
+        "nixl_presence_cache": False,
+        "nixl_async_put": False,
+        "use_direct_io": False,
+        "nixl_path": None,
+        "nixl_enable_prog_thread": True,
+    }
+    return config
+
+
+def _nixl_gpu_config(pool_size: int = 0) -> LMCacheEngineConfig:
+    config = _nixl_cpu_config(pool_size)
+    config.nixl_buffer_device = "cuda"
+    config.nixl_buffer_size = 1024 * 1024
+    return config
+
+
+def _make_paged_allocator(metadata: LMCacheMetadata) -> PagedTensorMemoryAllocator:
+    shapes = metadata.get_shapes()
+    dtypes = metadata.get_dtypes()
+    chunk_bytes = sum(
+        s.numel() * d.itemsize for s, d in zip(shapes, dtypes, strict=True)
+    )
+    buffer = torch.zeros(chunk_bytes * 4, dtype=torch.uint8)
+    return PagedTensorMemoryAllocator(
+        buffer,
+        [torch.Size(metadata.kv_shape)],
+        [metadata.kv_dtype],
+        MemoryFormat.KV_2LTD,
+    )
+
+
+def _make_local_cpu_paged(
+    monkeypatch, metadata: LMCacheMetadata, local_cpu: bool = True
+) -> LocalCPUBackend:
+    """LocalCPUBackend with memory_allocator = MixedMemoryAllocator(use_paging=True).
+
+    Sized to exactly 4 chunks so tests that need to drive the pool to
+    saturation know the page count without inspecting allocator internals.
+    """
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256, local_cpu=local_cpu, lmcache_instance_id="test_paged"
+    )
+    shapes = metadata.get_shapes()
+    dtypes = metadata.get_dtypes()
+    chunk_bytes = sum(
+        s.numel() * d.itemsize for s, d in zip(shapes, dtypes, strict=True)
+    )
+    aligned = chunk_bytes * 4
+    config.max_local_cpu_size = aligned / (1024**3)
+    config.nixl_buffer_device = "cpu"
+    config.extra_config = {"enable_nixl_storage": True}
+    config.save_unfull_chunk = False
+    real_buf = torch.zeros(aligned, dtype=torch.uint8)
+    monkeypatch.setattr(
+        memory_management_module,
+        "_allocate_cpu_memory",
+        lambda size, *a, **kw: real_buf,
+    )
+    # real_buf is a plain (pageable) tensor, not cudaHostAlloc'd. The real
+    # _free_cpu_memory would call cudaFreeHost on it on a CUDA build and raise
+    # "cudaFreeHost failed" — so neutralize free symmetrically with alloc; the
+    # tensor is reclaimed by normal Python GC.
+    monkeypatch.setattr(
+        memory_management_module, "_free_cpu_memory", lambda *a, **kw: None
+    )
+    return LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
+
+
+def _make_local_cpu_flat(metadata: LMCacheMetadata) -> LocalCPUBackend:
+    """LocalCPUBackend memory_allocator = MixedMemoryAllocator(use_paging=False)."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256, local_cpu=True, lmcache_instance_id="test_flat"
+    )
+    config.max_local_cpu_size = 0.01
+    return LocalCPUBackend(config=config, metadata=metadata, dst_device="cpu")
+
+
+def _stub_dynamic_agent(monkeypatch) -> None:
+    monkeypatch.setattr(
+        nixl_module.NixlDynamicStorageAgent, "__init__", lambda self, *a, **kw: None
+    )
+    monkeypatch.setattr(nixl_module.NixlDynamicStorageAgent, "close", lambda self: None)
+    monkeypatch.setattr(
+        nixl_module.NixlDynamicStorageAgent, "mem_type", "OBJ", raising=False
+    )
+
+
+def _stub_static_agent(monkeypatch) -> None:
+    monkeypatch.setattr(
+        nixl_module.NixlStaticStorageAgent, "__init__", lambda self, *a, **kw: None
+    )
+    monkeypatch.setattr(nixl_module.NixlStaticStorageAgent, "close", lambda self: None)
+
+
+def _stub_gpu_allocator(monkeypatch, allocator) -> None:
+    monkeypatch.setattr(
+        nixl_module.NixlStorageBackend,
+        "initialize_allocator",
+        lambda self, config, metadata: allocator,
+    )
+
+
+def _build_dynamic(monkeypatch, metadata, config, local_cpu_backend=None):
+    _stub_dynamic_agent(monkeypatch)
+    loop = asyncio.new_event_loop()
+    nixl_config = nixl_module.NixlStorageConfig.from_cache_engine_config(
+        config, metadata
+    )
+    backend = nixl_module.NixlDynamicStorageBackend(
+        nixl_config, config, metadata, loop, local_cpu_backend=local_cpu_backend
+    )
+    return backend, loop
+
+
+def _build_static(monkeypatch, metadata, config, local_cpu_backend=None):
+    _stub_static_agent(monkeypatch)
+    loop = asyncio.new_event_loop()
+    nixl_config = nixl_module.NixlStorageConfig.from_cache_engine_config(
+        config, metadata
+    )
+    backend = nixl_module.NixlStaticStorageBackend(
+        nixl_config, config, metadata, loop, local_cpu_backend=local_cpu_backend
+    )
+    return backend, loop
+
+
+def _make_key(idx: int) -> CacheEngineKey:
+    """Unique CacheEngineKey for tests."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=idx,
+        dtype=torch.bfloat16,
+    )
+
+
+def _stub_dynamic_agent_runtime(backend) -> None:
+    """Stub the NixlDynamicStorageAgent runtime methods invoked by storage_to_mem.
+
+    The constructor was already stubbed by _stub_dynamic_agent; this fills in
+    the transport surface so storage_to_mem can run end-to-end without real NIXL.
+    """
+    backend.agent.mem_type = "OBJ"
+    backend.agent.create_batched_storage_handler = MagicMock(
+        return_value=(MagicMock(), MagicMock())
+    )
+    backend.agent.get_storage_to_mem_handle = MagicMock(return_value=MagicMock())
+    backend.agent.post_blocking = MagicMock()
+    backend.agent.release_handle = MagicMock()
+    backend.agent.release_storage_handler = MagicMock()
+
+
+# ---------------------------------------------------------------------------
+# Tests: Dynamic CPU mode
+# ---------------------------------------------------------------------------
+
+
+class TestDynamicCpuMode:
+    def test_cpu_mode_raises_without_local_cpu(self, monkeypatch):
+        """Constructor raises RuntimeError if local_cpu_backend is None in CPU mode."""
+        metadata = _make_metadata()
+        _stub_dynamic_agent(monkeypatch)
+        loop = asyncio.new_event_loop()
+        try:
+            nixl_config = nixl_module.NixlStorageConfig.from_cache_engine_config(
+                _nixl_cpu_config(), metadata
+            )
+            with pytest.raises(RuntimeError, match="max_local_cpu_size"):
+                nixl_module.NixlDynamicStorageBackend(
+                    nixl_config,
+                    _nixl_cpu_config(),
+                    metadata,
+                    loop,
+                    local_cpu_backend=None,
+                )
+        finally:
+            loop.close()
+
+    def test_cpu_mode_raises_if_wrong_allocator_type(self, monkeypatch):
+        """RuntimeError when LocalCPUBackend uses non-paged MixedMemoryAllocator."""
+        metadata = _make_metadata()
+        local_cpu_flat = _make_local_cpu_flat(metadata)
+        _stub_dynamic_agent(monkeypatch)
+        loop = asyncio.new_event_loop()
+        try:
+            nixl_config = nixl_module.NixlStorageConfig.from_cache_engine_config(
+                _nixl_cpu_config(), metadata
+            )
+            with pytest.raises(
+                RuntimeError, match="MixedMemoryAllocator\\(use_paging=True\\)"
+            ):
+                nixl_module.NixlDynamicStorageBackend(
+                    nixl_config,
+                    _nixl_cpu_config(),
+                    metadata,
+                    loop,
+                    local_cpu_backend=local_cpu_flat,
+                )
+        finally:
+            loop.close()
+
+    def test_get_allocator_backend_returns_local_cpu(self, monkeypatch):
+        """get_allocator_backend() returns local_cpu_backend in CPU mode."""
+        metadata = _make_metadata()
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata)
+        backend, loop = _build_dynamic(
+            monkeypatch, metadata, _nixl_cpu_config(), local_cpu_backend=local_cpu
+        )
+        try:
+            assert backend.get_allocator_backend() is local_cpu
+        finally:
+            loop.close()
+            local_cpu.memory_allocator.close()
+
+
+# ---------------------------------------------------------------------------
+# Tests: Dynamic GPU mode
+# ---------------------------------------------------------------------------
+
+
+class TestDynamicGpuMode:
+    def test_get_allocator_backend_returns_self(self, monkeypatch):
+        """In GPU mode, get_allocator_backend() returns self."""
+        metadata = _make_metadata()
+        fake_alloc = _make_paged_allocator(metadata)
+        _stub_gpu_allocator(monkeypatch, fake_alloc)
+        monkeypatch.setattr(torch.cuda, "current_device", lambda: 0, raising=False)
+        monkeypatch.setattr(torch.cuda, "set_device", lambda x: None, raising=False)
+
+        backend, loop = _build_dynamic(monkeypatch, metadata, _nixl_gpu_config())
+        try:
+            assert backend.get_allocator_backend() is backend
+        finally:
+            loop.close()
+            fake_alloc.close()
+
+
+# ---------------------------------------------------------------------------
+# Tests: Static CPU mode
+# ---------------------------------------------------------------------------
+
+
+class TestStaticCpuMode:
+    def test_cpu_mode_raises_if_wrong_allocator_type(self, monkeypatch):
+        """Static backend: RuntimeError when LocalCPUBackend uses flat allocator."""
+        metadata = _make_metadata()
+        local_cpu_flat = _make_local_cpu_flat(metadata)
+        _stub_static_agent(monkeypatch)
+        loop = asyncio.new_event_loop()
+        try:
+            nixl_config = nixl_module.NixlStorageConfig.from_cache_engine_config(
+                _nixl_cpu_config(pool_size=4), metadata
+            )
+            with pytest.raises(
+                RuntimeError, match="MixedMemoryAllocator\\(use_paging=True\\)"
+            ):
+                nixl_module.NixlStaticStorageBackend(
+                    nixl_config,
+                    _nixl_cpu_config(pool_size=4),
+                    metadata,
+                    loop,
+                    local_cpu_backend=local_cpu_flat,
+                )
+        finally:
+            loop.close()
+
+
+# ---------------------------------------------------------------------------
+# Tests: cross-pool ownership bug fix (red->green demonstration)
+# ---------------------------------------------------------------------------
+
+
+class TestCrossPoolOwnershipFix:
+    """Red->green test for the cross-pool ownership bug.
+
+    Pre-fix: _allocate_for_read called self.memory_allocator.allocate()
+    directly. Once NIXL-hit promotions filled LocalCPUBackend's hot cache
+    with buffers from the shared pool, allocate() returned None and
+    batched_get_blocking returned [None].
+
+    Post-fix: _allocate_for_read routes through
+    LocalCPUBackend.allocate(eviction=True), so eviction fires on the
+    shared pool and frees a page from hot_cache to satisfy the read.
+    """
+
+    def test_get_succeeds_after_pool_saturation_via_eviction(self, monkeypatch):
+        """After N promotions saturate the shared pool, the (N+1)th
+        batched_get_blocking still returns a valid MemoryObj (eviction fires
+        via the shared allocator)."""
+        metadata = _make_metadata()
+        # The fixture sizes the pool to exactly 4 chunks; drive exactly that
+        # many promotions to saturate it without peeking at allocator state.
+        num_pages = 4
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata)
+        backend, loop = _build_dynamic(
+            monkeypatch, metadata, _nixl_cpu_config(), local_cpu_backend=local_cpu
+        )
+
+        try:
+            backend.init_chunk_meta(metadata)
+            _stub_dynamic_agent_runtime(backend)
+
+            for i in range(num_pages):
+                key = _make_key(i)
+                objs = backend.batched_get_blocking([key])
+                assert objs[0] is not None, (
+                    f"batched_get_blocking returned None at promotion "
+                    f"{i}/{num_pages}; pool exhausted earlier than expected"
+                )
+                # Promote into hot_cache and drop the caller's ref so hot_cache
+                # holds the only reference to the page.
+                local_cpu.batched_submit_put_task([key], objs)
+                objs[0].ref_count_down()
+
+            # Verify the pool is saturated via the public allocator API: a
+            # no-eviction allocation must fail when every page is pinned in
+            # hot_cache.
+            shapes = metadata.get_shapes()
+            dtypes = metadata.get_dtypes()
+            sat_obj = local_cpu.allocate(
+                shapes, dtypes, MemoryFormat.KV_2LTD, eviction=False
+            )
+            assert sat_obj is None, (
+                "Test fixture: shared pool should be saturated after "
+                f"{num_pages} promotions"
+            )
+
+            # The (N+1)th read must still succeed — _allocate_for_read routes
+            # through LocalCPUBackend.allocate(eviction=True), which evicts
+            # one hot_cache entry to free a page.
+            extra_key = _make_key(num_pages)
+            objs = backend.batched_get_blocking([extra_key])
+            assert objs[0] is not None, (
+                "Shared-pool eviction did not fire: pre-fix, _allocate_for_read "
+                "called the inner allocator directly with no eviction and "
+                "returned None."
+            )
+            objs[0].ref_count_down()
+        finally:
+            loop.close()
+            local_cpu.memory_allocator.close()
+
+
+# ---------------------------------------------------------------------------
+# Tests: shared-pool contract (close ownership + staging-only mode)
+# ---------------------------------------------------------------------------
+
+
+class TestSharedPoolContract:
+    """Behavioral contracts for the CPU-mode shared pool."""
+
+    def test_close_does_not_close_borrowed_allocator(self, monkeypatch):
+        """NixlStorageBackend.close() must not close the LocalCPUBackend
+        allocator it borrowed — that allocator is owned by LocalCPUBackend."""
+        metadata = _make_metadata()
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata)
+        backend, loop = _build_dynamic(
+            monkeypatch, metadata, _nixl_cpu_config(), local_cpu_backend=local_cpu
+        )
+
+        close_calls: list[None] = []
+        original_close = local_cpu.memory_allocator.close
+
+        def spy() -> None:
+            close_calls.append(None)
+            original_close()
+
+        monkeypatch.setattr(local_cpu.memory_allocator, "close", spy)
+
+        try:
+            backend.close()
+            assert close_calls == [], (
+                "NIXL.close() must not invoke close() on the borrowed allocator"
+            )
+            # And the allocator is still usable after NIXL has shut down.
+            shapes = metadata.get_shapes()
+            dtypes = metadata.get_dtypes()
+            obj = local_cpu.allocate(shapes, dtypes, MemoryFormat.KV_2LTD)
+            assert obj is not None, (
+                "Borrowed allocator is no longer usable after NIXL close()"
+            )
+            obj.ref_count_down()
+        finally:
+            loop.close()
+            local_cpu.memory_allocator.close()
+
+    def test_local_cpu_false_does_not_promote_to_hot_cache(self, monkeypatch):
+        """With local_cpu=False the LocalCPUBackend is a NIXL staging buffer
+        only: batched_submit_put_task is a no-op, so a subsequent
+        get_blocking returns None. Documents the contract stated in the
+        NIXL docs and exercised by the CreateStorageBackends path that
+        force-creates LocalCPUBackend in CPU mode."""
+        metadata = _make_metadata()
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata, local_cpu=False)
+
+        try:
+            shapes = metadata.get_shapes()
+            dtypes = metadata.get_dtypes()
+            obj = local_cpu.allocate(shapes, dtypes, MemoryFormat.KV_2LTD)
+            assert obj is not None, "Staging-only LocalCPUBackend must still allocate"
+            key = _make_key(0)
+            local_cpu.batched_submit_put_task([key], [obj])
+            assert local_cpu.get_blocking(key) is None, (
+                "local_cpu=False must suppress hot-cache promotion"
+            )
+            obj.ref_count_down()
+        finally:
+            local_cpu.memory_allocator.close()
+
+
+class TestAllocatorMethodsRouteThroughLocalCpu:
+    """In CPU mode the AllocatorBackendInterface methods on NixlStorageBackend
+    must delegate to LocalCPUBackend's public API, not call the inner
+    allocator directly. Matches P2P's pattern (allocations via
+    local_cpu_backend.allocate, allocator only peeked for buffer info)."""
+
+    def test_allocate_routes_through_local_cpu_backend(self, monkeypatch):
+        metadata = _make_metadata()
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata)
+        backend, loop = _build_dynamic(
+            monkeypatch, metadata, _nixl_cpu_config(), local_cpu_backend=local_cpu
+        )
+
+        calls: list[dict] = []
+        original_allocate = local_cpu.allocate
+
+        def spy(shapes, dtypes, fmt=None, eviction=True, busy_loop=True):
+            calls.append(
+                {"shapes": shapes, "eviction": eviction, "busy_loop": busy_loop}
+            )
+            return original_allocate(
+                shapes, dtypes, fmt, eviction=eviction, busy_loop=busy_loop
+            )
+
+        monkeypatch.setattr(local_cpu, "allocate", spy)
+
+        try:
+            shapes = metadata.get_shapes()
+            dtypes = metadata.get_dtypes()
+            obj = backend.allocate(shapes, dtypes, MemoryFormat.KV_2LTD)
+            assert obj is not None
+            assert len(calls) == 1, (
+                "NixlStorageBackend.allocate must delegate to LocalCPUBackend"
+            )
+            assert calls[0]["busy_loop"] is False, (
+                "Delegated allocate must force busy_loop=False (NIXL semantics)"
+            )
+            obj.ref_count_down()
+        finally:
+            backend.close()
+            loop.close()
+            local_cpu.memory_allocator.close()
+
+    def test_batched_allocate_routes_through_local_cpu_backend(self, monkeypatch):
+        metadata = _make_metadata()
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata)
+        backend, loop = _build_dynamic(
+            monkeypatch, metadata, _nixl_cpu_config(), local_cpu_backend=local_cpu
+        )
+
+        calls: list[dict] = []
+        original_batched = local_cpu.batched_allocate
+
+        def spy(shapes, dtypes, batch_size, fmt=None, eviction=True, busy_loop=True):
+            calls.append({"batch_size": batch_size, "busy_loop": busy_loop})
+            return original_batched(
+                shapes,
+                dtypes,
+                batch_size,
+                fmt,
+                eviction=eviction,
+                busy_loop=busy_loop,
+            )
+
+        monkeypatch.setattr(local_cpu, "batched_allocate", spy)
+
+        try:
+            shapes = metadata.get_shapes()
+            dtypes = metadata.get_dtypes()
+            objs = backend.batched_allocate(shapes, dtypes, 2, MemoryFormat.KV_2LTD)
+            assert objs is not None
+            assert len(calls) == 1, (
+                "NixlStorageBackend.batched_allocate must delegate to LocalCPUBackend"
+            )
+            assert calls[0]["batch_size"] == 2
+            assert calls[0]["busy_loop"] is False
+            for obj in objs:
+                obj.ref_count_down()
+        finally:
+            backend.close()
+            loop.close()
+            local_cpu.memory_allocator.close()
+
+    def test_get_memory_allocator_returns_local_cpu_allocator(self, monkeypatch):
+        """storage_manager.memcheck() iterates AllocatorBackendInterface
+        backends and calls get_memory_allocator().memcheck(). In CPU mode the
+        NIXL backend shares LocalCPUBackend's pool — returning the same
+        allocator avoids double-counting the pool in memcheck."""
+        metadata = _make_metadata()
+        local_cpu = _make_local_cpu_paged(monkeypatch, metadata)
+        backend, loop = _build_dynamic(
+            monkeypatch, metadata, _nixl_cpu_config(), local_cpu_backend=local_cpu
+        )
+
+        try:
+            assert backend.get_memory_allocator() is local_cpu.get_memory_allocator()
+        finally:
+            backend.close()
+            loop.close()
+            local_cpu.memory_allocator.close()
+
+
+def _scheduler_metadata() -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+        role="scheduler",
+    )
+
+
+class TestSchedulerRoleRejection:
+    """The scheduler role never creates a LocalCPUBackend, so NIXL CPU mode —
+    which shares that backend's pool — cannot run there. CreateStorageBackends
+    rejects the combo with a clear ValueError instead of letting it crash deep
+    in the NIXL constructor. See plans/pr-nixl-cpu-shared-pool-review."""
+
+    def test_scheduler_role_nixl_cpu_rejected(self):
+        config = _nixl_cpu_config()
+        loop = asyncio.new_event_loop()
+        try:
+            with pytest.raises(ValueError, match="scheduler"):
+                CreateStorageBackends(config, _scheduler_metadata(), loop)
+        finally:
+            loop.close()
+
+    def test_scheduler_role_without_nixl_ok(self):
+        # The guard is specific to NIXL CPU mode: a scheduler with no NIXL
+        # storage must still build (no LocalCPUBackend, no rejection).
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            lmcache_instance_id="test_sched_no_nixl",
+        )
+        loop = asyncio.new_event_loop()
+        try:
+            backends = CreateStorageBackends(config, _scheduler_metadata(), loop)
+            assert "LocalCPUBackend" not in backends
+        finally:
+            loop.close()
diff --git a/tests/v1/storage_backend/test_p2p_backend_with_controller.py b/tests/v1/storage_backend/test_p2p_backend_with_controller.py
new file mode 100644
index 0000000..ba053cd
--- /dev/null
+++ b/tests/v1/storage_backend/test_p2p_backend_with_controller.py
@@ -0,0 +1,609 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+from unittest.mock import AsyncMock, MagicMock, patch
+import asyncio
+import contextlib
+import multiprocessing as mp
+import threading
+import time
+
+# Third Party
+import msgspec
+import pytest
+import torch
+import zmq
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.cache_controller.message import (
+    BatchedP2PLookupMsg,
+    BatchedP2PLookupRetMsg,
+)
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.paged_cpu_gpu_memory_allocator import (
+    PagedCpuGpuMemoryAllocator,
+)
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.p2p_backend import P2PBackend
+from lmcache.v1.transfer_channel.transfer_utils import P2PInitSideRetMsg
+from tests.v1.utils import get_available_ports
+
+logger = init_logger(__name__)
+
+
+def wait_for_keys_in_cache(
+    backend: LocalCPUBackend,
+    keys: list,
+    timeout: float = 5.0,
+    poll_interval: float = 0.1,
+) -> bool:
+    """Wait for keys to appear in the backend's cache."""
+    start_time = time.time()
+    missing_keys = keys.copy()  # Initialize with all keys
+    while time.time() - start_time < timeout:
+        missing_keys = [key for key in keys if not backend.contains(key, pin=False)]
+        if not missing_keys:
+            return True
+        time.sleep(poll_interval)
+    logger.warning(
+        f"Timeout waiting for keys: {[key.to_string() for key in missing_keys]}"
+    )
+    return False
+
+
+def wait_for_backend_ready(
+    backend: P2PBackend, timeout: float = 5.0, poll_interval: float = 0.1
+) -> bool:
+    """Wait for P2P backend to be ready for operations."""
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        # Check if backend is properly initialized by checking its attributes
+        if (
+            hasattr(backend, "tp_rank")
+            and hasattr(backend, "peer_init_url")
+            and backend.peer_init_url
+            and hasattr(backend, "peer_lookup_url")
+            and backend.peer_lookup_url
+        ):
+            return True
+        time.sleep(poll_interval)
+    logger.warning("Timeout waiting for backend to be ready")
+    return False
+
+
+class MockLMCacheWorker:
+    """Mock worker that simulates controller responses"""
+
+    def __init__(self, controller_url: str):
+        self.controller_url = controller_url
+        self.messages: list = []
+        self.context = None
+        self.socket = None
+
+    def _ensure_socket(self):
+        """Ensure socket is created and connected"""
+        if self.socket is None:
+            self.context = zmq.asyncio.Context()
+            self.socket = self.context.socket(zmq.REQ)
+            self.socket.connect(self.controller_url)
+            self.socket.setsockopt(zmq.RCVTIMEO, 5000)
+            self.socket.setsockopt(zmq.SNDTIMEO, 5000)
+
+    async def async_put_and_wait_msg(self, msg):
+        """Send message to controller and wait for response"""
+        self.messages.append(msg)
+
+        if isinstance(msg, BatchedP2PLookupMsg):
+            self._ensure_socket()
+            try:
+                await self.socket.send(msgspec.msgpack.encode(msg))
+                response_bytes = await self.socket.recv()
+                response = msgspec.msgpack.decode(
+                    response_bytes, type=BatchedP2PLookupRetMsg
+                )
+                return response
+            except zmq.Again as e:
+                logger.error("Timeout waiting for controller response: %s", e)
+                return BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+            except Exception as e:
+                logger.error("Error communicating with controller: %s", e)
+                return BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+
+        return None
+
+    def close(self):
+        """Close socket and context"""
+        if self.socket is not None:
+            self.socket.close()
+        if self.context is not None:
+            self.context.term()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+
+def run_mock_controller(
+    controller_url: str,
+    peer_mappings: dict,
+    stop_event: "mp.synchronize.Event",
+    ready_event: "mp.synchronize.Event",
+):
+    """Run a mock controller that handles P2P lookup requests"""
+    context = zmq.Context()
+    socket = context.socket(zmq.REP)
+    socket.bind(controller_url)
+    socket.setsockopt(zmq.RCVTIMEO, 1000)
+
+    logger.info(f"Mock controller started at {controller_url}")
+    ready_event.set()  # Signal that the controller is ready
+
+    while not stop_event.is_set():
+        try:
+            msg_bytes = socket.recv()
+            msg = msgspec.msgpack.decode(msg_bytes, type=BatchedP2PLookupMsg)
+
+            # Simulate lookup logic
+            response_key = (msg.instance_id, msg.worker_id, tuple(msg.hashes))
+            if response_key in peer_mappings:
+                response = peer_mappings[response_key]
+            else:
+                response = BatchedP2PLookupRetMsg(layout_info=[("", "", 0, "")])
+
+            socket.send(msgspec.msgpack.encode(response))
+        except zmq.Again:
+            continue
+        except Exception as e:
+            logger.error("Controller error: %s", e)
+            if not stop_event.is_set():
+                time.sleep(0.01)
+
+    socket.close()
+    context.term()
+    logger.info("Mock controller stopped")
+
+
+def create_test_config(
+    p2p_host: str,
+    p2p_init_ports: list[int],
+    p2p_lookup_ports: list[int],
+    transfer_channel: str = "mock_memory",
+    extra_config: Optional[dict] = None,
+):
+    """Create test configuration for P2P backend"""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=1.0,
+        p2p_host=p2p_host,
+        p2p_init_ports=p2p_init_ports,
+        p2p_lookup_ports=p2p_lookup_ports,
+        transfer_channel=transfer_channel,
+        lmcache_instance_id="test_instance",
+    )
+    if extra_config:
+        config.extra_config = extra_config
+    return config
+
+
+def create_test_metadata(worker_id: int = 0):
+    """Create test metadata"""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=2,
+        local_world_size=2,
+        worker_id=worker_id,
+        local_worker_id=worker_id,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(28, 2, 256, 8, 128),
+    )
+
+
+def create_test_key(key_id: str = "test_key") -> CacheEngineKey:
+    """Create a test CacheEngineKey"""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=2,
+        worker_id=0,
+        chunk_hash=hash(key_id),
+        dtype=torch.bfloat16,
+        request_configs=None,
+    )
+
+
+@pytest.fixture
+def async_loop():
+    """Create an asyncio event loop running in a background thread"""
+    loop = asyncio.new_event_loop()
+    ready_event = threading.Event()
+
+    def run_loop():
+        asyncio.set_event_loop(loop)
+        ready_event.set()  # Signal that the loop is ready
+        loop.run_forever()
+
+    thread = threading.Thread(target=run_loop, daemon=True)
+    thread.start()
+
+    # Wait for the thread to initialize the event loop
+    if not ready_event.wait(timeout=5.0):
+        raise RuntimeError("Event loop thread failed to initialize within 5 seconds")
+
+    yield loop
+
+    # Stop the loop first to prevent new tasks from being scheduled
+    loop.call_soon_threadsafe(loop.stop)
+    thread.join(timeout=3)
+
+    # Force terminate if thread is still alive
+    if thread.is_alive():
+        logger.warning("Event loop thread did not stop gracefully")
+
+    # Clean up remaining tasks without recursion
+    if not loop.is_closed():
+        try:
+            # Get all pending tasks
+            pending = asyncio.all_tasks(loop)
+            for task in pending:
+                if not task.done():
+                    # Cancel without waiting to avoid recursion
+                    task.cancel()
+        except Exception as e:
+            logger.warning("Error cancelling tasks: %s", e)
+
+        # Close the loop
+        try:
+            loop.close()
+        except Exception as e:
+            logger.warning("Error closing loop: %s", e)
+
+
+@contextlib.contextmanager
+def cpu_allocator():
+    """Create and cleanup CPU memory allocator"""
+    allocator = PagedCpuGpuMemoryAllocator()
+    allocator.init_cpu_memory_allocator(
+        size=1120 * 1024 * 1024,
+        shapes=[torch.Size([28, 2, 256, 8, 128])],
+        dtypes=[torch.bfloat16],
+        fmt=MemoryFormat.KV_2LTD,
+    )
+    try:
+        yield allocator
+    finally:
+        allocator.close()
+
+
+@pytest.fixture
+def local_cpu_backend():
+    """Create local CPU backend with allocator"""
+
+    def _create_backend(config):
+        allocator = PagedCpuGpuMemoryAllocator()
+        allocator.init_cpu_memory_allocator(
+            size=1120 * 1024 * 1024,
+            shapes=[torch.Size([28, 2, 256, 8, 128])],
+            dtypes=[torch.bfloat16],
+            fmt=MemoryFormat.KV_2LTD,
+        )
+        return LocalCPUBackend(config=config, memory_allocator=allocator)
+
+    return _create_backend
+
+
+@contextlib.contextmanager
+def mock_controller_context(peer_mappings: dict):
+    """Context manager for mock controller process"""
+    controller_port = get_available_ports(1)[0]
+    controller_url = f"tcp://localhost:{controller_port}"
+    stop_event = mp.Event()
+    ready_event = mp.Event()
+
+    process = mp.Process(
+        target=run_mock_controller,
+        args=(controller_url, peer_mappings, stop_event, ready_event),
+    )
+    process.start()
+
+    # Wait for the controller to signal it's ready
+    if not ready_event.wait(timeout=5.0):
+        raise RuntimeError("Mock controller failed to start within 5 seconds")
+
+    try:
+        yield controller_url
+    finally:
+        stop_event.set()
+        process.join(timeout=5)
+        if process.is_alive():
+            process.terminate()
+            process.join()
+
+
+@contextlib.contextmanager
+def p2p_backend_context(config, metadata, async_loop, local_backend, mock_worker):
+    """Context manager for P2P backend with automatic cleanup"""
+    backend = P2PBackend(
+        config=config,
+        metadata=metadata,
+        loop=async_loop,
+        local_cpu_backend=local_backend,
+        lmcache_worker=mock_worker,
+    )
+    try:
+        yield backend
+    finally:
+        try:
+            backend.close()
+        except Exception as e:
+            logger.warning("Error closing P2P backend: %s", e)
+        # Give some time for cleanup
+        time.sleep(0.1)
+
+
+class TestP2PBackendWithController:
+    """Test cases for P2P Backend with Controller"""
+
+    def test_p2p_backend_initialization(self, async_loop, local_cpu_backend):
+        """
+        Test the basic initialization of P2P backend with mock_memory transfer channel.
+
+        This test verifies that:
+        - P2P backend can be properly initialized with valid configuration
+        - All required attributes are set correctly (tp_rank, peer URLs)
+        - The backend is ready for P2P communication
+        """
+        peer_init_port, peer_lookup_port, controller_port = get_available_ports(3)
+
+        config = create_test_config(
+            p2p_host="localhost",
+            p2p_init_ports=[peer_init_port],
+            p2p_lookup_ports=[peer_lookup_port],
+        )
+        metadata = create_test_metadata(worker_id=0)
+        local_backend = local_cpu_backend(config)
+        controller_url = f"tcp://localhost:{controller_port}"
+
+        with (
+            MockLMCacheWorker(controller_url) as mock_worker,
+            p2p_backend_context(
+                config, metadata, async_loop, local_backend, mock_worker
+            ) as p2p_backend,
+        ):
+            assert p2p_backend is not None
+            assert p2p_backend.tp_rank == 0
+            assert p2p_backend.peer_init_url == f"localhost:{peer_init_port}"
+            assert p2p_backend.peer_lookup_url == f"localhost:{peer_lookup_port}"
+
+    @pytest.mark.skip(reason="Complex P2P communication test that may hang in CI/CD")
+    def test_p2p_backend_normal_flow(self, async_loop):
+        """
+        Test the complete P2P data retrieval flow between two peers
+        with controller coordination.
+
+        This test verifies:
+        - Two P2P backends can communicate through the controller
+        - Data can be put into one peer and retrieved from another
+        - Batched contains and get operations work correctly
+        - The controller properly routes lookup requests
+        """
+        peer1_init_port, peer1_lookup_port, peer2_init_port, peer2_lookup_port = (
+            get_available_ports(4)
+        )
+
+        config1 = create_test_config(
+            p2p_host="localhost",
+            p2p_init_ports=[peer1_init_port, peer2_init_port],
+            p2p_lookup_ports=[peer1_lookup_port, peer2_lookup_port],
+        )
+        config2 = create_test_config(
+            p2p_host="localhost",
+            p2p_init_ports=[peer1_init_port, peer2_init_port],
+            p2p_lookup_ports=[peer1_lookup_port, peer2_lookup_port],
+        )
+
+        metadata1 = create_test_metadata(worker_id=0)
+        metadata2 = create_test_metadata(worker_id=1)
+
+        test_keys = [create_test_key(f"key_{i}") for i in range(2)]
+        test_hashes = tuple([key.chunk_hash for key in test_keys])
+        peer2_init_url = f"localhost:{peer2_init_port}"
+
+        peer_mappings = {
+            ("test_instance", 0, test_hashes): BatchedP2PLookupRetMsg(
+                layout_info=[("test_instance", "cpu", 2, peer2_init_url)]
+            )
+        }
+
+        with cpu_allocator() as allocator1, cpu_allocator() as allocator2:
+            local_backend1 = LocalCPUBackend(
+                config=config1, memory_allocator=allocator1
+            )
+            local_backend2 = LocalCPUBackend(
+                config=config2, memory_allocator=allocator2
+            )
+
+            with mock_controller_context(peer_mappings) as controller_url:
+                with (
+                    MockLMCacheWorker(controller_url) as mock_worker1,
+                    MockLMCacheWorker(controller_url) as mock_worker2,
+                ):
+                    with (
+                        p2p_backend_context(
+                            config1, metadata1, async_loop, local_backend1, mock_worker1
+                        ) as p2p_backend1,
+                        p2p_backend_context(
+                            config2, metadata2, async_loop, local_backend2, mock_worker2
+                        ) as _p2p_backend2,
+                    ):
+                        # Wait for backends to be ready instead of using fixed sleep
+                        assert wait_for_backend_ready(p2p_backend1), (
+                            "P2P backend 1 failed to initialize"
+                        )
+
+                        # Prepare test data on Peer2
+                        test_objs = []
+                        for key in test_keys:
+                            mem_obj = local_backend2.allocate(
+                                torch.Size([28, 2, 256, 8, 128]),
+                                torch.bfloat16,
+                                MemoryFormat.KV_2LTD,
+                            )
+                            if mem_obj.tensor is not None:
+                                mem_obj.tensor.fill_(float(hash(key.to_string()) % 100))
+                            test_objs.append(mem_obj)
+
+                        for key, obj in zip(test_keys, test_objs, strict=True):
+                            local_backend2.submit_put_task(key, obj)
+
+                        # Wait for keys to be stored in cache
+                        assert wait_for_keys_in_cache(local_backend2, test_keys), (
+                            "Keys not stored in cache"
+                        )
+
+                        # Test P2P get
+                        async def test_get():
+                            num_hits = await p2p_backend1.batched_async_contains(
+                                lookup_id="test_lookup_1", keys=test_keys, pin=False
+                            )
+                            assert num_hits == 2, f"Expected 2 hits, got {num_hits}"
+
+                            cum_chunk_lengths = [0, 256, 512]
+                            retrieved_objs = (
+                                await p2p_backend1.batched_get_non_blocking(
+                                    lookup_id="test_lookup_1",
+                                    keys=test_keys,
+                                    transfer_spec={
+                                        "cum_chunk_lengths": cum_chunk_lengths
+                                    },
+                                )
+                            )
+
+                            assert len(retrieved_objs) == 2, (
+                                f"Expected 2 objects, got {len(retrieved_objs)}"
+                            )
+                            for retrieved_obj in retrieved_objs:
+                                assert retrieved_obj.tensor is not None, (
+                                    "Retrieved tensor should not be None"
+                                )
+
+                            logger.info("P2P normal flow test passed")
+
+                        try:
+                            asyncio.run_coroutine_threadsafe(
+                                test_get(), async_loop
+                            ).result(timeout=10)
+                        except Exception as e:
+                            logger.error("Test failed: %s", e)
+                            raise
+
+    def test_p2p_backend_no_hits(self, async_loop):
+        """
+        Test P2P backend behavior when the controller returns no matching data.
+
+        This test verifies:
+        - The backend correctly handles empty lookup results
+        - No false positives are reported
+        - The system doesn't crash on empty responses
+        - Proper error handling for missing data
+        """
+        peer_init_port, peer_lookup_port = get_available_ports(2)
+
+        config = create_test_config(
+            p2p_host="localhost",
+            p2p_init_ports=[peer_init_port],
+            p2p_lookup_ports=[peer_lookup_port],
+        )
+        metadata = create_test_metadata(worker_id=0)
+        peer_mappings = {}
+
+        with cpu_allocator() as allocator:
+            local_backend = LocalCPUBackend(config=config, memory_allocator=allocator)
+
+            with mock_controller_context(peer_mappings) as controller_url:
+                with MockLMCacheWorker(controller_url) as mock_worker:
+                    with p2p_backend_context(
+                        config, metadata, async_loop, local_backend, mock_worker
+                    ) as p2p_backend:
+                        # Wait for backend to be ready instead of using fixed sleep
+                        assert wait_for_backend_ready(p2p_backend), (
+                            "P2P backend failed to initialize"
+                        )
+
+                        test_keys = [create_test_key("key_1")]
+
+                        async def test_no_hits():
+                            num_hits = await p2p_backend.batched_async_contains(
+                                lookup_id="test_lookup_no_hits",
+                                keys=test_keys,
+                                pin=False,
+                            )
+                            assert num_hits == 0, f"Expected 0 hits, got {num_hits}"
+
+                        asyncio.run_coroutine_threadsafe(
+                            test_no_hits(), async_loop
+                        ).result(timeout=5)
+
+    def test_ensure_peer_connection_race_condition(self, async_loop):
+        peer_init_port, peer_lookup_port = get_available_ports(2)
+
+        config = create_test_config(
+            p2p_host="localhost",
+            p2p_init_ports=[peer_init_port],
+            p2p_lookup_ports=[peer_lookup_port],
+        )
+        metadata = create_test_metadata(worker_id=0)
+        peer_mappings = {}
+
+        with cpu_allocator() as allocator:
+            local_backend = LocalCPUBackend(config=config, memory_allocator=allocator)
+
+            with mock_controller_context(peer_mappings) as controller_url:
+                with MockLMCacheWorker(controller_url) as mock_worker:
+                    with patch(
+                        "lmcache.v1.rpc_utils.get_zmq_socket_with_timeout"
+                    ) as mock_get_socket:
+                        mock_get_socket.return_value = MagicMock()
+
+                        with p2p_backend_context(
+                            config, metadata, async_loop, local_backend, mock_worker
+                        ) as p2p_backend:
+
+                            async def async_lazy_init_peer_connection(*args, **kwargs):
+                                logger.info("async_lazy_init_peer_connection called")
+                                await asyncio.sleep(0.5)
+                                return P2PInitSideRetMsg(
+                                    peer_lookup_url="127.0.0.1:19998"
+                                )
+
+                            p2p_backend.transfer_channel.async_lazy_init_peer_connection = AsyncMock(  # noqa: E501
+                                side_effect=async_lazy_init_peer_connection
+                            )
+
+                            # by mock_get_socket, the port is not used in the test
+                            target_peer_init_url = "127.0.0.1:19999"
+                            future_1 = asyncio.run_coroutine_threadsafe(
+                                p2p_backend._ensure_peer_connection(
+                                    target_peer_init_url
+                                ),
+                                async_loop,
+                            )
+                            future_2 = asyncio.run_coroutine_threadsafe(
+                                p2p_backend._ensure_peer_connection(
+                                    target_peer_init_url
+                                ),
+                                async_loop,
+                            )
+                            future_1.result(timeout=5)
+                            future_2.result(timeout=5)
+
+                            assert (
+                                p2p_backend.transfer_channel.async_lazy_init_peer_connection.call_count
+                                == 1
+                            )
diff --git a/tests/v1/storage_backend/test_path_sharder.py b/tests/v1/storage_backend/test_path_sharder.py
new file mode 100644
index 0000000..70da606
--- /dev/null
+++ b/tests/v1/storage_backend/test_path_sharder.py
@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for :mod:`lmcache.v1.storage_backend.path_sharder`."""
+
+# Standard
+from unittest.mock import patch
+import os
+import shutil
+import tempfile
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.storage_backend.path_sharder import PathSharder
+
+
+class TestPathSharder:
+    """Tests for PathSharder class."""
+
+    def test_single_path(self):
+        d = tempfile.mkdtemp()
+        try:
+            s = PathSharder(d, strategy="by_gpu", dst_device="cuda:0")
+            assert s.selected == d
+            assert s.all_paths == [d]
+            assert s.strategy == "by_gpu"
+        finally:
+            shutil.rmtree(d, ignore_errors=True)
+
+    def test_multi_path_selects_by_device_id(self):
+        dirs = [tempfile.mkdtemp() for _ in range(3)]
+        try:
+            csv = ",".join(dirs)
+            for i, d in enumerate(dirs):
+                s = PathSharder(csv, strategy="by_gpu", dst_device=f"cuda:{i}")
+                assert s.selected == d
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    def test_modulo_wraps(self):
+        dirs = [tempfile.mkdtemp() for _ in range(2)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cuda:4")
+            # 4 % 2 == 0
+            assert s.selected == dirs[0]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    def test_create_dirs(self):
+        base = tempfile.mkdtemp()
+        try:
+            paths = [os.path.join(base, f"nvme{i}") for i in range(3)]
+            csv = ",".join(paths)
+            PathSharder(csv, strategy="by_gpu", dst_device="cuda:0", create_dirs=True)
+            for p in paths:
+                assert os.path.isdir(p)
+        finally:
+            shutil.rmtree(base, ignore_errors=True)
+
+    def test_no_create_dirs_by_default(self):
+        base = tempfile.mkdtemp()
+        try:
+            new_dir = os.path.join(base, "should_not_exist")
+            PathSharder(new_dir, strategy="by_gpu", dst_device="cuda:0")
+            assert not os.path.exists(new_dir)
+        finally:
+            shutil.rmtree(base, ignore_errors=True)
+
+    def test_empty_csv_raises(self):
+        with pytest.raises(ValueError, match="At least one path"):
+            PathSharder("", strategy="by_gpu", dst_device="cuda:0")
+
+    def test_whitespace_only_raises(self):
+        with pytest.raises(ValueError, match="At least one path"):
+            PathSharder("  , ,  ", strategy="by_gpu", dst_device="cuda:0")
+
+    def test_unsupported_strategy_raises(self):
+        d = tempfile.mkdtemp()
+        try:
+            with pytest.raises(ValueError, match="Unsupported path sharding"):
+                PathSharder(d, strategy="round_robin", dst_device="cuda:0")
+        finally:
+            shutil.rmtree(d, ignore_errors=True)
+
+    def test_strips_whitespace(self):
+        dirs = [tempfile.mkdtemp() for _ in range(2)]
+        try:
+            csv = f"  {dirs[0]}  ,  {dirs[1]}  "
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cuda:0")
+            assert s.all_paths == dirs
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.is_available",
+        return_value=False,
+    )
+    def test_cpu_device_selects_first_path(self, _avail):
+        dirs = [tempfile.mkdtemp() for _ in range(2)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cpu")
+            assert s.selected == dirs[0]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    def test_all_paths_returns_copy(self):
+        d = tempfile.mkdtemp()
+        try:
+            s = PathSharder(d, strategy="by_gpu", dst_device="cuda:0")
+            paths = s.all_paths
+            paths.append("/rogue")
+            assert "/rogue" not in s.all_paths
+        finally:
+            shutil.rmtree(d, ignore_errors=True)
+
+    # -- device-resolution edge cases (exercised via public API) -----------
+
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.is_available",
+        return_value=True,
+    )
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.current_device",
+        return_value=1,
+    )
+    def test_bare_cuda_uses_current_device(self, _cur, _avail):
+        """Bare 'cuda' resolves to torch_dev.current_device()."""
+        dirs = [tempfile.mkdtemp() for _ in range(3)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cuda")
+            assert s.selected == dirs[1]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.is_available",
+        return_value=False,
+    )
+    def test_bare_cuda_no_gpu_selects_first(self, _avail):
+        """Bare 'cuda' with no GPU falls back to device 0."""
+        dirs = [tempfile.mkdtemp() for _ in range(3)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cuda")
+            assert s.selected == dirs[0]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.is_available",
+        return_value=True,
+    )
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.current_device",
+        return_value=2,
+    )
+    def test_cpu_device_always_selects_first(self, _cur, _avail):
+        """'cpu' always resolves to index 0, even when CUDA is available."""
+        dirs = [tempfile.mkdtemp() for _ in range(3)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cpu")
+            assert s.selected == dirs[0]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.is_available",
+        return_value=True,
+    )
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.current_device",
+        return_value=2,
+    )
+    def test_malformed_device_empty_index_falls_back(self, _cur, _avail):
+        """'cuda:' (no int) falls back to current_device."""
+        dirs = [tempfile.mkdtemp() for _ in range(3)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cuda:")
+            assert s.selected == dirs[2]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
+
+    @patch(
+        "lmcache.v1.storage_backend.path_sharder.torch_dev.is_available",
+        return_value=False,
+    )
+    def test_malformed_device_non_numeric_falls_back(self, _avail):
+        """'cuda:foo' falls back to 0 when CUDA is unavailable."""
+        dirs = [tempfile.mkdtemp() for _ in range(3)]
+        try:
+            csv = ",".join(dirs)
+            s = PathSharder(csv, strategy="by_gpu", dst_device="cuda:foo")
+            assert s.selected == dirs[0]
+        finally:
+            for d in dirs:
+                shutil.rmtree(d, ignore_errors=True)
diff --git a/tests/v1/storage_backend/test_pd_backend_async.py b/tests/v1/storage_backend/test_pd_backend_async.py
new file mode 100644
index 0000000..9e7268d
--- /dev/null
+++ b/tests/v1/storage_backend/test_pd_backend_async.py
@@ -0,0 +1,1297 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for PDBackendAsync (async PD sender/receiver).
+
+No NIXL, CUDA, or real ZMQ peers required — all I/O is mocked with
+asyncio.sleep stubs so tests run fast (< 1 s total) in CI.  Assertions
+focus on timing and call ordering; data integrity is covered separately
+by the NIXL integration tests.
+"""
+
+# Standard
+from contextlib import contextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+import asyncio
+import itertools
+import threading
+import time
+
+# Third Party
+import msgspec
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.memory_management import MemoryFormat, MemoryObj
+from lmcache.v1.storage_backend.pd_backend import AllocRequest as SyncAllocRequest
+from lmcache.v1.storage_backend.pd_backend import AllocResponse as SyncAllocResponse
+from lmcache.v1.storage_backend.pd_backend import PDMsg as SyncPDMsg
+from lmcache.v1.storage_backend.pd_backend_async import (
+    AllocRequest as AsyncAllocRequest,
+)
+from lmcache.v1.storage_backend.pd_backend_async import (
+    AllocResponse as AsyncAllocResponse,
+)
+from lmcache.v1.storage_backend.pd_backend_async import (
+    CancelNotif,
+    PDBackendAsync,
+)
+from lmcache.v1.storage_backend.pd_backend_async import PDMsg as AsyncPDMsg
+from lmcache.v1.storage_backend.pd_backend_async import (
+    ProxyNotif,
+)
+
+TRANSFER_DELAY = 0.15
+NONBLOCKING_THRESHOLD_RATIO = 0.25
+CI_SERIAL_TIMEOUT_MARGIN = 3
+_DEFAULT_SHAPE = [4, 2, 16, 8, 128]
+
+
+def _make_key(i: int) -> CacheEngineKey:
+    return CacheEngineKey(
+        model_name="test",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=i,
+        dtype=torch.bfloat16,
+    )
+
+
+def _make_mem_obj(idx: int = 0) -> MemoryObj:
+    obj = MagicMock(spec=MemoryObj)
+    obj.meta = SimpleNamespace(
+        address=idx,
+        fmt=MemoryFormat.KV_2LTD,
+        shape=torch.Size(_DEFAULT_SHAPE),
+        dtype=torch.bfloat16,
+    )
+    obj._ref_count = 1
+
+    def _ref_up():
+        obj._ref_count += 1
+
+    def _ref_down():
+        obj._ref_count -= 1
+
+    def _get_ref_count():
+        return obj._ref_count
+
+    obj.ref_count_up.side_effect = _ref_up
+    obj.ref_count_down.side_effect = _ref_down
+    obj.get_ref_count.side_effect = _get_ref_count
+    return obj
+
+
+def _make_transfer_spec(
+    receiver_host="127.0.0.1",
+    init_port=9100,
+    alloc_port=9101,
+    req_id="req-0",
+    is_last_prefill=True,
+    num_transferred_tokens=0,
+    total_chunks=0,
+):
+    return SimpleNamespace(
+        receiver_host=receiver_host,
+        receiver_init_port=[init_port],
+        receiver_alloc_port=[alloc_port],
+        req_id=req_id,
+        is_last_prefill=is_last_prefill,
+        num_transferred_tokens=num_transferred_tokens,
+        total_chunks=total_chunks,
+    )
+
+
+def _make_alloc_req(
+    keys,
+    last_chunk_toks=16,
+    req_id="",
+    is_last_batch=False,
+    shape=None,
+    total_chunks=0,
+):
+    return AsyncAllocRequest(
+        keys=[k.to_string() for k in keys],
+        fmt=MemoryFormat.KV_2LTD.value,
+        shape=list(shape or _DEFAULT_SHAPE),
+        dtype="bfloat16",
+        last_chunk_toks=last_chunk_toks,
+        req_id=req_id,
+        is_last_batch=is_last_batch,
+        total_chunks=total_chunks,
+    )
+
+
+def _auto_alloc():
+    """Allocator that returns a fresh MemoryObj stub on every call."""
+    c = itertools.count()
+
+    def alloc(shapes, dtype, fmt=MemoryFormat.KV_2LTD, **kw):
+        return _make_mem_obj(idx=next(c))
+
+    return alloc
+
+
+def _pd_backend_patches():
+    return (
+        patch(
+            "lmcache.v1.storage_backend.pd_backend_async.get_zmq_context",
+            return_value=MagicMock(),
+        ),
+        patch(
+            "lmcache.v1.storage_backend.pd_backend_async.CreateTransferChannel",
+            return_value=MagicMock(),
+        ),
+        patch(
+            "lmcache.v1.storage_backend.pd_backend_async.get_correct_device",
+            return_value="cpu",
+        ),
+    )
+
+
+@contextmanager
+def _patched_pd():
+    p1, p2, p3 = _pd_backend_patches()
+    with p1, p2, p3:
+        yield
+
+
+# ── fixtures ──────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def async_sender():
+    p1, p2, p3 = _pd_backend_patches()
+
+    with p1, p2 as mock_create_tc, p3:
+        alloc_socket = MagicMock()
+        alloc_response = AsyncAllocResponse(remote_indexes=[0])
+        alloc_socket.recv_multipart = AsyncMock(
+            return_value=[b"", msgspec.msgpack.encode(alloc_response)]
+        )
+        alloc_socket.send_multipart = AsyncMock()
+
+        tc = MagicMock()
+
+        async def _slow_write(*a, **kw):
+            await asyncio.sleep(TRANSFER_DELAY)
+            return 1
+
+        tc.async_batched_write = _slow_write
+        mock_create_tc.return_value = tc
+
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+        from lmcache.v1.metadata import LMCacheMetadata
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=16,
+            pd_role="sender",
+            pd_proxy_host="127.0.0.1",
+            pd_proxy_port=5555,
+            pd_buffer_size=64 * 1024 * 1024,
+            pd_buffer_device="cpu",
+        )
+        metadata = LMCacheMetadata(
+            model_name="test",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 16, 8, 128),
+        )
+        backend = PDBackendAsync(config, metadata)
+        # Override async proxy socket with a mock so tests don't need a real ZMQ
+        # connection.  _init_sender() already ran on the sender loop; we replace
+        # the socket here before any tests send ProxyNotifs.
+        backend._async_proxy_socket = AsyncMock()
+
+        receiver_id = "127.0.0.1" + str(9100)
+        backend.initialized_peers.add(receiver_id)
+        backend._async_alloc_sockets[receiver_id] = alloc_socket
+
+        yield backend
+        backend.close()
+
+
+@pytest.fixture
+def async_receiver():
+    p1, p2, p3 = _pd_backend_patches()
+
+    with p1, p2, p3:
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+        from lmcache.v1.metadata import LMCacheMetadata
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=16,
+            pd_role="receiver",
+            pd_peer_host="127.0.0.1",
+            pd_peer_init_port=[9200],
+            pd_peer_alloc_port=[9201],
+            pd_buffer_size=64 * 1024 * 1024,
+            pd_buffer_device="cpu",
+        )
+        metadata = LMCacheMetadata(
+            model_name="test",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 16, 8, 128),
+        )
+        backend = PDBackendAsync(config, metadata)
+        yield backend
+        for mem_obj in backend.data.values():
+            try:
+                mem_obj.ref_count_down()
+            except Exception:
+                pass
+        backend.close()
+
+
+# ── sender tests ──────────────────────────────────────────────────────────
+
+
+def test_sender_nonblocking_fifo_transfers(async_sender):
+    """batched_submit_put_task returns immediately; all requests complete."""
+    N = 4
+    done_events = [threading.Event() for _ in range(N)]
+
+    def make_cb(i):
+        def cb(key):
+            done_events[i].set()
+
+        return cb
+
+    t0 = time.monotonic()
+    for i in range(N):
+        async_sender.batched_submit_put_task(
+            [_make_key(i)],
+            [_make_mem_obj(i)],
+            transfer_spec=_make_transfer_spec(req_id=f"req-{i}"),
+            on_complete_callback=make_cb(i),
+        )
+    enqueue_elapsed = time.monotonic() - t0
+
+    assert enqueue_elapsed < TRANSFER_DELAY * NONBLOCKING_THRESHOLD_RATIO
+
+    timeout = TRANSFER_DELAY * N * CI_SERIAL_TIMEOUT_MARGIN
+    for i, ev in enumerate(done_events):
+        assert ev.wait(timeout=timeout), f"req-{i} did not complete"
+
+
+def test_sender_flow_control_backpressure(async_sender):
+    """allocate() blocks when staging buffer is physically full, unblocks on notify."""
+    sentinel = _make_mem_obj(idx=77)
+    should_block = [True]
+
+    def alloc_fn(*args, **kw):
+        if should_block[0]:
+            return None
+        return sentinel
+
+    async_sender.memory_allocator.allocate = alloc_fn
+
+    result = []
+    blocked = threading.Event()
+    unblocked = threading.Event()
+
+    def worker():
+        blocked.set()
+        result.append(async_sender.allocate(torch.Size(_DEFAULT_SHAPE), torch.bfloat16))
+        unblocked.set()
+
+    t = threading.Thread(target=worker, daemon=True)
+    t.start()
+    assert blocked.wait(timeout=2.0)
+    time.sleep(0.1)
+    assert not unblocked.is_set(), "allocate() should be blocked"
+
+    # Make allocator return sentinel and wake the condition.
+    should_block[0] = False
+    async_sender._notify_staging_freed()
+    assert unblocked.wait(timeout=2.0)
+    assert result[0] is sentinel
+    t.join(timeout=1.0)
+
+
+def test_sender_chunk_ordering(async_sender):
+    """Last prefill chunk waits for prior slow chunk before sending ProxyNotif."""
+    SLOW, FAST = 0.30, 0.05
+    REQ_ID = "req-chunked"
+
+    # total_chunks=2 is passed via transfer_spec so the sender loop initializes
+    # per-request tracking internally (try_admit is not called from test code
+    # because it belongs to the sender loop, not caller threads).
+
+    call_count = 0
+    call_lock = threading.Lock()
+
+    async def controlled_write(*a, **kw):
+        nonlocal call_count
+        with call_lock:
+            call_count += 1
+            idx = call_count
+        await asyncio.sleep(SLOW if idx == 1 else FAST)
+        return 1
+
+    async_sender.transfer_channel.async_batched_write = controlled_write
+
+    notify_times = []
+    sent_data = []
+
+    async def record_send(data):
+        notify_times.append(time.monotonic())
+        sent_data.append(data)
+
+    async_sender._async_proxy_socket.send = record_send
+
+    async_sender.batched_submit_put_task(
+        [_make_key(0)],
+        [_make_mem_obj(0)],
+        transfer_spec=_make_transfer_spec(
+            req_id=REQ_ID, is_last_prefill=False, total_chunks=2
+        ),
+    )
+    time.sleep(0.01)
+
+    done = threading.Event()
+    async_sender.batched_submit_put_task(
+        [_make_key(1)],
+        [_make_mem_obj(1)],
+        transfer_spec=_make_transfer_spec(
+            req_id=REQ_ID, is_last_prefill=True, total_chunks=2
+        ),
+        on_complete_callback=lambda k: done.set(),
+    )
+    t_submit = time.monotonic()
+
+    assert done.wait(timeout=SLOW * 3)
+
+    # Wait for ProxyNotif to be sent (fires after the slow batch 1 completes).
+    timeout_end = time.monotonic() + SLOW * 2
+    while not notify_times and time.monotonic() < timeout_end:
+        time.sleep(0.01)
+
+    assert len(notify_times) == 1
+
+    notif = msgspec.msgpack.decode(sent_data[0], type=AsyncPDMsg)
+    assert isinstance(notif, ProxyNotif) and notif.req_id == REQ_ID
+
+    elapsed = notify_times[0] - t_submit
+    assert elapsed >= SLOW * 0.8, (
+        f"ProxyNotif too early ({elapsed:.3f}s) — fast chunk didn't wait for slow"
+    )
+
+
+def test_sender_per_receiver_concurrency(async_sender):
+    """Different-receiver requests run concurrently."""
+    SLOW, FAST = 0.25, 0.05
+
+    recv1_id = "127.0.0.1" + str(9100)
+    recv2_id = "127.0.0.1" + str(9200)
+
+    sock2 = MagicMock()
+    sock2.recv_multipart = AsyncMock(
+        return_value=[
+            b"",
+            msgspec.msgpack.encode(AsyncAllocResponse(remote_indexes=[0])),
+        ]
+    )
+    sock2.send_multipart = AsyncMock()
+    async_sender.initialized_peers.add(recv2_id)
+    async_sender._async_alloc_sockets[recv2_id] = sock2
+
+    delays = {recv1_id: SLOW, recv2_id: FAST}
+    orig_transfer = async_sender._async_transfer_task
+
+    async def patched_transfer(**kw):
+        rid = kw.get("receiver_id", "")
+        await asyncio.sleep(delays.get(rid, FAST))
+        cb = kw.get("on_complete_callback")
+        for key in kw.get("keys", []):
+            if cb:
+                try:
+                    cb(key)
+                except Exception:
+                    pass
+        async_sender._notify_staging_freed()
+
+    async_sender._async_transfer_task = patched_transfer
+
+    events = {"A": threading.Event(), "B": threading.Event(), "C": threading.Event()}
+    times = {}
+    lock = threading.Lock()
+
+    def cb(name):
+        def f(key):
+            with lock:
+                times[name] = time.monotonic()
+            events[name].set()
+
+        return f
+
+    async_sender.batched_submit_put_task(
+        [_make_key(10)],
+        [_make_mem_obj(10)],
+        transfer_spec=_make_transfer_spec(
+            init_port=9100, alloc_port=9101, req_id="A", is_last_prefill=True
+        ),
+        on_complete_callback=cb("A"),
+    )
+    async_sender.batched_submit_put_task(
+        [_make_key(20)],
+        [_make_mem_obj(20)],
+        transfer_spec=_make_transfer_spec(
+            init_port=9200, alloc_port=9201, req_id="B", is_last_prefill=True
+        ),
+        on_complete_callback=cb("B"),
+    )
+    async_sender.batched_submit_put_task(
+        [_make_key(30)],
+        [_make_mem_obj(30)],
+        transfer_spec=_make_transfer_spec(
+            init_port=9100, alloc_port=9101, req_id="C", is_last_prefill=True
+        ),
+        on_complete_callback=cb("C"),
+    )
+
+    for name, ev in events.items():
+        assert ev.wait(timeout=SLOW * 6), f"{name} timed out"
+
+    assert times["B"] < times["A"], "B (fast recv2) should finish before A (slow recv1)"
+
+    async_sender._async_transfer_task = orig_transfer
+
+
+# ── receiver tests ────────────────────────────────────────────────────────
+
+
+def test_receiver_nonblocking_async_sleep(async_receiver):
+    """Busy-wait retries yield via asyncio.sleep, not time.sleep."""
+    RETRY_COUNT = 5
+    TOKS_A, TOKS_B = 16, 8
+
+    key_a, key_b = _make_key(100), _make_key(200)
+    obj_a, obj_b = _make_mem_obj(idx=10), _make_mem_obj(idx=20)
+
+    finish_order = []
+    orig_put = async_receiver.put
+
+    def tracked_put(key, mem_obj):
+        if key == key_a:
+            finish_order.append("a")
+        elif key == key_b:
+            finish_order.append("b")
+        return orig_put(key, mem_obj)
+
+    async_receiver.put = tracked_put
+
+    calls = {}
+
+    def patched_alloc(shapes, dtype, fmt=MemoryFormat.KV_2LTD, **kw):
+        tok_dim = MemoryFormat.KV_2LTD.token_dim()
+        toks = shapes[tok_dim] if isinstance(shapes, torch.Size) else shapes[tok_dim]
+        calls[toks] = calls.get(toks, 0) + 1
+        if toks == TOKS_A and calls[toks] <= RETRY_COUNT:
+            return None
+        return obj_a if toks == TOKS_A else obj_b
+
+    async_receiver.allocate = patched_alloc
+
+    req_a = _make_alloc_req(
+        [key_a], last_chunk_toks=TOKS_A, shape=[4, 2, TOKS_A, 8, 128]
+    )
+    req_b = _make_alloc_req(
+        [key_b], last_chunk_toks=TOKS_B, shape=[4, 2, TOKS_B, 8, 128]
+    )
+
+    async def _run():
+        await asyncio.gather(
+            async_receiver._async_allocate_and_put(req_a),
+            async_receiver._async_allocate_and_put(req_b),
+        )
+
+    asyncio.run(_run())
+
+    assert finish_order == ["b", "a"], (
+        f"Got {finish_order}, busy-wait likely uses time.sleep instead of asyncio.sleep"
+    )
+
+
+def test_receiver_flow_control_inflight(async_receiver):
+    """Allocation blocks when memory is full, unblocks when remove() frees a chunk."""
+    mem_obj = _make_mem_obj(idx=60)
+    freed = [False]  # Controls when allocate succeeds
+
+    def patched_alloc(shapes, dtype, fmt=MemoryFormat.KV_2LTD, **kw):
+        return mem_obj if freed[0] else None
+
+    async_receiver.allocate = patched_alloc
+
+    alloc_req = _make_alloc_req([_make_key(600)])
+
+    # Wait longer than several poll intervals so condition-timeout retries
+    # still return None (freed[0] is still False).
+    block_duration = async_receiver._condition_poll_interval * 5
+
+    async def run():
+        completed = asyncio.Event()
+        holder = []
+
+        async def do_alloc():
+            holder.append(await async_receiver._async_allocate_and_put(alloc_req))
+            completed.set()
+
+        async def free_later():
+            await asyncio.sleep(block_duration)
+            assert not completed.is_set(), "should still be blocked"
+            freed[0] = True
+            # Notify the alloc freed condition to wake the blocked coroutine.
+            async with async_receiver._alloc_freed_condition:
+                async_receiver._alloc_freed_condition.notify_all()
+
+        await asyncio.gather(do_alloc(), free_later())
+        assert holder[0].remote_indexes == [mem_obj.meta.address]
+
+    asyncio.run(run())
+
+
+def test_receiver_last_chunk_shape_override(async_receiver):
+    """Last chunk's token dim is overridden to last_chunk_toks."""
+    mem_obj = _make_mem_obj(idx=30)
+    LAST_TOKS = 7
+
+    shapes_seen = []
+
+    def tracking_alloc(shapes, dtype, fmt=MemoryFormat.KV_2LTD, **kw):
+        shapes_seen.append(shapes)
+        return mem_obj
+
+    async_receiver.allocate = tracking_alloc
+
+    keys = [_make_key(300), _make_key(301), _make_key(302)]
+    asyncio.run(
+        async_receiver._async_allocate_and_put(
+            _make_alloc_req(keys, last_chunk_toks=LAST_TOKS)
+        )
+    )
+
+    assert len(shapes_seen) == 3
+    tok_dim = MemoryFormat.KV_2LTD.token_dim()
+    assert shapes_seen[-1][tok_dim] == LAST_TOKS
+
+
+@pytest.mark.parametrize(
+    "total_declared, b1_n, b2_n",
+    [(5, 5, 1), (4, 3, 2)],
+    ids=["exact-then-overflow", "partial-then-overflow"],
+)
+def test_receiver_fail_fast_overflow(async_receiver, total_declared, b1_n, b2_n):
+    """
+    Cumulative chunks > declared total_chunks → RuntimeError;
+    all keys rolled back.
+    """
+    async_receiver.allocate = _auto_alloc()
+    req_id = "req-failfast"
+
+    b1_keys = [_make_key(i) for i in range(b1_n)]
+
+    async def run():
+        r1 = await async_receiver._async_allocate_and_put(
+            _make_alloc_req(b1_keys, req_id=req_id, total_chunks=total_declared)
+        )
+        assert -1 not in r1.remote_indexes and len(r1.remote_indexes) == b1_n
+
+        with pytest.raises(RuntimeError, match="total_chunks"):
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(5000 + i) for i in range(b2_n)],
+                    req_id=req_id,
+                    total_chunks=total_declared,
+                )
+            )
+
+    asyncio.run(run())
+
+    # Fail-fast path rolls back prior batch keys too.
+    for k in b1_keys:
+        assert not async_receiver.contains(k, pin=False)
+
+    # unrelated req_id should work fine
+    async def check_other():
+        r = await async_receiver._async_allocate_and_put(
+            _make_alloc_req([_make_key(20000)], req_id="req-other", total_chunks=1)
+        )
+        assert -1 not in r.remote_indexes
+
+    asyncio.run(check_other())
+
+
+def test_receiver_alloc_timeout(async_receiver):
+    """
+    allocate() returning None past deadline → RuntimeError;
+    prior batches rolled back.
+    """
+    req_id = "req-timeout"
+    async_receiver.allocate = _auto_alloc()
+
+    b1_keys = [_make_key(1000 + i) for i in range(3)]
+    r1 = asyncio.run(
+        async_receiver._async_allocate_and_put(
+            _make_alloc_req(b1_keys, req_id=req_id, total_chunks=6)
+        )
+    )
+    assert -1 not in r1.remote_indexes
+
+    # second batch: first key ok, rest always None
+    n = [0]
+
+    def fail_after_first(shapes, dtype, fmt=MemoryFormat.KV_2LTD, **kw):
+        n[0] += 1
+        return _make_mem_obj(idx=999) if n[0] == 1 else None
+
+    async_receiver.allocate = fail_after_first
+    async_receiver._allocation_timeout = 0.05
+
+    async def run():
+        with pytest.raises(RuntimeError, match="timeout"):
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(2000 + i) for i in range(3)],
+                    req_id=req_id,
+                    total_chunks=6,
+                )
+            )
+
+    asyncio.run(run())
+
+    # New design rolls back prior batches on failure.
+    for k in b1_keys:
+        assert not async_receiver.contains(k, pin=False)
+
+
+def test_receiver_is_last_batch_cleanup(async_receiver):
+    """is_last_batch=True removes req_id from _req_allocated_keys."""
+    req_id = "req-lifecycle"
+    async_receiver.allocate = _auto_alloc()
+
+    asyncio.run(
+        async_receiver._async_allocate_and_put(
+            _make_alloc_req(
+                [_make_key(3000 + i) for i in range(3)],
+                req_id=req_id,
+                is_last_batch=False,
+                total_chunks=5,
+            )
+        )
+    )
+    assert req_id in async_receiver._req_allocated_keys
+    assert len(async_receiver._req_allocated_keys[req_id]) == 3
+
+    asyncio.run(
+        async_receiver._async_allocate_and_put(
+            _make_alloc_req(
+                [_make_key(4000 + i) for i in range(2)],
+                req_id=req_id,
+                is_last_batch=True,
+                total_chunks=5,
+            )
+        )
+    )
+    assert req_id not in async_receiver._req_allocated_keys
+
+
+def test_receiver_admission_control(async_receiver):
+    """Reservation-based admission: concurrent requests can proceed."""
+    async_receiver.allocate = _auto_alloc()
+
+    log = []
+
+    async def run():
+        log.append("A1-start")
+        await async_receiver._async_allocate_and_put(
+            _make_alloc_req(
+                [_make_key(7000 + i) for i in range(2)],
+                req_id="req-A",
+                is_last_batch=False,
+                total_chunks=3,
+            )
+        )
+        log.append("A1-done")
+
+        async def do_b():
+            log.append("B-start")
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(8000)],
+                    req_id="req-B",
+                    is_last_batch=True,
+                    total_chunks=1,
+                )
+            )
+            log.append("B-done")
+
+        async def do_a2():
+            await asyncio.sleep(0.02)
+            log.append("A2-start")
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(9000)],
+                    req_id="req-A",
+                    is_last_batch=True,
+                    total_chunks=3,
+                )
+            )
+            log.append("A2-done")
+
+        await asyncio.gather(do_b(), do_a2())
+
+    asyncio.run(run())
+
+    # With reservation-based admission, A2 and B can proceed concurrently.
+    # All should complete successfully.
+    assert "A1-done" in log
+    assert "A2-done" in log
+    assert "B-done" in log
+
+
+def test_receiver_error_response(async_receiver):
+    """_handle_alloc_request sends error AllocResponse when allocation fails."""
+    payload = msgspec.msgpack.encode(_make_alloc_req([_make_key(0)], req_id="req-err"))
+    identity = b"fake-sender"
+
+    frames_sent = []
+    sock = MagicMock()
+    sock.send_multipart = AsyncMock(side_effect=lambda f: frames_sent.append(f))
+
+    orig = async_receiver._async_allocate_and_put
+
+    async def failing(req):
+        raise RuntimeError("boom")
+
+    async_receiver._async_allocate_and_put = failing
+    asyncio.run(async_receiver._handle_alloc_request(sock, identity, payload))
+    async_receiver._async_allocate_and_put = orig
+
+    assert len(frames_sent) == 1
+    f = frames_sent[0]
+    assert f[0] == identity and f[1] == b""
+    resp = msgspec.msgpack.decode(f[2], type=AsyncPDMsg)
+    assert isinstance(resp, AsyncAllocResponse) and resp.remote_indexes == [-1]
+
+
+# ── close() ──────────────────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("role", ["sender", "receiver"])
+def test_close_stops_thread(role, async_sender, async_receiver):
+    """close() stops the background event-loop thread."""
+    backend = async_sender if role == "sender" else async_receiver
+    attr = "_sender_thread" if role == "sender" else "_recv_thread"
+    assert getattr(backend, attr).is_alive()
+    backend.close()
+    assert not getattr(backend, attr).is_alive()
+    backend.running = False
+
+
+# ── pd_max_prefill_len init check ────────────────────────────────────────
+
+
+def test_pd_max_prefill_len_check():
+    """pd_max_prefill_len > buffer capacity → ValueError on init."""
+    # First Party
+    from lmcache.v1.config import LMCacheEngineConfig
+    from lmcache.v1.metadata import LMCacheMetadata
+
+    def recv_cfg(max_len):
+        return LMCacheEngineConfig.from_defaults(
+            chunk_size=16,
+            pd_role="receiver",
+            pd_peer_host="127.0.0.1",
+            pd_peer_init_port=[9200],
+            pd_peer_alloc_port=[9201],
+            pd_buffer_size=64 * 1024 * 1024,
+            pd_buffer_device="cpu",
+            pd_max_prefill_len=max_len,
+        )
+
+    def send_cfg(max_len):
+        return LMCacheEngineConfig.from_defaults(
+            chunk_size=16,
+            pd_role="sender",
+            pd_proxy_host="127.0.0.1",
+            pd_proxy_port=5555,
+            pd_buffer_size=64 * 1024 * 1024,
+            pd_buffer_device="cpu",
+            pd_max_prefill_len=max_len,
+        )
+
+    meta = LMCacheMetadata(
+        model_name="test",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 16, 8, 128),
+    )
+
+    with _patched_pd():
+        with pytest.raises(ValueError, match="pd_max_prefill_len"):
+            PDBackendAsync(recv_cfg(5000), meta)
+
+    with _patched_pd():
+        with pytest.raises(ValueError, match="pd_max_prefill_len"):
+            PDBackendAsync(send_cfg(5000), meta)
+
+    with _patched_pd():
+        PDBackendAsync(recv_cfg(4096), meta).close()  # boundary ok
+
+    with _patched_pd():
+        PDBackendAsync(recv_cfg(0), meta).close()  # 0 skips check
+
+
+# ── wire-format compatibility (sync ↔ async) ─────────────────────────────
+
+
+def test_sync_request_decoded_as_async():
+    req = SyncAllocRequest(
+        keys=["k0", "k1"],
+        fmt=0,
+        shape=[4, 2, 16, 8, 128],
+        dtype="bfloat16",
+        last_chunk_toks=7,
+    )
+    decoded = msgspec.msgpack.decode(msgspec.msgpack.encode(req), type=AsyncPDMsg)
+    assert isinstance(decoded, AsyncAllocRequest)
+    assert (
+        decoded.keys == ["k0", "k1"]
+        and decoded.req_id == ""
+        and not decoded.is_last_batch
+    )
+
+
+def test_async_response_decoded_as_sync():
+    resp = AsyncAllocResponse(remote_indexes=[100, 200])
+    decoded = msgspec.msgpack.decode(msgspec.msgpack.encode(resp), type=SyncPDMsg)
+    assert isinstance(decoded, SyncAllocResponse)
+    assert decoded.already_sent_indexes == [] and decoded.remote_indexes == [100, 200]
+
+
+def test_sync_response_decoded_as_async():
+    resp = SyncAllocResponse(already_sent_indexes=[0], remote_indexes=[100])
+    decoded = msgspec.msgpack.decode(msgspec.msgpack.encode(resp), type=AsyncPDMsg)
+    assert isinstance(decoded, AsyncAllocResponse)
+    assert decoded.already_sent_indexes == [0] and decoded.remote_indexes == [100]
+
+
+# ── new coverage tests ────────────────────────────────────────────────────
+
+
+def test_receiver_reject_legacy_sender_zero_total_chunks(async_receiver):
+    """req_id + total_chunks=0 → RuntimeError (legacy sender rejected).
+
+    Verifies that a request with a req_id but total_chunks=0 is rejected
+    immediately, since the new reservation-based design requires senders to
+    declare total_chunks upfront.
+    """
+    async_receiver.allocate = _auto_alloc()
+    req = _make_alloc_req([_make_key(0)], req_id="req-legacy", total_chunks=0)
+
+    async def run():
+        with pytest.raises(RuntimeError, match="total_chunks"):
+            await async_receiver._async_allocate_and_put(req)
+
+    asyncio.run(run())
+
+
+def test_receiver_reservation_admission_timeout(async_receiver):
+    """Admission times out when buffer is fully reserved by another request.
+
+    Verifies that when the entire buffer is reserved by an in-progress request,
+    a new request's admission attempt times out and raises RuntimeError.
+    """
+    async_receiver.allocate = _auto_alloc()
+    # Set the reservation manager's own admission timeout to keep the test fast.
+    async_receiver._recv_reservation_mgr._allocation_timeout = 0.05
+    total = async_receiver._recv_reservation_mgr._total_chunks
+
+    async def run():
+        # Admit a request that reserves the entire buffer (not yet released).
+        await async_receiver._async_allocate_and_put(
+            _make_alloc_req(
+                [_make_key(i) for i in range(total)],
+                req_id="req-hog",
+                total_chunks=total,
+                is_last_batch=False,
+            )
+        )
+
+        # Second request cannot be admitted → timeout.
+        with pytest.raises(RuntimeError, match="timed out"):
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(9000)],
+                    req_id="req-blocked",
+                    total_chunks=1,
+                )
+            )
+
+    asyncio.run(run())
+
+
+def test_receiver_cancel_notif_releases_keys_and_reservation(async_receiver):
+    """CancelNotif removes keys, releases reservation, and cleans up tracking.
+
+    Verifies that when a CancelNotif arrives via _handle_alloc_request, all
+    previously allocated keys are removed, the per-request tracking entry is
+    deleted, and the reservation is fully released.
+    """
+    async_receiver.allocate = _auto_alloc()
+    req_id = "req-cancel"
+    keys = [_make_key(5000 + i) for i in range(3)]
+
+    async def run():
+        # Allocate first batch (not last).
+        await async_receiver._async_allocate_and_put(
+            _make_alloc_req(keys, req_id=req_id, total_chunks=5, is_last_batch=False)
+        )
+        assert req_id in async_receiver._req_allocated_keys
+        assert async_receiver._recv_reservation_mgr._total_reserved > 0
+
+        # Send CancelNotif via _handle_alloc_request.
+        cancel = CancelNotif(req_id=req_id, keys=[k.to_string() for k in keys])
+        payload = msgspec.msgpack.encode(cancel)
+        sock = MagicMock()
+        sock.send_multipart = AsyncMock()
+        await async_receiver._handle_alloc_request(sock, b"sender-1", payload)
+
+        # Verify cleanup.
+        for k in keys:
+            assert not async_receiver.contains(k, pin=False)
+        assert req_id not in async_receiver._req_allocated_keys
+        assert async_receiver._recv_reservation_mgr._total_reserved == 0
+
+    asyncio.run(run())
+
+
+def test_receiver_no_req_id_skips_admission(async_receiver):
+    """Empty req_id bypasses reservation admission and chunk accounting.
+
+    Verifies that anonymous requests (req_id="") are allocated without
+    touching the reservation manager, leaving total_reserved unchanged.
+    """
+    async_receiver.allocate = _auto_alloc()
+
+    async def run():
+        r = await async_receiver._async_allocate_and_put(
+            _make_alloc_req([_make_key(0), _make_key(1)], req_id="", total_chunks=0)
+        )
+        assert len(r.remote_indexes) == 2
+        assert -1 not in r.remote_indexes
+        # No reservation should be held for anonymous requests.
+        assert async_receiver._recv_reservation_mgr._total_reserved == 0
+
+    asyncio.run(run())
+
+
+def test_receiver_batch_failure_rolls_back_prior_batches(async_receiver):
+    """Second batch allocation timeout → both batches rolled back.
+
+    Verifies that when a batch fails mid-allocation, all previously allocated
+    keys from earlier batches for the same request are also removed and the
+    reservation is released, since the decoder needs all chunks to proceed.
+    """
+    async_receiver.allocate = _auto_alloc()
+    req_id = "req-rollback"
+    b1_keys = [_make_key(1000 + i) for i in range(3)]
+
+    async def run():
+        # First batch succeeds.
+        r1 = await async_receiver._async_allocate_and_put(
+            _make_alloc_req(b1_keys, req_id=req_id, total_chunks=6, is_last_batch=False)
+        )
+        assert -1 not in r1.remote_indexes
+        for k in b1_keys:
+            assert async_receiver.contains(k, pin=False)
+
+        # Second batch: allocator always returns None → timeout.
+        async_receiver.allocate = lambda *a, **kw: None
+        async_receiver._allocation_timeout = 0.05
+
+        with pytest.raises(RuntimeError, match="timeout"):
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(2000 + i) for i in range(3)],
+                    req_id=req_id,
+                    total_chunks=6,
+                    is_last_batch=True,
+                )
+            )
+
+        # Prior batch keys must be rolled back too.
+        for k in b1_keys:
+            assert not async_receiver.contains(k, pin=False)
+        assert req_id not in async_receiver._req_allocated_keys
+        assert async_receiver._recv_reservation_mgr._total_reserved == 0
+
+    asyncio.run(run())
+
+
+def test_receiver_reservation_released_unblocks_waiting_request(async_receiver):
+    """Releasing a reservation unblocks a concurrently waiting admission.
+
+    Covers the notify_all() call in async_release_reservation.
+    """
+    async_receiver.allocate = _auto_alloc()
+    total = async_receiver._recv_reservation_mgr._total_chunks
+
+    async def run():
+        # Fill all reservation with req-fill (not last batch, so not released yet).
+        await async_receiver._async_allocate_and_put(
+            _make_alloc_req(
+                [_make_key(i) for i in range(total)],
+                req_id="req-fill",
+                total_chunks=total,
+                is_last_batch=False,
+            )
+        )
+
+        result: list = []
+
+        async def blocked_req():
+            r = await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [_make_key(9000)],
+                    req_id="req-wait",
+                    total_chunks=1,
+                )
+            )
+            result.append(r)
+
+        async def release_later():
+            await asyncio.sleep(0.05)
+            # Release req-fill's reservation by sending the last batch.
+            await async_receiver._async_allocate_and_put(
+                _make_alloc_req(
+                    [],
+                    req_id="req-fill",
+                    total_chunks=total,
+                    is_last_batch=True,
+                )
+            )
+
+        await asyncio.gather(blocked_req(), release_later())
+        assert len(result) == 1
+        assert -1 not in result[0].remote_indexes
+
+    asyncio.run(run())
+
+
+# ── ref-count call verification for already_sent_indexes (dedup path) ─────
+
+
+def test_receiver_dedup_pins_existing_key_via_ref_count_up(async_receiver):
+    """
+    _async_allocate_and_put calls ref_count_up
+    on pre-existing key (via contains(pin=True)).
+    """
+    existing_key = _make_key(11000)
+    existing_obj = _make_mem_obj(idx=42)
+    async_receiver.data[existing_key] = existing_obj
+
+    new_key = _make_key(11001)
+    new_obj = _make_mem_obj(idx=99)
+    async_receiver.allocate = lambda *a, **kw: new_obj
+
+    req = _make_alloc_req(
+        [existing_key, new_key],
+        req_id="req-dedup-pin",
+        total_chunks=2,
+        is_last_batch=True,
+    )
+    resp = asyncio.run(async_receiver._async_allocate_and_put(req))
+
+    assert resp.already_sent_indexes == [0]
+    assert len(resp.remote_indexes) == 1
+    # The critical assertion: production code called ref_count_up exactly once
+    # on the existing object (via contains(pin=True)).
+    existing_obj.ref_count_up.assert_called_once()
+    # New object should NOT have ref_count_up called by dedup logic.
+    new_obj.ref_count_up.assert_not_called()
+
+
+def test_receiver_dedup_multiple_existing_keys_each_pinned_once(async_receiver):
+    """Each pre-existing key gets exactly one ref_count_up call."""
+    keys = [_make_key(12000 + i) for i in range(4)]
+    objs = [_make_mem_obj(idx=i) for i in range(4)]
+
+    # Index 0, 2 pre-exist.
+    async_receiver.data[keys[0]] = objs[0]
+    async_receiver.data[keys[2]] = objs[2]
+
+    alloc_counter = itertools.count(start=500)
+
+    def counting_alloc(*a, **kw):
+        return _make_mem_obj(idx=next(alloc_counter))
+
+    async_receiver.allocate = counting_alloc
+
+    req = _make_alloc_req(
+        keys,
+        req_id="req-multi-dedup",
+        total_chunks=4,
+        is_last_batch=True,
+    )
+    resp = asyncio.run(async_receiver._async_allocate_and_put(req))
+
+    assert sorted(resp.already_sent_indexes) == [0, 2]
+    assert len(resp.remote_indexes) == 2
+    objs[0].ref_count_up.assert_called_once()
+    objs[2].ref_count_up.assert_called_once()
+
+
+def test_remove_calls_ref_count_down_and_conditional_delete(async_receiver):
+    """remove() calls ref_count_down; deletes from data only when get_ref_count()==0."""
+    key = _make_key(13000)
+    obj = _make_mem_obj(idx=50)
+    obj._ref_count = 3
+    async_receiver.data[key] = obj
+
+    # First remove: ref_count_down called, but get_ref_count() returns 2 → not deleted
+    async_receiver.remove(key)
+    assert obj.ref_count_down.call_count == 1
+    assert key in async_receiver.data
+
+    # Second remove
+    async_receiver.remove(key)
+    assert obj.ref_count_down.call_count == 2
+    assert key in async_receiver.data
+
+    # Third remove: get_ref_count() will return 0 → deleted
+    async_receiver.remove(key)
+    assert obj.ref_count_down.call_count == 3
+    assert key not in async_receiver.data
+
+
+def test_put_duplicate_calls_ref_count_down_on_new_obj(async_receiver):
+    """Duplicate put() calls ref_count_down on the *new* (rejected) object."""
+    key = _make_key(14000)
+    first_obj = _make_mem_obj(idx=60)
+    second_obj = _make_mem_obj(idx=61)
+
+    async_receiver.put(key, first_obj)
+    first_obj.ref_count_down.assert_not_called()
+
+    async_receiver.put(key, second_obj)
+    # Production code drops the new obj:
+    second_obj.ref_count_down.assert_called_once()
+    # Original untouched:
+    first_obj.ref_count_down.assert_not_called()
+    assert async_receiver.data[key] is first_obj
+
+
+def test_sender_dedup_calls_ref_count_down_on_skipped_chunks():
+    """Sender calls ref_count_down on dedup'd chunks without RDMA write."""
+    p1, p2, p3 = _pd_backend_patches()
+    with p1, p2 as mock_create_tc, p3:
+        alloc_response = AsyncAllocResponse(
+            remote_indexes=[100],
+            already_sent_indexes=[0],
+        )
+        alloc_socket = MagicMock()
+        alloc_socket.recv_multipart = AsyncMock(
+            return_value=[b"", msgspec.msgpack.encode(alloc_response)]
+        )
+        alloc_socket.send_multipart = AsyncMock()
+
+        tc = MagicMock()
+        tc.async_batched_write = AsyncMock(return_value=1)
+        mock_create_tc.return_value = tc
+
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+        from lmcache.v1.metadata import LMCacheMetadata
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=16,
+            pd_role="sender",
+            pd_proxy_host="127.0.0.1",
+            pd_proxy_port=5555,
+            pd_buffer_size=64 * 1024 * 1024,
+            pd_buffer_device="cpu",
+        )
+        metadata = LMCacheMetadata(
+            model_name="test",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 16, 8, 128),
+        )
+        sender = PDBackendAsync(config, metadata)
+        sender._async_proxy_socket = AsyncMock()
+
+        receiver_id = "127.0.0.1" + str(9100)
+        sender.initialized_peers.add(receiver_id)
+        sender._async_alloc_sockets[receiver_id] = alloc_socket
+
+        mem_obj_0 = _make_mem_obj(idx=0)
+        mem_obj_0._ref_count = 2  # post ref_count_up
+        mem_obj_1 = _make_mem_obj(idx=1)
+        mem_obj_1._ref_count = 2
+
+        keys = [_make_key(15000), _make_key(15001)]
+
+        async def run():
+            await sender._async_transfer_task(
+                keys=keys,
+                memory_objs=[mem_obj_0, mem_obj_1],
+                receiver_id=receiver_id,
+                on_complete_callback=None,
+                transfer_spec=_make_transfer_spec(
+                    req_id="req-sender-dedup",
+                    total_chunks=2,
+                ),
+            )
+
+        asyncio.run(run())
+
+        # mem_obj_0 (dedup'd): ref_count_down called exactly once (skip RDMA path)
+        mem_obj_0.ref_count_down.assert_called_once()
+        # mem_obj_1 (sent): ref_count_down called exactly once (after RDMA write)
+        mem_obj_1.ref_count_down.assert_called_once()
+        # Only mem_obj_1 was sent via RDMA
+        tc.async_batched_write.assert_called_once()
+        call_kw = tc.async_batched_write.call_args[1]
+        assert call_kw["objects"] == [mem_obj_1]
+
+        sender.close()
+
+
+def test_dedup_pin_then_remove_verifies_call_sequence(async_receiver):
+    """Full lifecycle: verify ref_count_up/down call counts through dedup + removes."""
+    key = _make_key(16000)
+    obj = _make_mem_obj(idx=70)
+    async_receiver.data[key] = obj
+
+    # Dedup pin via contains(pin=True)
+    async_receiver.contains(key, pin=True)
+    obj.ref_count_up.assert_called_once()
+
+    # First remove
+    async_receiver.remove(key)
+    assert obj.ref_count_down.call_count == 1
+    assert key in async_receiver.data  # ref_count=1 after mock side_effect
+
+    # Second remove
+    async_receiver.remove(key)
+    assert obj.ref_count_down.call_count == 2
+    assert key not in async_receiver.data  # ref_count=0 → deleted
diff --git a/tests/v1/storage_backend/test_pd_backend_bidirectional.py b/tests/v1/storage_backend/test_pd_backend_bidirectional.py
new file mode 100644
index 0000000..a793925
--- /dev/null
+++ b/tests/v1/storage_backend/test_pd_backend_bidirectional.py
@@ -0,0 +1,439 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for PDBackend bidirectional NIXL support.
+
+Verifies that:
+1. PDConfig accepts "both" role
+2. CacheQueryRequest/CacheQueryResponse messages work correctly
+3. batched_submit_read_task queries decoder cache and reads via NIXL
+4. NixlChannel.batched_read performs NIXL READ operation
+5. Config fields pd_bidirectional and pd_peer_query_port exist
+"""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import threading
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.storage_backend.pd_backend import (
+    CacheQueryRequest,
+    CacheQueryResponse,
+    PDBackend,
+    PDConfig,
+    PDMsg,
+)
+
+
+class TestPDConfigBothRole:
+    """Tests for PDConfig with role='both'."""
+
+    def test_both_role_accepted(self):
+        """PDConfig accepts 'both' as a valid role."""
+        config = MagicMock()
+        config.pd_role = "both"
+        config.pd_buffer_size = 1024
+        config.pd_buffer_device = "cuda:0"
+        config.pd_peer_host = "10.0.0.1"
+        config.pd_peer_init_port = [5000]
+        config.pd_peer_alloc_port = [5001]
+        config.pd_peer_query_port = [5002]
+        config.pd_proxy_host = "10.0.0.2"
+        config.pd_proxy_port = 8080
+
+        metadata = MagicMock()
+        metadata.worker_id = 0
+
+        with patch(
+            "lmcache.v1.storage_backend.pd_backend.get_correct_device",
+            return_value="cuda:0",
+        ):
+            pd_config = PDConfig.from_cache_engine_config(config, metadata, tp_rank=0)
+
+        assert pd_config.role == "both"
+        assert pd_config.peer_host == "10.0.0.1"
+        assert pd_config.peer_init_port == 5000
+        assert pd_config.peer_alloc_port == 5001
+        assert pd_config.peer_query_port == 5002
+
+    def test_sender_role_still_works(self):
+        """Existing 'sender' role still works."""
+        config = MagicMock()
+        config.pd_role = "sender"
+        config.pd_buffer_size = 1024
+        config.pd_buffer_device = "cuda:0"
+        config.pd_peer_host = None
+        config.pd_peer_init_port = None
+        config.pd_peer_alloc_port = None
+        config.pd_peer_query_port = None
+        config.pd_proxy_host = "10.0.0.2"
+        config.pd_proxy_port = 8080
+
+        metadata = MagicMock()
+        metadata.worker_id = 0
+
+        with patch(
+            "lmcache.v1.storage_backend.pd_backend.get_correct_device",
+            return_value="cuda:0",
+        ):
+            pd_config = PDConfig.from_cache_engine_config(config, metadata, tp_rank=0)
+
+        assert pd_config.role == "sender"
+
+    def test_receiver_role_still_works(self):
+        """Existing 'receiver' role still works."""
+        config = MagicMock()
+        config.pd_role = "receiver"
+        config.pd_buffer_size = 1024
+        config.pd_buffer_device = "cuda:0"
+        config.pd_peer_host = "10.0.0.1"
+        config.pd_peer_init_port = [5000]
+        config.pd_peer_alloc_port = [5001]
+        config.pd_peer_query_port = None
+        config.pd_proxy_host = None
+        config.pd_proxy_port = None
+
+        metadata = MagicMock()
+        metadata.worker_id = 0
+
+        with patch(
+            "lmcache.v1.storage_backend.pd_backend.get_correct_device",
+            return_value="cuda:0",
+        ):
+            pd_config = PDConfig.from_cache_engine_config(config, metadata, tp_rank=0)
+
+        assert pd_config.role == "receiver"
+
+    def test_invalid_role_rejected(self):
+        """Invalid roles are rejected."""
+        config = MagicMock()
+        config.pd_role = "invalid"
+        config.pd_buffer_size = 1024
+        config.pd_buffer_device = "cuda:0"
+
+        metadata = MagicMock()
+        metadata.worker_id = 0
+
+        with pytest.raises(AssertionError, match="Invalid role"):
+            with patch(
+                "lmcache.v1.storage_backend.pd_backend.get_correct_device",
+                return_value="cuda:0",
+            ):
+                PDConfig.from_cache_engine_config(config, metadata, tp_rank=0)
+
+
+class TestCacheQueryMessages:
+    """Tests for CacheQueryRequest/CacheQueryResponse message types."""
+
+    def test_cache_query_request_serialization(self):
+        """CacheQueryRequest can be serialized and deserialized."""
+        # Third Party
+        import msgspec
+
+        req = CacheQueryRequest(keys=["key1", "key2", "key3"])
+        encoded = msgspec.msgpack.encode(req)
+        decoded = msgspec.msgpack.decode(encoded, type=PDMsg)
+        assert isinstance(decoded, CacheQueryRequest)
+        assert decoded.keys == ["key1", "key2", "key3"]
+
+    def test_cache_query_response_serialization(self):
+        """CacheQueryResponse can be serialized and deserialized."""
+        # Third Party
+        import msgspec
+
+        resp = CacheQueryResponse(
+            cached_keys=["key1", "key3"],
+            cached_indexes=[0, 2],
+        )
+        encoded = msgspec.msgpack.encode(resp)
+        decoded = msgspec.msgpack.decode(encoded, type=PDMsg)
+        assert isinstance(decoded, CacheQueryResponse)
+        assert decoded.cached_keys == ["key1", "key3"]
+        assert decoded.cached_indexes == [0, 2]
+
+    def test_empty_cache_query_response(self):
+        """Empty CacheQueryResponse (no cache hits) works."""
+        # Third Party
+        import msgspec
+
+        resp = CacheQueryResponse(cached_keys=[], cached_indexes=[])
+        encoded = msgspec.msgpack.encode(resp)
+        decoded = msgspec.msgpack.decode(encoded, type=PDMsg)
+        assert isinstance(decoded, CacheQueryResponse)
+        assert len(decoded.cached_keys) == 0
+        assert len(decoded.cached_indexes) == 0
+
+
+class TestBatchedSubmitReadTask:
+    """Tests for PDBackend.batched_submit_read_task."""
+
+    @staticmethod
+    def _make_key(chunk_hash: int) -> CacheEngineKey:
+        """Create a valid CacheEngineKey for testing."""
+        # Third Party
+        import torch
+
+        return CacheEngineKey(
+            model_name="test-model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=chunk_hash,
+            dtype=torch.bfloat16,
+        )
+
+    def _make_backend_stub(self):
+        """Create a minimal PDBackend-like object for testing."""
+        backend = MagicMock(spec=PDBackend)
+        backend.tp_rank = 0
+        backend.initialized_peers = set()
+        backend.mem_alloc_sockets = {}
+        backend.cache_query_sockets = {}
+        backend.data = {}
+        backend.data_lock = threading.Lock()
+
+        # Mock transfer channel
+        backend.transfer_channel = MagicMock()
+        backend.transfer_channel.batched_read.return_value = 3
+
+        # Mock NIXL worker queue: drain puts synchronously so read futures
+        # resolve via a direct batched_read call (mimics the worker thread).
+        class _SyncQueue:
+            def __init__(self, inner_backend):
+                self._backend = inner_backend
+
+            def put(self, item):
+                op_type = item[0]
+                if op_type == "read":
+                    _, buffers, channel_spec, completion_future = item
+                    try:
+                        result = self._backend.transfer_channel.batched_read(
+                            buffers=buffers,
+                            transfer_spec=channel_spec,
+                        )
+                        completion_future.set_result(result)
+                    except Exception as e:  # pragma: no cover - defensive
+                        completion_future.set_exception(e)
+
+        backend._nixl_queue = _SyncQueue(backend)
+
+        # Mock zmq context
+        backend.zmq_context = MagicMock()
+
+        return backend
+
+    def test_read_task_no_cache_hits(self):
+        """batched_submit_read_task returns 0 when decoder has no cached blocks."""
+        backend = self._make_backend_stub()
+
+        # Mock query_remote_cache to return empty response
+        empty_resp = CacheQueryResponse(cached_keys=[], cached_indexes=[])
+        backend.query_remote_cache = MagicMock(return_value=empty_resp)
+        backend._ensure_peer_connection = MagicMock()
+        backend._ensure_cache_query_connection = MagicMock()
+
+        keys = [self._make_key(0), self._make_key(1)]
+        mem_objs = [MagicMock(), MagicMock()]
+
+        transfer_spec = MagicMock()
+        transfer_spec.receiver_host = "10.0.0.1"
+        transfer_spec.receiver_init_port = [5000]
+        transfer_spec.receiver_alloc_port = [5001]
+        transfer_spec.receiver_query_port = [5002]
+
+        result = PDBackend.batched_submit_read_task(
+            backend, keys, mem_objs, transfer_spec
+        )
+        assert result == 0
+
+    def test_read_task_with_cache_hits(self):
+        """batched_submit_read_task reads cached blocks via NIXL READ."""
+
+        backend = self._make_backend_stub()
+
+        key0 = self._make_key(0)
+        key1 = self._make_key(1)
+        key2 = self._make_key(2)
+
+        # Mock cache query response: key0 and key2 are cached
+        cache_resp = CacheQueryResponse(
+            cached_keys=[key0.to_string(), key2.to_string()],
+            cached_indexes=[100, 300],
+        )
+
+        # Mock query_remote_cache to return our response
+        backend.query_remote_cache = MagicMock(return_value=cache_resp)
+        backend._ensure_peer_connection = MagicMock()
+        backend._ensure_cache_query_connection = MagicMock()
+
+        keys = [key0, key1, key2]
+        mem_objs = [MagicMock(), MagicMock(), MagicMock()]
+
+        transfer_spec = MagicMock()
+        transfer_spec.receiver_host = "10.0.0.1"
+        transfer_spec.receiver_init_port = [5000]
+        transfer_spec.receiver_alloc_port = [5001]
+        transfer_spec.receiver_query_port = [5002]
+
+        PDBackend.batched_submit_read_task(backend, keys, mem_objs, transfer_spec)
+
+        # Should have called batched_read with 2 objects (key0 and key2)
+        backend.transfer_channel.batched_read.assert_called_once()
+        call_kwargs = backend.transfer_channel.batched_read.call_args
+        buffers = call_kwargs.kwargs.get("buffers")
+        spec = call_kwargs.kwargs.get("transfer_spec")
+        assert len(buffers) == 2
+        assert buffers[0] is mem_objs[0]  # key0 → index 0
+        assert buffers[1] is mem_objs[2]  # key2 → index 2
+        assert spec["remote_indexes"] == [100, 300]
+        assert spec["sender_id"] == "10.0.0.15000"
+
+
+class TestNixlChannelBatchedRead:
+    """Tests for NixlChannel.batched_read implementation."""
+
+    def test_batched_read_calls_nixl_read(self):
+        """batched_read uses NIXL READ operation."""
+        # First Party
+        from lmcache.v1.transfer_channel.nixl_channel import NixlChannel
+
+        # Create a mock channel
+        channel = MagicMock(spec=NixlChannel)
+        channel.nixl_agent = MagicMock()
+        channel.nixl_wrapper = MagicMock()
+        channel.nixl_wrapper.xfer_handler = "local_handler"
+        channel.remote_xfer_handlers_dict = {"peer1": "remote_handler"}
+
+        # Mock make_prepped_xfer and transfer
+        mock_handle = MagicMock()
+        channel.nixl_agent.make_prepped_xfer.return_value = mock_handle
+        channel.nixl_agent.check_xfer_state.return_value = "DONE"
+
+        # Create mock buffers with MemoryObj-like interface
+        buf1 = MagicMock()
+        buf1.meta = MagicMock()
+        buf1.meta.address = 0
+        buf2 = MagicMock()
+        buf2.meta = MagicMock()
+        buf2.meta.address = 1
+
+        # Mock get_local_mem_indices to return addresses
+        channel.get_local_mem_indices = MagicMock(return_value=[0, 1])
+
+        transfer_spec = {
+            "sender_id": "peer1",
+            "remote_indexes": [10, 20],
+        }
+
+        # Call the real method
+        result = NixlChannel.batched_read(channel, [buf1, buf2], transfer_spec)
+
+        assert result == 2
+        channel.nixl_agent.make_prepped_xfer.assert_called_once_with(
+            "READ",
+            channel.nixl_wrapper.xfer_handler,
+            [0, 1],
+            "remote_handler",
+            [10, 20],
+        )
+        channel.nixl_agent.transfer.assert_called_once_with(mock_handle)
+
+
+class TestConfigFields:
+    """Test that new config fields exist and have correct defaults."""
+
+    def test_pd_bidirectional_default(self):
+        """pd_bidirectional defaults to False."""
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+
+        config = LMCacheEngineConfig.from_defaults()
+        assert config.pd_bidirectional is False
+
+    def test_pd_bidirectional_set(self):
+        """pd_bidirectional can be set to True."""
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+
+        config = LMCacheEngineConfig.from_defaults(pd_bidirectional=True)
+        assert config.pd_bidirectional is True
+
+    def test_pd_peer_query_port_default(self):
+        """pd_peer_query_port defaults to None."""
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+
+        config = LMCacheEngineConfig.from_defaults()
+        assert config.pd_peer_query_port is None
+
+    def test_pd_peer_query_port_set(self):
+        """pd_peer_query_port can be set."""
+        # First Party
+        from lmcache.v1.config import LMCacheEngineConfig
+
+        expected = [6000, 6001, 6002, 6003, 6004, 6005, 6006, 6007]
+        config = LMCacheEngineConfig.from_defaults(pd_peer_query_port=expected)
+        assert config.pd_peer_query_port == expected
+
+
+class TestCacheQueryLoop:
+    """Tests for the decoder-side _cache_query_loop."""
+
+    @staticmethod
+    def _make_key(chunk_hash: int) -> CacheEngineKey:
+        """Create a valid CacheEngineKey for testing."""
+        # Third Party
+        import torch
+
+        return CacheEngineKey(
+            model_name="test-model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=chunk_hash,
+            dtype=torch.bfloat16,
+        )
+
+    def test_cache_query_returns_cached_keys(self):
+        """_cache_query_loop returns correct cached keys and indexes."""
+
+        backend = MagicMock(spec=PDBackend)
+        backend.running = True
+        backend.data = {}
+        backend.data_lock = threading.Lock()
+
+        # Populate decoder's cache with some keys
+        key1 = self._make_key(1)
+        key2 = self._make_key(2)
+        key3 = self._make_key(3)  # not cached
+        mem1 = MagicMock()
+        mem1.meta.address = 42
+        mem2 = MagicMock()
+        mem2.meta.address = 84
+        backend.data[key1] = mem1
+        backend.data[key2] = mem2
+
+        # Create a query for 3 keys (2 cached, 1 not)
+        query = CacheQueryRequest(
+            keys=[
+                key1.to_string(),
+                key3.to_string(),
+                key2.to_string(),
+            ]
+        )
+
+        # Simulate what _cache_query_loop does
+        cached_keys = []
+        cached_indexes = []
+        with backend.data_lock:
+            for key_str in query.keys:
+                key = CacheEngineKey.from_string(key_str)
+                if mem_obj := backend.data.get(key, None):
+                    cached_keys.append(key_str)
+                    cached_indexes.append(mem_obj.meta.address)
+
+        assert len(cached_keys) == 2
+        assert cached_keys[0] == key1.to_string()
+        assert cached_keys[1] == key2.to_string()
+        assert cached_indexes == [42, 84]
diff --git a/tests/v1/storage_backend/test_pd_backend_buffer_alignment.py b/tests/v1/storage_backend/test_pd_backend_buffer_alignment.py
new file mode 100644
index 0000000..caa8f1d
--- /dev/null
+++ b/tests/v1/storage_backend/test_pd_backend_buffer_alignment.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for PD backend buffer-size alignment."""
+
+# Standard
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.pd_backend import PDBackend
+
+
+def create_test_metadata(kv_shape=(4, 2, 256, 8, 128)) -> LMCacheMetadata:
+    """Create test metadata with configurable KV shape."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+    )
+
+
+@patch("lmcache.v1.storage_backend.pd_backend.PagedCpuGpuMemoryAllocator")
+def test_buffer_size_unaligned_to_aligned(mock_allocator_cls):
+    """
+    Test that PD buffer size is rounded down to the nearest chunk multiple.
+
+    Args:
+        mock_allocator_cls: Mocked paged allocator class injected by patch.
+    """
+    metadata = create_test_metadata(kv_shape=(4, 2, 256, 8, 128))
+    # 4 * 2 * 256 * 8 * 128 * 2 bytes (bfloat16) = 4194304 bytes per chunk.
+    # (13000000 // 4194304) * 4194304 = 12582912 bytes.
+    expected_aligned_size = 12582912
+
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        pd_buffer_size=13000000,  # NOT a multiple of 4194304
+    )
+
+    allocator = MagicMock()
+    mock_allocator_cls.return_value = allocator
+
+    backend_context = SimpleNamespace(corrected_device="cpu")
+
+    returned_allocator = PDBackend.initialize_allocator(
+        backend_context, config, metadata
+    )
+
+    assert returned_allocator is allocator
+    allocator.init_gpu_memory_allocator.assert_not_called()
+    allocator.init_cpu_memory_allocator.assert_called_once_with(
+        expected_aligned_size,
+        [torch.Size(metadata.kv_shape)],
+        [metadata.kv_dtype],
+        MemoryFormat.KV_2LTD,
+    )
diff --git a/tests/v1/storage_backend/test_raw_block_core.py b/tests/v1/storage_backend/test_raw_block_core.py
new file mode 100644
index 0000000..d7ac8f8
--- /dev/null
+++ b/tests/v1/storage_backend/test_raw_block_core.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.storage_backend.raw_block import RawBlockCore, encode_object_key
+from tests.v1.storage_backend.raw_block_test_utils import (
+    make_empty_memory_obj,
+    make_memory_obj,
+    make_object_key,
+    make_raw_block_core_config,
+    make_raw_block_file,
+    memory_obj_bytes,
+)
+
+pytest.importorskip("lmcache_rust_raw_block_io")
+
+
+def test_raw_block_core_store_load_and_exists(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    config = make_raw_block_core_config(path)
+    core = RawBlockCore(config, key_namespace="object")
+
+    try:
+        keys = [make_object_key(i) for i in range(3)]
+        specs = [encode_object_key(key) for key in keys]
+        payloads = [
+            bytes([1]) * 1024,
+            bytes([2]) * 2048,
+            bytes([3]) * 3072,
+        ]
+        objects = [make_memory_obj(payload) for payload in payloads]
+
+        put_result = core.put_many(specs, objects)
+
+        assert put_result.results == [True, True, True]
+        assert put_result.stored_keys == [spec.encoded for spec in specs]
+        assert core.exists_many([spec.encoded for spec in specs]) == [
+            True,
+            True,
+            True,
+        ]
+
+        loaded = [make_empty_memory_obj(len(payload)) for payload in payloads]
+        load_result = core.load_many_into([spec.encoded for spec in specs], loaded)
+
+        assert load_result == [True, True, True]
+        assert [memory_obj_bytes(obj) for obj in loaded] == payloads
+    finally:
+        core.close()
+
+
+def test_raw_block_core_duplicate_put_keeps_original_payload(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    config = make_raw_block_core_config(path)
+    core = RawBlockCore(config, key_namespace="object")
+
+    try:
+        spec = encode_object_key(make_object_key(11))
+        original = b"original"
+        duplicate = b"mutated!"
+
+        first_result = core.put_many([spec], [make_memory_obj(original)])
+        duplicate_result = core.put_many([spec], [make_memory_obj(duplicate)])
+
+        assert first_result.results == [True]
+        assert first_result.stored_keys == [spec.encoded]
+        assert duplicate_result.results == [True]
+        assert duplicate_result.stored_keys == []
+
+        loaded = make_empty_memory_obj(len(original))
+        assert core.load_many_into([spec.encoded], [loaded]) == [True]
+        assert memory_obj_bytes(loaded) == original
+    finally:
+        core.close()
+
+
+def test_raw_block_core_delete_and_missing_load(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    config = make_raw_block_core_config(path)
+    core = RawBlockCore(config, key_namespace="object")
+
+    try:
+        existing = encode_object_key(make_object_key(21))
+        missing = encode_object_key(make_object_key(22))
+
+        put_result = core.put_many([existing], [make_memory_obj(b"delete-me")])
+        assert put_result.results == [True]
+        assert core.contains_key(existing.encoded) is True
+
+        assert core.delete_many([existing.encoded, missing.encoded]) == [True, False]
+        assert core.exists_many([existing.encoded, missing.encoded]) == [False, False]
+
+        loaded = make_empty_memory_obj(len(b"delete-me"))
+        assert core.load_many_into([existing.encoded], [loaded]) == [False]
+    finally:
+        core.close()
+
+
+def test_raw_block_core_recovers_checkpoint_from_temp_file(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    config = make_raw_block_core_config(path)
+    spec = encode_object_key(make_object_key(31))
+    payload = b"recoverable-raw-block-payload"
+
+    core = RawBlockCore(config, key_namespace="object")
+    try:
+        put_result = core.put_many([spec], [make_memory_obj(payload)])
+        assert put_result.results == [True]
+        core.checkpoint_now()
+    finally:
+        core.close()
+
+    recovered = RawBlockCore(config, key_namespace="object")
+    try:
+        assert recovered.contains_key(spec.encoded) is True
+        loaded = make_empty_memory_obj(len(payload))
+        assert recovered.load_many_into([spec.encoded], [loaded]) == [True]
+        assert memory_obj_bytes(loaded) == payload
+    finally:
+        recovered.close()
diff --git a/tests/v1/storage_backend/test_raw_block_device.py b/tests/v1/storage_backend/test_raw_block_device.py
new file mode 100644
index 0000000..bfe5596
--- /dev/null
+++ b/tests/v1/storage_backend/test_raw_block_device.py
@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+import errno
+import os
+import platform
+
+# Third Party
+import pytest
+
+# First Party
+from tests.v1.storage_backend.raw_block_test_utils import (
+    RAW_BLOCK_CI_BLOCK_ALIGN,
+    RAW_BLOCK_CI_CAPACITY_BYTES,
+    make_raw_block_file,
+)
+
+lmcache_rust_raw_block_io = pytest.importorskip("lmcache_rust_raw_block_io")
+RawBlockDevice = lmcache_rust_raw_block_io.RawBlockDevice
+
+
+def _is_skip_safe_io_error(exc: BaseException) -> bool:
+    if getattr(exc, "errno", None) in {errno.EINVAL, errno.ENOSYS, errno.EPERM}:
+        return True
+    msg = str(exc).lower()
+    return any(
+        text in msg
+        for text in (
+            "function not implemented",
+            "invalid argument",
+            "io_uring init failed",
+            "not supported",
+            "operation not permitted",
+            "unsupported",
+        )
+    )
+
+
+def test_raw_block_device_posix_roundtrip_on_tmp_file(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    dev = RawBlockDevice(
+        str(path),
+        writable=True,
+        use_odirect=False,
+        alignment=RAW_BLOCK_CI_BLOCK_ALIGN,
+        io_engine="posix",
+        iouring_queue_depth=8,
+    )
+
+    try:
+        assert dev.size_bytes() == RAW_BLOCK_CI_CAPACITY_BYTES
+
+        payload1 = bytearray(b"raw-block-posix-ci-payload")
+        payload2 = bytearray(bytes(range(64)))
+        out1 = bytearray(len(payload1))
+        out2 = bytearray(len(payload2))
+
+        dev.pwrite_from_buffer(4096, payload1, len(payload1), len(payload1))
+        dev.pwrite_from_buffer(8192, payload2, len(payload2), len(payload2))
+
+        dev.pread_into(4096, out1, len(out1), len(out1))
+        dev.pread_into(8192, out2, len(out2), len(out2))
+
+        assert out1 == payload1
+        assert out2 == payload2
+    finally:
+        dev.close()
+
+
+def test_raw_block_device_read_past_capacity_raises(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    dev = RawBlockDevice(
+        str(path),
+        writable=True,
+        use_odirect=False,
+        alignment=RAW_BLOCK_CI_BLOCK_ALIGN,
+        io_engine="posix",
+        iouring_queue_depth=8,
+    )
+
+    try:
+        out = bytearray(1)
+        with pytest.raises(RuntimeError, match="unexpected EOF"):
+            dev.pread_into(RAW_BLOCK_CI_CAPACITY_BYTES, out, len(out), len(out))
+    finally:
+        dev.close()
+
+
+@pytest.mark.skipif(platform.system() != "Linux", reason="io_uring is Linux only")
+def test_raw_block_device_iouring_best_effort_roundtrip(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    dev = None
+    try:
+        dev = RawBlockDevice(
+            str(path),
+            writable=True,
+            use_odirect=False,
+            alignment=RAW_BLOCK_CI_BLOCK_ALIGN,
+            io_engine="io_uring",
+            iouring_queue_depth=8,
+        )
+
+        payload = bytearray(b"raw-block-iouring-ci-payload")
+        out = bytearray(len(payload))
+
+        batch_id = dev.batched_write([4096], [payload], [len(payload)])
+        dev.wait_iouring(batch_id)
+        batch_id = dev.batched_read([4096], [out], [len(out)])
+        dev.wait_iouring(batch_id)
+
+        assert out == payload
+    except Exception as e:
+        if _is_skip_safe_io_error(e):
+            pytest.skip(f"io_uring is unavailable on this runner: {e}")
+        raise
+    finally:
+        if dev is not None:
+            dev.close()
+
+
+@pytest.mark.skipif(
+    os.getenv("LMCACHE_RUN_ODIRECT_SMOKE") != "1",
+    reason="O_DIRECT smoke is opt-in and not part of default PR CI",
+)
+def test_raw_block_device_odirect_optional_smoke(tmp_path):
+    path = make_raw_block_file(tmp_path)
+    dev = None
+    try:
+        dev = RawBlockDevice(
+            str(path),
+            writable=True,
+            use_odirect=True,
+            alignment=RAW_BLOCK_CI_BLOCK_ALIGN,
+            io_engine="posix",
+            iouring_queue_depth=8,
+        )
+
+        payload = bytearray([17]) * RAW_BLOCK_CI_BLOCK_ALIGN
+        out = bytearray(len(payload))
+        dev.pwrite_from_buffer(4096, payload, len(payload), len(payload))
+        dev.pread_into(4096, out, len(out), len(out))
+        assert out == payload
+    except Exception as e:
+        if _is_skip_safe_io_error(e):
+            pytest.skip(f"O_DIRECT is unavailable on this runner: {e}")
+        raise
+    finally:
+        if dev is not None:
+            dev.close()
diff --git a/tests/v1/storage_backend/test_raw_block_key_codec.py b/tests/v1/storage_backend/test_raw_block_key_codec.py
new file mode 100644
index 0000000..1bc3770
--- /dev/null
+++ b/tests/v1/storage_backend/test_raw_block_key_codec.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# First Party
+from lmcache.v1.distributed.api import ObjectKey
+from lmcache.v1.storage_backend.raw_block.key_codec import (
+    decode_object_key,
+    object_key_to_string,
+)
+
+
+def test_raw_block_object_key_codec_preserves_sep_literal() -> None:
+    """Object-key encoding must not treat literal -SEP- as a slash escape."""
+    key = ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(123),
+        model_name="my-SEP-model",
+        kv_rank=1,
+        cache_salt="tenant",
+    )
+
+    decoded = decode_object_key(object_key_to_string(key))
+
+    assert decoded == key
+
+
+def test_raw_block_object_key_codec_roundtrips_slash_and_sep() -> None:
+    """Object-key encoding must round-trip slashes and literal -SEP- strings."""
+    key = ObjectKey(
+        chunk_hash=ObjectKey.IntHash2Bytes(456),
+        model_name="org/model-SEP-name",
+        kv_rank=2,
+    )
+
+    encoded = object_key_to_string(key)
+    decoded = decode_object_key(encoded)
+
+    assert "%2F" in encoded
+    assert decoded == key
+
+
+def test_raw_block_object_key_codec_roundtrips_object_group_id() -> None:
+    """object_group_id must survive encode/decode for salted and unsalted keys."""
+    for object_group_id in (0, 1, 255):
+        for cache_salt in ("", "tenant"):
+            key = ObjectKey(
+                chunk_hash=ObjectKey.IntHash2Bytes(789),
+                model_name="org/model",
+                kv_rank=7,
+                object_group_id=object_group_id,
+                cache_salt=cache_salt,
+            )
+            assert decode_object_key(object_key_to_string(key)) == key
+
+
+def test_raw_block_object_group_id_distinguishes_encoding() -> None:
+    """Keys differing only in object_group_id must encode differently."""
+    chunk_hash = ObjectKey.IntHash2Bytes(1)
+    enc0 = object_key_to_string(
+        ObjectKey(chunk_hash=chunk_hash, model_name="m", kv_rank=0, object_group_id=0)
+    )
+    enc1 = object_key_to_string(
+        ObjectKey(chunk_hash=chunk_hash, model_name="m", kv_rank=0, object_group_id=1)
+    )
+    assert enc0 != enc1
diff --git a/tests/v1/storage_backend/test_raw_block_uring_cmd.py b/tests/v1/storage_backend/test_raw_block_uring_cmd.py
new file mode 100644
index 0000000..e109953
--- /dev/null
+++ b/tests/v1/storage_backend/test_raw_block_uring_cmd.py
@@ -0,0 +1,320 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Tests for io_uring command (passthrough) support in Rust raw block backend."""
+
+# Standard
+from unittest.mock import MagicMock, patch
+import asyncio
+import os
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.logging import init_logger
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.plugins.rust_raw_block_backend import (
+    RustRawBlockBackend,
+)
+from lmcache.v1.storage_backend.raw_block.core import (
+    RawBlockCore,
+)
+
+logger = init_logger(__name__)
+
+
+# GLobal test device configuration with environment variables
+TEST_DEVICES = {
+    "block_device": os.environ.get("LMCACHE_TEST_BLOCK_DEVICE", "/dev/nvme0n1"),
+    "char_device": os.environ.get("LMCACHE_TEST_CHAR_DEVICE", "/dev/ng0n1"),
+    "null_device": os.environ.get("LMCACHE_TEST_NULL_DEVICE", "/dev/null"),
+}
+
+
+def _get_sysfs_path(device_path: str) -> str:
+    """Derive sysfs path from device path."""
+
+    device_name = os.path.basename(device_path)
+
+    if device_name.startswith("ng"):
+        parts = device_name[2:]
+        device_name = f"nvme{parts}"
+
+    return f"/sys/block/{device_name}"
+
+
+def _has_ext() -> bool:
+    """Check if the Rust raw block I/O extension is available."""
+    try:
+        # Third Party
+        import lmcache_rust_raw_block_io  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+# Skip all tests in this file if the Rust extension is not available
+pytestmark = pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not available"
+)
+
+
+@pytest.fixture
+def loop_in_thread():
+    loop = asyncio.new_event_loop()
+    try:
+        yield loop
+    finally:
+        loop.close()
+
+
+class MockConfig:
+    """Mock configuration for testing."""
+
+    def __init__(
+        self,
+        device_path: str,
+        use_uring_cmd: bool = False,
+        meta_total_bytes=4 * 1024 * 1024,
+    ):
+        self.extra_config = {
+            "rust_raw_block.device_path": device_path,
+            "rust_raw_block.use_odirect": False,
+            "rust_raw_block.use_uring": True,
+            "rust_raw_block.use_uring_cmd": use_uring_cmd,
+            "rust_raw_block.capacity_bytes": 1024 * 1024 * 1024,  # 1GB
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": meta_total_bytes,
+        }
+
+
+class MockMetadata:
+    """Mock metadata for testing."""
+
+    def __init__(self, worker_id: int = 0, world_size: int = 1):
+        self.worker_id = worker_id
+        self.world_size = world_size
+
+
+class MockLocalCPUBackend:
+    """Mock local CPU backend for testing."""
+
+    def __init__(self):
+        pass
+
+    def get_memory_allocator(self):
+        return None
+
+    def get_full_chunk_size_bytes(self) -> int:
+        """return a default chunk size only for testing."""
+        return 256 * 1024
+
+
+def _build_rust_raw_block_metadata(
+    worker_id: int = 0,
+    world_size: int = 1,
+) -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=world_size,
+        local_world_size=world_size,
+        worker_id=worker_id,
+        local_worker_id=worker_id,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+
+def _build_rust_raw_block_local_cpu_backend() -> MagicMock:
+    local_cpu_backend = MagicMock()
+    local_cpu_backend.get_full_chunk_size_bytes.return_value = 4096
+    return local_cpu_backend
+
+
+def _build_transfer_limit_backend(
+    dev_path: str,
+    max_data_transfer_size: int | None = None,
+) -> RustRawBlockBackend:
+    config = MockConfig(device_path=dev_path, use_uring_cmd=True)
+    if max_data_transfer_size is not None:
+        config.extra_config["rust_raw_block.max_data_transfer_size"] = (
+            max_data_transfer_size
+        )
+
+    metadata = MockMetadata()
+    loop = asyncio.new_event_loop()
+    try:
+        with (
+            patch.object(RawBlockCore, "_rawdev", return_value=MagicMock()),
+            patch.object(RawBlockCore, "_ensure_capacity_and_layout"),
+            patch.object(RawBlockCore, "_load_checkpoint_from_device"),
+        ):
+            backend = RustRawBlockBackend(
+                config=config,
+                metadata=metadata,
+                local_cpu_backend=MockLocalCPUBackend(),
+                loop=loop,
+                dst_device="cpu",
+            )
+            return backend
+    finally:
+        loop.close()
+
+
+def test_uring_cmd_requires_character_device(loop_in_thread):
+    """Test that io_uring_cmd requires a character device, not a block device."""
+    # This test requires a block device device
+    # Skip if this doesn't exist
+    device_path = TEST_DEVICES["block_device"]
+
+    if not os.path.exists(device_path):
+        pytest.skip(f"Test device {device_path} not found.")
+
+    config = MockConfig(device_path=device_path, use_uring_cmd=True)
+    metadata = MockMetadata(worker_id=0, world_size=1)
+    local_cpu_backend = MockLocalCPUBackend()
+
+    # This should raise an error because the device is not a character device
+    with pytest.raises(
+        ValueError, match="use_uring_cmd requires an NVMe namespace character device"
+    ):
+        RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop_in_thread,
+        )
+
+
+def test_uring_cmd_get_nvme_info(loop_in_thread):
+    """Test getting NVMe namespace ID and LBA size from character device."""
+    # This test requires a nvme NS character device
+    # Skip if this doesn't exist
+    device_path = TEST_DEVICES["char_device"]
+
+    if not os.path.exists(device_path):
+        pytest.skip(f"Test device {device_path} not found.")
+
+    config = MockConfig(device_path=device_path, use_uring_cmd=True)
+    metadata = MockMetadata(worker_id=0, world_size=1)
+    local_cpu_backend = MockLocalCPUBackend()
+
+    try:
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop_in_thread,
+        )
+
+        # Get the raw device
+        raw_device = backend._core.raw_device()
+
+        # Test getting namespace ID
+        nsid = raw_device.nvme_nsid()
+        assert nsid > 0, f"Expected positive nsid, got {nsid}"
+        logger.info(f"NVMe namespace ID: {nsid}")
+
+        # Test getting LBA size
+        lba_size = raw_device.nvme_lba_size()
+        assert lba_size > 0, f"Expected positive lba_size, got {lba_size}"
+        logger.info(f"NVMe LBA size: {lba_size} bytes")
+
+    except Exception as e:
+        pytest.fail(f"Failed to get NVMe info: {e}")
+
+
+def test_uring_cmd_disabled(loop_in_thread):
+    """Test that NVMe methods are not available when use_uring_cmd is disabled."""
+    config = MockConfig(device_path=TEST_DEVICES["null_device"], use_uring_cmd=False)
+    metadata = MockMetadata(worker_id=0, world_size=1)
+    local_cpu_backend = MockLocalCPUBackend()
+    raw_device = MagicMock()
+    raw_device.nvme_nsid.side_effect = RuntimeError("use_uring_cmd not enabled")
+    raw_device.nvme_lba_size.side_effect = RuntimeError("use_uring_cmd not enabled")
+
+    with (
+        patch.object(RawBlockCore, "_rawdev", return_value=MagicMock()),
+        patch.object(RawBlockCore, "_ensure_capacity_and_layout"),
+        patch.object(RawBlockCore, "_load_checkpoint_from_device"),
+    ):
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop_in_thread,
+        )
+        backend._raw = raw_device
+
+    # These should raise errors when use_uring_cmd is disabled
+    with pytest.raises(RuntimeError, match="use_uring_cmd not enabled"):
+        raw_device.nvme_nsid()
+
+    with pytest.raises(RuntimeError, match="use_uring_cmd not enabled"):
+        raw_device.nvme_lba_size()
+
+
+def test_uring_cmd_auto_transfer_limit_from_sysfs_ng_device():
+    expected_path = (
+        f"{_get_sysfs_path(TEST_DEVICES['char_device'])}/queue/max_hw_sectors_kb"
+    )
+    with patch(
+        "lmcache.v1.storage_backend.raw_block.core._read_sysfs_int",
+        return_value=1024,
+    ) as mock_read:
+        backend = _build_transfer_limit_backend(
+            TEST_DEVICES["char_device"], max_data_transfer_size=-1
+        )
+
+    mock_read.assert_called_once_with(expected_path)
+    assert backend._core.max_data_transfer_size == 1024 * 1024
+
+
+def test_uring_cmd_auto_transfer_limit_fails_when_sysfs_unavailable():
+    expected_path = (
+        f"{_get_sysfs_path(TEST_DEVICES['char_device'])}/queue/max_hw_sectors_kb"
+    )
+    with patch(
+        "lmcache.v1.storage_backend.raw_block.core._read_sysfs_int",
+        return_value=None,
+    ) as mock_read:
+        with pytest.raises(RuntimeError, match="failed to read max_hw_sectors_kb"):
+            _build_transfer_limit_backend(
+                TEST_DEVICES["char_device"], max_data_transfer_size=-1
+            )
+
+    mock_read.assert_called_once_with(expected_path)
+
+
+def test_uring_cmd_explicit_transfer_limit_must_be_block_aligned():
+    """Test that explicitly configured max_data_transfer_size must be block-aligned."""
+    # Default block_align is 4096 bytes
+    # 4096 is block-aligned (4096 % 4096 == 0)
+    backend = _build_transfer_limit_backend(
+        TEST_DEVICES["char_device"], max_data_transfer_size=4096
+    )
+    assert backend._core.max_data_transfer_size == 4096
+
+    # 8192 is block-aligned (8192 % 4096 == 0)
+    backend = _build_transfer_limit_backend(
+        TEST_DEVICES["char_device"], max_data_transfer_size=8192
+    )
+    assert backend._core.max_data_transfer_size == 8192
+
+    # 5000 is NOT block-aligned (5000 % 4096 != 0)
+    with pytest.raises(
+        ValueError,
+        match=r"max_data_transfer_size \(5000\) must be a multiple of "
+        "block_align \(4096\)",
+    ):
+        _build_transfer_limit_backend(
+            TEST_DEVICES["char_device"], max_data_transfer_size=5000
+        )
+
+
+if __name__ == "__main__":
+    # Run tests with pytest
+    pytest.main([__file__, "-v"])
diff --git a/tests/v1/storage_backend/test_remote_storage_plugin.py b/tests/v1/storage_backend/test_remote_storage_plugin.py
new file mode 100644
index 0000000..48f102c
--- /dev/null
+++ b/tests/v1/storage_backend/test_remote_storage_plugin.py
@@ -0,0 +1,534 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test cases for remote storage plugin functionality.
+
+This module tests the remote storage  plugin loading mechanism in ConnectorManager.
+It creates mock connector adapters extending ConnectorAdapter and verifies that:
+1. Connector adapters are properly loaded via the configuration
+2. The connector adapter's create_connector method is called for matching URLs
+3. Invalid configurations are handled gracefully
+"""
+
+# Standard
+from typing import List, Optional
+import asyncio
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.storage_backend.connector import (
+    ConnectorAdapter,
+    ConnectorContext,
+    ConnectorManager,
+    CreateConnector,
+)
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+
+
+class MockTestRemoteConnector(RemoteConnector):
+    """
+    A mock remote connector for testing the remote storage plugin functionality.
+    This connector tracks method calls for verification.
+    """
+
+    def __init__(self, config, metadata):
+        # Skip parent __init__ since we're mocking
+        self.call_history: List[str] = []
+        self.storage: dict = {}
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        """Check if key exists."""
+        self.call_history.append(f"exists:{key.chunk_hash}")
+        return key.chunk_hash in self.storage
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        """Check if key exists synchronously."""
+        self.call_history.append(f"exists_sync:{key.chunk_hash}")
+        return key.chunk_hash in self.storage
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Get a value."""
+        self.call_history.append(f"get:{key.chunk_hash}")
+        return self.storage.get(key.chunk_hash)
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj):
+        """Put a value."""
+        self.call_history.append(f"put:{key.chunk_hash}")
+        self.storage[key.chunk_hash] = memory_obj
+
+    async def list(self) -> List[str]:
+        """List all keys."""
+        self.call_history.append("list")
+        return list(self.storage.keys())
+
+    async def close(self):
+        """Close the connector."""
+        self.call_history.append("close")
+
+    def __repr__(self) -> str:
+        return "MockTestRemoteConnector"
+
+
+class MockTestConnectorAdapter(ConnectorAdapter):
+    """
+    A mock connector adapter for testing the remote storage functionality.
+    This adapter extends ConnectorAdapter and creates MockTestRemoteConnector instances.
+
+    This adapter uses instance-level storage for call history and connector storage
+    to enable proper testing of dynamically loaded connector adapters.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("mockplugin://")
+        self.call_history: List[str] = []
+
+    def create_connector(self, context: ConnectorContext) -> RemoteConnector:
+        """Create a mock remote connector."""
+        self.call_history.append(f"create_connector:{context.url}")
+        connector = MockTestRemoteConnector(context.config, context.metadata)
+        return connector
+
+
+class NotAConnectorAdapter:
+    """
+    A class that does not implement ConnectorAdapter.
+    Used to test that non-ConnectorAdapter classes are rejected.
+    """
+
+    def __init__(self) -> None:
+        pass
+
+
+# Module-level constants for connector plugin configuration
+MOCK_CONNECTOR_EXTRA_CONFIG = {
+    "remote_storage_plugin.mock_connector.module_path": (
+        "tests.v1.storage_backend.test_remote_storage_plugin"
+    ),
+    "remote_storage_plugin.mock_connector.class_name": "MockTestConnectorAdapter",
+}
+MOCK_CONNECTOR_REMOTE_STORAGE_PLUGINS = ["mock_connector"]
+
+
+def create_test_config(
+    extra_config: Optional[dict] = None,
+    remote_storage_plugins: Optional[List[str]] = None,
+) -> LMCacheEngineConfig:
+    """Create a test configuration for connector plugin testing."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=0.1,
+        lmcache_instance_id="test_remote_storage_plugin_instance",
+    )
+    if extra_config:
+        config.extra_config = extra_config
+    if remote_storage_plugins:
+        config.remote_storage_plugins = remote_storage_plugins
+    return config
+
+
+def isinstance_mock_adapter(x) -> bool:
+    """Tests MockTestConnectorAdapter as isinstance() not identifying the child class"""
+    return (
+        isinstance(x, ConnectorAdapter)
+        and x.__class__.__name__ == "MockTestConnectorAdapter"
+    )
+
+
+def isinstance_mock_connector(x) -> bool:
+    """Tests MockTestRemoteConnector as isinstance() not identifying the child class"""
+    return (
+        isinstance(x, RemoteConnector)
+        and x.__class__.__name__ == "MockTestRemoteConnector"
+    )
+
+
+def isinstance_mock_instrumented_connector(x) -> bool:
+    """Tests InstrumentedRemoteConnector as isinstance() not identifying the child
+    class"""
+    return (
+        isinstance(x, RemoteConnector)
+        and x.__class__.__name__ == "InstrumentedRemoteConnector"
+    )
+
+
+class TestConnectorPluginLauncher:
+    """Test cases for connector plugin launcher functionality."""
+
+    @pytest.fixture
+    def async_loop(self):
+        """Create an async event loop for testing."""
+        loop = asyncio.new_event_loop()
+        yield loop
+        loop.close()
+
+    def test_remote_storage_plugin_adapter_is_loaded(self, async_loop):
+        """
+        Test that a connector adapter plugin is properly loaded via ConnectorManager.
+        """
+        config = create_test_config(
+            extra_config=MOCK_CONNECTOR_EXTRA_CONFIG,
+            remote_storage_plugins=MOCK_CONNECTOR_REMOTE_STORAGE_PLUGINS,
+        )
+
+        # Create ConnectorManager with the mock connector URL
+        manager = ConnectorManager(
+            url="mockplugin://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Verify the mock adapter is loaded
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 1, (
+            f"Expected 1 MockTestConnectorAdapter, got: {len(mock_adapters)}"
+        )
+
+        # Verify the adapter can parse the URL
+        mock_adapter = mock_adapters[0]
+        assert mock_adapter.can_parse("mockplugin://localhost:1234"), (
+            "Expected adapter to be able to parse 'mockplugin://' URLs"
+        )
+
+    def test_remote_storage_plugin_creates_connector(self, async_loop):
+        """
+        Test that ConnectorManager creates a connector using the plugin adapter.
+        """
+        config = create_test_config(
+            extra_config=MOCK_CONNECTOR_EXTRA_CONFIG,
+            remote_storage_plugins=MOCK_CONNECTOR_REMOTE_STORAGE_PLUGINS,
+        )
+
+        url = "mockplugin://localhost:1234"
+
+        # Create ConnectorManager and get the connector
+        manager = ConnectorManager(
+            url=url,
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        connector = manager.create_connector()
+
+        # Verify a connector was created
+        assert connector is not None, "Expected a connector to be created"
+        assert isinstance_mock_connector(connector), (
+            "Expected a MockTestRemoteConnector connector to be created"
+        )
+
+    def test_remote_storage_plugin_via_create_connector_function(self, async_loop):
+        """
+        Test that CreateConnector function properly loads and uses connector plugins.
+        """
+        config = create_test_config(
+            extra_config=MOCK_CONNECTOR_EXTRA_CONFIG,
+            remote_storage_plugins=MOCK_CONNECTOR_REMOTE_STORAGE_PLUGINS,
+        )
+
+        # Create connector using the CreateConnector function
+        connector = CreateConnector(
+            url="mockplugin://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Verify a connector was created (wrapped in InstrumentedRemoteConnector)
+        assert connector is not None, "Expected a connector to be created"
+        assert isinstance_mock_instrumented_connector(connector), (
+            "Expected a InstrumentedRemoteConnector connector to be created"
+        )
+
+    def test_remote_storage_plugin_without_remote_storage_plugins_config(
+        self, async_loop
+    ):
+        """
+        Test that no connector plugin is loaded when remote_storage_plugins
+        is not configured.
+        """
+        # Configure extra_config but don't set remote_storage_plugins
+        config = create_test_config(
+            extra_config=MOCK_CONNECTOR_EXTRA_CONFIG,
+            remote_storage_plugins=None,
+        )
+
+        manager = ConnectorManager(
+            url="mockplugin://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Verify no MockTestConnectorAdapter is loaded
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 0, (
+            f"Expected 0 MockTestConnectorAdapter, got: {len(mock_adapters)}"
+        )
+
+    def test_remote_storage_plugin_with_invalid_module_path(self, async_loop):
+        """
+        Test that invalid module path is handled gracefully.
+        """
+        extra_config = {
+            "remote_storage_plugin.invalid_connector.module_path": "nonexistent.module.path",  # noqa: E501
+            "remote_storage_plugin.invalid_connector.class_name": "NonexistentClass",
+        }
+        remote_storage_plugins = ["invalid_connector"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            remote_storage_plugins=remote_storage_plugins,
+        )
+
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Invalid connector adapter should not be loaded
+        # (only builtin adapters should be present)
+        adapter_class_names = [type(a).__name__ for a in manager.adapters]
+        assert "NonexistentClass" not in adapter_class_names, (
+            f"Expected 'NonexistentClass' not in adapters, got: {adapter_class_names}"
+        )
+
+    def test_remote_storage_plugin_with_invalid_class_name(self, async_loop):
+        """
+        Test that invalid class name is handled gracefully.
+        """
+        extra_config = {
+            "remote_storage_plugin.invalid_connector.module_path": (
+                "tests.v1.storage_backend.test_remote_storage_plugin"
+            ),
+            "remote_storage_plugin.invalid_connector.class_name": "NonexistentClass",
+        }
+        remote_storage_plugins = ["invalid_connector"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            remote_storage_plugins=remote_storage_plugins,
+        )
+
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Invalid connector adapter should not be loaded
+        adapter_class_names = [type(a).__name__ for a in manager.adapters]
+        assert "NonexistentClass" not in adapter_class_names, (
+            f"Expected 'NonexistentClass' not in adapters, got: {adapter_class_names}"
+        )
+
+    def test_remote_storage_plugin_with_non_connector_adapter_class(self, async_loop):
+        """
+        Test that classes not implementing ConnectorAdapter are rejected.
+        """
+        extra_config = {
+            "remote_storage_plugin.not_adapter.module_path": (
+                "tests.v1.storage_backend.test_remote_storage_plugin"
+            ),
+            "remote_storage_plugin.not_adapter.class_name": "NotAConnectorAdapter",
+        }
+        remote_storage_plugins = ["not_adapter"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            remote_storage_plugins=remote_storage_plugins,
+        )
+
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Non-ConnectorAdapter class should not be loaded
+        adapter_class_names = [type(a).__name__ for a in manager.adapters]
+        assert "NotAConnectorAdapter" not in adapter_class_names, (
+            f"Expected 'NotAConnectorAdapter' not in adapters, "
+            f"got: {adapter_class_names}"
+        )
+
+    def test_remote_storage_plugin_with_missing_module_path(self, async_loop):
+        """
+        Test that missing module_path in extra_config is handled gracefully.
+        """
+        extra_config = {
+            # Missing module_path
+            "remote_storage_plugin.missing_path.class_name": "MockTestConnectorAdapter",
+        }
+        remote_storage_plugins = ["missing_path"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            remote_storage_plugins=remote_storage_plugins,
+        )
+
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Adapter with missing module_path should not be loaded
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 0, (
+            f"Expected 0 MockTestConnectorAdapter, got: {len(mock_adapters)}"
+        )
+
+    def test_remote_storage_plugin_with_missing_class_name(self, async_loop):
+        """
+        Test that missing class_name in extra_config is handled gracefully.
+        """
+        extra_config = {
+            "remote_storage_plugin.missing_class.module_path": (
+                "tests.v1.storage_backend.test_remote_storage_plugin"
+            ),
+            # Missing class_name
+        }
+        remote_storage_plugins = ["missing_class"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            remote_storage_plugins=remote_storage_plugins,
+        )
+
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Adapter with missing class_name should not be loaded
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 0, (
+            f"Expected 0 MockTestConnectorAdapter, got: {len(mock_adapters)}"
+        )
+
+    def test_remote_storage_plugin_with_missing_extra_config(self, async_loop):
+        """
+        Test that missing extra_config is handled gracefully.
+        """
+        config = create_test_config(
+            extra_config=None,  # No extra_config
+            remote_storage_plugins=["some_connector"],
+        )
+
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # No plugin adapter should be loaded when extra_config is None
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 0, (
+            f"Expected 0 MockTestConnectorAdapter, got: {len(mock_adapters)}"
+        )
+
+    def test_remote_storage_plugin_with_none_config(self, async_loop):
+        """
+        Test that None config is handled gracefully.
+        """
+        # Should not raise an exception
+        manager = ConnectorManager(
+            url="lm://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=None,  # No config at all
+            metadata=None,
+        )
+
+        # Only builtin adapters should be loaded
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 0, (
+            f"Expected 0 MockTestConnectorAdapter, got: {len(mock_adapters)}"
+        )
+
+    def test_remote_storage_plugin_multiple_plugins(self, async_loop):
+        """
+        Test that multiple connector plugins can be loaded simultaneously.
+        """
+        extra_config = {
+            "remote_storage_plugin.mock_connector_1.module_path": (
+                "tests.v1.storage_backend.test_remote_storage_plugin"
+            ),
+            "remote_storage_plugin.mock_connector_1.class_name": "MockTestConnectorAdapter",  # noqa: E501
+            "remote_storage_plugin.mock_connector_2.module_path": (
+                "tests.v1.storage_backend.test_remote_storage_plugin"
+            ),
+            "remote_storage_plugin.mock_connector_2.class_name": "MockTestConnectorAdapter",  # noqa: E501
+        }
+        remote_storage_plugins = ["mock_connector_1", "mock_connector_2"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            remote_storage_plugins=remote_storage_plugins,
+        )
+
+        manager = ConnectorManager(
+            url="mockplugin://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Verify both adapters are loaded
+        mock_adapters = [a for a in manager.adapters if isinstance_mock_adapter(a)]
+        assert len(mock_adapters) == 2, (
+            f"Expected 2 MockTestConnectorAdapter instances, got: {len(mock_adapters)}"
+        )
+
+    def test_remote_storage_plugin_no_matching_url_raises_error(self, async_loop):
+        """
+        Test that ValueError is raised when no adapter matches the URL.
+        """
+        config = create_test_config(
+            extra_config=MOCK_CONNECTOR_EXTRA_CONFIG,
+            remote_storage_plugins=MOCK_CONNECTOR_REMOTE_STORAGE_PLUGINS,
+        )
+
+        # Create ConnectorManager and get the connector
+        manager = ConnectorManager(
+            url="unknownscheme://localhost:1234",
+            loop=async_loop,
+            local_cpu_backend=None,
+            config=config,
+            metadata=None,
+        )
+
+        # Should raise ValueError when no adapter matches
+        with pytest.raises(ValueError, match="No adapter found for URL"):
+            manager.create_connector()
diff --git a/tests/v1/storage_backend/test_resp_connector.py b/tests/v1/storage_backend/test_resp_connector.py
new file mode 100644
index 0000000..25256f3
--- /dev/null
+++ b/tests/v1/storage_backend/test_resp_connector.py
@@ -0,0 +1,477 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for RESP connector integration.
+
+These tests verify the RESP protocol client implementation, including:
+- Basic operations (exists, get, set)
+- Batch operations (batch_get, batch_set, batch_exists)
+- Error handling
+- Different chunk sizes per operation
+"""
+
+# Standard
+from unittest.mock import patch
+import asyncio
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.connector import CreateConnector
+
+# Local
+from ...conftest import MockRESPClient
+from ..utils import (
+    check_mem_obj_equal,
+    close_asyncio_loop,
+    dumb_cache_engine_key,
+    init_asyncio_loop,
+)
+
+
+@pytest.fixture(autouse=True)
+def mock_resp_client():
+    """Use in-memory MockRESPClient so tests never hit real Redis (no 6379)."""
+    with patch(
+        "lmcache.v1.storage_backend.connector.redis_connector.RESPClient",
+        MockRESPClient,
+    ):
+        yield
+
+
+def _get_metadata(use_mla: bool = False):
+    """Helper to create test metadata."""
+    kv_shape = (32, 1 if use_mla else 2, 256, 1 if use_mla else 8, 128)
+    dtype = torch.bfloat16
+    metadata = LMCacheMetadata(
+        model_name="test-model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=dtype,
+        kv_shape=kv_shape,
+        use_mla=use_mla,
+    )
+    return metadata
+
+
+def _create_local_cpu_backend(memory_allocator, use_mla=False, config=None):
+    """Helper to create a local CPU backend for testing."""
+    if config is None:
+        config = LMCacheEngineConfig.from_defaults(
+            extra_config={
+                "save_chunk_meta": False,  # RESP requires this
+                "resp_num_threads": 4,
+            }
+        )
+    metadata = _get_metadata(use_mla)
+    return LocalCPUBackend(
+        config=config, metadata=metadata, memory_allocator=memory_allocator
+    )
+
+
+@pytest.fixture
+def resp_url():
+    """RESP URL for testing; mock only, no real port (no 6379)."""
+    return "resp://mock.local:0"
+
+
+@pytest.fixture
+def resp_config():
+    """Create a config for RESP connector testing."""
+    return LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "save_chunk_meta": False,  # RESP requires this
+            "resp_num_threads": 4,
+        }
+    )
+
+
+@pytest.fixture
+def local_backend():
+    """Create a local CPU backend for testing."""
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)  # 1GB
+    backend = _create_local_cpu_backend(memory_allocator, use_mla=False)
+    yield backend
+    backend.close()
+
+
+def test_resp_connector_basic_operations(
+    resp_url, local_backend, resp_config, autorelease_v1
+):
+    """Test basic RESP operations: exists, put, get."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, resp_config)
+        )
+
+        random_key = dumb_cache_engine_key()
+
+        # Test 1: Key doesn't exist initially
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(random_key), async_loop
+        )
+        assert not future.result(), "Key should not exist initially"
+
+        # Test 2: Create and store test data
+        num_tokens = 256  # Full chunk
+        mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+        dtype = torch.bfloat16
+        memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+        memory_obj.ref_count_up()
+
+        # Fill with deterministic test data
+        torch.manual_seed(42)
+        test_tensor = torch.randint(
+            0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+        )
+        memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+        # Test 3: Put data
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(random_key, memory_obj), async_loop
+        )
+        future.result()
+
+        # Test 4: Key exists after put
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(random_key), async_loop
+        )
+        assert future.result(), "Key should exist after put"
+        assert memory_obj.get_ref_count() == 1
+
+        # Test 5: Get and verify data
+        future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+        retrieved_memory_obj = future.result()
+
+        check_mem_obj_equal([retrieved_memory_obj], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_resp_connector_batch_operations(
+    resp_url, local_backend, resp_config, autorelease_v1
+):
+    """Test RESP batch operations: batch_put, batch_get, batch_exists."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, resp_config)
+        )
+
+        # Create multiple keys (unique chunk_hash per key so each put/get pair matches)
+        num_keys = 10
+        keys = [dumb_cache_engine_key(i) for i in range(num_keys)]
+
+        # Test 1: Batch exists - all should be False initially
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_async_contains("test_lookup", keys), async_loop
+        )
+        count = future.result()
+        assert count == 0, "No keys should exist initially"
+
+        # Test 2: Create memory objects
+        num_tokens = 256  # Full chunk
+        mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+        dtype = torch.bfloat16
+        memory_objs = []
+
+        for i in range(num_keys):
+            memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+            memory_obj.ref_count_up()
+
+            # Fill with unique deterministic data
+            torch.manual_seed(42 + i)
+            test_tensor = torch.randint(
+                0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+            )
+            memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+            memory_objs.append(memory_obj)
+
+        # Test 3: Batch put
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys, memory_objs), async_loop
+        )
+        future.result()
+
+        # Test 4: Batch exists - all should be True now
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_async_contains("test_lookup", keys), async_loop
+        )
+        count = future.result()
+        assert count == num_keys, "All keys should exist after batch_put"
+
+        # Test 5: Batch get and verify
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get(keys), async_loop
+        )
+        retrieved_objs = future.result()
+
+        assert len(retrieved_objs) == num_keys
+        check_mem_obj_equal(retrieved_objs, memory_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_resp_connector_different_chunk_sizes(resp_url, autorelease_v1):
+    """Test that different operations can use different chunk sizes."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    # Create backend with 4MB chunks
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "save_chunk_meta": False,
+            "resp_num_threads": 4,
+        }
+    )
+
+    # Metadata with larger chunks
+    # (chunk_size must match kv_shape token dim for get_shapes())
+    kv_shape = (32, 2, 512, 8, 128)  # Larger chunk size
+    dtype = torch.bfloat16
+    metadata = LMCacheMetadata(
+        model_name="test-model-large",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=dtype,
+        kv_shape=kv_shape,
+        use_mla=False,
+        chunk_size=512,
+    )
+    local_backend = LocalCPUBackend(
+        config=config, metadata=metadata, memory_allocator=memory_allocator
+    )
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, config)
+        )
+
+        # Test with larger chunk
+        key1 = dumb_cache_engine_key()
+        mem_obj_shape = torch.Size([2, 32, 512, 1024])
+        memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+        memory_obj.ref_count_up()
+
+        torch.manual_seed(100)
+        test_tensor = torch.randint(
+            0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+        )
+        memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+        # Put and get with larger chunk
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key1, memory_obj), async_loop
+        )
+        future.result()
+
+        future = asyncio.run_coroutine_threadsafe(connector.get(key1), async_loop)
+        retrieved_obj = future.result()
+
+        check_mem_obj_equal([retrieved_obj], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+        local_backend.close()
+
+
+def test_resp_connector_nonexistent_key(
+    resp_url, local_backend, resp_config, autorelease_v1
+):
+    """Test getting a non-existent key returns None."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, resp_config)
+        )
+
+        nonexistent_key = dumb_cache_engine_key()
+
+        # Test exists returns False
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(nonexistent_key), async_loop
+        )
+        assert not future.result()
+
+        # Test get returns None (RESP protocol should handle this gracefully)
+        # Note: This might throw an error depending on how RESP handles missing keys
+        future = asyncio.run_coroutine_threadsafe(
+            connector.get(nonexistent_key), async_loop
+        )
+
+        try:
+            result = future.result()
+            assert result is None, "Getting non-existent key should return None"
+        except Exception:
+            # RESP might throw an error for missing keys, which is also acceptable
+            pass
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_resp_connector_sequential_operations(
+    resp_url, local_backend, resp_config, autorelease_v1
+):
+    """Test multiple sequential put/get operations work correctly."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, resp_config)
+        )
+
+        # Perform 5 sequential put/get cycles
+        num_ops = 5
+        for i in range(num_ops):
+            key = dumb_cache_engine_key()
+
+            # Create unique data
+            num_tokens = 256
+            mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+            dtype = torch.bfloat16
+            memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+            memory_obj.ref_count_up()
+
+            torch.manual_seed(1000 + i)
+            test_tensor = torch.randint(
+                0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+            )
+            memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+            # Put
+            future = asyncio.run_coroutine_threadsafe(
+                connector.put(key, memory_obj), async_loop
+            )
+            future.result()
+
+            # Get and verify
+            future = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+            retrieved_obj = future.result()
+
+            check_mem_obj_equal([retrieved_obj], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_resp_connector_concurrent_operations(
+    resp_url, local_backend, resp_config, autorelease_v1
+):
+    """Test that concurrent operations are handled correctly."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, resp_config)
+        )
+
+        # Submit multiple operations concurrently
+        # (unique keys so each get matches its put)
+        num_concurrent = 5
+        keys = [dumb_cache_engine_key(i) for i in range(num_concurrent)]
+        memory_objs = []
+
+        num_tokens = 256
+        mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+        dtype = torch.bfloat16
+
+        # Create and submit all puts concurrently
+        put_futures = []
+        for i, key in enumerate(keys):
+            memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+            memory_obj.ref_count_up()
+
+            torch.manual_seed(2000 + i)
+            test_tensor = torch.randint(
+                0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+            )
+            memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+            memory_objs.append(memory_obj)
+
+            future = asyncio.run_coroutine_threadsafe(
+                connector.put(key, memory_obj), async_loop
+            )
+            put_futures.append(future)
+
+        # Wait for all puts to complete
+        for future in put_futures:
+            future.result()
+
+        # Submit all gets concurrently
+        get_futures = []
+        for key in keys:
+            future = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+            get_futures.append(future)
+
+        # Verify all gets
+        retrieved_objs = [future.result() for future in get_futures]
+        check_mem_obj_equal(retrieved_objs, memory_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+@pytest.mark.parametrize("num_threads", [1, 4, 8, 16])
+def test_resp_connector_thread_scaling(resp_url, num_threads, autorelease_v1):
+    """Test RESP connector with different numbers of worker threads."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "save_chunk_meta": False,
+            "resp_num_threads": num_threads,
+        }
+    )
+    local_backend = _create_local_cpu_backend(memory_allocator, False, config)
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(resp_url, async_loop, local_backend, config)
+        )
+
+        # Test basic operation with different thread counts
+        key = dumb_cache_engine_key()
+        num_tokens = 256
+        mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+        dtype = torch.bfloat16
+        memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+        memory_obj.ref_count_up()
+
+        torch.manual_seed(3000)
+        test_tensor = torch.randint(
+            0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+        )
+        memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+        # Put
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key, memory_obj), async_loop
+        )
+        future.result()
+
+        # Get and verify
+        future = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+        retrieved_obj = future.result()
+
+        check_mem_obj_equal([retrieved_obj], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+        local_backend.close()
diff --git a/tests/v1/storage_backend/test_rust_raw_block_backend.py b/tests/v1/storage_backend/test_rust_raw_block_backend.py
new file mode 100644
index 0000000..4dd66c3
--- /dev/null
+++ b/tests/v1/storage_backend/test_rust_raw_block_backend.py
@@ -0,0 +1,2448 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Future
+from __future__ import annotations
+
+# Standard
+from concurrent.futures import Future
+from typing import Any
+from unittest.mock import MagicMock, patch
+import asyncio
+import os
+import struct
+import sys
+import tempfile
+import threading
+import time
+import types
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.plugins.rust_raw_block_backend import (
+    _DEFAULT_META_MAGIC,
+    _DEFAULT_META_VERSION,
+    RustRawBlockBackend,
+)
+from lmcache.v1.storage_backend.raw_block import (
+    RawBlockCore,
+    RawBlockCoreConfig,
+    RawBlockKeySpec,
+    RawBlockPutManyResult,
+)
+
+
+def _has_ext() -> bool:
+    try:
+        # Third Party
+        import lmcache_rust_raw_block_io  # noqa: F401
+
+        return True
+    except Exception:
+        return False
+
+
+class _FakeRawBlockDevice:
+    def __init__(self, path: str, *, size_bytes: int, **kwargs):
+        del path, kwargs
+        self._data = bytearray(size_bytes)
+
+    def size_bytes(self):
+        return len(self._data)
+
+    def pread_into(self, offset, out, payload_len, total_len=None):
+        del total_len
+        out[:payload_len] = self._data[offset : offset + payload_len]
+
+    def pwrite_from_buffer(self, offset, data, payload_len=None, total_len=None):
+        del total_len
+        length = len(data) if payload_len is None else payload_len
+        self._data[offset : offset + length] = bytes(memoryview(data)[:length])
+
+    def close(self):
+        return None
+
+
+def _install_fake_raw_block_device(monkeypatch, *, size_bytes: int = 64 * 1024):
+    def create_fake_device(path: str, **kwargs):
+        return _FakeRawBlockDevice(path, size_bytes=size_bytes, **kwargs)
+
+    monkeypatch.setitem(
+        sys.modules,
+        "lmcache_rust_raw_block_io",
+        types.SimpleNamespace(RawBlockDevice=create_fake_device),
+    )
+
+
+def _make_raw_block_core(*, use_odirect: bool = False) -> RawBlockCore:
+    return RawBlockCore(
+        RawBlockCoreConfig(
+            device_path="/tmp/raw-block-boundary-test",
+            capacity_bytes=64 * 1024,
+            block_align=4096,
+            header_bytes=4096,
+            slot_bytes=8192,
+            use_odirect=use_odirect,
+            enable_zero_copy=True,
+            meta_total_bytes=16 * 1024,
+            meta_magic=b"LMCIDX01",
+            meta_version=1,
+            meta_checkpoint_interval_sec=60,
+            meta_idle_quiet_ms=100,
+            meta_enable_periodic=False,
+            load_checkpoint_on_init=True,
+            meta_verify_on_load=True,
+            io_engine="posix",
+            iouring_queue_depth=256,
+        ),
+        key_namespace="object",
+    )
+
+
+def _make_byte_obj(size: int) -> TensorMemoryObj:
+    raw_data = torch.empty(size, dtype=torch.uint8)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([size]),
+        dtype=torch.uint8,
+        address=0,
+        phy_size=size,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+    return TensorMemoryObj(raw_data, metadata, parent_allocator=None)
+
+
+def test_raw_block_core_passes_io_engine_options_to_rust_binding(monkeypatch):
+    calls: list[dict[str, object]] = []
+
+    class FakeRawBlockDevice:
+        def __init__(self, path: str, **kwargs):
+            calls.append({"path": path, **kwargs})
+
+        def size_bytes(self):
+            return 2 * 1024 * 1024
+
+        def pread_into(self, offset, out, payload_len, total_len=None):
+            del offset, total_len
+            out[:payload_len] = b"\x00" * payload_len
+
+        def pwrite_from_buffer(self, offset, data, payload_len=None, total_len=None):
+            del offset, data, payload_len, total_len
+
+        def close(self):
+            return None
+
+    monkeypatch.setitem(
+        sys.modules,
+        "lmcache_rust_raw_block_io",
+        types.SimpleNamespace(RawBlockDevice=FakeRawBlockDevice),
+    )
+
+    core = RawBlockCore(
+        RawBlockCoreConfig(
+            device_path="/tmp/raw-block-engine-test",
+            capacity_bytes=0,
+            block_align=4096,
+            header_bytes=4096,
+            slot_bytes=8192,
+            use_odirect=False,
+            enable_zero_copy=True,
+            meta_total_bytes=16 * 1024,
+            meta_magic=b"LMCIDX01",
+            meta_version=1,
+            meta_checkpoint_interval_sec=60,
+            meta_idle_quiet_ms=100,
+            meta_enable_periodic=False,
+            load_checkpoint_on_init=True,
+            meta_verify_on_load=True,
+            io_engine="io_uring",
+            iouring_queue_depth=512,
+        ),
+        key_namespace="legacy",
+    )
+    try:
+        assert calls == [
+            {
+                "path": "/tmp/raw-block-engine-test",
+                "writable": True,
+                "use_odirect": False,
+                "alignment": 4096,
+                "io_engine": "io_uring",
+                "use_uring_cmd": False,
+                "iouring_queue_depth": 512,
+            }
+        ]
+    finally:
+        core.close()
+
+
+def test_raw_block_core_non_odirect_rejects_payload_over_slot_capacity(monkeypatch):
+    _install_fake_raw_block_device(monkeypatch)
+    core = _make_raw_block_core(use_odirect=False)
+    try:
+        payload_capacity = core.slot_bytes - core.header_bytes
+        exact_key = RawBlockKeySpec(encoded="exact", slot_identity=1)
+        too_large_key = RawBlockKeySpec(encoded="too-large", slot_identity=2)
+
+        exact = core.put_many([exact_key], [_make_byte_obj(payload_capacity)])
+        assert exact.results == [True]
+        assert core.contains_key("exact") is True
+
+        too_large = core.put_many(
+            [too_large_key],
+            [_make_byte_obj(payload_capacity + 1)],
+        )
+        assert too_large.results == [False]
+        assert core.contains_key("too-large") is False
+    finally:
+        core.close()
+
+
+def test_raw_block_core_odirect_prepare_payload_boundaries(monkeypatch):
+    _install_fake_raw_block_device(monkeypatch)
+    core = _make_raw_block_core(use_odirect=True)
+    try:
+        payload_capacity = core.slot_bytes - core.header_bytes
+
+        _, payload_len, total_len = core._prepare_write_payload(
+            _make_byte_obj(payload_capacity)
+        )
+        assert payload_len == payload_capacity
+        assert total_len == payload_capacity
+
+        _, payload_len, total_len = core._prepare_write_payload(
+            _make_byte_obj(payload_capacity - 1)
+        )
+        assert payload_len == payload_capacity - 1
+        assert total_len == payload_capacity
+
+        with pytest.raises(RuntimeError, match="slot capacity"):
+            core._prepare_write_payload(_make_byte_obj(payload_capacity + 1))
+    finally:
+        core.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+@pytest.mark.parametrize("io_engine", ["posix", "io_uring"])
+def test_raw_block_device_all_io_engines_roundtrip_on_tmp_file(io_engine):
+    # Third Party
+    from lmcache_rust_raw_block_io import RawBlockDevice
+
+    with tempfile.TemporaryDirectory(dir="/tmp") as td:
+        dev_path = os.path.join(td, f"raw-block-{io_engine}.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(1024 * 1024)
+
+        dev = RawBlockDevice(
+            dev_path,
+            writable=True,
+            use_odirect=False,
+            alignment=4096,
+            io_engine=io_engine,
+        )
+
+        try:
+            payload = bytearray(f"raw-block-{io_engine}".encode())
+            out = bytearray(len(payload))
+            dev.pwrite_from_buffer(4096, payload, len(payload), len(payload))
+            dev.pread_into(4096, out, len(out), len(out))
+            assert out == payload
+        finally:
+            dev.close()
+
+
+@pytest.fixture
+def loop_in_thread():
+    loop = asyncio.new_event_loop()
+    t = threading.Thread(target=loop.run_forever, name="test-loop", daemon=True)
+    t.start()
+    try:
+        yield loop
+    finally:
+        loop.call_soon_threadsafe(loop.stop)
+        t.join(timeout=5)
+        loop.close()
+
+
+def _run_batched_get_prefix_stop(
+    memory_allocator,
+    loop_in_thread,
+    *,
+    async_get: bool,
+) -> None:
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_batched_get",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = AdHocMemoryAllocator(device="cpu")
+            key1 = CacheEngineKey("test_model", 1, 0, 1001, torch.bfloat16)
+            key_miss = CacheEngineKey("test_model", 1, 0, 1002, torch.bfloat16)
+            key3 = CacheEngineKey("test_model", 1, 0, 1003, torch.bfloat16)
+
+            obj1 = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            obj3 = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj1 is not None and obj1.tensor is not None
+            assert obj3 is not None and obj3.tensor is not None
+            obj1.tensor.fill_(1)
+            obj3.tensor.fill_(3)
+            expected1 = bytes(obj1.byte_array)
+            expected3 = bytes(obj3.byte_array)
+
+            for key, obj in ((key1, obj1), (key3, obj3)):
+                futs = backend.batched_submit_put_task([key], [obj])
+                assert futs is not None
+                futs[0].result(timeout=10)
+                obj.ref_count_down()
+
+            if async_get:
+                future = asyncio.run_coroutine_threadsafe(
+                    backend.batched_get_non_blocking(
+                        "lookup-rawblock", [key1, key_miss, key3]
+                    ),
+                    loop_in_thread,
+                )
+                async_results = future.result(timeout=10)
+                assert len(async_results) == 1
+                assert bytes(async_results[0].byte_array) == expected1
+                async_results[0].ref_count_down()
+            else:
+                blocking_results = backend.batched_get_blocking([key1, key_miss, key3])
+                assert len(blocking_results) == 3
+                assert blocking_results[0] is not None
+                assert bytes(blocking_results[0].byte_array) == expected1
+                assert blocking_results[1] is None
+                assert blocking_results[2] is None
+                blocking_results[0].ref_count_down()
+
+            out3 = backend.get_blocking(key3)
+            assert out3 is not None
+            assert bytes(out3.byte_array) == expected3
+            out3.ref_count_down()
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_put_get_roundtrip(memory_allocator, loop_in_thread):
+    """Test basic put/get roundtrip with RustRawBlockBackend."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            key = CacheEngineKey("test_model", 1, 0, 12345, torch.bfloat16)
+            allocator = AdHocMemoryAllocator(device="cpu")
+            obj = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None
+            assert obj.tensor is not None
+            obj.tensor.fill_(7)
+            expected = bytes(obj.byte_array)
+
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+            assert isinstance(futs[0], Future)
+            futs[0].result(timeout=10)
+
+            out = backend.get_blocking(key)
+            assert out is not None
+            assert bytes(out.byte_array) == expected
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_blocking_prefix_stop(
+    memory_allocator, loop_in_thread
+):
+    """Batched blocking get should stop at the first miss and preserve order."""
+    _run_batched_get_prefix_stop(memory_allocator, loop_in_thread, async_get=False)
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_non_blocking_prefix_stop(
+    memory_allocator, loop_in_thread
+):
+    """Async batched get should return only the successful prefix."""
+    _run_batched_get_prefix_stop(memory_allocator, loop_in_thread, async_get=True)
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_pin_and_contains_are_idempotent(
+    memory_allocator, loop_in_thread
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_pin_idempotent",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            key = CacheEngineKey("test_model", 1, 0, 4242, torch.bfloat16)
+            allocator = AdHocMemoryAllocator(device="cpu")
+            obj = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None
+
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+            futs[0].result(timeout=10)
+            obj.ref_count_down()
+
+            encoded_key = key.to_string()
+            assert backend.contains(key, pin=True) is True
+            assert backend.lock_refcount(encoded_key) == 1
+            assert backend.contains(key, pin=True) is True
+            assert backend.lock_refcount(encoded_key) == 1
+            assert backend.pin(key) is True
+            assert backend.lock_refcount(encoded_key) == 1
+
+            assert backend.unpin(key) is True
+            assert backend.lock_refcount(encoded_key) == 0
+            assert backend.unpin(key) is True
+            assert backend.lock_refcount(encoded_key) == 0
+
+            barrier = threading.Barrier(8)
+            pin_results: list[bool] = []
+            result_lock = threading.Lock()
+
+            def pin_concurrently() -> None:
+                barrier.wait(timeout=5)
+                pinned = backend.pin(key)
+                with result_lock:
+                    pin_results.append(pinned)
+
+            threads = [
+                threading.Thread(target=pin_concurrently, daemon=True) for _ in range(8)
+            ]
+            for thread in threads:
+                thread.start()
+            for thread in threads:
+                thread.join(timeout=5)
+
+            assert pin_results == [True] * 8
+            assert backend.lock_refcount(encoded_key) == 1
+
+            assert backend.unpin(key) is True
+            assert backend.lock_refcount(encoded_key) == 0
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_close_is_thread_safe(memory_allocator, loop_in_thread):
+    """Concurrent close calls should not double-clean raw-block resources."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_concurrent_close",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        errors: list[BaseException] = []
+        errors_lock = threading.Lock()
+
+        def close_backend() -> None:
+            try:
+                backend.close()
+            except BaseException as e:
+                with errors_lock:
+                    errors.append(e)
+
+        threads = [threading.Thread(target=close_backend) for _ in range(8)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join(timeout=5)
+
+        assert errors == []
+        backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_resets_inflight_on_rawdev_error(
+    memory_allocator, loop_in_thread
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_rawdev_error",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = AdHocMemoryAllocator(device="cpu")
+            key = CacheEngineKey("test_model", 1, 0, 3001, torch.bfloat16)
+            obj = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None and obj.tensor is not None
+            obj.tensor.fill_(31)
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+            futs[0].result(timeout=10)
+            obj.ref_count_down()
+
+            with patch.object(
+                backend._core, "_rawdev", side_effect=RuntimeError("boom")
+            ):
+                with pytest.raises(RuntimeError, match="boom"):
+                    backend.get_blocking(key)
+            assert backend.inflight_io_count() == 0
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_handles_allocator_exhaustion(
+    memory_allocator, loop_in_thread
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_allocator_exhaustion",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = AdHocMemoryAllocator(device="cpu")
+            key = CacheEngineKey("test_model", 1, 0, 3002, torch.bfloat16)
+            obj = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None and obj.tensor is not None
+            obj.tensor.fill_(32)
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+            futs[0].result(timeout=10)
+            obj.ref_count_down()
+
+            with patch.object(local_cpu, "allocate", return_value=None):
+                assert backend.get_blocking(key) is None
+                assert backend.batched_get_blocking([key]) == [None]
+            assert backend.inflight_io_count() == 0
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_releases_allocation_on_read_error(
+    memory_allocator, loop_in_thread
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_release_failed_get",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = AdHocMemoryAllocator(device="cpu")
+            key = CacheEngineKey("test_model", 1, 0, 3003, torch.bfloat16)
+            obj = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None and obj.tensor is not None
+            obj.tensor.fill_(33)
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+            futs[0].result(timeout=10)
+            obj.ref_count_down()
+
+            leaked_obj = local_cpu.allocate(
+                torch.Size([2, 16, 8, 128]),
+                torch.bfloat16,
+                MemoryFormat.KV_T2D,
+            )
+            assert leaked_obj is not None
+            assert leaked_obj.get_ref_count() == 1
+
+            raw_dev = MagicMock()
+            raw_dev.pread_into.side_effect = OSError("read failed")
+            with patch.object(local_cpu, "allocate", return_value=leaked_obj):
+                with patch.object(backend._core, "_rawdev", return_value=raw_dev):
+                    with pytest.raises(OSError, match="read failed"):
+                        backend.get_blocking(key)
+
+            assert leaked_obj.get_ref_count() == 0
+            assert backend.inflight_io_count() == 0
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_releases_loaded_prefix_on_read_error(
+    memory_allocator, loop_in_thread
+):
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_release_prefix_get",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = AdHocMemoryAllocator(device="cpu")
+            key1 = CacheEngineKey("test_model", 1, 0, 3004, torch.bfloat16)
+            key2 = CacheEngineKey("test_model", 1, 0, 3005, torch.bfloat16)
+            for key, fill in ((key1, 34), (key2, 35)):
+                obj = allocator.allocate(
+                    [torch.Size([2, 16, 8, 128])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None and obj.tensor is not None
+                obj.tensor.fill_(fill)
+                futs = backend.batched_submit_put_task([key], [obj])
+                assert futs is not None
+                futs[0].result(timeout=10)
+                obj.ref_count_down()
+
+            loaded_obj = local_cpu.allocate(
+                torch.Size([2, 16, 8, 128]),
+                torch.bfloat16,
+                MemoryFormat.KV_T2D,
+            )
+            failed_obj = local_cpu.allocate(
+                torch.Size([2, 16, 8, 128]),
+                torch.bfloat16,
+                MemoryFormat.KV_T2D,
+            )
+            assert loaded_obj is not None
+            assert failed_obj is not None
+            assert loaded_obj.get_ref_count() == 1
+            assert failed_obj.get_ref_count() == 1
+
+            raw_dev = MagicMock()
+            raw_dev.pread_into.side_effect = [None, OSError("read failed")]
+            with patch.object(
+                local_cpu, "allocate", side_effect=[loaded_obj, failed_obj]
+            ):
+                with patch.object(backend._core, "_rawdev", return_value=raw_dev):
+                    with pytest.raises(OSError, match="read failed"):
+                        backend.batched_get_blocking([key1, key2])
+
+            assert loaded_obj.get_ref_count() == 0
+            assert failed_obj.get_ref_count() == 0
+            assert backend.inflight_io_count() == 0
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_rejects_when_full(memory_allocator, loop_in_thread):
+    """Test that raw-block writes fail when no slot has been freed."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_evict",
+        )
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.capacity_bytes": 3 * 4 * 1024 * 1024,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.slot_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            alloc = AdHocMemoryAllocator(device="cpu")
+
+            k1 = CacheEngineKey("test_model", 1, 0, 1, torch.bfloat16)
+            k2 = CacheEngineKey("test_model", 1, 0, 2, torch.bfloat16)
+            k3 = CacheEngineKey("test_model", 1, 0, 3, torch.bfloat16)
+
+            o1 = alloc.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            o2 = alloc.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            o3 = alloc.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert o1 and o2 and o3
+            assert (
+                o1.tensor is not None
+                and o2.tensor is not None
+                and o3.tensor is not None
+            )
+            o1.tensor.fill_(1)
+            o2.tensor.fill_(2)
+            o3.tensor.fill_(3)
+
+            f1 = backend.batched_submit_put_task([k1], [o1])[0]
+            f2 = backend.batched_submit_put_task([k2], [o2])[0]
+            f1.result(timeout=10)
+            f2.result(timeout=10)
+
+            assert backend.get_blocking(k1) is not None
+
+            f3 = backend.batched_submit_put_task([k3], [o3])[0]
+            with pytest.raises(RuntimeError, match="Failed to persist raw-block key"):
+                f3.result(timeout=10)
+
+            assert backend.get_blocking(k1) is not None
+            assert backend.get_blocking(k2) is not None
+            assert backend.contains(k3) is False
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_device_checkpoint_roundtrip(
+    memory_allocator, loop_in_thread
+):
+    """Test on-device metadata checkpoint persistence across backend restarts."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        base_cfg = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_manifest",
+        )
+        base_cfg.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=base_cfg,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend1 = RustRawBlockBackend(
+            config=base_cfg,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        alloc = AdHocMemoryAllocator(device="cpu")
+        k1 = CacheEngineKey("test_model", 1, 0, 111, torch.bfloat16)
+        o1 = alloc.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        assert o1 and o1.tensor is not None
+        o1.tensor.fill_(9)
+        expected = bytes(o1.byte_array)
+        try:
+            fut = backend1.batched_submit_put_task([k1], [o1])[0]
+            fut.result(timeout=10)
+        finally:
+            backend1.close()
+
+        # New backend instance should restore index and retrieve
+        backend2 = RustRawBlockBackend(
+            config=base_cfg,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        try:
+            assert backend2.contains(k1)
+            out = backend2.get_blocking(k1)
+            assert out is not None
+            assert bytes(out.byte_array) == expected
+        finally:
+            backend2.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_skips_checkpoint_on_init(
+    memory_allocator, loop_in_thread
+):
+    """Skip on-device metadata checkpoint loading when configured."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_skip_checkpoint",
+        )
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend1 = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        allocator = AdHocMemoryAllocator(device="cpu")
+        key = CacheEngineKey("test_model", 1, 0, 222, torch.bfloat16)
+        obj = allocator.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        assert obj is not None
+        try:
+            fut = backend1.batched_submit_put_task([key], [obj])[0]
+            fut.result(timeout=10)
+        finally:
+            backend1.close()
+
+        config.extra_config["rust_raw_block.load_checkpoint_on_init"] = False
+        with patch.object(
+            RawBlockCore,
+            "_select_latest_checkpoint",
+            side_effect=AssertionError("checkpoint retrieval should be skipped"),
+        ) as mock_select_latest_checkpoint:
+            backend2 = RustRawBlockBackend(
+                config=config,
+                metadata=metadata,
+                local_cpu_backend=local_cpu,
+                loop=loop_in_thread,
+                dst_device="cpu",
+            )
+        try:
+            assert mock_select_latest_checkpoint.call_count == 0
+            assert backend2.contains(key) is False
+        finally:
+            backend2.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_data_offsets_start_after_metadata(
+    memory_allocator, loop_in_thread
+):
+    """Slot allocations must begin after reserved metadata region."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_offsets",
+        )
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 8 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            key = CacheEngineKey("test_model", 1, 0, 777, torch.bfloat16)
+            alloc = AdHocMemoryAllocator(device="cpu")
+            obj = alloc.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj is not None
+            futs = backend.batched_submit_put_task([key], [obj])
+            assert futs is not None
+            futs[0].result(timeout=10)
+
+            entry_offset = backend.entry_offset(key)
+            assert entry_offset is not None
+            assert entry_offset >= 8 * 1024 * 1024
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_ignores_torn_newer_checkpoint(
+    memory_allocator, loop_in_thread
+):
+    """
+    If a newer checkpoint copy is torn, loader falls back to the older valid copy.
+    """
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        base_cfg = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_torn_checkpoint",
+        )
+        meta_total = 4 * 1024 * 1024
+        align = 4096
+        base_cfg.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": align,
+            "rust_raw_block.header_bytes": align,
+            "rust_raw_block.meta_total_bytes": meta_total,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=base_cfg,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+
+        backend1 = RustRawBlockBackend(
+            config=base_cfg,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        alloc = AdHocMemoryAllocator(device="cpu")
+        key = CacheEngineKey("test_model", 1, 0, 888, torch.bfloat16)
+        obj = alloc.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        assert obj is not None and obj.tensor is not None
+        obj.tensor.fill_(11)
+        expected = bytes(obj.byte_array)
+        try:
+            fut = backend1.batched_submit_put_task([key], [obj])[0]
+            fut.result(timeout=10)
+        finally:
+            torn_offset = backend1.metadata_container_offsets()[1]
+            backend1.close()
+
+        # Corrupt the newer checkpoint copy with invalid CRC.
+        # Header format: <8sIQQI (magic, version, seq, payload_len, crc).
+        header = struct.pack(
+            "<8sIQQI", _DEFAULT_META_MAGIC, _DEFAULT_META_VERSION, 9999, 2, 0
+        )
+        padded_header = header + bytes(align - len(header))
+        with open(dev_path, "r+b") as f:
+            f.seek(torn_offset + align)
+            f.write(b"{}")
+            f.seek(torn_offset)
+            f.write(padded_header)
+
+        backend2 = RustRawBlockBackend(
+            config=base_cfg,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        try:
+            assert backend2.contains(key)
+            out = backend2.get_blocking(key)
+            assert out is not None
+            assert bytes(out.byte_array) == expected
+        finally:
+            backend2.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_skips_invalid_checkpoint_entries(
+    memory_allocator, loop_in_thread
+):
+    """Checkpoint restore should reject invalid offset/size metadata entries."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        base_cfg = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_invalid_checkpoint",
+        )
+        base_cfg.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+            "rust_raw_block.meta_verify_on_load": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=base_cfg,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=base_cfg,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        try:
+            entries = {}
+            for chunk_hash, (offset, size) in {
+                1: (backend.data_base_offset - backend.slot_bytes, 1024),
+                2: (backend.data_base_offset + 1, 1024),
+                3: (
+                    backend.data_base_offset,
+                    backend.slot_bytes - backend.header_bytes + 1,
+                ),
+            }.items():
+                key = CacheEngineKey("test_model", 1, 0, chunk_hash, torch.bfloat16)
+                entries[key.to_string()] = {
+                    "offset": offset,
+                    "size": size,
+                    "shape": [2, 16, 8, 128],
+                    "dtype": "bfloat16",
+                    "fmt": MemoryFormat.KV_T2D.name,
+                    "cached_positions": None,
+                }
+
+            applied = backend.apply_loaded_state(
+                {
+                    "version": 1,
+                    "device_path": dev_path,
+                    "capacity_bytes": backend.capacity_bytes,
+                    "block_align": backend.block_align,
+                    "header_bytes": backend.header_bytes,
+                    "slot_bytes": backend.slot_bytes,
+                    "meta_total_bytes": backend.meta_total_bytes,
+                    "meta_magic": backend.meta_magic_text,
+                    "meta_version": backend.meta_version,
+                    "data_base_offset": backend.data_base_offset,
+                    "next_slot": 0,
+                    "free_slots": [],
+                    "entries": entries,
+                }
+            )
+            assert applied is True
+            assert backend.indexed_key_count() == 0
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_recovers_legacy_key_dtype(
+    memory_allocator, loop_in_thread
+):
+    """Checkpoint recovery should fall back to dtype encoded in legacy keys."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(8 * 1024 * 1024)
+
+        base_cfg = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_legacy_dtype",
+        )
+        base_cfg.storage_plugins = []
+        base_cfg.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.slot_bytes": 1 * 1024 * 1024,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+            "rust_raw_block.meta_verify_on_load": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=base_cfg,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=base_cfg,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        try:
+            key = CacheEngineKey("test_model", 1, 0, 99, torch.bfloat16)
+            applied = backend.apply_loaded_state(
+                {
+                    "version": 1,
+                    "device_path": dev_path,
+                    "capacity_bytes": backend.capacity_bytes,
+                    "block_align": backend.block_align,
+                    "header_bytes": backend.header_bytes,
+                    "slot_bytes": backend.slot_bytes,
+                    "meta_total_bytes": backend.meta_total_bytes,
+                    "meta_magic": backend.meta_magic_text,
+                    "meta_version": backend.meta_version,
+                    "data_base_offset": backend.data_base_offset,
+                    "next_slot": 1,
+                    "free_slots": [],
+                    # Older checkpoints may include this key; recovery ignores it.
+                    "lru_keys": [key.to_string()],
+                    "entries": {
+                        key.to_string(): {
+                            "offset": backend.data_base_offset,
+                            "size": 1024,
+                            "shape": [512],
+                            "dtype": "torch.bfloat16",
+                            "fmt": MemoryFormat.KV_2LTD.name,
+                            "cached_positions": None,
+                        }
+                    },
+                }
+            )
+
+            assert applied is True
+            loaded = backend.batched_get_blocking([key])
+            assert loaded[0] is not None
+            assert loaded[0].metadata.dtype is torch.bfloat16
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_tp4_initialization(memory_allocator, loop_in_thread):
+    """Test TP=4 initialization with per-TP device paths."""
+    TP = 4
+    with tempfile.TemporaryDirectory() as td:
+        device_paths = [os.path.join(td, f"device{i}.bin") for i in range(TP)]
+        for p in device_paths:
+            with open(p, "wb") as f:
+                f.truncate(256 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_tp4_init",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.per_tp_device_paths": {
+                str(i): device_paths[i] for i in range(TP)
+            },
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+
+        backends = []
+        try:
+            for i in range(TP):
+                metadata = LMCacheMetadata(
+                    model_name="test-model",
+                    world_size=TP,
+                    local_world_size=TP,
+                    worker_id=i,
+                    local_worker_id=i,
+                    kv_dtype=torch.bfloat16,
+                    kv_shape=(32, 2, 256, 32, 128),
+                )
+                local_cpu = LocalCPUBackend(
+                    config=config,
+                    metadata=metadata,
+                    dst_device="cpu",
+                    memory_allocator=memory_allocator,
+                )
+                be = RustRawBlockBackend(
+                    config=config,
+                    metadata=metadata,
+                    local_cpu_backend=local_cpu,
+                    loop=loop_in_thread,
+                    dst_device="cpu",
+                )
+                backends.append(be)
+                assert be.device_path == device_paths[i]
+            assert len({b.device_path for b in backends}) == TP
+        finally:
+            for backend in backends:
+                backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_tp4_initialization_accepts_integer_yaml_keys(
+    memory_allocator, loop_in_thread
+):
+    """Accept integer per-TP YAML keys in addition to quoted string keys."""
+    TP = 4
+    with tempfile.TemporaryDirectory() as td:
+        device_paths = [os.path.join(td, f"device{i}.bin") for i in range(TP)]
+        for p in device_paths:
+            with open(p, "wb") as f:
+                f.truncate(256 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_tp4_init_int_keys",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.per_tp_device_paths": {
+                i: device_paths[i] for i in range(TP)
+            },
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+
+        backends = []
+        try:
+            for i in range(TP):
+                metadata = LMCacheMetadata(
+                    model_name="test-model",
+                    world_size=TP,
+                    local_world_size=TP,
+                    worker_id=i,
+                    local_worker_id=i,
+                    kv_dtype=torch.bfloat16,
+                    kv_shape=(32, 2, 256, 32, 128),
+                )
+                local_cpu = LocalCPUBackend(
+                    config=config,
+                    metadata=metadata,
+                    dst_device="cpu",
+                    memory_allocator=memory_allocator,
+                )
+                be = RustRawBlockBackend(
+                    config=config,
+                    metadata=metadata,
+                    local_cpu_backend=local_cpu,
+                    loop=loop_in_thread,
+                    dst_device="cpu",
+                )
+                backends.append(be)
+                assert be.device_path == device_paths[i]
+        finally:
+            for backend in backends:
+                backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_tp4_comprehensive_io(memory_allocator, loop_in_thread):
+    """Comprehensive TP=4 I/O test covering roundtrip, multiple ops, and isolation."""
+    TP = 4
+    with tempfile.TemporaryDirectory() as td:
+        device_paths = [os.path.join(td, f"device{i}.bin") for i in range(TP)]
+        for p in device_paths:
+            with open(p, "wb") as f:
+                f.truncate(1024 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_tp4_io",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.per_tp_device_paths": {
+                str(i): device_paths[i] for i in range(TP)
+            },
+            "rust_raw_block.capacity_bytes": 0,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+
+        backends = []
+        try:
+            for i in range(TP):
+                metadata = LMCacheMetadata(
+                    model_name="test-model",
+                    world_size=TP,
+                    local_world_size=TP,
+                    worker_id=i,
+                    local_worker_id=i,
+                    kv_dtype=torch.bfloat16,
+                    kv_shape=(32, 2, 256, 32, 128),
+                )
+                local_cpu = LocalCPUBackend(
+                    config=config,
+                    metadata=metadata,
+                    dst_device="cpu",
+                    memory_allocator=memory_allocator,
+                )
+                be = RustRawBlockBackend(
+                    config=config,
+                    metadata=metadata,
+                    local_cpu_backend=local_cpu,
+                    loop=loop_in_thread,
+                    dst_device="cpu",
+                )
+                backends.append(be)
+
+            allocator = AdHocMemoryAllocator(device="cpu")
+            for tp in range(TP):
+                backend = backends[tp]
+                key = CacheEngineKey("test-model", TP, tp, 1000 + tp, torch.bfloat16)
+                obj = allocator.allocate(
+                    [torch.Size([2, 16, 8, 128])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None
+                assert obj.tensor is not None
+                obj.tensor.fill_(tp * 10)
+                expected = bytes(obj.byte_array)
+
+                futs = backend.batched_submit_put_task([key], [obj])
+                assert futs is not None
+                futs[0].result(timeout=10)
+                obj.ref_count_down()
+
+                out = backend.get_blocking(key)
+                assert out is not None
+                assert bytes(out.byte_array) == expected
+                out.ref_count_down()
+
+                for other in range(TP):
+                    if other == tp:
+                        continue
+                    other_key = CacheEngineKey(
+                        "test-model", TP, other, 1000 + other, torch.bfloat16
+                    )
+                    assert backend.get_blocking(other_key) is None
+
+            all_keys = []
+            for tp in range(TP):
+                keys = []
+                for i in range(TP - 1):
+                    allocator = AdHocMemoryAllocator(device="cpu")
+                    obj = allocator.allocate(
+                        [torch.Size([2, 16, 8, 128])],
+                        [torch.bfloat16],
+                        fmt=MemoryFormat.KV_T2D,
+                    )
+                    assert obj is not None
+                    assert obj.tensor is not None
+                    obj.tensor.fill_(tp * 100 + i)
+                    key = CacheEngineKey(
+                        "test-model", TP, tp, tp * 100 + i, torch.bfloat16
+                    )
+                    keys.append(key)
+                    futs = backends[tp].batched_submit_put_task([key], [obj])
+                    assert futs is not None
+                    futs[0].result(timeout=10)
+                    obj.ref_count_down()
+                all_keys.append(keys)
+
+            for tp in range(TP):
+                for key in all_keys[tp]:
+                    out = backends[tp].get_blocking(key)
+                    assert out is not None
+                    assert out.tensor is not None
+                    out.ref_count_down()
+
+            for tp in range(TP):
+                for other in range(TP):
+                    if other == tp:
+                        continue
+                    for key in all_keys[other]:
+                        assert backends[tp].get_blocking(key) is None
+        finally:
+            for backend in backends:
+                backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_tp_paths_must_be_unique(
+    memory_allocator, loop_in_thread
+):
+    """Reject TP config when multiple ranks point to the same partition."""
+    with tempfile.TemporaryDirectory() as td:
+        shared_dev = os.path.join(td, "shared.bin")
+        with open(shared_dev, "wb") as f:
+            f.truncate(512 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_tp_dupe_paths",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.per_tp_device_paths": {"0": shared_dev, "1": shared_dev},
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test-model",
+            world_size=2,
+            local_world_size=2,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(32, 2, 256, 32, 128),
+        )
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        with pytest.raises(ValueError, match="Duplicate device path configured"):
+            RustRawBlockBackend(
+                config=config,
+                metadata=metadata,
+                local_cpu_backend=local_cpu,
+                loop=loop_in_thread,
+                dst_device="cpu",
+            )
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_warns_on_cross_rank_metadata_load(
+    memory_allocator, loop_in_thread
+):
+    """Warn when loading metadata whose first entry belongs to another worker."""
+    with tempfile.TemporaryDirectory() as td:
+        device0 = os.path.join(td, "device0.bin")
+        device1 = os.path.join(td, "device1.bin")
+        for p in [device0, device1]:
+            with open(p, "wb") as f:
+                f.truncate(512 * 1024 * 1024)
+
+        base_extra = {
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+        }
+
+        config_tp0 = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_cross_rank_warn_tp0",
+        )
+        config_tp0.storage_plugins = []
+        config_tp0.extra_config = {
+            **base_extra,
+            "rust_raw_block.per_tp_device_paths": {"0": device0, "1": device1},
+        }
+        metadata_tp0 = LMCacheMetadata(
+            model_name="test-model",
+            world_size=2,
+            local_world_size=2,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(32, 2, 256, 32, 128),
+        )
+        local_cpu_tp0 = LocalCPUBackend(
+            config=config_tp0,
+            metadata=metadata_tp0,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend_tp0 = RustRawBlockBackend(
+            config=config_tp0,
+            metadata=metadata_tp0,
+            local_cpu_backend=local_cpu_tp0,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+        key_tp0 = CacheEngineKey("test-model", 2, 0, 31337, torch.bfloat16)
+        allocator = AdHocMemoryAllocator(device="cpu")
+        obj = allocator.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        assert obj is not None
+        assert obj.tensor is not None
+        obj.tensor.fill_(9)
+        try:
+            futs = backend_tp0.batched_submit_put_task([key_tp0], [obj])
+            assert futs is not None
+            futs[0].result(timeout=10)
+            obj.ref_count_down()
+        finally:
+            backend_tp0.close()
+
+        config_tp1_mis = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_backend_cross_rank_warn_tp1",
+        )
+        config_tp1_mis.storage_plugins = []
+        config_tp1_mis.extra_config = {
+            **base_extra,
+            "rust_raw_block.per_tp_device_paths": {"1": device0},
+        }
+        metadata_tp1 = LMCacheMetadata(
+            model_name="test-model",
+            world_size=2,
+            local_world_size=2,
+            worker_id=1,
+            local_worker_id=1,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(32, 2, 256, 32, 128),
+        )
+        local_cpu_tp1 = LocalCPUBackend(
+            config=config_tp1_mis,
+            metadata=metadata_tp1,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+
+        with patch(
+            "lmcache.v1.storage_backend.plugins.rust_raw_block_backend.logger.warning"
+        ) as mock_warning:
+            backend_tp1 = RustRawBlockBackend(
+                config=config_tp1_mis,
+                metadata=metadata_tp1,
+                local_cpu_backend=local_cpu_tp1,
+                loop=loop_in_thread,
+                dst_device="cpu",
+            )
+        try:
+            matched = False
+            for call in mock_warning.call_args_list:
+                call_args = call.args
+                if not call_args:
+                    continue
+                fmt = call_args[0]
+                if "loaded metadata may belong to another worker" not in str(fmt):
+                    continue
+                assert int(call_args[2]) == 1
+                assert int(call_args[3]) == 0
+                matched = True
+                break
+            assert matched, "Expected cross-rank metadata warning was not emitted"
+        finally:
+            backend_tp1.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_uring_put_get_roundtrip(
+    memory_allocator, loop_in_thread
+):
+    """Test batched write with io_uring and verify data integrity on read.
+
+    Writes 128 items asynchronously, then reads them back and verifies
+    the data matches what was written.
+    """
+    NUM_OPS = 128
+
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(1024 * 1024 * 1024)  # 1G
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=1,
+            lmcache_instance_id="test_rust_raw_block_uring",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.use_uring": True,  # Enable io_uring
+            "rust_raw_block.use_odirect": True,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+            chunk_size=256,
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = local_cpu.memory_allocator
+
+            # Create keys and memory objects with unique data patterns
+            keys = []
+            objs = []
+            expected_data = []
+
+            for i in range(NUM_OPS):
+                key = CacheEngineKey("test_model", 1, 0, i, torch.bfloat16)
+                keys.append(key)
+
+                # Each object gets a unique fill value
+                obj = allocator.allocate(
+                    [torch.Size([2, 16, 8, 128])],
+                    [torch.bfloat16],
+                    fmt=MemoryFormat.KV_T2D,
+                )
+                assert obj is not None
+                assert obj.tensor is not None
+
+                # Use unique pattern: (i + 1) as fill value
+                obj.tensor.fill_(float(i + 1))
+                expected_data.append(bytes(obj.byte_array))
+                objs.append(obj)
+
+            # Submit all writes using io_uring batched write
+            futs = backend.batched_submit_put_task(keys, objs)
+            assert futs is not None
+            futs[0].result(timeout=10)
+
+            # Read back and verify data integrity
+            for i, key in enumerate(keys):
+                out = backend.get_blocking(key)
+                assert out is not None, f"Failed to read key {i}"
+                actual_data = bytes(out.byte_array)
+                # Use `raise AssertionError` instead of `assert ==` so pytest
+                # doesn't try to render a difflib diff between two large
+                # byte arrays on failure (effectively a hang on _fancy_replace).
+                if actual_data != expected_data[i]:
+                    raise AssertionError(
+                        f"Data mismatch for key {i}: "
+                        f"expected first bytes {expected_data[i][:16]!r}, "
+                        f"got {actual_data[:16]!r}"
+                    )
+
+        finally:
+            backend.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_close_with_inflight(memory_allocator, loop_in_thread):
+    """Test that RawBlockDevice close handles queued / inflight io_uring writes."""
+    del memory_allocator, loop_in_thread
+    # Third Party
+    from lmcache_rust_raw_block_io import RawBlockDevice
+
+    NUM_OPS = 128
+
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(16 * 1024 * 1024)
+
+        writer = RawBlockDevice(
+            dev_path,
+            writable=True,
+            use_odirect=False,
+            alignment=4096,
+            io_engine="io_uring",
+        )
+        payload_len = 4096
+        offsets: list[int] = []
+        buffers: list[bytearray] = []
+        total_lens: list[int] = []
+
+        for i in range(NUM_OPS):
+            payload = bytearray([i % 251]) * payload_len
+            offsets.append(i * payload_len)
+            buffers.append(payload)
+            total_lens.append(payload_len)
+
+        writer.batched_write(offsets, buffers, total_lens)
+        time.sleep(0.001)
+        writer.close()
+
+        reader = RawBlockDevice(
+            dev_path,
+            writable=False,
+            use_odirect=False,
+            alignment=4096,
+            io_engine="posix",
+        )
+        try:
+            for i, expected in enumerate(buffers):
+                actual = bytearray(payload_len)
+                reader.pread_into(i * payload_len, actual, payload_len, payload_len)
+                # Use `raise AssertionError` instead of `assert ==` so pytest
+                # doesn't try to render a difflib-based diff between two
+                # large byte arrays on failure, which is O(n^2) on
+                # `_fancy_replace` and effectively never returns.
+                if actual != expected:
+                    raise AssertionError(
+                        f"Data mismatch at offset {i * payload_len}: "
+                        f"expected first bytes {bytes(expected[:16])!r}, "
+                        f"got {bytes(actual[:16])!r}"
+                    )
+        finally:
+            reader.close()
+
+
+@pytest.mark.skipif(
+    not _has_ext(), reason="lmcache_rust_raw_block_io extension not installed"
+)
+def test_rust_raw_block_backend_batched_get_with_uring(
+    memory_allocator, loop_in_thread
+):
+    """Test batched_get_blocking and batched_get_non_blocking with io_uring enabled."""
+    with tempfile.TemporaryDirectory() as td:
+        dev_path = os.path.join(td, "dev.bin")
+        with open(dev_path, "wb") as f:
+            f.truncate(64 * 1024 * 1024)
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            lmcache_instance_id="test_rust_raw_block_batched_get_uring",
+        )
+        config.storage_plugins = []
+        config.extra_config = {
+            "rust_raw_block.device_path": dev_path,
+            "rust_raw_block.block_align": 4096,
+            "rust_raw_block.header_bytes": 4096,
+            "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+            "rust_raw_block.meta_enable_periodic": False,
+            "rust_raw_block.use_uring": True,  # Enable io_uring
+            "rust_raw_block.use_odirect": True,
+        }
+        metadata = LMCacheMetadata(
+            model_name="test_model",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=torch.bfloat16,
+            kv_shape=(4, 2, 256, 8, 128),
+        )
+
+        local_cpu = LocalCPUBackend(
+            config=config,
+            metadata=metadata,
+            dst_device="cpu",
+            memory_allocator=memory_allocator,
+        )
+        backend = RustRawBlockBackend(
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu,
+            loop=loop_in_thread,
+            dst_device="cpu",
+        )
+
+        try:
+            allocator = local_cpu.memory_allocator
+            key1 = CacheEngineKey("test_model", 1, 0, 4001, torch.bfloat16)
+            key2 = CacheEngineKey("test_model", 1, 0, 4002, torch.bfloat16)
+            key_miss = CacheEngineKey("test_model", 1, 0, 4003, torch.bfloat16)
+            key3 = CacheEngineKey("test_model", 1, 0, 4004, torch.bfloat16)
+
+            obj1 = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            obj2 = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            obj3 = allocator.allocate(
+                [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+            )
+            assert obj1 is not None and obj1.tensor is not None
+            assert obj2 is not None and obj2.tensor is not None
+            assert obj3 is not None and obj3.tensor is not None
+            obj1.tensor.fill_(41)
+            obj2.tensor.fill_(42)
+            obj3.tensor.fill_(43)
+            expected1 = bytes(obj1.byte_array)
+            expected2 = bytes(obj2.byte_array)
+
+            # Put keys 1, 2, and 3
+            for key, obj in ((key1, obj1), (key2, obj2), (key3, obj3)):
+                futs = backend.batched_submit_put_task([key], [obj])
+                assert futs is not None
+                futs[0].result(timeout=10)
+                obj.ref_count_down()
+
+            # Test batched_get_blocking with uring. It should stop at first miss
+            blocking_results = backend.batched_get_blocking(
+                [key1, key2, key_miss, key3]
+            )
+            assert len(blocking_results) == 4
+            assert blocking_results[0] is not None
+            assert bytes(blocking_results[0].byte_array) == expected1
+            assert blocking_results[1] is not None
+            assert bytes(blocking_results[1].byte_array) == expected2
+            assert blocking_results[2] is None  # Miss
+            assert blocking_results[3] is None  # After miss
+            blocking_results[0].ref_count_down()
+            blocking_results[1].ref_count_down()
+
+            # Test batched_get_non_blocking with uring.
+            # It should return only successful prefix
+            future = asyncio.run_coroutine_threadsafe(
+                backend.batched_get_non_blocking(
+                    "lookup-uring", [key1, key2, key_miss, key3]
+                ),
+                loop_in_thread,
+            )
+            async_results = future.result(timeout=10)
+            assert len(async_results) == 2  # Only key1 and key2
+            assert bytes(async_results[0].byte_array) == expected1
+            assert bytes(async_results[1].byte_array) == expected2
+            async_results[0].ref_count_down()
+            async_results[1].ref_count_down()
+
+        finally:
+            backend.close()
+
+
+def _make_raw_block_backend(
+    dev_path: str,
+    memory_allocator: Any,
+    loop: asyncio.AbstractEventLoop,
+    *,
+    io_engine: str = "io_uring",
+) -> RustRawBlockBackend:
+    """Build a RustRawBlockBackend over a fake raw-block device.
+
+    Args:
+        dev_path: Backing device path passed to the (faked) raw block device.
+        memory_allocator: Allocator shared with the local CPU backend.
+        loop: Running asyncio event loop for dispatched put coroutines.
+        io_engine: Raw-block I/O engine to configure.
+
+    Returns:
+        A backend whose core reports the requested I/O engine.
+    """
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=0.1,
+        lmcache_instance_id="test_rust_raw_block_backend_plugin_dedup",
+    )
+    config.storage_plugins = []
+    config.extra_config = {
+        "rust_raw_block.device_path": dev_path,
+        "rust_raw_block.block_align": 4096,
+        "rust_raw_block.header_bytes": 4096,
+        "rust_raw_block.meta_total_bytes": 4 * 1024 * 1024,
+        "rust_raw_block.meta_enable_periodic": False,
+        "rust_raw_block.io_engine": io_engine,
+    }
+    metadata = LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+    local_cpu = LocalCPUBackend(
+        config=config,
+        metadata=metadata,
+        dst_device="cpu",
+        memory_allocator=memory_allocator,
+    )
+    return RustRawBlockBackend(
+        config=config,
+        metadata=metadata,
+        local_cpu_backend=local_cpu,
+        loop=loop,
+        dst_device="cpu",
+    )
+
+
+def test_rust_raw_block_backend_batched_submit_rolls_back_refs_on_dispatch_failure(
+    monkeypatch, memory_allocator, loop_in_thread
+):
+    """A dispatch failure rolls back every ref_count_up and clears put_tasks.
+
+    The plugin raises the ref count for each pending object before handing the
+    batch to the event loop. If that hand-off raises (e.g. the loop is shutting
+    down), every raised ref must be returned and every key removed from the
+    in-flight put-task set so nothing leaks.
+    """
+    _install_fake_raw_block_device(monkeypatch, size_bytes=64 * 1024 * 1024)
+    backend = _make_raw_block_backend(
+        "/tmp/plugin-rollback", memory_allocator, loop_in_thread
+    )
+    try:
+        allocator = AdHocMemoryAllocator(device="cpu")
+        key1 = CacheEngineKey("test_model", 1, 0, 2001, torch.bfloat16)
+        key2 = CacheEngineKey("test_model", 1, 0, 2002, torch.bfloat16)
+        obj1 = allocator.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        obj2 = allocator.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        assert obj1 is not None and obj2 is not None
+        before1 = obj1.get_ref_count()
+        before2 = obj2.get_ref_count()
+
+        with patch(
+            "lmcache.v1.storage_backend.plugins.rust_raw_block_backend."
+            "asyncio.run_coroutine_threadsafe",
+            side_effect=RuntimeError("event loop is shutting down"),
+        ):
+            with pytest.raises(RuntimeError):
+                backend.batched_submit_put_task([key1, key2], [obj1, obj2])
+
+        assert obj1.get_ref_count() == before1
+        assert obj2.get_ref_count() == before2
+        assert not backend.exists_in_put_tasks(key1)
+        assert not backend.exists_in_put_tasks(key2)
+        obj1.ref_count_down()
+        obj2.ref_count_down()
+    finally:
+        backend.close()
+
+
+def test_rust_raw_block_backend_batched_submit_rolls_back_only_unscheduled_refs(
+    monkeypatch, memory_allocator, loop_in_thread
+):
+    """A partial per-key dispatch failure leaves scheduled task cleanup to task."""
+    _install_fake_raw_block_device(monkeypatch, size_bytes=64 * 1024 * 1024)
+    backend = _make_raw_block_backend(
+        "/tmp/plugin-partial-rollback",
+        memory_allocator,
+        loop_in_thread,
+        io_engine="posix",
+    )
+    try:
+        allocator = AdHocMemoryAllocator(device="cpu")
+        key1 = CacheEngineKey("test_model", 1, 0, 3001, torch.bfloat16)
+        key2 = CacheEngineKey("test_model", 1, 0, 3002, torch.bfloat16)
+        obj1 = allocator.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        obj2 = allocator.allocate(
+            [torch.Size([2, 16, 8, 128])], [torch.bfloat16], fmt=MemoryFormat.KV_T2D
+        )
+        assert obj1 is not None and obj2 is not None
+        before1 = obj1.get_ref_count()
+        before2 = obj2.get_ref_count()
+        real_run_coroutine_threadsafe = asyncio.run_coroutine_threadsafe
+        first_future: Future | None = None
+
+        def fake_put_many(
+            keys: list[RawBlockKeySpec],
+            objs: list[Any],
+        ) -> RawBlockPutManyResult:
+            del objs
+            return RawBlockPutManyResult(
+                results=[True] * len(keys),
+                stored_keys=[key.encoded for key in keys],
+            )
+
+        def run_first_then_fail(
+            coro: Any,
+            loop: asyncio.AbstractEventLoop,
+        ) -> Future:
+            nonlocal first_future
+            if first_future is None:
+                first_future = real_run_coroutine_threadsafe(coro, loop)
+                return first_future
+            raise RuntimeError("event loop is shutting down")
+
+        with (
+            patch.object(backend._core, "put_many", side_effect=fake_put_many),
+            patch(
+                "lmcache.v1.storage_backend.plugins.rust_raw_block_backend."
+                "asyncio.run_coroutine_threadsafe",
+                side_effect=run_first_then_fail,
+            ),
+        ):
+            with pytest.raises(RuntimeError):
+                backend.batched_submit_put_task([key1, key2], [obj1, obj2])
+
+            assert first_future is not None
+            first_future.result(timeout=10)
+
+        assert obj1.get_ref_count() == before1
+        assert obj2.get_ref_count() == before2
+        assert not backend.exists_in_put_tasks(key1)
+        assert not backend.exists_in_put_tasks(key2)
+        obj1.ref_count_down()
+        obj2.ref_count_down()
+    finally:
+        backend.close()
diff --git a/tests/v1/storage_backend/test_storage_manager.py b/tests/v1/storage_backend/test_storage_manager.py
new file mode 100644
index 0000000..f7346dc
--- /dev/null
+++ b/tests/v1/storage_backend/test_storage_manager.py
@@ -0,0 +1,370 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test cases for StorageManager.
+
+This module tests the critical logic in prefetch_all_done_callback that handles:
+1. Calculating the actual number of retrieved chunks based on batched_get_non_blocking
+   results (not batched_async_contains results)
+2. Handling chunk eviction between contains check and actual retrieval
+3. Ensuring prefix-based continuity: if a tier retrieves fewer chunks than expected,
+   all subsequent tiers are ignored
+4. Properly cleaning up (ref_count_down) memory objects that won't be used due to
+   discontinuity
+
+Key scenarios tested:
+- All chunks retrieved successfully from all tiers
+- Middle tier partial retrieval (subsequent tiers ignored)
+- First tier partial retrieval (all subsequent tiers ignored)
+- Last chunk not being full size
+- Single tier partial retrieval
+"""
+
+# Standard
+import asyncio
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventManager, EventType
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.storage_manager import StorageManager
+
+
+class MockMemoryObj:
+    """Mock MemoryObj for testing."""
+
+    def __init__(self, obj_id: int):
+        self.obj_id = obj_id
+        self.ref_count = 1
+        self.ref_count_down_called = False
+
+    def ref_count_down(self):
+        self.ref_count -= 1
+        self.ref_count_down_called = True
+
+    def __repr__(self):
+        return f"MockMemoryObj(id={self.obj_id}, ref_count={self.ref_count})"
+
+
+class MockAsyncLookupServer:
+    """Mock async lookup server for testing."""
+
+    def __init__(self):
+        self.responses = []
+
+    def send_response_to_scheduler(self, lookup_id: str, retrieved_length: int):
+        self.responses.append((lookup_id, retrieved_length))
+
+
+@pytest.fixture
+def event_manager():
+    """Create an EventManager for testing."""
+    return EventManager()
+
+
+@pytest.fixture
+def storage_manager_config():
+    """Create a test configuration for StorageManager."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=False,
+        lmcache_instance_id="test_instance",
+    )
+    return config
+
+
+@pytest.fixture
+def storage_manager_metadata():
+    """Create test metadata for StorageManager."""
+    metadata = LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(28, 2, 256, 8, 128),
+        role="scheduler",
+    )
+    return metadata
+
+
+@pytest.fixture
+def storage_manager(storage_manager_config, storage_manager_metadata, event_manager):
+    """Create a StorageManager for testing."""
+    manager = StorageManager(
+        config=storage_manager_config,
+        metadata=storage_manager_metadata,
+        event_manager=event_manager,
+    )
+    # Mock the async lookup server
+    manager.async_lookup_server = MockAsyncLookupServer()
+    yield manager
+    manager.close()
+
+
+class TestStorageManagerPrefetchCallback:
+    """Test cases for StorageManager prefetch_all_done_callback."""
+
+    def test_all_chunks_retrieved_successfully(self, storage_manager):
+        """Test Case 1: All chunks retrieved successfully from all tiers."""
+        # Setup: 5 chunks total (1280 tokens), distributed across 2 tiers
+        # Tier 0: 3 chunks, Tier 1: 2 chunks
+        cum_chunk_lengths_total = [0, 256, 512, 768, 1024, 1280]
+        tier_expected_chunks = [3, 2]
+
+        # Create mock memory objects for all chunks. At runtime,
+        # gather_with_keys() in async_lookup_and_prefetch produces
+        # (key, mem_obj) tuples per chunk, so res mirrors that shape.
+        tier0_objs = [MockMemoryObj(i) for i in range(3)]
+        tier1_objs = [MockMemoryObj(i + 3) for i in range(2)]
+        res = [
+            [(f"k{i}", obj) for i, obj in enumerate(tier0_objs)],
+            [(f"k{i + 3}", obj) for i, obj in enumerate(tier1_objs)],
+        ]
+
+        # Create a mock future that returns the result
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        future = loop.create_future()
+        future.set_result(res)
+
+        # Register the event before calling callback
+        storage_manager.event_manager.add_event(
+            EventType.LOADING, "test_lookup_1", future
+        )
+
+        # Call the callback
+        storage_manager.prefetch_all_done_callback(
+            future, "test_lookup_1", cum_chunk_lengths_total, tier_expected_chunks
+        )
+        loop.close()
+
+        # Verify: All 5 chunks should be counted, total 1280 tokens
+        assert len(storage_manager.async_lookup_server.responses) == 1
+        lookup_id, retrieved_length = storage_manager.async_lookup_server.responses[0]
+        assert lookup_id == "test_lookup_1"
+        assert retrieved_length == 1280
+
+        # Verify: No memory objects should have ref_count_down called
+        for obj in tier0_objs + tier1_objs:
+            assert not obj.ref_count_down_called
+
+    def test_middle_tier_partial_retrieval(self, storage_manager):
+        """Test Case 2: Middle tier only got partial chunks, subsequent tier ignored."""
+        # Setup: 7 chunks total (1792 tokens), distributed across 3 tiers
+        # Tier 0: 3 chunks, Tier 1: 2 chunks, Tier 2: 2 chunks
+        cum_chunk_lengths_total = [0, 256, 512, 768, 1024, 1280, 1536, 1792]
+        tier_expected_chunks = [3, 2, 2]
+
+        # Tier 0 got all 3, Tier 1 only got 1 (eviction), Tier 2 got all 2
+        tier0_objs = [MockMemoryObj(i) for i in range(3)]
+        tier1_objs = [MockMemoryObj(i + 3) for i in range(1)]  # Only 1 instead of 2
+        tier2_objs = [MockMemoryObj(i + 5) for i in range(2)]  # Got all 2
+        res = [
+            [(f"k{i}", obj) for i, obj in enumerate(tier0_objs)],
+            [(f"k{i + 3}", obj) for i, obj in enumerate(tier1_objs)],
+            [(f"k{i + 5}", obj) for i, obj in enumerate(tier2_objs)],
+        ]
+
+        # Create a mock future that returns the result
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        future = loop.create_future()
+        future.set_result(res)
+
+        # Register the event before calling callback
+        storage_manager.event_manager.add_event(
+            EventType.LOADING, "test_lookup_2", future
+        )
+
+        # Call the callback
+        storage_manager.prefetch_all_done_callback(
+            future, "test_lookup_2", cum_chunk_lengths_total, tier_expected_chunks
+        )
+        loop.close()
+
+        # Verify: Only 4 chunks counted (3 from tier0 + 1 from tier1)
+        # Total: 1024 tokens
+        assert len(storage_manager.async_lookup_server.responses) == 1
+        lookup_id, retrieved_length = storage_manager.async_lookup_server.responses[0]
+        assert lookup_id == "test_lookup_2"
+        assert retrieved_length == 1024
+
+        # Verify: Tier 0 and Tier 1 objects should NOT have ref_count_down called
+        for obj in tier0_objs + tier1_objs:
+            assert not obj.ref_count_down_called
+
+        # Verify: All Tier 2 objects should have ref_count_down called
+        for obj in tier2_objs:
+            assert obj.ref_count_down_called
+
+    def test_first_tier_partial_retrieval(self, storage_manager):
+        """
+        Test Case 3: First tier only got partial chunks,
+        all subsequent tiers ignored.
+        """
+        # Setup: 7 chunks total (1792 tokens), distributed across 3 tiers
+        # Tier 0: 3 chunks, Tier 1: 2 chunks, Tier 2: 2 chunks
+        cum_chunk_lengths_total = [0, 256, 512, 768, 1024, 1280, 1536, 1792]
+        tier_expected_chunks = [3, 2, 2]
+
+        # Tier 0 only got 2 (eviction), Tier 1 got all 2, Tier 2 got all 2
+        tier0_objs = [MockMemoryObj(i) for i in range(2)]  # Only 2 instead of 3
+        tier1_objs = [MockMemoryObj(i + 3) for i in range(2)]  # Got all 2
+        tier2_objs = [MockMemoryObj(i + 5) for i in range(2)]  # Got all 2
+        res = [
+            [(f"k{i}", obj) for i, obj in enumerate(tier0_objs)],
+            [(f"k{i + 3}", obj) for i, obj in enumerate(tier1_objs)],
+            [(f"k{i + 5}", obj) for i, obj in enumerate(tier2_objs)],
+        ]
+
+        # Create a mock future that returns the result
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        future = loop.create_future()
+        future.set_result(res)
+
+        # Register the event before calling callback
+        storage_manager.event_manager.add_event(
+            EventType.LOADING, "test_lookup_3", future
+        )
+
+        # Call the callback
+        storage_manager.prefetch_all_done_callback(
+            future, "test_lookup_3", cum_chunk_lengths_total, tier_expected_chunks
+        )
+        loop.close()
+
+        # Verify: Only 2 chunks counted (2 from tier0)
+        # Total: 512 tokens
+        assert len(storage_manager.async_lookup_server.responses) == 1
+        lookup_id, retrieved_length = storage_manager.async_lookup_server.responses[0]
+        assert lookup_id == "test_lookup_3"
+        assert retrieved_length == 512
+
+        # Verify: Tier 0 objects should NOT have ref_count_down called
+        for obj in tier0_objs:
+            assert not obj.ref_count_down_called
+
+        # Verify: All Tier 1 and Tier 2 objects should have ref_count_down called
+        for obj in tier1_objs + tier2_objs:
+            assert obj.ref_count_down_called
+
+    def test_last_chunk_not_full(self, storage_manager):
+        """Test with last chunk not being full size."""
+        # Setup: 3 chunks with last chunk only 128 tokens (640 tokens total)
+        # Tier 0: 2 chunks, Tier 1: 1 chunk
+        cum_chunk_lengths_total = [0, 256, 512, 640]  # Last chunk is 128 tokens
+        tier_expected_chunks = [2, 1]
+
+        # All chunks retrieved successfully
+        tier0_objs = [MockMemoryObj(i) for i in range(2)]
+        tier1_objs = [MockMemoryObj(i + 2) for i in range(1)]
+        res = [
+            [(f"k{i}", obj) for i, obj in enumerate(tier0_objs)],
+            [(f"k{i + 2}", obj) for i, obj in enumerate(tier1_objs)],
+        ]
+
+        # Create a mock future that returns the result
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        future = loop.create_future()
+        future.set_result(res)
+
+        # Register the event before calling callback
+        storage_manager.event_manager.add_event(
+            EventType.LOADING, "test_lookup_4", future
+        )
+
+        # Call the callback
+        storage_manager.prefetch_all_done_callback(
+            future, "test_lookup_4", cum_chunk_lengths_total, tier_expected_chunks
+        )
+        loop.close()
+
+        # Verify: All 3 chunks counted, total 640 tokens
+        assert len(storage_manager.async_lookup_server.responses) == 1
+        lookup_id, retrieved_length = storage_manager.async_lookup_server.responses[0]
+        assert lookup_id == "test_lookup_4"
+        assert retrieved_length == 640
+
+        # Verify: No memory objects should have ref_count_down called
+        for obj in tier0_objs + tier1_objs:
+            assert not obj.ref_count_down_called
+
+    def test_single_tier_partial_retrieval(self, storage_manager):
+        """Test with single tier that only got partial chunks."""
+        # Setup: 5 chunks total (1280 tokens), single tier
+        cum_chunk_lengths_total = [0, 256, 512, 768, 1024, 1280]
+        tier_expected_chunks = [5]
+
+        # Only got 3 chunks instead of 5
+        tier0_objs = [MockMemoryObj(i) for i in range(3)]
+        res = [[(f"k{i}", obj) for i, obj in enumerate(tier0_objs)]]
+
+        # Create a mock future that returns the result
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        future = loop.create_future()
+        future.set_result(res)
+
+        # Register the event before calling callback
+        storage_manager.event_manager.add_event(
+            EventType.LOADING, "test_lookup_5", future
+        )
+
+        # Call the callback
+        storage_manager.prefetch_all_done_callback(
+            future, "test_lookup_5", cum_chunk_lengths_total, tier_expected_chunks
+        )
+        loop.close()
+
+        # Verify: Only 3 chunks counted, total 768 tokens
+        assert len(storage_manager.async_lookup_server.responses) == 1
+        lookup_id, retrieved_length = storage_manager.async_lookup_server.responses[0]
+        assert lookup_id == "test_lookup_5"
+        assert retrieved_length == 768
+
+        # Verify: No memory objects should have ref_count_down called
+        # (no remaining chunks in current tier, no subsequent tiers)
+        for obj in tier0_objs:
+            assert not obj.ref_count_down_called
+
+    def test_layerwise_partial_chunk_tail_released(self, storage_manager):
+        """keys_per_chunk=4, backend returns 7 mem_objs for 2 chunks (8 keys);
+        the 3 mem_objs in the rounded-off partial-chunk tail must be released."""
+        keys_per_chunk = 4
+        cum_chunk_lengths_total = [0, 256, 512]
+        tier_expected_chunks = [2]
+
+        tier0_objs = [MockMemoryObj(i) for i in range(7)]
+        res = [[(f"k{i}", obj) for i, obj in enumerate(tier0_objs)]]
+
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        future = loop.create_future()
+        future.set_result(res)
+        storage_manager.event_manager.add_event(
+            EventType.LOADING, "test_layerwise_tail", future
+        )
+
+        storage_manager.prefetch_all_done_callback(
+            future,
+            "test_layerwise_tail",
+            cum_chunk_lengths_total,
+            tier_expected_chunks,
+            keys_per_chunk=keys_per_chunk,
+        )
+        loop.close()
+
+        assert storage_manager.async_lookup_server.responses == [
+            ("test_layerwise_tail", 256)
+        ]
+        for obj in tier0_objs[:4]:
+            assert not obj.ref_count_down_called
+        for obj in tier0_objs[4:]:
+            assert obj.ref_count_down_called
diff --git a/tests/v1/storage_backend/test_storage_plugin.py b/tests/v1/storage_backend/test_storage_plugin.py
new file mode 100644
index 0000000..a9977cb
--- /dev/null
+++ b/tests/v1/storage_backend/test_storage_plugin.py
@@ -0,0 +1,484 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Test cases for  storage_plugin_launcher.
+
+This module tests the storage plugins loading mechanism in CreateStorageBackends.
+It creates a simple mock storage plugin extends StoragePluginInterface
+and verifies that:
+1. The backend is properly loaded via the configuration
+2. The backend methods can be called through StorageManager
+"""
+
+# Standard
+from typing import Any, Callable, List, Optional, Sequence
+import asyncio
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventManager
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend import CreateStorageBackends
+from lmcache.v1.storage_backend.abstract_backend import (
+    AllocatorBackendInterface,
+    StoragePluginInterface,
+)
+from lmcache.v1.storage_backend.storage_manager import StorageManager
+from tests.v1.utils import create_test_memory_obj
+
+
+class MockStoragePlugin(StoragePluginInterface):
+    """
+    A mock storage plugin for testing the storage plugin functionality.
+    This storage plugin extends StoragePluginInterface and provides simple
+    in-memory storage for testing purposes.
+
+    This plugin uses instance-level storage for call history and data storage
+    to enable proper testing of dynamically loaded storage plugins.
+    """
+
+    def __init__(
+        self,
+        config=None,
+        metadata=None,
+        local_cpu_backend=None,
+        loop=None,
+        dst_device: str = "cpu",
+    ):
+        super().__init__(
+            dst_device=dst_device,
+            config=config,
+            metadata=metadata,
+            local_cpu_backend=local_cpu_backend,
+            loop=loop,
+        )
+        self._allocator = AdHocMemoryAllocator(device="cpu")
+        # Use instance-level storage
+        self.call_history: List[str] = []
+        self.storage: dict = {}
+
+    def __str__(self):
+        return "MockStoragePlugin"
+
+    def contains(self, key: CacheEngineKey, pin: bool = False) -> bool:
+        """Check if key exists in storage."""
+        self.call_history.append(f"contains:{key.chunk_hash}")
+        return key.chunk_hash in self.storage
+
+    def exists_in_put_tasks(self, key: CacheEngineKey) -> bool:
+        """Check if key is in ongoing put tasks."""
+        self.call_history.append(f"exists_in_put_tasks:{key.chunk_hash}")
+        return False
+
+    def batched_submit_put_task(
+        self,
+        keys: Sequence[CacheEngineKey],
+        objs: List[MemoryObj],
+        transfer_spec: Any = None,
+        on_complete_callback: Optional[Callable[[CacheEngineKey], None]] = None,
+    ) -> None:
+        """Submit a batched put task."""
+        for key, obj in zip(keys, objs, strict=True):
+            self.call_history.append(f"batched_submit_put_task:{key.chunk_hash}")
+            self.storage[key.chunk_hash] = obj
+
+    def get_blocking(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        """Blocking get for a single key."""
+        self.call_history.append(f"get_blocking:{key.chunk_hash}")
+        return self.storage.get(key.chunk_hash)
+
+    def pin(self, key: CacheEngineKey) -> bool:
+        """Pin a key in storage."""
+        self.call_history.append(f"pin:{key.chunk_hash}")
+        return key.chunk_hash in self.storage
+
+    def unpin(self, key: CacheEngineKey) -> bool:
+        """Unpin a key in storage."""
+        self.call_history.append(f"unpin:{key.chunk_hash}")
+        return key.chunk_hash in self.storage
+
+    def remove(self, key: CacheEngineKey, force: bool = True) -> bool:
+        """Remove a key from storage."""
+        self.call_history.append(f"remove:{key.chunk_hash}")
+        if key.chunk_hash in self.storage:
+            del self.storage[key.chunk_hash]
+            return True
+        return False
+
+    def get_allocator_backend(self) -> "AllocatorBackendInterface":
+        """Get the allocator backend."""
+        # Return the LocalCPUBackend if available, otherwise use self
+        if self.local_cpu_backend is not None:
+            return self.local_cpu_backend
+        raise RuntimeError("No allocator backend available")
+
+    def close(self) -> None:
+        """Close the backend."""
+        self.call_history.append("close")
+
+
+# Module-level constants for storage plugin configuration
+MOCK_BACKEND_EXTRA_CONFIG = {
+    "storage_plugin.mock_backend.module_path": (
+        "tests.v1.storage_backend.test_storage_plugin"
+    ),
+    "storage_plugin.mock_backend.class_name": "MockStoragePlugin",
+}
+MOCK_BACKEND_STORAGE_PLUGINS = ["mock_backend"]
+
+
+def create_test_key(key_id: int = 0) -> CacheEngineKey:
+    """Create a test CacheEngineKey."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=key_id,
+        dtype=torch.bfloat16,
+    )
+
+
+def create_test_config(
+    extra_config: Optional[dict] = None,
+    storage_plugins: Optional[List[str]] = None,
+):
+    """Create a test configuration for storage plugin testing."""
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=0.1,  # Small size for testing
+        lmcache_instance_id="test_storage_plugin_instance",
+    )
+    if extra_config:
+        config.extra_config = extra_config
+    if storage_plugins:
+        config.storage_plugins = storage_plugins
+    return config
+
+
+def create_test_metadata():
+    """Create test metadata for testing."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            4,
+            2,
+            256,
+            8,
+            128,
+        ),  # (num_layers, 2, chunk_size, num_heads, head_dim)
+    )
+
+
+def get_mock_backend(storage_manager_or_backends):
+    """
+    Get the mock storage plugin instance from storage manager or backends dict.
+    Handles both StorageManager and OrderedDict[str, StorageBackendInterface].
+    """
+    if hasattr(storage_manager_or_backends, "storage_backends"):
+        backends = storage_manager_or_backends.storage_backends
+    else:
+        backends = storage_manager_or_backends
+
+    return backends.get("mock_backend")
+
+
+class TestCreateDynamicBackends:
+    """Test cases for storage_plugin_launcher functionality."""
+
+    @pytest.fixture
+    def event_manager(self):
+        """Create an EventManager for testing."""
+        return EventManager()
+
+    @pytest.fixture
+    def async_loop(self):
+        """Create an async event loop for testing."""
+        loop = asyncio.new_event_loop()
+        yield loop
+        loop.close()
+
+    @pytest.fixture
+    def storage_manager_with_mock_backend(self, event_manager):
+        """Fixture to create a StorageManager with the mock storage plugin loaded."""
+        config = create_test_config(
+            extra_config=MOCK_BACKEND_EXTRA_CONFIG,
+            storage_plugins=MOCK_BACKEND_STORAGE_PLUGINS,
+        )
+        metadata = create_test_metadata()
+
+        storage_manager = StorageManager(
+            config=config,
+            metadata=metadata,
+            event_manager=event_manager,
+        )
+
+        yield storage_manager
+
+        storage_manager.close()
+
+    def test_storage_plugin_is_loaded(self, async_loop):
+        """
+        Test that a storage plugin is properly loaded via CreateStorageBackends.
+        """
+        config = create_test_config(
+            extra_config=MOCK_BACKEND_EXTRA_CONFIG,
+            storage_plugins=MOCK_BACKEND_STORAGE_PLUGINS,
+        )
+        metadata = create_test_metadata()
+
+        # Create storage backends
+        storage_backends = CreateStorageBackends(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            dst_device="cpu",
+        )
+
+        # Verify the dynamic backend is loaded
+        assert "mock_backend" in storage_backends, (
+            f"Expected 'mock_backend' in storage_backends, "
+            f"got: {list(storage_backends.keys())}"
+        )
+
+        # Verify it's an instance by checking class name
+        # (since the dynamically imported class is a different object)
+        mock_backend = storage_backends["mock_backend"]
+        assert mock_backend.__class__.__name__ == MockStoragePlugin.__name__, (
+            f"Expected MockStoragePlugin instance, got: {type(mock_backend)}"
+        )
+
+        # Verify it extends StoragePluginInterface
+        assert isinstance(mock_backend, StoragePluginInterface), (
+            f"Expected StoragePluginInterface instance, got: {type(mock_backend)}"
+        )
+
+        # Verify the backend has the expected attributes (call_history, storage)
+        assert hasattr(mock_backend, "call_history"), (
+            "Expected mock_backend to have 'call_history' attribute"
+        )
+        assert hasattr(mock_backend, "storage"), (
+            "Expected mock_backend to have 'storage' attribute"
+        )
+
+        # Close all backends
+        for backend in storage_backends.values():
+            backend.close()
+
+    def test_dynamic_backend_contains_called_via_storage_manager(
+        self, storage_manager_with_mock_backend
+    ):
+        """
+        Test that StorageManager calls the dynamic backend's contains method.
+        """
+        storage_manager = storage_manager_with_mock_backend
+
+        # Verify MockStoragePlugin is in the storage backends
+        assert "mock_backend" in storage_manager.storage_backends, (
+            f"Expected 'mock_backend' in storage_backends, "
+            f"got: {list(storage_manager.storage_backends.keys())}"
+        )
+
+        # Get the mock backend instance to access its call history
+        mock_backend = get_mock_backend(storage_manager)
+        assert mock_backend is not None, "Expected mock_backend to be loaded"
+
+        # Clear the call history before the test
+        mock_backend.call_history.clear()
+
+        # Create a test key
+        test_key = create_test_key(key_id=12345)
+
+        # Call contains via storage_manager
+        # The contains method iterates over all backends
+        result = storage_manager.contains(test_key)
+
+        # Verify the dynamic backend's contains was called
+        assert any("contains:12345" in call for call in mock_backend.call_history), (
+            f"Expected 'contains:12345' in call history, "
+            f"got: {mock_backend.call_history}"
+        )
+
+        # The key doesn't exist, so result should be None
+        assert result is None, f"Expected None, got: {result}"
+
+    def test_dynamic_backend_get_blocking_called_via_storage_manager(
+        self, storage_manager_with_mock_backend
+    ):
+        """
+        Test that StorageManager can retrieve data through the dynamic backend.
+        """
+        storage_manager = storage_manager_with_mock_backend
+
+        # Get the mock backend instance
+        mock_backend = get_mock_backend(storage_manager)
+        assert mock_backend is not None, "Expected mock_backend to be loaded"
+
+        # Pre-populate storage with a test memory object
+        test_key = create_test_key(key_id=67890)
+        test_memory_obj = create_test_memory_obj()
+        mock_backend.storage[test_key.chunk_hash] = test_memory_obj
+
+        # Clear the call history before the test
+        mock_backend.call_history.clear()
+
+        # Call get via storage_manager
+        # This should iterate through backends and call get_blocking
+        result = storage_manager.get(test_key)
+
+        # Verify get_blocking was called on our dynamic backend
+        assert any(
+            "get_blocking:67890" in call for call in mock_backend.call_history
+        ), (
+            f"Expected 'get_blocking:67890' in call history, "
+            f"got: {mock_backend.call_history}"
+        )
+
+        # The result should be our test memory object
+        assert result is test_memory_obj, f"Expected test_memory_obj, got: {result}"
+
+    def test_dynamic_backend_remove_called_via_storage_manager(
+        self, storage_manager_with_mock_backend
+    ):
+        """
+        Test that StorageManager can remove data through the dynamic backend.
+        """
+        storage_manager = storage_manager_with_mock_backend
+
+        # Get the mock backend instance
+        mock_backend = get_mock_backend(storage_manager)
+        assert mock_backend is not None, "Expected mock_backend to be loaded"
+
+        # Pre-populate storage with a test memory object
+        test_key = create_test_key(key_id=11111)
+        test_memory_obj = create_test_memory_obj()
+        mock_backend.storage[test_key.chunk_hash] = test_memory_obj
+
+        # Clear the call history before the test
+        mock_backend.call_history.clear()
+
+        # Call remove via storage_manager
+        num_removed = storage_manager.remove(test_key)
+
+        # Verify remove was called on our dynamic backend
+        assert any("remove:11111" in call for call in mock_backend.call_history), (
+            f"Expected 'remove:11111' in call history, got: {mock_backend.call_history}"
+        )
+
+        # Should have removed from at least one backend
+        assert num_removed >= 1, f"Expected at least 1 removal, got: {num_removed}"
+
+        # Verify the key is no longer in storage
+        assert test_key.chunk_hash not in mock_backend.storage, (
+            f"Expected key {test_key.chunk_hash} to be removed from storage"
+        )
+
+    def test_dynamic_backend_batched_contains_called_via_storage_manager(
+        self, storage_manager_with_mock_backend
+    ):
+        """
+        Test that StorageManager calls batched_contains on the dynamic backend.
+        """
+        storage_manager = storage_manager_with_mock_backend
+
+        # Get the mock backend instance
+        mock_backend = get_mock_backend(storage_manager)
+        assert mock_backend is not None, "Expected mock_backend to be loaded"
+
+        # Pre-populate storage with test memory objects
+        test_keys = [create_test_key(key_id=i) for i in range(1000, 1003)]
+        for key in test_keys:
+            mock_backend.storage[key.chunk_hash] = create_test_memory_obj()
+
+        # Clear the call history before the test
+        mock_backend.call_history.clear()
+
+        # Call batched_contains via storage_manager
+        hit_chunks, block_mapping = storage_manager.batched_contains(test_keys)
+
+        # Verify contains was called for the keys
+        # (batched_contains internally calls contains for each key)
+        contains_calls = [
+            call for call in mock_backend.call_history if call.startswith("contains:")
+        ]
+        assert len(contains_calls) >= 1, (
+            f"Expected at least 1 contains call, got: {mock_backend.call_history}"
+        )
+
+        # Should have found some hits in the mock backend
+        assert hit_chunks >= 1, f"Expected at least 1 hit, got: {hit_chunks}"
+
+    def test_dynamic_backend_without_storage_plugins_config(self, async_loop):
+        """
+        Test that no dynamic backend is loaded when storage_plugins is not configured.
+        """
+        # Configure extra_config but don't set storage_plugins
+        config = create_test_config(
+            extra_config=MOCK_BACKEND_EXTRA_CONFIG,
+            storage_plugins=None,  # No storage_plugins
+        )
+        metadata = create_test_metadata()
+
+        # Create storage backends
+        storage_backends = CreateStorageBackends(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            dst_device="cpu",
+        )
+
+        # Verify no mock_backend is loaded
+        assert "mock_backend" not in storage_backends, (
+            f"Expected 'mock_backend' not to be in storage_backends, "
+            f"got: {list(storage_backends.keys())}"
+        )
+
+        # Close all backends
+        for backend in storage_backends.values():
+            backend.close()
+
+    def test_dynamic_backend_with_invalid_module_path(self, async_loop):
+        """
+        Test that invalid module path is handled gracefully.
+        """
+        # Configure with invalid module path
+        extra_config = {
+            "storage_plugin.invalid_backend.module_path": ("nonexistent.module.path"),
+            "storage_plugin.invalid_backend.class_name": "NonexistentClass",
+        }
+        storage_plugins = ["invalid_backend"]
+
+        config = create_test_config(
+            extra_config=extra_config,
+            storage_plugins=storage_plugins,
+        )
+        metadata = create_test_metadata()
+
+        # Create storage backends - should not raise exception
+        storage_backends = CreateStorageBackends(
+            config=config,
+            metadata=metadata,
+            loop=async_loop,
+            dst_device="cpu",
+        )
+
+        # Invalid backend should not be loaded
+        assert "invalid_backend" not in storage_backends, (
+            f"Expected 'invalid_backend' not to be in storage_backends, "
+            f"got: {list(storage_backends.keys())}"
+        )
+
+        # Close all backends
+        for backend in storage_backends.values():
+            backend.close()
diff --git a/tests/v1/storage_backend/test_valkey_connector.py b/tests/v1/storage_backend/test_valkey_connector.py
new file mode 100644
index 0000000..5ec206e
--- /dev/null
+++ b/tests/v1/storage_backend/test_valkey_connector.py
@@ -0,0 +1,1305 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for ValkeyConnector.
+
+These tests verify the Valkey connector implementation, including:
+- Basic operations (exists, get, set)
+- Batch operations (batch_get, batch_put, batch_exists)
+- Partial misses and non-blocking prefix truncation
+- Cluster mode vs standalone config passthrough
+- Error handling
+- Worker scaling
+
+The worker pool is mocked to avoid requiring glide_sync or a real Valkey server.
+"""
+
+# Standard
+from concurrent.futures import Future, ThreadPoolExecutor
+from unittest.mock import patch
+import asyncio
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.connector import CreateConnector
+
+# Captured at import time (before the autouse mock_thread_worker_pool fixture
+# patches valkey_connector._ThreadWorkerPool) so tests can exercise the real
+# worker-pool methods directly.
+from lmcache.v1.storage_backend.connector.valkey_connector import (  # noqa: E402
+    _ThreadWorkerPool as _RealThreadWorkerPool,
+)
+
+# Local
+from ...conftest import MockSyncGlideClient
+from ..utils import (
+    check_mem_obj_equal,
+    close_asyncio_loop,
+    dumb_cache_engine_key,
+    init_asyncio_loop,
+)
+
+
+class MockThreadWorkerPool:
+    """In-memory mock of _ThreadWorkerPool that uses MockSyncGlideClient.
+
+    Runs all operations in-process so tests don't need glide_sync or a
+    real Valkey server.  Captures constructor kwargs so tests can verify
+    config passthrough (cluster_mode, database_id, tls_enable, etc.).
+    """
+
+    # Class-level record of the last __init__ kwargs for config assertions.
+    last_init_kwargs: dict = {}
+
+    #: When True, ``_do_get_into`` mirrors the real buffer-GET branch: it stages
+    #: into a scratch buffer and relies on the client returning an int byte
+    #: count (``n = int(result)``), exercising the same control flow as the real
+    #: ``_ThreadWorkerPool``. Default False uses the simpler legacy GET branch.
+    simulate_buffer_get: bool = False
+
+    def __init__(self, *args, **kwargs):
+        MockThreadWorkerPool.last_init_kwargs = {
+            "args": args,
+            "kwargs": kwargs,
+        }
+        self.num_workers = kwargs.get("num_workers", 8)
+        if len(args) > 2 and isinstance(args[2], int):
+            self.num_workers = args[2]
+        self._ttl_seconds = kwargs.get("ttl_seconds", None)
+        self._client = MockSyncGlideClient()
+        self._executor = ThreadPoolExecutor(max_workers=self.num_workers)
+
+    def _do_set(self, key_str: str, data: bytes) -> None:
+        """SET a key, mirroring the real pool's TTL handling."""
+        # ("EX", ttl) is a stand-in for glide_sync.ExpirySet, which isn't
+        # importable in the test env.
+        expiry = ("EX", self._ttl_seconds) if self._ttl_seconds is not None else None
+        self._client.set(key_str.encode(), bytes(data), expiry=expiry)
+
+    def _do_get_into(self, key_str: str, buf: memoryview) -> bool:
+        """GET a key into a buffer.
+
+        Mirrors the real ``_ThreadWorkerPool._do_get_into``: when
+        ``simulate_buffer_get`` is set, take the buffer-GET branch (stage into
+        a scratch buffer, rely on an int byte count); otherwise use the legacy
+        GET branch that returns the full bytes.
+        """
+        flat = buf.cast("B") if buf.format != "B" else buf
+        if type(self).simulate_buffer_get:
+            size = flat.nbytes
+            scratch = memoryview(bytearray(size))
+            result = self._client.get(key_str.encode(), buffer=scratch)
+            if result is None:
+                return False
+            n = int(result)
+            flat[:n] = scratch[:n]
+            return True
+        data = self._client.get(key_str.encode())
+        if data is None:
+            return False
+        flat[: len(data)] = data
+        return True
+
+    def _do_exists(self, key_str: str) -> bool:
+        """Check if a key exists."""
+        return bool(self._client.exists([key_str.encode()]))
+
+    def submit_set(self, key_str: str, data: bytes) -> Future:
+        """Submit a SET operation."""
+        return self._executor.submit(self._do_set, key_str, data)
+
+    def submit_get_into(self, key_str: str, buf: memoryview) -> Future:
+        """Submit a GET-into-buffer operation."""
+        return self._executor.submit(self._do_get_into, key_str, buf)
+
+    def submit_exists(self, key_str: str) -> Future:
+        """Submit an EXISTS check."""
+        return self._executor.submit(self._do_exists, key_str)
+
+    def close(self) -> None:
+        """Shut down the thread pool."""
+        self._executor.shutdown(wait=True)
+
+
+def _get_metadata():
+    """Helper to create test metadata."""
+    kv_shape = (32, 2, 256, 8, 128)
+    return LMCacheMetadata(
+        model_name="test-model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+        use_mla=False,
+    )
+
+
+def _create_local_cpu_backend(memory_allocator, config=None):
+    """Helper to create a local CPU backend for testing."""
+    if config is None:
+        config = LMCacheEngineConfig.from_defaults(
+            extra_config={"valkey_num_workers": 4}
+        )
+    metadata = _get_metadata()
+    return LocalCPUBackend(
+        config=config, metadata=metadata, memory_allocator=memory_allocator
+    )
+
+
+def _create_test_memory_obj(local_backend, seed=42):
+    """Allocate a test memory object with deterministic random data.
+
+    Args:
+        local_backend: The local CPU backend for allocation.
+        seed: Random seed for reproducible data.
+
+    Returns:
+        A MemoryObj with ref_count incremented and random data filled.
+    """
+    mem_obj_shape = torch.Size([2, 32, 256, 1024])
+    dtype = torch.bfloat16
+    memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+    memory_obj.ref_count_up()
+    torch.manual_seed(seed)
+    test_tensor = torch.randint(0, 100, memory_obj.raw_data.shape, dtype=torch.int64)
+    memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+    return memory_obj
+
+
+@pytest.fixture(autouse=True)
+def mock_thread_worker_pool():
+    """Replace _ThreadWorkerPool with in-memory mock so tests never need
+    glide_sync or a real Valkey server."""
+    MockSyncGlideClient.reset_store()
+    MockThreadWorkerPool.last_init_kwargs = {}
+    MockThreadWorkerPool.simulate_buffer_get = False
+    with patch(
+        "lmcache.v1.storage_backend.connector.valkey_connector._ThreadWorkerPool",
+        MockThreadWorkerPool,
+    ):
+        yield
+
+
+@pytest.fixture
+def valkey_url():
+    """URL for testing."""
+    return "valkey://mock.local:0"
+
+
+@pytest.fixture
+def valkey_config():
+    """Config for ValkeyConnector testing."""
+    return LMCacheEngineConfig.from_defaults(extra_config={"valkey_num_workers": 4})
+
+
+@pytest.fixture
+def local_backend():
+    """Create a local CPU backend for testing."""
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    backend = _create_local_cpu_backend(memory_allocator)
+    yield backend
+    backend.close()
+
+
+def test_valkey_basic_operations(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test basic operations: exists, put, get."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        random_key = dumb_cache_engine_key()
+
+        # Key doesn't exist initially
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(random_key), async_loop
+        )
+        assert not future.result(), "Key should not exist initially"
+
+        memory_obj = _create_test_memory_obj(local_backend, seed=42)
+
+        # Put data
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(random_key, memory_obj), async_loop
+        )
+        future.result()
+
+        # Key exists after put
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(random_key), async_loop
+        )
+        assert future.result(), "Key should exist after put"
+
+        # Get and verify data
+        future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+        retrieved = future.result()
+        check_mem_obj_equal([retrieved], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_batch_operations(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test batch operations: batched_put, batched_get, batched_async_contains."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        num_keys = 10
+        keys = [dumb_cache_engine_key(i) for i in range(num_keys)]
+
+        # Batch exists — all should be False initially
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_async_contains("test_lookup", keys), async_loop
+        )
+        assert future.result() == 0, "No keys should exist initially"
+
+        memory_objs = [
+            _create_test_memory_obj(local_backend, seed=42 + i) for i in range(num_keys)
+        ]
+
+        # Batch put
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys, memory_objs), async_loop
+        )
+        future.result()
+
+        # Batch exists — all should be True now
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_async_contains("test_lookup", keys), async_loop
+        )
+        assert future.result() == num_keys, "All keys should exist after batch_put"
+
+        # Batch get and verify
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get(keys), async_loop
+        )
+        retrieved_objs = future.result()
+
+        assert len(retrieved_objs) == num_keys
+        check_mem_obj_equal(retrieved_objs, memory_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_nonexistent_key(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test exists and get on a non-existent key."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        nonexistent_key = dumb_cache_engine_key()
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(nonexistent_key), async_loop
+        )
+        assert not future.result()
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.get(nonexistent_key), async_loop
+        )
+        assert future.result() is None, "get() should return None for missing key"
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_sequential_operations(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test multiple sequential put/get cycles."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        for i in range(5):
+            key = dumb_cache_engine_key(i)
+            memory_obj = _create_test_memory_obj(local_backend, seed=1000 + i)
+
+            future = asyncio.run_coroutine_threadsafe(
+                connector.put(key, memory_obj), async_loop
+            )
+            future.result()
+
+            future = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+            retrieved = future.result()
+            check_mem_obj_equal([retrieved], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_concurrent_operations(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test concurrent put/get operations."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        num_concurrent = 5
+        keys = [dumb_cache_engine_key(i) for i in range(num_concurrent)]
+        memory_objs = [
+            _create_test_memory_obj(local_backend, seed=2000 + i)
+            for i in range(num_concurrent)
+        ]
+
+        put_futures = [
+            asyncio.run_coroutine_threadsafe(
+                connector.put(keys[i], memory_objs[i]), async_loop
+            )
+            for i in range(num_concurrent)
+        ]
+        for f in put_futures:
+            f.result()
+
+        get_futures = [
+            asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+            for key in keys
+        ]
+        retrieved_objs = [f.result() for f in get_futures]
+        check_mem_obj_equal(retrieved_objs, memory_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_exists_sync(valkey_url, local_backend, valkey_config, autorelease_v1):
+    """Test synchronous exists method."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        key = dumb_cache_engine_key()
+        assert not connector.exists_sync(key)
+
+        memory_obj = _create_test_memory_obj(local_backend)
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key, memory_obj), async_loop
+        )
+        future.result()
+
+        assert connector.exists_sync(key)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_batched_contains_prefix(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test that batched_contains returns prefix count correctly."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        keys = [dumb_cache_engine_key(i) for i in range(5)]
+
+        # Put only first 3 keys
+        for i in range(3):
+            memory_obj = _create_test_memory_obj(local_backend, seed=i)
+            future = asyncio.run_coroutine_threadsafe(
+                connector.put(keys[i], memory_obj), async_loop
+            )
+            future.result()
+
+        count = connector.batched_contains(keys)
+        assert count == 3, f"Expected 3 consecutive keys, got {count}"
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_different_chunk_sizes(autorelease_v1):
+    """Test that the connector works with different chunk sizes."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    config = LMCacheEngineConfig.from_defaults(extra_config={"valkey_num_workers": 4})
+
+    kv_shape = (32, 2, 512, 8, 128)
+    dtype = torch.bfloat16
+    metadata = LMCacheMetadata(
+        model_name="test-model-large",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=dtype,
+        kv_shape=kv_shape,
+        use_mla=False,
+        chunk_size=512,
+    )
+    local_backend = LocalCPUBackend(
+        config=config, metadata=metadata, memory_allocator=memory_allocator
+    )
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(
+                "valkey://mock.local:0",
+                async_loop,
+                local_backend,
+                config,
+            )
+        )
+
+        key = dumb_cache_engine_key()
+        mem_obj_shape = torch.Size([2, 32, 512, 1024])
+        memory_obj = local_backend.allocate(mem_obj_shape, dtype)
+        memory_obj.ref_count_up()
+
+        torch.manual_seed(100)
+        test_tensor = torch.randint(
+            0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+        )
+        memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key, memory_obj), async_loop
+        )
+        future.result()
+
+        future = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+        retrieved = future.result()
+        check_mem_obj_equal([retrieved], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+        local_backend.close()
+
+
+def test_valkey_pipelined_batch_exceeds_arena(
+    valkey_url, valkey_config, autorelease_v1
+):
+    """Test batched put/get when batch size > num_workers.
+
+    With num_workers=4, a batch of 12 keys forces the connector to handle
+    more concurrent operations than workers, verifying that all data is
+    correctly processed.
+
+    Uses a dedicated 2 GB allocator so the 12 put objects + 12 get objects
+    (~768 MB total at 32 MB each) fit without blocking.
+    """
+    async_loop, async_thread = init_asyncio_loop()
+
+    memory_allocator = PinMemoryAllocator(2 * 1024 * 1024 * 1024)
+    local_backend = _create_local_cpu_backend(memory_allocator, valkey_config)
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        num_keys = 12
+        keys = [dumb_cache_engine_key(i) for i in range(num_keys)]
+        memory_objs = [
+            _create_test_memory_obj(local_backend, seed=5000 + i)
+            for i in range(num_keys)
+        ]
+
+        # Batch put all 12
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys, memory_objs), async_loop
+        )
+        future.result()
+
+        # All 12 should exist
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_async_contains("test_lookup", keys), async_loop
+        )
+        assert future.result() == num_keys
+
+        # Batch get and verify every item matches
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get(keys), async_loop
+        )
+        retrieved_objs = future.result()
+
+        assert len(retrieved_objs) == num_keys
+        check_mem_obj_equal(retrieved_objs, memory_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+        local_backend.close()
+
+
+@pytest.mark.parametrize("num_workers", [1, 4, 8])
+def test_valkey_worker_scaling(num_workers, autorelease_v1):
+    """Test ValkeyConnector with different numbers of worker threads."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={"valkey_num_workers": num_workers}
+    )
+    metadata = _get_metadata()
+    local_backend = LocalCPUBackend(
+        config=config, metadata=metadata, memory_allocator=memory_allocator
+    )
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(
+                "valkey://mock.local:0",
+                async_loop,
+                local_backend,
+                config,
+            )
+        )
+
+        key = dumb_cache_engine_key()
+        memory_obj = _create_test_memory_obj(local_backend, seed=3000)
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key, memory_obj), async_loop
+        )
+        future.result()
+
+        future = asyncio.run_coroutine_threadsafe(connector.get(key), async_loop)
+        retrieved = future.result()
+        check_mem_obj_equal([retrieved], [memory_obj])
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+        local_backend.close()
+
+
+# ── New tests: partial misses, non-blocking prefix, config passthrough ──
+
+
+def test_valkey_batched_get_partial_misses(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test batched_get when some keys exist and some don't.
+
+    Put keys 0-4, request keys 0-9.  The result should have 5 MemoryObjs
+    followed by 5 Nones.
+    """
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        num_present = 5
+        num_total = 10
+        keys = [dumb_cache_engine_key(i) for i in range(num_total)]
+        put_objs = [
+            _create_test_memory_obj(local_backend, seed=7000 + i)
+            for i in range(num_present)
+        ]
+
+        # Put only first 5
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys[:num_present], put_objs), async_loop
+        )
+        future.result()
+
+        # Batch get all 10
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get(keys), async_loop
+        )
+        results = future.result()
+
+        assert len(results) == num_total
+        # First 5 should be valid MemoryObjs matching what we put
+        for i in range(num_present):
+            assert results[i] is not None, f"Key {i} should exist"
+        check_mem_obj_equal(results[:num_present], put_objs)
+        # Last 5 should be None
+        for i in range(num_present, num_total):
+            assert results[i] is None, f"Key {i} should be None"
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_batched_get_non_blocking_all_present(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test batched_get_non_blocking when all keys are present."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        num_keys = 5
+        keys = [dumb_cache_engine_key(i) for i in range(num_keys)]
+        put_objs = [
+            _create_test_memory_obj(local_backend, seed=8000 + i)
+            for i in range(num_keys)
+        ]
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys, put_objs), async_loop
+        )
+        future.result()
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get_non_blocking("lookup", keys), async_loop
+        )
+        prefix = future.result()
+
+        assert len(prefix) == num_keys
+        check_mem_obj_equal(prefix, put_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_batched_get_non_blocking_prefix_truncation(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test batched_get_non_blocking returns only the consecutive prefix.
+
+    Put keys 0-2, request keys 0-4.  Should return only the first 3
+    objects; keys 3-4 are missing so the prefix stops there.
+    """
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        num_present = 3
+        num_total = 5
+        keys = [dumb_cache_engine_key(i) for i in range(num_total)]
+        put_objs = [
+            _create_test_memory_obj(local_backend, seed=9000 + i)
+            for i in range(num_present)
+        ]
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys[:num_present], put_objs), async_loop
+        )
+        future.result()
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get_non_blocking("lookup", keys), async_loop
+        )
+        prefix = future.result()
+
+        assert len(prefix) == num_present
+        check_mem_obj_equal(prefix, put_objs)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_batched_get_non_blocking_first_missing(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """Test batched_get_non_blocking returns empty when first key is missing."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        keys = [dumb_cache_engine_key(i) for i in range(3)]
+        # Don't put anything
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.batched_get_non_blocking("lookup", keys), async_loop
+        )
+        prefix = future.result()
+
+        assert len(prefix) == 0
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_standalone_mode_config(local_backend, autorelease_v1):
+    """Test that standalone mode (default) passes correct config to pool."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_database": 3,
+        }
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://standalone.local:6379",
+                async_loop,
+                local_backend,
+                config,
+            )
+        )
+
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        # Positional args: host, port, num_workers, username, password
+        assert init_info["args"][0] == "standalone.local"
+        assert init_info["args"][1] == 6379
+        assert init_info["args"][2] == 2
+        assert init_info["kwargs"].get("cluster_mode") is False
+        assert init_info["kwargs"].get("database_id") == 3
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_cluster_mode_config(local_backend, autorelease_v1):
+    """Test that cluster mode passes cluster_mode=True and ignores database_id."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 4,
+            "valkey_mode": "cluster",
+            "valkey_database": 5,  # should be ignored in cluster mode
+        }
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://cluster.local:7000",
+                async_loop,
+                local_backend,
+                config,
+            )
+        )
+
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["args"][0] == "cluster.local"
+        assert init_info["args"][1] == 7000
+        assert init_info["kwargs"].get("cluster_mode") is True
+        # database_id should be None (ignored in cluster mode)
+        assert init_info["kwargs"].get("database_id") is None
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+@pytest.mark.parametrize(
+    "raw_value,expected",
+    [("true", True), ("True", True), ("1", True), ("false", False), ("0", False)],
+)
+def test_valkey_tls_enable_string_coercion(
+    local_backend, autorelease_v1, raw_value, expected
+):
+    """tls_enable from free-form extra_config may be a string; it must be
+    coerced (a bare bool("false") would wrongly enable TLS)."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={"valkey_num_workers": 2, "tls_enable": raw_value}
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://tlsstr.local:6380",
+                async_loop,
+                local_backend,
+                config,
+            )
+        )
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["kwargs"].get("tls_enable") is expected
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_tls_config(local_backend, autorelease_v1):
+    """Test that tls_enable is passed through to the pool."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "tls_enable": True,
+        }
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://tls.local:6380",
+                async_loop,
+                local_backend,
+                config,
+            )
+        )
+
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["kwargs"].get("tls_enable") is True
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+# ── TTL feature flag (volatile-* eviction support) ──────────────────────
+
+
+def test_valkey_ttl_sec_disabled_by_default(local_backend, autorelease_v1):
+    """By default (no valkey_enable_ttl) no TTL is passed to the pool."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(extra_config={"valkey_num_workers": 2})
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+        )
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["kwargs"].get("ttl_seconds") is None
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_ttl_sec_enabled_passthrough(local_backend, autorelease_v1):
+    """valkey_enable_ttl + valkey_ttl_sec flow through to the pool as ttl_seconds."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+            "valkey_ttl_sec": 3600,
+        }
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+        )
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["kwargs"].get("ttl_seconds") == 3600
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_ttl_sec_enabled_without_value_uses_default(
+    local_backend, autorelease_v1
+):
+    """Enabling the flag without valkey_ttl_sec falls back to DEFAULT_TTL_SECS."""
+    # First Party
+    from lmcache.v1.storage_backend.connector.valkey_connector import (
+        DEFAULT_TTL_SECS,
+    )
+
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+        }
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+        )
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["kwargs"].get("ttl_seconds") == DEFAULT_TTL_SECS
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+@pytest.mark.parametrize("raw_ttl", [0, -1, -100, "-100", "0.5", "-0.5"])
+def test_valkey_ttl_sec_invalid_value_raises(raw_ttl, local_backend, autorelease_v1):
+    """A non-positive valkey_ttl_sec is rejected when the flag is enabled.
+
+    Covers zero, negative ints/strings, and sub-second values that truncate
+    to zero.
+    """
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+            "valkey_ttl_sec": raw_ttl,
+        }
+    )
+
+    try:
+        with pytest.raises(ValueError, match="valkey_ttl_sec must be a positive"):
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+@pytest.mark.parametrize(
+    "raw_ttl,expected",
+    [("1800", 1800), ("1800.0", 1800), (1800.0, 1800), (1800, 1800)],
+)
+def test_valkey_ttl_sec_numeric_coercion(
+    raw_ttl, expected, local_backend, autorelease_v1
+):
+    """valkey_ttl_sec may arrive as an int/float or an int/float-like string
+    from free-form extra_config; all coerce to a positive int TTL."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+            "valkey_ttl_sec": raw_ttl,
+        }
+    )
+
+    try:
+        autorelease_v1(
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+        )
+        init_info = MockThreadWorkerPool.last_init_kwargs
+        assert init_info["kwargs"].get("ttl_seconds") == expected
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_ttl_sec_non_numeric_raises(local_backend, autorelease_v1):
+    """A non-numeric valkey_ttl_sec is rejected with a clear ValueError."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+            "valkey_ttl_sec": "not-a-number",
+        }
+    )
+
+    try:
+        with pytest.raises(ValueError, match="valkey_ttl_sec must be a positive"):
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+@pytest.mark.parametrize("raw_ttl", [True, False])
+def test_valkey_ttl_sec_bool_raises(raw_ttl, local_backend, autorelease_v1):
+    """A boolean valkey_ttl_sec is rejected (bool is an int subclass, so it
+    would otherwise silently coerce to a 1-second TTL)."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+            "valkey_ttl_sec": raw_ttl,
+        }
+    )
+
+    try:
+        with pytest.raises(ValueError, match="valkey_ttl_sec must be a positive"):
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_ttl_sec_applied_on_put(local_backend, autorelease_v1):
+    """When TTL is enabled, SET carries an expiry; otherwise it does not."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "valkey_enable_ttl": True,
+            "valkey_ttl_sec": 1800,
+        }
+    )
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(
+                "valkey://ttl.local:6379", async_loop, local_backend, config
+            )
+        )
+
+        key = dumb_cache_engine_key()
+        memory_obj = _create_test_memory_obj(local_backend, seed=11)
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key, memory_obj), async_loop
+        )
+        future.result()
+
+        # The mock client records the expiry passed to the last SET.
+        assert MockSyncGlideClient.last_expiry == ("EX", 1800)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_no_ttl_on_put_when_disabled(
+    valkey_url, local_backend, valkey_config, autorelease_v1
+):
+    """With TTL disabled, SET passes no expiry (legacy behavior)."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        key = dumb_cache_engine_key()
+        memory_obj = _create_test_memory_obj(local_backend, seed=12)
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(key, memory_obj), async_loop
+        )
+        future.result()
+
+        assert MockSyncGlideClient.last_expiry is None
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_rejects_save_unfull_chunk(local_backend, autorelease_v1):
+    """Valkey uses single-key fixed-size storage with no per-chunk metadata,
+    so partial/unfull chunks are not allowed (same as RESP)."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={"valkey_num_workers": 2},
+    )
+    # Force the partial-chunk flag on after construction so we exercise the
+    # adapter's guard rather than any config auto-adjust logic.
+    config.save_unfull_chunk = True
+
+    try:
+        with pytest.raises(ValueError, match="save_unfull_chunk must be False"):
+            autorelease_v1(
+                CreateConnector(
+                    "valkey://nopartial.local:6379",
+                    async_loop,
+                    local_backend,
+                    config,
+                )
+            )
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_rejects_save_chunk_meta(local_backend, autorelease_v1):
+    """Valkey does not persist per-chunk metadata, so save_chunk_meta must be
+    False (same as RESP)."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "save_chunk_meta": True,
+        },
+    )
+
+    try:
+        with pytest.raises(ValueError, match="save_chunk_meta must be False"):
+            autorelease_v1(
+                CreateConnector(
+                    "valkey://nometa.local:6379",
+                    async_loop,
+                    local_backend,
+                    config,
+                )
+            )
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+@pytest.mark.parametrize(
+    "raw_value,should_reject",
+    [
+        ("true", True),
+        ("True", True),
+        ("1", True),
+        ("false", False),
+        ("0", False),
+    ],
+)
+def test_valkey_save_chunk_meta_string_coercion(
+    local_backend, autorelease_v1, raw_value, should_reject
+):
+    """save_chunk_meta from free-form extra_config may be a string; it must be
+    coerced (a bare truthiness check would treat "false" as True)."""
+    async_loop, async_thread = init_asyncio_loop()
+
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={
+            "valkey_num_workers": 2,
+            "save_chunk_meta": raw_value,
+        },
+    )
+
+    try:
+        if should_reject:
+            with pytest.raises(ValueError, match="save_chunk_meta must be False"):
+                autorelease_v1(
+                    CreateConnector(
+                        "valkey://strmeta.local:6379",
+                        async_loop,
+                        local_backend,
+                        config,
+                    )
+                )
+        else:
+            autorelease_v1(
+                CreateConnector(
+                    "valkey://strmeta.local:6379",
+                    async_loop,
+                    local_backend,
+                    config,
+                )
+            )
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
+
+
+def test_valkey_do_get_into_rejects_short_read():
+    """_do_get_into must not silently accept a short read: fixed-size chunks
+    require an exact round-trip, so a partial fill is treated as a miss
+    (returns False) instead of leaving stale tail bytes in the buffer."""
+    # Standard
+    from types import SimpleNamespace
+
+    class _FakeClient:
+        def __init__(self, payload: bytes):
+            self._payload = payload
+
+        def get(self, key, buffer=None):
+            if buffer is not None:
+                n = len(self._payload)
+                buffer[:n] = self._payload
+                return n
+            return self._payload
+
+    def _make_self(payload, has_buffer_get):
+        return SimpleNamespace(
+            _get_client=lambda: _FakeClient(payload),
+            _has_buffer_get=has_buffer_get,
+            _get_scratch=lambda size: bytearray(size),
+        )
+
+    expected = 8
+
+    # Short read (buffer-get path) → treated as miss
+    buf = memoryview(bytearray(expected))
+    fake = _make_self(b"\xaa" * 4, has_buffer_get=True)
+    assert _RealThreadWorkerPool._do_get_into(fake, "k", buf) is False
+
+    # Short read (non-buffer path) → treated as miss
+    buf = memoryview(bytearray(expected))
+    fake = _make_self(b"\xaa" * 4, has_buffer_get=False)
+    assert _RealThreadWorkerPool._do_get_into(fake, "k", buf) is False
+
+    # Exact read (buffer-get path) → hit, buffer fully populated
+    buf = memoryview(bytearray(expected))
+    fake = _make_self(b"\xbb" * expected, has_buffer_get=True)
+    assert _RealThreadWorkerPool._do_get_into(fake, "k", buf) is True
+    assert bytes(buf) == b"\xbb" * expected
+
+    # Exact read (non-buffer path) → hit, buffer fully populated
+    buf = memoryview(bytearray(expected))
+    fake = _make_self(b"\xcc" * expected, has_buffer_get=False)
+    assert _RealThreadWorkerPool._do_get_into(fake, "k", buf) is True
+    assert bytes(buf) == b"\xcc" * expected
+
+
+@pytest.mark.parametrize("simulate_buffer_get", [False, True])
+def test_valkey_get_round_trip_both_get_modes(
+    valkey_url, local_backend, valkey_config, autorelease_v1, simulate_buffer_get
+):
+    """get/batched_get must round-trip correctly on both worker-pool GET paths:
+    the legacy GET (returns full bytes) and the buffer-GET branch (returns an
+    int byte count). This closes the gap where the mock only exercised the
+    non-buffer branch, leaving the connector's buffer-GET handling untested."""
+    MockThreadWorkerPool.simulate_buffer_get = simulate_buffer_get
+    async_loop, async_thread = init_asyncio_loop()
+
+    try:
+        connector = autorelease_v1(
+            CreateConnector(valkey_url, async_loop, local_backend, valkey_config)
+        )
+
+        # Single get round-trip
+        key = dumb_cache_engine_key()
+        mem = _create_test_memory_obj(local_backend, seed=7)
+        asyncio.run_coroutine_threadsafe(connector.put(key, mem), async_loop).result()
+        retrieved = asyncio.run_coroutine_threadsafe(
+            connector.get(key), async_loop
+        ).result()
+        assert retrieved is not None
+        check_mem_obj_equal([retrieved], [mem])
+
+        # Batched get round-trip
+        keys = [dumb_cache_engine_key(i) for i in range(3)]
+        mems = [_create_test_memory_obj(local_backend, seed=100 + i) for i in range(3)]
+        asyncio.run_coroutine_threadsafe(
+            connector.batched_put(keys, mems), async_loop
+        ).result()
+        retrieved_batch = asyncio.run_coroutine_threadsafe(
+            connector.batched_get(keys), async_loop
+        ).result()
+        assert all(r is not None for r in retrieved_batch)
+        check_mem_obj_equal(retrieved_batch, mems)
+
+    finally:
+        close_asyncio_loop(async_loop, async_thread)
diff --git a/tests/v1/test_address_manager.py b/tests/v1/test_address_manager.py
new file mode 100644
index 0000000..6ccf10d
--- /dev/null
+++ b/tests/v1/test_address_manager.py
@@ -0,0 +1,1207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for AddressManager class."""
+
+# Standard
+from typing import List, Tuple
+import concurrent.futures
+import threading
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.memory_management import AddressManager
+
+
+class TestAddressManagerBasic:
+    """Test basic functionality of AddressManager."""
+
+    def test_initialization(self):
+        """Test that AddressManager initializes correctly."""
+        size = 4096 * 10  # 10 pages
+        manager = AddressManager(size)
+
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_initialization_custom_alignment(self):
+        """Test initialization with custom alignment."""
+        size = 1024 * 100
+        align_bytes = 1024
+        manager = AddressManager(size, align_bytes=align_bytes)
+
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_compute_aligned_size(self):
+        """Test that compute_aligned_size works correctly."""
+        manager = AddressManager(4096 * 10, align_bytes=4096)
+
+        # Size already aligned
+        assert manager.compute_aligned_size(4096) == 4096
+        assert manager.compute_aligned_size(8192) == 8192
+
+        # Size needs alignment
+        assert manager.compute_aligned_size(1) == 4096
+        assert manager.compute_aligned_size(4097) == 8192
+        assert manager.compute_aligned_size(100) == 4096
+
+    def test_compute_aligned_size_custom_alignment(self):
+        """Test compute_aligned_size with different alignment values."""
+        manager = AddressManager(10000, align_bytes=256)
+
+        assert manager.compute_aligned_size(1) == 256
+        assert manager.compute_aligned_size(256) == 256
+        assert manager.compute_aligned_size(257) == 512
+        assert manager.compute_aligned_size(512) == 512
+
+
+class TestAddressManagerAllocation:
+    """Test allocation functionality."""
+
+    def test_single_allocation(self):
+        """Test a single allocation."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        address, allocated_size = manager.allocate(100)
+
+        # Verify allocation returns valid values
+        assert address >= 0
+        assert allocated_size == 4096  # Aligned to 4096
+        assert manager.total_allocated_size == 4096
+        assert manager.get_free_size() == size - 4096
+        assert manager.check_consistency()
+
+    def test_multiple_allocations(self):
+        """Test multiple sequential allocations."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        # First allocation
+        addr1, size1 = manager.allocate(1000)
+        assert addr1 >= 0
+        assert size1 == 4096
+
+        # Second allocation
+        addr2, size2 = manager.allocate(2000)
+        assert addr2 >= 0
+        assert size2 == 4096
+
+        # Third allocation
+        addr3, size3 = manager.allocate(5000)
+        assert addr3 >= 0
+        assert size3 == 8192
+
+        # Verify allocations don't overlap
+        allocations = [(addr1, size1), (addr2, size2), (addr3, size3)]
+        assert _no_overlap(allocations)
+
+        assert manager.total_allocated_size == 4096 + 4096 + 8192
+        assert manager.get_free_size() == size - (4096 + 4096 + 8192)
+        assert manager.check_consistency()
+
+    def test_allocation_exact_size(self):
+        """Test allocation with exact aligned size."""
+        manager = AddressManager(4096 * 5)
+
+        addr, alloc_size = manager.allocate(4096)
+        assert addr >= 0
+        assert alloc_size == 4096
+        assert manager.check_consistency()
+
+    def test_allocation_failure_out_of_memory(self):
+        """Test that allocation fails when out of memory."""
+        size = 4096 * 2
+        manager = AddressManager(size)
+
+        # First allocation succeeds
+        manager.allocate(4096)
+
+        # Second allocation succeeds
+        manager.allocate(4096)
+
+        # Third allocation should fail
+        with pytest.raises(RuntimeError, match="no memory is available"):
+            manager.allocate(1)
+
+        assert manager.check_consistency()
+
+    def test_allocation_failure_too_large(self):
+        """Test allocation failure when requested size is too large."""
+        size = 4096 * 2
+        manager = AddressManager(size)
+
+        with pytest.raises(RuntimeError, match="no memory is available"):
+            manager.allocate(size + 1)
+
+        assert manager.check_consistency()
+
+
+class TestAddressManagerBatchedAllocation:
+    """Test batched_allocate functionality."""
+
+    def test_single_batch(self):
+        """Test batched_allocate with batch_size=1 behaves like allocate."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        results = manager.batched_allocate(100, 1)
+
+        assert len(results) == 1
+        addr, allocated_size = results[0]
+        assert addr >= 0
+        assert allocated_size == 4096  # Aligned to 4096
+        assert manager.total_allocated_size == 4096
+        assert manager.get_free_size() == size - 4096
+        assert manager.check_consistency()
+
+    def test_multiple_batch(self):
+        """Test batched_allocate with multiple blocks."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        results = manager.batched_allocate(1000, 5)
+
+        assert len(results) == 5
+        for addr, allocated_size in results:
+            assert addr >= 0
+            assert allocated_size == 4096
+
+        assert _no_overlap(results)
+        assert manager.total_allocated_size == 4096 * 5
+        assert manager.get_free_size() == size - 4096 * 5
+        assert manager.check_consistency()
+
+    def test_batch_exact_aligned_size(self):
+        """Test batched_allocate with exact aligned size."""
+        manager = AddressManager(4096 * 5)
+
+        results = manager.batched_allocate(4096, 5)
+
+        assert len(results) == 5
+        for addr, allocated_size in results:
+            assert addr >= 0
+            assert allocated_size == 4096
+
+        assert _no_overlap(results)
+        assert manager.get_free_size() == 0
+        assert manager.check_consistency()
+
+    def test_batch_allocate_all_memory(self):
+        """Test batched_allocate that exhausts all memory."""
+        size = 4096 * 8
+        manager = AddressManager(size)
+
+        results = manager.batched_allocate(4096, 8)
+
+        assert len(results) == 8
+        assert _no_overlap(results)
+        assert manager.get_free_size() == 0
+        assert manager.total_allocated_size == size
+        assert manager.check_consistency()
+
+    def test_batch_failure_out_of_memory(self):
+        """Test that batched_allocate fails when out of memory."""
+        size = 4096 * 2
+        manager = AddressManager(size)
+
+        # First batch succeeds
+        manager.batched_allocate(4096, 2)
+
+        # Second batch should fail - no memory left
+        with pytest.raises(RuntimeError):
+            manager.batched_allocate(4096, 1)
+
+        assert manager.check_consistency()
+
+    def test_batch_failure_insufficient_memory(self):
+        """Test batched_allocate fails when not enough memory for all blocks."""
+        size = 4096 * 3
+        manager = AddressManager(size)
+
+        # Request 5 blocks but only 3 pages available
+        with pytest.raises(RuntimeError):
+            manager.batched_allocate(4096, 5)
+
+        # Verify no partial allocation occurred (atomicity)
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_batch_failure_too_large_single_block(self):
+        """Test batched_allocate failure when single block size is too large."""
+        size = 4096 * 2
+        manager = AddressManager(size)
+
+        with pytest.raises(RuntimeError):
+            manager.batched_allocate(size + 1, 1)
+
+        assert manager.total_allocated_size == 0
+        assert manager.check_consistency()
+
+    def test_batch_atomicity_on_failure(self):
+        """Test that failed batched_allocate does not modify state."""
+        size = 4096 * 5
+        manager = AddressManager(size)
+
+        # Pre-allocate some memory
+        manager.allocate(4096 * 2)
+        allocated_before = manager.total_allocated_size
+        free_before = manager.get_free_size()
+
+        # This should fail - requesting more than available
+        with pytest.raises(RuntimeError):
+            manager.batched_allocate(4096, 10)
+
+        # State should be unchanged
+        assert manager.total_allocated_size == allocated_before
+        assert manager.get_free_size() == free_before
+        assert manager.check_consistency()
+
+    def test_batch_after_free(self):
+        """Test batched_allocate after freeing memory."""
+        size = 4096 * 5
+        manager = AddressManager(size)
+
+        # Allocate all
+        addrs = []
+        for _ in range(5):
+            addr, alloc_size = manager.allocate(4096)
+            addrs.append((addr, alloc_size))
+
+        # Free 3 blocks
+        for addr, alloc_size in addrs[:3]:
+            manager.free(addr, alloc_size)
+
+        # Batched allocate should succeed with 3 blocks
+        results = manager.batched_allocate(4096, 3)
+        assert len(results) == 3
+        assert _no_overlap(results + addrs[3:])
+        assert manager.check_consistency()
+
+    def test_batch_from_fragmented_memory(self):
+        """Test batched_allocate from fragmented free list."""
+        size = 4096 * 6
+        manager = AddressManager(size)
+
+        # Allocate all 6 blocks
+        addrs = []
+        for _ in range(6):
+            addr, alloc_size = manager.allocate(4096)
+            addrs.append((addr, alloc_size))
+
+        # Free alternating blocks to create fragmentation
+        # Free blocks 0, 2, 4 => 3 free non-contiguous blocks
+        manager.free(addrs[0][0], addrs[0][1])
+        manager.free(addrs[2][0], addrs[2][1])
+        manager.free(addrs[4][0], addrs[4][1])
+
+        assert manager.get_free_size() == 4096 * 3
+
+        # Batched allocate 3 blocks from fragmented free list
+        results = manager.batched_allocate(4096, 3)
+        assert len(results) == 3
+        # All allocated + still-occupied blocks should not overlap
+        all_allocs = results + [addrs[1], addrs[3], addrs[5]]
+        assert _no_overlap(all_allocs)
+        assert manager.get_free_size() == 0
+        assert manager.check_consistency()
+
+    def test_batch_carves_from_large_block(self):
+        """
+        Test batched_allocate carving multiple chunks from a single large free block.
+        """
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        # All memory is one contiguous free block
+        results = manager.batched_allocate(4096, 5)
+        assert len(results) == 5
+        assert _no_overlap(results)
+        assert manager.total_allocated_size == 4096 * 5
+        assert manager.get_free_size() == 4096 * 5
+        assert manager.check_consistency()
+
+    def test_batch_with_non_aligned_size(self):
+        """Test batched_allocate with non-aligned size request."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        results = manager.batched_allocate(100, 3)
+
+        assert len(results) == 3
+        for addr, allocated_size in results:
+            assert addr >= 0
+            assert allocated_size == 4096  # Aligned up to 4096
+        assert _no_overlap(results)
+        assert manager.total_allocated_size == 4096 * 3
+        assert manager.check_consistency()
+
+    def test_batch_mixed_with_single_allocate(self):
+        """Test batched_allocate interleaved with single allocate."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        # Single allocate
+        addr1, size1 = manager.allocate(4096)
+
+        # Batch allocate
+        batch_results = manager.batched_allocate(4096, 3)
+
+        # Single allocate again
+        addr2, size2 = manager.allocate(4096)
+
+        all_allocs = [(addr1, size1), (addr2, size2)] + batch_results
+        assert _no_overlap(all_allocs)
+        assert manager.total_allocated_size == 4096 * 5
+        assert manager.check_consistency()
+
+    def test_batch_after_sbrk(self):
+        """Test batched_allocate after sbrk expansion."""
+        size = 4096 * 2
+        manager = AddressManager(size)
+
+        # Allocate all initial memory
+        manager.allocate(4096)
+        manager.allocate(4096)
+        assert manager.get_free_size() == 0
+
+        # Expand
+        manager.sbrk(4096 * 5)
+
+        # Now batched_allocate should succeed
+        results = manager.batched_allocate(4096, 3)
+        assert len(results) == 3
+        assert _no_overlap(results)
+        assert manager.check_consistency()
+
+    def test_batch_free_and_rebatch(self):
+        """Test free after batched_allocate and re-allocate."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        # Batched allocate
+        results = manager.batched_allocate(4096, 5)
+        assert len(results) == 5
+
+        # Free all batched blocks
+        for addr, alloc_size in results:
+            manager.free(addr, alloc_size)
+
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+        # Re-allocate the same batch
+        results2 = manager.batched_allocate(4096, 5)
+        assert len(results2) == 5
+        assert _no_overlap(results2)
+        assert manager.check_consistency()
+
+    def test_batch_size_zero(self):
+        """Test batched_allocate with batch_size=0."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        results = manager.batched_allocate(4096, 0)
+        assert len(results) == 0
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+
+class TestAddressManagerFree:
+    """Test free functionality."""
+
+    def test_simple_free(self):
+        """Test simple allocation and free."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        addr, alloc_size = manager.allocate(1000)
+        assert manager.total_allocated_size == alloc_size
+
+        manager.free(addr, alloc_size)
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_free_and_realloc(self):
+        """Test that freed memory can be reallocated."""
+        size = 4096 * 3
+        manager = AddressManager(size)
+
+        # Allocate all memory
+        addr1, size1 = manager.allocate(4096)
+        addr2, size2 = manager.allocate(4096)
+        addr3, size3 = manager.allocate(4096)
+
+        # Free middle block
+        manager.free(addr2, size2)
+        assert manager.get_free_size() == 4096
+        assert manager.check_consistency()
+
+        # Reallocate should succeed (freed block is available)
+        addr_new, size_new = manager.allocate(4096)
+        assert addr_new >= 0
+        assert size_new == 4096
+        assert manager.check_consistency()
+
+    def test_coalescing_allows_larger_allocation(self):
+        """Test that freeing adjacent blocks allows larger allocation."""
+        size = 4096 * 4
+        manager = AddressManager(size)
+
+        # Allocate three blocks
+        addr1, size1 = manager.allocate(4096)
+        addr2, size2 = manager.allocate(4096)
+        addr3, size3 = manager.allocate(4096)
+
+        # Free blocks 2 and 3
+        manager.free(addr3, size3)
+        manager.free(addr2, size2)
+
+        assert manager.get_free_size() == size - size1
+        assert manager.check_consistency()
+
+        # Should be able to allocate a block of size 2*4096
+        # (only possible if blocks were coalesced)
+        addr_large, size_large = manager.allocate(8192)
+        assert addr_large >= 0
+        assert size_large == 8192
+        assert manager.check_consistency()
+
+    def test_coalescing_predecessor(self):
+        """Test that freeing blocks coalesces with predecessor."""
+        size = 4096 * 4
+        manager = AddressManager(size)
+
+        # Allocate three blocks
+        addr1, size1 = manager.allocate(4096)
+        addr2, size2 = manager.allocate(4096)
+        addr3, size3 = manager.allocate(4096)
+
+        # Free blocks 1 and 2
+        manager.free(addr1, size1)
+        manager.free(addr2, size2)
+
+        assert manager.get_free_size() == size - size3
+        assert manager.check_consistency()
+
+        # Should be able to allocate a block of size 2*4096
+        addr_large, size_large = manager.allocate(8192)
+        assert addr_large >= 0
+        assert size_large == 8192
+        assert manager.check_consistency()
+
+    def test_coalescing_both_sides(self):
+        """Test that freeing a block coalesces with both neighbors."""
+        size = 4096 * 5
+        manager = AddressManager(size)
+
+        # Allocate four blocks
+        addr1, size1 = manager.allocate(4096)
+        addr2, size2 = manager.allocate(4096)
+        addr3, size3 = manager.allocate(4096)
+        addr4, size4 = manager.allocate(4096)
+
+        # Free blocks 1, 3, then 2
+        # Block 2 should coalesce with both block 1 and block 3
+        manager.free(addr1, size1)
+        manager.free(addr3, size3)
+        manager.free(addr2, size2)
+
+        assert manager.get_free_size() == size - size4
+        assert manager.check_consistency()
+
+        # Should be able to allocate a block of size 3*4096
+        addr_large, size_large = manager.allocate(12288)
+        assert addr_large >= 0
+        assert size_large == 12288
+        assert manager.check_consistency()
+
+    def test_free_all(self):
+        """Test freeing all allocated memory."""
+        size = 4096 * 5
+        manager = AddressManager(size)
+
+        allocations: List[Tuple[int, int]] = []
+        for _ in range(5):
+            addr, alloc_size = manager.allocate(4096)
+            allocations.append((addr, alloc_size))
+
+        assert manager.get_free_size() == 0
+
+        # Free in reverse order
+        for addr, alloc_size in reversed(allocations):
+            manager.free(addr, alloc_size)
+
+        assert manager.get_free_size() == size
+        assert manager.total_allocated_size == 0
+        assert manager.check_consistency()
+
+    def test_free_random_order(self):
+        """Test freeing blocks in random order."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        allocations: List[Tuple[int, int]] = []
+        for _ in range(10):
+            addr, alloc_size = manager.allocate(4096)
+            allocations.append((addr, alloc_size))
+
+        assert manager.get_free_size() == 0
+
+        # Free in a shuffled order
+        # Standard
+        import random
+
+        random.seed(42)
+        shuffled = allocations.copy()
+        random.shuffle(shuffled)
+
+        for addr, alloc_size in shuffled:
+            manager.free(addr, alloc_size)
+            assert manager.check_consistency()
+
+        assert manager.get_free_size() == size
+        assert manager.total_allocated_size == 0
+        assert manager.check_consistency()
+
+
+class TestAddressManagerSbrk:
+    """Test sbrk (expand) functionality."""
+
+    def test_sbrk_basic(self):
+        """Test basic sbrk expansion."""
+        initial_size = 4096 * 2
+        manager = AddressManager(initial_size)
+
+        # Allocate all initial memory
+        manager.allocate(4096)
+        manager.allocate(4096)
+
+        assert manager.get_free_size() == 0
+
+        # Expand
+        manager.sbrk(4096 * 2)
+
+        # Should now be able to allocate more
+        addr, alloc_size = manager.allocate(4096)
+        assert addr >= 0
+        assert alloc_size == 4096
+        assert manager.check_consistency()
+
+    def test_sbrk_increases_free_size(self):
+        """Test that sbrk increases free size."""
+        size = 4096 * 3
+        manager = AddressManager(size)
+
+        # Allocate two blocks
+        manager.allocate(4096)
+        manager.allocate(4096)
+
+        free_before = manager.get_free_size()
+        assert free_before == 4096
+
+        # Expand
+        manager.sbrk(4096)
+        assert manager.get_free_size() == free_before + 4096
+        assert manager.check_consistency()
+
+    def test_sbrk_allows_larger_allocation(self):
+        """Test that sbrk allows allocating larger blocks."""
+        size = 4096 * 2
+        manager = AddressManager(size)
+
+        # Allocate one block
+        manager.allocate(4096)
+
+        # Try to allocate 2 pages - should fail
+        with pytest.raises(RuntimeError):
+            manager.allocate(8192)
+
+        # Expand
+        manager.sbrk(4096 * 2)
+
+        # Now it should succeed
+        addr, alloc_size = manager.allocate(8192)
+        assert addr >= 0
+        assert alloc_size == 8192
+        assert manager.check_consistency()
+
+    def test_sbrk_after_fragmentation(self):
+        """Test sbrk after memory fragmentation."""
+        size = 4096 * 4
+        manager = AddressManager(size)
+
+        # Allocate all
+        addrs = []
+        for _ in range(4):
+            addr, alloc_size = manager.allocate(4096)
+            addrs.append((addr, alloc_size))
+
+        # Create fragmentation by freeing alternating blocks
+        manager.free(addrs[1][0], addrs[1][1])
+        manager.free(addrs[3][0], addrs[3][1])
+
+        # Expand
+        manager.sbrk(4096)
+        assert manager.check_consistency()
+
+        # Free size should include the expansion
+        assert manager.get_free_size() == 4096 * 3  # 2 freed + 1 expanded
+
+
+class TestAddressManagerConsistency:
+    """Test consistency checking."""
+
+    def test_consistency_empty(self):
+        """Test consistency on empty manager."""
+        manager = AddressManager(4096 * 10)
+        assert manager.check_consistency()
+
+    def test_consistency_full(self):
+        """Test consistency on fully allocated manager."""
+        manager = AddressManager(4096 * 3)
+
+        manager.allocate(4096)
+        manager.allocate(4096)
+        manager.allocate(4096)
+
+        assert manager.check_consistency()
+
+    def test_consistency_after_operations(self):
+        """Test consistency after various operations."""
+        manager = AddressManager(4096 * 10)
+
+        # Series of operations
+        _ = manager.allocate(4096)
+        a2 = manager.allocate(8192)
+        _ = manager.allocate(4096)
+        assert manager.check_consistency()
+
+        manager.free(a2[0], a2[1])
+        assert manager.check_consistency()
+
+        manager.allocate(4096)
+        assert manager.check_consistency()
+
+        manager.sbrk(4096)
+        assert manager.check_consistency()
+
+    def test_free_size_plus_allocated_equals_total(self):
+        """Test that free_size + allocated_size equals total size."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        # After various operations, invariant should hold
+        allocations = []
+        for _ in range(5):
+            addr, alloc_size = manager.allocate(4096)
+            allocations.append((addr, alloc_size))
+            assert manager.get_free_size() + manager.total_allocated_size == size
+
+        for addr, alloc_size in allocations[:3]:
+            manager.free(addr, alloc_size)
+            assert manager.get_free_size() + manager.total_allocated_size == size
+
+        # After sbrk, total size increases
+        manager.sbrk(4096 * 5)
+        new_total = size + 4096 * 5
+        assert manager.get_free_size() + manager.total_allocated_size == new_total
+
+
+class TestAddressManagerThreadSafety:
+    """Test thread-safety of AddressManager."""
+
+    def test_concurrent_allocations(self):
+        """Test that concurrent allocations are thread-safe."""
+        # Large enough for many concurrent allocations
+        size = 4096 * 1000
+        manager = AddressManager(size)
+
+        num_threads = 50
+        allocations_per_thread = 10
+        results: List[List[Tuple[int, int]]] = [[] for _ in range(num_threads)]
+        errors: List[Exception] = []
+
+        def allocate_worker(thread_id: int):
+            try:
+                for _ in range(allocations_per_thread):
+                    addr, alloc_size = manager.allocate(4096)
+                    results[thread_id].append((addr, alloc_size))
+            except Exception as e:
+                errors.append(e)
+
+        threads = []
+        for i in range(num_threads):
+            t = threading.Thread(target=allocate_worker, args=(i,))
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Check no errors occurred
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+
+        # Verify all allocations succeeded
+        all_allocations = [a for thread_results in results for a in thread_results]
+        assert len(all_allocations) == num_threads * allocations_per_thread
+
+        # Verify no overlapping addresses
+        assert _no_overlap(all_allocations)
+
+        # Verify consistency
+        assert manager.check_consistency()
+        assert (
+            manager.total_allocated_size == num_threads * allocations_per_thread * 4096
+        )
+
+    def test_concurrent_frees(self):
+        """Test that concurrent frees are thread-safe."""
+        size = 4096 * 100
+        manager = AddressManager(size)
+
+        # Pre-allocate blocks
+        allocations = []
+        for _ in range(100):
+            addr, alloc_size = manager.allocate(4096)
+            allocations.append((addr, alloc_size))
+
+        errors: List[Exception] = []
+
+        def free_worker(allocs: List[Tuple[int, int]]):
+            try:
+                for addr, alloc_size in allocs:
+                    manager.free(addr, alloc_size)
+            except Exception as e:
+                errors.append(e)
+
+        # Split allocations among threads
+        num_threads = 10
+        chunk_size = len(allocations) // num_threads
+        threads = []
+        for i in range(num_threads):
+            start = i * chunk_size
+            end = start + chunk_size if i < num_threads - 1 else len(allocations)
+            t = threading.Thread(target=free_worker, args=(allocations[start:end],))
+            threads.append(t)
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Check no errors
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+
+        # Verify all memory is freed
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_concurrent_alloc_and_free(self):
+        """Test concurrent allocations and frees."""
+        size = 4096 * 500
+        manager = AddressManager(size)
+
+        num_iterations = 100
+        errors: List[Exception] = []
+        allocated_lock = threading.Lock()
+        allocated: List[Tuple[int, int]] = []
+
+        def alloc_worker():
+            try:
+                for _ in range(num_iterations):
+                    try:
+                        addr, alloc_size = manager.allocate(4096)
+                        with allocated_lock:
+                            allocated.append((addr, alloc_size))
+                    except RuntimeError:
+                        # Out of memory is expected sometimes
+                        pass
+            except Exception as e:
+                errors.append(e)
+
+        def free_worker():
+            try:
+                for _ in range(num_iterations):
+                    to_free = None
+                    with allocated_lock:
+                        if allocated:
+                            to_free = allocated.pop()
+                    if to_free:
+                        manager.free(to_free[0], to_free[1])
+            except Exception as e:
+                errors.append(e)
+
+        # Run allocators and freers concurrently
+        threads = []
+        for _ in range(5):
+            threads.append(threading.Thread(target=alloc_worker))
+            threads.append(threading.Thread(target=free_worker))
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        # Check no errors
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+
+        # Verify consistency
+        assert manager.check_consistency()
+
+        # Free remaining allocations
+        for addr, alloc_size in allocated:
+            manager.free(addr, alloc_size)
+
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_concurrent_with_thread_pool(self):
+        """Test using ThreadPoolExecutor for concurrent operations."""
+        size = 4096 * 200
+        manager = AddressManager(size)
+
+        def alloc_and_free():
+            addr, alloc_size = manager.allocate(4096)
+            # Small delay to increase chance of race conditions
+            manager.free(addr, alloc_size)
+            return True
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=20) as executor:
+            futures = [executor.submit(alloc_and_free) for _ in range(100)]
+            results = [f.result() for f in concurrent.futures.as_completed(futures)]
+
+        assert all(results)
+        assert manager.total_allocated_size == 0
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_stress_test_concurrent_operations(self):
+        """Stress test with many concurrent operations."""
+        size = 4096 * 2000
+        manager = AddressManager(size)
+
+        num_threads = 20
+        operations_per_thread = 50
+        errors: List[Exception] = []
+
+        allocated_lock = threading.Lock()
+        allocated: List[Tuple[int, int]] = []
+
+        def worker(thread_id: int):
+            try:
+                for i in range(operations_per_thread):
+                    if i % 2 == 0:
+                        # Allocate
+                        try:
+                            addr, alloc_size = manager.allocate(4096)
+                            with allocated_lock:
+                                allocated.append((addr, alloc_size))
+                        except RuntimeError:
+                            pass
+                    else:
+                        # Free
+                        to_free = None
+                        with allocated_lock:
+                            if allocated:
+                                to_free = allocated.pop()
+                        if to_free:
+                            manager.free(to_free[0], to_free[1])
+            except Exception as e:
+                errors.append(e)
+
+        threads = [
+            threading.Thread(target=worker, args=(i,)) for i in range(num_threads)
+        ]
+
+        for t in threads:
+            t.start()
+
+        for t in threads:
+            t.join()
+
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+        assert manager.check_consistency()
+
+        # Clean up remaining allocations
+        for addr, alloc_size in allocated:
+            manager.free(addr, alloc_size)
+
+        assert manager.total_allocated_size == 0
+        assert manager.check_consistency()
+
+    def test_concurrent_batched_allocations(self):
+        """Test that concurrent batched_allocate calls are thread-safe."""
+        size = 4096 * 2000
+        manager = AddressManager(size)
+
+        num_threads = 20
+        batch_per_thread = 10
+        results: List[List[Tuple[int, int]]] = [[] for _ in range(num_threads)]
+        errors: List[Exception] = []
+
+        def batch_alloc_worker(thread_id: int):
+            try:
+                batch = manager.batched_allocate(4096, batch_per_thread)
+                results[thread_id] = batch
+            except Exception as e:
+                errors.append(e)
+
+        threads = [
+            threading.Thread(target=batch_alloc_worker, args=(i,))
+            for i in range(num_threads)
+        ]
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+
+        all_allocations = [a for thread_results in results for a in thread_results]
+        assert len(all_allocations) == num_threads * batch_per_thread
+        assert _no_overlap(all_allocations)
+        assert manager.check_consistency()
+        assert manager.total_allocated_size == num_threads * batch_per_thread * 4096
+
+    def test_concurrent_batched_alloc_and_free(self):
+        """Test concurrent batched_allocate and free operations."""
+        size = 4096 * 1000
+        manager = AddressManager(size)
+
+        num_iterations = 20
+        errors: List[Exception] = []
+        allocated_lock = threading.Lock()
+        allocated: List[Tuple[int, int]] = []
+
+        def batch_alloc_worker():
+            try:
+                for _ in range(num_iterations):
+                    try:
+                        batch = manager.batched_allocate(4096, 5)
+                        with allocated_lock:
+                            allocated.extend(batch)
+                    except RuntimeError:
+                        pass
+            except Exception as e:
+                errors.append(e)
+
+        def free_worker():
+            try:
+                for _ in range(num_iterations * 5):
+                    to_free = None
+                    with allocated_lock:
+                        if allocated:
+                            to_free = allocated.pop()
+                    if to_free:
+                        manager.free(to_free[0], to_free[1])
+            except Exception as e:
+                errors.append(e)
+
+        threads = []
+        for _ in range(5):
+            threads.append(threading.Thread(target=batch_alloc_worker))
+            threads.append(threading.Thread(target=free_worker))
+
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        assert len(errors) == 0, f"Errors occurred: {errors}"
+        assert manager.check_consistency()
+
+        # Clean up remaining allocations
+        for addr, alloc_size in allocated:
+            manager.free(addr, alloc_size)
+
+        assert manager.total_allocated_size == 0
+        assert manager.check_consistency()
+
+
+class TestAddressManagerEdgeCases:
+    """Test edge cases."""
+
+    def test_zero_size_manager(self):
+        """Test manager with zero size."""
+        manager = AddressManager(0)
+        assert manager.get_free_size() == 0
+        assert manager.total_allocated_size == 0
+        assert manager.check_consistency()
+
+        with pytest.raises(RuntimeError):
+            manager.allocate(1)
+
+    def test_alignment_edge_cases(self):
+        """Test allocation with sizes at alignment boundaries."""
+        align = 4096
+        manager = AddressManager(align * 10, align_bytes=align)
+
+        # Exactly one byte less than alignment
+        addr1, size1 = manager.allocate(align - 1)
+        assert size1 == align
+
+        # Exactly one byte more than alignment
+        addr2, size2 = manager.allocate(align + 1)
+        assert size2 == align * 2
+
+        # Verify no overlap
+        assert _no_overlap([(addr1, size1), (addr2, size2)])
+        assert manager.check_consistency()
+
+    def test_many_small_allocations(self):
+        """Test many small allocations."""
+        size = 4096 * 100
+        manager = AddressManager(size)
+
+        allocations = []
+        for _ in range(100):
+            addr, alloc_size = manager.allocate(1)  # Will be aligned to 4096
+            allocations.append((addr, alloc_size))
+
+        assert manager.get_free_size() == 0
+        assert _no_overlap(allocations)
+        assert manager.check_consistency()
+
+        # Free all
+        for addr, alloc_size in allocations:
+            manager.free(addr, alloc_size)
+
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_single_large_allocation(self):
+        """Test allocating entire space at once."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        addr, alloc_size = manager.allocate(size)
+        assert addr >= 0
+        assert alloc_size == size
+        assert manager.get_free_size() == 0
+        assert manager.check_consistency()
+
+        manager.free(addr, alloc_size)
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_repeated_alloc_free_cycle(self):
+        """Test repeated allocation and free cycles."""
+        size = 4096 * 5
+        manager = AddressManager(size)
+
+        for _ in range(100):
+            addr, alloc_size = manager.allocate(4096 * 3)
+            assert manager.check_consistency()
+            manager.free(addr, alloc_size)
+            assert manager.check_consistency()
+
+        assert manager.get_free_size() == size
+        assert manager.total_allocated_size == 0
+
+    def test_varied_allocation_sizes(self):
+        """Test allocations of varied sizes."""
+        size = 4096 * 100
+        manager = AddressManager(size)
+
+        allocations = []
+        # Allocate blocks of different sizes
+        for num_pages in [1, 2, 3, 5, 8, 13]:
+            addr, alloc_size = manager.allocate(4096 * num_pages)
+            allocations.append((addr, alloc_size))
+
+        assert _no_overlap(allocations)
+        assert manager.check_consistency()
+
+        # Free all
+        for addr, alloc_size in allocations:
+            manager.free(addr, alloc_size)
+
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_batched_allocate_varied_batch_sizes(self):
+        """Test batched_allocate with varied batch sizes."""
+        size = 4096 * 100
+        manager = AddressManager(size)
+
+        all_allocs: List[Tuple[int, int]] = []
+
+        for batch_size in [1, 2, 5, 10, 3]:
+            results = manager.batched_allocate(4096, batch_size)
+            assert len(results) == batch_size
+            all_allocs.extend(results)
+
+        assert _no_overlap(all_allocs)
+        assert manager.total_allocated_size == 4096 * (1 + 2 + 5 + 10 + 3)
+        assert manager.check_consistency()
+
+        # Free all
+        for addr, alloc_size in all_allocs:
+            manager.free(addr, alloc_size)
+
+        assert manager.get_free_size() == size
+        assert manager.check_consistency()
+
+    def test_batched_allocate_from_zero_size_manager(self):
+        """Test batched_allocate on a zero-size manager."""
+        manager = AddressManager(0)
+
+        with pytest.raises(RuntimeError):
+            manager.batched_allocate(1, 1)
+
+        assert manager.check_consistency()
+
+    def test_batched_allocate_repeated_cycles(self):
+        """Test repeated batched_allocate and free cycles."""
+        size = 4096 * 10
+        manager = AddressManager(size)
+
+        for _ in range(50):
+            results = manager.batched_allocate(4096, 5)
+            assert len(results) == 5
+            assert manager.check_consistency()
+
+            for addr, alloc_size in results:
+                manager.free(addr, alloc_size)
+            assert manager.check_consistency()
+
+        assert manager.get_free_size() == size
+        assert manager.total_allocated_size == 0
+
+
+def _no_overlap(allocations: List[Tuple[int, int]]) -> bool:
+    """
+    Check that no allocations overlap.
+
+    Args:
+        allocations: List of (address, size) tuples
+
+    Returns:
+        True if no overlaps, False otherwise
+    """
+    # Sort by address
+    sorted_allocs = sorted(allocations, key=lambda x: x[0])
+
+    for i in range(len(sorted_allocs) - 1):
+        addr1, size1 = sorted_allocs[i]
+        addr2, size2 = sorted_allocs[i + 1]
+        # Check that first block ends before second block starts
+        if addr1 + size1 > addr2:
+            return False
+
+    return True
diff --git a/tests/v1/test_basic_check.py b/tests/v1/test_basic_check.py
new file mode 100644
index 0000000..a6be999
--- /dev/null
+++ b/tests/v1/test_basic_check.py
@@ -0,0 +1,266 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from types import ModuleType
+from unittest.mock import AsyncMock, patch
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.basic_check import main, parse_args
+from lmcache.v1.check import CheckModeRegistry, check_mode
+
+# --------------- CheckModeRegistry tests ---------------
+
+
+class TestCheckModeRegistry:
+    """Tests for CheckModeRegistry."""
+
+    def test_register_and_get(self) -> None:
+        reg = CheckModeRegistry()
+        reg.loaded = True  # skip auto-loading
+
+        async def dummy(**kw):
+            pass
+
+        reg.register("foo", dummy)
+        assert reg.get_mode("foo") is dummy
+
+    def test_register_duplicate_raises(self) -> None:
+        reg = CheckModeRegistry()
+        reg.loaded = True
+
+        reg.register("dup", lambda: None)
+        with pytest.raises(ValueError, match="already registered"):
+            reg.register("dup", lambda: None)
+
+    def test_get_mode_returns_none_for_unknown(self) -> None:
+        reg = CheckModeRegistry()
+        reg.loaded = True
+        assert reg.get_mode("nonexistent") is None
+
+    def test_load_modes_discovers_decorated_functions(
+        self, tmp_path, monkeypatch
+    ) -> None:
+        """Verify that load_modes discovers check_mode_ modules."""
+        reg = CheckModeRegistry()
+
+        # Create a fake check_mode_ module
+        mod = ModuleType("check_mode_fake")
+
+        async def fake_func(**kw):
+            pass
+
+        fake_func.is_check_mode = True  # type: ignore[attr-defined]
+        fake_func.mode_name = "fake"  # type: ignore[attr-defined]
+        mod.fake_func = fake_func  # type: ignore[attr-defined]
+
+        # Patch os.listdir to return our fake module
+        monkeypatch.setattr(
+            "os.listdir",
+            lambda _: ["check_mode_fake.py", "utils.py"],
+        )
+        monkeypatch.setattr(
+            "importlib.import_module",
+            lambda name, package=None: mod,
+        )
+
+        reg.load_modes()
+        assert reg.loaded is True
+        assert "fake" in reg.modes
+        assert reg.modes["fake"] is fake_func
+
+    def test_load_modes_skips_import_errors(self, monkeypatch) -> None:
+        """load_modes should not crash on ImportError."""
+        reg = CheckModeRegistry()
+
+        def raiser(name, package=None):
+            raise ImportError("boom")
+
+        monkeypatch.setattr(
+            "os.listdir",
+            lambda _: ["check_mode_bad.py"],
+        )
+        monkeypatch.setattr("importlib.import_module", raiser)
+
+        reg.load_modes()
+        assert reg.loaded is True
+        assert len(reg.modes) == 0
+
+    def test_load_modes_called_once(self, monkeypatch) -> None:
+        """Second call to load_modes should be a no-op."""
+        reg = CheckModeRegistry()
+
+        call_count = 0
+
+        def counting_listdir(path):
+            nonlocal call_count
+            call_count += 1
+            return []
+
+        monkeypatch.setattr("os.listdir", counting_listdir)
+
+        reg.load_modes()
+        reg.load_modes()
+        assert call_count == 1
+
+    def test_get_mode_triggers_load(self, monkeypatch) -> None:
+        """get_mode should call load_modes if not yet loaded."""
+        reg = CheckModeRegistry()
+        assert reg.loaded is False
+
+        monkeypatch.setattr("os.listdir", lambda _: [])
+
+        reg.get_mode("any")
+        assert reg.loaded is True
+
+
+# --------------- check_mode decorator tests ---------------
+
+
+class TestCheckModeDecorator:
+    """Tests for the @check_mode decorator."""
+
+    def test_decorator_sets_attributes(self) -> None:
+        @check_mode("my_mode")
+        async def handler(**kw):
+            pass
+
+        assert handler.is_check_mode is True  # type: ignore[attr-defined]
+        assert handler.mode_name == "my_mode"  # type: ignore[attr-defined]
+
+    def test_decorated_function_still_callable(self) -> None:
+        @check_mode("callable_check")
+        def sync_fn():
+            return 42
+
+        assert sync_fn() == 42
+
+
+# --------------- parse_args tests ---------------
+
+
+class TestParseArgs:
+    """Tests for basic_check.parse_args."""
+
+    def test_required_mode(self) -> None:
+        with patch(
+            "sys.argv",
+            ["basic_check", "--mode", "test_remote"],
+        ):
+            args = parse_args()
+        assert args.mode == "test_remote"
+
+    @pytest.mark.parametrize(
+        "flag,value,attr,expected",
+        [
+            ("--model", "/my/model", "model", "/my/model"),
+            ("--num-keys", "50", "num_keys", 50),
+            ("--concurrency", "8", "concurrency", 8),
+            ("--offset", "10", "offset", 10),
+        ],
+    )
+    def test_optional_flags(
+        self,
+        flag: str,
+        value: str,
+        attr: str,
+        expected: object,
+    ) -> None:
+        with patch(
+            "sys.argv",
+            ["basic_check", "--mode", "x", flag, value],
+        ):
+            args = parse_args()
+        assert getattr(args, attr) == expected
+
+    def test_defaults(self) -> None:
+        with patch("sys.argv", ["basic_check", "--mode", "x"]):
+            args = parse_args()
+        assert args.num_keys == 5
+        assert args.concurrency == 16
+        assert args.offset == 0
+        assert args.model == "/lmcache_test_model/"
+        assert args.l2_adapter == []
+        assert args.obj_size is None
+        assert args.kv_dtype is None
+        assert args.settle_time == 0.0
+
+
+# --------------- main() tests ---------------
+
+
+class TestMain:
+    """Tests for basic_check.main (async)."""
+
+    @pytest.mark.asyncio
+    async def test_list_mode(self, monkeypatch, capsys) -> None:
+        """--mode list should print available modes."""
+        monkeypatch.setattr("sys.argv", ["basic_check", "--mode", "list"])
+
+        fake_reg = CheckModeRegistry()
+        fake_reg.loaded = True
+        fake_reg.modes["alpha"] = lambda: None
+        fake_reg.modes["beta"] = lambda: None
+
+        monkeypatch.setattr("lmcache.v1.basic_check.registry", fake_reg)
+
+        await main()
+        out = capsys.readouterr().out
+        assert "alpha" in out
+        assert "beta" in out
+
+    @pytest.mark.asyncio
+    async def test_unknown_mode(self, monkeypatch, capsys) -> None:
+        """Unknown mode should print an error."""
+        monkeypatch.setattr(
+            "sys.argv",
+            ["basic_check", "--mode", "no_such_mode"],
+        )
+
+        fake_reg = CheckModeRegistry()
+        fake_reg.loaded = True  # empty registry
+
+        monkeypatch.setattr("lmcache.v1.basic_check.registry", fake_reg)
+
+        await main()
+        out = capsys.readouterr().out
+        assert "Unknown mode" in out
+
+    @pytest.mark.asyncio
+    async def test_valid_mode_invokes_function(self, monkeypatch) -> None:
+        """A valid mode should be called with parsed args."""
+        handler = AsyncMock()
+
+        fake_reg = CheckModeRegistry()
+        fake_reg.loaded = True
+        fake_reg.register("run_it", handler)
+
+        monkeypatch.setattr("lmcache.v1.basic_check.registry", fake_reg)
+        monkeypatch.setattr(
+            "sys.argv",
+            [
+                "basic_check",
+                "--mode",
+                "run_it",
+                "--num-keys",
+                "5",
+                "--concurrency",
+                "2",
+                "--offset",
+                "3",
+            ],
+        )
+
+        await main()
+
+        handler.assert_awaited_once_with(
+            model="/lmcache_test_model/",
+            num_keys=5,
+            concurrency=2,
+            offset=3,
+            l2_adapter=[],
+            obj_size=None,
+            kv_dtype=None,
+            settle_time=0.0,
+        )
diff --git a/tests/v1/test_bloom_filter.py b/tests/v1/test_bloom_filter.py
new file mode 100644
index 0000000..b619ca4
--- /dev/null
+++ b/tests/v1/test_bloom_filter.py
@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for lmcache.v1.utils.bloom_filter.
+
+Covers add / contains semantics, batch insertion, clear, and the
+statistics helpers across both string and integer item types.
+"""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.utils.bloom_filter import BloomFilter
+
+
+class TestSizing:
+    def test_default_construction(self) -> None:
+        bf = BloomFilter()
+        assert bf.expected_elements == 1_000_000
+        assert bf.false_positive_rate == 0.01
+        assert bf.size > 0
+        assert bf.hash_count >= 1
+        assert bf.item_count == 0
+
+    def test_smaller_target_rate_yields_larger_bit_array(self) -> None:
+        loose = BloomFilter(expected_elements=1000, false_positive_rate=0.1)
+        tight = BloomFilter(expected_elements=1000, false_positive_rate=0.001)
+        assert tight.size > loose.size
+        assert tight.hash_count >= loose.hash_count
+
+    @pytest.mark.parametrize(
+        "expected_elements,false_positive_rate,expected_size,expected_hash_count",
+        [
+            # Hard-coded golden values from the standard Bloom-filter formulas
+            # m = -n * ln(p) / (ln 2)^2 and k = (m / n) * ln 2, with the
+            # implementation's int()/max(1, ...) rounding applied. Hard-coding
+            # avoids the tautology of reproducing the production formula in
+            # the test body — these values are independently re-derivable.
+            (5000, 0.01, 47925, 6),
+            (1000, 0.01, 9585, 6),
+            (10000, 0.001, 143775, 9),
+        ],
+    )
+    def test_optimal_sizing_matches_golden_values(
+        self,
+        expected_elements: int,
+        false_positive_rate: float,
+        expected_size: int,
+        expected_hash_count: int,
+    ) -> None:
+        bf = BloomFilter(
+            expected_elements=expected_elements,
+            false_positive_rate=false_positive_rate,
+        )
+        assert bf.size == expected_size
+        assert bf.hash_count == expected_hash_count
+
+
+class TestContainsString:
+    def test_no_false_negatives(self) -> None:
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        items = [f"key-{i}" for i in range(500)]
+        for item in items:
+            bf.add(item)
+        for item in items:
+            assert bf.contains(item)
+        assert bf.item_count == 500
+
+    def test_empty_filter_contains_nothing(self) -> None:
+        bf = BloomFilter(expected_elements=100, false_positive_rate=0.01)
+        assert not bf.contains("anything")
+        assert not bf.contains("")
+
+    def test_false_positive_rate_within_reasonable_bound(self) -> None:
+        # Honour the design budget loosely: with 1000 inserted and 10000
+        # never-inserted items, observed false-positive rate should stay
+        # below 5x the target. Inputs are fixed strings hashed with SHA-256,
+        # so this test is fully deterministic (no RNG, no flakes).
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        for i in range(1000):
+            bf.add(f"in-{i}")
+        misses = sum(1 for i in range(10000) if bf.contains(f"out-{i}"))
+        observed_rate = misses / 10000
+        assert observed_rate < 0.05
+
+
+class TestContainsInt:
+    def test_int_items_round_trip(self) -> None:
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        for n in (0, 1, 2, 255, 65536, 10**18):
+            bf.add(n)
+            assert bf.contains(n)
+        # item_count counts add() calls regardless of duplicates
+        assert bf.item_count == 6
+
+    def test_int_zero_round_trips(self) -> None:
+        # n=0 exercises the (0).to_bytes(0, ...) edge case in _hashes;
+        # call out separately so a regression here is unambiguous.
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        bf.add(0)
+        assert bf.contains(0)
+
+    @pytest.mark.parametrize("value", [0, 1, 42, 123456789])
+    def test_int_and_str_use_disjoint_hash_inputs(self, value: int) -> None:
+        # The contract is structural, not probabilistic: ints are hashed via
+        # int.to_bytes(...) while strings are hashed via f"{item}_{i}".encode().
+        # The byte streams are disjoint by construction, so contains(str(value))
+        # is deterministically False after only add(value) — no RNG involved.
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        bf.add(value)
+        assert bf.contains(value)
+        assert not bf.contains(str(value))
+
+
+class TestBatchInsert:
+    """Batch insertion takes raw bit positions, not items.
+
+    Tests use hand-picked positions to verify the dedup-by-bitmap behavior
+    without relying on the BloomFilter's internal hashing details.
+    """
+
+    def test_batch_returns_unique_count_for_distinct_positions(self) -> None:
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        # Three position sets, each touching disjoint bits → all three are new.
+        added = bf.add_batch_with_hashes_and_check(
+            [[0, 1, 2], [10, 11, 12], [20, 21, 22]]
+        )
+        assert added == 3
+        assert bf.item_count == 3
+
+    def test_batch_dedups_when_all_bits_already_set(self) -> None:
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        first = bf.add_batch_with_hashes_and_check([[5, 6, 7]])
+        # Same positions again — every bit is already set, so it counts as 0.
+        second = bf.add_batch_with_hashes_and_check([[5, 6, 7]])
+        assert first == 1
+        assert second == 0
+        assert bf.item_count == 1
+
+    def test_batch_treats_partial_overlap_as_new(self) -> None:
+        bf = BloomFilter(expected_elements=1000, false_positive_rate=0.01)
+        bf.add_batch_with_hashes_and_check([[0, 1]])
+        # Position 2 is unset → the whole positions list is treated as new.
+        added = bf.add_batch_with_hashes_and_check([[0, 1, 2]])
+        assert added == 1
+        assert bf.item_count == 2
+
+
+class TestClearAndStats:
+    def test_clear_resets_state(self) -> None:
+        bf = BloomFilter(expected_elements=100, false_positive_rate=0.01)
+        for i in range(50):
+            bf.add(f"k{i}")
+        assert bf.get_bit_set() > 0
+        bf.clear()
+        assert bf.item_count == 0
+        assert bf.get_bit_set() == 0
+        assert bf.get_fill_rate() == 0.0
+        for i in range(50):
+            assert not bf.contains(f"k{i}")
+
+    def test_memory_usage_matches_size(self) -> None:
+        bf = BloomFilter(expected_elements=10000, false_positive_rate=0.01)
+        assert bf.get_memory_usage_bytes() == bf.size // 8
+
+    def test_statistics_shape_and_values(self) -> None:
+        bf = BloomFilter(expected_elements=500, false_positive_rate=0.01)
+        for i in range(10):
+            bf.add(f"k{i}")
+        stats = bf.get_statistics()
+        assert set(stats.keys()) == {
+            "size_mb",
+            "hash_count",
+            "item_count",
+            "bits_set",
+            "fill_rate",
+            "expected_elements",
+            "false_positive_rate",
+        }
+        assert stats["item_count"] == 10
+        assert stats["expected_elements"] == 500
+        assert stats["false_positive_rate"] == pytest.approx(0.01)
+        assert stats["bits_set"] > 0
+        assert 0.0 < stats["fill_rate"] < 1.0
+        # Mirror production: size_mb derives from get_memory_usage_bytes(),
+        # which uses floor division. Reproducing `bf.size / 8` here only
+        # matched production when bf.size happened to be divisible by 8.
+        assert stats["size_mb"] == pytest.approx(
+            bf.get_memory_usage_bytes() / 1024 / 1024
+        )
diff --git a/tests/v1/test_c_ops_fallback_parity.py b/tests/v1/test_c_ops_fallback_parity.py
new file mode 100644
index 0000000..666310f
--- /dev/null
+++ b/tests/v1/test_c_ops_fallback_parity.py
@@ -0,0 +1,396 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Verify that every public function/enum in python_ops_fallback that also
+exists in c_ops has a matching signature.
+
+Does NOT require python_ops_fallback to implement everything in c_ops —
+only checks the intersection. If you implement a function in the fallback,
+its signature must match c_ops exactly.
+
+Default value rules (relaxed):
+  - If c_ops has a default, fallback MUST also have one with the same value —
+    otherwise callers relying on the default will break.
+  - If c_ops has NO default, fallback MAY add one (superset, backward-compatible).
+
+Requires CUDA (c_ops must be importable). Automatically skipped on CPU-only CI.
+"""
+
+# Standard
+import enum
+import inspect
+import re
+
+# Third Party
+import pytest
+
+# First Party
+import lmcache.python_ops_fallback as fallback
+
+try:
+    # First Party
+    import lmcache.c_ops as c_ops
+
+    HAS_C_OPS = c_ops is not fallback
+except ImportError:
+    HAS_C_OPS = False
+
+
+# ── Helpers ──
+
+
+def _public_callables(module):
+    """Return {name: obj} for all public, non-dunder, non-enum callables."""
+    return {
+        name: obj
+        for name, obj in inspect.getmembers(module)
+        if not name.startswith("_")
+        and callable(obj)
+        and not (inspect.isclass(obj) and issubclass(obj, enum.Enum))
+        and not hasattr(obj, "__members__")  # exclude pybind11 enums
+        and getattr(obj, "__module__", None) == getattr(module, "__name__", None)
+    }
+
+
+def _public_enums(module):
+    """Return {name: obj} for all public enum-like classes.
+
+    Detects both Python enum.Enum subclasses and pybind11 enums.
+    pybind11 enums have a ``__members__`` dict attribute.
+    """
+    return {
+        name: obj
+        for name, obj in inspect.getmembers(module, inspect.isclass)
+        if not name.startswith("_")
+        and (issubclass(obj, enum.Enum) or hasattr(obj, "__members__"))
+        and getattr(obj, "__module__", None) == getattr(module, "__name__", None)
+    }
+
+
+def _get_enum_members(enum_cls):
+    """Extract {name: value} from a Python enum or pybind11 enum."""
+    if issubclass(enum_cls, enum.Enum):
+        return {m.name: m.value for m in enum_cls}
+    elif hasattr(enum_cls, "__members__"):
+        return {name: int(val) for name, val in enum_cls.__members__.items()}
+    return {}
+
+
+def _public_descriptor_classes(module: object) -> dict[str, type]:
+    """Return {name: cls} for public classes that are neither enums
+    nor plain functions — e.g. pybind11 ``py::class_<>`` types like
+    ``PageBufferShapeDesc``.
+    """
+    return {
+        name: obj
+        for name, obj in inspect.getmembers(module, inspect.isclass)
+        if not name.startswith("_")
+        and not (issubclass(obj, enum.Enum) or hasattr(obj, "__members__"))
+        and callable(obj)
+        and getattr(obj, "__module__", None) == getattr(module, "__name__", None)
+    }
+
+
+def _normalize_default(value_str):
+    """Normalize a default value string for comparison.
+
+    Handles differences between pybind11 docstring representation
+    and Python inspect representation:
+      - 'false'/'False' → False
+      - 'true'/'True'   → True
+      - numeric strings  → float/int
+      - quoted strings   → unquoted
+    """
+    s = value_str.strip()
+
+    if s.lower() == "false":
+        return False
+    if s.lower() == "true":
+        return True
+    if s == "None" or s == "none":
+        return None
+
+    # Strip quotes: 'foo' or "foo" → foo
+    if (s.startswith("'") and s.endswith("'")) or (
+        s.startswith('"') and s.endswith('"')
+    ):
+        return s[1:-1]
+
+    # Try numeric
+    try:
+        return int(s)
+    except ValueError:
+        pass
+    try:
+        return float(s)
+    except ValueError:
+        pass
+
+    # Return as-is for anything else (e.g. enum values)
+    return s
+
+
+def _parse_docstring_params(func):
+    """Parse pybind11 docstring to extract [(name, has_default, default_value)].
+
+    pybind11 generates docstrings like:
+        func_name(arg1: type1, arg2: type2 = default) -> ret
+
+    Returns None if parsing fails.
+    default_value is the normalized value if present, or None if no default.
+    """
+    doc = getattr(func, "__doc__", None)
+    if not doc:
+        return None
+
+    first_line = doc.strip().split("\n")[0]
+    match = re.match(r"\w+\((.*)\)\s*->", first_line)
+    if not match:
+        return None
+
+    params_str = match.group(1)
+    if not params_str.strip():
+        return []
+
+    # Split on commas that are NOT inside brackets/parens
+    params = []
+    depth = 0
+    current = []
+    for char in params_str:
+        if char in "([":
+            depth += 1
+            current.append(char)
+        elif char in ")]":
+            depth -= 1
+            current.append(char)
+        elif char == "," and depth == 0:
+            params.append("".join(current).strip())
+            current = []
+        else:
+            current.append(char)
+    if current:
+        params.append("".join(current).strip())
+
+    result = []
+    for param in params:
+        colon_idx = param.find(":")
+        if colon_idx == -1:
+            name = param.split("=")[0].strip()
+        else:
+            name = param[:colon_idx].strip()
+
+        has_default = "=" in param
+        default_value = None
+        if has_default:
+            default_value = _normalize_default(param.split("=", 1)[1])
+
+        result.append((name, has_default, default_value))
+
+    return result
+
+
+def _get_python_params(func):
+    """Extract [(name, has_default, default_value)] via inspect.signature."""
+    try:
+        sig = inspect.signature(func)
+    except ValueError as err:
+        raise ValueError("no signature found for {!r}".format(func)) from err
+    result = []
+    for p in sig.parameters.values():
+        has_default = p.default is not inspect.Parameter.empty
+        default_value = None
+        if has_default:
+            default_value = _normalize_default(repr(p.default))
+        result.append((p.name, has_default, default_value))
+    return result
+
+
+def _has_real_names(params):
+    """Check if parameter names are real (not arg0, arg1, ...)."""
+    return params and not any(re.match(r"^arg\d+$", name) for name, _, _ in params)
+
+
+# ── Discover the intersection automatically ──
+
+# Functions intentionally excluded from parity checks.
+_EXCLUDED_FUNCS: set[str] = set()
+
+_fallback_callables = _public_callables(fallback)
+_c_ops_callables = _public_callables(c_ops) if HAS_C_OPS else {}
+_shared_func_names = sorted(
+    (set(_fallback_callables) & set(_c_ops_callables)) - _EXCLUDED_FUNCS
+)
+
+_fallback_enums = _public_enums(fallback)
+_c_ops_enums = _public_enums(c_ops) if HAS_C_OPS else {}
+_shared_enum_names = sorted(set(_fallback_enums) & set(_c_ops_enums))
+
+_fallback_descs = _public_descriptor_classes(fallback)
+_c_ops_descs = _public_descriptor_classes(c_ops) if HAS_C_OPS else {}
+_shared_desc_names = sorted(set(_fallback_descs) & set(_c_ops_descs))
+
+
+# ── Tests ──
+
+
+@pytest.mark.skipif(not HAS_C_OPS, reason="c_ops not available (no CUDA)")
+@pytest.mark.parametrize(
+    "func_name",
+    _shared_func_names if _shared_func_names else ["__placeholder__"],
+)
+def test_function_signature_parity(func_name):
+    """For every function that python_ops_fallback chose to implement,
+    its signature must match c_ops exactly.
+
+    When c_ops has real py::arg() names  → check names, count, defaults.
+    When c_ops only has arg0/arg1/...    → check count and defaults only.
+
+    Default rules (relaxed):
+      c_ops has default, fallback does NOT      → FAIL (callers will break)
+      c_ops has default, fallback has different  → FAIL (silent behavior change)
+      c_ops has NO default, fallback does        → OK   (backward-compatible)
+    """
+    if func_name == "__placeholder__":
+        pytest.skip("No shared functions found between c_ops and fallback")
+
+    c_func = _c_ops_callables[func_name]
+    py_func = _fallback_callables[func_name]
+
+    # Get c_ops params: try docstring first (more reliable for pybind11),
+    # then inspect.signature
+    c_params = _parse_docstring_params(c_func)
+    if c_params is None:
+        try:
+            c_params = _get_python_params(c_func)
+        except (ValueError, TypeError):
+            pass
+
+    if c_params is None:
+        pytest.skip(f"Cannot inspect c_ops.{func_name} signature")
+
+    # Get fallback params: always via inspect.signature
+    try:
+        py_params = _get_python_params(py_func)
+    except (ValueError, TypeError):
+        pytest.skip(f"Cannot inspect fallback.{func_name} signature")
+
+    c_has_names = _has_real_names(c_params)
+
+    # 1. Always check parameter count
+    assert len(c_params) == len(py_params), (
+        f"{func_name}: parameter count mismatch\n"
+        f"  c_ops ({len(c_params)}):    {[p[0] for p in c_params]}\n"
+        f"  fallback ({len(py_params)}): {[p[0] for p in py_params]}"
+    )
+
+    # 2. Check each parameter
+    for i, (
+        (c_name, c_has_def, c_default),
+        (py_name, py_has_def, py_default),
+    ) in enumerate(zip(c_params, py_params, strict=False)):
+        # Check names only when c_ops has real py::arg() names
+        if c_has_names:
+            assert c_name == py_name, (
+                f"{func_name}: param #{i} name mismatch — "
+                f"c_ops: '{c_name}', fallback: '{py_name}'"
+            )
+
+        # Relaxed default check:
+        # Only fail if c_ops has a default but fallback does NOT,
+        # or if both have defaults but values differ.
+        # Fallback having an extra default is fine (backward-compatible).
+        if c_has_def:
+            assert py_has_def, (
+                f"{func_name}: param #{i} ('{py_name}') — "
+                f"c_ops has default={c_default!r} but fallback has NO default. "
+                f"Callers relying on the default will break."
+            )
+            assert c_default == py_default, (
+                f"{func_name}: param #{i} ('{py_name}') — "
+                f"default value mismatch: "
+                f"c_ops={c_default!r}, fallback={py_default!r}"
+            )
+
+
+@pytest.mark.skipif(not HAS_C_OPS, reason="c_ops not available (no CUDA)")
+@pytest.mark.parametrize(
+    "enum_name",
+    _shared_enum_names if _shared_enum_names else ["__placeholder__"],
+)
+def test_enum_parity(enum_name):
+    """For every enum that python_ops_fallback defines,
+    its members and values must match c_ops."""
+    if enum_name == "__placeholder__":
+        pytest.skip("No shared enums found between c_ops and fallback")
+
+    c_members = _get_enum_members(_c_ops_enums[enum_name])
+    py_members = _get_enum_members(_fallback_enums[enum_name])
+
+    assert c_members == py_members, (
+        f"{enum_name} mismatch:\n  c_ops:    {c_members}\n  fallback: {py_members}"
+    )
+
+
+# ── Coverage tests: every c_ops API must have a fallback ──
+
+
+@pytest.mark.skipif(not HAS_C_OPS, reason="c_ops not available (no CUDA)")
+def test_all_c_ops_callables_have_fallback() -> None:
+    """Every public callable in c_ops must exist in
+    python_ops_fallback."""
+    missing = sorted(set(_c_ops_callables) - set(_fallback_callables) - _EXCLUDED_FUNCS)
+    assert not missing, f"c_ops callables missing from python_ops_fallback: {missing}"
+
+
+@pytest.mark.skipif(not HAS_C_OPS, reason="c_ops not available (no CUDA)")
+def test_all_c_ops_enums_have_fallback() -> None:
+    """Every public enum in c_ops must exist in
+    python_ops_fallback."""
+    missing = sorted(set(_c_ops_enums) - set(_fallback_enums))
+    assert not missing, f"c_ops enums missing from python_ops_fallback: {missing}"
+
+
+@pytest.mark.skipif(not HAS_C_OPS, reason="c_ops not available (no CUDA)")
+def test_all_c_ops_descriptors_have_fallback() -> None:
+    """Every public descriptor class in c_ops must exist in
+    python_ops_fallback."""
+    missing = sorted(set(_c_ops_descs) - set(_fallback_descs))
+    assert not missing, (
+        f"c_ops descriptor classes missing from python_ops_fallback: {missing}"
+    )
+
+
+@pytest.mark.skipif(not HAS_C_OPS, reason="c_ops not available (no CUDA)")
+@pytest.mark.parametrize(
+    "cls_name",
+    _shared_desc_names if _shared_desc_names else ["__placeholder__"],
+)
+def test_descriptor_class_parity(cls_name: str) -> None:
+    """For every descriptor class shared between c_ops and the fallback,
+    every public, non-callable attribute on the c_ops instance must also
+    be present on the fallback instance.
+    """
+    if cls_name == "__placeholder__":
+        pytest.skip("No shared descriptor classes found")
+
+    # Attribute parity requires a no-arg constructor on both sides. Some plan
+    # value structs (e.g. StagingCopy, KernelGroupSpec) only expose an
+    # args-required constructor and no readable fields, so there is nothing to
+    # compare — skip them rather than fail on construction.
+    try:
+        c_inst = _c_ops_descs[cls_name]()
+    except TypeError:
+        pytest.skip(f"{cls_name} has no no-arg constructor in c_ops")
+
+    py_inst = _fallback_descs[cls_name]()
+
+    def _public_data_attrs(inst: object) -> set[str]:
+        return {
+            a
+            for a in dir(inst)
+            if not a.startswith("_") and not callable(getattr(inst, a))
+        }
+
+    missing = sorted(_public_data_attrs(c_inst) - _public_data_attrs(py_inst))
+    assert not missing, (
+        f"{cls_name}: fallback is missing attributes present on c_ops: {missing}"
+    )
diff --git a/tests/v1/test_cache_engine.py b/tests/v1/test_cache_engine.py
new file mode 100644
index 0000000..f177c18
--- /dev/null
+++ b/tests/v1/test_cache_engine.py
@@ -0,0 +1,2118 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections import OrderedDict
+from copy import deepcopy
+from unittest.mock import MagicMock, patch
+import os
+import random
+import shlex
+import subprocess
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import (
+    CacheEngineKey,
+    mock_up_broadcast_fn,
+    mock_up_broadcast_object_fn,
+)
+from lmcache.v1.cache_engine import LMCacheEngine, LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventStatus, EventType
+
+# Local
+from .utils import (
+    DummyLMCacheAsyncLookupServer,
+    check_paged_kv_cache_equal,
+    create_gpu_connector,
+    create_test_memory_obj,
+    dumb_metadata,
+    generate_kv_cache_paged_list_tensors,
+    generate_tokens,
+    has_cufile,
+    recover_engine_states,
+)
+
+# Optional override for tempfile root. In CI we point this at a GDS-capable
+# host-backed mount (see .buildkite/k3_tests/unit/run.sh); locally it's
+# unset and tempfile falls back to its default. Direct-I/O-backed paths are
+# required for GDS tests (cuFile err=5027 on overlayfs/tmpfs).
+_TEST_TMPDIR = os.environ.get("LMCACHE_TEST_TMPDIR") or None
+
+
+def get_expected_count(token_len, save_unfull_chunk, chunk_size):
+    """Calculate expected token count based on save_unfull_chunk setting.
+
+    Args:
+        token_len: Total token length
+        save_unfull_chunk: Whether to save partial chunks
+        chunk_size: Chunk size for alignment
+
+    Returns:
+        If save_unfull_chunk is True, returns token_len as-is.
+        Otherwise, returns chunk-aligned count (rounded down).
+    """
+    if save_unfull_chunk:
+        return token_len
+    return (token_len // chunk_size) * chunk_size
+
+
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_same_retrieve_store(save_unfull_chunk, autorelease_v1):
+    device = "cuda"
+    num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+
+    chunk_size = 256
+    kv_shape = (32, 2, chunk_size, 8, 128)
+
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    original_retrieved_cache = deepcopy(retrieved_cache)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    # Check the kv cache and the retrieval buffer are not the same
+    check_paged_kv_cache_equal(retrieved_cache, original_retrieved_cache, slot_mapping)
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(retrieved_cache, kv_cache, slot_mapping)
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size, remote_url=None, save_unfull_chunk=save_unfull_chunk
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    """ test retrieve empty """
+    ret_mask = engine.retrieve(
+        tokens, kvcaches=retrieved_cache, slot_mapping=slot_mapping
+    )
+    recover_engine_states(engine)
+
+    length = torch.sum(ret_mask)
+    assert length == 0
+    check_paged_kv_cache_equal(retrieved_cache, original_retrieved_cache, slot_mapping)
+    """ test store """
+    engine.store(tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    recover_engine_states(engine)
+
+    """ Store is async. Need to wait for the store to finish """
+    expected_count = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    timeout = 1.5
+    start_time = time.time()
+    while engine.lookup(tokens) < expected_count:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ test retrieve """
+    ret_mask = engine.retrieve(
+        tokens, kvcaches=retrieved_cache, slot_mapping=slot_mapping
+    )
+    recover_engine_states(engine)
+
+    length = torch.sum(ret_mask)
+    assert length == expected_count
+    check_paged_kv_cache_equal(retrieved_cache, kv_cache, slot_mapping[:expected_count])
+
+
+@pytest.mark.parametrize("chunk_size", [128, 256])
+@pytest.mark.parametrize("backend", ["cpu", "local_disk", "remote", "remote_cachegen"])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.parametrize("lmserver_v1_process", ["cpu"], indirect=True)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_retrieve_prefix(
+    chunk_size, backend, save_unfull_chunk, lmserver_v1_process, autorelease_v1
+):
+    url = None
+    remote_serde = None
+    check_equality = True
+    if "remote" in backend:
+        url = lmserver_v1_process.server_url
+        if backend == "remote_cachegen":
+            backend = "remote"
+            remote_serde = "cachegen"
+            check_equality = False
+        else:
+            remote_serde = "naive"
+    device = "cuda"
+    num_tokens = 2000
+    new_num_tokens = 1000
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    new_tokens = generate_tokens(new_num_tokens, device)
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    slot_mapping_full = random.sample(
+        range(0, num_blocks * block_size), num_tokens + new_num_tokens
+    )
+    slot_mapping = torch.tensor(slot_mapping_full[:num_tokens], device=device)
+
+    new_slot_mapping = torch.tensor(slot_mapping_full[-new_num_tokens:], device=device)
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend=backend,
+        remote_url=url,
+        remote_serde=remote_serde,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    """ test store """
+    t1 = time.perf_counter()
+    engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    recover_engine_states(engine)
+    t2 = time.perf_counter()
+    print(f"store {len(tokens)} takes {t2 - t1}")
+    """ Compute expected length """
+    expected_length = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    """ Store is async. Need to wait for the store to finish """
+    if backend == "cpu":
+        timeout = 1
+        search_range = "LocalCPUBackend"
+    elif backend == "local_disk":
+        timeout = 30
+        search_range = "LocalDiskBackend"
+    elif backend == "remote":
+        timeout = 30
+        search_range = "RemoteBackend"
+    start_time = time.time()
+    while engine.lookup(tokens, search_range=search_range) < expected_length:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ test retrieve """
+    # Get actual stored length - may be less than expected if is_last_prefill=False
+    # even when save_unfull_chunk=True
+    actual_stored_tokens = engine.lookup(torch.cat([tokens, new_tokens]))
+    t4 = time.perf_counter()
+    ret_mask = engine.retrieve(
+        torch.cat([tokens, new_tokens]),
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+
+    length = torch.sum(ret_mask)
+    t5 = time.perf_counter()
+    print(f"retrieve {length} takes {t5 - t4}")
+
+    # Use actual stored length (may be chunk-aligned even if save_unfull_chunk=True
+    # if is_last_prefill=False)
+    assert length == actual_stored_tokens
+
+    if check_equality:
+        check_paged_kv_cache_equal(
+            kv_cache,
+            retrieved_cache,
+            torch.cat([slot_mapping, new_slot_mapping])[:actual_stored_tokens],
+        )
+
+    if backend in ["local_disk"]:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+@pytest.mark.parametrize("chunk_size", [256])
+@pytest.mark.parametrize(
+    "backend",
+    ["cpu", "local_disk", "remote"],
+)
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.parametrize("lmserver_v1_process", ["cpu"], indirect=True)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_store_offset(
+    chunk_size, backend, save_unfull_chunk, lmserver_v1_process, autorelease_v1
+):
+    url = None
+    if backend == "remote":
+        url = lmserver_v1_process.server_url
+    device = "cuda"
+    num_tokens = 2000
+    num_suffix_tokens = 500
+    num_total_tokens = 3000
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_total_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_total_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend=backend,
+        remote_url=url,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    """ test store """
+    engine.store(
+        tokens[:num_tokens],
+        kvcaches=kv_cache,
+        slot_mapping=slot_mapping[:num_tokens],
+    )
+
+    offset_chunk_cnt = num_tokens // chunk_size
+    offset_length = offset_chunk_cnt * chunk_size
+    mask = torch.ones(num_tokens + num_suffix_tokens, device=device)
+    mask[:offset_length] = 0
+    engine.store(
+        tokens[: num_tokens + num_suffix_tokens],
+        kvcaches=kv_cache,
+        mask=mask,
+        slot_mapping=slot_mapping[: num_tokens + num_suffix_tokens],
+    )
+    recover_engine_states(engine)
+
+    """ Compute expected length """
+    total_tokens = num_tokens + num_suffix_tokens
+    expected_length = (total_tokens // chunk_size) * chunk_size
+    """ Store is async. Need to wait for the store to finish """
+    if backend == "cpu":
+        timeout = 1
+    elif backend == "local_disk":
+        timeout = 30
+    start_time = time.time()
+    while engine.lookup(tokens[: num_tokens + num_suffix_tokens]) < expected_length:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ test retrieve """
+    t4 = time.perf_counter()
+    ret_mask = engine.retrieve(
+        tokens, kvcaches=retrieved_cache, slot_mapping=slot_mapping
+    )
+    recover_engine_states(engine)
+
+    length = torch.sum(ret_mask)
+    t5 = time.perf_counter()
+    print(f"retrieve {length} takes {t5 - t4}")
+
+    assert length == expected_length
+    check_paged_kv_cache_equal(
+        kv_cache,
+        retrieved_cache,
+        slot_mapping[:expected_length],
+    )
+
+    if backend in ["local_disk"]:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+@pytest.mark.parametrize("chunk_size", [128])  # , 256])
+@pytest.mark.parametrize(
+    "backend",
+    [
+        # "cpu",
+        "local_disk"
+    ],
+)
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_mixed_retrieve(chunk_size, backend, save_unfull_chunk, autorelease_v1):
+    device = "cuda"
+    num_tokens = 2000
+    new_num_tokens = 1000
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    new_tokens = generate_tokens(new_num_tokens, device)
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    slot_mapping_full = random.sample(
+        range(0, num_blocks * block_size), num_tokens + new_num_tokens
+    )
+    slot_mapping = torch.tensor(slot_mapping_full[:num_tokens], device=device)
+
+    new_slot_mapping = torch.tensor(slot_mapping_full[-new_num_tokens:], device=device)
+
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size, backend=backend, save_unfull_chunk=save_unfull_chunk
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    """ test store """
+    engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    engine.store(new_tokens, kvcaches=kv_cache, slot_mapping=new_slot_mapping)
+    recover_engine_states(engine)
+    """ Store is async. Need to wait for the store to finish """
+    expected_length = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    if backend == "cpu":
+        timeout = 1
+        search_range = "LocalCPUBackend"
+    elif backend == "local_disk":
+        timeout = 30
+        search_range = "LocalDiskBackend"
+    start_time = time.time()
+    while engine.lookup(tokens, search_range=search_range) < expected_length:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ test retrieve """
+    # Check actual stored tokens for the combined tokens
+    # When tokens are stored separately, the total may be chunk-aligned
+    actual_stored_total = engine.lookup(
+        torch.cat([tokens, new_tokens]), search_range=search_range
+    )
+    ret_mask = engine.retrieve(
+        torch.cat([tokens, new_tokens]),
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    # Use actual stored total (may be chunk-aligned even if save_unfull_chunk=True
+    # if is_last_prefill=False)
+    assert length == actual_stored_total
+    check_paged_kv_cache_equal(
+        retrieved_cache,
+        kv_cache,
+        torch.cat([slot_mapping, new_slot_mapping])[:length],
+    )
+
+    """Wait for store to finish"""
+    expected_length = get_expected_count(new_num_tokens, save_unfull_chunk, chunk_size)
+    start_time = time.time()
+    while engine.lookup(new_tokens, search_range=search_range) < expected_length:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ test another retrieve """
+    ret_mask = engine.retrieve(
+        new_tokens, kvcaches=retrieved_cache, slot_mapping=new_slot_mapping
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    assert length == expected_length
+    check_paged_kv_cache_equal(
+        retrieved_cache, kv_cache, new_slot_mapping[:expected_length]
+    )
+
+    """ insert the mixed kv cache """
+    final_tokens = torch.cat([tokens, new_tokens])
+    engine.store(
+        final_tokens,
+        kvcaches=kv_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+
+    """Wait until store finishes"""
+    expected_length = get_expected_count(
+        num_tokens + new_num_tokens, save_unfull_chunk, chunk_size
+    )
+    start_time = time.time()
+    while (
+        engine.lookup(torch.cat([tokens, new_tokens]), search_range=search_range)
+        < expected_length
+    ):
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ should retrieve the mixed version """
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    ret_mask = engine.retrieve(
+        final_tokens,
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    assert length == expected_length
+
+    # Only check chunk-aligned tokens when save_unfull_chunk=False
+    check_paged_kv_cache_equal(
+        retrieved_cache,
+        kv_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping])[:expected_length],
+    )
+    """destroy local disk path"""
+    if backend in ["local_disk"]:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_store_kv_tensors_mask(save_unfull_chunk, autorelease_v1):
+    device = "cuda"
+    num_tokens = 1000
+    new_num_tokens = 2000
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+
+    chunk_size = 256
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+
+    new_tokens = generate_tokens(new_num_tokens, device)
+    final_tokens = torch.cat([tokens, new_tokens])
+
+    slot_mapping_full = random.sample(
+        range(0, num_blocks * block_size), num_tokens + new_num_tokens
+    )
+    slot_mapping = torch.tensor(slot_mapping_full[:num_tokens], device=device)
+
+    new_slot_mapping = torch.tensor(slot_mapping_full[-new_num_tokens:], device=device)
+
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size, save_unfull_chunk=save_unfull_chunk
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    """ Store some tokens with mask """
+    engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    recover_engine_states(engine)
+    """Wait until store finishes"""
+    expected_count = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    timeout = 1
+    start_time = time.time()
+    while engine.lookup(tokens) < expected_count:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+
+    prefix_length = engine.lookup(tokens)
+    assert prefix_length == expected_count, (
+        f"Expected {expected_count} prefix tokens, but got {prefix_length}"
+    )
+    """ Store more tokens """
+    # Re-query prefix_length for final_tokens (original flow)
+    prefix_length = engine.lookup(final_tokens)
+    # Store requires mask False count to be chunk-aligned
+    # When save_unfull_chunk=True, prefix_length may not be chunk-aligned,
+    # so we need to round it down to chunk boundary for the mask
+    num_falses_for_store = (prefix_length // chunk_size) * chunk_size
+    kv_tensor_mask = torch.ones_like(final_tokens, dtype=torch.bool)
+    kv_tensor_mask[:num_falses_for_store] = False
+
+    engine.store(
+        final_tokens,
+        mask=kv_tensor_mask,
+        kvcaches=kv_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+    """Wait until store finishes"""
+    expected_final_count = get_expected_count(
+        num_tokens + new_num_tokens, save_unfull_chunk, chunk_size
+    )
+    timeout = 1
+    start_time = time.time()
+    while engine.lookup(final_tokens) < expected_final_count:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+
+    prefix_length = engine.lookup(final_tokens)
+    assert prefix_length == expected_final_count, (
+        f"Expected {expected_final_count} prefix tokens, but got {prefix_length}"
+    )
+    """ retrieve the whole cache """
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+    ret_mask = engine.retrieve(
+        final_tokens,
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    check_paged_kv_cache_equal(
+        retrieved_cache,
+        kv_cache,
+        torch.cat([slot_mapping, new_slot_mapping])[:length],
+    )
+
+    """ retrieve cache with some mask:
+    """
+    # Retrieve requires mask False count to be chunk-aligned
+    # Original used chunk_size * 3 (768), which is tokens' chunk-aligned length
+    # When save_unfull_chunk=True, we need to ensure chunk alignment
+    num_falses = (num_tokens // chunk_size) * chunk_size
+    mask = torch.ones_like(final_tokens, dtype=torch.bool)
+    mask[:num_falses] = False
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+    ret_mask = engine.retrieve(
+        final_tokens,
+        mask=mask,
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    full_length = num_tokens + new_num_tokens
+    expected_length = full_length - num_falses
+    # When save_unfull_chunk=False, retrieved length may be chunk-aligned
+    expected_retrieved_length = get_expected_count(
+        expected_length, save_unfull_chunk, chunk_size
+    )
+    assert length == expected_retrieved_length
+
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(
+            retrieved_cache,
+            kv_cache,
+            torch.cat([slot_mapping, new_slot_mapping])[:full_length],
+        )
+    check_paged_kv_cache_equal(
+        retrieved_cache,
+        kv_cache,
+        torch.cat([slot_mapping, new_slot_mapping])[num_falses : num_falses + length],
+    )
+
+    mask[: num_falses + 5] = False
+    with pytest.raises(ValueError):
+        engine.retrieve(
+            final_tokens,
+            mask=mask,
+            kvcaches=retrieved_cache,
+            slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+        )
+        recover_engine_states(engine)
+
+
+@pytest.mark.parametrize("chunk_size", [128])
+@pytest.mark.parametrize(
+    "backend",
+    [
+        "local_cpu_disk_remote",
+    ],
+)
+@pytest.mark.parametrize(
+    "retrieve_from",
+    [
+        "local_cpu",
+        "local_disk",
+        "remote",
+    ],
+)
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.parametrize("lmserver_v1_process", ["cpu"], indirect=True)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_hierarchy_retrieve(
+    chunk_size,
+    backend,
+    retrieve_from,
+    save_unfull_chunk,
+    lmserver_v1_process,
+    autorelease_v1,
+):
+    url = None
+    if backend == "local_cpu_disk_remote":
+        url = lmserver_v1_process.server_url
+    device = "cuda"
+    num_tokens = 2000
+    new_num_tokens = 1000
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+
+    new_tokens = generate_tokens(new_num_tokens, device)
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+
+    slot_mapping = random.sample(
+        range(0, num_blocks * block_size), num_tokens + new_num_tokens
+    )
+    slot_mapping = torch.tensor(slot_mapping[:num_tokens], device=device)
+
+    new_slot_mapping = torch.tensor(slot_mapping[-new_num_tokens:], device=device)
+
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend=backend,
+        remote_url=url,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    """ test store """
+    t1 = time.perf_counter()
+    engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    recover_engine_states(engine)
+    t2 = time.perf_counter()
+    print(f"store {len(tokens)} takes {t2 - t1}")
+    """ Compute expected length """
+    expected_length = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    """ Store is async. Need to wait for the store to finish """
+    timeout = 1
+    start_time = time.time()
+    while engine.lookup(tokens) < expected_length:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ Wait until disk save is finished """
+    if retrieve_from in ["local_disk", "remote"]:
+        engine.storage_manager.clear(locations=["LocalCPUBackend"])
+        timeout = 30
+        start_time = time.time()
+        while (
+            engine.lookup(tokens, search_range=["LocalDiskBackend"]) < expected_length
+        ):
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+    """ Wait until remote save is finished """
+    if retrieve_from == "remote":
+        engine.storage_manager.clear(locations=["LocalCPUBackend"])
+        # FIXME: change this `clear`
+        engine.storage_manager.storage_backends["LocalDiskBackend"].dict.clear()
+        timeout = 30
+        start_time = time.time()
+        while engine.lookup(tokens, search_range=["RemoteBackend"]) < expected_length:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+    """ test retrieve """
+    t4 = time.perf_counter()
+    # Get actual stored length
+    actual_stored = engine.lookup(torch.cat([tokens, new_tokens]))
+    ret_mask = engine.retrieve(
+        torch.cat([tokens, new_tokens]),
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+    )
+    recover_engine_states(engine)
+
+    length = torch.sum(ret_mask)
+    t5 = time.perf_counter()
+    print(f"retrieve {length} takes {t5 - t4}")
+
+    # Use actual stored length for assertion
+    assert length == actual_stored
+    check_paged_kv_cache_equal(
+        retrieved_cache,
+        kv_cache,
+        torch.cat([slot_mapping, new_slot_mapping])[:actual_stored],
+    )
+
+    """ Wait until disk save is finished before deleting the directory"""
+    if backend in ["local_cpu_disk"]:
+        engine.storage_manager.clear(locations=["LocalCPUBackend"])
+        timeout = 30
+        start_time = time.time()
+        while engine.lookup(tokens) < expected_length:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+
+    if backend in ["local_cpu_disk"]:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+@pytest.mark.parametrize(
+    "backend",
+    [
+        "local_cpu_disk",
+    ],
+)
+@pytest.mark.parametrize(
+    "prefetch_from",
+    [
+        "local_disk",
+    ],
+)
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_prefetch_retrieve(
+    backend, prefetch_from, save_unfull_chunk, autorelease_v1
+):
+    device = "cuda"
+    num_tokens = 2000
+    new_num_tokens = 1000
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+    test_lookup_id = "test_lookup_id"
+
+    chunk_size = 256
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+    new_tokens = generate_tokens(new_num_tokens, device)
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype=dtype
+    )
+
+    slot_mapping = random.sample(
+        range(0, num_blocks * block_size), num_tokens + new_num_tokens
+    )
+    slot_mapping = torch.tensor(slot_mapping[:num_tokens], device=device)
+
+    new_slot_mapping = torch.tensor(slot_mapping[-new_num_tokens:], device=device)
+
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend=backend,
+        enable_async_loading=True,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+
+    async_lookup_server = DummyLMCacheAsyncLookupServer()
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        ),
+        async_lookup_server=async_lookup_server,
+    )
+
+    """ test store """
+    t1 = time.perf_counter()
+    engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    recover_engine_states(engine)
+    t2 = time.perf_counter()
+    print(f"store {len(tokens)} takes {t2 - t1}")
+    """ Compute expected length """
+    # For prefetch retrieve, we need to check what was actually stored
+    # Since this test uses async operations, we check the actual lookup result
+    expected_length = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    """ Wait for cpu store to finish """
+    timeout = 1
+    start_time = time.time()
+    actual_lookup = engine.lookup(tokens)
+    while actual_lookup < expected_length:
+        if time.time() - start_time > timeout:
+            raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+        time.sleep(0.01)
+    """ Delete cpu cache and wait until disk save finishes."""
+    if prefetch_from == "local_disk":
+        engine.storage_manager.clear(locations=["LocalCPUBackend"])
+        timeout = 30
+        start_time = time.time()
+        while engine.lookup(tokens) < expected_length:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.1)
+    """ Wait until disk load (prefetch) finishes and delete disk cache"""
+    engine.async_lookup_and_prefetch(
+        lookup_id=test_lookup_id, tokens=torch.cat([tokens, new_tokens])
+    )
+
+    if prefetch_from == "local_disk":
+        timeout = 60
+        start_time = time.time()
+        while (
+            engine.event_manager.get_event_status(EventType.LOADING, test_lookup_id)
+            != EventStatus.DONE
+        ):
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+        engine.storage_manager.storage_backends["LocalDiskBackend"].dict.clear()
+    """ test retrieve """
+    t4 = time.perf_counter()
+
+    # Get actual stored length for retrieve
+    actual_stored = engine.lookup(torch.cat([tokens, new_tokens]))
+    ret_mask = engine.retrieve(
+        torch.cat([tokens, new_tokens])[:actual_stored],
+        kvcaches=retrieved_cache,
+        slot_mapping=torch.cat([slot_mapping, new_slot_mapping]),
+        req_id=test_lookup_id,
+    )
+    recover_engine_states(engine)
+
+    length = torch.sum(ret_mask)
+    t5 = time.perf_counter()
+    print(f"retrieve {length} takes {t5 - t4}")
+
+    assert length == actual_stored
+    check_paged_kv_cache_equal(
+        retrieved_cache,
+        kv_cache,
+        torch.cat([slot_mapping, new_slot_mapping])[:actual_stored],
+    )
+
+    if backend in ["local_cpu_disk"]:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_async_lookup_and_prefetch_layerwise(autorelease_v1):
+    # Regression: before the fix, async_lookup_and_prefetch sent chunk-level
+    # CacheEngineKey objects into batched_async_contains, but store_layer
+    # populates hot_cache with per-layer LayerCacheEngineKey objects, so every
+    # lookup reported 0 hits. We stage hot_cache the way store_layer would and
+    # assert async_lookup_and_prefetch reports the full token count.
+    chunk_size = 256
+    num_layers = 4
+    num_chunks = 3
+    num_tokens = chunk_size * num_chunks
+    kv_shape = (num_layers, 2, chunk_size, 8, 128)
+    lookup_id = "layerwise-async-1"
+
+    captured: dict[str, int] = {}
+
+    class _RecordingAsyncLookupServer:
+        def send_response_to_scheduler(
+            self, lookup_id: str, retrieved_length: int
+        ) -> None:
+            captured[lookup_id] = retrieved_length
+
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend="cpu",
+        enable_async_loading=True,
+    )
+    cfg.use_layerwise = True
+
+    connector = create_gpu_connector(1024, num_layers)
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        ),
+        async_lookup_server=_RecordingAsyncLookupServer(),
+    )
+
+    tokens = generate_tokens(num_tokens, "cuda")
+    chunk_keys = [
+        key for _, _, key in engine.token_database.process_tokens(tokens=tokens)
+    ]
+    assert len(chunk_keys) == num_chunks
+
+    # Populate LocalCPUBackend.hot_cache the way store_layer would: one entry
+    # per (chunk, layer) keyed by LayerCacheEngineKey.
+    cpu_backend = engine.storage_manager.storage_backends["LocalCPUBackend"]
+    for chunk_key in chunk_keys:
+        for layer_key in chunk_key.split_layers(num_layers):
+            cpu_backend.submit_put_task(layer_key, create_test_memory_obj())
+
+    engine.async_lookup_and_prefetch(lookup_id=lookup_id, tokens=tokens)
+
+    deadline = time.time() + 10
+    while (
+        engine.event_manager.get_event_status(EventType.LOADING, lookup_id)
+        != EventStatus.DONE
+    ):
+        if time.time() > deadline:
+            raise TimeoutError("layerwise async lookup did not finish in time")
+        time.sleep(0.01)
+
+    assert captured.get(lookup_id) == num_tokens, (
+        f"Expected retrieved_length={num_tokens}, got {captured.get(lookup_id)}"
+    )
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_async_lookup_and_prefetch_layerwise_partial_layer_missing(autorelease_v1):
+    # When a single per-layer key is missing for one chunk, that chunk must be
+    # rounded down to a miss (the `// keys_per_chunk` round-down path).
+    chunk_size = 256
+    num_layers = 4
+    num_chunks = 3
+    num_tokens = chunk_size * num_chunks
+    kv_shape = (num_layers, 2, chunk_size, 8, 128)
+    lookup_id = "layerwise-async-2"
+
+    captured: dict[str, int] = {}
+
+    class _RecordingAsyncLookupServer:
+        def send_response_to_scheduler(
+            self, lookup_id: str, retrieved_length: int
+        ) -> None:
+            captured[lookup_id] = retrieved_length
+
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend="cpu",
+        enable_async_loading=True,
+    )
+    cfg.use_layerwise = True
+
+    connector = create_gpu_connector(1024, num_layers)
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        ),
+        async_lookup_server=_RecordingAsyncLookupServer(),
+    )
+
+    tokens = generate_tokens(num_tokens, "cuda")
+    chunk_keys = [
+        key for _, _, key in engine.token_database.process_tokens(tokens=tokens)
+    ]
+
+    # Stage chunks 0 and 1 fully; drop the last per-layer key of chunk 2.
+    cpu_backend = engine.storage_manager.storage_backends["LocalCPUBackend"]
+    for i, chunk_key in enumerate(chunk_keys):
+        per_layer_keys = chunk_key.split_layers(num_layers)
+        if i == len(chunk_keys) - 1:
+            per_layer_keys = per_layer_keys[:-1]
+        for layer_key in per_layer_keys:
+            cpu_backend.submit_put_task(layer_key, create_test_memory_obj())
+
+    engine.async_lookup_and_prefetch(lookup_id=lookup_id, tokens=tokens)
+
+    deadline = time.time() + 10
+    while (
+        engine.event_manager.get_event_status(EventType.LOADING, lookup_id)
+        != EventStatus.DONE
+    ):
+        if time.time() > deadline:
+            raise TimeoutError("layerwise async lookup did not finish in time")
+        time.sleep(0.01)
+
+    # First two chunks are complete; the partially-evicted third chunk is a
+    # miss, so the prefix-match retrieval pattern reports 2 chunks worth.
+    assert captured.get(lookup_id) == 2 * chunk_size, (
+        f"Expected retrieved_length={2 * chunk_size}, got {captured.get(lookup_id)}"
+    )
+
+
+@pytest.mark.parametrize("chunk_size", [256])
+@pytest.mark.parametrize(
+    "backend",
+    [
+        "cpu",
+        "local_disk",
+        "remote",
+        "local_disk_remote",
+        "local_cpu_disk_remote",
+    ],
+)
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.no_shared_allocator
+@pytest.mark.parametrize("lmserver_v1_process", ["cpu"], indirect=True)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_mem_leak(
+    chunk_size, backend, save_unfull_chunk, lmserver_v1_process, autorelease_v1
+):
+    url = None
+    if "remote" in backend:
+        url = lmserver_v1_process.server_url
+
+    device = "cuda"
+    num_tokens = 2000
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+    connector = create_gpu_connector(1024, 32)
+
+    tokens = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend=backend,
+        remote_url=url,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    engine.store(tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+    recover_engine_states(engine)
+
+    expected_length = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+    timeout = 30
+    """Wait until cpu store finishes"""
+    if "cpu" in backend:
+        start_time = time.time()
+        while engine.lookup(tokens, search_range=["LocalCPUBackend"]) < expected_length:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+    """Wait until disk store finishes"""
+    if "disk" in backend:
+        start_time = time.time()
+        while (
+            engine.lookup(tokens, search_range=["LocalDiskBackend"]) < expected_length
+        ):
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+
+    if "remote" in backend:
+        start_time = time.time()
+        while engine.lookup(tokens, search_range=["RemoteBackend"]) < expected_length:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+
+    tensor_memory_allocator = (
+        engine.storage_manager.allocator_backend.memory_allocator.pin_allocator
+    )
+    if "cpu" not in backend:
+        assert tensor_memory_allocator.total_allocated_size == 0
+    else:
+        assert tensor_memory_allocator.total_allocated_size > 0
+
+    if "disk" in backend:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+@pytest.mark.parametrize("chunk_size", [256])
+@pytest.mark.parametrize(
+    "backend",
+    [
+        "cpu",
+        "local_disk",
+    ],
+)
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_paged_retrieve_after_eviction(
+    chunk_size, backend, save_unfull_chunk, autorelease_v1
+):
+    device = "cuda"
+    # NOTE: The default backend cache size is 2 GB.
+    # 10000 tokens ia around 1.3 GB so a second retrieve will cause an eviction.
+    num_tokens = 10000
+    kv_shape = (32, 2, chunk_size, 8, 128)
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+    connector = create_gpu_connector(1024, 32)
+
+    tokens_1 = generate_tokens(num_tokens, device)
+    tokens_2 = generate_tokens(num_tokens, device)
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    slot_mapping_1 = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping_1 = torch.tensor(slot_mapping_1, device=device)
+    slot_mapping_2 = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping_2 = torch.tensor(slot_mapping_2, device=device)
+    """ initialize the engine """
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_size,
+        backend=backend,
+        save_unfull_chunk=save_unfull_chunk,
+    )
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            "test",
+            cfg,
+            dumb_metadata(kv_shape),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    expected_length = get_expected_count(num_tokens, save_unfull_chunk, chunk_size)
+
+    engine.store(tokens_1, kvcaches=kv_cache, slot_mapping=slot_mapping_1)
+    recover_engine_states(engine)
+
+    timeout = 30
+    if "disk" in backend:
+        start_time = time.time()
+        while (
+            engine.lookup(tokens_1, search_range=["LocalDiskBackend"]) < expected_length
+        ):
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+
+    engine.store(tokens_2, kvcaches=kv_cache, slot_mapping=slot_mapping_2)
+    recover_engine_states(engine)
+
+    """Wait until cpu store finishes"""
+    if "cpu" in backend:
+        start_time = time.time()
+        while (
+            engine.lookup(tokens_2, search_range=["LocalCPUBackend"]) < expected_length
+        ):
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+        assert (
+            engine.lookup(tokens_1, search_range=["LocalCPUBackend"]) < expected_length
+        )
+
+    """Wait until disk store finishes"""
+    if "disk" in backend:
+        start_time = time.time()
+        while (
+            engine.lookup(tokens_2, search_range=["LocalDiskBackend"]) < expected_length
+        ):
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"Operation timed out after {timeout} seconds.")
+            time.sleep(0.01)
+        assert (
+            engine.lookup(tokens_1, search_range=["LocalDiskBackend"]) < expected_length
+        )
+
+    ret_mask = engine.retrieve(
+        tokens_1,
+        kvcaches=retrieved_cache,
+        slot_mapping=slot_mapping_1,
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    assert length < num_tokens
+
+    ret_mask = engine.retrieve(
+        tokens_2,
+        kvcaches=retrieved_cache,
+        slot_mapping=slot_mapping_2,
+    )
+    recover_engine_states(engine)
+    length = torch.sum(ret_mask)
+    assert length == expected_length
+
+    if backend in ["local_disk"]:
+        subprocess.run(shlex.split("rm -rf local/disk_test/local_disk/"))
+
+
+def test_builder(autorelease_v1):
+    instance_id = "test"
+    cfg = LMCacheEngineConfig.from_legacy(chunk_size=256)
+    cfg2 = LMCacheEngineConfig.from_legacy(chunk_size=512)
+    connector = None
+    should_be_none = LMCacheEngineBuilder.get(instance_id)
+    assert should_be_none is None
+
+    _engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            instance_id,
+            cfg,
+            dumb_metadata(),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+    _engine2 = autorelease_v1(LMCacheEngineBuilder.get(instance_id))  # noqa
+
+    with pytest.raises(ValueError):
+        LMCacheEngineBuilder.get_or_create(
+            instance_id,
+            cfg2,
+            dumb_metadata(),
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_force_store_wait(autorelease_v1):
+    device = "cuda"
+    num_tokens = 10000
+    num_blocks = 5000
+    block_size = 16
+    dtype = torch.bfloat16
+
+    chunk_size = 256
+    kv_shape = (32, 2, chunk_size, 8, 128)
+
+    connector = create_gpu_connector(1024, 32)
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    num_requests = 8
+
+    def generate_random_slot_mapping(num_blocks, block_size, num_tokens, device):
+        slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        return torch.tensor(slot_mapping, device=device)
+
+    list_tokens = [generate_tokens(num_tokens, device) for _ in range(num_requests)]
+    list_slot_mappings = [
+        generate_random_slot_mapping(num_blocks, block_size, num_tokens, device)
+        for _ in range(num_requests)
+    ]
+
+    with tempfile.TemporaryDirectory(
+        dir=_TEST_TMPDIR, ignore_cleanup_errors=True
+    ) as temp_dir:
+        cfg = LMCacheEngineConfig.from_defaults(
+            local_cpu=False,
+            max_local_cpu_size=2,  # small cpu buffer
+            local_disk=temp_dir,
+            max_local_disk_size=20,
+            extra_config={"force_store_wait": True},
+        )
+
+        engine = autorelease_v1(
+            LMCacheEngineBuilder.get_or_create(
+                "test",
+                cfg,
+                dumb_metadata(kv_shape),
+                connector,
+                mock_up_broadcast_fn,
+                mock_up_broadcast_object_fn,
+            )
+        )
+
+        # Store kv cache into slow devices
+        for t, s in zip(list_tokens, list_slot_mappings, strict=False):
+            engine.store(t, kvcaches=kv_cache, slot_mapping=s)
+
+        # Sleep 10 seconds for the last request
+        time.sleep(20)
+
+        # No KV cache should be skipped
+        # With default save_unfull_chunk=False, we expect chunk-aligned count
+        chunk_size = 256
+        for t in list_tokens:
+            expected_count = (len(t) // chunk_size) * chunk_size
+            assert engine.lookup(t) == expected_count
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_builder_destroy(autorelease_v1):
+    """Test the destroy method of LMCacheEngineBuilder"""
+    instance_id = "test_destroy"
+    cfg = LMCacheEngineConfig.from_legacy(chunk_size=256)
+    connector = create_gpu_connector(1024, 32)
+
+    # Verify instance doesn't exist initially
+    should_be_none = LMCacheEngineBuilder.get(instance_id)
+    assert should_be_none is None
+
+    # Create an engine instance
+    engine = LMCacheEngineBuilder.get_or_create(
+        instance_id,
+        cfg,
+        dumb_metadata(),
+        connector,
+        mock_up_broadcast_fn,
+        mock_up_broadcast_object_fn,
+    )
+
+    # Verify instance exists
+    retrieved_engine = LMCacheEngineBuilder.get(instance_id)
+    assert retrieved_engine is not None
+    assert retrieved_engine is engine
+
+    # Verify internal state is populated
+    assert instance_id in LMCacheEngineBuilder._instances
+    assert instance_id in LMCacheEngineBuilder._cfgs
+    assert instance_id in LMCacheEngineBuilder._metadatas
+    assert instance_id in LMCacheEngineBuilder._stat_loggers
+
+    # Destroy the instance
+    LMCacheEngineBuilder.destroy(instance_id)
+
+    # Verify instance is completely removed
+    should_be_none_after_destroy = LMCacheEngineBuilder.get(instance_id)
+    assert should_be_none_after_destroy is None
+
+    # Verify all internal state is cleaned up
+    assert instance_id not in LMCacheEngineBuilder._instances
+    assert instance_id not in LMCacheEngineBuilder._cfgs
+    assert instance_id not in LMCacheEngineBuilder._metadatas
+    assert instance_id not in LMCacheEngineBuilder._stat_loggers
+
+    # Verify destroying non-existent instance doesn't raise error
+    LMCacheEngineBuilder.destroy("non_existent_id")  # Should not raise
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_builder_destroy_multiple_instances(autorelease_v1):
+    """Test destroying one instance doesn't affect others"""
+    instance_id1 = "test_destroy_1"
+    instance_id2 = "test_destroy_2"
+    cfg = LMCacheEngineConfig.from_legacy(chunk_size=256)
+    connector = create_gpu_connector(1024, 32)
+
+    # Create two engine instances
+    engine1 = LMCacheEngineBuilder.get_or_create(
+        instance_id1,
+        cfg,
+        dumb_metadata(),
+        connector,
+        mock_up_broadcast_fn,
+        mock_up_broadcast_object_fn,
+    )
+
+    engine2 = LMCacheEngineBuilder.get_or_create(
+        instance_id2,
+        cfg,
+        dumb_metadata(),
+        connector,
+        mock_up_broadcast_fn,
+        mock_up_broadcast_object_fn,
+    )
+
+    # Verify both instances exist
+    assert LMCacheEngineBuilder.get(instance_id1) is engine1
+    assert LMCacheEngineBuilder.get(instance_id2) is engine2
+
+    # Destroy only the first instance
+    LMCacheEngineBuilder.destroy(instance_id1)
+
+    # Verify first instance is destroyed but second remains
+    assert LMCacheEngineBuilder.get(instance_id1) is None
+    assert LMCacheEngineBuilder.get(instance_id2) is engine2
+
+    # Verify internal state for first instance is cleaned up
+    assert instance_id1 not in LMCacheEngineBuilder._instances
+    assert instance_id1 not in LMCacheEngineBuilder._cfgs
+    assert instance_id1 not in LMCacheEngineBuilder._metadatas
+    assert instance_id1 not in LMCacheEngineBuilder._stat_loggers
+
+    # Verify internal state for second instance remains
+    assert instance_id2 in LMCacheEngineBuilder._instances
+    assert instance_id2 in LMCacheEngineBuilder._cfgs
+    assert instance_id2 in LMCacheEngineBuilder._metadatas
+    assert instance_id2 in LMCacheEngineBuilder._stat_loggers
+
+    # Clean up second instance
+    LMCacheEngineBuilder.destroy(instance_id2)
+
+
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="Requires CUDA for test_multi_device_backends",
+)
+@pytest.mark.skipif(
+    not has_cufile(),
+    reason="Requires NVIDIA cuFile (libcufile.so). "
+    "Skipping on systems without GDS/cuFile (e.g., AMD ROCm).",
+)
+def test_multi_device_backends(save_unfull_chunk, autorelease_v1):
+    """Test running GPU-related backend with local CPU backends
+    together
+    """
+    device = "cuda"
+    num_tokens = 2000
+    chunk_size = 256  # Default chunk size for this test
+    num_blocks = 1000
+    block_size = 16
+    dtype = torch.bfloat16
+
+    connector = create_gpu_connector(1024, 32)
+    metadata = dumb_metadata()
+    metadata.model_name = "test-model"  # NOTE: Gds does not accept name with '_'
+
+    tokens = generate_tokens(num_tokens, device)
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+    retrieved_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype
+    )
+
+    original_retrieved_cache = deepcopy(retrieved_cache)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    # Check the kv cache and the retrieval buffer are not the same
+    check_paged_kv_cache_equal(retrieved_cache, original_retrieved_cache, slot_mapping)
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(retrieved_cache, kv_cache, slot_mapping)
+
+    with tempfile.TemporaryDirectory(
+        dir=_TEST_TMPDIR, ignore_cleanup_errors=True
+    ) as temp_dir:
+        cfg = LMCacheEngineConfig.from_dict(
+            {
+                "local_cpu": True,
+                "max_local_cpu_size": 5,
+                "gds_path": temp_dir,
+                "gds_buffer_size": 1024,
+                "save_unfull_chunk": save_unfull_chunk,
+                "extra_config": {
+                    "use_direct_io": True,
+                },
+            }
+        )
+
+        connector = create_gpu_connector(1024, 32)
+
+        engine = autorelease_v1(
+            LMCacheEngineBuilder.get_or_create(
+                "engine",
+                cfg,
+                metadata,
+                connector,
+                mock_up_broadcast_fn,
+                mock_up_broadcast_object_fn,
+            )
+        )
+
+        """ test store """
+        engine.store(tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+        recover_engine_states(engine)
+        time.sleep(3)  # wait a bit to finish the store
+
+        """ Test lookup """
+        expected_count = get_expected_count(len(tokens), save_unfull_chunk, chunk_size)
+        ret = engine.lookup(tokens)
+        assert ret == expected_count
+
+        ret_cpu = engine.lookup(tokens, search_range=["LocalCPUBackend"])
+        assert ret_cpu == expected_count
+
+        ret_gds = engine.lookup(tokens, search_range=["GdsBackend"])
+        assert ret_gds == expected_count
+
+        """ Test retrieve """
+        ret_mask = engine.retrieve(
+            tokens, kvcaches=retrieved_cache, slot_mapping=slot_mapping
+        )
+        recover_engine_states(engine)
+        length = torch.sum(ret_mask)
+        assert length == expected_count
+        # Only check chunk-aligned tokens when save_unfull_chunk=False
+        check_paged_kv_cache_equal(
+            retrieved_cache, kv_cache, slot_mapping[:expected_count]
+        )
+
+        LMCacheEngineBuilder.destroy("engine")
+
+
+def _make_key(chunk_hash: int) -> CacheEngineKey:
+    """Create a CacheEngineKey for testing."""
+    return CacheEngineKey("test", 1, 0, chunk_hash, torch.bfloat16)
+
+
+def _make_mock_memory_obj(size: int = 1024) -> MagicMock:
+    """Create a mock MemoryObj that tracks ref_count_down calls."""
+    mock = MagicMock()
+    mock.get_size.return_value = size
+    return mock
+
+
+def _make_mock_engine(
+    process_tokens_results: list,
+    block_mapping: dict,
+    batched_get_side_effect: list,
+) -> MagicMock:
+    """Create a mock engine with the attributes needed by
+    _process_tokens_internal.
+
+    Args:
+        process_tokens_results: list of (start, end, key) tuples that
+            token_database.process_tokens will yield.
+        block_mapping: dict returned by storage_manager.get_block_mapping.
+        batched_get_side_effect: list of return values for successive
+            storage_manager.batched_get calls (one per location).
+
+    Returns:
+        A MagicMock configured as a minimal LMCacheEngine.
+    """
+    engine = MagicMock()
+    engine.token_database.process_tokens.return_value = process_tokens_results
+    engine.storage_manager.get_block_mapping.return_value = block_mapping
+    engine.storage_manager.batched_get.side_effect = batched_get_side_effect
+    engine.lookup_pins = {}
+    return engine
+
+
+def test_process_tokens_single_location_boundary_failure():
+    """The block whose end equals last_failed_block_start covers
+    [start, last_failed_block_start) — entirely before the gap — and
+    must be kept."""
+    k0, k1 = _make_key(0), _make_key(1)
+    mem0 = _make_mock_memory_obj()
+
+    engine = _make_mock_engine(
+        process_tokens_results=[(0, 10, k0), (10, 20, k1)],
+        block_mapping=OrderedDict(
+            [
+                ("LocationA", [(k0, 0, 10), (k1, 10, 20)]),
+            ]
+        ),
+        batched_get_side_effect=[[mem0, None]],
+    )
+
+    ret_mask = torch.zeros(20, dtype=torch.bool)
+    chunks, tot_kv_size = LMCacheEngine._process_tokens_internal(
+        engine, torch.zeros(20, dtype=torch.long), None, ret_mask
+    )
+
+    assert len(chunks) == 1
+    assert chunks[0][0] == k0
+    assert chunks[0][1] is mem0
+    assert tot_kv_size == 1024
+    assert ret_mask[:10].all()
+    assert not ret_mask[10:].any()
+    mem0.ref_count_down.assert_not_called()
+
+
+def test_process_tokens_early_failure_truncates_later_location():
+    """When an early location fails, blocks successfully retrieved from
+    a later location (covering higher positions) must be discarded and
+    freed because they are past the gap."""
+    k0, k1 = _make_key(0), _make_key(1)
+    k2, k3 = _make_key(2), _make_key(3)
+    mem0 = _make_mock_memory_obj()
+    mem2 = _make_mock_memory_obj()
+    mem3 = _make_mock_memory_obj()
+
+    engine = _make_mock_engine(
+        process_tokens_results=[
+            (0, 10, k0),
+            (10, 20, k1),
+            (20, 30, k2),
+            (30, 40, k3),
+        ],
+        block_mapping=OrderedDict(
+            [
+                ("LocationA", [(k0, 0, 10), (k1, 10, 20)]),
+                ("LocationB", [(k2, 20, 30), (k3, 30, 40)]),
+            ]
+        ),
+        batched_get_side_effect=[
+            [mem0, None],
+            [mem2, mem3],
+        ],
+    )
+
+    ret_mask = torch.zeros(40, dtype=torch.bool)
+    chunks, tot_kv_size = LMCacheEngine._process_tokens_internal(
+        engine, torch.zeros(40, dtype=torch.long), None, ret_mask
+    )
+
+    assert len(chunks) == 1
+    assert chunks[0][0] == k0
+    assert tot_kv_size == 1024
+    assert ret_mask[:10].all()
+    assert not ret_mask[10:].any()
+    mem0.ref_count_down.assert_not_called()
+    mem2.ref_count_down.assert_called_once()
+    mem3.ref_count_down.assert_called_once()
+
+
+def test_process_tokens_multi_location_both_fail_takes_min():
+    """When failures occur in multiple locations, the earliest failure
+    start (MIN) should be used so that everything after the first gap
+    is discarded."""
+    k0, k1 = _make_key(0), _make_key(1)
+    k2, k3 = _make_key(2), _make_key(3)
+    mem0 = _make_mock_memory_obj()
+    mem2 = _make_mock_memory_obj()
+
+    engine = _make_mock_engine(
+        process_tokens_results=[
+            (0, 10, k0),
+            (10, 20, k1),
+            (20, 30, k2),
+            (30, 40, k3),
+        ],
+        block_mapping=OrderedDict(
+            [
+                ("LocationA", [(k0, 0, 10), (k1, 10, 20)]),
+                ("LocationB", [(k2, 20, 30), (k3, 30, 40)]),
+            ]
+        ),
+        batched_get_side_effect=[
+            [mem0, None],
+            [mem2, None],
+        ],
+    )
+
+    ret_mask = torch.zeros(40, dtype=torch.bool)
+    chunks, tot_kv_size = LMCacheEngine._process_tokens_internal(
+        engine, torch.zeros(40, dtype=torch.long), None, ret_mask
+    )
+
+    assert len(chunks) == 1
+    assert chunks[0][0] == k0
+    assert tot_kv_size == 1024
+    assert ret_mask[:10].all()
+    assert not ret_mask[10:].any()
+    mem0.ref_count_down.assert_not_called()
+    mem2.ref_count_down.assert_called_once()
+
+
+def test_process_tokens_no_failure():
+    """When all blocks are retrieved successfully, every chunk should
+    be returned and no ref_count_down should be called."""
+    k0, k1 = _make_key(0), _make_key(1)
+    mem0 = _make_mock_memory_obj()
+    mem1 = _make_mock_memory_obj()
+
+    engine = _make_mock_engine(
+        process_tokens_results=[(0, 10, k0), (10, 20, k1)],
+        block_mapping=OrderedDict(
+            [
+                ("LocationA", [(k0, 0, 10), (k1, 10, 20)]),
+            ]
+        ),
+        batched_get_side_effect=[[mem0, mem1]],
+    )
+
+    ret_mask = torch.zeros(20, dtype=torch.bool)
+    chunks, tot_kv_size = LMCacheEngine._process_tokens_internal(
+        engine, torch.zeros(20, dtype=torch.long), None, ret_mask
+    )
+
+    assert len(chunks) == 2
+    assert tot_kv_size == 2048
+    assert ret_mask[:20].all()
+    mem0.ref_count_down.assert_not_called()
+    mem1.ref_count_down.assert_not_called()
+
+
+def test_process_tokens_unused_keys_no_double_free():
+    """A key returned non-None by batched_get but coming after a None
+    (unused) should be freed exactly once in the per-location cleanup
+    and never again in post-processing."""
+    k0, k1, k2 = _make_key(0), _make_key(1), _make_key(2)
+    mem0 = _make_mock_memory_obj()
+    mem2 = _make_mock_memory_obj()
+
+    engine = _make_mock_engine(
+        process_tokens_results=[(0, 10, k0), (10, 20, k1), (20, 30, k2)],
+        block_mapping=OrderedDict(
+            [
+                ("LocationA", [(k0, 0, 10), (k1, 10, 20), (k2, 20, 30)]),
+            ]
+        ),
+        batched_get_side_effect=[[mem0, None, mem2]],
+    )
+
+    ret_mask = torch.zeros(30, dtype=torch.bool)
+    chunks, tot_kv_size = LMCacheEngine._process_tokens_internal(
+        engine, torch.zeros(30, dtype=torch.long), None, ret_mask
+    )
+
+    assert len(chunks) == 1
+    assert chunks[0][0] == k0
+    assert tot_kv_size == 1024
+    assert ret_mask[:10].all()
+    assert not ret_mask[10:].any()
+    mem0.ref_count_down.assert_not_called()
+    mem2.ref_count_down.assert_called_once()
+
+
+def test_process_tokens_first_block_fails():
+    """When the very first block fails, no chunks should be returned
+    and ret_mask should be all False."""
+    k0, k1 = _make_key(0), _make_key(1)
+    mem1 = _make_mock_memory_obj()
+
+    engine = _make_mock_engine(
+        process_tokens_results=[(0, 10, k0), (10, 20, k1)],
+        block_mapping=OrderedDict(
+            [
+                ("LocationA", [(k0, 0, 10), (k1, 10, 20)]),
+            ]
+        ),
+        batched_get_side_effect=[[None, mem1]],
+    )
+
+    ret_mask = torch.zeros(20, dtype=torch.bool)
+    chunks, tot_kv_size = LMCacheEngine._process_tokens_internal(
+        engine, torch.zeros(20, dtype=torch.long), None, ret_mask
+    )
+
+    assert len(chunks) == 0
+    assert tot_kv_size == 0
+    assert not ret_mask.any()
+    mem1.ref_count_down.assert_called_once()
+
+
+def test_compress_decompress_unpin_not_pinned() -> None:
+    """Verify that compress and decompress check is_pinned before calling unpin()
+
+    This prevents negative pin counts and double unpin warnings on backends like
+    Remote/S3.
+    """
+    # Create mock memory objects
+    mock_mem_obj = MagicMock()
+    mock_mem_obj.is_pinned = False  # Not pinned (e.g. from Remote/S3 backend)
+
+    mock_compressed_mem_obj = MagicMock()
+    mock_compressed_mem_obj.is_pinned = False  # Not pinned
+
+    # Mock serializer and deserializer
+    mock_serializer = MagicMock()
+    mock_serializer.serialize.return_value = mock_compressed_mem_obj
+    mock_deserializer = MagicMock()
+    mock_deserializer.deserialize.return_value = mock_mem_obj
+
+    # Create a mock engine
+    engine = MagicMock(spec=LMCacheEngine)
+    engine.metadata = MagicMock()
+    engine.config = MagicMock()
+    engine.lookup_pins = {"event_123": {"remote": ["key1"]}}
+
+    # Mock engine.lookup to return number of tokens (non-zero)
+    engine.lookup.return_value = 100
+
+    # Mock storage_manager methods
+    engine.storage_manager = MagicMock()
+    # For compress: batched_get returns mock_mem_obj
+    engine.storage_manager.batched_get.return_value = [mock_mem_obj]
+
+    with patch(
+        "lmcache.v1.storage_backend.naive_serde.CreateSerde",
+        return_value=(mock_serializer, mock_deserializer),
+    ):
+        # Call compress on the engine
+        res = LMCacheEngine.compress(
+            engine,
+            tokens=[1, 2, 3],
+            method="cachegen",
+            location="remote",
+            event_id="event_123",
+        )
+
+        assert res == 100
+        # Verify that serialize was called
+        mock_serializer.serialize.assert_called_once_with(mock_mem_obj)
+        # Verify that unpin was NOT called since is_pinned = False
+        mock_mem_obj.unpin.assert_not_called()
+
+        # Verify batched_remove and batched_put were called on storage_manager
+        engine.storage_manager.batched_remove.assert_called_once_with(
+            ["key1"], locations=["remote"]
+        )
+        engine.storage_manager.batched_put.assert_called_once_with(
+            keys=["key1"],
+            memory_objs=[mock_compressed_mem_obj],
+            location="remote",
+        )
+
+    # Reset storage_manager mock
+    engine.storage_manager.reset_mock()
+    # For decompress: batched_get returns mock_compressed_mem_obj
+    engine.storage_manager.batched_get.return_value = [mock_compressed_mem_obj]
+
+    with patch(
+        "lmcache.v1.storage_backend.naive_serde.CreateSerde",
+        return_value=(mock_serializer, mock_deserializer),
+    ):
+        res_decomp = LMCacheEngine.decompress(
+            engine,
+            tokens=[1, 2, 3],
+            method="cachegen",
+            location="remote",
+            event_id="event_123",
+        )
+
+        assert res_decomp == 100
+        # Verify that deserialize was called
+        mock_deserializer.deserialize.assert_called_once_with(mock_compressed_mem_obj)
+        # Verify that unpin was NOT called since is_pinned = False
+        mock_compressed_mem_obj.unpin.assert_not_called()
+
+        # Verify batched_remove and batched_put were called on storage_manager
+        engine.storage_manager.batched_remove.assert_called_once_with(
+            ["key1"], locations=["remote"]
+        )
+        engine.storage_manager.batched_put.assert_called_once_with(
+            keys=["key1"],
+            memory_objs=[mock_mem_obj],
+            location="remote",
+        )
+
+
+def test_compress_decompress_unpin_when_pinned() -> None:
+    """Verify that compress and decompress call unpin() if is_pinned is True"""
+    # Create mock memory objects
+    mock_mem_obj = MagicMock()
+    mock_mem_obj.is_pinned = True
+
+    mock_compressed_mem_obj = MagicMock()
+    mock_compressed_mem_obj.is_pinned = True
+
+    # Mock serializer and deserializer
+    mock_serializer = MagicMock()
+    mock_serializer.serialize.return_value = mock_compressed_mem_obj
+    mock_deserializer = MagicMock()
+    mock_deserializer.deserialize.return_value = mock_mem_obj
+
+    # Create a mock engine
+    engine = MagicMock(spec=LMCacheEngine)
+    engine.metadata = MagicMock()
+    engine.config = MagicMock()
+    engine.lookup_pins = {"event_123": {"local_cpu": ["key1"]}}
+    engine.lookup.return_value = 100
+    engine.storage_manager = MagicMock()
+
+    # Test compress
+    engine.storage_manager.batched_get.return_value = [mock_mem_obj]
+    with patch(
+        "lmcache.v1.storage_backend.naive_serde.CreateSerde",
+        return_value=(mock_serializer, mock_deserializer),
+    ):
+        LMCacheEngine.compress(
+            engine,
+            tokens=[1, 2, 3],
+            method="cachegen",
+            location="local_cpu",
+            event_id="event_123",
+        )
+        mock_mem_obj.unpin.assert_called_once()
+
+    # Test decompress
+    engine.storage_manager.reset_mock()
+    engine.storage_manager.batched_get.return_value = [mock_compressed_mem_obj]
+    with patch(
+        "lmcache.v1.storage_backend.naive_serde.CreateSerde",
+        return_value=(mock_serializer, mock_deserializer),
+    ):
+        LMCacheEngine.decompress(
+            engine,
+            tokens=[1, 2, 3],
+            method="cachegen",
+            location="local_cpu",
+            event_id="event_123",
+        )
+        mock_compressed_mem_obj.unpin.assert_called_once()
+
+
+def test_retrieve_cleanup_ref_count_and_unpin() -> None:
+    """Verify that retrieve() unpins and ref_count_downs all retrieved chunks.
+
+    Specifically in the else branch when remove_after_retrieve is False.
+    """
+    # Create mock memory objects
+    mem_obj_pinned = MagicMock()
+    mem_obj_pinned.is_pinned = True
+
+    mem_obj_not_pinned = MagicMock()
+    mem_obj_not_pinned.is_pinned = False
+
+    # Mock engine instance
+    engine = MagicMock(spec=LMCacheEngine)
+    engine.is_healthy.return_value = True
+    engine.remove_after_retrieve = False
+    engine._is_passive.return_value = False
+    engine.save_only_first_rank = False
+    engine._get_req_id.return_value = "req_123"
+
+    # We want retrieve to process chunks
+    k0 = _make_key(0)
+    k1 = _make_key(1)
+    reordered_chunks = [
+        (k0, mem_obj_pinned, 0, 10),
+        (k1, mem_obj_not_pinned, 10, 20),
+    ]
+
+    engine.async_loading = False
+    engine._process_tokens_internal.return_value = (reordered_chunks, 1024)
+    engine._is_sync_pd_backend.return_value = False
+
+    # Mock stats monitor
+    engine.stats_monitor = MagicMock()
+    mock_stats = MagicMock()
+    mock_stats.time_to_retrieve.return_value = 1.0
+    engine.stats_monitor.on_retrieve_request.return_value = mock_stats
+
+    # Mock gpu_connector
+    engine.gpu_connector = MagicMock()
+
+    # Call retrieve
+    tokens = torch.zeros(20, dtype=torch.long)
+    kvcaches = torch.zeros(20)
+    slot_mapping = torch.zeros(20, dtype=torch.long)
+
+    LMCacheEngine.retrieve(
+        engine,
+        tokens=tokens,
+        kvcaches=kvcaches,
+        slot_mapping=slot_mapping,
+    )
+
+    # Assertions
+    mem_obj_pinned.ref_count_down.assert_called_once()
+    mem_obj_pinned.unpin.assert_called_once()
+
+    mem_obj_not_pinned.ref_count_down.assert_called_once()
+    mem_obj_not_pinned.unpin.assert_not_called()
diff --git a/tests/v1/test_cache_engine_cleanup.py b/tests/v1/test_cache_engine_cleanup.py
new file mode 100644
index 0000000..3e89f26
--- /dev/null
+++ b/tests/v1/test_cache_engine_cleanup.py
@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Regression tests for LMCacheEngine.cleanup_memory_objs.
+
+Some storage backends (LocalCPU, LocalDisk, P2P, Maru) pin the MemoryObj
+they return via async prefetch, while others (Remote, Nixl, plugin tiers)
+do not. cleanup_memory_objs must skip unpin for the latter to avoid
+driving pin_count below zero.
+"""
+
+# Standard
+from collections.abc import Generator
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import MagicMock
+import logging
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.cache_engine import LMCacheEngine
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.event_manager import EventStatus
+from lmcache.v1.pin_monitor import PinMonitor
+
+# Local
+from .utils import create_test_memory_obj
+
+
+@pytest.fixture
+def pin_monitor() -> Generator[None, None, None]:
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=256, lmcache_instance_id="test_cleanup"
+    )
+    PinMonitor.GetOrCreate(config)
+    yield
+    PinMonitor.DestroyInstance()
+
+
+def test_cleanup_memory_objs_handles_mixed_pin_state(
+    caplog: pytest.LogCaptureFixture, pin_monitor: Any
+) -> None:
+    """
+    Cleanup must unpin chunks that were pinned during prefetch and
+    skip unpin for chunks that were not, leaving every chunk with a
+    non-negative pin_count and no "Double unpin" warning.
+    """
+    pinned_obj = create_test_memory_obj()
+    pinned_obj.pin()
+    pinned_obj.ref_count_up()
+    assert pinned_obj.metadata.pin_count == 1
+
+    nonpinned_obj = create_test_memory_obj()
+    assert nonpinned_obj.metadata.pin_count == 0
+
+    future = MagicMock()
+    future.result.return_value = [
+        [(None, pinned_obj)],
+        [(None, nonpinned_obj)],
+    ]
+
+    engine = SimpleNamespace(event_manager=MagicMock())
+    engine.event_manager.get_event_status.return_value = EventStatus.DONE
+    engine.event_manager.pop_event.return_value = future
+
+    caplog.set_level(logging.WARNING, logger="lmcache")
+
+    LMCacheEngine.cleanup_memory_objs(engine, "test_lookup")  # type: ignore[arg-type]
+
+    assert pinned_obj.metadata.pin_count == 0
+    assert nonpinned_obj.metadata.pin_count == 0
+    assert "Double unpin" not in caplog.text
+    assert "is negative" not in caplog.text
+
+    pinned_obj.ref_count_down()
diff --git a/tests/v1/test_cache_interface.py b/tests/v1/test_cache_interface.py
new file mode 100644
index 0000000..798271f
--- /dev/null
+++ b/tests/v1/test_cache_interface.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# TODO (Jiayi)
diff --git a/tests/v1/test_cache_policy.py b/tests/v1/test_cache_policy.py
new file mode 100644
index 0000000..5d004c9
--- /dev/null
+++ b/tests/v1/test_cache_policy.py
@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+# First Party
+from lmcache.v1.storage_backend.cache_policy import get_cache_policy
+
+# Local
+from .utils import dumb_cache_engine_key
+
+
+class DummyMemoryObj:
+    def __init__(self, can_evict: bool = True):
+        self.can_evict = can_evict
+
+
+def test_lru():
+    policy = get_cache_policy("LRU")
+    cache_dict = policy.init_mutable_mapping()
+    obj1 = DummyMemoryObj()
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key1, cache_dict)
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+    assert evict_candidates == [key2, key3]
+
+
+def test_lru_with_pin():
+    policy = get_cache_policy("LRU")
+    cache_dict = policy.init_mutable_mapping()
+    obj1 = DummyMemoryObj()
+    obj2 = DummyMemoryObj(can_evict=False)  # Pinned object
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key1, cache_dict)
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+    assert evict_candidates == [key3, key1]
+
+
+def test_fifo():
+    policy = get_cache_policy("FIFO")
+    cache_dict = policy.init_mutable_mapping()
+    obj1 = DummyMemoryObj()
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key1, cache_dict)
+    policy.update_on_hit(key3, cache_dict)
+    policy.update_on_hit(key2, cache_dict)
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+    assert evict_candidates == [key1, key2]
+
+
+def test_fifo_with_pin():
+    policy = get_cache_policy("FIFO")
+    cache_dict = policy.init_mutable_mapping()
+    obj1 = DummyMemoryObj(can_evict=False)  # Pinned object
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key1, cache_dict)
+    policy.update_on_hit(key3, cache_dict)
+    policy.update_on_hit(key2, cache_dict)
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+    assert evict_candidates == [key2, key3]
+
+
+def test_lfu():
+    policy = get_cache_policy("LFU")
+    cache_dict = policy.init_mutable_mapping()
+
+    obj1 = DummyMemoryObj()
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key3, cache_dict)
+    policy.update_on_hit(key3, cache_dict)
+    policy.update_on_hit(key2, cache_dict)
+    policy.update_on_hit(key2, cache_dict)
+    policy.update_on_hit(key1, cache_dict)
+
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+
+    assert evict_candidates == [key1, key3]
+
+
+def test_lfu_with_pin():
+    policy = get_cache_policy("LFU")
+    cache_dict = policy.init_mutable_mapping()
+
+    obj1 = DummyMemoryObj(can_evict=False)  # Pinned object
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key3, cache_dict)
+    policy.update_on_hit(key3, cache_dict)
+    policy.update_on_hit(key2, cache_dict)
+    policy.update_on_hit(key2, cache_dict)
+    policy.update_on_hit(key1, cache_dict)
+
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+
+    assert evict_candidates == [key3, key2]
+
+
+def test_mru():
+    policy = get_cache_policy("MRU")
+    cache_dict = policy.init_mutable_mapping()
+    obj1 = DummyMemoryObj()
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj()
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key1, cache_dict)
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+    # key1 is the most recent, followed by key3.
+    assert evict_candidates == [key1, key3], (evict_candidates, [key1, key3])
+
+
+def test_mru_with_pin():
+    policy = get_cache_policy("MRU")
+    cache_dict = policy.init_mutable_mapping()
+    obj1 = DummyMemoryObj()
+    obj2 = DummyMemoryObj()
+    obj3 = DummyMemoryObj(can_evict=False)  # Pinned object
+    key1 = dumb_cache_engine_key(1)
+    key2 = dumb_cache_engine_key(2)
+    key3 = dumb_cache_engine_key(3)
+
+    cache_dict[key1] = obj1
+    policy.update_on_put(key1)
+    cache_dict[key2] = obj2
+    policy.update_on_put(key2)
+    cache_dict[key3] = obj3
+    policy.update_on_put(key3)
+
+    policy.update_on_hit(key1, cache_dict)
+    evict_candidates = policy.get_evict_candidates(cache_dict, num_candidates=2)
+    # key1 is most recent, followed by key3, but since key3 is pinned, wo go to key2.
+    assert evict_candidates == [key1, key2], (evict_candidates, [key1, key2])
diff --git a/tests/v1/test_config.py b/tests/v1/test_config.py
new file mode 100644
index 0000000..4db217e
--- /dev/null
+++ b/tests/v1/test_config.py
@@ -0,0 +1,1053 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+from typing import Any, cast
+import os
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig, load_ec_engine_config
+from lmcache.v1.config_base import apply_remote_configs, validate_and_set_config_value
+
+BASE_DIR = Path(__file__).parent
+
+
+def test_get_extra_config_from_file():
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/test_config.yaml")
+    check_extra_config(config)
+
+
+def test_get_extra_config_from_env():
+    config = LMCacheEngineConfig.from_env()
+    assert config.extra_config is None
+
+    # set env of extra_config
+    os.environ["LMCACHE_EXTRA_CONFIG"] = '{"key1": "value1", "key2": "value2"}'
+
+    new_config = LMCacheEngineConfig.from_env()
+    check_extra_config(new_config)
+
+
+def check_extra_config(config: "LMCacheEngineConfig"):
+    assert config.extra_config is not None
+    assert isinstance(config.extra_config, dict)
+    assert len(config.extra_config) == 2
+    assert config.extra_config["key1"] == "value1"
+    assert config.extra_config["key2"] == "value2"
+
+
+def test_load_ec_engine_config_prefixed_file_and_env_overrides(
+    tmp_path: Path,
+    monkeypatch,
+):
+    config_path = tmp_path / "lmcache.yaml"
+    config_path.write_text(
+        "\n".join(
+            [
+                "chunk_size: 256",
+                "local_disk: /tmp/base-disk",
+                "max_local_disk_size: 2",
+                "ec_chunk_size: 1024",
+                "ec_local_disk: /tmp/ec-disk",
+                "ec_max_local_disk_size: 4",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    monkeypatch.setenv("LMCACHE_CONFIG_FILE", str(config_path))
+    monkeypatch.setenv("LMCACHE_EC_CHUNK_SIZE", "1536")
+    monkeypatch.setenv("LMCACHE_EC_REMOTE_URL", "http://ec.example.com")
+
+    base_config = LMCacheEngineConfig.from_file(config_path)
+    ec_config = cast(Any, load_ec_engine_config(base_config=base_config))
+
+    assert base_config.chunk_size == 256
+    assert base_config.local_disk == "/tmp/base-disk"
+    assert base_config.max_local_disk_size == 2
+
+    assert ec_config.chunk_size == 1536
+    assert ec_config.local_disk == "/tmp/ec-disk"
+    assert ec_config.max_local_disk_size == 4
+    assert ec_config.remote_url == "http://ec.example.com"
+
+
+def test_load_ec_engine_config_applies_storage_defaults():
+    base_config = LMCacheEngineConfig.from_defaults(
+        enable_pd=False,
+        local_cpu=False,
+        max_local_cpu_size=0,
+        local_disk="/tmp/ec-disk",
+        max_local_disk_size=0,
+    )
+
+    ec_config = cast(Any, load_ec_engine_config(base_config=base_config))
+
+    assert ec_config.local_cpu is True
+    assert ec_config.max_local_cpu_size == 1
+    assert ec_config.max_local_disk_size == 64
+
+
+def test_update_config_from_env_basic():
+    config = LMCacheEngineConfig.from_defaults()
+    original_chunk_size = config.chunk_size
+    os.environ["LMCACHE_CHUNK_SIZE"] = "  512  "
+    os.environ["LMCACHE_REMOTE_URL"] = "  http://example.com:8080  "
+    config.update_config_from_env()
+    assert config.chunk_size == 512 and config.chunk_size != original_chunk_size
+    assert config.remote_url == "http://example.com:8080"
+    del os.environ["LMCACHE_CHUNK_SIZE"]
+    del os.environ["LMCACHE_REMOTE_URL"]
+
+
+def test_update_config_from_env_quotes():
+    config = LMCacheEngineConfig.from_defaults()
+    os.environ["LMCACHE_REMOTE_URL"] = "'http://example.com:8080'"
+    os.environ["LMCACHE_PD_ROLE"] = '"sender"'
+    os.environ["LMCACHE_BLEND_SPECIAL_STR"] = "' ### '"
+    config.update_config_from_env()
+    assert config.remote_url == "http://example.com:8080"
+    assert config.pd_role == "sender" and config.blend_special_str == " ### "
+    del os.environ["LMCACHE_REMOTE_URL"]
+    del os.environ["LMCACHE_PD_ROLE"]
+    del os.environ["LMCACHE_BLEND_SPECIAL_STR"]
+
+
+def test_update_config_from_env_extra_config():
+    config = LMCacheEngineConfig.from_defaults()
+    test_cases = [
+        (
+            '  {"test_key": "test_value", "number": 42}  ',
+            {"test_key": "test_value", "number": 42},
+        ),
+        ('\'{"nested": {"key": "value"}}\'', {"nested": {"key": "value"}}),
+        ('"{\\"config\\": \\"prod\\"}"', {"config": "prod"}),
+    ]
+    for test_input, expected in test_cases:
+        os.environ["LMCACHE_EXTRA_CONFIG"] = test_input
+        config.update_config_from_env()
+        assert config.extra_config == expected
+        del os.environ["LMCACHE_EXTRA_CONFIG"]
+
+
+def test_update_config_from_env_internal_api_server_include_index_list():
+    config = LMCacheEngineConfig.from_defaults()
+    test_cases = [
+        ("  1,2,3,4  ", [1, 2, 3, 4]),
+        ('"1,2,3,4"', [1, 2, 3, 4]),
+        ("'1,2,3,4'", [1, 2, 3, 4]),
+        (" 1 , 2 , 3 , 4 ", [1, 2, 3, 4]),
+        ("  5  ", [5]),
+        ('"10"', [10]),
+    ]
+    for test_input, expected in test_cases:
+        os.environ["LMCACHE_INTERNAL_API_SERVER_INCLUDE_INDEX_LIST"] = test_input
+        config.update_config_from_env()
+        assert config.internal_api_server_include_index_list == expected
+        del os.environ["LMCACHE_INTERNAL_API_SERVER_INCLUDE_INDEX_LIST"]
+
+
+def test_update_config_from_env_error_handling():
+    config = LMCacheEngineConfig.from_defaults()
+    original_chunk_size, original_extra_config = config.chunk_size, config.extra_config
+    os.environ["LMCACHE_CHUNK_SIZE"] = "invalid_number"
+    os.environ["LMCACHE_EXTRA_CONFIG"] = "invalid_json{"
+    config.update_config_from_env()
+    assert (
+        config.chunk_size == original_chunk_size
+        and config.extra_config == original_extra_config
+    )
+    os.environ["LMCACHE_CONTROLLER_PULL_URL"] = "http://controller.example.com"
+    config.update_config_from_env()
+    assert config.controller_pull_url == "http://controller.example.com"
+    del os.environ["LMCACHE_CHUNK_SIZE"]
+    del os.environ["LMCACHE_EXTRA_CONFIG"]
+    del os.environ["LMCACHE_CONTROLLER_PULL_URL"]
+
+
+@pytest.mark.parametrize("use_mla", [True, False])
+def test_get_lookup_server_worker_ids(use_mla):
+    config = LMCacheEngineConfig.from_defaults()
+    lookup_server_worker_ids = config.get_lookup_server_worker_ids(use_mla, 8)
+    # test default value
+    if use_mla:
+        assert lookup_server_worker_ids == [0]
+    else:
+        assert lookup_server_worker_ids == [0, 1, 2, 3, 4, 5, 6, 7]
+
+    # test different config
+    # TODO: not support format "[]" or "[0, 3, 6]
+    os.environ["LMCACHE_LOOKUP_SERVER_WORKER_IDS"] = "1"
+    config.update_config_from_env()
+    lookup_server_worker_ids = config.get_lookup_server_worker_ids(use_mla, 8)
+    assert lookup_server_worker_ids == [1]
+
+    os.environ["LMCACHE_LOOKUP_SERVER_WORKER_IDS"] = "0, 3, 6"
+    config.update_config_from_env()
+    lookup_server_worker_ids = config.get_lookup_server_worker_ids(use_mla, 8)
+    assert lookup_server_worker_ids == [0, 3, 6]
+
+    del os.environ["LMCACHE_LOOKUP_SERVER_WORKER_IDS"]
+
+
+class TestValidateAndSetConfigValue:
+    """Test cases for validate_and_set_config_value function."""
+
+    def test_set_basic_config_value(self):
+        """Test setting a basic configuration value."""
+        config = LMCacheEngineConfig.from_defaults()
+        result = validate_and_set_config_value(config, "chunk_size", 512)
+        assert result is True
+        assert config.chunk_size == 512
+
+    def test_set_nonexistent_key(self):
+        """Test setting a non-existent configuration key."""
+        config = LMCacheEngineConfig.from_defaults()
+        result = validate_and_set_config_value(config, "nonexistent_key", "value")
+        assert result is False
+
+    def test_set_extra_config_with_dict(self):
+        """Test setting extra_config with a dictionary value."""
+        config = LMCacheEngineConfig.from_defaults()
+        new_config = {"key1": "value1", "key2": "value2"}
+        result = validate_and_set_config_value(config, "extra_config", new_config)
+        assert result is True
+        assert config.extra_config == new_config
+
+    def test_set_extra_config_with_json_string(self):
+        """Test setting extra_config with a JSON string value."""
+        config = LMCacheEngineConfig.from_defaults()
+        json_str = '{"key1": "value1", "key2": "value2"}'
+        result = validate_and_set_config_value(config, "extra_config", json_str)
+        assert result is True
+        assert config.extra_config == {"key1": "value1", "key2": "value2"}
+
+    def test_set_extra_config_override_true(self):
+        """Test that override=True completely replaces extra_config."""
+        config = LMCacheEngineConfig.from_defaults()
+        # Set initial value
+        config.extra_config = {"key1": "value1", "key2": "value2"}
+
+        # Override with new value
+        new_config = {"key3": "value3"}
+        result = validate_and_set_config_value(
+            config, "extra_config", new_config, override=True
+        )
+        assert result is True
+        assert config.extra_config == {"key3": "value3"}
+        assert "key1" not in config.extra_config
+        assert "key2" not in config.extra_config
+
+    def test_set_extra_config_override_false_merge(self):
+        """Test that override=False merges extra_config dictionaries."""
+        config = LMCacheEngineConfig.from_defaults()
+        # Set initial value
+        config.extra_config = {"key1": "value1", "key2": "value2"}
+
+        # Merge with new value (override=False)
+        new_config = {"key2": "new_value2", "key3": "value3"}
+        result = validate_and_set_config_value(
+            config, "extra_config", new_config, override=False
+        )
+        assert result is True
+        # key1 should be preserved
+        assert config.extra_config["key1"] == "value1"
+        # key2 should be updated
+        assert config.extra_config["key2"] == "new_value2"
+        # key3 should be added
+        assert config.extra_config["key3"] == "value3"
+
+    def test_set_extra_config_override_false_with_json_string(self):
+        """Test merge with JSON string input when override=False."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"existing_key": "existing_value"}
+
+        json_str = '{"new_key": "new_value"}'
+        result = validate_and_set_config_value(
+            config, "extra_config", json_str, override=False
+        )
+        assert result is True
+        assert config.extra_config["existing_key"] == "existing_value"
+        assert config.extra_config["new_key"] == "new_value"
+
+    def test_set_extra_config_override_false_current_none(self):
+        """Test override=False when current extra_config is None."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = None
+
+        new_config = {"key1": "value1"}
+        result = validate_and_set_config_value(
+            config, "extra_config", new_config, override=False
+        )
+        assert result is True
+        assert config.extra_config == {"key1": "value1"}
+
+    def test_set_extra_config_override_false_new_value_none(self):
+        """Test override=False when new value is None, should keep current."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1"}
+
+        result = validate_and_set_config_value(
+            config, "extra_config", None, override=False
+        )
+        assert result is True
+        assert config.extra_config == {"key1": "value1"}
+
+    def test_set_extra_config_override_false_empty_string(self):
+        """Test override=False when new value is empty string."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1"}
+
+        result = validate_and_set_config_value(
+            config, "extra_config", "", override=False
+        )
+        assert result is True
+        # Empty string converts to None, so current value should be kept
+        assert config.extra_config == {"key1": "value1"}
+
+    def test_set_extra_config_default_override_is_true(self):
+        """Test that default behavior is override=True."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1"}
+
+        new_config = {"key2": "value2"}
+        # Don't pass override parameter, should default to True
+        result = validate_and_set_config_value(config, "extra_config", new_config)
+        assert result is True
+        # Should completely replace
+        assert config.extra_config == {"key2": "value2"}
+        assert "key1" not in config.extra_config
+
+    def test_set_extra_config_invalid_json_string(self):
+        """Test setting extra_config with invalid JSON string."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1"}
+        original_config = config.extra_config.copy()
+
+        result = validate_and_set_config_value(config, "extra_config", "invalid_json{")
+        assert result is False
+        # Original value should be preserved on error
+        assert config.extra_config == original_config
+
+    def test_set_basic_config_override_false_skip_when_user_set(self):
+        """Test override=False skips setting value for user-set config keys."""
+        # Create config with user-set chunk_size
+        config = LMCacheEngineConfig.from_defaults(chunk_size=256)
+        # Verify chunk_size is marked as user-set
+        assert "chunk_size" in config._user_set_keys
+
+        result = validate_and_set_config_value(
+            config, "chunk_size", 512, override=False
+        )
+        assert result is True
+        # Value should not be changed because override=False and key is user-set
+        assert config.chunk_size == 256
+
+    def test_set_basic_config_override_false_set_when_not_user_set(self):
+        """Test override=False sets value for non-user-set keys (default values)."""
+        config = LMCacheEngineConfig.from_defaults()
+        # chunk_size has default value 256, not user-set
+        assert "chunk_size" not in config._user_set_keys
+        assert config.chunk_size == 256  # Default value
+
+        result = validate_and_set_config_value(
+            config, "chunk_size", 512, override=False
+        )
+        assert result is True
+        # Value should be set because key is not user-set (just default)
+        assert config.chunk_size == 512
+
+    def test_set_basic_config_override_false_with_none_default(self):
+        """Test override=False sets value for None default keys when not user-set."""
+        config = LMCacheEngineConfig.from_defaults()
+        assert config.remote_url is None  # Default is None
+        assert "remote_url" not in config._user_set_keys
+
+        result = validate_and_set_config_value(
+            config, "remote_url", "http://example.com", override=False
+        )
+        assert result is True
+        # Value should be set because key is not user-set
+        assert config.remote_url == "http://example.com"
+
+    def test_set_basic_config_override_false_skip_user_set_none(self):
+        """Test override=False skips even if user explicitly set value to None."""
+        # User explicitly sets remote_url to None
+        config = LMCacheEngineConfig.from_defaults(remote_url=None)
+        assert "remote_url" in config._user_set_keys
+        assert config.remote_url is None
+
+        result = validate_and_set_config_value(
+            config, "remote_url", "http://example.com", override=False
+        )
+        assert result is True
+        # Value should NOT be changed because key is user-set (even though it's None)
+        assert config.remote_url is None
+
+    def test_set_basic_config_override_true_always_sets(self):
+        """Test that override=True always sets the value regardless of current value."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.chunk_size = 256
+
+        result = validate_and_set_config_value(config, "chunk_size", 512, override=True)
+        assert result is True
+        # Value should be changed because override=True
+        assert config.chunk_size == 512
+
+
+class TestApplyRemoteConfigs:
+    """Test cases for apply_remote_configs function with override parameter."""
+
+    def test_apply_remote_configs_override_true(self):
+        """Test that override=True completely replaces the config value."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.chunk_size = 256
+
+        remote_response = {
+            "configs": [{"key": "chunk_size", "value": 512, "override": True}]
+        }
+        apply_remote_configs(config, remote_response)
+        assert config.chunk_size == 512
+
+    def test_apply_remote_configs_override_false_basic_skip(self):
+        """Test override=False for basic config - skip if user-set."""
+        # Create config with user-set chunk_size
+        config = LMCacheEngineConfig.from_defaults(chunk_size=256)
+        assert "chunk_size" in config._user_set_keys
+
+        remote_response = {
+            "configs": [{"key": "chunk_size", "value": 512, "override": False}]
+        }
+        apply_remote_configs(config, remote_response)
+        # For user-set keys, override=False should skip
+        assert config.chunk_size == 256  # Original user-set value preserved
+
+    def test_apply_remote_configs_override_false_basic_set_when_default(self):
+        """Test override=False for basic config - set value if using default."""
+        config = LMCacheEngineConfig.from_defaults()
+        assert "chunk_size" not in config._user_set_keys
+        assert config.chunk_size == 256  # Default value
+
+        remote_response = {
+            "configs": [{"key": "chunk_size", "value": 512, "override": False}]
+        }
+        apply_remote_configs(config, remote_response)
+        # For non-user-set keys, override=False should set value
+        assert config.chunk_size == 512
+
+    def test_apply_remote_configs_extra_config_override_true(self):
+        """Test override=True completely replaces extra_config."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1", "key2": "value2"}
+
+        remote_response = {
+            "configs": [
+                {"key": "extra_config", "value": {"key3": "value3"}, "override": True}
+            ]
+        }
+        apply_remote_configs(config, remote_response)
+        assert config.extra_config == {"key3": "value3"}
+        assert "key1" not in config.extra_config
+        assert "key2" not in config.extra_config
+
+    def test_apply_remote_configs_extra_config_override_false_merge(self):
+        """Test override=False merges extra_config dictionaries."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1", "key2": "value2"}
+
+        remote_response = {
+            "configs": [
+                {
+                    "key": "extra_config",
+                    "value": {"key2": "new_value2", "key3": "value3"},
+                    "override": False,
+                }
+            ]
+        }
+        apply_remote_configs(config, remote_response)
+        # key1 should be preserved
+        assert config.extra_config["key1"] == "value1"
+        # key2 should be updated (new values take precedence)
+        assert config.extra_config["key2"] == "new_value2"
+        # key3 should be added
+        assert config.extra_config["key3"] == "value3"
+
+    def test_apply_remote_configs_extra_config_override_false_current_none(self):
+        """Test override=False when current extra_config is None."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = None
+
+        remote_response = {
+            "configs": [
+                {"key": "extra_config", "value": {"key1": "value1"}, "override": False}
+            ]
+        }
+        apply_remote_configs(config, remote_response)
+        assert config.extra_config == {"key1": "value1"}
+
+    def test_apply_remote_configs_default_override_is_true(self):
+        """Test that default override behavior is True when not specified."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.extra_config = {"key1": "value1"}
+
+        # No 'override' key in config item, should default to True
+        remote_response = {
+            "configs": [{"key": "extra_config", "value": {"key2": "value2"}}]
+        }
+        apply_remote_configs(config, remote_response)
+        # Should completely replace
+        assert config.extra_config == {"key2": "value2"}
+        assert "key1" not in config.extra_config
+
+    def test_apply_remote_configs_multiple_items_mixed_override(self):
+        """Test applying multiple config items with different override settings."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.chunk_size = 256
+        config.extra_config = {"existing": "value"}
+
+        remote_response = {
+            "configs": [
+                {"key": "chunk_size", "value": 512, "override": True},
+                {
+                    "key": "extra_config",
+                    "value": {"new": "data"},
+                    "override": False,
+                },
+            ]
+        }
+        apply_remote_configs(config, remote_response)
+        assert config.chunk_size == 512
+        assert config.extra_config["existing"] == "value"
+        assert config.extra_config["new"] == "data"
+
+    def test_apply_remote_configs_empty_configs(self):
+        """Test applying empty configs list."""
+        config = LMCacheEngineConfig.from_defaults()
+        original_chunk_size = config.chunk_size
+
+        remote_response = {"configs": []}
+        apply_remote_configs(config, remote_response)
+        assert config.chunk_size == original_chunk_size
+
+    def test_apply_remote_configs_invalid_config_item(self):
+        """Test that invalid config items are skipped."""
+        config = LMCacheEngineConfig.from_defaults()
+        remote_response = {
+            "configs": [
+                "invalid_item",  # Not a dict
+                {"value": 512},  # Missing 'key'
+                {"key": "chunk_size", "value": 1024, "override": True},  # Valid
+            ]
+        }
+        apply_remote_configs(config, remote_response)
+        assert config.chunk_size == 1024
+
+    def test_apply_remote_configs_nonexistent_key(self):
+        """Test applying config with non-existent key."""
+        config = LMCacheEngineConfig.from_defaults()
+
+        remote_response = {
+            "configs": [
+                {"key": "nonexistent_key", "value": "some_value", "override": True}
+            ]
+        }
+        # Should not raise, just log warning
+        result = apply_remote_configs(config, remote_response)
+        assert result is config  # Returns the config object
+
+
+class TestUserSetKeysTracking:
+    """Test cases for _user_set_keys tracking functionality."""
+
+    def test_from_defaults_no_kwargs_empty_user_set_keys(self):
+        """Test that from_defaults without kwargs has empty _user_set_keys."""
+        config = LMCacheEngineConfig.from_defaults()
+        assert hasattr(config, "_user_set_keys")
+        assert len(config._user_set_keys) == 0
+
+    def test_from_defaults_with_kwargs_tracks_user_set_keys(self):
+        """Test that from_defaults with kwargs tracks user-set keys."""
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=512,
+            remote_url="http://example.com",
+        )
+        assert "chunk_size" in config._user_set_keys
+        assert "remote_url" in config._user_set_keys
+        # Other keys should not be in _user_set_keys
+        assert "local_cpu" not in config._user_set_keys
+
+    def test_from_defaults_user_set_same_as_default(self):
+        """Test that user-set value same as default is still tracked."""
+        # Default chunk_size is 256
+        config = LMCacheEngineConfig.from_defaults(chunk_size=256)
+        # Even though value is same as default, it's user-set
+        assert "chunk_size" in config._user_set_keys
+        assert config.chunk_size == 256
+
+    def test_from_env_tracks_env_set_keys(self):
+        """Test that from_env tracks keys set via environment variables."""
+        os.environ["LMCACHE_CHUNK_SIZE"] = "1024"
+        os.environ["LMCACHE_REMOTE_URL"] = "http://env.example.com"
+        try:
+            config = LMCacheEngineConfig.from_env()
+            assert "chunk_size" in config._user_set_keys
+            assert "remote_url" in config._user_set_keys
+            assert config.chunk_size == 1024
+            assert config.remote_url == "http://env.example.com"
+        finally:
+            del os.environ["LMCACHE_CHUNK_SIZE"]
+            del os.environ["LMCACHE_REMOTE_URL"]
+
+    def test_update_config_from_env_adds_to_user_set_keys(self):
+        """Test that update_config_from_env adds newly set keys to _user_set_keys."""
+        config = LMCacheEngineConfig.from_defaults()
+        assert "chunk_size" not in config._user_set_keys
+
+        os.environ["LMCACHE_CHUNK_SIZE"] = "2048"
+        try:
+            config.update_config_from_env()
+            assert "chunk_size" in config._user_set_keys
+            assert config.chunk_size == 2048
+        finally:
+            del os.environ["LMCACHE_CHUNK_SIZE"]
+
+    def test_from_file_tracks_file_set_keys(self):
+        """Test that from_file tracks keys set in config file."""
+        config = LMCacheEngineConfig.from_file(BASE_DIR / "data/test_config.yaml")
+        # Keys in the config file should be in _user_set_keys
+        assert "extra_config" in config._user_set_keys
+
+    def test_from_dict_tracks_dict_set_keys(self):
+        """Test that from_dict tracks keys set in dictionary."""
+        config_dict = {
+            "chunk_size": 512,
+            "remote_url": "http://dict.example.com",
+        }
+        config = LMCacheEngineConfig.from_dict(config_dict)
+        assert "chunk_size" in config._user_set_keys
+        assert "remote_url" in config._user_set_keys
+        assert "local_cpu" not in config._user_set_keys
+
+    def test_override_false_respects_user_set_for_non_none_defaults(self):
+        """Test override=False respects user-set keys even for non-None defaults."""
+        # chunk_size has default 256 (not None)
+        # User explicitly sets it to 512
+        config = LMCacheEngineConfig.from_defaults(chunk_size=512)
+        assert config.chunk_size == 512
+        assert "chunk_size" in config._user_set_keys
+
+        # Remote config tries to set it with override=False
+        result = validate_and_set_config_value(
+            config, "chunk_size", 1024, override=False
+        )
+        assert result is True
+        # Value should NOT change because user set it
+        assert config.chunk_size == 512
+
+    def test_override_true_ignores_user_set_keys(self):
+        """Test that override=True changes value even if user-set."""
+        config = LMCacheEngineConfig.from_defaults(chunk_size=512)
+        assert "chunk_size" in config._user_set_keys
+
+        result = validate_and_set_config_value(
+            config, "chunk_size", 1024, override=True
+        )
+        assert result is True
+        # Value SHOULD change because override=True
+        assert config.chunk_size == 1024
+
+
+class TestValidateAndSetConfigValueTypeConversion:
+    """Test cases for type conversion in validate_and_set_config_value function."""
+
+    def test_convert_string_to_int(self):
+        """Test that string values are converted to int for int config keys."""
+        config = LMCacheEngineConfig.from_defaults()
+        # chunk_size is defined as int with int() as env_converter
+        result = validate_and_set_config_value(config, "chunk_size", "512")
+        assert result is True
+        assert config.chunk_size == 512
+        assert isinstance(config.chunk_size, int)
+
+    def test_convert_string_to_bool(self):
+        """Test that string values are converted to bool for bool config keys."""
+        config = LMCacheEngineConfig.from_defaults()
+        # save_decode_cache is defined as bool with _to_bool as env_converter
+        result = validate_and_set_config_value(config, "save_decode_cache", "true")
+        assert result is True
+        assert config.save_decode_cache is True
+        assert isinstance(config.save_decode_cache, bool)
+
+    def test_convert_string_false_to_bool(self):
+        """Test that 'false' string is converted to False."""
+        config = LMCacheEngineConfig.from_defaults()
+        result = validate_and_set_config_value(config, "save_decode_cache", "false")
+        assert result is True
+        assert config.save_decode_cache is False
+
+    def test_convert_string_to_int_list(self):
+        """Test that comma-separated string is converted to int list."""
+        config = LMCacheEngineConfig.from_defaults()
+        # internal_api_server_include_index_list uses _to_int_list converter
+        result = validate_and_set_config_value(
+            config, "internal_api_server_include_index_list", "1,2,3"
+        )
+        assert result is True
+        assert config.internal_api_server_include_index_list == [1, 2, 3]
+
+    def test_convert_invalid_string_to_int_fails(self):
+        """Test that invalid string fails to convert to int."""
+        config = LMCacheEngineConfig.from_defaults()
+        original_value = config.chunk_size
+        result = validate_and_set_config_value(config, "chunk_size", "not_a_number")
+        assert result is False
+        # Value should remain unchanged
+        assert config.chunk_size == original_value
+
+    def test_convert_none_value_succeeds(self):
+        """Test that None value can be set without conversion error."""
+        config = LMCacheEngineConfig.from_defaults()
+        # remote_url accepts None
+        result = validate_and_set_config_value(config, "remote_url", None)
+        assert result is True
+        assert config.remote_url is None
+
+    def test_convert_already_correct_type(self):
+        """Test that values of correct type are passed through."""
+        config = LMCacheEngineConfig.from_defaults()
+        result = validate_and_set_config_value(config, "chunk_size", 512)
+        assert result is True
+        assert config.chunk_size == 512
+
+    def test_extra_config_json_string_conversion(self):
+        """Test that JSON string is converted to dict for extra_config."""
+        config = LMCacheEngineConfig.from_defaults()
+        json_str = '{"key": "value", "num": 42}'
+        result = validate_and_set_config_value(config, "extra_config", json_str)
+        assert result is True
+        assert config.extra_config == {"key": "value", "num": 42}
+
+    def test_extra_config_invalid_json_fails(self):
+        """Test that invalid JSON string for extra_config fails."""
+        config = LMCacheEngineConfig.from_defaults()
+        result = validate_and_set_config_value(config, "extra_config", "{invalid_json")
+        assert result is False
+
+
+def test_lmcache_get_or_create_config_validates_pd_settings():
+    # First Party
+    from lmcache.integration.vllm.utils import lmcache_get_or_create_config
+    import lmcache.integration.vllm.utils as vllm_utils
+
+    os.environ["LMCACHE_ENABLE_PD"] = "true"
+    os.environ["LMCACHE_PD_ROLE"] = "sender"
+    os.environ["LMCACHE_PD_BUFFER_SIZE"] = "1024"
+    os.environ["LMCACHE_PD_BUFFER_DEVICE"] = "cpu"
+    os.environ.pop("LMCACHE_CONFIG_FILE", None)
+    os.environ.pop("LMCACHE_SAVE_UNFULL_CHUNK", None)
+
+    # Reset singleton so we get a fresh config
+    old_instance = vllm_utils._config_instance
+    vllm_utils._config_instance = None
+
+    try:
+        config = lmcache_get_or_create_config()
+        assert config.save_unfull_chunk is True, (
+            "validate() was not called — save_unfull_chunk should be "
+            "auto-set to True for P/D mode"
+        )
+    finally:
+        vllm_utils._config_instance = old_instance
+        del os.environ["LMCACHE_ENABLE_PD"]
+        del os.environ["LMCACHE_PD_ROLE"]
+        del os.environ["LMCACHE_PD_BUFFER_SIZE"]
+        del os.environ["LMCACHE_PD_BUFFER_DEVICE"]
+
+
+def test_sglang_lmcache_get_config_validates_pd_settings(tmp_path):
+    # First Party
+    from lmcache.integration.sglang.utils import lmcache_get_config
+
+    config_path = tmp_path / "lmcache_pd.yaml"
+    config_path.write_text(
+        "\n".join(
+            [
+                "enable_pd: true",
+                "pd_role: sender",
+                "pd_buffer_size: 1024",
+                "pd_buffer_device: cpu",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    config = lmcache_get_config(str(config_path))
+    assert config.save_unfull_chunk is True, (
+        "validate() was not called — save_unfull_chunk should be "
+        "auto-set to True for P/D mode"
+    )
+
+
+def test_update_config_from_env_calls_validate():
+    """Test that update_config_from_env() calls validate() method.
+
+    This is a regression test for the issue where _validate_config at line 504
+    was not being called after commit 3d88cee. The issue was that the custom
+    _update_config_from_env method was removed from namespace_extras, causing
+    the config to use the base implementation which doesn't call validate().
+    """
+    # Set up environment for PD mode which requires validation
+    os.environ["LMCACHE_ENABLE_PD"] = "true"
+    os.environ["LMCACHE_PD_ROLE"] = "sender"
+    os.environ["LMCACHE_PD_BUFFER_SIZE"] = "1024"
+    os.environ["LMCACHE_PD_BUFFER_DEVICE"] = "cpu"
+    os.environ["LMCACHE_SAVE_UNFULL_CHUNK"] = "false"
+
+    try:
+        # Create a config and update from env
+        config = LMCacheEngineConfig.from_defaults()
+        config.update_config_from_env()
+
+        # If validate() was called, save_unfull_chunk should be auto-set to True
+        # because PD mode requires it (see line 558-564 in config.py)
+        assert config.save_unfull_chunk is True, (
+            "validate() was not called - save_unfull_chunk should be True for PD mode"
+        )
+    finally:
+        # Clean up environment
+        del os.environ["LMCACHE_ENABLE_PD"]
+        del os.environ["LMCACHE_PD_ROLE"]
+        del os.environ["LMCACHE_PD_BUFFER_SIZE"]
+        del os.environ["LMCACHE_PD_BUFFER_DEVICE"]
+        del os.environ["LMCACHE_SAVE_UNFULL_CHUNK"]
+
+
+class TestControllerConfigValidation:
+    """Test validation of required controller fields when enable_controller=True."""
+
+    def _make_controller_config(self, **overrides):
+        """Create a config with controller enabled and all required fields set.
+
+        Override specific fields to None to test individual validation checks.
+        Note: lmcache_instance_id is auto-generated in __post_init__ if None,
+        so we set it after construction to test the validation path.
+        """
+        defaults = dict(
+            enable_controller=True,
+            controller_pull_url="tcp://localhost:5555",
+            controller_reply_url="tcp://localhost:5556",
+            lmcache_worker_ports=[8000],
+        )
+        # lmcache_instance_id must be set after construction because
+        # __post_init__ auto-generates it when None
+        instance_id = overrides.pop("lmcache_instance_id", "instance-1")
+        defaults.update(overrides)
+        config = LMCacheEngineConfig.from_defaults(**defaults)
+        config.lmcache_instance_id = instance_id
+        return config
+
+    def test_controller_requires_lmcache_instance_id(self):
+        config = self._make_controller_config(lmcache_instance_id=None)
+        with pytest.raises(ValueError, match="lmcache_instance_id"):
+            config.validate()
+
+    def test_controller_requires_controller_pull_url(self):
+        config = self._make_controller_config(controller_pull_url=None)
+        with pytest.raises(ValueError, match="controller_pull_url"):
+            config.validate()
+
+    def test_controller_requires_controller_reply_url(self):
+        config = self._make_controller_config(controller_reply_url=None)
+        with pytest.raises(ValueError, match="controller_reply_url"):
+            config.validate()
+
+    def test_controller_requires_lmcache_worker_ports(self):
+        config = self._make_controller_config(lmcache_worker_ports=None)
+        with pytest.raises(ValueError, match="lmcache_worker_ports"):
+            config.validate()
+
+    def test_controller_rejects_empty_worker_ports(self):
+        config = self._make_controller_config(lmcache_worker_ports=[])
+        with pytest.raises(ValueError, match="cannot be empty"):
+            config.validate()
+
+    def test_controller_valid_config_no_error(self):
+        config = self._make_controller_config()
+        config.validate()  # Should not raise
+
+    def test_controller_disabled_no_error(self):
+        config = LMCacheEngineConfig.from_defaults(
+            enable_controller=False,
+        )
+        # All controller fields are None by default; should not raise
+        config.validate()
+
+
+class TestNixlBufferDeviceCpuValidation:
+    """Validate the rejection of nixl_buffer_size in CPU mode and the
+    max_local_cpu_size requirement (see review item #1)."""
+
+    @staticmethod
+    def _nixl_cpu_defaults(**overrides: Any) -> LMCacheEngineConfig:
+        config = LMCacheEngineConfig.from_defaults()
+        config.nixl_buffer_device = "cpu"
+        config.extra_config = {
+            "enable_nixl_storage": True,
+            "nixl_backend": "POSIX",
+            "nixl_pool_size": 2,
+            "nixl_path": "/tmp/nixl/cache",
+        }
+        for key, value in overrides.items():
+            setattr(config, key, value)
+        return config
+
+    def test_cpu_mode_rejects_nixl_buffer_size(self):
+        config = self._nixl_cpu_defaults(nixl_buffer_size=2**30)
+        with pytest.raises(ValueError, match="nixl_buffer_size must not be set"):
+            config.validate()
+
+    def test_cpu_mode_requires_max_local_cpu_size_positive(self):
+        config = self._nixl_cpu_defaults(max_local_cpu_size=0.0)
+        with pytest.raises(ValueError, match="max_local_cpu_size > 0"):
+            config.validate()
+
+    def test_cpu_mode_valid_when_buffer_size_unset(self):
+        config = self._nixl_cpu_defaults()
+        config.validate()  # Should not raise
+
+    def test_gpu_mode_still_requires_nixl_buffer_size(self):
+        config = self._nixl_cpu_defaults(nixl_buffer_device="cuda")
+        with pytest.raises(AssertionError):
+            config.validate()
+
+    def test_gpu_mode_accepts_nixl_buffer_size(self):
+        config = self._nixl_cpu_defaults(
+            nixl_buffer_device="cuda", nixl_buffer_size=2**30
+        )
+        config.validate()  # Should not raise
+
+    def test_cpu_mode_rejects_enable_p2p(self):
+        """P2P and the NIXL storage backend would both run NIXL agents over
+        LocalCPUBackend's pinned pool when nixl_buffer_device=cpu. The
+        combination is structurally supported but has no CI coverage and
+        has not been exercised end-to-end; reject until it has been."""
+        config = self._nixl_cpu_defaults()
+        # enable_p2p has its own validate() preconditions (controller URLs,
+        # peer ports, transfer_channel); set them so we hit the NIXL block.
+        config.enable_p2p = True
+        config.enable_controller = True
+        config.controller_pull_url = "tcp://localhost:9001"
+        config.controller_reply_url = "tcp://localhost:9002"
+        config.lmcache_instance_id = "test"
+        config.lmcache_worker_ports = [9000]
+        config.p2p_host = "localhost"
+        config.p2p_init_ports = [9003]
+        config.p2p_lookup_ports = [9004]
+        config.transfer_channel = "nixl"
+        with pytest.raises(ValueError, match="has not been validated end-to-end"):
+            config.validate()
+
+    def test_gpu_mode_accepts_enable_p2p(self):
+        """The P2P + NIXL storage combo is only rejected in CPU mode; the
+        GPU-mode path doesn't touch LocalCPUBackend's allocator."""
+        config = self._nixl_cpu_defaults(
+            nixl_buffer_device="cuda", nixl_buffer_size=2**30
+        )
+        config.enable_p2p = True
+        config.enable_controller = True
+        config.controller_pull_url = "tcp://localhost:9001"
+        config.controller_reply_url = "tcp://localhost:9002"
+        config.lmcache_instance_id = "test"
+        config.lmcache_worker_ports = [9000]
+        config.p2p_host = "localhost"
+        config.p2p_init_ports = [9003]
+        config.p2p_lookup_ports = [9004]
+        config.transfer_channel = "nixl"
+        config.validate()  # Should not raise
+
+
+class TestNixlUseHugepagesDeprecation:
+    """Validate the deprecation alias for extra_config.nixl_use_hugepages.
+
+    The flag is replaced by the top-level local_cpu_use_hugepages: hugepages
+    have never applied to GPU buffers, and in CPU mode the NIXL pool is now
+    owned by LocalCPUBackend. validate() must alias the value into
+    local_cpu_use_hugepages in CPU mode, warn in GPU mode, and pop the
+    deprecated key in both cases (see review item #2).
+    """
+
+    @staticmethod
+    def _nixl_cpu_defaults(**overrides: Any) -> LMCacheEngineConfig:
+        config = LMCacheEngineConfig.from_defaults()
+        config.nixl_buffer_device = "cpu"
+        config.extra_config = {
+            "enable_nixl_storage": True,
+            "nixl_backend": "POSIX",
+            "nixl_pool_size": 2,
+            "nixl_path": "/tmp/nixl/cache",
+        }
+        for key, value in overrides.items():
+            setattr(config, key, value)
+        return config
+
+    def test_cpu_mode_aliases_to_local_cpu_use_hugepages(self):
+        config = self._nixl_cpu_defaults()
+        config.extra_config["nixl_use_hugepages"] = True
+        assert config.local_cpu_use_hugepages is False  # default
+        config.validate()
+        assert config.local_cpu_use_hugepages is True
+        assert "nixl_use_hugepages" not in config.extra_config
+
+    def test_cpu_mode_conflicting_values_raise(self):
+        config = LMCacheEngineConfig.from_defaults(local_cpu_use_hugepages=False)
+        config.nixl_buffer_device = "cpu"
+        config.extra_config = {
+            "enable_nixl_storage": True,
+            "nixl_backend": "POSIX",
+            "nixl_pool_size": 2,
+            "nixl_path": "/tmp/nixl/cache",
+            "nixl_use_hugepages": True,
+        }
+        with pytest.raises(ValueError, match="Conflicting hugepage settings"):
+            config.validate()
+
+    def test_cpu_mode_agreeing_values_no_conflict(self):
+        config = LMCacheEngineConfig.from_defaults(local_cpu_use_hugepages=True)
+        config.nixl_buffer_device = "cpu"
+        config.extra_config = {
+            "enable_nixl_storage": True,
+            "nixl_backend": "POSIX",
+            "nixl_pool_size": 2,
+            "nixl_path": "/tmp/nixl/cache",
+            "nixl_use_hugepages": True,
+        }
+        config.validate()
+        assert config.local_cpu_use_hugepages is True
+        assert "nixl_use_hugepages" not in config.extra_config
+
+    def test_gpu_mode_drops_flag_without_aliasing(self):
+        """In GPU mode the flag was always a no-op; alias would be misleading
+        (LocalCPUBackend's hugepages should not be toggled by a NIXL knob in
+        a GPU-only deployment). Just drop it with a warning."""
+        config = self._nixl_cpu_defaults(
+            nixl_buffer_device="cuda", nixl_buffer_size=2**30
+        )
+        config.extra_config["nixl_use_hugepages"] = True
+        config.validate()
+        assert config.local_cpu_use_hugepages is False  # unchanged
+        assert "nixl_use_hugepages" not in config.extra_config
+
+    def test_flag_absent_is_noop(self):
+        """No-op when the deprecated flag isn't set; local_cpu_use_hugepages
+        keeps whatever value the user set."""
+        config = LMCacheEngineConfig.from_defaults(local_cpu_use_hugepages=True)
+        config.nixl_buffer_device = "cpu"
+        config.extra_config = {
+            "enable_nixl_storage": True,
+            "nixl_backend": "POSIX",
+            "nixl_pool_size": 2,
+            "nixl_path": "/tmp/nixl/cache",
+        }
+        config.validate()
+        assert config.local_cpu_use_hugepages is True
diff --git a/tests/v1/test_connector.py b/tests/v1/test_connector.py
new file mode 100644
index 0000000..e94e51a
--- /dev/null
+++ b/tests/v1/test_connector.py
@@ -0,0 +1,452 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+from unittest.mock import patch
+import asyncio
+import tempfile
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.protocol import RemoteMetadata
+from lmcache.v1.storage_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.connector import CreateConnector
+
+# Local
+from .utils import (
+    check_mem_obj_equal,
+    close_asyncio_loop,
+    dumb_cache_engine_key,
+    init_asyncio_loop,
+)
+
+
+@pytest.mark.parametrize("lmserver_v1_process", ["cpu"], indirect=True)
+@pytest.mark.parametrize(
+    "url",
+    [
+        "lm://localhost:65000",
+    ],
+)
+def test_lm_connector(url, autorelease_v1, lmserver_v1_process):
+    if url.startswith("lm"):
+        url = lmserver_v1_process.server_url
+
+    async_loop, async_thread = init_asyncio_loop()
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    local_cpu_backend = _create_local_cpu_backend(memory_allocator, False)
+    connector = autorelease_v1(CreateConnector(url, async_loop, local_cpu_backend))
+
+    random_key = dumb_cache_engine_key()
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert not future.result()
+
+    num_tokens = 1000
+    mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+    dtype = torch.bfloat16
+    memory_obj = local_cpu_backend.allocate(mem_obj_shape, dtype)
+    memory_obj.ref_count_up()
+
+    torch.manual_seed(42)
+    test_tensor = torch.randint(0, 100, memory_obj.raw_data.shape, dtype=torch.int64)
+    memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+    future = asyncio.run_coroutine_threadsafe(
+        connector.put(random_key, memory_obj), async_loop
+    )
+    future.result()
+
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert future.result()
+    assert memory_obj.get_ref_count() == 1
+
+    future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+    retrieved_memory_obj = future.result()
+
+    check_mem_obj_equal(
+        [retrieved_memory_obj],
+        [memory_obj],
+    )
+
+    close_asyncio_loop(async_loop, async_thread)
+    local_cpu_backend.close()
+
+
+@pytest.mark.parametrize("full_chunk", [True, False])
+@pytest.mark.parametrize("save_chunk_meta", [True, False])
+@pytest.mark.parametrize("use_mla", [True, False])
+def test_fs_connector(autorelease_v1, full_chunk, save_chunk_meta, use_mla):
+    """
+    Test FSConnector: exists, put, get, list, and file store
+    with the following conditions:
+    full_chunk: is the block full
+    save_chunk_meta: save the metadata of the chunk or not
+    use_mla: is mla enabled
+    """
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        # Setup
+        url = f"fs://host:0/{temp_dir}/"
+        async_loop, async_thread = init_asyncio_loop()
+        memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+        # full chunk's kv_shape (num_layer, 2, chunk_size, num_kv_head, head_size)
+        kv_shape = (32, 1 if use_mla else 2, 256, 1 if use_mla else 8, 128)
+        dtype = torch.bfloat16
+        config = LMCacheEngineConfig.from_defaults(
+            extra_config={"save_chunk_meta": save_chunk_meta}
+        )
+        local_cpu_backend = _create_local_cpu_backend(memory_allocator, use_mla, config)
+        connector = autorelease_v1(
+            CreateConnector(url, async_loop, local_cpu_backend, config)
+        )
+        random_key = dumb_cache_engine_key()
+
+        # Test 1: Verify key doesn't exist initially
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(random_key), async_loop
+        )
+        assert not future.result()
+
+        # Test 2: Create and store test data
+        # The size of the full chunk is 256.
+        # If test unfull chunk, use 100 (<256) to allocate memory_obj.
+        memory_obj_shape = torch.Size(
+            [
+                kv_shape[1],
+                kv_shape[0],
+                kv_shape[2] if full_chunk else 100,
+                kv_shape[3] * kv_shape[4],
+            ]
+        )
+        memory_obj = local_cpu_backend.allocate(memory_obj_shape, dtype)
+        memory_obj.ref_count_up()
+        # Fill with deterministic test data
+        torch.manual_seed(42)
+        test_tensor = torch.randint(
+            0, 100, memory_obj.raw_data.shape, dtype=torch.int64
+        )
+        memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+        future = asyncio.run_coroutine_threadsafe(
+            connector.put(random_key, memory_obj), async_loop
+        )
+        future.result()
+
+        # Test 3: Verify key exists after putting data
+        future = asyncio.run_coroutine_threadsafe(
+            connector.exists(random_key), async_loop
+        )
+        assert future.result()
+        assert memory_obj.get_ref_count() == 1
+
+        # Test 4: Retrieve and verify data
+        future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+        check_mem_obj_equal([future.result()], [memory_obj], use_mla)
+
+        # Test 5: List the keys
+        future = asyncio.run_coroutine_threadsafe(connector.list(), async_loop)
+        assert future.result() == [random_key.to_string()]
+
+        # Test 6: Verify file existence and other attributes
+        # file name
+        files = list(Path(temp_dir).glob("*.data"))
+        assert len(files) == 1
+        assert files[0].name == f"{random_key.to_string()}.data"
+
+        # file size
+        dtype_size = torch.tensor([], dtype=dtype).element_size()
+        num_elements = 1
+        for dim in memory_obj_shape:
+            num_elements *= dim
+        expected_file_size = dtype_size * num_elements + (28 if save_chunk_meta else 0)
+        assert files[0].stat().st_size == expected_file_size
+
+        close_asyncio_loop(async_loop, async_thread)
+        local_cpu_backend.close()
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "redis://localhost:6379",
+        "redis://user:password@localhost:6379/0",
+        "redis://:password@localhost:6379/1",
+        "rediss://user:password@localhost:6380?ssl_cert_reqs=CERT_REQUIRED",
+        "unix:///tmp/redis.sock",
+        "plugin://redis",
+    ],
+)
+def test_redis_connector(url, autorelease_v1):
+    """Test Redis connector: exists, put, get operations.
+
+    This test uses the MockRedis from conftest.py to simulate
+    Redis behavior without requiring an actual Redis server.
+    """
+
+    async_loop, async_thread = init_asyncio_loop()
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    local_cpu_backend = _create_local_cpu_backend(memory_allocator, False)
+    connector = autorelease_v1(CreateConnector(url, async_loop, local_cpu_backend))
+
+    random_key = dumb_cache_engine_key()
+
+    # Test 1: Verify key doesn't exist initially
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert not future.result()
+
+    # Test 2: Create and store test data
+    num_tokens = 1000
+    mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+    dtype = torch.bfloat16
+    memory_obj = local_cpu_backend.allocate(mem_obj_shape, dtype)
+    memory_obj.ref_count_up()
+
+    torch.manual_seed(42)
+    test_tensor = torch.randint(0, 100, memory_obj.raw_data.shape, dtype=torch.int64)
+    memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+    # Test 3: Put data
+    future = asyncio.run_coroutine_threadsafe(
+        connector.put(random_key, memory_obj), async_loop
+    )
+    future.result()
+
+    # Test 4: Verify key exists after putting data
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert future.result()
+    assert memory_obj.get_ref_count() == 1
+
+    # Test 5: Retrieve and verify data
+    future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+    retrieved_memory_obj = future.result()
+
+    check_mem_obj_equal(
+        [retrieved_memory_obj],
+        [memory_obj],
+    )
+
+    close_asyncio_loop(async_loop, async_thread)
+    local_cpu_backend.close()
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "redis-sentinel://localhost:26379,localhost:26380,localhost:26381",
+        "redis-sentinel://user:password@localhost:26379,localhost:26380",
+        "redis-sentinel://localhost:26379",
+    ],
+)
+def test_redis_sentinel_connector(url, autorelease_v1):
+    """Test Redis Sentinel connector: exists, put, get operations.
+
+    This test uses the MockRedisSentinel from conftest.py to simulate
+    Redis Sentinel behavior without requiring an actual Redis Sentinel setup.
+    """
+    # Standard
+    import os
+
+    # Set required environment variables for Redis Sentinel
+    os.environ["REDIS_SERVICE_NAME"] = "mymaster"
+    os.environ["REDIS_TIMEOUT"] = "5"
+
+    async_loop, async_thread = init_asyncio_loop()
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    local_cpu_backend = _create_local_cpu_backend(memory_allocator, False)
+    connector = autorelease_v1(CreateConnector(url, async_loop, local_cpu_backend))
+
+    random_key = dumb_cache_engine_key()
+
+    # Test 1: Verify key doesn't exist initially
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert not future.result()
+
+    # Test 2: Create and store test data
+    num_tokens = 1000
+    mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+    dtype = torch.bfloat16
+    memory_obj = local_cpu_backend.allocate(mem_obj_shape, dtype)
+    memory_obj.ref_count_up()
+
+    # Fill with deterministic test data for Redis Sentinel test
+    torch.manual_seed(123)
+    test_tensor = torch.randint(0, 100, memory_obj.raw_data.shape, dtype=torch.int64)
+    memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+    # Test 3: Put data
+    future = asyncio.run_coroutine_threadsafe(
+        connector.put(random_key, memory_obj), async_loop
+    )
+    future.result()
+
+    # Test 4: Verify key exists after putting data
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert future.result()
+
+    # Test 5: Retrieve and verify data
+    future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+    future.result()
+
+    close_asyncio_loop(async_loop, async_thread)
+    local_cpu_backend.close()
+
+
+REDIS_CLUSTER_URLS = [
+    "redis-cluster://host1:7000,host2:7000,host3:7000",
+    "redis-cluster://clustercfg.cluster-name.id.region.cache.amazonaws.com:6379",
+    "redis-cluster://user:password@host1:7000,host2:7000,host3:7000",
+]
+
+
+@pytest.mark.parametrize("url", REDIS_CLUSTER_URLS)
+def test_redis_cluster_connector(url, autorelease_v1):
+    """Test Redis Cluster connector: exists, put, get operations.
+
+    This test uses the MockRedisCluster from conftest.py to simulate
+    Redis Cluster behavior without requiring an actual Redis Cluster setup.
+    """
+
+    # Standard
+    import os
+
+    os.environ["REDIS_TIMEOUT"] = "3.5"
+
+    async_loop, async_thread = init_asyncio_loop()
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    local_cpu_backend = _create_local_cpu_backend(memory_allocator, False)
+    connector = autorelease_v1(CreateConnector(url, async_loop, local_cpu_backend))
+
+    random_key = dumb_cache_engine_key()
+
+    # Test 1: Verify key doesn't exist initially, test contains key not exist
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert not future.result()
+
+    # Test 2: Create and store test data
+    num_tokens = 1000
+    mem_obj_shape = torch.Size([2, 32, num_tokens, 1024])
+    dtype = torch.bfloat16
+    memory_obj = local_cpu_backend.allocate(mem_obj_shape, dtype)
+    memory_obj.ref_count_up()
+
+    # Fill with deterministic test data
+    torch.manual_seed(42)
+    test_tensor = torch.randint(0, 100, memory_obj.raw_data.shape, dtype=torch.int64)
+    memory_obj.raw_data.copy_(test_tensor.to(torch.float32).to(dtype))
+
+    # Test 3: Put data
+    future = asyncio.run_coroutine_threadsafe(
+        connector.put(random_key, memory_obj), async_loop
+    )
+    future.result()
+
+    # Test 4: Verify key exists after putting data, test contains key exists
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert future.result()
+    assert memory_obj.get_ref_count() == 1
+
+    # Test 5: Retrieve and verify data
+    future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+    retrieved_memory_obj = future.result()
+
+    check_mem_obj_equal([retrieved_memory_obj], [memory_obj])
+
+    close_asyncio_loop(async_loop, async_thread)
+    local_cpu_backend.close()
+
+
+@pytest.mark.parametrize("url", REDIS_CLUSTER_URLS)
+def test_cluster_metadata_without_kv_bytes(url, autorelease_v1):
+    async_loop, async_thread = init_asyncio_loop()
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    local_cpu_backend = _create_local_cpu_backend(memory_allocator, False)
+    connector = autorelease_v1(CreateConnector(url, async_loop, local_cpu_backend))
+
+    random_key = dumb_cache_engine_key()
+    # build a small mem obj to get correct metadata bytes
+    memory_obj = local_cpu_backend.allocate(torch.Size([2, 32, 8, 64]), torch.bfloat16)
+    kv_bytes = memory_obj.byte_array
+    meta = RemoteMetadata(
+        len(kv_bytes),
+        memory_obj.get_shapes(),
+        memory_obj.get_dtypes(),
+        memory_obj.get_memory_format(),
+    )
+    metadata_bytes = meta.serialize()
+
+    # clean up memory object after getting metadata
+    memory_obj.ref_count_down()
+
+    # inject only metadata, no kv_bytes
+    meta_key = random_key.to_string() + "metadata"
+    connector._connector.cluster.set(meta_key, metadata_bytes)
+
+    # get() should return None and remove the metadata without kv_bytes pair
+    future = asyncio.run_coroutine_threadsafe(connector.get(random_key), async_loop)
+    assert future.result() is None
+
+    future = asyncio.run_coroutine_threadsafe(connector.exists(random_key), async_loop)
+    assert not future.result()
+
+    close_asyncio_loop(async_loop, async_thread)
+    local_cpu_backend.close()
+
+
+def _get_metadata(use_mla: bool):
+    kv_shape = (32, 1 if use_mla else 2, 256, 1 if use_mla else 8, 128)
+    dtype = torch.bfloat16
+    metadata = LMCacheMetadata(
+        model_name="deepseek/DeepSeek-R1",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=dtype,
+        kv_shape=kv_shape,
+        use_mla=use_mla,
+    )
+    return metadata
+
+
+def _create_local_cpu_backend(memory_allocator, use_mla, config=None):
+    if config is None:
+        config = LMCacheEngineConfig.from_defaults()
+    metadata = _get_metadata(use_mla)
+    return LocalCPUBackend(
+        config=config, metadata=metadata, memory_allocator=memory_allocator
+    )
+
+
+@patch("lmcache.v1.storage_backend.connector.redis_connector.RedisConnector")
+def test_redis_plugin_custom_url(mock_redis_connector, autorelease_v1) -> None:
+    """Verify that RedisConnectorAdapter extracts custom Redis URL
+    from extra_config when loaded dynamically as a plugin.
+    """
+    async_loop, async_thread = init_asyncio_loop()
+    memory_allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+    local_cpu_backend = _create_local_cpu_backend(memory_allocator, False)
+
+    # Define custom Redis URL inside extra_config
+    custom_url = "redis://my-custom-redis-host:6379"
+    config = LMCacheEngineConfig.from_defaults(
+        extra_config={"remote_storage_plugin.redis.redis_url": custom_url}
+    )
+
+    # Create connector using dynamic plugin schema URL
+    autorelease_v1(
+        CreateConnector("plugin://redis", async_loop, local_cpu_backend, config)
+    )
+
+    mock_redis_connector.assert_called_once_with(
+        url=custom_url,
+        loop=async_loop,
+        local_cpu_backend=local_cpu_backend,
+    )
+
+    close_asyncio_loop(async_loop, async_thread)
+    local_cpu_backend.close()
diff --git a/tests/v1/test_connector_discovery.py b/tests/v1/test_connector_discovery.py
new file mode 100644
index 0000000..8b899c5
--- /dev/null
+++ b/tests/v1/test_connector_discovery.py
@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from types import ModuleType
+import asyncio
+import importlib
+import pkgutil
+
+# First Party
+from lmcache.v1.storage_backend.connector import ConnectorAdapter, ConnectorManager
+
+
+def test_discover_adapters(monkeypatch):
+    """Validate adapter discovery filters modules and tolerates failures.
+
+    Args:
+        monkeypatch: Pytest fixture for patching module discovery.
+    """
+
+    class GoodAdapter(ConnectorAdapter):
+        """Connector adapter used to verify discovery success."""
+
+        def __init__(self) -> None:
+            super().__init__("good://")
+
+        def create_connector(self, context):
+            raise AssertionError("not used")
+
+    class BrokenAdapter(ConnectorAdapter):
+        """Connector adapter that fails during instantiation."""
+
+        def __init__(self) -> None:
+            raise RuntimeError("boom")
+
+        def create_connector(self, context):
+            raise AssertionError("not used")
+
+    good_module = ModuleType("good_adapter")
+    good_module.GoodAdapter = GoodAdapter
+    good_module.NotAnAdapter = object
+
+    broken_module = ModuleType("broken_adapter")
+    broken_module.BrokenAdapter = BrokenAdapter
+
+    non_adapter_module = ModuleType("non_adapter")
+    non_adapter_module.NotAnAdapter = object
+
+    fake_package = ModuleType("lmcache.v1.storage_backend.connector")
+    fake_package.__path__ = []  # type: ignore[attr-defined]
+
+    def fake_iter_modules(_path):
+        """Yield a mix of adapter and non-adapter module names."""
+        yield None, "good_adapter", False
+        yield None, "_private_adapter", False
+        yield None, "non_adapter", False
+        yield None, "broken_adapter", False
+        yield None, "missing_adapter", False
+
+    def fake_import_module(name):
+        """Return fake modules or simulate import failure."""
+        if name == "lmcache.v1.storage_backend.connector":
+            return fake_package
+        if name.endswith(".good_adapter"):
+            return good_module
+        if name.endswith(".broken_adapter"):
+            return broken_module
+        if name.endswith(".non_adapter"):
+            return non_adapter_module
+        if name.endswith(".missing_adapter"):
+            raise ImportError("missing module")
+        raise AssertionError(f"unexpected import: {name}")
+
+    monkeypatch.setattr(pkgutil, "iter_modules", fake_iter_modules)
+    monkeypatch.setattr(importlib, "import_module", fake_import_module)
+
+    loop = asyncio.new_event_loop()
+    try:
+        manager = ConnectorManager("lm://localhost:1234", loop, None)
+    finally:
+        loop.close()
+
+    assert len(manager.adapters) == 1
+    assert isinstance(manager.adapters[0], GoodAdapter)
diff --git a/tests/v1/test_decode_save_and_preemption.py b/tests/v1/test_decode_save_and_preemption.py
new file mode 100644
index 0000000..7fb5a40
--- /dev/null
+++ b/tests/v1/test_decode_save_and_preemption.py
@@ -0,0 +1,402 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for:
+1. Fix: decode save cache token slicing uses min(num_computed_tokens, tracker_len)
+2. Fix: preemption assertion allows off-by-one from full-hit adjustment
+
+These tests exercise the token slicing and assertion logic in
+build_connector_meta (vllm_v1_adapter.py) without requiring GPU or vLLM server.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+
+# Third Party
+import pytest
+
+# ---------------------------------------------------------------------------
+# Minimal stubs — just enough to test the slicing + assertion logic
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class StubRequest:
+    """Minimal vLLM Request stub."""
+
+    request_id: str
+    num_computed_tokens: int
+    _all_token_ids: list[int] = field(default_factory=list)
+    num_tokens: int = 0
+
+    @property
+    def all_token_ids(self):
+        return self._all_token_ids
+
+
+@dataclass
+class StubLoadSpec:
+    vllm_cached_tokens: int
+    lmcache_cached_tokens: int
+    can_load: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Extracted logic under test
+# ---------------------------------------------------------------------------
+
+
+def compute_new_token_ids(
+    request: StubRequest,
+    tracker_token_ids: list[int],
+    num_new_tokens: int,
+) -> list[int]:
+    """
+    Reproduces the fixed token slicing logic from build_connector_meta.
+    Uses min(num_computed_tokens, tracker_len) as slice base.
+    """
+    num_current_tokens = request.num_computed_tokens
+    tracker_len = len(tracker_token_ids)
+    slice_base = min(num_current_tokens, tracker_len)
+    return list(request.all_token_ids[slice_base : slice_base + num_new_tokens])
+
+
+def check_preemption_assertion(
+    request: StubRequest,
+    load_spec: StubLoadSpec,
+):
+    """
+    Reproduces the fixed assertion from build_connector_meta for preempted
+    requests. On full cache hit where lmcache is dominant, expected is -1.
+    """
+    expected = max(load_spec.lmcache_cached_tokens, load_spec.vllm_cached_tokens)
+    full_hit_adj = (
+        load_spec.lmcache_cached_tokens == request.num_tokens
+        and load_spec.lmcache_cached_tokens > load_spec.vllm_cached_tokens
+    )
+    if full_hit_adj:
+        expected -= 1
+    if request.num_computed_tokens != expected:
+        raise AssertionError(
+            f"Preempted request {request.request_id} has "
+            f"num_computed_tokens {request.num_computed_tokens} "
+            f"but expected {expected} (full_hit_adj={full_hit_adj})"
+        )
+
+
+# ===========================================================================
+# Fix 1: token slicing with min(num_computed_tokens, tracker_len)
+# ===========================================================================
+
+
+class TestTokenSlicing:
+    """Tests for the min()-based slice base in build_connector_meta."""
+
+    def test_sync_decode_normal(self):
+        """Normal sync decode: num_computed == tracker_len. Both in sync."""
+        prompt = list(range(100))
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=100,
+            _all_token_ids=prompt + [1001],  # T1 appended by update_from_output
+        )
+        tracker_ids = prompt.copy()
+        result = compute_new_token_ids(request, tracker_ids, num_new_tokens=1)
+        assert result == [1001], f"Should get decode token T1, got {result}"
+
+    def test_num_computed_ahead_of_tracker(self):
+        """
+        The PR #2821 scenario: num_computed_tokens was incremented (e.g. by
+        _update_after_schedule) but tracker hasn't been updated yet.
+        min() picks tracker_len, giving the correct slice.
+        """
+        prompt = list(range(100))
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=101,  # already incremented
+            _all_token_ids=prompt + [1001],
+        )
+        tracker_ids = prompt.copy()  # not yet updated
+        result = compute_new_token_ids(request, tracker_ids, num_new_tokens=1)
+        assert result == [1001], (
+            "min() should pick tracker_len=100, slicing [100:101] = [T1]"
+        )
+
+    def test_num_computed_ahead_old_code_fails(self):
+        """Verify the OLD code (using num_computed_tokens directly) would fail."""
+        prompt = list(range(100))
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=101,
+            _all_token_ids=prompt + [1001],
+        )
+        # Old code: slice base = num_computed_tokens = 101
+        old_result = request.all_token_ids[101:102]
+        assert old_result == [], "Old code produces empty slice (the bug)"
+
+    def test_preemption_tracker_stale(self):
+        """
+        Preemption: tracker has stale tokens from before preemption,
+        num_computed_tokens was reset. min() picks num_computed_tokens.
+        """
+        prompt = list(range(100))
+        decode_tokens = list(range(1001, 1051))  # 50 decode tokens
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=50,  # reset to cached prefix after preemption
+            _all_token_ids=prompt + decode_tokens,
+        )
+        tracker_ids = prompt + decode_tokens  # stale: 150 tokens
+        num_new_tokens = 50  # recompute prompt[50:100]
+
+        result = compute_new_token_ids(request, tracker_ids, num_new_tokens)
+        # min(50, 150) = 50 → slice [50:100] = prompt tokens 50-99
+        assert result == list(range(50, 100)), (
+            "min() should pick num_computed=50, getting prompt suffix"
+        )
+
+    def test_preemption_old_fix_fails(self):
+        """Verify the PR #2821 fix (tracker_len only) would fail on preemption."""
+        prompt = list(range(100))
+        decode_tokens = list(range(1001, 1051))
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=50,
+            _all_token_ids=prompt + decode_tokens,
+        )
+        tracker_ids = prompt + decode_tokens  # 150 tokens (stale)
+        tracker_len = len(tracker_ids)
+        # PR #2821 fix: slice base = tracker_len = 150
+        pr_result = request.all_token_ids[tracker_len : tracker_len + 50]
+        assert pr_result == [], "PR #2821 fix gives empty (regression)"
+
+    def test_chunked_prefill(self):
+        """Chunked prefill: tracker has first chunk, processing second."""
+        prompt = list(range(500))
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=256,  # first chunk done
+            _all_token_ids=prompt,
+        )
+        tracker_ids = prompt[:256]  # first chunk
+        num_new_tokens = 244  # second chunk
+
+        result = compute_new_token_ids(request, tracker_ids, num_new_tokens)
+        assert result == list(range(256, 500)), "Should get second chunk tokens"
+
+    def test_both_equal_zero(self):
+        """Edge case: brand new request, both are 0."""
+        prompt = list(range(100))
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=0,
+            _all_token_ids=prompt,
+        )
+        tracker_ids = []
+        result = compute_new_token_ids(request, tracker_ids, num_new_tokens=100)
+        assert result == prompt
+
+    def test_multiple_decode_steps(self):
+        """Trace through multiple decode steps to verify consistency."""
+        prompt = list(range(100))
+        tracker_ids = prompt.copy()
+
+        for step in range(10):
+            token = 1001 + step
+            all_token_ids = prompt + list(range(1001, 1001 + step + 1))
+            request = StubRequest(
+                request_id="req1",
+                num_computed_tokens=100 + step,
+                _all_token_ids=all_token_ids,
+            )
+            result = compute_new_token_ids(request, tracker_ids, num_new_tokens=1)
+            assert result == [token], f"Step {step}: expected [{token}], got {result}"
+            tracker_ids.append(token)
+
+
+# ===========================================================================
+# Fix 2: preemption assertion off-by-one
+# ===========================================================================
+
+
+class TestPreemptionAssertion:
+    """Tests for the deterministic assertion in build_connector_meta."""
+
+    def test_no_full_hit_exact_match(self):
+        """No full hit (lmcache < num_tokens): num_computed == expected."""
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=3000,
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=100,
+            lmcache_cached_tokens=3000,
+        )
+        check_preemption_assertion(request, load_spec)
+
+    def test_full_hit_lmcache_dominant(self):
+        """
+        Full hit + lmcache > vllm: get_num_new_matched_tokens subtracts 1,
+        so num_computed = expected - 1.
+        """
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=4031,  # T - 1
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=0,
+            lmcache_cached_tokens=4032,
+        )
+        check_preemption_assertion(request, load_spec)
+
+    def test_full_hit_both_equal(self):
+        """
+        Full hit but vllm == lmcache: need_to_allocate goes negative,
+        returns 0, so num_computed = vllm_cached = num_tokens. No adjustment.
+        """
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=4032,
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=4032,
+            lmcache_cached_tokens=4032,
+        )
+        check_preemption_assertion(request, load_spec)
+
+    def test_old_assertion_would_fail(self):
+        """Verify the OLD strict assertion would crash on the full-hit case."""
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=4031,
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=0,
+            lmcache_cached_tokens=4032,
+        )
+        # Old assertion: strict equality against unadjusted max
+        unadjusted = max(load_spec.lmcache_cached_tokens, load_spec.vllm_cached_tokens)
+        assert request.num_computed_tokens != unadjusted, (
+            "Confirm the old strict == would fail"
+        )
+
+    def test_off_by_two_still_fails(self):
+        """Off-by-two should still be caught."""
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=4030,  # T - 2
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=0,
+            lmcache_cached_tokens=4032,
+        )
+        with pytest.raises(AssertionError):
+            check_preemption_assertion(request, load_spec)
+
+    def test_vllm_cached_dominates(self):
+        """When vllm_cached > lmcache_cached, no adjustment."""
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=500,
+            num_tokens=1000,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=500,
+            lmcache_cached_tokens=200,
+        )
+        check_preemption_assertion(request, load_spec)
+
+    def test_vllm_dominant_wrong_value_fails(self):
+        """When vllm dominates, num_computed must equal vllm_cached exactly."""
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=499,  # wrong
+            num_tokens=1000,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=500,
+            lmcache_cached_tokens=200,
+        )
+        with pytest.raises(AssertionError):
+            check_preemption_assertion(request, load_spec)
+
+    def test_num_computed_above_expected_fails(self):
+        """num_computed > expected should fail."""
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=4032,  # should be 4031 with full hit adj
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=0,
+            lmcache_cached_tokens=4032,
+        )
+        with pytest.raises(AssertionError):
+            check_preemption_assertion(request, load_spec)
+
+    def test_realistic_batch_preemption_scenario(self):
+        """
+        Realistic scenario from the bug report: batch_size=32, preemption
+        during decode with save_decode_cache=True.
+        """
+        request = StubRequest(
+            request_id="req_batch32_7",
+            num_computed_tokens=4031,  # T - 1 due to full hit adj
+            num_tokens=4032,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=100,  # prefix cache hit (prompt)
+            lmcache_cached_tokens=4032,  # full LMCache hit
+        )
+        check_preemption_assertion(request, load_spec)
+
+
+# ===========================================================================
+# Combined: both fixes working together
+# ===========================================================================
+
+
+class TestCombinedFixes:
+    """Test that both fixes work correctly together in a preemption scenario."""
+
+    def test_preempted_full_hit_decode_flow(self):
+        """
+        Full scenario: preempted request with full LMCache hit.
+        Verifies both the slice and assertion work.
+        """
+        prompt = list(range(100))
+        decode_tokens = list(range(1001, 1101))  # 100 decode tokens
+        all_tokens = prompt + decode_tokens  # 200 total
+
+        # After preemption + reschedule with full hit (-1 adjustment):
+        request = StubRequest(
+            request_id="req1",
+            num_computed_tokens=199,  # 200 - 1 (full hit adjustment)
+            _all_token_ids=all_tokens,
+            num_tokens=200,
+        )
+        load_spec = StubLoadSpec(
+            vllm_cached_tokens=100,  # prefix cache
+            lmcache_cached_tokens=200,  # full LMCache hit
+        )
+
+        # 1. Assertion should pass (off-by-one allowed)
+        check_preemption_assertion(request, load_spec)
+
+        # 2. Token slicing: tracker is stale from before preemption
+        stale_tracker = all_tokens.copy()  # 200 tokens
+        num_new_tokens = 1  # recompute last token
+
+        result = compute_new_token_ids(request, stale_tracker, num_new_tokens)
+        # min(199, 200) = 199 → all_tokens[199:200] = [last decode token]
+        assert result == [decode_tokens[-1]], (
+            f"Should get the last decode token, got {result}"
+        )
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/tests/v1/test_device_id_race.py b/tests/v1/test_device_id_race.py
new file mode 100644
index 0000000..c6def16
--- /dev/null
+++ b/tests/v1/test_device_id_race.py
@@ -0,0 +1,178 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for NixlDynamicStorageBackend._alloc_device_ids.
+
+These tests verify the fix for the NIXL OBJ devIdToObjKey_ race condition
+(https://github.com/LMCache/LMCache/issues/2983).  When nixl_async_put is
+enabled, async PUT cleanup and sync GET run concurrently.  Both previously
+used device_id = 0, 1, 2, ... for every call, causing the PUT's
+deregister to erase the GET registration in NIXL's flat map.
+
+The fix uses a monotonically increasing counter so each register/deregister
+cycle gets globally unique device_ids.  These tests validate correctness
+and thread safety of that counter without requiring NIXL or CUDA hardware.
+"""
+
+# Standard
+import threading
+
+# Third Party
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Helper: build a minimal NixlDynamicStorageBackend with only the fields
+# needed by _alloc_device_ids, bypassing __init__'s heavy dependencies.
+# ---------------------------------------------------------------------------
+def _make_stub_backend():
+    """Return a NixlDynamicStorageBackend instance with __init__ bypassed."""
+    # Import inside function so the test file can be collected even when
+    # nixl is not installed (the importorskip below handles the skip).
+    # First Party
+    from lmcache.v1.storage_backend.nixl_storage_backend import (
+        NixlDynamicStorageBackend,
+    )
+
+    obj = object.__new__(NixlDynamicStorageBackend)
+    obj._device_id_counter = 0
+    obj._device_id_lock = threading.Lock()
+    return obj
+
+
+# Skip the entire module if nixl is not importable (mirrors existing tests)
+pytest.importorskip("nixl", reason="nixl package is required for nixl tests")
+
+
+# ---- Basic correctness ----------------------------------------------------
+
+
+class TestAllocDeviceIds:
+    """Tests for _alloc_device_ids correctness."""
+
+    def test_single_alloc_returns_sequential_range(self):
+        backend = _make_stub_backend()
+        ids = backend._alloc_device_ids(5)
+        assert ids == [0, 1, 2, 3, 4]
+
+    def test_successive_allocs_are_non_overlapping(self):
+        backend = _make_stub_backend()
+        first = backend._alloc_device_ids(3)
+        second = backend._alloc_device_ids(4)
+        third = backend._alloc_device_ids(2)
+        assert first == [0, 1, 2]
+        assert second == [3, 4, 5, 6]
+        assert third == [7, 8]
+
+    def test_alloc_zero_returns_empty(self):
+        backend = _make_stub_backend()
+        ids = backend._alloc_device_ids(0)
+        assert ids == []
+        # Counter should not advance
+        assert backend._device_id_counter == 0
+
+    def test_alloc_one_returns_single_element(self):
+        backend = _make_stub_backend()
+        ids = backend._alloc_device_ids(1)
+        assert ids == [0]
+        assert backend._device_id_counter == 1
+
+    def test_counter_advances_correctly(self):
+        backend = _make_stub_backend()
+        backend._alloc_device_ids(10)
+        assert backend._device_id_counter == 10
+        backend._alloc_device_ids(5)
+        assert backend._device_id_counter == 15
+
+    def test_all_ids_globally_unique_across_many_allocs(self):
+        backend = _make_stub_backend()
+        all_ids = []
+        for n in [1, 3, 7, 2, 10, 5]:
+            all_ids.extend(backend._alloc_device_ids(n))
+        assert len(all_ids) == len(set(all_ids)), "duplicate device_ids found"
+        assert all_ids == list(range(28))
+
+
+# ---- Thread safety ---------------------------------------------------------
+
+
+class TestAllocDeviceIdsThreadSafety:
+    """Verify no duplicate IDs under concurrent access."""
+
+    def test_concurrent_allocs_produce_unique_ids(self):
+        """Simulate the race: multiple threads calling _alloc_device_ids
+        concurrently, as happens when async PUT cleanup and sync GET
+        overlap."""
+        backend = _make_stub_backend()
+        num_threads = 16
+        allocs_per_thread = 200
+        batch_size = 5  # typical: one device_id per key in a batch
+        results: list[list[int]] = [[] for _ in range(num_threads)]
+
+        barrier = threading.Barrier(num_threads)
+
+        def worker(thread_idx):
+            barrier.wait()  # maximize contention
+            for _ in range(allocs_per_thread):
+                ids = backend._alloc_device_ids(batch_size)
+                results[thread_idx].extend(ids)
+
+        threads = [
+            threading.Thread(target=worker, args=(i,)) for i in range(num_threads)
+        ]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        all_ids = []
+        for r in results:
+            all_ids.extend(r)
+
+        expected_total = num_threads * allocs_per_thread * batch_size
+        assert len(all_ids) == expected_total
+        assert len(set(all_ids)) == expected_total, (
+            f"found {expected_total - len(set(all_ids))} duplicate device_ids "
+            f"under concurrent access"
+        )
+
+    def test_interleaved_put_get_simulation(self):
+        """Simulate interleaved PUT (async cleanup) and GET (sync worker)
+        operations to verify the fix prevents the exact race from #44."""
+        backend = _make_stub_backend()
+        put_ids: list[list[int]] = []
+        get_ids: list[list[int]] = []
+        barrier = threading.Barrier(2)
+
+        def put_worker():
+            """Simulates async PUT: register → transfer → deregister."""
+            barrier.wait()
+            for _ in range(100):
+                ids = backend._alloc_device_ids(3)
+                put_ids.append(ids)
+
+        def get_worker():
+            """Simulates sync GET: register → prepXfer → postXfer → deregister."""
+            barrier.wait()
+            for _ in range(100):
+                ids = backend._alloc_device_ids(3)
+                get_ids.append(ids)
+
+        t_put = threading.Thread(target=put_worker)
+        t_get = threading.Thread(target=get_worker)
+        t_put.start()
+        t_get.start()
+        t_put.join()
+        t_get.join()
+
+        # Flatten and check uniqueness
+        all_put = [id_ for batch in put_ids for id_ in batch]
+        all_get = [id_ for batch in get_ids for id_ in batch]
+
+        # No overlap between PUT and GET id ranges
+        overlap = set(all_put) & set(all_get)
+        assert len(overlap) == 0, (
+            f"PUT and GET device_ids overlap: {sorted(list(overlap))[:10]}..."
+        )
+
+        # All IDs globally unique
+        combined = all_put + all_get
+        assert len(combined) == len(set(combined))
diff --git a/tests/v1/test_ec_connector.py b/tests/v1/test_ec_connector.py
new file mode 100644
index 0000000..a4421be
--- /dev/null
+++ b/tests/v1/test_ec_connector.py
@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from unittest.mock import patch
+import tempfile
+import time
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("vllm", reason="EC connector adapter imports vLLM at module top")
+
+# First Party
+from lmcache.integration.vllm.vllm_ec_adapter import (  # noqa: E402
+    LMCacheECConnectorImpl,
+    LMCacheECConnectorMetadata,
+    MMMeta,
+)
+
+
+class _FakeTransferConfig:
+    def __init__(self, storage_path: str):
+        self._storage_path = storage_path
+
+    def get_from_extra_config(self, key: str, default=None):
+        if key == "shared_storage_path":
+            return self._storage_path
+        return default
+
+
+class _FakeVllmConfig:
+    def __init__(self, storage_path: str):
+        self.ec_transfer_config = _FakeTransferConfig(storage_path)
+        self.model_config = _FakeModelConfig()
+        self.parallel_config = _FakeParallelConfig()
+        self.cache_config = _FakeCacheConfig()
+
+
+class _FakeModelConfig:
+    model = "fake-model"
+    served_model_name = "fake-model"
+    dtype = torch.float16
+
+    def get_num_layers(self, parallel_config):
+        return 1
+
+    def get_num_kv_heads(self, parallel_config):
+        return 1
+
+    def get_head_size(self):
+        return 1
+
+
+class _FakeParallelConfig:
+    world_size = 1
+    rank = 0
+
+
+class _FakeCacheConfig:
+    cache_dtype = "auto"
+
+
+class _FakeRole:
+    name = "WORKER"
+
+
+class _FakeParent:
+    def __init__(self):
+        self.is_producer = True
+        self._meta = None
+
+    def _get_connector_metadata(self):
+        return self._meta
+
+
+def test_ec_roundtrip_save_then_load():
+    with tempfile.TemporaryDirectory() as td:
+        vllm_config = _FakeVllmConfig(td)
+        parent = _FakeParent()
+        conn = LMCacheECConnectorImpl(
+            vllm_config=vllm_config,
+            role=_FakeRole(),
+            parent=parent,
+        )
+
+        try:
+            mm_hash = "hash_abc"
+            x = torch.randn(7, 13, dtype=torch.float16)
+            encoder_cache = {mm_hash: x}
+
+            conn.save_caches(encoder_cache, mm_hash)
+
+            # EC storage is asynchronous across tiers; wait briefly for visibility.
+            deadline = time.time() + 2.0
+            while not conn.has_cache_item(mm_hash) and time.time() < deadline:
+                time.sleep(0.05)
+
+            assert conn.has_cache_item(mm_hash)
+
+            # Minimal fake metadata plumbing
+            meta = LMCacheECConnectorMetadata()
+            meta.add_mm_data(MMMeta.make_meta(mm_hash))
+            parent._meta = meta
+
+            # Pin device to "cpu" for the load path: on CPU-only CI runners
+            # vLLM's UnspecifiedPlatform returns an empty device_type, which
+            # would make tensor.to(device="") raise. The test exercises the
+            # round-trip itself, not vLLM's device discovery.
+            encoder_cache2 = {}
+            with patch(
+                "lmcache.integration.vllm.vllm_ec_adapter.torch_device_type",
+                new="cpu",
+            ):
+                conn.start_load_caches(encoder_cache2)
+
+            assert mm_hash in encoder_cache2
+            assert encoder_cache2[mm_hash].shape == x.shape
+            assert encoder_cache2[mm_hash].dtype == x.dtype
+        finally:
+            conn.close()
diff --git a/tests/v1/test_event_notifier.py b/tests/v1/test_event_notifier.py
new file mode 100644
index 0000000..c08ced2
--- /dev/null
+++ b/tests/v1/test_event_notifier.py
@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import os
+import select
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.platform import (
+    HAS_EVENTFD,
+    EventfdNotifier,
+    EventNotifier,
+    PipeNotifier,
+    consume_fd,
+    create_event_notifier,
+)
+from lmcache.v1.platform import event_notifier as _canonical_ev_mod
+
+
+class TestEventNotifierAPI:
+    """Test the public API on the current platform."""
+
+    def test_create_returns_event_notifier(self):
+        """Factory returns an EventNotifier subclass."""
+        n = create_event_notifier()
+        try:
+            assert isinstance(n, EventNotifier)
+        finally:
+            n.close()
+
+    def test_fileno_is_nonnegative(self):
+        """fileno() returns a valid fd."""
+        n = create_event_notifier()
+        try:
+            assert n.fileno() >= 0
+        finally:
+            n.close()
+
+    def test_notify_then_consume(self):
+        """notify() makes the fd readable; consume() drains it."""
+        n = create_event_notifier()
+        try:
+            n.notify()
+            poller = select.poll()
+            poller.register(n.fileno(), select.POLLIN)
+            events = poller.poll(100)
+            assert len(events) > 0
+            n.consume()
+        finally:
+            n.close()
+
+    def test_multiple_notify_single_consume(self):
+        """Multiple notify() calls are coalesced by one consume()."""
+        n = create_event_notifier()
+        try:
+            n.notify()
+            n.notify()
+            n.notify()
+            n.consume()
+            # After consume, fd should not be readable
+            poller = select.poll()
+            poller.register(n.fileno(), select.POLLIN)
+            events = poller.poll(50)
+            assert len(events) == 0
+        finally:
+            n.close()
+
+    def test_consume_without_notify_is_noop(self):
+        """consume() without prior notify() does not block or raise."""
+        n = create_event_notifier()
+        try:
+            n.consume()  # should not block or raise
+        finally:
+            n.close()
+
+    def test_close_is_idempotent(self):
+        """Calling close() twice does not raise."""
+        n = create_event_notifier()
+        n.close()
+        n.close()  # should not raise
+
+    def test_context_manager(self):
+        """EventNotifier works as a context manager."""
+        with create_event_notifier() as n:
+            n.notify()
+            n.consume()
+            assert n.fileno() >= 0
+
+
+class TestPipeNotifier:
+    """Force the pipe-based fallback path."""
+
+    def test_both_fds_closed(self):
+        """close() releases both read and write fds."""
+        n = PipeNotifier()
+        r = n.fileno()
+        # Second fd via notify/consume cycle: after close, both must be gone.
+        n.notify()
+        n.consume()
+        n.close()
+        with pytest.raises(OSError):
+            os.fstat(r)
+
+    def test_notify_when_pipe_full_is_noop(self):
+        """notify() does not raise when pipe buffer is full."""
+        n = PipeNotifier()
+        try:
+            # A POSIX pipe's capacity is at most 1 MiB on current
+            # Linux/macOS kernels and each notify() writes a single
+            # byte, so (1 << 21) iterations comfortably saturate it
+            # while keeping the test fast - notify() itself swallows
+            # BlockingIOError once the buffer is full.
+            for _ in range(1 << 21):
+                n.notify()
+            # Still a no-op once the pipe is saturated.
+            n.notify()
+        finally:
+            n.close()
+
+    def test_pollable(self):
+        """PipeNotifier fd is pollable with select.poll."""
+        n = PipeNotifier()
+        try:
+            n.notify()
+            poller = select.poll()
+            poller.register(n.fileno(), select.POLLIN)
+            events = poller.poll(100)
+            assert len(events) > 0
+        finally:
+            n.close()
+
+    def test_multiple_create_close_cycles(self):
+        """Create and close multiple notifiers without leaking."""
+        for _ in range(20):
+            n = PipeNotifier()
+            n.notify()
+            n.consume()
+            n.close()
+
+
+class TestPipeEOF:
+    """Regression test: pipe EOF must not spin the drain loop.
+
+    ``os.read`` returns ``b''`` (not ``BlockingIOError``) when the
+    write end is closed.  Both ``PipeNotifier.consume`` and the
+    module-level ``consume_fd`` helper share this drain loop, so
+    they must treat an empty read as "drained" -- otherwise a dead
+    pipe would hang a background event loop.
+    """
+
+    def test_consume_fd_returns_on_pipe_eof(self, monkeypatch):
+        """consume_fd() returns when the pipe write end is closed."""
+        monkeypatch.setattr(_canonical_ev_mod, "HAS_EVENTFD", False)
+        r, w = os.pipe()
+        os.set_blocking(r, False)
+        try:
+            os.close(w)  # write end closed -> read end at EOF
+            consume_fd(r)  # must return promptly, not hang
+        finally:
+            os.close(r)
+
+
+class TestConsumeFd:
+    """Test the consume_fd utility function."""
+
+    def test_consume_fd_after_notify(self):
+        """consume_fd() drains a notifier's fd."""
+        n = create_event_notifier()
+        try:
+            n.notify()
+            consume_fd(n.fileno())
+            # After consume, fd should not be readable
+            poller = select.poll()
+            poller.register(n.fileno(), select.POLLIN)
+            events = poller.poll(50)
+            assert len(events) == 0
+        finally:
+            n.close()
+
+    def test_consume_fd_without_signal(self):
+        """consume_fd() on unsignaled fd does not block."""
+        n = create_event_notifier()
+        try:
+            consume_fd(n.fileno())  # should not block
+        finally:
+            n.close()
+
+
+class TestBackendSelection:
+    """Validate which concrete backend the factory picks."""
+
+    def test_factory_matches_platform_capability(self):
+        """create_event_notifier() picks the backend for this OS."""
+        n = create_event_notifier()
+        try:
+            if HAS_EVENTFD:
+                assert isinstance(n, EventfdNotifier)
+            else:
+                assert isinstance(n, PipeNotifier)
+        finally:
+            n.close()
+
+
+class TestForcedPipeFallback:
+    """Exercise the pipe fallback even when eventfd is available.
+
+    On Linux CI ``create_event_notifier()`` would normally return
+    an ``EventfdNotifier``; monkeypatch ``HAS_EVENTFD`` to force
+    the pipe path so the non-Linux code is covered on every OS.
+    """
+
+    @pytest.fixture
+    def force_pipe(self, monkeypatch):
+        monkeypatch.setattr(_canonical_ev_mod, "HAS_EVENTFD", False)
+        yield
+
+    def test_factory_returns_pipe_notifier(self, force_pipe):
+        n = create_event_notifier()
+        try:
+            assert isinstance(n, PipeNotifier)
+        finally:
+            n.close()
+
+    def test_notify_consume_roundtrip(self, force_pipe):
+        n = create_event_notifier()
+        try:
+            n.notify()
+            poller = select.poll()
+            poller.register(n.fileno(), select.POLLIN)
+            assert poller.poll(100)
+            n.consume()
+            assert not poller.poll(50)
+        finally:
+            n.close()
+
+    def test_consume_fd_uses_pipe_path(self, force_pipe):
+        n = create_event_notifier()
+        try:
+            n.notify()
+            consume_fd(n.fileno())
+            poller = select.poll()
+            poller.register(n.fileno(), select.POLLIN)
+            assert not poller.poll(50)
+        finally:
+            n.close()
diff --git a/tests/v1/test_freeze_mode_integration.py b/tests/v1/test_freeze_mode_integration.py
new file mode 100644
index 0000000..96c8353
--- /dev/null
+++ b/tests/v1/test_freeze_mode_integration.py
@@ -0,0 +1,332 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import random
+import time
+
+# Third Party
+import requests
+import torch
+
+# First Party
+from lmcache.utils import mock_up_broadcast_fn, mock_up_broadcast_object_fn
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.mock_gpu_connector import MockGPUConnector
+from lmcache.v1.internal_api_server.api_server import InternalAPIServer
+from lmcache.v1.metadata import LMCacheMetadata
+from tests.v1.utils import (
+    MockAdapter,
+    dumb_metadata,
+    generate_kv_cache_paged_list_tensors,
+    generate_tokens,
+    get_available_port,
+    recover_engine_states,
+)
+
+
+def test_freeze_with_real_cache_engine(autorelease_v1):
+    """
+    Integration test for freeze mode with real cache engine.
+
+    This test verifies:
+    1. Normal mode stores KV cache correctly to local_cpu backend
+    2. Enable freeze mode via HTTP API
+    3. Store operations are skipped in freeze mode (no new allocations)
+    4. Only local_cpu backend is accessible in freeze mode
+    5. Disable freeze mode and verify store works again
+    """
+    # Setup
+    device = "cpu"
+    instance_id = f"test_freeze_real_{random.getrandbits(64)}"
+    chunk_size = 256
+    num_tokens = 512
+    num_blocks = 100
+    block_size = 16
+    dtype = torch.bfloat16
+    kv_shape = (32, 2, chunk_size, 8, 128)
+
+    # Create config with CPU backend for easy verification
+    cfg = LMCacheEngineConfig.from_defaults(
+        chunk_size=chunk_size,
+        local_cpu=True,
+    )
+
+    # Enable Internal API Server
+    cfg.internal_api_server_enabled = True
+    # Get an available port for the API server
+    # worker_id will be 0, so port_offset = 1 + 0 = 1
+    # actual_port = port_start + port_offset, so port_start = actual_port - 1
+    actual_port = get_available_port()
+    cfg.internal_api_server_port_start = actual_port - 1
+    cfg.internal_api_server_socket_path_prefix = None
+
+    # Create mock GPU connector that works on CPU
+    connector = MockGPUConnector(kv_shape=kv_shape)
+    # Use explicit metadata with worker_id=0 to control port offset
+    metadata = LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+    )
+
+    # Create engine
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            instance_id,
+            cfg,
+            metadata,
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    api_server = None
+    try:
+        # Create adapter and start API server
+        adapter = MockAdapter(engine, cfg)
+        api_server = InternalAPIServer(adapter)
+        api_server.start()
+
+        # Wait for server to start and become responsive
+        max_retries = 40
+        retry_delay = 0.5
+        server_ready = False
+        base_url = "http://localhost:%d" % actual_port
+
+        # Wait for server to be responsive
+        for i in range(max_retries):
+            try:
+                response = requests.get("%s/freeze/status" % base_url, timeout=1)
+                if response.status_code in [200, 503]:
+                    server_ready = True
+                    break
+            except requests.exceptions.RequestException:
+                pass
+            time.sleep(retry_delay)
+
+        assert server_ready, "Server failed to respond after %d retries" % max_retries
+
+        # ============================================
+        # Step 1: Verify initial freeze mode is OFF
+        # ============================================
+        response = requests.get("%s/freeze/status" % base_url)
+        assert response.status_code == 200
+        assert response.json()["freeze"] is False
+
+        # ============================================
+        # Step 2: Normal mode - Store should work
+        # ============================================
+        tokens_1 = generate_tokens(num_tokens, device)
+        kv_cache = generate_kv_cache_paged_list_tensors(
+            num_blocks, device, block_size, dtype
+        )
+        slot_mapping_1 = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping_1 = torch.tensor(slot_mapping_1, device=device)
+
+        # Store data in normal mode
+        engine.store(
+            tokens=tokens_1,
+            kvcaches=kv_cache,
+            slot_mapping=slot_mapping_1,
+        )
+        recover_engine_states(engine)
+
+        # Wait for async store to complete
+        timeout = 5
+        start_time = time.time()
+        while engine.lookup(tokens_1) < num_tokens:
+            if time.time() - start_time > timeout:
+                raise TimeoutError("Store operation timed out in normal mode")
+            time.sleep(0.1)
+
+        # Verify data was stored
+        stored_length = engine.lookup(tokens_1)
+        assert stored_length == num_tokens, "Expected %d tokens stored, got %d" % (
+            num_tokens,
+            stored_length,
+        )
+
+        # ============================================
+        # Step 3: Enable freeze mode via HTTP API
+        # ============================================
+        response = requests.put("%s/freeze/enable" % base_url)
+        assert response.status_code == 200
+        result = response.json()
+        assert result["freeze"] is True
+        assert result["status"] == "success"
+
+        # Verify status
+        response = requests.get("%s/freeze/status" % base_url)
+        assert response.status_code == 200
+        assert response.json()["freeze"] is True
+
+        # ============================================
+        # Step 4: Read-only mode - Store should be skipped
+        # ============================================
+        tokens_2 = generate_tokens(num_tokens, device)
+        slot_mapping_2 = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping_2 = torch.tensor(slot_mapping_2, device=device)
+
+        # Try to store new data in freeze mode
+        engine.store(
+            tokens=tokens_2,
+            kvcaches=kv_cache,
+            slot_mapping=slot_mapping_2,
+        )
+        recover_engine_states(engine)
+
+        # Wait a bit to ensure store would have completed if not skipped
+        time.sleep(1)
+
+        # Verify data was NOT stored (freeze mode should skip)
+        stored_length_2 = engine.lookup(tokens_2)
+        assert stored_length_2 == 0, (
+            "Expected 0 tokens stored in freeze mode, got %d" % stored_length_2
+        )
+
+        # Original data should still be there
+        assert engine.lookup(tokens_1) == num_tokens
+
+        # ============================================
+        # Step 5: Disable freeze mode via HTTP API
+        # ============================================
+        response = requests.put("%s/freeze/disable" % base_url)
+        assert response.status_code == 200
+        result = response.json()
+        assert result["freeze"] is False
+        assert result["status"] == "success"
+
+        # ============================================
+        # Step 6: Store should work again after disabling
+        # ============================================
+        tokens_3 = generate_tokens(num_tokens, device)
+        slot_mapping_3 = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping_3 = torch.tensor(slot_mapping_3, device=device)
+
+        engine.store(
+            tokens=tokens_3,
+            kvcaches=kv_cache,
+            slot_mapping=slot_mapping_3,
+        )
+        recover_engine_states(engine)
+
+        # Wait for async store to complete
+        start_time = time.time()
+        while engine.lookup(tokens_3) < num_tokens:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(
+                    "Store operation timed out after disabling freeze mode"
+                )
+            time.sleep(0.1)
+
+        # Verify data was stored
+        stored_length_3 = engine.lookup(tokens_3)
+        assert stored_length_3 == num_tokens, (
+            "Expected %d tokens stored after disable, got %d"
+            % (num_tokens, stored_length_3)
+        )
+    finally:
+        # Cleanup
+        if api_server:
+            api_server.stop()
+            # Give it some time to shut down
+            time.sleep(0.5)
+        LMCacheEngineBuilder.destroy(instance_id)
+
+
+def test_freeze_direct_api(autorelease_v1):
+    """
+    Test freeze mode via direct engine API (without HTTP server).
+
+    This test verifies:
+    1. Freeze mode can be enabled/disabled via direct API
+    2. Store operations are skipped in freeze mode
+    3. No new memory allocations occur in freeze mode
+    4. Only local_cpu backend is used for retrieval in freeze mode
+    """
+    # Setup
+    device = "cpu"
+    instance_id = "test_freeze_direct"
+    chunk_size = 256
+    num_tokens = 512
+    num_blocks = 100
+    block_size = 16
+    dtype = torch.bfloat16
+    kv_shape = (32, 2, chunk_size, 8, 128)
+
+    cfg = LMCacheEngineConfig.from_defaults(
+        chunk_size=chunk_size,
+        local_cpu=True,
+    )
+
+    connector = MockGPUConnector(kv_shape=kv_shape)
+    metadata = dumb_metadata(kv_shape)
+
+    engine = autorelease_v1(
+        LMCacheEngineBuilder.get_or_create(
+            instance_id,
+            cfg,
+            metadata,
+            connector,
+            mock_up_broadcast_fn,
+            mock_up_broadcast_object_fn,
+        )
+    )
+
+    try:
+        # Verify initial state
+        assert engine.is_frozen() is False
+
+        # Test set/get methods
+        engine.freeze(True)
+        assert engine.is_frozen() is True
+
+        engine.freeze(False)
+        assert engine.is_frozen() is False
+
+        # Test store behavior with freeze mode
+        tokens = generate_tokens(num_tokens, device)
+        kv_cache = generate_kv_cache_paged_list_tensors(
+            num_blocks, device, block_size, dtype
+        )
+        slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        slot_mapping = torch.tensor(slot_mapping, device=device)
+
+        # Store in normal mode
+        engine.store(tokens=tokens, kvcaches=kv_cache, slot_mapping=slot_mapping)
+        recover_engine_states(engine)
+
+        timeout = 5
+        start_time = time.time()
+        while engine.lookup(tokens) < num_tokens:
+            if time.time() - start_time > timeout:
+                raise TimeoutError("Store timed out")
+            time.sleep(0.1)
+
+        assert engine.lookup(tokens) == num_tokens
+
+        # Enable freeze mode
+        engine.freeze(True)
+
+        # Try to store new data
+        new_tokens = generate_tokens(num_tokens, device)
+        new_slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+        new_slot_mapping = torch.tensor(new_slot_mapping, device=device)
+
+        engine.store(
+            tokens=new_tokens, kvcaches=kv_cache, slot_mapping=new_slot_mapping
+        )
+        recover_engine_states(engine)
+
+        time.sleep(1)
+
+        # Should not be stored
+        assert engine.lookup(new_tokens) == 0
+
+    finally:
+        LMCacheEngineBuilder.destroy(instance_id)
diff --git a/tests/v1/test_gds.py b/tests/v1/test_gds.py
new file mode 100644
index 0000000..3f32093
--- /dev/null
+++ b/tests/v1/test_gds.py
@@ -0,0 +1,132 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+import asyncio
+import os
+import shutil
+import tempfile
+import threading
+
+# Third Party
+import pytest
+import safetensors
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.cache_engine import LMCacheEngineBuilder
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.cu_file_memory_allocator import CuFileMemoryAllocator
+from lmcache.v1.memory_allocators.hip_file_memory_allocator import (
+    HipFileMemoryAllocator,
+)
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.storage_backend import CreateStorageBackends
+from lmcache.v1.storage_backend.gds_backend import pack_metadata, unpack_metadata
+
+
+def test_gds_backend_metadata():
+    # This is a sanity check that packing and unpacking works. We can add
+    # more tensor types to be sure.
+    for [tensor, expected_nbytes] in [(torch.randn(3, 10), 120)]:
+        r = pack_metadata(tensor, fmt=MemoryFormat.KV_2LTD, version="test")
+        size, dtype, nbytes, fmt, meta = unpack_metadata(r)
+        assert size == tensor.size()
+        assert dtype == tensor.dtype
+        assert expected_nbytes == nbytes
+        assert fmt == MemoryFormat.KV_2LTD
+        assert meta["version"] == "test"
+
+        # Make sure that safetensors can load this
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_file_path = os.path.join(temp_dir, "test.safetensors")
+            with open(temp_file_path, "wb") as f:
+                f.write(r)
+                f.write(b" " * nbytes)
+
+            with safetensors.safe_open(temp_file_path, framework="pt") as f:
+                tensor = f.get_tensor("kvcache")
+                assert size == tensor.size()
+                assert dtype == tensor.dtype
+                assert expected_nbytes == nbytes
+
+
+@pytest.mark.skip(reason="We need to add this test back after implementing prefetch")
+def test_gds_backend_sanity():
+    BASE_DIR = Path(__file__).parent
+    GDS_DIR = "/tmp/gds/test-cache"
+    TEST_KEY = CacheEngineKey(
+        model_name="meta-llama/Llama-3.1-70B-Instruct",
+        world_size=8,
+        worker_id=0,
+        chunk_hash="e3229141e680fb413d2c5d3ebb416c4ad300d381e309fc9e417757b91406c157",
+        dtype=torch.uint8,
+    )
+    BACKEND_NAME = "GdsBackend"
+
+    try:
+        os.makedirs(GDS_DIR, exist_ok=True)
+        config_gds = LMCacheEngineConfig.from_file(BASE_DIR / "data/gds.yaml")
+        assert config_gds.gds_buffer_size == 128
+
+        thread_loop = asyncio.new_event_loop()
+        thread = threading.Thread(target=thread_loop.run_forever)
+        thread.start()
+
+        backends = CreateStorageBackends(
+            config_gds,
+            None,
+            thread_loop,
+            LMCacheEngineBuilder._Create_memory_allocator(config_gds, None),
+        )
+        assert len(backends) == 2
+        assert BACKEND_NAME in backends
+
+        gds_backend = backends[BACKEND_NAME]
+        assert gds_backend is not None
+        assert gds_backend.memory_allocator is not None
+        assert isinstance(
+            gds_backend.memory_allocator,
+            (CuFileMemoryAllocator, HipFileMemoryAllocator),
+        )
+
+        assert not gds_backend.contains(TEST_KEY, False)
+        assert not gds_backend.exists_in_put_tasks(TEST_KEY)
+
+        memory_obj = gds_backend.memory_allocator.allocate(
+            [2048, 2048], dtype=torch.uint8
+        )
+        future = gds_backend.submit_put_task(TEST_KEY, memory_obj)
+        assert future is not None
+        assert gds_backend.exists_in_put_tasks(TEST_KEY)
+        assert not gds_backend.contains(TEST_KEY, False)
+        future.result()
+        assert gds_backend.contains(TEST_KEY, False)
+        assert not gds_backend.exists_in_put_tasks(TEST_KEY)
+
+        returned_memory_obj = gds_backend.get_blocking(TEST_KEY)
+        assert returned_memory_obj is not None
+        assert returned_memory_obj.get_size() == memory_obj.get_size()
+        assert returned_memory_obj.get_shape() == memory_obj.get_shape()
+        assert returned_memory_obj.get_dtype() == memory_obj.get_dtype()
+
+        future = gds_backend.get_non_blocking(TEST_KEY)
+        assert future is not None
+        returned_memory_obj = future.result()
+        assert returned_memory_obj is not None
+        assert returned_memory_obj.get_size() == memory_obj.get_size()
+        assert returned_memory_obj.get_shape() == memory_obj.get_shape()
+        assert returned_memory_obj.get_dtype() == memory_obj.get_dtype()
+    finally:
+        if thread_loop.is_running():
+            thread_loop.call_soon_threadsafe(thread_loop.stop)
+        if thread.is_alive():
+            thread.join()
+        # We rmtree AFTER we ensure that the thread loop is done.
+        # This way we don't hit any race conditions in rmtree()
+        # where temp files are renamed while we try to unlink them.
+        # We also take care of any other errors with ignore_errors=True
+        # so if we want to run tests in parallel in the future they
+        # don't make each other fail.
+        if os.path.exists(GDS_DIR):
+            shutil.rmtree(GDS_DIR)
diff --git a/tests/v1/test_gpu_connector.py b/tests/v1/test_gpu_connector.py
new file mode 100644
index 0000000..b5b7f58
--- /dev/null
+++ b/tests/v1/test_gpu_connector.py
@@ -0,0 +1,963 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import nullcontext
+from unittest.mock import patch
+import random
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.gpu_connectors import (
+    SGLangGPUConnector,
+    VLLMBufferLayerwiseGPUConnector,
+    VLLMPagedMemGPUConnectorV2,
+    VLLMPagedMemGPUConnectorV3,
+    VLLMPagedMemLayerwiseGPUConnector,
+)
+from lmcache.v1.gpu_connector.utils import get_dtype
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.metadata import LMCacheMetadata
+
+if torch.cuda.is_available():
+    try:
+        # First Party
+        import lmcache.c_ops as lmc_ops
+    except ImportError:
+        lmc_ops = None
+else:
+    lmc_ops = None
+
+# Mock c_ops when not available
+if lmc_ops is None:
+
+    class MockEngineKVFormat:
+        NL_X_TWO_NB_BS_NH_HS = 0
+        NL_X_NB_TWO_BS_NH_HS = 1
+        NL_X_NB_BS_HS = 2
+
+    class MockCOps:
+        EngineKVFormat = MockEngineKVFormat
+        GPUKVFormat = MockEngineKVFormat
+
+    lmc_ops = MockCOps()
+
+# Local
+from .utils import (
+    check_paged_kv_cache_equal,
+    check_paged_kv_cache_equal_with_mla,
+    check_sglang_paged_kv_cache_equal,
+    generate_kv_cache_paged_list_tensors,
+    generate_sglang_kv_cache_paged_list_tensors,
+    recover_gpu_connector_states,
+)
+
+
+@pytest.fixture(autouse=True, scope="module")
+def patch_pin_allocator():
+    def fake_pin_init(self, size: int, use_paging: bool = False, **kwargs):
+        """
+        :param int size: The size of the pinned memory in bytes.
+        """
+
+        # self.buffer = torch.empty(size, dtype=torch.uint8)
+        # ptr = self.buffer.data_ptr()
+        # err = torch.cuda.cudart().cudaHostRegister(ptr, size, 0)
+        # assert err == 0, (
+        #     f"cudaHostRegister failed: {torch.cuda.cudart().cudaGetErrorString(err)}"
+        # )
+        self._unregistered = False
+        self.buffer = torch.empty(size, dtype=torch.uint8, pin_memory=True)
+
+        if use_paging:
+            assert "shapes" in kwargs, (
+                "shapes must be specified for paged memory allocator"
+            )
+            assert "dtypes" in kwargs, (
+                "dtypes must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.allocator = PagedTensorMemoryAllocator(
+                tensor=self.buffer,
+                shapes=kwargs["shapes"],
+                dtypes=kwargs["dtypes"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.allocator = TensorMemoryAllocator(self.buffer)
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+    def fake_pin_close(self):
+        if not self._unregistered:
+            torch.cuda.synchronize()
+            # torch.cuda.cudart().cudaHostUnregister(self.buffer.data_ptr())
+            self._unregistered = True
+
+    with (
+        patch(
+            "lmcache.v1.memory_allocators.pin_memory_allocator.PinMemoryAllocator.__init__",
+            fake_pin_init,
+        ),
+        patch(
+            "lmcache.v1.memory_allocators.pin_memory_allocator.PinMemoryAllocator.close",
+            fake_pin_close,
+        ),
+    ):
+        yield
+
+
+@pytest.mark.parametrize("use_gpu", [True, False])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    ],  # vllm MLA
+)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_vllm_paged_connector_v2_with_gpu_and_mla(use_gpu, engine_kv_format):
+    use_mla = engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 1 if use_mla else 8
+    head_size = 128
+    device = "cuda"
+    hidden_dim = num_heads * head_size
+
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    dtype = get_dtype(gpu_kv_src, engine_kv_format)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        if use_mla:
+            check_paged_kv_cache_equal_with_mla(
+                gpu_kv_src, gpu_kv_dst, slot_mapping, head_size
+            )
+        else:
+            check_paged_kv_cache_equal(
+                gpu_kv_src,
+                gpu_kv_dst,
+                slot_mapping,
+                num_heads,
+                head_size,
+                engine_kv_format,
+            )
+
+    connector = VLLMPagedMemGPUConnectorV2(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+    connector2 = VLLMPagedMemGPUConnectorV2(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+    assert connector.use_mla == use_mla
+    assert connector2.use_mla == use_mla
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape = connector.get_shape(end - start)
+        memory_obj = allocator.allocate(shape, dtype)
+        connector.from_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=gpu_kv_src,
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        recover_gpu_connector_states(connector)
+        if use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+        connector2.to_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=gpu_kv_dst,
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        allocator.free(memory_obj)
+        assert allocator.memcheck()
+
+    if use_mla:
+        check_paged_kv_cache_equal_with_mla(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, head_size
+        )
+    else:
+        check_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size, engine_kv_format
+        )
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True, False])
+@pytest.mark.parametrize("num_groups", [1, 2, 3])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    ],  # vllm MLA
+)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV3",
+)
+def test_vllm_paged_connector_v3_with_gpu_and_mla(
+    use_gpu, num_groups, engine_kv_format
+):
+    use_mla = engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    head_sizes = [64, 66, 66]
+    dtypes = [torch.uint8, torch.bfloat16, torch.uint8]
+    num_blocks = 100
+    block_size = 16
+    num_heads = 1 if use_mla else 8
+    device = "cuda"
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    # generate kv cache tensors
+    src_kv_groups: list[list] = []
+    dst_kv_groups: list[list] = []
+    src_kv_caches: dict[str, torch.Tensor] = {}
+    dst_kv_caches: dict[str, torch.Tensor] = {}
+    for i in range(num_groups):
+        for groups, kv_caches in [
+            (src_kv_groups, src_kv_caches),
+            (dst_kv_groups, dst_kv_caches),
+        ]:
+            kv_group = generate_kv_cache_paged_list_tensors(
+                num_blocks=num_blocks,
+                device=device,
+                block_size=block_size,
+                dtype=dtypes[i],
+                num_layers=8,
+                head_size=head_sizes[i],
+                engine_kv_format=engine_kv_format,
+            )
+            groups.append(kv_group)
+            for j, layer_tensor in enumerate(kv_group):
+                kv_caches[f"{i}-{j}"] = layer_tensor
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the kv group is not the same before copying
+    with pytest.raises(AssertionError):
+        for i in range(num_groups):
+            if use_mla:
+                check_paged_kv_cache_equal_with_mla(
+                    src_kv_groups[i], dst_kv_groups[i], slot_mapping, head_sizes[i]
+                )
+            else:
+                check_paged_kv_cache_equal(
+                    src_kv_groups[i],
+                    dst_kv_groups[i],
+                    slot_mapping,
+                    num_heads,
+                    head_sizes[i],
+                    engine_kv_format,
+                )
+
+    # create metadata and init kv layer groups
+    metadata = _create_metadata(use_mla, src_kv_caches, engine_kv_format)
+    metadata2 = _create_metadata(use_mla, dst_kv_caches, engine_kv_format)
+
+    # connector will copy with src_kv_groups
+    connector = VLLMPagedMemGPUConnectorV3(
+        metadata=metadata,
+        use_gpu=use_gpu,
+        device=slot_mapping.device,
+    )
+    # connector2 will copy with dst_kv_groups
+    connector2 = VLLMPagedMemGPUConnectorV3(
+        metadata=metadata2,
+        use_gpu=use_gpu,
+        device=slot_mapping.device,
+    )
+    assert connector.use_mla == use_mla
+    assert connector2.use_mla == use_mla
+
+    # copy from src_kv_groups to memory_obj,
+    # and then copy from memory_obj to dst_kv_groups
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        memory_obj = allocator.allocate(
+            metadata.get_shapes(end - start), metadata.get_dtypes()
+        )
+        connector.from_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=list(src_kv_caches.values()),
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        if use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+        connector2.to_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=list(dst_kv_caches.values()),
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        allocator.free(memory_obj)
+        assert allocator.memcheck()
+
+    # Check the kv group is same after copying
+    for i in range(num_groups):
+        if use_mla:
+            check_paged_kv_cache_equal_with_mla(
+                src_kv_groups[i], dst_kv_groups[i], slot_mapping, head_sizes[i]
+            )
+        else:
+            check_paged_kv_cache_equal(
+                src_kv_groups[i],
+                dst_kv_groups[i],
+                slot_mapping,
+                num_heads,
+                head_sizes[i],
+                engine_kv_format,
+            )
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+    ],
+)
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemLayerwiseGPUConnector",
+)
+def test_layerwise_vllm_paged_connector_with_gpu(use_gpu, engine_kv_format):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "cuda"
+    hidden_dim = num_heads * head_size
+
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    dtype = get_dtype(gpu_kv_src, engine_kv_format)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size, engine_kv_format
+        )
+
+    connector = VLLMPagedMemLayerwiseGPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+    )
+
+    # from gpu to cpu
+    starts = []
+    ends = []
+    memory_objs = []
+
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_T2D
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts.append(start)
+        ends.append(end)
+        memory_objs.append(memory_objs_multi_layer)
+
+    memory_objs = [list(row) for row in zip(*memory_objs, strict=False)]
+
+    mem_obj_generator = connector.batched_from_gpu(
+        memory_objs,
+        starts,
+        ends,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping,
+        sync=True,
+    )
+
+    for layer_id in range(num_layers + 1):
+        next(mem_obj_generator)
+
+    # from cpu to gpu
+    mem_obj_consumer = connector.batched_to_gpu(
+        starts,
+        ends,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping,
+        sync=True,
+    )
+    next(mem_obj_consumer)
+    for layer_id in range(num_layers):
+        mem_obj_consumer.send(memory_objs[layer_id])
+    next(mem_obj_consumer)
+
+    # free all mem objs
+    for mem_obj_multi_layer in memory_objs:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    assert allocator.memcheck()
+
+    assert connector.gpu_buffer_allocator.memcheck()
+
+    check_paged_kv_cache_equal(
+        gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size, engine_kv_format
+    )
+
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemLayerwiseGPUConnector",
+)
+def test_batched_layerwise_vllm_paged_connector_with_gpu(use_gpu):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "cuda"
+    hidden_dim = num_heads * head_size
+
+    num_tokens_1 = 800
+    num_tokens_2 = 500
+    num_tokens_total = num_tokens_1 + num_tokens_2
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    dtype = gpu_kv_src[0][0].dtype
+
+    slot_mapping_total = random.sample(
+        range(0, num_blocks * block_size), num_tokens_total
+    )
+    slot_mapping_total = torch.tensor(
+        slot_mapping_total, device=device, dtype=torch.int64
+    )
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(gpu_kv_src, gpu_kv_dst, slot_mapping_total)
+
+    connector = VLLMPagedMemLayerwiseGPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+    )
+
+    # from gpu to cpu
+    starts_1 = []
+    ends_1 = []
+    memory_objs_1 = []
+
+    for start in range(0, num_tokens_1, chunk_size):
+        end = min(start + chunk_size, num_tokens_1)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_T2D
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts_1.append(start)
+        ends_1.append(end)
+        memory_objs_1.append(memory_objs_multi_layer)
+
+    memory_objs_1 = [list(row) for row in zip(*memory_objs_1, strict=False)]
+
+    starts_2 = []
+    ends_2 = []
+    memory_objs_2 = []
+    for start in range(num_tokens_1, num_tokens_total, chunk_size):
+        end = min(start + chunk_size, num_tokens_total)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_T2D
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts_2.append(start)
+        ends_2.append(end)
+        memory_objs_2.append(memory_objs_multi_layer)
+
+    memory_objs_2 = [list(row) for row in zip(*memory_objs_2, strict=False)]
+
+    mem_obj_generator_1 = connector.batched_from_gpu(
+        memory_objs_1,
+        starts_1,
+        ends_1,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping_total,
+        sync=True,
+    )
+
+    mem_obj_generator_1 = connector.batched_from_gpu(
+        memory_objs_1,
+        starts_1,
+        ends_1,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping_total,
+        sync=True,
+    )
+
+    mem_obj_generator_2 = connector.batched_from_gpu(
+        memory_objs_2,
+        starts_2,
+        ends_2,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping_total,
+        sync=False,
+    )
+
+    for layer_id in range(num_layers + 1):
+        next(mem_obj_generator_1)
+        next(mem_obj_generator_2)
+
+    # from cpu to gpu
+    mem_obj_consumer_1 = connector.batched_to_gpu(
+        starts_1,
+        ends_1,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping_total,
+        sync=False,
+    )
+    mem_obj_consumer_2 = connector.batched_to_gpu(
+        starts_2,
+        ends_2,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping_total,
+        sync=True,
+    )
+
+    next(mem_obj_consumer_1)
+    next(mem_obj_consumer_2)
+    for layer_id in range(num_layers):
+        mem_obj_consumer_1.send(memory_objs_1[layer_id])
+        mem_obj_consumer_2.send(memory_objs_2[layer_id])
+    next(mem_obj_consumer_1)
+    next(mem_obj_consumer_2)
+
+    # free all mem objs
+    for mem_obj_multi_layer in memory_objs_1:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    for mem_obj_multi_layer in memory_objs_2:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    assert allocator.memcheck()
+
+    assert connector.gpu_buffer_allocator.memcheck()
+
+    check_paged_kv_cache_equal(
+        gpu_kv_src,
+        gpu_kv_dst,
+        slot_mapping_total,
+        num_heads,
+        head_size,
+    )
+
+    allocator.close()
+
+
+@pytest.mark.skip(reason="This test is skipped due to vllm dependency")
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMBufferLayerwiseGPUConnector",
+)
+def test_layerwise_vllm_buffer_connector_with_gpu(use_gpu):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "cuda"
+    hidden_dim = num_heads * head_size
+
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    dtype = gpu_kv_src[0][0].dtype
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size
+        )
+
+    connector = VLLMBufferLayerwiseGPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        dtype=dtype,
+        device=device,
+    )
+
+    # from gpu to cpu
+    starts = []
+    ends = []
+    memory_objs = []
+
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_2TD
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts.append(start)
+        ends.append(end)
+        memory_objs.append(memory_objs_multi_layer)
+
+    memory_objs = [list(row) for row in zip(*memory_objs, strict=False)]
+
+    mem_obj_generator = connector.batched_from_gpu(
+        memory_objs,
+        starts,
+        ends,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping,
+    )
+
+    for layer_id in range(num_layers + 1):
+        next(mem_obj_generator)
+
+    # from cpu to gpu
+    mem_obj_consumer = connector.batched_to_gpu(
+        starts,
+        ends,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping,
+    )
+    next(mem_obj_consumer)
+    for layer_id in range(num_layers):
+        mem_obj_consumer.send(memory_objs[layer_id])
+    next(mem_obj_consumer)
+
+    # free all mem objs
+    for mem_obj_multi_layer in memory_objs:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    assert allocator.memcheck()
+
+    assert connector.gpu_buffer_allocator.memcheck()
+
+    check_paged_kv_cache_equal(
+        gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size
+    )
+
+    allocator.close()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to VLLMPagedMemGPUConnectorV2",
+)
+def test_vllm_paged_connector_v2_to_gpu_bench(benchmark):
+    """
+    VLLMPagedMemGPUConnectorV2.to_gpu() micro-benchmark.
+
+    This test is to measure the performance of
+    VLLMPagedMemGPUConnectorV2.to_gpu() when both KV caches and
+    memobject are on GPU.
+
+    """
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "cuda"
+    hidden_dim = num_heads * head_size
+
+    chunk_size = 256
+
+    allocator = GPUMemoryAllocator(1024 * 1024 * 1024, device)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), chunk_size)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    connector = VLLMPagedMemGPUConnectorV2(hidden_dim, num_layers)
+    shape = connector.get_shape(chunk_size)
+    memory_obj = allocator.allocate(shape, gpu_kv_src[0][0].dtype)
+    connector.from_gpu(
+        memory_obj,
+        0,
+        chunk_size,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping,
+        offset=0,
+    )
+    recover_gpu_connector_states(connector)
+    assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+    benchmark.pedantic(
+        connector.to_gpu,
+        args=(memory_obj, 0, chunk_size),
+        kwargs={
+            "kvcaches": gpu_kv_dst,
+            "slot_mapping": slot_mapping,
+            "offset": 0,
+        },
+        rounds=100,
+        iterations=1000,
+        warmup_rounds=10,
+    )
+    allocator.free(memory_obj)
+    assert allocator.memcheck()
+
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True, False])
+@pytest.mark.parametrize("use_mla", [True, False])
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non-CUDA implementation to SGLangGPUConnector",
+)
+def test_sglang_connector_with_gpu_and_mla(use_gpu, use_mla):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 1 if use_mla else 8
+    head_size = 128
+    device = "cuda"
+    dtype = torch.bfloat16
+    hidden_dim = num_heads * head_size
+
+    num_tokens = num_blocks * block_size // 2
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=use_mla,
+        device=device,
+        dtype=dtype,
+    )
+    gpu_kv_dst = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=use_mla,
+        device=device,
+        dtype=dtype,
+    )
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        if use_mla:
+            check_paged_kv_cache_equal_with_mla(
+                gpu_kv_src, gpu_kv_dst, slot_mapping, head_size
+            )
+        else:
+            check_sglang_paged_kv_cache_equal(
+                gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size
+            )
+
+    connector = SGLangGPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+    connector2 = SGLangGPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+    assert connector.use_mla == use_mla
+    assert connector2.use_mla == use_mla
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape = connector.get_shape(end - start)
+        memory_obj = allocator.allocate(shape, gpu_kv_src[0][0].dtype)
+        connector.from_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=gpu_kv_src,
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        if use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+        connector2.to_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=gpu_kv_dst,
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        allocator.free(memory_obj)
+        assert allocator.memcheck()
+
+    if use_mla:
+        check_paged_kv_cache_equal_with_mla(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, head_size
+        )
+    else:
+        check_sglang_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size
+        )
+
+    allocator.close()
+
+
+def _create_metadata(use_mla, kv_caches, engine_kv_format):
+    # First Party
+    from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+
+    num_heads = 1 if use_mla else 8
+    metadata = LMCacheMetadata(
+        model_name="test",
+        world_size=8,
+        local_world_size=8,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(32, 2, 256, num_heads, 128),
+        use_mla=use_mla,
+    )
+    kv_list = list(kv_caches.values())
+    metadata.kv_layer_groups_manager = KVLayerGroupsManager(
+        kv_list,
+        engine_kv_formats=[engine_kv_format] * len(kv_list),
+    )
+    return metadata
diff --git a/tests/v1/test_health_monitor.py b/tests/v1/test_health_monitor.py
new file mode 100644
index 0000000..a563a8b
--- /dev/null
+++ b/tests/v1/test_health_monitor.py
@@ -0,0 +1,361 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the health_monitor module."""
+
+# Standard
+from typing import List
+from unittest.mock import MagicMock
+import asyncio
+import threading
+import time
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.exceptions import IrrecoverableException
+from lmcache.v1.health_monitor.base import HealthCheck, HealthMonitor
+from lmcache.v1.health_monitor.checks.remote_backend_check import (
+    RemoteBackendHealthCheck,
+)
+
+# ============================================================================
+# Mock Classes
+# ============================================================================
+
+
+class SimpleHealthCheck(HealthCheck):
+    """Configurable health check for testing."""
+
+    def __init__(
+        self, name: str = "SimpleCheck", healthy: bool = True, skip: bool = False
+    ):
+        self._name, self._healthy, self._skip = name, healthy, skip
+        self.check_count = 0
+
+    def name(self) -> str:
+        return self._name
+
+    def check(self) -> bool:
+        self.check_count += 1
+        return self._healthy
+
+    def should_skip(self) -> bool:
+        return self._skip
+
+    def set_healthy(self, healthy: bool) -> None:
+        self._healthy = healthy
+
+    @classmethod
+    def create(cls, manager) -> List[HealthCheck]:
+        return [cls()]
+
+
+class ExceptionHealthCheck(HealthCheck):
+    def name(self) -> str:
+        return "ExceptionHealthCheck"
+
+    def check(self) -> bool:
+        raise RuntimeError("Simulated failure")
+
+    @classmethod
+    def create(cls, manager) -> List[HealthCheck]:
+        return [cls()]
+
+
+class IrrecoverableHealthCheck(HealthCheck):
+    """Health check that raises IrrecoverableException."""
+
+    def name(self) -> str:
+        return "IrrecoverableHealthCheck"
+
+    def check(self) -> bool:
+        raise IrrecoverableException("Simulated irrecoverable failure")
+
+    @classmethod
+    def create(cls, manager) -> List[HealthCheck]:
+        return [cls()]
+
+
+# ============================================================================
+# Fixtures
+# ============================================================================
+
+
+@pytest.fixture
+def mock_manager():
+    manager = MagicMock()
+    manager.lmcache_engine = MagicMock()
+    manager.lmcache_engine.config.extra_config = None
+    manager.lmcache_engine.storage_manager = None
+    return manager
+
+
+@pytest.fixture
+def monitor(mock_manager):
+    return HealthMonitor(manager=mock_manager, ping_interval=0.1)
+
+
+@pytest.fixture
+def mock_backend():
+    mock = MagicMock()
+    mock.remote_url = "lm://localhost:1234"
+    mock.loop = asyncio.new_event_loop()
+    mock.connection = MagicMock()
+    mock.connection.support_ping.return_value = True
+    return mock
+
+
+# ============================================================================
+# Tests for HealthCheck Base Class
+# ============================================================================
+
+
+class TestHealthCheckBase:
+    @pytest.mark.parametrize(
+        "healthy,skip,expected_check,expected_skip",
+        [
+            (True, False, True, False),
+            (False, False, False, False),
+            (False, True, False, True),
+        ],
+    )
+    def test_simple_health_check_variants(
+        self, healthy, skip, expected_check, expected_skip
+    ):
+        check = SimpleHealthCheck(healthy=healthy, skip=skip)
+        assert check.check() is expected_check
+        assert check.should_skip() is expected_skip
+
+    def test_toggle_health_state(self):
+        check = SimpleHealthCheck(healthy=True)
+        assert check.check() is True
+        check.set_healthy(False)
+        assert check.check() is False
+
+
+# ============================================================================
+# Tests for HealthMonitor
+# ============================================================================
+
+
+class TestHealthMonitor:
+    def test_initialization(self, mock_manager):
+        monitor = HealthMonitor(manager=mock_manager, ping_interval=10.0)
+        assert monitor.is_healthy() is True
+        assert monitor._ping_interval == 10.0
+
+    @pytest.mark.parametrize(
+        "checks,expected",
+        [
+            ([SimpleHealthCheck(healthy=True), SimpleHealthCheck(healthy=True)], True),
+            (
+                [SimpleHealthCheck(healthy=True), SimpleHealthCheck(healthy=False)],
+                False,
+            ),
+            ([SimpleHealthCheck(healthy=False, skip=True)], True),  # skipped check
+        ],
+    )
+    def test_run_all_checks(self, monitor, checks, expected):
+        monitor._health_checks = checks
+        assert monitor._run_all_checks() is expected
+
+    def test_exception_treated_as_failure(self, monitor):
+        monitor._health_checks = [ExceptionHealthCheck()]
+        assert monitor._run_all_checks() is False
+
+    def test_health_state_transitions(self, monitor):
+        assert monitor.is_healthy() is True
+        monitor._set_healthy(False)
+        assert monitor.is_healthy() is False
+        monitor._set_healthy(True)
+        assert monitor.is_healthy() is True
+
+    def test_start_stop_lifecycle(self, monitor):
+        monitor._health_checks = [SimpleHealthCheck(healthy=True)]
+        thread = monitor.start()
+        assert thread is not None and thread.is_alive()
+        time.sleep(0.2)
+        monitor.stop()
+        time.sleep(0.1)
+        assert not thread.is_alive()
+
+    @pytest.mark.parametrize(
+        "checks", [[], [SimpleHealthCheck(healthy=False, skip=True)]]
+    )
+    def test_start_with_no_active_checks_returns_none(self, monitor, checks):
+        monitor._health_checks = checks
+        assert monitor.start() is None
+
+    def test_monitor_detects_state_changes(self, monitor):
+        toggle = SimpleHealthCheck(healthy=True)
+        monitor._health_checks = [toggle]
+        thread = monitor.start()
+        assert thread is not None
+
+        time.sleep(0.15)
+        assert monitor.is_healthy() is True
+
+        toggle.set_healthy(False)
+        time.sleep(0.15)
+        assert monitor.is_healthy() is False
+
+        toggle.set_healthy(True)
+        time.sleep(0.15)
+        assert monitor.is_healthy() is True
+        monitor.stop()
+
+    def test_thread_safety(self, monitor):
+        monitor._ping_interval = 0.05
+        toggle = SimpleHealthCheck(healthy=True)
+        monitor._health_checks = [toggle]
+        results, stop_event = [], threading.Event()
+
+        def reader():
+            while not stop_event.is_set():
+                results.append(monitor.is_healthy())
+                time.sleep(0.01)
+
+        monitor.start()
+        reader_thread = threading.Thread(target=reader)
+        reader_thread.start()
+
+        for _ in range(3):
+            toggle.set_healthy(False)
+            time.sleep(0.03)
+            toggle.set_healthy(True)
+            time.sleep(0.03)
+
+        stop_event.set()
+        monitor.stop()
+        reader_thread.join()
+        assert len(results) > 0
+
+
+# ============================================================================
+# Tests for RemoteBackendHealthCheck
+# ============================================================================
+
+
+class TestRemoteBackendHealthCheck:
+    def test_should_not_skip_when_connection_is_none(self, mock_backend):
+        mock_backend.connection = None
+        assert RemoteBackendHealthCheck(mock_backend).should_skip() is False
+
+    def test_name_includes_url(self, mock_backend):
+        assert "localhost:1234" in RemoteBackendHealthCheck(mock_backend).name()
+
+    def test_create_with_remote_backend(self):
+        # First Party
+        from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+        mock_backend = MagicMock(spec=RemoteBackend)
+        mock_backend.remote_url = "lm://localhost:1234"
+        mock_backend.connection = MagicMock()
+        mock_backend.config = MagicMock()
+        mock_backend.config.extra_config = None
+
+        mock_manager = MagicMock()
+        mock_manager.lmcache_engine = MagicMock()
+        mock_manager.lmcache_engine.storage_manager = MagicMock()
+        mock_manager.lmcache_engine.storage_manager.storage_backends = {
+            "RemoteBackend": mock_backend
+        }
+
+        checks = RemoteBackendHealthCheck.create(mock_manager)
+        assert len(checks) == 1 and "localhost:1234" in checks[0].name()
+
+    def test_create_no_remote_backend(self):
+        mock_manager = MagicMock()
+        mock_manager.lmcache_engine = MagicMock()
+        mock_manager.lmcache_engine.storage_manager = MagicMock()
+        mock_manager.lmcache_engine.storage_manager.storage_backends = {}
+        assert len(RemoteBackendHealthCheck.create(mock_manager)) == 0
+
+
+# ============================================================================
+# Tests for IrrecoverableException Handling
+# ============================================================================
+
+
+class TestIrrecoverableException:
+    def test_run_all_checks_propagates_irrecoverable_exception(self, monitor):
+        """Test that _run_all_checks propagates IrrecoverableException."""
+        monitor._health_checks = [IrrecoverableHealthCheck()]
+        with pytest.raises(IrrecoverableException):
+            monitor._run_all_checks()
+
+    def test_run_all_checks_irrecoverable_before_other_checks(self, monitor):
+        """Test that IrrecoverableException stops further checks."""
+        irrecoverable_check = IrrecoverableHealthCheck()
+        simple_check = SimpleHealthCheck(healthy=True)
+        monitor._health_checks = [irrecoverable_check, simple_check]
+
+        with pytest.raises(IrrecoverableException):
+            monitor._run_all_checks()
+
+        # simple_check should not have been called
+        assert simple_check.check_count == 0
+
+    def test_run_loop_stops_on_irrecoverable_exception(self, monitor):
+        """Test that _run_loop exits when IrrecoverableException is raised."""
+        monitor._health_checks = [IrrecoverableHealthCheck()]
+        monitor._ping_interval = 0.05
+
+        thread = monitor.start()
+        assert thread is not None
+
+        # Wait for the loop to encounter the exception and exit
+        time.sleep(0.2)
+
+        # The thread should have stopped due to the exception
+        assert not thread.is_alive()
+        # System should be marked unhealthy
+        assert monitor.is_healthy() is False
+
+    def test_run_loop_stops_immediately_on_irrecoverable(self, monitor):
+        """Test that the monitor stops checking after IrrecoverableException."""
+        call_count = 0
+
+        class CountingIrrecoverableCheck(HealthCheck):
+            def name(self) -> str:
+                return "CountingIrrecoverableCheck"
+
+            def check(self) -> bool:
+                nonlocal call_count
+                call_count += 1
+                raise IrrecoverableException("Stop now")
+
+            @classmethod
+            def create(cls, manager) -> List[HealthCheck]:
+                return [cls()]
+
+        monitor._health_checks = [CountingIrrecoverableCheck()]
+        monitor._ping_interval = 0.05
+
+        thread = monitor.start()
+        assert thread is not None
+
+        # Wait enough time for multiple check cycles
+        time.sleep(0.3)
+
+        # The check should only be called once before loop exits
+        assert call_count == 1
+        assert not thread.is_alive()
+
+    def test_regular_exception_does_not_stop_loop(self, monitor):
+        """Test that regular exceptions don't stop the monitoring loop."""
+        monitor._health_checks = [ExceptionHealthCheck()]
+        monitor._ping_interval = 0.05
+
+        thread = monitor.start()
+        assert thread is not None
+
+        # Wait for multiple check cycles
+        time.sleep(0.2)
+
+        # The thread should still be running (regular exceptions don't stop the loop)
+        assert thread.is_alive()
+        # System should be marked unhealthy
+        assert monitor.is_healthy() is False
+
+        monitor.stop()
diff --git a/tests/v1/test_health_monitor_fallback_recovery.py b/tests/v1/test_health_monitor_fallback_recovery.py
new file mode 100644
index 0000000..ac8ede0
--- /dev/null
+++ b/tests/v1/test_health_monitor_fallback_recovery.py
@@ -0,0 +1,641 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Integration tests for RemoteBackendHealthCheck fallback and recovery.
+
+Tests the health check lifecycle: healthy -> failure -> LOCAL_CPU fallback -> recovery.
+"""
+
+# Standard
+from typing import List, Optional
+from unittest.mock import MagicMock
+import asyncio
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.health_monitor.base import HealthMonitor
+from lmcache.v1.health_monitor.checks.remote_backend_check import (
+    RemoteBackendHealthCheck,
+)
+from lmcache.v1.health_monitor.constants import FallbackPolicy
+from lmcache.v1.memory_management import MemoryObj
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+
+class ControllablePingConnector(RemoteConnector):
+    """Mock connector with controllable ping response."""
+
+    def __init__(self):
+        self._ping_error_code = 0
+        self._ping_lock = threading.Lock()
+
+    def set_ping_error_code(self, error_code: int) -> None:
+        with self._ping_lock:
+            self._ping_error_code = error_code
+
+    def support_ping(self) -> bool:
+        return True
+
+    async def ping(self) -> int:
+        with self._ping_lock:
+            return self._ping_error_code
+
+    async def exists(self, key: CacheEngineKey) -> bool:
+        return False
+
+    def exists_sync(self, key: CacheEngineKey) -> bool:
+        return False
+
+    async def get(self, key: CacheEngineKey) -> Optional[MemoryObj]:
+        return None
+
+    async def put(self, key: CacheEngineKey, memory_obj: MemoryObj) -> None:
+        pass
+
+    async def list(self) -> List[str]:
+        return []
+
+    async def close(self) -> None:
+        pass
+
+
+class EventLoopThread:
+    """Helper to manage an event loop in a background thread."""
+
+    def __init__(self):
+        self.loop = asyncio.new_event_loop()
+        self.thread = None
+
+    def start(self):
+        self.thread = threading.Thread(target=self._run_loop, daemon=True)
+        self.thread.start()
+        time.sleep(0.05)
+
+    def _run_loop(self):
+        asyncio.set_event_loop(self.loop)
+        self.loop.run_forever()
+
+    def stop(self):
+        if self.loop.is_running():
+            self.loop.call_soon_threadsafe(self.loop.stop)
+        if self.thread:
+            self.thread.join(timeout=1.0)
+
+
+# ==============================================================================
+# Fixtures
+# ==============================================================================
+
+
+@pytest.fixture
+def event_loop_thread():
+    elt = EventLoopThread()
+    elt.start()
+    yield elt
+    elt.stop()
+
+
+@pytest.fixture
+def test_config():
+    return LMCacheEngineConfig.from_defaults(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=0.1,
+        remote_url="blackhole://test",
+        remote_serde="naive",
+        lmcache_instance_id="test_health_fallback_instance",
+        extra_config={
+            "ping_timeout": 1.0,
+            "ping_interval": 0.1,
+            "fallback_policy": "local_cpu",
+        },
+    )
+
+
+@pytest.fixture
+def test_metadata():
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+        role="worker",
+    )
+
+
+@pytest.fixture
+def controllable_connector():
+    return ControllablePingConnector()
+
+
+@pytest.fixture
+def mock_remote_backend(event_loop_thread, test_config, controllable_connector):
+    backend = MagicMock(spec=RemoteBackend)
+    backend.remote_url = "controllable://test:1234"
+    backend.loop = event_loop_thread.loop
+    backend.connection = controllable_connector
+    backend.config = test_config
+    backend.init_connection = MagicMock()
+    backend.get_blocking_failed_count = 0
+    return backend
+
+
+@pytest.fixture
+def mock_local_cpu_backend():
+    backend = MagicMock(spec=LocalCPUBackend)
+    backend.use_hot = False
+    backend.clear = MagicMock()
+    return backend
+
+
+@pytest.fixture
+def mock_storage_manager(mock_remote_backend, mock_local_cpu_backend):
+    storage_manager = MagicMock()
+    storage_manager.storage_backends = {
+        "RemoteBackend": mock_remote_backend,
+        "LocalCPUBackend": mock_local_cpu_backend,
+    }
+    storage_manager.local_cpu_backend = mock_local_cpu_backend
+    storage_manager.set_backend_bypass = MagicMock()
+    storage_manager.is_backend_bypassed = MagicMock(return_value=False)
+    return storage_manager
+
+
+@pytest.fixture
+def mock_manager(test_config, mock_storage_manager):
+    engine = MagicMock()
+    engine.storage_manager = mock_storage_manager
+    manager = MagicMock()
+    manager.lmcache_engine = engine
+    manager._config = test_config
+    return manager
+
+
+# ==============================================================================
+# Test Classes
+# ==============================================================================
+
+
+class TestRemoteBackendHealthCheckFallbackRecovery:
+    """Test cases for RemoteBackendHealthCheck fallback and recovery."""
+
+    def test_health_check_creation_and_basic_checks(
+        self,
+        mock_manager,
+        mock_remote_backend,
+        controllable_connector,
+        event_loop_thread,
+    ):
+        """Test health check creation and basic pass/fail scenarios."""
+        # Verify creation with LOCAL_CPU fallback
+        checks = RemoteBackendHealthCheck.create(mock_manager)
+        assert len(checks) == 1
+        check = checks[0]
+        assert isinstance(check, RemoteBackendHealthCheck)
+        assert check.fallback_policy == FallbackPolicy.LOCAL_CPU
+        assert check.get_bypass_backend_name() == "RemoteBackend"
+
+        # Test pass when ping returns 0
+        controllable_connector.set_ping_error_code(0)
+        assert check.check() is True
+
+        # Test fail when ping returns non-zero
+        controllable_connector.set_ping_error_code(1)
+        assert check.check() is False
+
+    def test_fallback_and_recovery_cycle(
+        self,
+        mock_manager,
+        mock_remote_backend,
+        mock_local_cpu_backend,
+        mock_storage_manager,
+        controllable_connector,
+        event_loop_thread,
+    ):
+        """Test complete fallback and recovery cycle."""
+        monitor = HealthMonitor(manager=mock_manager, ping_interval=0.1)
+        assert len(monitor._health_checks) == 1
+
+        # Initially healthy
+        controllable_connector.set_ping_error_code(0)
+        assert monitor._run_all_checks() is True
+
+        mock_storage_manager.set_backend_bypass.reset_mock()
+
+        # Simulate failure - should apply LOCAL_CPU fallback
+        controllable_connector.set_ping_error_code(1)
+        assert monitor._run_all_checks() is True  # Still healthy due to fallback
+        mock_storage_manager.set_backend_bypass.assert_called_with(
+            "RemoteBackend", True
+        )
+        assert mock_local_cpu_backend.use_hot is True
+
+        mock_storage_manager.set_backend_bypass.reset_mock()
+
+        # Recovery - ping returns 0 again
+        controllable_connector.set_ping_error_code(0)
+        monitor._run_all_checks()
+        mock_storage_manager.set_backend_bypass.assert_called_with(
+            "RemoteBackend", False
+        )
+        assert mock_local_cpu_backend.use_hot is False
+        mock_local_cpu_backend.clear.assert_called_once()
+
+    def test_full_cycle_with_monitor_thread(
+        self,
+        mock_manager,
+        mock_remote_backend,
+        mock_local_cpu_backend,
+        mock_storage_manager,
+        controllable_connector,
+        event_loop_thread,
+    ):
+        """Test fallback/recovery using the monitor thread."""
+        monitor = HealthMonitor(manager=mock_manager, ping_interval=0.05)
+        controllable_connector.set_ping_error_code(0)
+
+        thread = monitor.start()
+        assert thread is not None
+
+        try:
+            time.sleep(0.2)
+            assert monitor.is_healthy() is True
+
+            # Simulate failure
+            controllable_connector.set_ping_error_code(1)
+            time.sleep(0.2)
+            assert monitor.is_healthy() is True
+            assert mock_local_cpu_backend.use_hot is True
+
+            # Simulate recovery
+            controllable_connector.set_ping_error_code(0)
+            time.sleep(0.2)
+            assert monitor.is_healthy() is True
+            assert mock_local_cpu_backend.use_hot is False
+        finally:
+            monitor.stop()
+
+    def test_multiple_failures_do_not_duplicate_fallback(
+        self,
+        mock_manager,
+        mock_local_cpu_backend,
+        mock_storage_manager,
+        controllable_connector,
+        event_loop_thread,
+    ):
+        """Test that consecutive failures don't duplicate fallback actions."""
+        monitor = HealthMonitor(manager=mock_manager, ping_interval=0.1)
+
+        controllable_connector.set_ping_error_code(0)
+        monitor._run_all_checks()
+        mock_storage_manager.set_backend_bypass.reset_mock()
+
+        # Multiple failures should only trigger fallback once
+        controllable_connector.set_ping_error_code(1)
+        monitor._run_all_checks()
+        first_call_count = mock_storage_manager.set_backend_bypass.call_count
+        assert first_call_count == 1
+
+        monitor._run_all_checks()
+        monitor._run_all_checks()
+        assert mock_storage_manager.set_backend_bypass.call_count == first_call_count
+
+    def test_multiple_backends_fallback_and_partial_recovery(
+        self,
+        mock_local_cpu_backend,
+        mock_storage_manager,
+        event_loop_thread,
+        test_config,
+    ):
+        """
+        Test that original_hot_cache is preserved correctly when multiple backends
+        fail and only some recover.
+
+        Scenario:
+        1. Initial state: use_hot = False
+        2. Backend A fails -> use_hot = True, original saved as False
+        3. Backend B fails -> use_hot = True, original should still be False
+        4. Backend A recovers -> use_hot should STAY True (B still down)
+        5. Backend B recovers -> use_hot should be restored to False
+        """
+        # Create two controllable connectors for two backends
+        connector_a = ControllablePingConnector()
+        connector_b = ControllablePingConnector()
+
+        # Create two mock remote backends
+        backend_a = MagicMock(spec=RemoteBackend)
+        backend_a.remote_url = "controllable://test_a:1234"
+        backend_a.loop = event_loop_thread.loop
+        backend_a.connection = connector_a
+        backend_a.config = test_config
+        backend_a.init_connection = MagicMock()
+        backend_a.get_blocking_failed_count = 0
+
+        backend_b = MagicMock(spec=RemoteBackend)
+        backend_b.remote_url = "controllable://test_b:1234"
+        backend_b.loop = event_loop_thread.loop
+        backend_b.connection = connector_b
+        backend_b.config = test_config
+        backend_b.init_connection = MagicMock()
+        backend_b.get_blocking_failed_count = 0
+
+        # Update storage manager to have two remote backends
+        mock_storage_manager.storage_backends = {
+            "RemoteBackend_A": backend_a,
+            "RemoteBackend_B": backend_b,
+            "LocalCPUBackend": mock_local_cpu_backend,
+        }
+
+        # Create mock manager
+        engine = MagicMock()
+        engine.storage_manager = mock_storage_manager
+        manager = MagicMock()
+        manager.lmcache_engine = engine
+        manager._config = test_config
+
+        # Create two health checks manually
+        check_a = RemoteBackendHealthCheck(backend=backend_a)
+        check_a._backend_name = "RemoteBackend_A"
+
+        check_b = RemoteBackendHealthCheck(backend=backend_b)
+        check_b._backend_name = "RemoteBackend_B"
+
+        # Create monitor and manually set health checks
+        monitor = HealthMonitor(manager=manager, ping_interval=0.1)
+        monitor._health_checks = [check_a, check_b]
+        monitor._previous_check_status = {
+            check_a.name(): True,
+            check_b.name(): True,
+        }
+
+        # Initial state: use_hot = False
+        mock_local_cpu_backend.use_hot = False
+
+        # Step 1: Both backends healthy
+        connector_a.set_ping_error_code(0)
+        connector_b.set_ping_error_code(0)
+        monitor._run_all_checks()
+        assert mock_local_cpu_backend.use_hot is False
+        assert len(monitor._bypassed_backends) == 0
+        assert monitor._original_hot_cache is None
+
+        # Step 2: Backend A fails
+        connector_a.set_ping_error_code(1)
+        monitor._run_all_checks()
+        assert mock_local_cpu_backend.use_hot is True
+        assert "RemoteBackend_A" in monitor._bypassed_backends
+        assert monitor._original_hot_cache is False  # Saved original value
+
+        # Step 3: Backend B also fails
+        connector_b.set_ping_error_code(1)
+        monitor._run_all_checks()
+        assert mock_local_cpu_backend.use_hot is True
+        assert "RemoteBackend_A" in monitor._bypassed_backends
+        assert "RemoteBackend_B" in monitor._bypassed_backends
+        # CRITICAL: original_hot_cache should STILL be False, not True
+        assert monitor._original_hot_cache is False
+
+        mock_local_cpu_backend.clear.reset_mock()
+
+        # Step 4: Backend A recovers
+        connector_a.set_ping_error_code(0)
+        monitor._run_all_checks()
+        assert "RemoteBackend_A" not in monitor._bypassed_backends
+        assert "RemoteBackend_B" in monitor._bypassed_backends
+        # CRITICAL: use_hot should STAY True because B is still down
+        assert mock_local_cpu_backend.use_hot is True
+        # clear() should NOT have been called yet
+        mock_local_cpu_backend.clear.assert_not_called()
+        # original_hot_cache should still be preserved
+        assert monitor._original_hot_cache is False
+
+        # Step 5: Backend B recovers
+        connector_b.set_ping_error_code(0)
+        monitor._run_all_checks()
+        assert len(monitor._bypassed_backends) == 0
+        # CRITICAL: Now use_hot should be restored to False
+        assert mock_local_cpu_backend.use_hot is False
+        # clear() should have been called now
+        mock_local_cpu_backend.clear.assert_called_once()
+        # original_hot_cache should be reset
+        assert monitor._original_hot_cache is None
+
+
+class TestRemoteBackendHealthCheckEdgeCases:
+    """Test edge cases for RemoteBackendHealthCheck."""
+
+    def test_health_check_with_asyncio(self, event_loop_thread, test_config):
+        """Test check() properly uses asyncio for ping."""
+        connector = ControllablePingConnector()
+        backend = MagicMock(spec=RemoteBackend)
+        backend.remote_url = "controllable://test:1234"
+        backend.loop = event_loop_thread.loop
+        backend.connection = connector
+        backend.init_connection = MagicMock()
+        backend.config = test_config
+        backend.get_blocking_failed_count = 0
+
+        check = RemoteBackendHealthCheck(backend=backend)
+        check._backend_name = "RemoteBackend"
+
+        connector.set_ping_error_code(0)
+        assert check.check() is True
+
+        connector.set_ping_error_code(42)
+        assert check.check() is False
+
+    def test_health_check_handles_ping_timeout(self, event_loop_thread):
+        """Test health check handles ping timeout correctly."""
+
+        class SlowPingConnector(ControllablePingConnector):
+            async def ping(self) -> int:
+                try:
+                    await asyncio.sleep(10)
+                except asyncio.CancelledError:
+                    pass
+                return 0
+
+        # Create config with short ping timeout
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.1,
+            remote_url="blackhole://test",
+            remote_serde="naive",
+            lmcache_instance_id="test_ping_timeout",
+            extra_config={
+                "ping_timeout": 0.1,
+                "ping_interval": 0.1,
+                "fallback_policy": "local_cpu",
+            },
+        )
+
+        backend = MagicMock(spec=RemoteBackend)
+        backend.remote_url = "slow://test:1234"
+        backend.loop = event_loop_thread.loop
+        backend.connection = SlowPingConnector()
+        backend.init_connection = MagicMock()
+        backend.config = config
+        backend.get_blocking_failed_count = 0
+
+        check = RemoteBackendHealthCheck(backend=backend)
+        check._backend_name = "RemoteBackend"
+
+        assert check.check() is False
+
+    def test_health_check_handles_none_connection(self, test_config):
+        """Test health check handles None connection gracefully."""
+        backend = MagicMock(spec=RemoteBackend)
+        backend.remote_url = "none://test:1234"
+        backend.connection = None
+        backend.init_connection = MagicMock()
+        backend.config = test_config
+
+        check = RemoteBackendHealthCheck(backend=backend)
+
+        assert check.check() is False
+
+
+class TestFallbackWithCacheEngineOperations:
+    """Test fallback behavior through CacheEngine operations (lookup/store/retrieve)."""
+
+    def test_store_lookup_retrieve_during_fallback(
+        self,
+        mock_manager,
+        mock_local_cpu_backend,
+        mock_storage_manager,
+        controllable_connector,
+        event_loop_thread,
+    ):
+        """Test operations bypass RemoteBackend during fallback."""
+        monitor = HealthMonitor(manager=mock_manager, ping_interval=0.1)
+
+        # Start healthy
+        controllable_connector.set_ping_error_code(0)
+        monitor._run_all_checks()
+        assert mock_local_cpu_backend.use_hot is False
+
+        # Trigger fallback
+        controllable_connector.set_ping_error_code(1)
+        monitor._run_all_checks()
+
+        # Verify fallback state
+        mock_storage_manager.set_backend_bypass.assert_called_with(
+            "RemoteBackend", True
+        )
+        assert mock_local_cpu_backend.use_hot is True
+        mock_storage_manager.is_backend_bypassed.return_value = True
+        assert mock_storage_manager.is_backend_bypassed("RemoteBackend") is True
+
+        # Recovery
+        controllable_connector.set_ping_error_code(0)
+        monitor._run_all_checks()
+
+        mock_storage_manager.set_backend_bypass.assert_called_with(
+            "RemoteBackend", False
+        )
+        assert mock_local_cpu_backend.use_hot is False
+        mock_local_cpu_backend.clear.assert_called_once()
+
+
+class TestFallbackIntegrationWithRealStorageManager:
+    """Integration tests using real StorageManager."""
+
+    @pytest.fixture
+    def real_storage_manager(self, test_metadata):
+        # First Party
+        from lmcache.v1.event_manager import EventManager
+        from lmcache.v1.storage_backend.storage_manager import StorageManager
+
+        config = LMCacheEngineConfig.from_defaults(
+            chunk_size=256,
+            local_cpu=True,
+            max_local_cpu_size=0.5,
+            lmcache_instance_id="test_fallback_integration",
+            extra_config={
+                "ping_timeout": 1.0,
+                "ping_interval": 0.1,
+                "fallback_policy": "local_cpu",
+            },
+        )
+        manager = StorageManager(
+            config=config, metadata=test_metadata, event_manager=EventManager()
+        )
+        yield manager
+        manager.close()
+
+    def test_storage_manager_bypass_mode(self, real_storage_manager):
+        """Test StorageManager bypass mode operations."""
+        sm = real_storage_manager
+
+        # Initially no backends bypassed
+        assert sm.is_backend_bypassed("RemoteBackend") is False
+        assert sm.is_backend_bypassed("LocalCPUBackend") is False
+
+        # Test bypass toggle
+        sm.set_backend_bypass("RemoteBackend", True)
+        assert sm.is_backend_bypassed("RemoteBackend") is True
+
+        sm.set_backend_bypass("RemoteBackend", False)
+        assert sm.is_backend_bypassed("RemoteBackend") is False
+
+    def test_get_active_backends_respects_bypass(self, real_storage_manager):
+        """Test get_active_storage_backends skips bypassed backends."""
+        sm = real_storage_manager
+        # This test requires RemoteBackend to be configured
+        assert "RemoteBackend" not in sm.storage_backends, (
+            "Test requires no RemoteBackend"
+        )
+
+        # Verify bypass logic works with LocalCPUBackend
+        assert "LocalCPUBackend" in sm.storage_backends
+        sm.set_backend_bypass("LocalCPUBackend", True)
+        backend_names = [name for name, _ in sm.get_active_storage_backends()]
+        assert "LocalCPUBackend" not in backend_names
+        sm.set_backend_bypass("LocalCPUBackend", False)
+
+    def test_local_cpu_hot_cache_toggle(self, real_storage_manager):
+        """Test LocalCPUBackend hot cache can be toggled."""
+        assert real_storage_manager.local_cpu_backend is not None, (
+            "Test requires LocalCPUBackend"
+        )
+        local_cpu = real_storage_manager.local_cpu_backend
+        original = local_cpu.use_hot
+
+        local_cpu.use_hot = True
+        assert local_cpu.use_hot is True
+
+        local_cpu.use_hot = False
+        assert local_cpu.use_hot is False
+
+        local_cpu.use_hot = original
+
+    def test_contains_respects_bypass(self, real_storage_manager):
+        """Test contains operation respects bypass mode."""
+        sm = real_storage_manager
+        test_key = CacheEngineKey(
+            model_name="test_model",
+            world_size=1,
+            worker_id=0,
+            chunk_hash=hash("test"),
+            dtype=torch.bfloat16,
+        )
+
+        # Test with LocalCPUBackend bypass
+        assert "LocalCPUBackend" in sm.storage_backends, "Test requires LocalCPUBackend"
+        sm.set_backend_bypass("LocalCPUBackend", True)
+        result = sm.contains(test_key)
+        assert result is None  # No other backend available
+        sm.set_backend_bypass("LocalCPUBackend", False)
diff --git a/tests/v1/test_hidden_state_store.py b/tests/v1/test_hidden_state_store.py
new file mode 100644
index 0000000..e9cf516
--- /dev/null
+++ b/tests/v1/test_hidden_state_store.py
@@ -0,0 +1,434 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for :class:`HiddenStateStore` and engine integration.
+
+These tests construct a :class:`HiddenStateStore` directly so they don't need
+a full :class:`LMCacheEngine`, GPU connector, or storage manager. The KV
+presence side of "coupled eviction" is exercised via a tiny fake storage
+manager that exposes the single ``contains`` method the store consults.
+"""
+
+# Standard
+from typing import Optional, Set
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.hidden_state_store import HiddenStateStore
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.token_database import ChunkedTokenDatabase
+
+CHUNK_SIZE = 8
+HIDDEN_DIM = 16
+
+
+def _metadata() -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(1, 2, CHUNK_SIZE, 1, HIDDEN_DIM),
+    )
+
+
+def _config(
+    *,
+    enable_hidden_state_cache: bool = True,
+    pool_gb: float = 0.05,
+    layers=None,
+) -> LMCacheEngineConfig:
+    """Minimal CPU-only config for HS-store tests."""
+    return LMCacheEngineConfig.from_defaults(
+        chunk_size=CHUNK_SIZE,
+        local_cpu=True,
+        max_local_cpu_size=0.05,
+        local_disk=None,
+        max_local_disk_size=0,
+        remote_url=None,
+        save_unfull_chunk=False,
+        enable_hidden_state_cache=enable_hidden_state_cache,
+        max_hidden_state_cpu_size=pool_gb,
+        hidden_state_layers=layers,
+    )
+
+
+def _token_db(config: LMCacheEngineConfig) -> ChunkedTokenDatabase:
+    db = ChunkedTokenDatabase(config, _metadata())
+    return db
+
+
+class _Fixture:
+    """Bundle a config, one token database, and a fake SM.
+
+    A shared :class:`ChunkedTokenDatabase` instance is essential here: the
+    database lazily resolves its hash function on first use, so two separate
+    instances can pick different ``NONE_HASH`` seeds and produce different
+    keys for the same tokens.
+    """
+
+    def __init__(self, *, layers=None, pool_gb: float = 0.05) -> None:
+        self.config = _config(layers=layers, pool_gb=pool_gb)
+        self.db = _token_db(self.config)
+        self.sm = _FakeStorageManager()
+        self.store = HiddenStateStore(self.config, self.db)
+        self.store.bind_storage_manager(self.sm)  # type: ignore[arg-type]
+
+    def keys_for(self, token_ids):
+        return [key for _, _, key in self.db.process_tokens(tokens=token_ids)]
+
+    def mark_kv_present(self, keys) -> None:
+        self.sm.present.update(keys)
+
+    def close(self) -> None:
+        self.store.close()
+
+
+class _FakeStorageManager:
+    """Implements just the ``contains(key)`` slice the store consults."""
+
+    def __init__(self, present_keys: Optional[Set[CacheEngineKey]] = None) -> None:
+        self.present: Set[CacheEngineKey] = (
+            set(present_keys) if present_keys is not None else set()
+        )
+
+    def contains(self, key, search_range=None, pin: bool = False):  # noqa: D401
+        return "LocalCPUBackend" if key in self.present else None
+
+
+# ---------------------------------------------------------------------------
+# Alignment with KV chunking
+# ---------------------------------------------------------------------------
+
+
+def test_chunks_align_with_kv_keys():
+    """HS uses the engine's TokenDatabase, so chunk keys equal KV chunk keys."""
+    fix = _Fixture()
+    token_ids = list(range(3 * CHUNK_SIZE))  # exactly three full chunks
+    expected_keys = fix.keys_for(token_ids)
+    assert len(expected_keys) == 3
+    fix.mark_kv_present(expected_keys)
+
+    n = fix.store.store_hidden_states(
+        token_ids, torch.randn(len(token_ids), HIDDEN_DIM)
+    )
+    assert n == 3
+    for k in expected_keys:
+        assert fix.store.has_chunk(k, layer_idx=0)
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Round-trip retrieve
+# ---------------------------------------------------------------------------
+
+
+def test_store_then_retrieve_roundtrip():
+    fix = _Fixture()
+    token_ids = list(range(2 * CHUNK_SIZE))
+    fix.mark_kv_present(fix.keys_for(token_ids))
+
+    rows = torch.randn(len(token_ids), HIDDEN_DIM)
+    assert fix.store.store_hidden_states(token_ids, rows) == 2
+
+    out = fix.store.retrieve_hidden_states(token_ids)
+    assert out is not None
+    assert out.shape == (len(token_ids), HIDDEN_DIM)
+    torch.testing.assert_close(out, rows.to(torch.float32))
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Coupled eviction (KV evict implies HS evict on next read)
+# ---------------------------------------------------------------------------
+
+
+def test_kv_eviction_truncates_retrieved_prefix():
+    fix = _Fixture()
+    token_ids = list(range(3 * CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    rows = torch.randn(len(token_ids), HIDDEN_DIM)
+    fix.store.store_hidden_states(token_ids, rows)
+    assert fix.store.num_cached_chunks() == 3
+
+    fix.sm.present.discard(keys[1])  # simulate KV eviction of chunk #1
+
+    out = fix.store.retrieve_hidden_states(token_ids)
+    assert out is not None
+    assert out.shape == (CHUNK_SIZE, HIDDEN_DIM)
+    torch.testing.assert_close(out, rows[:CHUNK_SIZE].to(torch.float32))
+    # KV evict -> HS evict (orphan dropped lazily on retrieve).
+    assert not fix.store.has_chunk(keys[1])
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Retrieve refreshes LRU in reverse prefix order
+# ---------------------------------------------------------------------------
+
+
+def test_retrieve_refreshes_lru_in_reverse_prefix_order():
+    """After a prefix retrieve, earliest chunks are MRU and suffix chunks LRU.
+
+    ``retrieve_hidden_states`` collects hit keys during the prefix walk, then
+    touches ``_lru`` in reverse order so that under HS-only pool pressure the
+    suffix is evicted before the prefix (matching KV cache LRU semantics).
+    """
+    fix = _Fixture()
+    token_ids = list(range(3 * CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    fix.store.store_hidden_states(token_ids, torch.randn(len(token_ids), HIDDEN_DIM))
+    # Store order: oldest -> newest.
+    assert list(fix.store._lru.keys()) == keys
+
+    fix.store.retrieve_hidden_states(token_ids)
+    # Reverse touch on hit: suffix oldest, prefix newest.
+    assert list(fix.store._lru.keys()) == [keys[2], keys[1], keys[0]]
+    fix.close()
+
+
+def test_retrieve_reverse_lru_evicts_suffix_before_prefix():
+    """HS-only eviction after retrieve drops the suffix chunk, not the prefix."""
+    fix = _Fixture()
+    token_ids = list(range(3 * CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    fix.store.store_hidden_states(token_ids, torch.randn(len(token_ids), HIDDEN_DIM))
+    fix.store.retrieve_hidden_states(token_ids)
+
+    assert fix.store._evict_one_lru()
+    assert fix.store.has_chunk(keys[0])
+    assert fix.store.has_chunk(keys[1])
+    assert not fix.store.has_chunk(keys[2])
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# HS-only eviction does not touch KV
+# ---------------------------------------------------------------------------
+
+
+def test_hs_eviction_does_not_imply_kv_eviction():
+    fix = _Fixture()
+    token_ids = list(range(2 * CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    fix.store.store_hidden_states(token_ids, torch.randn(len(token_ids), HIDDEN_DIM))
+    assert fix.store.drop_key(keys[0])  # HS-only LRU-style eviction
+    # KV-side state untouched.
+    assert keys[0] in fix.sm.present
+    assert keys[1] in fix.sm.present
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Partial restore cutoff (HS missing in the middle)
+# ---------------------------------------------------------------------------
+
+
+def test_partial_restore_cutoff_when_hs_missing():
+    fix = _Fixture()
+    token_ids = list(range(3 * CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    rows = torch.randn(len(token_ids), HIDDEN_DIM)
+    fix.store.store_hidden_states(token_ids, rows)
+    fix.store.drop_key(keys[1])  # HS hole in the middle, KV intact
+
+    out = fix.store.retrieve_hidden_states(token_ids)
+    assert out is not None
+    # prefix_strict: stop at the missing-HS chunk.
+    assert out.shape == (CHUNK_SIZE, HIDDEN_DIM)
+    torch.testing.assert_close(out, rows[:CHUNK_SIZE].to(torch.float32))
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Multi-layer storage and per-layer retrieve
+# ---------------------------------------------------------------------------
+
+
+def test_multi_layer_store_and_retrieve():
+    fix = _Fixture()
+    token_ids = list(range(2 * CHUNK_SIZE))
+    fix.mark_kv_present(fix.keys_for(token_ids))
+
+    layer0 = torch.randn(len(token_ids), HIDDEN_DIM)
+    layer3 = torch.randn(len(token_ids), HIDDEN_DIM)
+    assert fix.store.store_hidden_states(token_ids, layer0, layer_idx=0) > 0
+    assert fix.store.store_hidden_states(token_ids, layer3, layer_idx=3) > 0
+
+    out0 = fix.store.retrieve_hidden_states(token_ids, layer_idx=0)
+    out3 = fix.store.retrieve_hidden_states(token_ids, layer_idx=3)
+    assert out0 is not None and out3 is not None
+    torch.testing.assert_close(out0, layer0.to(torch.float32))
+    torch.testing.assert_close(out3, layer3.to(torch.float32))
+    assert fix.store.retrieve_hidden_states(token_ids, layer_idx=99) is None
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Layer allowlist filters writes
+# ---------------------------------------------------------------------------
+
+
+def test_layer_allowlist_filters_writes():
+    fix = _Fixture(layers=[0])
+    token_ids = list(range(CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    rows = torch.randn(len(token_ids), HIDDEN_DIM)
+    assert fix.store.store_hidden_states(token_ids, rows, layer_idx=0) == 1
+    assert fix.store.store_hidden_states(token_ids, rows, layer_idx=1) == 0
+    assert fix.store.has_chunk(keys[0], layer_idx=0)
+    assert not fix.store.has_chunk(keys[0], layer_idx=1)
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# Separate memory pool isolation
+# ---------------------------------------------------------------------------
+
+
+def test_hs_pool_is_independent_object():
+    """Each HS store owns its own ``MixedMemoryAllocator`` (and pinned buffer).
+
+    Filling one store's pool does not affect a peer store's contents.
+    """
+    fix_a = _Fixture()
+    fix_b = _Fixture()
+    assert fix_a.store._allocator is not fix_b.store._allocator
+
+    n_toks = 4 * CHUNK_SIZE
+    rows = torch.randn(n_toks, HIDDEN_DIM)
+    token_ids = list(range(n_toks))
+    fix_a.mark_kv_present(fix_a.keys_for(token_ids))
+    fix_a.store.store_hidden_states(token_ids, rows)
+    assert fix_a.store.num_cached_chunks() > 0
+    assert fix_b.store.num_cached_chunks() == 0
+    fix_a.close()
+    fix_b.close()
+
+
+# ---------------------------------------------------------------------------
+# Without a bound storage manager, retrieve assumes KV is present.
+# ---------------------------------------------------------------------------
+
+
+def test_retrieve_without_bound_sm_returns_full_prefix():
+    cfg = _config()
+    db = _token_db(cfg)
+    store = HiddenStateStore(cfg, db)  # no SM bound
+
+    token_ids = list(range(2 * CHUNK_SIZE))
+    rows = torch.randn(len(token_ids), HIDDEN_DIM)
+    store.store_hidden_states(token_ids, rows)
+
+    out = store.retrieve_hidden_states(token_ids)
+    assert out is not None
+    assert out.shape == (len(token_ids), HIDDEN_DIM)
+    store.close()
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+
+def test_store_rejects_wrong_shape():
+    fix = _Fixture()
+    with pytest.raises(ValueError):
+        fix.store.store_hidden_states([1, 2, 3], torch.randn(2, HIDDEN_DIM))
+    with pytest.raises(ValueError):
+        fix.store.store_hidden_states([1, 2, 3], torch.randn(3))
+    fix.close()
+
+
+# ---------------------------------------------------------------------------
+# token_offset: incremental store
+# ---------------------------------------------------------------------------
+
+
+def test_store_with_token_offset_aligns_with_kv_keys():
+    """Calling store incrementally via token_offset stores all chunks with
+    correct KV-aligned keys, and retrieve returns the full concatenated rows.
+
+    Simulates the vllm-omni pattern where:
+    - call 1 covers the first CHUNK_SIZE tokens (offset=0, short token_ids)
+    - call 2 covers the next CHUNK_SIZE tokens (offset=CHUNK_SIZE, full
+      token_ids so chunk keys are KV-aligned across the whole prefix)
+    """
+    fix = _Fixture()
+    token_ids = list(range(2 * CHUNK_SIZE))
+    keys = fix.keys_for(token_ids)
+    fix.mark_kv_present(keys)
+
+    rows = torch.randn(len(token_ids), HIDDEN_DIM)
+
+    # First call: only the first chunk's tokens are available so far.
+    # Pass just that segment; chunk key is computed identically because
+    # the first chunk's key depends only on token_ids[0:CHUNK_SIZE].
+    n1 = fix.store.store_hidden_states(
+        token_ids[:CHUNK_SIZE], rows[:CHUNK_SIZE], token_offset=0
+    )
+    assert n1 == 1
+
+    # Second call: full token_ids for correct KV-aligned chunk keys,
+    # but hidden_states covers only token_ids[CHUNK_SIZE:] (the new tokens).
+    n2 = fix.store.store_hidden_states(
+        token_ids, rows[CHUNK_SIZE:], token_offset=CHUNK_SIZE
+    )
+    assert n2 == 1
+
+    # Both chunk keys should now be present.
+    for k in keys:
+        assert fix.store.has_chunk(k, layer_idx=0)
+
+    # Retrieve should return the full prefix, matching original rows.
+    out = fix.store.retrieve_hidden_states(token_ids)
+    assert out is not None
+    assert out.shape == (len(token_ids), HIDDEN_DIM)
+    torch.testing.assert_close(out, rows.to(torch.float32))
+    fix.close()
+
+
+def test_store_token_offset_rejects_bad_args():
+    """token_offset out of range or mismatched hidden_states length is rejected."""
+    fix = _Fixture()
+    token_ids = list(range(CHUNK_SIZE))
+
+    # Negative offset.
+    with pytest.raises(ValueError):
+        fix.store.store_hidden_states(
+            token_ids, torch.randn(CHUNK_SIZE, HIDDEN_DIM), token_offset=-1
+        )
+
+    # Offset beyond sequence length.
+    with pytest.raises(ValueError):
+        fix.store.store_hidden_states(
+            token_ids,
+            torch.randn(0, HIDDEN_DIM),
+            token_offset=CHUNK_SIZE + 1,
+        )
+
+    # hidden_states rows don't match n_toks - token_offset.
+    with pytest.raises(ValueError):
+        fix.store.store_hidden_states(
+            token_ids,
+            torch.randn(CHUNK_SIZE, HIDDEN_DIM),  # should be CHUNK_SIZE - 2 rows
+            token_offset=2,
+        )
+    fix.close()
diff --git a/tests/v1/test_impl_completeness.py b/tests/v1/test_impl_completeness.py
new file mode 100644
index 0000000..ff3a18d
--- /dev/null
+++ b/tests/v1/test_impl_completeness.py
@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unified test to ensure wrapper implementations implement all methods
+defined in their base interface classes.
+
+This test uses parameterization to handle multiple base classes and their
+implementations, making it easy to add new completeness checks.
+"""
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.lookup_client.abstract_client import LookupClientInterface
+from lmcache.v1.lookup_client.chunk_statistics_lookup_client import (
+    ChunkStatisticsLookupClient,
+)
+from lmcache.v1.lookup_client.hit_limit_lookup_client import HitLimitLookupClient
+from lmcache.v1.storage_backend.connector.audit_connector import AuditConnector
+from lmcache.v1.storage_backend.connector.base_connector import RemoteConnector
+from lmcache.v1.storage_backend.connector.instrumented_connector import (
+    InstrumentedRemoteConnector,
+)
+from tests.v1.utils import (
+    check_method_signatures,
+    get_abstract_methods,
+    get_all_methods_from_base,
+    get_methods_implemented_in_class,
+)
+
+
+class TestImplementationCompleteness:
+    """Test that wrapper implementations implement all base interface methods"""
+
+    @pytest.mark.parametrize(
+        "base_class,impl_class",
+        [
+            # Lookup client implementations
+            (LookupClientInterface, HitLimitLookupClient),
+            (LookupClientInterface, ChunkStatisticsLookupClient),
+            # Storage backend connector implementations
+            (RemoteConnector, AuditConnector),
+            (RemoteConnector, InstrumentedRemoteConnector),
+        ],
+    )
+    def test_implementation_completeness(self, base_class, impl_class):
+        """
+        Verify implementations have all methods from their base class.
+        """
+        base_name = base_class.__name__
+        impl_name = impl_class.__name__
+
+        # 1. Get all methods from base class
+        base_methods = get_all_methods_from_base(base_class)
+
+        # 2. Get methods actually implemented in the class
+        impl_methods = get_methods_implemented_in_class(impl_class, base_class)
+
+        # 3. Check which base methods are missing in the implementation
+        missing_methods = base_methods - impl_methods
+
+        assert len(missing_methods) == 0, (
+            f"{impl_name} is missing {len(missing_methods)} methods from "
+            f"{base_name}: {sorted(missing_methods)}\n"
+            f"Base methods: {sorted(base_methods)}\n"
+            f"Implemented methods: {sorted(impl_methods)}"
+        )
+
+        # 4. Check all abstract methods are implemented
+        abstract_methods = get_abstract_methods(base_class)
+        missing_abstract = []
+        for method_name in abstract_methods:
+            # Check if the method is actually implemented in the class
+            if method_name not in impl_methods:
+                missing_abstract.append(method_name)
+
+        assert len(missing_abstract) == 0, (
+            f"{impl_name} has not implemented {len(missing_abstract)} "
+            f"abstract methods: {sorted(missing_abstract)}"
+        )
+
+        # 5. Check method signatures match
+        signature_mismatches = check_method_signatures(base_class, impl_class)
+
+        assert len(signature_mismatches) == 0, (
+            f"{impl_name} has {len(signature_mismatches)} method signature "
+            f"mismatches:\n"
+            + "\n".join(
+                f"  - {m['method']}: base={m['base_params']}, impl={m['impl_params']}"
+                for m in signature_mismatches
+            )
+        )
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v", "-s"])
diff --git a/tests/v1/test_json_utils.py b/tests/v1/test_json_utils.py
new file mode 100644
index 0000000..6b94fc1
--- /dev/null
+++ b/tests/v1/test_json_utils.py
@@ -0,0 +1,108 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Unit tests for lmcache.v1.utils.json_utils.
+
+Covers make_json_safe (recursive sanitization) and safe_asdict
+(dataclass -> JSON-safe dict) across primitive, container,
+nested, non-serializable, and invalid-input scenarios.
+"""
+
+# Standard
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.utils.json_utils import make_json_safe, safe_asdict
+
+# ---------------------------------------------------------------- #
+#  make_json_safe
+# ---------------------------------------------------------------- #
+
+
+class TestMakeJsonSafe:
+    @pytest.mark.parametrize(
+        "value",
+        ["s", 1, 1.5, True, False, None],
+    )
+    def test_primitives_unchanged(self, value: Any):
+        """JSON-native primitives are returned unchanged."""
+        assert make_json_safe(value) == value
+        assert type(make_json_safe(value)) is type(value)
+
+    def test_dict_recursively_sanitized(self):
+        obj = {"a": 1, "b": Path("/tmp/x"), "c": {"d": (1, 2)}}
+        result = make_json_safe(obj)
+        assert result == {"a": 1, "b": "/tmp/x", "c": {"d": [1, 2]}}
+
+    def test_tuple_becomes_list(self):
+        assert make_json_safe((1, 2, 3)) == [1, 2, 3]
+
+    def test_list_recursively_sanitized(self):
+        assert make_json_safe([1, Path("/a"), [Path("/b")]]) == [
+            1,
+            "/a",
+            ["/b"],
+        ]
+
+    def test_non_serializable_falls_back_to_str(self):
+        class Opaque:
+            def __str__(self) -> str:
+                return "opaque-repr"
+
+        assert make_json_safe(Opaque()) == "opaque-repr"
+
+    def test_nested_mixed_structures(self):
+        obj = {"items": [{"p": Path("/x")}, (Path("/y"),)]}
+        assert make_json_safe(obj) == {
+            "items": [{"p": "/x"}, ["/y"]],
+        }
+
+
+# ---------------------------------------------------------------- #
+#  safe_asdict
+# ---------------------------------------------------------------- #
+
+
+@dataclass
+class _FakeCfg:
+    name: str = "n"
+    port: int = 8080
+    path: Path = Path("/tmp/cfg")
+    nested: dict = field(default_factory=lambda: {"k": Path("/v")})
+
+
+@dataclass
+class _EmptyCfg:
+    pass
+
+
+class TestSafeAsdict:
+    def test_dataclass_converted_with_non_serializable_fields(self):
+        result = safe_asdict(_FakeCfg())
+        assert result == {
+            "name": "n",
+            "port": 8080,
+            "path": "/tmp/cfg",
+            "nested": {"k": "/v"},
+        }
+
+    def test_empty_dataclass(self):
+        assert safe_asdict(_EmptyCfg()) == {}
+
+    def test_non_dataclass_raises(self):
+        with pytest.raises(TypeError, match="Expected a dataclass"):
+            safe_asdict({"not": "a dataclass"})
+
+    def test_dataclass_class_rejected(self):
+        """A dataclass *type* (not instance) must be rejected."""
+        with pytest.raises(TypeError, match="Expected a dataclass"):
+            safe_asdict(_FakeCfg)
+
+    @pytest.mark.parametrize("bad", [None, 42, "str", [1, 2]])
+    def test_primitive_inputs_rejected(self, bad: Any):
+        with pytest.raises(TypeError, match="Expected a dataclass"):
+            safe_asdict(bad)
diff --git a/tests/v1/test_kv_cache_groups.py b/tests/v1/test_kv_cache_groups.py
new file mode 100644
index 0000000..b7a0f51
--- /dev/null
+++ b/tests/v1/test_kv_cache_groups.py
@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+import msgspec
+
+# First Party
+from lmcache.v1.multiprocess.group_view import (
+    EngineGroupInfo,
+    expand_engine_block_ids,
+    get_engine_group_indices,
+    num_engine_group_infos,
+    num_engine_groups,
+    slice_block_ids_per_group,
+)
+
+
+def test_engine_group_infos_default_to_one_engine_group():
+    assert num_engine_groups([]) == 1
+    assert num_engine_group_infos([]) == 1
+    assert get_engine_group_indices([], 1) is None
+
+
+def test_engine_group_infos_build_per_layer_engine_group_indices():
+    groups = [
+        EngineGroupInfo(0, (0, 2)),
+        EngineGroupInfo(1, (1, 3)),
+    ]
+
+    assert num_engine_groups(groups) == 2
+    assert num_engine_group_infos(groups) == 2
+    assert get_engine_group_indices(groups, 4) == [0, 1, 0, 1]
+
+
+def test_engine_group_infos_expand_engine_block_ids():
+    groups = [
+        EngineGroupInfo(0, (0, 2)),
+        EngineGroupInfo(0, (4,)),
+        EngineGroupInfo(1, (1, 3)),
+    ]
+
+    assert expand_engine_block_ids(groups, [[10, 11], [20, 21]]) == [
+        [10, 11],
+        [10, 11],
+        [20, 21],
+    ]
+
+
+def test_engine_group_info_old_payload_defaults_sw_size():
+    """A pre-sw_size_tokens msgspec payload decodes with the -1 default."""
+    old_payload = {"engine_group_id": 0, "layer_indices": (0, 1)}
+
+    decoded = msgspec.msgpack.decode(
+        msgspec.msgpack.encode(old_payload), type=EngineGroupInfo
+    )
+
+    assert decoded.sw_size_tokens == -1
+
+
+def test_engine_group_infos_msgspec_round_trip():
+    """The groups encode/decode losslessly via msgspec (the IPC path)."""
+    groups = [
+        EngineGroupInfo(0, (0, 2)),
+        EngineGroupInfo(1, (1, 3), sw_size_tokens=128),
+    ]
+
+    decoded = msgspec.msgpack.decode(
+        msgspec.msgpack.encode(groups), type=list[EngineGroupInfo]
+    )
+
+    assert decoded == groups
+
+
+def test_engine_group_infos_exclude_uncovered_layers():
+    """Layers not referenced by any group are tagged EXCLUDED_ENGINE_GROUP.
+
+    Cross-layer KV-sharing layers (e.g. google/gemma-4-E4B-it) alias a target
+    owner's KV cache and are intentionally left out of every group; downstream
+    grouping skips them rather than treating partial coverage as an error.
+    """
+    # First Party
+    from lmcache.v1.kv_layer_groups import EXCLUDED_ENGINE_GROUP
+
+    groups = [
+        EngineGroupInfo(0, (0,)),
+        EngineGroupInfo(1, (1,)),
+    ]
+
+    # Layer 2 is not covered by any group -> excluded, not an error.
+    assert get_engine_group_indices(groups, 3) == [0, 1, EXCLUDED_ENGINE_GROUP]
+
+
+def test_engine_group_infos_reject_out_of_range_layer():
+    groups = [EngineGroupInfo(0, (0, 5))]
+
+    try:
+        get_engine_group_indices(groups, 3)
+    except ValueError as exc:
+        assert "outside registered layer range" in str(exc)
+    else:
+        raise AssertionError("Expected out-of-range layer index to fail")
+
+
+def test_slice_block_ids_uniform_block_sizes():
+    """Groups sharing one tokens_per_block slice to equal counts."""
+    allocated = {0: list(range(16)), 1: list(range(100, 116))}
+    sliced = slice_block_ids_per_group(
+        allocated,
+        group_tokens_per_block=[16, 16],
+        start_token_idx=0,
+        end_token_idx=256,
+    )
+    assert sliced == [list(range(16)), list(range(100, 116))]
+
+
+def test_slice_block_ids_heterogeneous_block_sizes():
+    """A tokens_per_block-32 group gets half the IDs of a 16 group.
+
+    The range [0, 256) spans 256 tokens: the tokens_per_block-16 group
+    needs 16 block IDs, the tokens_per_block-32 group 8, for the same
+    token span.
+    """
+    allocated = {0: list(range(16)), 1: list(range(8))}
+    sliced = slice_block_ids_per_group(
+        allocated,
+        group_tokens_per_block=[16, 32],
+        start_token_idx=0,
+        end_token_idx=256,
+    )
+    assert sliced == [list(range(16)), list(range(8))]
+
+
+def test_slice_block_ids_smaller_than_base_block_sizes():
+    """Groups with tiny paged chunks (e.g. DeepSeek V4 compressor state,
+    tokens_per_block 4/8) get proportionally more IDs over one token span."""
+    allocated = {0: [0], 1: list(range(64)), 2: list(range(32))}
+    sliced = slice_block_ids_per_group(
+        allocated,
+        group_tokens_per_block=[256, 4, 8],
+        start_token_idx=0,
+        end_token_idx=256,
+    )
+    assert sliced == [[0], list(range(64)), list(range(32))]
+
+
+def test_slice_block_ids_nonzero_start_offset():
+    """Start/end token offsets are divided per group by tokens_per_block."""
+    allocated = {0: list(range(32)), 1: list(range(16))}
+    sliced = slice_block_ids_per_group(
+        allocated,
+        group_tokens_per_block=[16, 32],
+        start_token_idx=256,
+        end_token_idx=512,
+    )
+    assert sliced == [list(range(16, 32)), list(range(8, 16))]
+
+
+def test_slice_block_ids_missing_group_yields_empty():
+    """A group with no allocated block IDs slices to an empty list."""
+    allocated = {0: list(range(16))}  # group 1 absent
+    sliced = slice_block_ids_per_group(
+        allocated,
+        group_tokens_per_block=[16, 16],
+        start_token_idx=0,
+        end_token_idx=256,
+    )
+    assert sliced == [list(range(16)), []]
+
+
+def test_slice_block_ids_misaligned_range_raises():
+    """A range that is not a whole number of a group's chunks is rejected."""
+    allocated = {0: list(range(8)), 1: list(range(8))}
+    # group 1 tokens_per_block 48; end=128 is not a multiple of 48.
+    try:
+        slice_block_ids_per_group(
+            allocated,
+            group_tokens_per_block=[16, 48],
+            start_token_idx=0,
+            end_token_idx=128,
+        )
+    except ValueError as exc:
+        assert "does not align" in str(exc)
+    else:
+        raise AssertionError("Expected misaligned range to fail")
diff --git a/tests/v1/test_kv_layer_groups_manager.py b/tests/v1/test_kv_layer_groups_manager.py
new file mode 100644
index 0000000..3517599
--- /dev/null
+++ b/tests/v1/test_kv_layer_groups_manager.py
@@ -0,0 +1,677 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from collections.abc import Sequence
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.kv_layer_groups import (
+    EXCLUDED_ENGINE_GROUP,
+    KernelGroupIdentity,
+    KernelGroupInfo,
+    KVLayerGroupInfo,
+    KVLayerGroupsManager,
+    LayerGroupIdentity,
+    ObjectGroupInfo,
+    format_kvcache_shape_spec,
+    group_layers_by_identity,
+    parse_kvcache_shape_spec,
+)
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available(), reason="PageBufferShapeDesc requires CUDA build"
+)
+
+
+def _build_manager(
+    tensors: list[torch.Tensor],
+    *,
+    engine_group_infos: Sequence[EngineGroupInfo] = (),
+    separate_object_groups: bool = False,
+) -> KVLayerGroupsManager:
+    """Build a manager using the per-layer NHD format.
+
+    Tensors in these tests have shape ``[2, NB, BS, NH, HS]`` — the
+    canonical vLLM flash-attention per-layer NHD layout matched by
+    ``GPUKVFormat.NL_X_TWO_NB_BS_NH_HS``. ``bs`` and ``nb`` are discovered
+    per-layer from the tensor shapes, so callers pass neither.
+    """
+    # First Party
+    import lmcache.c_ops as lmc_ops
+
+    return KVLayerGroupsManager(
+        tensors,
+        engine_kv_formats=[lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS] * len(tensors),
+        engine_group_infos=engine_group_infos,
+        separate_object_groups=separate_object_groups,
+    )
+
+
+class TestKVLayerGroupsManager:
+    """Tests for KVLayerGroupsManager construction and lookups."""
+
+    def test_build_empty(self):
+        manager = _build_manager([])
+        assert manager.kernel_groups == []
+
+    def test_build_single_layer(self):
+        tensors = [torch.randn(2, 32, 256, 8, 64, dtype=torch.float16)]
+        manager = _build_manager(tensors)
+
+        assert len(manager.kernel_groups) == 1
+        group = manager.kernel_groups[0]
+        assert isinstance(group, KVLayerGroupInfo)
+        assert group.layer_indices == [0]
+        assert group.shape_desc.kv_size == 2
+        assert group.shape_desc.nh == 8
+        assert group.shape_desc.hs == 64
+        assert group.shape_desc.nl == 1
+        assert group.shape_desc.nb == 32
+        assert group.shape_desc.bs == 256
+        assert group.dtype == torch.float16
+
+    def test_build_mixed_formats_per_group(self):
+        """Mixed-format shape: a K+V group and a key-only MLA group are shaped
+        with their own per-layer formats (kv_size 2 and 1), not one shared
+        format -- the server-side per-group path."""
+        # First Party
+        import lmcache.c_ops as lmc_ops
+
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.bfloat16),  # K+V (rank-5)
+            torch.randn(32, 256, 128, dtype=torch.bfloat16),  # MLA key-only (rank-3)
+        ]
+        manager = KVLayerGroupsManager(
+            tensors,
+            engine_kv_formats=[
+                lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+                lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+            ],
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,)),
+                EngineGroupInfo(1, (1,)),
+            ],
+        )
+
+        groups = manager.kernel_groups
+        assert len(groups) == 2
+        by_group = {g.engine_group_idx: g for g in groups}
+        assert by_group[0].shape_desc.kv_size == 2  # K+V main cache
+        assert by_group[0].shape_desc.nh == 8
+        assert by_group[1].shape_desc.kv_size == 1  # key-only MLA index cache
+        assert by_group[1].shape_desc.nh == 1
+        assert by_group[1].shape_desc.hs == 128
+        # Each kernel group persists its own format for the transfer path.
+        assert (
+            by_group[0].engine_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+        )
+        assert by_group[1].engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+
+    def test_build_multiple_layers_same_shape(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16) for _ in range(3)
+        ]
+        manager = _build_manager(tensors)
+
+        assert len(manager.kernel_groups) == 1
+        group = manager.kernel_groups[0]
+        assert group.layer_indices == [0, 1, 2]
+        assert group.shape_desc.nl == 3
+        assert group.shape_desc.nh == 8
+        assert group.engine_group_idx == 0
+
+    def test_build_splits_same_shape_by_engine_group_idx(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16) for _ in range(4)
+        ]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0, 2)),
+                EngineGroupInfo(1, (1, 3)),
+            ],
+        )
+
+        assert len(manager.kernel_groups) == 2
+        groups_by_engine_group_idx = {
+            group.engine_group_idx: group for group in manager.kernel_groups
+        }
+        assert groups_by_engine_group_idx[0].layer_indices == [0, 2]
+        assert groups_by_engine_group_idx[1].layer_indices == [1, 3]
+
+    def test_build_rejects_bad_engine_group_infos(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16) for _ in range(2)
+        ]
+        with pytest.raises(ValueError, match="outside registered layer"):
+            _build_manager(
+                tensors,
+                engine_group_infos=[EngineGroupInfo(0, (2,))],
+            )
+
+    def test_build_rejects_coarse_engine_group_infos(self):
+        # One info covering two layers that split into two kernel groups
+        # (different num_heads) violates the one-info-per-kernel-group
+        # contract.
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float16),
+        ]
+        with pytest.raises(ValueError, match="engine group info"):
+            _build_manager(
+                tensors,
+                engine_group_infos=[EngineGroupInfo(0, (0, 1))],
+            )
+
+    def test_build_different_shapes(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(tensors)
+        assert len(manager.kernel_groups) == 2
+        group1, group2 = manager.kernel_groups
+        assert group1.layer_indices == [0, 2]
+        assert group1.shape_desc.nh == 8
+        assert group2.layer_indices == [1]
+        assert group2.shape_desc.nh == 16
+
+    def test_build_different_dtypes(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float32),
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(tensors)
+        assert len(manager.kernel_groups) == 2
+        group1, group2 = manager.kernel_groups
+        assert group1.layer_indices == [0, 2]
+        assert group1.dtype == torch.float16
+        assert group2.layer_indices == [1]
+        assert group2.dtype == torch.float32
+
+    def test_build_mixed_differences(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),  # nh=8, f16
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float32),  # nh=8, f32
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float16),  # nh=16, f16
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),  # nh=8, f16
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float32),  # nh=16, f32
+        ]
+        manager = _build_manager(tensors)
+        assert len(manager.kernel_groups) == 4
+
+        groups_by_key = {(g.shape_desc.nh, g.dtype): g for g in manager.kernel_groups}
+        assert groups_by_key[(8, torch.float16)].layer_indices == [0, 3]
+        assert groups_by_key[(8, torch.float32)].layer_indices == [1]
+        assert groups_by_key[(16, torch.float16)].layer_indices == [2]
+        assert groups_by_key[(16, torch.float32)].layer_indices == [4]
+
+    def test_get_shape_desc_by_group_idx(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(tensors)
+
+        sd0 = manager.get_shape_desc(0)
+        assert sd0.nh == 8
+        assert sd0.hs == 64
+        assert sd0.nl == 1
+
+        sd1 = manager.get_shape_desc(1)
+        assert sd1.nh == 16
+        assert sd1.hs == 64
+
+
+class TestParseKvcacheShapeSpec:
+    """Test cases for parse_kvcache_shape_spec function."""
+
+    def test_single_group(self):
+        """Test parsing a single group spec."""
+        groups = parse_kvcache_shape_spec("(2,1024,16,8,128):float16:32")
+        assert len(groups) == 1
+        g = groups[0]
+        assert g.num_layers == 32
+        assert g.shape_desc.kv_size == 2
+        assert g.shape_desc.nb == 1024
+        assert g.shape_desc.bs == 16
+        assert g.shape_desc.nh == 8
+        assert g.shape_desc.hs == 128
+        assert g.shape_desc.nl == 32
+        assert g.dtype == torch.float16
+        assert g.layer_indices == list(range(32))
+        # Bench bookkeeping groups carry no format (the server re-detects); the
+        # spec has no format enum and these never drive a transfer.
+        assert g.engine_kv_format is None
+
+    def test_multiple_groups(self):
+        """Test parsing multiple groups separated by semicolons."""
+        spec = "(2,1024,16,8,128):float16:30;(2,1024,16,4,64):bfloat16:2"
+        groups = parse_kvcache_shape_spec(spec)
+        assert len(groups) == 2
+
+        # First group: 30 layers
+        assert groups[0].num_layers == 30
+        assert groups[0].dtype == torch.float16
+        assert groups[0].layer_indices == list(range(30))
+
+        # Second group: 2 layers, offset by 30
+        assert groups[1].num_layers == 2
+        assert groups[1].dtype == torch.bfloat16
+        assert groups[1].shape_desc.nh == 4
+        assert groups[1].shape_desc.hs == 64
+        assert groups[1].layer_indices == [30, 31]
+
+    def test_empty_spec_raises(self):
+        """Test that empty spec raises ValueError."""
+        with pytest.raises(ValueError, match="cannot be empty"):
+            parse_kvcache_shape_spec("")
+
+    def test_invalid_format_raises(self):
+        """Test that invalid format raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid group spec"):
+            parse_kvcache_shape_spec("bad_format")
+
+    def test_unrecognized_dtype_raises(self):
+        """Test that unrecognized dtype raises with helpful message."""
+        with pytest.raises(ValueError, match="Unrecognized dtype"):
+            parse_kvcache_shape_spec("(2,1024,16,8,128):float64:32")
+
+    def test_invalid_number_raises(self):
+        """Test that non-numeric shape values raise ValueError."""
+        with pytest.raises(ValueError, match="Invalid number"):
+            parse_kvcache_shape_spec("(2,abc,16,8,128):float16:32")
+
+    def test_whitespace_handling(self):
+        """Test that whitespace around group separators is handled."""
+        groups = parse_kvcache_shape_spec(
+            " (2,1024,16,8,128):float16:4 ; (2,1024,16,4,64):bfloat16:2 "
+        )
+        assert len(groups) == 2
+        assert groups[0].num_layers == 4
+        assert groups[1].num_layers == 2
+
+    def test_no_valid_groups_raises(self):
+        """Test that spec with only separators raises."""
+        with pytest.raises(ValueError, match="No valid layer groups"):
+            parse_kvcache_shape_spec(";;;")
+
+
+class TestFormatKvcacheShapeSpec:
+    """Test cases for format_kvcache_shape_spec function."""
+
+    def test_single_group(self):
+        spec = "(2,1024,16,8,128):float16:32"
+        groups = parse_kvcache_shape_spec(spec)
+        assert format_kvcache_shape_spec(groups) == spec
+
+    def test_multiple_groups(self):
+        spec = "(2,1024,16,8,128):float16:30;(1,512,8,4,64):bfloat16:2"
+        groups = parse_kvcache_shape_spec(spec)
+        assert format_kvcache_shape_spec(groups) == spec
+
+    def test_uint8_dtype(self):
+        spec = "(2,1024,16,8,128):uint8:32"
+        groups = parse_kvcache_shape_spec(spec)
+        assert format_kvcache_shape_spec(groups) == spec
+
+    def test_round_trip_normalizes_whitespace(self):
+        """format() always produces the canonical (whitespace-free) form."""
+        messy = " (2,1024,16,8,128):float16:4 ; (2,1024,16,4,64):bfloat16:2 "
+        canonical = "(2,1024,16,8,128):float16:4;(2,1024,16,4,64):bfloat16:2"
+        assert format_kvcache_shape_spec(parse_kvcache_shape_spec(messy)) == canonical
+
+    def test_empty_groups_raises(self):
+        with pytest.raises(ValueError, match="empty"):
+            format_kvcache_shape_spec([])
+
+
+class TestValidateBlockChunkSizeConfig:
+    """Construction-time validation of the block/chunk size configuration:
+    ``tokens_per_block`` (engine KV cache spec) must pack whole
+    ``slots_per_block`` (registered tensor batch dimension), an LMCache chunk
+    must span whole paged blocks, and a sub-chunk sliding window must cover
+    whole paged blocks.
+    """
+
+    def _validate(
+        self, slots: int, tokens: int, chunk: int = 256, sw: int = -1
+    ) -> None:
+        KVLayerGroupsManager._validate_block_chunk_size_config(
+            group_idx=0,
+            slots_per_block=slots,
+            tokens_per_block=tokens,
+            lmcache_tokens_per_chunk=chunk,
+            sw_size_tokens=sw,
+        )
+
+    def test_valid_configs_pass(self):
+        self._validate(slots=16, tokens=16)
+        # slots=8 packs 2 logical tokens per physical slot (DeepSeek V4 style).
+        self._validate(slots=8, tokens=16)
+        # Sub-chunk window aligned to whole paged blocks.
+        self._validate(slots=16, tokens=16, sw=64)
+        # Big window (>= chunk) needs no sub-chunk alignment.
+        self._validate(slots=16, tokens=16, sw=1000)
+
+    def test_not_divisible_raises(self):
+        # Divisibility is enforced loudly (e.g. slots=6 does not divide 16).
+        with pytest.raises(ValueError, match="must be a multiple of"):
+            self._validate(slots=6, tokens=16)
+
+    def test_chunk_not_divisible_by_ratio_raises(self):
+        with pytest.raises(ValueError, match="lmcache_tokens_per_chunk"):
+            self._validate(slots=1, tokens=96, chunk=256)
+
+    def test_subchunk_window_not_block_aligned_raises(self):
+        # A sub-chunk window of 100 tokens does not cover whole 16-token
+        # blocks, so the transfer slot count would disagree with the kept
+        # block IDs.
+        with pytest.raises(ValueError, match="sliding window"):
+            self._validate(slots=16, tokens=16, sw=100)
+
+
+class TestKernelGroupIdentity:
+    """The grouping key is a named tuple; ``LayerGroupIdentity`` is its alias."""
+
+    def test_fields_and_alias(self):
+        # First Party
+        import lmcache.c_ops as lmc_ops
+
+        fmt = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+        ident = KernelGroupIdentity(
+            kv_size=2,
+            num_heads=8,
+            head_size=64,
+            block_size=16,
+            engine_group_idx=0,
+            dtype=torch.float16,
+            engine_kv_format=fmt,
+        )
+        assert ident.kv_size == 2
+        assert ident.num_heads == 8
+        assert ident.head_size == 64
+        assert ident.block_size == 16
+        assert ident.engine_group_idx == 0
+        assert ident.dtype == torch.float16
+        assert ident.engine_kv_format == fmt
+        assert LayerGroupIdentity is KernelGroupIdentity
+
+    def test_hashable_as_dict_key(self):
+        # First Party
+        import lmcache.c_ops as lmc_ops
+
+        fmt = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+        ident = KernelGroupIdentity(2, 8, 64, 16, 0, torch.float16, fmt)
+        assert {ident: "x"}[ident] == "x"
+
+    def test_excluded_engine_group_sentinel(self):
+        assert EXCLUDED_ENGINE_GROUP == -1
+
+    def test_format_in_identity_splits_same_geometry(self):
+        """Two layers with identical geometry but different layouts (NHD vs HND,
+        num_heads == block_size) must not merge into one kernel group: format is
+        part of the identity, so each gets its own kernel with the correct
+        layout instead of one transferring the other with the wrong axis order.
+        """
+        # First Party
+        import lmcache.c_ops as lmc_ops
+
+        # NH == BS == 16, so NHD [.., BS, NH, ..] and HND [.., NH, BS, ..] yield
+        # the same kv_size/num_heads/head_size/block_size; only axis order differs.
+        tensors = [
+            torch.randn(2, 32, 16, 16, 64, dtype=torch.float16),
+            torch.randn(2, 32, 16, 16, 64, dtype=torch.float16),
+        ]
+        groups = group_layers_by_identity(
+            tensors,
+            [
+                lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # NHD
+                lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,  # HND
+            ],
+        )
+        # Without the format in the identity these share one geometry and would
+        # have merged into a single group; with it they split into two.
+        assert len(groups) == 2
+        assert {idxs[0] for _, idxs in groups} == {0, 1}
+
+
+class TestKernelAndObjectGroups:
+    """Kernel-group accessors, deprecated aliases, and the (currently single)
+    object-group layout."""
+
+    def test_kernel_groups_match_deprecated_alias(self):
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16) for _ in range(3)
+        ]
+        manager = _build_manager(tensors)
+        # The deprecated alias must still return the live list, not a bound
+        # method (regression guard for the @property/@deprecate ordering).
+        assert isinstance(manager.kv_layer_groups, list)
+        assert manager.kernel_groups is manager.kv_layer_groups
+        assert manager.num_kernel_groups == manager.num_groups
+        assert manager.num_kernel_groups == len(manager.kernel_groups)
+        assert all(isinstance(g, KernelGroupInfo) for g in manager.kernel_groups)
+
+    def test_single_object_group_covers_all_kernel_groups(self):
+        # Two distinct kernel groups (different num_heads) still share one
+        # object group under the current single-object-group assumption.
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(tensors)
+        assert manager.num_kernel_groups == 2
+        assert manager.num_object_groups == 1
+        obj = manager.object_groups[0]
+        assert isinstance(obj, ObjectGroupInfo)
+        assert obj.kernel_group_indices == list(range(manager.num_kernel_groups))
+        assert obj.sw_size_chunks == -1
+        assert manager.get_attn_desc().num_chunks_in_sw == [-1]
+
+    def test_object_group_separation_disabled_merges_groups(self):
+        # With separation off (the default), a full-attention group and a
+        # sliding-window group still collapse into one full-attention object
+        # group, and get_attn_desc reports full attention.
+        tensors = [torch.randn(2, 32, 32, 8, 64, dtype=torch.float16) for _ in range(2)]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,)),
+                EngineGroupInfo(1, (1,), sw_size_tokens=64),
+            ],
+            separate_object_groups=False,
+        )
+        assert manager.num_kernel_groups == 2
+        assert manager.num_object_groups == 1
+        assert manager.object_groups[0].kernel_group_indices == [0, 1]
+        assert manager.get_attn_desc().num_chunks_in_sw == [-1]
+
+    def test_object_group_separation_enabled_buckets_by_window(self):
+        # With separation on, the full-attention and sliding-window kernel groups
+        # land in distinct object groups, ordered by first kernel group index,
+        # and get_attn_desc reports each group's real window.
+        tensors = [torch.randn(2, 32, 32, 8, 64, dtype=torch.float16) for _ in range(2)]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,)),
+                EngineGroupInfo(1, (1,), sw_size_tokens=64),
+            ],
+            separate_object_groups=True,
+        )
+        assert manager.num_kernel_groups == 2
+        assert manager.num_object_groups == 2
+        # Group 0: full attention (kernel group 0). Group 1: sliding window.
+        assert manager.object_groups[0].kernel_group_indices == [0]
+        assert manager.object_groups[0].sw_size_chunks == -1
+        attn_desc = manager.get_attn_desc()
+        assert attn_desc.num_chunks_in_sw[0] == -1
+        assert manager.object_groups[1].kernel_group_indices == [1]
+        assert manager.object_groups[1].sw_size_chunks >= 1
+        assert attn_desc.num_chunks_in_sw[1] == manager.object_groups[1].sw_size_chunks
+
+    def test_object_group_separation_enabled_non_hybrid_single_group(self):
+        # Even with separation on, a non-hybrid model (no sliding-window groups)
+        # yields a single full-attention object group.
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 256, 16, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(tensors, separate_object_groups=True)
+        assert manager.num_object_groups == 1
+        assert manager.get_attn_desc().num_chunks_in_sw == [-1]
+
+    def test_kernel_groups_carry_sw_size_tokens(self):
+        # Same-shape layers split by engine group; the sliding-window group's
+        # window size lands on its kernel group, the other stays -1.
+        tensors = [torch.randn(2, 32, 32, 8, 64, dtype=torch.float16) for _ in range(2)]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,)),
+                EngineGroupInfo(1, (1,), sw_size_tokens=64),
+            ],
+        )
+        assert [g.sw_size_tokens for g in manager.kernel_groups] == [-1, 64]
+
+    def test_subchunk_window_not_block_aligned_rejected(self):
+        # A 64-token window over 256-slot blocks does not cover whole blocks;
+        # construction fails loudly instead of mistransferring.
+        tensors = [torch.randn(2, 32, 256, 8, 64, dtype=torch.float16)]
+        with pytest.raises(ValueError, match="sliding window"):
+            _build_manager(
+                tensors,
+                engine_group_infos=[EngineGroupInfo(0, (0,), sw_size_tokens=64)],
+            )
+
+    def test_subchunk_sw_size_tokens(self):
+        # lmcache chunk size is 256 (default), 32-slot blocks. Sub-chunk
+        # window (64) is returned as-is; non-SW (-1) and big-SW (512) return
+        # the chunk size.
+        tensors = [
+            torch.randn(2, 32, 32, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 32, 16, 64, dtype=torch.float16),
+            torch.randn(2, 32, 32, 32, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,)),
+                EngineGroupInfo(0, (1,), sw_size_tokens=64),
+                EngineGroupInfo(0, (2,), sw_size_tokens=512),
+            ],
+        )
+        assert manager.get_subchunk_sw_size_tokens(0) == 256
+        assert manager.get_subchunk_sw_size_tokens(1) == 64
+        assert manager.get_subchunk_sw_size_tokens(2) == 256
+        # Transfer slots follow the sub-chunk window (ratio 1 here).
+        assert manager.get_slots_per_chunk_in_sw(0) == 256
+        assert manager.get_slots_per_chunk_in_sw(1) == 64
+        assert manager.get_slots_per_chunk_in_sw(2) == 256
+
+    def test_mixed_sw_kernel_groups_share_single_object_group(self):
+        # Object-level bucketing by sliding window size is not enabled yet:
+        # kernel groups with differing window sizes still land in ONE object
+        # group and get_attn_desc stays full attention.
+        tensors = [
+            torch.randn(2, 32, 32, 8, 64, dtype=torch.float16),
+            torch.randn(2, 32, 32, 16, 64, dtype=torch.float16),
+            torch.randn(2, 32, 32, 32, 64, dtype=torch.float16),
+        ]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,)),
+                EngineGroupInfo(0, (1,), sw_size_tokens=64),
+                EngineGroupInfo(0, (2,), sw_size_tokens=512),
+            ],
+        )
+        assert manager.num_object_groups == 1
+        obj = manager.object_groups[0]
+        assert obj.kernel_group_indices == list(range(manager.num_kernel_groups))
+        assert obj.sw_size_chunks == -1
+        assert manager.get_attn_desc().num_chunks_in_sw == [-1]
+
+    def test_empty_manager_has_no_groups(self):
+        # Empty registration returns early in __init__; both group lists must
+        # still be initialized (regression guard for missing _object_groups).
+        manager = _build_manager([])
+        assert manager.kernel_groups == []
+        assert manager.num_kernel_groups == 0
+        assert manager.object_groups == []
+        assert manager.num_object_groups == 0
+
+    def test_excluded_layer_left_out_of_all_groups(self):
+        # Layer 2 is referenced by no engine group info, so it is excluded entirely.
+        tensors = [
+            torch.randn(2, 32, 256, 8, 64, dtype=torch.float16) for _ in range(3)
+        ]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[EngineGroupInfo(0, (0, 1))],
+        )
+        grouped = sorted(
+            idx for group in manager.kernel_groups for idx in group.layer_indices
+        )
+        assert grouped == [0, 1]
+
+    def test_calculate_num_blocks_uncompressed(self):
+        # bs=16, compress_ratio=1 -> 256 tokens span 16 blocks.
+        tensors = [torch.randn(2, 32, 16, 8, 64, dtype=torch.float16) for _ in range(2)]
+        manager = _build_manager(tensors)
+        assert manager.calculate_num_blocks(0, 256) == 16
+
+    def test_dsv4_flash_style_mixed_compression(self):
+        # Mirrors DeepSeek-V4-Flash: one 256-token engine group whose layers
+        # have 64- and 2-slot pages (declared compress ratios 4 and 128), one
+        # 64-token SWA group and one 4-token compressor-state group (ratio 1).
+        tensors = [
+            torch.randn(2, 8, 64, 1, 64, dtype=torch.float16),
+            torch.randn(2, 8, 2, 1, 64, dtype=torch.float16),
+            torch.randn(2, 8, 64, 1, 32, dtype=torch.float16),
+            torch.randn(2, 8, 4, 1, 128, dtype=torch.float32),
+        ]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0,), tokens_per_block=256),
+                EngineGroupInfo(0, (1,), tokens_per_block=256),
+                EngineGroupInfo(1, (2,), tokens_per_block=64),
+                EngineGroupInfo(2, (3,), tokens_per_block=4),
+            ],
+        )
+        by_layer = {g.layer_indices[0]: g for g in manager.kernel_groups}
+        assert by_layer[0].tokens_per_block // by_layer[0].slots_per_block == 4
+        assert by_layer[1].tokens_per_block // by_layer[1].slots_per_block == 128
+        assert by_layer[2].tokens_per_block // by_layer[2].slots_per_block == 1
+        assert by_layer[3].tokens_per_block // by_layer[3].slots_per_block == 1
+        # 256-token LMCache chunk -> 2 physical slots in the ratio-128 group.
+        assert by_layer[1].calculate_slots(256) == 2
+        assert by_layer[0].calculate_slots(256) == 64
+
+    def test_calculate_num_blocks_compressed(self):
+        # slots_per_block=8 (tensor), tokens_per_block=16 (engine spec) ->
+        # compress_ratio=2; 256 logical tokens -> 128 physical slots ->
+        # 128 // 8 = 16 blocks.
+        tensors = [torch.randn(2, 32, 8, 8, 64, dtype=torch.float16) for _ in range(2)]
+        manager = _build_manager(
+            tensors,
+            engine_group_infos=[
+                EngineGroupInfo(0, (0, 1), tokens_per_block=16),
+            ],
+        )
+        group = manager.kernel_groups[0]
+        assert group.tokens_per_block == 16
+        assert group.slots_per_block == 8
+        assert group.tokens_per_block // group.slots_per_block == 2
+        assert manager.calculate_num_blocks(0, 256) == 16
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/tests/v1/test_manager.py b/tests/v1/test_manager.py
new file mode 100644
index 0000000..aa41a52
--- /dev/null
+++ b/tests/v1/test_manager.py
@@ -0,0 +1,559 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for LMCacheManager.
+"""
+
+# Standard
+from unittest.mock import MagicMock, patch
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.integration.base_service_factory import BaseServiceFactory
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.manager import LMCacheManager
+
+
+def _make_mock_factory(**overrides):
+    """Create a mock BaseServiceFactory with sensible defaults."""
+    factory = MagicMock(spec=BaseServiceFactory)
+    factory.get_or_create_metadata.return_value = overrides.get("metadata", None)
+    factory.get_or_create_lmcache_engine.return_value = overrides.get("engine", None)
+    factory.maybe_create_lookup_client.return_value = overrides.get(
+        "lookup_client", None
+    )
+    factory.maybe_create_lookup_server.return_value = overrides.get(
+        "lookup_server", None
+    )
+    factory.maybe_create_offload_server.return_value = overrides.get(
+        "offload_server", None
+    )
+    factory.maybe_create_runtime_plugin_launcher.return_value = overrides.get(
+        "plugin_launcher", None
+    )
+    factory.maybe_create_internal_api_server.return_value = overrides.get(
+        "api_server", None
+    )
+    factory.maybe_create_health_monitor.return_value = overrides.get(
+        "health_monitor", None
+    )
+    return factory
+
+
+class TestLMCacheManagerInit:
+    """Tests for LMCacheManager initialization."""
+
+    def test_init_stores_config(self):
+        """Test that __init__ stores config correctly."""
+        config = LMCacheEngineConfig.from_defaults()
+        connector = MagicMock()
+        factory = _make_mock_factory()
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+            connector=connector,
+        )
+
+        assert manager._config is config
+        assert manager._connector is connector
+
+    def test_init_calls_factory_methods(self):
+        """Test that __init__ calls all factory creation methods."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+
+        LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        factory.get_or_create_metadata.assert_called_once()
+        factory.get_or_create_lmcache_engine.assert_called_once()
+        factory.maybe_create_lookup_client.assert_called_once()
+        factory.maybe_create_lookup_server.assert_called_once()
+        factory.maybe_create_offload_server.assert_called_once()
+        factory.maybe_create_runtime_plugin_launcher.assert_called_once()
+        factory.maybe_create_internal_api_server.assert_called_once()
+
+    def test_init_does_not_call_health_monitor(self):
+        """Test that __init__ does NOT create health monitor (deferred to post_init)."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+
+        LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        factory.maybe_create_health_monitor.assert_not_called()
+
+
+class TestLMCacheManagerProperties:
+    """Tests for LMCacheManager property accessors."""
+
+    @pytest.fixture
+    def manager_with_mocked_init(self):
+        """Create a manager with mocked factory."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+            connector=MagicMock(),
+        )
+        return manager
+
+    def test_lmcache_engine_property(self, manager_with_mocked_init):
+        """Test lmcache_engine property returns the engine."""
+        manager = manager_with_mocked_init
+        mock_engine = MagicMock()
+        manager._lmcache_engine = mock_engine
+
+        assert manager.lmcache_engine is mock_engine
+
+    def test_lmcache_engine_metadata_property(self, manager_with_mocked_init):
+        """Test lmcache_engine_metadata property returns the metadata."""
+        manager = manager_with_mocked_init
+        mock_metadata = MagicMock()
+        manager._lmcache_engine_metadata = mock_metadata
+
+        assert manager.lmcache_engine_metadata is mock_metadata
+
+    def test_lookup_client_property(self, manager_with_mocked_init):
+        """Test lookup_client property returns the client."""
+        manager = manager_with_mocked_init
+        mock_client = MagicMock()
+        manager._lookup_client = mock_client
+
+        assert manager.lookup_client is mock_client
+
+    def test_lookup_server_property(self, manager_with_mocked_init):
+        """Test lookup_server property returns the server."""
+        manager = manager_with_mocked_init
+        mock_server = MagicMock()
+        manager._lookup_server = mock_server
+
+        assert manager.lookup_server is mock_server
+
+    def test_offload_server_property(self, manager_with_mocked_init):
+        """Test offload_server property returns the server."""
+        manager = manager_with_mocked_init
+        mock_server = MagicMock()
+        manager._offload_server = mock_server
+
+        assert manager.offload_server is mock_server
+
+    def test_config_property(self, manager_with_mocked_init):
+        """Test config property returns the config."""
+        manager = manager_with_mocked_init
+        assert manager.config is manager._config
+
+
+class TestLMCacheManagerStart:
+    """Tests for LMCacheManager start method."""
+
+    def test_start_calls_api_server_start(self):
+        """Test start_services() calls api_server.start() when api_server exists."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_api_server = MagicMock()
+        mock_plugin_launcher = MagicMock()
+        factory = _make_mock_factory(
+            api_server=mock_api_server,
+            plugin_launcher=mock_plugin_launcher,
+        )
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        manager.start_services()
+
+        mock_api_server.start.assert_called_once()
+        mock_plugin_launcher.launch_plugins.assert_called_once()
+
+    def test_start_handles_none_api_server(self):
+        """Test start_services() handles None api_server gracefully."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        # Should not raise any exception
+        manager.start_services()
+
+
+class TestLMCacheManagerPostInit:
+    """Tests for LMCacheManager post_init method."""
+
+    def test_post_init_without_engine(self):
+        """Test post_init initializes health monitor when engine is None."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_health_monitor = MagicMock()
+        factory = _make_mock_factory(health_monitor=mock_health_monitor)
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        manager.post_init()
+
+        # Health monitor should still be created even without engine
+        factory.maybe_create_health_monitor.assert_called_once_with(
+            lmcache_manager=manager
+        )
+
+    def test_post_init_with_engine_and_async_loading(self):
+        """Test post_init calls engine.post_init with async_lookup_server."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.enable_async_loading = True
+        mock_engine = MagicMock()
+        factory = _make_mock_factory(engine=mock_engine)
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        manager.post_init()
+
+        # When lookup_server is None, engine.post_init should be called
+        # with async_lookup_server=None
+        mock_engine.post_init.assert_called_once_with(async_lookup_server=None)
+
+    def test_post_init_with_engine_and_async_server(self):
+        """Test post_init calls engine.post_init when async lookup server exists."""
+        # First Party
+        from lmcache.v1.lookup_client.lmcache_async_lookup_client import (
+            LMCacheAsyncLookupServer,
+        )
+
+        config = LMCacheEngineConfig.from_defaults()
+        config.enable_async_loading = True
+        mock_engine = MagicMock()
+        mock_lookup_server = MagicMock(spec=LMCacheAsyncLookupServer)
+        factory = _make_mock_factory(
+            engine=mock_engine,
+            lookup_server=mock_lookup_server,
+        )
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        manager.post_init()
+
+        # When lookup_server is LMCacheAsyncLookupServer, it should be passed
+        mock_engine.post_init.assert_called_once_with(
+            async_lookup_server=mock_lookup_server
+        )
+
+
+class TestLMCacheManagerShutdown:
+    """Tests for LMCacheManager shutdown method."""
+
+    def test_shutdown_closes_all_components(self):
+        """Test stop_services() closes all components."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_offload = MagicMock()
+        mock_plugin = MagicMock()
+        mock_api = MagicMock()
+        mock_lookup_server = MagicMock()
+        mock_lookup_client = MagicMock()
+        factory = _make_mock_factory(
+            offload_server=mock_offload,
+            plugin_launcher=mock_plugin,
+            api_server=mock_api,
+            lookup_server=mock_lookup_server,
+            lookup_client=mock_lookup_client,
+        )
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        with patch("lmcache.v1.manager.LMCacheEngineBuilder") as mock_builder:
+            manager.stop_services()
+
+            # Verify all components were closed
+            mock_offload.close.assert_called_once()
+            mock_plugin.stop_plugins.assert_called_once()
+            mock_api.stop.assert_called_once()
+            mock_lookup_server.close.assert_called_once()
+            mock_lookup_client.close.assert_called_once()
+            mock_builder.destroy.assert_called_once()
+
+    def test_shutdown_handles_none_components(self):
+        """Test stop_services() handles None components gracefully."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        with patch("lmcache.v1.manager.LMCacheEngineBuilder"):
+            # Should not raise any exception
+            manager.stop_services()
+
+    def test_shutdown_handles_component_errors(self):
+        """Test stop_services() handles errors from components gracefully."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_offload = MagicMock()
+        mock_offload.close.side_effect = RuntimeError("Test error")
+        mock_lookup_client = MagicMock()
+        factory = _make_mock_factory(
+            offload_server=mock_offload,
+            lookup_client=mock_lookup_client,
+        )
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        with patch("lmcache.v1.manager.LMCacheEngineBuilder"):
+            # Should not raise exception, but should continue shutdown
+            manager.stop_services()
+
+            # lookup_client should still be closed even if offload_server failed
+            mock_lookup_client.close.assert_called_once()
+
+
+class TestLMCacheManagerHelpers:
+    """Tests for LMCacheManager helper methods."""
+
+    def test_need_gpu_interm_buffer_returns_not_enable_pd(self):
+        """Test _need_gpu_interm_buffer returns opposite of enable_pd."""
+        config = LMCacheEngineConfig.from_defaults()
+        config.enable_pd = False
+        # First Party
+        from lmcache.v1.gpu_connector.utils import need_gpu_interm_buffer
+
+        assert need_gpu_interm_buffer(config) is True
+
+        config.enable_pd = True
+        assert need_gpu_interm_buffer(config) is False
+
+
+class TestLMCacheManagerValidation:
+    """Tests for validate_mla_config (now in utils)."""
+
+    def test_validate_mla_config_raises_on_wrong_serde(self):
+        """Test validate_mla_config raises error for non-naive serde with MLA."""
+        # First Party
+        from lmcache.integration.vllm.utils import validate_mla_config
+
+        config = LMCacheEngineConfig.from_defaults()
+        config.remote_serde = "cachegen"
+
+        with pytest.raises(ValueError, match="MLA only works with naive serde mode"):
+            validate_mla_config(config, use_mla=True)
+
+    def test_validate_mla_config_raises_on_layerwise_with_blending(self):
+        """Test validate_mla_config raises with MLA + layerwise + blending."""
+        # First Party
+        from lmcache.integration.vllm.utils import validate_mla_config
+
+        config = LMCacheEngineConfig.from_defaults()
+        config.remote_serde = "naive"
+        config.use_layerwise = True
+        config.enable_blending = True
+
+        with pytest.raises(ValueError, match="MLA with Cacheblend"):
+            validate_mla_config(config, use_mla=True)
+
+
+class TestLMCacheManagerCalculateDraftLayers:
+    """Tests for calculate_draft_layers (now in utils)."""
+
+    def test_calculate_draft_layers_no_speculative_config(self):
+        """Test returns 0 when no speculative_config."""
+        # First Party
+        from lmcache.integration.vllm.utils import calculate_draft_layers
+
+        vllm_config = MagicMock()
+        vllm_config.speculative_config = None
+
+        assert calculate_draft_layers(vllm_config) == 0
+
+    def test_calculate_draft_layers_deepseek_mtp(self):
+        """Test returns correct layers for deepseek_mtp method."""
+        # First Party
+        from lmcache.integration.vllm.utils import calculate_draft_layers
+
+        vllm_config = MagicMock()
+        vllm_config.speculative_config = MagicMock()
+        vllm_config.speculative_config.method = "deepseek_mtp"
+        vllm_config.model_config = MagicMock()
+        vllm_config.model_config.hf_config = MagicMock()
+        vllm_config.model_config.hf_config.num_nextn_predict_layers = 3
+
+        assert calculate_draft_layers(vllm_config) == 3
+
+
+class TestLMCacheManagerInitFailure:
+    """Tests for LMCacheManager initialization failure handling."""
+
+    def test_init_components_exception_makes_unhealthy(self):
+        """Test that exception during factory calls makes manager unhealthy."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+        factory.get_or_create_metadata.side_effect = RuntimeError("Test init failure")
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        # Verify through is_healthy API
+        assert manager.is_healthy() is False
+
+    def test_post_init_skipped_when_init_failed(self):
+        """Test that post_init marks engine unhealthy when init failed."""
+        config = LMCacheEngineConfig.from_defaults()
+        factory = _make_mock_factory()
+        factory.get_or_create_metadata.side_effect = RuntimeError("Test init failure")
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        mock_engine = MagicMock()
+        manager._lmcache_engine = mock_engine
+
+        manager.post_init()
+
+        # Engine should be marked as init failed
+        mock_engine.mark_init_failed.assert_called_once()
+        # Manager should report unhealthy
+        assert manager.is_healthy() is False
+
+    def test_post_init_exception_makes_unhealthy(self):
+        """Test that exception during post_init makes system unhealthy."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_engine = MagicMock()
+        mock_engine.post_init.side_effect = RuntimeError("Test post_init failure")
+        factory = _make_mock_factory(engine=mock_engine)
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        manager.post_init()
+
+        # Verify engine was marked as failed
+        mock_engine.mark_init_failed.assert_called_once()
+        # Manager should report unhealthy
+        assert manager.is_healthy() is False
+
+    def test_unhealthy_engine_makes_manager_unhealthy(self):
+        """Test that manager is unhealthy when engine is unhealthy."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_engine = MagicMock()
+        mock_engine.is_healthy.return_value = False
+        factory = _make_mock_factory(engine=mock_engine)
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        assert manager.is_healthy() is False
+
+    def test_healthy_when_all_components_healthy(self):
+        """Test that manager is healthy when all components are healthy."""
+        config = LMCacheEngineConfig.from_defaults()
+        mock_engine = MagicMock()
+        mock_engine.is_healthy.return_value = True
+        factory = _make_mock_factory(engine=mock_engine)
+
+        manager = LMCacheManager(
+            config=config,
+            service_factory=factory,
+        )
+
+        mock_health_monitor = MagicMock()
+        mock_health_monitor.is_healthy.return_value = True
+        manager._health_monitor = mock_health_monitor
+
+        assert manager.is_healthy() is True
+
+
+class TestLMCacheEngineInitFailure:
+    """Tests for LMCacheEngine init failure behavior on lookup/retrieve."""
+
+    def test_lookup_returns_zero_when_init_failed(self):
+        """Test that lookup returns 0 when engine is marked as init failed."""
+        # First Party
+        from lmcache.v1.cache_engine import LMCacheEngine
+
+        engine = MagicMock(spec=LMCacheEngine)
+        engine._init_failed = False
+        engine._health_monitor = None
+
+        # Attach real methods to the mock
+        engine.mark_init_failed = LMCacheEngine.mark_init_failed.__get__(
+            engine, LMCacheEngine
+        )
+        engine.is_healthy = LMCacheEngine.is_healthy.__get__(engine, LMCacheEngine)
+
+        # Call mark_init_failed and verify is_healthy returns False
+        engine.mark_init_failed("Test reason")
+        assert engine.is_healthy() is False
+
+    def test_retrieve_returns_empty_mask_when_init_failed(self):
+        """Test retrieve returns all-False mask when engine init failed."""
+        # First Party
+        from lmcache.v1.cache_engine import LMCacheEngine
+
+        engine = MagicMock(spec=LMCacheEngine)
+        engine._init_failed = False
+        engine._health_monitor = None
+
+        # Attach real methods to the mock
+        engine.mark_init_failed = LMCacheEngine.mark_init_failed.__get__(
+            engine, LMCacheEngine
+        )
+        engine.is_healthy = LMCacheEngine.is_healthy.__get__(engine, LMCacheEngine)
+
+        # Mark as init failed and verify is_healthy returns False
+        # (which would cause retrieve to return all-False mask)
+        engine.mark_init_failed("Test reason")
+        assert engine.is_healthy() is False
+
+    def test_mark_init_failed_makes_engine_unhealthy(self):
+        """Test that mark_init_failed makes engine report unhealthy."""
+        # First Party
+        from lmcache.v1.cache_engine import LMCacheEngine
+
+        engine = MagicMock(spec=LMCacheEngine)
+        engine._init_failed = False
+        engine._health_monitor = None
+
+        # Attach real methods to the mock
+        engine.mark_init_failed = LMCacheEngine.mark_init_failed.__get__(
+            engine, LMCacheEngine
+        )
+        engine.is_healthy = LMCacheEngine.is_healthy.__get__(engine, LMCacheEngine)
+
+        # Verify initially healthy
+        assert engine.is_healthy() is True
+
+        # Call the method under test
+        engine.mark_init_failed("Test reason")
+
+        # Assert on the outcome
+        assert engine.is_healthy() is False
diff --git a/tests/v1/test_mem_kernels.py b/tests/v1/test_mem_kernels.py
new file mode 100644
index 0000000..dcf4975
--- /dev/null
+++ b/tests/v1/test_mem_kernels.py
@@ -0,0 +1,971 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List
+import random
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+
+if not torch.cuda.is_available():
+    pytest.skip(
+        "CUDA is not available, skipping the test",
+        allow_module_level=True,
+    )
+
+# First Party
+if torch.cuda.is_available():
+    try:
+        # First Party
+        import lmcache.c_ops as lmc_ops
+    except ImportError:
+        lmc_ops = None
+else:
+    lmc_ops = None
+
+# Mock c_ops when not available
+if lmc_ops is None:
+
+    class MockEngineKVFormat:
+        NL_X_TWO_NB_BS_NH_HS = 0
+        NL_X_NB_TWO_BS_NH_HS = 1
+        NL_X_NB_BS_HS = 2
+        NL_X_TWO_NB_NH_BS_HS = 3
+        NL_X_NB_TWO_NH_BS_HS = 4
+
+    class MockTransferDirection:
+        H2D = 0
+        D2H = 1
+
+    class MockCOps:
+        EngineKVFormat = MockEngineKVFormat
+        GPUKVFormat = MockEngineKVFormat
+        TransferDirection = MockTransferDirection
+
+    lmc_ops = MockCOps()
+
+# Local
+from .utils import (
+    check_mem_obj_equal,
+    check_paged_kv_cache_equal,
+    generate_kv_cache_paged,
+    generate_kv_cache_paged_list_tensors,
+)
+
+
+def _tuple_kv_to_blob(
+    kv_tensors,
+) -> torch.Tensor:
+    k_temp = []
+    v_temp = []
+    for kv_layer in kv_tensors:
+        k_temp.append(kv_layer[0])
+        v_temp.append(kv_layer[1])
+    k_tensor_blob = torch.stack(k_temp)
+    v_tensor_blob = torch.stack(v_temp)
+
+    # kv_tensors: [num_layer, 2, num_tok, num_kv_head, head_size]
+    kv_tensors_flatten = torch.stack((k_tensor_blob, v_tensor_blob))
+    kv_tensors_flatten = kv_tensors_flatten.permute([1, 0, 2, 3, 4])
+
+    return kv_tensors_flatten
+
+
+def _slice_kv_at(
+    start_idx: int,
+    kv_tensors: torch.Tensor,
+    chunk_size: int,
+) -> List[torch.Tensor]:
+    return [
+        x.contiguous()
+        for x in list(
+            torch.split(
+                kv_tensors[:, :, start_idx:, ...],
+                chunk_size,
+                dim=2,
+            )
+        )
+    ]
+
+
+@pytest.mark.parametrize("num_tokens", [256, 500, 1024, 8000])
+def test_extract_and_load_back(num_tokens):
+    device = "cuda"
+
+    num_blocks = 1000
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    num_layers = 32
+    dtype = torch.bfloat16
+    kv_cache = generate_kv_cache_paged(num_blocks, device, block_size, dtype)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    pinned_cpu_size = 4 * 1024 * 1024 * 1024  # 4GB
+    mem_allocator = PinMemoryAllocator(pinned_cpu_size)
+
+    # Old extract
+    kv_tuple_list = []
+    memory_obj_old_list = []
+    chunk_size = 256
+    start_event = torch.cuda.Event(enable_timing=True)
+    end_event = torch.cuda.Event(enable_timing=True)
+    start_event.record()
+    for layer_id in range(num_layers):
+        key_cache = kv_cache[layer_id][0].reshape(-1, num_heads, head_size)
+        value_cache = kv_cache[layer_id][1].reshape(-1, num_heads, head_size)
+        kv_tuple_list.append((key_cache[slot_mapping], value_cache[slot_mapping]))
+    kv_blob = _tuple_kv_to_blob(kv_tuple_list)
+    kv_chunked = _slice_kv_at(0, kv_blob, chunk_size)
+    for chunk_id, chunk in enumerate(kv_chunked):
+        mem_obj_shape = torch.Size(
+            [2, num_layers, chunk.shape[2], num_heads * head_size]
+        )
+
+        memory_obj_old = mem_allocator.allocate(mem_obj_shape, dtype)
+        chunk = chunk.contiguous()
+        for layer_id in range(num_layers):
+            memory_obj_old.tensor[0, layer_id].copy_(
+                chunk[layer_id, 0].reshape(-1, 1024)
+            )
+            memory_obj_old.tensor[1, layer_id].copy_(
+                chunk[layer_id, 1].reshape(-1, 1024)
+            )
+        memory_obj_old_list.append(memory_obj_old)
+    end_event.record()
+    torch.cuda.synchronize()
+    elapsed_time_ms = start_event.elapsed_time(end_event)
+    print("Old extract time: ", elapsed_time_ms / 1000)
+
+    # New extract (zero-copy kernels)
+    memory_obj_new_list = []
+    start_event = torch.cuda.Event(enable_timing=True)
+    end_event = torch.cuda.Event(enable_timing=True)
+    start_event.record()
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        mem_obj_shape = torch.Size(
+            [2, num_layers, len(slot_mapping_temp), num_heads * head_size]
+        )
+
+        memory_obj_new = mem_allocator.allocate(mem_obj_shape, dtype)
+        for layer_id in range(num_layers):
+            lmc_ops.load_and_reshape_flash(
+                memory_obj_new.tensor,
+                kv_cache[layer_id][0],
+                kv_cache[layer_id][1],
+                slot_mapping_temp,
+                layer_id,
+            )
+        memory_obj_new_list.append(memory_obj_new)
+    end_event.record()
+    # wait for all the operations to finish
+    torch.cuda.synchronize()
+    elapsed_time_ms = start_event.elapsed_time(end_event)
+    print("New extract time: ", elapsed_time_ms / 1000)
+    check_mem_obj_equal(
+        memory_obj_old_list,
+        memory_obj_new_list,
+    )
+
+    # Generate new paged kv_cache
+    kv_cache_new = generate_kv_cache_paged(num_blocks, device, block_size, dtype)
+
+    # New load back (zero-copy kernels)
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        memory_obj_new = memory_obj_new_list[chunk_id]
+        for layer_id in range(num_layers):
+            lmc_ops.reshape_and_cache_back_flash(
+                memory_obj_new.tensor,
+                kv_cache_new[layer_id][0],
+                kv_cache_new[layer_id][1],
+                slot_mapping_temp,
+                layer_id,
+            )
+    check_paged_kv_cache_equal(
+        kv_cache,
+        kv_cache_new,
+        slot_mapping,
+    )
+
+    mem_allocator.close()
+
+
+@pytest.mark.parametrize("num_tokens", [256, 500, 1024, 8000])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+    ],
+)
+def test_multi_layer_kernel(num_tokens, engine_kv_format):
+    device = "cuda"
+
+    num_blocks = 1000
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    chunk_size = 256
+    num_layers = 32
+    dtype = torch.bfloat16
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype, engine_kv_format=engine_kv_format
+    )
+    # old deprecated kernels only handle vllm non-MLA flash attention format
+    if engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS:
+        kv_cache_force_old = [
+            kv_layer.clone().permute(1, 0, 2, 3, 4).contiguous()
+            for kv_layer in kv_cache
+        ]
+    else:
+        kv_cache_force_old = kv_cache
+    page_buffer_size = num_blocks * block_size
+
+    slot_mapping = random.sample(range(0, page_buffer_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    pinned_cpu_size = 4 * 1024 * 1024 * 1024  # 4GB
+    mem_allocator = PinMemoryAllocator(pinned_cpu_size)
+
+    # layer by layer extract
+    memory_obj_old_list = []
+    start_event = torch.cuda.Event(enable_timing=True)
+    end_event = torch.cuda.Event(enable_timing=True)
+    start_event.record()
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        mem_obj_shape = torch.Size(
+            [2, num_layers, len(slot_mapping_temp), num_heads * head_size]
+        )
+
+        memory_obj_old = mem_allocator.allocate(mem_obj_shape, dtype)
+        for layer_id in range(num_layers):
+            lmc_ops.load_and_reshape_flash(
+                memory_obj_old.tensor,
+                kv_cache_force_old[layer_id][0],
+                kv_cache_force_old[layer_id][1],
+                slot_mapping_temp,
+                layer_id,
+            )
+        memory_obj_old_list.append(memory_obj_old)
+    end_event.record()
+    # wait for all the operations to finish
+    torch.cuda.synchronize()
+    elapsed_time_ms = start_event.elapsed_time(end_event)
+    print("Old extract time: ", elapsed_time_ms / 1000)
+
+    # New extract with multi layer kernel
+    kv_cache_pointers = torch.empty(
+        num_layers, dtype=torch.int64, device="cpu", pin_memory=True
+    )
+    for i in range(num_layers):
+        kv_cache_pointers[i] = kv_cache[i].data_ptr()
+
+    memory_obj_new_list = []
+    start_event = torch.cuda.Event(enable_timing=True)
+    end_event = torch.cuda.Event(enable_timing=True)
+    start_event.record()
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        mem_obj_shape = torch.Size(
+            [2, num_layers, len(slot_mapping_temp), num_heads * head_size]
+        )
+
+        memory_obj_new = mem_allocator.allocate(mem_obj_shape, dtype)
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj_new.tensor,
+            kv_cache_pointers,
+            slot_mapping_temp,
+            kv_cache[0].device,
+            page_buffer_size,
+            lmc_ops.TransferDirection.D2H,
+            engine_kv_format,
+            block_size,
+        )
+        memory_obj_new_list.append(memory_obj_new)
+
+    end_event.record()
+    # wait for all the operations to finish
+    torch.cuda.synchronize()
+    elapsed_time_ms = start_event.elapsed_time(end_event)
+    print("New extract time: ", elapsed_time_ms / 1000)
+
+    check_mem_obj_equal(
+        memory_obj_old_list,
+        memory_obj_new_list,
+    )
+
+    # Generate new paged kv_cache
+    kv_cache_new = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype, engine_kv_format=engine_kv_format
+    )
+
+    kv_cache_pointers_new = torch.empty(
+        num_layers, dtype=torch.int64, device="cpu", pin_memory=True
+    )
+    for i in range(num_layers):
+        kv_cache_pointers_new[i] = kv_cache_new[i].data_ptr()
+
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        memory_obj_new = memory_obj_new_list[chunk_id]
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj_new.tensor,
+            kv_cache_pointers_new,
+            slot_mapping_temp,
+            kv_cache_new[0].device,
+            page_buffer_size,
+            lmc_ops.TransferDirection.H2D,
+            engine_kv_format,
+            block_size,
+        )
+
+    check_paged_kv_cache_equal(
+        kv_cache,
+        kv_cache_new,
+        slot_mapping,
+        engine_kv_format=engine_kv_format,
+    )
+
+    mem_allocator.close()
+
+
+@pytest.mark.parametrize("num_tokens", [256, 500, 1024, 8000])
+@pytest.mark.parametrize("head_size", [576, 66])  # Use 68 for dsv32 (132x int8)
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [lmc_ops.EngineKVFormat.NL_X_NB_BS_HS],  # vllm MLA
+)
+def test_multi_layer_kernel_use_mla(num_tokens, head_size, engine_kv_format):
+    device = "cuda"
+
+    num_blocks = 1000
+    block_size = 64
+    chunk_size = 256
+    dtype = torch.bfloat16
+    num_layers = 32
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers,
+        head_size,
+        engine_kv_format=engine_kv_format,
+    )
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    pinned_cpu_size = 4 * 1024 * 1024 * 1024  # 4GB
+    mem_allocator = PinMemoryAllocator(pinned_cpu_size)
+
+    # layer by layer extract
+    memory_obj_old_list = []
+    start_event = torch.cuda.Event(enable_timing=True)
+    end_event = torch.cuda.Event(enable_timing=True)
+    start_event.record()
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        mem_obj_shape = torch.Size([1, num_layers, len(slot_mapping_temp), head_size])
+        memory_obj_old = mem_allocator.allocate(mem_obj_shape, dtype)
+
+        for layer_id in range(num_layers):
+            for token_idx, slot_idx in enumerate(slot_mapping_temp):
+                slot_idx = slot_idx.item()
+
+                block_idx = slot_idx // block_size
+                block_offset = slot_idx % block_size
+
+                memory_obj_old.tensor[0][layer_id][token_idx] = kv_cache[layer_id][
+                    block_idx
+                ][block_offset]
+
+        memory_obj_old_list.append(memory_obj_old)
+    end_event.record()
+    # wait for all the operations to finish
+    torch.cuda.synchronize()
+    elapsed_time_ms = start_event.elapsed_time(end_event)
+    print("Old extract time: ", elapsed_time_ms / 1000)
+
+    # New extract with multi layer kernel
+    kv_cache_pointers = torch.empty(
+        num_layers, dtype=torch.int64, device="cpu", pin_memory=True
+    )
+    for i in range(num_layers):
+        kv_cache_pointers[i] = kv_cache[i].data_ptr()
+
+    memory_obj_new_list = []
+    start_event = torch.cuda.Event(enable_timing=True)
+    end_event = torch.cuda.Event(enable_timing=True)
+    start_event.record()
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        mem_obj_shape = torch.Size([1, num_layers, len(slot_mapping_temp), head_size])
+
+        memory_obj_new = mem_allocator.allocate(mem_obj_shape, dtype)
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj_new.tensor,
+            kv_cache_pointers,
+            slot_mapping_temp,
+            kv_cache[0].device,
+            0,
+            lmc_ops.TransferDirection.D2H,
+            engine_kv_format,
+            block_size,
+        )
+        memory_obj_new_list.append(memory_obj_new)
+
+    end_event.record()
+    # wait for all the operations to finish
+    torch.cuda.synchronize()
+    elapsed_time_ms = start_event.elapsed_time(end_event)
+    print("New extract time: ", elapsed_time_ms / 1000)
+
+    for left_mem_obj, right_mem_obj in zip(
+        memory_obj_old_list, memory_obj_new_list, strict=False
+    ):
+        left_kv, right_kv = left_mem_obj.tensor[0], right_mem_obj.tensor[0]
+        right_kv = right_kv.to(left_kv.device)
+
+        assert len(left_kv.shape) == 3
+        assert len(right_kv.shape) == 3
+
+        assert (left_kv[:, :, :] == right_kv[:, :, :]).all()
+
+    # Generate new paged kv_cache
+    kv_cache_new = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers,
+        head_size,
+        engine_kv_format=engine_kv_format,
+    )
+
+    kv_cache_pointers_new = torch.empty(
+        num_layers, dtype=torch.int64, device="cpu", pin_memory=True
+    )
+    for i in range(num_layers):
+        kv_cache_pointers_new[i] = kv_cache_new[i].data_ptr()
+
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        memory_obj_new = memory_obj_new_list[chunk_id]
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj_new.tensor,
+            kv_cache_pointers_new,
+            slot_mapping_temp,
+            kv_cache_new[0].device,
+            0,
+            lmc_ops.TransferDirection.H2D,
+            engine_kv_format,
+            block_size,
+        )
+
+    for left_kv, right_kv in zip(kv_cache, kv_cache_new, strict=False):
+        assert len(left_kv.shape) == 3
+        assert len(right_kv.shape) == 3
+
+        left_reshaped = left_kv.reshape(
+            left_kv.shape[0] * left_kv.shape[1], left_kv.shape[2]
+        )
+        right_reshaped = right_kv.reshape(
+            right_kv.shape[0] * right_kv.shape[1], right_kv.shape[2]
+        )
+
+        assert (left_reshaped[slot_mapping, :] == right_reshaped[slot_mapping, :]).all()
+
+    mem_allocator.close()
+
+
+@pytest.mark.parametrize("num_tokens", [256, 500, 1024, 8000])
+@pytest.mark.parametrize("token_major", [True, False])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+    ],
+)
+def test_single_layer_kernel(num_tokens, token_major, engine_kv_format):
+    device = "cuda"
+
+    num_layers = 32
+    num_blocks = 1000
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    hidden_dim_size = num_heads * head_size
+    dtype = torch.bfloat16
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype, engine_kv_format=engine_kv_format
+    )
+    kv_cache_new = generate_kv_cache_paged_list_tensors(
+        num_blocks, device, block_size, dtype, engine_kv_format=engine_kv_format
+    )
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    if token_major:
+        tmp_gpu_buffer = torch.empty(
+            (num_tokens, 2, hidden_dim_size), dtype=dtype, device=device
+        )
+    else:
+        tmp_gpu_buffer = torch.empty(
+            (2, num_tokens, hidden_dim_size), dtype=dtype, device=device
+        )
+
+    for layer_id in range(num_layers):
+        lmc_ops.single_layer_kv_transfer(
+            tmp_gpu_buffer,
+            kv_cache[layer_id],
+            slot_mapping,
+            lmc_ops.TransferDirection.D2H,
+            engine_kv_format,
+            token_major,
+        )
+        lmc_ops.single_layer_kv_transfer(
+            tmp_gpu_buffer,
+            kv_cache_new[layer_id],
+            slot_mapping,
+            lmc_ops.TransferDirection.H2D,
+            engine_kv_format,
+            token_major,
+        )
+
+    check_paged_kv_cache_equal(
+        kv_cache,
+        kv_cache_new,
+        slot_mapping,
+        engine_kv_format=engine_kv_format,
+    )
+
+
+@pytest.mark.parametrize("num_tokens", [256, 500, 1024])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,  # vllm HND flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS,  # vllm HND flash infer
+    ],
+)
+def test_multi_layer_kernel_hnd(num_tokens, engine_kv_format):
+    """Round-trip test for HND multi-layer kernel: D2H then H2D."""
+    device = "cuda"
+
+    num_blocks = 200
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    chunk_size = 256
+    num_layers = 4
+    dtype = torch.bfloat16
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_size,
+        engine_kv_format=engine_kv_format,
+    )
+    page_buffer_size = num_blocks * block_size
+
+    slot_mapping = random.sample(range(0, page_buffer_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    pinned_cpu_size = 512 * 1024 * 1024  # 512MB
+    mem_allocator = PinMemoryAllocator(pinned_cpu_size)
+
+    # D2H: extract from paged cache into flat memory
+    kv_cache_pointers = torch.empty(
+        num_layers, dtype=torch.int64, device="cpu", pin_memory=True
+    )
+    for i in range(num_layers):
+        kv_cache_pointers[i] = kv_cache[i].data_ptr()
+
+    memory_obj_list = []
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+    for slot_mapping_temp in slot_mapping_chunked:
+        mem_obj_shape = torch.Size(
+            [2, num_layers, len(slot_mapping_temp), num_heads * head_size]
+        )
+        memory_obj = mem_allocator.allocate(mem_obj_shape, dtype)
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj.tensor,
+            kv_cache_pointers,
+            slot_mapping_temp,
+            kv_cache[0].device,
+            page_buffer_size,
+            lmc_ops.TransferDirection.D2H,
+            engine_kv_format,
+            block_size,
+            head_size=head_size,
+        )
+        memory_obj_list.append(memory_obj)
+    torch.cuda.synchronize()
+
+    # H2D: write back into a fresh paged cache
+    kv_cache_new = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_size,
+        engine_kv_format=engine_kv_format,
+    )
+    kv_cache_pointers_new = torch.empty(
+        num_layers, dtype=torch.int64, device="cpu", pin_memory=True
+    )
+    for i in range(num_layers):
+        kv_cache_pointers_new[i] = kv_cache_new[i].data_ptr()
+
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        lmc_ops.multi_layer_kv_transfer(
+            memory_obj_list[chunk_id].tensor,
+            kv_cache_pointers_new,
+            slot_mapping_temp,
+            kv_cache_new[0].device,
+            page_buffer_size,
+            lmc_ops.TransferDirection.H2D,
+            engine_kv_format,
+            block_size,
+            head_size=head_size,
+        )
+    torch.cuda.synchronize()
+
+    check_paged_kv_cache_equal(
+        kv_cache,
+        kv_cache_new,
+        slot_mapping,
+        engine_kv_format=engine_kv_format,
+    )
+    mem_allocator.close()
+
+
+@pytest.mark.parametrize("num_tokens", [256, 500, 1024])
+@pytest.mark.parametrize("token_major", [True, False])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,  # vllm HND flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS,  # vllm HND flash infer
+    ],
+)
+def test_single_layer_kernel_hnd(num_tokens, token_major, engine_kv_format):
+    """Round-trip test for HND single-layer kernel: D2H then H2D per layer."""
+    device = "cuda"
+
+    num_layers = 4
+    num_blocks = 200
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    hidden_dim_size = num_heads * head_size
+    dtype = torch.bfloat16
+
+    kv_cache = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_size,
+        engine_kv_format=engine_kv_format,
+    )
+    kv_cache_new = generate_kv_cache_paged_list_tensors(
+        num_blocks,
+        device,
+        block_size,
+        dtype,
+        num_layers=num_layers,
+        head_size=head_size,
+        engine_kv_format=engine_kv_format,
+    )
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device)
+
+    if token_major:
+        tmp_gpu_buffer = torch.empty(
+            (num_tokens, 2, hidden_dim_size), dtype=dtype, device=device
+        )
+    else:
+        tmp_gpu_buffer = torch.empty(
+            (2, num_tokens, hidden_dim_size), dtype=dtype, device=device
+        )
+
+    for layer_id in range(num_layers):
+        lmc_ops.single_layer_kv_transfer(
+            tmp_gpu_buffer,
+            kv_cache[layer_id],
+            slot_mapping,
+            lmc_ops.TransferDirection.D2H,
+            engine_kv_format,
+            token_major,
+        )
+        lmc_ops.single_layer_kv_transfer(
+            tmp_gpu_buffer,
+            kv_cache_new[layer_id],
+            slot_mapping,
+            lmc_ops.TransferDirection.H2D,
+            engine_kv_format,
+            token_major,
+        )
+
+    check_paged_kv_cache_equal(
+        kv_cache,
+        kv_cache_new,
+        slot_mapping,
+        engine_kv_format=engine_kv_format,
+    )
+
+
+def test_lmcache_memcpy_async():
+    # Register 4 memory regions and try to launch copy
+    chunk_size = 1 << 26
+    num_chunks = 4
+    dtype = torch.bfloat16
+    elements_per_chunk = chunk_size // dtype.itemsize
+
+    big_cpu_tensor = torch.rand(
+        elements_per_chunk * num_chunks, dtype=dtype, device="cpu"
+    )
+    big_gpu_tensor = torch.rand(
+        elements_per_chunk * num_chunks, dtype=dtype, device="cuda"
+    )
+
+    def check_gpu_and_cpu_equal(
+        gpu_tensor: torch.Tensor,
+        cpu_tensor: torch.Tensor,
+    ):
+        cpu_tensor_from_gpu = gpu_tensor.to("cpu")
+        assert torch.allclose(cpu_tensor_from_gpu, cpu_tensor, atol=1e-5)
+
+    rt = torch.cuda.cudart()
+
+    # Register the cpu memory
+    ptr = big_cpu_tensor.data_ptr()
+    for i in range(num_chunks):
+        rt.cudaHostRegister(ptr + i * chunk_size, chunk_size, 0)
+
+    # Launch default cuda copy
+    with pytest.raises(RuntimeError):
+        big_gpu_tensor.copy_(big_cpu_tensor, non_blocking=True)
+        torch.cuda.synchronize()
+
+    # Launc default cuda copy for a small page
+    big_gpu_tensor[: elements_per_chunk // 2].copy_(
+        big_cpu_tensor[: elements_per_chunk // 2], non_blocking=True
+    )
+    torch.cuda.synchronize()
+
+    check_gpu_and_cpu_equal(
+        big_gpu_tensor[: elements_per_chunk // 2],
+        big_cpu_tensor[: elements_per_chunk // 2],
+    )
+
+    # Positions to copy
+    # - 0.25 chunk -- 0.75 chunk
+    # - 0.75 chunk -- 1.25 chunk
+    # - 1.75 chunk -- 3.25 chunk
+    # - whole 4 chunks
+    starts = [chunk_size // 4, (3 * chunk_size) // 4, (7 * chunk_size) // 4, 0]
+    ends = [
+        (3 * chunk_size) // 4,
+        (5 * chunk_size) // 4,
+        (13 * chunk_size) // 4,
+        chunk_size * num_chunks,
+    ]
+
+    # H2D copy
+    for start, end in zip(starts, ends, strict=False):
+        # should not be equal before copy
+        with pytest.raises(AssertionError):
+            check_gpu_and_cpu_equal(
+                big_gpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+                big_cpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+            )
+
+        lmc_ops.lmcache_memcpy_async(
+            big_gpu_tensor.data_ptr() + start,
+            big_cpu_tensor.data_ptr() + start,
+            end - start,
+            lmc_ops.TransferDirection.H2D,
+            start,
+            chunk_size,
+        )
+        torch.cuda.synchronize()
+
+        check_gpu_and_cpu_equal(
+            big_gpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+            big_cpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+        )
+
+    # Reset the data in gpu
+    big_gpu_tensor = torch.rand(
+        elements_per_chunk * num_chunks, dtype=dtype, device="cuda"
+    )
+    # D2H copy
+    for start, end in zip(starts, ends, strict=False):
+        # copy from gpu to cpu
+        with pytest.raises(AssertionError):
+            check_gpu_and_cpu_equal(
+                big_gpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+                big_cpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+            )
+
+        lmc_ops.lmcache_memcpy_async(
+            big_cpu_tensor.data_ptr() + start,
+            big_gpu_tensor.data_ptr() + start,
+            end - start,
+            lmc_ops.TransferDirection.D2H,
+            start,
+            chunk_size,
+        )
+        torch.cuda.synchronize()
+
+        check_gpu_and_cpu_equal(
+            big_gpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+            big_cpu_tensor[start // dtype.itemsize : end // dtype.itemsize],
+        )
+
+    # Unregister the cpu memory
+    ptr = big_cpu_tensor.data_ptr()
+    for i in range(num_chunks):
+        rt.cudaHostUnregister(ptr + i * chunk_size)
+
+
+def test_lmcache_memcpy_async_int8_hidden132():
+    """Test lmcache_memcpy_async with int8 dtype and hidden_size=132.
+
+    hidden_size=132 means each token occupies 132 bytes, which is NOT a
+    multiple of 4 (uint32 size). This tests that the kernel correctly handles
+    non-uint32-aligned data sizes when splitting copies across registered
+    memory chunk boundaries.
+
+    The KV buffer shape is (2, num_layers, num_tokens, hidden_size), so the
+    total bytes = 2 * num_layers * num_tokens * 132. We pick values such that
+    the copy spans across at least one PIN_CHUNK_SIZE (64 MB) boundary.
+    """
+    # Use PIN_CHUNK_SIZE = 64 MB as the registration granularity
+    chunk_size = 1 << 26  # 64 MB
+    num_chunks = 2
+    dtype = torch.int8
+    hidden_size = 132  # NOT a multiple of 4 — tests uint32 alignment handling
+
+    # Total bytes must span at least one chunk boundary.
+    # We allocate num_chunks * chunk_size bytes worth of int8 elements.
+    total_bytes = chunk_size * num_chunks
+    total_elements = total_bytes  # int8: 1 byte per element
+
+    cpu_tensor = torch.randint(-128, 127, (total_elements,), dtype=dtype, device="cpu")
+    gpu_tensor = torch.zeros(total_elements, dtype=dtype, device="cuda")
+
+    rt = torch.cuda.cudart()
+
+    # Register the cpu memory in PIN_CHUNK_SIZE chunks
+    ptr = cpu_tensor.data_ptr()
+    for i in range(num_chunks):
+        rt.cudaHostRegister(ptr + i * chunk_size, chunk_size, 0)
+
+    def check_equal(gpu_t: torch.Tensor, cpu_t: torch.Tensor):
+        assert torch.equal(gpu_t.cpu(), cpu_t), "GPU and CPU tensors are not equal"
+
+    # Test cases: copy ranges that cross chunk boundaries with non-4-byte-aligned
+    # sizes, simulating real KV cache transfers where hidden_size=132 (int8).
+    #
+    # Each "KV row" is hidden_size=132 bytes. We pick copy sizes that are
+    # multiples of 132 but NOT multiples of 4, so the copy boundary falls on
+    # a non-uint32-aligned offset within a registered chunk.
+    #
+    # num_tokens=3: 3 * 132 = 396 bytes (396 % 4 == 0, but 132 % 4 != 0)
+    # num_tokens=1: 1 * 132 = 132 bytes (132 % 4 == 0)
+    # num_tokens=5: 5 * 132 = 660 bytes (660 % 4 == 0)
+    # Use an offset that puts the copy right across the 64MB boundary.
+    boundary = chunk_size  # 64 MB boundary in bytes
+
+    # Place the copy so it straddles the chunk boundary:
+    # start = boundary - 2 * hidden_size, length = 4 * hidden_size
+    # This means 2 * hidden_size bytes before the boundary and 2 * hidden_size
+    # bytes after — each segment is 264 bytes, not a multiple of 4*hidden_size.
+    test_cases = [
+        # (start_bytes, num_hidden_rows)
+        (boundary - 2 * hidden_size, 4),  # straddles boundary, 528 bytes
+        (boundary - hidden_size, 3),  # straddles boundary, 396 bytes
+        (boundary - 3 * hidden_size, 6),  # straddles boundary, 792 bytes
+        (0, 1),  # single row at start, 132 bytes
+        (total_bytes - hidden_size, 1),  # single row at end, 132 bytes
+    ]
+
+    for start_bytes, num_rows in test_cases:
+        nbytes = num_rows * hidden_size
+        end_bytes = start_bytes + nbytes
+        assert end_bytes <= total_bytes, (
+            f"Test case out of bounds: start={start_bytes}, nbytes={nbytes}"
+        )
+
+        # Reset gpu_tensor slice to zeros so we can detect the copy
+        gpu_tensor[start_bytes:end_bytes].zero_()
+
+        # H2D copy
+        lmc_ops.lmcache_memcpy_async(
+            gpu_tensor.data_ptr() + start_bytes,
+            cpu_tensor.data_ptr() + start_bytes,
+            nbytes,
+            lmc_ops.TransferDirection.H2D,
+            start_bytes,
+            chunk_size,
+        )
+        torch.cuda.synchronize()
+
+        check_equal(
+            gpu_tensor[start_bytes:end_bytes],
+            cpu_tensor[start_bytes:end_bytes],
+        )
+
+    # D2H copy: write known values to GPU, copy back to CPU, verify
+    gpu_src = torch.randint(-128, 127, (total_elements,), dtype=dtype, device="cuda")
+    cpu_dst = torch.zeros(total_elements, dtype=dtype, device="cpu")
+
+    # Register cpu_dst for D2H
+    ptr_dst = cpu_dst.data_ptr()
+    for i in range(num_chunks):
+        rt.cudaHostRegister(ptr_dst + i * chunk_size, chunk_size, 0)
+
+    for start_bytes, num_rows in test_cases:
+        nbytes = num_rows * hidden_size
+        end_bytes = start_bytes + nbytes
+
+        cpu_dst[start_bytes:end_bytes].zero_()
+
+        lmc_ops.lmcache_memcpy_async(
+            cpu_dst.data_ptr() + start_bytes,
+            gpu_src.data_ptr() + start_bytes,
+            nbytes,
+            lmc_ops.TransferDirection.D2H,
+            start_bytes,
+            chunk_size,
+        )
+        torch.cuda.synchronize()
+
+        check_equal(
+            gpu_src[start_bytes:end_bytes],
+            cpu_dst[start_bytes:end_bytes],
+        )
+
+    # Unregister memory
+    ptr = cpu_tensor.data_ptr()
+    for i in range(num_chunks):
+        rt.cudaHostUnregister(ptr + i * chunk_size)
+
+    ptr_dst = cpu_dst.data_ptr()
+    for i in range(num_chunks):
+        rt.cudaHostUnregister(ptr_dst + i * chunk_size)
diff --git a/tests/v1/test_memory_allocator_import_surface.py b/tests/v1/test_memory_allocator_import_surface.py
new file mode 100644
index 0000000..83982e0
--- /dev/null
+++ b/tests/v1/test_memory_allocator_import_surface.py
@@ -0,0 +1,173 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from pathlib import Path
+import subprocess
+import sys
+import textwrap
+
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _run_import_script(script: str) -> None:
+    """Run an import check in a fresh Python subprocess.
+
+    Args:
+        script: Python source code to execute with ``python -c``.
+
+    Raises:
+        AssertionError: If the subprocess exits with a non-zero status.
+    """
+    result = subprocess.run(
+        [sys.executable, "-c", textwrap.dedent(script)],
+        cwd=_REPO_ROOT,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    assert result.returncode == 0, (
+        f"subprocess failed with {result.returncode}\n"
+        f"stdout:\n{result.stdout}\n"
+        f"stderr:\n{result.stderr}"
+    )
+
+
+def test_memory_allocators_package_import_is_lazy() -> None:
+    """Importing the allocator package does not eagerly import submodules."""
+    _run_import_script(
+        """
+        import sys
+
+        import lmcache.v1.memory_allocators as allocators
+
+        allocator_modules = {
+            "ad_hoc_memory_allocator",
+            "buffer_allocator",
+            "cu_file_memory_allocator",
+            "devdax_memory_allocator",
+            "gpu_memory_allocator",
+            "hip_file_memory_allocator",
+            "host_memory_allocator",
+            "lazy_memory_allocator",
+            "mixed_memory_allocator",
+            "paged_cpu_gpu_memory_allocator",
+            "paged_tensor_memory_allocator",
+            "pin_memory_allocator",
+            "tensor_memory_allocator",
+        }
+        loaded = sorted(
+            name
+            for name in sys.modules
+            if name.startswith("lmcache.v1.memory_allocators.")
+            and name.rsplit(".", 1)[-1] in allocator_modules
+        )
+        assert loaded == [], loaded
+        assert "LazyMemoryAllocator" in allocators.__all__
+        assert "TensorMemoryAllocator" in allocators.__all__
+        """
+    )
+
+
+def test_allocator_submodule_first_import_keeps_core_surface() -> None:
+    """Importing concrete allocator modules first does not create a cycle."""
+    _run_import_script(
+        """
+        from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+            PagedAddressManager,
+            PagedTensorMemoryAllocator,
+        )
+        from lmcache.v1.memory_allocators.tensor_memory_allocator import (
+            TensorMemoryAllocator,
+        )
+        from lmcache.v1.memory_management import (
+            MemoryAllocatorInterface,
+            MemoryFormat,
+        )
+
+        assert PagedAddressManager.__name__ == "PagedAddressManager"
+        assert PagedTensorMemoryAllocator.__name__ == "PagedTensorMemoryAllocator"
+        assert TensorMemoryAllocator.__name__ == "TensorMemoryAllocator"
+        assert MemoryAllocatorInterface.__name__ == "MemoryAllocatorInterface"
+        assert MemoryFormat.KV_2LTD.name == "KV_2LTD"
+        """
+    )
+
+
+def test_multiple_allocator_submodule_imports_keep_core_surface() -> None:
+    """Concrete allocator imports do not disturb core memory_management imports."""
+    _run_import_script(
+        """
+        from lmcache.v1.memory_allocators.devdax_memory_allocator import (
+            DevDaxMemoryAllocator,
+        )
+        from lmcache.v1.memory_allocators.tensor_memory_allocator import (
+            TensorMemoryAllocator,
+        )
+        from lmcache.v1.memory_management import (
+            MemoryObj,
+            TensorMemoryObj,
+        )
+
+        assert DevDaxMemoryAllocator.__name__ == "DevDaxMemoryAllocator"
+        assert TensorMemoryAllocator.__name__ == "TensorMemoryAllocator"
+        assert MemoryObj.__name__ == "MemoryObj"
+        assert TensorMemoryObj.__name__ == "TensorMemoryObj"
+        """
+    )
+
+
+def test_lazy_allocator_package_and_submodule_paths_match() -> None:
+    """The lazy allocator package export matches its concrete submodule."""
+    _run_import_script(
+        """
+        import lmcache.v1.memory_allocators as allocators
+
+        from lmcache.v1.memory_allocators.lazy_memory_allocator import (
+            LazyMemoryAllocator,
+        )
+
+        assert LazyMemoryAllocator is allocators.LazyMemoryAllocator
+        """
+    )
+
+
+def test_memory_management_all_keeps_only_core_names() -> None:
+    """The memory_management import surface lists only core memory types."""
+    _run_import_script(
+        """
+        import lmcache.v1.memory_management as memory_management
+
+        allocator_names = {
+            "AdHocMemoryAllocator",
+            "BufferAllocator",
+            "CuFileMemoryAllocator",
+            "DevDaxMemoryAllocator",
+            "GPUMemoryAllocator",
+            "HipFileMemoryAllocator",
+            "HostMemoryAllocator",
+            "MixedMemoryAllocator",
+            "PagedAddressManager",
+            "PagedCpuGpuMemoryAllocator",
+            "PagedTensorMemoryAllocator",
+            "PinMemoryAllocator",
+            "TensorMemoryAllocator",
+        }
+        expected = {
+            "AddressManager",
+            "BytesBufferMemoryObj",
+            "FreeBlock",
+            "GDSMemoryObject",
+            "MemoryAllocatorInterface",
+            "MemoryFormat",
+            "MemoryObj",
+            "MemoryObjMetadata",
+            "TensorMemoryObj",
+            "torch_device_type",
+        }
+        missing = expected - set(memory_management.__all__)
+        assert missing == set(), missing
+        assert allocator_names.isdisjoint(memory_management.__all__)
+
+        assert not hasattr(memory_management, "TensorMemoryAllocator")
+        """
+    )
diff --git a/tests/v1/test_memory_management.py b/tests/v1/test_memory_management.py
new file mode 100644
index 0000000..1edea61
--- /dev/null
+++ b/tests/v1/test_memory_management.py
@@ -0,0 +1,1179 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import threading
+import time
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.observability import LMCStatsMonitor
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_allocators.host_memory_allocator import HostMemoryAllocator
+from lmcache.v1.memory_allocators.mixed_memory_allocator import MixedMemoryAllocator
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import (
+    BytesBufferMemoryObj,
+    MemoryFormat,
+    MemoryObjMetadata,
+    TensorMemoryObj,
+    _allocate_cpu_memory,
+    _free_cpu_memory,
+    _read_hugepage_info,
+)
+from lmcache.v1.pin_monitor import PinMonitor
+
+HUGEPAGE_SIZE = 2 * 1024 * 1024  # MAP_HUGE_2MB
+
+
+def check_allocator(allocator, max_size):
+    # 512 * 512 * 4 = 1MB
+    shape1 = torch.Size([512, 512])
+    data1 = allocator.allocate(shape1, torch.float)
+    assert data1 is not None
+    assert data1.tensor.dtype == torch.float
+    assert data1.tensor.shape == shape1
+
+    # 1024 * 1024 * 2 = 2MB
+    shape2 = torch.Size([1024, 1024])
+    data2 = allocator.allocate(shape2, torch.bfloat16)
+    assert data2 is not None
+    assert data2.tensor.dtype == torch.bfloat16
+    assert data2.tensor.shape == shape2
+
+    # 2048 * 2048 * 1 = 4MB
+    shape3 = torch.Size([2048, 2048])
+    data3 = allocator.allocate(shape3, torch.int8)
+    assert data3 is not None
+    assert data3.tensor.dtype == torch.int8
+    assert data3.tensor.shape == shape3
+
+    allocator.free(data2)
+    assert data2.tensor is None
+    assert allocator.memcheck()
+
+    allocator.free(data1)
+    assert data1.tensor is None
+    assert allocator.memcheck()
+
+    allocator.free(data2)  # This should not crash
+
+    shape4 = torch.Size([3, 5, 7])
+    data4 = allocator.allocate(shape4, torch.half)
+    assert data4 is not None
+    assert data4.tensor.dtype == torch.half
+    assert data4.tensor.shape == shape4
+
+    data_fail = allocator.allocate(
+        torch.Size([max_size]), torch.float
+    )  # This should fail
+    assert data_fail is None
+
+    assert allocator.memcheck()
+
+    allocator.free(data1)
+    allocator.free(data2)
+    allocator.free(data3)
+    allocator.free(data4)
+
+    assert allocator.memcheck()
+
+    allocator.close()
+
+
+def check_paged_allocator(allocator, shape, dtype, fmt, max_num_pages):
+    # Allocate one page
+    data1 = allocator.allocate(shape, dtype, fmt)
+    assert data1 is not None
+    assert data1.tensor.dtype == dtype
+    assert data1.tensor.shape == shape
+
+    # Allocate another 2 pages
+    data2 = allocator.batched_allocate(shape, dtype, 2, fmt)
+
+    for data in data2:
+        assert data is not None
+        assert data.tensor.dtype == dtype
+        assert data.tensor.shape == shape
+
+    # Allocate a smaller page
+    smaller_shape = torch.Size([2, 32, 8, 1024])
+    data3 = allocator.allocate(smaller_shape, dtype, fmt)
+    assert data3 is not None
+    assert data3.tensor.dtype == dtype
+    assert data3.tensor.shape == smaller_shape
+
+    allocator.free(data3)
+    assert allocator.memcheck()
+
+    allocator.batched_free(data2)
+    assert allocator.memcheck()
+
+    allocator.free(data1)
+    assert allocator.memcheck()
+
+    data_fail = allocator.batched_allocate(
+        shape, dtype, max_num_pages + 1, fmt
+    )  # This should fail
+    assert data_fail is None
+
+    assert allocator.memcheck()
+
+    allocator.close()
+
+
+@pytest.mark.parametrize(
+    "use_paging",
+    [True, False],
+)
+def test_tensor_allocator(use_paging):
+    total_size = 1024 * 1024 * 128  # 128MB
+    tensor_buffer = torch.zeros(total_size, dtype=torch.uint8, device="cpu")
+    if use_paging:
+        shape = torch.Size([2, 32, 16, 1024])  # 64 pages
+        dtype = torch.bfloat16
+        fmt = MemoryFormat.KV_2LTD
+        num_pages = 64
+        allocator = PagedTensorMemoryAllocator(tensor_buffer, [shape], [dtype], fmt)
+        check_paged_allocator(allocator, shape, dtype, fmt, num_pages)
+    else:
+        allocator = TensorMemoryAllocator(tensor_buffer)
+        check_allocator(allocator, total_size)
+
+    allocator.close()
+
+
+@pytest.mark.parametrize(
+    "alloc_cls",
+    [
+        HostMemoryAllocator,
+        PinMemoryAllocator,
+        GPUMemoryAllocator,
+        MixedMemoryAllocator,
+    ],
+)
+@pytest.mark.parametrize(
+    "use_paging",
+    [
+        False,
+        True,
+    ],
+)
+def test_device_allocators(alloc_cls, use_paging):
+    total_size = 1024 * 1024 * 128  # 128MB
+
+    shape = torch.Size([2, 32, 16, 1024])  # 64 pages
+    dtype = torch.bfloat16
+    fmt = MemoryFormat.KV_2LTD
+
+    allocator = alloc_cls(
+        total_size, use_paging=use_paging, shapes=[shape], dtypes=[dtype], fmt=fmt
+    )
+
+    if use_paging:
+        num_pages = 64
+        check_paged_allocator(allocator, shape, dtype, fmt, num_pages)
+    else:
+        check_allocator(allocator, total_size)
+
+    allocator.close()
+
+
+@pytest.mark.parametrize(
+    "alloc_cls",
+    [
+        HostMemoryAllocator,
+        PinMemoryAllocator,
+        GPUMemoryAllocator,
+        MixedMemoryAllocator,
+    ],
+)
+def test_inplace_modification(alloc_cls):
+    total_size = 1024 * 1024
+    allocator = alloc_cls(total_size)
+
+    shape = torch.Size([4096])
+    data = allocator.allocate(shape, torch.float)
+    assert data is not None
+    assert data.tensor.dtype == torch.float
+    assert data.tensor.shape == shape
+
+    data.tensor.fill_(1.0)
+    assert torch.all(data.tensor == 1.0)
+
+    data.tensor[1] = 2.0
+    assert data.tensor[1] == 2.0
+
+    allocator.close()
+
+
+@pytest.mark.parametrize(
+    "alloc_cls",
+    [
+        HostMemoryAllocator,
+        PinMemoryAllocator,
+        GPUMemoryAllocator,
+        MixedMemoryAllocator,
+    ],
+)
+def test_boundary_alloc(alloc_cls):
+    total_size = 1 << 25
+    allocator = alloc_cls(total_size)
+
+    shape = torch.Size([512, 10])
+    data1 = allocator.allocate(shape, torch.float)
+    allocator.allocate(shape, torch.float)
+    allocator.free(data1)
+
+    # `FreeBlock` with size 0 shouldn't exist in the allocator
+    allocator.allocate(shape, torch.float)
+
+    assert allocator.memcheck()
+    allocator.close()
+
+
+def test_mixed_allocator_owns_returned_tensor_object():
+    allocator = MixedMemoryAllocator(1024 * 1024)
+
+    data = allocator.allocate(torch.Size([4096]), torch.float)
+    assert data is not None
+    assert data.parent() is allocator
+
+    data.ref_count_down()
+    assert not data.is_valid()
+    assert allocator.memcheck()
+    allocator.close()
+
+
+@pytest.mark.parametrize(
+    "alloc_cls",
+    [
+        HostMemoryAllocator,
+        PinMemoryAllocator,
+        GPUMemoryAllocator,
+        MixedMemoryAllocator,
+    ],
+)
+def test_batched_alloc(alloc_cls):
+    total_size = 32 * 100 * 2 * 1024 * 2
+    batch_size = 32
+    allocator = alloc_cls(total_size)
+    shape = torch.Size([100, 2, 1024])
+    objs = allocator.batched_allocate(
+        shape, torch.bfloat16, batch_size, MemoryFormat.KV_T2D
+    )
+
+    assert len(objs) == batch_size
+    for obj in objs:
+        assert obj is not None
+        assert obj.tensor is not None
+        assert obj.tensor.dtype == torch.bfloat16
+        assert obj.tensor.shape == shape
+    allocator.batched_free(objs)
+
+    assert allocator.memcheck()
+    allocator.close()
+
+
+@pytest.mark.parametrize(
+    "alloc_cls",
+    [
+        MixedMemoryAllocator,
+    ],
+)
+def test_mixed_alloc(alloc_cls):
+    total_size = 1 << 25
+    allocator = alloc_cls(total_size)
+    shape = torch.Size([512, 10])
+    data1 = allocator.allocate(shape, [], MemoryFormat.BINARY_BUFFER)
+    allocator.allocate(shape, torch.float)
+    allocator.free(data1)
+
+    assert isinstance(data1, BytesBufferMemoryObj)
+
+    assert len(data1.byte_array) == 512
+
+    allocator.memcheck()
+    allocator.close()
+
+
+def test_byte_array_caches_ctypes_array_type():
+    """``TensorMemoryObj.byte_array`` must reuse the ctypes array type per length.
+
+    Regression for https://github.com/LMCache/LMCache/issues/3767.
+
+    ``ctypes`` does not cache ``(c_ubyte * N)`` array types: every ``*`` call
+    builds a fresh heap type whose metadata stays alive forever. On the remote
+    backend put/get path ``byte_array`` is accessed once per chunk, so without
+    caching every call permanently leaks ~1-2 kB of heap-type metadata. Long
+    timed-trace replays then see monotonic anonymous-memory growth that
+    eventually triggers an OOM kill.
+
+    Verify two contracts:
+    1. Repeated ``byte_array`` accesses with the same logical size return
+       memoryviews backed by the same underlying ctypes array type.
+    2. Different sizes hit different cached types (the cache is keyed on the
+       logical byte length).
+    """
+    # First Party
+    from lmcache.v1.memory_management import _get_cached_ubyte_array_type
+
+    # Direct helper contract.
+    t1 = _get_cached_ubyte_array_type(1024)
+    t2 = _get_cached_ubyte_array_type(1024)
+    t3 = _get_cached_ubyte_array_type(2048)
+    assert t1 is t2, "same length must map to the same cached array type"
+    assert t1 is not t3, "different lengths must not share a cached array type"
+
+    # Property-level contract: repeated TensorMemoryObj.byte_array accesses
+    # must not create new heap types.
+    total_size = 1 << 22
+    allocator = MixedMemoryAllocator(total_size)
+    shape = torch.Size([4096])
+    obj = allocator.allocate(shape, torch.uint8)
+    assert isinstance(obj, TensorMemoryObj)
+    try:
+        # Prime the cache with this object's size (and any other state the
+        # allocate path warmed up) so we measure only repeated-access growth.
+        _ = obj.byte_array
+        before = _get_cached_ubyte_array_type.cache_info().currsize
+        for _ in range(50):
+            mv = obj.byte_array
+            assert isinstance(mv, memoryview)
+        after = _get_cached_ubyte_array_type.cache_info().currsize
+        assert after == before, (
+            f"byte_array leaked array types across 50 repeated accesses: "
+            f"cache grew from {before} to {after}"
+        )
+    finally:
+        obj.ref_count_down()
+        allocator.close()
+
+
+def test_memory_obj_metadata_to_and_from_dict():
+    shape1 = torch.Size([128, 10])
+    dtype1 = torch.float
+    shape2 = torch.Size([256, 10])
+    dtype2 = torch.uint8
+    shapes = [shape1, shape2]
+    dtypes = [dtype1, dtype2]
+    metadata1 = MemoryObjMetadata(
+        shape=shape1,
+        dtype=dtype1,
+        address=0,
+        phy_size=0,
+        ref_count=0,
+        pin_count=0,
+        fmt=MemoryFormat.KV_T2D,
+    )
+    dict1 = metadata1.to_dict()
+    metadata_from_dict_1 = MemoryObjMetadata.from_dict(dict1)
+    assert metadata_from_dict_1.shape == shape1
+    assert metadata_from_dict_1.dtype == dtype1
+    assert metadata_from_dict_1.shapes is None
+    assert metadata_from_dict_1.dtypes is None
+
+    metadata2 = MemoryObjMetadata(
+        shape=shape1,
+        dtype=dtype1,
+        address=0,
+        phy_size=0,
+        ref_count=0,
+        pin_count=0,
+        fmt=MemoryFormat.KV_T2D,
+        shapes=shapes,
+        dtypes=dtypes,
+    )
+    dict2 = metadata2.to_dict()
+    metadata_from_dict_2 = MemoryObjMetadata.from_dict(dict2)
+    assert metadata_from_dict_2.shape == shape1
+    assert metadata_from_dict_2.dtype == dtype1
+    assert metadata_from_dict_2.shapes == shapes
+    assert metadata_from_dict_2.dtypes == dtypes
+
+
+@pytest.mark.parametrize(
+    "alloc_cls,custom_timeout,elapsed_time",
+    [
+        (HostMemoryAllocator, None, 360),
+        (PinMemoryAllocator, None, 360),
+        (GPUMemoryAllocator, None, 360),
+        (MixedMemoryAllocator, None, 360),
+        (HostMemoryAllocator, 60, 90),
+    ],
+)
+def test_pin_timeout(alloc_cls, custom_timeout, elapsed_time):
+    # Reset the singleton to ensure clean state
+    LMCStatsMonitor.DestroyInstance()
+    # Also reset the class variable to use the new singleton
+    TensorMemoryObj.monitor = LMCStatsMonitor.GetOrCreate()
+
+    # Reset and initialize PinMonitor
+    PinMonitor._instance = None
+    config = LMCacheEngineConfig.from_defaults()
+    PinMonitor.GetOrCreate(config)
+
+    try:
+        total_size = 1024 * 1024
+        allocator = alloc_cls(total_size)
+
+        # Create a memory object
+        data = allocator.allocate(torch.Size([4096]), torch.float)
+        assert data is not None
+
+        # Pin the object
+        data.pin()
+        assert data.metadata.pin_count == 1
+
+        # Get initial forced unpin count
+        monitor = LMCStatsMonitor.GetOrCreate()
+        initial_forced_unpin_count = monitor.interval_forced_unpin_count
+
+        # Get the PinMonitor instance that was used by pin()
+        pin_monitor = PinMonitor.GetOrCreate()
+
+        # Override timeout if custom timeout is specified
+        if custom_timeout is not None:
+            pin_monitor._pin_timeout_sec = custom_timeout
+
+        # Simulate timeout by manually setting register time in PinMonitor
+        obj_id = id(data)
+        with pin_monitor._objects_lock:
+            if obj_id in pin_monitor._pinned_objects:
+                memory_obj, _ = pin_monitor._pinned_objects[obj_id]
+                pin_monitor._pinned_objects[obj_id] = (
+                    memory_obj,
+                    time.time() - elapsed_time,
+                )
+
+        # Force a timeout check
+        pin_monitor._check_timeouts()
+
+        # Verify that pin_count is now 0
+        assert data.metadata.pin_count == 0
+
+        # Verify that forced unpin count increased
+        assert monitor.interval_forced_unpin_count == initial_forced_unpin_count + 1
+
+        allocator.close()
+    finally:
+        pass
+
+
+def test_pin_monitor_timeout():
+    """Test that PinMonitor correctly detects and handles pin timeouts."""
+
+    # Create a mock memory object for testing
+    class MockMemoryObjMetadata:
+        def __init__(self):
+            self.address = 12345
+            self.pin_count = 0
+            self.ref_count = 1
+
+    class MockMemoryObj:
+        def __init__(self):
+            self.meta = MockMemoryObjMetadata()
+            self.lock = threading.Lock()
+            self.parent_allocator = None
+
+        def unpin(self):
+            self.meta.pin_count -= 1
+            if self.meta.pin_count == 0:
+                PinMonitor.GetOrCreate().on_unpin(self)
+            if self.meta.pin_count < 0:
+                self.meta.pin_count = 0
+
+    # Reset PinMonitor singleton for testing
+    PinMonitor._instance = None
+
+    # Create PinMonitor with short timeout for testing
+    config = LMCacheEngineConfig.from_defaults(
+        pin_timeout_sec=1, pin_check_interval_sec=1
+    )
+    pin_monitor = PinMonitor.GetOrCreate(config)
+
+    # Create a mock memory object
+    mock_obj = MockMemoryObj()
+
+    # Test registration
+    pin_monitor.on_pin(mock_obj)
+    assert pin_monitor.get_monitored_count() == 1
+
+    # Test unregistration
+    pin_monitor.on_unpin(mock_obj)
+    assert pin_monitor.get_monitored_count() == 0
+
+    # Test timeout detection
+    try:
+        # Register object first
+        mock_obj.meta.pin_count = 1
+        pin_monitor.on_pin(mock_obj)
+
+        # Manually set old register time to simulate timeout
+        # Set to 2 seconds ago to exceed the 1 second timeout
+        obj_id = id(mock_obj)
+        with pin_monitor._objects_lock:
+            if obj_id in pin_monitor._pinned_objects:
+                memory_obj, _ = pin_monitor._pinned_objects[obj_id]
+                pin_monitor._pinned_objects[obj_id] = (
+                    memory_obj,
+                    time.time() - 2.0,
+                )
+
+        # Force a timeout check
+        pin_monitor._check_timeouts()
+
+        # Verify object was unpinned
+        assert mock_obj.meta.pin_count == 0
+        assert pin_monitor.get_monitored_count() == 0
+
+    finally:
+        pass
+
+
+def test_pin_monitor_background_thread():
+    """Test that PinMonitor background thread starts correctly."""
+    # Reset singleton and create with config
+    PinMonitor._instance = None
+    config = LMCacheEngineConfig.from_defaults()
+    pin_monitor = PinMonitor.GetOrCreate(config)
+
+    # PinMonitor auto-starts in __init__, so it should already be running
+    # PinMonitor now inherits from PeriodicThread, use is_running property
+    assert pin_monitor.is_running
+    assert pin_monitor._thread is not None
+    assert pin_monitor._thread.is_alive()
+
+    # Give thread a moment to start
+    time.sleep(0.1)
+
+    # Test basic functionality without stopping the thread
+    # (thread stopping is handled by daemon thread behavior)
+
+
+def test_tensor_memory_obj_pin_monitor_integration():
+    """Test integration between TensorMemoryObj and PinMonitor."""
+
+    # Create a simple allocator for testing
+    class MockAllocator:
+        def free(self, obj):
+            pass
+
+    # Create a real TensorMemoryObj
+    raw_data = torch.empty(100, dtype=torch.float32)
+    metadata = MemoryObjMetadata(
+        shape=torch.Size([100]),
+        dtype=torch.float32,
+        address=12345,
+        phy_size=400,
+        fmt=MemoryFormat.KV_2LTD,
+        ref_count=1,
+    )
+
+    allocator = MockAllocator()
+    memory_obj = TensorMemoryObj(raw_data, metadata, allocator)
+
+    # Get PinMonitor instance
+    pin_monitor = PinMonitor.GetOrCreate()
+    initial_count = pin_monitor.get_monitored_count()
+
+    # Test pinning registers with PinMonitor
+    memory_obj.pin()
+    assert pin_monitor.get_monitored_count() == initial_count + 1
+
+    # Test unpinning unregisters from PinMonitor
+    memory_obj.unpin()
+    assert pin_monitor.get_monitored_count() == initial_count
+
+    # Test multiple pins/unpins
+    memory_obj.pin()
+    memory_obj.pin()  # Pin twice
+    assert pin_monitor.get_monitored_count() == initial_count + 1
+
+    memory_obj.unpin()
+    assert pin_monitor.get_monitored_count() == initial_count + 1  # Still monitored
+
+    memory_obj.unpin()
+    assert pin_monitor.get_monitored_count() == initial_count  # Fully unregistered
+
+
+# =============================================================================
+# LazyMemoryAllocator Tests
+# =============================================================================
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="LazyMemoryAllocator requires CUDA for memory pinning",
+)
+class TestLazyMemoryAllocator:
+    """
+    Test suite for LazyMemoryAllocator.
+
+    These tests focus on the public interface defined by MemoryAllocatorInterface:
+    - allocate(shapes, dtypes, fmt, allocator_type) -> Optional[MemoryObj]
+    - batched_allocate(shapes, dtypes, batch_size, fmt, allocator_type)
+        -> Optional[List[MemoryObj]]
+    - free(memory_obj, allocator_type)
+    - batched_free(memory_objs, allocator_type, update_stats)
+    - close()
+    - memcheck() -> bool
+    """
+
+    # Use sizes that are multiples of PIN_CHUNK_SIZE (16 MB)
+    INIT_SIZE = 1 << 25  # 32 MB
+    FINAL_SIZE = 1 << 27  # 128 MB
+
+    @pytest.fixture
+    def lazy_allocator_cls(self):
+        """Lazily import LazyMemoryAllocator to avoid import errors
+        on CPU-only builds.
+        """
+        # First Party
+        from lmcache.v1.memory_allocators.lazy_memory_allocator import (
+            LazyMemoryAllocator,
+        )
+
+        return LazyMemoryAllocator
+
+    def test_allocate_basic(self, lazy_allocator_cls):
+        """Test basic allocation returns a valid MemoryObj."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([512, 512])
+        dtype = torch.float32
+        memory_obj = allocator.allocate(shape, dtype)
+
+        assert memory_obj is not None
+        assert memory_obj.is_valid()
+        assert memory_obj.tensor is not None
+        assert memory_obj.tensor.shape == shape
+        assert memory_obj.tensor.dtype == dtype
+
+        allocator.close()
+
+    def test_allocate_with_format(self, lazy_allocator_cls):
+        """Test allocation with explicit memory format."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([100, 2, 1024])
+        dtype = torch.bfloat16
+        fmt = MemoryFormat.KV_T2D
+
+        memory_obj = allocator.allocate(shape, dtype, fmt)
+
+        assert memory_obj is not None
+        assert memory_obj.is_valid()
+        assert memory_obj.get_memory_format() == fmt
+
+        allocator.close()
+
+    def test_allocate_multiple_shapes_and_dtypes(self, lazy_allocator_cls):
+        """Test allocation with multiple shapes and dtypes."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shapes = [torch.Size([100, 2, 512]), torch.Size([100, 2, 512])]
+        dtypes = [torch.bfloat16, torch.bfloat16]
+
+        memory_obj = allocator.allocate(shapes, dtypes)
+
+        assert memory_obj is not None
+        assert memory_obj.is_valid()
+
+        allocator.close()
+
+    def test_allocate_returns_none_when_out_of_memory(self, lazy_allocator_cls):
+        """Test that allocation returns None when memory is exhausted."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.INIT_SIZE,  # Same as init to prevent expansion
+        )
+
+        # Try to allocate more than available
+        huge_shape = torch.Size([self.INIT_SIZE])
+        memory_obj = allocator.allocate(huge_shape, torch.float32)
+
+        assert memory_obj is None
+
+        allocator.close()
+
+    def test_free_basic(self, lazy_allocator_cls):
+        """Test that free invalidates the MemoryObj."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([512, 512])
+        memory_obj = allocator.allocate(shape, torch.float32)
+        assert memory_obj is not None
+        assert memory_obj.is_valid()
+
+        allocator.free(memory_obj)
+        assert not memory_obj.is_valid()
+        assert memory_obj.tensor is None
+
+        allocator.close()
+
+    def test_free_idempotent(self, lazy_allocator_cls):
+        """Test that freeing an already freed object does not crash."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([256, 256])
+        memory_obj = allocator.allocate(shape, torch.float32)
+        assert memory_obj is not None
+
+        allocator.free(memory_obj)
+        # This should not crash
+        allocator.free(memory_obj)
+
+        assert allocator.memcheck()
+        allocator.close()
+
+    def test_batched_allocate_basic(self, lazy_allocator_cls):
+        """Test batched allocation returns correct number of MemoryObjs."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([100, 2, 512])
+        dtype = torch.bfloat16
+        batch_size = 8
+
+        memory_objs = allocator.batched_allocate(shape, dtype, batch_size)
+
+        assert memory_objs is not None
+        assert len(memory_objs) == batch_size
+        for obj in memory_objs:
+            assert obj is not None
+            assert obj.is_valid()
+            assert obj.tensor is not None
+            assert obj.tensor.shape == shape
+            assert obj.tensor.dtype == dtype
+
+        allocator.close()
+
+    def test_batched_allocate_with_format(self, lazy_allocator_cls):
+        """Test batched allocation with explicit memory format."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([100, 2, 512])
+        dtype = torch.bfloat16
+        fmt = MemoryFormat.KV_T2D
+        batch_size = 4
+
+        memory_objs = allocator.batched_allocate(shape, dtype, batch_size, fmt)
+
+        assert memory_objs is not None
+        for obj in memory_objs:
+            assert obj.get_memory_format() == fmt
+
+        allocator.close()
+
+    def test_batched_allocate_returns_none_when_out_of_memory(self, lazy_allocator_cls):
+        """Test that batched allocation returns None when memory is exhausted."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.INIT_SIZE,
+        )
+
+        shape = torch.Size([1024 * 1024])  # 1M elements
+        dtype = torch.float32  # 4 bytes each = 4MB per allocation
+        batch_size = 100  # Would need 400MB, more than available
+
+        memory_objs = allocator.batched_allocate(shape, dtype, batch_size)
+
+        assert memory_objs is None
+
+        allocator.close()
+
+    def test_batched_free_basic(self, lazy_allocator_cls):
+        """Test batched free invalidates all MemoryObjs."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([100, 2, 512])
+        dtype = torch.bfloat16
+        batch_size = 4
+
+        memory_objs = allocator.batched_allocate(shape, dtype, batch_size)
+        assert memory_objs is not None
+
+        allocator.batched_free(memory_objs)
+
+        for obj in memory_objs:
+            assert not obj.is_valid()
+
+        assert allocator.memcheck()
+        allocator.close()
+
+    def test_memcheck_returns_true_after_operations(self, lazy_allocator_cls):
+        """Test that memcheck returns True after valid operations."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        # Initial state
+        assert allocator.memcheck()
+
+        # After allocation
+        shape = torch.Size([512, 512])
+        memory_obj = allocator.allocate(shape, torch.float32)
+        assert allocator.memcheck()
+
+        # After free
+        allocator.free(memory_obj)
+        assert allocator.memcheck()
+
+        # After batched operations
+        objs = allocator.batched_allocate(shape, torch.float32, 4)
+        assert allocator.memcheck()
+
+        allocator.batched_free(objs)
+        assert allocator.memcheck()
+
+        allocator.close()
+
+    def test_inplace_tensor_modification(self, lazy_allocator_cls):
+        """Test that allocated tensor data can be modified in place."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([1024])
+        memory_obj = allocator.allocate(shape, torch.float32)
+        assert memory_obj is not None
+
+        # Modify the tensor in place
+        memory_obj.tensor.fill_(42.0)
+        assert torch.all(memory_obj.tensor == 42.0)
+
+        memory_obj.tensor[0] = 123.0
+        assert memory_obj.tensor[0] == 123.0
+
+        allocator.close()
+
+    def test_lazy_expansion_allows_larger_allocations(self, lazy_allocator_cls):
+        """
+        Test that lazy expansion allows allocations beyond init_size.
+
+        The background thread should expand the available memory over time,
+        allowing allocations that exceed the initial size.
+        """
+        # Start with small init_size, larger final_size
+        init_size = 1 << 25  # 32 MB
+        final_size = 1 << 27  # 128 MB
+
+        allocator = lazy_allocator_cls(
+            init_size=init_size,
+            final_size=final_size,
+        )
+
+        # Wait for background expansion to complete
+        # This gives the lazy allocator time to expand memory
+        time.sleep(0.5)
+
+        # Try to allocate more than init_size (but less than final_size)
+        # 64 MB > 32 MB init_size
+        large_shape = torch.Size([16 * 1024 * 1024])  # 16M elements * 4 bytes = 64MB
+        memory_obj = allocator.allocate(large_shape, torch.float32)
+
+        assert memory_obj is not None
+        assert memory_obj.is_valid()
+
+        allocator.close()
+
+    def test_allocate_various_dtypes(self, lazy_allocator_cls):
+        """Test allocation with various data types."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        test_cases = [
+            (torch.Size([512, 512]), torch.float32),
+            (torch.Size([1024, 1024]), torch.bfloat16),
+            (torch.Size([2048, 2048]), torch.int8),
+            (torch.Size([256, 256]), torch.half),
+        ]
+
+        memory_objs = []
+        for shape, dtype in test_cases:
+            obj = allocator.allocate(shape, dtype)
+            assert obj is not None, f"Failed to allocate {shape} with {dtype}"
+            assert obj.tensor.dtype == dtype
+            assert obj.tensor.shape == shape
+            memory_objs.append(obj)
+
+        # Free all
+        for obj in memory_objs:
+            allocator.free(obj)
+
+        assert allocator.memcheck()
+        allocator.close()
+
+    def test_allocation_and_free_interleaved(self, lazy_allocator_cls):
+        """Test interleaved allocation and free operations."""
+        allocator = lazy_allocator_cls(
+            init_size=self.INIT_SIZE,
+            final_size=self.FINAL_SIZE,
+        )
+
+        shape = torch.Size([256, 256])
+        dtype = torch.float32
+
+        obj1 = allocator.allocate(shape, dtype)
+        obj2 = allocator.allocate(shape, dtype)
+
+        allocator.free(obj1)
+
+        obj3 = allocator.allocate(shape, dtype)
+
+        allocator.free(obj2)
+        allocator.free(obj3)
+
+        assert allocator.memcheck()
+        allocator.close()
+
+
+def _get_num_free_hugepages() -> int:
+    """Return the number of free huge pages, or 0 if unknown."""
+    info = _read_hugepage_info()
+    if info is None:
+        return 0
+    _, free, _ = info
+    return free
+
+
+@pytest.mark.skipif(
+    _get_num_free_hugepages() < 1,
+    reason="Requires at least 1 free huge page (sysctl vm.nr_hugepages)",
+)
+class TestHugepageAllocation:
+    """Tests for hugepage-backed CPU memory allocation.
+
+    Skipped unless the system has pre-allocated huge pages.
+    """
+
+    def test_allocate_and_free(self):
+        """Allocate one huge page worth of memory and free it."""
+        buf = _allocate_cpu_memory(HUGEPAGE_SIZE, use_hugepages=True)
+        assert buf.numel() == HUGEPAGE_SIZE
+        assert buf.dtype == torch.uint8
+        buf[0] = 42
+        buf[-1] = 99
+        assert buf[0].item() == 42
+        assert buf[-1].item() == 99
+        _free_cpu_memory(buf, size=HUGEPAGE_SIZE, use_hugepages=True)
+
+    @pytest.mark.skipif(
+        _get_num_free_hugepages() < 4,
+        reason="Requires at least 4 free huge pages (sysctl vm.nr_hugepages)",
+    )
+    def test_allocate_multiple_pages(self):
+        """Allocate several huge pages and verify the buffer is usable."""
+        size = 4 * HUGEPAGE_SIZE
+        buf = _allocate_cpu_memory(size, use_hugepages=True)
+        assert buf.numel() == size
+        buf.fill_(7)
+        assert buf[size // 2].item() == 7
+        _free_cpu_memory(buf, size=size, use_hugepages=True)
+
+    def test_read_hugepage_info(self):
+        """_read_hugepage_info returns valid data on Linux."""
+        info = _read_hugepage_info()
+        assert info is not None
+        total, free, page_mb = info
+        assert total > 0
+        assert free >= 0
+        assert page_mb == 2
+
+
+# ---------------------------------------------------------------------------
+# set_used_size: narrowing logical size after a partial write
+# ---------------------------------------------------------------------------
+
+
+class TestSetUsedSize:
+    """``TensorMemoryObj.set_used_size`` narrows the logical view after a
+    write that did not fill the whole allocated buffer (e.g. when a serde
+    sizes its destination from ``estimate_serialized_size`` -- an upper
+    bound -- and then writes fewer bytes).  The override must survive
+    until the block is recycled by the paged allocator, at which point it
+    resets to ``None`` so the fresh allocation returns its layout-derived
+    size.
+    """
+
+    @staticmethod
+    def _make_byte_buffer(n_bytes: int) -> TensorMemoryObj:
+        """Construct a flat uint8 TensorMemoryObj of capacity ``n_bytes``
+        directly (no allocator), suitable for set_used_size mechanics
+        tests where allocator reuse isn't the focus."""
+        raw = torch.zeros(n_bytes, dtype=torch.uint8)
+        shape = torch.Size([n_bytes])
+        meta = MemoryObjMetadata(
+            shape=shape,
+            dtype=torch.uint8,
+            address=0,
+            phy_size=n_bytes,
+            ref_count=1,
+            pin_count=0,
+            fmt=MemoryFormat.BINARY_BUFFER,
+            shapes=[shape],
+            dtypes=[torch.uint8],
+        )
+        return TensorMemoryObj(raw_data=raw, metadata=meta, parent_allocator=None)
+
+    def test_default_get_size_is_layout_derived(self) -> None:
+        obj = self._make_byte_buffer(1024)
+        assert obj.get_size() == 1024
+        # No override set yet.
+        assert obj._used_size_override is None
+
+    def test_set_used_size_narrows_get_size_and_byte_array(self) -> None:
+        obj = self._make_byte_buffer(1024)
+        obj.set_used_size(213)
+        assert obj.get_size() == 213
+        # byte_array honors get_size, not the allocated capacity.
+        assert len(obj.byte_array) == 213
+
+    def test_set_used_size_keeps_tensor_and_shm_length_consistent(self) -> None:
+        """A narrowed buffer must expose ``tensor``, ``shm_byte_length``,
+        ``get_size`` and ``byte_array`` at the same length.  The SHM
+        transport builds a slot from ``tensor.shape`` plus
+        ``shm_byte_length`` and the worker rebuilds a view from both, so
+        any disagreement -- e.g. ``tensor`` reshaping to the original
+        (wider) layout while ``shm_byte_length`` reports the narrowed
+        length -- raises ``shape is invalid for input of size`` on one
+        side.  Accessing ``tensor`` must not raise.
+        """
+        obj = self._make_byte_buffer(1024)
+        obj.set_used_size(213)
+        t = obj.tensor
+        assert t is not None
+        # Flat uint8 view of exactly the used bytes -- not the 1024-wide
+        # layout that would fail to reshape.
+        assert t.dtype == torch.uint8
+        assert tuple(t.shape) == (213,)
+        assert obj.shm_byte_length == 213
+        assert t.numel() == obj.shm_byte_length == obj.get_size()
+
+    def test_set_used_size_zero_is_allowed(self) -> None:
+        obj = self._make_byte_buffer(1024)
+        obj.set_used_size(0)
+        assert obj.get_size() == 0
+        assert len(obj.byte_array) == 0
+
+    def test_set_used_size_at_physical_size_is_allowed(self) -> None:
+        obj = self._make_byte_buffer(1024)
+        obj.set_used_size(obj.get_physical_size())
+        assert obj.get_size() == obj.get_physical_size()
+
+    def test_set_used_size_rejects_out_of_range(self) -> None:
+        obj = self._make_byte_buffer(1024)
+        with pytest.raises(ValueError):
+            obj.set_used_size(-1)
+        with pytest.raises(ValueError):
+            obj.set_used_size(obj.get_physical_size() + 1)
+
+    def _paged_byte_allocator(
+        self, n_pages: int, page_bytes: int
+    ) -> "PagedTensorMemoryAllocator":
+        """Build a paged uint8 allocator with ``n_pages`` pages of
+        ``page_bytes`` each, suitable for testing block-recycle resets.
+        """
+        # The paged allocator splits a flat tensor into equal-sized
+        # pages; the page shape is what allocate/batched_allocate hand
+        # back per block.
+        shape = torch.Size([page_bytes])
+        buffer = torch.zeros(n_pages * page_bytes, dtype=torch.uint8)
+        return PagedTensorMemoryAllocator(
+            tensor=buffer,
+            shapes=[shape],
+            dtypes=[torch.uint8],
+            fmt=MemoryFormat.BINARY_BUFFER,
+        )
+
+    def test_used_size_override_resets_on_paged_allocator_reuse(self) -> None:
+        """After a free + re-allocate from the paged allocator, a
+        recycled block must return its layout-derived size, not the
+        previous owner's narrowed size. The reset is what makes
+        ``set_used_size`` safe to use on temp buffers that pass through
+        the L1 pool repeatedly."""
+        allocator = self._paged_byte_allocator(n_pages=2, page_bytes=1024)
+        shape = torch.Size([1024])
+
+        obj_a = allocator.allocate(shape, torch.uint8, fmt=MemoryFormat.BINARY_BUFFER)
+        assert obj_a is not None
+        assert obj_a.get_size() == 1024
+        obj_a.set_used_size(213)
+        assert obj_a.get_size() == 213
+
+        # Free returns the block to the free_blocks deque; the next
+        # allocate will hand it back, and the recycle path must clear
+        # _used_size_override.
+        allocator.free(obj_a)
+        obj_b = allocator.allocate(shape, torch.uint8, fmt=MemoryFormat.BINARY_BUFFER)
+        assert obj_b is not None
+        assert obj_b._used_size_override is None
+        assert obj_b.get_size() == 1024
+
+    def test_used_size_override_resets_on_paged_batched_reuse(self) -> None:
+        """Same contract as the single-allocate test but via
+        ``batched_allocate``, which has its own copy of the per-block
+        metadata-reset logic."""
+        allocator = self._paged_byte_allocator(n_pages=4, page_bytes=1024)
+        shape = torch.Size([1024])
+
+        batch = allocator.batched_allocate(
+            shape, torch.uint8, batch_size=2, fmt=MemoryFormat.BINARY_BUFFER
+        )
+        assert batch is not None and len(batch) == 2
+        for blk in batch:
+            blk.set_used_size(100)
+        for blk in batch:
+            allocator.free(blk)
+
+        batch2 = allocator.batched_allocate(
+            shape, torch.uint8, batch_size=2, fmt=MemoryFormat.BINARY_BUFFER
+        )
+        assert batch2 is not None and len(batch2) == 2
+        for blk in batch2:
+            assert blk._used_size_override is None
+            assert blk.get_size() == 1024
+
+    def test_bytes_buffer_memory_obj_set_used_size_is_noop(self) -> None:
+        """``BytesBufferMemoryObj`` does not distinguish "used" from
+        "allocated"; ``set_used_size`` is the base-class no-op so the
+        size stays the raw buffer length."""
+        buf = BytesBufferMemoryObj(b"abc")
+        assert buf.get_size() == 3
+        # Should not raise; should not change get_size.
+        buf.set_used_size(1)
+        assert buf.get_size() == 3
diff --git a/tests/v1/test_mp_mem_kernels.py b/tests/v1/test_mp_mem_kernels.py
new file mode 100644
index 0000000..1aebd9f
--- /dev/null
+++ b/tests/v1/test_mp_mem_kernels.py
@@ -0,0 +1,471 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+import random
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip(
+    "lmcache.c_ops",
+    reason="Requires CUDA extension lmcache.c_ops",
+)
+
+# First Party
+import lmcache.c_ops as lmc_ops
+
+# Skip all tests if cuda is unavailable
+pytestmark = pytest.mark.skipif(
+    not torch.cuda.is_available() or torch.cuda.device_count() == 0,
+    reason="No CUDA GPU present",
+)
+
+# ---------------------------------------------------------------------------
+# Tensor factories (ported from kernel harness)
+# ---------------------------------------------------------------------------
+
+
+def _create_random_tensor(
+    shape: list, dtype: torch.dtype, device: torch.device
+) -> torch.Tensor:
+    if dtype == torch.float8_e4m3fn:
+        return torch.rand(shape, dtype=torch.bfloat16, device=device).to(dtype)
+    return torch.rand(shape, dtype=dtype, device=device)
+
+
+def _create_zero_tensor(
+    shape: list, dtype: torch.dtype, device: torch.device
+) -> torch.Tensor:
+    if dtype == torch.float8_e4m3fn:
+        return torch.zeros(shape, dtype=torch.bfloat16, device=device).to(dtype)
+    return torch.zeros(shape, dtype=dtype, device=device)
+
+
+# Format enum values from c_ops
+FMT_NORMAL = lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+FMT_CROSS_LAYER = lmc_ops.EngineKVFormat.NB_NL_TWO_BS_NH_HS
+FMT_FLASH_INFER = lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS
+FMT_MLA = lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+FMT_SGLANG_MHA = lmc_ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS
+FMT_SGLANG_MLA = lmc_ops.EngineKVFormat.NL_X_NBBS_ONE_HS
+FMT_NORMAL_HND = lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS
+FMT_FLASH_INFER_HND = lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS
+
+# Format parameters: (engine_kv_format, num_layers, num_heads, head_size, is_mla)
+# Use small layer counts to keep GPU memory usage low in CI
+FORMAT_PARAMS = [
+    (FMT_NORMAL, 4, 8, 128, False),
+    (FMT_CROSS_LAYER, 4, 8, 128, False),
+    (FMT_FLASH_INFER, 4, 8, 128, False),
+    (FMT_MLA, 4, 1, 576, True),
+    (FMT_SGLANG_MHA, 4, 8, 128, False),
+    (FMT_SGLANG_MLA, 4, 1, 576, True),
+    (FMT_NORMAL_HND, 4, 8, 128, False),
+    (FMT_FLASH_INFER_HND, 4, 8, 128, False),
+]
+
+
+def create_vllm_tensors(
+    engine_kv_format,
+    nl: int,
+    nb: int,
+    bs: int,
+    nh: int,
+    hs: int,
+    dtype: torch.dtype,
+    device: torch.device,
+) -> list[torch.Tensor]:
+    nbbs = nb * bs
+    if engine_kv_format == FMT_NORMAL:
+        shape = [2, nb, bs, nh, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_NORMAL_HND:
+        shape = [2, nb, nh, bs, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_CROSS_LAYER:
+        shape = [nb, nl, 2, bs, nh, hs]
+        return [_create_random_tensor(shape, dtype, device)]
+    elif engine_kv_format == FMT_FLASH_INFER:
+        shape = [nb, 2, bs, nh, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_FLASH_INFER_HND:
+        shape = [nb, 2, nh, bs, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_MLA:
+        shape = [nb, bs, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_SGLANG_MHA:
+        shape = [nbbs, nh, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(2 * nl)]
+    elif engine_kv_format == FMT_SGLANG_MLA:
+        shape = [nbbs, 1, hs]
+        return [_create_random_tensor(shape, dtype, device) for _ in range(nl)]
+    raise ValueError(f"Unknown format: {engine_kv_format}")
+
+
+def create_zero_vllm_tensors(
+    engine_kv_format,
+    nl: int,
+    nb: int,
+    bs: int,
+    nh: int,
+    hs: int,
+    dtype: torch.dtype,
+    device: torch.device,
+) -> list[torch.Tensor]:
+    nbbs = nb * bs
+    if engine_kv_format == FMT_NORMAL:
+        shape = [2, nb, bs, nh, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_NORMAL_HND:
+        shape = [2, nb, nh, bs, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_CROSS_LAYER:
+        shape = [nb, nl, 2, bs, nh, hs]
+        return [_create_zero_tensor(shape, dtype, device)]
+    elif engine_kv_format == FMT_FLASH_INFER:
+        shape = [nb, 2, bs, nh, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_FLASH_INFER_HND:
+        shape = [nb, 2, nh, bs, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_MLA:
+        shape = [nb, bs, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(nl)]
+    elif engine_kv_format == FMT_SGLANG_MHA:
+        shape = [nbbs, nh, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(2 * nl)]
+    elif engine_kv_format == FMT_SGLANG_MLA:
+        shape = [nbbs, 1, hs]
+        return [_create_zero_tensor(shape, dtype, device) for _ in range(nl)]
+    raise ValueError(f"Unknown format: {engine_kv_format}")
+
+
+def create_memory_objects(
+    kv_dim: int,
+    nl: int,
+    tokens_per_object: int,
+    hidden_dim: int,
+    num_objects: int,
+    dtype: torch.dtype,
+    device: torch.device,
+) -> list[torch.Tensor]:
+    shape = [kv_dim, nl, tokens_per_object, hidden_dim]
+    objects = []
+    for _ in range(num_objects):
+        if dtype == torch.float8_e4m3fn:
+            t = torch.zeros(shape, dtype=torch.bfloat16, device=device)
+            t = t.to(dtype)
+        else:
+            t = torch.zeros(shape, dtype=dtype, device=device)
+        if device.type == "cpu":
+            t = t.pin_memory()
+        objects.append(t)
+    return objects
+
+
+def get_block_data(
+    vllm_tensors: list[torch.Tensor],
+    engine_kv_format,
+    nl: int,
+    bs: int,
+    nh: int,
+    block_idx: int,
+) -> list[torch.Tensor]:
+    """Extract all layer data for a given block."""
+    results = []
+    for layer_idx in range(nl):
+        if engine_kv_format == FMT_NORMAL:
+            results.append(vllm_tensors[layer_idx][:, block_idx, :, :, :].clone())
+        elif engine_kv_format == FMT_NORMAL_HND:
+            results.append(vllm_tensors[layer_idx][:, block_idx, :, :, :].clone())
+        elif engine_kv_format == FMT_CROSS_LAYER:
+            results.append(vllm_tensors[0][block_idx, layer_idx, :, :, :, :].clone())
+        elif engine_kv_format == FMT_FLASH_INFER:
+            results.append(vllm_tensors[layer_idx][block_idx, :, :, :, :].clone())
+        elif engine_kv_format == FMT_FLASH_INFER_HND:
+            results.append(vllm_tensors[layer_idx][block_idx, :, :, :, :].clone())
+        elif engine_kv_format == FMT_MLA:
+            results.append(vllm_tensors[layer_idx][block_idx, :, :].clone())
+        elif engine_kv_format == FMT_SGLANG_MHA:
+            ts, ed = block_idx * bs, (block_idx + 1) * bs
+            k = vllm_tensors[layer_idx][ts:ed, :, :].clone()
+            v = vllm_tensors[nl + layer_idx][ts:ed, :, :].clone()
+            results.append(torch.stack([k, v], dim=0))
+        elif engine_kv_format == FMT_SGLANG_MLA:
+            ts, ed = block_idx * bs, (block_idx + 1) * bs
+            results.append(vllm_tensors[layer_idx][ts:ed, 0, :].clone())
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Kernel call helper
+# ---------------------------------------------------------------------------
+
+
+def call_block_kernel(
+    vllm_tensors: list[torch.Tensor],
+    mem_objects: list[torch.Tensor],
+    block_ids: list[int],
+    engine_kv_format,
+    direction,
+    nl: int,
+    nb: int,
+    bs: int,
+    nh: int,
+    hs: int,
+    is_mla: bool,
+    tokens_per_object: int,
+    skip_prefix_n_blocks: int = 0,
+) -> None:
+    device = vllm_tensors[0].device
+
+    shape_desc = lmc_ops.PageBufferShapeDesc()
+    shape_desc.kv_size = 1 if is_mla else 2
+    shape_desc.nl = nl
+    shape_desc.nb = nb
+    shape_desc.bs = bs
+    shape_desc.nh = nh
+    shape_desc.hs = hs
+    shape_desc.element_size = vllm_tensors[0].element_size()
+
+    ptrs = [t.data_ptr() for t in vllm_tensors]
+    paged_buffer_ptrs_tensor = torch.tensor(ptrs, dtype=torch.int64, device=device)
+    lmcache_objects_ptrs = [m.data_ptr() for m in mem_objects]
+
+    block_ids_gpu = torch.tensor(block_ids, dtype=torch.int64, device=device)
+    lmc_ops.multi_layer_block_kv_transfer(
+        paged_buffer_ptrs_tensor,
+        lmcache_objects_ptrs,
+        block_ids_gpu,
+        device,
+        direction,
+        shape_desc,
+        tokens_per_object,
+        engine_kv_format,
+        skip_prefix_n_blocks,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+NB = 1000
+BS = 16
+NUM_MEMORY_OBJECTS = 4
+TOKENS_PER_OBJECT = 256
+BLOCKS_PER_OBJECT = TOKENS_PER_OBJECT // BS  # 16
+TOTAL_BLOCKS = NUM_MEMORY_OBJECTS * BLOCKS_PER_OBJECT  # 64
+
+
+@pytest.mark.parametrize(
+    "engine_kv_format,nl,nh,hs,is_mla",
+    FORMAT_PARAMS,
+    ids=[
+        "normal",
+        "cross_layer",
+        "flash_infer",
+        "mla",
+        "sglang_mha",
+        "sglang_mla",
+        "normal_hnd",
+        "flash_infer_hnd",
+    ],
+)
+@pytest.mark.parametrize(
+    "dtype", [torch.bfloat16, torch.float8_e4m3fn], ids=["bf16", "fp8"]
+)
+@pytest.mark.parametrize("mem_device", ["cuda", "cpu"], ids=["mem_gpu", "mem_cpu"])
+def test_block_transfer_roundtrip(
+    engine_kv_format, nl, nh, hs, is_mla, dtype, mem_device
+):
+    """
+    D2H -> H2D roundtrip with different block IDs proves data flows through
+    memory objects.
+    """
+    device = torch.device("cuda")
+    mem_dev = torch.device(mem_device)
+    kv_dim = 1 if is_mla else 2
+    hidden_dim = nh * hs
+
+    # Create tensors
+    source_vllm = create_vllm_tensors(
+        engine_kv_format, nl, NB, BS, nh, hs, dtype, device
+    )
+    target_vllm = create_zero_vllm_tensors(
+        engine_kv_format, nl, NB, BS, nh, hs, dtype, device
+    )
+    mem_objects = create_memory_objects(
+        kv_dim,
+        nl,
+        TOKENS_PER_OBJECT,
+        hidden_dim,
+        NUM_MEMORY_OBJECTS,
+        dtype,
+        mem_dev,
+    )
+
+    # Disjoint block IDs for D2H and H2D
+    rng_d2h = random.Random(42)
+    block_ids_d2h = rng_d2h.sample(range(NB), TOTAL_BLOCKS)
+    excluded = set(block_ids_d2h)
+    available = [i for i in range(NB) if i not in excluded]
+    rng_h2d = random.Random(123)
+    block_ids_h2d = rng_h2d.sample(available, TOTAL_BLOCKS)
+
+    # D2H: source -> mem_objects
+    call_block_kernel(
+        source_vllm,
+        mem_objects,
+        block_ids_d2h,
+        engine_kv_format,
+        lmc_ops.TransferDirection.D2H,
+        nl,
+        NB,
+        BS,
+        nh,
+        hs,
+        is_mla,
+        TOKENS_PER_OBJECT,
+    )
+    torch.cuda.synchronize()
+
+    # H2D: mem_objects -> target
+    call_block_kernel(
+        target_vllm,
+        mem_objects,
+        block_ids_h2d,
+        engine_kv_format,
+        lmc_ops.TransferDirection.H2D,
+        nl,
+        NB,
+        BS,
+        nh,
+        hs,
+        is_mla,
+        TOKENS_PER_OBJECT,
+    )
+    torch.cuda.synchronize()
+
+    # Verify: target[h2d_block] == source[d2h_block]
+    for i in range(TOTAL_BLOCKS):
+        src_data = get_block_data(
+            source_vllm, engine_kv_format, nl, BS, nh, block_ids_d2h[i]
+        )
+        tgt_data = get_block_data(
+            target_vllm, engine_kv_format, nl, BS, nh, block_ids_h2d[i]
+        )
+        for layer_idx in range(nl):
+            assert torch.equal(src_data[layer_idx], tgt_data[layer_idx]), (
+                f"Mismatch at block index {i}, layer {layer_idx}"
+            )
+
+
+@pytest.mark.parametrize(
+    "engine_kv_format,nl,nh,hs,is_mla",
+    FORMAT_PARAMS,
+    ids=[
+        "normal",
+        "cross_layer",
+        "flash_infer",
+        "mla",
+        "sglang_mha",
+        "sglang_mla",
+        "normal_hnd",
+        "flash_infer_hnd",
+    ],
+)
+@pytest.mark.parametrize("dtype", [torch.bfloat16], ids=["bf16"])
+def test_block_transfer_skip_prefix(engine_kv_format, nl, nh, hs, is_mla, dtype):
+    """Verify skip_prefix_n_blocks=4 skips the first 4 blocks globally."""
+    device = torch.device("cuda")
+    kv_dim = 1 if is_mla else 2
+    hidden_dim = nh * hs
+    skip = 4
+
+    source_vllm = create_vllm_tensors(
+        engine_kv_format, nl, NB, BS, nh, hs, dtype, device
+    )
+    target_vllm = create_zero_vllm_tensors(
+        engine_kv_format, nl, NB, BS, nh, hs, dtype, device
+    )
+    mem_objects = create_memory_objects(
+        kv_dim,
+        nl,
+        TOKENS_PER_OBJECT,
+        hidden_dim,
+        NUM_MEMORY_OBJECTS,
+        dtype,
+        device,
+    )
+
+    rng_d2h = random.Random(42)
+    block_ids_d2h = rng_d2h.sample(range(NB), TOTAL_BLOCKS)
+    excluded = set(block_ids_d2h)
+    available = [i for i in range(NB) if i not in excluded]
+    rng_h2d = random.Random(123)
+    block_ids_h2d = rng_h2d.sample(available, TOTAL_BLOCKS)
+
+    # D2H with skip
+    call_block_kernel(
+        source_vllm,
+        mem_objects,
+        block_ids_d2h,
+        engine_kv_format,
+        lmc_ops.TransferDirection.D2H,
+        nl,
+        NB,
+        BS,
+        nh,
+        hs,
+        is_mla,
+        TOKENS_PER_OBJECT,
+        skip_prefix_n_blocks=skip,
+    )
+    torch.cuda.synchronize()
+
+    # H2D with skip
+    call_block_kernel(
+        target_vllm,
+        mem_objects,
+        block_ids_h2d,
+        engine_kv_format,
+        lmc_ops.TransferDirection.H2D,
+        nl,
+        NB,
+        BS,
+        nh,
+        hs,
+        is_mla,
+        TOKENS_PER_OBJECT,
+        skip_prefix_n_blocks=skip,
+    )
+    torch.cuda.synchronize()
+
+    # Non-skipped blocks should match
+    for i in range(skip, TOTAL_BLOCKS):
+        src_data = get_block_data(
+            source_vllm, engine_kv_format, nl, BS, nh, block_ids_d2h[i]
+        )
+        tgt_data = get_block_data(
+            target_vllm, engine_kv_format, nl, BS, nh, block_ids_h2d[i]
+        )
+        for layer_idx in range(nl):
+            assert torch.equal(src_data[layer_idx], tgt_data[layer_idx]), (
+                f"Mismatch at block index {i}, layer {layer_idx}"
+            )
+
+    # Skipped blocks in target should remain zero
+    for i in range(skip):
+        tgt_data = get_block_data(
+            target_vllm, engine_kv_format, nl, BS, nh, block_ids_h2d[i]
+        )
+        for layer_idx in range(nl):
+            block = tgt_data[layer_idx]
+            if block.dtype == torch.float8_e4m3fn:
+                block = block.to(torch.float32)
+            assert block.abs().sum().item() == 0, (
+                f"Skipped block {i}, layer {layer_idx} is not zero"
+            )
diff --git a/tests/v1/test_musa_connector.py b/tests/v1/test_musa_connector.py
new file mode 100644
index 0000000..1460025
--- /dev/null
+++ b/tests/v1/test_musa_connector.py
@@ -0,0 +1,1023 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from contextlib import nullcontext
+from types import SimpleNamespace
+from typing import Any, cast
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.musa_connectors import (
+    VLLMPagedMemLayerwiseMUSAConnector,
+    VLLMPagedMemMUSAConnectorV2,
+)
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from tests.v1.utils import (
+    check_paged_kv_cache_equal,
+    generate_kv_cache_paged_list_tensors,
+)
+import lmcache.c_ops as lmc_ops
+
+
+def _skip_if_no_musa() -> None:
+    if not hasattr(torch, "musa") or not torch.musa.is_available():
+        pytest.skip("torch.musa is not available")
+
+
+def _make_unique_slot_mapping(
+    *, total_slots: int, num_tokens: int, device: torch.device
+) -> torch.Tensor:
+    return torch.randperm(total_slots, device=device, dtype=torch.int64)[:num_tokens]
+
+
+def _pack_slot_mapping(
+    slot_mapping: torch.Tensor, starts: list[int], ends: list[int]
+) -> torch.Tensor:
+    return torch.cat(
+        [slot_mapping[s:e] for s, e in zip(starts, ends, strict=False)],
+        dim=0,
+    )
+
+
+def _make_metadata(
+    *,
+    model_name: str,
+    num_layers: int,
+    num_tokens: int,
+    num_heads: int,
+    head_size: int,
+) -> LMCacheMetadata:
+    """Create metadata for a synthetic vLLM MUSA KV cache."""
+    return LMCacheMetadata(
+        model_name=model_name,
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(num_layers, 2, num_tokens, num_heads, head_size),
+    )
+
+
+def _patch_musa_connector_attrs(
+    monkeypatch: pytest.MonkeyPatch,
+    conn: VLLMPagedMemMUSAConnectorV2,
+    *,
+    num_layers: int,
+    num_blocks: int,
+    block_size: int,
+    num_heads: int,
+    head_size: int,
+    engine_kv_format: lmc_ops.EngineKVFormat = (
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    ),
+) -> None:
+    """Patch connector layout discovery so transfer logic can run on CPU."""
+
+    def _initialize_attributes(_kv_caches: list[torch.Tensor]) -> None:
+        conn.device = torch.device("cpu")
+        conn.engine_kv_format = engine_kv_format
+        conn.num_layers = num_layers
+        conn.num_blocks = num_blocks
+        conn.block_size = block_size
+        conn.page_buffer_size = num_blocks * block_size
+        conn.hidden_dim_size = num_heads * head_size
+        conn.head_size = head_size
+        conn.use_mla = False
+        conn.dtype = torch.bfloat16
+        conn.num_heads = num_heads
+        conn._attributes_initialized = True
+
+    monkeypatch.setattr(conn, "_initialize_attributes", _initialize_attributes)
+
+
+class _FakeMUSAStream:
+    """Minimal stream object used by CPU-only MUSA generator tests."""
+
+    def wait_stream(self, _stream: object) -> None:
+        return None
+
+
+class _FakeMUSA:
+    """Minimal ``torch.musa`` facade for CPU-only generator contract tests."""
+
+    def Stream(self) -> _FakeMUSAStream:
+        return _FakeMUSAStream()
+
+    def current_stream(self) -> _FakeMUSAStream:
+        return _FakeMUSAStream()
+
+    def stream(self, _stream: object) -> Any:
+        return nullcontext()
+
+
+def test_musa_connector_to_gpu_skips_vllm_cached_prefix(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``vllm_cached_tokens`` skips prefix slots before torch ``index_copy_``."""
+    num_layers = 1
+    num_blocks = 3
+    block_size = 4
+    num_heads = 1
+    head_size = 2
+    hidden_dim = num_heads * head_size
+    start = 4
+    end = 8
+    vllm_cached_tokens = 6
+    skipped = vllm_cached_tokens - start
+
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(
+            model_name="musa_test_vllm_cached_tokens",
+            num_layers=num_layers,
+            num_tokens=end - start,
+            num_heads=num_heads,
+            head_size=head_size,
+        ),
+    )
+    _patch_musa_connector_attrs(
+        monkeypatch,
+        conn,
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+    )
+
+    kvcaches_dst = [
+        torch.zeros(
+            2,
+            num_blocks,
+            block_size,
+            num_heads,
+            head_size,
+            dtype=torch.bfloat16,
+        )
+    ]
+    memory_tensor = torch.arange(
+        2 * num_layers * (end - start) * hidden_dim,
+        dtype=torch.float32,
+    ).reshape(2, num_layers, end - start, hidden_dim)
+    memory_tensor = memory_tensor.to(torch.bfloat16)
+    memory_obj = cast(
+        MemoryObj,
+        SimpleNamespace(
+            tensor=memory_tensor,
+            metadata=SimpleNamespace(fmt=MemoryFormat.KV_2LTD),
+        ),
+    )
+    slot_mapping = torch.tensor(
+        [-1, -1, -1, -1, -1, -1, 6, 7],
+        dtype=torch.long,
+    )
+
+    conn.to_gpu(
+        memory_obj,
+        start=start,
+        end=end,
+        slot_mapping=slot_mapping,
+        kvcaches=kvcaches_dst,
+        vllm_cached_tokens=vllm_cached_tokens,
+    )
+
+    flat_k = kvcaches_dst[0][0].reshape(num_blocks * block_size, hidden_dim)
+    flat_v = kvcaches_dst[0][1].reshape(num_blocks * block_size, hidden_dim)
+    target_slots = slot_mapping[vllm_cached_tokens:end]
+
+    assert torch.equal(flat_k[target_slots], memory_tensor[0, 0, skipped:])
+    assert torch.equal(flat_v[target_slots], memory_tensor[1, 0, skipped:])
+    assert torch.count_nonzero(flat_k[-1]) == 0
+    assert torch.count_nonzero(flat_v[-1]) == 0
+
+
+def test_musa_connector_rejects_unsupported_kv_layout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Unsupported MUSA KV layouts fail with a connector-level message."""
+    num_layers = 1
+    num_blocks = 3
+    block_size = 4
+    num_heads = 1
+    head_size = 2
+    hidden_dim = num_heads * head_size
+
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(
+            model_name="musa_test_unsupported_layout",
+            num_layers=num_layers,
+            num_tokens=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+        ),
+    )
+    _patch_musa_connector_attrs(
+        monkeypatch,
+        conn,
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        engine_kv_format=lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,
+    )
+
+    kvcaches_dst = [
+        torch.zeros(
+            num_blocks,
+            2,
+            block_size,
+            num_heads,
+            head_size,
+            dtype=torch.bfloat16,
+        )
+    ]
+    memory_obj = cast(
+        MemoryObj,
+        SimpleNamespace(
+            tensor=torch.zeros(
+                2,
+                num_layers,
+                block_size,
+                hidden_dim,
+                dtype=torch.bfloat16,
+            ),
+            metadata=SimpleNamespace(fmt=MemoryFormat.KV_2LTD),
+        ),
+    )
+
+    with pytest.raises(ValueError, match="VLLMPagedMemMUSAConnectorV2 supports"):
+        conn.to_gpu(
+            memory_obj,
+            start=0,
+            end=block_size,
+            slot_mapping=torch.arange(block_size, dtype=torch.long),
+            kvcaches=kvcaches_dst,
+        )
+
+
+def test_musa_connector_to_gpu_uses_native_when_available(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Connector skips torch scatter when the native adapter completes."""
+    num_layers = 1
+    num_blocks = 2
+    block_size = 4
+    num_heads = 1
+    head_size = 2
+    hidden_dim = num_heads * head_size
+    calls: list[str] = []
+
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(
+            model_name="musa_native_to_gpu",
+            num_layers=num_layers,
+            num_tokens=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+        ),
+    )
+    _patch_musa_connector_attrs(
+        monkeypatch,
+        conn,
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+    )
+
+    def _native_to_gpu(**_kwargs: object) -> bool:
+        calls.append("native_to_gpu")
+        return True
+
+    monkeypatch.setattr(
+        "lmcache.v1.gpu_connector.musa_connectors.try_native_to_gpu",
+        _native_to_gpu,
+    )
+
+    memory_obj = cast(
+        MemoryObj,
+        SimpleNamespace(
+            tensor=torch.ones(2, num_layers, block_size, hidden_dim),
+            metadata=SimpleNamespace(fmt=MemoryFormat.KV_2LTD),
+        ),
+    )
+    kvcaches_dst = [
+        torch.zeros(2, num_blocks, block_size, num_heads, head_size),
+    ]
+
+    conn.to_gpu(
+        memory_obj,
+        start=0,
+        end=block_size,
+        slot_mapping=torch.arange(block_size),
+        kvcaches=kvcaches_dst,
+    )
+
+    assert calls == ["native_to_gpu"]
+    assert torch.count_nonzero(kvcaches_dst[0]) == 0
+
+
+def test_musa_connector_to_gpu_falls_back_when_native_declines(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Connector keeps Stage1 torch behavior when native returns False."""
+    num_layers = 1
+    num_blocks = 2
+    block_size = 4
+    num_heads = 1
+    head_size = 2
+    hidden_dim = num_heads * head_size
+
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(
+            model_name="musa_native_fallback",
+            num_layers=num_layers,
+            num_tokens=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+        ),
+    )
+    _patch_musa_connector_attrs(
+        monkeypatch,
+        conn,
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+    )
+    monkeypatch.setattr(
+        "lmcache.v1.gpu_connector.musa_connectors.try_native_to_gpu",
+        lambda **_kwargs: False,
+    )
+
+    memory_tensor = torch.arange(
+        2 * num_layers * block_size * hidden_dim,
+        dtype=torch.float32,
+    ).reshape(2, num_layers, block_size, hidden_dim)
+    memory_obj = cast(
+        MemoryObj,
+        SimpleNamespace(
+            tensor=memory_tensor,
+            metadata=SimpleNamespace(fmt=MemoryFormat.KV_2LTD),
+        ),
+    )
+    kvcaches_dst = [
+        torch.zeros(2, num_blocks, block_size, num_heads, head_size),
+    ]
+
+    conn.to_gpu(
+        memory_obj,
+        start=0,
+        end=block_size,
+        slot_mapping=torch.arange(block_size),
+        kvcaches=kvcaches_dst,
+    )
+
+    flat_k = kvcaches_dst[0][0].reshape(num_blocks * block_size, hidden_dim)
+    assert torch.equal(flat_k[:block_size], memory_tensor[0, 0])
+
+
+def test_vllm_layerwise_musa_connector_constructs_without_torch_musa(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Layerwise construction must not require a MUSA-enabled torch build."""
+    monkeypatch.delattr(torch, "musa", raising=False)
+
+    conn = VLLMPagedMemLayerwiseMUSAConnector(
+        hidden_dim_size=64,
+        num_layers=2,
+        use_musa=False,
+        chunk_size=16,
+        dtype=torch.float32,
+        device=torch.device("cpu"),
+    )
+
+    assert tuple(conn.get_shape(num_tokens=3)) == (3, 2, 64)
+
+
+def test_musa_connector_from_gpu_uses_native_when_available(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Connector skips torch gather when the native adapter completes."""
+    num_layers = 1
+    num_blocks = 2
+    block_size = 4
+    num_heads = 1
+    head_size = 2
+    hidden_dim = num_heads * head_size
+    calls: list[str] = []
+
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(
+            model_name="musa_native_from_gpu",
+            num_layers=num_layers,
+            num_tokens=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+        ),
+    )
+    _patch_musa_connector_attrs(
+        monkeypatch,
+        conn,
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+    )
+
+    def _native_from_gpu(**_kwargs: object) -> bool:
+        calls.append("native_from_gpu")
+        return True
+
+    monkeypatch.setattr(
+        "lmcache.v1.gpu_connector.musa_connectors.try_native_from_gpu",
+        _native_from_gpu,
+    )
+
+    memory_obj = cast(
+        MemoryObj,
+        SimpleNamespace(
+            tensor=torch.zeros(2, num_layers, block_size, hidden_dim),
+            metadata=SimpleNamespace(fmt=MemoryFormat.KV_2LTD),
+        ),
+    )
+    kvcaches_src = [
+        torch.ones(2, num_blocks, block_size, num_heads, head_size),
+    ]
+
+    conn.from_gpu(
+        memory_obj,
+        start=0,
+        end=block_size,
+        slot_mapping=torch.arange(block_size),
+        kvcaches=kvcaches_src,
+    )
+
+    assert calls == ["native_from_gpu"]
+    assert torch.count_nonzero(memory_obj.tensor) == 0
+
+
+def test_vllm_layerwise_musa_batched_to_gpu_accepts_empty_batch(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Empty layerwise batches keep the generator contract without cat([])."""
+    monkeypatch.setattr(torch, "musa", _FakeMUSA(), raising=False)
+
+    num_layers = 2
+    conn = VLLMPagedMemLayerwiseMUSAConnector(
+        hidden_dim_size=4,
+        num_layers=num_layers,
+        use_musa=False,
+        chunk_size=16,
+        dtype=torch.float32,
+        device=torch.device("cpu"),
+    )
+    consumer = conn.batched_to_gpu(
+        starts=[],
+        ends=[],
+        slot_mapping=torch.empty(0, dtype=torch.long),
+        sync=True,
+        kvcaches=[torch.empty(0) for _ in range(num_layers)],
+    )
+
+    for _ in range(num_layers + 2):
+        next(consumer)
+    with pytest.raises(StopIteration):
+        next(consumer)
+
+
+@pytest.mark.parametrize("use_gpu", [False, True])
+def test_musa_connector_roundtrip_non_layerwise(use_gpu: bool):
+    """Round-trip from_gpu -> to_gpu on the non-layerwise MUSA connector."""
+    _skip_if_no_musa()
+    device = torch.device("musa:0")
+
+    num_layers = 2
+    num_blocks = 4
+    block_size = 16
+    head_size = 64
+    num_tokens = 32
+
+    kvcaches = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_layers=num_layers,
+        head_size=head_size,
+        device=device,
+    )
+
+    _, _, num_heads_actual, head_size_actual = kvcaches[0][0].shape
+    hidden_dim_actual = num_heads_actual * head_size_actual
+
+    total_slots = num_blocks * block_size
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=total_slots, num_tokens=num_tokens, device=device
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 64)
+    memobj = pin_alloc.allocate(
+        torch.Size([2, num_layers, num_tokens, hidden_dim_actual]),
+        torch.bfloat16,
+        MemoryFormat.KV_2LTD,
+    )
+
+    meta = LMCacheMetadata(
+        model_name="musa_test",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            num_layers,
+            2,
+            num_tokens,
+            num_heads_actual,
+            head_size_actual,
+        ),
+    )
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        meta,
+        use_gpu=use_gpu,
+        device=device,
+    )
+
+    try:
+        conn.from_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches,
+        )
+
+        kvcaches_dst = generate_kv_cache_paged_list_tensors(
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_layers=num_layers,
+            head_size=head_size_actual,
+            device=device,
+        )
+        for t in kvcaches_dst:
+            t.zero_()
+
+        conn.to_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches_dst,
+        )
+
+        check_paged_kv_cache_equal(
+            kvcaches,
+            kvcaches_dst,
+            slot_mapping,
+            num_heads=num_heads_actual,
+            head_size=head_size_actual,
+        )
+    finally:
+        memobj.ref_count_down()
+        pin_alloc.close()
+
+
+def test_musa_connector_to_gpu_accepts_cpu_slot_mapping() -> None:
+    """Round-trip with CPU ``slot_mapping`` and MUSA KV cache tensors."""
+    _skip_if_no_musa()
+    device = torch.device("musa:0")
+
+    num_layers = 2
+    num_blocks = 4
+    block_size = 16
+    head_size = 64
+    num_tokens = 32
+
+    kvcaches_src = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_layers=num_layers,
+        head_size=head_size,
+        device=device,
+    )
+    _, _, num_heads_actual, head_size_actual = kvcaches_src[0][0].shape
+    hidden_dim_actual = num_heads_actual * head_size_actual
+
+    slot_mapping_cpu = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=num_tokens,
+        device=torch.device("cpu"),
+    )
+    slot_mapping_musa = slot_mapping_cpu.to(device)
+
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        _make_metadata(
+            model_name="musa_test_cpu_slot_mapping",
+            num_layers=num_layers,
+            num_tokens=num_tokens,
+            num_heads=num_heads_actual,
+            head_size=head_size_actual,
+        ),
+        use_gpu=False,
+        device=device,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 64)
+    memobj = pin_alloc.allocate(
+        torch.Size([2, num_layers, num_tokens, hidden_dim_actual]),
+        torch.bfloat16,
+        MemoryFormat.KV_2LTD,
+    )
+
+    try:
+        conn.from_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping_cpu,
+            kvcaches=kvcaches_src,
+        )
+
+        kvcaches_dst = generate_kv_cache_paged_list_tensors(
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_layers=num_layers,
+            head_size=head_size_actual,
+            device=device,
+        )
+        for layer in kvcaches_dst:
+            layer.zero_()
+
+        conn.to_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping_cpu,
+            kvcaches=kvcaches_dst,
+        )
+
+        check_paged_kv_cache_equal(
+            kvcaches_src,
+            kvcaches_dst,
+            slot_mapping_musa,
+            num_heads=num_heads_actual,
+            head_size=head_size_actual,
+        )
+    finally:
+        memobj.ref_count_down()
+        pin_alloc.close()
+
+
+@pytest.mark.parametrize("use_gpu", [False, True])
+def test_musa_connector_roundtrip_layerwise(use_gpu: bool):
+    """Round-trip batched_from_gpu -> batched_to_gpu on layerwise MUSA connector."""
+    _skip_if_no_musa()
+    device = torch.device("musa:0")
+
+    num_layers = 4
+    num_blocks = 8
+    block_size = 16
+    head_size = 64
+    num_tokens = 64
+
+    kvcaches = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_layers=num_layers,
+        head_size=head_size,
+        device=device,
+    )
+
+    _, _, num_heads_actual, head_size_actual = kvcaches[0][0].shape
+    hidden_dim_actual = num_heads_actual * head_size_actual
+
+    total_slots = num_blocks * block_size
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=total_slots, num_tokens=num_tokens, device=device
+    )
+
+    meta = LMCacheMetadata(
+        model_name="musa_test_layerwise",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            num_layers,
+            2,
+            num_tokens,
+            num_heads_actual,
+            head_size_actual,
+        ),
+    )
+
+    conn = VLLMPagedMemLayerwiseMUSAConnector.from_metadata(
+        meta,
+        use_musa=use_gpu,
+        device=device,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 256)
+
+    memobjs_by_layer = [
+        [
+            pin_alloc.allocate(
+                torch.Size([num_tokens, 2, hidden_dim_actual]),
+                torch.bfloat16,
+                MemoryFormat.KV_T2D,
+            )
+        ]
+        for _ in range(num_layers)
+    ]
+
+    try:
+        gen = conn.batched_from_gpu(
+            memobjs_by_layer,
+            starts=[0],
+            ends=[num_tokens],
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches,
+        )
+
+        for _ in range(num_layers + 1):
+            next(gen)
+
+        kvcaches_dst = generate_kv_cache_paged_list_tensors(
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_layers=num_layers,
+            head_size=head_size_actual,
+            device=device,
+        )
+        for t in kvcaches_dst:
+            t.zero_()
+
+        gen2 = conn.batched_to_gpu(
+            starts=[0],
+            ends=[num_tokens],
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches_dst,
+        )
+
+        next(gen2)
+        for layer_id in range(num_layers):
+            gen2.send(memobjs_by_layer[layer_id])
+
+        next(gen2)
+
+        check_paged_kv_cache_equal(
+            kvcaches,
+            kvcaches_dst,
+            slot_mapping,
+            num_heads=num_heads_actual,
+            head_size=head_size_actual,
+        )
+    finally:
+        for layer in memobjs_by_layer:
+            for m in layer:
+                m.ref_count_down()
+        pin_alloc.close()
+
+
+@pytest.mark.parametrize("use_gpu", [False, True])
+def test_musa_connector_roundtrip_non_layerwise_multi_chunk(
+    use_gpu: bool,
+) -> None:
+    """Non-layerwise multi-chunk round-trip on MUSA connector."""
+    _skip_if_no_musa()
+    device = torch.device("musa:0")
+
+    num_layers = 2
+    num_blocks = 6
+    block_size = 8
+    head_size = 64
+    total_tokens = 32
+
+    starts = [0, 7, 19]
+    ends = [4, 13, 25]
+
+    kvcaches = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_layers=num_layers,
+        head_size=head_size,
+        device=device,
+    )
+    _, _, num_heads_actual, head_size_actual = kvcaches[0][0].shape
+    hidden_dim_actual = num_heads_actual * head_size_actual
+
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=total_tokens,
+        device=device,
+    )
+    packed_slot_mapping = _pack_slot_mapping(slot_mapping, starts, ends)
+
+    meta = LMCacheMetadata(
+        model_name="musa_test_non_layerwise_multi_chunk",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            num_layers,
+            2,
+            total_tokens,
+            num_heads_actual,
+            head_size_actual,
+        ),
+    )
+    conn = VLLMPagedMemMUSAConnectorV2.from_metadata(
+        meta,
+        use_gpu=use_gpu,
+        device=device,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 64)
+    memobjs = []
+    try:
+        for s, e in zip(starts, ends, strict=False):
+            n = e - s
+            memobj = pin_alloc.allocate(
+                torch.Size([2, num_layers, n, hidden_dim_actual]),
+                torch.bfloat16,
+                MemoryFormat.KV_2LTD,
+            )
+            conn.from_gpu(
+                memobj,
+                start=s,
+                end=e,
+                slot_mapping=slot_mapping,
+                kvcaches=kvcaches,
+            )
+            memobjs.append((s, e, memobj))
+
+        kvcaches_dst = generate_kv_cache_paged_list_tensors(
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_layers=num_layers,
+            head_size=head_size_actual,
+            device=device,
+        )
+        for layer in kvcaches_dst:
+            layer.zero_()
+
+        for s, e, memobj in memobjs:
+            conn.to_gpu(
+                memobj,
+                start=s,
+                end=e,
+                slot_mapping=slot_mapping,
+                kvcaches=kvcaches_dst,
+            )
+
+        check_paged_kv_cache_equal(
+            kvcaches,
+            kvcaches_dst,
+            packed_slot_mapping,
+            num_heads=num_heads_actual,
+            head_size=head_size_actual,
+        )
+    finally:
+        for _, _, memobj in memobjs:
+            memobj.ref_count_down()
+        pin_alloc.close()
+
+
+@pytest.mark.parametrize("use_musa", [False, True])
+def test_musa_connector_roundtrip_layerwise_multi_chunk(
+    use_musa: bool,
+) -> None:
+    """Layerwise multi-chunk round-trip on MUSA connector."""
+    _skip_if_no_musa()
+    device = torch.device("musa:0")
+
+    num_layers = 4
+    num_blocks = 8
+    block_size = 8
+    head_size = 64
+    total_tokens = 40
+
+    starts = [0, 9, 21]
+    ends = [5, 15, 30]
+
+    kvcaches = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_layers=num_layers,
+        head_size=head_size,
+        device=device,
+    )
+
+    _, _, num_heads_actual, head_size_actual = kvcaches[0][0].shape
+    hidden_dim_actual = num_heads_actual * head_size_actual
+
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=total_tokens,
+        device=device,
+    )
+    packed_slot_mapping = _pack_slot_mapping(slot_mapping, starts, ends)
+
+    meta = LMCacheMetadata(
+        model_name="musa_test_layerwise_multi_chunk",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(
+            num_layers,
+            2,
+            total_tokens,
+            num_heads_actual,
+            head_size_actual,
+        ),
+    )
+    conn = VLLMPagedMemLayerwiseMUSAConnector.from_metadata(
+        meta,
+        use_musa=use_musa,
+        device=device,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 128)
+    memobjs_by_layer = []
+    for _ in range(num_layers):
+        per_layer = []
+        for s, e in zip(starts, ends, strict=False):
+            n = e - s
+            per_layer.append(
+                pin_alloc.allocate(
+                    torch.Size([n, 2, hidden_dim_actual]),
+                    torch.bfloat16,
+                    MemoryFormat.KV_T2D,
+                )
+            )
+        memobjs_by_layer.append(per_layer)
+
+    try:
+        producer = conn.batched_from_gpu(
+            memobjs_by_layer,
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches,
+        )
+        for _ in range(num_layers + 1):
+            next(producer)
+
+        if use_musa:
+            assert conn.gpu_buffer_allocator is not None
+        else:
+            assert conn.gpu_buffer_allocator is None
+
+        kvcaches_dst = generate_kv_cache_paged_list_tensors(
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_layers=num_layers,
+            head_size=head_size_actual,
+            device=device,
+        )
+        for layer in kvcaches_dst:
+            layer.zero_()
+
+        consumer = conn.batched_to_gpu(
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches_dst,
+        )
+        next(consumer)
+        for layer_id in range(num_layers):
+            consumer.send(memobjs_by_layer[layer_id])
+        next(consumer)
+
+        check_paged_kv_cache_equal(
+            kvcaches,
+            kvcaches_dst,
+            packed_slot_mapping,
+            num_heads=num_heads_actual,
+            head_size=head_size_actual,
+        )
+    finally:
+        for layer in memobjs_by_layer:
+            for memobj in layer:
+                memobj.ref_count_down()
+        pin_alloc.close()
diff --git a/tests/v1/test_musa_mp_handle.py b/tests/v1/test_musa_mp_handle.py
new file mode 100644
index 0000000..cce2653
--- /dev/null
+++ b/tests/v1/test_musa_mp_handle.py
@@ -0,0 +1,244 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from types import SimpleNamespace
+from typing import cast
+import importlib
+
+# Third Party
+import pytest
+import torch
+
+
+class _FakeMusaEvent:
+    """Minimal TorchMUSA Event facade for capability-gate tests."""
+
+    def __init__(self, interprocess: bool = False) -> None:
+        self.interprocess = interprocess
+
+    @classmethod
+    def from_ipc_handle(cls, _device: object, _handle: bytes) -> "_FakeMusaEvent":
+        """Reconstruct an event from an IPC handle."""
+        return cls(interprocess=True)
+
+
+class _FakeDevice:
+    """Minimal device object exposing only ``type`` for factory routing tests."""
+
+    type = "musa"
+
+
+class _FakeMusaTensor:
+    """Minimal tensor-like object exposing a MUSA device for routing tests."""
+
+    device = _FakeDevice()
+
+
+def _fake_musa_kv_caches() -> dict[str, torch.Tensor]:
+    """Return a typed KV cache mapping backed by a minimal MUSA tensor facade."""
+    return cast(dict[str, torch.Tensor], {"layer_0": _FakeMusaTensor()})
+
+
+def test_musa_handle_transfer_disabled_by_default(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Stage4 MUSA handle transfer is opt-in and unavailable by default."""
+    # First Party
+    from lmcache.v1.platform.musa import ipc
+
+    monkeypatch.delenv(ipc.ENV_MUSA_HANDLE_TRANSFER, raising=False)
+
+    assert ipc.is_musa_handle_transfer_enabled() is False
+    assert ipc.is_musa_handle_transfer_available() is False
+
+
+def test_musa_handle_transfer_requires_torch_musa(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Opt-in alone is not enough without a visible TorchMUSA runtime."""
+    # First Party
+    from lmcache.v1.platform.musa import ipc
+
+    monkeypatch.setenv(ipc.ENV_MUSA_HANDLE_TRANSFER, "1")
+    monkeypatch.setattr(ipc, "is_torch_musa_available", lambda: False)
+
+    assert ipc.is_musa_handle_transfer_available() is False
+
+
+def test_get_torch_musa_module_imports_torch_musa_registration(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """TorchMUSA may register ``torch.musa`` only after ``torch_musa`` import."""
+    # First Party
+    from lmcache.v1.platform.musa import ipc
+
+    fake_torch = SimpleNamespace()
+    torch_musa = SimpleNamespace(is_available=lambda: True)
+
+    def import_module(name: str) -> object:
+        assert name == "torch_musa"
+        fake_torch.musa = torch_musa
+        return SimpleNamespace()
+
+    monkeypatch.setattr(ipc, "torch", fake_torch)
+    monkeypatch.setattr(ipc.importlib, "import_module", import_module)
+
+    assert ipc.get_torch_musa_module() is torch_musa
+    assert ipc.is_torch_musa_available() is True
+
+
+def test_musa_handle_transfer_requires_event_and_block_transfer_capabilities(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Memory IPC alone is not enough to enable the MUSA handle path."""
+    # First Party
+    from lmcache.v1.platform.musa import ipc
+
+    torch_musa = SimpleNamespace(
+        ipc_get_mem_handle=lambda _tensor: b"handle",
+        ipc_open_mem_handle=lambda _handle, nbytes, _device: torch.empty(
+            nbytes,
+            dtype=torch.uint8,
+        ),
+    )
+
+    monkeypatch.setenv(ipc.ENV_MUSA_HANDLE_TRANSFER, "1")
+    monkeypatch.setattr(ipc, "is_torch_musa_available", lambda: True)
+    monkeypatch.setattr(ipc, "get_torch_musa_module", lambda: torch_musa)
+
+    assert ipc.check_torch_musa_ipc_support(torch_musa) is True
+    assert ipc.check_torch_musa_event_support(torch_musa) is False
+    assert ipc.is_musa_handle_transfer_available() is False
+
+
+def test_musa_handle_transfer_available_when_all_capabilities_present(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Forced MUSA handle mode is available only after all gates pass."""
+    # First Party
+    from lmcache.v1.platform.musa import ipc
+
+    torch_musa = SimpleNamespace(
+        ipc_get_mem_handle=lambda _tensor: b"handle",
+        ipc_open_mem_handle=lambda _handle, nbytes, _device: torch.empty(
+            nbytes,
+            dtype=torch.uint8,
+        ),
+        Event=_FakeMusaEvent,
+    )
+
+    monkeypatch.setenv(ipc.ENV_MUSA_HANDLE_TRANSFER, "1")
+    monkeypatch.setattr(ipc, "is_torch_musa_available", lambda: True)
+    monkeypatch.setattr(ipc, "get_torch_musa_module", lambda: torch_musa)
+    monkeypatch.setattr(ipc, "is_musa_block_transfer_available", lambda: True)
+
+    assert ipc.check_torch_musa_ipc_support(torch_musa) is True
+    assert ipc.check_torch_musa_event_support(torch_musa) is True
+    assert ipc.is_musa_handle_transfer_available() is True
+
+
+def test_musa_handle_transfer_rejects_incomplete_torch_musa_runtime() -> None:
+    """Missing TorchMUSA IPC symbols keep Stage4 handle mode disabled."""
+    # First Party
+    from lmcache.v1.platform.musa import ipc
+
+    torch_musa = SimpleNamespace(ipc_get_mem_handle=lambda _tensor: b"handle")
+
+    assert ipc.check_torch_musa_ipc_support(torch_musa) is False
+
+
+def test_musa_platform_discovers_factory_and_registers_capability_predicate() -> None:
+    """The MUSA wrapper is auto-discovered while availability stays explicit."""
+    # First Party
+    from lmcache.v1.platform import _registry as platform_registry
+    from lmcache.v1.platform import get_device_spec
+    import lmcache.v1.platform.musa as musa_platform
+
+    snapshot = platform_registry.snapshot()
+    try:
+        platform_registry.reset_for_tests()
+        importlib.reload(musa_platform)
+
+        factory = platform_registry.get_kv_wrapper_factory("musa")
+
+        device_spec = get_device_spec("musa")
+        assert device_spec is not None
+        assert device_spec.is_handle_transfer_available() is False
+        assert callable(factory)
+        with pytest.raises(ValueError, match="expected a MUSA tensor"):
+            factory(torch.empty(1))
+    finally:
+        platform_registry.restore(snapshot)
+
+
+def test_create_transfer_context_auto_keeps_musa_on_data_path() -> None:
+    """Stage4 must not silently switch MUSA auto mode away from Stage3 data path."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        EngineDrivenTransferContext,
+        create_transfer_context,
+    )
+
+    context = create_transfer_context(_fake_musa_kv_caches())
+
+    assert isinstance(context, EngineDrivenTransferContext)
+
+
+def test_create_transfer_context_musa_handle_requires_capability() -> None:
+    """Forced MUSA handle mode fails closed when the Stage4 capability is absent."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import create_transfer_context
+
+    with pytest.raises(ValueError, match="not available"):
+        create_transfer_context(_fake_musa_kv_caches(), mode="lmcache_driven")
+
+
+def test_create_transfer_context_musa_handle_allowed_when_available(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Forced MUSA handle mode is allowed once the platform reports capability."""
+    # First Party
+    from lmcache.v1.multiprocess.transfer_context import (
+        LMCacheDrivenTransferContext,
+        create_transfer_context,
+    )
+    from lmcache.v1.platform import _registry as platform_registry
+    from lmcache.v1.platform import get_device_spec
+
+    snapshot = platform_registry.snapshot()
+    try:
+        platform_registry.register_kv_wrapper("musa", lambda tensor: tensor)
+        musa_spec = get_device_spec("musa")
+        if musa_spec:
+            monkeypatch.setattr(musa_spec, "is_handle_transfer_available", lambda: True)
+
+        context = create_transfer_context(
+            _fake_musa_kv_caches(),
+            mode="lmcache_driven",
+        )
+    finally:
+        platform_registry.restore(snapshot)
+
+    assert isinstance(context, LMCacheDrivenTransferContext)
+
+
+def test_musa_ipc_wrapper_rejects_non_musa_tensor() -> None:
+    """The MUSA IPC wrapper never accepts CPU tensors by accident."""
+    # First Party
+    from lmcache.v1.platform.musa.ipc import MusaIPCWrapper
+
+    with pytest.raises(ValueError, match="expected a MUSA tensor"):
+        MusaIPCWrapper(torch.empty(4))
+
+
+def test_musa_ipc_wrapper_uses_device_agnostic_wire_base() -> None:
+    """Stage4 uses the device-agnostic KVCache wire base for MUSA handles."""
+    # First Party
+    from lmcache.v1.multiprocess.custom_types import DeviceIPCWrapper, KVCache
+    from lmcache.v1.platform.cuda.ipc_wrapper import CudaIPCWrapper
+    from lmcache.v1.platform.musa.ipc import MusaIPCWrapper
+
+    assert issubclass(MusaIPCWrapper, DeviceIPCWrapper)
+    assert not issubclass(MusaIPCWrapper, CudaIPCWrapper)
+    assert MusaIPCWrapper.device_type == "musa"
+    assert KVCache == list[DeviceIPCWrapper]
diff --git a/tests/v1/test_musa_native.py b/tests/v1/test_musa_native.py
new file mode 100644
index 0000000..9497590
--- /dev/null
+++ b/tests/v1/test_musa_native.py
@@ -0,0 +1,457 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from types import ModuleType, SimpleNamespace
+from typing import Any, cast
+import sys
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.platform.musa import native_kv_transfer as musa_native
+import lmcache.python_ops_fallback as py_ops
+
+
+def _make_native_module() -> ModuleType:
+    """Create a fake native module with the Stage2 LMCache ABI."""
+    module = ModuleType("musa_aiter")
+    module.native_lmcache_kv_transfer_abi_version = lambda: 1  # type: ignore[attr-defined]
+    module.lmcache_kv_paged_to_buffer = lambda *args, **kwargs: True  # type: ignore[attr-defined]
+    module.lmcache_kv_buffer_to_paged = lambda *args, **kwargs: True  # type: ignore[attr-defined]
+    module.lmcache_mla_paged_to_buffer = lambda *args, **kwargs: True  # type: ignore[attr-defined]
+    module.lmcache_mla_buffer_to_paged = lambda *args, **kwargs: True  # type: ignore[attr-defined]
+    return module
+
+
+def _make_block_shape_desc(
+    *,
+    num_layers: int = 2,
+    num_blocks: int = 4,
+    block_size: int = 4,
+    num_heads: int = 2,
+    head_size: int = 8,
+) -> py_ops.PageBufferShapeDesc:
+    """Create a page-buffer shape descriptor for block-transfer tests."""
+    shape_desc = py_ops.PageBufferShapeDesc()
+    shape_desc.nl = num_layers
+    shape_desc.nb = num_blocks
+    shape_desc.bs = block_size
+    shape_desc.nh = num_heads
+    shape_desc.hs = head_size
+    shape_desc.element_size = torch.empty((), dtype=torch.float32).element_size()
+    shape_desc.kv_size = 2
+    return shape_desc
+
+
+def test_native_transfer_disabled_by_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Native MUSA transfer is opt-in so Stage1 behavior remains unchanged."""
+    monkeypatch.delenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", raising=False)
+
+    assert musa_native.is_native_musa_kv_transfer_enabled() is False
+
+
+def test_native_transfer_module_lives_under_musa_platform() -> None:
+    """The native KV-transfer adapter belongs to the MUSA platform package."""
+    assert musa_native.__name__ == "lmcache.v1.platform.musa.native_kv_transfer"
+
+
+def test_get_backend_prefers_musa_ops_over_cuda_when_musa_is_available(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Backend composition follows device detection priority when MUSA is active."""
+    # Standard
+    import os
+
+    # First Party
+    from lmcache.v1.platform import _detect_device, get_backend
+    from lmcache.v1.platform.musa import ops as musa_ops
+
+    os.environ["DEVICE_TYPE"] = "musa"
+    monkeypatch.setattr(torch.cuda, "is_available", lambda: True)
+    monkeypatch.setattr(
+        torch,
+        "musa",
+        SimpleNamespace(is_available=lambda: True),
+        raising=False,
+    )
+
+    dev, dev_type = _detect_device()
+
+    assert dev_type == "musa"
+    backend = get_backend(dev_type)
+    assert backend is not None
+    assert backend.multi_layer_block_kv_transfer is (
+        musa_ops.multi_layer_block_kv_transfer
+    )
+    del os.environ["DEVICE_TYPE"]
+
+
+def test_native_transfer_enabled_by_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The opt-in environment variable enables native dispatch attempts."""
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+
+    assert musa_native.is_native_musa_kv_transfer_enabled() is True
+
+
+def test_load_native_module_returns_none_when_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Missing optional ``musa_aiter`` must not break LMCache imports."""
+    monkeypatch.setitem(cast(dict[str, Any], sys.modules), "musa_aiter", None)
+
+    assert musa_native.load_native_musa_module() is None
+
+
+def test_check_native_abi_requires_expected_symbols() -> None:
+    """LMCache accepts only the Stage2 LMCache-compatible native ABI."""
+    assert musa_native.check_native_abi(_make_native_module()) is True
+
+
+def test_check_native_abi_rejects_missing_symbol() -> None:
+    """The adapter falls back when the optional native module is incomplete."""
+    module = SimpleNamespace(native_lmcache_kv_transfer_abi_version=lambda: 1)
+
+    assert musa_native.check_native_abi(module) is False
+
+
+def test_check_native_abi_rejects_non_callable_symbol() -> None:
+    """Native symbols must be callable to be considered ABI-compatible."""
+    module = _make_native_module()
+    module.lmcache_kv_buffer_to_paged = object()  # type: ignore[attr-defined]
+
+    assert musa_native.check_native_abi(module) is False
+
+
+def test_try_native_to_gpu_calls_non_mla_symbol(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Non-MLA scatter uses the LMCache-compatible buffer-to-paged call."""
+    calls: list[tuple[str, tuple[Any, ...], dict[str, Any]]] = []
+    module = _make_native_module()
+
+    def _buffer_to_paged(*args: Any, **kwargs: Any) -> bool:
+        calls.append(("buffer_to_paged", args, kwargs))
+        return True
+
+    module.lmcache_kv_buffer_to_paged = _buffer_to_paged  # type: ignore[attr-defined]
+    monkeypatch.setattr(musa_native, "load_native_musa_module", lambda: module)
+    monkeypatch.setattr(musa_native, "_native_tensors_ready", lambda *args: True)
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+
+    used = musa_native.try_native_to_gpu(
+        use_mla=False,
+        memory_tensor=torch.empty(2, 1, 4, 8),
+        kvcaches=[torch.empty(2, 2, 2, 2, 4)],
+        slot_mapping=torch.arange(4),
+        start=0,
+        end=4,
+        skip_prefix_n_tokens=0,
+        block_size=2,
+        num_heads=2,
+        head_size=4,
+    )
+
+    assert used is True
+    assert calls[0][0] == "buffer_to_paged"
+    assert torch.equal(calls[0][1][2], torch.arange(4))
+    assert calls[0][1][3] == 0
+
+
+def test_try_native_to_gpu_returns_true_for_empty_range(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """An empty native transfer is a completed no-op after ABI is ready."""
+    module = _make_native_module()
+    monkeypatch.setattr(musa_native, "load_native_musa_module", lambda: module)
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+
+    assert musa_native.try_native_to_gpu(
+        use_mla=False,
+        memory_tensor=torch.empty(2, 1, 4, 8),
+        kvcaches=[torch.empty(2, 2, 2, 2, 4)],
+        slot_mapping=torch.arange(4),
+        start=0,
+        end=4,
+        skip_prefix_n_tokens=4,
+        block_size=2,
+        num_heads=2,
+        head_size=4,
+    )
+
+
+def test_try_native_to_gpu_rejects_cpu_tensors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Native dispatch must not consume CPU tensors through musa_aiter fallback."""
+    module = _make_native_module()
+    monkeypatch.setattr(musa_native, "load_native_musa_module", lambda: module)
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+
+    used = musa_native.try_native_to_gpu(
+        use_mla=False,
+        memory_tensor=torch.empty(2, 1, 4, 8),
+        kvcaches=[torch.empty(2, 2, 2, 2, 4)],
+        slot_mapping=torch.arange(4),
+        start=0,
+        end=4,
+        skip_prefix_n_tokens=0,
+        block_size=2,
+        num_heads=2,
+        head_size=4,
+    )
+
+    assert used is False
+
+
+def test_try_native_from_gpu_falls_back_on_native_exception(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Native failures must return False so callers keep the torch fallback."""
+    module = _make_native_module()
+
+    def _paged_to_buffer(*args: Any, **kwargs: Any) -> bool:
+        raise RuntimeError("native boom")
+
+    module.lmcache_kv_paged_to_buffer = _paged_to_buffer  # type: ignore[attr-defined]
+    monkeypatch.setattr(musa_native, "load_native_musa_module", lambda: module)
+    monkeypatch.setattr(musa_native, "_native_tensors_ready", lambda *args: True)
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+
+    used = musa_native.try_native_from_gpu(
+        use_mla=False,
+        memory_tensor=torch.empty(2, 1, 4, 8),
+        kvcaches=[torch.empty(2, 2, 2, 2, 4)],
+        slot_mapping=torch.arange(4),
+        start=0,
+        end=4,
+        block_size=2,
+        num_heads=2,
+        head_size=4,
+    )
+
+    assert used is False
+
+
+def test_try_native_from_gpu_rejects_cpu_tensors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Native gather must not consume CPU tensors through musa_aiter fallback."""
+    module = _make_native_module()
+    monkeypatch.setattr(musa_native, "load_native_musa_module", lambda: module)
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+
+    used = musa_native.try_native_from_gpu(
+        use_mla=False,
+        memory_tensor=torch.empty(2, 1, 4, 8),
+        kvcaches=[torch.empty(2, 2, 2, 2, 4)],
+        slot_mapping=torch.arange(4),
+        start=0,
+        end=4,
+        block_size=2,
+        num_heads=2,
+        head_size=4,
+    )
+
+    assert used is False
+
+
+def test_native_block_gather_uses_device_staging_for_cpu_out(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Block-level native gather stages CPU output and expands slot IDs."""
+    paged_layers = [torch.zeros(4, 4, 16) for _ in range(2)]
+    out = torch.zeros(2, 8, 16)
+    captured: dict[str, Any] = {}
+
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+    monkeypatch.setattr(
+        musa_native, "_is_musa_block_transfer_candidate", lambda *_args: True
+    )
+
+    def _fake_native_from_gpu(**kwargs: Any) -> bool:
+        memory_tensor = kwargs["memory_tensor"]
+        captured["used_cpu_out_directly"] = memory_tensor is out
+        captured["slot_mapping"] = kwargs["slot_mapping"].cpu()
+        memory_tensor.fill_(7.0)
+        return True
+
+    monkeypatch.setattr(musa_native, "try_native_from_gpu", _fake_native_from_gpu)
+
+    used = musa_native.try_native_multi_layer_block_kv_transfer(
+        paged_layers=paged_layers,
+        object_tensors=[out],
+        block_ids=[2, 4],
+        direction=py_ops.TransferDirection.D2H,
+        shape_desc=_make_block_shape_desc(head_size=16),
+        lmcache_chunk_size=8,
+        engine_kv_format=py_ops.EngineKVFormat.NL_X_NB_BS_HS,
+        skip_prefix_n_blocks=0,
+    )
+
+    assert used is True
+    assert captured["used_cpu_out_directly"] is False
+    assert torch.equal(
+        captured["slot_mapping"], torch.tensor([8, 9, 10, 11, 16, 17, 18, 19])
+    )
+    assert torch.all(out == 7.0)
+
+
+def test_native_block_scatter_uses_device_staging_for_cpu_chunks(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Block-level native scatter must not pass CPU/SHM chunks directly."""
+    paged_layers = [torch.zeros(4, 4, 16) for _ in range(2)]
+    chunk = torch.zeros(2, 8, 16)
+    captured: dict[str, bool] = {}
+
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+    monkeypatch.setattr(
+        musa_native, "_is_musa_block_transfer_candidate", lambda *_args: True
+    )
+
+    def _fake_native_to_gpu(**kwargs: Any) -> bool:
+        captured["used_cpu_chunk_directly"] = kwargs["memory_tensor"] is chunk
+        return True
+
+    monkeypatch.setattr(musa_native, "try_native_to_gpu", _fake_native_to_gpu)
+
+    used = musa_native.try_native_multi_layer_block_kv_transfer(
+        paged_layers=paged_layers,
+        object_tensors=[chunk],
+        block_ids=[0, 1],
+        direction=py_ops.TransferDirection.H2D,
+        shape_desc=_make_block_shape_desc(head_size=16),
+        lmcache_chunk_size=8,
+        engine_kv_format=py_ops.EngineKVFormat.NL_X_NB_BS_HS,
+        skip_prefix_n_blocks=0,
+    )
+
+    assert used is True
+    assert captured["used_cpu_chunk_directly"] is False
+
+
+def test_native_block_scatter_uses_whole_block_skip(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Block-level native scatter receives skip offsets in whole-block tokens."""
+    paged_layers = [torch.zeros(4, 4, 16) for _ in range(2)]
+    chunk = torch.zeros(2, 8, 16)
+    captured: dict[str, int] = {}
+
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+    monkeypatch.setattr(
+        musa_native, "_is_musa_block_transfer_candidate", lambda *_args: True
+    )
+
+    def _fake_native_to_gpu(**kwargs: Any) -> bool:
+        captured["skip_prefix_n_tokens"] = kwargs["skip_prefix_n_tokens"]
+        return True
+
+    monkeypatch.setattr(musa_native, "try_native_to_gpu", _fake_native_to_gpu)
+
+    used = musa_native.try_native_multi_layer_block_kv_transfer(
+        paged_layers=paged_layers,
+        object_tensors=[chunk],
+        block_ids=[0, 1],
+        direction=py_ops.TransferDirection.H2D,
+        shape_desc=_make_block_shape_desc(head_size=16),
+        lmcache_chunk_size=8,
+        engine_kv_format=py_ops.EngineKVFormat.NL_X_NB_BS_HS,
+        skip_prefix_n_blocks=1,
+    )
+
+    assert used is True
+    assert captured["skip_prefix_n_tokens"] == 4
+
+
+def test_native_block_gather_skips_native_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Block-level native gather is not attempted when env opt-in is disabled."""
+    paged_layers = [torch.zeros(4, 4, 16) for _ in range(2)]
+
+    monkeypatch.delenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", raising=False)
+    monkeypatch.setattr(
+        musa_native, "_is_musa_block_transfer_candidate", lambda *_args: True
+    )
+
+    def _raise_if_called(**_kwargs: Any) -> bool:
+        raise AssertionError("native path should not be called when disabled")
+
+    monkeypatch.setattr(musa_native, "try_native_from_gpu", _raise_if_called)
+
+    used = musa_native.try_native_multi_layer_block_kv_transfer(
+        paged_layers=paged_layers,
+        object_tensors=[torch.zeros(2, 8, 16)],
+        block_ids=[0, 1],
+        direction=py_ops.TransferDirection.D2H,
+        shape_desc=_make_block_shape_desc(head_size=16),
+        lmcache_chunk_size=8,
+        engine_kv_format=py_ops.EngineKVFormat.NL_X_NB_BS_HS,
+        skip_prefix_n_blocks=0,
+    )
+
+    assert used is False
+
+
+def test_native_block_transfer_rejects_unvalidated_layout(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Unsupported MUSA layouts fall back below the device-layer entry."""
+    monkeypatch.setenv("LMCACHE_MUSA_NATIVE_KV_TRANSFER", "1")
+    monkeypatch.setattr(
+        musa_native, "_is_musa_block_transfer_candidate", lambda *_args: True
+    )
+
+    used = musa_native.try_native_multi_layer_block_kv_transfer(
+        paged_layers=[torch.zeros(2, 4, 2, 4, 8)],
+        object_tensors=[torch.zeros(2, 2, 8, 16)],
+        block_ids=[0, 1],
+        direction=py_ops.TransferDirection.H2D,
+        shape_desc=_make_block_shape_desc(),
+        lmcache_chunk_size=8,
+        engine_kv_format=py_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS,
+        skip_prefix_n_blocks=0,
+    )
+
+    assert used is False
+
+
+def test_musa_ops_block_transfer_entry_dispatches_to_musa_platform(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """MUSA ops backend hides native dispatch behind the c_ops-compatible API."""
+    # First Party
+    from lmcache.v1.platform.musa import ops as musa_ops
+
+    captured: dict[str, Any] = {}
+
+    def _fake_musa_block_transfer(**kwargs: Any) -> bool:
+        captured.update(kwargs)
+        return True
+
+    monkeypatch.setattr(
+        musa_native,
+        "try_native_multi_layer_block_kv_transfer",
+        _fake_musa_block_transfer,
+    )
+
+    paged_layers = [torch.zeros(4, 4, 16) for _ in range(2)]
+    object_tensors = [torch.zeros(2, 8, 16)]
+    musa_ops.multi_layer_block_kv_transfer(
+        paged_layers,
+        object_tensors,
+        [0, 1],
+        "musa",
+        py_ops.TransferDirection.D2H,
+        _make_block_shape_desc(head_size=16),
+        8,
+        py_ops.EngineKVFormat.NL_X_NB_BS_HS,
+        0,
+    )
+
+    assert captured["paged_layers"] is paged_layers
+    assert captured["object_tensors"] is object_tensors
+    assert captured["block_ids"] == [0, 1]
diff --git a/tests/v1/test_musa_support.py b/tests/v1/test_musa_support.py
new file mode 100644
index 0000000..14bef54
--- /dev/null
+++ b/tests/v1/test_musa_support.py
@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+MUSA support unit tests that do not require MUSA hardware.
+
+These tests cover the design contract documented in
+``docs/source/developer_guide/musa_support_design.rst``:
+
+- Device detection via the registry-driven
+  :func:`lmcache.v1.platform._detect_device`.
+- Factory dispatch in :func:`lmcache.v1.gpu_connector.CreateGPUConnector`,
+  including fail-fast validation when device-scoped features are requested on
+  accelerators without connector support.
+
+The tests stub ``torch_device_type`` / ``torch_dev`` (rather than mutating
+the global PyTorch namespace) so they run on any platform.
+"""
+
+# Standard
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import patch
+import importlib
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import EngineType
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector import CreateGPUConnector
+from lmcache.v1.metadata import LMCacheMetadata
+import lmcache as lmc
+import lmcache.v1.gpu_connector as gpu_connector_module
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_metadata() -> LMCacheMetadata:
+    """Minimal metadata accepted by ``CreateGPUConnector``."""
+    return LMCacheMetadata(
+        model_name="musa_support_test",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(2, 2, 16, 8, 64),
+    )
+
+
+def _make_config(**overrides: Any) -> LMCacheEngineConfig:
+    """Default config plus the requested overrides."""
+    config = LMCacheEngineConfig.from_defaults(chunk_size=16)
+    for key, value in overrides.items():
+        setattr(config, key, value)
+    return config
+
+
+class _FakeTorchDev:
+    """Stand-in for ``torch.musa`` / ``torch.xpu`` / ``torch.cuda``."""
+
+    def __init__(self, device_count: int = 1) -> None:
+        self._device_count = device_count
+
+    def is_available(self) -> bool:
+        return True
+
+    def device_count(self) -> int:
+        return self._device_count
+
+    def current_device(self) -> int:
+        return 0
+
+    def set_device(self, _idx: int) -> None:
+        return
+
+
+def _patch_device(monkeypatch: pytest.MonkeyPatch, device_type: str) -> None:
+    """Pretend the current accelerator is ``device_type`` in the factory."""
+    monkeypatch.setattr(gpu_connector_module, "torch_device_type", device_type)
+    monkeypatch.setattr(gpu_connector_module, "torch_dev", _FakeTorchDev())
+
+
+# ---------------------------------------------------------------------------
+# _detect_device
+# ---------------------------------------------------------------------------
+
+
+class _StubTorch:
+    """Minimal stand-in for ``torch`` exposing only what ``_detect_device`` reads."""
+
+    def __init__(
+        self,
+        *,
+        has_musa: bool = False,
+        has_xpu: bool = False,
+        has_hpu: bool = False,
+        musa_available: bool = False,
+        xpu_available: bool = False,
+        hpu_available: bool = False,
+    ) -> None:
+        self.cuda = SimpleNamespace(is_available=lambda: True)
+        if has_musa:
+            self.musa = SimpleNamespace(is_available=lambda: musa_available)
+        if has_xpu:
+            self.xpu = SimpleNamespace(is_available=lambda: xpu_available)
+        if has_hpu:
+            self.hpu = SimpleNamespace(is_available=lambda: hpu_available)
+
+
+def _detect_with_stub(stub: _StubTorch) -> tuple[Any, str]:
+    """Run ``_detect_device`` with ``torch`` swapped for the stub."""
+    # First Party
+    from lmcache.v1.platform import _detect_device
+
+    with patch.dict("sys.modules", {"torch": stub}):
+        return _detect_device()
+
+
+def test_detect_device_prefers_musa_when_available() -> None:
+    """``_detect_device`` returns MUSA whenever ``torch.musa.is_available()``."""
+    # Standard
+    import os
+
+    os.environ["DEVICE_TYPE"] = "musa"
+    stub = _StubTorch(
+        has_musa=True,
+        has_xpu=True,
+        has_hpu=True,
+        musa_available=True,
+        xpu_available=True,
+        hpu_available=True,
+    )
+    dev, name = _detect_with_stub(stub)
+    assert name == "musa"
+    assert dev is stub.musa
+    del os.environ["DEVICE_TYPE"]
+
+
+def test_detect_device_falls_back_past_unavailable_musa() -> None:
+    """Falls through MUSA when ``torch.musa.is_available()`` is False."""
+    # Standard
+    import os
+
+    os.environ["DEVICE_TYPE"] = "musa"
+    stub = _StubTorch(
+        has_musa=True,
+        musa_available=False,
+    )
+    _, name = _detect_with_stub(stub)
+    assert name == "cuda"
+    del os.environ["DEVICE_TYPE"]
+
+
+def test_detect_device_cuda_fallback_when_no_alt_accelerator() -> None:
+    """Default fallback is CUDA so existing CUDA tests/paths keep working."""
+    stub = _StubTorch()
+    dev, name = _detect_with_stub(stub)
+    assert name == "cuda"
+    assert dev is stub.cuda
+
+
+# ---------------------------------------------------------------------------
+# CreateGPUConnector: MUSA branch + device-scoped feature guards
+# ---------------------------------------------------------------------------
+
+
+def test_create_gpu_connector_blending_rejected_on_musa(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``enable_blending`` must fail fast on MUSA."""
+    _patch_device(monkeypatch, "musa")
+    config = _make_config(enable_blending=True, use_layerwise=True)
+    metadata = _make_metadata()
+    with pytest.raises(ValueError, match="enable_blending"):
+        CreateGPUConnector(config, metadata, EngineType.VLLM)
+
+
+@pytest.mark.parametrize("device_type", ["musa", "hpu"])
+def test_create_gpu_connector_blending_rejected_on_unsupported_devices(
+    monkeypatch: pytest.MonkeyPatch, device_type: str
+) -> None:
+    """The blending guard rejects devices without a blending connector."""
+    _patch_device(monkeypatch, device_type)
+    config = _make_config(enable_blending=True, use_layerwise=True)
+    metadata = _make_metadata()
+    with pytest.raises(ValueError, match="enable_blending"):
+        CreateGPUConnector(config, metadata, EngineType.VLLM)
+
+
+def test_create_gpu_connector_v3_rejected_on_musa(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``use_gpu_connector_v3`` must fail fast on MUSA."""
+    _patch_device(monkeypatch, "musa")
+    config = _make_config(use_gpu_connector_v3=True)
+    metadata = _make_metadata()
+    with pytest.raises(ValueError, match="use_gpu_connector_v3"):
+        CreateGPUConnector(config, metadata, EngineType.VLLM)
+
+
+def test_create_gpu_connector_layerwise_rejected_on_hpu(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """HPU ships only ``VLLMPagedMemHPUConnectorV2`` (no layerwise variant).
+
+    Previously, ``use_layerwise=True`` on HPU silently fell through into
+    ``VLLMPagedMemLayerwiseGPUConnector`` — the CUDA layerwise connector —
+    which then crashed on HPU tensors when constructing
+    ``torch.cuda.Stream()``. The guard must reject this combination with a
+    clear error before any device-specific construction.
+    """
+    _patch_device(monkeypatch, "hpu")
+    config = _make_config(use_layerwise=True)
+    metadata = _make_metadata()
+    with pytest.raises(ValueError) as exc:
+        CreateGPUConnector(config, metadata, EngineType.VLLM)
+    message = str(exc.value)
+    assert "use_layerwise" in message
+    assert "hpu" in message.lower()
+
+
+def test_create_gpu_connector_musa_dispatches_to_musa_connector(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``torch_device_type == 'musa'`` selects a MUSA connector class.
+
+    We do not need real MUSA hardware: the factory's ``torch.device`` call
+    is patched (PyTorch builds without ``torch_musa`` reject the 'musa'
+    string), and ``from_metadata`` is replaced on the MUSA connectors so
+    the assertion checks only the dispatch.
+    """
+    _patch_device(monkeypatch, "musa")
+    # First Party
+    from lmcache.v1.gpu_connector import musa_connectors as musa_mod
+
+    monkeypatch.setattr(
+        gpu_connector_module.torch, "device", lambda *_a, **_kw: "musa:0"
+    )
+
+    sentinel_v2 = object()
+    sentinel_layer = object()
+    monkeypatch.setattr(
+        musa_mod.VLLMPagedMemMUSAConnectorV2,
+        "from_metadata",
+        classmethod(lambda cls, *a, **kw: sentinel_v2),
+    )
+    monkeypatch.setattr(
+        musa_mod.VLLMPagedMemLayerwiseMUSAConnector,
+        "from_metadata",
+        classmethod(lambda cls, *a, **kw: sentinel_layer),
+    )
+
+    metadata = _make_metadata()
+    assert (
+        CreateGPUConnector(_make_config(use_layerwise=False), metadata, EngineType.VLLM)
+        is sentinel_v2
+    )
+    assert (
+        CreateGPUConnector(_make_config(use_layerwise=True), metadata, EngineType.VLLM)
+        is sentinel_layer
+    )
+
+
+def test_create_gpu_connector_rejects_sglang_on_musa(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Stage2 does not expose SGLang MUSA connector dispatch."""
+    _patch_device(monkeypatch, "musa")
+    with pytest.raises(ValueError, match="SGLang on MUSA"):
+        CreateGPUConnector(_make_config(), _make_metadata(), EngineType.SGLANG)
+
+
+# ---------------------------------------------------------------------------
+# Module import sanity
+# ---------------------------------------------------------------------------
+
+
+def test_lmcache_exports_torch_dev_and_torch_device_type() -> None:
+    """The contract used by every accelerator-aware module is the
+    ``torch_dev`` / ``torch_device_type`` pair exported from ``lmcache``.
+
+    Re-import to defeat any per-test monkeypatching above.
+    """
+    importlib.reload(lmc)
+    assert hasattr(lmc, "torch_dev")
+    assert isinstance(lmc.torch_device_type, str)
+    assert lmc.torch_device_type in {"cuda", "musa", "xpu", "hpu", "cpu"}
diff --git a/tests/v1/test_nixl_batched_contains.py b/tests/v1/test_nixl_batched_contains.py
new file mode 100644
index 0000000..f3596ec
--- /dev/null
+++ b/tests/v1/test_nixl_batched_contains.py
@@ -0,0 +1,391 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for ``batched_contains()`` and ``batched_nixl_desc_exists()``.
+
+All tests use lightweight mocks so they run without NIXL or CUDA hardware.
+The mock approach binds the *real* unbound method onto a ``Mock(spec=…)``
+object, so the actual implementation is exercised while external
+dependencies (NIXL agent, memory allocators) are replaced by mocks.
+"""
+
+# Standard
+from typing import List
+from unittest.mock import Mock
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("nixl")
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.storage_backend.nixl_storage_backend import (
+    NixlDynamicStorageAgent,
+    NixlDynamicStorageBackend,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_key(chunk_hash: int) -> CacheEngineKey:
+    """Create a single CacheEngineKey for testing."""
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=1,
+        worker_id=0,
+        chunk_hash=chunk_hash,
+        dtype=torch.bfloat16,
+    )
+
+
+def _make_keys(n: int) -> List[CacheEngineKey]:
+    """Create *n* distinct CacheEngineKeys (chunk_hash = 0 … n-1)."""
+    return [_make_key(i) for i in range(n)]
+
+
+def _mock_backend(**overrides) -> Mock:
+    """Return a ``Mock(spec=NixlDynamicStorageBackend)`` with sensible defaults.
+
+    Every test that exercises ``batched_contains`` or ``contains`` needs
+    a backend with at least ``_exists_in_put_tasks_or_cache``,
+    ``_format_object_key``, ``_cache_add``, and ``agent`` wired up.
+    """
+    backend = Mock(spec=NixlDynamicStorageBackend)
+    backend.agent = Mock()
+    backend._cache_add = Mock()
+    backend.presence_cache_only = False
+    # Default: _format_object_key returns a predictable string
+    backend._format_object_key = Mock(
+        side_effect=lambda key: f"formatted_{key.chunk_hash}"
+    )
+    backend.agent.batched_nixl_desc_exists = Mock(return_value=0)
+    # batched_contains() reads self.path to pass it to the agent; the value
+    # is unused here (the agent is mocked), but Mock(spec=...) raises on the
+    # unset instance attribute without it.
+    backend.path = None
+    for k, v in overrides.items():
+        setattr(backend, k, v)
+    return backend
+
+
+# ---------------------------------------------------------------------------
+# NixlDynamicStorageAgent.batched_nixl_desc_exists
+# ---------------------------------------------------------------------------
+
+
+class TestBatchedNixlDescExists:
+    """Unit tests for ``NixlDynamicStorageAgent.batched_nixl_desc_exists``."""
+
+    @staticmethod
+    def _make_agent() -> Mock:
+        agent = Mock(spec=NixlDynamicStorageAgent)
+        agent.nixl_agent = Mock()
+        agent.backend = "OBJ"
+        agent.mem_type = "OBJ"
+        return agent
+
+    @staticmethod
+    def _call(agent: Mock, reg_list):
+        return NixlDynamicStorageAgent.batched_nixl_desc_exists(agent, reg_list)
+
+    def test_empty_list(self) -> None:
+        agent = self._make_agent()
+        assert self._call(agent, []) == 0
+
+    def test_all_exist(self) -> None:
+        agent = self._make_agent()
+        reg_list = [(0, 0, 0, "k1"), (0, 0, 0, "k2"), (0, 0, 0, "k3")]
+        agent.nixl_agent.query_memory.return_value = ["d1", "d2", "d3"]
+        assert self._call(agent, reg_list) == 3
+        agent.nixl_agent.query_memory.assert_called_once_with(
+            reg_list, "OBJ", mem_type="OBJ"
+        )
+
+    def test_consecutive_then_miss(self) -> None:
+        agent = self._make_agent()
+        agent.nixl_agent.query_memory.return_value = ["d1", "d2", None, "d4"]
+        assert self._call(agent, [(0, 0, 0, f"k{i}") for i in range(4)]) == 2
+
+    def test_first_missing(self) -> None:
+        agent = self._make_agent()
+        agent.nixl_agent.query_memory.return_value = [None, "d2"]
+        assert self._call(agent, [(0, 0, 0, "k1"), (0, 0, 0, "k2")]) == 0
+
+    def test_exception_returns_zero(self) -> None:
+        agent = self._make_agent()
+        agent.nixl_agent.query_memory.side_effect = RuntimeError("boom")
+        assert self._call(agent, [(0, 0, 0, "k1")]) == 0
+
+    # -- FILE backend: resolves via os.path.exists, not query_memory --------
+
+    @staticmethod
+    def _make_file_agent() -> Mock:
+        agent = Mock(spec=NixlDynamicStorageAgent)
+        agent.nixl_agent = Mock()
+        agent.backend = "POSIX"
+        agent.mem_type = "FILE"
+        return agent
+
+    def test_file_all_exist(self) -> None:
+        agent = self._make_file_agent()
+        agent.nixl_desc_exists.return_value = True
+        reg_list = [(0, 0, 0, "k1"), (0, 0, 0, "k2"), (0, 0, 0, "k3")]
+        assert (
+            NixlDynamicStorageAgent.batched_nixl_desc_exists(agent, reg_list, "/dir")
+            == 3
+        )
+        # FILE must not use query_memory (it only answers for object stores)
+        agent.nixl_agent.query_memory.assert_not_called()
+        agent.nixl_desc_exists.assert_any_call("k1", "/dir")
+
+    def test_file_consecutive_then_miss(self) -> None:
+        agent = self._make_file_agent()
+        agent.nixl_desc_exists.side_effect = [True, True, False, True]
+        reg_list = [(0, 0, 0, f"k{i}") for i in range(4)]
+        assert (
+            NixlDynamicStorageAgent.batched_nixl_desc_exists(agent, reg_list, "/dir")
+            == 2
+        )
+
+    def test_file_first_missing(self) -> None:
+        agent = self._make_file_agent()
+        agent.nixl_desc_exists.side_effect = [False, True]
+        reg_list = [(0, 0, 0, "k1"), (0, 0, 0, "k2")]
+        assert (
+            NixlDynamicStorageAgent.batched_nixl_desc_exists(agent, reg_list, "/dir")
+            == 0
+        )
+
+    def test_file_requires_path(self) -> None:
+        agent = self._make_file_agent()
+        with pytest.raises(ValueError, match="path must be provided"):
+            NixlDynamicStorageAgent.batched_nixl_desc_exists(agent, [(0, 0, 0, "k1")])
+
+
+# ---------------------------------------------------------------------------
+# NixlDynamicStorageBackend.contains (refactored)
+# ---------------------------------------------------------------------------
+
+
+class TestContains:
+    """Verify the refactored ``contains()`` delegates correctly."""
+
+    @staticmethod
+    def _call(backend: Mock, key: CacheEngineKey, pin: bool = False) -> bool:
+        return NixlDynamicStorageBackend.contains(backend, key, pin)
+
+    def test_cache_hit(self) -> None:
+        """When the helper finds the key in the presence cache, return True."""
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.return_value = (True, True)
+
+        assert self._call(backend, _make_key(1)) is True
+        backend.key_exists.assert_not_called()
+
+    def test_put_task_hit(self) -> None:
+        """When the key is in put tasks, return False immediately."""
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.return_value = (True, False)
+
+        assert self._call(backend, _make_key(1)) is False
+        backend.key_exists.assert_not_called()
+
+    def test_fallback_to_key_exists_hit(self) -> None:
+        """When local lookup misses, fall back to key_exists and cache the result."""
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.return_value = (False, False)
+        backend.key_exists.return_value = True
+
+        key = _make_key(42)
+        assert self._call(backend, key) is True
+        backend.key_exists.assert_called_once_with(key)
+        backend._cache_add.assert_called_once_with(key.chunk_hash)
+
+    def test_fallback_to_key_exists_miss(self) -> None:
+        """When key_exists also returns False, return False and don't cache."""
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.return_value = (False, False)
+        backend.key_exists.return_value = False
+
+        assert self._call(backend, _make_key(42)) is False
+        backend._cache_add.assert_not_called()
+
+    def test_presence_cache_only_skips_remote(self) -> None:
+        """With presence_cache_only set, a presence-cache miss returns False
+        without issuing the queryMem call (key_exists not called)."""
+        backend = _mock_backend(presence_cache_only=True)
+        backend._exists_in_put_tasks_or_cache.return_value = (False, False)
+
+        assert self._call(backend, _make_key(7)) is False
+        backend.key_exists.assert_not_called()
+        backend._cache_add.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# NixlDynamicStorageBackend.batched_contains
+# ---------------------------------------------------------------------------
+
+
+class TestBatchedContains:
+    """Verify ``batched_contains()`` prefix-match semantics."""
+
+    @staticmethod
+    def _call(
+        backend: Mock,
+        keys: List[CacheEngineKey],
+        pin: bool = False,
+    ) -> int:
+        return NixlDynamicStorageBackend.batched_contains(backend, keys, pin)
+
+    # -- trivial / edge cases -----------------------------------------------
+
+    def test_empty_keys(self) -> None:
+        backend = _mock_backend()
+        assert self._call(backend, []) == 0
+
+    def test_all_local_cache_hits(self) -> None:
+        """Every key resolved from the local presence cache."""
+        keys = _make_keys(3)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (True, True),
+            (True, True),
+            (True, True),
+        ]
+        assert self._call(backend, keys) == 3
+        backend.agent.batched_nixl_desc_exists.assert_not_called()
+
+    # -- early-stop on put-task ---------------------------------------------
+
+    def test_first_key_in_put_tasks(self) -> None:
+        keys = _make_keys(3)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (True, False),
+        ]
+        assert self._call(backend, keys) == 0
+
+    def test_second_key_in_put_tasks(self) -> None:
+        keys = _make_keys(3)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (True, True),
+            (True, False),
+        ]
+        assert self._call(backend, keys) == 1
+
+    # -- remote fallback ----------------------------------------------------
+
+    def test_all_keys_remote(self) -> None:
+        """No local hits; all keys go to batched_nixl_desc_exists."""
+        keys = _make_keys(3)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (False, False),
+        ]
+        backend.agent.batched_nixl_desc_exists.return_value = 2
+
+        assert self._call(backend, keys) == 2
+        # Verify all 3 keys sent to agent
+        call_args = backend.agent.batched_nixl_desc_exists.call_args[0][0]
+        assert len(call_args) == 3
+
+    def test_mixed_local_and_remote(self) -> None:
+        """First key from cache, remaining from remote."""
+        keys = _make_keys(3)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (True, True),
+            (False, False),
+        ]
+        backend.agent.batched_nixl_desc_exists.return_value = 1
+
+        assert self._call(backend, keys) == 2  # 1 local + 1 remote
+        # Only the 2 remaining keys should go to agent
+        call_args = backend.agent.batched_nixl_desc_exists.call_args[0][0]
+        assert len(call_args) == 2
+
+    def test_presence_cache_only_skips_remote(self) -> None:
+        """With presence_cache_only set, batched_contains returns the count of
+        leading local hits and never issues the remote batched query."""
+        keys = _make_keys(3)
+        backend = _mock_backend(presence_cache_only=True)
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (True, True),
+            (False, False),
+        ]
+
+        assert self._call(backend, keys) == 1
+        backend.agent.batched_nixl_desc_exists.assert_not_called()
+        backend._cache_add.assert_not_called()
+
+    def test_remote_hits_are_cached(self) -> None:
+        """Remote hits should be added to the presence cache."""
+        keys = _make_keys(4)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (False, False),
+        ]
+        backend.agent.batched_nixl_desc_exists.return_value = 3
+
+        self._call(backend, keys)
+        # _cache_add should be called for each remote hit
+        assert backend._cache_add.call_count == 3
+        cached_hashes = [c.args[0] for c in backend._cache_add.call_args_list]
+        assert cached_hashes == [0, 1, 2]
+
+    # -- key formatting (catches the original chunk_hash vs formatted-key bug)
+
+    def test_reg_list_uses_formatted_object_keys(self) -> None:
+        """The reg_list sent to the agent must contain formatted object-key
+        strings (from ``_format_object_key``), not raw chunk-hash integers.
+
+        This test would have caught the original bug where ``key.chunk_hash``
+        was passed instead of ``self._format_object_key(key)``.
+        """
+        keys = _make_keys(3)
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (False, False),
+        ]
+        backend.agent.batched_nixl_desc_exists.return_value = 0
+
+        self._call(backend, keys)
+
+        call_args = backend.agent.batched_nixl_desc_exists.call_args[0][0]
+        # Each meta_info element must be a string, not an int
+        meta_infos = [t[3] for t in call_args]
+        assert meta_infos == ["formatted_0", "formatted_1", "formatted_2"]
+        assert all(isinstance(m, str) for m in meta_infos)
+
+    def test_format_object_key_called_for_each_remaining_key(self) -> None:
+        """_format_object_key must be called once per key that goes remote."""
+        keys = _make_keys(4)
+        backend = _mock_backend()
+        # First 2 keys resolve locally, remaining 2 go remote
+        backend._exists_in_put_tasks_or_cache.side_effect = [
+            (True, True),
+            (True, True),
+            (False, False),
+        ]
+        backend.agent.batched_nixl_desc_exists.return_value = 0
+
+        self._call(backend, keys)
+
+        formatted_hashes = [
+            c.args[0].chunk_hash for c in backend._format_object_key.call_args_list
+        ]
+        assert formatted_hashes == [2, 3]
+
+    def test_single_key_present(self) -> None:
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.return_value = (True, True)
+        assert self._call(backend, _make_keys(1)) == 1
+
+    def test_single_key_missing_remote(self) -> None:
+        backend = _mock_backend()
+        backend._exists_in_put_tasks_or_cache.return_value = (False, False)
+        backend.agent.batched_nixl_desc_exists.return_value = 0
+        assert self._call(backend, _make_keys(1)) == 0
diff --git a/tests/v1/test_nixl_doca_memos.py b/tests/v1/test_nixl_doca_memos.py
new file mode 100644
index 0000000..8fa0464
--- /dev/null
+++ b/tests/v1/test_nixl_doca_memos.py
@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for the DOCA_MEMOS NIXL storage backend.
+
+Covers backend/device validation, the 128-bit-hex object-key format
+(``_format_object_key_b128``) and the URL-safe regression guard, static
+object-pool slot names and the ``createPool`` routing, and the dynamic
+backend's formatter dispatch.
+
+All tests run without NIXL hardware: the formatters do not touch instance
+state, so the real unbound methods are invoked directly with a
+``Mock(spec=...)`` standing in for ``self``.
+"""
+
+# Standard
+from typing import Any
+from unittest.mock import MagicMock, Mock, patch
+import hashlib
+import re
+import uuid
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("nixl")
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.storage_backend.nixl_storage_backend import (
+    B128_MAX_POOL_SIZE,
+    NixlDynamicStorageBackend,
+    NixlObjectPool,
+    NixlStaticStorageBackend,
+    NixlStorageConfig,
+)
+import lmcache.v1.storage_backend.nixl_storage_backend as nsb
+
+_HEX_128 = re.compile(r"^[0-9a-f]{32}$")
+
+
+def _make_key(
+    model_name: str = "org/test_model", chunk_hash: int = 0
+) -> CacheEngineKey:
+    """A CacheEngineKey whose to_string() contains both '/' and '@'."""
+    return CacheEngineKey(
+        model_name=model_name,
+        world_size=1,
+        worker_id=0,
+        chunk_hash=chunk_hash,
+        dtype=torch.bfloat16,
+    )
+
+
+class TestFormatObjectKeyB128:
+    """``_format_object_key_b128`` -> 32-char hex (sha256 truncated to 128 bits)."""
+
+    @staticmethod
+    def _fmt(key: CacheEngineKey) -> str:
+        backend = Mock(spec=NixlDynamicStorageBackend)
+        return NixlDynamicStorageBackend._format_object_key_b128(backend, key)
+
+    def test_returns_32_char_lowercase_hex(self) -> None:
+        out = self._fmt(_make_key())
+        assert _HEX_128.match(out), f"not 128-bit hex: {out!r}"
+
+    def test_matches_documented_algorithm(self) -> None:
+        key = _make_key()
+        expected = hashlib.sha256(key.to_string().encode("utf-8")).hexdigest()[:32]
+        assert self._fmt(key) == expected
+
+    def test_deterministic_for_same_key(self) -> None:
+        key = _make_key(chunk_hash=42)
+        assert self._fmt(key) == self._fmt(_make_key(chunk_hash=42))
+
+    def test_distinct_keys_differ(self) -> None:
+        assert self._fmt(_make_key(chunk_hash=1)) != self._fmt(_make_key(chunk_hash=2))
+
+
+class TestFormatObjectKeyUrlSafe:
+    """Regression guard for the legacy URL-safe formatter (non-DOCA backends)."""
+
+    @staticmethod
+    def _fmt(key: CacheEngineKey) -> str:
+        backend = Mock(spec=NixlDynamicStorageBackend)
+        return NixlDynamicStorageBackend._format_object_key_url_safe(backend, key)
+
+    def test_no_raw_slash_or_at(self) -> None:
+        out = self._fmt(_make_key())
+        assert "/" not in out and "@" not in out
+
+    def test_matches_legacy_transform(self) -> None:
+        # Standard
+        from urllib.parse import quote
+
+        key = _make_key()
+        flat = key.to_string().replace("/", "_").replace("@", "_")
+        assert self._fmt(key) == quote(flat, safe="")
+
+
+class TestNixlObjectPoolKeys:
+    """Static object-pool slot names per backend."""
+
+    def test_b128_keys_are_128bit_hex(self) -> None:
+        pool = NixlObjectPool(64, b128=True)
+        assert len(pool.keys) == 64
+        assert all(_HEX_128.match(k) for k in pool.keys)
+
+    def test_b128_keys_are_unique(self) -> None:
+        pool = NixlObjectPool(256, b128=True)
+        assert len(set(pool.keys)) == len(pool.keys)
+
+    def test_b128_first_8_hex_encode_slot_index(self) -> None:
+        size = 16
+        pool = NixlObjectPool(size, b128=True)
+        # Keys are generated for i in reversed(range(size)); the leading
+        # 8 hex chars must recover every slot index exactly once.
+        indices = sorted(int(k[:8], 16) for k in pool.keys)
+        assert indices == list(range(size))
+
+    def test_default_keys_use_obj_prefix(self) -> None:
+        pool = NixlObjectPool(8)
+        assert all(k.startswith("obj_") for k in pool.keys)
+
+    def test_b128_rejects_pool_size_above_max(self) -> None:
+        with pytest.raises(ValueError, match="at most"):
+            NixlObjectPool(B128_MAX_POOL_SIZE + 1, b128=True)
+
+    def test_b128_max_pool_size_is_2_32(self) -> None:
+        # The guard accepts up to 2**32 slots because the largest valid slot
+        # index (B128_MAX_POOL_SIZE - 1 == 0xffffffff) still formats to exactly
+        # 8 hex chars, keeping the full slot name at 32 hex chars (128 bits).
+        # Constructing a 2**32-slot pool is infeasible in a test, so this
+        # asserts the boundary invariant directly rather than the constructor.
+        assert B128_MAX_POOL_SIZE == 2**32
+        max_index = B128_MAX_POOL_SIZE - 1
+        key = f"{max_index:08x}{uuid.uuid4().hex[:24]}"
+        assert len(key) == 32 and _HEX_128.match(key)
+
+
+class TestValidateNixlBackend:
+    """NixlStorageConfig.validate_nixl_backend — the config-acceptance path."""
+
+    def test_doca_memos_cpu_is_valid(self) -> None:
+        assert NixlStorageConfig.validate_nixl_backend("DOCA_MEMOS", "cpu") is True
+
+    def test_doca_memos_cuda_is_rejected(self) -> None:
+        assert NixlStorageConfig.validate_nixl_backend("DOCA_MEMOS", "cuda") is False
+
+    def test_doca_memos_cuda_with_index_is_rejected(self) -> None:
+        # device strings may carry an index suffix (e.g. "cuda:0")
+        assert NixlStorageConfig.validate_nixl_backend("DOCA_MEMOS", "cuda:0") is False
+
+
+class TestCreatePool:
+    """NixlStaticStorageBackend.createPool — the static configured path."""
+
+    def test_doca_memos_creates_b128_object_pool(self) -> None:
+        pool = NixlStaticStorageBackend.createPool(
+            "DOCA_MEMOS",
+            size=8,
+            path="/tmp/unused",
+            use_direct_io=False,
+            path_sharding="by_gpu",
+            dst_device="cpu",
+        )
+        assert isinstance(pool, NixlObjectPool)
+        # b128 slot names are 32-char lowercase hex (no "obj_" prefix).
+        assert all(_HEX_128.match(k) for k in pool.keys)
+        assert not any(k.startswith("obj_") for k in pool.keys)
+
+    def test_obj_creates_non_b128_object_pool(self) -> None:
+        pool = NixlStaticStorageBackend.createPool(
+            "OBJ",
+            size=8,
+            path="/tmp/unused",
+            use_direct_io=False,
+            path_sharding="by_gpu",
+            dst_device="cpu",
+        )
+        assert isinstance(pool, NixlObjectPool)
+        assert all(k.startswith("obj_") for k in pool.keys)
+
+
+class TestDynamicFormatterDispatch:
+    """A dynamic backend must route _format_object_key to b128 for DOCA_MEMOS."""
+
+    @staticmethod
+    def _make_dynamic_backend(backend_name: str) -> nsb.NixlDynamicStorageBackend:
+        cfg = MagicMock()
+        cfg.backend = backend_name
+        cfg.use_direct_io = False
+        cfg.enable_async_put = False
+        cfg.enable_presence_cache = False
+        cfg.path = "/tmp/nixl-unused"
+
+        def fake_super_init(self: Any, *args: Any, **kwargs: Any) -> None:
+            # super().__init__ normally allocates the NIXL buffer/allocator;
+            # the agent constructor reads self.memory_allocator.
+            self.memory_allocator = MagicMock()
+
+        with (
+            patch.object(nsb.NixlStorageBackend, "__init__", fake_super_init),
+            # Skip init_chunk_meta so the mock metadata is never dereferenced.
+            patch.object(nsb.NixlDynamicStorageBackend, "init_chunk_meta"),
+            patch.object(nsb, "NixlDynamicStorageAgent", return_value=MagicMock()),
+        ):
+            return nsb.NixlDynamicStorageBackend(
+                cfg, MagicMock(), MagicMock(), MagicMock()
+            )
+
+    def test_doca_memos_uses_b128(self) -> None:
+        backend = self._make_dynamic_backend("DOCA_MEMOS")
+        key = _make_key()
+        assert backend._format_object_key(key) == backend._format_object_key_b128(key)
+
+    def test_obj_uses_url_safe(self) -> None:
+        backend = self._make_dynamic_backend("OBJ")
+        key = _make_key()
+        assert backend._format_object_key(key) == backend._format_object_key_url_safe(
+            key
+        )
diff --git a/tests/v1/test_nixl_multipath.py b/tests/v1/test_nixl_multipath.py
new file mode 100644
index 0000000..3781b5e
--- /dev/null
+++ b/tests/v1/test_nixl_multipath.py
@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+import pytest
+
+pytest.importorskip("nixl", reason="nixl package is required for nixl tests")
+
+# First Party
+from lmcache.v1.storage_backend.path_sharder import PathSharder
+
+
+class TestNixlMultipath:
+    """Test cases for NIXL multipath functionality using PathSharder."""
+
+    def test_path_sharder_single_path(self):
+        """Test PathSharder with a single path string."""
+        path = "/tmp/nixl/cache"
+        path_sharding = "by_gpu"
+        dst_device = "cuda:0"
+
+        sharder = PathSharder(path, path_sharding, dst_device)
+
+        # Should return the same path since there's only one
+        assert sharder.selected == path
+        assert sharder.all_paths == [path]
+
+    def test_path_sharder_multiple_paths(self):
+        """Test PathSharder with a CSV string of paths."""
+        paths = "/tmp/nixl/cache0,/tmp/nixl/cache1,/tmp/nixl/cache2"
+        path_sharding = "by_gpu"
+
+        # Test with cuda:0 (device 0)
+        sharder = PathSharder(paths, path_sharding, "cuda:0")
+        assert sharder.selected == "/tmp/nixl/cache0"
+
+        # Test with cuda:1 (device 1)
+        sharder = PathSharder(paths, path_sharding, "cuda:1")
+        assert sharder.selected == "/tmp/nixl/cache1"
+
+        # Test with cuda:2 (device 2)
+        sharder = PathSharder(paths, path_sharding, "cuda:2")
+        assert sharder.selected == "/tmp/nixl/cache2"
+
+        # Test with cuda:3 (should wrap around to cache0)
+        sharder = PathSharder(paths, path_sharding, "cuda:3")
+        assert sharder.selected == "/tmp/nixl/cache0"
+
+    def test_path_sharder_empty_path(self):
+        """Test PathSharder with empty path."""
+        with pytest.raises(ValueError, match="At least one path must be provided"):
+            PathSharder("", "by_gpu", "cuda:0")
+
+    def test_path_sharder_unsupported_sharding(self):
+        """Test PathSharder with unsupported path sharding."""
+        path = "/tmp/nixl/cache"
+        with pytest.raises(ValueError, match="Unsupported path sharding"):
+            PathSharder(path, "unsupported_sharding", "cuda:0")
+
+    def test_path_sharder_cpu_device(self):
+        """Test PathSharder with CPU device."""
+        path = "/tmp/nixl/cache"
+        path_sharding = "by_gpu"
+        dst_device = "cpu"
+
+        sharder = PathSharder(path, path_sharding, dst_device)
+        assert sharder.selected == path
diff --git a/tests/v1/test_nixl_storage.py b/tests/v1/test_nixl_storage.py
new file mode 100644
index 0000000..8709c8b
--- /dev/null
+++ b/tests/v1/test_nixl_storage.py
@@ -0,0 +1,483 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from pathlib import Path
+import asyncio
+import contextlib
+import functools
+import os
+import shutil
+import tempfile
+import threading
+import uuid
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("nixl", reason="nixl package is required for nixl tests")
+
+# Third Party
+from nixl._api import nixl_agent as NixlAgent
+from nixl._api import nixl_agent_config as NixlAgentConfig
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend import CreateStorageBackends
+from lmcache.v1.storage_backend.nixl_storage_backend import (
+    NixlStorageBackend,
+    NixlStorageConfig,
+)
+from lmcache.v1.transfer_channel.transfer_utils import get_correct_device
+
+# cuFile-based backends (GDS, GDS_MT) need a GDS-capable filesystem
+_TEST_TMPDIR = os.environ.get("LMCACHE_TEST_TMPDIR") or None
+
+
+@functools.lru_cache(maxsize=None)
+def _can_register_file_with_nixl_backend(backend: str) -> bool:
+    """Probe ``cuFileHandleRegister`` via NIXL on the test scratch dir."""
+
+    probe_dir = tempfile.mkdtemp(prefix="nixl_gds_probe_", dir=_TEST_TMPDIR)
+    probe_path = os.path.join(probe_dir, "probe.bin")
+    fd = -1
+    try:
+        agent = NixlAgent(
+            f"NixlGdsProbe_{uuid.uuid4().hex}",
+            NixlAgentConfig(backends=[]),
+        )
+        agent.create_backend(backend, {})
+        fd = os.open(probe_path, os.O_CREAT | os.O_RDWR, 0o600)
+        os.write(fd, b"\x00" * 4096)
+        agent.register_memory([(0, 4096, fd, "")], mem_type="FILE")
+        return True
+    except Exception:
+        return False
+    finally:
+        if fd >= 0:
+            with contextlib.suppress(OSError):
+                os.close(fd)
+        shutil.rmtree(probe_dir, ignore_errors=True)
+
+
+_GDS_SKIP_REASON = (
+    "NIXL {backend} cannot register file handles in this environment; "
+    "set LMCACHE_TEST_TMPDIR to a GDS-capable mount (ext4/xfs) to enable."
+)
+
+
+@pytest.fixture
+def nixl_tmp_path():
+    """Per-test scratch dir, honoring ``LMCACHE_TEST_TMPDIR``."""
+    path = tempfile.mkdtemp(prefix="nixl_test_", dir=_TEST_TMPDIR)
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def create_key(chunk_hash: str):
+    return CacheEngineKey(
+        model_name="meta-llama/Llama-3.1-70B-Instruct",
+        world_size=8,
+        worker_id=0,
+        chunk_hash=int(chunk_hash, base=16),
+        dtype=torch.bfloat16,
+    )
+
+
+def run(config: LMCacheEngineConfig, shape, dtype):
+    BACKEND_NAME = "NixlStorageBackend"
+    keys = []
+    objs = []
+    keys.append(
+        create_key("e3229141e680fb413d2c5d3ebb416c4ad300d381e309fc9e417757b91406c157")
+    )
+    keys.append(
+        create_key("e3229141e680fb413d2c5d3ebb416c4ad300d381e309fc9e417757b91406d268")
+    )
+    keys.append(
+        create_key("e3229141e680fb413d2c5d3ebb416c4ad300d381e309fc9e417757b91406e379")
+    )
+    bad_key = create_key("deadbeefdeadbeef")
+
+    thread_loop = None
+    thread = None
+    try:
+        thread_loop = asyncio.new_event_loop()
+        thread = threading.Thread(target=thread_loop.run_forever)
+        thread.start()
+
+        metadata = LMCacheMetadata(
+            model_name="Llama-3.1-70B-Instruct",
+            world_size=1,
+            local_world_size=1,
+            worker_id=0,
+            local_worker_id=0,
+            kv_dtype=dtype,
+            kv_shape=shape,
+        )
+
+        backends = CreateStorageBackends(
+            config,
+            metadata,
+            thread_loop,
+            dst_device=get_correct_device(
+                config.nixl_buffer_device, metadata.worker_id
+            ),
+        )
+        assert len(backends) == 2  # NixlStorageBackend + LocalCPUBackend
+        assert BACKEND_NAME in backends
+
+        nixl_backend = backends[BACKEND_NAME]
+        assert isinstance(nixl_backend, NixlStorageBackend)
+        assert isinstance(nixl_backend.memory_allocator, PagedTensorMemoryAllocator)
+        assert nixl_backend is not None
+        assert nixl_backend.memory_allocator is not None
+
+        # Allocate via the chunk shape that LMCacheMetadata derives from
+        # kv_shape (LocalCPUBackend / NIXL share the same paged pool sized
+        # by metadata.get_shapes()); passing the raw 5D kv_shape would
+        # produce a same-byte-count but differently-indexed tensor.
+        alloc_shape = metadata.get_shapes()[0]
+        for key in keys:
+            assert not nixl_backend.contains(key, False)
+            assert not nixl_backend.exists_in_put_tasks(key)
+
+            obj = nixl_backend.memory_allocator.allocate(alloc_shape, dtype)
+            assert obj is not None
+            assert obj.tensor is not None
+            objs.append(obj)
+
+        # small tensor changes for data validation (chunk shape is 4D:
+        # [kv_size, num_layers, num_tokens, num_heads * head_size] =
+        # [2, 4, 256, 1024] for kv_shape (4, 2, 256, 8, 128))
+        objs[0].tensor[0, 0, 100, 200] = 1e-3
+        objs[0].tensor[1, 0, 200, 100] = 1e-4
+
+        objs[1].tensor[0, 1, 150, 400] = 1e-2
+        objs[1].tensor[1, 1, 100, 300] = 1e-5
+
+        objs[2].tensor[0, 2, 50, 200] = 3e-2
+        objs[2].tensor[1, 3, 200, 100] = 4e-5
+
+        # Insert first 2 keys
+        first_keys = keys[0:2]
+        first_objs = objs[0:2]
+        nixl_backend.batched_submit_put_task(first_keys, first_objs)
+
+        for key, obj in zip(first_keys, first_objs, strict=False):
+            returned_memory_obj = nixl_backend.get_blocking(key)
+            assert returned_memory_obj is not None
+            assert returned_memory_obj.get_size() == obj.get_size()
+            assert returned_memory_obj.get_shape() == obj.get_shape()
+            assert returned_memory_obj.get_dtype() == obj.get_dtype()
+            assert returned_memory_obj.metadata.address != obj.metadata.address
+
+            returned_tensor = returned_memory_obj.tensor
+            obj_tensor = obj.tensor
+            assert returned_tensor is not None
+            assert obj_tensor is not None
+            assert torch.equal(returned_tensor, obj_tensor)
+
+        obj_list = asyncio.run(
+            nixl_backend.batched_get_non_blocking(lookup_id="test", keys=first_keys)
+        )
+
+        for i, obj in enumerate(first_objs):
+            returned_memory_obj = obj_list[i]
+            assert returned_memory_obj is not None
+            assert returned_memory_obj.get_size() == obj.get_size()
+            assert returned_memory_obj.get_shape() == obj.get_shape()
+            assert returned_memory_obj.get_dtype() == obj.get_dtype()
+            assert returned_memory_obj.metadata.address != obj.metadata.address
+
+            returned_tensor = returned_memory_obj.tensor
+            obj_tensor = obj.tensor
+            assert returned_tensor is not None
+            assert obj_tensor is not None
+            assert torch.equal(returned_tensor, obj_tensor)
+
+        def test_eviction(new_idx, old_idx):
+            nixl_backend.batched_submit_put_task([keys[new_idx]], [objs[new_idx]])
+
+            obj = nixl_backend.get_blocking(keys[new_idx])
+            assert obj is not None
+            assert obj.tensor is not None
+            assert torch.equal(obj.tensor, objs[new_idx].tensor)
+
+            obj = nixl_backend.get_blocking(keys[old_idx])
+            assert obj is None
+
+        ######## Test bad key lookup #########
+        obj = nixl_backend.get_blocking(bad_key)
+        assert obj is None
+
+        ######## Test eviction #########
+        obj = nixl_backend.get_blocking(keys[0])
+        assert obj is not None
+
+        # At this point, key 0 & key 1 are cached. Key 1 is LRU key.
+        # Submitting key 2 should evict key 1.
+
+        test_eviction(new_idx=2, old_idx=1)
+
+        ######## Test pin #########
+        val = nixl_backend.pin(keys[2])
+        assert val is True
+
+        obj = nixl_backend.get_blocking(keys[0])
+        assert obj is not None
+
+        # At this point, key 0 & key 2 are cached.
+        # Key 2 is LRU key, but is pinned.
+        # Submitting key 1 should evict key 0.
+
+        test_eviction(new_idx=1, old_idx=0)
+
+        ######## Test unpin #########
+        val = nixl_backend.unpin(keys[2])
+        assert val is True
+
+        obj = nixl_backend.get_blocking(keys[1])
+        assert obj is not None
+
+        # At this point, key 1 & key 2 are cached.
+        # Key 2 is LRU key, and is now unpinned.
+        # Submitting key 0 should evict key 2.
+
+        test_eviction(new_idx=0, old_idx=2)
+
+        for backend in backends.values():
+            backend.close()
+
+    except Exception:
+        raise
+    finally:
+        if thread_loop and thread_loop.is_running():
+            thread_loop.call_soon_threadsafe(thread_loop.stop)
+        if thread and thread.is_alive():
+            thread.join()
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Requires CUDA")
+@pytest.mark.skipif(
+    not _can_register_file_with_nixl_backend("GDS_MT"),
+    reason=_GDS_SKIP_REASON.format(backend="GDS_MT"),
+)
+def test_nixl_gds_mt_cuda_backend(nixl_tmp_path):
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+
+    dtype = torch.bfloat16
+    shape = torch.Size([4, 2, 256, 8, 128])
+
+    config.nixl_buffer_device = "cuda"
+    # data/nixl.yaml is CPU-mode (no nixl_buffer_size); CUDA mode sizes the
+    # NIXL buffer via nixl_buffer_size, so restore it when flipping the device.
+    config.nixl_buffer_size = 1024**3
+    config.extra_config["nixl_backend"] = "GDS_MT"
+    config.extra_config["enable_cuda"] = True
+    config.extra_config["nixl_path"] = nixl_tmp_path
+
+    run(config, shape, dtype)
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(
+    not _can_register_file_with_nixl_backend("GDS_MT"),
+    reason=_GDS_SKIP_REASON.format(backend="GDS_MT"),
+)
+def test_nixl_gds_mt_cpu_backend(nixl_tmp_path):
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+
+    dtype = torch.bfloat16
+    shape = torch.Size([4, 2, 256, 8, 128])
+
+    config.nixl_buffer_device = "cpu"
+    config.extra_config["nixl_backend"] = "GDS_MT"
+    config.extra_config["enable_cuda"] = False
+    config.extra_config["nixl_path"] = nixl_tmp_path
+
+    run(config, shape, dtype)
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="Requires CUDA")
+@pytest.mark.skipif(
+    not _can_register_file_with_nixl_backend("GDS"),
+    reason=_GDS_SKIP_REASON.format(backend="GDS"),
+)
+def test_nixl_gds_cuda_backend(nixl_tmp_path):
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+
+    dtype = torch.bfloat16
+    shape = torch.Size([4, 2, 256, 8, 128])
+
+    config.nixl_buffer_device = "cuda"
+    # data/nixl.yaml is CPU-mode (no nixl_buffer_size); CUDA mode sizes the
+    # NIXL buffer via nixl_buffer_size, so restore it when flipping the device.
+    config.nixl_buffer_size = 1024**3
+    config.extra_config["nixl_backend"] = "GDS"
+    config.extra_config["enable_cuda"] = True
+    config.extra_config["nixl_path"] = nixl_tmp_path
+
+    run(config, shape, dtype)
+
+
+@pytest.mark.no_shared_allocator
+@pytest.mark.skipif(
+    not _can_register_file_with_nixl_backend("GDS"),
+    reason=_GDS_SKIP_REASON.format(backend="GDS"),
+)
+def test_nixl_gds_cpu_backend(nixl_tmp_path):
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+
+    dtype = torch.bfloat16
+    shape = torch.Size([4, 2, 256, 8, 128])
+
+    config.nixl_buffer_device = "cpu"
+    config.extra_config["nixl_backend"] = "GDS"
+    config.extra_config["enable_cuda"] = False
+    config.extra_config["nixl_path"] = nixl_tmp_path
+
+    run(config, shape, dtype)
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_endpoint_list_empty_raises():
+    """nixl_endpoint_list=[] should raise ValueError before any nixl ops."""
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+    config.extra_config["nixl_endpoint_list"] = []
+
+    metadata = LMCacheMetadata(
+        model_name="Llama-3.1-70B-Instruct",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+    with pytest.raises(ValueError, match="nixl_endpoint_list is set but empty"):
+        NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_endpoint_list_malformed_url_raises():
+    """A non-http(s) entry in nixl_endpoint_list should raise ValueError."""
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+    config.extra_config["nixl_endpoint_list"] = ["htps://typo.example.com"]
+    config.extra_config["nixl_backend"] = "OBJ"
+
+    metadata = LMCacheMetadata(
+        model_name="Llama-3.1-70B-Instruct",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+    with pytest.raises(ValueError, match="is not a valid URL"):
+        NixlStorageConfig.from_cache_engine_config(config, metadata)
+
+
+def _presence_cache_metadata() -> LMCacheMetadata:
+    return LMCacheMetadata(
+        model_name="Llama-3.1-70B-Instruct",
+        world_size=1,
+        local_world_size=1,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(4, 2, 256, 8, 128),
+    )
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_presence_cache_only_defaults_false():
+    """presence_cache_only defaults to False when the config key is absent."""
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+
+    nixl_config = NixlStorageConfig.from_cache_engine_config(
+        config, _presence_cache_metadata()
+    )
+
+    assert nixl_config.presence_cache_only is False
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_presence_cache_only_parsed():
+    """nixl_presence_cache_only=True is parsed onto NixlStorageConfig."""
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+    config.extra_config["nixl_presence_cache"] = True
+    config.extra_config["nixl_presence_cache_only"] = True
+
+    nixl_config = NixlStorageConfig.from_cache_engine_config(
+        config, _presence_cache_metadata()
+    )
+
+    assert nixl_config.presence_cache_only is True
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_presence_cache_only_requires_presence_cache():
+    """nixl_presence_cache_only=True without nixl_presence_cache raises ValueError."""
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+    config.extra_config["nixl_presence_cache_only"] = True
+
+    with pytest.raises(ValueError, match="nixl_presence_cache must be true"):
+        config.validate()
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_posix_backend(nixl_tmp_path):
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl.yaml")
+
+    dtype = torch.bfloat16
+    shape = torch.Size([4, 2, 256, 8, 128])
+
+    config.nixl_buffer_device = "cpu"
+    config.extra_config["nixl_backend"] = "POSIX"
+    config.extra_config["enable_cuda"] = False
+    config.extra_config["nixl_path"] = nixl_tmp_path
+
+    run(config, shape, dtype)
+
+
+@pytest.mark.no_shared_allocator
+def test_nixl_posix_backend_multipath():
+    """Test NIXL backend with multipath support and path sharding."""
+    BASE_DIR = Path(__file__).parent
+    config = LMCacheEngineConfig.from_file(BASE_DIR / "data/nixl_multipath.yaml")
+
+    dtype = torch.bfloat16
+    shape = torch.Size([4, 2, 256, 8, 128])
+
+    config.nixl_buffer_device = "cpu"
+    config.extra_config["nixl_backend"] = "POSIX"
+    config.extra_config["enable_cuda"] = False
+
+    # Test that multipath configuration is properly handled
+    assert isinstance(config.extra_config["nixl_path"], list)
+    assert len(config.extra_config["nixl_path"]) == 3
+    assert config.extra_config["nixl_path_sharding"] == "by_gpu"
+
+    run(config, shape, dtype)
diff --git a/tests/v1/test_pos_kernels.py b/tests/v1/test_pos_kernels.py
new file mode 100644
index 0000000..c726f0a
--- /dev/null
+++ b/tests/v1/test_pos_kernels.py
@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from unittest.mock import MagicMock
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.compute.positional_encoding import get_fused_rope
+
+# Attempt to import vLLM configuration utilities
+try:
+    # Third Party
+    from vllm.config import CompilationConfig, VllmConfig, set_current_vllm_config
+except ImportError:
+    # Fallback for older versions or different paths
+    set_current_vllm_config = None
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO: Add non CUDA implementations for CUDA enhanced functions",
+)
+def test_rope():
+    head_dim = 128
+    max_position_embeddings = 8192
+    rope_scaling = None
+    rope_theta = 500000.0
+    is_neox_style = True
+    dtype = torch.bfloat16
+
+    # ---  manually set vLLM config context ---
+    if set_current_vllm_config is not None:
+        c_config = CompilationConfig()
+        c_config.custom_ops = ["all"]
+
+        mock_config = MagicMock(spec=VllmConfig)
+        mock_config.compilation_config = c_config
+
+        with set_current_vllm_config(mock_config):
+            fused_rotary_emb = get_fused_rope(
+                head_dim,
+                rotary_dim=head_dim,
+                max_position=max_position_embeddings,
+                base=rope_theta,
+                rope_scaling=rope_scaling,
+                is_neox_style=is_neox_style,
+                dtype=dtype,
+            )
+    else:
+        # For older vLLM versions, no context is needed
+        fused_rotary_emb = get_fused_rope(
+            head_dim,
+            rotary_dim=head_dim,
+            max_position=max_position_embeddings,
+            base=rope_theta,
+            rope_scaling=rope_scaling,
+            is_neox_style=is_neox_style,
+            dtype=dtype,
+        )
+    # ------------------------------------------
+
+    assert fused_rotary_emb is not None, "Failed to get fused rotary embedding"
diff --git a/tests/v1/test_python_ops_fallback.py b/tests/v1/test_python_ops_fallback.py
new file mode 100644
index 0000000..ddf254f
--- /dev/null
+++ b/tests/v1/test_python_ops_fallback.py
@@ -0,0 +1,2867 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Any, Union
+import ctypes
+import os
+import time
+import unittest.mock
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.multiprocess.native_completion import (
+    DeviceHostFuncDispatcher,
+    submit_callback_to_stream,
+)
+import lmcache.python_ops_fallback as _py_ops
+
+# ==========================================
+# 0. utils functions.
+# ==========================================
+
+
+# Device utility functions
+def device_sync(device: str) -> None:
+    """Synchronize device operations.
+
+    Args:
+        device: Device string ("cuda", "xpu", or "cpu")
+
+    This function synchronizes operations for GPU devices:
+    - For CUDA devices, calls torch.cuda.synchronize()
+    - For XPU devices, calls torch.xpu.synchronize()
+    - For CPU, no synchronization is needed (returns immediately)
+    """
+    if device == "cuda":
+        torch.cuda.synchronize()
+    elif device == "xpu":
+        if hasattr(torch, "xpu") and torch.xpu.is_available():
+            torch.xpu.synchronize()
+    else:
+        # TODO: add more device here
+        pass
+    # CPU requires no synchronization
+
+
+# ==========================================
+# 1. Backend Configuration
+# ==========================================
+
+
+def _build_backend_params() -> list:
+    """Build pytest parameter list for the backend fixture.
+
+    Returns one entry per available backend configuration:
+    - cuda_c_ops: uses lmcache.c_ops (requires CUDA and the CUDA extension)
+    - cuda_py_ops: uses lmcache.python_ops_fallback with GPU visible
+    - cpy_py_ops: uses lmcache.python_ops_fallback with GPU mocked away
+    - xpu_sycl_ops: uses lmcache.xpu_ops (requires XPU and the SYCL extension)
+    - xpu_py_ops: uses lmcache.python_ops_fallback with XPU visible
+    """
+    params = []
+    cuda_available = torch.cuda.is_available()
+
+    params.append(pytest.param(("cpu_py_ops", _py_ops, "cpu"), id="cpu_py_ops"))
+
+    if cuda_available:
+        try:
+            # First Party
+            import lmcache.c_ops as cuda_c_ops
+
+            params.append(
+                pytest.param(("cuda_c_ops", cuda_c_ops, "cuda"), id="cuda_c_ops")
+            )
+        except ImportError:
+            pass
+
+        if _py_ops._get_copy_lib() is not None:
+            params.append(
+                pytest.param(("cuda_py_ops", _py_ops, "cuda"), id="cuda_cuda_py_ops")
+            )
+        else:
+            params.append(
+                pytest.param(("cuda_py_ops", _py_ops, "cpu"), id="cuda_cpu_py_ops")
+            )
+
+    if hasattr(torch, "xpu") and torch.xpu.is_available():
+        try:
+            # First Party
+            import lmcache.c_ops as xpu_sycl_ops
+
+            params.append(
+                pytest.param(("xpu_sycl_ops", xpu_sycl_ops, "xpu"), id="xpu_sycl_ops")
+            )
+        except ImportError:
+            pass
+
+    return params
+
+
+_BACKEND_PARAMS = _build_backend_params()
+
+# Module-level storage: (scenario_name, backend_id) -> {result_key: tensor}
+_results: dict[tuple[str, str], dict[str, Any]] = {}
+
+
+@pytest.fixture(scope="module", params=_BACKEND_PARAMS)
+def backend(request: pytest.FixtureRequest) -> Any:
+    """Yield (backend_id, ops_module, device) for each backend config.
+
+    For the cpu_py_ops variant, torch.cuda.is_available is patched to
+    return False so the scenario code behaves as if no GPU is present.
+    """
+    backend_id, ops, device = request.param
+    if backend_id == "cpu_py_ops":
+        with unittest.mock.patch("torch.cuda.is_available", return_value=False):
+            yield backend_id, ops, device
+    else:
+        yield backend_id, ops, device
+
+
+# ==========================================
+# 2. Scenario functions
+# ==========================================
+
+
+def scenario_get_gpu_pci_bus_id(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test get_gpu_pci_bus_id returns a valid string on CUDA backends."""
+    res = ops.get_gpu_pci_bus_id(0)
+
+    is_valid = isinstance(res, str) and len(res) > 0
+
+    if torch.cuda.is_available() is False:
+        # for non cuda device, not expecting a valid return
+        # but crash should not happen
+        # and we mock a valid return here
+        is_valid = True
+
+    # 1 = PASS (call succeeded without crash)
+    # 0 = FAIL
+    return {
+        "get_gpu_pci_bus_id": torch.tensor([1 if is_valid else 0], dtype=torch.int32)
+    }
+
+
+def scenario_calculate_cdf(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test calculate_cdf for multiple bin counts."""
+    num_bins_list = [1, 2, 5, 11, 15, 31, 32, 63]
+    results: dict[str, torch.Tensor] = {}
+
+    # all bins should be smaller than 64 -> align with C ops
+    assert all(n < 64 for n in num_bins_list), (
+        f"All num_bins must be < 64, got {[n for n in num_bins_list if n >= 64]}"
+    )
+
+    for num_bins in num_bins_list:
+        torch.manual_seed(42)
+
+        # Create on CPU first for consistent RNG across backends
+        input_tensor = torch.randint(0, num_bins, (1, 1000, 1), dtype=torch.int8).to(
+            device
+        )
+
+        raw_output = ops.calculate_cdf(input_tensor, num_bins)
+
+        # Both CUDA and non-CUDA return int16 with shape
+        # [nlayers, nchannels, num_bins + 1]
+        nlayers, _, nchannels = input_tensor.shape
+        assert raw_output.shape == (nlayers, nchannels, num_bins + 1), (
+            f"Expected shape ({nlayers}, {nchannels}, {num_bins + 1}), "
+            f"got {raw_output.shape}"
+        )
+
+        out_cpu = raw_output.flatten().cpu()
+        out_int32 = out_cpu.to(torch.int32)
+        out_uint16 = torch.where(out_int32 < 0, out_int32 + 65536, out_int32)
+        final_result = out_uint16.float() / 65536.0
+
+        results[f"calculate_cdf_bins{num_bins}"] = final_result
+
+    return results
+
+
+def scenario_rotary_embedding_k_fused(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test rotary_embedding_k_fused for both NeoX and GPT-J rotation styles."""
+    torch.manual_seed(42)
+
+    # 1. Setup Dimensions
+    num_tokens = 128
+    num_kv_heads = 32
+    head_size = 128
+    max_position = 2048
+    rotary_dim = head_size
+
+    # 2. Generate Inputs on CPU first for consistent RNG across backends
+    old_positions = torch.randint(0, 1000, (num_tokens,), dtype=torch.long).to(device)
+    new_positions = old_positions + 1
+
+    cos_sin_cache = torch.randn(max_position, rotary_dim, dtype=torch.float32).to(
+        device
+    )
+
+    # Test both is_neox=True (NeoX-style, contiguous halves) and
+    # is_neox=False (GPT-J-style, interleaved)
+    results: dict[str, torch.Tensor] = {}
+    for is_neox in [True, False]:
+        # Reset seed for consistent key tensor across both tests
+        torch.manual_seed(42)
+
+        key = torch.randn(num_tokens, num_kv_heads, head_size, dtype=torch.float32).to(
+            device
+        )
+
+        # 3. Execute (in-place update on key)
+        ops.rotary_embedding_k_fused(
+            old_positions,
+            new_positions,
+            key,
+            head_size,
+            cos_sin_cache,
+            is_neox,
+        )
+
+        # 4. Collect with is_neox suffix to distinguish the two test cases
+        neox_suffix = "neox" if is_neox else "gptj"
+        results[f"rotary_embedding_k_fused_{neox_suffix}"] = key.cpu()
+
+    return results
+
+
+def scenario_lmcache_memcpy_async(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test lmcache_memcpy_async for H2D and D2H memory transfers.
+
+    Tests both pointer mode (int pointers) and tensor mode (torch.Tensor objects).
+    Uses pointer mode for CPU/CUDA devices and tensor mode for other devices.
+
+    Exercises multiple boundary conditions to verify correct behaviour for
+    both the CUDA c_ops backend (which chunks at alignment boundaries via
+    cudaMemcpyAsync) and the Python fallback backend (which issues a single
+    synchronous copy):
+      - copy spanning exactly one aligned block
+      - copy entirely within one aligned block (no boundary crossing)
+      - copy crossing a single alignment boundary
+      - copy crossing multiple alignment boundaries
+      - copy starting exactly at an alignment boundary
+      - copy with an unaligned start offset crossing many boundaries
+    Both H2D and D2H directions are verified for each boundary condition.
+    """
+    torch.manual_seed(42)
+
+    # Buffer large enough for all boundary test cases (max offset+nbytes = 16+200 = 216)
+    buf_size = 256
+    alignment = 64  # boundary interval in bytes (must be a power of two)
+
+    src_host = torch.randint(0, 256, (buf_size,), dtype=torch.uint8)
+    gpu_buffer = torch.zeros(buf_size, dtype=torch.uint8, device=device)
+
+    dst_host = torch.zeros(buf_size, dtype=torch.uint8)
+    if device in ("cuda", "xpu"):
+        dst_host = dst_host.pin_memory()
+
+    h2d_dir = ops.TransferDirection.H2D
+    d2h_dir = ops.TransferDirection.D2H
+
+    # Decide mode based on the running device.
+    # The native CUDA/XPU backend only accepts a tensor of uint64 pointers;
+    # only the Python fallback supports list[Tensor].
+    use_tensor_mode = device not in ("cpu", "cuda", "xpu")
+
+    # (host_buffer_offset, nbytes) boundary test cases:
+    #   (0,  64): exactly one aligned block from the start
+    #   (32, 32): entirely within one block, no boundary crossing
+    #   (32, 64): crosses one boundary — [32..64) then [64..96)
+    #   (0, 192): three full aligned blocks (boundaries at 64 and 128)
+    #   (64, 128): starts at alignment boundary, spans two full blocks
+    #   (16, 200): unaligned start, crosses multiple boundaries
+    test_cases = [
+        (0, 64),
+        (32, 32),
+        (32, 64),
+        (0, 192),
+        (64, 128),
+        (16, 200),
+    ]
+
+    all_results: list[torch.Tensor] = []
+
+    for offset, nbytes in test_cases:
+        gpu_buffer.zero_()
+        dst_host.zero_()
+        expected = src_host[offset : offset + nbytes].clone()
+
+        device_sync(device)
+
+        if use_tensor_mode:
+            ops.lmcache_memcpy_async(
+                gpu_buffer[offset : offset + nbytes],
+                src_host[offset : offset + nbytes],
+                nbytes,
+                h2d_dir,
+                0,
+                alignment,
+            )
+            device_sync(device)
+            ops.lmcache_memcpy_async(
+                dst_host[offset : offset + nbytes],
+                gpu_buffer[offset : offset + nbytes],
+                nbytes,
+                d2h_dir,
+                0,
+                alignment,
+            )
+        else:
+            ops.lmcache_memcpy_async(
+                gpu_buffer.data_ptr() + offset,
+                src_host.data_ptr() + offset,
+                nbytes,
+                h2d_dir,
+                offset,
+                alignment,
+            )
+            device_sync(device)
+            ops.lmcache_memcpy_async(
+                dst_host.data_ptr() + offset,
+                gpu_buffer.data_ptr() + offset,
+                nbytes,
+                d2h_dir,
+                offset,
+                alignment,
+            )
+
+        device_sync(device)
+
+        result = dst_host[offset : offset + nbytes].cpu()
+        assert torch.equal(result, expected), (
+            f"Boundary test (offset={offset}, nbytes={nbytes}, alignment={alignment}): "
+            f"data corrupted, max diff = "
+            f"{(result.float() - expected.float()).abs().max().item()}"
+        )
+        all_results.append(result)
+
+    return {"lmcache_memcpy_async": torch.cat(all_results)}
+
+
+def scenario_load_and_reshape_flash(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test load_and_reshape_flash extracts KV cache tokens into contiguous buffer."""
+    torch.manual_seed(42)
+
+    # 1. Standard Params
+    src_device = device
+    dst_device = "cpu"
+
+    num_blocks = 100
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    num_layers = 32
+    num_tokens = 256
+    chunk_size = 256
+    dtype = torch.bfloat16
+
+    # 2. Setup Data (Deterministic Pattern)
+    total_elements = num_blocks * block_size * num_heads * head_size
+
+    kv_cache_cpu = []
+    for i in range(num_layers):
+        base_tensor = torch.linspace(i, i + 1, total_elements, dtype=torch.float32)
+        base_tensor = base_tensor.reshape(
+            num_blocks, block_size, num_heads, head_size
+        ).to(dtype)
+        k = base_tensor
+        v = base_tensor + 0.5
+        kv_cache_cpu.append([k, v])
+
+    kv_cache = [
+        [layer[0].to(src_device), layer[1].to(src_device)] for layer in kv_cache_cpu
+    ]
+
+    # Slot mapping: deterministic strided selection
+    step = (num_blocks * block_size) // num_tokens
+    slot_indices = list(range(0, num_blocks * block_size, step))[:num_tokens]
+    slot_mapping = torch.tensor(slot_indices, device=src_device, dtype=torch.int64)
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+
+    # 3. Extract (to CPU pinned)
+    extracted_chunks = []
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        mem_obj_shape = (2, num_layers, len(slot_mapping_temp), num_heads * head_size)
+        mem_obj_tensor = torch.zeros(mem_obj_shape, dtype=dtype, device=dst_device)
+
+        if device in ("cuda", "xpu"):
+            mem_obj_tensor = mem_obj_tensor.pin_memory()
+
+        for layer_id in range(num_layers):
+            ops.load_and_reshape_flash(
+                mem_obj_tensor,
+                kv_cache[layer_id][0],
+                kv_cache[layer_id][1],
+                slot_mapping_temp,
+                layer_id,
+            )
+        extracted_chunks.append(mem_obj_tensor)
+
+    device_sync(device)
+
+    # 4. Verify: compare extracted data against original kv_cache
+    #    mem_obj_tensor layout:
+    #       [2, num_layers, num_tokens_in_chunk, num_heads * head_size]
+    #    dim 0: K=0, V=1
+    #    Original kv_cache layout: [num_blocks, block_size, num_heads, head_size]
+    #    slot_mapping tells us which (block, offset) each token comes from
+    for chunk_id, slot_mapping_temp in enumerate(slot_mapping_chunked):
+        slots = slot_mapping_temp.cpu()
+        extracted = extracted_chunks[chunk_id].cpu()
+
+        for layer_id in range(num_layers):
+            orig_k = kv_cache_cpu[layer_id][
+                0
+            ]  # [num_blocks, block_size, num_heads, head_size]
+            orig_v = kv_cache_cpu[layer_id][1]
+
+            for tok_idx, slot in enumerate(slots):
+                block_idx = slot.item() // block_size
+                offset = slot.item() % block_size
+
+                # Expected: flattened [num_heads * head_size]
+                expected_k = orig_k[block_idx, offset].reshape(-1)
+                expected_v = orig_v[block_idx, offset].reshape(-1)
+
+                # Extracted
+                got_k = extracted[0, layer_id, tok_idx]
+                got_v = extracted[1, layer_id, tok_idx]
+
+                k_diff = (got_k.float() - expected_k.float()).abs().max().item()
+                assert torch.equal(got_k, expected_k), (
+                    f"K mismatch layer={layer_id}, slot={slot.item()}, "
+                    f"max diff={k_diff}"
+                )
+
+                v_diff = (got_v.float() - expected_v.float()).abs().max().item()
+                assert torch.equal(got_v, expected_v), (
+                    f"V mismatch layer={layer_id}, slot={slot.item()}, "
+                    f"max diff={v_diff}"
+                )
+
+    # 5. Return ALL extracted chunks concatenated for cross-backend comparison
+    return {
+        "load_and_reshape_flash": torch.cat([c.cpu() for c in extracted_chunks], dim=2)
+    }
+
+
+def scenario_reshape_and_cache_back_flash(
+    ops: Any, device: str
+) -> dict[str, torch.Tensor]:
+    """Test reshape_and_cache_back_flash writes tokens back into paged KV cache."""
+    torch.manual_seed(42)
+
+    # 1. Environment Setup
+    src_device = "cpu"
+    dst_device = device
+
+    num_blocks = 100
+    block_size = 16
+    num_heads = 8
+    head_size = 128
+    num_layers = 32
+    num_tokens = 256
+    chunk_size = 256
+    dtype = torch.bfloat16
+
+    # 2. Prepare Source Data (CPU Buffer)
+    # Shape: [2, num_layers, num_tokens, num_heads * head_size]
+    mem_obj_shape = (2, num_layers, num_tokens, num_heads * head_size)
+    src_buffer = torch.zeros(mem_obj_shape, dtype=dtype, device=src_device)
+
+    # Data Pattern: Odd numbers (1.0, 3.0, 5.0, ...)
+    for i in range(num_tokens):
+        val = 1.0 + (i * 2.0)
+        src_buffer[0, :, i, :] = val  # Key
+        src_buffer[1, :, i, :] = val + 0.5  # Value
+
+    if device in ("cuda", "xpu"):
+        src_buffer = src_buffer.pin_memory()
+
+    # 3. Prepare Destination (Empty Cache)
+    kv_cache = [
+        [
+            torch.zeros(
+                num_blocks,
+                block_size,
+                num_heads,
+                head_size,
+                device=dst_device,
+                dtype=dtype,
+            ),
+            torch.zeros(
+                num_blocks,
+                block_size,
+                num_heads,
+                head_size,
+                device=dst_device,
+                dtype=dtype,
+            ),
+        ]
+        for _ in range(num_layers)
+    ]
+
+    # 4. Slot Mapping (Continuous: Token 0 → Slot 0, Token 1 → Slot 1, ...)
+    slot_indices = list(range(num_tokens))
+    slot_mapping = torch.tensor(slot_indices, device=dst_device, dtype=torch.int64)
+    slot_mapping_chunked = torch.split(slot_mapping, chunk_size)
+
+    # 5. Execute Operator (Load Back)
+    current_token_offset = 0
+    for chunk_id, slot_chunk in enumerate(slot_mapping_chunked):
+        chunk_len = len(slot_chunk)
+
+        buffer_chunk = src_buffer[
+            :, :, current_token_offset : current_token_offset + chunk_len, :
+        ]
+        if not buffer_chunk.is_contiguous():
+            buffer_chunk = buffer_chunk.contiguous()
+
+        for layer_id in range(num_layers):
+            ops.reshape_and_cache_back_flash(
+                buffer_chunk,
+                kv_cache[layer_id][0],
+                kv_cache[layer_id][1],
+                slot_chunk,
+                layer_id,
+            )
+        current_token_offset += chunk_len
+
+    device_sync(device)
+
+    # 6. Verify: check written values against source pattern
+    for layer_id in range(num_layers):
+        k_cache = kv_cache[layer_id][
+            0
+        ].cpu()  # [num_blocks, block_size, num_heads, head_size]
+        v_cache = kv_cache[layer_id][1].cpu()
+
+        for tok_idx, slot in enumerate(slot_indices):
+            block_idx = slot // block_size
+            offset = slot % block_size
+
+            expected_k_val = 1.0 + (tok_idx * 2.0)
+            expected_v_val = expected_k_val + 0.5
+
+            got_k = k_cache[block_idx, offset]
+            got_v = v_cache[block_idx, offset]
+
+            expected_k = torch.full_like(got_k, expected_k_val)
+            expected_v = torch.full_like(got_v, expected_v_val)
+
+            assert torch.allclose(got_k.float(), expected_k.float(), atol=0.1), (
+                f"K mismatch at layer={layer_id}, slot={slot}, "
+                f"expected={expected_k_val}, got={got_k[0, 0].item()}"
+            )
+            assert torch.allclose(got_v.float(), expected_v.float(), atol=0.1), (
+                f"V mismatch at layer={layer_id}, slot={slot}, "
+                f"expected={expected_v_val}, got={got_v[0, 0].item()}"
+            )
+
+    # 7. Return first block of layer 0 key cache for cross-backend comparison
+    return {"reshape_and_cache_back_flash": kv_cache[0][0][0].cpu()}
+
+
+def scenario_encode_fast_new(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test encode_fast_new produces valid, non-empty encoded output."""
+    torch.manual_seed(42)
+
+    # 1. Hyperparameters
+    nlayers = 2
+    nchannels = 4
+    ntokens = 128
+    alphabet_size = 16
+    max_buf_len = ntokens * 2
+
+    # 2. Construct Data on target device
+    # A. CDF: uniform distribution, strictly increasing
+    step = 100 // alphabet_size
+    base_cdf = torch.arange(0, 100, step, dtype=torch.int32)
+    base_cdf = base_cdf[:alphabet_size]
+
+    cdf_cpu = (
+        base_cdf.unsqueeze(0).unsqueeze(0).expand(nlayers, nchannels, -1).contiguous()
+    )
+    cdf = cdf_cpu.to(dtype=torch.int16, device=device)
+
+    # B. Input symbols: cycling 0..14
+    total_syms = nlayers * ntokens * nchannels
+    input_cpu = torch.arange(total_syms, dtype=torch.float32)
+    input_cpu = (input_cpu % (alphabet_size - 1)).to(torch.int8)
+    input_cpu = input_cpu.reshape(nlayers, ntokens, nchannels)
+    input_sym = input_cpu.to(device=device)
+
+    # 3. Prepare Outputs
+    output_buffer = torch.zeros(
+        (nlayers, nchannels, max_buf_len),
+        dtype=torch.uint8,
+        device=device,
+    )
+    output_lengths = torch.zeros(
+        (nlayers, nchannels),
+        dtype=torch.int32,
+        device=device,
+    )
+
+    # 4. Execute
+    ops.encode_fast_new(
+        cdf,
+        input_sym,
+        output_buffer,
+        output_lengths,
+    )
+
+    device_sync(device)
+
+    # 5. Verify
+    lengths_cpu = output_lengths.cpu()
+
+    assert (lengths_cpu > 0).all(), "Encoding produced zero-length output!"
+    assert (lengths_cpu <= max_buf_len).all(), "Buffer overflow detected!"
+
+    # 6. Return: first 200 bytes of layer 0, channel 0
+    valid_len = int(lengths_cpu[0, 0].item())
+    res = output_buffer[0, 0, : min(valid_len, 200)].cpu()
+    return {"encode_fast_new": res}
+
+
+def scenario_decode_fast_new(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test decode_fast_new correctly decodes a round-tripped encoded stream."""
+    torch.manual_seed(42)
+
+    # 1. Config
+    nlayers = 2
+    nchannels = 4
+    ntokens = 128
+    alphabet_size = 16
+    max_buf_len = ntokens * 2
+
+    # 2. Data Generation on CPU first for consistent RNG across backends
+    cdf = torch.randint(
+        1,
+        100,
+        (nlayers, nchannels, alphabet_size),
+        dtype=torch.int32,
+    )
+    cdf = torch.cumsum(cdf, dim=-1).to(torch.int16).to(device)
+
+    input_sym = torch.randint(
+        0,
+        alphabet_size - 2,
+        (nlayers, ntokens, nchannels),
+        dtype=torch.int8,
+    ).to(device)
+
+    # 3. Encode first (need encoded data to test decode)
+    encoded_buffer = torch.zeros(
+        (nlayers, nchannels, max_buf_len),
+        dtype=torch.uint8,
+        device=device,
+    )
+    encoded_lengths = torch.zeros(
+        (nlayers, nchannels),
+        dtype=torch.int32,
+        device=device,
+    )
+
+    ops.encode_fast_new(
+        cdf,
+        input_sym,
+        encoded_buffer,
+        encoded_lengths,
+    )
+    device_sync(device)
+
+    # 4. Decode
+    decoded_sym = torch.zeros_like(input_sym, dtype=torch.uint8)
+
+    ops.decode_fast_new(
+        cdf,
+        encoded_buffer,
+        encoded_lengths,
+        decoded_sym,
+    )
+    device_sync(device)
+
+    # 5. Verify: decoded must match original
+    input_uint8 = input_sym.to(torch.uint8)
+    mismatch = (input_uint8 != decoded_sym).sum().item()
+    if mismatch > 0:
+        mask = input_uint8 != decoded_sym
+        ly, t, c = mask.nonzero()[0].tolist()
+        pytest.fail(
+            f"Decode mismatch: {mismatch} errors. "
+            f"First diff at L{ly}T{t}C{c}: "
+            f"orig={input_uint8[ly, t, c].item()} "
+            f"decoded={decoded_sym[ly, t, c].item()}"
+        )
+
+    # 6. Return decoded slice for cross-backend comparison
+    return {"decode_fast_new": decoded_sym[0, :20, 0].cpu()}
+
+
+def scenario_decode_fast_prefsum(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test decode_fast_prefsum correctly decodes with prefix-sum offsets."""
+    torch.manual_seed(42)
+
+    # 1. Configuration
+    nlayers = 2
+    nchannels = 4
+    ntokens = 128
+    alphabet_size = 16
+    max_buf_len = ntokens * 2
+
+    # 2. Data Generation (Normalized CDF) on CPU first for consistent RNG
+    cdf = torch.randint(
+        1,
+        100,
+        (nlayers, nchannels, alphabet_size),
+        dtype=torch.int32,
+    )
+    cdf = torch.cumsum(cdf, dim=-1).float()
+    cdf = (cdf / cdf[..., -1:] * 65536).to(torch.int32)
+    cdf[..., -1] = 65536
+    cdf = cdf.to(torch.int16).to(device).contiguous()
+
+    input_sym = torch.randint(
+        0,
+        alphabet_size - 2,
+        (nlayers, ntokens, nchannels),
+        dtype=torch.int8,
+    ).to(device)
+
+    # 3. Encode to get variable lengths
+    tmp_buf = torch.zeros(
+        (nlayers, nchannels, max_buf_len),
+        dtype=torch.uint8,
+        device=device,
+    )
+    tmp_len = torch.zeros(
+        (nlayers, nchannels),
+        dtype=torch.int32,
+        device=device,
+    )
+    ops.encode_fast_new(cdf, input_sym, tmp_buf, tmp_len)
+    device_sync(device)
+
+    # 4. Pack into 1D dense bytestream
+    lens_flat = tmp_len.cpu().flatten().tolist()
+    bufs_flat = tmp_buf.cpu().reshape(-1, max_buf_len).numpy()
+    all_bytes = []
+    for i, length in enumerate(lens_flat):
+        all_bytes.extend(bufs_flat[i, :length].tolist())
+
+    bytestream_1d = torch.tensor(
+        all_bytes,
+        dtype=torch.uint8,
+        device=device,
+    ).contiguous()
+
+    # 5. Offsets (end-position via cumsum)
+    lengths_prefsum = (
+        tmp_len.flatten().cumsum(0).reshape(tmp_len.shape).to(torch.int64).to(device)
+    ).contiguous()
+
+    # 6. Decode
+    decoded_sym = (
+        torch.zeros_like(
+            input_sym,
+            dtype=torch.uint8,
+        )
+        .to(device)
+        .contiguous()
+    )
+
+    ops.decode_fast_prefsum(
+        cdf,
+        bytestream_1d,
+        lengths_prefsum,
+        decoded_sym,
+    )
+    device_sync(device)
+
+    # 7. Verify roundtrip
+    input_ref = input_sym.to(torch.uint8)
+    mismatch = (input_ref != decoded_sym).sum().item()
+    if mismatch > 0:
+        mask = input_ref != decoded_sym
+        ly, t, c = mask.nonzero()[0].tolist()
+        pytest.fail(
+            f"Prefsum mismatch: {mismatch} errors. "
+            f"First diff at L{ly}T{t}C{c}: "
+            f"orig={input_ref[ly, t, c].item()} "
+            f"decoded={decoded_sym[ly, t, c].item()}"
+        )
+
+    # 8. Return
+    return {
+        "decode_fast_prefsum": decoded_sym[0, :20, 0].cpu(),
+    }
+
+
+def scenario_single_layer_kv_transfer(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test single_layer_kv_transfer for multiple KV formats and directions."""
+    torch.manual_seed(42)
+
+    num_tokens = 64
+    num_blocks = 256
+    block_size = 16
+    num_heads = 12
+    head_size = 64
+    hidden_size = num_heads * head_size
+
+    slot_mapping = torch.arange(
+        0,
+        num_tokens * 2,
+        2,
+        device=device,
+    ).to(torch.int64)
+
+    # (engine_kv_format, is_mla, token_major, direction)
+    # direction: False = LMC→vLLM (H2D), True = vLLM→LMC (D2H)
+    test_cases = [
+        # flash attn: [2, NB, BS, NH, HS] — two_major
+        (ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS, False, True, False),
+        (ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS, False, False, False),
+        (ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS, False, True, True),
+        # flash infer: [NB, 2, BS, NH, HS]
+        (ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS, False, True, False),
+        (ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS, False, False, False),
+        (ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS, False, True, True),
+        # vLLM MLA: [NB, BS, HS]
+        (ops.EngineKVFormat.NL_X_NB_BS_HS, True, True, False),
+        (ops.EngineKVFormat.NL_X_NB_BS_HS, True, True, True),
+    ]
+
+    for engine_kv_format, is_mla, token_major, direction in test_cases:
+        dir_tag = "v2l" if direction else "l2v"
+        is_two_major = engine_kv_format == ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+        case_desc = (
+            f"fmt={engine_kv_format}, MLA={is_mla}, TM={token_major}, Dir={dir_tag}"
+        )
+
+        # ── 1. Setup Shapes ──
+        lmc_shape: tuple[int, ...] = ()
+        vllm_shape: tuple[int, ...] = ()
+        if is_mla:
+            lmc_shape = (num_tokens, hidden_size)
+            vllm_shape = (num_blocks, block_size, hidden_size)
+        else:
+            lmc_shape = (
+                (num_tokens, 2, hidden_size)
+                if token_major
+                else (2, num_tokens, hidden_size)
+            )
+            if is_two_major:
+                # flash attn: [2, num_blocks, block_size, num_heads, head_size]
+                vllm_shape = (2, num_blocks, block_size, num_heads, head_size)
+            else:
+                # flash infer: [num_blocks, 2, block_size, num_heads, head_size]
+                vllm_shape = (num_blocks, 2, block_size, num_heads, head_size)
+
+        # ── 2. Deterministic Data ──
+        lmc_size = 1
+        for s in lmc_shape:
+            lmc_size *= s
+        vllm_size = 1
+        for s in vllm_shape:
+            vllm_size *= s
+
+        lmc_tensor = (
+            (torch.arange(lmc_size, device=device) % 1000)
+            .to(torch.float16)
+            .reshape(lmc_shape)
+        )
+        vllm_tensor = (
+            (torch.arange(vllm_size, device=device) % 1000)
+            .to(torch.float16)
+            .reshape(vllm_shape)
+        )
+
+        # ── 3. Golden Reference ──
+        lmc_ref = lmc_tensor.clone()
+        vllm_ref = vllm_tensor.clone()
+        block_indices = slot_mapping // block_size
+        block_offsets = slot_mapping % block_size
+
+        if not direction:  # LMC → vLLM
+            if is_mla:
+                vllm_ref[block_indices, block_offsets, :] = lmc_ref
+            else:
+                src = lmc_ref if token_major else lmc_ref.permute(1, 0, 2)
+                src = src.view(num_tokens, 2, num_heads, head_size)
+                if is_two_major:
+                    # [2, NB, BS, NH, HS]
+                    vllm_ref[0, block_indices, block_offsets] = src[:, 0, :, :]
+                    vllm_ref[1, block_indices, block_offsets] = src[:, 1, :, :]
+                else:
+                    # [NB, 2, BS, NH, HS]
+                    vllm_ref[block_indices, 0, block_offsets] = src[:, 0, :, :]
+                    vllm_ref[block_indices, 1, block_offsets] = src[:, 1, :, :]
+        else:  # vLLM → LMC
+            if is_mla:
+                lmc_ref = vllm_ref[block_indices, block_offsets, :]
+            else:
+                if is_two_major:
+                    k = vllm_ref[0, block_indices, block_offsets]
+                    v = vllm_ref[1, block_indices, block_offsets]
+                else:
+                    k = vllm_ref[block_indices, 0, block_offsets]
+                    v = vllm_ref[block_indices, 1, block_offsets]
+                combined = torch.stack(
+                    [k, v],
+                    dim=1,
+                ).view(num_tokens, 2, hidden_size)
+                lmc_ref = combined if token_major else combined.permute(1, 0, 2)
+
+        # ── 4. Execute ──
+        xfer_dir = ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D
+        ops.single_layer_kv_transfer(
+            lmc_tensor,
+            vllm_tensor,
+            slot_mapping,
+            xfer_dir,
+            engine_kv_format,
+            token_major,
+        )
+        device_sync(device)
+
+        # ── 5. Verify ──
+        if not direction:
+            torch.testing.assert_close(
+                vllm_tensor,
+                vllm_ref,
+                rtol=1e-3,
+                atol=1e-3,
+                msg=f"Mismatch in {case_desc}",
+            )
+        else:
+            torch.testing.assert_close(
+                lmc_tensor,
+                lmc_ref,
+                rtol=1e-3,
+                atol=1e-3,
+                msg=f"Mismatch in {case_desc}",
+            )
+
+    # ── 6. Collect canonical results for cross-backend comparison ──
+    # Use flash attn (two_major) format to match original file names
+    canonical_cases = [
+        (False, True, False),  # l2v, non-MLA
+        (False, True, True),  # v2l, non-MLA
+        (True, True, False),  # l2v, MLA
+        (True, True, True),  # v2l, MLA
+    ]
+
+    results: dict[str, torch.Tensor] = {}
+    for is_mla, token_major, direction in canonical_cases:
+        dir_tag = "v2l" if direction else "l2v"
+
+        if is_mla:
+            lmc_shape = (num_tokens, hidden_size)
+            vllm_shape = (num_blocks, block_size, hidden_size)
+            fmt = ops.EngineKVFormat.NL_X_NB_BS_HS
+        else:
+            lmc_shape = (num_tokens, 2, hidden_size)
+            vllm_shape = (2, num_blocks, block_size, num_heads, head_size)
+            fmt = ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+
+        lmc_size = 1
+        for s in lmc_shape:
+            lmc_size *= s
+        vllm_size = 1
+        for s in vllm_shape:
+            vllm_size *= s
+
+        lmc_tensor = (
+            (torch.arange(lmc_size, device=device) % 1000)
+            .to(torch.float16)
+            .reshape(lmc_shape)
+        )
+        vllm_tensor = (
+            (torch.arange(vllm_size, device=device) % 1000)
+            .to(torch.float16)
+            .reshape(vllm_shape)
+        )
+
+        xfer_dir = ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D
+        ops.single_layer_kv_transfer(
+            lmc_tensor,
+            vllm_tensor,
+            slot_mapping,
+            xfer_dir,
+            fmt,
+            token_major,
+        )
+        device_sync(device)
+
+        result = lmc_tensor.cpu() if direction else vllm_tensor.cpu()
+        results[f"single_layer_kv_transfer_{dir_tag}_mla_{is_mla}"] = result
+
+    return results
+
+
+def scenario_single_layer_kv_transfer_sgl(
+    ops: Any, device: str
+) -> dict[str, torch.Tensor]:
+    """Test single_layer_kv_transfer_sgl for SGLang KV format."""
+    torch.manual_seed(42)
+
+    num_tokens = 32
+    num_blocks = 128
+    block_size = 16
+    num_heads = 8
+    head_size = 64
+    hidden_size = num_heads * head_size
+
+    slot_mapping = torch.arange(
+        0,
+        num_tokens * 3,
+        3,
+        device=device,
+    ).to(torch.int64)
+
+    # (token_major, direction)
+    # direction: False = LMC→SGL, True = SGL→LMC
+    test_cases = [
+        (True, False),
+        (False, False),
+        (True, True),
+        (False, True),
+    ]
+
+    results: dict[str, torch.Tensor] = {}
+    for token_major, direction in test_cases:
+        dir_tag = "s2l" if direction else "l2s"
+
+        # 1. Setup Shapes
+        lmc_shape = (
+            (num_tokens, 2, hidden_size)
+            if token_major
+            else (2, num_tokens, hidden_size)
+        )
+        sgl_shape = (
+            num_blocks,
+            block_size,
+            num_heads,
+            head_size,
+        )
+
+        # 2. Deterministic Data
+        lmc_size = 1
+        for s in lmc_shape:
+            lmc_size *= s
+        sgl_size = 1
+        for s in sgl_shape:
+            sgl_size *= s
+
+        lmc_tensor = (
+            (torch.arange(lmc_size, device=device) % 500)
+            .to(torch.float16)
+            .reshape(lmc_shape)
+        )
+        sgl_k_tensor = (
+            (torch.arange(sgl_size, device=device) % 500 + 500)
+            .to(torch.float16)
+            .reshape(sgl_shape)
+        )
+        sgl_v_tensor = (
+            (torch.arange(sgl_size, device=device) % 500 + 1000)
+            .to(torch.float16)
+            .reshape(sgl_shape)
+        )
+
+        # 3. Golden Reference
+        lmc_ref = lmc_tensor.clone()
+        sgl_k_ref = sgl_k_tensor.clone()
+        sgl_v_ref = sgl_v_tensor.clone()
+
+        block_indices = slot_mapping // block_size
+        block_offsets = slot_mapping % block_size
+
+        if not direction:  # LMC → SGL
+            src = lmc_ref if token_major else lmc_ref.permute(1, 0, 2)
+            src_k = src[:, 0, :].view(
+                num_tokens,
+                num_heads,
+                head_size,
+            )
+            src_v = src[:, 1, :].view(
+                num_tokens,
+                num_heads,
+                head_size,
+            )
+            sgl_k_ref[block_indices, block_offsets] = src_k
+            sgl_v_ref[block_indices, block_offsets] = src_v
+        else:  # SGL → LMC
+            k_data = sgl_k_ref[block_indices, block_offsets].reshape(
+                num_tokens, hidden_size
+            )
+            v_data = sgl_v_ref[block_indices, block_offsets].reshape(
+                num_tokens, hidden_size
+            )
+
+            combined = torch.stack(
+                [k_data, v_data],
+                dim=1,
+            )  # [N, 2, H]
+            lmc_ref = combined if token_major else combined.permute(1, 0, 2)
+
+        # 4. Execute
+        ops.single_layer_kv_transfer_sgl(
+            lmc_tensor,
+            sgl_k_tensor,
+            sgl_v_tensor,
+            slot_mapping,
+            ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D,
+            token_major,
+        )
+        device_sync(device)
+
+        # 5. Verify
+        case_desc = f"TM={token_major}, Dir={dir_tag}"
+        if not direction:
+            torch.testing.assert_close(
+                sgl_k_tensor,
+                sgl_k_ref,
+                rtol=1e-3,
+                atol=1e-3,
+                msg=f"K mismatch in {case_desc}",
+            )
+            torch.testing.assert_close(
+                sgl_v_tensor,
+                sgl_v_ref,
+                rtol=1e-3,
+                atol=1e-3,
+                msg=f"V mismatch in {case_desc}",
+            )
+        else:
+            torch.testing.assert_close(
+                lmc_tensor,
+                lmc_ref,
+                rtol=1e-3,
+                atol=1e-3,
+                msg=f"Mismatch in {case_desc}",
+            )
+
+        # 6. Collect each case separately
+        result = lmc_tensor.cpu() if direction else sgl_k_tensor.cpu()
+        results[f"single_layer_kv_transfer_sgl_{dir_tag}_tm_{token_major}"] = result
+
+    return results
+
+
+def scenario_multi_layer_kv_transfer(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test multi_layer_kv_transfer for multiple paged KV formats and directions.
+
+    Tests both pointer mode (torch.Tensor of int64 pointers) and tensor list mode
+    (list[torch.Tensor]) for key_value_ptrs.
+    """
+    torch.manual_seed(42)
+
+    num_layers = 2
+    num_tokens = 4
+    head_size = 16
+    page_buffer_size = 10
+    block_size = 5
+    dtype = torch.float32
+
+    slot_mapping = torch.tensor(
+        [0, 2, 5, 9],
+        dtype=torch.int64,
+        device=device,
+    )
+
+    # ── Format-specific test cases ──
+    # Each: (engine_kv_format, is_mla, block_size_arg)
+    format_cases = [
+        (ops.EngineKVFormat.NB_NL_TWO_BS_NH_HS, False, 1),  # vLLM cross layer
+        (ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS, False, 1),  # flash attn
+        (ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS, False, block_size),  # flash infer
+        (ops.EngineKVFormat.NL_X_NB_BS_HS, True, 1),  # vLLM MLA
+        (ops.EngineKVFormat.NL_X_NBBS_ONE_HS, True, 1),  # SGLang MLA
+    ]
+
+    # Decide mode based on the running device.
+    # The native CUDA/XPU backend only accepts a tensor of uint64 pointers;
+    # only the Python fallback supports list[Tensor].
+    use_tensor_list = device not in ("cpu", "cuda", "xpu")
+
+    for engine_kv_format, is_mla, bs_arg in format_cases:
+        k_or_v_size = 1 if is_mla else 2
+
+        for direction in [True, False]:
+            dir_tag = "paged2lmc" if direction else "lmc2paged"
+            fmt_name = str(engine_kv_format).split(".")[-1]
+
+            # ── 1. LMCache Tensor ──
+            lmc_shape = (k_or_v_size, num_layers, num_tokens, head_size)
+            key_value = torch.zeros(lmc_shape, dtype=dtype, device="cpu")
+            if device in ("cuda", "xpu"):
+                key_value = key_value.pin_memory()
+
+            if not direction:  # LMC → Paged
+                for kv in range(k_or_v_size):
+                    for ly in range(num_layers):
+                        for t in range(num_tokens):
+                            val = (
+                                kv * 5000
+                                + ly * 1000
+                                + t * 10
+                                + torch.arange(head_size, device=device)
+                            ).to(dtype)
+                            key_value[kv, ly, t] = val
+
+            # ── 2. Paged Buffers (one per layer) ──
+            page_buffers = []
+            for ly in range(num_layers):
+                if engine_kv_format == ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS:
+                    num_blocks = page_buffer_size // bs_arg
+                    pb = torch.zeros(
+                        (num_blocks, 2, bs_arg, head_size),
+                        dtype=dtype,
+                        device=device,
+                    )
+                elif is_mla:
+                    pb = torch.zeros(
+                        (page_buffer_size, head_size),
+                        dtype=dtype,
+                        device=device,
+                    )
+                else:
+                    # Handles NB_NL_TWO_BS_NH_HS and NL_X_TWO_NB_BS_NH_HS
+                    pb = torch.zeros(
+                        (2, page_buffer_size, head_size),
+                        dtype=dtype,
+                        device=device,
+                    )
+
+                if direction:  # Paged → LMC
+                    for s in range(page_buffer_size):
+                        for kv in range(k_or_v_size):
+                            val = (
+                                kv * 7000
+                                + ly * 2000
+                                + s * 10
+                                + torch.arange(head_size, device=device)
+                            ).to(dtype)
+                            if (
+                                engine_kv_format
+                                == ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS
+                            ):
+                                blk_idx = s // bs_arg
+                                blk_off = s % bs_arg
+                                pb[blk_idx, kv, blk_off] = val
+                            elif is_mla:
+                                pb[s] = val
+                            else:
+                                # Handles NB_NL_TWO_BS_NH_HS and NL_X_TWO_NB_BS_NH_HS
+                                pb[kv, s] = val
+
+                page_buffers.append(pb)
+
+            # ── 3. Prepare key_value_ptrs (pointer mode or tensor list mode) ──
+            key_value_ptrs: Union[list[torch.Tensor], torch.Tensor]
+            if use_tensor_list:
+                # Tensor list mode: pass the tensor objects directly
+                key_value_ptrs = page_buffers
+            else:
+                # Pointer mode: create tensor of uint64 pointers
+                key_value_ptrs = torch.tensor(
+                    [pb.data_ptr() for pb in page_buffers],
+                    dtype=torch.uint64,
+                    device=device,
+                )
+
+            # ── 4. Execute ──
+            xfer_dir = (
+                ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D
+            )
+            ops.multi_layer_kv_transfer(
+                key_value,
+                key_value_ptrs,
+                slot_mapping,
+                torch.device(device),
+                page_buffer_size,
+                xfer_dir,
+                engine_kv_format,
+                bs_arg,
+            )
+            device_sync(device)
+
+            # ── 5. Verify (internal, per-format) ──
+            for t_id in range(num_tokens):
+                s_idx = int(slot_mapping[t_id].item())
+                for ly in range(num_layers):
+                    for kv in range(k_or_v_size):
+                        lmc_val = key_value[kv, ly, t_id]
+
+                        if engine_kv_format == ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS:
+                            blk_idx = s_idx // bs_arg
+                            blk_off = s_idx % bs_arg
+                            paged_val = page_buffers[ly][blk_idx, kv, blk_off]
+                        elif is_mla:
+                            paged_val = page_buffers[ly][s_idx]
+                        else:
+                            # Handles NB_NL_TWO_BS_NH_HS and NL_X_TWO_NB_BS_NH_HS
+                            paged_val = page_buffers[ly][kv, s_idx]
+
+                        torch.testing.assert_close(
+                            lmc_val.to("cpu"),
+                            paged_val.to("cpu"),
+                            msg=(
+                                f"Mismatch: {fmt_name} {dir_tag} "
+                                f"(tensor_list={use_tensor_list}), "
+                                f"kv={kv}, layer={ly}, token={t_id}"
+                            ),
+                        )
+
+    # ── 6. Collect ONE canonical result for cross-backend comparison ──
+    # Use flash attn format (NL_X_TWO_NB_BS_NH_HS), re-run canonical cases
+    canonical_format = ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    results: dict[str, torch.Tensor] = {}
+    for direction in [True, False]:
+        dir_tag = "paged2lmc" if direction else "lmc2paged"
+        lmc_shape = (2, num_layers, num_tokens, head_size)
+        key_value = torch.zeros(lmc_shape, dtype=dtype, device=device)
+
+        if not direction:
+            for ly in range(num_layers):
+                for t in range(num_tokens):
+                    val = (
+                        ly * 1000 + t * 10 + torch.arange(head_size, device=device)
+                    ).to(dtype)
+                    key_value[0, ly, t] = val
+                    key_value[1, ly, t] = val + 500
+
+        page_buffers = []
+        for ly in range(num_layers):
+            pb = torch.zeros(
+                (2, page_buffer_size, head_size),
+                dtype=dtype,
+                device=device,
+            )
+            if direction:
+                for s in range(page_buffer_size):
+                    val = (
+                        ly * 2000 + s * 10 + torch.arange(head_size, device=device)
+                    ).to(dtype)
+                    pb[0, s] = val
+                    pb[1, s] = val + 700
+            page_buffers.append(pb)
+
+        if use_tensor_list:
+            key_value_ptrs = page_buffers
+        else:
+            key_value_ptrs = torch.tensor(
+                [pb.data_ptr() for pb in page_buffers],
+                dtype=torch.uint64,
+                device=device,
+            )
+
+        xfer_dir = ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D
+        ops.multi_layer_kv_transfer(
+            key_value,
+            key_value_ptrs,
+            slot_mapping,
+            torch.device(device),
+            page_buffer_size,
+            xfer_dir,
+            canonical_format,
+            1,
+        )
+        device_sync(device)
+
+        results[f"multi_layer_kv_transfer_{dir_tag}"] = key_value.cpu()
+
+    return results
+
+
+def scenario_multi_layer_kv_transfer_unilateral(
+    ops: Any, device: str
+) -> dict[str, torch.Tensor]:
+    """Test multi_layer_kv_transfer_unilateral for non-interleaved K/V pointers.
+
+    Tests both pointer mode (torch.Tensor of int64 pointers) and tensor list mode
+    (list[torch.Tensor]) for key_value_ptrs.
+    """
+    torch.manual_seed(42)
+
+    num_layers = 2
+    num_tokens = 4
+    head_size = 16
+    page_buffer_size = 10
+    dtype = torch.float32
+
+    slot_mapping = torch.tensor(
+        [1, 3, 4, 7],
+        dtype=torch.int64,
+        device=device,
+    )
+
+    # ── Test cases: (engine_kv_format, is_mla) ──
+    format_cases = [
+        (
+            ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+            False,
+        ),  # SGLang MHA (unilateral path)
+        (
+            ops.EngineKVFormat.NL_X_NB_BS_HS,
+            True,
+        ),  # vLLM MLA (delegates to multi_layer_kv_transfer)
+        (
+            ops.EngineKVFormat.NL_X_NBBS_ONE_HS,
+            True,
+        ),  # SGLang MLA (delegates to multi_layer_kv_transfer)
+    ]
+
+    # Decide mode based on the running device.
+    # The native CUDA/XPU backend only accepts a tensor of uint64 pointers;
+    # only the Python fallback supports list[Tensor].
+    use_tensor_list = device not in ("cpu", "cuda", "xpu")
+
+    for engine_kv_format, is_mla in format_cases:
+        k_or_v_size = 1 if is_mla else 2
+
+        for direction in [True, False]:
+            dir_tag = "p2l" if direction else "l2p"
+
+            # ── 1. LMCache Tensor ──
+            lmc_shape = (k_or_v_size, num_layers, num_tokens, head_size)
+            lmc_tensor = torch.zeros(lmc_shape, dtype=dtype, device="cpu")
+            if device in ("cuda", "xpu"):
+                lmc_tensor = lmc_tensor.pin_memory()
+
+            if not direction:  # LMC → Paged
+                for kv in range(k_or_v_size):
+                    for ly in range(num_layers):
+                        for t in range(num_tokens):
+                            val = (
+                                kv * 5000
+                                + ly * 1000
+                                + t * 10
+                                + torch.arange(head_size, device=device)
+                            ).to(dtype)
+                            lmc_tensor[kv, ly, t] = val
+
+            # ── 2. Paged Buffers ──
+            key_value_ptrs: Union[list[torch.Tensor], torch.Tensor]
+            if is_mla:
+                # MLA delegates to multi_layer_kv_transfer
+                # ptrs: [layer0, layer1, ...], each -> [page_buffer_size, head_size]
+                page_buffers = []
+                for ly in range(num_layers):
+                    pb = torch.zeros(
+                        (page_buffer_size, head_size),
+                        dtype=dtype,
+                        device=device,
+                    )
+                    if direction:  # Paged → LMC
+                        for s in range(page_buffer_size):
+                            val = (
+                                ly * 2000
+                                + s * 10
+                                + torch.arange(head_size, device=device)
+                            ).to(dtype)
+                            pb[s] = val
+                    page_buffers.append(pb)
+
+                if use_tensor_list:
+                    key_value_ptrs = page_buffers
+                else:
+                    key_value_ptrs = torch.tensor(
+                        [pb.data_ptr() for pb in page_buffers],
+                        dtype=torch.uint64,
+                        device=device,
+                    )
+            else:
+                # Non-MLA unilateral: separate K/V buffers
+                # ptrs: [K_l0, K_l1, ..., V_l0, V_l1, ...]
+                # each -> [page_buffer_size, head_size]
+                buffers = {}
+                for kv in range(2):
+                    for ly in range(num_layers):
+                        pb = torch.zeros(
+                            (page_buffer_size, head_size),
+                            dtype=dtype,
+                            device=device,
+                        )
+                        if direction:  # Paged → LMC
+                            for s in range(page_buffer_size):
+                                val = (
+                                    kv * 7000
+                                    + ly * 2000
+                                    + s * 10
+                                    + torch.arange(head_size, device=device)
+                                ).to(dtype)
+                                pb[s] = val
+                        buffers[(kv, ly)] = pb
+
+                if use_tensor_list:
+                    # Tensor list mode: [K_l0, K_l1, ..., V_l0, V_l1, ...]
+                    tensor_list = []
+                    for ly in range(num_layers):
+                        tensor_list.append(buffers[(0, ly)])
+                    for ly in range(num_layers):
+                        tensor_list.append(buffers[(1, ly)])
+                    key_value_ptrs = tensor_list
+                else:
+                    # Pointer mode
+                    ptr_list = []
+                    for ly in range(num_layers):
+                        ptr_list.append(buffers[(0, ly)].data_ptr())
+                    for ly in range(num_layers):
+                        ptr_list.append(buffers[(1, ly)].data_ptr())
+
+                    key_value_ptrs = torch.tensor(
+                        ptr_list,
+                        dtype=torch.uint64,
+                        device=device,
+                    ).contiguous()
+
+            # ── 3. Execute ──
+            xfer_dir = (
+                ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D
+            )
+            ops.multi_layer_kv_transfer_unilateral(
+                lmc_tensor,
+                key_value_ptrs,
+                slot_mapping,
+                torch.device(device),
+                page_buffer_size,
+                xfer_dir,
+                engine_kv_format,
+            )
+            device_sync(device)
+
+            # ── 4. Verify ──
+            for t_id in range(num_tokens):
+                s_idx = int(slot_mapping[t_id].item())
+                for ly in range(num_layers):
+                    for kv in range(k_or_v_size):
+                        lmc_val = lmc_tensor[kv, ly, t_id]
+
+                        if is_mla:
+                            paged_val = page_buffers[ly][s_idx]
+                        else:
+                            paged_val = buffers[(kv, ly)][s_idx]
+
+                        torch.testing.assert_close(
+                            lmc_val.to("cpu"),
+                            paged_val.to("cpu"),
+                            msg=(
+                                f"Mismatch: {engine_kv_format} {dir_tag} "
+                                f"(tensor_list={use_tensor_list}), "
+                                f"KV={kv}, layer={ly}, "
+                                f"token={t_id}, slot={s_idx}"
+                            ),
+                        )
+
+    # ── 5. Collect canonical result for cross-backend comparison ──
+    # Use non-MLA unilateral (the primary use case of this function)
+    results: dict[str, torch.Tensor] = {}
+    for direction in [True, False]:
+        dir_tag = "p2l" if direction else "l2p"
+
+        lmc_shape = (2, num_layers, num_tokens, head_size)
+        lmc_tensor = torch.zeros(lmc_shape, dtype=dtype, device=device)
+
+        if not direction:
+            for kv in range(2):
+                for ly in range(num_layers):
+                    for t in range(num_tokens):
+                        val = (
+                            kv * 5000
+                            + ly * 1000
+                            + t * 10
+                            + torch.arange(head_size, device=device)
+                        ).to(dtype)
+                        lmc_tensor[kv, ly, t] = val
+
+        buffers = {}
+        for kv in range(2):
+            for ly in range(num_layers):
+                pb = torch.zeros(
+                    (page_buffer_size, head_size),
+                    dtype=dtype,
+                    device=device,
+                )
+                if direction:
+                    for s in range(page_buffer_size):
+                        val = (
+                            kv * 7000
+                            + ly * 2000
+                            + s * 10
+                            + torch.arange(head_size, device=device)
+                        ).to(dtype)
+                        pb[s] = val
+                buffers[(kv, ly)] = pb
+
+        key_value_ptrs: Union[list[torch.Tensor], torch.Tensor]  # type: ignore[no-redef]
+        if use_tensor_list:
+            # Tensor list mode: [K_l0, K_l1, ..., V_l0, V_l1, ...]
+            tensor_list = []
+            for ly in range(num_layers):
+                tensor_list.append(buffers[(0, ly)])
+            for ly in range(num_layers):
+                tensor_list.append(buffers[(1, ly)])
+            key_value_ptrs = tensor_list
+        else:
+            ptr_list = []
+            for ly in range(num_layers):
+                ptr_list.append(buffers[(0, ly)].data_ptr())
+            for ly in range(num_layers):
+                ptr_list.append(buffers[(1, ly)].data_ptr())
+            key_value_ptrs = torch.tensor(
+                ptr_list,
+                dtype=torch.uint64,
+                device=device,
+            ).contiguous()
+
+        xfer_dir = ops.TransferDirection.D2H if direction else ops.TransferDirection.H2D
+        ops.multi_layer_kv_transfer_unilateral(
+            lmc_tensor,
+            key_value_ptrs,
+            slot_mapping,
+            torch.device(device),
+            page_buffer_size,
+            xfer_dir,
+            ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        )
+        device_sync(device)
+
+        results[f"multi_layer_kv_transfer_unilateral_{dir_tag}"] = lmc_tensor.cpu()
+
+    return results
+
+
+def scenario_alloc_free_pinned_ptr(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test alloc_pinned_ptr and free_pinned_ptr round-trip."""
+    alloc_size = 4096
+    flags = 0  # cudaHostAllocDefault
+
+    # 1. Allocate
+    ptr = ops.alloc_pinned_ptr(alloc_size, flags)
+    assert isinstance(ptr, int), f"Expected int, got {type(ptr)}"
+    assert ptr != 0, "alloc_pinned_ptr returned null"
+
+    # 2. Free
+    ops.free_pinned_ptr(ptr)
+
+    return {"alloc_free_pinned_ptr": torch.tensor([1], dtype=torch.int32)}
+
+
+def scenario_alloc_free_numa_ptr(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test alloc_numa_ptr and free_numa_ptr round-trip."""
+    alloc_size = 4096
+    node = 0  # NUMA node 0 (always exists)
+
+    # 1. Allocate
+    ptr = ops.alloc_numa_ptr(alloc_size, node)
+    assert isinstance(ptr, int), f"Expected int, got {type(ptr)}"
+    assert ptr != 0, "alloc_numa_ptr returned null"
+
+    # 2. Free (must pass same size as alloc)
+    ops.free_numa_ptr(ptr, alloc_size)
+
+    return {"alloc_free_numa_ptr": torch.tensor([1], dtype=torch.int32)}
+
+
+def scenario_alloc_free_pinned_numa_ptr(
+    ops: Any, device: str
+) -> dict[str, torch.Tensor]:
+    """Test alloc_pinned_numa_ptr and free_pinned_numa_ptr round-trip."""
+    alloc_size = 4096
+    node = 0  # NUMA node 0
+
+    # 1. Allocate (NUMA + cudaHostRegister)
+    ptr = ops.alloc_pinned_numa_ptr(alloc_size, node)
+    assert isinstance(ptr, int), f"Expected int, got {type(ptr)}"
+    assert ptr != 0, "alloc_pinned_numa_ptr returned null"
+
+    # 2. Free (cudaHostUnregister + munmap)
+    ops.free_pinned_numa_ptr(ptr, alloc_size)
+
+    return {"alloc_free_pinned_numa_ptr": torch.tensor([1], dtype=torch.int32)}
+
+
+def scenario_alloc_free_shm_pinned_ptr(
+    ops: Any, device: str
+) -> dict[str, torch.Tensor]:
+    """Test alloc_shm_pinned_ptr and free_shm_pinned_ptr round-trip."""
+    alloc_size = 4096
+    shm_name = "/test_lmcache_shm"
+
+    # 1. Allocate
+    ptr = ops.alloc_shm_pinned_ptr(alloc_size, shm_name)
+    assert isinstance(ptr, int), f"Expected int, got {type(ptr)}"
+    assert ptr != 0, "alloc_shm_pinned_ptr returned null"
+
+    # 2. Free
+    ops.free_shm_pinned_ptr(ptr, alloc_size, shm_name)
+
+    return {"alloc_free_shm_pinned_ptr": torch.tensor([1], dtype=torch.int32)}
+
+
+def scenario_transfer_direction_enum(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test TransferDirection enum has distinct H2D and D2H members."""
+    # 1. Verify enum members exist
+    td = ops.TransferDirection
+    assert hasattr(td, "H2D"), "Missing TransferDirection.H2D"
+    assert hasattr(td, "D2H"), "Missing TransferDirection.D2H"
+
+    # 2. Verify values are distinct
+    assert td.H2D != td.D2H, "H2D and D2H should be distinct"
+
+    # 3. Extract int value (compatible with both
+    #    pybind11 enum and Python enum)
+    h2d = td.H2D
+    d2h = td.D2H
+    h2d_val = h2d.value if hasattr(h2d, "value") else int(h2d)
+    d2h_val = d2h.value if hasattr(d2h, "value") else int(d2h)
+
+    return {
+        "transfer_direction_enum": torch.tensor(
+            [h2d_val, d2h_val],
+            dtype=torch.int32,
+        )
+    }
+
+
+def scenario_record_drain_completion(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test record_completion_on_stream / drain_recorded_completions contracts.
+
+    Verified backend-agnostic: native c_ops uses cudaLaunchHostFunc on the
+    default stream (ptr=0), which fires synchronously after device_sync; the
+    fallback enqueues immediately. Both paths satisfy every assertion below.
+    """
+    ops.drain_recorded_completions()  # clear residual global state
+
+    assert ops.drain_recorded_completions() == []
+
+    ops.record_completion_on_stream(0, "kind-a", b"payload-a")
+    ops.record_completion_on_stream(0, "kind-b", b"payload-b")
+    device_sync(device)
+    result = ops.drain_recorded_completions()
+    assert result == [("kind-a", b"payload-a"), ("kind-b", b"payload-b")]
+    assert all(isinstance(k, str) and isinstance(p, bytes) for k, p in result)
+
+    assert ops.drain_recorded_completions() == []
+
+    # Multiple records on the default stream (ptr=0) must all enqueue.
+    # Note: ptr=0 is the only value safe on both backends — the fallback
+    # ignores the field, but the native path casts it to cudaStream_t, so
+    # arbitrary values like -1 / 2**32 would be invalid there.
+    for _ in range(3):
+        ops.record_completion_on_stream(0, "k", b"v")
+    device_sync(device)
+    assert len(ops.drain_recorded_completions()) == 3
+
+    return {"record_drain_completion": torch.tensor([1], dtype=torch.int32)}
+
+
+def scenario_dispatcher_integration(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test submit_callback_to_stream -> DeviceHostFuncDispatcher -> handler.
+
+    Works on all backends: submit_callback_to_stream only reads stream.ptr, so
+    _FakeStream(ptr=0) is accepted; the native path routes through the CUDA
+    default stream which fires before the dispatcher's drain loop polls.
+    """
+    # First Party
+    import lmcache.v1.multiprocess.native_completion as nc
+
+    original = nc._lmc_ops
+    nc._lmc_ops = ops
+    try:
+        ops.drain_recorded_completions()
+
+        class _FakeStream:
+            ptr: int = 0
+
+        dispatcher = DeviceHostFuncDispatcher(drain_interval_seconds=0.001)
+        received: list[list[bytes]] = []
+        dispatcher.register("finish_write", received.append, payload_type=list[bytes])
+        dispatcher.start()
+        try:
+            submit_callback_to_stream(_FakeStream(), "finish_write", [b"k0", b"k1"])
+            deadline = time.monotonic() + 5.0
+            while time.monotonic() < deadline and not received:
+                time.sleep(0.01)
+        finally:
+            dispatcher.stop()
+
+        assert received == [[b"k0", b"k1"]]
+    finally:
+        nc._lmc_ops = original
+
+    return {"dispatcher_integration": torch.tensor([1], dtype=torch.int32)}
+
+
+def scenario_multi_layer_block_kv_transfer(
+    ops: Any, device: str
+) -> dict[str, torch.Tensor]:
+    """Test multi_layer_block_kv_transfer across all GPU KV formats.
+
+    Exercises the block-based transfer path for:
+    - NHD per-layer format (D2H and H2D round-trip)
+    - FlashInfer NHD per-layer format (interleaved K/V)
+    - HND per-layer format (with permute)
+    - FlashInfer HND per-layer format (interleaved K/V)
+    - MLA per-layer format (no K/V split)
+    - SGLang MLA flat per-layer format
+    - Cross-layer NHD (single tensor [NB, NL, 2, BS, NH, HS])
+    - Cross-layer HND (single tensor [NB, NL, 2, NH, BS, HS])
+    - SGLang MHA flat (2*NL tensors [NB*BS, NH, HS])
+    - SGLang MHA block (2*NL tensors [NB, BS, NH, HS])
+    - non-sequential block_ids and list[int] block_ids input
+    - skip_prefix_n_blocks > 0
+    - num_blocks > blocks_per_chunk (multi-chunk)
+    """
+    results = {}
+
+    # C++ bindings (cuda_c_ops, xpu_sycl_ops) expect uint64 pointer tensors for
+    # paged_buffer_ptrs_tensor and list[int] for lmcache_objects_ptrs.
+    # The Python fallback also supports both modes on cpu/cuda (pointer inputs
+    # are reconstructed internally via _tensor_from_ptr).
+    use_tensor_list = device not in ("cpu", "cuda")
+
+    def _alloc_chunks(shape: tuple[int, ...], count: int) -> list[torch.Tensor]:
+        chunks = [torch.zeros(shape, dtype=dtype) for _ in range(count)]
+        if device in ("cuda"):
+            chunks = [chunk.pin_memory() for chunk in chunks]
+        return chunks
+
+    # --- NHD per-layer ---
+    torch.manual_seed(123)
+    num_layers, num_blocks, block_size = 2, 8, 4
+    num_heads, head_size = 2, 8
+    blocks_per_chunk = 4
+    chunk_tokens = blocks_per_chunk * block_size
+    hidden_dim = num_heads * head_size
+    dtype = torch.float32
+
+    paged_layers = [
+        torch.randn(2, num_blocks, block_size, num_heads, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    shape_desc = ops.PageBufferShapeDesc()
+    shape_desc.nl = num_layers
+    shape_desc.nb = num_blocks
+    shape_desc.bs = block_size
+    shape_desc.nh = num_heads
+    shape_desc.hs = head_size
+    shape_desc.element_size = dtype.itemsize
+    shape_desc.kv_size = 2
+    engine_kv_format = ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    num_chunks = num_blocks // blocks_per_chunk
+    d2h_chunks = _alloc_chunks((2, num_layers, chunk_tokens, hidden_dim), num_chunks)
+    block_ids = list(range(num_blocks))
+
+    ops.multi_layer_block_kv_transfer(
+        paged_layers
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks if use_tensor_list else [c.data_ptr() for c in d2h_chunks],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format,
+        0,
+    )
+    paged_h2d = [torch.zeros_like(layer) for layer in paged_layers]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d], dtype=torch.uint64, device=device
+        ),
+        d2h_chunks if use_tensor_list else [c.data_ptr() for c in d2h_chunks],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers[i].cpu()
+        recon = paged_h2d[i].cpu()
+        results[f"nhd_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"NHD Layer {i} round-trip mismatch"
+        )
+
+    # --- FlashInfer NHD per-layer ---
+    torch.manual_seed(234)
+    paged_layers_fi_nhd = [
+        torch.randn(num_blocks, 2, block_size, num_heads, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    engine_kv_format_fi_nhd = ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS
+    d2h_chunks_fi_nhd = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_fi_nhd
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_fi_nhd],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_fi_nhd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_fi_nhd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_fi_nhd,
+        0,
+    )
+    paged_h2d_fi_nhd = [torch.zeros_like(layer) for layer in paged_layers_fi_nhd]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_fi_nhd
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_fi_nhd],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_fi_nhd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_fi_nhd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_fi_nhd,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_fi_nhd[i].cpu()
+        recon = paged_h2d_fi_nhd[i].cpu()
+        results[f"flashinfer_nhd_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"FlashInfer NHD Layer {i} round-trip mismatch"
+        )
+
+    # --- HND per-layer ---
+    torch.manual_seed(456)
+    paged_layers_hnd = [
+        torch.randn(2, num_blocks, num_heads, block_size, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    engine_kv_format_hnd = ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS
+    d2h_chunks_hnd = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_hnd
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_hnd],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_hnd if use_tensor_list else [c.data_ptr() for c in d2h_chunks_hnd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_hnd,
+        0,
+    )
+    paged_h2d_hnd = [torch.zeros_like(layer) for layer in paged_layers_hnd]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_hnd
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_hnd],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_hnd if use_tensor_list else [c.data_ptr() for c in d2h_chunks_hnd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_hnd,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_hnd[i].cpu()
+        recon = paged_h2d_hnd[i].cpu()
+        results[f"hnd_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"HND Layer {i} round-trip mismatch"
+        )
+
+    # --- FlashInfer HND per-layer ---
+    torch.manual_seed(567)
+    paged_layers_fi_hnd = [
+        torch.randn(num_blocks, 2, num_heads, block_size, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    engine_kv_format_fi_hnd = ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS
+    d2h_chunks_fi_hnd = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_fi_hnd
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_fi_hnd],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_fi_hnd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_fi_hnd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_fi_hnd,
+        0,
+    )
+    paged_h2d_fi_hnd = [torch.zeros_like(layer) for layer in paged_layers_fi_hnd]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_fi_hnd
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_fi_hnd],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_fi_hnd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_fi_hnd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_fi_hnd,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_fi_hnd[i].cpu()
+        recon = paged_h2d_fi_hnd[i].cpu()
+        results[f"flashinfer_hnd_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"FlashInfer HND Layer {i} round-trip mismatch"
+        )
+
+    # --- MLA per-layer ---
+    torch.manual_seed(789)
+    mla_hidden = 16
+    paged_layers_mla = [
+        torch.randn(num_blocks, block_size, mla_hidden, dtype=dtype).to(device)
+        for _ in range(num_layers)
+    ]
+    shape_desc_mla = ops.PageBufferShapeDesc()
+    shape_desc_mla.nl = num_layers
+    shape_desc_mla.nb = num_blocks
+    shape_desc_mla.bs = block_size
+    shape_desc_mla.nh = 1
+    shape_desc_mla.hs = mla_hidden
+    shape_desc_mla.element_size = dtype.itemsize
+    shape_desc_mla.kv_size = 1
+    engine_kv_format_mla = ops.EngineKVFormat.NL_X_NB_BS_HS
+    d2h_chunks_mla = _alloc_chunks((num_layers, chunk_tokens, mla_hidden), num_chunks)
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_mla
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_mla],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_mla if use_tensor_list else [c.data_ptr() for c in d2h_chunks_mla],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc_mla,
+        chunk_tokens,
+        engine_kv_format_mla,
+        0,
+    )
+    paged_h2d_mla = [torch.zeros_like(layer) for layer in paged_layers_mla]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_mla
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_mla],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_mla if use_tensor_list else [c.data_ptr() for c in d2h_chunks_mla],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc_mla,
+        chunk_tokens,
+        engine_kv_format_mla,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_mla[i].cpu()
+        recon = paged_h2d_mla[i].cpu()
+        results[f"mla_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"MLA Layer {i} round-trip mismatch"
+        )
+
+    # --- SGLang MLA flat per-layer ---
+    torch.manual_seed(890)
+    paged_layers_sglang_mla = [
+        torch.randn(num_blocks * block_size, 1, mla_hidden, dtype=dtype).to(device)
+        for _ in range(num_layers)
+    ]
+    engine_kv_format_sglang_mla = ops.EngineKVFormat.NL_X_NBBS_ONE_HS
+    d2h_chunks_sglang_mla = _alloc_chunks(
+        (num_layers, chunk_tokens, mla_hidden), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_sglang_mla
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_sglang_mla],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_sglang_mla
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_sglang_mla],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc_mla,
+        chunk_tokens,
+        engine_kv_format_sglang_mla,
+        0,
+    )
+    paged_h2d_sglang_mla = [
+        torch.zeros_like(layer) for layer in paged_layers_sglang_mla
+    ]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_sglang_mla
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_sglang_mla],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_sglang_mla
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_sglang_mla],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc_mla,
+        chunk_tokens,
+        engine_kv_format_sglang_mla,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_sglang_mla[i].cpu()
+        recon = paged_h2d_sglang_mla[i].cpu()
+        results[f"sglang_mla_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"SGLang MLA Layer {i} round-trip mismatch"
+        )
+
+    # --- Cross-layer NHD ---
+    torch.manual_seed(101)
+    paged_cross_nhd = torch.randn(
+        num_blocks,
+        num_layers,
+        2,
+        block_size,
+        num_heads,
+        head_size,
+        dtype=dtype,
+    ).to(device)
+    engine_kv_format_cross_nhd = ops.EngineKVFormat.NB_NL_TWO_BS_NH_HS
+    d2h_chunks_cross_nhd = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_cross_nhd
+        if use_tensor_list
+        else torch.tensor(
+            [paged_cross_nhd.data_ptr()], dtype=torch.uint64, device=device
+        ),
+        d2h_chunks_cross_nhd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_cross_nhd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_cross_nhd,
+        0,
+    )
+    paged_h2d_cross_nhd = torch.zeros_like(paged_cross_nhd)
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_cross_nhd
+        if use_tensor_list
+        else torch.tensor(
+            [paged_h2d_cross_nhd.data_ptr()], dtype=torch.uint64, device=device
+        ),
+        d2h_chunks_cross_nhd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_cross_nhd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_cross_nhd,
+        0,
+    )
+    orig = paged_cross_nhd.cpu()
+    recon = paged_h2d_cross_nhd.cpu()
+    results["cross_nhd"] = torch.stack([orig, recon])
+    assert torch.allclose(orig, recon, atol=1e-6), "Cross-layer NHD mismatch"
+
+    # --- Cross-layer HND ---
+    torch.manual_seed(202)
+    paged_cross_hnd = torch.randn(
+        num_blocks,
+        num_layers,
+        2,
+        num_heads,
+        block_size,
+        head_size,
+        dtype=dtype,
+    ).to(device)
+    engine_kv_format_cross_hnd = ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS
+    d2h_chunks_cross_hnd = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_cross_hnd
+        if use_tensor_list
+        else torch.tensor(
+            [paged_cross_hnd.data_ptr()], dtype=torch.uint64, device=device
+        ),
+        d2h_chunks_cross_hnd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_cross_hnd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_cross_hnd,
+        0,
+    )
+    paged_h2d_cross_hnd = torch.zeros_like(paged_cross_hnd)
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_cross_hnd
+        if use_tensor_list
+        else torch.tensor(
+            [paged_h2d_cross_hnd.data_ptr()], dtype=torch.uint64, device=device
+        ),
+        d2h_chunks_cross_hnd
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_cross_hnd],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_cross_hnd,
+        0,
+    )
+    orig = paged_cross_hnd.cpu()
+    recon = paged_h2d_cross_hnd.cpu()
+    results["cross_hnd"] = torch.stack([orig, recon])
+    assert torch.allclose(orig, recon, atol=1e-6), "Cross-layer HND mismatch"
+
+    # --- SGLang MHA flat (NBBS) ---
+    torch.manual_seed(303)
+    pbs = num_blocks * block_size
+    paged_sglang_nbbs = [
+        [
+            torch.randn(pbs, num_heads, head_size, dtype=dtype).to(device)
+            for _ in range(num_layers)
+        ],
+        [
+            torch.randn(pbs, num_heads, head_size, dtype=dtype).to(device)
+            for _ in range(num_layers)
+        ],
+    ]
+    engine_kv_format_sglang_nbbs = ops.EngineKVFormat.TWO_X_NL_X_NBBS_NH_HS
+    d2h_chunks_sglang_nbbs = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_sglang_nbbs
+        if use_tensor_list
+        else torch.tensor(
+            [t.data_ptr() for t in paged_sglang_nbbs[0]]
+            + [t.data_ptr() for t in paged_sglang_nbbs[1]],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_sglang_nbbs
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_sglang_nbbs],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_sglang_nbbs,
+        0,
+    )
+    paged_h2d_sglang_nbbs = [
+        [torch.zeros_like(t) for t in group] for group in paged_sglang_nbbs
+    ]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_sglang_nbbs
+        if use_tensor_list
+        else torch.tensor(
+            [t.data_ptr() for t in paged_h2d_sglang_nbbs[0]]
+            + [t.data_ptr() for t in paged_h2d_sglang_nbbs[1]],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_sglang_nbbs
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_sglang_nbbs],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_sglang_nbbs,
+        0,
+    )
+    for kv in range(2):
+        for i in range(num_layers):
+            orig = paged_sglang_nbbs[kv][i].cpu()
+            recon = paged_h2d_sglang_nbbs[kv][i].cpu()
+            results[f"sglang_nbbs_kv{kv}_l{i}"] = torch.stack([orig, recon])
+            assert torch.allclose(orig, recon, atol=1e-6), (
+                f"SGLang NBBS kv={kv} layer={i} mismatch"
+            )
+
+    # --- SGLang MHA block (NB_BS) ---
+    torch.manual_seed(404)
+    paged_sglang_nb = [
+        [
+            torch.randn(num_blocks, block_size, num_heads, head_size, dtype=dtype).to(
+                device
+            )
+            for _ in range(num_layers)
+        ],
+        [
+            torch.randn(num_blocks, block_size, num_heads, head_size, dtype=dtype).to(
+                device
+            )
+            for _ in range(num_layers)
+        ],
+    ]
+    engine_kv_format_sglang_nb = ops.EngineKVFormat.TWO_X_NL_X_NB_BS_NH_HS
+    d2h_chunks_sglang_nb = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_sglang_nb
+        if use_tensor_list
+        else torch.tensor(
+            [t.data_ptr() for t in paged_sglang_nb[0]]
+            + [t.data_ptr() for t in paged_sglang_nb[1]],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_sglang_nb
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_sglang_nb],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_sglang_nb,
+        0,
+    )
+    paged_h2d_sglang_nb = [
+        [torch.zeros_like(t) for t in group] for group in paged_sglang_nb
+    ]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_sglang_nb
+        if use_tensor_list
+        else torch.tensor(
+            [t.data_ptr() for t in paged_h2d_sglang_nb[0]]
+            + [t.data_ptr() for t in paged_h2d_sglang_nb[1]],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_sglang_nb
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_sglang_nb],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_sglang_nb,
+        0,
+    )
+    for kv in range(2):
+        for i in range(num_layers):
+            orig = paged_sglang_nb[kv][i].cpu()
+            recon = paged_h2d_sglang_nb[kv][i].cpu()
+            results[f"sglang_nb_kv{kv}_l{i}"] = torch.stack([orig, recon])
+            assert torch.allclose(orig, recon, atol=1e-6), (
+                f"SGLang NB kv={kv} layer={i} mismatch"
+            )
+
+    # --- skip_prefix_n_blocks > 0 ---
+    torch.manual_seed(505)
+    skip_n = 2
+    paged_layers_skip = [
+        torch.randn(2, num_blocks, block_size, num_heads, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    engine_kv_format_nhd = ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS
+    # With skip=2, effective blocks start at index 2.
+    # Object 0 occupies flat indices [0, blocks_per_chunk), skipping first 2.
+    # Object 1 occupies flat indices [blocks_per_chunk, 2*blocks_per_chunk).
+    d2h_chunks_skip = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_skip
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_skip],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_skip if use_tensor_list else [c.data_ptr() for c in d2h_chunks_skip],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_nhd,
+        skip_n,
+    )
+    paged_h2d_skip = [torch.zeros_like(layer) for layer in paged_layers_skip]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_skip
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_skip],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_skip if use_tensor_list else [c.data_ptr() for c in d2h_chunks_skip],
+        torch.tensor(block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_nhd,
+        skip_n,
+    )
+    # Blocks [skip_n:num_blocks] should round-trip at their original positions
+    for layer_idx in range(num_layers):
+        for kv in range(2):
+            orig_blocks = paged_layers_skip[layer_idx][kv, skip_n:num_blocks]
+            recon_blocks = paged_h2d_skip[layer_idx][kv, skip_n:num_blocks]
+            key = f"skip_l{layer_idx}_kv{kv}"
+            results[key] = torch.stack([orig_blocks.cpu(), recon_blocks.cpu()])
+            assert torch.allclose(orig_blocks, recon_blocks, atol=1e-6), (
+                f"Skip mismatch at layer={layer_idx} kv={kv}"
+            )
+    # Skipped blocks [0:skip_n] should remain zero
+    for layer_idx in range(num_layers):
+        for kv in range(2):
+            skipped = paged_h2d_skip[layer_idx][kv, :skip_n]
+            assert torch.all(skipped == 0), (
+                f"Skipped blocks not zero at layer={layer_idx} kv={kv}"
+            )
+    assert torch.all(d2h_chunks_skip[0][:, :, : skip_n * block_size] == 0), (
+        "Skipped D2H chunk region should remain zero"
+    )
+
+    # --- Non-sequential block_ids ---
+    torch.manual_seed(515)
+    paged_layers_permuted = [
+        torch.randn(2, num_blocks, block_size, num_heads, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    generator = torch.Generator(device="cpu").manual_seed(616)
+    permuted_block_ids = torch.randperm(num_blocks, generator=generator).tolist()
+    d2h_chunks_permuted = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks
+    )
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_permuted
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_permuted],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_permuted
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_permuted],
+        torch.tensor(permuted_block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_nhd,
+        0,
+    )
+    paged_h2d_permuted = [torch.zeros_like(layer) for layer in paged_layers_permuted]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_permuted
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_permuted],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_permuted
+        if use_tensor_list
+        else [c.data_ptr() for c in d2h_chunks_permuted],
+        torch.tensor(permuted_block_ids, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc,
+        chunk_tokens,
+        engine_kv_format_nhd,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_permuted[i].cpu()
+        recon = paged_h2d_permuted[i].cpu()
+        results[f"permuted_nhd_layer{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"Permuted NHD Layer {i} round-trip mismatch"
+        )
+
+    # --- Multi-chunk (num_blocks > blocks_per_chunk) ---
+    torch.manual_seed(606)
+    num_blocks_mc = 12
+    paged_layers_mc = [
+        torch.randn(2, num_blocks_mc, block_size, num_heads, head_size, dtype=dtype).to(
+            device
+        )
+        for _ in range(num_layers)
+    ]
+    shape_desc_mc = ops.PageBufferShapeDesc()
+    shape_desc_mc.nl = num_layers
+    shape_desc_mc.nb = num_blocks_mc
+    shape_desc_mc.bs = block_size
+    shape_desc_mc.nh = num_heads
+    shape_desc_mc.hs = head_size
+    shape_desc_mc.element_size = dtype.itemsize
+    shape_desc_mc.kv_size = 2
+    num_chunks_mc = num_blocks_mc // blocks_per_chunk  # 3 chunks
+    d2h_chunks_mc = _alloc_chunks(
+        (2, num_layers, chunk_tokens, hidden_dim), num_chunks_mc
+    )
+    block_ids_mc = list(range(num_blocks_mc))
+    ops.multi_layer_block_kv_transfer(
+        paged_layers_mc
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_layers_mc],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_mc if use_tensor_list else [c.data_ptr() for c in d2h_chunks_mc],
+        torch.tensor(block_ids_mc, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.D2H,
+        shape_desc_mc,
+        chunk_tokens,
+        engine_kv_format_nhd,
+        0,
+    )
+    paged_h2d_mc = [torch.zeros_like(layer) for layer in paged_layers_mc]
+    ops.multi_layer_block_kv_transfer(
+        paged_h2d_mc
+        if use_tensor_list
+        else torch.tensor(
+            [layer.data_ptr() for layer in paged_h2d_mc],
+            dtype=torch.uint64,
+            device=device,
+        ),
+        d2h_chunks_mc if use_tensor_list else [c.data_ptr() for c in d2h_chunks_mc],
+        torch.tensor(block_ids_mc, dtype=torch.int64, device=device),
+        torch.device(device),
+        ops.TransferDirection.H2D,
+        shape_desc_mc,
+        chunk_tokens,
+        engine_kv_format_nhd,
+        0,
+    )
+    for i in range(num_layers):
+        orig = paged_layers_mc[i].cpu()
+        recon = paged_h2d_mc[i].cpu()
+        results[f"multi_chunk_l{i}"] = torch.stack([orig, recon])
+        assert torch.allclose(orig, recon, atol=1e-6), (
+            f"Multi-chunk Layer {i} round-trip mismatch"
+        )
+
+    return results
+
+
+def scenario_record_drain_event(ops: Any, device: str) -> dict[str, torch.Tensor]:
+    """Test record_event_on_stream / drain_recorded_events contracts.
+
+    Verified backend-agnostic: native c_ops uses cudaLaunchHostFunc on the
+    default stream (ptr=0), which fires synchronously after device_sync; the
+    fallback enqueues immediately with time.time(). Both paths satisfy every
+    assertion below.
+    """
+    ops.drain_recorded_events()  # clear residual global state
+
+    assert ops.drain_recorded_events() == []
+
+    ops.record_event_on_stream(
+        0, "mp.store.start", "sess-1", {"device": "cuda:0"}, {"count": 10}
+    )
+    ops.record_event_on_stream(
+        0, "mp.store.end", "sess-1", {"device": "cuda:0"}, {"count": 10}
+    )
+    device_sync(device)
+    result = ops.drain_recorded_events()
+    assert len(result) == 2
+
+    # Each element is (event_type_name, session_id, timestamp, str_meta, int_meta)
+    name0, sid0, ts0, str_meta0, int_meta0 = result[0]
+    name1, sid1, ts1, str_meta1, int_meta1 = result[1]
+
+    assert name0 == "mp.store.start"
+    assert name1 == "mp.store.end"
+    assert sid0 == "sess-1"
+    assert sid1 == "sess-1"
+    assert ts0 > 0.0
+    assert ts1 >= ts0  # timestamps must be monotonically non-decreasing
+    assert str_meta0 == {"device": "cuda:0"}
+    assert int_meta0 == {"count": 10}
+    assert str_meta1 == {"device": "cuda:0"}
+    assert int_meta1 == {"count": 10}
+
+    # Drain clears the buffer
+    assert ops.drain_recorded_events() == []
+
+    # Multiple records on the default stream (ptr=0) must all enqueue.
+    for i in range(5):
+        ops.record_event_on_stream(0, f"mp.test.{i}", f"sess-{i}", {}, {"idx": i})
+    device_sync(device)
+    events = ops.drain_recorded_events()
+    assert len(events) == 5
+    for i, (name, sid, ts, str_meta, int_meta) in enumerate(events):
+        assert name == f"mp.test.{i}"
+        assert sid == f"sess-{i}"
+        assert int_meta == {"idx": i}
+        assert ts > 0.0
+
+    return {"record_drain_event": torch.tensor([1], dtype=torch.int32)}
+
+
+# ==========================================
+# 3. Registry
+# ==========================================
+
+# cover pybind list in csrc/pybind.cpp
+SCENARIO_REGISTRY = {
+    "transfer_direction_enum": scenario_transfer_direction_enum,
+    "multi_layer_kv_transfer": scenario_multi_layer_kv_transfer,
+    "multi_layer_kv_transfer_unilateral": scenario_multi_layer_kv_transfer_unilateral,
+    "multi_layer_block_kv_transfer": scenario_multi_layer_block_kv_transfer,
+    "single_layer_kv_transfer": scenario_single_layer_kv_transfer,
+    "single_layer_kv_transfer_sgl": scenario_single_layer_kv_transfer_sgl,
+    "load_and_reshape_flash": scenario_load_and_reshape_flash,
+    "reshape_and_cache_back_flash": scenario_reshape_and_cache_back_flash,
+    "lmcache_memcpy_async": scenario_lmcache_memcpy_async,
+    "encode_fast_new": scenario_encode_fast_new,
+    "decode_fast_new": scenario_decode_fast_new,
+    "decode_fast_prefsum": scenario_decode_fast_prefsum,
+    "calculate_cdf": scenario_calculate_cdf,
+    "rotary_embedding_k_fused": scenario_rotary_embedding_k_fused,
+    "alloc_free_pinned_ptr": scenario_alloc_free_pinned_ptr,
+    "alloc_free_pinned_numa_ptr": scenario_alloc_free_pinned_numa_ptr,
+    "alloc_free_numa_ptr": scenario_alloc_free_numa_ptr,
+    "alloc_free_shm_pinned_ptr": scenario_alloc_free_shm_pinned_ptr,
+    "get_gpu_pci_bus_id": scenario_get_gpu_pci_bus_id,
+    "record_drain_completion": scenario_record_drain_completion,
+    "dispatcher_integration": scenario_dispatcher_integration,
+    "record_drain_event": scenario_record_drain_event,
+}
+
+
+# ==========================================
+# 4. Test functions pytest sees
+# ==========================================
+
+
+class TestScenarios:
+    """Test class to ensure test_scenario runs before test_compare.
+
+    **Execution Order Guarantee:**
+    By grouping tests in a class and using alphabetically ordered method names
+    (test_1_scenario, test_2_compare), pytest will execute all scenario tests
+    before any compare tests, ensuring _results dict is fully populated.
+
+    """
+
+    @pytest.mark.parametrize("name,fn", list(SCENARIO_REGISTRY.items()))
+    def test_1_scenario(
+        self,
+        backend: tuple,
+        name: str,
+        fn: Any,
+    ) -> None:
+        """Run a single scenario with a specific backend configuration.
+
+        Each (scenario, backend) pair is a separate pytest test case, giving
+        per-scenario per-backend failure reporting without subprocess indirection.
+
+        Results are stored in the module-level _results dict for later comparison
+        by test_2_compare.
+        """
+        backend_id, ops, device = backend
+        result = fn(ops, device)
+        if result is not None:
+            _results[(name, backend_id)] = result
+
+    @pytest.mark.parametrize("name", list(SCENARIO_REGISTRY.keys()))
+    def test_2_compare(self, name: str) -> None:
+        """Compare results across backends for a single scenario.
+
+        When multiple backends ran (CUDA available), asserts that python
+        fallback equivalents produce numerically identical results to cuda_ops.
+        When only one backend ran (no CUDA), simply verifies results were stored.
+
+        This test runs after test_1_scenario due to alphabetical ordering of
+        method names within the TestScenarios class.
+        """
+        available = [p.values[0][0] for p in _BACKEND_PARAMS]  # list of backend_ids
+        backend_results = {
+            bid: _results[(name, bid)] for bid in available if (name, bid) in _results
+        }
+
+        assert len(backend_results) >= 1, (
+            f"{name}: no results collected — were all test_1_scenario tests skipped?"
+        )
+
+        if len(backend_results) < 2:
+            # Only one backend available (no CUDA); just verify results exist
+            return
+
+        # Collect all result keys across all backends for this scenario
+        all_keys: set[str] = set()
+        for res in backend_results.values():
+            all_keys.update(res.keys())
+
+        base_bid = next(iter(backend_results))  # first available backend as reference
+
+        for key in sorted(all_keys):
+            base_val = backend_results[base_bid].get(key)
+            if base_val is None:
+                continue
+
+            for bid, res in backend_results.items():
+                if bid == base_bid:
+                    continue
+                val = res.get(key)
+                if val is None:
+                    pytest.fail(
+                        f"{name}/{key}: backend '{bid}' has no result "
+                        f"(reference backend '{base_bid}' does)"
+                    )
+                    continue
+
+                if isinstance(val, torch.Tensor):
+                    v_current = val.detach().cpu().float()
+                    v_base = base_val.detach().cpu().float()
+                    if not torch.allclose(v_current, v_base, rtol=1e-4, atol=1e-4):
+                        max_diff = (v_current - v_base).abs().max().item()
+                        pytest.fail(
+                            f"{name}/{key}: '{bid}' vs '{base_bid}' mismatch, "
+                            f"max diff = {max_diff:.2e}"
+                        )
+                else:
+                    if val != base_val:
+                        pytest.fail(
+                            f"{name}/{key}: '{bid}'={val} != '{base_bid}'={base_val}"
+                        )
+
+
+# ==========================================
+# Allocation page alignment
+# ==========================================
+#
+# Rust raw-block backend with O_DIRECT requires page-aligned buffer
+# pointers; CUDA path gets this for free via cudaHostAlloc, and the
+# non-CUDA fallback in lmcache.non_cuda_equivalents shall mirror the same
+# guarantee.
+
+_PINNED_ALLOC_SIZES = [1, 4095, 4096, 8192, 1024 * 1024]
+
+
+@pytest.mark.parametrize("size", _PINNED_ALLOC_SIZES)
+def test_alloc_pinned_ptr_is_page_aligned(size: int) -> None:
+    page_size = os.sysconf("SC_PAGESIZE")
+    ptr = _py_ops.alloc_pinned_ptr(size)
+    try:
+        assert ptr != 0
+        if ptr % page_size != 0:
+            raise AssertionError(
+                f"alloc_pinned_ptr({size}) returned non-page-aligned ptr "
+                f"{hex(ptr)} (page size {page_size})"
+            )
+        # Touch every byte in the requested region through the raw pointer
+        # to confirm the registered view covers the full requested size
+        # (an undersized view would corrupt adjacent memory or segfault).
+        buf = (ctypes.c_uint8 * size).from_address(ptr)
+        for i in range(size):
+            buf[i] = (i & 0xFF) ^ 0xA5
+        for i in range(size):
+            assert buf[i] == ((i & 0xFF) ^ 0xA5)
+    finally:
+        _py_ops.free_pinned_ptr(ptr)
diff --git a/tests/v1/test_remote_metadata.py b/tests/v1/test_remote_metadata.py
new file mode 100644
index 0000000..843d515
--- /dev/null
+++ b/tests/v1/test_remote_metadata.py
@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: Apache-2.0
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.protocol import (
+    RemoteMetadata,
+    get_remote_metadata_bytes,
+    init_remote_metadata_info,
+    pad_shape_to_4d,
+    strip_shape_padding,
+)
+
+
+@pytest.mark.parametrize("num_groups", [1, 2, 3])
+def test_serialize_and_deserialize(num_groups):
+    all_shapes = [
+        torch.Size([1, 2, 3, 4]),
+        torch.Size([5, 6, 7, 8]),
+        torch.Size([9, 10, 11, 12]),
+    ]
+    all_dtypes = [torch.uint8, torch.float16, torch.float32]
+
+    shapes = all_shapes[:num_groups]
+    dtypes = all_dtypes[:num_groups]
+
+    # init remote metadata
+    init_remote_metadata_info(num_groups)
+
+    origin_metadata = RemoteMetadata(
+        100,
+        shapes,
+        dtypes,
+        MemoryFormat.KV_MLA_FMT,
+    )
+
+    meta_bytes = origin_metadata.serialize()
+    assert len(meta_bytes) == get_remote_metadata_bytes()
+    new_metadata = RemoteMetadata.deserialize(meta_bytes)
+    assert origin_metadata.length == new_metadata.length
+    assert origin_metadata.shapes == new_metadata.shapes
+    assert origin_metadata.dtypes == new_metadata.dtypes
+    assert origin_metadata.fmt == new_metadata.fmt
+
+
+def test_pad_shape_to_4d_already_4d():
+    shape = torch.Size([2, 4, 8, 16])
+    assert pad_shape_to_4d(shape) == [2, 4, 8, 16]
+
+
+def test_pad_shape_to_4d_1d():
+    shape = torch.Size([42])
+    assert pad_shape_to_4d(shape) == [42, 0, 0, 0]
+
+
+def test_pad_shape_to_4d_3d():
+    shape = torch.Size([1, 2, 3])
+    assert pad_shape_to_4d(shape) == [1, 2, 3, 0]
+
+
+def test_pad_shape_too_large():
+    with pytest.raises(AssertionError):
+        pad_shape_to_4d(torch.Size([1, 2, 3, 4, 5]))
+
+
+def test_strip_shape_padding_no_zeros():
+    assert strip_shape_padding([2, 4, 8, 16]) == torch.Size([2, 4, 8, 16])
+
+
+def test_strip_shape_padding_trailing_zeros():
+    assert strip_shape_padding([42, 0, 0, 0]) == torch.Size([42])
+
+
+def test_strip_shape_padding_preserves_one_dim():
+    assert strip_shape_padding([0, 0, 0, 0]) == torch.Size([0])
+
+
+# ---- Round-trip for sub-4D shapes in RemoteMetadata ----
+
+
+@pytest.mark.parametrize(
+    "shape",
+    [
+        torch.Size([128]),  # 1D (e.g. MLA)
+        torch.Size([4, 64]),  # 2D
+        torch.Size([2, 8, 128]),  # 3D
+        torch.Size([2, 4, 8, 128]),  # 4D (existing case)
+    ],
+)
+def test_remote_metadata_roundtrip_sub4d(shape):
+    init_remote_metadata_info(1)
+    original = RemoteMetadata(
+        100,
+        [shape],
+        [torch.float16],
+        MemoryFormat.KV_MLA_FMT,
+    )
+    restored = RemoteMetadata.deserialize(original.serialize())
+    assert restored.shapes[0] == shape
diff --git a/tests/v1/test_remote_mla_worker_id_as0.py b/tests/v1/test_remote_mla_worker_id_as0.py
new file mode 100644
index 0000000..7d8ccd0
--- /dev/null
+++ b/tests/v1/test_remote_mla_worker_id_as0.py
@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import List
+
+# Add import for mock
+from unittest import mock
+import asyncio
+import threading
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.metadata import LMCacheMetadata
+from lmcache.v1.storage_backend.connector import RemoteConnector
+from lmcache.v1.storage_backend.local_cpu_backend import LocalCPUBackend
+from lmcache.v1.storage_backend.remote_backend import RemoteBackend
+
+
+class MockConnector(RemoteConnector):
+    def __init__(self):
+        self.storage = {}
+
+    async def exists(self, key):
+        return key in self.storage
+
+    def exists_sync(self, key):
+        return key in self.storage
+
+    async def put(self, key, value):
+        self.storage[key] = value
+
+    async def get(self, key):
+        return self.storage.get(key)
+
+    async def close(self):
+        pass
+
+    async def list(self) -> List[str]:
+        return []
+
+
+# Mock the entire torch.cuda.Stream class
+@mock.patch("torch.cuda.Stream")
+def test_remote_mla_worker_id_as0(mock_stream):
+    # Create configuration
+    config = LMCacheEngineConfig(
+        chunk_size=256,
+        local_cpu=True,
+        max_local_cpu_size=5.0,
+        local_disk=None,
+        max_local_disk_size=0.0,
+        remote_url="lm://localhost:65432",
+        remote_serde="naive",
+        use_layerwise=False,
+        save_decode_cache=False,
+        enable_blending=False,
+        extra_config={"remote_enable_mla_worker_id_as0": True},
+    )
+
+    metadata = LMCacheMetadata(
+        model_name="test-model",
+        kv_dtype=torch.float16,
+        kv_shape=(32, 1, 256, 64, 128),
+        use_mla=True,
+        world_size=4,
+        local_world_size=4,
+        worker_id=2,
+        local_worker_id=2,
+    )
+    metadata0 = LMCacheMetadata(
+        model_name="test-model",
+        kv_dtype=torch.float16,
+        kv_shape=(32, 1, 256, 64, 128),
+        use_mla=True,
+        world_size=4,
+        local_world_size=4,
+        worker_id=0,
+        local_worker_id=0,
+    )
+
+    # Create memory allocator and local backend
+    # First Party
+    from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import (
+        AdHocMemoryAllocator,
+    )
+
+    pin_allocator = AdHocMemoryAllocator()
+    local_cpu_backend = LocalCPUBackend(
+        config, metadata, memory_allocator=pin_allocator
+    )
+
+    loop = asyncio.new_event_loop()
+    backend = RemoteBackend(
+        config=config,
+        metadata=metadata,
+        loop=loop,
+        local_cpu_backend=local_cpu_backend,
+    )
+    backend.connection = MockConnector()
+
+    # Start the event loop in a separate thread
+    loop_thread = threading.Thread(target=loop.run_forever, daemon=True)
+    loop_thread.start()
+
+    # Create key
+    key = CacheEngineKey(
+        model_name="test-model",
+        world_size=4,
+        worker_id=2,
+        chunk_hash="test_hash",
+        dtype=torch.float32,
+    )
+
+    local_cpu_backend0 = LocalCPUBackend(
+        config, metadata0, memory_allocator=pin_allocator
+    )
+    backend0 = RemoteBackend(
+        config=config,
+        metadata=metadata0,
+        loop=loop,
+        local_cpu_backend=local_cpu_backend0,
+    )
+    backend0.connection = backend.connection
+    # Create key
+    key0 = CacheEngineKey(
+        model_name="test-model",
+        world_size=4,
+        worker_id=0,
+        chunk_hash="test_hash",
+        dtype=torch.float32,
+    )
+
+    # Test not contains before adding data
+    assert not backend.contains(key)
+    assert not backend0.contains(key0)
+
+    # Test submit_put_task
+    memory_obj = local_cpu_backend.allocate(torch.Size([10, 10]), torch.float32)
+    future = backend.submit_put_task(key, memory_obj)
+    # Wait for put task to complete
+    if future is not None:
+        future.result()
+
+    # Test not contains after adding data since worker_id 2 skipped put
+    assert not backend.contains(key)
+
+    future = backend0.submit_put_task(key0, memory_obj)
+    # Wait for put task to complete
+    if future is not None:
+        future.result()
+
+    # Test contains after adding data since worker_id 0 should put
+    assert backend0.contains(key0)
+    # Test contains after adding data since we use worker_id 0 instead
+    assert backend.contains(key)
+
+    # Test get_blocking
+    retrieved = backend.get_blocking(key)
+    assert retrieved is not None
+    assert retrieved.get_shape() == torch.Size([10, 10])
+
+    # Cleanup
+    async def shutdown():
+        # Get all tasks
+        tasks = [t for t in asyncio.all_tasks(loop) if t is not asyncio.current_task()]
+        for task in tasks:
+            task.cancel()
+        # Wait for all tasks to be cancelled (or completed)
+        await asyncio.gather(*tasks, return_exceptions=True)
+        # Then stop the loop
+        loop.stop()
+
+    # Schedule the shutdown coroutine in the event loop thread
+    future = asyncio.run_coroutine_threadsafe(shutdown(), loop)
+    try:
+        # Wait for the shutdown to complete, but with a timeout
+        future.result(timeout=10)
+    except Exception as e:
+        print(f"Error during shutdown: {e}")
+    finally:
+        # Wait for the loop thread to finish
+        loop_thread.join(timeout=1.0)
+        loop.close()
diff --git a/tests/v1/test_staging_buffer.py b/tests/v1/test_staging_buffer.py
new file mode 100644
index 0000000..7e6cfde
--- /dev/null
+++ b/tests/v1/test_staging_buffer.py
@@ -0,0 +1,192 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Regression tests for issue #6215: staging scratch buffer prevents
+allocator reuse from corrupting in-flight buffer-GET data.
+
+Tests cover:
+1. The underlying bug (dangling byte_array after allocator reuse)
+2. Staging buffer safety (independent of allocator lifecycle)
+3. ValkeyConnector._do_get_into staging path
+"""
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+
+
+class TestUnderlyingBug:
+    """Demonstrates the root cause: byte_array dangles after free."""
+
+    def test_byte_array_dangling_after_free(self):
+        """byte_array memoryview sees new allocation's data after slot reuse."""
+        pool = torch.zeros(8192, dtype=torch.uint8, device="cpu")
+        allocator = TensorMemoryAllocator(pool)
+        shape = torch.Size([4096])
+
+        obj1 = allocator.allocate(shape, torch.uint8)
+        obj1.raw_data.fill_(0xAA)
+        mv1 = obj1.byte_array
+        if mv1.format != "B":
+            mv1 = mv1.cast("B")
+        assert mv1[0] == 0xAA
+
+        obj1.ref_count_down()  # free slot
+
+        obj2 = allocator.allocate(shape, torch.uint8)
+        obj2.raw_data.fill_(0xBB)
+
+        # BUG: mv1 is dangling — sees obj2's data
+        assert mv1[0] == 0xBB
+        obj2.ref_count_down()
+
+    def test_late_write_corrupts_recycled_slot(self):
+        """A write into a dangling memoryview destroys another allocation."""
+        # Standard
+        import ctypes
+
+        pool = torch.zeros(4096, dtype=torch.uint8, device="cpu")
+        allocator = TensorMemoryAllocator(pool)
+        shape = torch.Size([4096])
+
+        obj_a = allocator.allocate(shape, torch.uint8)
+        mv_a = obj_a.byte_array
+        if mv_a.format != "B":
+            mv_a = mv_a.cast("B")
+
+        obj_a.ref_count_down()  # slot recycled
+
+        obj_b = allocator.allocate(shape, torch.uint8)
+        obj_b.raw_data.fill_(0xBB)
+
+        # Late write (simulates Rust buffer-GET arriving after free)
+        ctypes.memset(ctypes.addressof(ctypes.c_ubyte.from_buffer(mv_a)), 0xCC, 4096)
+
+        # obj_b is corrupted
+        assert obj_b.raw_data[0].item() == 0xCC
+        obj_b.ref_count_down()
+
+
+class TestStagingBufferSafety:
+    """Staging scratch buffer is independent of allocator lifecycle."""
+
+    def test_scratch_unaffected_by_slab_reuse(self):
+        """Scratch buffer retains correct data even after slab is recycled."""
+        pool = torch.zeros(4096, dtype=torch.uint8, device="cpu")
+        allocator = TensorMemoryAllocator(pool)
+        shape = torch.Size([4096])
+
+        scratch = bytearray(4096)
+        scratch[:] = bytes([0xAA]) * 4096  # simulate GLIDE writing
+
+        obj = allocator.allocate(shape, torch.uint8)
+        obj.ref_count_down()  # free
+
+        obj2 = allocator.allocate(shape, torch.uint8)
+        obj2.raw_data.fill_(0xBB)  # overwrite slab
+
+        # Scratch is untouched — safe to copy from
+        assert scratch[0] == 0xAA
+        assert scratch[4095] == 0xAA
+        obj2.ref_count_down()
+
+    def test_scratch_reuse_across_calls(self):
+        """Scratch buffer grows and is reused without reallocation."""
+        # Standard
+        import threading
+
+        local = threading.local()
+
+        def get_scratch(size):
+            buf = getattr(local, "scratch", None)
+            if buf is None or len(buf) < size:
+                buf = bytearray(size)
+                local.scratch = buf
+            return buf
+
+        s1 = get_scratch(1024)
+        s1_id = id(s1)
+        s2 = get_scratch(512)  # smaller — reuses same buffer
+        assert id(s2) == s1_id
+
+        s3 = get_scratch(2048)  # larger — grows
+        assert len(s3) == 2048
+        s4 = get_scratch(1024)  # smaller again — reuses grown buffer
+        assert id(s4) == id(s3)
+
+
+class TestValkeyConnectorStaging:
+    """Tests for _ThreadWorkerPool staging buffer integration."""
+
+    def test_get_scratch_returns_correct_size(self):
+        """_get_scratch returns buffer at least as large as requested."""
+        # Standard
+        import threading
+
+        # Simulate the _get_scratch method
+        local = threading.local()
+
+        def _get_scratch(size):
+            buf = getattr(local, "scratch", None)
+            if buf is None or len(buf) < size:
+                buf = bytearray(size)
+                local.scratch = buf
+            return buf
+
+        buf = _get_scratch(65536)
+        assert len(buf) >= 65536
+        # Reuse
+        buf2 = _get_scratch(4096)
+        assert id(buf2) == id(buf)
+
+    def test_do_get_into_copies_only_n_bytes(self):
+        """Only the bytes actually received are copied into destination."""
+        scratch = bytearray(1024)
+        scratch[:500] = bytes([0xAA]) * 500
+        scratch[500:] = bytes([0x00]) * 524
+
+        dst = bytearray(1024)
+        n = 500
+        # Simulate: buf[:n] = scratch_view[:n]
+        memoryview(dst)[:n] = memoryview(scratch)[:n]
+
+        assert dst[0] == 0xAA
+        assert dst[499] == 0xAA
+        assert dst[500] == 0x00  # untouched beyond n
+
+
+class TestValkeyConnectorBatchStaging:
+    """Tests for batched staging buffer copy logic."""
+
+    def test_batch_staging_copies_all_buffers(self):
+        """Batched path stages into scratch then copies to each slab."""
+        pool = torch.zeros(4096 * 3, dtype=torch.uint8, device="cpu")
+        allocator = TensorMemoryAllocator(pool)
+        shape = torch.Size([4096])
+
+        objs = [allocator.allocate(shape, torch.uint8) for _ in range(3)]
+        assert all(o is not None for o in objs)
+
+        # Simulate: batch_get writes different patterns into scratch buffers
+        scratches = [bytearray(4096) for _ in range(3)]
+        for i, s in enumerate(scratches):
+            s[:] = bytes([i + 1]) * 4096
+
+        # Copy staged data into slab buffers (simulates post-batch_get copy)
+        for obj, scratch in zip(objs, scratches, strict=True):
+            dst = obj.byte_array
+            if not isinstance(dst, memoryview):
+                dst = memoryview(dst)
+            if dst.format != "B":
+                dst = dst.cast("B")
+            dst[:4096] = memoryview(scratch)[:4096]
+
+        # Verify each slab got the right data
+        assert objs[0].raw_data[0].item() == 1
+        assert objs[1].raw_data[0].item() == 2
+        assert objs[2].raw_data[0].item() == 3
+
+        for obj in objs:
+            obj.ref_count_down()
+        assert allocator.memcheck()
diff --git a/tests/v1/test_subclass_discovery.py b/tests/v1/test_subclass_discovery.py
new file mode 100644
index 0000000..3a87665
--- /dev/null
+++ b/tests/v1/test_subclass_discovery.py
@@ -0,0 +1,612 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for ``lmcache.v1.utils.subclass_discovery``."""
+
+# Standard
+from pathlib import Path
+from typing import Iterable, List, Tuple
+import importlib
+import sys
+import textwrap
+import uuid
+
+# Third Party
+import pytest
+
+# First Party
+from lmcache.v1.utils.subclass_discovery import discover_subclasses
+
+
+def _write_module(pkg_dir: Path, name: str, source: str) -> None:
+    (pkg_dir / f"{name}.py").write_text(textwrap.dedent(source))
+
+
+@pytest.fixture
+def temp_pkg(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    """Create a fresh, importable Python package on disk and yield its
+    fully-qualified name plus its filesystem path.
+
+    The fixture also takes care of cleaning ``sys.modules`` so each test
+    starts from a clean slate even when reusing the same Python
+    interpreter.
+    """
+    pkg_name = f"_subclass_discovery_pkg_{uuid.uuid4().hex}"
+    pkg_dir = tmp_path / pkg_name
+    pkg_dir.mkdir()
+    (pkg_dir / "__init__.py").write_text("")
+
+    # Make the parent dir importable.
+    monkeypatch.syspath_prepend(str(tmp_path))
+
+    yield pkg_name, pkg_dir
+
+    # Drop every module that the test imported under this package so
+    # subsequent runs cannot observe stale state.
+    for mod_name in [
+        m for m in list(sys.modules) if m == pkg_name or m.startswith(pkg_name + ".")
+    ]:
+        sys.modules.pop(mod_name, None)
+
+
+def _populate_basic_pkg(pkg_dir: Path) -> None:
+    """A minimal layout used by the majority of the tests:
+    base.py defines Base + AbstractChild, child_a.py & child_b.py define
+    one concrete subclass each.
+    """
+    _write_module(
+        pkg_dir,
+        "base",
+        """
+        from abc import ABC, abstractmethod
+
+        class Base(ABC):
+            @abstractmethod
+            def name(self) -> str: ...
+
+        class AbstractChild(Base):
+            # Still abstract: does not implement name().
+            pass
+        """,
+    )
+    _write_module(
+        pkg_dir,
+        "child_a",
+        """
+        from .base import Base
+
+        class ChildA(Base):
+            def name(self) -> str:
+                return "a"
+        """,
+    )
+    _write_module(
+        pkg_dir,
+        "child_b",
+        """
+        from .base import Base
+
+        class ChildB(Base):
+            def name(self) -> str:
+                return "b"
+        """,
+    )
+
+
+def _names(classes: Iterable[type]) -> List[str]:
+    return sorted(c.__name__ for c in classes)
+
+
+class TestDiscoverSubclassesBasic:
+    def test_finds_concrete_subclasses(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+            )
+        )
+
+        assert _names(result) == ["ChildA", "ChildB"]
+
+    def test_accepts_module_object(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+
+        pkg_mod = importlib.import_module(pkg_name)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_mod,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+            )
+        )
+
+        assert _names(result) == ["ChildA", "ChildB"]
+
+    def test_base_class_itself_is_skipped(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        # Even when scanning base.py the Base class itself is not yielded.
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                include_abstract=True,
+            )
+        )
+
+        assert base_mod.Base not in result
+
+
+class TestAbstractFiltering:
+    def test_skips_abstract_by_default(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(discover_subclasses(pkg_name, base_mod.Base))
+
+        # AbstractChild lives in base.py; with default filter
+        # (include_abstract=False) it must be excluded.
+        assert "AbstractChild" not in _names(result)
+        assert _names(result) == ["ChildA", "ChildB"]
+
+    def test_include_abstract_keeps_them(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                include_abstract=True,
+            )
+        )
+        assert "AbstractChild" in _names(result)
+
+
+class TestModuleFilter:
+    def test_module_filter_skips_modules(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n == "child_a",
+            )
+        )
+        assert _names(result) == ["ChildA"]
+
+
+class TestReExportHandling:
+    def test_default_excludes_reexports(self, temp_pkg: Tuple[str, Path]) -> None:
+        """A class re-exported from another module must not be yielded
+        twice when ``require_defined_in_module=True`` (the default)."""
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        # extra.py only re-imports ChildA; it does not define a new class.
+        _write_module(
+            pkg_dir,
+            "extra",
+            """
+            from .child_a import ChildA  # re-export
+            """,
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+            )
+        )
+        # Each class appears at most once - the re-export does not
+        # cause duplication.
+        assert _names(result) == ["ChildA", "ChildB"]
+
+    def test_disable_require_defined_keeps_reexports_but_dedups(
+        self, temp_pkg: Tuple[str, Path]
+    ) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        _write_module(
+            pkg_dir,
+            "extra",
+            """
+            from .child_a import ChildA  # re-export
+            """,
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+                require_defined_in_module=False,
+            )
+        )
+        # Even though ChildA is visible in two modules, dedup ensures
+        # it is yielded a single time.
+        assert _names(result) == ["ChildA", "ChildB"]
+        # And it is exactly the same class object.
+        assert result.count(importlib.import_module(f"{pkg_name}.child_a").ChildA) == 1
+
+
+class TestImportErrorHandling:
+    def test_callback_invoked_on_failure(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        _write_module(
+            pkg_dir,
+            "broken",
+            """
+            raise RuntimeError("boom")
+            """,
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        captured: List[Tuple[str, BaseException]] = []
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+                on_import_error=lambda mod, exc: captured.append((mod, exc)),
+            )
+        )
+
+        # Discovery still produced the healthy modules.
+        assert _names(result) == ["ChildA", "ChildB"]
+        assert len(captured) == 1
+        failed_mod, failed_exc = captured[0]
+        assert failed_mod == f"{pkg_name}.broken"
+        assert isinstance(failed_exc, RuntimeError)
+
+    def test_default_handler_logs_and_continues(
+        self,
+        temp_pkg: Tuple[str, Path],
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_basic_pkg(pkg_dir)
+        _write_module(
+            pkg_dir,
+            "broken",
+            """
+            raise RuntimeError("boom")
+            """,
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        # Spy directly on the module-level logger to avoid coupling the
+        # test to pytest's caplog interaction with the project's
+        # custom logger setup.
+        # First Party
+        from lmcache.v1.utils import subclass_discovery as sd
+
+        warnings: List[Tuple[str, Tuple[object, ...]]] = []
+        monkeypatch.setattr(
+            sd.logger,
+            "warning",
+            lambda msg, *args, **kwargs: warnings.append((msg, args)),
+        )
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+            )
+        )
+
+        assert _names(result) == ["ChildA", "ChildB"]
+        # The default handler must surface the failure via logging,
+        # without aborting the iteration.
+        assert any(f"{pkg_name}.broken" in str(args) for _, args in warnings)
+
+
+class TestInvalidPackage:
+    def test_non_package_raises_type_error(self) -> None:
+        # A regular (non-package) module: pytest itself has no __path__.
+        # Standard
+        import io  # any builtin module without __path__
+
+        with pytest.raises(TypeError):
+            list(discover_subclasses(io, object))
+
+
+def _populate_nested_pkg(pkg_dir: Path) -> None:
+    """Layout exercising multi-level discovery:
+
+    * depth 1: ``base.py`` (Base + AbstractChild), ``leaf_top.py`` (TopChild)
+    * depth 1 sub-pkg ``mid/`` with its own ``leaf_mid.py`` (MidChild)
+    * depth 2 sub-pkg ``mid/deep/`` with ``leaf_deep.py`` (DeepChild)
+    """
+    _write_module(
+        pkg_dir,
+        "base",
+        """
+        from abc import ABC, abstractmethod
+
+        class Base(ABC):
+            @abstractmethod
+            def name(self) -> str: ...
+
+        class AbstractChild(Base):
+            pass
+        """,
+    )
+    _write_module(
+        pkg_dir,
+        "leaf_top",
+        """
+        from .base import Base
+
+        class TopChild(Base):
+            def name(self) -> str:
+                return "top"
+        """,
+    )
+    mid = pkg_dir / "mid"
+    mid.mkdir()
+    (mid / "__init__.py").write_text("")
+    _write_module(
+        mid,
+        "leaf_mid",
+        """
+        from ..base import Base
+
+        class MidChild(Base):
+            def name(self) -> str:
+                return "mid"
+        """,
+    )
+    deep = mid / "deep"
+    deep.mkdir()
+    (deep / "__init__.py").write_text("")
+    _write_module(
+        deep,
+        "leaf_deep",
+        """
+        from ...base import Base
+
+        class DeepChild(Base):
+            def name(self) -> str:
+                return "deep"
+        """,
+    )
+
+
+class TestLevels:
+    def test_default_keeps_legacy_top_level_only(
+        self, temp_pkg: Tuple[str, Path]
+    ) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+            )
+        )
+        # No ``levels`` argument: behaves exactly like the historic
+        # direct-children-only scan.
+        assert _names(result) == ["TopChild"]
+
+    def test_levels_1_1_matches_default(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+                levels=[1, 1],
+            )
+        )
+        assert _names(result) == ["TopChild"]
+
+    def test_levels_2_2_only_grandchildren(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                levels=[2, 2],
+            )
+        )
+        # Only ``mid/leaf_mid.py`` lives at depth 2.
+        assert _names(result) == ["MidChild"]
+
+    def test_levels_1_2_combines_both_layers(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+                levels=[1, 2],
+            )
+        )
+        assert _names(result) == ["MidChild", "TopChild"]
+
+    def test_unlimited_via_empty_list(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+                levels=[],
+            )
+        )
+        assert _names(result) == ["DeepChild", "MidChild", "TopChild"]
+
+    def test_unlimited_via_zero_zero(self, temp_pkg: Tuple[str, Path]) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+                levels=[0, 0],
+            )
+        )
+        assert _names(result) == ["DeepChild", "MidChild", "TopChild"]
+
+    def test_module_filter_applies_per_level(self, temp_pkg: Tuple[str, Path]) -> None:
+        """The short-name filter is evaluated for every leaf module
+        regardless of its depth, matching the documented contract."""
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        # Add another depth-2 module that also happens to have the
+        # name ``leaf_mid`` shadowed under ``deep/`` -- proves the
+        # filter looks at the leaf short name, not the full path.
+        deep_dir = pkg_dir / "mid" / "deep"
+        _write_module(
+            deep_dir,
+            "leaf_mid",
+            """
+            from ...base import Base
+
+            class DeepShadow(Base):
+                def name(self) -> str:
+                    return "deep_shadow"
+            """,
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n == "leaf_mid",
+                levels=[],
+            )
+        )
+        assert _names(result) == ["DeepShadow", "MidChild"]
+
+    def test_discovers_class_in_subpackage_init(
+        self, temp_pkg: Tuple[str, Path]
+    ) -> None:
+        """A class defined directly in a sub-package ``__init__.py``
+        must be discovered at the sub-package's depth (depth 1).  This
+        matches the pre-levels legacy behaviour where sub-packages were
+        treated identically to leaf modules."""
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        # Place a class inside mid/__init__.py (depth 1 sub-package).
+        (pkg_dir / "mid" / "__init__.py").write_text(
+            textwrap.dedent(
+                """
+                from ..base import Base
+
+                class InitChild(Base):
+                    def name(self) -> str:
+                        return "init"
+                """
+            )
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        # Default levels [1, 1] -- depth 1, should see InitChild in
+        # mid/__init__.py at depth 1 + TopChild in leaf_top.py.
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                module_filter=lambda n: n != "base",
+            )
+        )
+        assert _names(result) == ["InitChild", "TopChild"]
+
+    def test_subpackage_init_not_found_at_deeper_level(
+        self, temp_pkg: Tuple[str, Path]
+    ) -> None:
+        """A class in a sub-package ``__init__.py`` at depth 1 must not
+        appear when the scan window excludes depth 1."""
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        (pkg_dir / "mid" / "__init__.py").write_text(
+            textwrap.dedent(
+                """
+                from ..base import Base
+
+                class InitChild(Base):
+                    def name(self) -> str:
+                        return "init"
+                """
+            )
+        )
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        # levels=[2, 2] only inspects depth-2 leaf modules.
+        result = list(
+            discover_subclasses(
+                pkg_name,
+                base_mod.Base,
+                levels=[2, 2],
+            )
+        )
+        # InitChild lives at depth 1, MidChild (mid/leaf_mid.py) at
+        # depth 2.
+        assert _names(result) == ["MidChild"]
+
+    @pytest.mark.parametrize(
+        "bad_levels",
+        [
+            [1],
+            [1, 2, 3],
+            [-1, 2],
+            [2, 1],
+            [0, 3],
+            [3, 0],
+        ],
+    )
+    def test_invalid_levels_raise(
+        self, temp_pkg: Tuple[str, Path], bad_levels: List[int]
+    ) -> None:
+        pkg_name, pkg_dir = temp_pkg
+        _populate_nested_pkg(pkg_dir)
+        base_mod = importlib.import_module(f"{pkg_name}.base")
+
+        with pytest.raises(ValueError):
+            list(
+                discover_subclasses(
+                    pkg_name,
+                    base_mod.Base,
+                    levels=bad_levels,
+                )
+            )
diff --git a/tests/v1/test_token_database.py b/tests/v1/test_token_database.py
new file mode 100644
index 0000000..33abfb3
--- /dev/null
+++ b/tests/v1/test_token_database.py
@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+import hashlib
+import os
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.token_database import ChunkedTokenDatabase, SegmentTokenDatabase
+
+# Local
+from .utils import dumb_metadata, dumb_metadata_with_model_name, generate_tokens
+
+
+def hf_credentials_available() -> bool:
+    token_env = os.getenv("HF_TOKEN")
+    hf_home = os.getenv("HF_HOME")
+    default_token_file = os.path.expanduser("~/.cache/huggingface/token")
+    token_file = os.path.join(hf_home, "token") if hf_home else ""
+    return bool(
+        token_env or os.path.exists(default_token_file) or os.path.exists(token_file)
+    )
+
+
+@pytest.mark.parametrize("chunk_length", [16, 64, 256])
+@pytest.mark.parametrize("save_unfull_chunk", [False, True])
+def test_chunked_token_database(chunk_length, save_unfull_chunk):
+    cfg = LMCacheEngineConfig.from_legacy(
+        chunk_size=chunk_length, backend="cpu", save_unfull_chunk=save_unfull_chunk
+    )
+    metadata = dumb_metadata()
+
+    test_length = 2500
+    tokens = generate_tokens(test_length, "cpu")
+    mask = torch.full([test_length], True, dtype=torch.bool, device="cpu")
+
+    num_falses = [i * chunk_length for i in range(0, test_length // chunk_length)]
+
+    db = ChunkedTokenDatabase(cfg, metadata)
+
+    # Process without mask
+    original_results = list(db.process_tokens(tokens=tokens))
+    end = (
+        test_length if save_unfull_chunk else (test_length - test_length % chunk_length)
+    )
+    for i in range(0, end, chunk_length):
+        st, ed, key = original_results[i // chunk_length]
+        assert st == i
+        if save_unfull_chunk:
+            assert ed == min(i + chunk_length, test_length)
+        else:
+            assert ed == i + chunk_length
+
+    for i in range(0, test_length // chunk_length):
+        mask[: num_falses[i]] = False
+        new_results = list(db.process_tokens(tokens=tokens, mask=mask))
+        assert len(new_results) == len(original_results) - i
+
+        for j in range(len(new_results)):
+            st, ed, key = new_results[j]
+            assert st == original_results[j + i][0]
+            assert ed == original_results[j + i][1]
+
+
+@pytest.mark.parametrize("prefix_length", [0, 16, 64, 256])
+@pytest.mark.parametrize("chunk_lengths", [[256, 512, 256], [1024, 512, 256]])
+@pytest.mark.skipif(
+    not hf_credentials_available(), reason="No Hugging Face credentials found"
+)
+def test_segment_token_database(prefix_length, chunk_lengths):
+    cfg = LMCacheEngineConfig.from_legacy(blend_special_str=" # # ")
+    metadata = dumb_metadata_with_model_name("facebook/opt-125m")
+
+    db = SegmentTokenDatabase(cfg, metadata)
+    sep_tokens = db.sep_tokens
+
+    sys_length = 25
+    query_length = 50
+    sys_tokens = generate_tokens(sys_length, "cpu", fixed=True)
+    query_tokens = generate_tokens(query_length, "cpu", fixed=True)
+
+    token_chunks = []
+    starts = [0]
+    ends = [sys_length]
+    sys_tuple = tuple(sys_tokens.cpu().tolist())
+    sys_hash = hash((None, sys_tuple, None))
+    hashes = [sys_hash]
+    start = sys_length + len(sep_tokens)
+    for idx, chunk_length in enumerate(chunk_lengths):
+        token_chunk = generate_tokens(chunk_length, "cpu", fixed=True)
+
+        token_tuple = tuple(token_chunk.cpu().tolist())
+        token_hash = hash((None, token_tuple, None))
+        hashes.append(token_hash)
+
+        token_chunk = torch.cat([sep_tokens, token_chunk])
+        token_chunks.append(token_chunk)
+        starts.append(start)
+        ends.append(start + chunk_length)
+        start += chunk_length + len(sep_tokens)
+
+    query_tuple = tuple(query_tokens.cpu().tolist())
+    query_hash = hash((None, query_tuple, None))
+    hashes.append(query_hash)
+    starts.append(start)
+    ends.append(start + query_length)
+
+    tokens = torch.cat([sys_tokens, *token_chunks, sep_tokens, query_tokens])
+    total_length = len(tokens)
+    mask = torch.full([total_length], True, dtype=torch.bool, device="cpu")
+    mask[:prefix_length] = False
+
+    chunk_lists = [sys_tokens, *token_chunks, sep_tokens, query_tokens]
+    skip_chunk_num = 0
+    cum_length = 0
+    for chunk in chunk_lists:
+        if prefix_length > cum_length:
+            skip_chunk_num += 1
+        cum_length += len(chunk)
+
+    starts = starts[skip_chunk_num:]
+    ends = ends[skip_chunk_num:]
+    hashes = hashes[skip_chunk_num:]
+
+    original_results = list(db.process_tokens(tokens=tokens, mask=mask))
+    for i in range(len(original_results)):
+        st, ed, key = original_results[i]
+        assert st == starts[i]
+        assert ed == ends[i]
+        assert key.chunk_hash == hashes[i]
+        # print(st, starts[i])
+        # print(ed, ends[i])
+
+
+def test_process_tokens_returns_int_keys_for_bytes_hash_func() -> None:
+    """process_tokens must produce int chunk_hash keys even when the underlying
+    hash function returns bytes (e.g. sha256_cbor). This ensures downstream
+    code such as msgpack serialisation always receives plain ints.
+    """
+    cfg = LMCacheEngineConfig.from_legacy(chunk_size=16, backend="cpu")
+    metadata = dumb_metadata()
+    db = ChunkedTokenDatabase(cfg, metadata)
+
+    # Stub that returns bytes, mimicking sha256_cbor without requiring cbor2.
+    db.hash_func = lambda x: hashlib.sha256(str(x).encode()).digest()
+
+    tokens = generate_tokens(32, "cpu")
+    results = list(db.process_tokens(tokens=tokens, make_key=False))
+
+    assert len(results) > 0
+    for _, _, hash_val in results:
+        assert isinstance(hash_val, int), f"Expected int, got {type(hash_val)}"
+        # Must fit in uint64 (msgpack range: 0 to 2**64 - 1)
+        assert 0 <= hash_val <= 2**64 - 1
diff --git a/tests/v1/test_trtllm_integration.py b/tests/v1/test_trtllm_integration.py
new file mode 100644
index 0000000..7ca6d0a
--- /dev/null
+++ b/tests/v1/test_trtllm_integration.py
@@ -0,0 +1,377 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Unit tests for the LMCache-side TRT-LLM integration components.
+
+Covers ``EngineType.TRTLLM``, the new ``NB_NL_TWO_NH_BS_HS`` GPU KV
+format, format-aware accessors in ``gpu_connector/utils.py``, the
+``TRTLLMGPUConnector`` construction path, and the
+``RawCudaIPCWrapper`` subclass relationship — without requiring
+TensorRT-LLM to be installed.
+"""
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.utils import EngineType
+
+
+def _has_lmc_ops() -> bool:
+    try:
+        # First Party
+        import lmcache.c_ops  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def _has_cuda() -> bool:
+    return torch.cuda.is_available()
+
+
+class TestEngineType:
+    def test_trtllm_exists(self) -> None:
+        assert hasattr(EngineType, "TRTLLM")
+        assert EngineType.TRTLLM.value == "trtllm"
+
+    def test_all_engine_types(self) -> None:
+        expected = {"vllm", "sglang", "trtllm", "mock"}
+        actual = {e.value for e in EngineType}
+        assert expected == actual
+
+
+class TestAssertContiguous:
+    def test_contiguous_tensor_passes(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import assert_contiguous
+
+        t = torch.zeros(2, 3, 4)
+        assert_contiguous(t)  # no raise
+
+    def test_non_contiguous_raises(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import assert_contiguous
+
+        t = torch.zeros(2, 3, 4).transpose(0, 1)
+        with pytest.raises(ValueError, match="not contiguous"):
+            assert_contiguous(t)
+
+    def test_nonzero_storage_offset_raises(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import assert_contiguous
+
+        base = torch.zeros(8)
+        view = base[2:6]  # storage_offset = 2
+        with pytest.raises(ValueError, match="storage_offset"):
+            assert_contiguous(view)
+
+
+@pytest.mark.skipif(not _has_lmc_ops(), reason="lmcache C ops not built")
+class TestGPUKVFormatEnum:
+    def test_nb_nl_two_nh_bs_hs_exists(self) -> None:
+        # First Party
+        import lmcache.c_ops as lmc_ops
+
+        assert hasattr(lmc_ops.EngineKVFormat, "NB_NL_TWO_NH_BS_HS")
+
+
+@pytest.mark.skipif(not _has_lmc_ops(), reason="lmcache C ops not built")
+class TestNormalizeTRTLLM:
+    """``normalize_kv_and_discover_format`` for ``EngineType.TRTLLM``."""
+
+    def test_4d_tensor_reshape_to_6d(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import (
+            LayoutHints,
+            normalize_kv_and_discover_format,
+        )
+        import lmcache.c_ops as lmc_ops
+
+        nb, nl, kv = 4, 2, 2
+        nh, bs, hs = 8, 16, 64
+        flat = nh * bs * hs
+
+        t = torch.zeros(nb, nl, kv, flat, dtype=torch.bfloat16)
+        layout_hints: LayoutHints = {
+            "kv_layout": "HND",
+            "num_kv_heads": nh,
+            "tokens_per_block": bs,
+            "head_dim": hs,
+        }
+
+        fmt, normalized = normalize_kv_and_discover_format(
+            t, EngineType.TRTLLM, layout_hints=layout_hints
+        )
+
+        assert fmt == lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS
+        assert isinstance(normalized, torch.Tensor)
+        assert tuple(normalized.shape) == (nb, nl, kv, nh, bs, hs)
+
+    def test_collapses_one_element_list(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import (
+            LayoutHints,
+            normalize_kv_and_discover_format,
+        )
+        import lmcache.c_ops as lmc_ops
+
+        nb, nl, kv, nh, bs, hs = 2, 2, 2, 4, 8, 32
+        t = torch.zeros(nb, nl, kv, nh * bs * hs)
+        layout_hints: LayoutHints = {
+            "kv_layout": "HND",
+            "num_kv_heads": nh,
+            "tokens_per_block": bs,
+            "head_dim": hs,
+        }
+        fmt, normalized = normalize_kv_and_discover_format(
+            [t], EngineType.TRTLLM, layout_hints=layout_hints
+        )
+        assert fmt == lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS
+        assert isinstance(normalized, torch.Tensor)
+        assert normalized.shape == (nb, nl, kv, nh, bs, hs)
+
+    def test_missing_layout_hints_raises(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import normalize_kv_and_discover_format
+
+        t = torch.zeros(2, 2, 2, 16)
+        with pytest.raises(ValueError, match="num_kv_heads"):
+            normalize_kv_and_discover_format(t, EngineType.TRTLLM, layout_hints={})
+
+    def test_flat_dim_mismatch_raises(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import (
+            LayoutHints,
+            normalize_kv_and_discover_format,
+        )
+
+        t = torch.zeros(2, 2, 2, 17)  # not divisible by 4*2*2 = 16
+        layout_hints: LayoutHints = {
+            "kv_layout": "HND",
+            "num_kv_heads": 4,
+            "tokens_per_block": 2,
+            "head_dim": 2,
+        }
+        with pytest.raises(ValueError, match="flat dim"):
+            normalize_kv_and_discover_format(
+                t, EngineType.TRTLLM, layout_hints=layout_hints
+            )
+
+
+@pytest.mark.skipif(not _has_lmc_ops(), reason="lmcache C ops not built")
+class TestAccessorsTRTLLM:
+    """Format accessors for ``NB_NL_TWO_NH_BS_HS``."""
+
+    def _tensor(
+        self,
+        nb: int = 4,
+        nl: int = 3,
+        kv: int = 2,
+        nh: int = 8,
+        bs: int = 16,
+        hs: int = 64,
+    ) -> torch.Tensor:
+        return torch.zeros(nb, nl, kv, nh, bs, hs, dtype=torch.bfloat16)
+
+    def test_get_num_layers(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_num_layers
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert get_num_layers(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 3
+
+    def test_get_num_blocks(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_num_blocks
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert get_num_blocks(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 4
+
+    def test_get_block_size(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_block_size
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert get_block_size(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 16
+
+    def test_get_num_heads(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_num_heads
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert get_num_heads(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 8
+
+    def test_get_head_size(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_head_size
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert get_head_size(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 64
+
+    def test_get_hidden_dim_size(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_hidden_dim_size
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert (
+            get_hidden_dim_size(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 8 * 64
+        )
+
+    def test_get_page_buffer_size(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_page_buffer_size
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert (
+            get_page_buffer_size(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == 4 * 16
+        )
+
+    def test_get_dtype(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_dtype
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        assert get_dtype(t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS) == torch.bfloat16
+
+    def test_get_group_data_ptrs_returns_single_base_pointer(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import get_group_data_ptrs
+        import lmcache.c_ops as lmc_ops
+
+        t = self._tensor()
+        ptrs = get_group_data_ptrs(
+            t, lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS, list(range(3))
+        )
+        assert len(ptrs) == 1
+        assert ptrs[0] == t.data_ptr()
+
+    def test_shape_description_strings(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.utils import (
+            get_attention_backend,
+            get_concrete_engine_kv_shape,
+            get_engine_kv_shape_description,
+        )
+        import lmcache.c_ops as lmc_ops
+
+        fmt = lmc_ops.EngineKVFormat.NB_NL_TWO_NH_BS_HS
+        assert get_engine_kv_shape_description(fmt) == "[NB, NL, 2, NH, BS, HS]"
+        assert "TRT-LLM" in get_attention_backend(fmt)
+        assert get_concrete_engine_kv_shape(self._tensor(), fmt) == (
+            "[4, 3, 2, 8, 16, 64]"
+        )
+
+
+@pytest.mark.skipif(not _has_cuda(), reason="CUDA required for connector init")
+@pytest.mark.skipif(not _has_lmc_ops(), reason="lmcache C ops not built")
+class TestTRTLLMGPUConnector:
+    def test_construct(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.gpu_connectors import TRTLLMGPUConnector
+
+        device = torch.device("cuda:0")
+        c = TRTLLMGPUConnector(
+            num_kv_heads=2,
+            head_dim=64,
+            hidden_dim_size=128,
+            num_layers=4,
+            chunk_size=256,
+            dtype=torch.bfloat16,
+            device=device,
+        )
+        assert c.num_kv_heads == 2
+        assert c.head_dim == 64
+        assert c.kv_cache_tensor is None  # not registered yet
+
+    def test_get_shape(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.gpu_connectors import TRTLLMGPUConnector
+
+        device = torch.device("cuda:0")
+        c = TRTLLMGPUConnector(
+            num_kv_heads=2,
+            head_dim=64,
+            hidden_dim_size=128,
+            num_layers=4,
+            chunk_size=256,
+            dtype=torch.bfloat16,
+            device=device,
+        )
+        # Memory-obj layout: [2, num_layers, num_tokens, hidden_dim]
+        assert tuple(c.get_shape(256)) == (2, 4, 256, 128)
+
+    def test_register_kv_caches_with_4d_tensor(self) -> None:
+        # First Party
+        from lmcache.v1.gpu_connector.gpu_connectors import TRTLLMGPUConnector
+
+        device = torch.device("cuda:0")
+        nh, bs, hs = 2, 16, 64
+        nb, nl, kv = 4, 4, 2
+        flat = nh * bs * hs
+        c = TRTLLMGPUConnector(
+            num_kv_heads=nh,
+            head_dim=hs,
+            hidden_dim_size=nh * hs,
+            num_layers=nl,
+            chunk_size=256,
+            dtype=torch.bfloat16,
+            device=device,
+        )
+        t = torch.zeros(nb, nl, kv, flat, dtype=torch.bfloat16, device=device)
+        c.register_kv_caches(t)
+        assert c.kv_cache_tensor is not None
+        assert tuple(c.kv_cache_tensor.shape) == (nb, nl, kv, nh, bs, hs)
+        assert c.tokens_per_block == bs
+        assert c.blocks_per_chunk == 256 // bs
+        assert c.shape_desc is not None
+        assert c.shape_desc.nl == nl
+        assert c.shape_desc.nb == nb
+        assert c.shape_desc.bs == bs
+        assert c.shape_desc.nh == nh
+        assert c.shape_desc.hs == hs
+
+
+class TestRawCudaIPCWrapperType:
+    """Subclass relationship — without invoking CUDA IPC syscalls."""
+
+    def test_is_subclass(self) -> None:
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import (
+            DeviceIPCWrapper,
+        )
+        from lmcache.v1.platform.cuda.ipc_wrapper import RawCudaIPCWrapper
+
+        assert issubclass(RawCudaIPCWrapper, DeviceIPCWrapper)
+
+    def test_kvcache_typing_unchanged(self) -> None:
+        """``KVCache = list[DeviceIPCWrapper]`` should accept concrete wrappers
+        — load-bearing for msgspec ext-code reuse over ZMQ.
+        """
+        # First Party
+        from lmcache.v1.multiprocess.custom_types import (
+            DeviceIPCWrapper,
+            KVCache,
+        )
+        from lmcache.v1.platform.cuda.ipc_wrapper import RawCudaIPCWrapper
+
+        assert KVCache == list[DeviceIPCWrapper]
+        # Static check substitute: a concrete wrapper fits the list type.
+        assert issubclass(RawCudaIPCWrapper, DeviceIPCWrapper)
+
+    def test_serde_uses_shared_ext_code(self) -> None:
+        """Ext code 1 dispatches via ``DeviceIPCWrapper`` for all wrappers."""
+        # First Party
+        from lmcache.v1.multiprocess import custom_types
+
+        registry = custom_types._CUSTOMERIZED_SERIALIZERS  # noqa: PLC2701
+        assert custom_types.DeviceIPCWrapper in registry
+        assert registry[custom_types.DeviceIPCWrapper].code == 1
diff --git a/tests/v1/test_v1_adapter_request_finished_scheduler_role.py b/tests/v1/test_v1_adapter_request_finished_scheduler_role.py
new file mode 100644
index 0000000..beee8ad
--- /dev/null
+++ b/tests/v1/test_v1_adapter_request_finished_scheduler_role.py
@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Regression test for LMCache#3337.
+
+``request_finished`` is a Scheduler-side connector API. In vLLM v1's
+split-process architecture:
+
+- The Scheduler typically does **not** initialize ``self.lmcache_engine``;
+  only the Worker role builds it by default (the Scheduler also builds
+  it when ``enable_scheduler_bypass_lookup`` is set).
+- The Scheduler **does** own ``self.lookup_client`` -- it is created
+  only on the Scheduler role (see
+  ``vllm_service_factory.maybe_create_lookup_client``).
+
+Previously the ``FINISHED_ABORTED`` cleanup path asserted both
+``self.lmcache_engine is not None`` and ``self.lookup_client is not None``.
+Under concurrent abort cleanups the first assert fired as an unhandled
+``AssertionError`` and killed the EngineCore process for every connected
+user.
+
+The fix replaces both asserts with ``if-warn-skip`` so the engine stays
+alive and only the affected request's cleanup is dropped. It also moves
+the async lookup cancel out of the engine-None branch -- since the
+Scheduler owns ``lookup_client`` independently of the engine, the lookup
+cancel must still run for Scheduler-side aborts to avoid leaking
+in-flight async lookups.
+
+This test locks in:
+
+1. Scheduler default (engine=None, lookup_client=None, async_loading=False)
+   + abort -> no crash, warning emitted, no engine attribute is read.
+2. Scheduler default (engine=None) + ``async_loading=True`` +
+   lookup_client present + abort -> ``lookup_client.cancel_lookup``
+   still runs (resource-leak regression guard).
+3. Engine initialized + abort -> ``storage_manager.cancel_request`` runs.
+4. Engine initialized + ``async_loading=True`` + lookup_client present
+   + abort -> both cancels run.
+5. ``async_loading=True`` + lookup_client missing + abort -> warns and
+   skips the lookup cancel instead of crashing.
+"""
+
+# Standard
+from collections.abc import Iterator
+from contextlib import contextmanager
+from types import SimpleNamespace
+import logging
+
+# Third Party
+import pytest
+
+pytest.importorskip("vllm")
+
+# Third Party
+# Third Party (after importorskip)
+from vllm.v1.request import RequestStatus  # noqa: E402
+
+# First Party
+from lmcache.integration.vllm.vllm_v1_adapter import LMCacheConnectorV1Impl
+
+_ADAPTER_LOGGER_NAME = "lmcache.integration.vllm.vllm_v1_adapter"
+
+
+@contextmanager
+def _capture_adapter_warnings() -> Iterator[list[logging.LogRecord]]:
+    """Capture WARNING records emitted by the adapter logger.
+
+    lmcache's ``init_logger`` sets ``propagate = False`` on the adapter
+    logger, so its records never reach pytest's ``caplog`` (which attaches a
+    handler to the root logger). Attach a handler directly to the named
+    logger instead -- the convention used across the v1 adapter tests -- and
+    force WARNING level so a higher ``LMCACHE_LOG_LEVEL`` cannot filter the
+    records out before the handler sees them.
+    """
+    records: list[logging.LogRecord] = []
+
+    class _ListHandler(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            records.append(record)
+
+    handler = _ListHandler(level=logging.WARNING)
+    logger = logging.getLogger(_ADAPTER_LOGGER_NAME)
+    original_level = logger.level
+    logger.setLevel(logging.WARNING)
+    logger.addHandler(handler)
+    try:
+        yield records
+    finally:
+        logger.removeHandler(handler)
+        logger.setLevel(original_level)
+
+
+class _FakeStorageManager:
+    def __init__(self) -> None:
+        self.cancelled: list[str] = []
+
+    def cancel_request(self, req_id: str) -> None:
+        self.cancelled.append(req_id)
+
+
+class _FakeEngine:
+    def __init__(self) -> None:
+        self.storage_manager = _FakeStorageManager()
+
+
+class _FakeLookupClient:
+    def __init__(self) -> None:
+        self.cancelled: list[str] = []
+
+    def cancel_lookup(self, req_id: str) -> None:
+        self.cancelled.append(req_id)
+
+
+def _make_aborted_request(req_id: str) -> SimpleNamespace:
+    """Build the minimum request shape ``request_finished`` reads."""
+    return SimpleNamespace(
+        request_id=req_id,
+        status=RequestStatus.FINISHED_ABORTED,
+    )
+
+
+def _make_connector(
+    *,
+    engine: object,
+    lookup_client: object,
+    async_loading: bool,
+) -> LMCacheConnectorV1Impl:
+    """Bypass ``__init__`` and pin only the attributes ``request_finished``
+    reads, so the test exercises the abort cleanup path in isolation.
+
+    ``lmcache_engine`` and ``lookup_client`` are read-only properties on
+    ``LMCacheConnectorV1Impl`` that delegate to ``self._manager``, so the
+    fixture installs a fake manager rather than assigning to those
+    properties directly.
+    """
+    connector = LMCacheConnectorV1Impl.__new__(LMCacheConnectorV1Impl)
+    connector._manager = SimpleNamespace(  # type: ignore[assignment]
+        lmcache_engine=engine,
+        lookup_client=lookup_client,
+    )
+    connector.async_loading = async_loading
+    connector.use_layerwise = False
+    connector.config = SimpleNamespace(
+        get_extra_config_value=lambda key, default: default
+    )
+    connector._request_trackers = {}
+    return connector
+
+
+def test_request_finished_scheduler_default_engine_none_skips_cleanup() -> None:
+    """Scheduler default config: ``lmcache_engine`` is None, abort must
+    not crash the EngineCore.
+
+    Regression for https://github.com/LMCache/LMCache/issues/3337.
+    """
+    connector = _make_connector(engine=None, lookup_client=None, async_loading=False)
+    request = _make_aborted_request("req-scheduler-default-abort")
+
+    with _capture_adapter_warnings() as records:
+        delay_free, return_params = connector.request_finished(request, [0, 1])
+
+    assert delay_free is False
+    assert return_params is None
+
+    warnings = [r for r in records if r.levelno == logging.WARNING]
+    assert any(
+        "req-scheduler-default-abort" in r.getMessage()
+        and "lmcache_engine" in r.getMessage()
+        for r in warnings
+    ), (
+        "Expected a warning naming the request id and lmcache_engine; "
+        f"got {[r.getMessage() for r in warnings]}"
+    )
+
+
+def test_request_finished_scheduler_default_async_loading_runs_lookup_cancel() -> None:
+    """Scheduler default (engine=None) + ``async_loading=True`` +
+    lookup_client present: ``lookup_client.cancel_lookup`` must still
+    run. Resource-leak regression guard -- the Scheduler owns
+    ``lookup_client`` even when it does not build an engine, so the
+    lookup cancel cannot be nested inside the engine-not-None branch.
+    """
+    lookup_client = _FakeLookupClient()
+    connector = _make_connector(
+        engine=None, lookup_client=lookup_client, async_loading=True
+    )
+    request = _make_aborted_request("req-scheduler-async-abort")
+
+    connector.request_finished(request, [0, 1])
+
+    assert lookup_client.cancelled == ["req-scheduler-async-abort"], (
+        "Scheduler-side abort must still cancel async lookups even when "
+        "lmcache_engine is None; otherwise async lookups leak."
+    )
+
+
+def test_request_finished_engine_initialized_runs_storage_manager_cancel() -> None:
+    """Engine-initialized path (Worker, or Scheduler with bypass lookup):
+    ``cancel_request`` must still fire on abort. Guards against the fix
+    accidentally short-circuiting the happy path.
+    """
+    engine = _FakeEngine()
+    connector = _make_connector(engine=engine, lookup_client=None, async_loading=False)
+    request = _make_aborted_request("req-engine-abort")
+
+    delay_free, return_params = connector.request_finished(request, [0, 1])
+
+    assert delay_free is False
+    assert return_params is None
+    assert engine.storage_manager.cancelled == ["req-engine-abort"]
+
+
+def test_request_finished_engine_with_async_loading_runs_both_cancels() -> None:
+    """Engine-initialized + ``async_loading=True`` + ``lookup_client``
+    present: both ``storage_manager.cancel_request`` and
+    ``lookup_client.cancel_lookup`` must fire on abort.
+    """
+    engine = _FakeEngine()
+    lookup_client = _FakeLookupClient()
+    connector = _make_connector(
+        engine=engine, lookup_client=lookup_client, async_loading=True
+    )
+    request = _make_aborted_request("req-async-abort")
+
+    connector.request_finished(request, [0, 1])
+
+    assert engine.storage_manager.cancelled == ["req-async-abort"]
+    assert lookup_client.cancelled == ["req-async-abort"]
+
+
+def test_request_finished_async_loading_without_lookup_client_skips_cancel() -> None:
+    """``async_loading=True`` + ``lookup_client`` missing: the second
+    assert in the original block would have crashed here too. The fix
+    must warn and skip, matching the fail-soft contract.
+    """
+    engine = _FakeEngine()
+    connector = _make_connector(engine=engine, lookup_client=None, async_loading=True)
+    request = _make_aborted_request("req-no-lookup-abort")
+
+    with _capture_adapter_warnings() as records:
+        connector.request_finished(request, [0, 1])
+
+    # storage_manager.cancel_request still fired (only the lookup path skipped)
+    assert engine.storage_manager.cancelled == ["req-no-lookup-abort"]
+
+    warnings = [r for r in records if r.levelno == logging.WARNING]
+    assert any(
+        "req-no-lookup-abort" in r.getMessage() and "lookup_client" in r.getMessage()
+        for r in warnings
+    ), (
+        "Expected a warning naming the request id and lookup_client; "
+        f"got {[r.getMessage() for r in warnings]}"
+    )
diff --git a/tests/v1/test_v1_adapter_state_desync.py b/tests/v1/test_v1_adapter_state_desync.py
new file mode 100644
index 0000000..a57b77c
--- /dev/null
+++ b/tests/v1/test_v1_adapter_state_desync.py
@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Regression test for LMCache#3318.
+
+The vLLM v1 adapter previously asserted
+``len(slot_mapping) == len(token_ids)`` inside ``wait_for_save``. When the
+state desynced (e.g. upstream allocation failure or preemption-induced
+mismatch) the assertion fired as an unhandled ``AssertionError`` and
+killed the entire EngineCore process for every connected user.
+
+The fix replaces the assert with a logged ``continue`` so the engine
+stays alive and only the affected request's save is dropped. This test
+locks in that behavior by feeding ``wait_for_save`` a request whose
+``slot_mapping`` and ``token_ids`` lengths disagree and asserting:
+
+1. ``wait_for_save`` does not raise.
+2. A warning is emitted naming the request id and both lengths.
+3. ``lmcache_engine.store`` is not called for the desynced request
+   (the save is dropped, not silently corrupted).
+4. ``lookup_unpin`` is still called so the pin count stays balanced.
+"""
+
+# Standard
+from types import SimpleNamespace
+import logging
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("vllm")
+
+# First Party
+from lmcache.integration.vllm.vllm_v1_adapter import (
+    LMCacheConnectorMetadata,
+    LMCacheConnectorV1Impl,
+    SaveSpec,
+)
+
+
+class _FakeParent:
+    def __init__(self, metadata: LMCacheConnectorMetadata) -> None:
+        self._connector_metadata = metadata
+
+    def _get_connector_metadata(self) -> LMCacheConnectorMetadata:
+        return self._connector_metadata
+
+
+class _FakeEngine:
+    """Records calls to ``lookup_unpin`` and ``store`` so the test can
+    assert which paths fired."""
+
+    def __init__(self) -> None:
+        self.unpinned: list[str] = []
+        self.store_calls: list[str] = []
+
+    def lookup_unpin(self, req_id: str) -> None:
+        self.unpinned.append(req_id)
+
+    def store(self, *args, **kwargs) -> None:
+        self.store_calls.append(kwargs.get("req_id", "<unknown>"))
+
+
+def _make_desync_request(
+    req_id: str, token_ids_len: int, slot_mapping_len: int
+) -> SimpleNamespace:
+    """Build a request whose ``token_ids`` and ``slot_mapping`` lengths
+    disagree, simulating a state desync."""
+    return SimpleNamespace(
+        req_id=req_id,
+        token_ids=list(range(token_ids_len)),
+        slot_mapping=torch.arange(slot_mapping_len, dtype=torch.long),
+        save_spec=SaveSpec(skip_leading_tokens=0, can_save=True),
+        disagg_spec=None,
+        is_last_prefill=True,
+        request_configs=None,
+    )
+
+
+def _make_connector(
+    requests: list[SimpleNamespace],
+) -> tuple[LMCacheConnectorV1Impl, _FakeEngine]:
+    metadata = LMCacheConnectorMetadata(requests=requests)  # type: ignore[arg-type]
+    engine = _FakeEngine()
+    connector = LMCacheConnectorV1Impl.__new__(LMCacheConnectorV1Impl)
+    connector._parent = _FakeParent(metadata)
+    # ``lmcache_engine`` is a read-only property backed by ``self._manager``;
+    # inject the fake engine through the manager so the property resolves to it.
+    connector._manager = SimpleNamespace(  # type: ignore[assignment]
+        lmcache_engine=engine
+    )
+    connector.kv_role = "kv_producer"
+    connector.use_layerwise = False
+    connector.enable_blending = False
+    connector.device = "cpu"
+    connector._lmcache_chunk_size = 8
+    connector.kv_caches = {"layer0": torch.zeros(1)}
+    connector.config = SimpleNamespace(pd_bidirectional=False)
+    return connector, engine
+
+
+def test_wait_for_save_skips_desynced_request_and_keeps_engine_alive() -> None:
+    """Length mismatch must drop only the affected request's save, log a
+    warning, and let ``wait_for_save`` return normally.
+
+    Regression for https://github.com/LMCache/LMCache/issues/3318.
+    """
+    # lmcache's ``init_logger`` sets ``propagate = False`` on the adapter
+    # logger so its records do not reach pytest's ``caplog`` (which
+    # attaches to the root logger). Toggling ``propagate`` is fragile --
+    # any lazy import that re-runs ``init_logger`` resets it. Attach a
+    # local handler directly to the named logger instead so we capture
+    # the warning regardless of how lmcache configures propagation.
+    captured_records: list[logging.LogRecord] = []
+
+    class _ListHandler(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            captured_records.append(record)
+
+    handler = _ListHandler(level=logging.WARNING)
+    adapter_logger = logging.getLogger("lmcache.integration.vllm.vllm_v1_adapter")
+    # ``init_logger`` sets the logger level from ``LMCACHE_LOG_LEVEL`` (default
+    # INFO). If a prior import set it above WARNING, ``logger.warning`` would be
+    # filtered before reaching our handler. Force WARNING for the duration of
+    # the test and restore the original level in ``finally``.
+    original_level = adapter_logger.level
+    adapter_logger.setLevel(logging.WARNING)
+    adapter_logger.addHandler(handler)
+    try:
+        desync_req = _make_desync_request(
+            "req-desync", token_ids_len=4, slot_mapping_len=3
+        )
+        connector, engine = _make_connector([desync_req])
+
+        connector.wait_for_save()
+
+        # 1. lookup_unpin still ran (pin balance preserved)
+        assert engine.unpinned == ["req-desync"]
+
+        # 2. store was NOT called for the desynced request (save dropped)
+        assert engine.store_calls == []
+
+        # 3. A warning was emitted naming the request and both lengths
+        warnings = [r for r in captured_records if r.levelno == logging.WARNING]
+        assert any(
+            "req-desync" in r.getMessage()
+            and "slot_mapping=3" in r.getMessage()
+            and "token_ids=4" in r.getMessage()
+            for r in warnings
+        ), (
+            "Expected desync warning naming req-desync; "
+            f"got {[r.getMessage() for r in warnings]}"
+        )
+    finally:
+        adapter_logger.removeHandler(handler)
+        adapter_logger.setLevel(original_level)
diff --git a/tests/v1/test_vllm_integration.py b/tests/v1/test_vllm_integration.py
new file mode 100644
index 0000000..798271f
--- /dev/null
+++ b/tests/v1/test_vllm_integration.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# TODO (Jiayi)
diff --git a/tests/v1/test_vllm_kv_cache_groups.py b/tests/v1/test_vllm_kv_cache_groups.py
new file mode 100644
index 0000000..4013e4d
--- /dev/null
+++ b/tests/v1/test_vllm_kv_cache_groups.py
@@ -0,0 +1,346 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from dataclasses import dataclass, field
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.integration.vllm.kv_cache_groups import (
+    create_engine_group_infos_from_vllm,
+)
+from lmcache.v1.multiprocess.group_view import (
+    expand_engine_block_ids,
+    get_engine_group_indices,
+    num_engine_groups,
+)
+
+# Test doubles for the vLLM KV cache spec classes. Unit tests must run
+# without vLLM installed; sliding-window specs are detected by class name,
+# so the doubles share the vLLM class names.
+
+
+@dataclass
+class MockKVCacheSpec:
+    block_size: int
+
+
+@dataclass
+class SlidingWindowSpec:
+    block_size: int
+    sliding_window: int
+
+
+@dataclass
+class SlidingWindowMLASpec(SlidingWindowSpec):
+    pass
+
+
+@dataclass
+class FullAttentionSpec:
+    block_size: int
+    sliding_window: "int | None" = None
+
+
+@dataclass
+class MLAAttentionSpec:
+    """Key-only, one-vector-per-token spec (an MLA index cache)."""
+
+    block_size: int
+
+
+@dataclass
+class UniformTypeKVCacheSpecs:
+    block_size: int
+    kv_cache_specs: "dict[str, object]" = field(default_factory=dict)
+
+
+@dataclass
+class MockKVCacheGroup:
+    layer_names: list[str]
+    kv_cache_spec: object
+
+
+@dataclass
+class MockKVCacheConfig:
+    kv_cache_groups: list[MockKVCacheGroup]
+
+
+def _same_shape_caches(names: list[str]) -> dict[str, torch.Tensor]:
+    return {n: torch.randn(2, 32, 16, 8, 64, dtype=torch.float16) for n in names}
+
+
+def _mla_caches(names: list[str]) -> dict[str, torch.Tensor]:
+    """Key-only rank-3 caches (num_blocks, block_size, head_size), MLA layout."""
+    return {n: torch.randn(32, 16, 128, dtype=torch.bfloat16) for n in names}
+
+
+def test_conversion_defaults_to_single_group_without_config():
+    """No vLLM KV cache groups -> all layers fall into a single engine group."""
+    spec = create_engine_group_infos_from_vllm(
+        None, _same_shape_caches(["layer.0", "layer.1"])
+    )
+
+    assert num_engine_groups(spec) == 1
+    assert [group.engine_group_id for group in spec] == [0]
+    assert spec[0].layer_indices == (0, 1)
+
+
+def test_conversion_preserves_engine_group_layers():
+    """Two engine groups with identical tensor shape stay separate by group."""
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(
+                    ["layer.0", "layer.2"], MockKVCacheSpec(block_size=16)
+                ),
+                MockKVCacheGroup(
+                    ["layer.1", "layer.3"], MockKVCacheSpec(block_size=16)
+                ),
+            ]
+        ),
+        _same_shape_caches(["layer.0", "layer.1", "layer.2", "layer.3"]),
+    )
+
+    assert num_engine_groups(spec) == 2
+    assert get_engine_group_indices(spec, 4) == [0, 1, 0, 1]
+    assert [group.tokens_per_block for group in spec] == [16, 16]
+
+
+def test_conversion_splits_by_lmcache_layer_identity():
+    """Layers split by both engine group and physical transfer identity."""
+    caches = _same_shape_caches(["layer.0", "layer.1", "layer.2", "layer.3"])
+    # layer.4 has a different head count -> distinct transfer identity.
+    caches["layer.4"] = torch.randn(2, 32, 16, 16, 64, dtype=torch.float16)
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(
+                    ["layer.0", "layer.2", "layer.4"], MockKVCacheSpec(block_size=16)
+                ),
+                MockKVCacheGroup(
+                    ["layer.1", "layer.3"], MockKVCacheSpec(block_size=16)
+                ),
+            ]
+        ),
+        caches,
+    )
+
+    assert [group.engine_group_id for group in spec] == [0, 1, 0]
+    assert [group.layer_indices for group in spec] == [(0, 2), (1, 3), (4,)]
+    assert expand_engine_block_ids(spec, [[10], [20]]) == [
+        [10],
+        [20],
+        [10],
+    ]
+
+
+def test_conversion_resolves_sliding_window_size():
+    """A SlidingWindowSpec group carries its window size in tokens;
+    subclasses count too."""
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(["layer.0"], FullAttentionSpec(block_size=16)),
+                MockKVCacheGroup(
+                    ["layer.1"], SlidingWindowSpec(block_size=16, sliding_window=64)
+                ),
+                MockKVCacheGroup(
+                    ["layer.2"],
+                    SlidingWindowMLASpec(block_size=16, sliding_window=128),
+                ),
+            ]
+        ),
+        _same_shape_caches(["layer.0", "layer.1", "layer.2"]),
+    )
+
+    assert [group.sw_size_tokens for group in spec] == [-1, 64, 128]
+
+
+def test_conversion_ignores_full_attention_sliding_window():
+    """SWA layers managed as full attention (hybrid allocator disabled) are
+    not sliding window: vLLM allocates blocks for all tokens."""
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(
+                    ["layer.0", "layer.1"],
+                    FullAttentionSpec(block_size=16, sliding_window=1024),
+                ),
+            ]
+        ),
+        _same_shape_caches(["layer.0", "layer.1"]),
+    )
+
+    assert [group.sw_size_tokens for group in spec] == [-1]
+
+
+def test_conversion_defaults_sliding_window_for_non_sw_spec():
+    """Groups whose spec is not a SlidingWindowSpec resolve to
+    non-sliding-window."""
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(["layer.0"], MockKVCacheSpec(block_size=16))
+            ]
+        ),
+        _same_shape_caches(["layer.0"]),
+    )
+
+    assert [group.sw_size_tokens for group in spec] == [-1]
+
+
+def test_conversion_uniform_type_specs_resolve_per_layer():
+    """Inside a UniformTypeKVCacheSpecs group, per-layer specs decide the
+    window. SW layers with a distinct transfer identity get their own group
+    carrying the window size."""
+    caches = _same_shape_caches(["layer.0", "layer.1"])
+    # layer.1 has a different head count -> distinct transfer identity.
+    caches["layer.1"] = torch.randn(2, 32, 16, 16, 64, dtype=torch.float16)
+    uniform_spec = UniformTypeKVCacheSpecs(
+        block_size=16,
+        kv_cache_specs={
+            "layer.0": FullAttentionSpec(block_size=16),
+            "layer.1": SlidingWindowSpec(block_size=16, sliding_window=512),
+        },
+    )
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[MockKVCacheGroup(["layer.0", "layer.1"], uniform_spec)]
+        ),
+        caches,
+    )
+
+    assert [group.layer_indices for group in spec] == [(0,), (1,)]
+    assert [group.sw_size_tokens for group in spec] == [-1, 512]
+
+
+def test_conversion_mixed_window_layers_in_one_group_rejected():
+    """Same-identity layers mixing different windows are inconsistent vLLM
+    metadata and fail loudly."""
+    uniform_spec = UniformTypeKVCacheSpecs(
+        block_size=16,
+        kv_cache_specs={
+            "layer.0": FullAttentionSpec(block_size=16),
+            "layer.1": SlidingWindowSpec(block_size=16, sliding_window=64),
+        },
+    )
+    with pytest.raises(ValueError, match="different sliding window sizes"):
+        create_engine_group_infos_from_vllm(
+            MockKVCacheConfig(
+                kv_cache_groups=[MockKVCacheGroup(["layer.0", "layer.1"], uniform_spec)]
+            ),
+            _same_shape_caches(["layer.0", "layer.1"]),
+        )
+
+
+def test_conversion_mixed_kv_and_mla_groups():
+    """Mixed-format shape: a K+V FullAttentionSpec group plus a key-only MLA index
+    group are detected per engine group and kept as separate LMCache groups with
+    the correct membership and per-group token packing."""
+    caches = {
+        **_same_shape_caches(["main.0", "main.1"]),
+        **_mla_caches(["idx.0", "idx.1"]),
+    }
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(
+                    ["main.0", "main.1"], FullAttentionSpec(block_size=16)
+                ),
+                MockKVCacheGroup(["idx.0", "idx.1"], MLAAttentionSpec(block_size=128)),
+            ]
+        ),
+        caches,
+    )
+
+    assert num_engine_groups(spec) == 2
+    assert [group.engine_group_id for group in spec] == [0, 1]
+    assert [group.layer_indices for group in spec] == [(0, 1), (2, 3)]
+    assert [group.tokens_per_block for group in spec] == [16, 128]
+
+
+def test_conversion_uniform_group_mixes_kv_and_mla_layouts():
+    """vLLM can coalesce a rank-5 K+V group and a rank-3 key-only indexer group
+    into ONE ``UniformTypeKVCacheSpecs`` group, not two. Detection must split it
+    by layout so the indexer gets the rank-3 format instead of inheriting the
+    K/V format; the two land in separate LMCache groups sharing one block-id
+    space."""
+    caches = {
+        **_same_shape_caches(["main.0", "main.1"]),  # rank-5 K+V
+        **_mla_caches(["idx.0", "idx.1"]),  # rank-3 indexer (key-only)
+    }
+    uniform_spec = UniformTypeKVCacheSpecs(
+        block_size=128,
+        kv_cache_specs={
+            "main.0": FullAttentionSpec(block_size=128),
+            "main.1": FullAttentionSpec(block_size=128),
+            "idx.0": MLAAttentionSpec(block_size=128),
+            "idx.1": MLAAttentionSpec(block_size=128),
+        },
+    )
+    spec = create_engine_group_infos_from_vllm(
+        MockKVCacheConfig(
+            kv_cache_groups=[
+                MockKVCacheGroup(["main.0", "main.1", "idx.0", "idx.1"], uniform_spec)
+            ]
+        ),
+        caches,
+    )
+
+    # One vLLM engine group, but two LMCache groups split by per-layer format.
+    assert num_engine_groups(spec) == 1
+    assert [group.engine_group_id for group in spec] == [0, 0]
+    assert [group.layer_indices for group in spec] == [(0, 1), (2, 3)]
+    # Both LMCache groups share the unified block-id space (tokens_per_block).
+    assert [group.tokens_per_block for group in spec] == [128, 128]
+
+
+def test_group_layers_by_identity_uses_per_layer_format():
+    """A per-layer Engine KV format gives the K+V layer kv_size=2 and the MLA
+    layer kv_size=1, splitting them into separate identities -- the per-group
+    distinction the single global format cannot express."""
+    # First Party
+    from lmcache.v1.kv_layer_groups import group_layers_by_identity
+    import lmcache.c_ops as lmc_ops
+
+    kv_caches = [
+        torch.randn(2, 32, 16, 8, 64, dtype=torch.bfloat16),  # K+V (rank-5)
+        torch.randn(32, 16, 128, dtype=torch.bfloat16),  # MLA key-only (rank-3)
+    ]
+    per_layer_format = [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    ]
+    groups = group_layers_by_identity(
+        kv_caches,
+        per_layer_format,
+        per_layer_engine_group_idx=[0, 1],
+    )
+
+    kv_size_by_group = {
+        identity.engine_group_idx: identity.kv_size for identity, _ in groups
+    }
+    num_heads_by_group = {
+        identity.engine_group_idx: identity.num_heads for identity, _ in groups
+    }
+    assert kv_size_by_group == {0: 2, 1: 1}
+    # The MLA group collapses heads to 1; the K+V group keeps its head count.
+    assert num_heads_by_group == {0: 8, 1: 1}
+
+
+def test_group_layers_by_identity_rejects_group_idx_length_mismatch():
+    """per_layer_engine_group_idx must hold one entry per layer."""
+    # First Party
+    from lmcache.v1.kv_layer_groups import group_layers_by_identity
+    import lmcache.c_ops as lmc_ops
+
+    kv_caches = [torch.randn(2, 32, 16, 8, 64, dtype=torch.bfloat16)]
+    # One layer (one format) but two engine-group ids.
+    with pytest.raises(ValueError, match="per_layer_engine_group_idx"):
+        group_layers_by_identity(
+            kv_caches,
+            [lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS],
+            per_layer_engine_group_idx=[0, 1],
+        )
diff --git a/tests/v1/test_vllm_layerwise_wait_for_save.py b/tests/v1/test_vllm_layerwise_wait_for_save.py
new file mode 100644
index 0000000..f7815d4
--- /dev/null
+++ b/tests/v1/test_vllm_layerwise_wait_for_save.py
@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: Apache-2.0
+
+# Standard
+from types import SimpleNamespace
+
+# Third Party
+import pytest
+import torch
+
+pytest.importorskip("vllm")
+
+# First Party
+from lmcache.integration.vllm.vllm_v1_adapter import (
+    LMCacheConnectorMetadata,
+    LMCacheConnectorV1Impl,
+    SaveSpec,
+)
+
+
+class _FakeParent:
+    def __init__(self, metadata):
+        self._connector_metadata = metadata
+
+    def _get_connector_metadata(self):
+        return self._connector_metadata
+
+
+class _FakeEngine:
+    def __init__(self):
+        self.unpinned: list[str] = []
+        self.store_steps: dict[str, int] = {}
+        self.store_calls: list[str] = []
+
+    def lookup_unpin(self, req_id: str) -> None:
+        self.unpinned.append(req_id)
+
+    def store_layer(self, token_ids, **kwargs):
+        req_id = kwargs["req_id"]
+        self.store_calls.append(req_id)
+        self.store_steps.setdefault(req_id, 0)
+
+        def _storer():
+            while True:
+                self.store_steps[req_id] += 1
+                yield None
+
+        return _storer()
+
+
+class _FakeManager:
+    def __init__(self, engine: _FakeEngine):
+        self.lmcache_engine = engine
+
+
+def _make_req(req_id: str, can_save: bool = True):
+    return SimpleNamespace(
+        req_id=req_id,
+        token_ids=[1, 2, 3, 4],
+        slot_mapping=torch.arange(4, dtype=torch.long),
+        save_spec=SaveSpec(skip_leading_tokens=0, can_save=can_save),
+    )
+
+
+def _make_connector(requests):
+    metadata = LMCacheConnectorMetadata(requests=requests)
+    engine = _FakeEngine()
+    connector = LMCacheConnectorV1Impl.__new__(LMCacheConnectorV1Impl)
+    connector._parent = _FakeParent(metadata)
+    connector._manager = _FakeManager(engine)
+    connector.kv_role = "kv_producer"
+    connector.use_layerwise = True
+    connector.device = "cpu"
+    connector._lmcache_chunk_size = 8
+    connector.kv_caches = {"layer0": torch.zeros(1)}
+    connector._layerwise_save_storers = {}
+    return connector, metadata, engine
+
+
+def test_layerwise_storer_is_request_scoped_across_interleaved_finalize() -> None:
+    connector, metadata, engine = _make_connector(
+        [_make_req("req-1"), _make_req("req-2")]
+    )
+
+    connector.save_kv_layer("layer0", torch.zeros(1), None)
+    assert engine.store_calls == ["req-1", "req-2"]
+    assert engine.store_steps["req-1"] == 1
+    assert engine.store_steps["req-2"] == 1
+
+    metadata.requests = [_make_req("req-1")]
+    connector.wait_for_save()
+    assert engine.store_steps["req-1"] == 2
+    assert engine.store_steps["req-2"] == 1
+    assert engine.unpinned == ["req-1"]
+    assert set(connector._layerwise_save_storers.keys()) == {"req-2"}
+
+    metadata.requests = [_make_req("req-2")]
+    connector.wait_for_save()
+    assert engine.store_steps["req-2"] == 2
+    assert engine.unpinned == ["req-1", "req-2"]
+    assert connector._layerwise_save_storers == {}
+
+
+def test_wait_for_save_repeated_call_does_not_readvance_finalized_storer() -> None:
+    connector, metadata, engine = _make_connector([_make_req("req-1")])
+    connector.save_kv_layer("layer0", torch.zeros(1), None)
+    assert engine.store_steps["req-1"] == 1
+
+    connector.wait_for_save()
+    assert engine.store_steps["req-1"] == 2
+    assert connector._layerwise_save_storers == {}
+
+    connector.wait_for_save()
+    assert engine.store_steps["req-1"] == 2
+
+
+def test_multi_layer_save_and_finalize() -> None:
+    connector, _, engine = _make_connector([_make_req("req-1"), _make_req("req-2")])
+    num_layers = 4
+
+    for _ in range(num_layers):
+        connector.save_kv_layer("layer_x", torch.zeros(1), None)
+
+    assert engine.store_steps["req-1"] == num_layers
+    assert engine.store_steps["req-2"] == num_layers
+
+    connector.wait_for_save()
+    assert engine.store_steps["req-1"] == num_layers + 1
+    assert engine.store_steps["req-2"] == num_layers + 1
+    assert connector._layerwise_save_storers == {}
+
+
+def test_layerwise_save_skips_requests_that_cannot_save() -> None:
+    connector, _, engine = _make_connector([_make_req("req-1", can_save=False)])
+    connector.kv_role = "kv_both"
+    connector.save_kv_layer("layer0", torch.zeros(1), None)
+    assert engine.store_calls == []
+    assert connector._layerwise_save_storers == {}
+
+
+def test_layerwise_save_kv_producer_ignores_can_save_flag() -> None:
+    connector, _, engine = _make_connector([_make_req("req-1", can_save=False)])
+
+    connector.save_kv_layer("layer0", torch.zeros(1), None)
+    assert engine.store_calls == ["req-1"]
+    assert engine.store_steps["req-1"] == 1
+    assert set(connector._layerwise_save_storers.keys()) == {"req-1"}
+
+    connector.wait_for_save()
+    assert engine.store_steps["req-1"] == 2
+    assert connector._layerwise_save_storers == {}
diff --git a/tests/v1/test_vllm_mp_adapter.py b/tests/v1/test_vllm_mp_adapter.py
new file mode 100644
index 0000000..372fa27
--- /dev/null
+++ b/tests/v1/test_vllm_mp_adapter.py
@@ -0,0 +1,750 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Public-API unit tests for ``LMCacheMPWorkerAdapter``. The MQ boundary is
+stubbed (see ``fake_adapter``); no GPU or live server needed. End-to-end
+recovery: ``.buildkite/k3_tests/multiprocess/scripts/run-restart-recovery.sh``."""
+
+# Standard
+from typing import Callable, ClassVar
+from unittest.mock import MagicMock
+import gc
+import os
+import threading
+import time
+import weakref
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.integration.vllm import vllm_multi_process_adapter as adapter_mod
+from lmcache.integration.vllm.vllm_multi_process_adapter import (
+    HeartbeatThread,
+    LMCacheMPWorkerAdapter,
+    LoadStoreOp,
+    ParallelStrategy,
+)
+from lmcache.v1.multiprocess.group_view import EngineGroupInfo
+from lmcache.v1.multiprocess.protocol import RequestType
+
+
+class FakeCudaEvent:
+    def ipc_handle(self) -> bytes:
+        return b"fake-ipc-handle"
+
+
+class FakeHeartbeatThread:
+    """Test double mirroring ``HeartbeatThread``'s public surface.
+    ``start()`` invokes class-level ``start_hook`` when set, otherwise
+    simulates a successful first ping. Class state reset per test."""
+
+    instances: ClassVar[list["FakeHeartbeatThread"]] = []
+    start_hook: ClassVar[Callable[["FakeHeartbeatThread"], None] | None] = None
+
+    def __init__(
+        self,
+        mq_client: object = None,
+        health_event: threading.Event | None = None,
+        interval: float = 0.0,
+        instance_id: int | None = None,
+    ) -> None:
+        self.mq_client = mq_client
+        self.health_event = (
+            health_event if health_event is not None else threading.Event()
+        )
+        self.interval = interval
+        self.instance_id = instance_id
+        # Snapshot of the health event at construction time: lets tests
+        # assert the adapter starts the heartbeat healthy (event still set).
+        self.health_event_set_at_init = self.health_event.is_set()
+        self.recover_callback: Callable[[], bool] | None = None
+        # Ordered record of public calls ("register_recover_callback",
+        # "start", "stop") for call-order assertions.
+        self.calls: list[str] = []
+        self.stop_requested = False
+        FakeHeartbeatThread.instances.append(self)
+
+    def register_recover_callback(self, callback: Callable[[], bool]) -> None:
+        self.calls.append("register_recover_callback")
+        self.recover_callback = callback
+
+    def start(self) -> None:
+        self.calls.append("start")
+        hook = FakeHeartbeatThread.start_hook
+        if hook is not None:
+            hook(self)
+        else:
+            self.simulate_successful_ping()
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self.calls.append("stop")
+        self.stop_requested = True
+
+    def simulate_successful_ping(self) -> None:
+        """Mimic one successful heartbeat cycle: on the unhealthy->healthy
+        edge the recover callback runs first, and the event is set only
+        when the callback returns ``True``."""
+        was_healthy = self.health_event.is_set()
+        ok = True
+        if not was_healthy and self.recover_callback is not None:
+            ok = self.recover_callback()
+        if ok:
+            self.health_event.set()
+
+
+def _make_worker_adapter(
+    extra_config: dict[str, object] | None = None,
+) -> LMCacheMPWorkerAdapter:
+    """Construct a worker adapter with the standard test arguments; the
+    network boundary must already be patched (see ``fake_adapter``).
+    ``extra_config`` forwards ``lmcache.mp.*`` overrides."""
+    parallel_strategy = ParallelStrategy(
+        use_mla=False,
+        vllm_world_size=1,
+        vllm_worker_id=0,
+        tp_size=1,
+        pp_size=1,
+        n_servers=1,
+    )
+    return LMCacheMPWorkerAdapter(
+        server_url="tcp://127.0.0.1:0",
+        context=MagicMock(name="zmq_context"),
+        model_name="test-model",
+        vllm_block_size=16,
+        parallel_strategy=parallel_strategy,
+        mq_timeout=5.0,
+        extra_config=extra_config,
+    )
+
+
+def _op(block_ids: list[list[int]]) -> LoadStoreOp:
+    """Build a minimal four-token ``LoadStoreOp`` over *block_ids*."""
+    return LoadStoreOp(token_ids=[1, 2, 3, 4], block_ids=block_ids, start=0, end=4)
+
+
+def _patch_transfer_context_factory(
+    monkeypatch: pytest.MonkeyPatch,
+) -> list[MagicMock]:
+    """Patch ``create_transfer_context`` to mint recorded MagicMocks,
+    returning the list every created context is appended to."""
+    contexts: list[MagicMock] = []
+
+    def fake_create_transfer_context(
+        kv_caches: dict[str, torch.Tensor], mode: str
+    ) -> MagicMock:
+        ctx = MagicMock(name=f"transfer_ctx_{len(contexts)}")
+        contexts.append(ctx)
+        return ctx
+
+    monkeypatch.setattr(
+        adapter_mod, "create_transfer_context", fake_create_transfer_context
+    )
+    return contexts
+
+
+@pytest.fixture
+def fake_adapter(monkeypatch):
+    """Build an adapter with the network boundary stubbed. Returns
+    ``(adapter, send_mock, future)``; ``future.result()`` defaults to succeed.
+    ``HeartbeatThread`` is replaced by ``FakeHeartbeatThread``."""
+    # Stub the MQ boundary so __init__'s chunk-size query and any later
+    # send_lmcache_request call don't touch a real socket.
+    fake_client = MagicMock(name="mq_client")
+    monkeypatch.setattr(adapter_mod, "MessageQueueClient", lambda *a, **kw: fake_client)
+    monkeypatch.setattr(adapter_mod, "get_lmcache_chunk_size", lambda *a, **kw: 256)
+
+    future = MagicMock(name="future")
+    future.result.return_value = None
+    send_mock = MagicMock(name="send_lmcache_request", return_value=future)
+    monkeypatch.setattr(adapter_mod, "send_lmcache_request", send_mock)
+
+    FakeHeartbeatThread.instances.clear()
+    FakeHeartbeatThread.start_hook = None
+    monkeypatch.setattr(adapter_mod, "HeartbeatThread", FakeHeartbeatThread)
+
+    # KV-cache wrapping pulls in CUDA IPC; bypass for unit tests.
+    monkeypatch.setattr(adapter_mod, "wrap_kv_caches", lambda kv: list(kv.values()))
+    # ``vllm_layout_hints`` returns a ``LayoutHints`` (TypedDict / dict at
+    # runtime); stub it with an empty dict.
+    monkeypatch.setattr(
+        "lmcache.integration.vllm.utils.vllm_layout_hints",
+        lambda: {},
+    )
+
+    adapter = _make_worker_adapter()
+    # __init__ issues exactly one MQ call (the chunk-size query). Reset
+    # so individual tests start with a clean call count.
+    send_mock.reset_mock()
+    return adapter, send_mock, future
+
+
+def test_register_kv_caches_updates_kv_caches_and_submits(fake_adapter):
+    """Public register_kv_caches stores the dict and submits one request."""
+    adapter, send_mock, _ = fake_adapter
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    new_caches = {"layer.0": fake_tensor, "layer.1": fake_tensor}
+
+    adapter.register_kv_caches(new_caches)
+
+    assert adapter.kv_caches is new_caches
+    assert send_mock.call_count == 1
+    args, _kwargs = send_mock.call_args
+    assert args[1] == RequestType.REGISTER_KV_CACHE
+
+
+def test_register_kv_caches_raises_connection_error_on_timeout(fake_adapter):
+    """Public register_kv_caches surfaces ConnectionError on MQ timeout."""
+    adapter, _send_mock, future = fake_adapter
+    future.result.side_effect = TimeoutError("server down")
+
+    with pytest.raises(ConnectionError, match="did not respond"):
+        fake_tensor = MagicMock()
+        fake_tensor.device.type = "cuda"
+        adapter.register_kv_caches({"layer.0": fake_tensor})
+
+
+def test_register_kv_caches_cpu_submits_engine_driven_context_registration(
+    fake_adapter, monkeypatch
+):
+    """CPU KV cache registration routes to REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT."""
+    adapter, send_mock, _ = fake_adapter
+    monkeypatch.setattr(
+        "lmcache.integration.vllm.utils.vllm_layout_hints",
+        lambda: {},
+        raising=False,
+    )
+    cpu_kv = {"layer.0": torch.randn(2, 8, 4, 2, 8)}
+
+    adapter.register_kv_caches(cpu_kv)
+
+    assert adapter.kv_caches is cpu_kv
+    assert send_mock.call_count == 1
+    args, _kwargs = send_mock.call_args
+    assert args[1] == RequestType.REGISTER_KV_CACHE_ENGINE_DRIVEN_CONTEXT
+    assert len(args[2]) == 1
+
+
+def test_submit_store_request_tracks_returned_future(fake_adapter, monkeypatch):
+    """submit_store_request stores the returned future in store_futures."""
+    adapter, _send_mock, _ = fake_adapter
+    monkeypatch.setattr(adapter, "_ensure_heartbeat_started", lambda: None)
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    adapter.kv_caches = {"layer.0": fake_tensor}
+    transfer_ctx = MagicMock()
+    fake_future = MagicMock()
+    transfer_ctx.submit_store.return_value = fake_future
+    adapter.transfer_ctx = transfer_ctx
+    op = LoadStoreOp(token_ids=[1, 2, 3, 4], block_ids=[[0]], start=0, end=4)
+
+    adapter.submit_store_request("req-1", op, event=MagicMock())
+
+    assert transfer_ctx.submit_store.called
+    assert transfer_ctx.submit_store.call_args.kwargs == {}
+    assert transfer_ctx.submit_store.call_args.args[4] == [[0]]
+    assert adapter.store_futures["req-1"] is fake_future
+
+
+def test_submit_store_request_expands_block_ids_to_views(fake_adapter, monkeypatch):
+    adapter, _send_mock, _ = fake_adapter
+    monkeypatch.setattr(adapter, "_ensure_heartbeat_started", lambda: None)
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    adapter.kv_caches = {"layer.0": fake_tensor}
+    adapter.engine_group_infos = [
+        EngineGroupInfo(0, (0, 2)),
+        EngineGroupInfo(0, (4,)),
+        EngineGroupInfo(1, (1, 3)),
+    ]
+    transfer_ctx = MagicMock()
+    fake_future = MagicMock()
+    transfer_ctx.submit_store.return_value = fake_future
+    adapter.transfer_ctx = transfer_ctx
+    op = LoadStoreOp(
+        token_ids=[1, 2, 3, 4],
+        block_ids=[[0, 1], [10, 11]],
+        start=0,
+        end=4,
+    )
+
+    adapter.submit_store_request("req-1", op, event=MagicMock())
+
+    assert transfer_ctx.submit_store.call_args.args[4] == [
+        [0, 1],
+        [0, 1],
+        [10, 11],
+    ]
+
+
+def test_submit_retrieve_request_tracks_returned_future(fake_adapter, monkeypatch):
+    """submit_retrieve_request stores returned future and block IDs."""
+    adapter, _send_mock, _ = fake_adapter
+    monkeypatch.setattr(adapter, "_ensure_heartbeat_started", lambda: None)
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    adapter.kv_caches = {"layer.0": fake_tensor}
+    transfer_ctx = MagicMock()
+    fake_future = MagicMock()
+    transfer_ctx.submit_retrieve.return_value = fake_future
+    adapter.transfer_ctx = transfer_ctx
+    op = LoadStoreOp(
+        token_ids=[1, 2, 3, 4],
+        block_ids=[[0]],
+        start=0,
+        end=4,
+        skip_first_n_tokens=1,
+    )
+
+    adapter.submit_retrieve_request("req-1", op, event=MagicMock())
+
+    assert transfer_ctx.submit_retrieve.called
+    assert transfer_ctx.submit_retrieve.call_args.kwargs == {"skip_first_n_tokens": 1}
+    assert transfer_ctx.submit_retrieve.call_args.args[4] == [[0]]
+    assert adapter.retrieve_futures["req-1"] == (fake_future, [0])
+
+
+def test_load_store_op_accepts_per_group_block_ids():
+    op = LoadStoreOp(
+        token_ids=[1, 2, 3, 4],
+        block_ids=[[0, 1], [10, 11]],
+        start=0,
+        end=4,
+    )
+
+    assert op.block_ids == [[0, 1], [10, 11]]
+    assert op.flat_block_ids == [0, 1, 10, 11]
+
+
+def test_store_keeps_event_until_future_finishes(fake_adapter):
+    """Store requests keep the exported CUDA event alive while pending."""
+    adapter, _send_mock, _future = fake_adapter
+    cuda_future = MagicMock(name="cuda_future")
+    cuda_future.query.return_value = False
+    transfer_ctx = MagicMock()
+    transfer_ctx.submit_store.return_value = cuda_future
+    adapter.transfer_ctx = transfer_ctx
+
+    event = FakeCudaEvent()
+    event_ref = weakref.ref(event)
+    op = LoadStoreOp(token_ids=[1, 2], block_ids=[[7]], start=0, end=2)
+
+    adapter.submit_store_request("req-1", op, event)
+    del event
+    gc.collect()
+    assert event_ref() is not None
+
+    cuda_future.query.return_value = True
+    cuda_future.result.return_value = True
+    finished_stores, finished_retrieves = adapter.get_finished({"req-1"})
+
+    assert finished_stores == {"req-1"}
+    assert finished_retrieves == set()
+    assert "req-1" not in adapter.store_events
+    transfer_ctx.reset_mock()
+    gc.collect()
+    assert event_ref() is None
+
+
+def test_retrieve_keeps_event_until_future_finishes(fake_adapter):
+    """Retrieve requests keep the exported CUDA event alive while pending."""
+    adapter, _send_mock, _future = fake_adapter
+    cuda_future = MagicMock(name="cuda_future")
+    cuda_future.query.return_value = False
+    transfer_ctx = MagicMock()
+    transfer_ctx.submit_retrieve.return_value = cuda_future
+    adapter.transfer_ctx = transfer_ctx
+
+    event = FakeCudaEvent()
+    event_ref = weakref.ref(event)
+    op = LoadStoreOp(token_ids=[1, 2], block_ids=[[7]], start=0, end=2)
+
+    adapter.submit_retrieve_request("req-1", op, event)
+    del event
+    gc.collect()
+    assert event_ref() is not None
+
+    cuda_future.query.return_value = True
+    cuda_future.result.return_value = True
+    finished_stores, finished_retrieves = adapter.get_finished(set())
+
+    assert finished_stores == set()
+    assert finished_retrieves == {"req-1"}
+    assert "req-1" not in adapter.retrieve_events
+    transfer_ctx.reset_mock()
+    gc.collect()
+    assert event_ref() is None
+
+
+def test_instance_id_is_uuid_derived_63_bit_int(fake_adapter) -> None:
+    """instance_id is a 63-bit int, not the PID, and unique per adapter."""
+    adapter, _send_mock, _ = fake_adapter
+
+    assert isinstance(adapter.instance_id, int)
+    assert not isinstance(adapter.instance_id, bool)
+    assert 0 <= adapter.instance_id < 2**63
+    assert adapter.instance_id != os.getpid()
+
+    other = _make_worker_adapter()
+    assert other.instance_id != adapter.instance_id
+
+
+def test_instance_id_logged_at_info_on_construction(fake_adapter, monkeypatch) -> None:
+    """The constructor logs instance_id at INFO for correlating server-side
+    reap warnings. The module logger does not propagate (``propagate=False``),
+    so the test spies on it directly instead of using ``caplog``."""
+    _adapter, _send_mock, _ = fake_adapter
+    messages: list[str] = []
+
+    def spy_info(msg: object, *args: object, **kwargs: object) -> None:
+        messages.append(str(msg) % args if args else str(msg))
+
+    monkeypatch.setattr(adapter_mod.logger, "info", spy_info)
+
+    adapter = _make_worker_adapter()
+
+    assert any(str(adapter.instance_id) in msg for msg in messages)
+
+
+def test_heartbeat_lazy_start_wires_callback_before_start(fake_adapter) -> None:
+    """The lazy create path starts the heartbeat healthy (no pessimistic
+    clear) and wires the recover callback before ``start()``; the first
+    store is not gated. Idempotent on re-entry (no second thread)."""
+    adapter, _send_mock, _ = fake_adapter
+    adapter.transfer_ctx = MagicMock()
+    assert adapter.is_healthy  # the constructor leaves the event set
+
+    adapter.submit_store_request("req-1", _op([[0]]), MagicMock())
+
+    assert len(FakeHeartbeatThread.instances) == 1
+    heartbeat = FakeHeartbeatThread.instances[0]
+    # Started healthy: the event was NOT cleared before construction, so
+    # the first store is not dropped.
+    assert heartbeat.health_event_set_at_init is True
+    # The recover callback is wired before start() (for genuine recovery).
+    assert heartbeat.calls == ["register_recover_callback", "start"]
+    assert adapter.is_healthy
+    assert adapter.transfer_ctx.submit_store.call_count == 1
+
+    # Re-entry is idempotent: no new thread.
+    adapter.submit_store_request("req-2", _op([[1]]), MagicMock())
+    assert len(FakeHeartbeatThread.instances) == 1
+    assert adapter.transfer_ctx.submit_store.call_count == 2
+
+
+def test_heartbeat_first_ping_runs_callback_before_setting_event(
+    monkeypatch,
+) -> None:
+    """Real HeartbeatThread: started with the health event cleared, the
+    first successful ping invokes the recover callback while the event
+    is still cleared, then sets the event."""
+    monkeypatch.setattr(
+        adapter_mod, "send_ping", lambda mq_client, timeout, instance_id=None: True
+    )
+    health_event = threading.Event()  # cleared: pessimistic start state
+    heartbeat = HeartbeatThread(
+        mq_client=MagicMock(name="mq_client"),
+        health_event=health_event,
+        interval=60.0,
+    )
+    event_state_during_callback: list[bool] = []
+
+    def recover() -> bool:
+        event_state_during_callback.append(health_event.is_set())
+        return True
+
+    heartbeat.register_recover_callback(recover)
+    try:
+        heartbeat.start()
+        assert health_event.wait(timeout=10.0)
+    finally:
+        heartbeat.stop(timeout=10.0)
+
+    assert event_state_during_callback == [False]
+
+
+def test_dropped_retrieve_reported_once_via_unhealthy_get_finished(
+    fake_adapter,
+) -> None:
+    """A retrieve submitted while unhealthy is dropped (blocks flagged,
+    nothing sent) and reported exactly once by the unhealthy branch of
+    ``get_finished``."""
+    adapter, _send_mock, _ = fake_adapter
+    transfer_ctx = MagicMock()
+    adapter.transfer_ctx = transfer_ctx
+    # Simulate a failed first ping: the heartbeat start clears the event.
+    FakeHeartbeatThread.start_hook = lambda hb: hb.health_event.clear()
+
+    adapter.submit_retrieve_request("req-1", _op([[3, 4]]), MagicMock())
+
+    assert not adapter.is_healthy
+    assert not transfer_ctx.submit_retrieve.called
+
+    ret_stores, finished_retrieves = adapter.get_finished(set())
+    assert ret_stores == set()
+    assert finished_retrieves == {"req-1"}
+    assert adapter.get_block_ids_with_load_errors() == {3, 4}
+
+    # Exactly once: a second poll must not re-report the request.
+    _ret_stores, finished_retrieves = adapter.get_finished(set())
+    assert finished_retrieves == set()
+
+
+def test_dropped_retrieve_reported_once_via_healthy_get_finished(
+    fake_adapter,
+) -> None:
+    """A retrieve dropped while unhealthy is still reported exactly once
+    by the healthy branch of ``get_finished`` after the server
+    recovers."""
+    adapter, _send_mock, _ = fake_adapter
+    adapter.transfer_ctx = MagicMock()
+    # Simulate a failed first ping: the heartbeat start clears the event.
+    FakeHeartbeatThread.start_hook = lambda hb: hb.health_event.clear()
+
+    adapter.submit_retrieve_request("req-1", _op([[5]]), MagicMock())
+    assert not adapter.is_healthy
+
+    # Server recovers: the next heartbeat cycle takes the edge.
+    FakeHeartbeatThread.instances[0].simulate_successful_ping()
+    assert adapter.is_healthy
+
+    _ret_stores, finished_retrieves = adapter.get_finished(set())
+    assert finished_retrieves == {"req-1"}
+    assert adapter.get_block_ids_with_load_errors() == {5}
+
+    _ret_stores, finished_retrieves = adapter.get_finished(set())
+    assert finished_retrieves == set()
+
+
+def test_shutdown_stops_heartbeat_before_unregister(fake_adapter) -> None:
+    """shutdown() stops the heartbeat before sending UNREGISTER, so no
+    stray heartbeat ping can race the closing mq_client."""
+    adapter, send_mock, future = fake_adapter
+    adapter.transfer_ctx = MagicMock()
+    adapter.submit_store_request("req-1", _op([[0]]), MagicMock())
+    heartbeat = FakeHeartbeatThread.instances[0]
+
+    stop_state_at_unregister: list[bool] = []
+
+    def record_send(
+        mq_client: object, request_type: RequestType, payloads: list[object]
+    ) -> MagicMock:
+        if request_type == RequestType.UNREGISTER_KV_CACHE:
+            stop_state_at_unregister.append(heartbeat.stop_requested)
+        return future
+
+    send_mock.side_effect = record_send
+
+    adapter.shutdown()
+
+    assert "stop" in heartbeat.calls
+    assert stop_state_at_unregister == [True]
+
+
+def test_shutdown_without_heartbeat_sends_unregister(fake_adapter) -> None:
+    """shutdown() on an adapter whose heartbeat was never lazily started
+    (cold shutdown before any traffic) still sends UNREGISTER and does
+    not raise."""
+    adapter, send_mock, _future = fake_adapter
+
+    adapter.shutdown()
+
+    assert FakeHeartbeatThread.instances == []
+    assert send_mock.call_count == 1
+    args, _kwargs = send_mock.call_args
+    assert args[1] == RequestType.UNREGISTER_KV_CACHE
+    assert args[2] == [adapter.instance_id]
+
+
+def test_straggler_cycle_after_stop_skips_callback_and_event(monkeypatch) -> None:
+    """Real HeartbeatThread: a ping still in flight when ``stop()`` returns
+    completes without firing the recover callback or setting the health
+    event — a straggler success must not re-register a ghost context."""
+    ping_entered = threading.Event()
+    release_ping = threading.Event()
+
+    def slow_ping(
+        mq_client: object, timeout: float, instance_id: int | None = None
+    ) -> bool:
+        ping_entered.set()
+        release_ping.wait(timeout=10.0)
+        return True
+
+    monkeypatch.setattr(adapter_mod, "send_ping", slow_ping)
+    health_event = threading.Event()  # cleared: a success would take the edge
+    heartbeat = HeartbeatThread(
+        mq_client=MagicMock(name="mq_client"),
+        health_event=health_event,
+        interval=60.0,
+    )
+    callback = MagicMock(name="recover_callback", return_value=True)
+    heartbeat.register_recover_callback(callback)
+
+    heartbeat.start()
+    assert ping_entered.wait(timeout=10.0)
+    # The join times out while the ping is still in flight.
+    heartbeat.stop(timeout=0.05)
+    release_ping.set()
+
+    # Wait for the straggler cycle to complete.
+    deadline = time.time() + 10.0
+    while heartbeat.total_runs == 0 and time.time() < deadline:
+        time.sleep(0.01)
+
+    assert heartbeat.total_runs == 1
+    callback.assert_not_called()
+    assert not health_event.is_set()
+
+
+def test_recover_callback_skips_register_after_stop_requested(
+    fake_adapter, monkeypatch
+) -> None:
+    """A recover callback that observes a requested stop bails out before
+    submitting REGISTER: a REGISTER submitted after UNREGISTER would
+    re-create a ghost server-side context."""
+    adapter, _send_mock, _ = fake_adapter
+    contexts = _patch_transfer_context_factory(monkeypatch)
+
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    adapter.register_kv_caches({"layer.0": fake_tensor})
+    adapter.submit_store_request("req-1", _op([[0]]), MagicMock())
+    heartbeat = FakeHeartbeatThread.instances[0]
+    assert heartbeat.recover_callback is not None
+    rebuilds_before = len(contexts)
+
+    # Simulate a stop landing while a recovery cycle is in flight: the
+    # pre-submission re-check must refuse to re-register.
+    heartbeat.stop()
+    assert heartbeat.recover_callback() is False
+
+    assert len(contexts) == rebuilds_before  # no new transfer context
+    assert contexts[-1].register.call_count == 1  # no second REGISTER
+
+
+def test_register_uses_local_context_when_self_transfer_ctx_nulled(
+    monkeypatch,
+) -> None:
+    """register must call register() on the local context, not re-read
+    self.transfer_ctx: a concurrent shutdown() can null the attribute
+    between publish and the call, which previously raised AttributeError."""
+
+    class _NullingTransferCtxAdapter(LMCacheMPWorkerAdapter):
+        # Models self.transfer_ctx already nulled by a racing shutdown():
+        # the getter always reports None, so any code re-reading the
+        # attribute (rather than the local) hits None.register.
+        @property
+        def transfer_ctx(self):
+            return None
+
+        @transfer_ctx.setter
+        def transfer_ctx(self, value):
+            pass
+
+    fake_client = MagicMock(name="mq_client")
+    monkeypatch.setattr(adapter_mod, "MessageQueueClient", lambda *a, **kw: fake_client)
+    monkeypatch.setattr(adapter_mod, "get_lmcache_chunk_size", lambda *a, **kw: 256)
+    future = MagicMock(name="future")
+    future.result.return_value = None
+    monkeypatch.setattr(adapter_mod, "send_lmcache_request", lambda *a, **kw: future)
+    monkeypatch.setattr(adapter_mod, "HeartbeatThread", FakeHeartbeatThread)
+    monkeypatch.setattr(adapter_mod, "wrap_kv_caches", lambda kv: list(kv.values()))
+    monkeypatch.setattr("lmcache.integration.vllm.utils.vllm_layout_hints", lambda: {})
+    local_ctx = MagicMock(name="local_transfer_ctx")
+    monkeypatch.setattr(
+        adapter_mod, "create_transfer_context", lambda kv, mode: local_ctx
+    )
+
+    parallel_strategy = ParallelStrategy(
+        use_mla=False,
+        vllm_world_size=1,
+        vllm_worker_id=0,
+        tp_size=1,
+        pp_size=1,
+        n_servers=1,
+    )
+    adapter = _NullingTransferCtxAdapter(
+        server_url="tcp://127.0.0.1:0",
+        context=MagicMock(name="zmq_context"),
+        model_name="test-model",
+        vllm_block_size=16,
+        parallel_strategy=parallel_strategy,
+        mq_timeout=5.0,
+    )
+
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    # Under the bug this raises AttributeError (None.register).
+    adapter.register_kv_caches({"layer.0": fake_tensor})
+
+    local_ctx.register.assert_called_once()
+
+
+def test_startup_warns_when_heartbeat_interval_exceeds_reap_floor(
+    fake_adapter, monkeypatch
+) -> None:
+    """3 x heartbeat_interval > 30 s emits a startup WARNING to raise the
+    server's worker reap timeout. The module logger does not propagate
+    (``propagate=False``), so the test spies on it instead of ``caplog``."""
+    _adapter, _send_mock, _ = fake_adapter
+    warnings: list[str] = []
+    monkeypatch.setattr(
+        adapter_mod.logger,
+        "warning",
+        lambda msg, *args, **kwargs: warnings.append(str(msg)),
+    )
+
+    _make_worker_adapter(extra_config={"lmcache.mp.heartbeat_interval": 15})
+
+    assert any("reap" in msg for msg in warnings)
+
+
+def test_startup_does_not_warn_for_default_heartbeat_interval(
+    fake_adapter, monkeypatch
+) -> None:
+    """The default 10 s heartbeat interval (3 x 10 s == 30 s floor) must
+    not emit the reap-timeout startup WARNING."""
+    _adapter, _send_mock, _ = fake_adapter
+    warnings: list[str] = []
+    monkeypatch.setattr(
+        adapter_mod.logger,
+        "warning",
+        lambda msg, *args, **kwargs: warnings.append(str(msg)),
+    )
+
+    _make_worker_adapter()
+
+    assert not any("reap" in msg for msg in warnings)
+
+
+def test_recover_callback_rebuilds_transfer_ctx_without_closing_previous(
+    fake_adapter, monkeypatch
+) -> None:
+    """Pin current behavior: every recover-callback invocation rebuilds
+    ``transfer_ctx`` without closing the previous context (known IPC leak;
+    in-flight submissions may still hold a reference to the old context)."""
+    adapter, _send_mock, _ = fake_adapter
+    contexts = _patch_transfer_context_factory(monkeypatch)
+
+    fake_tensor = MagicMock()
+    fake_tensor.device.type = "cuda"
+    adapter.register_kv_caches({"layer.0": fake_tensor})  # contexts[0]
+    # Start the heartbeat (healthy, no recover) so the callback is wired.
+    adapter.submit_store_request("req-1", _op([[0]]), MagicMock())
+    heartbeat = FakeHeartbeatThread.instances[0]
+    assert heartbeat.recover_callback is not None
+    assert len(contexts) == 1
+    assert adapter.transfer_ctx is contexts[0]
+
+    # Each recover-callback invocation rebuilds transfer_ctx without closing
+    # the previous context (known IPC leak; in-flight submissions may still
+    # hold a reference to the old context).
+    assert heartbeat.recover_callback() is True
+    assert len(contexts) == 2
+    assert adapter.transfer_ctx is contexts[1]
+    contexts[0].close.assert_not_called()
+
+    assert heartbeat.recover_callback() is True
+    assert len(contexts) == 3
+    assert adapter.transfer_ctx is contexts[2]
+    contexts[1].close.assert_not_called()
diff --git a/tests/v1/test_xpu_connector.py b/tests/v1/test_xpu_connector.py
new file mode 100644
index 0000000..bb823c8
--- /dev/null
+++ b/tests/v1/test_xpu_connector.py
@@ -0,0 +1,838 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from contextlib import nullcontext
+from unittest.mock import patch
+import random
+import threading
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector.utils import get_dtype
+from lmcache.v1.gpu_connector.xpu_connectors import (
+    VLLMBufferLayerwiseXPUConnector,
+    VLLMPagedMemLayerwiseXPUConnector,
+    VLLMPagedMemXPUConnectorV2,
+    VLLMPagedMemXPUConnectorV3,
+)
+from lmcache.v1.memory_allocators.gpu_memory_allocator import GPUMemoryAllocator
+from lmcache.v1.memory_allocators.paged_tensor_memory_allocator import (
+    PagedTensorMemoryAllocator,
+)
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.memory_allocators.tensor_memory_allocator import TensorMemoryAllocator
+from lmcache.v1.memory_management import MemoryFormat
+from lmcache.v1.metadata import LMCacheMetadata
+
+if torch.xpu.is_available():
+    try:
+        # First Party
+        import lmcache.c_ops as lmc_ops
+    except ImportError:
+        lmc_ops = None
+else:
+    lmc_ops = None
+
+# Mock c_ops when not available
+if lmc_ops is None:
+
+    class MockEngineKVFormat:
+        NL_X_TWO_NB_BS_NH_HS = 0
+        NL_X_NB_TWO_BS_NH_HS = 1
+        NL_X_NB_BS_HS = 2
+
+    class MockCOps:
+        EngineKVFormat = MockEngineKVFormat
+        GPUKVFormat = MockEngineKVFormat
+
+    lmc_ops = MockCOps()
+
+# Local
+from .utils import (
+    check_paged_kv_cache_equal,
+    check_paged_kv_cache_equal_with_mla,
+    generate_kv_cache_paged_list_tensors,
+    recover_gpu_connector_states,
+)
+
+
+@pytest.fixture(autouse=True, scope="module")
+def patch_pin_allocator():
+    def fake_pin_init(self, size: int, use_paging: bool = False, **kwargs):
+        """
+        :param int size: The size of the pinned memory in bytes.
+        """
+
+        self._unregistered = False
+        self.buffer = torch.empty(size, dtype=torch.uint8, pin_memory=True)
+
+        if use_paging:
+            assert "shapes" in kwargs, (
+                "shapes must be specified for paged memory allocator"
+            )
+            assert "dtypes" in kwargs, (
+                "dtypes must be specified for paged memory allocator"
+            )
+            assert "fmt" in kwargs, "fmt must be specified for paged memory allocator"
+            self.allocator = PagedTensorMemoryAllocator(
+                tensor=self.buffer,
+                shapes=kwargs["shapes"],
+                dtypes=kwargs["dtypes"],
+                fmt=kwargs["fmt"],
+            )
+        else:
+            self.allocator = TensorMemoryAllocator(self.buffer)
+
+        self.host_mem_lock = threading.Lock() if not use_paging else nullcontext()
+
+    def fake_pin_close(self):
+        if not self._unregistered:
+            torch.xpu.synchronize()
+            self._unregistered = True
+
+    with (
+        patch(
+            "lmcache.v1.memory_allocators.pin_memory_allocator.PinMemoryAllocator.__init__",
+            fake_pin_init,
+        ),
+        patch(
+            "lmcache.v1.memory_allocators.pin_memory_allocator.PinMemoryAllocator.close",
+            fake_pin_close,
+        ),
+    ):
+        yield
+
+
+@pytest.mark.parametrize("use_gpu", [True, False])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    ],  # vllm MLA
+)
+@pytest.mark.skipif(
+    not torch.xpu.is_available(),
+    reason="TODO: Add non-XPU implementation to VLLMPagedMemXPUConnectorV2",
+)
+def test_vllm_paged_connector_v2_with_gpu_and_mla(use_gpu, engine_kv_format):
+    use_mla = engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 1 if use_mla else 8
+    head_size = 128
+    device = "xpu"
+    hidden_dim = num_heads * head_size
+
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    dtype = get_dtype(gpu_kv_src, engine_kv_format)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        if use_mla:
+            check_paged_kv_cache_equal_with_mla(
+                gpu_kv_src, gpu_kv_dst, slot_mapping, head_size
+            )
+        else:
+            check_paged_kv_cache_equal(
+                gpu_kv_src,
+                gpu_kv_dst,
+                slot_mapping,
+                num_heads,
+                head_size,
+                engine_kv_format,
+            )
+
+    connector = VLLMPagedMemXPUConnectorV2(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+    connector2 = VLLMPagedMemXPUConnectorV2(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+        use_mla=use_mla,
+    )
+    assert connector.use_mla == use_mla
+    assert connector2.use_mla == use_mla
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape = connector.get_shape(end - start)
+        memory_obj = allocator.allocate(shape, dtype)
+        connector.from_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=gpu_kv_src,
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        recover_gpu_connector_states(connector)
+        if use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+        connector2.to_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=gpu_kv_dst,
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        allocator.free(memory_obj)
+        assert allocator.memcheck()
+
+    if use_mla:
+        check_paged_kv_cache_equal_with_mla(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, head_size
+        )
+    else:
+        check_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size, engine_kv_format
+        )
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True, False])
+@pytest.mark.parametrize("num_groups", [1, 2, 3])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+        lmc_ops.EngineKVFormat.NL_X_NB_BS_HS,
+    ],  # vllm MLA
+)
+@pytest.mark.skipif(
+    not torch.xpu.is_available(),
+    reason="TODO: Add non-XPU implementation to VLLMPagedMemXPUConnectorV3",
+)
+def test_vllm_paged_connector_v3_with_gpu_and_mla(
+    use_gpu, num_groups, engine_kv_format
+):
+    use_mla = engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    head_sizes = [64, 66, 66]
+    dtypes = [torch.uint8, torch.bfloat16, torch.uint8]
+    num_blocks = 100
+    block_size = 16
+    num_heads = 1 if use_mla else 8
+    device = "xpu"
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    # generate kv cache tensors
+    src_kv_groups: list[list] = []
+    dst_kv_groups: list[list] = []
+    src_kv_caches: dict[str, torch.Tensor] = {}
+    dst_kv_caches: dict[str, torch.Tensor] = {}
+    for i in range(num_groups):
+        for groups, kv_caches in [
+            (src_kv_groups, src_kv_caches),
+            (dst_kv_groups, dst_kv_caches),
+        ]:
+            kv_group = generate_kv_cache_paged_list_tensors(
+                num_blocks=num_blocks,
+                device=device,
+                block_size=block_size,
+                dtype=dtypes[i],
+                num_layers=8,
+                head_size=head_sizes[i],
+                engine_kv_format=engine_kv_format,
+            )
+            groups.append(kv_group)
+            for j, layer_tensor in enumerate(kv_group):
+                kv_caches[f"{i}-{j}"] = layer_tensor
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the kv group is not the same before copying
+    with pytest.raises(AssertionError):
+        for i in range(num_groups):
+            if use_mla:
+                check_paged_kv_cache_equal_with_mla(
+                    src_kv_groups[i], dst_kv_groups[i], slot_mapping, head_sizes[i]
+                )
+            else:
+                check_paged_kv_cache_equal(
+                    src_kv_groups[i],
+                    dst_kv_groups[i],
+                    slot_mapping,
+                    num_heads,
+                    head_sizes[i],
+                    engine_kv_format,
+                )
+
+    # create metadata and init kv layer groups
+    metadata = _create_metadata(use_mla, src_kv_caches, engine_kv_format)
+    metadata2 = _create_metadata(use_mla, dst_kv_caches, engine_kv_format)
+
+    # connector will copy with src_kv_groups
+    connector = VLLMPagedMemXPUConnectorV3(
+        metadata=metadata,
+        use_gpu=use_gpu,
+        device=slot_mapping.device,
+    )
+    # connector2 will copy with dst_kv_groups
+    connector2 = VLLMPagedMemXPUConnectorV3(
+        metadata=metadata2,
+        use_gpu=use_gpu,
+        device=slot_mapping.device,
+    )
+    assert connector.use_mla == use_mla
+    assert connector2.use_mla == use_mla
+
+    # copy from src_kv_groups to memory_obj,
+    # and then copy from memory_obj to dst_kv_groups
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        memory_obj = allocator.allocate(
+            metadata.get_shapes(end - start), metadata.get_dtypes()
+        )
+        connector.from_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=list(src_kv_caches.values()),
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        if use_mla:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_MLA_FMT
+        else:
+            assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+        connector2.to_gpu(
+            memory_obj,
+            start,
+            end,
+            kvcaches=list(dst_kv_caches.values()),
+            slot_mapping=slot_mapping,
+            offset=0,
+        )
+        allocator.free(memory_obj)
+        assert allocator.memcheck()
+
+    # Check the kv group is same after copying
+    for i in range(num_groups):
+        if use_mla:
+            check_paged_kv_cache_equal_with_mla(
+                src_kv_groups[i], dst_kv_groups[i], slot_mapping, head_sizes[i]
+            )
+        else:
+            check_paged_kv_cache_equal(
+                src_kv_groups[i],
+                dst_kv_groups[i],
+                slot_mapping,
+                num_heads,
+                head_sizes[i],
+                engine_kv_format,
+            )
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.parametrize(
+    "engine_kv_format",
+    [
+        lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,  # vllm non-MLA flash attention
+        lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS,  # vllm non-MLA flash infer
+    ],
+)
+@pytest.mark.skipif(
+    not torch.xpu.is_available(),
+    reason="TODO: Add non-XPU implementation to VLLMPagedMemLayerwiseXPUConnector",
+)
+def test_layerwise_vllm_paged_connector_with_gpu(use_gpu, engine_kv_format):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "xpu"
+    hidden_dim = num_heads * head_size
+
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(
+        num_blocks=num_blocks,
+        device=device,
+        block_size=block_size,
+        engine_kv_format=engine_kv_format,
+    )
+    dtype = get_dtype(gpu_kv_src, engine_kv_format)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size, engine_kv_format
+        )
+
+    connector = VLLMPagedMemLayerwiseXPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+    )
+
+    # from gpu to cpu
+    starts = []
+    ends = []
+    memory_objs = []
+
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_T2D
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts.append(start)
+        ends.append(end)
+        memory_objs.append(memory_objs_multi_layer)
+
+    memory_objs = [list(row) for row in zip(*memory_objs, strict=False)]
+
+    mem_obj_generator = connector.batched_from_gpu(
+        memory_objs,
+        starts,
+        ends,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping,
+        sync=True,
+    )
+
+    for layer_id in range(num_layers + 1):
+        next(mem_obj_generator)
+
+    # from cpu to gpu
+    mem_obj_consumer = connector.batched_to_gpu(
+        starts,
+        ends,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping,
+        sync=True,
+    )
+    next(mem_obj_consumer)
+    for layer_id in range(num_layers):
+        mem_obj_consumer.send(memory_objs[layer_id])
+    next(mem_obj_consumer)
+
+    # free all mem objs
+    for mem_obj_multi_layer in memory_objs:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    assert allocator.memcheck()
+
+    assert connector.gpu_buffer_allocator.memcheck()
+
+    check_paged_kv_cache_equal(
+        gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size, engine_kv_format
+    )
+
+    allocator.close()
+
+
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.skipif(
+    not torch.xpu.is_available(),
+    reason="TODO: Add non-XPU implementation to VLLMPagedMemLayerwiseXPUConnector",
+)
+def test_batched_layerwise_vllm_paged_connector_with_gpu(use_gpu):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "xpu"
+    hidden_dim = num_heads * head_size
+
+    num_tokens_1 = 800
+    num_tokens_2 = 500
+    num_tokens_total = num_tokens_1 + num_tokens_2
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    dtype = gpu_kv_src[0][0].dtype
+
+    slot_mapping_total = random.sample(
+        range(0, num_blocks * block_size), num_tokens_total
+    )
+    slot_mapping_total = torch.tensor(
+        slot_mapping_total, device=device, dtype=torch.int64
+    )
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(gpu_kv_src, gpu_kv_dst, slot_mapping_total)
+
+    connector = VLLMPagedMemLayerwiseXPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        chunk_size=chunk_size,
+        dtype=dtype,
+        device=device,
+    )
+
+    # from gpu to cpu
+    starts_1 = []
+    ends_1 = []
+    memory_objs_1 = []
+
+    for start in range(0, num_tokens_1, chunk_size):
+        end = min(start + chunk_size, num_tokens_1)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_T2D
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts_1.append(start)
+        ends_1.append(end)
+        memory_objs_1.append(memory_objs_multi_layer)
+
+    memory_objs_1 = [list(row) for row in zip(*memory_objs_1, strict=False)]
+
+    starts_2 = []
+    ends_2 = []
+    memory_objs_2 = []
+    for start in range(num_tokens_1, num_tokens_total, chunk_size):
+        end = min(start + chunk_size, num_tokens_total)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_T2D
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts_2.append(start)
+        ends_2.append(end)
+        memory_objs_2.append(memory_objs_multi_layer)
+
+    memory_objs_2 = [list(row) for row in zip(*memory_objs_2, strict=False)]
+
+    mem_obj_generator_1 = connector.batched_from_gpu(
+        memory_objs_1,
+        starts_1,
+        ends_1,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping_total,
+        sync=True,
+    )
+
+    mem_obj_generator_1 = connector.batched_from_gpu(
+        memory_objs_1,
+        starts_1,
+        ends_1,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping_total,
+        sync=True,
+    )
+
+    mem_obj_generator_2 = connector.batched_from_gpu(
+        memory_objs_2,
+        starts_2,
+        ends_2,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping_total,
+        sync=False,
+    )
+
+    for layer_id in range(num_layers + 1):
+        next(mem_obj_generator_1)
+        next(mem_obj_generator_2)
+
+    # from cpu to gpu
+    mem_obj_consumer_1 = connector.batched_to_gpu(
+        starts_1,
+        ends_1,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping_total,
+        sync=False,
+    )
+    mem_obj_consumer_2 = connector.batched_to_gpu(
+        starts_2,
+        ends_2,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping_total,
+        sync=True,
+    )
+
+    next(mem_obj_consumer_1)
+    next(mem_obj_consumer_2)
+    for layer_id in range(num_layers):
+        mem_obj_consumer_1.send(memory_objs_1[layer_id])
+        mem_obj_consumer_2.send(memory_objs_2[layer_id])
+    next(mem_obj_consumer_1)
+    next(mem_obj_consumer_2)
+
+    # free all mem objs
+    for mem_obj_multi_layer in memory_objs_1:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    for mem_obj_multi_layer in memory_objs_2:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    assert allocator.memcheck()
+
+    assert connector.gpu_buffer_allocator.memcheck()
+
+    check_paged_kv_cache_equal(
+        gpu_kv_src,
+        gpu_kv_dst,
+        slot_mapping_total,
+        num_heads,
+        head_size,
+    )
+
+    allocator.close()
+
+
+@pytest.mark.skip(reason="This test is skipped due to vllm dependency")
+@pytest.mark.parametrize("use_gpu", [True])
+@pytest.mark.skipif(
+    not torch.xpu.is_available(),
+    reason="TODO: Add non-XPU implementation to VLLMBufferLayerwiseXPUConnector",
+)
+def test_layerwise_vllm_buffer_connector_with_gpu(use_gpu):
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "xpu"
+    hidden_dim = num_heads * head_size
+
+    num_tokens = 800
+    chunk_size = 256
+
+    allocator = PinMemoryAllocator(1024 * 1024 * 1024)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    dtype = gpu_kv_src[0][0].dtype
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), num_tokens)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    # Check the gpu_kv is not the same before copying
+    with pytest.raises(AssertionError):
+        check_paged_kv_cache_equal(
+            gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size
+        )
+
+    connector = VLLMBufferLayerwiseXPUConnector(
+        hidden_dim,
+        num_layers,
+        use_gpu=use_gpu,
+        dtype=dtype,
+        device=device,
+    )
+
+    # from gpu to cpu
+    starts = []
+    ends = []
+    memory_objs = []
+
+    for start in range(0, num_tokens, chunk_size):
+        end = min(start + chunk_size, num_tokens)
+        shape_single_layer = connector.get_shape(end - start)
+        memory_objs_multi_layer = []
+
+        for layer_id in range(num_layers):
+            mem_obj_single_layer = allocator.allocate(
+                shape_single_layer, dtype, fmt=MemoryFormat.KV_2TD
+            )
+            memory_objs_multi_layer.append(mem_obj_single_layer)
+
+        starts.append(start)
+        ends.append(end)
+        memory_objs.append(memory_objs_multi_layer)
+
+    memory_objs = [list(row) for row in zip(*memory_objs, strict=False)]
+
+    mem_obj_generator = connector.batched_from_gpu(
+        memory_objs,
+        starts,
+        ends,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping,
+    )
+
+    for layer_id in range(num_layers + 1):
+        next(mem_obj_generator)
+
+    # from cpu to gpu
+    mem_obj_consumer = connector.batched_to_gpu(
+        starts,
+        ends,
+        kvcaches=gpu_kv_dst,
+        slot_mapping=slot_mapping,
+    )
+    next(mem_obj_consumer)
+    for layer_id in range(num_layers):
+        mem_obj_consumer.send(memory_objs[layer_id])
+    next(mem_obj_consumer)
+
+    # free all mem objs
+    for mem_obj_multi_layer in memory_objs:
+        for mem_obj in mem_obj_multi_layer:
+            mem_obj.ref_count_down()
+
+    assert allocator.memcheck()
+
+    assert connector.gpu_buffer_allocator.memcheck()
+
+    check_paged_kv_cache_equal(
+        gpu_kv_src, gpu_kv_dst, slot_mapping, num_heads, head_size
+    )
+
+    allocator.close()
+
+
+@pytest.mark.skipif(
+    not torch.xpu.is_available(),
+    reason="TODO: Add non-XPU implementation to VLLMPagedMemXPUConnectorV2",
+)
+def test_vllm_paged_connector_v2_to_gpu_bench(benchmark):
+    """
+    VLLMPagedMemXPUConnectorV2.to_gpu() micro-benchmark.
+
+    This test is to measure the performance of
+    VLLMPagedMemXPUConnectorV2.to_gpu() when both KV caches and
+    memobject are on GPU.
+
+    """
+    num_blocks = 100
+    block_size = 16
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    device = "xpu"
+    hidden_dim = num_heads * head_size
+
+    chunk_size = 256
+
+    allocator = GPUMemoryAllocator(1024 * 1024 * 1024, device)
+
+    gpu_kv_src = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+    gpu_kv_dst = generate_kv_cache_paged_list_tensors(num_blocks, device, block_size)
+
+    slot_mapping = random.sample(range(0, num_blocks * block_size), chunk_size)
+    slot_mapping = torch.tensor(slot_mapping, device=device, dtype=torch.int64)
+
+    connector = VLLMPagedMemXPUConnectorV2(hidden_dim, num_layers)
+    shape = connector.get_shape(chunk_size)
+    memory_obj = allocator.allocate(shape, gpu_kv_src[0][0].dtype)
+    connector.from_gpu(
+        memory_obj,
+        0,
+        chunk_size,
+        kvcaches=gpu_kv_src,
+        slot_mapping=slot_mapping,
+        offset=0,
+    )
+    recover_gpu_connector_states(connector)
+    assert memory_obj.metadata.fmt == MemoryFormat.KV_2LTD
+    benchmark.pedantic(
+        connector.to_gpu,
+        args=(memory_obj, 0, chunk_size),
+        kwargs={
+            "kvcaches": gpu_kv_dst,
+            "slot_mapping": slot_mapping,
+            "offset": 0,
+        },
+        rounds=100,
+        iterations=1000,
+        warmup_rounds=10,
+    )
+    allocator.free(memory_obj)
+    assert allocator.memcheck()
+
+    allocator.close()
+
+
+def _create_metadata(use_mla, kv_caches, engine_kv_format):
+    # First Party
+    from lmcache.v1.kv_layer_groups import KVLayerGroupsManager
+
+    num_heads = 1 if use_mla else 8
+    metadata = LMCacheMetadata(
+        model_name="test",
+        world_size=8,
+        local_world_size=8,
+        worker_id=0,
+        local_worker_id=0,
+        kv_dtype=torch.bfloat16,
+        kv_shape=(32, 2, 256, num_heads, 128),
+        use_mla=use_mla,
+    )
+    kv_list = list(kv_caches.values())
+    metadata.kv_layer_groups_manager = KVLayerGroupsManager(
+        kv_list,
+        engine_kv_formats=[engine_kv_format] * len(kv_list),
+    )
+    return metadata
diff --git a/tests/v1/test_xpu_sglang_connector.py b/tests/v1/test_xpu_sglang_connector.py
new file mode 100644
index 0000000..fab42c4
--- /dev/null
+++ b/tests/v1/test_xpu_sglang_connector.py
@@ -0,0 +1,899 @@
+# SPDX-License-Identifier: Apache-2.0
+# tests/v1/test_xpu_sglang_connector.py
+#
+# Unit tests for SGLang XPU connectors (SGLangXPUConnector and
+# SGLangLayerwiseXPUConnector). Mirrors the structure of
+# test_xpu_connector.py which covers the vLLM XPU connectors.
+
+# Third Party
+import pytest
+import torch
+
+# First Party
+from lmcache.v1.gpu_connector import xpu_connectors
+from lmcache.v1.gpu_connector.xpu_connectors import (
+    SGLangLayerwiseXPUConnector,
+    SGLangXPUConnector,
+)
+from lmcache.v1.memory_allocators.pin_memory_allocator import PinMemoryAllocator
+from lmcache.v1.memory_management import MemoryFormat
+from tests.v1.utils import (
+    check_paged_kv_cache_equal_with_mla,
+    check_sglang_paged_kv_cache_equal,
+    generate_sglang_kv_cache_paged_list_tensors,
+)
+
+
+def _skip_if_no_xpu():
+    if not hasattr(torch, "xpu") or not torch.xpu.is_available():
+        pytest.skip("torch.xpu is not available")
+
+
+def _make_unique_slot_mapping(
+    *, total_slots: int, num_tokens: int, device: torch.device
+) -> torch.Tensor:
+    return torch.randperm(total_slots, device=device, dtype=torch.int64)[:num_tokens]
+
+
+def _pack_slot_mapping(
+    slot_mapping: torch.Tensor, starts: list[int], ends: list[int]
+) -> torch.Tensor:
+    return torch.cat(
+        [slot_mapping[s:e] for s, e in zip(starts, ends, strict=False)],
+        dim=0,
+    )
+
+
+def _check_kv_equal(
+    kvcaches_src, kvcaches_dst, slot_mapping, num_heads, head_size, use_mla
+):
+    """Dispatch to the correct comparison helper based on MLA mode."""
+    if use_mla:
+        check_paged_kv_cache_equal_with_mla(
+            kvcaches_src, kvcaches_dst, slot_mapping, head_size
+        )
+    else:
+        check_sglang_paged_kv_cache_equal(
+            kvcaches_src,
+            kvcaches_dst,
+            slot_mapping,
+            num_heads=num_heads,
+            head_size=head_size,
+        )
+
+
+def _zero_kvcaches(kvcaches, use_mla):
+    """Zero out all tensors in the kvcaches structure."""
+    if use_mla:
+        for t in kvcaches:
+            t.zero_()
+    else:
+        for kv_list in kvcaches:
+            for t in kv_list:
+                t.zero_()
+
+
+def _as_flat_sglang_mha(kvcaches):
+    """Convert [[k_list], [v_list]] to flat [k0, ..., kN, v0, ..., vN]."""
+    return list(kvcaches[0]) + list(kvcaches[1])
+
+
+def _flat_to_nested_sglang_mha(kvcaches_flat, num_layers: int):
+    return [kvcaches_flat[:num_layers], kvcaches_flat[num_layers:]]
+
+
+# --------------------------------------------------------------------------- #
+# Non-layerwise (SGLangXPUConnector)
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize("use_xpu", [False, True])
+@pytest.mark.parametrize("use_mla", [False, True])
+def test_sglang_xpu_connector_roundtrip(use_xpu: bool, use_mla: bool):
+    """Roundtrip: XPU kvcaches -> CPU memobj -> XPU kvcaches_dst, then compare."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 2
+    num_blocks = 4
+    block_size = 16
+    num_heads = 1 if use_mla else 8
+    head_size = 64
+    num_tokens = 32
+    hidden_dim = num_heads * head_size
+
+    kvcaches = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=use_mla,
+        device=device,
+    )
+
+    total_slots = num_blocks * block_size
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=total_slots, num_tokens=num_tokens, device=device
+    )
+
+    conn = SGLangXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=use_xpu,
+        chunk_size=num_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=use_mla,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 64)
+    shape = conn.get_shape(num_tokens)
+    fmt = MemoryFormat.KV_MLA_FMT if use_mla else MemoryFormat.KV_2LTD
+    memobj = pin_alloc.allocate(shape, torch.bfloat16, fmt)
+
+    try:
+        # XPU -> CPU
+        conn.from_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches,
+        )
+
+        # CPU -> XPU into fresh caches
+        kvcaches_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+            device=device,
+        )
+        _zero_kvcaches(kvcaches_dst, use_mla)
+
+        conn.to_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches_dst,
+        )
+
+        _check_kv_equal(
+            kvcaches,
+            kvcaches_dst,
+            slot_mapping,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+        )
+    finally:
+        memobj.ref_count_down()
+        pin_alloc.close()
+
+
+@pytest.mark.parametrize("use_xpu", [False, True])
+@pytest.mark.parametrize("use_mla", [False, True])
+def test_sglang_xpu_connector_roundtrip_multi_chunk(use_xpu: bool, use_mla: bool):
+    """Multi-chunk roundtrip with non-contiguous token ranges."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 2
+    num_blocks = 6
+    block_size = 8
+    num_heads = 1 if use_mla else 8
+    head_size = 64
+    total_tokens = 32
+    hidden_dim = num_heads * head_size
+
+    starts = [0, 7, 19]
+    ends = [4, 13, 25]
+
+    kvcaches = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=use_mla,
+        device=device,
+    )
+
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=total_tokens,
+        device=device,
+    )
+    packed_slot_mapping = _pack_slot_mapping(slot_mapping, starts, ends)
+
+    conn = SGLangXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=use_xpu,
+        chunk_size=total_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=use_mla,
+    )
+
+    fmt = MemoryFormat.KV_MLA_FMT if use_mla else MemoryFormat.KV_2LTD
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 64)
+    memobjs = []
+    try:
+        for s, e in zip(starts, ends, strict=False):
+            n = e - s
+            shape = conn.get_shape(n)
+            memobj = pin_alloc.allocate(shape, torch.bfloat16, fmt)
+            conn.from_gpu(
+                memobj,
+                start=s,
+                end=e,
+                slot_mapping=slot_mapping,
+                kvcaches=kvcaches,
+            )
+            memobjs.append((s, e, memobj))
+
+        kvcaches_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+            device=device,
+        )
+        _zero_kvcaches(kvcaches_dst, use_mla)
+
+        for s, e, memobj in memobjs:
+            conn.to_gpu(
+                memobj,
+                start=s,
+                end=e,
+                slot_mapping=slot_mapping,
+                kvcaches=kvcaches_dst,
+            )
+
+        _check_kv_equal(
+            kvcaches,
+            kvcaches_dst,
+            packed_slot_mapping,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+        )
+    finally:
+        for _, _, memobj in memobjs:
+            memobj.ref_count_down()
+        pin_alloc.close()
+
+
+@pytest.mark.parametrize("use_xpu", [False, True])
+def test_sglang_xpu_connector_roundtrip_flat_mha_kvcaches(use_xpu: bool):
+    """Non-layerwise SGLang can pass flat MHA kvcaches; ensure roundtrip works."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 2
+    num_blocks = 4
+    block_size = 16
+    num_heads = 8
+    head_size = 64
+    num_tokens = 32
+    hidden_dim = num_heads * head_size
+
+    nested_src = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=False,
+        device=device,
+    )
+    kvcaches_src = _as_flat_sglang_mha(nested_src)
+
+    total_slots = num_blocks * block_size
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=total_slots, num_tokens=num_tokens, device=device
+    )
+
+    conn = SGLangXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=use_xpu,
+        chunk_size=num_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=False,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 64)
+    memobj = pin_alloc.allocate(
+        conn.get_shape(num_tokens), torch.bfloat16, MemoryFormat.KV_2LTD
+    )
+
+    try:
+        conn.from_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches_src,
+        )
+
+        nested_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=False,
+            device=device,
+        )
+        kvcaches_dst = _as_flat_sglang_mha(nested_dst)
+        for t in kvcaches_dst:
+            t.zero_()
+
+        conn.to_gpu(
+            memobj,
+            start=0,
+            end=num_tokens,
+            slot_mapping=slot_mapping,
+            kvcaches=kvcaches_dst,
+        )
+
+        _check_kv_equal(
+            _flat_to_nested_sglang_mha(kvcaches_src, num_layers),
+            _flat_to_nested_sglang_mha(kvcaches_dst, num_layers),
+            slot_mapping,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=False,
+        )
+    finally:
+        memobj.ref_count_down()
+        pin_alloc.close()
+
+
+# --------------------------------------------------------------------------- #
+# Layerwise (SGLangLayerwiseXPUConnector)
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize("use_xpu", [False, True])
+@pytest.mark.parametrize("use_mla", [False, True])
+def test_sglang_xpu_connector_roundtrip_layerwise(use_xpu: bool, use_mla: bool):
+    """Layerwise roundtrip using generator protocol."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 4
+    num_blocks = 8
+    block_size = 16
+    num_heads = 1 if use_mla else 8
+    head_size = 64
+    num_tokens = 64
+    hidden_dim = num_heads * head_size
+
+    kvcaches = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=use_mla,
+        device=device,
+    )
+
+    total_slots = num_blocks * block_size
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=total_slots, num_tokens=num_tokens, device=device
+    )
+
+    conn = SGLangLayerwiseXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=use_xpu,
+        chunk_size=num_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=use_mla,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 256)
+
+    # Per-layer list-of-chunks (1 chunk per layer)
+    mem_fmt = MemoryFormat.KV_MLA_FMT if use_mla else MemoryFormat.KV_T2D
+    memobjs_by_layer = [
+        [
+            pin_alloc.allocate(
+                conn.get_shape(num_tokens),
+                torch.bfloat16,
+                mem_fmt,
+            )
+        ]
+        for _ in range(num_layers)
+    ]
+
+    try:
+        # XPU -> CPU (layerwise generator): yields num_layers + 1 times
+        gen = conn.batched_from_gpu(
+            memobjs_by_layer,
+            starts=[0],
+            ends=[num_tokens],
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches,
+        )
+        for _ in range(num_layers + 1):
+            next(gen)
+
+        # CPU -> XPU into fresh caches
+        kvcaches_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+            device=device,
+        )
+        _zero_kvcaches(kvcaches_dst, use_mla)
+
+        gen2 = conn.batched_to_gpu(
+            starts=[0],
+            ends=[num_tokens],
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches_dst,
+        )
+
+        next(gen2)  # initial yield, expects send()
+        for layer_id in range(num_layers):
+            gen2.send(memobjs_by_layer[layer_id])
+        next(gen2)  # final yield
+
+        _check_kv_equal(
+            kvcaches,
+            kvcaches_dst,
+            slot_mapping,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+        )
+    finally:
+        for layer in memobjs_by_layer:
+            for m in layer:
+                m.ref_count_down()
+        pin_alloc.close()
+
+
+@pytest.mark.parametrize("use_xpu", [False, True])
+@pytest.mark.parametrize("use_mla", [False, True])
+def test_sglang_xpu_connector_roundtrip_layerwise_multi_chunk(
+    use_xpu: bool, use_mla: bool
+):
+    """Layerwise multi-chunk roundtrip."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 4
+    num_blocks = 8
+    block_size = 8
+    num_heads = 1 if use_mla else 8
+    head_size = 64
+    total_tokens = 40
+    hidden_dim = num_heads * head_size
+
+    starts = [0, 9, 21]
+    ends = [5, 15, 30]
+
+    kvcaches = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=use_mla,
+        device=device,
+    )
+
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=total_tokens,
+        device=device,
+    )
+    packed_slot_mapping = _pack_slot_mapping(slot_mapping, starts, ends)
+
+    conn = SGLangLayerwiseXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=use_xpu,
+        chunk_size=total_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=use_mla,
+    )
+
+    mem_fmt = MemoryFormat.KV_MLA_FMT if use_mla else MemoryFormat.KV_T2D
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 128)
+    memobjs_by_layer = []
+    for _ in range(num_layers):
+        per_layer = []
+        for s, e in zip(starts, ends, strict=False):
+            n = e - s
+            per_layer.append(
+                pin_alloc.allocate(
+                    conn.get_shape(n),
+                    torch.bfloat16,
+                    mem_fmt,
+                )
+            )
+        memobjs_by_layer.append(per_layer)
+
+    try:
+        # XPU -> CPU
+        producer = conn.batched_from_gpu(
+            memobjs_by_layer,
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches,
+        )
+        for _ in range(num_layers + 1):
+            next(producer)
+
+        # CPU -> XPU
+        kvcaches_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+            device=device,
+        )
+        _zero_kvcaches(kvcaches_dst, use_mla)
+
+        consumer = conn.batched_to_gpu(
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches_dst,
+        )
+        next(consumer)
+        for layer_id in range(num_layers):
+            consumer.send(memobjs_by_layer[layer_id])
+        next(consumer)
+
+        _check_kv_equal(
+            kvcaches,
+            kvcaches_dst,
+            packed_slot_mapping,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=use_mla,
+        )
+    finally:
+        for layer in memobjs_by_layer:
+            for memobj in layer:
+                memobj.ref_count_down()
+        pin_alloc.close()
+
+
+def test_sglang_layerwise_uses_kernel_transfers(monkeypatch):
+    """Ensure layerwise SGLang path dispatches through kernel transfer ops."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 3
+    num_blocks = 6
+    block_size = 8
+    num_heads = 8
+    head_size = 64
+    hidden_dim = num_heads * head_size
+    total_tokens = 24
+    starts = [0, 7]
+    ends = [4, 12]
+    num_chunks = len(starts)
+
+    kvcaches = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=False,
+        device=device,
+    )
+
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=total_tokens,
+        device=device,
+    )
+
+    conn = SGLangLayerwiseXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=True,
+        chunk_size=total_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=False,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 128)
+    memobjs_by_layer = []
+    for _ in range(num_layers):
+        per_layer = []
+        for s, e in zip(starts, ends, strict=False):
+            n = e - s
+            per_layer.append(
+                pin_alloc.allocate(
+                    torch.Size([n, 2, hidden_dim]),
+                    torch.bfloat16,
+                    MemoryFormat.KV_T2D,
+                )
+            )
+        memobjs_by_layer.append(per_layer)
+
+    calls: list[tuple[object, bool]] = []
+    orig_single_layer_kv_transfer_sgl = (
+        xpu_connectors.lmc_ops.single_layer_kv_transfer_sgl
+    )
+
+    def _recording_single_layer_kv_transfer_sgl(
+        src,
+        sgl_k,
+        sgl_v,
+        slot_map,
+        direction,
+        token_major=False,
+    ):
+        calls.append((direction, token_major))
+        return orig_single_layer_kv_transfer_sgl(
+            src,
+            sgl_k,
+            sgl_v,
+            slot_map,
+            direction,
+            token_major,
+        )
+
+    monkeypatch.setattr(
+        xpu_connectors.lmc_ops,
+        "single_layer_kv_transfer_sgl",
+        _recording_single_layer_kv_transfer_sgl,
+    )
+
+    try:
+        # D2H path
+        producer = conn.batched_from_gpu(
+            memobjs_by_layer,
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches,
+        )
+        for _ in range(num_layers + 1):
+            next(producer)
+
+        # H2D path into fresh caches
+        kvcaches_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=False,
+            device=device,
+        )
+        _zero_kvcaches(kvcaches_dst, use_mla=False)
+
+        consumer = conn.batched_to_gpu(
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches_dst,
+        )
+        next(consumer)
+        for layer_id in range(num_layers):
+            consumer.send(memobjs_by_layer[layer_id])
+        next(consumer)
+
+        expected_calls_per_direction = num_layers * num_chunks
+        d2h_calls = [
+            c for c in calls if c[0] == xpu_connectors.lmc_ops.TransferDirection.D2H
+        ]
+        h2d_calls = [
+            c for c in calls if c[0] == xpu_connectors.lmc_ops.TransferDirection.H2D
+        ]
+
+        assert len(d2h_calls) == expected_calls_per_direction
+        assert len(h2d_calls) == expected_calls_per_direction
+        assert all(token_major for _, token_major in calls)
+    finally:
+        for layer in memobjs_by_layer:
+            for memobj in layer:
+                memobj.ref_count_down()
+        pin_alloc.close()
+
+
+def test_sglang_layerwise_uses_mla_kernel_transfers(monkeypatch):
+    """Ensure MLA layerwise path dispatches through single_layer_kv_transfer."""
+    _skip_if_no_xpu()
+    device = torch.device("xpu:0")
+
+    num_layers = 3
+    num_blocks = 6
+    block_size = 8
+    num_heads = 1
+    head_size = 64
+    hidden_dim = num_heads * head_size
+    total_tokens = 24
+    starts = [0, 7]
+    ends = [4, 12]
+    num_chunks = len(starts)
+
+    kvcaches = generate_sglang_kv_cache_paged_list_tensors(
+        num_layers=num_layers,
+        num_blocks=num_blocks,
+        block_size=block_size,
+        num_heads=num_heads,
+        head_size=head_size,
+        use_mla=True,
+        device=device,
+    )
+
+    slot_mapping = _make_unique_slot_mapping(
+        total_slots=num_blocks * block_size,
+        num_tokens=total_tokens,
+        device=device,
+    )
+
+    conn = SGLangLayerwiseXPUConnector(
+        hidden_dim_size=hidden_dim,
+        num_layers=num_layers,
+        use_xpu=True,
+        chunk_size=total_tokens,
+        dtype=torch.bfloat16,
+        device=device,
+        use_mla=True,
+    )
+
+    pin_alloc = PinMemoryAllocator(size=1024 * 1024 * 128)
+    memobjs_by_layer = []
+    for _ in range(num_layers):
+        per_layer = []
+        for s, e in zip(starts, ends, strict=False):
+            n = e - s
+            per_layer.append(
+                pin_alloc.allocate(
+                    conn.get_shape(n),
+                    torch.bfloat16,
+                    MemoryFormat.KV_MLA_FMT,
+                )
+            )
+        memobjs_by_layer.append(per_layer)
+
+    single_layer_calls: list[tuple[object, bool]] = []
+    sgl_calls: list[tuple[object, bool]] = []
+    orig_single_layer_kv_transfer = xpu_connectors.lmc_ops.single_layer_kv_transfer
+    orig_single_layer_kv_transfer_sgl = (
+        xpu_connectors.lmc_ops.single_layer_kv_transfer_sgl
+    )
+
+    def _recording_single_layer_kv_transfer(
+        src,
+        dst,
+        slot_map,
+        direction,
+        engine_kv_format,
+        token_major=False,
+    ):
+        single_layer_calls.append((direction, token_major))
+        return orig_single_layer_kv_transfer(
+            src,
+            dst,
+            slot_map,
+            direction,
+            engine_kv_format,
+            token_major,
+        )
+
+    def _recording_single_layer_kv_transfer_sgl(
+        src,
+        sgl_k,
+        sgl_v,
+        slot_map,
+        direction,
+        token_major=False,
+    ):
+        sgl_calls.append((direction, token_major))
+        return orig_single_layer_kv_transfer_sgl(
+            src,
+            sgl_k,
+            sgl_v,
+            slot_map,
+            direction,
+            token_major,
+        )
+
+    monkeypatch.setattr(
+        xpu_connectors.lmc_ops,
+        "single_layer_kv_transfer",
+        _recording_single_layer_kv_transfer,
+    )
+    monkeypatch.setattr(
+        xpu_connectors.lmc_ops,
+        "single_layer_kv_transfer_sgl",
+        _recording_single_layer_kv_transfer_sgl,
+    )
+
+    try:
+        # D2H path
+        producer = conn.batched_from_gpu(
+            memobjs_by_layer,
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches,
+        )
+        for _ in range(num_layers + 1):
+            next(producer)
+
+        # H2D path into fresh caches
+        kvcaches_dst = generate_sglang_kv_cache_paged_list_tensors(
+            num_layers=num_layers,
+            num_blocks=num_blocks,
+            block_size=block_size,
+            num_heads=num_heads,
+            head_size=head_size,
+            use_mla=True,
+            device=device,
+        )
+        _zero_kvcaches(kvcaches_dst, use_mla=True)
+
+        consumer = conn.batched_to_gpu(
+            starts=starts,
+            ends=ends,
+            slot_mapping=slot_mapping,
+            sync=True,
+            kvcaches=kvcaches_dst,
+        )
+        next(consumer)
+        for layer_id in range(num_layers):
+            consumer.send(memobjs_by_layer[layer_id])
+        next(consumer)
+
+        expected_calls_per_direction = num_layers * num_chunks
+        d2h_calls = [
+            c
+            for c in single_layer_calls
+            if c[0] == xpu_connectors.lmc_ops.TransferDirection.D2H
+        ]
+        h2d_calls = [
+            c
+            for c in single_layer_calls
+            if c[0] == xpu_connectors.lmc_ops.TransferDirection.H2D
+        ]
+
+        assert len(d2h_calls) == expected_calls_per_direction
+        assert len(h2d_calls) == expected_calls_per_direction
+        assert all(token_major for _, token_major in single_layer_calls)
+        assert len(sgl_calls) == 0
+    finally:
+        for layer in memobjs_by_layer:
+            for memobj in layer:
+                memobj.ref_count_down()
+        pin_alloc.close()
diff --git a/tests/v1/utils.py b/tests/v1/utils.py
new file mode 100644
index 0000000..e94c347
--- /dev/null
+++ b/tests/v1/utils.py
@@ -0,0 +1,861 @@
+# SPDX-License-Identifier: Apache-2.0
+# Standard
+from typing import Optional
+from unittest.mock import MagicMock
+import asyncio
+import ctypes
+import functools
+import inspect
+import os
+import random
+import socket
+import string
+import tempfile
+import threading
+import uuid
+
+# Third Party
+import torch
+
+# First Party
+from lmcache.utils import CacheEngineKey
+from lmcache.v1.config import LMCacheEngineConfig
+from lmcache.v1.gpu_connector.gpu_connectors import VLLMPagedMemGPUConnectorV2
+from lmcache.v1.memory_allocators.ad_hoc_memory_allocator import AdHocMemoryAllocator
+from lmcache.v1.memory_management import (
+    MemoryFormat,
+    MemoryObj,
+)
+from lmcache.v1.metadata import LMCacheMetadata
+
+# Conditional import for CUDA-only operations
+if torch.cuda.is_available() or torch.xpu.is_available():
+    try:
+        # First Party
+        import lmcache.c_ops as lmc_ops
+    except ImportError:
+        # If c_ops is not built, create a mock
+        lmc_ops = None
+else:
+    # Mock c_ops when CUDA is not available
+    # First Party
+    lmc_ops = None
+
+# Define mock EngineKVFormat enum if c_ops is not available
+if lmc_ops is None:
+
+    class MockEngineKVFormat:
+        NL_X_TWO_NB_BS_NH_HS = 0
+        NL_X_NB_TWO_BS_NH_HS = 1
+        NL_X_NB_BS_HS = 2
+        NL_X_TWO_NB_NH_BS_HS = 3
+        NL_X_NB_TWO_NH_BS_HS = 4
+        NL_X_NB_NH_BS_TWO_HS = 5
+
+    class MockCOps:
+        EngineKVFormat = MockEngineKVFormat
+        GPUKVFormat = MockEngineKVFormat
+
+    lmc_ops = MockCOps()
+
+
+def _probe_cufile_register() -> bool:
+    """
+    Try to actually register a cuFile handle on a real file in the test
+    scratch dir. Returns True iff cuFileHandleRegister succeeds.
+
+    Importability of cufile / libcufile.so is necessary but not sufficient:
+    on hosts without nvidia-fs (or on a non-GDS-capable filesystem),
+    cuFileHandleRegister fails at runtime with CU_FILE_IO_NOT_SUPPORTED
+    (err=5027). This probe matches the exact path tests will exercise.
+    """
+    try:
+        # Third Party
+        import cufile
+    except Exception:
+        return False
+
+    probe_dir = os.environ.get("LMCACHE_TEST_TMPDIR") or tempfile.gettempdir()
+    if not os.path.isdir(probe_dir):
+        return False
+
+    try:
+        fd, probe_path = tempfile.mkstemp(dir=probe_dir, prefix="cufile-probe-")
+    except OSError:
+        return False
+
+    try:
+        try:
+            os.write(fd, b"\0" * 4096)
+        finally:
+            os.close(fd)
+        # Mirror production: GdsBackend opens with mode "r+" and
+        # use_direct_io=True (see gds_backend.py:950). If the FS doesn't
+        # support GDS+O_DIRECT, register fails here exactly as in tests.
+        cu = cufile.CuFile(probe_path, "r+", use_direct_io=True)
+        try:
+            cu.open()
+        except Exception:
+            # Register failed. cu._handle may hold the raw fd from os.open
+            # without a registered cuFile handle; close it ourselves and
+            # null the state so __del__ doesn't try to deregister None.
+            raw_fd = getattr(cu, "_handle", None)
+            if raw_fd is not None:
+                try:
+                    os.close(raw_fd)
+                except OSError:
+                    pass
+                cu._handle = None
+            return False
+        cu.close()
+        return True
+    finally:
+        try:
+            os.unlink(probe_path)
+        except OSError:
+            pass
+
+
+@functools.lru_cache(maxsize=1)
+def has_cufile() -> bool:
+    """
+    True only when NVIDIA cuFile is usable on this host's test scratch dir:
+    - python package `cufile` importable
+    - dynamic library `libcufile.so` loadable
+    - cuFileHandleRegister succeeds on a real file in LMCACHE_TEST_TMPDIR
+      (or the system tmpdir as a fallback)
+    """
+    try:
+        # Third Party
+        import cufile  # noqa: F401
+    except Exception:
+        return False
+
+    try:
+        ctypes.CDLL("libcufile.so")
+    except OSError:
+        return False
+
+    return _probe_cufile_register()
+
+
+def has_hipfile() -> bool:
+    """
+    True only when AMD hipFile is available:
+    - python package `hipfile` importable
+    - dynamic library `libhipfile.so` loadable
+    """
+    try:
+        # Third Party
+        import hipfile  # noqa: F401
+    except Exception:
+        return False
+
+    try:
+        ctypes.CDLL("libhipfile.so")
+    except OSError:
+        return False
+
+    return True
+
+
+def recover_engine_states(engine):
+    engine.gpu_connector.kv_cache_pointers_on_gpu = {}
+
+
+def recover_gpu_connector_states(gpu_connector):
+    gpu_connector.kv_cache_pointers_on_gpu = {}
+
+
+def dumb_metadata(kv_shape=(32, 2, 256, 8, 128)):
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=3,
+        local_world_size=3,
+        worker_id=1,
+        local_worker_id=1,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+    )
+
+
+def dumb_metadata_with_model_name(model_name: str, kv_shape=(32, 2, 256, 8, 128)):
+    return LMCacheMetadata(
+        model_name=model_name,
+        world_size=3,
+        local_world_size=3,
+        worker_id=1,
+        local_worker_id=1,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+    )
+
+
+def dumb_cache_engine_key(id: int = 0) -> CacheEngineKey:
+    return CacheEngineKey(
+        model_name="test_model",
+        world_size=3,
+        worker_id=1,
+        chunk_hash=id,
+        dtype=torch.bfloat16,
+    )
+
+
+def random_string(N):
+    return "".join(random.choices(string.ascii_uppercase + string.digits, k=N))
+
+
+def init_asyncio_loop():
+    async_loop = asyncio.new_event_loop()
+    async_thread = threading.Thread(target=async_loop.run_forever)
+    async_thread.start()
+    return async_loop, async_thread
+
+
+def close_asyncio_loop(async_loop, async_thread):
+    if async_loop.is_running():
+        # First, cancel all pending tasks
+        try:
+            # Get all tasks and cancel them
+            pending = asyncio.all_tasks(async_loop)
+            for task in pending:
+                if not task.done():
+                    task.cancel()
+        except Exception as e:
+            print(f"Error during close pending tasks: - {e}")
+
+        # Then stop the loop
+        async_loop.call_soon_threadsafe(async_loop.stop)
+
+    if async_thread.is_alive():
+        async_thread.join(timeout=2.0)
+
+    # Close the loop to release resources
+    if not async_loop.is_closed():
+        async_loop.close()
+
+    # Set event loop to None
+    asyncio.set_event_loop(None)
+
+
+def get_available_port(host: str = "127.0.0.1") -> int:
+    """
+    Get an available port dynamically by binding to port 0.
+
+    Args:
+        host: The host address to bind to. Default is "127.0.0.1".
+
+    Returns:
+        An available port number.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind((host, 0))
+        s.listen(1)
+        port = s.getsockname()[1]
+    return port
+
+
+def get_available_ports(count: int, host: str = "127.0.0.1") -> list[int]:
+    """
+    Get multiple available ports dynamically.
+
+    Args:
+        count: Number of ports to get.
+        host: The host address to bind to. Default is "127.0.0.1".
+
+    Returns:
+        A list of available port numbers.
+    """
+    ports = []
+    for _ in range(count):
+        ports.append(get_available_port(host))
+    return ports
+
+
+def generate_kv_cache(num_tokens, device):
+    ret = []
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    shape = [num_tokens, num_heads, head_size]
+    dtype = torch.bfloat16
+
+    for i in range(num_layers):
+        k = torch.rand(shape, dtype=dtype, device=device)
+        v = torch.rand(shape, dtype=dtype, device=device)
+        ret.append((k, v))
+
+    return tuple(ret)
+
+
+def generate_kv_cache_paged_list_tensors(
+    num_blocks,
+    device,
+    block_size=16,
+    dtype=torch.bfloat16,
+    num_layers=32,
+    head_size=128,
+    # default vllm non-MLA flash attention
+    engine_kv_format=lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+):
+    """
+    Instead of Tuple[Tuple[Tensor, Tensor]], return List[Tensor]
+    where KV are in the same tensor
+    """
+    ret = []
+    # only support vllm MLA format for now
+    use_mla = engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_BS_HS
+    num_heads = 1 if use_mla else 8
+    if use_mla:
+        shape = [num_blocks, block_size, head_size]
+    else:
+        if engine_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS:
+            shape = [2, num_blocks, block_size, num_heads, head_size]
+        elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS:
+            shape = [num_blocks, 2, block_size, num_heads, head_size]
+        elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS:
+            shape = [2, num_blocks, num_heads, block_size, head_size]
+        elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS:
+            shape = [num_blocks, 2, num_heads, block_size, head_size]
+        elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_NH_BS_TWO_HS:
+            # blocks-first, K/V fused into the trailing dim
+            shape = [num_blocks, num_heads, block_size, 2, head_size]
+        else:
+            raise ValueError(f"Unsupported engine_kv_format: {engine_kv_format}")
+
+    for i in range(num_layers):
+        # TODO(chunxiaozheng): support more dtypes
+        if dtype == torch.uint8:
+            kv = torch.randint(0, 256, shape, dtype=dtype, device=device)
+        else:
+            kv = torch.rand(shape, dtype=dtype, device=device)
+        ret.append(kv)
+
+    return ret
+
+
+def generate_sglang_kv_cache_paged_list_tensors(
+    num_layers,
+    num_blocks,
+    block_size,
+    num_heads,
+    head_size,
+    use_mla=False,
+    device="cuda",
+    dtype=torch.bfloat16,
+):
+    """
+    Instead of Tuple[Tuple[Tensor, Tensor]], return List[Tensor]
+    where KV are in the same tensor
+
+    For MLA: List[num_layers] of [page_buffer_size, 1, head_size]
+    For MHA: List[2] -> List[num_layers] of [page_buffer_size, num_heads, head_size]
+    """
+    shape = (
+        [num_blocks * block_size, 1, head_size]
+        if use_mla
+        else [num_blocks * block_size, num_heads, head_size]
+    )
+    if use_mla:
+        kv_cache = [
+            torch.rand(shape, dtype=dtype, device=device) for i in range(num_layers)
+        ]
+    else:
+        # MHA: List[2] -> List[num_layers]
+        k_cache = [
+            torch.rand(shape, dtype=dtype, device=device) for i in range(num_layers)
+        ]
+        v_cache = [
+            torch.rand(shape, dtype=dtype, device=device) for i in range(num_layers)
+        ]
+        kv_cache = [k_cache, v_cache]
+    return kv_cache
+
+
+def generate_kv_cache_paged(num_blocks, device, block_size=16, dtype=torch.bfloat16):
+    ret = []
+    num_layers = 32
+    num_heads = 8
+    head_size = 128
+    shape = [num_blocks, block_size, num_heads, head_size]
+
+    for i in range(num_layers):
+        k = torch.rand(shape, dtype=dtype, device=device)
+        v = torch.rand(shape, dtype=dtype, device=device)
+        ret.append((k, v))
+
+    return tuple(ret)
+
+
+def generate_tokens(num_tokens, device, fixed=False):
+    if fixed:
+        return torch.tensor([-1] * num_tokens).to(device)
+    else:
+        # random tokens
+        return torch.randint(0, 10000, size=[num_tokens]).to(device)
+
+
+def concatenate_kv_caches(kv_chunks):
+    dim = 0
+    ret = []
+    for kv_layer in zip(*kv_chunks, strict=False):
+        klist, vlist = zip(*kv_layer, strict=False)
+        klayer = torch.cat(klist, dim=dim)
+        vlayer = torch.cat(vlist, dim=dim)
+        ret.append((klayer, vlayer))
+    return tuple(ret)
+
+
+def check_mem_obj_equal(left, right, use_mla: bool = False):
+    """
+    check whether two memory objects are the same
+    """
+    for left_mem_obj, right_mem_obj in zip(left, right, strict=False):
+        left_tensor_size = left_mem_obj.tensor.size()
+        right_tensor_size = right_mem_obj.tensor.size()
+        if use_mla:
+            assert left_tensor_size[0] == 1
+            assert right_tensor_size[0] == 1
+
+            left_kv, right_kv = left_mem_obj.tensor[0], right_mem_obj.tensor[0]
+            right_kv = right_kv.to(left_kv.device)
+
+            assert len(left_kv.shape) == 3
+            assert len(right_kv.shape) == 3
+
+            assert (left_kv[:, :, :] == right_kv[:, :, :]).all()
+        else:
+            assert left_tensor_size[0] == 2
+            assert right_tensor_size[0] == 2
+
+            left_kv, right_kv = left_mem_obj.tensor, right_mem_obj.tensor
+            left_k, left_v = left_kv[0], left_kv[1]
+            right_k, right_v = right_kv[0], right_kv[1]
+            right_k = right_k.to(left_k.device)
+            right_v = right_v.to(left_v.device)
+
+            assert len(left_k.shape) == 3
+            assert len(left_v.shape) == 3
+            assert len(right_k.shape) == 3
+            assert len(right_v.shape) == 3
+
+            assert (left_k[:, :, :] == right_k[:, :, :]).all()
+            assert (left_v[:, :, :] == right_v[:, :, :]).all()
+
+
+# default checks for vllm non-MLA flash attention
+def check_paged_kv_cache_equal(
+    left,
+    right,
+    slot_mapping,
+    num_heads=8,
+    head_size=128,
+    engine_kv_format=lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS,
+):
+    """
+    check whether two paged kv caches are the same at slot_mapping
+    """
+
+    if engine_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_BS_NH_HS:
+        token_dim = 0
+        num_tokens = slot_mapping.shape[0]
+        for left_kv_layer, right_kv_layer in zip(left, right, strict=False):
+            left_k = left_kv_layer[0].reshape(-1, num_heads, head_size)
+            left_v = left_kv_layer[1].reshape(-1, num_heads, head_size)
+            right_k = right_kv_layer[0].reshape(-1, num_heads, head_size)
+            right_v = right_kv_layer[1].reshape(-1, num_heads, head_size)
+
+            assert len(left_k.shape) == 3
+            assert len(left_v.shape) == 3
+            assert len(right_k.shape) == 3
+            assert len(right_v.shape) == 3
+
+            assert left_k.shape[token_dim] >= num_tokens
+            assert left_v.shape[token_dim] >= num_tokens
+            assert right_k.shape[token_dim] >= num_tokens
+            assert right_v.shape[token_dim] >= num_tokens
+
+            assert (left_k[slot_mapping, :, :] == right_k[slot_mapping, :, :]).all()
+            assert (left_v[slot_mapping, :, :] == right_v[slot_mapping, :, :]).all()
+
+    elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_TWO_BS_NH_HS:
+        token_dim = 0
+        num_tokens = slot_mapping.shape[0]
+        for left_kv_layer, right_kv_layer in zip(left, right, strict=False):
+            left_k = left_kv_layer[:, 0].contiguous().reshape(-1, num_heads, head_size)
+            left_v = left_kv_layer[:, 1].contiguous().reshape(-1, num_heads, head_size)
+            right_k = (
+                right_kv_layer[:, 0].contiguous().reshape(-1, num_heads, head_size)
+            )
+            right_v = (
+                right_kv_layer[:, 1].contiguous().reshape(-1, num_heads, head_size)
+            )
+
+            assert len(left_k.shape) == 3
+            assert len(left_v.shape) == 3
+            assert len(right_k.shape) == 3
+            assert len(right_v.shape) == 3
+
+            assert left_k.shape[token_dim] >= num_tokens
+            assert left_v.shape[token_dim] >= num_tokens
+            assert right_k.shape[token_dim] >= num_tokens
+            assert right_v.shape[token_dim] >= num_tokens
+
+            assert (left_k[slot_mapping, :, :] == right_k[slot_mapping, :, :]).all()
+            assert (left_v[slot_mapping, :, :] == right_v[slot_mapping, :, :]).all()
+
+    elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_TWO_NB_NH_BS_HS:
+        # HND flash attention: [2, num_blocks, num_heads, block_size, head_size]
+        # Flatten [num_blocks, num_heads, block_size, head_size] ->
+        #   swap to [num_blocks, block_size, num_heads, head_size] ->
+        #   reshape to [num_blocks*block_size, num_heads, head_size]
+        num_tokens = slot_mapping.shape[0]
+        for left_kv_layer, right_kv_layer in zip(left, right, strict=False):
+            left_k = (
+                left_kv_layer[0]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+            left_v = (
+                left_kv_layer[1]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+            right_k = (
+                right_kv_layer[0]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+            right_v = (
+                right_kv_layer[1]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+
+            assert left_k.shape[0] >= num_tokens
+            assert (left_k[slot_mapping, :, :] == right_k[slot_mapping, :, :]).all()
+            assert (left_v[slot_mapping, :, :] == right_v[slot_mapping, :, :]).all()
+
+    elif engine_kv_format == lmc_ops.EngineKVFormat.NL_X_NB_TWO_NH_BS_HS:
+        # HND flash infer: [num_blocks, 2, num_heads, block_size, head_size]
+        # left_kv_layer[:, 0] -> [num_blocks, num_heads, block_size, head_size]
+        num_tokens = slot_mapping.shape[0]
+        for left_kv_layer, right_kv_layer in zip(left, right, strict=False):
+            left_k = (
+                left_kv_layer[:, 0]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+            left_v = (
+                left_kv_layer[:, 1]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+            right_k = (
+                right_kv_layer[:, 0]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+            right_v = (
+                right_kv_layer[:, 1]
+                .permute(0, 2, 1, 3)
+                .contiguous()
+                .reshape(-1, num_heads, head_size)
+            )
+
+            assert left_k.shape[0] >= num_tokens
+            assert (left_k[slot_mapping, :, :] == right_k[slot_mapping, :, :]).all()
+            assert (left_v[slot_mapping, :, :] == right_v[slot_mapping, :, :]).all()
+
+
+def check_sglang_paged_kv_cache_equal(
+    left, right, slot_mapping, num_heads=8, head_size=128
+):
+    """
+    check whether two paged kv caches are the same at slot_mapping
+
+    Format: List[2] -> List[num_layers] of [page_buffer_size, num_heads, head_size]
+    """
+    token_dim = 0
+    num_tokens = slot_mapping.shape[0]
+
+    # left and right are [k_list, v_list]
+    assert len(left) == 2, "Expected [k_list, v_list]"
+    assert len(right) == 2, "Expected [k_list, v_list]"
+
+    # Check K and V separately
+    for kv_idx in range(2):  # 0 for K, 1 for V
+        left_kv_list = left[kv_idx]
+        right_kv_list = right[kv_idx]
+
+        for left_kv, right_kv in zip(left_kv_list, right_kv_list, strict=False):
+            _left_kv = left_kv.reshape(-1, num_heads, head_size)
+            _right_kv = right_kv.reshape(-1, num_heads, head_size)
+
+            assert len(_left_kv.shape) == 3
+            assert len(_right_kv.shape) == 3
+
+            assert _left_kv.shape[token_dim] >= num_tokens
+            assert _right_kv.shape[token_dim] >= num_tokens
+
+            assert (_left_kv[slot_mapping, :, :] == _right_kv[slot_mapping, :, :]).all()
+
+
+def check_paged_kv_cache_equal_with_mla(left, right, slot_mapping, head_size=128):
+    """
+    check whether two paged kv caches are the same at slot_mapping when use mla
+    """
+    token_dim = 0
+    num_tokens = slot_mapping.shape[0]
+    for left_kv, right_kv in zip(left, right, strict=False):
+        new_left_kv = left_kv.reshape(-1, head_size)
+        new_right_kv = right_kv.reshape(-1, head_size)
+
+        assert len(new_left_kv.shape) == 2
+        assert len(new_right_kv.shape) == 2
+
+        assert new_left_kv.shape[token_dim] >= num_tokens
+        assert new_right_kv.shape[token_dim] >= num_tokens
+
+        assert (new_left_kv[slot_mapping, :] == new_right_kv[slot_mapping, :]).all()
+
+
+def check_kv_cache_device(kvs, device):
+    for kv in kvs:
+        k, v = kv
+        assert k.device == torch.device(device)
+        assert v.device == torch.device(device)
+
+
+def create_gpu_connector(hidden_dim, num_layers):
+    return VLLMPagedMemGPUConnectorV2(hidden_dim, num_layers)
+
+
+def get_all_methods_from_base(base_class):
+    """
+    Get all public methods defined in the base class (excluding inherited from object).
+    """
+    methods = set()
+    for name in dir(base_class):
+        # Skip private and special methods
+        if name.startswith("_"):
+            continue
+        attr = getattr(base_class, name)
+        if callable(attr):
+            methods.add(name)
+    return methods
+
+
+def get_methods_implemented_in_class(cls, base_class=None):
+    """
+    Get methods that are actually implemented in the class itself.
+    Args:
+        cls: The class to inspect
+        base_class: Optional base class to stop at. If None, stops at
+            abstract base classes.
+    """
+    implemented = set()
+
+    # Check the class's own __dict__ for methods
+    for name in cls.__dict__:
+        if name.startswith("_"):
+            continue
+        attr = cls.__dict__[name]
+        # Check if it's callable (function, method, etc.)
+        if callable(attr):
+            implemented.add(name)
+
+    # Also check using getattr to catch any dynamically added methods
+    for name in dir(cls):
+        if name.startswith("_"):
+            continue
+        if name in implemented:
+            continue  # Already found
+        try:
+            attr = getattr(cls, name)
+            if callable(attr):
+                # Verify it's not inherited from base class
+                # by checking if it exists in the class's MRO
+                for base in cls.__mro__:
+                    # Stop when we hit the specified base class
+                    if base_class is not None and base is base_class:
+                        break
+                    # Or stop when we hit an abstract base class
+                    if base_class is None and inspect.isabstract(base):
+                        break
+                    if name in base.__dict__:
+                        implemented.add(name)
+                        break
+        except AttributeError:
+            pass
+
+    return implemented
+
+
+def get_abstract_methods(cls):
+    """
+    Get all abstract methods from a class.
+    """
+    abstract_methods = set()
+    for name, method in inspect.getmembers(cls, predicate=inspect.isfunction):
+        if getattr(method, "__isabstractmethod__", False):
+            abstract_methods.add(name)
+    return abstract_methods
+
+
+def check_method_signatures(base_class, impl_class):
+    """
+    Check if method signatures in implementation class match the base class.
+    Returns a list of mismatches.
+    """
+    base_methods = get_all_methods_from_base(base_class)
+    signature_mismatches = []
+
+    for method_name in base_methods:
+        base_method = getattr(base_class, method_name)
+        impl_method = getattr(impl_class, method_name, None)
+
+        if impl_method is None:
+            continue
+
+        try:
+            base_sig = inspect.signature(base_method)
+            impl_sig = inspect.signature(impl_method)
+
+            # Compare parameter names (excluding 'self')
+            base_params = [p for p in base_sig.parameters.keys() if p != "self"]
+            impl_params = [p for p in impl_sig.parameters.keys() if p != "self"]
+
+            if base_params != impl_params:
+                signature_mismatches.append(
+                    {
+                        "method": method_name,
+                        "base_params": base_params,
+                        "impl_params": impl_params,
+                    }
+                )
+        except (ValueError, TypeError):
+            # Some methods might not have inspectable signatures
+            pass
+
+    return signature_mismatches
+
+
+class DummyLMCacheAsyncLookupServer:
+    def __init__(self):
+        pass
+
+    def send_response_to_scheduler(
+        self,
+        lookup_id: str,
+        retrieved_length: int,
+    ) -> None:
+        pass
+
+
+class MockAdapter:
+    """
+    Mock adapter to provide config and lmcache_engine to InternalAPIServer.
+    """
+
+    def __init__(self, engine, config):
+        self.lmcache_engine = engine
+        self.config = config
+
+
+def create_test_metadata(
+    worker_id: int = 0,
+    world_size: int = 1,
+    kv_shape: tuple = (4, 2, 256, 8, 128),
+    engine_id: Optional[str] = "test_engine",
+    kv_connector_extra_config: Optional[dict] = None,
+) -> LMCacheMetadata:
+    """Create test metadata for LMCacheEngine."""
+    return LMCacheMetadata(
+        model_name="test_model",
+        world_size=world_size,
+        local_world_size=world_size,
+        worker_id=worker_id,
+        local_worker_id=worker_id,
+        kv_dtype=torch.bfloat16,
+        kv_shape=kv_shape,
+        engine_id=engine_id,
+        kv_connector_extra_config=kv_connector_extra_config,
+    )
+
+
+def create_test_config(
+    chunk_size: int = 256,
+    local_cpu: bool = True,
+    max_local_cpu_size: float = 1.0,
+    rpc_port: int = 0,
+    extra_config: Optional[dict] = None,
+    instance_id: Optional[str] = None,
+) -> LMCacheEngineConfig:
+    """Create test configuration for LMCacheEngine."""
+    if instance_id is None:
+        instance_id = f"test_instance_{uuid.uuid4().hex[:8]}"
+    config = LMCacheEngineConfig.from_defaults(
+        chunk_size=chunk_size,
+        local_cpu=local_cpu,
+        max_local_cpu_size=max_local_cpu_size,
+        lmcache_instance_id=instance_id,
+    )
+    config.extra_config = extra_config.copy() if extra_config else {}
+    config.extra_config["lmcache_rpc_port"] = rpc_port
+    return config
+
+
+def create_mock_vllm_config(
+    rank: int = 0, world_size: int = 1, rpc_port: int = 0
+) -> MagicMock:
+    """Create a mock VllmConfig for testing."""
+    vllm_config = MagicMock()
+
+    # Mock model_config
+    vllm_config.model_config = MagicMock()
+    vllm_config.model_config.model = "test_model"
+    vllm_config.model_config.dtype = torch.bfloat16
+    vllm_config.model_config.get_num_layers = MagicMock(return_value=4)
+    vllm_config.model_config.get_num_kv_heads = MagicMock(return_value=8)
+    vllm_config.model_config.get_head_size = MagicMock(return_value=128)
+    vllm_config.model_config.hf_config = MagicMock()
+    vllm_config.model_config.hf_config.model_type = "llama"
+
+    # Mock parallel_config
+    vllm_config.parallel_config = MagicMock()
+    vllm_config.parallel_config.rank = rank
+    vllm_config.parallel_config.world_size = world_size
+    vllm_config.parallel_config.tensor_parallel_size = world_size
+    vllm_config.parallel_config.pipeline_parallel_size = 1
+
+    # Mock cache_config
+    vllm_config.cache_config = MagicMock()
+    vllm_config.cache_config.cache_dtype = torch.bfloat16
+
+    # Mock kv_transfer_config with engine_id
+    vllm_config.kv_transfer_config = MagicMock()
+    vllm_config.kv_transfer_config.engine_id = "test_engine"
+    vllm_config.kv_transfer_config.get_from_extra_config = MagicMock(
+        side_effect=lambda key, default: (
+            rpc_port if key == "lmcache_rpc_port" else default
+        )
+    )
+
+    return vllm_config
+
+
+def create_test_memory_obj(shape=None, dtype=torch.bfloat16, device="cpu") -> MemoryObj:
+    """Create a test MemoryObj using AdHocMemoryAllocator for testing."""
+    if shape is None:
+        shape = torch.Size([2, 16, 8, 128])
+    allocator = AdHocMemoryAllocator(device=device)
+    memory_obj = allocator.allocate([shape], [dtype], fmt=MemoryFormat.KV_T2D)
+    return memory_obj
diff --git a/tools/check_spdx_header.py b/tools/check_spdx_header.py
new file mode 100644
index 0000000..1302b7c
--- /dev/null
+++ b/tools/check_spdx_header.py
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# This script originated from the vLLM respoitory on GitHub.
+# For the original code, see
+# [vLLM](https://github.com/vllm-project/vllm/blob/main/tools/check_spdx_header.py)
+
+# Standard
+import sys
+
+SPDX_HEADER = "# SPDX-License-Identifier: Apache-2.0"
+SPDX_HEADER_PREFIX = "# SPDX-License-Identifier:"
+
+
+def check_spdx_header(file_path):
+    with open(file_path, encoding="UTF-8") as file:
+        lines = file.readlines()
+        if not lines:
+            # Empty file like __init__.py
+            return True
+        for line in lines:
+            if line.strip().startswith(SPDX_HEADER_PREFIX):
+                return True
+    return False
+
+
+def add_header(file_path):
+    with open(file_path, "r+", encoding="UTF-8") as file:
+        lines = file.readlines()
+        file.seek(0, 0)
+        if lines and lines[0].startswith("#!"):
+            file.write(lines[0])
+            file.write(SPDX_HEADER + "\n")
+            file.writelines(lines[1:])
+        else:
+            file.write(SPDX_HEADER + "\n")
+            file.writelines(lines)
+
+
+def main():
+    print("Running checker")
+    files_with_missing_header = []
+    for file_path in sys.argv[1:]:
+        if not check_spdx_header(file_path):
+            files_with_missing_header.append(file_path)
+
+    if files_with_missing_header:
+        print("The following files are missing the SPDX header:")
+        for file_path in files_with_missing_header:
+            print(f"  {file_path}")
+            add_header(file_path)
+
+    sys.exit(1 if files_with_missing_header else 0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tools/translate_docs_zh.py b/tools/translate_docs_zh.py
new file mode 100644
index 0000000..4ebc9d8
--- /dev/null
+++ b/tools/translate_docs_zh.py
@@ -0,0 +1,420 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Translate missing Chinese Sphinx gettext entries with a model endpoint."""
+
+# Future
+from __future__ import annotations
+
+# Standard
+from pathlib import Path
+from urllib import request
+import json
+import os
+import sys
+
+LOCALE_DIR = Path("docs/source/locale/zh_CN/LC_MESSAGES")
+MAX_ENTRIES = int(os.environ.get("TRANSLATION_MAX_ENTRIES", "500"))
+
+SYSTEM_PROMPT = (
+    "You translate Sphinx gettext entries from English to Simplified Chinese. "
+    "Each request contains one focal entry to translate, optionally preceded "
+    "by a 'Source file:' line and surrounded by 'Previous entry' and "
+    "'Next entry' blocks for context. Translate ONLY the focal msgid under "
+    "'Translate this entry'. Return the Chinese translation as plain text "
+    "with no labels, no surrounding quotes, no other entries, and no "
+    "explanation. "
+    "Use the neighboring entries only to infer the section topic and to "
+    "keep terminology consistent; never include their text in your output. "
+    "If the focal msgid is a code identifier (snake_case, "
+    "SCREAMING_SNAKE_CASE, a config key, environment variable, file path, "
+    "URL, or product name), return it unchanged. "
+    "Do not add notes, explanations, summaries, or comments. "
+    "Preserve all reStructuredText/Sphinx formatting exactly, including "
+    "headings, indentation, directives, roles, labels, anchors, references, "
+    "admonitions, lists, tables, and cross-references. "
+    "Do not translate or change code blocks, inline code, shell commands, "
+    "configuration snippets, Python/JSON/YAML/TOML, API signatures, "
+    "environment variables, file paths, URLs, placeholders, package names, "
+    "class names, function names, method names, parameter names, CLI flags, "
+    "model names, feature names, product names, or values inside backticks. "
+    "Preserve Sphinx roles exactly, such as :ref:`...`, :doc:`...`, "
+    ":class:`...`, :func:`...`, :meth:`...`, :mod:`...`, :attr:`...`, "
+    ":obj:`...`, and :term:`...`. "
+    "Translate only normal explanatory prose. "
+    "Use natural Simplified Chinese for developer documentation. "
+    "Use these terms consistently: "
+    "KV cache -> KV Cache; KV Cache -> KV Cache; "
+    "inference -> 推理; serving -> 服务; "
+    "prefill -> Prefill; decode -> 解码; decoding -> 解码; "
+    "offload -> 卸载; offloading -> 卸载; "
+    "prefetch -> 预取; prefetch module -> 预取模块; "
+    "evict -> 逐出; eviction -> 逐出; "
+    "recompute -> 重计算; recomputation -> 重计算; "
+    "throughput -> 吞吐量; latency -> 延迟; "
+    "GPU memory -> 显存; VRAM -> 显存; CPU memory -> CPU 内存; "
+    "backend -> 后端; connector -> 连接器; storage -> 存储; "
+    "cache hit -> 缓存命中; cache miss -> 缓存未命中; lookup -> 查找; "
+    "chunk -> 块; layerwise -> 逐层; compression -> 压缩; "
+    "quantization -> 量化; "
+    "serialization -> 序列化; deserialization -> 反序列化; "
+    "disaggregated prefill -> 分离式 Prefill; multi-tenant -> 多租户. "
+    "Keep these terms unchanged: LMCache, vLLM, SGLang, TensorRT-LLM, NIXL, "
+    "CUDA, ROCm, Redis, S3, GDS, POSIX, Hugging Face, CacheBlend, cache_salt, "
+    "TTFT, LLM, GPU, CPU, API, token, prompt, system prompt, Attention. "
+    "If unsure whether something is syntax, code, an identifier, or a "
+    "product name, keep it unchanged."
+)
+
+
+class PoEntry:
+    """One translatable message read from a ``.po`` translation file.
+
+    A ``.po`` file is a list of messages. Each message pairs the original
+    English text with its Chinese translation, plus some status markers.
+
+    Attributes:
+        start: Line number where this message begins in the file.
+        end: Line number just after this message ends in the file.
+        flags: Status markers on the message. ``"fuzzy"`` means the English
+            text changed since the last translation, so the Chinese is stale
+            and should be redone.
+        msgid: The original English text.
+        msgstr: The current Chinese translation (empty string if not yet
+            translated).
+    """
+
+    def __init__(
+        self,
+        start: int,
+        end: int,
+        flags: set[str],
+        msgid: str,
+        msgstr: str,
+    ) -> None:
+        self.start = start
+        self.end = end
+        self.flags = flags
+        self.msgid = msgid
+        self.msgstr = msgstr
+
+
+def decode_po_string(value: str) -> str:
+    """Unwrap one quoted ``.po`` line into a plain Python string."""
+    return json.loads(value)
+
+
+def encode_po_string(value: str) -> list[str]:
+    """Convert a Python string into one or more quoted ``.po`` lines."""
+    if "\n" not in value:
+        return [json.dumps(value, ensure_ascii=False)]
+
+    lines = ['""']
+    parts = value.splitlines(keepends=True)
+    for part in parts:
+        lines.append(json.dumps(part, ensure_ascii=False))
+    return lines
+
+
+def collect_field(lines: list[str], index: int) -> tuple[str, int]:
+    """Read one ``msgid``/``msgstr`` value plus any continuation lines.
+
+    Returns:
+        The joined string value, and the next line number to read.
+    """
+    _, raw_value = lines[index].split(" ", 1)
+    values = [decode_po_string(raw_value.strip())]
+    index += 1
+
+    while index < len(lines) and lines[index].startswith('"'):
+        values.append(decode_po_string(lines[index].strip()))
+        index += 1
+
+    return "".join(values), index
+
+
+def parse_entries(lines: list[str]) -> list[PoEntry]:
+    """Parse a ``.po`` file into one :class:`PoEntry` per message."""
+    entries: list[PoEntry] = []
+    index = 0
+
+    while index < len(lines):
+        start = index
+        flags: set[str] = set()
+
+        while index < len(lines) and not lines[index].startswith("msgid "):
+            if lines[index].startswith("#,"):
+                flags.update(flag.strip() for flag in lines[index][2:].split(","))
+            index += 1
+
+        if index >= len(lines):
+            break
+
+        msgid, index = collect_field(lines, index)
+
+        while index < len(lines) and not lines[index].startswith("msgstr "):
+            index += 1
+
+        if index >= len(lines):
+            break
+
+        msgstr, index = collect_field(lines, index)
+
+        while index < len(lines) and lines[index].strip():
+            index += 1
+
+        entries.append(PoEntry(start, index, flags, msgid, msgstr))
+
+    return entries
+
+
+def replace_msgstr(lines: list[str], entry: PoEntry, translation: str) -> None:
+    """Replace one entry's ``msgstr`` in ``lines``, in place."""
+    msgstr_index = entry.start
+    while msgstr_index < entry.end and not lines[msgstr_index].startswith("msgstr "):
+        msgstr_index += 1
+
+    msgstr_end = msgstr_index + 1
+    while msgstr_end < len(lines) and lines[msgstr_end].startswith('"'):
+        msgstr_end += 1
+
+    encoded = encode_po_string(translation)
+    lines[msgstr_index:msgstr_end] = ["msgstr " + encoded[0], *encoded[1:]]
+
+
+def clean_fuzzy_flag(lines: list[str], entry: PoEntry) -> None:
+    """Remove the ``"fuzzy"`` marker from a message, modifying ``lines`` in place."""
+    for index in range(entry.start, entry.end):
+        if not lines[index].startswith("#,"):
+            continue
+        flags = [flag.strip() for flag in lines[index][2:].split(",")]
+        flags = [flag for flag in flags if flag != "fuzzy"]
+        if flags:
+            lines[index] = "#, " + ", ".join(flags)
+        else:
+            lines.pop(index)
+        return
+
+
+def should_translate(entry: PoEntry) -> bool:
+    """Return True if the entry has English content and is empty or fuzzy."""
+    return bool(entry.msgid.strip()) and (
+        not entry.msgstr.strip() or "fuzzy" in entry.flags
+    )
+
+
+def build_user_message(
+    target: PoEntry,
+    previous: PoEntry | None,
+    next_: PoEntry | None,
+    source_file: str | None = None,
+) -> str:
+    """Build the chat-completions user message for one translation call.
+
+    Wraps the focal entry in labeled blocks and prepends the neighboring
+    entries (when present) so the model can disambiguate identifiers from
+    prose and reuse established terminology.
+
+    Args:
+        target: The entry being translated.
+        previous: The entry immediately before ``target``, or None at the
+            start of the file or when the neighbor has an empty msgid (the
+            gettext metadata header).
+        next_: The entry immediately after ``target``, or None at the end.
+        source_file: Optional ``.rst`` path the entries came from (e.g.,
+            ``"api_reference/configurations.rst"``).
+
+    Returns:
+        A multi-line string suitable for the ``content`` field of a user
+        message.
+    """
+    parts: list[str] = []
+
+    if source_file:
+        parts.append(f"Source file: {source_file}")
+        parts.append("")
+
+    if previous is not None and previous.msgid.strip():
+        parts.append("Previous entry (context only, do not translate):")
+        parts.append(f"  msgid: {json.dumps(previous.msgid, ensure_ascii=False)}")
+        if previous.msgstr.strip():
+            parts.append(f"  msgstr: {json.dumps(previous.msgstr, ensure_ascii=False)}")
+        parts.append("")
+
+    parts.append("Translate this entry:")
+    parts.append(f"  msgid: {json.dumps(target.msgid, ensure_ascii=False)}")
+
+    if next_ is not None and next_.msgid.strip():
+        parts.append("")
+        parts.append("Next entry (context only, do not translate):")
+        parts.append(f"  msgid: {json.dumps(next_.msgid, ensure_ascii=False)}")
+        if next_.msgstr.strip():
+            parts.append(f"  msgstr: {json.dumps(next_.msgstr, ensure_ascii=False)}")
+
+    return "\n".join(parts)
+
+
+def clean_translation_response(text: str) -> str:
+    """Strip incidental formatting the model occasionally adds to the output.
+
+    Trims whitespace, removes a leading ``msgstr:`` / ``Translation:`` label
+    if present, and unwraps a single pair of surrounding double quotes.
+
+    Args:
+        text: Raw ``message.content`` string returned by the endpoint.
+
+    Returns:
+        The Chinese translation only, ready to be written into ``msgstr``.
+    """
+    cleaned = text.strip()
+
+    for prefix in ("msgstr:", "msgstr =", "translation:"):
+        if cleaned.lower().startswith(prefix):
+            cleaned = cleaned[len(prefix) :].lstrip()
+            break
+
+    if len(cleaned) >= 2 and cleaned[0] == '"' and cleaned[-1] == '"':
+        try:
+            cleaned = json.loads(cleaned)
+        except json.JSONDecodeError:
+            cleaned = cleaned[1:-1]
+
+    return cleaned
+
+
+def endpoint_url() -> str:
+    """Build the chat-completions URL from ``TRANSLATION_API_BASE_URL``."""
+    base_url = os.environ["TRANSLATION_API_BASE_URL"].rstrip("/")
+    if base_url.endswith("/chat/completions"):
+        return base_url
+    return base_url + "/chat/completions"
+
+
+def translate_text(user_message: str) -> str:
+    """Send a pre-built user message to the endpoint and return the cleaned translation.
+
+    Raises:
+        RuntimeError: If the response has no message content.
+    """
+    payload = {
+        "model": os.environ["TRANSLATION_MODEL"],
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_message},
+        ],
+        "temperature": 0.2,
+    }
+    body = json.dumps(payload).encode("utf-8")
+    http_request = request.Request(
+        endpoint_url(),
+        data=body,
+        headers={
+            "Authorization": "Bearer " + os.environ["TRANSLATION_API_KEY"],
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+
+    with request.urlopen(http_request, timeout=120) as response:
+        data = json.loads(response.read().decode("utf-8"))
+
+    try:
+        raw = data["choices"][0]["message"]["content"]
+    except (KeyError, IndexError) as exc:
+        raise RuntimeError("Translation endpoint returned no message content") from exc
+    return clean_translation_response(raw)
+
+
+def validate_environment() -> None:
+    """Exit with an error if any required API env var is unset.
+
+    Raises:
+        SystemExit: If ``TRANSLATION_API_BASE_URL``, ``TRANSLATION_API_KEY``,
+            or ``TRANSLATION_MODEL`` is missing.
+    """
+    missing = [
+        name
+        for name in (
+            "TRANSLATION_API_BASE_URL",
+            "TRANSLATION_API_KEY",
+            "TRANSLATION_MODEL",
+        )
+        if not os.environ.get(name)
+    ]
+    if missing:
+        joined = ", ".join(missing)
+        raise SystemExit(f"Missing required translation secret(s): {joined}")
+
+
+def update_file(path: Path, remaining_budget: int) -> int:
+    """Translate up to ``remaining_budget`` empty/fuzzy messages in one ``.po`` file.
+
+    For each entry needing translation, sends the focal msgid along with its
+    immediate neighbors as contextual hints to the model.
+
+    Returns:
+        Number of messages actually translated.
+    """
+    lines = path.read_text(encoding="utf-8").splitlines()
+    entries = parse_entries(lines)
+    translated = 0
+
+    try:
+        source_file = str(path.relative_to(LOCALE_DIR).with_suffix(".rst"))
+    except ValueError:
+        source_file = None
+
+    for i in reversed(range(len(entries))):
+        if translated >= remaining_budget:
+            break
+        entry = entries[i]
+        if not should_translate(entry):
+            continue
+
+        previous = entries[i - 1] if i > 0 else None
+        next_ = entries[i + 1] if i + 1 < len(entries) else None
+
+        user_message = build_user_message(entry, previous, next_, source_file)
+        translation = translate_text(user_message)
+
+        replace_msgstr(lines, entry, translation)
+        if "fuzzy" in entry.flags:
+            clean_fuzzy_flag(lines, entry)
+        translated += 1
+
+    if translated:
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    return translated
+
+
+def main() -> int:
+    """Translate up to ``MAX_ENTRIES`` messages across all Chinese ``.po`` files."""
+    po_files = sorted(LOCALE_DIR.glob("**/*.po"))
+    if not po_files:
+        print("No Chinese PO files found.")
+        return 0
+
+    needs_translation = False
+    for path in po_files:
+        entries = parse_entries(path.read_text(encoding="utf-8").splitlines())
+        if any(should_translate(entry) for entry in entries):
+            needs_translation = True
+            break
+
+    if not needs_translation:
+        print("No missing or fuzzy Chinese translations found.")
+        return 0
+
+    validate_environment()
+
+    translated = 0
+    for path in po_files:
+        if translated >= MAX_ENTRIES:
+            break
+        translated += update_file(path, MAX_ENTRIES - translated)
+
+    print(f"Translated {translated} Chinese documentation entries.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())